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

package/src/manager.ts

@@ -0,0 +1,424 @@
+/**
+ * REA 的受管安装与状态探测：把「REA 包」与「REA skill」都变成插件自己管理的本机资源，
+ * 从而摆脱启动期 `npx -y` 拉取（那会在 boot 里跑 npm 安装脚本：原生依赖
+ * `@lydell/node-pty` 的 prebuild 下载一旦卡住，预设激活就不返回，名册与插件页
+ * 一起被吊住；事故经过见 docs/README.md「启动期拉取的教训」）。
+ *
+ * 落点（属插件数据，不进 settings，见 @dsh-plus/shared/plugin-data；插件数据目录名
+ * 取插件 id `dsh-plus-agent-preset-rea`）：
+ * - REA 包：`<DSH_HOME>/dsh-plus/dsh-plus-agent-preset-rea/rea-agent/`（npm --prefix
+ *   安装树；入口 `node_modules/rea-agents/scripts/rea.mjs`，用 `process.execPath` 直接
+ *   spawn，跨平台不经 shell shim）；
+ * - 手动更新的 skill：`<DSH_HOME>/dsh-plus/dsh-plus-agent-preset-rea/skills/`
+ *   （根下是 `<技能名>/` + `manifest.json`，与随包 `skills/` 同构；
+ *   清单完整时替代随包 skill 根）。
+ *
+ * 作业都是「先落 staging 再换目录」：中断只留下 staging，不会让半截安装树被当成可用
+ * 安装；换目录后清理旧树，运行中的旧进程按 POSIX 语义继续持有已打开文件。
+ *
+ * 外部进程经 {@link CommandRunner} 注入（见 exec.ts），单测用假 runner 跑完整状态机。
+ * @module @dsh-plus/agent-preset-rea/manager
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { pluginDataPath } from '@dsh-plus/shared'
+
+import type { AgentPresetReaConfig } from './config.ts'
+import {
+  type CommandRunner,
+  countFiles,
+  type JobDeps,
+  type JobOperation,
+  type JobTaskContext,
+  lineSink,
+  listFiles,
+  NPM,
+  npmEnv,
+  safeVersion,
+  spawnRunner,
+} from './exec.ts'
+import { probeReverse, REVERSE_PHASES, type ReverseState, runReverseSkillJob } from './reverse.ts'
+
+export type { JobDeps }
+
+/** npm 包名。 */
+export const REA_PACKAGE = 'rea-agents'
+
+/** 受管安装树目录名。 */
+export const REA_INSTALL_DIR = 'rea-agent'
+
+/** 手动更新 skill 的目录名。 */
+export const REA_SKILL_DIR = 'skills'
+
+/** REA 随包 skill 名（tar 包内路径与目录名同此）。 */
+export const REA_SKILL_NAME = 'reverse-engineer-anything'
+
+/** 插件数据目录标识（`<DSH_HOME>/dsh-plus/<id>`）。 */
+const PLUGIN_ID = 'dsh-plus-agent-preset-rea'
+
+/** 已安装的 REA 事实。 */
+export interface ReaInstall {
+  version: string
+  root: string
+  /** spawn 用的可执行文件（`process.execPath`，即当前 node）。 */
+  command: string
+  /** 入口脚本绝对路径（`scripts/rea.mjs`）。 */
+  entry: string
+}
+
+/** skill 来源事实。 */
+export interface SkillState {
+  /** `bundled` = 随包副本；`updated` = 插件数据目录里的手动更新副本。 */
+  source: 'bundled' | 'updated'
+  /** 来源版本（从清单 source 解析；解析不出为 null）。 */
+  version: string | null
+  root: string
+  files: number
+  updatedAt: string | null
+}
+
+/** 运行期事实快照（现探，不进配置；声明组装按它决定 mcp 行与 skill 根）。 */
+export interface RuntimeSnapshot {
+  install: ReaInstall | null
+  skill: SkillState
+  /** GitHub 技能源（zhaoxuya520/reverse-skill）现状。 */
+  reverse: ReverseState
+}
+
+/** skill 清单（与随包夹具同形；更新副本多写入 updatedAt）。 */
+export interface SkillManifest {
+  source: string
+  files: { path: string; sha256: string; bytes: number }[]
+  updatedAt?: string
+}
+
+/** 受管路径。 */
+export interface ManagerPaths {
+  installRoot: string
+  skillRoot: string
+}
+
+/** 作业可一次性覆盖的配置项（卡片未保存的代理端口即时生效用）。 */
+export interface JobOverrides {
+  proxyPort?: number
+}
+
+/** REA 管理面。 */
+export interface ReaManager {
+  paths(): ManagerPaths
+  /** 现探运行期事实（同步；声明组装在 `apply` 期就要读到）。 */
+  snapshot(): RuntimeSnapshot
+  /** 重新现探并更新快照（作业完成、volatile 变更后调用）。 */
+  refresh(): RuntimeSnapshot
+  /** 受管作业（安装/更新 REA 包、更新 REA skill、更新 reverse-skill）。 */
+  operations(overrides?: JobOverrides): {
+    install: JobOperation
+    skill: JobOperation
+    reverse: JobOperation
+  }
+}
+
+/** 安装作业阶段名。 */
+export const INSTALL_PHASES: string[] = [
+  '解析版本信息',
+  `下载并安装 ${REA_PACKAGE}`,
+  '替换安装目录',
+  '校验安装',
+]
+
+/** skill 作业阶段名。 */
+export const SKILL_PHASES: string[] = [
+  '解析版本信息',
+  '下载 skill 包',
+  '解包 skills',
+  '校验并写入清单',
+]
+
+/**
+ * 解析受管路径：`installRoot` 非空即运维指定位置（部署方平面），
+ * 否则落插件数据目录；skill 更新副本固定落插件数据目录。
+ */
+export function managerPaths(config: AgentPresetReaConfig): ManagerPaths {
+  const root = config.installRoot.trim()
+  return {
+    installRoot: root === '' ? pluginDataPath(PLUGIN_ID, REA_INSTALL_DIR) : root,
+    skillRoot: pluginDataPath(PLUGIN_ID, REA_SKILL_DIR),
+  }
+}
+
+/** 读 JSON（不存在或坏内容返回 null）。 */
+function readJson(file: string): unknown {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as unknown
+  } catch {
+    return null
+  }
+}
+
+/** 记录型守卫。 */
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null
+}
+
+/** 安装树内固定入口：`node_modules/rea-agents/scripts/rea.mjs`。 */
+function reaEntryFile(root: string): string {
+  return join(root, 'node_modules', REA_PACKAGE, 'scripts', 'rea.mjs')
+}
+
+/** 从清单 source（`rea-agents@1.2.3`）解析版本。 */
+function versionOfSource(source: string): string | null {
+  const prefix = `${REA_PACKAGE}@`
+  return source.startsWith(prefix) ? source.slice(prefix.length) : null
+}
+
+/**
+ * 探测已安装 REA：包版本可读 **且** 入口脚本存在才算安装完整
+ * （只有一半的安装树、或换目录中断留下的 staging 都不算）。
+ */
+export function probeInstall(paths: ManagerPaths): ReaInstall | null {
+  const pkg = asRecord(
+    readJson(join(paths.installRoot, 'node_modules', REA_PACKAGE, 'package.json')),
+  )
+  const version = typeof pkg?.['version'] === 'string' ? pkg['version'] : null
+  const entry = reaEntryFile(paths.installRoot)
+  if (version === null || !existsSync(entry)) return null
+  return { version, root: paths.installRoot, command: process.execPath, entry }
+}
+
+/** 探测 skill 来源：数据目录里清单完整且技能文件在位才认更新副本。 */
+export function probeSkill(
+  paths: ManagerPaths,
+  bundledRoot: string,
+  bundledVersion: string,
+): SkillState {
+  const manifest = asRecord(readJson(join(paths.skillRoot, 'manifest.json')))
+  const source = typeof manifest?.['source'] === 'string' ? manifest['source'] : null
+  const files = Array.isArray(manifest?.['files']) ? manifest['files'].length : 0
+  if (
+    source !== null &&
+    files > 0 &&
+    existsSync(join(paths.skillRoot, REA_SKILL_NAME, 'SKILL.md'))
+  ) {
+    return {
+      source: 'updated',
+      version: versionOfSource(source),
+      root: paths.skillRoot,
+      files,
+      updatedAt: typeof manifest?.['updatedAt'] === 'string' ? manifest['updatedAt'] : null,
+    }
+  }
+  return {
+    source: 'bundled',
+    version: bundledVersion,
+    root: bundledRoot,
+    files: countFiles(bundledRoot),
+    updatedAt: null,
+  }
+}
+
+/** 现探运行期事实。 */
+export function probeRuntime(
+  config: AgentPresetReaConfig,
+  bundledRoot: string,
+  bundledVersion: string,
+): RuntimeSnapshot {
+  const paths = managerPaths(config)
+  return {
+    install: probeInstall(paths),
+    skill: probeSkill(paths, bundledRoot, bundledVersion),
+    reverse: probeReverse(config),
+  }
+}
+
+/**
+ * 解析钉版在 registry 上的实际版本：顺带做存在性校验（失败即报错，
+ * 而不是装出一棵空树让 MCP 行指向不存在的入口）。
+ */
+async function resolveVersion(deps: JobDeps, ctx: JobTaskContext, wanted: string): Promise<void> {
+  ctx.phase(0)
+  const lines: string[] = []
+  const result = await deps.runner.run(
+    NPM,
+    ['view', `${REA_PACKAGE}@${wanted}`, 'version', '--json'],
+    {
+      env: npmEnv(deps.config),
+      signal: ctx.signal,
+      onLine: (line) => {
+        lines.push(line)
+        lineSink(ctx)(line)
+      },
+    },
+  )
+  if (result.code !== 0) throw new Error(`registry 上找不到 ${REA_PACKAGE}@${wanted}`)
+  const reported = lines.join('').replace(/["\s]/g, '')
+  if (reported !== '' && reported !== wanted) {
+    ctx.log(`registry 返回 ${reported}（配置钉的是 ${wanted}）`)
+  }
+}
+
+/** 装到 staging 并清掉失败现场的公共包壳。 */
+async function npmInstall(deps: JobDeps, ctx: JobTaskContext, staging: string): Promise<void> {
+  const version = safeVersion(deps.config.reaVersion)
+  await rm(staging, { recursive: true, force: true })
+  const result = await deps.runner.run(
+    NPM,
+    [
+      'install',
+      '--prefix',
+      staging,
+      '--no-audit',
+      '--no-fund',
+      '--loglevel',
+      'http',
+      `${REA_PACKAGE}@${version}`,
+    ],
+    { env: npmEnv(deps.config), signal: ctx.signal, onLine: lineSink(ctx) },
+  )
+  if (result.code !== 0) {
+    await rm(staging, { recursive: true, force: true })
+    throw new Error(`npm install 失败（退出码 ${result.code}）`)
+  }
+}
+
+/** 安装/更新 REA 包：staging 安装 → 换目录 → 校验入口可读。 */
+export async function runInstallJob(deps: JobDeps, ctx: JobTaskContext): Promise<string> {
+  const version = safeVersion(deps.config.reaVersion)
+  const root = managerPaths(deps.config).installRoot
+  const staging = `${root}.staging`
+  await resolveVersion(deps, ctx, version)
+
+  ctx.phase(1)
+  await npmInstall(deps, ctx, staging)
+
+  ctx.phase(2)
+  const backup = `${root}.old`
+  await rm(backup, { recursive: true, force: true })
+  if (existsSync(root)) await rename(root, backup)
+  await rename(staging, root)
+  await rm(backup, { recursive: true, force: true })
+
+  ctx.phase(3)
+  const probe = probeInstall(managerPaths(deps.config))
+  if (probe === null) throw new Error('安装校验失败：入口脚本不可用')
+  deps.refresh()
+  ctx.log(`已安装 ${REA_PACKAGE}@${probe.version} → ${probe.root}`)
+  return probe.version
+}
+
+/** 逐文件 sha256（相对路径 + 字节数）。 */
+function hashFiles(dir: string): SkillManifest['files'] {
+  return listFiles(dir).map((path) => {
+    const bytes = readFileSync(join(dir, path))
+    return { path, sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length }
+  })
+}
+
+/** 从 tar 包取钉版 skill 目录（副本根与随包 `skills/` 同构：只 strip 两层）。 */
+async function unpackSkill(
+  deps: JobDeps,
+  ctx: JobTaskContext,
+  staging: string,
+  tree: string,
+): Promise<void> {
+  const version = safeVersion(deps.config.reaVersion)
+  await rm(staging, { recursive: true, force: true })
+  await mkdir(staging, { recursive: true })
+  const packed = await deps.runner.run(
+    NPM,
+    ['pack', `${REA_PACKAGE}@${version}`, '--pack-destination', staging, '--loglevel', 'http'],
+    { env: npmEnv(deps.config), signal: ctx.signal, onLine: lineSink(ctx) },
+  )
+  if (packed.code !== 0) {
+    await rm(staging, { recursive: true, force: true })
+    throw new Error(`npm pack 失败（退出码 ${packed.code}）`)
+  }
+  const tarball = readdirSync(staging).find((name) => name.endsWith('.tgz'))
+  if (tarball === undefined) throw new Error('npm pack 未产出 tarball')
+
+  ctx.phase(2)
+  await mkdir(tree, { recursive: true })
+  const untar = await deps.runner.run(
+    'tar',
+    [
+      '-xzf',
+      join(staging, tarball),
+      '-C',
+      tree,
+      '--strip-components=2',
+      `package/skills/${REA_SKILL_NAME}`,
+    ],
+    { env: npmEnv(deps.config), signal: ctx.signal, onLine: lineSink(ctx) },
+  )
+  if (untar.code !== 0) {
+    await rm(staging, { recursive: true, force: true })
+    throw new Error(`tar 解包失败（退出码 ${untar.code}）`)
+  }
+}
+
+/** 拉取钉版 tarball 并替换手动更新的 skill 副本（写 sha256 清单后换目录）。 */
+export async function runSkillJob(deps: JobDeps, ctx: JobTaskContext): Promise<string> {
+  const version = safeVersion(deps.config.reaVersion)
+  const root = managerPaths(deps.config).skillRoot
+  const staging = `${root}.staging`
+  const tree = join(staging, 'tree')
+  await resolveVersion(deps, ctx, version)
+  ctx.phase(1)
+  await unpackSkill(deps, ctx, staging, tree)
+
+  ctx.phase(3)
+  const files = hashFiles(tree)
+  if (files.length === 0) throw new Error('解包结果为空：上游 skill 目录结构可能已变')
+  const manifest: SkillManifest = {
+    source: `${REA_PACKAGE}@${version}`,
+    files,
+    updatedAt: new Date().toISOString(),
+  }
+  await writeFile(join(tree, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  await rm(root, { recursive: true, force: true })
+  await rename(tree, root)
+  await rm(staging, { recursive: true, force: true })
+  deps.refresh()
+  ctx.log(`已更新 skill ${REA_SKILL_NAME}（${files.length} 文件）→ ${root}`)
+  return version
+}
+
+/** 生效配置：作业可带一次性覆盖（卡片未保存的代理端口即时可用）。 */
+export function configWith(
+  base: AgentPresetReaConfig,
+  overrides?: JobOverrides,
+): AgentPresetReaConfig {
+  if (overrides?.proxyPort === undefined) return base
+  return { ...base, proxyPort: overrides.proxyPort }
+}
+
+/** 建一个 REA 管理器。 */
+export function createManager(options: {
+  config: () => AgentPresetReaConfig
+  bundledRoot: string
+  bundledVersion: string
+  runner?: CommandRunner
+}): ReaManager {
+  const runner = options.runner ?? spawnRunner
+  const paths = (): ManagerPaths => managerPaths(options.config())
+  let cache: RuntimeSnapshot | null = null
+  const refresh = (): RuntimeSnapshot => {
+    cache = probeRuntime(options.config(), options.bundledRoot, options.bundledVersion)
+    return cache
+  }
+  return {
+    paths,
+    refresh,
+    snapshot: () => cache ?? refresh(),
+    operations: (overrides) => {
+      const deps: JobDeps = { config: configWith(options.config(), overrides), runner, refresh }
+      return {
+        install: { phases: INSTALL_PHASES, run: (ctx) => runInstallJob(deps, ctx) },
+        skill: { phases: SKILL_PHASES, run: (ctx) => runSkillJob(deps, ctx) },
+        reverse: { phases: REVERSE_PHASES, run: (ctx) => runReverseSkillJob(deps, ctx) },
+      }
+    },
+  }
+}

package/src/mcp.ts

@@ -1,9 +1,14 @@
 /**
- * REA MCP 行的取值派生：钉版版本、stdio 启动命令与参数、入参 schema 档位。
+ * REA MCP 行的取值派生：启动方式（受管安装入口 or 显式命令）、参数、入参/出参 schema 档位。
  *
  * REA 的 stdio 入口是 `rea-agents mcp`（`server.json` 的 positional 参数），
  * 包版本钉在 {@link REA_PINNED_VERSION}——升级只改这一个常量，漂移由测试拦住。
  * REA 的 Node 引擎要求为 `^22.19 || ^24.11 || >=26`（见 REA `docs/installation.md`）。
+ *
+ * **默认不 spawn npx**：启动期 `npx -y` 会跑 npm 安装脚本（原生依赖 prebuild 下载），
+ * 一旦卡住就把预设激活与整棵名册一起吊住；因此默认只认受管安装入口（见 manager.ts），
+ * 未安装时该行 `disabled`，安装入口在插件页卡片上。`mcpCommand` 显式配置时按用户
+ * 命令启动（经典 npx 配方仍可用，风险自负）。
  * @module @dsh-plus/agent-preset-rea/mcp
  */
 import type { AgentPresetReaConfig } from './config.ts'
@@ -11,7 +16,7 @@ import type { AgentPresetReaConfig } from './config.ts'
 /** 钉版基线：`rea-agents@6.5.0`（升级时同步测试断言、tests 清单与包文档）。 */
 export const REA_PINNED_VERSION = '6.5.0'
 
-/** stdio 启动命令默认值：POSIX 用 `npx`；Windows 需 `cmd.exe /c npx`（见包文档）。 */
+/** 显式命令配 npx 时的参数配方基准值（`mcpArgs` 留空即按它派生）。 */
 export const DEFAULT_MCP_COMMAND = 'npx'
 
 /** REA 工具入参 schema 广告档位：`compact` 压请求前缀体积，`full` 与上游默认一致。 */
@@ -20,11 +25,47 @@ export const INPUT_SCHEMA_PROFILES = ['compact', 'full'] as const
 /** REA 工具出参 schema 广告档位：`off` 不下发（结果仍由 REA 侧校验），`full` 与上游默认一致。 */
 export const OUTPUT_SCHEMA_PROFILES = ['off', 'full'] as const
 
-/** stdio 参数：显式配置优先（Windows/全局安装配方），否则按钉版版本派生。 */
+/** 受管安装的入口事实（结构上由 manager 的 ReaInstall 满足）。 */
+export interface InstalledEntry {
+  /** spawn 用的可执行文件。 */
+  command: string
+  /** 入口脚本绝对路径。 */
+  entry: string
+}
+
+/** MCP 行的启动方式。 */
+export interface McpLaunch {
+  command: string
+  args: string[]
+}
+
+/**
+ * 显式命令（`mcpCommand` 非空）时的参数：`mcpArgs` 优先；
+ * 留空时 npx 走 `-y rea-agents@<钉版> mcp`，其他可执行文件只补 `mcp`。
+ */
 export function reaMcpArgs(config: AgentPresetReaConfig): string[] {
-  return config.mcpArgs.length > 0
-    ? [...config.mcpArgs]
-    : ['-y', `rea-agents@${config.reaVersion}`, 'mcp']
+  if (config.mcpArgs.length > 0) return [...config.mcpArgs]
+  return config.mcpCommand === DEFAULT_MCP_COMMAND
+    ? ['-y', `rea-agents@${config.reaVersion}`, 'mcp']
+    : ['mcp']
+}
+
+/**
+ * 本预设 MCP 行的启动方式：
+ * 1. `mcpCommand` 显式配置 → 用用户命令（Windows 配方、全局安装场景）；
+ * 2. 受管安装存在 → 用当前 node 直接跑安装树里的入口脚本（跨平台、不经 shell shim）；
+ * 3. 都没有 → `null`，调用方把该行置 `disabled`（未安装，等卡片上的安装动作）。
+ */
+export function reaMcpLaunch(
+  config: AgentPresetReaConfig,
+  installed: InstalledEntry | null,
+): McpLaunch | null {
+  if (config.mcpCommand.trim() !== '') {
+    return { command: config.mcpCommand, args: reaMcpArgs(config) }
+  }
+  if (installed === null) return null
+  const extra = config.mcpArgs.length > 0 ? [...config.mcpArgs] : ['mcp']
+  return { command: installed.command, args: [installed.entry, ...extra] }
 }
 
 /**