dsh-paoding 0.3.4 → 0.3.5

package/docs/configuration.md

@@ -19,7 +19,7 @@ dsh-paoding 把「按角色分工的编排 preset」做成**配置驱动**：你
 | 场景 | 行为 |
 |---|---|
 | Web 面板（左侧栏「庖丁配置」入口） | **主路径**：打开面板会把既有配置加载为当前值，点「保存并应用」写入 preset 并把分配保存到配置文件（默认 `~/.dsh/dsh-paoding.config.yml`，以 `0o600` 权限写入）。手编过配置文件的话，先开面板再应用即可 |
-| 首装自动化 | 插件启动时发现 preset 缺失或版本标记不符，自动按配置文件应用一次（无配置则写基础模板）——日常无需手动触发 |
+| 首装自动化 | 插件启动时发现 preset 缺失、版本标记不符、或宿主预设轨道翻转（只升 dsh 不动插件），自动自愈一次：前者按配置文件重生成（无配置则写基础模板），轨道翻转只按磁盘产物补写缺失的声明行、不重生成内容——日常无需手动触发 |
 | 兜底 CLI（仅限克隆仓库的开发者） | `node tools/install.mjs --auto`：有配置文件则幂等应用，没有则写基础模板；`--dry-run` 只打印检测报告与将生成的 allow / persona 变化，不写任何文件（含配置文件），适合先预览再动手；`--config <file>` 用指定文件替代默认位置 |
 
 配置文件**存在但解析失败**是硬错误（直接报错退出）；**不存在**则视为无配置（写基础模板）。`profile`、`roles` 等顶层键的语义见下节。

package/docs/installation.md

@@ -19,7 +19,7 @@
 |---|---|---|
 | `$DSH_HOME` | `~/.dsh` | DSH 家目录（认环境变量 `DSH_HOME`，缺省 `$HOME/.dsh`）。host 层配置 `cordis.patch.yml`、`node_modules`、`profiles/<name>/cordis.patch.yml`、插件 profile 目录都在其下 |
 | preset roster 根目录 | `$DSH_HOME/.agent-presets/` | DSH ≤ 0.1.6 由 `dsh-agent-presets` 扫描此目录发现本地 authored presets；DSH ≥ 0.1.7 宿主不再扫目录，此目录退为预设文件存放处（见第 2 节「版本支持与预设落点双轨」） |
-| 本预设安装目标 | `$DSH_HOME/.agent-presets/orchestrator` | 生成产物：`agent.cordis.yml`（重写后的角色配置）、`preset.yml`、`restrict.mjs`、`.generator-version` 版本标记，是一个静态目录；按工作区配置生成的预设落同一父目录下的 `orchestrator-<slug>` |
+| 本预设安装目标 | `$DSH_HOME/.agent-presets/orchestrator` | 生成产物：`agent.cordis.yml`（重写后的角色配置）、`preset.yml`、`restrict.mjs`、`.generator-version` 版本与轨道标记，是一个静态目录；按工作区配置生成的预设落同一父目录下的 `orchestrator-<slug>` |
 | 声明行托管块（仅 DSH ≥ 0.1.7） | `$DSH_HOME/cordis.patch.yml` 内的托管块 | 以 `# --- dsh-paoding presets (auto-generated; do not edit) ---` 起始、配套 end 标记收尾，块内 `- insert:` 写 `@deepseek-ai/dsh-agent-preset` 声明行；安装器自动维护，详见第 2 节 |
 | 配置文件 | `$DSH_HOME/dsh-paoding.config.yml` | 「庖丁配置」面板「保存并应用」写入的角色与工具分配（`0o600`，可手编）；首装自动化同样读写它 |
 
@@ -80,11 +80,17 @@ dsh plugin --profile web add dsh-paoding
 
 插件启动时自动检测编排预设是否就位：`$DSH_HOME/.agent-presets/orchestrator` 目录缺失，或其中的 `.generator-version` 标记与插件包版本不符时，自动执行一次等价 `--auto` 的安装——`~/.dsh/dsh-paoding.config.yml` 已存在就按配置应用；没有就写基础模板（只含 DSH 自带的基础工具，见下）。它走的是与面板「保存并应用」同一条检测/生成管线（`collectState` / `generateAndInstall`）——同一管线，但启动自愈的检测是纯文件扫描、不带运行时检测事实，面板则带；host 上装有 bundle 形态插件时，两者的检测库存可能不同，产物随之略有差异。
 
-所以 **`dsh plugin add` + 重启 = 完整安装**：预设生成、配置模板落盘、面板可点，一步到位。自动生成失败不会拖垮插件启动——只在 DSH 日志里记一条告警，可到面板手动「保存并应用」补上。启动自愈同时负责双轨落点的维护与跨版本迁移——宿主在 0.1.6 与 0.1.7 之间升级、降级后，首次自愈会自动补写或撤下 `$DSH_HOME/cordis.patch.yml` 里的托管块（见上节「版本支持与预设落点双轨」）。
+所以 **`dsh plugin add` + 重启 = 完整安装**：预设生成、配置模板落盘、面板可点，一步到位。自动生成失败不会拖垮插件启动——只在 DSH 日志里记一条告警，可到面板手动「保存并应用」补上。启动自愈同时负责双轨落点的维护与跨版本迁移——宿主在 0.1.6 与 0.1.7 之间升级、降级后，首次自愈会自动补写或撤下 `$DSH_HOME/cordis.patch.yml` 里的托管块（见上节「版本支持与预设落点双轨」）。**只升级 dsh、不动插件**时同样如此：宿主轨道翻转后首次启动，自愈按磁盘上已有的预设产物补写缺失的声明行——preset 内容一字节不重生成，各工作区预设一并恢复。
 
 ### 版本标记与自动重生成
 
-`.generator-version` 标记（内容 = 生成器版本）由插件启动自愈在生成 preset 后写入。面板「保存并应用」与兜底 CLI 的生成走整目录重建、不写回标记——重建即移除旧标记，下次 DSH 启动自愈发现标记缺失会多补跑一次生成并重写标记（产物相同，只是多跑一轮）。版本不符触发重生成的语义不变：插件升级后标记与包版本不符，下次 DSH 启动自动按新版重生成，「升级后 preset 还是旧版产物」的漂移就此消除。标记只在缺失或版本不符时触发重生成，面板不监视配置文件改动；想立刻按当前配置重新生成，点面板「保存并应用」。
+`.generator-version` 标记由插件启动自愈在生成 preset 后写入，内容两行：**生成器版本 + 预设安装轨道**（旧版只写版本一行，读到时按「轨道未知」处理，恰是宿主升级后的迁移触发态）。三类触发：
+
+- **标记缺失 / 版本不符**（首装、插件升级）→ 整盘重生成。面板「保存并应用」与兜底 CLI 的生成走整目录重建、不写回标记——重建即移除旧标记，下次 DSH 启动自愈发现标记缺失会多补跑一次生成并重写标记（产物相同，只是多跑一轮）。插件升级后标记与包版本不符，下次 DSH 启动自动按新版重生成，「升级后 preset 还是旧版产物」的漂移就此消除。
+- **版本一致、轨道翻转**（只升 dsh 不动插件——升级最常见路径）→ 轻量迁移，不重生成内容：声明轨上按磁盘产物补写缺失的声明行（含各工作区预设），directory 轨上若有残留声明行则整盘重生成撤下（残留会让 0.1.6 profile 启动失败）。
+- **版本轨道都一致** → 对账声明行：缺行补行、目录已删的孤儿行撤行，齐则什么都不动。
+
+面板不监视配置文件改动；想立刻按当前配置重新生成，点面板「保存并应用」。
 
 ### 基础模板与工具勾选
 
@@ -108,7 +114,7 @@ dsh plugin --profile web add dsh-paoding
 dsh plugin --profile <name> update dsh-paoding
 ```
 
-（profile 自动探测，通常无需手填。）升级只换 profile 里的插件包本体，当前进程的代码不变；成功后提示**重启 DSH**，重启时 preset 按 `.generator-version` 标记自动按新版重生成。
+（profile 自动探测，通常无需手填。）升级只换 profile 里的插件包本体，当前进程的代码不变；成功后提示**重启 DSH**，重启时 preset 按 `.generator-version` 标记自动按新版重生成。只升级 dsh 本体（不动插件）同理：重启即触发轨道迁移自愈，无需重装或重新应用。
 
 手动升级等价：直接在终端跑上面这条 `dsh plugin update` 命令，同样重启生效。
 

package/docs/installation_en.md

@@ -19,7 +19,7 @@ Check the following before installing:
 |---|---|---|
 | `$DSH_HOME` | `~/.dsh` | The DSH home directory (the `DSH_HOME` environment variable is honored, defaulting to `$HOME/.dsh`). The home-layer `cordis.patch.yml`, `node_modules`, `profiles/<name>/cordis.patch.yml`, and plugin profile directories live under it |
 | preset roster root | `$DSH_HOME/.agent-presets/` | Under DSH ≤ 0.1.6, `dsh-agent-presets` scans this directory for locally authored presets; under DSH ≥ 0.1.7 the host no longer scans it and the directory is just where the preset files live (see §2 "Version support and the dual preset landing") |
-| Install target of this preset | `$DSH_HOME/.agent-presets/orchestrator` | The generated artifact: `agent.cordis.yml` (rewritten role config), `preset.yml`, `restrict.mjs`, and the `.generator-version` marker — a static directory; per-workspace presets land in sibling `orchestrator-<slug>` directories |
+| Install target of this preset | `$DSH_HOME/.agent-presets/orchestrator` | The generated artifact: `agent.cordis.yml` (rewritten role config), `preset.yml`, `restrict.mjs`, and the `.generator-version` version-and-track marker — a static directory; per-workspace presets land in sibling `orchestrator-<slug>` directories |
 | Declaration managed block (DSH ≥ 0.1.7 only) | a managed block inside `$DSH_HOME/cordis.patch.yml` | Opens with `# --- dsh-paoding presets (auto-generated; do not edit) ---` and closes with the matching end marker; the `- insert:` rows inside carry `@deepseek-ai/dsh-agent-preset` declarations, maintained by the installer — see §2 |
 | Config file | `$DSH_HOME/dsh-paoding.config.yml` | Role/tool assignments written by the Paoding Config panel's Save & Apply (`0o600`, hand-editable); first-install automation reads and writes it too |
 
@@ -80,11 +80,17 @@ Two cross-version behavior alignments happen the same automatic way, with no use
 
 At startup the plugin checks whether the orchestrator preset is in place: if the `$DSH_HOME/.agent-presets/orchestrator` directory is missing, or its `.generator-version` marker does not match the plugin package version, it automatically performs one install equivalent to `--auto` — applying `~/.dsh/dsh-paoding.config.yml` when it exists, writing the base template otherwise (DSH base tools only; see below). It runs the same detection/generation pipeline as the panel's Save & Apply (`collectState` / `generateAndInstall`) — the same pipeline, but the startup self-heal detects with a pure file scan and no runtime detection facts while the panel detects with them; when a bundle-form plugin is installed on the host, the two detection inventories may differ, and the outputs differ slightly with them.
 
-So **`dsh plugin add` + restart = a complete install**: preset generated, config template on disk, panel ready — all in one step. If the automatic generation fails it never takes the plugin down — a warning is logged, and you can apply manually from the panel. The startup self-heal also maintains the dual landing and the cross-version migration: after the host moves between 0.1.6 and 0.1.7, the first self-heal writes or removes the managed block in `$DSH_HOME/cordis.patch.yml` automatically (see "Version support and the dual preset landing" above).
+So **`dsh plugin add` + restart = a complete install**: preset generated, config template on disk, panel ready — all in one step. If the automatic generation fails it never takes the plugin down — a warning is logged, and you can apply manually from the panel. The startup self-heal also maintains the dual landing and the cross-version migration: after the host moves between 0.1.6 and 0.1.7, the first self-heal writes or removes the managed block in `$DSH_HOME/cordis.patch.yml` automatically (see "Version support and the dual preset landing" above). The same holds when **only dsh is upgraded and the plugin untouched**: after the host's preset system flips, the first startup backfills the missing declaration rows from the preset artifacts already on disk — no preset content is regenerated, and per-workspace presets are restored along with the base one.
 
 ### The version marker and auto-regeneration
 
-The `.generator-version` marker (its content = the generator version) is written by the plugin's startup self-heal after it generates the preset. The panel's Save & Apply (and the fallback CLI) do a full-directory rebuild and write no marker — the rebuild removes the old marker, so the next DSH start's self-heal finds it missing, runs one extra generation, and rewrites the marker (same output, just one extra round). The version-mismatch trigger is unchanged: after a plugin upgrade the marker no longer matches the package version, so the next DSH start regenerates the preset against the new version — the "upgraded the plugin but the preset is stale" drift is eliminated. The marker triggers regeneration only when missing or version-mismatched, and the panel does not watch the config file; to regenerate from the current config right away, hit Save & Apply.
+The `.generator-version` marker is written by the plugin's startup self-heal after it generates the preset. Its content is two lines: **the generator version and the preset system track** (older releases wrote only the version; such markers read back as "track unknown", which is exactly the migration trigger after a host upgrade). Three triggers:
+
+- **Marker missing or version-mismatched** (first install, plugin upgrade) → full regeneration. The panel's Save & Apply (and the fallback CLI) do a full-directory rebuild and write no marker — the rebuild removes the old marker, so the next DSH start's self-heal finds it missing, runs one extra generation, and rewrites the marker (same output, just one extra round). After a plugin upgrade the marker no longer matches the package version, so the next DSH start regenerates the preset against the new version — the "upgraded the plugin but the preset is stale" drift is eliminated.
+- **Version matching but the track flipped** (dsh upgraded, plugin untouched — the most common upgrade path) → lightweight migration with no content regeneration: on the declarative track, missing declaration rows are backfilled from the on-disk artifacts (per-workspace presets included); on the directory track, any leftover declaration rows force a full regeneration that strips them (leftovers would break 0.1.6 profile startup).
+- **Version and track both matching** → declaration-row reconciliation: missing rows are backfilled, orphan rows whose directories are gone are removed; if everything lines up, nothing is touched.
+
+The panel does not watch the config file; to regenerate from the current config right away, hit Save & Apply.
 
 ### Base template and tool opt-in
 
@@ -108,7 +114,7 @@ Once installed:
 dsh plugin --profile <name> update dsh-paoding
 ```
 
-(the profile is auto-detected; usually nothing to fill in). The upgrade only swaps the plugin package inside the profile — the running process's code is untouched; on success it asks you to **restart DSH**, and at restart the preset regenerates itself against the new version via the `.generator-version` marker.
+(the profile is auto-detected; usually nothing to fill in). The upgrade only swaps the plugin package inside the profile — the running process's code is untouched; on success it asks you to **restart DSH**, and at restart the preset regenerates itself against the new version via the `.generator-version` marker. Upgrading only the dsh host (plugin untouched) works the same way: the restart triggers the track-migration self-heal — no reinstall or manual re-apply needed.
 
 Manual equivalent: run the `dsh plugin update` command above yourself, restart, done.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-paoding",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "庖丁 — DSH (DeepSeek Harness) 编排模式安装器：host 感知的角色工具过滤 + Web 设置页可视化配置器",
   "type": "module",
   "license": "MIT",

package/plugins/paoding-config-ui/api-core.mjs

@@ -12,6 +12,14 @@ import { mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'n
 import { readFile } from 'node:fs/promises'
 import { assignSlugs, collectState, generateAndInstall, presetIdOf } from '../../tools/install.mjs'
 import { autoAssignments } from '../../tools/lib/alloc.mjs'
+import {
+  backfillHomePatchRows,
+  detectPresetSystem,
+  formatGeneratorMarker,
+  listOrchestratorPresetIds,
+  parseGeneratorMarker,
+  readHomePatchRows,
+} from '../../tools/lib/preset-system.mjs'
 
 export function resolveDshHome() {
   return process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
@@ -142,10 +150,11 @@ export function installAssignments(state, assignments, { dryRun = false, saveCon
 // ── 首装 / 升级后 preset 自动重生成 ─────────────────────────────────────────
 //
 // 唯一官方安装通道是插件通道（dsh plugin add dsh-paoding），包不再携带 CLI：
-// preset 的落盘改由插件启动时自愈——目录缺失（首装）或由旧版生成器产出（升级
-// 换包）时，按 install --auto 语义重生成一次。对账基准是 preset 目录里的
-// .generator-version 标记文件（内容 = 生成器版本）：插件包版本变 → 标记不符 →
-// 下次启动自动重生成，一举解决「升级后 preset 还是旧版产物」的漂移问题。
+// preset 的落盘改由插件启动时自愈。对账基准是 preset 目录里的 .generator-version
+// 标记文件（v2 起内容 = 生成器版本 + 预设安装轨道两行）：插件包版本变、或宿主
+// 轨道翻转（只升 dsh 不动插件——升级最常见路径，旧标记只记版本时同样解析为
+// 轨道不符）→ 下次启动自动自愈，一举解决「升级后 preset 还是旧版产物」与
+// 「升 dsh 后 preset 静默消失」两类漂移。
 
 // 生成器版本（标记对账基准）：插件包根 package.json 读一次即缓存。读失败兜底
 // '0.0.0'——最坏后果只是每次启动多重生成一次 preset，不会装坏任何东西。
@@ -165,23 +174,30 @@ export function pluginVersion() {
 const PRESET_ENSURE_ABORTED = '插件已卸载（dispose），本次 preset 生成中止'
 
 /**
- * 首装 / 升级后自动重生成 orchestrator preset（等价 install --auto 语义）。
+ * 首装 / 升级后自动安装 orchestrator preset（等价 install --auto 语义）。
  *
- * 判定：preset 目录缺失，或 .generator-version 标记缺失 / 版本与 generatorVersion
- * 不符 → 执行一次自动安装：局部 collectState()（不带运行时事实的纯文件扫描，
- * 首装触发点在插件启动、宿主服务未必就绪，且与 CLI --auto 语义对齐；预设安装
- * 轨道由 collectState 内部按 dsh --version / 文件探测兜底，state.presetSystem
- * 随 state 一并进 generateAndInstall 双轨收尾；不走 refreshState()——那会拿
- * 无事实的扫描覆盖路由层的共享缓存）后按既有配置合成 assignments（无配置写
- * 基础模板），经 generateAndInstall 落盘，最后写标记文件。
+ * 判定（满足其一即动盘）：
+ *   - preset 目录 / 标记缺失，或标记版本与 generatorVersion 不符 → 整盘重生成；
+ *   - 版本一致但标记轨道与当前宿主轨道不符（只升 dsh 不动插件 / 旧格式标记）→
+ *     轻量迁移：声明轨上按磁盘产物补写缺失声明行（内容字节不动，不重生成），
+ *     directory 轨上落回整盘重生成（残留声明行会让 0.1.6 profile 启动失败，
+ *     撤块自愈由其 directory 分支完成）；
+ *   - 版本轨道都一致 → 对账声明行（缺行补行、孤儿行撤行），齐则跳过。
+ * 局部 collectState() 不带运行时事实（首装触发点在插件启动、宿主服务未必就绪，
+ * 且与 CLI --auto 语义对齐；预设安装轨道由 collectState 内部按 argv 宿主版本 /
+ * dsh --version / 文件探测兜底，state.presetSystem 随 state 一并进
+ * generateAndInstall 双轨收尾；不走 refreshState()——那会拿无事实的扫描覆盖
+ * 路由层的共享缓存）后按既有配置合成 assignments（无配置写基础模板），经
+ * generateAndInstall 落盘，最后写标记文件（版本 + 轨道）。
  * shouldAbort 在各 await 点后检查：插件 dispose 后在途的生成不再继续写盘。
  * 可脱离 ctx 独立调用（单测友好），任何异常自捕、绝不抛出。
  *
  * @param {{dshHome?: string, generatorVersion?: string, shouldAbort?: () => boolean}} opts
  *   缺省取 resolveDshHome() 与 pluginVersion()；shouldAbort 返回 true 时中止
  *   （按 reason 返回，不算 error）。
- * @returns {Promise<{installed: boolean, reason?: string, error?: string}>}
- *   installed=true 表示本次实际重生成；false 时带 reason（无需重生成 / 已中止）
+ * @returns {Promise<{installed: boolean, backfilled?: string[], reason?: string, error?: string}>}
+ *   installed=true 表示本次实际重生成；backfilled 非空表示本次补写了哪些
+ *   preset 的声明行（内容未重生成）；两者皆否时带 reason（无需动盘 / 已中止）
  *   或 error（生成失败，调用方只记日志）。
  */
 export async function ensurePresetInstalled({ dshHome = resolveDshHome(), generatorVersion = pluginVersion(), shouldAbort = null } = {}) {
@@ -190,10 +206,35 @@ export async function ensurePresetInstalled({ dshHome = resolveDshHome(), genera
     const markerFile = path.join(presetDir, '.generator-version')
     let marker = null
     try {
-      marker = (await readFile(markerFile, 'utf8')).trim()
+      marker = parseGeneratorMarker(await readFile(markerFile, 'utf8'))
     } catch { /* 目录或标记缺失：按未生成处理 */ }
-    if (marker === generatorVersion) {
-      return { installed: false, reason: 'preset 已由当前版本生成器产出，无需重生成' }
+
+    if (marker !== null && marker.version === generatorVersion) {
+      // 版本一致：内容无需重生成，但宿主轨道可能已随 dsh 升降级翻转（只升 dsh
+      // 不动插件是升级常态），声明行也可能被外部动过——这里做轻量对账。
+      const system = await detectPresetSystem({ dshHome })
+      if (shouldAbort?.()) return { installed: false, reason: PRESET_ENSURE_ABORTED }
+      const presetIds = listOrchestratorPresetIds(dshHome)
+      if (system === 'declarative') {
+        const backfilled = backfillHomePatchRows(dshHome, presetIds)
+        if (marker.track === 'declarative' && backfilled.length === 0) {
+          return { installed: false, reason: 'preset 已由当前版本生成器产出，无需重生成' }
+        }
+        writeFileSync(markerFile, formatGeneratorMarker(generatorVersion, 'declarative'), 'utf8')
+        return backfilled.length > 0
+          ? { installed: false, backfilled, reason: `宿主已切换声明行轨，补写 ${backfilled.length} 条预设声明行（preset 内容未重生成）` }
+          : { installed: false, reason: '预设安装轨道标记已更新为声明行轨（内容无需重生成）' }
+      }
+      // directory 轨：声明行残留会让 0.1.6 profile 启动失败——有残留走整盘
+      // 重生成（directory 分支撤块自愈）；行清白时只升级标记格式，不动内容。
+      if (readHomePatchRows(dshHome).length === 0) {
+        if (marker.track === 'directory') {
+          return { installed: false, reason: 'preset 已由当前版本生成器产出，无需重生成' }
+        }
+        writeFileSync(markerFile, formatGeneratorMarker(generatorVersion, 'directory'), 'utf8')
+        return { installed: false, reason: '预设安装轨道标记已升级为带轨道格式（内容无需重生成）' }
+      }
+      // 声明行残留 + directory 宿主：落到下方整盘重生成
     }
 
     if (shouldAbort?.()) return { installed: false, reason: PRESET_ENSURE_ABORTED }
@@ -220,9 +261,14 @@ export async function ensurePresetInstalled({ dshHome = resolveDshHome(), genera
     // 标记最后写：generateAndInstall 会整目录重建（rmSync），先写必被删。
     if (shouldAbort?.()) return { installed: false, reason: PRESET_ENSURE_ABORTED }
     mkdirSync(presetDir, { recursive: true })
-    writeFileSync(markerFile, `${generatorVersion}\n`, 'utf8')
+    const track = result.presetSystem === 'declarative' ? 'declarative' : 'directory'
+    writeFileSync(markerFile, formatGeneratorMarker(generatorVersion, track), 'utf8')
+    // 声明轨上整盘重生成只重建本 preset 的行：其余工作区 preset 目录若在而
+    // 声明行缺（轨道翻转后首次触发本路径），一并补齐。
+    const backfilled = track === 'declarative' ? backfillHomePatchRows(dshHome, listOrchestratorPresetIds(dshHome)) : []
     return {
       installed: true,
+      ...(backfilled.length > 0 ? { backfilled } : {}),
       reason: state.existing
         ? 'preset 缺失或由旧版生成器产出，已按现有配置重新生成'
         : 'preset 缺失或由旧版生成器产出，已写入基础模板',

package/plugins/paoding-config-ui/index.mjs

@@ -175,12 +175,16 @@ function triggerPresetEnsure(ctx, isDisposed) {
         ctx.logger?.info?.(
           `paoding-config-ui: orchestrator preset 已重生成（generator v${generatorVersion}，${r.reason}）`,
         )
+      } else if (Array.isArray(r.backfilled) && r.backfilled.length > 0) {
+        // 轨道迁移 / 声明行对账补写（preset 内容未重生成）：值得留一行轨迹，
+        // 方便「升级 dsh 后主子代理消失」这类问题定位。
+        ctx.logger?.info?.(`paoding-config-ui: ${r.reason ?? '预设声明行已补写'}（${r.backfilled.join('、')}）`)
       } else if (r.error) {
         // 失败复位防抖闩：下次 activate（热重载 / 重注册）可重试
         presetEnsureStarted = false
         ctx.logger?.warn?.(`paoding-config-ui: preset 自动生成失败（可在侧栏底部「庖丁配置」入口手动应用）: ${r.error}`)
       }
-      // 版本一致的常规跳过不打日志：每次启动都刷一行纯噪音。
+      // 版本轨道一致的常规跳过 / 纯标记格式升级不打日志：每次启动都刷一行纯噪音。
     })
     .catch((err) => {
       presetEnsureStarted = false

package/plugins/paoding-config-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paoding-config-ui",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "private": true,
   "type": "module",
   "main": "index.mjs",

package/tools/lib/preset-system.mjs

@@ -5,9 +5,10 @@
  * name: '@deepseek-ai/dsh-agent-preset' 的行（config = { id 必填, name?,
  * description?, order?, plugins[] 必填 }，宿主 agent-preset-registry 挂载
  * plugins 子树；行 name 相对声明行 baseUrl 解析，绝对 file: URL 直接采用）。
- * 本模块为双轨化提供三件事：
+ * 本模块为双轨化提供四件事：
  *   1) 轨道探测 detectPresetSystem：运行时探测（Web 插件对宿主服务的实时反射，
- *      最权威）> `dsh --version` 版本号 > $DSH_HOME 单数包存在性 > 默认
+ *      最权威）> 进程 argv 宿主版本（插件进程内零开销，反映正在运行的宿主而非
+ *      PATH 上的 dsh）> `dsh --version` 版本号 > $DSH_HOME 单数包存在性 > 默认
  *      directory（安全侧：声明行误落 0.1.6 会炸 profile 启动，目录轨误落
  *      0.1.7 只是预设不显示）；
  *   2) 声明行构造 buildPresetRowText：把生成的 agent.cordis.yml 全文内联成
@@ -17,11 +18,16 @@
  *      readHomePatchRows：对 $DSH_HOME/cordis.patch.yml 的 MANAGED 标记块做
  *      行级增删查，块外用户内容一字节不动；托管块损坏（缺结束标记）时拒绝
  *      写盘并明确报错，与仓库「配置不可信时拒绝落盘」口径一致。
- * 零运行时依赖（node:child_process / node:fs / node:path）；被 state 引用。
+ *   4) 轨道迁移对账 backfillHomePatchRows / listOrchestratorPresetIds /
+ *      parseGeneratorMarker / formatGeneratorMarker：宿主只升 dsh 不动插件时
+ *      （标记版本一致、轨道翻转——升级最常见路径），按磁盘产物补写缺失声明行
+ *      而不整盘重生成；生成器标记记「版本 + 轨道」两行，任一不符即触发自愈。
+ * 零运行时依赖（node:child_process / node:fs / node:path / node:url）；被 state 引用。
  */
 import { spawnSync } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { warn } from './util.mjs'
 
 /** 托管块起始标记：其后到结束标记之间是本工具自动生成的声明行，用户勿改。 */
@@ -62,14 +68,22 @@ export function isDeclarativeTriple(triple) {
 /**
  * 探测当前宿主的预设安装轨道，返回 'declarative' | 'directory'。逐级降级：
  *   1) runtimeSystem 直通：Web 插件运行时对宿主服务的实时探测结果最权威；
- *   2) `dsh --version`（timeout 10s；spawn 失败 / 超时 / 输出不可解析一律吞掉
+ *   2) 进程 argv 宿主版本：插件与宿主同进程时零开销、且反映正在运行的宿主
+ *      （PATH 上的 dsh 可能已换代而旧进程还在跑，此时以 argv 为准才不会把
+ *      声明行提前写出去）；CLI / 测试进程不是 dsh，返回 null 落到下一级；
+ *   3) `dsh --version`（timeout 10s；spawn 失败 / 超时 / 输出不可解析一律吞掉
  *      落到下一级）；
- *   3) 文件探测：单数包 @deepseek-ai/dsh-agent-preset 是 0.1.7 的声明行宿主
+ *   4) 文件探测：单数包 @deepseek-ai/dsh-agent-preset 是 0.1.7 的声明行宿主
  *      组件，在即声明轨（复数包时代没有它）；
- *   4) 默认 directory —— 安全侧兜底（理由见模块头注释）。
+ *   5) 默认 directory —— 安全侧兜底（理由见模块头注释）。
  */
 export async function detectPresetSystem({ dshHome, runtimeSystem = null } = {}) {
   if (runtimeSystem === 'declarative' || runtimeSystem === 'directory') return runtimeSystem
+  const argvVersion = hostVersionFromArgv()
+  if (argvVersion !== null) {
+    const triple = parseVersionTriple(argvVersion)
+    if (triple !== null) return isDeclarativeTriple(triple) ? 'declarative' : 'directory'
+  }
   const versionText = dshVersionText()
   if (versionText !== null) {
     const triple = parseVersionTriple(versionText)
@@ -79,6 +93,32 @@ export async function detectPresetSystem({ dshHome, runtimeSystem = null } = {})
   return 'directory'
 }
 
+/**
+ * 从当前进程 argv[1] 推断正在运行的宿主版本：沿脚本所在目录向上找最近的
+ * package.json，name 是 @deepseek-ai/dsh 即取其 version。插件跑在宿主进程里，
+ * 这比 PATH 上的 `dsh --version` 又快又准（无需子进程）；找不到（CLI / 测试 /
+ * 任意非 dsh 进程）返回 null。找到的第一个 package.json 不是 dsh 即止——
+ * 向上穿越无关包目录没有意义。
+ */
+function hostVersionFromArgv() {
+  try {
+    const entry = process.argv[1]
+    if (typeof entry !== 'string' || entry === '') return null
+    let dir = path.dirname(path.resolve(entry))
+    for (let i = 0; i < 6 && dir !== path.dirname(dir); i++) {
+      const pkgPath = path.join(dir, 'package.json')
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+        return pkg?.name === '@deepseek-ai/dsh' ? String(pkg.version ?? '') : null
+      }
+      dir = path.dirname(dir)
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
 /** `dsh --version` 取裸版本号文本；任何失败（ENOENT / 超时 / 非零退出）返回 null。 */
 function dshVersionText() {
   try {
@@ -388,3 +428,130 @@ export function readHomePatchRows(dshHome) {
     return []
   }
 }
+
+// ── 轨道迁移对账（宿主升降级自愈）────────────────────────────────────────────
+//
+// 只升 dsh 不动插件是升级的最常见路径：标记版本照旧吻合、自愈不会触发，但
+// .agent-presets/ 目录轨产物在 0.1.7 下已经无人扫描——preset 静默消失。这一节
+// 的原语补上这条缝：标记从「只记版本」升级为「版本 + 轨道」两行，轨道翻转即
+// 触发自愈；且声明轨上的自愈可以只补 home patch 声明行（磁盘产物原样保留、
+// 字节不动），不必整盘重生成。
+
+/** 编排类 preset 目录名（orchestrator / orchestrator-<slug>）的形状过滤。 */
+const ORCHESTRATOR_PRESET_ID_RE = /^orchestrator(-[a-z0-9-]+)?$/
+
+/**
+ * 列出 $DSH_HOME/.agent-presets/ 下的编排类 preset 目录名（含基础 orchestrator
+ * 与各工作区专属 orchestrator-<slug>），按名排序。目录不存在 / 不可读一律返回
+ * 空列表。非编排类目录（liangshen 之类自制 preset）不在此列——迁移对账只认
+ * 本工具生成的产物形状。
+ */
+export function listOrchestratorPresetIds(dshHome) {
+  try {
+    return readdirSync(path.join(dshHome, '.agent-presets'))
+      .filter((name) => ORCHESTRATOR_PRESET_ID_RE.test(name))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 读任意 preset 目录下 preset.yml 的显示元数据（name / description / order），
+ * 与 generateAndInstall 写 preset.yml / 声明行 config 的取值口径同源：顶层
+ * name / order 单行标量 + description 多行纯量（续行按 YAML 折叠语义以空格
+ * 拼接成单值）。读不到 / 解析不出时返回空元数据——声明行的 name /
+ * description / order 都是宿主可选键，缺省不致命。
+ */
+export function readPresetDirMeta(dir) {
+  try {
+    const text = readFileSync(path.join(dir, 'preset.yml'), 'utf8')
+    const lines = text.split(/\r?\n/)
+    const firstMatch = (re) => {
+      for (const line of lines) {
+        const m = re.exec(line)
+        if (m) return m
+      }
+      return null
+    }
+    const name = firstMatch(/^name:[ \t]*(.+?)[ \t]*$/)?.[1] ?? null
+    const orderRaw = firstMatch(/^order:[ \t]*(\d+)[ \t]*$/)
+    const order = orderRaw ? Number(orderRaw[1]) : null
+    let description = null
+    const di = lines.findIndex((l) => /^description:/.test(l))
+    if (di !== -1) {
+      const parts = [lines[di].slice('description:'.length).trim()]
+      for (let i = di + 1; i < lines.length; i++) {
+        const line = lines[i]
+        if (line.trim() === '' || !/^[ \t]/.test(line)) break // 续行尽 / 撞上下一个顶层键
+        parts.push(line.trim())
+      }
+      description = parts.filter((p) => p !== '').join(' ') || null
+    }
+    return { name, description, order }
+  } catch {
+    return { name: null, description: null, order: null }
+  }
+}
+
+/**
+ * 把磁盘上已有的编排类 preset 目录补写进 home patch 托管块（缺行才补，已有行
+ * 原样不动）；行在、目录没了的撤行——目录与行同生同灭。产物不全（缺
+ * agent.cordis.yml / restrict.mjs）的目录跳过并 warn，不拖垮其余补写。
+ * 返回实际补写成功的 presetId 列表（既没补也没撤时为空数组）。
+ */
+export function backfillHomePatchRows(dshHome, presetIds) {
+  const rowsOnDisk = readHomePatchRows(dshHome)
+  const wanted = new Set((Array.isArray(presetIds) ? presetIds : []).filter((id) => ORCHESTRATOR_PRESET_ID_RE.test(id)))
+  const rows = []
+  const backfilled = []
+  for (const presetId of wanted) {
+    if (rowsOnDisk.some((r) => r.presetId === presetId)) continue
+    const dir = path.join(dshHome, '.agent-presets', presetId)
+    try {
+      const agentYmlText = readFileSync(path.join(dir, 'agent.cordis.yml'), 'utf8')
+      const restrictFile = path.join(dir, 'restrict.mjs')
+      if (!existsSync(restrictFile)) throw new Error('restrict.mjs 缺失')
+      const meta = readPresetDirMeta(dir)
+      rows.push(
+        buildPresetRowText({
+          presetId,
+          name: meta.name,
+          description: meta.description,
+          order: meta.order,
+          agentYmlText,
+          restrictFileUrl: pathToFileURL(restrictFile).href,
+        }),
+      )
+      backfilled.push(presetId)
+    } catch (err) {
+      warn(`声明行补写跳过 ${presetId}（产物不全，可整盘重生成修复）: ${err?.message ?? err}`)
+    }
+  }
+  if (rows.length > 0) upsertHomePatchRows(dshHome, rows)
+  // 反向对账：托管块里有行、磁盘上已无对应目录的（用户手删目录等），行同步撤下
+  const orphanRowIds = rowsOnDisk.filter((r) => r.presetId !== null && !wanted.has(r.presetId)).map((r) => r.rowId)
+  if (orphanRowIds.length > 0) stripHomePatchRows(dshHome, orphanRowIds)
+  return backfilled
+}
+
+/**
+ * 解析 .generator-version 标记文本为 { version, track }。v2 格式两行：首行
+ * 生成器版本、次行预设安装轨道（declarative / directory）；旧格式（单行版本，
+ * 0.3.4 及以前）解析出 track: null —— 恰是「宿主轨道已翻转但产物版本未动」的
+ * 迁移触发态。空文本 / 全空白返回 null（按未生成处理）。
+ */
+export function parseGeneratorMarker(text) {
+  const lines = String(text ?? '')
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l !== '')
+  if (lines.length === 0) return null
+  const track = lines[1] === 'declarative' || lines[1] === 'directory' ? lines[1] : null
+  return { version: lines[0], track }
+}
+
+/** 生成 .generator-version 标记文本（版本 + 轨道两行，v2 格式）。 */
+export function formatGeneratorMarker(version, presetSystem) {
+  return `${version}\n${presetSystem}\n`
+}

package/tools/lib/state.mjs

@@ -16,7 +16,6 @@ import {
   copyFileSync,
   existsSync,
   mkdirSync,
-  readdirSync,
   readFileSync,
   rmSync,
   statSync,
@@ -50,8 +49,10 @@ import { smartDefaults } from './alloc.mjs'
 import {
   buildPresetRowText,
   detectPresetSystem,
+  listOrchestratorPresetIds,
   presetRowId,
   readHomePatchRows,
+  readPresetDirMeta,
   stripHomePatchRows,
   upsertHomePatchRows,
 } from './preset-system.mjs'
@@ -236,14 +237,7 @@ export async function collectState({ dshHome, configFile, profile = null, patche
   // 无读权限等）一律降级为空列表，绝不影响检测结果本体；generateAndInstall
   // 成功落盘后以它为对账清单做孤儿工作区 preset 回收。两轨的产物目录同名同
   // 位置（.agent-presets/<presetId>/），这一扫描天然覆盖两轨的 installed 判定。
-  let installedPresets = []
-  try {
-    installedPresets = readdirSync(path.join(dshHome, '.agent-presets'))
-      .filter((name) => /^orchestrator(-[a-z0-9-]+)?$/.test(name))
-      .sort()
-  } catch {
-    installedPresets = []
-  }
+  const installedPresets = listOrchestratorPresetIds(dshHome)
 
   return {
     dshHome,
@@ -283,43 +277,13 @@ export async function collectState({ dshHome, configFile, profile = null, patche
 }
 
 /**
- * SRC preset.yml 显示元数据提取（name / description / order）：声明行轨把这些
- * 值写进 home patch 声明行的 config，取值口径与目录轨写 preset.yml 完全同源
+ * SRC preset.yml 显示元数据（name / description / order）：声明行轨把这些值
+ * 写进 home patch 声明行的 config，取值口径与目录轨写 preset.yml 完全同源
  * （name 可被 main_agent_display_name / 工作区派生名覆盖，见 generateAndInstall
- * 调用处）。preset.yml 是仓库内受控格式：顶层 name / order 单行标量 +
- * description 多行纯量（续行按 YAML 折叠语义以空格拼接成单值，落声明行时由
- * JSON.stringify 转义）。读不到 / 解析不出时返回空元数据——声明行的
- * name / description / order 都是宿主可选键，缺省不致命。
+ * 调用处）。解析实现已沉到 preset-system.readPresetDirMeta（迁移对账同源复用）。
  */
 function readPresetMeta() {
-  try {
-    const text = readFileSync(path.join(SRC_DIR, 'preset.yml'), 'utf8')
-    const lines = text.split(/\r?\n/)
-    const firstMatch = (re) => {
-      for (const line of lines) {
-        const m = re.exec(line)
-        if (m) return m
-      }
-      return null
-    }
-    const name = firstMatch(/^name:[ \t]*(.+?)[ \t]*$/)?.[1] ?? null
-    const orderRaw = firstMatch(/^order:[ \t]*(\d+)[ \t]*$/)
-    const order = orderRaw ? Number(orderRaw[1]) : null
-    let description = null
-    const di = lines.findIndex((l) => /^description:/.test(l))
-    if (di !== -1) {
-      const parts = [lines[di].slice('description:'.length).trim()]
-      for (let i = di + 1; i < lines.length; i++) {
-        const line = lines[i]
-        if (line.trim() === '' || !/^[ \t]/.test(line)) break // 续行尽 / 撞上下一个顶层键
-        parts.push(line.trim())
-      }
-      description = parts.filter((p) => p !== '').join(' ') || null
-    }
-    return { name, description, order }
-  } catch {
-    return { name: null, description: null, order: null }
-  }
+  return readPresetDirMeta(SRC_DIR)
 }
 
 /**