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 RegistryWorker 注册表展开它是 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.rsWorker 来源被建模为Source枚举其中注册表 Worker 对应Source::Package { reference, version }变体且version在解析之前为None。判断来源的关键在首个字符以.或/开头的是本地路径其余一律视为注册表引用——它可能带主机名如api.workers.iii.dev/state或作用域因此是否包含斜杠不能作为区分目录的依据。使用前提在添加 Worker 之前需要先确保 iii 已 安装 并 运行引擎。若只想临时起一个 iii 实例做测试可以运行iii --use-default-config见 默认配置。制品类型二进制与镜像注册表中的每个 Worker 以两种制品形态之一发布原生二进制native binary针对macOS、Linux、Windows分别提供对应平台的制品per-platform artifacts安装时按当前平台拉取对应文件Docker / OCI 兼容镜像Docker / OCI compatible image一份镜像可在所有受支持平台上运行适合对跨平台一致性要求更高的场景。这一区分同样反映在安装结果中二进制 Worker 可以在同一份iii.lock中为不同平台分别锁定制品详见下文版本与锁定。源码中的解析、验证与缓存iii worker add解析注册表 Worker 的底层逻辑在 crates/iii-compose/src/registry.rs其文档注释明确将流程概括为三步这也是整个注册表机制的核心原理Resolve解析注册表被询问哪个精确版本满足当前主机目标所声明的版本范围并返回 URL 与 digest摘要。POST /resolve的响应包含解析出的 Worker 列表以及依赖图边edges——因为两个 Worker 可能依赖同一个共享 Worker所以这是一张图而不是一棵树。默认注册表地址定义在同文件常量中DEFAULT_REGISTRY https://api.workers.iii.dev当package://引用未指定主机时即使用它。Verify校验归档在写入任何会被进程执行的位置之前先做哈希校验。下载内容与摘要不匹配不是慢下载或损坏而是与注册表承诺不同的制品它永远不会落到磁盘上。解析过程本身也带有容错设计解析尝试 3 次、每次超时 20 秒、重试间隔 250ms下载则有独立的 300 秒预算。Cache缓存安装以包元数据 目标平台 SHA-256为键缓存因此只有被精确验证过的制品才会在多个注册表和多个项目间复用。此外解析响应中的ResolvedWorker还包含binaries各平台制品及各自的sha256/url、archive_urlbundle 镜像形态的统一归档、sha256以及configWorker 自带默认配置若有等字段。版本与锁定可复现安装的基石注册表 Worker 按semver语义化版本发布。关于版本如何选取、如何用version固定、如何更新以及如何记录在iii.lock中详见 Workers 页面的 Versioning and pinning 与 Updating a worker。版本固定Version pins不指定版本安装时默认选取最新发布版latest release在注册表名称后追加version可以固定某个具体版本而不是跟随最新iii worker add iii-state1.2.0这个 pin 会被记录进iii.lock并在之后每次安装时重放replay保证换台机器、换个平台安装结果一致。锁文件 iii.lockiii.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、restartiii 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 沙箱内执行命令更新 Workeriii worker update worker-name # 更新单个 worker iii worker update # 更新所有已锁定的 workeriii 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_overridecontainers: 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项目级 Workerhttp、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考