skill-forge-hub 1.0.6 → 1.1.0

package/deck-stage/resources/skillforge-guide.txt

@@ -0,0 +1,131 @@
+# SkillForge 使用指引（技能锻造坊）
+
+SkillForge 是一套个人技能仓库 + 命令行分发器（npm 包 skill-forge-hub，命令 skill-forge）：把 21 个技能打包分发，一条命令装进你的 AI 助手技能目录；升级时配置版本感知，你的本地个性化配置永不丢失。
+
+## 一、SkillForge 是什么
+
+三个关键词：
+1、技能仓库：21 个技能按「最终产出什么」分七类（报表汇演 / 文档装裱 / 工程提效 / 演示汇演 / 数据整备 / 沟通协作 / 技能自造），每个技能都是 SKILL.md 薄入口 + resources/ 分册 + user-config.md 用户配置的规范结构
+2、命令行分发器：npm 包 skill-forge-hub，命令 skill-forge（ls / init / update），自动探测 AI 助手技能目录，交互或非交互安装
+3、配置保护：每个技能的用户配置出站在 user-config.md，升级永不覆盖；配置结构变化时备份 + 三选一，官方新配置另存对照文件供手动合并
+
+技能全景（21 个）：
+
+| 分类 | 技能 | 一句话触发语 |
+|:---|:---|:---|
+| 报表汇演 | daily-report | 「写日报」 |
+| 报表汇演 | weekly-report | 「写周报」 |
+| 报表汇演 | monthly-report | 「写月报」 |
+| 报表汇演 | quarterly-report | 「写季报」 |
+| 报表汇演 | annual-report | 「写年报」 |
+| 报表汇演 | team-report-collector | 「收日报」 |
+| 文档装裱 | article-to-html | 丢给它一个文档 |
+| 文档装裱 | twin-docs | 「翻译成英文文档」 |
+| 文档装裱 | one-pager | 「做张海报」 |
+| 工程提效 | spec-doc2spec | 「把这个文档转成需求规格」 |
+| 工程提效 | spec-spec2doc | 「把这个规格导出 Word/PDF」 |
+| 工程提效 | release-notes | 「写发版说明」 |
+| 演示汇演 | magic-deck | 「做个 PPT」（HTML 幻灯形态） |
+| 演示汇演 | deck-stage | 「做个 PPT」（.pptx 可编辑形态） |
+| 数据整备 | data-prepper | 「整理这份数据」 |
+| 数据整备 | commit-heatmap | 「生成提交热力图」 |
+| 沟通协作 | meeting-minutes | 「记会议」 |
+| 沟通协作 | prompt-pouch | 「做一个锦囊管理页面」 |
+| 沟通协作 | decision-log | 「记决策」 |
+| 技能自造 | meta-forge | 「帮我创建一个新技能」 |
+| 技能自造 | skill-doctor | 「给技能体检」 |
+
+## 二、命令速查
+
+| 命令 | 说明 |
+|:---|:---|
+| skill-forge ls | 列出全部技能（分类 + 名称 + 说明），只读不写文件 |
+| skill-forge init | 交互挑选安装：a 全装 / 编号挑选（已装标 ★）/ 确认时 s 跳过已装 |
+| npm update -g skill-forge-hub | 官方发新版后升级 CLI 本体（只升级本包） |
+| skill-forge update | 升级全部已安装技能（配置版本感知） |
+| skill-forge update --skills a,b | 只升级指定技能（未安装的提示跳过） |
+| skill-forge --version | 显示版本号 |
+| skill-forge --help | 显示完整帮助 |
+
+命令别名：list = ls、install = init、upgrade = update。
+
+通用参数（init / update 通用）：
+--target <目录>（-t）：指定技能目录；缺省自动探测常见助手目录（~/.qoder-cn、~/.claude、~/.cursor 等），探测到多个时交互选择
+--skills a,b（-s）：init 时跳过选择直接装指定技能（脚本与单件补装友好）；update 时只升级指定技能
+--yes（-y）：跳过确认直接执行；配置版本变化时默认「保留我的 + 官方版另存 .upstream 对照」
+
+## 三、场景化使用流程
+
+场景一 首次接入（从零到可用）：
+1、npm i -g skill-forge-hub
+2、skill-forge ls（先浏览清单，只读）
+3、skill-forge init（交互挑选）→ 输入 a 全装或编号挑选 → 确认时 s 跳过已装 → 自动探测技能目录 → 完成
+装完直接对话触发：「写日报」「写周报」「写月报」「写季报」「写年报」「记会议」，或直接丢给它一个文档。
+
+场景二 单件补装（脚本 / 只想要某一个）：
+skill-forge init --skills prompt-pouch --target ~/.qoder-cn/skills
+跳过挑选环节，只装指定技能到指定目录。
+
+场景三 官方发新版后升级：
+先 npm update -g skill-forge-hub（升级 CLI 本体），再 skill-forge update（全部）/ skill-forge update --skills daily-report（单个）
+· 配置结构没变：无感升级，user-config.md 原样保留
+· 配置结构变了（CONFIG_VERSION 升了）：先备份 user-config.md.bak-<时间戳>，再三选一——[1] 官方覆盖 / [2] 保留我的（默认，最稳，官方版另存 .upstream 对照文件手动合并）/ [3] 稍后处理
+· 官方删了文件：按 .installed-manifest 安装清单精准清理，你自建的文件一律不动
+
+场景四 非交互 / 自动化：
+skill-forge init --skills daily-report,weekly-report --yes
+--yes 跳过一切确认，配置冲突默认走 [2] 保留我的。
+
+场景五 换机器 / 换 AI 助手：
+新环境重新 npm i -g skill-forge-hub && skill-forge init；保留个人配置就把旧机器技能目录里的 user-config.md 一并拷过去（升级永不覆盖，覆盖安装时也保留）。
+
+## 四、典型技能使用链路
+
+统一节奏：安装 → 首次生成 → 修改配置 → 官方升级后 → 旧产物回炉。
+
+1、日报（报表族代表）：
+- 安装：skill-forge init --skills daily-report
+- 日常生成：说「写日报」口述内容 → md/txt/html（自动打开）+ 截图
+- 修改配置：user-config.md 改 DIR（落盘目录）/ THEME（五主题）/ TEMPLATE（自定义模板）；临时口头要求当次生效不写配置
+- 官方升级后：配置冲突选 [2] 保留我的，对照 .upstream 合并新配置点
+- 旧产物回炉：模板版本戳升了说「把我旧日报都升级成新样式」——浅升级换样式块、深升级从同目录 md 底稿重建，旧版先备份
+
+2、锦囊 prompt-pouch：
+- 安装：skill-forge init --skills prompt-pouch
+- 首次生成：「做一个锦囊管理页面」→ 生成管理台 html + data/prompts.json 数据文件
+- 日常使用：分组侧栏 / 搜索 / 收藏 / 标签点击过滤 / {变量} 插值一键复制 / 导入导出 JSON 备份；页面与数据分离，删页面不丢数据
+- 修改配置：user-config.md 改 DIR（页面目录）、DATA_DIR / BACKUP_DIR（数据与备份目录）
+- 官方升级后：数据目录与数据文件一概不动；深升级重建沿用原页 pouch-id → 收藏 / 分组照旧读回
+- 页面版本升级（回炉）：模板版本戳升了，下次生成时 AI 主动提示「检测到 X 份旧版锦囊」→ 说「把我旧锦囊都升级成新样式」→ 列清单选全部或部分 → 浅升级换样式块、深升级从模板重建沿用原页 pouch-id（收藏分组照旧读回）；prompts.json 数据不动、旧页先备份 .bak-时间戳
+- 多文件隔离：两份锦囊各自独立（内嵌 ID 命名空间）；复制文件副本 = 同一身份共享同一份数据（要独立身份请重新生成一份）
+
+3、PPT 两形态 magic-deck / deck-stage：
+- 选形态：说「做个 PPT」AI 先问——HTML 幻灯（magic-deck）还是 .pptx 可编辑文稿（deck-stage）
+- HTML 幻灯：magic-deck 生成单文件 HTML 幻灯，浏览器全屏放映（自动播放 / 循环 / 热键翻页）；需要图片时逐页 PNG 截图
+- .pptx 文稿：deck-stage 三问交互（素材 → 页骨架表 → 成片方式）生成 .pptx——常规页原生可编辑（数据卡 / 时间线 / 图表），封面与结尾页 HTML 截图保真
+- 补依赖：deck-stage 依赖 PptxGenJS，npm 包不含 node_modules，装完按提示 cd <技能目录>/deck-stage && npm install 补装一次
+- 修改配置：五主题 / 页面尺寸 / 演讲备注在 user-config.md
+
+4、会议纪要 meeting-minutes：
+- 日常生成：「记会议」口述材料 → 五段式纪要（会议信息 / 会议结论 / 议题讨论 / 决议与行动项 / 下次会议），行动项带负责人与截止时间——日报 / 周报 / 月报 / 季报的汇报链源头
+- 修改配置：SERIES_GROUP 三态——auto 自动提取系列名归入 meetings/{系列名}/、series 一律按系列建目录、off 纯月份平铺；改口机制「以后这个系列叫 XX」永久生效
+- 官方升级后：同报表族——配置三选一保护 + 说「把旧纪要升级成新样式」回炉
+
+## 五、通用小抄
+
+| 需求 | 做法 |
+|:---|:---|
+| 换落盘目录 / 主题 / 模板 | 改 user-config.md（升级永不覆盖） |
+| 官方发新版 | skill-forge update，配置冲突选 [2] 保留我的 |
+| 旧产物换新样式 | 说「把我旧 XX 都升级成新样式」 |
+| 装漏技能 | skill-forge init --skills 技能名 |
+| 查全部命令 | skill-forge --help |
+| 问单个技能用法 | 直接问「XX 技能怎么用」，AI 会读该技能的使用说明输出 |
+| 问 SkillForge 本身 | 问「skillforge 怎么用」，AI 朗读本指引并打开排版页 |
+
+## 六、常见问题
+
+1、装完对话没触发技能：确认装进了当前 AI 助手实际读取的技能目录（init 完成时输出的路径）
+2、deck-stage 报缺依赖：cd <技能目录>/deck-stage && npm install 补装 PptxGenJS 一次即可
+3、升级后配置会丢吗：不会。user-config.md（与 .preserve 清单内文件）升级永不覆盖，本地修改永久保留
+4、这份指引在哪：每个技能的 resources/ 目录里都有（skillforge-guide.txt 文字版 + skillforge-guide.html 排版版），官方升级时随技能资源一起更新

package/docs/architecture.en.md

@@ -0,0 +1,96 @@
+# Architecture & Conventions
+
+[中文](architecture.md)
+
+> This document describes the repository layout, skill anatomy (thin entry + resources), the eight core mechanisms, and the splitting conventions.
+
+## Directory Layout
+
+```
+.
+├── README.md                    # intro + output gallery + categories + skill list (English: README.en.md)
+├── CHANGELOG.md                 # version changelog (English: CHANGELOG.en.md)
+├── docs/                        # docs (install / architecture / usage examples / output screenshots; Chinese & English one-to-one)
+│   ├── install.md               # installation & upgrade in depth (English: install.en.md)
+│   ├── architecture.md          # this document (English: architecture.en.md)
+│   ├── usage-examples.md        # skill usage scenario examples (English: usage-examples.en.md)
+│   └── images/                  # output screenshots
+├── cli.js                       # installer (ls / init / update, zero-dependency Node>=14)
+├── package.json                 # npm package definition (skill-forge-hub, command name skill-forge)
+├── template/                    # new-skill template (thin entry + resources splitting conventions)
+├── meta-forge/                  # meta skill: forges skills (eight-mechanism embedding + repo registration)
+├── article-to-html/
+│   ├── SKILL.md                 # document → polished HTML full flow + per-chapter screenshots (with embedded usage guide)
+│   ├── design-system.md         # design system (fonts / colors / typography / chart redrawing)
+│   ├── user-config.md           # ⚙️ user config (THEME etc., never overwritten on upgrade)
+│   ├── .preserve                # upgrade preserve list (design-system.md is user-editable)
+│   └── scripts/                 # font install / docx extraction / font inlining scripts
+├── daily-report/ (weekly-report / monthly-report / quarterly-report / annual-report share the same shape)
+│   ├── SKILL.md                 # thin entry: frontmatter + generation flow + rules summary
+│   ├── user-config.md           # ⚙️ user config (CONFIG_VERSION + default config + custom templates)
+│   └── resources/               # heavy content split by generation stage, read on demand
+│       ├── usage-guide.md       # 📖 usage guide (verbatim source for usage-only answers)
+│       ├── date-parsing.md      # 🗓 date parsing (natural language first)
+│       ├── data-collection.md   # 📥 data collection (multi-source: verbal / text / files / images)
+│       ├── content-rules.md     # ✍️ content rules (aggregation sources / text-only mode / output format / writing style)
+│       ├── industry-dictionary.md # 🏭 industry adaptation (12-industry dictionary)
+│       └── disk-and-html.md     # 💾 local save / HTML styles / content-png capture spec
+├── magic-deck/
+│   ├── SKILL.md                 # thin entry: magic deck generation flow + rules summary
+│   ├── user-config.md           # ⚙️ user config
+│   └── resources/
+│       ├── usage-guide.md       # 📖 usage guide (features / hotkeys / capture / copy / fullscreen)
+│       ├── deck-spec.md         # full spec (skeleton / theme colors / template library / hotkey table / capture implementation)
+│       └── reference.html       # output skeleton (generation clones it and swaps content piece by piece)
+├── deck-stage/
+│   ├── SKILL.md                 # thin entry: stage-deck three-question interaction + generation flow
+│   ├── user-config.md           # ⚙️ user config
+│   ├── package.json             # dependency declaration (pptxgenjs)
+│   └── resources/
+│       ├── usage-guide.md       # 📖 usage guide
+│       ├── data-schema.md       # data.json structure (paragraph → page type / section color mapping)
+│       ├── pptx-builder.js      # source of truth: reads data.json, produces 16:9 pptx
+│       └── cover-template.html  # cover/closing capture template
+├── prompt-pouch/
+│   ├── SKILL.md                 # thin entry: prompt-pouch console generation flow
+│   ├── user-config.md           # ⚙️ user config (DIR/DATA_DIR/BACKUP_DIR etc.)
+│   └── resources/
+│       ├── usage-guide.md       # 📖 usage guide
+│       ├── data-format.md       # prompts.json data format
+│       └── reference.html       # output skeleton
+├── spec-doc2spec/ (spec-spec2doc shares the same shape)
+│   ├── SKILL.md                 # thin entry: Pandoc conversion + AI proofreading flow
+│   ├── user-config.md           # ⚙️ user config
+│   └── resources/               # volumes: checklist proofreading / images handling / structure organizing / pdf-path dual PDF paths / usage-guide
+├── quarterly-report/            # same shape as daily-report; quarterly specifics: QoQ/YoY dual baselines / Q1-Q4 trend chart / M1-M3 monthly timeline
+├── meeting-minutes/             # same shape as daily-report; minutes specifics: five sections / action-item triads / 12 meeting-type dictionaries
+└── weekly-report/               # same shape as daily-report; weekly specifics: WEEK_END week end / week targeting / weekly overview card / X.XD duration (1D=8H)
+```
+
+## Skill Anatomy
+
+- **SKILL.md keeps only**: the frontmatter, the generation-flow overview (each step names the resource it reads), the "⚙️ config & custom templates" pointer section (all user-editable config lives in user-config.md — must be read before every run), and a rules summary (3–5 hard rules).
+- **resources/ is one-file-one-job**: split by generation stage, with SKILL.md flow nodes annotated `read resources/xxx.md`; each resource is self-contained and readable on its own, with no cross-references.
+- **Usage-only answers**: when the user only asks how to use a skill without requesting generation, read `resources/usage-guide.md` and echo it verbatim (retitle the first heading to "<Skill> Usage Guide").
+- **User config extraction**: all user-editable content lives in `user-config.md` (with `CONFIG_VERSION` on the first line), never overwritten on upgrade.
+
+## The Eight Core Mechanisms
+
+| Mechanism | Description |
+|:---|:---|
+| CONFIG_VERSION key | The first line of user-config.md declares the config-structure version; bump by 1 whenever the official structure changes (keys added / renamed / removed) and document the migration rules in the SKILL.md "config version mechanism" section. Both the CLI updater and the AI self-check this version before running: version went up → back up as `.bak-<timestamp>` → interactive three-way choice (official overwrite / keep mine + `.upstream` companion / decide later). |
+| user-config extraction | User-editable content (default config + custom templates) is extracted from SKILL.md into a standalone `user-config.md`; SKILL.md keeps only the pointer section (must be read before every run). BUILTIN_PRESERVE plus the skill's `.preserve` list guard it doubly on upgrade, so local edits persist forever. |
+| reference dual-track | Skills that produce HTML (report family / magic deck / prompt pouch) keep a `resources/reference.html` as the visual source of truth: generation clones its skeleton and swaps content piece by piece, so output matches the official demo. Outputs carry an `sf-template` version stamp + a stable ID meta, enabling "reforge" upgrades of old outputs per the output-upgrade section. |
+| doc-sync self-check discipline | After touching any file, grep the whole repo to verify keywords — zero stale terms allowed; hard gates before delivery: headless (Playwright/Chrome) open with zero JS errors + screenshot proof that content is complete; static gates (frontmatter matches the declared version). IDs are locked to the standard UUID v4 format (crypto.randomUUID()) and checked for collisions by scanning the output directory before writing. |
+| .preserve list | Skills with semi-customizable assets (design systems / template drafts, files users may edit) declare them in a `.preserve` list: the CLI never overwrites these on upgrade, and official updates are saved as `.upstream` companions for manual merging. |
+| multi-file isolation | Pages with localStorage memory namespace their keys by an in-page embedded unique ID (standard UUID v4) — multiple outputs never cross-talk, and memories survive renames/moves; page-level self-healing: when the id meta is invalid/missing, the page heals itself to a standard v4 via a path key and writes it back to the meta. |
+| infringement-free, desensitized & offline | Zero brand fonts (free-for-commercial-use fonts only), no CDN so pages open offline, zero real identities in sample data (generic placeholders). |
+| output reforge upgrades | HTML carries a template version stamp (bumped on business / data-format / page changes); after an upgrade, old outputs can be interactively reforged (shallow upgrade = block replacement; deep upgrade = md rebuild), and generation proactively scans for old versions and suggests the trigger phrase; deep rebuilds of user-data skills must keep the page's stable ID (a new ID = lost data), and data files are never touched. |
+
+## Splitting Conventions
+
+- **New skills follow the `template/` structure**, directory name = skill name (lowercase-hyphen), and must be registered in the README category table + cli.js CATEGORIES + package.json files.
+- **Existing skills keep their own shape**: article-to-html uses a flat SKILL.md + design-system.md + scripts/ layout (its usage guide is embedded in the SKILL.md "user usage guide" section).
+- **General principles**: zero external dependencies (no CDN / external links, offline double-click works), cross-platform (macOS / Windows).
+- **Config upgrades**: bump CONFIG_VERSION and document migration rules; both CLI update and AI execution back up and prompt accordingly.
+- **Meta skill**: for meta-forge, `resources/forge-rules.md` is the source of truth (clarification checklist / structure / eight mechanisms / validation / repo registration); the SKILL.md flow and template/ both align with it.

package/docs/architecture.md

@@ -1,89 +1,96 @@
-# 架构与规范 · Architecture & Conventions
+# 架构与规范
 
-> 本文档描述仓库目录结构、技能形态（薄入口 + resources）、四大机制与拆分规范。This document describes the repository layout, skill anatomy (thin entry + resources), the four core mechanisms, and the splitting conventions.
+[English](architecture.en.md)
 
-## 目录结构 · Directory Layout
+> 本文档描述仓库目录结构、技能形态（薄入口 + resources）、八大机制与拆分规范。
+
+## 目录结构
 
 ```
 .
-├── README.md                    # 双语介绍 + 产物画廊 + 技能分类 + 技能清单 · bilingual intro, gallery, categories, skill list
-├── CHANGELOG.md                 # 版本变更记录 · version changelog
-├── docs/                        # 文档（安装升级 / 架构规范 / 产物截图）· docs (install / architecture / screenshots)
-│   ├── install.md               # 安装与升级详解 · installation & upgrade
-│   ├── architecture.md          # 本文档 · this document
-│   └── images/                  # 产物成品截图 · output screenshots
-├── cli.js                       # 安装器（ls / init / update，零依赖 Node>=14）· installer, zero-dependency Node>=14
-├── package.json                 # npm 包定义（skill-forge-hub，命令名 skill-forge）· npm package definition
-├── template/                    # 新技能模板（薄入口 + resources 拆分规范）· new-skill template
-├── meta-forge/                  # 元技能：造 skill 的 skill（四大机制植入 + 仓库登记）· meta skill: forges skills
+├── README.md                    # 介绍 + 产物画廊 + 技能分类 + 技能清单（英文版 README.en.md）
+├── CHANGELOG.md                 # 版本变更记录（英文版 CHANGELOG.en.md）
+├── docs/                        # 文档（安装升级 / 架构规范 / 使用示例 / 产物截图，中英一一对应）
+│   ├── install.md               # 安装与升级详解（英文版 install.en.md）
+│   ├── architecture.md          # 本文档（英文版 architecture.en.md）
+│   ├── usage-examples.md        # 技能使用场景示例（英文版 usage-examples.en.md）
+│   └── images/                  # 产物成品截图
+├── cli.js                       # 安装器（ls / init / update，零依赖 Node>=14）
+├── package.json                 # npm 包定义（skill-forge-hub，命令名 skill-forge）
+├── template/                    # 新技能模板（薄入口 + resources 拆分规范）
+├── meta-forge/                  # 元技能：造 skill 的 skill（八大机制植入 + 仓库登记）
 ├── article-to-html/
 │   ├── SKILL.md                 # 文档 → 精美 HTML 完整流程 + 逐章截图（含内嵌使用说明）
-│   ├── design-system.md         # 设计系统（字体 / 配色 / 排版 / 图表重绘）· design system
-│   ├── user-config.md           # ⚙️ 用户配置（THEME 等，升级不覆盖）· user config
-│   ├── .preserve                # 升级保留清单（design-system.md 用户可改）· extra preserve list
-│   └── scripts/                 # 字体安装 / docx 抽取 / 字体内联脚本 · font & extraction scripts
-├── daily-report/（weekly-report / monthly-report / quarterly-report / annual-report 同构 · same shape）
-│   ├── SKILL.md                 # 薄入口：frontmatter + 生成流程 + 规则速览 · thin entry
-│   ├── user-config.md           # ⚙️ 用户配置（CONFIG_VERSION + 默认配置 + 自定义模板）· user config
-│   └── resources/               # 重内容按生成阶段拆分，AI 按需读取 · heavy content split by stage
-│       ├── usage-guide.md       # 📖 使用说明（咨询应答的原样输出源）· usage guide
-│       ├── date-parsing.md      # 🗓 日期解析（自然语言优先）· date parsing
-│       ├── data-collection.md   # 📥 数据收集（多源聚合：口述 / 文字 / 文件 / 图片）· data collection
-│       ├── content-rules.md     # ✍️ 内容规则（聚合来源 / 纯文字模式 / 输出格式 / 写作风格）· content rules
-│       ├── industry-dictionary.md # 🏭 行业适配（12 行业职业词典）· industry dictionary
-│       └── disk-and-html.md     # 💾 本地落盘 / HTML 样式 / content-png 截图规范 · disk & HTML spec
+│   ├── design-system.md         # 设计系统（字体 / 配色 / 排版 / 图表重绘）
+│   ├── user-config.md           # ⚙️ 用户配置（THEME 等，升级不覆盖）
+│   ├── .preserve                # 升级保留清单（design-system.md 用户可改）
+│   └── scripts/                 # 字体安装 / docx 抽取 / 字体内联脚本
+├── daily-report/（weekly-report / monthly-report / quarterly-report / annual-report 同构）
+│   ├── SKILL.md                 # 薄入口：frontmatter + 生成流程 + 规则速览
+│   ├── user-config.md           # ⚙️ 用户配置（CONFIG_VERSION + 默认配置 + 自定义模板）
+│   └── resources/               # 重内容按生成阶段拆分，AI 按需读取
+│       ├── usage-guide.md       # 📖 使用说明（咨询应答的原样输出源）
+│       ├── date-parsing.md      # 🗓 日期解析（自然语言优先）
+│       ├── data-collection.md   # 📥 数据收集（多源聚合：口述 / 文字 / 文件 / 图片）
+│       ├── content-rules.md     # ✍️ 内容规则（聚合来源 / 纯文字模式 / 输出格式 / 写作风格）
+│       ├── industry-dictionary.md # 🏭 行业适配（12 行业职业词典）
+│       └── disk-and-html.md     # 💾 本地落盘 / HTML 样式 / content-png 截图规范
 ├── magic-deck/
-│   ├── SKILL.md                 # 薄入口：魔法幻灯生成流程 + 规则速览 · thin entry
-│   ├── user-config.md           # ⚙️ 用户配置 · user config
+│   ├── SKILL.md                 # 薄入口：魔法幻灯生成流程 + 规则速览
+│   ├── user-config.md           # ⚙️ 用户配置
 │   └── resources/
-│       ├── usage-guide.md       # 📖 使用说明（功能/热键/截图/复制/全屏）· usage guide
-│       ├── deck-spec.md         # 完整规范（骨架/主题色值/模板库/热键表/截图实现）· full deck spec
-│       └── reference.html       # 成品骨架（生成时以此为骨逐处替换内容）· output skeleton
+│       ├── usage-guide.md       # 📖 使用说明（功能/热键/截图/复制/全屏）
+│       ├── deck-spec.md         # 完整规范（骨架/主题色值/模板库/热键表/截图实现）
+│       └── reference.html       # 成品骨架（生成时以此为骨逐处替换内容）
 ├── deck-stage/
-│   ├── SKILL.md                 # 薄入口：登台 PPTX 三问交互 + 生成流程 · thin entry
-│   ├── user-config.md           # ⚙️ 用户配置 · user config
-│   ├── package.json             # 依赖声明（pptxgenjs）· dependency declaration
+│   ├── SKILL.md                 # 薄入口：登台 PPTX 三问交互 + 生成流程
+│   ├── user-config.md           # ⚙️ 用户配置
+│   ├── package.json             # 依赖声明（pptxgenjs）
 │   └── resources/
-│       ├── usage-guide.md       # 📖 使用说明 · usage guide
-│       ├── data-schema.md       # data.json 结构（段落 → 页类型/节色映射）· data schema
-│       ├── pptx-builder.js      # 真相源：读 data.json 产 16:9 pptx · source of truth
-│       └── cover-template.html  # 封面/结尾截图底版 · cover/closing capture template
+│       ├── usage-guide.md       # 📖 使用说明
+│       ├── data-schema.md       # data.json 结构（段落 → 页类型/节色映射）
+│       ├── pptx-builder.js      # 真相源：读 data.json 产 16:9 pptx
+│       └── cover-template.html  # 封面/结尾截图底版
 ├── prompt-pouch/
-│   ├── SKILL.md                 # 薄入口：锦囊管理台生成流程 · thin entry
-│   ├── user-config.md           # ⚙️ 用户配置（DIR/DATA_DIR/BACKUP_DIR 等）· user config
+│   ├── SKILL.md                 # 薄入口：锦囊管理台生成流程
+│   ├── user-config.md           # ⚙️ 用户配置（DIR/DATA_DIR/BACKUP_DIR 等）
 │   └── resources/
-│       ├── usage-guide.md       # 📖 使用说明 · usage guide
-│       ├── data-format.md       # prompts.json 数据格式 · data format
-│       └── reference.html       # 成品骨架 · output skeleton
-├── spec-doc2spec/（spec-spec2doc 同构 · same shape）
-│   ├── SKILL.md                 # 薄入口：Pandoc 转换 + AI 校对流程 · thin entry
-│   ├── user-config.md           # ⚙️ 用户配置 · user config
+│       ├── usage-guide.md       # 📖 使用说明
+│       ├── data-format.md       # prompts.json 数据格式
+│       └── reference.html       # 成品骨架
+├── spec-doc2spec/（spec-spec2doc 同构）
+│   ├── SKILL.md                 # 薄入口：Pandoc 转换 + AI 校对流程
+│   ├── user-config.md           # ⚙️ 用户配置
 │   └── resources/               # 分册：checklist 校对清单 / images 图片处理 / structure 目录组织 / pdf-path PDF 双路径 / usage-guide
 ├── quarterly-report/            # 结构同 daily-report，季报专属差异：环比/同比双基准 / Q1-Q4 走势图 / M1-M3 月时间线
 ├── meeting-minutes/             # 结构同 daily-report，纪要专属差异：五段式 / 行动项三要素 / 12 类会议词典
 └── weekly-report/               # 结构同 daily-report，周报专属差异：WEEK_END 周结束日 / 周定位解析 / 本周概览卡 / 用时 X.XD（1D=8H）
 ```
 
-## 技能形态 · Skill Anatomy
+## 技能形态
 
-- **SKILL.md 只保留**：frontmatter、生成流程总览（每步标注读哪个 resource）、「⚙️ 默认配置」「📝 自定义模板」（用户手改的配置必须留在入口）、规则速览（3-5 条硬性规则）。SKILL.md keeps only: frontmatter, the generation-flow overview (each step names its resource), the user-config pointer, and a rules summary (3-5 hard rules).
-- **resources/ 一文件一职责**：按生成阶段拆分，SKILL.md 流程节点标注 `读 resources/xxx.md`；每份 resource 独立可读，不互相引用。resources/ is one-file-one-job: split by generation stage, each file standalone, no cross-references.
-- **咨询应答**：用户只问用法不要求生成时，读 `resources/usage-guide.md` 原样输出（首行标题按技能改为「XX生成器使用指南」）。Usage-only questions read usage-guide.md and echo it verbatim.
-- **用户配置抽离**：所有用户可改内容在 `user-config.md`（首行 `CONFIG_VERSION`），升级永不覆盖。All user-editable content lives in user-config.md (CONFIG_VERSION on the first line), never overwritten on upgrade.
+- **SKILL.md 只保留**：frontmatter、生成流程总览（每步标注读哪个 resource）、「⚙️ 配置与自定义模板」指引段（用户可改配置全部出站在 user-config.md，执行前必须先 Read）、规则速览（3-5 条硬性规则）。
+- **resources/ 一文件一职责**：按生成阶段拆分，SKILL.md 流程节点标注 `读 resources/xxx.md`；每份 resource 独立可读，不互相引用。
+- **咨询应答**：用户只问用法不要求生成时，读 `resources/usage-guide.md` 原样输出（首行标题按技能改为「XX生成器使用指南」）。
+- **用户配置抽离**：所有用户可改内容在 `user-config.md`（首行 `CONFIG_VERSION`），升级永不覆盖。
 
-## 四大机制 · The Four Core Mechanisms
+## 八大机制
 
-| 机制 Mechanism | 说明 Description |
+| 机制 | 说明 |
 |:---|:---|
-| CONFIG_VERSION 钥匙<br>CONFIG_VERSION key | `user-config.md` 首行声明配置结构版本；官方结构变化（新增/改名/删除配置键）时递增 1 并在 SKILL.md「配置版本机制」节写明迁移规则。CLI 升级与 AI 执行前都自检该版本：版本升了 → 备份 `.bak-时间戳` → 交互三选一（官方覆盖 / 保留我的 + `.upstream` 对照 / 稍后处理）。<br>First line of user-config.md declares the config-structure version; bump by 1 whenever the official structure changes (keys added / renamed / removed) and document migration rules in SKILL.md. Both the CLI updater and the AI self-check this version before running. |
-| user-config 抽离<br>user-config extraction | 用户可改内容（默认配置 yaml + 自定义模板）从 SKILL.md 抽离到独立 `user-config.md`，SKILL.md 只留指引段（执行前必须先 Read）。升级时 BUILTIN_PRESERVE + 技能 `.preserve` 清单双重保护，本地修改永久保留。<br>User-editable content (default config + custom templates) is extracted from SKILL.md into user-config.md; SKILL.md keeps only the pointer. BUILTIN_PRESERVE plus the skill's .preserve list guard it on upgrade. |
-| reference 双轨<br>reference dual-track | 成品 HTML 形态的技能（报表族 / 魔法幻灯 / 锦囊）以 `resources/reference.html` 为视觉真相源：生成时以此为骨逐处替换内容，保证产物样式与官方演示一致；产物头部带 `sf-template` 版本戳 + 稳定 ID meta，按「产物升级（回炉）」节可把旧产物升级到新模板。<br>Skills that produce HTML keep a reference.html as the visual source of truth; generation clones its skeleton, so output matches the official demo. Outputs carry an sf-template version stamp + stable ID meta, enabling "回炉" (reforge) upgrades of old outputs. |
-| 自检纪律<br>self-check discipline | 交付前硬门禁：Playwright/Chrome headless 打开产物零 JS 错误 + 截图验证内容完整；静态门禁（grep 残留旧词 / frontmatter 与版本声明一致）。ID 格式定死（crypto.randomUUID() 标准 v4），落盘前顺扫目录查重。<br>Hard gates before delivery: headless open with zero JS errors + screenshot proof; static gates (no stale terms, consistent frontmatter). IDs are locked to the standard UUID v4 format and checked for collisions before writing. |
+| CONFIG_VERSION 钥匙 | `user-config.md` 首行声明配置结构版本；官方结构变化（新增/改名/删除配置键）时递增 1 并在 SKILL.md「配置版本机制」节写明迁移规则。CLI 升级与 AI 执行前都自检该版本：版本升了 → 备份 `.bak-时间戳` → 交互三选一（官方覆盖 / 保留我的 + `.upstream` 对照 / 稍后处理）。 |
+| user-config 抽离 | 用户可改内容（默认配置 + 自定义模板）从 SKILL.md 抽离到独立 `user-config.md`，SKILL.md 只留指引段（执行前必须先 Read）。升级时 BUILTIN_PRESERVE + 技能 `.preserve` 清单双重保护，本地修改永久保留。 |
+| reference 双轨 | 成品 HTML 形态的技能（报表族 / 魔法幻灯 / 锦囊）以 `resources/reference.html` 为视觉真相源：生成时以此为骨逐处替换内容，保证产物样式与官方演示一致；产物头部带 `sf-template` 版本戳 + 稳定 ID meta，按「产物升级（回炉）」节可把旧产物升级到新模板。 |
+| 文档同步自检纪律 | 改任一文件 grep 全仓核对关键词，旧词零残留；交付前硬门禁：Playwright/Chrome headless 打开产物零 JS 错误 + 截图验证内容完整；静态门禁（frontmatter 与版本声明一致）。ID 格式定死（crypto.randomUUID() 标准 v4），落盘前顺扫目录查重。 |
+| .preserve 保护清单 | 技能含半定制资产（设计系统 / 模板底稿等用户可改文件）时，用 `.preserve` 清单声明：CLI 升级永不覆盖这些文件，官方更新另存 `.upstream` 对照，可按需手动合并。 |
+| 多文件隔离 | 页面有 localStorage 记忆时，键按页内嵌唯一 ID（标准 UUID v4）命名空间——多份产物互不串台、改名/移动目录记忆不丢；页面执行层自愈：id meta 非法/缺失时按路径键自愈为标准 v4 并回写 meta。 |
+| 零侵权脱敏离线 | 品牌字体零出现（只用免费商用字体）、禁 CDN 页面离线可开、示例数据零真实身份（通用占位）。 |
+| 产物升级回炉 | HTML 带模板版本戳（业务/数据格式/页面改动均 bump），升级后可扫旧产物交互式回炉（浅升级区块替换 / 深升级 md 重建），生成时顺扫旧版主动提示触发语；用户数据类深升级重建必须沿用原页稳定 ID（换 ID = 数据失联），数据文件一概不动。 |
 
-## 拆分规范 · Splitting Conventions
+## 拆分规范
 
-- **新技能按 `template/` 结构创建**，目录名 = 技能名（英文短横线），并归入 README「技能分类」表对应分类 + 同步 cli.js CATEGORIES 与 package.json files。New skills follow the template/ structure, directory name = skill name (lowercase-hyphen), and must be registered in the README category table + cli.js CATEGORIES + package.json files.
-- **已有技能按各自结构维护**：article-to-html 采用 SKILL.md + design-system.md + scripts/ 平铺结构（使用说明内嵌 SKILL.md「用户使用说明」节）。Existing skills keep their own shape; article-to-html uses a flat SKILL.md + design-system.md + scripts/ layout.
-- **通用原则**：零外部依赖（禁 CDN / 外链，内网离线双击可开）、双系统兼容（macOS / Windows）。General principles: zero external dependencies (no CDN / external links, offline double-click works), cross-platform (macOS / Windows).
-- **配置升级**：user-config.md 首行带 `CONFIG_VERSION`，官方配置结构变化时递增并写明迁移规则；CLI update 与 AI 执行时均按该版本做备份 + 迁移提示。Config upgrades: bump CONFIG_VERSION and document migration rules; both CLI update and AI execution back up and prompt accordingly.
-- **元技能**：meta-forge 造技能时的规范真相源在 `resources/forge-rules.md`（澄清清单 / 结构规范 / 四大机制 / 校验清单 / 仓库登记），SKILL.md 流程节点与 template/ 模板均与之对齐。For the meta skill, forge-rules.md is the source of truth (clarification checklist / structure / four mechanisms / validation / repo registration); SKILL.md flow and template/ both align with it.
+- **新技能按 `template/` 结构创建**，目录名 = 技能名（英文短横线），并归入 README「技能分类」表对应分类 + 同步 cli.js CATEGORIES 与 package.json files。
+- **已有技能按各自结构维护**：article-to-html 采用 SKILL.md + design-system.md + scripts/ 平铺结构（使用说明内嵌 SKILL.md「用户使用说明」节）。
+- **通用原则**：零外部依赖（禁 CDN / 外链，内网离线双击可开）、双系统兼容（macOS / Windows）。
+- **配置升级**：user-config.md 首行带 `CONFIG_VERSION`，官方配置结构变化时递增并写明迁移规则；CLI update 与 AI 执行时均按该版本做备份 + 迁移提示。
+- **元技能**：meta-forge 造技能时的规范真相源在 `resources/forge-rules.md`（澄清清单 / 结构规范 / 八大机制 / 校验清单 / 仓库登记），SKILL.md 流程节点与 template/ 模板均与之对齐。

package/docs/install.en.md

@@ -0,0 +1,125 @@
+# Installation & Upgrade
+
+[中文](install.md)
+
+> This document covers both install methods, the command reference, and the config-protection mechanics applied on upgrade.
+
+## Method 1: Global npm Install (Recommended)
+
+```bash
+npm i -g skill-forge-hub
+skill-forge ls        # list all skills & descriptions (read-only)
+skill-forge init      # interactive skill picker, auto-detects & installs to the AI assistant's skill directory
+npm update -g skill-forge-hub    # upgrade the CLI itself after a release (this package only)
+skill-forge update    # upgrade installed skills (config-version aware, see below)
+```
+
+Non-interactive / explicit directory:
+
+```bash
+skill-forge init --target ~/.claude/skills --skills daily-report,weekly-report
+```
+
+> **deck-stage dependency note**: deck-stage needs PptxGenJS. Installing directly from this repo copies the skill's node_modules along (works offline); the npm global package excludes node_modules, so the CLI prompts `cd <skill dir>/deck-stage && npm install` to install it once.
+
+## Method 2: Manual Copy
+
+Copy the skill directories into your AI assistant's skill directory (any assistant supporting the SKILL.md format works).
+
+```bash
+cp -R daily-report weekly-report monthly-report quarterly-report annual-report <your AI assistant's skill directory>/
+cp -R magic-deck prompt-pouch <your AI assistant's skill directory>/
+cp -R spec-doc2spec spec-spec2doc <your AI assistant's skill directory>/
+```
+
+After copying, say "write a daily report", "write a weekly report", "write a monthly report", "write a quarterly report", "write an annual report", "take meeting minutes", or hand it a document to trigger a skill; asking "how do I use daily-report / weekly-report / monthly-report / quarterly-report / meeting-minutes / deck-stage" prints the usage guide.
+
+## Command Reference
+
+| Command | Description |
+|:---|:---|
+| `skill-forge ls` | List all skills (category + name + description), read-only |
+| `skill-forge init` | Interactive pick from the list: a=install all / pick by number (installed marked ★; confirm with s to skip installed and install only new ones) |
+| `skill-forge update` | Upgrade all installed skills (config-version aware) |
+| `skill-forge update --skills a,b` | Upgrade only the named skills (uninstalled ones are skipped with a notice) |
+| `skill-forge --version` | Show version |
+| `skill-forge --help` | Show full help |
+
+Common flags (for init / update):
+
+| Flag | Description |
+|:---|:---|
+| `--target <dir>` (`-t`) | Explicit skill directory; defaults to auto-detecting common assistant dirs (~/.qoder-cn, ~/.claude, ~/.cursor, ...), interactive pick when several are found |
+| `--skills a,b` (`-s`) | Named skill list: init skips the picker and installs/upgrades exactly these (good for scripts); update upgrades only these |
+| `--yes` (`-y`) | Skip confirmation; on config-version change defaults to "keep mine + official copy saved as .upstream" |
+
+Command aliases: `list` = `ls`, `install` = `init`, `upgrade` = `update`.
+
+## Scenario Walkthroughs
+
+### Scenario 1: first-time setup (zero to working)
+
+```bash
+npm i -g skill-forge-hub     # 1. global install of the CLI
+skill-forge ls               # 2. browse the skill list first (read-only, writes nothing)
+skill-forge init             # 3. interactively pick the skills to install
+```
+
+How `skill-forge init` works: lists every skill (category + name + one-line description) → type `a` to install all, or type numbers to pick (e.g. `1,3,5`; installed skills are marked ★) → on confirm, type `s` to skip installed and install only new ones → auto-detect the AI assistant's skill directory (pick by number when several are found) → done.
+
+After that, just talk to it: "write a daily report", "write a weekly report", "write a monthly report", "write a quarterly report", "write an annual report", "take meeting minutes", or hand it a document.
+
+### Scenario 2: single-skill install (scripts / just one)
+
+```bash
+skill-forge init --skills prompt-pouch --target ~/.qoder-cn/skills
+```
+
+Skips the picker and installs exactly the named skill to the named directory — good for scripting, CI, or topping up a single skill.
+
+### Scenario 3: upgrading after an official release
+
+```bash
+npm update -g skill-forge-hub                    # first upgrade the CLI itself (this package only)
+skill-forge update                              # then upgrade all installed skills
+skill-forge update --skills daily-report        # upgrade just one
+```
+
+- **Config structure unchanged**: silent upgrade — skill files update, your `user-config.md` stays untouched
+- **Config structure changed** (official `CONFIG_VERSION` bumped): your config is first backed up as `user-config.md.bak-<timestamp>`, then a three-way choice:
+  - `[1] official overwrite`: take the fresh official config (your old one is recoverable from the backup)
+  - `[2] keep mine` (default, safest): your config stays, the official version is saved as `user-config.md.upstream` for you to compare and merge new config points manually
+  - `[3] decide later`: skip this time, no companion file generated
+- **Official files deleted**: cleaned up precisely via the `.installed-manifest` (only files the official version deleted, plus now-empty directories); your self-created files are never touched
+
+### Scenario 4: non-interactive / automation
+
+```bash
+skill-forge init --skills daily-report,weekly-report --yes
+```
+
+`--yes` skips every confirmation; on config-version conflict it defaults to `[2] keep mine` (the safest branch).
+
+### Scenario 5: new machine / new AI assistant
+
+Run `npm i -g skill-forge-hub && skill-forge init` in the new environment; to carry your personal config over, copy the old `user-config.md` from the previous skill directory (never overwritten on upgrade, kept on install too).
+
+### FAQ
+
+- **Skills don't trigger after install**: check the CLI installed into the skill directory your AI assistant actually reads (the path printed when init finishes)
+- **deck-stage complains about a missing dependency**: run `cd <skill dir>/deck-stage && npm install` once for PptxGenJS
+- **Will upgrades wipe my config**: never. `user-config.md` (and `.preserve`-listed files) are never overwritten on upgrade — your local edits persist forever
+
+## Upgrade & Config Protection
+
+`skill-forge update` (all installed skills by default, or `--skills a,b`) protects your config before overwriting any skill files.
+
+- **Always preserved**: an existing `user-config.md` in the target directory (and any files declared in the skill's `.preserve` list) is never overwritten — your local config persists forever; when the official config gains updates, a `.upstream` companion file is saved so you can merge new config points manually
+- **Version aware**: when the official `user-config.md` declares a `CONFIG_VERSION` on its first line higher than your local version (config structure grew / shrank / was renamed) —
+  1. your config is first backed up as `user-config.md.bak-<timestamp>`
+  2. interactive three-way choice: `[1] official overwrite` (old config recoverable from the backup) / `[2] keep mine` + official copy saved as `.upstream` (default) / `[3] decide later` (no companion file generated this time)
+  3. `--yes` or non-interactive environments default to `[2]`, the safest option
+- **Version match**: silent upgrade — only skill files are updated, config stays untouched
+- **Structure sync**: upgrades sync official file additions/removals precisely via the `.installed-manifest` — only files listed in the manifest that the official version deleted (and now-empty directories) are cleaned up, self-created user files are never touched (older installs without a manifest skip cleanup and get the manifest written after upgrade); `user-config.md`, `.preserve` list files, `.upstream` companions, `.bak-*` backups and `node_modules` dependencies are never touched
+
+Maintainer conventions: whenever the official config structure changes (keys added / renamed / removed), bump `CONFIG_VERSION` in `user-config.md` by 1 and document the migration rules in the SKILL.md "config version mechanism" section (the AI also self-checks this version before every run).