企业官网建设流程全解析

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

先说说我为什么要折腾这么一套东西。过去一年多，我几乎每天都在跟 AI 编程助手打交道，从最早的代码补全，到后来的对话式改代码，再到现在的自主代理模式。用得越多，越发现一个尴尬的现实：模型能力在飞速进步，但围绕它的工程配套几乎是空白。

具体来说，我遇到的痛点集中在三个地方。第一是记忆问题。每次开一个新会话，AI 就完全失忆，昨天刚跟它讲清楚的架构约定、命名规范、踩过的坑，今天又要从头讲一遍。上下文窗口再大也扛不住这种重复消耗，而且塞太多历史进去，模型反而会抓不住重点。第二是代码理解问题。一个中等规模的项目动辄几百上千个文件，AI 每次都要靠关键词搜索去猜哪些文件相关，经常找错、找漏，改一处崩三处。第三是成本失控问题。代理模式会疯狂调用模型，一个任务跑下来烧掉多少 token、花掉多少钱，完全没有感知，等到账单出来才傻眼。

这三个问题不是孤立的，它们背后其实是同一个东西：缺少一层面向 AI 代理的工程基础设施。模型是发动机，但你不能只有发动机就上路，还得有变速箱、仪表盘、油箱。我开源的这套工具链，就是奔着补齐这层基础设施去的，一共 9 个仓库，全部 MIT 协议，随便用随便改。

它适合谁？如果你只是偶尔用 AI 补几行代码，那可能用不上。但如果你在做代理式编程——让 AI 自主读代码、改代码、跑测试、迭代——或者你在团队里想把 AI 编程流程标准化，那这套东西应该能帮你省下不少重复造轮子的时间。下面我按模块拆开讲，每个部分都会说清楚设计思路、关键实现和实操中踩过的坑。

2. 记忆模块：让 AI 记住该记的，忘掉该忘的

2.1 为什么不能简单地把历史全塞进去

很多人第一反应是：记忆嘛，把之前的对话记录拼起来不就行了。我一开始也这么干，结果很快发现问题。假设一个项目开发了两周，对话历史累积了几十万 token，你全塞进去，先不说成本，模型对中间部分的注意力会明显衰减，也就是常说的"lost in the middle"。而且历史里大量是一次性的调试信息，比如"这个变量名拼错了改一下"，这种内容对后续任务毫无价值，留着纯属噪音。

所以记忆模块的核心不是"存"，而是筛选和结构化。我的设计思路是把记忆分成三层：长期记忆存项目的稳定事实，比如技术栈、目录约定、核心抽象；中期记忆存当前任务链的上下文，比如这个功能改到哪一步了；短期记忆就是当前这一轮对话的临时信息。三层用不同的存储策略和过期策略。

2.2 三层记忆的具体实现

长期记忆我用的是结构化的 Markdown 文件加向量检索的组合。为什么不用纯向量库？因为纯向量检索有个致命问题：它只能按语义相似度召回，但项目里有些事实是"必须始终在场"的，比如"这个项目禁止使用某个被弃用的 API"。这种约束不该靠相似度去碰运气召回，而应该无条件注入。所以我的做法是：硬约束写成固定文件，每次必读；软知识才走向量检索。

中期记忆我用的是一个任务状态机。每个任务有明确的阶段，比如"需求澄清→方案设计→编码→测试→收尾"，每个阶段结束时把关键决策和产出物摘要写进状态文件。这样即使会话中断，下次接着干的时候，AI 读一下状态文件就知道进度，不用重新梳理。

短期记忆就是常规的对话窗口管理，但加了一个滑动窗口加摘要的机制：当对话超过一定轮数，把最早的几轮压缩成一段摘要，保留关键结论，丢掉过程细节。

# 记忆分层的一个简化示意 class MemoryLayer: def __init__(self, project_root): self.long_term = load_constraints(project_root) # 硬约束，必读 self.vector_store = VectorStore(project_root) # 软知识，检索 self.task_state = TaskStateMachine(project_root) # 任务进度 self.short_term = SlidingWindow(max_turns=20) # 对话窗口 def build_context(self, query): parts = [self.long_term] # 无条件注入 parts.append(self.task_state.summary()) # 当前进度 parts.append(self.vector_store.search(query, top_k=5)) # 相关软知识 parts.append(self.short_term.recent()) # 近期对话 return assemble(parts)

2.3 实操中的几个关键决策

第一个决策是记忆的写入时机。我试过让 AI 自己判断什么时候该记，结果它要么记太勤（把废话都存了），要么记太懒（重要决策漏了）。后来改成事件驱动：只在特定事件发生时触发写入，比如任务阶段切换、用户明确说"记住这个"、检测到重复出现的模式。这样写入的内容质量高很多。

第二个决策是记忆的冲突处理。项目在演进，早期记的"用方案 A"可能后来改成了方案 B。如果不处理冲突，AI 会拿到自相矛盾的记忆。我的做法是给每条记忆加时间戳和状态标记，检索时优先返回最新的，同时保留历史版本供追溯。遇到明确冲突时，在上下文里显式提示"注意：关于 X 存在新旧两种约定，当前以新版为准"。

提示：记忆模块最容易被忽视的是"遗忘"。我建议给软知识设置一个衰减机制，超过一定时间没被召回的记忆自动降权，避免陈旧信息干扰。硬约束则相反，要定期人工审查，确认还有效。

3. 代码地图：让 AI 不再靠猜来找文件

3.1 关键词搜索为什么不够用

AI 改代码的第一步是找到相关文件。大多数工具的做法是让 AI 生成关键词，然后做全文搜索。这个方法在小项目上凑合，项目一大就废了。原因很简单：代码的关联性不等于文本的相似性。一个函数调用了另一个模块的接口，这两个文件在文本上可能毫无共同词，但逻辑上强相关。反过来，两个文件可能都包含"user"这个词，但一个处理用户认证，一个处理用户界面，八竿子打不着。

所以代码地图要解决的是结构化的代码关系表示。它得回答几个问题：这个文件依赖谁、被谁依赖？这个函数在哪里被调用？改这个接口会影响哪些地方？这些问题的答案构成了 AI 导航的"地图"。

3.2 代码地图的构建方式

我用的是静态分析加轻量索引的方案。具体来说，分三步走。第一步，用语言对应的解析器把源码解析成语法树，提取出定义（函数、类、变量）和引用（调用、导入、继承）两类信息。第二步，把这些信息组织成图结构，节点是代码实体，边是关系。第三步，对图做预处理，算出一些常用的查询结果，比如每个文件的依赖闭包、每个函数的调用链。

为什么不直接上重型 IDE 的索引？因为那套东西太重，启动慢、内存占用高，而且和 AI 代理的调用模式不匹配。代理需要的是快速、增量、可编程的查询接口，不是给人用的图形界面。所以我做的是一个轻量的、可以按需构建的索引，项目首次构建可能花几十秒，之后增量更新基本是毫秒级。

# 构建代码地图的典型流程 codemap init --root ./my-project # 初始化，扫描项目结构 codemap build --lang python,typescript # 构建索引，指定语言 codemap query callers --symbol "processOrder" # 查询谁调用了这个函数 codemap query impact --file "src/order.ts" # 查询改这个文件的影响面

3.3 地图怎么喂给 AI 才有效

构建出地图是一回事，怎么让 AI 用好是另一回事。我踩过的坑是：一开始把整个地图的摘要一股脑塞给 AI，结果它被海量信息淹没了。后来改成按需查询：AI 先根据任务描述，通过工具调用去查地图，拿到精确结果再继续。这就像人查地图，你不会把整张地图背下来，而是先确定"我在哪、我要去哪"，然后查路线。

具体接口设计上，我提供了几个原子查询：查定义、查引用、查依赖、查影响面、查相似代码。AI 通过函数调用按需获取。实测下来，这种方式比一次性注入节省了大概 70% 的上下文 token，而且准确率更高，因为每次拿到的都是精确相关的信息。

3.4 增量更新与一致性

代码地图最大的工程挑战是保持和源码同步。项目一直在改，地图如果滞后，AI 就会基于过时信息做决策。我的方案是文件监听加增量重建：监听文件系统变化，文件改动时只重建受影响的部分。这里有个细节，改一个文件可能影响它的依赖者的依赖信息，所以增量更新要沿着图的边传播，但传播深度要设上限，否则一个小改动可能触发全图重建。

注意：代码地图的准确性依赖解析器的覆盖度。动态语言里有些引用是运行时才确定的，静态分析抓不到。我的处理是把这类"不确定引用"单独标记，查询时提示 AI"此处可能存在动态引用，需人工确认"，而不是假装它不存在。

4. Token 记账：把成本变成可见、可控的数字

4.1 为什么必须做记账

代理模式最吓人的地方是成本不可见。你让它改个功能，它可能在后台调了几十次模型，每次调用都消耗 token，但你完全没感觉。等到月底账单出来，才发现一个任务烧掉了几十块。更糟的是，你根本不知道钱花在哪了，是上下文太长，还是调用次数太多，还是某个环节陷入了死循环。

Token 记账要解决的就是这个。它得记录每一次模型调用的输入输出 token 数、对应的成本、归属的任务和阶段，然后聚合成可分析的报表。有了这个，你才能回答"这个功能开发花了多少钱""哪个环节最烧钱""有没有异常调用"。

4.2 记账的实现要点

实现上，核心是拦截所有模型调用。我在工具链里做了一层统一的调用网关，所有对模型的请求都经过它。网关在请求前后记录 token 数（优先用 API 返回的精确值，拿不到就用估算），打上任务 ID、阶段、时间戳等标签，写入本地账本。

账本我用的是 SQLite，为什么不用文件？因为要支持灵活的聚合查询。比如"查过去一周每个任务的成本分布""查某个阶段平均每次调用的 token 数"，这些用 SQL 几行就搞定，用文件得自己写一堆解析逻辑。

# 记账网关的核心逻辑 class MeteredGateway: def __init__(self, ledger): self.ledger = ledger def call(self, model, messages, task_id, stage): input_tokens = count_tokens(messages) response = model.invoke(messages) output_tokens = count_tokens(response) cost = calculate_cost(model, input_tokens, output_tokens) self.ledger.record( task_id=task_id, stage=stage, model=model.name, input_tokens=input_tokens, output_tokens=output_tokens, cost=cost, timestamp=now() ) return response

4.3 成本估算的精度问题

不同模型的计费方式不一样，有的按输入输出分开计价，有的有缓存折扣，有的按阶梯定价。要做到精确估算，得维护一张计费规则表，并且随着模型更新及时调整。我的做法是把计费规则做成可配置的，用户可以根据自己实际使用的模型和价格自己填。默认给一套常见模型的参考值，但不保证实时准确。

估算精度上，输入 token 一般能算得比较准，因为消息内容你完全掌握。输出 token 在拿到响应前是未知的，只能等响应回来再算。所以记账是事后记录，不是事前预估。如果你需要事前控制预算，那得另做一层预算检查：在调用前估算这次大概要花多少，超过阈值就拦截或告警。

4.4 从记账数据里能挖出什么

记账本身不难，难的是把数据用起来。我基于账本做了几个分析视图，实测很有用。第一个是任务成本排行，一眼看出哪个任务最烧钱，通常能发现一些设计不合理的任务。第二个是阶段成本分布，看看钱主要花在编码还是测试还是调试，如果调试占比过高，说明前面的方案设计有问题。第三个是异常调用检测，比如某个任务在短时间内调用次数暴增，很可能是陷入了重试循环。

提示：记账数据建议定期导出归档，本地库不要无限增长。另外，如果团队多人共用，账本要按用户或任务隔离，否则数据混在一起没法分析。

5. 工具链的组装与协同

5.1 9 个仓库怎么分工

这套工具链拆成 9 个仓库，不是为了显得多，而是为了职责清晰、按需取用。有人可能只需要记忆模块，有人可能只关心记账，强行打包成一个巨型仓库反而不好用。大致分工是：核心抽象层一个，记忆模块一个，代码地图一个，记账一个，然后是几个适配层（对接不同的模型和编辑器），再加一个命令行入口和一个示例项目。

仓库之间通过定义良好的接口通信，核心抽象层定义接口，各模块实现接口。这样你可以替换任何一个模块而不影响其他部分。比如你不喜欢我的记忆实现，完全可以自己写一个符合接口的，其他模块照常工作。

5.2 模块间的数据流

理解数据流对用好这套工具很重要。一次典型的代理任务，数据是这样流动的：任务开始，记忆模块加载长期约束和任务状态；AI 根据任务描述，通过代码地图查询相关文件；读取文件内容，结合记忆构建上下文；调用模型，记账网关记录消耗；模型返回修改方案，AI 执行修改；修改后更新代码地图的增量索引；任务阶段推进，记忆模块写入新的状态。整个过程形成一个闭环。

这个闭环里，记忆是横切的，每个环节都可能读写；代码地图是查询服务，被反复调用；记账是旁路，不干扰主流程但记录一切。三者协同，才让代理有了"记得住、找得到、算得清"的能力。

5.3 集成到现有工作流

这套东西不绑定特定的编辑器或平台，核心是命令行工具加库。你可以把它集成到自己的脚本里，也可以包一层接到编辑器插件里。我自己的用法是在项目根目录放一个配置文件，定义好模型、预算、记忆策略，然后通过命令行触发任务。团队协作时，配置文件纳入版本控制，保证大家用的是同一套约定。

# 工具链配置示例 project: root: ./ languages: [python, typescript] memory: constraints_file: .ai/constraints.md vector_store: .ai/memory.db task_state: .ai/task-state.json codemap: index_path: .ai/codemap.idx watch: true budget: ledger: .ai/ledger.db per_task_limit: 2.00 # 单任务成本上限，单位按你的计价 alert_threshold: 0.8 # 达到 80% 时告警

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

6.1 记忆模块的典型问题

问题一：记忆污染。有次 AI 把一次调试中的临时结论写进了长期记忆，导致后续任务一直带着错误假设。排查后发现是写入触发条件太宽。解决方法是给长期记忆的写入加一道确认，重要事实必须显式确认才入库。

问题二：检索召回不准。向量检索经常召回一些语义相似但实际无关的记忆。后来我加了元数据过滤，检索时先按任务类型、时间范围过滤，再做语义匹配，准确率明显提升。

问题三：上下文超限。三层记忆拼起来偶尔会超过模型窗口。解决方法是给每层设 token 预算，超了就按优先级裁剪，硬约束永远保留，软知识按相关度截断。

6.2 代码地图的典型问题

问题一：索引构建慢。大项目首次构建要几分钟。优化方法是并行解析加缓存，已经解析过的文件内容没变就跳过。实测能把首次构建时间砍掉一半以上。

问题二：动态引用漏检。前面提过，动态语言的运行时引用静态分析抓不到。我的补救是结合运行时的调用日志，把实际发生过的调用补进地图，作为静态分析的补充。

问题三：地图与源码不同步。文件监听偶尔会漏事件，导致地图滞后。加了一个定期全量校验的机制，比如每小时对比一次文件哈希，发现不一致就触发重建。

6.3 记账模块的典型问题

问题一：token 估算偏差。不同模型的分词方式不同，用统一估算会有偏差。解决方法是优先用 API 返回的精确值，估算只作为兜底，并且在报表里标注哪些是估算值。

问题二：并发写入冲突。多个任务同时跑，账本写入可能冲突。SQLite 开了 WAL 模式后基本解决，但高并发下还是建议加一个写入队列串行化。

问题三：成本归因不清。一个任务里嵌套了子任务，成本算谁的？我的做法是给每个调用打上完整的任务路径标签，分析时可以按任意层级聚合。

6.4 几个通用的避坑心得

第一，不要追求一步到位。我一开始想把三个模块都做到完美再发布，结果拖了很久。后来改成先发布能用的版本，边用边改，反而迭代更快。第二，日志要打够。代理系统出问题时，没有详细日志基本没法排查。我在每个关键环节都加了结构化日志，出问题能快速定位。第三，配置要外置。不要把策略硬编码在代码里，做成配置，不同项目不同场景可以调。第四，接口要稳定。模块间接口一旦定下来，尽量不改，改了要版本化，否则用户升级会痛苦。

这套工具链我还在持续迭代，9 个仓库都在活跃维护。如果你也在做代理式编程，欢迎拿去用，遇到问题提 issue，我会尽量回。我个人在实际操作中的体会是，AI 编程的上限不取决于模型多强，而取决于你给它搭的这套基础设施多扎实。模型会换，但记忆、地图、记账这三件事，是任何代理系统都绕不开的基本功。