TextBlock
KIT · interface · 类型合同
One structure-aware block of a long text.
导入
ts
import type { TextBlock } from '@jangts/agent-core/kits/text-blocks';js
/** @typedef {import('@jangts/agent-core/kits/text-blocks').TextBlock} TextBlock */其他公开入口：@jangts/agent-core/types、@jangts/agent-core/kits、@jangts/agent-core/kits/text-blocks。
定义
ts
interface TextBlock字段结构
| 字段 | 类型 | 必需 | 说明 |
|---|---|---|---|
number | number | 必需 | 只读。One-based position in source order; stable for a given text and target size. |
text | string | 必需 | 只读。Exact source substring, including its own line endings. |
start | number | 必需 | 只读。Start offset in UTF-16 code units. |
end | number | 必需 | 只读。End offset (exclusive) in UTF-16 code units; end - start === text.length. |
使用示例
- TextBlocks：长文本结构分片：把长文本切成有界结构块，为分页读取或索引保留原文与偏移。
先切一份带章节的说明
入门 · Node.js
示例只演示分片合同；分页窗口、上下文预算和提示词仍由 App 决定。
ts
import { TextBlocks } from '@jangts/agent-core/kits/text-blocks';
const text = '# 概览\n\n' + '说明内容\n'.repeat(4) + '\n## 细节\n\n' + '更多内容\n'.repeat(4);
const blocks = TextBlocks.split(text, { targetChars: 40 });
console.log(blocks.map(block => [block.number, block.start, block.end]));
console.log(blocks.map(block => block.text).join('') === text);js
import { TextBlocks } from '@jangts/agent-core/kits/text-blocks';
const text = '# 概览\n\n' + '说明内容\n'.repeat(4) + '\n## 细节\n\n' + '更多内容\n'.repeat(4);
const blocks = TextBlocks.split(text, { targetChars: 40 });
console.log(blocks.map(block => [block.number, block.start, block.end]));
console.log(blocks.map(block => block.text).join('') === text);按块分页并记录覆盖范围
配置 · Node.js
块边界不等于固定字符窗口；报告已读范围时应记录块的 start/end，而不是推算字符位置。
ts
import { TextBlocks, type TextBlock } from '@jangts/agent-core/kits/text-blocks';
const text = '# 报告\n\n' + '记录内容\n'.repeat(200);
const blocks = TextBlocks.split(text, { targetChars: 4000 });
const page = (offset: number, limit: number): { blocks: TextBlock[]; nextOffset?: number } => ({
blocks: blocks.slice(offset, offset + limit),
nextOffset: offset + limit < blocks.length ? offset + limit : undefined,
});
const first = page(0, 2);
console.log(first.blocks.map(block => block.number), first.nextOffset);js
import { TextBlocks } from '@jangts/agent-core/kits/text-blocks';
const text = '# 报告\n\n' + '记录内容\n'.repeat(200);
const blocks = TextBlocks.split(text, { targetChars: 4000 });
const page = (offset, limit) => ({
blocks: blocks.slice(offset, offset + limit),
nextOffset: offset + limit < blocks.length ? offset + limit : undefined,
});
const first = page(0, 2);
console.log(first.blocks.map(block => block.number), first.nextOffset);