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

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

@@ -18,6 +18,11 @@
  * 本插件据此换代注册（注销旧声明 → 按新值重建声明），**新建会话**即用新提示词，
  * 已存在会话保持既有 composition（注册表语义：运行中会话的装配不随换代改变）。
  *
+ * REA 的安装与更新也在卡片上（受管安装 + 后台作业 + 实时进度 + 可选代理端口）：
+ * 宿主半的 manager 把 `rea-agents` 装进插件数据目录、把 skill 拉成可替换副本，
+ * 作业完成后同样换代注册——因此预设声明里**不会**在 boot 期 spawn `npx`
+ * （那会跑 npm 安装脚本，原生依赖 prebuild 下载一卡就吊死预设激活与整个名册）。
+ *
  * 设计取舍：
  * - 独立插件而非 cordis.patch.yml 里的裸 `@deepseek-ai/dsh-agent-preset`
  *   行：便于纳入本仓的构建/测试/文档体系，并把显示面与 MCP/skill 参数开放为
@@ -36,7 +41,12 @@ 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'
 
@@ -44,17 +54,71 @@ export const name = 'dsh-plus-agent-preset-rea'
 export const inject = [] as const
 
 export { SETTINGS_NS } from './config.ts'
-export { ADDED_ROWS, CONFIG_DELTAS, REA_PRESET_ID, reaPresetDefinition } from './definition.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 }
@@ -76,20 +140,47 @@ export function apply(ctx: Context, config: AgentPresetReaConfigFields): 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()),
+        build: () => reaPresetDefinition(current(), manager.snapshot()),
         onError,
       })
+      reregister = () => registrar.refresh()
       // 监听器挂在插件自身 fiber 上：loader 正是对该 fiber 广播 volatile 提交。
-      const off = ctx.events.on('loader/volatile-update', () => registrar.refresh())
+      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 })
+  })
 }

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)
+    },
+  }
+}