企业官网建设流程全解析

我接手过很多 AI 编码辅助类项目，自己也维护过几套内部工具链，所以看到“开源了一套 AI 编程代理工具链：从记忆、代码地图到 token 记账（9 个仓库全 MIT）”这个标题时，第一反应是“终于有人把这几件事放在一起做了”。

大多数个人或小团队做 AI 编程代理，通常只解决一个点：有的只做代码检索，有的只管上下文打包，有的干脆就是接一个模型 API 完事。可一旦你真拿它去跑真实项目，很快就会发现三个绕不开的问题：Agent 记不住跨会话的项目背景，代码一多上下文窗口塞不下，以及模型调用费和失控的 token 用量根本说不清楚。这套工具链把记忆、代码地图、token 记账三大块拆成 9 个独立仓库，全部用 MIT 协议放出来，本质上就是把“能跑的 Demo”做成了“能维护的基础设施”。

这篇文章我会从设计思路开始，逐个拆解这三块核心能力分别解决什么问题、内部是怎么实现的、组装到一起后又是什么效果，最后会整理一些我实际跑这套链路时踩过的坑。如果你也在自己搭 AI 编码助手、Agent 工作流，或者单纯对这套工具链的架构感兴趣，可以参考着去改、去用。

1. 项目全景与定位

1.1 为什么 AI 编程代理需要“记忆层”

很多人对“记忆”的理解停留在“保存聊天记录”上，其实差的远。LLM 本身是无状态的，每次新开一个会话，模型对你的项目一无所知。你上一轮告诉它“我们后端用 Python 3.11，变量命名统一走 snake_case”，下一次它照样会给你生成驼峰命名的示例代码。

聊天历史只是记忆里最表层的东西。真正有用的记忆至少包含三类：

• 项目级事实：技术栈、目录约定、第三方库版本、部署方式。
• 用户偏好：代码风格、测试习惯、提交信息格式、不想动的模块。
• 历史决策：之前为什么没用某个方案、哪块代码被反复重构过、哪些坑是已知的。

没有这一层，Agent 每次开工都是“失忆状态”，你不得不重复描述背景，既浪费 token 又容易前后矛盾。有了记忆层，Agent 至少能像一个刚入职但认真读了项目文档的同事，而不是一个每次都把自己当第一天上班的新人。

1.2 代码地图解决“上下文窗口装不下代码库”的难题

上下文窗口这两年一直在涨，但真实项目的代码量涨得更快。一个中等规模的微服务仓库，光源码就可能有几十万到上百万 token，更别提依赖、配置、测试、脚本。你不可能把这些全部塞进 prompt。

所以需要代码地图。它不是简单地把代码塞进向量数据库做相似度搜索，而是把仓库结构解析成符号、文件、函数、类、调用关系组成的图谱，让 Agent 能够按名字定位、按调用链展开、按语义检索。Agent 不需要读完整仓库，只需要拿到跟当前任务相关的那一小片代码，以及它们之间的依赖关系。

1.3 token 记账：成本失控前必须做的事

只要 Agent 进化到“多轮工具调用”阶段，token 消耗就会变得非常难看。一次任务可能包含几十次模型调用，每次调用都会带上系统提示词、工具结果、历史上下文，实际 token 数往往是“最终回答”的好几倍。

没有记账，你根本不知道一个功能迭代花了多少钱、是哪个任务烧掉的、是哪次重试导致的超支。标题里把 token 记账和记忆、代码地图并列，说明作者很清楚：记忆让 Agent 变强，代码地图让 Agent 变准，记账让 Agent 变可控。这三件事合在一起，才是一个能长期跑在生产环境的 AI 编程代理。

2. 9 个仓库的分层逻辑与设计哲学

2.1 为什么拆 9 个而不是 1 个单体

这年头开源项目很容易走两个极端：要么一个超级仓库塞所有代码，要么拆成几十个微仓库互相 dependency hell。拆 9 个仓库，我认为是这条工具链最值得琢磨的地方。

从目录结构上看，它是典型的“领域垂直切分”：

• 基础层：公共 SDK、Schema 定义，另外几个领域模块依赖它们。
• 记忆域：负责记忆的存取、检索和淘汰策略。
• 代码地图域：负责解析代码、构建图谱、提供查询接口。
• 记账域：负责 token 统计、存储和报表。

每拆一个仓库，都要付出跨仓库联调、发版同步、Issue 分散的代价。但如果边界切得干净，收益更大：使用者不用为了一个功能把整套工具链全部引进来，可以按需引入；每个仓库可以独立发版、独立测试；贡献者可以只改自己熟悉的那一块，不用理解全局。

2.2 9 个仓库的典型职责划分

这 9 个仓库大致可以分为四组，每组内部职责单一，组间通过明确的数据结构通信：

这 9 个仓库合在一起就是一套完整工具链，拆开用也成立。你如果只想解决上下文浪费问题，单独用 code-index 和 code-query 就够了；如果只是想搞清楚模型调用成本，只上 token-collect 和 token-report 也能跑。

2.3 为什么全部选 MIT 许可

单独一个仓库 MIT 不稀奇，但 9 个仓库全部统一成 MIT，释放的信号很明确：作者是认真想让别人拿去用的。

MIT 对商业用户最友好。公司接入开源项目时，法务通常最怕 AGPL 这类有传染性条款的协议，而 MIT 意味着你可以把它集成进闭源商业产品，只要保留版权声明，基本没有合规负担。对个人开发者来说，MIT 也意味着可以放心地拆出来改、嵌入自己的项目，甚至商用。

另外，统一协议降低了社区参与门槛。贡献者不用记住“哪些仓库宽松、哪些仓库严格”，哪都能改、哪都能用，心智负担小很多。如果你在运营开源项目，这个细节其实很重要。

3. 记忆子系统：让 Agent 记住上一个界面

3.1 记忆系统要解决的具体场景

假设我在某个项目里已经和 Agent 连续协作了两周，期间告诉过它“订单模块的金额字段统一用 Decimal，不要把分转成元”“我们不用 ORM，直接写 SQL”“数据库迁移脚本放在 db/migrations 下”。

如果没有记忆，第二周开新会话，这些约定全部失效。Agent 可能又建议你引入某个 ORM，或者生成一个 float 类型金额字段。这种反复解释和来回纠错，浪费的 token 可能比你想象的多得多——而且很容易消磨使用耐心。

有记忆之后，Agent 在新会话启动时会先拉取与该任务相关的记忆条目，把项目约定直接拼进系统提示词里，行为表现会立刻像“记得这事”。这个体验差异是决定性的。

3.2 记忆接口设计与存储抽象

这套工具链里的记忆域不是简单的一个“save_text”函数，而是完整抽象了记忆的写入、读取、检索、淘汰四个环节。

核心接口可以想象成一个 MemoryProvider：

class MemoryProvider: def save(self, entry: MemoryEntry) -> str: ... def get(self, entry_id: str) -> MemoryEntry | None: ... def search(self, query: str, top_k: int = 10) -> list[MemoryEntry]: ... def forget(self, entry_id: str) -> None: ...

MemoryEntry 是 schema 仓库里定义好的统一结构，大致包含这些字段：

• entry_id：唯一标识。
• content：记忆正文，可以是一段摘要、一条事实或一个偏好。
• scope：作用域，比如项目级、模块级、会话级。
• importance：重要度打分。
• created_at / updated_at：时间戳。
• source：记忆来源，比如用户手动写入、系统自动总结。
• token_size：这条记忆转成 token 后估计的长度，方便做预算。

存储上默认实现是 JSONL 文件，简单、可靠、可读性强，重启不丢。如果你需要语义检索，可以换到向量库实现；如果多机部署，就换成数据库实现。接口不变，底层随便换。

3.3 关键设计：自动摘要、重要度分级与过期淘汰

如果只存不清理，记忆库很快会变成垃圾场。系统里设计了三个机制：

• 自动摘要：当对话轮次达到某个阈值，或者累计 token 超过阈值时，抽取此前的关键事实、用户偏好和未完成事项生成摘要，替换掉原始对话历史。
• 重要度打分：被用户在后续会话中引用越多的记忆条目，重要度越高；用户手动“star”过的记忆最高。每次新会话读取记忆时，按重要度从高到低排序，低优先级的记忆在上下文紧张时优先被截断。
• 过期淘汰：带 TTL 的临时记忆到期自动清理，长期记忆则定期做冲突检测和合并。比如“前端用 Vue”和“前端切到 React”这种矛盾，后来的覆盖先前的，而不是两条共存。

这套机制保证了记忆系统不会无限膨胀，也让每次组装 prompt 时的记忆检索开销是可控的。

3.4 实操笔记：记忆持久化的坑

这套工具链我在本地模拟几个项目试跑时，踩过一些记忆相关的坑：

第一，记忆条目的 Schema 一定要版本化。刚开始字段很随意，等加了 scope 和 source 之后，旧数据就没法兼容了。早早在 schema 仓库里加 version 字段，后面会省很多事。

第二，不要把敏感信息随便写进记忆。记忆是自动抽取的，有时候会把 API Key、内部地址、个人账号都抓进去。如果工具链要做多用户共享，必须加一道过滤层，用正则或关键词表把明显敏感的内容拦掉。

第三，读回的记忆要给上下文留出“垃圾桶”。如果一口气把 50 条记忆全部灌进 prompt，上下文立刻被占满。实际使用时要设一个预算，比如本轮任务最多使用 2000 token 的记忆，超出后按重要度截断。

4. 代码地图：把仓库变成可检索的关系图

4.1 代码地图不是 BFS 搜索

常规代码搜索工具是按文件名或字符串模糊匹配的，但你问“这个查询入口改动会影响哪些调用方”，字符串搜索解决不了。代码地图要建的是一张图：函数 A 调用了函数 B，类 C 继承了基类 D，模块 E 导入了模块 F，HTTP 接口 G 对应的处理函数是 H。

Agent 拿着这张图，才能回答“改动影响面”“调用链分析”“这个符号在哪里定义”这类真正有价值的问题。

4.2 索引流水线：解析-构建-存储-查询

代码地图的索引流水线大致分四步：

第一步解析。用 tree-sitter 或类似的语法解析器从源码里抽取符号，这一步不依赖运行时环境，不需要装依赖、不需要编译，速度快得多。缺点是拿不到类型推导和动态调用信息，但对大多数编程任务已经够用。

第二步建图。把文件、函数、类、变量构建成带类型的节点，把调用、继承、引用构建成带类型的边，存储成图数据结构。

第三步入库。默认实现用 SQLite 存储邻接表和节点属性，单机查询性能足够好；仓库特别大时，再考虑换成专门的图数据库。

第四步查询。提供三类主要接口：

• 按名字查符号：get_symbol_info("get_user_by_id")
• 查调用链：get_call_chain("create_order", depth=3)
• 前缀模糊搜：fuzzy_search_symbol("order_")

查询接口返回的是结构化 JSON，Agent 可以直接解析使用，不需要自己读大段代码。

4.3 与 Agent 的配合方式

代码地图单独拿给人类用不好用，但给 Agent 用就顺了。实际工作流里，代码地图是被当作工具调用暴露给 Agent 的：

• Agent 说“我现在要改 create_order 这个函数，你先帮我看看它调了哪些东西”，工具返回调用链。
• Agent 说“订单模块里有哪些地方引用了 Decimal 类型”，工具返回引用列表。
• Agent 说“帮我找到支付回调入口”，工具支持按路径前缀和目标函数名做模糊检索。

每一次工具调用只返回紧凑的结构化结果，token 开销远小于把相关文件整段读进上下文。这个取舍是代码地图模块真正有价值的地方。

4.4 大型仓库的性能取舍

代码地图不是建完就完事的，仓库一直在变，索引需要跟着更新。我有几点实际体会：

第一次全量索引会比较慢，几十万行代码可能要跑几分钟。但好的索引器做了增量设计，文件变化后只重解析变更过的文件，再增量更新节点和边，经常几秒内就完成了。

索引深度也要控制。很多调用链展开三层以后，子节点数量会爆炸。为保住准确性，查询会限制最大展开深度，默认三层，足够覆盖大多数影响面分析场景，又不至于把 Agent 卡死在超长返回结果上。

存储上，如果仓库真的特别大，可以考虑只索引主干代码、排除测试和构建产物；如果想精确分析动态类型，再引入语义级别的类型解析。这些可以做成配置项，动静结合。

5. token 记账：把每一美元花在明面上

5.1 记账要记录什么、在哪一层记录

token 记账的入口非常关键。直接在业务代码里逐行埋点不现实，副作用大。更合理的位置是工具链的调用网关层：Agent 每次发起模型请求，必经网关，网关在这里统一记录。

一条记账记录最少包含这些字段：

• request_id：唯一请求 ID。
• model：模型名，比如 gpt-4o、claude-sonnet。
• task_id：关联到某个任务或会话。
• prompt_tokens：请求侧 token 数。
• completion_tokens：生成侧 token 数。
• total_tokens：上面两项之和。
• cost_usd：估算成本。
• timestamp：请求发生时间。
• user_id / project_id：归属信息。

有了这些字段，后续才能按任务聚合、按时间聚合、按用户聚合。

为什么不用模型服务商后台的用量报表？因为后台报表有天然延迟，按小时甚至按天结算，而且很难按任务维度拆分。记账模块要做到实时，才能在你烧完预算之前拦住你。

5.2 token 统计的两种路径

模型 API 返回结果里通常会带 usage 字段，这是最准的，记账模块优先用这个值。

但有些场景拿不到准确 usage，比如流式输出、某些自建服务、或者 provider 没返回统计。这时就退到第二条路径：用本地 tokenizer 估算。粗略估算公式：

prompt_tokens ≈ len(prompt_chars) / 3.5 completion_tokens ≈ len(output_chars) / 3.5

英文场景下这个估算比较接近，中文场景会偏差大一些。所以记账模块会标记每一条记录的类型：usage_exact 或 estimation，报表里可以区分，不会把估算当精确值用。

5.3 记账服务与配额预警

记账域的存储选用 SQLite 已经完全够用，一天可能也就几万条记录。定时任务按小时聚合，生成项目维度和任务维度的统计报表。

预算预警是硬需求。系统里设置了两层：

• 日预算阈值：比如单日 token 消耗超过 80 万，或者折算成本超过 50 美元，触发 alert。
• 月累计阈值：比如整个项目月预算 3000 美元，用到 80% 就通知管理员，95% 就直接暂停非必要任务的调用。

收益非常直观。之前在一家团队里，夜间一个没注意的跑批任务连着调模型几小时，一个月结算时多出了异常账单。上了记账和阈值告警后，这类失控能被及时拦截。

5.4 小组实践：发现夜间跑批任务烧掉 40% 日预算

有一次我在本地模拟跑完一整个测试生成任务后，用报表模块拉了一下当天分布，发现从凌晨 2 点到 5 点有一波陡增。追查后确认是一个自动化回归任务里，某个重试循环对失败用例做了无上限重试，每次重试都在调模型，token 用量翻了好几倍。

这个问题的根因是“无节制重试”。后来在记账模块里加了非常简单的兜底：单任务 token 消耗超过某个阈值，自动切断后继模型调用，必须人工确认才能继续。这类功能在只依赖模型厂商账单时几乎无法实时做到，只有在自己这一层埋点记账才能拦截。

6. 将它们组装成一个可用的 AI 编程代理

6.1 最小装配方案

这套工具链的值需要组装起来才能完全发挥。组装后的最小工作流大概是：

1. 用户向 Agent 提出需求。
2. Agent 启动时从记忆模块拉取与当前项目相关的记忆，拼进系统提示词。
3. 遇到代码相关问题时，Agent 调用代码地图模块的查询接口，获取符号定位和调用链。
4. 每一次模型请求都经过 token 记账模块，记录 token 和成本。
5. 会话结束后，Agent 将本轮新获得的重要事实写回记忆模块。

这个闭环的价值在于，每一步的输出都成为下一步的输入，整个 Agent 是带着上下文、带着地图、带着预算在工作，不再是单次的无状态猜谜。

6.2 组装后的实际效果

我用一个模拟项目跑了一遍从“拿到需求”到“产出代码改动建议”的完整流程。

需求是：“给订单模块增加一个超时关闭状态。”原任务被翻译成一段自然语言。Agent 启动时先从记忆模块拉出了三条存量记忆：“订单金额统一用 Decimal”“数据库状态字段统一用 int，不用 string”“不要在 service 层直接操作数据库连接”。

接着 Agent 调用代码地图接口，定位到订单模块的入口类、关闭相关状态的处理函数、以及所有引用该状态的调用点，总共返回了 12 个符号和 3 条调用链。整个过程工具调用次数为 11 次，最终“模型消耗+工具输出截断”折算成 token 总计约 3.2 万。记账模块显示，这个任务的成本折算约 0.4 美元，低于人工改动前反复询问和试错的成本。

这个流程里记忆模块、代码地图模块、记账模块全程参与，但没有一次需要把完整的代码仓库灌进上下文。

6.3 版本演进路径：从单机到多机

这套工具链我在实践时一开始就是纯单机，所有组件都跑在同一台机器上，存储用本地文件 + SQLite，部署简单，零运维压力。

运行稳定后，如果要支持多人协作，可以按领域做拆分部署：memory-service 独立成一个服务，代码地图索引独立成一个服务，记账数据统一写入共享数据库。这样每个模块可以单独扩容，避免“一个模块卡了拖死整条链路”。

升级顺序我建议是：先让记账模块上共享存储，因为多人协作最容易出问题的是预算分不清；再上代码地图服务，多人需要共享一份索引；最后再做记忆服务，因为它涉及隐私和数据边界，需要考虑的东西更多。

7. 常见问题与避坑清单

7.1 记忆被“零散事实”占满了怎么办

记忆系统跑一段时间后，最容易出现的问题是存入了大量低价值的事实，比如“用户喜欢在周五下午改配置”“某条日志出现过一次报错”。这类零散事实对后续推理帮助不大，却占满了检索结果。

解决办法有两个：

• 写回记忆前增加一道“总结闸门”，把多条低价值记忆合并成一条带结论的高价值记忆。
• 检索时引入时间衰减和下界过滤，太旧或重要度太低的条目直接不参与组装。

我见过有人把记忆模块做成“只追加不清洗”，结果越跑越笨，因为每次检索都带上一堆历史噪声。定期清理不是可选优化，而是必做维护。

7.2 代码地图索引和实际代码不一致

代码地图使用久了，最典型的问题就是索引落后于仓库实际变更。改完代码之后马上让 Agent 查看最新内容，返回的却还是旧符号，非常误导人。

代码地图域的处理方式是：仓库文件变更时通过文件监听或 git hook 自动触发增量更新，同时每次增量更新后对变更文件生成哈希校验，查询时如果发现文件的索引哈希和当前文件不一致，会即时标记为 stale，强制触发该文件的重新解析。

这套机制在仓库频繁变动的快速迭代场景下很管用。如果你的工具链里代码地图查出来的结果总让你有一丝不信任感，先检查一下增量同步有没有正常工作。

7.3 token 统计明明和账单对不上

记账模块底层使用模型返回的 usage 字段，偶尔会对不上账单。原因是多个环节可能存在差异：token 策略在不同版本模型上有微调、缓存命中可能不重新计算输入 token、重试也可能产生额外请求记录。

建议做法是：账单级对应用差异，以模型服务商账单为准；而记账模块负责的是实时成本和预算拦截，两者存在小误差是常态，不要因为差异就把记账数据全盘否定。

操作上，可以给记账模块加一个“账单对账导入”接口，按月导入服务商账单并记录差异。误差持续超过 10% 时再排查到底是哪里出了问题。

7.4 9 个仓库的维护成本要不要担心

拆了 9 个仓库，维护成本确实比单仓库高。但工具链在设计上已经做了不少缓解：

• 统一 CI 模板：所有仓库共用同一套 lint、test 和 release 配置。
• 统一发布脚本：一个命令可以同时提交并发布有版本变动的仓库。
• Schema 仓库作为稳定基线：记忆、地图、记账之间的数据结构都定义在 schema 仓库里，其他仓库只依赖它，避免交叉依赖成环。

实际项目里这种模式跑得很稳。九仓库不是一个拍脑袋的数量，而是拆到不继续拆、组合起来又不互相纠缠的边界。如果你要维护自己的多个仓库项目，加入这两条经验会省大量时间。

写在最后的一点体会

这套工具链给我最大的触动，不是它把某个单一功能做得多么惊艳，而是它把“记忆、代码地图、token 记账”这三件看起来不相关的事，按同一个设计原则捏合在了一起：每个模块只做一件事，中间通过清晰的 Schema 通信，整体全部走 MIT 协议放开。

从实际使用的角度，我更想提醒的是：别急着把这 9 个仓库全部跑起来，先只接一个模块，跑通之后再加下一个。很多人刚开始搭 Agent 时容易贪多，想把所有功能一次性上完，结果每个模块都没调好，整体体验反而不如精简版。这就像你先让 Agent“记住一句话”，再让它“查一个函数”，最后再让它“看账单”——每一步都稳定了，再往前走，体验自然会好。

如果你也想自己搭一套 AI 编程代理的基础设施，不妨照着“记忆-代码地图-记账”这个三角框架去设计自己的架构。哪怕只做其中一块，并且做到分类清晰、协议开放、存储轻量，你的工具链就已经超过市面上大多数自研 Agent 项目了。