从零理解如何构建 AI Agent

Appearance

E9｜IDE / 桌面：行内 diff 和打开文件是客户端投影，不是第二套 agent ​

先别在扩展里实现 run_turn ​

A0 / A1 说过：VS Code、Cursor、Windsurf、JetBrains、Xcode 的 UI 不在本仓库。读到 SessionSource::VSCode 是默认值（protocol.rs:2765-2768）的人，仍会去找 vscode/ 插件源码，或把「打开文件进上下文」理解成 core 自己 read_file。

判断先说清楚：IDE 和桌面是 app-server 的富客户端。 它们做 E1 允许的三件事——提交、投影、自己的 UX 契约。打开的 tab、选区、行内 diff、审批对话框，都是把 Event / 编辑器状态 画进人正在看的表面。多 thread 指挥台、pop-out、防休眠、通知策略在闭源 App 壳里。本仓库能抄的是：IDE 上下文怎么有界地拼进用户消息、/import 怎么从 Claude Code / Cursor 迁配置。

1. 多家 IDE，同一只插座 ​

SessionSource 有 Cli / VSCode / Exec / Mcp / Custom… 默认 VSCode，说明 IDE 从一开始就是一等表面，不是 CLI 后补。Cursor / Windsurf 往往装同一套或同源扩展；JetBrains / Xcode 是另一套壳，协议仍是 v2 thread/*、turn/*。

行内 diff：core 产出 apply_patch 的 turn diff（B2）；扩展把它画在编辑器 gutter。审批对话框：core 发审批 Event；扩展弹原生 UI，回的是 RPC，不是本地假 Allow。换 IDE 不必换 Orchestrator。

没有「扩展只投影」会怎样？每个编辑器复制一份工具列表，JetBrains 的 Allow 和 VS Code 的 Allow 语义分叉。那正是 SQ/EQ 要阻止的。

2. 打开文件 / 选区：有界上下文，标记要跨表面一致 ​

TUI 也能要 IDE 上下文：/ide「include current selection, open files, and other context from your IDE」（slash_command.rs:126-128）。实现从 IDE 拉快照（tui/src/ide_context/，Windows 走 named pipe），再 apply_ide_context_to_user_input。

拼进 prompt 的结构（ide_context/prompt.rs:8-16, 97-182）：

  • # Context from my IDE setup:
  • 活动选区（有字符顶 MAX_ACTIVE_SELECTION_CHARS = 40_000）
  • Open tabs（最多 100 个、总字符 20_000，超出省略）
  • 分隔符 ## My request for Codex:

注释写死：这个分隔符必须和 桌面 App、IDE 扩展完全一致。上下文写在标记前，用户请求在标记后；transcript 渲染时剥到最后一个标记。这样在 IDE 里带着选区开的 thread，到 TUI resume 仍能分清「编辑器状态」和「我打的那句话」，符合 B4 禁止把注入和用户话搅在一起。

这是 E5 那种通道：看见当前 tab ≠ 那些文件已被 apply_patch。模型要改文件仍过工具和沙箱。

3. 指挥台、pop-out、防休眠、通知：壳的 UX，不是协议字段 ​

桌面 Codex App（codex app 只负责打开/安装，cli/src/desktop_app/mod.rs:6-12）才有：

  • 多 thread 指挥台（并行 Local / worktree / 云端任务列表）
  • pop-out 聊天窗
  • 防休眠（Remote 时保持 host 醒着，E3）
  • 系统通知策略

本仓库 没有 preventSleep 一类 RPC。它们不改变 AskForApproval，不改变 rollout。TUI 用 /agents 列 session，是瘦版指挥台，仍只是投影。

和 ChatGPT 桌面 合并后的入口 以当时官网为准：产品可能从独立 Codex.app 收到 ChatGPT 桌面里的 Codex 面板。工程师在这棵树里只保证 codex app 能拉起当前平台的安装器。入口变了，插座还是 app-server。

4. /import：迁 Claude Code 和 Cursor，不迁「另一个 agent」 ​

/import：「import setup, this project, and recent chats from Claude Code」（slash_command.rs:110）。crate external-agent-migration 实际认两家：

源目录 / 文件
Claude Code（ClaSource）.claude/、CLAUDE.md、settings.json（source/cla.rs:20-22）
Cursor（CurSource）.cursor/、.cursorrules、cli-config.json / cli.json、hooks.json、mcp.json（source/cur.rs:19-24）

迁的是说明书、hooks、MCP、部分 session/memory——映射到 Codex 的 AGENTS.md / hooks / mcp_servers，不是把 Claude 的循环搬过来。远程 session 和连着本地 daemon 时 不能 import（必须本机、非 daemon，flow.rs:21-22）。

C1 说过：CLAUDE.md 不是默认发现目标，import 是 一次性收敛到 AGENTS.md。不要长期双写。

5. 结语：带走一句话 ​

IDE 和桌面把打开的文件、选区、行内 diff、审批画进编辑器——分隔符和有界注入在本仓库里对齐；指挥台和防休眠在闭源壳里；/import 只搬家配置，不搬另一套 agent。