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 Registry 是什么、如何用iii worker add从三种来源（注册表名称、本地路径、Docker/OCI 镜像）安装 worker，以及 worker 的制品类型与版本固定机制。结合 iii 仓库中iii-workerCLI 的实际解析源码，本文进一步还原iii worker add背后的注册表解析、依赖图下载与iii.lock锁文件流程，使你在完成 worker 安装实操的同时，能够理解每一步命令在引擎内真实发生的事。

一、什么是 iii Worker Registry

iii 的 Worker Registry（注册表地址为 workers.iii.dev，是外部站点，此处仅作名词说明）是全部可安装 worker 的索引。每个 worker 的页面会列出以下关键信息：

该 worker 提供的functions（可被触发调用的函数）与trigger types（触发器类型）；
该 worker 的配置 schema（配置字段的结构与取值）；
支持的平台（macOS / Linux / Windows 等）；
随 worker 附带的agent skills（供 AI Agent 使用的技能条目）。

实际使用时的检索思路是：先明确项目需要的一种能力（例如 HTTP 端点、队列、状态存储），再到注册表页面中按“函数 / 触发器 / 配置”三要素定位满足该能力的 worker。

除了官方注册表，worker 还可以发布在Docker 与 OCI 兼容的镜像仓库中——这直接对应后文iii worker add的第三种来源。CLI 源码中同样内置了注册表地址作为引导信息，见 engine/src/trigger.rs。

二、`iii worker add`：三种 worker 来源

iii worker add接受三种来源。在所有情况下，worker 都会被写入项目根目录的config.yaml并自动启动，无需手动配置启动项：

iii worker add iii-state # 来源 1：注册表名称 iii worker add ./workers/my-worker # 来源 2：本地路径 iii worker add ghcr.io/org/worker:tag # 来源 3：Docker 或 OCI 镜像

三种来源的含义：

来源	适用场景	解析行为（结合源码可确认）
注册表名称	使用官方/社区发布的现成 worker	调用注册表 API 解析出制品类型、版本与下载地址，见下文“注册表解析机制”
本地路径	自研 worker 的开发调试	以目录形式接入，走本地 worker 安装通道（相关实现位于 crates/iii-worker/src/cli/local_worker.rs）
Docker/OCI 镜像	自托管或第三方镜像仓库中发布的 worker	解析镜像引用（参考 crates/iii-worker/src/cli/oci_ref.rs），在任何受支持平台上以镜像方式运行

一个真实可参考的配置形态来自引擎内置的queueworker 文档：通过package://协议 URL 从注册表解析 worker，并显式写死version字段，见 engine/src/workers/queue/README.md：

containers: queue: worker: package://api.workers.iii.dev/queue version: "0.21.5" config_name: queue

版本固定（pinning）与更新

注册表中的 worker 以semver 版本号发布。不指定版本时安装最新发布版；在名称后附加@<version>可固定特定版本：

iii worker add iii-state@1.2.0 # 固定到 1.2.0

name@version的拆分在源码中由parse_worker_input完成——以第一个@为界切分为名称与版本两部分，不带@则版本为None（取最新），见 crates/iii-worker/src/cli/registry.rs。

固定下来的版本会记录进项目根目录的iii.lock锁文件，之后每次安装都按锁文件回放，保证同一 iii 系统部署在不同机器上可复现。更新则用iii worker update <name>（单个）或iii worker update（全部锁定 worker）重新解析并回写iii.lock。更多版本与更新细节见 docs/0-12-0/using-iii/workers.mdx 中的“Versioning and pinning”与“Updating a worker”小节。

其他相关子命令速查

完整的iii worker子命令集（start / stop / restart / remove / clear / sync / verify 等）在 docs/0-12-0/using-iii/workers.mdx 有完整说明，与注册表安装流程直接相关的几条：

iii worker reinstall <name> # 强制重新下载（等价于 add --force） iii worker remove <worker-name> # 从 config.yaml 移除并停止进程 iii worker sync # 严格按 iii.lock 安装 iii worker sync --frozen # CI 形态：只校验锁文件，不修改本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移

三、制品类型：文档口径与源码中的完整枚举

原文档的口径是：每个注册表 worker 以原生二进制（按 macOS、Linux、Windows 提供各平台制品）或Docker/OCI 兼容镜像（运行于所有受支持平台）两种方式之一发布。

从源码结构看，CLI 实际识别的制品类型比文档口径更细。WorkerInfoResponse是一个按type字段区分的四元枚举，见 crates/iii-worker/src/cli/registry.rs：

#[serde(tag = "type")] pub enum WorkerInfoResponse { #[serde(rename = "binary")] Binary(BinaryWorkerResponse), // 原生二进制：各平台 URL + sha256 #[serde(rename = "image")] Oci(OciWorkerResponse), // OCI/Docker 镜像：image_url #[serde(rename = "engine")] Engine(EngineWorkerResponse), // 引擎内置 worker：仅名称与版本 #[serde(rename = "bundle")] Bundle(BundleWorkerResponse), // 打包目录：tar.gz 归档 + sha256 }

各类型的载荷字段与安装行为（均以源码注释为准）：

binary：binaries为“平台 → {url, sha256}”的映射，下载后按 sha256 校验；
image：只有image_url，跨平台统一运行；
engine：随 iii 引擎本体发布的内置 worker，无需下载制品；
bundle：打包好的 local-worker 目录 tar.gz 归档，归档根必须包含iii.worker.yaml，引擎下载、校验 sha256、原子解压后通过 libkrun 沙箱运行，见 crates/iii-worker/src/cli/registry.rs 的注释。

引擎自身维护的iii.lock就是一个 engine 类型的真实样例，见 engine/iii.lock：

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

二进制工件的平台覆盖

“按平台提供制品”这一点在引擎的托管二进制注册表中可直接验证。engine/src/cli/registry.rs 中的REGISTRY静态表为每个托管二进制声明了supported_targets，覆盖aarch64-apple-darwin、x86_64-apple-darwin、x86_64-unknown-linux-gnu、x86_64-unknown-linux-musl、aarch64-unknown-linux-gnu及 Windows MSVC 目标；has_checksum: true表明各平台制品均附校验和。该表中的iii-worker条目把iii worker子命令整体映射到独立二进制（CommandMapping { cli_command: "worker" }），说明iii worker add的执行体是随 iii 分发、按需解析平台制品的iii-worker程序。

四、`iii worker add <名称>`的注册表解析机制

当来源是注册表名称时，CLI 端有一个完整的“解析 → 校验 → 下载 → 写锁”流水线，核心在 crates/iii-worker/src/cli/registry.rs。

1. 端点与安全边界。默认 API 基址为https://api.workers.iii.dev（registry.rs#L15），可通过环境变量III_API_URL覆盖；仅调试构建支持file://指向本地 fixture 文件，用于离线/测试场景（registry.rs#L190-L219）。注册表 JSON 响应有 1 MiB 的大小上限（MAX_REGISTRY_RESPONSE_BYTES），目的是在依赖安全检查与下载字节上限生效之前，先防止不可信注册表造成无界内存分配（registry.rs#L16-L22）。

2. 名称校验。worker 名称只允许字母、数字、短横线、下划线和点，且禁止以.开头、禁止..。源码注释解释了原因：bundle 安装根目录保留.locks、.staging两个内部控制目录，以点开头的 worker 名会在磁盘上遮蔽它们，因此直接拒绝（registry.rs#L170-L179）。

3. 版本查询参数。请求形如GET /download/{name}；带版本时附加?version=<v>；在 CI 环境（探测GITHUB_ACTIONS、CI、JENKINS_URL等标准变量）中附加ci=true，见with_download_query（registry.rs#L54-L64）。

4. 依赖图解析。单个 worker 不是孤立下载的。解析结果ResolvedWorkerGraph包含根节点（root）、按版本解析出的 worker 列表（graph，每项含名称、类型、版本、制品地址、依赖映射）与依赖边（edges，含语义化版本范围range），见 registry.rs#L128-L168。这意味着执行iii worker add iii-state时，该 worker 声明的依赖会被一并解析安装；对 bundle 类型，锁文件路径强制要求archive_url与sha256同时存在，防止安装退化为不可校验的拉取（registry.rs#L141-L150）。

5. 锁文件落盘。解析结果最终写入项目根目录的iii.lock。锁文件模块维护一个 format version（当前version: 1），写入采用“相邻临时文件 + 原子替换”，避免半写文件；读取时执行validate()，不支持的 format 版本会被直接拒绝。相关实现与测试见 crates/iii-worker/src/cli/lockfile.rs，测试覆盖了往返序列化、版本校验（拒绝version: 2）、原子写入不留临时文件等场景（lockfile.rs#L678-L800）。

由此可以把文档中的一句话——“worker 被加入config.yaml并自动启动”——展开为完整链路：

iii worker add iii-state@1.2.0 → parse_worker_input 拆分名称/版本 → validate_worker_name 名称校验 → GET https://api.workers.iii.dev/download/iii-state?version=1.2.0 → 按 type 解析制品（binary/image/engine/bundle） → 展开依赖图（graph + edges），下载并校验 sha256 → 写入/更新 config.yaml，落盘 iii.lock → 引擎启动该 worker，WebSocket 连上后可见其函数与触发器

worker 通过 WebSocket 连上引擎后即可被整个系统与所有其他 worker 发现；断连后其函数与触发器停止可调用，直至重连，见 docs/0-12-0/using-iii/workers.mdx 的“Worker lifecycle”一节。

五、实操建议与适用范围

可复现部署：把iii.lock与config.yaml一起提交到版本库；CI 流水线使用iii worker sync --frozen校验而不改写文件。
版本策略：开发期可不带版本跟随最新；生产环境用@<version>固定，升级走iii worker update，变更集中体现在iii.lockdiff 中。
来源选择：官方/社区能力优先注册表名称；本地迭代用路径来源；私有仓库或自托管发行用 OCI 镜像引用。
平台前提：binary 制品受各 worker 声明的平台目标约束（Linux gnu/musl、macOS aarch64/x86_64 等，可参照 engine/src/cli/registry.rs 的目标清单）；跨平台一致性要求高的场景可优先选 image 制品。
适用版本说明：本文基于 iii 仓库 0.12.0 文档目录（docs/0-12-0/using-iii/workers-registry.mdx）与当前iii-workerCLI 源码撰写；原文档中标注的“LLM 浏览注册表”能力尚在 skills worker 中待稳定，暂不作为可用特性描述。

iii Worker Registry：三种 Worker 安装来源、制品类型与源码级解析机制