defineContextFragments

SUPPORT · function · 运行时值

Compile self-describing fragment declarations into a builder.

Each definition carries its own trust, lifetime and size metadata, so no separate metadata catalog is needed. The budget may be a constant or a function of the request input.

导入

TypeScript

import { defineContextFragments } from '@jangts/agent-core/support';

JavaScript

import { defineContextFragments } from '@jangts/agent-core/support';

其他公开入口：@jangts/agent-core、@jangts/agent-core/types、@jangts/agent-core/support、@jangts/agent-core/support/context。

定义

泛型参数

类型参数	约束	默认类型
Input	—	—

调用

defineContextFragments<Input>(definitions: readonly ContextFragmentConfig<Input>[], options?: ContextBuilderOptions<Input>): ContextBuilder<Input>

Compile self-describing fragment declarations into a builder.

Each definition carries its own trust, lifetime and size metadata, so no separate metadata catalog is needed. The budget may be a constant or a function of the request input.

类型参数	约束	默认类型
Input	—	—

参数	类型	传递	说明
definitions	readonly ContextFragmentConfig<Input>[]	必需	—
options	ContextBuilderOptions<Input>	可省略	—

options 的字段

字段	类型	必需	说明
maxInputChars	number | ((input: Input) => number) | undefined	可省略	只读。Character budget, constant or derived from the request; at least one of these is required.
transform	((fragment: ContextFragment, input: Input) => ContextFragment) | undefined	可省略	只读。Applied to every produced fragment before assembly; must be synchronous.

返回： ContextBuilder<Input>。

返回值结构

字段	类型	必需	说明
fragments	(input: Input) => ContextFragment[]	必需	Produces the fragments for one input, after transforms.
build	(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">) => BuiltContext	必需	Assembles and validates the plan into messages with usage accounting.
plan	(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">) => ContextPlan	必需	Produces the unassembled plan without running the budget boundary.

使用示例

• 上下文装配：稳定元数据配置一次：Support 提前绑定片段元数据、格式化和顺序，请求只提供变化的业务输入。

一次配置，以后只给问题和历史

入门 · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
type Input = { question: string; history: readonly { role: string; content: string }[] };
const builder = Support.defineContextFragments<Input>([
  { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
    role: 'user', format: input => input.question },
  { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
    role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const context = builder.build({ input: { question: '服务状态？', history: [] } });
console.log(context.messages);

JavaScript

import { Support } from '@jangts/agent-core';
const builder = Support.defineContextFragments([
    { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
        role: 'user', format: input => input.question },
    { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
        role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const context = builder.build({ input: { question: '服务状态？', history: [] } });
console.log(context.messages);

同一个 builder 提前给出计划

配置 · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
type Input = { question: string; history: readonly { role: string; content: string }[] };
const builder = Support.defineContextFragments<Input>([
  { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
    role: 'user', format: input => input.question },
  { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
    role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const input = { question: '服务状态？', history: [] };
const plan = builder.plan({ input });
const expanded = builder.fragments(input);
console.log(plan.maxInputChars, expanded.map(fragment => fragment.id));
const largerRequest = builder.build({ input, maxInputChars: 2000 });
console.log(largerRequest.maxInputChars);

JavaScript

import { Support } from '@jangts/agent-core';
const builder = Support.defineContextFragments([
    { id: 'question', sourceId: 'request', trust: 'user', lifetime: 'turn', maxChars: 1000,
        role: 'user', format: input => input.question },
    { id: 'history', sourceId: 'conversation', trust: 'user', lifetime: 'turn', maxChars: 10000,
        role: 'user', format: input => ({ messages: input.history }) },
], { maxInputChars: 1200 });
const input = { question: '服务状态？', history: [] };
const plan = builder.plan({ input });
const expanded = builder.fragments(input);
console.log(plan.maxInputChars, expanded.map(fragment => fragment.id));
const largerRequest = builder.build({ input, maxInputChars: 2000 });
console.log(largerRequest.maxInputChars);

复用元数据目录与请求贡献插槽

扩展 · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
import type { ContextFragment } from '@jangts/agent-core/types';
type Input = { question: string; evidence: string };
const builder = Support.defineContextAssembly<Input, 'question', 'evidence'>([
  { kind: 'fragment', id: 'question', format: input => input.question },
  { kind: 'contributions', placement: 'evidence' },
], {
  maxInputChars: 2000,
  fragment(id, value): ContextFragment { return { id, sourceId: 'request', trust: 'user', lifetime: 'turn', role: 'user', maxChars: 1000, value }; },
  contributions: { evidence(input) { return [{ id: 'evidence', sourceId: 'service', trust: 'server', lifetime: 'turn', role: 'user', maxChars: 1000, value: input.evidence }]; } },
});
console.log(builder.build({ input: { question: '状态？', evidence: '最近检查：正常' } }).messages);

JavaScript

import { Support } from '@jangts/agent-core';
const builder = Support.defineContextAssembly([
    { kind: 'fragment', id: 'question', format: input => input.question },
    { kind: 'contributions', placement: 'evidence' },
], {
    maxInputChars: 2000,
    fragment(id, value) { return { id, sourceId: 'request', trust: 'user', lifetime: 'turn', role: 'user', maxChars: 1000, value }; },
    contributions: { evidence(input) { return [{ id: 'evidence', sourceId: 'service', trust: 'server', lifetime: 'turn', role: 'user', maxChars: 1000, value: input.evidence }]; } },
});
console.log(builder.build({ input: { question: '状态？', evidence: '最近检查：正常' } }).messages);

相关策略源码

• 装配顺序、依赖快照与请求预算覆盖

相关定义

• ContextBuilder
• ContextBuilderOptions
• ContextFragmentConfig