@huicai/cli 2026.814.0 → 2026.1019.0

package/skills/qa-api-automation/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "qa-api-automation",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "搭接口自动化框架，断言分几层",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "回归全靠手点，接口用例怎么设计",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "用例老误报，脆弱率怎么治",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一次 UI 端到端自动化的选择器策略",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份测试方案的分层策略",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/qa-mobile-automation/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "qa-mobile-automation",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "搭移动端自动化，Appium 还是原生框架",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "云真机机型矩阵怎么选，弹窗打断怎么办",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "厂商 ROM 差异和弱网注入怎么做",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一次 Web 端 E2E 的并行分片",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一段 App 的启动优化",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/qa-ui-automation/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "qa-ui-automation",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "搭 Web UI 自动化，选择器策略怎么定",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "E2E 老是挂，跑一轮要两小时",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "显式等待和页面对象怎么组织",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一次接口自动化的断言分层",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份移动端云真机方案",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/quant-analysis/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "quant-analysis",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "分析这只股票的收益回撤和夏普",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "算一下 MACD RSI 技术指标",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "策略回测怎么防过拟合",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "做一次投资组合的业绩归因",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份行业研究报告",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/rag-triage/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: rag-triage
+description: RAG 检索问题分诊（12 类失败模式 P01–P12：接地漂移/分块边界/嵌入不匹配/索引陈旧/路由错配/长链漂移/工具未接地/记忆缺失/评测盲区/启动顺序/配置漂移/多租户干扰）。当用户说"知识库答非所问/检索不准/引用的不是原文/明明有资料却说没有/RAG 效果差/换了模型就不对了"时使用，先归类再动手。
+version: 1.0.0
+---
+
+# RAG 检索问题分诊
+
+RAG 出问题时最常见的处置是「加更多上下文」「换个更好的模型」——这两句话对任何症状都成立，
+因此对任何症状都没用。本技能的作用是**先把症状归到一类失败模式上，再谈修法**：
+归错类的修补不但白做，还会掩盖真正的原因。
+
+## 何时使用
+
+- 用户抱怨知识库答非所问、检索不准、引用对不上原文
+- 明明资料在库里却回答「没有依据」
+- 换了嵌入模型/换了库/重新导入之后效果突变
+- 本地好用、线上不准；或某个租户不准、别的租户正常
+
+## 怎么用
+
+1. 先问清三件事，缺一件都容易归错类：
+   - **具体问句**与**期望命中的原文**（不要只说"检索不准"）；
+   - 这批资料是**什么时候、用什么模型**建的库；检索时用的又是**哪个模型**；
+   - 是**一直不准**，还是**某次变更之后**才不准（变更是最强的线索）。
+2. 按下表归到**一个主类**，最多再列两个候选，不要罗列全部十二类。
+3. 每一类都给出**最小结构性修复**——改检索、改索引、改路由、改评测或改基建，
+   而不是「加更多上下文」「用更强的模型」这类放之四海皆准的空话。
+4. 手上有平台权限时，用检索测试接口看一轮真实 `topScore` 分布再下结论；
+   分数分布比任何主观判断都可靠。
+
+## 12 类失败模式
+
+| 编号 | 失败模式 | 典型症状 | 最小结构性修复方向 |
+|---|---|---|---|
+| P01 | 检索幻觉 / 接地漂移 | 答案自信地与检索到的文档相矛盾 | 引文逐字校验 + 拒答闸（本平台见 `CitationGuard`） |
+| P02 | 分块边界或切分缺陷 | 相关事实被切散或截断在不同块里 | 调分块粒度与重叠；开上下文邻块扩展 |
+| P03 | 嵌入不匹配 / 语义与向量距离脱节 | 余弦相似度与真实相关性对不上 | **核对建库与检索用的是不是同一模型同一维度**；各向异性做中心化 |
+| P04 | 索引偏斜或陈旧 | 源数据已更新，索引仍返回旧数据或缺数据 | 增量同步与保鲜；重建索引；核对入库是否静默失败 |
+| P05 | 查询改写或路由错配 | 路由把问题发到了错误的工具或数据集 | 路由判据显式化；低置信回退；本平台见 `QueryRewriter` |
+| P06 | 长链推理漂移 | 多步任务逐渐丢失早先的约束 | 阶段化 + 中间结论落盘；压缩时保住约束条款 |
+| P07 | 工具误用 / 工具未接地 | 工具被以错误参数调用，或调用时无依据 | 工具入参校验；工具结果回填后再要求引用 |
+| P08 | 会话记忆泄漏 / 上下文缺失 | 对话在轮次或会话之间丢失重要事实 | 检查压缩切点是否切断了 tool 配对；长期记忆写入时机 |
+| P09 | 评测盲区 | 系统通过测试但在真实事故上失败 | 用真实坏例建回归集；检索与生成指标**分开测** |
+| P10 | 启动顺序 / 依赖未就绪 | 部署后最初几分钟大量失败 | 就绪探针 + 重试退避；把「向量库未就绪」与「无结果」分开报 |
+| P11 | 配置或密钥跨环境漂移 | 本地能跑，预发/生产不准 | 配置项纳入发布清单；启动时打印生效的检索配置 |
+| P12 | 多租户 / 多智能体互相干扰 | 某个租户不准，或并发时互相串 | 检查库归属过滤是否在**检索层**；缓存键是否带租户维度 |
+
+## 归类要点（最容易归错的三组）
+
+- **P01 与 P03 的区别**：资料检对了但答案跑偏是 P01（下游接地问题）；
+  资料压根没检对是 P03/P02（上游检索问题）。先看检索返回的块**对不对**，再看答案。
+- **P03 与 P04 的区别**：P03 是「分数算得不对」，P04 是「东西根本不在索引里」。
+  拿一段原文**原句**去检索：检得到说明索引没问题（指向 P03），检不到就是 P04。
+- **P05 与 P02 的区别**：换个说法就能检到是 P05（措辞失配）；
+  换任何说法都只能检到半句是 P02（切分把事实切散了）。
+
+详细排查步骤见 [references/triage-playbook.md](references/triage-playbook.md)。
+
+## 边界
+
+- 本技能只做**归类与修复方向**，不替代真实数据上的验证：任何结论都应当用
+  「拿原句去检索」「看 topScore 分布」「对比建库与检索模型」这类可验证的动作确认。
+- 不要一次给出多于三类的判断。归类的价值在于收敛，列满十二类等于没归类。

package/skills/rag-triage/evals.json

@@ -0,0 +1,57 @@
+{
+  "_note": "行为层评测集（第 3 层）。跑法：node scripts/skill-optimize.cjs skills/rag-triage --score-only。这份是**人工撰写**的样板——skill-optimize 首次运行会自动生成一份，但生成的那份务必人工审一遍再用：模型很容易写出「是否专业」这类无法客观判定的标准。",
+  "scenarios": [
+    {
+      "id": 1,
+      "name": "典型：引用了不存在的原文",
+      "input": "知识库问答里，模型给的回答带了引用，但我去原文里搜根本搜不到那句话。怎么查？"
+    },
+    {
+      "id": 2,
+      "name": "边界：换模型后才不对",
+      "input": "之前 RAG 效果挺好的，换了个 embedding 模型之后就开始答非所问了，检索代码一行没动。"
+    },
+    {
+      "id": 3,
+      "name": "干扰项：症状描述含糊",
+      "input": "我们的 RAG 效果不太好，你看看怎么优化一下。"
+    },
+    {
+      "id": 4,
+      "name": "边界：明明有资料却说没有",
+      "input": "文档里明明写了这个流程，问它却说知识库里没有相关内容。"
+    }
+  ],
+  "evals": [
+    {
+      "id": 1,
+      "name": "先归类再动手",
+      "question": "输出是否先给出了一个 P01–P12 中的具体failure 模式编号，而不是直接开始给建议？",
+      "pass": "明确点名了某个 Pxx 分类（可以给出候选，但必须有编号）"
+    },
+    {
+      "id": 2,
+      "name": "结构性修复而非空话",
+      "question": "给出的修复建议是否是结构性的改动（改分块/改检索/改嵌入/加引文核对等），而不是「加更多上下文」「换个更好的模型」这类空话？",
+      "pass": "至少一条建议指向了管道里的某个具体环节"
+    },
+    {
+      "id": 3,
+      "name": "先要证据再下结论",
+      "question": "在症状描述不足以定位时，输出是否先要求补充具体信息（检索命中分、分块大小、嵌入模型等），而不是凭空断言根因？",
+      "pass": "对含糊的描述会先提问或列出需要确认的事实"
+    },
+    {
+      "id": 4,
+      "name": "嵌入不一致要被识别",
+      "question": "对「换了 embedding 模型后变差」这类描述，输出是否指向了建库与检索的嵌入不一致（P03 类）？",
+      "pass": "点出了「入库用的模型/维度与检索时不一致」这条线索"
+    },
+    {
+      "id": 5,
+      "name": "不编造平台组件",
+      "question": "输出提到的平台组件（如引文守卫、查询改写）是否都是真实存在的，没有编造不存在的功能开关？",
+      "pass": "只提到技能正文里出现过的组件名"
+    }
+  ]
+}

package/skills/rag-triage/references/triage-playbook.md

@@ -0,0 +1,75 @@
+# RAG 分诊排查手册
+
+按顺序做，每一步都产出可判定的结论，不要跳步。
+
+## 第 0 步：把症状变成可复现的一条用例
+
+拿到「检索不准」这种描述先别动手，问出三样东西：
+
+- 具体问句（原话，不要转述）
+- 期望命中的原文片段（用户认为答案应该在哪一段）
+- 是一直如此还是某次变更之后
+
+没有这三样，后面每一步都是猜。
+
+## 第 1 步：原句召回测试（分开 P04 与 P03）
+
+把**期望命中的那段原文的一整句**当作查询去检索。
+
+- 检得到，且排第一 → 索引没问题，问题在措辞失配或分数计算 → 转第 2 步
+- 检不到 → 东西不在索引里或索引坏了 → **P04**，去查入库流程是否静默失败、
+  文档是否真的完成了向量化、是否被归属过滤挡掉（后者是 **P12**）
+
+## 第 2 步：措辞替换测试（分开 P05 与 P02）
+
+把用户原问句换成资料里的正式措辞再检一次。
+
+- 换了说法就检到了 → **P05**，措辞失配。修法是查询改写（同义扩展/术语归一/去噪），
+  而不是调阈值
+- 换任何说法都只能检到半句、上下文断在关键处 → **P02**，切分把事实切散了。
+  修法是调分块粒度与重叠，或开上下文邻块扩展
+
+## 第 3 步：模型一致性核对（确认 P03）
+
+这一步经常被跳过，而它是「代码全对但就是不准」的头号原因。
+
+- 建库时用的嵌入模型 / 维度，与检索时用的**是不是同一个**
+- 中途换过模型吗？换了之后**有没有重建索引**（老向量与新查询向量不在同一空间，
+  余弦值毫无意义，但不会报任何错）
+- 维度对不上通常会报错，**同维度不同模型则完全静默**——这是最难发现的一种
+
+确认不一致即 **P03**，修法是统一模型并重建索引，而不是调阈值或换更强的生成模型。
+
+## 第 4 步：分数分布体检
+
+看一轮真实查询的 `topScore` 分布（本平台的检索接口回传该值）。
+
+- 分数普遍很低（如都在 0.3 以下）→ 多半仍是 P03，或语料与提问域根本不匹配
+- 分数分化明显（好的很高、坏的很低）→ 检索是健康的，问题在下游 → 转第 5 步
+- 分数普遍很高但答案不对 → **P01**，接地问题
+
+## 第 5 步：下游接地检查（确认 P01）
+
+检索返回的块**是对的**，但答案不对：
+
+- 答案里的引用能不能逐字回到原文？不能 → 引文校验没开或没生效
+- 提示词里有没有「资料不足时可以用你自己的知识」这类口子？有就是 P01 的源头
+- 证据不足时系统会拒答吗？不会 → 补前置检索闸
+
+## 第 6 步：环境与并发（P10 / P11 / P12）
+
+前五步都正常，问题却只在特定环境或特定租户出现：
+
+- 只在部署后头几分钟 → **P10**，就绪探针与重试
+- 本地好、线上不好 → **P11**，对比两边**生效的**检索配置（启动时打印出来对，
+  不要对配置文件——配置文件不等于生效值）
+- 只有某个租户/某个并发场景 → **P12**，检查归属过滤是否在检索层、缓存键是否带租户维度
+
+## 常见误诊
+
+| 现象 | 容易误判为 | 实际多半是 |
+|---|---|---|
+| 换了嵌入模型后突然不准 | 新模型不好 | P03，老向量没重建 |
+| 明明有资料却说没有 | 阈值太高 | P04 入库失败，或 P12 被归属过滤挡掉 |
+| 答案有细节但都是错的 | 模型能力不够 | P01 接地漂移 |
+| 长文档问答开头准结尾乱 | 上下文不够长 | P06 长链漂移，或 P02 切分问题 |

package/skills/rag-triage/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "rag-triage",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "知识库答非所问，检索不准怎么查",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "明明有资料却说没有，引用的不是原文",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "换了模型 RAG 效果就不对了",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "搭一套检索增强的数据管道",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一段向量库的查询代码",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/real-estate-property/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "real-estate-property",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "测算这个物业的 IRR 和租金回报",
+      "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/refactor-safely/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refactor-safely
-description: 在不改变外部行为的前提下安全重构（拆函数/去重/改名/解耦）。当用户要"重构/优化结构/消除重复/降复杂度/清理代码"时使用。
+description: 在不改变外部行为的前提下安全重构（拆函数/去重/改名/解耦）。当用户要"重构这段代码/重构一下/优化结构/消除重复/降复杂度/清理代码"时使用。
 version: 1.0.0
 ---
 

package/skills/refactor-safely/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "refactor-safely",
+  "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/regression-forecast/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "regression-forecast",
+  "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/release-checklist/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "release-checklist",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "要发版了，上线前检查一遍",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "发布准备和打包发布要注意什么",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "release 前的系统化检查清单",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "定一套发布流程和灰度模式",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一段流水线的门禁配置",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/report-craft/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: report-craft
+description: 写要过评审的报告时载入——可研报告的财务测算（NPV/IRR/投资回收期/敏感性分析）、投资估算表与现金流量表、配数据图表（甘特图/投资构成/累计现金流/龙卷风/风险矩阵）和架构图、功能模块图，从代码库取证项目规模；让可行性研究、立项、结题、技术方案、商业计划书写得专业有说服力：先取证、再测算、再配图、最后成文与自审。
+version: 1.0.0
+---
+
+# 报告写作：让评审信服
+
+一句话：**先取证、再测算、再配图、最后成文；每个数有出处，每张图有用处，每个结论有依据。**
+
+报告写不好，很少是文笔的事。可研基线里的真实翻车：回收期拿收入除总投资（没扣经营成本）、
+「节约 60 万元/年」而被节约的那项支出总共才 22 万元、进度计划整体落在编制日期之前、
+同一份文件里「七个维度」和「五个维度」各说各的、四张图全是流程图而没有一张数据图、
+财务评价没有 NPV 和敏感性。这些都是**流程**出的错：没取证就写、没算就报、没规划图表就动笔。
+
+## 一、流程（顺序不能乱）
+
+| 步骤 | 做什么 | 用什么 |
+|---|---|---|
+| 1 定体例 | 这类文档有哪些必备章节、每节评审看什么 | tech-doc 技能；可研逐章要点见 [references/feasibility.md](references/feasibility.md) |
+| 2 取证 | 列事实清单，分清**已建成（现状）/ 在建 / 计划**三种时态，每条带来源 | `project_facts`（代码库）、`read_file` / `read_document`（已有的需求、设计、方案文档）、用户材料 |
+| 3 测算 | 投资、收入、经营成本、成本节约 → 表、指标、结论句、图表 spec | `fin_model` |
+| 4 图表计划 | 动笔前先列「这份报告要哪些图、哪些表、各放哪一节」 | 第三节 |
+| 5 出图 | 结构图与数据图，同一轮并行调用 | `render_diagram` / `render_chart` |
+| 6 成文 | 按章写 Markdown 草稿（`write_file`）；图写 `![图题](路径)`，表前一行写 `表：表题` | [references/writing.md](references/writing.md) |
+| 7 成稿与自审 | `create_doc`（`markdown_path` + `template`）→ `docx_inspect` → 必修清零、建议逐条过 | [references/review-checklist.md](references/review-checklist.md) |
+
+长报告按章写进**同一份草稿**：第一章 `write_file`，之后每章（或每 3000 字左右）`append=true` 追加。一次塞进上万字会被单次输出上限截断，后半截也必然潦草。
+
+## 二、三条红线（评审一票否决）
+
+1. **时态**。编制日期之后才发生的才叫计划。已经做完的写进「现有工作基础 / 项目进展」，
+   计划从编制之后排。项目已经做了一部分（代码库里有东西）时尤其要分清：
+   可研论证的是「接下来还要投入什么、做成什么、值不值」。`docx_inspect` 会报「进度计划整体早于编制时间」。
+2. **数字同源**。同一个数全文只有一个值：规模数字取自 `project_facts`，财务数字取自 `fin_model`
+   的同一次结果，正文、表、图、摘要一字不差。成稿前 `grep` 关键数（总投资、工期、人数、模块数）核一遍。
+3. **财务口径**。回收期基于净现金流且含建设期；节约额不超过被节约的支出；NPV、IRR、回收期、
+   敏感性四样齐全；悲观情景 NPV 转负就不能写「完全可行」，要写「有条件可行」并写清条件。
+   不心算：`fin_model` 给的结论句和表直接用，改假设就重算，不要手改结果。
+
+## 三、图表计划（可研基线，按项目增减）
+
+**结构图（render_diagram）**：总体架构（layered）、技术架构（layered）、功能模块（tree，`project_facts`
+已给出模块树 spec）、部署架构（layered）、核心业务流程（flow）、关键技术原理（flow / sequence）、
+组织结构（tree）。
+
+**数据图（render_chart）**：投资构成（pie / waterfall）、累计现金流量（line，看回收期）、
+敏感性（tornado）、实施进度（gantt，`today` 填编制日期）、风险矩阵（matrix）、
+市场规模与增长（bar / line，**必须注明数据来源**，没有来源就不画）。
+
+**表**：投资估算表、分年度投资计划、项目投资现金流量表、财务评价指标表、敏感性分析表、
+方案比选表、进度计划与里程碑表、风险登记表、人员分工表、技术指标表（指标 / 现状值 / 目标值 / 测试方法）。
+
+规则：每张图都有一句引出它的正文（「如@fig:arch 所示，……」并说出它说明了什么）；图题用名词短语；
+一张图只讲一件事；数据图不用 `run_python` 手写 matplotlib。结构图**为纸面画**：插进文档的加 `header:false`，
+`render_diagram` 报「打印看不清」就精简节点、拆图，或横排插入（`{#fig:x .landscape}`）。各类 spec 的现成写法见
+[references/visuals.md](references/visuals.md)。
+
+## 四、写得像行家
+
+- 每节第一句就是本节结论；段落按「主张—依据—含义」走。
+- 用数字和对象代替形容词：✗「显著提升对账效率」→ ✓「单次对账从 40 分钟降到 6 分钟（2026 年 7 月 3 家门店试点实测）」。
+- 依据写出来源：「据 backend/pom.xml，后端由 9 个模块组成」「经 fin_model 测算」。
+- **不编造**：人名、职称、客户名单、合同额、市场数据，拿不到就写「［待补：……］」并在交付时列出待补清单。
+  编一个像样的数比留空危险得多——评审一问来源就全盘失信。
+- 一句只讲一件事：超过 60 字、或连着三个以上逗号就拆开（`docx_inspect` 会标长句）。
+- 同一事物全文一个叫法，缩略语首次出现给全称。
+- 不写空话：赋能、助力、打造、全方位、深度融合、显著提升……（`docx_inspect` 的 AI 味会标出来）。
+
+好坏对照与段落范例见 [references/writing.md](references/writing.md)。
+
+## 五、交付说明
+
+交付时说清五件事：文档路径；图表清单（几张结构图、几张数据图、几张表）；测算关键数（总投资、NPV、
+IRR、回收期、最敏感因素）；**待补信息清单**（哪些必须由用户补，如人员、单位资质、合同）；
+`docx_inspect` 的结论（必修几项、建议几项、哪些建议有意保留及理由）。