双 Agent 自动联调 · 实施报告

配套《基于 CodeWhale 的双 Agent 自动联调可行性方案》
2026-06-25 | 已验证 ✓ 可行
📋 执行摘要

基于可行性方案的"协调器+共享消息总线"架构,在真实内网环境中完成了双 Agent 自动联调系统的完整部署与端到端验证。后端 Agent(本机 Linux)与前端 Agent(远程 Windows)均通过协调器成功完成真实任务下发、异步执行、结果轮回流。所有关键组件已就绪并经验证。

⚙️ 系统状态总览
组件位置状态说明
协调器中心本机 172.16.0.69✓ 就绪/root/coordinator,增强dispatch(提交+轮询)
后端 Agent本机 127.0.0.1:7878✓ 常驻deepseek-tui v0.8.18,auth=on
前端 Agent192.168.2.76:7878✓ 常驻Windows,deepseek-tui v0.8.64,auth=on
消息总线本机 /root/coordinator/conversation.txt✓ 就绪集中式(免共享存储)
真实结果回流dispatch() 轮询 GET /v1/tasks/{id}✓ 验证后端 5.8s / 前端 2.0s
🔍 1. 环境侦察与准备
🧩 2. 协调器本地部署与 dry-run 自检

部署目录:/root/coordinator/

文件职责
coordinator.py主程序(轮询/解析/路由/HTTP下发/原子写回/重试/心跳/优雅退出),Python 3.6 兼容
config.json全部可配置项(Agent URL/轮询间隔/API Key/路由表/dry_run/wait_result)
conversation.txt共享消息队列(轻量消息总线),协议:时间戳|发送者|接收者|动作|参数
state.json运行态(已处理字节偏移),自动生成
run.sh / stop.sh后台启停协调器(nohup + pidfile)
serve-start.sh / serve-stop.sh通用 Agent 服务启停(支持 HOST/PORT/TOKEN 环境变量)
check-agents.sh连通性+鉴权检查(读 config.json,对每个 Agent 检查 /v1/runtime/info 和 /v1/tasks)

dry-run 自检结果:

# 4 条消息: 正常路由 / 接收者过滤 / 未知action / 幂等
BUILD_BACKEND → backend (127.0.0.1) ✓ DRYRUN 写回
dev|frontend|SOMETHING → 忽略(receiver≠coordinator) ✓
UNKNOWN_ACTION → 写回 ERROR ✓
RUN_E2E → frontend ✓ DRYRUN 写回
processed 3 (非 coordinator 消息不计)
第二次 --once → processed 0 (无自循环) ✓
🖥️ 3. Agent 服务 (7878) 探测与常驻

关键发现:deepseek serve 需显式指定模式(--http / --mcp / --acp),否则报错:

Error: Choose exactly one server mode: --mcp, --http, or --acp

使用 deepseek serve --http 验证:

auth-token 探测(临时端口 7879,绑定 0.0.0.0):

无 token → 401
带 token → 200
经本机内网IP 172.16.0.69:7879 → 200(模拟外机路径)

生成统一鉴权令牌,启动本机后端 Agent(127.0.0.1:7878 + auth-token)。

🌐 4. 跨机器联调部署

4.1 拓扑

4.2 网络探测(172.16.0.69 → 192.168.2.76)

检查项结果解读
ip route getvia 172.16.0.1 dev ens33路由存在,走默认网关
ping0% packet loss / 0.66ms网络层通,延迟极低
TCP 7878(初次)超时 (curl rc=28)前端防火墙 DROP 或 serve 未启动/未绑 0.0.0.0
TCP 7878(修复后)TCP_CONNECT_OK前端放行 7878 + serve 绑 0.0.0.0

4.3 鉴权令牌不一致问题与修复

初次连通后,GET /v1/runtime/info → 200(该端点不校验 token,具迷惑性),但 GET /v1/tasks → 401(受保护路由),暴露了前端 serve 启动时使用的 auth-token 与协调器令牌不一致。

修复:前端用同一令牌重启 → /v1/tasks → 200。check-agents.sh 全绿:

[backend]  OK GET http://127.0.0.1:7878/v1/runtime/info -> 200
[backend]  OK GET http://127.0.0.1:7878/v1/tasks -> 200
[frontend] OK GET http://192.168.2.76:7878/v1/runtime/info -> 200
[frontend] OK GET http://192.168.2.76:7878/v1/tasks -> 200
RESULT: ALL OK
🧪 5. 真实端到端验证

5.1 真实 POST 探针(直接 curl 验证 /v1/tasks schema)

5.2 dispatch() 增强:提交 → 轮询 → 写回真实结果

基于探针发现,增强 dispatch():POST 拿 task_id → 轮询 GET /v1/tasks/{id} 至终态 → 写回真实 status/result_summary/duration。

新增配置:wait_result: true,result_poll_interval_sec: 2.0,result_timeout_sec: 300。

5.3 经协调器端到端真发验证

测试目标结果耗时
PROBE (dry-run)backend 127.0.0.1DRYRUN(逻辑路径正常)-
PROBE (真发)backend 127.0.0.1completed / summary=PROBE_OK5,762ms
PROBE_FE (真发)frontend 192.168.2.76completed / summary=PROBE_OK1,936ms

conversation.txt 真实写回证据:

1782381330|coordinator|dev|RESULT_PROBE|status=OK;detail=id=task_0a2de1cd status=completed dur_ms=5762 summary=PROBE_OK
1782381500|coordinator|dev|RESULT_PROBE_FE|status=OK;detail=id=task_aada50ac status=completed dur_ms=1936 summary=PROBE_OK
📖 6. 使用指南

文件总览

/root/coordinator/
├── coordinator.py        # 协调器主程序 (增强版, 提交+轮询)
├── config.json           # 配置文件
├── conversation.txt      # 消息队列 (干净态)
├── state.json            # 运行状态 (字节偏移)
├── run.sh / stop.sh      # 协调器启停
├── serve-start.sh        # 通用 Agent 启动脚本
├── serve-stop.sh         # Agent 停止脚本
├── check-agents.sh       # 连通性 + 鉴权检查
├── CROSS-MACHINE.md      # 跨机器部署详细说明
└── README.md             # 总览文档

常用命令

# 连通自检
cd /root/coordinator
./check-agents.sh

# 后端自检 (真发一条 PROBE, 轮询拿结果)
python3 coordinator.py --no-dry-run --send "x|coordinator|PROBE|" && python3 coordinator.py --no-dry-run --once

# 前端自检
python3 coordinator.py --no-dry-run --send "x|coordinator|PROBE_FE|" && python3 coordinator.py --no-dry-run --once

# 发联调消息 (任意动作)
python3 coordinator.py --send "dev|coordinator|BUILD_BACKEND|branch=main"
python3 coordinator.py --send "ops|coordinator|RUN_E2E|suite=smoke"

# 常驻真发模式
# config.json 改 dry_run=false → ./run.sh

# 远程写消息 (集中式)
ssh root@172.16.0.69 'cd /root/coordinator && python3 coordinator.py --send "dev|coordinator|RUN_E2E|suite=smoke"'

# 停止
./stop.sh          # 协调器
./serve-stop.sh    # Agent 服务
真实使用提醒
· routes 中 BUILD_BACKEND/RUN_E2E 等的 prompt 目前为通用占位,真实项目应改为针对实际工程的明确指令。
· 分发给 Agent 的任务默认 allow_shell:true, auto_approve:true(允许 Shell 且自动批准),联调 prompt 需谨慎编写。
· 前端机 Windows 路径 d:\agent_test 需确认远端已存在。