defineContentProjection

KIT · function · 运行时值

Compile a JSON-preserving projector.

Keep valid JSON while reducing prose before dropping records; budgets are caller policy. The candidate list is tried in order (outer counts, inner lengths), so callers control whether trimming text or dropping items is preferred, and the configured fallback is used only when no candidate fits.

导入

TypeScript

import { defineContentProjection } from '@jangts/agent-core/kits/projection';

JavaScript

import { defineContentProjection } from '@jangts/agent-core/kits/projection';

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

定义

调用

defineContentProjection(options: ContentProjectionOptions): Readonly<{ project: ({ value, maxChars: limit, }: { value: unknown; maxChars: number; }) => ContentProjection; }>

Compile a JSON-preserving projector.

Keep valid JSON while reducing prose before dropping records; budgets are caller policy. The candidate list is tried in order (outer counts, inner lengths), so callers control whether trimming text or dropping items is preferred, and the configured fallback is used only when no candidate fits.

参数	类型	传递	说明
options	ContentProjectionOptions	必需	—

options 的字段

字段	类型	必需	说明
counts	readonly number[]	必需	只读。Maximum array items to keep, tried in order before moving to the next length.
lengths	readonly number[]	必需	只读。Maximum characters per string, tried in order inside each count candidate.
render	(excerpt: unknown) => string	必需	只读。Renders a shortened value; must be synchronous.
fallback	(limit: number) => string	必需	只读。Builds fallback text for a limit, used when no candidate fits; must be synchronous.

返回： Readonly<{ project: ({ value, maxChars: limit, }: { value: unknown; maxChars: number; }) => ContentProjection; }>。

返回值结构

字段	类型	必需	说明
project	({ value, maxChars: limit, }: { value: unknown; maxChars: number; }) => ContentProjection	必需	见类型定义及调用场景。

使用示例

• Projection：按预算投影内容：先缩短文本，再减少条目；源数据、投影结果和预算由 App 显式区分。

为同一份查询结果准备紧凑 JSON

入门 · Node.js

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const projection = Projection.defineContentProjection({
  counts: [10, 3, 1], lengths: [200, 80, 20],
  render: value => JSON.stringify(value), fallback: () => '{}',
});
const result = projection.project({ value: { items: [{ title: '配置说明', body: '正文'.repeat(100) }] }, maxChars: 120 });
console.log(result.text, result.truncated);

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const projection = Projection.defineContentProjection({
    counts: [10, 3, 1], lengths: [200, 80, 20],
    render: value => JSON.stringify(value), fallback: () => '{}',
});
const result = projection.project({ value: { items: [{ title: '配置说明', body: '正文'.repeat(100) }] }, maxChars: 120 });
console.log(result.text, result.truncated);

相同数据先移除私有字段，再按预算投影

配置 · Node.js

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const tree = Projection.defineTreeProjection({
  maxDepth: 4,
  visitRecord(record) { delete record.privateNote; },
});
const source = { items: [{ title: '配置说明', body: '正文'.repeat(100), privateNote: '不向模型提供' }] };
// 调用者明确选择副本所有权；visitor 不会碰原记录。
const publicData = tree.visit(structuredClone(source), undefined);
const compact = Projection.defineContentProjection({ counts: [10, 3, 1], lengths: [200, 80, 20], render: JSON.stringify, fallback: () => '{}' });
console.log(compact.project({ value: publicData, maxChars: 120 }));

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const tree = Projection.defineTreeProjection({
    maxDepth: 4,
    visitRecord(record) { delete record.privateNote; },
});
const source = { items: [{ title: '配置说明', body: '正文'.repeat(100), privateNote: '不向模型提供' }] };
// 调用者明确选择副本所有权；visitor 不会碰原记录。
const publicData = tree.visit(structuredClone(source), undefined);
const compact = Projection.defineContentProjection({ counts: [10, 3, 1], lengths: [200, 80, 20], render: JSON.stringify, fallback: () => '{}' });
console.log(compact.project({ value: publicData, maxChars: 120 }));

保留连续正文而非拆散段落

扩展 · Node.js

render 的输出长度须随前缀长度单调增长，二分搜索才有意义。

TypeScript

import { Projection } from '@jangts/agent-core/kits/projection';
const body = '一段连续的资料正文。'.repeat(100);
const excerpt = Projection.projectContinuousExcerpt(body, 120, length => JSON.stringify({ excerpt: body.slice(0, length) }));
if (excerpt) console.log(JSON.parse(excerpt.text));

JavaScript

import { Projection } from '@jangts/agent-core/kits/projection';
const body = '一段连续的资料正文。'.repeat(100);
const excerpt = Projection.projectContinuousExcerpt(body, 120, length => JSON.stringify({ excerpt: body.slice(0, length) }));
if (excerpt)
    console.log(JSON.parse(excerpt.text));

相关策略源码

• 缩减顺序与树遍历

相关定义

• ContentProjectionOptions