企业官网建设流程全解析

AI 编程代理这半年突飞猛进，但真拿它干工程活的人基本都会遇到同一个尴尬：对话窗口一清空，它就把昨天帮你定的架构方案忘得干干净净；改到第三个文件时，它已经找不到关键的调用关系，开始就地发明接口；到了月底一看账单，几千块 token 费用根本说不清花在哪次重构里。

我做这套工具链的起因，就是自己团队在这三件事上反复吃瘪。当时市面上没有一套顺手的小工具能同时管住“记忆、代码结构、费用”这三块短板，于是我干脆自己动手。攒了三个月，开源了九个小仓库，代码量都不大，但全是能立刻落地的实用型组件，覆盖记忆持久化、代码地图索引、token 记账三个方向，全部 MIT 协议，拿过去就能直接改。

这篇文章我把整体思路、每个仓库的定位、部署方式和踩坑过程一次讲清楚，给打算自建 AI 编程代理基础设施的同学一个最小可行参考。这套东西不绑定任何特定模型或框架，适合所有基于大模型做编程辅助的团队和个人开发者。

1. 先交代背景：为什么我会攒出九个小项目

单纯用 AI 编程代理写“一次性脚本”没问题，但一旦进入真实工程环境，比如维护一个几十万行的老项目、多人协同开发、跨模块重构，立刻会冒出一堆大模型本身解决不了的问题。

我把团队的经历总结成三个最核心的痛点。

第一个是记忆断裂。AI 代理的能力边界就是它的上下文窗口，窗口之外发生过的决策、偏好、约束条件全部不记得。每次新开一轮对话，它都会礼貌地重新问你：“这个项目的构建命令是什么？”问题是这个问题你上周已经回答过八次了。项目里的历史决策尤其重要，比如“支付模块必须走独立审核流程”“测试环境不要用真实用户数据”这类约束，靠聊天记录根本没法沉淀。

第二个是代码定位效率低。让 AI 代理去改代码，它总得先“看懂”代码在哪。现在主流做法是给它接上检索增强生成，也就是把代码片段切成 chunk 塞进向量库。但向量检索有个天然缺陷：它能找到“词面上相似”的文件，却理解不了“模块 A 依赖模块 B，B 的接口变更会影响 A”这种拓扑关系。代理经常搜到一段函数的片段，却不知道这个函数被哪些地方调用、修改它会不会搞挂其他模块。

第三个是成本失控。大模型 API 的 token 计费不像水电表，它有输入单价、输出单价、缓存命中的折扣单价，还有工具调用附带的隐藏消耗。一个代理跑上一个工作日，肉眼根本看不出钱花在哪。我们曾出现过一次重构任务跑了两小时，烧掉的价值顶得上一天房租，回报却是一堆没用的代码草稿。这倒不是模型的锅，是我们当时完全缺少监控手段。

所以我才定下这套工具链的三个基本盘：持久化记忆、代码结构地图、token 记账审计。每一块都对应一个实际的工程日常。九个仓库不是一次设计出来的，而是边用边拆、边发现问题边拆出来的，最后拧成一条完整的链。

2. 记忆层：代理的“第二大脑”

2.1 记忆仓库能干什么

记忆模块在整套工具链里是设计得最重的一块。它其实不是一个模型，而是一套外挂的记忆服务：你让代理在关键时刻调用记忆接口写入信息，下次对话启动时再从记忆里拉回相关上下文。

我拆成了两个仓库，一个负责存储与检索的核心库，另一个是对外提供服务的 API 层。存储层默认使用普通的关系型嵌入式数据库起步，想上规模再切到独立的数据库服务。API 层提供 REST 接口和 Python、TypeScript 两种 SDK，代理侧只需要几行代码就能接入。

实际使用中最舒服的一点是，它不挑模型。我试过给不同的代理工具接这套记忆，统一走 HTTP 接口，模型这边完全无感。代理只知道自己多了个“记事本”，需要回忆什么的时候就主动翻一翻。

2.2 记忆数据结构的设计逻辑

记忆如果只是存对话原文，那和系统的日志没区别，检索时照样抓瞎。我在这套工具里把记忆条目标成了三段式结构：实体、属性、关系。

实体表示你要记住的对象，比如模块名、用户、命令；属性是实体的具体描述，比如“构建命令是 xxx”；关系描述实体之间的联系，比如“支付模块依赖于审计模块”。存进去的时候，客户端把一句话映射成这种结构化记录，查的时候才能通过关系链检索。

举个例子，代理之前了解到“批量导入接口在处理超过 1 万条数据时容易超时”，这条信息的实体是“批量导入接口”，属性是“性能阈值——1 万条”，关系是“超时可能影响——财务月结任务”。下次再讨论导入相关需求时，检索接口能顺着关系把这条记忆拉出来，而不是把整个聊天记录糊到上下文里。

这种设计的直接好处是上下文利用率高。一个大模型的上下文窗口就那么多 token，给它塞十条不相关的日志倒不如塞三条真正有关联的记忆。我的记忆仓库检索接口默认返回 top-k 条相关结果，每条还可以配置摘要模式，只返回核心字段而不返回全文。

2.3 冷热分层与去重：我不建议踩的坑

记忆存多了以后有一个非常现实的问题：旧的记忆和新的事实冲突了怎么办？比如项目初期说“构建产物放在 dist 目录”，后来 CI 调整成了“放在 build 目录”，老记忆不删会持续误导代理。

我一开始没处理这个问题，结果代理照着旧记忆报错报到崩溃。后来在记忆写入层加了版本号和时间戳，读取时对同一实体按时间排序，默认只返回最新版本。同时给显式删除留了接口，允许人工纠正。

另一个心得是冷热分层。我建了两张存储表，热表放最近 30 天活跃的记忆，冷表放历史归档。检索时先查热表，热表没命中再查冷表。这样日常查询的响应速度会稳很多。归档任务用一条带调度的脚本每天跑一次即可。

3. 代码地图：给代理画一张城区导航图

3.1 从“搜关键词”升级到“读拓扑”

很多 AI 编程辅助工具的代码检索停留在关键词匹配层面，这在单体小项目里勉强够用，但项目一大就捉襟见肘。agent 需要的是结构化的“地图”：这个目录下有哪些模块、每个模块对外暴露哪些函数、哪个函数被谁调用、改动它会波及哪些地方。

代码地图仓库的核心就是做这个事。它不直接参与对话，而是定期扫描代码仓库，用语法解析器读取抽象语法树，抽出项目里的符号表，再构建符号之间的引用关系。最终落成一个轻量的结构化文件，相当于给整个项目建了一份索引目录。

我选择用独立进程跑代码地图而不是作为库嵌在代理里，初衷很简单：索引构建是一件非常消耗资源的事情，如果嵌在代理的每次调用里，会拖慢响应速度，而独立进程可以后台构建，代理需要时再按需读取。

3.2 索引生成流程与支持语言

代码地图的执行逻辑分成三步。

第一步是解析。它用现成的语言解析工具读取源代码，提取出每个文件里的类名、函数名、全局变量名，以及这些符号所在的文件路径和行列号。

第二步是建立引用拓扑。扫完所有文件后，它会做一次全量匹配，找出“函数 A 在文件 B 中被调用”这类关系。这一步是最耗时的，因为要先全量解析一遍，再做交叉引用。我给扫描器加了并发支持，多核机器上速度基本能接受。

第三步是输出。生成的索引文件采用轻量文本格式，方便代理直接读取。结构很简——每个模块节点带上依赖列表和公开符号列表，再带一个简单的调用计数。代理拿到这份地图后，能够明确回答“我改了支付模块的校验函数，哪些模块会受影响”这类问题。

目前支持的主流语言包括几种动态语言和几种静态类型语言，覆盖了绝大多数后端项目的需求。其它小众语言暂时没进主索引，但也可以通过自定义解析器插件扩展。

3.3 增量更新与缓存策略

全量构建索引在超大仓库上可能要几分钟，所以增量更新是必需品。我采用的策略是监听文件系统事件，只重新解析发生变更的文件，再局部更新引用关系表。监听器本身很轻量，也不干扰日常开发。

做完这件事以后，我还加了缓存层。代理多次查询同一个符号，打印输出时不会被缓存。而不需要频繁重复构建。这一点在处理 monorepo 这类超大仓库时非常有效。

关于缓存，我给一个小建议：索引文件最好生成在工作区外的独立目录，否则很容易被误提交进版本控制。我第一次部署时因为缓存目录落在项目里，每个开发分支切换都会触发索引失效，后来把这个目录挪到全局临时目录下才算干净。

4. token 记账：每一分钱都花在明面上

4.1 钱到底花在哪

先算一笔粗糙的账：假设一个中等规模的重构任务，代理需要读取代码地图、检索记忆、调用模型补全好几轮，每轮输入可能几千 token、输出几百 token。如果对话轮次上百，总体消耗达几十万 token 并不稀奇。商用模型 API 按百万 token 计价，一天的代理使用量完全可能吃掉几十块到几百块的预算。

问题是每次调用的单价不是唯一决定因素。大批量请求如果打不到缓存，费用明显上升；输出越长，单价越贵；频繁请求不同模型也会让费用结构变得复杂。没有记账工具，你只能等月底账单出来吓一跳。

4.2 记账实现：拦截层、存储与报表

token 记账仓库提供了一层轻量的请求拦截代理。所有发往模型 API 的请求会经过这层，它解析响应头里的 usage 字段，把模型名、输入 token 数、输出 token 数、计费单价、时间戳全部写入本地存储。

存储结构非常简单，就是一张明细表加一张汇总表。明细表记录每一次请求，汇总表按小时、天、项目三个维度做聚合。查账的时候用命令行工具就能拉出日报、周报，还能导出 CSV 做二次加工。

关键的一点在于，我用了统一的成本换算函数，把不同模型的计费单位归一化，再乘上每次请求的实际 token 数，得到一条不可篡改的成本记录。

4.3 把账本升级成预算控制

光记账还不够，还得能控制。我在记账服务上加了一个轻量告警器，支持设置每日、每月预算上限，超过阈值就通过邮件或自定义接口通知。再往上走，可以配置“熔断模式”，预算耗尽时自动拒绝继续调用模型，防止代理失控烧钱。

我自己的团队用的是月预算 80% 告警、100% 熔断的配置。最开始浪费最严重的时段是深夜无人值守时的后台批处理任务，后来把这个时间段的单独预算调低，情况立刻好转。

如果接的是本地开源模型，费用维度天然不存在，但 token 记账的明细功能依然有意义。至少你能知道模型一次任务读了多少上下文，这能反推哪类任务在消耗大量输入 token——通常是可以优化的信号。

5. 九个仓库的分工与整体架构

5.1 仓库清单与职责说明

整套工具链按功能边界切成了九个仓库，彼此独立依赖。我把它们在项目里的分工理成一张表：

九个仓库之间通过配置文件和统一的环境变量对接。代理侧只需要访问记忆服务和代码地图索引服务，token 记账则是透明地挂在整个请求链路上，代理无感。

5.2 为什么拆成九份而不是一个大仓库

几乎每个第一次看到这个项目的人都问我：为什么不合成一个仓库维护？答案有三个。

第一是关注点隔离。记忆、代码地图、token 记账三个方向的改动频率差异很大，放在一起会让提交历史互相污染。拆开后，谁出问题直接单独发版，互不牵连。

第二是降门槛。使用者不一定要全上。如果你的项目只需要代码地图，那直接拉代码地图的仓库就行，不会被迫吞下整套工具的复杂度。这对我这类开源项目尤其重要——单个仓库的依赖越少，使用者越敢用。

第三是技术选型自由。我在这三个方向用了三种不同的语言栈，因为“最适合”的才是最好的。解析语法树适合用性能强的语言，写 HTTP 服务用生态成熟的语言更快，脚本类工具用简单的语言更好维护。如果硬合成一个仓库，你必须在语言上做一个痛苦的折中。

6. 从零部署一套完整工具链的实操记录

6.1 环境准备与依赖安装

整套工具链运行时最少需要一台有基础内存的服务器或开发机，操作系统不限主流的几种。三个核心服务分别是记忆服务、代码地图索引服务、token 记账服务，各自有独立的启动方式。

基础依赖是运行时环境。记忆仓库需要 Python 3.10 以上，代码地图解析器需要对应的编译工具链，索引服务需要 Go 1.22 以上。这些版本要求写在了各自的文档里，照着装就行。

安装方式我统一成了同一个模式：克隆仓库后跑一条初始化脚本，脚本会自动安装 Python 依赖、编译工具链、生成默认配置文件。这套方式保证不同环境下的安装行为一致，省掉了不少手工排错的时间。

6.2 三个核心服务的启动流程

先说记忆服务。默认配置下它使用嵌入式数据库作为存储后端，启动命令非常简单。首次启动会要求设置一个服务密钥，代理端后续访问需要带上这个密钥才能读写记忆。

代码地图索引服务稍微复杂一点。它需要指向一个待扫描的项目目录，然后第一次跑全量索引。我的建议是在业务低峰期执行首轮索引，因为大项目第一次扫描会比较耗时。生成完毕后守护进程会开始监听文件变更，后续就是增量模式了。

token 记账服务作为拦截层，需要配置目标模型 API 的地址和密钥。它启动后会开启一个本地端口，代理的请求地址指向这个端口，再由它转发给真实模型服务。这一步只要转发逻辑没问题，记账数据就会自动开始积累。

6.3 和现有 AI 编程代理工具的对接方式

对接方式分为两种场景。

如果你用的是自带插件机制的代理框架，那最简单的方式是写一段几十行的适配代码，在代理的会话开始、结束、工具调用点分别调用记忆和代码地图接口。代理框架的事件钩子足够覆盖这些时机。

如果你用的是命令行式的代理工具，那就直接改环境变量，把模型 API 地址指到 token 记账服务的地址上。而记忆和代码地图则通过系统提示词注入：启动时读一次记忆、拉一次主题相关的代码地图片段，放进提示词里。

两种方式我都验证过，稳定度都能满足日常开发使用。老项目中已经积累了不小的索引，代理的改动准确率提升比较明显，至少不再频繁“编造”不存在的接口或命令。

7. 真实环境里最容易踩的五个坑

7.1 记忆写入后查不到

这个现象很迷惑人。测试的时候写入再查询都正常，但项目跑起来以后，代理说“记住了”，下轮对话却还是什么都想不起来。

我排查后的原因基本都在数据归属命名空间上。记忆服务的写入与查询必须使用同一个命名空间，一旦代理在某个环节改了命名空间配置，新旧记录就会隔离。后来我在所有 SDK 里把命名空间作为必填参数，而不是用默认值，才算把问题治住。

7.2 代码地图索引过期导致代理“瞎改”

代理拿着过期的代码地图去改一个早已重构的模块，报错后它甚至会自信地把锅甩给地图：“这里没有这个函数。”这个问题在多人并行开发的分支上尤其明显。

换到监听文件事件后，索引仍然会有短暂延迟，这个正常。但不正常的是很多人忽略了“合并分支”这个动作——CI 服务器拉下来的代码是新的，监听器却盯着本地旧目录。解决办法很简单：在 CI 环境里加一步“强制同步索引”的脚本，每次构建后重新拉一次最新代码再跑增量更新。

7.3 token 计费出现明显偏差

记账模块和真实账单对不上，最常见原因是部分模型的 usage 字段不完整。有的只返回提示词的 token 数，不返回补全 token；还有的缓存命中时计费口径完全不同。

我在解析层加了一个计费口径选项，允许按模型单独指定：有的模型按“输入+输出总和”计费，有的按“缓存未命中的输入按原价、命中的按折扣价”计费。把口径配置对以后，偏差基本降到可以接受的范围。如果你发现数字突然离谱，第一反应应该是去查模型的计费文档变了没有。

7.4 多个服务端口冲突

九个小仓库都是独立服务，端口冲突几乎是必然。第一次联调时记忆服务和代码地图服务都默认监听同一个端口，代理端直接连错。

解决办法是工具链配置中心统一分配端口号，并在各服务启动时校验端口占用。部署的时候建议直接把整套服务的端口段规划写进配置模板，不要各仓库分散管理端口。

7.5 数据备份被忽略

记忆数据和代码地图索引都属于“丢了要哭”的数据。代码地图还好，重新构建一遍就是时间成本。但记忆数据一旦丢失，代理之前学到的项目约束全部归零，那种感觉像失忆。

我给记忆存储目录配了定时快照任务，每天压缩备份一次。恢复流程也写成了脚本，能在新机器上自动恢复数据。这块建议动手部署的人第一时间配好，千万别等出问题再补。

8. 一点心得与建议

这套工具链做到现在这个状态，最大的收获不是代码本身，而是让我想清楚了一件事：AI 编程代理要真正进入生产环境，光靠模型本身的智力是不够的，它还需要一套基础设施来补足记忆、导航和可控性。

如果你也想自建类似的一套东西，我的建议是从单点开始。不要一上来就九个仓库全铺开。先在现有代理上接一个简单的记忆服务，跑两周感受一下；再上代码地图，体验搜索效率的提升；最后再看 token 记账。确定每一步都有真实收益，再逐步加码。

开源这套项目之后，我自己在后续迭代里最看重的是模块的稳定性。工具链这种东西，宁可功能少一点，稳定性必须拉满，因为它是被别的系统依赖的底层设施，任何一个细微的接口变动都可能传导到上层代理的行为上。

如果你也在折腾 AI 编程代理的基础设施，欢迎直接把这几个仓库拿过去用。改坏了也没什么，MIT 协议就是希望你拿去折腾的。遇到具体问题，可以对照这篇里的经验先排查一遍，剩下的基本都能在各自的仓库文档里找到答案。