工具定位与安装前准备

Sourcegraph Cody 是面向开发者的 AI 编程助手。

它常用于代码解释、函数生成、单元测试补全、跨文件检索和项目问答。

它的优势不只是“写一段代码”。

它能结合当前仓库上下文，理解工程结构。

它适合日常开发、代码审查前自检、老项目梳理和新人熟悉业务代码等场景。

安装前，建议先确认三件事：

• 第一：编辑器版本是否较新。VS Code 建议使用近几个月内的稳定版。JetBrains 系列也应保持官方仍维护的版本。
• 第二：是否已有 Sourcegraph 或 Cody 可用账号。部分团队环境还需要管理员开启对应权限。
• 第三：本机能否正常访问所需服务端点。如果公司使用自建 Sourcegraph 实例，还要提前拿到实例地址、访问令牌和模型策略说明。

VS Code 安装步骤

最常见的安装方式是在 VS Code 中完成。

打开扩展面板，搜索“Cody AI”或“Sourcegraph Cody”。

确认发布方为 Sourcegraph 后，点击安装。

安装完成后，左侧活动栏通常会出现 Cody 图标。你也可以通过命令面板输入“Cody”查看可用命令。

首次启动时，Cody 会提示登录或配置访问方式。

个人用户可按界面引导完成授权。

团队用户若使用自建实例，应选择配置 Sourcegraph 端点。填写形如 https://sourcegraph.example.com 的地址，再填入个人访问令牌。

配置后，建议重启编辑器，确保扩展读取到最新设置。

如果需要手动检查配置，可进入 VS Code 设置，搜索“Cody”。重点查看 Endpoint、Access Token、Autocomplete、Chat Model 等项目。

注意：不要把令牌直接写入项目配置文件，也不要提交到代码仓库。多人协作时，应使用个人级本地设置或团队统一的密钥管理方案。

JetBrains 安装步骤

在 IntelliJ IDEA、WebStorm、PyCharm 等 JetBrains IDE 中，可进入 Settings 或 Preferences，打开 Plugins。

搜索 Cody，确认来源后安装并重启 IDE。

重启后，在工具窗口或设置页中找到 Cody 配置入口。按提示登录，或填写 Sourcegraph 实例地址与访问令牌。

JetBrains 环境的常见差异在于索引和项目权限。

大型项目首次打开时，IDE 还在建立索引。Cody 对上下文的读取可能不完整。

建议等待索引完成后再进行问答或补全测试。

如果项目使用多模块结构，应确认当前打开的是工程根目录，而不是单个子目录。否则，代码检索效果会明显下降。

API 配置思路与调用测试

Cody 的可用性通常取决于三层配置：账号权限、服务端点、模型能力。

• 账号权限决定能否调用。
• 服务端点决定请求发往哪里。
• 模型能力决定聊天、补全、解释代码等功能是否可用。

遇到问题时，不要只盯着编辑器界面。先做一次最小化 API 连通性测试，能更快定位故障。

测试前准备

准备好三个信息：Sourcegraph 实例地址、访问令牌、测试用接口路径。

不同部署版本支持的接口可能不同。建议以所在团队提供的文档或实例页面为准。

若只是验证令牌和端点是否可用，可优先调用用户信息、站点状态或 GraphQL 查询类接口。

若要验证 Cody 相关能力，则应检查实例是否启用了对应功能。

通用测试方法

一种通用测试方式是使用终端工具发起请求。

请求头中带上 Authorization: token 你的令牌，并访问实例的 API 或 GraphQL 地址。

若返回当前用户信息、站点版本或正常的 JSON 结果，说明基础连通和令牌权限大概率正常。

若返回 401，通常是令牌无效或格式错误。

若返回 403，多半是账号没有对应权限。

若连接超时，则应检查端点地址、证书和网络策略。

编辑器功能验证

完成 API 测试后，再回到编辑器执行三项功能验证：

1. 打开一个真实代码文件，选中函数后让 Cody 解释逻辑。
2. 在聊天框询问当前项目中某个类的用途。
3. 新建一个测试文件，尝试生成简单单元测试。

三项都正常，说明安装和配置基本完成。

常见报错与解决流程

报错一：“Authentication failed”或登录失败

优先检查令牌是否复制完整，前后是否多了空格，令牌是否已过期。

团队实例中，还要确认账号是否被分配 Cody 使用权限。

处理顺序建议为：

1. 重新生成个人令牌。
2. 更新编辑器配置。
3. 重启编辑器。
4. 再做 API 连通测试。

报错二：“Endpoint not reachable”或连接失败

先确认地址协议和域名是否正确。很多问题来自把 http 与 https 写错，或遗漏路径。

其次，检查本机时间是否准确。时间偏差可能导致证书校验异常。

若在公司内网环境使用，应咨询管理员确认访问范围。不要随意使用来源不明的中转工具。

报错三：“No context available”或回答与项目无关

这通常不是模型失效，而是上下文没有被正确读取。

解决方法包括：

• 打开工程根目录。
• 等待 IDE 索引完成。
• 确认仓库已被 Sourcegraph 索引。
• 避免一次性打开过大的临时目录。

对于单文件脚本，也可以在提问时明确贴出关键函数或说明文件路径。

报错四：自动补全不出现

先检查设置中 Autocomplete 是否开启。再确认当前文件类型是否受支持。

某些语言服务未启动、文件过大、光标位置上下文不足，都会影响补全。

可以换一个小文件测试。输入函数名和注释后停顿数秒，观察是否出现建议。

报错五：提示模型不可用或配额不足

这类问题多与服务端策略有关。

个人环境可检查订阅状态和模型选择。团队环境应联系管理员，查看模型提供方、调用额度和访问分组。

不要通过共享令牌绕过限制，这会带来审计和安全风险。

安全边界与使用建议

使用 AI 编程工具时，最重要的边界是代码和凭据保护。

• 不要把生产密钥、客户资料、内部接口凭证直接粘贴到聊天框。
• 不要让工具生成后未经审查就合并到主分支。
• 不要把访问令牌写进 README、脚本或示例配置。

对外部依赖、鉴权逻辑、数据删除逻辑、支付类流程等敏感代码，必须由开发者复核。

建议把 Cody 当成“高效助理”，而不是最终决策者。

适合交给它的任务包括：

• 解释陌生模块。
• 生成样板代码。
• 补充测试思路。
• 整理重构方案。
• 指出潜在空指针和异常分支。

涉及架构取舍、线上变更、权限控制和核心算法时，应结合团队规范、测试结果和代码评审。

为了获得更稳定的效果，提问时应尽量具体。

例如：

• 不要只问“这段代码怎么样”。而是问“请解释这个函数的输入输出、异常分支和可改进点”。
• 不要只说“帮我写测试”。而是说明测试框架、边界条件和期望覆盖的场景。

上下文越清楚，生成结果越接近可用状态。

安装完成后的检查清单

完成安装后，可按清单逐项确认：

• 扩展已启用。
• 账号已登录或令牌已配置。
• Sourcegraph 端点正确。
• API 连通测试返回正常。
• 当前项目从根目录打开。
• IDE 索引完成。
• 聊天、解释代码、自动补全至少各测试一次。
• 令牌没有出现在项目文件中。
• 团队成员了解哪些代码可以提交给工具分析。

如果后续升级 Cody 或更换 Sourcegraph 实例，建议先记录旧配置。包括扩展版本、端点地址、主要模型和可用功能。

升级后若出现异常，可先禁用再启用扩展，清理本地缓存，重新登录，并用 API 测试确认服务端状态。

必要时回退到上一稳定版本，等团队验证通过后再统一更新。

总体来看，Sourcegraph Cody 的安装并不复杂。

真正容易出问题的是：账号权限、端点地址、模型策略和项目上下文。

按照“先确认环境、再配置令牌、后做 API 测试、最后验证编辑器功能”的顺序处理，大多数报错都能快速定位，后续使用也更安全可靠。