Agensh Agent运行时揭秘:Copilot ACP桥接、工具拒绝清单与关机归档校验

原创2026-10-31 11:16:181,342 阅读

Agensh Agent运行时揭秘:Copilot ACP桥接、工具拒绝清单与关机归档校验

Agensh 是一个可扩展到 1,024 个 Agent 的自组织多智能体协作框架(Multiagent Harness)。在它的 Agent 运行时中,每个 worker 都运行着一个原生 Copilot ACP 会话:由 acp-bridge.py 通过 Unix socket 桥接模型进程、用工具拒绝清单精确收窄权限、并在关机时用归档校验保证工作成果一个字节都不丢。本文带你从零读懂这套运行时的三大核心机制。

Agensh多Agent协作循环:领取子任务、执行、验证并异步合并进度

1️⃣ Agent 运行时长什么样?

agent/ 目录就是单个 Agent 的"运行时全家桶",每个文件各司其职:

文件 职责
Dockerfile 在任务镜像上安装私有 Node、锁定版本 1.0.70 的 Copilot 与 MCP 工具
entrypoint.sh 安装凭据、渲染提示词与 MCP 配置、检查 SQLite 锁、启动桥接
acp-bridge.py 监听 Unix socket,启动非 root 的 ACP 子进程并处理取消
archive.py 保存 HOME/工作区状态,并在清理前校验关机归档
config/ MCP 服务器模板与工具排除清单

几个关键设计:

  • 非 root 运行:根监督进程以 UID/GID 10000 启动 Copilot,持久化 HOME 位于 /opt/data/home,工作区是 /work;
  • 会话存储可锁:启动前会探测挂载卷能否支持 SQLite 的 fcntl 锁(entrypoint.sh),否则直接拒绝启动,避免 Agent 每条提示都报 database is locked;
  • 独立 Node 运行时:Node 装在 /opt/agentrt,与任务自带工具链互不干扰(Dockerfile)。

2️⃣ Copilot ACP 桥接:一条 socket,一次只服务一个连接

ACP(Agent Client Protocol)是 Copilot 对外暴露的标准化协议。Agensh 的 acp-bridge.py 做了一件很克制的事:把一条 Unix socket 连接串行地桥接到一个非 root 的 Copilot 进程(团队模式使用 /var/run/acp/agent.sock)。

它的工作流程可以概括为四步:

  1. 监听与握手:桥接进程绑定 socket 并只串行接受连接——新连接必须等上一个子进程清理完毕才能接管(acp-bridge.py),从源头避免并发踩踏;
  2. 双向转发:两个守护线程分别把 socket 上的 JSON-RPC 行转发给子进程、把子进程 stdout 转发回客户端,同时跟踪所有未完成的 session/prompt(acp-bridge.py);
  3. 原生取消优先:连接断开时,桥接不会直接杀进程,而是先向仍在进行中的会话逐条发送 session/cancel,让 Copilot 有机会"体面地"收尾工具调用(acp-bridge.py);
  4. 分级终止:先 SIGTERM 再 SIGKILL 回收整个进程组;即使进程句柄丢失,还会扫描 /proc 清掉所有残留的 worker-UID 进程(acp-bridge.py)。

事件端的搭档是 mini-router 中的 acp_socket_channel.ts:它通过同一条 socket 下发 prompt、把 session ID 持久化到 MySQL 以便断线重连恢复会话,并内置"静默看门狗"——超过阈值没有任何 ACP 消息就强制断开重置,防止一轮对话卡死整个 worker。

1,024个Agent通过Gitea、Mattermost和共享上下文协作的Agensh运行时演示

3️⃣ 工具拒绝清单:给 Agent 套上"精准缰绳"

多 Agent 协作最怕"某个 worker 手滑删了仓库、建了频道"。Agensh 的答案是一份显式的工具拒绝清单:copilot-deny-tools.json。

["gitea(create_repo)", "gitea(delete_branch)", "mattermost(delete_message)", ...]

清单条目采用 server(tool) 语法,覆盖两类"高危写操作":

  • Gitea 侧:建仓、fork、删分支、改文件、标签/发布管理等 30 多项;
  • Mattermost 侧:建频道、删消息、改消息、文件上传等 20 多项。

妙处在于双保险注入(entrypoint.sh):启动脚本读取清单后,对每一条规则同时生成 --deny-tool(权限层拒绝)和 --excluded-tools(模型层隐藏),再额外排除原生 task 与 list_agents。也就是说,模型不仅"调不到"这些工具,甚至"看不见"它们——既减少误调用,也省下了宝贵的提示词空间。若清单为空,启动会直接失败,杜绝"裸奔"上线。

配套的 mcp.json.tmpl 则以模板方式声明 gitea、mattermost、board 三个 stdio MCP 服务器,由入口脚本用 envsubst 渲染出每个 worker 专属的 /work/.mcp.json,所有工具结果再经过 mcp-notice-shim.cjs 附带私信与看板通知。

4️⃣ 关机归档校验:清理前的最后一道保险

六小时跑完一个任务,磁盘上的 state.tar.gz 是唯一的"成果存根"。archive.py 用三步保证它真实且完整:

  1. 开机登记:begin() 在 shutdown/ 下创建 0o700 私有目录并写入 status=running 的 manifest(archive.py);
  2. 密封归档:save() 把 HOME 与 /work 完整打成 state.tar.gz(保留符号链接,包含 Git 和被忽略文件),先 fsync 刷盘、再原子替换,最后才把 status 置为 complete 并记录文件大小与 SHA-256 摘要(archive.py);manifest 本身也是临时文件+原子替换+目录 fsync,防止半截 JSON;
  3. 校验放行:check() 遍历每个 worker 的每一次开机记录,逐一比对 status、符号链接、字节数与摘要;任何一次归档不完整都会阻断自动清理,数据被保留待人工恢复(archive.py)。

桥接进程的收尾逻辑与之呼应:收到 SIGTERM 后,它在 540 秒截止时间前等待所有连接线程结束,随后才执行最终归档(acp-bridge.py);而宿主侧脚本(如 launch_single_agent.py)只有在 archive.py check 通过后,才允许进入清理与导出阶段。

5️⃣ 为什么这套运行时值得看 👀

这套"桥接 + 清单 + 归档"的朴素工程,支撑的是论文中最亮眼的数据:在 ProgramBench 五大最难题上,Pandoc 任务的测试通过率从单 Agent 的 33.89% 提升到 1,024 Agent 的 55.06%;换用 GPT-6.1-sol 后,32 个 Agent 即达 79.59%。

Agensh Agent规模扩展实验:Pandoc任务最终测试通过率随Agent数量增长曲线

小结 🎯

  • ACP 桥接:一条 socket、串行服务、原生取消优先,让 1,024 个 Copilot 会话互不干扰(agent/acp-bridge.py);
  • 工具拒绝清单:权限层+模型层双重排除,把多 Agent 的"越权风险"关进笼子(agent/config/copilot-deny-tools.json);
  • 关机归档校验:密封、摘要、校验三连,让每次自动清理都有据可查(agent/archive.py)。

想动手复现整套团队实验,可参考 REPRODUCE.md 与启动脚本指南 scripts/README.md,配合 agensh.pdf 技术报告阅读效果更佳。

登录后查看全文
Agensh