# 架构评审 Workflow

## 定位

用于在实现前评估系统架构、服务边界、技术选型、数据模型、Runtime、RAG / GraphRAG 和长期复杂度。

本 Workflow 面向建筑行业项目的架构评审增强。普通非建筑架构评审优先使用宿主工具的通用架构能力；只有项目 profile、上下文或任务事实涉及建筑行业语义、工程知识、RAG / GraphRAG、审图、证据链、人工复核或审计留痕时，才启用 `aios-*` 行业增强。

## 触发场景

- 新系统、新模块或核心服务设计。
- 服务拆分、数据模型、存储组件或技术栈调整。
- Hermes / OpenClaw / Agent Runtime 重大变化。
- RAG / GraphRAG、知识图谱或 BIM / IFC 模块边界设计。

## 参与角色与 Skill

| 阶段 | 主 Agent | Skill |
| --- | --- | --- |
| 可选战略双审 | Janus | `aios-ceo` |
| 可选产品契约 | Janus | `aios-product` |
| 架构判断 | Atlas | `aios-arch` |
| 架构健康事实与棘轮 | Atlas | `aios-arch-health` |
| 工程拆解 | Mason | `aios-plan` |
| Runtime 设计 | Daedalus | `aios-runtime` |
| 行业语义 | Vitruvius | `aios-knowledge` |
| 结构力学 / 求解链路 | Euclid | `aios-structural` |
| 风险审查 | Argus | `aios-review` |

## 输入

- 背景和目标。
- 当前架构、目录、模块和数据结构。
- 现有代码、配置、接口契约、测试、脚本、部署入口和运行方式。
- 候选方案。
- 约束：成本、时间、团队、运行环境、权限、数据规模。
- 已知风险和历史决策。
- 可用 Capability、工具返回值、测试 / 构建 / 规范查询 / 求解器证据。
- 已确认的 CEO 战略边界或 Product 版本契约，如存在；纯技术评审不强制补齐。

## 执行顺序

1. Atlas 明确问题类型和评审边界；用户明确要求 CEO + Arch 时，Janus 同时做独立战略评审，双方共用事实底稿。
2. Atlas 基于现有代码、配置、契约、测试、脚本和部署入口核验事实；需要复杂度、依赖、覆盖率或趋势证据时，先用 `aios-arch-health` 生成确定性事实和棘轮结果。文档结论必须能回到项目事实。
3. Atlas 做技术范围挑战，明确当前评审接受的实现范围和不在范围内的扩展项；不用技术建议替代 CEO 的项目停损或 Product 的版本优先级。
4. Atlas 盘点已有能力，确认应复用的模块、契约、测试和脚本。
5. Atlas 做端到端链路抽样：对关键用户输入、配置字段、领域元数据、版本关系、审计关系或跨存储关系，至少追踪一条从 UI / API / CLI 入口到领域模型、后台任务、存储、检索/消费端和测试的完整路径。
6. Atlas 对候选方案做 tradeoff，识别复杂度、技术债、生产失效方式和长期迁移成本。
7. Atlas 用 P0/P1/P2 或等效等级标注风险优先级，形成架构依据。
8. Daedalus 评审 AI Runtime / RAG / Tool / Memory 相关设计。
9. Vitruvius 评审 BIM / IFC / 建筑规范相关语义。
10. Euclid 评审结构力学、荷载、边界条件、FEM 或求解器接口相关问题；关键数值必须来自确定性求解器或标记 `需核验`。
11. Argus 评审安全、权限、Prompt 注入、依赖和发布风险。
12. 对 Agent 冲突输出中文化的 `判断事项 / 证据 / 工具结果 / 处理建议`，按 `governance/arbitration-protocol.md` 仲裁。
13. Atlas 做交付审查增强：列出本次事实刷新、历史报告过期判断、与既有报告 diff、领域风险 / 工程风险分类，以及每个高优先级发现的文件落点和验证方式。
14. 存在 Product 契约时，Atlas 对需求逐项返回 `支持 / 需调整 / 技术阻断`，Janus 回写版本范围和非目标；若核心价值、目标市场或投入边界必须改变，升级到 CEO 模式。
15. Mason 将通过评审的方案拆成可执行任务，并纳入 Failure Modes、测试缺口、并行 workstream 和冲突点。

## 输出

1. 结论
2. 架构判断
3. 风险与边界
4. 推荐方案
5. 已拒绝方案
6. 假设 / 需核验
7. 失败模式
8. 判断事项 / 证据 / 工具结果 / 处理建议
9. 后续执行任务
10. 本次事实刷新
11. 已过期判断 / 与既有报告 diff
12. 第一小步建议
13. 联合评审时的战略判断 / 技术判断 / 一致项 / 冲突项 / 处理建议

## 文档与补充检查

当架构评审需要审阅设计文档、对比多份评审或整合补充检查项时：

- 先回到现有代码、配置、接口契约、测试、脚本和部署入口核验事实。
- 再判断各检查项的定位：架构依据、工程计划、代码审查、测试计划或风险清单。
- 架构依据优先采纳边界判断、风险分级、长期演进和被拒绝方案。
- 工程计划优先采纳 Failure Modes、测试缺口、并行 workstream、冲突标记和回归命令。
- 纠正文档中的细节错误，例如假设与需核验数量混淆。
- 对“未覆盖”的判断要谨慎：如果已有评审已触及某风险但未形成完整策略，应写成“已触及但未系统展开”。
- 如果本次是“全新独立评审”，仍应建立历史高优先级发现的回归清单；清单只用于防止漏检，不要求继承旧报告结论。
- 抽象发现不能吞掉具体断链。若某字段、关系或元数据已经被纳入更大的 P1/P2 主题，还必须说明是否完成端到端贯通；未贯通时应保留独立风险或验收项。
- 对 RAG / GraphRAG、规范知识库和审计系统，重点抽查 `source_version`、适用地区、专业、生效状态、复核状态、版本替代关系、证据引用和缓存/索引版本是否从摄取入口贯通到消费端。
- 每个 P0/P1/P2 发现必须标注为 `领域风险`、`工程风险` 或 `混合风险`，并说明文件 / 模块、最小改动范围和验证命令；无法定位时标为 `需核验`。
- 最终必须给出“现在最该做的一件小事”，优先选择低风险、可验证、能消除静默错误或关键漂移的动作。

## 仲裁门禁

当 Atlas、Mason、Vitruvius、Euclid、Daedalus 或 Argus 的判断冲突时：

- 先把意见转成判断事项，不直接用自然语言争论结论。
- 优先采纳确定性工具、项目事实和结构化知识证据。
- 工具结果缺少输入、版本、适用条件或执行状态时，标为 `需核验`。
- L1 工具失败、规范适用性冲突、安全权限失败或结构输入无效时，阻断进入 Mason 拆解或 Hephaestus 执行。
- 涉及生产授权、法规合规最终判断、结构安全结论或商业范围取舍时，升级给人类负责人。

## 端到端链路抽样清单

架构评审至少抽查以下一类链路；涉及知识、审计或合规结论时应优先抽查多类：

- 用户提交字段：页面表单、前端 API 封装、后端 DTO / query / form 参数、后台任务、领域模型、持久化和回显。
- 领域关系：版本替代、引用关系、父子层级、任务到报告、报告到复核、事件到 outbox。
- 知识元数据：来源、版本、地区、专业、生效状态、来源哈希、页码范围、质量状态和人工复核状态。
- 运行期边界：配置变更、缓存 key、索引版本、任务状态、多实例共享和重启恢复。

输出要求：若链路断在任一层，应写清断点、静默失败方式、用户可见影响和最小回归测试。

## 升级与人工确认

以下情况必须人工确认：

- 核心技术栈替换。
- 生产数据模型迁移。
- Runtime 权限扩大。
- 自动执行权限放开。
- 影响长期平台路线的服务边界调整。
- 法规合规最终判定和结构安全结论。

## 验收标准

- 推荐方案有明确边界和取舍。
- 被拒绝方案有原因。
- 后续任务可被 Mason 拆解。
- 不确定项和待验证项被显式记录。