企业官网建设流程全解析

• 文档
• 教程

在修改一个陌生项目之前，最关键的准备工作不是猜，而是搞清楚"这个行为到底在哪里实现、如何验证"。VS Code 的 AI Agent 可以帮助你找到入口点、跨文件追踪调用链、定位相关测试，但它的解释应当被当作核查的起点，而不是对项目的权威描述。本篇指南将带你以"只读探索"的方式，用 Agent 在现有仓库中调查一个具体行为，最终产出一张相关代码地图、带源码出处的支撑引用，以及一份改动前必须澄清的问题清单。

本文以仓库中的官方指南 docs/agents/guides/explore-a-codebase.md 为主体骨架，并结合 docs/agents/run/chat-view.md、docs/agents/run/security.md、docs/agents/run/approvals.md 等文档与仓库目录结构，为你还原一套可复制的"探索—验证—记录"方法论。

为什么在改动前先探索代码库

对一个不熟悉的项目直接动手改代码，最常见的失败方式是"改动与既有架构脱节"：入口点找错、行为实现分散在多个文件、测试覆盖了和你假设完全不同的语义。Agent 的价值在于把这三件事快速摊开：

• 定位入口点（路由、命令、UI 元素对应的处理函数）；
• 跨文件跟随调用链，理解数据从输入到输出的完整路径；
• 找到相关测试，用测试断言来校验 Agent 的解释是否与代码事实一致。

正如 docs/agents/guides/overview.md 中所说，探索代码库（Explore a codebase）是"不编辑文件、仅追踪行为并根据源码引用验证解释"，适合用自己的仓库作为实战对象。请把 Agent 的回答当作待核查的假设，逐条对照源码，而不是照单全收。

前置准备

开始探索前，完成以下三件事：

1. 配置 Copilot：参照 docs/setup/copilot.md 完成 VS Code 中 Copilot 的初始化设置。
2. 打开目标仓库：在 VS Code 中打开你想探索的仓库作为工作区。工作区是 Agent 的文件访问边界，也是会话上下文的基础。
3. 选定一个探索问题：选择一个具体的行为问题，例如"某个请求是如何被授权的"、"某个表单是如何保存数据的"、"某个 API 响应是在哪里组装出来的"。

[!IMPORTANT] 在信任或运行不熟悉的代码之前，请先阅读 docs/agents/run/security.md 中的安全指南。探索阶段不需要安装依赖，也不需要运行应用——纯静态的源码阅读足够回答"行为在哪里实现"这类问题。

从安全模型的底层看，这条"先看文档再行动"的建议与 VS Code 的信任边界设计是一致的：在受限模式（Restricted Mode）下打开未受信任的项目会直接禁用 Agent（见 docs/agents/run/security.md）。因此，探索应始终发生在受信任的工作区内，并遵循最小权限原则。

第 1 步：定义问题（限定探索范围）

探索的第一步不是让 Agent 解释整个仓库，而是只问一个行为。有边界的问题更容易核查其解释是否完整——如果范围太大，你根本无法判断它是否漏掉了关键路径。

操作步骤如下：

1. 打开 Chat view（在标题栏选择Chat菜单 →Open Chat，或使用快捷键kb(workbench.action.chat.open)，也可在命令行运行code chat），开始一个新会话。
2. 将会话目标（Session Target）选择为Copilot，角色（Agent）选择为Agent，并保持手动权限（Manual permissions）。
3. 用自然语言描述你想理解的行为。如果你知道入口点（如某个路由、命令或 UI 元素），务必写进提示词。

以下提示词可直接改造后用于你项目中的某个端点：

Explain how a request to GET /issues becomes a paginated response in this repository. Start with the route registration and follow the implementation to the returned response. Do not edit files, install dependencies, start services, or run project code. Cite the files and symbols that support your explanation. Separate facts you verified from assumptions and open questions.

[!IMPORTANT] 提示词中说"不要编辑或运行代码"只是一条指令，不是权限边界。你需要自行审查会话的权限设置和工具活动记录。不要想当然地认为选择了手动权限，就要求每一次文件编辑都必须经过你批准——手动权限只是采用你配置的审批规则，具体哪些操作需要确认由审批设置决定。

补充：会话控制项的含义

根据 docs/agents/run/chat-view.md，Chat view 底部输入区包含四个关键控制项：Session Target（会话目标，决定在本地、远程还是云端运行）、Agent（角色）、Language model（语言模型）、Permissions（权限级别）。首次编码任务推荐Copilot + Agent + Auto + Manual permissions的组合（见 docs/agents/quickstart.md）。在定义问题阶段，把权限保持为 Manual permissions，能让每一步工具调用都在你的监督之下。

第 2 步：定位相关代码（先要一张"小地图"）

问题定义好之后，不要急着让 Agent 深入实现细节，先向它要一张与答案相关部件的小地图：

Identify the entry point, implementation modules, configuration, and tests relevant to this request. Explain each file's role and why it belongs in the investigation. Do not summarize unrelated directories or read secret values.

一边读回答，一边打开它引用的文件，逐项核对：

• 路由或其它入口点确实注册在你正在调查的应用中；
• 引用的函数存在于当前检出（checkout）的代码里；
• 该实现是生效代码，而不是未使用的示例、生成产物或测试夹具（fixture）；
• 任何配置断言都指名了配置来源，且没有暴露凭据。

多应用仓库与上下文管理

如果仓库包含多个应用或同一功能的多套实现，务必指明你说的是哪一套。与其让 Agent 重新搜索整个仓库，不如直接把相关文件添加为聊天上下文。VS Code 支持用#提及（#-mention）文件、文件夹、符号，或在 Chat view 的Add Context选择器中添加Files & Folders与Symbols；如果确认要使用整个代码库作为上下文，可以直接在提示词中加入#codebase（见 docs/chat/copilot-chat-context.md）。显式添加上下文，能确保 Agent 在后续追问中始终聚焦在你指定的文件上，而不是反复全库检索。

第 3 步：沿一条具体路径追踪（验证连接关系）

地图就位后，选一个具体的输入，从入口点一路追踪到结果。把示例值替换成你的应用真实支持的请求：

Trace GET /issues?page=2 through the files you identified. Show where the page parameter is parsed and validated, how records are selected, and how the response is constructed. For each step, cite the relevant symbol and explain the input and output. Include error paths and any database or external-service boundary. If a dependency's implementation is unavailable, identify what you cannot verify. Do not edit files or execute project code.

追踪时请检查连接关系，而不只是单个函数：

• 调用方是否真的传入了 Agent 所描述的那些值？
• 返回值是否真的到达了响应组装处？
• 错误处理是否沿着 Agent 声称的路径流转？

当解释跳过某一步时，用聚焦的追问把它逼出来：

You identified the pagination helper, but have not shown how the route calls it. Find that call site and verify which default page value it receives. If you cannot find a connection, revise the explanation.

这类追问的设计思路是：让 Agent 出示调用点（call site）证据。如果它找不到连接，就要求它修正解释——这正是把"假设"变成"验证过的事实"的关键一步。

第 4 步：用测试校验解释（证据比对）

测试是行为的"可执行规格"。它们既能给出预期行为的示例，也能暴露实现摘要遗漏的边界情况：

Find tests for the request path we traced. List the inputs and expected results they check, with source references. Identify boundary cases that are not covered. Do not claim that the tests pass unless they have been run in this environment.

拿到测试清单后：

• 把断言与解释、项目文档逐条比对。测试名称本身不是"该测试确实检查了这个行为"的证据——必须看断言内容。
• 不要因为"Agent 说测试通过"就相信测试通过。提示词中特意要求：除非测试已在本环境中真正运行过，否则不得声称其通过。

如果确实需要运行时确认，请遵循以下纪律：

1. 先查看项目的搭建说明和它建议的测试命令；
2. 只运行你信任的仓库中的代码，并使用合适的本地测试资源；
3. 记录实际结果以及任何环境限制；
4. 不可用的服务、未执行的测试，都不能当作"通过的检查"来对待。

这与仓库中 docs/agents/guides/overview.md 对其他工作流的验证要求一脉相承——"完成消息不是功能生效的证据"，测试输出才是。

第 5 步：记录已验证的结论（为第一次改动做准备）

探索的最后一步，是让 Agent 产出一份精炼的已验证摘要，供你规划第一次改动时使用：

Summarize what we verified about this behavior. Include the entry point, the implementation path, relevant tests and commands, and unresolved questions. Link each important claim to its source. Distinguish tests we inspected from tests we ran. Do not create or edit files.

摘要产出后，必须由你自己复查。你应该能够做到：

• 定位到实现位置；
• 解释一条成功路径和一条错误/边界路径；
• 说明你打算如何验证一个改动。

如果某个重要连接仍然存疑，请在编辑之前向维护者求证或继续调查。把验证过的摘要随任务保留；只有经过复查，才把稳定的项目知识沉淀到团队共享文档中——不要直接保存一份未经核查的 Agent 生成的架构描述。

安全与权限：探索工作流背后的底层支撑

"只读探索 + 手动权限"的组合，是仓库安全模型中推荐基线的具体落地。结合 docs/agents/run/security.md 与 docs/agents/run/approvals.md，探索时你实际依赖的防护层包括：

两个需要特别警惕的事实：

1. 探索阶段的"不要编辑"只是一条指令。想让这条指令真正生效，靠的是权限设置与工具活动审查，而不是提示词本身（见 docs/agents/run/approvals.md）。
2. 手动权限并不等于"每个操作都要批准"。哪些工具可被自动批准由chat.tools.eligibleForAutoApproval决定；如果你希望某些工具（如execute/runInTerminal、web/fetch）永远要求人工确认，可以把对应条目显式设为false。

因此，在探索一个不熟悉的仓库时，最稳妥的组合是：受信任的工作区 + Manual permissions + 工作区限定的文件访问 + 不运行项目代码。这样既保留了 Agent 的检索能力，又把"读代码"与"改代码/执行代码"彻底隔离开。

从探索到动手：衔接下一步

完成一次成功的代码库探索之后，你手上已经有：入口点、实现路径、相关测试与命令、未解决问题清单。接下来就可以带着这份已验证的地图进入实际改动环节：

• 为现有项目添加功能：基于探索结论，走"评审计划 → 按批准范围实现 → 验证"的完整流程；
• 在不改变行为的前提下重构：利用已确认的调用关系与测试基线，分步安全重构；
• 需要更多可改造的提示词模板时，可参考 提示词示例；关于 Agent 使用的通用纪律，见 使用 AI 的最佳实践。

这套"定义问题 → 定位代码 → 追踪路径 → 测试校验 → 记录结论"的工作流，把 Agent 从"看起来能解释代码"升级为"每一步都有源码出处的可核查工具"。下次接手陌生仓库时，先用一个下午走完这条流程，再决定是否动手——你会发现自己改代码时的底气完全不同。

• 文档
• 教程