iii-worker-lifecycle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worker Lifecycle

Worker 生命周期

Use this skill when the task is about the

iii worker ...

command surface or managed worker lifecycle.

当任务涉及

iii worker ...

命令集或托管 worker 生命周期时，使用本技能。

Command Groups

命令组

Command	Use when
`iii worker add <worker[@version]>`	Add a registry-managed worker and update config/lockfile when the resolver returns a graph
`iii worker add <oci-ref>`	Add an OCI/container worker such as `ghcr.io/org/worker:tag`
`iii worker add ./path`	Register a local worker project for managed sandbox/local development
`iii worker remove <name>`	Remove a worker from config and managed lifecycle
`iii worker reinstall <name>`	Reinstall a managed worker artifact without changing intent
`iii worker update [name]`	Intentionally re-resolve worker pins and rewrite `iii.lock`
`iii worker clear [name]`	Clear local managed-worker artifacts/cache before reinstalling or re-adding
`iii worker start <name>`	Start a managed worker that is configured but not running
`iii worker stop <name>`	Stop a running managed worker
`iii worker restart <name>`	Stop then start a managed worker
`iii worker list`	Show configured/managed workers
`iii worker status [name]`	Inspect runtime status, PID/state, and whether a worker is running
`iii worker logs <name>`	Read managed worker logs
`iii worker logs <name> --follow`	Tail logs while debugging startup/runtime issues
`iii worker exec <name> -- <cmd>`	Run a command inside a running worker environment
`iii worker init`	Scaffold worker metadata such as `iii.worker.yaml` for a local worker
`iii worker sync`	Replay registry-managed workers from `iii.lock` for the current platform
`iii worker sync --frozen`	Verify reproducibility without changing local files
`iii worker verify`	Check that config and `iii.lock` agree

命令	使用场景
`iii worker add <worker[@version]>`	添加注册表托管的 worker，当解析器返回依赖图时更新配置/锁文件
`iii worker add <oci-ref>`	添加 OCI/容器 worker，例如 `ghcr.io/org/worker:tag`
`iii worker add ./path`	注册本地 worker 项目，用于托管沙箱/本地开发
`iii worker remove <name>`	从配置和托管生命周期中移除 worker
`iii worker reinstall <name>`	在不改变配置意图的情况下重新安装托管 worker 制品
`iii worker update [name]`	主动重新解析 worker 版本锁定并改写 `iii.lock`
`iii worker clear [name]`	在重新安装或添加前清除本地托管 worker 的制品/缓存
`iii worker start <name>`	启动已配置但未运行的托管 worker
`iii worker stop <name>`	停止正在运行的托管 worker
`iii worker restart <name>`	先停止再启动托管 worker
`iii worker list`	显示已配置/托管的 worker
`iii worker status [name]`	检查运行时状态、PID/状态以及 worker 是否正在运行
`iii worker logs <name>`	查看托管 worker 的日志
`iii worker logs <name> --follow`	在调试启动/运行时问题时跟踪日志
`iii worker exec <name> -- <cmd>`	在运行中的 worker 环境内执行命令
`iii worker init`	为本地 worker 搭建元数据，例如 `iii.worker.yaml`
`iii worker sync`	针对当前平台，从 `iii.lock` 中恢复注册表托管的 worker
`iii worker sync --frozen`	在不修改本地文件的情况下验证可复现性
`iii worker verify`	检查配置与 `iii.lock` 是否一致

Lifecycle Decisions

生命周期决策

Add a built-in or registry worker by name:

iii worker add iii-state

iii worker add image-resize@1.0.0

Add multiple dependency workers in one command when docs show that pattern:
```
iii worker add iii-state iii-stream iii-queue
```
.
Add a container worker by OCI reference when the worker ships as an image:
```
iii worker add ghcr.io/my-org/my-worker:latest
```
.
Add a local worker path for development:
```
iii worker add ./workers/my-worker
```
.
Use
```
update
```
only when intentionally accepting new resolved versions.
Use
```
sync
```
after clone/CI restore to install artifacts from
```
iii.lock
```
.
Use
```
verify
```
in CI before running the engine.
Use
```
reinstall
```
or
```
clear
```
when the local managed artifact is corrupt or dependency setup changed.

通过名称添加内置或注册表 worker：

iii worker add iii-state

、

iii worker add image-resize@1.0.0

。

当文档显示该模式时，可在一条命令中添加多个依赖 worker：
```
iii worker add iii-state iii-stream iii-queue
```
。
当 worker 以镜像形式发布时，通过 OCI 引用添加容器 worker：
```
iii worker add ghcr.io/my-org/my-worker:latest
```
。
添加本地 worker 路径用于开发：
```
iii worker add ./workers/my-worker
```
。
仅当主动接受新的解析版本时使用
```
update
```
命令。
在克隆/CI 恢复后使用
```
sync
```
命令从
```
iii.lock
```
安装制品。
在 CI 中运行引擎前使用
```
verify
```
命令。
当本地托管制品损坏或依赖配置变更时，使用
```
reinstall
```
或
```
clear
```
命令。

Local vs Registry-Managed

本地托管 vs 注册表托管

Registry-managed workers are reproducible through
```
iii.lock
```
and
```
iii worker sync
```
.
Local path workers are for development and may have local setup/cache state.
Built-in workers can be referenced directly in config and may be skipped by lockfile verification.
Registry pages may label core capabilities as
```
engine
```
workers. Still use the shown
```
iii worker add <name>
```
command when instructing users.
Direct OCI refs are pinned best by immutable tags or digests; lockfile replay focuses on registry-managed worker graphs.

注册表托管的 worker 可通过
```
iii.lock
```
和
```
iii worker sync
```
实现复现。
本地路径 worker 用于开发，可能包含本地配置/缓存状态。
内置 worker 可直接在配置中引用，且可能被锁文件验证跳过。
注册表页面可能将核心功能标记为
```
engine
```
worker。指导用户时仍需使用所示的
```
iii worker add <name>
```
命令。
直接 OCI 引用最好通过不可变标签或摘要锁定；锁文件恢复主要针对注册表托管的 worker 依赖图。

Binary vs OCI Workers

二进制 Worker vs OCI Worker

Binary workers resolve to platform-specific artifacts.
```
iii.lock
```
records artifacts by target triple.
OCI/container workers run from images and can expose default config through image environment declarations.
Managed sandbox/local workers run in isolated local environments where supported and are controlled by the same lifecycle commands.

二进制 worker 会解析为特定平台的制品。
```
iii.lock
```
按目标三元组记录制品。
OCI/容器 worker 从镜像运行，可通过镜像环境声明暴露默认配置。
托管沙箱/本地 worker 在支持的情况下运行于隔离的本地环境中，并由相同的生命周期命令控制。

iii worker exec

iii worker exec

命令

Use

exec

docker exec

for managed workers:

bash

iii worker exec image-resize -- ls -la /workspace
iii worker exec image-resize -e LOG_LEVEL=debug -w /tmp -- ./probe
iii worker exec image-resize --timeout 30s -- ./long-task
iii worker exec image-resize -- sh

TTY is auto-detected for interactive terminals. Use

-t

to force TTY and

--no-tty

for byte-exact pipe mode.

对托管 worker 使用

exec

命令，用法类似

docker exec

：

bash

iii worker exec image-resize -- ls -la /workspace
iii worker exec image-resize -e LOG_LEVEL=debug -w /tmp -- ./probe
iii worker exec image-resize --timeout 30s -- ./long-task
iii worker exec image-resize -- sh

交互式终端会自动检测 TTY。使用

-t

强制启用 TTY，使用

--no-tty

启用字节精确的管道模式。

Pattern Boundaries

模式边界

For lockfile reproducibility, prefer
```
iii-worker-lockfile
```
.
For engine YAML fields, prefer
```
iii-engine-config
```
.
For choosing which worker provides which capability, prefer
```
iii-worker-catalog
```
.
For worker RBAC and public browser access, prefer
```
iii-worker-rbac
```
.

若涉及锁文件可复现性，优先使用
```
iii-worker-lockfile
```
。
若涉及引擎 YAML 字段，优先使用
```
iii-engine-config
```
。
若需选择哪个 worker 提供哪种功能，优先使用
```
iii-worker-catalog
```
。
若涉及 worker RBAC 和公共浏览器访问，优先使用
```
iii-worker-rbac
```
。

When to Use

使用场景

Use this skill when the task mentions
```
iii worker
```
commands, worker installation, worker logs, worker status, worker exec, local worker development, OCI workers, or managed worker lifecycle.

当任务提及
```
iii worker
```
命令、worker 安装、worker 日志、worker 状态、worker 执行、本地 worker 开发、OCI worker 或托管 worker 生命周期时，使用本技能。

Boundaries

使用限制

Never use old aliases such as
```
iii install
```
,
```
iii uninstall
```
, or
```
iii list
```
; the current surface is
```
iii worker add/remove/list
```
.
Do not generate removed service APIs or adapter-extension APIs.
Always keep generated examples aligned with
```
config.yaml
```
plus
```
iii.lock
```
when registry-managed workers are involved.

切勿使用旧别名，如

iii install

、

iii uninstall

或

iii list

；当前命令集为

iii worker add/remove/list

。

不要生成已移除的服务 API 或适配器扩展 API。
当涉及注册表托管的 worker 时，生成的示例需始终与
```
config.yaml
```
和
```
iii.lock
```
保持一致。