iii Worker Registry 完全指南：浏览、安装与管理可插拔 Worker

iii Worker Registry 完全指南：浏览、安装与管理可插拔 Worker

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii

导读

本指南围绕 iii 项目的Worker Registry（Worker 注册表）展开，它是 iii 生态中可安装 Worker 的中央索引：开发者可以像管理 npm 包一样，通过iii worker add一条命令把某个独立、可部署的运行时能力装进自己的项目。读完本文，你将掌握如何在注册表中定位满足需求的 Worker、用三种来源（注册表名称、本地路径、Docker/OCI 镜像）安装 Worker、理解其二进制与镜像两种制品形态，并学会配合版本锁定与iii.lock实现可复现安装。

本文以 docs/0-17-0/using-iii/workers-registry.mdx 为核心骨架，并结合 docs/0-17-0/using-iii/workers.mdx 以及 iii-compose 的源码实现展开。

什么是 iii Worker Registry

在 iii 中，任何新增功能都以Worker的形式出现。Worker 可以理解为 iii 版本的"自包含、隔离的服务"——它与传统服务不同之处在于：使用 Worker不需要任何集成代码，只需要安装和管理，就像 npm 包一样，区别是你拿到的是完整的可部署运行时，而非一个库。

Worker Registry就是这个"包管理器"的中央仓库。它托管在workers.iii.dev（项目文档中的官方索引站点），是可安装 Worker 的索引。每个 Worker 的独立页面会列出：

• 该 Worker 提供的functions（函数）与trigger types（触发器类型）；
• 它的configuration schema（配置结构），方便你了解需要配置哪些字段；
• supported platforms（支持的平台）；
• agent skills（代理技能），即该 Worker 为 Agent 工作流附带的能力描述。

利用这些信息，你可以精准定位一个能满足项目某方面能力的 Worker。除了官方注册表，Worker 也可以在Docker 与 OCI 兼容注册表中找到，这对应了下文三种添加来源中的镜像方式。

添加 Worker：一条命令，三种来源

iii worker add是接入 Worker 的唯一入口，它接受三种来源。无论哪种来源，Worker 都会被写入项目的config.yaml（或 compose 配置）并自动启动：

iii worker add iii-state # registry name（注册表名称） iii worker add ./workers/my-worker # local path（本地路径） iii worker add ghcr.io/org/worker:tag # Docker or OCI image（容器镜像）

从源码实现看，iii worker add的解析逻辑位于 crates/iii-compose/src/edit.rs：Worker 来源被建模为Source枚举，其中注册表 Worker 对应Source::Package { reference, version }变体，且version在解析之前为None。判断来源的关键在首个字符：

• 以.或/开头的是本地路径；
• 其余一律视为注册表引用——它可能带主机名（如api.workers.iii.dev/state）或作用域，因此"是否包含斜杠"不能作为区分目录的依据。

使用前提

在添加 Worker 之前，需要先确保 iii 已 安装 并 运行引擎。若只想临时起一个 iii 实例做测试，可以运行iii --use-default-config（见 默认配置）。

制品类型：二进制与镜像

注册表中的每个 Worker 以两种制品形态之一发布：

1. 原生二进制（native binary）：针对macOS、Linux、Windows分别提供对应平台的制品（per-platform artifacts），安装时按当前平台拉取对应文件；
2. Docker / OCI 兼容镜像（Docker / OCI compatible image）：一份镜像可在所有受支持平台上运行，适合对跨平台一致性要求更高的场景。

这一区分同样反映在安装结果中：二进制 Worker 可以在同一份iii.lock中为不同平台分别锁定制品（详见下文"版本与锁定"）。

源码中的解析、验证与缓存

iii worker add解析注册表 Worker 的底层逻辑在 crates/iii-compose/src/registry.rs，其文档注释明确将流程概括为三步，这也是整个注册表机制的核心原理：

1. Resolve（解析）：注册表被询问"哪个精确版本满足当前主机目标所声明的版本范围"，并返回 URL 与 digest（摘要）。POST /resolve的响应包含解析出的 Worker 列表以及依赖图边（edges）——因为两个 Worker 可能依赖同一个共享 Worker，所以这是一张图而不是一棵树。默认注册表地址定义在同文件常量中：DEFAULT_REGISTRY = "https://api.workers.iii.dev"，当package://引用未指定主机时即使用它。
2. Verify（校验）：归档在写入任何会被进程执行的位置之前先做哈希校验。下载内容与摘要不匹配，不是"慢下载"或"损坏"，而是"与注册表承诺不同的制品"，它永远不会落到磁盘上。解析过程本身也带有容错设计：解析尝试 3 次、每次超时 20 秒、重试间隔 250ms，下载则有独立的 300 秒预算。
3. Cache（缓存）：安装以包元数据 + 目标平台 + SHA-256为键缓存，因此只有被精确验证过的制品才会在多个注册表和多个项目间复用。

此外，解析响应中的ResolvedWorker还包含binaries（各平台制品及各自的sha256/url）、archive_url（bundle 镜像形态的统一归档）、sha256以及config（Worker 自带默认配置，若有）等字段。

版本与锁定：可复现安装的基石

注册表 Worker 按semver（语义化版本）发布。关于版本如何选取、如何用@<version>固定、如何更新以及如何记录在iii.lock中，详见 Workers 页面的 Versioning and pinning 与 Updating a worker。

版本固定（Version pins）

• 不指定版本安装时，默认选取最新发布版（latest release）；
• 在注册表名称后追加@<version>可以固定某个具体版本，而不是跟随最新：

iii worker add iii-state@1.2.0

这个 pin 会被记录进iii.lock，并在之后每次安装时重放（replay），保证换台机器、换个平台安装结果一致。

锁文件 iii.lock

iii.lock是位于项目根目录的 YAML 文件，它为每个受管 Worker 固定具体版本与来源，从而让同一组 Worker 在不同机器和平台上以相同方式安装。二进制 Worker 甚至可以在同一份锁文件里为 macOS、Linux、Windows 分别固定平台制品。

version: 1 workers: iii-http: version: 0.13.0-next.1 type: engine dependencies: {}

（以上为仓库内 engine/iii.lock 的实际片段。）

请将iii.lock与config.yaml一起提交到版本控制，以获得可复现安装。直接操作锁文件的命令有三个：

iii worker sync # 完全按照 iii.lock 安装 worker iii worker sync --frozen # CI 形态：校验锁文件而不改动本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移（drift）

第三个与锁文件相关的命令是iii worker update：它会将 pin 重新解析到最新允许的版本，并写回iii.lock。

管理 Worker 的完整命令集

围绕 Worker 的完整生命周期，iii worker子命令覆盖了：在注册表中寻找新 Worker、将其安装进config.yaml与iii.lock、控制其运行状态、查看日志，以及不再需要时移除。以下命令来自 Workers 页面的 Managing workers 章节。

列出与增删

iii worker list # 列出 config.yaml 中声明的所有 worker 及当前状态 iii worker reinstall <name> # 强制重新下载已存在的 worker（等价于 add --force） iii worker remove -y <worker-name> # 从 config.yaml 移除并停止运行进程（-y 跳过运行中确认） iii worker clear -y <worker-name> # 同时删除磁盘上已下载的制品；省略名称则清理全部

启停与重启

添加的 Worker 会随引擎自动启动。如需手动控制，使用start、stop、restart：

iii worker start <name> # 启动单个 worker iii worker stop -y <name> # 停止单个 worker（-y 跳过确认提示） iii worker restart <name> # 先停后启

状态、日志与沙箱执行

iii worker status <name> # 配置、沙箱状态、近期日志 iii worker logs <name> # 流式查看 worker 日志 iii worker exec <name> -- <command> # 在 worker 沙箱内执行命令

更新 Worker

iii worker update <worker-name> # 更新单个 worker iii worker update # 更新所有已锁定的 worker

iii worker update会重新解析已锁定的 Worker 并把新 pin 写回iii.lock。

从配置到运行：仓库中的落地示例

compose 配置中的 Worker 声明

在仓库的 engine/worker-compose.yaml 中可以看到 Worker 在 compose 文件里的实际声明形态：每个容器条目通过worker: package://api.workers.iii.dev/<name>指定注册表来源，并附上version、config_name与config_override：

containers: state: worker: package://api.workers.iii.dev/state version: "0.22.2" config_name: state config_override: adapter: name: kv config: store_method: file_based file_path: ./data/state_store.db http: worker: package://api.workers.iii.dev/http version: "0.21.3" config_name: http config_override: port: 3111 host: 127.0.0.1 default_timeout: 30000 concurrency_request_limit: 1024 cors: allowed_origins: - http://localhost:3000 - http://localhost:5173

注意package://api.workers.iii.dev/state这种引用格式——主机名显式出现时，解析会定向到该注册表；省略主机时则回落到默认注册表常量。这也印证了"本地路径以.//开头、其余视为注册表引用"的解析规则。另一方面，引擎自身的生命周期 Worker 则记录在 engine/config.yaml 的workers:段（如iii-stream、configuration），项目级 Worker（http、state、cron、queue、pubsub、bridge）属于worker-compose.yaml。

生命周期语义

Worker 通过WebSocket连接 iii：当 Worker 连接成功，它便对整个 iii 系统及系统内其他 Worker 可见；当它断开连接，其 functions 与 triggers 将停止可调用，直到重连。functions 和 triggers 全部来自已连接的 Worker——例如通过 iii-http Worker 添加http触发器后，你就能像在 Express 或 FastAPI 这类 Web 框架中一样为函数暴露端点。

移除与清理的边界

iii worker remove将 Worker 从config.yaml中移除，引擎随之拆除正在运行的 Worker 进程；但已下载的制品仍保留在磁盘上。需要连制品一起删除时，使用iii worker clear。省略名称可清除所有 Worker 的制品。这两个命令当前都需要-y跳过交互确认（源码注释标明未来计划将其改为非交互模式）。

Worker Skills：为 Agent 工作流准备的能力

除了可执行能力，每个 Worker 还随附面向Agentic 工作的 skills（技能）。skills 由skillsWorker 管理——它是一个仍在积极开发的内容注册型 Worker，和普通 Worker 一样通过iii worker add加入项目。技能正文采用懒加载：顶层条目保持精简，Agent 仅在某个函数引用解析到具体内容时，才通过iii://<worker>/<leaf>这样的 section URI 拉取更深层内容。项目还随附高层级 skills，使任何 Agent 都能立刻上手使用 iii 及其 Worker。

小结

Worker Registry 是 iii "像管理 npm 包一样管理服务运行时"这一设计的关键一环：浏览注册表（functions、triggers、配置 schema、平台、skills）→ 选择来源（注册表名、本地路径、镜像）→ 添加并自动运行 → 用@版本与iii.lock锁定可复现环境 → 用sync/verify/update维护锁文件。底层 registry.rs 的"解析—校验—缓存"三步机制，以及 edit.rs 的来源解析规则，为这一体验提供了安全、可复现的工程保障。

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii