agentworkshop 0.7.54 → 0.7.59

package/server/services/workshop/agents/industrial/grant-guard.ts

@@ -0,0 +1,145 @@
+/**
+ * grant-guard —— 工业工具运行时产线 grant 复核(权限模型 v3 / 收权即失活的收口)。
+ *
+ * 为什么需要:agent 绑定面是**绑定时点**的静态授权(绑定端点已校验 lineMode),
+ * 但 admin 事后撤销某用户的产线授权后,绑定行仍在 —— 若工具分发只查绑定面,
+ * 被撤权用户的 agent 依旧能经工具桥读/写该产线(REST/内部回合/MCP 全路径)。
+ * 本守卫在工业工具分发入口按**调用上下文的当前 grant**复核:
+ *   - 上下文用户 = channel 属主(REST invoke 的调用者已另行校验可支配该 agent,
+ *     二者语义一致;agent 自主回合归属其 channel 属主);
+ *   - 目标产线从调用参数解析(node_id / recipe_id / line_id / ids),解析不到时
+ *     回退为「该 agent 全部绑定的产线」(如 daq_query 不带 node_id 的全节点查询);
+ *   - 只读工具要求 ≥readonly,写族工具要求 operate;
+ *   - 遗留无主 channel(owner NULL)豁免(存量数据兼容;新建 channel 均有属主);
+ *   - admin 属主天然放行;channel/属主不存在 → fail-closed 拒绝。
+ */
+import { AppError } from '@/server/utils/errors'
+import { userRepository } from '@/server/repositories/user.repository'
+import { lineMode, type LineMode } from '@/server/services/workshop/permissions'
+import { INDUSTRIAL_TOOL_NAMES } from '../host-tool-bridge/tools/industrial'
+
+/** 写族工具:涉及产线写向/下发意图,要求 operate(其余工业工具按只读复核) */
+const WRITE_TOOLS = new Set([
+  'recipe_propose',
+  'recipe_update',
+  'recipe_apply',
+  'recipe_trial',
+  'recipe_rollback',
+  'optimization_explore',
+  'twin_calibration_request',
+  // 产线管理面(启停直接改物理状态与批次窗口)
+  'line_start',
+  'line_stop',
+])
+
+/** 无需复核的纯协作/管理面工具(不触达产线数据) */
+const GRANT_EXEMPT = new Set([
+  'team_grant_nodes',
+  'team_revoke_nodes',
+  'aml_activity',
+  'exp_collect',
+])
+
+interface GuardIdentity {
+  agentId: string
+  channelId: string
+}
+
+/** 从调用参数解析涉及的产线(动态 import 重仓,避免与 dcw/daq 模块循环依赖) */
+async function resolveTargetLines(agentId: string, toolName: string, args: Record<string, unknown>): Promise<string[] | null> {
+  const lines = new Set<string>()
+  const one = (v: unknown) => (typeof v === 'string' && v.trim() ? v.trim() : '')
+  const nodeIdLine = async (id: string): Promise<string | null> => {
+    const { getDaqNodeRepo } = await import('@/server/services/workshop/daq/daq-node.repo')
+    const daq = getDaqNodeRepo().byId(id)
+    if (daq?.lineId) return daq.lineId
+    const { getDcwController } = await import('@/server/services/workshop/dcw/dcw-controller')
+    return getDcwController().byId(id)?.lineId ?? null
+  }
+  const { getDcwController } = await import('@/server/services/workshop/dcw/dcw-controller')
+
+  const explicit = one(args.node_id ?? args.nodeId)
+  if (explicit) {
+    const l = await nodeIdLine(explicit)
+    if (l) lines.add(l)
+  }
+  const recipeId = one(args.recipe_id ?? args.recipeId)
+  if (recipeId) {
+    const r = getDcwController().listRecipes().find(x => x.id === recipeId)
+    if (r?.lineId) lines.add(r.lineId)
+  }
+  const lineArg = one(args.line_id ?? args.lineId)
+  if (lineArg) lines.add(lineArg)
+  const ids = Array.isArray(args.ids) ? args.ids.map(one).filter(Boolean) : []
+  for (const id of ids) {
+    const l = await nodeIdLine(id)
+    if (l) lines.add(l)
+  }
+  if (lines.size > 0) return [...lines]
+
+  // 无显式目标(如全节点 daq_query)→ 回退 agent 绑定面涉及的全部产线
+  const { getAgentNodeBindingRepo } = await import('@/server/services/workshop/agents/node-bindings.repo')
+  const bindings = getAgentNodeBindingRepo().byAgent(agentId)
+  for (const b of bindings) {
+    if (b.kind === 'recipe') {
+      const r = getDcwController().listRecipes().find(x => x.id === b.nodeId)
+      if (r?.lineId) lines.add(r.lineId)
+    }
+    else {
+      const l = await nodeIdLine(b.nodeId)
+      if (l) lines.add(l)
+    }
+  }
+  return lines.size > 0 ? [...lines] : null
+}
+
+/**
+ * 工业工具分发前的 grant 复核。通过 → 静默返回;
+ * 不通过 → 返回面向 agent 的工具错误文本(fail-closed,不做部分放行)。
+ */
+export async function guardIndustrialToolGrant(identity: GuardIdentity, toolName: string, args: Record<string, unknown>): Promise<{ text: string, isError: true } | null> {
+  if (!INDUSTRIAL_TOOL_NAMES.has(toolName) || GRANT_EXEMPT.has(toolName)) return null
+  if (!identity.channelId) return null
+  try {
+    const { getWorkshopManager } = await import('@/server/plugins/workshop')
+    const manager = getWorkshopManager()
+    const channel = manager.deps.repos.channels.findById(identity.channelId)
+    if (!channel) {
+      return { text: `工具调用被拒:所属频道不存在或已删除(channel=${identity.channelId.slice(0, 8)})。`, isError: true }
+    }
+    // 遗留无主 channel 豁免(存量兼容;新 channel 均有属主)
+    if (!channel.ownerUserId) return null
+    const owner = userRepository.findById(channel.ownerUserId)
+    if (!owner) {
+      return { text: '工具调用被拒:频道属主账号不存在(fail-closed)。请联系管理员。', isError: true }
+    }
+    if (owner.role === 'admin') return null
+
+    const need: LineMode = WRITE_TOOLS.has(toolName) ? 'operate' : 'readonly'
+    const resolved = await resolveTargetLines(identity.agentId, toolName, args ?? {})
+    // P1-6:频道绑线并入复核集 —— line_start/line_stop 等产线管理工具的目标产线
+    // 来自频道绑线(ch.lineId)而非调用参数,agent 无节点绑定时 resolveTargetLines
+    // 返回 null → 守卫在此直接放行,属主被撤权后绑线频道的启停/读面照常工作
+    // (收权即失活的结构性缺口,2026-10-08 评审)。
+    const lineSet = new Set(resolved ?? [])
+    if (channel.lineId) lineSet.add(channel.lineId)
+    if (lineSet.size === 0) return null
+    for (const lineId of lineSet) {
+      const mode = lineMode({ id: owner.id, role: owner.role }, lineId)
+      const ok = mode === 'operate' || (need === 'readonly' && mode === 'readonly')
+      if (!ok) {
+        const what = need === 'operate' ? '写控/下发' : '读取'
+        return {
+          text: `工具调用被拒(权限模型 v3):频道属主对产线「${lineId}」无${need === 'operate' ? '可操控' : '查看'}授权,无法${what}。请联系管理员在「权限管理」中重新授予;该限制在授权收回后即时生效。`,
+          isError: true,
+        }
+      }
+    }
+    return null
+  }
+  catch (err) {
+    if (err instanceof AppError) throw err
+    // 守卫自身故障 → fail-closed(不因实现缺陷放行)
+    return { text: `工具调用被拒:权限复核服务异常(${err instanceof Error ? err.message : String(err)})。`, isError: true }
+  }
+}

package/server/services/workshop/agents/industrial/index.ts

@@ -17,6 +17,7 @@
 export { toolMyIndustrialNodes, toolDcwControl, toolDcwRead } from './dcw-tools'
 export { toolParamControl, toolParamRead } from './param-tools'
 export { toolDaqQuery, toolDaqFrames } from './daq-tools'
+export { toolDaqExport } from './daq-export'
 export { toolDcwJudge, toolDcwRollback, toolDcwJournal } from './dcw-judge-tools'
 export { toolOpsLog, toolRecipeLog, toolLineContext, toolRecipeVersions, toolRecipeUpdate, toolRecipeRollback, toolRecipeTrial, toolRecipeApply } from './ops-tools'
 export { toolMesCatalog, toolMesFetch, toolMesDatasetRead, toolMesDatasets } from './mes-tools'
@@ -25,3 +26,6 @@ export { toolAmlJobSubmit, toolAmlJobStatus, toolAmlJobLogs, toolAmlJobCancel, t
 
 export { toolOptimizationExplore } from './optimization-tools'
 export { toolTwinProviderCatalog, toolTwinSceneDiscover, toolTwinSceneCompile, toolTwinSceneFreeze, toolTwinSceneRead, toolTwinPhysicsSpecDraft, toolTwinPhysicsSpecValidate, toolTwinPhysicsSpecCompile, toolTwinSnapshotCreate, toolTwinTrialRun, toolMpcOptimize, toolTwinGateEvaluate, toolTwinCalibrationRequest, toolTwinBayesOptimize } from './twin-tools'
+export { toolAmlActivity } from './aml-activity'
+export { toolRecipePropose } from './recipe-propose-tools'
+export { toolLineStart, toolLineStop, toolLineStatus } from './line-tools'

package/server/services/workshop/agents/industrial/line-tools.ts

@@ -0,0 +1,151 @@
+/**
+ * 产线管理工具 —— Agent(频道 lead)的开线/停线/状态面。
+ *
+ * 权限模型:
+ *   - line_start / line_stop:仅频道 lead;频道必须绑线;目标产线 = 频道绑定产线
+ *     (不接受跨线参数 —— 管理 action 与 Channel 产线锚点 1:1,杜绝跨线操作)。
+ *   - 两者恒为 HITL(人工批准才执行;产线启停直接改变物理状态与批次窗口,无 auto 免批)。
+ *   - line_status:只读,lead/worker 均可(复用工业工具的 grant 复核,channel 线 ≥readonly)。
+ * 理由强制:reason 必填(启停理由入审计与审批卡,人要看懂为什么启停)。
+ */
+import { getWorkshopManager } from '@/server/plugins/workshop'
+import { getToolApprovals } from '../tool-approvals'
+import { agentBadgeLabel } from '../agent-badge'
+import { getDcwController } from '../../dcw/dcw-controller'
+import { getDcwLineRepo } from '../../dcw/dcw-line.repo'
+import { recordOps } from '../../ops/ops'
+
+export interface LineStartInput { recipe_id?: string, reason?: string }
+export interface LineStopInput { reason?: string }
+export interface LineStatusInput { line_id?: string }
+
+/** 解析「频道 lead + 绑线」上下文;line_start/line_stop 共用 */
+async function requireBoundLineLead(agentId: string, channelId: string | undefined): Promise<{ lineId: string, lineName: string } | { error: string }> {
+  if (!channelId) return { error: 'line_start/line_stop 仅限频道内使用(缺频道上下文)。' }
+  const manager = getWorkshopManager()
+  const ch = manager.deps.repos.channels.findById(channelId)
+  if (!ch) return { error: `频道不存在: ${channelId}` }
+  if (ch.leadAgentId !== agentId) return { error: '产线启停仅限频道 lead 操作(你是 worker;如需启停请向 lead 提出)。' }
+  const lineId = String(ch.lineId ?? '').trim()
+  if (!lineId) return { error: '本频道未绑定产线,无法执行产线启停(绑线频道才能管理产线)。' }
+  const line = getDcwLineRepo().byId(lineId)
+  if (!line) return { error: `频道绑定的产线不存在: ${lineId}` }
+  return { lineId, lineName: line.name }
+}
+
+// 延迟导入避免循环依赖(line-run ← dcw-controller ← 本模块经 controller 已引入)
+
+/** 工具:line_start —— lead 申请开线(选配方),恒 HITL,人工批准后执行。 */
+export async function toolLineStart(agentId: string, args: LineStartInput, channelId?: string): Promise<{ text: string, isError?: boolean }> {
+  const reason = String(args.reason ?? '').trim()
+  if (!reason) return { text: 'reason 必填:开线必须说明作业依据(工单/排产/实验目的),人工审批要能看懂。', isError: true }
+  const recipeId = String(args.recipe_id ?? '').trim()
+  if (!recipeId) return { text: 'recipe_id 必填(line_context 可看到当前配方 id)。', isError: true }
+  const ctx = await requireBoundLineLead(agentId, channelId)
+  if ('error' in ctx) return { text: ctx.error, isError: true }
+  const { lineId, lineName } = ctx
+  const ctrl = getDcwController()
+  const recipe = ctrl.listRecipes().find(r => r.id === recipeId)
+  if (!recipe) return { text: `配方 ${recipeId} 不存在。`, isError: true }
+  if (recipe.lineId !== lineId) return { text: `配方「${recipe.name}」不属于本频道绑定的产线「${lineName}」,不能用于开线。`, isError: true }
+  if (ctrl.lineState(lineId).active) {
+    const cur = ctrl.lineState(lineId)
+    return { text: `产线「${lineName}」已在运行(批次 ${cur.runId},配方 ${cur.recipeName});重复开线被拒。如需换配方,先 line_stop 再开。`, isError: true }
+  }
+  let decision
+  try {
+    decision = await getToolApprovals().request(
+      agentId,
+      `line-start:${lineId}`,
+      'dcw',
+      `产线开跑审批:产线「${lineName}」以配方「${recipe.name}」v${recipe.version ?? 1} 开线(参数:${recipe.params.map((p) => {
+        const node = ctrl.byId(p.nodeId)
+        return `${node?.name ?? p.nodeId}=${p.value}${node?.unit ?? ''}`
+      }).join(';')})。理由:${reason} | 批准=开线并下发配方;拒绝可附指导。`,
+      { title: `产线开跑:${lineName}`, payload: { schemaVersion: 1, kind: 'line-start', lineId, recipeId, reason } },
+    )
+  }
+  catch (err) {
+    return { text: `提交开线审批失败:${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+  if (!decision.approved) {
+    return { text: `开线未获批准(超时未批或人工拒绝),产线未做任何变更。人工意见:${decision.comment || '(无附言)'}` }
+  }
+  try {
+    const run = await ctrl.lineStart(lineId, recipeId)
+    try {
+      recordOps({
+        actor: agentId, actorName: agentBadgeLabel(agentId), actorKind: 'agent',
+        action: 'line.start', kind: 'line', targetKind: 'line', targetId: lineId, lineId,
+        summary: `Agent 开线:「${lineName}」以配方「${recipe.name}」开跑(批次 ${run.id.slice(0, 8)});理由:${reason}`,
+      })
+    }
+    catch { /* 审计失败不影响执行 */ }
+    return { text: `产线「${lineName}」已开跑(批次 ${run.id.slice(0, 8)},配方「${recipe.name}」参数已下发)。用 daq_query 复测确认数采窗口激活。` }
+  }
+  catch (err) {
+    return { text: `开线执行失败(产线未变更):${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+}
+
+/** 工具:line_stop —— lead 申请停线,恒 HITL;停线关闭批次窗口并停该线数采。 */
+export async function toolLineStop(agentId: string, args: LineStopInput, channelId?: string): Promise<{ text: string, isError?: boolean }> {
+  const reason = String(args.reason ?? '').trim()
+  if (!reason) return { text: 'reason 必填:停线必须说明原因(完工/检修/异常),审计与审批都要看懂。', isError: true }
+  const ctx = await requireBoundLineLead(agentId, channelId)
+  if ('error' in ctx) return { text: ctx.error, isError: true }
+  const { lineId, lineName } = ctx
+  const ctrl = getDcwController()
+  const st = ctrl.lineState(lineId)
+  if (!st.active) return { text: `产线「${lineName}」未在运行,无需停线。`, isError: true }
+  let decision
+  try {
+    decision = await getToolApprovals().request(
+      agentId,
+      `line-stop:${lineId}`,
+      'dcw',
+      `产线停线审批:产线「${lineName}」将关闭当前批次窗口(批次 ${st.runId},配方 ${st.recipeName},已打标 ${st.taggedSamples} 样本)。理由:${reason} | 批准=停线(数采同步停止);拒绝可附指导。`,
+      { title: `产线停线:${lineName}`, payload: { schemaVersion: 1, kind: 'line-stop', lineId, reason } },
+    )
+  }
+  catch (err) {
+    return { text: `提交停线审批失败:${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+  if (!decision.approved) {
+    return { text: `停线未获批准(超时未批或人工拒绝),产线继续运行。人工意见:${decision.comment || '(无附言)'}` }
+  }
+  try {
+    const run = ctrl.lineStop(lineId)
+    try {
+      recordOps({
+        actor: agentId, actorName: agentBadgeLabel(agentId), actorKind: 'agent',
+        action: 'line.stop', kind: 'line', targetKind: 'line', targetId: lineId, lineId,
+        summary: `Agent 停线:「${lineName}」批次 ${run.id.slice(0, 8)} 收窗;理由:${reason}`,
+      })
+    }
+    catch { /* 审计失败不影响执行 */ }
+    return { text: `产线「${lineName}」已停线(批次 ${run.id.slice(0, 8)} 收窗,打标样本 ${st.taggedSamples})。数据保留可查(daq_query 历史窗)。` }
+  }
+  catch (err) {
+    return { text: `停线执行失败(产线未变更):${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+}
+
+/** 工具:line_status —— 本频道绑定产线的运行状态(只读)。 */
+export async function toolLineStatus(agentId: string, args: LineStatusInput, channelId?: string): Promise<{ text: string, isError?: boolean }> {
+  void agentId
+  const ctrl = getDcwController()
+  const manager = getWorkshopManager()
+  const ch = channelId ? manager.deps.repos.channels.findById(channelId) : undefined
+  const wantLine = String(args.line_id ?? '').trim() || String(ch?.lineId ?? '').trim()
+  const lines = ctrl.listLines().filter(l => !wantLine || l.id === wantLine)
+  const states = ctrl.allLineStates().filter(s => !wantLine || s.lineId === wantLine)
+  if (lines.length === 0) return { text: `产线不存在或不在你的可见范围: ${wantLine || '(未指定)'}`, isError: true }
+  const rows = lines.map((l) => {
+    const s = states.find(x => x.lineId === l.id)
+    return s?.active
+      ? `· ${l.name}:运行中(批次 ${s.runId?.slice(0, 8)},配方「${s.recipeName}」,产品「${s.productName}」,自 ${s.startedAt},已打标 ${s.taggedSamples} 样本)`
+      : `· ${l.name}:未运行(数据保留可查)`
+  })
+  return { text: `产线状态:\n${rows.join('\n')}` }
+}

package/server/services/workshop/agents/industrial/manual-approval.ts

@@ -16,7 +16,7 @@ export async function requestManualApproval(args: {
   detail: string
   /** 动作口径(决定三处文案的动词):缺省 '下发'(参数面/节点面);回退面传 '回退' */
   action?: '下发' | '回退'
-}): Promise<{ ok: true } | { ok: false, text: string, isError?: boolean }> {
+}): Promise<{ ok: true, comment: string } | { ok: false, text: string, isError?: boolean }> {
   const action = args.action ?? '下发'
   const pendingText = action === '回退'
     ? '你对该节点已有一条待审批指令,请等待用户处理后再发新的回退请求(避免审批堆积)。'
@@ -41,5 +41,6 @@ export async function requestManualApproval(args: {
       isError: true,
     }
   }
-  return { ok: true }
+  // 批准附言随回执:人类可在批准时留反馈(缺省空),原样回流给 Agent
+  return { ok: true, comment: ap.comment ?? '' }
 }

package/server/services/workshop/agents/industrial/mes-tools.ts

@@ -1,135 +1,143 @@
-/**
- * MES 数据集工具族(mes_catalog / mes_fetch / mes_dataset_read / mes_datasets)。
- *
- * 面向 Agent 的 MES REST 点位只读面:目录检索、历史取数(护栏在 mes-controller 代码级)、
- * CSV 数据集读取与清单。铁律:MES 行级原文不进 prompt —— 所有回包只给统计摘要 + ≤3 行采样;
- * 全量原文只落 <configRoot>/datasets/<id>.csv(见 services/workshop/mes/mes-datasets.ts)。
- * 权限:fetch 按 dcw 绑线过滤(controller 内代码级);数据集读取/清单按
- * 创建者 ∪ 节点绑定 ∪ 可读产线(agentOpsScope 既有路径)过滤。
- */
-import type { MesDatasetRow, MesDatasetRead } from '../../mes/mes-datasets'
-import { getMesDatasets } from '../../mes/mes-datasets'
-import { createMesController } from '../../mes/mes-controller'
-import { agentOpsScope } from './ops-tools'
-import { AppError } from '../../../../utils/errors'
-
-/** 控制器单例(护栏依赖真实服务;无状态可安全复用) */
-let controller: ReturnType<typeof createMesController> | null = null
-function mesController(): ReturnType<typeof createMesController> {
-  controller ??= createMesController()
-  return controller
-}
-
-/** 数据集可见性:创建者 ∪ 节点绑定 ∪ 可读产线(节点授权线 ∪ 频道绑定线) */
-function mesDatasetVisible(agentId: string, ds: MesDatasetRow): boolean {
-  if (ds.createdBy === agentId) return true
-  const scope = agentOpsScope(agentId)
-  if (!scope) return false
-  if (scope.nodeIds.has(ds.nodeId)) return true
-  return !!ds.lineId && (scope.lineIds.includes(ds.lineId) || scope.boundLineIds.includes(ds.lineId))
-}
-
-/** 数据集行 → 一行摘要(id | 节点 | 窗口 | 行数 | 状态) */
-function dsLine(ds: MesDatasetRow): string {
-  const win = ds.fromTs && ds.toTs ? `${ds.fromTs.slice(5, 16).replace('T', ' ')} ~ ${ds.toTs.slice(5, 16).replace('T', ' ')}` : '当前值'
-  let state: string
-  if (ds.status === 'ready') state = `就绪(${ds.rows} 行,sha256 ${ds.sha256.slice(0, 8)})`
-  else if (ds.status === 'running') state = '取数中'
-  else state = `失败(${ds.error.slice(0, 80)})`
-  return `- ${ds.id} | ${ds.nodeName || ds.nodeId} | ${win} | ${state}`
-}
-
-/** 工具:mes_catalog —— MES REST 点位目录(数据驱动;q 子串/产线过滤;只读,无授权门槛)。
- *  每条含 id/单位/量程/读写/历史能力位,是 mes_fetch 与 mes_dataset_read 的寻址入口。 */
-export async function toolMesCatalog(_agentId: string, args: { q?: string, line_id?: string, limit?: number | string } = {}): Promise<{ text: string, isError?: boolean }> {
-  try {
-    const r = await mesController().catalog(args)
-    return { text: r.text }
-  }
-  catch (err) {
-    return { text: `MES 点位目录查询失败:${err instanceof Error ? err.message : String(err)}(服务未就绪时请稍后重试)。`, isError: true }
-  }
-}
-
-/** 工具:mes_fetch —— MES 历史取数(护栏代码级:绑线授权/窗口≤7天/行数≤5000/每分钟≤6次)。
- *  三模式:无 from/to=当前值快照;小窗口内联统计;大请求异步落 CSV 数据集(回 job_id/dataset_id,
- *  勿轮询,用 mes_datasets 查状态)。回包只含统计摘要 + ≤3 行采样,MES 原文不进对话。 */
-export async function toolMesFetch(agentId: string, args: { ids?: unknown, from?: string, to?: string, max_rows?: number | string } = {}): Promise<{ text: string, isError?: boolean }> {
-  try {
-    const r = await mesController().fetch(agentId, args)
-    return { text: r.text, isError: r.isError }
-  }
-  catch (err) {
-    return { text: `MES 取数失败:${err instanceof Error ? err.message : String(err)}(驱动离线或点位配置缺失时常见;可先用 mes_catalog 确认点位)。`, isError: true }
-  }
-}
-
-/** 工具:mes_dataset_read —— 读 CSV 数据集(head=列名+总行数 / stats=统计 / rows=分页)。
- *  权限:创建者或有该节点/产线可见权;回包同样只带 ≤3 行采样(原文不进 prompt)。 */
-export async function toolMesDatasetRead(agentId: string, args: { dataset_id?: string, mode?: string, offset?: number | string } = {}): Promise<{ text: string, isError?: boolean }> {
-  const datasetId = String(args.dataset_id ?? '').trim()
-  if (!datasetId) return { text: 'dataset_id 必填(mes_fetch 异步回包或 mes_datasets 清单里的 id)。', isError: true }
-  const modeArg = String(args.mode ?? 'head').trim()
-  const mode = modeArg === 'stats' || modeArg === 'rows' ? modeArg : 'head'
-  try {
-    const store = getMesDatasets()
-    const meta = store.datasetMeta(datasetId)
-    if (!meta) return { text: `数据集 ${datasetId} 不存在(用 mes_datasets 列出你可读的数据集)。`, isError: true }
-    if (!mesDatasetVisible(agentId, meta)) {
-      return { text: `无权读取数据集 ${datasetId}(仅创建者、该节点绑定者或该产线可读者可读)。`, isError: true }
-    }
-    const r: MesDatasetRead = store.readDataset(datasetId, mode, Number(args.offset) || 0)
-    const stateTxt = meta.status === 'ready' ? '' : meta.status === 'running' ? '\n注意:数据集仍在取数中,当前为已写入部分。' : `\n注意:取数已失败:${meta.error.slice(0, 120)}(以下为失败前已写入部分)。`
-    if (r.mode === 'stats') {
-      const s = r.stats
-      const f4 = (v: number | null | undefined): string => v == null || !Number.isFinite(v) ? '-' : String(Number(v.toFixed(4)))
-      return {
-        text: `数据集 ${datasetId} 统计(${meta.nodeName || meta.nodeId},产线 ${meta.lineId || '未分配'}):\n`
-          + `  数值行数 ${s.count} | 首 ${s.firstTs ?? '-'} ~ 末 ${s.lastTs ?? '-'}\n`
-          + `  min ${f4(s.min)} / max ${f4(s.max)} / mean ${f4(s.mean)} / stddev ${f4(s.stddev)}\n`
-          + `  文件 sha256 ${meta.sha256.slice(0, 16)}${stateTxt}`,
-      }
-    }
-    // head / rows:列名+行数+分页游标,采样 ≤3 行(原文不进 prompt)
-    let headTxt: string
-    let totalRows: number
-    let sample: string[]
-    if (r.mode === 'head') {
-      headTxt = `数据集 ${datasetId} 概览(${meta.nodeName || meta.nodeId},产线 ${meta.lineId || '未分配'}):\n  列名: ${r.head.columns.join(', ')}\n  总行数: ${r.head.totalRows}\n`
-      totalRows = r.head.totalRows
-      sample = r.head.preview.slice(0, 3).map(row => row.join(','))
-    }
-    else {
-      headTxt = `数据集 ${datasetId} 第 ${r.rowsView.offset} 行起的分页(每页 20 行,共 ${r.rowsView.total} 行;本页 ${r.rowsView.rows.length} 行):\n`
-      totalRows = r.rowsView.total
-      sample = r.rowsView.rows.slice(0, 3).map(row => row.join(','))
-    }
-    return {
-      text: `${headTxt}采样(≤3 行,ts,value): ${sample.join(' | ') || '(空)'}${totalRows > 3 ? '(其余行不进对话;统计用 mode=stats,分页翻看用 offset)' : ''}${stateTxt}`,
-    }
-  }
-  catch (err) {
-    if (err instanceof AppError && err.status === 404) return { text: err.message, isError: true }
-    return { text: `数据集读取失败:${err instanceof Error ? err.message : String(err)}`, isError: true }
-  }
-}
-
-/** 工具:mes_datasets —— 你可见的 CSV 数据集清单(新→旧;创建者/节点绑定/产线可读过滤)。
- *  用于找回 mes_fetch 异步作业的 dataset_id 与确认取数状态(替代轮询 job)。 */
-export async function toolMesDatasets(agentId: string, args: { limit?: number | string } = {}): Promise<{ text: string, isError?: boolean }> {
-  try {
-    const store = getMesDatasets()
-    const limit = Math.min(Math.max(Math.round(Number(args.limit)) || 20, 1), 100)
-    const visible = store.listDatasets(100).filter(ds => mesDatasetVisible(agentId, ds)).slice(0, limit)
-    if (visible.length === 0) {
-      return { text: '你还没有可见的 MES 数据集。用 mes_fetch(带 from/to 与较大 max_rows)创建;或刚创建的作业尚未登记(稍后再查)。' }
-    }
-    const running = visible.filter(ds => ds.status === 'running').length
-    return {
-      text: `MES 数据集清单(可见 ${visible.length} 条,新→旧${running > 0 ? `;其中 ${running} 条取数中 —— 勿轮询,未完成先做别的` : ''}):\n${visible.map(dsLine).join('\n')}\n\n说明:读统计用 mes_dataset_read(dataset_id, mode=stats);读分页/概览用 mode=head|rows。`,
-    }
-  }
-  catch (err) {
-    return { text: `数据集清单查询失败:${err instanceof Error ? err.message : String(err)}(服务未就绪时请稍后重试)。`, isError: true }
-  }
-}
+/**
+ * MES 数据集工具族(mes_catalog / mes_fetch / mes_dataset_read / mes_datasets)。
+ *
+ * 面向 Agent 的 MES REST 点位只读面:目录检索、历史取数(护栏在 mes-controller 代码级)、
+ * CSV 数据集读取与清单。铁律:MES 行级原文不进 prompt —— 所有回包只给统计摘要 + ≤3 行采样;
+ * 全量原文只落 <configRoot>/datasets/<id>.csv(见 services/workshop/mes/mes-datasets.ts)。
+ * 权限:fetch 按 dcw 绑线过滤(controller 内代码级);数据集读取/清单按
+ * 创建者 ∪ 节点绑定 ∪ 可读产线(agentOpsScope 既有路径)过滤。
+ */
+import type { MesDatasetRow, MesDatasetRead } from '../../mes/mes-datasets'
+import { getMesDatasets } from '../../mes/mes-datasets'
+import { createMesController } from '../../mes/mes-controller'
+import { agentOpsScope } from './ops-tools'
+import { AppError } from '../../../../utils/errors'
+
+/** 控制器单例(护栏依赖真实服务;无状态可安全复用) */
+let controller: ReturnType<typeof createMesController> | null = null
+function mesController(): ReturnType<typeof createMesController> {
+  controller ??= createMesController()
+  return controller
+}
+
+/** 数据集可见性:创建者 ∪ 节点绑定 ∪ 可读产线(节点授权线 ∪ 频道绑定线) */
+function mesDatasetVisible(agentId: string, ds: MesDatasetRow): boolean {
+  if (ds.createdBy === agentId) return true
+  const scope = agentOpsScope(agentId)
+  if (!scope) return false
+  if (scope.nodeIds.has(ds.nodeId)) return true
+  return !!ds.lineId && (scope.lineIds.includes(ds.lineId) || scope.boundLineIds.includes(ds.lineId))
+}
+
+/** 数据集行 → 一行摘要(id | 节点 | 窗口 | 行数 | 状态) */
+function dsLine(ds: MesDatasetRow): string {
+  const win = ds.fromTs && ds.toTs ? `${ds.fromTs.slice(5, 16).replace('T', ' ')} ~ ${ds.toTs.slice(5, 16).replace('T', ' ')}` : '当前值'
+  let state: string
+  if (ds.status === 'ready') state = `就绪(${ds.rows} 行,sha256 ${ds.sha256.slice(0, 8)})`
+  else if (ds.status === 'running') state = '取数中'
+  else state = `失败(${ds.error.slice(0, 80)})`
+  return `- ${ds.id} | ${ds.nodeName || ds.nodeId} | ${win} | ${state}`
+}
+
+/** 工具:mes_catalog —— MES REST 点位目录(数据驱动;q 子串/产线过滤;按调用者可读产线严格过滤:
+ *  跨产线与孤儿(未分配)点位不可见;未绑线的 agent 得到空目录 —— 与 mes_fetch 的授权口径一致)。 */
+export async function toolMesCatalog(agentId: string, args: { q?: string, line_id?: string, limit?: number | string } = {}): Promise<{ text: string, isError?: boolean }> {
+  try {
+    const scope = agentOpsScope(agentId)
+    const scopeLineIds = scope ? [...scope.lineIds] : []
+    const r = await mesController().catalog({ ...args, scope_line_ids: scopeLineIds })
+    if (r.entries.length === 0 && scopeLineIds.length === 0) {
+      return { text: '你还没有可读的产线绑定,无可见 MES 点位。先完成产线绑定与节点绑定后再用 mes_catalog。' }
+    }
+    return { text: r.text }
+  }
+  catch (err) {
+    return { text: `MES 点位目录查询失败:${err instanceof Error ? err.message : String(err)}(服务未就绪时请稍后重试)。`, isError: true }
+  }
+}
+
+/** 工具:mes_fetch —— MES 历史取数(护栏代码级:绑线授权/窗口≤7天/行数≤5000/每分钟≤6次)。
+ *  格式全谱:标量/向量(膜厚断面等)/图像帧(CCD,自动落盘)/表格/事件记录;按点位格式呈现统计与采样。
+ *  param 透传给节点已配置的 requestHook/dataHook(用户自写代码做请求构造与数据下沉处理,
+ *  处理摘要与产物清单随回包返回)。三模式:无 from/to=当前值快照;小窗口内联统计;
+ *  大请求异步落 CSV 数据集(回 job_id/dataset_id,勿轮询,用 mes_datasets 查状态)。
+ *  铁律:回包只含统计摘要与 ≤3 行采样,MES 行级原文不进对话。 */
+export async function toolMesFetch(agentId: string, args: { ids?: unknown, from?: string, to?: string, max_rows?: number | string, param?: unknown } = {}): Promise<{ text: string, isError?: boolean }> {
+  try {
+    const r = await mesController().fetch(agentId, args)
+    return { text: r.text, isError: r.isError }
+  }
+  catch (err) {
+    return { text: `MES 取数失败:${err instanceof Error ? err.message : String(err)}(驱动离线或点位配置缺失时常见;可先用 mes_catalog 确认点位)。`, isError: true }
+  }
+}
+
+/** 工具:mes_dataset_read —— 读 CSV 数据集(head=列名+总行数 / stats=统计 / rows=分页)。
+ *  权限:创建者或有该节点/产线可见权;回包同样只带 ≤3 行采样(原文不进 prompt)。 */
+export async function toolMesDatasetRead(agentId: string, args: { dataset_id?: string, mode?: string, offset?: number | string } = {}): Promise<{ text: string, isError?: boolean }> {
+  const datasetId = String(args.dataset_id ?? '').trim()
+  if (!datasetId) return { text: 'dataset_id 必填(mes_fetch 异步回包或 mes_datasets 清单里的 id)。', isError: true }
+  const modeArg = String(args.mode ?? 'head').trim()
+  const mode = modeArg === 'stats' || modeArg === 'rows' ? modeArg : 'head'
+  try {
+    const store = getMesDatasets()
+    const meta = store.datasetMeta(datasetId)
+    if (!meta) return { text: `数据集 ${datasetId} 不存在(用 mes_datasets 列出你可读的数据集)。`, isError: true }
+    if (!mesDatasetVisible(agentId, meta)) {
+      return { text: `无权读取数据集 ${datasetId}(仅创建者、该节点绑定者或该产线可读者可读)。`, isError: true }
+    }
+    const r: MesDatasetRead = store.readDataset(datasetId, mode, Number(args.offset) || 0)
+    const stateTxt = meta.status === 'ready' ? '' : meta.status === 'running' ? '\n注意:数据集仍在取数中,当前为已写入部分。' : `\n注意:取数已失败:${meta.error.slice(0, 120)}(以下为失败前已写入部分)。`
+    if (r.mode === 'stats') {
+      const s = r.stats
+      const f4 = (v: number | null | undefined): string => v == null || !Number.isFinite(v) ? '-' : String(Number(v.toFixed(4)))
+      return {
+        text: `数据集 ${datasetId} 统计(${meta.nodeName || meta.nodeId},产线 ${meta.lineId || '未分配'}):\n`
+          + `  数值行数 ${s.count} | 首 ${s.firstTs ?? '-'} ~ 末 ${s.lastTs ?? '-'}\n`
+          + `  min ${f4(s.min)} / max ${f4(s.max)} / mean ${f4(s.mean)} / stddev ${f4(s.stddev)}\n`
+          + `  文件 sha256 ${meta.sha256.slice(0, 16)}${stateTxt}`,
+      }
+    }
+    // head / rows:列名+行数+分页游标,采样 ≤3 行(原文不进 prompt)
+    let headTxt: string
+    let totalRows: number
+    let sample: string[]
+    if (r.mode === 'head') {
+      headTxt = `数据集 ${datasetId} 概览(${meta.nodeName || meta.nodeId},产线 ${meta.lineId || '未分配'}):\n  列名: ${r.head.columns.join(', ')}\n  总行数: ${r.head.totalRows}\n`
+      totalRows = r.head.totalRows
+      sample = r.head.preview.slice(0, 3).map(row => row.join(','))
+    }
+    else {
+      headTxt = `数据集 ${datasetId} 第 ${r.rowsView.offset} 行起的分页(每页 20 行,共 ${r.rowsView.total} 行;本页 ${r.rowsView.rows.length} 行):\n`
+      totalRows = r.rowsView.total
+      sample = r.rowsView.rows.slice(0, 3).map(row => row.join(','))
+    }
+    return {
+      text: `${headTxt}采样(≤3 行,ts,value): ${sample.join(' | ') || '(空)'}${totalRows > 3 ? '(其余行不进对话;统计用 mode=stats,分页翻看用 offset)' : ''}${stateTxt}`,
+    }
+  }
+  catch (err) {
+    if (err instanceof AppError && err.status === 404) return { text: err.message, isError: true }
+    return { text: `数据集读取失败:${err instanceof Error ? err.message : String(err)}`, isError: true }
+  }
+}
+
+/** 工具:mes_datasets —— 你可见的 CSV 数据集清单(新→旧;创建者/节点绑定/产线可读过滤)。
+ *  用于找回 mes_fetch 异步作业的 dataset_id 与确认取数状态(替代轮询 job)。 */
+export async function toolMesDatasets(agentId: string, args: { limit?: number | string } = {}): Promise<{ text: string, isError?: boolean }> {
+  try {
+    const store = getMesDatasets()
+    const limit = Math.min(Math.max(Math.round(Number(args.limit)) || 20, 1), 100)
+    const visible = store.listDatasets(100).filter(ds => mesDatasetVisible(agentId, ds)).slice(0, limit)
+    if (visible.length === 0) {
+      return { text: '你还没有可见的 MES 数据集。用 mes_fetch(带 from/to 与较大 max_rows)创建;或刚创建的作业尚未登记(稍后再查)。' }
+    }
+    const running = visible.filter(ds => ds.status === 'running').length
+    return {
+      text: `MES 数据集清单(可见 ${visible.length} 条,新→旧${running > 0 ? `;其中 ${running} 条取数中 —— 勿轮询,未完成先做别的` : ''}):\n${visible.map(dsLine).join('\n')}\n\n说明:读统计用 mes_dataset_read(dataset_id, mode=stats);读分页/概览用 mode=head|rows。`,
+    }
+  }
+  catch (err) {
+    return { text: `数据集清单查询失败:${err instanceof Error ? err.message : String(err)}(服务未就绪时请稍后重试)。`, isError: true }
+  }
+}