@huicai/cli 2026.804.0 → 2026.1019.0

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

@@ -0,0 +1,599 @@
+# 从一张「项目档案卡」生成整套研发归档骨架（约 45 份文档 + 表格）。
+#
+# 为什么值得做：一个项目的归档件里，**真正需要人想**的只有那几件事——项目名称与编号、
+# 负责人与联系人、起止时间、考核指标、人员分工、里程碑、预算。其余四十多份文档的封面、
+# 目录编号、章节骨架、签批栏、12 期周期性报告、5 个阶段评审文件，全是这几件事的机械展开。
+# 人手抄这四十多遍，抄出来的就是真实归档里那些毛病：项目名称三种写法、编号两个值、
+# 联系人栏填成电话、12 期月度验收报告一份没交。
+#
+# **所有文档的封面字段都取自同一张卡**——跨文档一致性因此天然为真，
+# 而那恰恰是真实归档里最高频、也最难靠人工消灭的一类缺陷。
+#
+# 用法：python archive_build.py 档案卡.json 输出目录 [--only 研发任务书,立项申请书]
+
+import calendar
+import datetime
+import json
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import archive_spec as S          # noqa: E402
+
+
+def safe_name(name, max_bytes=180, fallback='未命名'):
+    """清洗成安全的文件/目录名：去非法字符 + **按字节截断**。
+
+    只去非法字符不够：多数文件系统的单段上限是 255 字节，一个 200 字的中文项目名
+    就是 600 字节，落盘直接 OSError。截断要按字节走且不能把多字节字符切一半。"""
+    s = re.sub(r'[\\/:*?"<>|\r\n\t]', '_', str(name or '')).strip().strip('.') or fallback
+    if len(s.encode('utf-8')) <= max_bytes:
+        return s
+    out, n = [], 0
+    for ch in s:
+        w = len(ch.encode('utf-8'))
+        if n + w > max_bytes - 3:
+            break
+        out.append(ch)
+        n += w
+    return ''.join(out) + '…'
+
+
+def _sibling(skill, mod):
+    """取同源技能的引擎（docx-author / xlsx-analysis）。缺席时给出可读原因而不是裸崩。"""
+    here = os.path.dirname(os.path.abspath(__file__))
+    d = os.path.join(os.path.dirname(os.path.dirname(here)), skill, 'scripts')
+    if d not in sys.path:
+        sys.path.insert(0, d)
+    return __import__(mod)
+
+
+# ── 档案卡 ─────────────────────────────────────────────────────────────────
+CARD_REQUIRED = ['项目名称', '项目编号', '项目负责人', '建设单位', '部门', '起止时间']
+CARD_DEFAULTS = {
+    '项目联系人': None,        # 缺省跟随项目负责人
+    '联系电话': '',
+    '编制人': None,            # 缺省跟随项目负责人
+    '年度': None,              # 缺省从起止时间取
+    '项目级别': 'B',
+    '项目类型': '新产品',
+    '预算': 0,
+    '考核指标': [],            # [[指标, 要求值, 测试方法/判定依据], …]
+    '人员': [],                # [[姓名, 单位, 职称/职务, 分工], …]
+    '里程碑': [],              # [[阶段, 任务, 处理人, 工时, 开始, 结束, 交付物], …]
+    '预算科目': [],            # [[科目, 全年金额], …]；缺省按研发费用归集口径给零表
+    '章节内容': {},            # {文档类型: {章节名: 正文}} —— 有多少填多少，其余出骨架
+}
+YEAR_RE = re.compile(r'(20\d{2})')
+
+
+def normalize_card(card):
+    c = dict(CARD_DEFAULTS)
+    c.update({k: v for k, v in (card or {}).items() if v is not None})
+    miss = [k for k in CARD_REQUIRED if not str(c.get(k) or '').strip()]
+    if miss:
+        raise ValueError('档案卡缺必填项：' + '、'.join(miss)
+                         + '（这几项决定全档一致性，没有它们生成出来的骨架必然对不上）')
+    c['项目联系人'] = c['项目联系人'] or c['项目负责人']
+    c['编制人'] = c['编制人'] or c['项目负责人']
+    if not c['年度']:
+        m = YEAR_RE.search(str(c['起止时间']))
+        c['年度'] = int(m.group(1)) if m else datetime.date.today().year
+    c['年度'] = int(c['年度'])
+    c['单位落款'] = f"{c['建设单位']}技术中心{c['部门']}"
+    return c
+
+
+def cover_fields(card, kind):
+    """统一封面信息栏。**唯一来源就是这张卡**，所以不可能出现填串或截断。"""
+    base = [['项目名称', card['项目名称']], ['项目编号', card['项目编号']],
+            ['项目负责人', card['项目负责人']], ['项目联系人', card['项目联系人']],
+            ['联系电话', card['联系电话']], ['编制人', card['编制人']]]
+    if kind in ('工作总结报告', '技术总结报告', '项目验收报告', '研发评价总结纪要'):
+        base = [['项目名称', card['项目名称']], ['项目编号', card['项目编号']],
+                ['建设单位', card['建设单位']], ['项目负责人', card['项目负责人']],
+                ['联系电话', card['联系电话']], ['编制人', card['编制人']]]
+    return base
+
+
+# ── 单份 docx ──────────────────────────────────────────────────────────────
+def _doc_blocks(kind, card, spec, inserts=None, tail=None, warns=None):
+    """章节骨架 + 表单字段表 + 签批栏。
+
+    inserts = {章节名: [块…]} —— 把表格**插进它该在的那一节里**，不是统统堆到文末。
+    位置错了不只是难看：档案体检的「立项考核指标 → 验收实测值」勾稽是按节取文的，
+    指标表落在节外，那条最值钱的检查就永远判成「这一节没有量化指标」。
+    """
+    blocks = []
+    inserts = inserts or {}
+    body = (card.get('章节内容') or {}).get(kind) or {}
+    form = spec['form_fields'].get(kind)
+    if form:
+        pairs = []
+        for f in form:
+            k = S.field_key(f)
+            pairs.append([f, str(card.get(k, '')) if k else str(body.get(f, ''))])
+        blocks.append({'type': 'kv', 'pairs': pairs})
+    for title, subs, _level, _al in spec['sections'].get(kind, []):
+        blocks.append({'type': 'h1', 'text': title})
+        if body.get(title):
+            blocks.append({'type': 'p', 'text': str(body[title])})
+        blocks.extend(inserts.get(title) or [])
+        for sname in subs:
+            blocks.append({'type': 'h2', 'text': sname})
+            if body.get(sname):
+                blocks.append({'type': 'p', 'text': str(body[sname])})
+            blocks.extend(inserts.get(sname) or [])
+    # 注入到「不存在的章节名」的内容**绝不能静默丢弃**：用户写了字，字却凭空消失，
+    # 而且没有任何提示——这是最坏的一种失败。原样排到文末并如实报出来。
+    used = {t for t, subs, _l, _a in spec['sections'].get(kind, []) for t in [t] + list(subs)}
+    extra_keys = [k for k in body if k not in used]
+    if extra_keys:
+        if warns is not None:
+            # 把**该类文档的规范章节列全**。只说「写错了」不给对的名字，
+            # 调用方（人或模型）没法自纠，只能一次次猜——真跑里模型自造的章节名
+            # 几乎没一个对得上，正文全被排到了文末。
+            warns.append(f'【{kind}】{extra_keys} 不是该类文档的规范章节，'
+                         f'已作为附加章节排在文末；该类文档的规范章节是：'
+                         f'{[t for t, _s, _l, _a in spec["sections"].get(kind, [])]}')
+        for k in extra_keys:
+            blocks.append({'type': 'h1', 'text': str(k)})
+            blocks.append({'type': 'p', 'text': str(body[k])})
+    blocks.extend(tail or [])
+    ap = spec['approvals'].get(kind)
+    if ap:
+        # 有的文档把审批本身就列为正式章节（立项申请书的「审批意见」、实施计划的「审批记录」）。
+        # 那种情况下只补签批表，不再另起一节——否则会生成两个同名章节，
+        # 而重复标题恰恰是本项目的单文档体检会报的问题。
+        titles = [t for t, _s, _l, _a in spec['sections'].get(kind, [])]
+        own = next((t for t in titles if t in ('审批意见', '审批记录')), None)
+        if not own:
+            blocks.append({'type': 'h1', 'text': '审批记录'})
+        blocks.append({'type': 'kv', 'pairs': [[a, ''] for a in ap]})
+    return blocks
+
+
+def _write_doc(kind, card, spec, path, title=None, inserts=None, tail=None,
+               numbering='cn', warns=None):
+    B = _sibling('docx-author', 'docx_build')
+    spec_doc = {
+        'profile': 'tech', 'numbering': numbering,
+        'title': title or f"{card['项目名称']}\n{kind}",
+        'subtitle': kind if not title else '',
+        'org': card['单位落款'], 'author': card['编制人'],
+        'doc_no': card['项目编号'],
+        # 落款日期必须跟着卡走：周期性文档各自落在当期期末，不是「生成当天」
+        'date': card.get('date'),
+        'cover_fields': cover_fields(card, kind),
+        # 封面信息栏必须是表格：只有表格形态才能被档案体检按「键→值」读出来核对
+        'cover_table': True,
+        'toc': bool(spec['sections'].get(kind)),
+        'header': f"{card['项目名称']} · {kind}",
+        'footer': card['单位落款'],
+        'blocks': _doc_blocks(kind, card, spec, inserts, tail, warns),
+        'inspect': False,
+    }
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    B.build(spec_doc, path)
+    return path
+
+
+# ── 表格件 ─────────────────────────────────────────────────────────────────
+PLAN_COLS = [('seq', '序列'), ('stage', '阶段名称'), ('task', '任务名称'), ('owner', '处理人'),
+             ('est', '预估工时'), ('start', '计划开始'), ('end', '计划结束'),
+             ('pct', '进度'), ('memo', '备注')]
+ACT_EXTRA = [('act_h', '实际工时'), ('act_s', '实际开始'), ('act_e', '实际结束')]
+
+BUDGET_ROWS = [
+    '一、内部研究开发投入额', '其中：人员工资', '福利费', '办公及通讯费', '差旅及交通费',
+    '服务费', '测试调试费', '无形资产摊销', '业务招待费', '其它', '折旧费用与长期费用摊销',
+    '二、委托外部研究开发投入额', '其中：境内的投入额', '境外的投入额',
+]
+
+
+def _write_plan(card, path, actual_quarter=None):
+    X = _sibling('xlsx-analysis', 'xlsx_build')
+    cols = list(PLAN_COLS)
+    if actual_quarter:
+        cols = PLAN_COLS[:7] + ACT_EXTRA + PLAN_COLS[7:]
+    rows = []
+    for i, m in enumerate(card['里程碑'], 1):
+        stage, task, owner, est, start, end = (list(m) + [''] * 6)[:6]
+        r = [i, stage, task, owner, est, start, end]
+        # 季度实际表是**累计**的：第 3 季度那张要含前两季度已完成任务的实际数据，
+        # 不是只填本季度发生的。真实归档正是这样（各季表的内容逐季变长）。
+        # 只填本季度会造出「进度标 1、实际日期却空着」的自相矛盾——
+        # 那恰恰是本项目的进度表体检会报的必修项。
+        done_by_now = bool(actual_quarter and _quarter_of(end)
+                           and _quarter_of(end) <= actual_quarter)
+        if actual_quarter:
+            r += [est if done_by_now else '', start if done_by_now else '',
+                  end if done_by_now else '']
+        r += [1 if done_by_now else 0, '']
+        rows.append(r)
+    title = f"{card['项目名称']}项目研发进度{'计划' if not actual_quarter else f'表-实际-第{actual_quarter}季度'}表"
+    X.build({'profile': 'plain', 'sheets': [{
+        'name': '任务计划', 'title': title,
+        'columns': [{'key': k, 'header': h,
+                     'format': 'int' if k in ('est', 'act_h', 'seq') else
+                               ('percent' if k == 'pct' else
+                                ('date' if k in ('start', 'end', 'act_s', 'act_e') else 'general'))}
+                    for k, h in cols],
+        'rows': rows, 'total': {'label': '合计', 'cols': ['est'] + (['act_h'] if actual_quarter else [])},
+    }], 'inspect': False}, path)
+    return path
+
+
+def _quarter_of(d):
+    m = re.search(r'(?:^|\D)(\d{1,2})\s*[-/月]', str(d or ''))
+    if not m:
+        return None
+    mm = int(m.group(1))
+    return (mm - 1) // 3 + 1 if 1 <= mm <= 12 else None
+
+
+def budget_unmatched(card):
+    """档案卡里对不上固定科目表的预算科目。
+
+    预算表的科目是**研发费用归集口径的固定一套**（模板原样），卡里写「人员费/设备费」
+    这类自造名字一个都对不上，`plan.get(name, 0)` 会让它们**静默变零**——
+    于是卡上预算 280 万、科目加总也 280 万（内部勾稽还是通过的），
+    生成出来的预算表却整张全零，没有任何提示。这是最难查的一类失败。
+    不做同义词猜测：「设备费」在这套口径里没有对应行（它属于折旧费用），
+    猜错的科目归集比留空更糟——只如实点名，把正确科目表给出来。
+    """
+    return [str(k) for k, _v in (card.get('预算科目') or []) if str(k) not in BUDGET_ROWS]
+
+
+def _write_budget(card, path):
+    X = _sibling('xlsx-analysis', 'xlsx_build')
+    plan = {str(k): float(v) for k, v in (card.get('预算科目') or [])}
+    rows = []
+    for name in BUDGET_ROWS:
+        total = round(plan.get(name, 0.0), 2)
+        # 12 个月按四舍五入平摊后**加起来往往不等于全年**（2600000/12×12 = 2600000.04）。
+        # 差额必须由末月吸收——预算表最忌讳的就是横向加总对不上全年数，
+        # 财务复核第一件事就是拿计算器横着加一遍。
+        per = round(total / 12, 2) if total else 0.0
+        months = [per] * 11 + [round(total - per * 11, 2)] if total else [0.0] * 12
+        rows.append([name] + months + [total])
+    cols = ([{'key': 'sub', 'header': '科目'}]
+            + [{'key': f'm{i}', 'header': f'{i}月', 'format': 'amount'} for i in range(1, 13)]
+            + [{'key': 'sum', 'header': '合计(元)', 'format': 'amount'}])
+    X.build({'profile': 'finance', 'sheets': [{
+        'name': '研发支出预算表', 'title': f"{card['部门']}{card['年度']}年度项目研发支出预算表",
+        'note': f"项目：{card['项目名称']}（{card['项目编号']}）　口径：研发费用归集口径，单位：元",
+        'columns': cols, 'rows': rows, 'total': {'label': '小计'},
+        'print': {'landscape': True},
+    }], 'inspect': False}, path)
+    return path
+
+
+REVIEW_ITEMS = ['立项申请书', '项目建议书', '可行性分析报告', '产品研发任务书',
+                '研发实施计划', '总体预算', '总体研发进度表']
+
+
+def _write_review(card, stage, path):
+    X = _sibling('xlsx-analysis', 'xlsx_build')
+    X.build({'profile': 'plain', 'sheets': [
+        {'name': '评审说明', 'title': f'{stage}评审报告',
+         'columns': [{'key': 'k', 'header': '项目'}, {'key': 'v', 'header': '内容'}],
+         'rows': [['项目名称', card['项目名称']], ['项目编号', card['项目编号']],
+                  ['项目经理', card['项目负责人']], ['评审方式', '中心正式评审'],
+                  ['评审内容', '；'.join(REVIEW_ITEMS)], ['评审日期', ''], ['评审地点', ''],
+                  ['评审准备总工作量', ''], ['评审会议时间长度', ''], ['问题跟踪工作量', '']]},
+        {'name': '评审小组',
+         'columns': [{'key': 'role', 'header': '角色'}, {'key': 'name', 'header': '姓名（电话）'},
+                     {'key': 'prep', 'header': '评审准备工作量（小时）', 'format': 'int'},
+                     {'key': 'meet', 'header': '评审会议工作量（小时）', 'format': 'int'}],
+         'rows': [[r, '', 0, 0] for r in ('主持人,评审人', '作者', '记录员,评审人',
+                                          '跟踪人,评审人', '评审人', '评审人')],
+         'total': {'label': '合计'}},
+        {'name': '评审记录',
+         'columns': [{'key': c, 'header': h} for c, h in
+                     [('id', 'ID'), ('desc', '问题描述'), ('by', '提出人'), ('fix', '解决建议'),
+                      ('way', '解决方式'), ('sev', '严重程度'), ('due', '预计解决时间'),
+                      ('who', '修改人'), ('track', '跟踪人'), ('sign', '跟踪意见、签字')]],
+         'rows': [[i] + [''] * 9 for i in range(1, 6)]},
+        {'name': '评审结论',
+         'columns': [{'key': 'k', 'header': '评审内容'}, {'key': 'v', 'header': '评审结论'}],
+         'rows': [[it, ''] for it in REVIEW_ITEMS] + [['是否需要重新评审', ''], ['缺陷跟踪计划', '']]},
+    ], 'inspect': False}, path)
+    return path
+
+
+# ── 周期性文档：内容从里程碑推导（这一层才是「自动化」的实质）──────────────
+def _month_progress(card, month):
+    """按里程碑推出这一期的进度叙述——真实进度报告里的「项目进度情况」正是这么写的。
+    没有里程碑数据就返回空，让人去写，**不编内容**。"""
+    ms = card.get('里程碑') or []
+    if not ms:
+        return '', ''
+    y = card['年度']
+    done, doing = [], []
+    for m in ms:
+        stage, task, owner, _est, start, end = (list(m) + [''] * 6)[:6]
+        em, sm = _month_of(end), _month_of(start)
+        if em and em <= month:
+            done.append(f'{stage}·{task}')
+        elif sm and sm <= month <= (em or 12):
+            doing.append(f'{stage}·{task}（{owner}）')
+    pct = round(len(done) / max(len(ms), 1) * 100)
+    last = calendar.monthrange(y, month)[1]
+    txt = (f'截至 {y} 年 {month} 月 {last} 日，项目累计完成 {len(done)}/{len(ms)} 项任务，'
+           f'整体进度约 {pct}%。')
+    if done:
+        txt += '本期已完成：' + '；'.join(done[-6:]) + '。'
+    if doing:
+        txt += '正在进行：' + '；'.join(doing[:6]) + '。'
+    return txt, f'{y}年{month:02d}月31日' if last == 31 else f'{y}年{month:02d}月{last}日'
+
+
+def _month_of(d):
+    m = re.search(r'(?:^|\D)(\d{1,2})\s*[-/月]', str(d or ''))
+    if not m:
+        return None
+    v = int(m.group(1))
+    return v if 1 <= v <= 12 else None
+
+
+def _period_end(year, n, count):
+    """这一期的落款日期：月度取当月最后一天，季度取季末最后一天。
+
+    十二期月报全盖「生成当天」是不对的——真实月报各自落在当期月末，
+    档案体检会（正确地）报「落款月份与期号对不上」。日期本来就算出来了，别丢掉。"""
+    if count == 12:
+        return year, n, calendar.monthrange(year, n)[1]
+    if count == 4:
+        m = n * 3
+        return year, m, calendar.monthrange(year, m)[1]
+    return None
+
+
+def _write_periodic(card, spec, root, kind, dirname, pattern, count):
+    made = []
+    for n in range(1, count + 1):
+        txt, _asof = _month_progress(card, n) if count == 12 else ('', '')
+        body = {'编写目的': f"通过本报告了解 {card['项目名称']} 在 {card['年度']} 年第 {n} "
+                            f"{'月' if count == 12 else '期'}的研发进度与经费执行情况。",
+                '项目进度情况': txt}
+        c2 = dict(card)
+        c2['章节内容'] = dict(card.get('章节内容') or {})
+        c2['章节内容'][kind] = {**(c2['章节内容'].get(kind) or {}), **{k: v for k, v in body.items() if v}}
+        pe = _period_end(card['年度'], n, count)
+        if pe:
+            c2['date'] = f'{pe[0]} 年 {pe[1]} 月 {pe[2]} 日'
+        p = os.path.join(root, dirname, pattern.format(n=n))
+        _write_doc(kind, c2, spec, p,
+                   title=f"{card['项目名称']}\n{kind}（{card['年度']}年{n:02d}月）")
+        made.append(p)
+    return made
+
+
+# ── 主流程 ─────────────────────────────────────────────────────────────────
+def build(card, out_root, spec_name='hengtong', only=None):
+    spec = S.load(spec_name)
+    card = normalize_card(card)
+    root = os.path.join(out_root, safe_name(card['项目名称']))
+    os.makedirs(root, exist_ok=True)
+    made, warns = [], []
+    want = set(only) if only else None
+
+    def need(kind):
+        return want is None or kind in want
+
+    bad_subs = budget_unmatched(card)
+    if bad_subs:
+        warns.append(f'档案卡的「预算科目」有 {len(bad_subs)} 项对不上研发费用归集口径 {bad_subs}，'
+                     f'这些金额不会进预算表（该行会是 0）；'
+                     f'可用科目：{BUDGET_ROWS}')
+    subs = sum(float(v) for _k, v in (card.get('预算科目') or []))
+    total = float(card.get('预算') or 0)
+    if subs and total and abs(subs - total) > max(1.0, total * 1e-6):
+        warns.append(f'预算科目加总 {subs:,.2f} 与档案卡的预算总额 {total:,.2f} 不符'
+                     f'（差 {subs - total:,.2f}）——这类数字在立项书、预算表、验收决算里都要出现，'
+                     f'先在卡上对平再生成')
+
+    known = set(spec['sections']) | {'研发进度报告', '月度验收报告', '评审签到表'}
+    unknown_kinds = [k for k in (card.get('章节内容') or {}) if k not in known]
+    if unknown_kinds:
+        # 可用类型**列全，不截断**。真跑里模型写了「项目工作总结报告」（正确是「工作总结报告」），
+        # 提示里的类型表被 `…` 截掉，它拿不到对的名字，只能反复猜——
+        # 报错说了「你写错了」却不说对的是什么，等于没报。
+        warns.append(f'档案卡的「章节内容」里有未收录的文档类型 {unknown_kinds}，这部分内容不会被使用；'
+                     f'可用类型：{sorted(known)}')
+
+    ind_rows = [['序号', '考核指标', '要求值', '测试方法/判定依据']] + \
+               [[i] + list(x)[:3] for i, x in enumerate(card['考核指标'], 1)]
+    ppl_rows = [['姓名', '单位', '职称/职务', '分工']] + [list(x)[:4] for x in card['人员']]
+
+    ind_tbl = {'type': 'table', 'rows': ind_rows, 'caption': '项目考核指标'}
+    ppl_tbl = {'type': 'table', 'rows': ppl_rows, 'caption': '项目主要参加人员'}
+    # 交付物清单必须落进计划类文档：它是「任务书 → 实施计划 → 验收报告」那条勾稽链的起点，
+    # 只躺在档案卡里等于没有——验收时按什么逐条核对？
+    dlv_rows = [['序号', '阶段', '任务', '交付物', '计划完成']] + [
+        [i, (list(m) + [''] * 7)[0], (list(m) + [''] * 7)[1],
+         (list(m) + [''] * 7)[6], (list(m) + [''] * 7)[5]]
+        for i, m in enumerate(card['里程碑'], 1)]
+    dlv_tbl = {'type': 'table', 'rows': dlv_rows, 'caption': '交付物与里程碑'}
+    plan = {
+        '项目建议书': ('1-立项文档/1-项目建议书.docx',
+                       {'项目团队': [ppl_tbl]}, []),
+        '可行性研究报告': ('1-立项文档/2-可行性研究报告.docx',
+                           {'项目实施主要内容、技术关键与创新点、预期目标': [ind_tbl],
+                            '承担单位和主要研究人员简况': [ppl_tbl]}, []),
+        '立项申请书': ('1-立项文档/3-立项申请书.docx',
+                       {'项目考核指标': [ind_tbl], '项目主要参加人员': [ppl_tbl]}, []),
+        '项目立项的决议': ('1-立项文档/4-项目立项的决议.docx', {}, [
+            {'type': 'p', 'text': f"经公司管理层会议决定，同意 {card['项目名称']}"
+                                  f"（项目编号 {card['项目编号']}）立项，研究开发起止时间为"
+                                  f"{card['起止时间']}，由{card['部门']}承担实施；"
+                                  f"财务部门设置研究开发项目费用核算账目，实行专账管理。"}]),
+        '产品开发需求申请': ('产品开发需求申请.docx', {}, []),
+        '项目开发需求申请': ('项目开发需求申请.docx', {}, []),
+        '研发任务书': ('5-研发任务书.docx',
+                       {'目标及要求': [{**ind_tbl, 'caption': '技术指标与判定依据'}],
+                        '项目人员': [{**ppl_tbl, 'caption': '项目人员'}],
+                        '项目开发计划': [dlv_tbl]}, []),
+        '项目研发实施计划': ('6-项目研发实施计划.docx',
+                             {'主要参与人员': [{**ppl_tbl, 'caption': '主要参与人员'}],
+                              '产品及成果': [{**dlv_tbl, 'caption': '交付物清单'}]}, []),
+        '项目验收申请表': ('9-10验收/项目验收申请表.docx', {}, []),
+        '项目验收报告': ('9-10验收/项目验收报告.docx',
+                         {'考核技术指标': [{'type': 'table', 'caption': '考核指标验收对照',
+                                            'rows': [['立项书规定技术指标', '实际完成情况', '专家审查意见']]
+                                                    + [[f'{x[0]} {x[1] if len(x) > 1 else ""}', '', ''] for x in card['考核指标']]}],
+                          '项目主要参加人员名单': [{**ppl_tbl, 'caption': '项目主要参加人员名单'}]}, []),
+        '工作总结报告': ('9-10验收/工作总结报告.docx',
+                         {'项目考核指标完成情况': [{'type': 'table', 'caption': '考核指标完成情况',
+                                                    'rows': [['序号', '合同规定', '实际完成内容', '完成评价']]
+                                                            + [[i, f'{x[0]} {x[1] if len(x) > 1 else ""}', '', ''] for i, x in enumerate(card['考核指标'], 1)]}]}, []),
+        '技术总结报告': ('9-10验收/技术总结报告.docx', {}, []),
+        '研发评价总结纪要': ('9-10验收/研发评价总结纪要.docx', {}, []),
+    }
+    for kind, (rel, ins, tail) in plan.items():
+        if not need(kind):
+            continue
+        try:
+            made.append(_write_doc(kind, card, spec, os.path.join(root, rel),
+                                   inserts=ins, tail=tail, warns=warns))
+        except Exception as e:
+            warns.append(f'{kind} 生成失败：{type(e).__name__}: {e}')
+
+    if need('项目研发进度表-计划'):
+        try:
+            made.append(_write_plan(card, os.path.join(root, '7-进度表', '1-项目研发进度表-计划.xlsx')))
+            for q in range(1, 5):
+                made.append(_write_plan(card, os.path.join(
+                    root, '7-进度表', f'1-项目研发进度表-实际-第{q}季度.xlsx'), actual_quarter=q))
+        except Exception as e:
+            warns.append(f'进度表生成失败：{type(e).__name__}: {e}')
+    if need('年度研发支出预算表'):
+        try:
+            made.append(_write_budget(card, os.path.join(
+                root, safe_name(f"8-{card['部门']}{card['年度']}年度项目研发支出预算表", 120)
+                + '.xlsx')))
+        except Exception as e:
+            warns.append(f'预算表生成失败：{type(e).__name__}: {e}')
+    for i, r in enumerate(spec['reviews'], 1):
+        if not need('评审文件'):
+            break
+        try:
+            made.append(_write_review(card, r['stage'], os.path.join(
+                root, '评审文件', f"{i}-{r['stage']}评审报告.xlsx")))
+            made.append(_write_doc('评审签到表', card, spec, os.path.join(
+                root, '评审文件', f"{i}-{r['stage']}评审会议签到表.docx"),
+                title=f"{card['项目名称']}\n{r['stage']}评审会议签到表",
+                tail=[{'type': 'table', 'caption': '与会人员签到',
+                        'rows': [['序号', '姓名', '部门', '职务', '签到']] + [[i2, '', '', '', ''] for i2 in range(1, 11)]}]))
+        except Exception as e:
+            warns.append(f"{r['stage']}评审文件生成失败：{type(e).__name__}: {e}")
+    for p in spec['periodic']:
+        if p['kind'].startswith('项目研发进度表'):
+            continue                       # 进度表在上面按季度单独出
+        # **选做的周期性文档不默认生成**：规范目录里列了周报（52 期）与月度开发报告，
+        # 但两个真实项目都没做。默认全生成会凭空多出六十多份没人要的文件。
+        # 想要就在 only 里点名。
+        if not p.get('required', True) and (want is None or p['kind'] not in want):
+            continue
+        if not need(p['kind']):
+            continue
+        if not str(p['pattern']).lower().endswith('.docx'):
+            # 这一层只会用 docx 建版器。把 docx 内容写进 .xlsx 文件名，
+            # 落盘时不报错，打开时才发现「不是有效的工作簿」——必须在这里挡住。
+            warns.append(f"{p['kind']} 的规范产物是 {os.path.splitext(p['pattern'])[1]} 而非 .docx，"
+                         f"本工具暂不生成，请按模板手工补")
+            continue
+        try:
+            made += _write_periodic(card, spec, root, p['kind'], p['dir'],
+                                    p['pattern'], p['count'])
+        except Exception as e:
+            warns.append(f"{p['kind']} 生成失败：{type(e).__name__}: {e}")
+
+    if want is None:
+        try:
+            made.append(_write_manifest(card, root, made))
+        except Exception as e:
+            warns.append(f'档案清册生成失败：{type(e).__name__}: {e}')
+    return root, made, warns
+
+
+def _write_manifest(card, root, made):
+    X = _sibling('xlsx-analysis', 'xlsx_build')
+    rows = []
+    for i, p in enumerate(sorted(set(made)), 1):
+        rel = os.path.relpath(p, root)
+        rows.append([i, os.path.dirname(rel) or '（根目录）', os.path.basename(rel),
+                     S.kind_of(os.path.basename(rel)) or '—',
+                     round(os.path.getsize(p) / 1024, 1) if os.path.exists(p) else 0, ''])
+    path = os.path.join(root, '档案清册.xlsx')
+    X.build({'profile': 'report', 'sheets': [{
+        'name': '档案清册', 'title': f"{card['项目名称']} 档案清册",
+        'note': f"项目编号 {card['项目编号']}　起止 {card['起止时间']}　编制 {card['编制人']}",
+        'columns': [{'key': 'no', 'header': '序号', 'format': 'int'},
+                    {'key': 'dir', 'header': '所在目录'}, {'key': 'f', 'header': '文件名'},
+                    {'key': 'kind', 'header': '文档类型'},
+                    {'key': 'kb', 'header': '大小(KB)', 'format': 'amount'},
+                    {'key': 'memo', 'header': '备注'}],
+        'rows': rows, 'total': {'label': '合计', 'cols': ['kb']},
+    }], 'inspect': False}, path)
+    return path
+
+
+def main(argv):
+    args = [a for a in argv if not a.startswith('--')]
+    if len(args) < 2:
+        print('用法：python archive_build.py 档案卡.json 输出目录 [--only 类型1,类型2] [--demo]')
+        return 2
+    only = None
+    for a in argv:
+        if a.startswith('--only'):
+            only = (a.split('=', 1)[1] if '=' in a else args[2] if len(args) > 2 else '').split(',')
+            only = [x.strip() for x in only if x.strip()] or None
+    card = json.load(open(args[0], encoding='utf-8'))
+    try:
+        root, made, warns = build(card, args[1], only=only)
+    except ValueError as e:
+        # 档案卡填得不对是**用户输入问题**，报「缺了哪几项」就够了。
+        # 前面缀个 ValueError: 只会让人以为是工具坏了——本项目的报错口径是「结论 + 下一步」。
+        print(json.dumps({'error': str(e)}, ensure_ascii=False))
+        return 1
+    except Exception as e:
+        print(json.dumps({'error': f'{type(e).__name__}: {e}'}, ensure_ascii=False))
+        return 1
+    print(json.dumps({'root': root, 'files': len(made), 'warnings': warns,
+                      'made': [os.path.relpath(p, root) for p in made]},
+                     ensure_ascii=False))
+    return 0
+
+
+DEMO_CARD = {
+    '项目名称': '基于知识图谱的智能客服系统研发', '项目编号': 'ZY202601001',
+    '项目负责人': '张工', '联系电话': '13800000000',
+    '建设单位': '示例科技股份有限公司', '部门': '研发一部',
+    '起止时间': '2026年1月1日至2026年12月31日', '预算': 3800000,
+    '考核指标': [['意图识别准确率', '≥ 92%', '标注集 5000 条离线评测'],
+                 ['平均响应时延', '≤ 300ms', '800 并发压测 P95'],
+                 ['人工转接率', '≤ 15%', '生产环境连续 30 天统计']],
+    '人员': [['张工', '研发一部', '高级工程师', '项目负责人'],
+             ['李工', '研发一部', '工程师', '算法开发'],
+             ['王工', '测试部', '工程师', '测试验证']],
+    '里程碑': [['需求分析', '需求调研与规格说明', '张工', 80, '2026-01-01', '2026-01-31', '需求规格说明书'],
+               ['设计', '总体与详细设计', '张工', 120, '2026-02-01', '2026-03-31', '设计说明书'],
+               ['开发', '知识图谱构建与对话引擎', '李工', 480, '2026-04-01', '2026-08-31', '可运行系统'],
+               ['测试', '功能与性能测试', '王工', 160, '2026-09-01', '2026-10-31', '测试报告'],
+               ['验收', '试运行与验收', '张工', 80, '2026-11-01', '2026-12-31', '验收报告']],
+    '预算科目': [['其中：人员工资', 2600000], ['服务费', 400000], ['测试调试费', 300000],
+                 ['办公及通讯费', 200000], ['差旅及交通费', 300000]],
+}
+
+if __name__ == '__main__':
+    if '--demo' in sys.argv:
+        out = [a for a in sys.argv[1:] if not a.startswith('--')] or ['.']
+        r, m, w = build(DEMO_CARD, out[0])
+        print(f'demo → {r}（{len(m)} 份）')
+        if w:
+            print('提示：' + '；'.join(w))
+        sys.exit(0)
+    sys.exit(main(sys.argv[1:]))