DCP 配置全解

學完你能做什麼

掌握 DCP 的三級配置系統（全域、專案、環境變數）
理解配置優先級規則，知道哪個配置會生效
根據需求調整修剪策略和保護機制
配置通知級別，控制修剪提示的詳細程度

你現在的困境

DCP 安裝後預設配置就能工作，但你可能遇到這些問題：

想為不同專案設定不同的修剪策略
不希望某些檔案被修剪
修剪提示太頻繁或太詳細
想禁用某個自動修剪策略

這時候就需要了解 DCP 的配置系統了。

什麼時候用這一招

專案級定制：不同專案有不同的修剪需求
除錯問題：啟用 debug 日誌定位問題
效能調優：調整策略開關和閾值
個人化體驗：修改通知級別、保護關鍵工具

核心思路

DCP 採用三級配置系統，按優先級從低到高依次是：

預設值（程式碼硬編碼）→ 全域配置 → 環境變數配置 → 專案配置
         優先級最低                              優先級最高

每級配置都會覆蓋上一級的同名配置項，所以專案配置的優先級最高。

為什麼需要多層級配置？

這樣設計的目的是：

全域配置：設定通用的預設行為，適用於所有專案
專案配置：針對特定專案進行定制，不影響其他專案
環境變數：在不同環境（如 CI/CD）中快速切換配置

🎒 開始前的準備

確保已完成安裝與快速開始，DCP 外掛已成功安裝並在 OpenCode 中執行。

跟我做

第 1 步：查看當前配置

為什麼 先了解預設配置，再決定如何調整。

DCP 首次執行時會自動建立全域配置檔案。

bash

# macOS/Linux
cat ~/.config/opencode/dcp.jsonc

# Windows PowerShell
Get-Content "$env:USERPROFILE\.config\opencode\dcp.jsonc"

你應該看到：類似下面的預設配置

jsonc

{
    "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
    "enabled": true,
    "debug": false,
    "pruneNotification": "detailed",
    "commands": {
        "enabled": true,
        "protectedTools": []
    },
    "turnProtection": {
        "enabled": false,
        "turns": 4
    },
    "protectedFilePatterns": [],
    "tools": {
        "settings": {
            "nudgeEnabled": true,
            "nudgeFrequency": 10,
            "protectedTools": []
        },
        "discard": {
            "enabled": true
        },
        "extract": {
            "enabled": true,
            "showDistillation": false
        }
    },
    "strategies": {
        "deduplication": {
            "enabled": true,
            "protectedTools": []
        },
        "supersedeWrites": {
            "enabled": false
        },
        "purgeErrors": {
            "enabled": true,
            "turns": 4,
            "protectedTools": []
        }
    }
}

第 2 步：理解配置檔案位置

DCP 支援三個層級的配置檔案：

層級	路徑	優先級	適用場景
全域	`~/.config/opencode/dcp.jsonc` 或 `dcp.json`	2	所有專案的預設配置
環境變數	`$OPENCODE_CONFIG_DIR/dcp.jsonc` 或 `dcp.json`	3	特定環境的配置
專案	`<project>/.opencode/dcp.jsonc` 或 `dcp.json`	4	單個專案的配置覆蓋

配置檔案格式

DCP 支援 .json 和 .jsonc 兩種格式：

.json：標準 JSON 格式，不能包含註解
.jsonc：支援 // 註解的 JSON 格式（推薦使用）

第 3 步：配置修剪通知

為什麼 控制 DCP 顯示修剪提示的詳細程度，避免過度打擾。

編輯全域配置檔案：

jsonc

{
    "pruneNotification": "detailed"  // 可選值: "off", "minimal", "detailed"
}

通知級別說明：

級別	行為	適用場景
off	不顯示修剪通知	專注開發，不需要回饋
minimal	只顯示簡要統計（節省的 Token 數）	需要簡單回饋，不想被太多資訊打擾
detailed	顯示修剪的詳細資訊（工具名、原因）	了解修剪行為，除錯配置

你應該看到：修改配置後，下次觸發修剪時通知會按新級別顯示。

第 4 步：配置自動修剪策略

為什麼 DCP 提供三種自動修剪策略，你可以根據需求開關。

編輯配置檔案：

jsonc

{
    "strategies": {
        // 去重策略：移除重複的工具呼叫
        "deduplication": {
            "enabled": true,           // 啟用/禁用
            "protectedTools": []         // 額外保護的工具名
        },

        // 覆蓋寫入策略：清理已被讀取覆蓋的寫操作
        "supersedeWrites": {
            "enabled": false          // 預設禁用
        },

        // 清除錯誤策略：清理過期錯誤工具的輸入
        "purgeErrors": {
            "enabled": true,           // 啟用/禁用
            "turns": 4,               // 幾回合後清理錯誤
            "protectedTools": []         // 額外保護的工具名
        }
    }
}

策略詳解：

deduplication（去重）：預設啟用。檢測相同工具和參數的呼叫，保留最新一次。
supersedeWrites（覆蓋寫入）：預設禁用。如果寫操作後有後續讀取，清理該寫操作的輸入。
purgeErrors（清除錯誤）：預設啟用。超過指定回合數的錯誤工具會被修剪（只保留錯誤訊息，移除可能很大的輸入參數）。

第 5 步：配置保護機制

為什麼 避免誤修剪關鍵內容（如重要檔案、核心工具）。

DCP 提供三種保護機制：

1. 回合保護（Turn Protection）

保護最近幾回合的工具輸出，給 AI 足夠時間引用。

jsonc

{
    "turnProtection": {
        "enabled": false,   // 啟用後保護最近 4 回合
        "turns": 4          // 保護回合數
    }
}

適用場景：當你發現 AI 頻繁遺失上下文時，可以啟用。

2. 受保護工具（Protected Tools）

某些工具預設始終不會被修剪：

task, todowrite, todoread, discard, extract, batch, write, edit, plan_enter, plan_exit

你可以新增額外需要保護的工具：

jsonc

{
    "tools": {
        "settings": {
            "protectedTools": [
                "myCustomTool",   // 新增自訂工具
                "databaseQuery"    // 新增需要保護的工具
            ]
        }
    },
    "strategies": {
        "deduplication": {
            "protectedTools": ["databaseQuery"]  // 為特定策略保護工具
        }
    }
}

3. 受保護檔案模式（Protected File Patterns）

使用 glob 模式保護特定檔案：

jsonc

{
    "protectedFilePatterns": [
        "**/*.config.ts",           // 保護所有 .config.ts 檔案
        "**/secrets/**",           // 保護 secrets 目錄下的所有檔案
        "**/*.env",                // 保護環境變數檔案
        "**/critical/*.json"        // 保護 critical 目錄下的 JSON 檔案
    ]
}

注意

protectedFilePatterns 匹配的是 tool.parameters.filePath，而不是檔案的實際路徑。這意味著它只適用於有 filePath 參數的工具（如 read、write、edit）。

第 6 步：建立專案級配置

為什麼 不同專案可能需要不同的修剪策略。

在專案根目錄建立 .opencode 目錄（如果不存在），然後建立 dcp.jsonc：

bash

# 在專案根目錄執行
mkdir -p .opencode
cat > .opencode/dcp.jsonc << 'EOF'
{
    "$schema": "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/master/dcp.schema.json",
    // 這個專案的特定配置
    "strategies": {
        "supersedeWrites": {
            "enabled": true   // 這個專案啟用覆蓋寫入策略
        }
    },
    "protectedFilePatterns": [
        "**/config/**/*.ts"   // 保護這個專案的配置檔案
    ]
}
EOF

你應該看到：

專案級配置會覆蓋全域配置的同名項
未覆蓋的項繼續使用全域配置

第 7 步：啟用除錯日誌

為什麼 遇到問題時，查看詳細的除錯日誌。

編輯配置檔案：

jsonc

{
    "debug": true
}

日誌位置：

~/.config/opencode/logs/dcp/daily/YYYY-MM-DD.log

你應該看到：日誌檔案中包含詳細的修剪操作、配置載入等資訊。

生產環境建議

除錯完成後記得將 debug 改回 false，避免日誌檔案增長過快。

檢查點 ✅

完成以上步驟後，確認以下內容：

[ ] 知道配置檔案的三個層級和優先級
[ ] 能修改通知級別並看到效果
[ ] 理解三種自動修剪策略的作用
[ ] 會配置保護機制（回合、工具、檔案）
[ ] 能建立專案級配置覆蓋全域設定

踩坑提醒

配置修改不生效

問題：修改配置檔案後，OpenCode 沒有反應。

原因：OpenCode 不會自動重新載入配置檔案。

解決：修改配置後需要重啟 OpenCode。

配置檔案語法錯誤

問題：配置檔案有語法錯誤，DCP 無法解析。

表現：OpenCode 會顯示 Toast 警告提示 "Invalid config"。

解決：檢查 JSON 語法，特別是：

引號、逗號、括號是否匹配
是否有多餘的逗號（如最後一個元素後的逗號）
布林值用 true/false，不要用引號

推薦做法：使用支援 JSONC 的編輯器（如 VS Code + JSONC 外掛）。

受保護工具不生效

問題：新增了 protectedTools，但工具仍被修剪。

原因：

工具名拼寫錯誤
新增到了錯誤的 protectedTools 陣列（如 tools.settings.protectedTools vs strategies.deduplication.protectedTools）
工具呼叫在回合保護期內（如果啟用了回合保護）

解決：

確認工具名拼寫正確
檢查是否新增到了正確的位置
查看 debug 日誌瞭解修剪原因

本課小結

DCP 配置系統的核心要點：

三級配置：預設值 → 全域 → 環境變數 → 專案，優先級遞增
靈活覆蓋：專案配置可以覆蓋全域配置
保護機制：回合保護、受保護工具、受保護檔案模式，避免誤修剪
自動策略：去重、覆蓋寫入、清除錯誤，按需開關
重啟生效：修改配置後記得重啟 OpenCode

下一課預告

下一課我們學習 自動修剪策略詳解。
你會學到：
去重策略如何檢測重複工具呼叫
覆蓋寫入策略的工作原理
清除錯誤策略的觸發條件
如何監控策略效果

附錄：原始碼參考

點選展開查看原始碼位置

更新時間：2026-01-23

功能	檔案路徑	行號
配置管理核心	`lib/config.ts`	1-798
配置 Schema	`dcp.schema.json`	1-232
預設配置	`lib/config.ts`	423-464
配置優先級	`lib/config.ts`	669-797
配置驗證	`lib/config.ts`	147-375
配置檔案路徑	`lib/config.ts`	484-526
預設受保護工具	`lib/config.ts`	68-79
合併策略配置	`lib/config.ts`	565-595
合併工具配置	`lib/config.ts`	597-622

關鍵常數：

DEFAULT_PROTECTED_TOOLS：預設受保護的工具名列表（lib/config.ts:68-79）

關鍵函式：

getConfig()：載入並合併所有層級的配置（lib/config.ts:669-797）
getInvalidConfigKeys()：驗證配置檔案中的無效鍵（lib/config.ts:135-138）
validateConfigTypes()：驗證配置值的型別（lib/config.ts:147-375）
getConfigPaths()：取得所有配置檔案的路徑（lib/config.ts:484-526）

DCP 配置全解 ​

學完你能做什麼 ​

你現在的困境 ​

什麼時候用這一招 ​

核心思路 ​

🎒 開始前的準備 ​

跟我做 ​

第 1 步：查看當前配置 ​

第 2 步：理解配置檔案位置 ​

第 3 步：配置修剪通知 ​

第 4 步：配置自動修剪策略 ​

第 5 步：配置保護機制 ​

1. 回合保護（Turn Protection） ​

2. 受保護工具（Protected Tools） ​

3. 受保護檔案模式（Protected File Patterns） ​

第 6 步：建立專案級配置 ​

第 7 步：啟用除錯日誌 ​

檢查點 ✅ ​

踩坑提醒 ​

配置修改不生效 ​

配置檔案語法錯誤 ​

受保護工具不生效 ​

本課小結 ​

下一課預告 ​

附錄：原始碼參考 ​

DCP 配置全解

學完你能做什麼

你現在的困境

什麼時候用這一招

核心思路

🎒 開始前的準備

跟我做

第 1 步：查看當前配置

第 2 步：理解配置檔案位置

第 3 步：配置修剪通知

第 4 步：配置自動修剪策略

第 5 步：配置保護機制

1. 回合保護（Turn Protection）

2. 受保護工具（Protected Tools）

3. 受保護檔案模式（Protected File Patterns）

第 6 步：建立專案級配置

第 7 步：啟用除錯日誌

檢查點 ✅

踩坑提醒

配置修改不生效

配置檔案語法錯誤

受保護工具不生效

本課小結

下一課預告

附錄：原始碼參考