skill-forge-hub 1.0.7 → 1.2.0

package/daily-report/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/daily-report/user-config.md

@@ -2,7 +2,7 @@
 
 > 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
 > 本文件始终保留你的版本——落盘目录、格式、角色画像、自定义模板放心改。
-> 官方升级若带来新配置点，会另存 `user-config.md.upstream` 对照文件到同目录，
+> 官方升级若带来新配置点，会另存 `user-config.upstream.md` 对照文件到同目录，
 > 你按需查看并手动合并新配置点到本文件。
 
 

package/data-prepper/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: data-prepper
+description: 把 Excel/CSV/JSON 散装数据清洗为结构化数据（JSON/CSV 落盘）并生成数据概览报告（行数 / 字段 / 分布 / 异常值 + 清洗变更清单）。当用户请求整理数据、清洗数据、xlsx 转结构化、数据预览、数据整备时使用。
+allowed-tools: Bash, Read, Write
+disable-model-invocation: false
+---
+
+# 数据整备（data-prepper）
+
+散装数据进、结构化数据出：读取 → 清洗（规则明示、不猜不编）→ 结构化落盘 → 概览报告。
+
+## 生成流程
+
+0. **读用户配置**（OUT_FORMAT/CLEAN_PRESET/DIR/REPORT/ID_FIELDS）→ 先 Read 同目录 `user-config.md`
+1. **读取数据**（xlsx/csv/json 格式探测与解析）→ 读 `resources/read-data.md`
+2. **清洗**（去重 / 去空格 / 类型规整 / 缺失值策略，每条操作留痕）→ 读 `resources/clean-rules.md`
+3. **结构化落盘**（JSON / CSV）→ 读 `resources/clean-rules.md`
+4. **概览报告**（数据画像 md：行数列数 / 字段表 / 分布 / 异常值 / 清洗变更清单）→ 读 `resources/overview.md`
+5. **使用咨询**（用户只问「数据整备怎么用」等用法、未要求处理数据）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「数据整备使用指南」），不读取、不清洗、不落盘
+
+## ⚙️ 配置与自定义
+
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（OUT_FORMAT/CLEAN_PRESET/DIR/REPORT/ID_FIELDS）都在该文件中，以它为准。升级技能时 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 全文核对相关关键词在各文件间一致（字段名 / 流程节点 / 模板名改名时新旧词全仓核对，旧词零残留才算完成）。
+
+
+## 规则速览
+
+- 数据零损失：原始文件永不修改；清洗结果写新文件；每步清洗操作记录进变更清单
+- 不猜不编：缺失值留空并标注，禁止编造填充；语义不明先与用户确认再动
+- 清洗规则明示：动手前把将执行的清洗项列给用户看，用户改口即调整
+- 脱敏纪律：数据中的真实姓名 / 手机号 / 邮箱在报告中用掩码展示，落盘文件保持原样不擅自脱敏
+
+---
+
+## 🔍 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/data-prepper/resources/clean-rules.md

@@ -0,0 +1,18 @@
+# 清洗与结构化落盘（阶段 2-3）
+
+## 清洗预设（CLEAN_PRESET）
+
+**standard（标准）**：去空行 → 去首尾空格 → 去除全空列 → 空单元格留空不编造 → 数值列类型规整（去千分位逗号 / 百分号转小数按列语义定，语义不明不动）→ 按 ID_FIELDS 去重（保留首条）
+**minimal**：只转格式不洗内容，原样落盘
+
+## 清洗纪律
+
+- **动手前列清单**：将执行的清洗项逐条列出（「去重：按 姓名+日期 主键，删除 N 条」）给用户看，改口即调整，确认后执行
+- **变更留痕**：每条清洗操作记录「做了什么 + 影响多少行」进变更清单（最终并入概览报告）
+- **原始文件永不修改**：清洗结果写新文件；不编造缺失值；语义不明先问
+
+## 结构化落盘
+
+- OUT_FORMAT: json → `cleaned/data.json`（数组结构，字段保持原表头清洗后的名称）；csv → `cleaned/data.csv`（UTF-8 BOM 便于 Excel 打开）；both 两份都出
+- DIR: auto 时落盘到源文件同目录 `cleaned/` 子目录；目录已存在直接复用
+- **落盘完成后对话报告落盘位置**：完整路径 + 行数列数 + 清洗变更清单摘要

package/data-prepper/resources/overview.md

@@ -0,0 +1,17 @@
+# 数据概览报告（阶段 4）
+
+REPORT: true 时生成 `cleaned/overview.md`，结构：
+
+## 报告结构
+
+1. **数据画像**：源文件 / 清洗后行数列数 / 字段表（字段名 / 类型 / 非空率 / 示例值）
+2. **分布摘要**：关键列（数值列给 min/max/均值，枚举列给 Top 取值计数）
+3. **异常值清单**：空值占比高的列 / 类型异常单元格 / 疑似重复行（逐条列位置与内容）
+4. **清洗变更清单**：每条操作「做了什么 + 影响多少行」
+5. **口径备注**：本次使用的清洗预设与用户确认过的口径
+
+## 纪律
+
+- 报告不编数据：所有数字来自实际解析结果
+- 脱敏：报告中真实姓名 / 手机号 / 邮箱用掩码（张*、138****1234）；落盘数据文件保持原样
+- 落盘后对话报告报告路径；用户说「只要数据不要报告」时 REPORT 本次按 false 处理（不写配置）

package/data-prepper/resources/read-data.md

@@ -0,0 +1,13 @@
+# 读取数据（阶段 1）
+
+## 格式探测与解析
+
+1. **xlsx/xls**：优先 `python3 -c "import openpyxl"` 探测；可用则 openpyxl 读全部 sheet（表名 + 行数列数 + 前 5 行采样）；不可用则 LibreOffice `soffice --headless --convert-to csv` 兜底（多 sheet 取第一个，对话注明）
+2. **csv**：编码探测——先试 utf-8，失败试 gbk/gb18030；`python3` 读行数与表头 + 前 5 行采样；分隔符探测（逗号 / 制表符 / 分号）
+3. **json**：直接 Read 或 python3 json.load；数组 / 对象两种结构分别处理（对象按顶层键拆表）
+
+## 采样预览
+
+- 先输出结构画像：格式、表（sheet）清单、行数列数、表头清单、前 5 行采样
+- 大文件（> 5000 行）只采样首尾各 5 行 + 中间 5 行，禁止全文 Read 撑爆上下文
+- 把结构画像展示给用户，等确认口径（哪个 sheet / 哪些列进结构化）后再进清洗