@zeyue0329/xiaoma-cli 1.12.0 → 1.13.0

package/demo/xiaoma-prd-saas-zh/product-brief.md

@@ -0,0 +1,97 @@
+---
+stepsCompleted:
+  - step-01-init
+  - step-02-vision
+  - step-03-users
+  - step-04-metrics
+  - step-05-scope
+  - step-06-complete
+inputDocuments: []
+date: '2026-04-22'
+author: 张明远
+---
+
+# Product Brief: 灵协 Linkly
+
+## Vision
+
+**愿景：** 让中型企业的客户成功（CS）团队在统一画布上看见、解读并干预客户旅程，把流失预警的"发现到触达"从平均 7 天压到 24 小时内。
+
+**核心问题：** 中型企业 CS 团队同时使用 4-6 个系统（CRM、客服、数据看板、IM、工单、合同），客户信号分散，CSM 平均每天花 90 分钟手动汇集信息，流失预警延迟 5-7 天，单人服务客户数受限。
+
+**价值主张：**
+
+- 跨系统聚合的客户旅程视图，单页可视化 ≥ 12 个月历史
+- LLM 自动摘要近 30 天高风险对话，CSM 平均处理时间从 18 分钟降至 6 分钟
+- 风险评分与触达建议同源，CSM 单人服务客户数从 30 提升至 40
+
+**差异化：**
+
+- 唯一同时整合"旅程画布 + LLM 摘要 + 风险评分"三能力的国内 SaaS
+- 国内同类产品（聚客云、客成 Pro）只覆盖其中 1-2 项
+
+## Target Users
+
+主要用户（primary）：
+
+- **客户成功经理（CSM）** — 直接对客户健康度负责，每日检视高风险客户并介入
+- **客服主管** — 负责团队 KPI、SLA、人力调度
+- **数据分析师** — 季度健康度报告、流失预测模型迭代
+
+次要用户（secondary）：
+
+- **租户管理员（Admin）** — 配置权限、订阅、集成
+- **产品经理（PM）** — 月度功能反馈分析
+
+不在目标用户中：
+
+- 一线客服坐席（已有 Salesforce Service Cloud / 钉钉客服覆盖）
+- 销售团队（CRM 主战场，本产品仅消费 CRM 数据）
+
+## Success Metrics
+
+候选指标（PM 在 PRD §2 中需补全 baseline / target / measurement / window）：
+
+- 流失预警触达率：从 30% 提升至 ≥ 95%
+- CSM 单人服务客户数：从 30 提升至 40
+- LLM 摘要采纳率：人工标注后采纳 ≥ 80%
+- 月度 SLA：99.9%
+- 试点客户 NPS：≥ 45（季度调研）
+- 12 个月内付费客户数：≥ 80
+- 单客户平均合同金额（ACV）：≥ 18 万元/年
+
+## Scope
+
+**In-Scope（MVP，2026 H2 上线）：**
+
+- 客户档案管理：多源聚合 · 标签 · 检索
+- 旅程画布：单租户视图 · 12 个月历史 · 时间轴
+- 风险预警：3 类规则引擎 · 工单系统单向集成
+- AI 摘要：近 30 天对话摘要 · 触达建议
+- 工单整合：钉钉 / 飞书 / Salesforce 单向同步
+- 租户与权限：4 角色 RBAC · 基础订阅层级（Starter/Team/Business）
+
+**Out-of-Scope：**
+
+- 海外多语：首期客户均为国内中型企业，海外需求量 < 5%
+- 自营客服坐席系统：与现有合作伙伴 Salesforce/钉钉客服重叠
+- 自营 CRM：仅消费现有 CRM 数据，不替代
+- 移动原生 App：MVP 仅 Web；移动需求由 PWA 满足
+
+**Future Phases：**
+
+- Growth（2027 Q1）：客户健康度模型可调校 · 移动 PWA · 多 LLM 厂商抽象层
+- Vision（2027 H2+）：自动触达执行（IM 推送 / 邮件）· 跨租户行业基准对比 · 海外多语
+
+**Constraints：**
+
+- 团队规模：2026 H2 前 8 人（含 PM、设计、前端 2、后端 3、数据 1）
+- 预算：年化研发投入 ¥6M
+- 时间：2026 H2 上线，节点：2026/06 内测、2026/09 公测、2026/12 GA
+- 数据本地化：所有客户数据仅存储于中国大陆 IDC
+
+## Differentiation
+
+- 国内同类产品对比：见 market-research-2026-q1.md §3 竞争分析
+- 技术新颖度：LLM 摘要 + 风险评分 + 旅程画布的三位一体集成在国内为首
+- 核心壁垒：旅程画布的多源聚合管线（≥ 12 个月历史）+ 可解释风险评分模型

package/demo/xiaoma-prd-saas-zh/validation-report.md

@@ -0,0 +1,279 @@
+---
+workflowType: 'prd-validation'
+prdFile: ./prd.md
+prdVersion: '1.0.0'
+rubricFile: '../../src/xmc/workflows/2-plan-workflows/xiaoma-validate-prd/data/prd-quality-rubric.csv'
+validationIteration: 1
+date: '2026-05-08'
+verdict: 'pass'
+totalScore: 97.5
+gatePassed: true
+---
+
+# PRD Validation Report — 灵协 Linkly v1.0.0
+
+> 本报告是 [prd.md](./prd.md) 跑完 `xiaoma-validate-prd` 13 步校验后的得分卡，演示 `prd-quality-rubric.csv` 的 13 维量化打分逻辑。
+
+## Verdict
+
+| 项                | 值          | 备注                                                |
+| ----------------- | ----------- | --------------------------------------------------- |
+| **Total Score**   | 97.5 / 100  | 加权总分（partial 按 50% 权重计入）                 |
+| **Blockers Failed** | 0         | D05 / D06 / D08 / D10 全 pass                       |
+| **Verdict**       | **pass** ✅ | 无 blocker 且总分 ≥ 80                              |
+| Validation Iteration | 1 / 3    | 首轮即 pass，无需重试                               |
+| Gate Threshold    | 80          | 已通过                                              |
+
+可进入下游 `xiaoma-create-epics-and-stories` 工作流。
+
+---
+
+## 13 维得分卡
+
+| ID  | 维度                      | step_ref                                         | 权重 | 状态     | 得分    | 严重度  |
+| --- | ------------------------- | ------------------------------------------------ | ---- | -------- | ------- | ------- |
+| D01 | Discovery Completeness    | step-v-01-discovery                              | 5    | pass     | 5.0     | minor   |
+| D02 | Format & Parity           | step-v-02-format-detection + step-v-02b          | 6    | pass     | 6.0     | major   |
+| D03 | Information Density       | step-v-03-density-validation                     | 10   | pass     | 10.0    | major   |
+| D04 | Brief Coverage            | step-v-04-brief-coverage-validation              | 8    | pass     | 8.0     | major   |
+| D05 | **Measurability**         | step-v-05-measurability-validation               | 12   | pass     | 12.0    | blocker |
+| D06 | **Traceability**          | step-v-06-traceability-validation                | 12   | pass     | 12.0    | blocker |
+| D07 | Implementation Leakage    | step-v-07-implementation-leakage-validation      | 8    | pass     | 8.0     | major   |
+| D08 | **Domain Compliance**     | step-v-08-domain-compliance-validation           | 10   | pass     | 10.0    | blocker |
+| D09 | Project-Type Fit          | step-v-09-project-type-validation                | 7    | pass     | 7.0     | major   |
+| D10 | **SMART (FR/NFR)**        | step-v-10-smart-validation                       | 12   | pass     | 12.0    | blocker |
+| D11 | Holistic Quality          | step-v-11-holistic-quality-validation            | 5    | partial  | 2.5     | minor   |
+| D12 | Completeness              | step-v-12-completeness-validation                | 5    | pass     | 5.0     | major   |
+| D13 | Dual-Audience Readiness   | step-v-13-report-complete (fused)                | 0    | pass     | (info)  | minor   |
+|     |                           | **TOTAL**                                        | 100  |          | **97.5**|         |
+
+---
+
+## 维度详情
+
+### D01 Discovery Completeness — pass
+
+- inputDocuments：3 个文件全部加载成功（product-brief.md / market-research-2026-q1.md / domain-research.md）
+- frontmatter `workflowType: 'prd'`：✅
+- frontmatter `templateVersion: '2.0-m1'`：✅
+
+### D02 Format & Parity — pass
+
+9 个必需章节全部以 `## N. <Name>` 形式存在：
+
+```
+## 1. Executive Summary
+## 2. Success Criteria
+## 3. Product Scope
+## 4. User Journeys
+## 5. Domain Requirements
+## 6. Innovation Analysis
+## 7. Project-Type Requirements
+## 8. Functional Requirements
+## 9. Non-Functional Requirements
+```
+
+格式：XiaoMa 2.0-m1（无需 parity check）。
+
+### D03 Information Density — pass
+
+| 信号关键词        | 命中数 | 阈值 |
+| ----------------- | ------ | ---- |
+| 打造              | 0      | < 3  |
+| 业界领先          | 0      | < 3  |
+| 一站式            | 0      | < 3  |
+| 赋能              | 0      | < 3  |
+| 数字化转型        | 0      | < 3  |
+| 智能化            | 0      | < 3  |
+| 全方位            | 0      | < 3  |
+| the system will   | 0      | < 3  |
+| in order to       | 0      | < 3  |
+| **Total fluff/100 lines** | **0** | **< 3** |
+
+§1 Executive Summary 直接量化（"7 天压到 24 小时"），无口号化。
+
+### D04 Brief Coverage — pass
+
+`contract-check.json` 验证通过：
+
+```json
+{
+  "passed": true,
+  "missing_required": [],
+  "missing_conditional": [],
+  "applied_policies": {},
+  "tbds": []
+}
+```
+
+product-brief.md 中所有 `required: yes` 字段均映射到 PRD 对应章节：
+
+| Brief 字段              | PRD 章节                                                        |
+| ----------------------- | --------------------------------------------------------------- |
+| vision_statement        | §1 Executive Summary（行 24）                                   |
+| core_problem            | §1 Executive Summary（行 26）                                   |
+| target_personas         | §1 + §4 全部 4 个 journey（CSM/Manager/分析师/Admin）            |
+| value_propositions      | §1 价值主张三条                                                 |
+| success_metrics_draft   | §2（SC-01..08 全覆盖 brief 中候选指标 + 添加 baseline/target）  |
+| mvp_scope               | §3 MVP 列表                                                     |
+| out_of_scope            | §3 Out-of-Scope（6 条）                                         |
+| differentiation         | §1 What Makes Special + §6 Innovation Analysis                  |
+
+### D05 Measurability — pass（blocker）
+
+**FR 分析（24 条）：**
+
+| 检查项               | 违规数 |
+| -------------------- | ------ |
+| 格式 `[Actor] can`   | 0      |
+| 主观形容词           | 0      |
+| 模糊量词             | 0      |
+| 实现泄漏             | 0      |
+| **FR violations**    | **0**  |
+
+**NFR 分析（10 条）：**
+
+| 检查项                   | 违规数 |
+| ------------------------ | ------ |
+| 缺测量方法               | 0      |
+| 缺数值阈值               | 0      |
+| 缺前置条件               | 0      |
+| **NFR violations**       | **0**  |
+
+总违规数 = 0（< 5 阈值），状态 pass。
+
+### D06 Traceability — pass（blocker）
+
+§Traceability Matrix（[prd.md 行 314-339](./prd.md)）含 24 行：
+
+- 24/24 FR 含 `Maps to Vision`
+- 22/24 FR 含 `Maps to Success Criteria`（FR-PROFILE-04 / FR-JOURNEY-04 / FR-RISK-04 / FR-SUMMARY-04 / FR-TENANT-01 / FR-TENANT-03 标注 "-" — Admin/Manager 配置类 FR 无直接 SC 映射，已合理化）
+- 24/24 FR 含 `Maps to Journey Step`
+
+无空 mapping 比例：0% < 20% 阈值，pass。
+
+### D07 Implementation Leakage — pass
+
+跨 §1, §2, §4, §8 扫描技术栈关键词：
+
+| 关键词             | §1 | §2 | §4 | §8 |
+| ------------------ | -- | -- | -- | -- |
+| Redis/Postgres/...  | 0 | 0  | 0  | 0  |
+| React/Vue/...       | 0 | 0  | 0  | 0  |
+| Docker/K8s/...      | 0 | 0  | 0  | 0  |
+| AWS/GCP/Azure       | 0 | 0  | 0  | 0  |
+
+§7 Project-Type Requirements 出现 "K8s HPA"（NFR-SCALE-02）属于可接受位置（基础设施约束）。
+
+### D08 Domain Compliance — pass（blocker）
+
+domain 检测：`general` + medium complexity（来自 frontmatter `domainTier: 'medium'` + project_type saas_b2b）。
+
+`domain-complexity.csv` 对 `general` 域要求 `special_sections: standard_requirements`。
+PRD §5 含 6 条具体可验证条款（5.1.1-5.1.6），且 §5.2 行业术语表 + §5.3 外部依赖均完整。
+
+虽然 domain=general 不是 high-complexity，但 PRD 主动覆盖了等保二级 + 个保法 + 数据本地化 + 审计日志 + 数据备份 + 数据导出 + 数据删除 7 个合规维度，超出 general 域要求。
+
+### D09 Project-Type Fit — pass
+
+`project-types.csv` 中 `saas_b2b` 行的 `required_sections`：
+
+```
+tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs
+```
+
+PRD §7 覆盖：
+
+| required_section    | §7 子节                  | 状态 |
+| ------------------- | ------------------------ | ---- |
+| tenant_model        | §7.1 多租户模型          | ✅   |
+| rbac_matrix         | §7.2 RBAC 角色矩阵       | ✅   |
+| subscription_tiers  | §7.3 订阅层级            | ✅   |
+| integration_list    | §7.4 集成清单（MVP）     | ✅   |
+| compliance_reqs     | §7.6 合规需求摘要        | ✅   |
+
+`skip_sections: cli_interface;mobile_first` — PRD 在 §3 Out-of-Scope 明确"MVP 仅 Web，移动需求由 PWA 满足"，已显式处理。
+
+### D10 SMART (FR/NFR) — pass（blocker）
+
+| FR/NFR 总数 | Specific | Measurable | Attainable | Relevant | Traceable | 复合需求 |
+| ----------- | -------- | ---------- | ---------- | -------- | --------- | -------- |
+| FR (24)     | 24/24    | 24/24      | 24/24      | 24/24    | 24/24     | 0        |
+| NFR (10)    | 10/10    | 10/10      | 10/10      | 10/10    | 10/10     | 0        |
+
+无单条 FR 含 `且|并|同时|以及`。所有 NFR 含 baseline + threshold + measurement method。
+
+### D11 Holistic Quality — partial ⚠️
+
+发现 1 处轻度跨节不一致：
+
+- §3 Out-of-Scope 列出 "自动触达执行（自动外呼 / 自动 IM）：MVP 仅生成建议，CSM 手动确认后执行"
+- §8.5 工单整合 包含 FR-TICKET-02（系统同步工单到外部）— 同步工单本身可视为"系统侧自动触达"
+- 风险：读者可能将 FR-TICKET-02 误读为"自动触达执行"被偷偷加回 MVP
+
+建议：在 §3 Out-of-Scope 第一条加注释，明确"自动触达执行"特指对客户的主动外呼/IM 推送，不含工单同步动作。修正后可升级为 pass。
+
+权重计算：5 × 50% = 2.5（partial 折半）。
+
+### D12 Completeness — pass
+
+| 章节                | 字符数 | 阈值     | 状态    |
+| ------------------- | ------ | -------- | ------- |
+| §1 Executive Summary| ~750   | > 200    | ✅      |
+| §2 Success Criteria | ~620   | > 200    | ✅      |
+| §3 Product Scope    | ~960   | > 200    | ✅      |
+| §4 User Journeys    | ~1850  | > 200    | ✅      |
+| §5 Domain Reqs      | ~1100  | > 200    | ✅      |
+| §6 Innovation       | ~580   | > 200    | ✅      |
+| §7 Project-Type     | ~880   | > 200    | ✅      |
+| §8 FR (24 items)    | ~1500  | > 200    | ✅      |
+| §9 NFR (10 items)   | ~720   | > 200    | ✅      |
+
+frontmatter 完整性：所有 M1 新增字段 (`templateVersion`, `densityLevel`, `domainTier`, `projectType`, `version`) 均填写。
+
+无残留 `{{...}}` 占位。
+
+### D13 Dual-Audience Readiness — pass（informational）
+
+| 检查项                                   | 状态 |
+| ---------------------------------------- | ---- |
+| Skim — 仅看 ## 头能理解结构              | ✅   |
+| Skip — 每节有 1-2 句开场总结             | ✅   |
+| Scan — 表格/列表/加粗承载密度数据        | ✅   |
+| Chunk — 一段一概念                       | ✅   |
+| Anchor — 所有 §N / FR-AREA-NN 引用一致   | ✅   |
+| Cite — 跨引使用全 ID                     | ✅   |
+| Forward-reference free                   | ✅   |
+| Section-local terminology                | ✅   |
+
+8/8 通过。informational 维度，不计入加权得分。
+
+---
+
+## 修复建议（按优先级）
+
+| # | 维度  | 问题                                       | 建议                                                                                  | 工作量 |
+| - | ----- | ------------------------------------------ | ------------------------------------------------------------------------------------- | ------ |
+| 1 | D11   | §3 自动触达描述与 §8.5 工单同步可能混淆    | §3 第一条 Out-of-Scope 加注释，明确"自动触达"特指对客户主动外呼/IM 推送，不含工单同步 | XS     |
+
+修复后预期总分：100 / 100。
+
+---
+
+## 与 prd-bad-examples.md 的对比
+
+将 [prd-bad-examples.md](./prd-bad-examples.md) 中 8 个反模式片段拼成的"坏 PRD"喂给同一份 rubric，预期得分卡完全不同：
+
+| 维度 | good 版本（本报告） | bad 版本（预期）       |
+| ---- | ------------------- | ---------------------- |
+| D03  | pass (10)           | partial (5) — AP-01 命中  |
+| D05  | pass (12)           | **fail (0)** — blocker |
+| D06  | pass (12)           | **fail (0)** — blocker |
+| D07  | pass (8)            | major (4) — Redis/React |
+| D08  | pass (10)           | **fail (0)** — blocker |
+| D10  | pass (12)           | **fail (0)** — blocker |
+| ...  | ...                 | ...                    |
+| 总分 | 97.5                | < 50                   |
+| Verdict | **pass**          | **reject**（≥ 4 blockers） |
+
+这一对比是 rubric 设计的核心校准目标。

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@zeyue0329/xiaoma-cli",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "XiaoMa Universal AI Agent Framework",
   "keywords": [
     "agile",

package/patent-disclosure-optimized/SKILL.md

@@ -248,30 +248,148 @@ compatibility: "Requires docx skill for Word document generation. Requires bash
 
 交底书输出为 .docx 格式。**必须先阅读 docx skill 获取 docx-js 最新的使用指南和注意事项**（路径通常在同级 skills 目录下的 `docx/SKILL.md`）。docx skill 中包含了完整的文档创建、验证流程和关键规则，务必遵循。
 
-### 5.1 文档格式要求
+> **格式权威参考**：本节给出的字体、字号、行距、颜色、首行缩进、对齐方式全部来自客户提供的《技术交底书模板.doc》。若客户另外给出模板文件，应以客户模板为准，并按相同方法（unpack → 读 styles.xml + document.xml）提取规范后覆盖此处默认值。
+>
+> 详细格式速查表见 `references/docx-format-spec.md`。
+> 已封装的转换实现见 `scripts/md2docx.js`（推荐直接调用，无需重复编写）。
+
+### 5.1 页面与基本参数
+
+| 项目 | 取值 | 备注 |
+| --- | --- | --- |
+| 纸张 | A4 | 宽 11906 × 高 16838 DXA |
+| 上下页边距 | 2.54cm（1440 DXA） | |
+| 左右页边距 | 3.17cm（1800 DXA） | 即模板默认值 |
+| 页码 | 底部居中，9pt | 用 `PageNumber.CURRENT` |
+| 默认颜色 | 黑色 `#000000` | 蓝色 `#0000FF` 仅用于占位提示语，正式内容一律用黑色 |
+
+### 5.2 四类段落样式（**严格执行**）
+
+字号单位说明：docx-js 的 `size` 字段使用半磅，10.5pt = 21，18pt = 36，9pt = 18。
+
+| 段落类型 | 触发条件 | 东亚字体 | 西文字体 | 字号 | 字形 | 对齐 | 行距 | 首行缩进 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 大标题 | 仅文档首行的「技术交底书」 | 楷体_GB2312 | Times New Roman | 18pt（sz=36） | 加粗 | 居中 | 固定 21pt（line=420 exact） | 无 |
+| 头部字段 | `**交底书名称：**…` `**本专利发明人：**…` `**技术问题联系人：**…` `**联系人电话：**…` `**E-MAIL：**…` 五行 | 仿宋_GB2312 | Times New Roman | 10.5pt（sz=21） | 加粗 | 左对齐 | 1.5x（line=360 auto） | 无 |
+| 章节标题 | Markdown `#` / `##` / `###` / `####` | 楷体_GB2312 | Times New Roman | 10.5pt（sz=21） | 加粗 | 左对齐 | 固定 21pt（line=420 exact） | 无 |
+| 正文 | 其余段落、列表、表格内文字 | 宋体 | Times New Roman | 10.5pt（sz=21） | 常规 | 两端对齐（both） | 1.5x（line=360 auto） | 2 个汉字（firstLine=420 twips） |
+| 行内代码 / 代码块 | `` `code` `` / ``` ``` ``` | 宋体（兜底） | Consolas | 10pt（sz=20） | 常规 | 左对齐 | 1.25x（line=300 auto） | 无；底色 `#F5F5F5` |
+| 表格表头 | 表格首行 | 宋体 | Times New Roman | 10.5pt | 加粗 | 居中 | 1.25x | — |
+| 表格单元格 | 表格其它行 | 宋体 | Times New Roman | 10.5pt | 常规 | 左对齐 | 1.25x | — |
+| 附图 | 独立成行的 `![alt](path)` | — | — | 等比缩放至内容宽度 540px / 高度上限 720px | — | 居中 | 1.5x | — |
+| 图注 | 紧跟附图，沿用 alt 文字 | 宋体 | Times New Roman | 10pt（sz=20） | 斜体 | 居中 | 1.25x | — |
+
+### 5.3 docx-js API 关键写法
+
+docx-js 中 `font` 字段必须显式区分四个槽位，否则东亚字体会被覆写：
+
+```js
+// ❌ 错误：name 会被同时填到 eastAsia，把中文字体清掉
+new TextRun({ text: "中文 English", font: { name: "Times New Roman", eastAsia: "宋体" } });
+
+// ✅ 正确：分别声明 ascii / hAnsi / cs / eastAsia
+new TextRun({
+  text: "中文 English",
+  font: { ascii: "Times New Roman", hAnsi: "Times New Roman", cs: "Times New Roman", eastAsia: "宋体" },
+  size: 21,
+  color: "000000",
+});
+```
+
+颜色字段必须传 6 位十六进制不带 `#`：
+
+```js
+new TextRun({ ..., color: "000000" }); // 全文统一黑色；蓝色 "0000FF" 仅用于占位提示
+```
+
+### 5.4 附图嵌入（**强制：必须真正嵌入图片，不可用文本描述代替**）
+
+代理人审阅交底书时需要直接看到附图。生成 docx 时，md 中的 `![alt](path)` 必须被解析为真实图片嵌入到对应位置，**严禁**保留 `[附图1 - 四遍扫描整体流程](media/doc1_fig1.png)` 这类纯文本形式。
+
+#### 5.4.1 Markdown 写法
+
+附图必须 **独立成行**：
+
+```markdown
+![附图1 - 四遍扫描整体流程](media/doc1_fig1.png)
+```
+
+不要把附图与正文混排在同一段；非独立行的 `![]()` 不会触发图片嵌入。
+
+#### 5.4.2 文件组织
 
-- 纸张：A4（docx-js 默认值，无需额外设置）
-- 正文字体：宋体/SimSun 小四（12pt）
-- 英文/数字字体：Times New Roman 12pt
-- 一级标题：黑体/SimHei 三号（16pt）加粗
-- 二级标题：黑体 四号（14pt）加粗
-- 三级标题：宋体 小四（12pt）加粗
-- 行距：1.5 倍行距（line spacing: 360 = 1.5x of 240 twips for 12pt）
-- 页边距：上下 2.54cm（约1440 DXA），左右 3.17cm（约1800 DXA）
-- 页码：底部居中
+- 每篇交底书 md 的同目录下建立 `media/` 子目录，把附图统一放在里面
+- 命名建议：`doc{交底书序号}_fig{图序}.png`，如 `media/doc1_fig1.png`、`media/doc2_fig3.png`
+- 路径解析以 md 文件所在目录为基准，支持相对路径或绝对路径
 
-### 5.2 生成流程
+#### 5.4.3 嵌入规则（已在 `scripts/md2docx.js` 中实现）
 
-1. 阅读 docx skill（`docx/SKILL.md`），遵循其中的创建文档流程和关键规则
-2. `npm install -g docx`（如果尚未安装）
-3. 用 JavaScript 通过 docx-js 库按上述格式生成文档
-4. 使用 docx skill 中的 `scripts/office/validate.py` 脚本校验生成的文件
-5. 将最终文件保存到用户的工作目录
+| 项 | 取值 |
+| --- | --- |
+| 支持格式 | png / jpg / jpeg / gif / bmp / svg |
+| 真实像素读取 | png：解析 IHDR 块；其它：按 4:3 兜底 |
+| 目标宽度 | 540 px（≈A4 内容区宽 8306 DXA 留少量边距） |
+| 高度上限 | 720 px；超限时按高度反算宽度 |
+| 缩放方式 | 等比，绝不拉伸 / 绝不裁剪 |
+| 图片段落 | 居中，1.5x 行距，段前 120 / 段后 40 twips |
+| 图注 | 自动用 `alt` 文本生成；居中宋体 10pt 斜体；alt 为空时不输出 |
+| 容错 | 图片不存在时插入红色 `[图片缺失] alt (src)`，不中断转换 |
 
-### 5.3 文档命名
+#### 5.4.4 docx-js 关键写法
+
+```js
+new ImageRun({
+  type: "png",                                // 必填
+  data: fs.readFileSync(absPath),
+  transformation: { width: 540, height: 360 },
+  altText: { title: alt, description: alt, name: path.basename(absPath) }, // 三字段全填
+});
+```
+
+`scripts/md2docx.js` 已封装路径解析、IHDR 读取、等比缩放、图注、容错；直接调用脚本即可，无需手写 ImageRun。
+
+### 5.5 生成流程
+
+推荐路径（无需重复造轮子）：
+
+1. 阅读 docx skill（`docx/SKILL.md`），掌握 docx-js 基本规则与 `scripts/office/validate.py` 的调用方式
+2. `npm install docx`（项目级或工作区）
+3. 把 md 与 `media/` 子目录放好；md 中通过 `![alt](media/xxx.png)` 引用附图
+4. 直接调用本技能自带的 `scripts/md2docx.js`：
+   ```bash
+   node patent-disclosure-optimized/scripts/md2docx.js \
+     专利交底书_<发明名称简写>_<YYYYMMDD>.md \
+     专利交底书_<发明名称简写>_<YYYYMMDD>.docx
+   ```
+   脚本会按 5.2 / 5.4 节规范自动处理：大标题、五个头部字段、章节标题、正文、表格、列表、代码块、**附图嵌入与图注**。
+5. 用 `docx/scripts/office/validate.py` 校验生成文件
+6. 解包抽样核对（**附图与字体颜色都要查**）：
+   ```bash
+   python scripts/office/unpack.py 输出.docx tmp/
+   grep -oE 'w:eastAsia="[^"]+"' tmp/word/document.xml | sort | uniq -c
+   grep -oE 'w:color w:val="[A-F0-9]+"' tmp/word/document.xml | sort | uniq -c
+   ls tmp/word/media/ | wc -l   # 内嵌图片数应等于 md 中独立 ![]() 行数
+   ```
+   期望：
+   - 楷体_GB2312（标题）≥ 章节数；仿宋_GB2312 = 5（五个头部字段）；其余 = 宋体
+   - 颜色仅 `000000`（除非保留蓝色占位语）
+   - **`tmp/word/media/` 下图片数 = md 中独立 `![](...)` 行数**
+7. 将最终文件保存到用户的工作目录
+
+### 5.6 文档命名
 
 `专利交底书_<发明名称简写>_<日期YYYYMMDD>.docx`
 
+### 5.7 客户给了不同模板的情况
+
+若客户提供新模板（如《技术交底书模板.doc》），按以下流程更新格式：
+
+1. 用 `soffice.py --convert-to docx` 把 .doc 转为 .docx
+2. `python scripts/office/unpack.py 模板.docx tmpl/` 解包
+3. 读 `tmpl/word/styles.xml`（默认 rFonts、字号、行距）与 `tmpl/word/document.xml`（实际样例段落的 rPr）
+4. 重点提取：默认字体（rFontsDefault）、行距（spacing.line + lineRule）、首行缩进（ind.firstLineChars / firstLine）、各类标题字体与颜色、占位提示语颜色（如 `0000FF`）
+5. 把新参数覆盖到 `scripts/md2docx.js` 顶部的常量（FONT_BODY_EAST / FONT_HEADING_EAST / FONT_TITLE_EAST / FONT_HEADER_FIELD_EAST / SIZE_BODY / SIZE_TITLE / BODY_LINE_SPACING / HEADING_LINE_SPACING / BODY_FIRST_LINE_INDENT），同时在本节表格里记录变更
+
 ---
 
 ## 工作流程总结