@huicai/cli 2026.804.0 → 2026.1019.0

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

@@ -0,0 +1,499 @@
+# 研发项目文档归档规范（内置体例从真实归档套件逐份抽取，不是凭印象编的）。
+#
+# 为什么要有「档案级」这一层：单份文档体检得再干净，也看不见下面这些——
+# 同一个项目 41 份文档里项目名称有三种写法（含一个被截断的）、研发任务书写 ZY202501003
+# 而验收申请表写 ZY202501006、项目建议书把「联系人/电话/编制人」三个字段填串了、
+# 12 期月度验收报告一份没交。这些全是**跨文档**的事实，只有把整个项目目录一起看才发现得了，
+# 而它们恰恰是验收与审计现场最容易被挑出来的问题。
+#
+# 体例可换：内置 `hengtong`（技术中心研发部通行的那套编号目录），
+# 也可以传自定义 JSON 覆盖——`load(name_or_path)`。
+
+import json
+import os
+import re
+
+# ── 统一封面信息栏 ─────────────────────────────────────────────────────────
+# 这套体例里几乎每份正式文档都带同一张封面信息表 + 单位落款 + 日期。
+# 字段名在各文档间略有出入（有的叫「编制人」有的叫「报告编写人」），归一到下面这组语义键。
+FIELD_ALIASES = {
+    '项目名称': ['项目名称', '项 目 名 称', '总项目名称'],
+    '项目编号': ['项目编号', '项目编码'],
+    '项目负责人': ['项目负责人', '项目经理'],
+    '项目联系人': ['项目联系人'],
+    '联系电话': ['联系电话', '联 系 电 话', '联系电话（手机）', '电话'],
+    '建设单位': ['建设单位', '建 设 单 位', '项目承建单位', '项目承担单位', '单位'],
+    '编制人': ['编制人', '编 制 人', '报告编写人', '编写人', '申请人'],
+    '编制时间': ['编制时间', '编 制 时 间', '编制日期', '编 制 日 期', '完成时间',
+                 '立项时间', '申请日期', '提交时间'],
+    '起止时间': ['项目起止时间', '起止时间', '研究起止时间'],
+    '申请部门': ['申请部门', '部门'],
+}
+FIELD_KEYS = list(FIELD_ALIASES)
+
+# 反查表：归一化后的字面 → 语义键
+_ALIAS_INDEX = {}
+for _k, _vs in FIELD_ALIASES.items():
+    for _v in _vs:
+        _ALIAS_INDEX[re.sub(r'[\s　]', '', _v).rstrip('：:')] = _k
+
+
+def field_key(raw):
+    """把文档里的字段名归一到语义键；认不出返回 None。"""
+    return _ALIAS_INDEX.get(re.sub(r'[\s　]', '', str(raw or '')).rstrip('：:'))
+
+
+# ── 各文档的章节骨架 ───────────────────────────────────────────────────────
+# 每条 = (章节名, 子节, 级别, 别名)。级别两档，是**按真实归档语料标定的**，不是拍脑袋：
+#   must   —— 模板要求且两个真实项目都写了 → 缺了报必修；
+#   should —— 模板里有、但真实项目普遍省略 → 缺了只报建议（照模板一刀切会对每个
+#             正常项目都误报一次，那种噪声比漏报更快让人关掉检查）。
+# 别名来自真实文档的改名习惯（「验收标准和验收工作安排」实际写成「验收标准」），
+# 不给别名就会把改了名的合规章节判成缺失。
+SECTIONS = {
+    '项目建议书': [
+        ('文档介绍', ['文档目的', '文档范围', '读者对象', '参考文献', '术语与缩写解释'], 'should', []),
+        ('产品介绍', ['产品定义', '产品开发背景', '产品主要功能和特色', '产品范围'], 'must', []),
+        ('市场概述', ['客户需求', '市场规模与发展趋势'], 'should', ['市场分析']),
+        ('产品发展目标', [], 'must', []),
+        ('产品技术方案', ['产品体系结构', '关键技术'], 'must', []),
+        ('产品优缺点分析', [], 'should', []),
+        ('Make-or-Buy决策', ['项目团队', '软硬件资源估算', '成本估算'], 'must', []),
+        ('项目计划', [], 'should', ['进度安排']),
+        ('市场营销计划', [], 'should', []),
+        ('成本效益分析', [], 'must', []),
+        ('总结', [], 'must', []),
+    ],
+    # 真实体例是科技计划项目可研那一套十一节，两个项目逐字一致——
+    # 早先用的通用「总论/技术方案/投资估算」骨架在这套语料上一条都对不上。
+    '可行性研究报告': [
+        ('立项的背景与意义', [], 'must', ['立项背景']),
+        ('国内外研究现状与发展趋势', [], 'must', ['研究现状']),
+        ('项目实施主要内容、技术关键与创新点、预期目标',
+         ['实施主要内容', '预期目标'], 'must', ['实施主要内容']),
+        ('现有工作基础、条件和优势', [], 'must', ['现有工作基础']),
+        ('项目实施方案、组织方式与课题分解', [], 'must', ['项目实施方案']),
+        ('进度安排与年度计划内容', [], 'must', ['进度安排']),
+        ('承担单位和主要研究人员简况', [], 'must', ['承担单位']),
+        ('经费预算来源、使用计划及还款能力分析', [], 'must', ['经费预算']),
+        ('应用或产业化前景与市场需求分析', [], 'must', ['产业化前景', '市场需求分析']),
+        ('经济、社会效益分析', [], 'must', ['经济效益', '社会效益']),
+        ('项目的风险分析与对策', [], 'must', ['风险分析']),
+    ],
+    '立项申请书': [
+        ('项目立项背景', [], 'must', []),
+        ('项目主要研究（实验或推广）内容', [], 'must', ['主要研究内容']),
+        ('项目拟解决的技术关键及解决措施', [], 'must', ['技术关键']),
+        ('项目考核指标', [], 'must', ['考核指标']),
+        ('进度安排', [], 'must', []),
+        ('项目验收时间', [], 'must', []),
+        ('项目经费预算', [], 'must', ['经费预算']),
+        ('项目主要参加人员', [], 'must', ['主要参加人员']),
+        ('审批意见', [], 'must', []),
+    ],
+    '研发任务书': [
+        ('项目概述', ['项目摘要', '项目背景与目的', '项目主要设计与改进说明'], 'must', []),
+        ('目标及要求', ['技术选型', '项目目标'], 'must', []),
+        ('项目人员', [], 'must', []),
+        ('费用预算', [], 'must', []),
+        ('项目开发计划', [], 'must', []),
+        ('结项条件', [], 'must', []),
+    ],
+    '项目研发实施计划': [
+        ('引言', ['编写目的', '背景'], 'must', []),
+        ('定义', ['专门术语', '缩写'], 'must', []),
+        ('项目概述', ['工作内容', '主要参与人员'], 'must', []),
+        ('绩效与考核机制', [], 'should', ['考核机制']),
+        ('研发计划', [], 'should', []),
+        ('产品及成果', [], 'must', []),
+        ('验收标准和验收工作安排', ['代码的验收', '文档验收标准', '服务验收'], 'must', ['验收标准']),
+        ('审批记录', [], 'must', []),
+    ],
+    '研发进度报告': [
+        ('编写目的', [], 'must', []),
+        ('项目概述', [], 'must', []),
+        ('项目进度概述', ['项目进度情况', '费用情况'], 'must', []),
+        ('外部情况分析', [], 'must', []),
+        ('审批记录', [], 'must', []),
+    ],
+    '工作总结报告': [
+        ('项目执行概述', [], 'must', []),
+        ('项目来源', ['项目立项背景', '项目立项的依据和来源'], 'must', []),
+        ('实施完成情况', ['项目研究内容完成情况', '项目考核指标完成情况', '项目取得的主要成果'], 'must', []),
+        ('经费支出情况', [], 'must', []),
+        ('存在的问题及改进意见', [], 'must', ['存在的问题']),
+    ],
+    '技术总结报告': [
+        ('项目简介', [], 'must', []),
+        ('主要研究内容开展及完成情况', ['项目研究总体设计与技术路线'], 'must',
+         ['主要研究的内容', '主要研究内容']),
+        ('技术创新成果', [], 'must', ['主要技术创新点', '技术创新点', '技术创新']),
+        ('存在的问题与建议', [], 'must', ['存在问题及建议', '存在的问题及建议', '存在问题与建议']),
+    ],
+    '项目验收报告': [
+        ('目标任务完成情况', ['项目主要研究内容', '考核技术指标', '考核经济指标',
+                              '考核社会生态效益指标', '考核科技产出指标'], 'must', []),
+        ('项目经费决算表', [], 'must', ['经费决算']),
+        ('项目主要参加人员名单', [], 'must', ['主要参加人员']),
+        ('验收委员会名单', [], 'must', ['验收委员会']),
+        ('项目验收意见', [], 'must', ['验收意见']),
+    ],
+    '项目验收申请表': [],          # 表单式：主体是字段表，无章节
+    '研发评价总结纪要': [],
+    '产品开发需求申请': [],
+    '项目开发需求申请': [],
+}
+
+# 表单式文档的必填字段（缺项就会被退回，失分点几乎全在这里而不在文采）
+FORM_FIELDS = {
+    '项目验收申请表': ['项目名称', '项目承建单位', '项目立项文件', '项目编号', '项目负责人',
+                       '联系电话（手机）', '项目联系人', '项目起止时间', '合同规定验收时间',
+                       '项目承建单位申请意见', '项目经理意见', '技术分管副总意见', '总经理意见'],
+    '研发评价总结纪要': ['对外合作', '合作单位', '费用合计', '起止时间', '研发过程情况',
+                         '该项目的专利情况', '该项目研发存在的主要问题及今后的设想',
+                         '项目研究成果的主体内容', '分管副总意见', '总经理意见'],
+    '项目开发需求申请': ['项目名称', '版本号', '申请时间', '申请部门', '开发类型', '需求内容概述',
+                         '可行性分析', '需求申请人', '技术分管经理', '需求方部门领导',
+                         '技术分管副总', '需求方分管副总', '总经理'],
+    '产品开发需求申请': ['申请人', '申请部门', '申请日期', '项目名称', '提交时间',
+                         '产品功能及服务要求', '市场负责人意见', '技术负责人意见', '总经理意见'],
+}
+
+# 各文档必须有的签批栏（少一级签批 = 流程没走完，交上去会被退）
+APPROVALS = {
+    '立项申请书': ['技术负责人意见', '财务负责人意见', '总经理意见'],
+    '研发任务书': ['项目负责人意见', '技术负责人意见'],
+    '项目研发实施计划': ['项目经理意见', '分管副总意见'],
+    '研发进度报告': ['项目经理意见', '技术副总意见', '财务负责人意见', '市场负责人意见', '总经理意见'],
+    '项目验收申请表': ['项目经理意见', '技术分管副总意见', '总经理意见'],
+    '研发评价总结纪要': ['分管副总意见', '总经理意见'],
+    '项目开发需求申请': ['技术分管经理', '技术分管副总', '总经理'],
+}
+
+# ── 归档目录规范 ───────────────────────────────────────────────────────────
+# match 用正则而不是精确文件名：真实项目会把「6-研发实施计划」改成「6-项目研发实施计划」，
+# 按精确名核对会把改了名的合规文件误报成缺失。
+ARCHIVE_ITEMS = [
+    {'dir': '1-立项文档', 'kind': '项目建议书', 'file': '1-项目建议书.docx',
+     'match': r'项目建议书', 'required': True, 'stage': '立项'},
+    {'dir': '1-立项文档', 'kind': '可行性研究报告', 'file': '2-可行性研究报告.docx',
+     'match': r'可行性(研究)?报告|可研', 'required': True, 'stage': '立项'},
+    {'dir': '1-立项文档', 'kind': '立项申请书', 'file': '3-立项申请书.docx',
+     'match': r'立项申请书', 'required': True, 'stage': '立项'},
+    {'dir': '1-立项文档', 'kind': '项目立项的决议', 'file': '4-项目立项的决议.docx',
+     'match': r'立项的?决议', 'required': True, 'stage': '立项'},
+    {'dir': '', 'kind': '产品开发需求申请', 'file': '产品开发需求申请.docx',
+     'match': r'产品开发需求申请', 'required': True, 'stage': '需求'},
+    {'dir': '', 'kind': '项目开发需求申请', 'file': '项目开发需求申请.docx',
+     'match': r'项目开发需求申请', 'required': True, 'stage': '需求'},
+    {'dir': '', 'kind': '研发任务书', 'file': '5-研发任务书.docx',
+     'match': r'研发任务书', 'required': True, 'stage': '任务下达'},
+    {'dir': '', 'kind': '项目研发实施计划', 'file': '6-项目研发实施计划.docx',
+     'match': r'(研发|项目研发)实施计划', 'required': True, 'stage': '计划'},
+    {'dir': '7-进度表', 'kind': '项目研发进度表-计划', 'file': '1-项目研发进度表-计划.xlsx',
+     'match': r'进度表.*计划|进度计划', 'required': True, 'stage': '计划'},
+    {'dir': '', 'kind': '年度研发支出预算表', 'file': '8-研发支出预算表.xls',
+     'match': r'研发支出预算', 'required': True, 'stage': '预算'},
+    {'dir': '9-10验收', 'kind': '项目验收申请表', 'file': '项目验收申请表.docx',
+     'match': r'验收申请表', 'required': True, 'stage': '验收'},
+    {'dir': '9-10验收', 'kind': '项目验收报告', 'file': '项目验收报告.docx',
+     'match': r'验收报告', 'required': True, 'stage': '验收'},
+    {'dir': '9-10验收', 'kind': '工作总结报告', 'file': '工作总结报告.docx',
+     'match': r'工作总结报告', 'required': True, 'stage': '验收'},
+    {'dir': '9-10验收', 'kind': '技术总结报告', 'file': '技术总结报告.docx',
+     'match': r'技术总结报告', 'required': True, 'stage': '验收'},
+    {'dir': '9-10验收', 'kind': '研发评价总结纪要', 'file': '研发评价总结纪要.docx',
+     'match': r'研发评价总结纪要|评价总结纪要', 'required': True, 'stage': '验收'},
+    {'dir': '', 'kind': '档案清册', 'file': '档案清册.xlsx',
+     'match': r'档案清册', 'required': False, 'stage': '归档'},
+    {'dir': '', 'kind': '借阅台账', 'file': '借阅台账.xlsx',
+     'match': r'借阅台账', 'required': False, 'stage': '归档'},
+]
+
+# 周期性文档：份数是硬指标——12 期少一期，加计扣除与高企核查都会追问
+PERIODIC = [
+    {'kind': '研发进度报告', 'dir': '周期性文档/研发进度报告',
+     'pattern': '研发进度报告-{n:02d}.docx', 'match': r'研发进度报告[-_]?(\d{1,2})',
+     'bare': r'研发进度报告', 'freq': '月', 'count': 12, 'required': True},
+    {'kind': '月度验收报告', 'dir': '周期性文档/月度验收报告',
+     'pattern': '项目月度验收报告{n:02d}.docx', 'match': r'月度验收报告[-_]?(\d{1,2})',
+     'bare': r'月度验收报告', 'freq': '月', 'count': 12, 'required': True},
+    {'kind': '项目研发进度表-实际', 'dir': '7-进度表',
+     'pattern': '1-项目研发进度表-实际-第{n}季度.xlsx', 'match': r'实际[-_]?第?(\d)\s*季度',
+     'bare': r'项目研发进度表[-_]?实际', 'freq': '季', 'count': 4, 'required': True},
+    # 下面两类规范目录里有、但两个真实项目都没做——**列为选做**：
+    # 缺席不报缺，只是让 kind_of 认得出来（认不出会被归到「不在规范目录内」，
+    # 那等于告诉用户「这份文件不知道是什么」，比不列更糟）。
+    {'kind': '项目研发周报', 'dir': '周期性文档/工作周报',
+     'pattern': '项目研发周报-{n:02d}.docx', 'match': r'研发周报[-_]?(\d{1,2})',
+     'bare': r'研发周报', 'freq': '周', 'count': 52, 'required': False},
+    {'kind': '月度开发报告', 'dir': '周期性文档/月度开发报告',
+     'pattern': '项目月度开发报告{n:02d}.xlsx', 'match': r'月度开发报告[-_]?(\d{1,2})',
+     'bare': r'月度开发报告', 'freq': '月', 'count': 12, 'required': False},
+]
+
+# 阶段评审：每个阶段一份评审报告(xls) + 一份会议签到表(docx)，缺一半就是流程没闭环
+REVIEWS = [
+    {'stage': '立项', 'match': r'立项评审', 'report': '1-软件立项评审报告.xls',
+     'signin': '1-软件立项评审会议签到表.docx'},
+    {'stage': '设计', 'match': r'设计评审', 'report': '2-软件设计评审报告.xls',
+     'signin': '2-软件设计评审会议签到表.docx'},
+    {'stage': '测试用例', 'match': r'测试用例评审|软件测试评审', 'report': '3-系统测试用例评审报告.xls',
+     'signin': '3-系统测试用例评审会议签到表.docx'},
+    {'stage': '验收', 'match': r'验收评审', 'report': '4-项目验收评审报告.xls',
+     'signin': '4-项目验收评审会议签到表.docx'},
+    {'stage': '结项', 'match': r'结项评审', 'report': '5-项目结项评审报告.xls',
+     'signin': '5-项目结项评审会议签到表.docx'},
+]
+
+# 条件性目录：**只在发生了对应事件时才需要**，缺席不算缺陷（照抄模板目录去要求它们
+# 会对每个顺利执行的项目都误报一次——这类噪声比漏报更快让人关掉检查）
+CONDITIONAL = [
+    {'dir': '变更文档', 'when': '发生过人员/预算/范围/延期变更'},
+    {'dir': '委外文档', 'when': '有委外开发'},
+    {'dir': '测试文档', 'when': '有独立测试环节归档要求'},
+]
+
+# ── 模板残留 ───────────────────────────────────────────────────────────────
+# 模板里成片的「提示：…」是写作指引，正式文档必须删干净；XX/XXX 是待替换占位符。
+# 模板写给「填表人」的批注（不是写给读者的注释）。正式交付件里必须删干净。
+# 判据用**明确的指令性措辞**而不是笼统的「注：」——「注：数据口径以合同为准」是正经注释，
+# 「注：由项目单位如实填写实际完成情况，下同。」才是模板批注。两者只差几个字，判错就天天误报。
+TEMPLATE_NOTES = [
+    r'注[：:]\s*由[^。；\n]{0,24}(?:填写|摘抄|提供)',
+    r'请选择以下结论',
+    r'如实填写',
+    r'摘抄约定内容',
+    r'下同[。．]',
+    r'正式文档中需删除',
+    r'注[：:]\s*[^。；\n]{0,12}请(?:选择|填写|注明|按)',
+]
+# 需要勾选的选项：一组括号**一个都没填** = 这道题没做。
+# 只判括号不判方框：方框是多选/单选题，选完必然剩下未选项，剩几个是正常的。
+EMPTY_CHOICE_RE = re.compile(r'[（(][ 　]{1,6}[)）]')
+# 「已勾选」只认**勾选记号**，或两侧带空格的数字。
+# 不能把裸的「（1）」算作已勾——那是标题自动编号（本项目的四级标题就是「（1）」），
+# 一份带四级编号的文档会因此永远不报「选择项未勾」，静默漏报。
+FILLED_CHOICE_RE = re.compile(r'[（(][ 　]*[√✓✔☑■×✗xX][ 　]*[)）]'
+                              r'|[（(][ 　]+[\d一二三四五六七八九][ 　]+[)）]')
+# 方框型选择题：**一个都没勾** = 这道题一道都没做。
+# 与括号型分开判，判据也不同：方框常是多选，选完必然剩下未选项，「剩几个」不算问题；
+# 但整份文档里一个勾都找不到（真实归档的人员变更申请表就是「□是   □否」原样交出去），
+# 那就是从头到尾没人填过。
+EMPTY_BOX_RE = re.compile(r'[□☐]')
+FILLED_BOX_RE = re.compile(r'[■☑☒▣✔✓√]')
+
+# ── 模板写死的字数上限 ────────────────────────────────────────────────────
+# 模板正文里白纸黑字写着「（500字内）」「（200字内，包括立项文件号、合同号、研究起止时间）」。
+# 这不是建议而是填表要求：真实交付件把「项目立项背景」写到 4000+ 字（限 500），
+# 高企认定/加计扣除的审查人是按模板逐条核的。
+# 数字取自模板原文，不是我定的——改之前先去模板里找到那句话。
+WORD_LIMITS = [
+    ('工作总结报告', '项目立项背景', 500, ''),
+    ('工作总结报告', '项目立项的依据和来源', 200, '包括立项文件号、合同号、研究起止时间'),
+    ('技术总结报告', '项目简介', 500, '重点说明本项目解决的技术问题'),
+]
+# 超出多少才报：模板写「500字内」「500字左右」，卡死 500 会把 520 字也报出来，没意义。
+WORD_LIMIT_SLACK = 1.5
+
+# 跨文档类型的样板段落：同一段话逐字出现在**多种不同用途**的文档里。
+# 与「周期性文档雷同」不是一回事——那是 12 期月报互比（同类），
+# 这是一段 449 字的技术描述同时出现在项目建议书、进度报告、验收总结、研发任务书里。
+#
+# 阈值量自真语料：立项三件套（建议书→可研→立项申请书）共享背景是**正当的**，
+# 可研本就是建议书的展开——它们只占 3 种类型，所以门槛定在 **≥4 种**。
+# 真实两个项目分别有 13 段和 34 段越过这条线（后者最严重的一段横跨 9 种类型、20 份文件）。
+# 60 字下限排掉标题、表头、固定表述这些天然重复的短句。
+BOILER_MIN_CHARS = 60
+BOILER_MIN_KINDS = 4
+
+# 模板点名「这一节必须包含什么」。两个参考项目的立项依据都只写了「依据…文件精神」，
+# 文件号与合同号一个都没有——审查人按模板逐项对，这是当场会被问的。
+SECTION_MUST_MENTION = [
+    ('工作总结报告', '项目立项的依据和来源', [
+        ('立项文件号', re.compile(r'第?[〔\[(（]?\d{2,4}[〕\])）]?\s*[号第]|文件号|批复号')),
+        ('合同号', re.compile(r'合同[号编]|合同编号')),
+        ('研究起止时间', re.compile(r'20\d{2}\s*年.{0,6}(?:至|—|-|到).{0,6}20\d{2}\s*年|起止')),
+    ]),
+]
+
+# 签到表的与会人表：表头有「姓名」，底下却一行都没填 = 这个会没有任何与会记录。
+# 判建议档不判必修：纸质签到表原件常在线下，电子件留空是常见做法。
+SIGNIN_HEADER = ('姓名', '签名')
+
+# ── 项目名称 ─────────────────────────────────────────────────────────────
+# 「基于X的Y系统(的)研发」这一族。末尾不吃「项目」二字，否则会把
+# 「…系统的研发项目提供了以下平台」整句吞进来当成一个项目名。
+PROJECT_NAME_RE = re.compile(r'基于[一-龥]{2,14}?的?[一-龥]{2,16}?(?:系统|平台)(?:的研发|研发)?')
+# 简称是正常的：真实归档里「…系统的研发」「…系统研发」「…系统」三种写法混用 144 次，
+# 归一化后相等就一律放过——把它们报出来只会淹掉真正的错字。
+_NAME_TRIM = re.compile(r'的|\s|项目$|的研发$|研发$')
+
+
+def name_key(name):
+    """项目名归一化：去掉「的」、空白与「(的)研发/项目」后缀。
+    归一化后仍不相等，才可能是错字或另一个项目。"""
+    prev = None
+    cur = (name or '').strip()
+    while cur != prev:          # 「…系统的研发项目」要连剥两层
+        prev = cur
+        cur = _NAME_TRIM.sub('', cur)
+    return cur
+
+
+# 表单类归档件：会议名称/项目名称栏里**只该出现本项目**。
+# 真实归档两个项目各抓到一处：深度学习的结项评审签到表写着联邦学习的项目名，
+# 联邦学习的软件设计评审签到表写着「基于信用模型算法的供应商管理系统研发」——
+# 都是拿上一个项目的文件改的，改漏了标题。
+FORM_KINDS = ('签到表', '评审报告', '进度表', '预算表', '申请表', '申请书', '通知', '决议')
+
+# 这几类文档没有图基本说不过去——技术路线、架构、流程总要画出来
+FIGURE_EXPECTED = ('技术总结报告', '可行性研究报告', '项目建议书', '概要设计说明书',
+                   '详细设计说明书', '项目研发实施计划')
+
+# 验收/总结类文档的「实际完成情况」栏里，这些措辞等于承认没完成——
+# 而文档本身正在做验收。真实归档里出现过「进行中，指标为预计完成指标」，
+# 两个项目都有，专家审查栏还是空的。
+UNFINISHED_WORDS = ('进行中', '预计完成', '尚未完成', '暂未', '待完成', '未开展',
+                    '正在推进', '后续完成', '有待')
+# 验收类文档：这些栏位里出现未完成措辞才算问题（研究内容描述里出现是正常的）
+ACCEPT_KINDS = ('项目验收报告', '工作总结报告', '技术总结报告')
+
+LEAK_PATTERNS = [
+    ('hint', re.compile(r'提示[：:]'), 'error', '模板提示块未删除',
+     '模板里明确写了「正式文档中需删除提示内容」，留着交出去等于把说明书当正文'),
+    ('placeholder', re.compile(r'(?<![A-Za-z])XX+(?![A-Za-z])|××'), 'error', '残留 XX 占位符',
+     '模板占位没替换：XX 部 / XX 项目 / XX 年度'),
+    ('todo', re.compile(r'待补充|待完善|TBD|待定(?![常义])|此处填写|请填写'), 'warn', '留了待办占位',
+     ''),
+]
+
+# 全档一致性字段：这几个在真实归档里出错最多，逐份核对
+CONSISTENCY_FIELDS = ['项目名称', '项目编号', '项目负责人', '项目联系人',
+                      '联系电话', '建设单位', '起止时间']
+
+# 字段串位检测：这几个字段的取值有明确形态，填错位一眼可判
+FIELD_SHAPES = {
+    '联系电话': (re.compile(r'^\+?\d[\d\s\-]{6,19}$'), '应为电话号码'),
+    '项目联系人': (re.compile(r'^[^\d]{2,20}$'), '应为人名，不是号码'),
+    '项目负责人': (re.compile(r'^[^\d]{2,20}$'), '应为人名，不是号码'),
+    '编制人': (re.compile(r'^[^\d]{2,20}$'), '应为人名，不是号码'),
+}
+
+SPEC = {
+    'name': 'hengtong',
+    'label': '研发项目归档规范（编号目录体例：1 立项 / 5 任务书 / 6 实施计划 / 7 进度表 / '
+             '8 预算 / 9-10 验收 + 评审文件 + 周期性文档）',
+    'org_line': '{company}技术中心{dept}',
+    'cover_fields': FIELD_KEYS,
+    'items': ARCHIVE_ITEMS,
+    'periodic': PERIODIC,
+    'reviews': REVIEWS,
+    'conditional': CONDITIONAL,
+    'sections': SECTIONS,
+    'form_fields': FORM_FIELDS,
+    'approvals': APPROVALS,
+    'consistency': CONSISTENCY_FIELDS,
+}
+
+
+def load(name_or_path='hengtong'):
+    """取规范。传路径则读自定义 JSON（只覆盖给出的键，其余沿用内置）。"""
+    s = str(name_or_path or 'hengtong')
+    if s in ('hengtong', '', 'default'):
+        return dict(SPEC)
+    if os.path.exists(s):
+        over = json.load(open(s, encoding='utf-8'))
+        out = dict(SPEC)
+        out.update(over)
+        return out
+    return dict(SPEC)
+
+
+def kind_of(filename, spec=None):
+    """按文件名判断这是哪一类文档（用正则，容忍改名）。认不出返回 None。"""
+    spec = spec or SPEC
+    base = os.path.basename(str(filename))
+    stem = os.path.splitext(base)[0]
+    for p in spec['periodic']:
+        if re.search(p['match'], stem):
+            return p['kind']
+    # 模板件没有期号（「XX项目研发进度报告-季度.docx」「2-项目研发进度表-实际.xlsx」），
+    # 带期号的正则认不出它们。认不出就会被归进「不在规范目录内」——
+    # 等于告诉用户「这份文件不知道是什么」，而它明明就是规范里的那一类。
+    for p in spec['periodic']:
+        if p.get('bare') and re.search(p['bare'], stem):
+            return p['kind']
+    for r in spec['reviews']:
+        if re.search(r['match'], stem):
+            return f"{r['stage']}评审" + ('签到表' if '签到' in stem else '报告')
+    # 长匹配优先：「项目验收申请表」不能被「验收报告」的规则先抢走
+    best = None
+    for it in spec['items']:
+        m = re.search(it['match'], stem)
+        if m and (best is None or len(m.group(0)) > best[1]):
+            best = (it['kind'], len(m.group(0)))
+    return best[0] if best else None
+
+
+def outline(kind, spec=None):
+    """出某类文档的 Markdown 骨架（章节 + 表单字段 + 签批栏）。"""
+    spec = spec or SPEC
+    secs = spec['sections'].get(kind)
+    if secs is None:
+        return f'未收录「{kind}」。已收录：' + '、'.join(spec['sections'])
+    out = [f'# {kind}', '']
+    fields = spec['form_fields'].get(kind)
+    if fields:
+        out += ['本类为**表单式**文档，主体是字段表（用 create_doc 的 type:"kv"），不是散文。字段：', '']
+        out += [f'- {f}：' for f in fields] + ['']
+    for title, subs, level, _al in secs:
+        out.append(f'## {title}' + ('' if level == 'must' else '（模板有，实践中常省略）'))
+        for s in subs:
+            out.append(f'### {s}')
+        out.append('')
+    ap = spec['approvals'].get(kind)
+    if ap:
+        out += ['## 审批栏（缺一级就是流程没走完）', ''] + [f'- {a}：' for a in ap] + ['']
+    return '\n'.join(out)
+
+
+def self_test():
+    assert field_key('项 目 名 称：') == '项目名称'
+    assert field_key('联 系 电 话') == '联系电话'
+    assert field_key('报告编写人') == '编制人'
+    assert field_key('编制日期') == '编制时间', '生成器用「编制日期」、模板用「编制时间」，别名必须打通'
+    assert kind_of('6-项目研发实施计划.docx') == '项目研发实施计划', kind_of('6-项目研发实施计划.docx')
+    assert kind_of('研发进度报告-03.docx') == '研发进度报告'
+    assert kind_of('1-项目研发进度表-实际-第2季度.xlsx') == '项目研发进度表-实际'
+    assert kind_of('软件立项评审报告_01.xls') == '立项评审报告'
+    assert kind_of('1-软件立项评审会议签到表.docx') == '立项评审签到表'
+    assert kind_of('项目验收申请表.docx') == '项目验收申请表', kind_of('项目验收申请表.docx')
+    assert kind_of('项目验收报告.docx') == '项目验收报告'
+    assert kind_of('毫不相干的文件.txt') is None
+    assert '项目考核指标' in outline('立项申请书')
+    assert '立项的背景与意义' in outline('可行性研究报告'), '可研必须用真实体例'
+    assert '技术负责人意见' in outline('立项申请书')
+    assert '表单式' in outline('项目验收申请表')
+    assert LEAK_PATTERNS[0][1].search('提示：这里要写清楚')
+    import re as _re
+    _tn = _re.compile('|'.join(TEMPLATE_NOTES))
+    for _t in ('注：由项目单位如实填写实际完成情况，下同。', '注：专家请选择以下结论。',
+               '注：由项目单位对照《立项申请书》摘抄约定内容'):
+        assert _tn.search(_t), _t
+    for _t in ('注：数据口径以合同附件三为准。', '注：金额单位为万元。', '注：本表由财务部填报后归档'):
+        assert not _tn.search(_t), f'正经注释被误判：{_t}'
+    assert EMPTY_CHOICE_RE.search('完成70%及以上（  ）') and not EMPTY_CHOICE_RE.search('（√）')
+    assert FILLED_CHOICE_RE.search('（√）') and FILLED_CHOICE_RE.search('（ 1 ）')
+    assert not FILLED_CHOICE_RE.search('（1）本节说明'), '标题编号「（1）」被当成了勾选'
+    assert not FILLED_CHOICE_RE.search('（二）技术路线'), '标题编号「（二）」被当成了勾选'
+    assert LEAK_PATTERNS[1][1].search('技术中心XX部') and not LEAK_PATTERNS[1][1].search('XXL 号')
+    ok, _ = FIELD_SHAPES['联系电话']
+    assert ok.match('13809475135') and not ok.match('陈波')
+    print(f'[archive_spec] self-test OK · {len(ARCHIVE_ITEMS)} 项必备文档 / '
+          f'{len(PERIODIC)} 类周期性（{sum(p["count"] for p in PERIODIC)} 期）/ '
+          f'{len(REVIEWS)} 个阶段评审 / {len(SECTIONS)} 类章节骨架')
+
+
+if __name__ == '__main__':
+    self_test()