agentworkshop 0.7.39 → 0.7.40

package/server/services/workshop/dcw/param-limits.ts

@@ -0,0 +1,142 @@
+/**
+ * ParamLimits —— 工艺参数写入限界的分层解析与联锁断言(策略层)。
+ *
+ * 分层限界(层层收窄,任一层越界即拒;有效限界 = 各生效层交集):
+ *   1. node    节点工艺安全量程(结构性硬边界,驱动层 validateEng 结构性兜底,不可旁路)
+ *   2. param   工艺参数基准限界(常驻边界,配置在参数映射上)
+ *   3. product 产品限界(该产线活动批次产品的 paramLimits[paramKey];换产品即换边界)
+ *   4. recipe  配方窗口(活动批次配方对该执行节点的 param.min/max;开跑期间生效)
+ *
+ * 四路写路径(手动 REST / Agent 工具 / 配方下发 / 回退)共用 DcwController.write
+ * 咽喉点 → 断言在咽喉点单点生效,用户与 Agent 一体约束,不存在旁路来源。
+ * D8 基准消融:includeSoft=false 时仅保留 node 结构层(软联锁消融臂语义)。
+ */
+
+import { AppError, ErrorCodes } from '../../../utils/errors'
+import type { ParamLimitLayer, ParamLimitsBreakdown } from '../../../../shared/dcw-protocol'
+import type { DcwNode } from './dcw-node'
+import { getDcwParamRepo } from './param-map.repo'
+import { getDcwProductRepo } from './dcw-product.repo'
+import { getDcwRecipeRepo } from './dcw-recipe.repo'
+import { getActiveLineRun } from './line-run'
+
+export interface LimitResolveOpts {
+  /** false = 仅结构层(消融臂/展示结构层);缺省 true = 全层 */
+  includeSoft?: boolean
+  /** 跳过配方窗口层(配方下发路径传 true:下发值已在配方保存时对自身窗口校验,
+   *  且中途应用新配方不应被旧批次配方窗口误伤;手动/Agent 写恒受活动配方窗口约束) */
+  skipRecipe?: boolean
+}
+
+/** 解析某执行节点当前生效的限界层(node 层恒在;软层按配置/运行态可有可无) */
+export function limitLayersOf(node: DcwNode, opts: LimitResolveOpts = {}): ParamLimitLayer[] {
+  const includeSoft = opts.includeSoft !== false
+  const layers: ParamLimitLayer[] = [{
+    layer: 'node',
+    label: '节点安全量程',
+    min: node.min,
+    max: node.max,
+  }]
+  if (!includeSoft) return layers
+
+  const paramRepo = getDcwParamRepo()
+  const param = paramRepo.byNode(node.id)
+  const paramKey = param?.key ?? null
+  if (param && (param.min != null || param.max != null)) {
+    layers.push({
+      layer: 'param',
+      label: `工艺参数「${param.key}」基准限界`,
+      min: param.min,
+      max: param.max,
+    })
+  }
+
+  const run = getActiveLineRun(node.lineId)
+  if (!run) return layers
+
+  if (paramKey) {
+    const product = getDcwProductRepo().byId(run.productId)
+    const range = product?.paramLimits?.[paramKey]
+    if (product && range && (range.min != null || range.max != null)) {
+      layers.push({
+        layer: 'product',
+        label: `产品「${product.name}」限界`,
+        min: range.min ?? null,
+        max: range.max ?? null,
+      })
+    }
+  }
+
+  const recipe = getDcwRecipeRepo().byId(run.recipeId)
+  const recipeParam = recipe?.params.find(p => p.nodeId === node.id)
+  if (!opts.skipRecipe && recipe && recipeParam && (recipeParam.min != null || recipeParam.max != null)) {
+    layers.push({
+      layer: 'recipe',
+      label: `配方「${recipe.name}」工艺窗口`,
+      min: recipeParam.min ?? null,
+      max: recipeParam.max ?? null,
+    })
+  }
+  return layers
+}
+
+/** 各层交集(最紧有效限界;node 层恒在,恒有值) */
+export function intersectLayers(layers: ParamLimitLayer[]): { min: number, max: number } {
+  let min = Number.NEGATIVE_INFINITY
+  let max = Number.POSITIVE_INFINITY
+  for (const l of layers) {
+    if (l.min != null && l.min > min) min = l.min
+    if (l.max != null && l.max < max) max = l.max
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    // 结构层缺失属编程错误(节点构造恒有量程);兜底全开域避免误杀写路径
+    return { min: Number.isFinite(min) ? min : -Number.MAX_VALUE, max: Number.isFinite(max) ? max : Number.MAX_VALUE }
+  }
+  return { min, max }
+}
+
+/** 有效限界全量剖面(参数台账/前端展示/Agent 语义回包共用) */
+export function limitsBreakdownOf(node: DcwNode, opts: LimitResolveOpts = {}): ParamLimitsBreakdown {
+  const param = getDcwParamRepo().byNode(node.id)
+  const layers = limitLayersOf(node, opts)
+  return {
+    nodeId: node.id,
+    paramId: param?.id ?? null,
+    paramKey: param?.key ?? null,
+    layers,
+    effective: intersectLayers(layers),
+  }
+}
+
+/**
+ * 写入联锁断言:逐层校验,越界即 400,错误消息点名层来源与可用区间。
+ * 在 DcwController.write 咽喉点调用 —— 手动/Agent/配方/回退四路一体约束。
+ */
+export function assertWithinLimits(node: DcwNode, eng: number, opts: LimitResolveOpts = {}): void {
+  if (!Number.isFinite(eng)) {
+    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `设定值需为数字(当前: ${String(eng)})`)
+  }
+  const layers = limitLayersOf(node, opts)
+  const paramKey = getDcwParamRepo().byNode(node.id)?.key ?? null
+  const unit = node.unit ?? ''
+  const { min, max } = intersectLayers(layers)
+  for (const l of layers) {
+    if (l.min == null && l.max == null) continue
+    if (l.min != null && eng < l.min) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `${violatedText(l, '低于下限', eng, unit, paramKey)}(当前有效写入区间 ${min}~${max}${unit};各层限界按安全规约取交集,越界写入已拒绝)`)
+    }
+    if (l.max != null && eng > l.max) {
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `${violatedText(l, '超出上限', eng, unit, paramKey)}(当前有效写入区间 ${min}~${max}${unit};各层限界按安全规约取交集,越界写入已拒绝)`)
+    }
+  }
+}
+
+function violatedText(l: ParamLimitLayer, dir: string, eng: number, unit: string, paramKey: string | null): string {
+  const bound = dir === '低于下限' ? l.min : l.max
+  const subject = l.layer === 'node'
+    ? '节点工艺安全量程'
+    : l.layer === 'param'
+      ? `工艺参数「${paramKey ?? ''}」基准限界`
+      : l.label + (paramKey ? `(工艺参数 ${paramKey})` : '')
+  return `设定值 ${eng}${unit} ${dir} ${subject} 的 ${bound}${unit} —— 约束层:${l.label}`
+}

package/server/services/workshop/dcw/param-map.repo.ts

@@ -0,0 +1,305 @@
+/**
+ * DcwParamRepo —— 工艺参数映射仓库(data/dcw-params.json)。
+ *
+ * 工艺参数映射 = 「工艺参数(语义面) → 写控制执行节点(PLC 面)」的显式绑定:
+ * 用户/Agent 只面向参数(key/单位/工程量)读写,寄存器/数据类型/字节序等 PLC
+ * 细节全部封装在执行节点驱动配置内(单一事实源,参数面不透出)。
+ *
+ * 生命周期:节点创建即自动生成同名映射(开箱即得的参数面,ensureForNode);
+ * 节点删除级联清理映射(removeForNode);映射删除不影响节点执行能力。
+ * lineId 不落盘 —— 派生自执行节点(节点换线参数自动跟随,单一事实源)。
+ */
+
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import type { DcwNodeView, DcwParamInput, DcwParamView } from '../../../../shared/dcw-protocol'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import { AppError, ErrorCodes } from '../../../utils/errors'
+import { createLogger } from '../logger'
+import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
+import { getDcwNodeRepo } from './dcw-node.repo'
+import type { DcwNode } from './dcw-node'
+
+const log = createLogger('dcw.param-repo')
+
+// 配置根 .AgentWorkShop/data（ensureDataDir 自动迁移旧 cwd/server/data 位置）
+const DB_PATH = join(ensureDataDir(), 'dcw-params.json')
+
+interface DcwParamRow {
+  id: string
+  /** 参数键(执行节点所属产线内唯一) */
+  key: string
+  name: string
+  templateRef: string
+  unit: string
+  decimals: number
+  /** 基准写入限界(null = 该侧不约束) */
+  min: number | null
+  max: number | null
+  /** 映射目标:写控制执行节点 */
+  nodeId: string
+  /** 标准转换模式摘要(配置期选定;运行期换算以执行节点驱动配置为单一事实源) */
+  conversion?: DcwParamView['conversion']
+  createdAt: string
+}
+
+function load(): DcwParamRow[] {
+  try {
+    const parsed = loadJsonFile(DB_PATH, null)
+    return Array.isArray(parsed) ? parsed as DcwParamRow[] : []
+  }
+  catch {
+    return []
+  }
+}
+
+/** 参数键规范化:去空白;空串拒绝 */
+const normKey = (key: unknown): string => String(key ?? '').trim()
+
+class DcwParamRepo {
+  private list: DcwParamRow[] = load()
+
+  all(): DcwParamRow[] {
+    return this.list
+  }
+
+  byId(id: string): DcwParamRow | undefined {
+    return this.list.find(p => p.id === id)
+  }
+
+  byNode(nodeId: string): DcwParamRow | undefined {
+    return this.list.find(p => p.nodeId === nodeId)
+  }
+
+  /** 按 key 检索(可能跨产线同名;返回全部命中) */
+  byKey(key: string): DcwParamRow[] {
+    const k = normKey(key)
+    return this.list.filter(p => p.key === k)
+  }
+
+  /** key 在某产线内是否已被占用(经执行节点的产线归属判定) */
+  keyTakenOnLine(key: string, lineId: string, excludeId?: string): boolean {
+    const k = normKey(key)
+    const nodeRepo = getDcwNodeRepo()
+    return this.list.some((p) => {
+      if (p.id === excludeId || p.key !== k) return false
+      return (nodeRepo.byId(p.nodeId)?.lineId ?? '') === lineId
+    })
+  }
+
+  /** 产线内唯一化 key:base / base-2 / base-3 … */
+  uniqueKeyOnLine(base: string, lineId: string): string {
+    const root = normKey(base) || 'param'
+    if (!this.keyTakenOnLine(root, lineId)) return root
+    for (let i = 2; ; i++) {
+      const candidate = `${root}-${i}`
+      if (!this.keyTakenOnLine(candidate, lineId)) return candidate
+    }
+  }
+
+  /**
+   * 创建映射。校验:执行节点存在;templateRef 可解析(缺省继承节点);
+   * key 产线内唯一(缺省继承模板 key,冲突自动加后缀);min<=max。
+   */
+  create(input: DcwParamInput): DcwParamRow {
+    const nodeRepo = getDcwNodeRepo()
+    const nodeId = String(input.nodeId ?? '').trim()
+    if (!nodeId) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'nodeId 必填:工艺参数映射必须指向一个写控制执行节点')
+    const node = nodeRepo.byId(nodeId)
+    if (!node) throw new AppError(404, ErrorCodes.NOT_FOUND, `执行节点不存在: ${nodeId}`)
+    const templateRef = String(input.templateRef ?? node.templateRef ?? '').trim()
+    if (!templateRef) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'templateRef 必填:工艺参数需绑定语义模板')
+    const lineId = node.lineId
+    const key = input.key == null
+      ? this.uniqueKeyOnLine(node.templateKey, lineId)
+      : (() => {
+          const k = normKey(input.key)
+          if (!k) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, '参数键 key 不可为空')
+          if (this.keyTakenOnLine(k, lineId)) throw new AppError(409, ErrorCodes.CONFLICT, `参数键「${k}」在本产线已被占用(产线内唯一)`)
+          return k
+        })()
+    const { min, max } = normRange(input.min, input.max, key)
+    const row: DcwParamRow = {
+      id: `pp-${randomUUID().slice(0, 8)}`,
+      key,
+      name: String(input.name ?? node.name ?? key).trim() || key,
+      templateRef,
+      unit: String(input.unit ?? node.unit ?? '').trim(),
+      decimals: clampDecimals(input.decimals ?? node.decimals),
+      min,
+      max,
+      nodeId,
+      createdAt: new Date().toISOString(),
+    }
+    if (input.conversion) row.conversion = input.conversion
+    this.list.push(row)
+    this.flush()
+    return row
+  }
+
+  update(id: string, patch: DcwParamInput): DcwParamRow {
+    const row = this.byId(id)
+    if (!row) throw new AppError(404, ErrorCodes.NOT_FOUND, `工艺参数映射不存在: ${id}`)
+    const node = getDcwNodeRepo().byId(row.nodeId)
+    const lineId = node?.lineId ?? ''
+    if (patch.key !== undefined) {
+      const k = normKey(patch.key)
+      if (!k) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, '参数键 key 不可为空')
+      if (this.keyTakenOnLine(k, lineId, row.id)) throw new AppError(409, ErrorCodes.CONFLICT, `参数键「${k}」在本产线已被占用(产线内唯一)`)
+      row.key = k
+    }
+    if (patch.name !== undefined) row.name = String(patch.name).trim() || row.key
+    if (patch.templateRef !== undefined) {
+      const t = String(patch.templateRef).trim()
+      if (!t) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, 'templateRef 不可为空')
+      row.templateRef = t
+    }
+    if (patch.unit !== undefined) row.unit = String(patch.unit).trim()
+    if (patch.decimals !== undefined) row.decimals = clampDecimals(patch.decimals)
+    if (patch.min !== undefined || patch.max !== undefined) {
+      const { min, max } = normRange(
+        patch.min === undefined ? row.min : patch.min,
+        patch.max === undefined ? row.max : patch.max,
+        row.key,
+      )
+      row.min = min
+      row.max = max
+    }
+    if (patch.conversion !== undefined) {
+      if (patch.conversion == null) delete row.conversion
+      else row.conversion = patch.conversion
+    }
+    // nodeId 映射目标不可变:换绑请删建(避免账本/限界层悬空引用)
+    this.flush()
+    return row
+  }
+
+  remove(id: string): boolean {
+    const before = this.list.length
+    this.list = this.list.filter(p => p.id !== id)
+    if (this.list.length !== before) {
+      this.flush()
+      return true
+    }
+    return false
+  }
+
+  removeForNode(nodeId: string): boolean {
+    const before = this.list.length
+    this.list = this.list.filter(p => p.nodeId !== nodeId)
+    if (this.list.length !== before) {
+      this.flush()
+      return true
+    }
+    return false
+  }
+
+  /**
+   * 节点创建即自动生成参数映射(开箱即得的参数面)。防御性:任何失败只记日志
+   * 不阻断节点创建(节点是执行主体,映射面可事后手工补建)。
+   */
+  ensureForNode(node: DcwNode): DcwParamRow | undefined {
+    try {
+      const existing = this.byNode(node.id)
+      if (existing) return existing
+      const row: DcwParamRow = {
+        id: `pp-${randomUUID().slice(0, 8)}`,
+        key: this.uniqueKeyOnLine(node.templateKey, node.lineId),
+        name: node.name,
+        templateRef: node.templateRef,
+        unit: node.unit,
+        decimals: node.decimals,
+        min: null,
+        max: null,
+        nodeId: node.id,
+        createdAt: new Date().toISOString(),
+      }
+      this.list.push(row)
+      this.flush()
+      return row
+    }
+    catch (err) {
+      log.error('[dcw-param] 节点参数面自动生成失败(不影响节点):', err)
+      return undefined
+    }
+  }
+
+  /** 视图投影(联接执行节点;节点已删除的悬空行过滤返回 null) */
+  viewOf(row: DcwParamRow): DcwParamView | null {
+    const node = getDcwNodeRepo().byId(row.nodeId)
+    if (!node) return null
+    return this.project(row, node.toView())
+  }
+
+  listViews(): DcwParamView[] {
+    const nodeRepo = getDcwNodeRepo()
+    const views = new Map(nodeRepo.all().map(n => [n.id, n.toView()]))
+    return this.list
+      .map(p => views.get(p.nodeId) ? this.project(p, views.get(p.nodeId)!) : null)
+      .filter((v): v is DcwParamView => v != null)
+  }
+
+  private project(row: DcwParamRow, node: DcwNodeView): DcwParamView {
+    return {
+      id: row.id,
+      key: row.key,
+      name: row.name,
+      templateRef: row.templateRef,
+      unit: row.unit || node.unit,
+      decimals: row.decimals,
+      min: row.min,
+      max: row.max,
+      nodeId: row.nodeId,
+      lineId: node.lineId,
+      driver: node.driver,
+      enabled: node.enabled,
+      value: node.value,
+      readValue: node.readValue,
+      state: node.state,
+      conversion: row.conversion,
+      createdAt: row.createdAt,
+    }
+  }
+
+  private flush(): void {
+    try {
+      saveJsonFileAtomic(DB_PATH, this.list)
+    }
+    catch (err) {
+      log.error('[dcw-param] 落盘失败:', err)
+    }
+  }
+}
+
+/** 限界规范化:有限数字或 null;min<=max */
+function normRange(min: unknown, max: unknown, label: string): { min: number | null, max: number | null } {
+  const nOf = (v: unknown): number | null => {
+    if (v == null || v === '') return null
+    const n = Number(v)
+    if (!Number.isFinite(n)) throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `工艺参数「${label}」限界需为数字或空(当前: ${String(v)})`)
+    return n
+  }
+  const lo = nOf(min)
+  const hi = nOf(max)
+  if (lo != null && hi != null && lo > hi) {
+    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `工艺参数「${label}」限界非法:min ${lo} > max ${hi}`)
+  }
+  return { min: lo, max: hi }
+}
+
+function clampDecimals(v: unknown): number {
+  const d = Number(v)
+  if (!Number.isInteger(d) || d < 0 || d > 6) {
+    throw new AppError(400, ErrorCodes.VALIDATION_ERROR, `decimals 必须为 0..6 的整数(当前: ${String(v)})`)
+  }
+  return d
+}
+
+const g = globalThis as typeof globalThis & { __dcwParamRepo?: DcwParamRepo }
+
+export function getDcwParamRepo(): DcwParamRepo {
+  g.__dcwParamRepo ??= new DcwParamRepo()
+  return g.__dcwParamRepo
+}
+
+export type { DcwParamRow }

package/server/services/workshop/dcw/recipe-rollback-manager.ts

@@ -108,7 +108,9 @@ export class RecipeRollBackManager {
    * 返回 anchorId/recordId 供工具回包;内部异常不外抛(记账失败不影响写结果)。
    */
   afterWrite(
-    node: { id: string, name: string, lineId: string, templateRef: string },
+    // unit 参与入册摘要(下方 `node.unit ?? ''`);调用方传的是 DcwNode 实例(unit: string),
+    // 原先这里漏声明该字段,导致实现读到了参数类型之外的属性
+    node: { id: string, name: string, lineId: string, templateRef: string, unit?: string | null },
     eng: number,
     prevValue: number | null,
     meta: DcwWriteMeta & { rollbackOf?: string },
@@ -535,12 +537,16 @@ export class RecipeRollBackManager {
         values.push(v)
       }
       const win = recipe?.daqWindows?.find(w => w.nodeId === ch.daqNodeId)
-      let breaches = win && (win.min != null || win.max != null) ? 0 : -1
-      for (const v of values) {
-        if (breaches === -1)
-          break
-        if ((win.min != null && v < win.min) || (win.max != null && v > win.max))
-          breaches++
+      // 「有窗口且设了边界」才计越界:原实现用 breaches=-1 + 循环首拍 break 短路,
+      // 等价于整段跳过(循环体在 -1 时没有任何副作用)。把这条不变量显式上移,
+      // win 在循环内即可被收窄(不再需要断言/非空断言)。
+      const windowed = win != null && (win.min != null || win.max != null)
+      let breaches = windowed ? 0 : -1
+      if (win && windowed) {
+        for (const v of values) {
+          if ((win.min != null && v < win.min) || (win.max != null && v > win.max))
+            breaches++
+        }
       }
       ch.latest = values.length ? values[values.length - 1]! : null
       ch.avg = values.length ? Number((values.reduce((a, b) => a + b, 0) / values.length).toFixed(2)) : null

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

@@ -137,6 +137,10 @@ export interface TaskEngine {
   queueViewOf(channelId: string, agentId: string): AgentTaskQueueView
   /** 批量队列视图(一次查询聚合全 channel;调度快照热路径) */
   queueViewsOf(channelId: string): Map<string, AgentTaskQueueView>
+  /** 批量队列视图 lite 版(元数据投影,免 artifacts/history 大列解析;调度快照热路径) */
+  queueViewsOfLite(channelId: string): Map<string, AgentTaskQueueView>
+  /** 任务列表 lite 版(元数据投影;调度决策/规则引擎仅消费 id/state/parent/进度/标题) */
+  listLite(channelId: string): WorkspaceTask[]
 }
 
 /**

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

@@ -332,7 +332,12 @@ export class AgentChannelManager {
   /** agent 最近一次工具 invoke 时刻(调度器停滞看门狗的活性源;工具调用即健康推进) */
   private readonly lastToolInvokeAt = new Map<string, number>()
 
-  constructor(private deps: ManagerDeps) {
+  /** 依赖集(repos/implFactory/db)。
+   *  API 作业面(ws/agent-tools/a2a card/…)需要直接读 repo —— 原先只能靠
+   *  `(manager as unknown as { deps })` 断言绕过 private。这里改成 public readonly:
+   *  TS 的 private 是纯类型层(擦除后运行时无差异),readonly 保证不可重绑定,
+   *  既去掉断言又保持封装语义(依赖注入本身就是本类的构造契约)。 */
+  constructor(readonly deps: ManagerDeps) {
     // 记忆衰减清理定时器(失败只记日志,绝不抛出;unref 不阻进程退出;非法/非正 env 回退默认)
     this.memoryTimer = setInterval(() => {
       try {
@@ -2510,7 +2515,7 @@ export class AgentChannelManager {
    * 用途:校验「Agent ↔ 工业节点绑定」的主体 —— 运行时持绑定做鉴权的是**成员实例**,
    * 不是 Agent 模板;绑到模板 id 上会得到一条永远不生效的静默绑定(实测踩过)。
    */
-  findChannelAgentById(channelAgentId: string): { id: string, channelId: string, templateId: string } | undefined {
+  findChannelAgentById(channelAgentId: string): { id: string, channelId: string, templateId: string | null } | undefined {
     const row = this.deps.repos.channelAgents.findById(channelAgentId)
     return row ? { id: row.id, channelId: row.channelId, templateId: row.templateId } : undefined
   }
@@ -2640,6 +2645,8 @@ export class AgentChannelManager {
     name: string
     description: string
     leadName: string | null
+    /** 团队共享域知识量(实现体第 2661 行已产出;原声明漏写 → 与 AgentWorkspace.listOtherTeams 漂移) */
+    sharedMemories: number
     activeTasks: Array<{ id: string, title: string, state: string }>
     recentCompleted: Array<{ title: string }>
   }> {

package/server/services/workshop/settings.ts

@@ -54,8 +54,10 @@ export function settingOf(key: string): unknown {
   return effective()[key]
 }
 
-/** 聚合组(前缀匹配;dotted 键 → 平铺键名,如 memory.primer_tokens → { primer_tokens }) */
-function section<G extends string>(group: string): G {
+/** 聚合组(前缀匹配;dotted 键 → 平铺键名,如 memory.primer_tokens → { primer_tokens })
+ *  G 是调用方声明的**设置组对象类型**(如 MemorySettings):本函数只负责按前缀聚合,
+ *  不校验形状,故约束为 object 而非 string —— 原约束 'string' 与全部调用点都不相容。 */
+function section<G extends object>(group: string): G {
   const out: Record<string, unknown> = {}
   const prefix = `${group}.`
   for (const [k, v] of Object.entries(effective())) {

package/server/types/pg.d.ts

@@ -0,0 +1,49 @@
+/**
+ * pg 的最小环境声明(补第三方**缺失的类型**,不是屏蔽错误)。
+ *
+ * 依据(实测 node_modules/pg@8.23.0):
+ *  - package.json 无 "types"/"typings" 字段,files 只有 lib / esm/SPONSORS.md —— 包内**零 .d.ts**;
+ *    仓库也未安装 @types/pg(实测 node_modules/@types 只有 js-yaml / node / three),
+ *    所以 `import type { Pool } from 'pg'` 必然 TS7016(隐式 any)。
+ *  - exports["."].import → ./esm/index.mjs(TS7016 报的就是该文件);运行时导出面见 lib/index.js
+ *    (Pool / Client / types 等),本文件只声明代码真正用到的成员。
+ *  - 行值形状由 SQL 与 pg 的 type parser 在运行时决定(timestamptz → Date、float8 → number、
+ *    count(*) → string),查询期无法静态得知 —— 与官方 @types/pg 一致,用索引签名表达"逐查询动态";
+ *    需要窄化的查询点在调用侧显式断言(见 timescale.adapter.ts queryTagged 的 rows as Array<{...}>)。
+ *
+ * 覆盖范围:server/services/workshop/daq/storage/timescale.adapter.ts 的用法
+ * (Pool 构造 / query(sql[, values]) / connect()→query+release / end())。新增用法时按需扩展。
+ */
+declare module 'pg' {
+  /** 行对象形状逐查询动态(官方 @types/pg 同样用索引签名表达) */
+  export interface QueryResultRow {
+    [column: string]: any
+  }
+
+  export interface QueryResult<R extends QueryResultRow = QueryResultRow> {
+    rows: R[]
+    rowCount: number | null
+    command: string
+  }
+
+  export interface PoolConfig {
+    connectionString?: string
+    max?: number
+    min?: number
+    idleTimeoutMillis?: number
+    connectionTimeoutMillis?: number
+  }
+
+  /** 池借出的连接:复合语句事务(BEGIN/COMMIT/ROLLBACK)与参数化查询 */
+  export interface PoolClient {
+    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>
+    release(err?: Error | boolean): void
+  }
+
+  export class Pool {
+    constructor(config?: PoolConfig)
+    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>
+    connect(): Promise<PoolClient>
+    end(): Promise<void>
+  }
+}

package/server/utils/stability-severity.ts

@@ -28,7 +28,18 @@
 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/
+export const UPSTREAM_UNREACHABLE = /ECONNREFUSED|ENOTFOUND|EHOSTUNREACH|ENETUNREACH|ERR_SOCKET_CONNECTION_TIMEOUT|UND_ERR_CONNECT_TIMEOUT/i
+
+/**
+ * 人类可读的"设备不可达"文本兜底。
+ *
+ * 修复动因(实测事故):部分工业驱动库(Modbus/OPC UA 客户端)在链路超时时
+ * **不抛 errno code**,只给可读 message("TCP Connection Timed Out")。
+ * 旧实现只认 errno token / ERR_SOCKET_CONNECTION_TIMEOUT,该 message 一路落到
+ * `fatal` → 整个生产实例 exit 1(实测 13 分钟内即发生一次),与守卫自述的
+ * "设备下电/模拟器未启不该带走平台"直接矛盾。
+ */
+export const UPSTREAM_UNREACHABLE_TEXT = /TCP Connection Timed Out|connection timed out|connect(?:ion)? timeout|socket hang ?up/i
 
 /** SQLite 忙/锁(hardening ST-1) */
 export const SQLITE_BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i
@@ -58,7 +69,7 @@ export function classifyFatalCandidate(reason: unknown): FatalSeverity {
 
   if (SOCKET_NOISE.test(text)) return 'socket'
   if (SQLITE_BUSY.test(text)) return 'db-busy'
-  if (UPSTREAM_UNREACHABLE.test(text)) return 'upstream'
+  if (UPSTREAM_UNREACHABLE.test(text) || UPSTREAM_UNREACHABLE_TEXT.test(text)) return 'upstream'
   // 引擎边界只看首行:避免 stack 里偶然出现的引擎名把真实错误降级
   const head = describeReason(reason).split('\n')[0] ?? ''
   if (ENGINE_BOUNDARY.test(head)) return 'engine'

package/shared/config/groups.mjs

@@ -47,12 +47,31 @@ export function defaultPluginGroupId(pluginName) {
 
 const ID_RE = /^[A-Za-z0-9_-]{1,48}$/
 
+/**
+ * 配置分组(与 server/services/system-config.ts 的 ConfigGroup 同形的数据形状)。
+ * order 可为空:持久化条目/插件声明未写 order 时由 mergeGroups 沿用内置声明顺序兜底,
+ * 故这里如实声明为可选(消费侧一律按「可能没有 order」处理)。
+ * @typedef {object} ConfigGroupDef
+ * @property {string} id
+ * @property {string} label
+ * @property {string} [labelKey]
+ * @property {string} description
+ * @property {number} [order]
+ * @property {boolean} collapsed
+ * @property {boolean} collapsible
+ * @property {string} icon
+ * @property {'builtin' | 'user' | 'plugin'} source
+ * @property {string} [plugin] source=plugin 时的插件名
+ */
+
 /**
  * 规范化分组定义。
  * order 只在「显式给出」或调用方提供 fallbackOrder(新建分组时)才落值 ——
  * 从磁盘读回的旧条目若没写 order,交给 mergeGroups 沿用内置声明顺序,
  * 否则会平白跳到列表末尾。
- * @returns {{ ok: true, group: object } | { ok: false, error: string }}
+ * @param {object} def 待规范化的分组定义(id/label/description/order/collapsed/collapsible/icon/labelKey)
+ * @param {{ source?: 'builtin' | 'user' | 'plugin', plugin?: string | null, fallbackOrder?: number }} [opts]
+ * @returns {{ ok: true, group: ConfigGroupDef } | { ok: false, error: string }}
  */
 export function normalizeGroup(def, { source = 'user', plugin = null, fallbackOrder } = {}) {
   const d = def ?? {}
@@ -101,6 +120,7 @@ export function saveGroups(groups, groupsPath) {
   return payload
 }
 
+/** @returns {ConfigGroupDef[]} 规范化后的持久化分组(非法条目直接丢弃) */
 export function readGroups(groupsPath) {
   if (!existsSync(groupsPath)) return []
   const out = []
@@ -141,6 +161,7 @@ export function builtinGroupOrder(descriptors = []) {
  * @param {Array} o.persisted        持久化分组(含管理员定制)
  * @param {Array} o.pluginGroups     本轮插件声明的分组
  * @param {Map<string,string>} [o.pluginLabelById] 插件名 → 展示名(用于自动生成组标题)
+ * @returns {ConfigGroupDef[]} 有序分组(已按 order、id 排序)
  */
 export function mergeGroups({ descriptors = [], persisted = [], pluginGroups = [], pluginLabelById = new Map() } = {}) {
   const out = new Map()