@dsh-plus/agent-preset-rea 0.0.0-stage → 0.1.1

package/lib/index.d.ts

@@ -0,0 +1,431 @@
+import { UnwrapVolatile } from "@dsh-plus/shared";
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+import { PresetDefinition } from "@deepseek-ai/dsh-agent-preset-registry";
+//#region src/config.d.ts
+/** settings 命名空间（字面量即合法命名空间；配置卡片与运行期读取同一份）。 */
+declare const SETTINGS_NS = "dsh-plus-agent-preset-rea";
+declare const Config: z<Schemastery.ObjectS<NoInfer<{
+  enabled: z<boolean, boolean, "defined">;
+  name: z<string, string, "defined">;
+  description: z<string, string, "defined">;
+  order: z<number, number, "defined">;
+  personaPrefix: z<string, string, "volatile-defined">;
+  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">;
+  outputSchemaProfile: z<"full" | "off", "full" | "off", "defined">;
+  toolCallTimeoutMs: z<number, number, "defined">;
+  failOnStartupError: z<boolean, boolean, "defined">;
+  extraSkillDirs: z<string[], string[], "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+  enabled: z<boolean, boolean, "defined">;
+  name: z<string, string, "defined">;
+  description: z<string, string, "defined">;
+  order: z<number, number, "defined">;
+  personaPrefix: z<string, string, "volatile-defined">;
+  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">;
+  outputSchemaProfile: z<"full" | "off", "full" | "off", "defined">;
+  toolCallTimeoutMs: z<number, number, "defined">;
+  failOnStartupError: z<boolean, boolean, "defined">;
+  extraSkillDirs: z<string[], string[], "defined">;
+}>>, "plain">;
+/** 活动字段形态（loader 解析产物：`personaPrefix` 为活动引用）。 */
+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";
+/** 相对上游 `standard` 新增的行 id（镜像测试按此白名单放行自造行）。 */
+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, 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";
+/** 显式命令配 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'];
+/** 受管安装的入口事实（结构上由 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 子进程的环境变量（并入被清洗过的宿主环境之上）。
+ *
+ * REA 有 207 个工具（`server.json` 同版的 skill 元数据 `tool_count`），工具定义
+ * 是每轮请求的固定开销，因此两个 schema 档位默认都取最省的一档；REA 自己仍按
+ * 规范契约校验结果，`full` 可逐项还原上游默认。
+ */
+declare function reaMcpEnv(config: AgentPresetReaConfig): Record<string, string>;
+//#endregion
+//#region src/prompt.d.ts
+/**
+ * 本包随包携带的上游提示词文本：`standard` 预设 `plan-mode` 行的 section 原文。
+ *
+ * `dsh-plan-mode` 要求 `config.section` 非空（部署方所有权），因此该文本必须随包；
+ * 逐字相等由 tests/upstream-mirror.test.ts 对着上游夹具守卫，上游一改即失败。
+ *
+ * persona 不在本文件：本预设的 persona 前缀默认为**空串**（见 config.ts 的
+ * `personaPrefix`），不随包任何自有 persona 文案；官方工具指引、项目指令
+ * （AGENTS.md）与运行时上下文照常装配。
+ * @module @dsh-plus/agent-preset-rea/prompt
+ */
+/** 上游 `standard` 预设 `plan-mode` 行的 section 原文（逐字，勿手改）。 */
+declare const PLAN_MODE_SECTION = "You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.\n\nExplore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.\n\nThe tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.\n\nResolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.\n\nMake the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.\n\nWhen ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask \"should I proceed?\" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.\n";
+//#endregion
+//#region src/registration.d.ts
+/** 注册表返回的注销句柄。 */
+type Unregister = () => Promise<void>;
+interface PresetRegistrarOptions {
+  /** 注册一份声明，返回其注销句柄（即 `ctx.agentPresets.register`）。 */
+  register(definition: PresetDefinition): Promise<Unregister>;
+  /** 按当前配置构造声明（每次换代重新调用，读到的必须是活值）。 */
+  build(): PresetDefinition;
+  /** 注册/注销失败的上报口（不抛）。 */
+  onError(error: unknown): void;
+}
+/** 换代器：`refresh()` 触发一次换代，`dispose()` 停用并注销。 */
+interface PresetRegistrar {
+  refresh(): void;
+  dispose(): void;
+}
+/**
+ * 建一个换代器并立即调度初始注册。
+ * 后台串行链不返回句柄：需要等待完成的是测试与调用方的关停流程，而不是业务路径。
+ */
+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/`）。
+ *
+ * `src/` 与构建产物 `lib/` 同为包根下一级，`../skills` 在源码直跑测试与安装后
+ * 运行产物两种位置下解析到同一目录。
+ */
+declare const BUNDLED_SKILL_ROOT: 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";
+/** 无硬 inject：agentPresets 经 apply 内惰性 inject 接线（缺席即空转）。 */
+declare const inject: readonly [];
+/**
+ * 注册 rea 预设，并在 persona 热更后换代；卸载时注销当前一代。
+ *
+ * 注册与换代都在 effect 生命周期内完成：fiber 早于注册完成被卸下时，
+ * 换代器自己收掉晚到的 disposer，不泄漏预设子树。
+ * @param ctx - 宿主上下文。
+ * @param config - 已验证的插件配置（`personaPrefix` 为活动引用）。
+ */
+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 };