1. 为什么我要拆 hermes-kanban 的架构hermes-kanban 是 Hermes Agent 在 v0.12.0 引入的多智能体任务编排模块简单说就是把一个模糊的大目标拆成一张张卡片每张卡片绑定一个 AI 角色然后并行跑、自动流转状态。它适合谁适合那些已经受够单 Agent 串行干活、一步卡死全流程停摆的开发者也适合想研究 AI Agent 协作机制、但不想从零造轮子的架构学习者。我这次调研的目标很明确不看它有多少 Star而是把它的存储层和协作机制拆开搞清楚 SQLite 到底存了什么、角色是怎么分派的、并行委托靠什么隔离上下文。然后交付一套可以直接复制的 config.toml 和 settings.json 骨架再通过 TaoToken 统一 Key 通道把 AI 工具接进来跑一次真实的验证请求。这样你拿到的不是一篇读后感而是一个能复现的调研环境。整个拆解会围绕三个问题展开数据落在哪、任务怎么流转、模型调用怎么统一。前两个是 hermes-kanban 自身的架构第三个是我在调研时额外补的一层——因为多角色协作意味着多模型调用如果每个角色都配一套 Key管理成本会爆炸。下面按顺序来。2. 存储层拆解SQLite 里到底存了什么hermes-kanban 的持久化文件默认在~/.hermes/kanban.db这是一个标准的 SQLite 库。我建议你第一件事不是急着跑任务而是先把库结构 dump 出来看一遍这样后面排查状态流转问题时心里有底。# 确认库文件存在 ls -lh ~/.hermes/kanban.db # 查看所有表 sqlite3 ~/.hermes/kanban.db .tables # 查看核心表结构records 表是任务卡片主表 sqlite3 ~/.hermes/kanban.db .schema records实测下来核心数据模型是父子两层父任务卡片Parent Task存顶层目标和拆解规则子任务卡片Sub Task存原子任务两者通过parent_id建立层级关系。每个子任务绑定一个 Agent Profile也就是角色。状态机是pending → assigned → running → completed / failed / blocked失败可以重试阻塞可以解除。这里有个容易踩的坑SQLite 默认的并发写能力有限如果你同时跑多个子 Agent 往同一张表写状态可能会遇到database is locked。调研阶段问题不大但如果你打算压测并行度建议先把 WAL 模式打开sqlite3 ~/.hermes/kanban.db PRAGMA journal_modeWAL; sqlite3 ~/.hermes/kanban.db PRAGMA busy_timeout5000;WAL 模式让读和写不互相阻塞busy_timeout则让写操作在锁冲突时等待而不是直接报错。这两条是我在复现并行委托时最先加的配置不加的话四五个子 Agent 一起跑就会零星失败。另外轨迹文件是 JSONL 格式落在~/.hermes/trajectories/*.jsonl同时同步进 SQLite 会话库。系统提示、用户输入、工具调用、子 Agent 输出、错误堆栈都在里面。想复现某个失败节点直接搜轨迹比翻日志快hermes session_search failed at kanban_complete3. 协作机制角色分派与并行委托hermes-kanban 的协作设计有两个关键点理解了这两点整个架构就通了。第一是角色化分派。每个任务卡片可以绑定一个 Agent Profile常见角色有 researcher、engineer、reviewer、executor、reporter。每个 Profile 由独立的SOUL.md定义身份特征和行为边界。这样做的好处是职能分离——researcher 只负责调研和摘要engineer 只负责代码生成和执行reviewer 只做质量审查。能力不冲突职责清晰。第二是 Delegate 并行委托。主 Agent 动态生成子 Agent 实例每个子 Agent 在隔离的终端会话里跑拥有独立的上下文、工具作用域和迭代预算。子 Agent 之间互不干扰上下文开销接近零。这是它比单 Agent 串行快得多的核心原因。要让委托机制生效需要确认工具已注册并在 SOUL.md 里写并行策略。下面是我复现时用的配置片段# ~/.hermes/config.toml [agent] enable_delegate true max_delegate_workers 4 [kanban] db_path ~/.hermes/kanban.db default_roles [researcher, engineer, reviewer, executor, reporter] auto_split true max_split_depth 3 [delegate] isolation session # 每个子 Agent 独立会话 context_mode minimal # 零上下文开销 rpc_enabled true对应的settings.json骨架主要管模型和工具作用域{ agent: { profile_dir: ~/.hermes/profiles, soul_file: SOUL.md, max_iterations: 20 }, tools: { delegate_tool: { enabled: true, max_subagents: 4 }, terminal_exec: { enabled: true, sandbox: true }, web_search: { enabled: true } }, roles: { researcher: { skills: [web-search, summarize] }, engineer: { skills: [code-gen, terminal-exec] }, reviewer: { skills: [code-review, security-audit] }, reporter: { skills: [report-gen, chart-gen] } } }SOUL.md 里的并行策略指令可以这样写让主 Agent 在任务复杂度超过阈值时自动开委托# SOUL.md 片段 when task_complexity 3: use delegate_tool with max_subagents4 assign roles by skill match merge results after all subagents complete启动带委托能力的 Agenthermes run --enable-delegate --max-delegate-workers 4这里要注意max_delegate_workers不是越大越好。我试过开到 8结果 SQLite 写冲突明显增多而且模型 API 的并发限流也会触发。4 是一个比较稳的平衡点具体还得看你用的模型通道的限流策略。4. 用 TaoToken 统一模型调用通道多角色协作意味着多模型调用。researcher 可能用便宜快的模型做摘要engineer 需要代码能力强的模型reviewer 又要另一个视角。如果每个角色配一套 Key管理成本高还容易在配置里泄露。我的做法是用 TaoToken 做统一 Key/API 通道所有角色走同一个入口按需切换模型。这样配置文件里只出现一个 base_url 和一个 Key干净很多。先拿 Key访问 https://taotoken.net/api-keys 创建然后到接入文档 https://taotoken.net/doc 确认最新的参数格式。下面是我在 hermes 里接的配置# ~/.hermes/config.toml 追加 [llm] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} default_model claude-sonnet-4-5 timeout 60 [llm.role_models] researcher gpt-4o-mini engineer claude-sonnet-4-5 reviewer claude-sonnet-4-5 reporter gpt-4o-miniKey 用环境变量注入不要硬编码进文件export TAOTOKEN_API_KEY你的Key这样配置的好处是角色和模型的映射集中在一处换模型只改一行。调研阶段我经常在 researcher 上换不同模型对比摘要质量改配置比改代码快得多。如果你主要做长期编码或 Agent 编排可以看下 Coding Plan https://taotoken.net/coding-plan 它的额度模型更适合这种多轮、多角色的持续调用场景。单纯想先验证模型对话效果用模型对话页 https://taotoken.net/models 直接试就行。5. 验证请求跑通一次真实调用配置写完必须验证不然你不知道是架构问题还是通道问题。我习惯先用最小请求确认通道通再跑完整任务流。第一步用 curl 确认 TaoToken 通道可用curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 OK 两个字母}] }返回里能看到choices[0].message.content是 OK说明 Key 和 base_url 都对。第二步初始化看板并创建一个带拆解规则的父任务hermes kanban init hermes kanban create \ --title 生成Q4多平台兼容性测试报告 \ --split 5 \ --roles researcher,engineer,reviewer,executor,reporter第三步确认持久化生效sqlite3 ~/.hermes/kanban.db SELECT id, title, status FROM records LIMIT 10;你应该能看到父任务和拆解出的子任务状态从 pending 开始流转。第四步实时监控执行hermes kanban tail如果一切正常你会看到子任务依次进入 assigned、running最后 completed。失败的任务会标 failed阻塞的标 blocked。这一步是整个调研环境跑通的关键信号——存储层有数据、协作层有分派、模型通道有响应三者都验证到了。6. 本篇常见错排查报错一database is locked原因多个子 Agent 并发写 SQLite。解决开 WAL 模式加 busy_timeout或者降低max_delegate_workers。我一般两个都做。报错二401 Unauthorized或invalid api key原因环境变量没生效或者 Key 复制时带了空格。解决echo $TAOTOKEN_API_KEY确认非空重新从 https://taotoken.net/api-keys 复制。注意 base_url 结尾不要多加/v1TaoToken 的接入地址是https://taotoken.net/api具体路径以接入文档 https://taotoken.net/doc 为准。报错三子 Agent 不并行还是串行跑原因enable_delegate没开或者 SOUL.md 里没写并行策略。解决确认 config.toml 里enable_delegate true并检查tools/__init__.py里 DelegateTool 已注册。报错四任务卡在 assigned 不动原因角色对应的模型调用超时或者该角色没有绑定模型。解决检查[llm.role_models]是否覆盖了所有用到的角色适当调大 timeout。报错五轨迹文件为空原因轨迹写入路径权限问题或者会话库没同步。解决确认~/.hermes/trajectories/目录可写用hermes session_search验证会话库是否有记录。排查顺序建议从通道到存储再到协作先 curl 确认模型通道再 sqlite3 确认存储最后看 kanban tail 确认协作流转。这样能快速定位问题在哪一层。7. 调研环境搭好之后到这里你的 hermes-kanban 调研环境应该已经能跑了SQLite 存储层看得见摸得着角色分派和并行委托配置到位模型调用通过 TaoToken 统一通道走通验证请求也拿到了成功结果。接下来我建议做两件事。一是把max_delegate_workers从 4 逐步往上调观察 SQLite 写冲突和模型限流的临界点这能帮你摸清这套架构的实际并发上限。二是把轨迹文件导出来做一次分析看看哪些子任务耗时最长、哪些角色最容易失败这对理解多 Agent 协作的真实瓶颈比看文档有用得多。如果你想把模型通道也纳入长期管理Coding Plan https://taotoken.net/coding-plan 的额度模型更适合持续的多角色调用日常调试和验证用模型对话页 https://taotoken.net/models 快速试模型就够了。控制台 https://taotoken.net/console 可以看用量方便你估算多 Agent 并行时的成本。