@dsh-plus/agent-preset-rea 0.1.1 → 0.1.3

package/lib/index.d.ts

@@ -10,8 +10,16 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
   name: z<string, string, "defined">;
   description: z<string, string, "defined">;
   order: z<number, number, "defined">;
+  personaPrefixMode: z<"custom" | "default", "custom" | "default", "volatile-defined">;
   personaPrefix: z<string, string, "volatile-defined">;
-  mcpEnabled: z<boolean, boolean, "defined">;
+  capabilityProtocol: z<string, string, "defined">;
+  subagentDirective: z<string, string, "defined">;
+  mcpEnabled: z<boolean, boolean, "volatile-defined">;
+  skillEnabled: z<boolean, boolean, "volatile-defined">;
+  reverseSkillEnabled: z<boolean, boolean, "volatile-defined">;
+  reverseSkillRepo: z<string, string, "defined">;
+  reverseSkillRef: z<string, string, "defined">;
+  reverseSkillGroups: z<string[], string[], "defined">;
   mcpServerName: z<string, string, "defined">;
   reaVersion: z<string, string, "defined">;
   installRoot: z<string, string, "defined">;
@@ -28,8 +36,16 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
   name: z<string, string, "defined">;
   description: z<string, string, "defined">;
   order: z<number, number, "defined">;
+  personaPrefixMode: z<"custom" | "default", "custom" | "default", "volatile-defined">;
   personaPrefix: z<string, string, "volatile-defined">;
-  mcpEnabled: z<boolean, boolean, "defined">;
+  capabilityProtocol: z<string, string, "defined">;
+  subagentDirective: z<string, string, "defined">;
+  mcpEnabled: z<boolean, boolean, "volatile-defined">;
+  skillEnabled: z<boolean, boolean, "volatile-defined">;
+  reverseSkillEnabled: z<boolean, boolean, "volatile-defined">;
+  reverseSkillRepo: z<string, string, "defined">;
+  reverseSkillRef: z<string, string, "defined">;
+  reverseSkillGroups: z<string[], string[], "defined">;
   mcpServerName: z<string, string, "defined">;
   reaVersion: z<string, string, "defined">;
   installRoot: z<string, string, "defined">;
@@ -76,17 +92,83 @@ interface JobOperation {
   phases: string[];
   run(ctx: JobTaskContext): Promise<string>;
 }
+/** 作业依赖：生效配置、命令执行面、作业完成后的现探刷新。 */
+interface JobDeps {
+  config: AgentPresetReaConfig;
+  runner: CommandRunner;
+  refresh(): void;
+}
 /** 实际 runner：spawn 子进程、逐行回调、AbortSignal 触发即杀。 */
 declare const spawnRunner: CommandRunner;
-/**
- * npm 子进程环境：继承宿主环境，附带代理端口（port > 0 时同时给 npm 与
- * prebuild-install 注入代理——后者只认 `https_proxy` 系列环境变量，
- * 这是原生依赖 prebuild 下载卡死的正解）。
- */
+/** npm 子进程环境（{@link commandEnv} 的 npm 形态）。 */
 declare function npmEnv(config: AgentPresetReaConfig): Record<string, string>;
 /** 版本收窄：进命令前把配置里的钉版校验成纯版本号。 */
 declare function safeVersion(version: string): string;
 //#endregion
+//#region src/reverse.d.ts
+/** 本技能源在插件数据目录下的子目录名。 */
+declare const REVERSE_DIR = "reverse-skill";
+/** 仓库树目录名（换目录作业的替换单元是它的父目录）。 */
+declare const REVERSE_TREE_DIR = "repo";
+/** 默认仓库。 */
+declare const REVERSE_DEFAULT_REPO = "zhaoxuya520/reverse-skill";
+/** 手动更新作业阶段名。 */
+declare const REVERSE_PHASES: string[];
+/** 受管路径。 */
+interface ReversePaths {
+  /** 技能源根（`repo/` 与 `manifest.json` 的父目录）。 */
+  root: string;
+  /** 仓库树根。 */
+  tree: string;
+}
+/** 清单（溯源事实；sha 已是内容级溯源，故不再逐文件复算哈希）。 */
+interface ReverseManifest {
+  source: string;
+  repo: string;
+  /** 配置里的 ref（空串 = 仓库默认分支）。 */
+  ref: string;
+  /** GitHub 机构 API 解析到的提交 sha。 */
+  sha: string;
+  /** 仓库 `VERSION` 文件内容（无则 null）。 */
+  version: string | null;
+  /** 树内文件数。 */
+  files: number;
+  /** 树内发现的技能组（相对路径）。 */
+  groups: string[];
+  updatedAt: string;
+}
+/** 技能源现状。 */
+interface ReverseState {
+  installed: boolean;
+  repo: string;
+  ref: string | null;
+  sha: string | null;
+  version: string | null;
+  files: number;
+  /** 树内发现的全部技能组（相对路径）。 */
+  groups: string[];
+  updatedAt: string | null;
+}
+/** 受管路径（固定落插件数据目录，无部署方可调项）。 */
+declare function reversePaths(): ReversePaths;
+/** 发现树内的技能组：直接子目录带 SKILL.md 的目录（排除树根与 SKIP_DIRS）。 */
+declare function discoverSkillGroups(tree: string): string[];
+/** 现探技能源（清单可读 + 树在 + 至少一个技能组才算可用）。 */
+declare function probeReverse(config: AgentPresetReaConfig, repo?: string): ReverseState;
+/**
+ * 挂进本预设的技能组目录：配置选中 ∩ 树内发现。
+ *
+ * 组是否真实存在由现探的 {@link discoverSkillGroups} 负责（发现即存在），这里不再
+ * 二次查盘——否则「未安装/组缺席」两种语义会在两处各判一遍。
+ * @param config - 插件配置。
+ * @param state - 现探现状。
+ */
+declare function reverseSkillDirs(config: AgentPresetReaConfig, state: ReverseState): string[];
+/** 作业依赖（与 manager 的作业同形：配置 + 命令执行面 + 现探刷新）。 */
+type ReverseDeps = JobDeps;
+/** 手动更新作业：拉默认分支/指定 ref 的最新提交，解包后换目录并写清单。 */
+declare function runReverseSkillJob(deps: ReverseDeps, ctx: JobTaskContext): Promise<string>;
+//#endregion
 //#region src/manager.d.ts
 /** npm 包名。 */
 declare const REA_PACKAGE = "rea-agents";
@@ -119,6 +201,8 @@ interface SkillState {
 interface RuntimeSnapshot {
   install: ReaInstall | null;
   skill: SkillState;
+  /** GitHub 技能源（zhaoxuya520/reverse-skill）现状。 */
+  reverse: ReverseState;
 }
 /** skill 清单（与随包夹具同形；更新副本多写入 updatedAt）。 */
 interface SkillManifest {
@@ -146,10 +230,11 @@ interface ReaManager {
   snapshot(): RuntimeSnapshot;
   /** 重新现探并更新快照（作业完成、volatile 变更后调用）。 */
   refresh(): RuntimeSnapshot;
-  /** 受管作业（安装/更新 REA 包、更新 skill）。 */
+  /** 受管作业（安装/更新 REA 包、更新 REA skill、更新 reverse-skill）。 */
   operations(overrides?: JobOverrides): {
     install: JobOperation;
     skill: JobOperation;
+    reverse: JobOperation;
   };
 }
 /** 安装作业阶段名。 */
@@ -170,12 +255,6 @@ declare function probeInstall(paths: ManagerPaths): ReaInstall | null;
 declare function probeSkill(paths: ManagerPaths, bundledRoot: string, bundledVersion: string): SkillState;
 /** 现探运行期事实。 */
 declare function probeRuntime(config: AgentPresetReaConfig, bundledRoot: string, bundledVersion: string): RuntimeSnapshot;
-/** 作业依赖：生效配置、命令执行面、作业完成后的现探刷新。 */
-interface JobDeps {
-  config: AgentPresetReaConfig;
-  runner: CommandRunner;
-  refresh(): void;
-}
 /** 生效配置：作业可带一次性覆盖（卡片未保存的代理端口即时可用）。 */
 declare function configWith(base: AgentPresetReaConfig, overrides?: JobOverrides): AgentPresetReaConfig;
 /** 建一个 REA 管理器。 */
@@ -196,6 +275,13 @@ declare const ADDED_ROWS: readonly string[];
  * 删除某条等于把该行改回上游原文；改动上游不存在的字段会被测试拦下。
  */
 declare const CONFIG_DELTAS: Readonly<Record<string, readonly string[]>>;
+/**
+ * 最小（或极简）预设 id 判定：命中时注入文本需做减法适配。
+ *
+ * 判定面与上游预设命名惯例一致（`minimal` / `sdk-minimal` / `<x>/minimal` /
+ * 含 `preset-minimal`），不引入自造 id 概念。
+ */
+declare function isMinimalPresetId(id: string | undefined): boolean;
 /** 未安装、随包 skill 的运行期事实（默认值：测试与无 manager 场景）。 */
 declare function emptyRuntime(): RuntimeSnapshot;
 /**
@@ -214,8 +300,8 @@ declare function reaPresetDefinition(config: AgentPresetReaConfig, runtime?: Run
  * 两端共用同一份字段定义，避免「宿主改了字段、卡片还在读老名字」的静默漂移。
  * @module @dsh-plus/agent-preset-rea/dto
  */
-/** 作业种类。 */
-type JobKind = 'install' | 'skill';
+/** 作业种类：REA 包安装/更新、REA skill 更新、reverse-skill 更新。 */
+type JobKind = 'install' | 'skill' | 'reverse';
 /** 作业状态。 */
 type JobState = 'running' | 'ok' | 'error' | 'cancelled';
 /** 作业进度（按阶段推进；percent 为进入该阶段时的完成度）。 */
@@ -265,20 +351,46 @@ interface McpDto {
   command: string | null;
   args: string[];
 }
+/** GitHub 技能源（zhaoxuya520/reverse-skill）事实。 */
+interface ReverseSkillDto {
+  installed: boolean;
+  repo: string;
+  /** 清单记录的 ref（空串 = 安装时取的默认分支）。 */
+  ref: string | null;
+  /** 提交 sha（内容级溯源）。 */
+  sha: string | null;
+  /** 仓库 VERSION 文件内容。 */
+  version: string | null;
+  root: string;
+  tree: string;
+  files: number;
+  /** 树内发现的全部技能组（相对安装树根）。 */
+  groups: string[];
+  /** 配置选中且实际挂进预设的组。 */
+  activeGroups: string[];
+  updatedAt: string | null;
+}
 /** `GET /status` 响应。 */
 interface StatusDto {
   config: {
     reaVersion: string;
     proxyPort: number;
     mcpEnabled: boolean;
+    skillEnabled: boolean;
+    reverseSkillEnabled: boolean;
+    reverseSkillRepo: string;
+    reverseSkillRef: string;
+    reverseSkillGroups: string[];
     installRoot: string;
   };
   install: InstallDto;
   skill: SkillDto;
+  reverse: ReverseSkillDto;
   mcp: McpDto;
   paths: {
     installRoot: string;
     skillRoot: string;
+    reverseRoot: string;
   };
   job: JobDto | null;
 }
@@ -348,6 +460,82 @@ declare function reaMcpLaunch(config: AgentPresetReaConfig, installed: Installed
  */
 declare function reaMcpEnv(config: AgentPresetReaConfig): Record<string, string>;
 //#endregion
+//#region src/persona-prefix.d.ts
+/**
+ * 随包内置的 persona 前缀默认文本（REA 预设的「默认提示词」）。
+ *
+ * 文本取自 dsh-purge 的出厂注入明文（`lib/default-prompt-inject.md`，经
+ * `lib/asset-table.js` 的 AES-256-GCM 槽密封发布）。此处**逐字保留**：不改写信封、
+ * 不重排段落——注入效果依赖原文形态（信封首行、规则段落边界）。
+ *
+ * 承载形态用**字符串数组简单拼接**而非模板字面量：原文含 40 个反引号
+ * （`[TARGET_IP]` 一类占位符），模板字面量需逐处转义；数组形式零转义、与原文
+ * 逐字节等价，且 diff 按行可读。
+ *
+ * @module @dsh-plus/agent-preset-rea/persona-prefix
+ */
+/** 内置默认提示词（原文，换行符恒为 `\n`）。 */
+declare const DEFAULT_PERSONA_PREFIX: string;
+/** 信封首行：必须独立成行，否则尖括号被当成半截标签、整段注入失效。 */
+declare const PREFIX_ENVELOPE_LINE = "<|im_start|>system:<project_instructions>";
+/** 归一化后的比对形态。归一化后可容忍换行与缩进漂移，但正文实质改动无法隐藏。 */
+declare function normalizePersonaPrefix(text: string): string;
+/**
+ * 内置默认提示词的归一化形态，用于对比与指纹守卫。
+ *
+ * 指纹 `DEFAULT_PERSONA_PREFIX_HASH` 由它算出；改文本必须同步改常量，否则测试失败。
+ */
+declare function normalizedDefaultPersonaPrefix(): string;
+/** 归一化形态的 sha256，作为文本漂移守卫。 */
+declare const DEFAULT_PERSONA_PREFIX_HASH = "3e47b4b5b11beb0de6aaea95d195f4974d59c14a84ac60b5bf49299ac3a0102f";
+/**
+ * 内置文本字符数（卡片只读展示用）。
+ *
+ * 用 `.length` 而非 UTF-8 字节数：`.length` 在 Node 与浏览器同值，不需要
+ * `Buffer` / `TextEncoder` 之类的运行期能力，卡片这一处只是给人看的量级提示。
+ * 字节数另有 {@link DEFAULT_PERSONA_PREFIX_BYTES} 供测试用（正文含 CJK，两者不同值）。
+ */
+declare const DEFAULT_PERSONA_PREFIX_LENGTH: number;
+/** 内置文本的 UTF-8 字节数（测试的第二道独立守卫；正文含 CJK，比字符数大）。 */
+declare const DEFAULT_PERSONA_PREFIX_BYTES: number;
+/** 内置文本的只读预览（卡片在「默认」模式展示；正文真源仍是上面的常量）。 */
+declare const DEFAULT_PERSONA_PREFIX_PREVIEW: string;
+/** 内置文本必须覆盖的规则段标题（缺一即测试失败）。 */
+declare const REQUIRED_PREFIX_SECTIONS: readonly string[];
+/** persona 前缀的来源选择：`default` = 随包内置，`custom` = 用户自定义文本。 */
+type PersonaPrefixMode = 'default' | 'custom';
+/** 前缀选择的最小输入面（避免与 config.ts 形成循环依赖）。 */
+interface PersonaPrefixChoice {
+  personaPrefixMode: PersonaPrefixMode;
+  personaPrefix: string;
+}
+/**
+ * 追加段的最小输入面（部署方平面：两个可选段落，空串 = 不追加）。
+ *
+ * 两段都追加在正文**末尾**，正文本身逐字不动：借用做法不以改写已验证的随包文本
+ * 为代价；默认（两段皆空）产出物与「只有正文」逐字节相同。
+ */
+interface PersonaPrefixExtensions {
+  /** 能力选用协议：任务驱动挑选技能与 MCP，并声明不移除宿主既有能力。 */
+  capabilityProtocol: string;
+  /** 子代理指令继承：派发 brief 时须浓缩继承本节规则。 */
+  subagentDirective: string;
+}
+/**
+ * 把非空追加段接到正文末尾。
+ *
+ * 空串（含纯空白）整段跳过，因此「没配置」与「配置成空」产出同一结果；段与正文
+ * 之间只插一个空行。
+ */
+declare function appendPersonaExtensions(text: string, extensions: PersonaPrefixExtensions): string;
+/**
+ * 按模式取 `persona` 行实际写入的 `prefix`，并接上部署方追加段。
+ *
+ * `custom` 取用户值；用户值意外为空时回落内置文本——空 persona 会静默遮蔽部署级
+ * 人设却不注入任何内容，比「用默认」更难排查。
+ */
+declare function resolvePersonaPrefix(config: PersonaPrefixChoice & PersonaPrefixExtensions): string;
+//#endregion
 //#region src/prompt.d.ts
 /**
  * 本包随包携带的上游提示词文本：`standard` 预设 `plan-mode` 行的 section 原文。
@@ -408,11 +596,19 @@ declare function registerReaRoutes(ctx: Context, options: ReaRoutesOptions): voi
  */
 declare const BUNDLED_SKILL_ROOT: string;
 /**
- * skill-filesystem 的追加根清单。
+ * REA skill 根（随包副本，或手动更新副本——后者存在即替代前者）。
+ * @param updatedRoot - 手动更新副本根（来自 manager 现探）。
+ */
+declare function reaSkillDirs(updatedRoot?: string | null): string[];
+/**
+ * 本预设 `skill-filesystem` 行的完整追加根清单，按三个开关裁剪：
+ * - `skillEnabled=false` → 不挂 REA 官方 skill（安装副本仍留在磁盘）；
+ * - `reverseSkillEnabled=false` → 不挂 reverse-skill 的技能组；
+ * - `extraSkillDirs` 是部署方追加项，不受开关影响（关掉的是本插件自带的两个源）。
  * @param config - 插件配置。
- * @param updatedRoot - 手动更新副本根（存在即替代随包根；来自 manager 现探）。
+ * @param runtime - 现探运行期事实。
  */
-declare function reaSkillDirs(config: AgentPresetReaConfig, updatedRoot?: string | null): string[];
+declare function presetSkillDirs(config: AgentPresetReaConfig, runtime: RuntimeSnapshot): string[];
 //#endregion
 //#region src/index.d.ts
 declare const name = "dsh-plus-agent-preset-rea";
@@ -428,4 +624,4 @@ declare const inject: readonly [];
  */
 declare function apply(ctx: Context, config: AgentPresetReaConfigFields): void;
 //#endregion
-export { ADDED_ROWS, type AgentPresetReaConfig, type AgentPresetReaConfigFields, BUNDLED_SKILL_ROOT, CONFIG_DELTAS, type CommandRunner, Config, DEFAULT_MCP_COMMAND, INPUT_SCHEMA_PROFILES, INSTALL_PHASES, type InstallDto, type InstalledEntry, type JobActionDto, type JobBoard, JobCancelled, type JobDeps, type JobDto, type JobKind, type JobOperation, type JobOverrides, type JobProgressDto, type JobSnapshot, type JobState, type JobTaskContext, type ManagerPaths, type McpDto, type McpLaunch, NPM, OUTPUT_SCHEMA_PROFILES, PLAN_MODE_SECTION, type PresetRegistrar, REA_INSTALL_DIR, REA_PACKAGE, REA_PINNED_VERSION, REA_PRESET_ID, REA_SKILL_DIR, REA_SKILL_NAME, ROUTE_BASE, type ReaInstall, type ReaManager, type RuntimeSnapshot, SETTINGS_NS, SKILL_PHASES, type SkillDto, type SkillManifest, type SkillState, type StatusDto, type Unregister, apply, configWith, createJobBoard, createManager, createPresetRegistrar, emptyRuntime, inject, managerPaths, name, npmEnv, probeInstall, probeRuntime, probeSkill, reaMcpArgs, reaMcpEnv, reaMcpLaunch, reaPresetDefinition, reaSkillDirs, registerReaRoutes, safeVersion, spawnRunner, statusPayload };
+export { ADDED_ROWS, type AgentPresetReaConfig, type AgentPresetReaConfigFields, BUNDLED_SKILL_ROOT, CONFIG_DELTAS, type CommandRunner, Config, DEFAULT_MCP_COMMAND, DEFAULT_PERSONA_PREFIX, DEFAULT_PERSONA_PREFIX_BYTES, DEFAULT_PERSONA_PREFIX_HASH, DEFAULT_PERSONA_PREFIX_LENGTH, DEFAULT_PERSONA_PREFIX_PREVIEW, INPUT_SCHEMA_PROFILES, INSTALL_PHASES, type InstallDto, type InstalledEntry, type JobActionDto, type JobBoard, JobCancelled, type JobDeps, type JobDto, type JobKind, type JobOperation, type JobOverrides, type JobProgressDto, type JobSnapshot, type JobState, type JobTaskContext, type ManagerPaths, type McpDto, type McpLaunch, NPM, OUTPUT_SCHEMA_PROFILES, PLAN_MODE_SECTION, PREFIX_ENVELOPE_LINE, type PersonaPrefixChoice, type PersonaPrefixExtensions, type PersonaPrefixMode, type PresetRegistrar, REA_INSTALL_DIR, REA_PACKAGE, REA_PINNED_VERSION, REA_PRESET_ID, REA_SKILL_DIR, REA_SKILL_NAME, REQUIRED_PREFIX_SECTIONS, REVERSE_DEFAULT_REPO, REVERSE_DIR, REVERSE_PHASES, REVERSE_TREE_DIR, ROUTE_BASE, type ReaInstall, type ReaManager, type ReverseManifest, type ReversePaths, type ReverseSkillDto, type ReverseState, type RuntimeSnapshot, SETTINGS_NS, SKILL_PHASES, type SkillDto, type SkillManifest, type SkillState, type StatusDto, type Unregister, appendPersonaExtensions, apply, configWith, createJobBoard, createManager, createPresetRegistrar, discoverSkillGroups, emptyRuntime, inject, isMinimalPresetId, managerPaths, name, normalizePersonaPrefix, normalizedDefaultPersonaPrefix, npmEnv, presetSkillDirs, probeInstall, probeReverse, probeRuntime, probeSkill, reaMcpArgs, reaMcpEnv, reaMcpLaunch, reaPresetDefinition, reaSkillDirs, registerReaRoutes, resolvePersonaPrefix, reversePaths, reverseSkillDirs, runReverseSkillJob, safeVersion, spawnRunner, statusPayload };