skill-forge-hub 0.4.0 → 0.5.0

package/magic-deck/resources/usage-guide.md

@@ -0,0 +1,42 @@
+# 魔法幻灯生成器使用说明
+
+> 本文件是使用咨询的应答源：用户只问「怎么用 / 使用说明 / 能干什么」时，将本文件内容原样输出（首行标题改为「魔法幻灯生成器使用指南」），不执行任何生成动作。
+
+## 能干什么（三句话版）
+
+1. **内容变幻灯**：把一段文字、一份大纲或一个文件，做成单文件 HTML 幻灯片——16:9 舞台、双击即开、离线可用
+2. **现场改版**：版式模板十六套（经典商务 / 极简留白 / 杂志画册 / 黑金发布……）与主题配色十六套即点即换，可套全部页或仅当前页；「💼 领域」Tab 还有二十一套成套模板（毕业答辩 / 年终汇报 / 商业计划书 / 政务汇报……），一键生成整套页面
+3. **放映与出料**：自动播放 / 全屏纯净放映 / 翻页动画与元素动画库；逐页 PNG 截图与本页 / 选页文字复制（均不含工具栏等操作元素）
+
+## 放映热键
+
+| 按键 | 功能 |
+|:---|:---|
+| ← → ↑ ↓ / PageUp / PageDown / 空格 | 上一页 / 下一页 |
+| Home / End | 首页 / 末页 |
+| 1-9 | 数字直达对应页 |
+| P | 播放 / 暂停 |
+| S | 截图本页 |
+| C | 复制本页文字 |
+| F | 全屏（纯净放映，无关元素自动退场） |
+| G | 右侧边栏（▤ 页面管理 / ⚙ 工具） |
+| ? | 操作说明 |
+| Esc | 关闭弹层 / 退出全屏 |
+| Ctrl+Z / Ctrl+Shift+Z（Ctrl+Y） | 撤销 / 重做 |
+
+## 工具栏与边栏
+
+- **🎨 模板**：十六套版式骨架，应用范围可选全部页面 / 仅本页 / 勾选页面；先「预览本页」看效果再应用，切回「经典商务」恢复原排版、内容不丢
+- **🎨 主题**：十六套配色，色点即点即换，范围可选全部页面或仅本页
+- **↶ ↷ 撤销 / 重做**：模板应用、增删页、换主题等所有编辑操作都可回退
+- **▤ 页导航**：右侧缩略图边栏——点缩略图跳页、＋新页（16 版式任选）、复页、排序、删页
+- **⚙ 工具**：右侧边栏第二页签——翻页动画八套、元素入场 / 离场 / 强调动画、标题文字动画、⧉ 复制本页 / ▦ 选页复制 / 📷 截图本页 / ▦ 选页截图
+- **▶ 自动播放**：间隔 3s / 5s / 8s / 10s 可设，可循环、可从当前页或从头开始
+
+## 常见问题
+
+- **截图存到哪？** 截图 / 选页截图通过浏览器下载通道保存（逐张 PNG，命名含页码与主题名）；选页截图面板默认全选 = 一键导出全部页
+- **复制只想要文字？** 复制通道只取页面文字（多页按「【第 N 页】」分隔）；图片内容请走截图
+- **改完怎么保存？** 页面的编辑与换肤作用于当前打开的内存副本，刷新后回到原始文件；要固化效果请把新的版式 / 主题告诉 AI，让它重新生成 HTML
+- **放映时怎么干净？** 按 F 进全屏：工具栏、页码、箭头、弹层全部隐藏，画面纯黑背景只留幻灯内容，与 PPT 软件放映一致
+- **能拿到 PPT 吗？** magic-deck 产出 HTML 幻灯；要 .pptx 文件请用「登台 deck-stage」技能（报告 / 素材转专业 PPT，原生可编辑）

package/magic-deck/user-config.md

@@ -9,14 +9,16 @@
 ## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
 
 ```yaml
-CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+CONFIG_VERSION: 2              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
 
 # ── 落盘与外观 ──
 DIR: ~/Desktop            # 幻灯片 HTML 落盘目录
 FILENAME: auto            # 文件名（不含扩展名）：auto = 按本次内容主题+用途自动总结中文名（如「智能探针系统-产品介绍」，便于日后按名找回继续改）；也可口头指定文件名（永远优先）；或写死固定名如 slides（重名自动加日期后缀，不覆盖）
 OPEN_HTML: true           # 生成后自动打开浏览器放映
-THEME: tech               # 默认主题：tech 深蓝科技 / biz 浅色商务 / mono 极简黑白 / warm 温暖渐变（放映时工具栏可整份切换或「仅本页」单页换肤）
-TEMPLATE: classic         # 默认模板（版式骨架，与主题正交可自由组合）：classic 经典商务 / minimal 极简留白 / magazine 杂志画册 / keynote 黑金发布 / timeline 时间线叙事。生成时定默认版式，放映时可随时经工具栏「🎨 模板」面板切换（全部页/仅本页/勾选页，标题自动映射）
+THEME: tech               # 默认主题（十六套：tech 深蓝科技 / biz 浅色商务 / mono 极简黑白 / warm 温暖渐变 / aurora 极光紫 / dracula 德古拉紫 / nord 北欧冰蓝 / midnight 东京夜色 / matrix 终端荧光绿 / cyber 赛博霓虹 / apple 苹果极简 / stripe 条纹紫蓝 / notion 纸感暖白 / gruvbox 复古暖橙 / gold 黑金奢华 / ocean 深洋蓝；放映时「🎨 主题」面板色点即点即换：范围可选全部页面或仅本页）
+TEMPLATE: classic         # 默认模板
+TRANSITION: slide-lr     # 默认翻页动画风格（八套：slide-lr 左右滑移 / fade 淡入淡出 / slide-ud 上下滑移 / zoom 缩放推进 / flip 3D 翻页 / cube 立方翻转 / wipe 平移擦除 / dissolve 溶解模糊；放映时边栏「⚙ 工具」Tab 即点即换，选择记忆）
+ANIM: true               # 元素动画默认开（入场十二式挂 data-anim + 离场十二式挂 data-anim-leave + 强调八式挂 data-anim-emphasis + 标题文字动画，均带 data-anim-delay 八档错落；放映时边栏「⚙ 工具」Tab「开启」勾选框一键全关；false = 生成时 deck 挂 data-anim="off"）
 WIDTH: 1280               # 舞台宽度（16:9 基准，改宽高请同步改 deck-spec 同值）
 HEIGHT: 720               # 舞台高度
 SEC: 5                    # 自动播放默认间隔（秒，可选 3/5/8/10）
@@ -30,8 +32,9 @@ SIGNATURE: GENERATED BY SKILLFORGE   # 封面/结束页署名
 ```
 
 
-## 📝 模板与主题（像真 PPT 一样可选）
+## 📝 模板、主题与动画（像真 PPT 一样可选）
 
-- **内置模板五套**（版式骨架）：classic 经典商务（默认）/ minimal 极简留白 / magazine 杂志画册 / keynote 黑金发布 / timeline 时间线叙事。改上方 `TEMPLATE` 即换生成默认，或生成时口头点名（如「用杂志风模板」）当次生效；放映时随时经工具栏「🎨 模板」面板切换（全部页面/仅本页/选择页面），标题自动映射到模板固定位置，切回经典商务即恢复原排版
-- **内置主题四套**（配色，放映时随时换）：tech / biz / mono / warm。工具栏色点点击=整份切换；点「⭮ 仅本页」后再点色点=只给当前页换肤，再点一次恢复整份模式
-- **自定义模板片段**（可选）：在 `resources/templates/` 下放 `my-*.html`（仅 body 内容片段，不含 html/head/script），生成时用户点名模板名即可套用；未点名用内置五套模板
+- **内置模板十六套**（版式骨架）：classic 经典商务（默认）/ minimal 极简留白 / magazine 杂志画册 / keynote 黑金发布 / timeline 时间线叙事 / steps 流程步骤 / poster 海报宣传 / vintage 复古报纸 / finance 金融报表 / blueprint 蓝图工程 / education 教学板书 / executive 高管简报 / metro 扁平磁贴 / bento 模块网格 / dark 暗夜深色 / nature 自然清新。改上方 `TEMPLATE` 即换生成默认，或生成时口头点名（如「用杂志风模板」）当次生效；放映时随时经工具栏「🎨 模板」面板切换（全部页面/仅本页/选择页面），可先「预览本页」看效果再应用，标题自动映射到模板固定位置，切回经典商务即恢复原排版
+- **内置主题十六套**（配色，放映时随时换）：tech 深蓝科技（默认）/ biz 浅色商务 / mono 极简黑白 / warm 温暖渐变 / aurora 极光紫 / dracula 德古拉紫 / nord 北欧冰蓝 / midnight 东京夜色 / matrix 终端荧光绿 / cyber 赛博霓虹 / apple 苹果极简 / stripe 条纹紫蓝 / notion 纸感暖白 / gruvbox 复古暖橙 / gold 黑金奢华 / ocean 深洋蓝。「🎨 主题」面板点色点=整份切换；范围选「仅本页」后再点色点=只给当前页换肤，选回「全部页面」即恢复整份模式
+- **动画库**（动效，与模板/主题正交，放映时收纳在右侧边栏「⚙ 工具」Tab，应用范围可选全部页面/仅本页）：翻页风格八套——slide-lr 左右滑移（默认）/ fade 淡入淡出 / slide-ud 上下滑移 / zoom 缩放推进 / flip 3D 翻页 / cube 立方翻转 / wipe 平移擦除 / dissolve 溶解模糊，改上方 `TRANSITION` 即换生成默认，放映时即点即换；元素入场动画十二式（fade-up 上浮 / fade-in 淡入 / fade-down 下沉 / zoom-in 缩放 / slide-left 左滑 / slide-right 右滑 / slide-up 上滑 / slide-down 下滑 / pop 弹出 / bounce-in 弹跳 / flip-in 翻转 / blur 模糊浮现，另有 none 无动画），生成时元素挂 `data-anim` 属性声明、同页多元素挂 `data-anim-delay` 错落，翻到该页自动播放；离场动画十二式（元素挂 `data-anim-leave`，翻页前元素先离场 0.45s 再切页）；强调动画八式（pulse 脉冲 / swing 摆动 / shake 抖动 / breathe 呼吸 / flash 闪烁 / tada 放大 / spin 旋转 / glow 发光，元素挂 `data-anim-emphasis` 循环播放）；标题文字动画四式（none 无动画默认 / char 逐字 / word 逐词 / line 逐行）；`ANIM: false` 时入场动画整份关闭（或放映时「开启」勾选框取消），所有选择浏览器记忆
+- **自定义模板片段**（可选）：在 `resources/templates/` 下放 `my-*.html`（仅 body 内容片段，不含 html/head/script），生成时用户点名模板名即可套用；未点名用内置十六套模板

package/meta-forge/SKILL.md

@@ -34,6 +34,8 @@ disable-model-invocation: false
 
 升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
 
+**无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
+
 ## 文档同步自检纪律（维护者必读）
 
 修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如机制名/流程节点/字段名改名时新旧词全仓核对，旧词零残留才算完成）。修改 forge-rules.md 的机制规范必须同步检查本 SKILL.md 流程节点与 template/ 模板是否对齐，三者以 forge-rules.md 为规范真相源；改完后互相 grep 关键参数确认对齐。

package/meta-forge/resources/forge-rules.md

@@ -36,6 +36,7 @@
 - SKILL.md 含「配置版本机制（升级保护）」节，声明当前版本 + 迁移四步（备份 .bak-时间戳 → 按规则迁移 → 更新版本号 → 对话告知用户）
 - 配置结构变化（增/删/改名键）时：CONFIG_VERSION 递增 1，SKILL.md 该节写明迁移规则
 - 双层校验：CLI update 比对官方/本地版本做备份+询问；AI 每次执行时自检版本，不一致按迁移规则处理
+- **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三绝不——绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 / ✅ 已自动迁移清单 / 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
 - 禁止在未声明版本变更的情况下静默修改配置语义
 
 ### 机制二：user-config 抽离（配置出站）

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skill-forge-hub",
-  "version": "0.4.0",
-  "description": "SkillForge (技能锻造坊) — a curated collection of AI craft skills. Install once, then pick skills interactively: daily/weekly reports, article-to-HTML, SpecCore document converters.",
+  "version": "0.5.0",
+  "description": "SkillForge (技能锻造坊) — a curated collection of AI craft skills. Install once, then pick skills interactively: daily/weekly/annual reports, article-to-HTML, magic-deck slides, deck-stage PPTX, prompt-pouch manager, Pandoc doc converters, meta-forge.",
   "bin": {
     "skill-forge": "cli.js"
   },
@@ -12,19 +12,31 @@
     "annual-report",
     "article-to-html",
     "magic-deck",
+    "deck-stage",
     "spec-doc2spec",
     "spec-spec2doc",
     "meta-forge",
-    "template"
+    "prompt-pouch",
+    "template",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "keywords": [
     "skillforge",
     "skills",
     "ai-agent",
     "claude-skills",
+    "skill-forge",
     "daily-report",
     "weekly-report",
-    "article-to-html"
+    "annual-report",
+    "article-to-html",
+    "magic-deck",
+    "deck-stage",
+    "prompt-pouch",
+    "pandoc",
+    "meta-forge"
   ],
   "license": "MIT",
   "engines": {

package/prompt-pouch/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: prompt-pouch
+description: >
+  锦囊（prompt-pouch）提示词管理 Skill：生成并维护一个本地 HTML 提示词管理页面（锦囊管理台），
+  暖棕金/深蓝科技/极简黑白/薄荷绿四套主题（右下角换肤坞随时切换，THEME 配置可设默认），功能为分组侧栏（带计数徽章）+ 搜索（关键词高亮）+ 卡片网格 + 四种排序（最新添加默认/最近使用/使用频率/手动，
+  拖拽与 ▲▼ 自动切手动）+ 使用统计 + 收藏星标 + {变量} 插值填充面板 + 一键复制 + 卡片「👁 详情」弹窗
+  （全文滚动查看 / 复制 / 修改 / 创建修改时间线）；数据存 <DIR>/cache/prompts.json（DATA_DIR 可配），
+  页面与数据严格分离，双笔协作（页面经授权目录直写，AI 代笔维护）。三类任务：①初始化——目标目录无页面时确认目录（默认用户配置 DIR）
+  并生成 prompt-pouch.html（样式真相源为 resources/reference.html，原样复制）与 cache/prompts.json
+  （默认示例五组：写作输出/沟通协作/规划执行/复盘成长/提问艺术，每条带 createdAt；页面另内置同款示例种子 DEFAULT_POUCH，prompts.json 读不到时兜底展示）；②维护——按用户口述增删改提示词与分组、调整排序、
+  切换收藏，读写 prompts.json（UTF-8、2 空格缩进），用户刷新页面即见；③打开——用户说「打开锦囊」时
+  起本地服务并按平台打开浏览器访问管理页面。
+  数据通过 HTTP 方式访问（file:// 直开会回退浏览器缓存快照，需提示用户起本地服务）。
+  当用户问「锦囊怎么用/使用说明」时输出 resources/usage-guide.md 内容，不执行任何文件操作。
+allowed-tools: ["Bash", "Read", "Write", "Edit"]
+disable-model-invocation: false
+---
+
+# 锦囊 · 提示词管理台（prompt-pouch）
+
+妙计入囊、随取随用：一个纯 HTML 的本地提示词管理台，页面与数据分离——双笔协作：页面可直写、AI 可代笔，用户只管说，刷新即见。
+
+## 默认示例数据（INIT_DATA: example 时按此生成，可微调措辞）
+
+面向所有职业的通用场景五组，每组 3 条，标题简洁（2-6 字），正文含 {变量} 插值：
+
+| 分组（icon） | 条目（标题 → 正文模板） |
+|:---|:---|
+| 写作输出 ✍️ | ① 日报速写 → 帮我根据以下内容写一份工作日报。今日完成：{今日事项}；明日计划：{明日计划}；风险阻塞：{风险问题}。要求：简洁、量化优先、分点列出。② 周报汇总 → 帮我写一份本周周报。本周完成：{本周成果}；下周计划：{下周安排}；需要协调：{协调事项}。要求：突出数据结果，避免流水账。③ 工作汇报 → 请根据以下材料起草一份向上级的工作汇报。进展：{工作进展}；成果数据：{量化数据}；所需支持：{支持需求}。要求：结论先行、语气专业。 |
+| 沟通协作 💬 | ① 会议纪要 → 帮我把这份会议记录整理成规范纪要。原始记录：{会议内容}。输出：会议主题、核心结论、待办事项（含负责人与截止时间）。② 邮件润色 → 帮我润色这封工作邮件，使其更专业得体。邮件原文：{邮件内容}。收件人身份：{收件人身份}。③ 沟通话术 → 帮我把这段话改得更委婉得体，用于跨部门沟通。原始表达：{原始表达}。沟通背景：{沟通背景}。 |
+| 规划执行 📌 | ① 任务拆解 → 帮我把这个目标拆解成可执行的任务清单。目标：{目标描述}；截止时间：{截止日期}。按优先级排序，每项给出验收标准。② 计划安排 → 帮我制定未来 {时间周期} 的工作计划。重点事项：{重点事项}；可用时间：{可用工时}。要求：安排到天、留出缓冲。③ 优先级排序 → 帮我给以下待办事项排序。待办清单：{待办清单}。按重要紧急四象限分类并说明理由。 |
+| 复盘成长 🔍 | ① 项目复盘 → 帮我做一次项目复盘。项目情况：{项目背景}；结果数据：{结果数据}；遇到的问题：{问题清单}。输出：亮点、不足、改进措施。② 阶段总结 → 帮我把以下工作记录提炼成阶段总结。工作记录：{工作记录}。要求：突出关键成果与量化指标。③ 经验沉淀 → 帮我把这次经验整理成可复用的方法论。事件经过：{事件描述}；我的做法：{处理方式}；结果：{最终结果}。输出：步骤化流程 + 注意事项。 |
+| 提问艺术 🎯 | ① 需求澄清 → 帮我把这段模糊需求拆解成可执行的具体要求。原始需求：{需求描述}。输出：目标、约束条件、交付物、验收标准；不确定处附追问清单，不要自行假设。② 引导式提问 → 请按「背景 → 现状 → 目标 → 障碍 → 已试过的办法」引导我逐步提供信息。我要解决的问题：{问题描述}。要求：一次只问一个问题，先别急着给答案。③ 追问清单 → 针对我的问题先列出 {数量} 个关键追问帮我理清思路，再基于我的回答给方案。我的问题：{问题描述}。追问要求：具体、可回答、按重要性排序。 |
+
+## 执行流程
+
+0. **读用户配置**（DIR/DIR_WIN/PORT/DATA_DIR/BACKUP_DIR/INIT_DATA/CONFIRM/THEME/CONFIG_VERSION）→ 先 Read 同目录 `user-config.md`
+1. **初始化**（目标目录无 `prompt-pouch.html` 时）：
+   - **目录确认**：用户未提目录 → 用配置 `DIR`；`CONFIRM: true` 时先 AskUserQuestion 确认（选项：用默认目录 / 换目录）；用户已说「放到 XX 目录」→ 直接用该目录（本次会话有效，不改配置文件）
+   - 复制 `resources/reference.html` → `<DIR>/prompt-pouch.html`（原样复制，不修改任何样式与脚本；唯一例外：html 根标签 `data-theme` 属性值设为配置 `THEME`——reference 默认 "gold"，仅当配置非 gold 时替换该属性值）
+   - 创建 `<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:// 直开回退缓存快照）
+2. **维护**（页面已存在时）：读 `<DIR>/<DATA_DIR>/prompts.json` → 按用户意图修改 → 写回（UTF-8、2 空格缩进、保留 version 字段）→ 提醒用户刷新页面
+   - **分类交互**：用户说「添加 XX」但未说分组 → AskUserQuestion 列出全部现有分组（加「新建分组」选项）让用户选；用户指定的分组不存在 → 明确告知该分组不存在，并问是否新建（新建则补 groups 条目：id 16 位数字主键（雪花规则见 data-format.md）、name 中文、icon 一个 emoji）
+3. **打开页面**：用户说「打开锦囊 / 打开提示词页面」→
+   - 目标目录无页面时先执行步骤 1（初始化）
+   - 后台起本地服务（`cd <DIR> && python3 -m http.server <PORT>`，Windows 用 `py -m http.server`；端口被占则换 PORT+1 再试）
+   - 按平台打开浏览器：darwin → `open http://localhost:<PORT>/prompt-pouch.html`；win32 → `start` 同 URL；linux → `xdg-open` 同 URL
+4. **结构规则与维护操作** → 读 `resources/data-format.md`（schema、id 规范、createdAt、updatedAt、排序落盘、插值语法、排序模式）
+5. **批量整理入囊**（用户给一堆文字/文件/说「把最近对话框内容整理进锦囊」）：
+   - 读 `<DIR>/<DATA_DIR>/prompts.json` 现状 → 逐条提炼候选提示词（标题/正文/建议归入哪个现有组/标签 1-3 个）
+   - 输出整理方案表给用户：每条建议分组与理由；现有组装不下的条目推荐新建分组（中文名 + emoji icon + 一句推荐理由），不擅自落盘
+   - 用户口述调整（换组/改名/删条目/改推荐组名）→ 确认后一次性落盘：id 雪花规则、createdAt 当天、各组 order 续排，写回前重读最新文件合并
+   - 落盘后提醒用户刷新页面
+6. **使用咨询**（用户只问「锦囊怎么用」等用法、未要求生成或修改）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「锦囊使用指南」），不读写任何文件
+
+## ⚙️ 配置与自定义主题
+
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：目录（DIR/DIR_WIN）、端口（PORT）、初始化数据（INIT_DATA）、确认开关（CONFIRM）、主题（THEME）等默认配置都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留。
+
+**THEME 主题机制**：页面内置四套主题——gold 暖棕金（默认）/ tech 深蓝科技 / mono 极简黑白 / mint 薄荷绿。初始化复制 reference.html 后，将 html 根标签 `data-theme` 属性值设为配置 `THEME`（仅此一处修改）；页面右下角「换肤坞」色点可随时切换主题，选择经浏览器 localStorage 持久（key: sf-pouch-theme），刷新后保持；localStorage 优先级高于根标签 data-theme。已初始化的页面改配置 THEME 不追溯——用户手动换过主题即以其选择为准。
+
+**配置版本机制（升级保护）**：user-config.md 头部 `CONFIG_VERSION` 标识结构版本。升级 skill 后若发现新版本结构（如 v2 新增 THEME 字段）而用户配置是旧版：先备份旧配置为 `user-config.md.bak-时间戳`，将旧值迁移进新结构（保留用户已有 DIR/PORT/INIT_DATA/CONFIRM，缺失字段补默认值），更新 CONFIG_VERSION，最后用一句话告知用户配置已升级、旧文件备份在哪。 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三绝不——绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在备份）、一次说清（升级报告三段式：⚠️ 版本与备份路径 / ✅ 已自动迁移 / 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件（prompts.json）迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层（旧 id 兼容保留即范例）或留备份提示手动整理
+
+## 核心约束
+
+- **页面与数据分离**：HTML 不内嵌用户数据——一切用户数据只进 <DATA_DIR>/prompts.json；HTML 内置只读示例种子（DEFAULT_POUCH 五组 15 条），仅当 prompts.json 读不到且浏览器无缓存快照时兜底展示（file:// 直开也能看到示范数据），一旦读到 prompts.json 即以文件为准；样式升级只改仓库 reference.html 后重新复制到目标目录（用户数据不受影响）
+- **目录结构（v3）**：数据文件默认 `<DIR>/<DATA_DIR>/prompts.json`（默认 cache/），自动备份默认 `<DIR>/<BACKUP_DIR>/`（默认 backup/，pouch-backup.json + .prev.json 滚动双备份）；页面读侧兼容旧平铺结构（新路径读不到时兜底读根目录旧文件），写侧一律写新路径；AI 初始化/维护时发现旧平铺结构（根目录 prompts.json / pouch-backup*.json）→ 建子目录并迁移文件（迁移前先复制 .bak-时间戳），一句话告知用户
+- **双笔协作**：页面（授权目录时）与 AI 都可写 prompts.json——页面上有「＋ 新增提示词 / ✎ / 🗑 / 分组管理」表单直写；AI 落盘前必须重读最新文件再合并写回（见「页面双笔纪律」）
+- **prompts.json 结构必须合法**：写回前自查 schema（version/groups[]/prompts[] 各字段齐全、group 引用存在、order 连续）
+- **排序四模式**：页面顶栏切换「最新添加（默认，按 createdAt 倒序）/ 最近使用 / 使用频率 / 手动顺序」；最近使用与使用频率由页面在复制时自动统计（浏览器本地态，AI 不落盘）；用户在非手动模式下拖动卡片或点 ▲▼ 会自动切回手动顺序、点卡片 ⇄ 可把提示词移到其它分组——用户随后粘贴「复制变更指令」，AI 必须按指令落盘：先执行「分组调整」节（改各条 group），再按「各组顺序」节每组列出的顺序重写各条 `order`，写回后提醒用户刷新并点页面「✓ 已落盘」清除标记
+- **id 规范**：组与提示词的 id 均为 16 位纯数字主键（雪花变体 = 13 位毫秒时间戳 + 3 位随机数，如 1762500000123456），全库唯一、删除后不复用、跨导出导入不冲突；AI 生成时按当前日期时间换算 13 位毫秒戳 + 自选 3 位随机数，与现有 id 重复则只换随机段；旧版「slug+序号」字符串 id（如 w05）兼容保留不迁移，新数据一律数字雪花 id（详见 data-format.md「id 生成规则」）
+- **createdAt 规范**：新增提示词必写 `createdAt`（当天日期，YYYY-MM-DD 或完整 ISO 8601），它是「最新添加」默认排序的依据；旧数据可无此字段
+- **updatedAt 规范**：AI 修改提示词（改标题/分组/内容/标签）时同步写/更新 `updatedAt`（当天日期，格式同 createdAt）；仅重排 order 或改收藏不更新；新增不写（视为无修改）
+- **页面双笔纪律**：页面经目录授权后可直写 prompts.json（增删改分组与提示词、排序落盘）。AI 每次维护必须先重读最新 prompts.json 再修改写回，严禁基于会话早期读入的旧内容覆盖写回（会丢失页面刚写入的改动）；页面未授权目录时的操作会生成「复制指令」交回 AI，按指令内容落盘
+- **插值语法**：内容里的 `{变量名}`（如「{功能名}」）会被页面自动识别为填充面板变量，写内容时按需保留花括号占位
+- **主题令牌纪律**：reference.html 组件样式一律引用 CSS 变量（--gold/--gold2/--gold-dim/--border/--tag-bg/--star/--glow/--bar-hi/--bar-lo 等），禁止在组件侧硬编码暖棕金色值（#e8b04b、rgba(232,176,75,…)、rgba(23,17,12,…)）；新增样式需复用现有令牌或先在四主题块中各补一致定义；改主题只改对应 [data-theme] 块，不动组件

package/prompt-pouch/resources/data-format.md

@@ -0,0 +1,67 @@
+# prompts.json 结构规范与维护操作
+
+## Schema（version 1）
+
+```json
+{
+  "version": 1,
+  "groups": [
+    { "id": 1762500000000101, "name": "写作输出", "icon": "✍️" }
+  ],
+  "prompts": [
+    {
+      "id": 1762500000123456,
+      "group": 1762500000000101,
+      "title": "日报速写",
+      "content": "提示词正文，支持 {变量} 插值占位……",
+      "tags": ["日报", "工作"],
+      "order": 1,
+      "favorite": true,
+      "createdAt": "2026-11-10 14:23:45",
+      "updatedAt": "2026-11-10 16:05:12"
+    }
+  ]
+}
+```
+
+## 字段约定
+
+- `groups[].id`：16 位纯数字主键（雪花 ID，见下「id 生成规则」），全库唯一；`name` 中文显示名；`icon` 一个 emoji
+- `prompts[].id`：16 位纯数字主键（雪花 ID），全库唯一，删除后不复用
+- `prompts[].group`：引用组的数字 id，写回前逐一校验
+- `prompts[].order`：组内排序权重，从 1 递增且尽量连续；重排时按新顺序整体重写（数字 id 天然按时间有序，可作辅助参考）
+- `prompts[].favorite`：收藏星标（页面点星为本地态，指令「收藏/取消收藏 XX」由 AI 落盘）
+- `prompts[].tags`：1-3 个短标签，用于搜索与归类
+- `prompts[].createdAt`：添加时间（YYYY-MM-DD 或 YYYY-MM-DD HH:mm:ss，**新增提示词必写到时分秒**）；旧数据可无此字段或仅日期（页面按 order 兜底排序，数字 id 时间序可辅助）
+- `prompts[].updatedAt`：最近一次内容修改时间（格式同 createdAt，写到时分秒）；新增不写、首次修改才写，仅重排 order 不更新
+
+### id 生成规则（雪花变体）
+
+16 位纯数字 = 13 位毫秒时间戳 + 3 位随机数，如 `1762500000123456`：
+
+- AI 生成：把当前日期时间换算成 13 位毫秒时间戳（精确到秒即可，毫秒三位自选），末尾拼 3 位随机数（000~999 自选）；与现有 id 重复时只换随机段（同一毫秒不同随机数即不同 id）
+- 保证：不同时刻生成必不同 → 导出数据再导入不冲突；删除不复用；纯数字比 UUID 短一半，AI 抄写定位不易错
+- 存量兼容：早期版本 id 可能是「组 slug+序号」字符串（如 w05），兼容保留不必迁移（id 仅作唯一键）；新生成的组/提示词一律用数字雪花 id
+
+## 维护操作规则
+
+- **新增提示词**：用户说「把 XX 加到锦囊的写作输出分组」→ 补一条 prompts 记录（id 按雪花规则生成数字主键、group/title/content/tags/order/favorite/createdAt 齐全，createdAt 写到时分秒）；未指定分组时，优先选语义最匹配的现有分组，实在没有才新建分组并先询问
+- **修改**：定位 id 或标题，只改用户指定的字段；「修改锦囊里『日报速写』的内容」→ 整段替换 content；改标题/分组/内容/标签时把 updatedAt 更新为当前时间（格式同 createdAt，写到时分秒）
+- **删除**：删 prompts 条目；删分组前须先处理组内条目（移组或一并删除，需与用户确认）
+- **排序与分组**：用户粘贴「复制变更指令」文本 → 先按「分组调整」节改各条 `group`（把「X」从「A」移到「B」），再按「各组顺序」节每组列表顺序重写 `order`；指令含「未保存」提示时，说明用户拖拽后未复制最新指令，以指令内容为准
+- **新建分组**：id 按雪花规则生成数字主键，name 中文，icon 一个 emoji
+- **写回格式**：UTF-8、2 空格缩进、末尾换行；不压缩不重排无关字段
+- **双写者纪律**：页面（授权目录时）与 AI 都会写本文件——任何一方写回前必须重读最新内容再合并修改，严禁基于旧内容整体覆盖
+
+## 页面排序模式（AI 只负责 order、createdAt 与 updatedAt，其余为浏览器本地态）
+
+| 模式 | 依据 | 谁维护 |
+|:---|:---|:---|
+| 最新添加（默认） | `createdAt` 倒序，全时间范围 | AI 写 createdAt |
+| 最近使用 | 复制时页面自动记 `lastUsed` 时间戳，倒序 | 页面自动（浏览器本地态） |
+| 使用频率 | 复制时页面自动累加 `useCount`，倒序 | 页面自动（浏览器本地态） |
+| 手动顺序 | `order` 升序 | AI 按「复制变更指令」重写 order |
+
+- 排序模式选择、使用统计、收藏均存浏览器本地（IndexedDB + localStorage 镜像），**不写数据文件（prompts.json）**，AI 无需落盘这些字段
+- 用户在「最近添加/最近使用/使用频率」模式下拖动卡片或点 ▲▼，页面自动切回「手动顺序」并提示；随后按指令重写 order
+- 写 order 时注意：手动顺序只约束组内，跨组顺序无意义（页面按分组展示）