krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e1aed590f8de3b4d2a6ba559f7251f380892b218
boss/docs/architecture/codex_server_progress_card_cn.md
AI Bot e1aed590f8 feat: harden enterprise control plane
2026-05-17 02:20:08 +08:00

7.5 KiB
Raw Blame History

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

更新时间：2026-05-16

1. Codex 最新开放协议结论

2026-05-16 的最新架构判断：Boss 后续优先围绕 Codex App Server 做深度接入，但当前生产链路仍保留 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 的普通任务完成回写；下一批再继续把 Approval、Skill、file changes 和更细粒度 progress 归一化为 Boss 自有的 execution_progress / approval_card / change_set / risk_event / skill_capability。

官方文档入口：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.131.0-alpha.9
  • 本机 codex app-server --help 已可用；本机 help 当前显示 --listen 支持 stdio://、unix://、unix://PATH 和 off
  • 官方文档仍提到 WebSocket 传输，但标注 experimental / unsupported；Boss 当前只把 stdio 作为默认接入，后续如要接 WebSocket 必须先做协议快照和灰度开关
  • 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>/。

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 展示结构对齐截图：

  • 进度：步骤列表，显示已完成 / 进行中 / 待处理 / 失败
  • 分支详情：变更行、Git 操作、GitHub CLI 可用状态
  • 生成结果：从执行结果里提取文件、图片、APK、文档等产物名
  • 后台智能体：预留 OMX / Hermes / explorer 等多智能体来源展示

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

后续建议按两步继续：

  1. 把当前 runner 提升为完整 CodexAppServerBackendAdapter：继续补 Approval / file change / skill / app / browser / computer-use 事件映射，但保持 feature flag 默认关闭。
  2. 新增 CodexMcpBackendAdapter：让 codex mcp-server 成为 ExecutionBackend 的兼容实现，用于 App Server 不可用或只需要轻量会话时。
  3. 增加任务级 live progress API：POST /api/v1/master-agent/tasks/[taskId]/progress，让本地 agent 在执行中也能实时刷新进度卡，而不是只在 claim / complete 两个节点更新。
  4. 建立协议快照目录和兼容测试：每次 Codex 协议升级时生成 schema、跑映射测试、灰度打开新 capability，避免把某个 Codex 版本写死到 APP 或后台。