agentworkshop 0.8.2 → 0.8.4

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

@@ -1,1155 +1,1155 @@
-/**
- * MES 取数控制器(Agent 工具后端)—— mes-rest 点位目录 + 历史取数编排。
- *
- * 护栏全部**代码级**(不是提示词):绑线授权过滤、时间窗 ≤7 天、maxRows ≤5000、
- * 每 agent 每 60s ≤6 次 fetch;数据原文不进 prompt —— 文本只给 stats + ≤3 行采样,
- * 行级原文只落 CSV 数据集(mes-datasets)。
- *
- * 取数三模式:
- *   无 from/to                     → 当前值快照(driver.read 内联直读);
- *   from/to 且 maxRows ≤ 2000      → 同步 fetchHistory 内联返回(缓冲截断保护);
- *   其余(maxRows > 2000)         → createFetchJob 异步落 CSV,回 job_id/dataset_id。
- */
-import { randomUUID } from 'node:crypto'
-import { closeSync, mkdirSync, openSync, readFileSync, writeFileSync, writeSync } from 'node:fs'
-import { join, resolve, sep } from 'node:path'
-import { ensureDataDir } from '@/shared/config/home.mjs'
-import { getActiveLineRun } from '../dcw/line-run'
-import { resolveDcwDriver } from '../dcw/drivers'
-import type { DcwFieldDef, DcwHistoryFormat as MesHistoryFormat } from '../dcw/drivers/shared'
-import { historyFormatOf, normalizeMesDictionary } from '../dcw/drivers/mes-rest'
-import type { MesHistoryDriver, MesDatasetStatsView, MesDatasetStore } from './mes-datasets'
-import { getMesDatasets } from './mes-datasets'
-import { mesDataHookCode, mesRequestHookCode, runMesDataHook, runMesRequestHook, saveMesImageArtifact } from './mes-hook'
-import type { MesHookArtifact, MesHookData } from './mes-hook'
-
-/** mes-rest 驱动 kind(并行工作流收编进 DcwDriverKind 联合;此处按字符串经注册表解析,不 import 驱动实现) */
-export const MES_REST_DRIVER_KIND = 'mes-rest'
-
-// ============================================================
-// 护栏常量(单一事实源;测试直接引用)
-// ============================================================
-
-/** 历史窗口上限:7 天 */
-export const MES_WINDOW_MAX_MS = 7 * 24 * 3_600_000
-/** 单次取数行数硬上限 */
-export const MES_MAX_ROWS_CAP = 5000
-/** 同步内联返回的行数上限(超过走异步数据集) */
-export const MES_SYNC_INLINE_MAX_ROWS = 2000
-/** 频次限流:窗口与次数(每 agent) */
-export const MES_RATE_WINDOW_MS = 60_000
-export const MES_RATE_MAX_CALLS = 6
-/** max_rows 缺省值 */
-export const MES_DEFAULT_MAX_ROWS = 500
-/** 离线导出单次行数上限(CSV/JSONL 流式写盘;比在线取数宽,仍防磁盘失控) */
-export const MES_EXPORT_MAX_ROWS = 200_000
-/** 离线导出图像帧上限(单次) */
-export const MES_EXPORT_MAX_FRAMES = 500
-
-// ============================================================
-// 频次限流(进程内内存计数;Map<agentId, 时间戳[]>)
-// ============================================================
-
-const fetchCallStamps = new Map<string, number[]>()
-
-/** 记一次 fetch 并判定是否放行(滑动 60s 窗 ≤6 次;超限不记账) */
-export function mesFetchRateCheck(agentId: string, nowMs = Date.now()): boolean {
-  const stamps = (fetchCallStamps.get(agentId) ?? []).filter(t => nowMs - t < MES_RATE_WINDOW_MS)
-  if (stamps.length >= MES_RATE_MAX_CALLS) {
-    fetchCallStamps.set(agentId, stamps)
-    return false
-  }
-  stamps.push(nowMs)
-  fetchCallStamps.set(agentId, stamps)
-  return true
-}
-
-/** 清空限流账(测试用) */
-export function mesFetchRateReset(): void {
-  fetchCallStamps.clear()
-}
-
-// ============================================================
-// 节点/依赖(结构化注入;缺省接真实服务,测试注入假件不联网)
-// ============================================================
-
-export interface MesNodeLike {
-  id: string
-  name: string
-  driver: string
-  lineId: string
-  unit: string
-  min: number
-  max: number
-  enabled: boolean
-  driverConfig: Record<string, string | number | boolean>
-}
-
-export interface MesControllerDeps {
-  /** 数据集服务(异步取数账本;缺省 getMesDatasets()) */
-  store: Pick<MesDatasetStore, 'createFetchJob'>
-  /** 全量 dcw 节点(缺省 dcw-node.repo) */
-  nodes: () => MesNodeLike[] | Promise<MesNodeLike[]>
-  /** 调用者可见节点(绑线过滤:dcw 绑定集;缺省 node-bindings.repo) */
-  boundNodeIds: (agentId: string) => Set<string> | Promise<Set<string>>
-  /** 驱动解析(缺省 dcw 注册表) */
-  resolveDriver: (kind: string) => MesHistoryDriver
-  nowMs: () => number
-}
-
-/** 缺省依赖:重模块(dcw 仓储/绑线仓储)经动态 import 引入,保持本模块可被 tsx 测试轻量直跑 */
-function defaultDeps(): MesControllerDeps {
-  return {
-    store: new Proxy({} as Pick<MesDatasetStore, 'createFetchJob'>, {
-      get: (_t, prop) => {
-        const store = getMesDatasets() as unknown as Record<string | symbol, unknown>
-        const v = store[prop]
-        return typeof v === 'function' ? (v as (...a: unknown[]) => unknown).bind(store) : v
-      },
-    }),
-    nodes: async () => {
-      const { getDcwNodeRepo } = await import('../dcw/dcw-node.repo')
-      return getDcwNodeRepo().all()
-    },
-    boundNodeIds: async (agentId) => {
-      // 权限模型 v2:dcw 绑定(存量)∪ 绑定配方内的参数节点(kind='recipe' 的配方可见节点)
-      const { getAgentNodeBindingRepo } = await import('../agents/node-bindings.repo')
-      const { getDcwController } = await import('../dcw/dcw-controller')
-      const bindings = getAgentNodeBindingRepo().byAgent(agentId)
-      const ids = new Set(bindings.filter(b => b.kind === 'dcw').map(b => b.nodeId))
-      const recipeIds = new Set(bindings.filter(b => b.kind === 'recipe').map(b => b.nodeId))
-      if (recipeIds.size > 0) {
-        for (const r of getDcwController().listRecipes()) {
-          if (!recipeIds.has(r.id)) continue
-          for (const p of r.params) ids.add(p.nodeId)
-        }
-      }
-      return ids
-    },
-    resolveDriver: kind => resolveDcwDriver(kind as Parameters<typeof resolveDcwDriver>[0]),
-    nowMs: () => Date.now(),
-  }
-}
-
-export type MesCatalogEntry = {
-  id: string
-  name: string
-  lineId: string
-  unit: string
-  min: number
-  max: number
-  desc: string
-  readable: boolean
-  writable: boolean
-  historyable: boolean
-  /** 历史格式(scalar/vector/image/table/event;historyMap 未配置时 scalar) */
-  format: MesHistoryFormat
-  /** 已配置数据下沉 hook(dataHook) */
-  hooked: boolean
-  enabled: boolean
-  /** 字段级数据字典(响应缓存 ∪ 节点静态配置;无则空数组) */
-  fields: DcwFieldDef[]
-}
-
-// ============================================================
-// 字段字典缓存(响应返回 → 后续 catalog/导出复用)
-// ============================================================
-
-const dictionaryCache = new Map<string, DcwFieldDef[]>()
-const DICTIONARY_CACHE_MAX = 200
-
-function cacheDictionary(nodeId: string, fields: DcwFieldDef[] | undefined): void {
-  if (!fields || fields.length === 0) return
-  dictionaryCache.delete(nodeId)
-  dictionaryCache.set(nodeId, fields)
-  while (dictionaryCache.size > DICTIONARY_CACHE_MAX) {
-    const oldest = dictionaryCache.keys().next().value
-    if (oldest === undefined) break
-    dictionaryCache.delete(oldest)
-  }
-}
-
-/** 节点静态字典(driverConfig.dictionary / fieldDictionary 的 JSON 文本) */
-function configuredDictionary(cfg: Record<string, unknown>): DcwFieldDef[] {
-  for (const key of ['dictionary', 'fieldDictionary', 'fields']) {
-    const raw = cfg[key]
-    if (raw === undefined || raw === null || String(raw).trim() === '') continue
-    try {
-      const parsed = typeof raw === 'string' ? JSON.parse(raw) as unknown : raw
-      const fields = normalizeMesDictionary(parsed)
-      if (fields.length > 0) return fields
-    }
-    catch { /* 坏配置不击穿目录;由驱动测试报错 */ }
-  }
-  return []
-}
-
-/** 节点有效字典:响应缓存优先(实时真相),否则静态配置 */
-export function mesDictionaryOfNode(nodeId: string, cfg: Record<string, unknown>): DcwFieldDef[] {
-  return dictionaryCache.get(nodeId) ?? configuredDictionary(cfg)
-}
-
-/** 字典一行摘要(字段名(标签,单位;量程;点数)) */
-export function fieldSummaryOf(fields: DcwFieldDef[]): string {
-  return fields.slice(0, 8).map((f) => {
-    const bits = [f.label, f.unit, f.min != null || f.max != null ? `${f.min ?? '-∞'}~${f.max ?? '+∞'}` : '', f.points?.length ? `${f.points.length} 点` : '']
-      .filter(Boolean)
-    return bits.length > 0 ? `${f.field}(${bits.join(',')})` : f.field
-  }).join('; ')
-}
-
-/** 字段字典 → 多行可读文本(Agent 直接引用;含单位/量程/物理意义/逐点语义) */
-export function formatDictionary(fields: DcwFieldDef[], indent = '  '): string {
-  if (fields.length === 0) return ''
-  const pointLine = (f: DcwFieldDef): string => {
-    const pts = f.points ?? []
-    if (pts.length === 0) return ''
-    const head = pts.slice(0, 6).map(p => `${p.index ?? '?'}=${p.label ?? p.field}${p.unit ? `(${p.unit})` : ''}`).join(', ')
-    return `; 点位 ${pts.length} 个: ${head}${pts.length > 6 ? ', …' : ''}`
-  }
-  const lines = fields.slice(0, 24).map((f) => {
-    const meta = [
-      f.label && f.label !== f.field ? `标签 ${f.label}` : '',
-      f.unit ? `单位 ${f.unit}` : '',
-      f.min != null || f.max != null ? `量程 ${f.min ?? '-∞'}~${f.max ?? '+∞'}` : '',
-      f.kind ? `形态 ${f.kind}` : '',
-    ].filter(Boolean).join(' | ')
-    const desc = f.description ? ` — ${f.description.slice(0, 160)}` : ''
-    return `${indent}- ${f.field}${meta ? ` [${meta}]` : ''}${desc}${pointLine(f)}`
-  })
-  return `字段字典(${fields.length} 个字段,来自 MES 响应/节点配置):\n${lines.join('\n')}${fields.length > 24 ? `\n${indent}(仅显示前 24 个字段)` : ''}`
-}
-
-/** 目录条目合成:desc/readMap/writeMap/historyMap 均来自 driverConfig(数据驱动,零硬编码) */
-export function mesCatalogEntryOf(n: MesNodeLike): MesCatalogEntry {
-  const cfg = n.driverConfig ?? {}
-  return {
-    id: n.id,
-    name: n.name,
-    lineId: n.lineId ?? '',
-    unit: n.unit ?? '',
-    min: n.min,
-    max: n.max,
-    desc: String(cfg.desc ?? ''),
-    readable: Boolean(cfg.readMap),
-    writable: Boolean(cfg.writeMap),
-    historyable: Boolean(cfg.historyMap),
-    format: historyFormatOf(cfg as Record<string, unknown>),
-    hooked: Boolean(cfg.dataHook),
-    enabled: Boolean(n.enabled),
-    fields: mesDictionaryOfNode(n.id, cfg as Record<string, unknown>),
-  }
-}
-
-// ============================================================
-// 控制器
-// ============================================================
-
-export type MesToolResult = { text: string, isError?: boolean }
-
-export type MesFetchOutcome = MesToolResult & {
-  mode?: 'snapshot' | 'inline' | 'async'
-  data?: {
-    job_ids?: string[]
-    dataset_ids?: string[]
-    stats?: Array<{ nodeId: string, stats: MesDatasetStatsView, truncated: boolean }>
-  }
-}
-
-export interface MesFetchArgs {
-  ids?: unknown
-  from?: string
-  to?: string
-  max_rows?: number | string
-  /** 透传给 requestHook/dataHook 的参数对象(Agent 只传 param,其余交给配置) */
-  param?: unknown
-  /** 内联/快照回包是否附带采样行的实际数组/数值内容(默认 false=只给统计与均值) */
-  include_data?: boolean | string
-}
-
-export interface MesCatalogArgs {
-  q?: string
-  line_id?: string
-  /** 按产品 id 收窄到该产品产线(可选;与 line_id 冲突时拒绝) */
-  product_id?: string
-  /** 按配方 id 收窄到该配方产线(可选;与 line_id 冲突时拒绝) */
-  recipe_id?: string
-  limit?: number | string
-  /** 调用者可读产线集(绑线授权口径);提供时严格过滤(孤儿/越线点位不可见,空集=空目录 fail-closed) */
-  scope_line_ids?: string[]
-}
-
-export interface MesExportArgs {
-  ids?: unknown
-  from?: string
-  to?: string
-  max_rows?: number | string
-  /** 透传给 requestHook 的调用参数 */
-  param?: unknown
-  /** 导出子目录(相对 <数据根>/mes-exports;绝对路径须落在 AW_MES_EXPORT_ROOT 内) */
-  folder?: string
-  title?: string
-  note?: string
-  /** 标量节点是否生成按时间对齐的 merged.csv(缺省 true) */
-  merge?: boolean | string
-}
-
-export function createMesController(deps: Partial<MesControllerDeps> = {}) {
-  const d: MesControllerDeps = { ...defaultDeps(), ...deps }
-
-  // ---------- 目录 ----------
-
-  /** mes-rest 点位目录(q 对 name/desc 子串过滤;line_id 精确过滤;limit 缺省 20;
-   *  scope_line_ids 提供时按调用者可读产线严格过滤——跨产线点位与孤儿(未分配)点位不可见) */
-  async function catalog(args: MesCatalogArgs = {}): Promise<MesToolResult & { entries: MesCatalogEntry[], total: number }> {
-    const all = await d.nodes()
-    let mes = all.filter(n => n.driver === MES_REST_DRIVER_KIND).map(mesCatalogEntryOf)
-    if (Array.isArray(args.scope_line_ids)) {
-      const scope = new Set(args.scope_line_ids)
-      mes = mes.filter(e => e.lineId !== '' && scope.has(e.lineId))
-    }
-    const total = mes.length
-    let lineId = String(args.line_id ?? '').trim()
-    const productId = String(args.product_id ?? '').trim()
-    if (productId) {
-      const { getDcwProductRepo } = await import('../dcw/dcw-product.repo')
-      const product = getDcwProductRepo().byId(productId)
-      if (!product) return { text: `产品 ${productId} 不存在。`, isError: true, entries: [], total: 0 }
-      if (lineId && product.lineId !== lineId) return { text: `产品 ${productId} 归属产线 ${product.lineId},与 line_id=${lineId} 不一致。`, isError: true, entries: [], total: 0 }
-      lineId = product.lineId
-    }
-    const recipeId = String(args.recipe_id ?? '').trim()
-    if (recipeId) {
-      const { getDcwController } = await import('../dcw/dcw-controller')
-      const recipe = getDcwController().listRecipes().find(r => r.id === recipeId)
-      if (!recipe) return { text: `配方 ${recipeId} 不存在。`, isError: true, entries: [], total: 0 }
-      if (lineId && recipe.lineId !== lineId) return { text: `配方 ${recipeId} 归属产线 ${recipe.lineId},与 line_id=${lineId} 不一致。`, isError: true, entries: [], total: 0 }
-      lineId = recipe.lineId
-    }
-    if (lineId) mes = mes.filter(e => e.lineId === lineId)
-    const q = String(args.q ?? '').trim().toLowerCase()
-    if (q) mes = mes.filter(e => e.name.toLowerCase().includes(q) || e.desc.toLowerCase().includes(q))
-    const limit = Math.min(Math.max(Math.round(Number(args.limit)) || 20, 1), 100)
-    const shown = mes.slice(0, limit)
-
-    const cap = (e: MesCatalogEntry): string => {
-      const hist = e.historyable ? (e.format !== 'scalar' ? `史·${e.format}` : '史') : null
-      const ab = [e.readable ? '读' : null, e.writable ? '写' : null, hist, e.hooked ? '钩子' : null].filter(Boolean)
-      return ab.length > 0 ? ab.join('/') : '无能力位'
-    }
-    const body = shown.map((e) => {
-      const fields = e.fields.length > 0 ? ` | 字段: ${fieldSummaryOf(e.fields)}` : ''
-      return `- ${e.name}(id=${e.id}) | 产线 ${e.lineId || '未分配'} | 单位 ${e.unit || '-'} | 量程 ${e.min}~${e.max} | 能力 ${cap(e)}${e.enabled ? '' : ' [停用]'}${e.desc ? ` | ${e.desc.slice(0, 80)}` : ''}${fields}`
-    })
-    const more = mes.length - shown.length
-    const text = `MES REST 点位目录(共 ${total} 个${lineId ? `,产线 ${lineId}` : ''}${q ? `,关键字「${args.q}」` : ''};显示 ${shown.length} 条):\n${body.join('\n') || '(无匹配点位)'}${more > 0 ? `\n(另有 ${more} 条未显示,可收紧 q/line_id 或调大 limit≤100)` : ''}\n\n说明:能力 读=可读当前值,写=可写设定值,史=可取历史(史·vector=每时间点检测向量,史·image=图像帧,史·table/event=记录流),钩子=已配 dataHook(取数后自动做下沉处理并回传摘要与产物)。字段级语义来自 MES 响应 dictionaryPath 或节点 driverConfig.dictionary;首次 mes_fetch 后缓存,后续目录可直接看到字段标签/单位/点位。历史取数用 mes_fetch(ids=[点位id], from, to, max_rows, param?);需要落盘到目录做离线分析用 mes_export。`
-    return { text, entries: shown, total }
-  }
-
-  // ---------- 取数 ----------
-
-  /** 归一 ids + 授权过滤(绑线路径:仅调用者 dcw 绑定的 mes-rest 节点) */
-  async function resolveVisibleIds(agentId: string, rawIds: unknown): Promise<{ ok: true, nodes: MesNodeLike[] } | { ok: false, text: string, isError: true }> {
-    const ids = Array.isArray(rawIds) ? [...new Set(rawIds.map(x => String(x ?? '').trim()).filter(Boolean))] : []
-    if (ids.length === 0) return { ok: false, text: 'ids 必填:目标 mes-rest 点位 id 数组(catalog 输出的 id;至少 1 个)。', isError: true }
-    const all = await d.nodes()
-    const bound = await d.boundNodeIds(agentId)
-    const mesById = new Map(all.filter(n => n.driver === MES_REST_DRIVER_KIND).map(n => [n.id, n]))
-    const picked: MesNodeLike[] = []
-    const missing: string[] = []
-    const notAllowed: string[] = []
-    for (const id of ids) {
-      const n = mesById.get(id)
-      if (!n) {
-        missing.push(id)
-        continue
-      }
-      if (!bound.has(id)) {
-        notAllowed.push(id)
-        continue
-      }
-      picked.push(n)
-    }
-    if (missing.length > 0 || notAllowed.length > 0) {
-      const allowed = [...bound]
-        .map(id => mesById.get(id))
-        .filter((n): n is MesNodeLike => !!n && n.driver === MES_REST_DRIVER_KIND)
-      const parts: string[] = []
-      if (missing.length > 0) parts.push(`不存在或不是 mes-rest 点位:${missing.join(', ')}`)
-      if (notAllowed.length > 0) parts.push(`无权访问(须为你绑定的数控节点):${notAllowed.join(', ')}`)
-      return {
-        ok: false,
-        text: `取数被拒:${parts.join(';')}。你有权取数的 mes-rest 点位:${allowed.map(n => `${n.name}(${n.id})`).join(', ') || '(无)'}。`,
-        isError: true,
-      }
-    }
-    return { ok: true, nodes: picked }
-  }
-
-  /** 时间窗/行数护栏归一(代码级;返回错误文本或归一值) */
-  function normalizeWindow(args: MesFetchArgs): { ok: true, from?: string, to?: string, maxRows: number } | { ok: false, text: string, isError?: true } {
-    const from = String(args.from ?? '').trim()
-    const to = String(args.to ?? '').trim()
-    if ((from && !to) || (!from && to)) {
-      return { ok: false, text: 'from/to 必须成对提供(历史取数),或都不传(当前值快照模式)。' }
-    }
-    if (from && to) {
-      const fromMs = Date.parse(from)
-      const toMs = Date.parse(to)
-      if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return { ok: false, text: 'from/to 必须是合法 ISO 时间戳。' }
-      if (fromMs >= toMs) return { ok: false, text: `时间窗无效:from(${from}) 必须早于 to(${to})。` }
-      if (toMs - fromMs > MES_WINDOW_MAX_MS) {
-        return { ok: false, text: `时间窗被拒:窗口 ${(toMs - fromMs) / 3_600_000 / 24} 天超过上限 7 天。请拆成 ≤7 天的分段分批取数。`, isError: true }
-      }
-    }
-    const maxRows = args.max_rows == null || args.max_rows === '' ? MES_DEFAULT_MAX_ROWS : Math.round(Number(args.max_rows))
-    if (!Number.isFinite(maxRows) || maxRows < 1) return { ok: false, text: 'max_rows 必须为 ≥1 的整数。' }
-    if (maxRows > MES_MAX_ROWS_CAP) {
-      return { ok: false, text: `max_rows=${maxRows} 被拒:单次取数上限 ${MES_MAX_ROWS_CAP} 行。请缩小时间窗或分批取数。`, isError: true }
-    }
-    return { ok: true, from: from || undefined, to: to || undefined, maxRows }
-  }
-
-  /** 统计摘要(数值列;均值/采样标准差) */
-  function statsOf(values: number[], firstTs: string | null, lastTs: string | null): MesDatasetStatsView {
-    const n = values.length
-    if (n === 0) return { count: 0, min: null, max: null, mean: null, stddev: null, firstTs: null, lastTs: null }
-    const min = Math.min(...values)
-    const max = Math.max(...values)
-    const mean = values.reduce((a, b) => a + b, 0) / n
-    const stddev = n > 1 ? Math.sqrt(values.reduce((a, b) => a + (b - mean) ** 2, 0) / (n - 1)) : 0
-    return { count: n, min, max, mean, stddev, firstTs, lastTs }
-  }
-
-  const fmtN = (v: number | null | undefined, digits = 3): string =>
-    v == null || !Number.isFinite(v) ? '-' : String(Number(v.toFixed(digits)))
-  const shortTs = (iso: string | null): string => iso && iso.length >= 19 ? iso.slice(5, 19).replace('T', ' ') : (iso ?? '-')
-  const clip = (v: unknown, max: number): string => {
-    const s = typeof v === 'string' ? v : JSON.stringify(v) ?? String(v)
-    return s.length > max ? `${s.slice(0, max)}…` : s
-  }
-
-  // -------- 格式感知取数(行形态全谱;内存硬顶防大payload 拖垮进程) --------
-
-  /** 泛化历史行缓冲的硬顶 */
-  const VECTOR_ELEMENT_CAP = 2_000_000
-  const IMAGE_BASE64_CAP = 16_000_000
-  const RECORD_JSON_CAP = 8_000_000
-  /** image 格式自动落盘帧数上限(其余帧不落盘,回包注明) */
-  const IMAGE_AUTOSAVE_MAX = 20
-
-  interface GenRow { ts: string, value?: number, values?: number[], data?: string, mime?: string, record?: unknown }
-
-  interface GenStats extends MesDatasetStatsView {
-    /** vector:维度(首行长度)与维度不齐行数 */
-    dim?: number
-    dimMismatch?: number
-    /** vector:全体元素均值(比行均值更细) */
-    elementMean?: number
-  }
-
-  /** requestHook 覆盖合并:克隆 driverConfig,把 {path,query,headers} 合入 historyMap JSON */
-  async function configWithRequestHook(node: MesNodeLike, param: unknown): Promise<Record<string, unknown>> {
-    const cfg = { ...(node.driverConfig as Record<string, unknown>) }
-    const hookCode = mesRequestHookCode(cfg as Record<string, unknown>)
-    if (!hookCode) return cfg
-    const overrides = await runMesRequestHook(hookCode, param, { nodeId: node.id })
-    if (overrides.path === undefined && overrides.query === undefined && overrides.headers === undefined) return cfg
-    try {
-      const map = JSON.parse(String(cfg.historyMap ?? '{}')) as Record<string, unknown>
-      if (overrides.path !== undefined) map.path = overrides.path
-      const baseQuery = (map.query !== null && typeof map.query === 'object' && !Array.isArray(map.query) ? map.query : {}) as Record<string, unknown>
-      map.query = { ...baseQuery, ...(overrides.query ?? {}) }
-      const baseHeaders = (map.headers !== null && typeof map.headers === 'object' && !Array.isArray(map.headers) ? map.headers : {}) as Record<string, unknown>
-      if (overrides.headers !== undefined) map.headers = { ...baseHeaders, ...overrides.headers }
-      cfg.historyMap = JSON.stringify(map)
-    }
-    catch (err) {
-      throw new AppError(422, 'MES_HOOK_FAILED', `requestHook 覆盖合并失败(historyMap 非法 JSON):${err instanceof Error ? err.message : String(err)}`)
-    }
-    return cfg
-  }
-
-  /** 向量行统计摘要(行均值序列 stats + 维度 + 全体元素均值) */
-  function vectorStats(rows: GenRow[]): GenStats {
-    const rowMeans = rows.map((r) => {
-      const vs = r.values ?? []
-      return vs.length > 0 ? vs.reduce((a, b) => a + b, 0) / vs.length : NaN
-    }).filter(v => Number.isFinite(v))
-    const all: number[] = []
-    for (const r of rows) if (Array.isArray(r.values)) all.push(...r.values)
-    const base = statsOf(rowMeans, rows[0]?.ts ?? null, rows[rows.length - 1]?.ts ?? null) as GenStats
-    base.dim = Array.isArray(rows[0]?.values) ? rows[0]!.values!.length : undefined
-    base.dimMismatch = base.dim === undefined ? undefined : rows.filter(r => Array.isArray(r.values) && r.values!.length !== base.dim).length
-    base.elementMean = all.length > 0 ? all.reduce((a, b) => a + b, 0) / all.length : undefined
-    return base
-  }
-
-  /** 同步取单节点历史(格式感知:统计+采样+图像落盘+dataHook 下沉处理;原文不回传) */
-  async function inlineFetchNode(node: MesNodeLike, from: string, to: string, maxRows: number, param: unknown, includeData = false): Promise<{
-    text: string
-    stats: MesDatasetStatsView
-    truncated: boolean
-    sample: string[]
-    hookText?: string
-    artifacts: MesHookArtifact[]
-  }> {
-    const cfg = node.driverConfig as Record<string, unknown>
-    const format = historyFormatOf(cfg)
-    const driver = d.resolveDriver(node.driver)
-    if (typeof driver.fetchHistory !== 'function') {
-      return { text: `驱动 ${node.driver} 未提供历史原语(fetchHistory)`, stats: statsOf([], null, null), truncated: true, sample: [], artifacts: [] }
-    }
-    const effCfg = await configWithRequestHook(node, param)
-    const buf: GenRow[] = []
-    let truncated = false
-    let vecElems = 0
-    let imgChars = 0
-    let recChars = 0
-    let memoryHit = ''
-    let dictionary: DcwFieldDef[]
-    const result = await driver.fetchHistory({
-      driverConfig: effCfg,
-      fromIso: from,
-      toIso: to,
-      maxRows,
-      onRows: (batch) => {
-        for (const r of batch ?? []) {
-          if (buf.length >= maxRows) {
-            truncated = true
-            break
-          }
-          const row: GenRow = { ts: String(r?.ts ?? '') }
-          if (typeof r?.value === 'number') row.value = r.value
-          if (Array.isArray(r?.values)) {
-            vecElems += r.values.length
-            if (vecElems > VECTOR_ELEMENT_CAP) {
-              memoryHit = `向量元素总量超过 ${VECTOR_ELEMENT_CAP} 上限`
-              truncated = true
-              break
-            }
-            row.values = r.values as number[]
-          }
-          if (typeof r?.data === 'string') {
-            imgChars += r.data.length
-            if (imgChars > IMAGE_BASE64_CAP) {
-              memoryHit = `图像载荷总量超过 ${Math.round(IMAGE_BASE64_CAP / 1024 / 1024)}MB 上限`
-              truncated = true
-              break
-            }
-            row.data = r.data
-            row.mime = typeof r?.mime === 'string' ? r.mime : 'image/png'
-          }
-          if (r?.record !== undefined && r.record !== null) {
-            let json: string
-            try {
-              json = JSON.stringify(r.record)
-            }
-            catch {
-              continue
-            }
-            recChars += json.length
-            if (recChars > RECORD_JSON_CAP) {
-              memoryHit = `记录载荷总量超过 ${Math.round(RECORD_JSON_CAP / 1024 / 1024)}MB 上限`
-              truncated = true
-              break
-            }
-            row.record = r.record
-          }
-          buf.push(row)
-        }
-      },
-    })
-    if (result?.dictionary && result.dictionary.length > 0) {
-      dictionary = result.dictionary
-      cacheDictionary(node.id, dictionary)
-    }
-    else {
-      dictionary = mesDictionaryOfNode(node.id, cfg)
-    }
-    if (result && result.complete === false) truncated = true
-    if (!truncated && memoryHit) truncated = true
-
-    // 统计与采样(按格式)
-    let stats: GenStats
-    let autosaved: MesHookArtifact[] = []
-    const sample: string[] = []
-    let tableFieldStats = ''
-    if (format === 'vector') {
-      stats = vectorStats(buf)
-      // 空窗口不得生成采样下标(否则 buf[0] undefined → 取数崩溃)
-      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
-      const vecField = dictionary.find(f => f.kind === 'vector' || (f.points?.length ?? 0) > 0)
-      const pointLabel = (i: number): string => {
-        const p = vecField?.points?.[i]
-        return p?.label ?? p?.field ?? `v${i}`
-      }
-      for (const i of idx) {
-        const r = buf[i]!
-        const vs = r.values ?? []
-        const m = vs.length > 0 ? vs.reduce((a, b) => a + b, 0) / vs.length : NaN
-        const valuesTxt = includeData && vs.length > 0
-          ? `,values=[${vs.slice(0, 64).map((v, j) => `${pointLabel(j)}=${Number(v.toFixed(4))}`).join(',')}${vs.length > 64 ? ',…' : ''}]`
-          : ''
-        sample.push(`${shortTs(r.ts)},dim=${vs.length},mean=${fmtN(m)},min=${fmtN(vs.length ? Math.min(...vs) : NaN)},max=${fmtN(vs.length ? Math.max(...vs) : NaN)}${valuesTxt}`)
-      }
-    }
-    else if (format === 'image') {
-      stats = { count: buf.length, min: null, max: null, mean: null, stddev: null, firstTs: buf[0]?.ts ?? null, lastTs: buf[buf.length - 1]?.ts ?? null }
-      // 图像 base64 永不进 prompt:自动落盘(≤20 帧),采样给文件名
-      const saved: MesHookArtifact[] = []
-      for (const [i, r] of buf.entries()) {
-        if (typeof r.data !== 'string') continue
-        if (saved.length >= IMAGE_AUTOSAVE_MAX) break
-        const a = saveMesImageArtifact(node.id, `frame-${String(i).padStart(4, '0')}`, r.data, r.mime ?? 'image/png')
-        if (a) saved.push(a)
-      }
-      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
-      for (const i of idx) {
-        const r = buf[i]!
-        const kb = r.data ? Math.round(r.data.length * 3 / 4 / 1024) : 0
-        const f = saved.find(x => x.name.includes(`frame-${String(i).padStart(4, '0')}`))
-        sample.push(`${shortTs(r.ts)},${r.mime ?? 'image/png'},~${kb}KB${f ? ` → ${f.name}` : ''}`)
-      }
-      autosaved = saved
-    }
-    else if (format === 'table' || format === 'event') {
-      stats = { count: buf.length, min: null, max: null, mean: null, stddev: null, firstTs: buf[0]?.ts ?? null, lastTs: buf[buf.length - 1]?.ts ?? null }
-      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
-      for (const i of idx) {
-        const r = buf[i]!
-        let body: string
-        try {
-          body = JSON.stringify(r.record)
-        }
-        catch {
-          body = '(不可序列化)'
-        }
-        sample.push(`${shortTs(r.ts)},${clip(body ?? '', 120)}`)
-      }
-      // map/多参数行:逐数值字段统计(最多 12 个字段),让 Agent 不必只看 3 行采样
-      const cols = new Map<string, number[]>()
-      for (const r of buf) {
-        if (r.record === null || typeof r.record !== 'object' || Array.isArray(r.record)) continue
-        for (const [k, v] of Object.entries(r.record as Record<string, unknown>)) {
-          if (v === null || v === '' || typeof v === 'boolean') continue
-          const n = Number(v)
-          if (!Number.isFinite(n)) continue
-          const arr = cols.get(k) ?? []
-          arr.push(n)
-          cols.set(k, arr)
-        }
-      }
-      const fieldLines = [...cols.entries()].slice(0, 12).map(([k, vs]) => {
-        const mean = vs.reduce((a, b) => a + b, 0) / vs.length
-        const def = dictionary.find(f => f.field === k)
-        const label = def?.label ? `${def.label}(${k})` : k
-        const unit = def?.unit ? ` ${def.unit}` : ''
-        return `${label}: n=${vs.length} min=${fmtN(Math.min(...vs))} max=${fmtN(Math.max(...vs))} mean=${fmtN(mean)}${unit}`
-      })
-      if (fieldLines.length > 0) {
-        tableFieldStats = `  数值字段统计(${cols.size} 个字段${cols.size > 12 ? ',显示前12' : ''}): ${fieldLines.join(' | ')}`
-      }
-    }
-    else {
-      const values = buf.map(r => r.value).filter((v): v is number => Number.isFinite(v))
-      stats = statsOf(values, buf[0]?.ts ?? null, buf[buf.length - 1]?.ts ?? null)
-      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
-      for (const i of idx) sample.push(`${shortTs(buf[i]!.ts)},${fmtN(buf[i]!.value ?? NaN)}${includeData ? ` (value=${buf[i]!.value ?? '-'})` : ''}`)
-    }
-
-    const fmtLabel = format === 'scalar' ? `标量` : format === 'vector' ? `向量(dim=${stats.dim ?? '?'})` : format === 'image' ? `图像(${(buf[0]?.mime as string) ?? 'image/png'})` : format === 'table' ? `表格记录` : `事件记录`
-    const statLine = format === 'scalar'
-      ? `  统计:min ${fmtN(stats.min)} / max ${fmtN(stats.max)} / mean ${fmtN(stats.mean)} / stddev ${fmtN(stats.stddev)} ${node.unit}`
-      : format === 'vector'
-        ? `  统计(按行均值):min ${fmtN(stats.min)} / max ${fmtN(stats.max)} / mean ${fmtN(stats.mean)} / stddev ${fmtN(stats.stddev)} ${node.unit};全体元素均值 ${fmtN(stats.elementMean ?? NaN)}${stats.dimMismatch ? `;维度漂移 ${stats.dimMismatch} 行` : ''}`
-        : `  统计:${stats.count} 条记录(非数值格式不做均值)`
-    const dictText = formatDictionary(dictionary)
-    const text = [
-      `■ ${node.name}(id=${node.id})[格式 ${fmtLabel};节点单位 ${node.unit || '-'};量程 ${node.min}~${node.max}]`,
-      `  行数 ${stats.count}${truncated ? `(截断:${memoryHit || '达到 maxRows 上限'})` : '(完整)'} | 首 ${shortTs(stats.firstTs)} ~ 末 ${shortTs(stats.lastTs)}`,
-      statLine,
-      sample.length > 0 ? `  采样(≤3 行): ${sample.join(' | ')}` : '  采样:无有效行',
-      ...(tableFieldStats ? [tableFieldStats] : []),
-      ...(dictText ? [dictText] : []),
-    ].join('\n')
-
-    // dataHook 下沉处理(用户配置的 (param, data, ctx) => {...})
-    let hookText: string | undefined
-    const artifacts: MesHookArtifact[] = [...(autosaved as MesHookArtifact[])]
-    const hookCode = mesDataHookCode(cfg)
-    if (hookCode) {
-      const hookData: MesHookData = {
-        node: { id: node.id, name: node.name, lineId: node.lineId, unit: node.unit },
-        format,
-        rows: buf,
-        window: { from, to },
-      }
-      try {
-        const outcome = await runMesDataHook(hookCode, param, hookData, { nodeId: node.id })
-        if (outcome.ok) {
-          artifacts.push(...outcome.artifacts)
-          const parts = [`  钩子(dataHook):已执行,产物 ${outcome.artifacts.length} 个`]
-          if (outcome.summary) parts.push(`  处理摘要: ${outcome.summary}`)
-          if (outcome.context) parts.push(`  处理说明: ${outcome.context}`)
-          if (outcome.logs.length > 0) parts.push(`  hook 日志(≤3): ${outcome.logs.slice(0, 3).join(' / ')}`)
-          hookText = parts.join('\n')
-        }
-        else {
-          hookText = `  钩子(dataHook)执行失败:${outcome.error ?? '未知原因'}(统计仍基于原始数据)`
-        }
-      }
-      catch (err) {
-        hookText = `  钩子(dataHook)执行失败:${err instanceof Error ? err.message : String(err)}`
-      }
-    }
-
-    // 产物行(hook 之外含自动落盘图像)
-    if (artifacts.length > 0) {
-      const shown = artifacts.slice(0, 8).map(a => `${a.name}(${Math.max(1, Math.round(a.bytes / 1024))}KB)`)
-      hookText = `${hookText ?? ''}\n  产物(${artifacts.length}${artifacts.length > 8 ? ',显示前8' : ''}): ${shown.join(' | ')}`
-    }
-    return { text, stats, truncated, sample, hookText, artifacts }
-  }
-
-  /**
-   * 取数编排(护栏全代码级):
-   * 授权过滤 → 窗口/行数归一 → 频次限流 → 快照 / 内联 / 异步三模式。
-   */
-  async function fetch(agentId: string, args: MesFetchArgs): Promise<MesFetchOutcome> {
-    // ① 授权:ids 必须是调用者可见(绑线)的 mes-rest 节点
-    const vis = await resolveVisibleIds(agentId, args.ids)
-    if (!vis.ok) return { text: vis.text, isError: true }
-    // ② 窗口/行数护栏
-    const win = normalizeWindow(args)
-    if (!win.ok) return { text: win.text, isError: true }
-    // ③ 频次限流(每 agent 每 60s ≤6 次)
-    if (!mesFetchRateCheck(agentId, d.nowMs())) {
-      return { text: `取数过于频繁:每 60 秒最多 ${MES_RATE_MAX_CALLS} 次。请先消化已有结果,稍后再取。`, isError: true }
-    }
-    // ④ 格式门控:image/table/event 的原文(帧/记录)不进 prompt 也不落 CSV 数据集,
-    //    只支持内联行数(≤MES_SYNC_INLINE_MAX_ROWS);大窗口请拆小分批
-    if (win.maxRows > MES_SYNC_INLINE_MAX_ROWS) {
-      const INLINE_ONLY = new Set(['image', 'table', 'event'])
-      const hits = vis.nodes.filter(n => INLINE_ONLY.has(historyFormatOf(n.driverConfig as Record<string, unknown>)))
-      if (hits.length > 0) {
-        return {
-          text: `行数上限冲突:${hits.map(n => `${n.name}(${n.id})`).join(', ')} 是 图像/表格/事件 格式点位,只在 max_rows ≤ ${MES_SYNC_INLINE_MAX_ROWS} 的内联模式支持(原文不落 CSV 数据集)。请缩小时间窗或调低 max_rows 后重取。`,
-          isError: true,
-        }
-      }
-    }
-
-    // 模式一:当前值快照(无 from/to)
-    if (!win.from || !win.to) {
-      const lines: string[] = []
-      for (const node of vis.nodes) {
-        const driver = d.resolveDriver(node.driver)
-        try {
-          if (typeof driver.read !== 'function') {
-            lines.push(`- ${node.name}(${node.id}):驱动 ${node.driver} 不支持读取`)
-            continue
-          }
-          const r = await driver.read({ domain: { min: node.min, max: node.max }, driverConfig: node.driverConfig })
-          const at = new Date(d.nowMs()).toISOString()
-          if (r.dictionary && r.dictionary.length > 0) cacheDictionary(node.id, r.dictionary)
-          const dict = r.dictionary && r.dictionary.length > 0 ? r.dictionary : mesDictionaryOfNode(node.id, node.driverConfig as Record<string, unknown>)
-          lines.push(r.ok && r.eng != null
-            ? `- ${node.name}(${node.id}):${fmtN(r.eng)}${node.unit} @ ${shortTs(at)}${dict.length > 0 ? `\n${formatDictionary(dict, '    ')}` : ''}`
-            : `- ${node.name}(${node.id}):读取失败(${r.message.slice(0, 80)})`)
-        }
-        catch (err) {
-          lines.push(`- ${node.name}(${node.id}):读取异常(${(err instanceof Error ? err.message : String(err)).slice(0, 80)})`)
-        }
-      }
-      return {
-        mode: 'snapshot',
-        text: `MES 当前值快照(${vis.nodes.length} 个点位,内联直读):\n${lines.join('\n')}\n\n说明:当前值为直读快照;历史窗口用 mes_fetch 带 from/to(≤7 天,max_rows≤${MES_MAX_ROWS_CAP})。`,
-      }
-    }
-
-    // 模式二:同步内联(行数 ≤ MES_SYNC_INLINE_MAX_ROWS;格式感知+dataHook 下沉)
-    if (win.maxRows <= MES_SYNC_INLINE_MAX_ROWS) {
-      const sections: string[] = []
-      const statsOut: NonNullable<MesFetchOutcome['data']>['stats'] = []
-      for (const node of vis.nodes) {
-        try {
-          const one = await inlineFetchNode(node, win.from, win.to, win.maxRows, args.param, args.include_data === true || args.include_data === 'true')
-          sections.push(one.hookText ? `${one.text}\n${one.hookText}` : one.text)
-          statsOut.push({ nodeId: node.id, stats: one.stats, truncated: one.truncated })
-        }
-        catch (err) {
-          sections.push(`■ ${node.name}(id=${node.id})\n  取数失败:${err instanceof Error ? err.message : String(err)}`)
-        }
-      }
-      return {
-        mode: 'inline',
-        text: `MES 历史取数(内联同步,${vis.nodes.length} 个点位,窗口 ${shortTs(win.from)} ~ ${shortTs(win.to)}):\n${sections.join('\n')}\n\n说明:以上为统计摘要与 ≤3 行采样;MES 原文不进入对话。向量/图像/记录点位按各自格式呈现,已配置数据钩子(dataHook)的点位会附处理摘要与产物清单(文件落 <数据根>/mes-artifacts/<点位id>/)。需要标量/向量全量行请用更大 max_rows(> ${MES_SYNC_INLINE_MAX_ROWS})走异步数据集,再用 mes_dataset_read 读。`,
-        data: { stats: statsOut },
-      }
-    }
-
-    // 模式三:异步数据集(行数 > MES_SYNC_INLINE_MAX_ROWS;进程内异步,绝不进调度循环;
-    // requestHook 覆盖在此同样生效——合并进作业用的 driverConfig)
-    const jobIds: string[] = []
-    const datasetIds: string[] = []
-    const lines: string[] = []
-    for (const node of vis.nodes) {
-      let effCfg: Record<string, unknown>
-      try {
-        effCfg = await configWithRequestHook(node, args.param)
-      }
-      catch (err) {
-        lines.push(`- ${node.name}(${node.id}):requestHook 失败,作业未创建(${err instanceof Error ? err.message : String(err)})`)
-        continue
-      }
-      const run = node.lineId ? getActiveLineRun(node.lineId) : null
-      const { jobId, datasetId } = d.store.createFetchJob({
-        nodeId: node.id,
-        fromIso: win.from,
-        toIso: win.to,
-        maxRows: win.maxRows,
-        agentId,
-        lineId: node.lineId,
-        nodeName: node.name,
-        driverConfig: effCfg,
-        dictionary: mesDictionaryOfNode(node.id, node.driverConfig as Record<string, unknown>),
-        nodeMeta: {
-          unit: node.unit,
-          min: node.min,
-          max: node.max,
-          description: String(node.driverConfig.desc ?? ''),
-          semantics: String(node.driverConfig.semantics ?? ''),
-          format: historyFormatOf(node.driverConfig as Record<string, unknown>),
-        },
-        context: run
-          ? { lineId: run.lineId, productId: run.productId, recipeId: run.recipeId, runId: run.runId }
-          : { lineId: node.lineId },
-      })
-      jobIds.push(jobId)
-      datasetIds.push(datasetId)
-      lines.push(`- ${node.name}(${node.id}):job_id=${jobId} dataset_id=${datasetId} status=running`)
-    }
-    return {
-      mode: 'async',
-      text: `已创建 ${lines.length} 个异步取数作业(窗口 ${shortTs(win.from)} ~ ${shortTs(win.to)},max_rows=${win.maxRows}):\n${lines.join('\n')}\n\n勿轮询;未完成先做别的,用 mes_datasets 查状态,完成后 mes_dataset_read(dataset_id, mode=stats/rows) 读内容。`,
-      data: { job_ids: jobIds, dataset_ids: datasetIds },
-    }
-  }
-
-  // ---------- 离线导出(指定目录 + manifest/README 语义清单) ----------
-
-  /** 安全子路径:只允许落在 root 内(拒绝 ../、绝对路径逃逸、盘符切换) */
-  function resolveUnderRoot(root: string, folder: string, fallback: string): { ok: true, dir: string } | { ok: false, text: string } {
-    const base = resolve(root)
-    const raw = String(folder ?? '').trim()
-    if (!raw) return { ok: true, dir: join(base, fallback) }
-    const target = resolve(base, raw)
-    if (target !== base && !target.startsWith(`${base}${sep}`)) {
-      return {
-        ok: false,
-        text: `导出目录被拒:folder=${raw} 越出允许根目录 ${base}(只接受相对路径;如需自定义根目录,请由管理员设置环境变量 AW_MES_EXPORT_ROOT)。`,
-      }
-    }
-    return { ok: true, dir: target }
-  }
-
-  function safeSeg(value: string): string {
-    return value.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80) || 'node'
-  }
-
-  function writeChunk(fd: number, text: string): void {
-    const buf = Buffer.from(text, 'utf8')
-    let off = 0
-    while (off < buf.length) off += writeSync(fd, buf, off, buf.length - off)
-  }
-
-  /**
-   * 把可见 MES 点位的历史原样导出到目录(流式写盘):
-   *   scalar → data.csv(ts,value)
-   *   vector → data.csv(宽表 ts,v0..vN)+ manifest 里的逐点语义
-   *   image  → frames.jsonl(元数据)+ frames/*.png
-   *   table/event → records.jsonl
-   * 每个导出目录都写 manifest.json + README.md(字段含义/单位/量程/产线批次上下文),
-   * Agent 与离线分析器都能直接读懂,不需要回读平台。
-   */
-  async function exportData(agentId: string, args: MesExportArgs): Promise<MesToolResult & { dir?: string, manifestPath?: string, rows?: number }> {
-    const vis = await resolveVisibleIds(agentId, args.ids)
-    if (!vis.ok) return { text: vis.text, isError: true }
-    const from = String(args.from ?? '').trim()
-    const to = String(args.to ?? '').trim()
-    if (!from || !to) return { text: 'mes_export 需要 from/to(ISO)历史窗口;当前值快照请用 mes_fetch。', isError: true }
-    const fromMs = Date.parse(from)
-    const toMs = Date.parse(to)
-    if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return { text: 'from/to 必须是合法 ISO 时间戳。', isError: true }
-    if (fromMs >= toMs) return { text: `时间窗无效:from(${from}) 必须早于 to(${to})。`, isError: true }
-    if (toMs - fromMs > MES_WINDOW_MAX_MS) {
-      return { text: `时间窗被拒:超过 7 天上限。请拆成 ≤7 天的分段导出。`, isError: true }
-    }
-    const rawMax = args.max_rows == null || args.max_rows === '' ? MES_MAX_ROWS_CAP : Math.round(Number(args.max_rows))
-    if (!Number.isFinite(rawMax) || rawMax < 1) return { text: 'max_rows 必须为 ≥1 的整数。', isError: true }
-    const maxRows = Math.min(rawMax, MES_EXPORT_MAX_ROWS)
-    if (!mesFetchRateCheck(agentId, d.nowMs())) {
-      return { text: `导出过于频繁:每 60 秒最多 ${MES_RATE_MAX_CALLS} 次。请稍后再试。`, isError: true }
-    }
-
-    const root = process.env.AW_MES_EXPORT_ROOT
-      ? resolve(process.env.AW_MES_EXPORT_ROOT)
-      : join(ensureDataDir(), 'mes-exports')
-    const exportId = `mesexp-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}-${randomUUID().slice(0, 6)}`
-    const where = resolveUnderRoot(root, String(args.folder ?? ''), exportId)
-    if (!where.ok) return { text: where.text, isError: true }
-    const dir = where.dir
-    mkdirSync(dir, { recursive: true })
-
-    const title = String(args.title ?? '').trim() || `MES 数据导出 ${exportId}`
-    const note = String(args.note ?? '').trim()
-    const manifestNodes: Array<Record<string, unknown>> = []
-    const failures: string[] = []
-    const scalarFiles: Array<{ nodeName: string, nodeId: string, file: string }> = []
-    let totalRows = 0
-
-    for (const node of vis.nodes) {
-      const cfg = node.driverConfig as Record<string, unknown>
-      const format = historyFormatOf(cfg)
-      const nodeDir = join(dir, safeSeg(node.id))
-      try {
-        mkdirSync(nodeDir, { recursive: true })
-        const driver = d.resolveDriver(node.driver)
-        if (typeof driver.fetchHistory !== 'function') {
-          failures.push(`${node.name}(${node.id}):驱动 ${node.driver} 无历史原语`)
-          continue
-        }
-        const effCfg = await configWithRequestHook(node, args.param)
-        const run = node.lineId ? getActiveLineRun(node.lineId) : null
-        let dictionary = mesDictionaryOfNode(node.id, cfg)
-        let rows = 0
-        let truncated = false
-        let dim = 0
-        let dimDrift = 0
-        let skipped = 0
-        let frameSaved = 0
-        let frameSkipped = 0
-        let fd: number | null = null
-        let headerWritten = false
-        let columns: string[] = []
-        let fileRel = ''
-        const jsonl: string[] = []
-
-        if (format === 'image') {
-          mkdirSync(join(nodeDir, 'frames'), { recursive: true })
-        }
-        else {
-          fd = openSync(join(nodeDir, format === 'table' || format === 'event' ? 'records.jsonl' : 'data.csv'), 'w')
-        }
-
-        const result = await driver.fetchHistory({
-          driverConfig: effCfg,
-          fromIso: from,
-          toIso: to,
-          maxRows,
-          onRows: (batch) => {
-            if (!Array.isArray(batch)) return
-            for (const r of batch) {
-              if (rows >= maxRows) {
-                truncated = true
-                break
-              }
-              const ts = String(r?.ts ?? '')
-              if (format === 'vector') {
-                if (!Array.isArray(r?.values) || r.values.length === 0) {
-                  skipped++
-                  continue
-                }
-                if (!headerWritten) {
-                  dim = r.values.length
-                  columns = ['ts', ...Array.from({ length: dim }, (_, i) => `v${i}`)]
-                  writeChunk(fd!, `${columns.join(',')}\r\n`)
-                  headerWritten = true
-                }
-                if (r.values.length !== dim) dimDrift++
-                const cells = [ts]
-                for (let i = 0; i < dim; i++) {
-                  const v = r.values[i]
-                  cells.push(Number.isFinite(v) ? String(v) : '')
-                }
-                writeChunk(fd!, `${cells.join(',')}\r\n`)
-                rows++
-                continue
-              }
-              if (format === 'image') {
-                if (typeof r?.data !== 'string' || r.data.trim() === '') {
-                  skipped++
-                  continue
-                }
-                if (frameSaved >= MES_EXPORT_MAX_FRAMES) {
-                  frameSkipped++
-                  truncated = true
-                  continue
-                }
-                const mime = typeof r.mime === 'string' && r.mime.includes('/') ? r.mime : 'image/png'
-                const ext = mime.includes('jpeg') ? 'jpg' : mime.includes('webp') ? 'webp' : 'png'
-                const name = `frames/${String(frameSaved).padStart(5, '0')}-${ts.replace(/[:.]/g, '-')}.${ext}`
-                try {
-                  writeFileSync(join(nodeDir, name), Buffer.from(r.data, 'base64'))
-                  jsonl.push(JSON.stringify({ ts, mime, file: name, ...(r.record !== null && typeof r.record === 'object' ? { record: r.record } : {}) }))
-                  frameSaved++
-                  rows++
-                }
-                catch (imgErr) {
-                  skipped++
-                  jsonl.push(JSON.stringify({ ts, mime, error: imgErr instanceof Error ? imgErr.message : String(imgErr) }))
-                }
-                continue
-              }
-              if (format === 'table' || format === 'event') {
-                if (r?.record === null || r?.record === undefined) {
-                  skipped++
-                  continue
-                }
-                jsonl.push(JSON.stringify({ ts, record: r.record }))
-                rows++
-                continue
-              }
-              if (typeof r?.value !== 'number' || !Number.isFinite(r.value)) {
-                skipped++
-                continue
-              }
-              if (!headerWritten) {
-                columns = ['ts', 'value']
-                writeChunk(fd!, `${columns.join(',')}\r\n`)
-                headerWritten = true
-              }
-              writeChunk(fd!, `${ts},${r.value}\r\n`)
-              rows++
-            }
-          },
-        })
-        if (result?.dictionary && result.dictionary.length > 0) {
-          dictionary = result.dictionary
-          cacheDictionary(node.id, dictionary)
-        }
-        if (result && result.complete === false) truncated = true
-        if (format === 'image' || format === 'table' || format === 'event') {
-          writeFileSync(join(nodeDir, 'records.jsonl'), `${jsonl.join('\n')}${jsonl.length > 0 ? '\n' : ''}`, 'utf8')
-          fileRel = `${safeSeg(node.id)}/records.jsonl`
-        }
-        else {
-          if (!headerWritten) {
-            columns = format === 'vector' ? ['ts'] : ['ts', 'value']
-            writeChunk(fd!, `${columns.join(',')}\r\n`)
-            headerWritten = true
-          }
-          fileRel = `${safeSeg(node.id)}/data.csv`
-        }
-        if (fd != null) {
-          closeSync(fd)
-          fd = null
-        }
-        if (format === 'scalar') scalarFiles.push({ nodeName: node.name, nodeId: node.id, file: fileRel })
-        totalRows += rows
-        manifestNodes.push({
-          id: node.id,
-          name: node.name,
-          line_id: node.lineId,
-          format,
-          unit: node.unit,
-          range: { min: node.min, max: node.max },
-          description: String(cfg.desc ?? ''),
-          semantics: String(cfg.semantics ?? ''),
-          file: fileRel,
-          columns,
-          rows,
-          ...(format === 'vector' ? { vector: { dim, dimension_drift_rows: dimDrift } } : {}),
-          ...(format === 'image' ? { frames: { saved: frameSaved, skipped: frameSkipped } } : {}),
-          skipped_rows: skipped,
-          truncated,
-          fields: dictionary,
-          context: run ? { line_id: run.lineId, product_id: run.productId, recipe_id: run.recipeId, run_id: run.runId } : { line_id: node.lineId },
-        })
-      }
-      catch (err) {
-        failures.push(`${node.name}(${node.id}):${err instanceof Error ? err.message : String(err)}`)
-      }
-    }
-
-    // 多标量节点按时间对齐的宽表(默认生成;纯时间戳交集,不做插值)
-    let mergedFile: string | null = null
-    const mergeEnabled = !(args.merge === false || args.merge === 'false')
-    if (mergeEnabled && scalarFiles.length > 1) {
-      try {
-        const series = scalarFiles.map((s) => {
-          const map = new Map<string, number>()
-          const raw = readFileSync(join(dir, s.file), 'utf8')
-          for (const line of raw.split(/\r?\n/).slice(1)) {
-            const [ts, v] = line.split(',')
-            if (ts && v !== undefined && Number.isFinite(Number(v))) map.set(ts, Number(v))
-          }
-          return { ...s, map }
-        })
-        const times = [...new Set(series.flatMap(s => [...s.map.keys()]))].sort()
-        const header = ['time', ...series.map(s => `${s.nodeName}(${s.nodeId})`)]
-        const lines = [header.join(',')]
-        for (const ts of times) lines.push([ts, ...series.map(s => s.map.get(ts) ?? '')].join(','))
-        writeFileSync(join(dir, 'merged.csv'), `${lines.join('\n')}\n`, 'utf8')
-        mergedFile = join(dir, 'merged.csv')
-      }
-      catch { /* merge 失败不影响单节点导出 */ }
-    }
-
-    const manifest = {
-      schema: 'aw.mes-export/1',
-      export_id: exportId,
-      created_at: new Date().toISOString(),
-      title,
-      note,
-      window: { from, to, from_ms: fromMs, to_ms: toMs },
-      directory: dir,
-      nodes: manifestNodes,
-      merged_file: mergedFile,
-      totals: { nodes: manifestNodes.length, rows: totalRows, failed_nodes: failures.length },
-      usage: 'data.csv 首行为列名(ts=时间,v0..vN=向量点位);records.jsonl 每行一条记录;image 格式的像素在 frames/ 下,records.jsonl 是对应元数据。字段含义/单位/量程见 nodes[].fields(向量逐点语义在 fields[].points);批次归属见 nodes[].context。',
-    }
-    const manifestPath = join(dir, 'manifest.json')
-    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
-
-    const readme: string[] = [
-      `# ${title}`,
-      '',
-      `- 导出时间: ${new Date().toISOString()}`,
-      `- 时间窗: ${from} ~ ${to}`,
-      `- 导出目录: ${dir}`,
-      `- 说明: ${note || '(无)'}`,
-      '',
-      '## 文件与字段',
-      '',
-    ]
-    for (const n of manifestNodes) {
-      readme.push(`### ${String(n.name)} (${String(n.id)})`)
-      readme.push(`- 格式: ${String(n.format)};文件: ${String(n.file)};行数: ${String(n.rows)}`)
-      readme.push(`- 单位: ${String(n.unit || '-')};量程: ${JSON.stringify(n.range)}`)
-      if (n.semantics) readme.push(`- 物理意义: ${String(n.semantics)}`)
-      const fields = Array.isArray(n.fields) ? n.fields as DcwFieldDef[] : []
-      const dict = formatDictionary(fields, '  ')
-      if (dict) readme.push(dict)
-      readme.push('')
-    }
-    if (mergedFile) readme.push(`多参数对齐宽表: ${mergedFile}(列名=节点名(节点id);仅对齐相同时间戳,不插值)`, '')
-    if (failures.length > 0) readme.push('## 失败节点', '', ...failures.map(f => `- ${f}`), '')
-    writeFileSync(join(dir, 'README.md'), `${readme.join('\n')}\n`, 'utf8')
-
-    const lines = manifestNodes.map(n => `- ${String(n.name)}(${String(n.id)}) [${String(n.format)}] ${String(n.rows)} 行 → ${String(n.file)}`)
-    const failText = failures.length > 0 ? `\n失败节点(${failures.length}):\n${failures.map(f => `  - ${f}`).join('\n')}` : ''
-    return {
-      isError: failures.length > 0,
-      dir,
-      manifestPath,
-      rows: totalRows,
-      text: `MES 数据已导出(${manifestNodes.length}/${vis.nodes.length} 个点位,共 ${totalRows} 行):\n${lines.join('\n')}${mergedFile ? `\n- 多参数宽表: ${mergedFile}` : ''}${failText}\n\n目录: ${dir}\n语义清单: ${manifestPath}\n说明: README.md\n\n离线分析请直接读取上述文件;在线继续取数用 mes_fetch/mes_dataset_read。`,
-    }
-  }
-
-  return { catalog, fetch, exportData }
-}
-
-export type MesController = ReturnType<typeof createMesController>
+/**
+ * MES 取数控制器(Agent 工具后端)—— mes-rest 点位目录 + 历史取数编排。
+ *
+ * 护栏全部**代码级**(不是提示词):绑线授权过滤、时间窗 ≤7 天、maxRows ≤5000、
+ * 每 agent 每 60s ≤6 次 fetch;数据原文不进 prompt —— 文本只给 stats + ≤3 行采样,
+ * 行级原文只落 CSV 数据集(mes-datasets)。
+ *
+ * 取数三模式:
+ *   无 from/to                     → 当前值快照(driver.read 内联直读);
+ *   from/to 且 maxRows ≤ 2000      → 同步 fetchHistory 内联返回(缓冲截断保护);
+ *   其余(maxRows > 2000)         → createFetchJob 异步落 CSV,回 job_id/dataset_id。
+ */
+import { randomUUID } from 'node:crypto'
+import { closeSync, mkdirSync, openSync, readFileSync, writeFileSync, writeSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import { getActiveLineRun } from '../dcw/line-run'
+import { resolveDcwDriver } from '../dcw/drivers'
+import type { DcwFieldDef, DcwHistoryFormat as MesHistoryFormat } from '../dcw/drivers/shared'
+import { historyFormatOf, normalizeMesDictionary } from '../dcw/drivers/mes-rest'
+import type { MesHistoryDriver, MesDatasetStatsView, MesDatasetStore } from './mes-datasets'
+import { getMesDatasets } from './mes-datasets'
+import { mesDataHookCode, mesRequestHookCode, runMesDataHook, runMesRequestHook, saveMesImageArtifact } from './mes-hook'
+import type { MesHookArtifact, MesHookData } from './mes-hook'
+
+/** mes-rest 驱动 kind(并行工作流收编进 DcwDriverKind 联合;此处按字符串经注册表解析,不 import 驱动实现) */
+export const MES_REST_DRIVER_KIND = 'mes-rest'
+
+// ============================================================
+// 护栏常量(单一事实源;测试直接引用)
+// ============================================================
+
+/** 历史窗口上限:7 天 */
+export const MES_WINDOW_MAX_MS = 7 * 24 * 3_600_000
+/** 单次取数行数硬上限 */
+export const MES_MAX_ROWS_CAP = 5000
+/** 同步内联返回的行数上限(超过走异步数据集) */
+export const MES_SYNC_INLINE_MAX_ROWS = 2000
+/** 频次限流:窗口与次数(每 agent) */
+export const MES_RATE_WINDOW_MS = 60_000
+export const MES_RATE_MAX_CALLS = 6
+/** max_rows 缺省值 */
+export const MES_DEFAULT_MAX_ROWS = 500
+/** 离线导出单次行数上限(CSV/JSONL 流式写盘;比在线取数宽,仍防磁盘失控) */
+export const MES_EXPORT_MAX_ROWS = 200_000
+/** 离线导出图像帧上限(单次) */
+export const MES_EXPORT_MAX_FRAMES = 500
+
+// ============================================================
+// 频次限流(进程内内存计数;Map<agentId, 时间戳[]>)
+// ============================================================
+
+const fetchCallStamps = new Map<string, number[]>()
+
+/** 记一次 fetch 并判定是否放行(滑动 60s 窗 ≤6 次;超限不记账) */
+export function mesFetchRateCheck(agentId: string, nowMs = Date.now()): boolean {
+  const stamps = (fetchCallStamps.get(agentId) ?? []).filter(t => nowMs - t < MES_RATE_WINDOW_MS)
+  if (stamps.length >= MES_RATE_MAX_CALLS) {
+    fetchCallStamps.set(agentId, stamps)
+    return false
+  }
+  stamps.push(nowMs)
+  fetchCallStamps.set(agentId, stamps)
+  return true
+}
+
+/** 清空限流账(测试用) */
+export function mesFetchRateReset(): void {
+  fetchCallStamps.clear()
+}
+
+// ============================================================
+// 节点/依赖(结构化注入;缺省接真实服务,测试注入假件不联网)
+// ============================================================
+
+export interface MesNodeLike {
+  id: string
+  name: string
+  driver: string
+  lineId: string
+  unit: string
+  min: number
+  max: number
+  enabled: boolean
+  driverConfig: Record<string, string | number | boolean>
+}
+
+export interface MesControllerDeps {
+  /** 数据集服务(异步取数账本;缺省 getMesDatasets()) */
+  store: Pick<MesDatasetStore, 'createFetchJob'>
+  /** 全量 dcw 节点(缺省 dcw-node.repo) */
+  nodes: () => MesNodeLike[] | Promise<MesNodeLike[]>
+  /** 调用者可见节点(绑线过滤:dcw 绑定集;缺省 node-bindings.repo) */
+  boundNodeIds: (agentId: string) => Set<string> | Promise<Set<string>>
+  /** 驱动解析(缺省 dcw 注册表) */
+  resolveDriver: (kind: string) => MesHistoryDriver
+  nowMs: () => number
+}
+
+/** 缺省依赖:重模块(dcw 仓储/绑线仓储)经动态 import 引入,保持本模块可被 tsx 测试轻量直跑 */
+function defaultDeps(): MesControllerDeps {
+  return {
+    store: new Proxy({} as Pick<MesDatasetStore, 'createFetchJob'>, {
+      get: (_t, prop) => {
+        const store = getMesDatasets() as unknown as Record<string | symbol, unknown>
+        const v = store[prop]
+        return typeof v === 'function' ? (v as (...a: unknown[]) => unknown).bind(store) : v
+      },
+    }),
+    nodes: async () => {
+      const { getDcwNodeRepo } = await import('../dcw/dcw-node.repo')
+      return getDcwNodeRepo().all()
+    },
+    boundNodeIds: async (agentId) => {
+      // 权限模型 v2:dcw 绑定(存量)∪ 绑定配方内的参数节点(kind='recipe' 的配方可见节点)
+      const { getAgentNodeBindingRepo } = await import('../agents/node-bindings.repo')
+      const { getDcwController } = await import('../dcw/dcw-controller')
+      const bindings = getAgentNodeBindingRepo().byAgent(agentId)
+      const ids = new Set(bindings.filter(b => b.kind === 'dcw').map(b => b.nodeId))
+      const recipeIds = new Set(bindings.filter(b => b.kind === 'recipe').map(b => b.nodeId))
+      if (recipeIds.size > 0) {
+        for (const r of getDcwController().listRecipes()) {
+          if (!recipeIds.has(r.id)) continue
+          for (const p of r.params) ids.add(p.nodeId)
+        }
+      }
+      return ids
+    },
+    resolveDriver: kind => resolveDcwDriver(kind as Parameters<typeof resolveDcwDriver>[0]),
+    nowMs: () => Date.now(),
+  }
+}
+
+export type MesCatalogEntry = {
+  id: string
+  name: string
+  lineId: string
+  unit: string
+  min: number
+  max: number
+  desc: string
+  readable: boolean
+  writable: boolean
+  historyable: boolean
+  /** 历史格式(scalar/vector/image/table/event;historyMap 未配置时 scalar) */
+  format: MesHistoryFormat
+  /** 已配置数据下沉 hook(dataHook) */
+  hooked: boolean
+  enabled: boolean
+  /** 字段级数据字典(响应缓存 ∪ 节点静态配置;无则空数组) */
+  fields: DcwFieldDef[]
+}
+
+// ============================================================
+// 字段字典缓存(响应返回 → 后续 catalog/导出复用)
+// ============================================================
+
+const dictionaryCache = new Map<string, DcwFieldDef[]>()
+const DICTIONARY_CACHE_MAX = 200
+
+function cacheDictionary(nodeId: string, fields: DcwFieldDef[] | undefined): void {
+  if (!fields || fields.length === 0) return
+  dictionaryCache.delete(nodeId)
+  dictionaryCache.set(nodeId, fields)
+  while (dictionaryCache.size > DICTIONARY_CACHE_MAX) {
+    const oldest = dictionaryCache.keys().next().value
+    if (oldest === undefined) break
+    dictionaryCache.delete(oldest)
+  }
+}
+
+/** 节点静态字典(driverConfig.dictionary / fieldDictionary 的 JSON 文本) */
+function configuredDictionary(cfg: Record<string, unknown>): DcwFieldDef[] {
+  for (const key of ['dictionary', 'fieldDictionary', 'fields']) {
+    const raw = cfg[key]
+    if (raw === undefined || raw === null || String(raw).trim() === '') continue
+    try {
+      const parsed = typeof raw === 'string' ? JSON.parse(raw) as unknown : raw
+      const fields = normalizeMesDictionary(parsed)
+      if (fields.length > 0) return fields
+    }
+    catch { /* 坏配置不击穿目录;由驱动测试报错 */ }
+  }
+  return []
+}
+
+/** 节点有效字典:响应缓存优先(实时真相),否则静态配置 */
+export function mesDictionaryOfNode(nodeId: string, cfg: Record<string, unknown>): DcwFieldDef[] {
+  return dictionaryCache.get(nodeId) ?? configuredDictionary(cfg)
+}
+
+/** 字典一行摘要(字段名(标签,单位;量程;点数)) */
+export function fieldSummaryOf(fields: DcwFieldDef[]): string {
+  return fields.slice(0, 8).map((f) => {
+    const bits = [f.label, f.unit, f.min != null || f.max != null ? `${f.min ?? '-∞'}~${f.max ?? '+∞'}` : '', f.points?.length ? `${f.points.length} 点` : '']
+      .filter(Boolean)
+    return bits.length > 0 ? `${f.field}(${bits.join(',')})` : f.field
+  }).join('; ')
+}
+
+/** 字段字典 → 多行可读文本(Agent 直接引用;含单位/量程/物理意义/逐点语义) */
+export function formatDictionary(fields: DcwFieldDef[], indent = '  '): string {
+  if (fields.length === 0) return ''
+  const pointLine = (f: DcwFieldDef): string => {
+    const pts = f.points ?? []
+    if (pts.length === 0) return ''
+    const head = pts.slice(0, 6).map(p => `${p.index ?? '?'}=${p.label ?? p.field}${p.unit ? `(${p.unit})` : ''}`).join(', ')
+    return `; 点位 ${pts.length} 个: ${head}${pts.length > 6 ? ', …' : ''}`
+  }
+  const lines = fields.slice(0, 24).map((f) => {
+    const meta = [
+      f.label && f.label !== f.field ? `标签 ${f.label}` : '',
+      f.unit ? `单位 ${f.unit}` : '',
+      f.min != null || f.max != null ? `量程 ${f.min ?? '-∞'}~${f.max ?? '+∞'}` : '',
+      f.kind ? `形态 ${f.kind}` : '',
+    ].filter(Boolean).join(' | ')
+    const desc = f.description ? ` — ${f.description.slice(0, 160)}` : ''
+    return `${indent}- ${f.field}${meta ? ` [${meta}]` : ''}${desc}${pointLine(f)}`
+  })
+  return `字段字典(${fields.length} 个字段,来自 MES 响应/节点配置):\n${lines.join('\n')}${fields.length > 24 ? `\n${indent}(仅显示前 24 个字段)` : ''}`
+}
+
+/** 目录条目合成:desc/readMap/writeMap/historyMap 均来自 driverConfig(数据驱动,零硬编码) */
+export function mesCatalogEntryOf(n: MesNodeLike): MesCatalogEntry {
+  const cfg = n.driverConfig ?? {}
+  return {
+    id: n.id,
+    name: n.name,
+    lineId: n.lineId ?? '',
+    unit: n.unit ?? '',
+    min: n.min,
+    max: n.max,
+    desc: String(cfg.desc ?? ''),
+    readable: Boolean(cfg.readMap),
+    writable: Boolean(cfg.writeMap),
+    historyable: Boolean(cfg.historyMap),
+    format: historyFormatOf(cfg as Record<string, unknown>),
+    hooked: Boolean(cfg.dataHook),
+    enabled: Boolean(n.enabled),
+    fields: mesDictionaryOfNode(n.id, cfg as Record<string, unknown>),
+  }
+}
+
+// ============================================================
+// 控制器
+// ============================================================
+
+export type MesToolResult = { text: string, isError?: boolean }
+
+export type MesFetchOutcome = MesToolResult & {
+  mode?: 'snapshot' | 'inline' | 'async'
+  data?: {
+    job_ids?: string[]
+    dataset_ids?: string[]
+    stats?: Array<{ nodeId: string, stats: MesDatasetStatsView, truncated: boolean }>
+  }
+}
+
+export interface MesFetchArgs {
+  ids?: unknown
+  from?: string
+  to?: string
+  max_rows?: number | string
+  /** 透传给 requestHook/dataHook 的参数对象(Agent 只传 param,其余交给配置) */
+  param?: unknown
+  /** 内联/快照回包是否附带采样行的实际数组/数值内容(默认 false=只给统计与均值) */
+  include_data?: boolean | string
+}
+
+export interface MesCatalogArgs {
+  q?: string
+  line_id?: string
+  /** 按产品 id 收窄到该产品产线(可选;与 line_id 冲突时拒绝) */
+  product_id?: string
+  /** 按配方 id 收窄到该配方产线(可选;与 line_id 冲突时拒绝) */
+  recipe_id?: string
+  limit?: number | string
+  /** 调用者可读产线集(绑线授权口径);提供时严格过滤(孤儿/越线点位不可见,空集=空目录 fail-closed) */
+  scope_line_ids?: string[]
+}
+
+export interface MesExportArgs {
+  ids?: unknown
+  from?: string
+  to?: string
+  max_rows?: number | string
+  /** 透传给 requestHook 的调用参数 */
+  param?: unknown
+  /** 导出子目录(相对 <数据根>/mes-exports;绝对路径须落在 AW_MES_EXPORT_ROOT 内) */
+  folder?: string
+  title?: string
+  note?: string
+  /** 标量节点是否生成按时间对齐的 merged.csv(缺省 true) */
+  merge?: boolean | string
+}
+
+export function createMesController(deps: Partial<MesControllerDeps> = {}) {
+  const d: MesControllerDeps = { ...defaultDeps(), ...deps }
+
+  // ---------- 目录 ----------
+
+  /** mes-rest 点位目录(q 对 name/desc 子串过滤;line_id 精确过滤;limit 缺省 20;
+   *  scope_line_ids 提供时按调用者可读产线严格过滤——跨产线点位与孤儿(未分配)点位不可见) */
+  async function catalog(args: MesCatalogArgs = {}): Promise<MesToolResult & { entries: MesCatalogEntry[], total: number }> {
+    const all = await d.nodes()
+    let mes = all.filter(n => n.driver === MES_REST_DRIVER_KIND).map(mesCatalogEntryOf)
+    if (Array.isArray(args.scope_line_ids)) {
+      const scope = new Set(args.scope_line_ids)
+      mes = mes.filter(e => e.lineId !== '' && scope.has(e.lineId))
+    }
+    const total = mes.length
+    let lineId = String(args.line_id ?? '').trim()
+    const productId = String(args.product_id ?? '').trim()
+    if (productId) {
+      const { getDcwProductRepo } = await import('../dcw/dcw-product.repo')
+      const product = getDcwProductRepo().byId(productId)
+      if (!product) return { text: `产品 ${productId} 不存在。`, isError: true, entries: [], total: 0 }
+      if (lineId && product.lineId !== lineId) return { text: `产品 ${productId} 归属产线 ${product.lineId},与 line_id=${lineId} 不一致。`, isError: true, entries: [], total: 0 }
+      lineId = product.lineId
+    }
+    const recipeId = String(args.recipe_id ?? '').trim()
+    if (recipeId) {
+      const { getDcwController } = await import('../dcw/dcw-controller')
+      const recipe = getDcwController().listRecipes().find(r => r.id === recipeId)
+      if (!recipe) return { text: `配方 ${recipeId} 不存在。`, isError: true, entries: [], total: 0 }
+      if (lineId && recipe.lineId !== lineId) return { text: `配方 ${recipeId} 归属产线 ${recipe.lineId},与 line_id=${lineId} 不一致。`, isError: true, entries: [], total: 0 }
+      lineId = recipe.lineId
+    }
+    if (lineId) mes = mes.filter(e => e.lineId === lineId)
+    const q = String(args.q ?? '').trim().toLowerCase()
+    if (q) mes = mes.filter(e => e.name.toLowerCase().includes(q) || e.desc.toLowerCase().includes(q))
+    const limit = Math.min(Math.max(Math.round(Number(args.limit)) || 20, 1), 100)
+    const shown = mes.slice(0, limit)
+
+    const cap = (e: MesCatalogEntry): string => {
+      const hist = e.historyable ? (e.format !== 'scalar' ? `史·${e.format}` : '史') : null
+      const ab = [e.readable ? '读' : null, e.writable ? '写' : null, hist, e.hooked ? '钩子' : null].filter(Boolean)
+      return ab.length > 0 ? ab.join('/') : '无能力位'
+    }
+    const body = shown.map((e) => {
+      const fields = e.fields.length > 0 ? ` | 字段: ${fieldSummaryOf(e.fields)}` : ''
+      return `- ${e.name}(id=${e.id}) | 产线 ${e.lineId || '未分配'} | 单位 ${e.unit || '-'} | 量程 ${e.min}~${e.max} | 能力 ${cap(e)}${e.enabled ? '' : ' [停用]'}${e.desc ? ` | ${e.desc.slice(0, 80)}` : ''}${fields}`
+    })
+    const more = mes.length - shown.length
+    const text = `MES REST 点位目录(共 ${total} 个${lineId ? `,产线 ${lineId}` : ''}${q ? `,关键字「${args.q}」` : ''};显示 ${shown.length} 条):\n${body.join('\n') || '(无匹配点位)'}${more > 0 ? `\n(另有 ${more} 条未显示,可收紧 q/line_id 或调大 limit≤100)` : ''}\n\n说明:能力 读=可读当前值,写=可写设定值,史=可取历史(史·vector=每时间点检测向量,史·image=图像帧,史·table/event=记录流),钩子=已配 dataHook(取数后自动做下沉处理并回传摘要与产物)。字段级语义来自 MES 响应 dictionaryPath 或节点 driverConfig.dictionary;首次 mes_fetch 后缓存,后续目录可直接看到字段标签/单位/点位。历史取数用 mes_fetch(ids=[点位id], from, to, max_rows, param?);需要落盘到目录做离线分析用 mes_export。`
+    return { text, entries: shown, total }
+  }
+
+  // ---------- 取数 ----------
+
+  /** 归一 ids + 授权过滤(绑线路径:仅调用者 dcw 绑定的 mes-rest 节点) */
+  async function resolveVisibleIds(agentId: string, rawIds: unknown): Promise<{ ok: true, nodes: MesNodeLike[] } | { ok: false, text: string, isError: true }> {
+    const ids = Array.isArray(rawIds) ? [...new Set(rawIds.map(x => String(x ?? '').trim()).filter(Boolean))] : []
+    if (ids.length === 0) return { ok: false, text: 'ids 必填:目标 mes-rest 点位 id 数组(catalog 输出的 id;至少 1 个)。', isError: true }
+    const all = await d.nodes()
+    const bound = await d.boundNodeIds(agentId)
+    const mesById = new Map(all.filter(n => n.driver === MES_REST_DRIVER_KIND).map(n => [n.id, n]))
+    const picked: MesNodeLike[] = []
+    const missing: string[] = []
+    const notAllowed: string[] = []
+    for (const id of ids) {
+      const n = mesById.get(id)
+      if (!n) {
+        missing.push(id)
+        continue
+      }
+      if (!bound.has(id)) {
+        notAllowed.push(id)
+        continue
+      }
+      picked.push(n)
+    }
+    if (missing.length > 0 || notAllowed.length > 0) {
+      const allowed = [...bound]
+        .map(id => mesById.get(id))
+        .filter((n): n is MesNodeLike => !!n && n.driver === MES_REST_DRIVER_KIND)
+      const parts: string[] = []
+      if (missing.length > 0) parts.push(`不存在或不是 mes-rest 点位:${missing.join(', ')}`)
+      if (notAllowed.length > 0) parts.push(`无权访问(须为你绑定的数控节点):${notAllowed.join(', ')}`)
+      return {
+        ok: false,
+        text: `取数被拒:${parts.join(';')}。你有权取数的 mes-rest 点位:${allowed.map(n => `${n.name}(${n.id})`).join(', ') || '(无)'}。`,
+        isError: true,
+      }
+    }
+    return { ok: true, nodes: picked }
+  }
+
+  /** 时间窗/行数护栏归一(代码级;返回错误文本或归一值) */
+  function normalizeWindow(args: MesFetchArgs): { ok: true, from?: string, to?: string, maxRows: number } | { ok: false, text: string, isError?: true } {
+    const from = String(args.from ?? '').trim()
+    const to = String(args.to ?? '').trim()
+    if ((from && !to) || (!from && to)) {
+      return { ok: false, text: 'from/to 必须成对提供(历史取数),或都不传(当前值快照模式)。' }
+    }
+    if (from && to) {
+      const fromMs = Date.parse(from)
+      const toMs = Date.parse(to)
+      if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return { ok: false, text: 'from/to 必须是合法 ISO 时间戳。' }
+      if (fromMs >= toMs) return { ok: false, text: `时间窗无效:from(${from}) 必须早于 to(${to})。` }
+      if (toMs - fromMs > MES_WINDOW_MAX_MS) {
+        return { ok: false, text: `时间窗被拒:窗口 ${(toMs - fromMs) / 3_600_000 / 24} 天超过上限 7 天。请拆成 ≤7 天的分段分批取数。`, isError: true }
+      }
+    }
+    const maxRows = args.max_rows == null || args.max_rows === '' ? MES_DEFAULT_MAX_ROWS : Math.round(Number(args.max_rows))
+    if (!Number.isFinite(maxRows) || maxRows < 1) return { ok: false, text: 'max_rows 必须为 ≥1 的整数。' }
+    if (maxRows > MES_MAX_ROWS_CAP) {
+      return { ok: false, text: `max_rows=${maxRows} 被拒:单次取数上限 ${MES_MAX_ROWS_CAP} 行。请缩小时间窗或分批取数。`, isError: true }
+    }
+    return { ok: true, from: from || undefined, to: to || undefined, maxRows }
+  }
+
+  /** 统计摘要(数值列;均值/采样标准差) */
+  function statsOf(values: number[], firstTs: string | null, lastTs: string | null): MesDatasetStatsView {
+    const n = values.length
+    if (n === 0) return { count: 0, min: null, max: null, mean: null, stddev: null, firstTs: null, lastTs: null }
+    const min = Math.min(...values)
+    const max = Math.max(...values)
+    const mean = values.reduce((a, b) => a + b, 0) / n
+    const stddev = n > 1 ? Math.sqrt(values.reduce((a, b) => a + (b - mean) ** 2, 0) / (n - 1)) : 0
+    return { count: n, min, max, mean, stddev, firstTs, lastTs }
+  }
+
+  const fmtN = (v: number | null | undefined, digits = 3): string =>
+    v == null || !Number.isFinite(v) ? '-' : String(Number(v.toFixed(digits)))
+  const shortTs = (iso: string | null): string => iso && iso.length >= 19 ? iso.slice(5, 19).replace('T', ' ') : (iso ?? '-')
+  const clip = (v: unknown, max: number): string => {
+    const s = typeof v === 'string' ? v : JSON.stringify(v) ?? String(v)
+    return s.length > max ? `${s.slice(0, max)}…` : s
+  }
+
+  // -------- 格式感知取数(行形态全谱;内存硬顶防大payload 拖垮进程) --------
+
+  /** 泛化历史行缓冲的硬顶 */
+  const VECTOR_ELEMENT_CAP = 2_000_000
+  const IMAGE_BASE64_CAP = 16_000_000
+  const RECORD_JSON_CAP = 8_000_000
+  /** image 格式自动落盘帧数上限(其余帧不落盘,回包注明) */
+  const IMAGE_AUTOSAVE_MAX = 20
+
+  interface GenRow { ts: string, value?: number, values?: number[], data?: string, mime?: string, record?: unknown }
+
+  interface GenStats extends MesDatasetStatsView {
+    /** vector:维度(首行长度)与维度不齐行数 */
+    dim?: number
+    dimMismatch?: number
+    /** vector:全体元素均值(比行均值更细) */
+    elementMean?: number
+  }
+
+  /** requestHook 覆盖合并:克隆 driverConfig,把 {path,query,headers} 合入 historyMap JSON */
+  async function configWithRequestHook(node: MesNodeLike, param: unknown): Promise<Record<string, unknown>> {
+    const cfg = { ...(node.driverConfig as Record<string, unknown>) }
+    const hookCode = mesRequestHookCode(cfg as Record<string, unknown>)
+    if (!hookCode) return cfg
+    const overrides = await runMesRequestHook(hookCode, param, { nodeId: node.id })
+    if (overrides.path === undefined && overrides.query === undefined && overrides.headers === undefined) return cfg
+    try {
+      const map = JSON.parse(String(cfg.historyMap ?? '{}')) as Record<string, unknown>
+      if (overrides.path !== undefined) map.path = overrides.path
+      const baseQuery = (map.query !== null && typeof map.query === 'object' && !Array.isArray(map.query) ? map.query : {}) as Record<string, unknown>
+      map.query = { ...baseQuery, ...(overrides.query ?? {}) }
+      const baseHeaders = (map.headers !== null && typeof map.headers === 'object' && !Array.isArray(map.headers) ? map.headers : {}) as Record<string, unknown>
+      if (overrides.headers !== undefined) map.headers = { ...baseHeaders, ...overrides.headers }
+      cfg.historyMap = JSON.stringify(map)
+    }
+    catch (err) {
+      throw new AppError(422, 'MES_HOOK_FAILED', `requestHook 覆盖合并失败(historyMap 非法 JSON):${err instanceof Error ? err.message : String(err)}`)
+    }
+    return cfg
+  }
+
+  /** 向量行统计摘要(行均值序列 stats + 维度 + 全体元素均值) */
+  function vectorStats(rows: GenRow[]): GenStats {
+    const rowMeans = rows.map((r) => {
+      const vs = r.values ?? []
+      return vs.length > 0 ? vs.reduce((a, b) => a + b, 0) / vs.length : NaN
+    }).filter(v => Number.isFinite(v))
+    const all: number[] = []
+    for (const r of rows) if (Array.isArray(r.values)) all.push(...r.values)
+    const base = statsOf(rowMeans, rows[0]?.ts ?? null, rows[rows.length - 1]?.ts ?? null) as GenStats
+    base.dim = Array.isArray(rows[0]?.values) ? rows[0]!.values!.length : undefined
+    base.dimMismatch = base.dim === undefined ? undefined : rows.filter(r => Array.isArray(r.values) && r.values!.length !== base.dim).length
+    base.elementMean = all.length > 0 ? all.reduce((a, b) => a + b, 0) / all.length : undefined
+    return base
+  }
+
+  /** 同步取单节点历史(格式感知:统计+采样+图像落盘+dataHook 下沉处理;原文不回传) */
+  async function inlineFetchNode(node: MesNodeLike, from: string, to: string, maxRows: number, param: unknown, includeData = false): Promise<{
+    text: string
+    stats: MesDatasetStatsView
+    truncated: boolean
+    sample: string[]
+    hookText?: string
+    artifacts: MesHookArtifact[]
+  }> {
+    const cfg = node.driverConfig as Record<string, unknown>
+    const format = historyFormatOf(cfg)
+    const driver = d.resolveDriver(node.driver)
+    if (typeof driver.fetchHistory !== 'function') {
+      return { text: `驱动 ${node.driver} 未提供历史原语(fetchHistory)`, stats: statsOf([], null, null), truncated: true, sample: [], artifacts: [] }
+    }
+    const effCfg = await configWithRequestHook(node, param)
+    const buf: GenRow[] = []
+    let truncated = false
+    let vecElems = 0
+    let imgChars = 0
+    let recChars = 0
+    let memoryHit = ''
+    let dictionary: DcwFieldDef[]
+    const result = await driver.fetchHistory({
+      driverConfig: effCfg,
+      fromIso: from,
+      toIso: to,
+      maxRows,
+      onRows: (batch) => {
+        for (const r of batch ?? []) {
+          if (buf.length >= maxRows) {
+            truncated = true
+            break
+          }
+          const row: GenRow = { ts: String(r?.ts ?? '') }
+          if (typeof r?.value === 'number') row.value = r.value
+          if (Array.isArray(r?.values)) {
+            vecElems += r.values.length
+            if (vecElems > VECTOR_ELEMENT_CAP) {
+              memoryHit = `向量元素总量超过 ${VECTOR_ELEMENT_CAP} 上限`
+              truncated = true
+              break
+            }
+            row.values = r.values as number[]
+          }
+          if (typeof r?.data === 'string') {
+            imgChars += r.data.length
+            if (imgChars > IMAGE_BASE64_CAP) {
+              memoryHit = `图像载荷总量超过 ${Math.round(IMAGE_BASE64_CAP / 1024 / 1024)}MB 上限`
+              truncated = true
+              break
+            }
+            row.data = r.data
+            row.mime = typeof r?.mime === 'string' ? r.mime : 'image/png'
+          }
+          if (r?.record !== undefined && r.record !== null) {
+            let json: string
+            try {
+              json = JSON.stringify(r.record)
+            }
+            catch {
+              continue
+            }
+            recChars += json.length
+            if (recChars > RECORD_JSON_CAP) {
+              memoryHit = `记录载荷总量超过 ${Math.round(RECORD_JSON_CAP / 1024 / 1024)}MB 上限`
+              truncated = true
+              break
+            }
+            row.record = r.record
+          }
+          buf.push(row)
+        }
+      },
+    })
+    if (result?.dictionary && result.dictionary.length > 0) {
+      dictionary = result.dictionary
+      cacheDictionary(node.id, dictionary)
+    }
+    else {
+      dictionary = mesDictionaryOfNode(node.id, cfg)
+    }
+    if (result && result.complete === false) truncated = true
+    if (!truncated && memoryHit) truncated = true
+
+    // 统计与采样(按格式)
+    let stats: GenStats
+    let autosaved: MesHookArtifact[] = []
+    const sample: string[] = []
+    let tableFieldStats = ''
+    if (format === 'vector') {
+      stats = vectorStats(buf)
+      // 空窗口不得生成采样下标(否则 buf[0] undefined → 取数崩溃)
+      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
+      const vecField = dictionary.find(f => f.kind === 'vector' || (f.points?.length ?? 0) > 0)
+      const pointLabel = (i: number): string => {
+        const p = vecField?.points?.[i]
+        return p?.label ?? p?.field ?? `v${i}`
+      }
+      for (const i of idx) {
+        const r = buf[i]!
+        const vs = r.values ?? []
+        const m = vs.length > 0 ? vs.reduce((a, b) => a + b, 0) / vs.length : NaN
+        const valuesTxt = includeData && vs.length > 0
+          ? `,values=[${vs.slice(0, 64).map((v, j) => `${pointLabel(j)}=${Number(v.toFixed(4))}`).join(',')}${vs.length > 64 ? ',…' : ''}]`
+          : ''
+        sample.push(`${shortTs(r.ts)},dim=${vs.length},mean=${fmtN(m)},min=${fmtN(vs.length ? Math.min(...vs) : NaN)},max=${fmtN(vs.length ? Math.max(...vs) : NaN)}${valuesTxt}`)
+      }
+    }
+    else if (format === 'image') {
+      stats = { count: buf.length, min: null, max: null, mean: null, stddev: null, firstTs: buf[0]?.ts ?? null, lastTs: buf[buf.length - 1]?.ts ?? null }
+      // 图像 base64 永不进 prompt:自动落盘(≤20 帧),采样给文件名
+      const saved: MesHookArtifact[] = []
+      for (const [i, r] of buf.entries()) {
+        if (typeof r.data !== 'string') continue
+        if (saved.length >= IMAGE_AUTOSAVE_MAX) break
+        const a = saveMesImageArtifact(node.id, `frame-${String(i).padStart(4, '0')}`, r.data, r.mime ?? 'image/png')
+        if (a) saved.push(a)
+      }
+      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
+      for (const i of idx) {
+        const r = buf[i]!
+        const kb = r.data ? Math.round(r.data.length * 3 / 4 / 1024) : 0
+        const f = saved.find(x => x.name.includes(`frame-${String(i).padStart(4, '0')}`))
+        sample.push(`${shortTs(r.ts)},${r.mime ?? 'image/png'},~${kb}KB${f ? ` → ${f.name}` : ''}`)
+      }
+      autosaved = saved
+    }
+    else if (format === 'table' || format === 'event') {
+      stats = { count: buf.length, min: null, max: null, mean: null, stddev: null, firstTs: buf[0]?.ts ?? null, lastTs: buf[buf.length - 1]?.ts ?? null }
+      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
+      for (const i of idx) {
+        const r = buf[i]!
+        let body: string
+        try {
+          body = JSON.stringify(r.record)
+        }
+        catch {
+          body = '(不可序列化)'
+        }
+        sample.push(`${shortTs(r.ts)},${clip(body ?? '', 120)}`)
+      }
+      // map/多参数行:逐数值字段统计(最多 12 个字段),让 Agent 不必只看 3 行采样
+      const cols = new Map<string, number[]>()
+      for (const r of buf) {
+        if (r.record === null || typeof r.record !== 'object' || Array.isArray(r.record)) continue
+        for (const [k, v] of Object.entries(r.record as Record<string, unknown>)) {
+          if (v === null || v === '' || typeof v === 'boolean') continue
+          const n = Number(v)
+          if (!Number.isFinite(n)) continue
+          const arr = cols.get(k) ?? []
+          arr.push(n)
+          cols.set(k, arr)
+        }
+      }
+      const fieldLines = [...cols.entries()].slice(0, 12).map(([k, vs]) => {
+        const mean = vs.reduce((a, b) => a + b, 0) / vs.length
+        const def = dictionary.find(f => f.field === k)
+        const label = def?.label ? `${def.label}(${k})` : k
+        const unit = def?.unit ? ` ${def.unit}` : ''
+        return `${label}: n=${vs.length} min=${fmtN(Math.min(...vs))} max=${fmtN(Math.max(...vs))} mean=${fmtN(mean)}${unit}`
+      })
+      if (fieldLines.length > 0) {
+        tableFieldStats = `  数值字段统计(${cols.size} 个字段${cols.size > 12 ? ',显示前12' : ''}): ${fieldLines.join(' | ')}`
+      }
+    }
+    else {
+      const values = buf.map(r => r.value).filter((v): v is number => Number.isFinite(v))
+      stats = statsOf(values, buf[0]?.ts ?? null, buf[buf.length - 1]?.ts ?? null)
+      const idx = buf.length > 0 ? [...new Set([0, Math.floor((buf.length - 1) / 2), buf.length - 1])].slice(0, 3) : []
+      for (const i of idx) sample.push(`${shortTs(buf[i]!.ts)},${fmtN(buf[i]!.value ?? NaN)}${includeData ? ` (value=${buf[i]!.value ?? '-'})` : ''}`)
+    }
+
+    const fmtLabel = format === 'scalar' ? `标量` : format === 'vector' ? `向量(dim=${stats.dim ?? '?'})` : format === 'image' ? `图像(${(buf[0]?.mime as string) ?? 'image/png'})` : format === 'table' ? `表格记录` : `事件记录`
+    const statLine = format === 'scalar'
+      ? `  统计:min ${fmtN(stats.min)} / max ${fmtN(stats.max)} / mean ${fmtN(stats.mean)} / stddev ${fmtN(stats.stddev)} ${node.unit}`
+      : format === 'vector'
+        ? `  统计(按行均值):min ${fmtN(stats.min)} / max ${fmtN(stats.max)} / mean ${fmtN(stats.mean)} / stddev ${fmtN(stats.stddev)} ${node.unit};全体元素均值 ${fmtN(stats.elementMean ?? NaN)}${stats.dimMismatch ? `;维度漂移 ${stats.dimMismatch} 行` : ''}`
+        : `  统计:${stats.count} 条记录(非数值格式不做均值)`
+    const dictText = formatDictionary(dictionary)
+    const text = [
+      `■ ${node.name}(id=${node.id})[格式 ${fmtLabel};节点单位 ${node.unit || '-'};量程 ${node.min}~${node.max}]`,
+      `  行数 ${stats.count}${truncated ? `(截断:${memoryHit || '达到 maxRows 上限'})` : '(完整)'} | 首 ${shortTs(stats.firstTs)} ~ 末 ${shortTs(stats.lastTs)}`,
+      statLine,
+      sample.length > 0 ? `  采样(≤3 行): ${sample.join(' | ')}` : '  采样:无有效行',
+      ...(tableFieldStats ? [tableFieldStats] : []),
+      ...(dictText ? [dictText] : []),
+    ].join('\n')
+
+    // dataHook 下沉处理(用户配置的 (param, data, ctx) => {...})
+    let hookText: string | undefined
+    const artifacts: MesHookArtifact[] = [...(autosaved as MesHookArtifact[])]
+    const hookCode = mesDataHookCode(cfg)
+    if (hookCode) {
+      const hookData: MesHookData = {
+        node: { id: node.id, name: node.name, lineId: node.lineId, unit: node.unit },
+        format,
+        rows: buf,
+        window: { from, to },
+      }
+      try {
+        const outcome = await runMesDataHook(hookCode, param, hookData, { nodeId: node.id })
+        if (outcome.ok) {
+          artifacts.push(...outcome.artifacts)
+          const parts = [`  钩子(dataHook):已执行,产物 ${outcome.artifacts.length} 个`]
+          if (outcome.summary) parts.push(`  处理摘要: ${outcome.summary}`)
+          if (outcome.context) parts.push(`  处理说明: ${outcome.context}`)
+          if (outcome.logs.length > 0) parts.push(`  hook 日志(≤3): ${outcome.logs.slice(0, 3).join(' / ')}`)
+          hookText = parts.join('\n')
+        }
+        else {
+          hookText = `  钩子(dataHook)执行失败:${outcome.error ?? '未知原因'}(统计仍基于原始数据)`
+        }
+      }
+      catch (err) {
+        hookText = `  钩子(dataHook)执行失败:${err instanceof Error ? err.message : String(err)}`
+      }
+    }
+
+    // 产物行(hook 之外含自动落盘图像)
+    if (artifacts.length > 0) {
+      const shown = artifacts.slice(0, 8).map(a => `${a.name}(${Math.max(1, Math.round(a.bytes / 1024))}KB)`)
+      hookText = `${hookText ?? ''}\n  产物(${artifacts.length}${artifacts.length > 8 ? ',显示前8' : ''}): ${shown.join(' | ')}`
+    }
+    return { text, stats, truncated, sample, hookText, artifacts }
+  }
+
+  /**
+   * 取数编排(护栏全代码级):
+   * 授权过滤 → 窗口/行数归一 → 频次限流 → 快照 / 内联 / 异步三模式。
+   */
+  async function fetch(agentId: string, args: MesFetchArgs): Promise<MesFetchOutcome> {
+    // ① 授权:ids 必须是调用者可见(绑线)的 mes-rest 节点
+    const vis = await resolveVisibleIds(agentId, args.ids)
+    if (!vis.ok) return { text: vis.text, isError: true }
+    // ② 窗口/行数护栏
+    const win = normalizeWindow(args)
+    if (!win.ok) return { text: win.text, isError: true }
+    // ③ 频次限流(每 agent 每 60s ≤6 次)
+    if (!mesFetchRateCheck(agentId, d.nowMs())) {
+      return { text: `取数过于频繁:每 60 秒最多 ${MES_RATE_MAX_CALLS} 次。请先消化已有结果,稍后再取。`, isError: true }
+    }
+    // ④ 格式门控:image/table/event 的原文(帧/记录)不进 prompt 也不落 CSV 数据集,
+    //    只支持内联行数(≤MES_SYNC_INLINE_MAX_ROWS);大窗口请拆小分批
+    if (win.maxRows > MES_SYNC_INLINE_MAX_ROWS) {
+      const INLINE_ONLY = new Set(['image', 'table', 'event'])
+      const hits = vis.nodes.filter(n => INLINE_ONLY.has(historyFormatOf(n.driverConfig as Record<string, unknown>)))
+      if (hits.length > 0) {
+        return {
+          text: `行数上限冲突:${hits.map(n => `${n.name}(${n.id})`).join(', ')} 是 图像/表格/事件 格式点位,只在 max_rows ≤ ${MES_SYNC_INLINE_MAX_ROWS} 的内联模式支持(原文不落 CSV 数据集)。请缩小时间窗或调低 max_rows 后重取。`,
+          isError: true,
+        }
+      }
+    }
+
+    // 模式一:当前值快照(无 from/to)
+    if (!win.from || !win.to) {
+      const lines: string[] = []
+      for (const node of vis.nodes) {
+        const driver = d.resolveDriver(node.driver)
+        try {
+          if (typeof driver.read !== 'function') {
+            lines.push(`- ${node.name}(${node.id}):驱动 ${node.driver} 不支持读取`)
+            continue
+          }
+          const r = await driver.read({ domain: { min: node.min, max: node.max }, driverConfig: node.driverConfig })
+          const at = new Date(d.nowMs()).toISOString()
+          if (r.dictionary && r.dictionary.length > 0) cacheDictionary(node.id, r.dictionary)
+          const dict = r.dictionary && r.dictionary.length > 0 ? r.dictionary : mesDictionaryOfNode(node.id, node.driverConfig as Record<string, unknown>)
+          lines.push(r.ok && r.eng != null
+            ? `- ${node.name}(${node.id}):${fmtN(r.eng)}${node.unit} @ ${shortTs(at)}${dict.length > 0 ? `\n${formatDictionary(dict, '    ')}` : ''}`
+            : `- ${node.name}(${node.id}):读取失败(${r.message.slice(0, 80)})`)
+        }
+        catch (err) {
+          lines.push(`- ${node.name}(${node.id}):读取异常(${(err instanceof Error ? err.message : String(err)).slice(0, 80)})`)
+        }
+      }
+      return {
+        mode: 'snapshot',
+        text: `MES 当前值快照(${vis.nodes.length} 个点位,内联直读):\n${lines.join('\n')}\n\n说明:当前值为直读快照;历史窗口用 mes_fetch 带 from/to(≤7 天,max_rows≤${MES_MAX_ROWS_CAP})。`,
+      }
+    }
+
+    // 模式二:同步内联(行数 ≤ MES_SYNC_INLINE_MAX_ROWS;格式感知+dataHook 下沉)
+    if (win.maxRows <= MES_SYNC_INLINE_MAX_ROWS) {
+      const sections: string[] = []
+      const statsOut: NonNullable<MesFetchOutcome['data']>['stats'] = []
+      for (const node of vis.nodes) {
+        try {
+          const one = await inlineFetchNode(node, win.from, win.to, win.maxRows, args.param, args.include_data === true || args.include_data === 'true')
+          sections.push(one.hookText ? `${one.text}\n${one.hookText}` : one.text)
+          statsOut.push({ nodeId: node.id, stats: one.stats, truncated: one.truncated })
+        }
+        catch (err) {
+          sections.push(`■ ${node.name}(id=${node.id})\n  取数失败:${err instanceof Error ? err.message : String(err)}`)
+        }
+      }
+      return {
+        mode: 'inline',
+        text: `MES 历史取数(内联同步,${vis.nodes.length} 个点位,窗口 ${shortTs(win.from)} ~ ${shortTs(win.to)}):\n${sections.join('\n')}\n\n说明:以上为统计摘要与 ≤3 行采样;MES 原文不进入对话。向量/图像/记录点位按各自格式呈现,已配置数据钩子(dataHook)的点位会附处理摘要与产物清单(文件落 <数据根>/mes-artifacts/<点位id>/)。需要标量/向量全量行请用更大 max_rows(> ${MES_SYNC_INLINE_MAX_ROWS})走异步数据集,再用 mes_dataset_read 读。`,
+        data: { stats: statsOut },
+      }
+    }
+
+    // 模式三:异步数据集(行数 > MES_SYNC_INLINE_MAX_ROWS;进程内异步,绝不进调度循环;
+    // requestHook 覆盖在此同样生效——合并进作业用的 driverConfig)
+    const jobIds: string[] = []
+    const datasetIds: string[] = []
+    const lines: string[] = []
+    for (const node of vis.nodes) {
+      let effCfg: Record<string, unknown>
+      try {
+        effCfg = await configWithRequestHook(node, args.param)
+      }
+      catch (err) {
+        lines.push(`- ${node.name}(${node.id}):requestHook 失败,作业未创建(${err instanceof Error ? err.message : String(err)})`)
+        continue
+      }
+      const run = node.lineId ? getActiveLineRun(node.lineId) : null
+      const { jobId, datasetId } = d.store.createFetchJob({
+        nodeId: node.id,
+        fromIso: win.from,
+        toIso: win.to,
+        maxRows: win.maxRows,
+        agentId,
+        lineId: node.lineId,
+        nodeName: node.name,
+        driverConfig: effCfg,
+        dictionary: mesDictionaryOfNode(node.id, node.driverConfig as Record<string, unknown>),
+        nodeMeta: {
+          unit: node.unit,
+          min: node.min,
+          max: node.max,
+          description: String(node.driverConfig.desc ?? ''),
+          semantics: String(node.driverConfig.semantics ?? ''),
+          format: historyFormatOf(node.driverConfig as Record<string, unknown>),
+        },
+        context: run
+          ? { lineId: run.lineId, productId: run.productId, recipeId: run.recipeId, runId: run.runId }
+          : { lineId: node.lineId },
+      })
+      jobIds.push(jobId)
+      datasetIds.push(datasetId)
+      lines.push(`- ${node.name}(${node.id}):job_id=${jobId} dataset_id=${datasetId} status=running`)
+    }
+    return {
+      mode: 'async',
+      text: `已创建 ${lines.length} 个异步取数作业(窗口 ${shortTs(win.from)} ~ ${shortTs(win.to)},max_rows=${win.maxRows}):\n${lines.join('\n')}\n\n勿轮询;未完成先做别的,用 mes_datasets 查状态,完成后 mes_dataset_read(dataset_id, mode=stats/rows) 读内容。`,
+      data: { job_ids: jobIds, dataset_ids: datasetIds },
+    }
+  }
+
+  // ---------- 离线导出(指定目录 + manifest/README 语义清单) ----------
+
+  /** 安全子路径:只允许落在 root 内(拒绝 ../、绝对路径逃逸、盘符切换) */
+  function resolveUnderRoot(root: string, folder: string, fallback: string): { ok: true, dir: string } | { ok: false, text: string } {
+    const base = resolve(root)
+    const raw = String(folder ?? '').trim()
+    if (!raw) return { ok: true, dir: join(base, fallback) }
+    const target = resolve(base, raw)
+    if (target !== base && !target.startsWith(`${base}${sep}`)) {
+      return {
+        ok: false,
+        text: `导出目录被拒:folder=${raw} 越出允许根目录 ${base}(只接受相对路径;如需自定义根目录,请由管理员设置环境变量 AW_MES_EXPORT_ROOT)。`,
+      }
+    }
+    return { ok: true, dir: target }
+  }
+
+  function safeSeg(value: string): string {
+    return value.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 80) || 'node'
+  }
+
+  function writeChunk(fd: number, text: string): void {
+    const buf = Buffer.from(text, 'utf8')
+    let off = 0
+    while (off < buf.length) off += writeSync(fd, buf, off, buf.length - off)
+  }
+
+  /**
+   * 把可见 MES 点位的历史原样导出到目录(流式写盘):
+   *   scalar → data.csv(ts,value)
+   *   vector → data.csv(宽表 ts,v0..vN)+ manifest 里的逐点语义
+   *   image  → frames.jsonl(元数据)+ frames/*.png
+   *   table/event → records.jsonl
+   * 每个导出目录都写 manifest.json + README.md(字段含义/单位/量程/产线批次上下文),
+   * Agent 与离线分析器都能直接读懂,不需要回读平台。
+   */
+  async function exportData(agentId: string, args: MesExportArgs): Promise<MesToolResult & { dir?: string, manifestPath?: string, rows?: number }> {
+    const vis = await resolveVisibleIds(agentId, args.ids)
+    if (!vis.ok) return { text: vis.text, isError: true }
+    const from = String(args.from ?? '').trim()
+    const to = String(args.to ?? '').trim()
+    if (!from || !to) return { text: 'mes_export 需要 from/to(ISO)历史窗口;当前值快照请用 mes_fetch。', isError: true }
+    const fromMs = Date.parse(from)
+    const toMs = Date.parse(to)
+    if (!Number.isFinite(fromMs) || !Number.isFinite(toMs)) return { text: 'from/to 必须是合法 ISO 时间戳。', isError: true }
+    if (fromMs >= toMs) return { text: `时间窗无效:from(${from}) 必须早于 to(${to})。`, isError: true }
+    if (toMs - fromMs > MES_WINDOW_MAX_MS) {
+      return { text: `时间窗被拒:超过 7 天上限。请拆成 ≤7 天的分段导出。`, isError: true }
+    }
+    const rawMax = args.max_rows == null || args.max_rows === '' ? MES_MAX_ROWS_CAP : Math.round(Number(args.max_rows))
+    if (!Number.isFinite(rawMax) || rawMax < 1) return { text: 'max_rows 必须为 ≥1 的整数。', isError: true }
+    const maxRows = Math.min(rawMax, MES_EXPORT_MAX_ROWS)
+    if (!mesFetchRateCheck(agentId, d.nowMs())) {
+      return { text: `导出过于频繁:每 60 秒最多 ${MES_RATE_MAX_CALLS} 次。请稍后再试。`, isError: true }
+    }
+
+    const root = process.env.AW_MES_EXPORT_ROOT
+      ? resolve(process.env.AW_MES_EXPORT_ROOT)
+      : join(ensureDataDir(), 'mes-exports')
+    const exportId = `mesexp-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}-${randomUUID().slice(0, 6)}`
+    const where = resolveUnderRoot(root, String(args.folder ?? ''), exportId)
+    if (!where.ok) return { text: where.text, isError: true }
+    const dir = where.dir
+    mkdirSync(dir, { recursive: true })
+
+    const title = String(args.title ?? '').trim() || `MES 数据导出 ${exportId}`
+    const note = String(args.note ?? '').trim()
+    const manifestNodes: Array<Record<string, unknown>> = []
+    const failures: string[] = []
+    const scalarFiles: Array<{ nodeName: string, nodeId: string, file: string }> = []
+    let totalRows = 0
+
+    for (const node of vis.nodes) {
+      const cfg = node.driverConfig as Record<string, unknown>
+      const format = historyFormatOf(cfg)
+      const nodeDir = join(dir, safeSeg(node.id))
+      try {
+        mkdirSync(nodeDir, { recursive: true })
+        const driver = d.resolveDriver(node.driver)
+        if (typeof driver.fetchHistory !== 'function') {
+          failures.push(`${node.name}(${node.id}):驱动 ${node.driver} 无历史原语`)
+          continue
+        }
+        const effCfg = await configWithRequestHook(node, args.param)
+        const run = node.lineId ? getActiveLineRun(node.lineId) : null
+        let dictionary = mesDictionaryOfNode(node.id, cfg)
+        let rows = 0
+        let truncated = false
+        let dim = 0
+        let dimDrift = 0
+        let skipped = 0
+        let frameSaved = 0
+        let frameSkipped = 0
+        let fd: number | null = null
+        let headerWritten = false
+        let columns: string[] = []
+        let fileRel = ''
+        const jsonl: string[] = []
+
+        if (format === 'image') {
+          mkdirSync(join(nodeDir, 'frames'), { recursive: true })
+        }
+        else {
+          fd = openSync(join(nodeDir, format === 'table' || format === 'event' ? 'records.jsonl' : 'data.csv'), 'w')
+        }
+
+        const result = await driver.fetchHistory({
+          driverConfig: effCfg,
+          fromIso: from,
+          toIso: to,
+          maxRows,
+          onRows: (batch) => {
+            if (!Array.isArray(batch)) return
+            for (const r of batch) {
+              if (rows >= maxRows) {
+                truncated = true
+                break
+              }
+              const ts = String(r?.ts ?? '')
+              if (format === 'vector') {
+                if (!Array.isArray(r?.values) || r.values.length === 0) {
+                  skipped++
+                  continue
+                }
+                if (!headerWritten) {
+                  dim = r.values.length
+                  columns = ['ts', ...Array.from({ length: dim }, (_, i) => `v${i}`)]
+                  writeChunk(fd!, `${columns.join(',')}\r\n`)
+                  headerWritten = true
+                }
+                if (r.values.length !== dim) dimDrift++
+                const cells = [ts]
+                for (let i = 0; i < dim; i++) {
+                  const v = r.values[i]
+                  cells.push(Number.isFinite(v) ? String(v) : '')
+                }
+                writeChunk(fd!, `${cells.join(',')}\r\n`)
+                rows++
+                continue
+              }
+              if (format === 'image') {
+                if (typeof r?.data !== 'string' || r.data.trim() === '') {
+                  skipped++
+                  continue
+                }
+                if (frameSaved >= MES_EXPORT_MAX_FRAMES) {
+                  frameSkipped++
+                  truncated = true
+                  continue
+                }
+                const mime = typeof r.mime === 'string' && r.mime.includes('/') ? r.mime : 'image/png'
+                const ext = mime.includes('jpeg') ? 'jpg' : mime.includes('webp') ? 'webp' : 'png'
+                const name = `frames/${String(frameSaved).padStart(5, '0')}-${ts.replace(/[:.]/g, '-')}.${ext}`
+                try {
+                  writeFileSync(join(nodeDir, name), Buffer.from(r.data, 'base64'))
+                  jsonl.push(JSON.stringify({ ts, mime, file: name, ...(r.record !== null && typeof r.record === 'object' ? { record: r.record } : {}) }))
+                  frameSaved++
+                  rows++
+                }
+                catch (imgErr) {
+                  skipped++
+                  jsonl.push(JSON.stringify({ ts, mime, error: imgErr instanceof Error ? imgErr.message : String(imgErr) }))
+                }
+                continue
+              }
+              if (format === 'table' || format === 'event') {
+                if (r?.record === null || r?.record === undefined) {
+                  skipped++
+                  continue
+                }
+                jsonl.push(JSON.stringify({ ts, record: r.record }))
+                rows++
+                continue
+              }
+              if (typeof r?.value !== 'number' || !Number.isFinite(r.value)) {
+                skipped++
+                continue
+              }
+              if (!headerWritten) {
+                columns = ['ts', 'value']
+                writeChunk(fd!, `${columns.join(',')}\r\n`)
+                headerWritten = true
+              }
+              writeChunk(fd!, `${ts},${r.value}\r\n`)
+              rows++
+            }
+          },
+        })
+        if (result?.dictionary && result.dictionary.length > 0) {
+          dictionary = result.dictionary
+          cacheDictionary(node.id, dictionary)
+        }
+        if (result && result.complete === false) truncated = true
+        if (format === 'image' || format === 'table' || format === 'event') {
+          writeFileSync(join(nodeDir, 'records.jsonl'), `${jsonl.join('\n')}${jsonl.length > 0 ? '\n' : ''}`, 'utf8')
+          fileRel = `${safeSeg(node.id)}/records.jsonl`
+        }
+        else {
+          if (!headerWritten) {
+            columns = format === 'vector' ? ['ts'] : ['ts', 'value']
+            writeChunk(fd!, `${columns.join(',')}\r\n`)
+            headerWritten = true
+          }
+          fileRel = `${safeSeg(node.id)}/data.csv`
+        }
+        if (fd != null) {
+          closeSync(fd)
+          fd = null
+        }
+        if (format === 'scalar') scalarFiles.push({ nodeName: node.name, nodeId: node.id, file: fileRel })
+        totalRows += rows
+        manifestNodes.push({
+          id: node.id,
+          name: node.name,
+          line_id: node.lineId,
+          format,
+          unit: node.unit,
+          range: { min: node.min, max: node.max },
+          description: String(cfg.desc ?? ''),
+          semantics: String(cfg.semantics ?? ''),
+          file: fileRel,
+          columns,
+          rows,
+          ...(format === 'vector' ? { vector: { dim, dimension_drift_rows: dimDrift } } : {}),
+          ...(format === 'image' ? { frames: { saved: frameSaved, skipped: frameSkipped } } : {}),
+          skipped_rows: skipped,
+          truncated,
+          fields: dictionary,
+          context: run ? { line_id: run.lineId, product_id: run.productId, recipe_id: run.recipeId, run_id: run.runId } : { line_id: node.lineId },
+        })
+      }
+      catch (err) {
+        failures.push(`${node.name}(${node.id}):${err instanceof Error ? err.message : String(err)}`)
+      }
+    }
+
+    // 多标量节点按时间对齐的宽表(默认生成;纯时间戳交集,不做插值)
+    let mergedFile: string | null = null
+    const mergeEnabled = !(args.merge === false || args.merge === 'false')
+    if (mergeEnabled && scalarFiles.length > 1) {
+      try {
+        const series = scalarFiles.map((s) => {
+          const map = new Map<string, number>()
+          const raw = readFileSync(join(dir, s.file), 'utf8')
+          for (const line of raw.split(/\r?\n/).slice(1)) {
+            const [ts, v] = line.split(',')
+            if (ts && v !== undefined && Number.isFinite(Number(v))) map.set(ts, Number(v))
+          }
+          return { ...s, map }
+        })
+        const times = [...new Set(series.flatMap(s => [...s.map.keys()]))].sort()
+        const header = ['time', ...series.map(s => `${s.nodeName}(${s.nodeId})`)]
+        const lines = [header.join(',')]
+        for (const ts of times) lines.push([ts, ...series.map(s => s.map.get(ts) ?? '')].join(','))
+        writeFileSync(join(dir, 'merged.csv'), `${lines.join('\n')}\n`, 'utf8')
+        mergedFile = join(dir, 'merged.csv')
+      }
+      catch { /* merge 失败不影响单节点导出 */ }
+    }
+
+    const manifest = {
+      schema: 'aw.mes-export/1',
+      export_id: exportId,
+      created_at: new Date().toISOString(),
+      title,
+      note,
+      window: { from, to, from_ms: fromMs, to_ms: toMs },
+      directory: dir,
+      nodes: manifestNodes,
+      merged_file: mergedFile,
+      totals: { nodes: manifestNodes.length, rows: totalRows, failed_nodes: failures.length },
+      usage: 'data.csv 首行为列名(ts=时间,v0..vN=向量点位);records.jsonl 每行一条记录;image 格式的像素在 frames/ 下,records.jsonl 是对应元数据。字段含义/单位/量程见 nodes[].fields(向量逐点语义在 fields[].points);批次归属见 nodes[].context。',
+    }
+    const manifestPath = join(dir, 'manifest.json')
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+
+    const readme: string[] = [
+      `# ${title}`,
+      '',
+      `- 导出时间: ${new Date().toISOString()}`,
+      `- 时间窗: ${from} ~ ${to}`,
+      `- 导出目录: ${dir}`,
+      `- 说明: ${note || '(无)'}`,
+      '',
+      '## 文件与字段',
+      '',
+    ]
+    for (const n of manifestNodes) {
+      readme.push(`### ${String(n.name)} (${String(n.id)})`)
+      readme.push(`- 格式: ${String(n.format)};文件: ${String(n.file)};行数: ${String(n.rows)}`)
+      readme.push(`- 单位: ${String(n.unit || '-')};量程: ${JSON.stringify(n.range)}`)
+      if (n.semantics) readme.push(`- 物理意义: ${String(n.semantics)}`)
+      const fields = Array.isArray(n.fields) ? n.fields as DcwFieldDef[] : []
+      const dict = formatDictionary(fields, '  ')
+      if (dict) readme.push(dict)
+      readme.push('')
+    }
+    if (mergedFile) readme.push(`多参数对齐宽表: ${mergedFile}(列名=节点名(节点id);仅对齐相同时间戳,不插值)`, '')
+    if (failures.length > 0) readme.push('## 失败节点', '', ...failures.map(f => `- ${f}`), '')
+    writeFileSync(join(dir, 'README.md'), `${readme.join('\n')}\n`, 'utf8')
+
+    const lines = manifestNodes.map(n => `- ${String(n.name)}(${String(n.id)}) [${String(n.format)}] ${String(n.rows)} 行 → ${String(n.file)}`)
+    const failText = failures.length > 0 ? `\n失败节点(${failures.length}):\n${failures.map(f => `  - ${f}`).join('\n')}` : ''
+    return {
+      isError: failures.length > 0,
+      dir,
+      manifestPath,
+      rows: totalRows,
+      text: `MES 数据已导出(${manifestNodes.length}/${vis.nodes.length} 个点位,共 ${totalRows} 行):\n${lines.join('\n')}${mergedFile ? `\n- 多参数宽表: ${mergedFile}` : ''}${failText}\n\n目录: ${dir}\n语义清单: ${manifestPath}\n说明: README.md\n\n离线分析请直接读取上述文件;在线继续取数用 mes_fetch/mes_dataset_read。`,
+    }
+  }
+
+  return { catalog, fetch, exportData }
+}
+
+export type MesController = ReturnType<typeof createMesController>