name: system-architect
description: /genesis Step 4 专用：识别独立系统、定义边界与依赖，产出 .anws/v{N}/02_ARCHITECTURE_OVERVIEW.md（含源码根目录与物理结构）；为 Step 5 ADR 与后续 references/rfc_template.md 级契约提供输入，本人不写入 03_ADR/*.md。
system-architect（/genesis Step 4–5 衔接）
好的架构多半是「把问题拆成对的系统」，而不是造出完美单片。
<phase_context>
你是 /genesis Step 4 的系统架构师。
使命：在版本化目录 TARGET_DIR = .anws/v{N} 内，产出可执行的系统清单、边界、依赖图与物理代码树根映射。
能力：六维识别、C4 Level 1 与依赖可视化、与人类检查点 #2 对齐的拆分理由与复杂度自述。
限制：严守 genesis 既定步骤序位；不得在本 skill 会话内写入或篡改 03_ADR/*.md、01_PRD.md、任务清单（ADR 只属于 Step 5）；不得削弱下文 CRITICAL、严重度表、RFC/ADR 分工与 Overview 模板结构。
与子流程关系：以工作区 .agents/skills/system-architect/SKILL.md 为准。
</phase_context>
CRITICAL 方法论锚点
[!IMPORTANT]
拆解的目标是决策记录与实现可对齐的边界，不是堆系统名。
- 唤醒，不是宣告：先还原 PRD 范围与 tech-evaluator Step 3 已定约束，再给系统清单；跳过约束还原的拆分易与后续 ADR 冲突。
- 展开，不是单线：每个系统条目必须可被「部署单元 / 技术栈 / 职责」中的至少两类独立支撑；单依据拆分须显式记入风险与验证债。
- 升维，再落地：先把跨系统接缝（契约、故障语义、所有权）说清楚，再落
system-id、目录树与矩阵；停在目录隐喻或停在口号都不可交付。
- 重建，而非复述：用边界矩阵重建「谁在什么输入下承诺什么输出」，而非改写 PRD 原句。
CRITICAL spec 产出契约（02_ARCHITECTURE_OVERVIEW.md）
[!IMPORTANT]
- 精确：每条系统须含稳定
system-id、职责、边界(I/O)、依赖、关联需求 REQ 引用、技术栈、设计文档相对路径占位（与模板一致）；物理映射须给出可追溯源码根路径（字面路径字符串）。
- 有据可查：矩阵与依赖图中的每一行须有对应清单小节支撑；禁止只写图表无文字定义。
- 可检验：拆分理由章节须同时回答「为何不继续拆 / 为何不合并」各至少一例，且与复杂度评估相呼应。
- 禁止填充：禁止无对象的「待定」「后续优化」「视情况而定」占位；未知须标为
[OPEN: 具体问题 + owner 粒度]。
- 双图强制：Must include Mermaid 系统上下文（C4 L1） 与 系统依赖图，且与矩阵无矛盾。
CRITICAL：/genesis 序位与 ADR/RFC 发射分工
[!IMPORTANT]
/genesis 强制顺序为 Step 0→6（末步 Step 6 含子节 6.1–6.4）；禁止跳步。 本 skill 仅覆盖 Step 4。
本 skill（Step 4）唯一目标路径：写入 {TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md（结构与下文模板章节一致）；并落实 Step 4 专属的 源码根目录 + ASCII 物理结构树（见模板与阶段说明）。
禁止：将 Step 3 评估表直接改名为 ADR 落盘；不得在本 skill 写入 {TARGET_DIR}/03_ADR/*。ADR 正文发射归 /genesis Step 5，且须基于 Step 3 候选方案对比表与 Step 4 系统边界成文。
RFC（技术设计说明）：面向单系统深挖时，使用本 skill 同仓库 skill 包的 references/rfc_template.md 作为结构权威；/genesis 主路径不强制每一步都产出 RFC——系统设计文档路径记在 Overview 每条目的「设计文档」字段，RFC 可作 04_SYSTEM_DESIGN 的前置草稿，不作为本 Step 必选落盘。
ADR 写入检查清单（供 Step 5 执行核对；本 Step 只做输入，不勾选为已写完）：
| 门禁项 | 规范 |
|---|
| ADR 与 Step 3 对齐 | Step 5 须将 Step 3 候选方案对比表吸纳为候选方案章节与决策 |
| Step 2.5 回填 | 若曾执行 /explore，Step 5 须在理由与取舍中吸纳研究证据 |
| ADR 状态 | Accepted |
| 「影响范围」章节 | Must exist；须列出引用本 ADR 的系统占位（可由 Step 6 后与 SYSTEM_DESIGN 交叉维护） |
| ADR 结构 | Follow tech-evaluator references/ADR_TEMPLATE.md 全章节（模板见下文规范摘要） |
ADR_TEMPLATE 章节不可删节（摘录为发射规范；正文撰写在 Step 5）：
| 章节 | 必须满足 |
|---|
| 状态 | Proposed | Accepted | Deprecated | Superseded … |
| 日期 | YYYY-MM-DD |
| 背景 | 问题、约束、干系期望 |
| 决策驱动因素 | 编号列表 |
| 候选方案 | 多方案利弊对照 |
| 决策 | 明确选定方案 |
| 后果 | 正/负/后续行动拆分 |
| 参考资料 | 可空但不得删除标题行 |
| 影响范围 | 列出将引用本报的系统 / 文档路径占位 |
CRITICAL：sequential-thinking
[!IMPORTANT]
必须在开始列举系统-ID 之前，使用 sequential-thinking：3–7 个 thought（复杂度低取 3，高耦合或多端取 7），覆盖拆分/合并备选、演进与物理边界；自然 CoT 不可顶替该 CLI 义务（无 CLI 时输出首段须声明 SEQUENTIAL_THINKING_BLOCKED，并降级为可追溯的条目化假设清单，禁止伪造 thought）。
严重度分级（Overview 自检 / 与人类检查点 #2）
| 等级 | 判定标准 | 所需行动 |
|---|
| Critical | Overview 与 PRD 覆盖范围矛盾；系统边界导致无法实现需求；遗漏 genesis 要求的物理根路径 / 必备图 | Step 5 以前必须修复 |
| High | 依赖环路；跨系统契约完全空白；拆分粒度过极端（单机式或碎片化）且无理由 | forge 前应修复或通过 ADR / 增补设计闭合 |
| Medium | 边界措辞含糊但可解码；单侧依赖偏多但可重构 | Step 或设计阶段清偿 |
| Low | 文档措辞、排序、格式 | 可持续改进 |
子代理编排
父代理（/genesis 宿主会话）：拥有 TARGET_DIR、写入 02_ARCHITECTURE_OVERVIEW.md 的最终版本、与人类检查点的呈现节奏、以及是否触发 Step 5 的最终路由。
子代理（若可用）：可接收切片「仅产出六维草稿 / 仅产出 Mermaid / 仅审计矩阵一致性」；不得独自定稿同名路径文件。
闭环交接清单（子代理交回父代理前自检）
顶级阶段：/genesis Step 4（含 Step 5 输入预备）
以下五阶段对应 Step 4 执行包；完成后父工作流进入 Step 5 ADR 发射（非本 skill 直接写入）。
阶段 A：输入与时间轴锚定
做什么：确认 TARGET_DIR；载入 01_PRD.md、concept_model.json（若存在）、Step 3 评估结论（内存或摘要）；摘录 [REQ-*]。
为什么：无对象拆解产生「架构散文」。
怎么验收：能列出 PRD 与 Step 3 中与部署/运行时相关的硬性约束不少于 3 条；Thought 序号已按计划执行。
阶段 B：六维系统识别（合成候选清单）
做什么：逐项扫 用户触点 / 数据存储 / 核心逻辑 / 外部集成 / 部署单元 / 技术栈，生成候选 system-id 草案。
为什么：穷尽维度降低漏系统风险。
怎么验收：六维皆有显式条目或标注 N/A 理由一行；草案数量落入 3–10 或可辩护的极少数例外。
阶段 C：边界、依赖与需求追溯
做什么：对每个系统写清 I/O 边界；建立 边界矩阵 + 依赖图；挂载关联需求 ID。
为什么：接缝是 ADR 与后续设计的着力点。
怎么验收：矩阵行数与清单一致；图上每条边在两系统条目中各出现一次且无环（若有环须在理由段解释接受条件）。
阶段 D：物理代码结构映射（/genesis Step 4 CRITICAL）
做什么：每个系统：源码根路径（如 src/packages/frontend）+ ASCII 目录树。
为什么：克隆与 IDE 导入依赖物理真相。
怎么验收：树中不出现「TBD-only」而无 [OPEN] 记录；路径与单体/多仓假设一致。
阶段 E：成文、02_* 落盘与 Step 5 就绪交接
做什么：按下方 输出格式模板填满 02_ARCHITECTURE_OVERVIEW.md；自检严重度表；为人类检查点 #2 准备一页执行摘要（可附文末 shortlist）。
为什么：ADR 必须与稳定系统边界对齐。
怎么验收：模板 §1–8 齐全；High 以上问题数显式归零或升格为 [OPEN] 并得到父代理接受；父代理已知下一步须跑 Step 5。
Step 5 输入就绪（宿主执行；本 skill 校对清单）
做什么：移交 系统-ID 全集、跨系统疑点、[OPEN]、Step 3 对比表指针。
为什么：ADR 必须引用真实边界与备选方案来历。
怎么验收：tech-evaluator ADR_TEMPLATE 可被无冲突填充；ADR「影响范围」可预填系统占位。
核心原则
[!IMPORTANT]
关注点分离：一系统一事；边界清晰：I/O 与数据契约显式；适度拆分：避免 >10 系统且无理由，禁止 无端单系统。
反模式：每功能一系统 / 巨石无界 / 跨层叠责 / 「前端后端混一栏不分」
正例：按技术栈、部署单元、职责边界、变更频率论证拆分或合并
系统识别框架：6 维度（执行扫表）
1. 用户触点
Web / Mobile / CLI / API Gateway…… → 通常映射独立 *-system。异栈或异部署触点 不得强行合并为一个 ID。
2. 数据存储
数据库、缓存、对象存储、搜索；可合并仅在 同一运维边界 + 共用访问模式 + 拆分无独立生命周期 时，并记入理由。
3. 核心业务逻辑
API、Agent、Pipeline、Batch；不同演进速率与 SLA 的常见拆点。
4. 外部集成
OAuth、支付、LLM；默认归入主导系统边界，仅在集成复杂度自持生命周期时升格独立系统-ID。
5. 部署单元
CDN 静态 / 容器服务 / Worker；一对一映系统候选最常见。
6. 技术栈
栈差异本身是强分解信号（例：React + FastAPI + PG → 至少三系统维度上的边界）。
输出格式：Architecture Overview 模板
使用以下结构产出 {TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md：
# 系统架构总览 (Architecture Overview)
**项目**: [Project Name]
**版本**: 1.0
**日期**: [YYYY-MM-DD]
---
## 1. 系统上下文 (System Context)
### 1.1 C4 Level 1 - 系统上下文图
[使用Mermaid绘制系统与用户、外部系统的交互]
\`\`\`mermaid
graph TD
User[用户] -->|HTTP| WebApp[Web应用]
WebApp -->|API| Backend[后端服务]
Backend -->|Query| DB[(数据库)]
Backend -->|Call| LLM[LLM API]
\`\`\`
### 1.2 关键用户 (Key Users)
- **终端用户**: 使用Web界面的用户
- **管理员**: 管理系统配置的用户
- ...
### 1.3 外部系统 (External Systems)
- **LLM API**: OpenAI / Anthropic
- **认证服务**: Auth0 / OAuth
- ...
---
## 2. 系统清单 (System Inventory)
### System 1: Frontend UX System
**系统ID**: `frontend-system`
**职责 (Responsibility)**:
- 用户界面展示与交互
- API调用封装
- 客户端状态管理
**边界 (Boundary)**:
- **输入**: 用户操作（点击、输入）
- **输出**: HTTP API请求
- **依赖**: backend-api-system
**关联需求**: [REQ-001] 用户登录, [REQ-002] Dashboard展示
**技术栈**:
- Framework: React 18
- Build Tool: Vite
- Styling: TailwindCSS
- State: Context API / Zustand
**源码根目录**: `src/packages/frontend`
**仓库内物理结构 (ASCII)**:
src/packages/frontend/
apps/
components/
...
**设计文档**: `04_SYSTEM_DESIGN/frontend-system.md` (待创建)
---
### System 2: Backend API System
**系统ID**: `backend-api-system`
**职责 (Responsibility)**:
- REST API服务
- 业务逻辑处理
- 数据库交互
**边界 (Boundary)**:
- **输入**: HTTP请求 (JSON)
- **输出**: HTTP响应 (JSON)
- **依赖**: database-system, agent-system
**关联需求**: [REQ-001] 用户登录, [REQ-003] 数据查询
**技术栈**:
- Framework: FastAPI
- Language: Python 3.11
- ORM: SQLAlchemy
- Auth: JWT
**源码根目录**: `src/backend/api`
**仓库内物理结构 (ASCII)**:
src/backend/api/
api/
services/
...
**设计文档**: `04_SYSTEM_DESIGN/backend-api-system.md` (待创建)
---
### System 3: Database System
**系统ID**: `database-system`
**职责 (Responsibility)**:
- 数据持久化
- 数据查询与索引
- 数据备份与恢复
**边界 (Boundary)**:
- **输入**: SQL查询
- **输出**: 查询结果
- **依赖**: 无（基础设施）
**关联需求**: 所有需要数据存储的需求
**技术栈**:
- Database: PostgreSQL 15
- Cache: Redis 7
- ORM: SQLAlchemy
**源码根目录**: `infra/db` 或 `[schema/migrations path]`
**仓库内物理结构 (ASCII)**:
db/migrations/
...
**设计文档**: `04_SYSTEM_DESIGN/database-system.md` (待创建)
---
[继续列出其他系统...]
---
## 3. 系统边界矩阵 (System Boundary Matrix)
| 系统 | 输入 | 输出 | 依赖系统 | 被依赖系统 | 关联需求 |
|------|------|------|---------|----------|---------|
| Frontend | 用户操作 | HTTP请求 | Backend API | - | [REQ-001], [REQ-002] |
| Backend API | HTTP请求 | JSON响应 | Database, Agent | Frontend | [REQ-001], [REQ-003] |
| Database | SQL查询 | 查询结果 | - | Backend API, Agent | All |
| Agent System | 任务请求 | 执行结果 | Database, LLM API | Backend API | [REQ-005] |
---
## 4. 系统依赖图 (System Dependency Graph)
\`\`\`mermaid
graph TD
Frontend[Frontend System] -->|API Call| Backend[Backend API System]
Backend -->|Query| DB[Database System]
Backend -->|Invoke| Agent[Agent System]
Agent -->|Query| DB
Agent -->|Call| LLM[LLM API - External]
style Frontend fill:#e1f5ff
style Backend fill:#fff4e1
style DB fill:#e1ffe1
style Agent fill:#ffe1f5
\`\`\`
**依赖关系说明**:
- Frontend依赖Backend（前后端分离架构）
- Backend是核心枢纽，协调Database和Agent
- Agent独立完成推理任务，但需要Database支持
---
## 5. 技术栈总览 (Technology Stack Overview)
| Layer | Technology | Used By |
|-------|-----------|---------|
| **Frontend** | React, Vite, TailwindCSS | Frontend System |
| **Backend** | Python, FastAPI, SQLAlchemy | Backend API System |
| **Database** | PostgreSQL, Redis | Database System |
| **Agent** | LangGraph, OpenAI | Agent System |
| **Infrastructure** | Docker, Kubernetes | All Systems |
---
## 6. 拆分原则与理由 (Decomposition Rationale)
### 为什么拆分为这些系统？
**技术栈维度**:
- Frontend (React) vs Backend (Python) → 技术栈完全不同，必须分离
**部署维度**:
- Frontend (静态部署CDN) vs Backend (容器部署) → 部署方式不同
**职责维度**:
- Backend API (业务逻辑) vs Agent (推理逻辑) → 职责独立，可并行开发
**变化频率**:
- Frontend (UI变化频繁) vs Database Schema (相对稳定) → 分离便于独立演进
### 为什么不进一步拆分？
**Frontend为什么不拆分为多个系统？**
- 虽然有多个页面，但共享状态和组件，拆分会增加复杂度
**Backend为什么不拆成微服务？**
- 当前规模不需要，Modular Monolith足够
- 可以通过模块化代码结构实现关注点分离
---
## 7. 系统复杂度评估 (Complexity Assessment)
**系统数量**: 4个系统
**评估**:
- 数量合理 (< 10)
- 边界清晰
- 依赖关系简单（无循环依赖）
**潜在风险**:
- Backend API可能成为瓶颈（协调多个系统）
- 未来可能需要拆分Backend（当代码量 > 50K行时）
---
## 8. 下一步行动 (Next Steps)
### 为每个系统设计详细文档
运行以下命令为每个系统创建设计文档：
\`\`\`bash
/design-system frontend-system
/design-system backend-api-system
/design-system database-system
/design-system agent-system
\`\`\`
### `/genesis` Step 5 提醒（宿主）
- 宿主应基于 Step **3 + 本文件**写入 `03_ADR/ADR_001_TECH_STACK.md` 及其他跨系统决策，结构遵循 `ADR_TEMPLATE.md`。
### `/blueprint` 前置（整体设计完成后）
\`\`\`bash
/blueprint
\`\`\`
拆解守则
守则1：不要过度拆分
规则：系统数量通常 < 10。拆分须带来独立部署价值、生命周期或技术栈差异之一。
守则2：不要过度聚合
规则：前端、后端、数据库通常为三套独立系统-ID（可有例外但必须 ADR 级论证）。
守则3：边界必须清晰
规则：每条目 输入 / 输出 / 序列化语义（至少到「JSON/Event/SQL」一级）可查。
守则4：使用 C4 + Mermaid 可视化
规则：上下文图 + 依赖图与矩阵一致。
RFC（references/rfc_template.md）结构契约 — 节选规范
仅在需要补足 API / 函数签名 / DDL 粒度时使用；章节骨架不得删。
| RFC 必选块 | 规范 |
|---|
| 高层设计 + Mermaid | 数据流与组件层级可追溯 |
| API 契约 / 函数接口 | 精确签名，禁止占位符冒充已定契约 |
| 数据模型策略 | DDL 变更或等价声明 |
| 实施步骤 | 原子、有序 |
| 安全与风险 | 认证、校验显式 |
全文模板见：.agents/skills/system-architect/references/rfc_template.md（若本地化 references/，须保持等价章节）。
工具箱
识别 Checklist：触点 / 存储 / 核心逻辑 / 外部集成 / 部署 / 栈 — 逐项勾。
落盘自检：上文 质量检查清单 + 严重度表。
常见场景摘要
| 场景 | 系统（典型计数） |
|---|
| Web 三件套 | Frontend + Backend API + DB（3） |
| + Agent | + Agent（4） |
| 企业扩展 | Web + Mobile + Backend + DB + Search + Worker（≤6–8） |
质量检查清单
系统数量
系统边界
依赖关系
- 无未解释环；Mermaid 可读出与矩阵等价信息；任一系统外向依赖不宜 > 5 而无缓解策略
文档完整性（Step 4）
- §1–8 按模板齐备
- Physical root + ASCII tree 每系统一笔
- 拆分理由对冲问题已答
CRITICAL：/genesis 集成提示（只读宿主条文摘要）
宿主 Step 6 会更新 AGENTS.md 与本 Overview 对齐；宿主 禁止在未完成 Step 5 时用 ADR 内容覆盖本节系统边界。Git 分支换轨仍以宿主 genesis.md 「Pre-Check」为准。
<completion_criteria>
- Architecture Overview 模板§1–8（含边界矩阵与技术栈两张主表）、拆解守则四章、严重度四章表、RFC 节选规范表 + ADR 发射分工 + ADR_TEMPLATE 章节表均以规范形态保留且无 emoji。
- CRITICAL 块齐备：方法论锚点、spec 产出契约、genesis 序位与 ADR/RFC 分工、sequential-thinking。
- 子代理编排与交接清单齐备；顶级 五阶段 Step 4 + Step 5 输入就绪 均含「做什么／为什么／怎么验收」。
- phase_context 已落地；文稿与约束口径一致（禁预读、单一路径）。
- 输出路径约定仍指向
{TARGET_DIR}/02_ARCHITECTURE_OVERVIEW.md。
</completion_criteria>
