iii Worker 生命周期与 CLI 管理实战安装、运维、版本锁定与 Agent 技能【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本指南围绕 iii 项目的 WorkerWorker展开Worker 是 iii 中自包含、可独立部署的运行时单元通过 WebSocket 连接引擎并对外提供函数与触发器。你将掌握iii worker子命令的完整用法——从注册表发现、安装、启停、检查到移除理解iii.lock锁文件的版本固定机制与sync/verify的漂移校验流程并了解 Worker 内置的 Agent 技能Skills如何被按需加载。Worker 是什么像服务一样自包含的运行时该页完整版 workers.mdx 开头用一个比喻概括了 Worker 的定位Worker 可以理解为 iii 版本的服务——自包含、隔离、且能与系统中其他 Worker 自由互操作。任何时候你要向项目添加新功能功能都会以 Worker 的形式到来。Worker 与传统服务的核心差异在于使用无需任何集成Worker 可以像 npm 包一样通过iii worker add安装和管理但安装得到的不是库而是完整的、可部署的运行时complete deployable runtimes开箱即用。这一设计在源码中得到印证。engine/src/workers/config.rs 中的WorkerEntry只有三个字段name、可选的imageOCI 镜像引用设置为它即表示外部 Worker与可选的configYAML 配置块WorkerRegistry同文件 L324-L326以工厂函数统一注册所有内置与外置 Worker。Workertrait 定义了initialize、start_background_tasks、destroy、is_alive、register_functions等生命周期钩子其中is_external_process()返回true的 Worker 由引擎以独立进程方式托管如iii-sandbox。Worker 生命周期WebSocket 连接即上线Worker 通过WebSocket连接 iii 引擎Worker 连接成功后它对整个 iii 系统以及系统中的每一个其他 Worker立即可见当 Worker 断开连接时它的函数和触发器停止可调用直到它重新连接。源码层面engine/src/worker_connections/mod.rs 定义了WorkerConnectionStatus::Connected与Disconnected两种连接状态并记录连接时间connected_at、注册的命名空间等信息正是这套连接簿记支撑了上线即发现、下线即失联的语义。从 Worker 代码侧建立连接所需的 SDK 调用connectToEngine等参见 创建 Workers / Workers。管理 Worker 的完整命令集iii worker子命令覆盖项目中每个 Worker 的完整生命周期在注册表中发现新 Worker、将其安装进config.yaml与iii.lock、控制其运行状态、检查日志以及在不需要时将其移除。所有子命令的 clap 定义集中在 crates/iii-worker/src/cli/app.rs日常以iii worker 子命令形式调用。前置条件执行前需要先 安装 iii 并确保 引擎已运行。若只想快速测试可运行iii --use-default-config启动一个临时实例见 默认配置。查找 Workeriii 维护一个公开的 Worker Registry官方注册中心站点其中收录了大量封装常见服务的 Worker。每个 Worker 页面会列出它提供的函数、触发器类型、配置 schema、支持平台与 Agent 技能用来判断某个能力是否已有现成 Worker 可用。关于注册中心与 Worker 形态的详细介绍见 Worker Registry。添加 Workeriii worker add name将一个 Worker 安装进你的项目iii worker add iii-state命令执行后Worker 会被写入项目的config.yaml并自动启动。add支持三种来源见 Worker Registry / 添加 Workeriii worker add iii-state # 注册表名称 iii worker add ./workers/my-worker # 本地路径目录内需有 iii.worker.yaml iii worker add ghcr.io/org/worker:tag # Docker / OCI 镜像引用源码实现的几个值得注意的行为细节app.rs默认情况下add会等待最多 120 秒直到 Worker 上报 ready超时后命令返回 shellWorker 继续在后台启动可用iii worker status与iii worker logs继续观察对已存在的 Worker 强制重新下载使用iii worker reinstall name等价于add --force的强制重下语义reinstall不会阻塞等待 ready且可通过--reset-config将config.yaml中的条目重置为注册表默认值add --no-wait/--force可分别跳过就绪等待与触发重下。此外managed.rs 明确了命令的输出契约成功时 stdout 只输出一行机器可读的 Worker 名便于脚本iii worker start foo | xargs ...管道消费其余所有人类可读的状态、进度与错误一律走 stderr——脚本化集成时可依赖这一约定。列出 Workeriii worker listiii worker list显示项目config.yaml中声明的每个 Worker 及其当前状态。从源码与测试看它还会发现磁盘上残留的运行中 Worker集成测试 worker_list_discovery_integration.rs 验证了发现逻辑会合并~/.iii/managed/{name}/OCI/VM 型 Worker 目录与~/.iii/pids/{name}.pid二进制型 Worker 的 pidfile两处磁盘形态去重排序后一并展示并据此区分 running / stopped 状态。启停 Worker已添加的 Worker 会随引擎自动启动。手动控制使用start、stop、restartiii worker start name # 启动一个 Worker iii worker stop -y name # 停止一个 Worker-y 跳过确认提示 iii worker restart name # 先停后启细节app.rsstart/restart默认同样等待最多 120 秒直至 ready--no-wait可立即返回若本地 artifacts 已被clear清掉start会先从注册表重新拉取start --port u16指定生成的 Worker 回连引擎的 WebSocket 端口默认取config.yaml中iii-worker-manager的端口否则 49134引擎自动拉起外部 Worker 时会显式传入该端口stop被视为常规、可逆的操作之后iii worker start name即可重新拉起stop本身从不提示确认-y是为旧脚本保留的兼容性 no-op--config path可将 YAML 配置转发给生成的 Worker 二进制仅二进制型 Worker 生效。调用运行中 Worker 内的函数直接使用worker.trigger/iii trigger或绑定到带条件门控的事件见 Triggers。检查 Workeriii worker status name # 配置、沙箱状态、最近日志 iii worker logs name # 流式查看 Worker 日志 iii worker exec name -- command # 在 Worker 沙箱内执行命令各命令的可选参数app.rsstatus默认在终端内实时刷新直到 Worker 达到成功或失败状态引擎未运行时立即退出--no-watch可只打印一次状态logs从本地日志文件~/.iii/logs/{name}/读取-f/--follow持续跟随输出exec把 stdin/stdout/stderr 管道直通沙箱并透传子进程退出码可用参数包括-e KEYVALUE注入环境变量可重复、-w dir设置工作目录默认/workspace、-t分配 PTY交互式 shell 必需stdin/stdout 均为 TTY 时自动启用、--no-tty强制管道模式以获取字节级精确输出、--timeout 时长如30s、5m超时向会话发 SIGKILL 并以退出码 124 结束与 coreutilstimeout(1)语义一致便于脚本区分超时与普通非零退出。更新 Workeriii worker update worker-name # 更新单个 Worker iii worker update # 更新所有已锁定的 Workeriii worker update会重新解析iii.lock中锁定的 Worker 到注册表允许的最新版本并把新的 pin 写回iii.lock同时改写config.yaml是第三个与锁文件直接相关的命令。移除 Workeriii worker remove -y worker-name # -y 在 Worker 运行中时跳过确认iii worker remove把 Worker 从config.yaml中删除引擎随即拆掉对应的运行进程。注意下载的 artifacts 在移除后仍保留在磁盘上需要一并删除时使用iii worker clear -y worker-name # 删除该 Worker 的下载 artifacts iii worker clear -y # 省略名称则清空所有 Worker 的 artifactsclear只清理~/.iii/下的下载产物不影响 Worker 自身的构建产物与依赖如node_modules、Cargo.lock。Worker Skills为 Agent 而生的能力清单每个 Worker 还会随包附带面向 Agentic 工作的Skills技能。Skills 由skillsWorker 管理——它是一个正在积极开发的内容注册表 Worker像其他 Worker 一样通过iii worker add加入项目。技能内容采用懒加载设计顶层条目保持很小Agent 只有在某个函数引用解析到具体技能时才会通过iii://worker/leaf这种 section URI 按需拉取更深层的内容。iii 还附带高层级 Skills让任意 Agent 都能立即上手使用 iii 及其 Worker。当前文档所描述的 Skills 交互面对应skillsWorker 的早期版本v0.2.4在其 API 稳定前可能有所演进。函数与触发器由已连接 Worker 提供函数Functions与触发器Triggers来自已连接的 Worker。要使用某种类型的触发器提供它的 Worker 必须处于连接状态。例如通过 iii-http Worker 添加http触发器后你就能像在 Express 或 FastAPI 这类 Web 框架中一样为你的函数暴露 HTTP 端点。这一机制把能力供给与连接状态绑定Worker 上线即注册其函数与触发器断线即整体下线与服务发现天然一致。版本化与可复现安装语义化版本与版本钉iii 的 Worker 遵循semver。项目会把每个托管 Worker 的已解析版本记录在iii.lock中从而让安装在不同机器与平台上可复现。不带版本说明符安装时默认取最新 release在注册表名称后追加version可钉住特定版本iii worker add iii-state1.2.0该 pin 会写入iii.lock并在之后的每次安装中按此重放。锁文件 iii.lockiii.lock是位于项目根目录的 YAML 文件把每个托管 Worker 钉到具体的版本与来源保证同一组 Worker 在任何机器与平台上安装结果一致。二进制型 Worker 可以在同一个锁文件中按平台macOS、Linux、Windows分别钉住各自的 artifacts。锁文件的结构可以从 crates/iii-worker/src/cli/lockfile.rs 一窥究竟顶层字段version锁文件格式版本、manifest_hashiii.worker.yaml依赖清单规范序列化的 SHA-256用于漂移检测旧锁可能缺失、declared_dependencies写锁时的项目依赖声明、workers按名称索引的LockedWorker映射LockedWorkerversion、typebinary/image/engine/bundle、dependencies、可选的sourceLockedSource按类型区分binary按目标平台列出urlsha256的 artifacts 映射、imageOCI 镜像引用、bundle归档archive_urlsha256。仓库中 engine/iii.lock 给出了一个最小实例version: 1 workers: iii-http: version: 0.13.0-next.1 type: engine dependencies: {}建议把iii.lock与config.yaml一起提交到版本库以获得可复现安装。直接作用于锁文件的命令有两个iii worker sync # 严格按 iii.lock 安装 Worker iii worker sync --frozen # CI 形态只校验锁文件不改动本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移sync --frozen定位为 CI/CD 中的校验步骤app.rs 注释Verify lockfile dependencies without mutating local files. Useful for validation in CICDverify检查config.yaml中每个托管 Worker 是否已在iii.lock中为当前平台完成钉版verify --strict还会进一步核对依赖声明与锁定版本是否一致第三个相关命令是上文介绍的iii worker update它把 pin 重新解析到允许的最新版本并写回iii.lock。这些行为都有集成测试覆盖例如 sync_drift_adversarial.rs对抗性漂移场景与 config_managed_integration.rs托管配置端到端。版本演进提示在当前仓库主分支中项目级 Workerhttp、state、cron、queue、pubsub 等的声明正在向 worker-compose.yaml 迁移容器以package://api.workers.iii.dev/name加version字段引用见 engine/config.yaml 顶部注释iii.lock同源钉版的思想在两个文件中一脉相承。编写新 Worker 的边界本页聚焦于使用既有 Worker。创建新 Worker、在 Worker 代码中注册函数与触发器、以及构建或发布 Worker 镜像超出了本页范围请参见 创建 Workers / Workers。参考资料文档主体Workers0-16-0 与 渲染版命令定义crates/iii-worker/src/cli/app.rs锁文件实现crates/iii-worker/src/cli/lockfile.rs输出契约crates/iii-worker/src/cli/managed.rs引擎侧 Worker 注册与配置engine/src/workers/config.rs连接状态管理engine/src/worker_connections/mod.rs配置示例engine/config.yaml、engine/worker-compose.yaml、engine/iii.lock相关集成测试worker_list_discovery_integration.rs、sync_drift_adversarial.rs、config_managed_integration.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），仅供参考
)
