Nexus：用Tauri+Rust打造本地桥，让ChatGPT网页版直接操作你的项目文件

1. 从额度焦虑说起：为什么我要自己造一个桥

Codex 额度用完的那一刻，我正改一个 Rust 项目的 trait 约束改到一半。屏幕上的报错还没消，命令行那边先弹出一行冷冰冰的提示，大意是这个周期的用量已经见底。那一瞬间的体验很割裂——网页版 ChatGPT 就在浏览器里开着，上下文还在，思路也还在，但本地那堆文件它碰不到，我只能手动复制粘贴，来回搬运代码片段。搬了十几分钟我就烦了，这种重复劳动不该由人来做。

于是就有了 Nexus 这个项目，当前版本 v1.20.0。一句话说清楚它是什么：一个跑在本地的桌面程序，把 ChatGPT 网页版和你本地的项目目录接起来，让网页端能直接读取、检索、修改你机器上的文件。它不是又一个套壳聊天客户端，核心价值在于“操作本地项目”这几个字——读文件、写文件、按目录检索、执行受控的命令，这些动作都发生在你自己的机器上，网页端只负责理解和决策。

这件事解决的是三类人的痛点。第一类是 Codex、各类命令行编程助手额度经常告急的开发者，网页版通常有独立的对话额度，把它利用起来等于多了一条通道。第二类是不习惯命令行、更愿意在网页界面里跟模型来回讨论的人，Nexus 让他们不用离开熟悉的交互方式就能动本地代码。第三类是想研究本地 AI Agent 怎么落地的人，Nexus 用 Tauri + Rust 写成，整个桥接层、工具调用协议、权限模型都是开源的，拿来做参考实现很合适。

我先把结论摆前面：Nexus 不是要替代 Codex 或者任何命令行工具，它是补位。命令行助手强在自动化和批处理，网页版强在交互和上下文讨论，Nexus 把后者的手伸到了本地文件系统。你不需要放弃任何一个，只需要在额度紧张或者想边聊边改的时候，多一个选择。下面我会把设计思路、核心实现、实操步骤和踩过的坑全部摊开讲，代码层面的东西尽量给到能直接抄的程度。

2. 整体架构与方案选型：为什么是 Tauri 加 Rust

2.1 桥接层的本质是一个本地 HTTP 服务

Nexus 的架构说穿了不复杂。本地跑一个轻量 HTTP 服务，监听回环地址上的某个端口，网页端通过一段注入脚本或者浏览器扩展跟这个服务通信。服务收到请求后，解析成具体的工具调用——读文件、写文件、列目录、搜索内容、执行白名单内的命令——在本地执行完，把结果回传。整个链路里，模型负责“想”，Nexus 负责“做”，两者之间用一套明确定义的 JSON 协议对话。

为什么用 HTTP 而不是别的？因为网页端的运行环境限制很多，它能稳定发起的跨进程通信方式基本就是网络请求。WebSocket 也行，但 HTTP 更简单，调试的时候 curl 一下就能验证服务是否正常，排查问题成本低。回环地址意味着流量不出本机，这一点对安全很关键，后面权限那节会细说。

2.2 选 Tauri 而不是 Electron 的真实理由

很多人第一反应是 Electron，生态成熟、上手快。我一开始也想过，但最后选了 Tauri，原因有三个，都是实际开发中撞出来的。

体积和内存。Electron 打出来的包动辄一百多兆，空载内存几百兆起步。Nexus 是个常驻后台的工具，用户可能开着它一整天，内存占用直接影响到它能不能“无感”地待在那儿。Tauri 用系统自带的 WebView 渲染前端，打包体积能压到十几兆，空载内存几十兆，这个差距在常驻场景下是决定性的。

Rust 后端带来的能力。Nexus 的核心是文件操作和进程管理，这些恰好是 Rust 的强项。文件读写、目录遍历、路径规范化、并发控制，Rust 的标准库和生态给得很足，而且性能稳定、内存安全。用 Node 做后端当然也能实现，但涉及大量文件 IO 和并发的时候，Rust 的确定性和性能优势很明显。

权限模型的粒度。Tauri 的命令系统天然支持细粒度的权限配置，哪些前端能调用哪些后端命令，可以在配置里精确控制。这对一个要操作本地文件的工具来说太重要了，我需要确保每一个能碰到文件系统的入口都是显式声明的，而不是靠运行时判断。

代价也有。Tauri 的生态比 Electron 小，遇到问题可搜的资料少，WebView 在不同系统上的行为差异需要额外测试。但权衡下来，对一个常驻的、以本地操作为核心的工具，Tauri 是更合适的选择。

2.3 Rust 在整个项目里承担了什么

Rust 不只是“后端语言”这么简单。Nexus 里几个关键模块都是 Rust 写的：文件系统抽象层负责路径解析和安全校验，工具调度器负责把模型发来的调用分发到具体实现，进程管理器负责拉起和监控受控命令，配置模块负责读写和校验配置文件。这些模块之间通过 Tauri 的命令通道和事件系统通信。

我特别想强调路径安全这块。模型发来的路径是不可信的，它可能拼出../../这种越界路径，也可能用符号链接绕开检查。Rust 里做路径规范化、检查最终解析结果是否落在允许的工作目录内，这套逻辑写起来清晰，而且编译器会逼着你处理各种边界情况。换成动态语言，这类安全检查很容易在某个分支上漏掉。

3. 核心机制拆解：工具调用协议与权限模型

3.1 工具调用协议长什么样

Nexus 和网页端之间的协议，本质是一组约定好的工具定义。每个工具有一个名字、一段描述、一组参数 schema，模型根据当前任务决定调哪个工具、传什么参数。这套设计借鉴了主流函数调用规范的思路，但做了简化，因为网页端能拿到的信息有限，协议太复杂反而容易出错。

目前核心工具大概这几类：读取文件内容、写入文件内容、在目录内搜索、列出目录结构、执行白名单命令。每个工具的返回都带明确的状态码和错误信息，模型拿到错误后能自己决定重试还是换策略。这里有个设计取舍——错误信息要给得足够具体，让模型能自我纠正，但又不能泄露敏感路径信息。我的做法是返回相对路径和错误类型，绝对路径只在本地日志里出现。

协议里还有一个容易被忽略的点：幂等性标记。写文件这类操作不是幂等的，重复执行会覆盖。我在协议里给每个调用带了唯一 ID，本地服务会记录最近处理过的 ID，重复请求直接返回缓存结果。这个机制在网页端网络抖动、请求重发的时候救过好几次场。

3.2 权限模型：默认拒绝，显式放行

这是整个项目我最在意的部分。一个能读写本地文件的工具，权限设计错了就是灾难。Nexus 的原则是默认拒绝，所有能力都要用户显式开启。

工作目录是第一个边界。用户必须手动指定一个或多个允许操作的根目录，Nexus 只在这个范围内活动。路径校验在 Rust 侧做，每次文件操作前都把目标路径规范化，然后检查它是否落在允许的根目录下。符号链接会被解析到真实路径再检查，防止用链接绕出去。

命令执行是第二个边界，也是风险最高的。我的做法是白名单加参数校验。用户可以在配置里声明允许执行的命令模板，比如只允许cargo build、cargo test这类，参数里不允许出现管道、重定向、命令替换这些 shell 特性。执行的时候不走 shell，直接以参数数组的形式拉起进程，从根上杜绝注入。

第三个边界是操作确认。对于写文件和执行命令这两类有副作用的操作，可以配置成需要用户在界面上点确认才执行。这个模式适合刚开始用、还不放心的时候，等信任建立了再关掉。我自己是写文件开着确认，读操作全放行，命令执行看项目——生产相关的仓库一律开确认。

提示：权限配置改完之后一定要重启本地服务，配置是在服务启动时加载的，热改不生效。这个坑我踩过，改了配置发现没反应，排查了半天才发现是没重启。

3.3 上下文怎么喂给模型

网页端拿不到你本地的文件树，所以 Nexus 需要主动把项目结构“介绍”给模型。我的做法是启动时扫描工作目录，生成一份精简的目录树，过滤掉node_modules、target、.git这些噪音目录，只保留源码和配置文件。这份目录树会作为初始上下文注入对话。

但目录树只是骨架，模型还需要知道具体文件的内容。这里不能一股脑全塞进去，上下文窗口扛不住。Nexus 的策略是按需读取——模型先看目录树，判断哪个文件相关，再调用读取工具拿内容。这个“先看结构再读内容”的两步走，比一次性灌入整个项目高效得多，也更接近人类开发者理解陌生代码库的方式。

搜索工具在这里很关键。模型可以传一个关键词或者正则，Nexus 在允许的目录里搜，返回匹配的文件和行号。这相当于给模型一个 grep 能力，让它能快速定位相关代码，而不是靠猜文件名。实测下来，有了搜索工具之后，模型定位问题的准确率明显提升。

4. 从零跑起来：安装、配置与首次连接

4.1 环境准备与安装

Nexus 是 Tauri 应用，安装方式取决于你的系统。Windows 用户拿到的是 msi 或 exe 安装包，双击按提示走就行。macOS 是 dmg，拖进 Applications。Linux 目前提供 AppImage 和 deb 两种格式，AppImage 给个执行权限就能跑，deb 用包管理器装。

如果你要自己从源码构建，需要先装 Rust 工具链和 Tauri 的构建依赖。Rust 用 rustup 装最省事，装完之后rustc --version和cargo --version都能正常输出就说明好了。Tauri 的依赖在不同系统上不一样，Linux 上需要装 webkit2gtk 相关的开发包，Windows 上需要 WebView2 运行时（Win10 较新版本和 Win11 自带），macOS 用系统自带的 WKWebView 不用额外装。

构建命令就一条cargo tauri build，第一次跑会编译一堆依赖，耐心等。编译产物在src-tauri/target/release下面。开发模式用cargo tauri dev，改前端代码热更新，改 Rust 代码会自动重编译，调试体验还不错。

注意：Windows 上如果构建报链接错误，大概率是缺少 MSVC 构建工具，装一下 Visual Studio Build Tools 里的 C++ 组件就好。这个报错信息不太直观，我第一次遇到的时候绕了弯路。

4.2 配置文件怎么写

Nexus 的配置是一个 TOML 文件，放在用户配置目录下。核心配置项分几块：服务监听端口、允许的工作目录列表、命令白名单、操作确认开关、日志级别。下面给一份我日常用的配置示例，你可以直接改。

[server] port = 17890 host = "127.0.0.1" [workspace] roots = [ "/home/user/projects/my-app", "/home/user/scratch" ] ignore = ["node_modules", "target", ".git", "dist", "build"] [commands] allow = [ { name = "cargo-build", cmd = "cargo", args = ["build"] }, { name = "cargo-test", cmd = "cargo", args = ["test"] }, { name = "cargo-check", cmd = "cargo", args = ["check"] } ] timeout_secs = 120 [confirm] write_file = true run_command = true [log] level = "info"

端口选 17890 是随手挑的，避开常见服务端口就行。工作目录的 roots 一定要写绝对路径，相对路径在服务启动时解析的基准目录不确定，容易出问题。ignore 列表按你的项目类型调整，前端项目记得把dist、.next这些加进去，不然目录树会很长。

命令白名单里的 args 是固定参数，模型只能选命令名，不能改参数。这个设计牺牲了灵活性换安全，如果你确实需要模型传参数，得单独开一个允许参数的命令类型，并且对参数做严格校验。我个人的建议是尽量别开，需要灵活执行的时候手动跑一下，别让模型碰。

4.3 首次连接与验证

配置写好、服务起来之后，怎么确认它真的在工作？我的验证流程分三步。

第一步，本地自测。用 curl 打一下服务的健康检查接口，返回正常就说明服务活着。这一步能排除掉端口占用、配置解析失败这类基础问题。

curl http://127.0.0.1:17890/health

第二步，工具调用测试。手动构造一个读取请求，看能不能拿到文件内容。这一步验证的是权限配置和路径解析是否正确。如果返回权限错误，检查工作目录配置；如果返回文件不存在，检查路径拼写。

第三步，网页端连接。在 ChatGPT 网页版里加载 Nexus 的桥接脚本（具体加载方式见下一节），然后让它读一个文件试试。这一步验证的是端到端链路。如果网页端没反应，先看浏览器控制台有没有报错，再看 Nexus 的日志有没有收到请求。请求到了本地但没返回，多半是工具执行出错；请求根本没到本地，那是桥接脚本的问题。

5. 网页端接入实操：让 ChatGPT 真正碰到你的文件

5.1 桥接脚本的加载方式

网页端要跟本地服务通信，中间需要一个桥。Nexus 提供两种方式：浏览器扩展和用户脚本。扩展方式更稳定，安装一次就行，但需要浏览器支持；用户脚本方式更灵活，配合脚本管理器用，适合不想装扩展的人。

扩展的安装很简单，从发布页下载 crx 或者解压后的目录，在浏览器的扩展管理页开启开发者模式，加载进去。装好之后扩展图标会亮，点开能看到本地服务的连接状态。绿色表示已连接，灰色表示没连上，红色表示连上了但握手失败——握手失败通常是版本不匹配，升级一下 Nexus 或者扩展就好。

用户脚本方式需要先装一个脚本管理器，然后把 Nexus 提供的脚本添加进去。脚本里配置本地服务的端口，跟 TOML 里保持一致。这种方式的好处是你可以直接看脚本源码，知道它到底发了什么请求，对安全敏感的人会更放心。

5.2 一次完整的对话流程

装好桥接之后，实际用起来是什么体验？我拿一个真实场景走一遍。

我在改一个 Rust 项目的错误处理，想把几个unwrap()换成更合理的错误传播。打开 ChatGPT 网页版，新开一个对话，先跟它说“我本地有个 Rust 项目，你通过 Nexus 看一下结构”。模型会调用列目录工具，拿到过滤后的目录树，然后告诉我它看到了哪些模块。

接着我说“看一下 src/error.rs 和 src/main.rs”。模型调用读取工具，两个文件的内容进入上下文。它分析完之后给出修改建议，我让它直接改。这时候 Nexus 弹出确认框，显示要写入的文件路径和改动内容，我扫一眼没问题，点确认。文件在本地被修改，模型收到成功回执，继续下一步。

整个过程里，我不需要复制任何代码，也不需要手动保存文件。模型在网页端，文件在本地，Nexus 在中间跑腿。这种体验一旦习惯了，再回去手动搬运会觉得很别扭。

5.3 上下文管理的实操技巧

用了一段时间之后，我总结出几个让 Nexus 用起来更顺的技巧。

对话开头的“项目介绍”很重要。第一次连接的时候，花一两句话告诉模型这个项目是干什么的、用什么技术栈、目录结构大概什么样。这段介绍会成为后续所有操作的背景，模型定位文件、理解代码意图都会更准。我一般会准备一段固定的项目描述，每次新对话开头粘一下。

控制单次读取的范围。模型有时候会贪心，一次读好几个大文件，把上下文撑满。我一般会明确告诉它“先看目录，需要哪个文件再读”，或者在配置里限制单次读取的文件大小上限。上下文是稀缺资源，省着用。

定期清理对话。网页版的对话越长，模型对早期内容的注意力越弱，而且响应也越慢。一个任务做完，开新对话，把项目描述重新粘一遍，比在一个超长对话里继续聊效率高。Nexus 这边是无状态的，每次请求独立处理，所以换对话对它没影响。

6. 常见问题与排查实录

6.1 连接类问题速查

这张表是我自己遇到问题后整理的，基本覆盖了九成以上的连接故障。排查顺序建议从下往上——先确认服务活着，再确认桥接加载了，最后看具体请求。从底层往上层查，比一上来就怀疑网页端要高效。

6.2 文件操作类问题

路径越界是最常见的报错。模型拼出来的路径有时候会带..，或者用了绝对路径但不在允许目录内。Nexus 会拒绝并返回错误，模型收到后一般会自己纠正。如果它反复在同一个路径上撞墙，说明它对项目结构的理解有偏差，这时候手动告诉它正确的路径前缀。

编码问题也遇到过。Windows 上有些文件是 GBK 编码，读出来是乱码。Nexus 默认按 UTF-8 读，遇到非 UTF-8 文件会报错。解决办法是在配置里指定编码探测策略，或者手动把文件转成 UTF-8。我现在的做法是项目统一 UTF-8，从源头避免这个问题。

大文件读取要小心。模型读一个几兆的日志文件，上下文直接爆掉。Nexus 有单文件大小限制，超过就拒绝，但模型可能不理解为什么被拒。我在工具描述里写清楚了大小限制，模型会自己改用搜索工具去定位关键行，而不是整个读。

6.3 命令执行类问题

命令白名单的配置最容易出错。args 数组里的每个元素都要精确匹配，多一个空格都算不匹配。我建议配置完之后手动测一遍，确认能跑通再交给模型用。

超时设置很关键。有些命令比如全量构建，跑几分钟很正常，超时设短了会被误杀。但设太长又会让模型干等。我的经验值是构建类命令给 120 秒，测试类给 300 秒，具体按项目规模调。超时之后 Nexus 会杀掉进程并返回超时错误，模型收到后一般会建议你手动跑。

命令的工作目录也要注意。Nexus 执行命令时的工作目录默认是工作根目录，如果你的命令需要在子目录里跑，要么在配置里指定 cwd，要么让模型先 cd（但 cd 本身不在白名单里，所以还是配置解决）。这个细节不注意的话，命令会报找不到文件。

7. 安全边界与使用建议

7.1 我给自己定的几条规矩

用这类工具，安全意识比功能本身更重要。我给自己定了三条规矩，分享出来供参考。

第一，敏感项目不开写权限。涉及密钥、凭证、生产配置的仓库，Nexus 只开读，写操作一律手动。模型再聪明也可能犯错，让它碰这些文件的风险不值得冒。

第二，命令白名单宁少勿多。只放真正需要的、参数固定的命令。任何涉及网络、涉及删除、涉及权限变更的命令，一律不进白名单。需要的时候手动跑，多花几秒钟，换的是安心。

第三，定期看日志。Nexus 的日志记录了每一次工具调用，包括时间、工具名、参数、结果。我每周会扫一眼，看看有没有异常的调用模式。这个习惯帮我发现过一次配置错误——某个目录意外地被加进了允许列表，日志里出现了不该出现的路径。

7.2 关于额度与成本的现实考量

回到最初的问题——Codex 额度用完。Nexus 的思路是把网页版的额度利用起来，但这不意味着网页版额度是无限的。它同样有周期限制，只是和命令行工具分开计算。所以 Nexus 解决的是“多一条通道”，不是“无限额度”。

实际用下来，网页版额度在交互式改代码的场景下消耗比命令行慢，因为你可以控制每次请求的范围，不会像自动化任务那样一次性烧掉大量 token。但如果你用它跑大批量重构，消耗一样快。我的建议是把它用在需要来回讨论、需要看上下文的任务上，批量机械操作还是交给命令行工具或者脚本。

7.3 这个项目后续可以怎么扩展

Nexus 目前的定位是桥，把网页端和本地接起来。往深了做，有几个方向我觉得有价值。

一是更细的权限粒度。现在的工作目录是整体放行，未来可以做到按文件类型、按目录层级配置权限，比如只允许改src下的文件，不允许碰config。

二是操作审计的可视化。日志现在是文本，做成时间线视图，每次改动前后 diff 一目了然，回滚也方便。

三是多模型适配。现在主要对接网页版，协议层其实可以抽象出来，接别的有函数调用能力的模型。这块我还在摸索，等稳定了再单独写。

8. 一些踩坑之后的真心话

做 Nexus 这段时间，最大的体会是：本地 AI Agent 的难点不在模型能力，在工程细节。模型能不能理解你的意图，很大程度上取决于你给它的工具好不好用、错误信息清不清晰、上下文组织得合不合理。同样一个模型，接一套设计良好的工具，和接一套粗糙的工具，表现差距非常大。

另一个体会是安全设计要前置。我一开始图快，权限校验写得比较粗，后来 review 的时候发现几个边界情况没覆盖，吓出一身冷汗。这类工具一旦出安全问题，后果比普通应用严重得多，因为它直接操作文件系统。所以宁可前期多花时间把权限模型做扎实，也不要事后打补丁。

最后说个实际的小技巧。如果你刚开始用，别一上来就开写权限。先用只读模式跑几天，看看模型读文件、搜代码的表现，建立信任之后再逐步放开。这个过程本身也是你在学习怎么跟它协作——什么样的指令它执行得准，什么样的任务它容易跑偏，这些经验只能自己试出来。工具是死的，用法是活的，找到适合自己工作流的用法，比工具本身有多少功能更重要。