skill-forge-hub 0.1.0 → 0.3.0

package/magic-deck/user-config.md

@@ -0,0 +1,37 @@
+# 用户配置（升级技能时本文件不会被覆盖）
+
+> 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
+> 本文件始终保留你的版本——默认主题、页面尺寸、默认播放间隔、文件名、落盘目录放心改。
+> 官方升级若带来新配置点，会另存 `user-config.md.upstream` 对照文件到同目录，
+> 你按需查看并手动合并新配置点到本文件。
+
+
+## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+
+```yaml
+CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+
+# ── 落盘与外观 ──
+DIR: ~/Desktop            # 幻灯片 HTML 落盘目录
+FILENAME: auto            # 文件名（不含扩展名）：auto = 按本次内容主题+用途自动总结中文名（如「智能探针系统-产品介绍」，便于日后按名找回继续改）；也可口头指定文件名（永远优先）；或写死固定名如 slides（重名自动加日期后缀，不覆盖）
+OPEN_HTML: true           # 生成后自动打开浏览器放映
+THEME: tech               # 默认主题：tech 深蓝科技 / biz 浅色商务 / mono 极简黑白 / warm 温暖渐变（放映时工具栏可整份切换或「仅本页」单页换肤）
+TEMPLATE: classic         # 默认模板（版式骨架，与主题正交可自由组合）：classic 经典商务 / minimal 极简留白 / magazine 杂志画册 / keynote 黑金发布 / timeline 时间线叙事
+WIDTH: 1280               # 舞台宽度（16:9 基准，改宽高请同步改 deck-spec 同值）
+HEIGHT: 720               # 舞台高度
+SEC: 5                    # 自动播放默认间隔（秒，可选 3/5/8/10）
+
+# ── 播放行为 ──
+LOOP_DEFAULT: false       # 循环播放默认关（放映时可勾选）
+FROM_START_DEFAULT: true  # 从头播放默认开（取消勾选=从当前页继续）
+
+# ── 页脚署名 ──
+SIGNATURE: GENERATED BY SKILLFORGE   # 封面/结束页署名
+```
+
+
+## 📝 模板与主题（像真 PPT 一样可选）
+
+- **内置模板五套**（版式骨架，生成时生效）：classic 经典商务（默认）/ minimal 极简留白 / magazine 杂志画册 / keynote 黑金发布 / timeline 时间线叙事。改上方 `TEMPLATE` 即换默认，或生成时口头点名（如「用杂志风模板」）当次生效
+- **内置主题四套**（配色，放映时随时换）：tech / biz / mono / warm。工具栏色点点击=整份切换；点「⭮ 仅本页」后再点色点=只给当前页换肤，再点一次恢复整份模式
+- **自定义模板片段**（可选）：在 `resources/templates/` 下放 `my-*.html`（仅 body 内容片段，不含 html/head/script），生成时用户点名模板名即可套用；未点名用内置五套模板

package/meta-forge/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: meta-forge
+description: 锻造新技能的元技能（造 skill 的 skill）。按 SkillForge 工坊规范从需求出发生成完整技能包（薄入口 SKILL.md + 按阶段拆分的 resources/ + 用户配置 user-config.md），自动植入四大机制：CONFIG_VERSION 配置版本钥匙、user-config 配置抽离、reference 双轨（含 HTML 输出时）、文档同步自检纪律；技能入 SkillForge 仓库时同步登记 README 分类表与 cli.js CATEGORIES。当用户请求创建新技能、造一个 skill、做一个 XX 技能、把 XX 流程固化成技能，或询问 meta-forge 用法（怎么造技能/元锻炉怎么用）时使用。
+allowed-tools: Bash, Read, Write
+disable-model-invocation: false
+---
+
+# 元锻炉（meta-forge）
+
+把一段重复劳作锻造为标准技能包：薄入口 SKILL.md + 按阶段拆分的 resources/ + 用户配置 user-config.md，植入工坊四大机制后交付——产出可直接安装、可安全升级、可跨宿主迁移的技能。
+
+## 生成流程
+
+0. **读用户配置**（DIR/REGISTER/CONFIG_VERSION）→ 先 Read 同目录 `user-config.md`
+1. **需求澄清**（技能名、触发场景、产出形态、可配置项、是否含 HTML 输出、是否入仓库）→ 读 `resources/forge-rules.md` 的「一、澄清清单」
+2. **结构生成**（薄入口 + resources 拆分 + 咨询应答接线）→ 读 `resources/forge-rules.md` 的「二、结构规范」
+3. **机制植入**（CONFIG_VERSION 钥匙 / user-config 抽离 / reference 双轨 / 自检纪律，四大机制缺一不可）→ 读 `resources/forge-rules.md` 的「三、四大机制」
+4. **校验**（frontmatter 格式、resource 引用可达、配置抽离完整、旧词零残留）→ 读 `resources/forge-rules.md` 的「四、校验清单」
+5. **仓库登记**（技能入 SkillForge 仓库时：README 技能分类表/技能清单/目录结构 + cli.js CATEGORIES 同步登记，登记后跑 `skill-forge ls` 验证）→ 读 `resources/forge-rules.md` 的「五、仓库登记」
+6. **使用咨询**（用户只问「怎么造技能」等用法、未要求创建）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「元锻炉使用指南」），不创建任何文件
+
+## ⚙️ 配置与自定义
+
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（DIR/REGISTER/CONFIG_VERSION）都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
+
+## 配置版本机制（升级保护）
+
+本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
+
+1. 先将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`（同目录，绝不删除旧值）
+2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
+3. 更新 CONFIG_VERSION 为当前版本
+4. 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」
+
+升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
+
+## 文档同步自检纪律（维护者必读）
+
+修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如机制名/流程节点/字段名改名时新旧词全仓核对，旧词零残留才算完成）。修改 forge-rules.md 的机制规范必须同步检查本 SKILL.md 流程节点与 template/ 模板是否对齐，三者以 forge-rules.md 为规范真相源；改完后互相 grep 关键参数确认对齐。
+
+## 规则速览
+
+- 四大机制缺一不可：CONFIG_VERSION 钥匙（配置版本机制节 + user-config 配置块首行 CONFIG_VERSION: 1）、user-config 抽离（用户可改配置全部出站，SKILL.md 只引用不内嵌）、reference 双轨（含 HTML 输出的技能以 reference.html 为样式真相源）、自检纪律（改一处 grep 全仓）
+- 薄入口：SKILL.md 只留 frontmatter / 生成流程 / 配置节 / 机制节 / 规则速览；重内容按阶段拆 resources/，一文件一职责
+- 新技能必须带 user-config.md（含 CONFIG_VERSION: 1）与 resources/usage-guide.md（咨询应答原样输出源）
+- 完整规则（澄清清单 / 结构规范 / 四大机制 / 校验清单 / 仓库登记）见 `resources/forge-rules.md`

package/meta-forge/resources/forge-rules.md

@@ -0,0 +1,74 @@
+# 锻造规范（forge-rules）
+
+造一个新技能要过的全部关口：澄清清单 → 结构规范 → 四大机制 → 校验清单 → 仓库登记。本文档是 meta-forge 的规范真相源，SKILL.md 流程节点与 template/ 模板均与本文档对齐。
+
+## 一、澄清清单（开造前必问）
+
+以下问题未答清不动手：
+
+1. **技能名**：英文短横线（如 daily-report），与目录名一致，2-4 个单词
+2. **触发场景**：用户说什么话会触发？写进 description 的触发词；是否只在特定关键词出现时使用（如 speccore 专属技能）
+3. **产出形态**：对话输出？落盘文件（哪些格式）？HTML？截图？浏览器打开？
+4. **可配置项**：哪些行为用户会想改？→ 全部进 user-config.md
+5. **是否含 HTML 输出**：是 → 必须建 reference.html 双轨机制（机制三）；否 → 无此要求
+6. **归属**：入 SkillForge 仓库（需登记）还是独立技能（不登记）？
+
+## 二、结构规范（薄入口 + resources 拆分）
+
+```
+{skill-name}/
+├── SKILL.md               # 薄入口：frontmatter + 生成流程 + 配置节 + 机制节 + 规则速览
+├── user-config.md         # 用户可改配置（含 CONFIG_VERSION），升级永不覆盖
+└── resources/             # 重内容按生成阶段拆分，一文件一职责
+    ├── usage-guide.md     # 咨询应答原样输出源（必建）
+    └── {阶段名}.md        # 每个生成阶段一份，独立可读、不互相引用
+```
+
+- **SKILL.md 只保留**：frontmatter（name/description/allowed-tools/disable-model-invocation）、生成流程总览（每步标注读哪个 resource；第 0 步固定为「读用户配置 → 先 Read user-config.md」，最后一步固定为「使用咨询 → 读 usage-guide.md 原样输出」）、配置节、配置版本机制节、文档同步自检纪律节、规则速览（3-5 条硬性规则）
+- **resources/ 一文件一职责**：按生成阶段拆分；每份独立可读，不互相引用；SKILL.md 流程节点标注 `读 resources/xxx.md`
+- **咨询应答**：用户只问用法不要求生成时，读 resources/usage-guide.md 原样输出（首行标题按技能改为「XX使用指南」），不执行任何生成动作
+
+## 三、四大机制（缺一不可）
+
+### 机制一：CONFIG_VERSION 钥匙（配置版本机制）
+
+- user-config.md 的 yaml 块含 `CONFIG_VERSION: N`（初始 1），注释写明用途
+- SKILL.md 含「配置版本机制（升级保护）」节，声明当前版本 + 迁移四步（备份 .bak-时间戳 → 按规则迁移 → 更新版本号 → 对话告知用户）
+- 配置结构变化（增/删/改名键）时：CONFIG_VERSION 递增 1，SKILL.md 该节写明迁移规则
+- 双层校验：CLI update 比对官方/本地版本做备份+询问；AI 每次执行时自检版本，不一致按迁移规则处理
+- 禁止在未声明版本变更的情况下静默修改配置语义
+
+### 机制二：user-config 抽离（配置出站）
+
+- 用户可能改的一切配置（目录/格式/开关/角色/模板）全部放进 user-config.md，SKILL.md 只在第 0 步引用，不内嵌配置值
+- user-config.md 头部写「升级技能时本文件不会被覆盖」+ .upstream 对照说明
+- CLI 层：user-config.md 常驻保护（升级永不覆盖）+ 官方新配置另存 .upstream 对照
+
+### 机制三：reference 双轨（仅含 HTML 输出的技能）
+
+- resources/reference.html = 定稿样式真相源；SKILL.md 与样式文档的样式描述只是参数解释与禁止项
+- 生成 HTML 必须先 Read reference.html 与样式文档两份，以 reference.html 为骨架模板逐处替换数据
+- 修改 HTML 效果必须同步更新 reference.html + 样式文档描述，禁止只改一处；改完互相 grep 关键参数确认对齐
+- 铁律写入样式文档首段：「Reference 铁律（最高优先）」
+
+### 机制四：文档同步自检纪律
+
+- 修改技能任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（章节名/字段名/效果参数改名时新旧词全仓核对，旧词零残留才算完成）
+- 写入 SKILL.md「文档同步自检纪律（维护者必读）」节
+
+## 四、校验清单（交付前全过）
+
+1. frontmatter：name 与目录名一致且非占位符 skill-name；description 含触发词
+2. resource 引用可达：SKILL.md 每个 `读 resources/xxx.md` 的文件真实存在
+3. 配置抽离完整：SKILL.md 无内嵌配置值；user-config.md 含 CONFIG_VERSION: 1
+4. 四大机制四节齐全：配置节 / 配置版本机制节 / 自检纪律节 / usage-guide 接线
+5. 旧词零残留：全文 grep 无占位符、无废弃字段名
+6. 语言一致：正文中文；技术术语保留原文
+
+## 五、仓库登记（技能入 SkillForge 时）
+
+1. README.md「技能分类」表：有对应分类则收录，无则新增分类行（分类只按「最终产出」归类，一个技能只归一类）
+2. README.md「技能清单」表：新增一行（技能 / 分类 / 目录 / 一句话说明）
+3. cli.js 的 CATEGORIES 数组：同步登记（name/en/skills），与 README 分类表一致
+4. README「目录结构」图：按需补新技能目录
+5. 登记后跑 `skill-forge ls` 验证技能出现在正确分类下

package/meta-forge/resources/usage-guide.md

@@ -0,0 +1,41 @@
+# 元锻炉使用指南
+
+meta-forge 是「造 skill 的 skill」：把一段重复劳作，按 SkillForge 工坊规范锻造成完整技能包。
+
+## 能干什么
+
+- 一句话起造：「做一个 XX 技能」「把 XX 流程固化成技能」
+- 产出完整技能包：薄入口 SKILL.md + 按阶段拆分的 resources/ + 用户配置 user-config.md + 咨询应答 usage-guide.md
+- 自动植入四大机制（工坊标准，缺一不可）：
+  1. CONFIG_VERSION 钥匙——配置结构带版本号，升级时自动备份迁移，不丢用户设置
+  2. user-config 抽离——用户可改配置全部出站到 user-config.md，升级永不覆盖
+  3. reference 双轨——技能含 HTML 输出时，reference.html 是定稿样式真相源，改样式三处同步
+  4. 自检纪律——改任一文件 grep 全仓核对关键词，旧词零残留
+- 技能入 SkillForge 仓库时，自动登记 README 技能分类表/技能清单/目录结构与 cli.js CATEGORIES
+
+## 怎么用
+
+直接说需求即可，例如：
+
+- 「做一个会议纪要技能」→ 澄清需求后生成技能包
+- 「把 git 提交统计流程做成技能，含 HTML 报告」→ 生成并植入 reference 双轨机制
+- 「做一个 XX 技能，不用登记进仓库」→ 只生成技能包
+
+只问用法（如「元锻炉怎么用」）时，本指南原样输出，不创建任何文件。
+
+## 新技能长什么样
+
+```
+{skill-name}/
+├── SKILL.md               # 薄入口：frontmatter + 生成流程 + 配置节 + 机制节 + 规则速览
+├── user-config.md         # 用户可改配置（含 CONFIG_VERSION），升级永不覆盖
+└── resources/             # 重内容按生成阶段拆分，一文件一职责
+    ├── usage-guide.md     # 咨询应答原样输出源（必建）
+    └── {阶段名}.md        # 每个生成阶段一份，独立可读、不互相引用
+```
+
+## 常见问题
+
+- **和宿主自带的 create-skill / create-plugin 有什么区别？** 它们是宿主通用指引；meta-forge 是工坊专属流水线，产出直接符合 SkillForge 拆分规范与四大机制，可被 skill-forge CLI 安全升级
+- **生成后怎么用？** 技能包落盘到 DIR 配置的目录；要安装到 AI 助手，跑 `skill-forge init --skills <技能名>`
+- **已有技能怎么升级？** 官方配置结构变化时 CONFIG_VERSION 递增并写明迁移规则，`skill-forge update` 与 AI 执行时都会按版本备份迁移

package/meta-forge/user-config.md

@@ -0,0 +1,19 @@
+# 用户配置（升级技能时本文件不会被覆盖）
+
+> 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
+> 本文件始终保留你的版本——生成目录、登记方式放心改。
+> 官方升级若带来新配置点，会另存 `user-config.md.upstream` 对照文件到同目录，
+> 你按需查看并手动合并新配置点到本文件。
+
+
+## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+
+```yaml
+CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）DIR: auto                      # 新技能生成目录：auto = 探测 SkillForge 仓库根（~/SmartDeveloper/DevWorkspace/AI/SkillForge 或含 cli.js 的当前目录）；也可写死绝对路径
+REGISTER: true                 # 仓库登记：true = 生成后自动更新 README 技能分类表/技能清单与 cli.js CATEGORIES；false = 只生成技能包不登记
+```
+
+> 临时口头要求（仅对当次生效，不修改上方配置）：说「生成到 XX 目录」→ 当次改 DIR；说「不用登记」→ 当次 REGISTER=false。
+
+---
+> 更多用法见 SKILL.md 的「生成流程」与 resources/ 分册。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-forge-hub",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "SkillForge (技能锻造坊) — a curated collection of AI craft skills. Install once, then pick skills interactively: daily/weekly reports, article-to-HTML, SpecCore document converters.",
   "bin": {
     "skill-forge": "cli.js"
@@ -9,9 +9,12 @@
     "cli.js",
     "daily-report",
     "weekly-report",
+    "annual-report",
     "article-to-html",
+    "magic-deck",
     "spec-doc2spec",
     "spec-spec2doc",
+    "meta-forge",
     "template"
   ],
   "keywords": [

package/spec-doc2spec/SKILL.md

@@ -1,53 +1,73 @@
 ---
 name: spec-doc2spec
 description: >
-  SpecCore 文档导入专属 Skill（doc2spec）。仅在用户明确提到 speccore、迭代、期次、Spec、/doc2spec 等关键词，
-  或明确要求通过 speccore 导入需求文档时使用：将 PRD / Word / PDF 需求文档导入迭代目录，
-  产出需求文档与功能单元切片，后续可接 unitize / analyze / taskify 全流程。
-  参数提取与前置校验（文件存在性、格式检测）由 speccore ask 引擎执行；参数缺失时引擎输出 [SPECCORE_NEEDS_INFO] 交互式提示。
-  不影响 speccore ask 的意图识别能力。
-  不处理一般性的文档内容讨论（如「帮我看看这份文档讲了什么」），只处理 speccore 上下文中的文档导入。
+  文档转需求规格 Skill（doc2spec）。仅在用户要求把 PRD / Word / Markdown 需求文档转成结构化需求文档
+  （需求点提炼、功能单元切分）时使用。Pandoc 负责 Word→Markdown 机械转换，AI 全程参与校对防错——
+  Pandoc 对复杂表格（合并单元格拆裂）、文本框（内容丢失）、图片（EMF/WMF 浏览器不可渲染）、修订痕（删除线残留）
+  有已知局限，机械产物一律只作底稿，AI 对照原文逐段校对、纠错补漏后再加工成需求规格。
+  图片自动提取与目录组织（默认 assets/images/，可配置 IMG_DIR；EMF/WMF 自动检测并跨系统转 PNG）。
+  输出目录默认源文档同目录下 {文档名}-spec/ 子目录，可配置 OUTPUT_DIR。
+  跨系统适配 macOS / Windows / Linux（Pandoc 安装、EMF 转换工具链探测、路径引用）。
+  支持 .docx（Pandoc 转换）/ .md（直接读取）；.pdf 走 pdftotext 文本提取（无图）或提示先转 Word。
+  不处理一般性的文档内容讨论（如「帮我看看这份文档讲了什么」），只处理「文档 → 需求规格」的转换任务。
 allowed-tools: ["Bash", "Read", "Write", "Edit"]
 disable-model-invocation: false
 ---
 
 # 文档 → 需求规格（doc2spec）
 
-将需求文档（PRD / Word / PDF / Markdown）导入 SpecCore 迭代目录，产出 `010-requirements/` 下的需求文档与功能单元切片。.docx/.pdf 走 Pandoc 转换 + AI 双路交叉验证，导入后可继续 unitize 切分功能单元。
+将产品需求文档（PRD）转换为结构化的 Markdown 需求文档。分工原则：**Pandoc 负责机械转换，AI 负责校对防错与需求加工**——Pandoc 对复杂表格（合并单元格拆裂）、文本框（内容丢失）、图片（EMF 格式浏览器不可渲染）、修订痕（删除线残留）存在已知局限，机械产物一律只作底稿，AI 必须对照原文逐段校对、纠错补漏后再加工。
 
-## 前置依赖
+## 生成流程
 
-- SpecCore CLI 已安装（`speccore` 命令可用）
-- 项目已有迭代目录（无迭代时引擎会引导创建）
-- speccore ask 引擎随 SpecCore 提供：负责参数提取、前置校验（文件存在性、格式检测）与命令构造，本技能不自行解析参数
+0. **读用户配置**（OUTPUT_DIR/IMG_DIR/EMF_POLICY/CONFIRM/CONFIG_VERSION）→ 先 Read 同目录 `user-config.md`
+1. **依赖检测**（每次必做）→ `pandoc --version`；未安装按「安装指引」输出并停止，不执行任何转换命令
+2. **格式路由** → `.docx` 走 Pandoc 机械转换；`.md` 直接 Read 原文（跳过第 3 步转换，第 4 步校对照做）；`.pdf` 走 `pdftotext` 文本提取（仅文本、无图无版式）或提示用户先转 Word
+3. **Pandoc 机械转换** → `pandoc <输入.docx> -f docx -t gfm --extract-media=<IMG_DIR> -o 00-converted.md`（标题/表格/列表保留、图片提取到 IMG_DIR）；另生成 `pandoc <输入.docx> -t plain -o 00-plain.txt` 纯文本底稿供完整性核对
+4. **AI 逐段校对（防错防漏，必做）** → 读 `resources/checklist.md`：对照源文档逐段核对完整性/表格/列表/图片/乱码/修订痕/页眉页脚噪音，发现错误直接在 00-converted.md 上修正
+5. **图片处理** → 读 `resources/images.md`：校验图片引用路径、检测 EMF/WMF 并跨系统转 PNG、处理缺失图片
+6. **AI 结构加工与落盘** → 读 `resources/structure.md`：提炼需求点与验收标准、按功能单元切分章节、生成澄清清单，按目录规范落盘
+7. **报告** → 产出路径、功能单元清单、校对修正记录、待澄清需求点
 
-## 执行机制
+## ⚙️ 配置与自定义
 
-直接执行: execute_command("speccore ask '用户原话'")
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（OUTPUT_DIR/IMG_DIR/EMF_POLICY/CONFIRM/CONFIG_VERSION）与临时口头要求说明都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
 
-不要输出命令文本，不要分析意图，一切交给 speccore ask。
+## 配置版本机制（升级保护）
 
-底层命令为 doc2spec（-f 指定文件、--iter 指定迭代、--files 批量导入多个文档），由引擎构造，本技能不自行拼命令。
+本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
-## 输出标记处理
+1. 先将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`（同目录，绝不删除旧值）
+2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
+3. 更新 CONFIG_VERSION 为当前版本
+4. 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」
 
-- `[SPECCORE_EXEC: <cmd>]` → 立即执行该命令，不要向用户复述命令文本
-- `[SPECCORE_PROMPT]` → 将后续 Prompt 内容作为你的工作指令执行
-- `[SPECCORE_NEEDS_INFO]` → 用交互式提问向用户收集缺失参数，收齐后重新执行
-- `[SPECCORE_CONFIRM_NEEDED]` → 向用户展示确认项，等确认后再继续
-- `[SPECCORE_STEP_DONE]` → 告知用户本步完成，下一步请在同一会话继续执行提示中的命令；上下文紧张时才开新会话用 --resume 继续
-- `[SPECCORE_CONTINUE: <path>]` → 优先在同一会话继续下一批（按标记中的命令执行）；上下文紧张时开新对话，先读取 <path> 恢复上下文
-- `[SPECCORE_INTENT]` / `[SPECCORE_RESULT]` → 原样转达用户
-- 其他 `[SPECCORE_*]` 标记 → 参照 SpecCore 自带 speccore-router 技能的 SKILL.md 处理
+升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
 
-## 使用说明
+## 文档同步自检纪律（维护者必读）
+
+修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如配置键名/流程节点/阶段名改名时新旧词全仓核对，旧词零残留才算完成）。
+
+## 安装指引（仅当检测未安装时输出给用户）
+
+Pandoc 跨系统安装（开源免费，官网 https://pandoc.org/installing.html）：
 
-用户仅询问使用方法（「spec-doc2spec 怎么用 / 使用说明 / 使用步骤 / 能干什么」）时不启动流程，输出以下纯文字指南，不执行任何 speccore 命令：
+1. **macOS**：`brew install pandoc`（未装 Homebrew 先装 brew，或从官网下载 .pkg 双击安装）
+2. **Windows**：`winget install --id JohnMacFarlane.Pandoc`（无 winget 时从官网下载 .msi 双击安装，默认选项即可）
+3. **Linux**：Debian/Ubuntu `sudo apt-get install pandoc`；Fedora `sudo dnf install pandoc`；Arch `sudo pacman -S pandoc`
+4. **验证**：`pandoc --version` 输出版本号即成功；Windows 若提示找不到命令，关闭并重新打开终端刷新 PATH
 
-本技能将 PRD / Word / PDF 需求文档导入 SpecCore 迭代目录，产出需求文档与功能单元切片。
+EMF 图片转 PNG 依赖 LibreOffice（可选，仅当文档含 EMF 图）：macOS `brew install --cask libreoffice`；Windows `winget install TheDocumentFoundation.LibreOffice`；Linux `sudo apt-get install libreoffice`。
+
+安装完成后，请用户重新说一次需求，再走「生成流程」。
+
+## 使用说明
 
-**使用步骤**：1. 确保已安装 SpecCore CLI 且项目已有迭代（speccore iteration create）；2. 直接说「导入需求 产品需求文档.docx」「把这份 PRD 转成 Spec」「分析这个 PRD 文档」等；3. 引擎自动提取文件与迭代参数，文件不存在、格式不支持或参数缺失时会交互式提问；4. 导入完成后产出 010-requirements/ 下的转换文档与切片，可继续 unitize 切分功能单元。
+用户仅询问使用方法（「spec-doc2spec 怎么用 / 使用说明 / 使用步骤 / 能干什么」）时不启动流程，读 `resources/usage-guide.md` 将其内容原样输出（首行标题改为「doc2spec 使用指南」），不执行任何转换命令。
 
-**支持格式**：.docx（Pandoc + AI 双路验证）/ .pdf / .md。
+## 规则速览
 
-**触发词**：导入需求 / 把 PRD 转成 Spec / Word 转需求文档 / 分析这个 PRD / /doc2spec。
+- 机械产物只作底稿：AI 校对（完整性/表格/图片/乱码/修订痕）与需求加工（需求点+验收标准、功能单元切分、澄清清单）缺一不可
+- 图片一律进 IMG_DIR（默认 assets/images），EMF/WMF 必须先转 PNG（soffice headless → qlmanage → magick 按系统探测）
+- 输出目录默认 {文档名}-spec/，00-converted.md 底稿保留溯源、加工稿另写不覆盖底稿
+- 有疑点进 _clarify.md，不臆造内容；落盘后向用户报告产出路径/单元清单/校对记录/待澄清点

package/spec-doc2spec/resources/checklist.md

@@ -0,0 +1,25 @@
+# AI 校对清单（机械转换后必做）
+
+Pandoc 机械产物只作底稿。AI 必须 Read 源文档与 00-converted.md / 00-plain.txt，逐段对照核对，发现问题直接在底稿上修正，修正后再进入需求加工。
+
+## 完整性核对
+
+- 章节结构：源文档每个一级/二级标题在转换结果中都有对应内容，无整章整段丢失
+- 双通道比对：00-plain.txt 是纯文本全量输出——若某段内容 plain 版有而 gfm 版无，说明该段在格式转换中丢失（常见于 Word 文本框、SmartArt、批注框内文本），必须找回补进底稿
+- 关键词抽查：源文档高频词/专有名词（功能名、接口名、字段名、编号）逐一 grep 底稿确认在位
+
+## 错误排查（Pandoc 已知局限）
+
+- **表格**：合并单元格拆裂、列错位、跨页表格断行错乱 → AI 重建为规范 markdown 表格（合并单元格用行内注释注明合并范围）；表格被降级成纯文本段落时恢复为表格
+- **列表**：多层嵌套层级丢失、有序列表编号中断 → AI 按原文恢复层级与编号
+- **图片**：引用路径失效、图片丢失、.emf/.wmf 引用 → 见 images.md
+- **特殊字符**：公式变形、箭头/全角符号乱码 → AI 修正；数学公式用 $...$ 行内 / $$...$$ 块级保留 LaTeX 原貌
+- **修订痕**：Word 修订模式未接受时，转换可能残留删除线文本 → 提示用户「接受所有修订」后重转；无法重转时 AI 按「接受后状态」处理并注明
+- **页眉页脚/页码**：转换为正文残留文本 → 剔除
+- **超链接**：链接地址丢失 → AI 从源文档补回或注明
+
+## 校对纪律
+
+- 修正直接在 00-converted.md 上进行，修正后该文件即「已校对底稿」
+- 修正与补漏逐条记录（供最终报告引用）
+- 校对后仍存疑的内容进 _clarify.md 澄清清单，不臆造

package/spec-doc2spec/resources/images.md

@@ -0,0 +1,27 @@
+# 图片处理
+
+## 提取
+
+- Pandoc 转换命令带 `--extract-media=<IMG_DIR>`（默认 assets/images，相对输出目录）：文档内嵌图片自动提取到该目录，md 引用改写为相对路径
+- 转换后 Read 00-converted.md 收集全部 `![](...)` 引用，逐一核对 IMG_DIR 下对应文件存在；引用路径以 00-converted.md 所在目录为基准解析
+
+## EMF/WMF 转换（浏览器不可渲染格式）
+
+- 检查 IMG_DIR 下是否出现 .emf/.wmf 文件（Word 图形对象默认 EMF，很常见）：有则必须转 PNG，否则预览/截图/后续加工全部不可见
+- 转换链（跨系统，按序探测，成功即止）：
+  1. LibreOffice：`soffice --headless --convert-to png --outdir <IMG_DIR> <file.emf>`（三系统通用，首选）
+  2. macOS 备选：`qlmanage -t -s 1600 -o <IMG_DIR> <file.emf>`（部分 EMF 不支持）
+  3. Windows 备选：ImageMagick `magick <file.emf> <file.png>`
+- 转换成功后把 md 引用 .emf → .png 全部替换
+- 全部工具缺失时：按 EMF_POLICY=keep 保留原文件，在 _clarify.md 注明「N 张 EMF 图无法渲染，建议在 Word 中另存为 PNG 后重新转换」
+
+## 缺失与异常
+
+- 引用存在但文件缺失：核对 --extract-media 是否执行、路径是否被移动；无法恢复的在 _clarify.md 记录「图片缺失：<原位置>」
+- alt 文本：Pandoc 保留 Word 图片 alt 文本，AI 校对时确认关键图片 alt 与原文图注一致；无 alt 的关键图片按原文图注补写
+- 图片命名：默认沿用 Pandoc 提取名（image1.png 等）；重名冲突时 AI 重命名并在 md 引用同步更新
+
+## 目录组织
+
+- 默认 IMG_DIR=assets/images（相对输出目录，可配置改绝对路径）
+- 严禁图片散落在输出目录根：一律进 IMG_DIR

package/spec-doc2spec/resources/structure.md

@@ -0,0 +1,27 @@
+# 目录组织与落盘
+
+## 默认输出结构
+
+```
+{源目录}/{文档名}-spec/          ← OUTPUT_DIR=auto 默认；可配置绝对路径
+├── README.md                    ← 索引：源文档、转换时间、功能单元清单、校对记录摘要
+├── 00-converted.md              ← Pandoc 机械底稿（AI 已校对修正版，保留溯源）
+├── 00-plain.txt                 ← 纯文本底稿（完整性核对用，保留溯源）
+├── 01-需求规格.md                ← AI 加工后的主规格：需求点 + 验收标准（功能单元 ≤3 时单文件即可）
+├── requirements/                ← 功能单元切片（单元 >3 时启用）
+│   ├── REQ-01-{单元名}.md
+│   └── ...
+├── assets/images/               ← 图片目录（IMG_DIR 可配置）
+└── _clarify.md                  ← 待澄清清单（有疑点才生成）
+```
+
+## 加工规则
+
+- 需求点提炼：每条「需求点 - 验收标准」结对，保留原文关键表述，不臆造内容
+- 功能单元切分：按业务功能边界切分，单元名用中文短名（如「用户登录」）；单元 >3 时拆 requirements/ 目录，否则合并在 01-需求规格.md 内分章节
+- 澄清清单：校对中发现的歧义/缺失/矛盾 → _clarify.md 逐条编号记录（问题 + 原文出处 + AI 建议）
+- 溯源：每个功能单元注明来源章节；00-converted.md 保留不做删改，加工后的规格另写文件、不覆盖底稿
+
+## 目录复用
+
+- 输出目录已存在时：复用并覆盖本清单内同名文件（00-converted.md/01-需求规格.md 等），其余文件保留；不清空目录

package/spec-doc2spec/resources/usage-guide.md

@@ -0,0 +1,32 @@
+# doc2spec 使用指南
+
+## 能干什么
+
+把 PRD / Word / Markdown 需求文档转成结构化 Markdown 需求规格：Pandoc 机械转换 + AI 逐段校对（纠错补漏）+ 需求点提炼与功能单元切分。图片自动提取到 assets/images/（EMF 等不可渲染格式自动转 PNG）；输出默认「源文档同目录/{文档名}-spec/」子目录，输出与图片目录均可配置。
+
+## 使用方式
+
+1. 直接说「把这份 PRD 转成需求文档」「Word 转需求切片」并给出文件路径
+2. 未装 Pandoc 时按引导安装（macOS brew / Windows winget / Linux apt-get）
+3. Pandoc 完成 Word→Markdown 机械转换后，AI 对照原文逐段校对（完整性/表格/图片/乱码/修订痕），再提炼需求点、按功能单元切分
+4. 产出结构化需求文档到指定目录
+
+## 支持格式
+
+- .docx（Pandoc 转换，图片自动提取）
+- .md（直接读取）
+- .pdf（pdftotext 文本提取，仅文本无图；需要图片建议先转 Word）
+
+## 常用说法
+
+- 「输出到桌面」→ 临时改输出目录
+- 「图片放 figures/」→ 临时改图片目录
+- 「先看看效果」→ 先出预览确认再落盘
+
+## 产出
+
+{文档名}-spec/ 目录：README 索引 + 需求规格（含功能单元切片）+ 图片目录 + 澄清清单（有疑点时）。
+
+## 触发词
+
+把 PRD 转成需求文档 / Word 转需求切片 / 文档转规格 / /doc2spec

package/spec-doc2spec/user-config.md

@@ -0,0 +1,22 @@
+# 用户配置（升级技能时本文件不会被覆盖）
+
+> 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
+> 本文件始终保留你的版本——输出目录、模板与引擎策略、确认方式放心改。
+> 官方升级若带来新配置点，会另存 `user-config.md.upstream` 对照文件到同目录，
+> 你按需查看并手动合并新配置点到本文件。
+
+
+## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+
+```yaml
+CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+OUTPUT_DIR: auto              # 输出目录：auto = 源文档同目录下新建 {文档名}-spec/ 子目录；也可写死绝对路径
+IMG_DIR: assets/images        # 图片提取目录（相对输出目录）；Pandoc --extract-media 提取到此处
+EMF_POLICY: convert           # EMF/WMF 图片策略：convert = 自动跨系统转 PNG（LibreOffice 兜底）；keep = 保留原样并在澄清清单注明不可渲染
+CONFIRM: never                # 落盘前确认：never = 直接生成落盘；always = 先出加工预览确认后再落盘
+```
+
+> 临时口头要求（仅对当次生效，不修改上方配置）：说「输出到 XX 目录」→ 当次改 OUTPUT_DIR；说「图片放 XX」→ 当次改 IMG_DIR；说「先看看效果」→ 当次先出预览确认再落盘。
+
+---
+> 更多用法见 SKILL.md 的「生成流程」与 resources/ 分册。

package/spec-spec2doc/SKILL.md

@@ -1,52 +1,71 @@
 ---
 name: spec-spec2doc
 description: >
-  SpecCore 文档导出专属 Skill（spec2doc）。仅在用户明确提到 speccore、迭代、期次、Spec、/spec2doc 等关键词，
-  或明确要求通过 speccore 导出文档时使用：将迭代 / Task 的规格文档导出为 Word / PDF 交付文档（AI 排版 + 验证）。
-  参数提取与前置校验（迭代/Task 存在性）由 speccore ask 引擎执行；参数缺失时引擎输出 [SPECCORE_NEEDS_INFO] 交互式提示。
-  不影响 speccore ask 的意图识别能力。
-  不处理一般性的文档转换（如「把这个 md 转成 Word」非 speccore 语境），只处理 speccore 上下文中的规格导出。
+  规格转交付文档 Skill（spec2doc）。仅在用户要求把 Markdown 规格 / 技术文档导出为 Word / PDF 交付文档时使用。
+  Pandoc 负责机械转换，AI 负责转换前排版整理与转换后回验防错（Pandoc 对复杂表格、图片路径、中文字体有局限，
+  回验发现问题修正源稿重新转换直到通过，机械产物不直接交付）。主路径 Markdown → Word（支持 --reference-doc
+  模板：默认依次探测源目录 template.docx / reference.docx，可配置 TEMPLATE_DOCX）。
+  Markdown → PDF 双路径：xelatex（需 LaTeX 引擎与 CJK 中文字体）或 Chrome headless 打印（免 LaTeX、跨系统兜底），
+  引擎可配置 PDF_ENGINE。输出目录默认与源文档同目录，可配置 OUTPUT_DIR。
+  跨系统适配 macOS / Windows / Linux（Pandoc/LaTeX 安装、中文字体探测、Chrome 路径探测）。
+  不处理一般性的文档格式转换（如「把这个 txt 转成 Word」），只处理「规格 → 交付文档」的转换任务。
 allowed-tools: ["Bash", "Read", "Write", "Edit"]
 disable-model-invocation: false
 ---
 
 # 规格 → 交付文档（spec2doc）
 
-将 SpecCore 迭代 / Task 的规格文档（`020-specs/`、`030-tasks/`）导出为 Word / PDF 交付文档，由引擎编排 AI 排版与验证，产出可直接交付的文档文件。
+将 Markdown 规格 / 技术文档转换为 Word / PDF 交付文档。分工原则：**Pandoc 负责机械转换，AI 负责排版整理与回验防错**——AI 转换前整理标题层级/表格/图片路径，转换后核对产出文档内容完整与格式正确，发现问题修正源稿重新转换，直到回验通过（机械产物不直接交付）。
 
-## 前置依赖
+## 生成流程
 
-- SpecCore CLI 已安装（`speccore` 命令可用）
-- 已有迭代且规格文档已产出（analyze / taskify 之后）
-- speccore ask 引擎随 SpecCore 提供：负责参数提取、前置校验（迭代/Task 存在性）与命令构造，本技能不自行解析参数
+0. **读用户配置**（OUTPUT_DIR/TEMPLATE_DOCX/TOC/PDF_ENGINE/CONFIG_VERSION）→ 先 Read 同目录 `user-config.md`
+1. **依赖检测**（每次必做）→ `pandoc --version`；未安装按「安装指引」输出并停止。目标为 PDF 时另探测引擎：`xelatex --version`（LaTeX 路径）→ Chrome 路径（打印路径），细节读 `resources/pdf-path.md`
+2. **AI 排版整理** → 统一标题层级、规整表格（超宽表拆表或改列表）、检查图片引用路径、确定元信息（标题/作者）
+3. **Pandoc 输出** → Word：`pandoc <输入.md> -f gfm -t docx -o <输出.docx> [--reference-doc=<模板>] [--toc --toc-depth=3]`（模板探测与图片路径读 `resources/images-and-template.md`）；PDF：双路径命令读 `resources/pdf-path.md`
+4. **AI 回验（防错防漏，必做）** → 读 `resources/checklist.md`：反向转换比对内容完整性、图片嵌入核对、标题层级、中文显示、乱码排查
+5. **修正重转** → 发现问题修正源稿重新转换，再次回验；重转不超过 3 轮，仍不通过如实报告「哪些项无法修复 + 原因」，不交付带错文档
+6. **报告** → 输出路径与格式、回验结论、PDF 引擎与兜底说明
 
-## 执行机制
+## ⚙️ 配置与自定义
 
-直接执行: execute_command("speccore ask '用户原话'")
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（OUTPUT_DIR/TEMPLATE_DOCX/TOC/PDF_ENGINE/CONFIG_VERSION）与临时口头要求说明都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
 
-不要输出命令文本，不要分析意图，一切交给 speccore ask。
+## 配置版本机制（升级保护）
 
-底层命令为 spec2doc（-i 指定迭代、-o 指定输出文件名与格式 .docx/.pdf、--all 导出全部规格），由引擎构造，本技能不自行拼命令。
+本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
-## 输出标记处理
+1. 先将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`（同目录，绝不删除旧值）
+2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
+3. 更新 CONFIG_VERSION 为当前版本
+4. 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」
 
-- `[SPECCORE_EXEC: <cmd>]` → 立即执行该命令，不要向用户复述命令文本
-- `[SPECCORE_PROMPT]` → 将后续 Prompt 内容作为你的工作指令执行
-- `[SPECCORE_NEEDS_INFO]` → 用交互式提问向用户收集缺失参数，收齐后重新执行
-- `[SPECCORE_CONFIRM_NEEDED]` → 向用户展示确认项，等确认后再继续
-- `[SPECCORE_STEP_DONE]` → 告知用户本步完成，下一步请在同一会话继续执行提示中的命令；上下文紧张时才开新会话用 --resume 继续
-- `[SPECCORE_CONTINUE: <path>]` → 优先在同一会话继续下一批（按标记中的命令执行）；上下文紧张时开新对话，先读取 <path> 恢复上下文
-- `[SPECCORE_INTENT]` / `[SPECCORE_RESULT]` → 原样转达用户
-- 其他 `[SPECCORE_*]` 标记 → 参照 SpecCore 自带 speccore-router 技能的 SKILL.md 处理
+升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
 
-## 使用说明
+## 文档同步自检纪律（维护者必读）
+
+修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如配置键名/流程节点/阶段名改名时新旧词全仓核对，旧词零残留才算完成）。
+
+## 安装指引（仅当检测未安装时输出给用户）
+
+Pandoc 跨系统安装（开源免费，官网 https://pandoc.org/installing.html）：
 
-用户仅询问使用方法（「spec-spec2doc 怎么用 / 使用说明 / 使用步骤 / 能干什么」）时不启动流程，输出以下纯文字指南，不执行任何 speccore 命令：
+1. **macOS**：`brew install pandoc`（未装 Homebrew 先装 brew，或从官网下载 .pkg 双击安装）
+2. **Windows**：`winget install --id JohnMacFarlane.Pandoc`（无 winget 时从官网下载 .msi 双击安装，默认选项即可）
+3. **Linux**：Debian/Ubuntu `sudo apt-get install pandoc`；Fedora `sudo dnf install pandoc`；Arch `sudo pacman -S pandoc`
+4. **验证**：`pandoc --version` 输出版本号即成功；Windows 若提示找不到命令，关闭并重新打开终端刷新 PATH
 
-本技能将 SpecCore 迭代 / Task 的规格文档导出为 Word / PDF 交付文档（AI 排版 + 验证）。
+PDF 的 LaTeX 引擎（仅当要求 LaTeX 出 PDF 时）：macOS `brew install --cask basictex`（装完 `sudo tlmgr install ctex`）；Windows `winget install MiKTeX.MiKTeX`；Linux Debian/Ubuntu `sudo apt-get install texlive-xetex texlive-lang-chinese`。免装 LaTeX 可走 Chrome 打印路径（见 resources/pdf-path.md）。
+
+安装完成后，请用户重新说一次需求，再走「生成流程」。
+
+## 使用说明
 
-**使用步骤**：1. 确保已有迭代且规格文档已产出（analyze / taskify 之后）；2. 直接说「导出文档」「生成 Word/PDF」「导出 Q1 迭代的文档」「打包技术文档」等；3. 引擎自动提取迭代与输出格式参数，迭代不存在时会交互式提问；4. 导出完成后产出 .docx / .pdf 交付文档，可用 --all 导出全部规格。
+用户仅询问使用方法（「spec-spec2doc 怎么用 / 使用说明 / 使用步骤 / 能干什么」）时不启动流程，读 `resources/usage-guide.md` 将其内容原样输出（首行标题改为「spec2doc 使用指南」），不执行任何转换命令。
 
-**支持格式**：Word（.docx）/ PDF（.pdf）。
+## 规则速览
 
-**触发词**：导出文档 / 生成 Word/PDF / 打包技术文档 / 导出全部 Spec / /spec2doc。
+- 机械产物不直接交付：AI 排版整理（转换前）与回验防错（转换后）缺一不可，发现问题修正源稿重转直到通过
+- Word 是主路径（Pandoc 原生）；PDF 双路径 xelatex / Chrome 打印，引擎缺失先出 Word 并提示 Word 另存 PDF
+- 图片相对路径以工作目录为基准：转换前 cd 到源 md 目录或 --resource-path 声明；EMF 源图先转 PNG
+- 模板探测链 template.docx → reference.docx → Pandoc 默认样式；目录生成 TOC 默认开启