做了几年桌面工具，越来越确定一件事：AI Coding Agent 这类产品，最适合的形态就是桌面客户端。 浏览器里的 Web IDE 接触不到你本地完整的文件系统，权限模型绕来绕去，更别说把 AI 生成的命令直接丢进终端里跑。 LobsterAI 的思路很直接——用 Electron 把大模型能力、本地工作区、代码编辑器和执行环境串成一条完整的链路，让 AI 不只是补全代码，而是真正“替你干活”。 这篇文章不聊宣传话术，只拆架构：从进程模型、IPC 通信、流式输出到沙箱执行，再到后续的跨平台适配，把一条真实可落地的全链路方案摊开讲。 内容主要面向两类人：一类是准备自己写桌面端 AI Agent 的开发者，另一类是已经在用 Electron 做工具、想接 AI 能力但不知道从哪下手的团队。 看完你应该能照着搭出一个能跑的骨架，并对关键坑点心里有数。

1. 项目概述与整体设计

1.1 LobsterAI 要解决的问题

先说清楚 LobsterAI 到底是什么。 它本质上是一个嵌入式 AI 编程助手，常驻在桌面端，能够感知你正在编辑的文件、整个项目的目录结构、运行中的终端输出，然后基于这些上下文执行代码生成、命令建议、代码解释、测试生成等任务。

为什么非得是桌面端？ 因为编码场景里最值钱的上下文全在本地。 文件内容、git diff、运行日志、依赖树，这些都是零散的、高度私有的实时数据。 Web 端工具要么上传、要么授权浏览器访问本地目录（本质还是文件对话框的变体），体验始终有隔阂。 桌面端可以直接读取工作区，AI 看到的上下文完整，回复质量自然高一个档次。

LobsterAI 的核心使用流程是这样：你打开项目目录，在侧边栏的对话框里输入一句“帮我写一个处理 CSV 的 Python 脚本，支持大文件分块读取”，Agent 会先扫描当前目录结构、读取相关文件、理解项目风格，然后生成代码、写入编辑器，还可以直接调用终端执行验证。 整个过程不需要切换到浏览器，不需要复制粘贴，文件操作、命令执行、结果反馈全部在本地闭环。

这解决的痛点是分裂。 一个编码任务通常被拆成搜索资料、写代码、跑测试、修报错四步，每步换一个工具。 LobsterAI 的目标是让这四步走同一条链路：输入意图、收集上下文、模型推理、落地执行、反馈迭代。 适合的人群很明确——本地开发、重视数据隐私、需要 AI 直达命令行和文件系统的开发者。

1.2 为什么选 Electron 而不是 Tauri 或 Qt

很多人在选桌面框架时纠结过，尤其现在 Tauri 风头正盛，体积小、内存低，听起来很香。 但放在 AI Coding Agent 这个场景，Electron 有一些绕不开的优势。

第一，生态成熟度。 编辑器这块，Monaco Editor 本身就是 VS Code 同款内核，与 Electron 的契合度经过多年验证。 代码高亮、智能提示、diff 视图全部现成。 若用 Tauri 搭载 WebView，Monaco 的体积和渲染性能在不同系统上的表现差异很大，尤其在 Windows 上旧版 WebView2 会有兼容性问题。 做工具类应用，稳定性优先级高于包体积的炫技。

第二，Node.js 运行时一体化。 桌面 AI Agent 的核心能力是文件系统操作、子进程管理、终端交互。 Electron 主进程天然跑着 Node.js，直接使用 fs、child_process、net 这些模块，几乎零中间层。 Tauri 需要 Rust 侧暴露命令再通过桥接调用，数据量大时还需要考虑序列化开销，对于“读取整个工作目录树”这种高频操作，Electron 的开发效率高得多。

第三，跨平台一致性。 编码工具的用户从来不是单一平台。 Electron 把 Chromium 打包进去，意味着你在 macOS 上开发，放到 Windows 和 Linux 上渲染效果基本一致。 Tauri 依赖系统 WebView，不同平台的渲染差异和 CSS 兼容性需要投入额外测试成本。

当然，Electron 的代价也明确：安装包 100MB 起步，内存占用动辄几百 MB。 针对这个，LobsterAI 的做法是接受它，并用架构去平衡——让渲染进程只负责 UI，把 AI 推理、文件扫描、命令执行全部下沉到主进程或子进程，保证交互不掉帧。 这也是全链路架构设计的核心出发点。

1.3 全链路架构的完整视图

把 LobsterAI 的运行时拆成一句话：用户通过界面表达意图，主进程调度数据流，AI 服务负责推理，执行沙箱负责落地。 更细一点，整条链路分为六个环节。

• 会话输入：用户在对话框输入自然语言或代码相关指令。
• 上下文引擎：读取当前打开文件、工作区文件树、最近终端输出、项目配置（如 package.json、pyproject.toml）。
• 模型路由：根据任务类型决定用哪个模型（本地小模型做简单补全，云端大模型做复杂推理）。
• 流式输出：模型生成的增量内容实时推送到渲染进程，一边生成一边渲染。
• 落地执行：需要落盘的命令写入文件，需要运行的命令进入沙箱执行，并将输出回传。
• 反馈闭环：执行结果或代码结构变化再次进入上下文，供下一轮对话使用。

模块划分上，LobsterAI 采用四层结构：

渲染层（React + Monaco + 聊天面板） ↓ IPC（contextBridge 暴露白名单 API） 主进程（Electron Main：窗口管理、会话状态、文件操作、命令执行） ↓ 内部调用 能力层（上下文引擎、AI Provider 抽象、沙箱管理器）

有意思的地方在“能力层”这层。 它不只封装了简单的 fetch 调用，而是一组可插拔的服务。 后续加入新模型、新本地执行器、新文件索引方式，都不需要动主进程的窗口逻辑。 这也是全链路架构能持续演进的根基。

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

2.1 Electron 进程模型的分工与 IPC 设计

Electron 的进程模型对桌面 AI Agent 来说不是理论问题，而是直接影响 API 选型。 主进程掌管窗口生命周期，渲染进程展示界面，两者之间靠 IPC 通信。 在这个链路里，AI 流式响应、文件读写、命令执行都是耗时操作，如果走错进程，卡顿立刻可见。

LobsterAI 的进程职责划分如下：

• 主进程：所有 Node.js 能力——文件读写、子进程 spawn、AI 服务的网络请求、会话状态存储。
• 渲染进程：Monaco 编辑器、聊天面板、设置页、所有 React 组件状态。
• 预加载脚本（Preload）：通过 contextBridge 向渲染进程暴露白名单 API，比如window.lobster.openWorkspace()、window.lobster.streamChat()。

为什么不让渲染进程直接开 Node？ 主要原因是安全边界。 渲染进程加载的是不可信内容（AI 返回的 Markdown 可能携带链接，项目文件可能包含恶意内容），如果开启了nodeIntegration且禁用contextIsolation，页面内的任何脚本都有能力直接操作文件系统。 开发期没问题，打包后面对真实用户是灾难。

IPC 通信规范上，LobsterAI 统一使用ipcMain.handle/ipcRenderer.invoke模式，而不是send/on。 原因很实际：需要拿到返回值或错误信息。invoke天然支持 Promise，主进程 handler 抛出的异常能直接传回渲染进程的 catch。 比如读取文件内容，渲染进程这样调用：

// renderer/src/utils/file.ts const content = await window.lobster.readFile('/path/to/project/src/index.ts');

主进程对应：

// main/src/ipc/file.ts import { ipcMain } from 'electron'; ipcMain.handle('file:read', async (_event, filePath: string) => { if (!isPathInsideWorkspace(filePath)) { throw new Error('拒绝访问工作区外文件'); } return await fs.promises.readFile(filePath, 'utf-8'); });

这里做了一层路径校验，是很容易被忽略但很关键的细节。 桌面 Agent 的 IPC handler 本质上是一个能力边界，不能无条件信任渲染进程的请求。 即使渲染进程被攻破，攻击者也只能通过白名单 API 访问文件，而路径校验能拦住大部分越权操作。

2.2 菜单系统与全局快捷键的设计

做 Electron 应用，菜单是绕不开的。 LobsterAI 的菜单设计分两层：应用级菜单（窗口顶部）和编辑器右键上下文菜单。 点击“AI”菜单时，会根据当前会话状态动态变化，比如没有打开文件时，“AI: 解释当前文件”置灰，但“AI: 通用对话”保持可用。

有同学觉得 Electron 菜单就是Menu.buildFromTemplate然后Menu.setApplicationMenu，其实小细节很多。 比如 macOS 上第一个菜单项必须是 App 名称，Windows 上菜单栏默认显示。 LobsterAI 的做法是写一个菜单工厂函数，根据平台返回不同结构：

// main/src/menu.ts import { Menu, BrowserWindow } from 'electron'; export function buildAppMenu(win: BrowserWindow, isMac: boolean): Menu { const template: Electron.MenuItemConstructorOptions[] = [ ...(isMac ? [{ role: 'appMenu' }] : []), { label: 'AI', submenu: [ { label: '解释当前文件', accelerator: 'CmdOrCtrl+Shift+E', enabled: win && win.isFocused(), click: () => win.webContents.send('menu:explain-current-file'), }, { label: '运行 AI 命令', accelerator: 'CmdOrCtrl+Enter', click: () => win.webContents.send('menu:run-command'), }, ], }, { role: 'editMenu' }, { role: 'windowMenu' }, ]; return Menu.buildFromTemplate(template); }

快捷键的坑在于冲突。 比如CmdOrCtrl+Enter在聊天输入框内是发送消息，在全局也是运行命令，需要做栈式优先级处理，否则焦点在编辑器里按快捷键会触发双重动作。 LobsterAI 的解决方案是渲染进程侧维护一个“当前活跃面板”的状态，快捷键事件先判断焦点所在区域，再决定行为。

另外，菜单触发后向渲染进程发消息时建议带上目标窗口 id。 多窗口场景下BrowserWindow.getAllWindows()[0]可能不是你要的那个。 稳妥做法是用event.sender或记录的当前聚焦窗口引用。

2.3 AI 服务集成：流式输出与上下文窗口管理

LobsterAI 的 AI 层没有把自己绑死在某个厂商 SDK 上，而是实现了一个 OpenAI 兼容接口的 Provider。 好处是本地模型（Ollama 部署的 Qwen、Llama 等）和云端模型（GPT、Claude 等 OpenAI 兼容端点）可以统一接入，配置不同的baseURL即可。

流式输出的实现是这个模块的重头戏。 聊天面板上那些逐字蹦出来的效果不是setState不停刷新字符串，而是把 SSE 流做成可暂停、可重连的数据管道：

// main/src/ai/stream.ts export async function streamCompletion(params: ChatParams, onDelta: (text: string) => void) { const controller = new AbortController(); const timeoutTimer = setTimeout(() => controller.abort(), 120_000); const response = await fetch(params.baseURL + '/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${params.apiKey}`, }, body: JSON.stringify({ model: params.model, messages: params.messages, stream: true, }), signal: controller.signal, }); if (!response.ok) { throw new Error(`AI 服务返回 ${response.status}: ${await response.text()}`); } const reader = response.body!.getReader(); const decoder = new TextDecoder('utf-8'); let buffer = ''; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const lines = buffer.split('\n'); buffer = lines.pop() ?? ''; for (const line of lines) { if (!line.startsWith('data:')) continue; const data = line.slice(5).trim(); if (data === '[DONE]') return; try { const json = JSON.parse(data); const delta = json.choices?.[0]?.delta?.content ?? ''; if (delta) onDelta(delta); } catch { // 忽略不完整 chunk，等下一轮再拼 } } } clearTimeout(timeoutTimer); }

有两个细节值得说。 第一，TextDecoder不能直接逐段 decode 再 split，因为 UTF-8 字符可能被截断在两个 chunk 边界上，必须用{ stream: true }保持内部缓冲。 第二，超时时间 120 秒不是拍脑袋。 模型生成长代码时，首个 token 可能要几十秒，普通 HTTP 请求没有读取超时概念，只能靠 AbortController 兜底。

上下文窗口管理是个无底洞。 工作区文件动辄上千行全塞进 prompt，token 成本瞬间爆炸。 LobsterAI 的上下文章节采用策略性截断：

• 当前打开的文件：完整保留，最多 3000 token。
• 工作区文件树：只保留目录结构和文件名列表。
• 最近 git diff：保留，最多 1500 token。
• 历史对话：滑动窗口，最近 6 轮。

同时提供手动“锁定上下文”功能，把指定文件的选定行作为不可裁剪的强制上下文。 这样既保证常用场景的上下文质量，又控制成本。

2.4 代码执行沙箱：让 AI 生成的命令安全落地

这个模块是 LobsterAI 架构里争议最大、也最重要的部分。 AI 生成的代码有 bug 是常态，但更危险的是 AI 生成的 “修复命令”里有恶意指令——比如删除操作或者下载执行远程脚本。 桌面客户端直接调用child_process.spawn是不可能的，必须加沙箱。

沙箱设计分两层：软沙箱和硬沙箱。

软沙箱是 LobsterAI 默认启用的一层规则。 命令执行时限定工作目录、环境变量白名单、命令白名单（部分允许）、超时强制终止、输出流大小限制。 这套方案不依赖 Docker，适合本地快速执行常见命令：

// main/src/sandbox/soft-sandbox.ts import { spawn } from 'child_process'; export function runInSoftSandbox(command: string, cwd: string, timeoutMs = 30_000) { return new Promise<{ stdout: string; stderr: string; code: number | null }>((resolve, reject) => { const allowedPrefixes = ['npm run', 'pnpm', 'python3', 'node', 'git status']; // 黑名单词直接拒绝 const deniedPatterns = [/\bsudo\b/, /\brm\s+-rf\s+(?:\/|~)/, /\bcurl\s+.*\s*\|.*sh/]; if (deniedPatterns.some((re) => re.test(command)) || !allowedPrefixes.some((pre) => command.startsWith(pre))) { reject(new Error('命令不在白名单内，已拒绝执行')); return; } const child = spawn(command, { cwd, shell: true, env: { ...process.env } }); const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs); let stdout = ''; let stderr = ''; child.stdout.on('data', (chunk) => (stdout += chunk.toString())); child.stderr.on('data', (chunk) => (stderr += chunk.toString())); child.on('close', (code) => { clearTimeout(timer); resolve({ stdout, stderr, code }); }); child.on('error', reject); }); }

实际操作里，白名单前缀的方案比较粗糙，但作为默认防线足够。 真正需要执行复杂命令且环境允许 Docker 时，硬沙箱方案更可靠：把项目目录挂载进容器、只读访问系统目录、网络策略限制为--network=bridge，容器内执行结束后销毁。 开销大，但隔离性强。

无论如何，绝对不要在渲染进程直接执行子进程命令。 渲染进程的沙箱隔离机制一旦失效，恶意页面代码可以无限制调用 shell。 这属于安全底线的设计决策，没有妥协空间。

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

3.1 项目初始化的技术栈选择

LobsterAI 的前身是一个 Electron + React 原型，后来重构为 electron-vite 组织。 选 electron-vite 而不是裸手写 webpack 配置，原因是它能同时处理主进程、预加载脚本和渲染进程三套构建，开发模式下热重载不需要额外插件。

依赖清单按作用分三组：

• UI 组：react、zustand（聊天状态管理）、monaco-editor。
• Electron 生态：electron（运行时）、electron-builder（打包）、electron-vite（构建）。
• 工具组：typescript、pnpm、simple-git（git 状态读取）、ky（渲染进程轻量请求）。

工程目录严格执行 main / preload / renderer / shared 四层隔离：

lobster-ai/ ├── build/ # 打包配置 ├── src/ │ ├── main/ # 主进程代码 │ ├── preload/ # 预加载脚本 │ ├── renderer/ # React 应用 │ └── shared/ # 主进程与渲染进程共享的类型和常量 ├── electron.vite.config.ts └── package.json

shared目录很关键。 IPC 通信的事件名、请求响应类型定义全部放在这里，主进程和渲染进程都引用同一份类型，避免两边改了事件名调试半天的惨剧。

初始化命令：

pnpm create @quick-start/electron lobster-ai --template react-ts cd lobster-ai pnpm install pnpm add zustand simple-git ky pnpm add -D monaco-editor

3.2 主进程核心代码：文件操作与命令执行

主进程的代码风格很简单：每个功能域一个 module，在src/main/ipc下统一注册 handler。 这里以“打开工作区”和“运行命令”两个实例说明。

打开工作区不只是弹出文件夹对话框，还要在确认后做三件事：验证路径存在、构建文件树索引、把根路径返回给渲染进程供编辑器使用：

// main/src/ipc/workspace.ts import { dialog, ipcMain, BrowserWindow } from 'electron'; import { promises as fs } from 'fs'; import path from 'path'; ipcMain.handle('workspace:open', async (event) => { const win = BrowserWindow.fromWebContents(event.sender); if (!win) return null; const result = await dialog.showOpenDialog(win, { properties: ['openDirectory'], title: '选择工作区目录', }); if (result.canceled || result.filePaths.length === 0) return null; const root = result.filePaths[0]; // 限制深度，避免巨大目录导致索引卡顿 const entries = await buildFileTree(root, 3); return { root, entries }; }); async function buildFileTree(dir: string, depth: number): Promise<any> { if (depth <= 0) return []; const list = await fs.readdir(dir, { withFileTypes: true }); const result = []; for (const ent of list) { if (ent.name.startsWith('.') || ent.name.includes('node_modules')) continue; const full = path.join(dir, ent.name); result.push({ name: ent.name, path: full, dir: ent.isDirectory(), children: ent.isDirectory() ? await buildFileTree(full, depth - 1) : [], }); } return result; }

这里跳过node_modules是必须的。 即使限制深度 3，一个大型前端项目的 node_modules 也能让递归直接卡住。 更合理的方案是读取.gitignore来生成忽略列表，不过作为原型，写死忽略前缀已经解决 90% 问题。

命令执行这块走前面提到的软沙箱，同时把 stdout 和 stderr 分别回传。 注意 GUI 应用启动时往往不加载.bashrc/.zshrc，导致用户配置的 PATH 不在环境中。 实测最稳的做法是请求中带上 shell 路径，或者先跑一次$SHELL -lc 'echo $PATH'解析出有效环境变量。

3.3 渲染进程核心代码：Monaco 与聊天面板

渲染进程最复杂的部分是 Monaco 和聊天面板的联动。 Monaco 初始化需要指定语言、主题和自动布局：

// renderer/src/components/Editor.tsx import Editor, { loader, type OnMount } from '@monaco-editor/react'; const handleMount: OnMount = (editor, monaco) => { editor.updateOptions({ minimap: { enabled: false }, fontSize: 14, tabSize: 2, automaticLayout: true, }); // 注册 command，供 AI 回写代码使用 window.lobster.onWriteCode((content: string) => { editor.getModel()?.setValue(content); }); }; export function CodeEditor() { return ( <Editor height="calc(100vh - 40px)" defaultLanguage="typescript" theme="vs-dark" onMount={handleMount} options={{ readOnly: false }} path={window.lobster.currentFile ?? undefined} /> ); }

流式消息渲染是另一个容易做错的地方。 聊天消息列表是数组，每次收到 delta 就更新数组末尾的 message.content，会导致整个列表重新渲染，长对话时肉眼可见地卡。 优化方案是只更新尾部消息组件：

// renderer/src/components/ChatMessage.tsx export function ChatMessage({ msg }: { msg: Message }) { const textRef = useRef<HTMLDivElement>(null); useEffect(() => { // 只在增量场景追加 DOM 文本，减少 React 渲染 if (msg.appendMode && textRef.current) { textRef.current.textContent += msg.delta ?? ''; } }, [msg.delta]); return <div ref={textRef}>{msg.content}</div>; }

这算一个面试级优化点：流式 UI 的卡顿通常不是网络慢，而是每 tick 触发一次整个列表的 reconciliation。

3.4 关键参数与调优配置

把实践中的参数值整理成一张表，方便直接参考：

这几个数值不是凭空定的，比如 chunk 大小取决于渲染线程 16ms 一帧的预算。 512 字符做文本渲染通常低于 1ms，留出富余给编辑器其他操作。

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

4.1 白屏与预加载脚本失效

Electron 开发中最常遇到的问题是窗口开出来了但一片空白。 常见原因之一是预加载脚本路径错误，或者 preload 脚本使用了require但运行环境是 sandbox。 排查步骤：

先看开发者工具里 Console 有没有报错。 如果报require is not defined，多半是预加载脚本在 sandbox 环境下运行，不能使用 CommonJS 的require。 解决方案是改用 ESM 或让 electron-vite 把 preload 打包成 cjs 格式。 另一个坑是开启contextIsolation: true后，window 上挂载的自定义属性需要通过contextBridge.exposeInMainWorld暴露，不能直接window.lobster = ...。

4.2 流式输出界面掉帧

现象是 AI 回复时聊天面板滚动卡顿，甚至整个窗口无响应。 原因通常有两个：渲染进程主线程被同步操作霸占，或者 IPC 高频调用压垮了序列化通道。

检查方法：打开 Chrome DevTools 的 Performance 面板，录制几秒，看长任务（Long Task）出现在哪里。 如果是JSON.parse频繁执行，说明 AI chunk 序列化太细，应该在主进程拼接好 20 个 delta 再发送一次。 如果是setState触发的全列表渲染，参考前面的ChatMessage优化方案，改用 DOM append。

4.3 命令执行时找不到命令

桌面应用双击打开时，环境的 PATH 与终端里不同。 比如用户终端里装好了pnpm，但 LobsterAI 执行pnpm test时提示pnpm: command not found。

排查思路是先打印process.env.PATH，确认缺了什么。 解决方案是让用户配置 Shell 路径，执行时改为：

$SHELL -lc "cd /path/to/project && pnpm test"

注意-lc表示加载登录 shell 的配置。 但这也带来新问题：某些 shell 的启动配置会执行耗时任务，导致首条命令延迟。 折中方案是把解析出的 PATH 缓存起来，后续命令直接带上。

4.4 打包体积与旧系统兼容性

Electron 应用打包后普遍 150MB 起步，这个无法避免，但可以做一些优化：移除不必要的 Chromium 开关、压缩 asar 包、排除系统原生依赖。 electron-builder 里设置files白名单只打包需要的文件，能去掉很多开发依赖。

有趟过一个真问题：企业用户还在用 Win7，而新版本 Electron 18+ 不再支持 Win7。 如果目标用户包含这类环境，需要锁定 Electron 版本在 22 以下，并承担部分安全更新缺失的风险。 至于 Windows 95 这类更老的系统，Electron 本身无法运行，不必考虑兼容。 合理策略是调研用户系统占比，用少数用户换取现代化框架是值得的权衡。

5. 架构演进与扩展思考

5.1 多模型路由与离线回退

LobsterAI 的 AI Provider 抽象层让多模型接入变得简单，但真正的价值在于路由策略。 简单场景（代码格式化、简单问答）用本地模型回复，成本和延迟都很低；复杂场景（跨文件重构、多步骤任务）路由到云端大模型。

实现上维护一个模型能力矩阵，每个任务类型标注最小模型能力等级。 调用前先用本地轻量模型做意图分类，再路由。 这个设计在断网或内网环境下尤为重要：本地模型离线可用，保证 Agent 的核心功能不依赖外网，这对很多企业用户是刚需。

5.2 跨平台移植与新系统适配

近两年经常有人问 Electron 应用怎么往 HarmonyOS 这类新平台迁移。 思路其实和其他 Web 技术栈移植类似，核心是分层替换，而不是推倒重写。

渲染层保留现有的 React + Monaco Web 代码，迁移到鸿蒙时用 ArkWeb 组件承载，界面这部分改动最小。 主进程的 Node.js 能力（文件操作、网络请求、子进程管理）需要改写为鸿蒙的 Stage Model API：文件系统用@ohos.file.fs，网络用@ohos.net.http，子进程则要看具体 API 支持程度，不行就降级为“生成命令让用户手动执行”。

这套迁移方案的前提是架构里已经做了“能力层”抽象。 如果最初把 Node.js 调用写得到处都是 IPC handler 满天飞，迁移时会非常痛苦。 所以从一开始就要坚持 IPC 层只负责通道，具体业务逻辑在能力层收口。

5.3 插件化与 Agent 能力扩展

全链路架构的下一步是插件化。 例如让用户注册自定义工具：读取测试覆盖率、提交代码到远程仓库、重启 Docker 容器。 这些工具以 JSON Manifest 注册到 Agent 的能力列表，AI 根据用户意图自动选择调用。

这对架构提出的新要求是：工具调用的参数需要强校验，返回值需要结构化。 否则 AI 生成run_command({ command: 'rm -rf /' })时，容错空间为零。 真正的 Agent 是要能失误的，但架构要保证失误只影响沙箱，不影响宿主系统。 这同时也是未来把一个单机 Agent 演进成多机协同 Agent 的基础。

回到 LoobsterAI 本身，用 Electron 做桌面 AI Coding Agent 从来不是最优美方案，却是当前综合成本最低的方案。 如果让我再选一次，依然会选 Electron，但一定会用今天拆解过的这些架构设计去打磨每一个细节。 别把 AI 塞进渲染进程，别把文件读取做成同步操作，别让命令执行裸奔。 踩过这几个坑，你的 Agent 就已经能跑得比大多数原型稳了。