skill-forge-hub 1.0.5 → 1.0.7

package/template/SKILL.md

@@ -11,31 +11,35 @@ disable-model-invocation: false
 
 ## 生成流程
 
+0. **读用户配置**（<配置项列表，如 DISK/DIR/TEMPLATE>）→ 先 Read 同目录 `user-config.md`
 1. **阶段一（做什么）** → 读 `resources/xxx.md`
 2. **阶段二（做什么）** → 读 `resources/yyy.md`
 3. **阶段三（做什么）** → 读 `resources/zzz.md`
-3.5 **交付前自检**（落盘前必做，硬门禁不可跳过）：<按技能类型写自检手段——页面类 用 Playwright headless 零报错（channel="chrome"）+ localStorage 键路径命名空间 核验（固定键零残留）+ 多文件隔离实测（复制 HTML 到第二路径互不干扰）+ 品牌字体 零侵权扫描（PingFang/YaHei/apple-system 等零出现）+ 示例数据脱敏核验（真实项目名/人名/公司名/本机路径零出现，署名 GENERATED BY AI TEAM）+ 产物版本戳核验（`<meta name="sf-template" content="<skill>@N">` 已写入且 N 与当前模板版本一致；业务/数据格式/页面改动必 bump 版本）；文档类检查结构与数据纪律； 产物类校验文件完整性与内容一致>——未通过修复后重跑，禁止跳过直接交付
+3.5 **交付前自检**（落盘前必做，硬门禁不可跳过）：<按技能类型写自检手段——页面类用 Playwright headless 零报错（channel="chrome"）+ localStorage 键路径命名空间核验（固定键零残留）+ 多文件隔离实测（复制 HTML 到第二路径互不干扰）+ 品牌字体零侵权扫描（PingFang/YaHei/apple-system 等零出现）+ 示例数据脱敏核验（真实项目名/人名/公司名/本机路径零出现，署名 GENERATED BY AI TEAM）+ 产物版本戳核验（`<meta name="sf-template" content="<skill>@N">` 已写入且 N 与当前模板版本一致；业务/数据格式/页面改动必 bump 版本）；文档类检查结构与数据纪律；产物类校验文件完整性与内容一致>——未通过修复后重跑，禁止跳过直接交付
 4. **使用咨询**（用户只问用法、未要求生成）→ 读 `resources/usage-guide.md` 原样输出（首行标题改为「XX使用指南」），不执行任何生成动作
 
-## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+## ⚙️ 配置与自定义
 
-```yaml
-DISK: true      # 示例配置项：是否落盘写文件；false = 默认只在对话输出
-DIR: auto       # 示例配置项：落盘根目录
-```
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（<配置项列表>）与自定义模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
 
-> 临时口头要求（仅对当次生效，不修改上方配置）：说「xxx」→ 当次改某行为；……
+## 配置版本机制（升级保护）
 
-## 📝 自定义模板（TEMPLATE: custom 时启用，用户可手改）
+本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
-把顶部 TEMPLATE 改为 custom 后，按下面结构生成（段名、段数、条目格式均可改）：
+1. 先将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`（同目录，绝不删除旧值）
+2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
+3. 更新 CONFIG_VERSION 为当前版本
+4. 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」
 
-```text
-段一：……（每条：……）
-段二：……（每条：……）
-```
+升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
 
-> 只写段结构与条目格式即可；未写明的细节沿用默认规范。
+## 产物升级（回炉）——仅含 HTML 输出的技能保留本节，否则删除
+
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="<skill>@1">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧XX换新样式」时：扫落盘目录读版本戳筛出旧版（无版本戳或缺少稳定 ID meta 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/手改状态）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建且**沿用原页稳定 ID meta 值**（用户数据类换 ID = 数据失联），先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版产物，说『把我旧XX都升级成新样式』即可一键升级」，不让用户背触发语。
+
+## 文档同步自检纪律（维护者必读）
+
+修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如机制名/流程节点/字段名改名时新旧词全仓核对，旧词零残留才算完成）。
 
 ## 规则速览
 

package/template/resources/README.md

@@ -16,5 +16,5 @@
 约定：
 
 - 每份 resource 独立可读，不互相引用（避免读取链断裂）
-- 用户可手改的配置（默认配置 / 自定义模板）必须留在 SKILL.md，不进 resources
+- 用户可手改的配置（默认配置 / 自定义模板）全部进 user-config.md，SKILL.md 只在第 0 步引用，不内嵌配置值
 - resource 内标题用原章节标题，内容从旧版单文件 SKILL.md 原样迁移

package/template/resources/usage-guide.md

@@ -0,0 +1,17 @@
+# <技能名>使用指南
+
+<一句话介绍：做什么、一句话触发示例>
+
+## 能干什么
+
+- <能力 1>
+- <能力 2>
+
+## 怎么用
+
+- 「<触发语 1>」→ <产出 1>
+- 「<触发语 2>」→ <产出 2>
+
+## 常见问题
+
+- <高频问题>：<答案>

package/template/user-config.md

@@ -0,0 +1,28 @@
+# 用户配置（升级技能时本文件不会被覆盖）
+
+> 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
+> 本文件始终保留你的版本——落盘目录、格式开关放心改。
+> 官方升级若带来新配置点，会另存 `user-config.md.upstream` 对照文件到同目录，
+> 你按需查看并手动合并新配置点到本文件。
+
+## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+
+```yaml
+CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+DISK: true                     # 示例配置项：是否落盘写文件；false = 默认只在对话输出
+DIR: auto                      # 示例配置项：落盘根目录
+TEMPLATE: default              # 示例配置项：模板开关（default 默认模板 / custom 自定义模板）
+```
+
+> 临时口头要求（仅对当次生效，不修改上方配置）：说「xxx」→ 当次改某行为；……
+
+## 📝 自定义模板（TEMPLATE: custom 时启用，用户可手改）
+
+把 TEMPLATE 改为 custom 后，按下面结构生成（段名、段数、条目格式均可改）：
+
+```text
+段一：……（每条：……）
+段二：……（每条：……）
+```
+
+> 只写段结构与条目格式即可；未写明的细节沿用默认规范。