用 VS Code Agent 探索代码库：行为定位、调用链追踪与源码验证的完整工作流

文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载在修改一个陌生项目之前最关键的准备工作不是猜而是搞清楚这个行为到底在哪里实现、如何验证。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 的回答当作待核查的假设逐条对照源码而不是照单全收。前置准备开始探索前完成以下三件事配置 Copilot参照 docs/setup/copilot.md 完成 VS Code 中 Copilot 的初始化设置。打开目标仓库在 VS Code 中打开你想探索的仓库作为工作区。工作区是 Agent 的文件访问边界也是会话上下文的基础。选定一个探索问题选择一个具体的行为问题例如某个请求是如何被授权的、某个表单是如何保存数据的、某个 API 响应是在哪里组装出来的。[!IMPORTANT] 在信任或运行不熟悉的代码之前请先阅读 docs/agents/run/security.md 中的安全指南。探索阶段不需要安装依赖也不需要运行应用——纯静态的源码阅读足够回答行为在哪里实现这类问题。从安全模型的底层看这条先看文档再行动的建议与 VS Code 的信任边界设计是一致的在受限模式Restricted Mode下打开未受信任的项目会直接禁用 Agent见 docs/agents/run/security.md。因此探索应始终发生在受信任的工作区内并遵循最小权限原则。第 1 步定义问题限定探索范围探索的第一步不是让 Agent 解释整个仓库而是只问一个行为。有边界的问题更容易核查其解释是否完整——如果范围太大你根本无法判断它是否漏掉了关键路径。操作步骤如下打开 Chat view在标题栏选择Chat菜单 →Open Chat或使用快捷键kb(workbench.action.chat.open)也可在命令行运行code chat开始一个新会话。将会话目标Session Target选择为Copilot角色Agent选择为Agent并保持手动权限Manual permissions。用自然语言描述你想理解的行为。如果你知道入口点如某个路由、命令或 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.mdChat 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 files 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?page2 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 dependencys 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 说测试通过就相信测试通过。提示词中特意要求除非测试已在本环境中真正运行过否则不得声称其通过。如果确实需要运行时确认请遵循以下纪律先查看项目的搭建说明和它建议的测试命令只运行你信任的仓库中的代码并使用合适的本地测试资源记录实际结果以及任何环境限制不可用的服务、未执行的测试都不能当作通过的检查来对待。这与仓库中 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探索时你实际依赖的防护层包括机制对探索工作流的作用关键设置工作区限定文件访问内置 Agent 工具只能读写当前工作区文件夹内的文件可选用chat.additionalReadAccessFolders追加只读目录chat.additionalReadAccessFolders权限级别决定当前会话的审批行为Manual permissions默认按你的审批设置逐项确认、Assisted permissionsLLM 法官评估每次工具调用、Allow all全部自动放行chat.permissions.defaultAgent 沙箱对终端命令与子进程做文件系统/网络隔离独立于权限级别生效平台相关工具选择器可选择性启用/禁用具体工具精确控制 Agent 的能力面chat.tools.eligibleForAutoApprovalURL 审批抓取网页内容时拆分请求审批与响应审批两步防止提示注入chat.tools.urls.autoApprove两个需要特别警惕的事实探索阶段的不要编辑只是一条指令。想让这条指令真正生效靠的是权限设置与工具活动审查而不是提示词本身见 docs/agents/run/approvals.md。手动权限并不等于每个操作都要批准。哪些工具可被自动批准由chat.tools.eligibleForAutoApproval决定如果你希望某些工具如execute/runInTerminal、web/fetch永远要求人工确认可以把对应条目显式设为false。因此在探索一个不熟悉的仓库时最稳妥的组合是受信任的工作区 Manual permissions 工作区限定的文件访问 不运行项目代码。这样既保留了 Agent 的检索能力又把读代码与改代码/执行代码彻底隔离开。从探索到动手衔接下一步完成一次成功的代码库探索之后你手上已经有入口点、实现路径、相关测试与命令、未解决问题清单。接下来就可以带着这份已验证的地图进入实际改动环节为现有项目添加功能基于探索结论走评审计划 → 按批准范围实现 → 验证的完整流程在不改变行为的前提下重构利用已确认的调用关系与测试基线分步安全重构需要更多可改造的提示词模板时可参考 提示词示例关于 Agent 使用的通用纪律见 使用 AI 的最佳实践。这套定义问题 → 定位代码 → 追踪路径 → 测试校验 → 记录结论的工作流把 Agent 从看起来能解释代码升级为每一步都有源码出处的可核查工具。下次接手陌生仓库时先用一个下午走完这条流程再决定是否动手——你会发现自己改代码时的底气完全不同。赞分享文档教程【免费下载链接】vscode-docsPublic documentation for Visual Studio Code项目地址https://gitcode.com/gh_mirrors/vs/vscode-docs点击查看免费下载相关推荐IronClaw 代码库端到端追踪指南用 /trace 命令定位数据流与缺陷的完整链路IronClaw 代码库端到端追踪指南用 /trace 命令定位数据流与缺陷的完整链路 本指南以仓库 .claude/commands/trace.md 中的人工智能AI 应用交互助手AI Agent源码猎人source-code-hunterDubbo服务调用链路追踪源码猎人source code hunterDubbo服务调用链路追踪 引言分布式系统中的调用追踪挑战 在微服务架构盛行的今天一个简单的用户请求往往需要跨文档教程技术博客知识库深入 WAHA 代码库Agent 探索、扩展与验证 WhatsApp HTTP API 的完整行动手册深入 WAHA 代码库Agent 探索、扩展与验证 WhatsApp HTTP API 的完整行动手册 WAHAWhatsApp HTTP API是一个可后端即时通讯上一篇如何快速部署iTransformer完整实战指南与性能优化技巧下一篇AutoClicker5分钟掌握鼠标自动化点击的终极使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考