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

package/src/definition.ts

@@ -8,8 +8,13 @@
  *
  * 增量仅三处，测试按 {@link ADDED_ROWS} / {@link CONFIG_DELTAS} 白名单放行：
  * 1. `persona` 行 `prefix` 取配置值（默认空串 = 空 persona）；
- * 2. `skill-filesystem` 行加 `customSkillDirs`（随包 REA skill + 配置追加目录）；
- * 3. 新增 `mcp-rea` 行：官方 MCP 客户端连 REA stdio 服务，落在本预设作用域内。
+ * 2. `skill-filesystem` 行加 `customSkillDirs`（REA skill 源与 reverse-skill 技能组，
+ *    各受一个活动开关控制，另加部署方 `extraSkillDirs`）；
+ * 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
@@ -17,9 +22,11 @@
 import type { PresetDefinition } from '@deepseek-ai/dsh-agent-preset-registry'
 
 import type { AgentPresetReaConfig } from './config.ts'
-import { reaMcpArgs, reaMcpEnv } from './mcp.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 { reaSkillDirs } from './skill.ts'
+import { emptyReverseState } from './reverse.ts'
+import { BUNDLED_SKILL_ROOT, presetSkillDirs } from './skill.ts'
 
 /** 预设注册表身份（改 id 等于换预设，default 等引用都会落空）。 */
 export const REA_PRESET_ID = 'rea'
@@ -42,147 +49,197 @@ 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,
+    },
+    reverse: emptyReverseState(),
+  }
+}
+
+/** 声明里的行类型（官方 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: presetSkillDirs(config, runtime),
+      },
+    },
+    { 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): PresetDefinition {
+export function reaPresetDefinition(
+  config: AgentPresetReaConfig,
+  runtime: RuntimeSnapshot = emptyRuntime(),
+): PresetDefinition {
   return {
     id: REA_PRESET_ID,
     name: config.name,
     description: config.description,
     order: config.order,
-    plugins: [
-      // 身份：沿用官方装配（非 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) },
-      },
-      { 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' },
-      // 计划模式：状态天然属于单个 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> 注册在
-      // 本预设作用域；服务名预留按作用域隔离，其他预设不受影响。
-      {
-        id: 'mcp-rea',
-        name: '@deepseek-ai/dsh-mcp-client',
-        disabled: !config.mcpEnabled,
-        config: {
-          transport: 'stdio',
-          serverName: config.mcpServerName,
-          command: config.mcpCommand,
-          args: reaMcpArgs(config),
-          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 },
-    ],
+    plugins: [...baseRows(config, runtime), ...orchestrationRows(config, runtime)],
   }
 }

package/src/dto.ts

@@ -0,0 +1,113 @@
+/**
+ * 宿主半与浏览器半之间的 wire 数据门面（纯类型 + 纯函数，零 node 依赖）。
+ *
+ * 浏览器半只 `import type` 消费本文件（编译期擦除，不进 client bundle），
+ * 两端共用同一份字段定义，避免「宿主改了字段、卡片还在读老名字」的静默漂移。
+ * @module @dsh-plus/agent-preset-rea/dto
+ */
+
+/** 作业种类：REA 包安装/更新、REA skill 更新、reverse-skill 更新。 */
+export type JobKind = 'install' | 'skill' | 'reverse'
+
+/** 作业状态。 */
+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[]
+}
+
+/** GitHub 技能源（zhaoxuya520/reverse-skill）事实。 */
+export interface ReverseSkillDto {
+  installed: boolean
+  repo: string
+  /** 清单记录的 ref（空串 = 安装时取的默认分支）。 */
+  ref: string | null
+  /** 提交 sha（内容级溯源）。 */
+  sha: string | null
+  /** 仓库 VERSION 文件内容。 */
+  version: string | null
+  root: string
+  tree: string
+  files: number
+  /** 树内发现的全部技能组（相对安装树根）。 */
+  groups: string[]
+  /** 配置选中且实际挂进预设的组。 */
+  activeGroups: string[]
+  updatedAt: string | null
+}
+
+/** `GET /status` 响应。 */
+export interface StatusDto {
+  config: {
+    reaVersion: string
+    proxyPort: number
+    mcpEnabled: boolean
+    skillEnabled: boolean
+    reverseSkillEnabled: boolean
+    reverseSkillRepo: string
+    reverseSkillRef: string
+    reverseSkillGroups: string[]
+    installRoot: string
+  }
+  install: InstallDto
+  skill: SkillDto
+  reverse: ReverseSkillDto
+  mcp: McpDto
+  paths: { installRoot: string; skillRoot: string; reverseRoot: string }
+  job: JobDto | null
+}
+
+/** 作业类响应（启动/取消）。 */
+export interface JobActionDto {
+  job: JobDto | null
+  /** 拒绝原因（409/400 时给出人话）。 */
+  error?: string
+}

package/src/exec.ts

@@ -0,0 +1,177 @@
+/**
+ * 外部命令执行面与作业原语：受管安装/更新作业要跑 `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>
+}
+
+/** 作业依赖：生效配置、命令执行面、作业完成后的现探刷新。 */
+export interface JobDeps {
+  config: AgentPresetReaConfig
+  runner: CommandRunner
+  refresh(): void
+}
+
+/** 实际 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 })
+      })
+    }),
+}
+
+/** 本机代理 URL（未配置代理时为 null）。 */
+export function proxyUrl(config: AgentPresetReaConfig): string | null {
+  return config.proxyPort > 0 ? `http://127.0.0.1:${config.proxyPort}` : null
+}
+
+/**
+ * 子进程环境：继承宿主环境，附带代理端口（port > 0 时给 `https_proxy` 系列，
+ * prebuild-install 与 curl 都认这些变量——原生依赖 prebuild 下载卡死的正解）。
+ * @param config - 插件配置。
+ * @param npm - 是否附带 npm 专属开关（npm 子进程用；curl 等非 npm 命令不需要）。
+ */
+export function commandEnv(config: AgentPresetReaConfig, npm = false): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined) env[key] = value
+  }
+  if (npm) {
+    env['npm_config_audit'] = 'false'
+    env['npm_config_fund'] = 'false'
+    env['npm_config_update_notifier'] = 'false'
+    env['npm_config_loglevel'] = 'http'
+  }
+  const proxy = proxyUrl(config)
+  if (proxy !== null) {
+    env['HTTP_PROXY'] = proxy
+    env['HTTPS_PROXY'] = proxy
+    env['http_proxy'] = proxy
+    env['https_proxy'] = proxy
+    if (npm) {
+      env['npm_config_proxy'] = proxy
+      env['npm_config_https_proxy'] = proxy
+    }
+  }
+  return env
+}
+
+/** npm 子进程环境（{@link commandEnv} 的 npm 形态）。 */
+export function npmEnv(config: AgentPresetReaConfig): Record<string, string> {
+  return commandEnv(config, true)
+}
+
+/** 版本收窄：进命令前把配置里的钉版校验成纯版本号。 */
+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
+  }
+}