skill-forge-hub 1.0.3 → 1.0.5

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

@@ -0,0 +1,76 @@
+# 季度总结使用指南
+
+## 能干什么
+
+把一个季度的工作沉淀成四段式季度总结：季度概览（一句话 TL;DR + 核心数据卡，数字带环比上季度/同比去年同期双基准 + Q1-Q4 季度走势图）/ 季度关键成果（季度内 M1-M3 月时间线）/ 问题与改进 / 下季度计划。适配各行业：内置 12 行业职业词典，报职业自动换术语、指标与标题（如「2026-Q4 研发季度总结」「2026-Q4 销售季度总结」）；不报职业按你的默认角色画像生成。
+
+## 基本用法
+- 直接说「写季报 / 生成季度总结」→ 默认生成当前自然季度的总结，无需指定季度
+- 指定季度（多种说法均可）：
+  - 「2026 年 Q4 的总结 / 这个季度的总结」→ 当前自然季度（未过完只算到「今天」，标题注明「截至 2026-11-12」）
+  - 「上季度的总结 / Q3 的总结」→ 上一自然季度
+  - 「近三个月的总结 / 最近 90 天的总结」→ 滚动 90 天（今天往前推 90 天）
+  - 「2026-Q3 的总结」→ 明确指定的季度
+  - 「今年 Q1-Q4 的总结 / 全年季度回顾」→ 全年按 Q1/Q2/Q3/Q4 季度时间线回顾
+- 同一份季度总结重复生成默认直接覆盖；说「保留之前的 / 另存 / 不覆盖」→ 文件名追加时间戳另存不覆盖
+- 说「打开 / 查看 2026-Q4 季报」→ 该报告文件已存在时直接打开不重新生成；不存在则按正常流程生成
+- 开发类用户可说「只算我的提交」→ 只聚合本人提交；默认仓库内全部提交都计入
+- 说「只聚合 xxx 仓库 / 只写 xxx 的季报」→ 只收集指定仓库的提交，跳过其它仓库
+
+## 口头补充素材
+- 说「补充一下：这个季度上了对账系统，季中拿下了金融客户」→ 自动按语义拆成多条，润色为规范格式并入对应月份与段落
+- 拆分信号：时间词（季初/第一个月/季中/季末/M1/M2/M3/10月）、连接词（还有/另外/以及）、分号顿号列举、数字列举
+- 补充内容带分段词时按段并入：「下季度计划：做 XX」→ 下季度计划段；「问题：复盘机制缺失」→ 问题与改进段；不带分段词按语义归段（成果 → 成果段，感悟 → 概览或问题段）
+- 与提交记录聚合出的成果自动去重，同一件事只保留一条（量化以提交统计为准、定性以口述为准）
+
+## 贴文字 / 发图片 / 给文件整理（没有提交记录也适用）
+- 直接贴一段文字说「整理成季报 / 把这段文字整理成季报」→ 以文字为主源生成，不依赖提交记录（非开发岗位也可用）；说「只整理这段文字 / 只按这段」同样跳过其它来源与会话上下文
+- 发图片（截图/照片等 jpg/png/webp）或给文件（md/txt/docx/pdf 等）说「整理成季报」→ 先用 Read 读取：图片按视觉理解提取图中文字信息，md/txt 直接读文本，docx/pdf 优先尝试 pandoc 转文本（无 pandoc 则请用户粘贴文字），再按纯文字模式整理；聊天记录/周报/月报/会议纪要文件也可作为素材
+- 图片模糊/内容读不清时：先把已提取的部分展示给用户确认或补充，不瞎编没读到的内容
+- 素材不足的段写「暂无」并提示用户可补充素材
+- 默认直接生成落盘（CONFIRM: never，无需确认）；把顶部 CONFIRM 改为 text/always，或临时说「先看看效果/先出效果」→ 先在对话输出整理好的报告正文，用户说「可以/确认/落盘」→ 再落盘文件与内容区截图并开 html；说「改一下 xxx」→ 按意见修改后重新出效果再确认
+- 说「不用确认/直接落盘」→ 当次跳过确认直接落盘（临时要求优先于配置）
+- 说「不落盘/别写文件」时跳过确认，直接对话输出
+
+## 自定义模板（适配各类岗位）
+- 内置模板为四段式（季度概览/季度关键成果/问题与改进/下季度计划），适合开发岗位；其他岗位可自定义模板
+- 临时换模板：说「这次按 xxx 来」→ 口头描述结构（如"按三段：本季工作概述/重点成果与经验/下季度计划"），当次按该结构生成，不改配置
+- 永久换模板：把顶部配置 TEMPLATE 改为 custom，并按 SKILL.md 的「📝 自定义模板」节说明修改段结构，之后默认按新模板生成
+- 说「以后都用这个模板」→ 自动把当前口述的结构写入「📝 自定义模板」节并把 TEMPLATE 改为 custom
+- 模板优先于纯文字模式的信号词归类：指定了段名后，文字按段名归类填充
+
+## 角色定制（我的职业画像）
+- 默认按顶部「默认配置」ROLE 生成（当前：全栈开发工程师（企业内技术开发））；说「我的职业是 XX / 我的主要工作是 XX / 以后默认用 XX 角色」→ 永久修改 ROLE
+- 说「以 XX 的身份写季报」→ 当次按该角色生成（内置 12 行业词条：研发/销售/运营/产品/HR/财务/市场/客服/项目/行政/法务/设计可直接用），不改配置
+- 标题随职业词条变化：研发 →「2026-Q4 研发季度总结」、销售 →「2026-Q4 销售季度总结」等
+- 词典外行业走兜底：按骨架 + 你提供的素材现场生成词条；说「记住这个行业」→ 固化为新词条
+
+## 控制落盘（临时要求，仅对当次生效）
+- 默认：对话输出 Markdown + md/txt/html 三文件 + 内容区截图 content-png 落盘到 DIR（auto 按系统选：macOS=~/reports、Windows=%USERPROFILE%\reports，模板默认值，路径以 user-config.md 顶部「默认配置」为准）/YYYY-QN/ + html 自动打开（DIR 目录/盘符不存在时自动改用用户主目录下 reports：macOS=~/reports、Windows=%USERPROFILE%\reports）
+- 说「写到桌面」→ 本次落盘到桌面（macOS=~/Desktop、Windows=%USERPROFILE%\Desktop）；说「存到 ~/report / D:\report」→ 本次用指定目录（均自动按季度建子目录）
+- 说「不落盘/别写文件」→ 本次只在对话输出，不写文件、不开浏览器
+- 说「只要 md」「只出 html」「只要内容区截图」→ 本次只落指定格式文件；说「这次不截图」→ 本次跳过截图（content-png = 四张分节卡片整体一张图，四周约 40px 留白，不含头部标题、复制按钮、页脚）
+- 说「只要截图/重新截个图」（如「给 2026-Q4 季报截个图」）→ 本次不重新生成内容，只对现有 html 执行内容区截图（覆盖 content-png，需 html 已存在，找不到则提示先生成）
+- 说「别开浏览器」→ 本次落盘后不自动打开 html
+- 说「保留之前的」→ 同季度重复生成时不覆盖，文件名追加时间戳另存
+
+## 配置开关（改 user-config.md 顶部「默认配置」节，长期生效）
+| 配置项 | 作用 | 可选值 / 示例 |
+|---|---|---|
+| DISK | 是否落盘写文件 | true（落盘，默认）/ false（默认只在对话输出） |
+| FORMATS | 落盘哪些格式（数组） | [md, txt, html, content-png]（默认，含内容区截图）/ [md, html] / [md, txt, html]（不截图）；content-png = 四张分节卡片整体截图（四周约 40px 留白），不含头部标题/复制按钮/页脚 |
+| DIR | 落盘根目录 | auto（按当前系统自动选 DIR_MAC / DIR_WIN，默认）；DIR_MAC = macOS 根目录（模板默认 ~/reports，可改）；DIR_WIN = Windows 根目录（模板默认 %USERPROFILE%\reports，可改） |
+| OPEN_HTML | 落盘后是否自动打开 html | true（自动打开，默认）/ false（不打开） |
+| TEMPLATE | 报告模板 | default（内置四段式，默认）/ custom（按「📝 自定义模板」节的结构生成） |
+| ROLE | 默认职业角色画像 | 全栈开发工程师（企业内技术开发）等；职业名 + 括号内工作内容 |
+| CONFIRM | 落盘前先出效果确认 | never（直接生成不确认，默认）/ text（纯文字整理模式确认）/ always（所有生成都确认） |
+- 优先级：临时口头要求（不落盘/写到桌面/只要 md/只要内容区截图/这次不截图/别开浏览器/临时换模板等）永远优先于默认配置，仅对当次生效、不改配置
+- DIR（按系统解析）指向的目录/盘符不存在时，自动回退到用户主目录下 reports（macOS=~/reports、Windows=%USERPROFILE%\reports）
+
+## 效果不对怎么办
+
+- 页面效果不对（布局乱 / 样式错 / 交互异常 / 内容显示不全），直接对 AI 说「这个页面效果不对，对照参考模板修复」，把问题描述清楚（哪一节、什么现象，能截图最好）
+- 本技能的设计标准答案就在技能目录里：`resources/reference.html`（双击可直接打开看标准效果），AI 修复时以此为唯一对照
+- AI 的处理流程固定：先打开 reference.html 作标准 → 再读你那份问题 html 文件 → 逐处比对找出跑偏的地方 → 以 reference 为准修复 → 用浏览器自动截图对比修复前后，自证修好了再交付
+- 效果对了但内容不对（数字/条目写错）同样说「内容有误：xxx 应该是 xxx」，AI 只改数据不动版式；参考模板本身有缺陷时（生成结果与 reference 一模一样但仍有问题）说一句「参考模板也有这个问题」，AI 会连模板一起修并同步回 reference.html
+- 修复后想要永久按修复效果生成：说「以后都按这个效果生成」即可

package/quarterly-report/user-config.md

@@ -0,0 +1,53 @@
+# 用户配置（升级技能时本文件不会被覆盖）
+
+> 你的个人配置全放在这里。skill-forge 升级技能时官方只更新 SKILL.md 与 resources/，
+> 本文件始终保留你的版本——落盘目录、格式、角色画像、自定义模板放心改。
+> 官方升级若带来新配置点，会另存 `user-config.md.upstream` 对照文件到同目录，
+> 你按需查看并手动合并新配置点到本文件。
+
+
+## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
+
+```yaml
+DISK: true                     # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
+CONFIG_VERSION: 3              # 配置结构版本：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）
+DIR_WIN: %USERPROFILE%\reports                   # Windows 落盘根目录（自动按目标季度建子目录 2026-Q4 式样；目录/盘符不存在时回退用户主目录下 reports）
+OPEN_HTML: true                # 落盘后是否自动用浏览器打开 html（FORMATS 不含 html 时忽略）
+THEME: tech                    # html 页面主题：tech 深蓝科技（默认）/ biz 浅色商务 / mono IDEA 黑亮 / light IDEA 白亮 / warm 温暖渐变；生成时写 <html data-theme="THEME值"> 定默认，页面右下角换肤坞五色点随点随换（浏览器本地记忆（键按页内嵌唯一 ID 隔离、多份产物互不串台、改名/移动目录记忆不丢；生成时头部写 `<meta name="quarterly-id" content="<UUID>">`，每次新 UUID），?shot 截图模式自动隐藏，打印隐藏）
+TEMPLATE: default              # 报告模板：default = 内置四段式（季度概览/季度关键成果/问题与改进/下季度计划）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
+ROLE: 全栈开发工程师（企业内技术开发）  # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/里程碑/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
+CONFIRM: never                 # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
+DATA_SOURCES: []               # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
+  # - 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 全文、目录逐个 Read 文本文件，二进制跳过；路径无效静默跳过）
+  #   mac: ~/Documents/meeting-notes.md
+  #   win: -
+  # - name: 数据接口
+  #   type: remote             # remote = 远程网络源（只需 url 字段忽略 mac/win；AI 联网拉取内容提取要点；失败静默跳过不阻塞；仅收集时联网，HTML 产物仍零外链）
+  #   url: https://example.com/data.json
+```
+
+> 临时口头要求（仅对当次生效，不修改上方配置）：说「不落盘/别写文件」→ 当次 DISK=false；说「写到桌面/存到 ~/report（macOS）或 D:\report（Windows）」→ 当次改用该 DIR；说「只要 md / 只出 html / 只要内容区截图」→ 当次只落指定格式；说「这次不截图」→ 当次不生成内容区截图；说「只要截图/重新截个图」→ 当次只对现有 html 执行内容区截图（不重新收集数据、不重写 md/txt/html 内容文件）；说「别开浏览器」→ 当次 OPEN_HTML=false；说「这次按 xxx 模板来」→ 当次临时换模板（不改配置）；说「以后都用这个模板」→ 自动写入下方「📝 自定义模板」节并把 TEMPLATE 改为 custom（永久生效）；说「先看看效果/先出效果再落盘」→ 当次先出效果确认后再落盘；说「不用确认/直接落盘」→ 当次跳过确认直接落盘。说「页面用浅色商务主题/浅色主题」→ 当次 THEME=biz；说「以后默认用暖色主题」→ 永久改 THEME=warm。
+
+## 📝 自定义模板（TEMPLATE: custom 时启用，用户可手改，适配各类岗位）
+
+把顶部 TEMPLATE 改为 custom 后，按下面结构生成报告（段名、段数、条目格式均可改）：
+
+```text
+段一：季度工作概述（每条：概述 - 量化结果）
+段二：本季重点成果（每条：成果描述 - 完成时间 - 影响）
+段三：问题与改进（每条：问题 - 影响 - 改进措施）
+段四：下季度工作计划（每条：计划描述 - 预期目标 - 时间节点）
+```
+
+> 只写段结构与条目格式即可；未写明的细节（中文顿号序号、生成时间行、落盘行为、HTML 样式）沿用默认规范。
+
+---
+> 更多用法见 SKILL.md 的「生成流程」与 resources/ 分册。

package/spec-doc2spec/SKILL.md

@@ -1,34 +1,30 @@
 ---
 name: spec-doc2spec
 description: >
-  文档转需求规格 Skill（doc2spec）。仅在用户要求把 PRD / Word / Markdown 需求文档转成结构化需求文档
-  （需求点提炼、功能单元切分）时使用。Pandoc 负责 Word→Markdown 机械转换，AI 全程参与校对防错——
-  Pandoc 对复杂表格（合并单元格拆裂）、文本框（内容丢失）、图片（EMF/WMF 浏览器不可渲染）、修订痕（删除线残留）
-  有已知局限，机械产物一律只作底稿，AI 对照原文逐段校对、纠错补漏后再加工成需求规格。
-  图片自动提取与目录组织（默认 assets/images/，可配置 IMG_DIR；EMF/WMF 自动检测并跨系统转 PNG）。
-  输出目录默认源文档同目录下 {文档名}-spec/ 子目录，可配置 OUTPUT_DIR。
-  跨系统适配 macOS / Windows / Linux（Pandoc 安装、EMF 转换工具链探测、路径引用）。
-  支持 .docx（Pandoc 转换）/ .md（直接读取）；.pdf 走 pdftotext 文本提取（无图）或提示先转 Word。
-  不处理一般性的文档内容讨论（如「帮我看看这份文档讲了什么」），只处理「文档 → 需求规格」的转换任务。
+  文档转高质量 Markdown Skill（doc2spec）。把 Word / PDF / Markdown 文档转成结构化 Markdown——Pandoc 负责机械转换，AI 全程校对防错（量化校验断言、双通道完整性比对、表格列表修复、图片提取与 EMF/WMF 自动转 PNG、乱码与修订痕清理），转换后整理成干净的正文稿落盘。
+  可选「需求加工档」：用户要求整理成需求规格时，另出需求点+验收标准与功能单元切片。
+  图片自动提取到 assets/images（可配置 IMG_DIR）；输出默认源文档同目录下 {文档名}-spec/ 子目录，可配置 OUTPUT_DIR（绝对路径同样按文档名建子目录，多文档互不覆盖）。
+  跨系统适配 macOS / Windows / Linux（Pandoc 安装、EMF 转换工具链探测）。支持 .docx（Pandoc 转换）/ .md（直接读取）/ .pdf（LibreOffice 转 docx 优先保留图片版式，降级 pdftotext 纯文本）。
+  不处理一般性的文档内容讨论（如「帮我看看这份文档讲了什么」），只处理「文档 → Markdown / 需求规格」的转换任务。
   用户询问用法（doc2spec 怎么用/使用说明/能干什么）时走使用说明应答：读 resources/usage-guide.md 原样输出（首行标题改为「doc2spec 使用指南」），不执行任何转换命令。
 allowed-tools: ["Bash", "Read", "Write", "Edit"]
 disable-model-invocation: false
 ---
 
-# 文档 → 需求规格（doc2spec）
+# 文档 → 高质量 Markdown（doc2spec）
 
-将产品需求文档（PRD）转换为结构化的 Markdown 需求文档。分工原则：**Pandoc 负责机械转换，AI 负责校对防错与需求加工**——Pandoc 对复杂表格（合并单元格拆裂）、文本框（内容丢失）、图片（EMF 格式浏览器不可渲染）、修订痕（删除线残留）存在已知局限，机械产物一律只作底稿，AI 必须对照原文逐段校对、纠错补漏后再加工。
+将 Word / PDF / Markdown 文档转换为结构化 Markdown。分工原则：**Pandoc 负责机械转换，AI 负责校对防错与整理**——Pandoc 对复杂表格（合并单元格拆裂）、文本框（内容丢失）、图片（EMF 格式浏览器不可渲染）、修订痕（删除线残留）存在已知局限，机械产物一律只作底稿，AI 必须对照原文逐段校对、纠错补漏后再整理成稿。用户要求「整理成需求规格」时另启用需求加工档。
 
 ## 生成流程
 
 0. **读用户配置**（OUTPUT_DIR/IMG_DIR/EMF_POLICY/CONFIRM/CONFIG_VERSION）→ 先 Read 同目录 `user-config.md`
 1. **依赖检测**（每次必做）→ `pandoc --version`；未安装按「安装指引」输出并停止，不执行任何转换命令
-2. **格式路由** → `.docx` 走 Pandoc 机械转换；`.md` 直接 Read 原文（跳过第 3 步转换，第 4 步校对照做）；`.pdf` 走 `pdftotext` 文本提取（仅文本、无图无版式）或提示用户先转 Word
-3. **Pandoc 机械转换** → `pandoc <输入.docx> -f docx -t gfm --extract-media=<IMG_DIR> -o 00-converted.md`（标题/表格/列表保留、图片提取到 IMG_DIR）；另生成 `pandoc <输入.docx> -t plain -o 00-plain.txt` 纯文本底稿供完整性核对
-4. **AI 逐段校对（防错防漏，必做）** → 读 `resources/checklist.md`：对照源文档逐段核对完整性/表格/列表/图片/乱码/修订痕/页眉页脚噪音，发现错误直接在 00-converted.md 上修正
-5. **图片处理** → 读 `resources/images.md`：校验图片引用路径、检测 EMF/WMF 并跨系统转 PNG、处理缺失图片
-6. **AI 结构加工与落盘** → 读 `resources/structure.md`：提炼需求点与验收标准、按功能单元切分章节、生成澄清清单，按目录规范落盘
-7. **报告** → 产出路径、功能单元清单、校对修正记录、待澄清需求点
+2. **格式路由** → `.docx` 走 Pandoc 机械转换；`.md` 直接 Read 原文（跳过第 3 步转换，第 4 步校对照做）；`.pdf` 先 `soffice --headless --convert-to docx --outdir <临时目录> <输入.pdf>` 转 docx 再走完整 docx 路径（保留图片与版式；无 LibreOffice 或转换失败时降级 `pdftotext -layout <输入.pdf> 00-plain.txt` 纯文本提取——仅文本无图，如实告知用户）
+3. **建目录 + Pandoc 机械转换** → 先 `mkdir -p <输出目录>`（输出目录规则见 `resources/structure.md`）→ **cd 到输出目录再执行**（图片提取以输出目录为基准，引用路径才正确）：`pandoc <输入绝对路径.docx> -f docx -t gfm --extract-media=<IMG_DIR> -o 00-converted.md`；另生成 `pandoc <输入绝对路径.docx> -t plain -o 00-plain.txt` 纯文本底稿供完整性核对
+4. **AI 逐段校对（防错防漏，必做）** → 读 `resources/checklist.md`：量化校验断言 + 双通道比对 + 专项排查，发现错误直接在 00-converted.md 上修正
+5. **图片处理** → 读 `resources/images.md`：图片拍平到 IMG_DIR、引用校验、EMF/WMF 跨系统转 PNG、图片内容抽检
+6. **AI 整理与落盘** → 读 `resources/structure.md`：整理 01-正文.md（去噪 + 表格列表修复 + 图片引用就位）；用户要求「整理成需求规格 / 提炼需求点」时另出需求加工档（01-需求规格.md / requirements/ 切片）；生成 README 索引与 _clarify.md 澄清清单
+7. **报告** → 产出路径、章节清单、校对修正记录、待澄清点
 
 ## ⚙️ 配置与自定义
 
@@ -36,7 +32,7 @@ disable-model-invocation: false
 
 ## 配置版本机制（升级保护）
 
-本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
+本 skill 当前配置版本为 `2`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明的当前版本不一致：
 
 1. 先将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`（同目录，绝不删除旧值）
 2. 按本节「配置升级规则」迁移字段：新增字段补默认值、改名字段按映射改写、删除字段的值保留在备份中并在对话提示用户手动确认
@@ -45,6 +41,8 @@ disable-model-invocation: false
 
 升级本 skill 时，配置结构如有变化必须同步更新本节的当前版本号与迁移说明；禁止在未声明版本变更的情况下静默修改配置语义。
 
+当前版本变更记录：v1→v2 OUTPUT_DIR 绝对路径模式同样按 {文档名}-spec/ 建子目录（多文档互不覆盖，说「直接放这个目录」才平铺）；PDF 输入改 LibreOffice 转 docx 优先（保留图片版式，降级 pdftotext）；图片提取改「输出目录内执行 pandoc + media/ 拍平」。
+
 ## 文档同步自检纪律（维护者必读）
 
 修改本 skill 任一文件（SKILL.md / user-config.md / resources/*）后，必须 grep 全文核对相关关键词在各文件间一致（如配置键名/流程节点/阶段名改名时新旧词全仓核对，旧词零残留才算完成）。
@@ -68,7 +66,8 @@ EMF 图片转 PNG 依赖 LibreOffice（可选，仅当文档含 EMF 图）：mac
 
 ## 规则速览
 
-- 机械产物只作底稿：AI 校对（完整性/表格/图片/乱码/修订痕）与需求加工（需求点+验收标准、功能单元切分、澄清清单）缺一不可
-- 图片一律进 IMG_DIR（默认 assets/images），EMF/WMF 必须先转 PNG（soffice headless → qlmanage → magick 按系统探测）
-- 输出目录默认 {文档名}-spec/，00-converted.md 底稿保留溯源、加工稿另写不覆盖底稿
-- 有疑点进 _clarify.md，不臆造内容；落盘后向用户报告产出路径/单元清单/校对记录/待澄清点
+- 机械产物只作底稿：AI 校对（量化断言 + 双通道比对 + 专项排查）与整理（01-正文.md）缺一不可
+- 图片一律进 IMG_DIR（默认 assets/images，拍平无 media/ 残留），EMF/WMF 必须先转 PNG（soffice headless → qlmanage → magick 按系统探测）
+- 输出目录默认 {文档名}-spec/（auto 或绝对路径均按文档名建子目录），00-converted.md 底稿保留溯源、整理稿另写不覆盖底稿
+- 需求加工是可选档：用户说「整理成需求规格 / 提炼需求点」才出 01-需求规格.md 与 requirements/ 切片
+- 有疑点进 _clarify.md，不臆造内容；落盘后向用户报告产出路径/章节清单/校对记录/待澄清点

package/spec-doc2spec/resources/checklist.md

@@ -2,6 +2,12 @@
 
 Pandoc 机械产物只作底稿。AI 必须 Read 源文档与 00-converted.md / 00-plain.txt，逐段对照核对，发现问题直接在底稿上修正，修正后再进入需求加工。
 
+## 量化校验断言（机器计数，先跑）
+
+- 图片：`grep -o '!\[' 00-converted.md | wc -l` == IMG_DIR 下图片文件数（拍平转 PNG 后）；不等则逐个排查丢图/多图
+- 章节：`grep -c '^#' 00-converted.md` 的标题数与 Read 源文档数出的章节数一致；缺则定位丢失段落
+- 双通道量比：`pandoc 00-converted.md -t plain | wc -c` 与 `wc -c 00-plain.txt` 字符量差 ≤5%（超出说明 gfm 版有格式残留或内容丢失，逐段比对找回）
+
 ## 完整性核对
 
 - 章节结构：源文档每个一级/二级标题在转换结果中都有对应内容，无整章整段丢失
@@ -13,6 +19,7 @@ Pandoc 机械产物只作底稿。AI 必须 Read 源文档与 00-converted.md /
 - **表格**：合并单元格拆裂、列错位、跨页表格断行错乱 → AI 重建为规范 markdown 表格（合并单元格用行内注释注明合并范围）；表格被降级成纯文本段落时恢复为表格
 - **列表**：多层嵌套层级丢失、有序列表编号中断 → AI 按原文恢复层级与编号
 - **图片**：引用路径失效、图片丢失、.emf/.wmf 引用 → 见 images.md
+- **嵌入对象**：Word 内嵌 Excel 表格 / OLE 公式对象不随 Pandoc 提取 → 双通道比对发现缺失后，提示用户「嵌入对象需单独导出」，或从源文档截取对应内容补进底稿并注明出处
 - **特殊字符**：公式变形、箭头/全角符号乱码 → AI 修正；数学公式用 $...$ 行内 / $$...$$ 块级保留 LaTeX 原貌
 - **修订痕**：Word 修订模式未接受时，转换可能残留删除线文本 → 提示用户「接受所有修订」后重转；无法重转时 AI 按「接受后状态」处理并注明
 - **页眉页脚/页码**：转换为正文残留文本 → 剔除

package/spec-doc2spec/resources/images.md

@@ -1,13 +1,23 @@
 # 图片处理
 
-## 提取
+## 提取与拍平
 
-- Pandoc 转换命令带 `--extract-media=<IMG_DIR>`（默认 assets/images，相对输出目录）：文档内嵌图片自动提取到该目录，md 引用改写为相对路径
-- 转换后 Read 00-converted.md 收集全部 `![](...)` 引用，逐一核对 IMG_DIR 下对应文件存在；引用路径以 00-converted.md 所在目录为基准解析
+- Pandoc 转换命令带 `--extract-media=<IMG_DIR>`（默认 assets/images，相对输出目录；**必须在输出目录内执行 pandoc**，图片基准才正确）：图片默认提取到 `<IMG_DIR>/media/` 子目录，md 引用写作 `media/xxx`
+- 转换后拍平：把 `<IMG_DIR>/media/*` 全部移到 `<IMG_DIR>/` 根目录，同步把 00-converted.md 中 `media/` 引用前缀改掉，删除空的 media/ 子目录——产物目录里图片直接可见，不留冗余层级
+- 重名冲突时 AI 重命名（如 image1-2.png）并在 md 引用同步更新
+
+## 引用校验
+
+- Read 00-converted.md 收集全部 `![](...)` 引用，逐一核对 IMG_DIR 下对应文件存在
+- 量化断言：`!\[` 引用数 == IMG_DIR 下图片文件数（见 checklist.md），不等则逐个排查丢图/多图
+
+## 图片内容抽检
+
+- Read 抽检关键图片：有图注的图、流程/架构/截图类图片至少各抽一张，确认图片内容与原文图注对应、无黑图/半截图/错位图；发现异常从源文档重新提取
 
 ## EMF/WMF 转换（浏览器不可渲染格式）
 
-- 检查 IMG_DIR 下是否出现 .emf/.wmf 文件（Word 图形对象默认 EMF，很常见）：有则必须转 PNG，否则预览/截图/后续加工全部不可见
+- 检查 IMG_DIR 下是否出现 .emf/.wmf 文件（Word 图形对象默认 EMF，很常见）：有则必须转 PNG，否则预览/后续加工全部不可见
 - 转换链（跨系统，按序探测，成功即止）：
   1. LibreOffice：`soffice --headless --convert-to png --outdir <IMG_DIR> <file.emf>`（三系统通用，首选）
   2. macOS 备选：`qlmanage -t -s 1600 -o <IMG_DIR> <file.emf>`（部分 EMF 不支持）
@@ -19,7 +29,6 @@
 
 - 引用存在但文件缺失：核对 --extract-media 是否执行、路径是否被移动；无法恢复的在 _clarify.md 记录「图片缺失：<原位置>」
 - alt 文本：Pandoc 保留 Word 图片 alt 文本，AI 校对时确认关键图片 alt 与原文图注一致；无 alt 的关键图片按原文图注补写
-- 图片命名：默认沿用 Pandoc 提取名（image1.png 等）；重名冲突时 AI 重命名并在 md 引用同步更新
 
 ## 目录组织
 

package/spec-doc2spec/resources/structure.md

@@ -3,25 +3,34 @@
 ## 默认输出结构
 
 ```
-{源目录}/{文档名}-spec/          ← OUTPUT_DIR=auto 默认；可配置绝对路径
-├── README.md                    ← 索引：源文档、转换时间、功能单元清单、校对记录摘要
+{源目录}/{文档名}-spec/          ← OUTPUT_DIR=auto 默认；OUTPUT_DIR 写绝对路径时以其为产物根目录，其下仍建 {文档名}-spec/ 子目录（说「直接放这个目录」才平铺）
+├── README.md                    ← 索引：源文档、转换时间、章节清单、校对记录摘要
 ├── 00-converted.md              ← Pandoc 机械底稿（AI 已校对修正版，保留溯源）
 ├── 00-plain.txt                 ← 纯文本底稿（完整性核对用，保留溯源）
-├── 01-需求规格.md                ← AI 加工后的主规格：需求点 + 验收标准（功能单元 ≤3 时单文件即可）
+├── 01-正文.md                   ← AI 整理后的正文稿：去噪（页眉页脚/修订痕）、表格列表修复、图片引用就位
+├── assets/images/               ← 图片目录（IMG_DIR 可配置；已拍平，图片直接可见、无 media/ 残留）
+└── _clarify.md                  ← 待澄清清单（有疑点才生成）
+```
+
+## 需求加工档（可选，仅当用户要求「整理成需求规格 / 提炼需求点」时启用）
+
+```
+├── 01-需求规格.md                ← 需求点 + 验收标准（功能单元 ≤3 时单文件即可）
 ├── requirements/                ← 功能单元切片（单元 >3 时启用）
 │   ├── REQ-01-{单元名}.md
 │   └── ...
-├── assets/images/               ← 图片目录（IMG_DIR 可配置）
-└── _clarify.md                  ← 待澄清清单（有疑点才生成）
 ```
 
-## 加工规则
+- 未要求需求加工：不出 01-需求规格.md 与 requirements/，01-正文.md 即最终正文稿
+- 要求需求加工：01-正文.md 保留（溯源正文），另出 01-需求规格.md（≤3 单元单文件）或 requirements/ 切片（>3 单元时 01-需求规格.md 为总览：各单元一句话摘要 + 文件名映射）
+
+## 整理规则
 
-- 需求点提炼：每条「需求点 - 验收标准」结对，保留原文关键表述，不臆造内容
-- 功能单元切分：按业务功能边界切分，单元名用中文短名（如「用户登录」）；单元 >3 时拆 requirements/ 目录，否则合并在 01-需求规格.md 内分章节
+- 正文整理：保留原文关键表述与结构，修复表格/列表/图片引用，剔除页眉页脚/页码/修订痕噪音，不臆造内容
+- 需求加工（可选档）：每条「需求点 - 验收标准」结对，保留原文关键表述；按业务功能边界切分，单元名用中文短名（如「用户登录」）；每个单元注明来源章节
 - 澄清清单：校对中发现的歧义/缺失/矛盾 → _clarify.md 逐条编号记录（问题 + 原文出处 + AI 建议）
-- 溯源：每个功能单元注明来源章节；00-converted.md 保留不做删改，加工后的规格另写文件、不覆盖底稿
+- 溯源：00-converted.md 保留不做删改，整理稿另写文件、不覆盖底稿
 
 ## 目录复用
 
-- 输出目录已存在时：复用并覆盖本清单内同名文件（00-converted.md/01-需求规格.md 等），其余文件保留；不清空目录
+- 输出目录已存在时：复用并覆盖本清单内同名文件（00-converted.md/01-正文.md 等），其余文件保留；不清空目录

package/spec-doc2spec/resources/usage-guide.md

@@ -2,31 +2,33 @@
 
 ## 能干什么
 
-把 PRD / Word / Markdown 需求文档转成结构化 Markdown 需求规格：Pandoc 机械转换 + AI 逐段校对（纠错补漏）+ 需求点提炼与功能单元切分。图片自动提取到 assets/images/（EMF 等不可渲染格式自动转 PNG）；输出默认「源文档同目录/{文档名}-spec/」子目录，输出与图片目录均可配置。
+把 Word / PDF / Markdown 文档转成高质量结构化 Markdown：Pandoc 机械转换 + AI 逐段校对（量化校验 + 双通道比对纠错补漏）+ 整理成干净正文稿。图片自动提取到 assets/images/（EMF 等不可渲染格式自动转 PNG）；输出默认「源文档同目录/{文档名}-spec/」子目录，输出与图片目录均可配置。说「整理成需求规格」时另出需求点+验收标准与功能单元切片（可选档）。
 
 ## 使用方式
 
-1. 直接说「把这份 PRD 转成需求文档」「Word 转需求切片」并给出文件路径
+1. 直接说「把这份 Word 转成 Markdown」「这份 PDF 转成文档」并给出文件路径
 2. 未装 Pandoc 时按引导安装（macOS brew / Windows winget / Linux apt-get）
-3. Pandoc 完成 Word→Markdown 机械转换后，AI 对照原文逐段校对（完整性/表格/图片/乱码/修订痕），再提炼需求点、按功能单元切分
-4. 产出结构化需求文档到指定目录
+3. Pandoc 完成机械转换后，AI 对照原文逐段校对（量化断言/完整性/表格/图片/乱码/修订痕），整理出 01-正文.md
+4. 需要需求规格时说「顺便整理成需求规格」——AI 另出需求点+验收标准与功能单元切片
 
 ## 支持格式
 
 - .docx（Pandoc 转换，图片自动提取）
 - .md（直接读取）
-- .pdf（pdftotext 文本提取，仅文本无图；需要图片建议先转 Word）
+- .pdf（LibreOffice 转 docx 优先，保留图片版式；无 LibreOffice 降级纯文本提取）
 
 ## 常用说法
 
-- 「输出到桌面」→ 临时改输出目录
+- 「输出到桌面」→ 临时改输出目录（仍按文档名建子目录）
+- 「直接放这个目录」→ 产物平铺到指定目录不建子目录
 - 「图片放 figures/」→ 临时改图片目录
+- 「整理成需求规格」→ 启用需求加工档
 - 「先看看效果」→ 先出预览确认再落盘
 
 ## 产出
 
-{文档名}-spec/ 目录：README 索引 + 需求规格（含功能单元切片）+ 图片目录 + 澄清清单（有疑点时）。
+{文档名}-spec/ 目录：README 索引 + 01-正文.md（校对整理稿）+ 图片目录 + 澄清清单（有疑点时）；需求加工档启用时另含 01-需求规格.md 与 requirements/ 切片。
 
 ## 触发词
 
-把 PRD 转成需求文档 / Word 转需求切片 / 文档转规格 / /doc2spec
+Word 转 Markdown / 文档转 md / 把这份文档转成 Markdown / 需求文档转规格 / /doc2spec

package/spec-doc2spec/user-config.md

@@ -9,8 +9,8 @@
 ## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）
 
 ```yaml
-CONFIG_VERSION: 1              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
-OUTPUT_DIR: auto              # 输出目录：auto = 源文档同目录下新建 {文档名}-spec/ 子目录；也可写死绝对路径
+CONFIG_VERSION: 2              # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
+OUTPUT_DIR: auto              # 输出目录：auto = 源文档同目录下新建 {文档名}-spec/ 子目录；写绝对路径时以其为产物根目录、其下仍建 {文档名}-spec/ 子目录（说「直接放这个目录」才平铺）
 IMG_DIR: assets/images        # 图片提取目录（相对输出目录）；Pandoc --extract-media 提取到此处
 EMF_POLICY: convert           # EMF/WMF 图片策略：convert = 自动跨系统转 PNG（LibreOffice 兜底）；keep = 保留原样并在澄清清单注明不可渲染
 CONFIRM: never                # 落盘前确认：never = 直接生成落盘；always = 先出加工预览确认后再落盘

package/spec-spec2doc/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: spec-spec2doc
 description: >
-  规格转交付文档 Skill（spec2doc）。仅在用户要求把 Markdown 规格 / 技术文档导出为 Word / PDF 交付文档时使用。
+  文档转 Word/PDF 交付稿 Skill（spec2doc）。把 Markdown 文档（规格/技术文档/说明文档/会议纪要等）导出为 Word / PDF——
   Pandoc 负责机械转换，AI 负责转换前排版整理与转换后回验防错（Pandoc 对复杂表格、图片路径、中文字体有局限，
   回验发现问题修正源稿重新转换直到通过，机械产物不直接交付）。主路径 Markdown → Word（支持 --reference-doc
   模板：默认依次探测源目录 template.docx / reference.docx，可配置 TEMPLATE_DOCX）。
   Markdown → PDF 双路径：xelatex（需 LaTeX 引擎与 CJK 中文字体）或 Chrome headless 打印（免 LaTeX、跨系统兜底），
   引擎可配置 PDF_ENGINE。输出目录默认与源文档同目录，可配置 OUTPUT_DIR。
   跨系统适配 macOS / Windows / Linux（Pandoc/LaTeX 安装、中文字体探测、Chrome 路径探测）。
-  不处理一般性的文档格式转换（如「把这个 txt 转成 Word」），只处理「规格 → 交付文档」的转换任务。
+  .txt 纯文本视为无格式 md 同样可转；不处理一般性的文档内容讨论，只处理「Markdown → Word/PDF」的转换任务。
   用户询问用法（spec2doc 怎么用/使用说明/能干什么）时走使用说明应答：读 resources/usage-guide.md 原样输出（首行标题改为「spec2doc 使用指南」），不执行任何转换命令。
 allowed-tools: ["Bash", "Read", "Write", "Edit"]
 disable-model-invocation: false
 ---
 
-# 规格 → 交付文档（spec2doc）
+# Markdown → Word/PDF（spec2doc）
 
-将 Markdown 规格 / 技术文档转换为 Word / PDF 交付文档。分工原则：**Pandoc 负责机械转换，AI 负责排版整理与回验防错**——AI 转换前整理标题层级/表格/图片路径，转换后核对产出文档内容完整与格式正确，发现问题修正源稿重新转换，直到回验通过（机械产物不直接交付）。
+将 Markdown 文档（规格 / 技术文档 / 说明文档 / 会议纪要等）转换为 Word / PDF 交付文档。分工原则：**Pandoc 负责机械转换，AI 负责排版整理与回验防错**——AI 转换前整理标题层级/表格/图片路径，转换后核对产出文档内容完整与格式正确，发现问题修正源稿重新转换，直到回验通过（机械产物不直接交付）。
 
 ## 生成流程
 

package/spec-spec2doc/resources/checklist.md

@@ -9,6 +9,12 @@
 - 文件可开性：docx 大小异常（接近 0KB 或数倍膨胀）→ 转换失败信号，重转排查
 - PDF 回验：`pdftotext <输出.pdf> - | wc -l` 文本行数合理（非 0 非异常少）；必要时截图查看版式
 
+## 量化校验断言（机器计数，逐项执行）
+
+- 章节/表格：`pandoc <输出.docx> -t gfm` 反转换结果的 `grep -c '^#'` 标题数、表格块数与源 md 一致
+- 图片：`unzip -l <输出.docx> | grep -c 'word/media/'` == 源 md `!\[` 引用数
+- PDF 中文：`pdftotext <输出.pdf> - | grep -c '�'` 应为 0；`pdftotext <输出.pdf> - | grep -o '[一-鿿]' | wc -l` 中文字符量非 0（豆腐块/丢中文时接近 0）
+
 ## 检查项
 
 - 内容完整：无章节/段落/表格遗漏（反向转换比对）

package/spec-spec2doc/resources/pdf-path.md

@@ -15,6 +15,7 @@
 - Chrome 路径探测（跨系统）：macOS `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`；Windows 按序探测 `C:\Program Files\Google\Chrome\Application\chrome.exe` → `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe` → `%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`；Linux `google-chrome` / `chromium`；均无则换 Edge（路径同族探测）
 - 版式：可加 `--css=<样式.css>` 定制打印版式（页边距、字体）
 - 引擎决策：PDF_ENGINE=auto 时先探测 xelatex，无则走 Chrome 打印路径并在报告注明「PDF 由 HTML 打印生成」
+- 中文豆腐块检测：`pdftotext <输出.pdf> - | grep -c '�'` 应为 0、中文字符量非 0（无中文字体的 Linux 先装 Noto Sans CJK；检测方法见 checklist.md）
 
 ## 引擎缺失兜底
 

package/spec-spec2doc/resources/usage-guide.md

@@ -2,7 +2,7 @@
 
 ## 能干什么
 
-把 Markdown 规格 / 技术文档导出为 Word / PDF 交付文档：AI 先整理排版，Pandoc 机械转换，AI 回验纠错直到通过。Word 支持模板（默认探测源目录 template.docx，可配置）；PDF 双路径（LaTeX 或 Chrome 打印，免装 LaTeX 也有兜底）；输出默认与源文档同目录，可配置。
+把 Markdown 文档（规格/技术文档/说明文档/会议纪要等）导出为 Word / PDF 交付文档：AI 先整理排版，Pandoc 机械转换，AI 回验纠错直到通过。Word 支持模板（默认探测源目录 template.docx，可配置）；PDF 双路径（LaTeX 或 Chrome 打印，免装 LaTeX 也有兜底）；输出默认与源文档同目录，可配置。
 
 ## 使用方式
 
@@ -29,4 +29,4 @@
 
 ## 触发词
 
-导出成 Word / 生成 PDF / 规格转文档 / 打包交付文档 / /spec2doc
+md 转 Word / 导出成 Word / 生成 PDF / 打包交付文档 / /spec2doc

package/template/SKILL.md

@@ -14,7 +14,7 @@ disable-model-invocation: false
 1. **阶段一（做什么）** → 读 `resources/xxx.md`
 2. **阶段二（做什么）** → 读 `resources/yyy.md`
 3. **阶段三（做什么）** → 读 `resources/zzz.md`
-3.5 **交付前自检**（落盘前必做，硬门禁不可跳过）：<按技能类型写自检手段——页面类用 Playwright headless 零报错（channel="chrome"）；文档类检查结构与数据纪律；产物类校验文件完整性与内容一致>——未通过修复后重跑，禁止跳过直接交付
+3.5 **交付前自检**（落盘前必做，硬门禁不可跳过）：<按技能类型写自检手段——页面类 用 Playwright headless 零报错（channel="chrome"）+ localStorage 键路径命名空间 核验（固定键零残留）+ 多文件隔离实测（复制 HTML 到第二路径互不干扰）+ 品牌字体 零侵权扫描（PingFang/YaHei/apple-system 等零出现）+ 示例数据脱敏核验（真实项目名/人名/公司名/本机路径零出现，署名 GENERATED BY AI TEAM）+ 产物版本戳核验（`<meta name="sf-template" content="<skill>@N">` 已写入且 N 与当前模板版本一致；业务/数据格式/页面改动必 bump 版本）；文档类检查结构与数据纪律； 产物类校验文件完整性与内容一致>——未通过修复后重跑，禁止跳过直接交付
 4. **使用咨询**（用户只问用法、未要求生成）→ 读 `resources/usage-guide.md` 原样输出（首行标题改为「XX使用指南」），不执行任何生成动作
 
 ## ⚙️ 默认配置（用户可手动修改；临时口头要求永远优先）

package/weekly-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weekly-report
-description: 生成工作周报（默认本周结论+本周任务进度/下周计划/风险阻塞点结构，中文顿号序号，1D=8H），适配各行业（内置 12 行业职业词典，可指定角色身份）。数据来源灵活：直接口述、给一段文字、发文件（Word/PDF/Excel/PPT 等）或图片，都能整理成周报。支持自定义模板（可永久或临时指定）、周结束日可配置（默认周五，可改周日等）。支持自然语言定位周（本周/上周/10月第2周/10月20号所在周等）。当用户请求写周报、本周周报、上周周报、生成周报、/weekly-report，或询问周报用法（周报怎么用/周报使用说明/周报有哪些使用方式）时使用。用户说「写总结/工作总结/写个汇报」等未言明周期的词时，先 AskUserQuestion 分流（日报/周报/年报）再执行，不擅自默认。
+description: 生成工作周报（默认本周结论+本周任务进度/下周计划/风险阻塞点结构，中文顿号序号，1D=8H），适配各行业（内置 12 行业职业词典，可指定角色身份）。数据来源灵活：直接口述、给一段文字、发文件（Word/PDF/Excel/PPT 等）或图片，都能整理成周报。支持自定义模板（可永久或临时指定）、周结束日可配置（默认周五，可改周日等）。支持自然语言定位周（本周/上周/10月第2周/10月20号所在周等）。当用户请求写周报、本周周报、上周周报、生成周报、/weekly-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. **解析周**（自然语言 → 目标周：周一起点、WEEK_END 结束日）→ 读 `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 **交付前自检**（落盘与截图前必做，硬门禁不可跳过）：weekly-report-YYYYMMDD.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="weekly-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="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 或无版本戳的历史产物），说『把我旧周报都升级成新样式』即可一键升级」，不让用户背触发语。
+
+## 🔧 报修处理流程（用户报页面问题时）
+
+用户说「这个页面效果不对 / 布局乱了 / 有 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 对应处并在汇报中说明「参考模板已同步修正」，避免下一份重蹈覆辙
+
 ## 规则速览
 
 - 任务进度 5-15 点、每点 30-60 字；序号用中文顿号（1、2、3）

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

@@ -9,8 +9,8 @@
 - 任务来源（默认）：各仓库本周 提交记录自动聚合（同主题多日提交合并为一条）+ 本次会话中用户已提及/口述的工作内容 + 用户口头补充，全部合并去重；仅当用户明确说"只整理这段文字/只按这段"时才忽略提交记录与会话上下文、只用指定文字（见「纯文字整理模式」）
 - 「下周计划」取材双通道：①用户口述/文字补充的计划（优先并入）；②一次生成多周周报、或后续日期日报已生成时（本次批量生成中下一周的周报，或 reports 目录中已存在的后续日报/下周周报），从下一周周报的「本周任务进度」（无下周周报时从下周各日报的任务进度）中抽取任务作为「下周计划」（抽取数量灵活、不设死上限：下周完成任务多且连续性强时可多抽至 5-6 条，少则抽 2-3 条，与下一周内容形成呼应即可），描述改写为计划语气（完成态改进行态：如「完成 XX 重构」→「推进 XX 重构」「继续 XX 开发」，去掉量化数据/进度/用时）；批量多周时优先保证跨周连续性：抽取时尽量让本周「下周计划」与下一周「本周任务进度」形成「计划→完成」的同主题承接链（如本周计划「启动 XX 重构」→ 下周完成「完成 XX 重构」，长期任务串成连续的工作链）；无后续数据时，该段按口述或「暂无」处理
 - 量化数据取自 git --stat（文件数、增删行数）；用时为合理估算（提交记录不记录耗时，估算值注明"约"，可口头修正）
-- 数据收集范围（按当前系统自动选择，另一系统的仓库自动跳过）：macOS = NearCast / nearcast-server / nearcast-go / nearcast-admin / SmartCanteenConsumerMachineApp / TrustPay 共 6 个仓库；Windows = srf-app / srf-manage / srf-operation / srf-service / srf-web-user / srf-web-operation / srf-web-wx / srf-web-h5-teacher / srf-web-uop / Spec-Core-Smart-Canteen 共 10 个仓库；本周无提交的仓库不写入
-- HTML 版为参考图式深蓝面板卡片美化样式（实心深蓝卡片 + 细密水平条纹 + 上下边缘高光线 + 左缘节色条，保留 ask 同款发光动效）：附「本周概览」Bento 卡片（完成率圆环大卡 + 提交热力图 5天×3时段 + 提交数/活跃天数/涉及文件/代码行数四指标 + 提交节奏柱图带 hover 明细 + 环比行）、头部卡片下「本周结论」卡（三行：最重要的结果/值得处理的变化/下周优先的动作，紫色左缘色条 + 紫/橙/青三色标签，与分节卡片同质感）、顶部「一键复制」按钮（复制纯文本版）+ TL;DR 摘要行、「本周任务进度」标题右侧带周范围徽章（跟随 WEEK_END）+ 进度条终点圆点与流星扫描填充 + 液态玻璃卡片（@supports 兜底）+ CRT 扫描光带 + 全页 3D 微倾斜（±0.75°）、页脚署名 GENERATED BY SPECCORE TEAM（周范围动态跟随 WEEK_END），并随 FORMATS 默认落一张内容区截图 content-png（概览与卡片整体 + 四周留白 + 周范围徽章）
+- 数据收集范围：按 user-config.md 的 DATA_SOURCES 清单收集（按当前系统自动选路径，另一系统的路径自动跳过）；本周无提交的仓库不写入
+- HTML 版为参考图式深蓝面板卡片美化样式（实心深蓝卡片 + 细密水平条纹 + 上下边缘高光线 + 左缘节色条，保留 ask 同款发光动效）：附「本周概览」Bento 卡片（完成率圆环大卡 + 提交热力图 5天×3时段 + 提交数/活跃天数/涉及文件/代码行数四指标 + 提交节奏柱图带 hover 明细 + 环比行）、头部卡片下「本周结论」卡（三行：最重要的结果/值得处理的变化/下周优先的动作，紫色左缘色条 + 紫/橙/青三色标签，与分节卡片同质感）、顶部「一键复制」按钮（复制纯文本版）+ TL;DR 摘要行、「本周任务进度」标题右侧带周范围徽章（跟随 WEEK_END）+ 进度条终点圆点与流星扫描填充 + 液态玻璃卡片（@supports 兜底）+ CRT 扫描光带 + 全页 3D 微倾斜（±0.75°）、页脚署名 GENERATED BY AI TEAM（周范围动态跟随 WEEK_END），并随 FORMATS 默认落一张内容区截图 content-png（概览与卡片整体 + 四周留白 + 周范围徽章）
 
 ## 用户补充任务