AI 深度技能之-解读Hermes Agent（四）- Hermes Kanban 多 Agent 流水线什么是 Her

一个需求从拆解到上线，中间要经过需求分析、方案设计、编码实现、代码审查——如果每个阶段都靠人手动切换 Agent、复制上下文，这条流水线就是断的。Hermes Kanban 解决的核心问题就是：让多个 Agent Profile 自动接力，把整条流水线连起来。

什么是 Hermes Kanban

Hermes Kanban 是 Hermes Agent（Nous Research 出品）内置的持久化多 Agent 任务看板。底层是一个 SQLite 数据库（kanban.db），所有 Profile 都能读写。你在一个 Profile 里创建的任务，另一个 Profile 拉取后自动执行——不需要消息队列，不需要额外服务端。

核心设计很直接：

任务（Task） 是看板上的一张卡片，有标题、描述、指派人（assignee）、状态
Profile 就是 assignee——每个 Profile 是一个独立 Agent，有自己的记忆、技能、配置
Dispatcher 是 Gateway 内嵌的调度器，每 60 秒扫描一次数据库，发现 ready 状态的任务就拉起对应的 Worker 进程
Worker 是被 Dispatcher 拉起的 Agent 进程，执行完调用 kanban_complete 交还结果

这套机制让你可以编排一条完整的流水线：需求分析交给 @pm，方案设计交给 @designer，编码交给 @coder，审查交给 @reviewer——每个环节的产出自动成为下一环节的输入。

架构总览：

Hermes Kanban 架构图上图展示了五个层次：CLI/GUI 入口 → SQLite 核心 → Dispatcher 调度 → Worker 进程池 → 文件系统。Worker 通过 kanban_* 工具集直接操作数据库，不需要 shell out 调用 CLI。

核心概念速览

在动手之前，先理清几个关键概念：

概念	说明
Board	看板，一个独立的工作流队列。默认 board 叫 `default`，多项目可创建多个 board，各自独立 SQLite DB
Task	看板卡片，有 `title` / `body` / `assignee` / `status` / `skills` / `goal_mode`
Run	一次执行尝试。一个 Task 可以有多次 Run（重试），每次 Run 记录 Worker、耗时、结果摘要、metadata
Profile	assignee 的值，一个独立 Agent 实例（config + memory + skills + sessions）
Dispatcher	Gateway 内嵌调度器，60s 轮询 `ready` 状态任务，拉起对应 Profile 的 Worker
Worker Lane	Worker 的工作模式——Profile 作为 assignee 时被 Dispatcher 拉起后的行为契约
Tenant	可选的租户隔离，同一个 board 内用 `--tenant` 过滤，不跨 board
Metadata	Run 级别的结构化交接数据（`changed_files` / `decisions` / `diff_path` 等），下游 Worker 通过 `kanban_show` 读取

任务状态机

任务在看板上的流转遵循以下状态机：

Kanban 任务状态机

triage：刚创建、还没分解到具体 assignee 的粗略想法
todo：已分解、有 assignee，但前置依赖未完成
ready：就绪队列，Dispatcher 下一个 tick 就会 claim
running：Worker 正在执行，带 TTL 锁防止重复领取
blocked：需要人工介入或等待外部依赖
done：已完成，结果可供下游消费

Dispatcher 的容错机制：如果同一个 Task 连续 spawn 失败 2 次（默认 failure_limit），自动转入 blocked 状态并附带最后一次错误信息，防止无限重试。

环境准备

1. 安装 Hermes Agent

# 从官方文档获取安装脚本
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 验证安装
hermes --version
hermes kanban --help

2. 初始化 Kanban

# 初始化看板（创建 ~/.hermes/kanban.db）
hermes kanban init

# 启动 Dashboard（浏览器打开 http://127.0.0.1:9137）
hermes dashboard

第一次执行任何 hermes kanban 命令也会自动初始化数据库，kanban init 是显式调用。

3. 创建流水线所需的 Profile

这是流水线的核心——每个阶段对应一个专职 Profile：

# 需求分析 Agent
hermes profile create pm \
  --description "产品经理：拆解需求、写用户故事、定义验收标准" \
  --model claude-sonnet-4-20250514 \
  --toolset kanban,terminal,file

# 技术设计 Agent
hermes profile create designer \
  --description "架构师：技术方案设计、API 定义、数据建模" \
  --model claude-sonnet-4-20250514 \
  --toolset kanban,terminal,file,github-code-search

# 编码实现 Agent
hermes profile create coder \
  --description "全栈工程师：按设计方案编码实现、写测试" \
  --model claude-sonnet-4-20250514 \
  --toolset kanban,terminal,file,github-code-review

# 代码审查 Agent
hermes profile create reviewer \
  --description "审查员：代码质量检查、安全审计、给出修改建议" \
  --model claude-opus-4-20250514 \
  --toolset kanban,terminal,file,github-code-review,security-pr-audit

--description 参数很关键——当 @orchestrator 需要路由任务时，它通过 description 判断该把任务交给谁。

4. 启动 Gateway（调度器）

# 启动 Gateway，内含 Dispatcher
hermes gateway start

Gateway 启动后，Dispatcher 每 60 秒扫描一次 ready 状态的任务，匹配 assignee 对应的 Profile，拉起 Worker 进程。你也可以在 Dashboard 里实时观察这个过程。

实战：搭建需求 → 设计 → 编码流水线

流水线全景

三阶段流水线

上图展示了一条完整的五阶段流水线：需求分析 → 方案设计 → 编码实现 → 代码审查 → 合并交付。每个阶段的 Worker 完成后调用 kanban_complete，产出的 summary 和 metadata 自动传递给下游。

第一步：创建编排者任务

你是整条流水线的发起人。先创建一个根任务，指派给编排者 Profile（或你自己用 /kanban 命令）：

hermes kanban create "实现用户登录注册模块" \
  --assignee orchestrator \
  --body "需求：邮箱注册 + 密码登录 + JWT 会话管理 + 登录限流。
         交付标准：可运行的 API + 单元测试覆盖 80%+。
         技术栈：Python FastAPI + PostgreSQL。" \
  --skill project-management

第二步：编排者分解任务

@orchestrator 的 Worker 被 Dispatcher 拉起后，它做三件事：

调用 kanban_show 读取任务详情
分析需求，拆解为子任务
调用 kanban_create 创建子任务，指派给对应 Profile

# orchestrator 的内部逻辑（模型自动执行）：
kanban_show()                          # 读取根任务

# 创建需求分析子任务
kanban_create(
  title="需求分析：登录注册模块",
  assignee="pm",
  parent_id="t_root",
  body="拆解用户故事、定义验收标准、输出 PRD 文档"
)

# 创建设计子任务（依赖需求分析完成）
kanban_create(
  title="技术方案设计",
  assignee="designer",
  parent_id="t_root",
  body="根据 PRD 设计 API 接口、数据模型、安全方案",
  kind="dependency"                     # 标记为依赖，等需求完成自动就绪
)

kanban_complete(summary="已分解为 4 个子任务，依赖链已建立")

parent_id 建立了任务间的父子关系。kind="dependency" 的子任务初始状态是 todo，当父任务完成后自动提升为 ready。

第三步：PM 完成需求分析

Dispatcher 下一个 tick 发现 @pm 有一个 ready 任务，拉起 PM Worker：

# PM Worker 内部：
kanban_show()                          # 读取任务 + parent context

# 做需求分析工作...
# 输出 PRD 文档到 workspace

kanban_heartbeat(note="PRD 初稿完成，正在写验收标准")

# 完成交接
kanban_complete(
  summary="PRD 已完成。用户故事 5 个，验收标准 12 条。",
  metadata={
    "prd_path": "workspaces/login-module/docs/PRD.md",
    "user_stories": 5,
    "acceptance_criteria": 12
  }
)

第四步：Designer 接力

@designer 的 Worker 被拉起后，通过 kanban_show 不仅看到自己的任务，还能看到 parent 的 handoff——PRD 路径、用户故事数、验收标准。它读取 PRD 文档后开始设计：

kanban_show()                          # 读取任务 + parent handoff (PRD 路径)
# 读取 PRD，设计 API + 数据模型 + 安全方案
kanban_heartbeat(note="API 设计完成，正在画数据模型")

kanban_complete(
  summary="方案设计完成。6 个 API 端点，3 张数据表。",
  metadata={
    "design_doc": "workspaces/login-module/docs/DESIGN.md",
    "api_endpoints": ["/register", "/login", "/logout", "/refresh", "/verify", "/me"],
    "tables": ["users", "sessions", "rate_limits"],
    "decisions": "JWT + Refresh Token 双令牌策略"
  }
)

第五步：Coder 编码

@coder 读取设计文档后开始编码。关键：Coder 不需要从零理解需求——parent handoff 里的 design_doc 路径让它直接定位到方案文件：

kanban_show()                          # 读取任务 + parent handoff (设计文档路径)
# 按 DESIGN.md 编码实现
kanban_heartbeat(note="users 表 + sessions 表 migration 完成")
kanban_heartbeat(note="注册 + 登录 API 完成，正在写测试")

kanban_complete(
  summary="编码完成。6 个 API 全部实现，单元测试覆盖率 87%。",
  metadata={
    "changed_files": [
      "app/api/auth.py",
      "app/models/user.py",
      "app/models/session.py",
      "tests/test_auth.py"
    ],
    "test_coverage": 0.87,
    "diff_path": "workspaces/login-module/diffs/feature-auth.patch"
  }
)

第六步：Reviewer 审查

@reviewer 读取 coder 的 handoff（变更文件列表、测试覆盖率、diff 路径），开始审查：

kanban_show()                          # 读取任务 + parent handoff (代码变更列表)
# 审查代码 + 安全审计
kanban_heartbeat(note="安全审计中：检查 SQL 注入、XSS、CSRF")

# 如果发现问题，block 退回
kanban_block(
  reason="refresh_token 未做旋转，存在重放攻击风险",
  kind="capability"                     # 能力不足，需要 Coder 修改
)

# 或者审查通过
kanban_complete(
  summary="审查通过。安全审计无高危项，代码质量 A 级。",
  metadata={"verdict": "approve", "security": "clean"}
)

查看流水线状态

任意时刻，你可以查看整条流水线的进度：

# 查看所有任务
hermes kanban list

# 查看某个任务的详情 + 所有 Run 历史
hermes kanban show t_abc123

# 查看执行历史
hermes kanban runs t_abc123
# #  OUTCOME    PROFILE     ELAPSED  STARTED
# 1  completed  pm              45s  2026-07-12 10:30
#    → PRD 已完成。用户故事 5 个，验收标准 12 条。
# 2  completed  designer     2m 15s  2026-07-12 10:33
#    → 方案设计完成。6 个 API 端点，3 张数据表。
# 3  completed  coder       8m 42s  2026-07-12 10:36
#    → 编码完成。6 个 API 全部实现，单元测试覆盖率 87%。
# 4  completed  reviewer     3m 20s  2026-07-12 10:45
#    → 审查通过。安全审计无高危项，代码质量 A 级。

也可以直接在 Dashboard 里看，列视图按状态分组，点开任意卡片就能看到完整的 handoff chain。

CLI 命令速查

任务管理

# 创建任务
hermes kanban create "任务标题" \
  --assignee @coder \
  --body "详细描述" \
  --skill github-code-review \    # 附加技能（可多个）
  --skill security-pr-audit \
  --goal                            # 目标模式：循环执行直到验收通过
  --triage                          # 创建到 triage 列而非 todo
  --tenant team-a                   # 租户过滤

# 查看任务列表
hermes kanban list
hermes kanban list --assignee @coder --status ready
hermes kanban list --tenant content-ops --limit 20

# 查看任务详情（含 parent handoff、comment thread、run 历史）
hermes kanban show t_abc123

# 查看执行历史
hermes kanban runs t_abc123

# 归档已完成任务
hermes kanban archive t_abc123

Board 管理

# 列出所有 board
hermes kanban boards list

# 创建新 board（多项目隔离）
hermes kanban boards create api-server \
  --name "API Server" \
  --description "后端 API 项目" \
  --icon 🚀 \
  --switch                         # 切换为当前活跃 board

# 在指定 board 上操作（不切换）
hermes kanban --board api-server create "实现登录" --assignee @coder

# 切换活跃 board
hermes kanban boards switch api-server

/kanban slash 命令（Gateway 内）

如果你正在和某个 Agent 对话（通过 Telegram / Discord / Slack），可以直接在对话里用 slash 命令操作看板：

/kanban create "修复登录 bug" --assignee @coder
/kanban list
/kanban show t_abc123
/kanban boards switch api-server

/kanban 会绕过"运行中的 Agent 不能操作看板"的保护——这是设计允许的，让你在对话中即时管理任务。

进阶模式：Fan-out / Fan-in

流水线不一定是线性的。当你需要并行调研多个方案时，用 Fan-out / Fan-in 模式：

Fanout Fanin 模式

# 创建根任务（编排者）
hermes kanban create "技术选型调研：ORM 框架对比" \
  --assignee orchestrator \
  --body "对比 SQLAlchemy 2.0 / Tortoise ORM / SQLModel，从性能、生态、学习成本、维护活跃度四个维度评估"

编排者执行时 fan-out 出三个并行任务：

kanban_show()  # 读取根任务

# Fan-out：创建三个并行调研子任务
kanban_create(
  title="方案A调研：SQLAlchemy 2.0",
  assignee="researcher",
  parent_id="t_root",
  body="性能基准测试、生态调研、学习曲线评估"
)
kanban_create(
  title="方案B调研：Tortoise ORM",
  assignee="researcher",
  parent_id="t_root",
  body="异步性能测试、Django 兼容性、社区活跃度"
)
kanban_create(
  title="方案C调研：SQLModel",
  assignee="researcher",
  parent_id="t_root",
  body="Pydantic 集成、类型安全、FastAPI 协同"
)

kanban_complete(summary="已 fan-out 三个调研任务")

三个 @researcher Worker 并行执行（如果 Profile 配置了并发），各自产出 summary。然后编排者 fan-in 创建综合任务：

# 所有子任务完成后，创建综合分析任务
kanban_create(
  title="综合分析：ORM 选型结论",
  assignee="writer",
  parent_id="t_root",
  body="读取三个调研子任务的 summary 和 metadata，输出对比报告",
  kind="dependency"  # 等所有 sibling 完成后自动 ready
)

kind="dependency" 的妙处：子任务初始状态是 todo，Dispatcher 只在所有 sibling 都 done 后才把它提升为 ready。不需要写轮询逻辑。

进阶模式：Swarm（黑板模式）

Swarm 是更激进的并行模式——多个 Worker 同时读写一个共享"黑板"（Blackboard），由一个验证者 Gate 做准入门禁：

Swarm 黑板模式

Swarm 和 Fan-out 的区别：

维度	Fan-out / Fan-in	Swarm
数据流	每个 Worker 独立产出于各自的 task	多个 Worker 写同一个共享黑板
汇聚方式	编排者逐个读取子任务 summary	验证者一次性校验黑板全部内容
并发度	受 assignee 限制（一个 Profile 一次一个 Run）	多个不同 Profile 同时写黑板
适用场景	方案对比、独立调研	大型重构、多维度审计

Swarm 的实现依赖 kanban_comment——多个 Worker 把自己的发现 append 到根卡片的 comment thread 里，验证者读取所有 comment 后判断是否通过。

容错与重试

自动重试与熔断

Dispatcher 的内建容错机制：

场景	行为
Spawn 失败（Profile 不存在）	重试，连续 `failure_limit` 次（默认 2）后自动 block
Worker 进程崩溃（OOM / segfault）	Dispatcher 检测到 dead pid，任务回到 `ready`，重新 claim
Worker 超时（heartbeat 超过 TTL）	Dispatcher 回收任务，标记为 `ready` 重新调度
Worker 主动 block	任务进入 `blocked` 状态，等待人工 unblock

查看失败历史：

hermes kanban runs t_ef5d
# #   OUTCOME        PROFILE      ELAPSED  STARTED
# 1   spawn_failed   deploy-bot       0s   2026-07-12 14:30
#     ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 2   spawn_failed   deploy-bot       0s   2026-07-12 14:31
#     ! AWS_ACCESS_KEY_ID not set in deploy-bot env
# 3   gave_up        deploy-bot       0s   2026-07-12 14:32
#     ! AWS_ACCESS_KEY_ID not set in deploy-bot env

手动 unblock

修复底层问题后，手动将 blocked 任务恢复为 ready：

hermes kanban unblock t_ef5d

审查退回

代码审查发现问题时的退回流程：

# Reviewer Worker 内部：
kanban_block(
  reason="refresh_token 未做旋转，存在重放攻击风险",
  kind="capability"
)

kind 分类决定了退回后的行为：

kind	含义	自动行为
`dependency`	等待依赖完成	等依赖 done 后自动 ready
`needs_input`	需要人工输入	停在 blocked，等 unblock
`capability`	能力不足	停在 blocked，等 unblock
`transient`	临时问题（网络等）	停在 blocked，等 unblock

Dashboard 可视化看板

# 启动 Dashboard
hermes dashboard
# 默认地址：http://127.0.0.1:9137

Dashboard 是一个 React SPA，通过 WebSocket 实时刷新。主要视图：

列视图（Kanban Board）

按状态分列：Triage → To Do → Ready → In Progress → Blocked → Done。

In Progress 按 Profile 分组（Lanes by profile），一眼看到哪个 Worker 在忙
拖拽改变状态（比如把 triage 拖到 todo 触发 assignee 选择）
点开卡片侧滑抽屉，展示完整 comment thread + run history + metadata

运行历史

每个 task 下方展开 Run History，包含：

执行序号、outcome（completed / spawn_failed / gave_up / crashed / timed_out）
Worker Profile 名、执行时长、启动时间
handoff summary 全文
metadata blob（changed_files / decisions / diff_path）

批量操作

多选卡片 → 批量 archive / 批量 assignee
拖拽到删除区域 = archive

最佳实践

1. Profile 设计原则

一个 Profile = 一个角色，不是"一个工具"。@coder 不应该既写前端又做 DevOps——拆成 @frontend-dev 和 @sre。

description 要写清楚，因为 Orchestrator 靠它做路由判断：

# ✅ 好的 description
hermes profile create coder \
  --description "全栈工程师：Python/TypeScript 编码、单元测试、代码重构"

# ❌ 差的 description
hermes profile create coder \
  --description "写代码的"

2. Metadata 交接设计

kanban_complete 的 metadata 字段是上下游数据传递的核心。约定好结构：

# 推荐的 metadata 结构
{
    "changed_files": ["path/to/file1.py", "path/to/file2.py"],
    "decisions": "选择 JWT 而非 session，因为需要无状态",
    "diff_path": "workspaces/project/diffs/feature.patch",
    "test_coverage": 0.87,
    "blocking_issues": []  # 空数组表示无遗留问题
}

下游 Worker 通过 kanban_show 读取 parent 的 metadata，直接拿到文件路径和关键决策，不需要重新分析。

3. Workspace 隔离

每个 board 有独立的 workspaces/ 目录。不同项目的代码不要混在一起：

# 为不同项目创建不同 board
hermes kanban boards create api-server --switch
hermes kanban boards create mobile-app

# Worker 的 workspace 路径自动隔离
# api-server board → ~/.hermes/kanban/boards/api-server/workspaces/
# mobile-app board → ~/.hermes/kanban/boards/mobile-app/workspaces/

4. 技能附加

不要把所有技能塞进 Profile 的默认 toolset——按需在 Task 级别附加：

# 只有需要安全审计的任务才附加 security-pr-audit
hermes kanban create "审计认证流程安全性" \
  --assignee @reviewer \
  --skill security-pr-audit \
  --skill github-code-review

# 只有需要翻译的任务才附加 translation
hermes kanban create "翻译 README 为日文" \
  --assignee @linguist \
  --skill translation

技能名必须对应 assignee Profile 已安装的技能（hermes skills list 查看）。Task 级附加不会全局安装，只是这次 Run 临时加载。

5. Goal Mode 用于循环任务

普通任务 Worker 执行一次就退出。但有些任务需要循环迭代直到达标——比如"修复所有 lint 错误"可能需要多轮：

hermes kanban create "修复所有 ESLint 错误" \
  --assignee @coder \
  --goal  # 启用目标模式：Worker 循环执行，每次 turn 后 judge 检查是否达标

Goal mode 背后是 Ralph 式的 judge 循环：每次 Worker turn 后，一个辅助 judge 检查输出是否满足卡片的 title + body 作为验收标准，不满足则继续。

踩坑记录

1. Dispatcher 不拉起 Worker

检查清单：

Gateway 是否启动：hermes gateway status
Profile 是否存在：hermes profile list
任务状态是否 ready（不是 todo）
assignee 名称是否匹配 Profile 名（大小写敏感）

2. Worker 执行后任务不前进

确保 Worker 调用了 kanban_complete 或 kanban_block。如果 Worker 进程异常退出（没来得及调用），Dispatcher 检测到 dead pid 后会回收任务到 ready，但不会自动标记为 done。

3. 跨 Board 引用

Kanban 不支持跨 Board 的 parent-child 关系。如果你需要跨项目引用，用 free-text mention 在 body 里写 see board:api-server task:t_abc，手动查找。

4. 并发冲突

同一个 Board 上，同一个 assignee 的多个 ready 任务不会并行执行——Dispatcher 默认串行拉起同一 Profile 的 Worker。如果需要并行，创建多个同类 Profile（@coder-1 / @coder-2），或配置 Profile 的并发数。

5. 日志位置

Worker 的 stdout/stderr 写入 <board-root>/logs/<task_id>.log。通过 kanban show 的 run 详情可以读到 log_path、exit code、summary。排查 Worker 行为异常时，先看这个日志。

总结

Hermes Kanban 的设计哲学是：不用引入新的基础设施，用 SQLite + 文件系统就能编排多 Agent 流水线。

核心价值：

Profile 即角色——每个 Agent 有独立记忆、技能、配置，不互相污染
Task 即交接——metadata 结构化传递，下游不需要重新理解上游上下文
Dispatcher 即调度器——60 秒轮询，自动拉起，自动容错
Board 即项目——多项目隔离，独立 DB，独立 workspace

适合的场景：一个开发者 + 多个 Agent Profile 协作完成完整交付。不适合的场景：跨机器分布式调度（那是 Kubernetes + 消息队列的活）。

如果你已经在用 Hermes Agent，Kanban 是把单 Agent 变成 Agent 团队的关键一步。从一条简单的需求 → 设计 → 编码流水线开始，逐步加入审查、测试、部署环节，你会很快建立起自己的 Agent 流水线。

参考文档：

Hermes Kanban 官方文档：hermes-agent.nousresearch.com/docs/user-g…
Kanban Tutorial（四个实战故事）：kanban-tutorial
Worker Lanes 契约：kanban-worker-lanes
GitHub 仓库：github.com/NousResearc…