Token Context Optimizer (exhaustive)

Token 上下文优化器（详尽版）

Guiding rule

指导原则

Keep only decision-relevant tokens in context; move everything else out — to subagents, to files, to summaries, to memory, or to cache. Optimization never overrides correctness: if a specific fact, function body, or exact string is needed for the right answer, it stays in context.
只在上下文中保留与决策相关的 token；其余一切移出——移交给子代理、写入文件、转为摘要、存入记忆，或放入缓存。优化绝不凌驾于正确性之上：若得出正确答案需要某个具体事实、函数体或精确字符串，它就必须留在上下文中。

Techniques are grouped by where the saving happens. All are safe because they discard only low-signal redundancy, never information required to solve the problem.
各项技术按节省发生的位置分组。它们都是安全的，因为只丢弃低信号冗余，绝不丢弃解决问题所需的信息。

1. Don't bring it in (input reduction)

1. 别让它进来（输入削减）

• Subagent offload — delegate broad exploration to Agent (Explore/lite); results return as a compact summary, not raw files. Add max_turns + model:"lite" to cap cost. Safe: only the summary needed for synthesis enters context.
• 子代理卸载 — 将大范围探索交给 Agent（Explore/lite）；返回的是紧凑摘要而非原始文件。添加 max_turns + model:"lite" 以控制成本。安全：仅有用于综合的摘要进入上下文。
• Progressive disclosure — keep this file lean; load references/strategies.md only mid-task; lazy-load bundled references via Grep patterns. Safe: detail fetched on demand, not pre-loaded.
• 渐进式披露 — 保持本文件精简；仅在任务中途加载 references/strategies.md；通过 Grep 模式惰性加载打包的参考文档。安全：细节按需获取，而非预先加载。
• Search before read — Grep/Glob to locate, then Read with offset/limit (≤200). Safe: you read exactly the lines you act on.
• 先搜后读 — 用 Grep/Glob 定位，再用带 offset/limit（≤200）的 Read 读取。安全：你只读自己要处理的那几行。
• Source-side filtering — Grep output_mode:files_with_matches for paths only; pipe JSON through jq keeping only fields; use head_limit/offset to page. Safe: irrelevant fields never enter context.
• 源头过滤 — 路径用 Grep output_mode:files_with_matches；用 jq 管道只保留需要的字段；用 head_limit/offset 分页。安全：无关字段永远不进入上下文。
• Media/binary by path — pass file paths; never inline images/PDFs/base64. Safe: bytes read by the tool only at point of use.
• 媒体/二进制只传路径 — 传递文件路径；绝不内联图片/PDF/base64。安全：字节仅在工具使用时才被读取。
• Strip comments/whitespace for reasoning — when holding large code for analysis, minify; keep the original for edits. Use scripts/compact_json.py for structured data. Safe: semantics preserved; original restored before writing.
• 推理时剥离注释/空白 — 当为分析而持有大量代码时，做精简；保留原始文件用于编辑。结构化数据可用 scripts/compact_json.py。安全：语义保留；写入前恢复原始内容。
• Hold diffs, not full files — in review/edit, keep only the diff. Safe: unchanged lines are irrelevant to the change.
• 只持差异，不持全文件 — 在审查/编辑时，只保留 diff。安全：未改动行与该变更无关。
• Abbreviation maps — define a one-time short-key map for repeated long strings/IDs; use short forms thereafter. Safe: map is the single source of expansion.
• 缩写映射 — 为反复出现的长字符串/ID 定义一次短键映射；此后一律使用短形式。安全：映射是展开的唯一来源。
• Reference by ID, expand on demand — keep entity IDs; fetch full records only when used. Safe: only needed records are materialized.
• 按 ID 引用，按需展开 — 保留实体 ID；仅在用到时才拉取完整记录。安全：只有需要的记录才会被实例化。
• Disable ANSI color/paging in CLI — pass --no-pager, --color=never, LANG=C to git/grep/ls so output is smaller and cache-friendly. Safe: identical data, no escape codes.
• 关闭 CLI 的 ANSI 色彩/分页 — 给 git/grep/ls 传 --no-pager、--color=never、LANG=C，让输出更小且对缓存友好。安全：数据完全相同，只是没有了转义码。
• Skip boilerplate when reading source — ignore license headers / import blocks unless relevant; grep the meaningful body. Safe: non-functional text omitted.
• 读源码时跳过样板 — 忽略许可证头/导入块（除非相关）；用 grep 查找有意义的主体。安全：省略非功能性文本。
• Request dense, structured returns from subagents — ask for JSON/bullets, not prose, so the summary is compact. Safe: information equivalent, lower token cost.
• 向子代理要稠密、结构化的返回 — 要求 JSON/列表而非散文，让摘要更紧凑。安全：信息等价，但 token 成本更低。
• Ask for counts/summaries, not enumerations — "how many?" beats dumping all items. Safe: the aggregate conveys the answer.
• 要计数/摘要，不要枚举 — “有多少个？”胜过把全部条目倒出来。安全：聚合结果就足以传达答案。

2. Shrink what's already in (compression)

2. 压缩已在其中的内容（压缩）

• Summarize tool output — reduce to decision-relevant facts; quote only exact strings (errors, identifiers). Safe: summary retains the signal.
• 总结工具输出 — 精简为与决策相关的事实；只引用精确字符串（错误、标识符）。安全：摘要保留信号。
• Redirect huge stdout to scratch — run commands via scripts/run_to_scratch.py so full output lands in a file; context sees only a token-bounded head + path. Safe: full output is on disk, retrievable.
• 把巨型 stdout 重定向到临时文件 — 用 scripts/run_to_scratch.py 运行命令，完整输出落入文件；上下文只看到受 token 限制的开头几行 + 路径。安全：完整输出在磁盘上，可随时取回。
• Chunked streaming — loop read 200 lines → extract → discard → advance for files too big to read at once. Safe: each slice processed fully before discard.
• 分块流式 — 循环读取 200 行 → 提取 → 丢弃 → 推进，用于一次读不完的大文件。安全：每一片在丢弃前都被完整处理。
• Scratch offload of intermediate analysis — write long extractions/tables to a scratch file, keep a one-line pointer. Safe: pointer is enough to retrieve.
• 中间分析落临时文件 — 把冗长的提取/表格写入临时文件，保留一行指针。安全：指针已足够取回。
• Compress instructions — terse prompts, no duplicated constraints, minimal few-shot examples. Safe: models follow concise instructions well.
• 压缩指令 — 简洁的提示，不重复约束，少量示例。安全：模型对简洁指令遵循得很好。
• Anchor with file:line refs — store references, not values; fetch on demand. Safe: reference is precise and retrievable.
• 用 file:line 引用锚定 — 存引用而非数值；按需取回。安全：引用精确且可取回。
• Minify JSON in context — compact separators, drop insignificant whitespace. Safe: data identical.
• 上下文中 JSON 压缩 — 紧凑分隔符，去掉无意义空白。安全：数据完全相同。
• Token-targeted summaries — bound each summary to a token budget; stop when reached. Safe: budget sized to retain signal.
• 面向 token 预算的摘要 — 给每个摘要设定 token 预算；达到即止。安全：预算大小足以保留信号。

3. Don't carry it forward (lifecycle)

3. 别把它带向未来（生命周期）

• Avoid redundant re-ingestion — trust already-injected context; never re-read/re-fetch the same thing. Safe: content is already present.
• 避免冗余再摄入 — 信任已注入的上下文；绝不重复读/取同一内容。安全：内容已存在。
• Drop superseded info — when a fact updates, discard the stale version from active reasoning. Safe: only the latest is correct.
• 丢弃被取代的信息 — 当事实更新时，从活跃推理中丢弃过期版本。安全：只有最新版才正确。
• Compact under pressure — emit a state summary (goal, decisions, open items, key refs) and drop verbose raw history. Safe: continuity preserved via summary.
• 压力下压缩 — 产出状态摘要（目标、决策、待办、关键引用）并丢弃冗长的原始历史。安全：通过摘要保持连续性。
• Proactive periodic compaction — compact every N turns, not only at the limit. Safe: prevents a late, lossy crunch.
• 主动定期压缩 — 每 N 轮压缩一次，而非只在触顶时。安全：避免后期有损的仓促压缩。
• Externalize durable state to memory — persist decisions/preferences/conventions to memory files; read on demand across sessions. Safe: survives without re-carrying source.
• 把持久状态外置到记忆 — 把决策/偏好/约定持久化到记忆文件；跨会话按需读取。安全：无需重新携带来源即可存续。
• Scope historical recall — conversation_search only when needed, with self-contained query + tight date filters. Safe: returns few relevant hits, not a dump.
• 限定历史召回范围 — 仅在需要时调用 conversation_search，使用自包含查询 + 严格日期过滤。安全：返回少量相关命中，而非一整坨。
• Session-start preamble compaction — replace earlier Q&A with one standing summary at the top; re-reference it instead of re-carrying transcripts. Safe: summary preserves intent.
• 会话开头 preamble 压缩 — 用顶部一条常驻摘要替换早前的问答；引用它而非重新携带转录。安全：摘要保留意图。
• Skip-list of explored paths — maintain a set of already-visited files/paths to avoid re-exploration. Safe: no duplicate work.
• 已探索路径的 skip-list — 维护一组已访问过的文件/路径集合，避免重复探索。安全：没有重复工作。

4. Cache & reuse (avoid recompute)

4. 缓存与复用（避免重算）

• Stable prefix for prompt caching — keep large reused references at a fixed position; never insert volatile text (timestamps/ids) into that block. Safe: cached prefix is unchanged, just billed once.
• 稳定前缀用于提示缓存 — 把大型可复用参考放在固定位置；绝不把易变文本（时间戳/ID）插入该块。安全：缓存前缀不变，只计费一次。
• Disk cache of expensive results — cache analysis keyed by input hash; reuse instead of recompute. Safe: identical input → identical output.
• 把昂贵结果做磁盘缓存 — 以输入哈希为键缓存分析结果；复用而非重算。安全：相同输入 → 相同输出。
• Build a lightweight index once — file list / symbol table queried instead of re-grepping the whole tree. Safe: index is a faithful map.
• 一次性构建轻量索引 — 建立文件列表/符号表来查询，而非重新 grep 整棵树。安全：索引是一份忠实的地图。
• Resume a subagent — continue with SendMessage/resume instead of re-briefing + re-exploring. Safe: prior exploration is reused, not redone.
• 恢复子代理 — 用 SendMessage/resume 继续，而非重新 brief + 重新探索。安全：先前的探索被复用，而非重做。

5. Parallel & route (compute efficiency)

5. 并行与路由（计算效率）

• Parallel independent calls — issue independent tool calls in one message. Safe: same results, fewer round-trips.
• 并行独立调用 — 在一条消息中发出相互独立的工具调用。安全：结果相同，往返更少。
• Fan-out / fan-in — spawn N lite agents for independent subtrees, aggregate (see subagent-fanout skill). Safe: each subtree summarized once.
• 扇出 / 扇入 — 为独立子树生成 N 个 lite 代理，再聚合（见 subagent-fanout 技能）。安全：每个子树只被总结一次。
• Right-size model per subtask — lite for search, default for synthesis, reasoning only for hard problems. Safe: task gets the model it needs.
• 按子任务选对模型 — 搜索用 lite，综合用 default，只有难题才用 reasoning。安全：任务得到它所需的模型。
• Batch API where supported — combine independent inferences. Safe: identical outputs, lower overhead.
• 支持处用 Batch API — 合并相互独立的推理。安全：输出相同，开销更低。

6. Output discipline

6. 输出规范

• Lean user-facing text — no echo of tool JSON, raw dumps, or full file bodies; report outcomes + next steps. Safe: user reads the conclusion, not the transcript.
• 面向用户的文字要精简 — 不回显工具 JSON、原始转储或完整文件体；只报告结果与下一步。安全：用户读结论，而非转录。
• Constrain answer format/length — request the minimal format (bullets vs prose, ≤N points). Safe: answer still complete, just not padded.
• 约束回答的格式/长度 — 要求最小格式（列表 vs 散文，≤N 点）。安全：答案仍完整，只是不注水。
• Don't restate the question — answer directly. Safe: redundancy removed, meaning intact.
• 不要复述问题 — 直接回答。安全：去掉冗余，语义完好。
• Prefer dedicated tools over shell — Read/Edit emit cleaner, smaller diffs than cat/sed (no ANSI noise, no full echoes). Safe: same operation, less noise.
• 优先用专用工具而非 shell — Read/Edit 比 cat/sed 产生更干净、更小的 diff（无 ANSI 噪音，无完整回显）。安全：同一操作，更少噪音。
• Diff-based verification — verify via git diff rather than re-reading whole edited files. Safe: diff shows exactly what changed.
• 基于 diff 的验证 — 用 git diff 验证，而非重读整个被编辑文件。安全：diff 精确显示改动。

7. Governance

7. 治理

• Token budget per phase — allocate a budget; when near, compress proactively. Measure with scripts/estimate_tokens.py. See context-budget-guard skill. Safe: budgeting triggers compression, not omission.
• 每个阶段设 token 预算 — 分配预算；临近时用主动压缩。用 scripts/estimate_tokens.py 衡量。见 context-budget-guard 技能。安全：预算触发压缩，而非遗漏。
• Disambiguate before broad work — one AskUserQuestion can prevent 5–10 wasted explorations. Safe: right scope explored once.
• 在铺开前先澄清 — 一次 AskUserQuestion 可避免 5–10 次白费的探索。安全：正确范围一次性探索到位。

8. Measure & make savings visible (ledger)

8. 度量并让节省可见（账本）

Optimization you can't see is optimization you can't trust. Make every saving auditable:
看不见的优化是不可信的优化。让每一笔节省都可审计：
- Log each applied technique — after applying an optimization, call scripts/token_ledger.py log --technique <name> --raw <n> --optimized <m> --task <label> (or --raw-file/--optimized-file to auto-estimate from real content). raw = tokens that would have entered context without the technique; optimized = tokens that actually entered. The script auto-resolves which skill owns the technique (override with --skill <name>), and prints log ok | +N saved | <skill>｜<technique>. Safe: measurement is external; nothing about the answer changes.
- 记录每个已应用技术 — 应用优化后，调用 scripts/token_ledger.py log --technique <name> --raw <n> --optimized <m> --task <label>（或用 --raw-file/--optimized-file 从真实内容自动估算）。raw = 若不用该技术本会进入上下文的 token；optimized = 实际进入的 token。脚本自动判定该技术归属哪个技能（可用 --skill <name> 覆盖），并打印 log ok | +N saved | <skill>｜<technique>。安全：度量在外部进行；答案本身不变。
- Auto-log convenience — run_to_scratch.py and compact_json.py accept --log (plus optional --task/--note): they record the saving to the ledger themselves, so you don't need a separate token_ledger.py log call. Prefer --log when you run those scripts — it closes the "I forgot to record" gap. Both auto-estimate raw (full output / original JSON) and optimized (head / compacted) from the real data.
- 自动记录便利项 — run_to_scratch.py 与 compact_json.py 都接受 --log（及可选的 --task/--note）：它们会把节省自行写入账本，因此无需单独的 token_ledger.py log 调用。运行这两个脚本时优先用 --log——它堵上“我忘了记录”的漏洞。两者都从真实数据自动估算 raw（完整输出 / 原始 JSON）和 optimized（开头 / 压缩后）。
- Footer on EVERY reply (with skill-capability breakdown) — at the end of every reply, run scripts/token_ledger.py report and append its exact stdout as the final block of your reply (no extra commentary wrapped around it). Default output shows the total + a per-method breakdown that names which skill's capability saved each chunk:
- 每条回复末尾都加页脚（含 skill-能力 拆分） — 在每条回复末尾，运行 scripts/token_ledger.py report，并把其精确 stdout 作为回复最后一块追加（不要在周围包裹额外评论）。默认输出显示总计 + 一个按方法的拆分，标明是哪个 skill 的能力省下了每部分：
本次会话节约token（N），通过： 方法1(x);方法2(y);… 通过以下 skill 具体能力节约： • token-context-optimizer｜先搜后读：x • subagent-fanout｜子代理分流：y • …
The script is incremental (a checkpoint), so it shows only what was saved this question. If nothing was saved, it prints 本次会话节约token（0），通过：无 — still append it. report --compact = single-line form; report --all = cumulative; report --no-checkpoint = preview without advancing. Safe: the footer is a side channel; the answer itself is unchanged.
该脚本是增量式的（有一个检查点），因此只显示本次提问省下的部分。若什么都没省，它会打印 本次会话节约token（0），通过：无——照样追加。report --compact = 单行形式；report --all = 累计；report --no-checkpoint = 仅预览不推进。安全：页脚是旁路信道；答案本身不变。
- Inspect / aggregate on demand — token_ledger.py summary (full breakdown by skill → capability → task), today (today only), last 10 (recent events, each tagged with its skill). These are for manual checks, not the per-reply footer. Safe: read-only views.
- 按需查看 / 聚合 — token_ledger.py summary（按 skill → 能力 → task 的完整拆分）、today（仅今天）、last 10（最近事件，每条都带其技能标签）。这些用于人工检查，而非每条回复的页脚。安全：只读视图。
- Estimate, don't guess blindly — for raw/optimized, prefer passing the actual avoided content (--raw-file full_file.py) and the actual kept content (--optimized-file summary.txt) so the delta is concrete, not invented. Safe: numbers trace to real artifacts.
- 要估算，别盲猜 — raw/optimized 优先传入真实被避免的内容（--raw-file full_file.py）和真实保留的内容（--optimized-file summary.txt），这样差值具体而非编造。安全：数字可追溯到真实产物。
- The ledger is a local append-only JSONL at ~/.workbuddy/token_savings_ledger.jsonl; override with --ledger PATH. Totals accumulate across tasks and sessions; the report checkpoint lives in the same folder (*.checkpoint).
- 账本是本地只追加的 JSONL，位于 ~/.workbuddy/token_savings_ledger.jsonl；可用 --ledger PATH 覆盖。总计跨任务、跨会话累积；report 的检查点位于同一文件夹（*.checkpoint）。

Quick decision table

快速决策表

Companion skills (install to extend coverage)

配套技能（安装以扩展覆盖面）

• subagent-fanout — decompose a big task into N independent lite subagents, brief them, aggregate. The parallel-investigation workflow.
• subagent-fanout — 把一个大任务拆成 N 个独立的 lite 子代理，分别 brief 后聚合。即并行调查工作流。
• prompt-cache-optimizer — structure context for maximum prompt-cache hits (stable prefix discipline, cache-breaking pitfalls).
• prompt-cache-optimizer — 为最大化提示缓存命中而组织上下文（稳定前缀纪律、破坏缓存的坑）。
• context-budget-guard — enforce per-phase token budgets and auto-select the right optimization tier (with budget_check.py).
• context-budget-guard — 强制执行分阶段 token 预算并自动选对优化档位（配合 budget_check.py）。

Resources

资源

• references/strategies.md — detailed, categorized playbook with before/after examples and edge cases. Load mid-task.
• references/strategies.md — 带前后对比示例与边界情况的、按类细分的详细手册。任务中途再加载。
• references/error-handling.md — 本技能脚本的报错 / 降级 / 排查指引（tiktoken 缺失退回启发式、账本损坏可重建等）。
• scripts/estimate_tokens.py — rough token estimator to measure savings (uses tiktoken cl100k_base when available, else a CJK/non-CJK heuristic). Execute, don't read.
• scripts/estimate_tokens.py — 粗略的 token 估算器，用于衡量节省（可用时用 tiktoken cl100k_base，否则用 CJK/非-CJK 启发式）。执行，别读。
• scripts/token_ledger.py — record and report token savings (log / summary / today / last / report). This is the visibility layer: run it after applying optimizations so every saving is auditable.
• scripts/token_ledger.py — 记录并报告 token 节省（log / summary / today / last / report）。这是可见性层：应用优化后运行它，让每笔节省都可审计。
• scripts/compact_json.py — minify JSON / keep whitelisted keys / truncate long strings for context holding. Add --log to auto-record the saving.
• scripts/compact_json.py — 压缩 JSON / 保留白名单键 / 截断长字符串，用于上下文持有。加 --log 可自动记录节省。
• scripts/run_to_scratch.py — run a command, write full stdout to scratch, print token-bounded head + path. Add --log to auto-record the saving.
• scripts/run_to_scratch.py — 运行命令，把完整 stdout 写入临时文件，打印受 token 限制的开头 + 路径。加 --log 可自动记录节省。
• scripts/common.py — shared estimator + technique→skill/Chinese-name maps + the single ledger_log() writer used by the other scripts (keeps the heuristic and the ledger format defined once).
• scripts/common.py — 共享估算器 + 技术→技能/中文名映射 + 其他脚本共用的单一 ledger_log() 写入器（让启发式与账本格式只定义一次）。