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

package/src/definition.ts

@@ -0,0 +1,245 @@
+/**
+ * 逆向工程预设声明组装：官方 `standard` 预设**全量行**的逐字镜像 + 三处显式增量。
+ *
+ * 镜像：每条上游行的 `id`/`name`/`config`（含平台门控 `!!js` 表达式与 plan-mode
+ * 段落原文）都与 `@deepseek-ai/dsh-web-app` 的 `presets/standard.patch.yml` 逐字一致；
+ * 上游改用新版本后按 docs/ops/新版适配流程.md 刷新夹具，
+ * tests/upstream-mirror.test.ts 会逼出对齐。本预设不丢任何上游行（与 lean 相反）。
+ *
+ * 增量仅三处，测试按 {@link ADDED_ROWS} / {@link CONFIG_DELTAS} 白名单放行：
+ * 1. `persona` 行 `prefix` 取配置值（默认空串 = 空 persona）；
+ * 2. `skill-filesystem` 行加 `customSkillDirs`（随包 REA skill 或手动更新副本 + 追加目录）；
+ * 3. 新增 `mcp-rea` 行：官方 MCP 客户端连 REA stdio 服务，落在本预设作用域内；
+ *    **未安装 REA 时该行 `disabled`**（不 spawn npx，见 mcp.ts 的说明）。
+ *
+ * {@link RuntimeSnapshot} 是运行期事实（受管安装与 skill 来源），由 manager 现探后
+ * 传入；不传即「未安装 + 随包 skill」，测试据此断言两种形态。
+ *
+ * 组行必须带 `isolate` 归属 realm，否则注册表拒绝挂载（服务泄漏判定）。
+ * @module @dsh-plus/agent-preset-rea/definition
+ */
+import type { PresetDefinition } from '@deepseek-ai/dsh-agent-preset-registry'
+
+import type { AgentPresetReaConfig } from './config.ts'
+import type { RuntimeSnapshot } from './manager.ts'
+import { DEFAULT_MCP_COMMAND, reaMcpArgs, reaMcpEnv, reaMcpLaunch } from './mcp.ts'
+import { PLAN_MODE_SECTION } from './prompt.ts'
+import { BUNDLED_SKILL_ROOT, reaSkillDirs } from './skill.ts'
+
+/** 预设注册表身份（改 id 等于换预设，default 等引用都会落空）。 */
+export const REA_PRESET_ID = 'rea'
+
+/** 相对上游 `standard` 新增的行 id（镜像测试按此白名单放行自造行）。 */
+export const ADDED_ROWS: readonly string[] = ['mcp-rea']
+
+/**
+ * 已镜像行 → 允许偏离上游的字段名（其余字段必须逐字一致）。
+ * 删除某条等于把该行改回上游原文；改动上游不存在的字段会被测试拦下。
+ */
+export const CONFIG_DELTAS: Readonly<Record<string, readonly string[]>> = {
+  persona: ['prefix'],
+  'skill-filesystem': ['customSkillDirs'],
+}
+
+/** 平台门控表达式：与上游 `standard` 预设逐字相同，Windows 上由 pwsh 顶替 bash。 */
+const WINDOWS_ONLY = { __jsExpr: "process.platform === 'win32'" } as const
+const POSIX_ONLY = { __jsExpr: "process.platform !== 'win32'" } as const
+
+/** 官方 loader 的嵌套组行名。 */
+const GROUP = 'cordis:group'
+/** 未安装、随包 skill 的运行期事实（默认值：测试与无 manager 场景）。 */
+export function emptyRuntime(): RuntimeSnapshot {
+  return {
+    install: null,
+    skill: {
+      source: 'bundled',
+      version: null,
+      root: BUNDLED_SKILL_ROOT,
+      files: 0,
+      updatedAt: null,
+    },
+  }
+}
+
+/** 声明里的行类型（官方 loader entry 结构）。 */
+type Row = PresetDefinition['plugins'][number]
+
+/**
+ * 基础与工具面行：身份（persona）/ 项目指令与时钟 / shell 与文件工具 / 后台任务与
+ * 定时提醒 / skill 文件系统（本预设加 `customSkillDirs`，可指向手动更新副本）。
+ */
+function baseRows(config: AgentPresetReaConfig, runtime: RuntimeSnapshot): Row[] {
+  return [
+    // 身份：沿用官方装配（非 complete、保留运行时上下文），前缀取配置（默认空串：
+    // 空模板照样遮蔽部署级 persona 段，渲染为空后消失，不追加任何自有文案）。
+    {
+      id: 'persona',
+      name: '@deepseek-ai/dsh-persona',
+      config: { prefix: config.personaPrefix },
+    },
+    // 项目指令（AGENTS.md）与逐步时钟上下文（默认 10 分钟一条）。
+    {
+      id: 'agent-instructions',
+      name: '@deepseek-ai/dsh-agent-instructions',
+      config: { maxBytes: 65536 },
+    },
+    { id: 'time-context', name: '@deepseek-ai/dsh-time-context' },
+    // shell：一次性执行，执行器在宿主平面；平台门控与上游一致。
+    { id: 'tool-bash', name: '@deepseek-ai/dsh-tool-bash', disabled: WINDOWS_ONLY },
+    { id: 'tool-pwsh', name: '@deepseek-ai/dsh-tool-pwsh', disabled: POSIX_ONLY },
+    // 文件读写、检索与后台任务控制。
+    { id: 'tool-fs', name: '@deepseek-ai/dsh-tool-fs' },
+    {
+      id: 'tool-fs-search',
+      name: '@deepseek-ai/dsh-tool-fs-search',
+      config: { sampleOverCapGlobResults: false },
+    },
+    { id: 'tool-jobs', name: '@deepseek-ai/dsh-tool-jobs' },
+    { id: 'tool-schedule', name: '@deepseek-ai/dsh-tool-schedule' },
+    // 技能：本地目录发现 + 模型面加载器；本预设额外挂上随包 REA 官方 skill 根
+    // （customSkillDirs 是 rank 300 的追加根，不动项目/用户/bundled 根）。
+    {
+      id: 'skill-filesystem',
+      name: '@deepseek-ai/dsh-skill-filesystem',
+      config: {
+        customSkillDirs: reaSkillDirs(
+          config,
+          runtime.skill.source === 'updated' ? runtime.skill.root : null,
+        ),
+      },
+    },
+    { id: 'tool-skill', name: '@deepseek-ai/dsh-tool-skill' },
+    // 同会话目标：/goal 命令与模型面目标工具。
+    { id: 'command-goal', name: '@deepseek-ai/dsh-command-goal' },
+    { id: 'tool-goal', name: '@deepseek-ai/dsh-tool-goal' },
+  ]
+}
+
+/**
+ * 编排与交付面行：计划模式 / 上下文压缩 / 委派与 workflow / 交互与待办 / 网络工具 /
+ * **REA MCP 客户端** / 展示与插件管理。
+ */
+function orchestrationRows(config: AgentPresetReaConfig, runtime: RuntimeSnapshot): Row[] {
+  // 启动方式：显式 mcpCommand > 受管安装入口 > null（行禁用）。
+  const launch = reaMcpLaunch(config, runtime.install)
+  // 无启动方式时行被禁用，但 config 仍填经典 npx 配方：配置转储里能看到原始配方，
+  // 手工把行 enable 回来即回退到「启动期拉取」的老行为——默认路径绝不 spawn 它。
+  const mcp = launch ?? {
+    command: DEFAULT_MCP_COMMAND,
+    args: reaMcpArgs({ ...config, mcpCommand: DEFAULT_MCP_COMMAND }),
+  }
+  return [
+    // 计划模式：状态天然属于单个 agent，条目级 realm 即正确生命周期。
+    {
+      id: 'planning',
+      name: GROUP,
+      group: true,
+      isolate: { planMode: true },
+      config: [
+        {
+          id: 'plan-mode',
+          name: '@deepseek-ai/dsh-plan-mode',
+          config: { section: PLAN_MODE_SECTION },
+        },
+      ],
+    },
+    // 压缩：token 计量器留在宿主平面，本组只挂读取它的后端与结果裁剪器。
+    {
+      id: 'compaction',
+      name: GROUP,
+      group: true,
+      isolate: { compaction: true, toolResultPruner: true },
+      config: [
+        { id: 'compaction-basic', name: '@deepseek-ai/dsh-compaction-basic' },
+        { id: 'command-compact', name: '@deepseek-ai/dsh-command-compact' },
+        {
+          id: 'tool-result-pruner',
+          name: '@deepseek-ai/dsh-compaction-tool-result-pruner',
+          config: { thresholdChars: 8192, headChars: 4096, tailChars: 1024 },
+        },
+      ],
+    },
+    // 委派与编排：子代理、fork、workflow 整组（编排引擎只在本 realm 内共享）。
+    {
+      id: 'delegation',
+      name: GROUP,
+      group: true,
+      isolate: { workflowEngine: true },
+      config: [
+        { id: 'tool-subagent-control', name: '@deepseek-ai/dsh-tool-subagent-control' },
+        {
+          id: 'tool-subagent-list-agents',
+          name: '@deepseek-ai/dsh-tool-subagent-control/list-agents',
+        },
+        {
+          id: 'tool-subagent',
+          name: '@deepseek-ai/dsh-tool-subagent',
+          config: { provider: 'spawn', toolName: 'subagent', modelSelectionSettings: true },
+        },
+        {
+          id: 'tool-subagent-fork',
+          name: '@deepseek-ai/dsh-tool-subagent',
+          config: { provider: 'fork', toolName: 'subagent_fork' },
+        },
+        {
+          id: 'workflow-ptc',
+          name: '@deepseek-ai/dsh-workflow-ptc',
+          config: { provider: 'spawn' },
+        },
+        { id: 'tool-workflow', name: '@deepseek-ai/dsh-tool-workflow' },
+      ],
+    },
+    // 其余模型面行。
+    { id: 'tool-ask-user', name: '@deepseek-ai/dsh-tool-ask-user' },
+    {
+      id: 'tool-todo',
+      name: '@deepseek-ai/dsh-tool-todo',
+      config: { allowParallelInProgress: true },
+    },
+    {
+      id: 'tool-web',
+      name: '@deepseek-ai/dsh-tool-web',
+      config: { fetch: true, searchTimeoutMs: 60000 },
+    },
+    // 本预设新增：REA MCP 客户端（stdio），工具以 mcp__<serverName>__<tool> 注册在
+    // 本预设作用域；服务名预留按作用域隔离，其他预设不受影响。
+    // 未安装 REA 且未显式配 mcpCommand 时整行禁用：绝不在 boot 期 spawn npx
+    // （那会跑 npm 安装脚本，卡住即吊死预设激活与名册——见 docs/README.md）。
+    {
+      id: 'mcp-rea',
+      name: '@deepseek-ai/dsh-mcp-client',
+      disabled: !config.mcpEnabled || launch === null,
+      config: {
+        transport: 'stdio',
+        serverName: config.mcpServerName,
+        command: mcp.command,
+        args: mcp.args,
+        env: reaMcpEnv(config),
+        toolCallTimeoutMs: config.toolCallTimeoutMs,
+        failOnStartupError: config.failOnStartupError,
+      },
+    },
+    { id: 'present', name: '@deepseek-ai/dsh-tool-present' },
+    // 宿主插件管理：上游 standard 里同样是 disabled 行。
+    { id: 'tool-plugin-manager', name: '@deepseek-ai/dsh-plugin-manager/tools', disabled: true },
+  ]
+}
+
+/**
+ * 由配置 + 运行期事实拼出注册表声明。
+ * @param config - 已验证的插件配置。
+ * @param runtime - 受管安装与 skill 来源事实（默认「未安装 + 随包 skill」）。
+ * @returns id 固定为 `rea` 的预设声明。
+ */
+export function reaPresetDefinition(
+  config: AgentPresetReaConfig,
+  runtime: RuntimeSnapshot = emptyRuntime(),
+): PresetDefinition {
+  return {
+    id: REA_PRESET_ID,
+    name: config.name,
+    description: config.description,
+    order: config.order,
+    plugins: [...baseRows(config, runtime), ...orchestrationRows(config, runtime)],
+  }
+}

package/src/dto.ts

@@ -0,0 +1,87 @@
+/**
+ * 宿主半与浏览器半之间的 wire 数据门面（纯类型 + 纯函数，零 node 依赖）。
+ *
+ * 浏览器半只 `import type` 消费本文件（编译期擦除，不进 client bundle），
+ * 两端共用同一份字段定义，避免「宿主改了字段、卡片还在读老名字」的静默漂移。
+ * @module @dsh-plus/agent-preset-rea/dto
+ */
+
+/** 作业种类。 */
+export type JobKind = 'install' | 'skill'
+
+/** 作业状态。 */
+export type JobState = 'running' | 'ok' | 'error' | 'cancelled'
+
+/** 作业进度（按阶段推进；percent 为进入该阶段时的完成度）。 */
+export interface JobProgressDto {
+  step: number
+  steps: number
+  phase: string
+  percent: number
+}
+
+/** 作业快照。 */
+export interface JobDto {
+  id: number
+  kind: JobKind
+  state: JobState
+  progress: JobProgressDto
+  /** 日志尾部（宿主已有界）。 */
+  log: string[]
+  startedAt: string
+  finishedAt: string | null
+  version: string | null
+  error: string | null
+}
+
+/** 受管安装事实。 */
+export interface InstallDto {
+  installed: boolean
+  /** 已安装版本（未安装为 null）。 */
+  version: string | null
+  /** 受管安装树位置（无论是否已安装都有值，便于用户核对）。 */
+  root: string
+  /** 入口脚本（未安装为 null）。 */
+  entry: string | null
+}
+
+/** skill 来源事实。 */
+export interface SkillDto {
+  source: 'bundled' | 'updated'
+  version: string | null
+  root: string
+  files: number
+  updatedAt: string | null
+}
+
+/** MCP 行形态。 */
+export interface McpDto {
+  /** `installed` = 用受管安装入口；`custom` = 用显式 mcpCommand；`missing` = 未安装且无显式命令（行禁用）。 */
+  mode: 'installed' | 'custom' | 'missing'
+  /** 行是否启用（mcpEnabled && 有启动方式）。 */
+  enabled: boolean
+  command: string | null
+  args: string[]
+}
+
+/** `GET /status` 响应。 */
+export 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
+}
+
+/** 作业类响应（启动/取消）。 */
+export interface JobActionDto {
+  job: JobDto | null
+  /** 拒绝原因（409/400 时给出人话）。 */
+  error?: string
+}

package/src/exec.ts

@@ -0,0 +1,155 @@
+/**
+ * 外部命令执行面与作业原语：受管安装/更新作业要跑 `npm` / `tar`，这些调用全部经
+ * {@link CommandRunner} 注入，单测用假 runner 跑完整状态机（零网络、零 npm）。
+ *
+ * 作业阶段由 {@link JobTaskContext} 上报，日志行由 {@link JobOperation} 的调用方
+ * 收集；本模块只负责「怎么跑命令」与「怎么把输出变成日志行」。
+ * @module @dsh-plus/agent-preset-rea/exec
+ */
+import { spawn } from 'node:child_process'
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { AgentPresetReaConfig } from './config.ts'
+
+/** 版本字符串形状：进 shell 前把用户可配项收窄成纯版本号。 */
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+
+/** npm 命令名（Windows 经 shell 执行，见 {@link spawnRunner} 注释）。 */
+export const NPM = 'npm'
+
+/** 作业取消（AbortSignal 触发后由 runner 抛出）。 */
+export class JobCancelled extends Error {
+  constructor() {
+    super('作业已取消')
+    this.name = 'JobCancelled'
+  }
+}
+
+/** 外部命令执行面。 */
+export interface CommandRunner {
+  run(
+    command: string,
+    args: string[],
+    options: {
+      env: Record<string, string>
+      signal: AbortSignal
+      onLine(line: string): void
+    },
+  ): Promise<{ code: number }>
+}
+
+/** 作业执行上下文（阶段推进 + 日志 + 取消信号）。 */
+export interface JobTaskContext {
+  /** 进入第 step 个阶段（从 0 起，与 {@link JobOperation.phases} 对应）。 */
+  phase(step: number): void
+  log(line: string): void
+  signal: AbortSignal
+}
+
+/** 一类作业：阶段名 + 实现。 */
+export interface JobOperation {
+  phases: string[]
+  run(ctx: JobTaskContext): Promise<string>
+}
+
+/** 实际 runner：spawn 子进程、逐行回调、AbortSignal 触发即杀。 */
+export const spawnRunner: CommandRunner = {
+  run: (command, args, options) =>
+    new Promise((resolve, reject) => {
+      // Windows 下 npm/tar 都是 .cmd/.exe 包装，shell:false 无法直接执行
+      // （与官方 MCP 客户端同一坑）；参数全部由本模块构造，用户可配的版本号已按
+      // 形状收窄，无拼串注入面。
+      const child = spawn(command, args, {
+        env: options.env,
+        shell: process.platform === 'win32',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      let pending = ''
+      const emit = (chunk: string): void => {
+        pending += chunk
+        const lines = pending.split('\n')
+        pending = lines.pop() ?? ''
+        for (const line of lines) options.onLine(line.trimEnd())
+      }
+      child.stdout.setEncoding('utf8')
+      child.stderr.setEncoding('utf8')
+      child.stdout.on('data', emit)
+      child.stderr.on('data', emit)
+      const abort = (): void => {
+        child.kill('SIGTERM')
+      }
+      options.signal.addEventListener('abort', abort, { once: true })
+      child.on('error', reject)
+      child.on('close', (code) => {
+        options.signal.removeEventListener('abort', abort)
+        if (pending !== '') options.onLine(pending.trimEnd())
+        if (options.signal.aborted) reject(new JobCancelled())
+        else resolve({ code: code ?? 1 })
+      })
+    }),
+}
+
+/**
+ * npm 子进程环境：继承宿主环境，附带代理端口（port > 0 时同时给 npm 与
+ * prebuild-install 注入代理——后者只认 `https_proxy` 系列环境变量，
+ * 这是原生依赖 prebuild 下载卡死的正解）。
+ */
+export function npmEnv(config: AgentPresetReaConfig): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) env[key] = value
+  }
+  env['npm_config_audit'] = 'false'
+  env['npm_config_fund'] = 'false'
+  env['npm_config_update_notifier'] = 'false'
+  env['npm_config_loglevel'] = 'http'
+  if (config.proxyPort > 0) {
+    const proxy = `http://127.0.0.1:${config.proxyPort}`
+    env['HTTP_PROXY'] = proxy
+    env['HTTPS_PROXY'] = proxy
+    env['http_proxy'] = proxy
+    env['https_proxy'] = proxy
+    env['npm_config_proxy'] = proxy
+    env['npm_config_https_proxy'] = proxy
+  }
+  return env
+}
+
+/** 版本收窄：进命令前把配置里的钉版校验成纯版本号。 */
+export function safeVersion(version: string): string {
+  const trimmed = version.trim()
+  if (!VERSION_PATTERN.test(trimmed)) {
+    throw new Error(`配置里的 reaVersion 不是合法版本号：${JSON.stringify(version)}`)
+  }
+  return trimmed
+}
+
+/** 逐行转发子进程输出到作业日志（截断超长行）。 */
+export function lineSink(ctx: JobTaskContext): (line: string) => void {
+  return (line) => {
+    if (line !== '') ctx.log(line.slice(0, 500))
+  }
+}
+
+/** 递归列出目录下全部文件（相对 POSIX 路径，排序稳定）。 */
+export function listFiles(dir: string, base = ''): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )) {
+    const rel = base === '' ? entry.name : `${base}/${entry.name}`
+    if (entry.isDirectory()) out.push(...listFiles(join(dir, entry.name), rel))
+    else out.push(rel)
+  }
+  return out
+}
+
+/** 目录下文件数（目录缺席或不可读按 0；状态展示用，不抛）。 */
+export function countFiles(dir: string): number {
+  try {
+    return listFiles(dir).length
+  } catch {
+    return 0
+  }
+}

package/src/index.ts

@@ -0,0 +1,186 @@
+/**
+ * dsh 服务插件：把「逆向工程」注册为官方 agent preset（id=`rea`）。
+ *
+ * 预设声明经 `ctx.agentPresets.register()` 注册（官方 preset registry 是唯一
+ * 读取方），出现在设置 → Agent 预设的名单里，可被会话选择。
+ *
+ * 预设语义：官方 `standard` 预设**全量行**的逐字镜像（shell/文件读写与检索/
+ * 后台任务/定时提醒/技能/目标/计划/压缩/委派与编排/提问/待办/联网/交付/插件管理
+ * 全在），另加三处显式增量——persona 前缀取配置（默认空串）、`skill-filesystem`
+ * 加随包 REA skill 根、新增 `mcp-rea` 行连 REA stdio 服务。详见 definition.ts。
+ *
+ * 作用域：三处增量都落在本预设声明内，因此 REA 工具（`mcp__rea__*`）、REA skill
+ * 与附加 skill 根只对该预设的会话可见；宿主平面不新增工具/提示段，其他预设不受
+ * 影响（见 docs/README.md 的隔离一节）。
+ *
+ * persona 提示词：`personaPrefix` 是活动字段（`.volatile()`），由设置 → 插件页
+ * 的配置卡片写入；保存后 loader 原位提交活动引用并广播 `loader/volatile-update`，
+ * 本插件据此换代注册（注销旧声明 → 按新值重建声明），**新建会话**即用新提示词，
+ * 已存在会话保持既有 composition（注册表语义：运行中会话的装配不随换代改变）。
+ *
+ * REA 的安装与更新也在卡片上（受管安装 + 后台作业 + 实时进度 + 可选代理端口）：
+ * 宿主半的 manager 把 `rea-agents` 装进插件数据目录、把 skill 拉成可替换副本，
+ * 作业完成后同样换代注册——因此预设声明里**不会**在 boot 期 spawn `npx`
+ * （那会跑 npm 安装脚本，原生依赖 prebuild 下载一卡就吊死预设激活与整个名册）。
+ *
+ * 设计取舍：
+ * - 独立插件而非 cordis.patch.yml 里的裸 `@deepseek-ai/dsh-agent-preset`
+ *   行：便于纳入本仓的构建/测试/文档体系，并把显示面与 MCP/skill 参数开放为
+ *   可覆盖配置；
+ * - 惰性 inject `agentPresets`：服务缺席的 profile（如 headless）里本行
+ *   照常 active、只是不注册（等价插件缺席），绝不因硬 inject 永久 pending
+ *   拖垮 boot（同 boot-retry 的教训）；
+ * - 注册与换代在 effect 内后台串行完成、不阻塞 apply：注册会同步挂载预设
+ *   子树并等待其激活（含 MCP 首次连接），await 在本行激活内可能与 Host 树推进
+ *   互锁；失败仅记 warn（重名、MCP 起不来等由各注册表/客户端负责诊断），
+ *   不使 boot 失败。
+ * @module @dsh-plus/agent-preset-rea
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { unwrapVolatile } from '@dsh-plus/shared'
+
+import { type AgentPresetReaConfig, type AgentPresetReaConfigFields, Config } from './config.ts'
+import { reaPresetDefinition } from './definition.ts'
+import { createJobBoard } from './jobs.ts'
+import { createManager } from './manager.ts'
+import { REA_PINNED_VERSION } from './mcp.ts'
+import { createPresetRegistrar } from './registration.ts'
+import { registerReaRoutes } from './routes.ts'
+import { BUNDLED_SKILL_ROOT } from './skill.ts'
+
+export const name = 'dsh-plus-agent-preset-rea'
+
+/** 无硬 inject：agentPresets 经 apply 内惰性 inject 接线（缺席即空转）。 */
+export const inject = [] as const
+
+export { SETTINGS_NS } from './config.ts'
+export {
+  ADDED_ROWS,
+  CONFIG_DELTAS,
+  emptyRuntime,
+  REA_PRESET_ID,
+  reaPresetDefinition,
+} from './definition.ts'
+export type {
+  InstallDto,
+  JobActionDto,
+  JobDto,
+  JobKind,
+  JobProgressDto,
+  JobState,
+  McpDto,
+  SkillDto,
+  StatusDto,
+} from './dto.ts'
+export {
+  type CommandRunner,
+  JobCancelled,
+  type JobOperation,
+  type JobTaskContext,
+  NPM,
+  npmEnv,
+  safeVersion,
+  spawnRunner,
+} from './exec.ts'
+export { createJobBoard, type JobBoard, type JobSnapshot } from './jobs.ts'
+export {
+  configWith,
+  createManager,
+  INSTALL_PHASES,
+  type JobDeps,
+  type JobOverrides,
+  type ManagerPaths,
+  managerPaths,
+  probeInstall,
+  probeRuntime,
+  probeSkill,
+  REA_INSTALL_DIR,
+  REA_PACKAGE,
+  REA_SKILL_DIR,
+  REA_SKILL_NAME,
+  type ReaInstall,
+  type ReaManager,
+  type RuntimeSnapshot,
+  SKILL_PHASES,
+  type SkillManifest,
+  type SkillState,
+} from './manager.ts'
+export {
+  DEFAULT_MCP_COMMAND,
+  INPUT_SCHEMA_PROFILES,
+  type InstalledEntry,
+  type McpLaunch,
+  OUTPUT_SCHEMA_PROFILES,
+  REA_PINNED_VERSION,
+  reaMcpArgs,
+  reaMcpEnv,
+  reaMcpLaunch,
+} from './mcp.ts'
+export { PLAN_MODE_SECTION } from './prompt.ts'
+export { createPresetRegistrar, type PresetRegistrar, type Unregister } from './registration.ts'
+export { ROUTE_BASE, registerReaRoutes, statusPayload } from './routes.ts'
+export { BUNDLED_SKILL_ROOT, reaSkillDirs } from './skill.ts'
+export type { AgentPresetReaConfig, AgentPresetReaConfigFields }
+export { Config }
+
+/**
+ * 注册 rea 预设，并在 persona 热更后换代；卸载时注销当前一代。
+ *
+ * 注册与换代都在 effect 生命周期内完成：fiber 早于注册完成被卸下时，
+ * 换代器自己收掉晚到的 disposer，不泄漏预设子树。
+ * @param ctx - 宿主上下文。
+ * @param config - 已验证的插件配置（`personaPrefix` 为活动引用）。
+ */
+export function apply(ctx: Context, config: AgentPresetReaConfigFields): void {
+  const logger = ctx.logger('agent-preset-rea')
+  const current = (): AgentPresetReaConfig => unwrapVolatile(config)
+  if (current().enabled !== true) return
+
+  const onError = (error: unknown): void => {
+    const detail = error instanceof Error ? error.message : String(error)
+    logger.warn(`register rea preset failed: ${detail}`)
+  }
+  const manager = createManager({
+    config: current,
+    bundledRoot: BUNDLED_SKILL_ROOT,
+    bundledVersion: REA_PINNED_VERSION,
+  })
+  const board = createJobBoard()
+  // 换代入口：安装/更新作业完成、或活动配置提交后，都要按新事实重建声明。
+  let reregister: (() => void) | null = null
+  const refresh = (): void => {
+    manager.refresh()
+    reregister?.()
+  }
+  ctx.effect(
+    () =>
+      board.onSettled((snapshot) => {
+        refresh()
+        logger.info(`rea ${snapshot.kind} 作业结束：${snapshot.state}`)
+      }),
+    'agent-preset-rea: refresh after job',
+  )
+
+  ctx.inject(['agentPresets'], (scope) => {
+    scope.effect(() => {
+      const registrar = createPresetRegistrar({
+        register: (definition) => scope.agentPresets.register(definition),
+        build: () => reaPresetDefinition(current(), manager.snapshot()),
+        onError,
+      })
+      reregister = () => registrar.refresh()
+      // 监听器挂在插件自身 fiber 上：loader 正是对该 fiber 广播 volatile 提交。
+      const off = ctx.events.on('loader/volatile-update', () => refresh())
+      return () => {
+        reregister = null
+        off()
+        registrar.dispose()
+      }
+    }, 'agent-preset-rea: register rea preset')
+  })
+
+  // 安装/更新端点：webServer 缺席（headless）即不注册，插件其余能力照常。
+  ctx.inject(['webServer'], (scope) => {
+    registerReaRoutes(scope as unknown as Context, { manager, board, config: current })
+  })
+}