dsh-plugin-prompt-tool 0.7.2 → 0.8.0

package/lib/index.d.mts

@@ -1,103 +1,250 @@
-import { c as PresetWriterParams, l as WRITER_PARAM_KEYS, n as PromptConfigFile, r as PromptConfigSpec, s as ENGINE_PARAM_KEYS } from "./prompt-configs-CN0sJTUL.mjs";
+import { $ as ENGINE_RECIPES, A as resolvePresetParams, B as MAX_CHARACTER_CARD_STREAM_BYTES, C as loadPresetSpec, D as renderComposition, E as removeUserPreset, F as BridgeEndpoint, G as SkillPolicyChange, H as SkillCatalogEntry, I as BridgeErrorPayload, J as SkillsCatalogSnapshot, K as SkillPolicyScope, L as BridgeRequestMap, M as savePresetPersona, N as userPresetsDir, O as resolvePresetDir, P as BRIDGE_ENDPOINTS, Q as ENGINE_CAPABILITIES, R as BridgeValueMap, S as listPresets, T as removePresetModule, U as SkillContentSnapshot, V as SETTINGS_BRIDGE_PREFIX, W as SkillInvocation, X as invocationForScope, Y as SkillsState, Z as scopeOfInvocation, _ as buildModuleConfigsFromParams, a as installPresetPackage, at as isEngineCapabilityPresent, b as ensurePresetSeed, c as convertStToPreset, ct as ImportChoices, d as stPresetId, dt as InstructionFileSnapshot, et as EngineCapability, f as EngineCapabilityCreateRequest, ft as InstructionFileStatus, g as applyModuleConfigs, h as PresetSpec, i as exportPresetPackage, it as engineRecipe, j as savePresetParams, k as resolvePresetModuleFacts, l as mergeStPresets, lt as INSTRUCTION_FILE_STATUSES, m as EngineCapabilityRemoveResult, n as USER_SKILLS_DIR, nt as PresetModuleFacts, o as presetImportPreview, ot as validateCustomToolIdentities, p as EngineCapabilityCreateResult, pt as MAX_INSTRUCTION_FILE_BYTES, q as SkillSourceKind, r as expandPresetSource, rt as engineCapability, s as StConversionOptions, st as AssetFile, tt as ModuleSourceMode, u as processStText, ut as InstructionContextView, v as cloneBuiltinPreset, w as removeEngineCapabilityFromPreset, x as listBuiltinTemplates, y as createEngineCapabilityInPreset, z as MAX_BRIDGE_BODY_BYTES } from "./paths-CY5psBqE.mjs";
 import { parseDocument } from "yaml";
 import z from "@deepseek-ai/schemastery";
-import { Context } from "@deepseek-ai/cordis";
+import { Context, Volatile } from "@deepseek-ai/cordis";
+import { SkillViewOptions } from "@deepseek-ai/dsh-skill";
+import { AgentOptions } from "@deepseek-ai/dsh-agent";
+import { SubagentRuntime } from "@deepseek-ai/dsh-subagent";
+//#region src/host/prompt-configs.d.ts
+/**
+ * `PromptConfigSpec` 各枚举字段的**运行期值清单**。
+ *
+ * 类型由它派生（`(typeof X)[number]`），守卫测试也读它——于是「类型允许的值」与
+ * 「守卫断言的值」是同一份，不可能各自漂移；而这两个值集合都必须与 `engine/schema.mjs`
+ * 的对应 `KNOWN_*` 一致（守卫见 `test/shared/prompt-config-spec-enums.test.mjs`）。
+ *
+ * 为什么不直接从引擎派生类型：引擎是仓库根的纯 `.mjs`（无 `.d.mts`，`src/` 侧靠
+ * `@ts-expect-error` 引入），其 `KNOWN_*` 在 TS 看来是 `any`，派生不出字面量联合。
+ */
+declare const PROMPT_CONFIG_SPEC_ENUMS: {
+  readonly configKind: readonly ["ordered", "anchor"];
+  readonly role: readonly ["user"];
+  readonly position: readonly ["after-user", "before-all", "after-all"];
+  readonly dedupe: readonly ["session", "batch", "none"];
+  readonly promotion: readonly ["none", "main", "include-subagents"];
+  readonly audience: readonly ["main", "subagent"];
+  readonly subject: readonly ["toolArgs", "toolResult", "userMessage", "assistantText", "subagentInfo"];
+  readonly modelScope: readonly ["all", "pro", "flash"];
+  readonly mergeMode: readonly ["separate", "merged"];
+};
+/** 取上面某一条枚举的值联合。 */
+type SpecEnum<K extends keyof typeof PROMPT_CONFIG_SPEC_ENUMS> = (typeof PROMPT_CONFIG_SPEC_ENUMS[K])[number];
+interface PromptConfigSpec {
+  id: string;
+  name?: string;
+  enabled?: boolean;
+  strategy?: string;
+  layer?: string;
+  configKind?: SpecEnum<'configKind'>;
+  order?: number;
+  role?: SpecEnum<'role'>;
+  group?: string;
+  exclusive?: boolean;
+  position?: SpecEnum<'position'>;
+  dedupe?: SpecEnum<'dedupe'>;
+  promotion?: SpecEnum<'promotion'>;
+  /** 消息受众：缺省（省略/null）= 公用（主会话+子代理）；main=仅主会话；subagent=仅子代理。 */
+  audience?: SpecEnum<'audience'> | null;
+  /** 条件判定的匹配对象；缺省由层决定（engine/schema.mjs 的 LAYER_DEFAULT_SUBJECT）。 */
+  subject?: SpecEnum<'subject'>;
+  /** 条件判定的键集合；省略 = 无条件（旧行为）。 */
+  match?: PromptConfigMatch;
+  modelScope?: SpecEnum<'modelScope'>;
+  sourceKind?: string;
+  form?: string;
+  summary?: string;
+  identity?: {
+    field: 'plugin';
+    value: string;
+  };
+  text?: string;
+  /** 单条提示词配置的多段文本：注入为一条消息的多个 text 内容块。 */
+  texts?: string[];
+  /** 同位置多条提示词配置的插入方式：separate=先后插入独立消息（默认）；merged=拼接为一条消息。 */
+  mergeMode?: SpecEnum<'mergeMode'>;
+  templateFile?: string;
+  fill?: string;
+  variables?: Record<string, string>;
+  params?: Record<string, unknown>;
+}
+/**
+ * 提示词配置 / 自定义工具 ID 的安全文件名段校验：ID 直接拼进生成文件名
+ * （prompt-configs/<n>-<id>.yml / custom-tools/<n>-<id>.yml），含路径分隔符
+ * 或 Windows 非法字符会越出生成目录或写盘失败，保存/物化前 fail loud 拒绝。
+ * 允许 [a-zA-Z0-9._-] 与常见中文/多字节字符（ST 导入 id 含中文），
+ * 仅拒绝分隔符、控制字符、点目录与 Windows 保留字符。
+ */
+declare function assertSafeConfigId(id: string): void;
+/** 生成文件名统一 4 位零填充前缀（0000-…），超过 10 条后字典序仍稳定。 */
+declare function configFileName(index: number, id: string): string;
+interface PromptConfigFile {
+  /** 模块文件夹内文件名（数字前缀决定引擎执行顺序）。 */
+  file: string;
+  /** yml 文件内容。 */
+  content: string;
+}
+/**
+ * 条件判定的键集合：与 `engine/anchor-match.mjs` 的匹配语义同构。
+ * 键按字面文本匹配（正则元字符会被转义）；要写正则须用 `/pattern/flags` 形态或 `useRegex: true`。
+ */
+interface PromptConfigMatch {
+  keys?: string[];
+  secondaryKeys?: string[];
+  logic?: 'any' | 'all' | 'not' | 'notAny';
+  caseSensitive?: boolean;
+  wholeWords?: boolean;
+  useRegex?: boolean;
+}
+//#endregion
+//#region src/shared/engine-params.d.ts
+/**
+ * 引擎行为参数契约（单一来源）。
+ *
+ * 这是「可配置引擎参数」的类型唯一权威：所有消费引擎参数的接口（RuntimeOptions /
+ * WritePresetOptions）从这里派生，不再各自手写一遍字段
+ * （此前多处重复声明导致同字段签名漂移，如 maxDepth / modelTemperature）。
+ *
+ * 分层约定：
+ *  - 本文件 = 引擎参数「契约层」（类型）：参数桥/模板/UI 可配置的键与类型；
+ *  - ENGINE_PARAM_DEFINITIONS 统一键、校验、卡片、默认草稿与组合映射；
+ *    Record<keyof EngineParams, ...> 强制完整覆盖，ENGINE_PARAM_KEYS 与 PARAM_KEYS 从其派生；
+ *  - layerSettings ↔ 运行时平铺键：loadPresetSpec 展平 / savePresetParams 按层写入。
+ *
+ * 全部字段可选：缺省 = 模板 preset.yml layerSettings / 引擎默认，符合「一切皆可自定义」。
+ */
+interface EngineParams {
+  /** 首轮近距离锚定：首条真实用户消息后追加一次性首句锚点。 */
+  firstTurnAnchor?: boolean;
+  /** 自定义锚点文本；firstTurnCustom=true 时固定使用。 */
+  firstTurnText?: string;
+  /** 自定义锚点开关：true 固定使用 firstTurnText；false 按任务自动选择。 */
+  firstTurnCustom?: boolean;
+  /** 自定义每轮引导文本；guideCustom=true 时固定使用。 */
+  guideText?: string;
+  /** 自定义每轮引导开关：true 固定使用 guideText；false 按任务自动选择。 */
+  guideCustom?: boolean;
+  /** 每轮引导独立开关；缺省关闭。 */
+  guideEnabled?: boolean;
+  /** 锚定确认后注入 preset.md；关闭时仍保留工具引导，但不生成 prompt-injector 提示词配置内容。 */
+  injectPrompt?: boolean;
+  /** 模型路由 provider；与模型名同时非空时给 subagent/subagent_fork 行加 agentOptions（主对话直派子代理与委派子代理通用）。 */
+  modelProvider?: string;
+  /** 模型名；与 provider 同时非空时生效。 */
+  modelName?: string;
+  /** 子代理固定模型路由 provider（agentOptions 注入 tool-subagent）。 */
+  subagentModelProvider?: string;
+  /** 子代理固定模型名。 */
+  subagentModelName?: string;
+  /** 主对话思维程度（agent-request patch reasoningEffort；''=不设置，官方档位 off/low/high/max）。 */
+  modelReasoningEffort?: string;
+  /** 主对话采样温度（agent-request patch temperature；''=不设置）。 */
+  modelTemperature?: string;
+  /** 主对话输出上限（agent-request patch maxTokens；''=不设置）。 */
+  modelMaxTokens?: string;
+  /** 子代理思维程度（agent-request patch，audience=subagent；''=不设置）。 */
+  subagentReasoningEffort?: string;
+  /** 子代理采样温度（agent-request patch，audience=subagent；''=不设置）。 */
+  subagentTemperature?: string;
+  /** 子代理输出上限（agent-request patch，audience=subagent；''=不设置）。 */
+  subagentMaxTokens?: string;
+  /** 委派递归深度上限（0 禁止委派 / provider-managed / 正整数；数字字符串同义）。 */
+  maxDepth?: number | 'provider-managed' | string;
+  /** custom-fallback 锚定词（prompt-injector params.firstTurnWord）。 */
+  firstTurnWord?: string;
+  /**
+   * 锚定/引导内容键：writePreset 把它们映射进 near-anchor / router-guide 的
+   * promptConfig params（由对应策略消费）。此前只在 PARAM_KEYS 旁路白名单里，
+   * 保存链接受键名却被值校验拒绝，形成「白名单通过、写盘前报未知键」的断层。
+   */
+  /** 构建任务正则（锚定三档分类的 build 档；编译规则与 engine/classify-task.mjs 同源，flags=i）。 */
+  buildPattern?: string;
+  /** 复杂任务正则（锚定 complex 档与引导深度判定共用）。 */
+  complexPattern?: string;
+  /** 构建档锚句。 */
+  firstTurnBuild?: string;
+  /** 排查档锚句。 */
+  firstTurnInspect?: string;
+  /** 深度档锚句。 */
+  firstTurnDeep?: string;
+  /** 引导-简短档正文。 */
+  guideWeak?: string;
+  /** 引导-深度档正文。 */
+  guideDeep?: string;
+  /** 晋升后 agent-instructions 全文 → 一次性 hint。 */
+  instructionHint?: boolean;
+  /** str-replace-editor 最大输出字符数（参数桥默认官方值 16000；由引擎能力卡编辑）。 */
+  strReplaceEditorMaxOutputChars?: number;
+  /** tool-git-bash 行的能力开关（B2 T3 补；此前该行只能靠「在不在组合里」决定启停）。 */
+  toolGitBashEnabled?: boolean;
+  /** 自定义模型工具在执行前需用户批准的执行器种类。 */
+  customToolRequireApproval?: string[] | string;
+}
+type EngineParamKey = keyof EngineParams;
+/**
+ * writePreset.runtimeOf 实际透传进运行时 params 的引擎参数子集。
+ * RuntimeOptions（装配态）与 WritePresetOptions（写入态）都从这里派生，
+ * 防止「加参数只改一处、writePreset 忘透传」的静默漂移（如 stageAdvanceDescription 历史事故）。
+ */
+type PresetWriterParams = Partial<EngineParams>;
+/**
+ * 数值型引擎参数保存前校验（与 write-preset.modelRequestConfigs 消费规则同源）。
+ * 保存层响亮失败（400 逐字段错误），渲染层保持宽容（never-brick）：
+ *   - 布尔键：必须是 boolean；
+ *   - 数值键（temperature / maxTokens / 字符数）：'' = 合法（删键回落默认）；
+ *     非空必须可解析为数字并满足各自约束（有限数 / 正整数）；
+ *   - 字符串键：必须是 string（'' = 删键回落默认）；
+ *   - 列表键（执行器种类等）：必须是 string 或 string[]；
+ *   - maxDepth：'' / 'provider-managed' / 非负安全整数及其数字字符串。
+ * 未知键（旧内容别名等不兼容键）在保存期响亮失败，不做运行时自动兼容。
+ * 注意：内容占位变量（variables）的空字符串是合理设计（世界书动态引用），
+ * 本函数只校验引擎行为参数，绝不碰 variables 通道。
+ */
+interface EngineParamValueError {
+  key: string;
+  message: string;
+}
+declare const ENGINE_PARAM_KEYS: EngineParamKey[];
+/** writePreset.runtimeOf 实际透传键：全部引擎参数可直接进入 writer。 */
+declare const WRITER_PARAM_KEYS: (keyof EngineParams)[];
+/**
+ * 校验参数键值（键集合合法性由调用方白名单先行校验，本函数同样拒绝未知键）。
+ * 返回逐字段错误；空数组 = 通过。类型收窄：布尔/字符串/数值/列表各按 canonical
+ * 规则校验；'' 是合法删键值，其余非法类型与越界值在保存层响亮失败。
+ */
+declare function validateEngineParamValues(overrides: Record<string, unknown>): EngineParamValueError[];
+//#endregion
 //#region src/shared/param-keys.d.ts
 declare const PARAM_KEYS: ReadonlySet<string>;
 //#endregion
 //#region src/config.d.ts
 interface Config {
-  /** 是否用 AGENTS.md 内容替换本地 instruction-hint 的默认提示文本（默认关闭）。 */
-  injectAgentsPrompt: boolean;
-  /** 是否写 ~/.dsh/AGENTS.md（默认 true）。 */
-  writeAgents: boolean;
-  /** 是否生成锚定注入 preset（默认 true）。 */
-  writePreset: boolean;
-  /** 预设模板名（默认 anchored；其他模板时 anchored 专属 UI 可隐藏）。 */
-  presetTemplate: string;
-  /** 以技能目录名为键的逐技能开关，缺省视为 true。 */
-  skillSwitches: Record<string, boolean>;
-  /** 技能展示顺序（目录名数组）：排前面的技能 rank 更小，模型最先看到。 */
-  skillOrder: string[];
-  /** 用户自定义技能目录列表（按添加顺序，首个目录优先级最高）；空 = 自动使用当前 profile 下的 skills/ 副本。 */
-  skillsDirs: string[];
-  /** 旧版单值技能目录（仅读取迁移用，新版本统一写回 skillsDirs）。 */
-  skillsDir?: string;
-  /** 技能候选排序基数，技能目录内按下标递增。 */
-  skillRankBase: number;
-  /** 常驻规则文件目标路径。 */
-  residentAgentsPath: string;
-  /** 生成的 agent preset 目录。 */
-  presetDir: string;
+  /** 是否生成注入预设（默认 true）。 */
+  writePreset: Volatile<boolean>;
+  /** 预设模板名（默认 pt-standard：与宿主内置 standard 同名的用户目录会被遮蔽）。 */
+  presetTemplate: Volatile<string>;
   /** 生成 preset 的显示顺序。 */
-  presetOrder: number;
+  presetOrder: Volatile<number>;
   /** preset.md 缺失或不可读时使用的文本。 */
-  fallbackText: string;
-}
-declare const Config: z<Config>;
-interface SkillEntry {
-  /** 来源技能目录的绝对路径（多目录合并后用于修复定位与归属展示）。 */
-  dir: string;
-  folder: string;
-  file: string;
-  name: string;
-  description: string;
-  whenToUse?: string;
-  metadata?: Record<string, unknown>;
-  body: string;
-  /** 是否通过官方 dsh-skill 候选校验；false 时只进管理界面，不注册给模型。 */
-  valid: boolean;
-  /** invalid 条目的原因（可为空）。 */
-  issue?: string;
-  /** 通过符号链接/junction 挂入的目录（删除类操作需谨慎）。 */
-  linked?: boolean;
-  /** 官方调用策略：disable-model-invocation: true 时模型不可调用。 */
-  modelInvocable: boolean;
-  /** 官方调用策略：user-invocable: false 时用户不可调用。 */
-  userInvocable: boolean;
-}
-interface SkillCatalogEntry {
-  folder: string;
-  name: string;
-  description: string;
-  /** 是否通过官方 dsh-skill 候选校验；false 时 UI 灰显并展示 issue。 */
-  valid: boolean;
-  /** 来源技能目录绝对路径（多目录管理：修复定位 / 归属展示 / 目录计数）。 */
-  dir?: string;
-  /** 同名标记：多个目录存在相同 folder 时全部保留，UI 标注同名。 */
-  duplicate?: boolean;
-  /** invalid 条目的原因。 */
-  issue?: string;
-  /** 通过符号链接/junction 挂入的目录（删除类操作需谨慎）。 */
-  linked?: boolean;
-  modelInvocable: boolean;
-  userInvocable: boolean;
+  fallbackText: Volatile<string>;
 }
+declare const Config: z<Schemastery.ObjectS<NoInfer<{
+  writePreset: z<boolean, boolean, "volatile-defined">;
+  presetTemplate: z<string, string, "volatile-defined">;
+  presetOrder: z<number, number, "volatile-defined">;
+  fallbackText: z<string, string, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+  writePreset: z<boolean, boolean, "volatile-defined">;
+  presetTemplate: z<string, string, "volatile-defined">;
+  presetOrder: z<number, number, "volatile-defined">;
+  fallbackText: z<string, string, "volatile-defined">;
+}>>, "plain">;
 interface PromptSettings {
-  injectAgentsPrompt: boolean;
   /** 运行时检测：是否检测到任何模型服务商（不写入 settings）。 */
   modelsAvailable: boolean;
-  skillSwitches: Record<string, boolean>;
-  /** 技能展示顺序（目录名数组）。 */
-  skillOrder: string[];
-  skillCatalog: SkillCatalogEntry[];
-  /** 用户自定义技能目录列表（按添加顺序）；空 = 自动使用 profile skills 副本。 */
-  skillsDirs: string[];
-  /** 当前实际生效的技能目录列表（空配置 = [profile 副本路径]）。 */
-  activeSkillsDirs: string[];
-  /** 生效目录存在性（path → 目录是否存在，供 UI 状态徽章）。 */
-  skillsDirExists: Record<string, boolean>;
-  /** 技能候选排序基数。 */
-  skillRankBase: number;
-  /** 常驻规则文件目标路径。 */
-  residentAgentsPath: string;
-  /** 生成的 agent preset 目录。 */
-  presetDir: string;
   /** 生成 preset 的显示顺序。 */
   presetOrder: number;
   /** preset.md 缺失或不可读时使用的文本。 */
   fallbackText: string;
-  writeAgents: boolean;
   writePreset: boolean;
   presetTemplate: string;
 }
@@ -110,189 +257,314 @@ declare const PromptSettingsSchema: z<PromptSettings>;
  * 此处只保留 writePreset 专属字段——加引擎参数只需改一处契约，漏透传变成编译错误。
  */
 interface WritePresetOptions extends PresetWriterParams {
-  /** 是否注入 agents.md 内容到 instruction-hint（false 时 instruction-hint 走引擎默认提示/动态探测）。 */
-  injectAgentsPrompt?: boolean;
-  /** 写入 agents-instruction.txt 供 instruction-hint 配置读取;不传则使用本地默认 hint。 */
+  /** AGENTS.md 内容资产（写生成目录 agents.md）：常驻层写盘的唯一来源，不再注入提示词。 */
   agentsInstructionText?: string;
   presetDir: string;
   presetOrder: number;
   /** settings 层用户自定义提示词配置(优先级最高)。 */
   promptConfigs: PromptConfigSpec[];
-  /** 预设模板名(preset/<name>);默认 anchored(兼容期)。 */
+  /** 当前预设目录名；默认 pt-standard。 */
   presetTemplate?: string;
-  /** 输出目录/预设 id 覆盖（旧容器 id 兼容别名，如 prompt-tool）；缺省 = presetTemplate 同名输出。 */
+  /** 输出目录/预设 id 覆盖；缺省 = presetTemplate 同名输出。 */
   outputId?: string;
-  /** 兼容别名标记：输出目录是源预设的镜像（preset.yml name 加后缀，UI 可识别展示）。 */
-  aliasOf?: boolean;
+  /** 隔离的定义/资源来源；与最终 outputId 分离，不回退同名已安装预设。 */
+  sourceDir?: string;
+  /** 只生成并返回暂存目录；调用方负责安装或清理，不更新共享引擎及目标目录。 */
+  materializeOnly?: boolean;
   /** 目录加载失败等非致命告警回调。 */
   warn?: (message: string) => void;
 }
 /** 把任意单一参数预设模板物化到生成目录;全部失败 fail loud。 */
-declare function writePreset(prompt: string, options: WritePresetOptions): void;
+declare function writePreset(prompt: string, options: WritePresetOptions): string;
 //#endregion
-//#region src/host/manifest.d.ts
-interface PresetSpec {
-  id: string;
-  name: string;
-  /** 预设说明（官方用户预设格式元数据；列表展示用，可选）。 */
-  description?: string;
-  version: string;
-  engineCompat: string;
-  meta?: Record<string, unknown>;
-  content?: {
-    presetText?: string;
-    agentsText?: string;
-  };
-  /** 模块清单(参数文件决定组合内容):按序装配 engine/compositions/library/<name>.yml。 */
-  modules?: string[];
-  /** 兼容字段:内联组合文本或组合清单名。 */
-  composition?: string;
-  /** 扁平参数:全部直读(true/false、数字、字符串),on/off 作为兼容写法。 */
-  params?: Record<string, unknown>;
-  /** 顶层模型段（主对话，官方 agent-default-model 同构）：provider/name/reasoningEffort/temperature/maxTokens。 */
-  model?: Record<string, unknown>;
-  /** 顶层子代理模型段：provider/name/reasoningEffort/temperature/maxTokens。 */
-  subagentModel?: Record<string, unknown>;
-  /** 预设级模板变量（{{key}} 插值源；与引擎行为参数 params 分离，顶层 variables 段）。 */
-  variables?: Record<string, string>;
-  /** 自定义工具定义（tool-config-engine 渲染进 custom-tools/ 后运行时注册）。 */
-  customTools?: unknown[];
-  /** 模板变量插值开关（缺省 true = 启用；false = 停用，writePreset 不生成变量文件）。 */
-  variablesEnabled?: boolean;
-  /** 可选:模板自定义提示词配置覆盖(纯数据,不使用模板语法)。 */
-  promptConfigs?: unknown[];
-  /** 可选:引擎组合模块行参数直写(行级 map config 浅合并;参数桥未覆盖的键生效,参数桥优先)。 */
-  moduleConfigs?: Record<string, Record<string, unknown>>;
-  /** 世界书（独立存储段，不进 promptConfigs）：injectMode + 条目。 */
-  worldBook?: {
-    injectMode?: 'full' | 'keyword';
-    entries: Array<Record<string, unknown>>;
-  };
-  legacyCleanup?: string[];
-  upstream?: Record<string, unknown>;
+//#region src/host/agents-cards.d.ts
+/** 文件身份（fileId + 路径 + 展示路径）：生成卡与读取快照共用的最小形状。 */
+interface AgentsFileIdentity {
+  /** 稳定文件 id（规范化真实路径哈希；bridge 写白名单与卡 id 共用）。 */
+  fileId: string;
+  /** 探测到的路径（普通文件；符号链接在 realPath 解析）。 */
+  path: string;
+  displayPath: string;
+  scope: 'global' | 'project';
 }
-/** 加载某个预设模板的单一参数文件 preset/<name>/preset.yml。 */
-declare function loadPresetSpec(dir: string): PresetSpec;
+interface AgentsFileCard extends AgentsFileIdentity {
+  /** 解析后的真实路径：同一实际文件去重与身份校验用。 */
+  realPath: string;
+}
+declare function agentsFileId(path: string): string;
 /**
- * 顶层模型段 ↔ 扁平参数键双向映射（单一来源）。
- * loadPresetSpec 展平（段 → 扁平键）与 savePresetParams 迁移（扁平键 → 段）
- * 共用本常量，杜绝两处字面量漂移。段结构 = 官方 agent-default-model 同构。
+ * 探测当前可见的 AGENTS 指令文件：用户级 `$DSH_HOME/AGENTS.md` + cwd→项目根链的全部候选。
+ * 只返回已存在的文件——探测不到就不生成卡。
  */
-declare const MODEL_SEGMENT_MAP: Record<string, [string, string]>;
-/** 预设根：官方 USER_PRESET_DIR（~/.dsh/.agent-presets），导入/新建/种子化的预设都放这里。 */
-declare function userPresetsDir(): string;
+declare function detectAgentsFiles(options?: {
+  cwd?: string;
+  home?: string;
+  projects?: boolean;
+}): AgentsFileCard[];
 /**
- * 解析预设模板目录：用户自定义优先，包内模板回退。
- * 目录名与 preset.yml id 双匹配（UI 切换值=目录名；旧 settings 存量值=id 也兼容）。
+ * 探测结果 → pre-step 提示卡（每个文件一张，不落 preset.yml）。
+ * 插入点对齐官方 `@deepseek-ai/dsh-agent-instructions`：pre-step 层、紧随真实用户消息；
+ * 注入内容 = 该文件当前正文（`fill=instruction-file` 运行时读取，params.file 精确到单个文件）。
  */
-declare function resolvePresetDir(template: string): string;
-/** 可用预设清单：全部来自预设根 ~/.dsh/.agent-presets（官方预设目录，含 agent.cordis.yml
- *  即被宿主挂载；点前缀目录与无 preset.yml 的官方目录跳过，不占本插件列表）。 */
-declare function listPresets(): Array<{
-  id: string;
-  name: string;
-  user: boolean;
-  description?: string;
-  meta?: Record<string, unknown>;
-}>;
-/** 插件目录模板清单（「新建」选择器与首次种子化数据源；不直接出现在预设列表）。 */
-declare function listBuiltinTemplates(): Array<{
-  id: string;
-  name: string;
-}>;
-interface PromptToolState {
-  seeded?: boolean;
-  paramsMigrated?: boolean;
-  /** 旧容器 id 兼容快照已处理；删除后不再自动复活。 */
-  legacyAliasHandled?: boolean;
-}
-/** 读插件状态；文件缺失/损坏返回空对象（按未标记处理，触发首次动作）。 */
-declare function readPluginState(): PromptToolState;
-/** 原子写插件状态（tmp+rename）。 */
-declare function writePluginState(state: PromptToolState): void;
-/** 首次启动种子化：把插件目录全部内置模板复制到预设根（state.seeded 后不再自动补）。
- *  用户删除的预设不会自动复活；升级新增的模板用「新建」按需复制。
- *  兼容旧版预设根内 .pt-seeded 标记：存在即视为已种子化，并迁入状态文件后删除。 */
-declare function ensurePresetSeed(): {
-  created: string[];
-};
-/** 从插件目录复制内置预设到预设根（新建/还原）。
- *  autoSuffix=true（自定义预设入口）时同名自动递增（custom → custom-2 → …）；否则同名拒绝。 */
-declare function cloneBuiltinPreset(id: string, autoSuffix?: boolean): {
-  ok: true;
-  id: string;
-} | {
-  ok: false;
-  message: string;
-};
+declare function agentsFileCardSpecs(files?: readonly AgentsFileIdentity[]): PromptConfigSpec[];
 /**
- * 保存预设参数：写激活预设目录 preset.yml 的 params（merge）/ promptConfigs（整体替换）。
- * parseDocument 保留注释与未知键（preset.yml 模板含大量注释）；空值键删除（'' / []，
- * 回落模板/引擎默认；0 与 false 照常写入--语义与函数内注释、docs §3 一致）。写入后删除 prompt-tool.overrides.yml（旧参数覆盖
- * 通道残留——参数已并入 preset.yml，避免旧值覆盖新值）。
+ * 单次读取形成一致快照：正文、revision、身份、读取状态来自同一次读取。
+ * 只支持可正确解码的 UTF-8；有 BOM 的文件保留 BOM 字符，不让无关保存悄悄改写字节。
  */
-declare function savePresetParams(presetRoot: string, templateName: string, params: Record<string, unknown> | undefined, promptConfigs: unknown[] | undefined, variables?: Record<string, string>, variablesEnabled?: boolean): void;
-/** 删除预设目录（预设根/<id>；含同名导入的 .bak-* 备份目录）。
- *  仅作用于预设根（官方 USER_PRESET_DIR），包内置模板天然不受影响；路径越界与非法 id 拒绝。
- *  删除后宿主 agent-presets 目录列表自然不再出现该预设（官方 roster 即目录列表）。 */
-declare function removeUserPreset(id: string, presetRoot?: string): {
+declare function readAgentsFileSnapshot(file: AgentsFileCard): InstructionFileSnapshot;
+/** 探测 + 读取：同一套探测规则下每个文件一份快照。 */
+declare function detectAgentsFileSnapshots(options?: {
+  cwd?: string;
+  home?: string;
+  projects?: boolean;
+}): InstructionFileSnapshot[];
+type AgentsFileWriteOutcome = {
   ok: true;
+  fileId: string;
+  revision: string;
 } | {
   ok: false;
+  status: 400 | 404 | 409 | 413;
+  code: string;
   message: string;
 };
-/** 预设 params(默认参数)与运行时 settings 合并;settings 值优先。 */
-declare function resolvePresetParams(spec: PresetSpec, runtime: Record<string, unknown>): Record<string, unknown>;
+/** 原子写指令文件（tmp + rename）；调用方必须先用 detectAgentsFiles() 校验路径白名单。 */
+declare function writeAgentsFile(path: string, content: string): void;
 /**
- * 参数桥：params 扁平键 → 引擎模块行 config 对象（取代旧 __TOKEN__ 文本渲染）。
- *
- * 原则：
- *  - 未声明的键不合并（composition 行默认 / 引擎默认生效），与旧"空值删行"语义等价；
- *  - 值类型直达（布尔/数字/数组不再字符串化再解析）；
- *  - 合并优先级：参数桥（UI/基础层）> moduleConfigs（模板/ST 行级直写）> 行默认。
- * 模型路由/委派参数统一扁平键（modelProvider/subagentModelProvider/toolFilterAllow/maxDepth 等），
- * 与官方 AgentOptions{provider,model} / toolFilter{allow,deny} / maxDepth 对齐。
+ * 带版本校验的单文件写：
+ * 1. 写前在同一段内重读文件，expectedRevision 不一致 = 409（不做「猜到用户意图」的重试）；
+ * 2. 目标消失 = 404，不自动重建用户文件；
+ * 3. 正文超限 = 413，不截断保存；
+ * 4. 替换前复查目标身份（真实路径未变），失败保留原文件并清理临时文件。
+ */
+declare function writeAgentsFileChecked(options: {
+  file: AgentsFileCard;
+  content: string;
+  expectedRevision: string | null;
+}): Promise<AgentsFileWriteOutcome>;
+//#endregion
+//#region src/runtime/pre-step-coordinator.d.ts
+/** 协调服务名：引擎行通过 ctx.get 解析本服务决定走管理路径还是独立路径。 */
+declare const PRE_STEP_COORDINATOR_SERVICE = "promptToolPreStep";
+/** 服务契约版本：引擎与协调器不同步时按「不认识就不接管」处理。 */
+declare const PRE_STEP_COORDINATOR_VERSION = 1;
+/** 批执行算法消费的提示词配置（与 engine/schema.mjs 产出的形状同源）。 */
+interface PreStepPromptConfig {
+  id: string;
+  layer: string;
+  enabled?: boolean;
+  order: number;
+  position: string;
+  promotion: string;
+  audience: string | null;
+  modelScope: string;
+  role: string;
+  dedupe: string;
+  mergeMode: string;
+  sourceKind: string;
+  form?: string;
+  texts: string[];
+  params: Record<string, unknown>;
+  variables: Record<string, unknown>;
+  identity: {
+    field: 'plugin';
+    value: string;
+  };
+  resolve: (input: Record<string, unknown>) => unknown;
+}
+/** 一个预设 mount 注册进来的来源：提示词配置 + 装配事实（晋升/去重由协调器统一持有）。 */
+interface PreStepSource {
+  configs: readonly PreStepPromptConfig[];
+  officialInstructions?: boolean;
+}
+/**
+ * 文件来源每次 pre-step 编译出的最小候选。
+ * `available: false` 表示读取失败/超限/空内容：只在「该文件曾经注入过」时转成
+ * 一次性失效通知，不冒充空正文。
+ */
+interface PreStepFileContribution {
+  fileId: string;
+  displayPath: string;
+  revision: string;
+  text: string;
+  available: boolean;
+  reason?: string;
+  order: number;
+  position: string;
+  promotion: string;
+  audience: string | null;
+  modelScope: string;
+}
+interface PreStepCoordinatorOptions {
+  /** 每次 pre-step 现读指令文件；缺省实现走 host 探测 + 独立策略。测试可注入。 */
+  collectFiles?: (agent: unknown, session: unknown) => PreStepFileContribution[];
+  /** 策略文件位置覆盖（测试隔离用）。 */
+  policyFile?: string;
+  /** 用户级指令文件根（DSH_HOME）覆盖（测试隔离用）。 */
+  home?: string;
+}
+interface PreStepCoordinatorService {
+  readonly version: number;
+  /**
+   * 把 preset mount 的 pre-step 配置登记进协调器。
+   * 同一 scope 内同一个 `sourceId` 再次登记时后来者接管：先撤销旧登记再插入新登记。
+   * 宿主重挂同一个 preset（或其引擎行的旧 fiber 尚未释放）时这是正常路径，不是配置错误，
+   * 因此不抛错——抛错会让整行未激活，进而让 preset 挂载整体失败（无法切换预设）。
+   * @param sourceCtx 注册 ctx：同时决定来源作用域与释放时机（挂在这个 fiber 上）。
+   * @param sourceId 来源 id（同一 scope 内唯一：同名登记以最新一次为准）。
+   * @returns 幂等的撤销函数；登记已被后来者顶替时调用它是空操作。
+   */
+  registerPreset(sourceCtx: Context, sourceId: string, source: PreStepSource): () => void;
+  /** 该会话最近一次 pre-step 观察到的负责人事实；未知返回 undefined。 */
+  officialOwnerOf(sessionId: string): boolean | undefined;
+}
+/**
+ * 安装协调器：发布 `promptToolPreStep` 服务并注册唯一的 pre-step 监听器。
+ * 普通监听器留在 prepend 门控内侧；来源监听器只登记后交出执行权。
+ * 即使服务迟到或重挂，下游的 pre-step 过滤（声明式触发器的 `pre-step-filter` 动作）
+ * 仍能在本监听器交出执行权之后过滤最终消息批。
+ */
+declare function installPreStepCoordinator(ctx: Context, options?: PreStepCoordinatorOptions): PreStepCoordinatorService;
+//#endregion
+//#region src/runtime/models.d.ts
+/**
+ * 官方子代理 seam 的类型锚点：本插件只读 `list()` / `getProvider()` 并显式传参，
+ * 不替换 {@link SubagentRuntime.start} 或 `startContinuable`；这里保留类型引用是为了
+ * 让「不碰 registry 方法」这条边界在类型层随 rc.2 契约一起编译校验。
  */
-declare function buildModuleConfigsFromParams(params: Record<string, unknown>): Record<string, Record<string, unknown>>;
+type PluginSubagentSeam = Pick<SubagentRuntime, 'list' | 'getProvider'>;
+/** 模型服务商检测结果（含诊断信息，供 Web/TUI 展示）。 */
+interface ModelDetection {
+  /** 是否检测到任何已注册/可配置的服务商路由。 */
+  available: boolean;
+  /** 已检测到（live 注册）的模型服务商 id——状态提示用。 */
+  providers: string[];
+  error?: string;
+}
+/** 检测模型服务商：只统计 live 注册路由（状态提示与下拉共用同一来源）。 */
+declare function detectModels(ctx: Context): ModelDetection;
 /**
- * 加载预设声明的组合:
- *   1. `modules:` 清单 → 引擎模块库按序装配(最终形态);
- *   2. 兼容 `composition:` 内联文本或组合清单名。
+ * 目录失效：provider 注册/移除（官方 `llm/adapters-updated`）、服务重挂或显式刷新时
+ * 调用。代次前进让已在飞的旧查询回来后不再写缓存（M-11：变更必须让相关缓存失效）。
+ * 只清目录，不碰 provider 单点失败的既有语义。
  */
+declare function invalidateModelCatalog(ctx: Context): void;
+/** 同步读模型目录缓存（命中返回，未命中/过期返回空）：/describe 不触发查询。 */
+declare function peekModelCatalog(ctx: Context): Record<string, string[]>;
 /**
- * 行级 config 合并:仅支持 map 型 config 浅合并;
- * 数组型 config(如 delegation 组)按子行 id 嵌套合并;未声明模块原样保留。
- * 未声明 configs 时返回原文(零开销);parseDocument 往返保留注释。
- * 本函数是参数桥产物落位组合行的唯一机制(含 delegation 组子行嵌套),不是预设覆盖通道。
+ * 查询各已注册服务商公布的模型 id（对齐官方 web 选择器 buildModelCatalog：只遍历
+ * listProviders() live 路由，单点失败/超时不拖垮整体；仅作展示，不构成路由白名单）。
+ * 并行查询 + 10min 缓存 + 单点超时；同 Context 的并发刷新合并为一次查询，
+ * 失败只影响该次刷新（不写空缓存），旧代次结果不回写新数据。
  */
-declare function applyModuleConfigs(raw: string, configs: Record<string, Record<string, unknown>> | undefined): string;
+declare function listAdvertisedModels(ctx: Context): Promise<Record<string, string[]>>;
 /**
- * 预设组合渲染完整链路:模块装配 → 参数桥(moduleConfigs + params)行级合并。
- * 合并优先级:参数桥(params/UI 基础层) > moduleConfigs(模板/ST 行级直写) > 行默认。
- * moduleConfigs 仅补充参数桥未覆盖的行级 config(如 ST 导入的 tool-web.fetch),
- * 不再锁定覆盖 UI 可管理参数(旧作者锁定语义已移除)。
+ * 本插件子代理入口的显式模型路由（subagentModelProvider + subagentModelName 同时非空时生效）。
+ *
+ * 只产出要传给 {@link SubagentRuntime.start} 的 `agentOptions`，由调用方显式传入；
+ * 不修改 registry 上的 `start` / `startContinuable` 方法，也不在根 scope 强加默认值——
+ * 官方 API 的替换会让第三方直派调用也带上本插件的模型，超出插件授权范围。
  */
-declare function renderComposition(spec: PresetSpec, runtime: Record<string, unknown>, templateDir?: string): string;
+declare function resolveSubagentStartOptions(isEnabled: () => boolean, provider: () => string, model: () => string, getReasoningEffort?: () => string): AgentOptions | undefined;
+//#endregion
+//#region src/host/skills-actions.d.ts
+type SkillActionResult = {
+  ok: true;
+  id: string;
+  path: string;
+} | {
+  ok: false;
+  message: string;
+};
 //#endregion
-//#region src/host/sillytavern.d.ts
+//#region src/host/skills-policy.d.ts
+type SkillPolicyRead = {
+  ok: true;
+  invocation: SkillInvocation;
+  frontmatter?: string;
+  body?: string;
+} | {
+  ok: false;
+  message: string;
+};
+type SkillPolicyWrite = {
+  ok: true;
+  changed: boolean;
+  invocation: SkillInvocation;
+} | {
+  ok: false;
+  message: string;
+};
+/** 读取技能文件当前的调用策略（缺省即可调用）。 */
+declare function readSkillInvocation(file: string): SkillPolicyRead;
+/** 把技能文件的调用策略写到目标范围；返回是否发生写入。 */
+declare function setSkillInvocation(file: string, change: SkillPolicyChange | SkillPolicyScope): SkillPolicyWrite;
+//#endregion
+//#region src/host/skills-content.d.ts
+type SkillContentResult = ({
+  ok: true;
+  changed?: boolean;
+} & SkillContentSnapshot) | {
+  ok: false;
+  message: string;
+};
+//#endregion
+//#region src/host/skills-config.d.ts
+/** 与官方 `SKILL_NAME` 同规则；技能目录名、引用校验与调用策略写入共用。 */
+declare const SKILL_NAME_PATTERN: RegExp;
+type SkillsStateRead = {
+  ok: true;
+  state: SkillsState;
+  exists: boolean;
+} | {
+  ok: false;
+  state: SkillsState;
+  message: string;
+};
+declare function skillsStatePath(dshHome?: string): string;
+declare function readSkillsState(file?: string): SkillsStateRead;
+/** 写状态：Document API 保留注释与未知字段；内容无变化时不落盘；提交前核对本次读取的原文，失败清理暂存文件。 */
+declare function writeSkillsState(patch: Partial<Pick<SkillsState, 'folders'>>, file?: string): SkillsStateRead;
+//#endregion
+//#region src/runtime/settings-bridge.d.ts
+interface SkillsBridgeState {
+  /** 用户技能根（技能实体的落点）。 */
+  skillsRoot: string;
+  /** 用户添加的技能文件夹（只引用，不复制）。 */
+  folders: string[];
+  /** 技能清单：按会话工作区扫描官方六类技能根，调用策略取自各技能文件的 frontmatter。 */
+  listSkills: (cwd?: string) => SkillCatalogEntry[];
+  snapshot?: (options: SkillViewOptions) => Promise<SkillsCatalogSnapshot>;
+  /** 单端写入只提交本端意图；路径必须命中当前来源白名单。 */
+  setSkillPolicy: (name: string, path: string, change: SkillPolicyChange, cwd?: string) => SkillPolicyWrite;
+  readSkillContent: (name: string, path: string, cwd?: string) => SkillContentResult;
+  writeSkillContent: (name: string, path: string, content: string, description: string, expectedRevision: string, cwd?: string) => SkillContentResult;
+  deleteSkill: (name: string, path: string, cwd?: string) => SkillActionResult;
+  /** 添加 / 移除引用的技能文件夹。 */
+  patchSkillFolders: (folders: string[]) => SkillsStateRead | Promise<SkillsStateRead>;
+}
 /**
- * 处理 SillyTavern 文本，ST 变量语义 → 本项目 params fallback 插值：
- *   {{setvar::k::v}}        → 收集 k=v 进 params（会话变量初始值 = fallback 基准），指令剥离；
- *   {{getvar::k}}           → 改写为 {{k}}（引擎按 params 插值，无值保留原样）；
- *   {{getvar::k::default}}  → 改写为 {{k}} 且 variables 缺 k 时写入 default（fallback 落顶层 variables）；
- *   {{trim}}/{{//注释}}/{{ERA:...}} → 剥离（格式化/注释/第三方运行时）；
- *   {{user}}/{{char}}       → 替换占位符。
+ * 两类卡合并：预设卡原样保留，文件卡换成本次工作区的文件快照。
+ * 生成目录里属于其他工作区的文件卡不再展示（写盘白名单也不含它们）；
+ * 当前工作区里没有对应生成卡的文件按默认文件卡补齐。
  */
-declare function processStText(text: string, cardName: string, variables: Record<string, string>): string;
-/** 合并多个转换结果为一个预设（角色卡 × 响应预设 → 单预设）。 */
-declare function mergeStPresets(specs: PresetSpec[]): PresetSpec;
-/** SillyTavern JSON 预设卡片 → 本项目 PresetSpec（导入端点直接消费）。 */
-declare function convertStToPreset(card: unknown, baseName: string): PresetSpec;
-/** ST 导入预设 id：必须是官方 agent-presets 可发现的目录名（PRESET_ID =
- *  /^[a-z0-9][a-z0-9-]*$/——含中文的目录会被宿主 discovery 静默跳过，会话
- *  resume 报 preset not found）。文件名 slug 化（去中文）；纯中文名退化为
- *  st-<文件名短哈希>（唯一且合法）；显示名 name 仍保留中文原名。 */
-declare function stPresetId(baseName: string): string;
+declare function mergeInstructionCards(presetCards: readonly unknown[], files: readonly InstructionFileSnapshot[]): unknown[];
+/** 自建 loopback settings bridge：替代 registerConfigurableProviders，避免模型设置区出现插件条目。 */
+declare function registerSettingsBridge(ctx: Context, ns: string, getModelsState: () => ModelDetection, getSkillsState: () => SkillsBridgeState, getEngineStrategyDir: () => string, afterSkillsChange?: () => void,
+/** 生成目录（presetDir）：读取实际生效的提示词配置（引擎加载源）。 */
+getPresetConfigsDir?: () => string,
+/** 内容导入完成回调：批量 scope 只触发一次重建（更新运行时文本并重建预设）。 */
+afterPresetImport?: (scopes: Array<'preset' | 'agents'>) => void,
+/** 参数覆盖写入后重建当前预设。 */
+afterOverridesChange?: () => void | Promise<void>,
+/** 预设已完整安装后的刷新回调；失败只返回 refreshWarning，不再物化或撤销安装。 */
+afterPresetPackageImport?: (id: string) => void | Promise<void>,
+/** 能力/recipe 原子创建后重建回调；抛错时调用方恢复 preset.yml。 */
+afterCapabilityChange?: () => void,
+/** 新建、复制或删除预设后刷新官方注册。 */
+afterPresetListChange?: () => void | Promise<void>): {
+  invalidateDescriptor: () => void;
+};
 //#endregion
 //#region src/host/worldbook.d.ts
 type WorldBookEntry = Record<string, unknown>;
@@ -337,40 +609,31 @@ declare function resolveProfileDir(ctx: Context): string | undefined;
  *  2. 不修改同级 profile，不主动退出进程。
  */
 declare function ensureWebSurface(ctx: Context, warn: (message: string) => void): void;
-//#endregion
-//#region src/profile-skills.d.ts
 /**
- * 返回本插件应使用的 skills 目录：
- * 优先本插件 profile（prompt-tool）下的 `skills/` 副本；无法确定 profile
- * 或复制失败时回退到 sourceDir（默认包内 `skills/`）。
+ * 把首次启动自愈挂到插件生命周期上：延迟到本轮装配结束后执行，
+ * 插件卸载会取消计时器，卸载后不再异步补写 profile。
  */
-declare function resolveProfileSkillsDir(ctx: Context, sourceDir: string, warn: (message: string) => void): string;
-//#endregion
-//#region src/host/migration.d.ts
-declare function migrateLegacyLayout(presetRoot: string, legacyUserPresets: string): boolean;
-/** 旧版 presetDir 配置值（容器根/旧用户目录）归一化为预设根；其余原样。 */
-declare function normalizePresetRootDir(presetDir: string, presetRoot: string, legacyContainer: string): string;
+declare function scheduleWebSurfaceRepair(ctx: Context, warn: (message: string) => void): void;
 //#endregion
-//#region src/runtime/models.d.ts
-/** 模型服务商检测结果（含诊断信息，供 Web/TUI 展示）。 */
-interface ModelDetection {
-  /** 是否检测到任何已注册/可配置的服务商路由。 */
-  available: boolean;
-  /** 已检测到（live 注册）的模型服务商 id——状态提示用。 */
-  providers: string[];
-  error?: string;
+//#region src/host/skills-import.d.ts
+interface SkillsImportFile {
+  path?: unknown;
+  content?: unknown;
 }
-/** 检测模型服务商：只统计 live 注册路由（状态提示与下拉共用同一来源）。 */
-declare function detectModels(ctx: Context): ModelDetection;
-/** 查询各已注册服务商公布的模型 id（对齐官方 web 选择器 buildModelCatalog：只遍历 listProviders() live 路由，单点失败/超时不拖垮整体；仅作展示，不构成路由白名单）。并行查询 + 10min 缓存 + 单点超时。 */
-declare function listAdvertisedModels(ctx: Context): Promise<Record<string, string[]>>;
-/**
- * 主对话默认模型控制：modelProvider + modelName 同时非空时，经官方
- * `agentDefaultModel.saveSelection` 写入新会话默认模型（对齐官方 web 切换模型的
- * 默认级持久化；只影响新创建的 Agent，不干预已有会话）。任一为空 = 不干预
- * （继承用户在宿主 web 的选择）；agent-default-model 服务未装配时静默跳过。
- */
-declare function installDefaultModelRoute(ctx: Context, isEnabled: () => boolean, provider: () => string, model: () => string, getReasoningEffort?: () => string): () => void;
+type SkillsImportResult = {
+  ok: true;
+  path: string;
+  count: number;
+  overwritten: number;
+  warning?: string;
+} | {
+  ok: false;
+  message: string;
+  code?: 'skills-overwrite-required';
+  conflicts?: string[];
+};
+/** 浏览器上传：base64 文件列表；单技能包（无顶层目录）按 frontmatter.name 归类。 */
+declare function importSkillsPackage(root: string, files: SkillsImportFile[], overwrite?: readonly string[]): SkillsImportResult;
 //#endregion
 //#region src/runtime/configs-validate.d.ts
 interface PromptConfigValidationError {
@@ -395,26 +658,9 @@ interface PromptConfigValidationResult {
  */
 declare function validatePromptConfigs(value: unknown, options?: {
   strategyDir?: string;
+  presetDir?: string;
 }): Promise<PromptConfigValidationResult>;
 //#endregion
-//#region src/runtime/settings-bridge.d.ts
-interface SkillsBridgeState {
-  activeSkillsDirs: string[];
-  skillCatalog: SkillCatalogEntry[];
-}
-/** 自建 loopback settings bridge：替代 registerConfigurableProviders，避免模型设置区出现插件条目。 */
-declare function registerSettingsBridge(ctx: Context, ns: string, getModelsState: () => ModelDetection, getSkillsState: () => SkillsBridgeState, getEngineStrategyDir: () => string, afterSkillFix?: () => void,
-/** 生成目录（presetDir）：读取实际生效的提示词配置（引擎加载源）。 */
-getPresetConfigsDir?: () => string,
-/** 内容导入完成回调：批量 scope 只触发一次重建（更新运行时文本并重建预设）。 */
-afterPresetImport?: (scopes: Array<'preset' | 'agents'>) => void,
-/** 参数覆盖写入回调（重建预设使参数生效）。 */
-afterOverridesChange?: () => void,
-/** 预设包导入完成回调（物化导入预设：组合/配置目录/共享引擎落盘，宿主 discovery 可见）。 */
-afterPresetPackageImport?: (id: string) => void): {
-  invalidateDescriptor: () => void;
-};
-//#endregion
 //#region src/runtime/character-tools.d.ts
 /** 工具执行所需的运行时宿主能力（index.ts 闭包提供）。 */
 interface CharacterToolHost {
@@ -425,7 +671,7 @@ interface CharacterToolHost {
   /** 应用/移除后重建生成目录（写 preset.yml 后使参数生效）。 */
   rebuild: () => void;
 }
-/** 注册角色卡库模型工具；返回 disposer（预设切换重挂用）。enabled=false 返回空操作。 */
+/** 注册角色卡库模型工具；返回 disposer，随 character-tools 预设模块生命周期清理。 */
 declare function registerCharacterTools(ctx: Context, host: CharacterToolHost): () => void;
 //#endregion
 //#region src/runtime/world-book-tools.d.ts
@@ -437,10 +683,33 @@ interface WorldBookToolHost {
   /** 写盘后重建生成目录。 */
   rebuild: () => void;
 }
-/** 注册世界书条目级模型工具；返回 disposer（预设切换重挂用）。enabled=false 返回空操作。 */
+/** 注册世界书条目级模型工具；返回 disposer，随 world-book-tools 预设模块生命周期清理。 */
 declare function registerWorldBookTools(ctx: Context, host: WorldBookToolHost): () => void;
 //#endregion
 //#region src/host/characters.d.ts
+/** meta 下记录「每张卡引入了哪些模块」的键；来源保留到模块不再被消费并完成回退。 */
+declare const CHARACTER_MODULES_KEY = "characterModules";
+/** 读取 preset.yml `meta.modules` 之外的模块来源记录；非法形状一律视为无记录（老卡与手改文件不报错）。 */
+declare function recordedCharacterModules(meta: unknown): Record<string, string[]>;
+/** 卡自身声明的模块（声明优先：ST 转换产物自带六件套声明，行为因此不变）。
+ *  只丢弃非字符串与空串；模块名合法性仍由 appendPresetModules 校验（非法名 fail loud）。 */
+declare function declaredCharacterModules(spec: PresetSpec): string[];
+/** 必需模块：`prompt-config-engine` 缺失会让 promptConfigs 静默失效，因此始终补齐；
+ *  卡内含 world-book 策略配置时另需 `world-book-tools`（与旧实现同判据）。 */
+declare function requiredCharacterModules(configs: readonly unknown[]): string[];
+/** 移除一张卡之后，某个模块是否仍被预设内容或其他卡需要（需要则不回退）。 */
+interface CharacterModuleContext {
+  /** 移除本卡前缀配置之后的提示词配置。 */
+  configs: readonly Record<string, unknown>[];
+  /** 移除本卡声明的 params 键之后的预设参数。 */
+  params: Record<string, unknown>;
+  /** 预设顶层是否仍有自定义工具。 */
+  customTools: boolean;
+  /** 移除本卡之后仍标记为已导入的角色卡 id。 */
+  importedCharacters: readonly string[];
+}
+/** 模块的消费者判据。未知模块保守保留：宁可留一个无消费者的模块，也不误删用户或引擎要用的装配。 */
+declare function characterModuleStillNeeded(module: string, context: CharacterModuleContext): boolean;
 /** 角色卡记忆变更后同步已导入预设的 chara-<id>-memory 注入条目
  *  （world_book note 写入卡记忆后调用；未导入当前预设的卡返回 synced=false）。 */
 declare function syncImportedCharacterMemory(presetRoot: string, templateName: string, cardId: string): {
@@ -456,18 +725,20 @@ declare function appendCharacterMemory(presetRoot: string, cardId: string, note:
 declare function appendMemoryFile(file: string, note: string, header?: string): void;
 /** 读角色卡本地记忆文本（无记忆返回空串）。 */
 declare function readCharacterMemory(presetRoot: string, cardId: string): string;
-/** 角色卡入库：PNG 原图（可选）+ 角色卡 JSON → 转换参数存 converted.yml。 */
-declare function importCharacterCard(presetRoot: string, files: Array<{
-  path: string;
-  content: string;
-}>): {
+type CharacterImportOptions = StConversionOptions & ImportChoices;
+type CharacterImportResult = {
   ok: true;
   id: string;
   name: string;
+  warning?: string;
 } | {
   ok: false;
   message: string;
 };
+/** 角色卡入库：PNG 原图（可选）+ 角色卡 JSON → 转换参数存 converted.yml。 */
+declare function importCharacterCard(presetRoot: string, files: AssetFile[], options?: CharacterImportOptions): CharacterImportResult;
+/** 原始文件流导入：识别 PNG 魔数后在 host 侧提取角色卡，避免客户端 base64 膨胀 JSON。 */
+declare function importCharacterCardFile(presetRoot: string, filePath: string, fileName?: string, options?: CharacterImportOptions): CharacterImportResult;
 interface CharacterCardListItem {
   id: string;
   name: string;
@@ -527,110 +798,80 @@ declare function loadPromptTemplates(): PromptConfigTemplate[];
 declare function loadToolTemplates(): ToolTemplate[];
 //#endregion
 //#region src/runtime/tui.d.ts
+type TuiSource = PromptSettings & {
+  skillCatalog: SkillCatalogEntry[];
+  activeSkillsDirs: string[];
+};
 /** 参数保存回调：写激活预设 preset.yml；失败必须抛给命令层渲染为错误。 */
 type SavePresetParam = (key: string, value: unknown) => void | Promise<void>;
+/** 技能启停回调：切换受管实体的根链接。 */
+type ToggleSkillState = (folder: string, enabled: boolean) => {
+  ok: boolean;
+  message?: string;
+};
 /** 通过 DSH 命令注册表暴露 /prompt-tool，Web 与 dsh-tui 都能执行。 */
-declare function registerTuiCommand(ctx: Context, ns: 'prompt-tool', getSource: () => PromptSettings, getModelsState: () => ModelDetection, getModelCatalog: () => Promise<Record<string, string[]>>, getPresetConfigsDir?: () => string, savePresetParam?: SavePresetParam): void;
+declare function registerTuiCommand(ctx: Context, ns: 'prompt-tool', getSource: () => TuiSource, getModelsState: () => ModelDetection, getModelCatalog: () => Promise<Record<string, string[]>>, getPresetConfigsDir?: () => string, savePresetParam?: SavePresetParam, toggleSkillState?: ToggleSkillState): void;
 //#endregion
-//#region src/runtime/skills-provider.d.ts
-/** 官方 dsh-skill 的 SkillName 契约：kebab-case。 */
-declare const SKILL_NAME_RE: RegExp;
-interface SkillFolder {
-  name: string;
-  /** 通过符号链接/junction 挂入的目录（删除类操作需谨慎）。 */
-  linked: boolean;
-}
-declare function listSkillFolders(skillsDir: string): SkillFolder[];
-/** 只有 valid=true 的条目才能进入 ctx.skills 注册表。 */
-declare function isValidSkill(entry: SkillEntry): boolean;
-/** 供 provider 使用的合法条目集合（坏条目逐条跳过，绝不拖垮整批列表）。 */
-declare function validSkills(entries: SkillEntry[]): SkillEntry[];
-/**
- * 读取技能目录树的全部条目（含坏条目与嵌套子技能）。
- *  - 递归语义：任意层级含 SKILL.md 的目录都是技能（folder = 相对路径，嵌套用 / 分隔）；
- *    不含 SKILL.md 的目录（含多层空文件夹）不产生条目，继续下探其子目录。
- *  - 链接（junction/symlink）目录作为技能叶子：含 SKILL.md 则注册，不递归进入（防环）。
- *  - frontmatter 无 name 时回退目录名；name（frontmatter 或目录名）必须 kebab-case 才 valid；
- *  - warn 仅用于日志，不再决定条目去留。
- */
-declare function readSkills(skillsDir: string, warn?: (message: string) => void): SkillEntry[];
-/** 多目录全量合并：条目全部保留（同名不跳过，UI 层再做 duplicate 标注）。 */
-declare function mergeSkillDirs(dirs: string[], read: (dir: string, warn?: (message: string) => void) => SkillEntry[], warn?: (message: string) => void): SkillEntry[];
-/**
- * 进程内技能扫描缓存：按目录 + 每个 SKILL.md 的 mtime/size 签名失效。
- * 同一目录在内容未变化时，list/get 可复用同一次扫描结果。
- */
-interface CachedSkillsReader {
-  read: (skillsDir: string, warn?: (message: string) => void) => SkillEntry[];
-  invalidate: (skillsDir?: string) => void;
+//#region src/host/skills-refresh.d.ts
+interface SkillsReloaderDeps {
+  stateFile: string;
+  currentSnapshot: () => string;
+  accept: (state: SkillsState, snapshot: string) => void;
+  warn: (message: string) => void;
+}
+declare function createSkillsReloader(deps: SkillsReloaderDeps): {
+  reload: () => void;
+};
+//#endregion
+//#region src/host/skills-runtime.d.ts
+interface SkillsRuntime {
+  readonly skillsRoot: string;
+  readonly folders: string[];
+  listSkills: (cwd?: string) => SkillCatalogEntry[];
+  snapshot: (options?: SkillViewOptions) => Promise<SkillsCatalogSnapshot>;
+  setPolicy: (name: string, path: string, change: SkillPolicyChange, cwd?: string) => SkillPolicyWrite;
+  readContent: (name: string, path: string, cwd?: string) => SkillContentResult;
+  writeContent: (name: string, path: string, content: string, description: string, expectedRevision: string, cwd?: string) => SkillContentResult;
+  deleteSkill: (name: string, path: string, cwd?: string) => SkillActionResult;
+  setFolders: (folders: string[]) => SkillsStateRead;
+  invalidate: () => void;
 }
-declare function createCachedSkillsReader(): CachedSkillsReader;
+declare function createSkillsRuntime(ctx: Context, options?: {
+  dshHome?: string;
+}): SkillsRuntime;
 //#endregion
-//#region src/runtime/skill-fix.d.ts
-interface SkillFixResult {
-  fixed: boolean;
-  /** 修复前目录名。 */
+//#region src/host/skills-scan.d.ts
+interface ScanRoot {
+  kind: SkillSourceKind;
+  path: string;
+}
+interface ScannedSkill {
+  id: string;
+  source: SkillSourceKind;
+  rank: number;
+  dir: string;
   folder: string;
-  /** 修复后目录名。 */
-  fixedFolder: string;
-  /** 修复后注册名（与目录一致）。 */
+  file: string;
   name: string;
-  /** 实际执行的动作描述（写文件/重命名/剥 BOM/补 name）。 */
-  actions: string[];
-  error?: string;
+  description: string;
+  whenToUse?: string;
+  metadata?: Record<string, unknown>;
+  body: string;
+  valid: boolean;
+  issue?: string;
+  modelInvocable: boolean;
+  userInvocable: boolean;
 }
-/** 任意字符串 → kebab-case；空结果回退 'skill'。 */
-declare function toKebabName(value: string): string;
-/**
- * 修复一个无效技能条目。
- * @param skillsDir - activeSkillsDir（绝对路径）。
- * @param folder - 要修复的目录名（不允许含路径分隔符）。
- */
-declare function fixSkillEntry(skillsDir: string, folder: string): SkillFixResult;
-//#endregion
-//#region src/shared/bridge-contract.d.ts
-/**
- * settings bridge 跨端契约（host 注册 / client 消费的唯一来源）。
- * 铁律：25 端点载荷统一成功 `{ ok: true, value }`、失败 `{ ok: false, code?, message? }`；
- * 端点附加字段只能以 value 旁的可选扩展字段出现（describe）。
- * 改路径或载荷形状必须同步更新 test/shared/bridge-contract.test.mjs。
- */
-declare const SETTINGS_BRIDGE_PREFIX = "/api/prompt-tool/settings";
-/** 桥端点路径（相对前缀）。新增端点必须同时登记到契约测试。 */
-declare const BRIDGE_ENDPOINTS: {
-  readonly meta: "/meta";
-  readonly bootstrap: "/bootstrap";
-  readonly describe: "/describe";
-  readonly models: "/models";
-  readonly mutate: "/mutate";
-  readonly configsValidate: "/configs-validate";
-  readonly skillFix: "/skill-fix";
-  readonly templates: "/templates";
-  readonly promptConfigs: "/prompt-configs";
-  readonly presetContent: "/preset-content";
-  readonly importPreset: "/import-preset";
-  readonly paramOverrides: "/param-overrides";
-  readonly presetVariables: "/preset-variables";
-  readonly customTools: "/custom-tools";
-  readonly importPresetPackage: "/import-preset-package";
-  readonly exportPreset: "/export-preset";
-  readonly presetDelete: "/preset-delete";
-  readonly presetClone: "/preset-clone";
-  readonly presetDuplicate: "/preset-duplicate";
-  readonly presetOpen: "/preset-open";
-  readonly charactersImport: "/characters-import";
-  readonly charactersList: "/characters-list";
-  readonly charactersDelete: "/characters-delete";
-  readonly charactersApply: "/characters-apply";
-  readonly charactersRemove: "/characters-remove";
-};
-type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
-/** 失败载荷：两端共用。 */
-type BridgeErrorPayload = {
-  ok: false;
-  code?: string;
-  message?: string;
-};
+declare function resolveProjectRoot(cwd: string): string;
+declare function skillRoots(options: {
+  cwd?: string;
+  dshHome: string;
+  folders: readonly string[];
+}): ScanRoot[];
+/** 只扫描普通目录包和直属 Markdown 文件；链接技能由 registry 补充为只读条目。 */
+declare function scanRoot(root: ScanRoot): ScannedSkill[];
+declare function scanRoots(roots: readonly ScanRoot[]): ScannedSkill[];
+declare function catalogFromScan(skills: readonly ScannedSkill[]): SkillCatalogEntry[];
 //#endregion
 //#region src/runtime/skills-parse.d.ts
 interface SkillFrontmatter {
@@ -646,11 +887,16 @@ interface SkillFrontmatter {
 declare function parseFrontmatter(text: string): {
   data: SkillFrontmatter;
   body: string;
+  issue?: string;
 };
 //#endregion
+//#region src/shared/preset-ids.d.ts
+/** 包内模板、用户副本与当前预设共用同名 ID；避免与宿主官方预设重名。 */
+declare const DEFAULT_PRESET_ID = "pt-standard";
+//#endregion
 //#region src/index.d.ts
 declare const name = "prompt-tool";
 declare const inject: string[];
 declare function apply(ctx: Context, configIn: Config): void;
 //#endregion
-export { BRIDGE_ENDPOINTS, type BridgeEndpoint, type BridgeErrorPayload, type CachedSkillsReader, Config, ENGINE_PARAM_KEYS, MODEL_SEGMENT_MAP, PARAM_KEYS, type PresetSpec, type PromptConfigTemplate, type PromptConfigValidationError, type PromptConfigValidationResult, PromptSettingsSchema, SETTINGS_BRIDGE_PREFIX, SKILL_NAME_RE, type SkillCatalogEntry, type SkillEntry, type SkillFixResult, type SkillFrontmatter, type ToolTemplate, WRITER_PARAM_KEYS, type WritePresetOptions, appendCharacterMemory, appendMemoryFile, apply, applyCharacterToPreset, applyModuleConfigs, buildModuleConfigsFromParams, buildWorldBookEntry, cloneBuiltinPreset, convertStToPreset, createCachedSkillsReader, deleteCharacterCard, deleteWorldBookEntry, detectModels, ensurePresetSeed, ensureWebSurface, fixSkillEntry, importCharacterCard, inject, installDefaultModelRoute, isValidSkill, listAdvertisedModels, listBuiltinTemplates, listCharacterCards, listPresets, listSkillFolders, listWorldBookEntries, loadPresetSpec, loadPromptTemplates, loadToolTemplates, mergeSkillDirs, mergeStPresets, migrateLegacyLayout, name, normalizePresetRootDir, parseFrontmatter, processStText, readCharacterMemory, readPluginState, readSkills, registerCharacterTools, registerSettingsBridge, registerTuiCommand, registerWorldBookTools, removeCharacterFromPreset, removeUserPreset, renderComposition, resolvePresetDir, resolvePresetParams, resolveProfileDir, resolveProfileSkillsDir, savePresetParams, stPresetId, syncImportedCharacterMemory, toKebabName, upsertWorldBookEntry, userPresetsDir, validSkills, validatePromptConfigs, writePluginState, writePreset };
+export { BRIDGE_ENDPOINTS, type BridgeEndpoint, type BridgeErrorPayload, type BridgeRequestMap, type BridgeValueMap, CHARACTER_MODULES_KEY, type CharacterModuleContext, Config, DEFAULT_PRESET_ID, ENGINE_CAPABILITIES, ENGINE_PARAM_KEYS, ENGINE_RECIPES, type EngineCapability, type EngineCapabilityCreateRequest, type EngineCapabilityCreateResult, type EngineCapabilityRemoveResult, INSTRUCTION_FILE_STATUSES, type InstructionContextView, type InstructionFileSnapshot, type InstructionFileStatus, MAX_BRIDGE_BODY_BYTES, MAX_CHARACTER_CARD_STREAM_BYTES, MAX_INSTRUCTION_FILE_BYTES, type ModuleSourceMode, PARAM_KEYS, PRE_STEP_COORDINATOR_SERVICE, PRE_STEP_COORDINATOR_VERSION, type PluginSubagentSeam, type PreStepCoordinatorOptions, type PreStepCoordinatorService, type PreStepFileContribution, type PreStepPromptConfig, type PreStepSource, type PresetModuleFacts, type PresetSpec, type PromptConfigTemplate, type PromptConfigValidationError, type PromptConfigValidationResult, PromptSettingsSchema, SETTINGS_BRIDGE_PREFIX, SKILL_NAME_PATTERN, type SkillCatalogEntry, type SkillFrontmatter, type SkillPolicyChange, type SkillPolicyRead, type SkillPolicyScope, type SkillPolicyWrite, type SkillsCatalogSnapshot, type SkillsRuntime, type SkillsState, type ToolTemplate, USER_SKILLS_DIR, WRITER_PARAM_KEYS, type WritePresetOptions, agentsFileCardSpecs, agentsFileId, appendCharacterMemory, appendMemoryFile, apply, applyCharacterToPreset, applyModuleConfigs, assertSafeConfigId, buildModuleConfigsFromParams, buildWorldBookEntry, catalogFromScan, characterModuleStillNeeded, cloneBuiltinPreset, configFileName, convertStToPreset, createEngineCapabilityInPreset, createSkillsReloader, createSkillsRuntime, declaredCharacterModules, deleteCharacterCard, deleteWorldBookEntry, detectAgentsFileSnapshots, detectAgentsFiles, detectModels, engineCapability, engineRecipe, ensurePresetSeed, ensureWebSurface, expandPresetSource, exportPresetPackage, importCharacterCard, importCharacterCardFile, importSkillsPackage, inject, installPreStepCoordinator, installPresetPackage, invalidateModelCatalog, invocationForScope, isEngineCapabilityPresent, listAdvertisedModels, listBuiltinTemplates, listCharacterCards, listPresets, listWorldBookEntries, loadPresetSpec, loadPromptTemplates, loadToolTemplates, mergeInstructionCards, mergeStPresets, name, parseFrontmatter, peekModelCatalog, presetImportPreview, processStText, readAgentsFileSnapshot, readCharacterMemory, readSkillInvocation, readSkillsState, recordedCharacterModules, registerCharacterTools, registerSettingsBridge, registerTuiCommand, registerWorldBookTools, removeCharacterFromPreset, removeEngineCapabilityFromPreset, removePresetModule, removeUserPreset, renderComposition, requiredCharacterModules, resolvePresetDir, resolvePresetModuleFacts, resolvePresetParams, resolveProfileDir, resolveProjectRoot, resolveSubagentStartOptions, savePresetParams, savePresetPersona, scanRoot, scanRoots, scheduleWebSurfaceRepair, scopeOfInvocation, setSkillInvocation, skillRoots, skillsStatePath, stPresetId, syncImportedCharacterMemory, upsertWorldBookEntry, userPresetsDir, validateCustomToolIdentities, validateEngineParamValues, validatePromptConfigs, writeAgentsFile, writeAgentsFileChecked, writePreset, writeSkillsState };