skill-forge-hub 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 SkillForge（技能锻造坊）npm 包 `skill-forge-hub`（命令名 `skill-forge`）版本变更记录。
 
+## 1.0.5（2026-11-12）
+
+**月报技能上线：monthly-report + 报表家族四选一分流 + 登台月报映射**
+
+- 新增 monthly-report 技能：四段式月报（月度概览/本月关键成果/问题与改进/下月计划），差异化资产——数据卡环比小字（较上月 ±x%，绿涨红跌）、W1-W4 周时间线、月度日历热力图（echarts calendar heatmap，CSS 变量驱动五主题换肤）；数据收集支持 git 月度聚合 + 环比上月同口径 + 日历热力图逐日统计；自然语言月份定位（这个月/上个月/近一个月/2026-10）；与三报表同构：12 行业词典、自定义模板、五主题深蓝面板、content-png 截图
+- 分流升级：日报/周报/年报 SKILL.md 周期歧义分流 三选一 → 四选一（日报/周报/月报/年报）
+- 登台联动：deck-stage 报告四件套（补月报段映射：概览→overview、成果→timeline W1-W4、问题/计划→bullets、日历热力图→chart-heatmap）；usage-guide 示例补月报
+- CLI 与文档：cli.js CATEGORIES 报表汇演收编 monthly-report；README 分类行/技能表/安装命令同步
+- 实测：月度 reference.html headless 渲染四段卡片 + 日历热力图 + 换肤坞全通过；content 截图高度公式实测校准（760 宽基准 ~2020px + 条目增减线性外推），修正旧公式低估截断问题
+
+**纪要系列分组 + article 落盘治理 + ID 唯一性加固 + 体检四修 + 文档双语化**
+
+- 纪要系列分组：meeting-minutes 新增 SERIES_GROUP 三态（auto 自动提取系列名建 meetings/{系列名}/、series 一律系列目录、off 纯月份平铺）；系列名提取规则 + 目录名非法字符清洗 + 改口机制（「这个系列叫 XX」当次改 /「以后这个系列叫 XX」永久记）+ 一次性整理指令（扫全部旧纪要 → 移动计划确认 → 三段式报告，不删空月份目录）；CONFIG_VERSION 1→2
+- article-to-html 落盘治理：截图按篇隔离 文章截图/<标题slug>/C00-封面.png（消掉「章节截图」冗余层，多篇同名不再互相覆盖）；DIR 配置化（DIR: auto + DIR_MAC 默认 ~/articles + DIR_WIN，目录不存在回退用户主目录）；同名不同篇 slug 追加 -2/-3 序号；CONFIG_VERSION 1→2
+- ID 唯一性两条加固：①格式定死——crypto.randomUUID() 标准 UUID v4（8-4-4-4-12 十六进制小写），禁止手写变体/沿用占位与旧值；②落盘前查重——写文件前顺扫落盘目录本技能命名 html 读各 id meta，撞号重掷。三层防线：8 技能 SKILL.md 生成规则 + 9 技能 reference.html「格式自愈块」（meta 非法/缺失时按路径键自愈为合法 v4，同路径跨打开稳定复用，console.warn 显性报警）+ meta-forge forge-rules 机制句与验证环；Playwright 9/9 实测通过
+- 全仓体检四修：①quarterly-report user-config CONFIG_VERSION 1→3（内容已是 v3 形态，版本号漏 bump）；②prompt-pouch 补 sf-template@2 版本戳 + SKILL.md「产物升级（回炉）」节（深升级重建必须沿用原页 pouch-id——IndexedDB 用户数据按 pouch-id 命名空间，换 ID 即数据失联，prompts.json 数据文件一概不动）；③package.json files 补 monthly-report/meeting-minutes/quarterly-report（npm 包此前缺失这三个技能）；④meeting-minutes 补 2s 入场动画兜底 setTimeout（IntersectionObserver 不触发的环境——headless 截图/打印预览——卡片永久隐藏缺陷，与其余报表族对齐）+ 版本戳 @2→@3
+- 文档双语化改造：README 重构为中英双语全量对应 + 新增「产物画廊」（6 张技能成品真实截图，图文并茂）；拆分 docs/install.md（两种安装方式/命令参考/升级与配置保护机制详解）+ docs/architecture.md（目录结构/技能形态/四大机制/拆分规范），全部中英对照
+
+## 1.0.4（2026-11-11）
+
+**图表 echarts 化 + 数据源通用化 + 升级机制强化**
+
+- 图表 echarts 化：周报/年报四类图表（月提交柱图/日提交柱图/环形图/热力图）改 CDN echarts 渲染（jsdelivr 5.5.1）——五主题联动换肤、shot 截图模式停动画、离线自动降级提示（.ech-off 提示文案）；修复 weekly 概览 DOM 闭合层级（ov-bento 九子结构归位）与环中心文字溢出
+- 数据源通用化：三报表新增 DATA_SOURCES 数据源清单（git 仓库聚合 / file 文件目录 / remote 远程源三类型示例，mac/win 双字段），默认模板不再出现真实机器地址（~/reports、%USERPROFILE%\reports 通用路径模板）；CONFIG_VERSION 2→3；deck-stage/prompt-pouch 模板值同步通用化；全仓零真实地址残留
+- 升级机制强化：①新增 .installed-manifest 安装清单——升级时只清理清单内官方已删除的文件与空目录，用户自建文件一律不动（旧版本安装无清单时跳过清理，升级后补写清单）；②article-to-html 植入 .preserve 保护清单（design-system.md 永不覆盖，官方更新另存 .upstream 对照）；③meta-forge 机制五——.preserve 清单条件植入规范 + 校验清单 4b 项
+- 验证：升级机制三场景真机测试 12 项断言全过（旧版无清单升级 / 官方删文件精准清理 / 用户自建与定制文件保护）
+
 ## 1.0.3（2026-11-11）
 
 **窄屏分辨率适配 + 图表默认动画补齐**

package/README.md

@@ -2,172 +2,104 @@
 
 > 一处集中收纳「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, magic slides, PPTX decks, prompt manager, Pandoc converters, 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.
+**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. The craft is host-agnostic — a thin frontmatter envelope is all it takes to carry it from one AI assistant to another.
 
 所有技能均以 SKILL.md 为入口——frontmatter、生成流程、用户可改配置留在入口，重内容按生成阶段拆到 resources/ 或平铺辅助文件（如 design-system.md、scripts/），AI 执行到对应阶段才读取，降低常驻上下文占用。
 
-## 技能分类
+Every skill enters through its SKILL.md — frontmatter, generation flow, and user-editable config stay at the entry; heavy content is split into resources/ (or flat helper files such as design-system.md, scripts/) and read only when the AI reaches that stage, keeping resident context small.
+
+## 产物画廊 · Output Gallery
+
+以下均为各技能产出的真实成品截图。These are real screenshots of what each skill produces.
+
+<table>
+<tr>
+<td align="center" width="50%">
+  <img src="docs/images/daily-report.png" alt="日报成品页 Daily report page" width="100%"/><br/>
+  <sub>日报成品页（任务进度 / 明日计划 / 风险阻塞三段卡）<br/>Daily report page — progress, plans, blockers</sub>
+</td>
+<td align="center" width="50%">
+  <img src="docs/images/meeting-minutes.png" alt="会议纪要成品页 Meeting minutes page" width="100%"/><br/>
+  <sub>会议纪要成品页（会议信息 / 结论 / 议题 / 行动项五段卡）<br/>Meeting minutes page — five-section cards with action items</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="50%">
+  <img src="docs/images/article-to-html.png" alt="文档装裱成品页 Article-to-HTML page" width="100%"/><br/>
+  <sub>文档装裱成品页（暗色封面 + 组件化正文，图表矢量重绘）<br/>Article-to-HTML page — hero cover + component layout</sub>
+</td>
+<td align="center" width="50%">
+  <img src="docs/images/magic-deck.png" alt="魔法幻灯封面 Magic-deck slide cover" width="100%"/><br/>
+  <sub>魔法幻灯封面（16:9 舞台，放映 + 模板 + 主题）<br/>Magic-deck slide cover — 16:9 stage, playback + templates + themes</sub>
+</td>
+</tr>
+<tr>
+<td align="center" width="50%">
+  <img src="docs/images/deck-stage.png" alt="登台 PPTX 封面页 Deck-stage PPTX cover" width="100%"/><br/>
+  <sub>登台 PPTX 封面页（HTML 保真截图，原生可编辑页）<br/>Deck-stage PPTX cover — HTML-rendered, pages stay editable</sub>
+</td>
+<td align="center" width="50%">
+  <img src="docs/images/prompt-pouch.png" alt="锦囊提示词管理台 Prompt pouch manager" width="100%"/><br/>
+  <sub>锦囊提示词管理台（分组 / 搜索 / 收藏 / 标签 / 导入导出）<br/>Prompt pouch manager — groups, search, favorites, tags, JSON backup</sub>
+</td>
+</tr>
+</table>
+
+## 技能分类 · Categories
 
 按「技能最终产出什么」归类，一个技能只归一类；分类只用于本仓库组织与导航，安装时始终平铺复制到目标 AI 助手的技能目录，与分类无关。
 
-| 分类 | Category | 说明 | 收录技能 |
-|:---|:---|:---|:---|
-| 报表汇演 | Reports | 多源数据整理（一段文字 / 文件里的描述 / 图片与素材 / 口头补充，什么材料都能成稿），按周期产出报告（日报 / 周报 / 年报） | daily-report、weekly-report、annual-report |
-| 文档装裱 | Documents | 文档转换与美化：Word / Markdown / 纯文本 → 精美 HTML + 逐章截图 | article-to-html |
-| 工程提效 | Engineering | 基于 Pandoc 的文档 ↔ 规格互转（需求文档切片 / 规格导出 Word·PDF），Pandoc 机械转换 + AI 校对防错 | spec-doc2spec、spec-spec2doc |
-| 演示汇演 | Slides | 从内容到演示：HTML 形态的魔法幻灯（放映 + 模板 + 主题）与 .pptx 登台文稿（原生可编辑页 + 封面截图） | magic-deck、deck-stage |
-| 数据整备 | Data | Excel / CSV / 图表、数据清洗与模板整理 | （规划中） |
-| 沟通协作 | Communication | 提示词管理（锦囊本地管理台） | prompt-pouch |
-| 技能自造 | Meta | 锻造技能本身的元技能（创建技能 / 插件） | meta-forge |
-
-## 技能清单
-
-| 技能 | 分类 | 目录 | 说明 |
-|:---|:---|:---|:---|
-| daily-report | 报表汇演 | [daily-report/](daily-report/) | 多源数据生成日报（今日任务进度/明日计划/风险阻塞点）：一段文字、文件里的描述、图片或口头补充皆可成稿；支持自然语言日期（今天/昨天/上周三/10月20号）、连续多日批量、自定义模板、12 行业词条 |
-| weekly-report | 报表汇演 | [weekly-report/](weekly-report/) | 多源数据生成周报（本周结论 + 本周任务进度/下周计划/风险阻塞点 + 本周概览卡），数据来源同日报；周结束日可配置（默认周五，可改周日等），支持自然语言周定位（本周/上周/10月第2周/节假日锚定） |
-| annual-report | 报表汇演 | [annual-report/](annual-report/) | 多源数据生成年度总结（五段式：年度概览/核心成果/经验成长/不足反思/新年规划）：一段文字、文件里的描述、图片或口头补充皆可成稿；12 行业职业词典，支持自定义模板与自然语言年度定位 |
-| 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 需求文档转结构化需求切片（薄入口 + resources 分册）；自动检测 Pandoc，未装引导跨系统安装 |
-| spec-spec2doc | 工程提效 | [spec-spec2doc/](spec-spec2doc/) | Markdown 规格导出为 Word / PDF 交付文档；自动检测 Pandoc，未装引导跨系统安装；PDF 双路径（xelatex / Chrome 打印兜底） |
-| magic-deck | 演示汇演 | [magic-deck/](magic-deck/) | 内容 → 单文件 HTML 幻灯（16:9 舞台 + 播放引擎 + 十六套版式模板 + 十七套主题 + 领域成套模板 21 套 + 图表动画五式 + 动画库 + 全屏放映纯净模式）：自动播放/循环/间隔、键盘热键、页内连接、逐页 PNG 截图与主体复制（不含操作元素） |
-| deck-stage | 演示汇演 | [deck-stage/](deck-stage/) | 报告/素材 → 专业 .pptx 登台文稿：三问交互（素材 → 页骨架表 → 成片方式），常规页原生可编辑（数据卡/时间线/柱图/饼图/折线），封面与结尾页 HTML 截图保真，每页可带演讲备注；视觉与报表同源（tech/biz/mono/light/warm 五主题，mono 为 IDEA 黑亮、light 为 IDEA 白亮） |
-| meta-forge | 技能自造 | [meta-forge/](meta-forge/) | 元技能：从需求出发锻造完整技能包（薄入口 + resources 拆分 + user-config），自动植入四大机制（CONFIG_VERSION 钥匙 / user-config 抽离 / reference 双轨 / 自检纪律），入仓库时自动登记 README 与 cli.js 分类表 |
-| prompt-pouch | 沟通协作 | [prompt-pouch/](prompt-pouch/) | 锦囊提示词管理台：生成并维护本地 HTML 管理页面（分组侧栏/搜索/拖拽与按钮排序/收藏/{变量}插值/一键复制/标签全交互（点击过滤·悬停删·快捷加，AI 批量整理智能打标）/导入导出 JSON 备份/分组 emoji 快捷面板），数据存 data/prompts.json、滚动备份在 backup/ 子目录，页面与数据分离，双笔协作（页面直写 + AI 代笔） |
-
-## 安装
-
-### 方式一：npm 全局安装（推荐）
-
-```bash
-npm i -g skill-forge-hub
-skill-forge ls        # 列出全部技能与说明（只读）
-skill-forge init      # 交互式挑选技能，自动探测并安装到 AI 助手技能目录
-skill-forge update    # 升级已安装技能（配置版本感知，见下）
-```
-
-非交互 / 指定目录场景：
-
-```bash
-skill-forge init --target ~/.claude/skills --skills daily-report,weekly-report
-```
+Skills are grouped by what they ultimately produce — one skill, one category. Categories only organize this repository; installation always copies skills flat into the target AI assistant's skill directory.
 
-> **deck-stage 依赖说明**：deck-stage 需要 PptxGenJS。从本仓库直接 init 会连带复制技能目录内 node_modules，离线可用；npm 全局装出的包不含 node_modules，安装时会提示 `cd <技能目录>/deck-stage && npm install` 补装一次即可。
+| 分类 Category | 说明（中） Description | 收录技能 Skills |
+|:---|:---|:---|
+| 报表汇演<br>Reports | 多源数据整理（一段文字 / 文件里的描述 / 图片与素材 / 口头补充，什么材料都能成稿），按周期产出报告（日报 / 周报 / 月报 / 季报 / 年报）<br>Multi-source reports on a schedule — daily, weekly, monthly, quarterly, annual; any material (text, files, images, voice notes) can become a draft | daily-report、weekly-report、monthly-report、quarterly-report、annual-report |
+| 文档装裱<br>Documents | 文档转换与美化：Word / Markdown / 纯文本 → 精美 HTML + 逐章截图<br>Document conversion & beautification: Word / Markdown / plain text → polished HTML + per-chapter screenshots | article-to-html |
+| 工程提效<br>Engineering | 基于 Pandoc 的文档 ↔ 规格互转（需求文档切片 / 规格导出 Word·PDF），Pandoc 机械转换 + AI 校对防错<br>Pandoc-based document ↔ spec conversion (requirement slicing / spec export to Word·PDF), mechanical conversion plus AI proofreading | spec-doc2spec、spec-spec2doc |
+| 演示汇演<br>Slides | 从内容到演示：HTML 形态的魔法幻灯（放映 + 模板 + 主题）与 .pptx 登台文稿（原生可编辑页 + 封面截图）<br>From content to presentation: HTML magic slides (playback + templates + themes) and .pptx stage decks (editable pages + HTML cover) | magic-deck、deck-stage |
+| 数据整备<br>Data | Excel / CSV / 图表、数据清洗与模板整理（规划中）<br>Excel / CSV / charts, data cleaning & template tidying (planned) | （规划中 planned） |
+| 沟通协作<br>Communication | 会议纪要（行动项带负责人与截止时间，汇报链源头）与提示词管理（锦囊本地管理台）<br>Meeting minutes (action items with owners & deadlines, the source of the reporting chain) and prompt management (local pouch dashboard) | meeting-minutes、prompt-pouch |
+| 技能自造<br>Meta | 锻造技能本身的元技能（创建技能 / 插件）<br>Meta skills that forge skills themselves (create skill / plugin) | meta-forge |
 
-### 方式二：手动复制
+## 技能清单 · Skill List
 
-将技能目录复制到你所用的 AI 助手的技能目录（支持 SKILL.md 格式、本地加载技能的助手均可）：
+| 技能 Skill | 分类 Category | 目录 Dir | 说明（中） Description |
+|:---|:---|:---|:---|
+| daily-report | 报表汇演 Reports | [daily-report/](daily-report/) | 多源数据生成日报（今日任务进度/明日计划/风险阻塞点）：一段文字、文件里的描述、图片或口头补充皆可成稿；支持自然语言日期（今天/昨天/上周三/10月20号）、连续多日批量、自定义模板、12 行业词条<br>Daily reports (progress / plans / blockers) from any source; natural-language dates, batch multi-day runs, custom templates, 12-industry vocabulary |
+| weekly-report | 报表汇演 Reports | [weekly-report/](weekly-report/) | 多源数据生成周报（本周结论 + 本周任务进度/下周计划/风险阻塞点 + 本周概览卡）；周结束日可配置（默认周五），支持自然语言周定位（本周/上周/10月第2周/节假日锚定）<br>Weekly reports with a conclusion, progress/plans/blockers and an overview card; configurable week-end day (default Friday), natural-language week locating |
+| monthly-report | 报表汇演 Reports | [monthly-report/](monthly-report/) | 多源数据生成月报（四段式：月度概览/本月关键成果/问题与改进/下月计划），开发类用户可聚合当月 git 提交；12 行业职业词典，支持自定义模板与自然语言月份定位<br>Monthly reports (overview / key results / issues & improvements / next-month plans); optional git commit aggregation, custom templates, natural-language month locating |
+| quarterly-report | 报表汇演 Reports | [quarterly-report/](quarterly-report/) | 多源数据生成季度总结（四段式：季度概览/季度关键成果/问题与改进/下季度计划）：核心数据卡带环比（较上季度）+ 同比（较去年同期）双基准，概览附 Q1-Q4 季度走势图；成果段按 M1/M2/M3 月时间线；12 行业职业词典，支持自定义模板<br>Quarterly reviews with QoQ + YoY metric cards and a Q1-Q4 trend chart; results laid out on an M1/M2/M3 monthly timeline; 12-industry vocabulary, custom templates |
+| annual-report | 报表汇演 Reports | [annual-report/](annual-report/) | 多源数据生成年度总结（五段式：年度概览/核心成果/经验成长/不足反思/新年规划）：git 全年提交聚合 + 会话口述；12 行业职业词典，支持自定义模板与自然语言年度定位<br>Annual summaries in five sections; year-round git commit aggregation plus oral input; 12-industry vocabulary, custom templates, natural-language year locating |
+| article-to-html | 文档装裱 Documents | [article-to-html/](article-to-html/) | Word / Markdown / 纯文本 → 精美独立 HTML（思源黑体 + Roboto 商用免费字体，图表 HTML/CSS 重绘），逐章截图（Retina 2x）；现成 HTML 可直接截图或先美化<br>Word / Markdown / plain text → polished standalone HTML (free commercial fonts, vector-redrawn charts), per-chapter Retina screenshots; ready-made HTML can be screenshotted or restyled first |
+| spec-doc2spec | 工程提效 Engineering | [spec-doc2spec/](spec-doc2spec/) | Word / Markdown 需求文档转结构化需求切片（薄入口 + resources 分册）；自动检测 Pandoc，未装引导跨系统安装<br>Word / Markdown requirements → structured requirement slices; auto-detects Pandoc, guides cross-platform install when missing |
+| spec-spec2doc | 工程提效 Engineering | [spec-spec2doc/](spec-spec2doc/) | Markdown 规格导出为 Word / PDF 交付文档；自动检测 Pandoc，未装引导跨系统安装；PDF 双路径（xelatex / Chrome 打印兜底）<br>Markdown specs → Word / PDF deliverables; Pandoc auto-detect, dual PDF paths (xelatex / Chrome print fallback) |
+| magic-deck | 演示汇演 Slides | [magic-deck/](magic-deck/) | 内容 → 单文件 HTML 幻灯（16:9 舞台 + 播放引擎 + 十六套版式模板 + 十七套主题 + 领域成套模板 21 套 + 图表动画五式 + 动画库 + 全屏放映纯净模式）：自动播放/循环/间隔、键盘热键、页内连接、逐页 PNG 截图与主体复制<br>Content → single-file HTML slides (16:9 stage, playback engine, 16 layouts, 17 themes, 21 domain template packs, chart animations); autoplay, hotkeys, per-slide PNG capture |
+| deck-stage | 演示汇演 Slides | [deck-stage/](deck-stage/) | 报告/素材 → 专业 .pptx 登台文稿：三问交互（素材 → 页骨架表 → 成片方式），常规页原生可编辑（数据卡/时间线/柱图/饼图/折线），封面与结尾页 HTML 截图保真，每页可带演讲备注；视觉与报表同源（tech/biz/mono/light/warm 五主题）<br>Reports/materials → editable .pptx decks: three-question flow, native editable pages (data cards / timelines / charts), HTML-rendered cover & closing, speaker notes per page |
+| meta-forge | 技能自造 Meta | [meta-forge/](meta-forge/) | 元技能：从需求出发锻造完整技能包（薄入口 + resources 拆分 + user-config），自动植入四大机制（CONFIG_VERSION 钥匙 / user-config 抽离 / reference 双轨 / 自检纪律），入仓库时自动登记 README 与 cli.js 分类表<br>Meta skill: forge complete skill packages from requirements (thin entry + resources split + user-config) with four built-in mechanisms and automatic repo registration |
+| meeting-minutes | 沟通协作 Communication | [meeting-minutes/](meeting-minutes/) | 多源材料生成会议纪要（五段式：会议信息/会议结论/议题讨论/决议与行动项/下次会议）：行动项带负责人与截止时间（汇报链源头，可被日报/周报/月报/季报引用）；内置 12 类会议类型词典，支持自定义模板<br>Meeting minutes in five sections; action items with owners & deadlines (source of the reporting chain, citable by daily/weekly/monthly/quarterly reports); 12 meeting-type dictionaries, custom templates |
+| prompt-pouch | 沟通协作 Communication | [prompt-pouch/](prompt-pouch/) | 锦囊提示词管理台：生成并维护本地 HTML 管理页面（分组侧栏/搜索/拖拽与按钮排序/收藏/{变量}插值/一键复制/标签全交互/导入导出 JSON 备份/分组 emoji 快捷面板），数据存 data/prompts.json、滚动备份在 backup/ 子目录，页面与数据分离，双笔协作（页面直写 + AI 代笔）<br>Local prompt manager page (groups, search, drag & button sorting, favorites, {variable} interpolation, one-click copy, full tag interaction, JSON import/export); data lives in prompts.json with rolling backups, page and data stay separate |
+
+## 快速开始 · Quick Start
 
 ```bash
-cp -R daily-report weekly-report annual-report <你的 AI 助手技能目录>/
-cp -R magic-deck prompt-pouch <你的 AI 助手技能目录>/
-cp -R spec-doc2spec spec-spec2doc <你的 AI 助手技能目录>/
+npm i -g skill-forge-hub        # 全局安装 · global install
+skill-forge ls                  # 列出全部技能（只读）· list all skills
+skill-forge init                # 交互式挑选技能，自动探测并安装到 AI 助手技能目录 · pick & install interactively
+skill-forge update              # 升级已安装技能（配置版本感知，本地配置受保护）· upgrade with config protection
 ```
 
-复制后直接说「写日报」「写周报」或丢给它一个文档即可触发；问「日报怎么用 / 周报怎么用 / 登台怎么用」输出使用说明。
-
-## 命令参考
+安装后直接说「写日报」「写周报」「写月报」「写季报」「写年报」「记会议」或丢给它一个文档即可触发；问「日报怎么用 / 会议纪要怎么用 / 登台怎么用」等输出使用说明。
 
-| 命令 | 说明 |
-|:---|:---|
-| `skill-forge ls` | 列出全部技能（分类 + 名称 + 说明），只读 |
-| `skill-forge init` | 列清单交互挑选：a=全部安装 / 编号挑选（已装标 ★，确认时可 s 跳过已装只装新） |
-| `skill-forge update` | 升级全部已安装技能（配置版本感知） |
-| `skill-forge update --skills a,b` | 只升级指定技能（未安装的提示跳过） |
-| `skill-forge --version` | 显示版本号 |
-| `skill-forge --help` | 显示完整帮助 |
+Once installed, just say "写日报" (write a daily report), "记会议" (take meeting minutes), or hand it a document to trigger a skill; ask "how to use X" for a plain-language guide.
 
-通用参数（init / update 通用）：
+## 文档导航 · Documentation
 
-| 参数 | 说明 |
+| 文档 Document | 内容 Contents |
 |:---|:---|
-| `--target <目录>`（`-t`） | 指定技能目录；缺省自动探测常见助手目录（~/.qoder-cn、~/.claude、~/.cursor 等），探测到多个时交互选择 |
-| `--skills a,b`（`-s`） | 指定技能名列表：init 时跳过选择直接安装/升级指定技能（适合脚本与单件补装）；update 时只升级指定技能 |
-| `--yes`（`-y`） | 跳过确认直接执行；配置版本变化时默认「保留我的 + 官方版另存 .upstream 对照」 |
-
-命令别名：`list` = `ls`、`install` = `init`、`upgrade` = `update`。
-
-## 升级与配置保护
-
-`skill-forge update`（默认升级全部已装技能，可用 `--skills a,b` 指定）在覆盖技能文件前自动保护你的配置：
-
-- **常驻保护**：目标目录已存在的 `user-config.md`（及技能 `.preserve` 清单声明的文件）永不被覆盖，你的本地配置永久保留；官方配置内容有更新时另存 `.upstream` 对照文件，可按需手动合并新配置点
-- **版本感知**：官方 `user-config.md` 首行的 `CONFIG_VERSION` 高于你的本地版本（配置结构增/减/改名）时——
-  1. 先把你的配置备份为 `user-config.md.bak-<时间戳>`
-  2. 交互三选一：`[1] 官方覆盖`（旧配置在备份中随时找回）/ `[2] 保留我的` + 官方版另存 `.upstream` 对照（默认）/ `[3] 稍后处理`（本次不生成对照文件）
-  3. `--yes` 或非交互环境默认 `[2]`，最安全
-- **版本一致**：无感升级，只更新技能文件，配置原样保留
-- **结构同步**：升级时清理官方已删除的文件与空目录（历史只增不删的废弃文件不再残留）；`user-config.md`、`.preserve` 清单文件、`.upstream` 对照、`.bak-*` 备份与 `node_modules` 依赖永远不动
-
-技能维护者约定：官方配置结构每次变化（新增/改名/删除配置键）时，`user-config.md` 的 `CONFIG_VERSION` 递增 1，并在 SKILL.md「配置版本机制」节写明迁移规则（AI 每次执行前也会自检该版本）。
-
-## 目录结构
-
-```
-.
-├── README.md                    # 本文件（双语介绍 + 技能分类 + 命令参考）
-├── CHANGELOG.md                 # 版本变更记录
-├── cli.js                       # 安装器（ls / init / update，零依赖 Node>=14）
-├── package.json                 # npm 包定义（skill-forge-hub，命令名 skill-forge）
-├── template/                    # 新技能模板（薄入口 + resources 拆分规范）
-├── meta-forge/                  # 元技能：造 skill 的 skill（四大机制植入 + 仓库登记）
-├── article-to-html/
-│   ├── SKILL.md                 # 文档 → 精美 HTML 完整流程 + 逐章截图（含内嵌使用说明）
-│   ├── design-system.md         # 设计系统（字体 / 配色 / 排版 / 图表重绘）
-│   ├── user-config.md           # ⚙️ 用户配置（THEME 等，升级不覆盖）
-│   └── scripts/                 # 字体安装 / docx 抽取 / 字体内联脚本
-├── daily-report/（weekly-report / annual-report 同构）
-│   ├── SKILL.md                 # 薄入口：frontmatter + 生成流程 + 规则速览
-│   ├── user-config.md           # ⚙️ 用户配置（CONFIG_VERSION + 默认配置 + 自定义模板）
-│   └── resources/               # 重内容按生成阶段拆分，AI 按需读取
-│       ├── usage-guide.md       # 📖 使用说明（咨询应答的原样输出源）
-│       ├── date-parsing.md      # 🗓 日期解析（自然语言优先）
-│       ├── data-collection.md   # 📥 数据收集（多源聚合：口述 / 文字 / 文件 / 图片）
-│       ├── content-rules.md     # ✍️ 内容规则（聚合来源 / 纯文字模式 / 输出格式 / 写作风格）
-│       ├── industry-dictionary.md # 🏭 行业适配（12 行业职业词典）
-│       └── disk-and-html.md     # 💾 本地落盘 / HTML 样式 / content-png 截图规范
-├── magic-deck/
-│   ├── SKILL.md                 # 薄入口：魔法幻灯生成流程 + 规则速览
-│   ├── user-config.md           # ⚙️ 用户配置
-│   └── resources/
-│       ├── usage-guide.md       # 📖 使用说明（功能/热键/截图/复制/全屏）
-│       ├── deck-spec.md         # 完整规范（骨架/主题色值/模板库/热键表/截图实现）
-│       └── reference.html       # 成品骨架（生成时以此为骨逐处替换内容）
-├── deck-stage/
-│   ├── SKILL.md                 # 薄入口：登台 PPTX 三问交互 + 生成流程
-│   ├── user-config.md           # ⚙️ 用户配置
-│   ├── package.json             # 依赖声明（pptxgenjs）
-│   └── resources/
-│       ├── usage-guide.md       # 📖 使用说明
-│       ├── data-schema.md       # data.json 结构（段落 → 页类型/节色映射）
-│       ├── pptx-builder.js      # 真相源：读 data.json 产 16:9 pptx
-│       └── cover-template.html  # 封面/结尾截图底版
-├── prompt-pouch/
-│   ├── SKILL.md                 # 薄入口：锦囊管理台生成流程
-│   ├── user-config.md           # ⚙️ 用户配置（DIR/DATA_DIR/BACKUP_DIR 等）
-│   └── resources/
-│       ├── usage-guide.md       # 📖 使用说明
-│       ├── data-format.md       # prompts.json 数据格式
-│       └── reference.html       # 成品骨架
-├── spec-doc2spec/（spec-spec2doc 同构）
-│   ├── SKILL.md                 # 薄入口：Pandoc 转换 + AI 校对流程
-│   ├── user-config.md           # ⚙️ 用户配置
-│   └── resources/               # 分册：checklist 校对清单 / images 图片处理 /
-│                                #   structure 目录组织 / pdf-path PDF 双路径 / usage-guide
-└── weekly-report/
-    ├── SKILL.md
-    ├── user-config.md
-    └── resources/               # 结构同 daily-report，周报专属差异：
-                                 #   WEEK_END 周结束日 / 周定位解析 / 本周概览卡 / 用时 X.XD（1D=8H）
-```
+| [docs/install.md](docs/install.md) | 安装与升级详解：两种安装方式、命令参考、升级与配置保护机制、维护者约定（CONFIG_VERSION 递增规则）<br>Installation & upgrade in depth: two install methods, command reference, upgrade & config protection, maintainer conventions |
+| [docs/architecture.md](docs/architecture.md) | 架构与规范：目录结构、技能形态（薄入口 + resources）、四大机制、拆分规范、通用原则<br>Architecture & conventions: directory layout, skill anatomy, the four core mechanisms, splitting rules, general principles |
+| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 · Version changelog |
 
-## 拆分规范（薄入口 + resources）
+## 许可证 · License
 
-- **SKILL.md 只保留**：frontmatter、生成流程总览（每步标注读哪个 resource）、「⚙️ 默认配置」「📝 自定义模板」（用户手改的配置必须留在入口）、规则速览（3-5 条硬性规则）
-- **resources/ 一文件一职责**：按生成阶段拆分，SKILL.md 流程节点标注 `读 resources/xxx.md`；每份 resource 独立可读，不互相引用
-- **咨询应答**：用户只问用法不要求生成时，读 `resources/usage-guide.md` 原样输出（首行标题按技能改为「XX生成器使用指南」）
-- **新技能按 `template/` 结构创建**，目录名 = 技能名（英文短横线），并归入上方「技能分类」表对应分类 + 同步 cli.js CATEGORIES 与 package.json files
-- **已有技能按各自结构维护**：article-to-html 采用 SKILL.md + design-system.md + scripts/ 平铺结构（使用说明内嵌 SKILL.md「用户使用说明」节）
-- **通用原则**：零外部依赖（禁 CDN / 外链，内网离线双击可开）、双系统兼容（macOS / Windows）
-- **配置升级**：user-config.md 首行带 `CONFIG_VERSION`，官方配置结构变化时递增并写明迁移规则；CLI update 与 AI 执行时均按该版本做备份 + 迁移提示
-- **元技能**：meta-forge 造技能时的规范真相源在 `resources/forge-rules.md`（澄清清单 / 结构规范 / 四大机制 / 校验清单 / 仓库登记），SKILL.md 流程节点与 template/ 模板均与之对齐
+[MIT](LICENSE)

package/annual-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: annual-report
-description: 生成年度总结（默认五段式：年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划），适配各行业（内置 12 行业职业词典，可指定角色身份）。数据来源灵活：直接口述、给一段文字、发文件（Word/PDF/Excel/PPT 等）或图片，都能整理成年度总结。支持自定义模板（可永久或临时指定）。支持自然语言指定年度（2026年/去年/近一年/最近12个月等）。当用户请求写年度总结、年终总结、年度复盘、年总结、/annual-report，或询问年度总结用法（年度总结怎么用/年度总结使用说明）时使用。用户说「写总结/工作总结/写个汇报」等未言明周期的词时，先 AskUserQuestion 分流（日报/周报/年报）再执行，不擅自默认。
+description: 生成年度总结（默认五段式：年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划），适配各行业（内置 12 行业职业词典，可指定角色身份）。数据来源灵活：直接口述、给一段文字、发文件（Word/PDF/Excel/PPT 等）或图片，都能整理成年度总结。支持自定义模板（可永久或临时指定）。支持自然语言指定年度（2026年/去年/近一年/最近12个月等）。当用户请求写年度总结、年终总结、年度复盘、年总结、/annual-report，或询问年度总结用法（年度总结怎么用/年度总结使用说明）时使用。用户说「写总结/工作总结/写个汇报」等未言明周期的词时，先 AskUserQuestion 分流（日报/周报/月报/季报/年报）再执行，不擅自默认。
 allowed-tools: Bash, Read, Write
 disable-model-invocation: false
 ---
@@ -11,24 +11,30 @@ disable-model-invocation: false
 
 ## 生成流程
 
-0.5 **周期歧义分流**：用户说「写总结/工作总结/写个汇报/做一份总结」等未言明周期的词 → AskUserQuestion 三选一（日报/周报/年报）确认周期再继续，不擅自默认
-0. **读用户配置**（DISK/FORMATS/DIR/OPEN_HTML/THEME/TEMPLATE/ROLE/CONFIRM/CONFIG_VERSION、自定义模板）→ 先 Read 同目录 `user-config.md`
+0.5 **周期歧义分流**：用户说「写总结/工作总结/写个汇报/做一份总结」等未言明周期的词 → AskUserQuestion 五选一（日报/周报/月报/季报/年报）确认周期再继续，不擅自默认
+0. **读用户配置**（DISK/FORMATS/DIR/OPEN_HTML/THEME/TEMPLATE/ROLE/CONFIRM/CONFIG_VERSION/DATA_SOURCES、自定义模板）→ 先 Read 同目录 `user-config.md`
 1. **解析年度**（自然语言 → 目标年度区间）→ 读 `resources/date-parsing.md`
 2. **收集数据**（多源：会话口述 / 文字 / 文件 / 图片 / 代码提交记录，合并去重）→ 读 `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`
+5.5 **交付前自检**（落盘与截图前必做，硬门禁不可跳过）：annual-report-YYYY.html 文件写好后——
+   - Bash 起 `python3 -m http.server 8945`（后台，端口占用换 8946/8947…）
+   - Playwright headless 自检（缺则 `pip3 install --user playwright`；用系统 Chrome，channel="chrome" 无需下载浏览器）：goto 页面 → 挂 pageerror 监听（零容忍）→ 滚动到底部 → 断言头部标题卡与年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划五张分节卡存在（证明主体结构完整未被破坏）
+   - 截全页 PNG Read 自查：头部标题卡与年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划五张分节卡齐全、文字无溢出截断、无豆腐块缺字
+   - 任何报错或视觉问题：修 HTML → 重检；全绿才进第 6 步
 6. **使用咨询**（用户只问「年度总结怎么用」等用法、未要求生成）→ 读 `resources/usage-guide.md`，将其内容原样输出（首行标题改为「年度总结生成器使用指南」），不收集数据、不生成报告、不落盘、不开浏览器
 
 ## ⚙️ 配置与自定义模板
 
-**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（DISK/FORMATS/DIR/OPEN_HTML/THEME/TEMPLATE/ROLE/CONFIRM/CONFIG_VERSION）与自定义模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
+**执行本 skill 前必须先 Read 同目录 `user-config.md`**：默认配置（DISK/FORMATS/DIR/OPEN_HTML/THEME/TEMPLATE/ROLE/CONFIRM/CONFIG_VERSION/DATA_SOURCES）与自定义模板都在该文件中，以它为准。升级技能时 user-config.md 不会被覆盖，你的修改永久保留；官方更新配置时另存 `user-config.md.upstream` 对照文件，可按需手动合并新配置点。
 
-- **THEME**：html 页面主题，tech 深蓝科技（默认）/ biz 浅色商务 / mono IDEA 黑亮 / light IDEA 白亮 / warm 温暖渐变；生成时写 `<html data-theme="THEME值">` 定默认，页面右下角换肤坞随点随换（localStorage 记忆、?shot 截图模式与打印隐藏）
+- **THEME**：html 页面主题，tech 深蓝科技（默认）/ biz 浅色商务 / mono IDEA 黑亮 / light IDEA 白亮 / warm 温暖渐变；生成时写 `<html data-theme="THEME值">` 定默认，页面右下角换肤坞随点随换（localStorage 记忆（键按页内嵌唯一 ID 隔离、多份产物互不串台、改名/移动目录记忆不丢（生成时头部写 `<meta name="annual-id" content="<UUID>">`，每次 crypto.randomUUID() 生成标准 UUID v4（8-4-4-4-12 十六进制，禁止手写变体、禁止沿用占位与旧值）；落盘写文件前顺扫落盘目录下本技能命名的 html，读各文件 id meta 查重，撞号重掷至不重复））、?shot 截图模式与打印隐藏）
+- **DATA_SOURCES 意图路由**：用户说「把这些 git 地址 / 目录配置到这个 skill」「数据源加一下」「以后数据从 XX 仓库取」→ 默认指配置到 `user-config.md` 的 `DATA_SOURCES` 数据源清单（不是 SKILL.md、不是 disk-and-html.md）；「git 地址」给的是 URL 或本地仓库路径、目录给的是本地路径都写进 DATA_SOURCES。用户话术只指向某个特定数据源（如「只算这个仓库」）→ 当次生效，不写配置。意图仍有歧义（如分不清「数据收集配置」与「落盘目录配置」）→ 一句话与用户确认后写入，不猜
 
 ## 配置版本机制（升级保护）
 
-本 skill 当前配置版本为 `2`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
+本 skill 当前配置版本为 `3`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
 1. 先将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`（同目录，绝不删除旧值）
 2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
@@ -39,12 +45,26 @@ disable-model-invocation: false
 
 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
 
-当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。
+当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释；DIR_MAC/DIR_WIN 默认值通用化——已配置用户保留原值不受影响）。
 
 ## 文档同步自检纪律（维护者必读）
 
 修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如章节名/字段名/效果参数改名时新旧词全仓核对，旧词零残留才算完成）。修改 HTML 效果必须同步更新 `resources/reference.html` 与 `disk-and-html.md` 对应描述，三者以 reference.html 为真相源；改完后互相 grep 关键参数确认对齐。
 
+## 产物升级（回炉）
+
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="annual-report@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧年报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="annual-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版年报（vN-1 或无版本戳的历史产物），说『把我旧年报都升级成新样式』即可一键升级」，不让用户背触发语。
+
+## 🔧 报修处理流程（用户报页面问题时）
+
+用户说「这个页面效果不对 / 布局乱了 / 有 UI 问题 / 样式错了 / 交互坏了」（常附截图或指出具体现象）→ 按以下流程处理，不以「重新生成一份」敷衍：
+
+1. **立标准**：先 Read 本 skill 目录 `resources/reference.html`——它就是设计标准答案（布局/配色/交互全在代码里）
+2. **找问题**：Read 用户那份问题 html 文件，与 reference 逐处比对（结构顺序 / CSS 变量 / 关键类名 / 交互 JS），定位跑偏处；用户给了截图则按截图现象反查
+3. **修复**：以 reference 为准修复那份 html（只修跑偏处，不动正确内容；reference 与 html 不一致时以 reference 为准）
+4. **自证**：Chrome headless 访问修复后页面截全页 PNG，Read 自查修复点恢复标准效果；用户给了问题截图时尽量复现同视角截图做前后对比
+5. **汇报**：一句话说清问题根因 + 修复了什么 + 附截图；若根因在 reference.html 自身（生成结果与 reference 一模一样但仍有问题），顺修 reference.html 对应处并在汇报中说明「参考模板已同步修正」，避免下一份重蹈覆辙
+
 ## 规则速览
 
 - 五段式骨架行业无关：年度概览（一句话 TL;DR + 3-6 项核心数据卡，数字带同比基准）/ 核心成果与里程碑（按季度 Q1-Q4 时间线 8-12 项，每项 20-40 字 + 价值归因）/ 经验与成长（3-5 条，个人成长允许「我」）/ 不足与反思（2-4 条三环：问题+影响+改进，改进带可验证动作与时间）/ 新年展望与规划（3-5 项目标，各带量化指标、完成标准与分季度行动节点）

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

@@ -4,22 +4,39 @@
 
 ## 1. 代码仓库全年提交聚合（可选，开发类用户）
 
-- 遍历仓库清单（见 disk-and-html.md 的仓库清单节），对每仓执行全年统计：
+清单形状（每项 name 唯一名称 + type 类型 + 路径；完整填写说明见 user-config.md「默认配置」的 DATA_SOURCES 注释）：
+
+```yaml
+DATA_SOURCES:
+  - name: 主项目仓库          # name = 唯一 key（重名视为同一数据源；口述「只聚合 xxx」按 name 匹配）
+    type: git                # git = 代码仓库（git log 聚合提交）
+    mac: ~/Projects/main-app  # macOS 路径（绝对路径或 ~ 开头）
+    win: D:\Projects\main-app # Windows 路径；「-」= 该系统不存在，自动跳过
+  - name: 周例会纪要
+    type: file               # file = 普通文件/目录（直接 Read 内容聚合）
+    mac: ~/Documents/meeting-notes.md
+    win: -
+  - name: 数据接口
+    type: remote             # remote = 远程网络源（联网拉取 url 内容）
+    url: https://example.com/data.json
+```
+- 遍历 user-config.md 的 DATA_SOURCES 清单（type: git 项；个人数据源必须写在 user-config.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 之类单文件可贡献数十万行噪音
+  - **先剔除生成物路径**（.build/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 双列表，空列跳过）
+- 仓库按系统取有效路径（mac / win 双字段，「-」= 该系统不存在跳过）
 
 ## 2. 会话口述与文字材料
 
 - 用户口述的年度大事（「年初做了 X」「Q3 上了 Y」）逐条记录
 - 用户提供的总结草稿/文档（md/txt/docx）Read 提取要点；图片逐张 Read 识别内容
-- 聊天记录/周报/日报文件也可作为素材
+- DATA_SOURCES 清单中 type: file 的文件 Read 全文、目录逐个 Read 文本文件提取要点（二进制跳过、路径无效静默跳过）；type: remote 只需 url 字段（mac/win 忽略）联网拉取内容提取要点（拉取失败静默跳过；仅收集时联网，HTML 产物仍零外链）；未知 type 忽略该项并在生成时提示
+- 聊天记录/周报/日报/会议纪要文件也可作为素材（会议行动项可直接引用为成果依据）
 
 ## 3. 合并去重与口径
 
-- 同一成果 提交数据与口述重合时合并为一条，量化以 提交统计为准、定性以口述为准
+- 同一成果提交数据与口述重合时合并为一条，量化以提交统计为准、定性以口述为准；file/remote 提取要点与口述同等对待
 - 无法量化的条目写定性描述，不编造数字
 - 年度核心指标（概览卡数据）优先取：总提交数/年度增删行数/里程碑数（研发），其它行业按职业词典量化指标

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

@@ -1,4 +1,4 @@
-> ⛔ **Reference 铁律（最高优先）**：本目录 `reference.html` 是定稿样式源码。生成 HTML 时必须先 Read `resources/reference.html` 与本文件两份，以 reference.html 为骨架模板逐处替换数据（标题/日期/五段条目/TL;DR 摘要/数据卡数字/月提交柱图），本文件的描述是参数解释、变体规则与禁止项；两者冲突时**以 reference.html 为准**。修改本 skill 的 HTML 效果时，必须同步更新 `resources/reference.html` 与本文档的对应描述，禁止只改一处。
+> ⛔ **Reference 铁律（最高优先）**：本目录 `reference.html` 是定稿样式源码。生成 HTML 时必须先 Read `resources/reference.html` 与本文件两份，以 reference.html 为骨架模板逐处替换数据（标题/日期/五段条目/TL;DR 摘要/数据卡数字/月提交柱图数据数组——IIFE 内 MONTHS/VALS），本文件的描述是参数解释、变体规则与禁止项；两者冲突时**以 reference.html 为准**。修改本 skill 的 HTML 效果时，必须同步更新 `resources/reference.html` 与本文档的对应描述，禁止只改一处。
 
 # 落盘与 HTML（年度版式）
 
@@ -11,20 +11,20 @@
 
 ## HTML 年度版式（深蓝面板体系，与日报/周报同源）
 
-- 复用日报/周报深蓝面板视觉体系：背景 #0a1929 + SVG feTurbulence 微噪点（opacity .04）+ 三层科技底纹（.grid-pattern 60px 青色细网格 var(--scan-dim) + .stars 8 个 1-1.5px 星点白/青/紫/绿散落 + .scanlines 2px 周期扫描线 var(--scan-dim)）；禁用任何 CDN 与外部网络引用（@import、外链 CSS/JS/图片/网络字体一律禁止，页面必须公司内网离线双击可打开、零外部依赖）；字体全用系统本地字体栈 ui-monospace/'SF Mono'/SFMono-Regular/Menlo/Consolas；颜色全部用 CSS 变量统一主题令牌：19 令牌 × 5 主题（tech 深蓝科技（默认，色值与旧 ask 色板一致）/biz 浅色商务/mono IDEA 黑亮（JetBrains New UI Dark 官方色系：编辑区 #1e1f22 + 面板 #2b2d30）/light IDEA 白亮（IntelliJ Light 官方色系：白编辑区 + 浅灰面板）/warm 温暖渐变，html[data-theme] 运行时切换；12 核心契约 --bg/--bg2/--panel/--panel-solid/--text/--muted/--accent/--accent2/--border/--glow/--title-grad/--tag-bg + 报告扩展 --glow-soft/--scan/--scan-dim/--heat/--green/--orange/--rose；生成时按 THEME 配置写 data-theme 定默认，页面右下角换肤坞五色点随点随换、localStorage 记忆、?shot 截图模式与打印隐藏）
-- 头部卡片：标题按行业词典「标题」变量取词 + 年份前缀（如「2026 研发年度总结」；话术含职业词 → 该词条标题，未提职业 → 按 ROLE 画像匹配词条，词典外行业 → 「YYYY 年度总结」兜底；词典标题行见 `resources/industry-dictionary.md`）+ 副标题（ROLE 画像或年度区间）+ 生成时间行；speccore ask 同款发光特效：四边 1px 青色浮光线 transparent→var(--accent)→transparent 整条平移扫动（上 scanX 左→右、右 scanY 上→下、下 scanX-rev 右→左、左 scanY-rev 下→上，四线同周期 3s linear 单向平移，亮段完整穿越卡片后消失于两端界外，卡片 overflow:hidden 裁剪；禁止自创 background-position 滚动/常驻辉光/往返摆动/亮段半嵌常驻变体）+ 顶部光斑 cardGlow（radial-gradient ellipse at 50% 10% var(--glow)→transparent 70%，opacity .5→1 + scale 1→1.6，transform-origin top center，3s 循环，头部与每张分节卡片内均放 .card-glow 层）+ 标题文字青色光晕呼吸（text-shadow 双圈 3s 循环）
+- 复用日报/周报深蓝面板视觉体系：背景 #0a1929 + SVG feTurbulence 微噪点（opacity .04）+ 三层科技底纹（.grid-pattern 60px 青色细网格 var(--scan-dim) + .stars 8 个 1-1.5px 星点白/青/紫/绿散落 + .scanlines 2px 周期扫描线 var(--scan-dim)）；图表渲染用 echarts@5.5.1（body 末尾主 script 之前引入 `<script src="https://cdn.jsdelivr.net/npm/echarts@5.5.1/dist/echarts.min.js"></script>`，页面唯一网络引用；离线/内网无外网加载失败时图表容器显示 data-off 降级提示文字、页面其余内容正常浏览不受影响）；除 echarts 外禁用任何 CDN 与外部网络引用（@import、外链 CSS/图片/网络字体一律禁止）；字体全用系统本地字体栈 ui-monospace/'SF Mono'/SFMono-Regular/Menlo/Consolas；颜色全部用 CSS 变量统一主题令牌：19 令牌 × 5 主题（tech 深蓝科技（默认，色值与旧 ask 色板一致）/biz 浅色商务/mono IDEA 黑亮（JetBrains New UI Dark 官方色系：编辑区 #1e1f22 + 面板 #2b2d30）/light IDEA 白亮（IntelliJ Light 官方色系：白编辑区 + 浅灰面板）/warm 温暖渐变，html[data-theme] 运行时切换；12 核心契约 --bg/--bg2/--panel/--panel-solid/--text/--muted/--accent/--accent2/--border/--glow/--title-grad/--tag-bg + 报告扩展 --glow-soft/--scan/--scan-dim/--heat/--green/--orange/--rose；生成时按 THEME 配置写 data-theme 定默认，页面右下角换肤坞五色点随点随换、localStorage 记忆（键按页内嵌唯一 ID 隔离、多份产物互不串台、改名/移动目录记忆不丢；生成时头部写 `<meta name="annual-id" content="<UUID>">`，每次新 UUID）、?shot 截图模式与打印隐藏）
+- 头部卡片：标题按行业词典「标题」变量取词 + 年份前缀（如「2026 研发年度总结」；话术含职业词 → 该词条标题，未提职业 → 按 ROLE 画像匹配词条，词典外行业 → 「YYYY 年度总结」兜底；词典标题行见 `resources/industry-dictionary.md`）+ 副标题（ROLE 画像或年度区间）+ 生成时间行；指令面板同款发光特效：四边 1px 青色浮光线 transparent→var(--accent)→transparent 整条平移扫动（上 scanX 左→右、右 scanY 上→下、下 scanX-rev 右→左、左 scanY-rev 下→上，四线同周期 3s linear 单向平移，亮段完整穿越卡片后消失于两端界外，卡片 overflow:hidden 裁剪；禁止自创 background-position 滚动/常驻辉光/往返摆动/亮段半嵌常驻变体）+ 顶部光斑 cardGlow（radial-gradient ellipse at 50% 10% var(--glow)→transparent 70%，opacity .5→1 + scale 1→1.6，transform-origin top center，3s 循环，头部与每张分节卡片内均放 .card-glow 层）+ 标题文字青色光晕呼吸（text-shadow 双圈 3s 循环）
 - 五张分节卡片（实心深蓝底 #0b1e37 + 1px 白色微透细线 8px 周期淡条纹（repeating-linear-gradient(180deg, rgba(255,255,255,.012) 0 1px, transparent 1px 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 图标不加）
 - 数字选择：用户口述的业务结果指标（响应时间/错误率/转化率/成功率等）优先写入，提交统计（提交数/文件数/行数）仅在无业务指标时兜底，两者都有时业务指标在前、提交统计后置或省略；数字凡有对比基准必带（环比/同比/目标完成度至少其一，如「+18%」「达目标 90%」），无基准来源时不作要求 - 概览节：一句话 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 字 + 青色细边 var(--border) + 淡青底））
-- 年度提交月度柱图（研发词条；其它词条按职业词典图表主题）：.cb-col 12 根柱一月到十二月、.cb-bar width:24px 柱宽（太小显细弱）、柱高按当月提交数、position:relative 柱上带 .cb-tip hover 浮层「X月 · N 次提交」；置于里程碑节内时间线之后
+- 年度提交月度柱图（研发词条；其它词条按职业词典图表主题）：.cb-wrap 内 .ech echarts bar 容器 110px 高（#monthChart）、12 根柱一月到十二月、柱高按当月提交数、tooltip 显示「X月 · N 次提交」、--accent2→--accent 渐变柱身 + glow 光晕；置于里程碑节内时间线之后
 - 内容区 .wrap width:clamp(640px, 60%, 1200px)（与日报/周报同款自适应宽度，宽屏占 60% 不留大空边）+ 上下 padding 40px、左右 0 - 头部卡片内生成时间徽章下居中青色渐变 40px 大胶囊「一键复制」按钮（var(--accent)→var(--accent2)，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）；滚动入场：初始视口外的卡片滚到视口才上浮渐显（html.js 门控 + IntersectionObserver，translate 独立属性不碰 transform——hover 3D 偏转零冲突，stagger 70ms 封顶 280ms、入场完即清 delay 不拖慢 hover 偏转，2s 兜底强制显示；无 JS/打印/截图模式一律全显）；窄屏收敛：<680px 视口 wrap 满宽流式、边距收窄、h1 统一 26px（clamp 640px 下限在窄窗不再横向溢出）；月提交柱图加载生长动画 cbGrow 1s（对齐周报柱图）；月提交柱图 12 列窄屏随 flex 收缩（bar 弹性宽、gap 收窄），tip 浮层首末列锚定防裁剪、按钮弹入；卡片入场动画 fadeDown/fadeUp/riseIn 的 fill-mode 必须用 backwards 严禁 both（both 使动画结束后最后一帧 transform:none 永久覆盖 hover 的 3D 偏转 transform，hover 偏转会完全失效）
+- 入场动画：头部淡入下滑、五张卡片依次错峰上浮淡入（概览 0.13s/成果 0.26s/成长 0.4s/反思 0.54s/展望 0.68s）；滚动入场：初始视口外的卡片滚到视口才上浮渐显（html.js 门控 + IntersectionObserver，translate 独立属性不碰 transform——hover 3D 偏转零冲突，stagger 70ms 封顶 280ms、入场完即清 delay 不拖慢 hover 偏转，2s 兜底强制显示；无 JS/打印/截图模式一律全显）；窄屏收敛：<680px 视口 wrap 满宽流式、边距收窄、h1 统一 26px（clamp 640px 下限在窄窗不再横向溢出）；月提交柱图 echarts 默认生长动画（对齐周报柱图）；?shot 截图模式 animation:false 直接渲染终态（headless 虚拟时间下动画帧不推进会停在初始帧导致截图空白）；echarts 容器 width:100% 窄屏自适应无需特化、按钮弹入；卡片入场动画 fadeDown/fadeUp/riseIn 的 fill-mode 必须用 backwards 严禁 both（both 使动画结束后最后一帧 transform:none 永久覆盖 hover 的 3D 偏转 transform，hover 偏转会完全失效）
 - hover 微交互：卡片上浮 translateY(-2px) + 阴影加深 + inset 发光增强、条目淡青底 var(--tag-bg)、时间线节点与序号徽章放大微旋（li:hover .idx transform:scale(1.18) rotate(-4deg)、球内数字放大 12→14px、数字必须用 <b> 包裹（.idx b{display:inline-block;transition:transform .2s ease}）+ li:hover .idx b{transform:rotate(-6deg)} 数字在球内独立微旋；用户澄清 hover 变大的字体仅小球内数字，desc 正文保持 15px 不变不加斜体；销售 demo 版类名 .num：li:hover .num scale(1.22) rotate(-6deg)、数字 13→15px 同样 <b> 包裹 + rotate(-6deg)）、数据卡上浮、按钮上浮/按压回缩
 - 卡片级 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,var(--scan-dim) 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、footer 设 display:none（copy-wrap 在头部卡内随卡隐藏），body 四周 padding 统一 40px，供主体内容整体截图用、保证截图四周留白对称合适）
-- 页脚 10px muted 文字（无分隔线、不加边框），署名固定 GENERATED BY SPECCORE TEAM · <年度>（动态跟随目标年度，如 GENERATED BY SPECCORE TEAM · 2026）
+- 页脚 10px muted 文字（无分隔线、不加边框），署名固定 GENERATED BY AI TEAM · <年度>（动态跟随目标年度，如 GENERATED BY AI TEAM · 2026）
 - 五段分节列表，条目保持中文顿号序号；md/txt 版同条目依次写，文本格式不变