iii-worker-lockfile

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worker Lockfile

Worker 锁文件

iii.lock

is a YAML lockfile in the project root. It records resolved registry-managed worker sources so installs can be replayed across machines and CI.

iii.lock

是项目根目录下的一个YAML锁文件。它记录了已解析的、由注册表管理的worker源，以便在不同机器和CI环境中重现安装过程。

What It Records

记录内容

Lockfile version.
Registry-managed worker entries.
Binary source artifacts keyed by platform target triple.
OCI/image source pins such as resolved image digests where available.
Dependency graph pins returned by the worker registry.

config.yaml

expresses intent: which workers the project uses.

iii.lock

records the resolved worker graph and artifacts needed to reproduce that intent.

锁文件版本。
由注册表管理的worker条目。
按平台目标三元组索引的二进制源制品。
OCI/镜像源固定信息（如已解析的镜像摘要，若可用）。
worker注册表返回的依赖图固定信息。

config.yaml

用于声明项目的需求：即项目使用哪些worker。

iii.lock

则记录了已解析的worker图以及重现该需求所需的制品。

Commands

命令

Command	Mutates?	Behavior
`iii worker add <worker[@version]>`	Yes	Adds a registry-managed worker and merges resolved entries into `iii.lock` when the registry returns a graph
`iii worker update [worker]`	Yes	Re-resolves latest for one locked worker, or inferred roots when no worker is given, then rewrites `iii.lock`
`iii worker sync`	Local artifacts only	Replays registry-managed workers from `iii.lock` for the current target without rewriting config or lockfile
`iii worker sync --frozen`	No	Delegates to verification; use in CI or read-only checks
`iii worker verify`	No	Checks that lockfile-managed workers in config have lock entries and artifacts for the current target
`iii worker verify --strict`	No	Adds dependency freshness checks for locked ranges and local `iii.worker.yaml` dependency blocks

命令	是否修改文件？	行为
`iii worker add <worker[@version]>`	是	添加一个由注册表管理的worker，当注册表返回依赖图时，将已解析的条目合并到 `iii.lock` 中
`iii worker update [worker]`	是	重新解析指定锁定worker的最新版本；若未指定worker，则解析推断出的根worker，然后重写 `iii.lock`
`iii worker sync`	仅修改本地制品	根据 `iii.lock` 为当前目标重现由注册表管理的worker，不会重写配置或锁文件
`iii worker sync --frozen`	否	委托给验证流程；适用于CI或只读检查场景
`iii worker verify`	否	检查配置中由锁文件管理的worker是否存在对应的锁条目，以及当前目标所需的制品是否齐全
`iii worker verify --strict`	否	增加对锁定版本范围和本地 `iii.worker.yaml` 依赖块的依赖新鲜度检查

Reproducible Install Workflow

可重现安装流程

bash

iii worker add image-resize@1.0.0
git add config.yaml iii.lock
iii worker verify

After cloning or restoring CI state:

bash

iii worker sync
iii worker verify

For CI checks that must not mutate:

bash

iii worker sync --frozen
iii worker verify --strict

bash

iii worker add image-resize@1.0.0
git add config.yaml iii.lock
iii worker verify

克隆仓库或恢复CI状态后：

bash

iii worker sync
iii worker verify

适用于禁止修改的CI检查场景：

bash

iii worker sync --frozen
iii worker verify --strict

Commit Rules

提交规则

Commit
```
iii.lock
```
with
```
config.yaml
```
.
Update pins intentionally with
```
iii worker update
```
, not by hand-editing resolved artifact entries.
Do not expect built-ins, direct OCI refs, local-path workers, or sandbox rootfs/base images to be replayed by the v1 lockfile contract.
Extra lockfile entries are allowed by normal verification; strict verification adds freshness checks.

提交
```
config.yaml
```
时需一同提交
```
iii.lock
```
。
需通过
```
iii worker update
```
命令有意地更新固定版本，而非手动编辑已解析的制品条目。
v1锁文件协议不支持重现内置worker、直接OCI引用、本地路径worker或沙箱根文件系统/基础镜像。
普通验证允许锁文件存在额外条目；严格验证会增加新鲜度检查。

Pattern Boundaries

模式边界

For command-by-command worker operations, prefer
```
iii-worker-lifecycle
```
.
For config YAML structure, prefer
```
iii-engine-config
```
.

若需逐命令执行worker操作，建议使用
```
iii-worker-lifecycle
```
。
若涉及配置YAML结构，建议使用
```
iii-engine-config
```
。

When to Use

使用场景

Use this skill when the task mentions
```
iii.lock
```
, reproducible worker installs, frozen sync, worker verification, CI worker setup, or cross-machine worker reproducibility.

当任务涉及
```
iii.lock
```
、可重现worker安装、冻结同步、worker验证、CI worker设置或跨机器worker可重现性时，使用该技能。

Boundaries

限制

Do not invent lockfile entries manually.
Do not treat
```
sync
```
as an update command; it replays existing pins.
Do not generate removed service APIs or adapter-extension APIs.

请勿手动创建锁文件条目。
请勿将
```
sync
```
命令当作更新命令使用；它仅重现已有的固定版本。
请勿生成已移除的服务API或适配器扩展API。