skill-forge-hub 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 windfallsheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# SkillForge · 技能锻造坊
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 一处集中收纳「AI 手艺」的工坊——把日复一日的重复劳作，锻造成一句指令就能完成的顺手工具。坊中每一件技能都是一份写给 AI 的手艺说明，一句自然语言即可唤起，按既定工序产出标准化成果；手艺与宿主无关——换一份薄薄的 frontmatter 信封，就能从一位 AI 助手带去另一位。
+
+**SkillForge（技能锻造坊）** is a curated collection of AI craft skills — repetitive daily work, forged into tools that answer with a single command. Each skill is a set of craft instructions written for the AI: one natural-language request sets it in motion, and a polished, standardized deliverable comes out the other end — daily and weekly reports, documents dressed into beautiful pages, deployment pipelines, and more. The craft is host-agnostic — a thin frontmatter envelope is all it takes to carry it from one AI assistant to another. Everything here is built for high-frequency everyday work — reusable across projects, dependable on any machine, battle-tested by repeated use.
+
+所有技能均以 SKILL.md 为入口——frontmatter、生成流程、用户可改配置留在入口，重内容按生成阶段拆到 resources/ 或平铺辅助文件（如 design-system.md、scripts/），AI 执行到对应阶段才读取，降低常驻上下文占用。
+
+## 技能分类
+
+按「技能最终产出什么」归类，一个技能只归一类；分类只用于本仓库组织与导航，安装时始终平铺复制到目标 AI 助手的技能目录，与分类无关。
+
+| 分类 | Category | 说明 | 收录技能 |
+|:---|:---|:---|:---|
+| 报表汇演 | Reports | 聚合 git 与工程数据，按周期产出报告（日报 / 周报 / 月报） | daily-report、weekly-report |
+| 文档装裱 | Documents | 文档转换与美化：Word / Markdown / 纯文本 → 精美 HTML + 逐章截图 | article-to-html |
+| 工程提效 | Engineering | 开发流水线技能：部署、发布、审查、测试、文档 ↔ 规格互转 | spec-doc2spec、spec-spec2doc |
+| 数据整备 | Data | Excel / CSV / 图表、数据清洗与模板整理 | （规划中） |
+| 沟通协作 | Communication | 邮件起草、会议纪要、通知周知 | （规划中） |
+| 技能自造 | Meta | 锻造技能本身的元技能（创建技能 / 插件） | （规划中） |
+
+## 技能清单
+
+| 技能 | 分类 | 目录 | 说明 |
+|:---|:---|:---|:---|
+| daily-report | 报表汇演 | [daily-report/](daily-report/) | 聚合各仓库 git 提交 + 会话口述生成日报（今日完成任务/明日计划/风险阻塞点），支持自然语言日期（今天/昨天/上周三/10月20号）、连续多日批量、纯文字/图片/文件整理、自定义模板、12 行业词条 |
+| weekly-report | 报表汇演 | [weekly-report/](weekly-report/) | 同上生成周报（本周完成任务/下周计划/风险阻塞点 + 本周概览卡），周结束日可配置（默认周五，可改周日等），支持自然语言周定位（本周/上周/10月第2周/节假日锚定） |
+| article-to-html | 文档装裱 | [article-to-html/](article-to-html/) | Word / Markdown / 纯文本 → 精美独立 HTML（思源黑体 + Roboto 商用免费字体，图表 HTML/CSS 重绘），逐章截图（Retina 2x）；现成 HTML 可直接截图或先美化 |
+| spec-doc2spec | 工程提效 | [spec-doc2spec/](spec-doc2spec/) | Word / Markdown 需求文档转结构化需求切片；自动检测 Pandoc，未装引导跨系统安装 |
+| spec-spec2doc | 工程提效 | [spec-spec2doc/](spec-spec2doc/) | Markdown 规格导出为 Word / PDF 交付文档；自动检测 Pandoc，未装引导跨系统安装 |
+
+## 安装
+
+### 方式一：npm 全局安装（推荐）
+
+```bash
+npm i -g skill-forge-hub
+skill-forge ls        # 列出全部技能与说明（只读）
+skill-forge init      # 交互式挑选技能，自动探测并安装到 AI 助手技能目录
+```
+
+非交互 / 指定目录场景：
+
+```bash
+skill-forge init --target ~/.claude/skills --skills daily-report,weekly-report
+```
+
+### 方式二：手动复制
+
+将技能目录复制到你所用的 AI 助手的技能目录（支持 SKILL.md 格式、本地加载技能的助手均可）：
+
+```bash
+cp -R daily-report weekly-report article-to-html <你的 AI 助手技能目录>/
+cp -R spec-doc2spec spec-spec2doc <你的 AI 助手技能目录>/   # 仅 SpecCore 用户需要
+```
+
+复制后直接说「写日报」「写周报」或丢给它一个文档即可触发；问「日报怎么用 / 周报怎么用」输出使用说明。
+
+## 目录结构
+
+```
+.
+├── README.md                    # 本文件（双语介绍 + 技能分类）
+├── template/                    # 新技能模板（薄入口 + resources 拆分规范）
+├── article-to-html/
+│   ├── SKILL.md                 # 文档 → 精美 HTML 完整流程 + 逐章截图
+│   ├── design-system.md         # 设计系统（字体 / 配色 / 排版 / 图表重绘）
+│   └── scripts/                 # 字体安装 / docx 抽取 / 字体内联脚本
+├── daily-report/
+│   ├── SKILL.md                 # 薄入口：frontmatter + 生成流程 + 默认配置 + 自定义模板
+│   └── resources/               # 重内容按生成阶段拆分，AI 按需读取
+│       ├── usage-guide.md       # 📖 使用说明（咨询应答的原样输出源）
+│       ├── date-parsing.md      # 🗓 日期解析（自然语言优先）
+│       ├── data-collection.md   # 📥 数据收集（仓库表 / git 命令 / 行数口径）
+│       ├── content-rules.md     # ✍️ 内容规则（聚合来源 / 补充任务 / 纯文字模式 / 输出格式 / 写作风格）
+│       ├── industry-dictionary.md # 🏭 行业适配（12 行业职业词典）
+│       └── disk-and-html.md     # 💾 本地落盘 / HTML 样式 / content-png 截图规范
+├── spec-doc2spec/
+│   └── SKILL.md                 # 文档 → 需求规格（委托 SpecCore ask 引擎）
+├── spec-spec2doc/
+│   └── SKILL.md                 # 规格 → Word / PDF（委托 SpecCore ask 引擎）
+└── weekly-report/
+    ├── SKILL.md
+    └── resources/               # 结构同 daily-report，周报专属差异：
+                                 #   WEEK_END 周结束日 / 周定位解析 / 本周概览卡 / 用时 X.XD（1D=8H）
+```
+
+## 拆分规范（薄入口 + resources）
+
+- **SKILL.md 只保留**：frontmatter、生成流程总览（每步标注读哪个 resource）、「⚙️ 默认配置」「📝 自定义模板」（用户手改的配置必须留在入口）、规则速览（3-5 条硬性规则）
+- **resources/ 一文件一职责**：按生成阶段拆分，SKILL.md 流程节点标注 `读 resources/xxx.md`；每份 resource 独立可读，不互相引用
+- **咨询应答**：用户只问用法不要求生成时，读 `resources/usage-guide.md` 原样输出（首行标题按技能改为「XX生成器使用指南」）
+- **新技能按 `template/` 结构创建**，目录名 = 技能名（英文短横线），并归入上方「技能分类」表对应分类
+- **已有技能按各自结构维护**：article-to-html 采用 SKILL.md + design-system.md + scripts/ 平铺结构；spec-doc2spec / spec-spec2doc 为单文件薄技能（委托 SpecCore ask 引擎）
+- **通用原则**：零外部依赖（禁 CDN / 外链，内网离线双击可开）、双系统兼容（macOS / Windows）

package/annual-report/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: annual-report
+description: 生成年度总结（默认五段式：年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划），适配各行业（内置 12 行业职业词典，可指定角色身份）。数据来源灵活：各仓库 git 全年提交聚合、纯文字、图片或文件整理，无 git 也适用。支持自定义模板（可永久或临时指定）。支持自然语言指定年度（2026年/去年/近一年/最近12个月等）。当用户请求写年度总结、年终总结、年度复盘、年总结、/annual-report，或询问年度总结用法（年度总结怎么用/年度总结使用说明）时使用。
+allowed-tools: Bash, Read, Write
+disable-model-invocation: false
+---
+
+# 年度总结生成
+
+聚合各仓库 git 全年提交 + 本次会话口述内容生成五段式年度总结（年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划），对话输出 md 正文 + 落盘 md/txt/html/content-png 并自动打开 html。
+
+## 生成流程
+
+0. **读用户配置**（DISK/FORMATS/DIR/OPEN_HTML/TEMPLATE/ROLE/CONFIRM、自定义模板）→ 先 Read 同目录 `user-config.md`
+1. **解析年度**（自然语言 → 目标年度区间）→ 读 `resources/date-parsing.md`
+2. **收集数据**（git 全年提交聚合 + 会话口述 + 口头补充，合并去重）→ 读 `resources/data-collection.md`
+3. **内容归类与润色**（五段式结构 / 聚合来源 / 纯文字模式 / 输出格式 / 写作风格）→ 读 `resources/content-rules.md`
+4. **行业词条**（话术含职业词时按词典取词）→ 读 `resources/industry-dictionary.md`
+5. **落盘与截图**（md/txt/html/content-png + 自动打开 html）→ 读 `resources/disk-and-html.md`
+6. **使用咨询**（用户只问「年度总结怎么用」等用法、未要求生成）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「年度总结生成器使用指南」），不收集 git、不生成报告、不落盘、不开浏览器
+
+## ⚙️ 配置与自定义模板
+
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（DISK/FORMATS/DIR/OPEN_HTML/TEMPLATE/ROLE/CONFIRM）与自定义模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留。
+
+## 规则速览
+
+- 五段式骨架行业无关：年度概览（一句话 TL;DR + 3-6 项核心数据卡）/ 核心成果与里程碑（按季度 Q1-Q4 时间线 8-12 项，每项 20-40 字）/ 经验与成长（3-5 条）/ 不足与反思（2-4 条三环：问题+影响+改进）/ 新年展望与规划（3-5 项目标，各带量化指标与分季度行动节点）
+- 中文顿号序号（1、2、3）；段内无内容写「暂无」；量化优先，杜绝空话套话
+- 行业术语/指标/里程碑主题/风险话术按 `resources/industry-dictionary.md` 职业词典取词（未提职业按 ROLE 画像）
+- 完整规则（聚合来源 / 纯文字模式 / 写作风格约束 / 使用提示）见 `resources/content-rules.md`

package/annual-report/resources/content-rules.md

@@ -0,0 +1,40 @@
+# 内容规则（五段式）
+
+五段式骨架行业无关（任何职业通用），术语与指标由职业词典适配。
+
+## 段结构
+
+**段一 年度概览**
+- 一句话 TL;DR：全年工作的总体判断（如「交付密集的一年：全年完成 3 个版本迭代，代码库净增 4.2 万行」）
+- 核心数据卡 3-6 项：年度最关键的量化指标（按职业词典），每项：数字 + 单位 + 标签
+- 可带同比小字（「较去年：+18%」）
+
+**段二 核心成果与里程碑**
+- 按季度（Q1/Q2/Q3/Q4）时间线排列 8-12 项，每项：成果描述 20-40 字 + 所属季度 + 量化结果
+- 里程碑事件优先（版本发布/项目上线/重大交付），日常任务不逐条列
+- 未过完的季度（如写到 Q4 中途）注明「截至当前」
+
+**段三 经验与成长**
+- 3-5 条，每条一句话：沉淀的方法/技能/认知（「沉淀了 XX 方法」「掌握了 XX」）
+- 强调可复用（对未来有用的才写），不写「完成了 XX」这类成果句（归段二）
+
+**段四 不足与反思**
+- 2-4 条三环结构：问题（是什么）+ 影响（导致什么）+ 改进（明年怎么改）
+- 具体诚实，不写「还需努力」这类空话；无真实不足才写「暂无」
+
+**段五 新年展望与规划**
+- 年度目标 3-5 项：目标描述 + 可量化指标（「完成 XX，年底达到 XX」）
+- 每项目标带分季度行动节点（Q1 起…Q2 完成…）
+- 目标与段四不足的改进方向呼应
+
+## 写作风格
+
+- 中文顿号序号（1、2、3），段内条目数按上述区间；不足处写「暂无」
+- 量化优先：能带数字的带数字，估算值注明「约」
+- 语言朴素具体，杜绝「再接再厉/砥砺前行」等套话；全年视角有判断、有取舍，不是流水账
+- md/txt 正文含生成时间行（精确到时分秒，如 2026-11-06 19:10:38）
+
+## 聚合来源与纯文字模式
+
+- git 聚合来源（提交统计/里程碑）与口述来源（大事/感悟）合并后按段归类；两者矛盾时量化以 git 为准
+- 纯文字/图片/文件整理模式（无 git）：用户提供什么用什么，按五段结构归类；素材不足的段写「暂无」并提示用户可补充素材

package/annual-report/resources/data-collection.md

@@ -0,0 +1,25 @@
+# 数据收集（年度）
+
+三种来源合并去重：git 全年聚合为主、口述与文件为辅；无 git 也适用（纯文字/图片/文件整理）。
+
+## 1. git 全年聚合（有仓库时）
+
+- 遍历仓库清单（见 disk-and-html.md 的仓库清单节），对每仓执行全年统计：
+  - 总提交数：`git log --since={区间起} --until={区间止} --oneline | wc -l`
+  - 增删行数：`git log --since=... --until=... --numstat --pretty=tformat: | awk` 汇总 add/del
+  - **先剔除生成物路径**（.speccore/code-graph/、node_modules、dist、*.lock 等，用 grep -vE 按制表符+路径过滤），否则 graph.json 之类单文件可贡献数十万行噪音
+  - 月度分布：`git log --since=... --until=... --format='%ad' --date=format:'%Y-%m' | sort | uniq -c`（12 个月柱图数据）
+  - 里程碑：`git tag` / `git log --merges --oneline` 提取版本发布与重要合并，读 tag 信息取版本号与日期
+- 仓库按系统取有效路径（macOS / Windows 双列表，空列跳过）
+
+## 2. 会话口述与文字材料
+
+- 用户口述的年度大事（「年初做了 X」「Q3 上了 Y」）逐条记录
+- 用户提供的总结草稿/文档（md/txt/docx）Read 提取要点；图片逐张 Read 识别内容
+- 聊天记录/周报/日报文件也可作为素材
+
+## 3. 合并去重与口径
+
+- 同一成果 git 数据与口述重合时合并为一条，量化以 git 统计为准、定性以口述为准
+- 无法量化的条目写定性描述，不编造数字
+- 年度核心指标（概览卡数据）优先取：总提交数/年度增删行数/里程碑数（研发），其它行业按职业词典量化指标

package/annual-report/resources/date-parsing.md

@@ -0,0 +1,18 @@
+# 年度解析
+
+把自然语言定位到目标年度区间。年度区间决定 git 统计范围与目录/文件名。
+
+## 定位规则
+
+| 用户说法 | 目标年度 | 区间 |
+|:---|:---|:---|
+| 2026年 / 今年 / 写个年度总结（未指定）| 当前自然年（如 2026）| 01-01 ~ 12-31（未过完则到「今天」）|
+| 去年 / 2025年 | 上一自然年 | 01-01 ~ 12-31 |
+| 近一年 / 最近12个月 / 近 12 个月 | 滚动 12 个月 | 今天 - 12 个月 ~ 今天 |
+| 2026 财年 | 财年（可追问起止月，如 3 月~次年 2 月；不追问则按自然年处理并注明）| 按起止月 |
+
+- 「今年」以当前系统日期为准（11 月写年度总结 → 区间 01-01 ~ 今天，标题注明「截至 2026-11」）
+- 目录：`{DIR}/annual-{YYYY}/`（滚动 12 个月用起始年，如 2025-11~2026-11 → annual-2025，目录内文件名仍按目标年度）
+- 文件名：`annual-report-{YYYY}.md/.txt/.html`、截图 `annual-report-{YYYY}-content.png`
+- 同名目录已存在时直接复用（不重建、不清空），仅覆盖 FORMATS 清单内的同名文件；目录内其它文件一律保留不动
+- 同一份年度总结重复生成默认直接覆盖；用户说「保留之前的/另存/不覆盖」时文件名追加时间戳（如 `annual-report-2026-1530.html`）

package/annual-report/resources/disk-and-html.md

@@ -0,0 +1,28 @@
+# 落盘与 HTML（年度版式）
+
+## 落盘
+
+- FORMATS 默认 [md, txt, html, content-png]：md/txt/html 文件名 `annual-report-YYYY.<格式>`、截图 `annual-report-YYYY-content.png`；txt 为纯文本版；DISK: false 时全部不落盘
+- 目录：`{DIR}/annual-YYYY/`（DIR 按系统取 DIR_MAC/DIR_WIN，不存在回退用户主目录下 reports）；目录已存在直接复用，只覆盖本清单内同名文件；目录内存在非本 skill 命名的其它文件时对话中提示用户「该目录内已有其它文件，本次年度总结已与它们并列存放，未做任何改动」
+- 对话中照常输出 md 正文（不受 FORMATS 影响）；OPEN_HTML: true 且落盘了 html 时自动打开浏览器（macOS：open <html文件>；Windows PowerShell：Start-Process <html文件>）
+- FORMATS 含 content-png 时生成内容区截图：只截五张分节卡片整体（年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划，不含头部标题区/复制按钮/页脚，四周保留对称合适的外边距约 40px 留白）；html 内置 `?shot=content` 参数（页面 JS 检测后隐藏 header-card/copy-wrap/footer、body 四周 padding 统一 40px，正常浏览不受影响）；用 Chrome headless 访问带参 URL 截图（路径按系统选：macOS=`/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`；Windows 按序探测 `C:\Program Files\Google\Chrome\Application\chrome.exe` → `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe` → `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`，经 node child_process 执行 `--headless --disable-gpu --no-sandbox --hide-scrollbars --user-data-dir=<临时目录> --screenshot=<png路径> --window-size=760,<估算高度> --virtual-time-budget=4000 "file:///<html路径>?shot=content"`（Windows 下 URL 写作 file:///C:/...，用 node url.pathToFileURL 生成），跑完删除临时目录；禁止用 `--headless=new`（单例模式会静默失败生成占位图）；若 Chrome 不存在则换 Edge（macOS=`/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge`；Windows=`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe` → `C:\Program Files\Microsoft\Edge\Application\msedge.exe`），都找不到时跳过截图并在对话注明）；高度按内容区估算（body 上下留白~80 + 概览节(标题45+数据卡~90+45) + 里程碑节(标题45+条目数×~65+40) + 成长节/反思节/展望节(各45+条目数×~70+40) + 各卡片 margin-bottom 18 + 余量~15，底部留白仅 body 下 padding 40px、与顶部对称），截图后用 Read 校验：五张卡片整体完整在图内、无头部/按钮/页脚残留、四周留白对称合适、不截断；底部留白过大减高度、截断加高度重截
+
+## HTML 年度版式（深蓝面板体系，与日报/周报同源）
+
+- 复用日报/周报深蓝面板视觉体系：背景 #0a1929 + SVG feTurbulence 微噪点（opacity .04）+ 三层科技底纹（.grid-pattern 60px 青色细网格 rgba(0,240,255,.03) + .stars 8 个 1-1.5px 星点白/青/紫/绿散落 + .scanlines 2px 周期扫描线 rgba(0,240,255,.015)）；禁用任何 CDN 与外部网络引用（@import、外链 CSS/JS/图片/网络字体一律禁止，页面必须公司内网离线双击可打开、零外部依赖）；字体全用系统本地字体栈 ui-monospace/'SF Mono'/SFMono-Regular/Menlo/Consolas；颜色全部用 CSS 变量统一色板（--cyan #0ea5e9、--bg #0a1929、--card #0b1e37、--border rgba(14,165,233,.15)、--text #bae6fd、--muted #5b7fa5、--green #14b8a6、--orange #f97316、--purple #6366f1、--rose #f43f5e）
+- 头部卡片：标题「YYYY 年度总结」+ 副标题（ROLE 画像或年度区间）+ 生成时间行；speccore ask 同款发光特效：四边 1px 青色浮光线 transparent→var(--cyan)→transparent 整条平移扫动（上 scanX 左→右、右 scanY 上→下、下 scanX-rev 右→左、左 scanY-rev 下→上，四线同周期 3s linear 单向平移，亮段完整穿越卡片后消失于两端界外，卡片 overflow:hidden 裁剪；禁止自创 background-position 滚动/常驻辉光/往返摆动/亮段半嵌常驻变体）+ 顶部光斑 cardGlow（radial-gradient ellipse at 50% 10% rgba(14,165,233,.25)→transparent 70%，opacity .5→1 + scale 1→1.6，transform-origin top center，3s 循环，头部与每张分节卡片内均放 .card-glow 层）+ 标题文字青色光晕呼吸（text-shadow 双圈 3s 循环）
+- 五张分节卡片（实心深蓝底 #0b1e37 + 8px 周期细密水平条纹 + 上下边缘 1px 微亮描边 #0f3350 + 圆角 6px + overflow:hidden + 保留阴影与 inset 内发光），左侧 8px 宽节色竖线贯穿整卡（box-shadow 0 0 12px 同色 30% 光晕），内容 padding-left 24px；节色：概览亮蓝 linear-gradient(180deg,#38bdf8,#0ea5e9) / 成果青绿 linear-gradient(180deg,#5eead4,#14b8a6) / 成长紫 linear-gradient(180deg,#a5b4fc,#6366f1) / 反思玫红 linear-gradient(180deg,#fda4af,#e11d48) / 展望橙 linear-gradient(180deg,#fdba74,#f97316)；节标题 18px 同色渐变 SVG 语义图标（概览=仪表盘、成果=奖杯、成长=上升箭头、反思=三角警示、展望=日历）+ 文字微光晕（h2 flex gap 10px，标题色=节色亮端，同色双圈发光字 3s 呼吸 secGlow 动画，仅节标题文字发光，SVG 图标不加）
+- 概览节：一句话 TL;DR 引言行 + 核心数据卡 3-6 张横排（.stat-card flex 均分：大数字 28px 渐变字 + 12px muted 标签 + 11.5px 同比小字「较去年：+18%」，上涨 --green 绿、下跌 --rose 红；数据卡左侧小色条同概览节色）
+- 里程碑节：纵向时间线（.timeline 左侧 2px 青色竖线 + 季度节点：Q1/Q2/Q3/Q4 圆形节点（节色渐变球 + 光晕，当前季度节点加呼吸动画）+ 右侧内容（成果描述 15px + 量化小字 12px 青灰 + 季度徽章 11px muted 胶囊）；季度内多条共用季度节点，条目间青色虚线分隔）
+- 成长节/反思节：条目沿用 3D 立体圆球序号徽章（28px 白字，径向渐变球面（受光点 circle at 30% 28%，浅亮→主色→深色）+ inset 右下内暗影 + ::before 左上椭圆高光点 + 底部投影与同色光晕；成长紫、反思玫红）；反思条三环展开：问题主行 + 影响行 12px 青灰「影响：xxx」+ 改进行 12px 青色「改进：」加粗前缀
+- 展望节：目标条目卡（目标描述 15px + 量化指标加粗 + 分季度行动节点小胶囊 11px（Q1 起…/Q2 完成…，muted 字 + 青色细边 rgba(14,165,233,.18) + 淡青底））
+- 年度提交月度柱图（研发词条；其它词条按职业词典图表主题）：.cb-col 12 根柱一月到十二月、.cb-bar width:24px 柱宽（太小显细弱）、柱高按当月提交数、position:relative 柱上带 .cb-tip hover 浮层「X月 · N 次提交」；置于里程碑节内时间线之后
+- 青色渐变 40px 大胶囊「一键复制」按钮（var(--cyan)→#0284c7，30px 青色光晕，hover 45px 光晕上浮；flex 居中布局，内置 16px 内联 SVG 双矩形复制图标（白色 currentColor 描边、图标与文字 gap 8px、禁用 emoji 图标），复制成功后图标切对勾、文字变「已复制」）；复制源必须用 txt 文件内容（含换行、无 #/##/> 等 Markdown 符号，严禁用 md 内容当复制源）；JS 用 navigator.clipboard.writeText，失败回退隐藏 textarea + document.execCommand('copy')（兼容 file:// 打开）
+- 入场动画：头部淡入下滑、五张卡片依次错峰上浮淡入（概览 0.13s/成果 0.26s/成长 0.4s/反思 0.54s/展望 0.68s）、按钮弹入；卡片入场动画 fadeDown/fadeUp/riseIn 的 fill-mode 必须用 backwards 严禁 both（both 使动画结束后最后一帧 transform:none 永久覆盖 hover 的 3D 偏转 transform，hover 偏转会完全失效）
+- hover 微交互：卡片上浮 translateY(-2px) + 阴影加深 + inset 发光增强、条目淡青底 rgba(14,165,233,.06)、时间线节点放大微旋、数据卡上浮、按钮上浮/按压回缩
+- 卡片级 3D 微倾斜（严禁全页级 mousemove 倾斜）：每张卡片 hover 时仅该卡片随鼠标偏转（perspective(900px) + rotateY(calc(var(--mx,0)*2.5deg)) rotateX(calc(var(--my,0)*-2.5deg)) ±1.25° 极轻微，与 hover 上浮合并写同一条 transform 严禁拆两条相互覆盖）；JS 对每张卡片监听 mousemove 计算卡内相对位置（(clientX-rect.left)/rect.width*2-1 归一化 -1~1）只更新该卡 --mx/--my，mouseleave 归零回正，transition transform .18s 平滑；移动端无 mousemove 保持 0 不倾斜
+- CRT 扫描光带（.scanband position:fixed、left:0/right:0、height:150px、linear-gradient(180deg,transparent,rgba(0,240,255,.03) 50%,transparent)、animation:scanMove 11s linear infinite（top -22%→112%）、pointer-events:none、z-index:998，置于 scanlines 之下一层）
+- 禁止写 @media (prefers-reduced-motion: reduce) 禁用动画的媒体查询块（用户系统开启减少动画时该块会禁用全部动效）
+- 页面 JS 需支持 `?shot=content` 参数（检测 location.search 含 shot=content 时给 header-card、copy-wrap、footer 设 display:none，body 四周 padding 统一 40px，供主体内容整体截图用、保证截图四周留白对称合适）
+- 页脚 10px muted 文字（无分隔线、不加边框），署名固定 GENERATED BY SPECCORE TEAM · <年度>（动态跟随目标年度，如 GENERATED BY SPECCORE TEAM · 2026）
+- 五段分节列表，条目保持中文顿号序号；md/txt 版同条目依次写，文本格式不变

package/annual-report/resources/industry-dictionary.md

@@ -0,0 +1,19 @@
+# 行业适配（职业词典）
+
+报告骨架（五段式/TL;DR/核心数据卡/里程碑时间线/反思三环）行业无关，只有「行业变量」随职业切换。用户对话中声明职业即按词典取词（如「帮我写份销售年度总结」→ 销售词条）；词典没有的行业走兜底。
+
+| 变量 | 研发 | 销售 | 运营 | 产品 | HR | 财务 | 市场 | 客服 | 项目/PMO | 行政 | 法务 | 设计 |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| 标题 | 研发年度总结 | 销售年度总结 | 运营年度总结 | 产品年度总结 | 人事年度总结 | 财务年度总结 | 市场年度总结 | 客服年度总结 | 项目年度总结 | 行政年度总结 | 法务年度总结 | 设计年度总结 |
+| 工作单元 | 提交/版本/PR | 拜访/商机/回款 | 活动/渠道/内容 | 需求/迭代/上线 | 招聘/培训/入离职 | 报表/对账/税务 | 投放/活动/线索 | 工单/会话/满意度 | 里程碑/需求变更/资源/评审 | 会务/采购/资产/证照 | 合同审核/诉讼/合规/知产 | UI稿/设计规范/走查/交付 |
+| 量化指标 | 提交数·行数·版本数 | 拜访数·商机数·回款额 | 曝光·转化·GMV | 交付数·上线数 | 简历数·到面率·入职数 | 凭证数·回款·预算执行率 | 投放额·线索数·ROI | 工单量·解决率·满意度 | 里程碑达成数·任务完成数·变更数 | 会务场次·采购完成数·资产盘点数 | 合同审核数·案件进展·合规项数 | 页面稿数·规范组件数·走查问题数 |
+| 里程碑 | 版本发布/架构升级 | 大客户签约/区域突破 | 爆款活动/渠道扩张 | 重大版本迭代/核心功能上线 | 组织变革/人才梯队建设 | 系统上线/审计通过 | 品牌战役/投放升级 | 服务体系搭建/满意度跃升 | 重点项目交付/流程建设 | 办公搬迁/年会/体系建设 | 重大案件胜诉/合规体系落地 | 设计系统/规范落地 |
+| 风险话术 | 阻塞点/技术债 | 竞争/预算审批 | 资源/渠道效果 | 需求变更/排期 | 用人缺口 | 资金/合规 | 渠道成本 | 舆情/高峰 | 范围蔓延/资源冲突 | 供应商延期/预算超支 | 合规风险/诉讼时效 | 需求反复/排期挤压 |
+
+- 用户角色画像：顶部「默认配置」的 ROLE 定义用户默认角色与主要工作内容（当前：全栈开发工程师（企业内技术开发））；未提职业时按 ROLE 画像取词（当前等价研发词条：git 全年聚合 + 提交/版本术语 + 提交数/行数/版本数指标 + 版本发布/架构升级里程碑）
+- 触发：话术含职业词（销售/运营/产品/HR/财务/市场/客服/项目/PMO/行政/法务/设计等）→ 标题、工作单元术语、量化指标、里程碑主题、风险话术全部按该词典词条生成
+- 临时换角色：说「以 XX 的身份写年度总结」（如「以销售经理的身份写」）→ 当次按该角色词条生成，不改配置
+- 永久换角色：说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 更新顶部 ROLE 配置（永久生效）；词典没有的角色按用户描述新增词条
+- 声明+临时指标覆盖：说「这次指标看签约额和回款」→ 词条 + 临时指标（仅当次）；说「以后都用这套指标」→ 固化进词典（永久）
+- 兜底：词典外的行业（工地施工、医生值班等）→ 骨架 + 用户素材（文字/图片/文件）现场生成词条（工作单元/指标/里程碑从素材提取），本次生效；说「记住这个行业」→ 固化为新词条
+- 行业/角色切换只换内容与指标，HTML 骨架/色板/动效/落盘规范全部不变；纯文字整理模式同样适用词典；优先级：临时角色声明 > 顶部 ROLE 配置 > 词典表

package/annual-report/resources/usage-guide.md

@@ -0,0 +1,26 @@
+# 年度总结使用指南
+
+## 能干什么
+
+把一年的工作沉淀成五段式年度总结：年度概览（一句话 + 核心数据卡）/ 核心成果与里程碑（季度时间线）/ 经验与成长 / 不足与反思 / 新年展望与规划。适配各行业：内置 12 行业职业词典，报职业自动换术语与指标；不报职业按你的默认角色画像生成。
+
+## 三种使用方式
+
+1. **git 全年聚合**（有代码仓库）：自动统计全年提交数、增删行数、月度分布、版本里程碑，结合你口述的大事生成
+2. **纯文字整理**：把年度大事、成果、感悟直接说给我或发文字
+3. **图片/文件整理**：发总结草稿、聊天记录、日报周报文件，我提取要点
+
+三者可混用，有 git 就用 git 数据，没有也能写。
+
+## 常用说法
+
+- 「写个年度总结」/「2026 年年度总结」→ 当前年或指定年
+- 「去年的年度总结」/「近一年的总结」→ 去年或滚动 12 个月
+- 「以销售经理的身份写年度总结」→ 临时换职业词条
+- 「以后默认用 XX 角色」→ 永久换默认角色
+- 「只要 md」「别开浏览器」「写到桌面」→ 临时改落盘行为
+- 「以后都用这个模板」→ 永久自定义模板
+
+## 输出
+
+对话直接出正文；默认落盘 annual-YYYY/ 目录下的 md/txt/html 三件 + 内容区截图，并自动打开 html（深蓝面板年度版式：发光头部、数据卡、季度时间线）。

package/annual-report/user-config.md

@@ -0,0 +1,37 @@
+# 用户配置（升级技能时本文件不会被覆盖）
+
+> 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
+> 本文件始终保留你的版本——落盘目录、格式、角色画像、自定义模板放心改。
+
+
+## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+
+```yaml
+DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
+FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 内容区截图（五张分节卡片整体，不含头部标题/复制按钮/页脚），删除该项即不截图；不影响对话中的 md 正文输出）
+DIR: auto                      # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
+DIR_MAC: /Users/luzhaosheng/MyWork/智慧食堂/reports    # macOS 落盘根目录（自动按目标年度建子目录 annual-YYYY；目录不存在时回退用户主目录下 reports）
+DIR_WIN: d:\Workspace_QCoder\reports                   # Windows 落盘根目录（自动按目标年度建子目录 annual-YYYY；目录/盘符不存在时回退用户主目录下 reports）
+OPEN_HTML: true                # 落盘后是否自动用浏览器打开 html（FORMATS 不含 html 时忽略）
+TEMPLATE: default              # 报告模板：default = 内置五段式（年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
+ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/里程碑/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
+CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
+```
+
+> 临时口头要求（仅对当次生效，不修改上方配置）：说「不落盘/别写文件」→ 当次 DISK=false；说「写到桌面/存到 ~/report（macOS）或 D:\report（Windows）」→ 当次改用该 DIR；说「只要 md / 只出 html / 只要内容区截图」→ 当次只落指定格式；说「这次不截图」→ 当次不生成内容区截图；说「只要截图/重新截个图」→ 当次只对现有 html 执行内容区截图（不重新收集 git、不重写 md/txt/html 内容文件）；说「别开浏览器」→ 当次 OPEN_HTML=false；说「这次按 xxx 模板来」→ 当次临时换模板（不改配置）；说「以后都用这个模板」→ 自动写入下方「📝 自定义模板」节并把 TEMPLATE 改为 custom（永久生效）；说「先看看效果/先出效果再落盘」→ 当次先出效果确认后再落盘；说「不用确认/直接落盘」→ 当次跳过确认直接落盘。
+
+## 📝 自定义模板（TEMPLATE: custom 时启用，用户可手改，适配各类岗位）
+
+把顶部 TEMPLATE 改为 custom 后，按下面结构生成报告（段名、段数、条目格式均可改）：
+
+```text
+段一：年度工作概述（每条：概述 - 量化结果）
+段二：重点工作与成果（每条：成果描述 - 完成时间 - 影响）
+段三：经验与不足（每条：经验或不足 - 具体表现）
+段四：明年工作计划（每条：计划描述 - 预期目标）
+```
+
+> 只写段结构与条目格式即可；未写明的细节（中文顿号序号、生成时间行、落盘行为、HTML 样式）沿用默认规范。
+
+---
+> 更多用法见 SKILL.md 的「生成流程」与 resources/ 分册。