企业官网建设流程全解析

1. 这套工具链到底解决了什么问题

先说说我为什么要折腾这么一套东西。过去一年多，我几乎每天都在跟 AI 编程助手打交道，从最早的代码补全，到后来的对话式改代码，再到现在的 Agent 自动执行任务。用得越多，越发现一个尴尬的现实：模型本身越来越强，但围绕它的工程配套几乎是一片荒地。

具体来说，我遇到的痛点有这么几个。第一，每次开新会话，AI 对我的项目一无所知，我得反复贴目录结构、贴关键文件、解释架构，光这些前置动作就吃掉大量 token。第二，AI 改代码时经常"迷路"，它不知道某个函数被谁调用、某个模块的边界在哪，改一处崩三处。第三，token 消耗完全是个黑盒，月底一看账单吓一跳，但根本不知道钱花在哪了。第四，不同工具之间的记忆是割裂的，在这个编辑器里教过它的东西，换个环境又得重来。

这套工具链就是冲着这四个问题去的。我把它拆成了九个独立的仓库，每个仓库解决一个具体问题，全部 MIT 协议开源，你可以只用其中一个，也可以全部串起来用。核心模块包括：记忆层（跨会话保存项目上下文）、代码地图（把代码库结构化成 AI 能理解的形式）、token 记账（精确统计每次调用的消耗）、以及若干辅助工具。

适合谁来参考？如果你只是偶尔用 AI 写个脚本，那可能用不上。但如果你跟我一样，每天有大量时间泡在 AI 辅助编程里，项目规模又不小，那这套东西能帮你省下实打实的时间和成本。下面我按模块拆开讲，重点讲设计思路和踩过的坑。

2. 记忆层：让 AI 记住你的项目

2.1 为什么不用现成的向量数据库

一提到"让 AI 记住东西"，很多人第一反应是上向量数据库，把代码切块、做 embedding、检索。我一开始也是这么干的，但实测下来问题不少。代码跟自然语言不一样，它的语义高度依赖结构关系——一个函数的意义，很大程度上由它被谁调用、它操作什么数据结构决定。单纯按文本相似度检索，经常召回一堆看起来相关、实际没用的片段。

所以我最后选了一条更"笨"但更稳的路：结构化记忆 + 分层摘要。具体做法是，记忆层不存原始代码，而是存三类东西：项目级的架构摘要、模块级的职责说明、以及变更历史里的关键决策。这些内容用 Markdown 存，人可读、AI 也可读，检索时直接按路径和标签匹配，不走向量。

提示：结构化记忆的维护成本比向量方案低得多，因为你可以直接用 Git 管理这些 Markdown 文件，diff 清晰，回滚方便。

2.2 记忆的写入时机与粒度控制

记忆什么时候写、写多细，这是最容易翻车的地方。我试过让 AI 每次改完代码自动总结，结果记忆文件迅速膨胀到几万行，检索时反而成了负担。后来我定了个规矩：只在三种情况下写记忆。

第一种是项目初始化时，手动或半自动生成一份架构摘要，这个频率很低，一次就够。第二种是完成一个完整功能后，让 AI 生成一段变更说明，记录"做了什么、为什么这么做、影响了哪些模块"。第三种是遇到非显而易见的坑时，手动记一条，比如"这个接口不能并发调用，因为底层有个全局锁"。

粒度上，我控制在每条记忆不超过 200 字。超过这个长度，说明它该被拆成多条，或者该被提炼。这个数字不是拍脑袋来的，是我观察 AI 读取记忆时的表现总结的——太长了它抓不住重点，太短了信息量不够。

2.3 记忆的检索与注入策略

检索这块我做了个取舍：不做自动检索，做显式引用。什么意思？就是 AI 不会自己去"回忆"，而是由工具链在合适的时机把相关记忆注入到上下文里。比如你让 AI 改某个模块，工具链会先把这个模块的职责说明和最近三条变更记录塞进去，再让 AI 动手。

这样做的好处是可控。自动检索最大的问题是不可预测，你永远不知道它这次会召回什么，调试起来极其痛苦。显式注入虽然笨，但每次注入什么、注入多少，你心里有数，出了问题也好定位。

注入量上我设了个硬上限：不超过上下文窗口的 15%。留足空间给实际代码和对话。这个比例是我反复调出来的，太高了 AI 容易忽略当前任务，太低了记忆又不起作用。

3. 代码地图：给 AI 一张能看懂的地图

3.1 代码地图和普通索引的区别

代码地图这个概念，市面上已经有一些工具在做，但大多停留在"符号索引"层面——记录函数在哪、类在哪、谁引用了谁。这些信息有用，但对 AI 来说还不够。AI 需要的是带语义的分层结构：这个模块在整个系统里扮演什么角色，它对外暴露什么能力，它依赖哪些其他模块。

所以我的代码地图分三层。最底层是符号层，记录所有函数、类、变量的定义位置和引用关系，这层用现成的解析器生成。中间层是模块层，把符号按文件、目录聚合，生成每个模块的"能力清单"。最上层是架构层，描述模块之间的依赖方向和调用关系，形成一个有向图。

3.2 生成代码地图的实操流程

生成流程我写成了一个命令行工具，跑一次大概几十秒到几分钟，取决于项目大小。步骤是这样的。

第一步，扫描项目根目录，识别语言和构建配置。这一步主要是为了确定用哪个解析器，以及排除哪些目录（比如依赖包、构建产物）。

第二步，对每个源文件做语法解析，提取符号定义和引用。这里我用的是各语言官方的解析库，不用正则，因为正则处理不了嵌套和泛型这些情况。

第三步，聚合符号到模块，生成能力清单。这一步会做一些启发式判断，比如一个文件里导出超过五个函数，就认为它是个"工具模块"；导出主要是类，就认为是"领域模块"。

第四步，分析模块间依赖，构建有向图。这里要处理循环依赖，我的做法是标记出来但不阻断，因为实际项目里循环依赖很常见，硬要消除反而伤筋动骨。

第五步，输出成 Markdown 和 JSON 两种格式。Markdown 给人看，JSON 给工具链其他部分消费。

# 生成代码地图的典型调用 codemap build --root ./src --lang typescript --out ./codemap

3.3 地图的更新与增量维护

代码地图最大的敌人是"过期"。项目天天在变，地图如果不同步，比没有还危险——AI 会基于错误的信息做决策。我的方案是增量更新 + 定期全量重建。

增量更新挂在 Git 的 pre-commit 钩子上，每次提交时只重新解析改动的文件，更新对应的符号和模块信息。这个很快，通常一两秒。全量重建我设成每周一次，或者手动触发，用来修正增量更新累积的误差。

注意：增量更新有个坑，就是删除文件时容易漏掉清理。我踩过一次，地图里残留了一堆已经不存在的符号，导致 AI 引用到幽灵函数。后来加了删除检测才解决。

4. Token 记账：把每一分钱都算清楚

4.1 为什么 token 统计这么难做

你可能会想，token 统计有什么难的，调用 API 的时候不是返回用量吗？问题在于，实际使用中一次任务往往涉及多次调用，而且不同工具的调用方式不一样。有的走官方 SDK，有的走命令行，有的走编辑器插件。要把这些分散的调用统一记账，得在每个入口都埋点。

更麻烦的是归因。一次任务消耗了 5000 token，这 5000 里有多少是系统提示、多少是记忆注入、多少是实际代码、多少是 AI 的输出？不拆开看，你根本不知道优化从哪里下手。我见过太多人抱怨 token 贵，但一问细节，全是"不知道"。

4.2 记账模块的埋点设计

我的记账模块设计成一个独立的代理层，所有对模型的调用都经过它。它做三件事：记录原始请求和响应、按来源拆分 token、汇总到本地数据库。

拆分逻辑是这样的。请求侧分四类：系统提示、记忆注入、代码上下文、用户输入。响应侧分两类：思考过程和最终输出。每类都单独计数。这个拆分靠的是在构造请求时就打标签，而不是事后猜。

数据库我用的是 SQLite，单文件，方便迁移和备份。表结构很简单，一张调用记录表，一张任务汇总表。调用记录表存每次调用的明细，任务汇总表按任务聚合。

-- 调用记录表的核心字段 CREATE TABLE calls ( id INTEGER PRIMARY KEY, task_id TEXT, timestamp INTEGER, model TEXT, prompt_system INTEGER, prompt_memory INTEGER, prompt_context INTEGER, prompt_user INTEGER, completion_think INTEGER, completion_output INTEGER );

4.3 从记账数据里能看出什么

数据攒起来之后，能看出很多反直觉的东西。比如我原以为 token 大头在代码上下文，结果统计下来，系统提示和记忆注入加起来占了将近四成。这直接促使我去精简系统提示，把一些啰嗦的说明砍掉，一个月下来省了不少。

还有一个发现是，不同任务的 token 效率差异极大。同样是改一个函数，有的任务几百 token 搞定，有的要上万。差异主要来自上下文是否干净——如果 AI 被一堆无关信息干扰，它会反复试探，消耗自然高。这个发现让我更重视记忆注入的精准度。

提示：记账数据建议定期导出成 CSV 做趋势分析，光看单次数字意义不大，看趋势才能发现系统性问题。

5. 九个仓库怎么协同工作

5.1 仓库划分的逻辑

九个仓库不是随便拆的，划分原则是单一职责 + 可独立使用。每个仓库解决一个问题，不依赖其他仓库也能跑。这样你可以按需取用，不用为了一个功能引入整个体系。

具体划分是：记忆层两个仓库（存储和检索）、代码地图两个仓库（生成和查询）、记账两个仓库（埋点和分析）、辅助工具三个仓库（配置管理、任务编排、报告生成）。每个仓库都有独立的文档和示例，MIT 协议，随便改随便用。

5.2 数据如何在仓库间流动

仓库之间通过文件系统通信，不搞复杂的服务依赖。记忆层输出 Markdown 和 JSON，代码地图输出 JSON，记账输出 SQLite。任务编排工具读取这些文件，组装成最终的请求。

这种"文件即接口"的设计，好处是透明、可调试。你随时可以打开文件看里面是什么，出问题了直接改文件就行，不用去翻日志或者连数据库。坏处是性能一般，但对个人和小团队来说完全够用。

5.3 一个完整的任务流程示例

假设你要让 AI 重构某个模块。流程是这样的：任务编排工具先读取代码地图，找到这个模块的位置和依赖；然后从记忆层拉取这个模块的职责说明和最近变更；接着把这些信息和你的指令组装成请求，经过记账层发出；AI 返回结果后，记账层记录消耗，任务编排工具把结果写回，并触发记忆层更新。

整个过程你只需要下一条指令，剩下的自动完成。当然，你也可以关掉任何一环，手动控制。

6. 实操中踩过的坑与排查技巧

6.1 记忆污染：最隐蔽的问题

记忆层用久了，最大的问题是污染。所谓污染，就是记忆里混进了错误或过时的信息，AI 基于这些信息做出错误决策，而且你还很难发现。我遇到过一次，记忆里写着"这个接口是幂等的"，但实际上后来改成了非幂等，结果 AI 按幂等处理，出了 bug。

排查这类问题，我的办法是给每条记忆加时间戳和来源。时间戳让你知道它有多旧，来源让你知道是谁写的、在什么情况下写的。定期 review 旧记忆，该删的删，该更新的更新。这个习惯养成后，污染问题基本可控。

6.2 代码地图的解析失败

不同语言的解析器成熟度差异很大。主流的几门语言问题不大，但一些小众语言或者用了大量宏的代码，解析经常失败。我的处理策略是降级而非报错：解析失败的文件，退回到基于正则的粗略提取，虽然不准，但总比没有强。同时在报告里标记出来，提醒你手动检查。

6.3 Token 记账的漏记

漏记主要发生在异常路径上。比如请求发出去了但超时了，或者 AI 返回了错误，这些情况如果没处理好，消耗就漏掉了。我的做法是在记账层加一个兜底记录：不管请求成功失败，只要发出去了，就先记一条，成功后再更新明细。这样即使程序崩溃，也不会完全丢失数据。

6.4 常见问题速查表

7. 一些设计上的取舍与个人体会

7.1 为什么坚持 MIT 而不是更宽松或更严格

选 MIT 是权衡的结果。更宽松的协议（比如放弃版权）对使用者没保障，企业用起来有顾虑。更严格的协议（比如要求衍生作品也开源）会吓退一部分想集成的商业项目。MIT 是个中间点，既保证了使用自由，又保留了基本的署名要求，实际推广下来接受度最高。

7.2 不做 SaaS 只做本地工具

有人建议我把这套东西做成云服务，我拒绝了。原因很简单：代码是敏感资产，很多团队不愿意把代码结构、依赖关系这些信息传到第三方。本地工具虽然部署麻烦点，但数据不出门，用着放心。而且本地工具没有运维成本，我作为维护者也轻松。

7.3 关于维护节奏

九个仓库听着多，但实际维护量没想象中大。因为职责清晰，每个仓库的改动都很局部。我的节奏是：核心仓库（记忆和地图）保持活跃，辅助工具按需更新。issue 我会看，但不承诺响应时间，毕竟这是业余项目。想贡献的人直接提 PR，我基本都会 review。

这套工具链我用了大半年，最大的感受是：AI 编程的上限，很大程度上不取决于模型，而取决于你给它喂什么、怎么喂。同样的模型，配上好的记忆和地图，产出质量能差出一大截。如果你也在做类似的事情，欢迎交流，仓库地址在个人主页，MIT 协议，随便用。