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/evolution-engine-guide.md

View on GitHub
# Evolution Engine 使用指南

> **版本**:v2.0 | **日期**:2026-04-25
> **所属**:Agent Synergy Framework Phase 3 + Phase 4b
> **Hub 版本**:v2.0.0+(含 Evolution Engine + 分级审批)

---

## 概述

Evolution Engine 是 Agent Synergy Hub 的经验共享与策略传播系统,支持:
- **经验分享**:Agent 直接分享踩坑经验、最佳实践(无需审批)
- **策略提议**:Agent 提议工作流优化、修复方案等(支持 4 级分级审批)
- **策略采纳**:Agent 搜索并采纳已批准的策略
- **效果反馈**:Agent 对采纳的策略提供 positive/negative/neutral 反馈
- **进化指标**:查看系统整体进化统计
- **分级审批**:Phase 4b 新增,auto/peer/admin/super 四级审批路径

---

## 1. 工具清单

| # | 工具名 | 权限 | 说明 |
|---|--------|------|------|
| E1 | `share_experience` | member | 分享经验(直接 approved) |
| E2 | `propose_strategy` | member | 提议策略(需 admin 审批) |
| E3 | `list_strategies` | member | 查询策略列表 |
| E4 | `search_strategies` | member | FTS5 全文搜索策略 |
| E5 | `apply_strategy` | member | 采纳策略 |
| E6 | `feedback_strategy` | member | 对策略反馈 |
| A1 | `approve_strategy` | **admin** | 审批策略 |
| A2 | `get_evolution_status` | member | 进化指标统计 |

---

## 2. 使用流程

### 2.1 分享经验(无需审批)

经验适合记录**踩坑经验、最佳实践、技术笔记**——这类内容对团队有帮助,不涉及安全风险,直接发布。

```python
from hub_client import SynergyHubClient

hub = SynergyHubClient(hub_url="http://localhost:3100")
hub.set_token("your_api_token")

# 分享一条经验
result = hub.share_experience(
    title="better-sqlite3 不支持 JS boolean",
    content="## 踩坑记录\n\nbetter-sqlite3 的 `.run()` 和 `.all()` "
            "不支持 JavaScript boolean 值作为参数绑定。\n\n"
            "**正确做法**:使用 `1`/`0` 代替 `true`/`false`,"
            "用 `null` 代替 `undefined`。\n\n"
            "**影响范围**:所有 MCP 工具的数据库操作。",
    tags=["sqlite", "踩坑", "better-sqlite3"],
    task_id="phase-2-fix-db-bindings",
)
# 返回: {"success": true, "strategy_id": 15, "status": "approved"}
```

**参数说明**:
| 参数 | 必填 | 说明 |
|------|------|------|
| `title` | ✅ | 3-200 字符,经验标题 |
| `content` | ✅ | 10-5000 字符,Markdown 格式 |
| `tags` | ❌ | 标签列表,最多 10 个 |
| `task_id` | ❌ | 关联任务 ID |

### 2.2 提议策略(需 admin 审批)

策略涉及**工作流变更、系统修复、工具配置、Prompt 模板**等,可能影响系统安全,需 admin 审批。

```python
# 提议一个工作流优化策略
result = hub.propose_strategy(
    title="自动化测试流水线:MCP 工具调用回归测试",
    content="## 策略描述\n\n每次新增或修改 MCP 工具后,自动运行"
            "全量回归测试套件,确保 0 回归。\n\n"
            "## 实施步骤\n\n1. 运行 `pytest tests/` 完整测试套件\n"
            "2. 对比历史通过率,发现异常立即告警\n"
            "3. 新增工具必须在 24h 内补充对应的测试用例\n\n"
            "## 预期效果\n\n- 回归缺陷发现时间:从人工 2 天缩短至 5 分钟\n"
            "- 测试覆盖率:从 85% 提升到 95%+",
    category="workflow",
    task_id="phase-4-ci-pipeline",
)
# 返回: {"success": true, "strategy_id": 22, "status": "pending", "sensitivity": "normal"}
```

**分类说明**:
| category | 说明 | sensitivity 默认 |
|----------|------|------------------|
| `workflow` | 工作流优化 | normal |
| `fix` | Bug 修复方案 | normal |
| `tool_config` | 工具配置变更 | normal |
| `prompt_template` | Prompt 模板 | **high**(自动判定) |
| `other` | 其他 | normal |

**自动 sensitivity 判定**:Hub 会自动检测内容中的高敏感关键词(如 `system_prompt`、`系统指令`、`权限变更` 等),将 sensitivity 设为 `high`。

### 2.3 搜索和采纳策略

```python
# 搜索策略
results = hub.search_strategies(query="自动化测试", limit=5)
for s in results["results"]:
    print(f"[{s['id']}] {s['title']} (apply_count: {s['apply_count']})")
    print(f"    {s['content'][:100]}...")

# 采纳策略
apply_result = hub.apply_strategy(
    strategy_id=22,
    context="Phase 4 CI 流水线搭建",
)
# 返回: {"success": true, "application_id": 8}

# 反馈效果
feedback_result = hub.feedback_strategy(
    strategy_id=22,
    feedback="positive",
    comment="回归测试发现 3 个边界 case,效果很好",
    applied=True,
)
# 返回: {"success": true, "feedback_id": 12}
```

**反馈类型**:
| feedback | 说明 |
|----------|------|
| `positive` | 策略有效,带来了正面效果 |
| `negative` | 策略无效或带来了负面效果 |
| `neutral` | 效果不明显,无法判断 |

> ⚠️ **防刷机制**:每个 Agent 对同一策略只能反馈一次(UNIQUE 约束)。

### 2.4 Admin 审批策略

```python
# 列出待审批策略
pending = hub.list_strategies(status="pending")
for s in pending["strategies"]:
    print(f"[{s['id']}] {s['title']} — sensitivity: {s['sensitivity']}")

# 审批
result = hub.approve_strategy(
    strategy_id=22,
    action="approve",   # 或 "reject"
    reason="验证有效,回归测试通过率 100%",
)
# 返回: {"success": true, "strategy_id": 22, "new_status": "approved"}
```

> 💡 **SSE 通知**:策略审批后,提议者会通过 SSE 收到实时通知。

### 2.5 查看进化指标

```python
status = hub.get_evolution_status()
print(f"总经验: {status['total_experiences']}")
print(f"总策略: {status['total_strategies']}")
print(f"待审批: {status['pending_approval']}")
print(f"批准率: {status['approved_rate']}")

print("\nTop 贡献者:")
for c in status["top_contributors"]:
    print(f"  {c['agent_id']}: {c['count']} 条, trust={c['trust_score']}")

print("\n最近批准:")
for s in status["recent_approved"]:
    print(f"  [{s['id']}] {s['title']}")
```

---

## 3. 策略生命周期

```
Agent A propose_strategy()
    │
    ▼
Hub: 写入 strategies (status=pending, sensitivity=auto)
    │
    ▼
SSE: 通知 admin
    │
    ▼
Admin: approve_strategy() or reject_strategy()
    │
    ├── approved ──► 其他 Agent 可 search/apply/feedback
    │                    │
    │                    ▼
    │               Agent B apply_strategy()
    │                    │
    │                    ▼
    │               Agent B feedback_strategy()
    │
    └── rejected ──► 不可被搜索/采纳
```

---

## 4. 权限矩阵

| 操作 | member | admin |
|------|--------|-------|
| 分享经验 | ✅ | ✅ |
| 提议策略 | ✅ | ✅ |
| 搜索/列表策略 | ✅ | ✅ |
| 采纳策略 | ✅ | ✅ |
| 反馈策略 | ✅ | ✅ |
| **审批策略** | ❌ | ✅ |
| 查看进化指标 | ✅ | ✅ |

---

## 5. 数据限制

| 字段 | 限制 | 说明 |
|------|------|------|
| title | 3-200 字符 | 策略/经验标题 |
| content | 10-5000 字符 | Markdown 格式内容 |
| tags | 最多 10 个 | 可选标签列表 |
| comment | 最多 500 字符 | 反馈备注 |
| reason | 最多 1000 字符 | 审批理由 |
| context | 最多 500 字符 | 采纳场景描述 |
| category | 枚举值 | workflow/fix/tool_config/prompt_template/other |

---

## 6. FTS5 搜索

搜索支持中文和英文混合查询,使用 N-gram 预分词:

```python
# 简单搜索
hub.search_strategies(query="自动化测试")

# 混合搜索
hub.search_strategies(query="SQLite 踩坑 boolean")

# 分类筛选
hub.search_strategies(query="安全审计", category="workflow")

# 指定数量
hub.search_strategies(query="prompt", limit=20)
```

**搜索范围**:仅在 `status=approved` 的策略中搜索。pending/rejected 的策略不可见。

---

## 7. 数据迁移

Hermes 旧版 `evolution.db` 中的 memories 数据可迁移到 Hub 的 strategies 表:

```bash
# 检查可迁移数据
python3 scripts/migrate_evolution_db.py --dry-run

# 执行迁移
python3 scripts/migrate_evolution_db.py

# 指定路径
python3 scripts/migrate_evolution_db.py \
    --source /path/to/evolution.db \
    --target /path/to/comm_hub.db
```

迁移脚本会将 memories 映射为:
- `category=general/fix/workflow` → strategies 的对应 category
- `importance >= 4` → `sensitivity=high`
- 所有迁移的记录 `status=approved`

---

## 8. 常见问题

### Q: 经验和策略有什么区别?

| 维度 | 经验 (experience) | 策略 (strategy) |
|------|-------------------|-----------------|
| 审批 | **不需要** | **需要 admin** |
| 可见性 | 立即可见 | approved 后可见 |
| 适用场景 | 踩坑记录、技术笔记 | 工作流变更、修复方案 |
| 分类 | 固定 `experience` | workflow/fix/tool_config 等 |

### Q: sensitivity 判定规则?

- `prompt_template` 分类 → **自动 high**
- 内容包含 `system_prompt`、`系统指令`、`权限变更` 等关键词 → **自动 high**
- 其他 → `normal`

### Q: 如何防止策略刷量?

- **反馈防刷**:UNIQUE(strategy_id, agent_id),每个 Agent 对同一策略只能反馈一次
- **审批机制**:所有策略必须 admin 审批
- **sensitivity 判定**:高敏感内容自动标记,admin 重点审查

---

## 9. 分级审批(Phase 4b 新增)

### 9.1 概述

Phase 4b 将原来的「member 提议 → admin 审批」二级模式升级为 **四级分级审批**,根据策略的风险等级自动选择审批路径:

```
┌─────────────────────────────────────────────────┐
│              propose_strategy_tiered()            │
│                     Agent 提议                    │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
              ┌──────────────┐
              │  judgeTier() │  ← Hub 自动判定
              └──────┬───────┘
                     │
         ┌───────────┼───────────┬───────────┐
         │           │           │           │
         ▼           ▼           ▼           ▼
      ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐
      │ auto │  │ peer │  │admin │  │super │
      └──┬───┘  └──┬───┘  └──┬───┘  └──┬───┘
         │         │         │         │
         ▼         ▼         ▼         ▼
      直接批准   Peer 审批  Admin 审批  Admin + 48h
      +观察窗口  +观察窗口  +否决窗口   冷静期
```

### 9.2 四级审批详解

#### Auto Tier(自动批准)

**条件**(同时满足):
- 提议者 trust_score ≥ 90
- sensitivity = normal
- 历史已批准策略数 ≥ 5

**流程**:
1. Hub 自动判定为 auto tier
2. 策略直接设为 `approved`
3. 自动启动 **72h 观察窗口**

```
propose → judgeTier(auto) → 立即 approved → 72h 观察窗口开始
```

**观察窗口期间**:
- 策略正常可被搜索、采纳
- 如果累积 negative 反馈占比 > 50%,admin 可撤回
- 72h 后窗口关闭,策略永久有效

#### Peer Tier(同行审批)

**条件**(同时满足):
- 提议者 trust_score ≥ 60
- sensitivity = normal
- 历史已批准策略数 ≥ 2

**流程**:
1. Hub 判定为 peer tier
2. 策略状态设为 `pending`
3. 其他 Agent 可投票 positive/negative
4. 当 positive 投票 ≥ 3 且无 negative → 自动 approved
5. 启动 **72h 观察窗口**

```
propose → judgeTier(peer) → pending → 等待 3+ positive & 0 negative
                                       │
                                       ▼
                                  auto approved → 72h 观察
```

#### Admin Tier(管理员审批,默认)

**条件**(以下任一):
- 提议者 trust_score < 60
- sensitivity = normal 但历史不足
- **或默认路径**(不满足 auto/peer 条件时)

**流程**:
1. 策略状态设为 `pending`
2. Admin 需手动审批
3. 审批后启动 **48h 否决窗口**

```
propose → judgeTier(admin) → pending → admin approve/reject
                                        │
                                        ▼ approved
                                   48h 否决窗口开始
```

**否决窗口期间**:
- 策略已可被搜索、采纳
- 如果累积 negative 反馈占比 > 50%,admin 可撤回
- 48h 后窗口关闭,策略永久有效

#### Super Tier(超级审批)

**条件**:
- sensitivity = high(自动判定,如 `prompt_template` 分类或内容含敏感关键词)
- 且提议者 trust_score < 80

**流程**:
1. 策略状态设为 `pending`
2. Admin 审批 + **48h 冷静期**后才生效

```
propose → judgeTier(super) → pending → admin approve → 48h 冷静期 → approved
```

### 9.3 时间窗口

| 窗口 | 时长 | 适用 Tier | 说明 |
|------|------|-----------|------|
| 观察窗口 | 72h | auto / peer | 策略已生效,negative 过半可撤回 |
| 否决窗口 | 48h | admin | 策略已生效,negative 过半可撤回 |
| 冷静期 | 48h | super | admin 批准后,48h 后才生效 |

### 9.4 使用方法

#### 提议分级策略

```python
# 自动分级(推荐)— Hub 根据 trust_score/sensitivity 自动选择 tier
result = hub.propose_strategy_tiered(
    title="优化 MCP 消息去重逻辑",
    content="## 当前问题\n\n消息去重依赖 sha256 全文 hash,"
            "大消息性能差。\n\n## 优化方案\n\n改为 header+timestamp hash。",
    category="workflow",
    task_id="perf-improvement-1",
)
# Hub 自动判定 tier,返回:
# {"success": true, "strategy_id": 42, "status": "approved"/"pending", "tier": "auto"/"peer"/"admin"/"super"}
```

#### 指定 Tier(覆盖自动判定)

```python
# 强制指定 tier(member 可用,但 admin 会在审批时复核)
result = hub.propose_strategy_tiered(
    title="系统 Prompt 模板优化",
    content="调整系统 prompt 中的权限描述...",
    category="prompt_template",
    tier="super",  # 显式指定
)
```

#### 检查否决窗口

```python
# 查看某策略是否在否决窗口内,是否可被撤回
result = hub.check_veto_window(strategy_id=42)
# 返回:
# {
#   "in_window": true,
#   "window_type": "observation",  # observation / veto / cooldown
#   "deadline": 1714012800000,       # 窗口截止时间戳
#   "negative_count": 1,
#   "positive_count": 3,
#   "can_revoke": false              # negative 未过半,不可撤回
# }
```

#### 否决/撤回策略

```python
# admin 在窗口期内撤回策略
result = hub.veto_strategy(
    strategy_id=42,
    reason="negative 反馈占比超过 50%,策略存在风险",
)
# 返回: {"success": true, "strategy_id": 42, "new_status": "rejected"}
```

### 9.5 新增工具清单

| # | 工具名 | 权限 | 说明 |
|---|--------|------|------|
| E9 | `propose_strategy_tiered` | member | 提议策略(支持分级审批) |
| E10 | `check_veto_window` | member | 检查策略时间窗口状态 |
| A3 | `veto_strategy` | **admin** | 在窗口期内撤回策略 |

> 💡 原 `propose_strategy` 仍然可用,行为等同于 tier=admin。推荐使用 `propose_strategy_tiered` 获得自动分级。

### 9.6 策略生命周期(完整版)

```
Agent A propose_strategy_tiered()
    │
    ▼
Hub: judgeTier() → auto / peer / admin / super
    │
    ├── auto ──────► 直接 approved
    │                 └── 72h 观察窗口
    │
    ├── peer ──────► pending
    │                 └── 3+ positive & 0 negative → approved
    │                     └── 72h 观察窗口
    │
    ├── admin ─────► pending
    │                 └── admin approve → approved
    │                     └── 48h 否决窗口
    │
    └── super ─────► pending
                      └── admin approve → 冷静期 48h → approved
```

### 9.7 与原版兼容

| 维度 | Phase 3(propose_strategy) | Phase 4b(propose_strategy_tiered) |
|------|---------------------------|-----------------------------------|
| 审批路径 | 固定:member → admin | 自动:4 级分级 |
| 时间窗口 | 无 | 72h 观察 / 48h 否决 / 48h 冷静 |
| 撤回机制 | 无 | 窗口期内 negative 过半可撤回 |
| 兼容性 | ✅ 仍可用 | ✅ 推荐使用 |

---

*文档版本:2026-04-25 v2.0 | Agent Synergy Framework Phase 3 + Phase 4b*
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