企业官网建设流程全解析

上个月我把这个项目彻底开源了，一个真实跑了快一年、月均处理200亿token的桌面AI Agent应用。从最初只想给公司内部做个能自动整理资料的助手，到后来决定自己从零全栈打磨一版产品级的东西，前后花了80天。这篇文章不写那种“手把手Hello World”式教程，就说说一个真实运行、有真实token消耗压力的Agent应用，在工程上到底要过哪些坎。适合正在做AI应用、想了解Agent工程化落地、或者准备把项目开源出去的开发者参考。

我先把结论放在前面：AI Agent桌面应用，真正的难点不在“模型多聪明”，而在工程侧的三件事——并发与token治理、任务可靠性与可恢复、以及状态可观测。模型能力是底座，但底座之上怎么搭骨架，决定这个产品是玩具还是工具。

1. 为什么做桌面端AI Agent：聊天框式Chatbot解决不了的问题

1.1 闲聊式Chatbot与干活式Agent的差距

如果只是把AI Agent当成一个聊天框，那确实没必要做桌面端；但要把Agent当“能帮你处理本地文件、执行任务、常驻后台”的工具，Web聊天框的天花板就很明显。浏览器标签页一关，会话状态没了；Agent想读本地文件时，Web应用要么走繁琐的上传下载，要么依赖浏览器沙箱的权限模型，根本没法直接操作操作系统。后台任务更是无从谈起，你不能让一个网页挂在后台十几分钟不停调用工具、执行多步骤流程，然后在你回来时看到一个完整结果。

我最初在公司做的内部助手就是一个网页应用，功能不差，但大家用着用着就变成“提问—复制答案”的模式，没有人敢让它干正事——因为网页里的Agent天生够不着文件系统、够不着本地命令、够不着那些需要常驻监听的任务。真正让我下决心自己做桌面端的，是一次内部调研：用户想要的不是“再聪明一点的对话机器人”，而是“把查资料、读文件、生成报告、归类存档这一整条链路跑通的助手”，这必须落在操作系统层面。

1.2 产品边界：不做全能助手，只做三类核心场景

为了避免项目变成“什么都会一点但什么都不稳定”的大杂烩，我把产品边界收敛成三个核心场景。

• 资料整理Agent：给定一个主题，自动检索、抓取、摘要、格式化导出到指定目录。这看起来简单，但从写搜索query到去重、引用来源、生成目录结构，中间有大量工具编排。
• 本地研发助手：能读取仓库文件、执行git status、跑静态检查、运行白名单内的测试命令，把结果反馈给模型继续推理。这个场景对工具权限和沙箱隔离要求极高。
• 个人知识库问答：读本地Markdown、PDF、代码注释，做RAG检索和上下文相关的追问。

三个场景共用一套底层“工具注册与权限系统”。核心原则是：Agent只能操作白名单里的工具，所有工具调用都留痕，涉及删除、修改系统设置、执行任意命令等危险操作，必须弹窗人工确认。这条原则从第一天写代码就定了，后面所有可靠性设计都围绕它展开。

1.3 为什么以个人/小团队形态做

这类产品天然不适合一开始就做成公有云SaaS。桌面端的好处是本地可跑、隐私可控，不用把太多数据搬上云端，也不用从第一天就扛海量多租户并发。但“月均200亿token”这个量级意味着它背后必然有用户、有服务端、有真实流量。所以我的架构分了两层：本地Agent进程负责交互与执行，云端轻量网关负责模型路由、用量计费、密钥托管和审计。这种“客户端重、网关轻”的形态，兼顾了桌面应用的隐私优势和规模化运营的治理需求。

2. 技术选型：Tauri、FastAPI、LangGraph是怎么组合到一起的

2.1 桌面壳之争：为什么不选Electron

很多朋友看到“桌面应用”第一反应就是Electron，省事、生态成熟、前端随便写。省事是真的，但代价是体积和内存。Electron打包随便就200MB往上，内存常驻500MB起步，而AI Agent是要开机自启、托盘常驻、整天挂在后台的。我最后选了Tauri 2.x，前端还是React+TypeScript，但壳换成Rust，安装包十几MB级别，内存占用连Electron的零头都不到，托盘、全局快捷键、文件系统权限这些能力都控得更细。

代价也很现实：Tauri的插件生态远不如Electron成熟。遇到官网文档没覆盖的系统级API，你得亲自写Rust代码，这对纯前端的同学不太友好。但AI Agent桌面应用最需要的本地能力，无非就是文件读写、进程spawn、剪贴板、通知、全局热键，这些Tauri都有现成能力。如果选型标准是“长期占用资源少”且“需要的系统能力固定”，Tauri是更适合的选项。

2.2 本地Agent服务：为什么单独起一个Python后端

我这里做了个看似绕路的决定：桌面壳只负责UI，真正的“大脑”不是写在前端，而是一个跑在本地的Python服务，基于FastAPI。原因有三条。

第一，LLM的生态基本在Python这边。LangChain/LangGraph、各类Embedding模型、向量库、重试与退避库，Python都有现成的；如果全用TypeScript重写，工程量翻倍还容易踩坑。第二，桌面壳和Agent服务之间用HTTP/WebSocket/SSE通信，能把“模型调用”“工具执行”“状态持久化”这些重活从前端隔离出来。前端哪怕崩溃了，Agent任务还在本地服务里跑，恢复UI后状态还在。第三，模型密钥不能放前端。所有LLM调用都通过本地服务转发，再由本地服务向云端网关发起请求，用户不会直接接触任何Provider的ApiKey，密钥泄露面大大缩小。

本地进程我直接用uvicorn单实例运行，只监听127.0.0.1，不暴露到局域网或公网。云端网关则是另一套FastAPI服务，部署在容器里，负责负载均衡、密钥路由、重试和计量。

2.3 Agent编排框架：从自研循环到LangGraph

刚开始我其实试过自己写Agent循环：while True: 调模型 -> 拿tool call -> 执行工具 -> 塞回上下文 -> 再调模型。单轮Demo没问题，但一遇到多分支、中断恢复、异步长任务，代码很快就变成一坨if else嵌套，根本不敢改。后来切到LangGraph，核心思想是状态图：每个节点是一个明确的计算步骤，边决定下一步怎么走，LangGraph自带的checkpointer能把每一步的完整状态存进SQLite，断点续跑天然支持。

这个选择我至今觉得值。LangGraph的节点、条件边和checkpointer设计，和“任务会中断、需要恢复”的桌面Agent场景特别匹配。不过也有坑——LangGraph版本更新很快，接口说变就变，所以项目里必须锁死版本。我们在requirements.txt里固定了小版本号，并且CI里加了依赖检查，避免某天同学拉代码发现环境跑不起来。

2.4 数据落盘设计：SQLite为主，用量表是核心

本地数据我全部用SQLite，开启WAL模式，读写并发要好很多。核心表只有四张：sessions（会话）、messages（消息）、tool_calls（工具调用记录）、token_usage（token用量）。这里最关键的是一开始就把token_usage表设计好：字段包括模型名、prompt token、completion token、耗时、重试次数、关联的AgentRun ID、工具调用序列。每轮Agent运行结束，我会把这次任务的全部计量信息写进去。

这张表是整个项目后来能复盘“200亿token到底花在哪”的基础。没有它，成本优化就是瞎猜。

3. 月均200亿token的工程账：并发、成本与token治理

3.1 把200亿拆开算一算

很多同学看到“月均200亿token”觉得高不可攀，其实拆开算一算就没那么吓人。假设一次LLM调用平均输入加输出约1万token，那么一个月200亿token大约是200万次LLM调用，平均每天约6.6万次，折算成每秒不到1次。但Agent任务不是单次调用，一个任务内部可能调模型5到8次，而且每次模型响应都是流式输出，持续20到60秒。所以真实的活跃连接数很容易到几百，网关和客户端的连接管理才是压力点。

这种负载对普通服务器是扛得住的，真正的麻烦不是“QPS高”，而是“尖峰明显”：工作日早上大家集中开工，瞬时请求可能是平峰的10倍。如果按峰值去预留资源，平时就会浪费一大半。我的解法是：网关层做限流和排队，把尖峰压平；客户端做本地重试和退避，削掉一部分瞬时冲击。

3.2 并发链路：连接池、单飞刷新与重试退避

LLM Provider的API Key是最容易踩雷的地方。客户端不可能拿着每个用户的Key直接请求模型厂商，真要这么做，密钥泄露、跨用户计量、余额管理会全面失控。所以我做了一层统一网关：用户只发业务请求，网关负责负载均衡、密钥路由、重试和计量。

网关里的重试也不是无脑重试。对于429限流或5xx错误，用指数退避，最多重试3次；对于流式响应中途断连，不总是重新发起完整请求，而是看Provider是否支持续传，不支持就靠幂等ID识别重复请求，避免用户因为一次网络抖动看到重复执行。JWT这边，用户登录后拿到access和refresh两个token：access有效期设为15到30分钟，refresh有效期7到30天。所有请求带access，发现401后暂停业务请求，同一个客户端里只允许一个刷新请求在途，完成后重放队列里的请求。

这里有个很隐蔽的坑：多个请求同时401时，如果各自独立刷新refresh token，refresh token本身可能因为并发刷新被作废，导致用户明明没退出却被强制重新登录。所以必须做single-flight，整个客户端同一时刻只放一个刷新请求。

let refreshing: Promise<string> | null = null; async function getValidToken() { if (Date.now() < accessTokenExpiresAt) { return accessToken; } if (!refreshing) { refreshing = refreshAccessToken().then((newToken) => { accessToken = newToken; return newToken; }).finally(() => { refreshing = null; }); } return refreshing; }

这段逻辑看着简单，但解决了我们线上80%的“偶发掉登录”问题。

3.3 token治理：省token比换更便宜的模型更重要

月均200亿token，如果放任Agent自由发挥，同样的任务量可能多烧30%到50%的token。我做了四层治理，每一层都能在token_usage表里看到具体收益。

第一层是模型分诊。不是所有任务都上最强模型。先跑一个轻量意图分类器，任务分为“简单查询”“工具调用”“长文档分析”“代码生成”，再决定路由到哪个模型。简单查询直接走便宜的小模型，这里能省掉的token占总量的很大比例。

第二层是上下文压缩。长对话里历史消息会指数级膨胀，系统提示词和旧消息越来越多。我在每轮Agent运行结束后判断上下文是否超过阈值（比如12000 token），超过就把早期消息替换成摘要，并在系统提示词里注明“这是早期对话的摘要”。实测效果稳定，对后续任务的影响很小。

第三层是工具结果裁剪。工具返回的文件内容可能几万token，但模型真正需要分析的可能只是前几十行或匹配片段。每个工具都定义固定返回格式，默认截断到一定长度，模型需要更多细节再通过参数控制拉取。

第四层是语义缓存。相同或相似的用户请求直接返回缓存结果。尤其RAG场景下，多个用户查同一个知识库文档，缓存命中率能达到30%左右。

四层跑通之后，我对比治理前后的数据，单任务token消耗中位数下降了40%左右。这个数字说明，工程手段对AI应用的成本影响，一点都不比换更便宜的模型小。

3.4 长请求的稳定性：SSE、心跳与成本仪表盘

模型调用都是流式输出，SSE是标准做法。但SSE长连接在桌面UI、本地Agent服务、云端网关之间形成一条链路，任何一环断开都要有兜底。我在本地服务和UI之间专门做了一套事件推送机制：Agent内部每个节点开始、工具调用开始、工具返回、token增量、错误、进度百分比都作为事件推给前端。UI层面即使是在多个窗口里也要同步状态，所以还加了一层事件广播。

成本仪表盘则按模型、按天、按项目聚合token和费用，同时把“单任务token预算上限”写进去。任务消耗一旦超过预算，自动暂停并向用户询问是否继续。这个设计在Agent跑偏的时候救了我很多次——模型突然在工具循环里“上头”，预算闸门直接把它掐住，避免了无意义的token浪费。

4. 产品级Agent的可靠性：工具调用、长任务恢复与防失控

4.1 工具调用：把模型从“会选工具”变成“规范选工具”

工具调用是Agent的命门。模型输出tool call是自由文本，经常出现JSON不完整、参数类型错误、反复调用同一个工具这类问题。我的处理分三步。

第一步，工具定义必须用JSON Schema严格声明，参数给示例值，描述写清楚触发条件。比如文件搜索工具，descriptions里直接写明“当用户提到查找文档、文件、目录时使用”，参数给一个示例文件名。描述越具体，模型误选工具的概率越低。

第二步，容错解析。模型返回的文本先尝试json.loads，失败就做修复：提取花括号范围、补齐引号、截掉多余尾缀。修复失败就把错误信息作为工具结果回传给模型，让模型重新生成调用。实测下来，绝大多数坏JSON都能被第一步和第二步兜住。

第三步，工具执行结果按“成功/失败/超时”分等级回传。失败信息里带结构化错误码和修正提示。比如“文件不存在”就给模型提示可以尝试搜索附近文件名。模型看到修复提示后，第二次调用通常能自己修正参数。

同时，工具调用链必须有上限。我默认最多10步，达到上限立即停止并向用户解释当前执行到哪一步。这个上限就是防止模型在工具循环里自问自答、白白烧token的保险丝。

4.2 长任务恢复：应用崩溃后怎么续上

桌面AI应用最尴尬的场景是：任务跑了一半，电脑重启了。这也是我坚持用LangGraph checkpointer的原因。每个节点执行完，整个state序列化存进SQLite；应用开机后扫描未完成任务列表，用户可以选择继续。继续时不是从头跑，而是从崩溃的那个节点重新执行。

但这有一个前提：节点的副作用要做幂等设计。比如文件写入前判断目标文件是否已存在；执行命令时先查有没有相同PID的残留进程；调用Webhook前生成幂等ID，服务端收到相同ID直接返回已处理结果。没有幂等设计，“断点续跑”只是把重复操作再跑一遍，甚至可能产生更严重的错误。

实现上其实很直接：任务表加一个status字段，取值为pending/running/paused/failed/done，checkpointer保存每个节点的输入输出。恢复时构造新的LangGraph调用，把之前的state原样传进去。

4.3 防失控的三道闸门

第一道闸门是预算闸门。每个任务在创建时就带上token预算和费用预算，超限自动暂停。第二道闸门是危险操作闸门。删除文件、执行shell命令、修改系统设置这类工具单独管理，调用时必须弹人工确认，确认有超时时间，60秒不点默认拒绝。第三道闸门是审计日志。所有工具调用的时间、参数、结果、消耗token全部留痕，用户可以回看Agent每一步做了什么。

三个闸门看起来简单，但真实使用中非常关键。桌面端Agent因为能碰本地文件系统，风险高于纯云端Agent，没有闸门我根本不敢让它自动跑一个多小时。

5. 80天里值得写下来的几次重构

5.1 从“单轮对话”到“会话+任务”双模型

第一次重做是在第30天左右。最初产品就是一个聊天框：用户提问，Agent回答。但很快发现，真正的任务形态是“查资料、生成报告、发送到指定目录”，聊天框根本不适合承载多阶段流程。于是我把数据模型拆成两层。

会话（Session）负责上下文连续性、标题、历史摘要，用户看到的是长期对话。任务（AgentRun）负责一次多步骤执行的完整状态机，包含当前节点、已调用工具清单、token消耗、执行日志。UI也从聊天框变成了“会话+任务时间线”，每个工具调用都是时间线上的一个卡片。

这次重构让整个系统的可调试性上了一个台阶。用户在时间线里能清楚看到Agent每一步在干什么，token烧在哪一个工具，哪一个节点开始跑偏。没有这个拆分，后面的预算上限和断点续跑都无从谈起。

5.2 登录态与token续签：一个容易翻车但必须做对的细节

桌面应用也有登录态问题。最开始我图省事，把access token的有效期设为7天。结果7天一到，所有用户同时掉线，日志里全是401。后来改成15分钟access加30天refresh，但刚开始还是翻车——并发刷新导致refresh token被循环失效，用户明明没退出却被强制重新登录。解决方式就是前面的single-flight代码。

还有一种场景是登录时外部身份服务返回“token exchange failed”或403。这通常不是我们服务自身的问题，而是身份提供商拒绝了交换。需要区别对待：密钥过期、网络不通、权限不足，三种情况要给出不同的前端提示，不能全部当成“再点一次就行”，否则用户会看到无限转圈，然后认定产品有问题。

5.3 从轮询到SSE：进度推送与实时token计数

早期任务状态靠前端轮询，每2秒拉一次接口。任务一长，轮询既浪费资源又延迟高。后来我改造出统一的SSE推送通道，所有事件——节点开始、工具调用开始/结束、token增量、错误、进度百分比——都从后端推给前端。token计数也从“任务结束一次性上报”变成“流式输出每完成一小段就累计一次”。

这个细节对用户体验非常关键。用户能看到当前任务已经烧了多少token、走到第几步，而不是面对一个干等的神秘进程。尤其是长任务，如果没有实时进度，用户很快会失去耐心并判定任务失败。

5.4 可观测性：没有trace，谈不上优化

运行一段时间后我发现，如果不知道某次任务慢在哪、贵在哪，一切优化都是拍脑袋。于是我给Agent执行层加了一套OpenTelemetry埋点，每个LLM调用都记录：模型名、prompt token数、completion token数、延迟、重试次数、关联任务ID。本地日志按天轮转，保留15天。

后面做的所有成本优化，依据都来自这张trace表。模型分诊的效果、上下文压缩的收益、重试导致的额外消耗，全部能量化。对AI应用来说，可观测性不是锦上添花，而是基础设施。

6. 开源这步棋：从仓库空置到有人提PR

6.1 开源不只是把代码push上去

代码能跑通不等于能开源。我花了大约一周做开源准备，包括：选License（用MIT，让团队和大厂都敢放心集成）、写README（从“这是什么”讲起，附架构说明、快速启动步骤、FAQ）、补贡献指南（PR前先开issue，明确commit message规范）、配置Issue模板、搭自动化CI（lint、test、build、release）。这些看起来占用时间的工作，决定了用户能不能在3分钟内跑起来，也决定了社区的开发者愿不愿意深入看代码。

真正的教训是：开源项目的价值，一半在代码，一半在“让别人看懂并愿意参与”的工程包装。README写不清楚，跑不起来，再好的代码也会石沉大海。

6.2 开源后收到的反馈与取舍

项目发布后，收到最多的反馈有三类：一是“希望能支持本地模型”，二是“Windows下某一步环境变量没配好”，三是“能不能把Agent能力做成API供外部调用”。我没有全接。开源社群最大的风险是需求蔓延，什么都想做就什么都做不深。

我给自己定的原则：只做与桌面Agent核心闭环相关的事，其它需求收集进discussion，攒到一定量再评估。开源不是KPI，口碑比功能数量重要得多。

6.3 开源后的真实收益

开源带来的直接收益是问题反馈和场景洞察远超闭源阶段。用户会在issue里贴出我没遇到过的操作系统兼容问题、奇怪的工具调用失败、以及在自己行业里怎么用这个Agent。这些反馈变成下一轮迭代的输入。对我个人而言，开源也逼着我把代码写规范——丑代码会被陌生人看见，这个心理压力比任何code review都有效。

最后分享一个我在实际开发里最满意的小工具：桌面端调试模式。因为Agent服务是独立进程，我在本地服务里加了一个debug面板，前端可以直接查看当前任务的状态机、工具调用链、token消耗，还能手动注入一条假工具结果，测试Agent的下一步分叉。这个能力在断点续跑测试时帮了大忙——我能模拟“文件写入一半崩溃”再恢复，而不需要真的去拔电源。

如果你也要做一个产品级的AI Agent应用，我会反复建议把三件事当成核心原则：可观察、可恢复、可干预。模型能力决定上限，而这三点决定产品能不能真的被放心使用。