zcl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZCL Orchestrator (Codex Skill)

ZCL Orchestrator（Codex Skill）

This skill is for the orchestrator (you), not the spawned "zero context" agent.

本Skill面向编排器（即你），而非生成的“零上下文”Agent。

Goal

目标

Run a mission through ZCL with funnel-first evidence and deterministic artifacts under

.zcl/

Primary evidence:

```
.zcl/.../tool.calls.jsonl
```
```
.zcl/.../feedback.json
```
(authoritative outcome)

Secondary evidence (optional):

```
.zcl/.../notes.jsonl
```
```
.zcl/.../runner.*.json
```

.zcl/.../runner.command.txt

.zcl/.../runner.stdout.log

.zcl/.../runner.stderr.log

(suite runner IO capture)

通过ZCL运行任务，在

.zcl/

目录下生成漏斗优先的证据和确定性工件。

主要证据：

```
.zcl/.../tool.calls.jsonl
```
```
.zcl/.../feedback.json
```
（权威结果）

次要证据（可选）：

```
.zcl/.../notes.jsonl
```
```
.zcl/.../runner.*.json
```

.zcl/.../runner.command.txt

.zcl/.../runner.stdout.log

.zcl/.../runner.stderr.log

（套件运行器IO捕获日志）

Operator Invocation Story

操作者调用流程

When an operator says "run this through ZCL: <mission>", do this:

Resolve entrypoint: prefer
```
zcl
```
on
```
PATH
```
.
Preflight version policy for agent reliability:
- Check latest metadata:
```
zcl update status --json
```
- Prefer explicit harness floor: set
```
ZCL_MIN_VERSION=<semver>
```
  ; ZCL fails fast with
```
ZCL_E_VERSION_FLOOR
```
  when below floor.
Initialize project if needed:
```
zcl init
```
(idempotent).

Prefer native host spawning when available (Mode A):

Single attempt:

zcl attempt start --suite <suiteId> --mission <missionId> --prompt <promptText> --isolation-model native_spawn --json

Suite batch planning:

zcl suite plan --file <suite.(yaml|yml|json)> --json

Spawn exactly one fresh native agent session per attempt and pass the returned
```
env
```
.

Use process-runner orchestration only as an explicit fallback (Mode B):
- ```
zcl suite run --file <suite.(yaml|yml|json)> --session-isolation process --shim surfwright --json -- <runner-cmd> [args...]
```
- ```
--shim surfwright
```
  lets the agent visibly type
```
surfwright ...
```
  while ZCL still records invocations to
```
tool.calls.jsonl
```
  .
- Suite run captures runner IO by default into
```
runner.*
```
  logs for post-mortems.

Require the agent to finish by running:

zcl feedback --ok|--fail --result ...

--result-json ...

Optionally ask for self-report feedback and persist it as secondary evidence:
- ```
zcl note --kind agent --message "..."
```
Report back from artifacts (not from transcript):
- Primary:
```
tool.calls.jsonl
```
  ,
```
feedback.json
```
- Derived:
```
attempt.report.json
```
- Post-mortem:
```
zcl attempt explain [<attemptDir>]
```
  (tail trace + pointers)

当操作者说“通过ZCL运行此任务：<任务内容>”时，请执行以下步骤：

解析入口点：优先使用
```
PATH
```
中的
```
zcl
```
命令。
预检查版本策略以保障Agent可靠性：
- 检查最新元数据：
```
zcl update status --json
```
- 建议设置明确的最低版本要求：设置
```
ZCL_MIN_VERSION=<语义化版本号>
```
  ；当版本低于要求时，ZCL会快速失败并返回
```
ZCL_E_VERSION_FLOOR
```
  错误。
如有需要，初始化项目：
```
zcl init
```
（幂等操作）。
优先使用原生主机生成模式（模式A）：
- 单个测试任务：
```
zcl attempt start --suite <suiteId> --mission <missionId> --prompt <promptText> --isolation-model native_spawn --json
```
- 套件批量规划：
```
zcl suite plan --file <suite.(yaml|yml|json)> --json
```
- 为每个测试任务生成一个全新的原生Agent会话，并传入返回的
```
env
```
  环境变量。
仅在明确需要回退时使用进程运行器编排（模式B）：
- ```
zcl suite run --file <suite.(yaml|yml|json)> --session-isolation process --shim surfwright --json -- <runner-cmd> [args...]
```
- ```
--shim surfwright
```
  参数允许Agent可见地输入
```
surfwright ...
```
  命令，同时ZCL仍会将调用记录到
```
tool.calls.jsonl
```
  中。
- 套件运行默认会将运行器IO捕获到
```
runner.*
```
  日志中，用于事后分析。

要求Agent通过执行以下命令完成任务：

zcl feedback --ok|--fail --result ...

或

--result-json ...

可选：请求自我报告反馈并将其保存为次要证据：
- ```
zcl note --kind agent --message "..."
```
基于工件而非会话记录进行汇报：
- 核心工件：
```
tool.calls.jsonl
```
  ,
```
feedback.json
```
- 衍生工件：
```
attempt.report.json
```
- 事后分析：
```
zcl attempt explain [<attemptDir>]
```
  （追踪尾部信息+指向相关内容）

Fixed Harness Preamble (Turn 1)

固定测试前置说明（第一轮）

You must tell the spawned agent:

Finish rule: must end with
```
zcl feedback ...
```
(required for scoring).
Attempt context: ZCL attempt env vars are already provided (do not invent ids).
Tool execution rule depends on how you launched the attempt:
- If running under
```
zcl suite run --session-isolation process --shim surfwright
```
  : the agent should invoke
```
surfwright ...
```
  normally (no
```
zcl run
```
  ceremony).
- If no shim is installed: all actions must go through ZCL funnels (e.g.
```
zcl run -- ...
```
  ) so evidence exists.

你必须告知生成的Agent：

完成规则：必须以
```
zcl feedback ...
```
命令结束（评分的必要条件）。
任务上下文：ZCL任务环境变量已提供（请勿自行生成ID）。
工具执行规则取决于你启动任务的方式：
- 如果是通过
```
zcl suite run --session-isolation process --shim surfwright
```
  启动：Agent应正常调用
```
surfwright ...
```
  命令（无需
```
zcl run
```
  的繁琐流程）。
- 如果未安装shim：所有操作必须通过ZCL漏斗执行（例如
```
zcl run -- ...
```
  ），以确保生成证据。

Turn 2 (Default)

第二轮（默认）

One sentence mission prompt. Example:

"Use the SurfWright CLI to navigate to https://example.com and record TITLE=<...> via

zcl feedback --ok --result ...

单句任务提示。示例：

"使用SurfWright CLI导航至https://example.com，并通过`zcl feedback --ok --result ...`记录TITLE=<...>。"

Turn 3 (Optional)

第三轮（可选）

Only if needed: request structured formatting or classification, but do not lead the agent during discovery.

仅在需要时：请求结构化格式或分类，但在Agent探索过程中不要进行引导。

Expectations (Suite Guardrails)

预期（套件约束）

Suite

expects

can be grounded in:

```
feedback.json
```
(
```
expects.ok
```
,
```
expects.result.*
```
)

trace-derived constraints (

expects.trace.*

), e.g.:

maxToolCallsTotal

maxFailuresTotal

maxRepeatStreak

```
requireCommandPrefix: ["surfwright"]
```
to ensure SurfWright was actually invoked

套件的

expects

配置可基于：

```
feedback.json
```
（
```
expects.ok
```
,
```
expects.result.*
```
）

追踪衍生的约束（

expects.trace.*

），例如：

maxToolCallsTotal

maxFailuresTotal

maxRepeatStreak

```
requireCommandPrefix: ["surfwright"]
```
用于确保实际调用了SurfWright

Local Install (CLI + Skill)

本地安装（CLI + Skill）

zcl

is not on

PATH

(or you want it rebuilt from this checkout):

Build + install the CLI and link the skill:
- ```
scripts/dev-local-install.sh
```
Optional: auto-install on
```
git pull
```
/ branch switch:
- ```
scripts/dev-install-git-hooks.sh
```

如果

zcl

不在

PATH

中（或你想从当前代码库重新构建）：

构建并安装CLI，同时关联Skill：
- ```
scripts/dev-local-install.sh
```
可选：在
```
git pull
```
/ 切换分支时自动安装：
- ```
scripts/dev-install-git-hooks.sh
```