@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/tech-doc/scripts/doc_templates.py

@@ -0,0 +1,624 @@
+# 研发项目文档模板库：十七类文档的章节骨架、每节写作口径、评审扣分点、文档间勾稽关系。
+#
+# 这里存的不是「章节标题清单」——那种东西模型自己也能编，编出来的是空壳。
+# 存的是**评审现场才知道的事**：哪一节是决定通过与否的，哪句话写了等于没写，
+# 哪个数字必须和另一份文件里的数字一模一样。骨架是壳，points 与 traps 才是内容。
+#
+# 用法：
+#   python doc_templates.py list                    # 列全部类型
+#   python doc_templates.py outline 研发任务书       # 出 Markdown 骨架（带每节写作提示）
+#   python doc_templates.py check 项目验收报告       # 出提交前自查清单
+#   python doc_templates.py chain 验收             # 查这份文件要和谁对数字
+# 或 import：TEMPLATES / find() / outline() / checklist() / chain_for()
+
+import json
+import sys
+
+# profile 取值见 docx_layout.PROFILES：tech 技术文档 / gov 公文 / report 科技报告
+TEMPLATES = {
+    '项目建议书': {
+        'aliases': ['建议书', 'project proposal', '项目立项建议'],
+        'stage': '立项前',
+        'reader': '投资/决策层',
+        'decides': '这件事值不值得投入资源做进一步论证（不是「批不批」，是「要不要可研」）',
+        'profile': 'tech',
+        'sections': [
+            ('项目概况', ['名称、承担单位、拟建地点、建设性质（新建/改扩建/研发）、建设期',
+                          '一段话说清「做什么、多大规模、花多少钱、什么时候完」'], True),
+            ('建设的必要性', ['痛点用数据说：现状指标 + 差距 + 不做的后果（可量化的损失）',
+                              '政策依据引原文关键词，不要同义替换',
+                              '**这一节决定通过与否**，写不出数据就说明还没到写建议书的时候'], True),
+            ('需求分析与建设规模', ['需求来源（业务量预测/用户调研/上级要求），给推算过程',
+                                    '规模按需求倒推，不要先定规模再凑理由'], True),
+            ('建设方案设想', ['给 2–3 个方案的**比选**，不是只写选中的那个',
+                              '深度到「方向可行」即可——把可研的活提前干完，可研阶段就没东西写了'], True),
+            ('投资估算与资金来源', ['分项估算 + 单价来源；总投资在全文每处出现必须相同',
+                                    '资金来源分自筹/申请/贷款，比例合计 100%'], True),
+            ('效益分析', ['经济效益给测算口径与假设；社会效益避免形容词，给受益对象与规模'], True),
+            ('实施进度设想', ['分阶段给起止时间与阶段成果，不用到周'], False),
+            ('结论与建议', ['明确结论 + 下一步请示事项（通常是「建议开展可行性研究」）'], True),
+        ],
+        'traps': ['把「必要性」写成「先进性」——评审要的是「为什么非做不可」，不是「技术多好」',
+                  '投资估算拍脑袋，没有单价依据，可研阶段会被推翻重来',
+                  '只有一个方案，没有比选，等于没论证',
+                  '建议书写成小型可研，深度错位'],
+    },
+    '可行性研究报告': {
+        'aliases': ['可研', '可研报告', '可行性报告', 'feasibility study'],
+        'stage': '立项论证',
+        'reader': '评审专家、主管部门、投资方',
+        'decides': '技术上做不做得成、经济上划不划算、条件上具不具备',
+        'profile': 'report',
+        'sections': [
+            ('总论', ['项目概况、编制依据、研究范围、主要结论与建议一次说清',
+                      '总论是给不看后面的人写的，结论要能独立成立'], True),
+            ('需求分析与建设规模', ['需求预测给方法（趋势外推/类比/专家法）与数据来源', '规模论证：为什么是这个量不是别的量'], True),
+            ('技术方案', ['**必须三方案比选**：列比选表（技术成熟度/投资/工期/风险/可扩展性），给选择理由',
+                          '关键技术单独展开，说明成熟度与来源（自研/引进/合作）'], True),
+            ('建设条件与选址/环境', ['场地、网络、算力、数据、资质等前置条件逐项判定是否具备', '不具备的给获取方案与时间'], False),
+            ('节能环保与安全', ['按行业要求写；信息化项目重点是等保定级、数据合规、能耗'], False),
+            ('组织机构与人力资源', ['组织架构图 + 岗位与人数 + 现有/新增', '关键岗位说明能力要求与来源'], True),
+            ('实施进度计划', ['分阶段甘特（文字版即可），标关键路径与依赖'], True),
+            ('投资估算与资金筹措', ['分项估算表（设备/软件/人力/实施/运维/其他），每项给单价×数量×依据',
+                                    '分年度投资表；资金来源与到位计划'], True),
+            ('财务与效益评价', ['给假设表（折现率/周期/口径），算 NPV、IRR、投资回收期，做敏感性分析',
+                                '非经营性项目改做费用效果分析，不要硬编收入'], True),
+            ('风险分析与对策', ['技术/进度/资金/人员/合规五类，每条给概率×影响×应对措施与责任人'], True),
+            ('研究结论与建议', ['明确「可行/有条件可行/不可行」，有条件的写清条件'], True),
+        ],
+        'traps': ['全书数字不一致——总投资、工期、人数在不同章节对不上，这是最常见的一票否决项',
+                  '只有推荐方案没有比选表，「论证」变成「介绍」',
+                  '财务测算不给假设，数字无法复核',
+                  '风险章节写成套话，没有责任人和触发条件'],
+    },
+    '立项申请书': {
+        'aliases': ['立项申请', '课题申请书', '项目申报书', '开题报告'],
+        'stage': '立项',
+        'reader': '立项评审会 / 科技主管部门',
+        'decides': '批不批、给多少钱、考核什么',
+        'profile': 'tech',
+        'sections': [
+            ('项目基本信息', ['表单式：名称、编号、类别、承担单位、负责人、起止时间、经费、合作单位'], True),
+            ('立项背景与依据', ['行业现状与技术差距（给对比对象与数据）', '与规划/指南的对应关系，引原词'], True),
+            ('研究目标与考核指标', ['**指标写进去就是军令状**：每条给指标值、测试方法、验证环境、判定阈值',
+                                    '分「强制性指标」与「期望指标」两档，虚高会死在验收'], True),
+            ('主要研究内容', ['与目标一一映射，用 WBS 分解到可指派单元', '每项内容标注对应哪条考核指标'], True),
+            ('技术路线与实施方案', ['技术路线图（图 as code 画，别贴截图）+ 关键节点', '关键技术给解决思路与备选路径'], True),
+            ('现有工作基础与条件', ['团队、平台、前期成果、知识产权，给可核验的证据（专利号/论文/检测报告）'], True),
+            ('进度安排与里程碑', ['阶段—起止—交付物—验证方式四列表'], True),
+            ('经费预算', ['分科目 + 测算依据（单价×数量×次数），「打包估」过不了财务评审', '与研究内容对应，看得出钱花在哪条内容上'], True),
+            ('预期成果与知识产权', ['成果形式（样机/软件/标准/专利/论文）与数量，归属约定'], True),
+            ('风险分析与保障措施', ['技术风险给备选技术路径，进度风险给缓冲'], True),
+        ],
+        'traps': ['考核指标不可测（「显著提升」「大幅优化」），验收时无法判定',
+                  '研究内容与预算对不上，看不出钱花在哪',
+                  '现有基础用形容词堆砌，没有可核验的凭证',
+                  '指标定得比现有最好水平还高一大截，没给出为什么做得到'],
+        'chain': ['考核指标', '预算总额', '起止时间'],
+    },
+    '项目研发实施计划': {
+        'aliases': ['实施计划', '研发计划', '项目计划', '项目管理计划'],
+        'stage': '立项后启动',
+        'reader': '项目团队、PMO、甲方',
+        'decides': '谁在什么时候交什么，交不出来怎么办',
+        'profile': 'tech',
+        'sections': [
+            ('项目概述', ['目标、范围、约束、假设；**范围要写清「不做什么」**，这是防扯皮的关键'], True),
+            ('工作分解结构（WBS）', ['分解到可指派的最小单元（建议 ≤2 人周），每个单元有唯一编号与负责人',
+                                     'WBS 编号在后续所有文档里复用（进度、预算、验收都引它）'], True),
+            ('里程碑与进度计划', ['里程碑要有**可验证的判定标准**，不是「完成开发」而是「通过 XX 测试，缺陷密度 ≤ N」',
+                                  '给依赖关系与关键路径，标出缓冲'], True),
+            ('资源与人力计划', ['按阶段列人力投入（人月）与技能要求，与进度对得上',
+                                '设备/环境/数据/第三方服务的到位时间'], True),
+            ('技术方案要点', ['架构与关键技术选型结论（详细方案另出设计文档，这里只给结论与理由）'], False),
+            ('质量保证计划', ['评审点、测试策略、准入准出标准、缺陷分级与关闭标准'], True),
+            ('配置与变更管理', ['基线定义、版本规则、变更流程与审批权限'], True),
+            ('风险管理计划', ['风险登记册：编号/描述/概率/影响/应对/责任人/复审周期'], True),
+            ('沟通与汇报机制', ['例会节奏、汇报对象与频次、升级路径（多久没解决升给谁）'], False),
+            ('交付物清单', ['文档与产品逐项列，标明版本、介质、提交时间与接收人'], True),
+        ],
+        'traps': ['里程碑只有日期没有判定标准，到期只能靠嘴说完成了',
+                  '进度表没有依赖关系，看不出哪条是关键路径',
+                  '人力计划与进度矛盾（三个月的活排了两个人一个月）',
+                  '范围只写「做什么」不写「不做什么」，后期需求蔓延无从拒绝'],
+        'chain': ['里程碑日期', '交付物清单', '考核指标'],
+    },
+    '研发任务书': {
+        'aliases': ['任务书', '技术任务书', '研制任务书', '项目任务书'],
+        'stage': '任务下达',
+        'reader': '承研单位/团队，具有合同性质',
+        'decides': '干什么、干到什么程度、怎么算干完了',
+        'profile': 'tech',
+        'sections': [
+            ('任务来源与依据', ['上级文件/合同/立项批复的文号与名称'], True),
+            ('研制目标', ['一段话说清做出什么东西、达到什么水平、用在哪里'], True),
+            ('技术指标', ['**逐条给：指标名、指标值、测试方法、测试环境、判定依据**',
+                          '分强制性（不满足即不通过）与期望性两档并明确标注',
+                          '写「提升性能」这种无法验收的表述，等于把验收争议留给未来'], True),
+            ('工作内容与分工', ['按 WBS 列，标明各方责任边界与配合事项'], True),
+            ('交付物与技术状态', ['交付物清单（含文档、源码、样机、数据），标版本、介质、份数',
+                                  '技术状态基线：以哪个版本为准'], True),
+            ('进度节点', ['节点—时间—交付物—检查方式；节点与付款挂钩的要标明'], True),
+            ('经费与支付', ['总额、分期比例、支付条件（通常与节点验收挂钩）'], False),
+            ('验收方式与判据', ['验收组织形式、测试由谁做、在什么环境、判定规则（全部强制指标达标为通过）'], True),
+            ('知识产权与保密', ['成果归属、使用许可、涉密等级与保密期限'], True),
+            ('双方责任与变更', ['甲方提供什么（数据/环境/接口/人员）、乙方承诺什么',
+                                '变更的提出、评估与审批流程，以及对进度和经费的影响处理'], True),
+        ],
+        'traps': ['指标没有测试方法和环境——同一个指标不同环境测出来能差一个量级',
+                  '交付物只写「相关文档」，验收时扯不清该交几份',
+                  '甲方责任缺失，数据/环境不到位却由乙方担进度责任',
+                  '没有变更条款，需求一改就无据可依'],
+        'chain': ['考核指标', '里程碑日期', '交付物清单', '经费总额'],
+    },
+    '产品开发需求申请': {
+        'aliases': ['产品需求申请', '需求申请单', '产品需求提报'],
+        'stage': '需求提出',
+        'reader': '产品委员会/研发排期会',
+        'decides': '这个需求做不做、什么优先级、排哪个版本',
+        'profile': 'tech',
+        'sections': [
+            ('申请信息', ['申请人、部门、日期、期望上线时间、关联产品与版本'], True),
+            ('需求背景与问题描述', ['**写用户在什么场景下做不成什么事，不要写你想要的解决方案**',
+                                    '给发生频次与影响范围（多少用户、多少次/月、造成多少损失）'], True),
+            ('目标用户与使用场景', ['角色 + 场景 + 当前做法 + 痛点，最好给一个真实案例'], True),
+            ('需求描述', ['功能性需求：用户故事或用例，可验证',
+                          '非功能性需求：性能、并发、兼容、安全、可用性，给数值'], True),
+            ('业务价值与量化收益', ['收益要能算：省多少人力/提多少转化/降多少投诉，给测算方式',
+                                    '算不出来就如实说「暂无法量化」，别编'], True),
+            ('优先级与期望时间', ['给优先级理由（合规要求/客户承诺/收益规模），不是「都很急」'], True),
+            ('竞品与替代方案', ['别人怎么解决的；有没有不开发就能解决的办法（流程调整/采购/配置）'], False),
+            ('依赖与约束', ['依赖哪些系统/数据/团队；有什么不能碰的约束'], True),
+            ('验收标准', ['做成什么样算做完——由提出方给，不能等开发做完了再定'], True),
+            ('审批栏', ['申请人 / 部门负责人 / 产品经理 / 研发负责人 签批'], True),
+        ],
+        'traps': ['写成方案而不是问题（「我要一个导出按钮」而不是「财务每月手工汇总 40 张表」）',
+                  '收益不可量化又不承认，评审时无法排优先级',
+                  '没有验收标准，交付后争议「这不是我要的」',
+                  '优先级一律填「高」，等于没有优先级'],
+    },
+    '项目开发需求申请': {
+        'aliases': ['项目需求申请', '信息化需求申请', '系统开发需求申请'],
+        'stage': '需求提出（内部系统）',
+        'reader': '信息化主管部门 / 立项评审',
+        'decides': '立不立项、走开发还是走采购、预算多少',
+        'profile': 'tech',
+        'sections': [
+            ('申请单位与联系人', ['单位、部门、负责人、联系方式、申请日期'], True),
+            ('业务现状与痛点', ['现有流程（给流程图）、当前工具、耗时与差错率等可量化现状'], True),
+            ('目标业务流程', ['期望流程（给流程图），标出与现状的差异点'], True),
+            ('系统功能需求', ['按模块列，每条标必须/期望；写「能做什么」不写「怎么实现」'], True),
+            ('接口与数据需求', ['需对接的系统、数据来源与流向、数据量级、同步时效、责任方'], True),
+            ('性能、安全与合规要求', ['并发/响应/可用性给数值；等保定级、数据分类分级、审计要求'], True),
+            ('涉及部门与配合事项', ['列出需要配合的部门与配合内容，提前打招呼比事后催有用'], True),
+            ('预算来源与金额', ['预估金额与科目来源，注明是否已列入年度预算'], True),
+            ('期望上线时间与理由', ['时间点背后的业务约束（政策截止/审计要求/业务旺季）'], True),
+            ('审批栏', ['申请部门 / 归口管理部门 / 信息化主管 / 分管领导'], True),
+        ],
+        'traps': ['痛点不量化，评审无法与其他申请横向比较',
+                  '不写接口与数据，实施阶段才发现要跨三个系统',
+                  '配合部门没提前沟通，立项后推不动',
+                  '期望时间没有依据，变成「越快越好」'],
+    },
+    '需求规格说明书': {
+        'aliases': ['SRS', '软件需求规格说明书', '需求说明书'],
+        'stage': '需求分析',
+        'reader': '设计、开发、测试、甲方',
+        'decides': '要做的东西的边界，测试用例的来源',
+        'profile': 'report',
+        'sections': [
+            ('引言', ['编写目的、读者对象、术语与缩略语、参考资料'], True),
+            ('总体描述', ['产品定位与上下文（系统上下文图）、用户角色、总体约束与假设'], True),
+            ('功能需求', ['**每条需求一个唯一编号**（FR-001），后续设计/测试/追溯全靠它',
+                          '每条含：描述、输入、处理、输出、异常与边界、优先级'], True),
+            ('非功能需求', ['性能（并发/响应/吞吐，给测量条件）、可用性、安全、兼容、可维护、可移植，全部给数值'], True),
+            ('接口需求', ['用户界面、外部系统接口、硬件接口、通信协议；接口按契约描述'], True),
+            ('数据需求', ['数据字典、数据量与增长、保留与归档、隐私与分级'], True),
+            ('需求追溯矩阵', ['需求编号 ↔ 来源（需求申请/任务书条款）↔ 设计 ↔ 测试用例'], True),
+        ],
+        'traps': ['需求没有编号，无法追溯，改一条不知道影响什么',
+                  '非功能需求写成形容词（「响应快」「安全性高」）',
+                  '缺异常与边界描述，实现时各写各的',
+                  '把设计决定写进需求（约束了实现方式却没有理由）'],
+    },
+    '概要设计说明书': {
+        'aliases': ['概设', '总体设计说明书', 'HLD'],
+        'stage': '设计',
+        'reader': '开发、测试、架构评审',
+        'decides': '系统怎么切、模块怎么分、接口怎么定',
+        'profile': 'report',
+        'sections': [
+            ('引言与设计依据', ['依据的需求文档版本，设计约束与非目标'], True),
+            ('总体架构', ['分层/分模块架构图 + 每层职责；部署架构图；技术选型与理由'], True),
+            ('模块划分与职责', ['模块清单：名称、职责、对外接口、依赖；职责单一、依赖有向无环'], True),
+            ('接口设计', ['模块间与外部接口：协议、请求/响应、错误码、幂等与重试语义'], True),
+            ('数据设计', ['概念模型/ER 图、主要表与关系、分库分表与索引策略'], True),
+            ('关键流程', ['核心业务的时序图（下单/审批/同步），标出事务与失败处理'], True),
+            ('非功能设计', ['性能与容量测算（给算式）、高可用与容灾、安全设计、可观测性'], True),
+            ('技术风险与备选方案', ['选型的替代路径与切换代价'], False),
+        ],
+        'traps': ['只有架构图没有职责说明，图上每个框都是黑盒',
+                  '接口不写错误码与幂等语义，联调时才发现',
+                  '容量测算缺失，上线才发现算力不够',
+                  '设计与需求编号对不上，无法证明需求都被覆盖'],
+    },
+    '详细设计说明书': {
+        'aliases': ['详设', 'LLD', '详细设计文档'],
+        'stage': '设计',
+        'reader': '开发、代码评审',
+        'decides': '每个模块内部怎么写',
+        'profile': 'report',
+        'sections': [
+            ('模块概述', ['对应概设中的哪个模块、承担哪些需求编号'], True),
+            ('类/组件设计', ['主要类与职责、关键属性与方法签名、状态机（有状态时必给）'], True),
+            ('算法与关键逻辑', ['给伪码或流程图；复杂度与边界条件；为什么不用更直观的那个做法'], True),
+            ('数据结构与存储', ['表结构 DDL、字段含义与取值范围、索引与查询模式'], True),
+            ('接口实现细节', ['参数校验规则、错误处理、超时与重试、日志与埋点'], True),
+            ('异常与失败语义', ['失败时系统处于什么状态、调用方该怎么办、什么情况下不该重试'], True),
+            ('单元测试要点', ['关键分支与边界的测试点清单'], False),
+        ],
+        'traps': ['把代码贴进文档当详细设计——代码会变，文档不会跟着变',
+                  '不写失败语义，出问题时无人知道该怎么恢复',
+                  '算法只写「怎么做」不写「为什么不用另一种」，后人重复踩坑'],
+    },
+    '测试报告': {
+        'aliases': ['测试总结报告', '系统测试报告', 'QA 报告'],
+        'stage': '测试完成',
+        'reader': '项目组、甲方、验收专家',
+        'decides': '能不能上线/验收',
+        'profile': 'report',
+        'sections': [
+            ('测试概述', ['测试对象与版本号、测试依据、测试范围与不覆盖范围'], True),
+            ('测试环境', ['硬件、软件版本、数据规模、网络条件——**环境不写清，数据不可复现**'], True),
+            ('测试执行情况', ['用例总数/执行数/通过数/阻塞数，覆盖率（需求覆盖、代码覆盖）'], True),
+            ('缺陷统计与分析', ['按严重级别与模块分布，给收敛曲线；遗留缺陷逐条列并说明为什么可以放行'], True),
+            ('性能测试结果', ['场景、并发、时长、指标实测值 vs 目标值，给出结论与瓶颈定位'], True),
+            ('指标达成对照表', ['逐条对照任务书/需求的指标，给实测值与达成判定'], True),
+            ('结论与建议', ['明确「通过/有条件通过/不通过」，有条件的写清条件与期限'], True),
+        ],
+        'traps': ['只给通过率不给环境与数据规模，数字无法复现',
+                  '遗留缺陷含糊带过，上线后爆雷',
+                  '性能测试只给平均值不给 P95/P99 与压测时长',
+                  '结论写「基本通过」——没有这一档'],
+        'chain': ['考核指标'],
+    },
+    '项目工作总结报告': {
+        'aliases': ['工作总结', '项目总结报告', '项目工作报告'],
+        'stage': '项目收尾',
+        'reader': '管理层、PMO',
+        'decides': '这个项目管得怎么样，下个项目怎么改进',
+        'profile': 'tech',
+        'sections': [
+            ('项目概况', ['目标、范围、周期、投入、参与单位与人员规模'], True),
+            ('目标完成情况', ['**计划 vs 实际对照表**：目标项、计划值、实际值、达成率、说明',
+                              '未达成的不要藏在文字里，就放在表里'], True),
+            ('主要工作与过程', ['按阶段写关键活动与决策点，不写流水账'], True),
+            ('进度与成本执行分析', ['进度偏差与成本偏差（给数值与百分比），每个偏差写原因、影响、已采取措施'], True),
+            ('质量情况', ['交付质量数据：缺陷密度、返工率、评审发现问题数与关闭率'], True),
+            ('团队与协作', ['人力投入实际值、关键角色、协作中的堵点'], False),
+            ('问题与风险处置回顾', ['当初识别的风险哪些发生了、应对是否有效；哪些是没预料到的'], True),
+            ('经验与教训', ['**教训要具体到可执行**：「下次要提前介入」是口号，「合同签署前必须完成接口口径确认」才是教训'], True),
+            ('遗留问题与后续计划', ['逐条列：问题、影响、责任人、计划关闭时间'], True),
+        ],
+        'traps': ['只报喜不报忧，通篇「圆满完成」，管理层学不到任何东西',
+                  '没有计划-实际对照表，偏差被文字稀释掉',
+                  '经验教训写成口号，下个项目照样踩',
+                  '遗留问题没有责任人和时限，等于没有交接'],
+        'chain': ['里程碑日期', '经费总额'],
+    },
+    '项目技术总结报告': {
+        'aliases': ['技术总结', '技术总结报告', '研制总结报告'],
+        'stage': '项目收尾',
+        'reader': '技术评审专家、后续接手团队',
+        'decides': '技术上到底做成了什么，能不能推广',
+        'profile': 'report',
+        'sections': [
+            ('技术目标与指标完成情况', ['**指标实测数据表**：指标、要求值、实测值、测试条件、结论',
+                                        '这是全篇的核心，其余章节都是对它的解释'], True),
+            ('总体技术方案', ['最终采用的架构与技术路线（与立项时的差异要说明为什么变）'], True),
+            ('关键技术与解决途径', ['逐项：难在哪、试过哪些路、最后怎么解的、代价是什么'], True),
+            ('技术难点与突破', ['给出证据：对比实验数据、第三方检测、专利/查新报告'], True),
+            ('试验与验证结果', ['试验方案、样本量、环境、原始数据来源与保存位置'], True),
+            ('创新点与先进性对比', ['**「首次/领先」必须给对比对象与出处**，给不出就降格为「特色」'], True),
+            ('技术成熟度与推广条件', ['当前 TRL 等级、推广需要补什么条件'], False),
+            ('存在的技术问题', ['诚实列出未解决的问题与影响范围——这一节的存在本身就是可信度'], True),
+            ('知识产权与技术文件清单', ['专利/软著/论文/标准，列号；技术文件清单标版本与归档位置'], True),
+        ],
+        'traps': ['只写做了什么，不给实测数据，评审无法判断到底达没达标',
+                  '把工作量当创新点（「完成了 30 个接口开发」不是技术创新）',
+                  '测试条件不写，数据失去意义',
+                  '回避未解决的问题，评审专家一问就露'],
+        'chain': ['考核指标'],
+    },
+    '项目验收报告': {
+        'aliases': ['验收报告', '结项报告', '竣工验收报告'],
+        'stage': '验收',
+        'reader': '验收专家组、主管部门、审计',
+        'decides': '通过 / 整改后通过 / 不通过',
+        'profile': 'tech',
+        'sections': [
+            ('项目基本情况', ['名称、编号、承担单位、负责人、起止时间、合同/任务书文号'], True),
+            ('验收依据', ['合同、任务书、立项批复、相关标准规范——逐项列文号与名称'], True),
+            ('建设内容完成情况', ['对照任务书的工作内容逐条说明完成情况'], True),
+            ('技术指标验收对照表', ['**指标 / 要求值 / 实测值 / 检测方式 / 检测方 / 判定**，一条不落',
+                                    '实测值要有出处（测试报告编号、检测报告编号）'], True),
+            ('测试与检验结果', ['第三方检测/用户测试/压力测试的结论与报告编号'], True),
+            ('经费执行与决算', ['预算 vs 实际支出分科目对照，超支或结余说明原因'], True),
+            ('文档与交付物清单核对', ['逐项打勾：文档名称、版本、份数、介质、是否已归档'], True),
+            ('用户使用情况与意见', ['上线时间、使用范围、使用量、用户书面意见（附件）'], False),
+            ('存在问题与整改情况', ['如实列，说明整改责任人与完成时限'], True),
+            ('验收结论', ['**必须明确**：一致同意通过 / 整改后通过（写明整改事项与期限）/ 不通过'], True),
+            ('验收专家组名单与签字', ['姓名、单位、职称、组内分工，留签字栏'], True),
+        ],
+        'traps': ['指标对照表缺项或用「基本达标」——没有这一档，要么达标要么不达标',
+                  '实测值没有出处，审计时无法追溯',
+                  '文档清单只写「相关文档齐全」，核对不了',
+                  '结论含糊，事后争议无法收场'],
+        'chain': ['考核指标', '经费总额', '交付物清单', '起止时间'],
+    },
+    '项目验收申请表': {
+        'aliases': ['验收申请', '结项申请表', '验收申请书'],
+        'stage': '验收前',
+        'reader': '主管部门经办人',
+        'decides': '受不受理、什么时候组织验收',
+        'profile': 'tech',
+        'form': True,
+        'fields': [
+            '项目名称', '项目编号', '项目类别', '承担单位', '合作单位', '项目负责人',
+            '联系电话', '合同（任务书）编号', '计划起止时间', '实际起止时间',
+            '批准经费（万元）', '实际到位（万元）', '实际支出（万元）',
+            '主要研究内容', '完成的考核指标（对照任务书逐条填写）', '主要交付物',
+            '知识产权情况', '已提交验收材料清单', '申请验收方式（会议/函审/现场测试）',
+            '申请单位意见（盖章）', '主管部门意见（盖章）',
+        ],
+        'sections': [],
+        'traps': ['表单类文档的失分点几乎全在「字段缺项」与「签章不全」，不在文采',
+                  '考核指标栏写概述而不是逐条对照，会被退回',
+                  '材料清单与实际提交的不符',
+                  '经费三个数（批准/到位/支出）对不上，直接退回'],
+        'chain': ['考核指标', '经费总额', '起止时间'],
+    },
+    '项目研发评价总结纪要': {
+        'aliases': ['评价纪要', '评审纪要', '评议纪要', '总结会纪要', '研发评价纪要'],
+        'stage': '评价/评审会后',
+        'reader': '与会各方、存档',
+        'decides': '会上定了什么、谁在什么时候做什么',
+        'profile': 'gov',
+        'sections': [
+            ('会议基本信息', ['时间、地点、方式（现场/视频）、主持人、参加单位与人员、记录人'], True),
+            ('会议议程', ['按实际进行的顺序列'], True),
+            ('汇报要点', ['项目组汇报的核心内容与关键数据，一般不超过全文三分之一篇幅'], True),
+            ('评价意见', ['**逐条列专家意见**，重要的注明提出人；意见与建议分开，不要揉在一起'], True),
+            ('讨论与分歧', ['有分歧就写清分歧点与各方理由——纪要隐去分歧，事后就会翻案'], True),
+            ('评价结论', ['明确结论与等级（如优秀/良好/合格/不合格），给票数或一致意见的表述'], True),
+            ('待办事项', ['**事项 / 责任人 / 完成时限 / 验证方式** 四列表——没有责任人和时限的待办等于没写'], True),
+            ('附件', ['汇报材料、专家名单与签到表、评分表'], False),
+        ],
+        'traps': ['写成讲话稿，通篇「某某领导强调」，读者找不到结论',
+                  '没有待办事项表，会开完什么也没落地',
+                  '回避分歧，纪要与实际会议不符，签字环节会卡住',
+                  '结论没有等级或票数，无法作为后续依据'],
+    },
+    '变更申请单': {
+        'aliases': ['变更申请', '需求变更单', '工程变更'],
+        'stage': '执行期',
+        'reader': '变更控制委员会（CCB）',
+        'decides': '这个变更批不批、代价谁承担',
+        'profile': 'tech',
+        'form': True,
+        'fields': [
+            '变更编号', '提出人/部门', '提出日期', '变更类型（需求/设计/进度/范围/经费）',
+            '关联需求或 WBS 编号', '变更内容描述', '变更原因',
+            '不变更的后果', '影响分析（工作量/进度/成本/质量/风险）',
+            '替代方案', '受影响的交付物与文档', '实施计划与责任人',
+            '提出方意见', '技术负责人意见', '项目经理意见', 'CCB 审批意见',
+        ],
+        'sections': [],
+        'traps': ['只写「要改成什么」，不写「不改会怎样」，CCB 无法权衡',
+                  '影响分析缺工作量估算，批完才发现要延期两个月',
+                  '不列受影响的文档，基线文档改一处漏三处'],
+    },
+}
+
+# 文档之间必须对齐的字段——**跨文档的数字矛盾是评审与审计的高频失分点**，
+# 而它天然发生在「这份文档写得很好」的前提下：单看每份都对，放一起就打架。
+CHAIN = [
+    {'field': '考核指标',
+     'docs': ['立项申请书', '研发任务书', '项目研发实施计划', '测试报告', '项目技术总结报告',
+              '项目验收报告', '项目验收申请表'],
+     'rule': '指标名称、指标值、测试方法四要素在全链条中必须逐字一致；'
+             '任务书里写「≤8 分钟」，验收报告就不能写「约 8 分钟」'},
+    {'field': '经费总额',
+     'docs': ['可行性研究报告', '立项申请书', '研发任务书', '项目工作总结报告',
+              '项目验收报告', '项目验收申请表'],
+     'rule': '批准经费 / 实际到位 / 实际支出三个口径要分别标注，不能混着用同一个数；'
+             '总投资在同一份文档内的每一处出现也必须相同'},
+    {'field': '里程碑日期',
+     'docs': ['项目研发实施计划', '研发任务书', '项目工作总结报告'],
+     'rule': '计划日期与实际日期分列，偏差要有说明，不要用实际值悄悄覆盖计划值'},
+    {'field': '交付物清单',
+     'docs': ['研发任务书', '项目研发实施计划', '项目验收报告', '项目验收申请表'],
+     'rule': '名称、版本、份数、介质四项一致；验收时按任务书那份逐条核对'},
+    {'field': '起止时间',
+     'docs': ['立项申请书', '研发任务书', '项目验收报告', '项目验收申请表'],
+     'rule': '计划起止与实际起止分别写；有延期要有批准文号'},
+]
+
+
+def _corpus():
+    """取归档规范里的章节体例（同目录的 archive_spec）。取不到就返回 None，不影响本库自用。"""
+    try:
+        import archive_spec
+        return archive_spec.SECTIONS
+    except Exception:
+        return None
+
+
+def sections_for(kind):
+    """某类文档的章节骨架 —— **归档规范（真实语料体例）优先，本库通用体例兜底**。
+
+    为什么必须有这个收口：同一类「研发任务书」，本库给的是「任务来源与依据/研制目标/技术指标…」，
+    归档规范给的是「项目概述/目标及要求/项目人员…」。两套都对（前者是通用做法，后者是这家单位
+    的实际体例），但**同时存在就会打架**：用 create_doc 写的人被要求补 A，跑档案体检的人被要求补 B，
+    两边都按自己那套报「缺章节」。有自家体例时就以自家的为准，这是唯一说得通的口径。
+
+    返回统一成 (章节名, 子节, 是否必备) 三元组。
+    """
+    c = _corpus()
+    # **按「键在不在」判，不按「值空不空」判**：归档规范里 `'产品开发需求申请': []` 是有意义的
+    # ——那类文档在本体例下就是表单式、没有章节。把空列表当成「查无此类」而回退到通用库，
+    # 等于用通用章节去要求一份表单，两边又打起来。
+    if c is not None and kind in c:
+        return [(t, list(subs), lvl == 'must') for t, subs, lvl, _al in c[kind]]
+    return [(t, list(p), m) for t, p, m in TEMPLATES.get(kind, {}).get('sections', [])]
+
+
+def form_fields_for(kind):
+    """表单式文档的字段清单——同样归档规范优先。"""
+    try:
+        import archive_spec
+        if kind in archive_spec.FORM_FIELDS:
+            return list(archive_spec.FORM_FIELDS[kind])
+    except Exception:
+        pass
+    return list(TEMPLATES.get(kind, {}).get('fields', []))
+
+
+def find(name):
+    """按名称或别名找模板键。找不到返回 None（不猜）。"""
+    s = str(name or '').strip()
+    if s in TEMPLATES:
+        return s
+    low = s.lower()
+    for k, v in TEMPLATES.items():
+        if low == k.lower() or low in [a.lower() for a in v.get('aliases', [])]:
+            return k
+    for k, v in TEMPLATES.items():                    # 退一步做包含匹配
+        if s and (s in k or k in s):
+            return k
+        if any(s and (s in a or a in s) for a in v.get('aliases', [])):
+            return k
+    return None
+
+
+def outline(name, with_hints=True):
+    """出 Markdown 骨架。with_hints=True 时每节带 `> 写作提示`，供人先看再删。"""
+    key = find(name)
+    if not key:
+        return f'未收录「{name}」。已收录：' + '、'.join(TEMPLATES)
+    t = TEMPLATES[key]
+    out = [f'# {key}', '']
+    if with_hints:
+        out += [f'> 阶段：{t["stage"]}　读者：{t["reader"]}',
+                f'> 这份文件要帮读者做的决定：{t["decides"]}',
+                f'> 排版档位：{t["profile"]}', '']
+    secs = sections_for(key)
+    fields = form_fields_for(key)
+    # 判据是「有没有章节」，不是本库自己那个 form 标记：
+    # 归档规范可能把某类文档定成表单式（章节为空），本库却给了通用章节，
+    # 只看本库的标记就会该出字段清单时不出。
+    if fields and not secs:
+        out.append('本类为**表单式**文档：主体是字段表（用 kv 表排版），不是章节正文。字段清单：')
+        out.append('')
+        for f in fields:
+            out.append(f'- {f}：')
+        out.append('')
+    own = {x[0]: x[1] for x in t.get('sections', [])}
+    for title, subs, must in secs:
+        out.append(f'## {title}' + ('' if must else '（可选）'))
+        if with_hints:
+            for p in own.get(title, []):      # 本库的写作要点，能对上就带出来
+                out.append(f'> {p}')
+        for sname in subs:
+            out.append(f'### {sname}')
+        out.append('')
+    if with_hints and t.get('traps'):
+        out += ['---', '', '**评审扣分点（写完对照一遍）**', '']
+        out += [f'- {x}' for x in t['traps']]
+        out.append('')
+    return '\n'.join(out)
+
+
+def checklist(name):
+    key = find(name)
+    if not key:
+        return f'未收录「{name}」。'
+    t = TEMPLATES[key]
+    lines = [f'【{key} · 提交前自查】']
+    for title, _subs, must in sections_for(key):
+        if must:
+            lines.append(f'  [ ] {title} —— 必备章节，已写且不是空壳')
+    ff = form_fields_for(key)
+    if ff and not sections_for(key):
+        lines.append(f'  [ ] {len(ff)} 个字段无一缺项，签章齐全')
+    for x in t.get('traps', []):
+        lines.append(f'  [ ] 已避开：{x}')
+    for c in chain_for(key):
+        lines.append(f"  [ ] 「{c['field']}」与 {'、'.join(d for d in c['docs'] if d != key)} 一致（{c['rule']}）")
+    lines.append('  [ ] 已跑 docx_inspect 体检，必改项清零')
+    return '\n'.join(lines)
+
+
+def chain_for(name):
+    key = find(name) or name
+    return [c for c in CHAIN if key in c['docs']]
+
+
+def list_all():
+    rows = [('文档类型', '阶段', '决定什么')]
+    for k, v in TEMPLATES.items():
+        rows.append((k, v['stage'], v['decides'][:34]))
+    def dw(s):                       # 显示宽度：中日韩字符占两格
+        return sum(2 if ord(ch) > 0x2E80 else 1 for ch in s)
+    w = [max(dw(r[i]) for r in rows) for i in range(3)]
+    return '\n'.join('  '.join(c + ' ' * (w[i] - dw(c)) for i, c in enumerate(r)).rstrip()
+                     for r in rows)
+
+
+def self_test():
+    assert find('任务书') == '研发任务书'
+    assert find('可研') == '可行性研究报告'
+    assert find('验收申请') == '项目验收申请表'
+    assert find('不存在的东西xyz') is None
+    # 有归档规范时以它为准：研发任务书的体例章节是「目标及要求」而不是通用的「技术指标」
+    assert '目标及要求' in outline('研发任务书'), outline('研发任务书')[:200]
+    for k in set(TEMPLATES) & set(_corpus() or {}):
+        a = [x[0] for x in sections_for(k)]
+        b = [t for t, _s, lvl, _al in (_corpus() or {})[k]]
+        assert a == b, f'{k} 两套章节没对齐'
+    assert '字段清单' in outline('项目验收申请表')
+    assert '字段清单' in outline('产品开发需求申请'), '语料里是表单式，应出字段清单而非通用章节'
+    assert len(chain_for('项目验收报告')) >= 3
+    for k, v in TEMPLATES.items():
+        assert v.get('sections') or v.get('form'), k
+        assert v.get('traps'), k
+        assert v['profile'] in ('tech', 'gov', 'report'), k
+    for c in CHAIN:
+        for d in c['docs']:
+            assert d in TEMPLATES, d
+    print(f'[doc_templates] self-test OK · {len(TEMPLATES)} 类文档 / {len(CHAIN)} 条跨文档勾稽')
+
+
+def main(argv):
+    if not argv or argv[0] in ('list', '-l'):
+        print(list_all())
+        return 0
+    cmd = argv[0]
+    arg = argv[1] if len(argv) > 1 else ''
+    if cmd == 'outline':
+        print(outline(arg, '--plain' not in argv))
+    elif cmd == 'check':
+        print(checklist(arg))
+    elif cmd == 'chain':
+        cs = chain_for(arg) if arg else CHAIN
+        print(json.dumps(cs, ensure_ascii=False, indent=2))
+    elif cmd == 'selftest':
+        self_test()
+    else:
+        print('用法：list | outline <类型> | check <类型> | chain [类型] | selftest')
+        return 2
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))