hive —— 多机 AI Agent 协同的任务总线:分布式,多节点同时运行,保障不会宕机

发布时间：2026/10/30 4:53:24
hive —— 多机 AI Agent 协同的任务总线:分布式,多节点同时运行,保障不会宕机

hive —— 多机 AI Agent 协同的任务总线

repo:https://github.com/skywalk163/hive

状态：活跃开发中，按任务卡迭代，变更记在CHANGELOG.md。
hive 是自包含的工具，没有并入任何其它项目。「光明（LightLang）」是一门独立的
中文编程语言，与本项目无关——只是早期拿它的代码仓当过登记示例。

第一次用？直接看 使用指南：人照着命令跑，AI 照着工具序列用。

一个 Python 脚本（hive.py）+ 一个 git 仓库，把「总控 AI 拆任务」和「多台机器上的 agent 干活」连起来。
MCP server 与 LLM 总控已拆成独立模块（mcp_server.py/llm_controller.py）。

  • 总控只做三件事：写任务卡、分派、验收。
  • worker自己拉取、原子领取、在独立 worktree 里干活、把结果推回。
  • 不需要SSH 进 Windows，不需要共享目录，不需要中央数据库。
  • 领取靠git push的原子性：两个 worker 抢同一张卡，只有一个 push 成功。
  • 自带dispatch（能力/负载/依赖感知）、doctor（体检）、stats（成功率/耗时）。

1. 协调仓库

推荐做法：把本工具仓直接推成skywalk/hive，这样hive.py、windows/、docs/
都跟着仓库走：

cd~/dswork/hivegitremoteaddorigin http://192.168.1.5:3000/skywalk/hive.gitgitpush-uorigin main

任意机器 clone 之后跑一次init补齐任务目录：

gitclone http://192.168.1.5:3000/skywalk/hive.git ~/hive python3 ~/hive/hive.py--dir~/hive init

也可以从空仓库开始（init --remote ...会建目录并推第一版），但那样就没有现成的
windows/和docs/，需要自己拷。

init会把hive.py（以及可选的hive_ports.py/hive_cluster.py/conflict.py/dispatch_prompt.py）
一起放进仓库，之后每台机器 clone 下来就能直接跑，不用另外装。

目录：

hive/ ├── hive.py # 工具本体（随仓库走） ├── hive_ports.py # 端口默认值的唯一来源（8787/8788/8789/8799） ├── hive_cluster.py # 常驻集群（可选：发现/注册/选主/实时进度） ├── tasks/T-*.md # 任务卡（总控写） ├── inbox/<agent>/ # 分派信号（总控写） ├── results/T-*.json # 结果（worker 写，在 res/<task> 分支） ├── claims/T-*.json # 租约（worker 写，在 claim/<task> 分支） └── agents/<agent>.json # 每台机器的配置

1.5 常驻集群（可选，但强烈建议）

建议每台跑 agent 的机器都起一个常驻集群进程：自动发现同网段的其他 hive、向主节点注册、
实时同步进度和租约；主节点退出后自动重选。不跑也能用，只是跨机信息要等 git push。
git 仍是唯一真相，集群只是把「等下一次 git push 才能看到进度」变成秒级。

python3 ~/hive/hive.py--dir~/hive cluster start# 后台常驻python3 ~/hive/hive.py--dir~/hive cluster status# 谁是主节点 / 谁在线python3 ~/hive/hive.py--dir~/hive cluster peers python3 ~/hive/hive.py--dir~/hive clusterwatch# 事件流python3 ~/hive/hive.py--dir~/hive clustersync# 本机代码同步状态
  • 默认 HTTP8788、UDP 发现8789；跨网段用--seed 192.168.1.5:8788。
  • 端口规划（看板 8787 / 集群 8788 / 发现 8789 / 冒烟 8799）集中在
    docs/端口与服务规划.md，代码默认值只在
    hive_ports.py定义一次；hive ports查看，hive ports --check体检。
  • 跨机建议设置同一个HIVE_CLUSTER_TOKEN。
  • hive work/hive orchestrate会自动拉起本机集群（HIVE_CLUSTER_AUTOSTART=0关闭）。
  • 新机器在同网段启动即可自动注册；主节点停掉后 1~8 秒内自动出新主。
  • verify-only / GUI 机器用cluster start --no-elect做 observer，只观察不参选。
  • P0 起进度默认不写 Git：HIVE_STATUS_GIT=auto只在里程碑且集群不可用时兜底；
    land 后各机按repo.updated自动ff-only同步主检出。
  • P1 起hive daemon默认带本机 MCP HTTP：127.0.0.1:8790，一个 agent 一个 token；
    hive agent enroll --name <agent>生成 token 和客户端配置。
  • P2a/P2b 可选 store 控制面：--store --claim-backend store（实验）；claim/lease、
    dispatch/assign、result accepted/archive 已接；hive store看本机状态，默认仍是 Git claim。
  • 细节、API、选主/任期/化身号/宽限期的取舍：见 docs/集群服务.md。

2. 登记机器

agent 配置里写清楚：这台机器能干什么、仓库在哪、用什么命令启动 agent。

# FreeBSD 主力机：dsh headless，prompt 从 stdin 进python3 ~/hive/hive.py--dir~/hive agentadd\--namefb88-dsh\--command"dsh --profile headless -"\--capabilitiesfreebsd python compiler pytest\--repohive=/home/skywalk/dswork/hive\--worktrees/home/skywalk/.hive/wt

Windows VM（没有 agent CLI 也能当验收机）：

python C:\hive\hive.py--dirC:\hive agent add--name win10--mode verify `--capabilities windows exe powershell `--repo hive=C:\hive--worktrees C:\hive-wt

三种模式：

模式配置行为
exec--command "..."调 agent，prompt 从 stdin 进，cwd 是 worktree
verify--mode verify不调 agent，只跑任务卡的verify，不产出代码分支
manual--manual备好 worktree，等人/GUI agent 干完写.hive/summary.md

exec的约定：任务提示词从 stdin 传入，进程的 cwd 就是任务 worktree。
dsh --profile headless -正好满足；Claude Code 用claude -p；Codex 用codex exec -。
国产 GUI agent 大多没有 CLI，用verify或manual（见 §6、§7）。

3. 建卡与分派（总控做的事）

python3 ~/hive/hive.py--dir~/hive task new\--title"修复 LLVM 后端 Windows 路径分隔符"\--repohive\--pathssrc/codegen/ tests/\--verify"python -m pytest -q tests/test_llvm_paths.py"\--dependsT-0100\--body-file /tmp/card.md# 手工指定python3 ~/hive/hive.py--dir~/hive assign T-0101--agentwin10# 自动分派：先看计划，再 --applypython3 ~/hive/hive.py--dir~/hive dispatch python3 ~/hive/hive.py--dir~/hive dispatch--apply--limit3

任务卡就是tasks/T-0101.md，可以直接改、可以 review、可以回滚。
dispatch只看ready、依赖已完成的卡，按needs/repo匹配 agent，按max_concurrency控负载。

4. worker

# FreeBSD：丢进 tmux，断线也不怕tmux new-shive-fb88-d"python3 ~/hive/hive.py --dir ~/hive work --agent fb88-dsh --interval 30"# Windows：计划任务 / 开机启动，登录后常驻python C:\hive\hive.py--dirC:\hive work--agentwin10--interval60

scripts/下有两个省事的壳：start-worker.sh <agent>（自动把OPENAI_API_KEY
映射成 dsh 要的DEEPSEEK_API_KEY，多 worker 用HIVE_DIR各自 clone）；
dispatch-loop.sh（总控侧每分钟dispatch --apply，自动分派循环）。

每轮：

  1. git fetch+reset --hard origin/main（协调仓库只读）；
  2. 扫inbox/win10/T-*.md，跳过已完成 / 被别人领走的；
  3. 推claim/T-xxxx分支抢锁，输了就下一张；
  4. 在代码仓库建独立 worktree（exec/manual用task/T-xxxx，verify用只读的verify/T-xxxx）；
  5. exec跑--command（stdin 喂任务卡）；manual等人；verify跳过；
  6. exec/manual提交、pushtask/T-xxxx；verify不产出代码分支；
  7. 跑--verify，写results/T-xxxx.json到res/T-xxxx分支。

日志在~/.hive/agents/<agent>/logs/，--keep可以保留 worktree 排查。

5. 看板与运维

python3 ~/hive/hive.py--dir~/hive status# ID STATE OWNER RESULT CLAIM TITLE# T-0101 assigned win10 done win10@10-22T23 修复 LLVM 后端…python3 ~/hive/hive.py--dir~/hive doctor# 任务卡/租约/结果/agent 配置体检python3 ~/hive/hive.py--dir~/hive stats# 成功率、中位耗时、按 agent/仓库python3 ~/hive/hive.py--dir~/hive land T-0101# 合入 dry-run（默认，不动东西）python3 ~/hive/hive.py--dir~/hive land T-0101--apply# 合入 main 并 closepython3 ~/hive/hive.py--dir~/hive land--all--apply# 把能合的都合掉python3 ~/hive/hive.py--dir~/hive result T-0101# 看摘要python3 ~/hive/hive.py--dir~/hive retry T-0101# 失败重跑（清结果+租约，续用原分支）python3 ~/hive/hive.py--dir~/hive retry T-0101--fresh# 从 main 重来python3 ~/hive/hive.py--dir~/hive gc--minutes180# 回收跑飞的租约python3 ~/hive/hive.py--dir~/hive prune# 清代码仓里已合并的 task/verify 分支（dry-run）python3 ~/hive/hive.py--dir~/hive close T-0101--note"已 land 合入"# 不跑 worker 的人工链路（GUI agent 场景，与该 agent 的 worker 二选一）python3 ~/hive/hive.py--dir~/hive take T-0101--agentworkbuddy python3 ~/hive/hive.py--dir~/hive submit T-0101

land是最后一步的自动化：在临时 worktree里真跑一遍 merge（不是靠merge-tree猜），
干净就推 main 并close，冲突就把文件清单列出来交给人/回给 owner 开新卡 —— 不自动解、不 force。
默认 dry-run，--apply才动；详见docs/操作手册.md§5.1。

close会把res/里的结果归档到main:results/T-0101.json，然后删掉claim/T-0101、res/T-0101
两个分支——Gitea 分支列表里只留正在跑的任务，审计记录仍在 main 上。
合并进代码仓main之后跑一次prune：它只删「已合并且不在飞」的task/*、verify/*
分支（在飞的卡哪怕内容已并入也保留），默认 dry-run，--apply才真删。

retry会把远端结果分支删掉；worker 下一轮发现「本地有完成标记但远端没结果」会自动重跑，不需要去每台机器清缓存。

6. verify 模式（Windows 验收机）

适合没有 agent CLI的机器：只跑验收，不改代码。任务卡里必须至少有一条verify。

agentadd--namewin10--modeverify--repohive=C:\hive...

要验证某个修复分支，把任务卡的base写成task/T-0101即可；worker 检出那条分支跑命令，
结果里带"mode": "verify"，不会产生新的代码分支。

Windows 专属 bug 的三卡闭环：诊断卡（win10/verify）→ 修复卡（fb88/exec）→ 验收卡（win10/verify, base=task/T-xxxx）。

7. GUI agent（小浣熊 / WorkBuddy / IDE 里的 agent）

这类 agent 没有稳定的命令行入口，用--manual：

# Windows 里的 dumate / Trae / CodeArts：直接打开工作区python C:\hive\hive.py--dirC:\hive agentadd--namewin10-gui--modemanual`--launch"trae {worktree}"`--repohive=C:\hive--worktreesC:\hive-wt

launch支持{worktree}、{task}、{prompt}；trae不在 PATH 就写完整路径，或用explorer {worktree}。
worker 把 worktree 和.hive/task.md准备好、把提示词放进 Windows 剪贴板、执行 launch，然后等 GUI agent 改完并写出.hive/summary.md。

GUI 卡的timeout_minutes统一写 180、lease_minutes写 240——实测小浣熊一张文档卡就要
65 分钟左右，默认 60 分钟会在它写完 summary 前超时；超时之后 GUI 才写完的恢复步骤
（补 commit/push + 补 summary +retry不带--fresh）见 chroot 文档。
压根不想在这个 agent 上跑 worker 的话，也可以走人工链路：take领取、submit提交（见 §5）。

chroot 里的小浣熊 / WorkBuddy 的完整接法（共享/home、manual worker、WorkBuddy root 权限坑）：
docs/CHROOT_GUI_AGENTS.md。适合：

  • 需要人盯着界面的操作（浏览器验证、IDE 重构）；
  • 小浣熊这种深链登录、沙箱受限的 Electron 客户端；
  • 暂时不想给 agent 配 API key 的机器。

小浣熊接 MCP 的现成配置（已在~/.box-agent/config/mcp.json验证可用，15 个工具）：

{"command":"python3","args":["/home/skywalk/dswork/hive/hive.py","mcp","--agent","raccoon"]}

接上后它就能自己查卡/领卡/交了，不用人喂；流程见
AGENT 快速上手。

8. 限制（有意为之，v0.3.0）

  • 一个 worker 串行跑任务；要并行就在同一台机器起多个 worker + 多个 agent 名（max_concurrency只影响 dispatch 的分配）。
  • dispatch的并发锁粒度是paths 不是 repo：同一个仓里改互不相干目录的卡可以同时派给不同 agent；
    paths 重叠（含父子目录）或没声明 paths 的卡才互相排队，上限--max-per-repo（默认 1）。
  • claim/res 是分支，只在进行中存在；close会归档结果并删分支。
  • 没有内置 PR 创建、没有自动合并到 main；合并留给人或总控用 git 做，close只做验收归档。
  • 看板是只读的；写操作（take/submit/close/retry）走 CLI。
  • 任务卡 frontmatter 只支持标量和标量列表，够用就好。
  • 自建裸仓建议关掉receive.autogc+gc.auto，夜间手动 gc；原因见docs/操作手册.md§8。
  • Windows 引导脚本只在 PowerShell 7 上验证过语法和 dry-run，没在真机跑过；国产 GUI agent 没有 CLI，走manual。

9. 自测

python3 selftest.py

会在临时目录里模拟「一个代码仓库 + 两个 worker 抢同一张卡」，断言只有一个领取成功、只产出一个结果；还覆盖 verify-only 模式、跨卡验收（base=task/T-xxxx）、失败上报、retry/gc。

10. 看板

cd~/dswork/hivePORT=8787INTERVAL=20./scripts/serve-dashboard.sh# 浏览器打开 http://127.0.0.1:8787

远程看：ssh -L 8787:127.0.0.1:8787 skywalk@192.168.0.88，浏览器开http://127.0.0.1:8787。

端口只有一个来源：HIVE_DASHBOARD_PORT（默认8787），PORT是历史兼容的覆盖项。
服务化入口scripts/dashboard-service.sh start|stop|status、hive dash、各平台自启安装器
用的都是这个默认值；任何hive命令也会顺手探活并拉起看板（HIVE_DASH_AUTOSTART=0可关）。
全部端口（看板/集群/发现/测试/预留段）见
docs/端口与服务规划.md，现场用hive ports --check查占用。
页面右上角会显示「快照 N 分钟前」——刷新循环停摆时，数据不会静默停在旧快照上。

五列看板（待领取 / 进行中 / 待合并 / 异常 / 已关闭），租约过期实时变红，
支持仓库/owner/搜索筛选、详情抽屉、深浅色。零依赖静态页，serve.py只用标准库。
看板只读，写操作走 CLI（take/submit/close/retry）。
说明见 dashboard/README.md，实跑验收见
dashboard/VERIFICATION.md。

11. MCP：让 agent 自己来领活

hive mcp起一个 MCP stdio server，把任务总线暴露成 15 个工具。接上之后 agent
不用等人喂卡，自助闭环：查任务 → 领卡 → 干活 → 提交 → 干不下去还回去。

python3 ~/hive/hive.py--dir~/hive mcp--agentworkbuddy

客户端配置：

{"mcpServers":{"hive-workbuddy":{"command":"python3","args":["/home/skywalk/hive/hive.py","mcp","--agent","workbuddy","--dir","/home/skywalk/hive"]}}}

--dir必须写在mcp后面。写在前面会被顶层的同名参数吃掉、子命令取不到而静默回退
到默认 clone（~/.hive/clones/mcp-<agent>），不报错。不确定就看启动那行 stderr 的dir=。
也可以干脆不传--dir，用默认独占 clone（推荐）。

工具作用
hive_whoami/hive_list_tasks/hive_get_task我是谁、有哪些卡、某张卡的全文
hive_next推荐一张现在就能干的卡（跳过能力不匹配/依赖未就绪/已被领走）
hive_claim领取：指派给我 + 抢 claim 租约 + 备好 worktree 和提示词
hive_submit提交：commit + pushtask/<id>+ 跑 verify + 写结果
hive_abort/hive_extend_lease/hive_progress放弃还卡 / 续租 / 中途记进度
hive_block/hive_unblock条件没到先冻卡 / 解冻
hive_result/hive_stats/hive_doctor查结果 / 吞吐统计 / 体检

零第三方依赖（标准库实现的 stdio JSON-RPC 2.0）；一个 server 进程 = 一个 agent，
只能操作自己：不能替别人领卡、提交、终止租约，越权调用直接返回错误。
返回沿用 LightMem 的{status, message, details}信封，失败时hint告诉你下一步。
详见 MCP 接入。

12. 更多文档

  • 使用指南：从单机到多机、从 Git claim 到 P2 store，人和 AI 都能照着做
  • AGENT 快速上手：第一次接 hive 的 agent 从这里开始（agent 视角，含实测输出和踩坑）
  • 操作手册：每天的命令、总控流程、故障处理
  • 任务卡模板：代码卡 / 验收卡 / 诊断卡 / 手动卡
  • 迁移指南：从聊天里手工分发迁到蜂巢
  • 多机并行开发：多台机器 + 多个 agent 并行的部署、host 路由、防冲突、合流
  • Windows 接入：bootstrap.ps1 + 计划任务
  • Gitea 接入：私有仓、host-scoped 凭据 helper、T-0001 冒烟记录
  • chroot GUI agent：小浣熊 / WorkBuddy 的完整接法
  • MCP 接入：让任意 agent 通过 MCP 查/领/交/终止任务
  • 集群架构 v3.1：目标架构（P0/P1 + P2a 已落地，P2b 进行中）：hived、本地副本、OSPF 式自适应、Git 里程碑
  • 方案全文
  • CHANGELOG