IDE 扩展使用 - 从0开始的AI Coding 学习

本页目标

本页只讲 Codex 在 VS Code 及兼容编辑器中的实际工作流。完成后，你应能独立完成下面这条闭环：

安装并确认官方扩展。
登录账号并打开正确的项目目录。
把当前文件、选区和相关文件准确交给 Codex。
在 Ask 和 Edit 模式之间选择合适的授权方式。
阅读、审批或拒绝文件修改的 diff。
在编辑器面板和集成终端之间切换。
遇到扩展不显示、登录失败、上下文不准或命令失败时，按步骤定位。
在不泄露密钥、客户数据或内部代码的前提下完成验收。

界面名称、图标位置、可用模型和功能开关会随扩展版本、编辑器分支及账号权限变化。以下步骤中的菜单文字以你本机显示为准；当文字不一致时，先打开命令面板或扩展详情页确认当前版本，不要根据旧截图猜测。

先建立正确的模型

IDE 扩展是 Codex 在编辑器中的工作入口。它和 CLI 使用同一套代理能力、项目规则和大部分配置思路，但它额外知道编辑器当前打开的文件、光标位置和选中文本。桌面 App 与 Cloud 则是另外的入口，不是本页的重点。 Codex 的工作方式可以概括为“想、做、看”：

想：读取项目文件、理解请求、列出计划。
做：修改文件、运行命令或调用项目工具。
看：检查命令输出、测试结果和当前 diff，必要时继续修复。

IDE 面板并不会替你完成工程判断。你仍然要确认工作区、授权范围、要执行的命令和最终差异。模型给出的总结不是验收证据，编辑器中的 diff、终端退出码和测试输出才是证据。

扩展、CLI 和编辑器终端的分工

任务	IDE 面板	集成终端中的 CLI	适合的入口
询问当前文件或选区	很方便	需要明确路径或粘贴内容	IDE
逐文件审查修改	适合，能看编辑器 diff	可用 `git diff`	IDE + CLI
运行测试、构建和脚本	可请求代理执行	可手动观察完整输出	两者均可
SSH、批处理、管道和自动化	不适合	更灵活	CLI
只讨论方案，不写文件	Ask 模式	只读沙箱或审查会话	两者均可
需要人工逐项判断外部命令	默认会请求确认	终端中直接观察和批准	两者均可

扩展与 CLI 可以在同一个项目里交替使用。切换前先确认它们位于同一个项目根目录，并查看 git status --short，避免把两个会话的改动混在一起。

开始前检查

准备一个安全的工作区

第一次练习使用新建的演示目录或测试分支。不要直接在生产目录、包含客户数据的目录或正在发布的工作区里测试自动编辑。在项目根目录打开终端，确认路径和工作区状态：

pwd
# Windows PowerShell 可用：Get-Location

git status --short

如果已有未提交修改，记录它们属于谁、哪些文件已经被改过。不要为了让页面“干净”而删除他人的修改。实际任务开始前，准备以下信息：

项目根目录的绝对路径。
当前分支或提交号。
项目的启动、测试、格式化和构建命令。
本次允许修改的文件和明确禁止触碰的目录。
成功时可观察到的结果。

可在提示中明确写出：“不要提交、不要推送、不要删除文件，不修改目标范围外的内容。”这类边界不是替代权限控制，但能减少代理的猜测。

确认编辑器和 CLI

在终端检查编辑器版本和 Codex CLI 是否可用：

code --version
codex --version
codex --help

如果使用 Cursor、Windsurf 或 VS Code Insiders，把 code 替换为对应的命令；如果命令不存在，直接从图形界面打开项目即可。CLI 不是安装 IDE 扩展的硬性前提，但集成终端协同需要它已经在 PATH 中。

安装官方扩展

通过扩展市场安装

打开 VS Code、VS Code Insiders 或兼容编辑器。
打开扩展视图。Windows/Linux 通常使用 Ctrl+Shift+X，macOS 通常使用 Cmd+Shift+X。
搜索 Codex 或 ChatGPT。
核对发布者为 OpenAI，并核对扩展标识为 openai.chatgpt（若详情页显示的标识与此不同，以官方发布页和本机详情为准）。
点击安装，等待安装和激活完成。
首次安装后按提示重新加载窗口或重启编辑器。

预期界面行为：扩展详情页显示已安装，活动栏或侧边栏出现 Codex/ChatGPT 入口。VS Code 的入口可能在右侧，兼容编辑器可能出现在左侧、右侧或活动栏的更多菜单中。

通过命令行安装

如果编辑器命令已加入 PATH，可以运行：

code --install-extension openai.chatgpt

Cursor 等编辑器将 code 换成其命令行名称。预期输出会包含安装开始和成功完成的信息。若命令返回“无法连接市场”或下载超时，先检查代理、防火墙和编辑器的网络设置，不要从不明网站下载 .vsix。

安装后核对清单

安装完成后，在扩展详情页核对：

发布者是 OpenAI。
状态是已启用，而不是“已禁用”或“在远程中禁用”。
扩展没有被工作区的受限模式阻止。
编辑器版本满足扩展详情页列出的最低版本。
你打开的是桌面版编辑器，而不是无法运行扩展的纯文本预览窗口。

如果活动栏看不到入口，先执行“Developer: Reload Window”或重启编辑器，再检查活动栏的溢出菜单。入口被收起不等于扩展没有安装。

登录和会话

第一次登录

打开 Codex 面板。
选择登录方式。常见方式是使用 ChatGPT/OpenAI 账号在浏览器完成授权；某些环境也可能提供 API Key 选项。
若浏览器没有自动跳回编辑器，复制授权页面给出的回调提示，或回到编辑器查看登录通知。
登录完成后回到 Codex 面板，确认账号状态已经变为已登录。

预期界面行为：面板可以显示对话输入区、当前模型或模式选择器，登录按钮不再持续提示。不要把 API Key 直接写入项目文件、settings.json、终端脚本或截图。

登录失败时的处理顺序

按以下顺序缩小范围：

确认系统时间正确，浏览器能打开 OpenAI 登录页面。
在编辑器账户菜单中退出再登录，避免授权到了另一个账号。
检查公司代理、防火墙、VPN 或 DNS 是否阻断授权回调。
检查编辑器是否处于远程窗口，判断扩展运行在本机还是远程主机。
更新扩展和编辑器到兼容版本，再重新加载窗口。
打开扩展的日志或“输出”面板，记录错误码和时间。

不要把完整日志公开粘贴到 Issue 或群聊。日志可能包含工作区路径、组织信息、请求标识甚至文件片段；分享前先脱敏。

账号和项目边界

登录账号决定服务权限和配额，不等于自动获得本机所有文件的权限。文件能否读取、能否修改、命令是否需要确认，还受工作区、沙箱、审批模式和编辑器信任状态影响。如果编辑器打开了一个包含多个仓库的父目录，Codex 可能把整个父目录当作上下文范围。敏感项目应单独打开仓库根目录，而不是打开用户主目录或包含多个项目的上级目录。

打开正确的项目

从文件夹打开

使用“File: Open Folder”打开仓库根目录。不要只打开一份孤立文件，因为这样可能缺少依赖清单、测试配置、项目规则和版本控制信息。也可以在终端运行：

cd path/to/project
code .

Windows PowerShell 示例：

Set-Location C:\work\demo-project
code .

预期界面行为：资源管理器显示项目根目录，源代码管理视图显示当前仓库和分支，终端的新会话默认位于该目录。

通过工作区文件打开

.code-workspace 可以包含多个文件夹。使用多根工作区时，在提示中明确要操作哪一个根目录，例如“只修改 frontend 根目录中的文件”。没有明确范围时，先让 Codex 列出它识别到的项目根和候选文件。

打开后先做一次只读探索

在 Codex 面板先选择 Ask 或只读权限，发送：

请先只读检查当前工作区。
列出项目入口、主要依赖、测试命令和与登录功能相关的文件。
不要修改文件，不要安装依赖，不要访问外部服务。
最后说明你识别到的项目根目录和依据。

预期：Codex 读取少量相关文件并给出结构化说明，不产生文件 diff，也不执行未授权的写入命令。若它把别的目录当作项目，立即停止并重新打开正确文件夹。

当前文件、选区和文件引用

上下文越准确，提示越短，结果越容易审查。但“自动上下文”不是无限读取，也不代表你可以省略目标、约束和验收标准。

当前文件上下文

打开目标文件并保持编辑器焦点在文件中，然后在面板中提问：

解释当前文件的职责、入口函数、外部依赖和错误处理。
只读分析，不修改代码。

预期：回答围绕当前文件展开，并引用实际符号或行附近内容。若回答涉及不相关目录，改用明确的文件引用和范围。

选区上下文

在编辑器中选中目标函数、模板片段或报错附近的几行。
确认选区没有遗漏函数签名、条件分支和相关注释。
在面板中询问选区的行为或问题。

示例：

只分析当前选区。
说明它在空输入、无权限和网络失败时的行为，并指出需要补充的测试。
不要修改文件。

预期：回答明确对应选区；不应要求你再次描述“哪一段”。如果你切换了文件，重新选择目标范围，避免旧上下文继续影响新问题。

使用 `@` 引用文件

在提示框输入 @，从候选列表选择文件或工作区资源。不同编辑器对文件引用的显示形式可能不同，但原则相同：点名资料，不让代理猜路径。

参考 @src/types/user.ts 和 @src/services/user-service.ts。
说明 User 的字段如何从控制器传到服务层。
只读分析，不修改文件。

引用整个大文件可能增加上下文负担。优先引用接口、测试和实现中真正相关的部分。需要多个文件时，说明每个文件的作用，例如“第一个是类型定义，第二个是实现”。

图片、截图和二进制文件

遇到 UI 错位或报错截图，使用扩展支持的附件方式添加图片。拖放时若编辑器拦截普通拖放，可按当前版本提示使用复制粘贴或带修饰键拖放。发送前检查截图中没有密码、Token、客户姓名、内部域名和浏览器标签页。

上下文失真时的信号

出现以下现象时，不要继续批准修改：

Codex 提到不存在的文件或旧分支内容。
回答混入另一个项目的类名、端口或依赖。
你切换文件后，它仍然围绕上一段选区回答。
它声称“已验证”，但没有列出命令和输出。

处理方法是新建对话，重新打开目标文件并显式引用路径，然后让它先复述目标、范围和验收标准。

Ask 与 Edit 模式

不同扩展版本可能把模式称为 Ask、Chat、Edit、Agent 或类似名称。判断模式时看它是否允许写文件和运行命令，不要只依赖颜色或图标。

Ask 模式：先问、先读、先出方案

Ask 适合：

了解陌生项目。
解释当前文件或选区。
审查代码和列出风险。
设计跨文件改动方案。
还没有决定是否要修改时。

练习提示：

请为“给现有接口增加分页”提出实施方案。
先读取相关路由、服务、类型和测试文件，但不要修改任何文件。
列出候选文件、兼容性风险、测试命令和需要我确认的决策。

预期：面板给出计划和待确认事项，资源管理器中没有新文件或修改标记，源代码管理视图没有新增 diff。若 Ask 模式仍提议执行命令，检查该命令是否为只读命令；仍不确定时拒绝并要求先说明原因。

Edit 模式：在明确边界后实施

Edit 适合目标、范围和验证都已明确的局部任务。提示应包含四件套：

目标：改完要得到什么结果。
范围：允许改哪些文件、函数或选区。
约束：不能引入什么、不能改变什么行为。
验证：要运行什么测试、lint 或构建命令。

示例：

目标：让当前函数收到空列表时返回 0，而不是抛出除零异常。
范围：只修改 src/stats.py 中的 average 函数，并在 tests/test_stats.py 增加测试。
约束：不引入第三方依赖，保留非空列表的现有结果。
验证：运行 pytest tests/test_stats.py，并报告退出码。
先说明计划，确认后再编辑；不要提交或推送。

先计划再编辑的节奏

复杂任务分两轮：

在 Ask 模式请求探索和计划。
检查计划中的文件、接口和验证命令。
切到 Edit 模式，只放行一个小步骤。
查看 diff 和测试结果。
再决定是否继续下一步。

跨模块重构、认证、支付、数据库迁移和权限逻辑不应一次性授权全部修改。每个小步骤都应有可观察的结果和可回滚点。

阅读和审批 diff

为什么必须看 diff

Codex 的总结只能说明它认为自己做了什么。diff 才能显示：

实际修改了哪些文件。
是否改到了目标范围之外。
是否删除了注释、配置或错误处理。
是否产生格式化噪声或换行符大面积变化。
是否把凭据、调试输出或个人路径写入文件。

审批一个文件修改

当面板展示待应用修改时，按这个顺序检查：

文件路径是否属于当前项目和本次范围。
diff 的上下文是否对应你刚才指定的函数或选区。
新代码是否符合项目既有风格和接口约定。
是否改变了错误处理、权限检查或数据校验。
是否新增依赖、脚本、网络请求或配置文件。
测试是否覆盖了正常、边界和失败路径。
变更是否足够小，能在一次审查中看完。

确认后点击 Apply、Accept 或当前版本对应的应用按钮。发现问题则选择 Reject、Discard 或取消，不要为了“先试试看”批准无法解释的改动。

应用后再次核对

应用 diff 后，在集成终端运行：

git diff --stat
git diff --check
git status --short

再运行项目已有的最小验证命令。例如：

npm test
# 或项目文档规定的 pytest、go test、cargo test 等命令

预期：变更文件与目标一致，空白检查通过，测试退出码为 0。测试失败时保留完整输出，回到同一个对话要求“只修复这个失败，不扩大文件范围”。

不要混淆编辑器保存和审批

编辑器可能自动保存文件，也可能在应用 diff 前先写入临时内容。无论界面如何显示，都要以源代码管理视图和 git diff 为准。应用修改后如果看不到 diff，检查文件是否未保存、是否被 .gitignore 忽略，或是否实际写入了另一个工作区。

终端与 CLI 协同

在同一个工作区切换

打开集成终端（Windows/Linux 常见为 Ctrl+` ，macOS 常见为 Cmd+` ），先确认：

pwd
git status --short

然后可以直接运行项目命令，或启动 CLI：

codex

预期：CLI 的当前目录与编辑器打开的项目根一致。若不一致，先 cd 到正确目录，不要在主目录启动代理。

IDE 负责上下文，CLI 负责脚本

推荐的协同方式是：

在 IDE 选中代码，用 Ask 模式理解问题。
在 Edit 模式应用小范围修改。
在终端运行完整测试、构建或类型检查。
用 git diff 审查结果。
对批量、SSH 或重复任务切换到 CLI，但保持同样的范围和审批纪律。

CLI 会话和 IDE 会话可能同时修改同一文件。不要并行批准两个会话的编辑；每次切换前保存、查看状态并确认没有冲突。

让代理执行终端命令时的检查

以下动作需要特别谨慎：安装依赖、联网、删除或移动文件、修改环境变量、访问数据库、调用部署接口、提交和推送。批准前先问清：

命令的完整文本是什么。
当前工作目录是什么。
会读取或写入哪些路径。
是否联网，目标主机是什么。
失败时如何回滚。

对未知脚本先打开 package.json、Makefile、任务配置或项目文档查看定义。不要只因为命令名字包含 test、check 或 fix 就认为它无副作用。

一次完整练习

下面的练习验证安装、登录、上下文、Ask/Edit、diff 和终端协同。请在临时目录或测试分支进行。

第一步：创建练习项目

创建目录并在编辑器中打开。文件内容可以手动建立，避免依赖系统 shell 的换行差异。

ide-demo/
  greet.py

greet.py 内容：

def greet(name):
    return "Hello, " + name


print(greet("world"))

预期：资源管理器显示 greet.py，编辑器可以正常语法着色，终端位于 ide-demo。

第二步：用 Ask 模式分析

选中 greet 函数，发送：

只分析当前选区：说明这个函数的输入、输出和两个可改进点。
不要修改文件，也不要运行命令。

预期：出现文字分析，没有文件 diff。若出现待批准的写操作，拒绝并检查当前模式是否确实是 Ask。

第三步：用 Edit 模式修改

切换到 Edit/Agent 模式，发送：

只修改当前选中的 greet 函数。
把字符串拼接改成 f-string，并为 name 和返回值添加 str 类型注解。
不要改 print 调用，不要引入依赖。
完成后展示 diff，不要提交或推送。

预期：待应用的 diff 只涉及 greet.py 中的函数。应看到类似以下变化：

-def greet(name):
-    return "Hello, " + name
+def greet(name: str) -> str:
+    return f"Hello, {name}"

逐行阅读后再应用。若它同时改了 print、空白或其他文件，拒绝这次修改，重新强调范围。

第四步：在终端验证

应用后运行：

python greet.py
git diff --check
git diff --stat

预期：终端输出 Hello, world，空白检查没有错误，统计结果只显示预期文件。若系统中命令名是 python3，使用项目实际约定的解释器。

第五步：回到 Ask 做复查

新建或切回 Ask 对话，发送：

只读审查当前未提交改动。
检查类型注解、输出行为和是否修改了范围外内容。
列出你实际检查的命令或文件，不要再修改。

预期：得到审查结论而没有新增 diff。最后用编辑器源代码管理视图和终端输出互相核对。

常见故障和修复

扩展搜不到或装错

现象：搜索结果很多，找不到官方入口。处理：搜索 ChatGPT，核对发布者 OpenAI 和详情页标识；确认编辑器版本和网络；不要安装仅凭名称相似的第三方扩展。命令行安装时使用 openai.chatgpt，并检查命令输出。

已安装但入口不见

现象：扩展详情页显示已安装，活动栏没有入口。处理：重新加载窗口；检查活动栏的更多菜单和右侧面板；确认扩展已启用；检查当前窗口是不是远程窗口或受限模式；在“扩展”视图查看错误提示。必要时关闭其他会改变活动栏布局的扩展，再重启编辑器。

面板空白、卡在加载中

处理顺序：

重新加载窗口。
检查登录状态。
查看“View: Output”中的 Codex/扩展日志。
检查网络、代理和系统时间。
更新扩展和编辑器。
在最小测试项目中重现，判断是项目配置问题还是扩展问题。

记录版本、操作系统、是否远程开发、发生时间和脱敏后的错误信息。不要反复删除配置目录，除非已备份并确认其中没有需要保留的本地设置。

登录反复失效

确认浏览器登录的是预期账号，清理无关的旧授权会话后重新登录。企业网络可能拦截浏览器回调或服务域名；让网络管理员确认允许的域名和代理方式。不要把临时令牌复制到聊天、项目配置或脚本中。

Codex 读不到当前文件

确认文件已经保存，编辑器焦点在目标文件，选区仍然存在，并且文件位于当前工作区。新建对话后用 @ 显式引用文件，再让 Codex 复述路径。若文件被 .gitignore 忽略或属于未信任目录，先检查编辑器是否允许扩展访问。

Codex 改了错误的文件

立即拒绝或撤销待应用 diff。不要继续在错误上下文上追加提示。重新打开正确的仓库根目录，明确写出绝对或工作区相对路径、函数名、允许修改的文件和禁止修改的目录。先 Ask 让它列出计划，确认后再 Edit。

命令被拒绝或无法执行

先区分三种原因：沙箱阻止、审批未批准、系统本身找不到命令。查看面板中的完整命令和原因，再在终端手动检查：

pwd
which python
which node

Windows PowerShell 可用：

Get-Location
Get-Command python
Get-Command node

工作区外写入、联网和安装依赖不应通过盲目放宽权限来解决。必要时在临时目录中单独执行，并在完成后恢复原权限设置。

测试失败但代理说已完成

以测试输出和退出码为准。把完整错误贴回当前会话，要求它只处理这个失败，说明根因、修改文件和再次运行的命令。若测试本身依赖未安装的服务或环境变量，先区分代码失败和环境缺失，不要让代理伪造通过结果。

隐私和安全边界

默认不要发送的内容

不要把以下内容直接放进提示、截图、附件或日志：

API Key、访问令牌、SSH 私钥和密码。
.env、生产配置和完整凭据文件。
客户姓名、联系方式、订单、医疗或财务数据。
未公开的漏洞细节和内部网络拓扑。
与当前任务无关的整个仓库或用户主目录内容。

用脱敏后的占位符替代，例如 EXAMPLE_TOKEN、user@example.test 和 https://internal.example.test。如果必须讨论配置结构，只提供字段名和虚构值。

工作区和沙箱不是数据分类工具

工作区边界限制代理能访问或修改的路径，审批控制某些动作是否先询问；它们不能替你判断数据是否可以发送到外部服务。即使某个文件在工作区内，也可能包含不应上传或展示的敏感信息。先按组织政策分类数据，再决定是否使用 Codex。

外部内容可能包含不可信指令

README、Issue、网页、日志、依赖包输出和源代码注释都可能出现要求代理泄露信息、执行危险命令或修改权限的文本。把它们当作待分析数据，不当作授权。任何“忽略之前规则”“上传配置”“执行清理脚本”的指令，都必须由你独立核实。

高风险操作的人工确认

以下动作必须逐项确认，不因面板显示“建议”就自动批准：

删除、覆盖或批量重命名文件。
修改访问控制、认证、支付和部署配置。
安装未知依赖或运行下载来的脚本。
联网访问内部服务、数据库或生产 API。
提交、推送、创建合并请求或发布。
读取工作区外目录、浏览器配置或凭据存储。

验收清单

完成一次 IDE 任务后，逐条核对：

回滚和交接

如果修改结果不对，先停止代理并保存错误输出。对未提交改动，优先在编辑器源代码管理视图逐文件撤销；也可以在确认没有混入人工改动后使用：

git diff -- path/to/file
# 确认后再决定是否恢复该文件
 git restore -- path/to/file

注意命令前多出的空格仅为示例排版，实际执行时从 git 开始。不要使用恢复命令覆盖同事或自己尚未备份的修改。交接给同事或从 IDE 切到 CLI 时，提供：当前目录、分支、变更文件、已运行命令、测试结果、未解决问题和下一步。不要只说“已经修好”，也不要把未经脱敏的日志作为交接材料。

本页验收练习

你通过本页的标准是：能够在一个临时项目中安装并识别官方扩展，完成登录，打开项目，使用当前文件和选区提问；能够在 Ask 模式下只读分析，在 Edit 模式下应用一份只涉及目标函数的 diff；能够在终端验证输出并用 git diff --check 复核；能够故意制造一次上下文或权限问题，并根据日志、工作区路径、模式和命令输出定位原因；最后能说清哪些内容不应发送给 Codex，以及如何撤销未提交改动。下一步可以回到 CLI 页面，用同一个项目运行只读审查或测试命令，比较 IDE 的上下文能力与终端的自动化能力。无论入口如何切换，都保持“明确目标、限定范围、人工审 diff、运行验证、保留回滚点”的节奏。参考资料：参考/codex/09-ide.md、参考/codex/13-prompting.md、参考/codex/02-core-concepts.md。

​本页目标

​先建立正确的模型

​扩展、CLI 和编辑器终端的分工

​开始前检查

​准备一个安全的工作区

​确认编辑器和 CLI

​安装官方扩展

​通过扩展市场安装

​通过命令行安装

​安装后核对清单

​登录和会话

​第一次登录

​登录失败时的处理顺序

​账号和项目边界

​打开正确的项目

​从文件夹打开

​通过工作区文件打开

​打开后先做一次只读探索

​当前文件、选区和文件引用

​当前文件上下文

​选区上下文

​使用 @ 引用文件

​图片、截图和二进制文件

​上下文失真时的信号

​Ask 与 Edit 模式

​Ask 模式：先问、先读、先出方案

​Edit 模式：在明确边界后实施

​先计划再编辑的节奏

​阅读和审批 diff

​为什么必须看 diff

​审批一个文件修改

​应用后再次核对

​不要混淆编辑器保存和审批

​终端与 CLI 协同

​在同一个工作区切换

​IDE 负责上下文，CLI 负责脚本

​让代理执行终端命令时的检查

​一次完整练习

​第一步：创建练习项目

​第二步：用 Ask 模式分析

​第三步：用 Edit 模式修改

​第四步：在终端验证

​第五步：回到 Ask 做复查

​常见故障和修复

​扩展搜不到或装错

​已安装但入口不见

​面板空白、卡在加载中

​登录反复失效

​Codex 读不到当前文件

​Codex 改了错误的文件

​命令被拒绝或无法执行

​测试失败但代理说已完成

​隐私和安全边界

​默认不要发送的内容

​工作区和沙箱不是数据分类工具

​外部内容可能包含不可信指令

​高风险操作的人工确认

​验收清单

​回滚和交接

​本页验收练习