skill-forge-hub 1.0.6 → 1.1.0

package/docs/install.md

@@ -1,29 +1,30 @@
-# 安装与升级 · Installation & Upgrade
+# 安装与升级
 
-> 本文档详述 SkillForge 的两种安装方式、命令参考，以及升级时的配置保护机制。This document covers both install methods, the command reference, and the config-protection mechanics applied on upgrade.
+[English](install.en.md)
 
-## 方式一：npm 全局安装（推荐） · Method 1: Global npm Install (Recommended)
+> 本文档详述 SkillForge 的两种安装方式、命令参考，以及升级时的配置保护机制。
+
+## 方式一：npm 全局安装（推荐）
 
 ```bash
 npm i -g skill-forge-hub
-skill-forge ls        # 列出全部技能与说明（只读）· list all skills (read-only)
-skill-forge init      # 交互式挑选技能，自动探测并安装到 AI 助手技能目录 · pick skills interactively
-skill-forge update    # 升级已安装技能（配置版本感知，见下）· upgrade installed skills (config-version aware)
+skill-forge ls        # 列出全部技能与说明（只读）
+skill-forge init      # 交互式挑选技能，自动探测并安装到 AI 助手技能目录
+npm update -g skill-forge-hub    # 官方发新版后升级 CLI 本体（只升级本包）
+skill-forge update    # 升级已安装技能（配置版本感知，见下）
 ```
 
-非交互 / 指定目录场景 · Non-interactive or explicit directory:
+非交互 / 指定目录场景：
 
 ```bash
 skill-forge init --target ~/.claude/skills --skills daily-report,weekly-report
 ```
 
 > **deck-stage 依赖说明**：deck-stage 需要 PptxGenJS。从本仓库直接 init 会连带复制技能目录内 node_modules，离线可用；npm 全局装出的包不含 node_modules，安装时会提示 `cd <技能目录>/deck-stage && npm install` 补装一次即可。
->
-> **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
+## 方式二：手动复制
 
-将技能目录复制到你所用的 AI 助手的技能目录（支持 SKILL.md 格式、本地加载技能的助手均可）。Copy the skill directories into your AI assistant's skill directory (any assistant supporting the SKILL.md format works).
+将技能目录复制到你所用的 AI 助手的技能目录（支持 SKILL.md 格式、本地加载技能的助手均可）。
 
 ```bash
 cp -R daily-report weekly-report monthly-report quarterly-report annual-report <你的 AI 助手技能目录>/
@@ -33,39 +34,92 @@ cp -R spec-doc2spec spec-spec2doc <你的 AI 助手技能目录>/
 
 复制后直接说「写日报」「写周报」「写月报」「写季报」「写年报」「记会议」或丢给它一个文档即可触发；问「日报怎么用 / 周报怎么用 / 月报怎么用 / 季报怎么用 / 会议纪要怎么用 / 登台怎么用」输出使用说明。
 
-After copying, say "写日报" (write a daily report), "记会议" (take minutes), or hand it a document to trigger a skill; asking "how to use X" prints the usage guide.
-
-## 命令参考 · Command Reference
+## 命令参考
 
-| 命令 Command | 说明 Description |
+| 命令 | 说明 |
 |:---|:---|
-| `skill-forge ls` | 列出全部技能（分类 + 名称 + 说明），只读 · List all skills (category + name + description), read-only |
-| `skill-forge init` | 列清单交互挑选：a=全部安装 / 编号挑选（已装标 ★，确认时可 s 跳过已装只装新）· Interactive pick: a=all / numbered (installed marked ★; confirm with s to skip installed) |
-| `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 |
+| `skill-forge ls` | 列出全部技能（分类 + 名称 + 说明），只读 |
+| `skill-forge init` | 列清单交互挑选：a=全部安装 / 编号挑选（已装标 ★，确认时可 s 跳过已装只装新） |
+| `skill-forge update` | 升级全部已安装技能（配置版本感知） |
+| `skill-forge update --skills a,b` | 只升级指定技能（未安装的提示跳过） |
+| `skill-forge --version` | 显示版本号 |
+| `skill-forge --help` | 显示完整帮助 |
 
-通用参数（init / update 通用）· Common flags (for init / update):
+通用参数（init / update 通用）：
 
-| 参数 Flag | 说明 Description |
+| 参数 | 说明 |
 |:---|:---|
-| `--target <目录>`（`-t`） | 指定技能目录；缺省自动探测常见助手目录（~/.qoder-cn、~/.claude、~/.cursor 等），探测到多个时交互选择 · Explicit skill directory; defaults to auto-detecting common assistant dirs (~/.qoder-cn, ~/.claude, ~/.cursor, ...), interactive pick when several are found |
-| `--skills a,b`（`-s`） | 指定技能名列表：init 时跳过选择直接安装/升级指定技能（适合脚本与单件补装）；update 时只升级指定技能 · Named skill list: init skips the picker and installs/upgrades exactly these (good for scripts); update upgrades only these |
-| `--yes`（`-y`） | 跳过确认直接执行；配置版本变化时默认「保留我的 + 官方版另存 .upstream 对照」· Skip confirmation; on config-version change defaults to "keep mine + official copy saved as .upstream" |
+| `--target <目录>`（`-t`） | 指定技能目录；缺省自动探测常见助手目录（~/.qoder-cn、~/.claude、~/.cursor 等），探测到多个时交互选择 |
+| `--skills a,b`（`-s`） | 指定技能名列表：init 时跳过选择直接安装/升级指定技能（适合脚本与单件补装）；update 时只升级指定技能 |
+| `--yes`（`-y`） | 跳过确认直接执行；配置版本变化时默认「保留我的 + 官方版另存 .upstream 对照」 |
+
+命令别名：`list` = `ls`、`install` = `init`、`upgrade` = `update`。
+
+## 场景化使用流程
+
+### 场景一：新用户首次接入（从零到可用）
+
+```bash
+npm i -g skill-forge-hub     # 1. 全局安装 CLI
+skill-forge ls               # 2. 先浏览技能清单（只读，不写任何文件）
+skill-forge init             # 3. 交互式挑选要装的技能
+```
+
+`skill-forge init` 的交互过程：列出全部技能（分类 + 名称 + 一句话说明）→ 输入 `a` 全装，或输入编号挑选（如 `1,3,5`，已装技能标 ★）→ 确认时输 `s` 跳过已装、只装新技能 → 自动探测 AI 助手技能目录（探测到多个时按编号选择）→ 完成安装。
+
+装完即可直接对话触发：「写日报」「写周报」「写月报」「写季报」「写年报」「记会议」，或直接丢给它一个文档。
+
+### 场景二：单件补装（脚本 / 只想要某一个）
+
+```bash
+skill-forge init --skills prompt-pouch --target ~/.qoder-cn/skills
+```
+
+跳过挑选环节，只装指定技能到指定目录——适合脚本化、CI 或补装单个技能。
+
+### 场景三：官方发新版后升级
+
+```bash
+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] 保留我的`（默认，最安全）：你的配置不动，官方新版另存 `user-config.md.upstream` 对照文件，自己对比后按需合并新配置点
+  - `[3] 稍后处理`：本次跳过，不生成对照文件
+- **官方删了文件**：按 `.installed-manifest` 安装清单精准清理官方已删除的文件与空目录；你自建的文件一律不动
+
+### 场景四：非交互 / 自动化
+
+```bash
+skill-forge init --skills daily-report,weekly-report --yes
+```
+
+`--yes` 跳过一切确认；配置版本冲突时默认走 `[2] 保留我的`（最安全分支）。
+
+### 场景五：换机器 / 换 AI 助手
+
+新环境重新 `npm i -g skill-forge-hub && skill-forge init` 即可；要保留个人配置，把旧机器技能目录里的 `user-config.md` 一并拷过去（升级永不覆盖，覆盖安装时也保留）。
+
+### 常见问题
 
-命令别名：`list` = `ls`、`install` = `init`、`upgrade` = `update`。Command aliases: `list` = `ls`, `install` = `init`, `upgrade` = `update`.
+- **装完对话没触发技能**：确认装进了当前 AI 助手实际读取的技能目录（`init` 完成时输出的路径）
+- **deck-stage 报缺依赖**：`cd <技能目录>/deck-stage && npm install` 补装 PptxGenJS 一次即可
+- **升级后配置会丢吗**：不会。`user-config.md`（与 `.preserve` 清单内文件）升级永不覆盖，本地修改永久保留
 
-## 升级与配置保护 · Upgrade & Config Protection
+## 升级与配置保护
 
-`skill-forge update`（默认升级全部已装技能，可用 `--skills a,b` 指定）在覆盖技能文件前自动保护你的配置。`skill-forge update` (all installed skills by default, or `--skills a,b`) protects your config before overwriting any skill files.
+`skill-forge update`（默认升级全部已装技能，可用 `--skills a,b` 指定）在覆盖技能文件前自动保护你的配置。
 
-- **常驻保护 · Always preserved**：目标目录已存在的 `user-config.md`（及技能 `.preserve` 清单声明的文件）永不被覆盖，你的本地配置永久保留；官方配置内容有更新时另存 `.upstream` 对照文件，可按需手动合并新配置点
-- **版本感知 · Version aware**：官方 `user-config.md` 首行的 `CONFIG_VERSION` 高于你的本地版本（配置结构增/减/改名）时——
+- **常驻保护**：目标目录已存在的 `user-config.md`（及技能 `.preserve` 清单声明的文件）永不被覆盖，你的本地配置永久保留；官方配置内容有更新时另存 `.upstream` 对照文件，可按需手动合并新配置点
+- **版本感知**：官方 `user-config.md` 首行的 `CONFIG_VERSION` 高于你的本地版本（配置结构增/减/改名）时——
   1. 先把你的配置备份为 `user-config.md.bak-<时间戳>`
   2. 交互三选一：`[1] 官方覆盖`（旧配置在备份中随时找回）/ `[2] 保留我的` + 官方版另存 `.upstream` 对照（默认）/ `[3] 稍后处理`（本次不生成对照文件）
   3. `--yes` 或非交互环境默认 `[2]`，最安全
-- **版本一致 · Version match**：无感升级，只更新技能文件，配置原样保留
-- **结构同步 · Structure sync**：升级按 `.installed-manifest` 安装清单精准同步官方文件增删——只清理清单内官方已删除的文件与空目录，用户自建文件一律不动（旧版本安装无清单时跳过清理，升级后补写）；`user-config.md`、`.preserve` 清单文件、`.upstream` 对照、`.bak-*` 备份与 `node_modules` 依赖永远不动
+- **版本一致**：无感升级，只更新技能文件，配置原样保留
+- **结构同步**：升级按 `.installed-manifest` 安装清单精准同步官方文件增删——只清理清单内官方已删除的文件与空目录，用户自建文件一律不动（旧版本安装无清单时跳过清理，升级后补写）；`user-config.md`、`.preserve` 清单文件、`.upstream` 对照、`.bak-*` 备份与 `node_modules` 依赖永远不动
 
-技能维护者约定 · Maintainer conventions：官方配置结构每次变化（新增/改名/删除配置键）时，`user-config.md` 的 `CONFIG_VERSION` 递增 1，并在 SKILL.md「配置版本机制」节写明迁移规则（AI 每次执行前也会自检该版本）。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 "配置版本机制" section (the AI self-checks this version before every run).
+技能维护者约定：官方配置结构每次变化（新增/改名/删除配置键）时，`user-config.md` 的 `CONFIG_VERSION` 递增 1，并在 SKILL.md「配置版本机制」节写明迁移规则（AI 每次执行前也会自检该版本）。

package/docs/usage-examples.en.md

@@ -0,0 +1,50 @@
+# Skill Usage Examples
+
+[中文](usage-examples.md)
+
+> End-to-end examples, from install to everyday use. Four representative skills are picked: daily-report (representative of the report family, covering config tweaks and output reforge), prompt-pouch (local console, covering user data and multi-file isolation), magic-deck & deck-stage (both PPT forms, covering intent routing and dependency install), meeting-minutes (source of the reporting chain, covering series grouping). The other skills share the same shape as these four — easy to generalize.
+
+Every example follows the same rhythm: **install → first generation → config tweaks → what to do after an official upgrade → output reforge**.
+
+## Example 1: daily-report (representative of the report family)
+
+1. **Install**: `skill-forge init --skills daily-report`
+2. **First generation**: just say "write a daily report", describe what you did today (or hand it a paragraph / a file / an image) → produces `daily-report-YYYYMMDD.md` + `.txt` + `.html` (auto-opened), plus a full-page content-png capture
+3. **Config tweaks**: ask the AI to open the skill's `user-config.md` and change `DIR` (save directory), `THEME` (tech/biz/mono/light/warm five themes), `TEMPLATE: custom` for a custom template; ad-hoc verbal requests ("only 3 items today") apply once and never touch config
+4. **After an official upgrade**: `npm update -g skill-forge-hub` (upgrade the CLI itself) → `skill-forge update` (upgrade the skills) → if the official config structure changed, it backs up first then offers a three-way choice; pick `[2] keep mine`, then compare `user-config.md.upstream` and merge new config points manually (e.g. a new DATA_SOURCES list)
+5. **Output reforge**: when the official template stamp bumped (`sf-template@N`) → the next generation says "found X old daily reports" → say "upgrade all my old daily reports to the new style" → pick all or some → shallow upgrade (style changes) swaps style blocks, deep upgrade (structure changes) rebuilds from the sibling md draft, old version backed up first
+
+## Example 2: prompt-pouch (local console + user data)
+
+1. **Install**: `skill-forge init --skills prompt-pouch`
+2. **First generation**: "make me a prompt management page" → produces the console html + `data/prompts.json`
+3. **Everyday use**: group sidebar / search / favorites / tag click filtering / `{variable}` interpolation one-click copy / JSON import & export / group emoji quick panel; data lives in `data/prompts.json` with rolling backups in `backup/` — page and data are separated, deleting the page never loses data
+4. **Config tweaks**: in `user-config.md`, change `DIR` (page directory), `DATA_DIR` / `BACKUP_DIR` (data & backup directories)
+5. **After an official upgrade**: the data directory and data files are never touched; a deep rebuild keeps the page's original pouch-id → existing favorites / groups read back unchanged
+6. **Page-version upgrade (reforge)**: when the official template bumps (version stamp sf-template@N +1), the next "make a prompt management page" run has the AI proactively say "skill template upgraded to vN, found X old pouches" — say "upgrade all my old pouches to the new style" → the AI lists them (file / old version / has user data) → pick all or some → upgrade one by one: style-only changes swap the style block and scripts (shallow), structural changes rebuild from the template but keep the original pouch-id (deep — favorites and groups read back unchanged); prompts.json is never touched and the old page is backed up as .bak-<timestamp> first → three-part report (✅ upgraded / ⚠️ hand-edits kept / 🟡 failure reasons); pure wording polish does not bump the stamp — no reforge needed
+7. **Multi-file isolation**: two pouches stay independent (embedded-ID namespacing, no cross-talk); copying a file = same identity sharing the same data (for an independent identity, generate a new one — don't copy a file to fake a new output)
+
+## Example 3: magic-deck + deck-stage (both PPT forms)
+
+1. **Intent routing**: saying "make a PPT" prompts the AI to ask the form first — HTML slides (magic-deck) or an editable .pptx (deck-stage)
+2. **magic-deck**: produces a single-file HTML slide deck → open in the browser for fullscreen playback (autoplay / loop / hotkey paging) → per-page PNG captures when images are needed
+3. **deck-stage**: three-question interaction (materials → page skeleton table → build method) → produces a .pptx: regular pages natively editable (data cards / timelines / charts), cover & closing pages captured losslessly from HTML
+4. **Dependency**: deck-stage needs PptxGenJS — the npm package excludes node_modules, so after install run `cd <skill dir>/deck-stage && npm install` once as prompted
+5. **Config**: the five themes (tech/biz/mono/light/warm), page size, speaker-notes switch etc. all live in `user-config.md`
+
+## Example 4: meeting-minutes (source of the reporting chain)
+
+1. **Install**: `skill-forge init --skills meeting-minutes`
+2. **First generation**: "take meeting minutes" → describe the meeting materials → five-section minutes (meeting info / conclusions / agenda discussion / resolutions & action items / next meeting), action items with owners and deadlines — these action items are the source of the chain that daily / weekly / monthly / quarterly reports cite
+3. **Series grouping**: `SERIES_GROUP` three states — `auto` extracts series names into `meetings/{series}/`, `series` always uses series directories, `off` flat month directories; rename mechanism: "always call this series XX" persists
+4. **After an official upgrade**: same as the report family — three-way config protection + minutes reforge (say "upgrade my old minutes to the new style")
+
+## Cheat Sheet
+
+| Need | Do |
+|:---|:---|
+| Change save dir / theme / template | Edit `user-config.md` (never overwritten on upgrade) |
+| Official release is out | first `npm update -g skill-forge-hub` (the CLI itself), then `skill-forge update`; on config conflict pick `[2] keep mine` |
+| Restyle old outputs | Say "upgrade all my old XX to the new style" |
+| A skill is missing | `skill-forge init --skills <skill-name>` |
+| See all commands | `skill-forge --help` |

package/docs/usage-examples.md

@@ -0,0 +1,50 @@
+# 技能使用示例
+
+[English](usage-examples.en.md)
+
+> 从安装到日常使用的完整链路示例。挑选四个代表性技能：日报（报表族代表，覆盖配置修改与旧产物回炉）、锦囊（本地管理台，覆盖用户数据与多文件隔离）、魔法幻灯与登台（PPT 两种形态，覆盖意图分流与依赖补装）、会议纪要（汇报链源头，覆盖系列分组）。其余技能形态与这四个同构，可举一反三。
+
+每个示例按同一节奏展开：**安装 → 首次生成 → 修改配置 → 官方升级后的操作 → 旧产物升级（回炉）**。
+
+## 示例一：daily-report 日报（报表族代表）
+
+1. **安装**：`skill-forge init --skills daily-report`
+2. **首次生成**：直接说「写日报」，口述今天干了什么（或丢一段文字 / 一个文件 / 一张图）→ 生成 `daily-report-YYYYMMDD.md` + `.txt` + `.html`（自动打开），附整页截图 content-png
+3. **修改配置**：让 AI 打开技能目录的 `user-config.md`，改 `DIR`（落盘目录）、`THEME`（tech/biz/mono/light/warm 五主题）、`TEMPLATE: custom` 换自定义模板；临时口头要求（如「今天只写 3 条」）当次生效、不写配置
+4. **官方升级后**：`npm update -g skill-forge-hub`（升级 CLI 本体）→ `skill-forge update`（升级技能）→ 若官方配置结构变了，先自动备份再交互三选一，选 `[2] 保留我的`，然后对照 `user-config.md.upstream` 手动合并新配置点（如新增的 DATA_SOURCES 数据源清单）
+5. **旧产物回炉**：官方模板版本戳升了（`sf-template@N`）→ 下次生成时提示「检测到 X 份旧版日报」→ 说「把我旧日报都升级成新样式」→ 选全部或部分 → 浅升级（样式变化）替换样式块、深升级（结构变化）从同目录 md 底稿重建，旧版先备份
+
+## 示例二：prompt-pouch 锦囊（本地管理台 + 用户数据）
+
+1. **安装**：`skill-forge init --skills prompt-pouch`
+2. **首次生成**：「做一个锦囊管理页面」→ 生成锦囊管理台 html + `data/prompts.json` 数据文件
+3. **日常使用**：分组侧栏 / 搜索 / 收藏 / 标签点击过滤 / `{变量}` 插值一键复制 / 导入导出 JSON 备份 / 分组 emoji 快捷面板；数据存 `data/prompts.json`、滚动备份在 `backup/`——页面与数据分离，删页面不丢数据
+4. **修改配置**：`user-config.md` 改 `DIR`（页面目录）、`DATA_DIR` / `BACKUP_DIR`（数据与备份目录）
+5. **官方升级后**：数据目录与数据文件一概不动；深升级重建沿用原页 pouch-id → 原有收藏 / 分组照旧读回
+6. **页面版本升级（回炉）**：官方模板升级（版本戳 sf-template@N +1）后，下次「做一个锦囊管理页面」时 AI 主动提示「技能模板已升级至 vN，检测到 X 份旧版锦囊」——说「把我旧锦囊都升级成新样式」→ AI 列清单（文件 / 旧版本 / 有无用户数据）→ 选全部或部分 → 逐份升级：样式类变化替换 style 块与脚本（浅升级）、结构类变化从模板重建但沿用原页 pouch-id（深升级，收藏分组照旧读回），prompts.json 数据一概不动、旧页先备份 .bak-时间戳 → 报告三段式（✅ 已升级 / ⚠️ 手改保留 / 🟡 失败原因）；纯措辞润色不升版本戳，无需回炉
+7. **多文件隔离**：两份锦囊各自独立（内嵌 ID 命名空间，互不串台）；复制文件副本 = 同一身份共享同一份数据（要独立身份请重新生成一份，勿复制文件冒充新产物）
+
+## 示例三：magic-deck + deck-stage（PPT 两种形态）
+
+1. **意图分流**：说「做个 PPT」时，AI 会先问形态——HTML 幻灯（magic-deck）还是 .pptx 可编辑文稿（deck-stage）
+2. **magic-deck**：生成单文件 HTML 幻灯 → 浏览器打开全屏放映（自动播放 / 循环 / 热键翻页）→ 需要图片时逐页 PNG 截图
+3. **deck-stage**：三问交互（素材 → 页骨架表 → 成片方式）→ 生成 .pptx：常规页原生可编辑（数据卡 / 时间线 / 图表），封面与结尾页 HTML 截图保真
+4. **依赖补装**：deck-stage 依赖 PptxGenJS——npm 包不含 node_modules，装完按提示 `cd <技能目录>/deck-stage && npm install` 补装一次
+5. **配置**：五主题（tech/biz/mono/light/warm）、页面尺寸、演讲备注开关等均在 `user-config.md`
+
+## 示例四：meeting-minutes 会议纪要（汇报链源头）
+
+1. **安装**：`skill-forge init --skills meeting-minutes`
+2. **首次生成**：「记会议」→ 口述会议材料 → 五段式纪要（会议信息 / 会议结论 / 议题讨论 / 决议与行动项 / 下次会议），行动项带负责人与截止时间——这份行动项就是后续日报 / 周报 / 月报 / 季报的汇报链源头
+3. **系列分组**：`SERIES_GROUP` 三态——`auto` 自动提取系列名归入 `meetings/{系列名}/`、`series` 一律按系列建目录、`off` 纯月份平铺；改口机制：「以后这个系列叫 XX」永久生效
+4. **官方升级后**：同报表族——配置三选一保护 + 旧纪要回炉（说「把旧纪要升级成新样式」）
+
+## 通用小抄
+
+| 需求 | 做法 |
+|:---|:---|
+| 换落盘目录 / 主题 / 模板 | 改 `user-config.md`（升级永不覆盖） |
+| 官方发新版 | 先 `npm update -g skill-forge-hub`（CLI 本体）再 `skill-forge update`，配置冲突选 `[2] 保留我的` |
+| 旧产物换新样式 | 说「把我旧 XX 都升级成新样式」 |
+| 装漏技能 | `skill-forge init --skills 技能名` |
+| 看全部命令 | `skill-forge --help` |

package/magic-deck/SKILL.md

@@ -25,7 +25,7 @@ disable-model-invocation: false
    - Playwright headless 自检（缺则 `pip3 install --user playwright`；用系统 Chrome，无需 playwright install 下载浏览器）：`p.chromium.launch(channel="chrome", headless=True)` → goto 页面 → 挂 pageerror 监听（零容忍）→ 按页数循环 `go(i)` 把每一页翻完
    - 截首 / 中 / 末三页 PNG，Read 自查：版式正常、文字无溢出截断、图表数据到位、无豆腐块缺字
    - 任何报错或视觉问题：修 HTML → 重检；全绿才进第 3 步
-3. **落盘与命名**：自检通过后在 DIR 下新建 `{文件名}/` 子目录（`mkdir -p`，总目录统一管理、各次产出自包含互不干扰），`cp` 到该子目录，自动打开浏览器供用户放映。命名三级优先：①用户口头指定文件名 → 用指定名；②未指定且 FILENAME=auto → 按本次内容主题+用途总结中文名（如「智能探针系统-产品介绍」，让用户日后能按名找回继续改）；③FILENAME 写死固定名 → 用固定名。重名一律自动加日期后缀，绝不覆盖；落盘目录复用不清空、不改动目录内既有文件
+3. **落盘与命名**：自检通过后在 DIR 下新建 `{文件名}/` 子目录（`mkdir -p`，总目录统一管理、各次产出自包含互不干扰），`cp` 到该子目录，自动打开浏览器供用户放映。命名三级优先：①用户口头指定文件名 → 用指定名；②未指定且 FILENAME=auto → 按本次内容主题+用途总结中文名（如「智能探针系统-产品介绍」，让用户日后能按名找回继续改）；③FILENAME 写死固定名 → 用固定名。重名一律自动加日期后缀，绝不覆盖；落盘目录复用不清空、不改动目录内既有文件；落盘完成后对话回复必须向用户报告落盘位置：完整路径（DIR/{文件名}/ 子目录）与文件清单（html 与预览截图），并注明浏览器是否已自动打开
 4. **使用咨询**（用户只问「怎么用 / 使用说明 / 能干什么」等用法、未要求生成）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「魔法幻灯生成器使用指南」），不生成 HTML
 
 
@@ -84,3 +84,13 @@ disable-model-invocation: false
 - 修改本 skill 任何文件后，必须 grep 全文核对：新词已命中、旧词零残留（改一处查一处）
 - 修改 HTML 效果必须双处同步：`resources/reference.html` 与 `resources/deck-spec.md` 对应描述同时更新，禁止只改一处
 - 修改配置键必须三处同步：user-config.md 的 yaml、SKILL.md 配置键清单、deck-spec.md 对应规则
+
+
+---
+
+## 🔍 SkillForge 使用指引（整体咨询时触发）
+
+当用户询问 **SkillForge 本身**（不是单个技能用法）——「skillforge 怎么用 / 使用说明 / 使用指引 / 是什么」「技能怎么安装 / 怎么升级 / 装了哪些技能 / 技能清单」「skill-forge ls / init / update 等命令怎么用」「技能安装器 / 技能锻造坊」等（中英文、近似说法均可，关键词可自由扩展）：
+1. Read 同目录 `resources/skillforge-guide.txt` 全文，按其内容整理回答（命令与参数以 txt 为准，勿自行编造）
+2. 用系统命令打开同目录 `resources/skillforge-guide.html`（macOS `open`，Windows `start`），让用户在浏览器看排版版
+3. 用户只问单个技能怎么用时（如「日报怎么用」）不触发本指引，走本技能的使用说明

package/magic-deck/resources/deck-spec.md

@@ -6,7 +6,7 @@
 
 ## 0. 铁律
 
-- **单文件零依赖**：禁用 CDN/@import/外链 CSS/JS/图片/网络字体，双击离线可打开；字体用系统栈 `ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,'Microsoft YaHei',monospace`
+- **单文件零依赖**：禁用 CDN/@import/外链 CSS/JS/图片/网络字体，双击离线可打开；字体用系统栈 `ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,monospace`
 - **舞台 1280×720（16:9）**，按窗口等比缩放（--sc），窗口任意大小不变形
 - **截图与复制只含主体**：截图克隆当前 slide、复制取 slide innerText，绝不包含工具栏/页码/箭头/提示等操作元素
 - **全屏纯净**：`:root:fullscreen` 下所有操作元素与背景氛围层（.bg-glow/.bg-grid）全部隐藏、页面底色纯黑 `#000`，只留舞台主体（与 PPT 软件放映一致：幻灯按比例充满画面，比例不匹配处补黑边，绝无主题氛围边框/光斑/网格）

package/magic-deck/resources/reference.html

@@ -10,7 +10,7 @@
 /* ══════════ 0. 基础 ══════════ */
 *{ margin:0; padding:0; box-sizing:border-box; }
 html,body{ width:100%; height:100%; overflow:hidden;
-  font-family:ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,'Microsoft YaHei',monospace; }
+  font-family:ui-monospace,'SF Mono',SFMono-Regular,Menlo,Consolas,monospace; }
 button,select,input{ font-family:inherit; }
 /* ══════════ 1. 十六主题 CSS 变量（12 令牌 × 16 主题，默认 tech） ══════════ */
 :root, [data-theme="tech"]{