npm - skill-forge-hub - Versions diffs - 1.0.5 → 1.0.7 - Mend

skill-forge-hub 1.0.5 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/CHANGELOG.en.md +194 -0
package/CHANGELOG.md +20 -0
package/README.en.md +99 -0
package/README.md +53 -59
package/docs/architecture.en.md +95 -0
package/docs/architecture.md +70 -64
package/docs/install.en.md +69 -0
package/docs/install.md +32 -34
package/meta-forge/SKILL.md +5 -5
package/meta-forge/resources/forge-rules.md +8 -0
package/meta-forge/resources/usage-guide.md +7 -6
package/meta-forge/user-config.md +2 -1
package/package.json +4 -2
package/template/SKILL.md +18 -14
package/template/resources/README.md +1 -1
package/template/resources/usage-guide.md +17 -0
package/template/user-config.md +28 -0

package/docs/architecture.en.md ADDED Viewed

@@ -0,0 +1,95 @@
+# 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 / 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)
+│   └── 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 CHANGED Viewed

@@ -1,89 +1,95 @@
-# 架构与规范 · 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）
+│   └── 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 ADDED Viewed

@@ -0,0 +1,69 @@
+# 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
+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`.
+## 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).

package/docs/install.md CHANGED Viewed

@@ -1,29 +1,29 @@
-# 安装与升级 · 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 助手技能目录
+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 +33,37 @@ 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`。Command aliases: `list` = `ls`, `install` = `init`, `upgrade` = `update`.
+命令别名：`list` = `ls`、`install` = `init`、`upgrade` = `update`。
-## 升级与配置保护 · 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/meta-forge/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: meta-forge
-description: 锻造新技能的元技能（造 skill 的 skill）。按 SkillForge 工坊规范从需求出发生成完整技能包（薄入口 SKILL.md + 按阶段拆分的 resources/ + 用户配置 user-config.md），自动植入机制体系：CONFIG_VERSION 配置版本钥匙、user-config 配置抽离、reference 双轨（含 HTML 输出时）、多文件隔离（页面有 localStorage 记忆时）、零侵权脱敏离线纪律（含 HTML 输出时）、产物升级回炉（含 HTML 输出时）、文档同步自检纪律；技能入 SkillForge 仓库时同步登记 README 分类表与 cli.js CATEGORIES。当用户请求创建新技能、造一个 skill、做一个 XX 技能、把 XX 流程固化成技能，或询问 meta-forge 用法（怎么造技能/元锻炉怎么用）时使用。
+description: 锻造新技能的元技能（造 skill 的 skill）。按 SkillForge 工坊规范从需求出发生成完整技能包（薄入口 SKILL.md + 按阶段拆分的 resources/ + 用户配置 user-config.md），自动植入机制体系：CONFIG_VERSION 配置版本钥匙、user-config 配置抽离、reference 双轨（含 HTML 输出时）、多文件隔离（页面有 localStorage 记忆时）、零侵权脱敏离线纪律（含 HTML 输出时）、产物升级回炉（含 HTML 输出时）、preserve 保护清单（含半定制资产时）、文档同步自检纪律；技能入 SkillForge 仓库时同步登记 README 分类表、cli.js CATEGORIES 与 package.json files。当用户请求创建新技能、造一个 skill、做一个 XX 技能、把 XX 流程固化成技能，或询问 meta-forge 用法（怎么造技能/元锻炉怎么用）时使用。
 allowed-tools: Bash, Read, Write
 disable-model-invocation: false
 ---
@@ -14,9 +14,9 @@ disable-model-invocation: false
 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 双轨 / 多文件隔离 / 零侵权脱敏离线 / 产物升级回炉 / 自检纪律，缺一不可；含 HTML 输出加机制六、七、八）→ 读 `resources/forge-rules.md` 的「三、机制体系」
-4. **验证环**（静态门禁 grep 逐项 + 含 HTML 时 Playwright 运行时实测：零 JS 错误 / 键带路径 / 刷新恢复 / 多文件隔离 + 交付报告附验证证据，任一未过修复重跑禁止跳过）→ 读 `resources/forge-rules.md` 的「四、验证环」
-5. **仓库登记**（技能入 SkillForge 仓库时：README 技能分类表/技能清单/目录结构 + cli.js CATEGORIES 同步登记，登记后跑 `skill-forge ls` 验证）→ 读 `resources/forge-rules.md` 的「五、仓库登记」
+3. **机制植入**（CONFIG_VERSION 钥匙 / user-config 抽离 / reference 双轨 / 多文件隔离 / 零侵权脱敏离线 / 产物升级回炉 / preserve 保护清单 / 自检纪律，缺一不可；含 HTML 输出加机制三、七、八，页面有 localStorage 记忆加机制六，含半定制资产加机制五）→ 读 `resources/forge-rules.md` 的「三、机制体系」
+4. **验证环**（静态门禁 grep 逐项 + 含 HTML 时 Playwright 运行时实测：零 JS 错误 / 键带路径 / 刷新恢复 / 多文件隔离 / 自愈实测 + 交付报告附验证证据，任一未过修复重跑禁止跳过）→ 读 `resources/forge-rules.md` 的「四、验证环」
+5. **仓库登记**（技能入 SkillForge 仓库时：README 技能分类表/技能清单/目录结构 + cli.js CATEGORIES + package.json files 同步登记，登记后跑 `skill-forge ls` 与 `npm pack --dry-run` 验证）→ 读 `resources/forge-rules.md` 的「五、仓库登记」
 6. **使用咨询**（用户只问「怎么造技能」等用法、未要求创建）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「元锻炉使用指南」），不创建任何文件
 ## ⚙️ 配置与自定义
@@ -42,7 +42,7 @@ disable-model-invocation: false
 ## 规则速览
-- 机制体系缺一不可：CONFIG_VERSION 钥匙（配置版本机制节 + user-config 配置块首行 CONFIG_VERSION: 1）、user-config 抽离（用户可改配置全部出站，SKILL.md 只引用不内嵌）、reference 双轨（含 HTML 输出的技能以 reference.html 为样式真相源）、多文件隔离（页面有 localStorage 记忆时键带路径命名空间）、零侵权脱敏离线（品牌字体零出现、禁 CDN 离线可开、示例数据零真实身份）、产物升级回炉（HTML 带模板版本戳、业务/数据格式/页面改动均 bump、旧产物可交互回炉、生成时顺扫旧版主动提示）、自检纪律（改一处 grep 全仓）
+- 机制体系缺一不可：CONFIG_VERSION 钥匙（配置版本机制节 + user-config 配置块首行 CONFIG_VERSION: 1）、user-config 抽离（用户可改配置全部出站，SKILL.md 只引用不内嵌）、reference 双轨（含 HTML 输出的技能以 reference.html 为样式真相源）、多文件隔离（页面有 localStorage 记忆时键带路径命名空间）、零侵权脱敏离线（品牌字体零出现、禁 CDN 离线可开、示例数据零真实身份）、产物升级回炉（HTML 带模板版本戳、业务/数据格式/页面改动均 bump、旧产物可交互回炉、生成时顺扫旧版主动提示）、preserve 保护清单（半定制资产 .preserve 声明、CLI 升级永不覆盖、官方更新另存 .upstream 对照）、自检纪律（改一处 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 CHANGED Viewed

@@ -52,6 +52,7 @@
 - 生成 HTML 必须先 Read reference.html 与样式文档两份，以 reference.html 为骨架模板逐处替换数据
 - 修改 HTML 效果必须同步更新 reference.html + 样式文档描述，禁止只改一处；改完互相 grep 关键参数确认对齐
 - 铁律写入样式文档首段：「Reference 铁律（最高优先）」
+- 入场动画兜底：reference.html 含滚动入场动画（IntersectionObserver + JS 门控初始隐藏）时，脚本必须带 2s 兜底 setTimeout 强制全显（`.rv:not(.in)` 模式或等价代码）——IO 不触发的环境（headless 截图 / 打印预览 / PDF 导出 / 嵌入式 webview）卡片不得永久隐藏
 ### 机制四：文档同步自检纪律
@@ -73,6 +74,7 @@
 - **绝对禁止「固定键最近快照兜底」双键模式**：固定键在 file:// 同源下全局共享，A 写快照 B 兜底读到 → 必然串台（真实教训：prompt-pouch 曾因此 B 份继承 A 份分组/收藏，报障后改内嵌 ID）
 - 旧版数据迁移桥：新 ID 键读不到时一次性读旧版路径键（`旧前缀:路径-键`）迁入 ID 键；旧固定键/旧固定库数据归属不明，禁止迁入
 - 命名空间变量声明位置 = 所有使用它的代码块的**公共作用域**：页面含多个独立 `<script>`/IIFE 时，每个作用域各自声明（IIFE 内的 var 是局部变量，IIFE 外够不到；引用不可见会 ReferenceError、被 catch 静默吞掉 → 机制静默失效）
+- 页面执行层自愈：HTML 内嵌 JS 启动时校验 id meta——非法或缺失（占位残留 / 手写变体 / 误沿用旧值）时按路径键（`'sf-heal:' + location.pathname`）自愈为 crypto.randomUUID() 标准 v4 并回写 meta，console.warn 显性报警；路径键持久化保证同文件跨打开稳定复用（避免每次打开换新键丢记忆）；合法 UUID 原样放行（复制文件副本 = 同一身份共享数据，是特性）
 ### 机制七：零侵权、脱敏与离线纪律（HTML 产出技能必植入）
@@ -86,6 +88,7 @@
 - 产物版本戳：生成 HTML 时头部写 `<meta name="sf-template" content="<技能名>@N">`（N 为模板版本，初版 1）；模板升级时递增 N 并同步 reference.html 与 SKILL.md「产物升级（回炉）」节；检测双标记：版本戳 + 稳定 ID meta——无版本戳或缺少 `<前缀>-id` meta 的产物一律视为 v0 最旧版，必须进升级清单
 - 数据真相源：md/txt 与 html 同落盘，md 全文为内容底稿，html 永远可从 md 重建
 - 两级升级：浅升级（CSS/JS 变化、DOM 结构不变）→ 对旧页替换 <style> 块与交互脚本、正文原样保留；深升级（DOM 结构变化）→ 从同目录 md 底稿重生成，先备份旧版 .bak-时间戳
+- 用户数据类细则（IndexedDB 数据按稳定 ID 命名空间存取的技能）：深升级重建必须沿用原页稳定 ID meta 值（换 ID = 数据失联，重建后原收藏/分组照旧读回）；<DATA_DIR> 数据文件一概不动
 - 回炉交互：用户说「升级旧产物/回炉」→ 扫落盘目录读版本戳筛旧版（无版本戳或缺少稳定 ID meta 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态：旧 html 正文与 md 正文对比，不一致视为可能手改）→ AskUserQuestion 选全部或部分 → 逐份升级 → 报告三段式（✅ 已升级 / ⚠️ 手改保留 / 🟡 失败项原因）
 - 版本递增判定：模板业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与 SKILL.md「产物升级（回炉）」节；纯措辞润色不 bump
 - 主动提示：每次生成 HTML 或用户使用该技能 HTML 产出时，顺扫落盘目录读版本戳；发现低于当前模板版本的旧产物，主动告知「技能模板已升级至 vN，检测到 X 份旧版产物（vN-1），说『把我旧XX都升级成新样式』即可一键升级」，不让用户背触发语
@@ -106,12 +109,16 @@
 10. 示例数据脱敏：全文 grep 无真实项目名/人名/公司名/平台名/本机路径（/Users/具体用户名、~/SmartDeveloper 等）；页脚署名 GENERATED BY AI TEAM
 11. 产物版本戳（含 HTML 的技能）：reference.html 头部含 `<meta name="sf-template" content="<技能名>@N">`（N≥1）；SKILL.md 含「产物升级（回炉）」节且判定含无版本戳/无稳定 ID meta 视为 v0 最旧版
 12. 版本递增与主动提示（含 HTML 的技能）：SKILL.md 回炉节含版本递增判定（业务/数据格式/页面改动均 bump）与主动提示语（顺扫旧产物 + 告知触发语）
+13. 入场动画兜底（含 HTML 且含滚动入场动画的技能）：reference.html 含 2s 兜底强制全显代码（`.rv:not(.in)` 模式或等价），确保 headless 截图 / 打印预览内容全显
+14. 执行层自愈块（含 HTML 且页面有 localStorage 记忆的技能）：HTML 内嵌 JS 含 id meta 校验——非法或缺失（占位残留 / 手写变体 / 误沿用旧值）时按路径键（`sf-heal:` + location.pathname）自愈为 crypto.randomUUID() 标准 v4 并回写 meta，console.warn 显性报警
 ### B. 运行时实测（含 HTML 的技能必做，Playwright headless channel="chrome"）
 1. 页面加载零 JS 错误（pageerror 监听 + 控制台检查）
 2. 关键交互实测：主题/状态切换 → localStorage 键带路径 → 刷新恢复
 3. 多文件隔离实测：复制 HTML 到第二路径（用户数据类改成换 ID）→ 两份各自读写键互不干扰；用户数据类加测：同 ID 文件移动到新目录 → 数据保留
+4. 截图验证：headless 全页截图内容完整（标题 / 关键卡片 / 区块可见），入场动画兜底后内容全显；截图空白即失败（真实教训：入场动画无兜底 → headless 截图空白）
+5. 自愈实测（页面有 localStorage 记忆的技能）：把 id meta 改坏（占位值或删除）→ 重新打开页面 → meta 自愈为合法 v4 + console.warn 报警 + localStorage 记忆经路径键恢复（不丢）
 ### C. 验证证据（交付报告必附）
@@ -125,3 +132,4 @@
 3. cli.js 的 CATEGORIES 数组：同步登记（name/en/skills），与 README 分类表一致
 4. README「目录结构」图：按需补新技能目录
 5. 登记后跑 `skill-forge ls` 验证技能出现在正确分类下
+6. package.json 的 files 数组：补技能目录名——npm 包内容遗漏教训（1.0.5 曾漏 monthly-report/meeting-minutes/quarterly-report 三技能，装包却无技能）；登记后跑 `npm pack --dry-run` 验证新技能目录出现在包内容清单中

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

@@ -10,12 +10,13 @@ meta-forge 是「造 skill 的 skill」：把一段重复劳作，按 SkillForge
   1. CONFIG_VERSION 钥匙——配置结构带版本号，升级时自动备份迁移，不丢用户设置
   2. user-config 抽离——用户可改配置全部出站到 user-config.md，升级永不覆盖
   3. reference 双轨——技能含 HTML 输出时，reference.html 是定稿样式真相源，改样式三处同步
-  4. 多文件隔离——页面有 localStorage 记忆时，键按页内嵌唯一 ID 命名空间，多份产物互不串台、改名/移动目录记忆不丢
-  5. 零侵权脱敏离线——品牌字体零出现、禁 CDN 页面离线可开、示例数据零真实身份（通用占位）
-  6. 自检纪律——改任一文件 grep 全仓核对关键词，旧词零残留
-  7. 产物升级回炉——HTML 带模板版本戳（业务/数据格式/页面改动均 bump），升级后可扫旧产物交互式回炉（浅升级区块替换/深升级 md 重建），生成时顺扫旧版主动提示触发语
-- 交付前跑验证环（偏差必被发现）：静态门禁逐项 grep + 含 HTML 时 Playwright 实测（零 JS 错误 / 键带路径 / 刷新恢复 / 多文件隔离），验证证据随交付报告附上
-- 技能入 SkillForge 仓库时，自动登记 README 技能分类表/技能清单/目录结构与 cli.js CATEGORIES
+  4. 自检纪律——改任一文件 grep 全仓核对关键词，旧词零残留
+  5. preserve 保护清单——含半定制资产（设计系统/模板底稿）时 .preserve 声明，CLI 升级永不覆盖，官方更新另存 .upstream 对照
+  6. 多文件隔离——页面有 localStorage 记忆时，键按页内嵌唯一 ID（标准 UUID v4）命名空间，多份产物互不串台、改名/移动目录记忆不丢
+  7. 零侵权脱敏离线——品牌字体零出现、禁 CDN 页面离线可开、示例数据零真实身份（通用占位）
+  8. 产物升级回炉——HTML 带模板版本戳（业务/数据格式/页面改动均 bump），升级后可扫旧产物交互式回炉（浅升级区块替换/深升级 md 重建），生成时顺扫旧版主动提示触发语
+- 交付前跑验证环（偏差必被发现）：静态门禁逐项 grep + 含 HTML 时 Playwright 实测（零 JS 错误 / 键带路径 / 刷新恢复 / 多文件隔离 / 自愈实测），验证证据随交付报告附上
+- 技能入 SkillForge 仓库时，自动登记 README 技能分类表/技能清单/目录结构、cli.js CATEGORIES 与 package.json files（npm 包不遗漏技能）
 ## 怎么用

package/meta-forge/user-config.md CHANGED Viewed

@@ -9,7 +9,8 @@
 ## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
 ```yaml
-CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）DIR: auto                      # 新技能生成目录：auto = 探测 SkillForge 仓库根（~/SkillForge 或含 cli.js 的当前目录）；也可写死绝对路径
+CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+DIR: auto                      # 新技能生成目录：auto = 探测 SkillForge 仓库根（~/SkillForge 或含 cli.js 的当前目录）；也可写死绝对路径
 REGISTER: true                 # 仓库登记：true = 生成后自动更新 README 技能分类表/技能清单与 cli.js CATEGORIES；false = 只生成技能包不登记
 ```

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "skill-forge-hub",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "SkillForge (技能锻造坊) — a curated collection of AI craft skills. Install once, then pick skills interactively: daily/weekly/monthly/quarterly/annual reports, meeting minutes, article-to-HTML, magic-deck slides, deck-stage PPTX, prompt-pouch manager, Pandoc doc converters, meta-forge.",
   "bin": {
     "skill-forge": "cli.js"
@@ -24,7 +24,9 @@
     "docs",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "README.en.md",
+    "CHANGELOG.en.md"
   ],
   "keywords": [
     "skillforge",