dsh-plugin-prompt-tool 0.4.2 → 0.6.0

package/lib/index.d.mts

@@ -1,45 +1,38 @@
+import { n as PromptConfigFile, r as PromptConfigSpec } from "./prompt-configs-B4vH09wx.mjs";
+import { SettingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "@deepseek-ai/schemastery";
 import { Context } from "@deepseek-ai/cordis";
-//#region src/index.d.ts
-declare const name = "prompt-tool";
-declare const inject: string[];
+//#region src/shared/param-keys.d.ts
+/**
+ * 引擎行为参数键（按预设存储：激活预设 preset.yml 的 params + promptConfigs）。
+ * 不进 Config schema、不进 settings namespace——每预设一份，随预设走（官方范式：
+ * Config = 部署轴，引擎行为在预设文件）。
+ *
+ * 这些键在 UI 有专门编辑入口（模型设置 / 工具与深度 / 开关），writePreset 把
+ * 预设级 params 合并进每条 promptConfig 的 params 时排除——「params（高级参数
+ * JSON）」框只保留内容变量与配置自身策略参数，避免 UI 已管理的参数冗余回写。
+ * 放 shared：host（write-preset）与 config/settings-bridge 共用，单一来源。
+ */
+declare const PARAM_KEYS: ReadonlySet<string>;
+//#endregion
+//#region src/config.d.ts
 interface Config {
-  /** 可选：覆盖 preset.md 文本（默认读文件）。 */
-  text: string;
-  /** 可选：覆盖 AGENTS.md 文本（默认读文件）。 */
-  agentsText: string;
   /** 是否用 AGENTS.md 内容替换本地 instruction-hint 的默认提示文本（默认关闭）。 */
   injectAgentsPrompt: boolean;
   /** 是否写 ~/.dsh/AGENTS.md（默认 true）。 */
   writeAgents: boolean;
   /** 是否生成锚定注入 preset（默认 true）。 */
   writePreset: boolean;
-  /** 锚定层：we 锚定确认后是否注入 preset.md（默认 true）。 */
-  injectPrompt: boolean;
+  /** 预设模板名（默认 anchored；其他模板时 anchored 专属 UI 可隐藏）。 */
+  presetTemplate: string;
   /** 以技能目录名为键的逐技能开关，缺省视为 true。 */
   skillSwitches: Record<string, boolean>;
-  /** 首轮近距离锚定开关（默认关闭）。 */
-  anchorFirstTurn: boolean;
-  /** 自定义锚点文本；anchorCustom=true 时固定使用。 */
-  anchorText: string;
-  /** 自定义锚点开关：true 固定使用 anchorText；false 按任务自动选择。 */
-  anchorCustom: boolean;
-  /** 自定义每轮引导文本；guideCustom=true 时固定使用。 */
-  guideText: string;
-  /** 自定义每轮引导开关：true 固定使用 guideText；false 按任务自动选择。 */
-  guideCustom: boolean;
-  /** 子代理固定 Flash 模型：开启时给 subagent/subagent_fork 行加固定 Flash 路由；关闭时子代理继承主会话路由，目录全量放行。 */
-  subagentFlash: boolean;
-  /** 子代理 Flash 路由 provider（默认 deepseek-official）。 */
-  subagentFlashProvider: string;
-  /** 子代理 Flash 模型名（默认 deepseek-v4-flash）。 */
-  subagentFlashModel: string;
-  /** 首轮输出封顶；0 或未设置 = 不设封顶（本项目默认），正整数 = 请求 #1 的 maxTokens。 */
-  bootstrapMaxTokens: number;
-  /** 使用 PTC 模式：默认开启——晋升后把 wire 切换为 Code Mode（单一 run_code，完整插件工具经生成 SDK 调用）；关闭时晋升后恢复原生完整工具目录。 */
-  usePtcMode: boolean;
-  /** 用户自定义技能目录；空 = 自动使用当前 profile 下的 skills/ 副本。 */
-  skillsDir: string;
+  /** 技能展示顺序（目录名数组）：排前面的技能 rank 更小，模型最先看到。 */
+  skillOrder: string[];
+  /** 用户自定义技能目录列表（按添加顺序，首个目录优先级最高）；空 = 自动使用当前 profile 下的 skills/ 副本。 */
+  skillsDirs: string[];
+  /** 旧版单值技能目录（仅读取迁移用，新版本统一写回 skillsDirs）。 */
+  skillsDir?: string;
   /** 技能候选排序基数，技能目录内按下标递增。 */
   skillRankBase: number;
   /** 常驻规则文件目标路径。 */
@@ -52,37 +45,523 @@ interface Config {
   fallbackText: string;
 }
 declare const Config: z<Config>;
+interface SkillEntry {
+  /** 来源技能目录的绝对路径（多目录合并后用于修复定位与归属展示）。 */
+  dir: string;
+  folder: string;
+  file: string;
+  name: string;
+  description: string;
+  whenToUse?: string;
+  metadata?: Record<string, unknown>;
+  body: string;
+  /** 是否通过官方 dsh-skill 候选校验；false 时只进管理界面，不注册给模型。 */
+  valid: boolean;
+  /** invalid 条目的原因（可为空）。 */
+  issue?: string;
+  /** 通过符号链接/junction 挂入的目录（删除类操作需谨慎）。 */
+  linked?: boolean;
+  /** 官方调用策略：disable-model-invocation: true 时模型不可调用。 */
+  modelInvocable: boolean;
+  /** 官方调用策略：user-invocable: false 时用户不可调用。 */
+  userInvocable: boolean;
+}
 interface SkillCatalogEntry {
   folder: string;
   name: string;
   description: string;
+  /** 是否通过官方 dsh-skill 候选校验；false 时 UI 灰显并展示 issue。 */
+  valid: boolean;
+  /** 来源技能目录绝对路径（多目录管理：修复定位 / 归属展示 / 目录计数）。 */
+  dir?: string;
+  /** 同名标记：多个目录存在相同 folder 时全部保留，UI 标注同名。 */
+  duplicate?: boolean;
+  /** invalid 条目的原因。 */
+  issue?: string;
+  /** 通过符号链接/junction 挂入的目录（删除类操作需谨慎）。 */
+  linked?: boolean;
+  modelInvocable: boolean;
+  userInvocable: boolean;
 }
 interface PromptSettings {
-  promptText: string;
-  promptPath: string;
-  agentsText: string;
-  agentsPath: string;
   injectAgentsPrompt: boolean;
-  anchorFirstTurn: boolean;
-  anchorText: string;
-  anchorCustom: boolean;
+  /** 运行时检测：是否检测到任何模型服务商（不写入 settings）。 */
+  modelsAvailable: boolean;
+  skillSwitches: Record<string, boolean>;
+  /** 技能展示顺序（目录名数组）。 */
+  skillOrder: string[];
+  skillCatalog: SkillCatalogEntry[];
+  /** 用户自定义技能目录列表（按添加顺序）；空 = 自动使用 profile skills 副本。 */
+  skillsDirs: string[];
+  /** 当前实际生效的技能目录列表（空配置 = [profile 副本路径]）。 */
+  activeSkillsDirs: string[];
+  /** 生效目录存在性（path → 目录是否存在，供 UI 状态徽章）。 */
+  skillsDirExists: Record<string, boolean>;
+  /** 技能候选排序基数。 */
+  skillRankBase: number;
+  /** 常驻规则文件目标路径。 */
+  residentAgentsPath: string;
+  /** 生成的 agent preset 目录。 */
+  presetDir: string;
+  /** 生成 preset 的显示顺序。 */
+  presetOrder: number;
+  /** preset.md 缺失或不可读时使用的文本。 */
+  fallbackText: string;
+  writeAgents: boolean;
+  writePreset: boolean;
+  presetTemplate: string;
+}
+declare const PromptSettingsSchema: z<PromptSettings>;
+//#endregion
+//#region src/host/write-preset.d.ts
+interface WritePresetOptions {
+  firstTurnAnchor: boolean;
+  firstTurnText: string;
+  firstTurnCustom: boolean;
   guideText: string;
   guideCustom: boolean;
-  subagentFlash: boolean;
+  injectPrompt: boolean;
+  modelProvider: string;
+  modelName: string;
+  /** 子代理固定模型路由 provider（agentOptions 注入 tool-subagent）。 */
+  subagentModelProvider: string;
+  /** 子代理固定模型名。 */
+  subagentModelName: string;
+  /** 主对话思维程度（agent-request patch reasoningEffort；''=不设置，官方档位 off/low/high/max）。 */
+  modelReasoningEffort?: string;
+  /** 主对话采样温度（agent-request patch temperature；''=不设置）。 */
+  modelTemperature?: string;
+  /** 主对话输出上限（agent-request patch maxTokens；''=不设置）。 */
+  modelMaxTokens?: string;
+  /** 子代理思维程度（agent-request patch，audience=subagent；''=不设置）。 */
+  subagentReasoningEffort?: string;
+  /** 子代理采样温度（agent-request patch，audience=subagent；''=不设置）。 */
+  subagentTemperature?: string;
+  /** 子代理输出上限（agent-request patch，audience=subagent；''=不设置）。 */
+  subagentMaxTokens?: string;
+  /** 子代理自定义模型人设（per-child shadow；缺省 = 经 scope 链继承主会话 persona 模块）。 */
+  subagentPersona?: string;
+  /** 委派工具集白名单（toolFilter.allow；支持数组或逗号/空格分隔字符串）。 */
+  toolFilterAllow?: string[] | string;
+  /** 委派工具集黑名单（toolFilter.deny）。 */
+  toolFilterDeny?: string[] | string;
+  /** 委派递归深度上限（0 禁止委派 / provider-managed / 正整数）。 */
+  maxDepth?: number | 'provider-managed' | string;
+  /** 注入 kind 白名单（context-gate allowKinds；数组或逗号分隔字符串）。 */
+  allowKinds?: string[] | string;
+  /** custom-fallback 锚定词（prompt-injector params.firstTurnWord）。 */
+  firstTurnWord?: string;
+  /** 是否注入 agents.md 内容到 instruction-hint（false 时 instruction-hint 走引擎默认提示/动态探测）。 */
+  injectAgentsPrompt?: boolean;
   bootstrapMaxTokens: number;
   usePtcMode: boolean;
-  /** 运行时检测：是否注册了 DeepSeek 模型路由（不写入 settings）。 */
-  deepseekAvailable: boolean;
-  injectPrompt: boolean;
-  skillSwitches: Record<string, boolean>;
+  /** 写入 agents-instruction.txt 供 instruction-hint 配置读取;不传则使用本地默认 hint。 */
+  agentsInstructionText?: string;
+  presetDir: string;
+  presetOrder: number;
+  /** settings 层用户自定义提示词配置(优先级最高)。 */
+  promptConfigs: PromptConfigSpec[];
+  /** 预设模板名(preset/<name>);默认 anchored(兼容期)。 */
+  presetTemplate?: string;
+  /** 目录加载失败等非致命告警回调。 */
+  warn?: (message: string) => void;
+}
+/** 把任意单一参数预设模板物化到生成目录;全部失败 fail loud。 */
+declare function writePreset(prompt: string, options: WritePresetOptions): void;
+//#endregion
+//#region src/host/manifest.d.ts
+/**
+ * manifest — 预设模板单一参数 YAML(preset.yml)的加载与引擎参数解析。
+ *
+ * 一个预设 = 一个 preset.yml:
+ *   - modules/params/content/meta 全部是直读参数,无模板语法;
+ *   - 默认提示词配置由引擎按 params 生成(见 write-preset),promptConfigs 仅为可选覆盖;
+ *   - 组合模块中的 __TOKEN__ 由引擎内部 renderEngineTokens 按 params 生成,
+ *     不再暴露到参数文件。
+ * 本模块负责参数归一化与引擎 token 渲染;所有 anchored 专属行为都在引擎内部。
+ */
+interface PresetSpec {
+  id: string;
+  name: string;
+  /** 预设说明（官方用户预设格式元数据；列表展示用，可选）。 */
+  description?: string;
+  version: string;
+  engineCompat: string;
+  meta?: Record<string, unknown>;
+  content?: {
+    presetText?: string;
+    agentsText?: string;
+  };
+  /** 模块清单(参数文件决定组合内容):按序装配 engine/compositions/library/<name>.yml。 */
+  modules?: string[];
+  /** 兼容字段:内联组合文本或组合清单名。 */
+  composition?: string;
+  /** 扁平参数:全部直读(true/false、数字、字符串),on/off 作为兼容写法。 */
+  params?: Record<string, unknown>;
+  /** 预设级模板变量（{{key}} 插值源；与引擎行为参数 params 分离，顶层 variables 段）。 */
+  variables?: Record<string, string>;
+  /** 模板变量插值开关（缺省 true = 启用；false = 停用，writePreset 不生成变量文件）。 */
+  variablesEnabled?: boolean;
+  /** 宿主层默认值(唯一入口):apply 时合并进 Config,settings 仍可覆盖。 */
+  hostDefaults?: Record<string, unknown>;
+  /** 可选:模板自定义提示词配置覆盖(纯数据,不使用模板语法)。 */
+  promptConfigs?: unknown[];
+  /** 可选:引擎组合模块行参数覆盖(行级 map config 浅合并,preset 优先)。 */
+  moduleConfigs?: Record<string, Record<string, unknown>>;
+  /** 世界书（独立存储段，不进 promptConfigs）：injectMode + 条目。 */
+  worldBook?: {
+    injectMode?: 'full' | 'keyword';
+    entries: Array<Record<string, unknown>>;
+  };
+  legacyCleanup?: string[];
+  upstream?: Record<string, unknown>;
+}
+/** 加载某个预设模板的单一参数文件 preset/<name>/preset.yml。 */
+declare function loadPresetSpec(dir: string): PresetSpec;
+/** 预设根：官方 USER_PRESET_DIR（~/.dsh/.agent-presets），导入/新建/种子化的预设都放这里。 */
+declare function userPresetsDir(): string;
+/**
+ * 解析预设模板目录：用户自定义优先，包内模板回退。
+ * 目录名与 preset.yml id 双匹配（UI 切换值=目录名；旧 settings 存量值=id 也兼容）。
+ */
+declare function resolvePresetDir(template: string): string;
+/** 可用预设清单：全部来自预设根 ~/.dsh/.agent-presets（官方预设目录，含 agent.cordis.yml
+ *  即被宿主挂载；点前缀目录与无 preset.yml 的官方目录跳过，不占本插件列表）。 */
+declare function listPresets(): Array<{
+  id: string;
+  name: string;
+  user: boolean;
+  description?: string;
+  meta?: Record<string, unknown>;
+}>;
+/** 插件目录模板清单（「新建」选择器与首次种子化数据源；不直接出现在预设列表）。 */
+declare function listBuiltinTemplates(): Array<{
+  id: string;
+  name: string;
+}>;
+interface PromptToolState {
+  seeded?: boolean;
+  paramsMigrated?: boolean;
+}
+/** 读插件状态；文件缺失/损坏返回空对象（按未标记处理，触发首次动作）。 */
+declare function readPluginState(): PromptToolState;
+/** 原子写插件状态（tmp+rename）。 */
+declare function writePluginState(state: PromptToolState): void;
+/** 首次启动种子化：把插件目录全部内置模板复制到预设根（state.seeded 后不再自动补）。
+ *  用户删除的预设不会自动复活；升级新增的模板用「新建」按需复制。
+ *  兼容旧版预设根内 .pt-seeded 标记：存在即视为已种子化，并迁入状态文件后删除。 */
+declare function ensurePresetSeed(): {
+  created: string[];
+};
+/** 从插件目录复制内置预设到预设根（新建/还原）。
+ *  autoSuffix=true（自定义预设入口）时同名自动递增（custom → custom-2 → …）；否则同名拒绝。 */
+declare function cloneBuiltinPreset(id: string, autoSuffix?: boolean): {
+  ok: true;
+  id: string;
+} | {
+  ok: false;
+  message: string;
+};
+/**
+ * 保存预设参数：写激活预设目录 preset.yml 的 params（merge）/ promptConfigs（整体替换）。
+ * parseDocument 保留注释与未知键（preset.yml 模板含大量注释）；空值键跳过
+ * （保留 preset.yml 模板默认）。写入后删除 prompt-tool.overrides.yml（旧参数覆盖
+ * 通道残留——参数已并入 preset.yml，避免旧值覆盖新值）。
+ */
+declare function savePresetParams(presetRoot: string, templateName: string, params: Record<string, unknown> | undefined, promptConfigs: unknown[] | undefined, variables?: Record<string, string>, variablesEnabled?: boolean): void;
+/** 删除预设目录（预设根/<id>；含同名导入的 .bak-* 备份目录）。
+ *  仅作用于预设根（官方 USER_PRESET_DIR），包内置模板天然不受影响；路径越界与非法 id 拒绝。
+ *  删除后宿主 agent-presets 目录列表自然不再出现该预设（官方 roster 即目录列表）。 */
+declare function removeUserPreset(id: string, presetRoot?: string): {
+  ok: true;
+} | {
+  ok: false;
+  message: string;
+};
+/** 预设 params(默认参数)与运行时 settings 合并;settings 值优先。 */
+declare function resolvePresetParams(spec: PresetSpec, runtime: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 加载预设声明的组合:
+ *   1. `modules:` 清单 → 引擎模块库按序装配(最终形态);
+ *   2. 兼容 `composition:` 内联文本或组合清单名。
+ */
+/**
+ * 行级 config 合并(moduleConfigs):仅支持 map 型 config 浅合并;
+ * 数组型 config(如 compaction)与未声明模块原样保留。
+ * 未声明 moduleConfigs 时返回原文(零开销);parseDocument 往返保留注释与 __TOKEN__。
+ */
+declare function applyModuleConfigs(raw: string, configs: Record<string, Record<string, unknown>> | undefined): string;
+//#endregion
+//#region src/host/sillytavern.d.ts
+/** 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;
+//#endregion
+//#region src/web-surface.d.ts
+/** 从 loader 根 Include 的 baseUrl 推导 profile 目录。 */
+declare function resolveProfileDir(ctx: Context): string | undefined;
+/**
+ * 每次启动：
+ *  1. 只处理当前 profile：缺 webServer 时补 web-app 并提示重启；
+ *  2. 不修改同级 profile，不主动退出进程。
+ */
+declare function ensureWebSurface(ctx: Context, warn: (message: string) => void): void;
+//#endregion
+//#region src/profile-skills.d.ts
+/**
+ * 返回本插件应使用的 skills 目录：
+ * 优先本插件 profile（prompt-tool）下的 `skills/` 副本；无法确定 profile
+ * 或复制失败时回退到 sourceDir（默认包内 `skills/`）。
+ */
+declare function resolveProfileSkillsDir(ctx: Context, sourceDir: string, warn: (message: string) => void): string;
+//#endregion
+//#region src/host/migration.d.ts
+declare function migrateLegacyLayout(presetRoot: string, legacyUserPresets: string): boolean;
+/** 旧版 presetDir 配置值（容器根/旧用户目录）归一化为预设根；其余原样。 */
+declare function normalizePresetRootDir(presetDir: string, presetRoot: string, legacyContainer: string): string;
+//#endregion
+//#region src/runtime/models.d.ts
+/** 模型服务商检测结果（含诊断信息，供 Web/TUI 展示）。 */
+interface ModelDetection {
+  /** 是否检测到任何已注册/可配置的服务商路由。 */
+  available: boolean;
+  /** 已检测到（live 注册）的模型服务商 id——状态提示用。 */
+  providers: string[];
+  error?: string;
+}
+/** 检测模型服务商：只统计 live 注册路由（状态提示与下拉共用同一来源）。 */
+declare function detectModels(ctx: Context): ModelDetection;
+/** 查询各已注册服务商公布的模型 id（对齐官方 web 选择器 buildModelCatalog：只遍历 listProviders() live 路由，单点失败/超时不拖垮整体；仅作展示，不构成路由白名单）。并行查询 + 10min 缓存 + 单点超时。 */
+declare function listAdvertisedModels(ctx: Context): Promise<Record<string, string[]>>;
+/**
+ * 主对话默认模型控制：modelProvider + modelName 同时非空时，经官方
+ * `agentDefaultModel.saveSelection` 写入新会话默认模型（对齐官方 web 切换模型的
+ * 默认级持久化；只影响新创建的 Agent，不干预已有会话）。任一为空 = 不干预
+ * （继承用户在宿主 web 的选择）；agent-default-model 服务未装配时静默跳过。
+ */
+declare function installDefaultModelRoute(ctx: Context, isEnabled: () => boolean, provider: () => string, model: () => string, getReasoningEffort?: () => string): () => void;
+//#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;
+}): Promise<PromptConfigValidationResult>;
+//#endregion
+//#region src/runtime/settings-bridge.d.ts
+interface SkillsBridgeState {
+  activeSkillsDirs: string[];
   skillCatalog: SkillCatalogEntry[];
-  /** 用户自定义技能目录；空 = 自动使用 profile skills 副本。 */
-  skillsDir: string;
-  /** 当前实际生效的技能目录（profile 副本或用户自定义路径）。 */
-  activeSkillsDir: string;
-  writeAgents: boolean;
-  writePreset: boolean;
 }
-declare function apply(ctx: Context, config: Config): void;
+/** 自建 loopback settings bridge：替代 registerConfigurableProviders，避免模型设置区出现插件条目。 */
+declare function registerSettingsBridge(ctx: Context, ns: SettingsNamespace, getModelsState: () => ModelDetection, getSkillsState: () => SkillsBridgeState, getEngineStrategyDir: () => string, ensureRegistered: (sctx: Context) => boolean, afterSkillFix?: () => void,
+/** 生成目录（presetDir）：读取实际生效的提示词配置（引擎加载源）。 */
+getPresetConfigsDir?: () => string,
+/** 内容导入完成回调（更新运行时文本并重建预设）。 */
+afterPresetImport?: (scope: 'preset' | 'agents') => void,
+/** 参数覆盖写入回调（重建预设使参数生效）。 */
+afterOverridesChange?: () => void,
+/** 预设包导入完成回调（物化导入预设：组合/配置目录/共享引擎落盘，宿主 discovery 可见）。 */
+afterPresetPackageImport?: (id: string) => void): void;
+//#endregion
+//#region src/runtime/character-tools.d.ts
+/** 工具执行所需的运行时宿主能力（index.ts 闭包提供）。 */
+interface CharacterToolHost {
+  /** 预设根目录（presetDir）。 */
+  presetRoot: () => string;
+  /** 当前激活预设模板名。 */
+  templateName: () => string;
+  /** 应用/移除后重建生成目录（写 preset.yml 后使参数生效）。 */
+  rebuild: () => void;
+}
+declare function registerCharacterTools(ctx: Context, host: CharacterToolHost): void;
+//#endregion
+//#region src/runtime/world-book-tools.d.ts
+interface WorldBookToolHost {
+  /** 当前激活预设目录（preset.yml 所在目录）。 */
+  activeDir: () => string;
+  /** 预设根目录（角色卡库 .characters/<id> 所在根）。 */
+  presetRoot: () => string;
+  /** 写盘后重建生成目录。 */
+  rebuild: () => void;
+}
+declare function registerWorldBookTools(ctx: Context, host: WorldBookToolHost): void;
+//#endregion
+//#region src/host/templates.d.ts
+interface PromptConfigTemplate {
+  /** 模板文件名（数字前缀决定展示顺序）。 */
+  file: string;
+  /** 模板原文（编辑器源码模式可直接展示）。 */
+  content: string;
+  /** 解析后的单条提示词配置。 */
+  spec: PromptConfigSpec;
+}
+/** 扫描包内 templates/*.yml，按文件名排序返回（文件损坏时抛出，由调用方决定呈现）。 */
+declare function loadPromptTemplates(): PromptConfigTemplate[];
+//#endregion
+//#region src/runtime/tui.d.ts
+/** 通过 DSH 命令注册表暴露 /prompt-tool，Web 与 dsh-tui 都能执行。 */
+declare function registerTuiCommand(ctx: Context, ns: SettingsNamespace, getSource: () => PromptSettings, getModelsState: () => ModelDetection, getModelCatalog: () => Promise<Record<string, string[]>>, getPresetConfigsDir?: () => string,
+/** 参数保存回调（写激活预设 preset.yml；key='promptConfigs' 时 value 为数组）。 */
+savePresetParam?: (key: string, value: unknown) => void): void;
+//#endregion
+//#region src/runtime/settings-registration.d.ts
+interface SettingsRegistrationHooks<T> {
+  /** 注册时的 composition base（每次尝试注册都取最新值）。 */
+  base: () => T;
+  /** 注册成功后接线：setSource / watch / 初始 onChange。 */
+  onRegistered: (scope: {
+    get: () => T;
+    watch: (callback: (next: T, prev: T) => void) => void;
+  }) => void;
+  /** 注册失败（schema 校验或重复注册竞态）时的日志出口。 */
+  onError: (message: string) => void;
+}
+/**
+ * 确保 `ns` 已注册：已注册（describe 命中）直接返回 true；未注册时补注册。
+ * 官方 installSettingsSection 的 inject 回调只在 settings 服务首次可用时跑一次，
+ * settings 服务实例被替换（provider fiber reload）后注册丢失且不自动重建；
+ * 本函数由 Web bridge 每次请求前调用兜底。
+ */
+declare function ensureSettingsRegistered<T>(sctx: Context, ns: SettingsNamespace, schema: unknown, hooks: SettingsRegistrationHooks<T>): boolean;
+//#endregion
+//#region src/runtime/skills-provider.d.ts
+/** 官方 dsh-skill 的 SkillName 契约：kebab-case。 */
+declare const SKILL_NAME_RE: RegExp;
+interface SkillFolder {
+  name: string;
+  /** 通过符号链接/junction 挂入的目录（删除类操作需谨慎）。 */
+  linked: boolean;
+}
+declare function listSkillFolders(skillsDir: string): SkillFolder[];
+/** 只有 valid=true 的条目才能进入 ctx.skills 注册表。 */
+declare function isValidSkill(entry: SkillEntry): boolean;
+/** 供 provider 使用的合法条目集合（坏条目逐条跳过，绝不拖垮整批列表）。 */
+declare function validSkills(entries: SkillEntry[]): SkillEntry[];
+/**
+ * 读取技能目录树的全部条目（含坏条目与嵌套子技能）。
+ *  - 递归语义：任意层级含 SKILL.md 的目录都是技能（folder = 相对路径，嵌套用 / 分隔）；
+ *    不含 SKILL.md 的目录（含多层空文件夹）不产生条目，继续下探其子目录。
+ *  - 链接（junction/symlink）目录作为技能叶子：含 SKILL.md 则注册，不递归进入（防环）。
+ *  - frontmatter 无 name 时回退目录名；name（frontmatter 或目录名）必须 kebab-case 才 valid；
+ *  - warn 仅用于日志，不再决定条目去留。
+ */
+declare function readSkills(skillsDir: string, warn?: (message: string) => void): SkillEntry[];
+/** 多目录全量合并：条目全部保留（同名不跳过，UI 层再做 duplicate 标注）。 */
+declare function mergeSkillDirs(dirs: string[], read: (dir: string, warn?: (message: string) => void) => SkillEntry[], warn?: (message: string) => void): SkillEntry[];
+/**
+ * 进程内技能扫描缓存：按目录 + 每个 SKILL.md 的 mtime/size 签名失效。
+ * 同一目录在内容未变化时，list/get 可复用同一次扫描结果。
+ */
+interface CachedSkillsReader {
+  read: (skillsDir: string, warn?: (message: string) => void) => SkillEntry[];
+  invalidate: (skillsDir?: string) => void;
+}
+declare function createCachedSkillsReader(): CachedSkillsReader;
+//#endregion
+//#region src/runtime/skill-fix.d.ts
+interface SkillFixResult {
+  fixed: boolean;
+  /** 修复前目录名。 */
+  folder: string;
+  /** 修复后目录名。 */
+  fixedFolder: string;
+  /** 修复后注册名（与目录一致）。 */
+  name: string;
+  /** 实际执行的动作描述（写文件/重命名/剥 BOM/补 name）。 */
+  actions: string[];
+  error?: string;
+}
+/** 任意字符串 → kebab-case；空结果回退 'skill'。 */
+declare function toKebabName(value: string): string;
+/**
+ * 修复一个无效技能条目。
+ * @param skillsDir - activeSkillsDir（绝对路径）。
+ * @param folder - 要修复的目录名（不允许含路径分隔符）。
+ */
+declare function fixSkillEntry(skillsDir: string, folder: string): SkillFixResult;
+//#endregion
+//#region src/shared/bridge-contract.d.ts
+/**
+ * settings bridge 跨端契约（host 注册 / client 消费的唯一来源）。
+ * 铁律：11 端点载荷统一成功 `{ ok: true, value }`、失败 `{ ok: false, code?, message? }`；
+ * 端点附加字段只能以 value 旁的可选扩展字段出现（describe）。
+ * 改路径或载荷形状必须同步更新 test/shared/bridge-contract.test.mjs。
+ */
+declare const SETTINGS_BRIDGE_PREFIX = "/api/prompt-tool/settings";
+/** 22 个桥端点路径（相对前缀）。新增端点必须同时登记到契约测试。 */
+declare const BRIDGE_ENDPOINTS: {
+  readonly meta: "/meta";
+  readonly describe: "/describe";
+  readonly models: "/models";
+  readonly mutate: "/mutate";
+  readonly configsValidate: "/configs-validate";
+  readonly skillFix: "/skill-fix";
+  readonly templates: "/templates";
+  readonly promptConfigs: "/prompt-configs";
+  readonly presetContent: "/preset-content";
+  readonly importPreset: "/import-preset";
+  readonly paramOverrides: "/param-overrides";
+  readonly presetVariables: "/preset-variables";
+  readonly importPresetPackage: "/import-preset-package";
+  readonly exportPreset: "/export-preset";
+  readonly presetDelete: "/preset-delete";
+  readonly presetClone: "/preset-clone";
+  readonly presetDuplicate: "/preset-duplicate";
+  readonly presetOpen: "/preset-open";
+  readonly charactersImport: "/characters-import";
+  readonly charactersList: "/characters-list";
+  readonly charactersDelete: "/characters-delete";
+  readonly charactersApply: "/characters-apply";
+  readonly charactersRemove: "/characters-remove";
+};
+type BridgeEndpoint = (typeof BRIDGE_ENDPOINTS)[keyof typeof BRIDGE_ENDPOINTS];
+/** 失败载荷：两端共用。 */
+type BridgeErrorPayload = {
+  ok: false;
+  code?: string;
+  message?: string;
+};
+//#endregion
+//#region src/runtime/skills-parse.d.ts
+interface SkillFrontmatter {
+  name?: string;
+  description?: string;
+  whenToUse?: string;
+  metadata?: Record<string, unknown>;
+  /** 官方调用策略：true 时模型不可发现/不可加载（默认 false = 可调用）。 */
+  disableModelInvocation?: boolean;
+  /** 官方调用策略：false 时用户命令不可加载（默认 true）。 */
+  userInvocable?: boolean;
+}
+declare function parseFrontmatter(text: string): {
+  data: SkillFrontmatter;
+  body: string;
+};
+//#endregion
+//#region src/index.d.ts
+declare const name = "prompt-tool";
+declare const inject: string[];
+declare function apply(ctx: Context, configIn: Config): void;
 //#endregion
-export { Config, PromptSettings, apply, inject, name };
+export { BRIDGE_ENDPOINTS, type BridgeEndpoint, type BridgeErrorPayload, type CachedSkillsReader, Config, PARAM_KEYS, type PresetSpec, type PromptConfigTemplate, type PromptConfigValidationError, type PromptConfigValidationResult, PromptSettingsSchema, SETTINGS_BRIDGE_PREFIX, SKILL_NAME_RE, type SettingsRegistrationHooks, type SkillCatalogEntry, type SkillEntry, type SkillFixResult, type SkillFrontmatter, type WritePresetOptions, apply, applyModuleConfigs, cloneBuiltinPreset, createCachedSkillsReader, detectModels, ensurePresetSeed, ensureSettingsRegistered, ensureWebSurface, fixSkillEntry, inject, installDefaultModelRoute, isValidSkill, listAdvertisedModels, listBuiltinTemplates, listPresets, listSkillFolders, loadPresetSpec, loadPromptTemplates, mergeSkillDirs, migrateLegacyLayout, name, normalizePresetRootDir, parseFrontmatter, readPluginState, readSkills, registerCharacterTools, registerSettingsBridge, registerTuiCommand, registerWorldBookTools, removeUserPreset, resolvePresetDir, resolvePresetParams, resolveProfileDir, resolveProfileSkillsDir, savePresetParams, stPresetId, toKebabName, userPresetsDir, validSkills, validatePromptConfigs, writePluginState, writePreset };