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

package/src/jobs.ts

@@ -0,0 +1,145 @@
+/**
+ * 单作业作业板：同一时刻只允许一个安装/更新作业，快照供 HTTP 轮询，
+ * 完成后回调订阅者（宿主据此换代注册预设声明）。
+ *
+ * 进度按「阶段」推进（`percent = step / steps`）：安装类作业的外部命令不产出可靠
+ * 字节进度，硬造百分比是骗人；阶段 + 实时日志尾部 + 起止时间才是可核对的事实。
+ * 日志只保留尾部 {@link JOB_LOG_LIMIT} 行（回传浏览器，必须有界）。
+ *
+ * 状态放在 {@link BoardState} 里、函数都提到模块级：卡片/端点/测试三方共享同一份
+ * 语义，单个函数也保持在可读长度内（仓库门禁：函数 60/150 行）。
+ * @module @dsh-plus/agent-preset-rea/jobs
+ */
+import type { JobDto, JobKind, JobProgressDto } from './dto.ts'
+import { JobCancelled, type JobOperation, type JobTaskContext } from './exec.ts'
+
+/** 作业进度（与 wire DTO 同形）。 */
+export type JobProgress = JobProgressDto
+
+/** 作业快照（与 wire DTO 同形，HTTP 直接回传）。 */
+export type JobSnapshot = JobDto
+
+/** 作业板。 */
+export interface JobBoard {
+  /** 启动作业；已有作业在跑时返回 null（调用方回 409）。 */
+  start(kind: JobKind, operation: JobOperation): JobSnapshot | null
+  /** 取消当前作业（返回是否真的发出取消）。 */
+  cancel(): boolean
+  /** 当前/最近一次作业快照。 */
+  snapshot(): JobSnapshot | null
+  /** 订阅作业完成（返回退订函数）。 */
+  onSettled(listener: (snapshot: JobSnapshot) => void): () => void
+}
+
+/** 日志尾部保留行数。 */
+export const JOB_LOG_LIMIT = 200
+
+/** 作业板可变状态（函数按引用操作它，不靠闭包嵌套）。 */
+interface BoardState {
+  seq: number
+  current: JobSnapshot | null
+  abort: AbortController | null
+  listeners: Set<(snapshot: JobSnapshot) => void>
+}
+
+/** 阶段序号 → 进度（进入该阶段即报该阶段起点百分比）。 */
+function progressOf(operation: JobOperation, step: number): JobProgress {
+  const steps = operation.phases.length
+  return {
+    step: step + 1,
+    steps,
+    phase: operation.phases[step] ?? '',
+    percent: steps === 0 ? 0 : Math.round((step / steps) * 100),
+  }
+}
+
+/** 落定：写状态 + 通知订阅者（订阅者异常不得影响状态机）。 */
+function settleJob(state: BoardState, patch: Partial<JobSnapshot>): void {
+  const base = state.current
+  if (base === null) return
+  state.current = { ...base, ...patch, finishedAt: new Date().toISOString() }
+  for (const listener of [...state.listeners]) {
+    try {
+      listener(state.current)
+    } catch {
+      // 订阅者异常不影响作业板状态
+    }
+  }
+}
+
+/** 兜底进度形状（正常路径下 `state.current` 必有值，这里只防类型上的缺席）。 */
+const ZERO_PROGRESS: JobProgress = { step: 1, steps: 1, phase: '', percent: 0 }
+
+/** 收尾：成功记 ok + 版本，失败区分「取消」与「真失败」。 */
+function finishJob(state: BoardState, error: unknown, version: string | null): void {
+  if (version !== null) {
+    const progress = { ...(state.current?.progress ?? ZERO_PROGRESS), percent: 100 }
+    settleJob(state, { state: 'ok', version, progress })
+    return
+  }
+  const cancelled = error instanceof JobCancelled || state.abort?.signal.aborted === true
+  settleJob(state, {
+    state: cancelled ? 'cancelled' : 'error',
+    error: cancelled ? null : error instanceof Error ? error.message : String(error),
+  })
+}
+
+/** 起一个作业并挂上状态机（调用方已确认当前无运行中作业）。 */
+function startJob(state: BoardState, kind: JobKind, operation: JobOperation): JobSnapshot {
+  const controller = new AbortController()
+  state.abort = controller
+  state.seq += 1
+  const snapshot: JobSnapshot = {
+    id: state.seq,
+    kind,
+    state: 'running',
+    progress: progressOf(operation, 0),
+    log: [],
+    startedAt: new Date().toISOString(),
+    finishedAt: null,
+    version: null,
+    error: null,
+  }
+  state.current = snapshot
+  const push = (patch: Partial<JobSnapshot>): void => {
+    if (state.current !== null) state.current = { ...state.current, ...patch }
+  }
+  const ctx: JobTaskContext = {
+    phase: (step) => push({ progress: progressOf(operation, step) }),
+    log: (line) => push({ log: [...(state.current?.log ?? []), line].slice(-JOB_LOG_LIMIT) }),
+    signal: controller.signal,
+  }
+  void operation
+    .run(ctx)
+    .then(
+      (version) => finishJob(state, null, version),
+      (error: unknown) => finishJob(state, error, null),
+    )
+    .finally(() => {
+      state.abort = null
+    })
+  return snapshot
+}
+
+/** 取消当前作业。 */
+function cancelJob(state: BoardState): boolean {
+  // 只看状态：落定后 finally 还没跑（微任务次序），按 abort 句柄判断会误报「已取消」。
+  if (state.abort === null || state.current?.state !== 'running') return false
+  state.abort.abort()
+  return true
+}
+
+/** 建一个作业板。 */
+export function createJobBoard(): JobBoard {
+  const state: BoardState = { seq: 0, current: null, abort: null, listeners: new Set() }
+  return {
+    start: (kind, operation) =>
+      state.current?.state === 'running' ? null : startJob(state, kind, operation),
+    cancel: () => cancelJob(state),
+    snapshot: () => state.current,
+    onSettled: (listener) => {
+      state.listeners.add(listener)
+      return () => state.listeners.delete(listener)
+    },
+  }
+}

package/src/manager.ts

@@ -0,0 +1,419 @@
+/**
+ * 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 JobOperation,
+  type JobTaskContext,
+  lineSink,
+  listFiles,
+  NPM,
+  npmEnv,
+  safeVersion,
+  spawnRunner,
+} from './exec.ts'
+
+/** 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
+}
+
+/** 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 包、更新 skill）。 */
+  operations(overrides?: JobOverrides): { install: JobOperation; skill: 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),
+  }
+}
+
+/** 作业依赖：生效配置、命令执行面、作业完成后的现探刷新。 */
+export interface JobDeps {
+  config: AgentPresetReaConfig
+  runner: CommandRunner
+  refresh(): void
+}
+
+/**
+ * 解析钉版在 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) },
+      }
+    },
+  }
+}

package/src/mcp.ts

@@ -0,0 +1,83 @@
+/**
+ * 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'
+
+/** 钉版基线：`rea-agents@6.5.0`（升级时同步测试断言、tests 清单与包文档）。 */
+export const REA_PINNED_VERSION = '6.5.0'
+
+/** 显式命令配 npx 时的参数配方基准值（`mcpArgs` 留空即按它派生）。 */
+export const DEFAULT_MCP_COMMAND = 'npx'
+
+/** REA 工具入参 schema 广告档位：`compact` 压请求前缀体积，`full` 与上游默认一致。 */
+export const INPUT_SCHEMA_PROFILES = ['compact', 'full'] as const
+
+/** REA 工具出参 schema 广告档位：`off` 不下发（结果仍由 REA 侧校验），`full` 与上游默认一致。 */
+export const OUTPUT_SCHEMA_PROFILES = ['off', 'full'] as const
+
+/** 受管安装的入口事实（结构上由 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[] {
+  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] }
+}
+
+/**
+ * 传给 REA 子进程的环境变量（并入被清洗过的宿主环境之上）。
+ *
+ * REA 有 207 个工具（`server.json` 同版的 skill 元数据 `tool_count`），工具定义
+ * 是每轮请求的固定开销，因此两个 schema 档位默认都取最省的一档；REA 自己仍按
+ * 规范契约校验结果，`full` 可逐项还原上游默认。
+ */
+export function reaMcpEnv(config: AgentPresetReaConfig): Record<string, string> {
+  return {
+    REA_MCP_INPUT_SCHEMA_PROFILE: config.inputSchemaProfile,
+    REA_MCP_OUTPUT_SCHEMA_PROFILE: config.outputSchemaProfile,
+  }
+}

package/src/ns.ts

@@ -0,0 +1,9 @@
+/**
+ * settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
+ *
+ * 服务端以字面量参与 `Config` 的活动字段（dsh-settings 对命名空间做语法校验），
+ * 浏览器半把它作为配置卡片的注册键（插件页配置卡片挂在 row/bundle config 槽位上，
+ * 与命名空间解耦，见 shared/client/config-slots）；同一字面量两处共用，防止漂移。
+ * @module @dsh-plus/agent-preset-rea/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-agent-preset-rea'

package/src/prompt.ts

@@ -0,0 +1,25 @@
+/**
+ * 本包随包携带的上游提示词文本：`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 原文（逐字，勿手改）。 */
+export 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.
+
+Explore 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.
+
+The 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.
+
+Resolve 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.
+
+Make 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.
+
+When 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.
+`