前置条件与配置

OpenLogos CLI

版本要求：≥ 0.15.16。RunLogos 1.0.3 起统一以 0.15.16 作为最低版本，安装命令、版本检查与界面提示同源；1.0.2 起在版本不匹配时自动执行 openlogos sync 对齐。
必须在项目根目录运行：所有 openlogos 命令都要先 cd 到 logos/logos.config.json 所在目录，在子目录（如 src/）运行会报 logos.config.json not found。

npm install -g @miniidealab/openlogos@latest
openlogos --version

guard 文件（活跃变更锁）

logos/.openlogos-guard 由 openlogos change <slug> 自动写入、openlogos archive 自动删除；
无 guard 时禁止直接修改源码——先创建变更提案是 launched 项目的硬规则；
同一项目同一时刻只有一个活跃提案；Driver 的运行归属以该锁为事实源。

Agent 准备

Driver 只从已打开的 Agent 标签页中选择执行者，不使用无头会话；
可作为执行者或评审方的 Agent 类型：Claude Code（claude）、Codex（codex）、OpenCode（opencode）、Cursor（cursor）、WorkBuddy（workbuddy）、Qoder（qoder）；普通终端（terminal）不参与派活。安装方法见 Agent 安装指南；
Qoder 与 WorkBuddy 首次进入项目目录时会出现「信任此文件夹」确认，需要先在 Agent 终端里人工确认，再启动驱动；
至少打开 1 个 Agent 才能启动驱动；启用多 Agent Review 需要第 2 个（评审 Agent 必须不同于主 Agent）；
Codex 类 Agent 的用量遥测不可用时，相关额度展示会灰显，不影响驱动。

环境登记表（可选）

项目登记了 logos/environments.yaml 时（OpenLogos CLI ≥ 0.16.7），需要部署的提案按目标环境部署：

目标环境来自提案的部署决策；登记表配置了「提案默认」环境（proposal_default_env）时，Agent 写提案不再逐个追问目标环境；
冒烟按 DEPLOY_DONE 记录的目标环境执行；
在 RunLogos 环境面板「密钥」标签保存的部署密钥，会注入驱动派发的 Agent；
目标环境要求审批或晋级时，部署会停在「等待审批」或「晋级未满足」，这是任何模式都不会自动越过的硬停点。

不建登记表时，驱动按已合并部署方案的既有流程部署，不受影响。登记表的写法与面板操作见环境与部署。

logos.config.json 关键配置段

{
  "agents": [
    { "name": "Agent 2", "type": "claude", "cwd": null, "autoRun": true },
    { "name": "Agent 3", "type": "codex", "cwd": null, "autoRun": true }
  ],
  "driver": {
    "review": {
      "enabled": true,
      "nodes": { "proposal": false, "delta": true, "code": true },
      "authority": "hybrid:2",
      "block_severity": "high",
      "max_rounds": 5,
      "max_findings": 5
    }
  }
}

driver.review 字段说明

字段	默认	说明
`enabled`	`false`	多 Agent Review 总开关（启动弹窗可按次覆盖）
`nodes.proposal / delta / code`	`false / true / true`	三个受审环节的开关
`authority`	`hybrid:2`	冲突处理：`stop`（停下裁决）/ `reviewer`（以评审为准）/ `producer`（以产出为准）/ `hybrid:N`（前 N 轮听评审，之后以产出为准）
`block_severity`	`high`	达到该严重级别的意见才触发驳回处置
`max_rounds`	`5`	评审循环最大轮数（1–20）
`max_findings`	`5`	同一提案评审生命周期的累计 finding 天花板（`0` 表示无限）：首轮锁定意见 ID 后，后续轮次继承剩余预算、只对既有意见做关闭或坚持，不按轮重置名额

其他相关配置

配置	说明
`driver.openAgentBarrier.timeoutMs`	派活完成屏障超时；默认不设即不因等待超时失败，仅正整数才启用
`driver.lockWatchdog.idleMs`	运行锁空转看门狗阈值
`driver.verifyQuality.*`	验收质量门：低通过率阻断归档、最大跳过率、指定变更用例必须执行
`verify.pre_run_command` / `verify.result_path`	全量测试预跑命令与结果账本路径
`smoke.command` / `smoke.result_path`	冒烟命令与结果路径
`driver.smoke.timeoutMs`	驱动运行冒烟的超时，默认 30 分钟（1.0.4 起，此前默认 120 秒），大型项目的冒烟不再因超时被误判失败
merge 时限	驱动执行 `openlogos merge` 的时限固定为 5 分钟，不可配置；超时后停在「merge 超时」

测试与 Reporter 要求

被驱动项目的测试代码必须包含 OpenLogos reporter：每个用例执行后把 { id, status, timestamp, duration_ms } 写入 logos/resources/verify/test-results.jsonl。openlogos verify 依赖该账本做三层追溯——上报的每个 ID 必须在 logos/resources/test/ 规格中有定义行，且全部已定义用例都需被执行覆盖。