TextBlocks：长文本结构分片

把长文本切成有界结构块，为分页读取或索引保留原文与偏移。

split(text, { targetChars }) 只处理已解码的纯文本。标题与分隔线起新块，空行结束当前块，其余在换行处按 targetChars 断开；单行超过目标长度时保留为一个块，由后续分页切片，避免同一行被拆成互不相关的两段。所有块按顺序拼回与原文逐字一致，保留空白与 CRLF；number 从 1 开始，start/end 是原文 UTF-16 偏移。

targetChars 必须为正整数，空文本返回空数组。Kit 不读写文件、不分页、不访问模型或存储；分页窗口、检索、摘要与提示词由 App 决定。块边界跟随结构而不是固定字符窗口，需要报告覆盖范围时使用 start/end。

由简到繁的同业务示例

先切一份带章节的说明

入门 · Node.js

示例只演示分片合同；分页窗口、上下文预算和提示词仍由 App 决定。

TypeScript

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);

JavaScript

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，而不是推算字符位置。

TypeScript

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);

JavaScript

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);

策略与实现

• 结构边界、精确拼回与原文偏移