Harness / Loop / Agent / Kanban / Gateway

Agent Loop、 Loop Router、Kanban 多 Agent 队列、各类 Agent Profile、Harness 分层、Cron/Gateway/Skills/MCP 等外围系统如何串起来

1. 一句话结论

当前 Hermes 已经不是单纯的“聊天机器人”，而是一个 以 AIAgent 为核心执行引擎，以 Loop Router 做任务分流，以 Kanban 做持久化多 Agent 协作，以 Gateway/Cron 做长期运行入口，以 Skills/Memory/Tools/MCP 做能力扩展 的本地 Agent OS。

可以把整体理解成四层：

---

2. 总流程图

flowchart TD
    U[用户请求<br/>Desktop / CLI / WeChat / Cron] --> S[会话入口<br/>加载 profile/config/memory/skills/AGENTS.md]
    S --> R{Loop Router<br/>hermes-loop route}

    R -->|quick-task-loop| Q[当前会话快速闭环<br/>执行 → 验证 → 回复]
    R -->|复杂/生产/多角色| K[创建 Kanban triage card<br/>assignee=pmagent]

    K --> PM[pmagent 编排<br/>拆任务/定验收/分派 Agent]
    PM --> KB[(~/.hermes/kanban.db<br/>任务/评论/事件/依赖/Run 历史)]
    KB --> D[Gateway 内置 Dispatcher<br/>每 60s 扫描 ready 任务]
    D --> W[启动目标 Profile Worker<br/>HERMES_KANBAN_TASK + workspace]

    W --> A[AIAgent 核心 Loop<br/>LLM ↔ Tool Calls ↔ History]
    A --> T[工具层<br/>file/terminal/web/browser/MCP/github/...]
    A --> M[Memory / Session / Skills / Compression]
    A --> C{完成还是阻塞?}

    C -->|kanban_complete| Done[写入 run summary/metadata<br/>触发下游依赖/通知]
    C -->|kanban_block| Block[进入 blocked/triage<br/>等待人类或其他任务]
    C -->|失败/超时| Retry[Dispatcher 重试/回收/熔断]
    Retry --> KB

---

3. 核心 AIAgent Loop：每个 Agent 真正怎么“思考+行动”

核心执行引擎是 Hermes 源码里的：

• run_agent.py：AIAgent 主循环

• agent/prompt_builder.py：系统提示词组装

• model_tools.py：工具 schema 收集与工具调用分发

• tools/registry.py：工具注册中心

• hermes_state.py：SQLite 会话存储

单个 Agent 回合生命周期

run_conversation()
  1. 生成 task_id
  2. 把用户消息加入 conversation_history
  3. 构建/复用 system prompt
     - persona / profile
     - AGENTS.md / CLAUDE.md / .cursorrules
     - memory / user profile
     - skills
     - tool schemas
     - environment hints
  4. 判断是否需要 preflight compression
  5. 按 provider API mode 转换消息格式
     - chat_completions
     - codex_responses
     - anthropic_messages
  6. 调用模型
  7. 解析响应
     - 有 tool_calls：执行工具，把 tool result 追加回历史，继续循环
     - 有最终文本：持久化 session/memory，返回给入口

工具调用流程

模型产生 tool_call
  → run_agent.py / model_tools.py 找到 handler
  → pre_tool_call plugin hook
  → 危险动作检查 / approval gate
  → 执行工具
  → post_tool_call plugin hook
  → tool result 写回 conversation history
  → 再次调用模型判断下一步

关键约束：

---

4. Loop Router：新增的“需求分流器”

你当前加了一套本地 Loop 编排配置，目录在：

~/.hermes/loops/
  loop-router.yaml
  base-production-loop.yaml
  quick-task-loop.yaml
  project-bootstrap-loop.yaml
  feature-delivery-loop.yaml
  bugfix-loop.yaml
  tool-install-loop.yaml
  prod-hardening-loop.yaml
  research-decision-loop.yaml
  security-audit-loop.yaml
  release-loop.yaml
  overlays/
    frontend-overlay.yaml
    backend-api-overlay.yaml
    data-migration-overlay.yaml
    security-strict-overlay.yaml
    tool-install-overlay.yaml
    docs-overlay.yaml

当前入口规则是：

hermes-loop route "<用户请求>"

Router 会输出：

当前请求的路由结果

本次请求实际执行结果：

Loop: quick-task-loop
Risk: low
Entry: pmagent
Overlays: docs-overlay
Agents: pmagent, docsagent
Max iterations: 2
Loop file: /Users/zheng/.hermes/loops/quick-task-loop.yaml

所以这篇文档属于：低风险、文档类、当前会话直接完成，不需要新建 Kanban 任务。

---

5. 当前 Loop 矩阵

Base Production Loop 的标准阶段

复杂任务默认从 base-production-loop 继承这些阶段：

intake → product → research → decision → architecture → data
→ planning → implementation → code_review → qa → security
→ devops → docs → release

不是每个任务都跑满全链路；Loop 和 Overlay 会决定哪些阶段启用。

风险升级规则

Router 里的关键升级逻辑：

---

6. Kanban：持久化多 Agent 工作队列

Kanban 是你当前多 Agent 协作的核心“任务总线”。它不是普通 todo list，而是一个 SQLite-backed durable work queue。

当前默认看板状态采样：

Kanban 和 delegate_task 的区别

Kanban Worker 生命周期

用户/pmagent 创建任务
  → 写入 ~/.hermes/kanban.db
  → dispatcher 每 60s 扫描 ready 任务
  → claim 任务并生成 task_run
  → 启动 assignee profile 作为独立 worker 进程
  → worker 获得 HERMES_KANBAN_TASK / HERMES_KANBAN_BOARD / workspace
  → worker 首先调用 kanban_show()
  → 执行任务：读写文件、终端、测试、浏览器、MCP 等
  → 长任务用 kanban_heartbeat()
  → 完成调用 kanban_complete(summary, metadata, artifacts)
    或阻塞调用 kanban_block(reason)

Worker 不会 shell 出去跑 hermes kanban complete；它通过专门的 kanban_* toolset 直接读写 DB。这一点很重要：即使 terminal backend 是 Docker/SSH/远程环境，Agent 进程仍然能正确操作本机 Kanban DB。

Kanban 关键工具

---

7. Agent Profile 矩阵

当前本机已有这些具名 profile：

注意：profile 的 gateway 状态 stopped 不代表不能工作。Kanban dispatcher 可以按需启动 profile worker；长期监听消息入口才需要 gateway running。

---

8. Harness 分层：把 Agent 从“能做”变成“可控交付”

这里的 Harness 不是单个命令，而是一套工程外壳。当前 Hermes 的各组件正好可以映射成 7 类 Harness：

当前“完成定义”

复杂任务默认不能只靠模型说“完成”，至少要满足：

• 验收标准明确；

• 实现或产物真实落地；

• 有测试/验证/命令输出证据；

• 代码改动经过 review；

• 涉及安全/部署/数据时，对应 Agent 通过；

• 文档或 runbook 补齐；

• release/deploy 场景有 Go/No-Go 和回滚策略。

---

9. Gateway / Cron / Delegation / Skills 等外围系统

9.1 Gateway

当前状态采样：

Gateway 负责：

• 接收外部消息平台消息；

• 运行对应 profile 的 Agent 会话；

• 承载 Cron scheduler tick；

• 承载 Kanban dispatcher；

• 投递 Cron/Kanban 结果通知。

9.2 Cron

Cron 是持久化定时任务系统，存储在：

~/.hermes/cron/jobs.json
~/.hermes/cron/executions.db
~/.hermes/cron/output/<job_id>/<timestamp>.md

当前状态：4 active, 4 total。

Cron 每次触发都会启动一个新的 Agent session，不继承当前聊天上下文。重要能力：

9.3 delegate_task

delegate_task 是进程内短期 subagent：

• 适合并行分析、短任务、父 Agent 需要结果后继续；

• 子 Agent 有独立上下文和 terminal session；

• 不持久，进程退出会丢；

• leaf 默认不能再 delegate；orchestrator 受配置限制；

• 不适合长周期、人类介入、重启后继续的任务，这些用 Kanban。

9.4 Skills / Memory / Curator

9.5 MCP / Deferred Tools / Plugins

当前 default profile 有 MCP：GitHub、GitLab、Chrome DevTools、codebase-memory-mcp 等。Hermes 采用“窄核心 + 边缘扩展”原则：

• 常用能力通过 core tools/toolsets 暴露；

• 大量能力作为 deferred tools，需要时再加载 schema；

• 第三方能力优先做 MCP、plugin 或 skill，而不是塞进核心工具列表；

• toolsets 控制不同平台/任务暴露哪些工具，避免每次 LLM 请求都携带过多 schema。

---

10. 三条典型执行路径

路径 A：当前这种小型文档任务

用户请求文档
  → 必须先 hermes-loop route
  → 命中 quick-task-loop + docs-overlay
  → 当前 default Agent 直接收集资料
  → 写入 markdown 文档
  → 验证文件落地
  → 回复路径

路径 B：新功能/项目交付

用户要开发功能/项目
  → hermes-loop route 命中 feature-delivery-loop
  → 创建 Kanban triage card 给 pmagent
  → pmagent 明确 scope/验收标准
  → product/architect/codexdev/qa/codereview 等按需协作
  → 每个 worker 通过 kanban_complete 写证据
  → QA/review/security/devops/docs gates 通过
  → pmagent 汇总交付

路径 C：部署/Gateway/launchd 问题

用户反馈 gateway/launchd/部署/端口/网络问题
  → route 风险升级
  → 必须包含 devopsagent
  → 如涉及 token/auth/证书/MCP 安装，再包含 securityagent
  → 真实检查服务状态、日志、端口、配置
  → 修复后验证 browser/CLI/gateway 两侧行为
  → 写 runbook/回滚说明

---

11. 关键本地文件与命令速查

---

12. 当前系统的设计判断

1. AIAgent 是执行内核，不是项目管理者。
   它负责模型-工具循环、上下文、压缩、fallback、工具调用；复杂交付不应该全塞进一个聊天回合。

2. Loop Router 是任务入口治理。
   它把“这个需求该直接做，还是该进入生产级多 Agent 流程”变成显式规则。

3. Kanban 是长期多 Agent 协作的主干。
   它解决 delegate_task 不持久、不可人工介入、不可审计的问题。

4. Profile 是 Agent 身份。
   pmagent/docsagent/securityagent/devopsagent/... 不是简单标签，而是拥有独立配置、记忆、技能和运行入口的 worker 身份。

5. Harness 是质量体系。
   Loop、Kanban、toolsets、events、gates、approval、session history 共同组成“能交付、能复盘、能重试”的外壳。

6. Gateway 是常驻大脑干线。
   现在 default profile 的 gateway running，承载 WeChat 入口、Cron tick、Kanban dispatcher，是这套系统能持续运行的关键。

---

13. 建议后续补强

---

14. 最小操作守则

以后处理请求时，可以按这个规则执行：

1. 复杂/项目/生产/agent/loop/kanban/工作流相关请求：先 hermes-loop route。
2. quick-task-loop：当前会话直接完成，并给真实验证证据。
3. 非 quick-task-loop：创建 Kanban triage card 给 pmagent，写清验收标准。
4. 涉及 gateway/launchd/deploy/network/proxy/messaging：必须纳入 devopsagent。
5. 涉及 auth/secret/permission/dependency/MCP 安全/外部安装：中高风险时纳入 securityagent。
6. Worker 必须通过 kanban_complete/kanban_block 收尾，不能只口头说完成。
7. 任何构建/运行/验证类任务，都以真实工具输出为交付依据。