Lesson 0001

把 HiClaw 看成 Agent Harness

这一课的目标不是记住所有组件，而是建立一个判断框架：HiClaw 解决的是多 agent 如何被创建、协作、隔离、观察和人工干预。

1. 一句话模型

HiClaw 是一个 collaborative multi-agent runtime platform：Manager 在可见的 Matrix 房间里协调多个 Worker，Worker 在隔离的 runtime 中执行任务，controller、gateway 和 object storage 提供控制、安全和共享状态。

今天先记住：agent harness 不是更聪明的 prompt，而是让 agent 可以被安全、可见、可恢复地运行起来的系统外壳。

2. 六个核心节点

Human

人在 Matrix 房间里发起任务、观察过程、纠偏和终止。

Manager

把人的意图转成任务计划，创建或指挥 Workers。

Worker

执行具体任务。不同 Worker 可以使用不同 runtime。

Controller

控制平面，把 Worker、Team、Human 等声明变成实际资源。

Higress

AI/API 网关，集中处理 LLM、MCP 和真实凭据。

MinIO

共享对象存储，让 Manager 和 Workers 交换文件与产物。

3. 三条流

消息流:
Human -> Matrix room -> Manager -> Matrix room -> Worker

控制流:
Manager / CLI -> hiclaw-controller -> Docker containers or Kubernetes Pods

执行流:
Worker -> Higress -> LLM / MCP / APIs
Worker <-> MinIO <-> Manager

很多 agent demo 只有第一条的一部分：用户给 agent 发消息，agent 调工具。HiClaw 真正值得学的是后两条：谁创建 Worker，谁保管凭据，谁保存中间产物，谁允许人介入。

4. 为什么这是 Harness

问题 普通 agent app HiClaw 式 harness
多 agent 协作 通常写死在代码里 Manager、Worker、Team 和 Matrix 房间共同表达
凭据安全 agent 常直接持有 API key Worker 只拿 consumer token，真实凭据在 Higress
状态共享 塞进上下文或本地文件 共享对象存储承载工作区和产物
人工干预 靠额外 UI 或日志 每个房间天然可见、可插话、可审计
生命周期 进程启动后自己跑 controller 负责创建、更新、停止和恢复

5. Retrieval Check

先别看答案，口头回答这 5 个问题。检索比重读更能建立长期记忆。

  1. HiClaw 里谁负责把人的意图拆给多个 Worker？
  2. Worker 为什么不应该直接拿真实 LLM API key？
  3. Matrix room 在这个系统里不只是聊天，它还承担什么职责？
  4. MinIO 解决的是 token 问题、文件问题，还是权限问题？
  5. 如果要创建一个 Worker，控制流大概经过哪些组件？
  1. Manager。
  2. 真实凭据应由 Higress 等网关集中保管，Worker 只拿受限 consumer token，这样 Worker 被攻破时损失边界更小。
  3. 它承载可见协作、审计轨迹和 human-in-the-loop 干预。
  4. 主要是文件和共享状态问题，也间接减少把大内容塞进上下文带来的 token 消耗。
  5. 人的请求进入 Matrix，Manager 理解决策，调用 controller 或 CLI，controller 创建 Docker 容器或 Kubernetes Pod。

6. 课后 10 分钟动作

打开 HiClaw README，只读 Key Features、How It Works、Architecture 三段。读完后用自己的话补全这句话：

HiClaw 的 agent harness 最小闭环是：
人通过 ______ 发任务；
______ 负责任务协调；
______ 执行任务；
______ 负责生命周期；
______ 负责凭据隔离；
______ 负责共享文件。

卡住时直接问我。下一节我们会拆控制面：为什么 agent harness 需要 controller 和声明式资源。

References

主要来源：HiClaw README、HiClaw architecture.md。术语速查见 Agent Harness 术语速查。