ContextBuilder

SUPPORT · interface · 类型合同

Compiled builder. It holds no request state and may be shared across invocations.

导入

TypeScript

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

JavaScript

/** @typedef {import('@jangts/agent-core/support').ContextBuilder} ContextBuilder */

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

定义

interface ContextBuilder<Input>

泛型参数

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

字段结构

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

成员目录

成员	用途
fragments	Produces the fragments for one input, after transforms.
build	Assembles and validates the plan into messages with usage accounting.
plan	Produces the unassembled plan without running the budget boundary.

成员详情

fragments

Produces the fragments for one input, after transforms.

ContextBuilder.fragments(input: Input): ContextFragment[]

Produces the fragments for one input, after transforms.

参数	类型	传递	说明
input	Input	必需	—

返回： ContextFragment[]。

build

Assembles and validates the plan into messages with usage accounting.

ContextBuilder.build(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "fragments" | "maxInputChars">): BuiltContext

Assembles and validates the plan into messages with usage accounting.

参数	类型	传递	说明
request	{ input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">	必需	—

request 的字段

字段	类型	必需	说明
input	Input	必需	见类型定义及调用场景。
maxInputChars	number | undefined	可省略	见类型定义及调用场景。
additionalMessages	readonly (ModelMessage & { role: "user"; })[] | undefined	可省略	Protected user messages (for example image inputs); text counts toward the same budget.
originalFragments	readonly ContextFragment[] | undefined	可省略	Trusted originals for structural mutation auditing; never sent to the model.
mutableFragmentIds	readonly string[] | undefined	可省略	Explicit value-mutation allowance when originals are supplied.

返回： BuiltContext。

返回值结构

字段	类型	必需	说明
messages	ModelMessage[]	必需	Messages in final model order.
fragmentUsage	ContextFragmentUsage[]	必需	Per-fragment accounting in the same order as the fragments were merged.
inputChars	number	必需	Total counted characters across messages and usage.
maxInputChars	number	必需	Budget the assembly was validated against; Infinity means unbounded.

plan

Produces the unassembled plan without running the budget boundary.

ContextBuilder.plan(request: { input: Input; maxInputChars?: number; } & Omit<ContextPlan, "fragments" | "maxInputChars">): ContextPlan

Produces the unassembled plan without running the budget boundary.

参数	类型	传递	说明
request	{ input: Input; maxInputChars?: number; } & Omit<ContextPlan, "maxInputChars" | "fragments">	必需	—

request 的字段

字段	类型	必需	说明
input	Input	必需	见类型定义及调用场景。
maxInputChars	number | undefined	可省略	见类型定义及调用场景。
additionalMessages	readonly (ModelMessage & { role: "user"; })[] | undefined	可省略	Protected user messages (for example image inputs); text counts toward the same budget.
originalFragments	readonly ContextFragment[] | undefined	可省略	Trusted originals for structural mutation auditing; never sent to the model.
mutableFragmentIds	readonly string[] | undefined	可省略	Explicit value-mutation allowance when originals are supplied.

返回： ContextPlan。

返回值结构

字段	类型	必需	说明
fragments	readonly ContextFragment[]	必需	只读。Fragments in the order supplied by the App; assembly preserves it.
maxInputChars	number	必需	Character budget Core validates after assembly.
additionalMessages	readonly (ModelMessage & { role: "user"; })[] | undefined	可省略	Protected user messages (for example image inputs); text counts toward the same budget.
originalFragments	readonly ContextFragment[] | undefined	可省略	Trusted originals for structural mutation auditing; never sent to the model.
mutableFragmentIds	readonly string[] | undefined	可省略	Explicit value-mutation allowance when originals are supplied.

使用示例

• 上下文装配：稳定元数据配置一次：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);

相关策略源码

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

相关定义

• BuiltContext
• ContextFragment
• ContextPlan