agentworkshop 0.7.34 → 0.7.38

package/server/services/workshop/aml/runtime.ts

@@ -1,38 +1,107 @@
 /**
  * AML 运行时装配:db + 数据根目录 + 仓储访问器(插件 workshop.ts 装配,REST/工具读取)。
- * 数据落盘布局(<configRoot>/data/aml/):
+ *
+ * 数据落盘布局(<项目根>/aml/ —— 见 shared/config/home.mjs resolveAmlRoot):
+ *   .venv/             uv 创建的 Python 环境(固定位置,整体可删重建)
  *   datasets/<dsId>/   spec.json + manifest.json + report.json + arrays/*.f32
  *   jobs/<jobId>/      job.json + workspace/(train.py, amlkit.py) + run.log + artifacts/
  *   models/<modelId>/  model.onnx + io_spec.json(注册时从作业工件拷贝,不可变)
+ *   runtime/           运行时状态(uv.json 安装记录 / env.json 探针缓存)
+ *   tools/             项目本地自动安装的 uv 二进制(免管理员、不改 PATH)
+ *
+ * 元数据(SQLite 四表)与实体(磁盘目录)以 id 一一对应:
+ *   aml_datasets.id ↔ datasets/<id>/,aml_jobs.id ↔ jobs/<id>/,aml_models.id ↔ models/<id>/
+ * reconcileEntity() 负责两侧对账(元数据在而实体丢失 → 标记;实体在而元数据丢失 → 认领/清理)。
  */
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import type { DatabaseSync } from 'node:sqlite'
 import { AppError } from '../../../utils/errors'
+import { ensureAmlDir, resolveAmlRoot } from '@/shared/config/home.mjs'
 import { createAmlRepo, type AmlRepo } from './aml.repo'
 
 export interface AmlRuntime {
   db: DatabaseSync
-  /** <configRoot>/data/aml 绝对路径 */
+  /** <项目根>/aml 绝对路径 */
   root: string
+  /** 数据根解析来源(env/repo/home/cwd;UI 显示与排障用) */
+  rootMode: string
+  projectRoot: string | null
   repo: AmlRepo
   datasetsDir: string
   jobsDir: string
   modelsDir: string
+  /** uv venv 落点: <root>/.venv */
+  venvDir: string
+  /** 项目本地 uv 二进制落点: <root>/tools */
+  toolsDir: string
+  /** 运行时状态(安装记录/探针缓存): <root>/runtime */
+  runtimeDir: string
 }
 
 const g = globalThis as typeof globalThis & { __amlRuntime?: AmlRuntime }
 
-export function configureAmlRuntime(db: DatabaseSync, dataDir: string): AmlRuntime {
+/** 目录骨架说明文件(首次创建时落盘,便于人工理解 ./aml 的用途与清理方式) */
+const README = `# AML 平台数据目录
+
+本目录是 AgentWorkShop 自动建模(AML)平台的**全部资产根**,由服务自动创建与维护。
+
+## 目录约定
+
+| 路径 | 内容 | 可否手删 |
+| --- | --- | --- |
+| \`.venv/\` | uv 创建/管理的 Python 环境(依赖锁定在平台的 requirements.txt) | 可删,下次供给自动重建 |
+| \`datasets/<id>/\` | 数据集实体:\`spec.json\` 取数规格、\`manifest.json\` 列定义、\`report.json\` 质量报告、\`arrays/*.f32\` 列式数组 | 先删元数据行,再删目录 |
+| \`jobs/<id>/\` | 训练作业实体:\`job.json\` 提交契约、\`workspace/\`(train.py + amlkit.py)、\`run.log\`、\`artifacts/\`(产出模型) | 同上 |
+| \`models/<id>/\` | 模型实体:\`model.onnx\` + \`io_spec.json\`(输入输出契约,不可变) | 同上 |
+| \`runtime/\` | 平台运行时状态:uv 安装记录(\`uv.json\`)、环境探针快照(\`env.json\`) | 可删,自动重建 |
+| \`tools/\` | 平台自动安装的 uv 二进制(免管理员、不改系统 PATH) | 可删,可重新一键安装 |
+
+## 元数据与实体的关系
+
+平台用 SQLite 四表保存**元数据**(数据集/作业/实验/模型),用本目录保存**实体**。
+两者以 id 一一对应;REST 的 \`/api/workshop/aml/*\` 提供元数据 CRUD,
+删除元数据时同步清理对应实体目录(有引用的数据集会被拒绝删除)。
+
+## 迁移到别的机器
+
+整个 \`aml/\` 目录可直接拷贝(含 \`.venv\` 与模型工件);目标机若无同版本 Python,
+删掉 \`.venv/\` 让平台按本机解释器重建即可 —— 数据集与模型工件不受影响。
+`
+
+const GITIGNORE = `# AML 运行时资产:体积大且与机器绑定,不入库
+.venv/
+tools/
+runtime/
+datasets/
+jobs/
+models/
+`
+
+export function configureAmlRuntime(db: DatabaseSync, _dataDir?: string): AmlRuntime {
   if (g.__amlRuntime) return g.__amlRuntime
-  const root = join(dataDir, 'aml')
+  const resolved = resolveAmlRoot({})
+  const root = ensureAmlDir()
   const rt: AmlRuntime = {
     db,
     root,
+    rootMode: resolved.mode,
+    projectRoot: resolved.projectRoot,
     repo: createAmlRepo(db),
     datasetsDir: join(root, 'datasets'),
     jobsDir: join(root, 'jobs'),
     modelsDir: join(root, 'models'),
+    venvDir: join(root, '.venv'),
+    toolsDir: join(root, 'tools'),
+    runtimeDir: join(root, 'runtime'),
   }
+  mkdirSync(rt.venvDir, { recursive: true })
+  // 目录自述与忽略规则只在缺失时写,不覆盖用户改动
+  try {
+    if (!existsSync(join(root, 'README.md'))) writeFileSync(join(root, 'README.md'), README)
+    if (!existsSync(join(root, '.gitignore'))) writeFileSync(join(root, '.gitignore'), GITIGNORE)
+  }
+  catch { /* 元信息落盘失败不阻断平台装配 */ }
   g.__amlRuntime = rt
   return rt
 }
@@ -43,3 +112,25 @@ export function getAmlRuntime(): AmlRuntime {
   }
   return g.__amlRuntime
 }
+
+/** 数据根解析来源的中文说明(UI 展示) */
+export function amlRootSourceLabel(mode: string): string {
+  switch (mode) {
+    case 'env': return '环境变量 AW_AML_DIR 指定'
+    case 'repo': return '项目检出根(./aml)'
+    case 'home': return '用户配置根(~/.AgentWorkShop/aml)'
+    default: return '当前工作目录(./aml)'
+  }
+}
+
+/**
+ * 路径是否位于 AML 资产根内 —— 删除实体目录前的越界防护。
+ * 元数据行里的 path 字段来自历史写入,不能无条件信任:它理论上可能是任意绝对路径,
+ * 直接 rmSync 会造成"删一条元数据把用户别处的目录删掉"。
+ */
+export function isInsideAmlRoot(rt: AmlRuntime, p: string): boolean {
+  const norm = (s: string) => s.replace(/\\/g, '/').replace(/\/+$/, '')
+  const root = norm(rt.root)
+  const target = norm(p)
+  return target === root || target.startsWith(`${root}/`)
+}

package/server/services/workshop/daq/bus/mqtt.adapter.ts

@@ -123,7 +123,9 @@ export class MqttQueueAdapter implements DaqQueuePort {
         // end() 回调在某些断连路径下不触发,旧 client 的 connect/message/error 监听器
         // 会连同 socket 一起滞留(client 对象被闭包引用,GC 不可达)。
         // rebuildDaqQueue 反复换装时会累积;显式摘除是唯一确定性的清理点。
-        try { c.removeAllListeners() }
+        try {
+          c.removeAllListeners()
+        }
         catch { /* 已销毁等场景:尽力而为 */ }
       }
     }

package/server/services/workshop/daq/daq-controller.ts

@@ -393,7 +393,7 @@ class DaqController {
     const lineRun = getDaqHostPorts()?.lineRun.activeRun(node.lineId) ?? null
     if (lineRun) getDaqHostPorts()?.lineRun.bumpTaggedSamples(node.lineId)
     const metrics = f.metrics ?? {}
-    this.frameBuffer.push({
+    this.pushFrame({
       nodeId: node.id,
       tsMs,
       kind: f.kind,
@@ -410,8 +410,7 @@ class DaqController {
       metrics,
     })
     if (this.frameBuffer.length > FRAME_BUFFER_CAP) {
-      this.frameBuffer.splice(0, this.frameBuffer.length - FRAME_BUFFER_CAP)
-      this.tsdbDropped += 1
+      if (this.evictFrames(FRAME_BUFFER_CAP) > 0) this.tsdbDropped += 1
     }
     this.scheduleTsdbFlush()
     // 指标阈值告警(模板 metrics 规则;alarm 硬限边沿 → 既有告警链路)
@@ -515,14 +514,6 @@ class DaqController {
     this.emitController()
   }
 
-  /** 网关停止:全部节点置 offline */
-  markAllOffline(): void {
-    for (const n of this.repo.all()) {
-      if (n.enabled) n.state = 'offline'
-    }
-    this.emitController()
-  }
-
   /** 运行时注册表对账(仓库为权威:增删节点/启动即对齐;返回新建的运行时) */
   private syncRuntimes(): void {
     const live = new Set<string>()
@@ -665,8 +656,10 @@ class DaqController {
         }
       }
       // 帧批(v2:daq_frames;与样本同窗同重试语义)
-      while (this.frameBuffer.length > 0) {
-        const batch = this.frameBuffer.splice(0, this.frameBuffer.length)
+      // drainFrames 一次性取走并清空索引 —— 索引与缓冲必须同生命周期,否则查询会命中已刷盘的行
+      let pendingFrames = this.drainFrames()
+      while (pendingFrames.length > 0) {
+        const batch = pendingFrames
         let ok = false
         for (let attempt = 0; attempt < TSDB_WRITE_RETRIES && !ok; attempt++) {
           try {
@@ -684,6 +677,7 @@ class DaqController {
             }
           }
         }
+        pendingFrames = this.drainFrames()
       }
     }
     finally {
@@ -765,11 +759,6 @@ class DaqController {
     this.broadcast = fn
   }
 
-  onlineCount(): number {
-    if (!this.running) return 0
-    return this.repo.all().filter(n => n.enabled).length
-  }
-
   controllerState(): AepDaqControllerState & { produced?: number, consumed?: number, dropped?: number, samplesStored?: number, tsdbDropped?: number } {
     // 丢弃 = 队列层真实丢弃(inproc 拥塞/mqtt 断连)+ 消费侧乱序迟到帧(诚实可见)
     const queueLost = g_queueLost()
@@ -824,29 +813,83 @@ class DaqController {
     return getTsdb().query(id, opts)
   }
 
-  /** 帧查询的「内存读穿透」:帧先入 frameBuffer 再广播 thumbUrl(contentUrl),
-   *  TSDB 为 500ms 防抖异步刷盘 —— 收到 WS 立刻回查会在落库前 404。
-   *  故查询侧按 (nodeId, tsMs) 先看 buffer 命中;与 TSDB 返回形态逐字段对齐
-   *  (points 从 meta.points 还原,规则同 tsdb adapter 的 pointsFromMeta)。
-   *  注:刷盘 splice 与查询同一 JS 线程,不存在「既不在 buffer 又没落库」的空窗。 */
-  private framesFromBuffer(id: string, tsMs: number): DaqFrameRecord[] {
-    const out: DaqFrameRecord[] = []
-    for (const r of this.frameBuffer) {
-      if (r.nodeId !== id || r.tsMs !== tsMs) continue
-      out.push({
-        at: r.tsMs,
-        kind: r.kind,
-        points: r.kind === 'vector' ? DaqController.pointsFromMeta(r.meta) : undefined,
-        metrics: r.metrics,
-        meta: r.meta,
-        deviceBindingId: r.deviceBindingId ?? null,
-        lineId: r.lineId ?? null,
-        productId: r.productId ?? null,
-        recipeId: r.recipeId ?? null,
-        runId: r.runId ?? null,
-      })
+  /**
+   * 帧查询的「内存读穿透」索引 —— 帧先入 frameBuffer 再广播 thumbUrl(contentUrl),
+   * TSDB 为 500ms 防抖异步刷盘,收到 WS 立刻回查会在落库前 404,故查询侧先看 buffer。
+   *
+   * 为什么要有索引:早先 frameContent 直接线性扫 frameBuffer,而 frames() 更糟 ——
+   * 它对每个 pending 行都调一次 framesFromBuffer(),即**在 O(n) 的外层里再套 O(n) 的全扫**
+   * (n = FRAME_BUFFER_CAP = 2000):突发写入后缓冲全满时,单次 REST 查询 ≈ 4×10⁶ 次迭代
+   * + 2000 次多余对象构造,而它和 250ms 采样 sweep 跑在同一个事件循环上。
+   *
+   * 现在:byNode 按节点分桶(范围查询只扫该节点的行),byKey 给出 (nodeId, tsMs) 的 O(1) 命中。
+   * 两个索引与 frameBuffer 严格同生命周期 —— 所有 push/淘汰/flush 都必须经下面的私有方法,
+   * 不允许直接操作 frameBuffer,否则索引会与缓冲漂移(表现为"刚采到的帧查不到")。
+   */
+  private readonly frameByNode = new Map<string, DaqFrameRow[]>()
+  private readonly frameByKey = new Map<string, DaqFrameRow>()
+
+  /** 帧索引键((nodeId, tsMs) 唯一:同一节点同一毫秒只会有一帧) */
+  private static frameKey(nodeId: string, tsMs: number): string {
+    return `${nodeId}@${tsMs}`
+  }
+
+  /** 入缓冲 + 同步三处索引 */
+  private pushFrame(row: DaqFrameRow): void {
+    this.frameBuffer.push(row)
+    const key = DaqController.frameKey(row.nodeId, row.tsMs)
+    this.frameByKey.set(key, row)
+    const bucket = this.frameByNode.get(row.nodeId)
+    if (bucket) bucket.push(row)
+    else this.frameByNode.set(row.nodeId, [row])
+  }
+
+  /** 淘汰最旧若干行,并同步清理索引(避免索引持有已淘汰行的强引用 → 内存泄漏) */
+  private evictFrames(keepLast: number): number {
+    const excess = this.frameBuffer.length - keepLast
+    if (excess <= 0) return 0
+    const dropped = this.frameBuffer.splice(0, excess)
+    for (const row of dropped) {
+      const key = DaqController.frameKey(row.nodeId, row.tsMs)
+      // 同键只可能有一行;但仍比对引用,防同毫秒重采覆盖后误删新行
+      if (this.frameByKey.get(key) === row) this.frameByKey.delete(key)
+      const bucket = this.frameByNode.get(row.nodeId)
+      if (!bucket) continue
+      const idx = bucket.indexOf(row)
+      if (idx >= 0) bucket.splice(idx, 1)
+      if (bucket.length === 0) this.frameByNode.delete(row.nodeId)
     }
-    return out
+    return dropped.length
+  }
+
+  /** 取走全部帧(刷盘用)并清空索引 */
+  private drainFrames(): DaqFrameRow[] {
+    if (this.frameBuffer.length === 0) return []
+    const batch = this.frameBuffer.splice(0, this.frameBuffer.length)
+    this.frameByNode.clear()
+    this.frameByKey.clear()
+    return batch
+  }
+
+  /** 单行 → 对外记录(纯映射,不做任何扫描) */
+  private static toFrameRecord(r: DaqFrameRow): DaqFrameRecord {
+    return {
+      at: r.tsMs,
+      kind: r.kind,
+      points: r.kind === 'vector' ? DaqController.pointsFromMeta(r.meta) : undefined,
+      metrics: r.metrics,
+      meta: r.meta,
+      deviceBindingId: r.deviceBindingId ?? null,
+      lineId: r.lineId ?? null,
+      productId: r.productId ?? null,
+      recipeId: r.recipeId ?? null,
+      runId: r.runId ?? null,
+    }
+  }
+
+  /** (nodeId, tsMs) 精确命中未刷盘帧;O(1) */
+  private bufferedFrameAt(id: string, tsMs: number): DaqFrameRow | undefined {
+    return this.frameByKey.get(DaqController.frameKey(id, tsMs))
   }
 
   /** 向量点列从 meta.points 还原(与 TSDB adapter 同规则:非数组/空/越界/非数值 → undefined) */
@@ -865,13 +908,15 @@ class DaqController {
     const rows = await getTsdb().queryFrames(id, opts)
     // 未刷盘的帧补进结果集:同 (nodeId, tsMs) 以落库行为准(去重),按 at 降序
     const seen = new Set(rows.map(r => r.at))
-    const pending = this.frameBuffer.filter(r => r.nodeId === id
-      && (opts.kind == null || r.kind === opts.kind)
-      && r.tsMs >= (opts.fromMs ?? 0) && r.tsMs <= (opts.toMs ?? Date.now()))
-      .filter(r => !seen.has(r.tsMs))
+    const toMs = opts.toMs ?? Date.now()
+    const fromMs = opts.fromMs ?? 0
+    // 只扫本节点的桶(而非整条缓冲),再按范围/类型过滤;映射用纯函数,无二次扫描
+    const pending = (this.frameByNode.get(id) ?? [])
+      .filter(r => (opts.kind == null || r.kind === opts.kind)
+        && r.tsMs >= fromMs && r.tsMs <= toMs
+        && !seen.has(r.tsMs))
       .sort((a, b) => b.tsMs - a.tsMs)
-      .map(r => this.framesFromBuffer(id, r.tsMs)[0] ?? null)
-      .filter((r): r is DaqFrameRecord => r != null)
+      .map(DaqController.toFrameRecord)
     return [...rows, ...pending].slice(0, Math.min(Math.max(opts.limit ?? 100, 1), 1000))
   }
 
@@ -882,7 +927,10 @@ class DaqController {
     const node = this.repo.byId(id)
     if (!node) throw Object.assign(new Error(`数采节点不存在: ${id}`), { status: 404 })
     // 读穿透:先查内存攒批缓冲(帧刚 ingest、尚未刷盘时命中),未命中再查 TSDB
-    const rows = this.framesFromBuffer(id, tsMs)
+    const buffered = this.bufferedFrameAt(id, tsMs)
+    const rows = buffered
+      ? [DaqController.toFrameRecord(buffered)]
+      : await getTsdb().queryFrames(id, { fromMs: tsMs - 1, toMs: tsMs + 1, limit: 5 })
     if (rows.length === 0) rows.push(...await getTsdb().queryFrames(id, { fromMs: tsMs - 1, toMs: tsMs + 1, limit: 5 }))
     const row = rows.find(r => r.at === tsMs)
     if (!row || row.kind !== 'image') throw Object.assign(new Error(`帧不存在: ${id}@${tsMs}`), { status: 404 })

package/server/services/workshop/daq/daq-node.repo.ts

@@ -74,16 +74,6 @@ class DaqNodeRepo {
       log.error('[daq] 快照落盘失败:', err)
     }
   }
-
-  /** 读数落盘防抖(采样循环每帧调用;5s 合并一次磁盘写) */
-  flushDebounced(ms = 5000): void {
-    if (this.flushTimer) return
-    this.flushTimer = setTimeout(() => {
-      this.flushTimer = null
-      this.flushNow()
-    }, ms)
-    this.flushTimer.unref?.()
-  }
 }
 
 // 单例挂 globalThis(与 dcw-recipe.repo 同型):dev HMR 重建模块时保住实例,

package/server/services/workshop/daq/daq-runtime.ts

@@ -72,11 +72,6 @@ export class DaqNodeRuntime {
     this.lastIngestAt = 0
   }
 
-  /** 仅重置下发游标(全局下发间隔变更时,让新缺省立刻可观测) */
-  republish(): void {
-    this.lastPublishAt = 0
-  }
-
   /**
    * 是否已到采样时点(网关调度用)。
    * 网关每拍派发额度有限,先判到期再占用额度:未到期的节点零成本跳过,

package/server/services/workshop/json-store.mjs

@@ -47,16 +47,49 @@ export function loadJsonFile(filePath, fallback) {
   }
 }
 
+/**
+ * 紧凑 vs 缩进的切换阈值(顶层元素数)。
+ *
+ * 为什么需要:`null, 2` 缩进对**小文件**是净收益(人可读、diff 友好、成本可忽略),
+ * 但对**大库**是纯税:实测 DCW 回退账本 20000 锚 + 2000 记录 — 缩进 8.57 MB / 23.2 ms,
+ * 紧凑 5.82 MB / 13.2 ms(体积 -32%、CPU -43%)。而它每个 1.5s 防抖窗就要整库重写一次,
+ * 与 PLC 写 sweep 跑在同一个事件循环上 —— 缩进在这里换来的是几十毫秒的阻塞。
+ *
+ * 所以按规模自动选择:小库保持缩进(可读性),大库走紧凑(性能)。
+ * 2000 是实测拐点量级:低于此的库序列化都在亚毫秒,缩进白拿。
+ */
+const PRETTY_MAX_ENTRIES = 2000
+
+/** 顶层元素数估算(数组取长度;对象取各数组属性长度之和)——用于选择序列化形态 */
+function entryCount(data) {
+  if (Array.isArray(data)) return data.length
+  if (data && typeof data === 'object') {
+    let n = 0
+    for (const v of Object.values(data)) if (Array.isArray(v)) n += v.length
+    return n
+  }
+  return 0
+}
+
+/** 按规模选择缩进(小库可读、大库省 CPU/IO) */
+function serializeJson(data) {
+  return entryCount(data) > PRETTY_MAX_ENTRIES
+    ? JSON.stringify(data)
+    : JSON.stringify(data, null, 2)
+}
+
 /**
  * 原子落盘:写临时文件 → rename 替换;失败退回直写。
+ * 序列化形态按库规模自动选择(见 serializeJson)。
  * @param {string} filePath
  * @param {unknown} data
  */
 export function saveJsonFileAtomic(filePath, data) {
   mkdirSync(dirname(filePath), { recursive: true })
   const tmp = `${filePath}.tmp-${process.pid}`
+  const payload = serializeJson(data)
   try {
-    writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8')
+    writeFileSync(tmp, payload, 'utf-8')
     try {
       renameSync(tmp, filePath)
       return
@@ -68,5 +101,5 @@ export function saveJsonFileAtomic(filePath, data) {
   catch (tmpErr) {
     console.error(`[json-store] 临时文件写入失败(${tmpErr.message}),退回直写`)
   }
-  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8')
+  writeFileSync(filePath, payload, 'utf-8')
 }

package/server/services/workshop/plugins/host.mjs

@@ -8,7 +8,10 @@
 //   client?: './client.mjs', routes?: [{method,path,handler}] }
 // —— ctx 由宿主注入,插件运行时零导入依赖(sdk/ 供类型与显式糖)。
 //
-// 启停状态机:配置根 plugins-state.json { version, updatedAt, disabled: string[] }
+// 启停状态机:<home>/plugins-state.json { version, updatedAt, disabled: string[] }
+//   ⚠️ home = $AW_HOME 或 ~/.AgentWorkShop —— **不是**配置根。源码检出下两者不同:
+//   configRoot=<repo>/.AgentWorkShop(数据/kv 在这里),home=~/.AgentWorkShop(状态在这里)。
+//   全局安装两者重合,所以旧注释写"配置根"时看不出问题。
 //   · 装载时跳过 disabled 插件(manifest 仍可见,enabled:false)
 //   · 状态文件变化(fs.watch)→ 热重载:全部 dispose/解绑 → 重新装载
 //   · CLI(aw plugin enable/disable) 与 Web 设置页均只写状态文件,服务自感知
@@ -159,7 +162,8 @@ async function seedRuntimeServices() {
   servicesExt.register('plugins', async () => pluginManifest())
 }
 
-// ---- 启停状态(单一事实源:<配置根>/plugins-state.json;CLI/Web/宿主三方读写) ----
+// ---- 启停状态(单一事实源:<home>/plugins-state.json;CLI/Web/宿主三方读写) ----
+//  入参 homeDir 由 modePaths().homeDir 给出($AW_HOME 优先),**不是配置根**。
 export function statePathFor(homeDir) {
   return join(homeDir, 'plugins-state.json')
 }
@@ -182,7 +186,10 @@ export function writeDisabledSet(homeDir, disabled) {
   renameSync(tmp, p)
 }
 
-/** 发现插件入口,三作用域(builtin 同名被 project 覆盖,project 同名被 user 覆盖) */
+/** 发现插件入口,三作用域。**同名 builtin 优先**(先扫先占,`seen` 去重),
+ *  即优先级 builtin > project > user —— 与 CLI 指令注册表(cli/core/registry.mjs,
+ *  后扫覆盖 → project > user > builtin)方向相反,勿照搬。
+ *  实现见下方循环顺序 [builtin, project, user] + `if (seen.has(name)) continue`。 */
 export function discoverPluginDirs(cwd = process.cwd()) {
   const { builtinDir, projectDir, userDir } = modePaths(cwd)
   const out = []
@@ -381,9 +388,11 @@ async function loadAllPlugins(host, { config, paths }) {
       for (const e of groupsCheck.errors) host.logger.warn(`[${def.name}] 分组声明已跳过: ${e}`)
 
       const emitter = {
+        /** @returns {boolean} 注册结果(SDK 契约 `ctx.route(...) → boolean`,勿丢返回值) */
         registerRoute: (n, m, p, h) => {
-          host.routes.register(n, m, p, h)
-          rec.routes.push({ method: String(m).toUpperCase(), path: p })
+          const ok = host.routes.register(n, m, p, h)
+          if (ok) rec.routes.push({ method: String(m).toUpperCase(), path: p })
+          return ok
         },
       }
       const perPluginDisposables = []

package/server/services/workshop/runtime/manager.ts

@@ -38,7 +38,7 @@ import { ChannelRuntime } from './channel-runtime'
 import { SchedulerLoop, type SchedulerLoopOptions } from './scheduler-loop'
 import { TaskEngine as TaskEngineImpl } from './task-engine'
 import { AgentMemory, runMemoryMaintenance, segmentCJK, unsegmentCJK, vectorizeMemory, type MaintenanceResult, type MemorySnippet } from './memory'
-import { memorySettings } from '../settings'
+import { memorySettings, workshopSettings } from '../settings'
 import { createEnvEmbeddingProvider } from './embedding-provider'
 import { listHarnessProcesses, listAliveHarnessProcessesByAgent, sweepHarnessProcesses, killHarnessProcess } from '../agents/harness-process'
 import { hasTerminalSession, sweepTerminalSessions } from '../agents/harness-terminal'
@@ -155,6 +155,10 @@ function instanceToAgentInfo(m: ChannelAgentRow): AgentInfo {
     config: parseJson<Record<string, unknown>>(m.configJson, {}),
     token: m.token,
     enabled: m.enabled,
+    /** 来源 Agent 模板 id(手工成员为 null)。
+     *  外部调用方需要它把「模板 → 已部署实例」对上 —— Agent↔节点绑定必须落到实例 id,
+     *  而绑定接口只回一个实例 id;不暴露这个字段时调用方只能靠名字猜(实测踩过)。 */
+    templateId: m.templateId ?? null,
   }
 }
 
@@ -699,6 +703,10 @@ export class AgentChannelManager {
     const lead = this.ensureAgentRuntime(channelId, channel.leadAgentId)
     if (!lead) return
     const loop = new SchedulerLoop(cr, lead, {
+      // 停滞窗口默认取 workshop.stall_ms(默认 5 分钟,可经设置调整):
+      // 它决定"多久算停滞"以及"多久之后收口",是运维最需要按现场调的一个值;
+      // 以前写死在 SchedulerLoop 构造默认值里,mock/规则引擎路径上最长要 10 分钟才可见。
+      ...(Number.isFinite(workshopSettings().stall_ms) ? { stallMs: workshopSettings().stall_ms } : {}),
       ...options,
       // 停滞看门狗活性源:agent 最近一次工具 invoke 时刻(工具调用即健康推进)
       toolActivityOf: (agentId: string) => this.lastToolInvokeAt.get(agentId) ?? null,
@@ -2497,6 +2505,25 @@ export class AgentChannelManager {
     return message
   }
 
+  /**
+   * 按主键查 Channel 成员实例(跨频道)。
+   * 用途:校验「Agent ↔ 工业节点绑定」的主体 —— 运行时持绑定做鉴权的是**成员实例**,
+   * 不是 Agent 模板;绑到模板 id 上会得到一条永远不生效的静默绑定(实测踩过)。
+   */
+  findChannelAgentById(channelAgentId: string): { id: string, channelId: string, templateId: string } | undefined {
+    const row = this.deps.repos.channelAgents.findById(channelAgentId)
+    return row ? { id: row.id, channelId: row.channelId, templateId: row.templateId } : undefined
+  }
+
+  /** 某 Agent 模板已部署到哪些频道(用于把"绑错主体"的报错变成可执行提示) */
+  listChannelAgentInstances(templateId: string): Array<{ id: string, channelId: string, name: string }> {
+    return this.deps.repos.channelAgents.listByTemplate(templateId).map(r => ({
+      id: r.id,
+      channelId: r.channelId,
+      name: this.deps.repos.channels.findById(r.channelId)?.name ?? r.channelId,
+    }))
+  }
+
   /**
    * 实时消息(外部/系统注入):priority=immediate → busy 时 steer 注入运行中的 omp 会话。
    * 触发器 requireReply=true → 接收方须回执(执行结果+所需内容,in_reply_to 关联)。

package/server/services/workshop/runtime/scheduler-loop.ts

@@ -495,7 +495,16 @@ export class SchedulerLoop {
       else {
         this.notified.delete(task.id)
         this.lastProgress.delete(task.id)
-        decisions.push({ kind: 'cancel', taskId: task.id })
+        // 交回裁决:这里**不能无条件 cancel**。
+        // 直接派发给 worker 的任务(无父任务)是由 worker 自己调 complete_task 收口的;
+        // 它的回合结束时若漏了这一步,任务会停在 WORKING,assignee 也不再 busy ——
+        // 旧实现直接 cancel,把**已经产出的交付物一起作废**(实测:omp worker 干到
+        // progress=90、产物齐全,却因没走收口动作被整单取消;换成真实 harness lead 时
+        // 由 lead 的监督回合兜住,所以只在 mock/规则引擎这条路径上暴露)。
+        // 现在按"有没有真干过活"分流:干过 → 收口(成果保留);没干过 → 仍然取消(防永挂)。
+        const didWork = task.progress > 0
+          || (task.artifacts ?? []).some(a => a.name !== 'input' && (a.parts ?? []).length > 0)
+        decisions.push(didWork ? { kind: 'complete', taskId: task.id } : { kind: 'cancel', taskId: task.id })
       }
     }
 

package/server/services/workshop/settings.ts

@@ -107,6 +107,8 @@ export interface DcwSettings {
 export interface WorkshopSettings {
   idle_sweep_ms: number
   idle_grace_ms: number
+  /** 运行中任务的停滞判定窗口(ms):先催办一次,再过同样时长按有无产出收口 */
+  stall_ms: number
 }
 export interface BackupSettings {
   disabled: boolean

package/server/utils/stability-severity.ts

@@ -0,0 +1,66 @@
+/**
+ * 致命异常严重性判定(稳定性护栏的唯一判据来源)。
+ *
+ * 为什么独立成文件:判定逻辑必须可被 **纯 node 回归测试** 直接加载断言。
+ * 放在 `server/plugins/dev-stability-guard.ts` 里就只能靠起真实服务观察,
+ * 而"哪类异常该退进程"恰恰是最不该靠观察来确认的一类逻辑。
+ *
+ * 四级严重性,只有 `fatal` 会退进程:
+ *
+ *  1. `socket`   —— 浏览器/客户端硬断(WS、keep-alive)。最高频的瞬态噪声,
+ *                   Node 默认策略会直接击穿进程,从而拖垮所有并发会话。
+ *  2. `db-busy`  —— SQLite 忙/锁。多写竞争的瞬态错误,应重试而非退出。
+ *  3. `upstream` —— **外部设备/上游服务不可达**:ECONNREFUSED / ENOTFOUND /
+ *                   EHOSTUNREACH / ENETUNREACH / 连接超时。
+ *                   这是运维常态(设备下电、模拟器未启、容器重启),
+ *                   绝不能让"某一台设备没开"带走整个监控平台 ——
+ *                   DAQ 驱动本身把这类失败记为节点 lastError 并继续轮询,
+ *                   护栏再补一刀 exit 1 就构成可用性事故。
+ *                   ⚠️ 与"连上了但业务失败"区分:后者不在此列,仍走 fatal。
+ *  4. `engine`   —— Agent 引擎边界错误(opencode/omp/codex/dsh 的 RPC 失败)。
+ *                   只影响对应 agent 会话,服务端同时承载数采/数控,不可退进程。
+ *
+ * 其余一律 `fatal`:安全插件的 fail-fast(如生产密钥校验失败拒绝启动)依赖异常
+ * 中止进程,绝不能被护栏吞掉。
+ */
+
+/** socket 级断连噪声 */
+export const SOCKET_NOISE = /ECONNRESET|EPIPE|ECONNABORTED|ETIMEDOUT|ERR_STREAM_PREMATURE_CLOSE|ERR_STREAM_WRITE_AFTER_END/
+
+/** 外部设备/上游不可达(运维常态,非程序缺陷) */
+export const UPSTREAM_UNREACHABLE = /ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|ERR_SOCKET_CONNECTION_TIMEOUT|UND_ERR_CONNECT_TIMEOUT/
+
+/** SQLite 忙/锁(hardening ST-1) */
+export const SQLITE_BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i
+
+/** Agent 引擎边界错误(harness 容错) */
+export const ENGINE_BOUNDARY = /\b(opencode|omp|codex|dsh) API\b/i
+
+export type FatalSeverity = 'socket' | 'db-busy' | 'upstream' | 'engine' | 'fatal'
+
+/** 错误→可读文本;Error 取 message + 截断 stack,其余 String() */
+export function describeReason(reason: unknown): string {
+  return reason instanceof Error
+    ? `${reason.message}\n${reason.stack?.slice(0, 600) ?? ''}`
+    : String(reason)
+}
+
+/**
+ * 判定一次"致命候选"的真实严重性。
+ * 命中顺序即优先级:code 字段优先(经典 errno),再全文兜底
+ * (undici 等包装错误 code 可能是 UND_ERR_*,但 message/stack 仍带原文)。
+ */
+export function classifyFatalCandidate(reason: unknown): FatalSeverity {
+  if (reason == null) return 'fatal'
+  const err = reason as NodeJS.ErrnoException
+  const code = typeof err.code === 'string' ? err.code : ''
+  const text = `${code}\n${describeReason(reason)}`
+
+  if (SOCKET_NOISE.test(text)) return 'socket'
+  if (SQLITE_BUSY.test(text)) return 'db-busy'
+  if (UPSTREAM_UNREACHABLE.test(text)) return 'upstream'
+  // 引擎边界只看首行:避免 stack 里偶然出现的引擎名把真实错误降级
+  const head = describeReason(reason).split('\n')[0] ?? ''
+  if (ENGINE_BOUNDARY.test(head)) return 'engine'
+  return 'fatal'
+}