Agensh Agent运行时揭秘:Copilot ACP桥接、工具拒绝清单与关机归档校验
Agensh Agent运行时揭秘:Copilot ACP桥接、工具拒绝清单与关机归档校验
Agensh 是一个可扩展到 1,024 个 Agent 的自组织多智能体协作框架(Multiagent Harness)。在它的 Agent 运行时中,每个 worker 都运行着一个原生 Copilot ACP 会话:由 acp-bridge.py 通过 Unix socket 桥接模型进程、用工具拒绝清单精确收窄权限、并在关机时用归档校验保证工作成果一个字节都不丢。本文带你从零读懂这套运行时的三大核心机制。
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)。
它的工作流程可以概括为四步:
- 监听与握手:桥接进程绑定 socket 并只串行接受连接——新连接必须等上一个子进程清理完毕才能接管(acp-bridge.py),从源头避免并发踩踏;
- 双向转发:两个守护线程分别把 socket 上的 JSON-RPC 行转发给子进程、把子进程 stdout 转发回客户端,同时跟踪所有未完成的
session/prompt(acp-bridge.py); - 原生取消优先:连接断开时,桥接不会直接杀进程,而是先向仍在进行中的会话逐条发送
session/cancel,让 Copilot 有机会"体面地"收尾工具调用(acp-bridge.py); - 分级终止:先
SIGTERM再SIGKILL回收整个进程组;即使进程句柄丢失,还会扫描/proc清掉所有残留的 worker-UID 进程(acp-bridge.py)。
事件端的搭档是 mini-router 中的 acp_socket_channel.ts:它通过同一条 socket 下发 prompt、把 session ID 持久化到 MySQL 以便断线重连恢复会话,并内置"静默看门狗"——超过阈值没有任何 ACP 消息就强制断开重置,防止一轮对话卡死整个 worker。
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 用三步保证它真实且完整:
- 开机登记:
begin()在shutdown/下创建0o700私有目录并写入status=running的 manifest(archive.py); - 密封归档:
save()把 HOME 与/work完整打成state.tar.gz(保留符号链接,包含 Git 和被忽略文件),先 fsync 刷盘、再原子替换,最后才把status置为complete并记录文件大小与 SHA-256 摘要(archive.py);manifest 本身也是临时文件+原子替换+目录 fsync,防止半截 JSON; - 校验放行:
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%。
小结 🎯
- 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 技术报告阅读效果更佳。


