企业官网建设流程全解析

1. 先承认一个事实：AI Agent 读代码的方式，从根上就不对

1.1 让 AI 整文件硬啃，先烧掉的就是 token

我先说个真实场景。前几天在 Cursor 里让 AI 帮我改一个日志模块的格式化函数，那个文件大概 600 行。我盯着状态栏看它一步步"扫描文件"—先是 import 区，再是几个工具函数，然后一路读到底。等它终于开口说话的时候，我已经能猜到这次的 token 账单不会好看。

很多人的第一反应是：token 贵就贵嘛，反正现在模型便宜。这话对了一半。模型推理成本确实在降，但别忘了 AI 编程 Agent 的使用方式不是"问一次答一次"，而是多轮对话 + 自动工具调用 + 上下文持续累积。你让 Agent 改一个 bug，它会先读文件、再搜引用、再改代码、再跑测试、再根据报错读更多文件。每一轮它都要把之前读过的内容重新放进上下文里参与计算。一个 1000 行的文件按 3 到 4 万 token 算，一个跨文件的任务跑下来，几十万 token 就没了。这不是夸张，是我在中等规模 TypeScript 项目上反复实测出来的数字。

但 token 消耗其实还不是最要命的，它只是你最先感知到的那个痛点，真正的问题在下面。

1.2 更隐蔽的坑：上下文被无关代码"稀释"后，判断力直线下降

我一直觉得，AI 编程 Agent 目前最被低估的问题不是"读得不够多"，而是"读得太多太杂"。你可以把模型的上下文理解成一张注意力分配表：你塞进去的内容越多，模型分配到每个具体信息上的注意力就越少。这就像你在一个嘈杂的集市里找人问路，周围声音越大，你越听不清对面那句关键的话。

整文件硬啃带来的典型症状有三个：

• 改 A 函数带出 B 函数的修改。AI 读完了整个文件，发现 B 函数的写法"风格不一致"，顺手就给你改了。它觉得自己是在优化，实际是在制造无关 diff。
• 变量命名风格漂移。读了一堆风格统一的代码之后，AI 容易把不同模块的命名习惯混在一起，新写的代码一会儿用小驼峰，一会儿用下划线。
• 无中生有的"顺带修复"。AI 在无关代码里发现了一个潜在问题，于是自作主张加了一段错误处理。看起来是在帮你，但这种完全没有需求依据的改动，在 code review 时最让人头疼。

整文件读的另一个致命问题是：AI 读完整个文件，仍然可能找不到关键逻辑。因为它读到的是一堆平铺的代码文本，函数之间的调用关系、哪个函数是入口、哪个函数是关键实现，它全靠自己"猜"。你给它塞了 600 行代码，它真正需要的可能只在一个 20 行的函数里，但找到那 20 行的过程，消耗的不是 token，是模型的判断精度。

1.3 我踩过的真实例子：幻觉式重构比不做还危险

分享一个让我下定决心搞 ast-outline 的直接导火索。当时我在改一个内部工具里的日期格式化函数，需求很简单：把YYYY-MM-DD的格式输出改成YYYY/MM/DD，顺带支持一个时区参数。文件里有 600 多行，大部分是跟格式化无关的配置加载逻辑、缓存逻辑和几个废弃接口的兼容代码。

AI 读完整文件之后，给了我一个"惊喜"：它说"我注意到当前的配置初始化方式在时区参数传入时可能不兼容，建议一并重构"。然后它不仅改了格式化函数，还把配置初始化的调用链给重写了，理由是"这样更安全"。

我当场就愣住了。那个配置初始化和日期格式化是两个完全独立的模块，之间只有一个参数传递关系，AI 却因为在上下文里看到了配置代码，产生了过度联想。这种"幻觉式重构"在整文件读取的模式下几乎无法避免，因为模型分不清哪些代码和当前任务有关，哪些只是它读到的背景信息。

那次之后我做了一个决定：不再让 AI 直接整读文件，而是先给它一份代码结构的"地图"，让它按图索骥。这就是 ast-outline 这个项目的起点。

2. ast-outline 的核心逻辑：把每个文件变成一张"函数地图"

2.1 AST 到底是什么？把代码拆成编译器眼中的结构块

要理解 ast-outline，先得知道 AST 是什么。AST 全称是 Abstract Syntax Tree，抽象语法树。你可以把它理解成编译器眼里的"施工图纸"。

我们写代码的时候，看到的是缩进、括号、命名这些"人眼友好"的东西。但编译器不一样，它会把代码解析成一棵结构化的树：最外层是整个文件，往下一层是 import 声明、函数定义、类定义、变量声明，再往下一层是函数里的参数列表、函数体的各个语句、语句里的表达式。每一个语法元素都有明确的节点和层级关系。

ast-outline 做的事情，就是从这棵 AST 里抽取出一份"目录索引"——就像你不会为了知道一栋楼有几个房间就去读整本施工图纸，而是先看楼层平面图和房间分布表。这份目录索引不需要包含完整的代码实现，只需要告诉 AI 这些信息：

• 这个文件里有哪些函数、类、常量
• 每个函数/类的精确位置（从第几行到第几行）
• 函数签名（函数名、参数、返回值）
• 关键的修饰信息（是否导出、是否异步、是否有装饰器）
• 函数之间的调用关系（谁调用了谁）

有了这份索引，AI 在遇到一个文件时就不需要整读，它只需要先读"地图"，就能对文件的整体结构形成认知。

2.2 outline 包含哪些信息：签名、依赖、引用、调用关系

我用 JSON 文件来组织 outline 数据。每个源文件对应一个 outline 条目，里面包含结构化的符号索引。这里是我实际使用的格式示例，字段设计直接对应了 Agent 决策时的信息需求：

{ "file": "src/logger/formatter.ts", "language": "typescript", "symbols": [ { "name": "formatLogEntry", "type": "function", "signature": "(entry: LogEntry, options: FormatOptions) => string", "lineStart": 42, "lineEnd": 78, "exported": true, "async": false, "calls": [ {"name": "stringifyMeta", "targetFile": "src/logger/meta.ts", "line": 55} ] }, { "name": "stringifyMeta", "type": "function", "signature": "(meta: Record<string, unknown>) => string", "lineStart": 15, "lineEnd": 30, "exported": false, "async": false, "calls": [] }, { "name": "DEFAULT_OPTIONS", "type": "const", "lineStart": 8, "lineEnd": 14, "exported": true } ] }

很多人第一次看到这种结构会觉得，这不就是个代码索引吗？对，但关键差别在于一个"calls"字段。它记录了每个函数调用了哪些外部函数，以及被调用函数位于哪个文件的哪一行。这正是 Agent 按需导航的核心——它正在读formatLogEntry，发现里面调用了stringifyMeta，通过 outline 立刻知道这个函数在src/logger/meta.ts的第 15 行。它可以直接跳过去只读那一个函数，而不是把整个meta.ts文件读一遍。

这个"调用关系索引"是我认为 ast-outline 区别于普通代码大纲的关键。普通的大纲只是"目录"，而带调用关系的 outline 是一张"导航图"。

2.3 按需读取的完整链路：Agent 先看地图，再决定读哪段

ast-outline 设计的读取链路分为四步，对应 AI Agent 处理一个任务时的完整决策路径：

第一步：拿到文件列表后，先读 outline 索引，不读任何函数体。

这一步的目标是建立全局认知。AI 看到一个文件有 600 行，但通过 outline 它知道这 600 行由哪些部分组成：3 个导出函数、2 个内部工具函数、1 个配置常量。它不需要知道这些函数的实现细节，只需要知道"这里有什么"。

第二步：根据任务描述，匹配相关的函数签名。

这一步是"按需"的关键。任务说"改日期格式输出和时间处理"，Agent 对照签名列表，发现formatLogEntry接受一个FormatOptions参数，里面可能有dateFormat相关配置，于是它决定优先展开这个函数。展开的方式是读取该函数起始行到结束行的代码块。

第三步：在目标函数内部，如果发现依赖了外部符号，通过 calls 字段跳转到对应文件的对应行，只读取目标函数。

这一步处理的是跨文件依赖。Agent 读取formatLogEntry的实现后发现它调用了stringifyMeta，于是通过 outline 中的targetFile和line字段跳到src/logger/meta.ts的文件偏移位置，只读取第 15 到 30 行的内容。整个过程精确、可控、不产生多余上下文。

第四步：修改完成后，通过 outline 快速定位依赖方做影响分析。

Agent 改完stringifyMeta的返回值结构后，需要知道谁在调用它，以及影响面有多大。它再次通过 outline 的全局索引反查所有调用方，而不是逐个打开文件去 grep。

这套链路跑通之后，AI 的行为模式从"把整个文件读进来再说"变成了"先看地图、按图索骥、精准展开"。这和人读代码的习惯是一致的——我们接手一个陌生文件时，也不会从头读到尾，而是先看有没有目录结构，找到相关的函数再深入。

3. 从零接入 ast-outline 的实操记录

3.1 安装与初始化：三种接入姿势，按需选择

我实际用的 ast-outline 版本以 CLI 为主，配合编辑器插件和 MCP 工具集成使用。安装方式很简单：

# 全局安装 npm install -g ast-outline # 或者作为项目依赖安装 npm install --save-dev ast-outline

项目初始化时，在根目录生成配置文件：

ast-outline init

这会生成一个.ast-outline.json配置文件，主要控制索引的语言范围、生成路径、忽略规则等。我常用的配置长这样：

{ "rootDir": "src", "include": ["**/*.{ts,tsx,js,jsx}"], "exclude": ["**/node_modules/**", "**/dist/**", "**/test/**"], "outputDir": ".ast-outline", "languages": ["typescript", "javascript"], "maxFileSize": 200000 }

需要注意maxFileSize这个字段，它限制索引生成的最大文件行数。超过这个阈值的文件会全量索引（但不会截断），目的是防止超大文件拉低生成速度。exclude里我强烈建议把测试目录排除掉，因为大多数 Agent 任务针对的是生产代码，测试文件的符号会干扰匹配精度，还会浪费首次生成的时间。

如果你用的是编辑器场景，还有人写了 VS Code 插件，右键文件就能在侧边栏看到 outline 树形结构，点击任意符号直接跳转。不过我主力用的是 CLI 输出，因为我的工作流大部分在命令行环境里完成。

3.2 生成 outline 的完整命令和输出解析

初始化配置之后，生成索引只需要一条命令：

ast-outline build

默认会把索引写入.ast-outline/index.json，同时生成一个轻量级的.ast-outline/index.min.json（去掉了函数体摘要，只保留签名和调用关系，体积大概是完整版的三分之一）。如果你是给 AI Agent 用的，我建议直接用 min 版，因为 Agent 只需要决策信息，函数体内容它可以通过后续的精准读取获取。

完整索引文件的顶层结构长这样：

{ "version": 1, "projectRoot": "/home/user/my-project", "generatedAt": "2025-01-15T22:10:00.000Z", "files": [...], "symbols": { "formatLogEntry": [ {"file": "src/logger/formatter.ts", "line": 42} ], "stringifyMeta": [ {"file": "src/logger/meta.ts", "line": 15} ] } }

顶层有一个symbols的字段，它是全符号反向索引——所有符号名映射到所有出现位置。这个设计是为了支持跨文件搜索。当 Agent 要找出"谁在调用stringifyMeta"时，直接查这个反向索引就能立刻得到所有引用点，不需要在代码库里做全文搜索。

每次改完代码后，需要同步更新索引：

ast-outline build --watch

我习惯开着 watch 模式，它会监听配置目录下的文件变化，改动后自动重新生成索引。在大型项目上增量更新大概是每次 100 到 300 毫秒，体感上是无感知的。

3.3 让 Agent 工作流真正用起来：prompt 组织思路

工具搭好了，但 Agent 不会自动用 outline，你需要通过系统指令或工作流定义引导它。我整理了一段可以直接放进 Agent 系统提示的指令模板：

在修改代码之前，必须遵循以下读取流程： 1. 先查看项目根目录下的 .ast-outline/index.min.json 文件。 2. 根据任务关键词，在索引中匹配相关的文件名和符号名。 3. 通过 lineStart 和 lineEnd 字段，只读取目标函数对应的代码行。 4. 如果目标函数调用了外部函数，通过 calls 字段中的目标文件和行号，直接跳转到对应函数读取。 5. 在修改前，通过 symbols 反向索引查找所有引用方，确认影响范围。 禁止在未查看 outline 索引的情况下直接读取完整的源文件。

第一次接的时候，我发现 Agent 会有"惯性"，还是习惯直接读整个文件。解决方式是在项目根目录加一个AGENTS.md或者工作流描述文件，把这些指令固化进去。现在的 Agent 基本都能自动遵守项目级的工作流约定。

另外一个实用小技巧：在生成索引时，把函数体里的 docstring 或 JSDoc 注释摘要也一并提取出来。这样 Agent 在读 outline 的时候就能获取更多语义信息，很多简单任务（比如"这个函数的返回格式是什么"）直接看 outline 就能回答，连函数体都不需要展开，token 还能再省一截。

4. 同一任务对比：整文件读 vs 按 outline 读，差距比想象中大

4.1 测试任务设计

为了验证 ast-outline 的实际收益，我在自己的项目上做了一组对照测试。项目是一个中等规模的 TypeScript 服务端应用，约 80 个源文件，每个文件平均 300 行。测试任务设计成实际开发中很常见的需求：

"给formatLogEntry函数增加一个时区参数timezone，默认值为UTC，并在输出中加入时区标识。注意不要影响现有调用方。"

这个任务涉及三层改动：

• src/logger/formatter.ts中的formatLogEntry函数签名变化
• src/logger/meta.ts中的stringifyMeta被调用时接收新参数
• src/logger/index.ts中所有对外导出的调用入口需要透传参数

任务天然地覆盖了跨文件、签名变更、影响面分析三个典型难点。对照组分别在两个场景下让同一个 Agent 执行：

• 场景 A：Agent 直接整文件读取（无 outline）
• 场景 B：Agent 按 ast-outline 流程读取

每个场景跑 5 轮，统计中位数的数据。

4.2 三个维度的结果对比

我把关键数据整理成了表格，供参考：

token 消耗的差距是 5 倍左右，这符合预期。但比 token 更关键的是首次修改正确率：整文件读时，5 轮里只有 3 轮一次通过，另外 2 轮要么引入了无关改动，要么因为"发现"了所谓的潜在问题而改错了范围。用 outline 的 5 轮里，4 轮一次通过，只有 1 轮因为时区参数没有正确传递到嵌套调用而需要二次修复。

耗时差距更直观。整文件读的 Agent 在"看代码"上花了大量时间，真正写改动的时间很短。而 outline 模式的 Agent 大部分时间花在精准定位和影响面分析上，整体节奏快得多。这两种模式在用户体感上的差异，远比数字显示的更大——一个是你等着它慢慢看完一本书再动笔，另一个是它先翻目录、直接翻到相关页码就开写了。

4.3 为什么 outline 能带来正确率提升

我仔细复盘了 5 轮测试，总结出 outline 提升正确率的三个原因：

第一，决策信息密度更高。整文件读 600 行代码，Agent 真正有效的信息集中在 30 行目标函数里，其余 570 行都是干扰。outline 模式先给签名和调用关系，Agent 直接锁定目标，决策时上下文里全是相关信息，模型的推理精度自然上去。

第二，跨文件影响面分析更可靠。场景 A 的 Agent 在分析调用方时，靠的是全文搜索和猜。它搜到formatLogEntry出现在index.ts里，但不确定是导入还是调用，更不确定有没有间接引用。而 outline 的反向索引直接给出精确调用链，Agent 可以做完备的影响面分析再动手。实测中，场景 A 的 2 轮失败里有一轮就是漏掉了index.ts的透传。

第三，符合模型"规划-执行"的工作方式。现在的 Agent 模型都强调先规划后执行。outline 本身就是一份规划蓝图，Agent 先"读了地图"形成了整体认知，然后按计划逐步展开和修改。整文件读则等于让它在执行前先囫囵吞枣地看一遍全书，规划质量完全取决于它的临时状态。

5. 哪些场景不适合 outline？我趟过的边界

5.1 动态语言和元编程：AST 只能看到字面结构

讲完收益，必须说说边界。ast-outline 的根基是 AST 静态解析，所以它天然有盲区：一切运行时才能确定的调用关系，AST 都看不到。

我实际遇到的例子是 Python 项目里的动态派发：

def dispatch(action_name, payload): handler = getattr(handlers_module, action_name) return handler(payload)

这段代码通过getattr在运行时动态获取函数引用，AST 解析时只能看到一个字符串action_name，无法知道它实际会调用哪个函数。在 outline 里，这个动态调用点不会出现在任何函数的 calls 字段中。同理，JavaScript 里常见的装饰器模式、Proxy 拦截、事件总线机制，AST 都只能看到字面调用，看不到运行时真正的函数连接。

碰到这种情况，我的处理原则是：AST 负责定位，动态调用交给运行时推断。在 Java 里我会结合实际测试代码（写在单元测试里的实际调用路径）来补全动态关系；Python 里则在索引生成后跑一遍测试代码，把实际执行过的调用链手动灌回 outline 的补充映射表里。

5.2 跨模块全局修改：outline 定位，上下文仍需整读

outline 擅长解决"某个函数在哪个文件、它调用了谁"这种定位问题。但当你面对的是一个涉及十几个文件的全局变更需求，比如迁移一个核心状态管理库，光靠 outline 完全不够。

原因是这种任务的难点不在"找"而在"理解"：你需要理解数据流是怎么在整个系统里流转的、每个中间环节做了哪些状态转换、这些转换之间有什么相互约束。outline 的签名索引只能告诉你"有哪些函数、参数是什么样"，但函数体之间的语义联系、状态流转的隐含顺序，静态索引表达不出来。

这是我在实际项目中采用的分层策略：

• 第一层：用 outline 全局扫描，把所有涉及变更的文件和符号找出来，圈定影响面。
• 第二层：对核心路径上的几个文件做整文件读取（一般是入口文件 + 状态管理核心 + 最下游输出），理解数据流的完整语义。
• 第三层：对边缘文件只读关键函数，通过 outline 返回的精确行号精准展开。

这种组合模式比全量整读省了大概 60% 的上下文，同时在理解深度上有保障。

5.3 什么情况下我仍然选择整文件读

最后一个边界，也是我最有体感的一个。不是所有文件都适合用 outline 精确展开，以下三种情况我选择整读，不走"地图导航"：

文件小于 150 行。一个 80 行的文件，outline 本身可能占 20 行 JSON，Agent 读完索引再跳转，那 20 行开销就是纯浪费。实际测试中，遍历 80 行文件的开销小于解析 outline 加跳转的开销，整读反而更快。

需要理解文件风格统一性。比如做代码 review 或重构时，你希望 Agent 理解整个文件的命名风格、错误处理模式、注释习惯，以便保持修改的一致性。这时候只读几个函数反而会导致细节丢失。

高度耦合的"上帝文件"。有些文件里函数之间互相调用、共享大量状态，单读一个函数根本理解不了它的行为。这种文件在 AST 上也能生成 outline，但每个函数单独拎出来都是残缺的，AI 读了会更困惑。碰到这种文件我一般直接整读，同时接受它带来的高 token 消耗——这是代码质量的债，不是工具能解决的。

我的经验阈值表格如下：

最后补一个常用小技巧：ast-outline 支持在构建时指定--strip-comments，把注释从索引中移除，仅保留签名、调用关系和符号位置。很多人会犹豫要不要保留注释里的函数说明，我建议在 Agent 场景下果断移除——因为 JSDoc 里的描述往往和实际实现脱节，AI 如果同时读到注释和函数体，两套信息不一致时容易产生纠结，反而影响效率。把注释去掉，只保留代码事实，Agent 的判断更干净。这个细节是我在多次对比测试后发现的，实测能让正确率再提几个百分点。

如果你也在被 AI 编程 Agent 的 token 消耗和低质量修改困扰，建议从明天开始就给项目加上 outline 索引层。别指望一次性把所有文件都索引得完美，先跑通一个目录、一个任务，感受一下"按图索骥"和"整文件硬啃"的差异，你大概率会回不去的。