@huicai/cli 2026.814.0 → 2026.1021.0

package/skills/arch-diagram/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "arch-diagram",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "帮我画一张系统总体架构图",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "根据源码出一套部署拓扑和时序图",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "把这个方案画成业务流程图",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一份 PPT 汇报材料",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一段前端组件的样式",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/arch-distributed/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "arch-distributed",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "跨服务事务怎么设计，要不要上 TCC",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "分布式 ID 怎么生成，时钟回拨怎么办",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "要不要上分布式锁，数据不一致怎么排查",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一次单机 JVM 调优",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "设计一张宽表的分区策略",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/arch-multitenant/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "arch-multitenant",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "SaaS 多租户怎么做数据隔离，共表还是分库",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "大客户要独立部署，租户定制边界怎么定",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "noisy neighbor 怎么做配额治理",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "设计一个用户登录的鉴权流程",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "做一次缓存穿透的防护",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/audio-brief/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: audio-brief
+description: 把文稿改写成口播稿并合成音频简报（日报/周报/监视简报转成能在路上听的音频）。当用户说"念给我听/做成音频/语音播报/路上听/生成播客/口播稿"，或要求定时任务的产出附一份音频时使用。
+version: 1.0.0
+---
+
+# 音频简报：把要看的东西变成能听的东西
+
+自动化任务每天产出日报、周报、监视简报，而这些东西的阅读场景恰恰是**上班路上、会议间隙**——
+两个不方便看屏幕的场景。这个技能把已有的文字产出加一路音频输出。
+
+**它是文字简报的附加物，不是替代物。**音频不可检索、不可引用、不能跳读，
+文字版必须照旧产出。
+
+## 两步走，分工不能混
+
+| 步骤 | 谁做 | 为什么 |
+|---|---|---|
+| ① 把文稿改写成**口播稿** | **你（模型）** | 需要判断哪些能省、数字怎么读、段落怎么过渡 |
+| ② 切分 → 逐段合成 → 拼接 | **内核工具** | 纯确定性工作，交给模型编排只会每次做法都不一样 |
+
+不要自己写循环去调 TTS，也不要让用户手动拼音频。
+
+## 第一步：改写口播稿
+
+**直接把 Markdown 丢进 TTS 是不行的**——听众会听到「井号井号 三 本周概况」「星号星号 重点 星号星号」。
+清理标记内核会做，但**语体**要你改。六条规则：
+
+1. **短句**。书面语一句能套三个从句，听觉一次只能装一个意思。见到长句就断开。
+2. **数字读法**。`23.5%` 写成「百分之二十三点五」；`2026-08-20` 写成「八月二十号」；
+   `¥1,234,567` 写成「一百二十三万四千多」——**听众记不住精确到个位的大数**，播报要给量级。
+3. **去掉纯视觉元素**。表格改叙述（「三个部门里销售部涨得最多」），图表引用改结论，
+   链接直接删（念一串 URL 是灾难）。
+4. **补过渡**。文字靠标题分节，语音没有标题。段落之间要有「先说第一件事」「接下来是本周的异常」
+   这类路标，否则听众三十秒后就不知道听到哪了。
+5. **开头一句话说清这是什么**。「这是八月二十号的经营日报，一共三件事。」
+   听众按下播放时没有屏幕给他上下文。
+6. **结尾给行动**。「需要你今天确认的是第二件事。」听完不知道要干嘛的播报等于没听。
+
+**长度纪律**：口播稿控制在原文的三到五成。一份两千字的日报，口播稿六百到一千字（约三到五分钟）。
+超过五分钟的播报没人听得完——宁可只播「今天最要紧的三件事」，也不要把全文念一遍。
+
+## 第二步：合成
+
+改写完的口播稿交给内核工具合成。工具会：按句切分（默认每段 400 字）→ 逐段调 TTS →
+按序拼接成一个音频文件。三条内建纪律：
+
+- **超上限直接拒绝**，不静默截断（默认 120 段，约四万八千字）。
+  用户以为整份都念了、实际只念了三分之一，比明确报错糟得多——他不会去核对音频长度。
+- **任一段失败即整体失败**，不返回半截音频。一段没合成上的播报听起来只是「跳了一句」，
+  听的人根本不知道自己漏了什么。
+- **不支持 wav / pcm**：每段自带文件头，裸拼只有开头能播，故直接拒绝而不是给一个坏文件。
+
+## 什么时候不要用
+
+- **需要引用、需要检索、需要跳着看的内容**——那是文字的活。
+- **一次性的短回答**（几十个字）：交互式朗读就够了，不必走这条链路。
+- **默认给所有定时任务加音频**：一份日报要几十次 TTS 调用，按次计费。
+  应当由用户对**特定任务**显式开启。
+
+## 与其它技能的接力
+
+- 上游：`office-automation`（定时产出日报/周报）、`meeting-minutes`（纪要）、
+  `data-report-pro`（数据简报）——它们出文字，本技能出音频。
+- 投递：音频作为交付物落盘；要发给别人走通知中心的邮件渠道（附链接，不要附几 MB 的音频体）。

package/skills/audio-brief/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "audio-brief",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "把这份日报念给我听，路上听",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "做成音频简报，生成口播稿",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "定时任务的产出附一份语音播报",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "把这段文字翻译成英文",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份会议纪要",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/audit-assist/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "audit-assist",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "帮我做审计抽凭和穿行测试",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "年审底稿和函证怎么管理",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "内控测试的实质性程序怎么设计",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一次税务汇算清缴",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份投资尽调报告",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/audit-chain/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "audit-chain",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "年审从头配合到出报告，整条链怎么走",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "外部检查要应对，整条审计链怎么排",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "这条舞弊线索要查到底，流程怎么排",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "帮我做审计抽凭和穿行测试",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份税务申报说明",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/banking-credit/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "banking-credit",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "写一份授信调查报告",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "这家借款企业的偿债能力和现金流覆盖怎么测算",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "贷后检查要看哪些，担保怎么分析",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一份上市辅导材料",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "设计一个风控规则引擎",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/brand-design/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "brand-design",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "帮我写一份设计需求 Brief",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "品牌起名怎么评估，VI 规范怎么定",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "品牌设计稿评审要看哪些点",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "画一张系统架构图",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份新媒体内容日历",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/business-plan/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "business-plan",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "帮我写一份商业计划书",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "路演给投资人讲的故事怎么组织",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "市场规模怎么测算，商业模式画布怎么填",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "写一份项目立项申请",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "做一次财务报表分析",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/capital-ops/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "capital-ops",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "做一次投资测算和融资尽调准备",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "增资减资流程，ESOP 股权激励怎么落地",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "公司要注销清算，流程是什么",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "写一份授信调查报告",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "做一次月度结账",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/cicd-pipeline/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "cicd-pipeline",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "CI 老红，构建慢，流水线缓存怎么优化",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "流水线怎么 as code，密钥怎么不裸奔",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "runner 排队严重，矩阵并行和测试分片怎么配",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "写一份发布检查清单",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份 SQL 慢查询优化方案",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/code-archaeology/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: code-archaeology
+description: 代码考古——翻 git 历史重建「这段代码当初为什么被加进来」：引入提交、历次改动性质、常一起改的文件、当前归属、以及提交信息里的意图线索（工单、事故、性能、安全、兼容）。当用户问"这为什么在这儿/当初为什么这么写/这段历史遗留还需要吗/能不能删掉/这个兼容分支的来历/谁最清楚这块"时使用。注意：问「这段代码在做什么」是讲解现状，不归本技能。
+version: 1.0.0
+---
+
+# 代码考古
+
+看到一段看不懂的判断、一个没人解释过的魔数、一段标着「临时」却活了三年的兼容代码——
+最常见的两种处置都是错的：照着现状硬猜一个理由，或者干脆删掉试试。
+
+答案通常一直躺在 git 历史里。这个技能负责把史料翻出来。
+
+## 何时使用
+
+- 看到一段看不懂的代码、兼容分支、魔数
+- 要决定「这段历史遗留还能不能删」
+- 接手陌生模块，想知道该问谁
+- 用户问「这为什么在这儿」「这还需要吗」
+
+## 怎么用
+
+1. 调 `code_archaeology`，给文件路径；只关心某一段就带上 `from`/`to` 行号。
+2. **先读史料，再下结论**。看四样东西：
+   - **引入提交**：当初是为了什么加的
+   - **改动性质分布**：全是 fix 说明这块一直在出问题；全是 refactor 说明形态还没稳定
+   - **意图线索**：工单号、事故、性能、安全、兼容——这些是「当时确实有个具体缘由」的证据，值得顺藤摸瓜
+   - **伴生文件**：反复同改意味着隐式耦合，改这个多半也得看它们
+3. 给结论时**必须把推断的部分标出来**（见下）。
+
+## 一条不可让步的纪律：史料 ≠ 推测
+
+git 给的是**事实**：谁、何时、改了什么、提交信息怎么写的。
+「为什么」几乎总要靠推断。两者必须在你的回答里分开：
+
+- ✅「引入提交写的是『修复 #77 的越界』，**据此推测**这个边界判断是为了防越界」
+- ❌「这个边界判断是为了防越界」
+
+把推测写成事实，是考古这类工作最容易造成的伤害——后来的人会拿着一个编出来的理由去做决定，
+而那比不知道更糟。**线索不足时就如实说「历史里看不出来，建议问 XXX」**，不要硬编一个说法。
+
+同理，`当前归属` 回答的是「现在谁的代码最多」，**不等于「谁最懂」**——
+一次格式化就能让某人变成全仓最大归属者。它是问人的起点，不是结论。
+
+## 与决策图谱合流
+
+考古得出的结论可以写进决策图谱（`record_decision`），让时间线向前延伸到工具启用之前。
+写入时**必须**标明它是事后推断而非当时记录（工具已自动置 `origin: archaeology` 并降低置信度）——
+「当时真的记下来的」与「事后从历史里推出来的」混在一起，图谱的可信度就毁了。
+
+## 边界
+
+- 只读 git 历史，不改任何文件。
+- 历史被压扁过（squash / 仓库迁移）时线索会很薄，此时如实说明，不要拿三条提交硬编一个故事。
+- 它不审代码质量（那是 `code-review`），也不判断改动范围（那是 `scope-creep`）。

package/skills/code-archaeology/trigger-cases.json

@@ -0,0 +1,9 @@
+{
+  "cases": [
+    { "id": "why-here", "prompt": "这个边界判断为什么在这儿，当初是为了解决什么", "shouldTrigger": true },
+    { "id": "legacy-removable", "prompt": "这段历史遗留的兼容代码还需要吗，能不能删掉", "shouldTrigger": true },
+    { "id": "who-knows", "prompt": "这块谁最清楚，我想问问它的来历", "shouldTrigger": true },
+    { "id": "explain-what", "prompt": "这段代码是干嘛的，帮我理解一下逻辑", "shouldTrigger": false },
+    { "id": "review-quality", "prompt": "帮我审查一下这段代码有没有问题", "shouldTrigger": false }
+  ]
+}

package/skills/code-quality/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: code-quality
+description: 代码体检与自查自修：code_inspect 机器排查代码质量——空捕获吞异常、注释与实现对不上、Java 事务失效与代理陷阱（@Transactional 落私有方法/同类自调用/吞异常不回滚）、BigDecimal 精度、圈复杂度与函数过长、重复代码块、console.log 调试残留、测试 .only 残留与断言恒真、缺单元测试覆盖、硬编码密钥与 SQL 拼接；五类可自动修，逻辑与安全类报给人改；test_plan 在补单元测试前算清该测几条路、哪些边界、用什么框架。刚写完或改完代码后自查逻辑与注释、清理调试残留、补单测、交付前把关时载入。
+version: 1.0.0
+---
+
+# 代码自查自检自修
+
+**代码的事故和文档的事故不一样**：文档出问题是看得见的（文字出框、编号跳号），
+代码出问题是**看起来很对**——注释写着 `@param userId`，函数三个月前已经改叫 `id`；
+`catch` 里空着，线上故障被静默吞掉；测试里留了个 `.only`，CI 从此只跑一个用例还一直是绿的。
+
+这些东西不会在保存时报错，评审时一眼扫过去也像对的。
+**AI 生成的代码尤其如此**：流畅、成体系、命名漂亮，那种"顺滑感"会让评审的人放松警惕。
+所以自查不能靠"再读一遍感觉没问题"，要靠机器过一遍。
+
+## 用法
+
+```
+code_inspect(path)                      # 体检（不给 path 则整个工作目录）
+code_inspect(path, only="logic,security")   # 只看某几类
+code_inspect(path, fix=true)            # 顺带自动修那五类
+code_inspect(path, strict=true)         # 交付前把关：建议项也提升为必修
+test_plan(path)                         # 写单测之前：先算清该测什么
+```
+
+规则全表随时可查（从实现里现取，不会与文档漂移）：
+`python3 skills/code-quality/scripts/code_check.py --rules`
+
+**改完代码就跑一次**，别等用户问。回合收尾时系统会对你改过的源码自动体检一遍，
+有必修项会打回来要求修完——与其被打回，不如自己先查。
+
+## 七类规则怎么读
+
+| 类 | 抓什么 | 为什么它值得一条规则 |
+|---|---|---|
+| **logic** 逻辑 | 空捕获、恒真条件、条件里写了 `=`、自我比较、死代码、可变默认参数、循环内 await、Java 用 `==` 比字符串、浮点比相等 | 这些是**会出事**的，不是风格问题 |
+| **comment** 注释 | 文档写的形参函数里没有、说有返回值却从不返回、文档名字是从别的函数抄来的、被注释掉的死代码、无主 TODO | **过期的注释比没注释危害大**：它让下一个读者基于错误前提改代码 |
+| **readability** 可读性 | 函数过长、嵌套过深、圈复杂度、参数过多、魔法数字 | 阈值是"该停下来看一眼"的信号，不是"必须拆"的判决 |
+| **structure** 结构 | 重复代码块、硬编码本机路径、调试输出残留 | 重复=改的时候要记得改两处，而人总会忘一处 |
+| **test** 测试 | `.only` 残留、恒真断言、没有断言的测试、公共函数无覆盖 | 一个恒真断言让整个用例变成装饰品 |
+| **security** 安全 | 硬编码密钥、SQL 拼接、命令注入、eval、弱随机做令牌 | 误报代价高，所以每条都带排除；报出来的基本都值得看一眼 |
+| **consistency** 一致性 | 同名函数在多处签名漂移 | 单文件看不见，它只有把多个文件放一起才成立 |
+
+严重度三档：**必修(error)** 会出事或会骗人 · **建议(warn)** 该改但不拦交付 · **提示(info)** 风格偏好。
+
+**必修项清零之前不要说「已完成」。**
+
+## 分语言专属规则（Java 33 · Python 30 · JS/TS/Vue 20 · C# 20）
+
+通用七类对所有语言都跑，此外每种主力语言另有一组**专属规则**——
+它们的共同点是通用规则一条也看不见，却恰恰是各自语言里最会出事的地方：
+
+- **Java**：@Transactional 落私有方法/未配 rollbackFor/吞异常/事务内起线程、
+  **同类自调用 @Transactional·@Async**（走 this 不走代理，注解等于没写）、
+  BigDecimal 双坑、static SimpleDateFormat、MyBatis `${}`；
+- **Python**（走真 AST，判得最准）：类属性共享可变、闭包捕获循环变量、
+  **`except` 顺序错致子类分支永不执行**、生产代码用 assert、`open()` 无 encoding、
+  pandas 链式赋值与读表不指定 dtype（**事故不改外观、只改数字**）；
+- **JS/TS/Vue**：`.forEach(async …)`、`a?.b.c` 只防了第一层、`x === NaN`、
+  `as any` 与 `@ts-ignore`、**v-for 无 :key / v-if 与 v-for 同元素 / v-html**、
+  直接改 props、解构 reactive；
+- **C#**：**`async void`**（异常无人能接）、**`.Result`/`.Wait()`**（必然死锁，本地却测不出）、
+  **`throw ex;`**（重置堆栈，正确写法 `throw;` 反而更短）、`DateTime.Now`、`double` 算钱、
+  `lock(this)`、LINQ 多次枚举、DbContext 注册成 Singleton、`async void` 测试方法。
+
+细表见 `references/languages.md`；完整清单随时从实现里现取：
+`code_check.py --rules`（规则文件是动态发现的，不会与文档漂移）。
+
+## 能自动修的只有五类——其余为什么不能
+
+`fix=true` 只动这五样：`.only` 残留、行尾空白、被注释掉的死代码、调试输出、空 `finally`。
+共同点是**改完行为要么不变、要么是恢复本该有的行为**。
+
+两条看着能自动修、但**刻意不修**的：
+
+- `a == b` → `a === b`：**会改变行为**。`"1" == 1` 为真，`"1" === 1` 为假。
+  代码若正依赖松散比较，一键修完当场出故障。
+- `count = count;` 删掉：看着无害，但它多半是**漏写了 `this.`** 的现场证据。
+  删掉等于把线索抹了，bug 还在，只是再也查不到。
+
+逻辑、注释与实现不符、缺测试、安全——这几类工具一律不碰，报给你，**你来判断怎么改**。
+一个会自动改坏代码的修复器比没有修复器危险，因为人会停止复核它的改动。
+
+## 注释是怎么骗人的
+
+体检里最有价值的一条是 `comment.param-mismatch`：文档里写的形参，函数签名里根本没有。
+它几乎总是同一个故事——**形参改过名，注释没跟着改**。
+
+写注释时记住分工：
+- **代码写「做什么」，注释写「为什么」**。把代码念一遍的注释（`// 设置 name` 配 `user.name = x`）等于噪声，体检会报。
+- 在每个**转折处**写一句：为什么选了这个方案而不是那个、绕开了哪个坑、这段的前提是什么。
+- 改了签名就改文档，两者是一份东西的两半。
+
+## 写单测：先算清该测什么
+
+直接开写的产出通常是一堆"调一次、断言不为 null"——覆盖率上去了，缺陷一个也拦不住。
+原因是没先回答"这个函数到底有几条路、边界在哪"。
+
+`test_plan(path)` 把这部分算出来给你：
+
+- 哪些对外函数测试里从没出现过（按圈复杂度排序，**分支多的先补**）
+- 每个函数至少需要几个用例才能覆盖各分支
+- 每个参数该试哪些边界（按名字推断：`orders` 试空数组、`amount` 试负数与零、`deadline` 试时区边界）
+- 有没有异常路径 / 异步失败路径 / 需要替身的外部依赖
+- **这个项目的框架、测试目录、命名约定、参照文件**——照着既有约定写，不要自创一套
+
+写完再跑一次 `code_inspect`：恒真断言、没有断言的用例、`.only` 残留归那边管，
+而这三样正是写测试时最容易顺手留下的。
+
+**警惕自证循环**：你同时写实现和测试时，测试会"验证"你的实现——包括错的部分。
+正路是先定验收用例（或让人审你起草的用例），再写实现。
+
+## 误报怎么办
+
+确认某一条确实是误报，就地豁免：
+
+```js
+// code-inspect-ignore: security.command-injection cmd 来自内部白名单，已核实
+return execSync(`command -v ${cmd}`);
+```
+
+不写规则名则豁免该行全部规则。**顺手写下理由**——豁免是一条决定，
+下一个读到它的人（和下一次的你）需要知道这个决定的依据。
+
+但先想清楚：这一条真的是误报，还是你不想改？把真问题豁免掉，这个工具就白装了。
+
+## 自己写的代码怎么过自己这一关
+
+1. 写完就 `code_inspect(改过的文件)`，别等被打回；
+2. 必修项逐条改，改完**复检确认清零**——"应该修好了"不算；
+3. 建议项看一眼：函数超过 80 行、圈复杂度过 15，多半真的该拆；
+4. 新增对外函数就 `test_plan` 一遍，至少补正常路径 + 一个边界；
+5. 交付前 `strict=true` 再过一次。
+
+**引擎改了必须重跑压测台**：`python3 scripts/code_battery.py 300`
+（反向造缺陷覆盖全部 46 条规则 + 反误报 + 修复闭环 + 正向跑批）。
+只会说"未发现问题"的体检器比没有体检器更糟——它给人一个虚假的"已检查"印象。