agentworkshop 0.8.7 → 0.9.0

package/server/services/workshop/agents/industrial/bench-approval-only.ts

@@ -0,0 +1,394 @@
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { closeSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { networkInterfaces } from 'node:os'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+
+type TrialTarget = { id: string, driver: string, driverConfig: Record<string, unknown> }
+type TrialParam = { node_id: string, value: number }
+type PilotArm = 'ON' | 'OFF'
+type PilotCase = 'legal-approved' | 'legal-rejected' | 'out-of-range-approved'
+type Qualification = {
+  schema_version: 2
+  run_id: string
+  episode_id: string
+  arm: 'OFF'
+  case: PilotCase
+  aw_home: string
+  aw_base: string
+  sim_base: string
+  simulator_root: string
+  simulator_pid: number
+  line_id: string
+  recipe_id: string
+  actor_id: string
+  hypothesis: string
+  params: TrialParam[]
+  configuration_sha256: string
+  fixture_sha256: string
+  manifest_sha256: string
+  expires_at_utc: string
+  nodes: Array<{ node_id: string, driver: string, driver_config_sha256: string, host?: string, port?: number }>
+}
+
+type Manifest = {
+  schema_version: 'a1-approval-pilot-v1'
+  run_id: string
+  study_type: 'descriptive-pilot'
+  configuration_sha256: string
+  network_isolation: { mode: 'docker-network-none', loopback_only: true }
+  episodes: Array<{
+    episode_id: string
+    case: PilotCase
+    arm_order: PilotArm[]
+    actor_id: string
+    line_id: string
+    recipe_id: string
+    hypothesis: string
+    params: TrialParam[]
+    fixture_sha256: string
+  }>
+}
+
+export type ApprovalOnlyTrialReceipt = {
+  approval_bypassed: true
+  run_id: string
+  episode_id: string
+  arm: 'OFF'
+  case: PilotCase
+  invocation_id: string
+  configuration_sha256: string
+  fixture_sha256: string
+}
+
+type TrialCheckInput = {
+  stage: 'approval' | 'dispatch'
+  invocationId: string
+  actorId: string
+  recipeId: string
+  line: { id: string, simulated?: boolean } | undefined
+  nodes: TrialTarget[]
+  hypothesis: string
+  params: TrialParam[]
+}
+
+function sha256(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
+  if (value && typeof value === 'object') {
+    return `{${Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+/** Digest of the exact actor, recipe, target driver configuration, candidate and rationale. */
+export function approvalOnlyFixtureSha256(input: Omit<TrialCheckInput, 'stage' | 'invocationId'>): string {
+  const projection = {
+    schema_version: 1,
+    actor_id: input.actorId,
+    line_id: input.line?.id ?? '',
+    recipe_id: input.recipeId,
+    hypothesis: input.hypothesis,
+    params: input.params.map(param => ({ node_id: param.node_id, value: Number(param.value) })).sort((a, b) => a.node_id.localeCompare(b.node_id)),
+    nodes: input.nodes.map(node => ({
+      node_id: node.id,
+      driver: node.driver,
+      driver_config_sha256: sha256(stableJson(node.driverConfig)),
+    })).sort((a, b) => a.node_id.localeCompare(b.node_id)),
+  }
+  return sha256(stableJson(projection))
+}
+
+function loopbackUrl(raw: string | undefined, label: string): URL {
+  const url = new URL(raw ?? '')
+  if (!['http:', 'https:'].includes(url.protocol) || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+    || !url.port || url.username || url.password || url.search || url.hash || !['', '/'].includes(url.pathname)) {
+    throw new Error(`${label} must be an explicit loopback service URL`)
+  }
+  return url
+}
+
+function targetEndpoint(node: TrialTarget): { host: string, port: number } {
+  let host: string
+  let port: number
+  if (node.driver === 'opcua') {
+    const endpoint = new URL(String(node.driverConfig.endpoint ?? ''))
+    if (endpoint.protocol !== 'opc.tcp:' || endpoint.username || endpoint.password) throw new Error('unsupported OPC UA simulator endpoint')
+    host = endpoint.hostname
+    port = Number(endpoint.port)
+  }
+  else if (node.driver === 'modbus-tcp') {
+    host = String(node.driverConfig.host ?? '')
+    port = Number(node.driverConfig.port)
+  }
+  else throw new Error(`driver ${node.driver} is not permitted for approval-only trials`)
+  if (!['127.0.0.1', 'localhost', '[::1]', '::1'].includes(host) || !Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new Error('approval-only trials require loopback simulator driver endpoints')
+  }
+  return { host, port }
+}
+
+function assertListener(port: number, pid: number): void {
+  if (process.platform === 'win32') {
+    const rows = execFileSync('netstat.exe', ['-ano', '-p', 'tcp'], { encoding: 'utf8', timeout: 8000, maxBuffer: 4 * 1024 * 1024 })
+      .split(/\r?\n/).map(line => line.trim().split(/\s+/))
+      .filter(parts => parts[0] === 'TCP' && parts[3]?.toUpperCase() === 'LISTENING' && parts[1]?.endsWith(`:${port}`))
+    if (!rows.length || rows.some(parts => Number(parts[4]) !== pid || !['127.0.0.1', '[::1]'].includes(parts[1]!.slice(0, -(String(port).length + 1))))) {
+      throw new Error(`listener ownership or loopback binding is unverified for port ${port}`)
+    }
+    return
+  }
+  if (process.platform !== 'linux') throw new Error('listener ownership verification is supported only on Windows or Linux')
+  const output = execFileSync('ss', ['-ltnpH'], { encoding: 'utf8', timeout: 8000, maxBuffer: 4 * 1024 * 1024 })
+  const matching = output.split(/\r?\n/).filter(line => line.trim().split(/\s+/)[3]?.endsWith(`:${port}`))
+  if (!matching.length || matching.some((line) => {
+    const parts = line.trim().split(/\s+/)
+    const local = parts[3]?.slice(0, -(String(port).length + 1))
+    const owners = [...line.matchAll(/pid=(\d+)/g)].map(match => Number(match[1]))
+    return !['127.0.0.1', '[::1]'].includes(local ?? '') || owners.length !== 1 || owners[0] !== pid
+  })) {
+    throw new Error(`listener ownership or loopback binding is unverified for port ${port}`)
+  }
+}
+
+export function assertLoopbackOnlyNetworkNamespace(interfaces: ReturnType<typeof networkInterfaces>): void {
+  if (process.platform !== 'linux') throw new Error('approval-only trials require a Linux network namespace with verified no-egress isolation')
+  const names = Object.keys(interfaces)
+  const loopbackAddresses = interfaces.lo ?? []
+  if (names.length !== 1 || names[0] !== 'lo' || loopbackAddresses.length === 0
+    || loopbackAddresses.some(address => !address?.internal || !['127.0.0.1', '::1'].includes(address.address))) {
+    throw new Error('approval-only trials require a loopback-only network namespace')
+  }
+  const routes = readFileSync('/proc/net/route', 'utf8').trim().split(/\r?\n/).slice(1)
+  if (routes.some((line) => {
+    const parts = line.trim().split(/\s+/)
+    return parts[1] === '00000000' && parts[0] !== 'lo'
+  })) throw new Error('approval-only network namespace has an IPv4 default route via a non-loopback interface')
+  const routes6 = readFileSync('/proc/net/ipv6_route', 'utf8').trim().split(/\r?\n/)
+  if (routes6.some((line) => {
+    const parts = line.trim().split(/\s+/)
+    return /^0{32}$/.test(parts[1] ?? '') && parts[2] === '00' && parts[0] !== 'lo'
+  })) {
+    throw new Error('approval-only network namespace has an IPv6 default route via a non-loopback interface')
+  }
+}
+
+function configurationSha256(configuration: Record<string, unknown>): string {
+  const projection = { ...configuration }
+  delete projection.configuration_sha256
+  return sha256(stableJson(projection))
+}
+
+function readRegularJson(path: string, label: string): { value: Record<string, unknown>, bytes: Buffer } {
+  const stat = lstatSync(path)
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${label} must be a regular non-symlink file`)
+  const bytes = readFileSync(path)
+  return { value: JSON.parse(bytes.toString('utf8')) as Record<string, unknown>, bytes }
+}
+
+function readClaim(path: string): Record<string, unknown> {
+  return readRegularJson(path, 'approval-only one-shot claim').value
+}
+
+function withClaimLock<T>(home: string, callback: () => T): T {
+  const lockPath = join(home, 'approval-only-claim.lock')
+  let fd: number
+  try {
+    fd = openSync(lockPath, 'wx', 0o600)
+  }
+  catch (err) {
+    throw new Error(`approval-only qualification is busy or has a stale lock: ${err instanceof Error ? err.message : String(err)}`, { cause: err })
+  }
+  try {
+    writeFileSync(fd, `${process.pid}\n`, 'utf8')
+    fsyncSync(fd)
+    return callback()
+  }
+  finally {
+    closeSync(fd)
+    // A process crash may leave the exclusive lock behind; that intentionally fails closed.
+    rmSync(lockPath, { force: true })
+  }
+}
+
+function receiptOf(q: Qualification, invocationId: string): ApprovalOnlyTrialReceipt {
+  return {
+    approval_bypassed: true,
+    run_id: q.run_id,
+    episode_id: q.episode_id,
+    arm: q.arm,
+    case: q.case,
+    invocation_id: invocationId,
+    configuration_sha256: q.configuration_sha256,
+    fixture_sha256: q.fixture_sha256,
+  }
+}
+
+export function sameApprovalOnlyTrialReceipt(
+  first: ApprovalOnlyTrialReceipt | null | undefined,
+  second: ApprovalOnlyTrialReceipt | null | undefined,
+): boolean {
+  return Boolean(first && second
+    && first.approval_bypassed === true && second.approval_bypassed === true
+    && first.run_id === second.run_id
+    && first.episode_id === second.episode_id
+    && first.arm === 'OFF' && second.arm === 'OFF'
+    && first.case === second.case
+    && first.invocation_id === second.invocation_id
+    && first.configuration_sha256 === second.configuration_sha256
+    && first.fixture_sha256 === second.fixture_sha256)
+}
+
+function validate(input: TrialCheckInput): { q: Qualification, home: string, claimPath: string } {
+  if (!input.invocationId || input.invocationId.length > 160) throw new Error('trusted invocation id is required')
+  const runId = process.env.AW_AGENTTEAM_RUN_ID ?? ''
+  const episodeId = process.env.AW_BENCH_APPROVAL_ONLY_EPISODE_ID ?? ''
+  if (!/^[a-zA-Z0-9_-]{8,80}$/.test(runId) || process.env.AW_BENCH_APPROVAL_ONLY_ACK !== runId) throw new Error('run confirmation mismatch')
+  if (!/^[a-zA-Z0-9_-]{8,80}$/.test(episodeId) || process.env.AW_BENCH_APPROVAL_ONLY_ARM !== 'OFF') throw new Error('episode or manifest arm confirmation mismatch')
+  if (!/^[a-f0-9]{64}$/.test(process.env.AW_BENCH_APPROVAL_ONLY_MANIFEST_SHA256 ?? '')
+    || !/^[a-f0-9]{64}$/.test(process.env.AW_BENCH_APPROVAL_ONLY_CONFIG_SHA256 ?? '')) throw new Error('manifest/configuration digest confirmation is invalid')
+  if (process.env.AW_MODE !== 'home' || (process.env.AW_BENCH_MODE && process.env.AW_BENCH_MODE !== '0')) throw new Error('home mode is required and AW_BENCH_MODE must be disabled')
+
+  const rawHome = process.env.AW_HOME ?? ''
+  if (!isAbsolute(rawHome)) throw new Error('an explicit isolated AW_HOME is required')
+  const home = realpathSync(rawHome)
+  if (basename(home) !== 'aw-home' || basename(dirname(home)) !== 'OFF' || basename(dirname(dirname(home))) !== episodeId
+    || basename(dirname(dirname(dirname(home)))) !== 'episodes'
+    || basename(dirname(dirname(dirname(dirname(home))))) !== 'runtime'
+    || basename(dirname(dirname(dirname(dirname(dirname(home)))))) !== `${runId}-approval-ablation`) {
+    throw new Error('AW_HOME must be this run/episode OFF arm runtime directory')
+  }
+  if (resolve(rawHome) !== home) throw new Error('AW_HOME must not traverse a symlink')
+  const runRoot = dirname(dirname(dirname(dirname(dirname(home)))))
+  const expectedHome = join(runRoot, 'runtime', 'episodes', episodeId, 'OFF', 'aw-home')
+  if (home !== realpathSync(expectedHome)) throw new Error('AW_HOME path does not match the qualified OFF episode')
+
+  const aw = loopbackUrl(process.env.AW_BASE, 'AW_BASE')
+  const sim = loopbackUrl(process.env.SIM_BASE, 'SIM_BASE')
+  if (Number(sim.port) === 4010 || Number(aw.port) === 3001) throw new Error('shared default service ports are forbidden')
+
+  const qualificationPath = join(home, 'approval-only-qualification.json')
+  const { value: parsed } = readRegularJson(qualificationPath, 'approval-only qualification')
+  const q = parsed as unknown as Qualification
+  const expiry = Date.parse(q.expires_at_utc)
+  if (q.schema_version !== 2 || q.run_id !== runId || q.episode_id !== episodeId || q.arm !== 'OFF'
+    || resolve(q.aw_home) !== home || q.aw_base !== aw.origin || q.sim_base !== sim.origin
+    || q.configuration_sha256 !== process.env.AW_BENCH_APPROVAL_ONLY_CONFIG_SHA256
+    || q.manifest_sha256 !== process.env.AW_BENCH_APPROVAL_ONLY_MANIFEST_SHA256
+    || !Number.isFinite(expiry) || expiry <= Date.now() || expiry - Date.now() > 10 * 60_000) {
+    throw new Error('qualification is mismatched, expired, or not bound to this OFF episode')
+  }
+  if (!input.line?.simulated || q.line_id !== input.line.id || q.recipe_id !== input.recipeId || q.actor_id !== input.actorId
+    || q.hypothesis !== input.hypothesis || input.nodes.length !== 1 || input.params.length !== 1 || !Array.isArray(q.nodes)) {
+    throw new Error('the qualified simulated line, actor, recipe, candidate, and single target are required')
+  }
+  const sameParams = q.params.length === input.params.length && q.params.every((param, index) =>
+    param.node_id === input.params[index]?.node_id && Number(param.value) === Number(input.params[index]?.value))
+  if (!sameParams) throw new Error('candidate values differ from the qualified episode')
+
+  const endpoints = input.nodes.map((node) => {
+    const allowed = q.nodes.filter(entry => entry.node_id === node.id)
+    const hash = sha256(stableJson(node.driverConfig))
+    if (allowed.length !== 1 || allowed[0]!.driver !== node.driver || allowed[0]!.driver_config_sha256 !== hash) throw new Error('target or driver configuration differs from qualification')
+    const endpoint = targetEndpoint(node)
+    if (allowed[0]!.host !== endpoint.host || allowed[0]!.port !== endpoint.port) throw new Error('driver endpoint differs from qualification')
+    return endpoint
+  })
+  const fixtureSha = approvalOnlyFixtureSha256(input)
+  if (q.fixture_sha256 !== fixtureSha) throw new Error('actor/recipe/node/value/schema fixture digest mismatch')
+
+  const { value: manifest, bytes: manifestBytes } = readRegularJson(join(runRoot, 'manifest.json'), 'A1 pilot manifest')
+  const { value: configuration } = readRegularJson(join(runRoot, 'configuration.json'), 'A1 pilot configuration')
+  if (sha256(manifestBytes) !== q.manifest_sha256 || configurationSha256(configuration) !== q.configuration_sha256
+    || manifest.schema_version !== 'a1-approval-pilot-v1' || manifest.run_id !== runId
+    || manifest.study_type !== 'descriptive-pilot' || manifest.configuration_sha256 !== q.configuration_sha256
+    || stableJson(manifest.network_isolation) !== stableJson({ mode: 'docker-network-none', loopback_only: true })
+    || configuration.run_id !== runId || configuration.configuration_sha256 !== q.configuration_sha256) {
+    throw new Error('run manifest/configuration changed after episode qualification')
+  }
+  const registered = (manifest.episodes as Manifest['episodes'] | undefined)?.filter(row => row.episode_id === episodeId) ?? []
+  if (registered.length !== 1) throw new Error('episode id is absent or duplicated in the frozen manifest')
+  const row = registered[0]!
+  if (row.case !== q.case || row.arm_order.length !== 2 || [...row.arm_order].sort().join(',') !== 'OFF,ON'
+    || row.actor_id !== q.actor_id || row.line_id !== q.line_id
+    || row.recipe_id !== q.recipe_id || row.hypothesis !== q.hypothesis || row.fixture_sha256 !== q.fixture_sha256
+    || stableJson(row.params) !== stableJson(q.params)) throw new Error('episode qualification differs from its preregistered manifest row')
+
+  assertLoopbackOnlyNetworkNamespace(networkInterfaces())
+  const simRoot = realpathSync(q.simulator_root)
+  if (simRoot !== realpathSync(join(runRoot, 'runtime', 'episodes', episodeId, 'OFF', 'simulator')) || !Number.isInteger(q.simulator_pid) || q.simulator_pid <= 0) {
+    throw new Error('private simulator root/PID mismatch')
+  }
+  const commandLine = readFileSync(`/proc/${q.simulator_pid}/cmdline`, 'utf8').replaceAll('\0', ' ').replaceAll('\\', '/').toLowerCase()
+  if (!process.kill(q.simulator_pid, 0)) throw new Error('simulator PID is not alive')
+  if (!commandLine.includes(`${simRoot.replaceAll('\\', '/').toLowerCase()}/src/server/index.ts`)) throw new Error('simulator PID does not own this run\'s entry point')
+  assertListener(Number(aw.port), process.pid)
+  for (const port of new Set([Number(sim.port), ...endpoints.map(endpoint => endpoint.port)])) assertListener(port, q.simulator_pid)
+  return { q, home, claimPath: join(home, 'approval-only-claim.json') }
+}
+
+/** Validate the fixed OFF episode at approval time, then require atomic one-shot dispatch consumption. */
+export function approvalOnlyTrialReceipt(input: TrialCheckInput): ApprovalOnlyTrialReceipt | null {
+  const requested = process.env.AW_BENCH_APPROVAL_ONLY
+  if (requested == null || requested === '' || requested === '0') return null
+  try {
+    if (requested !== '1') throw new Error('AW_BENCH_APPROVAL_ONLY must be 1 or disabled')
+    const { q, home, claimPath } = validate(input)
+    return withClaimLock(home, () => {
+      if (input.stage === 'approval') {
+        const claim = {
+          schema_version: 1,
+          state: 'claimed',
+          run_id: q.run_id,
+          episode_id: q.episode_id,
+          invocation_id: input.invocationId,
+          arm: q.arm,
+          case: q.case,
+          configuration_sha256: q.configuration_sha256,
+          fixture_sha256: q.fixture_sha256,
+          claimed_at_utc: new Date().toISOString(),
+        }
+        const fd = openSync(claimPath, 'wx', 0o600)
+        try {
+          writeFileSync(fd, `${JSON.stringify(claim, null, 2)}\n`, 'utf8')
+          fsyncSync(fd)
+        }
+        finally { closeSync(fd) }
+      }
+      else {
+        const existing = readClaim(claimPath)
+        if (existing.state !== 'claimed' || existing.run_id !== q.run_id || existing.episode_id !== q.episode_id
+          || existing.arm !== 'OFF' || existing.invocation_id !== input.invocationId
+          || existing.fixture_sha256 !== q.fixture_sha256 || existing.configuration_sha256 !== q.configuration_sha256) {
+          throw new Error('dispatch does not match the claimed one-shot episode/invocation')
+        }
+        const consumedPath = join(home, 'approval-only-consumed.json')
+        const consumed = {
+          schema_version: 1,
+          state: 'consumed-before-dispatch',
+          run_id: q.run_id,
+          episode_id: q.episode_id,
+          invocation_id: input.invocationId,
+          arm: q.arm,
+          case: q.case,
+          configuration_sha256: q.configuration_sha256,
+          fixture_sha256: q.fixture_sha256,
+          consumed_at_utc: new Date().toISOString(),
+        }
+        const fd = openSync(consumedPath, 'wx', 0o600)
+        try {
+          writeFileSync(fd, `${JSON.stringify(consumed, null, 2)}\n`, 'utf8')
+          fsyncSync(fd)
+        }
+        finally { closeSync(fd) }
+      }
+      return receiptOf(q, input.invocationId)
+    })
+  }
+  catch (err) {
+    throw new Error(`Approval-only trial refused: ${err instanceof Error ? err.message : String(err)}`, { cause: err })
+  }
+}

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

@@ -31,17 +31,27 @@ export function daqTargetsOf(agentId: string, nodeIdArg: unknown, lineIdArg: unk
   if (readable.size === 0) {
     return { error: { text: '你尚未绑定任何数采节点,频道也未绑定产线,无权查询采集数据。请在数字孪生界面绑定数采节点,或将频道绑定到目标产线(绑线后可只读查询该线数采数据)。', isError: true } }
   }
-  const wanted = nodeIdArg ? String(nodeIdArg) : ''
-  if (wanted && !readable.has(wanted)) {
-    return { error: { text: `无权查询节点 ${wanted}。你有权访问的数采节点:${[...readable].join(', ')}`, isError: true } }
+  const wantedList = (Array.isArray(nodeIdArg)
+    ? nodeIdArg.map(v => String(v))
+    : String(nodeIdArg ?? '').split(','))
+    .map(s => s.trim())
+    .filter(Boolean)
+  if (wantedList.length > 20) {
+    return { error: { text: `一次最多查询 20 个数采节点(收到 ${wantedList.length});请分组查询或按 line_id 过滤。`, isError: true } }
+  }
+  for (const w of wantedList) {
+    if (!readable.has(w)) {
+      return { error: { text: `无权查询节点 ${w}。你有权访问的数采节点:${[...readable].join(', ')}`, isError: true } }
+    }
   }
   const lineFilter = lineIdArg ? String(lineIdArg).trim() : ''
   const lineOf = (id: string): string => getDaqNodeRepo().byId(id)?.lineId ?? ''
-  if (lineFilter && wanted && lineOf(wanted) !== lineFilter) {
-    return { error: { text: `节点 ${wanted} 不属于产线 ${lineFilter}(实际归属:${lineOf(wanted) || '未分配'}),line_id 与 node_id 过滤冲突。`, isError: true } }
+  const wrongLine = lineFilter ? wantedList.filter(id => lineOf(id) !== lineFilter) : []
+  if (wrongLine.length > 0) {
+    return { error: { text: `节点 ${wrongLine.join(', ')} 不属于产线 ${lineFilter}(实际归属:${wrongLine.map(id => lineOf(id) || '未分配').join('/')}),line_id 与 node_id 过滤冲突。`, isError: true } }
   }
-  let targets = wanted ? [wanted] : [...readable]
-  if (lineFilter && !wanted) {
+  let targets = wantedList.length > 0 ? wantedList : [...readable]
+  if (lineFilter && wantedList.length === 0) {
     const onLine = targets.filter(id => lineOf(id) === lineFilter)
     if (onLine.length === 0) {
       return { error: { text: `你有权访问的数采节点中没有归属产线 ${lineFilter} 的(各节点归属:${[...readable].map(id => `${id}=${lineOf(id) || '未分配'}`).join('; ')})。`, isError: true } }
@@ -61,42 +71,64 @@ export function daqTargetsOf(agentId: string, nodeIdArg: unknown, lineIdArg: unk
  * 只取当前配方 3 点/均值 247.99,差异足以改变 keep/rollback 结论)。
  * 需要跨配方对比或历史复盘时显式传 `scope: 'all'`(或直接给 product_id/recipe_id/run_id)。
  */
+/** 时间参数解析:epoch 毫秒 或 ISO 8601(含 date-only、带时区偏移);非法 → null(调用方必须报错) */
+function epochOfArg(v: unknown): number | null {
+  if (v == null) return null
+  const s = String(v).trim()
+  if (!s) return null
+  if (/^\d+$/.test(s)) {
+    const n = Number(s)
+    return Number.isFinite(n) && n > 0 ? n : null
+  }
+  const ms = Date.parse(s)
+  return Number.isFinite(ms) ? ms : null
+}
+
 export async function toolDaqQuery(agentId: string, args: {
   node_id?: string
+  /** 多字段查询(逗号分隔或数组;与 node_id 二选一,最多 20 个) */
+  node_ids?: string | string[]
   line_id?: string
   product_id?: string
   recipe_id?: string
   run_id?: string
   scope?: string
   last_minutes?: number | string
+  /** 起始时间:ISO 8601(如 2026-10-01T08:00:00+08:00)或 epoch 毫秒 */
+  from?: string | number
+  /** 结束时间:同上;缺省 = now */
+  to?: string | number
   from_ms?: number | string
   to_ms?: number | string
   bucket_ms?: number | string
   limit?: number | string
   agg?: string
 }): Promise<{ text: string, isError?: boolean }> {
-  const auth = daqTargetsOf(agentId, args.node_id, args.line_id)
+  const auth = daqTargetsOf(agentId, args.node_ids ?? args.node_id, args.line_id)
   if ('error' in auth) return auth.error
   const { targets } = auth
   const lineFilter = args.line_id ? String(args.line_id).trim() : ''
 
   // 参数校验:显式传入的非法值必须报错,不能静默回退(否则 Agent 以为按自己的窗口/条数查了)
   const provided = (v: unknown): boolean => v !== undefined && v !== null && String(v).trim() !== ''
-  if (provided(args.to_ms) && (!Number.isFinite(Number(args.to_ms)) || Number(args.to_ms) <= 0)) {
-    return { text: `to_ms 必须是正的 epoch 毫秒(收到 ${String(args.to_ms)})。`, isError: true }
+  const toArg = args.to ?? args.to_ms
+  const fromArg = args.from ?? args.from_ms
+  const toParsed = epochOfArg(toArg)
+  if (provided(toArg) && toParsed == null) {
+    return { text: `to 必须是 ISO 8601 时间(如 2026-10-01T08:00:00+08:00)或正的 epoch 毫秒(收到 ${String(toArg)})。`, isError: true }
   }
-  if (provided(args.from_ms) && (!Number.isFinite(Number(args.from_ms)) || Number(args.from_ms) <= 0)) {
-    return { text: `from_ms 必须是正的 epoch 毫秒(收到 ${String(args.from_ms)})。`, isError: true }
+  const fromParsed = epochOfArg(fromArg)
+  if (provided(fromArg) && fromParsed == null) {
+    return { text: `from 必须是 ISO 8601 时间(如 2026-10-01T08:00:00+08:00)或正的 epoch 毫秒(收到 ${String(fromArg)})。`, isError: true }
   }
   if (provided(args.last_minutes) && (!Number.isFinite(Number(args.last_minutes)) || Number(args.last_minutes) <= 0)) {
     return { text: `last_minutes 必须大于 0(收到 ${String(args.last_minutes)})。`, isError: true }
   }
-  const toMs = provided(args.to_ms) ? Number(args.to_ms) : Date.now()
-  const fromMs = provided(args.from_ms)
-    ? Number(args.from_ms)
-    : toMs - (provided(args.last_minutes) ? Number(args.last_minutes) : 30) * 60_000
+  const toMs = toParsed ?? Date.now()
+  const fromMs = fromParsed
+    ?? toMs - (provided(args.last_minutes) ? Number(args.last_minutes) : 30) * 60_000
   if (fromMs >= toMs) {
-    return { text: `时间窗非法:from_ms(${fromMs})必须小于 to_ms(${toMs})。`, isError: true }
+    return { text: `时间窗非法:from(${fromMs})必须小于 to(${toMs})。`, isError: true }
   }
   // 聚合口径:avg(缺省)/min/max 作用于降采样桶;最新值始终取库内最后一条原始样本
   const aggRaw = String(args.agg ?? '').trim().toLowerCase()
@@ -126,9 +158,13 @@ export async function toolDaqQuery(agentId: string, args: {
   /** scope=all:显式要求不过滤(跨配方/历史复盘),仅在无显式 id 时生效 */
   const wantAll = !explicitScoped && String(args.scope ?? '').trim().toLowerCase() === 'all'
 
-  const { getTsdb, tsdbReady } = await import('../../daq/storage')
+  const { getTsdb, tsdbReady, tsdbQueryHistory, tsdbRetentionInfo } = await import('../../daq/storage')
   await tsdbReady
   const tsdb = getTsdb()
+  // 分层保留:窗口早于原始样本保留期 → 自动改走 1m/1h 聚合(不静默返回空)
+  const rawRetentionH = tsdbRetentionInfo().rawRetentionH
+  const rawCutoffMs = Date.now() - rawRetentionH * 3_600_000
+  const needHistory = fromMs < rawCutoffMs
   // 各节点库内最新样本(用于「库内滞后」;查询本身走 tail 取窗口末尾,末元素才是最新)
   let latestMap = new Map<string, { tsMs: number, value: number }>()
   try {
@@ -161,9 +197,31 @@ export async function toolDaqQuery(agentId: string, args: {
     applied.push({ nodeId, lineId: nodeLine, runId: scopeRun.runId, recipeId: scopeRun.recipeId, source: scopeRun.source })
     try {
       let points: Array<{ at: number, value?: number, avg?: number, min?: number, max?: number, cnt?: number }>
+      let historyNote = ''
       // 是否有可用的打标过滤:显式 id、或活动批次(配方/批次 id 齐备)
       const useTagged = Boolean(scopeRun.recipeId || scopeRun.runId || scopeRun.productId)
-      if (useTagged) {
+      if (needHistory) {
+        // 超出原始保留期:走分层历史(1m/1h 聚合;跨边界时老段聚合 + 新段原始)
+        const h = await tsdbQueryHistory(nodeId, {
+          fromMs,
+          toMs,
+          bucketMs,
+          limit,
+          lineId: nodeLine || undefined,
+          productId: scopeRun.productId,
+          recipeId: scopeRun.recipeId,
+          runId: scopeRun.runId,
+        })
+        points = h.points
+        const label = h.resolution === 'minute'
+          ? '1 分钟聚合'
+          : h.resolution === 'hour' ? '1 小时聚合' : h.resolution === 'mixed' ? '聚合+原始拼接' : '原始样本'
+        historyNote = `数据分辨率=${label};${h.coverage.note}`
+        if (h.coverage.availableFromMs != null && h.coverage.availableFromMs > fromMs) {
+          historyNote += `;实际最早可查 ${new Date(h.coverage.availableFromMs).toISOString().slice(0, 16)}`
+        }
+      }
+      else if (useTagged) {
         const series = await queryTaggedLatest(tsdb, {
           lineId: nodeLine || undefined,
           productId: scopeRun.productId,
@@ -187,7 +245,8 @@ export async function toolDaqQuery(agentId: string, args: {
           : wantAll
             ? '全量窗口(scope=all,不做配方过滤)'
             : '未过滤(该产线当前未开跑 → 无活动批次可限定)'
-      const head = `■ ${node.name}(${ch})单位 ${node.unit},正常量程 ${node.min}~${node.max}${node.unit},当前状态 ${node.state},时间窗 ${new Date(fromMs).toISOString().slice(0, 16)} ~ ${new Date(toMs).toISOString().slice(0, 16)}(降采样 ${bucketMs}ms,聚合 ${agg})\n  ${scopeTag}`
+      // 表头携带节点 id(2026-10-30):多节点查询时模型/人可把数值精确回指到节点
+      const head = `■ ${node.name}[id=${nodeId}](${ch})单位 ${node.unit},正常量程 ${node.min}~${node.max}${node.unit},当前状态 ${node.state},时间窗 ${new Date(fromMs).toISOString().slice(0, 16)} ~ ${new Date(toMs).toISOString().slice(0, 16)}(降采样 ${bucketMs}ms,聚合 ${agg})\n  ${scopeTag}${historyNote ? `\n  ${historyNote}` : ''}`
       // 工况判读容器(具体判读在 values 计算后追加)
       const readout: string[] = []
       if (points.length === 0) {

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

@@ -7,6 +7,7 @@ import { agentBadgeLabel } from '../agent-badge'
 import { findDcwTemplate } from '../../dcw/dcw-templates'
 import { getActiveLineRun } from '../../dcw/line-run'
 import { getAgentNodeBindingRepo } from '../node-bindings.repo'
+import { scientificPayloadForWrite } from './identifiability-tools'
 import { getDaqNodeRepo } from '../../daq/daq-node.repo'
 import { getDcwController } from '../../dcw/dcw-controller'
 import { getDcwLineRepo } from '../../dcw/dcw-line.repo'
@@ -198,16 +199,20 @@ async function dcwControlGovernedLegacy(agentId: string, args: { node_id?: strin
     return { text: '自动模式下发必须附带 hypothesis(本次假设与依据:数采证据/判定结论)。请先 daq_query 取数判读,再带依据下发。', isError: true }
   }
   let manualFeedback = ''
+  let approvalId = ''
   if (needsApproval) {
     const bd = limitsBreakdownOf(node)
     const via = recipeBinding && authorizedRecipe
       ? `经配方授权「${authorizedRecipe.name}」${lineManual ? '(产线手动模式)' : ''}${channelManual ? '(频道手动模式)' : ''}`
       : (channelManual ? '(频道手动模式)' : '')
+    // P5 审批卡科学载荷:上次可辨识性判定 + 可证伪方式(卡片自动填,不再只有散文)
+    const sci = scientificPayloadForWrite(nodeId, node.name, value)
     const ap = await requestManualApproval({
       agentId,
       nodeId,
+      payload: sci.payload,
       // 审批卡可见"为什么":Agent 依据(hypothesis)随卡展示,人工批准时有判断材料
-      detail: `${node.name}(${tpl?.ch ?? node.templateKey})设定 ${value}${node.unit},有效写入区间 ${bd.effective.min}~${bd.effective.max}${node.unit}(${bd.layers.map(l => l.label).join(' ∩ ')})${via ? ` ${via}` : ''}${hypothesisText ? `;Agent 依据:${hypothesisText.slice(0, 200)}` : ''}`,
+      detail: `${node.name}(${tpl?.ch ?? node.templateKey})设定 ${value}${node.unit},有效写入区间 ${bd.effective.min}~${bd.effective.max}${node.unit}(${bd.layers.map(l => l.label).join(' ∩ ')})${via ? ` ${via}` : ''}${hypothesisText ? `;Agent 依据:${hypothesisText.slice(0, 200)}` : ''}\n${sci.lines.join('\n')}`,
       // 批准后复核同一条授权路径:直绑看 dcw 绑定,配方授权看配方绑定与参数仍存在
       verify: recipeBinding
         ? () => {
@@ -218,6 +223,7 @@ async function dcwControlGovernedLegacy(agentId: string, args: { node_id?: strin
         : undefined,
     })
     if (!ap.ok) return { text: ap.text, isError: true }
+    approvalId = ap.approvalId
     manualFeedback = ap.comment ?? ''
   }
 
@@ -242,6 +248,9 @@ async function dcwControlGovernedLegacy(agentId: string, args: { node_id?: strin
       actorName: agentBadgeLabel(agentId),
       taskId: args.task_id ? String(args.task_id) : undefined,
       hypothesis: args.hypothesis ? String(args.hypothesis) : '',
+      approvalId: approvalId || undefined,
+      // v34 干预台账归因:写入发生时所在 Channel(台账 path/channel 维度)
+      channelId: channelId ?? undefined,
       // 台账口径(三模式):该次写入发生时的频道生效执行模式(事后审计"这条写入当时是什么模式")
       executionMode: execMode,
     }