krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
32a9c9a26a7318321b984a81c740e39b9b7c3df7
boss/docs/architecture/codex_server_progress_card_cn.md
AI Bot 32a9c9a26a feat: surface codex image generation progress
2026-06-01 18:41:10 +08:00

19 KiB
Raw Blame History

Codex Server 协议与 Boss 执行进度卡接入记录

更新时间：2026-06-01

1. Codex 最新开放协议结论

2026-05-31 的最新架构判断：Boss 后续优先围绕 Codex App Server / Remote Control 做深度接入，但当前生产链路仍保留 codex exec resume，codex mcp-server 作为兼容 provider 候选。

Codex App Server 是更适合 Boss 长期接入的协议层，因为它面向富客户端和产品级集成，覆盖：

  • authentication
  • conversation history
  • approvals
  • streamed agent events
  • Thread / Turn / Item
  • model/list、skills/list、plugin/list、app/list
  • command execution、file change、tool input、MCP tool-call approvals

Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务层。当前第一批已经新增 local-agent/codex-app-server-runner.mjs，把 App Server 的 thread/resume | thread/start -> turn/start -> item/agentMessage/delta -> turn/completed 映射成 Boss 的普通任务完成回写。

2026-05-31 已继续把 turn/plan/updated、turn/diff/updated、item/started|completed、thread/started 这类协议事件归一化为 Boss execution_progress 的步骤、分支变更、产物和后台智能体。同日第二批补齐 item/*/requestApproval、item/autoApprovalReview/*、guardianWarning、serverRequest/resolved 和 item/fileChange/patchUpdated 的安全摘要映射，APP 只展示审批状态、风险提醒和文件路径，不展示完整命令、diff、系统提示词或密钥。第三批已把 thread/status/changed 与 thread/realtime/* 归一成 executionProgress.threadStatus / realtime，APP 只展示活跃/等待审批/等待用户输入、realtime 文本摘要、音频片段计数和关闭/错误原因；第四批已把 model/rerouted、thread/tokenUsage/updated、mcpServer/startupStatus/updated 和 remoteControl/status/changed 归一成 executionProgress.modelRoute / tokenUsage / mcpServers / remoteControl，用于 APP “运行状态”区块。

2026-06-01 第五批已把 thread/goal/updated|cleared、thread/settings/updated 和 thread/compacted 归一成 executionProgress.threadGoal / threadSettings / compaction，用于 APP “线程配置”区块；第六批已把 account/updated、account/rateLimits/updated、model/verification、warning、configWarning、deprecationNotice 归一成 executionProgress.accountStatus / modelVerification / warnings；第七批已把官方 ThreadItem.collabToolCall 归一成 executionProgress.threadCollaboration，并按官方建议把新版 ThreadItem.contextCompaction 映射回 executionProgress.compaction；第八批已把 mcpToolCall、dynamicToolCall、webSearch、imageView、enteredReviewMode、exitedReviewMode 和 commandExecution 归一成 executionProgress.toolActivities；第九批已把官方 ThreadItem.plan 的最终 item/completed 文本映射为 executionProgress.steps，并把 ThreadItem.reasoning.summary 映射为 executionProgress.reasoningSummary；第十批已把 ThreadItem.imageGeneration 安全映射为 executionProgress.toolActivities 的图像生成活动和 executionProgress.artifacts 的图片产物，供 APP 以“图像生成 / 生成结果”轻卡展示。

thread/realtime/sdp、音频 base64、原始 realtime item、remote installationId、thread settings 的 cwd、compaction turnId、collaboration settings 内部 prompt、collabToolCall 源/目标线程 ID、tool arguments/result/contentItems、web URL token、命令正文/输出、raw reasoning content、reasoning item id 和未清洗的 MCP 错误不入账。

官方文档入口：https://developers.openai.com/codex/app-server

当前仍可作为 Boss 兼容集成入口的是 Codex CLI MCP server：

  • 启动命令：codex mcp-server
  • Inspector 调试：npx @modelcontextprotocol/inspector codex mcp-server
  • 官方 MCP 工具：
    • codex：启动一个 Codex 会话，入参包含 prompt / approval-policy / base-instructions / config / cwd / include-plan-tool / model / profile / sandbox
    • codex-reply：继续一个 Codex 会话，入参包含 prompt / threadId，conversationId 只是兼容别名
  • 线程续写应使用 tools/call 返回里的 structuredContent.threadId
  • 现代 MCP 客户端主要读取 structuredContent；content 只作为旧客户端兼容输出

本机当前检测结果：

  • 本机 codex --version：codex-cli 0.135.0-alpha.1
  • 本机 codex app-server --help 已可用；本机 help 当前显示 --listen 支持 stdio://、unix://、unix://PATH、ws://IP:PORT 和 off
  • 本机 codex app-server --help 当前已经支持 --ws-auth capability-token|signed-bearer-token、--ws-token-file、--ws-token-sha256、--ws-shared-secret-file、issuer/audience/clock-skew 等 WebSocket 认证参数
  • 本机协议快照已生成到 docs/protocol-snapshots/codex-app-server/0.135.0-alpha.1/，共识别 137 个协议方法；确认支持 thread/inject_items、thread/rollback、thread/goal/*、turn/steer、command/exec、thread/realtime/*、account/*、model/verification、configWarning、deprecationNotice、model/list
  • Boss 当前默认仍以 stdio 作为本机 agent 接入方式；ws://127.0.0.1:<port> 和 unix://PATH 本地长驻 transport 已可灰度接入，WebSocket/Unix WebSocket handshake 支持 Authorization: Bearer <token>；非 loopback signed bearer/JWT、自动重连和健康探测仍保留为后续增强，不直接替换当前稳定链路
  • 官方文档提示 WebSocket ingress 满载时会返回 JSON-RPC -32001 / Server overloaded; retry later.；Boss runner 已对该错误做最多 3 次指数退避重试，避免长驻连接瞬时拥塞直接把用户任务打失败
  • Boss heartbeat 已新增 App Server 能力发现缓存：按 codexAppServerDiscoveryTtlMs 拉取 model/list、modelProvider/capabilities/read、skills/list、plugin/list、app/list，归一成设备 capabilities.codexAppServer.metadata；发现失败只记录 warn，不阻塞心跳
  • Boss 第一批只用 App Server 做任务级 provider，不直接复用 ChatGPT Mobile 到 Codex App 的官方 relay；官方移动控制链路仍属于 ChatGPT App 与 Codex App 同账号/工作区之间的产品能力，不是第三方 Boss 可以稳定依赖的私有通道

下一轮再核对版本时，不要只看 npm 包版本号；必须同时读取 App Server schema / TypeScript 定义，并把 protocol snapshot 保存到 docs/protocol-snapshots/codex-app-server/<version>/。

当前“线程和线程之间可以直接对话”的产品判断：

  • Codex 已经有更强的 thread coordination、subagent thread spawn、thread/fork、thread/read、thread/inject_items、turn/start、turn/steer 等能力。
  • 但这不等同于任意两个 Codex 线程官方原生 P2P 互聊。更稳的理解是：一个上层 orchestrator 可以读取线程 A、把必要上下文注入线程 B、再启动或 steer 线程 B 的 turn。
  • Boss 应该把这层做成自己的 Inter-Thread Broker：用户看到的是“线程协作 / 主 Agent 协调”，底层实现由 App Server provider 完成 read / inject / start / steer / rollback，并把过程写入审计与进度卡。
  • 2026-05-31 已落地第一版 runner 能力：当任务携带 intentCategory=thread_collaboration、sourceCodexThreadRef 和 targetCodexThreadRef 时，local-agent/codex-app-server-runner.mjs 会执行 thread/read(source) -> thread/inject_items(target) -> turn/start(target)，并只注入受控摘要，不注入系统提示词、设备密钥或内部调度字段。

2. Boss 当前采用的接入策略

短期不直接依赖 Codex Desktop 私有 UI 结构，也不把 Codex CLI 原始 stderr/stdout 泄露给 APP。

当前实现采用 Boss 自有结构化消息：

  • 新消息类型：execution_progress
  • 服务端字段：Message.executionProgress
  • 触发范围：
    • 普通单线程对话：用户在 Boss APP 指定线程里发消息
    • 主 Agent 托管线程：托管消息实际派到目标 Codex 线程时
    • 群聊确认下发：后续目标线程执行单会复用同一张卡
  • 生命周期：
    • 任务入队：创建进度卡
    • local-agent 认领：更新为 running
    • local-agent 完成：更新同一张卡为 completed / failed

APP 展示结构对齐截图：

  • 进度：步骤列表，显示已完成 / 进行中 / 待处理 / 失败
  • 安全提醒：展示 Guardian warning 的用户可读摘要
  • 审批状态：展示命令 / 文件 / 权限审批与自动复核状态
  • 文件变更：展示 App Server patchUpdated 中的文件路径和变更类型，不展示 diff
  • 线程状态：展示 active / idle / systemError / notLoaded 以及 waitingOnApproval / waitingOnUserInput
  • 实时状态：展示 realtime 启动、同步、关闭或错误状态，附带安全清洗后的 transcript 预览和计数
  • 线程配置：展示 thread goal、模型 / provider、审批 / 沙箱、协作模式和上下文压缩状态
  • 线程协作：展示 collabToolCall 的工具名、执行状态、目标类型和智能体状态，不展示源/目标线程 ID 或 prompt
  • 工具活动：展示 MCP / dynamic tool / web search / image view / image generation / Review / command 的类型、名称、状态和安全摘要，不展示参数、结果、URL token、命令正文、命令输出、图像生成原始 result 或 revised prompt
  • 思考摘要：展示 Codex 官方 reasoning summary 和状态，不展示 raw reasoning content、item id 或密钥
  • 运行状态：展示模型重路由、上下文用量、MCP 启动状态和远控连接状态
  • 分支详情：变更行、Git 操作、GitHub CLI 可用状态
  • 生成结果：从执行结果里提取文件、图片、APK、文档等产物名
  • 后台智能体：预留 OMX / Hermes / explorer 等多智能体来源展示

UI 参考：

  • image2 生成稿：design/image2/boss-app-codex-app-server-progress-card-20260531.png
  • 当前生成稿保持微信效率型：顶部保留项目目标 / 版本记录固定入口，聊天区只展示最终用户消息和结构化进度卡，进度卡分为 进度 / 线程状态 / 实时状态 / 线程配置 / 线程协作 / 工具活动 / 思考摘要 / 账号状态 / 运行状态 / 安全提醒 / 审批状态 / 文件变更 / 分支详情 / 生成结果 / 后台智能体
  • 后续 Android / Web 继续按该稿收口，不新增无关功能，不把协议字段、系统提示词或执行 envelope 暴露给用户

3. 安全边界

进度卡只允许展示用户可见摘要：

  • 不展示系统提示词
  • 不展示完整执行 prompt
  • 不展示设备 token、账号密钥、内部工作目录调度说明
  • 不展示 Codex CLI 启动 envelope、sandbox、approval、session id、MCP 启动日志
  • RemoteRuntimeAdapter 仍会先拦截只读环境提示和 Codex envelope 泄漏，再进入消息账本

4. 历史引用项目最新状态

本次按 GitHub 最新元数据核对过的项目：

项目 最新状态 对 Boss 的可借鉴点
openai/codex rust-v0.129.0，2026-05-07 发布；main 在 2026-05-08 仍有提交 后续优先补 codex mcp-server 长驻适配器；参考 ThreadStore、turn metadata、app-server protocol v3 方向，不再只靠 codex exec resume
Yeachan-Heo/oh-my-codex v0.16.2，2026-05-08 发布 $ultragoal 聚合目标、commit-shared wiki / compaction、state/session isolation、Codex native hook setup 值得同步到 Boss 的任务目标与进度卡
ultraworkers/claw-code main 最新提交 2026-05-06；原 instructkr/claw-code 已指向该仓库；暂无 GitHub release 继续保留抽象后端，不写死版本；重点观察 skills help routing、push_output_block、Rust harness 更新
NousResearch/hermes-agent v2026.5.7 / v0.13.0，Tenacity Release Durable Multi-Agent Kanban、heartbeat / reclaim / zombie detection、goal lock、checkpoints v2 可作为 Boss 主 Agent 长任务可靠性升级参考
iflytek/skillhub v0.2.6，2026-04-29 发布；main 2026-05-08 仍更新 Skill 订阅通知、OIDC 登录、S3 IAM、namespace CSV 批量成员导入，适合 Boss 企业 Skill 治理后台后续吸收
openclaw/openclaw v2026.5.7，2026-05-07 发布；main 2026-05-08 仍更新 Telegram allowlist、polling watchdog、deliverySucceeded、Codex approval 去重、provider/model callback 修复，可用于 Boss Telegram 网关和远程审批
goldmar/openclaw-code-agent v4.2.3，2026-05-08 发布 OpenClaw + Codex coding agent 的 session lifecycle、wake routing、worktree/PR policy，可作为 Boss “聊天控制桌面 Codex 开发”的旁路参考

5. 下一步建议

第一阶段已经落地：

  • Boss 消息账本新增 execution_progress
  • Android 原生聊天页新增结构化进度卡
  • local-agent 完成回写会补 Git diff、GitHub CLI 状态和产物名
  • local-agent 新增 Codex App Server runner，boss-agent 默认打开；conversation_reply / dispatch_execution 会先尝试 App Server，任务尚未真正启动 turn 时允许回退 CLI，turn 已启动后不再重复下发，避免双写同一线程
  • local-agent 新增 Codex Computer Use -> CUA Driver 桌面控制级 fallback：远程控制这台电脑时默认先通过 Codex Computer Use 执行，失败后再走 Boss 既有 CUA Driver runtime
  • device-heartbeat 设备能力新增 codexAppServer，用于前台和后台知道该设备是否具备 App Server provider
  • 新增 scripts/codex-app-server-protocol-snapshot.mjs，可把本机 Codex App Server 的 help、JSON Schema、TypeScript bindings 和方法清单生成到 docs/protocol-snapshots/codex-app-server/<version>/
  • local-agent/codex-app-server-runner.mjs 已吸收 App Server 协议进度事件，并把 plan、diff、artifact、subagent 归一成 Boss executionProgress，服务端 complete 回写会与本地 Git/GitHub 进度合并，不再覆盖协议原生进度
  • local-agent/codex-app-server-runner.mjs 已把 App Server 审批、Guardian warning 和 file-change patch 事件归一成 executionProgress.approvals / warnings / fileChanges；服务端和 Android 原生进度卡已支持展示，且测试覆盖了密钥和 diff 不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server thread/status/changed、thread/realtime/started|transcript|outputAudio|itemAdded|error|closed 归一成 executionProgress.threadStatus / realtime；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 SDP、音频原始数据和 raw item 不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server model/rerouted、thread/tokenUsage/updated、mcpServer/startupStatus/updated、remoteControl/status/changed 归一成 executionProgress.modelRoute / tokenUsage / mcpServers / remoteControl；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 installationId 和密钥不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server thread/goal/updated|cleared、thread/settings/updated、thread/compacted 归一成 executionProgress.threadGoal / threadSettings / compaction；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 cwd、turnId、内部 prompt 不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server account/updated、account/rateLimits/updated、model/verification、warning、configWarning、deprecationNotice 归一成 executionProgress.accountStatus / modelVerification / warnings；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖配置路径、turnId 和密钥不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server ThreadItem.collabToolCall 和 ThreadItem.contextCompaction 归一成 executionProgress.threadCollaboration / compaction；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖源/目标线程 ID、内部 prompt、turnId 和密钥不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server mcpToolCall、dynamicToolCall、webSearch、imageView、enteredReviewMode、exitedReviewMode、commandExecution 归一成 executionProgress.toolActivities；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 tool arguments/result、URL token、命令正文/输出、本地路径和密钥不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server ThreadItem.plan 与 ThreadItem.reasoning.summary 归一成 executionProgress.steps / reasoningSummary；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 raw reasoning content、reasoning item id 和密钥不外泄
  • local-agent/codex-app-server-runner.mjs 已把 App Server ThreadItem.imageGeneration 归一成 executionProgress.toolActivities / artifacts；服务端进度路由和 Android 原生进度卡已支持展示，测试覆盖 revisedPrompt、result、item id、本地绝对路径和密钥不外泄
  • 新增实时进度入口 POST /api/v1/master-agent/tasks/[taskId]/progress，设备端可在任务执行中持续刷新同一张 execution_progress 卡；local-agent 的 App Server runner 已在收到协议进度事件时调用该接口，complete 仍携带最终进度作为兜底
  • 新增服务端线程协作入口 POST /api/v1/projects/[projectId]/thread-collaboration，由 Boss 校验源/目标项目权限并创建 intentCategory=thread_collaboration 的 conversation_reply 任务；设备端继续通过 App Server runner 执行 thread/read -> thread/inject_items -> turn/start，避免把“线程互通”误做成无监管 P2P
  • 新增活跃 turn 干预：任务携带 targetCodexTurnId / targetTurnId 时，App Server runner 会调用 turn/steer，并把 turnControl=steer、turnId 写回执行结果；没有活跃 turn id 时仍使用 turn/start
  • getCodexAppServerRunnerConfig 已识别 codexAppServerTransport / BOSS_CODEX_APP_SERVER_TRANSPORT、codexAppServerUrl / BOSS_CODEX_APP_SERVER_URL、codexAppServerAuthTokenFile / BOSS_CODEX_APP_SERVER_AUTH_TOKEN_FILE；local-agent/codex-app-server-runner.mjs 现已支持 stdio、ws://127.0.0.1:<port> 与 unix://PATH 三种 JSON-RPC transport，默认仍是 stdio，ws/unix 适合作为同机长驻 App Server 灰度路径
  • 新增 App Server 过载退避：单个 JSON-RPC 请求收到 -32001 或 retry later 文案时，会在同一个任务生命周期内重试，超出上限后才进入失败/CLI fallback 判定
  • 新增 App Server capability discovery：local-agent 会把可用模型、默认/快速/深度模型建议、provider 能力、Skill、Plugin、App 摘要写入设备 heartbeat；Web 设备详情已显示 App Server、模型和扩展数量，为后续 APP/后台模型配置页提供真实数据来源

后续建议按两步继续：

  1. 把当前 runner 提升为完整 CodexAppServerBackendAdapter：继续补 MCP tool / account / rate-limit / config 事件映射，并把 realtime 字段纳入后台风险看板，但保持 feature flag 默认关闭。
  2. 完善长驻 transport 灰度：ws://127.0.0.1:<port>、unix://PATH 和 bearer token handshake 已可用，下一步补 signed bearer JWT 的 issuer / audience 校验联调、断线重连和健康探测；失败自动回退 stdio。
  3. 新增 CodexMcpBackendAdapter：让 codex mcp-server 成为 ExecutionBackend 的兼容实现，用于 App Server 不可用或只需要轻量会话时。
  4. 每次 Codex 协议升级时生成 schema、跑映射测试、灰度打开新 capability，避免把某个 Codex 版本写死到 APP 或后台。