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 为核心，讲解如何浏览注册表、通过iii worker add从三种来源安装 Worker，以及理解注册表 Worker 的制品类型、版本锁定与底层解析机制。读完本文，你将掌握在项目中检索并安装第三方 Worker 的完整流程，并能基于源码理解注册表解析、校验与缓存的具体原理。

浏览注册表（Browsing the registry）

iii 的 Worker Registry 托管在官方站点workers.iii.dev，是可安装 Worker 的索引。可以把注册表理解为"可部署运行时"版的 npm registry：你安装的不是一个库，而是一个完整、可直接运行的 Worker 运行时。

每个 Worker 页面会列出以下信息，用于帮助你在安装前判断它是否满足项目需求：

• 提供的 functions（函数）与 trigger types（触发器类型）：决定安装后你能调用哪些能力、绑定哪些事件；
• configuration schema（配置模式）：安装后需要或可以填写的配置项；
• supported platforms（支持的平台）：该 Worker 制品覆盖哪些操作系统与架构；
• agent skills（Agent 技能）：Worker 附带的、供 Agent 化工作流使用的内容能力。

也就是说，注册表不仅是"下载入口"，更是 Worker 的能力目录——先浏览、比对能力，再用iii worker add把它装进项目。

此外，Worker 也可以发布在 Docker 与 OCI 兼容的镜像仓库中，通过镜像引用直接安装（见下文"添加 Worker"）。

从源码结构看，注册表 Worker 的"函数 / 触发器 / 配置 / 技能"信息对应到仓库中 registry.rs 解析的ResolvedWorker结构：binaries（各平台二进制制品）、archive_url/sha256（bundle 制品的归档与摘要）、config（Worker 自带的默认配置），这些字段正是"worker 页面信息"在解析层的落点。

添加 Worker（Adding a worker）

iii worker add接受三种来源，在所有情况下，Worker 都会被写入项目的config.yaml并自动启动：

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（容器镜像引用）

三种来源分别对应：

三种来源在源码中如何区分

从源码结构看，来源的判定逻辑位于 edit.rs 的parse_worker：首字符是.或/即为本地路径，其余一律视为注册表引用。因为注册表引用本身可能带主机名（如api.workers.iii.dev/state）或作用域（如team/worker），所以"是否含斜杠"不能作为判断依据——这是路径与包引用最关键的区分点：

• state→ 解析为api.workers.iii.dev/state（默认注册表主机，见 edit.rs 中的DEFAULT_REGISTRY_HOST）；
• name@version→ 从最右侧@切分出版本号，例如iii-state@1.2.0；
• ./workers/api→ 本地路径，容器键取路径最后一段目录名api。

写入config.yaml时，注册表引用会被记录为worker: package://api.workers.iii.dev/state、version: "1.2.0"的形式，并附带# added by compose::add标记（见 edit.rs）；文件按文本拼接方式编辑，保留你原有的注释、空行与引号风格，不会因序列化往返而丢失。

安装后的自动启动

安装完成后 Worker 会被自动启动。iii worker add默认最多等待 120 秒等待 Worker 向引擎报告就绪；超时后命令返回 shell，但 Worker 会继续启动。之后可用iii worker status <name>继续观察启动过程，用iii worker logs <name>查看日志。

制品类型（Artifact types）

注册表里的每个 Worker 都以两种形态之一发布：

1. 原生二进制（native binary）：按平台分别发布制品，覆盖 macOS、Linux 与 Windows。安装时会根据当前主机选择对应的平台制品；
2. Docker / OCI 兼容镜像（Docker / OCI compatible image）：可在所有受支持平台上运行，不区分平台制品。

平台制品的底层选择逻辑

从源码看，平台选择由 registry.rs 的host_target()函数完成：它通过编译期cfg!判断当前运行环境，返回诸如x86_64-unknown-linux-gnu、aarch64-apple-darwin、x86_64-pc-windows-msvc之类的 target triple。由于 compose 守护进程与其子进程运行在同一台机器上，因此守护进程的 target 就是子进程需要运行的 target，无需运行时探测。

原生二进制制品按name-version-target-sha256摘要目录名缓存；若解析结果中没有当前平台的binaries条目，安装会在下载前直接失败并列出可用平台（UnsupportedPlatform错误），避免浪费带宽。

版本管理与锁定（Versioning and pinning）

注册表 Worker 按semver 语义化版本发布。安装时不带版本号则选取最新发布版本；用@<version>追加在注册表名称后即可锁定某个具体版本：

iii worker add iii-state@1.2.0

锁定的版本会记录在项目根目录的iii.lock中，并在之后的每次安装中回放，从而保证跨机器、跨平台的可复现安装。二进制 Worker 可以在同一份 lockfile 中按平台（macOS / Linux / Windows）分别锁定制品。仓库中的 engine/iii.lock 就是一个真实示例：

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

升级与回滚

• iii worker update：重新解析iii.lock中锁定的 Worker 到最新允许版本并回写 lockfile；带 Worker 名则只更新一个，省略则更新全部；
• 修改锁定版本等同于请求升级或回滚：对已存在的同容器条目，compose::add会就地替换version:字段，同时保留该条目中你手写的其他字段（如env_file、config_name），不会因为升级丢失凭据配置。

锁文件相关命令

与iii.lock直接相关的三条命令：

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

注册表解析的底层原理：Resolve → Verify → Cache

安装一个注册表 Worker 时，底层走的是"解析、校验、缓存"三步流水线，全部实现在 registry.rs：

1. Resolve（解析）：compose 向注册表发送POST /resolve请求，携带worker名称、version范围与target平台，注册表返回该 Worker 及其完整依赖图的 URL 与 SHA-256 摘要。解析请求最多重试 3 次（每次 20 秒超时、间隔 250ms 递增），只对瞬时故障（5xx、请求超时、429）重试，客户端错误直接返回——测试resolve_retries_a_transient_server_failure与resolve_does_not_retry_a_client_error分别验证了这两种行为；
2. Verify（校验）：任何归档在写入磁盘前都要先做 SHA-256 摘要比对。下载内容与注册表承诺的摘要不一致时，不会被当作"慢下载"或"损坏下载"处理，而是被视为与注册表承诺不同的制品，直接拒绝落盘（PackageDigestMismatch错误）。bundle 制品如果缺少archive_url + sha256配对，同样拒绝安装；
3. Cache（缓存）：安装目录以"包元数据 + target + SHA-256"为键，因此只有经过校验的精确制品才会在多个注册表与多个项目之间复用。第二次安装同一版本时直接命中缓存（InstallStatus::Cached），不再触碰网络——测试a_second_install_reuses_the_downloaded_artefact验证了这一点；而同名同版本但摘要不同的制品会被视为不同制品而重新下载（测试same_name_and_version_with_a_different_digest_is_downloaded_again）。

下载与解压采用"先解压到带 UUID 的 staging 目录、校验通过后 rename 发布"的策略：中途崩溃不会留下被误判为缓存命中的半解压目录；两个容器并发安装同一制品时，后到者发现目标目录已就绪便直接复用对方的（其校验已通过），不会破坏正在执行的目录。

更多iii worker子命令

除add外，iii worker命令集还覆盖 Worker 的完整生命周期（详见 workers.mdx 与 app.rs）：

iii worker list # 列出 config.yaml 中声明的全部 Worker 及状态 iii worker start <name> # 启动一个 Worker（默认等待 120s 就绪） iii worker stop -y <name> # 停止一个 Worker iii worker restart <name> # 先停后启 iii worker status <name> # 查看配置、沙箱状态与近期日志 iii worker logs <name> # 流式查看 Worker 日志 iii worker exec <name> -- <command> # 在 Worker 的沙箱/VM 内执行命令 iii worker remove -y <name> # 从 config.yaml 移除并让引擎回收运行进程 iii worker clear -y <name> # 删除磁盘上的下载制品（省略名称则清空全部）

移除后下载的制品仍留在磁盘上（默认位于~/.iii/managed/{name}/），需要彻底清理时再用iii worker clear；iii worker reinstall <name>等价于add --force，用于强制重新下载。

小结

iii Worker Registry 是"可安装运行时"的索引：在workers.iii.dev浏览能力，用iii worker add从注册表名称、本地路径或 OCI 镜像三种来源安装，靠 semver 加iii.lock锁定版本，以原生二进制或 OCI 镜像两种制品形态跨平台交付。底层则由 registry.rs 的"解析 → 校验 → 缓存"三步流水线保障安装的确定性、完整性与可复现性——这正是 Worker 能像依赖包一样被安装、更新与回滚的基石。

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