skill-forge-hub 1.3.1 → 1.3.2

package/CHANGELOG.en.md

@@ -4,6 +4,15 @@
 
 Version history of the SkillForge npm package `skill-forge-hub` (command name `skill-forge`).
 
+## 1.3.2 (2026-11-13)
+
+**prompt-pouch in-page usage scenarios + full functional check**
+
+- Functional check all green: 18/18 cards, zero JS errors; search/detail/delete-confirm/add/sort/theme-switch interactions verified; deleting a non-empty group triggers toast guard (confirm only for empty groups, both by design); the template page's three-tier fallback 404 probes are by design
+- In-page "usage tips" sidebar card and help panel (4 → 6 blocks) now cover conversation-saving scenarios: "save the last few rounds of chat into the pouch" with two-step confirmation, delete-first-confirm with prompts.json.bak-timestamp backup before write, and "rollback/restore pouch data" archive selection
+- usage-guide gains a "Typical scenarios" section: conversation capture / starting from scratch / delete & rollback / migration to a new machine
+- Template stamp prompt-pouch@10 → @11 (help panel structure change)
+
 ## 1.3.1 (2026-11-12)
 
 **Daily/weekly template sample data generalized + CSDN article visual refresh**

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 SkillForge（技能锻造坊）npm 包 `skill-forge-hub`（命令名 `skill-forge`）版本变更记录。
 
+## 1.3.2（2026-11-13）
+
+**prompt-pouch 页内使用场景三处布道 + 功能体检**
+
+- 功能体检全绿：18/18 卡片数、零 JS 报错，搜索/详情/删除确认/新增/排序/换肤全交互验证通过；删除非空分组走 toast 保护提示（组空才弹确认框，均设计内）；模板页三级兜底探测 404 为设计内行为
+- 页内「锦囊用法」侧栏说明卡与「使用帮助」面板（4 段扩 6 段）补充对话保存场景：对 AI 说「把上一轮/最近几轮对话存进锦囊」两段确认入囊、删除先确认且落盘前留 prompts.json.bak-时间戳、「回退/恢复锦囊数据」选档回滚
+- usage-guide 新增「典型使用场景」章节：对话沉淀 / 从零开始 / 对话删除与回退 / 换电脑迁移
+- 版本戳 prompt-pouch@10 → @11（帮助面板结构变化）
+
 ## 1.3.1（2026-11-12）
 
 **日报/周报模板示例数据通用化 + CSDN 推广文图文改版**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-forge-hub",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "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"

package/prompt-pouch/SKILL.md

@@ -31,11 +31,13 @@ disable-model-invocation: false
 1. **初始化**（目标目录无 `prompt-pouch.html` 时）：
    - **已有页面分支**：用户说「创建/生成」但目标目录已有 prompt-pouch.html → AskUserQuestion 三选项：A 打开现有页面（推荐，数据无损）；B 覆盖重建——旧页面先复制 .bak-时间戳，仅重置页面为新版 reference.html（DATA_DIR/BACKUP_DIR 数据目录一概不动，用户数据绝不丢）；C 取消不创建。默认推荐 A
    - **目录确认**：用户未提目录 → 用配置 `DIR`；`CONFIRM: true` 时先 AskUserQuestion 确认（选项：用默认目录 / 换目录）；用户已说「放到 XX 目录」→ 直接用该目录（本次会话有效，不改配置文件）
+   - **存内容触发的初始化**：用户因「把 XX 存进锦囊」而首次创建锦囊（目标目录无页面）→ 初始化前先 AskUserQuestion 询问示例数据（选项：A 生成示例五组（推荐，页面首开有内容可看）；B 空结构——直接进整理流程只存用户本次内容），用户未回应默认 A；选定后初始化继续，随后衔接步骤 2/5 完成本次入囊
    - 复制 `resources/reference.html` → `<DIR>/prompt-pouch.html`（原样复制，不修改任何样式与脚本；仅两处例外：①html 根标签 `data-theme` 属性值设为配置 `THEME`——reference 默认 "gold"，仅当配置非 gold 时替换该属性值；②head 中 `<meta name="pouch-id" content="...">` 的 content 替换为本次用 crypto.randomUUID() 新生成的全局唯一 ID——标准 UUID v4（十六进制 8-4-4-4-12 节，禁止手写变体、禁止沿用 reference 的占位 ID REF-POUCH-0000、禁止两份锦囊共用同一 ID；复制文件副本=同一身份共享数据）；落盘写文件前顺扫 <DIR> 下已有 html 的 pouch-id meta 查重，撞号重掷至不重复）
    - 创建 `<DIR>/<DATA_DIR>/` 与 `<DIR>/<BACKUP_DIR>/` 子目录（配置为空串则跳过、平铺根目录）；生成 `<DIR>/<DATA_DIR>/prompts.json`：`INIT_DATA: example` 时写入「各职业通用」示例五组（写作输出/沟通协作/规划执行/复盘成长/提问艺术，每组 3 条，标题与正文按下方「## 默认示例数据」清单写，**每条必带 createdAt 当前时间（YYYY-MM-DD HH:mm:ss，写到时分秒）**）；`empty` 时写空结构（version + 空 groups/prompts）
    - 收尾提示启动方式：`cd <DIR> && python3 -m http.server <PORT>`（Windows 无 python3 时 `py -m http.server`），浏览器访问 `http://localhost:<PORT>/prompt-pouch.html`（HTTP 自动读 prompts.json；file:// 直开浏览器会拦截文件读取——已授权目录则刷新自动直读 data/prompts.json，权限需重新确认时点徽标「🔓 恢复数据」一键续权，读不到则回退本地快照/镜像，推荐 HTTP 打开）
 2. **维护**（页面已存在时）：读 `<DIR>/<DATA_DIR>/prompts.json` → 按用户意图修改 → 写回（UTF-8、2 空格缩进、保留 version 字段）→ 提醒用户刷新页面
    - **落盘确认**：写回前展示将要落盘的内容（新增/修改的标题、分组、正文摘要，一句话说清改了什么），等用户确认后落盘；用户明确说「直接存/不用确认」则跳过（本次会话有效）；写回前重读最新文件合并；落盘完成后对话报告产物位置：页面文件 `<DIR>/prompt-pouch.html`、数据文件 `<DIR>/<DATA_DIR>/prompts.json`、滚动备份目录 `<DIR>/<BACKUP_DIR>/`
+   - **写回前备份**：每次修改写回前先复制 `<DIR>/<DATA_DIR>/prompts.json` 为同级 `prompts.json.bak-时间戳`（破坏性操作——删除提示词/删除或改动分组/批量整理——必做；简单新增可免但建议保留）；页面自动滚动备份只在页面运行时生效，AI 直写不触发，回退保障必须由 AI 自己留档。用户说「回退/恢复锦囊数据」时：列 `<DIR>/<DATA_DIR>/` 下 `.bak-时间戳` 清单（含时间与条目数）让用户选 → 恢复前再备份当前版（双保险）→ 恢复后机器校验 schema → 提醒用户刷新
    - **分类交互**：用户说「添加 XX」但未说分组 → 先按现有分组语义智能匹配（如内容讲周报 → 建议「写作输出 ✍️」并说明理由），匹配到则默认归入、用户可改口换组；匹配不到 → AskUserQuestion 列出全部现有分组（加「新建分组」选项）让用户选；用户指定的分组不存在 → 明确告知该分组不存在，并问是否新建（新建则补 groups 条目：id 16 位数字主键（雪花规则见 data-format.md）、name 中文、icon 一个 emoji）
 2.5 **交付前自检**（初始化与每次维护落盘后必做，硬门禁不可跳过）：
    - **json 机器校验**：`python3 -c "import json;json.load(open('<DIR>/<DATA_DIR>/prompts.json',encoding='utf-8'))"`（Windows 用 py）解析通过，且 schema 自查无缺（version/groups/prompts 齐全、group 引用存在、order 连续、新增条目 createdAt 到时分秒）
@@ -68,7 +70,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成/初始化页面时头部写版本戳 `<meta name="sf-template" content="prompt-pouch@10">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧锦囊/回炉旧页面/旧锦囊换新样式」时：扫 `<DIR>` 下 `prompt-pouch.html` 读版本戳筛出旧版（无版本戳或缺少 `<meta name="pouch-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/有无用户数据）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本；深升级（DOM 结构变化）从 reference.html 重建，**必须沿用原页 pouch-id meta 值**（IndexedDB 用户数据按 pouch-id 命名空间存取，换 ID = 数据失联，重建后原收藏/分组照旧读回），`<DIR>/<DATA_DIR>/prompts.json` 数据文件一概不动，先备份旧页 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成/初始化新锦囊时顺扫 `<DIR>` 读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版锦囊，说『把我旧锦囊都升级成新样式』即可一键升级」，不让用户背触发语。
+生成/初始化页面时头部写版本戳 `<meta name="sf-template" content="prompt-pouch@11">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧锦囊/回炉旧页面/旧锦囊换新样式」时：扫 `<DIR>` 下 `prompt-pouch.html` 读版本戳筛出旧版（无版本戳或缺少 `<meta name="pouch-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/有无用户数据）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本；深升级（DOM 结构变化）从 reference.html 重建，**必须沿用原页 pouch-id meta 值**（IndexedDB 用户数据按 pouch-id 命名空间存取，换 ID = 数据失联，重建后原收藏/分组照旧读回），`<DIR>/<DATA_DIR>/prompts.json` 数据文件一概不动，先备份旧页 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成/初始化新锦囊时顺扫 `<DIR>` 读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版锦囊，说『把我旧锦囊都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## ⚙️ 配置与自定义主题
 

package/prompt-pouch/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="prompt-pouch@10">
+<meta name="sf-template" content="prompt-pouch@11">
 <meta name="pouch-id" content="REF-POUCH-0000">
 <title>锦囊 Prompt Pouch — 提示词管理台</title>
 <style>
@@ -852,15 +852,23 @@ footer.open .ht-arrow{ transform:rotate(180deg); }
         <div class="hp-d">页面点 <b>「＋ 新增提示词」/「👁 详情」/「✎」/「🗑」</b>（授权目录即写即存），或对 AI 说 <b>「把 XX 加到锦囊的写作输出分组」</b>，AI 写入 data/prompts.json，刷新即见。</div>
       </div>
       <div class="hp-item">
-        <div class="hp-t">② 排序与移动</div>
+        <div class="hp-t">② 对话整理入囊</div>
+        <div class="hp-d">对 AI 说 <b>「把上一轮对话存进锦囊」「把最近几轮对话整理进锦囊」</b>——AI 提炼条目并智能打标、给 {变量} 泛化建议，确认条目后再推荐分组（装不下的建议新建），两段确认一次性入囊；还没锦囊时会先引导创建。</div>
+      </div>
+      <div class="hp-item">
+        <div class="hp-t">③ 排序与移动</div>
         <div class="hp-d">默认最新添加在前，可切「最近使用 / 使用频率 / 手动顺序」；拖动卡片或点 ▲▼ 自动切回手动、点 ⇄ 移到其它分组，点 <b>📋 复制变更指令</b> 交给 AI 落盘。</div>
       </div>
       <div class="hp-item">
-        <div class="hp-t">③ 打开方式</div>
+        <div class="hp-t">④ 删除与回退</div>
+        <div class="hp-d">页面点 🗑 删除弹统一确认框防误触（分组内有条目需先移出或删）；对 AI 说删同样先确认——AI 落盘前留 <b>prompts.json.bak-时间戳</b> 备份，说 <b>「回退/恢复锦囊数据」</b> 选档回滚。</div>
+      </div>
+      <div class="hp-item">
+        <div class="hp-t">⑤ 打开方式</div>
         <div class="hp-d">HTTP 访问读 data/prompts.json；file:// 直开则回退到本地缓存快照。</div>
       </div>
       <div class="hp-item">
-        <div class="hp-t">④ 数据安全</div>
+        <div class="hp-t">⑥ 数据安全</div>
         <div class="hp-d">收藏与排序存浏览器本地（IndexedDB）刷新不丢；每次变更 2 秒内自动备份到 backup/pouch-backup.json（滚动双备份），未授权时降级本地快照（保留 5 份）；<b>「📂 换目录」</b> 可随时重配，↩ 一键恢复。</div>
       </div>
     </div>
@@ -1033,7 +1041,7 @@ footer.open .ht-arrow{ transform:rotate(180deg); }
       html += '<div class="nav-item' + (state.curGroup===g.id?' on':'') + '" data-g="' + g.id + '" draggable="true" title="拖拽调整分组顺序"><span class="icon">' + g.icon + '</span><span class="g-name">' + escapeHtml(g.name) + '</span><span class="cnt">' + n + '</span><span class="g-ops"><button class="g-edit" title="编辑分组">✎</button><button class="g-del" title="删除分组">🗑</button></span></div>';
     });
     html += '</div>';
-    html += '<div class="side-tip"><b>锦囊用法</b><br>· 页面直接增删改：＋ 新建分组 / ＋ 新增提示词 / ✎ 编辑 / 🗑 删除（授权目录即写即存）<br>· 也可对 AI 说「把 XX 加到写作输出分组」<br>· 顶栏切换排序；⇄ 移组、拖卡片排序自动保存；拖分组条调整分组顺序<br>· 点卡片标签按标签筛选（再点取消）；标签悬停 ✕ 删 / ＋ 加；⤓ 导出 / ⤒ 导入 JSON 备份<br>· ⭐ 收藏常用 · 复制次数在卡片右上角</div>';
+    html += '<div class="side-tip"><b>锦囊用法</b><br>· 页面直接增删改：＋ 新建分组 / ＋ 新增提示词 / ✎ 编辑 / 🗑 删除（授权目录即写即存）<br>· 对 AI 说「把刚才这轮对话存进锦囊」——提炼条目、推荐分组，确认后入囊；也可说「把 XX 加到写作输出分组」<br>· 顶栏切换排序；⇄ 移组、拖卡片排序自动保存；拖分组条调整分组顺序<br>· 点卡片标签按标签筛选（再点取消）；标签悬停 ✕ 删 / ＋ 加；⤓ 导出 / ⤒ 导入 JSON 备份<br>· 删错对 AI 说「回退/恢复锦囊数据」选档回滚<br>· ⭐ 收藏常用 · 复制次数在卡片右上角</div>';
     sideNav.innerHTML = html;
     sideNav.querySelectorAll('.nav-item').forEach(function(el){
       el.addEventListener('click', function(){

package/prompt-pouch/resources/usage-guide.md

@@ -15,11 +15,18 @@
 9. **分组排序**：左侧分组条可直接拖拽调整顺序（已授权目录即写即存，未授权时指令自动复制给 AI 落盘）
 10. **导入 / 导出**：顶栏「⤓ 导出」把当前全部数据下载为 JSON 备份文件（文件名带时间戳）；「⤒ 导入」选择 JSON 文件整库覆盖现有数据（导入前自动备份，可从「↩ 恢复」回滚；未授权目录时导出仍可用、导入需先授权）
 
+## 典型使用场景
+
+- **对话沉淀**：对 AI 说「把上一轮对话存进锦囊」「把最近几轮对话整理进锦囊」「把最近一小时聊的内容存进锦囊」——AI 先把对话提炼成条目清单（标题/正文/智能标签/插值泛化建议），你确认条目后再按现有分组推荐归类（装不下的推荐新建分组），确认后一次性入囊
+- **从零开始**：还没创建锦囊时直接说「把 XX 存进锦囊」——AI 会先确认目录并引导创建页面（可选示例数据），随后无缝衔接入囊流程
+- **对话删除与回退**：对 AI 说「删掉锦囊里 XX 分组 / XX 这条」——先确认、落盘前自动留 `prompts.json.bak-时间戳` 备份；删错说「回退/恢复锦囊数据」，列出备份档供选档恢复（恢复前再备份当前版，双保险）
+- **换电脑迁移**：旧机「⤓ 导出」JSON 文件 → 新机「⤒ 导入」整库恢复（含分组与标签）；收藏、排序等页面本地态存浏览器本地（随页面 pouch-id 身份），不随 JSON 迁移
+
 ## 特色功能
 
 - **搜索高亮**：搜索框输入关键词，命中卡片的标题/正文/标签中匹配词以主题色徽标高亮（五主题自适应）；命中落在正文三行折叠区之外时，卡片顶部提示「正文命中，详见详情」，点开详情弹窗全文同样高亮
 - **{变量} 插值**：内容含花括号占位（如「{功能名}」）的提示词，点复制会自动弹出填充面板，填入变量后实时预览再复制
-- **自动备份（默认开启）**：数据一有变更 2 秒内自动备份——首次变更会请求授权写入 prompt-pouch.html 所在目录（弹窗选同目录即可，选一次后浏览器记住），写 backup/pouch-backup.json 并滚动保留上一版 .prev.json；未授权或浏览器不支持时自动降级为本地快照（浏览器内保留最近 5 份），页内「↩ 恢复」均可一键回滚；顶栏「📂 换目录」可随时重新配置备份目录
+- **自动备份（默认开启）**：数据一有变更 2 秒内自动备份——首次变更会请求授权写入 prompt-pouch.html 所在目录（弹窗选同目录即可，选一次后浏览器记住），写 backup/pouch-backup.json 并滚动保留上一版 .prev.json；未授权或浏览器不支持时自动降级为本地快照（浏览器内保留最近 5 份），页内「↩ 恢复」均可一键回滚；顶栏「📂 换目录」可随时重新配置备份目录；AI 代笔修改（对话中说增删改）落盘前也会在 data/ 目录留 `prompts.json.bak-时间戳`，说「回退/恢复锦囊数据」即可选档回滚
 - **统一确认弹框**：删除提示词/分组、覆盖导入、恢复备份、授权与换备份目录等需要确认的操作，都用页内统一样式的确认弹框（不再弹浏览器原生对话框）；删除/覆盖/恢复等危险操作为红调按钮，Esc 或点遮罩均可取消
 - **详情弹窗**：点卡片「👁 详情」弹出全文查看（超长内容限高 52vh 内滚动），带复制与修改入口，附时间线（创建 / 上次修改 / 最近使用）；含 {变量} 的模板会在弹窗里标出变量清单，复制时自动进入填充面板
 - **页面直写（双笔）**：页面增删改直接写入 data/prompts.json（与自动备份共用同一目录授权）；未授权时自动降级——生成操作指令复制到剪贴板，粘贴给 AI 落盘