TokenWise · Dev（开发全链路省 token）
这是什么 / 为什么有用（先看值不值）
省 token = 省钱。 开发是 token 消耗的大户——改接口读全文件、报错贴全文、问进度重读长对话、找代码全仓库翻……每一项都在烧钱。
TokenWise · Dev 让开发中的每次读取只覆盖当前任务真正需要的范围：改一个小点不读整个文件，问进度不重读长对话，模型选型直接给你挑省钱的用。项目文档和目录怎么规整，一句话就能交代清楚。
实测省 token（2026-08-12 真实项目对照）：
- 问"项目做到哪了"：通篇重读 19,899 token → 定向读取 532 token，省 97%
- 模型越贵省得越多：同样的 token 量，高级模型省钱金额成倍放大
安装方法
解压 → 复制整个文件夹到你的 AI 工具技能目录 → 重启会话，说一句"我们做到哪了"，正常返回即安装成功。各工具的具体路径见随包 INSTALL.md（3 步约 1 分钟）。
适配 AI 工具（能装 / 不能装）
| AI 工具 | 适配 | 做法 |
|---|---|---|
| WorkBuddy | ✅ 原生适配 | 复制到 ~/.workbuddy/skills/，对话直接触发 |
| CodeBuddy / Claude Code | ✅ 支持 | 复制到对应 skills 目录 |
| Cursor | ✅ 支持（新版） | 放入 .cursor/skills/ |
| Trae | ✅ 完整适配（实测） | 完整包放进 ~/.trae-cn/skills/<技能名>/（目录名=SKILL.md 的 name）；或核心纪律抄入 ~/.trae-cn/user_rules/ 常驻生效 |
| 纯聊天 AI（网页/App） | ⚠️ 降级可用 | 粘贴随包说明为"自定义指令" |
| 非 AI 工具 / 开发引擎 | ❌ 不适用 | 这是 AI 对话流程型技能 |
怎么用（纯对话触发）
- "我们做到哪了" / "这个 bug 之前怎么解决的" / "退款逻辑在哪" / "改这个接口会影响谁"
- 什么时候说（照场景对号入座）： 新会话问进度→"我们做到哪了"；忘 bug 修法→"这个 bug 之前怎么解决的"；找代码→"XX 逻辑在哪"；改接口怕改 A 炸 B→"改这个接口会影响谁"；文档太大每次被全文读→"把项目说明拆成按需文档"。日常开发不说不触发词也自动生效，说触发词只是把它拉回正轨。
- 开发会话中自动生效；新项目初始化流程见随包
engine/README.md，纪律落地模板见随包examples/CODEBUDDY.md
装完怎么验证（30 秒自检）
- 说"我们做到哪了"——正常返回 = 装好了
- 问"退款逻辑在哪"——回答带文件路径+行号（不再全仓库翻）= 机制生效
- 改接口时先给出影响面清单（调用方+文档+测试）= 已在省 token
- 每次回答末尾有合规自检标记（读了哪些文件/行号 + 省了多少 token）= 纪律可肉眼核验
- 机械验证安装完整性：跑
node engine/selfcheck.js，10 项校验全过（文件齐 / 元信息合法 / 版本一致 / 引用不断链 / 描述合规 / 章节完整 / 容错协议六维 / 高危识别清单 / 一键初始化 / 三件套实跑可生成）= 包本身没问题
一键初始化（30 秒开干，不用手工建文件）： 跑 bash examples/init.sh <项目根目录> <项目名>，一次生成三件套 —— CODEBUDDY.md（纪律常驻，免触发词）+ dev-state.md（状态：做到哪了/下一步/卡点）+ code-map.yaml（代码地图：改哪个模块影响谁）。急着开干加第三个参数 minimal，只建 CODEBUDDY.md 也能生效。已存在的文件不会被覆盖（幂等），填过的内容不会丢。
> 找不到文件？先看顶层 INDEX.md —— 按需求直达各文档，并说明每个主题的唯一事实源（避免同一规则两处措辞不一致）。
稳定性与可观测性设计（为什么可靠，不只靠自觉）
纯对话技能没有引擎强制，但用五道机制把"会不会跑偏"变成可预期、可核验：
- 收敛协议（最多 1-2 次补问）：判定不出读哪 → 最多补 1 问（跨多项目允许 2 问：一次锁项目、一次锁模块）；上下文出现 ≥2 个项目名自动按
[项目名]锁域，不再追问。 - 确定性兜底输出：每次回答末尾带合规自检标记（读了哪些文件/行号 + 省了多少 token）——没写具体出处 = 疑似通篇读，一眼可指正。
- 降级链（命中即停）：触发词未命中 → 最小上下文读起（README/dev-state/索引）→ 以代码为准 → 标准话术交代；任何一步生效即停，不扩散。
- 高危不省 token：改接口影响面、git 破坏性操作、删代码等高危场景不省上下文，先给影响面/确认再动手。
- AI 不遵守二次确认：检测到明显通篇读（无出处/读域外文件）自动输出固定提示并停止，反复违反写进项目 CODEBUDDY.md 常驻生效。
高危场景自动识别（不靠用户提醒，v1.9.0 新增）
上面第 4 条"高危不省 token"此前依赖你主动指正。现在改成自动识别：问题或上下文命中下列任一类，立即切换为「不省 token 模式」——先给影响面/确认再动手，且不允许为了省 token 跳读依赖：
| 高危类别 | 识别信号（命中即触发） | 该做什么 |
|---|---|---|
| 接口/契约变更 | 改接口、改签名、加参数、返回值变化、改 API | 先列调用方 + 文档 + 测试清单，再动手 |
| 破坏性版本操作 | git 回滚/rebase/强推、分支合并、tag 打错 | 先确认影响范围与可回退点 |
| 删除/清理代码 | 删文件、删函数、删依赖、重构移除 | 先确认引用方，避免误删仍在用 |
| 数据/结构迁移 | 迁移、换库、表结构变更、数据清洗 | 先备份路径与回滚方案 |
| 依赖升级 | 升版本、换包、改 lockfile | 先查破坏性变更与兼容范围 |
误判代价不对称：该省的时候多读一点只是多花几分钱，该不省的时候省了可能出事 —— 所以识别偏保守，宁可多给影响面。
技术层兜底（可运行，不靠自觉）
上面的机制是"行为约定"，下面这条是可执行的技术保障——即使 AI 完全不遵守规则，安装态本身的完整性依旧能被机械验证：
node engine/selfcheck.js # 人类可读报告；退出码 0=通过 / 1=有问题
node engine/selfcheck.js --quiet # 纯 JSON，可进 CI
自检 10 项（错误码 TWD-E001~E010）：必需文件齐全 / frontmatter 合法 / 版本号跨文件一致 / 文档引用不断链 / description 长度合规 / 关键章节存在 / 容错协议六维齐全 / 高危场景识别清单存在 / 一键初始化路径在位 / 一键初始化三件套可实跑生成（含幂等）。每项失败都给出明确错误码 + 具体修复动作，不静默通过。这是本技能的"技术层错误恢复"：问题发生时可被主动发现并定位，而非等用户撞上；同时把「稳定性写在文档里」升级为「稳定性被机械校验」。
容错协议（形式化：超时 / 重试 / 幂等 / 熔断）
把"重试与恢复"从隐含习惯变成显式规则，任何一步都不靠临场判断：
| 维度 | 规则（写死，不自由发挥） |
|---|---|
| 超时（收敛） | 单次任务读取轮次上限 3；第 3 轮仍未收敛 → 停止检索，输出已有结论 + 明示"信息不足，需你补一句" |
| 重试 | 判定失败仅重试 1 次（跨多项目放宽到 2 次：先锁项目、再锁模块）；第 2 次仍失败即降级，不无限追问 |
| 幂等 | 同一问题 + 同一主题域 + 同一 dev-state → 输出结构一致（三段式固定：结论 / 读了什么 / 省了多少）；结论不因重跑而漂移 |
| 熔断 | 检测到 AI 明显违规（读域外文件 / 无出处作答）→ 立即停止当前检索，输出固定提示，本轮不再尝试；重复违反升级为 CODEBUDDY.md 常驻规则 |
| 降级顺序 | 触发词未命中 → 最小上下文读起 → 以代码为准 → 标准话术交代；命中即停，不扩散为全仓库扫描 |
| 不可省 token 场景 | 改接口影响面 / 删除或迁移代码 / git 破坏性操作 —— 这些场景禁止走省 token 路径（安全 > 省钱） |
异常标准话术（先给这句再给路，不自由发挥）：
| 场景 | 用户可见提示（一句话） |
|---|---|
| 索引/code-map 缺失 | "没找到项目地图，我从最小上下文读起，顺手补建" |
| 判定失败（不知读哪） | "信息不足，最多补 1 问：你指的是哪个模块/哪段逻辑？" |
| 被指正通篇读 | "确实读了域外文件，重来——只读 <主题域>，带出处" |
| 矫枉过正（跳过必要分析） | "高危场景不省 token：改接口影响面/删代码我必须读全" |
| 多项目串域 | "这是 A 项目的问题，我用 A 的 dev-state 答，不混 B 的" |
> 完整错误码 TWD-E001~E010 与全部标准话术见随包 engine/README.md §10。
边界与承诺（诚实原则）
- 纯对话型流程技能：无引擎、无终端、无依赖，不联网、不采集数据，安全可审计
- 省的是实打实的 token 量；省钱金额取决于模型单价（便宜模型单次省几分钱，贵模型成倍放大）
- 它改变 AI 的"读取习惯"，不改变 AI 的"能力"
- 什么时候该用/不用（一句话判据）： 问题里带"项目/代码/开发进度/接口/bug"→ 用它；带"页面质量/文案质量/日常回忆"→ 它不是干这个的（UI 质检找 ui-quality-inspector、文案体检找 ai-content-qc、日常上下文找 TokenWise · Daily）
- 拆分阈值是明确的： 单个文档 >3000 字/行 → 拆，每份 500-1500 字为宜；没到阈值不拆，直接定向读（不为你省 token 反烧 token）
- 触发词没命中 / 项目没状态文件 / AI 走偏时，走预置降级预案 + 标准错误话术（索引缺失/判定失败/被指正/矫枉过正时 AI 固定说什么，见随包
engine/README.md），不自由发挥；高频问题、误触发澄清与故障排查详见随包references/faq.md
完整实现（唯一事实源）
> 本包完整实现细节（机制、规则、落地流程）见随包 engine/README.md——安装后即可查看。
> 可运行自检见 engine/selfcheck.js；全局文件导航见随包 INDEX.md。
快速对照表（一图判边界 / 选触发词）
边界一句话判据： 问题里带「项目 / 代码 / 开发进度 / 接口 / bug」→ 用它；带「页面质量 / 文案质量 / 日常回忆」→ 它不是干这个的（UI 质检找 ui-quality-inspector、文案体检找 ai-content-qc、日常上下文找 tokenwise-daily）。拆分阈值：单文档 >3000 字/行才拆，每份 500-1500 字，没到不拆。
触发词 × 场景对照：
| 说这句 | 对应场景 | 期望返回 |
|---|---|---|
| 我们做到哪了 | 新会话问进度 | 定向读取状态，不重读长对话 |
| 这个 bug 之前怎么解决的 | 忘历史修法 | 指向当时结论 + 文件位置 |
| XX 逻辑在哪 | 找代码 | 文件路径 + 行号，不全仓库翻 |
| 改这个接口会影响谁 | 改前影响面评估 | 调用方 + 文档 + 测试清单 |
| 项目 token 优化 | 主动要省 | 给出本项目可落地的省 token 动作 |
> 完整错误码（TWD-E001~E010）、AI 不遵守二次确认的固定提示、多项目补问锁域策略，见随包 engine/README.md §10。
