--- name: repo-atlas description: 从真实仓库生成可追溯源码的项目或模块分析，覆盖架构、关键业务链、数据、部署、外部依赖与未确认项，并交付可离线探索的交互 HTML。适用于接手复杂项目、梳理模块边界或制作架构图谱；不替代专项代码审计、缺陷修复或新系统设计。 --- # 项目模块图谱 把“项目解决什么问题、由什么组成、谁调用谁、关键事实如何流动、哪里仍不确定”整理成可验证、可探索的离线报告。默认使用本技能的模板，保留全文检索、关系图导航、缩放拖动、源码摘录、覆盖矩阵，以及 SVG / Mermaid 导出。 ## 范围与读者 从会话和当前目录确定项目路径、分析范围、主要读者与输出位置。未指定时，分析当前仓库，面向接手项目的研发人员，输出到工作区独立文档目录。单模块请求只追踪必要上下游；多个相关仓库可以统一纳入，但必须区分仓库、部署单元和业务分组。 先读取最近的 `AGENTS.md`、`CLAUDE.md`、README、项目记忆和交接资料，记录影响本次工作的约束。没有项目记忆或 Git 基线就明确说明。创建分析文档不授权修改业务代码、运行迁移、连接生产、上传文件或写长期记忆。 开始深入前先回答：读者最需要用报告完成什么判断；哪些业务链或模块优先；哪些环境事实本次无法核验。不要把源码目录结构直接当作架构，也不要为追求图表数量扩大范围。 ## 建立证据模型 编写报告展示内容前，必须读取 [读者体验与表达约束](references/reader-experience.md)。报告面向人阅读：标题、模块名、阶段标签和摘要优先讲业务含义；函数名、文件路径和内部字段用于定位，放在源码依据或技术细节中。先说明“谁做什么、为何继续或中止、最后得到什么”，再补实现证据。不要把调用顺序机械转述成业务说明，也不要自动替换函数名来编造含义。 1. 记录实际分支、提交与未提交变化，枚举入口、业务编排、数据访问、模型、配置、任务、部署描述、外部适配器和测试。文件规模可由工具统计，职责必须通过阅读判断。 2. 建立与范围相称的覆盖账本。常见维度包括入口与角色、认证授权、主业务链、状态与数据、异步任务、外部副作用、失败恢复、一致性与并发、配置、部署运行、可观测性和测试。只保留相关维度，并明确 `covered`、`partial`、`unknown` 或 `not_applicable`。 3. 以用户动作或业务事件为线索，追踪入口 -> 校验与权限 -> 编排 -> 数据读写 -> 外部副作用 -> 下游读取。对改变业务事实的动作确认事务边界、重复处理、并发、部分成功、重试、补偿和状态迁移；没有实现就如实记录。 4. 为重要关系保存小段证据：真实路径、稳定文本锚点和足够的上下文。调用点与被调用实现至少交叉核对一次；不能用类名、字段名、注释或 DDL 的存在推断主链行为。 5. 区分当前值、确认计划、执行结果、历史快照、审计记录和兼容路径。对持久化对象确认关联键、基数、唯一性、写入者和消费者。字段名含 `fk` 不代表物理外键，表名被引用不代表已投产或存在业务写入。 6. 区分已确认事实、基于证据的推断和未确认项。对会影响接手、变更或运行判断的结论，使用 `findings` 记录类型、可信状态、影响和最短验证路径；不要把普通代码观察包装成风险清单。 详细的覆盖取舍和证据门槛见 [analysis-guide.md](references/analysis-guide.md)。分析跨越多个模块、包含数据写入或存在明显未知时，必须读取该文件。 ## 选择视图 先给出一张能说明系统边界和主路径的总览，再按每条重要业务链和读者问题拆图。复杂项目不能只交付一张总链路图：每条关键链路必须在 `chains` 中登记，并把入口与权限、校验与编排、数据读写、外部副作用、结果与下游、失败恢复拆成阶段，绑定对应源码证据和待确认项。链路的先后关系以阶段摘要和触发 / 结果描述呈现；不要求制作或在前端展示 Mermaid 时序图。包含状态迁移、持久化关系、异步任务或运行边界时，再分别补充状态、数据、一致性、失败恢复和部署视图。 如果仓库存在多条用户旅程、事件消费链、批处理链或补偿链，应按链路分别建图，不把互不相同的触发、状态和失败语义压进一张图。图表数量由链路数量和读者问题决定；少于三张图的复杂项目应在覆盖矩阵中明确说明原因和缺口。 - 每张图只表达一种主关系；边必须带有调用、读写、发布、消费或返回等明确动词。 - 组织归属不暗示运行调用；源码目录不暗示独立部署；配置默认值不等于线上有效值。 - 状态图来自真实枚举和迁移逻辑。多个状态机分开；未连通或不可达状态说明来源。 - 数据图至少能回到“左对象.键 <-> 右对象.关联属性”；基数必须有实现或约束证据。 - 总览使用业务可读名称，真实接口、表名、状态码和类名放在细节视图、别名或证据弹窗。 - 流程说明优先使用自然语言阶段卡片，明确触发、处理、写入、副作用、结果和待确认项；不要让读者依赖缩放或阅读密集的源码节点。 第一屏应先让读者理解项目用途，并找到关心的业务场景与结论。分析基线、证据规模和源码定位放在可以进一步查阅的细节中。重要结论直接说明业务影响，待确认事项清楚呈现。模块卡片用简短句子解释职责；交付主体必须讲清业务过程、数据变化和边界，避免把函数调用或源码摘录堆成报告。 ## 生成报告 生成前完整读取 [manifest-format.md](references/manifest-format.md)，在项目文档目录创建 UTF-8 `atlas.json`。业务结论、覆盖状态与 Mermaid 内容由读过源码的助手编写；生成器只校验结构、提取摘录、统计文件和读取 Git 基线，不会自动理解业务。 ```text node /scripts/build.mjs /atlas.json ``` 要求 Node.js 18+。`workspace` 相对清单文件定位，`output` 必须位于工作区内，多仓路径均相对 `workspace`。无 Git 目录可省略 `repositories`。生成的 HTML 内嵌 Mermaid 10.9.3、Lucide 0.468.0、样式、图表和证据，默认离线打开，不启动项目应用，也不安装其依赖。 项目专属内容只放清单，不要修改模板来迎合单个项目。不要覆盖已有报告，除非用户要求更新或输出明确指向该文件；此时才使用 `--replace`。 只摘取说明关系所需的代码。配置只展示明确挑选且可公开的值，不把凭据、个人数据、生产样本或整个环境文件打包进报告。`redact` 只能作为最后一道字面遮盖，写出前仍需人工检查清单与 HTML。 ## 快照与增量更新 不要每次代码变化都重新读取整个仓库或把完整源码放入模型上下文。首次报告生成后，在工作区保存本地快照： ```text node /scripts/snapshot.mjs /atlas.json ``` 之后只在本地计算文件哈希、Git 状态和证据反向索引（证据文件每次重新核对哈希，未引用文件可复用未变化的文件系统元数据）： ```text node /scripts/delta.mjs /atlas.json node /scripts/refresh.mjs /atlas.json --delta .repo-atlas/delta.json node /scripts/context.mjs /atlas.json --changed-only ``` 增量结果包含新增、修改、删除、重命名、受影响模块、失效证据、复用/重算证据数量和是否建议全量重分析。`delta.json` 只保存差异摘要，不重复嵌入当前完整快照；需要同时落盘候选快照时可加 `--snapshot-output .repo-atlas/current-snapshot.json`。源文件被删除或证据锚点消失时，快照记录 `resolved: false` 和原因，不伪造旧摘录。 刷新器输出 `atlas.next.json`，不覆盖分析者维护的基线清单；只有复核受影响源码后才接受候选清单并重新生成快照。清单本身发生变化、公共基础设施大范围变化或变更超过阈值时，候选项统一标记为待复核并建议全量重分析。模型上下文只带变更 hunk、受影响模块旧摘要、相关证据摘录和必要的一跳调用关系，未变化模块直接复用。 需要保存正式复核记录时，运行 `review.mjs `，实际核对后填写 reviewer、reviewedAt 和每项 decision/note，再运行 `accept.mjs --review .repo-atlas/review.json`。不得为通过校验伪造审核结论。接受命令检查版本和正式构建，生成新版本目录，保留原始输入；输出的清单、报告、基线和回执可作为下一轮起点。候选或源码变化后必须重新准备复核。 缺失或歧义证据不能接受为正式交付。排查时使用 `build.mjs --review`，报告显式显示未解析原因，降低对应临时覆盖/可信度状态，不冒用旧摘录。视图、阶段及证据可以复制 # 定位链接；移动离线报告时保留片段。 `context.mjs` 生成 `.repo-atlas/context.json`，默认只携带 delta 中的变更文件、Git hunk、受影响链路/阶段、旧新证据摘录和一跳上下游关系；快照内的轻量摘要索引提供变更前摘要，证据摘录继续遵守 `redact`。使用 `--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 ` 检查已接受报告的文件完整性；它不重新扫描源码，也不认证审核人身份。 生成器首先校验路径、证据锚点、重复 ID、模块引用、发现项和覆盖状态。可用浏览器时运行： ```text node /scripts/verify.mjs --playwright ``` 验证脚本在断网 Chromium 中遍历实际图表和移动变体，检查渲染、页面错误、缩放拖动、证据弹窗、全文检索、索引过滤、导出、导航和移动端溢出，并写出截图和结果。Playwright 可通过显式路径、`REPO_ATLAS_PLAYWRIGHT_PATH` 或已安装包解析；脚本不下载浏览器或依赖。缺少环境时优先使用现有浏览器能力，无法执行就报告未验证项。 人工检查总览、最密集数据图、流程说明、发现项与覆盖矩阵，以及桌面和手机截图。重点检查字体过小、连线压字、裁切、空白失衡、术语不一致、流程是否能用自然语言读懂，以及结论与证据不匹配。浏览器通过只证明报告可用，不能替代对业务结论的复核。 可用 `--browser chromium|firefox|webkit` 指定验证引擎；分别报告实际运行结果。Windows WebKit 会在阻断 HTTP 请求的前提下先加载本地文件，再启用离线模拟，此差异会记入结果。不要将引擎验证描述为真实 Safari/iPhone 测试。 交付可直接打开的 HTML、可维护的 `atlas.json`，以及需要持续维护时的 `.repo-atlas/snapshot.json` 与 `delta.json`；说明覆盖范围、实际验证、最重要的已确认结论、未确认项和增量复核范围。不要为套模板新增迁移方案、专项风险审计或规划需求。需要复制提示词到其他工具时，再提供 [可复制提示词.md](references/可复制提示词.md)。