如何配置 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 正規表示式語法（由 Google 開發、Go 語言內建的正規引擎）。
• 在 JSON 字串格式中，反斜線必須進行雙重轉義。例如，字面點號應寫為 \\.，斜線可寫為 \\/ 或直接保留 /。
• 比對目標為 Sourcegraph 中註冊的倉庫標準完整名稱，格式通常為 <code-host>/<organization>/<repository>（如 github.com/example-corp/service-api）。

過濾比對邏輯與優先權機制

Cody 會根據管理員配置 include 與 exclude 的組合模式，執行不同的判定邏輯：

1. 未定義過濾器（預設行為）

若站點設定中未加入 cody.contextFilters，Cody 預設採用標準權限體系，只要使用者具備該倉庫的讀取權限，Cody 即可自由存取該倉庫程式碼作為上下文，不受任何過濾限制。

2. 僅設定 include 規則（嚴格白名單模式）

Cody 僅能讀取名稱符合 include 中任一正規表示式的倉庫作為上下文，其餘倉庫皆全面隱式排除。

• 適合採取 AI 零信任架構 的高度機密組織，僅對少數通過法務與合規審核的共用工具庫開放 AI。
• 只要符合 include 陣列中的任意一項條件即可生效。

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

3. 僅設定 exclude 規則（黑名單排除模式）

除了名稱符合 exclude 中任一正規表示式的倉庫外，Cody 預設可存取其餘所有倉庫的上下文。

• 適合普遍鼓勵 AI 提升開發效能、但需精確封鎖特定高風險業務庫（如金流結算核心、硬體加解密模組）的企業。
• 若在 exclude 中設定全匹配萬用字元 .*，即相當於全域緊急斷路器，將全面禁止 Cody 讀取任何程式碼上下文。

{
  "cody.contextFilters": {
    "exclude": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/crypto-vault$"
      },
      {
        "repoNamePattern": ".*payment-gateway.*"
      },
      {
        "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 權限登入 Sourcegraph 系統。
2. 點擊頂端導覽列的使用者頭像，選擇 Site Admin。
3. 在左側管理選單中，點選 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 Chat 面板中，嘗試以 @-mention 提及受限倉庫內的檔案或符號。該檔案將不會出現在上下文建議清單中，Cody 亦不會抓取其任何程式碼片段送往外部模型。

開發者體驗與受限行為說明

了解過濾規則對開發者的具體影響，有助於 IT 與研發團隊做好內部宣導：

• 通用對話維持運作： 即使開發者開啟的是被排除的機密專案，Cody Chat 依然可用於諮詢通用語言語法、除錯技巧或公開技術方案，差別僅在於 Cody 不會夾帶當前專案程式碼作為背景資訊。
• 依賴全域上下文之進階指令受限： 部份仰賴倉庫全域上下文的提示詞範本（Prompts）可能在受限倉庫中無法執行或回報停用錯誤。
• 自動補全（Autocomplete）即時防護： 游標位於受限倉庫檔案時，Cody 不會將周邊程式碼打包上傳至模型推論伺服器，嚴密守護機密資產。

縱深防禦：上下文過濾器與關聯防護機制對比

完善的企業資安治理依賴層層把關。下表整理了 cody.contextFilters 與其他防護機制的職責分工：

透過以 cody.contextFilters 作為組織級核心防線，搭配 .cody/ignore 排除專案內局部機密金鑰，並基於 Cody Gateway 企業零保留協議，企業即可在安心釋放生成式 AI 研發動能的同時，堅守程式碼資產的隱私與合規底線。

參考資料

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