写在前面

我是一名前端，日常更熟 React、工程化、性能优化。最近看招聘 JD，Electron + AI Agent 出现得很频繁：不仅要会调模型 API，还要能讲清整条链路——

用户输入 → 模型决策 → Tool Calling → 结果回写

于是我做了一个小 Demo：LocalDev Agent。它不是又一个网页聊天框，而是跑在本机的 Electron 桌面应用：你可以选定一个代码目录，用自然语言问「这个项目是干什么的」「IPC 相关代码在哪」，Agent 会真正去列目录、搜文件、读内容，再回答你。

不会我学还不行嘛，学学学！！！

这篇文章用前端能听懂的方式，把我踩过的概念和实现思路记下来。

先分清：聊天机器人 ≠ Agent

	普通 Chatbot	Agent
能力	主要靠训练知识和对话上下文	能调用外部能力（工具）
典型行为	直接生成文字	先决定「要不要动手」，再总结
前端类比	调一个返回字符串的接口	模型返回「要调哪个函数 + 参数」，你的程序去执行

LocalDev Agent 的工具目前是只读的：

list_directory：列目录
read_file：读文件
search_files：内容搜索（类 grep）
get_project_overview：快速看项目结构 / package.json

模型不会「假装读过代码」——至少在我们设计上，要求它优先调工具再下结论。

为什么必须是 Electron，而不是纯 Web？

浏览器里的前端碰不到用户本机任意目录（安全限制）。
要做「本机开发助手」，需要 Node 能力读文件——这正好落在 Electron 主进程。

于是架构自然拆成三层，前端同学可以这样记：

工具为什么放在主进程？

权限：只有主进程方便安全地访问文件系统
沙箱：渲染进程 nodeIntegration: false，不把 Node 直接暴露给页面
边界清晰：UI 只负责展示，执行与安全策略集中在一边，面试也好讲

Local-dev-agent

整体架构

提问时序

整体链路长什么样？

一次提问，大致是这样：

UI 上我会把每次工具调用做成可展开卡片：参数 / 结果 / 成功失败 一目了然。演示和排错都省事，也比「黑盒聊两句」更像工程作品。

关键实现 1：Preload 只暴露最小 API

安全做法是 contextIsolation: true，用 contextBridge 挂一个很薄的 window.localDev：

前端用法就像调自家 SDK：

原则：能少暴露就少暴露。页面不该拿到任意 ipcRenderer.send 的权力。

关键实现 2：Tool Calling 循环（以及如何防死循环）

主进程里大致是一个 while：

带着历史消息 + 工具定义调模型
若没有 tool_calls → 输出最终回答，结束
若有 → 逐个 executeTool，把结果以 role: 'tool' 写回消息列表
再进入下一轮推理

前端同学可以把它理解成：

模型不只返回 content 字符串，还可能返回「请调用这些函数」；
你的 Node 代码当运行时，跑完把结果交回去，让模型继续想。

一定要设上限，例如 MAX_TOOL_ROUNDS = 8。否则模型万一反复搜同一个关键词，会空转烧 Token。这是很小但很「工程」的细节，面试官往往爱听。

关键实现 3：Memory 不是魔法，RAG 也先别慌

对话 Memory（本项目已有）

就是把多轮 messages（user / assistant / tool）继续带给模型。
不是 DeepSeek「自己记住了你」，而是你的 App 把上下文又传了一遍。

清空会话 = 丢掉这段数组。就这么朴素。

RAG 是什么？要不要现在做？

把整份 PDF 塞进 prompt 再问，多数时候只是「加长上下文」，还不算严格 RAG。

真正的 RAG 更接近：

文档切成小段
做成向量入库
提问时先检索相关片段
再把片段 + 问题交给模型

对本 Demo，用 Tool 去读仓库、搜代码，已经能覆盖「问这个项目」的场景。
Memory 够讲，RAG 是加分项，不阻塞面试演示。

关键实现 4：工作区沙箱

Agent 能读盘，不等于能读整台电脑。

用户先选一个「工作区目录」，所有 read_file / search_files 都做路径归一化，并校验：

解析后的绝对路径必须落在工作区根目录之内。

尝试读 /etc/passwd 或工作区外的路径，应直接失败。
能力与边界一起讲，比只秀「会调模型」更完整。

我怎么演示这个项目（给你抄作业）

「这个项目是干什么的？」
观察是否先出现 get_project_overview / list_directory 等工具卡片，再出总结。
「搜索 IPC / preload 相关代码，并说明通信怎么做的」
证明模型会 search_files + read_file，而不是空口白话。
不清空，追问一句
「用前端能听懂的方式再总结一遍刚才的链路」——证明 Memory（历史 messages）在起作用。

口述可以压成 30 秒：

渲染进程负责聊天 UI；读文件和 Agent 循环在主进程。
用户提问后，模型决定是否 Tool Calling；工具经 IPC 执行，结果事件推回 React 展示。
完整链路是：输入 → 决策 → 工具 → 回写。

项目结构（方便对照代码）

本地跑起来：

设置里选工作区、填 API Key（默认可走 DeepSeek 的 OpenAI 兼容接口），就可以开始问了。

我学到了什么（前端视角）

Agent 的核心不是 Prompt 文案，而是「模型决策 + 你的运行时」。
Prompt 重要，但工程落点在工具定义、执行、多轮协议和 UI 可观测性。
Electron 三进程模型，和「前端 / BFF / 后端」心智可以迁移。
别把 Node 能力一股脑塞进渲染进程。
先做可演示的最小闭环，再谈 MCP / RAG / 自动更新。
一条讲得清的链路，比半成品功能清单更有说服力。

后续如果继续迭代，我会优先考虑：MCP 接入、流式输出、electron-builder 打包；RAG 等文档场景真的变大再上。

结语

AI 应用对前端不是「只会调 fetch」。
桌面场景里，你会更频繁地碰到进程边界、权限、工具协议和可观测性——这些本来就是工程问题，只是对象从「接口」变成了「模型 + 工具」。

如果你也是前端，想补一块 Electron / Agent 作品集，不妨从一个只读的本机代码助手开始：链路短、演示稳、故事好讲。

— 完 —

123 上链接（你需要自己准备一个deepseek apikey）！！！：

https://github.com/yuanfang19959/local-agent