如何配置 Sourcegraph Cody 上下文过滤器（cody.contextFilters）以排除敏感代码仓库

在企业推行 AI 辅助编程助手 Sourcegraph Cody 的过程中，研发负责人与合规安全团队普遍面临一个核心治理挑战：企业的核心商业机密、专利算法、涉及合规强监管的代码仓库（如 PCI-DSS 支付核心、HIPAA 医疗数据模块、ITAR 受限项目），如何确保其绝对不会作为上下文被打包并发送至第三方大语言模型（LLM）？

Sourcegraph Cody 提供了企业级的集中治理机制——上下文过滤器（cody.contextFilters）。该功能由站点管理员在 Sourcegraph 站点配置（Site Configuration）中集中维护，通过 RE2 正则表达式精准定义代码仓库的包含与排除策略。它在服务端建立了强制防线，从根本上防止敏感代码作为上下文泄露给外部大模型。

本文详细解析企业管理员如何配置 cody.contextFilters，说明正则语法规范与匹配规则优先级，并给出多层防御最佳实践。

运行前提与版本兼容性

在配置上下文过滤器之前，请确认企业环境与开发者客户端满足以下版本要求：

• Sourcegraph 实例版本： Sourcegraph Enterprise 5.4.0 及以上，且具备有效的 Cody Enterprise 许可证。
• 功能特性开关： 实例特性开关 cody-context-filters-enabled 需配置为 true。
• 客户端支持版本：
  • VS Code 插件版本：>= 1.20.0
  • JetBrains 插件版本：>= 6.0.0
  • Sourcegraph Web 客户端原生支持

客户端兼容性与策略强制执行

为了防止开发者使用过旧版本的 IDE 插件绕过安全审计，Sourcegraph 实例内置了向下兼容与强制拦截机制：

在现代版本的 Sourcegraph 服务端中，无法解析上下文过滤器的老旧客户端会被强制切断上下文传递并提示升级，杜绝了合规防护漏洞。

配置结构与 RE2 正则语法

上下文过滤器位于 Sourcegraph 站点管理的高级 JSON 配置中，键名为 cody.contextFilters。其根对象下包含两个可选数组：include（允许列表）与 exclude（排除列表）。

{
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/.*"
      }
    ],
    "exclude": [
      {
        "repoNamePattern": ".*-sensitive$"
      },
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/core-payments.*"
      }
    ]
  }
}

核心规则与语法要点：

• 一旦声明了 cody.contextFilters，其中必须包含至少一个字段（include 或 exclude）。
• 数组内部的每个元素均为包含 repoNamePattern 的对象。
• repoNamePattern 严格遵循 RE2 正则表达式语法（Go 语言标准库中的正则引擎）。
• 在 JSON 字符串中，反斜杠必须双重转义。例如，匹配字面点号需书写为 \\.，斜杠通常书写为 \\/ 或直接写 /。
• 匹配对象为 Sourcegraph 中登记的仓库完整标识符，通常形如 github.com/organization/repo-name 或私有 GitLab 路径 gitlab.corp.local/group/project。

过滤逻辑与规则优先级

Cody 会根据配置中是否存在 include 和 exclude，采用不同的判定逻辑：

1. 未配置过滤器（默认行为）

如果站点配置中完全未出现 cody.contextFilters，Cody 将遵循常规权限模型，对当前用户在 Sourcegraph 中拥有读取权限的所有仓库开放上下文访问，无任何额外限制。

2. 仅配置 include 规则（严格白名单模式）

Cody 仅允许使用名称匹配 include 中任意一条正则表达式的仓库作为上下文，其余所有仓库均被隐式排除。

• 适用于安全等级要求极高的企业，实施 AI 零信任策略，仅允许经过法务与合规审批的指定开源或基础组件接入 AI。
• 只要命中 include 中的任意一条规则，该仓库即被允许。

{
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/frontend-.*"
      },
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/public-docs$"
      }
    ]
  }
}

3. 仅配置 exclude 规则（黑名单排除模式）

除了名称匹配 exclude 中任意规则的仓库外，Cody 默认可以访问所有其余仓库的上下文。

• 适用于大部分常规企业环境：默认赋能开发者日常生产力，但针对少数高风险仓库（如清结算系统、风控模型、密码学机密模块）设立绝对禁区。
• 若在 exclude 中配置通配符 .*，将构成全局熔断开关，彻底阻断 Cody 提取任何仓库上下文。

{
  "cody.contextFilters": {
    "exclude": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/crypto-vault$"
      },
      {
        "repoNamePattern": ".*settlement-core.*"
      },
      {
        "repoNamePattern": ".*-restricted$"
      }
    ]
  }
}

4. 同时配置 include 与 exclude 规则（组合过滤）

当两个数组同时存在时，仓库必须同时满足以下两个条件方可作为上下文使用：

1. 仓库名称命中 include 中的至少一条规则；
2. 仓库名称未命中 exclude 中的任何一条规则。

排除规则具有最高优先级。如下例所示，公司允许所有 example-corp 旗下的代码仓库，但精确排除了包含 compliance 或以 -secret 结尾的核心库：

{
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/.+"
      }
    ],
    "exclude": [
      {
        "repoNamePattern": ".*compliance.*"
      },
      {
        "repoNamePattern": ".*-secret$"
      }
    ]
  }
}

管理员实施操作步骤

以下是在 Sourcegraph 企业实例中落地上下文过滤器的标准流程：

第一步：排查与核对仓库命名规范

Cody 匹配的是 Sourcegraph 内部索引的完整仓库名。

• 以管理员身份登录 Sourcegraph，进入 Site Admin > Repositories。
• 查看企业代码仓库的标准路径前缀（如 github.com/my-org/... 或自建 GitLab 域名）。
• 梳理合规受限仓库列表，制定正则表达式匹配方案。

第二步：进入站点配置编辑器

1. 点击顶部导航栏的用户头像，选择 Site Admin。
2. 在左侧管理菜单中，点击 Configuration（对应路径为 /site-admin/configuration）。

第三步：写入并校验 cody.contextFilters

在根 JSON 对象中补充特性开关与过滤器配置块：

{
  // ... 其他基础配置 ...
  "cody-context-filters-enabled": true,
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/my-org\\/.*"
      }
    ],
    "exclude": [
      {
        "repoNamePattern": "^github\\.com\\/my-org\\/financial-core$"
      },
      {
        "repoNamePattern": ".*proprietary.*"
      },
      {
        "repoNamePattern": ".*sec-tools.*"
      }
    ]
  }
}

第四步：保存并生效

点击页面底部的 Save changes。Sourcegraph 会进行实时配置热更新，通常无需重启服务集群。

第五步：客户端验证与测试

为确保合规策略生效，建议安排安全运维团队在客户端进行抽检：

1. 在 VS Code 或 JetBrains IDE 中打开一个已被排除的敏感仓库工程。
2. 尝试使用 Cody 行内编辑或快捷指令，客户端将拦截请求并弹出错误提示：

   Edit failed to run: file is ignored (due to cody.contextFilters Enterprise configuration setting)
   

3. 在 Cody 对话框中，尝试使用 @-mention 引用该仓库的文件或函数。被排除的仓库内容不会出现在上下文候选项中，Cody 也不会抽取其向量索引或代码片段作为提示词。

开发者体验与受限行为说明

在被排除的仓库中工作时，开发者的使用体验如下：

• 通用聊天不受影响： 开发者依然可以在 Cody 对话框中询问通用的编程问题、算法实现或公共库用法，但 Cody 不会拉取当前仓库的业务代码作为背景信息。
• 依赖上下文的高级功能受限： 需要提取仓库全量上下文的预置提示词模板（Prompts）可能在被排除的仓库中禁用或报错。
• 自动补全（Autocomplete）阻断： 当光标位于受限仓库的文件中时，代码片段不会被打包上传至第三方模型，最大程度保障代码隐私。

多层安全治理模型：上下文过滤器与关联安全机制对比

构建企业级代码数据防泄密体系需要多层纵深防御，下表对比了 cody.contextFilters 与其他安全机制的分工：

通过以 cody.contextFilters 为核心边界，结合 .cody/ignore 排除局部敏感密钥与配置文件，并依托 Cody Gateway 的零保留企业协议，工程团队即可在充分享受生成式 AI 生产力红利的同时，彻底消除源代码与商业机密外泄的合规隐患。

参考资料

• Manage Cody Context - Sourcegraph docs
• Cody Enterprise features - Sourcegraph docs
• Cody FAQs - Sourcegraph docs