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

package/lib/index.d.ts

@@ -14,6 +14,8 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
   mcpEnabled: z<boolean, boolean, "defined">;
   mcpServerName: z<string, string, "defined">;
   reaVersion: z<string, string, "defined">;
+  installRoot: z<string, string, "defined">;
+  proxyPort: z<number, number, "volatile-defined">;
   mcpCommand: z<string, string, "defined">;
   mcpArgs: z<string[], string[], "defined">;
   inputSchemaProfile: z<"compact" | "full", "compact" | "full", "defined">;
@@ -30,6 +32,8 @@ declare const Config: z<Schemastery.ObjectS<NoInfer<{
   mcpEnabled: z<boolean, boolean, "defined">;
   mcpServerName: z<string, string, "defined">;
   reaVersion: z<string, string, "defined">;
+  installRoot: z<string, string, "defined">;
+  proxyPort: z<number, number, "volatile-defined">;
   mcpCommand: z<string, string, "defined">;
   mcpArgs: z<string[], string[], "defined">;
   inputSchemaProfile: z<"compact" | "full", "compact" | "full", "defined">;
@@ -43,6 +47,145 @@ type AgentPresetReaConfigFields = Schemastery.TypeT<typeof Config>;
 /** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
 type AgentPresetReaConfig = UnwrapVolatile<AgentPresetReaConfigFields>;
 //#endregion
+//#region src/exec.d.ts
+/** npm 命令名（Windows 经 shell 执行，见 {@link spawnRunner} 注释）。 */
+declare const NPM = "npm";
+/** 作业取消（AbortSignal 触发后由 runner 抛出）。 */
+declare class JobCancelled extends Error {
+  constructor();
+}
+/** 外部命令执行面。 */
+interface CommandRunner {
+  run(command: string, args: string[], options: {
+    env: Record<string, string>;
+    signal: AbortSignal;
+    onLine(line: string): void;
+  }): Promise<{
+    code: number;
+  }>;
+}
+/** 作业执行上下文（阶段推进 + 日志 + 取消信号）。 */
+interface JobTaskContext {
+  /** 进入第 step 个阶段（从 0 起，与 {@link JobOperation.phases} 对应）。 */
+  phase(step: number): void;
+  log(line: string): void;
+  signal: AbortSignal;
+}
+/** 一类作业：阶段名 + 实现。 */
+interface JobOperation {
+  phases: string[];
+  run(ctx: JobTaskContext): Promise<string>;
+}
+/** 实际 runner：spawn 子进程、逐行回调、AbortSignal 触发即杀。 */
+declare const spawnRunner: CommandRunner;
+/**
+ * npm 子进程环境：继承宿主环境，附带代理端口（port > 0 时同时给 npm 与
+ * prebuild-install 注入代理——后者只认 `https_proxy` 系列环境变量，
+ * 这是原生依赖 prebuild 下载卡死的正解）。
+ */
+declare function npmEnv(config: AgentPresetReaConfig): Record<string, string>;
+/** 版本收窄：进命令前把配置里的钉版校验成纯版本号。 */
+declare function safeVersion(version: string): string;
+//#endregion
+//#region src/manager.d.ts
+/** npm 包名。 */
+declare const REA_PACKAGE = "rea-agents";
+/** 受管安装树目录名。 */
+declare const REA_INSTALL_DIR = "rea-agent";
+/** 手动更新 skill 的目录名。 */
+declare const REA_SKILL_DIR = "skills";
+/** REA 随包 skill 名（tar 包内路径与目录名同此）。 */
+declare const REA_SKILL_NAME = "reverse-engineer-anything";
+/** 已安装的 REA 事实。 */
+interface ReaInstall {
+  version: string;
+  root: string;
+  /** spawn 用的可执行文件（`process.execPath`，即当前 node）。 */
+  command: string;
+  /** 入口脚本绝对路径（`scripts/rea.mjs`）。 */
+  entry: string;
+}
+/** skill 来源事实。 */
+interface SkillState {
+  /** `bundled` = 随包副本；`updated` = 插件数据目录里的手动更新副本。 */
+  source: 'bundled' | 'updated';
+  /** 来源版本（从清单 source 解析；解析不出为 null）。 */
+  version: string | null;
+  root: string;
+  files: number;
+  updatedAt: string | null;
+}
+/** 运行期事实快照（现探，不进配置；声明组装按它决定 mcp 行与 skill 根）。 */
+interface RuntimeSnapshot {
+  install: ReaInstall | null;
+  skill: SkillState;
+}
+/** skill 清单（与随包夹具同形；更新副本多写入 updatedAt）。 */
+interface SkillManifest {
+  source: string;
+  files: {
+    path: string;
+    sha256: string;
+    bytes: number;
+  }[];
+  updatedAt?: string;
+}
+/** 受管路径。 */
+interface ManagerPaths {
+  installRoot: string;
+  skillRoot: string;
+}
+/** 作业可一次性覆盖的配置项（卡片未保存的代理端口即时生效用）。 */
+interface JobOverrides {
+  proxyPort?: number;
+}
+/** REA 管理面。 */
+interface ReaManager {
+  paths(): ManagerPaths;
+  /** 现探运行期事实（同步；声明组装在 `apply` 期就要读到）。 */
+  snapshot(): RuntimeSnapshot;
+  /** 重新现探并更新快照（作业完成、volatile 变更后调用）。 */
+  refresh(): RuntimeSnapshot;
+  /** 受管作业（安装/更新 REA 包、更新 skill）。 */
+  operations(overrides?: JobOverrides): {
+    install: JobOperation;
+    skill: JobOperation;
+  };
+}
+/** 安装作业阶段名。 */
+declare const INSTALL_PHASES: string[];
+/** skill 作业阶段名。 */
+declare const SKILL_PHASES: string[];
+/**
+ * 解析受管路径：`installRoot` 非空即运维指定位置（部署方平面），
+ * 否则落插件数据目录；skill 更新副本固定落插件数据目录。
+ */
+declare function managerPaths(config: AgentPresetReaConfig): ManagerPaths;
+/**
+ * 探测已安装 REA：包版本可读 **且** 入口脚本存在才算安装完整
+ * （只有一半的安装树、或换目录中断留下的 staging 都不算）。
+ */
+declare function probeInstall(paths: ManagerPaths): ReaInstall | null;
+/** 探测 skill 来源：数据目录里清单完整且技能文件在位才认更新副本。 */
+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 管理器。 */
+declare function createManager(options: {
+  config: () => AgentPresetReaConfig;
+  bundledRoot: string;
+  bundledVersion: string;
+  runner?: CommandRunner;
+}): ReaManager;
+//#endregion
 //#region src/definition.d.ts
 /** 预设注册表身份（改 id 等于换预设，default 等引用都会落空）。 */
 declare const REA_PRESET_ID = "rea";
@@ -53,24 +196,149 @@ declare const ADDED_ROWS: readonly string[];
  * 删除某条等于把该行改回上游原文；改动上游不存在的字段会被测试拦下。
  */
 declare const CONFIG_DELTAS: Readonly<Record<string, readonly string[]>>;
+/** 未安装、随包 skill 的运行期事实（默认值：测试与无 manager 场景）。 */
+declare function emptyRuntime(): RuntimeSnapshot;
 /**
- * 由配置拼出注册表声明。
+ * 由配置 + 运行期事实拼出注册表声明。
  * @param config - 已验证的插件配置。
+ * @param runtime - 受管安装与 skill 来源事实（默认「未安装 + 随包 skill」）。
  * @returns id 固定为 `rea` 的预设声明。
  */
-declare function reaPresetDefinition(config: AgentPresetReaConfig): PresetDefinition;
+declare function reaPresetDefinition(config: AgentPresetReaConfig, runtime?: RuntimeSnapshot): PresetDefinition;
+//#endregion
+//#region src/dto.d.ts
+/**
+ * 宿主半与浏览器半之间的 wire 数据门面（纯类型 + 纯函数，零 node 依赖）。
+ *
+ * 浏览器半只 `import type` 消费本文件（编译期擦除，不进 client bundle），
+ * 两端共用同一份字段定义，避免「宿主改了字段、卡片还在读老名字」的静默漂移。
+ * @module @dsh-plus/agent-preset-rea/dto
+ */
+/** 作业种类。 */
+type JobKind = 'install' | 'skill';
+/** 作业状态。 */
+type JobState = 'running' | 'ok' | 'error' | 'cancelled';
+/** 作业进度（按阶段推进；percent 为进入该阶段时的完成度）。 */
+interface JobProgressDto {
+  step: number;
+  steps: number;
+  phase: string;
+  percent: number;
+}
+/** 作业快照。 */
+interface JobDto {
+  id: number;
+  kind: JobKind;
+  state: JobState;
+  progress: JobProgressDto;
+  /** 日志尾部（宿主已有界）。 */
+  log: string[];
+  startedAt: string;
+  finishedAt: string | null;
+  version: string | null;
+  error: string | null;
+}
+/** 受管安装事实。 */
+interface InstallDto {
+  installed: boolean;
+  /** 已安装版本（未安装为 null）。 */
+  version: string | null;
+  /** 受管安装树位置（无论是否已安装都有值，便于用户核对）。 */
+  root: string;
+  /** 入口脚本（未安装为 null）。 */
+  entry: string | null;
+}
+/** skill 来源事实。 */
+interface SkillDto {
+  source: 'bundled' | 'updated';
+  version: string | null;
+  root: string;
+  files: number;
+  updatedAt: string | null;
+}
+/** MCP 行形态。 */
+interface McpDto {
+  /** `installed` = 用受管安装入口；`custom` = 用显式 mcpCommand；`missing` = 未安装且无显式命令（行禁用）。 */
+  mode: 'installed' | 'custom' | 'missing';
+  /** 行是否启用（mcpEnabled && 有启动方式）。 */
+  enabled: boolean;
+  command: string | null;
+  args: string[];
+}
+/** `GET /status` 响应。 */
+interface StatusDto {
+  config: {
+    reaVersion: string;
+    proxyPort: number;
+    mcpEnabled: boolean;
+    installRoot: string;
+  };
+  install: InstallDto;
+  skill: SkillDto;
+  mcp: McpDto;
+  paths: {
+    installRoot: string;
+    skillRoot: string;
+  };
+  job: JobDto | null;
+}
+/** 作业类响应（启动/取消）。 */
+interface JobActionDto {
+  job: JobDto | null;
+  /** 拒绝原因（409/400 时给出人话）。 */
+  error?: string;
+}
+//#endregion
+//#region src/jobs.d.ts
+/** 作业快照（与 wire DTO 同形，HTTP 直接回传）。 */
+type JobSnapshot = JobDto;
+/** 作业板。 */
+interface JobBoard {
+  /** 启动作业；已有作业在跑时返回 null（调用方回 409）。 */
+  start(kind: JobKind, operation: JobOperation): JobSnapshot | null;
+  /** 取消当前作业（返回是否真的发出取消）。 */
+  cancel(): boolean;
+  /** 当前/最近一次作业快照。 */
+  snapshot(): JobSnapshot | null;
+  /** 订阅作业完成（返回退订函数）。 */
+  onSettled(listener: (snapshot: JobSnapshot) => void): () => void;
+}
+/** 建一个作业板。 */
+declare function createJobBoard(): JobBoard;
 //#endregion
 //#region src/mcp.d.ts
 /** 钉版基线：`rea-agents@6.5.0`（升级时同步测试断言、tests 清单与包文档）。 */
 declare const REA_PINNED_VERSION = "6.5.0";
-/** stdio 启动命令默认值：POSIX 用 `npx`；Windows 需 `cmd.exe /c npx`（见包文档）。 */
+/** 显式命令配 npx 时的参数配方基准值（`mcpArgs` 留空即按它派生）。 */
 declare const DEFAULT_MCP_COMMAND = "npx";
 /** REA 工具入参 schema 广告档位：`compact` 压请求前缀体积，`full` 与上游默认一致。 */
 declare const INPUT_SCHEMA_PROFILES: readonly ['compact', 'full'];
 /** REA 工具出参 schema 广告档位：`off` 不下发（结果仍由 REA 侧校验），`full` 与上游默认一致。 */
 declare const OUTPUT_SCHEMA_PROFILES: readonly ['off', 'full'];
-/** stdio 参数：显式配置优先（Windows/全局安装配方），否则按钉版版本派生。 */
+/** 受管安装的入口事实（结构上由 manager 的 ReaInstall 满足）。 */
+interface InstalledEntry {
+  /** spawn 用的可执行文件。 */
+  command: string;
+  /** 入口脚本绝对路径。 */
+  entry: string;
+}
+/** MCP 行的启动方式。 */
+interface McpLaunch {
+  command: string;
+  args: string[];
+}
+/**
+ * 显式命令（`mcpCommand` 非空）时的参数：`mcpArgs` 优先；
+ * 留空时 npx 走 `-y rea-agents@<钉版> mcp`，其他可执行文件只补 `mcp`。
+ */
 declare function reaMcpArgs(config: AgentPresetReaConfig): string[];
+/**
+ * 本预设 MCP 行的启动方式：
+ * 1. `mcpCommand` 显式配置 → 用用户命令（Windows 配方、全局安装场景）；
+ * 2. 受管安装存在 → 用当前 node 直接跑安装树里的入口脚本（跨平台、不经 shell shim）；
+ * 3. 都没有 → `null`，调用方把该行置 `disabled`（未安装，等卡片上的安装动作）。
+ */
+declare function reaMcpLaunch(config: AgentPresetReaConfig, installed: InstalledEntry | null): McpLaunch | null;
 /**
  * 传给 REA 子进程的环境变量（并入被清洗过的宿主环境之上）。
  *
@@ -117,6 +385,20 @@ interface PresetRegistrar {
  */
 declare function createPresetRegistrar(options: PresetRegistrarOptions): PresetRegistrar;
 //#endregion
+//#region src/routes.d.ts
+/** 路由前缀。 */
+declare const ROUTE_BASE = "/dsh-plus/agent-preset-rea";
+/** 路由依赖。 */
+interface ReaRoutesOptions {
+  manager: ReaManager;
+  board: JobBoard;
+  config: () => AgentPresetReaConfig;
+}
+/** 组装状态响应（纯函数，可直接单测）。 */
+declare function statusPayload(options: ReaRoutesOptions): StatusDto;
+/** 注册全部路由。 */
+declare function registerReaRoutes(ctx: Context, options: ReaRoutesOptions): void;
+//#endregion
 //#region src/skill.d.ts
 /**
  * 随包 REA 官方 skill 根（包内 `skills/`）。
@@ -125,8 +407,12 @@ declare function createPresetRegistrar(options: PresetRegistrarOptions): PresetR
  * 运行产物两种位置下解析到同一目录。
  */
 declare const BUNDLED_SKILL_ROOT: string;
-/** skill-filesystem 的追加根清单：随包 REA skill 在前，配置追加目录随后。 */
-declare function reaSkillDirs(config: AgentPresetReaConfig): string[];
+/**
+ * skill-filesystem 的追加根清单。
+ * @param config - 插件配置。
+ * @param updatedRoot - 手动更新副本根（存在即替代随包根；来自 manager 现探）。
+ */
+declare function reaSkillDirs(config: AgentPresetReaConfig, updatedRoot?: string | null): string[];
 //#endregion
 //#region src/index.d.ts
 declare const name = "dsh-plus-agent-preset-rea";
@@ -142,4 +428,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, Config, DEFAULT_MCP_COMMAND, INPUT_SCHEMA_PROFILES, OUTPUT_SCHEMA_PROFILES, PLAN_MODE_SECTION, type PresetRegistrar, REA_PINNED_VERSION, REA_PRESET_ID, SETTINGS_NS, type Unregister, apply, createPresetRegistrar, inject, name, reaMcpArgs, reaMcpEnv, reaPresetDefinition, reaSkillDirs };
+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 };