Token节约专家
本技能遵循同目录 CLAUDE.md 的行为约束。任何冲突以 CLAUDE.md 为准。
一、核心目标
将单次任务的 Token 消耗降低 90%–98%，在不损失任务正确性的前提下压缩输入与输出。
适用场景：
- 需要在大型仓库中定位代码，但不能整仓读入
- 需要读取超长文件（日志、数据集、单文件数千行）
- 长对话历史累积导致上下文膨胀
- 多轮迭代任务、成本敏感的批量任务
- 需要严格控制输出体积的自动化流水线
二、三层懒加载架构（渐进式披露）
| 层级 | 载体 | 加载时机 | 上下文占用 |
|---|---|---|---|
| 元数据层 | 本文件 frontmatter（name + description） |
常驻 | ≤ 100 token |
| 指令层 | 本文件正文 | 命中触发词后按需加载 | 按需 |
| 资源层 | scripts/ 下的可执行脚本 |
仅通过 Bash 调用，脚本源码不进上下文 | 0 |
原则：能不进上下文的内容，一律外置为脚本；能用返回值代替的内容，一律不读原文。
三、五大核心功能
① 行为约束规范
- 禁止无目标的全文件读取；先定位再读取。
- 单次读取上限 100 行；超出则用
offset/limit分片或改用检索脚本。 - 禁止复述已在上下文中的内容；禁止贴回原始代码后再改。
- 中间过程不外显，只输出结论与差异。
② 结构化 JSON 输出
- 所有脚本统一输出紧凑 JSON，无缩进、无多余空白、无自然语言包装。
- 字段名使用短名（
file/line/kind/name），不重复冗余字段。 - 出错时输出
{"error":"<code>"}并以非零码退出，避免长堆栈污染上下文。
③ 工具调用替代上下文注入
优先用脚本返回摘要，而不是把文件塞进上下文：
- 找符号/结构 → scripts/code_graph.py
- 找内容/行号 → scripts/file_search.py
- 只有在拿到精确行号后，才用 Read 的 offset/limit 读取该窗口。
④ 上下文滑动窗口 + 摘要压缩
- 保留最近 N 轮完整对话（建议 N=3），更早的轮次压缩为 ≤ 5 行要点摘要。
- 摘要只保留：已确认结论、未决问题、关键路径与约束。
- 已被后续结论覆盖的历史内容直接丢弃，不做保留式追加。
⑤ 多 Agent 流水线拆分
- 将大任务拆为「检索 → 分析 → 修改 → 校验」四段，各段独立上下文。
- 段间只传递结构化产物（JSON / 文件路径 / 行号区间），不传原文。
- 校验段只读被修改的行窗口，不重读整文件。
⑥ 生成前决策阶梯（Ponytail 思路）
写任何代码前，AI 必须依次过 7 步检查，目标"能不写就不写"：
1. 这个功能真的需要存在吗（YAGNI，不需要就跳过）
2. 代码库是否已有实现（有就复用，先跑 scripts/preflight.py）
3. 标准库能解决吗（用）
4. 平台原生 API 能解决吗（用）
5. 已有依赖能解决吗（用）
6. 能一行搞定吗（一行）
7. 以上都不行才写最少代码
信任边界硬规则：绝不在输入校验 / 鉴权 / 序列化等信任边界处为省事简化校验（硬编码约束，优先级高于省 token）。
⑦ 语义图谱替代全目录扫描（CodeGraph 思路）
升级后的 scripts/code_graph.py 把代码库预索引为「符号 + 边」知识图谱，一次调用拿结构，替代反复 grep / 读文件：
- --mode symbols：输出符号表（含 file/line/kind/name），向后兼容旧调用方。
- --mode graph：输出完整图谱 {"files","symbols","edges"}，边含 calls/imports/extends。
- --mode callers <符号>：返回直接调用者（谁调用了它）。
- --mode callees <符号>：返回被直接调用的符号（它调用了谁）。
- --mode impact <符号>：递归向上追溯全部受影响调用者（影响面分析）。
注：本工具为正则启发式轻量替代，非 Tree-sitter AST，无法解析动态分发 / 反射；重型场景用真正的 CodeGraph。
四、工具使用优先级清单
scripts/preflight.py：写代码前的复用检查首选——先确认仓库是否已有类似实现，落实决策阶梯第②步。scripts/code_graph.py：需要了解代码结构、函数/类/接口清单，或做影响面分析（callers/callees/impact）时的首选。scripts/file_search.py：需要按正则定位内容并取少量上下文时的首选。Grep（files_with_matches模式）：只需知道"哪些文件命中"时使用。Glob：只需按路径模式列文件时使用。Read+offset/limit：已知精确行号后的窗口读取。Read（全文件）：最后手段，仅当文件 < 100 行且必须全量理解时使用。
禁止顺序倒置：不得在未执行 1–6 的情况下直接使用 7。
五、效果验证数据
| 优化手段 | Token 降低比例 | 适用场景 |
|---|---|---|
| 三层懒加载（frontmatter 常驻，正文按需） | 85%–95% | 技能/插件常驻开销 |
| 脚本外置（资源层零占用） | 95%–98% | 工具逻辑、模板、长规则 |
code_graph.py 替代整仓读取 |
96%–98% | 代码结构探查 |
file_search.py 替代整文件读取 |
90%–97% | 大文件内容定位 |
| 紧凑 JSON 替代自然语言输出 | 60%–80% | 所有工具返回值 |
| 滑动窗口 + 摘要压缩 | 70%–90% | 长对话、多轮迭代 |
| 多 Agent 流水线拆分 | 80%–92% | 复杂长链路任务 |
| 决策阶梯（Ponytail） | 代码行 -54%~94%（过度工程陷阱） | 前端迭代 / 原型 / 易过度工程任务 |
| 语义图谱（CodeGraph） | Token -47%~64% / 工具调用 -58%~81% | 大仓结构探查、影响面分析 |
综合叠加后，典型任务实测降幅落在 90%–98% 区间。
六、脚本用法
# 按正则定位内容，带上下文，最多 5 个匹配
python3 scripts/file_search.py --file <path> --pattern "<regex>" --before 2 --after 2 --limit 5
# 扫描目录，输出函数/类/接口符号表（含 async def / async function）
python3 scripts/code_graph.py --path <dir_or_file> --ext ".py,.ts,.tsx" --top 50
# 写代码前先跑复用检查：仓库里是否已有 parse/date 之类实现
python3 scripts/preflight.py --task "parse date string" --path <dir>
# 语义图谱：完整符号 + 边（calls/imports/extends）
python3 scripts/code_graph.py --path <dir> --mode graph
# 影响面分析：谁（传递地）调用了 target_fn
python3 scripts/code_graph.py --path <dir> --mode callers --symbol target_fn
python3 scripts/code_graph.py --path <dir> --mode callees --symbol target_fn
python3 scripts/code_graph.py --path <dir> --mode impact --symbol target_fn
