Полное руководство по конфигурации 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: стандартный формат JSON, не поддерживает комментарии
.jsonc: формат JSON с поддержкой комментариев // (рекомендуется использовать)

Шаг 3: Настройка уведомлений об обрезке

Зачем Контролировать уровень детализации уведомлений об обрезке, чтобы избежать излишнего беспокойства.

Отредактируйте файл глобальной конфигурации:

jsonc

{
    "pruneNotification": "detailed"  // Возможные значения: "off", "minimal", "detailed"
}

Описание уровней уведомлений:

Уровень	Поведение	Сценарий применения
off	Не отображать уведомления об обрезке	Сосредоточенная разработка, отсутствие необходимости в обратной связи
minimal	Отображать только краткую статистику (количество сохраненных токенов)	Необходим простой отклик, но без излишней информации
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"        // Защита JSON-файлов в директории critical
    ]
}

Внимание

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
Схема конфигурации	`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: Включение отладочных логов

Контрольная точка ✅

Предупреждения о подводных камнях

Изменения конфигурации не применяются

Синтаксические ошибки в файле конфигурации

Защищенные инструменты не работают

Резюме урока

Предварительный просмотр следующего урока

Приложение: Ссылки на исходный код