explain-architecture

解释架构

先选择分支，再选择模型。以指定角色探索、组装、验证并检查可视化成果。在分派独立的研究工作之前，通过 shared/references/model-preview.md 获取或复用恰好一个获批快照。

建立对代码库（或其中所选部分）的准确认知，并将其制作成一个独立的 HTML 导览页面。目标是帮助读者熟悉架构，而不是进行评判——读者看完后应了解各个部分是什么、如何组合、数据如何流动，以及接下来该看哪里。

借鉴自 Practical Model-Driven Enterprise Architecture：解释是一种视图，用于回答面向特定受众的明确问题，并分为结构（有哪些部分，它们如何连接）和行为（发生什么，以及按什么顺序发生）。先选定范围和受众，再只解释与之相关的内容——“一个视图只表达一个观点”。

结果主线

• **产出：**一个包含内联 CSS、JavaScript 和 SVG 的 .html 文件，默认路径为 docs/<scope>-architecture.html。
• **后续读者：**正在熟悉架构的人——直接从磁盘打开，无需服务器。
• **完成标准：**文件已存在，scripts/validate_explain_architecture.py 以 0 退出，并且页面已渲染或发送给用户。
• **意图：**这是一张地图，而非疆域本身。包含 4–6 个章节、一条追踪完整的流程，且每个论断都有实际读取过的文件作为依据。更深入的内容应交给 html-explainer。

步骤 0 — 范围与受众（仅在不明确时提问）

开始探索前，先确定两件事；能从请求中推断时就直接推断，无法推断时最多提出一个简短问题：

• 范围——整个代码库、一个服务、一个功能/流程，或一个模块。
• 受众 / 视角：
  • 新手——入门概览，尽量少用术语，并说明“从哪里开始”。
  • 实现者——提供足以在此处添加功能的信息：扩展点、惯例和注意事项。
  • 审查者——边界、依赖、不变量和风险区域。

如果用户只说“解释架构”，没有其他限定，默认采用 新手 + 全代码库概览。

确定视角后，先阅读 references/viewpoints.md，了解该视角的侧重点和页面篇幅预算，再开始探索。

输出路径：项目仓库中的 docs/<scope>-architecture.html。明确要求更新该产物，即表示授权修改指定范围。若现有目标文件未被选定为替换对象，请使用新路径，或询问要更新哪个产物；保留无关内容。

步骤 1 — 探索（不要猜测）

遵循共享证据规范 shared/references/grounded-evidence.md：每项论断都必须基于实际读取过的文件，引用 path:line，绝不凭空还原代码。由外向内进行：

1. 入口与清单——包清单、工作区文件、部署模板、当前项目说明、README、docs/ 和配置。这些文件能以较低成本说明项目意图。
2. 顶层结构——梳理目录树与职责的对应关系。为每个主要单元命名，并用一句话说明其作用。
3. 连接处——各单元如何通信：HTTP 路由、消息总线/事件、共享数据层、定时任务/工作进程。连接处_就是_架构。
4. 一条真实的端到端流程——追踪一个有代表性的请求或事件如何经过各层（例如前端操作 → API 路由 → 服务 → 实体/数据库 → 发出的事件 → 工作进程）。具体的追踪胜过抽象描述。
5. 横切关注点——身份验证、多租户、错误处理、迁移、代码生成。

对于较大的范围，仅当某个领域相互独立、内容充实且存在重要证据缺口时，才分派研究工作。每个选定的工作者都必须使用获批快照。嵌套工作者不得重新解析路由，也不得再添加工作者。其他情况下，以指定角色进行探索。保留结论、源文件路径和简短且已核实的代码片段，不要复制整个文件。每个计划章节都有引入句、架构图事实和 1–3 段带有 path:line 的原文摘录后，即可停止探索。

步骤 2 — 按层组织

将组件归入（书中所述的）三个层次，让读者看到的是顺序，而不是清单：

• 业务层 — 领域规则与不变量。
• 应用层 — 用软件自动化领域：服务、路由、工作进程、前端应用。
• 技术层 — 基础设施的底层支撑：云运行时、数据库、身份验证、构建/部署。

根据实际发现来划分层次，不要生搬硬套这些名称——如果仓库没有单独的工作进程层，就不要在页面中添加这一层。

步骤 3 — 组装页面

将此技能目录中的 assets/template.html 复制到输出路径，并替换其中的占位内容。阅读 shared/references/html-page-conventions.md，了解自包含、三个深度、转义和验证方面的要求。下表说明了此技能页面的结构。

按以下方式将说明映射到模板：

页面区域	内容
标题副标题	**用一段话说明：**系统是什么，以及它唯一的组织思路（例如“事件驱动的无服务器单体仓库、按组织划分的多租户、OpenAPI 优先的前端”）。
全局概览图	用一个 SVG 展示各部分及其连接处，按层（业务层／应用层／技术层）分组，每个框都用 onclick="jump('sec-…')" 链接到对应章节。图注说明页面未涵盖的内容。
技术栈网格	只列出当前视角所需的内容：新手视角列出 3–5 项，评审视角展示完整的运行时全貌。如果没有补充作用，则省略此区域。
1 · 各组成部分（结构）	每个主要组件用一个 details.drill 展示：一句话说明职责、路径，以及它交互的相邻组件。
2 · 各部分如何协作	说明层次、依赖方向、连接处及其契约。若依赖方向很重要，则添加一个小型章节示意图。
3 · 端到端流程（行为）	用 .flow 步骤追踪一个真实请求／事件，每一步都包含 path:line 代码栏和一段简短的原文片段。
4 · 横切关注点	只涵盖与范围相关的身份验证、多租户、迁移、代码生成等内容。
5 · 后续阅读建议	列出读者应根据目标优先查看的 3–5 个文件／目录。

仅当当前视角确有需要时才添加第六个章节（评审者：边界与不变量；实现者：扩展点与约定）。最多只能有六个章节——超过六个，说明主题更适合使用 html-explainer。

将书中“建模最佳实践”应用于页面时，遵循以下规则：

• 每页只讲一个要点。 如果两个子系统都需要完整介绍，就分别创建两个页面并互相链接。
• 只提供受众所需的细节——新手不需要了解每个 Lambda；评审者则需要了解各个边界。
• 使用代码库自身的术语（其分类体系）为事物命名，不要另造术语。
• 不要加入主观评论。 如果某个问题妨碍理解，可在一个提示框中说明；质量评判属于 architecture-lens 的职责，而非此技能的职责。
• 对每段代码片段，遵循要么原文引用，要么不引用的原则，如证据约定所述。

步骤 4 — 验证

SKILL_DIR="<absolute path of the directory containing this SKILL.md>";
python3 "$SKILL_DIR/scripts/validate_explain_architecture.py" <output-file.html>

修复所有问题，直到退出代码为 0，然后按照共享约定中的验证步骤操作（渲染页面，点击一个 jump() 确认能跳转到对应章节，并检查首屏以下的 DOM 查询）。

步骤 5 — 交付

首先给出文件路径和导航方式（点击概览图中的框，展开 ▸ 面板）；每个章节用一行列出；说明有哪些部分无法通过视觉方式验证。如果读者想进一步深入某个子系统，可推荐使用 html-explainer——沿用原有范围、视角和资料包，避免重复探索。