AI Agent 一周提交几十个 PR，架构地图怎样保持有用？Archwhere 的做法
当编码 Agent 开始并行修改多个模块，逐个 diff 审查很快会变成高成本工作：你能看到改了哪些文件，却未必能迅速判断改动落在哪个系统组件、是否触及安全边界，以及架构说明是否已经过时。传统架构图依赖人手维护，时间一久容易与代码脱节；只按路径分配负责人的 CODEOWNERS 文件则不表达组件之间的关系。
Archwhere 尝试把架构地图变成 Agent 工作流的一部分：仓库用一个 JSON 文件声明组件和路径映射，工具把 PR、任务和 Agent 的活动关联到地图上，并通过检查命令发现未映射文件或过期规则。它不是自动替你做架构决策，而是把“地图是否跟上代码”变成可检查的工程约束。
从仓库生成初稿，再由团队校准
项目 README 给出的快速开始命令是：
npx archwhere init
init 会根据目录结构、package.json workspaces 和导入边生成模型草稿，并写出 PR 评论工作流及 Agent 监听器。README 特别强调生成的是带有推测分类的初稿——例如目录名可能影响 security、product 或 ops 等 kind 判断；团队仍需审阅和修订，而不能把自动猜测当作架构事实。
模型以组件为核心，可以声明名称、类型、路径匹配规则、关注词和依赖。README 示例中的核心结构如下（省略了其他可选字段）：
{
"system": "Meridian",
"components": {
"auth": {
"name": "Auth & sessions",
"kind": "security",
"paths": ["core/auth/**"],
"watch": [{"pattern": "session|token|rbac", "note": "security review"}],
"deps": []
}
}
}
这里的价值不在于 JSON 本身，而在于团队明确表达“哪些文件属于哪个组件”以及“哪些变化值得额外注意”。README 说明 ** 可以跨目录匹配，而 * 留在单层；当多个规则匹配时，较长的规则优先。配置应尽量窄且可读，避免一个宽泛 glob 把无关文件都归入同一组件。
把地图接进日常检查
Archwhere 提供几个清晰的本地命令：
npx archwhere npx archwhere --base origin/main npx archwhere check npx archwhere check --fix npx archwhere heat npx archwhere doc --out ARCHITECTURE.md npx archwhere mission
默认命令查看当前工作树触及哪些组件；--base 可把比较基线指定为 origin/main。check 用于检查模型有效性、是否有文件未映射，以及 glob 是否过时；check --fix 会提出或应用将未映射文件归入最近组件的修复，变更仍应由人确认。heat 汇总最近 30 天变动较频繁的组件，适合发现 Agent 正集中改动的区域；doc 可生成架构文档；mission 启动本地交互界面。
项目还提供 GitHub Action：
- uses: tapaskar/archwhere@v1
README 描述的 PR 评论会列出涉及的组件、类型和文件，并标记安全相关信息及地图中的受影响部分。团队可以把 archwhere check 纳入 CI，避免新增路径长期无人认领；但这类检查只能验证声明与规则，不会证明设计本身正确，也不能代替代码审查。
地图也是 Agent 协作入口
Archwhere 的一个特别设计，是把讨论绑定到组件。README 描述的 Mission UI 支持点击组件打开 GitHub Issue 线程，Agent 可以在对应线程回复，回复随后显示在地图界面上。系统依靠 GitHub 作为协作总线，并不直接启动或控制 Agent；任何已有 GitHub 监听能力的 Agent，也可以关注带有 component:* 标签的 Issue。
项目还允许配置运行时状态端点，为组件展示健康信息；端点返回值按 README 中的示例使用 components 对象组织。由于这是可选集成，应先按项目文档配置自己的端点，不能把示例 JSON 当成可直接访问的公共服务。
适用边界与落地建议
Archwhere 适合已经有多个组件、Agent PR 数量增长、且团队愿意维护一份轻量架构声明的仓库。它的卖点是“让变更可定位、让地图可检查”，不是从代码自动推导出无争议的架构真相。若组件边界尚不稳定，先从核心目录建立少量映射，再逐步扩展；把安全区、关键依赖和需要人工关注的词显式写入模型，定期审阅 check 的结果。
与 CODEOWNERS 相比，它更强调组件语义和架构视图；与 Structurizr、IcePanel 等建模工具相比，README 的设计目标是让 Agent 也参与维护并将改动映射到 PR。它并不取代这类工具的全部建模能力，适合把“变更落在哪里”作为首要问题的开发团队。
Archwhere 是 MIT 许可的开源项目，README 声称零依赖、以单个 JSON 文件描述模型。建议先在一个非关键仓库试用 init 生成初稿，再人工校准路径和组件，最后把 check 加入 CI。这样既能获得自动化带来的可见性，也不会把模型生成结果误当成架构审定。