agentworkshop 0.7.41 → 0.7.46

package/server/services/system-config/mutate.ts

@@ -0,0 +1,103 @@
+/**
+ * SystemConfigServiceMutate —— 写入 / 重置 / 重载 / 订阅与广播
+ * (拆分层,承 SystemConfigServiceSnapshot;方法体与原文件逐行一致)
+ */
+import { SystemConfigServiceSnapshot } from './snapshot'
+import type { ConfigEventPayload, Listener } from './types'
+import { AppError } from '../../utils/errors'
+import { saveSettings, validateValue } from '@/shared/config/engine.mjs'
+
+export abstract class SystemConfigServiceMutate extends SystemConfigServiceSnapshot {
+  /**
+   * 应用一批覆盖（PATCH 语义）。
+   * @param patch { [key]: value }  value === null 表示清除该键覆盖（回落 config.yml/base）
+   * @returns { changed, restartRequired, effective, sources }
+   */
+  patch(patch: Record<string, unknown>): { changed: string[], restartRequired: string[], effective: Record<string, unknown>, sources: Record<string, unknown> } {
+    const errors: Record<string, string[]> = {}
+    const next = { ...this.overrides }
+    const changed: string[] = []
+    for (const [key, rawValue] of Object.entries(patch)) {
+      const desc = this.map[key]
+      if (!desc) {
+        errors[key] = ['未知设置项（不在 shared/config/schema.json 中）']
+        continue
+      }
+      // null → 清除覆盖
+      if (rawValue === null || rawValue === undefined) {
+        if (key in next) {
+          // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- 撤销覆盖语义
+          delete next[key]
+          changed.push(key)
+        }
+        continue
+      }
+      const errs = validateValue(desc, rawValue)
+      if (errs.length) {
+        errors[key] = errs
+        continue
+      }
+      if (next[key] !== rawValue) changed.push(key)
+      next[key] = rawValue
+    }
+    if (Object.keys(errors).length) {
+      throw new AppError(400, 'VALIDATION_ERROR', `设置校验失败: ${Object.entries(errors).map(([k, e]) => `${k}: ${e.join('; ')}`).join(' | ')}`)
+    }
+    if (changed.length) {
+      this.overrides = next
+      saveSettings(next, this.settingsPath)
+      this.recompute()
+    }
+    return this.result(changed)
+  }
+
+  /** 清空全部运行时覆盖（回落 config.yml/base + env） */
+  reset(): { changed: string[], restartRequired: string[] } {
+    const changed = Object.keys(this.overrides)
+    this.overrides = {}
+    saveSettings({}, this.settingsPath)
+    this.recompute()
+    const res = this.result(changed)
+    this.broadcast({ type: 'config:reset', changed, ...this.eventTail() })
+    return res
+  }
+
+  /** 手动重载（外部已改文件）并广播 */
+  reload(): { changed: string[], restartRequired: string[] } {
+    const { changed } = this.reloadFromDisk()
+    const res = this.result(changed)
+    this.broadcast({ type: 'config:reloaded', changed, ...this.eventTail() })
+    return res
+  }
+
+  subscribe(fn: Listener): () => void {
+    this.listeners.add(fn)
+    return () => this.listeners.delete(fn)
+  }
+
+  protected eventTail() {
+    return { restartRequired: this.restartRequiredKeys(), effective: { ...this.effective }, sources: { ...this.sources }, overrides: { ...this.overrides }, at: new Date().toISOString() }
+  }
+
+  protected result(changed: string[]): { changed: string[], restartRequired: string[], effective: Record<string, unknown>, sources: Record<string, unknown> } {
+    const out = this.eventTail()
+    const res = { changed, restartRequired: out.restartRequired as string[], effective: out.effective, sources: out.sources }
+    if (changed.length) this.broadcast({ type: 'config:changed', changed, ...out })
+    return res
+  }
+
+  protected restartRequiredKeys(): string[] {
+    return this.allDescriptors.filter(d => d.applies === 'restart' && this.overrides[d.key] !== undefined).map(d => d.key)
+  }
+
+  protected broadcast(payload: ConfigEventPayload): void {
+    for (const fn of [...this.listeners]) {
+      try {
+        fn(payload)
+      }
+      catch (err) {
+        console.error('[system-config] 广播监听器异常:', err)
+      }
+    }
+  }
+}

package/server/services/system-config/plugins.ts

@@ -0,0 +1,104 @@
+/**
+ * SystemConfigServicePlugins —— 插件描述符注入 / 旧键迁移 / 取值与运行时应用
+ * (拆分层,承 SystemConfigServiceGroups;方法体与原文件逐行一致)
+ */
+import { SystemConfigServiceGroups } from './groups'
+import type { ConfigGroup, RuntimeConfigView } from './types'
+import type { SettingsDescriptor } from '@/shared/config/engine.mjs'
+import { DAQ_PREFIX, PUBLIC_FIELDS, ROOT_FIELDS, daqView } from './helpers'
+import { getPath, readSettings, saveSettings, setPath } from '@/shared/config/engine.mjs'
+import { useRuntimeConfig } from '#imports'
+
+export abstract class SystemConfigServicePlugins extends SystemConfigServiceGroups {
+  /**
+   * 插件宿主装载/热重载后注入插件设置描述符 + 插件声明的配置分组。
+   * 合并进 map/snapshot/effective 后,前端设置页自动渲染、PATCH 自动校验、
+   * 保存即热生效(与全局设置同一条链路);并触发一次遗留键迁移(plugins.kb.* 等)。
+   */
+  setPluginDescriptors(descs: SettingsDescriptor[], groups?: ConfigGroup[], labels?: Map<string, string>): void {
+    this.pluginDescriptors = Array.isArray(descs) ? descs : []
+    if (Array.isArray(groups)) this.pluginGroups = groups
+    if (labels instanceof Map) this.pluginLabels = labels
+    this.rebuildMap()
+    if (!this.ready) return // init 尚未执行:init() 末尾会补跑迁移与重载
+    const { changed } = this.migrateLegacyPluginKeys()
+    const { changed: reloaded } = this.reloadFromDisk()
+    this.broadcast({ type: 'config:reloaded', changed: [...changed, ...reloaded, 'plugin-settings', 'config-groups'], ...this.eventTail() })
+  }
+
+  /** 一次性迁移:0.7.28 前写死在 schema.json 的 plugins.kb / plugins.diag 键 → 插件命名空间键 */
+  protected migrateLegacyPluginKeys(): { changed: string[] } {
+    const legacyMap: Record<string, string> = {
+      'plugins.kb.base_url': 'plugins.rag-bridge.base_url',
+      'plugins.kb.web_url': 'plugins.rag-bridge.web_url',
+      'plugins.kb.token': 'plugins.rag-bridge.token',
+      'plugins.diag.base_url': 'plugins.diag-bridge.base_url',
+      'plugins.diag.token': 'plugins.diag-bridge.token',
+      'plugins.diag.harness': 'plugins.diag-bridge.harness',
+      'plugins.diag.max_turns': 'plugins.diag-bridge.max_turns',
+      'plugins.diag.max_minutes': 'plugins.diag-bridge.max_minutes',
+      'plugins.diag.auto_enabled': 'plugins.diag-bridge.auto_enabled',
+      'plugins.diag.auto_rules': 'plugins.diag-bridge.auto_rules',
+    }
+    const raw = readSettings(this.settingsPath) as Record<string, unknown>
+    const moved: Record<string, unknown> = {}
+    const removed: string[] = []
+    for (const [oldKey, newKey] of Object.entries(legacyMap)) {
+      if (raw[oldKey] === undefined) continue
+      // 新键已注册才搬移并删旧键;否则保留旧键等下一次 pass(插件宿主装载后再触发),
+      // 绝不抢先删数据 —— nitro 插件顺序里本服务可能先于插件宿主初始化
+      if (raw[newKey] === undefined && this.map[newKey]) {
+        moved[newKey] = raw[oldKey]
+        removed.push(oldKey)
+      }
+    }
+    if (!removed.length) return { changed: [] }
+    const next: Record<string, unknown> = { ...raw }
+    for (const k of removed) {
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- 迁移语义:旧键必须从覆盖文件移除
+      delete next[k]
+    }
+    Object.assign(next, moved)
+    saveSettings(next, this.settingsPath)
+    console.log(`[system-config] 插件设置键已迁移: ${removed.join(', ')} → ${Object.keys(moved).join(', ') || '(丢弃,新键未注册)'}`)
+    return { changed: [...removed, ...Object.keys(moved)] }
+  }
+
+  /* ---------------- 私有:base / apply ---------------- */
+
+  /** 从当前 runtimeConfig 读取某 key 的构建期基准值 */
+  protected readBase(key: string): unknown {
+    const rc = useRuntimeConfig() as RuntimeConfigView
+    // 保留 ?.:public 缺失时按 undefined 处理(与改动前一致,不引入抛错路径)
+    if (PUBLIC_FIELDS[key]) return rc.public?.[PUBLIC_FIELDS[key]]
+    if (ROOT_FIELDS[key]) return rc[ROOT_FIELDS[key]]
+    if (key.startsWith(DAQ_PREFIX)) return getPath(rc.daq, key.slice(DAQ_PREFIX.length))
+    return undefined
+  }
+
+  /** 把某 key 的生效值写入 runtimeConfig（live 应用；restart 键仅改内存视图供展示）。
+   *  Nitro 4 中 runtimeConfig.public 为只读对象 → 赋值抛错；此处降级:
+   *  视图以本服务内存 effective 为唯一实时源，前端经 SSE 消费；SSR 读取在下次启动后对齐。 */
+  protected applyToRuntime(key: string, value: unknown): void {
+    try {
+      const rc = useRuntimeConfig() as RuntimeConfigView
+      if (PUBLIC_FIELDS[key]) {
+        rc.public[PUBLIC_FIELDS[key]] = value
+        return
+      }
+      if (ROOT_FIELDS[key]) {
+        rc[ROOT_FIELDS[key]] = value
+        return
+      }
+      if (key.startsWith(DAQ_PREFIX)) {
+        setPath(daqView(rc), key.slice(DAQ_PREFIX.length), value)
+      }
+    }
+    catch {
+      if (!this.applyWarned) {
+        this.applyWarned = true
+        console.warn('[system-config] runtimeConfig 只读 → live 应用降级为服务内存视图 + SSE 广播(前端实时;服务端 SSR 完整生效需重启)')
+      }
+    }
+  }
+}

package/server/services/system-config/recompute.ts

@@ -0,0 +1,66 @@
+/**
+ * SystemConfigServiceRecompute —— 有效值重算与磁盘重载
+ * (拆分层,承 SystemConfigServicePlugins;方法体与原文件逐行一致)
+ */
+import { SystemConfigServicePlugins } from './plugins'
+import { readSettings, validateValue } from '@/shared/config/engine.mjs'
+
+export abstract class SystemConfigServiceRecompute extends SystemConfigServicePlugins {
+  /** 全部描述符重算 effective + sources（base = runtimeConfig 构建值）
+   *  并可选地把 live 键应用到 runtimeConfig */
+  protected recompute({ applyLive = true } = {}): void {
+    const effective: Record<string, unknown> = {}
+    const sources: Record<string, 'config.yml' | 'runtime' | 'env'> = {}
+    for (const desc of this.allDescriptors) {
+      let value: unknown
+      let source: 'config.yml' | 'runtime' | 'env'
+      if (this.envOverrides[desc.key] !== undefined) {
+        value = this.envOverrides[desc.key]
+        source = 'env'
+      }
+      else if (this.overrides[desc.key] !== undefined) {
+        value = this.overrides[desc.key]
+        source = 'runtime'
+      }
+      else {
+        const base = this.readBase(desc.key)
+        value = base !== undefined ? base : desc.default
+        source = 'config.yml'
+      }
+      effective[desc.key] = value
+      sources[desc.key] = source
+      if (applyLive || this.overrides[desc.key] !== undefined) this.applyToRuntime(desc.key, value)
+    }
+    this.effective = effective
+    this.sources = sources
+  }
+
+  /** 从磁盘重读设置文件 → 校验 → recompute → 广播 */
+  reloadFromDisk(): { changed: string[] } {
+    const before = this.overrides
+    const raw = readSettings(this.settingsPath)
+    const validated: Record<string, unknown> = {}
+    const changed: string[] = []
+    for (const [key, value] of Object.entries(raw)) {
+      const desc = this.map[key]
+      if (!desc) continue // 未知键：忽略（schema 演进容错）
+      const errs = validateValue(desc, value)
+      if (errs.length) {
+        console.warn(`[system-config] 忽略无效运行时覆盖 ${key}=${JSON.stringify(value)}: ${errs.join('; ')}`)
+        continue
+      }
+      validated[key] = value
+      if (before[key] !== value) changed.push(key)
+    }
+    for (const key of Object.keys(before)) {
+      if (!(key in validated) && key in before) changed.push(key)
+    }
+    this.overrides = validated
+    this.recompute()
+    // 运行语义设置读取层(settings.ts effective 3s TTL)即时失效:live 键热重载零延迟
+    void import('../workshop/settings').then(m => m.invalidateRuntimeSettingsCache()).catch(() => {})
+    return { changed }
+  }
+
+  /* ---------------- 文件监听（外部写入热重载） ---------------- */
+}

package/server/services/system-config/snapshot.ts

@@ -0,0 +1,59 @@
+/**
+ * SystemConfigServiceSnapshot —— 文件监听 / 快照 / 路径访问器
+ * (拆分层,承 SystemConfigServiceRecompute;方法体与原文件逐行一致)
+ */
+import { SystemConfigServiceRecompute } from './recompute'
+import type { PublicSnapshot } from './types'
+import { errorText } from './helpers'
+import { existsSync, watch } from 'node:fs'
+import { join } from 'node:path'
+
+export abstract class SystemConfigServiceSnapshot extends SystemConfigServiceRecompute {
+  protected watchFiles(): void {
+    const dataDir = join(this.root, 'data')
+    const handler = (eventType: string, filename: string | null) => {
+      const name = filename ?? ''
+      const isSettings = name.includes('runtime-settings.json')
+      const isConfig = name.includes('config.yml')
+      if (!isSettings && !isConfig) return
+      // atomic 写（tmp+rename）在 Windows 上会以 rename/unlink 触发；防抖合并
+      if (this.reloadTimer) clearTimeout(this.reloadTimer)
+      this.reloadTimer = setTimeout(() => {
+        if (this.disposed) return
+        const { changed } = this.reloadFromDisk()
+        this.broadcast({ type: 'config:reloaded', changed, ...this.eventTail() })
+      }, 300)
+    }
+    try {
+      if (existsSync(dataDir)) this.watcher.push(watch(dataDir, { persistent: false }, handler))
+      if (existsSync(this.root)) this.watcher.push(watch(this.root, { persistent: false }, handler))
+    }
+    catch (err) {
+      console.warn('[system-config] 文件监听不可用（外部写入将不热重载）:', errorText(err))
+    }
+  }
+
+  /* ---------------- 公共 API ---------------- */
+
+  snapshot(): PublicSnapshot {
+    return {
+      descriptors: this.allDescriptors,
+      groups: this.listGroups(),
+      effective: { ...this.effective },
+      overrides: { ...this.overrides },
+      sources: { ...this.sources },
+      settingsPath: this.settingsPath,
+      configPath: this.configPath,
+    }
+  }
+
+  /** 分组注册文件路径(设置页展示用) */
+  get groupRegistryPath(): string {
+    return this.groupsPath
+  }
+
+  /** 生效的运行时设置文件路径(启动日志/排障用;经 resolveRunMode 解析,非写死的 <cwd>/data) */
+  get effectiveSettingsPath(): string {
+    return this.settingsPath
+  }
+}

package/server/services/system-config/state.ts

@@ -0,0 +1,79 @@
+/**
+ * SystemConfigServiceState —— 状态字段与派生视图
+ * (拆分层,承 SystemConfigServiceContracts;方法体与原文件逐行一致)
+ */
+import { SystemConfigServiceContracts } from './contracts'
+import type { ConfigGroup, Listener } from './types'
+import type { SettingsDescriptor } from '@/shared/config/engine.mjs'
+import type { watch } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { errorText } from './helpers'
+import { groupsPathFor } from '@/shared/config/groups.mjs'
+import { resolveRunMode } from '@/shared/config/home.mjs'
+
+export abstract class SystemConfigServiceState extends SystemConfigServiceContracts {
+  protected descriptors: SettingsDescriptor[] = []
+  /** 插件贡献的设置描述符(host 装载/热重载后注入;key 编址 plugins.<plugin>.<key>) */
+  protected pluginDescriptors: SettingsDescriptor[] = []
+  /** 插件声明的配置分组(host 装载/热重载后注入;卸载即摘除) */
+  protected pluginGroups: ConfigGroup[] = []
+  /** 插件名 → 展示名(自动生成插件分组标题用) */
+  protected pluginLabels = new Map<string, string>()
+  /** 管理员定制 + 自建分组的持久化副本 */
+  protected userGroups: ConfigGroup[] = []
+  /** key → 描述符(loadDescriptorMap 返回普通对象,非 Map;下标访问;含插件描述符) */
+  protected map: Record<string, SettingsDescriptor> = {}
+  protected overrides: Record<string, unknown> = {}
+  protected envOverrides: Record<string, unknown> = {}
+  protected effective: Record<string, unknown> = {}
+  protected sources: Record<string, 'config.yml' | 'runtime' | 'env'> = {}
+  protected listeners = new Set<Listener>()
+  protected configPath = ''
+  protected settingsPath = ''
+  protected groupsPath = ''
+  protected watcher: ReturnType<typeof watch>[] = []
+  protected reloadTimer: NodeJS.Timeout | null = null
+  protected disposed = false
+  protected applyWarned = false
+
+  /** 是否已完成 init()(descriptors 装载完毕;settings.ts 据此决定消费内存权威还是文件链) */
+  get ready(): boolean {
+    return this.descriptors.length > 0
+  }
+
+  /** 全量描述符 = 全局 schema + 插件声明(插件项以 plugins.<plugin>.<key> 编址,不与全局键冲突) */
+  protected get allDescriptors(): SettingsDescriptor[] {
+    return this.pluginDescriptors.length ? [...this.descriptors, ...this.pluginDescriptors] : this.descriptors
+  }
+
+  constructor(readonly root: string) {
+    super()
+    this.configPath = join(root, 'config.yml')
+    // 设置文件必须与 CLI(aw config set)/start/dev-guard 同源(resolveRunMode 单一入口):
+    // 原先写死 <cwd>/data/runtime-settings.json 造成"API 写 A、子系统读 B"的脑裂 —— 备份
+    // 周期/保留期/DAQ 覆盖等运行时设置对服务端静默无效。
+    const rm = resolveRunMode({ cwd: root, packageRoot: process.env.AW_PACKAGE_ROOT, env: process.env })
+    this.configPath = rm.configPath ?? this.configPath
+    this.settingsPath = rm.settingsPath ?? this.settingsPath
+    // 分组注册表与 runtime-settings.json 同目录(同为运行时状态,随配置根走)
+    this.groupsPath = groupsPathFor(dirname(this.settingsPath))
+    // 一次性收敛:遗留 <cwd>/data/runtime-settings.json 且目标不存在 → 迁移;两者并存 → 告警遗留被忽略
+    try {
+      const legacy = join(root, 'data', 'runtime-settings.json')
+      if (existsSync(legacy) && legacy !== this.settingsPath) {
+        if (!existsSync(this.settingsPath)) {
+          mkdirSync(dirname(this.settingsPath), { recursive: true })
+          copyFileSync(legacy, this.settingsPath)
+          console.log(`[system-config] 遗留设置已迁移: ${legacy} -> ${this.settingsPath}`)
+        }
+        else {
+          console.warn(`[system-config] 检测到遗留设置文件 ${legacy}(现以 ${this.settingsPath} 为准,该文件被忽略)`)
+        }
+      }
+    }
+    catch (err) {
+      console.warn('[system-config] 遗留设置迁移失败(不阻断启动):', errorText(err))
+    }
+  }
+}

package/server/services/system-config/types.ts

@@ -0,0 +1,58 @@
+/**
+ * SystemConfigService 的依赖类型与对外 DTO(原 server/services/system-config.ts 顶部模块级类型声明)。纯类型。
+ */
+import type { SettingsDescriptor } from '@/shared/config/engine.mjs'
+
+export interface ConfigGroup {
+  id: string
+  label: string
+  labelKey?: string
+  description: string
+  /** 排序权重(小在前);内置分组按 schema 声明顺序 ×10。
+   *  可缺省:持久化条目与插件声明允许不写 order,由 shared/config/groups.mjs 的
+   *  mergeGroups 沿用内置声明顺序兜底(消费侧见 nextGroupOrder/updateGroup 均按可缺省处理)。 */
+  order?: number
+  /** 前端默认折叠态(用户本地展开偏好优先) */
+  collapsed: boolean
+  collapsible: boolean
+  icon: string
+  source: 'builtin' | 'user' | 'plugin'
+  /** source=plugin 时的插件名 */
+  plugin?: string
+  /** 该分组下的字段数(只读,由服务端按当前描述符实时计算) */
+  fieldCount?: number
+}
+
+/* ---------- 描述符 key → runtimeConfig 字段映射 ----------
+ * nuxt.config runtimeConfig 的结构：
+ *   public.appTitle/appTitle/description/mode/apiBase/apiTimeout/primaryColor/themeMode/...
+ *   apiPageSize / apiMaxPageSize / approvalGate / daq.{...}
+ */
+export interface PublicSnapshot {
+  descriptors: SettingsDescriptor[]
+  /** 有序分组(后端权威;前端据此渲染分区、顺序、折叠态) */
+  groups: ConfigGroup[]
+  effective: Record<string, unknown>
+  overrides: Record<string, unknown>
+  sources: Record<string, 'config.yml' | 'runtime' | 'env'>
+  settingsPath: string
+  configPath: string
+}
+
+/** 广播载荷 */
+export interface ConfigEventPayload {
+  type: 'config:changed' | 'config:reset' | 'config:reloaded'
+  changed: string[]
+  restartRequired: string[]
+  effective: Record<string, unknown>
+  sources: Record<string, unknown>
+  overrides: Record<string, unknown>
+  at: string
+}
+
+export type Listener = (payload: ConfigEventPayload) => void
+
+/** runtimeConfig 的动态视图:PUBLIC_FIELDS(public.*)/ROOT_FIELDS(根字段)/daq.* 三处动态读写共用 */
+export type RuntimeConfigView = Record<string, unknown> & { public: Record<string, unknown> }
+
+/** 从 catch 的 unknown 值取可读错误文本(与原先的 String(err?.message ?? err) 运行时完全等价) */

package/server/services/workshop/agents/adapters/line-spawn.ts

@@ -37,10 +37,10 @@ export function resolveOnPath(command: string): string | null {
     }
   }
   const hasDir = command.includes('/') || command.includes('\\') || /^[A-Za-z]:/.test(command)
-  const exts = (process.env.PATHEXT?.split(';').filter(Boolean) ?? ['.EXE', '.CMD', '.BAT', '.COM']).map(e => e.toLowerCase())
+  const exts = ((process.env.PATHEXT ?? process.env.PathExt)?.split(';').filter(Boolean) ?? ['.EXE', '.CMD', '.BAT', '.COM']).map(e => e.toLowerCase())
   const bases = hasDir
     ? [command]
-    : (process.env.PATH ?? '').split(';').filter(Boolean).map(dir => join(dir, command))
+    : (process.env.PATH ?? process.env.Path ?? '').split(';').filter(Boolean).map(dir => join(dir, command))
   // PATHEXT 顺序(.exe → .cmd → …)优先;裸名兜底(npm sh 脚本,win 上不可执行,仅最后回退)
   for (const base of bases) {
     for (const ext of exts) {

package/server/services/workshop/agents/adapters/omp-rpc-client/api.ts

@@ -0,0 +1,111 @@
+/**
+ * OmpRpcClientApi —— 发送命令 / 事件与原始帧订阅 / 宿主工具回调 / 释放
+ * (拆分层,承 OmpRpcClientStart;方法体与原文件逐行一致)
+ */
+import { OmpRpcClientStart } from './start'
+import type { AgentSessionEvent, HostToolHandler, RpcCommand, RpcResponse } from './types'
+
+export abstract class OmpRpcClientApi extends OmpRpcClientStart {
+  /** 发送命令,等待关联响应 */
+  async send<T = RpcResponse>(command: RpcCommand): Promise<T & RpcResponse> {
+    if (!this.child?.stdin?.writable) throw new Error('omp 子进程未就绪或已关闭')
+    if (this.disposed) throw new Error('omp RPC 客户端已 dispose')
+
+    const id = command.id ?? `req_${++this.seq}`
+    const frame = JSON.stringify({ ...command, id }) + '\n'
+
+    return new Promise<T & RpcResponse>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error(`omp RPC 命令超时: ${command.type} (id=${id})`))
+      }, 60_000)
+
+      this.pending.set(id, {
+        resolve: resolve as (r: RpcResponse) => void,
+        reject,
+        timer,
+      })
+
+      this.child!.stdin!.write(frame, (err) => {
+        if (err) {
+          this.pending.delete(id)
+          clearTimeout(timer)
+          reject(new Error(`omp RPC 写入失败: ${err.message}`))
+        }
+      })
+    })
+  }
+
+  /** 订阅 AgentSessionEvent 流 */
+  onEvent(fn: (event: AgentSessionEvent) => void): () => void {
+    this.eventListeners.add(fn)
+    return () => {
+      this.eventListeners.delete(fn)
+    }
+  }
+
+  /**
+   * 订阅原始帧流(chunk 重组后的每一帧,含 response / host_tool_call /
+   * extension_ui_request / 全部会话事件)。终端镜像(harness-terminal)的事实源。
+   */
+  onRawFrame(fn: (frame: Record<string, unknown>) => void): () => void {
+    this.rawFrameListeners.add(fn)
+    return () => {
+      this.rawFrameListeners.delete(fn)
+    }
+  }
+
+  /**
+   * 写入原始 stdin 帧(不走命令/响应关联)——用于 side-channel 帧
+   * (extension_ui_response 等)。
+   */
+  writeRaw(frame: Record<string, unknown>): void {
+    if (!this.child?.stdin?.writable) throw new Error('omp 子进程未就绪或已关闭')
+    this.child.stdin.write(JSON.stringify(frame) + '\n')
+  }
+
+  /** 注册 host 工具 handler(omp 调用宿主工具时回调) */
+  onHostToolCall(handler: HostToolHandler): void {
+    this.hostToolHandler = handler
+  }
+
+  /** 优雅关闭:中止当前 prompt → 等待退出 */
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+
+    // 尝试优雅关闭(stdin close → omp 排空后 exit 0)
+    try {
+      if (this.child?.stdin && !this.child.stdin.destroyed) {
+        this.child.stdin.end()
+      }
+    }
+    catch {
+      // ignore
+    }
+
+    // 等待退出,最多 3s
+    await new Promise<void>((resolve) => {
+      if (!this.child || this.child.killed || this.exited) return resolve()
+      const timer = setTimeout(() => {
+        this.child?.kill('SIGKILL')
+        resolve()
+      }, 3_000)
+      this.child!.once('exit', () => {
+        clearTimeout(timer)
+        resolve()
+      })
+    })
+
+    // 清理 pending
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer)
+      p.reject(new Error('omp RPC 客户端已 dispose'))
+    }
+    this.pending.clear()
+    this.eventListeners.clear()
+    this.rawFrameListeners.clear()
+  }
+
+  // ===== 内部 =====
+}

package/server/services/workshop/agents/adapters/omp-rpc-client/contracts.ts

@@ -0,0 +1,22 @@
+/**
+ * OmpRpcClientContracts —— **跨层能力契约**。
+ *
+ * 拆成 6 层后,有 5 个方法只被"更早的层"调用;
+ * 与其把层序排成拓扑序打散职责,不如显式声明为抽象签名,由实现它的层提供(编译期校验)。
+ *
+ * 契约成员:
+ *   handleChunk  → 由 frames.ts 实现
+ *   handleExit  → 由 frames.ts 实现
+ *   handleHostToolCall  → 由 frames.ts 实现
+ *   notifyError  → 由 frames.ts 实现
+ *   onStdout  → 由 stdout.ts 实现
+ */
+import type { HostToolCallFrame, RpcChunkFrame } from './helpers'
+
+export abstract class OmpRpcClientContracts {
+  protected abstract handleChunk(frame: RpcChunkFrame): void
+  protected abstract handleExit(code: number | null): void
+  protected abstract handleHostToolCall(req: HostToolCallFrame): Promise<void>
+  protected abstract notifyError(err: Error): void
+  protected abstract onStdout(data: string): void
+}

package/server/services/workshop/agents/adapters/omp-rpc-client/facade.ts

@@ -0,0 +1,7 @@
+/**
+ * OmpRpcClient —— 组合各分层后的最终类(可见性/继承/实现接口与拆分前一致)
+ * + 原文件类体之后引用本类的模块级代码(单例/工厂/广播装配)。
+ */
+import { OmpRpcClientFrames } from './frames'
+
+export class OmpRpcClient extends OmpRpcClientFrames {}