docs: reorganize MVP interview documentation

2026-07-05 15:29:28 +08:00
parent b22f2d22c8
commit 88e0a6c944
51 changed files with 4352 additions and 1318 deletions
@@ -0,0 +1,179 @@
+# Agent 架构演进路线
+
+**更新日期**：2026-07-05  
+**状态**：后续演进设计，不代表当前已实现  
+**参考历史文档**：`archive/2026-07-05-legacy/agent-architecture.md`
+
+## 1. 为什么需要演进路线
+
+旧版 `agent-architecture.md` 包含很多生产级设想：专科 SubAgent、Skill 体系、进程隔离、回退路由、MCP 工具协议化、进化引擎。它们不应作为当前 MVP 事实写入主架构，但可以作为后续扩展路线。
+
+当前原则：
+
+- 当前文档只声明已经可运行或明确落地的能力。
+- 演进路线记录未来方向和触发条件。
+- 每个演进项必须有可验证收益，不能只因为“架构更炫”就拆。
+
+## 2. 演进总图
+
+```mermaid
+flowchart TD
+    MVP["Current MVP: Planner + Executor + Verifier"] --> Split{"Executor 是否过载?"}
+    Split -->|是| SubAgents["专科 SubAgent"]
+    Split -->|否| Keep["继续强化通用 Executor"]
+
+    SubAgents --> Skills["Skill / Playbook 体系"]
+    Skills --> Fallback["回退路由"]
+    Fallback --> Isolation["进程或 Pod 隔离"]
+
+    MVP --> ToolGrowth{"工具数量和来源是否增长?"}
+    ToolGrowth -->|是| MCP["MCP / Tool Server 协议化"]
+    ToolGrowth -->|否| ToolCallbacks["继续使用 @Tool / ToolCallback"]
+
+    MVP --> EvalGrowth{"评测数据是否足够?"}
+    EvalGrowth -->|是| Evolution["Prompt / Skill 进化引擎"]
+    EvalGrowth -->|否| Baseline["先扩大 baseline"]
+```
+
+## 3. 专科 SubAgent
+
+### 触发条件
+
+- Executor prompt 变得臃肿，难以同时覆盖接口、数据库、缓存、网络等场景。
+- 不同故障类型需要明显不同的工具权限。
+- Trace 显示某些场景经常走错排查路径。
+- 评测集已经能衡量拆分前后的收益。
+
+### 候选 SubAgent
+
+| SubAgent | 场景 | 工具倾向 |
+|---|---|---|
+| `ExternalApiSubAgent` | 错误码、接口参数、第三方调用失败 | `lookup_knowledge`, logs, trace |
+| `DatabaseSubAgent` | 连接池、慢 SQL、死锁、数据库不可用 | metrics, logs, knowledge |
+| `CacheSubAgent` | Redis 超时、热点 key、内存风险 | metrics, logs, knowledge |
+| `GenericDiagnosisSubAgent` | 兜底诊断 | 全量只读证据工具 |
+
+### 不立即拆分的原因
+
+- 当前 MVP 的工具规模还可由通用 Executor 管理。
+- 过早拆分会增加 Prompt、评测和 trace 分析成本。
+- 没有足够分类评测前，拆分可能只是移动复杂度。
+
+## 4. Skill / Playbook 体系
+
+旧版设计中的 Skill 可以在当前项目中演进为可版本化的诊断 Playbook。
+
+```text
+fault_category
+  -> playbook
+      -> required evidence
+      -> tool sequence
+      -> stop condition
+      -> report template
+      -> evaluation checks
+```
+
+优先落地方向：
+
+- AIOps 告警处理 Playbook。
+- 支付超时 Playbook。
+- MySQL 连接池风险 Playbook。
+- Redis timeout Playbook。
+
+落地前提：
+
+- 每个 Playbook 至少有 3-5 个 eval case。
+- Playbook 失败时可以回退到通用 Executor。
+- Trace 中能标记使用了哪个 Playbook 和哪个版本。
+
+## 5. 回退路由
+
+当前 Chat 已有低置信补证据和 REJECT 降级输出。后续如果引入 SubAgent，可扩展为：
+
+```text
+Specialized SubAgent
+  -> failed / low confidence
+  -> another specialized SubAgent
+  -> GenericDiagnosisSubAgent
+  -> degraded answer with confirmed facts only
+```
+
+回退依据：
+
+- 工具连续失败。
+- Verifier `REJECT`。
+- Verifier `LOW_CONFID` 且补证据失败。
+- Agent 输出缺失关键报告字段。
+
+## 6. 进程隔离
+
+当前所有 Agent 在同一 JVM 内运行。生产级隔离可以考虑：
+
+```text
+API service
+  -> Supervisor service
+  -> Planner service
+  -> SubAgent services
+  -> Verifier service
+```
+
+触发条件：
+
+- 某类 Agent 需要独立扩缩容。
+- 某类工具依赖不稳定，可能拖垮主应用。
+- 不同 Agent 需要不同权限和网络访问策略。
+- 单 JVM 内资源隔离不足。
+
+MVP 阶段暂不拆分进程，优先保证 trace、评测和工具边界清晰。
+
+## 7. MCP / Tool Server 协议化
+
+当前工具主要通过 `@Tool`、`methodTools` 和 `ToolCallbackProvider` 暴露。工具数量增加后，可演进为：
+
+```text
+Agent
+  -> Tool registry
+  -> MCP / tool server
+      -> log server
+      -> metrics server
+      -> knowledge server
+      -> ticket/change server
+```
+
+收益：
+
+- 工具独立部署。
+- 新工具上线不必重发主应用。
+- 不同 Agent 可获得不同工具子集。
+- 工具调用协议统一，更利于审计。
+
+风险：
+
+- 调用链更长。
+- 权限和超时治理更复杂。
+- 本地开发和 Demo 成本上升。
+
+## 8. 进化引擎
+
+旧版文档提到从诊断中学习。当前可以拆成更务实的步骤：
+
+1. 先扩大 diagnosis eval 和 RAG eval。
+2. 从失败 trace 中标注 bad case。
+3. 将高频失败沉淀为 Playbook 或 Prompt 规则。
+4. 对 Prompt 版本做离线对比。
+5. 足够稳定后再考虑线上 A/B。
+
+不建议 MVP 直接做自动 Prompt 自优化。没有可靠评测和回滚机制时，自动优化更容易引入不可解释变化。
+
+## 9. 演进优先级
+
+| 优先级 | 项目 | 原因 |
+|---|---|---|
+| P0 | 扩大 eval baseline | 没有评测，拆任何架构都难以证明收益 |
+| P1 | Playbook 化高频故障 | 可控、可解释、比拆 SubAgent 更轻 |
+| P1 | 完整 evidence block | 提升 Verifier 和 Trace 质量 |
+| P2 | 专科 SubAgent | 等问题类型和工具权限差异足够明显 |
+| P2 | AIOps LLM Verifier | 规则门禁不足时再引入 |
+| P3 | MCP 工具协议化 | 工具来源复杂后再做 |
+| P3 | 进程隔离 | 生产负载和权限隔离需要明确后再做 |
+