dsh-patch-edit-plus 0.4.7 → 0.4.8

package/INSTALL.md

@@ -0,0 +1,179 @@
+# Installation Guide (Official DSH CLI)
+
+This guide uses only the official DSH `dsh plugin` command. That command installs the dependency into a profile and synchronizes `dsh.profile.bundles`. Do not replace it with plain `npm install`, a direct `pnpm add` in the profile, or manual edits to the profile manifest.
+
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [French installation guide](./INSTALL.fr.md)
+- [German installation guide](./INSTALL.de.md)
+- [Italian installation guide](./INSTALL.it.md)
+- [Russian installation guide](./INSTALL.ru.md)
+- [Spanish installation guide](./INSTALL.es.md)
+- [English README](./README.md)
+- [中文 README](./README.zh.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [French README](./README.fr.md)
+- [German README](./README.de.md)
+- [Italian README](./README.it.md)
+- [Russian README](./README.ru.md)
+- [Spanish README](./README.es.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+- [French changelog](./CHANGELOG.fr.md)
+- [German changelog](./CHANGELOG.de.md)
+- [Italian changelog](./CHANGELOG.it.md)
+- [Russian changelog](./CHANGELOG.ru.md)
+- [Spanish changelog](./CHANGELOG.es.md)
+
+The placeholders in this guide are:
+
+- `<profile>`: the DSH profile to modify, usually `web`;
+- `dsh-patch-edit-plus`: the npm package, the runtime plugin ID, and the id of the single row the bundle patch inserts.
+
+> **Supported DSH range: `>=0.1.0-rc.8` through `0.2.0-rc.2` (incl. desktop) — a single release, v0.4.0.**
+>
+> Check the running version with `dsh --version` first.
+>
+> | DSH version | Status | Notes |
+> | --- | --- | --- |
+> | `0.2.0-rc.1` ~ `0.2.0-rc.2` (incl. desktop) | supported | Same v0.4.0. |
+> | `0.1.0-rc.8` ~ `0.1.7-rc.2` | supported | Same v0.4.0 — no branch or dist-tag selection is needed. |
+>
+> Install `latest` on any supported host line: one version serves 0.1.x and 0.2.x alike. After publishing, the dist-tags `latest`, `dsh-0.2.0`, `dsh-0.1.7`, `dsh-0.1.5` and `dsh-0.1.2` all point to 0.4.0.
+
+## 0. Prerequisites and profile discovery
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+Use the profile named by your running DSH process. `web` is common, but the active `--profile` argument is authoritative.
+
+## 1. Official installation
+
+```bash
+dsh plugin --profile <profile> add dsh-patch-edit-plus -w
+```
+
+(the `-w` flag is required when the profile is a pnpm workspace root, as `web` is.)
+
+Install a specific version explicitly:
+
+```bash
+dsh plugin --profile <profile> add dsh-patch-edit-plus@0.4.0 -w
+```
+
+The official CLI updates the profile dependency, the lockfile, and `dsh.profile.bundles` automatically. Do not add a manual YAML row.
+
+### Supply-chain cooling period
+
+The DSH runtime uses pnpm 11, whose `minimumReleaseAge` policy may block a freshly published version with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`. Add the version to `minimumReleaseAgeExclude` in `~/.dsh/profiles/<profile>/pnpm-workspace.yaml`:
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-patch-edit-plus@0.4.0
+```
+
+## 2. Restart the host
+
+This is a **host-only** plugin: it registers a tool and a settings section on the host, and ships no browser half. Restart the DSH host process after installing or upgrading; refreshing the page is neither required nor sufficient.
+
+## 3. Upgrade
+
+```bash
+dsh plugin --profile <profile> update dsh-patch-edit-plus -w
+```
+
+Restart DSH afterwards.
+
+## 4. Local-path / `link:` registration (alternative)
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-patch-edit-plus": "link:<absolute path to dsh-patch-edit-plus>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-patch-edit-plus
+#            name: dsh-patch-edit-plus
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+Or use the official CLI with a local path (no network needed):
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-patch-edit-plus -w
+```
+
+Building from a source checkout uses these scripts:
+
+```bash
+npm install
+npm run build          # tsc -p tsconfig.build.json → lib/ + lib/types/
+npm run typecheck      # tsc -p tsconfig.json
+npm run verify:source  # source-level assertions
+npm run test           # vitest run
+npm run smoke          # _smoke/load-smoke.mjs
+```
+
+`lib/` is not committed, so a source checkout must be built before it can be registered by path. Publishing builds it automatically through the `prepublishOnly` hook, so a published tarball always contains compiled output.
+
+## 5. Verify installation
+
+```bash
+grep -n "dsh-patch-edit-plus" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-patch-edit-plus/package.json').version"
+```
+
+Check the official composition:
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+It must contain:
+
+```yaml
+- id: dsh-patch-edit-plus
+  name: dsh-patch-edit-plus
+```
+
+## 6. Verify the plugin
+
+After the restart, confirm in a session:
+
+1. The `apply_patch` tool is available to the model.
+2. A unified-diff patch applies, and the file content matches the diff exactly.
+3. A patch that fails verification leaves the workspace untouched — the engine verifies everything read-only before it writes anything.
+4. A Codex-style patch while `allowCodexPatch` is off returns an actionable hint telling the model how to enable the style or retry in unified diff, rather than a generic parse error.
+
+If another plugin already provides a tool named `apply_patch`, the three-layer conflict policy (`rename` by default, or `skip` / `fail`) decides the outcome. With the default `rename`, DSH startup is unaffected and the tool is registered under a suffixed name.
+
+## 7. Troubleshooting
+
+| Symptom | Action |
+| --- | --- |
+| `dsh` is not found | Install or enable the official DSH CLI. |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | Add the version to `minimumReleaseAgeExclude` in the profile's `pnpm-workspace.yaml`. |
+| `apply_patch` does not appear | Restart the host process and re-check the composition row. |
+| Tool name clash with another `apply_patch` provider | Set the conflict policy to `rename` (default), `skip`, or `fail` per the README. |
+| Codex syntax rejected | Enable `allowCodexPatch: true`, or resend the change as a unified diff. |
+| Hunk mismatch | Read the four-element diagnostic (file + hunk index, search origin, expected preview, actual excerpt) and re-emit the hunk with matching context. |
+
+## 8. Remove
+
+```bash
+dsh plugin --profile <profile> remove dsh-patch-edit-plus
+```
+
+Restart DSH afterwards.
+
+## License
+
+MIT

package/INSTALL.ru.md

@@ -0,0 +1,179 @@
+# Руководство по установке (официальный DSH CLI)
+
+В этом руководстве используется только официальная команда DSH `dsh plugin`. Она устанавливает зависимость в профиль и синхронизирует `dsh.profile.bundles`. Не заменяйте её простым `npm install`, прямым `pnpm add` в профиле или ручными правками манифеста профиля.
+
+- [Руководство по установке на английском](./INSTALL.md)
+- [Руководство по установке на китайском](./INSTALL.zh.md)
+- [Руководство по установке на японском](./INSTALL.ja.md)
+- [Руководство по установке на корейском](./INSTALL.ko.md)
+- [Руководство по установке на русском](./INSTALL.ru.md)
+- [Руководство по установке на французском](./INSTALL.fr.md)
+- [Руководство по установке на немецком](./INSTALL.de.md)
+- [Руководство по установке на итальянском](./INSTALL.it.md)
+- [Руководство по установке на испанском](./INSTALL.es.md)
+- [README на английском](./README.md)
+- [README на китайском](./README.zh.md)
+- [README на японском](./README.ja.md)
+- [README на корейском](./README.ko.md)
+- [README на русском](./README.ru.md)
+- [README на французском](./README.fr.md)
+- [README на немецком](./README.de.md)
+- [README на итальянском](./README.it.md)
+- [README на испанском](./README.es.md)
+- [История изменений](./CHANGELOG.md)
+- [История изменений на японском](./CHANGELOG.ja.md)
+- [История изменений на корейском](./CHANGELOG.ko.md)
+- [История изменений на русском](./CHANGELOG.ru.md)
+- [История изменений на французском](./CHANGELOG.fr.md)
+- [История изменений на немецком](./CHANGELOG.de.md)
+- [История изменений на итальянском](./CHANGELOG.it.md)
+- [История изменений на испанском](./CHANGELOG.es.md)
+
+Заполнители в этом руководстве:
+
+- `<profile>`: изменяемый профиль DSH, обычно `web`;
+- `dsh-patch-edit-plus`: npm-пакет, ID плагина во время выполнения и id единственной строки, которую вставляет патч бандла.
+
+> **Поддерживаемый диапазон DSH: от `0.1.0-rc.8` до `0.2.0-rc.2` (включая desktop) — единая версия v0.4.0.**
+>
+> Сначала проверьте запущенную версию командой `dsh --version`.
+>
+> | Версия DSH | Статус | Примечания |
+> | --- | --- | --- |
+> | `0.2.0-rc.1` ~ `0.2.0-rc.2` (включая desktop) | поддерживается | Та же v0.4.0. |
+> | `0.1.0-rc.8` ~ `0.1.7-rc.2` | поддерживается | Та же v0.4.0 — выбирать ветку или dist-tag не нужно. |
+>
+> На любой поддерживаемой линии хостов устанавливайте `latest`: одна версия обслуживает и 0.1.x, и 0.2.x. После публикации dist-tag'и `latest`, `dsh-0.2.0`, `dsh-0.1.7`, `dsh-0.1.5` и `dsh-0.1.2` будут указывать на 0.4.0.
+
+## 0. Предварительные требования и обнаружение профиля
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+Используйте профиль, названный вашим запущенным процессом DSH. `web` — распространённое имя, но определяющим является активный аргумент `--profile`.
+
+## 1. Официальная установка
+
+```bash
+dsh plugin --profile <profile> add dsh-patch-edit-plus -w
+```
+
+(флаг `-w` обязателен, когда профиль является корнем pnpm-workspace, как в случае с `web`.)
+
+Явная установка конкретной версии:
+
+```bash
+dsh plugin --profile <profile> add dsh-patch-edit-plus@0.4.0 -w
+```
+
+Официальная CLI автоматически обновляет зависимость профиля, lock-файл и `dsh.profile.bundles`. Не добавляйте строку YAML вручную.
+
+### Период охлаждения цепочки поставок
+
+Среда выполнения DSH использует pnpm 11, политика которого `minimumReleaseAge` может заблокировать только что опубликованную версию с ошибкой `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`. Добавьте версию в `minimumReleaseAgeExclude` в `~/.dsh/profiles/<profile>/pnpm-workspace.yaml`:
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-patch-edit-plus@0.4.0
+```
+
+## 2. Перезапустите хост
+
+Это плагин **только для хоста**: он регистрирует инструмент и секцию настроек на хосте и не содержит браузерной части. После установки или обновления перезапустите процесс хоста DSH; обновление страницы не требуется и не помогает.
+
+## 3. Обновление
+
+```bash
+dsh plugin --profile <profile> update dsh-patch-edit-plus -w
+```
+
+После этого перезапустите DSH.
+
+## 4. Регистрация по локальному пути / `link:` (альтернатива)
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-patch-edit-plus": "link:<absolute path to dsh-patch-edit-plus>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-patch-edit-plus
+#            name: dsh-patch-edit-plus
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+Либо используйте официальную CLI с локальным путём (сеть не нужна):
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-patch-edit-plus -w
+```
+
+Сборка из исходного чекаута использует эти скрипты:
+
+```bash
+npm install
+npm run build          # tsc -p tsconfig.build.json → lib/ + lib/types/
+npm run typecheck      # tsc -p tsconfig.json
+npm run verify:source  # source-level assertions
+npm run test           # vitest run
+npm run smoke          # _smoke/load-smoke.mjs
+```
+
+`lib/` не коммитится, поэтому исходный чекаут нужно собрать, прежде чем регистрировать его по пути. При публикации сборка выполняется автоматически хуком `prepublishOnly`, так что опубликованный tarball всегда содержит скомпилированный вывод.
+
+## 5. Проверка установки
+
+```bash
+grep -n "dsh-patch-edit-plus" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-patch-edit-plus/package.json').version"
+```
+
+Проверьте официальную композицию:
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+Она должна содержать:
+
+```yaml
+- id: dsh-patch-edit-plus
+  name: dsh-patch-edit-plus
+```
+
+## 6. Проверка плагина
+
+После перезапуска подтвердите в сессии:
+
+1. Инструмент `apply_patch` доступен модели.
+2. Патч в виде unified diff применяется, и содержимое файла в точности совпадает с диффом.
+3. Патч, не прошедший проверку, оставляет рабочую область нетронутой — движок проверяет всё в режиме только чтение, прежде чем что-либо записывать.
+4. Патч в стиле Codex при выключенном `allowCodexPatch` возвращает действенную подсказку, объясняющую модели, как включить этот стиль или повторить попытку в unified diff, а не общую ошибку разбора.
+
+Если другой плагин уже предоставляет инструмент с именем `apply_patch`, исход определяет трёхуровневая политика конфликтов (`rename` по умолчанию, либо `skip` / `fail`). При значении по умолчанию `rename` запуск DSH не страдает, а инструмент регистрируется под именем с суффиксом.
+
+## 7. Устранение неполадок
+
+| Симптом | Действие |
+| --- | --- |
+| `dsh` не найден | Установите или включите официальную CLI DSH. |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | Добавьте версию в `minimumReleaseAgeExclude` в `pnpm-workspace.yaml` профиля. |
+| `apply_patch` не появляется | Перезапустите процесс хоста и снова проверьте строку композиции. |
+| Конфликт имени инструмента с другим провайдером `apply_patch` | Установите политику конфликтов в `rename` (по умолчанию), `skip` или `fail`, см. README. |
+| Синтаксис Codex отклонён | Включите `allowCodexPatch: true` или отправьте изменение заново в виде unified diff. |
+| Несовпадение хунка | Прочтите четырёхэлементную диагностику (файл + индекс хунка, начало поиска, ожидаемое превью, фактический фрагмент) и заново отправьте хунк с совпадающим контекстом. |
+
+## 8. Удаление
+
+```bash
+dsh plugin --profile <profile> remove dsh-patch-edit-plus
+```
+
+После этого перезапустите DSH.
+
+## Лицензия
+
+MIT

package/INSTALL.zh.md

@@ -0,0 +1,179 @@
+# 安装指南（官方 DSH CLI）
+
+本指南只使用官方 `dsh plugin` 命令。该命令会把依赖装入 profile 并同步 `dsh.profile.bundles`。请勿改用裸 `npm install`、在 profile 里直接 `pnpm add`，或手工编辑 profile 清单。
+
+- [English installation guide](./INSTALL.md)
+- [中文安装指南](./INSTALL.zh.md)
+- [日本語インストールガイド](./INSTALL.ja.md)
+- [한국어 설치 안내](./INSTALL.ko.md)
+- [法语安装指南](./INSTALL.fr.md)
+- [德语安装指南](./INSTALL.de.md)
+- [意大利语安装指南](./INSTALL.it.md)
+- [俄语安装指南](./INSTALL.ru.md)
+- [西班牙语安装指南](./INSTALL.es.md)
+- [English README](./README.md)
+- [中文 README](./README.zh.md)
+- [日本語 README](./README.ja.md)
+- [한국어 README](./README.ko.md)
+- [法语 README](./README.fr.md)
+- [德语 README](./README.de.md)
+- [意大利语 README](./README.it.md)
+- [俄语 README](./README.ru.md)
+- [西班牙语 README](./README.es.md)
+- [Changelog](./CHANGELOG.md)
+- [日本語 changelog](./CHANGELOG.ja.md)
+- [한국어 changelog](./CHANGELOG.ko.md)
+- [法语 changelog](./CHANGELOG.fr.md)
+- [德语 changelog](./CHANGELOG.de.md)
+- [意大利语 changelog](./CHANGELOG.it.md)
+- [俄语 changelog](./CHANGELOG.ru.md)
+- [西班牙语 changelog](./CHANGELOG.es.md)
+
+本指南中的占位符：
+
+- `<profile>`：要改动的 DSH profile，通常是 `web`；
+- `dsh-patch-edit-plus`：npm 包名、运行时插件 ID，同时也是 bundle 补丁所插入的那一行 id。
+
+> **支持的 DSH 范围：`0.1.0-rc.8` 至 `0.2.0-rc.2`（含 desktop）—— 单一版本 v0.4.0。**
+>
+> 先用 `dsh --version` 确认当前版本。
+>
+> | DSH 版本 | 状态 | 说明 |
+> | --- | --- | --- |
+> | `0.2.0-rc.1` ~ `0.2.0-rc.2`（含 desktop） | 支持 | 同一个 v0.4.0。 |
+> | `0.1.0-rc.8` ~ `0.1.7-rc.2` | 支持 | 同一个 v0.4.0 —— 无需选择分支或 dist-tag。 |
+>
+> 任何受支持宿主线一律安装 `latest`：一个版本同时服务 0.1.x 与 0.2.x。发布后 dist-tag `latest`、`dsh-0.2.0`、`dsh-0.1.7`、`dsh-0.1.5`、`dsh-0.1.2` 将全部指向 0.4.0。
+
+## 0. 前置条件与 profile 探查
+
+```bash
+echo "DSH_HOME=${DSH_HOME:-$HOME/.dsh}"
+dsh --version
+ls "${DSH_HOME:-$HOME/.dsh}/profiles"
+```
+
+请使用正在运行的 DSH 进程所使用的那个 profile。`web` 很常见，但以实际生效的 `--profile` 参数为准。
+
+## 1. 官方安装
+
+```bash
+dsh plugin --profile <profile> add dsh-patch-edit-plus -w
+```
+
+（当 profile 是 pnpm workspace 根时，如 `web`，`-w` 是必需的。）
+
+显式安装指定版本：
+
+```bash
+dsh plugin --profile <profile> add dsh-patch-edit-plus@0.4.0 -w
+```
+
+官方 CLI 会自动更新 profile 依赖、锁文件与 `dsh.profile.bundles`。不要手工添加 YAML 行。
+
+### 供应链冷却期
+
+DSH 运行时使用 pnpm 11，其 `minimumReleaseAge` 策略可能拦截刚发布的版本并报 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`。把该版本加入 `~/.dsh/profiles/<profile>/pnpm-workspace.yaml` 的 `minimumReleaseAgeExclude`：
+
+```yaml
+minimumReleaseAgeExclude:
+  - dsh-patch-edit-plus@0.4.0
+```
+
+## 2. 重启宿主
+
+本插件是**纯宿主半身**：只在宿主侧注册一个工具与一个设置区，不附带浏览器半身。安装或升级后请重启 DSH 宿主进程；刷新页面既非必需，也不足以生效。
+
+## 3. 升级
+
+```bash
+dsh plugin --profile <profile> update dsh-patch-edit-plus -w
+```
+
+升级后重启 DSH。
+
+## 4. 本地路径 / `link:` 注册（备选）
+
+```bash
+#    ~/.dsh/profiles/<profile>/package.json dependencies:
+#      "dsh-patch-edit-plus": "link:<absolute path to dsh-patch-edit-plus>"
+#    ~/.dsh/profiles/<profile>/cordis.patch.yml:
+#      - insert:
+#          - id: dsh-patch-edit-plus
+#            name: dsh-patch-edit-plus
+cd ~/.dsh/profiles/<profile> && pnpm install && dsh web
+```
+
+或用官方 CLI 直接指定本地路径（无需联网）：
+
+```bash
+dsh plugin --profile <profile> add /absolute/path/to/dsh-patch-edit-plus -w
+```
+
+从源码检出构建时用以下脚本：
+
+```bash
+npm install
+npm run build          # tsc -p tsconfig.build.json → lib/ + lib/types/
+npm run typecheck      # tsc -p tsconfig.json
+npm run verify:source  # 源码级断言
+npm run test           # vitest run
+npm run smoke          # _smoke/load-smoke.mjs
+```
+
+`lib/` 不入库，因此源码检出必须先构建才能按路径注册。发布时由 `prepublishOnly` 钩子自动构建，因此已发布的 tarball 一定包含编译产物。
+
+## 5. 校验安装
+
+```bash
+grep -n "dsh-patch-edit-plus" \
+  "${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/package.json"
+node -p "require('${DSH_HOME:-$HOME/.dsh}/profiles/<profile>/node_modules/dsh-patch-edit-plus/package.json').version"
+```
+
+检查官方装配：
+
+```bash
+dsh --profile <profile> --dump-default-config
+```
+
+其中必须包含：
+
+```yaml
+- id: dsh-patch-edit-plus
+  name: dsh-patch-edit-plus
+```
+
+## 6. 验证插件
+
+重启后，在会话中确认：
+
+1. 模型可用的工具里出现 `apply_patch`。
+2. 一个 unified diff 补丁可以应用，且文件内容与 diff 完全一致。
+3. 校验失败的补丁不会改动工作区——引擎在写入任何东西之前已完成全部只读校验。
+4. 在 `allowCodexPatch` 关闭时提交 Codex 风格补丁，会返回可操作的提示（告知如何启用该语法，或以 unified diff 重试），而不是笼统的解析错误。
+
+若已有其他插件提供了名为 `apply_patch` 的工具，三层冲突策略（默认 `rename`，另有 `skip` / `fail`）决定结果。默认 `rename` 下 DSH 启动不受影响，本工具会以带后缀的名字注册。
+
+## 7. 故障排查
+
+| 现象 | 处理 |
+| --- | --- |
+| 找不到 `dsh` | 安装或启用官方 DSH CLI。 |
+| `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | 把该版本加入该 profile 的 `pnpm-workspace.yaml` 中的 `minimumReleaseAgeExclude`。 |
+| `apply_patch` 未出现 | 重启宿主进程，并重新检查装配行。 |
+| 与其他 `apply_patch` 提供方名字冲突 | 按 README 设置冲突策略 `rename`（默认）/ `skip` / `fail`。 |
+| Codex 语法被拒绝 | 开启 `allowCodexPatch: true`，或改用 unified diff 重发该改动。 |
+| hunk 不匹配 | 阅读四元诊断（文件 + hunk 序号、搜索起点、期望片段预览、实际片段），并按匹配的上下文重新提交该 hunk。 |
+
+## 8. 卸载
+
+```bash
+dsh plugin --profile <profile> remove dsh-patch-edit-plus
+```
+
+卸载后重启 DSH。
+
+## 许可
+
+MIT

package/README.md

@@ -21,12 +21,12 @@ Tool capabilities are identical on every line: one `apply_patch` tool, git/unifi
 
 ## Why patch at all? (tool routing guide)
 
-The tool description explicitly routes the model:
+Two surfaces route the model, mirroring what DSH 0.2.2-rc.1 ships for its own built-in `apply_patch`:
 
-- **Single small change in one already-read file** → prefer the native `edit` tool (a patch costs more tokens than a literal edit).
-- **Small change inside a LARGE file** → `apply_patch` (no need to echo the whole file).
-- **Batched changes across MANY files** → `apply_patch` (one call, verified atomically).
-- **New file with substantial content / delete / rename** → `apply_patch`.
+- **Tool description** — one line, repeated on every call: prefer `apply_patch` over separate `edit` calls when a change spans several files, several separated regions of one file, or adds/deletes/moves files. A single small replacement in an already-read file is still cheaper through the native `edit` tool.
+- **System-prompt section** (`plugin:patch-edit-plus:apply_patch`, order 1350, right after `tool:edit`) — the full guidance: give every hunk enough surrounding context lines to match exactly one place in the current file; every hunk is matched against the current content before anything is written, so a rejected patch changes nothing and retrying with a corrected patch beats falling back to many small edits; once writing starts, operations stop at the first failure.
+
+The section is emitted only while the tool is registered in the acting scope, and `auto` skips it when rename avoidance had to step aside for another `apply_patch` (a host-shipped one, for example) so the two guidance texts never compete. `guidance: 'auto' | 'on' | 'off'` controls this; the default is `auto`.
 
 ## Installation
 
@@ -98,6 +98,7 @@ Enable with `allowCodexPatch: true`. When a Codex patch arrives while disabled,
 | `deleteBackend` | `shell` | `shell` or `none` (Delete/Move return a structured error). |
 | `shellDialect` | `auto` | `auto` (pwsh on win32) / `posix` / `pwsh`. |
 | `deleteCommand` / `moveCommand` | built-in | Custom command templates. Paths still arrive **only via env** (`DSH_PATCH_TARGET` / `DSH_PATCH_SOURCE`); never interpolate them into the command string. |
+| `guidance` | `auto` | System-prompt guidance: `auto` (skip when the tool had to be renamed), `on`, `off`. |
 | `dryRunByDefault` | `false` | Treat calls as dry runs unless `dryRun: false`. |
 | `followSymlinks` | `false` | Allow patch paths to traverse symlinks. |
 | `maxFiles` | `50` | Max file sections per patch. |

package/README.zh.md

@@ -21,12 +21,12 @@
 
 ## 工具路由指引（为什么该用谁）
 
-工具 description 内置了明确的路由规则：
+路由分两个面，形态对齐 DSH 0.2.2-rc.1 给自家内置 `apply_patch` 的做法：
 
-- **单个已读文件里的单点小改** → 优先原生 `edit`（patch 反而多花 token）。
-- **大文件里的小改动** → `apply_patch`（无需回显整个文件）。
-- **跨文件批量改动** → `apply_patch`（一次调用、原子验证）。
-- **新建大内容文件 / 删除 / 重命名** → `apply_patch`。
+- **工具 description** —— 每次调用都可见的一句话：当改动跨多个文件、同一文件的多个分离区域，或涉及新增/删除/移动文件时，优先用 `apply_patch` 而不是多次 `edit`；单个已读文件里的单点小替换仍然用原生 `edit` 更便宜。
+- **系统提示段**（`plugin:patch-edit-plus:apply_patch`，order 1350，紧跟在 `tool:edit` 之后）—— 完整指导：每个 hunk 给足上下文字段，确保只匹配文件中的一处；所有 hunk 在任何写入之前先对着当前内容匹配，因此被拒绝的 patch 不改变任何文件，修正后重试比退回多次小改更划算；一旦开始写入，首个失败即停。
+
+该段只在工具确实注册于当前作用域时输出；`auto` 在因重名避让而改名为其他名字时（例如宿主已自带 `apply_patch`）不再注入，避免两套提示互相竞争。`guidance: 'auto' | 'on' | 'off'` 控制此行为，默认为 `auto`。
 
 ## 安装
 
@@ -97,6 +97,7 @@ dsh web --dump-config   # 确认插件行出现
 | `deleteBackend` | `shell` | `shell` 或 `none`（Delete/Move 返回结构化错误）。 |
 | `shellDialect` | `auto` | `auto`（win32 上 pwsh）/ `posix` / `pwsh`。 |
 | `deleteCommand` / `moveCommand` | 内置 | 自定义命令模板。路径仍然**只经 env** 传入（`DSH_PATCH_TARGET` / `DSH_PATCH_SOURCE`），请勿把路径插值进命令串。 |
+| `guidance` | `auto` | 系统提示段：`auto`（工具被改名时跳过）/ `on` / `off`。 |
 | `dryRunByDefault` | `false` | 默认按 dry run 处理，除非调用显式传 `dryRun: false`。 |
 | `followSymlinks` | `false` | 允许补丁路径穿越符号链接。 |
 | `maxFiles` | `50` | 单补丁最大文件段数。 |

package/dsh.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dsh-patch-edit-plus",
   "name": "dsh-patch-edit-plus",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": {
     "en": "Patch-style file editing: one apply_patch tool for git/unified diff (default) and Codex apply_patch syntax (opt-in), with all-or-nothing application and sandbox-aware delete/move.",
     "zh": "补丁风格文件编辑：单个 apply_patch 工具，接受 git/unified diff（默认）与 Codex apply_patch 语法（可选开启），全量验证后原子应用，删除/移动走沙箱感知 shell。"

package/lib/config.js

@@ -18,6 +18,7 @@ export const Config = z.object({
     shellDialect: z.union(['auto', 'posix', 'pwsh']).default('auto'),
     deleteCommand: z.string(),
     moveCommand: z.string(),
+    guidance: z.union(['auto', 'on', 'off']).default('auto'),
     dryRunByDefault: z.boolean().default(false),
     followSymlinks: z.boolean().default(false),
     maxFiles: z.number().step(1).min(1).max(500).default(50),
@@ -45,6 +46,7 @@ export function resolveConfig(config) {
         shellDialect: c.shellDialect ?? 'auto',
         deleteCommand: typeof c.deleteCommand === 'string' && c.deleteCommand !== '' ? c.deleteCommand : undefined,
         moveCommand: typeof c.moveCommand === 'string' && c.moveCommand !== '' ? c.moveCommand : undefined,
+        guidance: c.guidance ?? 'auto',
         dryRunByDefault: c.dryRunByDefault ?? false,
         followSymlinks: c.followSymlinks ?? false,
         maxFiles: c.maxFiles ?? 50,