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 项目GitHub_Trending/mo/iii的 Worker Registry 展开系统讲解如何在 workers.iii.dev 检索可安装的 Worker、通过iii worker add从三类来源安装 Worker以及理解 Worker 的两种发布制品形态。读完本文你将掌握从 Registry 中定位能力、安装并自动启动 Worker、把运行期配置托管给 configuration worker 的完整实操路径并能结合仓库源码理解worker::add的底层安装流程。什么是 iii Worker Registryiii 的 Worker Registry 是可安装 Worker 的索引中心托管在 workers.iii.dev。它是一个面向能力查找的目录每个 Worker 页面都会列出该 Worker 提供的函数functions安装后可通过worker.trigger/iii trigger调用的能力触发器类型trigger types该 Worker 可以绑定的事件类型配置 Schemaconfiguration schema运行期设置的结构化定义JSON Schemaconfiguration worker 会基于它做校验支持的平台supported platforms该 Worker 可在哪些目标平台上运行Agent skills随 Worker 分发的、面向 Agentic 工作流的能力描述。借助这些信息你可以判断某个 Worker 是否满足项目所需的能力再决定是否安装。除官方 Registry 外Worker 也可以发布在Docker 与 OCI 兼容镜像仓库中通过镜像引用直接安装。从源码结构看这套平台与制品模型在引擎侧由 engine/src/cli/registry.rs 中的BinarySpec结构体承载每个二进制制品都声明了supported_targets如aarch64-apple-darwin、x86_64-apple-darwin、x86_64-pc-windows-msvc、aarch64-pc-windows-msvc、x86_64-unknown-linux-gnu、x86_64-unknown-linux-musl、aarch64-unknown-linux-gnu等以及has_checksum是否提供校验和用于下载完整性验证这与文档中原生二进制按平台分发作物的描述一一对应。添加 Worker三种来源iii worker add接受三种来源命令形式如下出自 workers-registry.mdxiii worker add state # 从 iii registry 下载并添加 Worker iii worker add ./workers/my_worker # 添加用 iii worker init 创建的本地 Worker iii worker add ghcr.io/org/worker:tag # 从 Docker 或 OCI 镜像仓库拉取并添加 Worker三种来源在源码中对应crates/iii-worker/src/core/types.rs的WorkerSource枚举Registry接受一个 registry 槽位名slug例如pdfkit可选附带version字段进行 semver 版本固定Oci接受完整的 OCI 引用例如ghcr.io/iii-hq/node:latestLocal接受引擎/守护进程宿主机上的 Worker 项目目录路径该目录必须包含iii.worker.yaml清单清单中可声明name、description、scripts.start必需、scripts.setup、scripts.install、dependencies其他 Worker 名 → semver 范围、resources.cpus默认 2、resources.memory默认 2048 MiB、env与runtime.base_image等字段未知键会在添加时被拒绝。无论从哪个来源安装iii worker add都会把 Worker 写入项目的config.yaml并自动启动。对应测试可参见 crates/iii-worker/tests/local_add_dependencies_integration.rs它端到端覆盖了本地路径添加 依赖解析的场景含依赖不可达时不留下任何状态、无依赖时跳过 registry、依赖可解析时推进到 install 阶段等用例。安装流程的源码视角iii worker add在 worker crate 中的编排入口是 crates/iii-worker/src/core/add.rs 的run()函数。它不直接执行安装而是做输入校验后把任务委托给WorkerHostShim并沿整个生命周期发射事件Started → Stage(downloading) → Stage(downloaded) → Done失败时则发射Failed携带底层错误信息且不会发出downloaded/Done。add.rs的单元测试直接断言了这一事件序列成功时恰好 4 个事件失败时恰好 3 个。值得注意的是add.rs的注释明确说明本地安装不再受触发器面限制worker::add { source: { kind: local, path } }可以通过总线触发——路径在守护进程宿主上解析并运行清单中的 setup/install/start 脚本因此把守护进程暴露给不受信任的 Worker 前需要谨慎评估信任边界。添加选项与行为细节从AddOptionscrates/iii-worker/src/core/types.rs可以看到worker add底层支持的选项及其语义选项含义force安装前删除缓存产物强制重新下载用于从损坏缓存中恢复CLI 侧对应iii worker reinstall name等价于add --forcereset_config重新添加前重置 Worker 在config.yaml中的config:块可与forcetrue组合做一次干净重装yes当解析出的依赖图超过 32 个 Worker 时跳过确认适用于 CI 等非交互环境iii worker add --yes namewait阻塞直到 Worker 报告就绪默认 true在触发器面上安装常会超过总线调用超时如npm install建议wait:false后轮询worker::status即使wait:true超时服务端的安装仍会继续不要盲目重发项目锁会繁忙关于超过 32 个 Worker 需要确认的限制实现位于 crates/iii-worker/src/cli/managed.rs安装前会对整个依赖图做无深度上限的解析与统计当node_count 32时抛出ConsentRequired提示传入yes:true或--yes。安装完成后返回结果AddOutcome会给出解析出的 Worker 名、从iii.lock读取的已安装版本以及状态枚举AddStatusInstalled新装 /AlreadyCurrent已是最新 /Repaired修复 /Replaced替换。安装位置与--host默认情况下iii worker add编辑当前目录下的配置文件因此应在引擎所在目录执行。要向运行在别处的引擎不同目录、不同机器或非默认端口安装使用--hostiii worker add pdfkit --host localhost:49134带--host时 CLI 会调用引擎的worker::add触发器由引擎在自己的项目目录内完成安装当前目录不受影响。如果你在没有config.yaml的目录执行iii worker add命令不会就地创建配置文件而是回退到--host localhost通过本机引擎安装并打印相应提示。添加之后的配置管理安装后 Worker 的设置遵循一次种子、持续托管的生命周期config.yaml中该 Worker 的config:块是引导种子bootstrap seed仅在 Worker 首次启动、注册了配置 Schema 后被读取一次用于创建该 Worker 的配置条目之后运行期设置由configuration worker接管默认启用每次变更都会按该 Worker 注册的 Schema 校验并应用到运行中的 Worker下一次启动时引擎会把已被消费的config:块从config.yaml中移除留下一条指向新位置的注释- name:行及其余内容原样保留。iii worker add默认写出不带config:块的裸- name:条目Worker 以内置默认值启动。你手动在config.yaml中编写config:块依然可以作为首次启动的一次性种子且重新添加 Worker 时该块会被保留iii-sandbox是唯一例外它的config:块必须写入因为镜像白名单是从文件强制执行的。配置托管的具体用法./config/下每 Worker 一个 YAML 文件、文件编辑 / 控制台 /configuration::set三种修改方式、${VAR:default}环境变量模板、热应用与重启级设置等详见 Configuration 文档。更广泛的 Worker 生命周期命令本指南聚焦 Registry 的浏览与添加Worker 的完整生命周期命令集移除、启停、同步、校验等在 Workers 文档 中有完整说明这里列出与 Registry 工作流直接相关的常用命令作为速查iii worker list # 列出 config.yaml 中声明的所有 Worker 及状态 iii worker start name # 启动一个 Worker iii worker stop -y name # 停止一个 Worker-y 跳过确认 iii worker restart name # 停止再启动 iii worker status name # 查看配置、沙箱状态与近期日志 iii worker logs name # 流式查看日志 iii worker exec name -- command # 在 Worker 沙箱内执行命令 iii worker remove -y worker-name # 从 config.yaml 移除并停止进程 iii worker clear -y worker-name # 同时删除下载到磁盘的产物 iii worker update worker-name # 重新解析并回写 iii.lock 版本固定制品类型原生二进制与 OCI 镜像每个 Registry Worker 以两种形态之一发布原生二进制native binary为macOS、Linux、Windows分别提供按平台区分的产物。源码中 engine/src/cli/registry.rs 的BinarySpec通过supported_targets列出了具体支持的目标三元组Apple Silicon / Intel macOS、x86_64 / aarch64 Windows MSVC、x86_64 / aarch64 Linux GNU 与 musl 等并可用has_checksum标识是否附带校验和保证下载完整性。Docker / OCI 兼容镜像单个镜像即可在所有受支持平台上运行通过iii worker add ghcr.io/org/worker:tag这类引用安装。需要留意的是iii worker add的镜像下载来源是远程仓库iii registry 或 OCI registry或本地文件夹不会读取你本地 Docker 守护进程中的镜像——用docker build在本地构建的镜像无法按名字被 iii 找到本地构建的 Docker 镜像仍可像普通镜像一样用docker run运行与测试。版本固定与锁文件Registry Worker 遵循 semver 发布。安装时不带版本号则选取最新版追加version可固定到指定版本iii worker add state1.2.0解析出的版本会记录在项目根目录的iii.lock中并在后续每次安装时回放保证跨机器、跨平台的可复现安装。二进制 Worker 还可以在同一锁文件中为 macOS / Linux / Windows 分别固定平台产物。建议把iii.lock与config.yaml一起提交。与锁文件直接相关的命令iii worker sync # 严格按 iii.lock 安装 iii worker sync --frozen # CI 形态仅校验锁文件不修改本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移iii worker update是第三个锁文件相关命令它把固定版本重新解析到允许的最新版本并回写iii.lock不带参数时更新所有被锁定的 Worker。小结Worker Registry 是 iii 生态中发现能力 → 安装能力 → 托管配置的第一站在 workers.iii.dev 按函数、触发器类型、配置 Schema、平台与 Agent skills 检索 Worker用iii worker add从 registry、本地目录或 OCI 镜像三类来源安装Worker 随即被写入config.yaml并自动启动运行期设置交由 configuration worker 按 Schema 校验托管。安装流程的底层实现WorkerSource三来源解析、worker::add事件编排、依赖图规模确认、iii.lock版本回放都可以在上述源码路径中进一步核对相关生命周期命令与配置管理细节可继续阅读 Workers 与 Configuration 文档。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考