skill-forge-hub 0.2.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.2.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"
@@ -11,8 +11,10 @@
     "weekly-report",
     "annual-report",
     "article-to-html",
+    "magic-deck",
     "spec-doc2spec",
     "spec-spec2doc",
+    "meta-forge",
     "template"
   ],
   "keywords": [

package/spec-doc2spec/SKILL.md

@@ -20,6 +20,7 @@ disable-model-invocation: false
 
 ## 生成流程
 
+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` 纯文本底稿供完整性核对
@@ -28,16 +29,24 @@ disable-model-invocation: false
 6. **AI 结构加工与落盘** → 读 `resources/structure.md`：提炼需求点与验收标准、按功能单元切分章节、生成澄清清单，按目录规范落盘
 7. **报告** → 产出路径、功能单元清单、校对修正记录、待澄清需求点
 
-## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+## ⚙️ 配置与自定义
 
-```yaml
-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 = 先出加工预览确认后再落盘
-```
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（OUTPUT_DIR/IMG_DIR/EMF_POLICY/CONFIRM/CONFIG_VERSION）与临时口头要求说明都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
 
-> 临时口头要求（仅当次生效）：说「输出到 XX 目录」→ 当次改 OUTPUT_DIR；说「图片放 XX」→ 当次改 IMG_DIR；说「先看看效果」→ 当次先出预览确认再落盘。
+## 配置版本机制（升级保护）
+
+本 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 全文核对相关关键词在各文件间一致（如配置键名/流程节点/阶段名改名时新旧词全仓核对，旧词零残留才算完成）。
 
 ## 安装指引（仅当检测未安装时输出给用户）
 

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

@@ -19,6 +19,7 @@ disable-model-invocation: false
 
 ## 生成流程
 
+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`
@@ -26,16 +27,24 @@ disable-model-invocation: false
 5. **修正重转** → 发现问题修正源稿重新转换，再次回验；重转不超过 3 轮，仍不通过如实报告「哪些项无法修复 + 原因」，不交付带错文档
 6. **报告** → 输出路径与格式、回验结论、PDF 引擎与兜底说明
 
-## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+## ⚙️ 配置与自定义
 
-```yaml
-OUTPUT_DIR: auto              # 输出目录：auto = 与源 md 同目录；可写死绝对路径
-TEMPLATE_DOCX: auto           # Word 模板：auto = 依次探测 <源目录>/template.docx → reference.docx → 无则 Pandoc 默认样式；可指定模板路径
-TOC: true                     # Word/PDF 是否生成目录（--toc --toc-depth=3）
-PDF_ENGINE: auto              # PDF 引擎：auto = 探测 xelatex（有则 LaTeX 路径）→ 无则 Chrome 打印路径
-```
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（OUTPUT_DIR/TEMPLATE_DOCX/TOC/PDF_ENGINE/CONFIG_VERSION）与临时口头要求说明都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
 
-> 临时口头要求（仅当次生效）：说「输出到 XX」→ 当次改 OUTPUT_DIR；说「用这个模板」+ 路径 → 当次换模板；说「不要目录」→ 当次 TOC=false；说「必须用 LaTeX 出 PDF」→ 当次 PDF_ENGINE=xelatex（无引擎则引导安装）。
+## 配置版本机制（升级保护）
+
+本 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 全文核对相关关键词在各文件间一致（如配置键名/流程节点/阶段名改名时新旧词全仓核对，旧词零残留才算完成）。
 
 ## 安装指引（仅当检测未安装时输出给用户）
 

package/spec-spec2doc/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 = 与源 md 同目录；可写死绝对路径
+TEMPLATE_DOCX: auto           # Word 模板：auto = 依次探测 <源目录>/template.docx → reference.docx → 无则 Pandoc 默认样式；可指定模板路径
+TOC: true                     # Word/PDF 是否生成目录（--toc --toc-depth=3）
+PDF_ENGINE: auto              # PDF 引擎：auto = 探测 xelatex（有则 LaTeX 路径）→ 无则 Chrome 打印路径
+```
+
+> 临时口头要求（仅对当次生效，不修改上方配置）：说「输出到 XX」→ 当次改 OUTPUT_DIR；说「用这个模板」+ 路径 → 当次换模板；说「不要目录」→ 当次 TOC=false；说「必须用 LaTeX 出 PDF」→ 当次 PDF_ENGINE=xelatex（无引擎则引导安装）。
+
+---
+> 更多用法见 SKILL.md 的「生成流程」与 resources/ 分册。

package/weekly-report/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: weekly-report
-description: 生成工作周报（默认本周完成任务/下周计划/风险阻塞点三段结构，中文顿号序号，1D=8H），适配各行业（内置 12 行业职业词典，可指定角色身份）。数据来源灵活：各仓库 git 提交聚合、纯文字、图片或文件整理，无 git 也适用。支持自定义模板（可永久或临时指定）、周结束日可配置（默认周五，可改周日等）。支持自然语言定位周（本周/上周/10月第2周/10月20号所在周等）。当用户请求写周报、本周周报、上周周报、生成周报、/weekly-report，或询问周报用法（周报怎么用/周报使用说明/周报有哪些使用方式）时使用。
+description: 生成工作周报（默认本周任务进度/下周计划/风险阻塞点三段结构，中文顿号序号，1D=8H），适配各行业（内置 12 行业职业词典，可指定角色身份）。数据来源灵活：各仓库 git 提交聚合、纯文字、图片或文件整理，无 git 也适用。支持自定义模板（可永久或临时指定）、周结束日可配置（默认周五，可改周日等）。支持自然语言定位周（本周/上周/10月第2周/10月20号所在周等）。当用户请求写周报、本周周报、上周周报、生成周报、/weekly-report，或询问周报用法（周报怎么用/周报使用说明/周报有哪些使用方式）时使用。
 allowed-tools: Bash, Read, Write
 disable-model-invocation: false
 ---
 
 # 周报生成
 
-聚合各仓库 git 提交 + 本次会话口述内容生成三段式周报（本周完成任务/下周计划/风险阻塞点 + 本周概览卡），对话输出 md 正文 + 落盘 md/txt/html/content-png 并自动打开 html。
+聚合各仓库 git 提交 + 本次会话口述内容生成三段式周报（本周任务进度/下周计划/风险阻塞点 + 本周概览卡），对话输出 md 正文 + 落盘 md/txt/html/content-png 并自动打开 html。
 
 ## 生成流程
 
-0. **读用户配置**（DISK/FORMATS/DIR/OPEN_HTML/TEMPLATE/ROLE/CONFIRM、自定义模板）→ 先 Read 同目录 `user-config.md`
+0. **读用户配置**（DISK/FORMATS/DIR/OPEN_HTML/TEMPLATE/ROLE/CONFIRM/CONFIG_VERSION、自定义模板）→ 先 Read 同目录 `user-config.md`
 1. **解析周**（自然语言 → 目标周：周一起点、WEEK_END 结束日）→ 读 `resources/date-parsing.md`
 2. **收集数据**（本周 git + 会话口述 + 口头补充，合并去重；同取上周数据供概览环比）→ 读 `resources/data-collection.md`
 3. **内容归类与润色**（聚合来源 / 补充任务 / 纯文字模式 / 输出格式 / 写作风格）→ 读 `resources/content-rules.md`
@@ -21,11 +21,26 @@ disable-model-invocation: false
 
 ## ⚙️ 配置与自定义模板
 
-**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（DISK/FORMATS/DIR/OPEN_HTML/TEMPLATE/ROLE/CONFIRM）与自定义模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留。
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（DISK/FORMATS/DIR/OPEN_HTML/TEMPLATE/ROLE/CONFIRM/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 全文核对相关关键词在各文件间一致（如章节名/字段名/效果参数改名时新旧词全仓核对，旧词零残留才算完成）。修改 HTML 效果必须同步更新 `resources/reference.html` 与 `disk-and-html.md` 对应描述，三者以 reference.html 为真相源；改完后互相 grep 关键参数确认对齐。
 
 ## 规则速览
 
-- 完成任务 5-15 点、每点 30-60 字；序号用中文顿号（1、2、3）
+- 任务进度 5-15 点、每点 30-60 字；序号用中文顿号（1、2、3）
 - 三段兜底写「暂无」；计划点带进度百分比与预估用时；风险阻塞点三环（问题+影响+建议）
 - 用时单位 X.XD（天，1D=8H），估算值注明「约」；落盘子目录名 = 当周最后一天（WEEK_END）日期
 - 完整规则（聚合来源 / 纯文字模式 / 写作风格约束 / 使用提示）见 `resources/content-rules.md`

package/weekly-report/resources/content-rules.md

@@ -1,24 +1,24 @@
 # 内容规则
 
 ## 输出内容与数据来源
-- 三段结构：本周完成任务（5-15 点）/ 下周计划 / 风险阻塞点
+- 三段结构：本周任务进度（5-15 点）/ 下周计划 / 风险阻塞点
 - 任务点格式：1、任务描述（量化数据：文件数/行数/提交次数）- 进度XX% - 用时X.XD（1D=8H）
 - 任务来源（默认）：各仓库本周 git 提交自动聚合（同主题多日提交合并为一条）+ 本次会话中用户已提及/口述的工作内容 + 用户口头补充，全部合并去重；仅当用户明确说"只整理这段文字/只按这段"时才忽略 git 与会话上下文、只用指定文字（见「纯文字整理模式」）
-- 「下周计划」取材双通道：①用户口述/文字补充的计划（优先并入）；②一次生成多周周报、或后续日期日报已生成时（本次批量生成中下一周的周报，或 reports 目录中已存在的后续日报/下周周报），从下一周周报的「本周完成任务」（无下周周报时从下周各日报的完成任务）中抽取任务作为「下周计划」（抽取数量灵活、不设死上限：下周完成任务多且连续性强时可多抽至 5-6 条，少则抽 2-3 条，与下一周内容形成呼应即可），描述改写为计划语气（完成态改进行态：如「完成 XX 重构」→「推进 XX 重构」「继续 XX 开发」，去掉量化数据/进度/用时）；批量多周时优先保证跨周连续性：抽取时尽量让本周「下周计划」与下一周「本周完成任务」形成「计划→完成」的同主题承接链（如本周计划「启动 XX 重构」→ 下周完成「完成 XX 重构」，长期任务串成连续的工作链）；无后续数据时，该段按口述或「暂无」处理
+- 「下周计划」取材双通道：①用户口述/文字补充的计划（优先并入）；②一次生成多周周报、或后续日期日报已生成时（本次批量生成中下一周的周报，或 reports 目录中已存在的后续日报/下周周报），从下一周周报的「本周任务进度」（无下周周报时从下周各日报的任务进度）中抽取任务作为「下周计划」（抽取数量灵活、不设死上限：下周完成任务多且连续性强时可多抽至 5-6 条，少则抽 2-3 条，与下一周内容形成呼应即可），描述改写为计划语气（完成态改进行态：如「完成 XX 重构」→「推进 XX 重构」「继续 XX 开发」，去掉量化数据/进度/用时）；批量多周时优先保证跨周连续性：抽取时尽量让本周「下周计划」与下一周「本周任务进度」形成「计划→完成」的同主题承接链（如本周计划「启动 XX 重构」→ 下周完成「完成 XX 重构」，长期任务串成连续的工作链）；无后续数据时，该段按口述或「暂无」处理
 - 量化数据取自 git --stat（文件数、增删行数）；用时为合理估算（git 不记录耗时，估算值注明"约"，可口头修正）
 - 数据收集范围（按当前系统自动选择，另一系统的仓库自动跳过）：macOS = NearCast / nearcast-server / nearcast-go / nearcast-admin / SmartCanteenConsumerMachineApp / TrustPay 共 6 个仓库；Windows = srf-app / srf-manage / srf-operation / srf-service / srf-web-user / srf-web-operation / srf-web-wx / srf-web-h5-teacher / srf-web-uop / Spec-Core-Smart-Canteen 共 10 个仓库；本周无提交的仓库不写入
-- HTML 版为参考图式深蓝面板卡片美化样式（实心深蓝卡片 + 细密水平条纹 + 上下边缘高光线 + 左缘节色条，保留 ask 同款发光动效）：附「本周概览」Bento 卡片（完成率圆环大卡 + 提交热力图 5天×3时段 + 提交数/活跃天数/涉及文件/代码行数四指标 + 提交节奏柱图带 hover 明细 + 环比行）、顶部「一键复制」按钮（复制纯文本版）+ TL;DR 摘要行、「本周完成任务」标题右侧带周范围徽章（跟随 WEEK_END）+ 进度条终点圆点与流星扫描填充 + 液态玻璃卡片（@supports 兜底）+ CRT 扫描光带 + 全页 3D 微倾斜（±0.75°）、页脚署名 GENERATED BY SPECCORE TEAM（周范围动态跟随 WEEK_END），并随 FORMATS 默认落一张内容区截图 content-png（概览与卡片整体 + 四周留白 + 周范围徽章）
+- HTML 版为参考图式深蓝面板卡片美化样式（实心深蓝卡片 + 细密水平条纹 + 上下边缘高光线 + 左缘节色条，保留 ask 同款发光动效）：附「本周概览」Bento 卡片（完成率圆环大卡 + 提交热力图 5天×3时段 + 提交数/活跃天数/涉及文件/代码行数四指标 + 提交节奏柱图带 hover 明细 + 环比行）、顶部「一键复制」按钮（复制纯文本版）+ TL;DR 摘要行、「本周任务进度」标题右侧带周范围徽章（跟随 WEEK_END）+ 进度条终点圆点与流星扫描填充 + 液态玻璃卡片（@supports 兜底）+ CRT 扫描光带 + 全页 3D 微倾斜（±0.75°）、页脚署名 GENERATED BY SPECCORE TEAM（周范围动态跟随 WEEK_END），并随 FORMATS 默认落一张内容区截图 content-png（概览与卡片整体 + 四周留白 + 周范围徽章）
 
 ## 用户补充任务
 
 用户调用时可能口头追加任务（如"还有一件事：这周处理了两天的支付问题"），按以下规则处理：
 
 - **触发**：话术含"补充/加上/还有/另外/以及/对了"等追加词，或直接口述任务内容（说"整理成周报/只整理这段文字/只按这段/不用 git"时走「纯文字整理模式」，不是追加）
-- **分段**：补充内容带分段词时按段并入——"下周计划/计划：xxx"→ 下周计划段；"风险/阻塞：xxx"→ 风险阻塞点段（说"风险暂无/无风险"→ 风险段写「暂无」）；不带分段词默认并入"本周完成任务"
+- **分段**：补充内容带分段词时按段并入——"下周计划/计划：xxx"→ 下周计划段；"风险/阻塞：xxx"→ 风险阻塞点段（说"风险暂无/无风险"→ 风险段写「暂无」）；不带分段词默认并入"本周任务进度"
 - **拆条**：按语义主题拆分，一个主题一条；拆分信号：时间词（周几/上几天）、追加连接词、分号顿号列举、数字列举（1、2、3）
 - **润色**：口语整理为规范任务描述（动词开头、说清对象与结果）；周报粒度较粗，多条零散小任务合并为一个周交付物条目（30-60 字）；用户未给量化数据时，优先从 git 提交补文件数/行数，无记录则省略量化、只写进度与用时（估算值注明"约"）
 - **去重**：与 git 聚合任务合并时，同一件事只保留一条
-- **格式**：与 git 聚合条目同格式，接在"本周完成任务"下继续编号
+- **格式**：与 git 聚合条目同格式，接在"本周任务进度"下继续编号
 
 ## 纯文字整理模式（用户贴一段文字，无 git 提交）
 
@@ -29,14 +29,14 @@
 - **三段归类**（用户文字没按段写明时用信号词归类）：
   - 含"下周/接下来/计划/准备/打算/将要/待办" → 下周计划
   - 含"风险/阻塞/问题/卡住/困难/待定/依赖/遗留" → 风险阻塞点
-  - 其余 → 本周完成任务；全段无任何信号词 → 全部归入本周完成任务
+  - 其余 → 本周任务进度；全段无任何信号词 → 全部归入本周任务进度
   - 用户已明确分段（"本周完成：A；下周计划：B；风险：C"）→ 按用户分段，不猜
 - **拆条**：按语义主题拆分，一个主题一条；拆分信号：时间词（周几/前几天）、连接词（还有/另外/以及）、分号顿号列举、数字列举（1、2、3）、换行/段落边界
 - **润色**：口语整理为规范任务描述（动词开头、说清对象与结果）；周报粒度较粗，多条零散小任务合并为一个周交付物条目（30-60 字）
 - **量化数据**：无 git 提交 → 不写文件数/行数/提交次数；格式退化为「1、任务描述 - 进度XX% - 用时X.XD」
 - **进度与用时**：文字没给进度时，完成任务默认 100%、计划默认 0%；用时/预估用时仅在用户文字给出时才写，没给就省略（不瞎编估算值）
 - **风险阻塞点**：只列描述
-- **周定位/落盘/HTML**：与常规流程一致（默认本周、md/txt/html 三文件 + 内容区截图落盘、html 自动打开）；html 概览卡片无 git 数据时只显示完成任务/计划/风险条数统计
+- **周定位/落盘/HTML**：与常规流程一致（默认本周、md/txt/html 三文件 + 内容区截图落盘、html 自动打开）；html 概览卡片无 git 数据时只显示任务进度/计划/风险条数统计
 
 ## 输出格式
 
@@ -45,7 +45,7 @@
 
 > 生成时间：YYYY-MM-DD HH:MM:SS
 
-## 本周完成任务
+## 本周任务进度
 1、任务描述（量化数据：文件数/行数/提交次数）- 进度XX% - 用时X.XD
 
 ## 下周计划
@@ -57,9 +57,9 @@
 
 ## 规则
 
-- 完成任务 5-15 点，每点 30-60 字；序号用中文顿号（1、2、）
+- 任务进度 5-15 点，每点 30-60 字；序号用中文顿号（1、2、）
 - 聚合后任务数超上限（15 点）时，同类小任务合并压缩到上限内；用户说「精简点/太长了」→ 条目数取下限、每点压缩到 30 字左右；说「详细点」→ 条目数取上限、每点写足 60 字
-- 三段兜底：完成任务默认进度 100%；本周完成任务/下周计划/风险阻塞点无任何内容时该段写「暂无」（默认聚合时下周计划无 git 来源，用户没给计划就写「暂无」）
+- 三段兜底：任务进度默认 100%；本周任务进度/下周计划/风险阻塞点无任何内容时该段写「暂无」（默认聚合时下周计划无 git 来源，用户没给计划就写「暂无」）
 - 计划每点带进度百分比与预估用时
 - 风险阻塞点三环结构：问题+影响+建议，不写进度用时
 - 用时单位：X.XD（天，1D=8H），估算值注明"约"