企业官网建设流程全解析

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 项目的 Worker（Worker）展开：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、可选的image（OCI 镜像引用，设置为它即表示外部 Worker）与可选的config（YAML 配置块）；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启动一个临时实例（见 默认配置）。

查找 Worker

iii 维护一个公开的 Worker Registry（官方注册中心站点），其中收录了大量封装常见服务的 Worker。每个 Worker 页面会列出它提供的函数、触发器类型、配置 schema、支持平台与 Agent 技能，用来判断某个能力是否已有现成 Worker 可用。关于注册中心与 Worker 形态的详细介绍，见 Worker Registry。

添加 Worker

iii worker add <name>将一个 Worker 安装进你的项目：

iii worker add iii-state

命令执行后，Worker 会被写入项目的config.yaml并自动启动。add支持三种来源（见 Worker Registry / 添加 Worker）：

iii 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；超时后命令返回 shell，Worker 继续在后台启动，可用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——脚本化集成时可依赖这一约定。

列出 Worker

iii worker list

iii 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、restart：

iii worker start <name> # 启动一个 Worker iii worker stop -y <name> # 停止一个 Worker（-y 跳过确认提示） iii worker restart <name> # 先停后启

细节（app.rs）：

• start/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。

检查 Worker

iii worker status <name> # 配置、沙箱状态、最近日志 iii worker logs <name> # 流式查看 Worker 日志 iii worker exec <name> -- <command> # 在 Worker 沙箱内执行命令

各命令的可选参数（app.rs）：

• status默认在终端内实时刷新直到 Worker 达到成功或失败状态，引擎未运行时立即退出；--no-watch可只打印一次状态；
• logs从本地日志文件~/.iii/logs/{name}/读取，-f/--follow持续跟随输出；
• exec把 stdin/stdout/stderr 管道直通沙箱并透传子进程退出码，可用参数包括：-e KEY=VALUE（注入环境变量，可重复）、-w <dir>（设置工作目录，默认/workspace）、-t（分配 PTY，交互式 shell 必需，stdin/stdout 均为 TTY 时自动启用）、--no-tty（强制管道模式以获取字节级精确输出）、--timeout <时长>（如30s、5m；超时向会话发 SIGKILL 并以退出码 124 结束，与 coreutilstimeout(1)语义一致，便于脚本区分超时与普通非零退出）。

更新 Worker

iii worker update <worker-name> # 更新单个 Worker iii worker update # 更新所有已锁定的 Worker

iii worker update会重新解析iii.lock中锁定的 Worker 到注册表允许的最新版本，并把新的 pin 写回iii.lock（同时改写config.yaml），是第三个与锁文件直接相关的命令。

移除 Worker

iii 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 的 artifacts

clear只清理~/.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-state@1.2.0

该 pin 会写入iii.lock，并在之后的每次安装中按此重放。

锁文件 iii.lock

iii.lock是位于项目根目录的 YAML 文件，把每个托管 Worker 钉到具体的版本与来源，保证同一组 Worker 在任何机器与平台上安装结果一致。二进制型 Worker 可以在同一个锁文件中按平台（macOS、Linux、Windows）分别钉住各自的 artifacts。

锁文件的结构可以从 crates/iii-worker/src/cli/lockfile.rs 一窥究竟：

• 顶层字段：version（锁文件格式版本）、manifest_hash（iii.worker.yaml依赖清单规范序列化的 SHA-256，用于漂移检测；旧锁可能缺失）、declared_dependencies（写锁时的项目依赖声明）、workers（按名称索引的LockedWorker映射）；
• LockedWorker：version、type（binary/image/engine/bundle）、dependencies、可选的source；
• LockedSource按类型区分：binary（按目标平台列出url+sha256的 artifacts 映射）、image（OCI 镜像引用）、bundle（归档archive_url+sha256）。

仓库中 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 CICD"）；
• verify检查config.yaml中每个托管 Worker 是否已在iii.lock中为当前平台完成钉版；verify --strict还会进一步核对依赖声明与锁定版本是否一致；
• 第三个相关命令是上文介绍的iii worker update，它把 pin 重新解析到允许的最新版本并写回iii.lock。

这些行为都有集成测试覆盖，例如 sync_drift_adversarial.rs（对抗性漂移场景）与 config_managed_integration.rs（托管配置端到端）。

版本演进提示：在当前仓库主分支中，项目级 Worker（http、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。

参考资料

• 文档主体：Workers（0-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