2026/9/13 6:22:35
FEATURED · 精选文章 
iii Workers 实战Worker 添加、生命周期管理、iii.lock 锁定与沙箱检查全流程【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文基于 iii 项目 0.12.0 版文档using-iii/workers页面展开系统讲解 iii 中 Worker 的完整使用闭环通过iii worker add安装 Worker、管理其启动/停止生命周期、用status/logs/exec检查沙箱内部状态以及利用iii.lock锁定文件实现跨机器的可复现安装。读完本文你可以独立完成一个 iii 项目中从“发现 Worker → 添加 → 版本固定 → 升级 → 清理”的全部运维操作并理解每条命令背后的 CLI 实现与锁文件机制。Worker 是什么免集成的自包含服务iii 的设计中任何功能扩展都以 Worker 的形式出现。可以把 Worker 理解为 iii 版的“自包含、隔离运行、且能与其他所有 Worker 自由互操作的服务”。与传统服务的关键区别在于Worker 不需要任何集成工作即可使用——它像 npm 包一样通过iii worker add安装和管理但你拿到的是一个完整的、可部署的运行时而不是一个库。这一点对应到仓库源码中Worker 的实现分散在 engine/src/workers 目录下内置 Worker 包括configuration配置、workerWebSocket 连接管理、queue队列含 RabbitMQ 适配器、stream流含 Redis 适配器、observability可观测性等模块每个内置 Worker 目录下都有iii.worker.yaml声明文件与skills/SKILL.md技能文件这与后文“Worker skills”一节所述一致。Worker 生命周期WebSocket 连接模型Worker 通过 WebSocket 连接到 iii 引擎。连接建立后该 Worker 对整个 iii 系统及系统内其他所有 Worker 可见一旦断开连接它提供的函数和触发器立即停止可被调用直到重新连接。从源码结构看这一连接的承接方是 engine/src/workers/worker/ws_handler.rs该模块处理 Worker 的 WebSocket 会话与注册对应的引擎侧端点在 engine/src/workers/worker/mod.rs 中定义了默认端口等常量。因此“断开即不可调用”不是软性降级而是注册表层面的事实未连接的 Worker 不进入函数/触发器的可解析集合。关于 Worker 代码侧建立连接的 SDK 调用可参考 Creating Workers / Workers 中的“Connecting to the engine”一节。发现 Worker官方 Worker 注册表官方维护了一个 Worker 注册表workers.iii.dev其中收录了封装常见服务的 Worker。注册表的详细用法见 Worker Registry。对于“某个功能比如 PDF 生成、对象存储有没有现成 Worker”这类问题先查注册表是官方推荐的入手方式。添加 Worker前置条件需要 iii 已安装且运行中。若只是临时测试可以先启动一个临时 iii 实例。iii worker add name将 Worker 安装到当前项目iii worker add iii-state执行后发生两件事Worker 被写入项目的config.yaml并被自动启动。若要强制重新下载一个已存在的 Worker使用iii worker reinstall name等价于add --force。对于本地路径、Docker / OCI 镜像以及版本固定的细节见 Worker Registry / Adding a worker。这条命令的实现在当前仓库中位于独立的iii-worker二进制中crates/iii-worker/src/cli/app.rs 定义了Add、Remove、Reinstall、Update、Clear、Start、Stop、Restart、List、Sync、Verify、Status、Logs、Init、Exec等子命令与本文档列出的全部命令一一对应。而 iii 主引擎二进制与iii-worker的关系可在 engine/src/cli/registry.rs 的REGISTRY表里看到其中iii-worker条目将 CLI 命令名worker映射到独立二进制说明 Worker 管理功能在架构上是与引擎分离、按需调度的一个可管理二进制。列出 Workeriii worker list展示项目config.yaml中声明的所有 Worker 及其当前状态iii worker list启动与停止 Worker通过add添加的 Worker 会随引擎自动启动。需要手动控制时使用start、stop、restartiii worker start name # 启动一个 worker iii worker stop name # 停止一个 worker iii worker restart name # 先停再起要对运行中 Worker 内部的函数发起调用直接用iii.trigger/iii trigger或将其绑定到事件上并附加可选条件门见 Triggers。检查 Worker 状态要查看某个 Worker 的状态、跟踪其日志或在 Worker 的沙箱内执行命令使用iii worker status name # 配置、沙箱状态、近期日志 iii worker logs name # 流式输出该 worker 的日志 iii worker exec name -- command # 在 worker 沙箱内运行一条命令exec是排障利器它直接在你下载并部署的那个 Worker 运行时里执行命令意味着你可以进入 Worker 的文件系统视角检查依赖、环境变量和产出物而无需重建环境。Status命令返回的“配置 沙箱状态 近期日志”三合一视图也对应 crates/iii-worker/src/cli/app.rs 中Status子命令对 Worker 名的参数定义。Worker Skills面向 Agent 的附带能力每个 Worker 同时附带用于 Agentic 工作的 skills。Skills 由skillsWorker 统一管理——它是一个内容注册表型 Worker像其他 Worker 一样被添加进项目。技能内容采用惰性加载顶层条目保持很小Agent 只有当某个函数引用解析到具体 section 时才通过iii://worker/leaf形式的 section URI 拉取深层内容。官方也提供高层 skills使任意 Agent 都能立即使用 iii 及其 Worker。这一点在源码中有直接佐证engine/src/workers 下多个内置 Worker 都携带skills/SKILL.md文件例如 engine/src/workers/queue 相关模块 的 README 与 engine/src/workers/stream/skills 等说明“每个 Worker 自带 skills”是仓库内一致落实的约定。可用的函数与触发器函数与触发器都来自已连接的 Worker。要使用某种类型的触发器必须先连接提供它的 Worker。例如添加 iii-http Worker 后你就可以像使用 Express 或 FastAPI 这样的 Web 框架一样为函数暴露 HTTP 端点。从引擎源码看这一“按 Worker 提供”的能力模型对应 engine/src/workers/registry.rs 等注册表模块函数/触发器的可调用集合随连接状态动态变化而不是编译期静态声明。版本与固定Versioning and PinningWorker 以 semver 版本发布。不带版本说明符安装时会选择最新 release。在注册表名后追加version即可固定到特定 release而不是持续跟踪最新iii worker add iii-state1.2.0这个 pin 会被记录进iii.lock并在后续每次安装时重放保证同一套 iii 部署在不同机器上可复现。更新 Workeriii worker update重新解析已锁定的 Worker并把新的 pin 写回iii.lock。传 Worker 名则只更新一个省略则更新所有已锁定 Workeriii worker update worker-name # 更新一个 worker iii worker update # 更新所有已锁定 worker在 crates/iii-worker/src/cli/app.rs 中Update子命令的参数定义也明确写道“Optional worker name to update. If omitted, updates every worker in iii.lock”与文档语义完全一致。锁文件 iii.lockiii.lock是位于项目根目录的 YAML 文件。它把每个受管 Worker 固定到具体版本与来源使同一组 Worker 在不同机器和平台上以相同方式安装。二进制 Worker 可以在同一个锁文件中按平台固定产物macOS、Linux、Windows。仓库内就有一份可直接参考的真实样例 engine/iii.lockversion: 1 workers: iii-http: version: 0.13.0-next.1 type: engine dependencies: {}可以看到顶层为version与workers两个字段每个 Worker 条目记录version、type如engine与dependencies。为了可复现安装建议把iii.lock与config.yaml一起提交进版本库。直接操作锁文件的命令有三个iii worker sync # 严格按 iii.lock 安装 workers iii worker sync --frozen # CI 形态校验锁文件但不改动本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移其中sync --frozen是 CI 场景的关键它只做校验不做变更适合作为流水线里的守门步骤verify则用于在开发者本机发现“config 改了但锁文件没跟上”的漂移。前文的iii worker update是第三个锁文件命令它把 pin 重新解析到允许范围内的最新版本并写回iii.lock。移除 Workeriii worker remove把 Worker 从config.yaml中删除引擎会随之拆掉运行中的 Worker 进程iii worker remove worker-name注意移除后已下载的产物仍保留在磁盘上。若连产物一起删除使用iii worker clear worker-name省略名称则清空所有 Worker 的产物。Remove与Clear在 crates/iii-worker/src/cli/app.rs 中均有对应子命令定义Clear的参数说明即“Worker name to clear (omit to clear all)”与文档描述一致。编写 Worker范围外创建新 Worker、在 Worker 代码中注册函数与触发器、构建或发布 Worker 镜像不属于本页范围见 Creating Workers / Workers 与 Creating Workers / Worker Registry。适用前提0.12.0 文档与当前仓库 HEAD 的差异本文以 0.12.0 文档为基准使用时需注意版本前提iii worker的宿主已演进。从当前仓库源码结构看Worker 管理命令已被拆分到独立的iii-worker二进制crates/iii-worker引擎主程序通过 engine/src/cli/registry.rs 的REGISTRY表将其作为可管理二进制调度同时 engine/src/main.rs 中的测试worker_is_no_longer_a_public_command与use_default_config_is_no_longer_a_flag表明在仓库 HEAD 版本的根 CLI 上iii worker不再作为公开子命令、--use-default-config标志也已被移除。因此本文命令序列对应 0.12.0 时期的 CLI 形态若使用当前版本二进制请以iii worker实际帮助输出为准各子命令语义在iii-worker二进制中仍然保留。锁文件字段随版本演进。engine/iii.lock 展示的version: 1结构是当前仓库内可验证的最小样例文档 TODO 注释亦提到按字段的完整锁文件 schema顶层字段、LockedWorker、BinaryArtifact、ImageSource、manifest 哈希格式参考页尚待补齐遇到更复杂的条目时以实际文件与工具链行为为准。Skills 接口不稳定。原文档明确标注 Worker skills 一节的描述基于 0.2.4 版 skills Worker 的形态稳定发布前接口可能变化iii://worker/leafsection URI 机制在仓库内如 engine/src/workers/worker/skills已有落地但其对外 API 细节建议以最新文档为准。小结生命周期Worker 以 WebSocket 连接存在连接即可见、断开即不可调用安装管理add写入config.yaml并自动启动→list/start/stop/restart→status/logs/exec沙箱内检查→remove/clear删声明 / 删磁盘产物可复现性version固定版本pin 落入iii.locksync含--frozenCI 形态与verify直接操作锁文件update负责重解析并回写能力来源函数与触发器均来自已连接 Worker例如 iii-http 提供 Express/FastAPI 式的端点暴露能力。这一套“包管理器式 锁文件 沙箱检查”的组合是 iii 把服务编排做到“像安装依赖一样安装服务”的核心支撑。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
iii Workers 实战：Worker 添加、生命周期管理、iii.lock 锁定与沙箱检查全流程
iii Workers 实战Worker 添加、生命周期管理、iii.lock 锁定与沙箱检查全流程【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii本文基于 iii 项目 0.12.0 版文档using-iii/workers页面展开系统讲解 iii 中 Worker 的完整使用闭环通过iii worker add安装 Worker、管理其启动/停止生命周期、用status/logs/exec检查沙箱内部状态以及利用iii.lock锁定文件实现跨机器的可复现安装。读完本文你可以独立完成一个 iii 项目中从“发现 Worker → 添加 → 版本固定 → 升级 → 清理”的全部运维操作并理解每条命令背后的 CLI 实现与锁文件机制。Worker 是什么免集成的自包含服务iii 的设计中任何功能扩展都以 Worker 的形式出现。可以把 Worker 理解为 iii 版的“自包含、隔离运行、且能与其他所有 Worker 自由互操作的服务”。与传统服务的关键区别在于Worker 不需要任何集成工作即可使用——它像 npm 包一样通过iii worker add安装和管理但你拿到的是一个完整的、可部署的运行时而不是一个库。这一点对应到仓库源码中Worker 的实现分散在 engine/src/workers 目录下内置 Worker 包括configuration配置、workerWebSocket 连接管理、queue队列含 RabbitMQ 适配器、stream流含 Redis 适配器、observability可观测性等模块每个内置 Worker 目录下都有iii.worker.yaml声明文件与skills/SKILL.md技能文件这与后文“Worker skills”一节所述一致。Worker 生命周期WebSocket 连接模型Worker 通过 WebSocket 连接到 iii 引擎。连接建立后该 Worker 对整个 iii 系统及系统内其他所有 Worker 可见一旦断开连接它提供的函数和触发器立即停止可被调用直到重新连接。从源码结构看这一连接的承接方是 engine/src/workers/worker/ws_handler.rs该模块处理 Worker 的 WebSocket 会话与注册对应的引擎侧端点在 engine/src/workers/worker/mod.rs 中定义了默认端口等常量。因此“断开即不可调用”不是软性降级而是注册表层面的事实未连接的 Worker 不进入函数/触发器的可解析集合。关于 Worker 代码侧建立连接的 SDK 调用可参考 Creating Workers / Workers 中的“Connecting to the engine”一节。发现 Worker官方 Worker 注册表官方维护了一个 Worker 注册表workers.iii.dev其中收录了封装常见服务的 Worker。注册表的详细用法见 Worker Registry。对于“某个功能比如 PDF 生成、对象存储有没有现成 Worker”这类问题先查注册表是官方推荐的入手方式。添加 Worker前置条件需要 iii 已安装且运行中。若只是临时测试可以先启动一个临时 iii 实例。iii worker add name将 Worker 安装到当前项目iii worker add iii-state执行后发生两件事Worker 被写入项目的config.yaml并被自动启动。若要强制重新下载一个已存在的 Worker使用iii worker reinstall name等价于add --force。对于本地路径、Docker / OCI 镜像以及版本固定的细节见 Worker Registry / Adding a worker。这条命令的实现在当前仓库中位于独立的iii-worker二进制中crates/iii-worker/src/cli/app.rs 定义了Add、Remove、Reinstall、Update、Clear、Start、Stop、Restart、List、Sync、Verify、Status、Logs、Init、Exec等子命令与本文档列出的全部命令一一对应。而 iii 主引擎二进制与iii-worker的关系可在 engine/src/cli/registry.rs 的REGISTRY表里看到其中iii-worker条目将 CLI 命令名worker映射到独立二进制说明 Worker 管理功能在架构上是与引擎分离、按需调度的一个可管理二进制。列出 Workeriii worker list展示项目config.yaml中声明的所有 Worker 及其当前状态iii worker list启动与停止 Worker通过add添加的 Worker 会随引擎自动启动。需要手动控制时使用start、stop、restartiii worker start name # 启动一个 worker iii worker stop name # 停止一个 worker iii worker restart name # 先停再起要对运行中 Worker 内部的函数发起调用直接用iii.trigger/iii trigger或将其绑定到事件上并附加可选条件门见 Triggers。检查 Worker 状态要查看某个 Worker 的状态、跟踪其日志或在 Worker 的沙箱内执行命令使用iii worker status name # 配置、沙箱状态、近期日志 iii worker logs name # 流式输出该 worker 的日志 iii worker exec name -- command # 在 worker 沙箱内运行一条命令exec是排障利器它直接在你下载并部署的那个 Worker 运行时里执行命令意味着你可以进入 Worker 的文件系统视角检查依赖、环境变量和产出物而无需重建环境。Status命令返回的“配置 沙箱状态 近期日志”三合一视图也对应 crates/iii-worker/src/cli/app.rs 中Status子命令对 Worker 名的参数定义。Worker Skills面向 Agent 的附带能力每个 Worker 同时附带用于 Agentic 工作的 skills。Skills 由skillsWorker 统一管理——它是一个内容注册表型 Worker像其他 Worker 一样被添加进项目。技能内容采用惰性加载顶层条目保持很小Agent 只有当某个函数引用解析到具体 section 时才通过iii://worker/leaf形式的 section URI 拉取深层内容。官方也提供高层 skills使任意 Agent 都能立即使用 iii 及其 Worker。这一点在源码中有直接佐证engine/src/workers 下多个内置 Worker 都携带skills/SKILL.md文件例如 engine/src/workers/queue 相关模块 的 README 与 engine/src/workers/stream/skills 等说明“每个 Worker 自带 skills”是仓库内一致落实的约定。可用的函数与触发器函数与触发器都来自已连接的 Worker。要使用某种类型的触发器必须先连接提供它的 Worker。例如添加 iii-http Worker 后你就可以像使用 Express 或 FastAPI 这样的 Web 框架一样为函数暴露 HTTP 端点。从引擎源码看这一“按 Worker 提供”的能力模型对应 engine/src/workers/registry.rs 等注册表模块函数/触发器的可调用集合随连接状态动态变化而不是编译期静态声明。版本与固定Versioning and PinningWorker 以 semver 版本发布。不带版本说明符安装时会选择最新 release。在注册表名后追加version即可固定到特定 release而不是持续跟踪最新iii worker add iii-state1.2.0这个 pin 会被记录进iii.lock并在后续每次安装时重放保证同一套 iii 部署在不同机器上可复现。更新 Workeriii worker update重新解析已锁定的 Worker并把新的 pin 写回iii.lock。传 Worker 名则只更新一个省略则更新所有已锁定 Workeriii worker update worker-name # 更新一个 worker iii worker update # 更新所有已锁定 worker在 crates/iii-worker/src/cli/app.rs 中Update子命令的参数定义也明确写道“Optional worker name to update. If omitted, updates every worker in iii.lock”与文档语义完全一致。锁文件 iii.lockiii.lock是位于项目根目录的 YAML 文件。它把每个受管 Worker 固定到具体版本与来源使同一组 Worker 在不同机器和平台上以相同方式安装。二进制 Worker 可以在同一个锁文件中按平台固定产物macOS、Linux、Windows。仓库内就有一份可直接参考的真实样例 engine/iii.lockversion: 1 workers: iii-http: version: 0.13.0-next.1 type: engine dependencies: {}可以看到顶层为version与workers两个字段每个 Worker 条目记录version、type如engine与dependencies。为了可复现安装建议把iii.lock与config.yaml一起提交进版本库。直接操作锁文件的命令有三个iii worker sync # 严格按 iii.lock 安装 workers iii worker sync --frozen # CI 形态校验锁文件但不改动本地文件 iii worker verify # 报告 config.yaml 与 iii.lock 之间的漂移其中sync --frozen是 CI 场景的关键它只做校验不做变更适合作为流水线里的守门步骤verify则用于在开发者本机发现“config 改了但锁文件没跟上”的漂移。前文的iii worker update是第三个锁文件命令它把 pin 重新解析到允许范围内的最新版本并写回iii.lock。移除 Workeriii worker remove把 Worker 从config.yaml中删除引擎会随之拆掉运行中的 Worker 进程iii worker remove worker-name注意移除后已下载的产物仍保留在磁盘上。若连产物一起删除使用iii worker clear worker-name省略名称则清空所有 Worker 的产物。Remove与Clear在 crates/iii-worker/src/cli/app.rs 中均有对应子命令定义Clear的参数说明即“Worker name to clear (omit to clear all)”与文档描述一致。编写 Worker范围外创建新 Worker、在 Worker 代码中注册函数与触发器、构建或发布 Worker 镜像不属于本页范围见 Creating Workers / Workers 与 Creating Workers / Worker Registry。适用前提0.12.0 文档与当前仓库 HEAD 的差异本文以 0.12.0 文档为基准使用时需注意版本前提iii worker的宿主已演进。从当前仓库源码结构看Worker 管理命令已被拆分到独立的iii-worker二进制crates/iii-worker引擎主程序通过 engine/src/cli/registry.rs 的REGISTRY表将其作为可管理二进制调度同时 engine/src/main.rs 中的测试worker_is_no_longer_a_public_command与use_default_config_is_no_longer_a_flag表明在仓库 HEAD 版本的根 CLI 上iii worker不再作为公开子命令、--use-default-config标志也已被移除。因此本文命令序列对应 0.12.0 时期的 CLI 形态若使用当前版本二进制请以iii worker实际帮助输出为准各子命令语义在iii-worker二进制中仍然保留。锁文件字段随版本演进。engine/iii.lock 展示的version: 1结构是当前仓库内可验证的最小样例文档 TODO 注释亦提到按字段的完整锁文件 schema顶层字段、LockedWorker、BinaryArtifact、ImageSource、manifest 哈希格式参考页尚待补齐遇到更复杂的条目时以实际文件与工具链行为为准。Skills 接口不稳定。原文档明确标注 Worker skills 一节的描述基于 0.2.4 版 skills Worker 的形态稳定发布前接口可能变化iii://worker/leafsection URI 机制在仓库内如 engine/src/workers/worker/skills已有落地但其对外 API 细节建议以最新文档为准。小结生命周期Worker 以 WebSocket 连接存在连接即可见、断开即不可调用安装管理add写入config.yaml并自动启动→list/start/stop/restart→status/logs/exec沙箱内检查→remove/clear删声明 / 删磁盘产物可复现性version固定版本pin 落入iii.locksync含--frozenCI 形态与verify直接操作锁文件update负责重解析并回写能力来源函数与触发器均来自已连接 Worker例如 iii-http 提供 Express/FastAPI 式的端点暴露能力。这一套“包管理器式 锁文件 沙箱检查”的组合是 iii 把服务编排做到“像安装依赖一样安装服务”的核心支撑。【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
