一个人开三个 AI 助手之后我发现真正的瓶颈不是模型当 OpenCode、Claude Code、Codex 同时为我干活时卡住我的不是「模型够不够聪明」而是——我到底派了哪些活、它们干到哪了、产出散落在哪。一、聊天窗口撑不起多 Agent 协作同时开好几个 AI 编程助手看起来很爽实际很快就撞墙谁在干什么没有统一的任务归属和在线状态两个 Agent 改同一块代码、重复劳动你压根不知道。干到哪了长任务一断线就失忆进度、重试、超时没人兜底只能靠翻聊天记录回忆。产出在哪、靠不靠谱需求、接口契约、测试验收散落在各自会话里写没写全、写没写对无人把关。根因其实很朴素聊天窗口是「逐句对话」的载体它天生缺少三样东西——任务的事实源、产出的门控、执行的可追溯。我想要的是让多 Agent 协作有一套本地可查、可追溯的「事实」而不是靠我在几个窗口之间人肉同步。二、于是我把任务收敛成一份本地事实mio-taskhub是一个本地单用户的跨 Agent 任务协调中枢人在 Web 看板建任务、看进度多个 AI 助手通过 MCP 或 HTTP 注册上线、自动领活、上报进度、交回结果。全程零联网、零外部依赖。它把我关心的东西全部钉在本地 SQLite 里任务执行状态机 7 段研发阶段谁领了、干到哪一阶段一目了然。Agent注册与心跳180 秒无心跳自动转离线。执行Run 进度 重试 超时回收。产出22 类文档、7 件套文档链、生命周期状态机 写时质量 lint。事件一条单调递增的全局事件流供增量订阅。人 mio-taskhub Agent │ │ │ │ 建任务 / 记想法 │ │ ├─────────────────────────│ queued · brainstorming │ │ │─────── register ─────────────┤ │ │─────── claim ────────────────┤ (或 hub 主动分配) │ ├─────── run 上下文 ───────────│ │ │─────── heartbeat 进度 ───────┤ │ 看板 / 甘特 / 拓扑 │ │ │─────────────────────────┤─────── submit_result ────────┤ │ │ completed · done │三、五个我每天都在用的能力17 段研发阶段产出物就是过路口令任务除了执行状态机还正交地挂一条 7 段流水线brainstorming → design → planning → ready → implementing → review → done ↑spec/api ↑plan ↑review进design要求spec与api文档都已approved进planning要求plan已approved阶段不到位任务就别想被领走。「先写文档再写代码」从一句标语变成流程里的一堵墙。2文档链门控 ReadEvidence最值得讲的一招Agent 领任务时服务端会返回一份必读清单required_reads默认 spec/api/requirement和文档内联预览。关键点内联预览不等于已读。动手前必须对每个必读项调taskhub_read_document(task_id, kind, run_id本次 run)落一条带内容指纹的 ReadEvidence。提交结果时服务端校验两件事缺了已读记录 →422文档在读取后被改动指纹不符→422于是「假装读过文档」在服务端层面不成立。连git push --no-verify也绕不过服务端门控——因为它压根不看你的本地钩子。3想法 → 讨论 → 拆解需求不是凭空变成任务的需求要发酵new ── fermenting ── formed ── broken_down ── (任务全部完成后可回流)taskhub_add_idea记下想法taskhub_open_discussion开会碰撞taskhub_close_discussion写结论成形后taskhub_breakdown_idea一次拆成多个带依赖的任务任务全完成后想法可回流继续演进为 ADR架构决策记录。4文档质量棘轮基线只升不降质量分公式score max(0, 100 - 20*errors - 5*warns)推进到review/approved/done时要求errors 0棘轮质量分与用例数按任务记录历史最好值后续低于基线直接 422确为有意下调用forcetrue并留痕。效果就是「先糊上去、以后再补」的债滚不起来。5心跳保活 自动派活空闲时每约 1 分钟调taskhub_agent_heartbeat保活超 180 秒转离线执行期间taskhub_heartbeat(run_id, progress)上报进度看门狗据此判断 Run 是否僵死调度器每 30 秒扫一次有「空闲在线 Agent ready 任务」就直接分配遵循高优先级优先 FIFO 多 Agent 公平轮转。四、一张图看懂整套闭环Agentmio-taskhub人Agentmio-taskhub人建任务 / 记想法registerclaim(task_id) → run_id required_readsread_document(kind, run_id)heartbeat(progress)submit_result(success)422 若缺 ReadEvidence / 指纹不符看板 / 文档 / 事件流更新五、实战五步跑通一个任务第一步注册上线# MCP 工具taskhub_register(nameopencode,agent_typecli)# 无 MCP 时的 CLI 降级路径python packaging/agent_wrapper.py opencode register第二步领取指定任务务必带task_id否则按相关度可能领到别的任务taskhub_claim(agentopencode,task_id0df294e8)// 返回run_id required_reads required_fr documents(预览)第三步写码前逐份读取必读文档产生 ReadEvidencetaskhub_read_document(task_id0df294e8,kindspec,run_idrun)taskhub_read_document(task_id0df294e8,kindrequirement,run_idrun)第四步执行期间上报进度taskhub_heartbeat(run_idrun,progress50,checkpoint编码中)第五步提交结果成功路径会校验 ReadEvidencetaskhub_submit_result(run_idrun,successtrue,result产出描述)提交前还能用taskhub_read_status(run_id)自查看还差哪些必读项。六、我踩过的五个坑不传task_id会领错任务claim默认按相关度挑点名提取务必显式传task_id。内联预览 ≠ 已读claim返回的documents.content只是预览不落 evidence提交照样 422。文档读完又改内容 → 指纹失效需要重读尤其改文档状态会改写文档头部版本/状态/时间务必在改完状态后重读。--no-verify只绕本地钩子绕不过服务端门控别抱侥幸。文档 kind 有三处同步点DOC_KINDS/DOC_PATTERNS/KIND_META新增一类漏改前端就不显示。七、适合谁用个人 / 小团队的本地多 Agent 协作需要强文档链与可追溯研发流程的团队离线或内网环境零联网、零外部依赖。几点坦白它是单用户本地服务认证只有单 Bearer Token不要直接暴露公网SQLite 有并发上限规模再涨要迁 Postgres文档质量 lint 是启发式的只看章节标题与表格行数判断不了内容对不对真正的内容审查还得靠人或 Agent 读。一句话收尾把「多 Agent 协作」从聊天窗口里的口头约定变成本地可查、可门控、可追溯的事实。项目地址http://127.0.0.1:48620本地服务Git 仓库https://github.com/mldlbs/mio-taskhub相关链接https://crlkcloud.cyou/关键词多 Agent 协作 / MCP / 任务中心 / 文档门控 / ReadEvidence