VS Code 多标签 ACP 客户端

本项目是一个运行在 VS Code 侧边栏中的 ACP（Agent Client Protocol）客户端。用户可以在当前工作区内选择 Claude Agent 或 OpenCode，创建多个相互独立的对话标签，并通过 Agent 原生 Session 浏览和恢复历史会话。

当前状态

阶段 0（技术验证与四项 ADR）到阶段 8（持久化、恢复与日志）的开发任务已全部完成，功能主干可用。

阶段 2、3 已实现 Agent Registry 与检测缓存、进程池与遗留进程清理、ACP 长连接、由已注册方法推导的客户端能力、fs/* 与 terminal/* 服务，以及首版多标签对话 UI；新建标签在 Agent 检测完成前即进入 starting 并可编辑发送，Webview 首屏走 stale-while-revalidate。Session 级 Prompt 队列通过 queuedPrompts.v1 持久化，并支持历史恢复后显式继续发送。阶段 5 已实现 Agent 原生历史列表（TTL 缓存、并发去重）、session/load/session/resume 打开、discoveredSessions.v1 本地发现降级、pinnedSessions.v1 固定、搜索排序、外部 Session 兼容提示、title 同步和 capability 驱动的原生删除。阶段 6 已实现动态 Session Config 控件与 agentConfigCache.v1 配置缓存预览、文件附件转换、@ 文件引用选择器、drafts.v1 草稿持久化，以及常驻的上下文窗口入口——Agent 上报 usage_update 时展示真实用量，仅在 Session 公布无需输入的 compact 命令时提供手动压缩。阶段 7a 已实现权限请求卡片、waiting-permission 状态、View Badge 和计划/命令/工具调用卡片。阶段 7b 已实现可审核 Diff 与 terminal/* 输出卡片（有界预览、按需查看完整输出）。阶段 8 已实现 Agent 崩溃一次自动重连、openTabs.v2 标签恢复（未提交的空标签重建新 Session，已有内容的标签恢复原 Session）、脱敏运行日志、默认关闭且带清理策略的 Traffic JSONL、viewPreferences.v1 折叠/滚动持久化，以及按 revision 分页传输的全量时间线与 Webview 动态高度虚拟列表。elicitation UI 和无文件夹临时工作区会话（每会话独立临时目录与独占 Agent 进程，关闭或启动失败立即回收）也已落地。

仍待开发：交互式终端桥接（ACP 1.4.0 稳定 Schema 未提供对应能力位，只保留只读输出卡片）；多根工作区中其他工作区根的次级只读浏览入口；阶段 9 的跨平台与远程环境验证目前只完成 Windows x64；阶段 10 发布准备只完成打包配置（npm run build:release 与 .vscodeignore），VSIX 打包、图标、用户文档、许可证与发布渠道尚未确定，package.json 的 version、license 与 categories 仍是初始值。详见 docs/backlog.md 与 docs/implementation-plan.md。

本地开发

npm install
npm run check
npm run test:integration

test:integration 使用本机已安装的 VS Code 或 Cursor 分别启动单根、多根和无文件夹工作区的隔离 Extension Host。默认优先 VS Code，找不到时回退到 Cursor；可用 ACP_INTEGRATION_EDITOR=vscode|cursor 指定宿主，也可用 VSCODE_EXECUTABLE_PATH / CURSOR_EXECUTABLE_PATH 指定可执行文件。它不会下载另一份编辑器。测试配置依据 VS Code 官方扩展测试指南。

在 Cursor 或 VS Code 中按 F5，会用当前编辑器启动 Extension Development Host，可下断点。调试面板里还可以选择「在 VS Code 中打开扩展」或「在 Cursor 中打开扩展」，用另一款编辑器加载本扩展。命令行等价于：

npm run debug:vscode
npm run debug:cursor

验证任意 stdio ACP Agent 时，先构建，再把命令和参数分别传给探针：

npm run build
npm run probe -- --sessions=2 opencode acp

探针默认在同一连接创建两个 Session，并同时发送不调用工具的验证 Prompt；它会输出 Agent 信息、认证方式、capabilities、Session 生命周期、客户端反向调用、分阶段耗时和进程资源峰值。--sessions=0..10 可控制并发数，--client-callbacks 声明安全的内存替身客户端能力，--cancel-after=<毫秒> 在 Prompt 启动后发送单向取消通知，--no-prompt 只创建 Session，--no-lifecycle 跳过 list/resume/close，--no-metrics 关闭资源采样，--metrics-interval=<毫秒> 调整采样间隔，--timeout=<毫秒> 调整总超时，--cwd=<路径> 指定工作目录。

对比一个共享进程承载多个 Session 与多个隔离进程时，使用独立基准命令。该命令默认不发送 Prompt，避免意外产生模型调用和费用：

npm run benchmark -- --sessions=10 --timeout=300000 opencode acp

Windows 无权读取完整进程树时会明确降级为根进程采样；此时结果中的 samplingScope 为 root，不能把它解释为包含所有子进程的完整资源数据。

文档索引

• 需求规格（docs/requirements.md）：产品范围、交互规则、能力边界和验收标准。
• 技术设计（docs/technical-design.md）：扩展架构、状态模型、ACP 连接、持久化、安全和远程环境设计。
• 实施计划（docs/implementation-plan.md）：分阶段开发顺序、验证方式、测试矩阵和发布条件。
• docs/decisions/：阶段 0 产出的决策记录（ADR），阻断项的最终结论以此为准。
• docs/compatibility/：Claude 与 OpenCode 的能力实测记录。

已确定的核心原则

1. 对话界面位于 VS Code 侧边栏，内部自行实现自动换行的多标签栏。
2. 默认按 (agentId, cwd) 共享进程并通过 sessionId 隔离标签；保留一标签一进程设置用于主动隔离和故障诊断。
3. 历史会话优先使用 Agent 原生 session/list、session/load 和 session/resume；session/list 在锁定 SDK 中已稳定，Agent 未声明时退回本地“发现缓存”，只用于列出候选，不伪造可恢复上下文。
4. ACP TypeScript SDK 已锁定为 @agentclientprotocol/sdk@1.4.0；Claude 候选适配器为 @agentclientprotocol/claude-agent-acp@0.70.0，首版由用户在 Extension Host 环境安装，OpenCode 使用本地 opencode acp。
5. UI、配置和操作均以 Agent 声明的 ACP capabilities 为准，不伪造 Agent 不支持的能力。
6. 插件同时是完整的 ACP Client：实现 fs/*、terminal/*、session/request_permission 和 elicitation/*，而不只是展示层。
7. Agent 是完整对话历史的唯一事实来源，插件只保存恢复 UI 所需的最小数据。
8. 未受信任工作区中不启动 Agent，也不允许执行命令或修改文件。

后续兼容性验证

Windows x64 已通过核心功能验证，其中 Webview 内联样式的 CSP 实机确认仍在 docs/backlog.md 的 B5-5 跟踪。阶段 9 的跨平台矩阵仍待执行：

1. macOS（arm64 必测、x64 打包验证）。
2. WSL2 Linux 与 Remote SSH Linux 上复验 Claude 安装、认证和启动。
3. Dev Container 与 Codespaces Remote Host 的可用性验证。

测试矩阵与场景清单见 docs/implementation-plan.md 第 12 节；执行状态在 docs/backlog.md 的 B5-3 跟踪。