日常开发中，一个完整任务往往涉及多个环节：理解需求、设计方案、写代码、跑测试、查日志。这些环节需要不同的专业能力和工具权限。单一 AI 助手要么权限过大（安全风险），要么能力面太广（每个方向都不够深）。
理解整个系统只需要抓住 5 个概念：
一个拥有特定身份、工具集和 LLM 后端的自治单元。每个 Agent 有自己的 system prompt 定义人设，有自己的工具白名单定义能力边界。
一件需要完成的具体工作。有明确的负责人（哪个 Agent）、输入（描述 + 上游产出物）、输出（结果 + 产出物）。多个 Task 通过依赖关系组成 DAG。
Task 完成后的交付物。比如 Ada 产出 design_doc，Leo 产出 code_diff，Ray 产出 test_report。上游的 Artifact 自动注入下游 Task 的上下文。
Agent 可以使用的能力。分为内置工具（读写文件、执行命令）和 MCP 工具（gitnexus、cooper 等外部服务）。工具白名单 = 权限边界。
由 Prompt 模板 + 工具子集 + I/O 契约组成的可复用工作流。比如"代码审查"skill 封装了 diff → 读文件 → 分析 → 输出报告的完整流程。Agent 激活 skill 后，按 skill 的专用 prompt 和工具集执行，产出结构化结果。
暂停执行、等待用户确认的检查点。出现在两个时机：执行前的方案确认、执行中的危险操作确认。确保人始终掌握最终决策权。
整个系统可以用一句话概括：用户只和 Max 对话，Max 把活拆给专人干，干完了汇总给你。
write_file 就不可能写文件，从架构上杜绝越权| Agent | 模型 | 理由 |
|---|---|---|
| Max | Sonnet | 调度逻辑不复杂，但需要稳定可靠 |
| Leo | Opus | 写代码是最复杂的任务，需要最强推理 |
| Ada | Opus | 架构设计需要深度分析和全局视野 |
| Ray | Sonnet | 写测试相对模式化，Sonnet 够用 |
| Sam | Haiku | 日志查询是结构化操作，不需要强推理 |
skills:
- name: code_review
description: "审查代码变更，输出结构化审查报告"
prompt: |
你是一个严格的代码审查者。检查以下变更：
- 逻辑正确性
- 边界条件
- 安全隐患（注入、未校验输入）
- 代码风格一致性
输出 JSON 格式的审查报告。
required_tools: [read_file, git_diff, search_code]
input:
- name: diff
type: string
description: "待审查的代码变更"
output:
type: review_report
fields: [issues, summary, verdict]
代价：多一层抽象，增加理解成本。write_file 工具（LLM 无法写任意文件），但 Max 的 Go 代码可以通过 Audit Logger 写日志。上游任务的产出物自动注入下游任务的上下文，形成信息链：
注：为简化图示，省略了 Ray（测试）环节。实际流程中 Leo 完成后会触发 Ray 测试，测试通过后再汇总。
安全设计围绕三道防线：
每个 Agent 只能调用配置中声明的工具。LLM 想调用未注册的工具会被 Runtime 直接拒绝。
工具本身还有细粒度控制：
即使 Agent 有权限，以下操作仍需用户确认：
只需要在 agents.yaml 中添加一段配置：
- name: doc # 名字
role: doc_writer # 角色
model: claude-sonnet-4-6
system_prompt: | # 人设
你是 Doc，一个技术文档工程师...
tools: # 工具白名单
- read_file
- write_file
constraints: # 约束
write_patterns: ["*.md"]
timeout: 120s
不需要改任何 Go 代码。框架自动根据配置创建 Agent 实例、注册工具、接入消息总线。
在 skills.yaml 中添加一段配置：
- name: bug_triage
description: "Bug 分诊：定位根因并输出修复建议"
prompt: |
分析以下 Bug 报告，结合代码和日志：
1. 复现路径
2. 根因定位
3. 修复建议（含代码片段）
输出结构化 JSON。
required_tools: [read_file, search_code, query_log]
input:
- name: bug_description
type: string
- name: error_log
type: string
optional: true
output:
type: triage_report
fields: [root_cause, fix_suggestion, severity]
timeout: 180s
框架自动完成：验证 Agent 是否具备所需 tool → 注入 skill prompt → 执行 → 校验输出结构。Agent 不满足 required_tools 时，该 skill 不可用。
Tool 接口（Name / Description / Parameters / Execute）只需在 Agent 配置的 mcp_servers 中添加 MCP Server 定义。框架自动启动进程、完成握手、发现工具。
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| Max 是单点瓶颈 所有通信经过 Max |
Max 响应慢时整个团队停摆 | Max 用 Sonnet（快+稳）；只做调度不做重活；未来可加副手 |
| LLM 幻觉导致错误操作 比如 Leo 写了错误代码 |
代码质量问题 | Ray 自动跑测试兜底；危险操作有审批门控；shell 命令白名单 |
| 上下文窗口溢出 复杂任务需要大量上下文 |
Agent 丢失关键信息 | Max 负责裁剪上下文——只传递 Artifact，不传递完整对话历史 |
| 任务拆解质量 Max 拆解不准确 |
后续执行方向偏差 | 方案确认环节由用户把关；Max 用结构化 prompt 引导输出 |
| 成本控制 多 Agent 意味着多次 LLM 调用 |
API 费用高于单 Agent | 审计日志记录 token 用量；Haiku 用于轻量任务；未来加缓存 |
| MCP Server 不稳定 外部进程崩溃 |
Agent 失去部分工具 | 自动重连 + 降级（移除不可用工具，继续执行） |
跑通核心链路：用户 → Max → Leo → 用户
交付标准：能对 Max 说"给 XX 加个功能"，Leo 自动写代码。
补齐团队成员、外部集成和 Skill 层