repo-atlas git:20261018.b1fe08bA

Immutable. This exact content never changes and is served at /api/v1/blob/3e339afa826887d8.

---
name: repo-atlas
description: 从真实仓库生成以项目架构、业务流程、数据流向和数据结构为主体的交互 HTML。点击模块了解职责、输入输出与关联对象，沿流程理解处理条件和结果，源码以链接和结构化依据供 AI 追溯，支持离线阅读及增量维护。适用于接手项目、梳理模块边界或制作架构图谱；不替代专项代码审计、缺陷修复或新系统设计。
---

# 项目模块图谱

按“项目架构 → 业务流程 → 数据流向 → 数据结构”组织阅读：先说明模块分工与边界，再解释业务从触发到结果的过程，随后追踪数据的来源、去向和存储关联。架构总览可直接用数据流向连接模块；同一组关系只展示一次。点击模块展示职责、流入与流出、关联数据对象，点击数据对象展示字段、键和关联。源码以简短超链接辅助追溯；结构化清单和内嵌依据保留给 AI 核对与维护。

## 范围与读者

从会话和当前目录确定项目路径、分析范围、主要读者与输出位置。未指定时，分析当前仓库，面向接手项目的研发人员，输出到工作区独立文档目录。单模块请求只追踪必要上下游；多个相关仓库可以统一纳入，但必须区分仓库、部署单元和业务分组。

先读取最近的 `AGENTS.md`、`CLAUDE.md`、README、项目记忆和交接资料，记录影响本次工作的约束。没有项目记忆或 Git 基线就明确说明。创建分析文档不授权修改业务代码、运行迁移、连接生产、上传文件或写长期记忆。

开始深入前先回答：读者最需要用报告完成什么判断；哪些业务链或模块优先；哪些环境事实本次无法核验。不要把源码目录结构直接当作架构，也不要为追求图表数量扩大范围。

## 建立证据模型

编写报告展示内容前，必须读取 [读者体验与表达约束](docs/analysis-guide.md#面向读者的表达)。报告面向人阅读：标题、模块名、阶段标签和摘要优先讲业务含义；函数名、文件路径和内部字段用于定位，放在源码依据或技术细节中。先说明“谁做什么、为何继续或中止、最后得到什么”，再补实现证据。不要把调用顺序机械转述成业务说明，也不要自动替换函数名来编造含义。

1. 记录实际分支、提交与未提交变化，枚举入口、业务编排、数据访问、模型、配置、任务、部署描述、外部适配器和测试。文件规模可由工具统计，职责必须通过阅读判断。
2. 建立与范围相称的覆盖账本。常见维度包括入口与角色、认证授权、主业务链、状态与数据、异步任务、外部副作用、失败恢复、一致性与并发、配置、部署运行、可观测性和测试。只保留相关维度，并明确 `covered`、`partial`、`unknown` 或 `not_applicable`。
3. 以用户动作或业务事件为线索，追踪入口 -> 校验与权限 -> 编排 -> 数据读写 -> 外部副作用 -> 下游读取。对改变业务事实的动作确认事务边界、重复处理、并发、部分成功、重试、补偿和状态迁移；没有实现就如实记录。
4. 为重要关系保存小段证据：真实路径、稳定文本锚点和足够的上下文。调用点与被调用实现至少交叉核对一次；不能用类名、字段名、注释或 DDL 的存在推断主链行为。
5. 区分当前值、确认计划、执行结果、历史快照、审计记录和兼容路径。对持久化对象确认关联键、基数、唯一性、写入者和消费者。字段名含 `fk` 不代表物理外键，表名被引用不代表已投产或存在业务写入。
6. 区分已确认事实、基于证据的推断和未确认项。对会影响接手、变更或运行判断的结论，使用 `findings` 记录类型、可信状态、影响和最短验证路径；不要把普通代码观察包装成风险清单。

长期维护的清单为每条证据设置稳定 `sources[].id`；重复锚点可补充 `before`、`after`，已核对摘录可用 `excerptSha256` 固定。实体中的事实、payload、条件和数据字段可用 `evidenceBindings` 绑定具体证据，避免用一个文件片段支撑整组结论。先运行 `doctor.mjs` 查看维护提醒，再按需要运行 `migrate.mjs` 自动补齐稳定 ID。

详细的覆盖取舍和证据门槛见 [analysis-guide.md](docs/analysis-guide.md)。分析跨越多个模块、包含数据写入或存在明显未知时，必须读取该文件。

## 选择视图

先给出能说明系统组成和边界的架构总览，再展开关键业务流程、需要深入的数据流、数据结构和运行边界。模块之间只展示数据流向，不提供“依赖关系 / 数据流向 / 全部关系”切换，也不另画内容重复的依赖图。使用 `relations` 的 `data_flow` 显式记录提供方、接收方、传递内容及触发条件；请求与返回分别标注。旧清单的 `dependency` 可作为结构化依据保留，不转换成数据流；没有数据流证据时说明尚未记录，不补造连线。

`views[].relations` 引用关系 ID；省略 `diagram` 时，生成器只按已声明的 `data_flow` 生成数据流图。有分层或特殊布局需求时保留手写 Mermaid，模块节点 ID 对应 `modules[].id`。总览已能解释的数据流不再建立相同的独立视图。每条关键链路在 `chains` 中登记业务阶段，流程图通过 `bindings` 绑定节点；需要显示阶段数据流时显式填写阶段的 `relations`。需要核对真实分支、异步交接、事务边界、幂等、补偿和状态结果时使用 `chains[].transitions`；需要自动生成流程图时创建带 `chain` 的 `flow` 视图，不同时手写 diagram。

自动生成的数据流图支持沿连线移动的标记、播放/暂停与模块聚焦。动画只演示清单中声明的数据方向，不代表实时流量或执行先后。尊重系统减少动态效果的偏好，导出和打印使用静态图。

数据结构使用 `tables[].fields` 描述字段、类型、键与引用，`views[].tables` 和 `aliases` 连接 ER 节点与实际对象。明确区分逻辑关联与数据库外键；内存对象或文件结构可以画成逻辑模型，但不能冒充数据库表。

如果仓库存在多条用户旅程、事件消费链、批处理链或补偿链，应按链路分别建图，不把互不相同的触发、状态和失败语义压进一张图。图表数量由需要解释的关系决定；未能确认的路径保留为明确的缺口。

- 每张图只表达一种主关系；边必须带有调用、读写、发布、消费或返回等明确动词。
- 标题点明对象与主题，如“订单架构与模块分工”“下单流程：校验、预留与记录”；副标题概括关键行为。节点说明按“职责 → 输入 → 处理条件 → 输出与去向”展开，避免把图上标签再复述一遍。
- 组织归属不暗示运行调用；源码目录不暗示独立部署；配置默认值不等于线上有效值。
- 状态图来自真实枚举和迁移逻辑。多个状态机分开；未连通或不可达状态说明来源。
- 数据图至少能回到“左对象.键 <-> 右对象.关联属性”；基数必须有实现或约束证据。
- 总览使用业务可读名称，真实接口、表名、状态码和类名放在细节视图、别名或证据弹窗。
- 分支流程标出继续、中止、失败和重复处理条件；跨角色先后关系用时序图，数据结构用 ER 图和字段说明。节点说明聚焦职责、输入输出、条件与结果。
- `stages` 的数组顺序是阅读顺序，不能自动当成实际执行连线。未知环节与已确认路径区分，不能把未实现的付款、发布或恢复画成已经发生。
- 没有图的旧清单仍可使用阶段导览；交接报告应优先补齐能回答核心问题的图。密集图拆分或提供保持节点 ID 的 `mobileDiagram`。

第一屏先给出简短用途和核心架构图。宽屏在图旁展示关系详情，窄屏就地切换图与详情，保留选中的模块、阶段或数据对象。源码依据仅以源文件链接和可选摘录链接呈现，不默认展开代码块、逐行解释或持续占据主界面的代码面板。`codeExplanation` 可作为 AI 分析注释保留，不作为人的主阅读内容。基线、完整证据和复核信息按需查阅。

## 生成报告

生成前完整读取 [manifest-format.md](docs/manifest-format.md)，在项目文档目录创建 UTF-8 `atlas.json`。业务结论、覆盖状态与 Mermaid 内容由读过源码的助手编写；生成器只校验结构、提取摘录、统计文件和读取 Git 基线，不会自动理解业务。

```text
node <skill-dir>/scripts/build.mjs <project-docs>/atlas.json
```

报告较大或需要随报告携带源码副本时，可使用内容寻址的本地资源目录；默认单文件交付不受影响：

```text
node <skill-dir>/scripts/build.mjs <project-docs>/atlas.json --assets-dir .repo-atlas/assets --source-bundle .repo-atlas/sources
```

要求 Node.js 18+。`workspace` 相对清单文件定位，`output` 必须位于工作区内，多仓路径均相对 `workspace`。无 Git 目录可省略 `repositories`。生成的 HTML 内嵌 Mermaid 10.9.3、Lucide 0.468.0、样式、图表和证据，默认离线打开，不启动项目应用，也不安装其依赖。

项目专属内容只放清单，不要修改模板来迎合单个项目。不要覆盖已有报告，除非用户要求更新或输出明确指向该文件；此时才使用 `--replace`。

只摘取说明关系所需的代码。配置只展示明确挑选且可公开的值，不把凭据、个人数据、生产样本或整个环境文件打包进报告。`redact` 只能作为最后一道字面遮盖，写出前仍需人工检查清单与 HTML。

## 快照与增量更新

不要每次代码变化都重新读取整个仓库或把完整源码放入模型上下文。首次报告生成后，在工作区保存本地快照：

```text
node <skill-dir>/scripts/snapshot.mjs <project-docs>/atlas.json
```

之后只在本地计算文件哈希、Git 状态和证据反向索引（证据文件每次重新核对哈希，未引用文件可复用未变化的文件系统元数据）：

```text
node <skill-dir>/scripts/delta.mjs <project-docs>/atlas.json
node <skill-dir>/scripts/refresh.mjs <project-docs>/atlas.json --delta .repo-atlas/delta.json
node <skill-dir>/scripts/context.mjs <project-docs>/atlas.json --changed-only
```

增量结果包含新增、修改、删除、重命名、受影响模块、失效证据、复用/重算证据数量和是否建议全量重分析。`delta.json` 只保存差异摘要，不重复嵌入当前完整快照；需要同时落盘候选快照时可加 `--snapshot-output .repo-atlas/current-snapshot.json`。源文件被删除或证据锚点消失时，快照记录 `resolved: false` 和原因，不伪造旧摘录。

刷新器输出 `atlas.next.json`，不覆盖分析者维护的基线清单；只有复核受影响源码后才接受候选清单并重新生成快照。清单本身发生变化、公共基础设施大范围变化或变更超过阈值时，候选项统一标记为待复核并建议全量重分析。模型上下文只带变更 hunk、受影响模块旧摘要、相关证据摘录和必要的一跳调用关系，未变化模块直接复用。

需要保存正式复核记录时，运行 `review.mjs <atlas.next.json>`，实际核对后填写 reviewer、reviewedAt 和每项 decision/note，再运行 `accept.mjs <atlas.next.json> --review .repo-atlas/review.json`。不得为通过校验伪造审核结论。接受命令检查版本和正式构建，生成新版本目录，保留原始输入；输出的清单、报告、基线和回执可作为下一轮起点。候选或源码变化后必须重新准备复核。

缺失或歧义证据不能接受为正式交付。排查时使用 `build.mjs <atlas.next.json> --review`，报告显式显示未解析原因，降低对应临时覆盖/可信度状态，不冒用旧摘录。视图、阶段及证据可以复制 # 定位链接；移动离线报告时保留片段。

`context.mjs` 生成 `.repo-atlas/context.json`，默认只携带 delta 中的变更文件、Git hunk、受影响链路/阶段、旧新证据摘录和一跳上下游关系；快照内的轻量摘要索引提供变更前摘要，证据摘录继续遵守 `redact`。影响路径写入 `delta.impact.paths`，上下文和报告使用同一套数据流/依赖回退规则。使用 `--stale-only` 只处理失效证据，使用 `--previous-manifest` 显式覆盖旧清单摘要。该文件是模型复核输入，不替代完整 `atlas.json` 或快照。

默认影响规则：普通实现变更影响所在模块和直接证据；路由、数据模型、锁文件、部署或公共配置变化扩大到相关入口、数据关系和运行视图；至少 10 个基线文件时变更超过约 20%、变更达到 20 个文件，或命中公共基础设施时建议全量重分析。`.repo-atlas` 快照目录默认不进入文件索引，避免工具产物污染基线。快照和差异文件只保存在本地，不上传仓库。

## 验证与交付

所有用户命令支持 `--help`；布尔选项可位于位置参数前后，未知或缺值选项会在执行前报错。完整路径与覆盖策略见 [命令参考](docs/cli.md)。比较两个清单可用 `compare.mjs old.json new.json --json`；若指定 `--output`，输出必须在当前工作目录内，已有结果需要 `--replace`，输入清单始终受保护。使用 `check-delivery.mjs <accepted-directory>` 检查已接受报告的文件完整性；它不重新扫描源码，也不认证审核人身份。

生成器首先校验路径、证据锚点、重复 ID、模块引用、发现项和覆盖状态。可用浏览器时运行：

```text
node <skill-dir>/scripts/verify.mjs <report.html> --playwright <installed-playwright/index.mjs>
```

验证脚本在断网 Chromium 中遍历实际图表和移动变体，检查渲染、页面错误、缩放拖动、证据弹窗、全文检索、索引过滤、导出、导航和移动端溢出，并写出截图和结果。Playwright 可通过显式路径、`REPO_ATLAS_PLAYWRIGHT_PATH` 或已安装包解析；脚本不下载浏览器或依赖。缺少环境时优先使用现有浏览器能力，无法执行就报告未验证项。

人工检查总览、数据流图、关键流程、ER 图和手机截图。确认模块关系只展示数据流向，点击模块能看清职责与输入输出，相关节点和连线同步突出；点击数据对象能看到字段和关联；返回或调整窗口后仍保留位置。源码链接可追溯，但主界面不依靠阅读源码才能理解。核对请求与返回的箭头、分支、未确认项、字体与裁切。浏览器通过只证明报告可用，不能替代对业务结论的复核。

可用 `--browser chromium|firefox|webkit` 指定验证引擎；分别报告实际运行结果。WebKit 会在阻断 HTTP 请求的前提下先加载本地文件，再启用离线模拟，此差异会记入结果。不要将引擎验证描述为真实 Safari/iPhone 测试。

交付可直接打开的 HTML、可维护的 `atlas.json`，以及需要持续维护时的 `.repo-atlas/snapshot.json` 与 `delta.json`；说明覆盖范围、实际验证、最重要的已确认结论、未确认项和增量复核范围。正式接受外置资源时，把 `--assets-dir` 与 `--source-bundle` 传给 `accept.mjs`，让资源和源码副本进入同一 accepted version 并由 delivery 检查。不要为套模板新增迁移方案、专项风险审计或规划需求。