Lesson 0002

HiClaw 控制面和声明式资源

这一课把“创建一个 Worker”拆成控制面动作：谁接收请求、谁记录期望状态、谁创建容器或 Pod、谁配置网关、房间和共享存储。

1. 这一课要拿下什么

上一课你已经知道 HiClaw 的核心节点。现在要把视角从“有哪些组件”推进到“一个新 agent 如何被系统创建出来”。

学习目标：听到“创建一个 frontend Worker”时，你能说出控制流经过 Manager、`hiclaw` CLI 或 REST API、Worker 资源、controller reconciler、Gateway/Matrix/MinIO 配置，最后落到 Docker container 或 Kubernetes Pod。

2. 控制面解决什么问题

如果只是本地跑一个 agent，进程启动就够了。但 agent harness 要管理多个可替换、可停止、可恢复、可授权的 agent。控制面就是把“我要一个什么样的 agent”变成“系统里真的存在并可用的 agent”。

没有控制面 有控制面
用户或脚本直接启动进程。 用户、Manager 或 CLI 提交资源声明。
启动参数散落在命令和环境变量里。 runtime、image、model、skills、state 写在资源 spec 中。
进程挂了需要人工判断。 controller 比较期望状态和实际状态，并执行修正。
凭据、房间、文件路径容易手工错配。 controller/reconciler 参与配置 gateway consumer、Matrix room 和 object storage。

3. 四类声明式资源

HiClaw architecture 文档把 `hiclaw.io/v1beta1` 下的主要 CRD 分成四类：Worker、Manager、Team、Human。它们不是普通配置文件，而是控制面要持续实现的“期望状态”。

资源 它描述什么 面试式判断问题
Worker 执行者 agent。重点字段包括 model、runtime、image、skills、MCP servers、expose ports、channelPolicy、state。 这个 Worker 用哪个 runtime？应该 Running、Sleeping 还是 Stopped？需要哪些工具和暴露端口？
Manager 协调者 agent。包含 model、runtime、image、skills、MCP servers、config、state。 Manager 的心跳、worker idle timeout、通知渠道应该由谁配置？
Team 一组带 Leader 和 Workers 的协作单元。包含 Leader、Workers、admin、peerMentions、channelPolicy。 团队房间、Leader DM、成员 readiness 应该如何聚合？
Human 人类参与者。包含 display name、email、permissionLevel、可访问 teams/workers。 谁能进入哪些房间？谁能访问哪些 Worker 或 Team？

4. 创建 Worker 的控制流

把这句话作为主线：“帮我创建一个叫 alice 的 frontend Worker。”

Human says request in Matrix
  -> Manager interprets the intent
  -> Manager chooses Worker spec
  -> hiclaw CLI or REST API sends request to controller
  -> Worker resource becomes desired state
  -> Worker reconciler creates infrastructure
  -> Gateway consumer, Matrix room, storage prefixes are prepared
  -> Docker container or Kubernetes Pod starts
  -> Worker joins the room and receives the task

关键点是：Manager 不应该自己“手搓”所有底层动作。它把意图变成资源请求，controller 负责把资源请求落到运行环境和基础设施配置上。

5. Local 和 Kubernetes 的差异

HiClaw 有两种部署形态，但控制面抽象保持一致。

维度 Local single host Kubernetes
controller 形态 embedded controller container 同时包含 Higress、Tuwunel、MinIO、Element Web 和 controller。 controller 是独立 Deployment，Higress、Tuwunel、MinIO、Element Web 通常是独立工作负载或 chart 依赖。
创建执行体 controller 通过 Docker/Podman API 创建 Manager 和 Worker container。 controller 根据 CR 创建 Manager 和 Worker Pods。
Manager/Worker 镜像 轻量镜像，不再内置完整基础设施栈。 同样是轻量 agent runtime 镜像，基础设施由集群组件提供。
你该记住 本地是便捷体验，infra 被打包到 embedded controller。 Kubernetes 是生产/共享部署，组件边界更清楚。

6. Retrieval Check

先口头回答，再点开答案。目标是能把控制面讲成因果链，而不是背组件名。

  1. 为什么 HiClaw 需要 controller，而不是让 Manager 直接启动 Worker？
  2. Worker spec 至少应该回答哪三类问题？
  3. `hiclaw` CLI 在控制流里扮演什么角色？
  4. Local 模式和 Kubernetes 模式最大的差异是什么？
  5. 如果 Worker 已经声明为 Running，但容器没起来，你应该怀疑哪个层？
  1. 因为 Manager 负责理解和协调任务，controller 负责生命周期、状态收敛、基础设施配置和运行环境差异。
  2. 它用什么运行：runtime/image/model；它能做什么：skills/MCP/expose；它该处于什么状态：Running/Sleeping/Stopped。
  3. 它是 operator-facing 工具，向 controller REST API 发起 create/get/update 等操作，Manager 和 Worker 镜像里也带有它。
  4. Local 把 infra 放进 embedded controller，并通过 Docker/Podman 创建容器；Kubernetes 把组件拆成工作负载，并通过 CR 创建 Pods。
  5. 先看 Worker resource/status、controller reconciler 日志、镜像拉取/运行时、以及 gateway/Matrix/storage 初始化是否失败。

References

主要来源：HiClaw architecture.md、HiClaw README。速查表见 HiClaw 控制面速查。