Лучшие практики DCP

Что вы сможете делать после изучения

• Понимать компромисс между Prompt Caching и экономией токенов
• Выбирать подходящие стратегии защиты (защита ходов, защищённые инструменты, режимы файлов)
• Использовать команды для ручной оптимизации использования токенов
• Настраивать конфигурацию DCP в соответствии с требованиями проекта

Компромисс Prompt Caching

Понимание компромисса между кэшированием и обрезкой

При обрезке вывода инструментов DCP изменяет содержимое сообщений, что приводит к аннулированию Prompt Caching на основе точного префиксного совпадения с этого момента.

Сравнение тестовых данных:

Сценарий	Попадание в кэш	Экономия токенов	Комплексный эффект
Без DCP	~85%	0%	Базовый уровень
DCP включён	~65%	20-40%	✅ Положительный эффект

Когда следует игнорировать потери кэша

Рекомендуемые сценарии использования DCP:

• ✅ Длинные диалоги (более 20 ходов): значительное раздувание контекста, экономия токенов намного превышает потери кэша
• ✅ Сервисы с оплатой по запросу: GitHub Copilot, Google Antigravity и другие, где потери кэша не имеют негативного влияния
• ✅ Интенсивный вызов инструментов: частое чтение файлов, выполнение поиска и другие сценарии
• ✅ Задачи рефакторинга кода: частое повторное чтение одних и тех же файлов

Сценарии, когда может потребоваться отключение DCP:

• ⚠️ Короткие диалоги (< 10 ходов): ограниченная выгода от обрезки, потери кэша могут быть более заметны
• ⚠️ Задачи, чувствительные к кэшу: сценарии, требующие максимального попадания в кэш (например, пакетная обработка)

Гибкая конфигурация

Вы можете динамически настраивать конфигурацию DCP в соответствии с требованиями проекта или даже отключать определённые стратегии на уровне конфигурации проекта.

---

Лучшие практики приоритета конфигурации

Правильное использование многоуровневой конфигурации

Конфигурация DCP объединяется в следующем порядке приоритета:

Значения по умолчанию < Глобальная конфигурация < Пользовательский каталог конфигурации < Конфигурация проекта

Описание каталога конфигурации

"Пользовательский каталог конфигурации" — это каталог, указанный через переменную окружения $OPENCODE_CONFIG_DIR. В этом каталоге необходимо разместить файл dcp.jsonc или dcp.json.

Рекомендуемые стратегии конфигурации

Сценарий	Рекомендуемое место конфигурации	Ключевые аспекты примера конфигурации
Личная среда разработки	Глобальная конфигурация	Включить автоматические стратегии, отключить отладочные логи
Командный проект	Конфигурация проекта	Защищённые файлы, специфичные для проекта, переключатели стратегий
CI/CD среда	Пользовательский каталог конфигурации	Отключить уведомления, включить отладочные логи
Временная отладка	Конфигурация проекта	Включить debug, подробный режим уведомлений

Пример: переопределение на уровне проекта

// ~/.config/opencode/dcp.jsonc (глобальная конфигурация)
{
    "enabled": true,
    "strategies": {
        "deduplication": {
            "enabled": true
        }
    }
}

// .opencode/dcp.jsonc (конфигурация проекта)
{
    "strategies": {
        // Переопределение на уровне проекта: отключить дедупликацию (например, проект требует сохранения исторического контекста)
        "deduplication": {
            "enabled": false
        }
    }
}

Перезапуск после изменения конфигурации

После изменения конфигурации необходимо перезапустить OpenCode для применения изменений.

---

Выбор стратегий защиты

Сценарии использования защиты ходов

Защита ходов (Turn Protection) предотвращает обрезку инструментов в течение указанного количества ходов, предоставляя AI достаточно времени для ссылки на недавний контент.

Рекомендуемые настройки:

Сценарий	Рекомендуемое значение	Причина
Решение сложных проблем	4-6 ходов	AI требуется несколько итераций для анализа вывода инструментов
Рефакторинг кода	2-3 хода	Быстрое переключение контекста, слишком длительный период защиты снижает эффективность
Быстрая разработка прототипов	2-4 хода	Баланс между защитой и экономией токенов
Конфигурация по умолчанию	4 хода	Протестированная точка баланса

Когда включать защиту ходов:

{
    "turnProtection": {
        "enabled": true,   // Включить защиту ходов
        "turns": 6        // Защита на 6 ходов (подходит для сложных задач)
    }
}

Когда не рекомендуется включать:

• Простые сценарии вопросов и ответов (AI отвечает напрямую, не требуется инструмент)
• Высокочастотные короткие диалоги (слишком длительный период защиты приводит к несвоевременной обрезке)

Конфигурация защищённых инструментов

Защищённые инструменты по умолчанию (не требуют дополнительной конфигурации):

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

Примечание о значениях по умолчанию в Schema

Если вы используете функцию автодополнения IDE, список защищённых инструментов по умолчанию в файле Schema (dcp.schema.json) может отображаться не полностью. Фактически используйте DEFAULT_PROTECTED_TOOLS, определённые в исходном коде, которые включают все 10 инструментов.

Когда добавлять дополнительные защищённые инструменты:

Сценарий	Пример конфигурации	Причина
Критически важные бизнес-инструменты	protectedTools: ["critical_tool"]	Обеспечить постоянную видимость критических операций
Инструменты, требующие исторического контекста	protectedTools: ["analyze_history"]	Сохранить полную историю для анализа
Пользовательские инструменты задач	protectedTools: ["custom_task"]	Защитить рабочий процесс пользовательских задач

{
    "strategies": {
        "deduplication": {
            "enabled": true,
            "protectedTools": ["custom_analyze"]  // Дополнительная защита определённых инструментов
        }
    },
    "tools": {
        "settings": {
            "protectedTools": ["important_check"]  // Дополнительная защита инструментов LLM
        }
    }
}

Использование режимов защищённых файлов

Рекомендуемые режимы защиты:

Тип файла	Рекомендуемый режим	Причина защиты
Файлы конфигурации	"*.env", ".env*"	Предотвратить потерю конфиденциальной информации при обрезке
Конфигурация базы данных	"**/config/database/*"	Обеспечить постоянную доступность конфигурации подключения к базе данных
Файлы ключей	"**/secrets/**"	Защитить все ключи и сертификаты
Ключевая бизнес-логика	"src/core/*"	Предотвратить потерю контекста критического кода

{
    "protectedFilePatterns": [
        "*.env",                // Защитить все файлы переменных окружения
        ".env.*",              // Включая .env.local и т.д.
        "**/secrets/**",       // Защитить каталог secrets
        "**/config/*.json",    // Защитить файлы конфигурации
        "src/auth/**"          // Защитить код, связанный с аутентификацией
    ]
}

Правила сопоставления шаблонов

protectedFilePatterns соответствует полю filePath в параметрах инструментов (например, инструменты read, write, edit).

---

Выбор автоматических стратегий

Стратегия дедупликации (Deduplication)

Включена по умолчанию, подходит для большинства сценариев.

Применимые сценарии:

• Повторное чтение одного и того же файла (например, рецензирование кода, многораундовая отладка)
• Выполнение одних и тех же команд поиска или анализа

Когда не рекомендуется включать:

• Необходимость сохранения точного вывода каждого вызова (например, мониторинг производительности)
• Вывод инструмента содержит временные метки или случайные значения (каждый вызов отличается)

Стратегия перезаписи (Supersede Writes)

Отключена по умолчанию, требует решения на основе требований проекта.

Рекомендуемые сценарии включения:

• Немедленное чтение для проверки после модификации файла (рефакторинг, пакетная обработка)
• Вывод операции записи очень велик, чтение перекрывает его ценность

{
    "strategies": {
        "supersedeWrites": {
            "enabled": true  // Включить стратегию перезаписи
        }
    }
}

Когда не рекомендуется включать:

• Необходимость отслеживания истории изменений файлов (аудит кода)
• Операция записи содержит важные метаданные (например, причины изменений)

Стратегия очистки ошибок (Purge Errors)

Включена по умолчанию, рекомендуется поддерживать включённой.

Рекомендации по конфигурации:

Сценарий	Рекомендуемое значение	Причина
Конфигурация по умолчанию	4 хода	Протестированная точка баланса
Сценарии быстрого отказа	2 хода	Очистить ошибочный ввод как можно раньше, уменьшить загрязнение контекста
Необходимость истории ошибок	6-8 ходов	Сохранить больше информации об ошибках для отладки

{
    "strategies": {
        "purgeErrors": {
            "enabled": true,
            "turns": 2  // Сценарий быстрого отказа: очистка ошибочного ввода через 2 хода
        }
    }
}

---

Лучшее использование инструментов на основе LLM

Оптимизация функции напоминаний

DCP по умолчанию напоминает AI об использовании инструментов обрезки после каждых 10 вызовов инструментов.

Рекомендуемая конфигурация:

Сценарий	nudgeFrequency	Описание эффекта
Интенсивный вызов инструментов	8-12	Своевременное напоминание AI об очистке
Низкочастотный вызов инструментов	15-20	Уменьшить помехи от напоминаний
Отключение напоминаний	Infinity	Полностью полагаться на автономное суждение AI

{
    "tools": {
        "settings": {
            "nudgeEnabled": true,
            "nudgeFrequency": 15  // Низкочастотный сценарий: напоминание после 15 вызовов инструментов
        }
    }
}

Использование инструмента Extract

Когда использовать Extract:

• Вывод инструмента содержит ключевые находки или данные, требующие сохранения резюме
• Исходный вывод очень велик, но извлечённой информации достаточно для последующих рассуждений

Рекомендации по конфигурации:

{
    "tools": {
        "extract": {
            "enabled": true,
            "showDistillation": false  // По умолчанию не отображать извлечённое содержимое (уменьшить помехи)
        }
    }
}

Когда включать showDistillation:

• Необходимость просмотра, какую ключевую информацию извлёк AI
• Отладка или проверка поведения инструмента Extract

Использование инструмента Discard

Когда использовать Discard:

• Вывод инструмента является только временным состоянием или шумом
• После завершения задачи вывод инструмента не требуется сохранять

Рекомендации по конфигурации:

{
    "tools": {
        "discard": {
            "enabled": true
        }
    }
}

---

Советы по использованию команд

Когда использовать /dcp context

Рекомендуемые сценарии:

• Подозрение на аномальное использование токенов
• Необходимость понимания распределения контекста текущего сеанса
• Оценка эффекта обрезки DCP

Лучшие практики:

• Проверить один раз в середине длинного диалога, чтобы понять состав контекста
• Проверить в конце диалога, чтобы просмотреть общее потребление токенов

Когда использовать /dcp stats

Рекомендуемые сценарии:

• Необходимость понимания долгосрочного эффекта экономии токенов
• Оценка общей ценности DCP
• Сравнение эффекта экономии при разных конфигурациях

Лучшие практики:

• Просматривать накопленную статистику раз в неделю
• Сравнивать эффект до и после оптимизации конфигурации

Когда использовать /dcp sweep

Рекомендуемые сценарии:

• Контекст слишком велик, что приводит к замедлению ответа
• Необходимость немедленного уменьшения потребления токенов
• Автоматические стратегии не вызвали обрезку

Советы по использованию:

Команда	Назначение
/dcp sweep	Обрезать все инструменты после последнего сообщения пользователя
/dcp sweep 10	Обрезать только последние 10 инструментов
/dcp sweep 5	Обрезать только последние 5 инструментов

Рекомендуемый рабочий процесс:

1. Сначала использовать /dcp context для просмотра текущего состояния
2. На основе ситуации решить количество обрезки
3. Использовать /dcp sweep N для выполнения обрезки
4. Снова использовать /dcp context для подтверждения эффекта

---

Выбор режима уведомлений

Сравнение трёх режимов уведомлений

Режим	Отображаемое содержимое	Применимые сценарии
off	Не отображать никаких уведомлений	Рабочая среда без необходимости помех
minimal	Отображать только количество обрезки и экономию токенов	Необходимость понимания эффекта без внимания к деталям
detailed	Отображать каждый обрезанный инструмент и причину (по умолчанию)	Сценарии отладки или необходимости детального мониторинга

Рекомендуемая конфигурация

Сценарий	Рекомендуемый режим	Причина
Ежедневная разработка	minimal	Внимание к эффекту, уменьшение помех
Отладка проблем	detailed	Просмотр причин каждой операции обрезки
Демонстрация или запись демонстрации	off	Избежать помех уведомлений в процессе демонстрации

{
    "pruneNotification": "minimal"  // Рекомендуется для ежедневной разработки
}

---

Обработка сценариев субагентов

Понимание ограничений субагентов

DCP полностью отключён в сеансах субагентов.

Причины:

• Цель субагента — вернуть краткое резюме находок
• Обрезка DCP может помешать поведению суммирования субагента
• Субагенты обычно выполняются быстро, раздувание контекста ограничено

Как определить, является ли сеанс сеансом субагента

1. Включить отладочные логи:

   {
       "debug": true
   }

2. Просмотреть логи: В логах будет отображаться метка isSubAgent: true

Рекомендации по оптимизации токенов для субагентов

Хотя DCP отключён в субагентах, вы всё равно можете:

• Оптимизировать подсказки субагентов, уменьшить длину вывода
• Ограничить диапазон вызова инструментов субагента
• Использовать параметр max_length инструмента task для контроля вывода

---

Резюме урока

Область лучших практик	Ключевые рекомендации
Prompt Caching	В длинных диалогах экономия токенов обычно превышает потери кэша
Приоритет конфигурации	Глобальная конфигурация для общих настроек, конфигурация проекта для специфических требований
Защита ходов	Сложные задачи 4-6 ходов, быстрые задачи 2-3 хода
Защищённые инструменты	Защита по умолчанию достаточна, добавлять критически важные бизнес-инструменты по требованию
Защищённые файлы	Защитить файлы конфигурации, ключей, ключевой бизнес-логики
Автоматические стратегии	Дедупликация и очистка ошибок включены по умолчанию, перезапись по требованию
Инструменты LLM	Частота напоминаний 10-15 раз, отображение извлечённого содержимого при отладке
Использование команд	Регулярная проверка контекста, обрезка по требованию
Режим уведомлений	Ежедневная разработка — minimal, отладка — detailed

---

Приложение: Справка по исходному коду

Нажмите, чтобы развернуть и просмотреть расположение исходного кода

Время обновления: 2026-01-23

Функция	Путь к файлу	Номера строк
Слияние конфигурации	lib/config.ts	691-794
Валидация конфигурации	lib/config.ts	147-375
Конфигурация по умолчанию	lib/config.ts	68-134
Защита ходов	lib/config.ts	432-437
Защищённые инструменты	lib/config.ts	68-79
Режимы защищённых файлов	protected-file-patterns.ts	1-60
Обнаружение субагентов	lib/state/utils.ts	1-8
Функция напоминаний	lib/config.ts	438-441

Ключевые константы:

• MAX_TOOL_CACHE_SIZE = 1000: Максимальное количество записей в кэше инструментов
• turnProtection.turns: Защита по умолчанию на 4 хода

Ключевые функции:

• getConfig(): Загрузка и слияние многоуровневой конфигурации
• validateConfigTypes(): Валидация типов элементов конфигурации
• mergeConfig(): Слияние конфигурации по приоритету
• isSubAgentSession(): Обнаружение сеанса субагента