cbx-orch

CBX Orchestrator (cbx)

English overview: README.en.md · 完整中文文档见本文件

基于 Node.js + TypeScript 的本地编排器，把任意 AI 编码 CLI（CodeBuddy / OpenCode / Pi 等）固成一条可持久化的流水线：

创建任务 → 执行 → 保存原始日志 → 跑测试 → 生成 diff → 审查 → 必要时返工

任务状态、事件流、测试日志、diff、审查报告全部落盘，进程崩溃后仍可恢复与续跑。

为什么需要 cbx

直接在终端里跑 agent CLI，每次都是一次性会话：进程一崩任务就丢，批量任务只能逐个盯，做完好坏全凭 agent 自评，换一家 CLI 工作流推倒重来。cbx 把委派变成一条可持久化、可验证、可并发的流水线：

• 崩溃可恢复：SQLite（WAL + 版本化 migration）持久化状态与事件流，worker 心跳 + 回收熔断 + fencing token 租约；执行中途崩溃留下的是可续跑的任务，不是黑盒。
• 执行器无关：一个编排器驾驭 5 个内置 CLI 适配器，新 agent 放一个 JSON spec 即接入（auto 按能力声明路由），不绑定任何一家厂商。
• 完成有证据：测试门 + 独立审查 agent 交叉验证 + SHA-256 完成证据门 + 可选审批门（beforeRun/beforeComplete）。done 意味着证据存在，而不是 agent 宣称完成。
• 隔离与并发：默认 git worktree 隔离、脏基线检测；队列 + 并发上限 + 批量波次，dependsOn 依赖层在独立 worktree 中物理并行。
• 治理内建：严格配置 schema、事件脱敏、插件路径/SHA-256 白名单、依赖锁文件守卫、保留期清理。
• agent 原生控制面：CLI / Web UI / TUI / MCP（stdio + HTTP）/ ZCode·Claude Code 插件五入口共享同一套原语——宿主 agent 可把长任务委派给 detached worker 增量轮询。

边界（有意为之）：--isolated 只是 Git worktree 隔离，不是 OS 沙箱；OS 级隔离外包给 runner 插件（容器）。单机单用户、仅绑定回环；远程访问须置于带认证的反向代理之后。

快速开始

全局安装（发布到 npm 后）：

npm install -g cbx-orch

开发模式（从源码构建）：

npm install
npm run build

源码仓库不包含 dist/；以下 node .../dist/src/cli.js 示例均以已经执行上述安装和构建命令为前提。若通过 npm 全局安装，则可直接把 node .../dist/src/cli.js 替换为 cbx。

在目标代码仓库中运行（默认执行器为 codebuddy）：

node C:\path\to\cbx-orch\dist\src\cli.js run `
  --workspace . `
  --task "实现用户登录功能" `
  --test "npm test" `
  --timeout-ms 1800000 `
  --max-retries 1 `
  --review

指定执行器（例如 OpenCode）：

node dist\src\cli.js run --workspace . --executor opencode --task "修复登录 bug" --test "npm test" --review

查询任务：

node dist\src\cli.js status JOB_ID
node dist\src\cli.js review JOB_ID
node dist\src\cli.js continue JOB_ID --message "修复 review.md 中的问题"
node dist\src\cli.js clean JOB_ID

默认任务数据保存在目标仓库的 .cbx/jobs/<job-id>/，包括需求、状态、原始事件流、测试日志、diff 和审查报告。

架构概览

任务状态机

stateDiagram-v2
    [*] --> queued: cbx run / start
    queued --> awaiting_approval: approval.beforeRun
    awaiting_approval --> running: cbx approve
    queued --> running: dispatch / serve 调度
    running --> done: 执行成功
    running --> failed: 执行器崩溃 / 超时
    running --> needs_fix: 测试失败
    running --> review_failed: review FAIL
    needs_fix --> running: cbx continue
    review_failed --> running: cbx continue
    failed --> queued: cbx retry
    running --> cancelled: cbx cancel
    needs_fix --> cancelled: cbx cancel
    review_failed --> cancelled: cbx cancel
    done --> [*]
    cancelled --> [*]

执行流水线

sequenceDiagram
    autonumber
    participant U as User
    participant C as cbx CLI
    participant Q as Queue (SQLite)
    participant W as Worker
    participant E as Executor
    participant T as Test
    participant R as Reviewer

    U->>C: cbx run --task "..."
    C->>Q: createJob + enqueue
    Q->>W: dispatch (serve / dispatch)
    W->>E: spawn executor
    E-->>W: handback.md
    W->>T: run testCommand
    alt test pass && review enabled
        W->>R: spawn reviewExecutor
        R-->>W: review.md
    end
    W->>Q: finalize state
    Q-->>U: done / failed / needs_fix / review_failed

系统组件

graph LR
    CLI[cbx CLI] --> DB[(SQLite .cbx/state.sqlite)]
    CLI --> Git[Git worktree]
    CLI --> Web[Web UI Server]
    Web --> Browser[Browser Dashboard]
    CLI --> MCP[MCP Server]
    MCP --> ZCode[ZCode / Claude Code]
    DB --> Events[events.ndjson]
    DB --> Telemetry[telemetry.ndjson]
    DB --> Outbox[delivery outbox]

执行器

executor 决定编排器实际调用哪个编码 CLI。内置 5 个适配器，也可指向自定义 ESM 插件。

执行器	注册名 / 别名	二进制	一次性调用	安装	覆盖 env
CodeBuddy	codebuddy / cbc	codebuddy	-p "<prompt>" --output-format stream-json --max-turns N --permission-mode M	npm i -g @tencent-ai/codebuddy-code	CBX_CODEBUDDY
OpenCode	opencode	opencode	run "<prompt>" --format json [--auto]	npm i -g opencode-ai	CBX_OPENCODE
Oh My Pi	omp / oh-my-pi	omp	-p "<prompt>" --mode json	npm i -g @oh-my-pi/pi-coding-agent	CBX_OMP
Cline	cline	cline	--json "<prompt>" --auto-approve true|false [--plan]	npm i -g cline	CBX_CLINE
Qwen Code	qwen	qwen	--prompt "<prompt>" --output-format stream-json --max-session-turns N [--yolo | --approval-mode plan]	npm i -g @qwen-code/qwen-code	CBX_QWEN

说明：

• oh-my-pi 是 Oh My Pi 的扩展框架，本身不是独立二进制，因此作为 omp 的别名。
• --auto（OpenCode）仅在 permissionMode 为 auto 或 dontAsk 时追加。Cline 始终显式传 --auto-approve：auto/dontAsk 为 true，default/acceptEdits/plan 为 false；plan 还会追加 --plan。
• Oh My Pi 的 CLI 文档未公开权限/放行 flag，因此当前不追加任何权限参数，由 omp 非交互 -p 默认行为决定；待其暴露后补齐。
• Cline 在 headless 模式默认 auto-approve=true，因此 cbx 对非自动模式显式关闭，避免受限权限被静默放宽。
• Qwen Code：permissionMode 映射为 plan → --approval-mode plan、auto/dontAsk → --yolo；maxTurns → --max-session-turns。无人值守场景建议在宿主环境设 QWEN_CODE_UNATTENDED_RETRY=1，子进程经 runProcess 自动继承以重试 429/529 瞬时错误。
• 仅 CodeBuddy（--max-turns）与 Qwen Code（--max-session-turns）支持轮数预算；OpenCode / Oh My Pi / Cline 靠 --timeout-ms 兜底。
• 通过对应的 env 变量可覆盖二进制路径，常用于测试或指向自定义脚本。
• 自定义插件：executor 指向一个 ESM 模块路径，模块导出 run(request)，返回 { code, output, timedOut }。示例见 plugins/example-executor.mjs。

Agent 注册与自动发现

全部 executor（含内置 5 个适配器，声明见 src/executors/specs.ts 的 BUILTIN_SPECS）共用同一 AgentSpec 契约：新增 CLI 无需改代码，在工作区 .cbx/agents/（项目级，可随仓库分发）或 ~/.cbx/agents/（用户级）放置一个 JSON spec 即可被自动发现并注册。同名时 workspace 覆盖用户级；内置注册名不可被覆盖。

供应链门禁（workspace 级 spec）：克隆来的仓库可以让 cbx 执行任意二进制（workspace spec 覆盖用户级），因此 workspace 级 spec 默认需要仓外审批——审批存储在 ~/.cbx/approved-specs.json 并按 spec 文件内容哈希绑定（spec 被改动后审批自动失效）。未批准的 spec 会被忽略并在 cbx agents 的 errors 里给出指引：

cbx agents approve myagent   # 批准单个（按当前内容哈希）
cbx agents approve --all     # 批准当前 workspace 全部 spec

逃生阀与强约束：.cbx.json 的 execution.workspaceAgents="allow" 恢复旧行为（全部放行）；governed 档位强制拒绝 workspace 级 spec（allow 也不生效）。用户级（~/.cbx/agents/）与内置执行器不受门禁影响。

{
  "name": "gemini",
  "aliases": ["gca"],
  "label": "Gemini CLI",
  "candidates": ["gemini"],
  "args": ["-p", "{prompt}", "--output-format", "json"],
  "autoArgs": ["--yolo"],
  "planArgs": ["--approval-mode", "plan"],
  "maxTurnsArg": "--max-turns",
  "capabilities": ["backend", "python"],
  "version": "1.0.0"
}

字段说明：name（小写字母/数字/._-，不可与内置冲突）、aliases（可选，resolveExecutor 同样命中）、label（显示名，用于阶段日志与错误消息）、candidates（PATH 上依次尝试的二进制名）、args（参数模板，支持 {prompt} / {maxTurns} / {permissionMode} / {auto} 占位符，{auto} 在 auto/dontAsk 模式渲染为 "true"、否则 "false"）、autoArgs（permissionMode 为 auto/dontAsk 时追加）、planArgs（plan 时追加）、maxTurnsArg（设置后追加 <maxTurnsArg> <maxTurns>）、modelArg（可选，模型选择 flag 如 --model；任务/配置指定 model 时追加 <modelArg> <model>——内置 CLI 未验证各家模型 flag 前不声明，文件 spec 可立即使用）、resumeArg（可选，会话续跑 flag 如 --resume；同 stage 的重试/修复轮存在上一轮会话 id 时追加 <resumeArg> <sessionId> 续接对话——见下文「会话续跑」）、envVar（可选，缺省由 name 派生为 CBX_<NAME>，用于覆盖二进制路径）、capabilities（可选，声明该 agent 擅长的领域/技术标签，如 ["frontend","react"]；供 auto 路由做能力匹配，缺省表示不可作为自动路由候选）。

注册后 --executor gemini 与 stage 的 executor: "gemini" 直接可用。查看注册结果与二进制可用性：

cbx agents --workspace .                # 表格视图
cbx agents --workspace . --json         # 机器可读
curl http://127.0.0.1:4173/api/agents  # Web UI 同款数据

spec 校验失败（缺字段、name 冲突）不会中断其他 agent 的注册，错误会聚合展示在 cbx agents 输出与 /api/agents 响应的 errors 字段中。

cbx agents 表格与 /api/agents（以及 --json）同时展示每个执行器在本 workspace 的历史战绩（Runs/OK%/AvgTok：终态任务数、成功率、均值 token）。战绩是从 .cbx/jobs/ 现场聚合的只读投影，不引入新持久化状态——被 purge 的任务自然退出战绩；无历史的 agent 显示 —（JSON 中 stats: null）。

Agent 路由（executor=auto）

除显式声明执行器外，可把 executor 或 review_executor 设为保留字 auto，在执行任务前由路由层自动选 agent：按各 agent 声明的 capabilities 与任务文本做确定性能力匹配打分（命中标签越多分越高，大小写不敏感；ASCII 单词用词边界匹配避免误伤子串，中文/短语走整串包含），从已探测可用（available=true）的 agent 中选得分最高者。声明式执行器永远优先，路由只兜底「未指定 / 指定 auto」的任务（渐进式，向后兼容）。路由决策（选中者、得分、排名、说明）落盘到任务 context.json 的 routing 字段供审计。

• 无可用 agent 命中能力时回退默认 codebuddy。
• 启用审查且 review_executor=auto（或 executor=auto 且未显式指定审查者）时，路由一个避开主执行 agent 的交叉验证者做独立审查；找不到其它可路由 agent 时回退主执行 agent 自审。
• 能力同分按历史战绩决胜：能力分并列时，按 Laplace 平滑成功率（(done+1)/(runs+2)，无历史得中性先验 0.5，小样本不被极端化）降序、再按均值 token 升序选优——在本 workspace 连败、烧 token 的 agent 会让位于同能力下战绩更好的 agent。决胜依据（各家的次数/成功率/token）写入 routing.notes 审计。战绩口径：仅终态任务（done/failed/needs_fix/review_failed；cancelled 不计），按主执行 executor 归因（context.executor）。
• 任务分类加权：任务文本经确定性分类器（src/task-category.ts）归入 bugfix/performance/refactor/testing/docs/feature/chore，分类持久化到 context.taskCategory；战绩层按 (executor × 分类) 聚合成功率，路由同层决胜优先用分类样本的平滑成功率（无分类样本回退全局、无历史回退中性先验）——agent 可能「修 bug 很行、做新功能不行」，分类口径比全局更能反映本次任务的契合度，且可以推翻全局口径。分类依据写入 routing.notes 审计。
• 路由策略（routingStrategy）：executor=auto 时可声明选人偏好——best（缺省，战绩决胜）、cheapest（能力同层内按均值 token 升序）、fastest（同层按平均任务墙钟升序）。策略窗口是最高能力分层：能力契合不可被成本/时延偏好交换，策略只在能力同分的候选间选优。数据源是执行器战绩（cbx agents 的 AvgTok/AvgSec 列）；无该指标样本的 agent 排后，同层全无样本时降级为战绩决胜并记 note；「多跑零成」（≥2 次且 0 成）的 agent 被剔除——快速失败的"便宜"是假象。策略在任务创建时定档并持久化到 context.routingStrategy，失败降级链重路由遵守同一策略。入口：.cbx.json 的 routingStrategy、CLI --routing-strategy、MCP 与 Web 请求体的 routing_strategy、任务模板的 routingStrategy；优先级为入口显式值 > 模板 > 配置文件。审查路由（交叉验证者）固定 best——审查要质量，不为成本牺牲。
• 执行失败降级链：executor=auto 的任务在执行器失败（崩溃、非零退出、超时）触发执行重试时，重新路由（排除已尝试的 agent）换下一个候选，而不是让同一个失败的 agent 原样再跑一遍；重路由使用最新的可用性探测与战绩，且吃既有执行重试预算（不新增尝试次数）。降级链持久化到 context.routing.fallbacks，并落 executor_fallback 事件（from/to/reason/ranked）供审计；context.executor 随之更新，之后 cbx retry 从降级后的 agent 起步继续走链，不会回头吃已失败的 agent。边界：显式声明的 executor（非 auto）不降级——尊重任务作者的选择；taskContract 中显式指定 executor 的 stage 同样不降级；测试/审查失败仍走同 agent 的 fix 循环（那是「活干坏了」，不是「harness 坏了」）。
• 路由打分是纯函数（无 I/O、无 LLM），见 src/executors/route.ts。
• 设计取舍：路由层不引入 LLM 打分作为第二档。路由发生在选定执行器之前——LLM 评分自身就得先调起一个 agent（用谁评？这本身就是一个路由决策）；且路由决策落盘 context.routing 供审计，LLM 输出不可复现会破坏审计语义，还给每次任务创建增加延迟与外部失败模式。需要 LLM 参与决策时走 adaptive 模式（manager executor 每轮决策），两层职责不混合。

消融对照（--ablate）

npm run bench:agents -- --executor <name> --ablate review（或 decompose）：同一套件跑「基准 vs 关闭该模块」两轮，输出成功率/均值 token/均值墙钟的贡献差——质量相关改动的收益不再靠直觉论证。真实首跑参考（codebuddy ×3 任务）：review 开关成功率 3/3→3/3、token +2.7%、墙钟 +20%，校验模块成本温和。

Agent 基准校准（bench）

路由的战绩来自真实任务历史；npm run bench:agents（先 npm run build）用一个小的确定性任务套件主动校准：对每个可用执行器 × 每个任务在全新临时 git 仓库里跑真实 job（种子文件先提交，任务间互不污染），汇总各执行器的成功率、均值 token、任务墙钟与分类分布——与战绩层同口径。

npm run build
npm run bench:agents                        # 全部可用执行器 × 内置套件（feature/bugfix/feature）
npm run bench:agents -- --executor qwen     # 只校准指定执行器（可重复）
npm run bench:agents -- --tasks bench.json  # 自定义套件：[{ "task": "...", "test": "node -e ...", "seed": [{ "path": "...", "body": "..." }] }]

基准跑在真实 workspace 时，结果任务自然进入该 workspace 的战绩（喂给 auto 路由）。会真实调用编码 CLI（消耗 token/网络/凭据），仅适合本地人工或手动触发；任一执行器 0 成功时非零退出（校准信号：该 agent 不可用或契约不兼容）。

项目配置

在目标仓库根目录放置 .cbx.json，命令行参数会覆盖配置文件：

{
  "executor": "codebuddy",
  "profile": "verified",
  "testCommand": "npm test",
  "review": true,
  "isolated": true,
  "timeoutMs": 1800000,
  "maxRetries": 1,
  "maxTurns": 50,
  "maxConcurrent": 2,
  "reviewRules": "重点检查鉴权、数据校验和回归测试。",
  "approval": { "beforeRun": true, "beforeComplete": false },
  "git": {
    "autoBranch": true,
    "autoCommit": true,
    "commitMessage": "chore: apply task"
  },
  "execution": {
    "trustMode": "trusted",
    "runner": "./my-container-runner.mjs"
  },
  "dependencyGuard": true,
  "templates": {
    "bugfix": {
      "task": "修复 review.md 中的问题",
      "test": "npm test",
      "review": true,
      "profile": "verified"
    },
    "feature": { "task": "实现新功能", "executor": "opencode" }
  },
  "adaptive": {
    "enabled": false,
    "maxRounds": 8,
    "managerExecutor": "codebuddy"
  },
  "cost": {
    "tokenBudget": 200000
  },
  "execution": {
    "autoDecompose": false
  },
  "context": {
    "tokenBudget": {
      "manager": 6000,
      "executor": 8000,
      "auditor": 8000
    }
  },
  "notifications": {
    "webhook": "https://example.test/cbx-events",
    "timeoutMs": 3000,
    "maxRetries": 2,
    "retryBaseMs": 100,
    "filters": {
      "events": ["job.state_changed"],
      "jobIds": ["job-123"],
      "statuses": ["done", "failed"]
    }
  },
  "telemetry": {
    "enabled": true,
    "endpoint": "http://localhost:4318/v1/traces",
    "serviceName": "cbx-orchestrator"
  },
  "governance": {
    "retentionDays": 30,
    "pruneJobs": true,
    "redactFields": ["token", "password", "authorization"]
  },
  "ui": {
    "token": "your-secret-token"
  }
}

任务模板

任务模板来自目标仓库 .cbx.json 的 templates 字段。查看当前 workspace 的模板目录：

cbx templates --workspace .
cbx templates --workspace . --json

默认输出每个模板的名称、profile 和 task 摘要；--json 输出 { "templates": [...] }，便于脚本读取。模板可设置 task、test、review、executor、isolated 和可选的 profile（fast/verified/governed/untrusted）：

{
  "templates": {
    "bugfix": {
      "task": "修复 review.md 中的问题",
      "test": "npm test",
      "review": true,
      "profile": "verified"
    }
  }
}

使用 cbx run 或 cbx start 的 --template <name> 展开模板。profile 的优先级为：CLI 显式 --profile > 模板 profile > 配置文件顶层 profile。

cbx start --workspace . --template bugfix
cbx start --workspace . --template bugfix --profile fast

执行档位（Execution Profiles）

profile 可写在 .cbx.json 顶层，也可通过 CLI --profile fast|verified|governed|untrusted、MCP cbx_start.profile 或 Web 请求体的 profile 传入。入口显式传入的 profile 会覆盖配置文件值。四档预设如下：

档位	默认行为与创建硬约束
fast	默认不启用 Git worktree 隔离（isolated=false）和独立审查（review=false），不强制测试命令；信任模式为 trusted。
verified	默认启用隔离与独立审查（isolated=true、review=true）；必须提供非空测试命令。
governed	verified 的约束，再要求依赖锁文件守卫（dependencyGuard=true）和完成前人工审批（approval.beforeComplete=true）。
untrusted	governed 的约束，并要求 trustMode=untrusted；还必须配置提供容器级隔离的 execution.runner，否则创建会被拒绝。

显式字段会覆盖 profile 的默认值，但覆盖后的配置仍必须满足对应硬约束；例如 verified 显式设置 review=false 或 isolated=false 会在任务创建阶段拒绝。除 untrusted 外，其余 profile 不允许使用 trustMode=untrusted。未设置 profile 时沿用现有字段默认值。

Doctor 诊断

cbx doctor 是只读环境诊断，不创建任务、不写工作区，也不会启动任何 Agent。它检查 Node.js >= 22、workspace 目录、.cbx.json 配置与 profile 硬约束、Git、executor 可用性，以及 untrusted 模式所需的 runner 文件：

node dist/src/cli.js doctor --workspace .
node dist/src/cli.js doctor --workspace . --json

默认输出人类可读的逐项状态；--json 输出包含 checks 的机器可读报告。任一检查为 fail 时返回非零退出码；只有 warn 或 pass 时返回 0。

cbx doctor --probe-executor [--executor <name>] 是显式 opt-in 的执行器流探针：对真实编码 CLI 发一个最小 prompt，检查退出码、流事件解析与会话 id 捕获。非只读（会真实调用 CLI、消耗少量 token），用于复核任务事件流里的 stream_events_empty 警告与上游 CLI 流格式漂移——日志页签/实时流/会话续跑都依赖流解析，格式漂移时此探针是第一诊断入口。日常本地验证可跑 npm run test:live（真实 codebuddy 流格式契约测试，CI 与默认 npm test 自动跳过）。

任务管理：

node dist/src/cli.js doctor --workspace .                   # 只读环境诊断
node dist/src/cli.js doctor --workspace . --json            # 输出机器可读诊断报告
node dist/src/cli.js list --workspace .
node dist/src/cli.js list --limit 50 --workspace .    # 只列出最近 50 条（updated_at 倒序）
node dist/src/cli.js list --all --workspace A --workspace B            # 跨 workspace 列出任务（带前缀）
node dist/src/cli.js ws --workspace A --workspace B                   # 跨 workspace 汇总（任务/队列/健康）
node dist/src/cli.js ws --workspaces-dir ~/code                       # 扫描含 .cbx 的子目录汇总
node dist/src/cli.js health --all --workspaces-dir ~/code             # 跨 workspace 健康汇总
node dist/src/cli.js batch --task "任务A" --task "任务B" --workspace .       # 批量创建任务
node dist/src/cli.js batch --task "A" --max-batch 2 --wait --workspace .    # 波次并发 + 等待终态汇总
node dist/src/cli.js logs JOB_ID --workspace .
node dist/src/cli.js files JOB_ID --workspace .                     # 列出任务 artifact 文件（读内容用 result/review/logs）
node dist/src/cli.js result JOB_ID --workspace .
node dist/src/cli.js export JOB_ID [--format text|markdown] --workspace .
node dist/src/cli.js approve JOB_ID --workspace .
node dist/src/cli.js queue --workspace .
node dist/src/cli.js queue pause --workspace .
node dist/src/cli.js queue resume --workspace .
node dist/src/cli.js retry JOB_ID --priority 10 --workspace .
node dist/src/cli.js watch JOB_ID --ci --workspace .
node dist/src/cli.js review-gate --workspace .          # 对工作区未提交改动跑独立审查（非零退出 = 有发现）
node dist/src/cli.js stop-review-gate                   # Stop hook 入口（stdin 读 cwd，fail-open 契约）
node dist/src/cli.js version                            # 输出版本号（等价 --version / -v）
node dist/src/cli.js --help                             # 显示用法

cbx batch 批量创建独立任务：--task/--task-file 可重复（可混用）；run 选项（--executor/--review/--isolated 等）透传到每个任务。--max-batch N 将批任务按 N 个一波分片入队（波间等上一波终态，不改变全局 maxConcurrent）；默认 0 = 一次全量入队。--wait 等待全部终态并输出成功/失败计数，超时（--wait-timeout-ms）返回未完成列表并以非零退出；批任务 job 与普通任务同构，可独立 retry/continue。

本地 Web UI / TUI

node dist/src/cli.js ui --workspace . --port 4173 node dist/src/cli.js ui --workspace . --port 4173 --ui-token your-secret-token node dist/src/cli.js tui --workspace .

多 workspace 模式:一个 UI 看多个项目,顶部 workspace 选择器 + Dashboard 卡片

node dist/src/cli.js ui --workspace ~/code/proj-a --workspace ~/code/proj-b --port 4173 node dist/src/cli.js ui --workspaces-dir ~/code --port 4173 # 仅扫描直接子目录（1 层，不递归）

单 workspace 时 ws-list 自动隐藏;Dashboard 卡片和实时秒表对单/多模式都生效

Web UI 接口（直接可读）

curl http://127.0.0.1:4173/ # HTML 仪表板 curl http://127.0.0.1:4173/events # SSE 实时事件流（支持 Last-Event-ID 回放） curl http://127.0.0.1:4173/api/workspaces # 所有 workspace 状态摘要 curl http://127.0.0.1:4173/api/jobs # 任务列表 curl http://127.0.0.1:4173/api/jobs/ # 单个任务详情 curl http://127.0.0.1:4173/api/jobs//artifacts # 可用 artifact 列表 curl http://127.0.0.1:4173/api/jobs//artifact/ # 读取 artifact（handback.md / complete.patch / test.log / review.md 等） curl http://127.0.0.1:4173/api/jobs//timeline # 阶段时间线(stages + currentStage + elapsedSec) curl http://127.0.0.1:4173/api/jobs//executor # PID/heartbeat/命令 + 进程是否还活 curl http://127.0.0.1:4173/api/jobs//agent.log?since=0 # agent.log 增量(默认 256KB) curl http://127.0.0.1:4173/api/jobs//events?since=0 # 任务事件流增量（浏览器「日志」页签数据源：全量历史 + 类型过滤/搜索 + 运行中 2s 跟随） curl http://127.0.0.1:4173/api/queue # 队列状态 curl http://127.0.0.1:4173/healthz # 健康检查 curl http://127.0.0.1:4173/api/metrics # 运行指标 curl http://127.0.0.1:4173/openapi.json # OpenAPI 3.1 文档（全部端点的机器可读说明书，无需鉴权）

Web UI 写操作（POST，需鉴权；浏览器自动携带 HttpOnly cookie，curl 需 Authorization: Bearer ）

curl -X POST http://127.0.0.1:4173/api/jobs//cancel # 取消任务 curl -X POST http://127.0.0.1:4173/api/jobs//retry # 重试失败任务 curl -X POST http://127.0.0.1:4173/api/jobs//approve # 批准等待中的任务（before_run 批准后自动启动） curl -X POST http://127.0.0.1:4173/api/jobs//continue # 续跑（body: {message, priority, refresh_baseline, extra_rounds}） curl -X POST http://127.0.0.1:4173/api/queue/pause # 暂停队列 curl -X POST http://127.0.0.1:4173/api/queue/resume # 恢复队列

创建任务（等价 CLI cbx start；body 支持 task 必填 + test_command/review/isolated/executor/max_turns/permission_mode/approval_before_run/dependency_guard 等 run 选项）

curl -X POST http://127.0.0.1:4173/api/jobs -H "content-type: application/json" -d '{"task":"实现登录功能"}'

CI 模式：任务失败时返回非 0 退出码

node dist/src/cli.js run --ci --workspace . --task "实现某功能" --test "npm test"

单次调度：回收死 worker 并启动排队任务

node dist/src/cli.js dispatch --workspace .

常驻调度器：启动时回收死 worker，随后按间隔调度；SIGINT/SIGTERM 会停止调度器

node dist/src/cli.js serve --workspace . --interval-ms 30000

不含任务正文的健康与运行指标

node dist/src/cli.js health --workspace .

`ui` 命令支持 token 鉴权：通过 `--ui-token <token>` 或 `.cbx.json` 的 `ui.token` 配置。启用后浏览器首次加载首页会收到 `cbx_token` HttpOnly cookie（`SameSite=Strict`），同源 API/SSE 请求自动携带——token 不进入页面 JS 作用域、不出现在 URL 查询串，降低 XSS 与浏览器历史泄露面。curl/API 客户端仍可用 `Authorization: Bearer <token>` 请求头；SSE 兼容旧客户端可传 `?token=<token>` 查询参数。`/healthz` 健康检查、`/` 首页与 `/openapi.json` 无需 token。

### OpenAPI 文档

`cbx ui` 启动的 server 在 `/openapi.json` 暴露 OpenAPI 3.1 文档，覆盖全部 REST 端点（路径/入参/响应/鉴权方式）。可直接粘进 [Swagger Editor](https://editor.swagger.io) 浏览，或用生成器产出客户端 SDK：

```powershell
npx @openapitools/openapi-generator-cli generate -i http://127.0.0.1:4173/openapi.json -g python -o ./cbx-client
```

文档与 `ui.ts` 路由的一致性由 `tests/openapi.test.ts` 保证：文档声明的端点必须真实可响应、未声明的路径返回 404，新增端点时两边同步更新。

### SSE 事件回放

`/events` 端点支持标准 `Last-Event-ID` 回放机制：每个事件携带 workspace 内单调递增的 `seq`（持久化于 SQLite，进程重启后续编）。客户端连接时带上 `Last-Event-ID` 头（或 `?last_event_id=` query），服务端自动补发 `seq > lastEventId` 的历史事件（上限 1000 条，超限发 `replay_truncated` 警告并只补最近 N 条）。浏览器 `EventSource` 在断线重连时自动携带 lastEventId，无需前端改动。无 lastEventId 时只推新事件（保持旧行为）。

### 执行器流式事件实时广播

Web UI 进程会自动发现 `running` 状态的任务并尾随其 `events.ndjson`，把新增的 `executor_stream_event`（思考/工具调用/文本）实时广播到 `/events`——浏览器里的事件流面板对运行中任务是真正的实时视图。设计边界：流式事件只广播不持久化到 workspace 总线（不污染审计事件流、不消耗 seq），也不参与 `Last-Event-ID` 回放（断线重连只补状态事件，流式历史走 `/api/jobs/<id>/events` 或任务详情的「日志」页签）。实时性受 worker 侧写缓冲（128 行/64KB 批量落盘）影响，突发任务的事件可能成批到达。

### 事件可见延迟预算

「实时」视图的最坏路径为三级延迟（常量单处汇总于 `src/timing.ts`，调整时同步本图）：

```
执行器输出发生
  │ worker 写缓冲：128 行 / 64KB 批量落盘（EVENT_BUFFER_*，突发任务成批可见）
  ▼
events.ndjson
  │ UI per-job tailer：500ms 轮询（EVENT_TAILER_POLL_MS；Windows fs.watch 不可靠，统一轮询）
  ▼
SSE 广播（首次发现 running 任务另有 ≤2s 监督器扫描间隔 JOB_STREAM_SCAN_INTERVAL_MS）
```

状态事件（`job.state_changed`）不经写缓冲、同轮可见；流式事件的完整历史不受此预算影响（走 `/api/jobs/<id>/events` 字节游标增量读）。

### 会话续跑（--resume）

内置 codebuddy 适配器声明了 `resumeArg: "--resume"`：从执行器流式输出捕获 CLI 原生会话 id（`session_id`），**同 stage 同执行器**的重试/修复轮自动带 `--resume <sessionId>` 续接上一轮对话——agent 不必重读全部上下文工件，修复轮更快、更省 token。会话持久化在每个 stage 的私有目录（`stage-artifacts/<index>/session.json`，按 stage 隔离、并行 stage 零冲突），`cbx continue` / 队列重派 / 崩溃回收后的新 run **首轮执行即续接**上一 run 的会话。

边界与治理：执行失败/超时（会话可能损坏）、降级换 agent 后自动失效；review 角色永不续跑（独立审查要新鲜视角）；同一会话最多续跑 5 轮，超限自动回收并全新开始（防上下文单调膨胀）；全程落 `session_resumed` / `session_dropped` / `session_recycled` 观测事件。

### 上下文包 token 预算

上下文包在打包时按 per-role token 预算裁剪（启发式估算：ASCII ≈ chars/4，CJK ≈ chars/1.5）。默认 manager 6000 / executor 8000 / auditor 8000 tokens，可经 `.cbx.json` 的 `context.tokenBudget.{manager,executor,auditor}` 覆盖（最小 100）。超预算时按优先级裁剪 taskContract 低优先字段（assumptions/rejectedOptions/decisions → constraints/relevantFiles → nonGoals；goal + acceptanceCriteria + stages 永不裁剪），再裁 recentFailure.retryReason 与 userInstructions。触发裁剪时 pack 标记 `truncated: true` 并记录 `estimatedTokens`。既有 24K 字符硬上限仍作为最终兜底。

### 任务成本熔断（cost.tokenBudget）

`.cbx.json` 的 `cost.tokenBudget` 为单个任务的累计 token 上限（创建时定档，运行期改配置不影响已建任务）。累计用量达到上限时任务暂停转 `needs_fix`（phase `cost_budget_exceeded`）并打开 Human Gate 等待人工裁决——防止 fix/重试循环无限烧钱。放行方式：调高预算后 `cbx continue`，或人工确认后重试。

### Stage 依赖声明

`taskContract.stages[].dependsOn` 接受前置 stage name 数组，用于声明阶段间依赖关系：

```json
{
  "taskContract": {
    "goal": "重构认证模块",
    "acceptanceCriteria": ["登录流程通过", "权限校验正确"],
    "stages": [
      { "name": "api", "executor": "codebuddy", "task": "实现后端 API" },
      { "name": "ui", "executor": "codebuddy", "task": "实现前端界面" },
      {
        "name": "integrate",
        "executor": "codebuddy",
        "task": "集成联调",
        "dependsOn": ["api", "ui"]
      }
    ]
  }
}

前置 stage 进入失败终态（review FAIL / 非零退出）后，后继 stage 标记 skipped 而非执行（失败传播），并记 stage_skipped 事件。adaptive 模式不支持 dependsOn（manager 每轮自选 stage、依赖无语义），任务创建时组合二者会被显式拒绝。stage 的 handback 注入会聚合所有 dependsOn stage 的交接文档。悬空依赖（引用不存在的 name）与循环依赖在任务创建时即被拒绝。隔离执行（isolated: true）+ 依赖模式时，同层 stage 物理并行：每个 stage 在独立 worktree 中运行（executor/test/review），层内并发、层间串行，每层完成后按声明顺序把各 stage 的 diff 合并进主 worktree，下一层的 stage worktree 包含全部前置层合并结果——与串行依赖模式的最终语义一致，仅缩短墙钟时间。合并冲突（同层 stage 改动同一文件）会以 needs_fix / stage_merge_conflict 暂停，需修正任务契约（如调整 stage 边界）后 continue。stage 产出物（handback/test.log/review.md）保留在 stage-artifacts/<index>/，最终聚合为 jobDir 证据。非隔离或线性模式保持单 worktree 串行执行，行为不变。

continue 默认将任务重新入队（后台执行）。加 --foreground 走前台同步语义（阻塞至完成）。

配置了 approval.beforeRun 后，任务会先进入 awaiting_approval，批准后才启动执行器。

git.autoCommit 会自动隐含开启 isolated（有提示，避免污染主工作区）；仅在 git.autoBranch 开启时，修改会提交到 cbx/<job-id> 分支，否则落在 worktree 的游离提交上。

后台 worker 是 detached 进程。可使用常驻 serve 监护队列；它启动时会回收死 worker，仍可用 dispatch 供 cron/计划任务执行。

notifications.webhook 接收任务状态事件；事件同时会写入 .cbx/events.ndjson。notifications.filters 可细分订阅：events（事件 type）、jobIds（payload.jobId）、statuses（payload.status）为可选字符串数组，AND 语义（多条件同时满足才投递）；未配置的维度不限制；不匹配的事件不入 outbox（本地 events.ndjson 仍全量）。webhook 和 OTLP 都支持 timeoutMs、maxRetries、retryBaseMs：待投递消息先进入 SQLite durable outbox，状态写入不等待网络；后台按有限指数退避投递，进程提前退出时由后续 cbx 进程继续处理。最终失败会落到 .cbx/delivery-failures.ndjson。任务 span 始终写入 .cbx/telemetry.ndjson 供本地排查；启用 telemetry 后才会按 OTLP/HTTP JSON ...

任务状态、队列、通知 outbox 和死信的权威数据存储在 .cbx/state.sqlite（WAL 模式、版本化 migration）；首次访问会无损导入旧的 .cbx/jobs/*/state.json、queue.json 和 delivery-failures.ndjson。这些 JSON/NDJSON artifact 会继续保留以便人工查看，但不再作为调度一致性的依据；worker 终态与对应队列条目、以及 retry 的状态重置与重新入队，均在同一 SQLite transaction 提交。常驻 serve 使用带续期与 fencing token 的工作区单实例租约，发现另一个存活实例会拒绝启动，丢失租约则主动停止。/healthz 与 /api/metrics、以及 cbx health 返回队列深度、任务状态计数、失败/重试、token 用量（tokensUsed，汇总执行器流内 usage 汇总行；解析不到的执行器保持缺省）、待投递和死信计数，且不包含任务正文。健康检查同时巡检孤儿 worktree（job 已被清理而 .<repo>.cbx-worktrees/ 下遗留的目录，含 stage 变体）：发现即列出路径，cbx clean --orphans 一键清理（优先 git worktree remove，best-effort 删除 cbx/<jobId> 分支；jobDir 仍在的终态遗留不受影响，仍走 cbx clean <jobId>）。

Executor 插件

executor 可以指向一个 ESM 模块。插件应导出版本化 manifest 和 run(request)；manifest 使用 cbx.executor/v1，包含 name、version 和最小能力声明（例如 execute）。示例见 plugins/example-executor.mjs：

{ "executor": "./plugins/example-executor.mjs" }

默认启用严格治理：只要声明 plugins（或未声明但使用 executor 插件），enforce 即默认为 true，必须为插件配置 allowPaths 或 allowSha256，并且每个已配置的 allowlist 都必须匹配；缺少 manifest、未批准路径或摘要都会被拒绝。如需显式回退到旧行为，可设置 plugins.enforce=false（会打印安全告警并记录审计事件）。任务事件只记录内置适配器来源/版本，或插件名称、版本、能力和 SHA-256，不记录环境变量值。

{
  "plugins": {
    "enforce": true,
    "allowPaths": ["./plugins/example-executor.mjs"],
    "allowSha256": ["replace-with-64-hex-character-sha256"]
  }
}

Runner 插件（容器执行）

execution.runner 指向一个 ESM 插件（cbx.runner/v1），把 executor / test / review 命令的进程执行外包给插件——典型用途是为 untrusted 信任模式提供容器级隔离。插件导出 manifest（{ apiVersion: "cbx.runner/v1", name, version }）与 run(request)；request 含 workspace/directory/workdir（host 路径，插件负责映射到容器内）、command（完整 argv）、shell、role（stage/review/manager/gate/test）、timeoutMs、env 与 logFile，返回 { code, timedOut, output }。插件必须在 timeoutMs 内杀掉容器进程（cbx 另有墙钟兜底）。路径穿越防护与 executor 插件一致（realpath 后必须位于 workspace 内）；runner 是可信的隔离边界提供者，无白名单执行子进程。

{
  "execution": { "trustMode": "untrusted", "runner": "./docker-runner.mjs" }
}

配置 runner 后 untrusted 任务放行（仍要求 isolated=true）；未配置时创建 untrusted 任务被拒绝。runner 模式下捕获输出经有界截断写入 agent.log / test.log，不产生流式事件与 active.pid。

质量与发布

npm run check 执行类型 lint、格式检查和测试；npm run coverage 运行 Node 测试覆盖率并按 scripts/check-coverage.mjs 中的最低阈值（lines/branch/functions）校验，低于阈值即失败；npm run audit 检查高危依赖问题；npm run sbom 生成 CycloneDX SBOM。CI 在 Ubuntu、Windows 与 macOS（Node 22、24）上执行这些确定性检查并上传测试、覆盖率和 SBOM 工件——Windows 是一等目标（进程树击杀 taskkill、文件锁与 worktree 路径均有平台分支），macOS 覆盖 Unix 侧进程组击杀与路径分支的第三平台验证。运行时要求 Node.js ≥ 22（与 CI 验证矩阵一致；Node 20 已 EOL 且不在验证范围）。

发布遵循 Semantic Versioning。源码仓库不跟踪 dist/；推送 v* tag 后，.github/workflows/publish.yml 会从源码构建它、运行测试，并用 npm pack --dry-run 校验待发布包确实包含 dist/src/cli.js，然后才发布到 npm（需在仓库 Secrets 配置 NPM_TOKEN）。package.json.files 仍明确限定 npm 包内容为 dist/ 和文档，不包含源码与测试；private 已设为 false。

MCP

最小 MCP 适配器，不依赖 MCP SDK。两种传输：

stdio（默认，向后兼容）：

cbx mcp

streamable HTTP（协议 2025-06-18，支持实时事件推送）：

cbx mcp --http --port 8931 --host 127.0.0.1 [--token <t>]

客户端把 MCP 配置从 command: cbx mcp 改为 url: http://127.0.0.1:8931/mcp（可选 Authorization: Bearer <t> 头）即接入。HTTP 模式启用 resources/subscribe：订阅 cbx://job/<id>/events?workspace=<ws> 后，该任务事件变化会经 SSE 推 notifications/resources/updated（通知为变更信号，数据经 resources/read 读增量 { events, next_offset }）。仅绑定 loopback。

提供的工具：cbx_start、cbx_status、cbx_review、cbx_continue、cbx_artifact、cbx_cancel、cbx_approve、cbx_list、cbx_logs、cbx_result、cbx_queue、cbx_queue_pause、cbx_queue_resume、cbx_retry、cbx_review_gate（对工作区未提交改动跑独立审查，配合 reviewGate.enabled 的 Stop hook）、cbx_clean（清理任务遗留的 Git worktree，对应 CLI cbx clean）、cbx_list_workspaces（扫描指定 root 下含 .cbx/ 的 workspace 并列出各自任务）。

MCP 还提供 resources/list 和 resources/read，可直接读取任务的 result.json、events.ndjson、complete.patch、review.md、stage-*-handback.md 等产物。

permissionMode 为 dontAsk 时，MCP 的 cbx_start 需要显式传 allow_unsafe_permissions: true（对应 CLI 的 --dangerously-skip-permissions），否则任务创建会被拒绝。

非平凡任务可在 cbx_start 中传结构化 task_contract（目标、验收标准、非目标、约束、相关文件、决策与假设）。执行器会先生成 understanding.json；存在阻塞问题时任务以 needs_fix / awaiting_clarification 暂停。创建任务时还会记录 Git commit、branch、dirty 状态及 dirty 内容指纹。isolated: true 且创建基线包含未提交内容时，任务会在创建 worktree 前以 needs_fix / dirty_baseline 暂停，避免未提交内容被静默遗漏；请先提交或清理这些内容，确认当前基线符合预期后再以 refresh_baseline: true 继续。隔离 worktree 随后固定从确认过的 commit 创建。非隔离任务仅在 HEAD 或 dirty 内容指纹相对创建基线发生漂移时暂停，dirty 内容未变时可正常执行。review_executor 可指定独立审查 CLI，默认仍沿用 executor。

cbx_start 还支持：max_turns（正整数）、permission_mode（default/acceptEdits/auto/dontAsk，dontAsk 需 allow_unsafe_permissions: true）、approval_before_run（执行前审批门，对应 approval.beforeRun）、dependency_guard（lockfile 哈希守卫）；task_contract.stages[].depends_on（前置 stage name 数组，对应 CLI 的 dependsOn）。approval_before_complete（测试+审查通过后，落 done 前再停一次审批门，对应 .cbx.json 的 approval.beforeComplete，批准入口同 cbx approve）；adaptive（对象，snake_case 字段 enabled/max_rounds/manager_executor，启用后由独立 manager executor 每轮决策跑哪个 stage，超出 max_rounds 触发 needs_fix / adaptive_max_rounds Human Gate，可用 cbx_continue 的 extra_rounds 续跑；adaptive.enabled=true 要求 review=true）。cbx_continue 支持 extra_rounds（1–100 整数，仅在 max_rounds Human Gate 等待时追加 adaptive 轮次）。

result.json 包含 changed files、handback、stages 数组（每阶段 exit code 与 review verdict）、测试与验收摘要、基线信息、humanGate（人工等待状态）及 artifact SHA-256。最终交付仍应通过 cbx_artifact 或 MCP resources 读取并核对 handback.md、complete.patch、test.log 和 review.md，不要只根据状态元数据总结。

result.json 的 evidenceAvailable 只有在配置了非空测试命令、测试成功且既有 review/证据条件均满足时才为 true，此时 verificationStatus 为 "verified"。未提供测试命令的任务仍可进入 done，但结果必须标记为 evidenceAvailable: false、verificationStatus: "unverified"；占位 test.log 不代表测试已验证。

ZCode 插件

cbx 本身就是一个 ZCode 市场插件（仓库根含 .zcode-plugin/plugin.json、commands/、skills/）。安装后自动注册 cbx MCP server，并提供斜杠命令和技能，无需手写 MCP 配置。

安装

# 1. 全局安装 cbx CLI（提供 cbx / cbx mcp 命令，依赖由 npm 自动解析）
npm install -g cbx-orch

# 2. 添加本仓库为市场源
zcode plugin marketplace add zerosloney/cbx-orch

# 3. 安装 cbx-orch 插件
zcode plugin install cbx-orch@cbx-orch-marketplace

安装后重启 ZCode 会话，插件 manifest 会调用全局安装的 cbx mcp，将 MCP server 自动以 cbx 名注册；工具暴露为 mcp__cbx__cbx_*。因此仅 clone 或安装插件目录并不足以启动 MCP，必须先确保全局 cbx 命令可用。

斜杠命令

命令	作用
/cbx-run [task]	委派任务到 cbx，后台执行（含测试+审查），轮询至完成
/cbx-status [job_id]	查任务状态/阶段/尝试
/cbx-continue [job_id] [message]	按 review.md 或测试失败返工
/cbx-list	列出当前工作区所有任务
/cbx-queue [pause|resume]	查看或控制任务队列

技能

cbx-orchestration 技能文档（skills/cbx-orchestration/SKILL.md）指导 agent 何时用 cbx、如何选执行器、隔离策略。

用户配置

插件安装后，在 ZCode 设置中可配置（对应 userConfig）：

配置项	默认值	作用
executor	codebuddy	默认执行器：codebuddy/opencode/omp/cline/qwen
review	true	测试通过后是否跑独立审查
isolated	true	是否在 git worktree 中隔离执行

工作区定位

插件通过 CBX_WORKSPACE=${CLAUDE_PROJECT_DIR} 把当前项目目录注入 cbx MCP server。调 cbx_* 工具时无需传 workspace 参数，默认即当前项目。

前置依赖

npm 发布包包含可直接运行的 dist/ 编译产物；源码仓库不跟踪该目录。自行 clone 源码后，需先执行 npm install && npm run build 生成 dist/。还需至少安装一个执行器 CLI（codebuddy/opencode/omp/cline/qwen 之一）才能真正执行任务。Stop review-gate hook 通过 cbx stop-review-gate 子命令调用，只依赖全局 cbx 命令，不依赖插件目录内的 dist；MCP server 同样只依赖全局 cbx 命令。

Claude Code 插件

cbx 同时是 Claude Code 市场插件（仓库含 .claude-plugin/plugin.json 与 .claude-plugin/marketplace.json，共用根目录 commands/、skills/、hooks/）。安装后自动注册 cbx MCP server，并提供斜杠命令和技能，无需手写 MCP 配置。

安装

# 1. 全局安装 cbx CLI（提供 cbx / cbx mcp 命令，依赖由 npm 自动解析）
npm install -g cbx-orch

# 2. 添加本仓库为市场源
claude plugin marketplace add zerosloney/cbx-orch

# 3. 安装 cbx-orch 插件
claude plugin install cbx-orch@cbx-orch-marketplace

安装后重启 Claude Code 会话，插件 manifest 会调用全局安装的 cbx mcp，将 MCP server 自动以 cbx 名注册；工具暴露为 mcp__cbx__cbx_*。因此仅 clone 或安装插件目录并不足以启动 MCP，必须先确保全局 cbx 命令可用。

斜杠命令、技能、用户配置与 ZCode 插件完全一致（见上文表格），区别仅在于宿主客户端：executor / review / isolated 在 Claude Code 设置中配置（对应 userConfig），工作区定位同样通过 CBX_WORKSPACE=${CLAUDE_PROJECT_DIR} 注入。

前置依赖

同 ZCode：npm 发布包含 dist/；从源码安装需先 npm install && npm run build。Stop review-gate hook 通过 cbx stop-review-gate 子命令调用，只依赖全局 cbx 命令，不依赖插件目录内的 dist；MCP server 同样只依赖全局 cbx 命令。

安全说明

• 默认权限模式 auto。可通过 --permission-mode 或配置覆盖；dontAsk 需显式 --dangerously-skip-permissions。
• 测试命令由用户提供，会在目标工作区执行。cbx 做有限黑名单过滤（覆盖 flag 顺序无关的 rd /q /s、erase、引号包裹变体与 find -exec 等已知绕过手法；正则无法穷举，仍可被未知的变体绕过），不保证命令安全。建议始终用 --isolated 让测试在 worktree 内跑；非隔离时 cbx 会输出告警。
• Web UI 与 MCP HTTP 默认校验 Host 头必须为本机回环（防 DNS rebinding），且浏览器请求携带的 Origin 头必须指向回环（防任意网页跨站发起 no-preflight POST 触发 cancel/pause 等写操作）。携带请求体的 POST 必须使用 application/json（MCP POST /mcp 一律强制）；无 body 的 POST（cancel/pause 等）不强制 content-type，保持 curl 兼容。用自定义 hosts 别名访问本机服务会被拒绝。
• Web UI / TUI 仅绑定本机回环（127.0.0.1/::1）。可通过 --ui-token 或配置 ui.token 启用 token 鉴权：浏览器走 HttpOnly cookie，curl/API 客户端走 Bearer header，/healthz 和首页保持开放。未配置 token 时不做鉴权。远程共享必须放在带认证的反向代理之后。
• --isolated 会创建 Git worktree，避免直接污染主工作区；它不是 OS 安全沙箱，不会隔离网络、凭据、宿主机文件或进程。
• 默认 execution.trustMode 是 trusted。untrusted 任务需要 OS 容器沙箱；cbx 自身不内置容器运行时——配置 execution.runner（cbx.runner/v1 ESM 插件，在容器内执行 executor/test/review 命令）后放行，未配置时明确拒绝启动。untrusted 仍要求 isolated=true。
• .cbx.json 是严格 schema：未知字段、错误类型和越界值会拒绝加载，避免策略拼写错误静默失效。governance.redactFields/redactPatterns 会递归脱敏事件（含任务级 events.ndjson 中的 process_started argv 与 executor_stream_event 的 toolArgs）、webhook 和死信中的同名字段与全文匹配；agent.log 与 test.log 是原始诊断产物，不做脱敏，请不要在其中粘贴密钥。governance.retentionDays 会在状态更新和健康检查时原子压缩 .cbx/delivery-failures.ndjson，并同步清理过期 SQLite 死信记录。governance.pruneJobs（默认 false，须显式开启）把保留期扩展到任务本体：超过 retentionDays 的已终态任务（done/failed/needs_fix/review_failed/cancelled）在终态路径与健康检查时自动执行等价 cbx purge 的清理（state/events/产物 + worktree），写入 tombstone 与 job.deleted webhook 审计；运行/排队/审批中任务永不触碰。
• --timeout-ms 限制执行器和测试命令的单次执行时间。
• --max-retries 控制失败后的自动重试预算，默认 1。内部拆为两个独立计数器：执行器崩溃预算 executionRetries = maxRetries+1，测试/审查失败修复预算 fixRetries = maxRetries。执行器崩溃只消耗 executionRetries，测试/审查失败只消耗 fixRetries，避免 needs_fix 场景每轮白耗一次执行器重试。CLI 与 .cbx.json 的 maxRetries 语义不变。
• --dependency-guard / .cbx.json dependencyGuard（默认关闭）：开启后每个 stage 执行前后对 package.json、package-lock.json、pnpm-lock.yaml、yarn.lock、bun.lockb 取 SHA-256 baseline 比对，未授权改动触发 needs_fix / dependency_guard 并提示恢复或 --no-dependency-guard 关闭。仅做哈希比对，不阻止其他文件改动，也不替代 OS 沙箱。
• 默认任务完成或失败后清理 isolated worktree；使用 --keep-worktree 保留。
• 同一个任务不能并发执行；cancel 会终止进程树并留下取消标记。