zcl

ZCL Orchestrator（Codex Skill）

此技能适用于协调器（你），而非生成的任务 Agent。

原生运行时边界（当前）

• ZCL 在 zcl suite run 和通过 runner.type=codex_app_server 运行的 campaign 流程中，提供一流的原生运行时执行能力。
• 运行时选择采用基于策略且确定性的方式，通过有序回退链完成（--runtime-strategies、ZCL_RUNTIME_STRATEGIES）。
• 进程运行器模式仍受支持，可作为显式回退方案（--session-isolation process）。
• 原生运行时策略的健康状态和故障类别均采用类型化定义，并在制品／JSON 输出中呈现。

能力矩阵

能力	已实现	已强制执行	备注
原生套件执行（--session-isolation native）	是	是	原生模式下，suite run 禁止使用进程运行器命令。
运行时策略回退链	是	是	有序策略 ID、能力检查、按策略分类的类型化故障。
原生 campaign 运行器（runner.type=codex_app_server）	是	是	无需为每个流程配置 runner.command。
原生事件跟踪映射（tool=native）	是	是	保留脱敏、边界限制和完整性标记。
仅限任务的结果通道定稿	是	是	通过 minResultTurn 支持 3 轮工作流。
提供方接入结构	是	部分	provider_stub 展示了不支持能力时的行为。
运行时故障分类（身份验证／速率限制／流／崩溃／监听器／停滞）	是	是	摘要和反馈故障负载中包含类型化的 ZCL_E_RUNTIME_* 代码。

主要证据：

• .zcl/.../tool.calls.jsonl
• .zcl/.../feedback.json

操作员调用流程

当被要求“通过 ZCL 运行此任务”时，按以下顺序操作：

1. zcl init
2. 可选的运行前检查：
   • zcl update status --json
   • zcl doctor --json
3. 可选的单次尝试分配流程：
   • zcl attempt start --suite <suiteId> --mission <missionId> --prompt <text> --isolation-model native_spawn --json
4. 首选的原生套件流程：
   • zcl suite run --file <suite.(yaml|yml|json)> --session-isolation native --runtime-strategies codex_app_server --feedback-policy auto_fail --finalization-mode auto_from_result_json --result-channel file_json --result-min-turn 3 --campaign-id <campaignId> --progress-jsonl <path|-> --json
5. 进程回退流程：
   • zcl suite run --file <suite.(yaml|yml|json)> --session-isolation process --feedback-policy auto_fail --finalization-mode auto_from_result_json --result-channel file_json --result-min-turn 3 --campaign-id <campaignId> --progress-jsonl <path|-> --shim tool-cli --json -- <runner-cmd> [args...]
6. 一流的 campaign 流程：
   • zcl campaign lint --spec <campaign.(yaml|yml|json)> --json
   • zcl campaign canary --spec <campaign.(yaml|yml|json)> --missions 3 --json
   • zcl campaign run --spec <campaign.(yaml|yml|json)> --json
   • zcl campaign resume --campaign-id <id> --json
   • zcl campaign status --campaign-id <id> --json
   • zcl campaign report --campaign-id <id> --allow-invalid --json
   • zcl campaign publish-check --campaign-id <id> --json
7. 根据制品进行验证／生成报告：
   • zcl report --strict <attemptDir|runDir>
   • zcl validate --strict <attemptDir|runDir>
   • zcl attempt explain --json <attemptDir>

适用于能感知测试框架的提示词的显式定稿流程：

• zcl feedback --ok --result <text> 或 zcl feedback --fail --result-json <json>

运行器防护措施

• 原生套件现在会在执行原生轮次前启动超时计时；原生尝试停滞时会归类为 ZCL_E_RUNTIME_STALL。
• 原生套件编排现在确保失败路径也会生成终态工件（feedback.json + 尽力生成的 attempt.report.json），以便事后分析时保持连续性。
• 如果持久化的 campaign.run.state.json 与当前规范中的任务选择不一致（例如，非空选择的 totalMissions=0），Campaign 读取、报告和恢复命令会快速失败，并返回 ZCL_E_CAMPAIGN_STATE_DRIFT。
• 对于 CI/自动化，建议使用 zcl campaign report --allow-invalid --json 收集报告内容，而不必根据进程退出码进行分支判断；将 zcl campaign publish-check 用作严格的发布门禁。

Campaign 指南

推荐的原生 Codex 工作流：

flows:
  - flowId: codex-native
    runner:
      type: codex_app_server
      sessionIsolation: native
      runtimeStrategies: ["codex_app_server"]
      feedbackPolicy: auto_fail
      freshAgentPerAttempt: true

仅任务的推荐变体：

promptMode: mission_only
flows:
  - flowId: codex-native
    runner:
      type: codex_app_server
      sessionIsolation: native
      runtimeStrategies: ["codex_app_server"]
      finalization:
        mode: auto_from_result_json
        minResultTurn: 3
        resultChannel:
          kind: file_json
          path: mission.result.json

提示词策略

每个 Campaign 只能使用一种模式：

• promptMode: mission_only（首选）：仅包含任务意图和输出约定；不包含运行框架相关术语。
• promptMode: default：允许使用了解运行框架的提示词。

原生模式推荐标准（实测）

在 CI/每夜检查中，满足以下两项时，推荐使用 Codex 原生运行时：

1. 可靠性：原生 20 次并行冒烟测试的成功率 >= 95%。
2. 吞吐量：同一测试在 CI 工作器基准环境中 <= 30 秒内完成。

防护测试路径：

• internal/interfaces/cli/suite_run_integration_test.go（TestSuiteRun_NativeParallelUniqueSessions、TestSuiteRun_NativeSchedulerRateLimitIsDeterministic）。

模板

• examples/campaign.canonical.yaml
• examples/campaign.no-context.comparison.yaml
• examples/campaign.no-context.codex-exec.yaml
• examples/campaign.no-context.codex-subagent.yaml
• examples/campaign.no-context.claude-subagent.yaml
• examples/campaign.native.codex.minimal.yaml
• examples/campaign.native.codex.advanced.yaml
• docs/migration/shell-adapter-to-native-codex.md