镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/claude-code.md ↗

Claude Code harness

claude_code 声明的 kind 为 writer、observer、evaluator;未声明 controller 能力,因此保存配置和运行时都拒绝 controller(包括 manager 与 coordinator)。其他后端保持既有能力和兼容约定。该驱动在项目容器(Workspace)及隔离运行容器(RunEnvironments,声明 isolation: run_environment)内执行真实 Claude Code 二进制,不调用普通 Chat Completions 代替 CLI。RoleRun 仍是现有 task_runs、assignment、lease epoch、TaskToolGateway 和 Publisher;没有新增任务队列或阶段调度。

工具卷、版本与部署

正式运行从容器只读工具卷 /opt/agent-tools(Docker 卷 agent-tools)加载已安装的 Claude Code 与配套 Node.js 运行时:

角色配置通过已有 V2 API 保存,可绑定项目模型(model_profile_ref)并选择模型来源(model_source):

{
  "expected_revision": 3,
  "enabled": true,
  "roles": [
    {
      "role_id": "dev",
      "harness_ref": { "id": "claude_code", "model_source": "gateway" },
      "model_profile_ref": { "model_id": "<model id>" },
      "environment_profile_ref": { "id": "isolated-workspace" }
    }
  ]
}

角色配置页展示 claude_code 与 codex 的工具卷挂载状态、已安装版本、所选版本、兼容版本范围、实际解析模型配置就绪状态与上游连通性状态(区分“连通性未探测”“连通正常”“连通失败”,并提供“探测模型连通性”操作)及不可用原因。模型完整 ID、CLI 版本和启动配置哈希进入 RunContext 和运行快照;同一角色 revision 恢复时变更模型或启动配置会以 model_revision_changed 拒绝,不静默换模型。

容器内模型中转、身份令牌与 GitHub 短期只读凭据

每次运行在容器内由 runner/harness-entry.mjs 以独立进程组启动:

  1. 回环模型中转(runner/model-relay.mjs,127.0.0.1:0):ANTHROPIC_BASE_URL 指向容器内本轮临时端口,ANTHROPIC_API_KEY 设为控制面签发的运行级身份令牌 rrt_…。中转经任务目录文件邮箱(model-requests/、model-replies/)转发到控制面 src/harness/model-gateway.ts;长期上游模型 API Key 仅保存在控制面加密存储中,永不进入容器环境、命令行或文件。即使隔离运行容器处于 --network none,模型调用仍经文件邮箱正常工作。
  2. 运行级身份令牌校验:控制面在每次模型请求、每次平台工具调用和每次 GitHub 短期只读令牌签发时复核 rrt_… 的哈希、租约 lease_epoch、角色、项目与能力范围(model:invoke、gateway:<tool>、github:read_token);撤销、过期或跨运行混用立即拒绝。
  3. GitHub 短期只读令牌辅助器(runner/git-credential-bot.mjs、runner/gh-wrapper.mjs):容器内不放置长期 GitHub Token,也不在 CLI 进程环境中设置 GH_TOKEN/GITHUB_TOKEN。需要远端只读访问时,Git credential helper 与 gh 包装器向 harness-entry.mjs 的本机凭据辅助端口申请短期只读安装令牌(剩余有效期不足 10 分钟自动续签),禁止 gh auth token / --show-token 导出明文,并对子进程输出做流式令牌脱敏;部分 GitHub 读取权限下引导改用平台结构化只读工具。GitHub 写入继续只走控制面受控 github_write 与 Publisher。

容器原生工具、平台 MCP 桥与证据边界

CLI 工作目录固定为容器内任务仓库检出 <task_dir>/repo;HOME 与 CLAUDE_CONFIG_DIR 指向角色实例专属状态目录 /workspace/tasks/<state_workspace_id>/cli-state/<session_key>/,随 WorkspaceCleanup 生命周期清理。

CLI 报告或退出码不会自动成为验收通过;writer 的 collect 由控制面取得候选快照并运行既有 finish 校验器,observer 只检视已固定的 role_candidate,独立 QA 始终使用全新上下文与独立检出。

流、恢复、取消与用量记账

输入是 NDJSON user 消息,显式绑定 session UUID。输出按锁定流协议解析,支持任意 UTF-8 分片,拒绝非法编码、未知协议、未终止 JSON 行、缺少 result、result 后迟到消息与无有效提交;单行上限 2 MiB、总流 32 MiB,公开文本上限 32 KiB,thinking/redacted_thinking 与签名不进入公开 trace。

恢复创建新的 run_id 与 lease_epoch。只有同一 tenant/project/task/role instance/assignment、相同候选/合同/技能/模型/配置且容器持久化目录中的原生会话文件确实存在时,才使用 --resume <UUID>(记录 native_resume);容器重建导致会话目录缺失或输入版本变化时,自动从持久化任务记录重建新会话并如实记录 rebuilt_from_task_records。observer 和 evaluator 每次创建干净会话,永不恢复或 fork 开发会话。

取消先发送 control_request/interrupt,宽限期后经 workspace_harness_interrupt 对整个容器内进程组发送 SIGKILL 并执行工作区 reap,确保 CLI 派生的测试、构建与子 Agent 进程全部回收,同时撤销运行令牌并拒绝迟到提交。

模型用量与完整请求轨迹由控制面 model-gateway.ts 在转发响应时统一写入 model_requests 与外部模型账本:明确的 4xx 上游拒绝记已知 0 token,5xx 或断流未拿到完整计数的请求记入 unknown_requests(lower_bound),并在结束时与 CLI result.usage 对账(usage_reconciliation)。

验证分层

官方接口依据:headless、CLI reference。