升级前必读：Cody 能解决哪些开发痛点
Sourcegraph Cody 是一款面向开发者的 AI 编程助手，常见用途涵盖代码解释、函数生成、单元测试补充、重构建议、跨文件问答以及提交前审查。相比单纯“写一段代码”，它的核心优势在于能结合当前项目上下文理解调用关系，特别适合中大型项目、遗留系统维护、多人协作代码库以及日常开发效率提升。
进行升级更新的价值主要体现在三方面：一是获取更稳定的代码补全和对话体验，减少扩展卡顿、上下文读取失败等问题；二是支持新模型接入并实现更灵活的模型切换策略；三是修复安全漏洞与兼容性问题。对于已在 VS Code、JetBrains 系列 IDE 或 Sourcegraph 网页端使用 Cody 的用户，建议优先确保扩展保持较新版本，避免因接口变动导致登录失败、索引异常或模型调用出错。
升级准备工作：账号、环境与配置核查
开始升级前，请先确认三项基础条件。第一，确保使用的编辑器版本较新。VS Code 用户推荐使用稳定版，JetBrains 用户需确认 IDE 仍在官方支持周期内。第二，确认 Sourcegraph Cody 账号可正常登录，企业用户还需核实组织管理员是否已开启 Cody 功能。第三，备份关键配置，例如自定义指令、模型偏好、代码补全开关、忽略文件规则以及企业实例地址。
若项目包含未公开代码、客户资料、密钥、内部接口文档等敏感内容，升级前应检查 Cody 的上下文读取范围。切勿将密钥写在代码注释或配置文件中，也不要在对话框中粘贴访问凭据。AI 编程工具能提升效率，但不能替代代码审查、权限管理和安全测试。
VS Code 版 Cody 更新操作指南
VS Code 用户最常用的升级方式是通过扩展市场更新。打开 VS Code，进入左侧“扩展”面板，在搜索框输入“Sourcegraph Cody”并进入详情页。若页面出现“更新”按钮，点击后等待安装完成。更新结束后，建议重启 VS Code，以确保旧进程释放缓存并加载新版本。
若未看到更新按钮，可点击扩展详情页的齿轮图标，检查是否关闭了自动更新。也可以在扩展面板中筛选“已安装”，找到 Cody 后查看当前版本号。若扩展市场加载异常，可先退出编辑器重新打开再试；仍失败时，可从 Sourcegraph 官方发布渠道下载对应版本安装包，在 VS Code 中选择“从 VSIX 安装”。手动安装务必确认来源可靠，避免使用来路不明的文件。
升级后建议做一次可用性测试：打开真实项目，选择一段函数代码，向 Cody 提问“解释这段代码的主要逻辑”；再新建一个简单函数，观察行内补全是否正常出现；最后尝试让 Cody 为某函数补充测试思路。若三项均正常，说明基础功能已恢复。
JetBrains 版 Cody 更新操作指南
JetBrains 系列 IDE（包括 IntelliJ IDEA、PyCharm、WebStorm、GoLand 等）的更新入口通常在“Settings / Preferences”中的“Plugins”。进入插件页面后，在“Installed”列表中找到 Cody，若有新版本会显示更新提示。点击更新并重启 IDE 即可完成。
若更新后 Cody 面板无法打开，先检查 IDE 右下角是否有插件加载错误提示，再进入插件页确认 Cody 是否被禁用。部分情况下，IDE 版本过旧会导致新版插件无法运行，此时应优先升级 IDE，或回退到兼容的 Cody 插件版本。企业环境中若使用统一插件仓库，还需确认内部仓库是否已同步新版本。
命令行与网页端的注意事项
部分团队会结合 Sourcegraph 实例、代码索引和 Cody 功能一起使用。网页端通常无需用户手动升级，但企业部署场景需由管理员维护 Sourcegraph 服务端版本。普通开发者遇到网页端 Cody 不可用时，不要急于修改本地配置，应先确认是否为组织层面的功能开关、授权额度或服务端版本问题。
若团队使用命令行工具或自动化脚本调用相关能力，升级前应仔细阅读版本变更说明，重点关注参数名称、认证方式、默认模型、输出格式是否变化。生产脚本不要直接使用未经验证的新版本，建议先在测试项目中运行，确认输出稳定后再推广。
升级后的必要配置：登录、索引与上下文
更新完成后，第一步是检查登录状态。打开 Cody 面板，若提示登录，按引导完成授权。登录成功后，确认账号显示正常，并检查当前连接的是 Sourcegraph Cloud 还是团队自建实例。企业用户尤其要核对实例地址，避免将问题误判为扩展故障。
第二步是检查上下文设置。Cody 的效果很大程度上取决于它能读取哪些代码和文档。小项目可直接使用当前工作区上下文；中大型项目建议配合 Sourcegraph 的代码索引能力，让 Cody 更好地理解跨文件调用。对于不希望被读取的目录（如构建产物、日志、临时文件、密钥样例），应通过忽略规则排除。
第三步是调整补全体验。若觉得补全干扰编码，可降低自动补全频率，或只在特定语言中启用。若经常处理样板代码、接口适配、类型定义，则建议保留行内补全，这类场景提效明显。
模型选择建议：别只看“最强”
选择模型时，应按任务拆分，而不是固定使用同一个模型。日常代码补全追求速度和稳定，适合选择响应快、成本适中的模型；复杂架构分析、跨文件重构、疑难错误排查，则更适合选择推理能力更强、上下文窗口更大的模型；写注释、生成测试用例、整理提交说明，对模型要求相对均衡。
若 Cody 面板提供多种模型，可按以下思路选择：第一，轻量补全优先选速度快的模型，减少等待；第二，代码问答和重构建议优先选理解能力强的模型；第三，长文件分析优先选支持更长上下文的模型；第四，团队协作场景优先选组织已批准的模型，确保权限和审计策略一致。
常见组合是：默认模型用于日常问答和补全，高能力模型用于复杂问题，经济型模型用于批量生成注释、简单测试或文档草稿。不要将所有任务都交给高成本模型，也不要为了节省资源而在关键代码评审中使用能力不足的模型。
实测升级流程中的常见问题与解决
问题一：更新后无法登录。通常是旧授权状态失效或浏览器授权未完成。可先退出 Cody 账号再重新登录；若使用企业实例，确认实例地址无误并联系管理员检查 Cody 功能是否开启。
问题二：补全没有反应。先确认当前文件类型受支持，再检查是否关闭了自动补全。也可能是项目过大、编辑器索引未完成，等待片刻或重启编辑器后再测试。若只在某个项目失败，重点检查项目配置和忽略规则。
问题三：回答内容与项目不匹配。多半是上下文没有正确加载。可在提问时明确指出文件、函数或目录，例如“结合当前打开文件说明这个方法的调用链”。对于大型代码库，建议先建立索引，再进行跨模块问答。
问题四：升级后变慢。新版扩展可能会重新扫描工作区，首次启动较慢属于正常现象。若持续卡顿，可关闭不必要的工作区、排除大型生成目录，并检查其他插件是否占用过高资源。
版本回退与故障处理
如果新版本影响正常工作，可以临时回退。VS Code 用户可在 Cody 扩展页面选择“安装其他版本”；JetBrains 用户可卸载当前插件后安装兼容版本。回退前记录当前版本号、编辑器版本、系统环境和错误提示，方便后续定位。
需要注意的是，回退只是临时措施。若问题来自账号授权、服务端策略或模型额度，单纯更换扩展版本未必有效。团队使用时应建立统一升级节奏，先由少量成员试用，再推广到全员，避免同一天集中升级造成排查困难。
安全边界：哪些内容不应交给 AI 工具
Cody 可以辅助开发，但不应接触不必要的敏感内容。不要在对话中提交密钥、访问令牌、内部账号、未脱敏日志、客户身份资料、合同原文或未公开方案。生成的代码也不能直接进入生产环境，必须经过人工审查、测试验证和安全扫描。
对于企业项目，建议明确三条规则：只在批准的工具和账号中使用；只让 Cody 读取必要的代码范围；重要变更必须经过同伴审查。AI 给出的解释可能合理但不一定正确，尤其在并发、权限、加密、数据一致性等场景，更要以项目规范和测试结果为准。
实用的升级建议
个人开发者可以开启扩展自动更新，但要保留回退入口；团队用户更适合采用“灰度升级”，先在测试项目验证登录、补全、问答和模型切换，再更新主力环境。升级记录应写明版本号、更新时间、已知问题和处理方式。
模型选择方面，建议建立自己的任务模板：简单补全用快速模型，复杂排查用高能力模型，批量文档用经济型模型。提问时尽量给出文件位置、目标、限制条件和期望输出格式，减少来回沟通。只要升级流程稳、上下文配置准、模型选择合理，Sourcegraph Cody 在日常编码中的实际提升会更加明显。
