企业官网建设流程全解析

接手一个五年前启动、核心代码超过三十万行的服务端项目时，我最大的感受是：代码明明都躺在仓库里，但真正想搞清楚“它为什么长成这样”，比想象中难得多。代码还在，可写代码的人、当时的业务约束、几次关键架构调整的原因，大部分散落在 commit 描述、未关闭的 issue 和为数不多的老同事脑子里。项目探测，就是把这堆隐性知识重新“测绘”出来；而把探测结果接进 AI 的外部记忆，则是让大模型理解老项目时不再只靠通用文本直觉。这篇文章会用我自己的实操为主线，讲怎么给老项目做知识测绘、建一个可检索的项目知识库，再让 AI Agent 基于它做问答和辅助改代码，最后附上一些直接用得上的细节和避坑经验。如果你正接手遗留系统，或者在做 AI 编程落地，这篇应该对胃口。

1. 老项目“懂不起”的根源：知识不在代码里

1.1 代码是结果，不是原因

很多人提到老项目，第一反应是“技术债”：循环依赖、超大接口、没有测试、一地 TODO。但我觉得真正的杀伤力是知识债。技术债至少能靠静态扫描找到位置，重构有路线图；知识债却很难量化，它藏在“这段逻辑为什么这么绕”的沉默里。

举个例子。一个订单模块里，我把cancelOrder的入口调用链从头摸到尾，发现系统在更新订单状态前会给一个看似多余的用户通知服务发消息。直觉上这是性能损耗，删掉似乎没问题。但我多问了一句才知道，早期版本因为没有这个通知，客服经常在订单取消后误操作，导致资损投诉。这个教训没有写进代码注释，只存在于当时两个开发在群里吵过的一轮对话里。代码是“结论”，不是“原因”。如果你只把代码丢给通用 AI 工具，它最多给你解释语法结构，解释不了背后的真实业务约束。

所以项目探测的第一步不是生成漂亮的架构图，而是把代码里外的“为什么”变成事实。把模块划分是什么、核心链路怎么走、哪些设计决策曾被人为否掉，都搜集出来。这个动作本身没有多高科技，难在系统性和可持续性。

1.2 项目探测到底探寻哪些知识

我习惯把老项目知识分成四类。

第一类是结构知识：模块、服务、数据模型、调用关系，偏静态。它可以通过扫描目录、读配置文件、分析 import/require 依赖得到。

第二类是行为知识：核心业务流程、状态机转换、异常路径、定时任务触发的链路，偏动态。这部分光看代码还不够，经常需要翻 PR 和跑测试用例才能还原。

第三类是约定知识：命名规范、错误码含义、配置项规则、接口幂等设计。这类知识散落在开发规范文档和代码 review 记录里，新人最容易踩坑。

第四类是决策知识：为什么从 A 方案换成 B 方案、哪块功能是临时兼容、哪些代码属于“明知不可为而为之”。这些往往只存在于老同事的脑子里，或者藏在某次 merge commit 的描述里。

这四类知识不是一次探测就能齐活的。我通常会先做第一类和第二类，因为可自动化；第三类需要找开发规范补充；第四类则需要和老员工聊天，像做采访一样逐条沉淀。很多团队希望用“代码即文档”解决一切，但商业项目里有大量上下文是代码表达不出来的。AI 可以帮你处理文本，但首先你得拥有记录这些上下文的文件。

1.3 先把“活文档”抢救出来

项目探测最容易被忽略的动作，是抢救那些还没离开团队的知识。每个老项目里至少有一两个“活字典”，他们对历史了如指掌，但如果不把经历固化成文字，等他们调岗或离职，项目会迎来一次断崖式的知识跌落。

我在一次治理里做过这样的事：约了负责过三版重构的老同事，按下面的提纲聊了两小时：

• 现在的核心业务链路里，哪里最容易被误改？
• 如果有新需求要动订单状态机，你第一反应要提醒什么？
• 哪些模块你特别不想让人碰，为什么？
• 有哪些“暂时兼容”“下个版本再删”的代码？当时是怎么决策的？

聊完之后，我把内容整理成一份带时间线和决策原因的“项目口述史”，大概八千字。这些内容后来成了 AI 知识库里价值很高的一部分。为什么不直接写成注释？因为注释跟着代码走，位置太碎，AI检索时不容易跨文件关联；独立成“决策档案”后，可以按主题被调用。

从这里能看到：项目探测不只是技术动作，还是一次知识资产管理。探测的产物，就是后续一切 AI 外部记忆建设的地基。

2. 为什么非得把知识做成 AI 的“外部记忆”

2.1 大模型很聪明，但它没有项目“私设”

大模型训练时见过海量通用代码和文档，能告诉你 Python 装饰器怎么写、设计模式什么场景用。但面对你公司独有的订单状态机、优惠叠加规则、会员等级体系，它在训练数据里根本找不到对应资料。模型像是很聪明的新人，常识丰富，但对你项目里那几个“私有设定”一无所知，还容易凭经验脑补。

大家喜欢说“让 AI 读代码”，但大模型输入窗口有限，即便无限长，把几十万行代码全部堆进上下文，效果也会变差。注意力会被无关代码稀释，模型会记住开头和结尾，中间关键信息反而漂移。而且每次对话都塞全量代码，成本高、响应慢，根本没法日常用。

解决矛盾的核心思路是给 AI 配一个可检索的外部记忆库：项目相关知识先存到外部存储，模型回答前只取和问题相关的片段。这个记忆库不属于单个对话上下文，而是独立存在的资产，可以被多个 Agent 和工具共享。

2.2 外部记忆这套打法的原理

外部记忆这个词听起来玄，本质上就是 Retrieval-Augmented Generation，检索增强生成。拆开看流程：

• 把项目文档、核心代码、口述史切分成小块；
• 用 Embedding 模型把每块转成向量，存入向量数据库；
• 用户提问时，把问题转成向量，在库里找相似度最高的若干块；
• 把检索到的内容作为参考材料，和大模型问题一起组装成 Prompt；
• 模型基于参考材料输出答案，并可以给出引用来源。

这一步和人类的工作方式很像：没人能在入职第一天背下整个集团历史，但会随身带一个能快速检索的笔记本。外部记忆就是这个“高亮笔记”，模型不需要记住所有内容，只需要知道怎么翻到对的那一页。

实际项目中，我还会在这套流程前面加一个 Agent 层。AI Agent 不只是被动回答，它能判断何时调用检索工具、何时先拆解任务、何时需要读某个具体代码文件。外部记忆在这里扮演长期记忆模块：Agent 在当前对话中临时拿到的上下文是短期记忆，而可以反复查询的知识库是长期记忆。

2.3 三种接入 AI 记忆的方式对比

在落地之前，我比较过三种常见做法。

第一种是把整个项目直接塞进 Prompt。优点是简单，适合几万行以内的小项目；缺点是成本高、超过上下文限制、检索质量不稳定。中大型老项目基本不可行。

第二种是直接靠 Cursor、GitHub Copilot 这类工具的代码索引。优点是开箱即用，能帮你做代码补全和局部问答；缺点是它们对“业务术语”的理解不够深，可能模型连你内部叫了几年的模块名都拼不对，而且它们没有第三方知识来源接口。

第三种是自己构建项目探测加外部记忆库，再做成工具或 MCP 服务。优点是可定制、可沉淀知识、可控隐私、工具通用；缺点是前期要投入时间做采集和清洗。

我的结论是，老项目治理值得采用第三种，但同时也不能否定第二种。Cursor 已经是我的日常编辑器，项目里长期放着.cursor/rules和关键架构说明，让 IDE 内的 AI 至少有项目基础背景；更复杂的问题或需要跨模块检索时，再去调用外部记忆服务。两者各管一段，效果互补。

2.4 我的选择：项目地图 + 知识检索双通道

对接了几个月的经验后，我不再单纯依赖纯向量检索，而是用“项目地图 + 知识检索”双通道结构。简单说：先给 AI 一张绝不超 500 token 的压缩版项目地图，里面包含核心模块、依赖方向、状态机大致节点，让它面对问题的时候能先定位到区域；然后再让 Agent 调用外部记忆里的检索工具，去读具体的代码片段或决策档案。

这套结构的价值在于，很多问题是“方向性”的。比如问“这个订单状态能不能从待支付直接改成已完成”，如果 AI 没有全局地图，它可能直接检索代码，找一个 StatusEnum 就开始瞎猜；但如果地图上标了订单状态机的五条主转移路径，它就会先意识到“待支付到已完成”不在正常路径上，再往下看有没有特别注释的历史兼容逻辑。先粗后细，比让它对着碎片“盲猜”靠谱非常多。

3. 动手实录：从老代码到 AI 可用知识库

3.1 第一步：用探测脚本画出项目骨架

我一般不会把整个仓库一股脑丢进知识库。第一件事是写脚本做项目探测，把仓库的地形摸清楚。不同语言思路一样，下面以 Python 后端项目为例。

先看目录结构：

tree -L 4 -I 'node_modules|dist|build|.git|__pycache__|venv' > project_tree.txt

这步能快速知道有哪些服务、哪些目录是核心逻辑。之后我再用一个简单脚本把代码文件按行数和修改时间排序，寻找那些又老又大的“定时炸弹”文件：

find app -name '*.py' -type f -exec wc -l {} + | sort -rn | head -30

文件大不一定代表责任大，但大概率是隐藏复杂度的信号。拿到这些候选文件后，用 AST 解析提取类和函数签名，比用正则可靠。AST 能正确识别嵌套函数、装饰器、方法参数，不会因为缩进而误判。对一段业务代码，我用类似下面的思路提取块信息：

import ast from pathlib import Path def extract_functions(filepath): tree = ast.parse(Path(filepath).read_text(encoding="utf-8")) records = [] for node in ast.walk(tree): if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): records.append({ "name": node.name, "lineno": node.lineno, "end_lineno": node.end_lineno, "args": [a.arg for a in node.args.args], "decorators": [ast.unparse(d) for d in node.decorator_list], }) return records

这一步生成的是结构化索引，还不是给 AI 看的自然语言。它会在后面辅助决定“哪个函数该单独切一块”。

做完静态结构探测，我还会看 git 历史里最有信息量的提交描述：

git log --pretty=format:'%h|%ad|%an|%s' --date=short --since='5 years ago' | head -200

从这些记录里能发现大量“为什么”线索，比如“调整抵扣顺序兼容旧卡券”“去掉营销位透出，降低资损风险”。把这些描述里出现频率高的词标出来，就能形成一个业务术语候选表，后续需要让 AI 理解这些词。

3.2 第二步：构建一份可读的“项目地图”

探测脚本输出的是碎片，需要有人把它们组装成项目地图。我通常给老项目写一份project_map.md，大概长这样：

# 项目地图 ## 核心模块 - billing-service：负责订单计费、优惠券核销、对账，依赖 member-service、coupon-service。 - member-service：负责会员等级、权益查询，不依赖其他业务模块。 - gateway-service：负责鉴权、路由和限流，不处理业务逻辑。 ## 主干链路 1. 客户端提交订单 -> gateway 解析 token -> order-service 创建 PENDING 状态订单。 2. billing-service 异步计算金额，若命中优惠券则调用 coupon-service 核销。 3. 支付回调回调 order-service，状态由 PENDING_WAIT_PAY 迁移至 PAID。 4. 超时未支付由定时任务取消，状态迁移至 CANCELED。 ## 重点状态机 order.status: PENDING_WAIT_PAY -> PAID -> SHIPPING -> DONE |-------> CANCELED（用户取消 / 超时） |-------> REFUNDING（支付后取消） -> REFUNDED ## 需要小心的地方 - 金额计算在服务端必须二次校验，原因是早期客户端绕过限制造成过资损。 - 会员等级缓存十分钟，不要为了强一致去掉缓存，会导致数据库抖动。

这个地图不会很长，最多一千多字，但它是给 AI 看的“城市总览”。如果没有这份文件，即使做了向量库，AI 也容易因为检索碎片而失去上下文。

写完地图后，我建议把它直接放到仓库的docs/目录，并加入.cursor/rules或类似 IDE 规则，让日常编码时 AI 默认读过这张地图。地图是需要人工维护的文档，但维护成本很低，因为模块级变化并不频繁。

3.3 第三步：知识切块，让 AI 能吃得动

没有经验的人会直接把单个 Markdown 文件或 Python 文件整块扔进向量库。对于超过几千字的文件，效果会明显变差，因为一个向量里的语义太多，检索时可能只命中其中一句话，却需要把整块无关内容都带出来。

我的切块原则有三个：语义完整、不越界、带元数据。

语义完整，意思是尽量按模块、类、函数、文档章节去切，不要按固定行数硬切。对代码块，我优先按 AST 提取每个函数或类作为一个独立块；如果函数实在很长，再按内部逻辑块拆分。对文档，我按 Markdown 标题层级拆分，再根据段落上下文粘合。

下面是一个简化示例，用于把 Python 文件中每个顶层函数做成一个知识块：

def build_knowledge_blocks(filepath): content = Path(filepath).read_text(encoding="utf-8") tree = ast.parse(content) for node in tree.body: if isinstance(node, ast.FunctionDef): block_text = ast.get_source_segment(content, node) block_meta = { "file": filepath, "line_start": node.lineno, "type": "function", "name": node.name, } # 后续交给 embedding 和向量库 store_block(block_text, block_meta)

这里有个很重要的细节：同一文件里的函数可能依赖同一个全局状态，切得太碎会让 AI 失去上下文。针对情况，我会在函数块前面拼上类定义或文件头注释，让块里包含说明。

还有一种知识类型不适合按代码切块，就是前面提到的“口述史”。我把口述史按业务主题切成段落，每段配上主题标签，比如“优惠券兼容”“订单状态机”“对账风险”。这类长文本用普通字符切分器可能割断因果关系，最好让切块时保留“原始段落”，同时允许相邻块有 20% 左右重叠，减少信息断裂。

3.4 第四步：生成向量并写入记忆库

切块之后，接下来是 Embedding。选模型的时候要注意，不是越贵的模型越适合所有场景。老项目里通常有大量中文注释和中文术语，如果使用主要面向英文代码的模型，中文业务术语的效果可能一般。我实际对比后，中文场景推荐用 BGE-M3 这类对中英混合友好的开源模型；如果项目只有英文注释且预算充足，OpenAI 的 text-embedding-3-small 也不错。

数据规模不大时，个人和团队没有必要上分布式向量库。我第一版用的是 SQLite + sqlite-vss，后来因为要支持混合检索，迁移到了可在 Docker 里部署的 Qdrant。成本上都能接受，核心是别在工具选型上内耗。

写入向量库时的伪代码：

from qdrant_client import QdrantClient from qdrant_client.models import PointStruct, VectorParams, Distance client = QdrantClient(host="localhost", port=6333) client.recreate_collection( collection_name="project_knowledge", vectors_config=VectorParams(size=1024, distance=Distance.COSINE), ) points = [] for block in knowledge_blocks: vector = embed_model.encode(block["text"]) points.append(PointStruct( id=block["id"], vector=vector, payload={ "text": block["text"], "meta": block["meta"], }, )) client.upsert(collection_name="project_knowledge", points=points)

一个容易忽略的点：保存块正文时，不要把已经截断或摘要后的文本存进去，一定要保存完整原文。向量检索后，还要把完整原文交给模型，而不是让模型只看向量转换后的那个“数字”。

3.5 第五步：把记忆库封装成 AI 可调用的工具

有了向量库，下一步是让 AI Agent 能调用它。我习惯把检索能力包装成一个函数，然后用 Function Calling 暴露给模型。函数的描述写得越清楚，模型越知道什么时候该用它：

tools = [ { "type": "function", "function": { "name": "search_project_knowledge", "description": "搜索项目知识库，覆盖项目地图、代码模块、业务决策档案、核心函数注释。当用户询问模块结构、状态机、历史约定、接口影响范围时必须调用。", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "查询内容，建议使用业务术语，例如：订单状态迁移、优惠券叠加规则" } }, "required": ["query"] } } } ]

在 Agent 的 system prompt 里，我会强制加一句：如果检索结果不足以回答用户问题，必须明确说“项目知识库里没有这个信息”，不要编造。这不只是工程习惯，更是避免 AI 幻觉的关键规则。

当用到 Cursor 之外的 IDE 或需要构建公司内部工具时，可以把同一套检索服务做成 MCP Server。MCP（Model Context Protocol）目前已经成为不少 AI 编辑器外部工具的通用接口。实现一个 MCP server 本质上就是起一个本地 JSON-RPC 服务，把search_project_knowledge作为 tool 暴露出来，然后在 Cursor 的 MCP 配置里注册即可。这样老项目的知识库就能被所有支持 MCP 的客户端复用，不只是模型聊天窗口。

4. 把“记忆库”做扎实的六个工程细节

4.1 只索引高价值知识，别把垃圾都喂给 AI

第一次建库，很容易把所有文件全部向量化，想着“都放进来总没错”。实际操作后会发现，代码质量越差，噪音越多。有些生成代码、旧测试用例、实验性脚本几乎每次检索都会被误召回来干扰判断。

我后来把所有知识分 collection 存储，默认权重按这样区分：

• core_docs：项目地图、架构说明、ADR，权重最高。
• core_code：领域模型、service 层、状态机、对外接口代码块。
• historical_decisions：口述史、重要 commit 整理，仅在涉及“为什么”时使用。
• api_contracts：对外接口文档和参数含义。
• tests：关键测试文件，用来帮助理解预期行为。
• old_docs_legacy：已经废弃但还有历史参考价值的文档，默认不参与通用检索。

这样在日常检索时，只搜索前五个集合；“旧文档库”如果总是被模型抓去当当前真理，反而会误导回答。知识库不是数据仓库，它需要“当前状态”和“历史档案”两种语义状态，不要让它们混在一起。

4.2 给每块知识装上“溯源信息”

如果 AI 的回答不能给出“为什么这么判断”，这个回答的价值会大打折扣。所以我在每个知识块的元数据里至少保留文件路径、起始行号、最后修改时间、来源类型、版本标签。这样模型可以给出类似“这个逻辑来自 order_service.py#L123-L167，最后一次修改是 2024-03-14，提交记录为 fix #884”的引用。

有溯源的好处还在于，人工 review 时能快速验证 AI 说的对不对。做工程的人都清楚，直接信 AI 的结论是危险的，但如果能把审查重点从“搜索代码”缩小到“看引用块”，效率会高很多。

4.3 向量检索靠不住，要混合检索

向量检索能理解“订单取消以后如何退款”这种语义问题，但对 “PENDING_PAY” 这种精确符号名往往不敏感。老项目里最多的恰恰是这种私有枚举值、错误码、类名、函数名。如果只依赖向量检索，看似检索到了相邻概念，实际上却漏了精确答案。

我现在的方案是混合检索：同时跑向量检索和全文检索，再把结果按一定规则融合。全文检索不必大动干戈上 Elasticsearch，用 SQLite FTS5 或者向量库自带的 sparse 索引基本足够。如果 query 里面有全大写的枚举值或驼峰类名，我会提高全文检索结果的权重；如果 query 是自然语言句子，提高向量检索结果权重。这个“规则”不需要写得太复杂，跑一段时间后根据具体问题调参即可。

4.4 给 AI 一张全局地图，而不是只给碎片

每一次从外部记忆里捞出来的只是有限几个碎片。AI 如果只看到碎片，容易“只见树木不见森林”。所以我在 system prompt 里固定注入一份压缩过的项目地图，核心信息包括：有哪些模块、各模块负责什么、模块依赖关系、核心状态机、几个关键业务术语表。地图大概几百 token，不会拖慢响应。

这个设计的作用是让 AI 先建立起坐标，再有目的地去检索细节。比如当用户问“改动会员等级会影响哪些模块”，AI 看到地图里 member-service 被 billing-service 依赖，就知道先去搜会员权益相关调用点，而不是先去读 gateway 路由代码。没有地图，它只是一个没有方向感的检索者，容易在知识库里翻错地方。

4.5 代码一变，记忆增量更新

老项目不是静止的，知识库也不能建完就不管。一个很常见的坑是：知识库里记录的还是三年前的状态，而代码已经改版两次。模型面对这种冲突，若默认使用知识库旧内容，就会给出错误结论。

我建议把知识库更新接入 CI。当 PR merge 到主干分支时，根据 git diff 识别被修改的文件，只对这些文件重新执行切块和向量化，并把旧块从库里删除或标记过期。更新策略可以简化成“删除原文件对应的所有块，再插入新块”，避免旧版本残留。

对“口述史”和“决策档案”这类不容易自动更新的内容，我设了一个季度 review 的机制，由团队核心同事检查一遍是否还有效。业务规则类的知识如果失效，就要立刻打上“已过期”标签，否则未来还是会被检索出来。

4.6 把“好的问答”手工沉淀回库

运行一段时间后，知识库最好的内容来源其实是你自己的问答实践。团队成员问 AI“这个接口能不能在 5 分钟内调用两次”，AI 通过检索代码给出了准确回答；又或者 AI 第一次回答错了，有人纠正了它。这类问答里有大量黑话和上下文，是静态文档里找不到的。我会把这类高质量问答沉淀成 Q/A 块，放回知识库，供后续检索。这样知识库会越长越“懂”这个项目，像一个慢慢熟悉公司黑话的同事。

我通常每周花半小时看一版对话日志，挑出五条有代表性的问答，清洗掉敏感内容后加入知识库。不用贪多，每条都要保证正确性，因为一条错误沉淀比没有更糟。

5. 现实效果与踩坑排查

5.1 这样改造后的真实效果

我在一个业务流程很重的老项目上试了快两个月，直观感受是新人接手速度明显加快。过去一个刚加入团队的同事要花一个月才能搞懂订单状态机里那些拐弯逻辑，现在用一个内部聊天机器人直接问“已支付订单为什么还能被用户取消”，得到回答后面还附带了代码路径和历史 commit 引用，半小时就能定位到关键文件。

回答质量方面，改造前直接让通用 AI 问老项目问题，准确率大概只有一半，而且经常给出模棱两可的话。改造后，针对预定范围内的典型问题，准确率能稳定到八成以上。无法回答时会明确说“知识库没有”，不会硬着头皮编。这个提升来自项目地图、混合检索、人工反馈三件事，不全是模型的功劳。

5.2 高频问题排查速查表

很多朋友照着文章搭完，会遇到一些典型问题。我整理成表格方便直接查：

5.3 一次典型的翻车：旧知识污染

我自己踩过最大的坑，是知识库索引了两年前的旧方案。当时有一个优惠规则，系统曾经允许多种优惠券叠加，后来因为资损整改，改成互斥。通用 AI 模型在检索时找到了旧规则块，自信地回答“系统支持多种优惠叠加”，还附上了一个已经废弃的类路径。我差点信了，最后对账脚本发现对不上，才追出问题源头。

这次翻车让我定了两条规矩：

• 所有代码知识块从代码生成时，必须读取当前分支版本；历史版本要放到单独“版本档案”集合，默认不能被检索到。
• 在 prompt 里告诉 AI：如果知识库结果和代码最新实现冲突，以代码库当前代码为准，并提醒用户可能存在陈旧文档。模型不知道“冲突”，所以需要我们把“哪种信息来源更可信”这个判断规则写清楚。

这种情况下，“外部记忆”不只是一个技术系统，它还需要治理规则。做 AI 辅助老项目，与其把精力花在调模型,不如多花时间在知识新鲜度上，收益明显高得多。

6. 收尾：一些轻量建议，如果你现在就要做

如果你正打算在自己团队里做类似的事，我的建议很直接：别想着一次做成大而全的平台。先选一个刚入职的研发作为“检验标杆”，选他最常问的五个问题，用这套项目地图加检索的方案把五个问题做通、做准，再逐步扩大知识覆盖面。小步快跑比等到把整个代码库清洗干净再上线现实得多。

我最初以为最关键的是 Embedding 模型或向量库选型，后来发现根本不是。最大的难点在于把隐性的业务历史变成文字，以及让知识库保持“当前状态”而不是垃圾场。只要这两件事做到位，哪怕你用的向量库很朴素，效果都不会差。后续我还在尝试把这条路和自动化测试结合起来，比如让 AI 根据外部记忆自动推断一次代码变更会影响哪些测试用例，减少回归遗漏。老项目不是一座没有地图的城市，项目探测就是画地形图的人，AI 外部记忆则让这张图不只印在纸上，还能随叫随到。最后想分享的小技巧是：从老同事口中问出来的“那个坑”，记得写完一定请对方复核一遍，否则 AI 会在你错误转述的基础上，把错误放大成一个看起来很有道理的结论。