dsh-custom-mode 2.2.5 → 2.2.6

package/README.i18n.yaml

@@ -1,5 +1,5 @@
 # 双语配对一致性记录：两侧在「上次确认一致」时的 git blob 哈希。
 # 两份文档权威相同——改完任意一侧，请把另一侧也改掉，然后重新记录：
 #   node tools/verify-translation-pairing.mjs --write
-README.md: f111de149dd80c8d3e73f5c6ef0d43e8af6d3748
-README.zh.md: ede6eabf8c6b7383e60158fbe76e6f86cb7c00d4
+README.md: f43403111d49476d68271c74036aec063e8b3417
+README.zh.md: 43c26010c77fca3121c1c1906c40880c710c16e9

package/README.md

@@ -19,80 +19,78 @@ Edit a DeepSeek Harness (`dsh`) custom mode: system prompt, base mode, and plugi
 </tr>
 </table>
 
-## Install
+## Install and make the first request
 
-Pin the version. A bare name can install an older build during pnpm's release cooldown. Details: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
+These instructions are for version `2.2.6`. Check the [exact-host results and acceptance limits](docs/CURRENT_COMPATIBILITY.md) before installing or updating.
+
+Start with an installed [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and a model configured through its own interface. Check `dsh --version` against the exact hosts in the compatibility record. This package does not install the host or configure model credentials.
+
+### Web / CLI
+
+Pin the plugin version; a bare name can resolve an older build during pnpm's release cooldown:
 
 ```sh
-dsh plugin --profile web add dsh-custom-mode@2.2.5
+dsh --version
+dsh plugin --profile web add dsh-custom-mode@2.2.6
 ```
 
-Restart the process that serves the profile. Success means Settings → Custom mode shows `v2.2.5`, and the session mode picker offers Custom mode without a broken-preset warning.
+Restart the process that serves this Web profile using its usual launcher. For a local CLI instance, the existing launch form is `dsh web --port 3081 --no-open`; use a free port and open the URL printed by that process. Restart only that instance. Installing a bundle does not refresh an already running host.
+
+### Desktop and Windows
 
-Desktop app: its in-app Plugins page is the installation entry point; the CLI cannot modify `profiles/desktop`. This release has not been verified on Windows/Electron.
+In the desktop app, use its **Plugins** page to install `dsh-custom-mode@2.2.6`, then restart the app. This project's scripts deliberately refuse `--profile desktop`; do not modify its profile files by hand. Windows/Electron acceptance remains separate from Web acceptance; see the compatibility record.
 
-On Windows, `install.sh` is bash and it needs a `dsh` executable on `PATH`. Otherwise use the `dsh` shipped with DeepSeek Harness, or `node node_modules/@deepseek-ai/dsh/lib/bin.js`.
+On Windows, the npm installation above can use the host's `dsh` command from PowerShell. Only the optional clone installer requires Git Bash (plus Node.js and npm). If `dsh` is not on PATH, use the host's supplied launcher, or replace `dsh` with `node "<host-install>/node_modules/@deepseek-ai/dsh/lib/bin.js"`. Do not point that path at this plugin's directory unless the host is actually installed there.
 
-The GitHub Release also provides a packed plugin (`dsh-custom-mode-2.2.5.tgz`), a preset-only import archive, and `SHA256SUMS`. Verify the checksum, then install the packed plugin with `dsh plugin --profile web add ./dsh-custom-mode-2.2.5.tgz`. The preset-only archive does not include the settings plugin.
+### Verify the whole path
 
-## Use
+1. Open Settings → Custom mode and check the displayed version. A page that opens is only the first check.
+2. Scroll to **New assistant at the bottom of the page**. When the built-in `custom` assistant already exists, this section follows its editor. Choose a starting setting such as Writing, enter a recognizable name, and select New assistant. The created assistant becomes the editing target.
+3. Set a temporary prompt such as `For the next readiness check, reply with exactly CUSTOM_MODE_READY.` Save and wait for the page to confirm that it was applied. If it says the file was saved but application failed, select Retry activation before continuing.
+4. Start a **new session**, open its mode/assistant selector, and explicitly choose that named assistant. Send `Readiness check.` through a model already configured in DSH.
+5. Success means the assistant is selectable without a broken-preset warning and returns the expected readiness reply without a prompt-assembly error. Restore your intended prompt after the check. If it fails, use the [current recovery steps](docs/TROUBLESHOOTING.md#current-recovery-steps).
 
-1. Open Settings → Custom mode.
-2. Edit the system prompt. Save is directly under the editor.
-3. For example, select Writing, create an assistant, then edit its prompt; or change the current assistant’s base mode and tool switches, then save.
-4. A new session uses this assistant when `settings.yaml` has no `agent-presets.default` yet. An existing value is left as it is. Flow-style, scalar, and alias `agent-presets` values are preserved without inserting YAML into them.
+## What each choice means
 
-The prompt is `prompt.md`. The next time a model step is assembled, that file is read again. History can load an older draft into the editor; loading does not write. A save computed against an older copy is refused when the file changed underneath. The model can change the same file only through `custom_prompt`, which asks first.
+The assistant selected on the settings page is the **one being edited**. Selecting or creating it does not change the assistant used by a new session. On first activation, the plugin may fill a missing default with the built-in `custom` assistant; an existing default is preserved. A newly created Writing assistant still needs to be chosen in the session selector.
 
-The page is two branches. This assistant edits the one you have open, and all five base modes can be chosen. New assistant writes only when you click New assistant: Coding, Writing, and Chat stay selectable, and only the official Standard mode is lit. The other four official modes are dim and cannot be chosen there.
+Choose the creation starting settings first; a new assistant starts from Standard. After creation, its base mode and individual plugin switches can be adjusted in its editor.
 
-| Posture | After create |
+| Starting settings | Initial behavior |
 | --- | --- |
-| Develop | Official Standard mode, tools as shipped. |
-| Write | Official Standard mode. Terminal off, file tools on. |
-| Chat | Official Standard mode. Files and terminal off. |
+| Coding | Official Standard mode, tools as shipped. |
+| Writing | Official Standard mode; terminal off, file tools on. |
+| Chat | Official Standard mode; files and terminal off. |
 
-## Boundaries
+The prompt is stored in `prompt.md` and reread when the next model step is assembled. History and file import load a draft; saving writes it. A stale save is refused when the underlying file changed. `custom_prompt` asks for approval before it writes the same file. Turning off the Identity/persona row also turns off this prompt's injection.
 
-- It does not replace Standard, PTC, Minimal, or Creator.
-- It does not ship a role-play preset.
-- It does not run in the desktop profile from the CLI. Headless mode will not start a session that uses an agent preset.
+## Upgrade, clone development, and removal
 
-## Compatibility
+The fixed-version npm path above is the normal installation path. Release assets, once published, also include `dsh-custom-mode-2.2.6.tgz`, a preset-only import archive, and `SHA256SUMS`. Verify a downloaded archive's hash before installing it; the preset-only archive does not include the settings page.
 
-Declared range: `>=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0 || >=0.2.1-alpha.1 <0.3.0-0`
+For a clone, `./install.sh --profile web` keeps the source-linked development workflow. It requires Node.js, npm, Bash and the host CLI. Before changing the profile, it prepares the new package and an archive of the **actual installed old package** with offline `npm pack --ignore-scripts`. It preserves existing prompt, metadata and composition, and refreshes managed code only after installation checks. A failed replacement reinstalls the local old archive and restores refreshed code. Files newly created by the attempt are retained at printed recovery paths when rolled back. An unverified rollback exits with an error and keeps the archive and logs at the printed transaction path. A broken old install that cannot be archived is rejected before replacement. The script is not a substitute for the desktop plugin manager.
 
-On 2026-10-17, npm `latest` names `0.2.0-rc.2`, `alpha` names `0.2.1-alpha.5`, and `next` names `0.2.1-rc.2`. Upstream has not published a final stable version yet.
+`./uninstall.sh` removes the plugin but keeps assistant data. `--purge` explicitly deletes the managed assistant directories and their prompts; keep your own backup before using it.
 
-| dsh | Channel | Checked for 2.2.5 |
-| --- | --- | --- |
-| `0.2.0-rc.2` | npm `latest` | Exact npm host, packed plugin load, API lifecycle, settings and picker in an isolated Linux Web profile |
-| `0.2.1-alpha.5` | npm `alpha` | The same isolated checks, against this host's own preset declarations |
-| `0.2.1-rc.2` | npm `next` | The same isolated checks, against this host's own preset declarations |
-| `0.1.7-rc.2` | earlier declared line | Kept in the CI regression matrix |
+## Compatibility and versioning
 
-Release waits for the unit, boot, and browser workflows. To reproduce against an already installed exact host:
+Declared host range: `>=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0 || >=0.2.1-alpha.1 <0.3.0-0 || >=0.2.2-alpha.2 <0.3.0-0`
 
-```sh
-node tools/compat-check.mjs --host-install /path/to/host --out /tmp/custom-mode-check
-node tools/runtime-check.mjs --host-install /path/to/host --out /tmp/custom-mode-check --browser /path/to/chrome
-```
+The plugin version is its own stable `x.y.z` line; it does not mirror DSH. On 2026-10-27 the public host tags were `latest=0.2.1-rc.2`, `next=0.2.1-rc.4`, and `alpha=0.2.2-alpha.2`. Tags move; the declared range and completed checks are separate facts. See [exact versions, acceptance limits and historical evidence](docs/CURRENT_COMPATIBILITY.md) for the tested scope.
 
-Both tools use a generated home and ordinary mock prompts. The runtime check exercises all five base modes, repeated saves, uninstall, reinstall, data preservation, and repeated installation. No model calls are needed. Windows/Electron desktop and real model or GPU execution are unverified. See [the exact coverage](docs/CURRENT_COMPATIBILITY.md).
+Release requires the compatibility and browser workflows. The unit runner, real prompt-component checks, packed-install checks and browser checks cover different boundaries. Windows/Electron, a real model response and GPU execution must each have their own evidence; they are not inferred from a page screenshot or unit count. Headless mode does not start an agent-preset session.
 
 ## Plugin markets
 
-`dshmarket`, DSH Plugin Hub (`dsh-plugin`), and DSH Plugin Store (`dshmarketplace-plugin`) use different catalogs but install the same profile bundle. The root npm manifest provides `dsh.bundle.patch`, the browser export, the public repository, and matching compatibility ranges; no extra runtime adapter or build script is needed.
-
-Run `node tools/market-check.mjs --out /tmp/custom-mode-markets.json` to check their public discovery data. An inaccessible catalog or an unverified/stale listing is reported explicitly. The tool never runs catalog-provided shell commands or submits a listing. [Market interfaces and limits](docs/MARKETPLACES.md).
+The documented catalogs use different discovery and approval rules. Their 2026-10-09 listing results are historical, so a package may not be searchable in every market today. The fixed-version installation above remains the direct path. [Market interfaces and limits](docs/MARKETPLACES.md) explains the read-only adapter; it never executes catalog-provided shell commands or submits a listing.
 
 ## Docs
 
-- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — wrong version installed, base mode unavailable, half-finished upgrade
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — where the prompt is read, and which host calls this package depends on
-- [docs/PUBLISHING.md](docs/PUBLISHING.md) — tags and release
-- [CONTRIBUTING.md](CONTRIBUTING.md) — people
-- [AGENTS.md](AGENTS.md) — agents
+- [Troubleshooting](docs/TROUBLESHOOTING.md) — current recovery first, historical incidents below.
+- [Architecture](docs/ARCHITECTURE.md) — prompt reading and host coupling points.
+- [Publishing](docs/PUBLISHING.md) — existing gated release path and read-back evidence.
+- [Contributing](CONTRIBUTING.md) — isolated development and checks.
+- [AGENTS.md](AGENTS.md) — repository instructions for agents.
 
 ## License
 

package/README.zh.md

@@ -19,80 +19,78 @@
 </tr>
 </table>
 
-## 安装
+## 安装并完成首次请求
 
-钉版本。只写包名时，pnpm 的发布冷却期可能装到旧版。细节见 [docs/TROUBLESHOOTING.zh.md](docs/TROUBLESHOOTING.zh.md)。
+本说明适用于版本 `2.2.6`。安装或更新前，先核对[精确宿主结果与验收边界](docs/CURRENT_COMPATIBILITY.zh.md)。
+
+先安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)，并在宿主自己的界面中配置可用模型。用 `dsh --version` 对照兼容记录中的精确宿主版本。本插件不安装宿主，也不配置模型凭据。
+
+### Web / CLI
+
+钉住插件版本；只写包名可能在 pnpm 发布冷却期解析到旧版：
 
 ```sh
-dsh plugin --profile web add dsh-custom-mode@2.2.5
+dsh --version
+dsh plugin --profile web add dsh-custom-mode@2.2.6
 ```
 
-重启为这个 profile 提供服务的进程。成功判定：设置 → 自定义模式显示 `v2.2.5`，会话模式选择器出现自定义模式，且没有预设损坏告警。
+用原有启动方式重启为该 Web profile 提供服务的进程。本地 CLI 的既有启动形式是 `dsh web --port 3081 --no-open`；选择空闲端口，打开该进程打印的地址。只重启这个实例。安装 bundle 不会刷新已经运行的宿主。
+
+### 桌面端与 Windows
 
-桌面端从应用里的插件页安装。CLI 不能改 `profiles/desktop`。本版未实测 Windows/Electron。
+在桌面应用的 **Plugins（插件）** 页安装 `dsh-custom-mode@2.2.6`，然后重启应用。本项目脚本明确拒绝 `--profile desktop`，不要手改它的 profile 文件。Windows/Electron 与 Web 分别验收，详见兼容记录。
 
-在 Windows 上，`install.sh` 是 bash，而且 PATH 里要有 `dsh`。否则用 DeepSeek Harness 自带的 `dsh`，或 `node node_modules/@deepseek-ai/dsh/lib/bin.js`。
+Windows 上可在 PowerShell 中用宿主提供的 `dsh` 执行上面的 npm 安装命令。只有可选的 clone 安装脚本需要 Git Bash，另需 Node.js 和 npm。PATH 中没有 `dsh` 时，使用宿主自带启动器，或将 `dsh` 替换为 `node "<host-install>/node_modules/@deepseek-ai/dsh/lib/bin.js"`。除非宿主确实装在本插件目录中，否则不要把这个路径指向插件目录。
 
-GitHub Release 另附插件包 `dsh-custom-mode-2.2.5.tgz`、仅供预设导入的归档与 `SHA256SUMS`。核对校验和后，可用 `dsh plugin --profile web add ./dsh-custom-mode-2.2.5.tgz` 安装插件包。仅供预设导入的归档不包含设置插件。
+### 验证完整路径
 
-## 使用
+1. 打开设置 → 自定义模式，检查显示版本。页面能打开只是第一步。
+2. 滚动到**页面底部的「新建助手」区**。已有内置 `custom` 助手时，该区位于编辑区之后。选择写作等起步设置，输入容易辨认的名称，再点「新增助手」；新建的助手会成为编辑对象。
+3. 临时把提示词设为 `下一次就绪检查只回复 CUSTOM_MODE_READY。`，保存并等页面确认已应用。若提示文件已保存但应用失败，先点「重试生效」。
+4. 新建一个**会话**，打开该会话的模式/助手选择器，明确选择刚才命名的助手。通过 DSH 中已经配置的模型发送 `就绪检查。`
+5. 成功意味着助手可以选择、没有预设损坏告警，并返回预期就绪回复且不出现提示词组装错误。检查后恢复自己的提示词。失败时先看[当前自救步骤](docs/TROUBLESHOOTING.zh.md#当前自救步骤)。
 
-1. 打开设置 → 自定义模式。
-2. 改系统提示词。保存按钮在编辑器下面。
-3. 典型用法：选写作姿态新增助手，再改提示词；或调整当前助手的基础模式和工具开关后保存。
-4. `settings.yaml` 里还没有 `agent-presets.default` 时，新会话用这个助手。已经写过的值保持原样。`agent-presets` 使用行内对象、标量或别名时也原样保留，不向里面插入 YAML。
+## 各项选择分别做什么
 
-提示词是 `prompt.md`。下一步组装模型输入时会重读这个文件。历史可以把旧稿载入编辑器；载入不落盘。打开页面之后文件被改过时，这一次保存会被拒绝。模型要改同一份文件，只能走 `custom_prompt`，并且先问过你。
+设置页选中的助手是**正在编辑的对象**。选中或新建它不会改变新会话使用的助手。首次激活时，插件可能把缺失的默认值补为内置 `custom`；已经存在的默认值保持不变。新建写作助手后，仍需在会话选择器中选它。
 
-页面分成两支。当前助手改的是已经打开的这一位，基础模式五档都可以点。新建助手只在点「新增助手」时写入：开发、写作、聊天可以点，工具底只有官方标准模式是亮的。其余四档是暗的，在这一支里点不了。
+先选择新建时的起步设置；新助手以标准模式创建。创建后，可以在它的编辑区调整基础模式与各项插件开关。
 
-| 姿态 | 新建之后 |
+| 起步设置 | 初始行为 |
 | --- | --- |
-| 开发 | 官方标准模式，工具按出厂。 |
-| 写作 | 官方标准模式。终端关，文件工具开。 |
-| 聊天 | 官方标准模式。文件和终端关。 |
+| 开发 | 官方标准模式，工具按出厂设置。 |
+| 写作 | 官方标准模式；终端关闭，文件工具开启。 |
+| 聊天 | 官方标准模式；文件与终端关闭。 |
 
-## 边界
+提示词保存在 `prompt.md`，下一步组装模型输入时会重读。历史与文件导入先载入草稿，保存才落盘。底层文件已变化时，过期保存会被拒绝。`custom_prompt` 写同一个文件前需要批准。关闭身份/persona 行也会关闭该提示词的注入。
 
-- 不替换标准、PTC、极简、创造。
-- 不附带角色扮演预设。
-- 不用 CLI 改桌面端 profile。headless 不会启动使用 agent preset 的会话。
+## 升级、clone 开发与卸载
 
-## 兼容
+上面的固定版本 npm 命令是普通安装入口。发布完成后，Release 还会提供 `dsh-custom-mode-2.2.6.tgz`、仅供预设导入的归档和 `SHA256SUMS`。安装下载的归档前先核对散列；仅供预设导入的归档没有设置页。
 
-声明范围：`>=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0 || >=0.2.1-alpha.1 <0.3.0-0`
+clone 后可用 `./install.sh --profile web` 保留源码链接的开发方式，需要 Node.js、npm、Bash 和宿主 CLI。它在改动 profile 前，通过离线 `npm pack --ignore-scripts` 准备新包，并归档**实际已安装的旧包**。已有提示词、元数据与组成保持原样，安装自检通过后才刷新受管代码。替换失败时，用本地旧归档重新安装并恢复已刷新的代码；本次新建文件在回滚时留有恢复副本，路径会打印。回滚未验证则报错，并在打印的事务目录保留旧包和日志。旧安装损坏、无法归档时，脚本在替换前中止。这个脚本不能代替桌面应用的插件管理器。
 
-2026-10-17 核对 npm：`latest` 是 `0.2.0-rc.2`，`alpha` 是 `0.2.1-alpha.5`，`next` 是 `0.2.1-rc.2`。上游尚未发布去掉预发布后缀的正式稳定版。
+`./uninstall.sh` 移除插件但保留助手数据。`--purge` 明确删除受管助手目录及提示词，使用前请自行备份。
 
-| dsh | 通道 | 2.2.5 核对 |
-| --- | --- | --- |
-| `0.2.0-rc.2` | npm `latest` | 精确 npm 宿主、打包加载、API 生命周期、隔离 Linux Web profile 设置页与选择器 |
-| `0.2.1-alpha.5` | npm `alpha` | 同一套隔离检查，读取该宿主自己的预设声明 |
-| `0.2.1-rc.2` | npm `next` | 同一套隔离检查，读取该宿主自己的预设声明 |
-| `0.1.7-rc.2` | 先前声明支持的版本 | 保留在 CI 回归矩阵里 |
+## 兼容与版本
 
-发布必须等待单元、启动和浏览器工作流通过。已有精确版本的宿主安装时，可以这样复现：
+声明的宿主范围：`>=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0 || >=0.2.1-alpha.1 <0.3.0-0 || >=0.2.2-alpha.2 <0.3.0-0`
 
-```sh
-node tools/compat-check.mjs --host-install /path/to/host --out /tmp/custom-mode-check
-node tools/runtime-check.mjs --host-install /path/to/host --out /tmp/custom-mode-check --browser /path/to/chrome
-```
+插件版本走独立的稳定 `x.y.z` 版本线，不镜像 DSH。2026-10-27 公开宿主标签为 `latest=0.2.1-rc.2`、`next=0.2.1-rc.4`、`alpha=0.2.2-alpha.2`。标签会移动，声明范围与已完成检查是两件事。实测范围见[精确版本、验收边界与历史证据](docs/CURRENT_COMPATIBILITY.zh.md)。
 
-两项工具只使用新生成的 home 和普通 mock 提示词。运行检查覆盖全部五档基础模式、重复保存、卸载、重装、用户数据保留与重复安装，不需要调用模型。Windows/Electron 桌面端和真实模型或 GPU 执行尚未验证。详见[准确覆盖范围](docs/CURRENT_COMPATIBILITY.zh.md)。
+发布必须通过兼容性与浏览器工作流。单元、真实提示词组件、打包安装和浏览器检查分别覆盖不同边界。Windows/Electron、真实模型回复、GPU 执行都必须单独留证，不能从页面截图或单元计数推断。headless 不启动使用 agent preset 的会话。
 
 ## 插件市场
 
-`dshmarket`、DSH Plugin Hub（`dsh-plugin`）和 DSH Plugin Store（`dshmarketplace-plugin`）使用不同目录，但安装的是同一个 profile bundle。根 npm 清单提供 `dsh.bundle.patch`、浏览器导出、公开仓库和一致的兼容范围，不需要额外的运行时适配器或构建脚本。
-
-运行 `node tools/market-check.mjs --out /tmp/custom-mode-markets.json` 检查它们的公开发现数据。目录不可访问、条目未审核或数据过期都会明确报告。工具不执行目录提供的 shell 命令，也不提交收录。[市场接口与限制](docs/MARKETPLACES.zh.md)。
+各目录的发现与审核规则不同。2026-10-09 的上架结果属于历史记录，不能据此保证今天每个市场都能搜索到。上面的固定版本安装仍是直接入口。[市场接口与限制](docs/MARKETPLACES.zh.md) 说明只读适配器；它不执行目录提供的 shell 命令，也不提交收录。
 
 ## 文档
 
-- [docs/TROUBLESHOOTING.zh.md](docs/TROUBLESHOOTING.zh.md) — 装到旧版、基础模式不可用、升级停在半截
-- [docs/ARCHITECTURE.zh.md](docs/ARCHITECTURE.zh.md) — 提示词在哪被读，依赖宿主的哪些调用
-- [docs/PUBLISHING.zh.md](docs/PUBLISHING.zh.md) — tag 与发布
-- [CONTRIBUTING.zh.md](CONTRIBUTING.zh.md) — 给人看
-- [AGENTS.md](AGENTS.md) — 给 agent 看
+- [故障排查](docs/TROUBLESHOOTING.zh.md) — 当前自救在前，历史故障在后。
+- [架构](docs/ARCHITECTURE.zh.md) — 提示词读取与宿主耦合点。
+- [发布](docs/PUBLISHING.zh.md) — 既有发布门禁与读回证据。
+- [贡献指南](CONTRIBUTING.zh.md) — 隔离开发与检查。
+- [AGENTS.md](AGENTS.md) — 仓库代理约定。
 
 ## 许可证
 

package/assistants.mjs

@@ -32,7 +32,7 @@ import { dshHome, PRESET_DIR } from './paths.mjs'
 // ReferenceError 被 try/catch 吞掉，回滚循环 continue 掉每一条 —— 用户看到的"已回滚"从未发生，
 // 磁盘上留下改了一半的 order。少一个导入就能让一整段安全网变成死代码（外部评审复现）。
 import { readPresetMeta, writePresetMeta, presetMetaPath } from './meta.mjs'
-import { writeAtomic } from './atomic.mjs'
+import { restoreBackups, writeAtomic } from './atomic.mjs'
 import { unresolvableRows } from './composition.mjs'
 import { seedPreset, seedPresetWithLog, dropShippedDescription } from './seed.mjs'
 
@@ -100,8 +100,13 @@ export function markSeeded(root) {
 /** Whether `dir` is a directory this feature owns (see the module comment). */
 export function isManagedDir(dir) {
   if (typeof dir !== 'string' || dir === '') return false
+  // A crashed save can move prompt.md away. Recover before requiring that very file as proof.
+  // Keep a known reader-owned directory visible on an unresolved recovery; readState explains it and
+  // seedPreset refuses to fill missing user data with template content.
+  const readerPresent = existsSync(join(dir, 'prompt-reader.mjs'))
+  if (readerPresent && restoreBackups(dir).ok !== true) return true
   if (!existsSync(join(dir, 'prompt.md'))) return false
-  if (existsSync(join(dir, 'prompt-reader.mjs'))) return true
+  if (readerPresent) return true
   // The reader is gone but the composition still injects it: still ours, and the
   // repair pass below can put the module back.
   try {
@@ -333,6 +338,7 @@ export function seedOnActivation({ root, templateDir, composition, log = console
   //   之后描述仍是旧的）。放在这个循环里，每次激活都会检查，且 `dropShippedDescription` 只认**逐字**
   //   等于我们自己写过的那些串，用户自己写的描述一个字都不会动。
   for (const dir of existing) {
+    if (restoreBackups(dir).ok !== true) continue
     try {
       if (dropShippedDescription(dir).migrated === true) {
         info(`custom-mode: 已清空 ${dir} 的描述 —— 它还是我们早年播种的那条中英拼接，壳无法按界面语言本地化产品数据`)

package/atomic.mjs

@@ -14,8 +14,8 @@
  *    random temporary name does not help with *that* collision, only with temp-vs-temp ones.
  */
 import { randomBytes } from 'node:crypto'
-import { existsSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
 
 /** Synchronous backoff: these write paths are synchronous, so waiting is simpler than async plumbing. */
 function sleepSync(ms) {
@@ -63,7 +63,12 @@ export function renameWithRetry(from, to, options = {}) {
  */
 export function stageAtomic(file, text) {
   const temporary = `${file}.tmp-${String(process.pid)}-${randomBytes(4).toString('hex')}`
-  writeFileSync(temporary, text, 'utf8')
+  try {
+    writeFileSync(temporary, text, 'utf8')
+  } catch (error) {
+    try { rmSync(temporary, { force: true }) } catch { /* retain the original failure */ }
+    throw error
+  }
   return { file, temporary }
 }
 
@@ -108,6 +113,14 @@ export function discardStaged(staged) {
  * @returns {void}
  */
 export function writeAtomicPair(entries) {
+  if (entries.length === 0) return
+  const directory = dirname(resolve(entries[0][0]))
+  const names = entries.map(([file]) => basename(file))
+  if (new Set(names).size !== names.length || entries.some(([file]) => dirname(resolve(file)) !== directory || !TRANSACTION_FILES.includes(basename(file)))) {
+    throw new Error('Atomic preset transactions require distinct preset files in one directory')
+  }
+  const recovery = restoreBackups(directory)
+  if (recovery.ok !== true) throw new Error(recovery.detail)
   const stamp = `${String(process.pid)}-${randomBytes(4).toString('hex')}`
 
   // ── phase 0: refuse to touch a destination that is a directory. ──
@@ -133,54 +146,41 @@ export function writeAtomicPair(entries) {
     throw error
   }
 
-  // ── phase 2: move the current targets aside. `null` = the target did not exist. ──
-  const backups = []
-  const installed = []
+  // A prepared journal is on disk BEFORE any original moves. Recovery rolls the WHOLE transaction
+  // back, including files already installed; a committed journal keeps the whole new generation.
+  const journal = join(directory, `${TRANSACTION_PREFIX}${stamp}.json`)
+  const transaction = {
+    version: 1,
+    stamp,
+    ownerPid: process.pid,
+    phase: 'prepared',
+    entries: staged.map((one) => ({
+      name: basename(one.file),
+      temporary: basename(one.temporary),
+      backup: `${basename(one.file)}.bak-${stamp}`,
+      existed: existsSync(one.file),
+    })),
+  }
+  ACTIVE_TRANSACTIONS.add(directory)
   try {
-    for (const one of staged) {
-      if (existsSync(one.file)) {
-        const backup = `${one.file}.bak-${stamp}`
-        renameWithRetry(one.file, backup)
-        backups.push([one.file, backup])
-      } else {
-        backups.push([one.file, null])
-      }
-    }
-    // ── phase 3: install. ──
-    for (const one of staged) {
-      commitStaged(one)
-      installed.push(one)
+    writeAtomic(journal, JSON.stringify(transaction) + '\n')
+    for (const one of transaction.entries) {
+      if (one.existed) renameWithRetry(join(directory, one.name), join(directory, one.backup))
     }
+    for (const one of staged) commitStaged(one)
+    writeAtomic(journal, JSON.stringify({ ...transaction, phase: 'committed' }) + '\n')
   } catch (error) {
-    // Undo in reverse: remove what we installed, then put the backups back.
-    for (const one of installed) {
-      try {
-        rmSync(one.file, { force: true })
-      } catch {
-        /* best effort — the restore below is what matters */
-      }
-    }
-    for (const [file, backup] of backups) {
-      if (backup === null) continue
-      try {
-        renameWithRetry(backup, file)
-      } catch {
-        /* best effort; the thrown error still tells the caller nothing is consistent */
-      }
-    }
+    // If writing the journal itself failed no target moved. Otherwise leave recovery evidence until
+    // rollback has completed; a failed restore must not be hidden as "nothing changed".
+    const outcome = existsSync(journal) ? recoverTransaction(directory, journal, transaction) : { ok: true }
     for (const one of staged) discardStaged(one)
+    ACTIVE_TRANSACTIONS.delete(directory)
+    if (outcome.ok !== true) throw new Error(String(error.message ?? error) + '; recovery required: ' + outcome.detail, { cause: error })
     throw error
   }
-
-  // ── success: drop the backups ──
-  for (const [, backup] of backups) {
-    if (backup === null) continue
-    try {
-      rmSync(backup, { force: true })
-    } catch {
-      /* a leftover .bak-… is inert; failing the whole write over it would be worse */
-    }
-  }
+  // Cleanup failure is recoverable from the committed journal and cannot undo a successful write.
+  recoverTransaction(directory, journal, { ...transaction, phase: 'committed' })
+  ACTIVE_TRANSACTIONS.delete(directory)
 }
 
 /**
@@ -204,24 +204,124 @@ export function writeAtomicPair(entries) {
  * @param {string} directory - one assistant directory.
  * @returns {void}
  */
+const TRANSACTION_FILES = ['prompt.md', 'agent.cordis.yml', 'preset.yml']
+const TRANSACTION_PREFIX = '.custom-mode-transaction-'
+const ACTIVE_TRANSACTIONS = new Set()
+
+function pidFromStamp(stamp) {
+  const pid = Number(stamp.split('-')[0])
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null
+}
+
+/** A different live or uninspectable process might still be writing. Only ESRCH proves death. */
+function ownerMayBeActive(pid) {
+  // This process runs transactions synchronously and ACTIVE_TRANSACTIONS covers its live writes.
+  if (pid === process.pid) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error.code !== 'ESRCH'
+  }
+}
+
+function activeOwnerResult(pid) {
+  return { ok: false, code: 'recoveryRequired', detail: `Preset transaction owner ${pid} is active or cannot be inspected; retry after it finishes` }
+}
+
+function validTransaction(transaction, journalName) {
+  if (transaction?.version !== 1 || !/^\d+-[a-f0-9]{8}$/.test(transaction.stamp ?? '')) return false
+  if (journalName !== `${TRANSACTION_PREFIX}${transaction.stamp}.json`) return false
+  const stampedPid = pidFromStamp(transaction.stamp)
+  const ownerPid = transaction.ownerPid ?? stampedPid
+  if (stampedPid === null || !Number.isSafeInteger(ownerPid) || ownerPid <= 0) return false
+  if (transaction.legacy !== true && ownerPid !== stampedPid) return false
+  if (!['prepared', 'committed'].includes(transaction.phase) || !Array.isArray(transaction.entries) || transaction.entries.length === 0) return false
+  const names = new Set()
+  for (const one of transaction.entries) {
+    if (one === null || typeof one !== 'object') return false
+    if (!TRANSACTION_FILES.includes(one.name) || names.has(one.name) || typeof one.existed !== 'boolean') return false
+    if (one.backup !== `${one.name}.bak-${transaction.stamp}`) return false
+    if (transaction.legacy === true ? one.temporary !== null : !new RegExp(`^${one.name.replaceAll('.', '\\.')}\\.tmp-\\d+-[a-f0-9]{8}$`).test(one.temporary ?? '')) return false
+    names.add(one.name)
+  }
+  return true
+}
+
+function recoverTransaction(directory, journal, transaction) {
+  try {
+    if (transaction.phase === 'prepared') {
+      for (const one of transaction.entries) {
+        const file = join(directory, one.name)
+        const backup = join(directory, one.backup)
+        if (one.existed) {
+          if (existsSync(backup)) renameWithRetry(backup, file)
+          else if (!existsSync(file)) throw new Error(`Missing original and backup for ${one.name}`)
+        } else {
+          rmSync(file, { force: true })
+        }
+      }
+    }
+    for (const one of transaction.entries) {
+      rmSync(join(directory, one.backup), { force: true })
+      if (one.temporary !== null) rmSync(join(directory, one.temporary), { force: true })
+    }
+    rmSync(journal, { force: true })
+    return { ok: true }
+  } catch (error) {
+    return { ok: false, code: 'recoveryRequired', detail: String(error.message ?? error) }
+  }
+}
+
+/** Recover before ownership discovery: prompt.md itself can be temporarily absent after a crash. */
 export function restoreBackups(directory) {
-  const names = ['prompt.md', 'agent.cordis.yml', 'preset.yml']
+  if (ACTIVE_TRANSACTIONS.has(resolve(directory))) return { ok: true, active: true }
   let entries
   try {
     entries = readdirSync(directory)
-  } catch {
-    return
+  } catch (error) {
+    return error.code === 'ENOENT' ? { ok: true } : { ok: false, code: 'recoveryRequired', detail: String(error.message ?? error) }
   }
-  for (const name of names) {
-    const file = join(directory, name)
-    if (existsSync(file)) continue
-    const backups = entries.filter((entry) => entry.startsWith(name + '.bak-'))
-    if (backups.length !== 1) continue
+  const journals = entries.filter((entry) => entry.startsWith(TRANSACTION_PREFIX) && entry.endsWith('.json'))
+  // Shared homes across live processes are not a supported transaction boundary. Never guess which of
+  // multiple interrupted generations owns a target, and never seed a replacement over their evidence.
+  if (journals.length > 1) return { ok: false, code: 'recoveryRequired', detail: 'Multiple preset transactions require manual recovery' }
+  for (const name of journals) {
+    let transaction
     try {
-      renameSync(join(directory, backups[0]), file)
-    } catch {
-      /* 恢复失败就留着备份，下一次读取再试 */
+      transaction = JSON.parse(readFileSync(join(directory, name), 'utf8'))
+    } catch (error) {
+      return { ok: false, code: 'recoveryRequired', detail: 'Unreadable preset transaction: ' + String(error.message ?? error) }
     }
+    if (!validTransaction(transaction, name)) return { ok: false, code: 'recoveryRequired', detail: 'Invalid preset transaction journal' }
+    const ownerPid = transaction.ownerPid ?? pidFromStamp(transaction.stamp)
+    if (ownerMayBeActive(ownerPid)) return activeOwnerResult(ownerPid)
+    const outcome = recoverTransaction(directory, join(directory, name), transaction)
+    if (outcome.ok !== true) return outcome
+  }
+  // Upgrade recovery for v2.2.5 transactions that predate the journal. Restore one whole backup group
+  // only when something is missing. Complete targets plus leftover backups denote a completed write.
+  try { entries = readdirSync(directory) } catch (error) {
+    return { ok: false, code: 'recoveryRequired', detail: String(error.message ?? error) }
+  }
+  const legacy = entries.map((entry) => ({ entry, match: /^(prompt\.md|agent\.cordis\.yml|preset\.yml)\.bak-(\d+-[a-f0-9]{8})$/.exec(entry) })).filter((one) => one.match !== null)
+  if (!legacy.some((one) => !existsSync(join(directory, one.match[1])))) return { ok: true }
+  if (new Set(legacy.map((one) => one.match[2])).size !== 1) return { ok: false, code: 'recoveryRequired', detail: 'Ambiguous legacy preset backups require manual recovery' }
+  const legacyOwner = pidFromStamp(legacy[0].match[2])
+  if (legacyOwner === null) return { ok: false, code: 'recoveryRequired', detail: 'Invalid legacy preset transaction owner' }
+  if (ownerMayBeActive(legacyOwner)) return activeOwnerResult(legacyOwner)
+  try {
+    // Recovery itself can be interrupted. Journal the whole legacy group BEFORE restoring even the
+    // first missing target; otherwise that first rename can hide the need to restore the rest.
+    const stamp = legacy[0].match[2]
+    const journal = join(directory, `${TRANSACTION_PREFIX}${stamp}.json`)
+    const transaction = { version: 1, stamp, ownerPid: process.pid, phase: 'prepared', legacy: true, entries: legacy.map((one) => ({
+      name: one.match[1], backup: one.entry, temporary: null, existed: true,
+    })) }
+    writeAtomic(journal, JSON.stringify(transaction) + '\n')
+    return recoverTransaction(directory, journal, transaction)
+  } catch (error) {
+    return { ok: false, code: 'recoveryRequired', detail: String(error.message ?? error) }
   }
 }