@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/slides-html/SKILL.md

@@ -7,9 +7,17 @@ version: 1.0.0
 # HTML 幻灯片（桌面端专属管线：HTML → 渲染 → PDF/PPTX/放映页）
 
 原理：每页 = 一个 1280×720 的自包含 HTML；桌面端 `slides_render` 工具离屏逐页渲染——
-产出每页 PNG 缩略图、整份 PDF、整页贴图 PPTX 与键盘翻页的放映 HTML，并把**每页截图注入给你自检**。
+产出每页 PNG 缩略图、整份 PDF、整页贴图 PPTX 与键盘翻页的放映 HTML。
 表现力上限=CSS（渐变/阴影/网格排版），远超 python-pptx 版式。
 
+**自检是两条通道，不要混为一谈**：
+- **机检**（随结果返回的「版式体检」）：在离屏页里跑真实 DOM 度量，报出文字被切多少 px、
+  哪两块文字重叠多少、图片被拉了几个百分点、有没有外链资源没加载。
+  这些是浏览器**算得出来的事实**——必修项为 0 是交付的硬门槛。
+- **看图**（注入的每页截图）：判视觉层次、留白、重点是否突出。这些机器判不了，得你看。
+
+缩略图上「被裁掉半行字」和「本来就排到底」长得一模一样，所以**能算的绝不靠看**。
+
 ## 流程
 
 1. **大纲先行**：逐页大纲（每页=标题+要点+版式选择），页数 8–15，重要汇报先让用户确认。
@@ -18,8 +26,8 @@ version: 1.0.0
 3. **逐页产出**：写 `slides/01-cover.html`、`slides/02-agenda.html`…（两位数前缀定顺序）。
    每个文件 = 模板骨架 + 选定版式片段填入内容；**整页自包含**。
 4. **渲染**：调用 `slides_render`（参数 dir="slides"、name="<中文成品名>"）。
-5. **自检回路（关键）**：对照注入的每页截图过验收清单——溢出/截断/挤压/对比度不足，
-   改对应 html 后**重新渲染**，直到全部合格再交付。
+5. **自检回路（关键）**：先看机检——**必修项不为 0 就不许交付**，按报告里的像素数改对应 html
+   后重新渲染；必修清零后再对照截图看视觉层次与留白。反复直到两关都过。
 6. 交付物：`<name>.pdf`（首选交付）、`<name>.pptx`（整页贴图，**不可编辑文字**——如实告知用户，
    要可编辑版用 pptx-author 另出结构稿）、`<name>-放映.html`（内置浏览器/浏览器全屏演示）。
 
@@ -34,15 +42,22 @@ version: 1.0.0
 
 ## 无 slides_render 工具时（CLI / IDE / 例程环境）
 
-工具仅桌面端注册。此时仍按上述规范产出 `slides/*.html` 并告知用户：
-「在 Work Twin 桌面端打开本目录可一键渲染导出 PDF/PPTX」；或改用 pptx-author 出直接可用的结构稿。
+工具仅桌面端注册（机检也随它一起，没有它就没有 DOM 度量）。此时仍按上述规范产出
+`slides/*.html` 并告知用户：「在 Work Twin 桌面端打开本目录可一键渲染导出 PDF/PPTX」；
+**或改用 `create_deck`（pptx-author）出直接可用的结构稿——那条路自带版式体检，各端都有**。
+
+## 验收自查
 
-## 验收自查（对照注入截图逐页过）
+机检负责（`slides_render` 自动跑，必修必须为 0）：
+- [ ] 文字被切（overflow:hidden 下内容高过容器）、整页溢出、元素超出画面
+- [ ] 文字块互相压盖（按文字实际占位算，不是按容器框算）
+- [ ] 图片变形（`object-fit:fill` + 宽高比≠原图）、图片没加载、图片发虚
+- [ ] 字号 <18px、对比度 <4.5:1、`.slide` 不是 1280×720、引用了外链
 
-- [ ] 无溢出/截断（右缘底缘完整，无被吃掉的行）
-- [ ] 中文全部正常渲染，无缺字方块
-- [ ] 主题一致（同一套配色变量，无串色页）
-- [ ] 每页焦点清晰，文字对比度充足（浅底深字/深底浅字）
+你看图负责（机检判不了的）：
+- [ ] 每页焦点清晰，一眼知道这页在说什么
+- [ ] 留白舒服，不挤不空；主题一致，无串色页
+- [ ] 中文正常渲染，无缺字方块
 - [ ] 已如实告知用户 PPTX 为贴图不可编辑
 
 ## 附件

package/skills/slides-html/trigger-cases.json

@@ -0,0 +1,11 @@
+{
+  "skill": "slides-html",
+  "purpose": "触发行为规格。与 pptx-author 是刻意分层：朴素结构稿走 pptx-author，设计感/发布会级走本技能。",
+  "intentionalOverlap": ["pptx-author"],
+  "cases": [
+    { "id": "fancy", "prompt": "做一套炫酷有设计感的发布会演示", "shouldTrigger": true },
+    { "id": "beautiful", "prompt": "这个 PPT 要好看一点，能不能做出设计感", "shouldTrigger": true },
+    { "id": "near-miss-plain", "prompt": "随便做几页幻灯片把要点列一下就行", "shouldTrigger": false },
+    { "id": "near-miss-webpage", "prompt": "帮我写一个产品官网首页", "shouldTrigger": false }
+  ]
+}

package/skills/sql-analysis/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: sql-analysis
+description: 对数据文件直接跑 SQL（DuckDB）——几十万行的 CSV/Excel/Parquet 筛选、聚合、多表关联、透视，不落库不导入。当用户说"几十万行/文件太大/跑不动/内存爆了/多表关联/对账/join 几张表/用 SQL 查"或表格行数明显超过几万时使用。与 xlsx-analysis 接力：SQL 先把大表压成小表，pandas 再做统计与画图。
+version: 1.0.0
+---
+
+# 用 SQL 查数据文件（DuckDB，经 run_python 执行）
+
+pandas 的模型是**整表读进内存再变换**。几万行很好用；到了几十万行、多表关联、跨月合并，
+它会同时出两个问题——一是内存，二是**模型写出来的代码质量**：
+多步链式变换（merge → groupby → pivot → 再 merge）是最容易写错也最难自查的一类代码，
+错了还不报错，只是数字不对。同样一件事写成一句 SQL，写对的概率高得多，人核对起来也快得多。
+
+DuckDB 直接对**文件**跑 SQL：不建库、不导入、不落盘，一个进程内的分析引擎。
+
+## 什么时候用 SQL，什么时候用 pandas
+
+**别让模型自己猜**，按下表选：
+
+| 任务 | 用 | 为什么 |
+|---|---|---|
+| 筛选、聚合、分组、排序 | **SQL** | 一句话说清，且不必整表进内存 |
+| 多表关联（join）、对账勾稽 | **SQL** | pandas 的多步 merge 最容易错在「关联键类型不一致」「重复行放大」 |
+| 透视（行列转置） | **SQL** `PIVOT` | DuckDB 原生支持，比 pandas 的多层索引好读 |
+| 去重、窗口函数（排名/环比/累计） | **SQL** | 窗口函数是 SQL 的主场 |
+| 统计检验、回归、时间序列建模 | pandas / scipy | SQL 不做这些 |
+| 画图 | pandas + matplotlib | 同上 |
+| 表头不在首行、金额是文本、夹着合计行 | **先 xlsx-analysis 的工具箱洗** | 脏表要先洗再查，见下节 |
+
+**接力是常态**：SQL 把几十万行压成几百行 → 交给 pandas 做统计与画图。
+不要用 SQL 硬做统计建模，也不要用 pandas 硬扛几十万行的 join。
+
+## 先量后算（与绘图引擎同一条纪律）
+
+动手前先看清楚有多大、长什么样，再决定策略——而不是读完才发现读不动：
+
+```python
+import duckdb
+con = duckdb.connect()          # 内存实例，不落盘
+# 1) 摸形状：列名、类型、行数（不把数据读进来）
+print(con.sql("DESCRIBE SELECT * FROM 'attachments/明细.csv'").df())
+print(con.sql("SELECT count(*) AS 行数 FROM 'attachments/明细.csv'").df())
+# 2) 看前几行确认表头识别对了
+print(con.sql("SELECT * FROM 'attachments/明细.csv' LIMIT 5").df())
+```
+
+行数在几万以内、且不涉及多表关联 → 直接回 pandas（`xlsx-analysis`），别为一件小事引一个引擎。
+
+## 直接查文件（不用导入）
+
+```python
+# CSV：自动推断分隔符/编码/类型
+con.sql("SELECT 部门, sum(金额) AS 合计 FROM 'attachments/明细.csv' GROUP BY 部门 ORDER BY 合计 DESC").df()
+
+# 多个文件当一张表（按月拆分的导出最常见）
+con.sql("SELECT * FROM 'attachments/2026-*.csv'").df()
+
+# Parquet（大数据量首选，比 CSV 快一个量级）
+con.sql("SELECT * FROM 'data/*.parquet' WHERE 日期 >= '2026-01-01'").df()
+
+# 多表关联：两份明细按月对账
+con.sql("""
+    SELECT a.月份, a.应收 , b.实收, a.应收 - b.实收 AS 差额
+    FROM (SELECT strftime(日期,'%Y-%m') AS 月份, sum(金额) AS 应收 FROM 'attachments/应收.csv' GROUP BY 1) a
+    FULL JOIN (SELECT strftime(日期,'%Y-%m') AS 月份, sum(金额) AS 实收 FROM 'attachments/实收.csv' GROUP BY 1) b
+      USING (月份)
+    ORDER BY 月份
+""").df()
+```
+
+## Excel 怎么办
+
+DuckDB 读 `.xlsx` 需要额外扩展，**受限网络下未必装得上**。可靠路径是两步走：
+
+```python
+import pandas as pd, duckdb
+con = duckdb.connect()
+df = pd.read_excel('attachments/台账.xlsx', sheet_name='明细')   # 脏表先用 xlsx-analysis 的 smart_read 洗
+con.register('明细', df)                                        # 注册成表，零拷贝
+con.sql("SELECT 部门, count(*) AS 笔数, sum(金额) AS 合计 FROM 明细 GROUP BY 部门").df()
+```
+
+表头不在首行、金额是带千分位的文本、夹着「合计」行——这些**先用 `xlsx-analysis` 的 `smart_read` 洗干净**，
+再 `register` 进来查。脏数据直接进 SQL 只会把脏往下游传。
+
+超大 Excel（几十万行）先转一次 Parquet，之后每次查都快：
+
+```python
+pd.read_excel('attachments/大台账.xlsx').to_parquet('/tmp/台账.parquet')
+con.sql("SELECT ... FROM '/tmp/台账.parquet' ...").df()
+```
+
+## 三条纪律
+
+1. **结果回 pandas 再呈现**：`.df()` 拿到 DataFrame，用既有的表格/图表能力输出。
+   不要把 SQL 的原始打印结果直接贴给用户——列宽和数字格式都不适合人读。
+2. **不落库、不持久化**。DuckDB 在这里的角色是「对文件跑 SQL 的计算引擎」，
+   不是数据库。真要连数据库（MySQL/PG）请走平台的数据源能力，不是这个技能。
+3. **关联前先核对关联键**。多表 join 出错，九成在键上——类型不一致（`'001'` vs `1`）、
+   有前后空格、一对多导致行数放大。join 之后**必须核对行数**：
+   ```python
+   con.sql("SELECT count(*) FROM a").df()   # join 前
+   con.sql("SELECT count(*) FROM a JOIN b USING(k)").df()   # join 后：多出来就是重复放大了
+   ```
+
+## 装不上怎么办
+
+`duckdb` 随扩展包 best-effort 预装；受限网络下可能缺席。
+用 `install_packages(["duckdb"])` 补装；补不上就如实告诉用户「本机装不上 DuckDB，改用 pandas 分块处理」，
+**不要假装跑过**。分块路径见 `xlsx-analysis`。

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

@@ -0,0 +1,34 @@
+{
+  "skill": "sql-analysis",
+  "intentionalOverlap": [
+    "xlsx-analysis"
+  ],
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "几十万行的表跑不动了，内存爆了",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "多张表要 join 对账，用 SQL 怎么写",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "这个 CSV 太大了，pandas 读不动",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "帮我把这张 Excel 做个透视表",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一段 MySQL 的慢查询优化",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/sql-tuning/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "sql-tuning",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "这条 SQL 太慢了，查询超时",
+      "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/statistical-testing/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "statistical-testing",
+  "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": "写一份 AB 实验的样本量计算",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/strategy-planning/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "strategy-planning",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "做战略规划和年度经营计划",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "SWOT 五力和 BCG 怎么用",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "战略解码 BSC 和业务复盘怎么做",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "写一份商业计划书融资材料",
+      "shouldTrigger": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "做一次市场竞品分析",
+      "shouldTrigger": false
+    }
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "skill": "supply-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": "写一份仓库 KPI 报表",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/tax-compliance/trigger-cases.json

@@ -0,0 +1,30 @@
+{
+  "skill": "tax-compliance",
+  "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/tech-doc/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: tech-doc
+description: 研发项目文档体系与归档：项目建议书、可行性研究报告、立项申请书、研发任务书、项目研发实施计划、产品/项目开发需求申请、需求规格与概要/详细设计说明书、测试报告、项目工作总结报告、项目技术总结报告、项目验收报告、项目验收申请表、研发评价总结纪要、变更申请单，以及整套归档的生成与体检。当用户要写这些文档中任何一类，或问"立项材料/验收材料要准备什么/任务书怎么写/研发文档归档齐不齐/做个档案体检"时使用。排版与单文档体检走 docx-author。
+version: 2.0.0
+---
+
+# 研发项目文档体系与归档
+
+分工先说清：**本技能管「这份文件该写什么」与「整套归档齐不齐、对不对得上」**；
+[docx-author](../docx-author/SKILL.md) 管「怎么做成一份合格的 Word」；
+表格件（进度表/预算表/评审报告）走 [xlsx-analysis](../xlsx-analysis/SKILL.md)；
+政府专项申报与预算勾稽走 [project-proposal](../project-proposal/SKILL.md)。
+
+## 一、先认清这是「一份文档」还是「一套归档」
+
+单份文档写得再好，也管不住下面这几件事——它们全是**跨文档的事实**：
+
+> 一个真实项目的 41 份归档件里，项目名称出现三种写法（其中一种在 12 期进度报告里被
+> 统一截断少了一个字）、研发任务书写 ZY202501003 而验收申请表写 ZY202501006、
+> 项目建议书把「联系人/电话/编制人」三栏填串了、12 期月度验收报告一份没交。
+> 每一份单独看都挑不出毛病，摆在一起就全是硬伤——而验收与审计恰恰是摆在一起看的。
+
+所以要写整套项目文档时，**先建档案，再写内容**：
+
+```
+create_project_docs(path='项目文档', card={…})     # 一次生成约 50 份骨架
+… 逐份补正文（或用 card.章节内容 批量注入）…
+docx_inspect(path='项目文档/XX项目')                # 目录 → 档案体检，必修清零
+```
+
+`create_project_docs` 的价值不在省打字，在于**所有文档的封面字段都取自同一张档案卡**，
+上面那四类缺陷因此天然不会发生。
+
+### 项目档案卡
+
+必填六项（它们决定全档一致性，缺了生成出来必然对不上）：
+`项目名称`、`项目编号`、`项目负责人`、`建设单位`、`部门`、`起止时间`。
+
+选填但强烈建议：`联系电话`、`预算`、
+`考核指标` `[[指标, 要求值, 测试方法/判定依据], …]`、
+`人员` `[[姓名, 单位, 职称/职务, 分工], …]`、
+`里程碑` `[[阶段, 任务, 处理人, 工时, 开始, 结束, 交付物], …]`、
+`预算科目` `[[科目, 全年金额], …]`。
+
+给了里程碑，12 期研发进度报告的「项目进度情况」会按里程碑**自动推算当期完成情况**；
+给了考核指标，它会同时出现在立项申请书、研发任务书、验收报告的对照表里——一处定义，处处一致。
+
+## 二、归档规范（编号目录体例）
+
+```
+1-立项文档/  1-项目建议书 2-可行性研究报告 3-立项申请书 4-项目立项的决议
+产品开发需求申请   项目开发需求申请
+5-研发任务书       6-项目研发实施计划
+7-进度表/    1-项目研发进度表-计划 + 实际-第 1~4 季度
+8-XX部XX年度项目研发支出预算表
+9-10验收/    项目验收申请表 项目验收报告 工作总结报告 技术总结报告 研发评价总结纪要
+评审文件/    立项·设计·测试用例·验收·结项 五个阶段 ×（评审报告 + 会议签到表）
+周期性文档/  研发进度报告 ×12   月度验收报告 ×12
+变更文档/    人员/预算/范围/延期变更申请（**发生了才要**，没发生不算缺）
+```
+
+几条硬规矩（都是评审与审计当场会查的）：
+
+- **周期性文档的份数是硬指标**：12 期就是 12 期，缺一期要在档案清册里写明原因；
+- **五个阶段评审，报告与签到表必须配对**——签到表是「会真的开过」的唯一物证；
+- **模板里的「提示：…」块必须删干净**，模板自己写了「正式文档中需删除提示内容」；
+  `XX 部`、`XX 项目`这类占位符同理；
+- 封面信息栏是**表格**不是几行居中文字（只有表格形态才能被工具读出来核对）；
+- 签批栏少一级 = 流程没走完，交上去会被退。
+
+## 三、各类文档最容易丢分的那一节
+
+- **项目建议书**：必要性。写成「技术多先进」就跑偏了——要写「为什么非做不可」：痛点 + 数据 + 政策呼应。
+- **可行性研究报告**：本体例用的是科技计划项目那套十一节（立项背景与意义 / 国内外研究现状 /
+  实施内容·技术关键·预期目标 / 现有工作基础 / 实施方案与组织方式 / 进度安排与年度计划 /
+  承担单位与人员简况 / 经费预算来源与使用计划 / 应用或产业化前景 / 经济社会效益 / 风险分析与对策）。
+  **别套通用可研骨架**，对不上。内容怎么写到评审信服（取证、财务测算、配图、自审）
+  按 [report-craft](../report-craft/SKILL.md)：`project_facts` → `fin_model` → `render_diagram`/`render_chart` → `docx_inspect`。
+- **立项申请书**：考核指标。它是全链条的源头——任务书、进度报告、验收报告都要引它，写虚了后面全废。
+- **研发任务书**：结项条件。指标没有测试方法与环境，同一指标不同环境能差一个量级。
+- **项目研发实施计划**：验收标准和验收工作安排。只有日期没有判定标准，到期只能靠嘴说完成了。
+- **研发进度报告**：审批记录五级（项目经理 / 技术副总 / 财务负责人 / 市场负责人 / 总经理）。
+  财务那一栏问的是「研发经费记录与财务记录是否相符」——这是加计扣除的证据链。
+- **工作总结报告**：完成情况要逐项回答「未完成 / 基本完成 / 全面完成 / 超额完成」，四选一，不许含糊。
+- **技术总结报告**：指标实测数据。只写做了什么不给数据，专家一问就露。
+- **项目验收报告**：五类考核指标对照表（研究内容 / 技术 / 经济 / 社会生态效益 / 科技产出），
+  每类都要「立项书规定 vs 实际完成情况 + 专家审查意见」三栏，
+  专家意见三档：超额或全面完成 / 完成 70% 及以上 / 完成 70% 以下。
+  **完成立项书约定内容 70% 及以上为验收通过**，未达 70% 不通过并应提出终止意见。
+- **表单类**（验收申请表 / 变更申请单 / 需求申请）：失分点几乎全在**字段缺项与签章不全**，不在文采。
+
+## 四、跨文档必须对齐的字段
+
+| 字段 | 贯穿 | 规矩 |
+|---|---|---|
+| 项目名称 | 全部 | 逐字一致，连「的」都不能多。被截断的写法是最高频缺陷 |
+| 项目编号 | 全部 | 一个项目一个编号，任务书与验收申请表对不上是硬伤 |
+| 项目负责人 / 联系人 / 联系电话 | 全部 | 三栏最容易填串（电话填进联系人栏） |
+| 建设单位 | 验收与总结类 | 「公司」还是「公司+部门」，择一到底 |
+| 起止时间 | 立项 / 任务书 / 验收 | 计划与实际分列，延期要有批准文号 |
+| 考核指标 | 立项 → 任务书 → 验收 → 总结 | 指标名、值、测试方法逐字一致；验收要逐条给实测值 |
+| 经费 | 可研 → 立项 → 任务书 → 预算表 → 验收 | 批准 / 到位 / 支出三个口径分别标注，不能混用一个数 |
+
+`docx_inspect(目录)` 会把这几项逐份比对并报出不一致，包括分辨「被截断」与「粒度不同」。
+
+## 五、周期性文档：份数对不等于真的写了
+
+12 期月报交齐了、份数也对，齐全性检查一切正常——但把 12 份摊开一读，正文相似度 98%，
+等于**同一份文档改个日期交了十二次**。「逐月记录研发过程」这件事实际上没有发生。
+研发费用加计扣除与高企认定的核查员会摊开来对着读，一眼就能看出来。
+
+`docx_inspect(目录)` 会算相邻两期的正文相似度（去掉标题与封面键值行后的实质正文）：
+中位 ≥90% 报必修并点名逐字相同的是哪两期，75%–90% 报建议。
+正文均长不足 300 字的按「还没填的骨架」处理，不判。
+
+每期至少要写清三件事：**本期实际完成了什么、与计划的偏差及原因、下期安排**。
+固定结构可以复用，这三件事必须各不相同。
+
+## 六、交付件里最容易被放过的四件事
+
+这四条都是**人一读就发现、份数与章节检查却看不见**的，`docx_inspect(目录)` 会逐条报：
+
+- **模板给填表人的批注还在**。「注：由项目单位如实填写实际完成情况，下同。」「注：专家请选择以下
+  结论」——这是模板的填表说明，不是给读者看的注释，交付前必须删干净。
+  正经注释（「注：数据口径以合同附件三为准」）不受影响。
+- **选择项一个都没勾**。验收报告每类指标下面是「1.超额或全面完成（ ） 2.完成70%及以上（ ）
+  3.完成70%以下（ ）」，三选一。整份文档一个括号都没填，等于专家结论没人做、字没人签——
+  而这正是验收报告的核心。
+- **验收时写「进行中 / 预计完成」**。验收结论只有达标与不达标两档，「进行中」既不是达标也不是
+  不达标，等于把判断推给后面的人。没完成就如实写不达标并说明整改。
+- **该有图的文档一张图都没有**。技术总结报告、可研、概要设计里的技术路线与系统架构，
+  用文字硬描是读者的负担，也是评审最常见的追问点。
+
+另外还查**时间线自洽**：第 N 期月报的落款月份必须是 N 月；五个阶段评审必须按
+立项→设计→测试用例→验收→结项的顺序开。顺序倒了是「材料后补」的直接证据。
+
+### 项目名称：全档只该有一个名字
+
+这一条在真实归档里命中率最高，而人工审读几乎发现不了——**差一个字，眼睛会自动补对**。
+体检把三种写法分开对待，因为整改动作完全不同：
+
+- **简称**：「…系统的研发」「…系统研发」「…系统」混用。两个参考项目里出现 144 次，
+  完全正常，**一条都不报**——报了就会把真问题淹掉。
+- **错字**：「基于联邦学习的数字权益**开发**系统」，正式名是「**开放**系统」。
+  一个参考项目里 25 处、散布 20 份文件，从立项一路错到验收。整改是全文替换。
+- **串项目**：签到表抬头写着上一个项目的名字。两个参考项目各抓到一处——
+  一处是「基于信用模型算法的供应商管理系统研发」，一处是另一个在研项目。
+  表单类（签到表/评审报告/申请书）的抬头只该出现本项目名，这类判**必修**；
+  正文里提到别的项目可能正当（引用软著名称、对比同类），只报提示，由人判断。
+
+基准名取封面「项目名称」栏里**最长的那个写法，不是最高频的**：真实归档里被截断的写法
+反而可能占多数（11 份写「…风控系统研」少一个「发」），按票数选会把整改指引指反。
+
+### 模板点名的必备要素、签到表与野文件
+
+- **模板在节标题后括号里写明的要素就是验收项**。「项目立项的依据和来源（200字内，包括
+  立项文件号、合同号、研究起止时间）」——两个参考项目都只写到「依据…文件精神」，
+  文号与合同号一个都没有。自研项目没有合同号的，写明「自研，无合同」也比留空好：
+  审查人分不清是没有还是漏填。
+- **签到表有表头没人名**。两个参考项目的 10 张评审签到表，与会人一栏全空。判**建议**不判必修——
+  纸质原件常在线下签；但归档里只剩这份电子件时，它就是唯一的出席证据。
+  生成器**不会**替你预填与会人：凭空填名字等于伪造出席记录。
+- **对不上规范条目的文件会被点名**，不只报个数。命名不规范会连带把齐全性判成缺件，
+  规范外的附件则可忽略——两种都得人看一眼，工具不替你决定。
+
+### 跨文档样板段落：一段话不该同时是九种文档的开场白
+
+`check_boilerplate` 查的是**同一段话逐字出现在多种用途不同的文档里**。这和「周期性文档雷同」
+不是一回事——那是 12 期月报互比（同类），这是一段 449 字的技术描述同时出现在项目建议书、
+可行性研究报告、研发任务书、实施计划、12 期进度报告、工作总结、技术总结、评价纪要里：
+真实语料的两个项目分别是 13 段 2358 字、34 段 7138 字。
+
+进度报告的职责是记录本期干了什么，它不该和立项建议书开同一个头。
+
+门槛定在 **≥4 种文档类型**，是量出来的：立项三件套（建议书→可研→立项申请书）共享背景
+是**正当的**——可研本就是建议书的展开——它们只占 3 种类型，正好在门槛之下。
+60 字下限排掉标题、表头、固定表述这些天然重复的短句。判**建议**不判必修：
+这是质量信号不是事实错误，而且**各写各的**指的是正文主体，背景介绍复用没问题。
+
+### 旧格式不是「查不了」，但也不能假装查过了
+
+真实归档里旧格式占比很高：一个参考项目的 12 份月度验收报告是二进制 `.doc`，
+全部评审报告与预算表是 `.xls`——两者加起来超过归档的三分之一。
+
+- **`.doc`**：借系统自带转换器（macOS `textutil` / Linux `antiword`）取纯文本，
+  参与模板残留、项目名一致性、雷同度这些**文本类**判据；表格与标题层次拿不到，
+  结构类检查自然不对它们发言。转换器一个都没有时**会点名说哪几份没读进来**——
+  沉默是最坏的降级：份数照样对得上，用户看到「必修 0」会以为查过了。
+- **`.xls`**：见 `xlsx-analysis`——数据层照查，公式/列宽/合并/打印明说「没查」，
+  `fix` 直接拒绝（另存会把原件的公式与格式丢光）。
+- 雷同度按**扩展名分组比**：`.doc` 走纯文本转换，文本厚度天然比 `.docx` 薄，
+  混在一起比等于拿两把尺量同一件事。
+
+### 模板写死的字数上限
+
+模板正文里白纸黑字写着「项目立项背景（500字内）」「项目立项的依据和来源（200字内，
+包括立项文件号、合同号、研究起止时间）」。两个参考项目分别写了 1722 字和 4186 字——
+超出 3.4 倍与 8.4 倍。这不是文风问题：高企认定与研发费用加计扣除的审查人按模板逐条核。
+留 1.5 倍宽限（模板也写「500字左右」），只报明显超出的。
+
+## 七、表格件不是「交了就行」
+
+进度表、评审报告、预算表是归档里最容易「交了但没人读」的部分。`docx_inspect(目录)` 按这几张表
+自己的语义核对，查出来的都是**份数与章节检查碰不到**的矛盾：
+
+- **标记完成却没有完成的痕迹**：进度 100%，实际起止空着、实际工时 0。
+  真实归档里出现过 6 条——说完成了，但没有任何完成的证据。
+- **进度值越界**：进度列是 0~1 的比例（0.03、0.38、0.75 都正常），出现 2.0 就是填错了量纲。
+- **计划表里填了进度**：计划归计划、实际归实际，混着填会让「计划 vs 实际」的对比失去意义。
+- **实际表的任务列表与计划表对不上**：实际表应在计划表基础上填实际值，增删任务要走变更流程。
+- **实际结束早于实际开始**（或计划的两个日期填反）。
+- **评审记录/评审结论几乎是空的**：会开过就该留下问题、责任人、解决时间；
+  一条都没有，等于无法证明评审真的发生过。
+- **预算表没有任何非零金额**：全零等于没编预算。
+
+季度实际表要**累计**填：第 3 季度那张含前两季度已完成任务的实际数据，不是只填本季度发生的。
+真实归档正是这样（各季表的内容逐季变长）。
+
+## 八、通用文档类型（本体例之外）
+
+不属于这套归档、但常一起要的：需求规格说明书、概要设计说明书、详细设计说明书、测试报告、
+变更申请单。骨架与评审扣分点见 `doc_templates.py`：
+
+```bash
+python $HUICAI_SKILLS_DIR/tech-doc/scripts/doc_templates.py list
+python $HUICAI_SKILLS_DIR/tech-doc/scripts/doc_templates.py outline 需求规格说明书
+python $HUICAI_SKILLS_DIR/tech-doc/scripts/doc_templates.py check 项目验收报告
+```
+
+单份文档落盘走 `create_doc(spec={template:'研发任务书', …})`——传 template 会核对必备章节。
+
+## 九、交付自查
+
+- [ ] `docx_inspect(目录)` 必修 = 0（做不到就如实说明哪几项要用户决定）
+- [ ] 周期性文档份数齐、五个阶段评审报告与签到表配对
+- [ ] 模板「提示：」块、「注：由…填写」批注与 XX 占位符已删干净
+- [ ] 验收报告的三选一结论逐条勾选、主审专家已签字
+- [ ] 「实际完成情况」栏写的是实测值，不是「进行中」
+- [ ] 进度表里标记完成的任务都有实际起止与工时，进度值在 0~1 之间
+- [ ] 评审记录与评审结论有实质内容，预算表有金额
+- [ ] 立项考核指标在验收与总结里逐条有对应实测值
+- [ ] 周期性文档不是同一份改日期（体检的「雷同度」为零必修）
+- [ ] 签批栏该有的都有（空栏要在归档前签字盖章）
+- [ ] 关键数字（经费/工期/指标值）在全档每处出现都相同
+
+## 附件
+
+- `scripts/archive_spec.py` — 归档规范：目录编号体系、各文档章节骨架（**逐份从真实模板抽取**，
+  必修/建议两档按真实归档语料标定）、表单必填字段、签批栏、周期性份数、评审配对、
+  一致性字段、模板残留特征。可传自定义 JSON 换体例。
+- `scripts/archive_build.py` — 从档案卡生成整套骨架（docx + xlsx），`--demo` 可自测。
+- `scripts/archive_check.py` — 档案体检：齐全性 / 跨文档一致性 / 模板残留 / 结构与签批 / 指标勾稽 /
+  雷同度 / 时间线 / 表格件语义 / 项目名一致性 / 模板字数上限；
+  CLI `python archive_check.py 项目目录 [--deep]`。
+- `scripts/archive_battery.py` — 压测：正向生成整套断言零必修，**反向造 28 类缺陷验证体检不是瞎子**，
+  再跑 8 项产物不变量与 13 项反误报。不变量守的是「产物本身对不对」，不依赖体检报不报：
+  超长名不撑爆路径 / 注入到不存在章节不丢内容 / 预算 12 月之和 = 全年 / 预算科目与总额勾稽 /
+  里程碑交付物进入计划类文档 / 选做周期性文档不默认生成 / **季度实际表累计且自洽** /
+  **归档产物逐份过单文档与单表体检**。最后那条守的是三套引擎的接缝——
+  档案体检看不见单文档层面的问题，单文档压测又不生成归档件，只有接起来跑才现形。
+  改了上面任何一个，**必须重跑**：`python archive_battery.py 8`。
+- `scripts/doc_templates.py` — 通用文档类型（17 类）的骨架、评审扣分点与跨文档勾稽。