agentworkshop 0.8.6 → 0.8.8

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

@@ -1,137 +1,143 @@
-// ============================================================
-// JSON 文件存储原语 —— 全部 JSON 仓库共用(hardening:防数据丢失)。
-//
-// 背景(2026-09-05 QA 审计 P0-2):各仓库原先直接 writeFileSync 落盘 +
-// load 时 catch 后静默返回空库。一次写入中断(崩溃/断电/磁盘满)即产生
-// 截断文件,下次启动静默以空库运行,首次落盘用空数据覆盖原文件 ——
-// recipes/产线配置/回滚锚点永久丢失。
-//
-// 约定:
-//  - loadJsonFile:损坏时把坏文件保留为 <name>.corrupt-<ts>(现场可追责),
-//    再返回 fallback;ENOTDIR/ENOENT 等缺失场景静默 fallback。
-//  - saveJsonFileAtomic:先写同目录临时文件再 rename(同卷原子替换);
-//    rename 失败(Windows 杀软占用等)退回直写,保证可用性。
-// ============================================================
-import { mkdirSync, readFileSync, renameSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
-
-/** load 时顺手清理本库的陈旧 tmp(崩溃/终态失败遗留;当前 pid 正在用的跳过) */
-function sweepStaleTmp(filePath) {
-  try {
-    const name = basename(filePath)
-    for (const ent of readdirSync(dirname(filePath))) {
-      if (!ent.startsWith(`${name}.tmp-`)) continue
-      if (ent === `${name}.tmp-${process.pid}`) continue
-      try {
-        rmSync(join(dirname(filePath), ent), { force: true })
-      }
-      catch { /* 被占用则下次再清 */ }
-    }
-  }
-  catch { /* 目录不可读则忽略 */ }
-}
-
-/**
- * 读取 JSON 文件;缺失或损坏时返回 fallback。
- * @param {string} filePath
- * @param {unknown} fallback 缺省结构(如 { anchors: [], records: [] } 或 [])
- * @returns
- */
-export function loadJsonFile(filePath, fallback) {
-  sweepStaleTmp(filePath)
-  let raw
-  try {
-    raw = readFileSync(filePath, 'utf-8')
-  }
-  catch {
-    return fallback
-  }
-  try {
-    return JSON.parse(raw)
-  }
-  catch (err) {
-    // 损坏现场保留:改名留档,绝不用空库静默顶替用户数据
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
-    const backupPath = `${filePath}.corrupt-${stamp}`
-    try {
-      renameSync(filePath, backupPath)
-      console.error(`[json-store] ⚠ ${filePath} 解析失败(${err.message}),坏文件已保留为 ${backupPath},本次以空数据启动`)
-    }
-    catch {
-      console.error(`[json-store] ⚠ ${filePath} 解析失败(${err.message}),且保留坏文件失败,本次以空数据启动`)
-    }
-    return fallback
-  }
-}
-
-/**
- * 紧凑 vs 缩进的切换阈值(顶层元素数)。
- *
- * 为什么需要:`null, 2` 缩进对**小文件**是净收益(人可读、diff 友好、成本可忽略),
- * 但对**大库**是纯税:实测 DCW 回退账本 20000 锚 + 2000 记录 — 缩进 8.57 MB / 23.2 ms,
- * 紧凑 5.82 MB / 13.2 ms(体积 -32%、CPU -43%)。而它每个 1.5s 防抖窗就要整库重写一次,
- * 与 PLC 写 sweep 跑在同一个事件循环上 —— 缩进在这里换来的是几十毫秒的阻塞。
- *
- * 所以按规模自动选择:小库保持缩进(可读性),大库走紧凑(性能)。
- * 2000 是实测拐点量级:低于此的库序列化都在亚毫秒,缩进白拿。
- */
-const PRETTY_MAX_ENTRIES = 2000
-
-/** 顶层元素数估算(数组取长度;对象取各数组属性长度之和)——用于选择序列化形态 */
-function entryCount(data) {
-  if (Array.isArray(data)) return data.length
-  if (data && typeof data === 'object') {
-    let n = 0
-    for (const v of Object.values(data)) if (Array.isArray(v)) n += v.length
-    return n
-  }
-  return 0
-}
-
-/** 按规模选择缩进(小库可读、大库省 CPU/IO) */
-function serializeJson(data) {
-  return entryCount(data) > PRETTY_MAX_ENTRIES
-    ? JSON.stringify(data)
-    : JSON.stringify(data, null, 2)
-}
-
-/**
- * 原子落盘:写临时文件 → rename 替换。
- * 序列化形态按库规模自动选择(见 serializeJson)。
- *
- * 失败语义(2026-10-04 事故修复:Windows 杀软/索引器瞬时占用导致
- * 「退回直写」先截断目标再写失败,device-twins.json 被清成 0 字节):
- *  - tmp 写与 rename 各带退避重试(瞬时占用 100/200/400ms 内自愈);
- *  - 重试仍失败 → 抛错,**目标文件分文不动**,新数据完整留在 tmp
- *    (下次成功 flush 顶替;load 侧自动清理陈旧 tmp)——
- *    绝不做「截断目标的直写兜底」,宁抛错不丢数据。
- * @param {string} filePath
- * @param {unknown} data
- */
-const RETRY_DELAYS = [100, 200, 400]
-
-function withRetry(fn, label) {
-  let lastErr
-  for (let i = 0; i <= RETRY_DELAYS.length; i++) {
-    try {
-      return fn()
-    }
-    catch (err) {
-      lastErr = err
-      if (i < RETRY_DELAYS.length) {
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, RETRY_DELAYS[i])
-      }
-    }
-  }
-  console.error(`[json-store] ${label} 重试 ${RETRY_DELAYS.length + 1} 次仍失败: ${lastErr?.message ?? lastErr}`)
-  throw lastErr
-}
-
-export function saveJsonFileAtomic(filePath, data) {
-  mkdirSync(dirname(filePath), { recursive: true })
-  const tmp = `${filePath}.tmp-${process.pid}`
-  const payload = serializeJson(data)
-  // 终态失败直接上抛(目标未动,数据留在 tmp —— 它是最新一份完整数据,勿删)
-  withRetry(() => writeFileSync(tmp, payload, 'utf-8'), `临时文件写入(${filePath})`)
-  withRetry(() => renameSync(tmp, filePath), `原子替换(${filePath})`)
-}
+// ============================================================
+// JSON 文件存储原语 —— 全部 JSON 仓库共用(hardening:防数据丢失)。
+//
+// 背景(2026-09-05 QA 审计 P0-2):各仓库原先直接 writeFileSync 落盘 +
+// load 时 catch 后静默返回空库。一次写入中断(崩溃/断电/磁盘满)即产生
+// 截断文件,下次启动静默以空库运行,首次落盘用空数据覆盖原文件 ——
+// recipes/产线配置/回滚锚点永久丢失。
+//
+// 约定:
+//  - loadJsonFile:损坏时把坏文件保留为 <name>.corrupt-<ts>(现场可追责),
+//    再返回 fallback;ENOTDIR/ENOENT 等缺失场景静默 fallback。
+//  - saveJsonFileAtomic:先写同目录临时文件再 rename(同卷原子替换);
+//    rename 失败(Windows 杀软占用等)退回直写,保证可用性。
+// ============================================================
+import { mkdirSync, readFileSync, renameSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+/** load 时顺手清理本库的陈旧 tmp(崩溃/终态失败遗留;当前 pid 正在用的跳过) */
+function sweepStaleTmp(filePath) {
+  try {
+    const name = basename(filePath)
+    for (const ent of readdirSync(dirname(filePath))) {
+      if (!ent.startsWith(`${name}.tmp-`)) continue
+      if (ent === `${name}.tmp-${process.pid}`) continue
+      try {
+        rmSync(join(dirname(filePath), ent), { force: true })
+      }
+      catch { /* 被占用则下次再清 */ }
+    }
+  }
+  catch { /* 目录不可读则忽略 */ }
+}
+
+/**
+ * 读取 JSON 文件;缺失或损坏时返回 fallback。
+ * @param {string} filePath
+ * @param {unknown} fallback 缺省结构(如 { anchors: [], records: [] } 或 [])
+ * @returns
+ */
+export function loadJsonFile(filePath, fallback) {
+  sweepStaleTmp(filePath)
+  let raw
+  try {
+    raw = readFileSync(filePath, 'utf-8')
+  }
+  catch (err) {
+    // 读失败此前完全静默(ENOENT/EACCES/ENOTDIR 不分):运行时只看到"空库",排障无从下手。
+    // 这里只对非 ENOENT 留一条 warn,返回值仍回落 fallback(行为不变)。
+    try {
+      if (err?.code !== 'ENOENT') console.warn(`[json-store] 读取失败(${err?.code ?? 'unknown'}),回落默认值:${filePath}`)
+    }
+    catch { /* 日志失败不影响主流程 */ }
+    return fallback
+  }
+  try {
+    return JSON.parse(raw)
+  }
+  catch (err) {
+    // 损坏现场保留:改名留档,绝不用空库静默顶替用户数据
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+    const backupPath = `${filePath}.corrupt-${stamp}`
+    try {
+      renameSync(filePath, backupPath)
+      console.error(`[json-store] ⚠ ${filePath} 解析失败(${err.message}),坏文件已保留为 ${backupPath},本次以空数据启动`)
+    }
+    catch {
+      console.error(`[json-store] ⚠ ${filePath} 解析失败(${err.message}),且保留坏文件失败,本次以空数据启动`)
+    }
+    return fallback
+  }
+}
+
+/**
+ * 紧凑 vs 缩进的切换阈值(顶层元素数)。
+ *
+ * 为什么需要:`null, 2` 缩进对**小文件**是净收益(人可读、diff 友好、成本可忽略),
+ * 但对**大库**是纯税:实测 DCW 回退账本 20000 锚 + 2000 记录 — 缩进 8.57 MB / 23.2 ms,
+ * 紧凑 5.82 MB / 13.2 ms(体积 -32%、CPU -43%)。而它每个 1.5s 防抖窗就要整库重写一次,
+ * 与 PLC 写 sweep 跑在同一个事件循环上 —— 缩进在这里换来的是几十毫秒的阻塞。
+ *
+ * 所以按规模自动选择:小库保持缩进(可读性),大库走紧凑(性能)。
+ * 2000 是实测拐点量级:低于此的库序列化都在亚毫秒,缩进白拿。
+ */
+const PRETTY_MAX_ENTRIES = 2000
+
+/** 顶层元素数估算(数组取长度;对象取各数组属性长度之和)——用于选择序列化形态 */
+function entryCount(data) {
+  if (Array.isArray(data)) return data.length
+  if (data && typeof data === 'object') {
+    let n = 0
+    for (const v of Object.values(data)) if (Array.isArray(v)) n += v.length
+    return n
+  }
+  return 0
+}
+
+/** 按规模选择缩进(小库可读、大库省 CPU/IO) */
+function serializeJson(data) {
+  return entryCount(data) > PRETTY_MAX_ENTRIES
+    ? JSON.stringify(data)
+    : JSON.stringify(data, null, 2)
+}
+
+/**
+ * 原子落盘:写临时文件 → rename 替换。
+ * 序列化形态按库规模自动选择(见 serializeJson)。
+ *
+ * 失败语义(2026-10-04 事故修复:Windows 杀软/索引器瞬时占用导致
+ * 「退回直写」先截断目标再写失败,device-twins.json 被清成 0 字节):
+ *  - tmp 写与 rename 各带退避重试(瞬时占用 100/200/400ms 内自愈);
+ *  - 重试仍失败 → 抛错,**目标文件分文不动**,新数据完整留在 tmp
+ *    (下次成功 flush 顶替;load 侧自动清理陈旧 tmp)——
+ *    绝不做「截断目标的直写兜底」,宁抛错不丢数据。
+ * @param {string} filePath
+ * @param {unknown} data
+ */
+const RETRY_DELAYS = [100, 200, 400]
+
+function withRetry(fn, label) {
+  let lastErr
+  for (let i = 0; i <= RETRY_DELAYS.length; i++) {
+    try {
+      return fn()
+    }
+    catch (err) {
+      lastErr = err
+      if (i < RETRY_DELAYS.length) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, RETRY_DELAYS[i])
+      }
+    }
+  }
+  console.error(`[json-store] ${label} 重试 ${RETRY_DELAYS.length + 1} 次仍失败: ${lastErr?.message ?? lastErr}`)
+  throw lastErr
+}
+
+export function saveJsonFileAtomic(filePath, data) {
+  mkdirSync(dirname(filePath), { recursive: true })
+  const tmp = `${filePath}.tmp-${process.pid}`
+  const payload = serializeJson(data)
+  // 终态失败直接上抛(目标未动,数据留在 tmp —— 它是最新一份完整数据,勿删)
+  withRetry(() => writeFileSync(tmp, payload, 'utf-8'), `临时文件写入(${filePath})`)
+  withRetry(() => renameSync(tmp, filePath), `原子替换(${filePath})`)
+}

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

@@ -743,10 +743,12 @@ export function createMesController(deps: Partial<MesControllerDeps> = {}) {
     // 模式一:当前值快照(无 from/to)
     if (!win.from || !win.to) {
       const lines: string[] = []
+      let failed = 0
       for (const node of vis.nodes) {
         const driver = d.resolveDriver(node.driver)
         try {
           if (typeof driver.read !== 'function') {
+            failed++
             lines.push(`- ${node.name}(${node.id}):驱动 ${node.driver} 不支持读取`)
             continue
           }
@@ -754,16 +756,19 @@ export function createMesController(deps: Partial<MesControllerDeps> = {}) {
           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>)
+          if (!(r.ok && r.eng != null)) failed++
           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) {
+          failed++
           lines.push(`- ${node.name}(${node.id}):读取异常(${(err instanceof Error ? err.message : String(err)).slice(0, 80)})`)
         }
       }
       return {
         mode: 'snapshot',
+        ...(failed === vis.nodes.length ? { isError: true } : {}),
         text: `MES 当前值快照(${vis.nodes.length} 个点位,内联直读):\n${lines.join('\n')}\n\n说明:当前值为直读快照;历史窗口用 mes_fetch 带 from/to(≤7 天,max_rows≤${MES_MAX_ROWS_CAP})。`,
       }
     }
@@ -772,6 +777,7 @@ export function createMesController(deps: Partial<MesControllerDeps> = {}) {
     if (win.maxRows <= MES_SYNC_INLINE_MAX_ROWS) {
       const sections: string[] = []
       const statsOut: NonNullable<MesFetchOutcome['data']>['stats'] = []
+      let failed = 0
       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')
@@ -779,11 +785,14 @@ export function createMesController(deps: Partial<MesControllerDeps> = {}) {
           statsOut.push({ nodeId: node.id, stats: one.stats, truncated: one.truncated })
         }
         catch (err) {
+          failed++
           sections.push(`■ ${node.name}(id=${node.id})\n  取数失败:${err instanceof Error ? err.message : String(err)}`)
         }
       }
       return {
         mode: 'inline',
+        // 全部点位失败时如实置 isError(此前仅文本提示"取数失败",Agent 可能当成功继续)
+        ...(failed === vis.nodes.length ? { isError: true } : {}),
         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 },
       }

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

@@ -300,6 +300,33 @@ interface WorkerReply {
   error?: string
 }
 
+/**
+ * hook 子进程环境白名单。
+ *
+ * hook 是管理员配置的用户代码(信任层与 AML 训练器同级),但此前走
+ * spawnLineProcess 的默认分支 = 全量 process.env 仅剥 10 个平台口令键 ——
+ * 引擎 provider key、MQTT/对象存储凭据等全部可见,与 AML 训练器的白名单口径不一致。
+ * 这里改为显式白名单:系统运行必需键 + AW_MES_* 显式注入,其余一律不继承。
+ */
+const HOOK_ENV_ALLOW = [
+  'PATH', 'Path', 'PATHEXT', 'SystemRoot', 'WINDIR',
+  'TEMP', 'TMP', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA',
+  'LANG', 'LC_ALL', 'TZ',
+] as const
+
+function hookEnv(): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const key of HOOK_ENV_ALLOW) {
+    const v = process.env[key]
+    if (v !== undefined) out[key] = v
+  }
+  // hook 专用注入面:只放行显式命名的 AW_MES_* 键(如 token/超时)
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== undefined && k.startsWith('AW_MES_')) out[k] = v
+  }
+  return out
+}
+
 async function runHookModule(kind: 'data' | 'request' | 'write' | 'write-check', code: string, payload: {
   param: unknown
   data?: MesHookData
@@ -313,7 +340,7 @@ async function runHookModule(kind: 'data' | 'request' | 'write' | 'write-check',
   writeFileSync(moduleFile, WORKER_MODULE_OF(code), 'utf-8')
   active += 1
   try {
-    const child = spawnLineProcess(process.execPath, [moduleFile])
+    const child = spawnLineProcess(process.execPath, [moduleFile], { cleanEnv: true, env: hookEnv() })
     const request = JSON.stringify({
       kind,
       param: payload.param,

package/server/services/workshop/net/ssrf.ts

@@ -1,74 +1,83 @@
-/**
- * 出站 HTTP 安全护栏(统一口径)。
- *
- * 背景:mes-rest 已有「协议白名单 + DNS 解析后私网/环回段拒绝 + allowPrivateHost 显式白名单」,
- * 但 DAQ/DCW 的 http 驱动仍是无护栏 fetch —— 同为 admin 配置面,却存在认知差与 SSRF 面。
- * 本模块把 mes-rest 的判定原样抽出,三处共用同一实现(消息里的主体名可配置)。
- */
-import { lookup } from 'node:dns/promises'
-import { isIP } from 'node:net'
-import { AppError } from '@/server/utils/errors'
-
-export interface SafeUrlOptions {
-  /** 'true' 才放行内网/环回(内网数据源显式白名单) */
-  allowPrivateHost?: unknown
-  /** 旧配置缺省(字段不存在)时是否沿用历史行为(允许私网);MES 保持默认拒绝 */
-  legacyAllowPrivateWhenUnset?: boolean
-  /** 错误文案里的主体名(如 MES / 数据源) */
-  label?: string
-}
-
-/** 私有/环回段:IPv4 127/8 · 10/8 · 172.16/12 · 192.168/16 · 169.254/16;IPv6 ::1 · :: · fc00::/7 · fe80::/10 */
-export function isPrivateIp(ip: string): boolean {
-  const v4 = ip.toLowerCase().startsWith('::ffff:') ? ip.slice(7) : ip // IPv4-mapped IPv6 按 IPv4 判
-  if (isIP(v4) === 4) {
-    const seg = v4.split('.').map(Number)
-    const a = seg[0]!
-    const b = seg[1]!
-    return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254)
-  }
-  const h16 = Number.parseInt(v4.split(':')[0] ?? '', 16)
-  if (!Number.isFinite(h16)) return true // 解析不了按保守拒绝
-  return h16 === 0x0001 || h16 === 0 || (h16 & 0xfe00) === 0xfc00 || (h16 & 0xffc0) === 0xfe80
-}
-
-/** 主机名 → IP 列表(字面 IP 直判不经 DNS;域名全量解析,任一内网地址即整批拒绝) */
-export async function resolveTargetIps(hostname: string, label = 'MES'): Promise<string[]> {
-  if (isIP(hostname)) return [hostname]
-  try {
-    const recs = await lookup(hostname, { all: true, verbatim: true })
-    return recs.map(r => r.address)
-  }
-  catch (err) {
-    throw new AppError(400, 'BAD_REQUEST', `${label} 主机 DNS 解析失败:${hostname}(${err instanceof Error ? err.message : String(err)})`)
-  }
-}
-
-/**
- * 校验出站 URL:仅 http/https;未显式开白名单时解析目标并拒绝私网/环回地址。
- * 返回解析后的 URL(调用方用 .origin/.toString())。
- */
-export async function assertSafeHttpUrl(rawUrl: string, opts: SafeUrlOptions = {}): Promise<URL> {
-  let u: URL
-  try {
-    u = new URL(rawUrl)
-  }
-  catch {
-    throw new AppError(400, 'BAD_REQUEST', `${opts.label ?? '目标'} 不是合法 URL:${rawUrl}`)
-  }
-  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
-    throw new AppError(400, 'BAD_REQUEST', `${opts.label ?? '目标'} 仅支持 http/https 协议(当前 ${u.protocol})`)
-  }
-  const raw = opts.allowPrivateHost
-  const explicit = raw !== undefined && raw !== null && String(raw).trim() !== ''
-  // 显式配置优先;未配置时 MES 默认拒绝,DAQ/DCW http 沿用旧行为(见 legacyAllowPrivateWhenUnset)
-  const shouldCheck = explicit ? String(raw) !== 'true' : !opts.legacyAllowPrivateWhenUnset
-  if (shouldCheck) {
-    const ips = await resolveTargetIps(u.hostname, opts.label)
-    const privateHits = [...new Set(ips.filter(a => isPrivateIp(a)))]
-    if (privateHits.length > 0) {
-      throw new AppError(400, 'BAD_REQUEST', `目标 ${u.hostname} 解析到内网/环回地址(${privateHits.join(', ')}),已按 SSRF 防护拒绝;若数据源确在内网,请把驱动配置 allowPrivateHost 显式设为 'true' 开启白名单`)
-    }
-  }
-  return u
-}
+/**
+ * 出站 HTTP 安全护栏(统一口径)。
+ *
+ * 背景:mes-rest 已有「协议白名单 + DNS 解析后私网/环回段拒绝 + allowPrivateHost 显式白名单」,
+ * 但 DAQ/DCW 的 http 驱动仍是无护栏 fetch —— 同为 admin 配置面,却存在认知差与 SSRF 面。
+ * 本模块把 mes-rest 的判定原样抽出,三处共用同一实现(消息里的主体名可配置)。
+ */
+import { lookup } from 'node:dns/promises'
+import { isIP } from 'node:net'
+import { AppError } from '@/server/utils/errors'
+
+export interface SafeUrlOptions {
+  /** 'true' 才放行内网/环回(内网数据源显式白名单) */
+  allowPrivateHost?: unknown
+  /** 旧配置缺省(字段不存在)时是否沿用历史行为(允许私网);MES 保持默认拒绝 */
+  legacyAllowPrivateWhenUnset?: boolean
+  /** 错误文案里的主体名(如 MES / 数据源) */
+  label?: string
+}
+
+/** 私有/环回段:IPv4 127/8 · 10/8 · 172.16/12 · 192.168/16 · 169.254/16;IPv6 ::1 · :: · fc00::/7 · fe80::/10 */
+export function isPrivateIp(ip: string): boolean {
+  const v4 = ip.toLowerCase().startsWith('::ffff:') ? ip.slice(7) : ip // IPv4-mapped IPv6 按 IPv4 判
+  if (isIP(v4) === 4) {
+    const seg = v4.split('.').map(Number)
+    const a = seg[0]!
+    const b = seg[1]!
+    return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254)
+  }
+  const h16 = Number.parseInt(v4.split(':')[0] ?? '', 16)
+  if (!Number.isFinite(h16)) return true // 解析不了按保守拒绝
+  return h16 === 0x0001 || h16 === 0 || (h16 & 0xfe00) === 0xfc00 || (h16 & 0xffc0) === 0xfe80
+}
+
+/** 主机名 → IP 列表(字面 IP 直判不经 DNS;域名全量解析,任一内网地址即整批拒绝) */
+export async function resolveTargetIps(hostname: string, label = 'MES'): Promise<string[]> {
+  if (isIP(hostname)) return [hostname]
+  try {
+    const recs = await lookup(hostname, { all: true, verbatim: true })
+    return recs.map(r => r.address)
+  }
+  catch (err) {
+    throw new AppError(400, 'BAD_REQUEST', `${label} 主机 DNS 解析失败:${hostname}(${err instanceof Error ? err.message : String(err)})`)
+  }
+}
+
+/**
+ * 出站目标允许内网的统一开关(默认拒绝)。
+ * 报警 webhook / embedding 服务 / 插件 ctx.http 都可能部署在内网,因此提供显式
+ * 开关而不是永远拒绝;但必须由运维明确打开,不能默认放行(否则等于没护栏)。
+ */
+export function allowPrivateOutbound(): boolean {
+  return process.env.AW_ALLOW_PRIVATE_OUTBOUND === '1'
+}
+
+/**
+ * 校验出站 URL:仅 http/https;未显式开白名单时解析目标并拒绝私网/环回地址。
+ * 返回解析后的 URL(调用方用 .origin/.toString())。
+ */
+export async function assertSafeHttpUrl(rawUrl: string, opts: SafeUrlOptions = {}): Promise<URL> {
+  let u: URL
+  try {
+    u = new URL(rawUrl)
+  }
+  catch {
+    throw new AppError(400, 'BAD_REQUEST', `${opts.label ?? '目标'} 不是合法 URL:${rawUrl}`)
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new AppError(400, 'BAD_REQUEST', `${opts.label ?? '目标'} 仅支持 http/https 协议(当前 ${u.protocol})`)
+  }
+  const raw = opts.allowPrivateHost
+  const explicit = raw !== undefined && raw !== null && String(raw).trim() !== ''
+  // 显式配置优先;未配置时 MES 默认拒绝,DAQ/DCW http 沿用旧行为(见 legacyAllowPrivateWhenUnset)
+  const shouldCheck = explicit ? String(raw) !== 'true' : !opts.legacyAllowPrivateWhenUnset
+  if (shouldCheck) {
+    const ips = await resolveTargetIps(u.hostname, opts.label)
+    const privateHits = [...new Set(ips.filter(a => isPrivateIp(a)))]
+    if (privateHits.length > 0) {
+      throw new AppError(400, 'BAD_REQUEST', `目标 ${u.hostname} 解析到内网/环回地址(${privateHits.join(', ')}),已按 SSRF 防护拒绝;若数据源确在内网,请把驱动配置 allowPrivateHost 显式设为 'true' 开启白名单`)
+    }
+  }
+  return u
+}