dsh-plugin-prompt-tool 2.0.1 → 2.1.0

package/lib/index.d.mts

@@ -1,4 +1,3 @@
-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";
@@ -28,6 +27,83 @@ interface PromptSettings {
   modulesEnabled: boolean;
 }
 //#endregion
+//#region src/shared/engine-capabilities.d.ts
+type ModuleSourceMode = 'explicit' | 'composition' | 'official' | 'unknown';
+/** 官方九个注入层：与 engine/schema.mjs 的 LAYER_ORDER 同源，改一处必须同步另一处。 */
+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;
+  rowIds: string[];
+  sourceMode: ModuleSourceMode;
+  editable: boolean;
+  effectiveConfigs?: Record<string, Record<string, unknown>>;
+  /** 策略段真实存在；能力声明仍在并不代表策略已开启。 */
+  subagentToolPolicyEnabled?: boolean;
+}
+interface ModuleCapability {
+  id: string;
+  moduleKeys: readonly string[];
+  rowIds: readonly string[];
+  displayLayer: InjectionPoint;
+  /** 真实跨层影响的相关层（只在确有第二通道时登记，避免把归属铺满九层）。 */
+  relatedLayers?: readonly InjectionPoint[];
+  /**
+   * 该能力拥有的 preset 顶层数据段（不是行级 config）。
+   * 创建时若段缺失则写入 `skeleton`（保证"模块在 ⇒ 数据在"）；删除时一并移除该段。
+   */
+  ownSection?: {
+    /** preset.yml 顶层键名。 */
+    key: string;
+    /** 启用时写入的可用骨架（必须能通过该段的校验）。 */
+    skeleton: Readonly<Record<string, unknown>>;
+  };
+}
+/** 首期只登记已有 typed editor 的能力，避免万能 key/value 表单。 */
+declare const MODULE_CAPABILITIES: readonly ModuleCapability[];
+/**
+ * 编辑组 = 前端一张可编辑卡（能力卡或专用卡）的主归属层。
+ * id 必须是代码里真实存在的 card / 展开键名，不新增臆造 id。
+ */
+interface EngineEditorGroup {
+  id: string;
+  displayLayer: InjectionPoint;
+  /** 真实跨层影响的相关层（只有确有第二通道时才写）。 */
+  relatedLayers?: readonly InjectionPoint[];
+  /** 真实生效通道的只读说明键（如 'agent-request' / 'system-section'）：供 UI 显示「实际生效通道」，
+   *  只写代码里可核对的事实，不承诺未验证的通道。 */
+  hook: string;
+}
+interface EngineRecipe {
+  id: string;
+  capabilities: readonly string[];
+  initialParams?: Readonly<Record<string, unknown>>;
+}
+/**
+ * 只保留已有真实工作流的一键组合；recipe 本身不写入 preset.yml。
+ *
+ * B7 T3 清空：三条 recipe 的成员都是随本轮退场的专用能力（phase-control /
+ * phase-control-ptc / deliberation），没有任何一条还能组成合法能力集合。
+ * export 与 `engineRecipe()` 保留——调用点（创建菜单、bridge 校验）不必跟着改，
+ * 空表天然让组合项整个消失。
+ */
+declare const ENGINE_RECIPES: readonly EngineRecipe[];
+declare function moduleCapability(id: string): ModuleCapability | undefined;
+declare function engineRecipe(id: string): EngineRecipe | undefined;
+/** 显式模块声明中的实际能力；包含当前参数与顶层策略所需的装配。
+ *  创建补声明由 host 单独检查 declaredModules；官方组合行不伪装成可编辑能力。 */
+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/legacy-prompt-params.d.ts
 /** 旧规则快捷参数只用于读取与旧 API 兼容；新编辑器直接保存规则实例。 */
 declare const LEGACY_PROMPT_PARAM_DEFINITIONS: {
@@ -280,6 +356,91 @@ declare function writeModule(prompt: string, options: WriteModuleOptions): strin
 /** @deprecated 使用 writeModule；旧字段仅在此边界适配。 */
 declare function writePreset(prompt: string, options: WritePresetOptions): string;
 //#endregion
+//#region src/shared/instructions.d.ts
+/**
+ * 指令文件（AGENTS.md / CLAUDE.md 等）跨 host/client 的最小契约。
+ * 只放两端都要理解的形状：读取快照、工作区上下文与写入结果；
+ * 引擎侧的位置/晋升/受众算法不在这里复制。
+ */
+/** 文件卡正文读写上限；官方注入的读取与渲染预算由官方配置决定。 */
+declare const MAX_INSTRUCTION_FILE_BYTES: number;
+declare const INSTRUCTION_FILE_STATUSES: readonly ["ready", "missing", "unreadable", "too-large"];
+/**
+ * 读取状态：`ready` 之外的任何状态都不代表空正文，也禁止写盘。
+ * 读取成功的空文件是 `ready` + `text: ''`，与读取失败严格区分。
+ */
+type InstructionFileStatus = (typeof INSTRUCTION_FILE_STATUSES)[number];
+/** 单次读取形成的一致快照：正文、身份、版本来自同一次读取。 */
+interface InstructionFileSnapshot {
+  /** 服务端按真实文件身份生成；不是客户端写入授权本身。 */
+  fileId: string;
+  /** 服务端解析出的绝对路径（客户端不得据此写盘，只是展示与身份）。 */
+  path: string;
+  /** 展示用路径（DSH_HOME 内 `~/.dsh/…`，项目内相对项目根）。 */
+  displayPath: string;
+  scope: 'global' | 'project';
+  status: InstructionFileStatus;
+  /** status === 'ready' 时的原始 UTF-8 正文（可为空串）；其他状态为 ''。 */
+  text: string;
+  /** status === 'ready' 时原始文件字节的 SHA-256；其他状态为 null。 */
+  revision: string | null;
+  /** 读取失败/超限的诊断信息；ready 时不带。 */
+  message?: string;
+}
+/**
+ * 本次工作区上下文：优先由存活本地 Agent 的会话 cwd 解析；拿不到会话时回退到
+ * 部署进程 cwd（与官方 agent-instructions 的 `session.header.cwd ?? process.cwd()`
+ * 同口径），并如实标记来源，让 UI 能辨别两种范围。
+ */
+interface InstructionContextView {
+  /** 上下文 id（cwd + 文件身份集派生）；无可解析本地会话时为 null。 */
+  contextId: string | null;
+  cwd: string | null;
+  /**
+   * session = 由存活本地 Agent 的会话 cwd 解析；
+   * deploy-cwd = 会话不可用，退回部署进程 cwd（范围提示，不构成写授权）；
+   * global-only = 客户端尚无服务端解析结果时的空池标记。
+   */
+  source: 'session' | 'deploy-cwd' | 'global-only';
+}
+interface InstructionsSnapshot {
+  context: InstructionContextView;
+  files: InstructionFileSnapshot[];
+  owner: InstructionsOwnerView;
+}
+/**
+ * 指令负责人事实：本会话实际装配里是否仍挂着官方指令加载行。
+ * `true` 表示官方负责注入；`false` 表示模块未装配官方来源；`null` 表示尚未观察到。
+ */
+interface InstructionsOwnerView {
+  officialInstructions: boolean | null;
+}
+/** /agents-file 成功返回值：写盘后的新版本，客户端据此更新基线。 */
+interface InstructionFileWriteResult {
+  fileId: string;
+  revision: string;
+}
+/**
+ * 指令文件卡策略（独立于模块与 settings 的本插件自有状态）。
+ *
+ * 只承载逐文件开关与展示名；正文、读取版本、会话 ID 和路径不进入策略。
+ * 默认放行官方注入，关闭只过滤后续消息，不撤回已持久历史。
+ */
+interface InstructionPolicyFileOverride {
+  /** 缺省开启；false 拦截该文件后续的官方注入。 */
+  enabled?: boolean;
+  /** 可选显示名（只影响 UI 标题）。 */
+  name?: string;
+}
+interface InstructionPolicy {
+  /** 按 fileId 的覆盖；删除覆盖恢复默认放行。 */
+  files: Record<string, InstructionPolicyFileOverride>;
+}
+/** 局部更新：只写传入的键；files[fileId] = null 表示删除该覆盖。 */
+interface InstructionPolicyPatch {
+  files?: Record<string, InstructionPolicyFileOverride | null>;
+}
+//#endregion
 //#region src/host/agents-cards.d.ts
 /** 文件身份（fileId + 路径 + 展示路径）：生成卡与读取快照共用的最小形状。 */
 interface AgentsFileIdentity {
@@ -393,6 +554,937 @@ interface PreStepCoordinatorService {
 }
 declare function installPreStepCoordinator(ctx: Context, options?: PreStepCoordinatorOptions): PreStepCoordinatorService;
 //#endregion
+//#region src/shared/persona-section.d.ts
+/**
+ * preset.yml 顶层 `persona` 段契约：与官方 `@deepseek-ai/dsh-persona` 行同构，
+ * 由渲染层写入 `deployment:persona-prefix`（order 0）与
+ * `deployment:persona-suffix`（order 10200）两段。
+ * 旧 params.sectionName 人设写法不做兼容也不迁移（本项目不含迁移代码）。
+ */
+/**
+ * preset.yml 顶层 `persona` 段：与官方 `@deepseek-ai/dsh-persona` 行的 config 同构。
+ * 官方 schema：prefix required、suffix 默认 ''、complete 默认 false、
+ * includeRuntimeContext 默认 true。
+ */
+interface PersonaSpec {
+  /** `deployment:persona-prefix` 文本（第一方指导之前，官方 order 0）。 */
+  prefix: string;
+  /** `deployment:persona-suffix` 文本（第一方指导之后，官方 order 10200）。 */
+  suffix?: string;
+  /** prefix 独占整个 system prompt（抑制其余段与 suffix）。 */
+  complete?: boolean;
+  /** false = 抑制该 scope 的动态 runtime-context 快照。 */
+  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 {
+  moduleId: string;
+  configId: string;
+}
+interface ModuleConfigOrderEntry extends ModuleConfigIdentity {
+  name: string;
+  layer: string;
+  position: string;
+  sequence: number;
+  enabled: boolean;
+  audience?: 'main' | 'subagent' | null;
+  strategy?: string;
+  /** 官方文本层的定位档位；其他层不使用。 */
+  order?: number;
+}
+interface ModuleConfigOrderSnapshot {
+  revision: string;
+  entries: ModuleConfigOrderEntry[];
+}
+//#endregion
+//#region src/shared/asset-transfer.d.ts
+/** 资产传输使用显式编码；省略编码仅兼容旧文本请求。 */
+interface AssetFile {
+  path: string;
+  content: string;
+  encoding?: 'utf8' | 'base64';
+}
+type ImportKind = 'native-preset' | 'native-character' | 'st-preset' | 'st-character' | 'world-book';
+interface ImportChoices {
+  targetId?: string;
+  targetName?: string;
+  overwrite?: boolean;
+  sourceKind?: ImportKind;
+  promptOrderCharacterId?: string;
+}
+interface AssetSummary {
+  sourceName: string;
+  kind: ImportKind;
+  targetId: string;
+  targetName: string;
+  exists: boolean;
+  files: Array<{
+    path: string;
+    bytes: number;
+  }>;
+  configCount: number;
+  warnings: string[];
+}
+interface AssetImportRequest extends ImportChoices {
+  files?: AssetFile[];
+  sourceId?: string;
+  preview?: boolean;
+  expectedSourceDigest?: string;
+  expectedPreviewRevision?: string;
+}
+interface ModuleExportRequest {
+  id: string;
+  mode?: 'definition' | 'zip';
+  preview?: boolean;
+  expectedRevision?: string;
+  memoryChoices?: Record<string, 'include' | 'exclude'>;
+}
+interface ModuleExportResult {
+  id: string;
+  name: string;
+  content: string;
+  encoding?: 'utf8' | 'base64';
+  filename?: string;
+  revision?: string;
+  files?: Array<{
+    path: string;
+    bytes: number;
+  }>;
+  warnings?: string[];
+  blockers?: string[];
+  memoryConflicts?: Array<{
+    id: string;
+    name: string;
+  }>;
+  excludedMemoryCount?: number;
+}
+//#endregion
+//#region src/shared/managed-config-fields.d.ts
+interface ConfigFieldSources {
+  configId: string;
+  fields: Array<{
+    path: string;
+    source: 'preset-param' | 'prompt-config';
+  }>;
+}
+//#endregion
+//#region src/shared/official-orders.d.ts
+/** 一个已求值的区段：`from` / `to` 是该组首末档位的**官方**数值。 */
+interface OfficialOrderSegment {
+  readonly id: string;
+  readonly from: number;
+  readonly to: number;
+}
+/** 下发形状：两层各自一组区段。 */
+interface OfficialOrdersView {
+  readonly sections: readonly OfficialOrderSegment[];
+  readonly contexts: readonly OfficialOrderSegment[];
+}
+//#endregion
+//#region src/shared/skills.d.ts
+interface SkillContentSnapshot {
+  /** Markdown 正文，不含 YAML frontmatter 与分隔线。 */
+  content: string;
+  description: string;
+  /** 当前原始内容的 SHA-256；只用于冲突检查，不保存历史版本。 */
+  revision: string;
+}
+/** 官方技能根分类；数值越小越优先，与官方 rank 一致。 */
+type SkillSourceKind = 'project-dsh' | 'project-agents' | 'custom' | 'user-dsh' | 'user-agents' | 'bundled' | 'other';
+/** 两个官方调用策略键：值就是「该端是否可调用」。 */
+interface SkillInvocation {
+  /** `disable-model-invocation`：false 时模型不可发现、不可加载。 */
+  modelInvocable: boolean;
+  /** `user-invocable`：false 时用户斜杠命令不可加载。 */
+  userInvocable: boolean;
+}
+/** 两端调用策略的目标范围：'model' = 只让模型端不可调用，'user' = 只让用户端不可调用，
+ *  'all' = 两端都不可调用，'none' = 两端都恢复可调用。语义是「点击之后的目标状态」。 */
+type SkillPolicyScope = 'none' | 'model' | 'user' | 'all';
+/** 单端操作不携带另一端的旧快照；显式 scope 供两端批量操作和 TUI 使用。 */
+type SkillPolicyChange = {
+  side: 'model' | 'user';
+  enabled: boolean;
+} | {
+  scope: SkillPolicyScope;
+};
+interface SkillsCatalogSnapshot {
+  skills: SkillCatalogEntry[];
+  /** false 表示观测不完整，不能把未发现解释成不存在。 */
+  complete: boolean;
+}
+/** 目标范围 → 两个键的写入意图（true = 该端可调用）。 */
+declare function invocationForScope(scope: SkillPolicyScope): SkillInvocation;
+/** 当前两端状态 → 范围（两端都可调用时为 'none'）。 */
+declare function scopeOfInvocation(invocation: SkillInvocation): SkillPolicyScope;
+/** 插件技能状态：只剩用户显式引用的技能文件夹（绝对路径，按引用顺序）。
+ *  技能是否可调用由技能文件自己声明，不再进状态文件。 */
+interface SkillsState {
+  version: number;
+  folders: string[];
+}
+/** 清单条目：由插件扫描六类官方技能根得到，是管理面的事实来源。 */
+interface SkillCatalogEntry {
+  /** 稳定键：来源类别 + 来源根 + 目录名。 */
+  id: string;
+  /** frontmatter name（缺失时回退目录名）。 */
+  name: string;
+  description: string;
+  /** 技能目录名（一层扫描，与官方发现规则一致）。 */
+  folder: string;
+  /** 来源根的绝对路径。 */
+  dir: string;
+  source: SkillSourceKind;
+  /** 来源优先级（越小越优先）。 */
+  rank: number;
+  valid: boolean;
+  issue?: string;
+  /** frontmatter 声明的模型端调用策略（唯一事实，缺省为可调用）。 */
+  modelInvocable: boolean;
+  /** frontmatter 声明的用户端调用策略（唯一事实，缺省为可调用）。 */
+  userInvocable: boolean;
+  /** 同名技能中的胜出者 id；本项未胜出时用于提示"被同名技能遮蔽"。 */
+  winnerId?: string;
+  /** 标记文件绝对路径（调用策略的写入目标与身份校验依据）。 */
+  path?: string;
+  /** 同名遮蔽事实：只有注册表确实报了同名技能时才标注；其余条目按文件声明为事实。 */
+  availability?: 'active' | 'shadowed';
+  provider?: string;
+  canSetPolicy?: boolean;
+  /** 普通本地资产可编辑描述和正文；缺描述可修复，损坏的 frontmatter 拒绝读取。 */
+  canEdit?: boolean;
+  canDelete?: boolean;
+  readonlyReason?: string;
+}
+//#endregion
+//#region src/shared/bridge-contract.d.ts
+declare const SETTINGS_BRIDGE_PREFIX = "/api/prompt-tool/settings";
+/** JSON bridge 的统一内存缓冲上限；超过后改用原始文件流端点。 */
+declare const MAX_BRIDGE_BODY_BYTES: number;
+/** 角色卡原始文件流上限；独立于 JSON bridge，避免 base64 膨胀。 */
+declare const MAX_CHARACTER_CARD_STREAM_BYTES: number;
+/** 桥端点路径（相对前缀）。新增端点必须同时登记到契约测试。 */
+declare const BRIDGE_ENDPOINTS: {
+  readonly meta: "/meta";
+  readonly bootstrap: "/bootstrap";
+  readonly describe: "/describe";
+  readonly models: "/models";
+  readonly modelReasoning: "/model-reasoning";
+  readonly mutate: "/mutate";
+  readonly skillsList: "/skills-list";
+  readonly skillPolicy: "/skill-policy";
+  readonly skillRead: "/skill-read";
+  readonly skillWrite: "/skill-write";
+  readonly skillsFolders: "/skills-folders";
+  readonly skillsImport: "/skills-import";
+  readonly skillsImportDirectory: "/skills-import-directory";
+  readonly skillCreate: "/skill-create";
+  readonly skillDelete: "/skill-delete";
+  readonly templates: "/templates";
+  readonly promptConfigs: "/prompt-configs";
+  readonly agentsFile: "/agents-file";
+  readonly instructionsPolicy: "/instructions-policy";
+  readonly moduleContent: "/module-content";
+  readonly importPreset: "/import-preset";
+  readonly paramOverrides: "/param-overrides";
+  readonly triggers: "/triggers";
+  readonly rules: "/rules";
+  readonly persona: "/persona";
+  readonly moduleVariables: "/module-variables";
+  readonly customTools: "/custom-tools";
+  readonly importModulePackage: "/import-module-package";
+  readonly assetUpload: "/asset-upload";
+  readonly assetRelease: "/asset-release";
+  readonly exportModule: "/export-module";
+  readonly moduleDelete: "/module-delete";
+  readonly moduleClone: "/module-clone";
+  readonly moduleDuplicate: "/module-duplicate";
+  readonly moduleOpen: "/module-open";
+  readonly moduleEnable: "/module-enable";
+  readonly moduleConfigOrder: "/module-config-order";
+  readonly charactersImport: "/characters-import";
+  readonly charactersImportStream: "/characters-import-stream";
+  readonly moduleMerge: "/module-merge";
+  readonly moduleUnmerge: "/module-unmerge";
+  readonly subagentToolPolicy: "/subagent-tool-policy";
+  readonly subagentToolPolicyPreview: "/subagent-tool-policy-preview";
+  readonly toolSurface: "/tool-surface";
+  readonly moduleCapability: "/module-capability";
+  readonly worldBookDiagnostics: "/world-book-diagnostics";
+};
+type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
+/** 失败载荷：两端共用。 */
+type BridgeErrorPayload = {
+  ok: false;
+  code?: string;
+  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 一一对应：新增端点必须同时补请求/响应映射，否则编译期断言失败。
+ * 载荷仍统一走 { ok, value } 包装（见 BridgeResult），这里收敛每端的 value 具体形状。
+ */
+interface BridgeRequestMap {
+  meta: undefined;
+  /** 可选 sessionId：服务端据此解析该本地 Agent 的工作区，返回对应指令文件快照。 */
+  bootstrap: {
+    sessionId?: string;
+  } | undefined;
+  describe: undefined;
+  /** 省略 body 或 `refresh: true`（显式刷新越过 10 分钟目录 TTL）。 */
+  models: {
+    refresh?: boolean;
+  } | undefined;
+  modelReasoning: {
+    provider: string;
+    model: string;
+  };
+  mutate: {
+    ops: unknown[];
+    expectedRevision?: number;
+  };
+  /** 技能清单：按会话工作区扫描官方六类技能根，调用策略取自各技能文件的 frontmatter。 */
+  skillsList: {
+    sessionId?: string;
+  } | undefined;
+  /** 调用策略开关：改写该技能 SKILL.md frontmatter 的官方两个键（正文不动）；
+   *  path 必须命中服务端当次扫描的同名条目，否则按陈旧界面拒绝。 */
+  skillPolicy: {
+    name: string;
+    path: string;
+    sessionId?: string;
+  } & SkillPolicyChange;
+  /** 技能描述、Markdown 正文和完整原文摘要；重新扫描同名同路径身份。 */
+  skillRead: {
+    name: string;
+    path: string;
+    sessionId?: string;
+  };
+  /** 仅保存描述与正文，保持其余 frontmatter，并用完整原文摘要拒绝并发覆盖。 */
+  skillWrite: {
+    name: string;
+    path: string;
+    sessionId?: string;
+    content: string;
+    description: string;
+    expectedRevision: string;
+  };
+  /** 添加 / 移除引用的技能文件夹（只记状态，不复制文件）。 */
+  skillsFolders: {
+    folders: string[];
+    sessionId?: string;
+  };
+  /** overwrite 仅包含用户已确认覆盖的技能目录名；缺省时遇到同名返回冲突且不写盘。 */
+  skillsImport: {
+    files: Array<{
+      path: string;
+      content: string;
+    }>;
+    overwrite?: string[];
+  };
+  skillsImportDirectory: {
+    path: string;
+    overwrite?: string[];
+  };
+  skillCreate: {
+    name: string;
+    description: string;
+    content: string;
+  };
+  skillDelete: {
+    name: string;
+    path: string;
+    sessionId?: string;
+  };
+  templates: undefined;
+  /** 可选 sessionId：与 /bootstrap 同源解析当前工作区（单读与聚合读取必须一致）。 */
+  promptConfigs: {
+    sessionId?: string;
+  } | undefined;
+  /**
+   * 单文件写盘：fileId/contextId 必须命中服务端当次解析的白名单；
+   * expectedRevision 是客户端已读取的字节版本（乐观并发控制，服务端重读校验）。
+   */
+  agentsFile: {
+    sessionId?: string;
+    contextId: string;
+    fileId: string;
+    expectedRevision: string | null;
+    content: string;
+  };
+  /**
+   * 指令文件卡策略（独立存储，默认禁用）：省略 `policy` = 读取；
+   * 写入必须带读取时的 `expectedRevision`（文件缺失为 null）。
+   */
+  /** 逐文件启停/名称；无 policy 时读取，写入仍校验原始字节版本。 */
+  instructionsPolicy: {
+    policy?: InstructionPolicyPatch;
+    expectedRevision?: string | null;
+  } | undefined;
+  moduleContent: undefined;
+  importPreset: {
+    contents: Array<{
+      scope: 'preset' | 'agents';
+      content: string;
+    }>;
+    expectedModuleId?: string;
+  };
+  paramOverrides: {
+    overrides?: Record<string, unknown>;
+    promptConfigs?: unknown[];
+    rebuild?: boolean;
+    expectedModuleId?: string;
+  };
+  triggers: {
+    expectedModuleId: string;
+    triggers?: unknown[];
+    expectedRevision?: string;
+    validateOnly?: boolean;
+  };
+  rules: RulesRequest;
+  /** 顶层 persona 段读写（官方 @deepseek-ai/dsh-persona 行 config 同构）；省略 persona 键 = 读取。 */
+  persona: {
+    persona?: PersonaSpec | null;
+    expectedModuleId?: string;
+  } | undefined;
+  moduleVariables: {
+    variables?: Record<string, string>;
+    enabled?: boolean;
+    expectedModuleId?: string;
+    expectedRevisions?: Partial<RuleRevisions>;
+    refreshOnly?: boolean;
+  };
+  customTools: {
+    customTools?: unknown[];
+    expectedModuleId?: string;
+  } | undefined;
+  /**
+   * 模块包导入（原生/ST/PNG/ZIP）。`preview: true` 只转换并返回报告，不写目标；
+   * 提交必须携带 expectedSourceDigest 和 expectedPreviewRevision，服务端重算并拒绝过期预览。
+   * `expectedPreviewRevision` 是预览返回的版本凭据：绑定文件、实际选组、转换器版本与
+   * 目标身份（含目标当前内容），服务端提交时重算，不符返回 409 且零写盘。
+   * `promptOrderCharacterId` 用于多顺序组包时显式选择：预览缺省时先返回候选
+   * （`state: 'needs-order-selection'`），提交时仍无法明确对应则拒绝。
+   * 上述参数只接受声明的类型，其它类型一律 400（见 docs/SillyTavern.md）。
+   */
+  importModulePackage: AssetImportRequest;
+  assetUpload: undefined;
+  assetRelease: {
+    sourceId: string;
+  };
+  exportModule: ModuleExportRequest;
+  moduleDelete: {
+    id: string;
+  };
+  moduleClone: {
+    id: string;
+    autoSuffix?: boolean;
+  };
+  moduleDuplicate: {
+    id: string;
+  };
+  moduleOpen: {
+    id: string;
+  };
+  moduleEnable: {
+    id: string;
+    enabled: boolean;
+  };
+  moduleConfigOrder: {
+    moduleId: string;
+  } | {
+    moduleId?: string;
+    entries: ModuleConfigIdentity[];
+    expectedRevision: string;
+  } | undefined;
+  /** 角色卡来源导入为普通模块；预览只读，提交与模块安装共用版本边界。 */
+  charactersImport: AssetImportRequest;
+  charactersImportStream: undefined;
+  moduleMerge: {
+    id: string;
+  };
+  moduleUnmerge: {
+    id: string;
+  };
+  subagentToolPolicy: {
+    policy?: unknown;
+    expectedModuleId?: string;
+  } | undefined;
+  subagentToolPolicyPreview: {
+    tool?: string;
+    description?: string;
+    prompt?: string;
+    tool_profile?: string;
+    character_id?: string;
+    task_type?: string;
+    additional_tools?: string[];
+    restrict_tools?: string[];
+  };
+  toolSurface: {
+    sessionId: string;
+    presetId?: never;
+  } | {
+    presetId: string;
+    sessionId?: never;
+  };
+  moduleCapability: ({
+    action: 'create' | 'remove';
+    capabilityId: string;
+  } | {
+    action: 'create-recipe';
+    recipeId: string;
+  }) & {
+    expectedModuleId?: string;
+  };
+  /** 只读世界书诊断：只回当前授权会话最近一次选择的观测记录。 */
+  worldBookDiagnostics: {
+    sessionId?: string;
+  } | undefined;
+}
+/** settings descriptor 的跨端最小结构。 */
+interface BridgeSettingsView {
+  ns: string;
+  value: unknown;
+  base?: unknown;
+  revision: number;
+}
+/**
+ * 一条 provider/model 路由的推理档位元数据（官方模型元数据的展示子集）。
+ *
+ * `known` 区分「查过且该路由不提供档位」与「尚未取得元数据」：前者 UI 必须隐藏档位
+ * 选择而不是拿固定列表伪造能力；后者只是还没查到，不能据此判断模型没有推理能力。
+ * 目录/元数据只作展示，不是授权白名单——查询失败不影响保存任意模型 id。
+ */
+interface ModelReasoningView {
+  known: boolean;
+  efforts: Array<{
+    id: string;
+    name: string;
+    description?: string;
+  }>;
+  defaultEffort?: string;
+}
+/**
+ * SillyTavern 转换报告（ST-03）：host 在真实转换路径上生成的**只读派生元数据**。
+ * 不落盘进 preset.yml、不进入模型上下文，也不是写入凭证——提交仍以本次上传文件重算的
+ * `sourceDigest` 为准；预览返回的摘要不能替代后端对目标/类型/大小的既有校验。
+ */
+type StConversionClass = 'equivalent' | 'degraded' | 'unsupported' | 'excluded';
+interface StConversionEntryReport {
+  /** 来源条目身份：上传文件显示名内的原 identifier/uid（不含绝对路径）。 */
+  sourceId: string;
+  /** 来源在文件内的序号（prompts 数组下标或世界书 entries 序号）。 */
+  sourceIndex: number;
+  /** 生成的目标配置 id（被排除的条目没有目标）。多文件合并后重写为**最终** id。 */
+  targetId?: string;
+  /** 同源生成的 promptConfigs 下标：合并重命名时用它把 targetId 关联到最终配置。 */
+  targetIndex?: number;
+  /** 来源显示名（多文件合并时用于区分条目来自哪个上传文件）。 */
+  sourceName?: string;
+  /** 来源在本次合并中的序号（0 起）。 */
+  sourceFileIndex?: number;
+  layer?: string;
+  order?: number;
+  role?: string;
+  position?: string;
+  classification: StConversionClass;
+  /** 稳定原因码（如 depth-collapsed / system-role-downgrade / marker-dropped）。 */
+  codes: string[];
+}
+interface StConversionDiagnostic {
+  code: string;
+  severity: 'warning' | 'info';
+  message: string;
+  /** 源身份定位：来源条目 id（与 targetId 分开表达，不混用同一字段）。 */
+  entryId?: string;
+  /** 目标身份定位：生成/合并后的最终配置 id（源条目被排除时缺省）。 */
+  targetId?: string;
+  field?: string;
+}
+interface StConversionReport {
+  /** 转换器版本：解释本次生成使用了哪一版语义。 */
+  converter: string;
+  /** 来源显示名（上传文件名，不含绝对路径）。 */
+  sourceName: string;
+  /** prompt_order 分组；`selected` 标记本次实际采用的组。 */
+  orderGroups: Array<{
+    characterId: string;
+    selected: boolean;
+    entries: number;
+  }>;
+  entries: StConversionEntryReport[];
+  diagnostics: StConversionDiagnostic[];
+  summary: {
+    /** 来源条目总数（prompts + 世界书条目 + 角色卡正文段）。 */
+    inputs: number;
+    /** 生成的 promptConfigs 数量。 */
+    converted: number;
+    /** 生成但被禁用的条目数。 */
+    disabled: number;
+    excluded: number;
+    unsupported: number;
+    degraded: number;
+    /** 需要用户确认的诊断数（warning 级）。 */
+    needsReview: number;
+  };
+  /** 记录超出上限时为 true：只截断展示，不影响转换结果。 */
+  truncated?: boolean;
+}
+/** 世界书入选/落选诊断记录（只读派生数据，由引擎真实求值路径产生）。 */
+interface WorldBookDiagnosticRecord {
+  /** 配置 id（`lore-<来源条目>`）。 */
+  id: string;
+  stage: 'excluded' | 'rejected' | 'candidate' | 'selected' | 'committed';
+  /** 稳定原因码：disabled / delay / cooldown / recursion / primary-miss / secondary-miss /
+   *  probability / group-lost / group-occupied / match-error / sticky / constant / key-match /
+   *  ungrouped / group-winner / injected。 */
+  reason: string;
+  [key: string]: unknown;
+}
+/** 顺序组候选：多 prompt_order 组需要用户先选择时的有界选项（不含转换结果）。 */
+interface StOrderGroupCandidate {
+  characterId: string;
+  entries: number;
+}
+/** 导入预览状态：`ready` 才有报告与写入凭据；候选状态不得启用确认。 */
+type ImportPreviewState = 'ready' | 'needs-order-selection' | 'needs-kind-selection';
+/** 引擎实际消费的实例参数；只下发可序列化约束，未知扩展键仍由原配置保留。 */
+interface LayerParamContract {
+  type: 'string' | 'boolean' | 'object' | 'enum';
+  values?: readonly string[];
+}
+/** 声明编辑目录由引擎提供；示例同时经过声明编译器验证。 */
+interface TriggerEditorMeta {
+  predicates: Array<{
+    kind: string;
+    example: Record<string, unknown>;
+  }>;
+  actions: Array<{
+    kind: string;
+    example: Record<string, unknown>;
+    channel: string;
+    phase: string;
+    supportsWhen: boolean;
+  }>;
+  composites: string[];
+  waterfallPositions: string[];
+}
+interface LayerContract {
+  strategies: readonly string[];
+  subjects: readonly string[];
+  content: 'text' | 'request' | 'stream' | 'tool-result' | 'subagent-result';
+  variables: boolean;
+  messageMetadata: boolean;
+  params: Readonly<Record<string, LayerParamContract>>;
+}
+/**
+ * /meta 与 /bootstrap 的 meta 段下发的层契约：九层顺序 + 编辑组主归属。
+ * 只含可序列化白名单字段（组 id / displayLayer / relatedLayers / hook）：
+ * 不含路径、行级配置、校验函数或服务实例 —— 展示归属不扩大写权限。
+ * 插件与内置引擎同步发布，这些字段由当前 bridge 完整下发。
+ */
+interface EngineMetaLayerContract {
+  /** 九层固定顺序（引擎 LAYER_ORDER，host 不另写一份）。 */
+  layerOrder: readonly EngineLayer[];
+  /** 编辑组主归属总表（能力组 id = 能力 id）；前端据此组织九层卡片。 */
+  editorGroups: readonly EngineEditorGroup[];
+  /** 每层真实可编辑的行为契约，来自独立可分发的 engine/schema.mjs。 */
+  layerContracts: Record<EngineLayer, LayerContract>;
+}
+/** 物化配置的只读来源；与配置一同读回，不能作为写入字段或授权。 */
+interface PromptConfigSourceView {
+  fieldSources?: ConfigFieldSources;
+  /** 只读排序投影；不能作为客户端提供的写盘序号。 */
+  sequence?: number;
+}
+/** 端点级响应 value 契约（value 字段形状；扩展字段仍以 value 旁可选字段出现）。 */
+interface BridgeValueMap {
+  /**
+   * `/meta` 与 `/bootstrap` 的 meta 段：层契约 + 官方装配刻度。
+   * `officialOrders` 缺席表示服务降级或官方档位名不匹配，消费方必须退化（不渲染刻度）。
+   */
+  meta: {
+    meta: Record<string, unknown> & EngineMetaLayerContract & {
+      officialOrders?: OfficialOrdersView;
+    };
+  };
+  bootstrap: BridgeSettingsView;
+  describe: BridgeSettingsView;
+  models: {
+    modelCatalog: Record<string, string[]>;
+  };
+  modelReasoning: {
+    reasoning: ModelReasoningView;
+  };
+  mutate: BridgeSettingsView;
+  /** 技能清单 + 引用目录 + 技能根（客户端据此渲染来源分组与调用策略）。 */
+  skillsList: SkillsCatalogSnapshot & {
+    folders: string[];
+    roots: string[];
+  };
+  skillPolicy: SkillsCatalogSnapshot;
+  skillRead: SkillContentSnapshot;
+  skillWrite: SkillContentSnapshot;
+  skillsFolders: SkillsCatalogSnapshot & {
+    folders: string[];
+  };
+  skillsImport: {
+    path: string;
+    count: number;
+    overwritten: number;
+    warning?: string;
+  };
+  skillCreate: {
+    id: string;
+    path: string;
+  };
+  skillDelete: {
+    id: string;
+    path: string;
+  };
+  skillsImportDirectory: {
+    path: string;
+    count: number;
+    overwritten: number;
+    warning?: string;
+  };
+  templates: {
+    templates?: unknown[];
+    toolTemplates?: unknown[];
+  };
+  promptConfigs: {
+    promptConfigs: Array<Record<string, unknown> & PromptConfigSourceView>;
+    instructions?: InstructionsSnapshot;
+  };
+  agentsFile: InstructionFileWriteResult;
+  instructionsPolicy: {
+    policy: InstructionPolicy;
+    revision: string | null;
+    exists: boolean;
+    error?: string;
+  };
+  moduleContent: Record<string, unknown>;
+  importPreset: {
+    scopes: Array<'preset' | 'agents'>;
+  };
+  /** 参数/提示词配置只保存当前模块，不同步宿主全局默认模型。 */
+  paramOverrides: {
+    overrides?: Record<string, unknown>;
+    promptConfigs?: unknown[];
+  };
+  triggers: {
+    triggers: unknown[];
+    revision: string;
+    meta: TriggerEditorMeta;
+  };
+  rules: RulesSnapshot;
+  persona: {
+    persona: PersonaSpec | null;
+  };
+  moduleVariables: {
+    variables: Record<string, string>;
+    enabled: boolean;
+    revisions: RuleRevisions;
+    persisted?: boolean;
+    publicationPending?: boolean;
+    publicationError?: string;
+  };
+  customTools: {
+    customTools?: unknown[];
+  };
+  importModulePackage: {
+    id?: string;
+    backupPath?: string;
+    preview?: boolean;
+    state?: ImportPreviewState;
+    /** 候选状态下的歧义来源文件显示名（不含绝对路径）。 */
+    sourceName?: string;
+    candidates?: StOrderGroupCandidate[];
+    sourceDigest?: string;
+    previewRevision?: string;
+    report?: StConversionReport;
+    summary?: AssetSummary;
+    kinds?: ImportKind[];
+  };
+  assetUpload: {
+    sourceId: string;
+    name: string;
+    bytes: number;
+  };
+  assetRelease: {
+    released: boolean;
+  };
+  exportModule: ModuleExportResult;
+  moduleDelete: {
+    id: string;
+  };
+  moduleClone: {
+    id: string;
+  };
+  moduleDuplicate: {
+    id: string;
+  };
+  moduleOpen: {
+    path: string;
+  };
+  moduleEnable: {
+    enabled: string[];
+  };
+  moduleConfigOrder: ModuleConfigOrderSnapshot;
+  charactersImport: {
+    id?: string;
+    name?: string;
+    preview?: boolean;
+    state?: ImportPreviewState;
+    candidates?: StOrderGroupCandidate[];
+    sourceDigest?: string;
+    previewRevision?: string;
+    report?: StConversionReport;
+    summary?: AssetSummary;
+    kinds?: ImportKind[];
+  };
+  charactersImportStream: {
+    id: string;
+    name: string;
+  };
+  moduleMerge: {
+    id: string;
+    count: number;
+  };
+  moduleUnmerge: {
+    id: string;
+    count: number;
+  };
+  subagentToolPolicy: {
+    policy: unknown;
+    defaultProfile?: string;
+    errors?: string[];
+  };
+  subagentToolPolicyPreview: {
+    result: unknown;
+    errors?: string[];
+  };
+  toolSurface: {
+    source: 'session' | 'preset';
+    sessionId?: string;
+    presetId?: string;
+    tools: Array<{
+      name: string;
+      description: string;
+    }>;
+  };
+  moduleCapability: {
+    changed: boolean;
+    addedModules?: string[];
+    removedModules?: string[];
+    capabilityIds: string[];
+  };
+  /** 只读世界书诊断：只回当前授权会话最近一次选择的观测记录（读取不重新求值）。 */
+  worldBookDiagnostics: {
+    records: WorldBookDiagnosticRecord[];
+    truncated: boolean;
+    step: number;
+    evaluated: boolean;
+  };
+}
+//#endregion
 //#region src/runtime/models.d.ts
 /**
  * 官方子代理 seam 的类型锚点：本插件只读 `list()` / `getProvider()` 并显式传参，
@@ -547,6 +1639,243 @@ declare class ModuleLayerSettingsError extends Error {
 /** 仅消费当前 layerSettings；其余段作为未知字段留存，不投影为运行时参数。 */
 declare function readModuleLayerSettings(source: unknown): Record<string, unknown>;
 //#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
+/**
+ * 模块目录确实存在于本插件存储根（身份判定与官方登记状态无关）。
+ *
+ * 启用表过滤、工具写入目标、TUI 目标共用这一条判据：本插件管理的模块 = 存储根里含
+ * `module.yml` 的目录，与「宿主有没有把它登记成官方预设」是两回事。
+ */
+declare function moduleDirExists(root: string, id: string): boolean;
+interface ModuleSpec {
+  id: string;
+  name: string;
+  /** 官方预设列表顺序；省略时由宿主排序。 */
+  order?: number;
+  /** 预设说明（官方用户预设格式元数据；列表展示用，可选）。 */
+  description?: string;
+  version: string;
+  engineCompat: string;
+  meta?: Record<string, unknown>;
+  content?: {
+    presetText?: string;
+    agentsText?: string;
+  };
+  /** 模块清单(参数文件决定组合内容):按序装配 source/local 与 library 中的唯一模块。 */
+  modules?: string[];
+  /** 手写组合：内联文本或组合清单名。 */
+  composition?: string;
+  /** 内部运行时平铺适配面；磁盘上的同名段不参与运行参数。 */
+  params?: Record<string, unknown>;
+  /** 共享引擎参数按编辑组的主归属插入点存储；规则实例仍拥有各自 params。 */
+  layerSettings?: Record<string, Record<string, unknown>>;
+  /** 顶层人设段（官方 @deepseek-ai/dsh-persona 行同构）：prefix/suffix/complete/includeRuntimeContext。 */
+  persona?: PersonaSpec;
+  /** 模块级模板变量（{{key}} 插值源；与 layerSettings 分离，顶层 variables 段）。 */
+  variables?: Record<string, string>;
+  /** 自定义工具定义（tool-config-engine 渲染进 custom-tools/ 后运行时注册）。 */
+  customTools?: unknown[];
+  /** 子代理实例级工具策略（subagentToolPolicy 顶层领域段；缺省 = 官方 delegation 行为）。 */
+  subagentToolPolicy?: Record<string, unknown>;
+  /** @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>;
+}
+/**
+ * 从模块 module.yml 的 modules 清单移除一个模块 id（YAML Document 保留注释
+ * 与其余字段）。返回是否发生修改；文件缺失或没有该模块时返回 false。
+ */
+declare function removeModuleCapabilityDeclaration(dir: string, moduleId: string): boolean;
+/** 加载某个模块模板的单一参数文件 modules/<name>/module.yml。 */
+declare function loadModuleSpec(dir: string): ModuleSpec;
+/** 模块根：本插件的存储根（~/.dsh/.prompt-tool），导入/新建/种子化的模块都放这里。 */
+declare function userModulesDir(): string;
+/**
+ * 解析模块模板目录：当前模块根优先，包内模板回退；不读取其他部署根的同名模块。
+ * 目录名与声明的 module.yml id 一致；不扫描其他目录的 id 别名。
+ */
+declare function resolveModuleDir(template: string, moduleRoot?: string): string;
+/** 本插件模块清单；所有目录按同一身份与组合源规则列举。 */
+declare function listModules(moduleRoot?: string): Array<{
+  id: string;
+  name: string;
+  user: boolean;
+  renderable: boolean;
+  description?: string;
+  meta?: Record<string, unknown>;
+}>;
+/** 插件目录模板清单（「新建」选择器与首次种子化数据源；不直接出现在模块列表）。 */
+declare function listBuiltinTemplates(): Array<{
+  id: string;
+  name: string;
+}>;
+/** 按包内同名目录补建缺失的内置模块；已有目录的定义、生成物和资源保持原样。 */
+declare function ensureModuleSeed(root?: string): {
+  created: string[];
+};
+/** 从包内同名目录复制模块；autoSuffix=true 时递增目录名并同步定义身份。 */
+declare function cloneBuiltinModule(id: string, autoSuffix?: boolean, moduleRoot?: string): {
+  ok: true;
+  id: string;
+} | {
+  ok: false;
+  message: string;
+};
+/**
+ * 保存部署能力参数与模板变量；规则写入只走 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, expectedRevisions?: Partial<RuleRevisions>): void;
+/**
+ * 保存激活模块的顶层 persona 段（官方 `@deepseek-ai/dsh-persona` 行 config 同构）。
+ * null = 删除该段（回落宿主部署人设）；默认值不落键（见 personaRowConfig）。
+ */
+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 removeUserModule(id: string, moduleRoot?: string): {
+  ok: true;
+} | {
+  ok: false;
+  message: string;
+};
+/** 当前 layerSettings 与显式运行参数合并；不从旧磁盘 params 段回退取值。 */
+declare function resolveModuleParams(spec: ModuleSpec, runtime: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 参数桥：params 扁平键 → 引擎模块行 config 对象（取代旧 __TOKEN__ 文本渲染）。
+ *
+ * 原则：
+ *  - 未声明的键不合并（composition 行默认 / 引擎默认生效），与旧"空值删行"语义等价；
+ *  - 值类型直达（布尔/数字/数组不再字符串化再解析）；
+ *  - 合并优先级：参数桥（UI/基础层）> moduleConfigs（模板/ST 行级直写）> 行默认。
+ * 模型路由/委派参数统一扁平键（modelProvider/subagentModelProvider/maxDepth 等），
+ * 与官方 AgentOptions{provider,model} / maxDepth 对齐。
+ */
+declare function buildModuleConfigsFromParams(params: Record<string, unknown>, options?: {
+  subagentPolicyEnabled?: boolean;
+}): Record<string, Record<string, unknown>>;
+/**
+ * 行级 config 合并:仅支持 map 型 config 浅合并;
+ * 数组型 config(如 delegation 组)按子行 id 嵌套合并;未声明模块原样保留。
+ * 未声明 configs 时返回原文(零开销);parseDocument 往返保留注释。
+ * 本函数是参数桥产物落位组合行的唯一机制(含 delegation 组子行嵌套),不是模块覆盖通道。
+ */
+declare function applyModuleConfigs(raw: string, configs: Record<string, Record<string, unknown>> | undefined): string;
+/**
+ * 解析模块的模块事实，供 UI 卡片存在性和受控创建共用。
+ * 显式模块及当前参数/策略所需的装配是可编辑插件能力；官方组合 row 仅保留为运行事实。
+ */
+declare function resolveModuleFacts(spec: ModuleSpec, templateDir?: string, editable?: boolean): ModuleFacts;
+type ModuleCapabilityCreateRequest = {
+  action: 'create';
+  capabilityId: string;
+} | {
+  action: 'create-recipe';
+  recipeId: string;
+};
+interface ModuleCapabilityCreateResult {
+  changed: boolean;
+  addedModules: string[];
+  capabilityIds: string[];
+}
+interface ModuleCapabilityRemoveResult {
+  changed: boolean;
+  removedModules: string[];
+  capabilityIds: string[];
+}
+/** 在内存候选文档中展开能力/recipe，校验成功后一次原子替换 module.yml。 */
+declare function createModuleCapability(moduleDir: string, request: ModuleCapabilityCreateRequest): ModuleCapabilityCreateResult;
+/** 删除能力：模块声明、顶层数据段，以及该能力的**显式参数与行配置**一起移除。
+ *  参数在 ⇒ 装配在（见 impliedModulesFromParams）：留下参数会让移除立刻被隐含装配拉回来，
+ *  所以"移除能力"必须是完整移除。未登记参数、其他能力的数据与未知字段一律不动。 */
+declare function removeModuleCapability(moduleDir: string, capabilityId: string): ModuleCapabilityRemoveResult;
+/**
+ * 模块组合渲染完整链路:模块装配 → 参数桥(moduleConfigs + params)行级合并。
+ * 合并优先级:参数桥(params/UI 基础层) > moduleConfigs(模板/ST 行级直写) > 行默认。
+ * moduleConfigs 仅补充参数桥未覆盖的行级 config(如 ST 导入的 tool-web.fetch),
+ * 不再锁定覆盖 UI 可管理参数(旧作者锁定语义已移除)。
+ */
+declare function renderComposition(spec: ModuleSpec, runtime: Record<string, unknown>, templateDir?: string): string;
+//#endregion
+//#region src/host/sillytavern.d.ts
+/** ST marker prompts（marker: true）：content 不发送给模型（仅标记注入位置，ST
+ *  以运行时内容填充该位置）；SPresetSettings 是旧版 ST 的预设设置 dump（正则
+ *  脚本/扩展配置/ToolBindings，动辄数百 KB）。两者转换时整体丢弃并计数进
+ *  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 mergeStModules(specs: ModuleSpec[]): ModuleSpec;
+/** 转换选项：多 prompt_order 分组时显式选择来源角色，避免照搬「默认任取首组」。 */
+interface StConversionOptions {
+  characterId?: string;
+}
+/** prompt_order 分组候选：预览选组 UI 与实际转换消费同一份事实。 */
+interface StOrderGroupSummary {
+  characterId: string;
+  entries: number;
+}
+/** SillyTavern JSON 预设卡片 → 本项目 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 stModuleId(baseName: string): string;
+//#endregion
 //#region src/host/worldbook.d.ts
 type WorldBookEntry = Record<string, unknown>;
 /** buildWorldBookEntry 输入（两通道共用：ST 导入转换与模型 world_book_upsert 工具）。 */
@@ -581,6 +1910,51 @@ declare function upsertWorldBookEntry(moduleDir: string, entry: WorldBookEntry):
 /** 删除一条世界书条目；不存在抛错。返回删除后条目总数。 */
 declare function deleteWorldBookEntry(moduleDir: string, id: string): number;
 //#endregion
+//#region src/host/import-source.d.ts
+type PreparedImport = {
+  state: 'ready';
+  kind: ImportKind;
+  spec: ModuleSpec;
+  yaml: string;
+  files: AssetFile[];
+  sourceName: string;
+  sourceDigest: string;
+  report?: StConversionReport;
+  avatar?: Buffer;
+  sourceText?: string;
+} | {
+  state: 'needs-order-selection';
+  candidates: StOrderGroupSummary[];
+  sourceName: string;
+} | {
+  state: 'needs-kind-selection';
+  kinds: ImportKind[];
+  sourceName: string;
+};
+/** 字节集合 → 同一规范化候选；没有目标写入和静默的未知 JSON 回退。 */
+declare function prepareImport(input: AssetFile[], target: 'preset' | 'character', choices?: ImportChoices): PreparedImport;
+//#endregion
+//#region src/host/module-package.d.ts
+declare function expandModuleSource(input: AssetFile[]): Promise<AssetFile[]>;
+type ReadyImport = Extract<ReturnType<typeof prepareImport>, {
+  state: 'ready';
+}>;
+declare function moduleImportPreview(root: string, files: AssetFile[], request: AssetImportRequest): {
+  prepared: ReadyImport;
+  summary: AssetSummary;
+  sourceDigest: string;
+  previewRevision: string;
+} | Exclude<ReturnType<typeof prepareImport>, {
+  state: 'ready';
+}>;
+declare function installModulePackage(root: string, files: AssetFile[], request: AssetImportRequest, options?: {
+  preserveAssets?: boolean;
+}): Promise<{
+  id: string;
+  backupPath?: string;
+}>;
+declare function exportModulePackage(root: string, request: ModuleExportRequest): Promise<ModuleExportResult>;
+//#endregion
 //#region src/web-surface.d.ts
 /** 从 loader 根 Include 的 baseUrl 推导 profile 目录。 */
 declare function resolveProfileDir(ctx: Context): string | undefined;
@@ -591,6 +1965,11 @@ declare function ensureWebSurface(ctx: Context, warn: (message: string) => void)
  */
 declare function scheduleWebSurfaceRepair(ctx: Context, warn: (message: string) => void): void;
 //#endregion
+//#region src/host/paths.d.ts
+/** 用户技能根：官方 `user-dsh` 技能根，也是本插件创建、复制导入、回收站与内置技能种子化的落点。
+ *  内置技能按「只补缺失」补建（见 `ensureSkillSeed`）：已有目录的正文、资源与调用策略保持原样。 */
+declare const USER_SKILLS_DIR: string;
+//#endregion
 //#region src/host/skills-import.d.ts
 interface SkillsImportFile {
   path?: unknown;