skill-forge-hub 1.0.7 → 1.2.0

package/release-notes/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/release-notes/resources/usage-guide.md

@@ -0,0 +1,25 @@
+# 发版说明生成器使用指南
+
+## 能做什么
+
+把 git 两个版本标签之间的提交，变成一份**人能读的发版说明**——自动分类归纳（新功能/修复/文档/优化），按用户视角改写（做了什么 + 带来什么），产出中英双语 RELEASE 文件与 CHANGELOG 条目，并附 npm 发布前自检清单。
+
+## 怎么用
+
+1. 说「**写发版说明**」或「**生成 release notes**」→ 我先读配置、收集 git 提交
+2. 我可顺口补充口径：「从 v1.0.7 到 v1.0.8」「只看最近两周」「聚焦 CLI 与文档」
+3. 口述本期要点（改了什么大方向）→ 与提交合并归纳
+4. 产出：RELEASE-{tag}.md（中英双语）+ CHANGELOG 条目 + 发布自检清单，落盘后报路径
+
+## 可改配置（user-config.md）
+
+- `REPO`：仓库根目录（默认当前目录向上探测）
+- `LANG`：zh / en / both
+- `CHANGELOG_FILE` / `REL_DIR`：落盘位置
+- `STATS`：是否附提交统计
+- `SCOPE_HINT`：发版说明聚焦主题
+
+## 使用提示
+
+- 没有 tag 时我会先问口径，不擅自假设
+- 每个版本发版前顺手跑一遍，CHANGELOG 永不欠账

package/release-notes/resources/write.md

@@ -0,0 +1,27 @@
+# 分类与改写（阶段 2-3）
+
+## 分类规则
+
+| 类型 | 归属 | 说明 |
+|:---|:---|:---|
+| feat | 🚀 新功能 | 用户可感知的新能力 |
+| fix | 🐛 修复 | bug 修复，说明修了什么、影响什么场景 |
+| docs | 📝 文档 | 文档增改（含示例、指引页） |
+| perf | ⚡ 优化 | 性能 / 体验优化 |
+| refactor | ♻️ 重构 | 结构改造（对外行为不变） |
+| breaking | 💥 破坏性变更 | 单独置顶，必须写明迁移方式 |
+| chore | 杂项 | 依赖 / 构建 / 琐碎项，一句话带过或省略 |
+
+## 改写纪律（用户视角）
+
+- 每条「**做了什么 + 带来什么**」：如「新增 skill-forge update 命令：升级时自动备份用户配置并三选一，用户改动不再被覆盖」
+- 同类提交合并为一条；每类 1-5 条；无价值的 chore 直接忽略
+- 禁止照抄 commit message 原文当说明；禁止流水账式逐条罗列
+- SCOPE_HINT 非空时聚焦该主题归纳，其余一句话带过
+
+## 落盘
+
+1. **RELEASE-{tag}.md**（REL_DIR 下，无 tag 用 RELEASE-{日期}.md）：顶部「版本 + 日期 + 一句话主题」，正文按分类列条目，底部附统计（STATS: true 时）
+2. **CHANGELOG 条目**：在 CHANGELOG_FILE 顶部（现有版本标题行上方）插入「## {version}（{日期}）」+ 条目；LANG: both 时同步生成 / 更新 CHANGELOG.en.md
+3. 双语时两份排版结构一致，术语对照一致；对话中照常输出发版说明正文
+4. **落盘完成后对话报告落盘位置**：完整路径清单（RELEASE 文件 + CHANGELOG 文件），并注明是否已插入 CHANGELOG

package/release-notes/user-config.md

@@ -0,0 +1,15 @@
+# user-config.md（本文件不会被 skill 升级覆盖，你的修改永久保留）
+# 官方配置更新时，另存 user-config.upstream.md 对照文件，可手动合并新配置点
+
+```yaml
+CONFIG_VERSION: 1  # 配置结构版本，skill 升级迁移依据
+
+# 提交收集口径
+REPO: auto          # git 仓库根目录；auto = 当前工作目录向上探测 .git；也可写绝对路径
+SCOPE_HINT:         # 可选：本次发版主题一句话（如「发版说明聚焦 CLI 与文档」），空 = 全量归纳
+
+# 产出形态
+LANG: both          # 说明语言：zh / en / both（双语两份）
+CHANGELOG_FILE: CHANGELOG.md   # 条目插入位置（相对 REPO 根）；both 时同步生成 CHANGELOG.en.md
+REL_DIR: releases/  # RELEASE-{tag}.md 落盘目录（相对 REPO 根，不存在则创建）
+STATS: true         # 是否附提交统计（提交数 / 净增删行数 / 提交者分布）

package/skill-doctor/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: skill-doctor
+description: 给已安装的技能做全身体检（frontmatter 完整性 / resource 引用可达 / 配置版本与保护机制 / 触发词 / 占位符残留 / HTML 技能的字体脱敏与产物版本戳），输出三段式体检报告（✅ 健康 / ⚠️ 警告 / 🟡 问题）。当用户请求体检技能、检查技能健康度、skill 体检、检查我的技能时使用。
+allowed-tools: Bash, Read
+disable-model-invocation: false
+---
+
+# 技能体检（skill-doctor）
+
+给技能做全身体检：扫描发现 → 逐项检查 → 三段式报告，与 meta-forge 形成「造 + 检」闭环。
+
+## 生成流程
+
+0. **读用户配置**（TARGET/CHECKS/FIX）→ 先 Read 同目录 `user-config.md`
+1. **扫描**（目标目录技能发现，逐技能定位 SKILL.md / user-config.md / resources/）→ 读 `resources/checks.md`
+2. **逐项检查**（通用项 + HTML 技能专属项）→ 读 `resources/checks.md`
+3. **体检报告**（三段式 ✅ / ⚠️ / 🟡 + 修复建议）→ 读 `resources/report.md`
+4. **使用咨询**（用户只问「技能体检怎么用」等用法、未要求体检）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「技能体检使用指南」），不扫描、不检查
+
+## ⚙️ 配置与自定义
+
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（TARGET/CHECKS/FIX）都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.upstream.md` 对照文件，可按需手动合并新配置点。
+
+## 配置版本机制（升级保护）
+
+本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明不一致：
+
+1. 先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）
+2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
+3. 更新 CONFIG_VERSION 为当前版本
+4. 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」
+
+升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
+## 文档同步自检纪律（维护者必读）
+
+修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（字段名 / 流程节点 / 模板名改名时新旧词全仓核对，旧词零残留才算完成）。
+
+
+## 规则速览
+
+- 只查不改（FIX: ask 时先列修复建议问用户，获准才动；off 时纯报告）
+- 检查项与 forge-rules.md 验证环对齐：静态门禁逐项映射，不另立标准
+- 报告三段式：✅ 健康 / ⚠️ 警告（能用但建议修）/ 🟡 问题（影响使用必修）；每项附文件与行级定位
+- 体检目录按 TARGET 探测：未指定时列出发现的技能目录让用户确认范围
+
+---
+
+## 🔍 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/skill-doctor/resources/checks.md

@@ -0,0 +1,27 @@
+# 扫描与逐项检查（阶段 1-2）
+
+## 扫描
+
+TARGET: auto 时按序探测技能目录（~/.qoder-cn/skills → ~/.claude/skills → ~/.cursor/rules → 当前项目 .agents/skills），汇总发现清单（技能名 / 目录 / 有无 SKILL.md）展示给用户确认范围；指定目录时直接扫描该目录。
+
+## 检查项（CHECKS: full）
+
+### 通用项（每个技能）
+
+1. **frontmatter 完整性**：name 与目录名一致且非占位符；description 非空且含触发词；allowed-tools 存在
+2. **resource 引用可达**：SKILL.md 中每个 `读 resources/xxx.md` 的文件真实存在（grep 提取 → ls 核对）
+3. **配置标准**：user-config.md 存在且含 `CONFIG_VERSION:` 声明 + 「升级不会被覆盖」说明；SKILL.md 含「配置版本机制」节
+4. **机制节齐全**：SKILL.md 含使用咨询接线（读 usage-guide.md）+ 文档同步自检纪律节
+5. **旧词零残留**：SKILL.md 与 resources 全文 grep 占位符（skill-name / TODO / REF- 残留）与废弃字段名
+
+### HTML 产出技能专属项（含 reference.html 的技能）
+
+6. **reference 双轨**：resources/reference.html 存在；SKILL.md 流程节点标注先 Read reference.html
+7. **字体零侵权**：reference.html 全文 grep 品牌字体（PingFang/YaHei/苹方/雅黑/apple-system）零出现；无 CDN 外链（@import / https:// 资源引用）
+8. **多文件隔离**（页面有 localStorage 记忆时）：grep 所有 localStorage 键——带命名空间拼接（内嵌 ID），固定键零残留；HTML 头部含 `<meta name="{前缀}-id">` 且 content 为合法 UUID v4
+9. **产物版本戳**：reference.html 头部含 `<meta name="sf-template" content="{技能名}@N">`（N≥1）；SKILL.md 含「产物升级（回炉）」节与主动提示语
+10. **入场动画兜底**：含滚动入场动画时脚本有 2s 兜底强制全显代码
+
+### slim（核心项）
+
+只跑通用项 1-3，其余跳过并在报告注明。

package/skill-doctor/resources/report.md

@@ -0,0 +1,26 @@
+# 体检报告（阶段 3）
+
+## 报告结构
+
+```
+# 技能体检报告（{日期}）
+
+## 总览
+体检范围：{目录}｜技能 {N} 个｜✅ 健康 {a} ｜⚠️ 警告 {b} ｜🟡 问题 {c}
+
+## ✅ 健康
+- {技能名}：全项通过
+
+## ⚠️ 警告（能用但建议修）
+- {技能名}：{问题描述} → {文件}:{行} → 建议 {修复方式}
+
+## 🟡 问题（影响使用必修）
+- {技能名}：{问题描述} → {文件}:{行} → 建议 {修复方式}
+```
+
+## 纪律
+
+- 每条结论附文件与行级定位（grep -n 结果），不写「可能有问题」这类无定位的猜测
+- 检查脚本输出（grep/ls）作为证据附在报告尾部「验证证据」节
+- FIX: ask 时报告末尾列「可顺修清单」AskUserQuestion 让用户选；获准后逐项修并复检该项
+- 报告落盘到 TARGET 目录 `skill-doctor-report-{日期}.md`；**落盘后对话报告报告路径**