三省六部军团管理 (Archive)

Archived original-language source from the legacy CrabClaw docs. This page is intentionally not machine-translated.

Crab Claw 的军团管理体系借鉴中国古代"三省六部"制度的治理智慧，构建了一套六层架构来管理子智能体的全生命周期。从蓝图定义到实例运行，从预算控制到熔断保护，每一层各司其职、协同运作。

六层架构总览

┌──────────────────────────────────────────────────────┐
│ L6: 治理层 — 三级指挥框架                                │
│   L1 意图识别 → L2 审批决策 → L3 合同约束                 │
├──────────────────────────────────────────────────────┤
│ L5: 军团管理 — 实例生命周期                               │
│   FleetManager · BudgetTracker · CircuitBreaker       │
│   StallDetector · AgentScheduler                      │
├──────────────────────────────────────────────────────┤
│ L4: 编排层 — 多智能体协作                                │
│   InterAgentBus · Supervisor · Pipeline · Swarm       │
├──────────────────────────────────────────────────────┤
│ L3: 实例化层 — 工厂流程                                  │
│   AgentFactory (7步) · ScopeCloner · ContractBuilder  │
├──────────────────────────────────────────────────────┤
│ L2: 蓝图层 — 模板定义                                    │
│   AgentBlueprint YAML · BlueprintStore · Validator    │
├──────────────────────────────────────────────────────┤
│ L1: 基座层 — 能力树与注册                                │
│   CapabilityTree · Registry · DelegationContract      │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│ L6: 治理层 — 三级指挥框架                                │
│   L1 意图识别 → L2 审批决策 → L3 合同约束                 │
├──────────────────────────────────────────────────────┤
│ L5: 军团管理 — 实例生命周期                               │
│   FleetManager · BudgetTracker · CircuitBreaker       │
│   StallDetector · AgentScheduler                      │
├──────────────────────────────────────────────────────┤
│ L4: 编排层 — 多智能体协作                                │
│   InterAgentBus · Supervisor · Pipeline · Swarm       │
├──────────────────────────────────────────────────────┤
│ L3: 实例化层 — 工厂流程                                  │
│   AgentFactory (7步) · ScopeCloner · ContractBuilder  │
├──────────────────────────────────────────────────────┤
│ L2: 蓝图层 — 模板定义                                    │
│   AgentBlueprint YAML · BlueprintStore · Validator    │
├──────────────────────────────────────────────────────┤
│ L1: 基座层 — 能力树与注册                                │
│   CapabilityTree · Registry · DelegationContract      │
└──────────────────────────────────────────────────────┘

L6: 治理层 — 三省（三级指挥）

治理层升级现有的三级指挥框架，为子智能体添加专属的意图识别、审批通道和合同约束：

L1 意图识别

当用户表达创建子智能体的意图时，intent_router 通过 blueprintCreationKeywords 关键词匹配，将消息分类为 task_write 层级，触发审批流程。

L2 审批决策

新增 ApprovalTypeBlueprintReview 审批类型。蓝图的创建、修改和激活操作通过 plan_confirm 审批通道，确保人类保持决策权。

L3 合同约束

DelegationContract 扩展 5 个新字段：

L5: 军团管理 — 六部（五大组件）

军团管理层是体系的核心中枢，包含五大组件：

FleetManager — 兵部（实例管理）

管理所有子智能体实例的完整生命周期：

创建 → 就绪 → 运行中 → 完成
                ↓         ↓
              卡死 ←→  失败
                ↓
              终止

创建 → 就绪 → 运行中 → 完成
                ↓         ↓
              卡死 ←→  失败
                ↓
              终止

• 6 种实例状态：created、ready、running、completed、failed、stalled
• RWMutex 并发安全：读操作不阻塞，写操作原子化
• API 方法：Register / Complete / Fail / MarkStalled / Terminate

BudgetTracker — 户部（预算管控）

三层预算体系，精确控制资源消耗：

• UTC 日零点自动重置每日额度
• 并发数控制：超限时新请求排队等待

CircuitBreaker — 刑部（熔断保护）

蓝图级别的熔断器，防止故障雪崩：

关闭（正常）──故障率达阈值──→ 打开（熔断）
    ↑                           │
    └──── 探测成功 ←── 半开（探测）←── 冷却期到

关闭（正常）──故障率达阈值──→ 打开（熔断）
    ↑                           │
    └──── 探测成功 ←── 半开（探测）←── 冷却期到

• 三种状态：closed（正常运行）→ open（拒绝新请求）→ half_open（允许少量探测）
• 冷却期机制：open 状态持续一段时间后自动转为 half_open
• 自动恢复：half_open 下探测成功 → 回到 closed

StallDetector — 御史台（卡死检测）

定期扫描运行中的实例，检测超时或无响应的智能体：

• ticker 扫描：按配置间隔轮询所有活跃实例
• 三级升级链：
  1. self — 尝试自行恢复（重试/重启）
  2. parent — 通知父智能体接管
  3. human — 升级到人类审批
• 复用 TTL 模式：与能力树 TTL 清理机制一致

AgentScheduler — 工部（调度触发）

三种触发模式驱动子智能体的自动执行：

• 通过 agentTurn Kind 让 cron 触发隔离智能体会话
• 会话中自动调用 spawn_agent 工具
• 零改动 cron 系统代码

L4: 编排层 — 协作模式

四种编排模式覆盖不同的多智能体协作场景：

InterAgentBus — 消息总线

智能体间通信的核心基础设施：

• 发布/订阅：多对多消息广播
• 直接通信：点对点消息传递
• 4 种过滤器：按来源、目标、类型、自定义条件筛选
• 环形缓冲：1000 条消息历史，溢出自动覆盖最旧条目

SupervisorOrchestrator — 监督者模式

一个监督者管理多个工作者：

• WorkerSpec：定义工作者能力标签和权重
• SelectWorker：按 tag 匹配 + 优先级选择最佳工作者
• Dispatch/Complete：任务分发与完成回调

PipelineOrchestrator — 流水线模式

多个智能体按顺序处理同一任务：

阶段 1 → 阶段 2 → 阶段 3 → 完成
 (收集)    (分析)    (报告)

阶段 1 → 阶段 2 → 阶段 3 → 完成
 (收集)    (分析)    (报告)

• 每阶段独立超时控制
• 上下文通过 ctx.Done() 传递取消信号
• 任一阶段失败则整体终止

SwarmOrchestrator — 蜂群模式

智能体自主决定将任务交接给谁：

• MaxHandoffs：循环保护，防止无限交接
• MaxConcurrent：并发控制
• TOCTOU 防护：原子化的交接检查与执行

RPC 接口

军团管理对外暴露 11 个 RPC 接口：

读操作

写操作

关键设计决策

升级而非新建

治理逻辑升级现有三级指挥框架（L1 Intent / L2 Approval / L3 Contract），而非新建 governance/ 包。代码量减少约 48%，零治理冲突风险。

接口解耦

runner 包通过 5 个接口访问 blueprint/factory/orchestration，避免循环依赖：

• BlueprintLoaderForAgent
• AgentFactoryForRunner
• InterAgentBusForAgent
• blueprintLister / blueprintSaver / blueprintDeleter

渐进式迁移

现有 spawn_coder/spawn_argus/spawn_media 保持原样，spawn_agent 作为独立并行路由。等价性测试 25 项全部 PASS。

测试覆盖

代码位置

相关文档：子智能体工厂 · 能力树与权限 · 系统架构