ContextProjection

SUPPORT · type · 类型合同

One declared projection: a single fragment or a placement expanded into fragments.

导入

TypeScript

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

JavaScript

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

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

定义

类型： ContextProjection<Input, Id, Placement>

类型表达式

type ContextProjection<Input, Id extends string = string, Placement extends string = string> = | {
      readonly kind: 'fragment';
      /** Fragment id; must be unique across all projections. */
      readonly id: Id;
      /** Produces the fragment value; must be synchronous. */
      readonly format: (input: Input) => ContextFragment['value'];
    }
  /** Expands to the fragments supplied for this placement; ids use a separate prefix. */
  | { readonly kind: 'contributions'; readonly placement: Placement };

泛型参数

类型参数	约束	默认类型
Input	—	—
Id	string	string
Placement	string	string

联合分支结构

ContextProjection的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

字段	类型	必需	说明
kind	"fragment"	必需	只读。见类型定义及调用场景。
id	Id	必需	只读。Fragment id; must be unique across all projections.
format	(input: Input) => ContextFragment["value"]	必需	只读。Produces the fragment value; must be synchronous.

分支 2

字段	类型	必需	说明
kind	"contributions"	必需	只读。见类型定义及调用场景。
placement	Placement	必需	只读。见类型定义及调用场景。

使用示例

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

相关策略源码

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

相关定义

• ContextFragment