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）

5 分钟跑起来

遇到问题怎么办

深入理解原理

看看新版本有什么

解锁三大能力

避免误删关键内容

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 步：启用调试日志 ​

检查点 ✅ ​

踩坑提醒 ​

配置修改不生效 ​

配置文件语法错误 ​

受保护工具不生效 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

DCP 配置全解

学完你能做什么

你现在的困境

什么时候用这一招

核心思路

🎒 开始前的准备

跟我做

第 1 步：查看当前配置

第 2 步：理解配置文件位置

第 3 步：配置修剪通知

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

第 5 步：配置保护机制

1. 回合保护（Turn Protection）

2. 受保护工具（Protected Tools）

3. 受保护文件模式（Protected File Patterns）

第 6 步：创建项目级配置

第 7 步：启用调试日志

检查点 ✅

踩坑提醒

配置修改不生效

配置文件语法错误

受保护工具不生效

本课小结

下一课预告

附录：源码参考