@xiaoso/dsh-tool-plus 0.1.9 → 0.1.10-beta.2

package/lib/types/host/browser-probe-rpc.d.ts

@@ -6,7 +6,8 @@
  *
  * **Why this registers its own route instead of calling `connection.rpc.handle`.**
  * The documented helper is unusable from a plugin in a real web deployment on
- * dsh 0.1.5-rc.1: `HostConnectionService.rpc` builds its handle against
+ * dsh 0.1.5-rc.1 — and still on 0.1.7-rc.1, re-checked for this migration:
+ * `HostConnectionService.rpc` builds its handle against
  * `owner = this.ctx` (`rpc-host.ts: "Generic channel registry scoped to the
  * Context reading this service"`), and `register()` then evaluates
  * `owner.webServer.register(route)`. The client-connection row declares

package/lib/types/host/preset-host.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Host half of the preset surface: read the deployment's declared presets and
+ * apply the panel's three actions through the harness's own config editor.
+ *
+ * WHY WE DO NOT WRITE FILES OURSELVES: dsh 0.1.7 removed the directory preset
+ * mechanism and the `agent_preset` tool with it. The only supported programmatic
+ * write path is `ctx.configEditor.edit()`, and it is a better one than we had —
+ * it takes the profile lock, serializes with HMR, validates the next config
+ * through the Loader's own waterfall, writes atomically, rolls back on a failed
+ * reconcile, and refuses when a home patch or `--patch` overlay would defeat the
+ * edit. It also gives us "revert to the bundled declaration" for free: handing
+ * back the inherited config makes it delete the override's `config` key.
+ *
+ * The service is resolved per call, so a deployment that mounts the editor
+ * after this plugin still works instead of caching an early `undefined`.
+ *
+ * Everything here is a thin adapter; the decisions live in `src/presets/**`
+ * (pure, fs-free, unit-testable) and this module only resolves services and
+ * shapes results.
+ * @module @xiaoso/dsh-tool-plus/host/preset-host
+ */
+import { type PresetActionResultValue, type PresetCompareValue, type PresetStatusListValue } from '../tools/shared/browser-rpc-channel.ts';
+import { type PresetActionKind } from '../presets/plan.ts';
+/** The context slice this module needs: Cordis service lookup only. */
+export interface PresetHostCtx {
+    get(name: string): unknown;
+}
+/** Structural view of one addressable Loader entry. */
+interface EntryLike {
+    options: {
+        id: string;
+        name?: string;
+        config?: unknown;
+    };
+}
+/** One `configEditor.configuration()` row. */
+interface ConfigurationRowLike {
+    entry: EntryLike;
+    /** The bundled layer's config (our shipped declaration). */
+    inherited: Record<string, unknown>;
+    /** The profile layer's config; `{}` when the user never overrode the row. */
+    override: Record<string, unknown>;
+}
+/**
+ * The slice of `@deepseek-ai/dsh-config-editor` this plugin uses. Declared
+ * structurally so the plugin keeps zero build-time coupling to a package it
+ * never bundles.
+ */
+export interface ConfigEditorLike {
+    /** Absolute path of the profile patch this editor writes. */
+    readonly documentPath: string;
+    entries(): readonly EntryLike[];
+    configuration(): readonly ConfigurationRowLike[];
+    edit(entry: EntryLike, change: (current: Record<string, unknown>, inherited: Record<string, unknown>) => Record<string, unknown>): Promise<void>;
+}
+/** One roster entry as the registry reports it. */
+interface RosterRowLike {
+    readonly id?: unknown;
+    readonly name?: unknown;
+    readonly description?: unknown;
+    readonly broken?: unknown;
+    readonly isDefault?: unknown;
+}
+/**
+ * The slice of the preset registry this plugin uses.
+ *
+ * `remoteExportList()` is preferred: it is the roster the official client reads,
+ * and unlike `list()` it also carries `isDefault`. `list()` remains the fallback
+ * for a deployment whose registry predates the exported roster.
+ */
+export interface AgentPresetsLike {
+    list?(): Promise<readonly RosterRowLike[]>;
+    remoteExportList?(): Promise<{
+        readonly presets?: readonly RosterRowLike[];
+    } | undefined>;
+}
+/**
+ * Answer `presets/status`.
+ * @param ctx - context used to resolve the config editor and the registry.
+ * @returns the panel's full status payload.
+ */
+export declare function listPresetStatuses(ctx: PresetHostCtx): Promise<PresetStatusListValue>;
+/**
+ * Answer `presets/apply` by planning the action and, when it is worth writing,
+ * delegating the write to the harness's own config editor.
+ * @param ctx - context used to resolve the services.
+ * @param presetId - the preset to act on.
+ * @param action - `upgrade`, `align` or `revert`.
+ * @param templateId - the align target (required for `align`).
+ * @returns the action result, never throwing.
+ */
+export declare function applyPresetAction(ctx: PresetHostCtx, presetId: string, action: PresetActionKind, templateId?: string): Promise<PresetActionResultValue>;
+/**
+ * Answer `presets/compare`: one preset's effective plugins against one of our
+ * declared templates. Never throws; an unresolvable side reports `unreadable`
+ * (that is a state the panel renders as a red dot, not a failed call).
+ * @param ctx - context used to resolve the services.
+ * @param presetId - the preset being inspected.
+ * @param templateId - the template to compare it against.
+ * @returns the comparison.
+ */
+export declare function comparePresetAgainstTemplate(ctx: PresetHostCtx, presetId: string, templateId: string): Promise<PresetCompareValue>;
+export {};

package/lib/types/host/preset-rpc.d.ts

@@ -1,102 +1,67 @@
 /**
  * Host half of the preset endpoints: answers `presets/status` (roster +
- * conflicts + template diff) and `presets/apply` (disable conflicting rows /
- * reset from our template) for the settings panel's 「全局」tab.
+ * conflicts + template diff), `presets/apply` (upgrade / align / revert) and
+ * `presets/compare` for the settings panel's 「全局」tab.
  *
- * These endpoints live on the **same** `/tool-plus` channel registration as
- * `browser/detect` and `rmSafe/status` (see `browser-probe-rpc.ts`): a
- * Connection channel has exactly one handler, so a second
- * `connection.rpc.handle('/tool-plus', …)` never takes effect. That is why this
- * module exports an endpoint handler instead of installing a channel of its
- * own.
+ * These endpoints live on the **same** `/tool-plus` route as `browser/detect`
+ * and `rmSafe/status` (see `browser-probe-rpc.ts`). That route is a plain
+ * `webServer.register({ kind: 'prefix', path: '/tool-plus' })` registration, NOT
+ * `connection.rpc.handle`: in this deployment the Connection handler resolves
+ * its owner through `this.ctx` without the `webServer` injection, so a
+ * `rpc.handle` registration never takes effect. The Connection service is still
+ * used for its loopback trust fence (`connection.requestRejection`).
  *
- * The preset analysis itself lives in `src/presets/**` and is **injected**, so
- * this module stays a thin wire adapter and its helpers are testable without a
- * Connection service or a filesystem.
- *
- * Trust policy is `loopback` (the channel's own policy): these endpoints read
- * and write files under the user's DSH home, so they must never be reachable
- * from a non-loopback host.
+ * This module is a wire adapter only: payload validation plus dispatch into an
+ * injected {@link PresetRpcDeps}. The service lookup, the configuration reads
+ * and the writes live in `../host/preset-host.ts`; the decision logic lives in
+ * `src/presets/**`. Trust policy is `loopback` — these endpoints read the user's
+ * profile configuration and the write path edits it, so they must never be
+ * reachable from a non-loopback host.
  * @module @xiaoso/dsh-tool-plus/host/preset-rpc
  */
 import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection';
-import { type PresetActionPayload, type PresetComparePayloadValue } from '../tools/shared/browser-rpc-channel.ts';
-import type { PresetInstallResult } from '../presets/install.ts';
-import type { PresetComparison, PresetTemplate } from '../presets/compare.ts';
-import type { PresetRosterEntry, PresetStatus } from '../presets/status.ts';
-/** Payload shape of a `presets/compare` call (shared contract). */
-type PresetComparePayload = PresetComparePayloadValue;
+import { type PresetActionPayload, type PresetActionResultValue, type PresetActionValue, type PresetComparePayloadValue, type PresetCompareValue, type PresetStatusListValue } from '../tools/shared/browser-rpc-channel.ts';
 /** Result shape of one Connection RPC call (official pattern in the gateway). */
 type ConnectionRpcResult = Awaited<ReturnType<ConnectionRpcHandler>>;
+/** The context slice this handler needs: pass-through to the injected deps. */
+export interface PresetEndpointCtx {
+    /** Cordis service lookup, forwarded to the host implementation. */
+    get(name: string): unknown;
+}
 /**
- * Structural view of one official `ctx.agentPresets.list()` entry. Declared
- * here instead of importing `@deepseek-ai/dsh-agent-presets` so the plugin
- * keeps zero build-time coupling to a package it never bundles — the service
- * is reached through the context, and every field is validated on the way in.
+ * Everything the endpoints need from the host plane. Injected so this module
+ * stays a thin wire adapter whose parsing helpers are testable without a
+ * Connection service, a Loader, or a profile.
  */
-interface RosterPresetLike {
-    readonly id?: unknown;
-    readonly trust?: unknown;
-    readonly path?: unknown;
-    readonly name?: unknown;
-    readonly description?: unknown;
-    readonly broken?: unknown;
-}
-/** The only slice of the official agent-presets service this plugin uses. */
-export interface AgentPresetsServiceLike {
-    list(): Promise<readonly RosterPresetLike[]>;
-}
-/** Install-time dependencies: the preset analysis owned by the host half. */
 export interface PresetRpcDeps {
-    /** Build one status row per roster entry (reads the user root, never writes). */
-    listStatuses: (roster: readonly PresetRosterEntry[]) => PresetStatus[];
-    /** Apply one action to one preset (the only endpoint that writes). */
-    applyAction: (id: string, action: PresetActionPayload['action'], templateId?: string) => PresetInstallResult;
-    /** Templates this package ships (the panel's "compare with" options). */
-    listTemplates: () => PresetTemplate[];
-    /**
-     * Read-only comparison between one roster preset and one of our templates.
-     * Returns `status: 'unreadable'` instead of throwing when a file cannot be
-     * read — that is a state the panel renders (red dot), not a failed call.
-     */
-    comparePreset: (preset: PresetRosterEntry, templateId: string) => PresetComparison;
+    /** Read every declared preset with its conflicts and template diff. */
+    listPresets: (ctx: PresetEndpointCtx) => Promise<PresetStatusListValue>;
+    /** Apply one action to one preset. The only path that writes. */
+    applyAction: (ctx: PresetEndpointCtx, id: string, action: PresetActionValue, templateId?: string) => Promise<PresetActionResultValue>;
+    /** Read-only comparison between one preset and one of our declarations. */
+    comparePreset: (ctx: PresetEndpointCtx, presetId: string, templateId: string) => Promise<PresetCompareValue>;
 }
 /**
  * Validate a `presets/compare` payload: two non-empty ids, nothing else.
  * @param payload - the raw RPC payload.
  * @returns the narrowed payload, or undefined when invalid.
  */
-export declare function parsePresetComparePayload(payload: unknown): PresetComparePayload | undefined;
+export declare function parsePresetComparePayload(payload: unknown): PresetComparePayloadValue | undefined;
 /**
  * Validate a `presets/apply` payload. Anything that is not exactly
- * `{ id: non-empty string, action: 'upgrade' | 'reset' }` is rejected, so the
- * write endpoint never receives a half-formed request.
+ * `{ id: non-empty string, action: 'upgrade' | 'align' | 'revert', templateId?: non-empty string }`
+ * is rejected, so the write endpoint never receives a half-formed request.
  * @param payload - the raw RPC payload.
  * @returns the narrowed payload, or undefined when invalid.
  */
 export declare function parsePresetActionPayload(payload: unknown): PresetActionPayload | undefined;
 /**
- * Narrow one roster entry coming from the official service. Unknown trust is
- * treated as `user` (the conservative side: it is a writable preset only when
- * the caller proves otherwise — the caller matches ids against our templates).
- * @param preset - raw entry from `ctx.agentPresets.list()`.
- * @returns the entry in our own shape.
- */
-export declare function toRosterEntry(preset: RosterPresetLike): PresetRosterEntry;
-/** The context slice this handler needs: service lookup only. */
-export interface PresetEndpointCtx {
-    /** Cordis service lookup; `agentPresets` is mounted by the harness. */
-    get(name: string): unknown;
-}
-/**
- * Answer one preset endpoint on the shared `/tool-plus` channel.
+ * Answer one preset endpoint on the shared `/tool-plus` route.
  *
  * Returns `undefined` for an endpoint this module does not own, so the caller
- * (the single channel handler) can keep serving its own families. The service
- * is resolved per call: a deployment that mounts `agent-presets` after this
- * plugin still gets a working endpoint instead of a stale `undefined`.
- * @param ctx - context used to resolve the `agentPresets` service.
- * @param deps - injected preset analysis.
+ * (the single route handler) can keep serving its own families.
+ * @param ctx - context forwarded to the injected host implementation.
+ * @param deps - injected host implementation.
  * @param endpoint - the requested endpoint name.
  * @param payload - the raw RPC payload.
  * @returns the RPC result, or undefined when the endpoint is not ours.

package/lib/types/presets/compare.d.ts

@@ -1,28 +1,22 @@
 /**
- * 预设比较：把"某份预设"和"我们随包的某个模板"放在一起看。
+ * 预设比较：把"某份 preset 生效的 plugins"和"某个随包声明的 plugins"放在一起看。
  *
- * 面板现在是两块信息、两个状态点：
- *   ①**工具行**：这份预设里我们那 4 个冲突行都禁用了吗（=`conflicts`）；
- *   ②**完整比较**：内容上和我们选的模板差多少（=`items`，弹窗里逐条展示）。
- * 这是只读操作，绝不写盘。比较一律**不跳过**冲突行的 `disabled` —— 第二个点
- * 要的是"完整的比较"，工具开关的不同也必须出现在差异清单里，否则会出现
- * "说内容一致、却说工具行没配好"这种自相矛盾的读数。
+ * 面板是两块信息、两个状态点：
+ *   ①**工具行**：这份 preset 里那 4 个冲突行都禁用了吗（=`conflicts`）；
+ *   ②**完整比较**：内容上和选中的模板差多少（=`items`，弹窗里逐条展示）。
+ * 只读，绝不写盘。比较一律**不跳过**冲突行的 `disabled` —— 第二个点要的是
+ * "完整的比较"，工具开关的不同也必须出现在差异清单里，否则会出现"说内容一致、
+ * 却说工具行没配好"这种自相矛盾的读数。
  * @module @xiaoso/dsh-tool-plus/presets/compare
  */
-import { type PresetDeps } from './paths.ts';
 import { type PresetDeltaItem } from './delta.ts';
-/** 面板"对比模板"下拉的一项：模板 id（可读性靠 name）。 */
-export interface PresetTemplate {
-    id: string;
-    name?: string;
-}
 /** 一次比较的结果（面板两个状态点 + 弹窗的全部数据）。 */
 export interface PresetComparison {
-    /** 任一侧读不到或形状不可识别 → `unreadable`，此时 `items` 为空。 */
+    /** 任一侧不是合法行列表 → `unreadable`，此时 `items` 为空。 */
     status: 'ok' | 'unreadable';
-    /** 这份预设里还没禁用的冲突行（空 = 我们的工具已生效）。 */
+    /** 这份 preset 里还没禁用的冲突行（空 = 本插件的工具已生效）。 */
     conflicts: string[];
-    /** 内容层面逐项一致（注释与排版差异不算，逐字节相同也不额外判断）。 */
+    /** 内容层面逐项一致（顺序不同不算差异，逐值比较）。 */
     identical: boolean;
     yoursCount: number;
     behindCount: number;
@@ -30,26 +24,9 @@ export interface PresetComparison {
     items: PresetDeltaItem[];
 }
 /**
- * 列出包里带模板的预设 id（面板"对比模板"下拉的选项）。只读目录，不抛。
- * @param deps - 路径注入（测试用）。
- * @returns 按 id 排序的模板清单（读不到目录时为空数组）。
- */
-export declare function listTemplates(deps?: PresetDeps): PresetTemplate[];
-/** 读一份模板的组合文件；不存在返回 undefined。 */
-export declare function readTemplateComposition(templateId: string, deps?: PresetDeps): string | undefined;
-/**
- * 比较两份组合文件文本（纯函数，只读）。
- * @param presetText - 所选预设的原文。
- * @param templateText - 所选模板的原文。
+ * 比较两份 `config.plugins`（纯函数，只读）。
+ * @param presetPlugins - 所选 preset 生效的 plugins。
+ * @param templatePlugins - 所选模板的 plugins（随包声明）。
  * @returns 两个状态点与弹窗需要的全部数据。
  */
-export declare function compareCompositions(presetText: string, templateText: string): PresetComparison;
-/**
- * 读盘版比较：预设一侧用 roster 给的组合文件路径，模板一侧按 id 去包里找。
- * 任一侧读不到都返回 `unreadable` —— 那是面板要渲染的红点，不是调用失败。
- * @param presetPath - 所选预设的组合文件绝对路径（来自 roster）。
- * @param templateId - 所选模板的 id。
- * @param deps - 路径注入（测试用）。
- * @returns 比较结果。
- */
-export declare function comparePresetFile(presetPath: string, templateId: string, deps?: PresetDeps): PresetComparison;
+export declare function comparePlugins(presetPlugins: unknown, templatePlugins: unknown): PresetComparison;

package/lib/types/presets/conflicts.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 冲突不变式：一个 preset「接上了本插件的工具」当且仅当官方那 4 个工具行
+ * 处于**不存在**或 **`disabled: true`** 状态。
+ *
+ * 原因（这套设计的地基，别丢）：`@xiaoso/dsh-tool-plus` 作为包在**宿主面**
+ * 加载时，它自己的 profile 补丁已经禁用了这 4 行并插入**一行全局** `tool-plus`；
+ * 注册表按 scope 分层、就近优先，所以宿主面那一份已经服务所有会话。若某个
+ * preset 又在 **agent 面**挂一份同名工具行，就会用**第二个 `apply()` 影子实例**
+ * 盖掉健康的宿主实例，而那个实例的 settings 注入永不触发（cfg 退化成
+ * replace-mode 读取 —— 2026-08-25 hashline 事故的根因）。
+ *
+ * 与旧文本实现的唯一区别是**载体**：以前逐行读 `agent.cordis.yml` 的文本，
+ * 现在直接看宿主交给我们的行对象。判定规则一字不改：
+ * - 只认**顶层**行；group 里嵌套的同名行不碰；
+ * - `disabled` 严格等于布尔 `true` 才算已处理 —— 缺席、`false`、字符串、
+ *   `!!js` 表达式统统算冲突（`!!js` 在挂载时才求值，我们要的是无条件关闭，
+ *   所以和旧实现一样整值翻成 `true`）；
+ * - 输出恒为新数组，输入不变；结果与输入逐值相同时 `changes` 为空（调用方以
+ *   此判定"不写盘"）。
+ * @module @xiaoso/dsh-tool-plus/presets/conflicts
+ */
+import { type PresetRow } from './rows.ts';
+/** 官方 standard / ptc / cordis 会挂的 4 个工具行 id。 */
+export declare const PRESET_CONFLICT_IDS: readonly string[];
+/** 一次改写实际发生的一处改动。 */
+export interface PresetChange {
+    /** 行 id（顶层 `- id: <id>`）。 */
+    id: string;
+    /** `disabled` = 该行原本没有 `disabled` 键，现在补上；`flipped` = 既有值被翻成 `true`。 */
+    action: 'disabled' | 'flipped';
+}
+/** 只读判定：给设置页状态用。 */
+export interface PresetAnalysis {
+    /** 仍挂着冲突行的 id（缺 `disabled` 或值不是布尔 `true`），按 conflictIds 顺序。 */
+    conflicts: string[];
+    /** 无冲突且形状可识别。 */
+    clean: boolean;
+    /** `unrecognized` = 不是合法的顶层行列表，一律不处理也不改写。 */
+    shape: 'ok' | 'unrecognized';
+}
+/**
+ * 只读分析一份 `plugins` 值。
+ * @param plugins - 声明的子插件列表（来自宿主配置，形状未知）。
+ * @param conflictIds - 冲突行清单，默认 {@link PRESET_CONFLICT_IDS}。
+ * @returns 冲突清单、是否干净、形状是否可识别。
+ */
+export declare function analyzePlugins(plugins: unknown, conflictIds?: readonly string[]): PresetAnalysis;
+/** 改写结果：新列表 + 实际改动清单 + 改写后仍未解决的冲突（理论上为空）。 */
+export interface PresetConflictRewrite {
+    plugins: PresetRow[];
+    changes: PresetChange[];
+}
+/**
+ * 把那 4 个仍挂着的冲突行翻成 `disabled: true`（不改别的行、不删行）。
+ * @param plugins - 合法顶层行列表。
+ * @param conflictIds - 冲突行清单，默认 {@link PRESET_CONFLICT_IDS}。
+ * @returns 新列表与实际改动清单（无改动时 `changes` 为空且列表为原引用）。
+ */
+export declare function disableConflicts(plugins: readonly PresetRow[], conflictIds?: readonly string[]): PresetConflictRewrite;

package/lib/types/presets/delta.d.ts

@@ -1,16 +1,18 @@
 /**
- * 预设差异清单：只读地说清"用户这份和随包模板差在哪"。
+ * 差异清单：只读地说清"这份 preset 与另一份（通常是随包声明）差在哪"。
  *
  * 为什么需要它：`templateDiffers: boolean` 只能说"不一样"，而面板上紧挨着的
- * 是"工具冲突行都已禁用、无需调整"。两句都对，但读起来打架 —— 前者说的是
- * **你改过内容**，后者说的是**我们自己那 4 个冲突行**。把差异逐条列出来，
- * 面板才不需要用户自己猜"到底哪里不同、更新会不会动它"。
+ * 是"冲突行都已禁用、无需调整"。两句都对，读起来却打架 —— 前者说的是
+ * **内容被改过**，后者说的是**我们自己那 4 个冲突行**。把差异逐条列出来，
+ * 用户才不用猜"到底哪里不同、对齐会不会动它"。
  *
- * 契约：①比**展开到叶子的点号路径**（`config.thresholdRatio`，列表项带 `[i]`）——
- * 真实漂移常藏在嵌套键里，只比顶层键会得出"没有差异"的错误结论；②冲突行的
- * `disabled` 由 `conflicts` 负责，不在差异里重复报；③形状不可识别 → 空清单，
- * 绝不猜；④顺序＝用户这份的行序在前，模板独有的行补在后；⑤`total` 是全量，
- * `items` 可被 `limit` 截断（面板据此说"等 N 项"）。
+ * 契约（自旧文本实现原样继承，语义未变）：
+ * - 比**展开到叶子的点号路径**（`config.thresholdRatio`、`config.models[0].id`）——
+ *   真实漂移常藏在嵌套键里，只比顶层键会得出"没有差异"的错误结论；
+ * - 冲突行的 `disabled` 由 `conflicts` 负责，不在差异里重复报；
+ * - 形状不可识别 → 空清单，绝不猜；
+ * - 顺序 = 你这份的行序在前（含 group 内子行），对方独有的行补在后；
+ * - `total` 是全量，`items` 可被 `limit` 截断（面板据此说"等 N 项"）。
  * @module @xiaoso/dsh-tool-plus/presets/delta
  */
 /** 一条差异：整行只在一侧、某个叶子只在一侧、或同一个叶子两边值不同。 */
@@ -18,13 +20,16 @@ export type PresetDeltaKind = 'changed' | 'only-yours' | 'only-template' | 'row-
 /** 差异清单的一项。`path` 为空串表示整行层面的差异。 */
 export interface PresetDeltaItem {
     kind: PresetDeltaKind;
-    /** 顶层行的 id。 */
+    /**
+     * 行路径：顶层行的 id（`tool-web`），或 group 内子行（`delegation/tool-ralph`）。
+     * 用路径而不是裸 id，是因为嵌套行重名时裸 id 会指错行。
+     */
     row: string;
     /** 行内点号路径（如 `config.thresholdRatio`）；整行差异时为空串。 */
     path: string;
     /** 你这份里的值（`only-template` / `row-only-template` 时不带）。 */
     yours?: string;
-    /** 模板里的值（`only-yours` / `row-only-yours` 时不带）。 */
+    /** 对方的同名值（`only-yours` / `row-only-yours` 时不带）。 */
     template?: string;
 }
 /** 差异清单：`items` 已按 `limit` 截断，`total` 是全量条数。 */
@@ -32,21 +37,21 @@ export interface PresetDelta {
     items: PresetDeltaItem[];
     total: number;
     /**
-     * 全量口径的两个分组：`yoursCount` = 你自己加/改的（更新不覆盖，重置会覆盖），
-     * `behindCount` = 模板有而你没有的（模板已更新，重置可对齐）。
+     * 全量口径的两个分组：`yoursCount` = 你自己加/改的（对齐会覆盖它），
+     * `behindCount` = 对方有而你没有的（对方已更新，对齐可补上）。
      * 分组计数必须按**全量**算：`items` 被 `limit` 截断后数它会把"等 N 项"说错。
      */
     yoursCount: number;
     behindCount: number;
 }
 /**
- * 比较两份组合文件，列出差异（只读，不改任何字节）。
- * @param userText - 用户这份的 `agent.cordis.yml` 原文。
- * @param templateText - 随包模板的同一文件原文。
+ * 比较两份 `config.plugins`，列出差异（只读，不改任何值）。
+ * @param yours - 你这一侧的 plugins（形状未知）。
+ * @param theirs - 对方的 plugins（形状未知）。
  * @param options - `conflictIds`（默认 {@link PRESET_CONFLICT_IDS}）与 `limit`（默认 6）。
- * @returns 差异清单；两侧任一不可识别时为空清单。
+ * @returns 差异清单；两侧任一形状不可识别时为空清单。
  */
-export declare function presetDelta(userText: string, templateText: string, options?: {
+export declare function presetDelta(yours: unknown, theirs: unknown, options?: {
     conflictIds?: readonly string[];
     limit?: number;
 }): PresetDelta;

package/lib/types/presets/plan.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 动作判定：三个面板动作各自"要不要动手、动手算不算真改动"。**纯函数**。
+ *
+ * 这一层存在的理由：真正落盘的是宿主自己的 `ctx.configEditor.edit()`，它**每次
+ * 调用都会重写 profile 补丁文件**（哪怕内容一个字没变）。所以"是否值得写"必须
+ * 在调用它**之前**判定，否则面板每点一次都会白改一次 mtime、白触发一轮 HMR 重载。
+ * 判定所需的事实全部来自 {@link PresetFacts}，因此这里可以纯函数测试，不需要
+ * 真的 profile、也不需要 cordis。
+ *
+ * 三个动作的语义（自旧目录机制映射而来，见 CHANGELOG）：
+ * - `upgrade`（最小更新）：只把仍挂着的官方冲突行翻成 `disabled: true`。不改别的行，
+ *   不动显示元数据 —— 幂等，已干净时一个字节都不写。
+ * - `align`（对齐模板）：把生效的 plugins 整份换成所选模板声明的 plugins。
+ *   *对齐到自己的随包声明* = 撤销覆盖，等价于 `revert`，这里直接归约过去。
+ * - `revert`（恢复随包）：让宿主删掉 profile 补丁里那一行的 `config`，
+ *   于是这一行回落到随包声明。没有覆盖时是 no-op。
+ * @module @xiaoso/dsh-tool-plus/presets/plan
+ */
+import type { PresetChange } from './conflicts.ts';
+/** 面板可以请求的三个动作。 */
+export type PresetActionKind = 'upgrade' | 'align' | 'revert';
+/** 判定所需的全部事实。 */
+export interface PresetPlanInput {
+    action: PresetActionKind;
+    /** 这个 preset 是不是本插件声明的（只有 ours 允许 align / revert）。 */
+    ours: boolean;
+    /** 用户是否在 profile 层写过覆盖。 */
+    customized: boolean;
+    /** 生效的完整 config（宿主的 `entry.options.config`）；取不到时 undefined。 */
+    effective: Record<string, unknown> | undefined;
+    /** 随包声明那一层的完整 config（宿主的 `inherited`）。 */
+    inherited: Record<string, unknown> | undefined;
+    /** `align` 的目标模板 plugins。 */
+    templatePlugins?: unknown;
+    /** `align` 请求的模板 id（仅用于文案与校验）。 */
+    templateId?: string;
+}
+/** 判定结果。 */
+export type PresetPlan = {
+    kind: 'noop';
+    reason: string;
+} | {
+    kind: 'upgrade';
+    changes: PresetChange[];
+} | {
+    kind: 'align';
+} | {
+    kind: 'revert';
+};
+/**
+ * 判定一个动作该不该写、会改什么。
+ * @param input - 判定所需的事实。
+ * @returns 计划；`noop` 时调用方**不要**调用 `configEditor.edit`。
+ */
+export declare function planPresetAction(input: PresetPlanInput): PresetPlan;

package/lib/types/presets/rows.d.ts

@@ -0,0 +1,84 @@
+/**
+ * preset 组合的**行模型**：官方声明式 preset 的 `config.plugins` 就是一棵
+ * Cordis entry list，本模块是它唯一的读写口径。
+ *
+ * 为什么不再有 YAML 文本层：旧机制里预设是磁盘上的 `agent.cordis.yml`，我们
+ * 只能逐行做文本手术（保缩进、保注释、保 CRLF）。0.1.7 起预设是 profile 配置
+ * 里的一条声明，宿主给我们的**已经是解析好的对象树**（`configEditor` 的
+ * `inherited` / `override`，以及 `entry.options.config`），再走文本就是自找
+ * 麻烦：`!!js` 标记、块标量、引号风格全都不该由我们操心。
+ *
+ * 三条纪律：
+ * - **形状判定照抄官方**：顶层必须是行列表，且每一行是带非空字符串 `name`
+ *   的映射（官方 `entryListProblem` 同款）。不满足 → `undefined`，一律不处理。
+ * - **只认顶层行**：`tool-bash`/`tool-fs` 这类 id 只按顶层匹配；group 里嵌套的
+ *   同名行属于那个 group 的私有组成，绝不被外层动作波及。
+ * - **绝不原地改**：所有"改写"都返回新对象，输入保持可比较（宿主按深相等判定
+ *   是否落盘，原地改会让幂等判定失去意义）。
+ * @module @xiaoso/dsh-tool-plus/presets/rows
+ */
+/** 一行 Cordis 配置项的最小子集（其余键原样透传）。 */
+export interface PresetRow {
+    id?: unknown;
+    name?: unknown;
+    group?: unknown;
+    disabled?: unknown;
+    isolate?: unknown;
+    config?: unknown;
+    [key: string]: unknown;
+}
+/** 行 id 的取值（非空字符串才认，与官方对 `name` 的要求同款）。 */
+export declare function rowId(row: PresetRow): string | undefined;
+/** 行模块名（官方 entry-list 要求每行都有非空 `name`）。 */
+export declare function rowName(row: PresetRow): string | undefined;
+/** 这一行是不是 group 载体（group 的子行在 `config` 里）。 */
+export declare function isGroupRow(row: PresetRow): boolean;
+/**
+ * 判定一份 `plugins` 值是不是合法的顶层行列表。规则与官方
+ * `entryListProblem` 一致：必须是数组，每一项必须是带非空 `name` 的映射。
+ * @param value - 待判定的值（来自宿主配置或测试注入）。
+ * @returns 合法时为 true。
+ */
+export declare function isRowList(value: unknown): value is PresetRow[];
+/**
+ * 展平一棵行树（含 group 嵌套），键为 `父/子` 形式的路径。
+ *
+ * 路径是**给面板看的标识**，也用于我们自己的差异比较；官方
+ * `compositionInventory()` 回的行没有路径（它压平后只剩 entryId/moduleName），
+ * 所以需要分组结构时只能从声明本身取。
+ * @param rows - 顶层行列表。
+ * @param prefix - 递归时的父路径。
+ * @returns 路径 → 行。
+ */
+export declare function flattenRows(rows: readonly PresetRow[], prefix?: string): Map<string, PresetRow>;
+/** 一个叶子：行内点号路径 → 规范化后的值字符串。 */
+export interface RowLeaf {
+    /** 行内路径，如 `config.thresholdRatio` 或 `config.models[0].id`。 */
+    path: string;
+    /** 规范化值：标量走 `JSON.stringify`，所以 `true`/`"true"`/`1` 不会互相混淆。 */
+    value: string;
+}
+/**
+ * `!!js` 表达式标记：entry-list 方言把它解析成 `{ __jsExpr: <源码> }`（见
+ * `vendor/include/src/index.ts` 的 `JsExpr`）。它对我们是**标量**——一整段待求值的
+ * 源码，不是可以逐键比较的结构。漏了这一步会造出 `disabled.__jsExpr` 这种假叶子，
+ * 顺带让"冲突行的 disabled 归 conflicts 管"这条跳过规则失效。
+ * @param value - 待判定的值。
+ * @returns 是表达式标记时为 true。
+ */
+export declare function isJsExpr(value: unknown): value is {
+    __jsExpr: string;
+};
+/**
+ * 收集一行自己的叶子路径（不含 `id`，不含 group 的子行）。
+ *
+ * 用规范化 JSON 而不是 `String()`：Loader 对 `disabled` 的语义是
+ * "布尔取 Boolean(value)"，所以字符串 `"false"` 与布尔 `false` **语义相反**；
+ * 两者若都显示成 `false`，面板就会把一处真实差异藏起来。
+ * @param row - 目标行。
+ * @param base - 递归时的前缀。
+ * @returns 该行的叶子清单（顺序为键的声明顺序）。
+ */
+export declare function rowLeaves(row: PresetRow, base?: string): RowLeaf[];
+/** 规范化的深比较（两侧都是 YAML/JSON 值，无函数与原型差异）。 */
+export declare function sameValue(a: unknown, b: unknown): boolean;