# dsh-patch-edit-plus Русский | [English](./README.md) | [简体中文](./README.zh.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md) | [Français](./README.fr.md) | [Deutsch](./README.de.md) | [Italiano](./README.it.md) | [Español](./README.es.md) Патчевое редактирование файлов для [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness): единственный доступный модели инструмент `apply_patch`, который принимает **git/unified diff** (по умолчанию) и **синтаксис `apply_patch` от Codex** (по явному включению), применяет каждое изменение по принципу **всё-или-ничего** и абсолютно не мешает работе DSH. ## Совместимость с версиями DSH | Версия DSH | Статус | Примечания | |---|---|---| | `0.2.0-rc.1+` | ✅ поддерживается (эта линия, v0.3.0+) | Декларативные настройки: `allowCodexPatch` помечен `.volatile()` — форма настроек формируется автоматически, а `loader/volatile-update` перерегистрирует инструмент без перемонтирования. Вызов регистрации не нужен. Delete/Move переведены на foreground-API `ShellExecutor.execute()` + `result()`. | | `0.1.7-rc.1+` | ↗ линия сопровождения | Обслуживается веткой `compat/0.1.7` / dist-tag `dsh-0.1.7` (там v0.2.1). Shell-исполнитель 0.2.0 переименовал `run` → `execute` (изменение появилось между 0.1.2 и 0.1.7), поэтому одна кодовая база не может типобезопасно обслуживать обе линии. | | `0.1.2-rc.1` ~ `0.1.5-rc.2` | ↗ линия сопровождения | Обслуживается веткой до 0.1.7 / dist-tag `dsh-0.1.5`. В 0.1.7 удалены императивные API настроек, на которых держался двух-API-фолбэк. | На этой линии настройки декларативны: поля, помеченные `.volatile()` в `Config`, становятся формой настроек; плагин подписывается на `loader/volatile-update` вместо получения регистрационных хуков. ## Зачем вообще патчи? (руководство по маршрутизации инструментов) Описание инструмента явно направляет модель: - **Одиночное небольшое изменение в уже прочитанном файле** → предпочитайте нативный инструмент `edit` (патч стоит больше токенов, чем буквальное редактирование). - **Небольшое изменение внутри БОЛЬШОГО файла** → `apply_patch` (не нужно повторять весь файл). - **Пакетные изменения во МНОГИХ файлах** → `apply_patch` (один вызов, атомарная проверка). - **Новый файл с существенным содержимым / удаление / переименование** → `apply_patch`. ## Установка ```bash dsh plugin --profile web add dsh web --dump-config # verify the plugin row appears # restart DSH ``` ## Использование ### Unified diff (по умолчанию, включён) ```text --- a/src/app.ts +++ b/src/app.ts @@ -10,4 +10,4 @@ export function main() { init() - start(oldPort) + start(newPort) await shutdown() } ``` ### Синтаксис apply_patch от Codex (по явному включению) ```text *** Begin Patch *** Update File: src/app.ts @@ init() - start(oldPort) + start(newPort) *** Add File: docs/notes.md +# Notes *** Delete File: tmp/junk.txt *** Move to: src/app.ts (via `*** Move to:` after *** Update File:) *** End Patch ``` Включается через `allowCodexPatch: true`. Если патч Codex приходит при выключенной опции, инструмент возвращает **действенную подсказку** (как её включить или как повторить попытку в unified diff) вместо общей ошибки разбора — синтаксис Codex является сильным априорным признаком для моделей семейства GPT, и молчаливый сбой затягивает их в циклы повторов. ### Операции | Операция | Unified diff | Codex | Путь выполнения | |---|---|---|---| | Добавление | `new file mode` + `/dev/null` | `*** Add File:` | `ctx.fs.writeText` (официальная intent-последовательность) | | Обновление (multi-hunk) | `@@` hunks | `@@` hunks | `ctx.fs.writeText` | | Удаление | `deleted file mode` + `/dev/null` | `*** Delete File:` | `ctx.shell` (с учётом sandbox, путь передаётся через env) | | Перемещение / переименование | `rename from/to` | `*** Move to:` | `ctx.shell` | ## Гарантии - **Всё-или-ничего**: весь патч сначала проверяется на соответствие текущему содержимому файлов (локализация контекста, удержание в рабочей области, политика symlink, дубликаты путей); любой сбой прерывает операцию без записи хотя бы байта. - **Соблюдение запрета на запись без чтения**: каждая запись воспроизводит intent-последовательность официального инструмента `write` — водопад `fs/write-intent` → защищённый `writeText` → эмиссия `fs/observed`. Голый `writeText` молча обходил бы этот барьер, поскольку провайдеры DSH никогда сами не диспетчеризуют события `fs/*`. - **Точная диагностика сбоев**: при несовпадении хунка ошибка содержит файл + индекс хунка, исходную строку поиска, превью ожидаемой строки (с показанными пробелами), фактический фрагмент файла и адресную подсказку. - **Точность переводов строк**: файлы CRLF записываются обратно как CRLF; окончания без завершающего перевода строки сохраняются, если только патч не меняет окончание. - **Чистое дополнение**: плагин регистрирует ровно один инструмент, никогда не вызывает `tools.restrict()`, никогда не переопределяет нативный инструмент, не регистрирует глобальных служб и при выгрузке удаляет всё. Конфликты имён с другими провайдерами `apply_patch` (`bainianlaoyao/dsh-codex-mode`, `shuind/dsh-codex-harness`, …) разрешаются избеганием переименования (`apply_patch_1`, `…_2`, …), так что DSH никогда не падает при старте. ## Конфигурация | Опция | По умолчанию | Описание | |---|---|---| | `toolName` | `apply_patch` | Имя инструмента, доступного модели. | | `conflictPolicy` | `rename` | `rename` / `skip` / `fail`, если имя инструмента уже занято. | | `renameSuffix` | `_1` | Суффикс, используемый при избегании переименования. | | `allowUnifiedDiff` | `true` | Принимать git/unified diff. | | `allowCodexPatch` | `false` | Принимать синтаксис `apply_patch` от Codex. Также редактируется в панели настроек DSH; изменения вступают в силу немедленно, без перезапуска. | | `deleteBackend` | `shell` | `shell` или `none` (Delete/Move возвращают структурированную ошибку). | | `shellDialect` | `auto` | `auto` (pwsh на win32) / `posix` / `pwsh`. | | `deleteCommand` / `moveCommand` | built-in | Пользовательские шаблоны команд. Пути по-прежнему передаются **только через переменные окружения** (`DSH_PATCH_TARGET` / `DSH_PATCH_SOURCE`); никогда не подставляйте их в строку команды интерполяцией. | | `dryRunByDefault` | `false` | Считать вызовы пробными запусками (dry run), если не задано `dryRun: false`. | | `followSymlinks` | `false` | Разрешить путям патча переходить по symlink. | | `maxFiles` | `50` | Максимум файловых секций на один патч. | | `maxPatchBytes` | `524288` | Максимальный размер текста патча в байтах. | | `maxDiffBytes` | `16384` | Максимальный размер диффа на файл, сохраняемого в метаданных результата (большие диффы опустошаются и помечаются `truncated`). | ## Ограничения (раскрытые) - **Delete/Move выполняются через `ctx.shell`.** Сила sandbox такова, каков обеспечивающий её загруженный shell-исполнитель (`bash-sandbox` изолирует; `bash-local` — нет) — та же позиция риска, что и у нативного инструмента bash. Каждый запрос несёт `sandboxPolicy` и сообщает факты о sandbox, чтобы «отказ политики» можно было отличить от «сбоя команды». - **Каждая запись и каждый Delete/Move несут политику в области действия сессии.** `apply_patch` разрешает `ctx.sandboxPolicy.resolve({ session })` при каждом вызове — переопределение режима сессии плюс её cwd как корень рабочей области — в точности как нативные инструменты `write`/`edit`, и разрешает пути плана относительно того же корня. Без этого файловая система принуждения откатывается к корню развёртывания, из-за чего записи внутри рабочей области завершаются отказами `workspace-write` даже в сессии `danger-full-access`. Отказ `workspace-write` проявляется как `PatchError`, сообщение которой несёт текст бэкенда (структурированный маркер `[sandbox: …]` и поля эскалации в том же ходе не реализованы; если нужна эскалация, пользуйтесь нативными `write`/`edit`). - **Add не создаёт родительские каталоги.** Это соответствует нативному инструменту `write` (у `ctx.fs` нет mkdir); в ошибке называется недостающий каталог. - Нет нечёткого/со смещением сопоставления: локализация хунка точная → `trimEnd` → `trim`, причём намеренно (нечёткое сопоставление небезопасно для разрушающих операций; оно есть в дорожной карте). - Двоичные патчи отклоняются с понятной ошибкой. ## Разработка ```bash npm install npm run typecheck # against 0.2.0-rc.1 peers (devDependencies) npm run typecheck:0.2.0 # against real 0.2.0-rc.1 peer packages installed from the registry (dual-baseline proof) npm test # vitest, 92 tests npm run lint npm run build # lib/ npm run verify:source # static safety assertions (intent dance, no node:fs, …) npm run smoke # load-level smoke against a stub host ``` Ручная проверка на живом DSH (`dsh plugin --profile web add` → перезапуск → вызов инструмента в сессии) намеренно оставлена оператору. ## Лицензия MIT