6.5 KiB
CodeX Workspace / Session 内存展示投影设计
更新时间:2026-10-08。文件名保留既有引用;本文描述当前设计,不再作为从零实现的任务提示词。
1. 定位与入口
CodeX 保留在 Remote Plugin 的 packages/plugin/src/codex/ 独立领域,Host 使用 stdio App Server,Remote 使用 codex.app.*。
Desktop 通过临时 Typert carrier 复用原生 Workspace / Session / Conversation / Composer;Android 直接消费同一领域并在内存中投影。
VS Code 当前不增加 CodeX 会话入口。完整 Remote Web runtime 仍在独立 Server 仓库;本仓库最小 Server 只转发加密数据。
用户从 Remote Host 的工作区选择器进入 CodeX Project / Workspace,可选择既有目录或注册 Host 现存目录。
CodeX 默认开启,可在 Host 后端设置中关闭;capability 与 workspaceTypes.available 同时成立才进入工作区。
命令可发现不代表 App Server 已登录或就绪。
2. 数据所有权与 authority
App Server 保存 Project、Thread、Turn、Item、History、运行与审批状态;Client 仅维护临时映射和 stream。
不得写 DSH SessionStore、Workspace 数据库、Harness 日志或自建展示数据库,不读取 ~/.codex 私有 JSONL/SQLite。
Workspace 优先由 project/list 得到;缺少可用根目录才使用 App Server thread/list 已返回的绝对 cwd 精确回退。
不推测共同父目录,不接受 Client 自报路径作为 authority。
project/create 仅接受 Host 已存在的单个绝对目录,Host 执行 realpath 和目录校验,App Server 返回新 Project 后才扩展 authority。
新 Thread 可使用 authority 根内经词法路径和 realpath 双重验证的真实子目录;带 threadId 的调用也校验 Thread 归属。
Workspace ID 使用 codex-workspace:project: 前缀,Session ID 使用 codex:<threadId>。
ID 只是映射,不能单独授权访问路径、Thread 或文件。
3. 数据流
Desktop 原生 UI / Android Workspace、Session、Chat
-> Client 内存展示投影
-> CodexRemoteClient
-> membership + pinned identity + Noise channel
-> 每连接 Codex bridge 与固定 allowlist
-> Host stdio Codex App Server
Desktop 虚拟 carrier 只实现 UI 需要的固定 endpoint;未知方法拒绝,不能回落到 Host 本地 Harness Session。 各版本 carrier 和 Session V3 兼容以兼容说明和源码为准。
4. 方法与原生操作
| UI 动作 | App Server 操作 |
|---|---|
| Project 列表 / 注册 | project/list / project/create |
| 新会话 / 打开历史 | thread/start / thread/read |
| Fork / Rename / Archive | thread/fork / thread/name/set / thread/archive |
| 发送 Prompt | thread/resume 后 turn/start |
| 运行中调整 | turn/steer,校验 expectedTurnId |
| 停止 | turn/interrupt |
| 审批 | Host codex.app.respond,单次允许或拒绝 |
打开历史不自动 resume;发送前恢复相应 Thread。账户、模型、unsubscribe/unarchive 等操作仍受编译期 allowlist 限制,
完整 schema 与限额见协议及 codex/method-policy.ts。
禁止 raw App Server 代理、command/*、process/*、任意 config、Thread 删除/注入和远程 API Key 登录。
图片以受限 base64 input 经 CodeX transfer 传递,在 Host 转为 App Server data URL;不接收通用附件、外部 URL 或任意 Host path。 权限控件显示 Host 确认的会话策略,未知时标明沿用 Host 设置;切换确认后生效。
5. History 与实时事件
打开 Session 从 thread/read(includeTurns: true) 取得 baseline,按 Turn/Item 顺序生成原生展示事件。
| CodeX 数据 | 原生展示 |
|---|---|
| Turn 开始/结束 | turn start/end |
| User / Agent message | user/assistant message |
| Assistant / reasoning delta | 原生 chunk 和 reasoning |
| Plan | todo/write 与计划展示 |
| Command / MCP / tool / file change | tool call/result 与受限摘要 |
| Output delta / progress | 同一 tool result 的有界累计更新 |
| Thread / model 状态 | session status 与模型选择投影 |
| 未识别 Item | 安全忽略,不透传任意原始对象 |
snapshot 保持 header/cursor/records/hasMore 和事件顺序;实时流处理开始、delta、完成、状态与审批。 大 History 走有界 transfer,断线后新的持久化 baseline 替换临时 live 状态,不重放 mutation 或建立永久 replay buffer。
6. CodeX Files / Terminal
当前 CodeX 会话已接入受限工作区工具。codex-workspace-bridge.ts 由 Host 将 codex:<threadId> 解析为 Thread cwd,
独立创建文件 scope 和终端上下文;不把 CodeX ID 当作 Harness agent,也不扩大 App Server allowlist。
路径规范化、realpath、符号链接、尺寸与会话有效性校验和 Harness 工具一致,不能越过该 Thread cwd。
只读文件使用固定 workspaceFiles/* 语义。终端使用官方 terminal/* shape、快照、controllerId、follow/retain 与单调输出序号,
遵循 Host 开关、设备归属与连接输入权。CodeX / ACP 共用 RemoteTerminalController,通过 Host subprocess
探测默认 shell 与可选 shell,使用交互参数;有 PTY 时启用官方进程范围管理和可用的 shell activity。
Host xterm headless 保存有界屏幕并序列化重连快照,不再回放原始日志。重复创建幂等,断线释放输入权但保留进程;
后端重配或 Host 关闭等待清理,启动中关闭也回收迟到进程。两小时无持有者且持续明确 idle 才自动回收,unknown/busy 不回收。
无 subprocess 的兼容 pipe 不支持 PTY resize 或终端 job control。
这是受控会话工具入口,不能成为 raw App Server shell/command 或通用 filesystem RPC。
7. 生命周期与验证
切换领域/Host、退出 Remote、撤销、断线或关闭 CodeX 时清理对应内存载体、stream、pending waiter 和审批句柄。 Host 配置热更新只重启变化后端;其他后端保留。工具和审批按认证连接隔离,未知连接、identity mismatch、越权 root 和迟到回复拒绝。 日志不包含 token、私钥、Prompt、历史、源码或工具输出。
核心验证保护 authority、allowlist、History/live 顺序、RPC、审批、恢复和文件/终端隔离;纯展示不新增测试。 已有 CodeX Desktop/Android 主链路验收不等于 Project 新建、最新工具、Windows 与长连接全部通过。 剩余验收见TODO,使用与边界见CodeX 技术说明,实现约束见 AGENTS。