| name | project-overview |
| version | 1.2.0 |
| description | 整理项目全链路结构与流程，生成单文件 HTML 总览（tab 分模块、字段级折叠明细、记录 git 版本）。当用户要求整理项目结构/梳理全链路流程/生成或更新项目总览 HTML、或代码改动后要同步总览口径时使用。 |
| metadata | {"requires":{"bins":["git"]}} |
项目全链路总览（project-overview）
把「从输入到产出的全链路流程与细节」整理成单文件 HTML 总览。产出物：
docs/全链路流程总览.html（或用户指定路径）。
skill 自带三件套（在本 skill 目录的 assets/ 下），新建报告直接用，
不要从零写样式或交互：
| 文件 | 作用 | 缺了会怎样 |
|---|
assets/skeleton.html | HTML 骨架（页眉/tab/折叠表/占位块示例） | 手写易错 tab- 前缀与折叠行顺序 |
assets/overview.css | 全部样式 | 无样式裸页 |
assets/overview.js | tab 切换 + hash 同步 + 行内折叠 | 点折叠行无反应、tab 点不动 |
起步：cp assets/skeleton.html <目标路径> → 把 assets/overview.css 与
assets/overview.js 全文粘进骨架对应的 <style> / <script>（骨架里已标注
粘贴位置）→ 按实际模块替换 tab 与内容。本规范任何项目通用，
不预设模块清单，模块以扫描结果和用户确认为准。
核心流程（每轮都先问，不擅自推进）
① 扫模块 → ② 问：初版总览 or 深挖某模块 → ③ 生成/填充 → ④ 展示等确认 → 回到 ②，直到无占位块
- 第 ② 步是硬规则：每次完成一轮后，列出剩余未填充模块，问
「继续深挖哪个模块 / 直接出初版」，不要自作主张一路填完。
- 用户确认某模块细节已够（或要求调整）后才进入下一模块。
- 全部填充完毕后做一次残留检查（见「完成检查」），再向用户交付。
① 扫描项目模块（通用方法，不预设清单）
read 项目根目录 + glob 各目录结构，读项目说明文件
（CLAUDE.md / AGENTS.md / README.md）与各模块入口文件确认职责边界。- 按数据流组织模块划分：入口（消息/请求接收与适配）→ 核心管线各阶段
（按产物流拆分）→ 汇总/产出层 → 支撑素材与知识库 → 基础设施（存储、
外部服务、契约、工具）。
- 模块命名与划分口径先问用户确认，不自己发明——命名返工成本高
（实例：曾把「维度分析」当主管线、把编排单位和功能单位混在一起，用户
纠正后才定稿）。划分结果若用户有既定口径（如「层1/层2/层3」），一律
沿用用户口径。
内容权威源：产物契约 / schema 是层间协议的权威源；实现文件确认实际
行为；文档注释与实现冲突时以契约为准并在总览里标注差异。
② 交互决策（每轮生成前先问）
- 首轮：问「生成初版总览（大流程），还是直接深挖某个模块？」
- 后续每轮：展示当前成果 + 剩余模块清单，问「继续哪个 / 收尾？」
- 用户说「先出初版」→ 只填大流程（模块职责表 + 流程框图），每页留
.todo 占位块；用户说「深挖 X」→ 填 X 的指标/字段级明细。
③ 生成 HTML 的规范（骨架 + 三件套）
- 起步用
assets/skeleton.html，不从空文件写。CSS/JS 取本 skill 的
assets/overview.css / assets/overview.js，内联进 <style> / <script>
（保持单文件离线可开）。样式或交互要改只改 skill assets/ 里这两个文件，
不在报告里派生第二份。
- 单文件：无外部依赖，离线可开；
<meta charset="utf-8">。
- JS 必带：折叠与 tab 全靠
overview.js，漏了页面看着正常但点不动
——交付前必须实际点一次验证。
- Tab 栏：
nav.tabs + section.tab-page，URL hash 记录当前 tab
（location.hash，刷新/分享停在原页）。
- 页眉
header.site：渐变蓝底。必须含 git 版本行（见下节）。
- 每页结构：
h2 模块标题（带目录 code 标注）→ card 概览/流程框图 →
职责表 → 明细。流程用纯 CSS 框图（.flow / .fnode / .farrow），不用图片。
- 明细统一用「表格行内折叠」：主行
tr.gx-row（点击展开）+ 紧跟的
tr.gx-detail hidden（明细表）。样式已内联在 overview.css，直接复用：
- 指标级明细 4 列：名称（字段）| 需求/产品对应名 | 产出 | 依赖与口径
- 中间产物明细 3 列：字段 | 产出 | 说明
- 折叠行样式：
▸ 指示符、table-layout: fixed 固定列宽（长字段名
word-break: break-all，否则长名会撑爆表格）。
- 徽标：
.badge code|llm|mix 标注每个指标/维度的产出方式
（CODE / LLM / CODE+LLM）——没有 LLM 的项目删掉对应徽标用法即可。
- 占位块：未填充细节用
.todo 块（橙虚线「待填充细节」），逐条列深挖
方向；填充后必须删除对应占位块。
- 对齐外部需求文档（如有）：明细表每行给「需求/产品指标名称」（加粗，
与文档原文一字不差）+ 展示位/出处（小字）。发现实现与文档不一致时，
在文档内标注差异，不擅自改口径。
- 口径要写「怎么算」：公式、阈值常量、降级路径、跨模块回填来源，都是
用户要看的细节。
git 版本记录（页眉 + 更新流程）
页眉副标题格式：
{一句话定位} · 按功能模块划分 · 更新于 {YYYY-MM-DD HH:MM}
（代码 {git rev-parse --short HEAD} · {最近一条 commit 标题摘要} · 已同步 MR !N/!M 的口径变更）
- 生成/更新时必做：
git rev-parse --short HEAD + git log --oneline -1，
把短 commit 号与摘要写进页眉。没有版本行视为未完成。
- 更新触发：代码改动（MR 合入、修复提交）后，用户要求同步总览时：
git log --oneline -10 + 相关 spec/变更记录，盘出本次改了哪些口径；- 在 HTML 里搜对应锚点（字段名/口径描述），逐处更新；
- 更新页眉时间戳 + commit 号 + MR 号；
- 检查残留旧口径（grep 旧字段名/旧描述确认无漏网）。
完成检查（交付前必做，可脚本化）
import re, pathlib
h = pathlib.Path("<报告路径>").read_text(encoding="utf-8")
print("残留占位块:", len(re.findall(r'class="todo[\s"]', h)))
navs = re.findall(r'data-tab="([\w-]+)"', h)
secs = re.findall(r'id="tab-([\w-]+)"', h)
print("tab 配对:", navs == secs, navs, secs)
print("折叠行配对:", len(re.findall(r'class="gx-row"', h)) ==
len(re.findall(r'class="gx-detail"', h)))
print("含版本行:", bool(re.search(r'代码 [0-9a-f]{7,}', h)))
print("含交互 JS:", "gx-detail" in h.split("<script>")[-1])
脚本全绿后必须用浏览器实跑——源码检查看不出交互失效与版式溢出：
- 切 tab、点两个折叠行、改 hash 与按后退键（验证
hashchange）；
- 多视口查横向溢出（1440/1280/1024/760），任一视口
scrollWidth > clientWidth 即有元素撑穿容器：
({ scrollW: document.documentElement.scrollWidth,
clientW: document.documentElement.clientWidth,
overflow: document.documentElement.scrollWidth > document.documentElement.clientWidth + 1 })
[...document.querySelectorAll('div.card, li, td, .fnode')]
.filter(el => el.scrollWidth > el.clientWidth + 1)
.map(el => ({ tag: el.tagName, cls: el.className, sw: el.scrollWidth, cw: el.clientWidth }))
- 验证改动时用
?v=<时间戳> 绕缓存，否则跑的是旧 CSS/JS 会误判。
常见坑
| 坑 | 处理 |
|---|
| 长字段名撑爆表格 | 明细表 table-layout: fixed + 首列 word-break: break-all（overview.css 已有） |
| 连续 ASCII 长串撑穿整页 | 白名单/路径串（a/b/c/d… 200+ 字符）在 CJK 段落里不断行，顶穿容器产生整页横向滚动。overview.css 已加 .card, .card p, .card li, .fnode, td, .hint { overflow-wrap: anywhere; }；验证必查 scrollWidth > clientWidth |
| 只内联 CSS 忘了 JS | 页面样式正常但 tab 点不动、折叠行无反应。overview.js 必带，交付前实点验证 |
| 从空文件手写 HTML | 用 skeleton.html 起步；手写易错 tab- 前缀、折叠行顺序、colspan |
gx-detail 放在 gx-row 之前 | 折叠靠 nextElementSibling，顺序颠倒即失效 |
| 只在启动时读一次 hash | 手改 #tab、站内锚点、后退键都不切内容。必须监听 hashchange；点 tab 用 pushState（replaceState 会让后退键失效）——overview.js 已修 |
| 浏览器缓存导致「改了没生效」 | 验证时用 ?v=N 绕缓存或硬刷新，否则跑的是旧 JS，会误判修复无效 |
| 折叠块新开独立章节（用户明确不喜欢） | 折叠必须做在表格的行内，不新开位置 |
| 文档注释与实现/契约冲突 | 以契约 + 实现为准，总览里按实际行为写并标注 |
| 需求/产品指标名对不上 | 从文档原文复制名称，发现命名差异标注出来，不猜 |
| 忘了页眉版本行 | 每次更新总览都必须刷新 commit 号与时间戳 |
| 多轮对话后内容漂移 | 每轮填充完让用户看一遍再继续，口径变更逐处 grep 确认 |
| 模块命名自作主张 | 划分口径先问用户，沿用用户既定叫法（层1/层2…） |
Git 红线（默认先批准后执行）
- 提交/推送 HTML、
git add 等一律先展示命令等用户批准；只读（log/
rev-parse/status）可直接执行。
- 产物默认本地工作文档，是否入库由用户决定（实例：20260813 用户明确说
「提交吧」后才提交，此前一直未跟踪）。
