circuit-breaker-manager
MCP依赖图与熔断器管理器v1.0,注册MCP依赖关系并拓扑排序,管理熔断器状态机(closed/open/half_open)与Bulkhead隔离舱,自动失败计数与恢复探测。触发:依赖注册/熔断检查/状态查询/熔断重置/级联故障分析/部署后验证
核心功能: 本技能提供/部署后验证、器v1等能力。
MCP依赖图与熔断器管理 v1.0 (ARCH-10)
注册MCP依赖关系并拓扑排序,管理熔断器状态机与Bulkhead隔离舱,自动失败计数与恢复探测。
使用场景
- 部署后注册MCP依赖关系,生成启动拓扑序 2. MCP调用失败时记录失败,触发熔断保护 3. MCP调用成功时记录成功,触发熔断恢复 4. 请求前检查熔断器是否放行 5. 手动重置熔断器(故障排查后) 6. 查询Bulkhead隔离舱并发状态 7. 级联故障分析(依赖图+熔断状态) 8. 健康检查与运维监控
核心概念
依赖图: MCP间的依赖关系有向图,Kahn算法拓扑排序,DFS检测循环依赖。依赖项需先启动。
熔断状态机: closed(正常) → open(熔断,拒绝请求) → half_open(探测) → closed/open。阈值5次失败,60秒恢复,半开最多1个探测请求。
Bulkhead隔离舱: 每MCP独立asyncio.Semaphore,最大并发10,排队等待30秒,防止故障MCP耗尽线程资源。
工作流
流程A: 注册MCP依赖关系
- 调用resilience-mcp的register_mcp_dependency(mcp_name, depends_on)
- 自动检测循环依赖,有环则回滚并返回CYCLE_DETECTED
- 返回拓扑排序结果(依赖项在前,被依赖项在后)
- 持久化到data/circuit_breaker/state.json
流程B: 调用前熔断检查(check_circuit)
- 调用前先check_circuit(mcp_name)
- 返回allowed=true → 放行请求; allowed=false → 拒绝并返回降级建议
- closed状态直接放行; open状态等待recovery_timeout后转half_open; half_open仅放行1个探测
流程C: 调用后记录结果
- 调用成功 → record_success(mcp_name),half_open状态下探测成功则恢复到closed
- 调用失败 → record_failure(mcp_name, error_type),连续5次失败触发熔断(open)
- 状态变更后自动持久化
流程D: 手动重置熔断器
- 故障排查后调用reset_circuit(mcp_name)
- 强制重置为closed状态,清空失败计数
- 记录操作日志
流程E: 隔离舱状态查询
- 调用get_bulkhead_status(mcp_name)
- 返回active_calls/queued_calls/total_rejected统计
- active_calls>=max_concurrent表示MCP过载
流程F: 依赖图与级联分析
- 调用get_dependency_graph获取完整图与拓扑序
- 结合get_circuit_state分析级联故障(被依赖MCP熔断→依赖方受影响)
- critical=true的MCP熔断需触发降级(记录待执行任务)
异常处理
| 异常 | 错误码 | 处理 |
|---|---|---|
| mcp_name为空 | INVALID_ARG | 返回错误,提示必填 |
| depends_on非列表 | INVALID_ARG | 返回错误,提示类型 |
| 检测到循环依赖 | CYCLE_DETECTED | 回滚注册,返回环路径 |
| MCP不可用 | MCP_UNAVAILABLE | 重启resilience-mcp |
| 状态持久化失败 | PERSIST_ERROR | 记录日志,内存状态仍有效 |
| 隔离舱排队超时 | QUEUE_TIMEOUT | 返回降级建议,统计rejected |
输入格式
{
"action": "register|graph|state|record_failure|record_success|check|reset|bulkhead|healthcheck",
"mcp_name": "content-publisher",
"depends_on": ["multi-publisher-mcp", "device-operations-mcp"],
"error_type": "timeout"
}
字段说明:
action: 操作类型(register注册/graph依赖图/state熔断状态/record_failure记录失败/record_success记录成功/check检查/reset重置/bulkhead隔离舱/healthcheck健康检查)mcp_name: MCP服务名(除graph/healthcheck外必填)depends_on: 依赖MCP列表(仅register使用)error_type: 错误类型(仅record_failure使用,如timeout/connection_error/http_5xx)
输出格式
{
"success": true,
"data": {
"name": "content-publisher",
"state": "closed",
"failure_count": 0,
"success_count": 25,
"failure_threshold": 5,
"recovery_timeout_sec": 60,
"half_open_max_calls": 1,
"last_failure_time": null,
"last_success_time": 1730908800.0,
"opened_at": null,
"last_error_type": null
},
"error": null,
"code": null
}
字段说明:
state: 熔断状态(closed正常/open熔断/half_open半开探测)failure_count: 连续失败次数(达failure_threshold触发熔断)success_count: 累计成功次数opened_at: 进入open状态的时间戳(null表示非open)last_error_type: 最近错误类型(用于故障分类)
示例
示例1: 注册依赖并获取拓扑序
- 调用register_mcp_dependency(mcp_name="content-publisher", depends_on=["multi-publisher-mcp","sensitive-word-mcp"])
- 返回:
{success:true, data:{registered:true, topo_order:["sensitive-word-mcp","multi-publisher-mcp","content-publisher"]}}
示例2: 熔断触发与恢复
- 对xianyu-agent-mcp连续调用record_failure 5次 → state变为open
- 调用check_circuit → allowed=false, 原因"open(剩余60s)"
- 等待60秒后调用check_circuit → allowed=true, 状态转为half_open
- 调用record_success → state恢复closed, failure_count=0
示例3: 循环依赖检测
- 调用register_mcp_dependency("A", ["B"]) → 成功
- 调用register_mcp_dependency("B", ["A"]) → 失败, code=CYCLE_DETECTED, error="检测到循环依赖: A -> B"
验证标准
| 验证项 | 标准 |
|---|---|
| 依赖图拓扑排序 | Kahn算法,无环时返回完整序 |
| 循环依赖检测 | DFS检测,有环时回滚并返回路径 |
| 熔断阈值 | failure_count>=5触发open |
| 恢复超时 | open后60秒转half_open |
| 探测限制 | half_open仅放行1个请求 |
| 探测成功恢复 | half_open+success → closed |
| 探测失败回退 | half_open+failure → open |
| Bulkhead并发 | 每MCP最大10并发,超限排队 |
| 排队超时 | 等待30秒未获槽位则拒绝 |
| 状态持久化 | 原子写入data/circuit_breaker/state.json |
变更历史
| 版本 | 日期 | 变更内容 |
|---|---|---|
| v1.0 | 2026-07-07 | ARCH-10初始版本:依赖图+熔断器+Bulkhead |
Related skills
- Downloads
- Security audit
- Pass
- Last updated
- 1mo ago
- Current version
- v1.0.2
- License
- MIT-0
