Checkmate

一个确定性的 Python 循环（scripts/run.py）调用大语言模型（LLM），分别扮演 worker（执行者）与 judge（评判者）角色。
任何输出都必须通过质量验证才能释放——而你在每一个检查点（checkpoint）都保有完全控制权。

运行要求

• OpenClaw 平台 CLI 工具（openclaw）——必须已加入系统 PATH 环境变量。用于以下操作：
  • openclaw gateway call sessions.list —— 获取会话 UUID，用于注入回合（turn injection）
  • openclaw agent --session-id —— 将检查点消息注入正在运行的会话中
  • openclaw message send —— 作为备用通道投递消息（例如 Telegram、Signal）
• Python 3 —— run.py 仅依赖标准库，无需安装任何 pip 包
• 无需单独配置 API 密钥或环境变量——所有请求均经由网关（gateway）已有的 OAuth 认证流程路由

安全模型与权限机制

⚠️ 这是一个高权限技能（high-privilege skill）。 在批量/自动化模式下启用前，请务必完整阅读本节说明。

所启动的 worker 和 judge 进程将继承完整的 host-agent 运行时权限，包括：

• exec（可执行任意 shell 命令）
• web_search、web_fetch
• 所有已安装的技能（包括那些绑定 OAuth 凭据的技能——如 Gmail、Drive 等）
• sessions_spawn（worker 可进一步生成子代理）

这意味着：你提供的任务描述将直接决定 worker 的行为——请将其视作一段即将执行的代码，而非一条待发送的消息。

批量模式（--no-interactive）将移除全部人工干预环节。 在交互模式（默认）下，你需要在循环继续前，手动批准每一轮的质量标准（criteria）与每个检查点；而在批量模式下，质量标准自动通过，整个循环将完全自主运行直至完成——仅建议在你完全信任该任务内容与运行环境的前提下启用。

用户输入桥接机制（user-input bridging）会将任意内容写入磁盘。 当你对某个检查点作出回复时，主代理（main agent）会将你的原始回复内容逐字写入工作区（workspace）下的 user-input.md 文件中；编排器（orchestrator）随后读取并据此执行。请勿将未经验证的第三方内容作为检查点回复进行转发。

适用场景

当「正确性」比「速度」更重要时，请使用 Checkmate——即“首次尝试即达标”不可接受的情形。

典型适用场景：

• 必须通过测试或满足明确规范的代码
• 需达到预定义质量门槛的文档或报告
• 需全面覆盖特定范围、严谨深入的研究任务
• 你原本会反复手动迭代直至满意的所有任务

触发短语（满足任一即可）：

• checkmate: TASK
• keep iterating until it passes
• don't stop until done
• until it passes
• quality loop: TASK
• iterate until satisfied
• judge and retry
• keep going until done

架构设计

scripts/run.py  （确定性的 Python while 循环 —— 编排器）
  ├─ 输入循环 [最多 max_intake_iter 次，默认为 5]：
  │    ├─ 草拟质量标准（输入提示 + 任务 + 优化反馈）
  │    ├─ ⏸ 用户审核：展示草稿 → 等待用户批准或反馈
  │    │     若批准 → 锁定 criteria.md
  │    │     若反馈 → 进入下一轮优化迭代
  │    └─ （非交互模式：由 criteria-judge 自动评估代替人工）
  │
  ├─ ⏸ 启动前门控（PRE-START GATE）：展示最终任务与质量标准 → 用户确认“开始”
  │         （此处支持编辑任务 / 取消执行）
  │
  └─ 主循环 [最多 max_iter 次，默认为 10]：
       ├─ Worker：启动代理会话 → 输出至 iter-N/output.md
       │          （完整运行时权限：exec、web_search、全部技能、OAuth 认证）
       ├─ Judge：启动代理会话 → 输出至 iter-N/verdict.md
       ├─ 通过？→ 写入 final-output.md，通知用户，退出
       └─ 失败？→ 提取差距项 → ⏸ 检查点：向用户展示评分与差距项
                     是否继续？→ 下一轮迭代（带 judge 提出的差距项）
                     redirect:X？→ 下一轮迭代（附加用户指定的方向指令）
                     是否终止？→ 结束循环，保留当前最优结果

交互模式（默认）：用户需批准质量标准、确认启动前门控，并审阅每一次失败后的检查点。
批量模式（--no-interactive）：完全自主运行；由 criteria-judge 完成输入阶段评估，不设检查点。

用户输入桥接机制

当编排器需要获取用户输入时，将执行以下步骤：

1. 写入 workspace/pending-input.json（含类型标识及工作区路径）
2. 通过 --recipient 与 --channel 配置的通道发送通知
3. 每 5 秒轮询一次 workspace/user-input.md（最长等待时间由 --checkpoint-timeout 分钟数限定）

主代理充当桥接角色：当 pending-input.json 存在且用户完成回复后，主代理将用户响应内容原样写入 workspace/user-input.md；编排器将自动读取该文件并恢复执行。

每个代理会话均通过如下命令启动：

openclaw agent --session-id  --message  --timeout  --json

所有通信均经由网关 WebSocket，复用现有 OAuth 认证——无需额外 API 密钥。
Worker 拥有完整代理运行时权限：exec、web_search、web_fetch、全部技能、sessions_spawn。

你的职责（主代理）

当 Checkmate 被触发时，请按以下步骤操作：

1. 获取当前会话 UUID（用于直接注入代理回合）：

   openclaw gateway call sessions.list --params '{"limit":1}' --json 
     | python3 -c "import json,sys; s=json.load(sys.stdin)['sessions'][0]; print(s['sessionId'])"
   

   同时记录你的 --recipient（频道用户/聊天 ID）与 --channel（备用通道）。

2. 创建工作区：

   bash /scripts/workspace.sh /tmp "TASK"
   

   命令将输出工作区路径。如有必要，可将完整任务描述写入 workspace/task.md。

3. 运行编排器（后台执行）：

   python3 /scripts/run.py 
     --workspace /tmp/checkmate-TIMESTAMP 
     --task "FULL TASK DESCRIPTION" 
     --max-iter 10 
     --session-uuid YOUR_SESSION_UUID 
     --recipient YOUR_RECIPIENT_ID 
     --channel 
   

   建议配合 exec 并设置 background=true。该进程将持续运行直至任务完成。
   添加 --no-interactive 参数可启用完全自主运行（无用户检查点）。

4. 通知用户：告知 Checkmate 已启动、当前处理的任务内容，并说明用户将通过你配置的通道接收质量标准草稿与检查点消息，以便审阅和批准。

5. 桥接用户回复：当用户对某条检查点消息作出响应后，请检查是否存在 pending-input.json，并将用户回复内容写入 workspace/user-input.md。

用户输入桥接操作指南

当收到检查点消息时（即编排器已向用户发送质量标准/审批/检查点请求），请桥接用户回复：

# 查找当前生效的 pending input
cat /checkmate-*/pending-input.json 2>/dev/null

# 路由用户回复内容
echo "USER REPLY HERE" > /path/to/workspace/user-input.md

编排器每 5 秒轮询一次该文件。一旦写入成功，它将自动恢复执行，并立即删除该文件。

各门控节点支持的用户回复类型：

参数说明

工作区目录结构

memory/checkmate-YYYYMMDD-HHMMSS/
├── task.md               # 任务描述（用户可在启动前编辑）
├── criteria.md           # 输入阶段完成后锁定
├── feedback.md           # 累计的 judge 差距项 + 用户方向指令
├── state.json            # {iteration, status} — 支持断点续跑（resume）
├── pending-input.json    # 等待用户输入时写入；收到回复后自动删除
├── user-input.md         # 主代理将用户回复写入此处；编排器读取后自动删除
├── intake-01/
│   ├── criteria-draft.md
│   ├── criteria-verdict.md  （仅非交互模式使用）
│   └── user-feedback.md     （交互模式：用户审阅评论）
├── iter-01/
│   ├── output.md         # worker 输出
│   └── verdict.md        # judge 评判结果
└── final-output.md       # 任务完成时写入

断点续跑（Resume）

若脚本执行被中断，只需使用相同的 --workspace 参数重新运行即可。它将自动读取 state.json，跳过已完成步骤；已锁定的 criteria.md 将被复用；已完成的 iter-N/output.md 不会重复执行。

提示词（Prompts）

由 run.py 实际调用的提示词：

• prompts/intake.md —— 将任务转换为质量标准草稿
• prompts/criteria-judge.md —— 评估质量标准质量（APPROVED / NEEDS_WORK）——仅用于非交互模式
• prompts/worker.md —— worker 提示词（变量：TASK、CRITERIA、FEEDBACK、ITERATION、MAX_ITER、OUTPUT_PATH）
• prompts/judge.md —— 根据质量标准评估输出结果（PASS / FAIL）

仅作参考（run.py 不调用）：

• prompts/orchestrator.md —— 架构说明文档，阐释设计原理