From facbff428d3ed7d3dcd0424b8a68219e24328b80 Mon Sep 17 00:00:00 2001 From: tianma-if Date: Tue, 29 Sep 2026 00:32:04 +0800 Subject: [PATCH] docs: clarify AI assistant redesign plan --- docs/ai-assistant-redesign-plan.zh-CN.md | 107 +++++++++++------------ 1 file changed, 53 insertions(+), 54 deletions(-) diff --git a/docs/ai-assistant-redesign-plan.zh-CN.md b/docs/ai-assistant-redesign-plan.zh-CN.md index 0e22029b..3833787e 100644 --- a/docs/ai-assistant-redesign-plan.zh-CN.md +++ b/docs/ai-assistant-redesign-plan.zh-CN.md @@ -24,19 +24,16 @@ ### 决策一：采用 ACP (Agent Client Protocol) 连接本地 Agent -* **核心结论**：引入 **`@agentclientprotocol/sdk` (ACP)** 作为连接本地 Agent 的统一标准。（注：Vercel AI SDK Harness 专为云端沙箱设计，无法调度本机环境且不兼容边缘运行时，故不采用）。 -* **背景与定位**：由 Zed、Anthropic（Claude Code）、JetBrains 联合制定的开放标准，定位为 AI 时代“客户端与本地 AI Agent 间的 LSP（Language Server Protocol）”。 +* **核心结论**：桌面版以 **`@agentclientprotocol/sdk` (ACP)** 作为本地 Agent 的首选接入协议。AI SDK Harness 并非不能在本机运行，但其沙箱、会话和适配层不直接解决“调用用户电脑上已配置 Agent”的需求，本阶段不引入。 +* **背景与定位**：ACP 标准化客户端与 Agent 之间的会话、进度和权限交互，适合由 EdgeEver 桌面应用充当客户端。首版采用稳定的 ACP v1；是否支持某个 Agent，以具体 ACP 适配器和真实握手结果为准。[ACP 协议概览](https://agentclientprotocol.com/protocol/v1/overview) * **通信方式**： - * **本地子进程模式**：EdgeEver 桌面端（Node/Electron 宿主）通过 `stdio` 管道直接拉起本地 Agent（如 `antigravity`, `codex`, `claude-code`）； - * **本地网络模式**：本地 Agent 常驻守护进程时，前端通过 `WebSocket` / `HTTP` 连接 `http://127.0.0.1:`； -* **协议优势**：原生规范了会话生命周期、打字机流式、文件 Diff 审查确认、权限确认拦截与工具执行状态。 -* **本地 Agent 智能嗅探（Auto-Discovery）**： - * **免配置痛点**：用户安装了桌面 App（如 Antigravity、Codex App、WorkBuddy）后，登录态通常已保存在本地用户目录中（共享登录态），但 CLI 命令往往未注入全局 `$PATH`。 - * **主动探测**：桌面端启动时自动按优先级扫描常见路径： - 1. 检查系统环境变量 `$PATH`； - 2. 扫描 macOS 默认 App 路径（如 `/Applications/.app/Contents/...`）； - 3. 检查用户主目录（如 `~/.local/bin/`、`~/.gemini/`、`~/.config/`）。 - * **状态可视**：探测成功直接显示 `🟢 已检测到本地 Agent (已认证)` 供用户一键选用；未找到时提供友好的“一键安装 CLI”或路径浏览指引，杜绝繁琐的手工终端配置。 + * **首版本地子进程模式**：Electron 主进程启动明确支持的 ACP 服务程序，通过 JSON-RPC over `stdio` 通信，渲染进程只通过受限的 preload / IPC 接口发送请求与接收事件。Codex 对应 [codex-acp](https://github.com/agentclientprotocol/codex-acp)，Antigravity 对应 [ACP 注册表中的适配器](https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json)；普通 `codex`、`agy` 命令或已打开的桌面 App 不能直接视为 ACP 服务。其他 Agent 逐个验证后再加入。 + * **远程连接暂不纳入首版**：ACP 也面向远程场景，但 HTTP / WebSocket 的完整支持仍在演进；不让网页前端自行连接任意 `127.0.0.1` 端口。 +* **协议优势与边界**：ACP 提供 `initialize`、认证协商、会话创建与可选续接、进度通知、取消及权限请求等接口；具体能力取决于 Agent 握手声明，文件 Diff 也不等于 EdgeEver 笔记修改提案。 +* **本地 Agent 可用性验证**： + * 用户选择 Agent 时，先查找已知 ACP 适配器的可执行程序，允许手动指定路径；不扫描凭据目录，也不根据某个 App 是否安装推断登录状态。 + * 通过 `initialize` 和必要的认证流程区分“程序存在”“需要登录”“可建立会话”“连接失败”。只有完成握手并成功建立会话才显示可用；复用本机登录态须逐个适配器实测。 + * 首版提供安装与配置指引；自动下载或安装可执行程序留待来源校验、更新和跨平台策略明确之后。 --- @@ -51,7 +48,7 @@ * `` / ``：原生可折叠的深度思考折叠面板； * ``：带快捷发送、换行、附件与自动高度调节的现代化输入框。 * **EdgeEver 专有能力适配**： - * **修改拦截与 Diff 卡片**：将 `CompanionActionCard`（笔记创建/更新/删除审核）以 ToolCall 卡片插槽形式嵌入消息流。 + * **修改拦截与 Diff 卡片**：保留 `CompanionActionCard` 作为业务卡片，只展示由 EdgeEver 后端创建并校验的待确认动作。ACP 工具事件与文件 Diff 可以展示执行进度，但不能直接转换成可应用的笔记动作。 * **富文本渲染**：消息正文无缝保留现有的 `@streamdown/mermaid` 与 `@streamdown/math`，图表与公式继续保持高质量流式排版。 --- @@ -87,17 +84,9 @@ --- -### 决策五：三方模型 API 客户端直连优先原则（Client-Direct First） +### 现有模型调用链路（不属于本次重构） -* **核心原则**：**只要运行环境与网络支持，三方模型请求永远由客户端直接发起，坚决避免服务端做长连接中转代理。** -* **架构价值**： - 1. **零知识与极致隐私（Privacy-First）**：笔记正文与用户提示词直接发往用户配置的官方模型 API，不经过任何自建或托管服务端暂存或转发。 - 2. **降低流式延迟（Lowest Latency）**：去掉了 `客户端 -> EdgeEver 服务端 -> 模型厂商` 的中间转发跳数，首字打字机延迟（TTFT）大幅优化。 - 3. **保护服务器算力与带宽（Serverless-Friendly）**：彻底解耦 Cloudflare Workers / Docker 容器，服务端不被大并发的长连接 SSE 中继占用资源。 -* **分端落地机制**： - * **桌面端（Desktop App）**：通过主进程/直连网络通道彻底绕过浏览器同源策略（CORS），100% 直连所有主流厂商（OpenAI, Anthropic, Gemini, DeepSeek, Ollama 等）。 - * **移动端（Mobile App）**：React Native / 原生网络栈无 CORS 限制，直接发起模型 API 请求。 - * **Web 浏览器端**：支持 CORS 的模型 API（如 Gemini、部分兼容中转、本地 Ollama）直接发起前端 `fetch` 直连；仅在纯网页遇到严格 CORS 拦截时保留极轻量的预备协议（Prepare-Direct）。 +EdgeEver 的 `packages/client/src/index.ts` 已实现模型 API 直连、浏览器端 CORS 探测及服务端代理回退；Companion 也已有相应的准备、执行和检查点接口。本方案沿用这条链路，不新增“客户端永远直连”的原则，不改变凭据准备、服务端工具调用或回退行为。模型请求是否经过实例服务端，取决于运行环境、模型提供方和当前调用路径；隐私、延迟与带宽效果需按实际路径测量，不能一概保证。 --- @@ -110,7 +99,7 @@ flowchart TD subgraph UI_Presentation ["前端表现层 (apps/web)"] Sidebar["右侧伴随式侧栏 (AiSidebar)"] AiElements["Vercel ai-elements\n(Conversation, Message, Reasoning, PromptInput)"] - ActionSlot["业务插槽 (CompanionActionCard / ToolCall / Mermaid)"] + ActionSlot["业务插槽 (已校验的 CompanionActionCard / ACP 进度)"] InlineMenu["编辑器选区悬浮胶囊 (Quick Inline Actions)"] end @@ -120,14 +109,14 @@ flowchart TD end subgraph Provider_Channel ["多通道执行驱动 (Execution Channels)"] - DirectModelChannel["通道 A: 客户端直连三方模型 (Client-Direct Stream)\n(OpenAI / Gemini / DeepSeek / Ollama)"] - LocalAgentChannel["通道 B: 本地 Agent 驱动 (Local ACP)\n(@agentclientprotocol/sdk / Localhost)"] - ServerFallbackChannel["通道 C: 服务端中继兜底 (仅受限 Web 环境)\n(Cloudflare Worker / Docker Proxy)"] + ExistingAiChannel["通道 A: 现有 AI / Companion 调用链路\n(沿用已有直连与代理回退)"] + LocalAgentChannel["通道 B: 桌面本机 ACP\n(Electron 主进程 / stdio)"] + ActionValidation["EdgeEver 后端动作校验与确认\n(本机 Agent 写入接口待设计)"] end subgraph External_Entities ["外部执行实体"] - ModelProviders["三方 AI 模型官方 API\n(零服务端中转 / 隐私直达)"] - LocalAgent["本地电脑 AI Agent\n(Codex / Antigravity / Claude Code)"] + ModelProviders["现有配置的模型提供方"] + LocalAgent["已验证的本机 ACP Agent\n(Codex / Antigravity 等)"] end Sidebar --> AiElements @@ -136,12 +125,13 @@ flowchart TD Sidebar --> AgentManager ContextCollector --> AgentManager - AgentManager -->|优先直连| DirectModelChannel - AgentManager -->|本地 Agent| LocalAgentChannel - AgentManager -.->|受限环境兜底| ServerFallbackChannel + AgentManager -->|内置助手| ExistingAiChannel + AgentManager -->|仅桌面版、用户选择| LocalAgentChannel - DirectModelChannel --> ModelProviders + ExistingAiChannel -->|保持现状| ModelProviders LocalAgentChannel --> LocalAgent + LocalAgentChannel -.->|后续阶段：结构化提案| ActionValidation + ActionValidation -.->|有效待确认动作| ActionSlot ``` ### 3.2 交互时序图（本地 Agent 调度示例） @@ -152,22 +142,30 @@ sequenceDiagram actor User as 用户 participant Editor as 笔记编辑器 participant Sidebar as AI 助手右侧栏 (ai-elements) - participant Client as 本地 ACP 桥接器 - participant Agent as 电脑本地 Agent (Antigravity/Codex) + participant Client as Electron 主进程 ACP 客户端 + participant Agent as 已验证的本机 ACP Agent + participant API as EdgeEver 后端动作接口 User->>Editor: 选中文本或阅读长篇笔记 - Editor-->>Sidebar: 广播选区与笔记 Context + Editor-->>Sidebar: 提供选区与笔记 Context User->>Sidebar: 输入任务要求或发送指令 - Sidebar->>Client: 发起请求 (带上下文元数据) - Client->>Agent: 通过 stdio / WebSocket 发起 JSON-RPC (ACP) - Agent-->>Client: 实时流式推送 (思考过程 + Tool 执行) - Client-->>Sidebar: ai-elements 流式渲染打字机效果 - Agent-->>Client: 产出笔记修改方案 (Action Diff) - Client-->>Sidebar: 渲染 CompanionActionCard (带应用/拒绝按钮) - User->>Sidebar: 点击「应用修改」 - Sidebar->>Editor: 安全执行原子化补丁更新 + Sidebar->>Client: 经受限 IPC 发起请求 (带选定上下文) + Client->>Agent: 通过 stdio 发送 ACP 会话请求 + Agent-->>Client: session/update (消息与工具进度) + Client-->>Sidebar: 映射为侧栏可展示的事件 + opt 后续阶段：本机 Agent 提议修改笔记 + Agent-->>Client: 通过受限工具提交结构化操作意图 + Client->>API: 认证并提交提案 (接口待设计) + API-->>Client: 校验后创建待确认动作，或拒绝 + Client-->>Sidebar: 仅对有效动作展示 CompanionActionCard + User->>Sidebar: 点击「应用修改」 + Sidebar->>API: 请求应用待确认动作 + API-->>Sidebar: 返回执行结果或版本冲突 + end ``` +本机 ACP 首版仅向 Agent 提供用户选定的只读笔记上下文，不提供写入 EdgeEver 的工具；Agent 自身的本机工具权限另按其适配器配置。ACP 的工具事件或文件 Diff 不会自动成为 EdgeEver 笔记操作；开放笔记写入前必须另行设计受限工具、结构化提案、工作区权限、笔记版本校验和服务端确认接口，禁止本机 Agent 绕过现有门禁直接改写笔记。 + --- ## 4. 变更风险与防范预案 @@ -178,8 +176,8 @@ sequenceDiagram | :--- | :--- | | **功能价值** | 彻底消除弹窗遮挡编辑器的交互硬伤；大幅减少手写冗余代码；统一操作心智；打通本地高阶 Agent 生态。 | | **影响范围** | `apps/web/src/components/EditorPane.tsx` 布局容器、`apps/web/src/components/dialogs/AiAssistantDialog.tsx`（逐步废弃并替换）、`WorkspaceApp.tsx` 侧栏布局排布、i18n 多语言文案。 | -| **最坏后果** | 1. 窄屏下侧边栏挤压主编辑器可视区；
2. 移除旧问答模式导致部分习惯“单点点击替换”的用户感到路径变长；
3. 本地连接异常时出现无响应等待。 | -| **回滚与防范方案** | 1. **弹性布局**：严格设定桌面最小断点，小屏强制降级为遮罩抽屉（Drawer）；
2. **保留行内极速改写**：编辑器 Bubble Menu 保留直达轻量操作；
3. **渐进式替换**：底层 `api.streamAiGeneration` 与 `CompanionChat` 逻辑保持向前兼容，先实现并挂载新侧栏，验收无误后再清理旧 Dialog 代码；
4. **连接状态可见**：本地通道明确展示连接状态灯（Connected / Disconnected / Port）。 | +| **最坏后果** | 1. 窄屏下侧边栏挤压主编辑器可视区；
2. 移除旧问答模式导致部分习惯“单点点击替换”的用户感到路径变长；
3. 本地连接异常时出现无响应等待；
4. 若错误地将本机 Agent 输出当成可信笔记动作，可能覆盖旧内容或绕过写入确认。 | +| **回滚与防范方案** | 1. **弹性布局**：严格设定桌面最小断点，小屏强制降级为遮罩抽屉（Drawer）；
2. **保留行内极速改写**：编辑器 Bubble Menu 保留直达轻量操作；
3. **渐进式替换**：底层 `api.streamAiGeneration` 与 `CompanionChat` 逻辑保持向前兼容，先实现并挂载新侧栏，验收无误后再清理旧 Dialog 代码；
4. **连接状态可见**：本地通道区分程序未找到、需要登录、会话可用和连接失败。 | | **跨运行时验证项** | 严格禁止在核心 Server 代码中引入 Node 本地沙箱依赖，确保 Cloudflare Workers 与 Docker 镜像构建 100% 保持纯净与通过。 | --- @@ -194,7 +192,7 @@ sequenceDiagram ### 第二阶段：基于 `ai-elements` 重构对话流（UI Modernization） - [ ] 封装基于 `ai-elements` 的对话主视口：``, ``, ``, ``。 - [ ] 将思考过程接入 `` 折叠展示。 -- [ ] 迁移并重构 `CompanionActionCard`，以标准工具响应卡片的形式嵌入流中，保留 Diff 对比与安全应用门禁。 +- [ ] 将 `CompanionActionCard` 作为后端已校验动作的业务卡片嵌入消息流，保留 Diff 对比与安全应用门禁；ACP 工具进度另行呈现。 - [ ] 确保正文的 `@streamdown/mermaid` 与 `@streamdown/math` 完美兼容流式解析。 ### 第三阶段：模式收敛与快捷技能（Simplification） @@ -204,12 +202,13 @@ sequenceDiagram - [ ] 验证多语言（zh-CN, en-US, ja, zh-TW）文案的同步清理与统一。 ### 第四阶段：本地 Agent 桥接与协议接入（Local Agent Connectivity） -- [ ] 引入 `@agentclientprotocol/sdk`，在客户端封装轻量 ACP 通信适配器。 -- [ ] 实现桌面端**本地 Agent 智能嗅探（Auto-Discovery）**模块： - * 自动探测常见默认路径（`PATH`、`/Applications/.app/...`、`~/.local/bin/`、`~/.gemini/` 等）； - * 无缝复用本地桌面 App 已落盘的登录态，避免二次认证； - * 提供状态灯（`🟢 已检测到本地 Agent / ⚪ 未检测到`）及一键补全指引。 +- [ ] 引入 `@agentclientprotocol/sdk`，在 Electron 主进程封装 ACP v1 `stdio` 客户端，并通过受限 preload / IPC 向侧栏传递事件。 +- [ ] 实现桌面端**本机 ACP Agent 可用性验证**： + * 只查找明确支持的 ACP 适配器可执行程序，并允许用户手动指定路径；不读取登录凭据目录。 + * 完成 `initialize`、必要的认证流程与会话创建，再显示“可用”；分别展示未安装、需登录、连接失败等状态。 + * 首版提供安装与配置指引，不自动下载或安装二进制程序；按平台验证登录态是否能够复用。 - [ ] 在设置中增加“Agent 来源”选择项： * **内置服务模式**（默认）：继续连接当前 EdgeEver 后端 / Companion 接口； - * **本地 Agent 模式**：优先通过智能嗅探直连，或支持手动配置本地连接地址（如 `http://127.0.0.1:xxxx`）。 -- [ ] 联调本地 Agent（如 Antigravity / Codex / Claude Code），验证真实会话、文件上下文传递与修改回填。 + * **本地 Agent 模式**：桌面版从已验证的 ACP 适配器中选择，支持手动指定适配器程序路径；首版不接受任意本地网络地址。 +- [ ] 分别联调 Codex 与 Antigravity 的 ACP 适配器，验证握手、认证、真实会话、流式事件、取消和只读笔记上下文；其他 Agent 通过同样的验证后再加入。 +- [ ] 若后续开放本机 Agent 修改笔记，先完成服务端结构化提案与确认门禁设计，并验证版本冲突与失败恢复；不得将 ACP 文件 Diff 直接交给编辑器写入。