skill-forge-hub 1.3.7 → 1.3.9

package/CHANGELOG.en.md

@@ -4,6 +4,24 @@
 
 Version history of the SkillForge npm package `skill-forge-hub` (command name `skill-forge`).
 
+## 1.3.9 (2026-11-13)
+
+**Theme-switch fade across twelve templates: 0.45s color transition instead of a hard flip**
+
+- Skin mechanism upgrade: clicking the theme dock / theme panel briefly adds a transient .theming class to <html> (auto-removed after 650ms), during which background/text/border/shadow/SVG fill-stroke colors transition smoothly at 0.45s — the switch now dissolves like ink; outside that window the class is absent, so existing element animations and hover effects stay untouched
+- Three guards: restoring a remembered theme on page load triggers no animation (no first-paint flicker); rapid consecutive theme clicks are debounced via timer reset; prefers-reduced-motion users get an instant switch (accessibility)
+- All template stamps bumped: daily/weekly/monthly/quarterly @2→3, annual/meeting-minutes @3→4, prompt-pouch @15→16, article-to-html @2→3, commit-heatmap/team-report-collector @1→2, one-pager @10→11, magic-deck @2→3 (say "upgrade my old pages" to remelt existing artifacts)
+
+## 1.3.8 (2026-11-13)
+
+**Data-collection config consolidation across seven report skills (five-suite v4 / meeting-minutes v3)**
+
+- Data source config (DATA_SOURCES / REPO) now lives only in user-config.md (upgrade-protected, never overwritten); mechanism docs (data-collection.md / content-rules.md / collect.md) get a "not a config zone" header, inline YAML examples removed, keeping only collection rules (type behaviors / git command templates / line-count filters / merge-dedup)
+- daily/weekly/monthly/quarterly/annual-report CONFIG_VERSION 3→4: first run after upgrade auto-prompts "data-collection config consolidated"; existing sources preserved as-is; sources mistakenly written in mechanism docs prompt manual relocation to user-config.md
+- meeting-minutes CONFIG_VERSION 2→3: source-material section gets placement note; DATA_SOURCES comments corrected to the actually supported type (file)
+- commit-heatmap / release-notes: placement note added atop collect.md (no config change, version untouched)
+- prompt-pouch-intro.md upgraded to illustrated edition: 10 pouch feature screenshots with ▲ interaction captions (images under docs/prompt-pouch-intro/, rendered directly on repo pages)
+
 ## 1.3.7 (2026-11-13)
 
 **prompt-pouch fixes theme dock covering fullscreen modal buttons (@15)**

package/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 SkillForge（技能锻造坊）npm 包 `skill-forge-hub`（命令名 `skill-forge`）版本变更记录。
 
+## 1.3.9（2026-11-13）
+
+**十二模板主题切换渐变：换肤不再生硬闪切，全页颜色 0.45s 平滑过渡**
+
+- 换肤机制升级：点击换肤坞/主题面板的瞬间给 <html> 挂瞬态 .theming 类（650ms 后自动摘除），期间全页背景/文字/边框/阴影/SVG 填充描边六项颜色属性以 0.45s 匀速渐变，切换如墨晕开；平时类不存在，各元素既有动画与 hover 零影响
+- 细节三保障：页面加载恢复记忆主题不触发动画（首屏不闪）；快速连点换肤计时器防抖互不打架；系统「减弱动态效果」偏好自动跳过渐变（无障碍惯例）
+- 版本戳全量 +1：日报/周报/月报/季报 @2→3、年报/会议纪要 @3→4、锦囊 @15→16、文章页 @2→3、热力图/收集台 @1→2、一页纸 @10→11、演示稿 @2→3（旧产物说「升级旧页面」即可回炉换新）
+
+## 1.3.8（2026-11-13）
+
+**报告七技能数据收集配置归位：配置落 user-config，机制文档收敛（五件套 v4 / 会议纪要 v3）**
+
+- 数据源配置统一归位：DATA_SOURCES / REPO 等数据收集配置一律只写 user-config.md（升级保护区，永不覆盖）；机制文档（data-collection.md / content-rules.md / collect.md）顶部加「不是配置区」定位声明，内置 YAML 清单示例移除，只留收集规则（type 行为 / git 命令模板 / 行数口径 / 合并去重）
+- 日报/周报/月报/季报/年报 CONFIG_VERSION 3→4：升级后首次执行自动提示「数据收集配置归位」，已填数据源原样保留；此前误写在机制文档里的数据源，提示手动搬回 user-config.md
+- 会议纪要 CONFIG_VERSION 2→3：素材来源节加定位声明，DATA_SOURCES 注释按实际支持类型（file）修正
+- 提交热力图 / 发版说明：collect.md 顶部补定位声明（配置无变化，版本不动）
+- 种草文 prompt-pouch-intro.md 升级图文版：嵌入 10 张锦囊功能截图与 ▲ 交互说明（配图落 docs/prompt-pouch-intro/，仓库页直接渲染）
+
 ## 1.3.7（2026-11-13）
 
 **prompt-pouch 修复全屏弹框按钮被换肤坞遮挡（@15）**

package/annual-report/SKILL.md

@@ -34,7 +34,7 @@ disable-model-invocation: false
 
 ## 配置版本机制（升级保护）
 
-本 skill 当前配置版本为 `3`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
+本 skill 当前配置版本为 `4`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
 1. 先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）
 2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
@@ -45,7 +45,7 @@ disable-model-invocation: false
 
 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
 
-当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释；DIR_MAC/DIR_WIN 默认值通用化——已配置用户保留原值不受影响）。
+当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释；DIR_MAC/DIR_WIN 默认值通用化——已配置用户保留原值不受影响）。v3→v4 数据收集配置归位：DATA_SOURCES 清单结构与已填值不变，仅澄清唯一配置落点——数据源一律只写 user-config.md「默认配置」的 DATA_SOURCES（升级保护区，永不覆盖）；resources/data-collection.md 收敛为纯机制说明（随升级覆盖，不再内置清单示例）。迁移动作：备份 user-config.md → CONFIG_VERSION 更新为 4，DATA_SOURCES 原样保留；若此前误把数据源写在 data-collection.md（升级后已被新版覆盖），请手动搬回 user-config.md。
 
 ## 文档同步自检纪律（维护者必读）
 
@@ -53,7 +53,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="annual-report@3">`（模板升级时递增 @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 或无版本戳的历史产物），说『把我旧年报都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="annual-report@4">`（模板升级时递增 @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 或无版本戳的历史产物），说『把我旧年报都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## 🔧 报修处理流程（用户报页面问题时）
 

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

@@ -1,25 +1,13 @@
 # 数据收集（年度）
 
+> ⚠️ **本文件是收集机制说明，不是配置区**——随 skill 升级会被官方版覆盖，写在这里的内容会丢。
+> 你的真实数据源只写在同目录外的 `user-config.md` 顶部「默认配置」的 `DATA_SOURCES` 数组（升级保护区，永不覆盖）。
+> 清单形状与逐字段填写说明，一律以 user-config.md「默认配置」的 DATA_SOURCES 注释为准，本文件不再重复清单示例。
+
 三种来源合并去重：口述与文字/文件/图片并重（业务结果以口述为准、统计数字以提交记录兜底）；没有提交记录也适用——给一段文字、文件里的描述或图片即可成稿。开发类用户可另做代码仓库全年提交聚合（见第 1 节）。
 
 ## 1. 代码仓库全年提交聚合（可选，开发类用户）
 
-清单形状（每项 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
@@ -32,7 +20,7 @@ DATA_SOURCES:
 
 - 用户口述的年度大事（「年初做了 X」「Q3 上了 Y」）逐条记录
 - 用户提供的总结草稿/文档（md/txt/docx）Read 提取要点；图片逐张 Read 识别内容
-- DATA_SOURCES 清单中 type: file 的文件 Read 全文、目录逐个 Read 文本文件提取要点（二进制跳过、路径无效静默跳过）；type: remote 只需 url 字段（mac/win 忽略）联网拉取内容提取要点（拉取失败静默跳过；仅收集时联网，HTML 产物仍零外链）；未知 type 忽略该项并在生成时提示
+- DATA_SOURCES 清单中 type: file 的文件 Read 全文、目录逐个 Read 文本文件提取要点（二进制跳过、路径无效静默跳过）；type: remote 按清单 url 联网拉取内容提取要点（拉取失败静默跳过；仅收集时联网，HTML 产物仍零外链）；未知 type 忽略该项并在生成时提示
 - 聊天记录/周报/日报/会议纪要文件也可作为素材（会议行动项可直接引用为成果依据）
 
 ## 3. 合并去重与口径

package/annual-report/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="sf-template" content="annual-report@3">
+<meta name="sf-template" content="annual-report@4">
 <meta name="annual-id" content="REF-ANNUAL-0000">
 <title>2026 研发年度总结</title>
 <style>
@@ -252,6 +252,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
   .header-card{ padding:26px 18px 20px; }
   .header-card h1{ font-size:26px; }
 }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -513,7 +517,7 @@ var SF_NS = 'annual:' + SF_ID;
   var saved = null; try{ saved = localStorage.getItem(SF_NS + '-theme') || localStorage.getItem('sf:' + location.pathname + '-theme'); }catch(e){}
   if (saved && THEMES.indexOf(saved) !== -1 && saved !== cur){ apply(saved); }
   else{ dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on', d.getAttribute('data-theme') === (cur || 'tech')); }); }
-  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ apply(d.getAttribute('data-theme')); }); });
+  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650); apply(d.getAttribute('data-theme')); }); });
 })();
 
 /* 滚动入场：初始视口外的卡片滚到视口才上浮渐显（首屏卡维持加载错峰动画）；无 JS 时 html.js 不生效全显 */

package/annual-report/user-config.md

@@ -10,7 +10,7 @@
 
 ```yaml
 DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
-CONFIG_VERSION: 3              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+CONFIG_VERSION: 4              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
 FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 内容区截图（五张分节卡片整体，不含头部标题/复制按钮/页脚），删除该项即不截图；不影响对话中的 md 正文输出）
 DIR: auto                      # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
 DIR_MAC: ~/reports                               # macOS 落盘根目录（自动按目标年度建子目录 annual-YYYY；目录不存在时回退用户主目录下 reports）
@@ -20,7 +20,7 @@ THEME: tech                    # html 页面主题：tech 深蓝科技（默认
 TEMPLATE: default              # 报告模板：default = 内置五段式（年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
 ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/里程碑/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
 CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
-DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
+DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。本清单是数据源唯一配置落点：resources/data-collection.md 只是收集机制说明（随升级覆盖），别把数据源写在那里。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
   # - name: 主项目仓库          # 名称：唯一 key（重名视为同一数据源；口述「只聚合 xxx」按 name 匹配）
   #   type: git                # git = 代码仓库（git log 聚合提交；路径不存在/非代码仓库时静默跳过）
   #   mac: ~/Projects/main-app  # macOS 路径（绝对路径或 ~ 开头）

package/article-to-html/SKILL.md

@@ -32,7 +32,7 @@ Turn any Word/Markdown/plain-text article into a standalone styled HTML page and
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="article-to-html@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧文章页换新样式」时：扫落盘目录下本技能生成的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="article-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/手改状态——html 与同目录 md 底稿正文对比，不一致视为可能手改过；无 md 底稿时标记「无法比对」）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从 md 底稿按当前 reference.html 重建（无 md 底稿则提取旧 html 正文重建），先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物（vN-1 或无版本戳的历史产物）主动告知「技能模板已升级至 vN，检测到 X 份旧版文章页，说『把我旧文章页都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="article-to-html@3">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧文章页换新样式」时：扫落盘目录下本技能生成的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="article-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/手改状态——html 与同目录 md 底稿正文对比，不一致视为可能手改过；无 md 底稿时标记「无法比对」）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从 md 底稿按当前 reference.html 重建（无 md 底稿则提取旧 html 正文重建），先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物（vN-1 或无版本戳的历史产物）主动告知「技能模板已升级至 vN，检测到 X 份旧版文章页，说『把我旧文章页都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## Prerequisites（新用户准备）
 

package/article-to-html/resources/reference.html

@@ -13,7 +13,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="article-to-html@2">
+<meta name="sf-template" content="article-to-html@3">
 <meta name="article-id" content="REF-ARTICLE-0000">
 <title>设计系统组件示范 · article-to-html</title>
 <style>
@@ -309,6 +309,10 @@ td.hl{font-weight:700;color:var(--ink)}
 .author p{font-size:13.5px;color:var(--ink-2);margin:0;line-height:1.7}
 
 .foot{text-align:center;padding:34px 0 44px;color:var(--ink-4);font-size:12.5px}
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -624,7 +628,7 @@ var SF_NS = 'article:' + SF_ID;
   try{ saved=localStorage.getItem(SF_NS + '-theme') || localStorage.getItem('sf:' + location.pathname + '-theme'); }catch(e){}
   if(saved && THEMES.indexOf(saved)!==-1 && saved!==cur){ apply(saved); }
   else{ dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on',d.getAttribute('data-theme')===(cur||'tech')); }); }
-  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click',function(){ apply(d.getAttribute('data-theme')); }); });
+  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click',function(){ var r=document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT=setTimeout(function(){ r.classList.remove('theming'); },650); apply(d.getAttribute('data-theme')); }); });
 })();
 </script>
 </body>

package/commit-heatmap/SKILL.md

@@ -51,7 +51,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="commit-heatmap@1">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧热力图/回炉」时：扫落盘目录读版本戳筛旧版（无版本戳或缺少 `<meta name="heat-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）重新跑 git 收集按当前 reference.html 重建，先备份旧版 `.bak-时间戳`，重建必须沿用原页 heat-id meta 值（换 ID = 主题记忆失联）→ 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动、数据格式改动、页面改动任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知用户「说『把我旧热力图都升级成新样式』即可一键升级」。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="commit-heatmap@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧热力图/回炉」时：扫落盘目录读版本戳筛旧版（无版本戳或缺少 `<meta name="heat-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）重新跑 git 收集按当前 reference.html 重建，先备份旧版 `.bak-时间戳`，重建必须沿用原页 heat-id meta 值（换 ID = 主题记忆失联）→ 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动、数据格式改动、页面改动任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知用户「说『把我旧热力图都升级成新样式』即可一键升级」。
 
 ## 规则速览
 

package/commit-heatmap/resources/collect.md

@@ -1,5 +1,8 @@
 # 收集数据（阶段 1）
 
+> ⚠️ 本文件是收集机制说明，不是配置区——随 skill 升级会被官方版覆盖。git 仓库等配置（REPO/DAYS/EXCLUDE 等）只写在同目录外的 `user-config.md`（升级保护区，永不覆盖）。
+
+
 ## 聚合命令
 
 ```bash

package/commit-heatmap/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="commit-heatmap@1">
+<meta name="sf-template" content="commit-heatmap@2">
 <meta name="heat-id" content="REF-HEAT-0000">
 <title>提交热力图 · 示例项目</title>
 <style>
@@ -74,6 +74,10 @@ body{background:var(--bg);color:var(--text);font-family:system-ui,'Segoe UI',Rob
 .th-dot.on{border-color:var(--today-ring)}
 footer{text-align:center;color:var(--muted);font-size:10px;margin-top:26px}
 html[data-shot] .card{animation:none!important}
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -141,6 +145,7 @@ window.HEAT_STATS = {total:486, streak:12, active:"62%", topDay:"2026-11-05", to
   document.querySelectorAll('.th-dot').forEach(function(d){
     d.addEventListener('click', function(){
       var t = d.getAttribute('data-t');
+      var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650);
       document.documentElement.setAttribute('data-theme', t);
       localStorage.setItem(THEME_KEY, t);
       document.querySelectorAll('.th-dot').forEach(function(x){ x.classList.toggle('on', x === d); });

package/daily-report/SKILL.md

@@ -34,7 +34,7 @@ disable-model-invocation: false
 
 ## 配置版本机制（升级保护）
 
-本 skill 当前配置版本为 `3`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
+本 skill 当前配置版本为 `4`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
 1. 先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）
 2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
@@ -45,7 +45,7 @@ disable-model-invocation: false
 
 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
 
-当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释；DIR_MAC/DIR_WIN 默认值通用化——已配置用户保留原值不受影响）。
+当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释；DIR_MAC/DIR_WIN 默认值通用化——已配置用户保留原值不受影响）。v3→v4 数据收集配置归位：DATA_SOURCES 清单结构与已填值不变，仅澄清唯一配置落点——数据源一律只写 user-config.md「默认配置」的 DATA_SOURCES（升级保护区，永不覆盖）；resources/data-collection.md 收敛为纯机制说明（随升级覆盖，不再内置清单示例）。迁移动作：备份 user-config.md → CONFIG_VERSION 更新为 4，DATA_SOURCES 原样保留；若此前误把数据源写在 data-collection.md（升级后已被新版覆盖），请手动搬回 user-config.md。
 
 ## 文档同步自检纪律（维护者必读）
 
@@ -53,7 +53,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="daily-report@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧日报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="daily-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版日报（vN-1 或无版本戳的历史产物），说『把我旧日报都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="daily-report@3">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧日报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="daily-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版日报（vN-1 或无版本戳的历史产物），说『把我旧日报都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## 🔧 报修处理流程（用户报页面问题时）
 

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

@@ -1,27 +1,16 @@
 # 数据收集
 
-先检测当前系统（macOS：`uname -s` 返回 Darwin；Windows：`node -e "console.log(process.platform)"` 返回 win32），再 Read 同目录外的 `user-config.md` 顶部「默认配置」的 DATA_SOURCES 清单，按清单逐项收集（空清单 = 只按会话/文字内容生成）。清单形状（每项 name 唯一名称 + type 类型 + 路径；完整填写说明见 user-config.md「默认配置」的 DATA_SOURCES 注释）：
+> ⚠️ **本文件是收集机制说明，不是配置区**——随 skill 升级会被官方版覆盖，写在这里的内容会丢。
+> 你的真实数据源只写在同目录外的 `user-config.md` 顶部「默认配置」的 `DATA_SOURCES` 数组（升级保护区，永不覆盖）。
+> 清单形状与逐字段填写说明，一律以 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
-```
+先检测当前系统（macOS：`uname -s` 返回 Darwin；Windows：`node -e "console.log(process.platform)"` 返回 win32），再 Read 同目录外的 `user-config.md` 顶部「默认配置」的 DATA_SOURCES 清单，按清单逐项收集（空清单 = 只按会话/文字内容生成）。
 
 每项按 type 分三种行为：
 
 - git = 代码仓库：取 mac / win 中当前系统对应路径（「-」= 该系统不存在，跳过；当前系统全部为「-」的陌生机器时跳过 git 收集，只按会话/文字内容生成），用下方命令模板聚合该仓当日提交，只汇总有提交的仓库
 - file = 普通文件/目录：路径指向文件 → Read 全文提取要点；指向目录 → 列目录逐个 Read 文本文件（md/txt/csv/日志等，二进制/超大文件跳过）；路径无效或全部不可读 → 静默跳过该数据源（不报错、不写入）
-- remote = 远程网络源：只需 url 字段（mac/win 忽略）；AI 联网拉取 url 内容（网页或数据接口均可）提取要点；拉取失败/超时 → 静默跳过该数据源不阻塞生成；仅收集时联网，HTML 产物仍零外链
+- remote = 远程网络源：按清单 url 联网拉取内容（网页或数据接口均可）提取要点；拉取失败/超时 → 静默跳过该数据源不阻塞生成；仅收集时联网，HTML 产物仍零外链
 - 未知 type（拼写错误/未支持）→ 忽略该项，生成时一句话提示用户该项未识别（不猜、不中断）
 - 多来源合并：同件事去重合并——量化数字以 git 提交统计为准、定性描述以口述/文件要点为准；file/remote 提取要点与口述同等对待
 

package/daily-report/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="daily-report@2">
+<meta name="sf-template" content="daily-report@3">
 <meta name="daily-id" content="REF-DAILY-0000">
 <title>今日日报 - 20261106</title>
 <style>
@@ -406,6 +406,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
   .header-card{ padding:26px 18px 20px; }
   .header-card h1{ font-size:26px; }
 }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -762,7 +766,7 @@ var SF_NS = 'daily:' + SF_ID;
     });
   }
   dock.querySelectorAll('.th-dot').forEach(function(d){
-    d.addEventListener('click', function(){ apply(d.getAttribute('data-theme')); });
+    d.addEventListener('click', function(){ var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650); apply(d.getAttribute('data-theme')); });
   });
 })();
 /* 滚动入场：初始视口外的卡片滚到视口才上浮渐显（首屏卡维持加载错峰动画）；无 JS 时 html.js 不生效全显 */

package/daily-report/user-config.md

@@ -10,7 +10,7 @@
 
 ```yaml
 DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
-CONFIG_VERSION: 3              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+CONFIG_VERSION: 4              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
 FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 整页内容区截图（头部标题卡片 + 今日任务进度/明日计划/风险阻塞点三张分节卡片整体截出，头部卡片必须带上），删除该项即不截图；不影响对话中的 md 正文输出）
 DIR: auto                      # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
 DIR_MAC: ~/reports                               # macOS 落盘根目录（自动按目标日期建子目录；目录不存在时回退用户主目录下 reports）
@@ -20,7 +20,7 @@ THEME: tech                    # html 页面主题：tech 深蓝科技（默认
 TEMPLATE: default              # 报告模板：default = 内置三段式（任务进度/明日计划/风险阻塞点）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
 ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/节奏条/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
 CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
-DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
+DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。本清单是数据源唯一配置落点：resources/data-collection.md 只是收集机制说明（随升级覆盖），别把数据源写在那里。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
   # - name: 主项目仓库          # 名称：唯一 key（重名视为同一数据源；口述「只聚合 xxx」按 name 匹配）
   #   type: git                # git = 代码仓库（git log 聚合提交；路径不存在/非代码仓库时静默跳过）
   #   mac: ~/Projects/main-app  # macOS 路径（绝对路径或 ~ 开头）

package/magic-deck/SKILL.md

@@ -76,7 +76,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="magic-deck@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧演示稿换新样式」时：扫落盘目录下本技能生成的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="deck-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/手改状态——deck 是单文件产物无 md 底稿，标记「无底稿，正文保留」）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文与 slide 内容原样保留；深升级（DOM 结构变化）提取旧页 slide 内容按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物（vN-1 或无版本戳的历史产物）主动告知「技能模板已升级至 vN，检测到 X 份旧版演示稿，说『把我旧演示稿都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="magic-deck@3">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧演示稿换新样式」时：扫落盘目录下本技能生成的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="deck-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/手改状态——deck 是单文件产物无 md 底稿，标记「无底稿，正文保留」）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文与 slide 内容原样保留；深升级（DOM 结构变化）提取旧页 slide 内容按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物（vN-1 或无版本戳的历史产物）主动告知「技能模板已升级至 vN，检测到 X 份旧版演示稿，说『把我旧演示稿都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## 📏 文档同步自检纪律（维护者必读）
 

package/magic-deck/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="magic-deck@2">
+<meta name="sf-template" content="magic-deck@3">
 <meta name="deck-id" content="REF-DECK-0000">
 <title>Reference 骨架 — magic-deck 定稿样例</title>
 <style>
@@ -784,6 +784,10 @@ body:hover .nav{ opacity:1; }
   .slide [data-anim-chart] .pt{ opacity:1 !important; }
 }
 
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -1348,6 +1352,7 @@ themeGrid.addEventListener('click', function(e){
   var it = e.target.closest('.th-item');
   if (!it) return;
   pushUndo();
+  var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650);
   var sc = themeMask.querySelector('input[name="thScope"]:checked');
   if (sc && sc.value === 'current') setSlideTheme(it.getAttribute('data-theme'));
   else setGlobalTheme(it.getAttribute('data-theme'));

package/meeting-minutes/SKILL.md

@@ -25,7 +25,7 @@ disable-model-invocation: false
 
 ## 配置版本机制（升级保护）
 
-本 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.bak-<时间戳>.md`（同目录，绝不删除旧值）
 2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
@@ -34,11 +34,13 @@ disable-model-invocation: false
 
 配置升级规则（v1→v2）：新增 `SERIES_GROUP: auto`（纪要系列分组，见 user-config.md 注释）；其余字段不变。
 
+配置升级规则（v2→v3）：DATA_SOURCES 数据收集配置归位——清单结构与已填值不变，仅澄清唯一配置落点（数据源一律只写 user-config.md「默认配置」的 DATA_SOURCES，升级保护区永不覆盖；收集机制说明见 resources/content-rules.md「素材来源」节，随升级覆盖）；DATA_SOURCES 示例注释按实际支持类型（file）修正。迁移动作：备份 user-config.md → CONFIG_VERSION 更新为 3，DATA_SOURCES 原样保留；若此前误把数据源写在 resources 文档里（升级后已被新版覆盖），请手动搬回 user-config.md。
+
 **无法迁移项处理**：值域失效（旧值不在新值域）/ 语义漂移（同名键含义变化）/ 数据不兼容，停下问、不猜值；旧值永远在 .bak-时间戳备份里，报告必附回滚一句话。
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="meeting-minutes@3">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧纪要换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="minutes-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版纪要（vN-1 或无版本戳的历史产物），说『把我旧纪要都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="meeting-minutes@4">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧纪要换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="minutes-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版纪要（vN-1 或无版本戳的历史产物），说『把我旧纪要都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## 规则速览
 

package/meeting-minutes/resources/content-rules.md

@@ -43,6 +43,8 @@
 
 ## 素材来源
 
+> ⚠️ 个人数据源只写在同目录外的 `user-config.md` 顶部「默认配置」的 `DATA_SOURCES` 数组（升级保护区，永不覆盖）；本文件随 skill 升级被官方覆盖，别把数据源写在这里。
+
 - 会话口述：用户直接口述会议过程（「会上说了三件事…」）逐条记录
 - 文字材料：用户贴的会议文字/聊天记录，按五段归类
 - 文件：md/txt 直接 Read 文本；docx/pdf 优先尝试 pandoc 转文本（无 pandoc 则请用户粘贴文字）；录音/视频文件不能直接解析——提示用户提供转写文本，或引导用户口述要点

package/meeting-minutes/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="sf-template" content="meeting-minutes@3">
+<meta name="sf-template" content="meeting-minutes@4">
 <meta name="minutes-id" content="REF-MINUTES-0000">
 <title>示例项目 周例会纪要</title>
 <style>
@@ -209,6 +209,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
   .section{ padding:20px 14px 20px 22px; }
   .act-table th:nth-child(2), .act-table td:nth-child(2){ display:none; }
 }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -392,6 +396,7 @@ var SF_NS = 'minutes:' + SF_ID;
   dots.forEach(function(d){
     d.addEventListener('click', function(){
       var t = d.getAttribute('data-theme');
+      var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650);
       document.documentElement.setAttribute('data-theme', t);
       try { localStorage.setItem(SF_NS + '-theme', t); } catch(e){}
       mark();

package/meeting-minutes/user-config.md

@@ -10,7 +10,7 @@
 
 ```yaml
 DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
-CONFIG_VERSION: 2              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+CONFIG_VERSION: 3              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
 FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 内容区截图（五张分节卡片整体，不含头部标题/复制按钮/页脚），删除该项即不截图；不影响对话中的 md 正文输出）
 SERIES_GROUP: auto             # 纪要系列分组：auto = 提取到稳定系列名（如「产品周例会」）时建系列目录 meetings/{系列名}/，未提取到则回退月份平铺 meetings/YYYY-MM/；series = 一律建系列目录（提取不到就用会议主题做目录名）；off = 纯月份平铺（旧行为）。系列名落盘确认时报给用户，可改口（说「这个系列叫 XX」→ 当次改目录名；说「以后这个系列叫 XX」→ 永久记住该系列名）
 DIR: auto                      # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
@@ -21,7 +21,7 @@ THEME: tech                    # html 页面主题：tech 深蓝科技（默认
 TEMPLATE: default              # 纪要模板：default = 内置五段式（会议信息/会议结论/议题讨论/决议与行动项/下次会议）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
 ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，会议类型推断/术语/行动项模板全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
 CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
-DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
+DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。本清单是数据源唯一配置落点：resources/content-rules.md「素材来源」节只是收集机制说明（随升级覆盖），别把数据源写在那里。本 skill 仅支持 type: file（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
   # - name: 会议速记目录        # 名称：唯一 key（重名视为同一数据源；口述「只整理 xxx」按 name 匹配）
   #   type: file                # file = 普通文件/目录（文件 Read 全文、目录逐个 Read 文本文件，二进制跳过；路径无效静默跳过）
   #   mac: ~/Documents/meetings  # macOS 路径（绝对路径或 ~ 开头）

package/monthly-report/SKILL.md

@@ -34,15 +34,15 @@ disable-model-invocation: false
 
 ## 配置版本机制（升级保护）
 
-本 skill 当前配置版本为 `3`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）→ 按本节「当前版本变更记录」迁移字段（新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认）→ 更新 CONFIG_VERSION 为当前版本 → 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」。禁止在未声明版本变更的情况下静默修改配置语义。
+本 skill 当前配置版本为 `4`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）→ 按本节「当前版本变更记录」迁移字段（新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认）→ 更新 CONFIG_VERSION 为当前版本 → 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」。禁止在未声明版本变更的情况下静默修改配置语义。
 
 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话。
 
-当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释）。
+当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释）。v3→v4 数据收集配置归位：DATA_SOURCES 清单结构与已填值不变，仅澄清唯一配置落点——数据源一律只写 user-config.md「默认配置」的 DATA_SOURCES（升级保护区，永不覆盖）；resources/data-collection.md 收敛为纯机制说明（随升级覆盖，不再内置清单示例）。迁移动作：备份 user-config.md → CONFIG_VERSION 更新为 4，DATA_SOURCES 原样保留；若此前误把数据源写在 data-collection.md（升级后已被新版覆盖），请手动搬回 user-config.md。
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="monthly-report@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧月报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="monthly-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版月报（vN-1 或无版本戳的历史产物），说『把我旧月报都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="monthly-report@3">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧月报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="monthly-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版月报（vN-1 或无版本戳的历史产物），说『把我旧月报都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## 🔧 报修处理流程（用户报页面问题时）
 

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

@@ -1,25 +1,13 @@
 # 数据收集（月度）
 
+> ⚠️ **本文件是收集机制说明，不是配置区**——随 skill 升级会被官方版覆盖，写在这里的内容会丢。
+> 你的真实数据源只写在同目录外的 `user-config.md` 顶部「默认配置」的 `DATA_SOURCES` 数组（升级保护区，永不覆盖）。
+> 清单形状与逐字段填写说明，一律以 user-config.md「默认配置」的 DATA_SOURCES 注释为准，本文件不再重复清单示例。
+
 三种来源合并去重：口述与文字/文件/图片并重（业务结果以口述为准、统计数字以提交记录兜底）；没有提交记录也适用——给一段文字、文件里的描述或图片即可成稿。开发类用户可另做代码仓库当月提交聚合（见第 1 节）。
 
 ## 1. 代码仓库当月提交聚合（可选，开发类用户）
 
-清单形状（每项 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={月末 23:59} --oneline | wc -l`
   - 增删行数：`git log --since=... --until=... --numstat --pretty=tformat: | awk` 汇总 add/del
@@ -33,7 +21,7 @@ DATA_SOURCES:
 
 - 用户口述的月度大事（「这个月上了 XX」「月初做了 YY」）逐条记录
 - 用户提供的总结草稿/文档（md/txt/docx）Read 提取要点；图片逐张 Read 识别内容
-- DATA_SOURCES 清单中 type: file 的文件 Read 全文、目录逐个 Read 文本文件提取要点（二进制跳过、路径无效静默跳过）；type: remote 只需 url 字段（mac/win 忽略）联网拉取内容提取要点（拉取失败静默跳过；仅收集时联网，HTML 产物仍零外链）；未知 type 忽略该项并在生成时提示
+- DATA_SOURCES 清单中 type: file 的文件 Read 全文、目录逐个 Read 文本文件提取要点（二进制跳过、路径无效静默跳过）；type: remote 按清单 url 联网拉取内容提取要点（拉取失败静默跳过；仅收集时联网，HTML 产物仍零外链）；未知 type 忽略该项并在生成时提示
 - 聊天记录/周报/日报/会议纪要文件也可作为素材；本月已生成的周报/日报直接引用其核心指标（同源数据不重复统计）
 
 ## 3. 合并去重与口径

package/monthly-report/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="sf-template" content="monthly-report@2">
+<meta name="sf-template" content="monthly-report@3">
 <meta name="monthly-id" content="REF-MONTHLY-0000">
 <title>2026-11 研发月度总结</title>
 <style>
@@ -250,6 +250,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
   .header-card{ padding:26px 18px 20px; }
   .header-card h1{ font-size:26px; }
 }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -492,7 +496,7 @@ var SF_NS = 'monthly:' + SF_ID;
   var saved = null; try{ saved = localStorage.getItem(SF_NS + '-theme') || localStorage.getItem('sf:' + location.pathname + '-theme'); }catch(e){}
   if (saved && THEMES.indexOf(saved) !== -1 && saved !== cur){ apply(saved); }
   else{ dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on', d.getAttribute('data-theme') === (cur || 'tech')); }); }
-  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ apply(d.getAttribute('data-theme')); }); });
+  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650); apply(d.getAttribute('data-theme')); }); });
 })();
 
 /* 滚动入场：初始视口外的卡片滚到视口才上浮渐显（首屏卡维持加载错峰动画）；无 JS 时 html.js 不生效全显 */

package/monthly-report/user-config.md

@@ -10,7 +10,7 @@
 
 ```yaml
 DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
-CONFIG_VERSION: 3              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+CONFIG_VERSION: 4              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
 FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 内容区截图（四张分节卡片整体，不含头部标题/复制按钮/页脚），删除该项即不截图；不影响对话中的 md 正文输出）
 DIR: auto                      # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
 DIR_MAC: ~/reports                               # macOS 落盘根目录（自动按目标月份建子目录 2026-11 式样；目录不存在时回退用户主目录下 reports）
@@ -20,7 +20,7 @@ THEME: tech                    # html 页面主题：tech 深蓝科技（默认
 TEMPLATE: default              # 报告模板：default = 内置四段式（月度概览/本月关键成果/问题与改进/下月计划）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
 ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/里程碑/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
 CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
-DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
+DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。本清单是数据源唯一配置落点：resources/data-collection.md 只是收集机制说明（随升级覆盖），别把数据源写在那里。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
   # - name: 主项目仓库          # 名称：唯一 key（重名视为同一数据源；口述「只聚合 xxx」按 name 匹配）
   #   type: git                # git = 代码仓库（git log 聚合提交；路径不存在/非代码仓库时静默跳过）
   #   mac: ~/Projects/main-app  # macOS 路径（绝对路径或 ~ 开头）

package/one-pager/SKILL.md

@@ -62,7 +62,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="one-pager@10">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧海报/回炉」时：顺扫海报库根目录（DIR 值）下两种形态——新子目录形态 `<slug>/poster.html` 与旧平铺形态 `poster-*.html`，读版本戳筛旧版（无版本戳或缺少 `<meta name="poster-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳`，重建必须沿用原页 poster-id meta 值（换 ID = 模板/主题记忆失联）→ 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动、数据格式改动、页面改动任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知用户「说『把我旧海报都升级成新样式』即可一键升级」。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="one-pager@11">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧海报/回炉」时：顺扫海报库根目录（DIR 值）下两种形态——新子目录形态 `<slug>/poster.html` 与旧平铺形态 `poster-*.html`，读版本戳筛旧版（无版本戳或缺少 `<meta name="poster-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳`，重建必须沿用原页 poster-id meta 值（换 ID = 模板/主题记忆失联）→ 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动、数据格式改动、页面改动任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知用户「说『把我旧海报都升级成新样式』即可一键升级」。
 
 ## 规则速览
 

package/one-pager/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="one-pager@10">
+<meta name="sf-template" content="one-pager@11">
 <meta name="poster-id" content="REF-POSTER-0000">
 <title>AI 改变工作 · 一页纸海报</title>
 <style>
@@ -697,6 +697,10 @@ html[data-shot] .dock-tpl,html[data-shot] .dock-theme{display:none!important}
   .tp-btn{font-size:11px;padding:4px 8px}
   .dock-body{max-width:calc(100vw - 36px)}
 }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -1208,6 +1212,7 @@ html[data-shot] .dock-tpl,html[data-shot] .dock-theme{display:none!important}
     d.addEventListener('click', function(){
       var t = d.getAttribute('data-t');
       curT = t;
+      var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650);
       document.documentElement.setAttribute('data-theme', t);
       try { localStorage.setItem(THEME_KEY, t); } catch(e) {}
       TH_DOTS.forEach(function(x){ x.classList.toggle('on', x === d); });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-forge-hub",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "SkillForge (技能锻造坊) — a curated collection of AI craft skills. Install once, then pick skills interactively: daily/weekly/monthly/quarterly/annual reports, meeting minutes, article-to-HTML, magic-deck slides, deck-stage PPTX, prompt-pouch manager, Pandoc doc converters, meta-forge.",
   "bin": {
     "skill-forge": "cli.js"

package/prompt-pouch/SKILL.md

@@ -78,7 +78,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成/初始化页面时头部写版本戳 `<meta name="sf-template" content="prompt-pouch@15">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧锦囊/回炉旧页面/旧锦囊换新样式」时：扫 `<DIR>` 下 `prompt-pouch.html` 读版本戳筛出旧版（无版本戳或缺少 `<meta name="pouch-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/有无用户数据）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本；深升级（DOM 结构变化）从 reference.html 重建，**必须沿用原页 pouch-id meta 值**（IndexedDB 用户数据按 pouch-id 命名空间存取，换 ID = 数据失联，重建后原收藏/分组照旧读回），`<DIR>/<DATA_DIR>/prompts.json` 数据文件一概不动，先备份旧页 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成/初始化新锦囊时顺扫 `<DIR>` 读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版锦囊，说『把我旧锦囊都升级成新样式』即可一键升级」，不让用户背触发语。
+生成/初始化页面时头部写版本戳 `<meta name="sf-template" content="prompt-pouch@16">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧锦囊/回炉旧页面/旧锦囊换新样式」时：扫 `<DIR>` 下 `prompt-pouch.html` 读版本戳筛出旧版（无版本戳或缺少 `<meta name="pouch-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/有无用户数据）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本；深升级（DOM 结构变化）从 reference.html 重建，**必须沿用原页 pouch-id meta 值**（IndexedDB 用户数据按 pouch-id 命名空间存取，换 ID = 数据失联，重建后原收藏/分组照旧读回），`<DIR>/<DATA_DIR>/prompts.json` 数据文件一概不动，先备份旧页 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成/初始化新锦囊时顺扫 `<DIR>` 读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版锦囊，说『把我旧锦囊都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## ⚙️ 配置与自定义主题
 

package/prompt-pouch/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="prompt-pouch@15">
+<meta name="sf-template" content="prompt-pouch@16">
 <meta name="pouch-id" content="REF-POUCH-0000">
 <title>锦囊 Prompt Pouch — 提示词管理台</title>
 <style>
@@ -691,6 +691,10 @@ footer.open .ht-arrow{ transform:rotate(180deg); }
 .theme-dock .th-dot[data-theme="light"]{ background:#ffffff; }
 .theme-dock .th-dot[data-theme="mint"]{ background:#4ade80; }
 @media print{ .theme-dock{ display:none; } }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -2696,7 +2700,7 @@ var SF_NS = 'pouch:' + POUCH_ID;
       });
     }
     dock.querySelectorAll('.th-dot').forEach(function(d){
-      d.addEventListener('click', function(){ apply(d.getAttribute('data-theme')); });
+      d.addEventListener('click', function(){ var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650); apply(d.getAttribute('data-theme')); });
     });
   }
   if (document.readyState === 'loading'){ document.addEventListener('DOMContentLoaded', init); }

package/quarterly-report/SKILL.md

@@ -34,15 +34,15 @@ disable-model-invocation: false
 
 ## 配置版本机制（升级保护）
 
-本 skill 当前配置版本为 `3`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）→ 按本节「当前版本变更记录」迁移字段（新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认）→ 更新 CONFIG_VERSION 为当前版本 → 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」。禁止在未声明版本变更的情况下静默修改配置语义。
+本 skill 当前配置版本为 `4`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）→ 按本节「当前版本变更记录」迁移字段（新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认）→ 更新 CONFIG_VERSION 为当前版本 → 对话中明确告知用户「检测到配置版本从 X 升级到 Y，旧配置已备份至 <路径>」。禁止在未声明版本变更的情况下静默修改配置语义。
 
 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话。
 
-当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释）。
+当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释）。v3→v4 数据收集配置归位：DATA_SOURCES 清单结构与已填值不变，仅澄清唯一配置落点——数据源一律只写 user-config.md「默认配置」的 DATA_SOURCES（升级保护区，永不覆盖）；resources/data-collection.md 收敛为纯机制说明（随升级覆盖，不再内置清单示例）。迁移动作：备份 user-config.md → CONFIG_VERSION 更新为 4，DATA_SOURCES 原样保留；若此前误把数据源写在 data-collection.md（升级后已被新版覆盖），请手动搬回 user-config.md。
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="quarterly-report@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧季报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="quarterly-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版季报（vN-1 或无版本戳的历史产物），说『把我旧季报都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="quarterly-report@3">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧季报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="quarterly-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版季报（vN-1 或无版本戳的历史产物），说『把我旧季报都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## 🔧 报修处理流程（用户报页面问题时）
 

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

@@ -1,25 +1,13 @@
 # 数据收集（季度）
 
+> ⚠️ **本文件是收集机制说明，不是配置区**——随 skill 升级会被官方版覆盖，写在这里的内容会丢。
+> 你的真实数据源只写在同目录外的 `user-config.md` 顶部「默认配置」的 `DATA_SOURCES` 数组（升级保护区，永不覆盖）。
+> 清单形状与逐字段填写说明，一律以 user-config.md「默认配置」的 DATA_SOURCES 注释为准，本文件不再重复清单示例。
+
 三种来源合并去重：口述与文字/文件/图片并重（业务结果以口述为准、统计数字以提交记录兜底）；没有提交记录也适用——给一段文字、文件里的描述或图片即可成稿。开发类用户可另做代码仓库当季提交聚合与环比/同比双基准统计（见第 1 节）。
 
 ## 1. 代码仓库当季提交聚合（可选，开发类用户）
 
-清单形状（每项 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={季末 23:59} --oneline | wc -l`
   - 增删行数：`git log --since=... --until=... --numstat --pretty=tformat: | awk` 汇总 add/del
@@ -35,7 +23,7 @@ DATA_SOURCES:
 
 - 用户口述的季度大事（「这季度上了 XX」「Q4 初做了 YY」）逐条记录
 - 用户提供的总结草稿/文档（md/txt/docx）Read 提取要点；图片逐张 Read 识别内容
-- DATA_SOURCES 清单中 type: file 的文件 Read 全文、目录逐个 Read 文本文件提取要点（二进制跳过、路径无效静默跳过）；type: remote 只需 url 字段（mac/win 忽略）联网拉取内容提取要点（拉取失败静默跳过；仅收集时联网，HTML 产物仍零外链）；未知 type 忽略该项并在生成时提示
+- DATA_SOURCES 清单中 type: file 的文件 Read 全文、目录逐个 Read 文本文件提取要点（二进制跳过、路径无效静默跳过）；type: remote 按清单 url 联网拉取内容提取要点（拉取失败静默跳过；仅收集时联网，HTML 产物仍零外链）；未知 type 忽略该项并在生成时提示
 - 聊天记录/周报/月报/会议纪要文件也可作为素材；本季度已生成的月报直接引用其核心指标（同源数据不重复统计）
 
 ## 3. 合并去重与口径

package/quarterly-report/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="sf-template" content="quarterly-report@2">
+<meta name="sf-template" content="quarterly-report@3">
 <meta name="quarterly-id" content="REF-QUARTERLY-0000">
 <title>2026-Q4 研发季度总结</title>
 <style>
@@ -230,6 +230,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
   .header-card{ padding:26px 18px 20px; }
   .header-card h1{ font-size:26px; }
 }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -470,7 +474,7 @@ var SF_NS = 'quarterly:' + SF_ID;
   var saved = null; try{ saved = localStorage.getItem(SF_NS + '-theme') || localStorage.getItem('sf:' + location.pathname + '-theme'); }catch(e){}
   if (saved && THEMES.indexOf(saved) !== -1 && saved !== cur){ apply(saved); }
   else{ dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on', d.getAttribute('data-theme') === (cur || 'tech')); }); }
-  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ apply(d.getAttribute('data-theme')); }); });
+  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650); apply(d.getAttribute('data-theme')); }); });
 })();
 
 /* 滚动入场：初始视口外的卡片滚到视口才上浮渐显（首屏卡维持加载错峰动画）；无 JS 时 html.js 不生效全显 */

package/quarterly-report/user-config.md

@@ -10,7 +10,7 @@
 
 ```yaml
 DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
-CONFIG_VERSION: 3              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+CONFIG_VERSION: 4              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
 FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 内容区截图（四张分节卡片整体，不含头部标题/复制按钮/页脚），删除该项即不截图；不影响对话中的 md 正文输出）
 DIR: auto                      # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
 DIR_MAC: ~/reports                               # macOS 落盘根目录（自动按目标季度建子目录 2026-Q4 式样；目录不存在时回退用户主目录下 reports）
@@ -20,7 +20,7 @@ THEME: tech                    # html 页面主题：tech 深蓝科技（默认
 TEMPLATE: default              # 报告模板：default = 内置四段式（季度概览/季度关键成果/问题与改进/下季度计划）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
 ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/里程碑/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
 CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
-DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
+DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。本清单是数据源唯一配置落点：resources/data-collection.md 只是收集机制说明（随升级覆盖），别把数据源写在那里。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
   # - name: 主项目仓库          # 名称：唯一 key（重名视为同一数据源；口述「只聚合 xxx」按 name 匹配）
   #   type: git                # git = 代码仓库（git log 聚合提交；路径不存在/非代码仓库时静默跳过）
   #   mac: ~/Projects/main-app  # macOS 路径（绝对路径或 ~ 开头）

package/release-notes/resources/collect.md

@@ -1,5 +1,8 @@
 # 收集提交（阶段 1）
 
+> ⚠️ 本文件是收集机制说明，不是配置区——随 skill 升级会被官方版覆盖。git 仓库等配置（REPO/SCOPE_HINT 等）只写在同目录外的 `user-config.md`（升级保护区，永不覆盖）。
+
+
 ## 区间口径（三档，先判断再收集）
 
 1. **双 tag**：`git log vA..vB --oneline`——vA 为上一版本标签，vB 为本次发布标签（vB 可缺省为 HEAD）

package/team-report-collector/SKILL.md

@@ -51,7 +51,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="team-report-collector@1">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧收集台/回炉」时：扫落盘目录读版本戳筛旧版（无版本戳或缺少 `<meta name="trc-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）从同目录 reports.json 数据按当前 reference.html 重建，先备份旧版 `.bak-时间戳`，重建必须沿用原页 trc-id meta 值（换 ID = 页面运行时收集的本地数据失联）→ 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动、数据格式改动、页面改动任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知用户「说『把我旧收集台都升级成新样式』即可一键升级」。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="team-report-collector@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧收集台/回炉」时：扫落盘目录读版本戳筛旧版（无版本戳或缺少 `<meta name="trc-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文原样保留；深升级（DOM 结构变化）从同目录 reports.json 数据按当前 reference.html 重建，先备份旧版 `.bak-时间戳`，重建必须沿用原页 trc-id meta 值（换 ID = 页面运行时收集的本地数据失联）→ 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动、数据格式改动、页面改动任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知用户「说『把我旧收集台都升级成新样式』即可一键升级」。
 
 ## 规则速览
 

package/team-report-collector/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="team-report-collector@1">
+<meta name="sf-template" content="team-report-collector@2">
 <meta name="trc-id" content="REF-TRC-0000">
 <title>示例团队日报收集台</title>
 <style>
@@ -190,6 +190,10 @@ footer{text-align:center;color:var(--muted);font-size:10px;margin-top:26px}
 html[data-shot] .card{animation:none!important}
 @media (max-width:680px){body{padding:24px 12px}.wrap{width:100%}.row2{grid-template-columns:1fr}.header-card h1{font-size:18px}}
 @media print{.theme-dock,.btn{display:none}}
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -361,7 +365,7 @@ window.TRC_DATA = [
   var initial = (savedTheme && THEMES.indexOf(savedTheme) !== -1) ? savedTheme : 'tech';
   applyTheme(initial);
   dock.querySelectorAll('.th-dot').forEach(function(d){
-    d.addEventListener('click', function(){ applyTheme(d.getAttribute('data-theme')); });
+    d.addEventListener('click', function(){ var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650); applyTheme(d.getAttribute('data-theme')); });
   });
   document.getElementById('d-badge').textContent = '2026-11-12';
   if (location.search.indexOf('shot') !== -1) {

package/weekly-report/SKILL.md

@@ -34,7 +34,7 @@ disable-model-invocation: false
 
 ## 配置版本机制（升级保护）
 
-本 skill 当前配置版本为 `3`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
+本 skill 当前配置版本为 `4`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
 1. 先将旧 user-config.md 备份为 `user-config.bak-<时间戳>.md`（同目录，绝不删除旧值）
 2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
@@ -45,7 +45,7 @@ disable-model-invocation: false
 
 **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
 
-当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释；DIR_MAC/DIR_WIN 默认值通用化——已配置用户保留原值不受影响）。
+当前版本变更记录：v1→v2 新增 THEME 字段（默认 tech；发现旧配置时按迁移规则补默认值）。v2→v3 新增 DATA_SOURCES 数据源清单段（默认空清单 + git/file/remote 三类型示例注释；DIR_MAC/DIR_WIN 默认值通用化——已配置用户保留原值不受影响）。v3→v4 数据收集配置归位：DATA_SOURCES 清单结构与已填值不变，仅澄清唯一配置落点——数据源一律只写 user-config.md「默认配置」的 DATA_SOURCES（升级保护区，永不覆盖）；resources/data-collection.md 收敛为纯机制说明（随升级覆盖，不再内置清单示例）。迁移动作：备份 user-config.md → CONFIG_VERSION 更新为 4，DATA_SOURCES 原样保留；若此前误把数据源写在 data-collection.md（升级后已被新版覆盖），请手动搬回 user-config.md。
 
 ## 文档同步自检纪律（维护者必读）
 
@@ -53,7 +53,7 @@ disable-model-invocation: false
 
 ## 产物升级（回炉）
 
-生成 HTML 时头部写版本戳 `<meta name="sf-template" content="weekly-report@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧周报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="weekly-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版周报（vN-1 或无版本戳的历史产物），说『把我旧周报都升级成新样式』即可一键升级」，不让用户背触发语。
+生成 HTML 时头部写版本戳 `<meta name="sf-template" content="weekly-report@3">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧周报换新样式」时：扫落盘目录下本技能命名的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="weekly-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单） → 列清单（文件/旧版本/手改状态——旧 html 正文与同目录 md 正文对比，不一致视为可能手改过）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从同目录 md 底稿按当前 reference.html 重建，先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物主动告知「技能模板已升级至 vN，检测到 X 份旧版周报（vN-1 或无版本戳的历史产物），说『把我旧周报都升级成新样式』即可一键升级」，不让用户背触发语。
 
 ## 🔧 报修处理流程（用户报页面问题时）
 

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

@@ -1,27 +1,16 @@
 # 数据收集
 
-先检测当前系统（macOS：`uname -s` 返回 Darwin；Windows：`node -e "console.log(process.platform)"` 返回 win32），再 Read 同目录外的 `user-config.md` 顶部「默认配置」的 DATA_SOURCES 清单，按清单逐项收集（空清单 = 只按会话/文字内容生成）。清单形状（每项 name 唯一名称 + type 类型 + 路径；完整填写说明见 user-config.md「默认配置」的 DATA_SOURCES 注释）：
+> ⚠️ **本文件是收集机制说明，不是配置区**——随 skill 升级会被官方版覆盖，写在这里的内容会丢。
+> 你的真实数据源只写在同目录外的 `user-config.md` 顶部「默认配置」的 `DATA_SOURCES` 数组（升级保护区，永不覆盖）。
+> 清单形状与逐字段填写说明，一律以 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
-```
+先检测当前系统（macOS：`uname -s` 返回 Darwin；Windows：`node -e "console.log(process.platform)"` 返回 win32），再 Read 同目录外的 `user-config.md` 顶部「默认配置」的 DATA_SOURCES 清单，按清单逐项收集（空清单 = 只按会话/文字内容生成）。
 
 每项按 type 分三种行为：
 
 - git = 代码仓库：取 mac / win 中当前系统对应路径（「-」= 该系统不存在，跳过；当前系统全部为「-」的陌生机器时跳过 git 收集，只按会话/文字内容生成），用下方命令模板聚合该仓本周（周一至周结束日 WEEK_END，默认周五）提交，聚合产出；同时统计上周同范围（周一至上周周结束日）提交数/完成任务数，供概览卡环比行使用。只汇总有提交的仓库
 - file = 普通文件/目录：路径指向文件 → Read 全文提取要点；指向目录 → 列目录逐个 Read 文本文件（md/txt/csv/日志等，二进制/超大文件跳过）；路径无效或全部不可读 → 静默跳过该数据源（不报错、不写入）
-- remote = 远程网络源：只需 url 字段（mac/win 忽略）；AI 联网拉取 url 内容（网页或数据接口均可）提取要点；拉取失败/超时 → 静默跳过该数据源不阻塞生成；仅收集时联网，HTML 产物仍零外链
+- remote = 远程网络源：按清单 url 联网拉取内容（网页或数据接口均可）提取要点；拉取失败/超时 → 静默跳过该数据源不阻塞生成；仅收集时联网，HTML 产物仍零外链
 - 未知 type（拼写错误/未支持）→ 忽略该项，生成时一句话提示用户该项未识别（不猜、不中断）
 - 多来源合并：同件事去重合并——量化数字以 git 提交统计为准、定性描述以口述/文件要点为准；file/remote 提取要点与口述同等对待
 

package/weekly-report/resources/reference.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="sf-template" content="weekly-report@2">
+<meta name="sf-template" content="weekly-report@3">
 <meta name="weekly-id" content="REF-WEEKLY-0000">
 <title>本周周报 - 20261102 ~ 20261106</title>
 <style>
@@ -528,6 +528,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
   .header-card{ padding:26px 18px 20px; }
   .header-card h1{ font-size:26px; }
 }
+/* 主题切换渐变：切换瞬间给 html 挂 .theming 类（650ms 后自动摘除），期间全页颜色属性平滑过渡；平时类不存在，不影响任何元素 */
+html.theming, html.theming *, html.theming *::before, html.theming *::after{ transition: background-color .45s ease, color .45s ease, border-color .45s ease, box-shadow .45s ease, fill .45s ease, stroke .45s ease !important; }
+@media (prefers-reduced-motion: reduce){ html.theming, html.theming *{ transition: none !important; } }
+
 </style>
 </head>
 <body>
@@ -1037,7 +1041,7 @@ var SF_NS = 'weekly:' + SF_ID;
   var saved = null; try{ saved = localStorage.getItem(SF_NS + '-theme') || localStorage.getItem('sf:' + location.pathname + '-theme'); }catch(e){}
   if (saved && THEMES.indexOf(saved) !== -1 && saved !== cur){ apply(saved); }
   else{ dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on', d.getAttribute('data-theme') === (cur || 'tech')); }); }
-  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ apply(d.getAttribute('data-theme')); }); });
+  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ var r = document.documentElement; r.classList.add('theming'); clearTimeout(r.__sfThT); r.__sfThT = setTimeout(function(){ r.classList.remove('theming'); }, 650); apply(d.getAttribute('data-theme')); }); });
 })();
 
 /* 滚动入场：初始视口外的卡片滚到视口才上浮渐显（首屏卡维持加载错峰动画）；无 JS 时 html.js 不生效全显 */

package/weekly-report/user-config.md

@@ -10,7 +10,7 @@
 
 ```yaml
 DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
-CONFIG_VERSION: 3              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+CONFIG_VERSION: 4              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
 FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 整页内容区截图（头部标题卡片 + 本周概览卡片与本周任务进度/下周计划/风险阻塞点分节卡片整体截出，头部卡片必须带上），删除该项即不截图；不影响对话中的 md 正文输出）
 DIR: auto                      # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
 DIR_MAC: ~/reports                               # macOS 落盘根目录（日报按目标日期、周报按当周最后一天建子目录；目录不存在时回退用户主目录下 reports）
@@ -21,7 +21,7 @@ TEMPLATE: default              # 报告模板：default = 内置四段式（本
 ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/热力图/柱图/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
 WEEK_END: friday               # 周结束日（当周最后一天）：friday = 每周五（默认）；可改 sunday = 每周日、saturday 等；周范围、落盘子目录名均按该天日期
 CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
-DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
+DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。本清单是数据源唯一配置落点：resources/data-collection.md 只是收集机制说明（随升级覆盖），别把数据源写在那里。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
   # - name: 主项目仓库          # 名称：唯一 key（重名视为同一数据源；口述「只聚合 xxx」按 name 匹配）
   #   type: git                # git = 代码仓库（git log 聚合提交；路径不存在/非代码仓库时静默跳过）
   #   mac: ~/Projects/main-app  # macOS 路径（绝对路径或 ~ 开头）