不用 SSH、不装数据库：我用 1 个 Python 脚本 + Git，把 15 个 AI Agent 串成了一条流水线-北京尧图网络

title: CSDN-hive-多机Agent协同任务总线不用 SSH、不装数据库我用 1 个 Python 脚本 Git把 15 个 AI Agent 串成了一条流水线发布摘要粘到 CSDN「摘要」框多台机器上的 AI Agent 并行改代码最难的从来不是让它们干活而是别抢同一张卡、别互相覆盖、干完还查得到。本文复盘蜂巢 Hive 的真实设计——用git push的非快进失败当分布式锁、lease_id fence 拦住旧 worker 复活、任务卡即 Git 文件、六列看板与「搁置」状态以及 133 张卡跑下来踩过的坑。零第三方依赖开源。写在前面这不是一篇「五分钟搭建多智能体框架」的爽文也不是概念科普。蜂巢 Hive 是我们每天真在用的工具跑了 133 张任务卡之后我觉得值得把为什么这么设计和哪些坑是真踩过的写下来。所有命令、状态、数字都来自实跑快照不是示意图。一句话矛盾跨 Windows / FreeBSD / macOS 的 15 个 AI Agent能力不一样、有的连 CLI 都没有怎么让它们并行改代码而不互相覆盖、不重复领活、干完还查得到一、起点聊天窗口管不住多台机器最开始的协同方式特别朴素我在对话框里写好一段需求贴给 A 机器的 agent跑完了它把结论贴回来我再贴给 B 机器。很快就有四个问题同时冒出来谁在干什么全靠我记。隔一小时回来分不清哪张卡在跑、哪张卡其实早死了。两个 agent 改同一片文件。各自都能提交合流时才炸而且炸完还得人工分辨谁的结果该留。旧进程会「复活」。一个卡在慢命令里的 worker租约被回收、卡被别人重新领走之后才醒过来最后把新人的结果 force push 覆盖了。结果散在各台机器的对话里。想复盘「这张卡为什么停在这儿」只剩一句「看板操作」。常见解法我都不太想用SSH 进 Windows 机器国产 GUI agent 很多压根没有 CLI、共享目录网络一抖就全乱、中央数据库或消息队列为了跑几个 agent 先运维一套中间件。后来想明白一件事每台机器上唯一肯定有、且天然支持原子操作的东西是 Git。于是整套设计收敛成一句话——一个 Python 脚本一个 Git 裸仓当协调仓用git push的非快进失败当分布式锁。不需要 SSH、不需要共享目录、不需要中央数据库。二、Hive 是什么以及不是什么hive.py 一个 Python 脚本标准库零第三方依赖协调仓git bare 只存任务卡、结果、租约、审计 dashboard/ 零依赖静态看板HTML 原生 JS 标准库 serve.py mcp_server.py MCP stdio server让 agent 自己来领活 hive_cluster.py 可选常驻集群秒级同步 SQLite store三个角色职责切得很硬角色只做三件事不做什么总控人或主控 agent写任务卡、分派、验收合流不替 worker 写代码worker每台机器一个拉取、原子领取、独立 worktree 干活、推回结果不自己合并 main看板只读全局少量带鉴权的运维写操作不调度、不做业务判断顺带澄清一个常被误会的点Hive 和「光明LightLang」中文编程语言没有关系。光明是独立项目早期只是拿它的代码仓当过登记示例。Hive 是自包含的工具没并入任何其它项目。三、核心机制把git push当分布式锁一张卡的一生大致是这样总控写卡 tasks/T-0101.md (state: ready) │ ▼ dispatch 按能力/负载/依赖挑卡 state: assigned ──► inbox/agent/T-0101.md │ ▼ worker 原子抢锁push refs/heads/claim/T-0101非快进即失败 claim/T-0101 分支 ← 只有一个 worker 能 push 成功 │ ▼ 独立 worktree 干活push task/T-0101 代码分支 res/T-0101 分支 ← 结果 JSONverify 全绿才 statusdone │ ▼ 人工 review 或总控 hive land 串行合流 state: done results/T-0101.json 归档claim/res 分支删除三套 ref 各管一件事这是整套设计里我最满意的部分ref内容生命周期claim/tid租约谁领的、lease_id、fence只在进行中存在close 时删res/tid结果verify 输出、耗时、head、summary合流后归档成results/tid.jsontask/tid代码分支交给 PR / land抢锁的原子性完全来自 Git 服务端两个 worker 同时 pushclaim/T-0101非快进的那个一定被拒不需要额外的锁服务。配合每人一个 worktreeagent 物理上就看不到对方没提交的改动。但只有锁是不够的fencing上面第 3 个坑旧 worker 复活是纯 Git 模型答不了的res/*用的是--force-with-lease本意是「同一张卡重跑能覆盖上一次」结果恰好也允许旧 worker 覆盖新 worker。补法是每次领取写两样东西lease_id这次领取的唯一编号写结果前必须对账fence单调递增序号每次回收 / 重派 1。旧 worker 醒来写结果时lease_id对不上直接拒就算它绕过校验硬推res.fence card.fence也会让land在合流前把这份过期结果认出来。锁决定「谁能干」fencing 决定「过期的结果不算数」两层缺一不可。再加两层才闭环层防的是什么paths互斥两张不同的卡改同一片文件 → dispatch 就不派下去粒度是路径不是整个仓land串行一次只合一张冲突显式暴露不静默覆盖四、任务卡长什么样一张卡就是一个带 frontmatter 的 Markdown 文件Git 就是数据库所以天然有历史、有 diff、能离线看---id:T-0101title:修复 CSV 导出在中文 Windows 下的编码repo:demobase:mainstate:readyowner:nullpriority:P1needs:[windows]# 能力标签没有对应 agent 的卡不该派出去paths:# 声明会动哪些文件防冲突的第一道闸-src/export/csv.py-tests/test_csv.pyverify:# 真跑的命令不是人肉勾选-python-m pytest-q tests/test_csv.pydepends_on:[]max_retries:3---复现步骤…… 判据导出的 CSV 用 Excel 打开不乱码。几个字段是踩坑踩出来的verify必须真跑过。曾经有一条验收命令自己写错了sys.exit却没import sys代码全对submit 判 failed。paths要写全。有次顺手改了 README 却没列进 paths被自己的越界检测抓回来重写。needs要确认有 agent 能满足。写过一张needs: windows的卡结果四个 agent 一个都没声明这个能力它就在 ready 里躺成了僵尸卡——现在draft lint会拦。有结果才算完成。早期close无条件写done于是「中途掐掉」和「真做完」在看板上长得一模一样。现在没res就记closed作废并把原状态、owner、失败原因一起写进卡面备注。五、五分钟跑起来以下命令都在工作目录执行比如~/dsworkhive 仓位于./hiveWindows 把路径分隔符换成反斜杠、解释器写python参数完全一样。# 1) 拿代码。推荐直接把工具仓推成自己的协调仓hive.py / docs / windows 都跟着走gitclone https://gitcode.com/skywalk163/hive.git hivegit-Chive remoteaddorigin你的协调仓地址git-Chive push-uorigin main# 2) 初始化补齐 tasks/ inbox/ results/ claims/ agents/ 等目录python3 hive/hive.py--dirhive init# 3) 登记一台机器agent 名全局唯一python3 hive/hive.py--dirhive agentadd--namewin-a--modemanual\--capabilitieswindows--repodemo本机代码仓路径# 4) 建一张卡python3 hive/hive.py--dirhive task new\--title修复 CSV 导出编码--repodemo\--pathssrc/export/csv.py\--verifypython -m pytest -q tests/test_csv.py# 5) 先看分派计划再落库python3 hive/hive.py--dirhive dispatch# 只看计划python3 hive/hive.py--dirhive dispatch--apply# 真分派# 6) 各台机器上起 worker--once 先跑一轮常驻用 --interval 30python3 hive/hive.py--dirhive work--agentwin-a--once# 7) 全局视图python3 hive/hive.py--dirhive status python3 hive/hive.py--dirhive doctor# 体检冲突/僵尸租约/land 滞后python3 hive/hive.py--dirhive stats--json# 成功率、耗时也可以从完全空的裸仓开始init --remote 地址会建目录并推第一版但那样就没有现成的windows/和docs/得自己拷。看板另起一个零依赖静态服务浏览器打开http://127.0.0.1:8787# 同样在工作目录里脚本会自己定位 hive 仓PORT8787INTERVAL20./hive/scripts/serve-dashboard.shworker 一定用setsid、tmux 或计划任务常驻我吃过亏随父 shell 回收日志静默停在半路六小时后才发现。六、看板一眼看到全局且不会骗你六列按单向互斥判定一张卡只出现在一列待领取 / 进行中 / 待合并 / 异常 / 最近完成 / 已关闭。租约过期在渲染时重新计算哪怕快照没刷新时间一到卡片自己变红落进异常列。有个细节我特别想安利响应头带快照时刻页面右下角显示「数据源/api/status快照 N 分钟前」超过 10 分钟加警示。起因是刷新循环曾经停摆/api/status依然返回 200页面安安静静渲染了一份 2 小时 43 分钟前的数据害我误判「退回没生效」。接口是活的不等于数据是新的——这种坑不显式摆出来就只能靠人肉发现。其它仓库 / owner / 优先级筛选、文本搜索、详情抽屉完整结果摘要每条 verify 的命令与退出码、深浅双主题、窄屏单列。看板写操作退回、重试、关闭、搁置默认只在回环绑定下免鉴权绑到内网必须配 token每次写操作落一条 append-only 审计日志。最新加的「搁置」给做不了的卡一个体面的去处有些卡当前确实做不了比如需要 macOS arm64 机器手边只有 x86_64。打回待领取会占位置、干扰 agent 领取一直挂在异常列又太显眼直接删更不行删了就真忘了。于是加了shelved不算挂账但不能忘。搁置时释放claim/res/status/分支、归档结果、收件箱信号和本机/集群租约推进 fence但卡面连同「为什么停、什么时候停、之前什么状态」全部留着连完整结果摘要都抄进卡面折叠块——因为释放res/分支会删掉那份结论而「不要忘记」不能只留 200 字。排版上没加第七列六列已经够挤搁置卡也不该和活跃卡平级。做成顶栏常驻的「搁置 N」一条默认收起的横条点开才显示卡片与三个出口放回待领取 / 另立新卡 / 废弃。它不进任何列、不计入活跃统计、doctor不报、不归档调度、worker、MCP 领取、land --all全跳过。复制按钮拿到的也不是「请领取任务」而是一段写明不要领取的搁置说明。七、让 agent 自己来领活MCP 跨机留言hive mcp是一个标准库实现的 stdio JSON-RPC server把任务总线暴露成 15 个工具agent 可以自助闭环hive_whoami → hive_next → hive_claim → 干活 → hive_submit └→ 干不下去 hive_abort / hive_block一个 server 进程一个 agent只能操作自己不能替别人领卡、提交、终止租约越权直接返回错误失败时还会给hint告诉你下一步。但这里有个很现实的约束我们登记的 15 个 agent 全是manual模式——国产 GUI agent小浣熊、Trae、CodeArts、WorkBuddy 之类很多没有 CLI没法自己起进程调 MCP。所以看板每张卡上有个「复制派发指令」按钮复制出来粘到 agent 对话框里。这是最土的办法也是跨机器、跨客户端最可靠的办法我们保留着没硬拗全自动。跨机沟通同样不走聊天软件看板右下角「留言」频道分大厅 /task:T-0231/agent:名字消息 1~2 秒同步到全网卡片和详情抽屉里都有「讨论 n」入口甩一条#chattask:T-0231的深链过去人点开就是那个线程。集群没起时降级到本机文件照样能发能看只是会明确提示「别的机器暂时看不到」。八、踩过的坑比特性更值得写现象根因后来的做法旧 worker 复活覆盖新结果res/*的 force push 认不出过期租约lease_id 单调fence写前对账、land 再验一次代码全对但判 failedverify 命令自己没import sys卡面入库前手动把每条 verify 真跑一遍卡在 ready 里永不派发needs写了没有 agent 声明的能力draft lint拦截写卡前hive agent listworker 日志静默停在半路没用setsid随父 shell 回收常驻启动脚本统一收口「完成」和「被掐掉」长得一样close无条件写done有res才done没有记closed并写现场看板显示几小时前的旧数据刷新循环停了但接口仍 200快照时刻响应头超 10 分钟警示重试卡反复被字段吞掉重写卡面时未登记字段被丢write_card保留自定义字段这些都不是理论上的「最佳实践」是半夜排障排出来的。它们现在都变成了代码里的守卫或卡面里的一个字段。九、跑到现在的数据一份真实的当前快照不是压测不是 benchmark项值任务卡133 张131 done / 2 shelved有结果归档129 张128 done / 1 failed登记的 agent15 个跨 Windows / FreeBSD / macOS涉及仓库4 个几个核心文件合计约 1.7 万行hive.py7.1k、hive_cluster.py3.9k、看板前端 2.6k 等不含文档与测试两套模式可以叠加纯 Git模式零依赖、单机也能跑常驻集群模式hived SQLite store面向更大规模目标 70 个并发 Agent × 7 张卡/天、可扩展到 100 节点选主和复制按 OSPF 的思路做Hello/Dead、term/vote、分区内多数Git 退回只写「建卡 / 结果归档 / 合并关闭」三个里程碑。一致性是分层的claim / lease / result走可复制的 op logprogress走可丢最后几秒的临时通道。明确不保证单节点分区最后几秒的进度、分区期间可能重复干活、Gitea 挂掉时 land 延后。写清楚比藏着强。十、有哪些「故意不做」不自动合并 main。合并留给人 review PR或总控用land一次一张串行做冲突显式暴露。一个 worker 串行跑。要并行就同机起多个 worker 多个 agent 名不做复杂的本地调度。不做自动扩缩容、不接 K8s。拓扑是运行态不是配置项1 台能起、100 台能加但成员靠发现不靠编排平台。看板不做拖拽改状态、不搞后端数据库。页面只读为主写操作走 CLI 并留审计。没有中央调度服务。没有那个单点也就没有那个单点要运维。适合谁已经有 Git、机器异构、agent 能力参差、需要「谁在干什么 / 为什么停」可追溯的团队。不适合谁单机单 agent、要毫秒级调度、或已经有成熟 CI/CD 编排体系的场景——那套比这个合适。结语回头看这套东西最值钱的不是代码量而是把「协同」这件事压回到了 Git 已有的语义里状态是文件、锁是 ref、结果是分支、审计是 commit。于是它天然能离线、能回溯、能用git log查半年前某张卡为什么被搁置也天然不需要我们再运维一个「协同系统」。开源部分永久免费直接用就行。真卡住了、或者要接进自己的多机产线可以写信聊helloquye.com。仓库https://gitcode.com/skywalk163/hive.git使用指南仓内docs/使用指南.md架构串讲docs/架构与排障全景.md如果只记一句别急着给多智能体协同上中间件先看看你手里的 Git 能不能当锁用。标签AI Agent多机协同GitPythonMCP分布式锁工程实践开源

不用 SSH、不装数据库：我用 1 个 Python 脚本 + Git，把 15 个 AI Agent 串成了一条流水线

相关推荐

Adam凭什么比SGD快？手写三组优化器，NumPy跑出10个数量级差距，ML数学基础第8期

为什么 Spring Boot 3 的虚拟线程没让接口变快：JDK 21 pinning 排查记录

【WSL】NodeJs安装

更多资讯

2KB SRAM Arduino多任务：SCoop协作式调度实战

研究生查文献总漏关键论文？我更建议用 NNScholar 接着做引文追踪

VMware安装CentOS 7全流程指南与优化技巧

Remix IDE与Polkadot Hub智能合约部署指南

纯电动车节能车速规划：时空建模与动态调整策略

数据清洗技术演进：从批处理到智能化的实践历程

今日更新

多智能体协作系统架构设计与实践优化

大模型系统性入门实战指南：从原理到部署微调的全链路路线

鸿蒙文件系统沙箱机制解析与开发实践

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？