dsh-plugin-prompt-tool 1.0.0 → 2.0.0

package/lib/{paths-BgL42sSM.d.mts → paths-CyP0IkaM.d.mts}

@@ -2,7 +2,13 @@ import { parseDocument } from "yaml";
 //#region src/shared/engine-capabilities.d.ts
 type ModuleSourceMode = 'explicit' | 'composition' | 'official' | 'unknown';
 /** 官方九个注入层：与 engine/schema.mjs 的 LAYER_ORDER 同源，改一处必须同步另一处。 */
-type EngineLayer = 'pre-step' | 'system-section' | 'runtime-context' | 'agent-request' | 'llm-stream' | 'tool-pipeline' | 'turn-stop' | 'subagent-start' | 'subagent-end';
+type InjectionPoint = 'pre-step' | 'system-section' | 'runtime-context' | 'agent-request' | 'llm-stream' | 'tool-pipeline' | 'turn-stop' | 'subagent-start' | 'subagent-end';
+/** 旧公开类型名只作输入兼容。 */
+/**
+ * 九层顺序的共享副本：宿主是旧版本（不下发 meta.layerOrder）时前端退化用它，
+ * 而不是各自再写一份层序清单。
+ */
+declare const INJECTION_POINT_ORDER: readonly InjectionPoint[];
 interface ModuleFacts {
   declaredModules: string[] | null;
   effectiveModules: string[] | null;
@@ -13,13 +19,13 @@ interface ModuleFacts {
   /** 策略段真实存在；能力声明仍在并不代表策略已开启。 */
   subagentToolPolicyEnabled?: boolean;
 }
-interface EngineCapability {
+interface ModuleCapability {
   id: string;
   moduleKeys: readonly string[];
   rowIds: readonly string[];
-  displayLayer: EngineLayer;
+  displayLayer: InjectionPoint;
   /** 真实跨层影响的相关层（只在确有第二通道时登记，避免把归属铺满九层）。 */
-  relatedLayers?: readonly EngineLayer[];
+  relatedLayers?: readonly InjectionPoint[];
   /**
    * 该能力拥有的 preset 顶层数据段（不是行级 config）。
    * 创建时若段缺失则写入 `skeleton`（保证"模块在 ⇒ 数据在"）；删除时一并移除该段。
@@ -32,16 +38,16 @@ interface EngineCapability {
   };
 }
 /** 首期只登记已有 typed editor 的能力，避免万能 key/value 表单。 */
-declare const ENGINE_CAPABILITIES: readonly EngineCapability[];
+declare const MODULE_CAPABILITIES: readonly ModuleCapability[];
 /**
  * 编辑组 = 前端一张可编辑卡（能力卡或专用卡）的主归属层。
  * id 必须是代码里真实存在的 card / 展开键名，不新增臆造 id。
  */
 interface EngineEditorGroup {
   id: string;
-  displayLayer: EngineLayer;
+  displayLayer: InjectionPoint;
   /** 真实跨层影响的相关层（只有确有第二通道时才写）。 */
-  relatedLayers?: readonly EngineLayer[];
+  relatedLayers?: readonly InjectionPoint[];
   /** 真实生效通道的只读说明键（如 'agent-request' / 'system-section'）：供 UI 显示「实际生效通道」，
    *  只写代码里可核对的事实，不承诺未验证的通道。 */
   hook: string;
@@ -60,13 +66,15 @@ interface EngineRecipe {
  * 空表天然让组合项整个消失。
  */
 declare const ENGINE_RECIPES: readonly EngineRecipe[];
-declare function engineCapability(id: string): EngineCapability | undefined;
+declare function moduleCapability(id: string): ModuleCapability | undefined;
 declare function engineRecipe(id: string): EngineRecipe | undefined;
 /** 显式模块声明中的实际能力；包含当前参数与顶层策略所需的装配。
  *  创建补声明由 host 单独检查 declaredModules；官方组合行不伪装成可编辑能力。 */
-declare function isEngineCapabilityPresent(id: string, facts: ModuleFacts | undefined): boolean;
+declare function isModuleCapabilityPresent(id: string, facts: ModuleFacts | undefined): boolean;
 /** custom tool 的运行时名称缺省回落 id；保存前拒绝会导致同层注册失败的重复项。 */
 declare function validateCustomToolIdentities(tools: readonly unknown[]): string[];
+/** 已发布名称只在此边界保留，内部使用模块能力与插入点命名。 */
+type EngineLayer = InjectionPoint;
 //#endregion
 //#region src/shared/instructions.d.ts
 /**
@@ -176,6 +184,88 @@ interface PersonaSpec {
   includeRuntimeContext?: boolean;
 }
 //#endregion
+//#region src/shared/rules.d.ts
+/** 一张独立配置卡的判断树；原语与组合的合法形状由引擎唯一校验。 */
+type RuleCondition = Record<string, unknown>;
+/** 动作拥有稳定身份；其执行点由动作目录推导，不能任意指定宿主事件。 */
+interface RuleAction extends Record<string, unknown> {
+  id: string;
+  kind: string;
+  channelOrder?: number;
+  waterfallPosition?: 'default' | 'outermost';
+}
+/**
+ * module.yml.rules 的单一规则定义；层用于呈现归属，不建立跨层执行顺序。
+ *
+ * **旧名 `when`/`do` 已随引擎重构退役**（不再作为兼容输入），全链路只有 `if`/`then`/`else`。
+ * 定义迁移由 YAML Document API 改键名完成，注释与未知字段原地保留。
+ */
+interface RuleDefinition {
+  id: string;
+  name?: string;
+  enabled?: boolean;
+  layer?: EngineLayer;
+  group?: string;
+  exclusive?: boolean;
+  /** 分支条件；缺省 = 无条件。 */
+  if?: RuleCondition;
+  /** 动作列表。 */
+  then: RuleAction[];
+  /** `if` 不命中时执行；与 `then` 结构互斥（编译期按 `not(if)` 展开）。 */
+  else?: RuleAction[];
+}
+/** 显式旧身份使改名、删除与 configOrder 在同一事务中更新。 */
+interface RuleEdit {
+  previousId: string | null;
+  rule: RuleDefinition | null;
+  /** 正文编辑不拥有启停与互斥状态；修改状态须显式声明并校验 settings 版本。 */
+  settingsChanged?: boolean;
+}
+interface RuleRevisions {
+  rules: Record<string, string>;
+  settings: string;
+  variables: string;
+}
+interface RulesRequest {
+  expectedModuleId?: string;
+  /** 旧公开输入仅在边界归一。 */
+  expectedPresetId?: string;
+  expectedRevision?: string;
+  expectedRevisions?: Partial<RuleRevisions>;
+  edits?: RuleEdit[];
+  /** 显式启用目标；保存端同时停用同模块互斥组的其他卡。 */
+  activateRuleId?: string;
+  validateOnly?: boolean;
+  /** 只重新发布已提交定义，不能与规则修改或候选校验混用。 */
+  refreshOnly?: boolean;
+}
+interface RuleEditorMeta {
+  predicates: Array<{
+    kind: string;
+    example: Record<string, unknown>;
+  }>;
+  composites: string[];
+  actions: Array<{
+    kind: string;
+    example: Record<string, unknown>;
+    channel: string;
+    phase: string;
+    supportsWhen: boolean;
+    lifecycle?: 'event' | 'registration';
+  }>;
+  waterfallPositions: string[];
+}
+interface RulesSnapshot {
+  rules: RuleDefinition[];
+  revisions: RuleRevisions;
+  /** 仅旧客户端兼容输入，不是规范响应的版本来源。 */
+  revision?: string;
+  meta: RuleEditorMeta;
+  persisted?: boolean;
+  publicationPending?: boolean;
+  publicationError?: string;
+}
+//#endregion
 //#region src/shared/module-config-order.d.ts
 /** 配置卡身份与排序快照；序号归模块定义，正文不进入排序载荷。 */
 interface ModuleConfigIdentity {
@@ -233,14 +323,14 @@ interface AssetImportRequest extends ImportChoices {
   expectedSourceDigest?: string;
   expectedPreviewRevision?: string;
 }
-interface PresetExportRequest {
+interface ModuleExportRequest {
   id: string;
   mode?: 'definition' | 'zip';
   preview?: boolean;
   expectedRevision?: string;
   memoryChoices?: Record<string, 'include' | 'exclude'>;
 }
-interface PresetExportResult {
+interface ModuleExportResult {
   id: string;
   name: string;
   content: string;
@@ -372,7 +462,6 @@ declare const BRIDGE_ENDPOINTS: {
   readonly models: "/models";
   readonly modelReasoning: "/model-reasoning";
   readonly mutate: "/mutate";
-  readonly configsValidate: "/configs-validate";
   readonly skillsList: "/skills-list";
   readonly skillPolicy: "/skill-policy";
   readonly skillRead: "/skill-read";
@@ -386,17 +475,18 @@ declare const BRIDGE_ENDPOINTS: {
   readonly promptConfigs: "/prompt-configs";
   readonly agentsFile: "/agents-file";
   readonly instructionsPolicy: "/instructions-policy";
-  readonly presetContent: "/preset-content";
+  readonly moduleContent: "/module-content";
   readonly importPreset: "/import-preset";
   readonly paramOverrides: "/param-overrides";
   readonly triggers: "/triggers";
+  readonly rules: "/rules";
   readonly persona: "/persona";
-  readonly presetVariables: "/preset-variables";
+  readonly moduleVariables: "/module-variables";
   readonly customTools: "/custom-tools";
-  readonly importPresetPackage: "/import-preset-package";
+  readonly importModulePackage: "/import-module-package";
   readonly assetUpload: "/asset-upload";
   readonly assetRelease: "/asset-release";
-  readonly exportPreset: "/export-preset";
+  readonly exportModule: "/export-module";
   readonly moduleDelete: "/module-delete";
   readonly moduleClone: "/module-clone";
   readonly moduleDuplicate: "/module-duplicate";
@@ -405,14 +495,12 @@ declare const BRIDGE_ENDPOINTS: {
   readonly moduleConfigOrder: "/module-config-order";
   readonly charactersImport: "/characters-import";
   readonly charactersImportStream: "/characters-import-stream";
-  readonly charactersList: "/characters-list";
-  readonly charactersDelete: "/characters-delete";
-  readonly charactersApply: "/characters-apply";
-  readonly charactersRemove: "/characters-remove";
+  readonly moduleMerge: "/module-merge";
+  readonly moduleUnmerge: "/module-unmerge";
   readonly subagentToolPolicy: "/subagent-tool-policy";
   readonly subagentToolPolicyPreview: "/subagent-tool-policy-preview";
   readonly toolSurface: "/tool-surface";
-  readonly engineCapability: "/engine-capability";
+  readonly moduleCapability: "/module-capability";
   readonly worldBookDiagnostics: "/world-book-diagnostics";
 };
 type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
@@ -423,6 +511,18 @@ type BridgeErrorPayload = {
   message?: string;
   conflicts?: string[];
 };
+/** 插件可编辑模块的身份与展示元数据；不可渲染的项保留身份供用户修复。 */
+interface ModuleSummary {
+  id: string;
+  name: string;
+  user?: boolean;
+  renderable?: boolean;
+  description?: string;
+  meta?: Record<string, unknown>;
+  broken?: string;
+  /** 是否在存储根 `config.yml` 的启用表里（启用即参与运行时装配）。 */
+  enabled?: boolean;
+}
 /**
  * 端点级请求体契约（body 形状；无请求体端点 = undefined）。
  * 与 BRIDGE_ENDPOINTS 一一对应：新增端点必须同时补请求/响应映射，否则编译期断言失败。
@@ -447,10 +547,6 @@ interface BridgeRequestMap {
     ops: unknown[];
     expectedRevision?: number;
   };
-  configsValidate: {
-    promptConfigs: unknown[];
-    strategyDir?: string;
-  };
   /** 技能清单：按会话工作区扫描官方六类技能根，调用策略取自各技能文件的 frontmatter。 */
   skillsList: {
     sessionId?: string;
@@ -529,39 +625,42 @@ interface BridgeRequestMap {
     policy?: InstructionPolicyPatch;
     expectedRevision?: string | null;
   } | undefined;
-  presetContent: undefined;
+  moduleContent: undefined;
   importPreset: {
     contents: Array<{
       scope: 'preset' | 'agents';
       content: string;
     }>;
-    expectedPresetId?: string;
+    expectedModuleId?: string;
   };
   paramOverrides: {
     overrides?: Record<string, unknown>;
     promptConfigs?: unknown[];
     rebuild?: boolean;
-    expectedPresetId?: string;
+    expectedModuleId?: string;
   };
   triggers: {
-    expectedPresetId: string;
+    expectedModuleId: string;
     triggers?: unknown[];
     expectedRevision?: string;
     validateOnly?: boolean;
   };
+  rules: RulesRequest;
   /** 顶层 persona 段读写（官方 @deepseek-ai/dsh-persona 行 config 同构）；省略 persona 键 = 读取。 */
   persona: {
     persona?: PersonaSpec | null;
-    expectedPresetId?: string;
+    expectedModuleId?: string;
   } | undefined;
-  presetVariables: {
+  moduleVariables: {
     variables?: Record<string, string>;
     enabled?: boolean;
-    expectedPresetId?: string;
+    expectedModuleId?: string;
+    expectedRevisions?: Partial<RuleRevisions>;
+    refreshOnly?: boolean;
   };
   customTools: {
     customTools?: unknown[];
-    expectedPresetId?: string;
+    expectedModuleId?: string;
   } | undefined;
   /**
    * 模块包导入（原生/ST/PNG/ZIP）。`preview: true` 只转换并返回报告，不写目标；
@@ -572,12 +671,12 @@ interface BridgeRequestMap {
    * （`state: 'needs-order-selection'`），提交时仍无法明确对应则拒绝。
    * 上述参数只接受声明的类型，其它类型一律 400（见 docs/SillyTavern.md）。
    */
-  importPresetPackage: AssetImportRequest;
+  importModulePackage: AssetImportRequest;
   assetUpload: undefined;
   assetRelease: {
     sourceId: string;
   };
-  exportPreset: PresetExportRequest;
+  exportModule: ModuleExportRequest;
   moduleDelete: {
     id: string;
   };
@@ -602,22 +701,18 @@ interface BridgeRequestMap {
     entries: ModuleConfigIdentity[];
     expectedRevision: string;
   } | undefined;
-  /** 角色卡 PNG/JSON/YAML 导入；预览不写角色库，提交必验版本，目标和选组均绑定预览。 */
+  /** 角色卡来源导入为普通模块；预览只读，提交与模块安装共用版本边界。 */
   charactersImport: AssetImportRequest;
   charactersImportStream: undefined;
-  charactersList: undefined;
-  charactersDelete: {
-    id: string;
-  };
-  charactersApply: {
+  moduleMerge: {
     id: string;
   };
-  charactersRemove: {
+  moduleUnmerge: {
     id: string;
   };
   subagentToolPolicy: {
     policy?: unknown;
-    expectedPresetId?: string;
+    expectedModuleId?: string;
   } | undefined;
   subagentToolPolicyPreview: {
     tool?: string;
@@ -636,14 +731,14 @@ interface BridgeRequestMap {
     presetId: string;
     sessionId?: never;
   };
-  engineCapability: ({
+  moduleCapability: ({
     action: 'create' | 'remove';
     capabilityId: string;
   } | {
     action: 'create-recipe';
     recipeId: string;
   }) & {
-    expectedPresetId?: string;
+    expectedModuleId?: string;
   };
   /** 只读世界书诊断：只回当前授权会话最近一次选择的观测记录。 */
   worldBookDiagnostics: {
@@ -826,16 +921,6 @@ interface BridgeValueMap {
     reasoning: ModelReasoningView;
   };
   mutate: BridgeSettingsView;
-  configsValidate: {
-    valid: boolean;
-    errors: Array<{
-      index: number;
-      id: string;
-      message: string;
-    }>;
-    configs?: unknown[];
-    files?: unknown[];
-  };
   /** 技能清单 + 引用目录 + 技能根（客户端据此渲染来源分组与调用策略）。 */
   skillsList: SkillsCatalogSnapshot & {
     folders: string[];
@@ -882,7 +967,7 @@ interface BridgeValueMap {
     exists: boolean;
     error?: string;
   };
-  presetContent: Record<string, unknown>;
+  moduleContent: Record<string, unknown>;
   importPreset: {
     scopes: Array<'preset' | 'agents'>;
   };
@@ -896,17 +981,22 @@ interface BridgeValueMap {
     revision: string;
     meta: TriggerEditorMeta;
   };
+  rules: RulesSnapshot;
   persona: {
     persona: PersonaSpec | null;
   };
-  presetVariables: {
+  moduleVariables: {
     variables: Record<string, string>;
     enabled: boolean;
+    revisions: RuleRevisions;
+    persisted?: boolean;
+    publicationPending?: boolean;
+    publicationError?: string;
   };
   customTools: {
     customTools?: unknown[];
   };
-  importPresetPackage: {
+  importModulePackage: {
     id?: string;
     backupPath?: string;
     preview?: boolean;
@@ -928,7 +1018,7 @@ interface BridgeValueMap {
   assetRelease: {
     released: boolean;
   };
-  exportPreset: PresetExportResult;
+  exportModule: ModuleExportResult;
   moduleDelete: {
     id: string;
   };
@@ -961,23 +1051,11 @@ interface BridgeValueMap {
     id: string;
     name: string;
   };
-  charactersList: {
-    characters: Array<{
-      id: string;
-      name: string;
-      description?: string;
-      hasAvatar: boolean;
-      imported: boolean;
-    }>;
-  };
-  charactersDelete: {
-    id: string;
-  };
-  charactersApply: {
+  moduleMerge: {
     id: string;
     count: number;
   };
-  charactersRemove: {
+  moduleUnmerge: {
     id: string;
     count: number;
   };
@@ -999,7 +1077,7 @@ interface BridgeValueMap {
       description: string;
     }>;
   };
-  engineCapability: {
+  moduleCapability: {
     changed: boolean;
     addedModules?: string[];
     removedModules?: string[];
@@ -1014,6 +1092,22 @@ interface BridgeValueMap {
   };
 }
 //#endregion
+//#region src/host/module-storage.d.ts
+interface ModuleDefinitionSnapshot {
+  dir: string;
+  file: string;
+  text: string;
+  doc: ReturnType<typeof parseDocument>;
+  source: Record<string, unknown>;
+  revision: string;
+  revisions: RuleRevisions;
+  rules: RuleDefinition[];
+  configOrder: Record<string, number>;
+  variables: Record<string, string>;
+  variablesEnabled: boolean;
+}
+declare function withModuleDefinition$1(directory: string, mutate: (doc: ReturnType<typeof parseDocument>, source: Record<string, unknown>) => void): ModuleDefinitionSnapshot;
+//#endregion
 //#region src/host/manifest.d.ts
 /**
  * 模块目录确实存在于本插件存储根（身份判定与官方登记状态无关）。
@@ -1044,8 +1138,6 @@ interface ModuleSpec {
   params?: Record<string, unknown>;
   /** 共享引擎参数按编辑组的主归属插入点存储；规则实例仍拥有各自 params。 */
   layerSettings?: Record<string, Record<string, unknown>>;
-  /** 兼容读取诊断，不写回模块定义。 */
-  legacyParamWarnings?: string[];
   /** 顶层人设段（官方 @deepseek-ai/dsh-persona 行同构）：prefix/suffix/complete/includeRuntimeContext。 */
   persona?: PersonaSpec;
   /** 模块级模板变量（{{key}} 插值源；与 layerSettings 分离，顶层 variables 段）。 */
@@ -1054,18 +1146,16 @@ interface ModuleSpec {
   customTools?: unknown[];
   /** 子代理实例级工具策略（subagentToolPolicy 顶层领域段；缺省 = 官方 delegation 行为）。 */
   subagentToolPolicy?: Record<string, unknown>;
-  /**
-   * 触发器声明（`triggers` 顶层段）：`{ id, channel, when?, do, … }` 的数组。
-   * 声明**由模块提供**（引擎不带默认），物化为 `triggers.yml` 后由 `declared-triggers`
-   * 运行时模块读入并注册；形状与校验归 `engine/trigger-spec.mjs` 的声明编译器。
-   */
+  /** @deprecated 仅标记旧导入形状；loadModuleSpec 拒绝，须先离线迁移。 */
   triggers?: unknown[];
   /** 模板变量插值开关（缺省 true = 启用；false = 停用，writePreset 不生成变量文件）。 */
   variablesEnabled?: boolean;
-  /** 可选:模板自定义提示词配置覆盖(纯数据,不使用模板语法)。 */
+  /** @deprecated 仅标记旧导入形状；loadModuleSpec 拒绝，须先离线迁移。 */
   promptConfigs?: unknown[];
   /** 配置卡的持久文件序号；跨模块UI排序只改此轻量元数据。 */
   configOrder?: Record<string, number>;
+  /** 模块唯一的条件→动作定义；旧源只供离线迁移器读取。 */
+  rules?: RuleDefinition[];
   /** 可选:引擎组合模块行参数直写(行级 map config 浅合并;参数桥未覆盖的键生效,参数桥优先)。 */
   moduleConfigs?: Record<string, Record<string, unknown>>;
   upstream?: Record<string, unknown>;
@@ -1074,16 +1164,14 @@ interface ModuleSpec {
  * 从模块 module.yml 的 modules 清单移除一个模块 id（YAML Document 保留注释
  * 与其余字段）。返回是否发生修改；文件缺失或没有该模块时返回 false。
  */
-declare function removePresetModule(dir: string, moduleId: string): boolean;
+declare function removeModuleCapabilityDeclaration(dir: string, moduleId: string): boolean;
 /** 加载某个模块模板的单一参数文件 modules/<name>/module.yml。 */
-declare function loadModuleSpec(dir: string, options?: {
-  legacyParams?: boolean;
-}): ModuleSpec;
+declare function loadModuleSpec(dir: string): ModuleSpec;
 /** 模块根：本插件的存储根（~/.dsh/.prompt-tool），导入/新建/种子化的模块都放这里。 */
 declare function userModulesDir(): string;
 /**
  * 解析模块模板目录：当前模块根优先，包内模板回退；不读取其他部署根的同名模块。
- * 目录名与声明的 preset.yml id 一致；不扫描其他目录的 id 别名。
+ * 目录名与声明的 module.yml id 一致；不扫描其他目录的 id 别名。
  */
 declare function resolveModuleDir(template: string, moduleRoot?: string): string;
 /** 本插件模块清单；所有目录按同一身份与组合源规则列举。 */
@@ -1101,11 +1189,11 @@ declare function listBuiltinTemplates(): Array<{
   name: string;
 }>;
 /** 按包内同名目录补建缺失的内置模块；已有目录的定义、生成物和资源保持原样。 */
-declare function ensurePresetSeed(root?: string): {
+declare function ensureModuleSeed(root?: string): {
   created: string[];
 };
 /** 从包内同名目录复制模块；autoSuffix=true 时递增目录名并同步定义身份。 */
-declare function cloneBuiltinPreset(id: string, autoSuffix?: boolean, moduleRoot?: string): {
+declare function cloneBuiltinModule(id: string, autoSuffix?: boolean, moduleRoot?: string): {
   ok: true;
   id: string;
 } | {
@@ -1113,27 +1201,33 @@ declare function cloneBuiltinPreset(id: string, autoSuffix?: boolean, moduleRoot
   message: string;
 };
 /**
- * 保存模块参数：写 layerSettings（merge）/ promptConfigs（整体替换）。
- * parseDocument 保留注释与未知键（preset.yml 模板含大量注释）；空值键删除（'' / []，
+ * 保存部署能力参数与模板变量；规则写入只走 module-rules 的版本事务。
+ * parseDocument 保留注释与未知键（module.yml 模板含大量注释）；空值键删除（'' / []，
  * 回落模板/引擎默认；0 与 false 照常写入——语义与函数内注释、docs §3 一致）。
  */
-declare function saveModuleParams(moduleRoot: string, templateName: string, params: Record<string, unknown> | undefined, promptConfigs: unknown[] | undefined, variables?: Record<string, string>, variablesEnabled?: boolean): void;
+declare function saveModuleParams(moduleRoot: string, templateName: string, params: Record<string, unknown> | undefined, promptConfigs: unknown[] | undefined, variables?: Record<string, string>, variablesEnabled?: boolean, expectedRevisions?: Partial<RuleRevisions>): void;
 /**
  * 保存激活模块的顶层 persona 段（官方 `@deepseek-ai/dsh-persona` 行 config 同构）。
  * null = 删除该段（回落宿主部署人设）；默认值不落键（见 personaRowConfig）。
  */
-declare function savePresetPersona(moduleRoot: string, templateName: string, persona: PersonaSpec | null): void;
+declare function saveModulePersona(moduleRoot: string, templateName: string, persona: PersonaSpec | null): void;
+/** 模块文件读-改-写（parseDocument 保留注释与未知键；mutate 内 setIn/deleteIn）。
+ *  角色卡库（characters）与世界书工具（world-book-tools）共用此入口，避免
+ *  各自实现 parseDocument 往返。写盘走原子替换，失败保留旧文件。 */
+declare function withModuleDefinition(moduleDir: string, mutate: (doc: ReturnType<typeof parseDocument>, source: Record<string, unknown>) => void): ReturnType<typeof withModuleDefinition$1>;
+/** 向 module.yml 的 modules 追加功能模块；空数组保持按需装配语义。 */
+declare function appendModuleCapabilities(doc: ReturnType<typeof parseDocument>, additions: readonly string[]): void;
 /** 删除具有合法身份的模块目录（模块根/<id>）；隐藏备份不经公共接口删除。
  *  仅作用于插件自有模块根，包内置模板不受影响；路径越界与非法 id 拒绝。
  *  模块不在宿主预设注册表里，删除后无需撤销官方登记；调用方按需重建当前模块。 */
-declare function removeUserPreset(id: string, moduleRoot?: string): {
+declare function removeUserModule(id: string, moduleRoot?: string): {
   ok: true;
 } | {
   ok: false;
   message: string;
 };
 /** 当前 layerSettings 与显式运行参数合并；不从旧磁盘 params 段回退取值。 */
-declare function resolvePresetParams(spec: ModuleSpec, runtime: Record<string, unknown>): Record<string, unknown>;
+declare function resolveModuleParams(spec: ModuleSpec, runtime: Record<string, unknown>): Record<string, unknown>;
 /**
  * 参数桥：params 扁平键 → 引擎模块行 config 对象（取代旧 __TOKEN__ 文本渲染）。
  *
@@ -1159,29 +1253,29 @@ declare function applyModuleConfigs(raw: string, configs: Record<string, Record<
  * 显式模块及当前参数/策略所需的装配是可编辑插件能力；官方组合 row 仅保留为运行事实。
  */
 declare function resolveModuleFacts(spec: ModuleSpec, templateDir?: string, editable?: boolean): ModuleFacts;
-type EngineCapabilityCreateRequest = {
+type ModuleCapabilityCreateRequest = {
   action: 'create';
   capabilityId: string;
 } | {
   action: 'create-recipe';
   recipeId: string;
 };
-interface EngineCapabilityCreateResult {
+interface ModuleCapabilityCreateResult {
   changed: boolean;
   addedModules: string[];
   capabilityIds: string[];
 }
-interface EngineCapabilityRemoveResult {
+interface ModuleCapabilityRemoveResult {
   changed: boolean;
   removedModules: string[];
   capabilityIds: string[];
 }
 /** 在内存候选文档中展开能力/recipe，校验成功后一次原子替换 module.yml。 */
-declare function createEngineCapabilityInPreset(moduleDir: string, request: EngineCapabilityCreateRequest): EngineCapabilityCreateResult;
+declare function createModuleCapability(moduleDir: string, request: ModuleCapabilityCreateRequest): ModuleCapabilityCreateResult;
 /** 删除能力：模块声明、顶层数据段，以及该能力的**显式参数与行配置**一起移除。
  *  参数在 ⇒ 装配在（见 impliedModulesFromParams）：留下参数会让移除立刻被隐含装配拉回来，
  *  所以"移除能力"必须是完整移除。未登记参数、其他能力的数据与未知字段一律不动。 */
-declare function removeEngineCapabilityFromPreset(moduleDir: string, capabilityId: string): EngineCapabilityRemoveResult;
+declare function removeModuleCapability(moduleDir: string, capabilityId: string): ModuleCapabilityRemoveResult;
 /**
  * 模块组合渲染完整链路:模块装配 → 参数桥(moduleConfigs + params)行级合并。
  * 合并优先级:参数桥(params/UI 基础层) > moduleConfigs(模板/ST 行级直写) > 行默认。
@@ -1197,8 +1291,19 @@ declare function renderComposition(spec: ModuleSpec, runtime: Record<string, unk
  *  meta.stDroppedMarkers——防止设置 dump 与位置占位污染 promptConfigs 与注入。 */
 /** 显式文本求值工具；导入本身仅 prepare，避免执行禁用卡的副作用。 */
 declare function processStText(text: string, cardName: string, variables: Record<string, string | number>): string;
+/** 合并后的最终 id 映射：来源索引 → 该来源 promptConfigs 下标 → 合并后的配置 id。 */
+type MergeIdMap = Map<number, Map<number, string>>;
+/**
+ * 合并多个转换结果为一个预设，并返回「来源 + 生成配置下标 → 最终 id」的同一份映射。
+ *
+ * 报告必须消费这份映射，而不是按后缀规则另行推测：后缀分配只发生在这里一次。
+ */
+declare function mergeStModulesWithReport(specs: ModuleSpec[]): {
+  spec: ModuleSpec;
+  idMap: MergeIdMap;
+};
 /** 合并多个转换结果为一个预设（角色卡 × 响应预设 → 单预设）。 */
-declare function mergeStPresets(specs: ModuleSpec[]): ModuleSpec;
+declare function mergeStModules(specs: ModuleSpec[]): ModuleSpec;
 /** 转换选项：多 prompt_order 分组时显式选择来源角色，避免照搬「默认任取首组」。 */
 interface StConversionOptions {
   characterId?: string;
@@ -1209,12 +1314,20 @@ interface StOrderGroupSummary {
   entries: number;
 }
 /** SillyTavern JSON 预设卡片 → 本项目 ModuleSpec（导入端点直接消费）。 */
-declare function convertStToPreset(card: unknown, baseName: string, options?: StConversionOptions): ModuleSpec;
+declare function convertStToModule(card: unknown, baseName: string, options?: StConversionOptions): ModuleSpec;
+/**
+ * 同源转换 + 结构化报告：预览与实际提交共用这一个纯函数实现，
+ * 报告只是派生元数据（不进 module.yml、不作写入凭证）。
+ */
+declare function convertStToModuleWithReport(card: unknown, baseName: string, options?: StConversionOptions): {
+  spec: ModuleSpec;
+  report: StConversionReport;
+};
 /** 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 stModuleId(baseName: string): string;
 //#endregion
 //#region src/host/import-source.d.ts
 type PreparedImport = {
@@ -1241,11 +1354,11 @@ type PreparedImport = {
 declare function prepareImport(input: AssetFile[], target: 'preset' | 'character', choices?: ImportChoices): PreparedImport;
 //#endregion
 //#region src/host/module-package.d.ts
-declare function expandPresetSource(input: AssetFile[]): Promise<AssetFile[]>;
+declare function expandModuleSource(input: AssetFile[]): Promise<AssetFile[]>;
 type ReadyImport = Extract<ReturnType<typeof prepareImport>, {
   state: 'ready';
 }>;
-declare function presetImportPreview(root: string, files: AssetFile[], request: AssetImportRequest): {
+declare function moduleImportPreview(root: string, files: AssetFile[], request: AssetImportRequest): {
   prepared: ReadyImport;
   summary: AssetSummary;
   sourceDigest: string;
@@ -1253,11 +1366,13 @@ declare function presetImportPreview(root: string, files: AssetFile[], request:
 } | Exclude<ReturnType<typeof prepareImport>, {
   state: 'ready';
 }>;
-declare function installPresetPackage(root: string, files: AssetFile[], request: AssetImportRequest): Promise<{
+declare function installModulePackage(root: string, files: AssetFile[], request: AssetImportRequest, options?: {
+  preserveAssets?: boolean;
+}): Promise<{
   id: string;
   backupPath?: string;
 }>;
-declare function exportPresetPackage(root: string, request: PresetExportRequest): Promise<PresetExportResult>;
+declare function exportModulePackage(root: string, request: ModuleExportRequest): Promise<ModuleExportResult>;
 //#endregion
 //#region src/host/paths.d.ts
 /** 用户技能根：官方 `user-dsh` 技能根，也是本插件创建、复制导入与回收站的落点。
@@ -1272,4 +1387,4 @@ declare const USER_SKILLS_DIR: string;
  */
 declare const MODULES_DIR: string;
 //#endregion
-export { AssetFile as $, resolveModuleFacts as A, MAX_BRIDGE_BODY_BYTES as B, loadModuleSpec as C, removeUserPreset as D, removePresetModule as E, BRIDGE_ENDPOINTS as F, SkillInvocation as G, SETTINGS_BRIDGE_PREFIX as H, BridgeEndpoint as I, SkillSourceKind as J, SkillPolicyChange as K, BridgeErrorPayload as L, saveModuleParams as M, savePresetPersona as N, renderComposition as O, userModulesDir as P, scopeOfInvocation as Q, BridgeRequestMap as R, listModules as S, removeEngineCapabilityFromPreset as T, SkillCatalogEntry as U, MAX_CHARACTER_CARD_STREAM_BYTES as V, SkillContentSnapshot as W, SkillsState as X, SkillsCatalogSnapshot as Y, invocationForScope as Z, buildModuleConfigsFromParams as _, installPresetPackage as a, MAX_INSTRUCTION_FILE_BYTES as at, ensurePresetSeed as b, convertStToPreset as c, EngineCapability as ct, stPresetId as d, engineCapability as dt, ImportChoices as et, EngineCapabilityCreateRequest as f, engineRecipe as ft, applyModuleConfigs as g, ModuleSpec as h, exportPresetPackage as i, InstructionFileStatus as it, resolvePresetParams as j, resolveModuleDir as k, mergeStPresets as l, ModuleFacts as lt, EngineCapabilityRemoveResult as m, validateCustomToolIdentities as mt, USER_SKILLS_DIR as n, InstructionContextView as nt, presetImportPreview as o, ENGINE_CAPABILITIES as ot, EngineCapabilityCreateResult as p, isEngineCapabilityPresent as pt, SkillPolicyScope as q, expandPresetSource as r, InstructionFileSnapshot as rt, StConversionOptions as s, ENGINE_RECIPES as st, MODULES_DIR as t, INSTRUCTION_FILE_STATUSES as tt, processStText as u, ModuleSourceMode as ut, cloneBuiltinPreset as v, moduleDirExists as w, listBuiltinTemplates as x, createEngineCapabilityInPreset as y, BridgeValueMap as z };
+export { SkillSourceKind as $, removeUserModule as A, BridgeEndpoint as B, ensureModuleSeed as C, moduleCapability as Ct, moduleDirExists as D, loadModuleSpec as E, saveModuleParams as F, MAX_CHARACTER_CARD_STREAM_BYTES as G, BridgeRequestMap as H, saveModulePersona as I, SkillCatalogEntry as J, ModuleSummary as K, userModulesDir as L, resolveModuleDir as M, resolveModuleFacts as N, removeModuleCapability as O, resolveModuleParams as P, SkillPolicyScope as Q, withModuleDefinition as R, createModuleCapability as S, isModuleCapabilityPresent as St, listModules as T, BridgeValueMap as U, BridgeErrorPayload as V, MAX_BRIDGE_BODY_BYTES as W, SkillInvocation as X, SkillContentSnapshot as Y, SkillPolicyChange as Z, ModuleSpec as _, MODULE_CAPABILITIES as _t, installModulePackage as a, ImportChoices as at, buildModuleConfigsFromParams as b, ModuleSourceMode as bt, convertStToModule as c, RuleDefinition as ct, mergeStModulesWithReport as d, InstructionFileSnapshot as dt, SkillsCatalogSnapshot as et, processStText as f, InstructionFileStatus as ft, ModuleCapabilityRemoveResult as g, InjectionPoint as gt, ModuleCapabilityCreateResult as h, INJECTION_POINT_ORDER as ht, exportModulePackage as i, AssetFile as it, renderComposition as j, removeModuleCapabilityDeclaration as k, convertStToModuleWithReport as l, INSTRUCTION_FILE_STATUSES as lt, ModuleCapabilityCreateRequest as m, ENGINE_RECIPES as mt, USER_SKILLS_DIR as n, invocationForScope as nt, moduleImportPreview as o, ModuleExportRequest as ot, stModuleId as p, MAX_INSTRUCTION_FILE_BYTES as pt, SETTINGS_BRIDGE_PREFIX as q, expandModuleSource as r, scopeOfInvocation as rt, StConversionOptions as s, ModuleExportResult as st, MODULES_DIR as t, SkillsState as tt, mergeStModules as u, InstructionContextView as ut, appendModuleCapabilities as v, ModuleCapability as vt, listBuiltinTemplates as w, validateCustomToolIdentities as wt, cloneBuiltinModule as x, engineRecipe as xt, applyModuleConfigs as y, ModuleFacts as yt, BRIDGE_ENDPOINTS as z };