企业官网建设流程全解析

1. 多 Agent 桌面 IDE 的整合思路与选型逻辑

1.1 为什么会有“换一个 Agent 就要换一个软件”的痛点

过去大半年，我几乎把市面上主流的命令行 AI 编程助手都折腾了一遍。Claude Code、Codex、Pi 这几个名字，相信经常写代码的朋友都不陌生。它们各自有各自的强项：Claude Code 在长上下文理解和复杂重构上表现突出，Codex 在代码补全和快速生成片段上响应极快，Pi 则在子任务拆解和工具调用链路上有自己的设计。问题在于，这三个东西的入口完全不一样——Claude Code 有自己的 CLI 和桌面端，Codex 有独立的安装包和交互界面，Pi 又是另一套 agent 框架。

结果就是我的工作流被切得稀碎。写一个功能，先用 Codex 生成骨架，切到 Claude Code 做重构，再开 Pi 跑子任务验证。每切一次，就要换窗口、换快捷键、换上下文记忆方式。一天下来，光是“切换”这个动作就消耗了大量注意力。更别提每个工具的配置目录、环境变量、代理设置都不一样，维护成本极高。

这个项目的出发点很朴素：能不能把这三个 Agent 塞进同一个桌面 IDE 里，用统一的界面和一套鼠标手势来操作？答案是能，而且实测下来体验比想象中顺滑。

1.2 整体架构：一个壳，三个引擎

核心思路是做一个“壳层 IDE”，它本身不实现 AI 能力，而是作为统一的前端容器，把 Claude、Codex、Pi 三个 Agent 作为可切换的后端引擎来管理。这个壳层负责几件事：统一的输入输出面板、会话上下文的路由、鼠标手势的映射、以及各 Agent 配置的隔离与加载。

为什么选择“壳层”而不是“插件化”？因为插件化要求每个 Agent 都提供标准接口，而这三个工具的接口形态差异太大。Claude Code 偏向对话式交互，Codex 偏向代码片段补全，Pi 偏向任务链编排。硬做插件化会丢失各自特性。壳层方案则是在保留各自原生能力的前提下，只统一“入口”和“操作方式”。

具体来说，壳层 IDE 维护一个 Agent 注册表，每个 Agent 对应一个适配器。适配器负责把统一的操作指令翻译成该 Agent 能理解的调用方式，再把返回结果归一化后渲染到统一面板。这样切换 Agent 时，用户看到的界面布局不变，只是背后的引擎换了。

1.3 鼠标手势的设计考量

鼠标手势是这个项目里我觉得最值得聊的部分。键盘快捷键当然也能做，但手势的优势在于“肌肉记忆”和“低认知负荷”。比如按住右键画一个“L”形，就切换到下一个 Agent；画一个圆圈，就清空当前会话；向上划是提交，向下划是回滚。这些动作不需要看键盘，手不用离开鼠标。

手势识别的实现并不复杂，核心是记录鼠标轨迹的关键点序列，做方向向量归一化，然后匹配预定义的手势模板。难点在于阈值调优——太灵敏会误触，太迟钝会画不出来。我试过几组参数，最后定在采样间隔 16ms、最小轨迹长度 80px、方向容差 30 度。这套参数在 1080p 和 4K 屏幕上都能稳定工作。

注意：手势操作一定要提供“撤销”和“确认”机制。我早期版本没有确认步骤，结果误触切换 Agent 导致上下文丢失，非常恼火。后来改成手势触发后弹出半透明提示，200ms 内可以按 Esc 取消。

2. 核心细节解析与实操要点

2.1 Agent 适配器的关键实现

每个 Agent 的适配器需要解决三个问题：进程管理、通信协议、上下文同步。

Claude Code 的适配器相对直接，它本身提供了本地服务端口，壳层通过 HTTP 长连接发送指令并接收流式响应。需要注意的是它的会话状态是服务端维护的，所以切换 Agent 再切回来时，要主动查询当前会话 ID 并恢复。

Codex 的适配器要处理的是它的补全式交互。Codex 更习惯接收“当前文件内容 + 光标位置”这样的上下文，返回的是插入建议。所以在壳层里，Codex 模式下我会把编辑器当前缓冲区的内容和光标偏移一起打包发送，返回结果直接以 diff 形式预览。

Pi 的适配器最复杂，因为 Pi 的 agent 模型支持多步子任务。壳层需要把 Pi 返回的任务链解析成可视化的步骤列表，每一步可以单独展开查看中间结果。这里我用了一个简单的状态机来跟踪 Pi 的任务执行状态：pending、running、done、failed。

2.2 配置隔离与环境变量管理

三个 Agent 的配置目录默认都在用户主目录下，如果直接共用会互相污染。我的做法是在壳层启动时，为每个 Agent 创建独立的配置沙箱目录，通过环境变量把各自的配置路径重定向过去。

具体操作上，壳层维护一个agents.json配置文件，结构大致如下：

{ "agents": [ { "id": "claude", "name": "Claude Code", "configDir": "~/.shell-ide/agents/claude", "env": { "CLAUDE_CONFIG_DIR": "~/.shell-ide/agents/claude" } }, { "id": "codex", "name": "Codex", "configDir": "~/.shell-ide/agents/codex", "env": { "CODEX_HOME": "~/.shell-ide/agents/codex" } }, { "id": "pi", "name": "Pi Agent", "configDir": "~/.shell-ide/agents/pi", "env": { "PI_WORKSPACE": "~/.shell-ide/agents/pi" } } ] }

这样每个 Agent 的登录态、缓存、会话历史都是独立的，互不干扰。实测下来，Claude 和 Codex 同时运行也不会出现端口冲突或配置覆盖。

2.3 鼠标手势的映射表设计

手势映射我做成可配置的，默认方案如下：

这套映射我用了两周，基本形成了肌肉记忆。最常用的是左右横划切换 Agent，比找快捷键快很多。

提示：手势映射表建议导出为独立文件，方便在不同机器间同步。我把它放在~/.shell-ide/gestures.json，换电脑时直接拷贝。

2.4 上下文路由的注意事项

多 Agent 共存最大的坑是上下文串味。比如你在 Claude 里聊了一半的需求，切到 Codex 后它并不知道之前的对话。我的处理方式是：壳层维护一个“共享上下文摘要”，每次切换 Agent 时，把最近 N 轮对话的关键信息压缩成一段简短描述，作为系统提示注入到新 Agent 的会话开头。

这个摘要不能太长，否则会占用新 Agent 的上下文窗口。我实测下来，控制在 200 字以内效果最好。摘要内容只保留：当前任务目标、已确认的技术选型、待解决的问题。具体代码细节不放进摘要，因为新 Agent 可以自己读文件。

3. 实操过程与核心环节实现

3.1 环境准备与依赖安装

先说一下我的运行环境：macOS 14.5，M2 Pro，32GB 内存。Windows 和 Linux 理论上也能跑，但手势库在三个平台上的表现有差异，下面会提到。

第一步是安装三个 Agent 的原生 CLI。Claude Code 和 Codex 都有官方安装脚本，Pi 需要从它的仓库拉取。这里不展开具体安装命令，因为各平台差异大，而且版本更新频繁。核心原则是：先确保每个 Agent 单独能跑通，再往壳层里集成。

第二步是准备壳层的运行环境。我用的是 Electron + Node.js，因为需要跨平台窗口管理和原生鼠标事件捕获。Electron 的globalShortcut和screen模块能满足大部分需求，但鼠标手势需要额外用uiohook-napi这类库来捕获全局鼠标事件。

# 壳层项目初始化 mkdir shell-ide && cd shell-ide npm init -y npm install electron uiohook-napi axios ws

3.2 壳层主进程与 Agent 进程的通信

壳层主进程负责启动和管理三个 Agent 的子进程。每个 Agent 启动时，壳层会分配一个独立的本地端口，并通过环境变量注入。

const { spawn } = require('child_process'); const net = require('net'); function getFreePort() { return new Promise((resolve) => { const server = net.createServer(); server.listen(0, () => { const port = server.address().port; server.close(() => resolve(port)); }); }); } async function startAgent(agentConfig) { const port = await getFreePort(); const env = { ...process.env, ...agentConfig.env, AGENT_PORT: String(port) }; const child = spawn(agentConfig.command, agentConfig.args, { env, cwd: agentConfig.configDir }); return { child, port }; }

通信层用 WebSocket 做双向流式传输。Claude 和 Pi 的响应本身就是流式的，Codex 虽然以补全为主，但也可以包装成流式返回。统一用 WebSocket 的好处是壳层只需要维护一套消息协议。

消息协议我定义得很简单：

{ "type": "request | response | stream | error", "agentId": "claude | codex | pi", "sessionId": "uuid", "payload": {} }

3.3 鼠标手势的捕获与识别

手势捕获用uiohook-napi监听全局鼠标事件。核心逻辑是：按下右键时开始记录轨迹点，移动时持续追加，松开时进行识别。

const { uIOhook } = require('uiohook-napi'); let recording = false; let points = []; uIOhook.on('mousedown', (e) => { if (e.button === 2) { recording = true; points = [{ x: e.x, y: e.y, t: Date.now() }]; } }); uIOhook.on('mousemove', (e) => { if (recording) { points.push({ x: e.x, y: e.y, t: Date.now() }); } }); uIOhook.on('mouseup', (e) => { if (e.button === 2 && recording) { recording = false; const gesture = recognizeGesture(points); if (gesture) handleGesture(gesture); } });

识别函数先做降采样和去噪，然后计算相邻点之间的方向向量，归一化后与模板匹配。

function recognizeGesture(points) { if (points.length < 5) return null; const filtered = points.filter((p, i) => { if (i === 0) return true; const prev = points[i - 1]; return Math.hypot(p.x - prev.x, p.y - prev.y) > 3; }); const totalLength = filtered.reduce((sum, p, i) => { if (i === 0) return 0; const prev = filtered[i - 1]; return sum + Math.hypot(p.x - prev.x, p.y - prev.y); }, 0); if (totalLength < 80) return null; const directions = []; for (let i = 1; i < filtered.length; i++) { const dx = filtered[i].x - filtered[i - 1].x; const dy = filtered[i].y - filtered[i - 1].y; const angle = Math.atan2(dy, dx) * 180 / Math.PI; directions.push(angle); } return matchTemplate(directions); }

模板匹配用的是方向序列的编辑距离，容差 30 度。这套逻辑在 macOS 上很稳，Windows 上需要把右键事件换成中键或者侧键，因为 Windows 的右键菜单会干扰手势录制。

3.4 统一输入面板与 Agent 切换

输入面板是用户接触最多的部分。我把它设计成底部固定区域，支持多行输入、历史回溯、以及 Agent 标识显示。切换 Agent 时，面板背景色会变化，给用户明确的视觉反馈。

切换逻辑本身很简单，就是更新当前活跃的 Agent ID，然后重新绑定 WebSocket 连接。但要注意：切换前必须把当前输入框的内容暂存到该 Agent 的草稿区，切回来时恢复。这个细节不做的话，用户切一下 Agent 输入的内容就没了，体验极差。

const drafts = new Map(); function switchAgent(newAgentId) { const current = getCurrentAgentId(); drafts.set(current, inputPanel.getValue()); setCurrentAgentId(newAgentId); inputPanel.setValue(drafts.get(newAgentId) || ''); rebindWebSocket(newAgentId); updatePanelTheme(newAgentId); }

3.5 会话持久化与恢复

每个 Agent 的会话历史我存在本地 SQLite 里，按 Agent ID 和会话 ID 分表。壳层启动时，会读取上次活跃的会话并恢复。这样即使关掉 IDE 再打开，之前的对话还在。

CREATE TABLE sessions ( id TEXT PRIMARY KEY, agent_id TEXT NOT NULL, title TEXT, created_at INTEGER, updated_at INTEGER ); CREATE TABLE messages ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, role TEXT NOT NULL, content TEXT NOT NULL, created_at INTEGER, FOREIGN KEY (session_id) REFERENCES sessions(id) );

恢复会话时，壳层会把历史消息重新渲染到面板，但不会重新发送给 Agent。Agent 那边的会话状态由它自己维护，壳层只负责展示。

4. 常见问题与排查技巧实录

4.1 Agent 启动失败或端口占用

这是最常见的问题。表现是壳层显示 Agent 离线，或者切换过去后没有响应。排查步骤：

1. 检查该 Agent 的配置目录是否存在且可写。
2. 检查分配的端口是否被其他进程占用。
3. 查看 Agent 子进程的 stderr 输出，通常会有明确报错。

我遇到过一次 Claude 启动失败，原因是它的配置目录里有一个损坏的缓存文件。删掉缓存后恢复正常。所以壳层最好提供一个“重置 Agent 配置”的按钮，一键清空沙箱目录。

4.2 手势识别不灵敏或误触

手势问题通常出在采样率和阈值上。如果用户画得很快，采样点太少，方向序列就不完整。解决办法是提高采样率，或者在识别前做插值。

误触则相反，通常是阈值太低。我把最小轨迹长度从 50px 提到 80px 后，误触率明显下降。另外，建议给手势加一个“冷却时间”，同一个手势在 500ms 内只触发一次。

4.3 切换 Agent 后上下文丢失

这个问题的根源是壳层没有做上下文摘要注入。我的解决方案是在切换时，从当前会话的最后几轮对话中提取关键信息，生成一段简短摘要，作为新 Agent 的第一条系统消息。

摘要生成可以用一个轻量级的本地模型，也可以直接用规则提取。我用的是规则提取：抓取最近三轮对话中的用户消息，去掉代码块和冗余描述，保留任务目标和约束条件。

注意：摘要不要包含具体的代码内容，否则会占用新 Agent 大量上下文窗口。只保留“做什么”和“为什么”，不保留“怎么做”。

4.4 流式响应卡顿或中断

流式响应依赖 WebSocket 长连接，网络波动或 Agent 进程崩溃都会导致中断。壳层需要做重连和断点续传。

我的做法是：每条流式消息带一个序号，壳层记录已接收的最大序号。重连后，从最大序号+1 开始请求续传。Agent 适配器需要支持这个续传协议，否则就只能重新生成。

实测下来，Claude 和 Pi 的流式接口比较稳定，Codex 偶尔会断。给 Codex 适配器加了一个 30 秒超时重试后，基本没再出过问题。

4.5 多 Agent 同时运行导致资源占用过高

三个 Agent 同时跑，内存占用确实不小。我的 M2 Pro 上，三个都活跃时大概占用 4-6GB 内存。如果机器配置一般，建议用“按需启动”策略：只有切换到某个 Agent 时才启动它的进程，切走后 5 分钟无活动就自动休眠。

休眠不是杀死进程，而是发送一个暂停指令，让 Agent 释放计算资源但保留会话状态。Claude 和 Pi 都支持这种暂停恢复，Codex 需要额外处理，因为它本身没有会话概念。

4.6 配置文件同步与迁移

换机器时，最麻烦的是三个 Agent 的登录态和配置。我的做法是把整个~/.shell-ide目录打包迁移，里面包含了所有 Agent 的沙箱配置、手势映射、会话数据库。新机器上解压后，只需要重新登录各 Agent 的账号即可。

但要注意：某些 Agent 的登录 token 和机器指纹绑定，直接拷贝可能失效。这种情况下只能重新登录。所以迁移前最好确认哪些配置是可移植的，哪些需要重新生成。

5. 一些实操心得与后续扩展方向

这个壳层 IDE 我用了大概一个月，最大的感受是：统一入口带来的效率提升，远大于单个 Agent 能力差异带来的影响。以前切换工具要花 10 秒，现在一个手势 1 秒搞定。一天切换几十次，省下来的时间和注意力非常可观。

另一个心得是：不要试图让三个 Agent 完全共享上下文。它们各自的设计哲学不同，强行统一反而会削弱各自优势。壳层应该做的是“让切换无感”，而不是“让它们变成一个”。共享摘要只保留最必要的任务信息，具体执行细节让每个 Agent 用自己的方式处理。

后续我打算加两个功能。一是 Agent 编排：让壳层根据任务类型自动选择最合适的 Agent，比如代码生成走 Codex，重构走 Claude，任务拆解走 Pi。二是手势自定义录制：让用户自己画一遍手势来绑定动作，而不是从预设列表里选。这两个功能都不难，核心逻辑已经在了，主要是交互设计要打磨。

如果你也在用多个 AI 编程助手，强烈建议试试这种壳层整合的思路。不一定非要用 Electron，用 Tauri 或者纯 Web 方案也能做，关键是把手势和统一面板这两个体验点做好。踩过的坑我都写在上面了，照着做能省不少时间。