* 工具输出边界
*
* 工具结果是唯一会把任意大小的外部数据灌进模型上下文的通道,因此必须有一个
* 明确的收敛点。这个模块是那个唯一的收敛点,它只回答两个问题:
*
* 1. 预算是多少 —— 由用户的 maxToolResultChars 单一决定(clampOutputBudget)。
* 2. 超预算时怎么收敛 —— 取决于输出形态:
* - text: 保留信号所在的一端,中间插入省略说明(boundTextOutput)。
* - json: 走降级阶梯,逐级换更省的载荷,每一级都仍是合法 JSON(boundJsonOutput)。
*
* 为什么 json 不能走 text 那条路:结构化结果被「留头 + 留尾」切开之后不再可解析,
* 模型拿到的是一段语法残骸,UI 侧的 JSON.parse 也会静默失败退成空列表。对结构化
* 数据来说,正确的省法是丢弃字段和层级(body → 位置 → 计数),而不是丢弃字符。
*/
export type ToolOutputFormat = 'text' | 'json'
* 文本结果的信号所在端。超预算时优先保留这一端。
*
* - head: 绝大多数工具。文件内容、搜索命中、目录列表的价值都集中在前面。
* - tail: 命令输出。报错、栈、退出码都在最后。
*/
export type ToolOutputSignal = 'head' | 'tail'
const MIN_OUTPUT_BUDGET = 1000
* 头尾保留比例。两端之和小于 1,余量留给省略说明本身。
*
* 这里只有两组常量,而不是按工具名查表:一张按名字索引的比例表会随着工具增删而
* 长出查不到的死键,而「信号在哪一端」本就是工具的固有属性,应该由工具自己声明。
*/
const SIGNAL_RATIOS: Record<ToolOutputSignal, { head: number; tail: number }> = {
head: { head: 0.85, tail: 0.1 },
tail: { head: 0.2, tail: 0.75 },
}
export function clampOutputBudget(configured: number | undefined): number {
if (!Number.isFinite(configured) || (configured as number) <= 0) return MIN_OUTPUT_BUDGET
return Math.max(MIN_OUTPUT_BUDGET, Math.floor(configured as number))
}
* JS 字符串按 UTF-16 code unit 索引,非 BMP 字符(emoji、CJK 扩展区如 U+20000)
* 占两个 unit。裸 slice 切在两个 unit 中间会留下一个孤立代理,渲染成 U+FFFD 并
* 原样进到发给模型的 tool 消息里 —— 表现就是「工具结果里出现一坨乱码」。
*
* 下面这组函数只做一件事:把边界从代理对中间挪开一格。宁可少一个字符,
* 也不要吐出半个字符。
*/
function splitsSurrogatePair(text: string, index: number): boolean {
if (index <= 0 || index >= text.length) return false
const prev = text.charCodeAt(index - 1)
const curr = text.charCodeAt(index)
return prev >= 0xd800 && prev <= 0xdbff && curr >= 0xdc00 && curr <= 0xdfff
}
function sliceHead(text: string, end: number): string {
if (end >= text.length) return text
const safeEnd = splitsSurrogatePair(text, end) ? end - 1 : end
return text.slice(0, Math.max(0, safeEnd))
}
function sliceTailFrom(text: string, start: number): string {
if (start <= 0) return text
const safeStart = splitsSurrogatePair(text, start) ? start + 1 : start
return text.slice(Math.min(safeStart, text.length))
}
function truncateAtLineEnd(text: string, maxLen: number): string {
if (text.length <= maxLen) return text
const searchStart = Math.max(0, maxLen - 100)
const lastNewline = text.lastIndexOf('\n', maxLen)
if (lastNewline > searchStart) return text.slice(0, lastNewline)
return sliceHead(text, maxLen)
}
function truncateAtLineStart(text: string, maxLen: number): string {
if (text.length <= maxLen) return text
const startPos = text.length - maxLen
const searchEnd = Math.min(text.length, startPos + 100)
const firstNewline = text.indexOf('\n', startPos)
if (firstNewline !== -1 && firstNewline < searchEnd) return text.slice(firstNewline + 1)
return sliceTailFrom(text, startPos)
}
* 把文本结果收敛到预算内,保留 signal 指定的一端。
*
* 注意这里不做任何内容嗅探。之前的实现会正则匹配 /error|exception|failed/ 并据此
* 翻转头尾比例,结果是「一个恰好提到 error 的源文件」会被从开头砍掉 —— 用内容猜
* 意图不如让工具直接声明。
*/
export function boundTextOutput(
text: string,
budget: number,
signal: ToolOutputSignal = 'head',
): string {
if (!text) return ''
const limit = clampOutputBudget(budget)
if (text.length <= limit) return text
const ratios = SIGNAL_RATIOS[signal]
const headSize = Math.floor(limit * ratios.head)
const tailSize = Math.floor(limit * ratios.tail)
const omitted = text.length - headSize - tailSize
const head = truncateAtLineEnd(sliceHead(text, headSize + 200), headSize)
const tail = truncateAtLineStart(sliceTailFrom(text, text.length - tailSize - 200), tailSize)
return `${head}\n\n... [truncated: ${omitted.toLocaleString()} chars omitted] ...\n\n${tail}`
}
* 把文件摘录收敛到预算内,超出时只保留开头并附上调用方给的后续指引。
*
* 与 boundTextOutput 的区别在于这里不留尾部:文件的行号是连续的,「前 200 行 +
* 后 50 行」会让模型误以为中间的行号可以直接用于编辑。只给开头、并明确告诉它
* 用行范围取剩下的部分,才是可行动的。
*
* footer 的长度从预算里预留,所以指引本身不会因为超预算而被后续边界层切掉 ——
* 那正是它最需要出现的时候。
*/
export function boundFileExcerpt(
content: string,
budget: number,
buildFooter: (retainedChars: number) => string,
): string {
const limit = clampOutputBudget(budget)
if (content.length <= limit) return content
const footerAllowance = buildFooter(limit).length + 2
const retained = Math.max(0, limit - footerAllowance)
const head = truncateAtLineEnd(sliceHead(content, retained + 200), retained)
return `${head}\n\n${buildFooter(head.length)}`
}
export interface JsonOutputStage {
build: () => unknown
* 本级相比完整结果丢了什么、以及如何补回来。
*
* hint 的有无就是「这一级是否完整」的唯一判据:有 hint 就贴上 truncated 标记,
* 没有就原样返回。这样第一级也能声明 hint —— 它常常本来就不完整(比如 max_matches
* 已经截过一刀),把「第几级」和「是否完整」绑在一起会让那种情况漏报。
*
* 阶梯的意义不只是变小,而是「变小之后仍然可以继续查」。丢掉 body 就要告诉模型
* 用 include_body 单独取,只剩计数就要告诉模型如何缩小范围重查。没有这句提示的
* 降级等于让模型面对一个残缺结果自己猜下一步。
*/
hint?: string
}
function buildExhaustedEnvelope(budget: number): string {
return JSON.stringify({
truncated: true,
truncationNotice: `The result does not fit in the ${budget} character budget even at the coarsest level. Narrow the query scope and retry.`,
})
}
* 逐级尝试,返回第一个塞得进预算的载荷序列化结果。
*
* 返回值保证是合法 JSON —— 这是整个模块存在的理由。不做 pretty-print:缩进对模型
* 没有价值,只是按 token 计费的空白。
*/
export function boundJsonOutput(stages: JsonOutputStage[], budget: number): string {
const limit = clampOutputBudget(budget)
for (const stage of stages) {
const payload = stage.build()
const serialized = stage.hint
? JSON.stringify(withTruncationNotice(payload, stage.hint))
: JSON.stringify(payload)
if (serialized.length <= limit) return serialized
}
return buildExhaustedEnvelope(limit)
}
function withTruncationNotice(payload: unknown, hint: string | undefined): unknown {
if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
return { truncated: true, ...(hint ? { truncationNotice: hint } : {}), result: payload }
}
return {
...(payload as Record<string, unknown>),
truncated: true,
...(hint ? { truncationNotice: hint } : {}),
}
}
* 边界兜底:一个声明为 json 的结果超出了预算。
*
* 正常情况下执行器的阶梯已经把结果压进预算,走到这里说明有未预期的巨大载荷
* (例如 MCP 工具,或某一级里嵌了超大字符串)。此时整体替换成一个合法信封,
* 而绝不头尾拼接 —— 拼接产生的是不可解析的残骸。
*/
export function replaceOversizedJsonOutput(byteLength: number, budget: number): string {
return JSON.stringify({
truncated: true,
truncationNotice: `The structured result was ${byteLength} characters, over the ${budget} character budget, and was dropped rather than cut mid-structure. Narrow the query scope and retry.`,
})
}