企业官网建设流程全解析

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_mode=WAL;" sqlite3 ~/.hermes/kanban.db "PRAGMA busy_timeout=5000;"

WAL 模式让读和写不互相阻塞，busy_timeout则让写操作在锁冲突时等待而不是直接报错。这两条是我在复现并行委托时最先加的配置，不加的话四五个子 Agent 一起跑就会零星失败。

另外轨迹文件是 JSONL 格式，落在~/.hermes/trajectories/*.jsonl，同时同步进 SQLite 会话库。系统提示、用户输入、工具调用、子 Agent 输出、错误堆栈都在里面。想复现某个失败节点，直接搜轨迹比翻日志快：

hermes session_search "failed at kanban_complete"

3. 协作机制：角色分派与并行委托

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_subagents=4 assign roles by skill match merge results after all subagents complete

启动带委托能力的 Agent：

hermes 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-mini"

Key 用环境变量注入，不要硬编码进文件：

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 结尾不要多加/v1，TaoToken 的接入地址是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 并行时的成本。