docs(tokenless): consolidate compression triggers, saving-rate fields, and reference workload

[Forrest-ly]

改动说明

按审查意见，本 PR 作为三份 tokenless 文档需求的统一交付入口：承接 #2596（节省率字段定义）与 #2601（压缩率适用场景与标准测试负载）的有效意图（两者已关闭并指向这里），并与本 PR 原有的「压缩触发条件与阈值」整合。所有行为说明均在下方基线上按当前源码逐项重新核对，不是旧分支文本的直接搬运。

基线与提交形态：分支已重写为相对最新 main（cc988a6b1，Tokenless 0.8.2）的单个提交（git rev-list --count cc988a6b1..HEAD = 1），旧的分支合并历史已去除；diff 仅含 8 个 tokenless 文档文件（+199/−14），中英文镜像。

1. user-manual.md —「压缩触发条件与阈值」（本 PR 原有内容，按本轮意见修正）

• 5 项触发条件清单；第 4 条按路径分别描述：
  • 4a 共享响应 Hook：纯文本交给内容感知文本压缩（构建/测试日志终端清理与进度缩减、CSV/TSV 表格压紧、API 搜索路径共享）；Shell 工具信封的主文本字段（stdout/stderr，至少 2,000 字符）先拆出送入文本槽位，压缩后回填同形状信封；
  • 4b OpenClaw：只有纯字符串和单文本块工具结果走可替换文本路径；其余对象/数组（包括 {"stdout": ...} Shell 信封）整体作为结构化 JSON 传给 Core 且禁用文本替换（信封保持顶层结构，只适用 JSON 域压缩）——修正此前「OpenClaw 与 Hermes 都会拆出主文本字段」的错误合并描述；
  • 4c Hermes：Shell 工具拆出信封 output 字段送入 Core（允许替换），压缩后回填同一信封；其他工具结果直接传递。
• 数组语义修正（按 tokenless-compressors/src/json.rs 与 CLI 参考）：数组仅在长度超过「类别阈值 + 尾部窗口」时截断——头部窗口保留至阈值个元素、尾部窗口默认 8 项内联保留、丢弃的中间段启用 Stash 时可取回、两窗口间插入截断标记；至少 33 个 JSON Object 的对象数组不受表中 128 / 65,536 阈值控制，改走 Record Reduction（32 条基础预算：前 4 + 后 4 + 错误/异常信号记录 + 数值异常记录 + 其余稳定采样；完整原始数组写入 Stash；无 Stash 时保留全部记录）。表列名相应改为「数组截断阈值」。
• 路径差异更新：CLI 独立默认值（4,096 字符 / 头窗口 32 + 尾窗口 8 / 深度 8，补充 --array-tail-preserve）；Codex 与 Qwen Code 在当前 PostToolUse 契约下不运行响应压缩与 TOON；OpenClaw 读取 tool_categories.json 映射内容来源（skip_tools/shell_tools 已删除）；TOON 独立触发（≥500 字符、槽位接受文本、严格变小才采用）；删除过时的 AgentScope 模式阈值说法——SDK/AgentScope 层的压缩阈值、内容检测与 TOON 选择均为 Core 行为，TokenlessRuntime.compress_response 可按次覆盖截断参数。

2. measuring-savings.md — 迁移内容（中英同步）

• 节省率字段定义（承接 docs(tokenless): clarify savings-rate field definitions #2596）：公式表覆盖 chars_saved_percent / tokens_saved_percent / saved_percent（compare 与 diff 两种 Schema）；公式边界已修正——summary 与 compare 的节省量经 saturating_sub 钳制为 0，diff 保留负值；分母为 0 时一律返回 0%；含 before=100 / after=150 → compare 0%、diff −50% 的示例；保留 prompt-cache 命中指标（savings_rate/cached_tokens）与 Tokenless 节省的区分说明。
• 压缩率的适用场景（承接 docs(tokenless): document compression-rate scenarios and standard test load #2601）：场景分层（收益高/中等/接近零/不参与压缩）；未引入任何过时行为说明（无 Codex 500/4,000 字符路径；非 JSON 不再一概写成不压缩——构建日志、CSV/TSV、搜索路径共享各有压缩器）。
• 标准测试负载与 main 已有「运行仓库参考负载」章节合并去重：不另立新章节，只补充 gen_fixtures.py 确定性生成、run-benchmarks.sh --quick 入口和「数字必须注明测量 commit」的提示；参考快照已在基线上复测更新（0.7.11 的 response 65.8% 已失效）：canonical response 36.3% / schema 47.3% / TOON-only 17.0% 与 −2.3%，并新增叠加配置表（response_only 34.0%、schema_only 3.0%、schema_response 37.0%、response_toon 47.4%、toon_only 15.8%、full_stack 50.3%），注明叠加行以 5,551 估算 Token 的合并基线为分母、TOON 行为不做门控的度量且部署结果可能略有差异。

3. cli-reference.md / framework-integration.md

• 补充交叉引用：触发条件小节、节省率字段定义（含 summary/compare 钳制与 diff 保留负值的一句话说明）。
• framework-integration 共享 Hook 路由表修正：原「构建/测试/包管理日志、搜索结果、表格……对应领域 Compressor 接入前原样透传」一行已过时（build-log 与 CSV/TSV 压缩器均已在 main 落地），拆分为构建日志、CSV/TSV 表格、API 搜索结果三行准确描述 + 其余类型仍透传，消除与 user-manual 4a 交叉引用的矛盾。

测试情况（真实执行，已脱敏）

环境概要：Linux x86_64；cargo/rustc 1.96.0；Node v22.21.1 / npm 10.9.4；Python 3.8.17；pandoc 2.0.6。

#	验证项	命令	结果
1	文档门禁（命名规范 + en/zh 目录镜像）	bash scripts/docs-lint.sh	✅ 通过
2	相对链接检查	python3 scripts/docs-link-check.py	✅ All relative links resolve
3	站点构建（含锚点/链接检查）	npm ci --prefix website、npm run validate:locales --prefix website、npm run build --prefix website	✅ en、zh 双语言构建成功，无断链/断锚点
4	参考数字复测	在 src/tokenless/benchmark/l1-compressor 执行 cargo build --release --bin compression_rate 与 ./target/release/compression_rate --json	✅ 文档引用的全部数字与输出逐项一致（canonical 36.3 / 47.3 / 17.0 / −2.3；stacking 34.0 / 3.0 / 37.0 / 47.4 / 15.8 / 50.3；baseline 5,551）
5	完整质量/对抗测试 + 报告（即文档中记载的命令）	./run-benchmarks.sh --quick	✅ exit 0；cargo test 97 passed / 0 failed / 0 ignored；报告数字与第 4 项一致
6	提交形态	git rev-list --count cc988a6b1..HEAD	✅ = 1；diff 仅 8 个预期文档文件
7	行为说明与源码逐项核对	见下方清单	✅ 一致

第 7 项核对清单（均在基线 cc988a6b1）：tokenless-compressors/src/json.rs（头/尾窗口截断、33 项起 Record Reduction、Stash 依赖、CLI 默认 4096-32-8）；tokenless-runtime/src/entry.rs（200 字符响应门禁、500 字符 TOON 门禁）与 post_tool/pipeline.rs（JSON/构建日志/CSV-TSV/搜索路径共享的域路由、Grep 例外、FileContent 跳过）、post_tool/arbitration.rs（严格变小保护）；taxonomy.rs + tool_categories.json（类别阈值与内置回退）；tokenless-stats 的 query.rs（compare saturating_sub、零分母 0%）、diff.rs（负值保留）、record.rs/recorder.rs（summary 钳制）；openclaw/index.ts（contentSlot() 三类槽位、结构化槽 replaceWithText=false、无 skip_tools/shell_tools、读取 tool_categories.json 带回退）；hermes/__init__.py（Shell 信封 output 拆出/回填）；compress_response_hook.py（stdout/stderr ≥2,000 字符拆出、YAML frontmatter 跳过仅为避免启动子进程）；codex adapter（无响应压缩/注入路径）；sdk.md（阈值为 Core 行为、非 Python 配置）。

未运行项：各 tokenless crate 的 cargo test —— 本次为纯文档变更，未触及任何 crate 源码；与文档数字直接相关的 l1-compressor 质量/对抗测试已通过第 5 项实际执行（97 passed / 0 failed）。

基准复测说明：变基到 cc988a6b1 前后各执行一次 compression_rate，结果完全一致（两个基线之间仅测试/Makefile 变更，git diff 07fcd0b88..cc988a6b1 -- src/tokenless/crates src/tokenless/benchmark src/tokenless/adapters 为空）。

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 82232111ee

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[qoderai]

本次仅发现 1 处文档行为描述与 Codex 特殊路径存在轻微偏差，已在英文用户手册对应位置留下建议性注释。未发现其他会影响压缩触发或阈值理解的具体问题。

---

🤖 Generated by Qoder • View workflow run

[Forrest-ly]

感谢细致的 review！这条建议已采纳，在后续提交 385ed5d 中将「压缩触发条件」第 4 条拆分为两个子项：

• 4a. 共享响应 Hook 路径：到达时不是 JSON 的纯文本会交给内容感知的文本压缩（终端输出清理、构建/日志空隙移除）；
• 4b. OpenClaw 和 Hermes：这两条路径只压缩 JSON，但框架本身会把 Shell 输出包装成 JSON（如 {"stdout": ...}），因此这类输出仍会被压缩。

YAML frontmatter 跳过的说明对三条路径共享，保留为第 4 条的收尾段落。中英文页面同步修改、结构一一对应；纯文档改动，无语义变化。

本地验证：scripts/docs-lint.sh（命名规范 + en/zh 目录镜像）与 scripts/docs-link-check.py（相对链接完整性）均通过；并用 GFM 渲染确认列表嵌套、加粗显示正常。

[SunnyQjm]

PR number: #2600
head_sha: 8a440ed
reviewed_at: 2026-08-31T06:20:46Z

评审结论

未发现 blocking package/module/public API 组织问题。

本 PR 为 tokenless 用户文档的纯文档变更，改动范围全部在 docs/user-guide/{en,zh}/token-saving/tokenless/ 下，不涉及 cosh-ng/cosh-shell 或任何 crate 代码，代码组织规范（owner 目录、root src、public API surface、依赖方向、大文件阈值）无适用对象，不产生结构性 finding。

检查要点（静态评审范围内均已核对）

• en/zh 镜像一致：6 个文件两两对应，新增小节「Compression trigger conditions and thresholds / 压缩的触发条件与阈值」在两侧同一位置插入（### 层级与相邻小节一致），5 条前提条件、4a/4b 子项、三层阈值表、5 条路径差异、「按任务查找文档」表新增行的位置和顺序均一一对应。
• 交叉引用自洽：cli-reference.md、framework-integration.md 新增的链接指向本 PR 在 user-manual.md 中新增的小节锚点（en #compression-trigger-conditions-and-thresholds、zh #压缩的触发条件与阈值），符合 GitHub slug 规则（ASCII 小写连字符、CJK 保留）；反向引用的 #adapter-processing-rules / #adapter-处理规则 为既有锚点（diff 上下文中可见旧链接已使用同一写法）。
• 文档内部口径一致：200 字符最小长度、65,536/128/8（Shell/exec）、1,048,576/65,536/32（其他结构化）、CLI 默认 4,096/32/8、TOON ≥500 字符等数字在正文、表格与 cli-reference.md 既有表述之间无自相矛盾；Codex/Qwen Code 不运行响应压缩的表述与 rebase 说明（Codex 已移除响应压缩）一致，此前 qoderai/Codex 关于「Codex 纯文本例外」的 P2 评论所针对的旧表述已随 rebase 失效。
• 历史评论处置：KaiLongZhou 关于第 4 条可读性的建议已在后续提交中采纳（拆分为 4a/4b），当前 diff 中该结构已落地且 en/zh 同步。

剩余风险

• 文档中的阈值数字与源码（tool_categories.json、compress_response_hook.py、response_compressor.rs 等）的一致性无法在本静态评审中复核，依赖 PR 描述中的逐项核对记录及 KaiLongZhou 已完成的源码对照（APPROVED）。若后续源码阈值调整，文档需同步更新——文档已注明 tool_categories.json 为单一事实来源，缓解了一部分漂移风险。
• 锚点有效性依赖 GitHub 渲染规则，本评审按规则推断；CI 的 docs-link-check.py 与 Docs Lint 已通过（见 status checks），覆盖相对链接与 en/zh 目录树镜像。

验证情况

• 已通过（CI）：📚 Docs Lint、📝 Commit Message Lint、🔍 PR Checks、Build website 均 SUCCESS；代码类检查按变更检测合理 SKIPPED。
• 未运行（本次不适用）：cargo check / cargo test（无 Rust 改动）；本评审未执行任何工具，仅基于输入中的 patch 与 PR state 静态判定。

[Forrest-ly]

已解决与 main 的合并冲突（merge commit 79d0fe66，PR 恢复为 MERGEABLE）。

冲突处理

main 的 #3173（feat(tokenless): add search path sharing）在中/英 user-manual.md 中插入 “Controlling search path sharing” / “控制搜索路径共享” 一节，位置正好与本 PR 新增的 “Compression trigger conditions and thresholds” / “压缩的触发条件与阈值” 相同，因此产生 content 冲突。两节全部保留：触发条件一节紧跟在 “Compression off” 一节之后（其第 1 条写着 “see the previous section”，指向的正是该节），搜索路径共享一节随后，仍在 “CSV/TSV views can be incomplete” 之前。cli-reference.md、framework-integration.md（中/英）自动合并，无需人工介入。

合并后本 PR 对 main 的净改动仍是 6 个文件 / +72 / -2，与冲突前完全一致。

超出纯冲突解决的两处修正（中/英同步）

按本 PR 上一轮 merge 的做法，重新用合入的 main 代码核对了新增章节，有两处因 search path sharing 而失准，已修正：

1. 第 2 条原本断言 Read/Glob/Grep/LSP/NotebookRead 及别名一律跳过响应压缩。但 compress_response_hook.py 现在会把 Claude Code 原生 Grep（mode=content 且未带 -A/-B/-C/context）的 content_origin 映射为 api_response，从而进入 SearchResultsCompressor；其余 layer_1_skip 工具仍映射为 file_content 并由 pipeline 透传，OpenClaw 侧的 Grep 也仍是 file_content。该例外是无损的、保留全部命中，因此改为显式写出并链接相邻小节，避免与它自相矛盾。
2. 第 4a 条的“内容感知文本压缩”列表只有构建/测试日志与 CSV/TSV，现补上 API 搜索路径共享并给出链接。

第 4b 条无需修改：search_candidate 要求 ContentOrigin::ApiResponse，而 4b 描述的是拆出的 shell 主文本字段（command_output 来源），仍然进不了搜索路径共享。

数值复核（合入 main 后均未变化）

tool_categories.json（65,536 / 128 / 8 与 1,048,576 / 65,536 / 32）、MIN_RESPONSE_CHARS = 200、MIN_TOON_CHARS = 500、JsonCompressionConfig 默认值（4,096 / 32 / 8）；search path sharing 在 entry.rs、lib.rs 与 pipeline config 中均默认开启。

校验

scripts/docs-lint.sh、scripts/docs-link-check.py 均通过；本次合并新增/引用的所有页内锚点在中英两份文档中都能解析到真实标题。CI 侧 📚 Docs Lint、📝 Commit Message Lint、🔍 PR Checks 已 pass，代码类 Test 作业按 docs-only 改动正确 skip。

[SunnyQjm]

PR number: #2600
head_sha: 79d0fe6
reviewed_at: 2026-09-16T07:03:20Z

Findings

• [P2] docs/user-guide/en/token-saving/tokenless/user-manual.md:120、docs/user-guide/zh/token-saving/tokenless/user-manual.md:116：数组截断规则描述错误。普通数组会保留头尾各 8 项并丢弃中段，而非仅保留头部、截断尾部；对象数组从 33 项起还可能进入不受表中数组阈值控制的 Record Reduction。当前说明会误导用户判断输出完整性和 Stash 可取回范围。

• [P2] docs/user-guide/en/token-saving/tokenless/user-manual.md:107、docs/user-guide/zh/token-saving/tokenless/user-manual.md:103：OpenClaw 与 Hermes 被错误合并描述。OpenClaw 会将普通 {"stdout": ...} 对象作为结构化 JSON 整体传入且不允许文本替换；Hermes 才会拆出 Shell 信封的 output 字段。应分别说明两条路径，避免误称 OpenClaw 的结构化槽位会进入文本压缩器。

未发现 blocking package/module/public API 组织问题。

剩余风险与验证

当前 head 尚未落实维护者最新要求的 #2596/#2601 内容整合及单提交整理。输入显示 Docs Lint、链接检查和站点构建已通过；本评审未执行工具，也未独立复核源码阈值。

[kongche-jbw]

@Forrest-ly 这三项文档更新统一收敛到本 PR（#2600）继续处理，#2596 和 #2601 将关闭并指向这里。关闭表示合并跟踪入口，不代表两项原始需求已完成；请将其有效意图一并迁移到本 PR。

请保留并整合以下三部分，中英文同步：

1. docs(tokenless): consolidate compression triggers, saving-rate fields, and reference workload #2600：压缩触发条件与阈值。 集中说明工具分类、触发门槛、阈值语义、宿主能力差异，以及 CLI/框架集成的交叉引用。
2. docs(tokenless): clarify savings-rate field definitions #2596：节省率字段定义。 说明 summary、双跑 compare、diff 的字段、公式和统计范围，区分 Tokenless 压缩节省与提供商 prompt-cache 命中指标。
3. docs(tokenless): document compression-rate scenarios and standard test load #2601：压缩率适用场景与标准测试负载。 说明场景差异、可复现的负载及运行步骤、估算 Token 的局限、基准结果与实际会话收益的区别。与 main 已有参考负载章节合并去重；引用数值须注明实际验证的版本/commit，历史快照不可当成当前部署保证。

请先重新对齐最新 main 的代码与已有文档，再整合内容。 本次查询 main 为 d940a663066499d875f951d37b8da5df3e3cd9ea；实际修改前请重新 fetch，以届时最新 main 为基线。这里要求逐项按当前源码重新核对行为，并非仅解决文本冲突。#2600 当前文字比 #2601 更新，可作为整理起点，但也仍需修正；不要直接把旧分支的整份文档覆盖回来。

本轮审查需要在整合时处理的具体问题：

• 数组保留规则（docs(tokenless): consolidate compression triggers, saving-rate fields, and reference workload #2600 EN user-manual.md:120，中文对应段）：普通数组默认保留头部和尾部 8 项，丢弃中间段；对象数组从 33 项起可能走独立的 Record Reduction，不受表中 128/65,536 阈值控制。请按当前 tokenless-compressors/src/json.rs 和 CLI 参考校正“数组上限/只保留前面/截断尾部”的说明。
• OpenClaw 与 Hermes 的输入处理（docs(tokenless): consolidate compression triggers, saving-rate fields, and reference workload #2600 EN user-manual.md:107）：OpenClaw 的 contentSlot() 将普通 {"stdout": ...} 对象整体作为结构化 JSON 传入，replaceWithText=false；字符串或单文本块才走文本路径。Hermes 会拆出 Shell 信封的 output 字段。请分别描述，不能写成两者都会拆出示例中的主文本字段。
• compare 与 diff 的公式边界（docs(tokenless): clarify savings-rate field definitions #2596 EN measuring-savings.md:82-85）：format_compare_json() 使用 saturating_sub，compare 的节省量是 max(baseline_tokens - tokenless_tokens, 0)；diff 保留负值。源码计算验证：before=100、after=150 时 compare=0%，diff=-50%；零分母均返回 0%。请同步修正公式表及“公式相同、仅口径不同”的概括。
• 不要重新引入 docs(tokenless): document compression-rate scenarios and standard test load #2601 的过时行为说明：Codex 已无 500/4,000 字符响应压缩/注入路径；OpenClaw 的 skip_tools/shell_tools 已移除；非 JSON 不能一概写成不压缩，当前已有构建日志、CSV/TSV 和搜索路径共享等路径，Grep 的适用例外也应按当前宿主及源码说明。

最终请将本 PR 相对最新 main 的全部文档改动整理为恰好 1 个 commit。 包含迁移内容和本轮修正，去掉重复章节、任务表行、交叉引用及旧的分支合并历史；要求 PR 分支本身只有这一个提交，而不是仅等待最终 squash merge。整理后请使用 git rev-list --count <最新基线SHA>..HEAD 确认结果为 1，并确认 diff 仅包含预期文档变更。

请同步重写 PR 标题/描述，说明本 PR 承接 #2596、#2601 的意图、采用的基线 SHA、最终内容和验证范围；重跑 bash scripts/docs-lint.sh、python3 scripts/docs-link-check.py、站点构建及锚点/链接检查。若保留当前压缩率数值，请在所引用版本上复测并记录命令与结果。完成后在本 PR 回复新的 head SHA，再统一复审。

[kongche-jbw]

@Forrest-ly 已复审最新提交 186fe109d0d787cb4393b6113f9524b8e833d751，对比上次审阅的 79d0fe66152e27fd05345f499af334eceb99952f。本次抓取的 base 为 b067c661ffbba8adf9aea5fc6c406023849bc7cc，merge-base 为 cc988a6b1b1cd058c68fbc1b11895d826d2619a7。

已确认 #2596 / #2601 的文档意图迁入本 PR，共修改 8 个中英文文档文件，分支已压缩为 1 个提交。当前 base 比分支起点多出的两个提交仅涉及 agent-memory，没有 tokenless 代码漂移。此前指出的数组 head/tail 与 Record Reduction、OpenClaw/Hermes 信封处理差异、compare 饱和值与 diff 有符号比例等问题已修正，旧 Codex 阈值和 OpenClaw 配置说明也已清理。

本轮新增发现：1 项 P2

[P2] OpenClaw 多块或非文本 toolResult 会直接跳过，不会进入 structured JSON 路径。

位置：英文 user-manual.md:107；中文 user-manual.md:103。

新增的 “any other object or array / 其余对象或数组整体作为结构化 JSON 传给 Core” 范围过大。实际 contentSlot() 对 role: "toolResult" 单独处理：content 不是恰好一个合法 text block 时直接返回 null，包括多个文本块、图片块、空或无效 content；回调随后直接返回，不调用 Core。见 contentSlot 分支 和 调用处。

这会使用户错误预期多块/多模态工具结果也会压缩并产生统计。请在中英文两处明确这些 toolResult 原样跳过，并把 structured JSON 的兜底范围限定为非 toolResult 的其他对象或数组；不需要修改实现。本轮直接提取最新提交的实际函数运行了四种输入：stdout 信封走 structured、单 text block 走 tool_text、双 text block 和 image block 均返回 null。

尚需完成的整理

PR 标题和正文仍是原来的阈值文档说明，正文还保留 Codex 500/4000、OpenClaw 配置覆盖等旧内容。请按最终合并后的三个文档意图重写标题和正文，说明 8 个文件的实际范围、参考基线、验证结果，以及与 #2596 / #2601 的关系。

请将上述文档修正 amend 到当前提交，继续保持 1 个 commit，完成后回复新的 head SHA。

验证：git diff --check cc988a6b1...186fe109 通过；上述 OpenClaw 函数边界检查符合源码行为。本轮未独立重跑完整 benchmark 或 E2E。最新 head 的所有实际执行 CI 检查均已通过，包括 Docs Lint、Build website 和 AW / required；代码构建/测试按文档变更范围跳过。

[Forrest-ly]

本轮意见已完成整合与修正，请复审。

新 head：186fe109d。分支已重写为相对最新 main 的单个提交（基线 cc988a6b1，Tokenless 0.8.2；git rev-list --count cc988a6b1..HEAD = 1；diff 仅 8 个 tokenless 文档文件，+199/−14，中英文镜像；旧分支合并历史已去除）。PR 标题/描述已按要求重写。

三部分内容整合：压缩触发条件与阈值（本 PR 原有）、节省率字段定义（承接 #2596 意图）、压缩率适用场景与标准测试负载（承接 #2601 意图，并与 main 已有「运行仓库参考负载」章节合并去重，未另立重复章节），均中英文同步。

四个技术问题逐项处理（均按基线源码重新核对，非照搬旧分支文本）：

1. 数组保留规则：已按 tokenless-compressors/src/json.rs 与 CLI 参考校正——头部窗口（类别阈值）+ 默认 8 项尾部窗口内联保留、中间段丢弃且启用 Stash 时可取回、两窗口间插入标记；至少 33 个 JSON Object 的对象数组不受表中 128 / 65,536 阈值控制，改走 Record Reduction（32 条基础预算：前 4 + 后 4 + 错误/异常记录 + 数值异常 + 稳定采样；完整原始数组入 Stash，无 Stash 时保留全部记录）。
2. OpenClaw 与 Hermes 分别描述：OpenClaw 的 contentSlot() 仅对纯字符串/单文本块走可替换文本路径，其余对象与数组（含 {"stdout": ...} 信封）整体作为结构化 JSON 传入且 replaceWithText=false；Hermes 则拆出 Shell 信封的 output 字段送 Core、压缩后回填同一信封。原「两者都会拆出主文本字段」的错误合并描述已删除。
3. compare/diff 公式边界：公式表已修正——summary 与 compare 的节省量经 saturating_sub 钳制为 0，stats diff 保留负值，分母为 0 时一律返回 0%；附 before=100 / after=150 → compare 0%、diff −50% 示例；「公式相同、仅口径不同」的概括已改写为同时说明口径与符号处理差异。
4. 未重新引入过时行为说明：无 Codex 500 / 4,000 字符路径、无 skip_tools / shell_tools；非 JSON 未一概写成不压缩（构建日志、CSV/TSV、搜索路径共享按当前路由分别说明）；Grep 例外按当前宿主与源码描述。

对齐最新 main 时额外发现并一并修正的两处过时文本：framework-integration 共享 Hook 路由表中「构建日志/搜索结果/表格等在领域 Compressor 接入前原样透传」一行（build-log 与 CSV/TSV 压缩器均已在 main 落地，与 user-manual 4a 的交叉引用矛盾）；以及 user-manual 中已无法在源码中找到的 AgentScope「conservative/balanced/aggressive 模式阈值」说法（已按 sdk.md 与源码改为「阈值是 Core 行为、TokenlessRuntime.compress_response 可按次覆盖」）。

压缩率数值复测：参考快照已在基线上用 compression_rate 复测并从 0.7.11（response 65.8%）更新为 0.8.2（response 36.3%，schema 47.3%、TOON-only 17.0% / −2.3% 不变），注明测量 commit，并补充叠加配置表（34.0 / 3.0 / 37.0 / 47.4 / 15.8 / 50.3%，注明合并基线与 TOON 不做门控的度量口径）。变基前后各跑一次结果一致（两基线间仅测试/Makefile 变更）。

验证记录：scripts/docs-lint.sh、scripts/docs-link-check.py、站点构建（en+zh，含锚点/链接检查）全部通过；run-benchmarks.sh --quick exit 0（cargo test 97 passed / 0 failed）。完整清单见 PR 描述「测试情况」。

[Forrest-ly]

08:11 复审意见已处理完毕，请再审。

新 head：06cbf4bd94e0e7b2ea7f72c197c0f2b8e431b98e（仍为单个提交，git rev-list --count a30575361..HEAD = 1；git diff --check 干净；diff 仍为 8 个中英文文档文件，+203/−14）。

逐项处理

1. [P2] OpenClaw 多块/非文本 toolResult 直接跳过 — 采纳并已修正（中英同步）。4b 现明确：纯字符串、或内容恰好是单个合法 text block 的 toolResult 走可替换文本路径；其余 toolResult（多个文本块、图片块、空或无效 content）原样跳过——插件在调用 Core 之前直接返回，这类结果既不压缩也不产生统计；structured JSON 兜底范围限定为非 toolResult 的对象/数组（含 {"stdout": ...} 信封）。已对照 contentSlot()（openclaw/index.ts:239-271）与调用处（:467-468，slot === null 即 return）逐分支核实，与 reviewer 的四输入实测一致。未改实现。
2. PR 标题/正文重写 — 已完成。上一轮推送后我已同步重写（标题为 consolidate compression triggers, saving-rate fields, and reference workload；正文按三个文档意图、8 文件范围、基线、验证结果与 docs(tokenless): clarify savings-rate field definitions #2596/docs(tokenless): document compression-rate scenarios and standard test load #2601 关系重写，无 Codex 500/4,000 与 OpenClaw 配置覆盖等旧内容）。复审抓取时可能恰与更新发生竞态，请以当前页面为准。

基线说明（新变化）

复审后 main 又前进了三个提交，其中 a30575361（opt-in Git diff 上下文裁剪）是行为变更且与本 PR 文档直接相关。按「以届时最新 main 为基线、逐项对源码复核」的要求，本轮已 rebase 并把该漂移吸收进文档：

• user-manual 4a：Bash 且以 diff --git 开头的 stdout 拆出信封时不受 2,000 字符下限限制；文本压缩器清单补充「需显式开启的 Git Diff 上下文裁剪」；
• user-manual 路径差异新增一条：diff 裁剪默认关闭，TOKENLESS_DIFF_COMPRESSION_ENABLED=1（或 SDK diff_compression_enabled）开启，要求命令输出来源 + 槽位可文本替换，保留全部变更行、完整原文入 Stash 并附取回提示，净节省不足 16 估算 Token 的候选被拒（对照 post_tool/pipeline.rs:92-96,135-158、arbitration.rs min_token_savings）；
• framework-integration 路由表：Git Diff 单列一行（opt-in），「长纯文本、Stack Trace、HTML、源码、Unknown」保持透传；
• measuring-savings「不参与压缩」条目：Git Diff 默认透传、开启开关后才裁剪。

merge-base 为 a30575361 而非 main tip b0acf793b：其后两个提交中 7a6258c09 修改了 .github/workflows/ci.yaml，本 fork 当前凭据无 workflow scope，包含它的推送会被 GitHub 拒绝（gh repo sync 同样被拒）；b0acf793b 仅为 tokenless 测试补充。两者均不影响文档所述行为，待凭据具备后可随下轮同步。参考快照的引用 commit 已相应改为 a30575361，并在该树上重跑 compression_rate 复核：canonical 36.3 / 47.3 / 17.0 / −2.3，stacking 34.0 / 3.0 / 37.0 / 47.4 / 15.8 / 50.3，baseline 5,551 —— 与文档数字逐项一致。

另：bot 审查此前备案的 2 条 [P2]（数组头/尾窗口与 ≥33 对象数组 Record Reduction、OpenClaw/Hermes 分别描述）已随上一轮 head 186fe109 修正，本轮 head 继续有效，其中数组语义按 json.rs 与 CLI 参考表述（头部窗口 = 类别阈值/CLI 默认 32，尾部窗口默认 8 项）。

本轮验证（真实执行）

• bash scripts/docs-lint.sh ✅（命名规范 + en/zh 目录镜像）；python3 scripts/docs-link-check.py ✅
• 站点构建 npm run build --prefix website ✅ en、zh 双语言（含断链/锚点检查）
• cargo build --release --bin compression_rate + compression_rate --json ✅ 数字与文档一致（见上）
• git rev-list --count a30575361..HEAD = 1 ✅；git diff --check a30575361...HEAD 干净 ✅
• 提交时点 CI 快照：1 项通过、其余进行中（本地已全量验证，不阻塞复审）

[kongche-jbw]

LGTM. 已复审 06cbf4bd94e0e7b2ea7f72c197c0f2b8e431b98e，未发现阻塞合并的问题。

• 上轮 OpenClaw 多块、非文本及无效 toolResult 的处理边界已在中英文文档中修正，与实际跳过 Core 的行为一致。
• #2596 / #2601 的有效文档意图已整合，当前仍为 1 个提交、8 个文档文件；此前数组保留规则、OpenClaw/Hermes 差异、节省率公式等修正均保留。
• 本轮新增的 Git Diff opt-in 裁剪说明已对照源码核对；也检查了 merge-base a30575361 到当前 main 29124111a 的差异，未发现与本 PR 文档冲突的行为变化。
• git diff --check 通过，最新 head 的所有实际执行 CI 检查均通过；代码测试按纯文档范围跳过。本轮未独立重跑 benchmark 或 E2E。

非阻塞整理：请将 PR 正文中的旧基线 cc988a6b1、+199/−14 和 OpenClaw 旧概括同步为本轮实际情况（基线 a30575361、+203/−14 及 toolResult 跳过例外）；最新评论已记录正确说明。