Skip to content

LeoYeAI/agent-master-skills / skills/agent-comm-hub

agent-comm-hub

Flagged

多智能体协同通信基础设施——基于 MCP+SSE 的实时消息、任务调度、记忆共享与进化引擎。支持 WorkBuddy、Hermes、QClaw 及任意 MCP 兼容 Agent 接入。53 个 MCP 工具、4 级权限、零外部依赖 Python SDK。触发词:agent通信、智能体通信、hub通信、多智能体、跨agent通信、任务调度、assign_task、send_message、hermes通信、workbuddy通信、agent hub、通信hub、mcp通信、记忆共享、进化引擎、策略共享、经验分享、共享记忆,共同进化

FileKindSize
.clawhub/origin.jsonconfig146 B
API_REFERENCE.mdmarkdown18.4 KB
HERMES-SETUP.mdmarkdown5.5 KB
README.mdmarkdown8.8 KB
SKILL.mdskill md16.4 KB
_meta.jsonconfig133 B
client-sdk/agent-client.d.tsscript11.6 KB
client-sdk/agent-client.jsscript28.6 KB
client-sdk/agent-client.tsscript29.8 KB
client-sdk/hermes-integration.d.tsscript785 B
client-sdk/hermes-integration.jsscript6.3 KB
client-sdk/hermes-integration.tsscript6.1 KB
client-sdk/hub_client.pyscript50.8 KB
client-sdk/workbuddy-integration.d.tsscript11 B
client-sdk/workbuddy-integration.jsscript4.3 KB
client-sdk/workbuddy-integration.tsscript4.2 KB
deploy/docker-compose.ymlconfig2.0 KB
deploy/grafana/dashboard.jsonconfig16.4 KB
deploy/grafana/provisioning/dashboards/dashboards.ymlconfig258 B
deploy/grafana/provisioning/datasources/prometheus.ymlconfig186 B
deploy/prometheus.ymlconfig408 B
docs/advanced-orchestration-guide.mdmarkdown11.8 KB
docs/evolution-engine-guide.mdmarkdown16.6 KB
docs/hermes-integration-guide.mdmarkdown22.3 KB
package-lock.jsonmanifest139.0 KB
package.jsonmanifest861 B
scripts/hub_task_runner.pyscript6.0 KB
scripts/hub_watcher.pyscript13.9 KB
scripts/install.shscript549 B
scripts/migrate_evolution_db.pyscript6.5 KB
scripts/migrate_from_agent.jsscript2.5 KB
scripts/wb_task_trigger.pyscript2.2 KB
src/db.d.tsscript3.7 KB
src/db.jsscript34.0 KB
src/db.tsscript37.4 KB
src/dedup.d.tsscript2.4 KB
src/dedup.jsscript8.5 KB
src/dedup.tsscript8.7 KB
src/errors.tsscript3.4 KB
src/evolution.d.tsscript6.6 KB
src/evolution.jsscript26.4 KB
src/evolution.tsscript31.0 KB
src/identity.d.tsscript3.4 KB
src/identity.jsscript15.9 KB
src/identity.tsscript17.1 KB
src/logger.d.tsscript1.1 KB
src/logger.jsscript2.8 KB
src/logger.tsscript3.5 KB
src/memory.d.tsscript2.1 KB
src/memory.jsscript13.0 KB
src/memory.tsscript14.3 KB
src/metrics.d.tsscript1.8 KB
src/metrics.jsscript8.4 KB
src/metrics.tsscript9.1 KB
src/orchestrator.d.tsscript6.1 KB
src/orchestrator.jsscript30.4 KB
src/orchestrator.tsscript33.4 KB
src/repo/interfaces.d.tsscript3.6 KB
src/repo/interfaces.jsscript49 B
src/repo/interfaces.tsscript4.2 KB
src/repo/sqlite-impl.d.tsscript225 B
src/repo/sqlite-impl.jsscript7.7 KB
src/repo/sqlite-impl.tsscript8.8 KB
src/repo/types.d.tsscript1021 B
src/repo/types.jsscript116 B
src/repo/types.tsscript1.6 KB
src/security.d.tsscript3.7 KB
src/security.jsscript15.0 KB
src/security.tsscript16.4 KB
src/server.d.tsscript11 B
src/server.jsscript24.7 KB
src/server.tsscript24.7 KB
src/sse.d.tsscript1.6 KB
src/sse.jsscript3.3 KB
src/sse.tsscript3.6 KB
src/stdio.d.tsscript11 B
src/stdio.jsscript1.7 KB
src/stdio.tsscript1.6 KB
src/tokenizer.d.tsscript1.3 KB
src/tokenizer.jsscript3.4 KB
src/tokenizer.tsscript3.2 KB
src/tools.d.tsscript474 B
src/tools.jsscript1.1 KB
src/tools.tsscript1.3 KB
src/tools/consumed.d.tsscript361 B
src/tools/consumed.jsscript5.5 KB
src/tools/consumed.tsscript5.3 KB
src/tools/evolution.d.tsscript660 B
src/tools/evolution.jsscript19.3 KB
src/tools/evolution.tsscript17.6 KB
src/tools/file.d.tsscript348 B
src/tools/file.jsscript7.1 KB
src/tools/file.tsscript6.5 KB
src/tools/identity.d.tsscript438 B
src/tools/identity.jsscript9.8 KB
src/tools/identity.tsscript9.3 KB
src/tools/memory.d.tsscript410 B
src/tools/memory.jsscript11.9 KB
src/tools/memory.tsscript10.8 KB
src/tools/message.d.tsscript467 B
src/tools/message.jsscript17.2 KB
src/tools/message.tsscript15.8 KB
src/tools/orchestrator.d.tsscript746 B
src/tools/orchestrator.jsscript27.8 KB
src/tools/orchestrator.tsscript24.3 KB
src/tools/security.d.tsscript386 B
src/tools/security.jsscript9.0 KB
src/tools/security.tsscript7.8 KB
src/types.tsscript5.9 KB
src/utils.d.tsscript421 B
src/utils.jsscript1.3 KB
src/utils.tsscript3.0 KB
tsconfig.jsonconfig337 B
vitest.config.tsscript1.2 KB

docs/advanced-orchestration-guide.md

View on GitHub
# 进阶编排使用指南

> **版本**:v1.0 | **日期**:2026-04-25
> **所属**:Agent Synergy Framework Phase 4b
> **Hub 版本**:v2.0.0+(含 Task Orchestrator 进阶能力)

---

## 概述

Phase 4b 在 Phase 4a 线性 Pipeline 基础上,引入了四种进阶编排能力:

| 能力 | 解决的问题 | 核心工具 |
|------|-----------|---------|
| **依赖链** | 任务有前后顺序(B 必须等 A 完成) | `add_dependency` / `remove_dependency` / `get_task_dependencies` |
| **并行组** | 多个任务可同时执行(A、B、C 互不依赖) | `create_parallel_group` |
| **质量门** | Pipeline 阶段检查点(代码 review 后才能继续) | `add_quality_gate` / `evaluate_quality_gate` |
| **交接协议** | 任务负责人变更(双向握手确认) | `request_handoff` / `accept_handoff` / `reject_handoff` |

---

## 1. 依赖链

### 1.1 概念

依赖链定义任务间的执行顺序。当任务 B 依赖任务 A 时:
- A 未完成 → B 处于 `waiting` 状态
- A 完成 → B 自动从 `waiting` 变为可执行
- 如果 A→B→C→A 形成环 → 自动拒绝(DFS 环检测)

### 1.2 依赖类型

| 类型 | 说明 | 触发时机 |
|------|------|---------|
| `finish_to_start` | 上游**完成后**下游可开始(默认) | 上游 status = completed |
| `start_to_start` | 上游**开始后**下游可开始 | 上游 status = in_progress |
| `finish_to_finish` | 上游**完成后**下游可完成 | 上游 status = completed |

### 1.3 使用示例

```json
// 1. 创建三个任务
{ "tool": "assign_task", "args": { "task_id": "design", "title": "UI设计", "assigned_to": "designer", "operator_id": "pm" } }
{ "tool": "assign_task", "args": { "task_id": "frontend", "title": "前端开发", "assigned_to": "dev1", "operator_id": "pm" } }
{ "tool": "assign_task", "args": { "task_id": "test", "title": "测试", "assigned_to": "qa", "operator_id": "pm" } }

// 2. 建立依赖:design → frontend → test
{ "tool": "add_dependency", "args": { "upstream_id": "design", "downstream_id": "frontend" } }
{ "tool": "add_dependency", "args": { "upstream_id": "frontend", "downstream_id": "test" } }

// 3. 此时 frontend 和 test 自动变为 waiting 状态
// 4. designer 完成 design → frontend 自动解除 waiting → dev1 可以开始
```

### 1.4 工具参数

#### add_dependency

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `upstream_id` | string | ✅ | 上游任务 ID(需先完成) |
| `downstream_id` | string | ✅ | 下游任务 ID(依赖上游完成后才能开始) |
| `dep_type` | enum | ❌ | 依赖类型,默认 `finish_to_start` |

**返回**:依赖创建结果 + 自动评估下游任务状态

**错误**:循环依赖 → `"Circular dependency detected"` / 任务不存在 → `"Task not found"`

#### get_task_dependencies

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `task_id` | string | ✅ | 要查询的任务 ID |

**返回**:

```json
{
  "task_id": "frontend",
  "upstreams": [
    { "task_id": "design", "status": "completed", "dep_type": "finish_to_start", "dep_status": "satisfied" }
  ],
  "downstreams": [
    { "task_id": "test", "status": "waiting", "dep_type": "finish_to_start", "dep_status": "pending" }
  ]
}
```

### 1.5 状态机扩展

```
原始状态机:
inbox → assigned → in_progress → completed
                     ↓            ↓
                  cancelled    failed

Phase 4b 扩展:
inbox → assigned → waiting → in_progress → completed
                     ↓          ↓            ↓
                  cancelled  cancelled    failed
```

`waiting` 状态:任务有未满足的上游依赖,自动进入。所有上游依赖满足后自动解除。

---

## 2. 并行组

### 2.1 概念

并行组标记一组可以同时执行的任务。同一 `parallel_group` 内的任务互不依赖,可由不同 Agent 并行处理。

### 2.2 使用示例

```json
// 1. 创建多个独立任务
{ "tool": "assign_task", "args": { "task_id": "api-dev", "title": "API开发", "assigned_to": "backend-dev" } }
{ "tool": "assign_task", "args": { "task_id": "ui-dev", "title": "UI开发", "assigned_to": "frontend-dev" } }
{ "tool": "assign_task", "args": { "task_id": "doc-dev", "title": "文档编写", "assigned_to": "tech-writer" } }

// 2. 标记为并行组
{ "tool": "create_parallel_group", "args": {
    "task_ids": ["api-dev", "ui-dev", "doc-dev"],
    "group_name": "v2-parallel-sprint"
}}

// 3. 三个任务可以同时执行
// 4. 查看并行组信息(通过 get_task_status 或直接查询)
```

### 2.3 工具参数

#### create_parallel_group

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `task_ids` | string[] | ✅ | 并行任务 ID 列表(2-10 个) |
| `group_name` | string | ❌ | 并行组名称(便于识别) |

**约束**:最少 2 个,最多 10 个任务

### 2.4 与依赖链组合

并行组常与依赖链组合使用,形成 DAG 工作流:

```
[design] ──完成──→ [并行组: api-dev + ui-dev + doc-dev] ──全部完成──→ [integration-test]
                  ↑                  ↑                     ↑
            互不依赖,可并行       三个都完成后           最后集成
```

---

## 3. 质量门

### 3.1 概念

质量门是 Pipeline 阶段的检查点。只有通过质量门后,后续任务才能继续。适用于代码 review、测试验收等场景。

### 3.2 使用示例

```json
// 1. 创建质量门(代码 review)
{ "tool": "add_quality_gate", "args": {
    "pipeline_id": "release-pipeline",
    "gate_name": "code_review",
    "criteria": "{\"type\":\"all_completed\",\"threshold\":1}",
    "after_order": 3
}}

// 2. 前面 3 个任务完成后,QA 评估质量门
{ "tool": "evaluate_quality_gate", "args": {
    "gate_id": "<gate-id>",
    "agent_id": "senior-dev",
    "passed": true,
    "result": "代码质量良好,无重大问题"
}}

// 3. 如果 passed=false,后续任务被阻塞
// 4. 修复后重新评估
```

### 3.3 工具参数

#### add_quality_gate

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `pipeline_id` | string | ✅ | Pipeline ID |
| `gate_name` | string | ✅ | 阶段名称(2-100 字符) |
| `criteria` | string | ✅ | JSON 判定条件 |
| `after_order` | number | ❌ | 在 order_index > 此值的任务开始前检查 |

**criteria 格式**:

```json
// 方式1:所有前置任务完成
{ "type": "all_completed" }

// 方式2:最低成功率
{ "type": "min_success_rate", "threshold": 0.8 }

// 方式3:自定义检查表达式
{ "type": "custom", "check_expr": "test_coverage > 0.9" }
```

#### evaluate_quality_gate

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `gate_id` | string | ✅ | 质量门 ID |
| `agent_id` | string | ✅ | 评估者 Agent ID |
| `passed` | boolean | ✅ | 是否通过 |
| `result` | string | ❌ | 评估结果说明 |

### 3.4 质量门状态

```
pending → passed / failed
```

- `pending`:等待评估
- `passed`:门已通过,后续任务可继续
- `failed`:门未通过,后续任务被阻塞(需修复后重新评估)

### 3.5 SSE 事件

| 事件 | 触发时机 | 推送目标 |
|------|---------|---------|
| `quality_gate_passed` | 门通过 | Pipeline 参与者 |
| `quality_gate_failed` | 门未通过 | Pipeline 参与者 + 管理员 |

---

## 4. 交接协议

### 4.1 概念

交接协议是任务负责人的变更流程,采用双向握手模式:

```
发起方(A)                    接收方(B)
   |                            |
   |-- request_handoff -------->|
   |                            |
   |<-- accept_handoff ---------|  或  |-- reject_handoff -------->|
   |                            |          (任务仍归 A)
   |-- assigned_to 更新为 B -->|
```

### 4.2 使用示例

```json
// 1. A 请求交接
{ "tool": "request_handoff", "args": {
    "task_id": "bugfix-123",
    "from": "dev-a",
    "to": "dev-b",
    "reason": "需要前端专家处理",
    "context": "已完成初步排查,CSS 兼容性问题,需要 Chrome 特定调试"
}}

// 2. B 接受(任务转移)
{ "tool": "accept_handoff", "args": {
    "task_id": "bugfix-123",
    "agent_id": "dev-b"
}}

// 或者 B 拒绝(任务仍归 A)
{ "tool": "reject_handoff", "args": {
    "task_id": "bugfix-123",
    "agent_id": "dev-b",
    "reason": "当前排期已满"
}}
```

### 4.3 工具参数

#### request_handoff

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `task_id` | string | ✅ | 要交接的任务 ID |
| `from` | string | ✅ | 当前负责人 Agent ID |
| `to` | string | ✅ | 目标接收人 Agent ID |
| `reason` | string | ❌ | 交接原因 |
| `context` | string | ❌ | 交接说明(进度、注意事项等) |

**约束**:
- 只有任务当前负责人才能发起交接
- 已终态(completed/failed/cancelled)的任务不能交接

#### accept_handoff / reject_handoff

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `task_id` | string | ✅ | 任务 ID |
| `agent_id` | string | ✅ | 操作者 Agent ID |
| `reason` | string | ❌ | 拒绝原因(仅 reject) |

### 4.4 SSE 事件

| 事件 | 触发时机 | 推送目标 |
|------|---------|---------|
| `handoff_requested` | 交接请求发出 | 接收方 |
| `handoff_accepted` | 接收方接受 | 原负责人 |
| `handoff_rejected` | 接收方拒绝 | 原负责人 |

### 4.5 交接状态

```
none → requested → accepted
                  → rejected → (可重新请求)
```

---

## 5. 组合工作流示例

一个完整的 DAG 工作流,组合依赖链 + 并行组 + 质量门 + 交接:

```
┌──────────────┐
│   需求分析    │  (PM)
└──────┬───────┘
       │ finish_to_start
       ▼
┌──────────────┐
│   架构设计    │  (Architect)
└──────┬───────┘
       │ finish_to_start
       ▼
┌──────────────┐
│  设计 Review  │ ← 质量门(code_review,必须通过)
└──────┬───────┘
       │ 门通过
       ▼
┌─────┴─────┐
│  并行组    │
│ ┌───────┐ │
│ │API开发 │ │  (Backend Dev)
│ ├───────┤ │
│ │前端开发│ │  (Frontend Dev)
│ ├───────┤ │
│ │文档编写│ │  (Tech Writer)
│ └───────┘ │
└─────┬─────┘
      │ 全部完成
      ▼
┌──────────────┐
│   集成测试    │  (QA)
└──────┬───────┘
       │ 测试通过
       ▼
┌──────────────┐
│  发布交接    │  (Dev → SRE) ← 交接协议
└──────────────┘
```

---

## 6. 数据模型

### task_dependencies 表

| 列 | 类型 | 说明 |
|------|------|------|
| id | TEXT PK | 依赖关系 ID |
| upstream_id | TEXT FK→tasks | 上游任务 |
| downstream_id | TEXT FK→tasks | 下游任务 |
| dep_type | TEXT | finish_to_start / start_to_start / finish_to_finish |
| status | TEXT | pending / satisfied / failed |
| created_at | INTEGER | 创建时间戳 |

**索引**:`idx_deps_downstream(downstream_id, status)`、`idx_deps_upstream(upstream_id, status)`

### quality_gates 表

| 列 | 类型 | 说明 |
|------|------|------|
| id | TEXT PK | 质量门 ID |
| pipeline_id | TEXT FK→pipelines | 所属 Pipeline |
| gate_name | TEXT | 阶段名称 |
| criteria | TEXT | JSON 判定条件 |
| after_order | INTEGER | 在此 order_index 后检查 |
| status | TEXT | pending / passed / failed |
| evaluator_id | TEXT | 评估者 |
| result | TEXT | 评估结果详情 |
| evaluated_at | INTEGER | 评估时间 |

---

*文档版本:v1.0 | 最后更新:2026-04-25*
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall