@toyako/hive 1.0.0

package/docs/architecture-current.md

@@ -0,0 +1,301 @@
+# Agent Hive — Architecture Current
+
+> Generated: 2026-06-07
+> Version: 2.1.5
+> Status: STABLE
+
+---
+
+## 1. 当前模块图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        CLI (cli.ts)                             │
+│  init | detect | agents | task | run | history | graph | ...    │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+┌──────────────────────────▼──────────────────────────────────────┐
+│                      Broker (Broker.ts)                          │
+│  ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
+│  │ AgentRegistry│ │ MessageBus   │ │ TaskQueue                │ │
+│  │ (registry)   │ │ (events)     │ │ (persistence)            │ │
+│  └─────────────┘ └──────────────┘ └──────────────────────────┘ │
+│  ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
+│  │ MessageRouter│ │ TaskRouter   │ │ ConversationManager      │ │
+│  │ (v2 routing) │ │ (v1 compat)  │ │ (multi-turn)             │ │
+│  └─────────────┘ └──────────────┘ └──────────────────────────┘ │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+┌──────────────────────────▼──────────────────────────────────────┐
+│                     Graph Layer (graph/)                         │
+│  ┌─────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
+│  │ AgentGraph   │ │ GraphValidator│ │ TopologyTemplates       │ │
+│  │ (directed)   │ │ (cycles)      │ │ (5 presets)             │ │
+│  └─────────────┘ └──────────────┘ └──────────────────────────┘ │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+┌──────────────────────────▼──────────────────────────────────────┐
+│                   Runtime Layer (runtime/)                       │
+│  ┌───────────────────┐ ┌─────────────────┐ ┌────────────────┐  │
+│  │ CapabilityDiscovery│ │ RuntimeScoreMgr │ │ RuntimeSelector│  │
+│  │ (probe + static)   │ │ (stats)         │ │ (auto select)  │  │
+│  └───────────────────┘ └─────────────────┘ └────────────────┘  │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+┌──────────────────────────▼──────────────────────────────────────┐
+│                    Safety Layer (safety/)                        │
+│  ┌──────────────┐ ┌────────────┐ ┌──────────────┐ ┌──────────┐│
+│  │ CircuitBreaker│ │ HopCounter │ │ MsgDedup     │ │ TimeBudget││
+│  └──────────────┘ └────────────┘ └──────────────┘ └──────────┘│
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+┌──────────────────────────▼──────────────────────────────────────┐
+│                   Adapter Layer (adapters/)                      │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐          │
+│  │ Codex    │ │ Claude   │ │ Hermes   │ │ OpenClaw │          │
+│  │ (OpenAI  │ │ (CLI)    │ │ (CLI)    │ │ (stub)   │          │
+│  │  SDK)    │ │          │ │          │ │          │          │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────┘          │
+│  ┌──────────┐ ┌──────────┐                                     │
+│  │ MockCodex│ │ MockClaude│                                    │
+│  └──────────┘ └──────────┘                                     │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │
+┌──────────────────────────▼──────────────────────────────────────┐
+│                  Persistence (.agent-hive/)                      │
+│  tasks/ | messages/ | logs/ | history/ | conversations/         │
+│  agents.json | graph.json | runtime-capabilities.json           │
+│  runtime-stats.json                                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Runtime 生命周期
+
+```
+detect()          health()          execute()           review()
+   │                 │                  │                  │
+   ▼                 ▼                  ▼                  ▼
+检查CLI是否      发送probe prompt    执行任务            审核结果
+安装并可启动     验证Runtime可工作   返回AgentResult     返回ReviewResult
+   │                 │                  │                  │
+   ▼                 ▼                  ▼                  ▼
+installed=true   healthy=true       success/output      decision/score
+```
+
+**Adapter接口 (AgentAdapter):**
+```typescript
+interface AgentAdapter {
+  name: string;
+  role: AgentRole;            // planner | executor | reviewer | coordinator
+  capabilities: string[];     // static declaration
+
+  detect(): Promise<boolean>;           // CLI installed?
+  health(): Promise<boolean>;           // Can respond to prompt?
+  execute(task): Promise<AgentResult>;  // Do the work
+  review?(task): Promise<ReviewResult>; // Review the work
+  converse?(msgs): Promise<MessageEnvelope>; // Multi-turn
+}
+```
+
+**Runtime注册流程:**
+1. `broker.registerAdapter(adapter)` → 调用 `detect()` → 写入 `agents.json`
+2. `broker.healthCheck(name)` → 调用 `health()` → 更新 healthy 状态
+3. `capabilityDiscovery.discover(adapter)` → probe prompt → 写入 `runtime-capabilities.json`
+
+---
+
+## 3. Graph 生命周期
+
+```
+创建                    添加Agent              添加Edge
+   │                       │                      │
+   ▼                       ▼                      ▼
+new AgentGraph()    graph.addAgent()       graph.addEdge()
+   │                       │                      │
+   ▼                       ▼                      ▼
+加载持久化            写入 graph.json        写入 graph.json
+(如果存在)                 │                      │
+                           ▼                      ▼
+                    GraphValidator.validate()
+                           │
+                           ▼
+                    环检测 + 孤立Agent检测
+```
+
+**Edge类型 (EdgeRelation):**
+- `delegates` — A委派任务给B
+- `reviews` — A审核B的输出
+- `provides` — A向B提供上下文
+- `escalates` — A升级问题给B
+- `collaborates` — A与B协作
+- `approves` — A审批B
+
+**预置拓扑模板:**
+- `simpleChain` — Executor → Reviewer
+- `planExecuteReview` — Planner → Executor → Reviewer
+- `pipeline` — Stage1 → Stage2 → Stage3
+- `fanOutReview` — Executor → [R1, R2, R3]
+- `peerReview` — AgentA ↔ AgentB
+
+**v1.1迁移:**
+- `reportsTo` 自动转换为 `reviews` + `escalates` 边
+
+---
+
+## 4. Task 生命周期
+
+```
+submit()        queue.nextPending()     processTask()
+   │                    │                     │
+   ▼                    ▼                     ▼
+创建Task对象       从磁盘读取PENDING      XState状态机驱动
+写入tasks/             │                     │
+                       ▼                     ▼
+               ┌───────────────────────────────────────┐
+               │           XState Workflow              │
+               │                                        │
+               │  PENDING → EXECUTING → REVIEWING       │
+               │                      │                 │
+               │                    PASS → COMPLETED    │
+               │                    FAIL →              │
+               │                      │                 │
+               │              revisionCount < max?      │
+               │                YES → REVISION_REQUIRED │
+               │                      → EXECUTING       │
+               │                NO  → FAILED            │
+               │                      (or ESCALATED)    │
+               └───────────────────────────────────────┘
+```
+
+**Task数据结构:**
+```typescript
+interface Task {
+  id: string;
+  instruction: string;
+  executor: string;          // Runtime name
+  reviewer: string;          // Runtime name
+  status: TaskStatus;        // PENDING|EXECUTING|REVIEWING|...
+  revisionCount: number;
+  maxRevision: number;       // default: 3
+  timeout: number;           // default: 600000ms
+  workingDirectory: string;
+  result?: any;
+  conversationId?: string;   // v1.0
+  escalationPolicy?: ...;    // v1.0
+}
+```
+
+**持久化:** 每个状态变更立即写入 `.agent-hive/tasks/<id>.json`
+
+---
+
+## 5. Runtime 选择流程
+
+```
+Task提交
+   │
+   ▼
+指定 executor? ──是──→ 使用指定的 Runtime
+   │
+   否
+   │
+   ▼
+RuntimeSelector.select({ taskType })
+   │
+   ▼
+CapabilityDiscovery.findByCapability(taskType)
+   │
+   ▼
+过滤: healthy + 未排除
+   │
+   ▼
+评分:
+  score = 0.4 × capabilityMatch × confidence
+        + 0.25 × successRate
+        + 0.15 × latencyScore
+        + 0.2  × reviewScore
+   │
+   ▼
+选择最高分
+   │
+   ▼
+返回 SelectionResult { runtimeId, score, reason, alternatives }
+```
+
+**Capability Discovery 流程:**
+1. 读取 Adapter 静态 capabilities
+2. 发送 Probe Prompt: "List your capabilities as JSON"
+3. 合并 (union of static + probe)
+4. 写入 `runtime-capabilities.json`
+5. confidence: merged=0.9, static-only=0.3
+
+**Score 计算:**
+- successRate: 历史成功次数 / 总任务数
+- latencyScore: max(0, 1 - avgLatency/60000)
+- reviewScore: avgReviewScore / 100
+
+---
+
+## 6. 安全层
+
+| 组件 | 功能 | 默认值 |
+|------|------|--------|
+| HopCounter | 消息跳数限制 | maxHops=10 |
+| MessageDeduplicator | 消息指纹去重 | window=30s |
+| CircuitBreaker | 熔断器 | threshold=5, cooldown=60s |
+| TimeBudget | 时间预算 | configurable |
+
+---
+
+## 7. 数据流示例
+
+```
+用户: agent-hive task --instruction "实现API" --executor codex --reviewer claude
+
+  1. cli.ts → broker.submit() → TaskQueue.create() → tasks/<id>.json
+  2. cli.ts → broker.run() → TaskQueue.nextPending()
+  3. Broker → XState START → EXECUTING
+  4. Broker → CodexAdapter.execute(task) → AgentResult
+  5. Broker → XState EXEC_DONE → REVIEWING
+  6. Broker → ClaudeAdapter.review(task) → ReviewResult
+  7. Broker → RevisionHistory.add(record)
+  8. Broker → XState REVIEW_PASS → COMPLETED
+  9. Broker → TaskQueue.save(task) → tasks/<id>.json updated
+```
+
+---
+
+## 8. 文件清单
+
+| 模块 | 文件 | 行数 | 职责 |
+|------|------|------|------|
+| broker/ | Broker.ts | 737 | 核心编排 |
+| broker/ | AgentRegistry.ts | 74 | Agent注册 |
+| broker/ | MessageBus.ts | 92 | 事件总线 |
+| broker/ | TaskRouter.ts | 32 | v1.1路由 |
+| broker/ | MessageRouter.ts | 153 | v1.0路由 |
+| graph/ | AgentGraph.ts | 276 | 有向图 |
+| graph/ | GraphValidator.ts | 107 | 图验证 |
+| graph/ | TopologyTemplates.ts | 152 | 拓扑模板 |
+| conversation/ | ConversationManager.ts | 158 | 多轮对话 |
+| runtime/ | CapabilityDiscovery.ts | 130 | 能力发现 |
+| runtime/ | RuntimeScoreManager.ts | 125 | 性能统计 |
+| runtime/ | RuntimeSelector.ts | 110 | 自动选择 |
+| safety/ | CircuitBreaker.ts | 98 | 熔断器 |
+| safety/ | HopCounter.ts | 57 | 跳数限制 |
+| safety/ | MessageDeduplicator.ts | 69 | 消息去重 |
+| safety/ | TimeBudget.ts | 129 | 时间预算 |
+| review/ | ReviewConsensus.ts | 243 | 多审查者共识 |
+| adapters/ | CodexAdapter.ts | 108 | OpenAI SDK |
+| adapters/ | ClaudeAdapter.ts | 136 | CLI |
+| adapters/ | HermesAdapter.ts | 175 | CLI |
+| adapters/ | OpenClawAdapter.ts | 60 | STUB |
+| api/ | MeshAPI.ts | 147 | 编程接口 |
+| workflow/ | WorkflowMachine.ts | 246 | XState |
+| types/ | index.ts | 286 | 类型定义 |
+| commands/ | cli.ts | 463 | CLI入口 |
+| utils/ | (5 files) | 213 | 工具函数 |
+
+**总计:** 37个TypeScript文件, ~6100行

package/docs/architecture-review-v2.1.7.md

@@ -0,0 +1,402 @@
+# Agent Hive v1.0 Architecture Freeze Review
+
+> 2026-06-07
+> 基于实际代码分析，非猜测
+
+---
+
+## 1. 模块复杂度分析
+
+### 1.1 代码量
+
+| 模块 | 文件数 | 总行数 | 最大文件 | 最大行数 |
+|------|--------|--------|----------|----------|
+| broker/ | 5 | 1088 | Broker.ts | 737 |
+| adapters/ | 6 | 578 | HermesAdapter.ts | 151 |
+| commands/ | 11 | 2627 | test-v2-integration.ts | 615 |
+| graph/ | 3 | 535 | AgentGraph.ts | 276 |
+| benchmark/ | 4 | 561 | BenchmarkSuite.ts | 193 |
+| runtime/ | 3 | 389 | CapabilityDiscovery.ts | 139 |
+| observability/ | 4 | 394 | RuntimeMetrics.ts | 112 |
+| safety/ | 4 | 353 | TimeBudget.ts | 129 |
+| conversation/ | 1 | 158 | ConversationManager.ts | 158 |
+| review/ | 1 | 243 | ReviewConsensus.ts | 243 |
+| workflow/ | 1 | 246 | WorkflowMachine.ts | 246 |
+| types/ | 1 | 286 | index.ts | 286 |
+| utils/ | 5 | 213 | TaskQueue.ts | 80 |
+| api/ | 1 | 147 | MeshAPI.ts | 147 |
+| **总计** | **52** | **8520** | **Broker.ts** | **737** |
+
+### 1.2 模块依赖关系图
+
+```
+                        types/index.ts (286行)
+                              │
+              ┌───────────────┼───────────────┐
+              │               │               │
+         utils/*          safety/*        graph/*
+         (213行)          (353行)         (535行)
+              │               │               │
+              └───────┬───────┘               │
+                      │                       │
+              ┌───────▼───────┐               │
+              │  Broker.ts    │◄──────────────┘
+              │  (737行)      │◄── conversation/*
+              │  13个依赖      │◄── review/*
+              └───────┬───────┘◄── workflow/*
+                      │
+         ┌────────────┼────────────┐
+         │            │            │
+    adapters/*    runtime/*    observability/*
+    (578行)       (389行)      (394行)
+         │            │
+         └─────┬──────┘
+               │
+          benchmark/*
+          (561行)
+```
+
+### 1.3 God Object 分析
+
+**Broker.ts (737行) — 存在 God Object 风险**
+
+依赖了 13 个模块:
+- AgentRegistry, MessageBus, TaskRouter, MessageRouter
+- AgentGraph, ConversationManager
+- CircuitBreaker, HopCounter, MessageDeduplicator, TimeBudget
+- TaskQueue, Logger, RevisionHistory
+- WorkflowMachine
+
+职责:
+- 任务提交 + 队列管理
+- v1.1 兼容模式 (processTask)
+- v1.0 图模式 (processTaskGraph)
+- Agent 注册
+- 图迁移
+- 安全层初始化
+- 升级策略执行
+
+**判断: 是 God Object。** 但当前阶段可接受，因为 Broker 是唯一编排中心，这是架构设计决定。
+
+### 1.4 循环依赖
+
+**无循环依赖。** 依赖方向单一:
+- types ← 所有模块
+- utils ← 大部分模块
+- broker ← adapters, runtime, benchmark
+- 无反向依赖
+
+### 1.5 最容易失控的模块
+
+| 模块 | 风险 | 原因 |
+|------|------|------|
+| Broker.ts | 高 | 737行，13个依赖，两种模式(v1.1/v1.0)，持续增长 |
+| cli.ts | 中 | 464行，所有命令集中在一个文件 |
+| types/index.ts | 中 | 286行，所有类型集中，修改影响全局 |
+| test-v2-integration.ts | 低 | 615行测试文件，不影响生产 |
+
+---
+
+## 2. 扩展性分析
+
+### 2.1 新增 Runtime 需要修改的文件
+
+以 "接入 Gemini CLI" 为例:
+
+| 操作 | 文件 | 工作量 |
+|------|------|--------|
+| 新建 | `src/adapters/GeminiAdapter.ts` | ~100行 |
+| 修改 | `src/commands/cli.ts` | +3行 (import + register) |
+| **总计** | **2个文件** | **~103行** |
+
+不需要修改:
+- Broker.ts ✗
+- AgentGraph.ts ✗
+- MessageRouter.ts ✗
+- WorkflowMachine.ts ✗
+- types/index.ts ✗
+- 安全层 ✗
+
+### 2.2 Open/Closed Principle 评估
+
+**满足 OCP 的部分:**
+- Adapter 接口统一，新增 Runtime 不改 Broker
+- 安全层组件独立，可插拔
+- Benchmark Suite 可扩展
+- Observability 模块零依赖
+
+**不完全满足 OCP 的部分:**
+- cli.ts 硬编码了 adapter 列表 (需要改代码加新 adapter)
+- Broker.ts 的 processTask/processTaskGraph 是两种模式硬编码
+
+### 2.3 OCP 改进方案
+
+```typescript
+// 当前 (硬编码):
+const claude = new ClaudeAdapter();
+const hermes = new HermesAdapter();
+const codex = new CodexAdapter();
+await broker.registerAdapter(claude);
+await broker.registerAdapter(hermes);
+await broker.registerAdapter(codex);
+
+// 改进 (自动发现):
+// adapters/ 目录下自动扫描所有 *Adapter.ts
+// 或通过 runtime-registry.json 配置
+```
+
+---
+
+## 3. 架构债务分析
+
+### Debt List
+
+| ID | 类型 | 位置 | 描述 | 优先级 |
+|----|------|------|------|--------|
+| D1 | God Object | Broker.ts | 737行，两种模式混合 | P1 |
+| D2 | 硬编码 | cli.ts | adapter 列表硬编码 | P1 |
+| D3 | 临时方案 | CodexAdapter | 用 OpenAI SDK 代替 CLI，不是原始设计 | P2 |
+| D4 | 历史兼容 | Broker.ts | v1.1 processTask 和 v1.0 processTaskGraph 共存 | P2 |
+| D5 | 重复逻辑 | TaskRouter vs MessageRouter | 两个路由器功能重叠 | P2 |
+| D6 | 硬编码 | ClaudeAdapter | --model mimo-v2.5-pro 硬编码 | P2 |
+| D7 | 缺失 | OpenClawAdapter | STUB 未实现 | P3 |
+| D8 | 缺失 | converse() | 大部分 adapter 未实现多轮对话 | P3 |
+| D9 | 文件持久化 | 全局 | 所有数据用 JSON 文件，无数据库 | P3 |
+| D10 | 无日志框架 | 全局 | 用 console.log，无结构化日志 | P3 |
+
+### 优先级说明
+
+- **P0 (阻塞):** 无
+- **P1 (应尽快修复):** D1, D2 — 影响可维护性
+- **P2 (可接受):** D3, D4, D5, D6 — 不影响功能
+- **P3 (未来):** D7, D8, D9, D10 — v1.0 范畴
+
+---
+
+## 4. 生产化缺口分析
+
+### MVP 阶段 (可商用)
+
+| 缺失 | 重要性 | 说明 |
+|------|--------|------|
+| Web API | 必须 | 当前只有 CLI，需要 REST/WebSocket API |
+| 认证 | 必须 | 无用户系统，无 API Key 管理 |
+| 错误恢复 | 必须 | 部分异常场景未处理 |
+| 日志系统 | 必须 | console.log 不够 |
+| Docker | 必须 | 部署方式 |
+
+### Growth 阶段
+
+| 缺失 | 重要性 | 说明 |
+|------|--------|------|
+| Agent Registry UI | 重要 | 可视化管理 Agent |
+| Runtime Dashboard | 重要 | 监控面板 |
+| 分布式队列 | 重要 | 当前文件队列不支持并发 |
+| WebSocket | 重要 | 实时推送 |
+| Secret Vault | 重要 | API Key 加密管理 |
+
+### Enterprise 阶段
+
+| 缺失 | 重要性 | 说明 |
+|------|--------|------|
+| 权限系统 | 必须 | RBAC |
+| PostgreSQL | 必须 | 替代文件存储 |
+| Redis | 重要 | 缓存 + 队列 |
+| Kubernetes | 重要 | 容器编排 |
+| 审计日志 | 必须 | 合规要求 |
+| SSO/SAML | 重要 | 企业认证 |
+| SLA 保证 | 重要 | 可用性 |
+
+---
+
+## 5. 与主流 Agent Framework 对比
+
+### 5.1 LangGraph
+
+| 维度 | LangGraph | Agent Hive |
+|------|-----------|------------|
+| 语言 | Python | TypeScript |
+| 核心模型 | 状态图 (StateGraph) | 有向能力图 (AgentGraph) |
+| Runtime | LLM 直连 | CLI Runtime Adapter |
+| 多 Agent | ✓ (图状) | ✓ (图状) |
+| 持久化 | PostgreSQL/SQLite | 文件系统 |
+| 生态 | LangChain 生态 | 独立 |
+| 社区 | 10k+ GitHub | 无 (内部项目) |
+
+**Agent Hive 优势:**
+- Runtime 抽象层 (不绑定特定 LLM)
+- CLI Runtime 接入 (Codex/Claude/Hermes 独立进程)
+- Observability 内置
+- Benchmark 系统
+
+**Agent Hive 短板:**
+- 无社区生态
+- 无 Python SDK
+- 无 LangSmith 等工具链
+- 持久化简陋
+
+### 5.2 CrewAI
+
+| 维度 | CrewAI | Agent Hive |
+|------|--------|------------|
+| 核心模型 | Crew (角色+任务) | Graph (节点+边) |
+| Agent 定义 | 角色+目标+ backstory | AgentProfile+Runtime |
+| 任务编排 | 顺序/层级 | 图状+升级策略 |
+| 工具 | 内置工具库 | CLI Runtime |
+
+**Agent Hive 优势:**
+- 更灵活的图状编排
+- 安全层 (熔断器/跳数限制/去重)
+- 多审查者共识
+
+**Agent Hive 短板:**
+- 无内置工具
+- 无角色定义系统
+- 无记忆系统
+
+### 5.3 AutoGen
+
+| 维度 | AutoGen | Agent Hive |
+|------|---------|------------|
+| 核心模型 | 对话 (Conversation) | 图 (Graph) + 对话 |
+| 多 Agent | ✓ (群聊) | ✓ (图状) |
+| 代码执行 | ✓ (Docker) | ✓ (CLI Runtime) |
+| 人机协作 | ✓ (HumanAgent) | ✗ |
+
+**Agent Hive 优势:**
+- 结构化图状编排
+- Runtime 抽象
+- Benchmark + Intelligence
+
+**Agent Hive 短板:**
+- 无人机协作模式
+- 无群聊模式
+
+### 5.4 OpenHands
+
+| 维度 | OpenHands | Agent Hive |
+|------|-----------|------------|
+| 定位 | 软件开发 Agent | 多 Agent 编排平台 |
+| Runtime | 内置 LLM | 外部 CLI |
+| UI | Web UI | CLI only |
+| 代码执行 | 沙箱 | CLI Runtime |
+
+**Agent Hive 优势:**
+- 多 Runtime 协作
+- 不绑定特定 LLM
+- 图状编排
+
+**Agent Hive 短板:**
+- 无 Web UI
+- 无沙箱
+- 无内置代码执行
+
+### 5.5 核心能力对比总结
+
+| 能力 | LangGraph | CrewAI | AutoGen | OpenHands | Agent Hive |
+|------|-----------|--------|---------|-----------|------------|
+| 多 Agent 图状编排 | ✓ | ✗ | ✗ | ✗ | ✓ |
+| Runtime 抽象 | ✗ | ✗ | ✗ | ✗ | ✓ |
+| CLI Runtime 接入 | ✗ | ✗ | ✗ | ✗ | ✓ |
+| 安全层 | ✗ | ✗ | ✗ | ✗ | ✓ |
+| Benchmark | ✗ | ✗ | ✗ | ✗ | ✓ |
+| Observability | 部分 | ✗ | ✗ | ✗ | ✓ |
+| 社区生态 | ✓✓✓ | ✓✓ | ✓✓ | ✓ | ✗ |
+| Web UI | ✗ | ✗ | ✗ | ✓ | ✗ |
+| 持久化 | ✓✓✓ | ✓ | ✓ | ✓ | ✓ |
+| 工具生态 | ✓✓✓ | ✓✓ | ✓✓ | ✓✓ | ✗ |
+
+**Agent Hive 独特优势:**
+- Runtime 抽象层 (唯一支持多 CLI Runtime 协作)
+- 安全层 (熔断器/跳数/去重/时间预算)
+- Benchmark 系统 (基于真实能力数据选择 Runtime)
+- Observability 内置
+
+**必须补齐的核心能力:**
+- Web API (否则无法对外服务)
+- 持久化升级 (文件→数据库)
+- 工具生态 (否则能力有限)
+
+---
+
+## 6. 下一阶段路线图
+
+### v1.0 — Autonomous Mesh
+
+**目标:** Agent 自主协作，减少人工配置
+
+| 功能 | 投入 | 风险 | 收益 |
+|------|------|------|------|
+| 自动 Topology 推荐 | 2天 | 低 | 中 |
+| Agent 自我发现 | 1天 | 低 | 中 |
+| 任务自动分解 | 3天 | 中 | 高 |
+| 动态图重构 | 3天 | 高 | 高 |
+
+**总投入:** ~9天
+**风险:** 中 (动态图重构可能引入不稳定性)
+**收益:** 中高
+
+### v1.0 — Platform
+
+**目标:** 成为可部署的 Agent 编排平台
+
+| 功能 | 投入 | 风险 | 收益 |
+|------|------|------|------|
+| REST API | 3天 | 低 | 高 |
+| WebSocket | 2天 | 低 | 中 |
+| PostgreSQL | 2天 | 低 | 高 |
+| Docker | 1天 | 低 | 高 |
+| Secret Vault | 2天 | 中 | 中 |
+| Web UI | 5天 | 中 | 高 |
+
+**总投入:** ~15天
+**风险:** 低
+**收益:** 高
+
+### v4.0 — Enterprise
+
+**目标:** 企业级多租户 Agent 平台
+
+| 功能 | 投入 | 风险 | 收益 |
+|------|------|------|------|
+| 多租户 | 5天 | 高 | 高 |
+| RBAC | 3天 | 中 | 高 |
+| Kubernetes | 3天 | 中 | 中 |
+| 审计日志 | 2天 | 低 | 高 |
+| SSO/SAML | 3天 | 中 | 中 |
+| SLA 监控 | 2天 | 低 | 中 |
+
+**总投入:** ~18天
+**风险:** 中高
+**收益:** 高
+
+---
+
+## 7. 建议
+
+### 当前应该: A. 继续开发
+
+**理由:**
+
+1. **架构已稳定。** 40个模块，无循环依赖，扩展性良好。
+2. **债务可控。** P0=0，P1=2，大部分是 P2/P3。
+3. **独特价值已建立。** Runtime 抽象层 + 安全层 + Benchmark + Observability 是其他框架没有的。
+4. **但还没到"冻结"的程度。** Broker.ts 的 God Object 问题和 cli.ts 的硬编码应该在进入产品化之前修复。
+
+### 具体建议:
+
+**Phase 1 (1-2天): 修复 P1 债务**
+- D1: 拆分 Broker.ts (graph mode 独立)
+- D2: cli.ts adapter 自动发现
+
+**Phase 2 (3-5天): 真实项目验证**
+- 用 Agent Hive 完成一个真实任务 (如: 自动代码审查系统)
+- 验证架构在真实场景下的表现
+
+**Phase 3: 进入 v1.0 产品化**
+- REST API + Docker + PostgreSQL
+- Web UI
+
+**不建议现在做:**
+- v1.0 Autonomous Mesh (架构债务未清)
+- v4.0 Enterprise (太早)