dsh-plugin-prompt-tool 1.0.0 → 2.0.0

package/lib/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as AssetFile, A as resolveModuleFacts, B as MAX_BRIDGE_BODY_BYTES, C as loadModuleSpec, D as removeUserPreset, E as removePresetModule, F as BRIDGE_ENDPOINTS, G as SkillInvocation, H as SETTINGS_BRIDGE_PREFIX, I as BridgeEndpoint, J as SkillSourceKind, K as SkillPolicyChange, L as BridgeErrorPayload, M as saveModuleParams, N as savePresetPersona, O as renderComposition, P as userModulesDir, Q as scopeOfInvocation, R as BridgeRequestMap, S as listModules, T as removeEngineCapabilityFromPreset, U as SkillCatalogEntry, V as MAX_CHARACTER_CARD_STREAM_BYTES, W as SkillContentSnapshot, X as SkillsState, Y as SkillsCatalogSnapshot, Z as invocationForScope, _ as buildModuleConfigsFromParams, a as installPresetPackage, at as MAX_INSTRUCTION_FILE_BYTES, b as ensurePresetSeed, c as convertStToPreset, ct as EngineCapability, d as stPresetId, dt as engineCapability, et as ImportChoices, f as EngineCapabilityCreateRequest, ft as engineRecipe, g as applyModuleConfigs, h as ModuleSpec, i as exportPresetPackage, it as InstructionFileStatus, j as resolvePresetParams, k as resolveModuleDir, l as mergeStPresets, lt as ModuleFacts, m as EngineCapabilityRemoveResult, mt as validateCustomToolIdentities, n as USER_SKILLS_DIR, nt as InstructionContextView, o as presetImportPreview, ot as ENGINE_CAPABILITIES, p as EngineCapabilityCreateResult, pt as isEngineCapabilityPresent, q as SkillPolicyScope, r as expandPresetSource, rt as InstructionFileSnapshot, s as StConversionOptions, st as ENGINE_RECIPES, tt as INSTRUCTION_FILE_STATUSES, u as processStText, ut as ModuleSourceMode, v as cloneBuiltinPreset, w as moduleDirExists, x as listBuiltinTemplates, y as createEngineCapabilityInPreset, z as BridgeValueMap } from "./paths-BgL42sSM.mjs";
+import { $ as SkillSourceKind, A as removeUserModule, B as BridgeEndpoint, C as ensureModuleSeed, Ct as moduleCapability, D as moduleDirExists, E as loadModuleSpec, F as saveModuleParams, G as MAX_CHARACTER_CARD_STREAM_BYTES, H as BridgeRequestMap, I as saveModulePersona, J as SkillCatalogEntry, K as ModuleSummary, L as userModulesDir, M as resolveModuleDir, N as resolveModuleFacts, O as removeModuleCapability, P as resolveModuleParams, Q as SkillPolicyScope, R as withModuleDefinition, S as createModuleCapability, St as isModuleCapabilityPresent, T as listModules, U as BridgeValueMap, V as BridgeErrorPayload, W as MAX_BRIDGE_BODY_BYTES, X as SkillInvocation, Y as SkillContentSnapshot, Z as SkillPolicyChange, _ as ModuleSpec, _t as MODULE_CAPABILITIES, a as installModulePackage, at as ImportChoices, b as buildModuleConfigsFromParams, bt as ModuleSourceMode, c as convertStToModule, ct as RuleDefinition, d as mergeStModulesWithReport, dt as InstructionFileSnapshot, et as SkillsCatalogSnapshot, f as processStText, ft as InstructionFileStatus, g as ModuleCapabilityRemoveResult, gt as InjectionPoint, h as ModuleCapabilityCreateResult, ht as INJECTION_POINT_ORDER, i as exportModulePackage, it as AssetFile, j as renderComposition, k as removeModuleCapabilityDeclaration, l as convertStToModuleWithReport, lt as INSTRUCTION_FILE_STATUSES, m as ModuleCapabilityCreateRequest, mt as ENGINE_RECIPES, n as USER_SKILLS_DIR, nt as invocationForScope, o as moduleImportPreview, ot as ModuleExportRequest, p as stModuleId, pt as MAX_INSTRUCTION_FILE_BYTES, q as SETTINGS_BRIDGE_PREFIX, r as expandModuleSource, rt as scopeOfInvocation, s as StConversionOptions, st as ModuleExportResult, tt as SkillsState, u as mergeStModules, ut as InstructionContextView, v as appendModuleCapabilities, vt as ModuleCapability, w as listBuiltinTemplates, wt as validateCustomToolIdentities, x as cloneBuiltinModule, xt as engineRecipe, y as applyModuleConfigs, yt as ModuleFacts, z as BRIDGE_ENDPOINTS } from "./paths-CyP0IkaM.mjs";
 import { parseDocument } from "yaml";
 import z from "@deepseek-ai/schemastery";
 import { ToolExecution } from "@deepseek-ai/dsh-tools";
@@ -11,18 +11,21 @@ declare const PARAM_KEYS: ReadonlySet<string>;
 //#endregion
 //#region src/config.d.ts
 interface Config {
-  /** 模块运行总闸；保留既有持久键，关闭只撤回运行贡献。 */
-  writePreset: Volatile<boolean>;
+  modulesEnabled: Volatile<boolean | undefined>;
+  /** 已部署配置的输入兼容；只在读取与显式保存边界归一。 */
+  writePreset?: Volatile<boolean | undefined>;
 }
 declare const Config: z<Schemastery.ObjectS<NoInfer<{
-  writePreset: z<boolean, boolean, "volatile-defined">;
+  modulesEnabled: z<boolean, boolean, "volatile">;
+  writePreset: z<boolean, boolean, "volatile">;
 }>>, Schemastery.ObjectT<NoInfer<{
-  writePreset: z<boolean, boolean, "volatile-defined">;
+  modulesEnabled: z<boolean, boolean, "volatile">;
+  writePreset: z<boolean, boolean, "volatile">;
 }>>, "plain">;
 interface PromptSettings {
   /** 运行时检测：是否检测到任何模型服务商（不写入 settings）。 */
   modelsAvailable: boolean;
-  writePreset: boolean;
+  modulesEnabled: boolean;
 }
 //#endregion
 //#region src/shared/legacy-prompt-params.d.ts
@@ -125,11 +128,11 @@ interface EngineParams {
 }
 type EngineParamKey = keyof EngineParams;
 /**
- * writePreset.runtimeOf 实际透传进运行时 params 的引擎参数子集。
- * RuntimeOptions（装配态）与 WritePresetOptions（写入态）都从这里派生，
- * 防止「加参数只改一处、writePreset 忘透传」的静默漂移（如 stageAdvanceDescription 历史事故）。
+ * writeModule 实际透传进运行时 params 的引擎参数子集。
+ * RuntimeOptions（装配态）与 WriteModuleOptions（写入态）都从这里派生，
+ * 防止「加参数只改一处、模块写者忘透传」的静默漂移（如 stageAdvanceDescription 历史事故）。
  */
-type PresetWriterParams = Partial<EngineParams & LegacyPromptParams>;
+type ModuleWriterParams = Partial<EngineParams & LegacyPromptParams>;
 /**
  * 数值型引擎参数保存前校验（与 write-preset.modelRequestConfigs 消费规则同源）。
  * 保存层响亮失败（400 逐字段错误），渲染层保持宽容（never-brick）：
@@ -148,8 +151,8 @@ interface EngineParamValueError {
   message: string;
 }
 declare const ENGINE_PARAM_KEYS: EngineParamKey[];
-/** writePreset.runtimeOf 实际透传键：全部引擎参数可直接进入 writer。 */
-declare const WRITER_PARAM_KEYS: ("firstTurnAnchor" | "firstTurnText" | "firstTurnCustom" | "guideText" | "guideCustom" | "guideEnabled" | "injectPrompt" | "firstTurnWord" | "buildPattern" | "complexPattern" | "firstTurnBuild" | "firstTurnInspect" | "firstTurnDeep" | "guideWeak" | "guideDeep" | keyof EngineParams)[];
+/** writeModule 实际透传键：全部引擎参数可直接进入 writer。 */
+declare const WRITER_PARAM_KEYS: (keyof EngineParams | "firstTurnAnchor" | "firstTurnText" | "firstTurnCustom" | "guideText" | "guideCustom" | "guideEnabled" | "injectPrompt" | "firstTurnWord" | "buildPattern" | "complexPattern" | "firstTurnBuild" | "firstTurnInspect" | "firstTurnDeep" | "guideWeak" | "guideDeep")[];
 /**
  * 校验参数键值（键集合合法性由调用方白名单先行校验，本函数同样拒绝未知键）。
  * 返回逐字段错误；空数组 = 通过。类型收窄：布尔/字符串/数值/列表各按 canonical
@@ -229,12 +232,6 @@ interface PromptConfigSpec {
 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`。
@@ -249,31 +246,38 @@ interface PromptConfigMatch {
 }
 //#endregion
 //#region src/host/write-preset.d.ts
-/**
- * 把任意单一参数模块模板物化到生成目录（writePreset）的写入态选项。
- * 引擎参数契约来自 shared/engine-params.ts（PresetWriterParams：runtimeOf 透传子集），
- * 此处只保留 writePreset 专属字段——加引擎参数只需改一处契约，漏透传变成编译错误。
- */
-interface WritePresetOptions extends PresetWriterParams {
-  /** AGENTS.md 内容资产（写生成目录 agents.md）：常驻层写盘的唯一来源，不再注入提示词。 */
+interface WriteModuleOptions {
+  modulesRoot: string;
+  moduleId: string;
+  targetModuleId?: string;
+  sourceDir?: string;
+  /** 返回独立暂存根下的合法模块目录；安装方负责交换与清理暂存根。 */
+  stageOnly?: boolean;
   agentsInstructionText?: string;
+  warn?: (message: string) => void;
+}
+/** 旧入口只做名称适配；行为规则和参数必须已写入完整定义。 */
+interface WritePresetOptions extends ModuleWriterParams {
   moduleDir: string;
-  /** @deprecated 模块排序归模块定义；该旧输入已不再覆盖顶层 order。 */
-  presetOrder?: number;
-  /** settings 层用户自定义提示词配置(优先级最高)。 */
-  promptConfigs: PromptConfigSpec[];
-  /** 当前模块目录名；默认 pt-standard。 */
   presetTemplate?: string;
-  /** 输出目录/模块 id 覆盖；缺省 = presetTemplate 同名输出。 */
   outputId?: string;
-  /** 隔离的定义/资源来源；与最终 outputId 分离，不回退同名已安装模块。 */
   sourceDir?: string;
-  /** 只生成并返回暂存目录；调用方负责安装或清理，不更新共享引擎及目标目录。 */
   materializeOnly?: boolean;
-  /** 目录加载失败等非致命告警回调。 */
+  agentsInstructionText?: string;
+  presetOrder?: number;
+  promptConfigs?: PromptConfigSpec[];
   warn?: (message: string) => void;
 }
-/** 把任意单一参数模块模板物化到生成目录;全部失败 fail loud。 */
+/** 按模块身份原地恢复切片；用户资产、正文与完整定义均不重写。 */
+declare function ensureModuleReady(id: string, options: {
+  modulesRoot?: string;
+  moduleDir?: string;
+  presetOrder?: number;
+  warn?: (message: string) => void;
+}): string;
+/** 已有同一模块只恢复切片；导入/复制先完整生成合法身份候选，再交换目标。 */
+declare function writeModule(prompt: string, options: WriteModuleOptions): string;
+/** @deprecated 使用 writeModule；旧字段仅在此边界适配。 */
 declare function writePreset(prompt: string, options: WritePresetOptions): string;
 //#endregion
 //#region src/host/agents-cards.d.ts
@@ -372,6 +376,8 @@ interface PreStepPromptConfig {
 }
 interface PreStepSource {
   configs: readonly PreStepPromptConfig[];
+  /** 已编译的本地点规则动作；执行与配置叶子共享同一批次资格帧。 */
+  ruleActions?: readonly unknown[];
   officialInstructions?: boolean;
 }
 interface PreStepCoordinatorOptions {
@@ -509,9 +515,9 @@ interface SkillsBridgeState {
  * 生成目录里属于其他工作区的文件卡不再展示（写盘白名单也不含它们）；
  * 当前工作区里没有对应生成卡的文件按默认文件卡补齐。
  */
-declare function mergeInstructionCards(presetCards: readonly unknown[], files: readonly InstructionFileSnapshot[]): unknown[];
+declare function mergeInstructionCards(moduleCards: 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,
+declare function registerSettingsBridge(ctx: Context, ns: string, getModelsState: () => ModelDetection, getSkillsState: () => SkillsBridgeState, _getEngineStrategyDir: () => string, afterSkillsChange?: () => void,
 /**
  * 生成目录（模块目录）：读取/写入哪一份提示词配置。
  *
@@ -519,20 +525,28 @@ declare function registerSettingsBridge(ctx: Context, ns: string, getModelsState
  * 没给则由 host 回退启用表首项。编辑器因此不必依赖某个全局单选——配置卡自己的
  * 模块身份决定写哪里。
  */
-getPresetConfigsDir?: (moduleId?: string) => string,
+getModuleDirectory?: (moduleId?: string) => string,
 /** 内容导入完成回调：批量 scope 只触发一次重建（更新运行时文本并重建模块）。 */
-afterPresetImport?: (scopes: Array<'preset' | 'agents'>, moduleId?: string) => void | Promise<void>,
+afterModuleContentImport?: (scopes: Array<'preset' | 'agents'>, moduleId?: string) => void | Promise<void>,
 /** 参数写入后重建指定模块；省略身份表示启用表变化，刷新全部运行实例。 */
 afterOverridesChange?: (moduleId?: string) => void | Promise<void>,
 /** 模块已完整安装后的刷新回调；失败返回未生效诊断，不再物化或撤销安装。 */
-afterPresetPackageImport?: (id: string) => void | Promise<void>,
-/** 能力/recipe 原子创建后重建回调；抛错时调用方恢复 preset.yml。 */
+afterModulePackageImport?: (id: string) => void | Promise<void>,
+/** 能力/recipe 提交后刷新回调；失败保留已提交定义并明确报告。 */
 afterCapabilityChange?: (moduleId?: string) => void | Promise<void>,
 /** 新建、复制或删除模块后重建当前模块。 */
-afterPresetListChange?: (id: string) => void | Promise<void>): {
+afterModuleListChange?: (id: string) => void | Promise<void>): {
   invalidateDescriptor: () => void;
 };
 //#endregion
+//#region src/host/module-layer-settings.d.ts
+declare class ModuleLayerSettingsError extends Error {
+  readonly code = "module-layer-settings-invalid";
+  constructor(message: string);
+}
+/** 仅消费当前 layerSettings；其余段作为未知字段留存，不投影为运行时参数。 */
+declare function readModuleLayerSettings(source: unknown): Record<string, unknown>;
+//#endregion
 //#region src/host/worldbook.d.ts
 type WorldBookEntry = Record<string, unknown>;
 /** buildWorldBookEntry 输入（两通道共用：ST 导入转换与模型 world_book_upsert 工具）。 */
@@ -597,32 +611,6 @@ type SkillsImportResult = {
 /** 浏览器上传：base64 文件列表；单技能包（无顶层目录）按 frontmatter.name 归类。 */
 declare function importSkillsPackage(root: string, files: SkillsImportFile[], overwrite?: readonly string[]): SkillsImportResult;
 //#endregion
-//#region src/runtime/configs-validate.d.ts
-interface PromptConfigValidationError {
-  /** 数组下标；结构层整组错误为 -1。 */
-  index: number;
-  /** 该条配置的 id（缺失或非字符串时为空串）。 */
-  id: string;
-  /** 引擎或结构层错误消息（保留 configs[i] 前缀）。 */
-  message: string;
-}
-interface PromptConfigValidationResult {
-  valid: boolean;
-  errors: PromptConfigValidationError[];
-  /** valid=true 时回显归一化前的输入数组（调用方预览用）。 */
-  configs?: PromptConfigSpec[];
-  /** valid=true 时逐条渲染的 yml 模块预览（与生成目录同构）。 */
-  files?: PromptConfigFile[];
-}
-/**
- * 逐条调用引擎权威校验并渲染预览文件。
- * 逐条（而非整组一次）校验保证一条坏配置不吞掉其余错误，且 index 可直接映射。
- */
-declare function validatePromptConfigs(value: unknown, options?: {
-  strategyDir?: string;
-  moduleDir?: string;
-}): Promise<PromptConfigValidationResult>;
-//#endregion
 //#region src/host/module-tool-target.d.ts
 interface ModuleToolTarget {
   id: string;
@@ -635,7 +623,6 @@ interface ModuleToolHost {
 }
 //#endregion
 //#region src/runtime/character-tools.d.ts
-/** 注册角色卡库模型工具；返回 disposer，随 character-tools 模块生命周期清理。 */
 declare function registerCharacterTools(ctx: Context, host: ModuleToolHost): () => void;
 //#endregion
 //#region src/runtime/world-book-tools.d.ts
@@ -643,44 +630,10 @@ declare function registerCharacterTools(ctx: Context, host: ModuleToolHost): ()
 declare function registerWorldBookTools(ctx: Context, host: ModuleToolHost): () => 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: ModuleSpec): 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(moduleRoot: string, templateName: string, cardId: string): {
-  ok: true;
-  synced: boolean;
-} | {
-  ok: false;
-  message: string;
-};
-/** 追加角色卡本地记忆（.characters/<id>/memory.md，跟随角色卡跨模块）。 */
-declare function appendCharacterMemory(moduleRoot: string, cardId: string, note: string): void;
-/** 追加记忆文件（时间戳列表格式；header 标注文件类型）。世界书工具与角色卡共用。 */
-declare function appendMemoryFile(file: string, note: string, header?: string): void;
-/** 读角色卡本地记忆文本（无记忆返回空串）。 */
-declare function readCharacterMemory(moduleRoot: string, cardId: string): string;
+/** 模块记忆与条目同归当前模块；来源和 id 前缀不改变位置。 */
+declare function appendModuleMemory(moduleDir: string, note: string): void;
+/** 每次显式读取最新字节；缺失为空，链接与读取失败原样报错。 */
+declare function readModuleMemory(moduleDir: string): string;
 type CharacterImportOptions = StConversionOptions & ImportChoices;
 type CharacterImportResult = {
   ok: true;
@@ -691,30 +644,11 @@ type CharacterImportResult = {
   ok: false;
   message: string;
 };
-/** 角色卡入库：PNG 原图（可选）+ 角色卡 JSON → 转换参数存 converted.yml。 */
-declare function importCharacterCard(moduleRoot: string, files: AssetFile[], options?: CharacterImportOptions): CharacterImportResult;
-/** 原始文件流导入：识别 PNG 魔数后在 host 侧提取角色卡，避免客户端 base64 膨胀 JSON。 */
-declare function importCharacterCardFile(moduleRoot: string, filePath: string, fileName?: string, options?: CharacterImportOptions): CharacterImportResult;
-interface CharacterCardListItem {
-  id: string;
-  name: string;
-  description?: string;
-  hasAvatar: boolean;
-  /** 是否已导入当前模块（激活模块 meta.importedCharacters 含该 id）。 */
-  imported: boolean;
-}
-/** 角色卡库清单 + 各卡在当前模块的导入状态。 */
-declare function listCharacterCards(moduleRoot: string, activeTemplate: string | undefined): CharacterCardListItem[];
-/** 删除角色卡库条目。 */
-declare function deleteCharacterCard(moduleRoot: string, id: string): {
-  ok: true;
-} | {
-  ok: false;
-  message: string;
-};
-/** 角色卡参数导入当前模块：promptConfigs 合并（chara-<id>- 前缀防冲突）、
- *  params 合并（角色卡覆盖同键）、meta.importedCharacters 记录来源。 */
-declare function applyCharacterToPreset(moduleRoot: string, templateName: string, cardId: string): {
+/** 复用普通模块候选校验、版本保护和目录交换，不生成角色专属存储。 */
+declare function importCharacterCard(root: string, files: AssetFile[], options?: CharacterImportOptions): Promise<CharacterImportResult>;
+declare function importCharacterCardFile(root: string, filePath: string, fileName?: string, options?: CharacterImportOptions): Promise<CharacterImportResult>;
+/** 通用并入保留既有带前缀往返行为，不复制本地记忆。 */
+declare function mergeModuleIntoModule(root: string, targetId: string, sourceId: string): {
   ok: true;
   count: number;
   personaOpened?: boolean;
@@ -722,9 +656,8 @@ declare function applyCharacterToPreset(moduleRoot: string, templateName: string
   ok: false;
   message: string;
 };
-/** 从当前模块移除角色卡参数：删前缀 promptConfigs、删该卡声明的 params 键、
- *  meta.importedCharacters 除名。 */
-declare function removeCharacterFromPreset(moduleRoot: string, templateName: string, cardId: string): {
+/** 撤销并入内容；旧 chara 前缀可撤销，能力归属只写一份登记。 */
+declare function removeMergedModule(root: string, targetId: string, sourceId: string): {
   ok: true;
   count: number;
 } | {
@@ -739,7 +672,7 @@ interface PromptConfigTemplate {
   /** 模板原文（编辑器源码模式可直接展示）。 */
   content: string;
   /** 解析后的单条提示词配置。 */
-  spec: PromptConfigSpec;
+  spec: RuleDefinition;
 }
 /** 自定义工具模板（templates/tools/*.yml；tool-config-engine 定义形态）。 */
 interface ToolTemplate {
@@ -758,15 +691,15 @@ type TuiSource = PromptSettings & {
   skillCatalog: SkillCatalogEntry[];
   activeSkillsDirs: string[];
 };
-/** 参数保存回调：写激活模块 preset.yml；失败必须抛给命令层渲染为错误。 */
-type SavePresetParam = (key: string, value: unknown) => void | Promise<void>;
+/** 参数保存回调：写激活模块 module.yml；失败必须抛给命令层渲染为错误。 */
+type SaveModuleParam = (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: () => TuiSource, getModelsState: () => ModelDetection, getModelCatalog: () => Promise<Record<string, string[]>>, getPresetConfigsDir?: () => string, savePresetParam?: SavePresetParam, toggleSkillState?: ToggleSkillState): void;
+declare function registerTuiCommand(ctx: Context, ns: 'prompt-tool', getSource: () => TuiSource, getModelsState: () => ModelDetection, getModelCatalog: () => Promise<Record<string, string[]>>, getModuleDirectory?: () => string, saveModuleParam?: SaveModuleParam, toggleSkillState?: ToggleSkillState, refreshModule?: (id: string) => Promise<void>): void;
 //#endregion
 //#region src/host/skills-refresh.d.ts
 interface SkillsReloaderDeps {
@@ -829,6 +762,16 @@ declare function scanRoot(root: ScanRoot): ScannedSkill[];
 declare function scanRoots(roots: readonly ScanRoot[]): ScannedSkill[];
 declare function catalogFromScan(skills: readonly ScannedSkill[]): SkillCatalogEntry[];
 //#endregion
+//#region src/host/module-install.d.ts
+declare function assertModuleId(id: unknown): asserts id is string;
+/** ENOENT 才表示不存在；权限、占用与读取失败继续传播。 */
+declare function modulePathExists(path: string): boolean;
+declare function canonicalModulesRoot(root: string, allowMissing?: boolean): string;
+/** 根与目标先解析真实路径，拒绝链接目录及定义身份不一致。 */
+declare function assertModuleDirectory(root: string, id: string, allowMissing?: boolean): string;
+/** 复制和物化只接受自有普通文件；不跟随任意层级链接读取根外数据。 */
+declare function assertModuleTree(dir: string): void;
+//#endregion
 //#region src/runtime/skills-parse.d.ts
 interface SkillFrontmatter {
   name?: string;
@@ -860,4 +803,4 @@ 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 BridgeRequestMap, type BridgeValueMap, CHARACTER_MODULES_KEY, type CharacterModuleContext, Config, DEFAULT_MODULE_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 ModuleFacts, type ModuleSourceMode, type ModuleSpec, PARAM_KEYS, PRE_STEP_COORDINATOR_SERVICE, PRE_STEP_COORDINATOR_VERSION, type PluginSubagentSeam, type PreStepCoordinatorOptions, type PreStepCoordinatorService, type PreStepPromptConfig, type PreStepSource, type PromptConfigTemplate, type PromptConfigValidationError, type PromptConfigValidationResult, 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, listModules, listWorldBookEntries, loadModuleSpec, loadPromptTemplates, loadToolTemplates, mergeInstructionCards, mergeStPresets, moduleDirExists, name, parseFrontmatter, peekModelCatalog, presetImportPreview, processStText, readAgentsFileSnapshot, readCharacterMemory, readSkillInvocation, readSkillsState, recordedCharacterModules, registerCharacterTools, registerSettingsBridge, registerTuiCommand, registerWorldBookTools, removeCharacterFromPreset, removeEngineCapabilityFromPreset, removePresetModule, removeUserPreset, renderComposition, requiredCharacterModules, resolveModuleDir, resolveModuleFacts, resolvePresetParams, resolveProfileDir, resolveProjectRoot, resolveSubagentStartOptions, saveModuleParams, savePresetPersona, scanRoot, scanRoots, scheduleWebSurfaceRepair, scopeOfInvocation, setSkillInvocation, skillRoots, skillsStatePath, stPresetId, syncImportedCharacterMemory, upsertWorldBookEntry, userModulesDir, validateCustomToolIdentities, validateEngineParamValues, validatePromptConfigs, writeAgentsFile, writeAgentsFileChecked, writePreset, writeSkillsState };
+export { BRIDGE_ENDPOINTS, type BridgeEndpoint, type BridgeErrorPayload, type BridgeRequestMap, type BridgeValueMap, Config, DEFAULT_MODULE_ID, MODULE_CAPABILITIES as ENGINE_CAPABILITIES, MODULE_CAPABILITIES, ENGINE_PARAM_KEYS, ENGINE_RECIPES, type ModuleCapability as EngineCapability, type ModuleCapability, type ModuleCapabilityCreateRequest as EngineCapabilityCreateRequest, type ModuleCapabilityCreateRequest, type ModuleCapabilityCreateResult as EngineCapabilityCreateResult, type ModuleCapabilityCreateResult, type ModuleCapabilityRemoveResult as EngineCapabilityRemoveResult, type ModuleCapabilityRemoveResult, INJECTION_POINT_ORDER, INSTRUCTION_FILE_STATUSES, type InjectionPoint, type InstructionContextView, type InstructionFileSnapshot, type InstructionFileStatus, MAX_BRIDGE_BODY_BYTES, MAX_CHARACTER_CARD_STREAM_BYTES, MAX_INSTRUCTION_FILE_BYTES, type ModuleExportRequest, type ModuleExportResult, type ModuleFacts, ModuleLayerSettingsError, type ModuleSourceMode, type ModuleSpec, type ModuleSummary, type ModuleWriterParams, PARAM_KEYS, PRE_STEP_COORDINATOR_SERVICE, PRE_STEP_COORDINATOR_VERSION, type PluginSubagentSeam, type PreStepCoordinatorOptions, type PreStepCoordinatorService, type PreStepPromptConfig, type PreStepSource, type PromptConfigTemplate, 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 WriteModuleOptions, type WritePresetOptions, agentsFileCardSpecs, agentsFileId, appendModuleCapabilities, appendModuleMemory, apply, applyModuleConfigs, assertModuleDirectory, assertModuleId, assertModuleTree, assertSafeConfigId, buildModuleConfigsFromParams, buildWorldBookEntry, canonicalModulesRoot, catalogFromScan, cloneBuiltinModule, cloneBuiltinModule as cloneBuiltinPreset, configFileName, convertStToModule, convertStToModule as convertStToPreset, convertStToModuleWithReport, createModuleCapability as createEngineCapabilityInPreset, createModuleCapability, createSkillsReloader, createSkillsRuntime, deleteWorldBookEntry, detectAgentsFileSnapshots, detectAgentsFiles, detectModels, moduleCapability as engineCapability, moduleCapability, engineRecipe, ensureModuleReady, ensureModuleSeed, ensureModuleSeed as ensurePresetSeed, ensureWebSurface, expandModuleSource, expandModuleSource as expandPresetSource, exportModulePackage, exportModulePackage as exportPresetPackage, importCharacterCard, importCharacterCardFile, importSkillsPackage, inject, installModulePackage, installModulePackage as installPresetPackage, installPreStepCoordinator, invalidateModelCatalog, invocationForScope, isModuleCapabilityPresent as isEngineCapabilityPresent, isModuleCapabilityPresent, listAdvertisedModels, listBuiltinTemplates, listModules, listWorldBookEntries, loadModuleSpec, loadPromptTemplates, loadToolTemplates, mergeInstructionCards, mergeModuleIntoModule, mergeStModules, mergeStModules as mergeStPresets, mergeStModulesWithReport, moduleDirExists, moduleImportPreview, moduleImportPreview as presetImportPreview, modulePathExists, name, parseFrontmatter, peekModelCatalog, processStText, readAgentsFileSnapshot, readModuleLayerSettings, readModuleMemory, readSkillInvocation, readSkillsState, registerCharacterTools, registerSettingsBridge, registerTuiCommand, registerWorldBookTools, removeModuleCapability as removeEngineCapabilityFromPreset, removeModuleCapability, removeMergedModule, removeModuleCapabilityDeclaration, removeModuleCapabilityDeclaration as removePresetModule, removeUserModule, removeUserModule as removeUserPreset, renderComposition, resolveModuleDir, resolveModuleFacts, resolveModuleParams, resolveModuleParams as resolvePresetParams, resolveProfileDir, resolveProjectRoot, resolveSubagentStartOptions, saveModuleParams, saveModulePersona, saveModulePersona as savePresetPersona, scanRoot, scanRoots, scheduleWebSurfaceRepair, scopeOfInvocation, setSkillInvocation, skillRoots, skillsStatePath, stModuleId, stModuleId as stPresetId, upsertWorldBookEntry, userModulesDir, validateCustomToolIdentities, validateEngineParamValues, withModuleDefinition, writeAgentsFile, writeAgentsFileChecked, writeModule, writePreset, writeSkillsState };