docx-factory-for-jp-software（对日开发文档工厂）

定位：docx-style-replicator（单文档样式复刻）的项目级工厂升级。
底层引擎（样式提取/渲染/自检）复用同目录 scripts/ 下的确定性脚本；
本 skill 新增的是"编排层"：需求萃取、主数据、一键管线、AI 评审、捺印状态机。

核心原则（对日交付的命脉，全程必须遵守）

1. 式样书 = 准法律文件：没写进式样书的功能 = 无效需求；写了的功能必须可验证、
   可追溯、可审计。因此推测内容一律进"未確認事項リスト"，禁止脑补成需求。
2. トレーサビリティ（追溯链）：需求编号 R-XXX-### ↔ 画面功能采番 1010/1020…
   ↔ 测试用例编号 ↔ BUG 编号，四段编号链必须完整，下游只准引用已确认条目。
3. ステージゲート（阶段门）：每个阶段产物必须过"AI 评审 + 人工捺印"才能进入下一阶段；
   测试结果类文档（测试报告/検収書）禁止预生成——执行后回填再评审。
4. 版本规则（公司惯例）：V0.0.01 起；与客户交流修改 Inner+1；签字版 Major+1；
   发布后变更 Minor+1。版本履历表每次生成自动追加。

工作流（按顺序执行）

Step 0（可选）会议录音 → 会议纪要 md

• 录音转写优先用宿主平台的录音/转写工具（如豆包的录音工具）；转写出中日混杂 md 即可。
• 无转写工具时：让用户在对话里口述会议要点，直接进入 Step 1。

Step 1 会议纪要 → 规范需求 requirements.md

python <skill>/scripts/extract_requirements.py --input 会议纪要.md [--out requirements.md] \
    [--config llm_config.json]

• 产出必须符合 references/requirements-schema.md 的 8 节结构（含"7. 未確認事項リスト"）。
• 完成后人工通读：重点核对未確認事項是否齐全（这是对日交付的生命线）。

Step 2 requirements.md → 主数据 project_data.json

python <skill>/scripts/build_master_data.py --input requirements.md \
    --abbr TPM --project "设备预防保全管理系统" --customer "○○電機株式会社" \
    [--out project_data.json] [--config llm_config.json]

• 产出 project_data.json（唯一事实源，schema 见 references/master-data-schema.md）。
• 脚本自动校验：需求编号唯一合法、功能采番唯一、编号链不断裂；FAIL 则不出库。

Step 3 一键生成全套 DRAFT

# 方式 A（推荐）：从模板注册表自动选模板
python <skill>/scripts/pipeline.py --draft \
    --data project_data.json --requirements requirements.md \
    --template-name "要件定义书" --variant simple \
    --out-dir <输出目录> [--name-prefix 设备预防保全管理系统]

# 方式 B：显式指定模板 + spec
python <skill>/scripts/pipeline.py --draft \
    --data project_data.json --requirements requirements.md \
    --template <templates/specs/xxx/…/要件定义书.docx> \
    --spec <templates/specs/xxx/style_spec.json> \
    --out-dir <输出目录> [--name-prefix 设备预防保全管理系统]

• 模板族感知（Phase 2）：--template-name 按注册表 key 匹配（如"要件定义书""项目计划书""详细设计书"），
  --variant simple|detail|default 选简/详版——简版自动用 4 章渲染器（1 项目目的/2 功能需求/3 限制条件/4 成果物，
  公司惯例 <1人月用简版），详版用 6 章渲染器。模板 spec 无表格时自动生成标准网格表（表头主题蓝）。
• --docs "要件定义书,需求列表,功能列表" 控制本次生成的文档（渲染器按注册名匹配）。
• 内部自动：渲染 content.md → build_docx.py（保留模板页眉页脚/页面设置/主题色，
  表头主蓝 #2F5496、--clean-meta）→ check_deliverable.py 自检 → 回写 documents 状态。
• 模板注册（一次性）：python <skill>/scripts/register_templates.py --dir <贵司模板目录>
  自动：.doc COM 转换 → 样式提取 → 简/详版分级（文件名含"简版/详版"）→ xlsx 结构画像
  （sheet/维度/表头，供后续 openpyxl 原生生成）。公司模板不入 Git。

Step 4 AI 智能评审（Phase 3 已实现）

python <skill>/scripts/review_docs.py --data project_data.json --out-dir <输出目录> \
    [--config llm_config.json] [--machine-only] [--promote]

• 两层把关：
  1. 机器自检（确定性规则，零成本）：编号链完整性（需求↔功能↔采番）/ 验收标准缺失与模糊词扫描 /
     孤立需求 / 未確認事項覆盖 / 商务红线（测试结果·納品·検収类文档禁止预生成）/
     状态矛盾（文档 DRAFT 却大量需求标"确认済"）
  2. LLM 三视角挑刺：客户（我能看懂吗？未确认内容写成定论？语言版本？）/
     评审会（每条可测吗？验收标准？追溯性？边界异常？）/
     PM（未確認事項何时确认？延期风险？商务红线？合同金额/納期/承認期限）
• 产出 review_report.md，问题分级 P0 必须修 / P1 强烈建议 / P2 可选：
  P0>0 → 🔴 打回（禁止交付）；P0=0 且有 P1 → 🟡 有条件通过；全清 → 🟢 通过
• 修复闭环：改 requirements.md → 重跑 Step 2/3 → review_docs.py 复评，直到 P0=0
• --promote：评审通过时 documents 状态 DRAFT→STAGED（等待客户确认/捺印）
• LLM 输出截断自动恢复（chat_json 从右往左试闭合点解析）；LLM_MAX_TOKENS 环境变量可调

Step 5 捺印（Phase 4 启用）

python <skill>/scripts/pipeline.py --approve 要件定义书 --data project_data.json

• 回填承認栏（meta.承認者/承認日）、版本 Inner+1、文档 status→APPROVED、追加版本履历。
• 测试结果类文档：--fill（执行后回填测试结果）→ 再评审 → 才可 APPROVED。

LLM 后端切换（外部 API / 本地 AI）

全部判断型环节走 scripts/llm_client.py（纯标准库，OpenAI 兼容接口）：

模式	配置	说明
external	{"llm":{"provider":"external","external":{"base_url":"…/v1","api_key_env":"DEEPSEEK_API_KEY","model":"deepseek-chat"}}}	key 只从环境变量读（红线）
local	{"llm":{"provider":"local","local":{"base_url":"http://127.0.0.1:11434/v1","model":"qwen2.5:14b"}}}	Ollama/llama.cpp，先启动服务

python <skill>/scripts/llm_client.py --config llm_config.json --prompt "你好"   # 冒烟测试

环境变量覆盖：LLM_PROVIDER / LLM_BASE_URL / LLM_MODEL / LLM_API_KEY。

对日交付文档知识（内置常识，评审与生成共用）

阶段	成果物	注意点
提案	提案書/見積書/契約書	范围・工数・納期锁定
要件定义	業務/システム要件定義書、業務フロー、機能一覧	式样书准法律效力；未確認事項显式化
基本设计	画面/帳票/IF/ER/API 一覧	客户確認者・確認日字段
详细设计	モジュール/DB定義/API詳細	逻辑处理粒度到"写明对应处理"
制造	コード/コーディング規約/README/SBOM	提交记录带备注
测试	計画/仕様/結果報告/バグ管理	用例↔式样条款映射；预期结果精确到消息原文
纳品	移行計画/操作マニュアル/運用手順/検収書	納品物一览 + 発注者署名・印

贯穿管理：WBS、進捗報告、議事録、質問票（QA管理表）、変更管理票。

完整知识库：以上为简表；各文档可执行注意点、三视角评审检查表、调研溯源
见 references/jp-delivery-knowledge.md（评审与生成共用依据，驱动本 skill 前建议通读）。

注意事项

• 风格与内容解耦：模板只提供排版（字体/字号/表格/页眉页脚），章节内容全由
  requirements.md + project_data.json 驱动，换主题只需换需求输入。
• 公司模板隐私：templates/specs/ 与所有 .docx/.doc 已被 .gitignore 排除；
  上传 Git 前跑一遍 git status 确认没有模板与本地路径。
• 乱码防护（Windows）：含中文路径/内容时脚本内置 UTF-8；PowerShell 内联中文易碎，
  复杂命令写成 .py/.ps1 文件再执行。
• 纯 Python 标准库实现（llm_client 用 urllib），无需 pip 安装。