adspecs 0.1.19 → 0.1.21

package/skills/adspecs-export-word/SKILL.md

@@ -1,498 +1,498 @@
----
-name: "adspecs-export-word"
-description: "将 Markdown 文档导出为 Word (.docx)，自动生成封面页和目录索引页。支持单文件或批量目录转换。"
-argument-hint: "指定 .md 文件路径或目录路径，如 docs/20-prd/xxx.md 或 docs/30-system-design/"
-compatibility: "需要 Node.js (>= 18)"
-metadata:
-  author: "Qingwen Chen"
-user-invocable: true
-disable-model-invocation: false
----
-
-# Markdown 导出 Word (Export to Word)
-
-## 用户输入
-
-```text
-$ARGUMENTS
-```
-
-**必须** 在继续之前考虑用户输入（如果非空）。
-
-## 路径配置加载
-
-在开始执行之前，先确定输出目录：
-
-1. 检查项目根目录是否存在 `.adspecs/paths.json`
-2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
-3. 如果不存在或配置键缺失，使用下方表格中的默认值
-
-| 配置键             | 默认值                 | 用途                             |
-| ------------------ | ---------------------- | -------------------------------- |
-| `export_dir`       | `docs/90-export`       | Word 导出输出目录                |
-| `architecture_dir` | `docs/10-architecture` | 架构文档目录（读取项目模块信息） |
-
-将解析后的路径记为 `EXPORT_DIR` 和 `ARCH_DIR`，后续步骤中引用此变量而非硬编码路径。
-
-## 定位
-
-本 skill 专注于 **Markdown → Word (.docx) 文档导出**，自动完成：
-
-1. **封面页生成** — 包含项目名称、文档标题、版本号、日期、作者、审核人、批准人、公司 Logo、公司名称、文档编号、保密等级
-2. **目录索引页生成** — 基于 Markdown heading 结构自动生成目录（深度到 H3）
-3. **正文转换** — 将 Markdown 内容完整转换为 Word 格式，保持标题层级、表格、代码块、列表等格式
-
-**典型使用场景**：
-
-- 将 PRD、系统设计文档导出为 Word 供业务方/客户审阅
-- 将需求分析文档导出为正式交付物
-- 批量导出 `docs/` 目录下的文档供归档
-
-**技术实现**：使用 Node.js + `docx` + `marked` 库，零系统级依赖（不需要安装 pandoc）。
-
-## 执行前检查
-
-### 1. Node.js 可用性检查
-
-执行 `node --version`，确认 Node.js 已安装且版本 >= 18。
-
-**如果 Node.js 未安装**，输出安装指引：
-
-```
-❌ 未检测到 Node.js，请先安装：
-
-  Windows:
-    winget install OpenJS.NodeJS.LTS    # winget
-    choco install nodejs-lts            # Chocolatey
-    scoop install nodejs-lts            # Scoop
-
-  macOS:
-    brew install node@20                # Homebrew
-
-  Linux:
-    sudo apt install nodejs npm         # Debian/Ubuntu
-    sudo dnf install nodejs npm         # Fedora/RHEL
-
-  通用：
-    从 https://nodejs.org/ 下载安装 LTS 版本
-
-安装后重新执行本命令。
-```
-
-### 2. npm 依赖检查
-
-检查本 skill 的 Node.js 依赖是否已安装：
-
-```bash
-SKILL_DIR="<SKILL.md 所在目录>"
-cd "$SKILL_DIR/references"
-```
-
-执行 `npm ls docx marked`，检查依赖是否存在。
-
-**如果依赖未安装**（首次使用），自动执行安装：
-
-```bash
-cd "$SKILL_DIR/references" && npm install
-```
-
-安装成功后继续。安装失败则输出错误并终止。
-
-### 3. 检查扩展钩子（导出前）
-
-- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
-- 如果存在，读取它并查找 `hooks.before_export_word` 下的条目。
-- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
-- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
-- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
-  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
-  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
-- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
-- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
-  - **可选钩子** (`optional: true`):
-
-    ```
-    ## 扩展钩子
-
-    **可选前置钩子**: {extension}
-    命令: `/{command}`
-    描述: {description}
-
-    提示: {prompt}
-    执行: `/{command}`
-    ```
-
-  - **必选钩子** (`optional: false`):
-
-    ```
-    ## 扩展钩子
-
-    **自动前置钩子**: {extension}
-    执行: `/{command}`
-    EXECUTE_COMMAND: {command}
-
-    等待钩子命令结果后再继续执行。
-    ```
-
-- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
-
-## 参数解析
-
-从 `$ARGUMENTS` 中解析以下参数：
-
-### 位置参数（必选）
-
-| 参数          | 说明                                       | 示例                     |
-| ------------- | ------------------------------------------ | ------------------------ |
-| 文件/目录路径 | 要转换的 `.md` 文件或包含 `.md` 文件的目录 | `docs/20-prd/crm-prd.md` |
-
-### 可选标志
-
-| 标志              | 说明                                | 默认值           |
-| ----------------- | ----------------------------------- | ---------------- |
-| `--output <路径>` | 自定义输出路径（覆盖 `EXPORT_DIR`） | `{EXPORT_DIR}/`  |
-| `--no-cover`      | 跳过封面页生成                      | 生成封面页       |
-| `--no-toc`        | 跳过目录索引页生成                  | 生成目录         |
-| `--recursive`     | 目录模式下递归扫描子目录            | 仅扫描当前层     |
-
-### 参数解析流程
-
-1. 从 `$ARGUMENTS` 中分离位置参数和可选标志
-2. 如果位置参数为空 → 使用 **AskUserQuestion** 让用户选择文件或输入路径
-3. 判断位置参数是文件还是目录，确定工作模式
-
-## 项目元数据提取
-
-从以下来源提取封面页信息（优先级从高到低）：
-
-### 提取来源
-
-| 优先级 | 来源                                        | 可提取字段                                 |
-| ------ | ------------------------------------------- | ------------------------------------------ |
-| 1      | `.adspecs/project.json`                     | 项目名称、公司名、公司 Logo 路径、保密等级 |
-| 2      | Markdown 文件 YAML frontmatter / 头部元信息 | 文档标题、版本、模块编号、模块名称         |
-| 3      | `CLAUDE.md` 第一行 `#` 标题                 | 项目名称                                   |
-| 4      | `git config user.name`                      | 作者                                       |
-| 5      | 当前日期                                    | 创建日期                                   |
-| 6      | **AskUserQuestion** 交互补全                | 审核人、批准人、文档编号、保密等级         |
-
-### `.adspecs/project.json` 结构（可选）
-
-```json
-{
-  "project_name": "CRM 客户关系管理平台",
-  "project_short_name": "crm",
-  "company_name": "XX 科技有限公司",
-  "company_logo": "docs/assets/logo.png",
-  "confidentiality": "内部 — 机密"
-}
-```
-
-如果 `project.json` 不存在，从 `CLAUDE.md` 和 git config 提取，缺失字段用 AskUserQuestion 补全。
-
-### 元数据字段清单
-
-| 字段      | 变量名            | 提取方式                              | 必填 |
-| --------- | ----------------- | ------------------------------------- | ---- |
-| 文档标题  | `title`           | Markdown H1 或文件名                  | ✅   |
-| 副标题    | `subtitle`        | frontmatter 或模块名称                | —    |
-| 项目名称  | `project_name`    | project.json / CLAUDE.md              | ✅   |
-| 公司名称  | `company_name`    | project.json / 交互                   | ✅   |
-| 公司 Logo | `company_logo`    | project.json / `docs/assets/logo.png` | —    |
-| 作者      | `author`          | git config user.name                  | ✅   |
-| 审核人    | `reviewer`        | 交互补全                              | —    |
-| 批准人    | `approver`        | 交互补全                              | —    |
-| 版本号    | `version`         | frontmatter / 默认 "v1.0"             | ✅   |
-| 日期      | `date`            | 当前日期                              | ✅   |
-| 文档编号  | `document_number` | 自动生成或交互                        | —    |
-| 保密等级  | `confidentiality` | project.json / 默认 "内部使用"        | ✅   |
-
-### 文档编号自动生成规则
-
-格式：`DOC-{MODULE_ID}-{DOC_TYPE}-{SEQ}`
-
-- `MODULE_ID`：从文档内容或所在目录识别的模块编号（如 M03-02）
-- `DOC_TYPE`：从文档类型推断（PRD / BRD / SDD / TR / SOW 等）
-- `SEQ`：同类型文档序号，从 001 开始
-
-如无法自动生成，使用 AskUserQuestion 让用户输入或留空。
-
-### 元数据补全交互
-
-对于必填但无法自动提取的字段，使用 **AskUserQuestion** 一次性收集：
-
-```
-请补全以下封面页信息：
-- 审核人：{输入或留空}
-- 批准人：{输入或留空}
-- 文档编号：{自动生成值或自定义}
-- 保密等级：[公开 / 内部使用 / 机密 / 绝密]
-```
-
-## 执行步骤
-
-### 步骤 1：确定工作模式
-
-根据参数解析结果确定工作模式：
-
-| 模式       | 触发条件                    | 行为                                          |
-| ---------- | --------------------------- | --------------------------------------------- |
-| **单文件** | 参数是单个 `.md` 文件路径   | 转换该文件                                    |
-| **多文件** | 参数包含多个 `.md` 文件路径 | 逐个转换                                      |
-| **目录**   | 参数是目录路径              | 扫描目录下所有 `.md` 文件（排除 `README.md`） |
-| **交互**   | 参数为空                    | 使用 AskUserQuestion 选择文件或输入路径       |
-
-**目录模式扫描规则**：
-
-- 默认扫描当前层：`{dir}/*.md`
-- 带 `--recursive` 标志：`{dir}/**/*.md`
-- 排除：`README.md`、隐藏目录（`.git/`、`.claude/`、`.adspecs/`、`node_modules/`）中的文件
-- 列出待转换文件清单，显示给用户确认
-
-### 步骤 2：提取项目元数据
-
-按"项目元数据提取"章节的规则，从各来源提取封面页信息：
-
-1. 读取 `.adspecs/project.json`（如存在）
-2. 读取目标 `.md` 文件头部元信息（frontmatter 或 `> **版本**:` 格式）
-3. 读取 `CLAUDE.md` 提取项目名称
-4. 执行 `git config user.name` 获取作者
-5. 对缺失的必填字段使用 AskUserQuestion 补全
-
-将提取结果记为元数据 JSON 对象，后续步骤使用。
-
-### 步骤 3：执行 Node.js 转换脚本
-
-**确定路径变量**：
-
-```
-SKILL_DIR = SKILL.md 所在目录
-SCRIPT_PATH = "{SKILL_DIR}/references/md-to-docx.js"
-OUTPUT_DIR = --output 参数值 或 EXPORT_DIR（默认 docs/90-export）
-```
-
-如果输出目录不存在，自动创建。
-
-**构造元数据 JSON 字符串**：
-
-```json
-{
-  "title": "{文档标题}",
-  "subtitle": "{副标题}",
-  "project_name": "{项目名称}",
-  "company_name": "{公司名称}",
-  "company_logo": "{公司 Logo 路径}",
-  "author": "{作者}",
-  "reviewer": "{审核人}",
-  "approver": "{批准人}",
-  "version": "{版本号}",
-  "date": "{日期}",
-  "document_number": "{文档编号}",
-  "confidentiality": "{保密等级}"
-}
-```
-
-将 JSON 对象序列化为字符串，记为 `META_JSON`。
-
-#### 单文件模式
-
-```bash
-node "{SCRIPT_PATH}" \
-  --input "{INPUT_FILE}" \
-  --output "{OUTPUT_DIR}/{original_name}.docx" \
-  --meta '{META_JSON}'
-```
-
-附加标志：
-
-| 标志         | 脚本参数     |
-| ------------ | ------------ |
-| 跳过封面页   | `--no-cover` |
-| 跳过目录页   | `--no-toc`   |
-
-#### 目录批量模式
-
-```bash
-node "{SCRIPT_PATH}" \
-  --dir "{INPUT_DIR}" \
-  --output "{OUTPUT_DIR}/" \
-  --meta '{META_JSON}'
-```
-
-附加标志：
-
-| 标志         | 脚本参数      |
-| ------------ | ------------- |
-| 跳过封面页   | `--no-cover`  |
-| 跳过目录页   | `--no-toc`    |
-| 递归扫描     | `--recursive` |
-
-**执行方式**：使用 Bash 工具执行 Node.js 命令。
-
-### 步骤 4：解析输出并生成报告
-
-脚本执行后，stdout 输出 JSON 格式的结果：
-
-```json
-{
-  "status": "success",
-  "files": [
-    { "input": "crm-prd.md", "output": "crm-prd.docx", "status": "ok" }
-  ],
-  "cover": true,
-  "toc": true,
-  "total": 1,
-  "success": 1,
-  "failed": 0
-}
-```
-
-根据 JSON 输出生成完成报告：
-
-```
-✅ Word 导出完成
-
-转换结果：
-| 序号 | 源文件 | 输出文件 | 状态 |
-|------|--------|----------|------|
-| 1    | {input} | {output} | ✅ 成功 |
-| ...  | ...    | ...      | ...  |
-
-封面页：{'✅ 已生成' 或 '❌ 已跳过 (--no-cover)'}
-目录页：{'✅ 已生成' 或 '❌ 已跳过 (--no-toc)'}
-
-输出目录：{OUTPUT_DIR}
-共转换 {total} 个文件，成功 {success} 个，失败 {failed} 个。
-```
-
-如果目录页已生成，追加提示：
-
-```
-💡 提示：在 Word 中打开文档后，右键点击目录区域选择"更新域"即可刷新目录页码。
-```
-
-**错误处理**：
-
-| 错误                          | 处理                                                              |
-| ----------------------------- | ----------------------------------------------------------------- |
-| 脚本输出 status = "error"     | 解析 JSON 中的 message 字段，输出错误详情                         |
-| Node.js 进程退出码非 0        | 输出 stderr 内容，提示用户检查 Node.js 安装和 Markdown 文件格式   |
-| `Cannot find module 'docx'`   | 在 `references/` 目录执行 `npm install` 后重试                    |
-| 图片资源找不到                | 脚本会在文档中插入 `[Image: path]` 占位文本，输出警告             |
-| 文件不存在                    | 提示用户检查输入路径                                              |
-
-## 必选执行后钩子
-
-**必须在向用户报告完成之前完成本节。**
-
-检查项目根目录是否存在 `.adspecs/extensions.yml`。
-
-- 如果不存在，或 `hooks.after_export_word` 下没有注册钩子，跳到完成报告。
-- 如果存在，读取它并查找 `hooks.after_export_word` 下的条目。
-- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。
-- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
-- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
-  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
-  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
-- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
-- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
-  - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**：
-
-    ```
-    ## 扩展钩子
-
-    **自动钩子**: {extension}
-    执行: `/{command}`
-    EXECUTE_COMMAND: {command}
-    ```
-
-  - **可选钩子** (`optional: true`):
-
-    ```
-    ## 扩展钩子
-
-    **可选钩子**: {extension}
-    命令: `/{command}`
-    描述: {description}
-
-    提示: {prompt}
-    执行: `/{command}`
-    ```
-
-## 错误处理
-
-### 常见错误及解决方案
-
-| 错误                                  | 可能原因                                    | 解决方案                                                  |
-| ------------------------------------- | ------------------------------------------- | --------------------------------------------------------- |
-| `node: command not found`             | Node.js 未安装或不在 PATH 中                | 按安装指引安装 Node.js >= 18                              |
-| `Cannot find module 'docx'`           | npm 依赖未安装                              | 在 `references/` 目录执行 `npm install`                   |
-| `Cannot find module 'marked'`         | npm 依赖未安装                              | 在 `references/` 目录执行 `npm install`                   |
-| `JSON 解析失败`                       | `--meta` 参数 JSON 格式错误                 | 检查 JSON 字符串引号转义                                  |
-| `文件不存在`                          | 输入文件路径错误                            | 检查 `--input` 路径                                       |
-| `目录中未找到 .md 文件`              | 目录为空或扫描范围不足                      | 添加 `--recursive` 标志或检查目录路径                     |
-| 图片显示为占位文本                    | Markdown 中引用了不存在的图片               | 检查图片路径是否正确                                      |
-| 目录页码为空                          | Word TOC 域未更新                           | 在 Word 中右键目录选择"更新域"                            |
-| 中文乱码或方块字符                    | 系统缺少中文字体                            | 安装微软雅黑/宋体字体                                     |
-
-## 快速指南
-
-### 首次使用准备
-
-首次使用前需安装 npm 依赖（仅需执行一次）：
-
-```bash
-cd skills/adspecs-export-word/references && npm install
-```
-
-依赖包括：
-- `docx` (^9.x) — Word 文档生成库
-- `marked` (^15.x) — Markdown 解析器
-
-### 基本用法
-
-```bash
-# 转换单个文件
-/adspecs-export-word docs/20-prd/crm-prd.md
-
-# 转换目录下所有文件
-/adspecs-export-word docs/30-system-design/
-
-# 递归转换目录及子目录
-/adspecs-export-word docs/ --recursive
-
-# 指定输出路径
-/adspecs-export-word docs/20-prd/crm-prd.md --output /tmp/exports/
-
-# 不生成封面页和目录
-/adspecs-export-word docs/20-prd/crm-prd.md --no-cover --no-toc
-```
-
-### 封面页与目录
-
-封面页和目录由 Node.js 脚本自动生成：
-
-- **封面页内容**：从 `.adspecs/project.json` 和 Markdown 元信息自动提取
-- **封面页样式**：修改 `references/md-to-docx.js` 中的 `buildCoverPage()` 函数
-- **目录深度**：默认 Heading 1-3，Word 打开后需右键更新目录域
-
-### 与 project-init 集成
-
-执行 `/project-init` 时会自动：
-
-- 创建 `docs/90-export/` 输出目录
-- 生成 `.adspecs/project.json` 提供封面页元数据
-
-## 完成标志
-
-- [ ] Node.js 可用性已确认（版本 >= 18）
-- [ ] npm 依赖已安装（docx + marked）
-- [ ] 工作模式已确定（单文件/多文件/目录/交互）
-- [ ] 项目元数据已从配置文件和 git 提取
-- [ ] 缺失的必填元数据字段已通过 AskUserQuestion 补全
-- [ ] 元数据 JSON 已构造
-- [ ] Node.js 转换脚本已执行（`md-to-docx.js`）
-- [ ] 封面页已生成（除非 `--no-cover`）
-- [ ] 目录索引页已生成（除非 `--no-toc`）
-- [ ] 完成报告已输出（转换结果表 + 统计数据）
-- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过
+---
+name: "adspecs-export-word"
+description: "将 Markdown 文档导出为 Word (.docx)，自动生成封面页和目录索引页。支持单文件或批量目录转换。"
+argument-hint: "指定 .md 文件路径或目录路径，如 docs/20-prd/xxx.md 或 docs/30-system-design/"
+compatibility: "需要 Node.js (>= 18)"
+metadata:
+  author: "Qingwen Chen"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Markdown 导出 Word (Export to Word)
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+**必须** 在继续之前考虑用户输入（如果非空）。
+
+## 路径配置加载
+
+在开始执行之前，先确定输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键             | 默认值                 | 用途                             |
+| ------------------ | ---------------------- | -------------------------------- |
+| `export_dir`       | `docs/90-export`       | Word 导出输出目录                |
+| `architecture_dir` | `docs/10-architecture` | 架构文档目录（读取项目模块信息） |
+
+将解析后的路径记为 `EXPORT_DIR` 和 `ARCH_DIR`，后续步骤中引用此变量而非硬编码路径。
+
+## 定位
+
+本 skill 专注于 **Markdown → Word (.docx) 文档导出**，自动完成：
+
+1. **封面页生成** — 包含项目名称、文档标题、版本号、日期、作者、审核人、批准人、公司 Logo、公司名称、文档编号、保密等级
+2. **目录索引页生成** — 基于 Markdown heading 结构自动生成目录（深度到 H3）
+3. **正文转换** — 将 Markdown 内容完整转换为 Word 格式，保持标题层级、表格、代码块、列表等格式
+
+**典型使用场景**：
+
+- 将 PRD、系统设计文档导出为 Word 供业务方/客户审阅
+- 将需求分析文档导出为正式交付物
+- 批量导出 `docs/` 目录下的文档供归档
+
+**技术实现**：使用 Node.js + `docx` + `marked` 库，零系统级依赖（不需要安装 pandoc）。
+
+## 执行前检查
+
+### 1. Node.js 可用性检查
+
+执行 `node --version`，确认 Node.js 已安装且版本 >= 18。
+
+**如果 Node.js 未安装**，输出安装指引：
+
+```
+❌ 未检测到 Node.js，请先安装：
+
+  Windows:
+    winget install OpenJS.NodeJS.LTS    # winget
+    choco install nodejs-lts            # Chocolatey
+    scoop install nodejs-lts            # Scoop
+
+  macOS:
+    brew install node@20                # Homebrew
+
+  Linux:
+    sudo apt install nodejs npm         # Debian/Ubuntu
+    sudo dnf install nodejs npm         # Fedora/RHEL
+
+  通用：
+    从 https://nodejs.org/ 下载安装 LTS 版本
+
+安装后重新执行本命令。
+```
+
+### 2. npm 依赖检查
+
+检查本 skill 的 Node.js 依赖是否已安装：
+
+```bash
+SKILL_DIR="<SKILL.md 所在目录>"
+cd "$SKILL_DIR/references"
+```
+
+执行 `npm ls docx marked`，检查依赖是否存在。
+
+**如果依赖未安装**（首次使用），自动执行安装：
+
+```bash
+cd "$SKILL_DIR/references" && npm install
+```
+
+安装成功后继续。安装失败则输出错误并终止。
+
+### 3. 检查扩展钩子（导出前）
+
+- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.before_export_word` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选前置钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+  - **必选钩子** (`optional: false`):
+
+    ```
+    ## 扩展钩子
+
+    **自动前置钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    等待钩子命令结果后再继续执行。
+    ```
+
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
+
+## 参数解析
+
+从 `$ARGUMENTS` 中解析以下参数：
+
+### 位置参数（必选）
+
+| 参数          | 说明                                       | 示例                     |
+| ------------- | ------------------------------------------ | ------------------------ |
+| 文件/目录路径 | 要转换的 `.md` 文件或包含 `.md` 文件的目录 | `docs/20-prd/crm-prd.md` |
+
+### 可选标志
+
+| 标志              | 说明                                | 默认值           |
+| ----------------- | ----------------------------------- | ---------------- |
+| `--output <路径>` | 自定义输出路径（覆盖 `EXPORT_DIR`） | `{EXPORT_DIR}/`  |
+| `--no-cover`      | 跳过封面页生成                      | 生成封面页       |
+| `--no-toc`        | 跳过目录索引页生成                  | 生成目录         |
+| `--recursive`     | 目录模式下递归扫描子目录            | 仅扫描当前层     |
+
+### 参数解析流程
+
+1. 从 `$ARGUMENTS` 中分离位置参数和可选标志
+2. 如果位置参数为空 → 使用 **AskUserQuestion** 让用户选择文件或输入路径
+3. 判断位置参数是文件还是目录，确定工作模式
+
+## 项目元数据提取
+
+从以下来源提取封面页信息（优先级从高到低）：
+
+### 提取来源
+
+| 优先级 | 来源                                        | 可提取字段                                 |
+| ------ | ------------------------------------------- | ------------------------------------------ |
+| 1      | `.adspecs/project.json`                     | 项目名称、公司名、公司 Logo 路径、保密等级 |
+| 2      | Markdown 文件 YAML frontmatter / 头部元信息 | 文档标题、版本、模块编号、模块名称         |
+| 3      | `CLAUDE.md` 第一行 `#` 标题                 | 项目名称                                   |
+| 4      | `git config user.name`                      | 作者                                       |
+| 5      | 当前日期                                    | 创建日期                                   |
+| 6      | **AskUserQuestion** 交互补全                | 审核人、批准人、文档编号、保密等级         |
+
+### `.adspecs/project.json` 结构（可选）
+
+```json
+{
+  "project_name": "CRM 客户关系管理平台",
+  "project_short_name": "crm",
+  "company_name": "XX 科技有限公司",
+  "company_logo": "docs/assets/logo.png",
+  "confidentiality": "内部 — 机密"
+}
+```
+
+如果 `project.json` 不存在，从 `CLAUDE.md` 和 git config 提取，缺失字段用 AskUserQuestion 补全。
+
+### 元数据字段清单
+
+| 字段      | 变量名            | 提取方式                              | 必填 |
+| --------- | ----------------- | ------------------------------------- | ---- |
+| 文档标题  | `title`           | Markdown H1 或文件名                  | ✅   |
+| 副标题    | `subtitle`        | frontmatter 或模块名称                | —    |
+| 项目名称  | `project_name`    | project.json / CLAUDE.md              | ✅   |
+| 公司名称  | `company_name`    | project.json / 交互                   | ✅   |
+| 公司 Logo | `company_logo`    | project.json / `docs/assets/logo.png` | —    |
+| 作者      | `author`          | git config user.name                  | ✅   |
+| 审核人    | `reviewer`        | 交互补全                              | —    |
+| 批准人    | `approver`        | 交互补全                              | —    |
+| 版本号    | `version`         | frontmatter / 默认 "v1.0"             | ✅   |
+| 日期      | `date`            | 当前日期                              | ✅   |
+| 文档编号  | `document_number` | 自动生成或交互                        | —    |
+| 保密等级  | `confidentiality` | project.json / 默认 "内部使用"        | ✅   |
+
+### 文档编号自动生成规则
+
+格式：`DOC-{MODULE_ID}-{DOC_TYPE}-{SEQ}`
+
+- `MODULE_ID`：从文档内容或所在目录识别的模块编号（如 M03-02）
+- `DOC_TYPE`：从文档类型推断（PRD / BRD / SDD / TR / SOW 等）
+- `SEQ`：同类型文档序号，从 001 开始
+
+如无法自动生成，使用 AskUserQuestion 让用户输入或留空。
+
+### 元数据补全交互
+
+对于必填但无法自动提取的字段，使用 **AskUserQuestion** 一次性收集：
+
+```
+请补全以下封面页信息：
+- 审核人：{输入或留空}
+- 批准人：{输入或留空}
+- 文档编号：{自动生成值或自定义}
+- 保密等级：[公开 / 内部使用 / 机密 / 绝密]
+```
+
+## 执行步骤
+
+### 步骤 1：确定工作模式
+
+根据参数解析结果确定工作模式：
+
+| 模式       | 触发条件                    | 行为                                          |
+| ---------- | --------------------------- | --------------------------------------------- |
+| **单文件** | 参数是单个 `.md` 文件路径   | 转换该文件                                    |
+| **多文件** | 参数包含多个 `.md` 文件路径 | 逐个转换                                      |
+| **目录**   | 参数是目录路径              | 扫描目录下所有 `.md` 文件（排除 `README.md`） |
+| **交互**   | 参数为空                    | 使用 AskUserQuestion 选择文件或输入路径       |
+
+**目录模式扫描规则**：
+
+- 默认扫描当前层：`{dir}/*.md`
+- 带 `--recursive` 标志：`{dir}/**/*.md`
+- 排除：`README.md`、隐藏目录（`.git/`、`.claude/`、`.adspecs/`、`node_modules/`）中的文件
+- 列出待转换文件清单，显示给用户确认
+
+### 步骤 2：提取项目元数据
+
+按"项目元数据提取"章节的规则，从各来源提取封面页信息：
+
+1. 读取 `.adspecs/project.json`（如存在）
+2. 读取目标 `.md` 文件头部元信息（frontmatter 或 `> **版本**:` 格式）
+3. 读取 `CLAUDE.md` 提取项目名称
+4. 执行 `git config user.name` 获取作者
+5. 对缺失的必填字段使用 AskUserQuestion 补全
+
+将提取结果记为元数据 JSON 对象，后续步骤使用。
+
+### 步骤 3：执行 Node.js 转换脚本
+
+**确定路径变量**：
+
+```
+SKILL_DIR = SKILL.md 所在目录
+SCRIPT_PATH = "{SKILL_DIR}/references/md-to-docx.js"
+OUTPUT_DIR = --output 参数值 或 EXPORT_DIR（默认 docs/90-export）
+```
+
+如果输出目录不存在，自动创建。
+
+**构造元数据 JSON 字符串**：
+
+```json
+{
+  "title": "{文档标题}",
+  "subtitle": "{副标题}",
+  "project_name": "{项目名称}",
+  "company_name": "{公司名称}",
+  "company_logo": "{公司 Logo 路径}",
+  "author": "{作者}",
+  "reviewer": "{审核人}",
+  "approver": "{批准人}",
+  "version": "{版本号}",
+  "date": "{日期}",
+  "document_number": "{文档编号}",
+  "confidentiality": "{保密等级}"
+}
+```
+
+将 JSON 对象序列化为字符串，记为 `META_JSON`。
+
+#### 单文件模式
+
+```bash
+node "{SCRIPT_PATH}" \
+  --input "{INPUT_FILE}" \
+  --output "{OUTPUT_DIR}/{original_name}.docx" \
+  --meta '{META_JSON}'
+```
+
+附加标志：
+
+| 标志         | 脚本参数     |
+| ------------ | ------------ |
+| 跳过封面页   | `--no-cover` |
+| 跳过目录页   | `--no-toc`   |
+
+#### 目录批量模式
+
+```bash
+node "{SCRIPT_PATH}" \
+  --dir "{INPUT_DIR}" \
+  --output "{OUTPUT_DIR}/" \
+  --meta '{META_JSON}'
+```
+
+附加标志：
+
+| 标志         | 脚本参数      |
+| ------------ | ------------- |
+| 跳过封面页   | `--no-cover`  |
+| 跳过目录页   | `--no-toc`    |
+| 递归扫描     | `--recursive` |
+
+**执行方式**：使用 Bash 工具执行 Node.js 命令。
+
+### 步骤 4：解析输出并生成报告
+
+脚本执行后，stdout 输出 JSON 格式的结果：
+
+```json
+{
+  "status": "success",
+  "files": [
+    { "input": "crm-prd.md", "output": "crm-prd.docx", "status": "ok" }
+  ],
+  "cover": true,
+  "toc": true,
+  "total": 1,
+  "success": 1,
+  "failed": 0
+}
+```
+
+根据 JSON 输出生成完成报告：
+
+```
+✅ Word 导出完成
+
+转换结果：
+| 序号 | 源文件 | 输出文件 | 状态 |
+|------|--------|----------|------|
+| 1    | {input} | {output} | ✅ 成功 |
+| ...  | ...    | ...      | ...  |
+
+封面页：{'✅ 已生成' 或 '❌ 已跳过 (--no-cover)'}
+目录页：{'✅ 已生成' 或 '❌ 已跳过 (--no-toc)'}
+
+输出目录：{OUTPUT_DIR}
+共转换 {total} 个文件，成功 {success} 个，失败 {failed} 个。
+```
+
+如果目录页已生成，追加提示：
+
+```
+💡 提示：在 Word 中打开文档后，右键点击目录区域选择"更新域"即可刷新目录页码。
+```
+
+**错误处理**：
+
+| 错误                          | 处理                                                              |
+| ----------------------------- | ----------------------------------------------------------------- |
+| 脚本输出 status = "error"     | 解析 JSON 中的 message 字段，输出错误详情                         |
+| Node.js 进程退出码非 0        | 输出 stderr 内容，提示用户检查 Node.js 安装和 Markdown 文件格式   |
+| `Cannot find module 'docx'`   | 在 `references/` 目录执行 `npm install` 后重试                    |
+| 图片资源找不到                | 脚本会在文档中插入 `[Image: path]` 占位文本，输出警告             |
+| 文件不存在                    | 提示用户检查输入路径                                              |
+
+## 必选执行后钩子
+
+**必须在向用户报告完成之前完成本节。**
+
+检查项目根目录是否存在 `.adspecs/extensions.yml`。
+
+- 如果不存在，或 `hooks.after_export_word` 下没有注册钩子，跳到完成报告。
+- 如果存在，读取它并查找 `hooks.after_export_word` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**：
+
+    ```
+    ## 扩展钩子
+
+    **自动钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+## 错误处理
+
+### 常见错误及解决方案
+
+| 错误                                  | 可能原因                                    | 解决方案                                                  |
+| ------------------------------------- | ------------------------------------------- | --------------------------------------------------------- |
+| `node: command not found`             | Node.js 未安装或不在 PATH 中                | 按安装指引安装 Node.js >= 18                              |
+| `Cannot find module 'docx'`           | npm 依赖未安装                              | 在 `references/` 目录执行 `npm install`                   |
+| `Cannot find module 'marked'`         | npm 依赖未安装                              | 在 `references/` 目录执行 `npm install`                   |
+| `JSON 解析失败`                       | `--meta` 参数 JSON 格式错误                 | 检查 JSON 字符串引号转义                                  |
+| `文件不存在`                          | 输入文件路径错误                            | 检查 `--input` 路径                                       |
+| `目录中未找到 .md 文件`              | 目录为空或扫描范围不足                      | 添加 `--recursive` 标志或检查目录路径                     |
+| 图片显示为占位文本                    | Markdown 中引用了不存在的图片               | 检查图片路径是否正确                                      |
+| 目录页码为空                          | Word TOC 域未更新                           | 在 Word 中右键目录选择"更新域"                            |
+| 中文乱码或方块字符                    | 系统缺少中文字体                            | 安装微软雅黑/宋体字体                                     |
+
+## 快速指南
+
+### 首次使用准备
+
+首次使用前需安装 npm 依赖（仅需执行一次）：
+
+```bash
+cd skills/adspecs-export-word/references && npm install
+```
+
+依赖包括：
+- `docx` (^9.x) — Word 文档生成库
+- `marked` (^15.x) — Markdown 解析器
+
+### 基本用法
+
+```bash
+# 转换单个文件
+/adspecs-export-word docs/20-prd/crm-prd.md
+
+# 转换目录下所有文件
+/adspecs-export-word docs/30-system-design/
+
+# 递归转换目录及子目录
+/adspecs-export-word docs/ --recursive
+
+# 指定输出路径
+/adspecs-export-word docs/20-prd/crm-prd.md --output /tmp/exports/
+
+# 不生成封面页和目录
+/adspecs-export-word docs/20-prd/crm-prd.md --no-cover --no-toc
+```
+
+### 封面页与目录
+
+封面页和目录由 Node.js 脚本自动生成：
+
+- **封面页内容**：从 `.adspecs/project.json` 和 Markdown 元信息自动提取
+- **封面页样式**：修改 `references/md-to-docx.js` 中的 `buildCoverPage()` 函数
+- **目录深度**：默认 Heading 1-3，Word 打开后需右键更新目录域
+
+### 与 project-init 集成
+
+执行 `/project-init` 时会自动：
+
+- 创建 `docs/90-export/` 输出目录
+- 生成 `.adspecs/project.json` 提供封面页元数据
+
+## 完成标志
+
+- [ ] Node.js 可用性已确认（版本 >= 18）
+- [ ] npm 依赖已安装（docx + marked）
+- [ ] 工作模式已确定（单文件/多文件/目录/交互）
+- [ ] 项目元数据已从配置文件和 git 提取
+- [ ] 缺失的必填元数据字段已通过 AskUserQuestion 补全
+- [ ] 元数据 JSON 已构造
+- [ ] Node.js 转换脚本已执行（`md-to-docx.js`）
+- [ ] 封面页已生成（除非 `--no-cover`）
+- [ ] 目录索引页已生成（除非 `--no-toc`）
+- [ ] 完成报告已输出（转换结果表 + 统计数据）
+- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过