skill-forge-hub 1.0.7 → 1.2.0

package/decision-log/resources/skillforge-guide.txt

@@ -0,0 +1,132 @@
+# SkillForge 使用指引（技能锻造坊）
+
+SkillForge 是一套个人技能仓库 + 命令行分发器（npm 包 skill-forge-hub，命令 skill-forge）：把 21 个技能打包分发，一条命令装进你的 AI 助手技能目录；升级时配置版本感知，你的本地个性化配置永不丢失。
+
+## 一、SkillForge 是什么
+
+三个关键词：
+1、技能仓库：21 个技能按「最终产出什么」分七类（报表汇演 / 文档装裱 / 工程提效 / 演示汇演 / 数据整备 / 沟通协作 / 技能自造），每个技能都是 SKILL.md 薄入口 + resources/ 分册 + user-config.md 用户配置的规范结构
+2、命令行分发器：npm 包 skill-forge-hub，命令 skill-forge（ls / init / update），自动探测 AI 助手技能目录，交互或非交互安装
+3、配置保护：每个技能的用户配置出站在 user-config.md，升级永不覆盖；配置结构变化时备份 + 三选一，官方新配置另存对照文件供手动合并
+
+技能全景（21 个）：
+
+| 分类 | 技能 | 一句话触发语 |
+|:---|:---|:---|
+| 报表汇演 | daily-report | 「写日报」 |
+| 报表汇演 | weekly-report | 「写周报」 |
+| 报表汇演 | monthly-report | 「写月报」 |
+| 报表汇演 | quarterly-report | 「写季报」 |
+| 报表汇演 | annual-report | 「写年报」 |
+| 报表汇演 | team-report-collector | 「收日报」 |
+| 文档装裱 | article-to-html | 丢给它一个文档 |
+| 文档装裱 | twin-docs | 「翻译成英文文档」 |
+| 文档装裱 | one-pager | 「做张海报」 |
+| 工程提效 | spec-doc2spec | 「把这个文档转成需求规格」 |
+| 工程提效 | spec-spec2doc | 「把这个规格导出 Word/PDF」 |
+| 工程提效 | release-notes | 「写发版说明」 |
+| 演示汇演 | magic-deck | 「做个 PPT」（HTML 幻灯形态） |
+| 演示汇演 | deck-stage | 「做个 PPT」（.pptx 可编辑形态） |
+| 数据整备 | data-prepper | 「整理这份数据」 |
+| 数据整备 | commit-heatmap | 「生成提交热力图」 |
+| 沟通协作 | meeting-minutes | 「记会议」 |
+| 沟通协作 | prompt-pouch | 「做一个锦囊管理页面」 |
+| 沟通协作 | decision-log | 「记决策」 |
+| 技能自造 | meta-forge | 「帮我创建一个新技能」 |
+| 技能自造 | skill-doctor | 「给技能体检」 |
+
+## 二、命令速查
+
+| 命令 | 说明 |
+|:---|:---|
+| skill-forge ls | 列出全部技能（分类 + 名称 + 说明），只读不写文件 |
+| skill-forge init | 交互挑选安装：a 全装 / 编号挑选（已装标 ★）/ 确认时 s 跳过已装 |
+| npm update -g skill-forge-hub | 官方发新版后升级 CLI 本体（只升级本包） |
+| skill-forge update | 升级全部已安装技能（配置版本感知） |
+| skill-forge update --skills a,b | 只升级指定技能（未安装的提示跳过） |
+| skill-forge --version | 显示版本号 |
+| skill-forge --help | 显示完整帮助 |
+
+命令别名：list = ls、install = init、upgrade = update。
+
+通用参数（init / update 通用）：
+--target <目录>（-t）：指定技能目录；缺省自动探测常见助手目录（~/.qoder-cn、~/.claude、~/.cursor 等），探测到多个时交互选择
+--skills a,b（-s）：init 时跳过选择直接装指定技能（脚本与单件补装友好）；update 时只升级指定技能
+--yes（-y）：跳过确认直接执行；配置版本变化时默认「保留我的 + 官方版另存 .upstream 对照」
+
+## 三、场景化使用流程
+
+场景一 首次接入（从零到可用）：
+1、npm i -g skill-forge-hub
+2、skill-forge ls（先浏览清单，只读）
+3、skill-forge init（交互挑选）→ 输入 a 全装或编号挑选 → 确认时 s 跳过已装 → 自动探测技能目录 → 完成
+装完直接对话触发：「写日报」「写周报」「写月报」「写季报」「写年报」「记会议」，或直接丢给它一个文档。
+
+场景二 单件补装（脚本 / 只想要某一个）：
+skill-forge init --skills prompt-pouch --target ~/.qoder-cn/skills
+跳过挑选环节，只装指定技能到指定目录。
+
+场景三 官方发新版后升级：
+先 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] 保留我的（默认，最稳，官方版另存 .upstream 对照文件手动合并）/ [3] 稍后处理
+· 官方删了文件：按 .installed-manifest 安装清单精准清理，你自建的文件一律不动
+
+场景四 非交互 / 自动化：
+skill-forge init --skills daily-report,weekly-report --yes
+--yes 跳过一切确认，配置冲突默认走 [2] 保留我的。
+
+场景五 换机器 / 换 AI 助手：
+新环境重新 npm i -g skill-forge-hub && skill-forge init；保留个人配置就把旧机器技能目录里的 user-config.md 一并拷过去（升级永不覆盖，覆盖安装时也保留）。
+
+## 四、典型技能使用链路
+
+统一节奏：安装 → 首次生成 → 修改配置 → 官方升级后 → 旧产物回炉。
+
+1、日报（报表族代表）：
+- 安装：skill-forge init --skills daily-report
+- 日常生成：说「写日报」口述内容 → md/txt/html（自动打开）+ 截图
+- 修改配置：user-config.md 改 DIR（落盘目录）/ THEME（五主题）/ TEMPLATE（自定义模板）；临时口头要求当次生效不写配置
+- 官方升级后：配置冲突选 [2] 保留我的，对照 .upstream 合并新配置点
+- 旧产物回炉：模板版本戳升了说「把我旧日报都升级成新样式」——浅升级换样式块、深升级从同目录 md 底稿重建，旧版先备份
+
+2、锦囊 prompt-pouch：
+- 安装：skill-forge init --skills prompt-pouch
+- 首次生成：「做一个锦囊管理页面」→ 生成管理台 html + data/prompts.json 数据文件
+- 日常使用：分组侧栏 / 搜索 / 收藏 / 标签点击过滤 / {变量} 插值一键复制 / 导入导出 JSON 备份；页面与数据分离，删页面不丢数据
+- 修改配置：user-config.md 改 DIR（页面目录）、DATA_DIR / BACKUP_DIR（数据与备份目录）
+- 官方升级后：数据目录与数据文件一概不动；深升级重建沿用原页 pouch-id → 收藏 / 分组照旧读回
+- 页面版本升级（回炉）：模板版本戳升了，下次生成时 AI 主动提示「检测到 X 份旧版锦囊」→ 说「把我旧锦囊都升级成新样式」→ 列清单选全部或部分 → 浅升级换样式块、深升级从模板重建沿用原页 pouch-id（收藏分组照旧读回）；prompts.json 数据不动、旧页先备份 .bak-时间戳
+- 多文件隔离：两份锦囊各自独立（内嵌 ID 命名空间）；复制文件副本 = 同一身份共享同一份数据（要独立身份请重新生成一份）
+
+3、PPT 两形态 magic-deck / deck-stage：
+- 选形态：说「做个 PPT」AI 先问——HTML 幻灯（magic-deck）还是 .pptx 可编辑文稿（deck-stage）
+- HTML 幻灯：magic-deck 生成单文件 HTML 幻灯，浏览器全屏放映（自动播放 / 循环 / 热键翻页）；需要图片时逐页 PNG 截图
+- .pptx 文稿：deck-stage 三问交互（素材 → 页骨架表 → 成片方式）生成 .pptx——常规页原生可编辑（数据卡 / 时间线 / 图表），封面与结尾页 HTML 截图保真
+- 补依赖：deck-stage 依赖 PptxGenJS，npm 包不含 node_modules，装完按提示 cd <技能目录>/deck-stage && npm install 补装一次
+- 修改配置：五主题 / 页面尺寸 / 演讲备注在 user-config.md
+
+4、会议纪要 meeting-minutes：
+- 日常生成：「记会议」口述材料 → 五段式纪要（会议信息 / 会议结论 / 议题讨论 / 决议与行动项 / 下次会议），行动项带负责人与截止时间——日报 / 周报 / 月报 / 季报的汇报链源头
+- 修改配置：SERIES_GROUP 三态——auto 自动提取系列名归入 meetings/{系列名}/、series 一律按系列建目录、off 纯月份平铺；改口机制「以后这个系列叫 XX」永久生效
+- 官方升级后：同报表族——配置三选一保护 + 说「把旧纪要升级成新样式」回炉
+
+## 五、通用小抄
+
+| 需求 | 做法 |
+|:---|:---|
+| 换落盘目录 / 主题 / 模板 | 改 user-config.md（升级永不覆盖） |
+| 官方发新版 | skill-forge update，配置冲突选 [2] 保留我的 |
+| 旧产物换新样式 | 说「把我旧 XX 都升级成新样式」 |
+| 装漏技能 | skill-forge init --skills 技能名 |
+| 查全部命令 | skill-forge --help |
+| 问单个技能用法 | 直接问「XX 技能怎么用」，AI 会读该技能的使用说明输出 |
+| 问 SkillForge 本身 | 问「skillforge 怎么用」，AI 朗读本指引并打开排版页 |
+| 查技能双语简介 / 实操文章 | SKILLS_CATALOG.md（21 技能逐条中英简介）/ docs/articles/（实操文章）/ docs/directory-submission.md（目录收录素材） |
+
+## 六、常见问题
+
+1、装完对话没触发技能：确认装进了当前 AI 助手实际读取的技能目录（init 完成时输出的路径）
+2、deck-stage 报缺依赖：cd <技能目录>/deck-stage && npm install 补装 PptxGenJS 一次即可
+3、升级后配置会丢吗：不会。user-config.md（与 .preserve 清单内文件）升级永不覆盖，本地修改永久保留
+4、这份指引在哪：每个技能的 resources/ 目录里都有（skillforge-guide.txt 文字版 + skillforge-guide.html 排版版），官方升级时随技能资源一起更新

package/decision-log/resources/usage-guide.md

@@ -0,0 +1,23 @@
+# 决策日志使用指南
+
+## 能做什么
+
+把重要决策沉淀为四元组日志（结论 / 取舍权衡 / 被否方案 / 适用与失效条件），按主题聚合、时间倒序索引，随时一句话检索复盘。
+
+## 怎么用
+
+1. 说「**记一条决策**」+ 口述内容（如「决定数据层用内嵌 ID 命名空间而不是固定键」）
+2. 我按四元组补全缺项（被否方案 / 失效条件等逐项追问），落盘到 `decisions/{主题}/`
+3. 说「**查决策** 数据层」→ 输出命中摘要清单，点条目看四元组全文
+4. 季度 / 年度复盘时：「把今年决策聚合一下」→ 按主题汇总输出
+
+## 可改配置（user-config.md）
+
+- `DIR`：日志根目录（默认当前项目 .decisions/）
+- `TEMPLATE`：记录模板（four-tuple 四元组）
+- `ASK_CONFIRM`：落盘前是否先确认
+
+## 使用提示
+
+- 四元组缺一不可，口述缺项我会追问补齐
+- 追加不覆盖，同主题决策按时间沉淀，复盘时脉络完整

package/decision-log/user-config.md

@@ -0,0 +1,9 @@
+# user-config.md（本文件不会被 skill 升级覆盖，你的修改永久保留）
+# 官方配置更新时，另存 user-config.upstream.md 对照文件，可手动合并新配置点
+
+```yaml
+CONFIG_VERSION: 1  # 配置结构版本，skill 升级迁移依据
+
+DIR: auto          # 日志根目录：auto = 当前项目 .decisions/；无项目上下文时回退用户主目录 ~/decisions
+TEMPLATE: four-tuple  # 记录模板：four-tuple 四元组（默认）
+ASK_CONFIRM: false  # 落盘前是否先展示记录内容等用户确认

package/deck-stage/SKILL.md

@@ -1,13 +1,6 @@
 ---
 name: deck-stage
-description: >
-  登台 deck-stage：把日报/周报/月报/季报/年报（md/HTML/口述大纲）或散装素材（目录/文件/随手文字）转成专业 .pptx 演示文稿。
-  三问交互——先问素材（指定目录/指定文件/贴文字/口述主题）、再报页结构大纲表确认、后选成片方式（一键成片/逐页确认）。
-  混合模式——常规页原生生成（文本/数据卡/时间线/柱图/饼图/折线，全部可编辑），封面与结尾页用 HTML 截图贴图（视觉保真）。
-  视觉与报告深蓝面板体系同源：tech 深蓝科技（默认）/biz 浅色商务/mono IDEA 黑亮/light IDEA 白亮/warm 温暖渐变五主题，
-  五段节色（蓝/绿/紫/玫红/橙）。每页可带演讲备注（notes），bullets 页可配图。
-  数据经结构化 data.json 交给 resources/pptx-builder.js（PptxGenJS，本目录 node_modules 离线可用）产出 16:9 pptx。
-  当用户请求把报告/日报/周报/月报/季报/年报转成 PPT、做成 PPT、导出 pptx、生成演示文稿、登台，或询问本 skill 用法时使用。用户要 HTML 网页幻灯（网页放映/分享）时不用本 skill（交给 magic-deck）；「做 PPT/演示文稿」未言明产出形态时先 AskUserQuestion 二选一（.pptx 可编辑文件 → 本 skill；HTML 网页幻灯 → magic-deck），不擅自默认。
+description: 登台 deck-stage：把日报/周报/月报/季报/年报（md/HTML/口述大纲）或散装素材（目录/文件/随手文字）转成专业 .pptx 演示文稿。 三问交互——先问素材（指定目录/指定文件/贴文字/口述主题）、再报页结构大纲表确认、后选成片方式（一键成片/逐页确认）。 混合模式——常规页原生生成（文本/数据卡/时间线/柱图/饼图/折线，全部可编辑），封面与结尾页用 HTML 截图贴图（视觉保真）。 视觉与报告深蓝面板体系同源：tech 深蓝科技（默认）/biz 浅色商务/mono IDEA 黑亮/light IDEA 白亮/warm 温暖渐变五主题， 五段节色（蓝/绿/紫/玫红/橙）。每页可带演讲备注（notes），bullets 页可配图。 数据经结构化 data.json 交给 resources/pptx-builder.js（PptxGenJS，本目录 node_modules 离线可用）产出 16:9 pptx。 当用户请求把报告/日报/周报/月报/季报/年报转成 PPT、做成 PPT、导出 pptx、生成演示文稿、登台，或询问本 skill 用法时使用。用户要 HTML 网页幻灯（网页放映/分享）时不用本 skill（交给 magic-deck）；「做 PPT/演示文稿」未言明产出形态时先 AskUserQuestion 二选一（.pptx 可编辑文件 → 本 skill；HTML 网页幻灯 → magic-deck），不擅自默认。
 allowed-tools: ["Bash", "Read", "Write", "Edit"]
 disable-model-invocation: false
 ---
@@ -54,7 +47,7 @@ disable-model-invocation: false
 3. **封面/结尾截图**（无现成素材时）→ 读 `resources/cover-template.html` 说明：复制模板到临时目录 → 替换 `COVER` 对象（title/subtitle/info/stats 或 mode:closing）→ Chrome headless 截图 1280x720（macOS：`/Applications/Google Chrome.app/Contents/MacOS/Google Chrome --headless --disable-gpu --no-sandbox --hide-scrollbars --screenshot=cover.png --window-size=1280,720 --virtual-time-budget=3000 "file:///<临时html>"`；Windows 按序探测 chrome.exe/msedge.exe，URL 用 node url.pathToFileURL）
 4. **生成 pptx**：写 data.json → `cd <skill目录> && node resources/pptx-builder.js --data <data.json绝对路径> --out <DIR>/<文件名>.pptx` → 输出 `PPTX_OK <路径>`
 5. **交付前自检**（硬门禁，不可跳过）：文件存在、大小 > 20KB；`unzip -l <pptx>` 校验——`ppt/slides/slideN.xml` 数量与 data.json pages 数一致、每页 slide XML 均存在且非空；builder 已报 `PPTX_OK` 才算通过。未通过 → 修 data.json 后重跑 builder，禁止跳过直接交付
-6. **落盘与打开**：按配置 DIR 落盘；`OPEN_PPTX: true` 时打开（macOS：`open <pptx>`；Windows：`start <pptx>`）
+6. **落盘与打开**：按配置 DIR 落盘；`OPEN_PPTX: true` 时打开（macOS：`open <pptx>`；Windows：`start <pptx>`）；落盘完成后对话回复必须向用户报告落盘位置：pptx 文件完整路径（如「已落盘到 ~/reports/月度汇报-202611.pptx」），并注明是否已自动打开（OPEN_PPTX=false 时注明未打开）
 7. **使用咨询**（用户只问「登台怎么用」「报告转 PPT 怎么用」等用法、未要求生成）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「登台 deck-stage 使用指南」），不执行任何生成动作
 
 
@@ -76,7 +69,7 @@ DIR（落盘根目录，DIR_MAC/DIR_WIN 双键）、THEME（tech/biz/mono/light/
 
 `user-config.md` 头部有 `CONFIG_VERSION` 字段，声明配置结构版本。本 skill 当前要求版本为 2。每次执行前先读 user-config.md：
 
-1. 若 CONFIG_VERSION 缺失或小于当前要求版本：先将旧 `user-config.md` 备份为 `user-config.md.bak-<时间戳>`
+1. 若 CONFIG_VERSION 缺失或小于当前要求版本：先将旧 `user-config.md` 备份为 `user-config.bak-<时间戳>.md`
 2. 按版本迁移规则迁移字段（新增字段补默认值、改名字段按映射改名、删除字段保留在备份并在对话中提示用户）
 3. 更新 `CONFIG_VERSION` 为当前版本
 4. 对话告知用户「配置已升级到 vN：新增 X、改名 Y」
@@ -85,7 +78,7 @@ DIR（落盘根目录，DIR_MAC/DIR_WIN 双键）、THEME（tech/biz/mono/light/
 
 **无法迁移项处理**（值域失效 / 语义漂移）：三绝不——绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话。
 
-升级技能时 user-config.md 不会被覆盖（官方更新另存 `user-config.md.upstream` 对照文件）。
+升级技能时 user-config.md 不会被覆盖（官方更新另存 `user-config.upstream.md` 对照文件）。
 
 ## 规则速览
 
@@ -109,3 +102,13 @@ DIR（落盘根目录，DIR_MAC/DIR_WIN 双键）、THEME（tech/biz/mono/light/
 - **落盘防覆盖**：同名 pptx 已存在时加日期后缀（如 `-1106`），不覆盖旧文件
 - **零外部网络**：生成全程离线（截图用本地 Chrome/Edge headless，依赖本地 node_modules），pptx 双击即开
 - **未授权目录不写**：DIR 不存在或不可写时停下问用户，不猜路径
+
+
+---
+
+## 🔍 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/deck-stage/resources/cover-template.html

@@ -21,7 +21,7 @@
   body{
     width:1280px; height:720px; overflow:hidden; position:relative;
     background:var(--bg); color:var(--text);
-    font-family:"PingFang SC","Microsoft YaHei","Source Han Sans SC",sans-serif;
+    font-family:"Source Han Sans SC",sans-serif;
   }
   /* 三层科技底纹（静态） */
   .bg-grid{ position:absolute; inset:0;