Repository navigation
docs(tokenless): document compression-rate scenarios and standard test load - #2601
Closed
Forrest-ly wants to merge 7 commits into
Closed
Forrest-ly wants to merge 7 commits into
Forrest-ly wants to merge 7 commits into
Conversation
![qoderai[bot]](https://avatars.githubusercontent.com/in/1396158?s=60&v=4){kind=small}
There was a problem hiding this comment.
- 英文文档的“Standard test load” 小节仅在括号中写明 “Linux only”，未明确说明该 workspace 不支持 macOS/Windows，易让跨平台用户误以为可以直接运行，建议补充平台约束说明。
- 中文文档对应小节虽提到“仅支持 Linux”，但同样未显式声明在 macOS/Windows 上不支持运行，建议与英文版对齐，追加明确的平台限制句。
🤖 Generated by Qoder • View workflow run
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d5f09b8e97
ℹ️ 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".
Collaborator
Author
|
来自同一任务的另一个并行执行：我提交的重复 PR #2602 已关闭，以本 PR 为准跟进。 一个合并顺序提示供参考：本 PR 中新增的 |
Forrest-ly
added a commit
to Forrest-ly/anolisa
that referenced
this pull request
Aug 17, 2026
…ore/tokenless-doc-compress-rate-scenarios Bring in the user-manual anchor (#compression-trigger-conditions-and-thresholds) that measuring-savings references, so PR agentic-os-org#2601 passes the website link check before PR agentic-os-org#2600 is merged. Cross-PR dependency fix for CI.
Forrest-ly
force-pushed
the
chore/tokenless-doc-compress-rate-scenarios
branch
from
August 28, 2026 09:25
cf33895 to
e2f35bd
Compare
kongche-jbw
requested review from
KaiLongZhou,
RemindD,
SunnyQjm,
Ziqi002,
chengshuyi,
edonyzpc,
ikunkun-sys,
jfeng18,
kid9,
kongche-jbw,
samchu-zsl,
yangdao479 and
yummypeng
as code owners
August 29, 2026 04:01
… --json usage - Make the Linux-only constraint of the standard test load explicit (unsupported on macOS/Windows) in EN and ZH docs. - Report the deployed (gated) full-stack rate ~65% instead of the benchmark's ungated full_stack ~63%: the compress-toon size guard keeps the original input when TOON does not reduce estimated tokens, which is what happens for the standard fixture. The ungated benchmark value is kept as a note for traceability. - Show -- --json in the compression_rate invocation; cargo consumes options before the binary argument separator, so the previously documented form errored with 'unexpected argument'.
Forrest-ly
force-pushed
the
chore/tokenless-doc-compress-rate-scenarios
branch
from
August 29, 2026 04:25
e2f35bd to
0f4993d
Compare
Collaborator
Author
|
感谢 review！关于轻微建议（P2）「全栈叠加」行 Notes 过长的处理情况： 已采纳，采用「拆为单独段落」方案（文档树中暂无脚注用法先例，为避免引入新的渲染语法风险，未使用脚注）：
已推送： 本地验证（与 Pages CI 同源的门禁）：
|
…ompress-rate-scenarios
yummypeng
removed their request for review
August 31, 2026 03:33
Collaborator
|
PR number: #2601 Findings未发现 blocking package/module/public API 组织问题。本 PR 仅改动 已核对项（静态评审范围内）
Validation
剩余风险
|
Collaborator
Author
|
回复上方 codex-auto-review（2026-08-31T06:17Z）评审意见： [P3] PR 描述与当前 patch 存在漂移 — 已采纳，已修复。 PR 描述已更新：
Open Question — PR #2600 当前状态
|
…ompress-rate-scenarios Resolve the user-manual.md conflicts introduced by dcf5723 ("feat(tokenless): compress csv and tsv output"), which added the "CSV/TSV views can be incomplete" section at the same position where this branch adds "Compression trigger conditions and thresholds". Both sections are kept. The branch section stays first because it refers back to the preceding "Compression off" section, and the csv/tsv section from main follows it unchanged. Resolved files: - docs/user-guide/en/token-saving/tokenless/user-manual.md - docs/user-guide/zh/token-saving/tokenless/user-manual.md The resulting diff against main is the original docs-only patch of this branch (8 files, +174/-2); no source or test file changed. Verified: bash scripts/docs-lint.sh, python3 scripts/docs-link-check.py.
…ompress-rate-scenarios Co-authored-by: multica-agent <github@multica.ai>
Collaborator
Author
|
已解决与 做法：把 冲突处理：只有
校验：本地 两点留给后续跟进（本次按「只解冲突、不改已评审正文」的原则未改动）：
|
Collaborator
|
PR number: #2601 Findings未发现 blocking package/module/public API 组织问题。本 PR 仅改动
已核对项（静态评审范围内）
Validation
剩余风险
|
kongche-jbw
removed request for
RemindD,
SunnyQjm,
Ziqi002,
casparant,
chengshuyi,
edonyzpc,
jfeng18,
kid9,
samchu-zsl and
yangdao479
September 16, 2026 06:23
Collaborator
|
本 PR 关闭，后续统一在 #2600 跟踪和交付。关闭仅表示收敛 PR，不代表本项文档需求已经完成。 请将本 PR 的原始意图迁移至 #2600：解释压缩率适用场景与影响因素，提供可复现的标准测试负载和运行步骤，说明估算 Token、历史基准数字与实际会话收益的区别。中英文同步，并与 main 已有参考负载章节及 #2600 的触发条件章节合并去重。 迁移时请按最新 main 重新核对实现，不要带回旧版 Codex 响应压缩、OpenClaw 分类覆盖项或“非 JSON / Grep 一律不压缩”等过时表述。三个 PR 的整合内容应在 #2600 中整理为相对最新 main 的 1 个 commit，重新验证后统一复审。 完整迁移要求与本轮审查问题见： #2600 (comment) |
Forrest-ly
added a commit
to Forrest-ly/anolisa
that referenced
this pull request
Sep 16, 2026
…rent source Carry the documentation intents of PRs agentic-os-org#2596 and agentic-os-org#2601 into this single change set and re-verify every claim against current source behavior: - user-manual: add compression trigger conditions and thresholds; describe OpenClaw input handling (string / single-text-block take the replaceable text path; other objects such as shell envelopes pass whole as structured JSON without text replacement) separately from Hermes (unwraps the shell envelope output field); correct array truncation to the head window plus 8-item tail window with a stashed middle segment, and document the 33-object record-reduction exception that bypasses the category caps - measuring-savings: add saving-rate field definitions, distinguishing the clamped summary/compare percentages (saturating subtraction, 0% on a zero denominator) from stats diff, which keeps negative values; add compression-rate applicability scenarios; refresh the reference workload snapshot to 0.8.2 measurements and add the stacking configurations - cli-reference, framework-integration: add cross-references and update the shared-hook routing table for the connected build-log, CSV/TSV, and search path sharing compressors Docs only; en/zh mirrored. Verified with scripts/docs-lint.sh, scripts/docs-link-check.py, the website build for both locales, and a re-run of the l1-compressor compression_rate report on the baseline.
Forrest-ly
added a commit
to Forrest-ly/anolisa
that referenced
this pull request
Sep 16, 2026
…rent source Carry the documentation intents of PRs agentic-os-org#2596 and agentic-os-org#2601 into this single change set and re-verify every claim against current source behavior: - user-manual: add compression trigger conditions and thresholds; describe OpenClaw input handling (string / single-text-block take the replaceable text path; other objects such as shell envelopes pass whole as structured JSON without text replacement) separately from Hermes (unwraps the shell envelope output field); correct array truncation to the head window plus 8-item tail window with a stashed middle segment, and document the 33-object record-reduction exception that bypasses the category caps - measuring-savings: add saving-rate field definitions, distinguishing the clamped summary/compare percentages (saturating subtraction, 0% on a zero denominator) from stats diff, which keeps negative values; add compression-rate applicability scenarios; refresh the reference workload snapshot to 0.8.2 measurements and add the stacking configurations - cli-reference, framework-integration: add cross-references and update the shared-hook routing table for the connected build-log, CSV/TSV, and search path sharing compressors Docs only; en/zh mirrored. Verified with scripts/docs-lint.sh, scripts/docs-link-check.py, the website build for both locales, and a re-run of the l1-compressor compression_rate report on the baseline.
kongche-jbw
pushed a commit
that referenced
this pull request
Sep 16, 2026
…rent source Carry the documentation intents of PRs #2596 and #2601 into this single change set and re-verify every claim against current source behavior: - user-manual: add compression trigger conditions and thresholds; describe OpenClaw input handling (string / single-text-block take the replaceable text path; other objects such as shell envelopes pass whole as structured JSON without text replacement) separately from Hermes (unwraps the shell envelope output field); correct array truncation to the head window plus 8-item tail window with a stashed middle segment, and document the 33-object record-reduction exception that bypasses the category caps - measuring-savings: add saving-rate field definitions, distinguishing the clamped summary/compare percentages (saturating subtraction, 0% on a zero denominator) from stats diff, which keeps negative values; add compression-rate applicability scenarios; refresh the reference workload snapshot to 0.8.2 measurements and add the stacking configurations - cli-reference, framework-integration: add cross-references and update the shared-hook routing table for the connected build-log, CSV/TSV, and search path sharing compressors Docs only; en/zh mirrored. Verified with scripts/docs-lint.sh, scripts/docs-link-check.py, the website build for both locales, and a re-run of the l1-compressor compression_rate report on the baseline.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
改动说明
应客户反馈，在 tokenless 用户文档中补充「压缩率适用场景」说明，并指引使用仓库内置的标准测试负载，使用户能够：1) 了解不同场景下的预期压缩率区间与影响因素；2) 用标准负载复现参考压缩率，自行验证所用版本的效果。
变更内容
8 个 Markdown 文件（+174/-2），纯文档变更，覆盖 4 个文档页面的中英文版本：
docs/user-guide/{zh,en}/token-saving/tokenless/measuring-savings.mdsrc/tokenless/benchmark/l1-compressor/fixtures/下 3 个 canonical fixtures，由python/gen_fixtures.py生成、无随机数、字节级可复现、已提交）；cargo run --release --bin compression_rate（快速报告）与./run-benchmarks.sh --quick（完整质量/对抗测试 + 报告），均已在本地实际执行验证；docs/user-guide/{zh,en}/token-saving/tokenless/user-manual.mdtool_categories.json类别/阈值表及阈值含义、独立 CLI / Codex / OpenClaw / TOON / AgentScope 的路径差异。该小节由本 PR 自包含新增，不依赖其他 PR 的合并顺序（本 PR 早期版本曾计划仅交叉引用 PR docs(tokenless): consolidate compression triggers, saving-rate fields, and reference workload #2600 的对应小节，现已改为本 PR 内自带）。docs/user-guide/{zh,en}/token-saving/tokenless/cli-reference.mddocs/user-guide/{zh,en}/token-saving/tokenless/framework-integration.md与 PR #2600 的关系（合并顺序说明）
PR #2600（截至 2026-08-31 仍为 OPEN）同样在
user-manual.md（EN/ZH）相同位置新增同名小节「压缩的触发条件与阈值」，并带有相同的任务查找表行与cli-reference.md/framework-integration.md交叉引用。本 PR 当前 patch 已自包含该小节，交叉引用锚点全部在本 PR 内闭环，不依赖 #2600 的合并顺序，可独立合并；作者早期评论中关于锚点/合并顺序的顾虑随之失效。两个 PR 同为一人所作，无论哪个先合并，后合并一方 rebase 时删除与 main 重复的小节/交叉引用即可（两版小节文字存在少量差异，rebase 时以 main 中已合并版本为准对齐）。测试情况
测试范围与实际执行的命令（本次为纯文档变更，共 8 个 Markdown 文件；为保证文档中的数字与操作步骤真实有效，实际运行了标准测试负载全流程）：
cargo build --release --bin compression_rate（l1-compressor 独立 workspace）— 成功cargo run --release --bin compression_rate— 输出与文档参考节省率一致：canonical response 65.8%、canonical schema 47.3%、混合负载 response_only 61.7%、schema_response 64.7%、full_stack 62.9%、toon_only 15.8%./run-benchmarks.sh --quick（完整质量/对抗测试 + 压缩率报告）— 全部通过，退出码 0cargo test --release— 96 passed、0 failed（13 个测试套件，含质量保留、对抗、worst-case、压缩率回归守护）bash scripts/docs-lint.sh（CI 文档门禁：命名规范 + en/zh 目录树镜像）— 通过python3 scripts/docs-link-check.py（相对链接检查）— 通过common/hooks/compress_response_hook.py、compress_toon_hook.py（最小 200 字符）、codex/scripts/compress-response（500/4,000 字符）、tool_categories.json（Layer 2/3 阈值）、benchmark fixtures 与gen_fixtures.py环境概要：Linux x86_64；Rust 1.94.1（cargo 1.94.1）；Python 3.8.17；rtk 0.43.0（报告中 RTK 采样正常输出）。
结果汇总：96 个测试全部通过，0 失败；文档门禁脚本全部通过；文档参考节省率与实测值完全一致。
未运行项及原因：
cargo bench）：未运行 — 本次不涉及性能结论，--quick模式按设计跳过该部分。2026-09-08 更新：同步 main 并解决合并冲突
main 合入
feat(tokenless): compress csv and tsv output后，该提交在user-manual.md（中英文）中新增的「CSV/TSV 视图可能不完整 / CSV/TSV views can be incomplete」小节，与本 PR 在同一位置新增的「压缩的触发条件与阈值 / Compression trigger conditions and thresholds」小节重叠，产生内容冲突。已将 main 合并进本分支并解决冲突。解决方式：两个小节全部保留。本 PR 的小节排在前面（其第 1 条「见上一节」指向前面的「关闭压缩只影响压缩操作」小节，顺序不能调换），main 新增的 CSV/TSV 小节原样紧随其后，未改动 main 的任何文字。
冲突文件（其余 6 个文件自动合并，无冲突）：
docs/user-guide/en/token-saving/tokenless/user-manual.mddocs/user-guide/zh/token-saving/tokenless/user-manual.md合并后验证：
git diff origin/main --stat结果为 8 个 Markdown 文件、+174/-2，与本 PR 原始 patch 完全一致 —— 合并未引入任何源码/测试文件改动，也未丢失或改写 main 的内容（user-manual.md相对 main 为纯新增 29 行、0 删除）。git merge-tree --write-tree origin/main <head>返回 0，无冲突；GitHub API 侧mergeable已由CONFLICTING恢复为MERGEABLE。bash scripts/docs-lint.sh通过（命名规范 + en/zh 目录树镜像），python3 scripts/docs-link-check.py通过（相对链接全部可解析）。user-manual.md无重复标题，#compression-trigger-conditions-and-thresholds/#压缩的触发条件与阈值锚点在本 PR 内自包含闭环，无残留冲突标记。本次为纯文档合并冲突解决，未触及任何 crate 源码，故未重复执行上一节记录的
cargo test/compression_rate/run-benchmarks.sh（其结论对本文档内容仍然有效，文档中的数字与源码阈值未发生变化）。与 PR #2600 的合并顺序：#2600 目前在
user-manual.md相同位置新增同名小节，本 PR 已自包含该小节，两者可独立合并，但后合并的一方需删除与 main 重复的小节、任务查找表行与cli-reference.md/framework-integration.md交叉引用（以 main 中已合入的版本为准对齐文字）。