agentworkshop 0.7.27 → 0.7.34

package/server/services/workshop/aml/python/amlkit.py

@@ -0,0 +1,120 @@
+# -*- coding: utf-8 -*-
+"""
+AML 平台种(amlkit)—— Agent 训练代码唯一允许的平台依赖。
+
+职责:
+  1. 加载 AML 数据集快照(memmap 零拷贝);
+  2. 进度协议上报(##AML NDJSON 行,stdout 唯一契约通道);
+  3. 指标落盘(metrics.json 合并写);
+  4. torch 模型 → one-step ONNX 导出助手(统一 IO 契约)。
+
+模型 IO 契约(canonical one-step,MPC 面向):
+  输入  history: float32 [batch, historySteps, nAllNodes](归一化)
+  输出  y_next : float32 [batch, nTargetNodes](归一化的"下一拍"目标)
+  多步预测 = 闭环滚动:预测输出回填 history 的 target 列,control 列取未来 U,
+  feature 列持最后观测值(persistence 假设,评估器与推理服务同口径实现)。
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+
+
+class Bundle:
+    """数据集快照句柄:x/u/y 为 float32 memmap,split 切片为连续段。"""
+
+    def __init__(self, dataset_path):
+        base = Path(dataset_path)
+        self.manifest = json.loads((base / "manifest.json").read_text(encoding="utf-8"))
+        sp = self.manifest["split"]
+        n = sp["train"] + sp["val"] + sp["test"]
+        shapes = self.manifest["shapes"]
+        arrays = base / "arrays"
+        self.x = np.memmap(arrays / "x.f32", dtype="<f4", mode="r", shape=tuple(shapes["x"]))
+        self.u = np.memmap(arrays / "u.f32", dtype="<f4", mode="r", shape=tuple(shapes["u"]))
+        self.y = np.memmap(arrays / "y.f32", dtype="<f4", mode="r", shape=tuple(shapes["y"]))
+        self.splits = {
+            "train": slice(0, sp["train"]),
+            "val": slice(sp["train"], sp["train"] + sp["val"]),
+            "test": slice(sp["train"] + sp["val"], n),
+        }
+
+    def get(self, name, split):
+        """name in {x,u,y};返回该切分的 numpy 拷贝(便于 shuffle/负采样)"""
+        arr = getattr(self, name)
+        return np.array(arr[self.splits[split]])
+
+
+def load_bundle(dataset_path):
+    return Bundle(dataset_path)
+
+
+def _safe_job_path(*parts):
+    """作业目录内收敛:resolve 规范化 + parents 前缀校验,越界即抛错。
+
+    平台工件(metrics.json / model.onnx)只允许写进作业目录 artifacts/ 下。
+    """
+    env_job_dir = os.environ.get("AML_JOB_DIR", "")
+    if not env_job_dir:
+        raise RuntimeError("AML_JOB_DIR 未设置(只能经 aml_run.py 运行)")
+    root = Path(env_job_dir).resolve()
+    target = root.joinpath(*parts).resolve()
+    if target != root and root not in target.parents:
+        raise RuntimeError("工件路径越界(已拒绝): %s" % target)
+    return str(target)
+
+
+def _artifacts_dir():
+    d = _safe_job_path("artifacts")
+    os.makedirs(d, exist_ok=True)
+    return d
+
+
+def report_progress(pct, note=""):
+    """进度上报(0-100);协议行之外的 print 也会被平台收进 run.log,但只有 ##AML 行被解析。"""
+    pct = max(0, min(100, int(pct)))
+    _emit({"type": "progress", "progress": pct, "note": str(note)[:200]})
+
+
+def _emit(obj):
+    sys.stdout.write("##AML " + json.dumps(obj, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+def save_metrics(extra):
+    """合并写 artifacts/metrics.json(agent 侧自报指标;平台会在评估阶段补权威指标)"""
+    p = Path(_artifacts_dir()) / "metrics.json"
+    cur = {}
+    if p.exists():
+        try:
+            cur = json.loads(p.read_text(encoding="utf-8"))
+        except Exception:
+            cur = {}
+    cur.update(extra)
+    p.write_text(json.dumps(cur, ensure_ascii=False, indent=2), encoding="utf-8")
+    return cur
+
+
+def export_torch_onnx(model, manifest, path=None):
+    """把接受 [batch, H, nAll] → [batch, nTgt](归一化)的 torch 模型导出为契约 ONNX。
+
+    返回导出路径;失败抛异常(训练作业按失败处理,不静默)。
+    """
+    import torch  # 惰性:仅深度模型需要
+
+    h = manifest["shapes"]["x"][1]
+    n_all = manifest["shapes"]["x"][2]
+    n_tgt = manifest["shapes"]["y"][2]
+    p = _safe_job_path("artifacts", "model.onnx") if path is None else str(path)
+    model = model.cpu().eval()
+    dummy = torch.zeros(1, h, n_all, dtype=torch.float32)
+    with torch.no_grad():
+        torch.onnx.export(
+            model, dummy, p,
+            input_names=["history"], output_names=["y_next"],
+            dynamic_axes={"history": {0: "batch"}, "y_next": {0: "batch"}},
+            opset_version=17,
+        )
+    return p

package/server/services/workshop/aml/python/requirements.txt

@@ -0,0 +1,7 @@
+numpy>=1.26,<3.0
+pandas>=2.1
+scikit-learn>=1.4
+torch>=2.2
+onnx>=1.15
+onnxscript>=0.1
+onnxruntime>=1.18

package/server/services/workshop/aml/python/train-example.py

@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+"""AML 参考训练实现(one-step 线性基线;e2e --real 模式与 Agent 的起点范本)。
+
+契约:
+  - 数据:amlkit.load_bundle(归一化 float32;x [N,H,nAll] / y [N,F,nTgt]);
+  - 模型:输入 [batch, H, nAll](展平)→ 输出 [batch, nTgt](下一拍目标,归一化);
+  - 产出:amlkit.export_torch_onnx(契约 ONNX)+ amlkit.save_metrics(自报指标,门禁另由平台评估器复算)。
+
+超参经作业 params 传入:lr / epochs / hidden / batch。
+"""
+import json
+import os
+from pathlib import Path
+
+import torch
+import torch.nn as nn
+
+import amlkit
+
+
+def main():
+    job_dir = Path(os.environ["AML_JOB_DIR"]).resolve()
+    job = json.loads((job_dir / "job.json").read_text(encoding="utf-8"))
+    params = job.get("params", {})
+
+    bundle = amlkit.load_bundle(job["datasetPath"])
+    manifest = bundle.manifest
+    h_steps = manifest["shapes"]["x"][1]
+    n_all = manifest["shapes"]["x"][2]
+    n_tgt = manifest["shapes"]["y"][2]
+
+    x_train = bundle.get("x", "train")
+    y_train = bundle.get("y", "train")[:, 0, :]  # 下一拍目标(第 0 个 horizon 步)
+    x_val = bundle.get("x", "val")
+    y_val = bundle.get("y", "val")[:, 0, :]
+
+    hidden = int(params.get("hidden", 128))
+    model = nn.Sequential(
+        nn.Flatten(),
+        nn.Linear(h_steps * n_all, hidden),
+        nn.ReLU(),
+        nn.Linear(hidden, n_tgt),
+    )
+    opt = torch.optim.Adam(model.parameters(), lr=float(params.get("lr", 1e-3)))
+    loss_fn = nn.MSELoss()
+
+    xt = torch.tensor(x_train, dtype=torch.float32)
+    yt = torch.tensor(y_train, dtype=torch.float32)
+    xv = torch.tensor(x_val, dtype=torch.float32) if x_val.shape[0] else None
+    yv = torch.tensor(y_val, dtype=torch.float32) if y_val.shape[0] else None
+
+    epochs = int(params.get("epochs", 80))
+    batch = int(params.get("batch", 256))
+    n = xt.shape[0]
+    best_val = float("inf")
+    train_loss = 0.0
+    val_loss = None
+    for epoch in range(epochs):
+        model.train()
+        perm = torch.randperm(n)
+        total = 0.0
+        for i in range(0, n, batch):
+            idx = perm[i:i + batch]
+            opt.zero_grad()
+            loss = loss_fn(model(xt[idx]), yt[idx])
+            loss.backward()
+            opt.step()
+            total += float(loss) * idx.shape[0]
+        train_loss = total / max(1, n)
+        if xv is not None:
+            model.eval()
+            with torch.no_grad():
+                val_loss = float(loss_fn(model(xv), yv))
+            best_val = min(best_val, val_loss)
+        amlkit.report_progress(5 + 90 * (epoch + 1) // epochs,
+                               "epoch %d/%d train=%.5f val=%s" % (epoch + 1, epochs, train_loss, val_loss if val_loss is not None else "n/a"))
+
+    amlkit.save_metrics({"agent": {
+        "kind": "mlp_one_step_baseline",
+        "epochs": epochs,
+        "train_loss_last": train_loss,
+        "val_loss_best": None if val_loss is None else best_val,
+        "params": params,
+    }})
+
+    amlkit.export_torch_onnx(model, manifest)
+    amlkit.report_progress(99, "exported onnx")
+    print("train-example done")
+
+
+if __name__ == "__main__":
+    main()

package/server/services/workshop/aml/python-runtime.ts

@@ -0,0 +1,217 @@
+/**
+ * AML Python 运行时:探测 python/uv → 共享 venv 供给(幂等,marker 校验)→
+ * 给作业运行器提供受控子进程(复用 line-spawn 的 Windows 引号纪律与杀树)。
+ *
+ * 供给纪律:仅 venv 创建阶段联网(pip/uv install,依赖锁定在 requirements.txt,
+ * 可配镜像);训练/评估进程不联网。探测结果与 venv 供给进程内缓存。
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { AppError } from '../../../utils/errors'
+import { resolveOnPath, spawnLineProcess } from '../agents/adapters/line-spawn'
+import { killHarnessProcess } from '../agents/harness-process'
+import { createLogger } from '../logger'
+import { amlSettings } from '../settings'
+import type { AmlRuntime } from './runtime'
+
+const log = createLogger('aml.py')
+
+const g = globalThis as typeof globalThis & {
+  __amlPyProbe?: PythonProbe
+  __amlVenvPromise?: Promise<string>
+}
+
+export interface PythonProbe {
+  ok: boolean
+  pythonPath?: string
+  version?: string
+  uvPath?: string
+  reason?: string
+}
+
+function runCapture(cmd: string, args: string[], timeoutMs: number): Promise<{ code: number, out: string, err: string }> {
+  return new Promise((resolve) => {
+    const child = spawnLineProcess(cmd, args)
+    let out = ''
+    let err = ''
+    const timer = setTimeout(() => {
+      void killHarnessProcess(child.pid ?? 0)
+      resolve({ code: -1, out, err: `${err}\n[timeout ${timeoutMs}ms]` })
+    }, timeoutMs)
+    child.stdout?.on('data', (d) => {
+      out += String(d)
+    })
+    child.stderr?.on('data', (d) => {
+      err += String(d)
+    })
+    child.on('error', (e) => {
+      clearTimeout(timer)
+      resolve({ code: -1, out, err: String(e) })
+    })
+    child.on('exit', (code) => {
+      clearTimeout(timer)
+      resolve({ code: code ?? -1, out, err })
+    })
+  })
+}
+
+/** 探测 python 与 uv(进程内缓存;settings 变更靠重启生效) */
+export async function probePython(): Promise<PythonProbe> {
+  if (g.__amlPyProbe) return g.__amlPyProbe
+  const s = amlSettings()
+  const candidates = s.python.pythonBin
+    ? [s.python.pythonBin]
+    : process.platform === 'win32'
+      ? ['python', 'py']
+      : ['python3', 'python']
+  let uvPath: string | undefined
+  const uvName = s.python.uvBin || 'uv'
+  const uvResolved = resolveOnPath(uvName)
+  if (uvResolved) uvPath = uvResolved
+  else if (!s.python.uvBin && process.platform !== 'win32') {
+    // 非 Windows resolveOnPath 不解析;用 which 语义兜底一次
+    const r = await runCapture('which', [uvName], 5000)
+    if (r.code === 0 && r.out.trim()) uvPath = r.out.trim().split('\n')[0]
+  }
+
+  for (const name of candidates) {
+    const resolved = resolveOnPath(name) ?? (name.includes('/') || name.includes('\\') || /^[A-Za-z]:/.test(name) ? name : undefined)
+    if (!resolved || !existsSync(resolved)) continue
+    const probe = await runCapture(resolved, ['--version'], 10_000)
+    if (probe.code === 0) {
+      const version = probe.out.trim() || probe.err.trim()
+      // `py -3` 需要 -3 参数才指向 Python3(Windows 启动器);其余直接用
+      const result: PythonProbe = {
+        ok: true,
+        pythonPath: resolved,
+        version,
+        uvPath,
+      }
+      g.__amlPyProbe = result
+      log.info(`[aml-python] 探测成功:${version} @ ${resolved}${uvPath ? ` (uv: ${uvPath})` : ''}`)
+      return result
+    }
+  }
+  // py 启动器特有:裸 `py --version` 可能成功但需要 -3 才是 py3
+  const result: PythonProbe = {
+    ok: false,
+    uvPath,
+    reason: '未找到可用的 Python 3 解释器:安装 Python 3.10+ 或 uv,或设置 aml.python.pythonBin 指向解释器绝对路径',
+  }
+  g.__amlPyProbe = result
+  return result
+}
+
+export function requirementsHash(): string {
+  const reqPath = join(platformPythonDir(), 'requirements.txt')
+  const content = existsSync(reqPath) ? readFileSync(reqPath, 'utf8') : ''
+  const idx = amlSettings().python.indexUrl
+  return createHash('sha256').update(content).update(idx).digest('hex').slice(0, 12)
+}
+
+/**
+ * 平台 python 资产目录解析(amlkit.py/aml_eval.py/requirements.txt 所在):
+ * dev=cwd 源码树;打包产物经 AW_PACKAGE_ROOT 或用户配置根兜底(与 schema.json 的
+ * cwd 兜底同范式 —— nitro 打包后 import.meta.dirname 不可靠)。
+ */
+export function platformPythonDir(): string {
+  const fallback = join(process.cwd(), 'server', 'services', 'workshop', 'aml', 'python')
+  const candidates = [
+    process.env.AML_PYHOME ?? '',
+    fallback,
+    join(process.env.AW_PACKAGE_ROOT ?? process.cwd(), 'server', 'services', 'workshop', 'aml', 'python'),
+  ]
+  for (const c of candidates) {
+    if (c && existsSync(join(c, 'amlkit.py'))) return c
+  }
+  return fallback
+}
+
+export function venvDir(rt: AmlRuntime): string {
+  return join(rt.root, 'runtime', 'venv')
+}
+
+export function venvPythonPath(rt: AmlRuntime): string {
+  return process.platform === 'win32'
+    ? join(venvDir(rt), 'Scripts', 'python.exe')
+    : join(venvDir(rt), 'bin', 'python')
+}
+
+/**
+ * 共享 venv 供给(幂等):marker 文件校验 requirements+indexUrl 摘要;并发调用共享同一 Promise。
+ * 返回 venv 内 python 绝对路径。
+ */
+export async function ensureVenv(rt: AmlRuntime): Promise<string> {
+  if (g.__amlVenvPromise) return g.__amlVenvPromise
+  g.__amlVenvPromise = (async () => {
+    const probe = await probePython()
+    if (!probe.ok || !probe.pythonPath) {
+      throw new AppError(503, 'AML_PYTHON_MISSING', `训练运行时不可用:${probe.reason}`)
+    }
+    const vdir = venvDir(rt)
+    const vpy = venvPythonPath(rt)
+    const marker = join(vdir, `.aml-ok-${requirementsHash()}`)
+    if (existsSync(marker) && existsSync(vpy)) return vpy
+
+    const s = amlSettings()
+    const idxArgs = s.python.indexUrl ? ['--index-url', s.python.indexUrl] : []
+    const reqPath = join(platformPythonDir(), 'requirements.txt')
+    log.info('[aml-python] 开始 venv 供给(首次可能需数分钟下载依赖)…')
+    if (probe.uvPath) {
+      const mk = await runCapture(probe.uvPath, ['venv', vdir, '--python', probe.pythonPath], 120_000)
+      if (mk.code !== 0) throw new AppError(500, 'AML_VENV_FAILED', `uv venv 失败:${mk.err.slice(-400)}`)
+      const inst = await runCapture(probe.uvPath, ['pip', 'install', '--python', vpy, '-r', reqPath, ...idxArgs], 20 * 60_000)
+      if (inst.code !== 0) throw new AppError(500, 'AML_VENV_FAILED', `依赖安装失败:${(inst.err || inst.out).slice(-400)}`)
+    }
+    else {
+      const mk = await runCapture(probe.pythonPath, ['-m', 'venv', vdir], 120_000)
+      if (mk.code !== 0) throw new AppError(500, 'AML_VENV_FAILED', `python -m venv 失败:${mk.err.slice(-400)}`)
+      const inst = await runCapture(vpy, ['-m', 'pip', 'install', '-r', reqPath, ...idxArgs], 20 * 60_000)
+      if (inst.code !== 0) throw new AppError(500, 'AML_VENV_FAILED', `pip install 失败:${(inst.err || inst.out).slice(-400)}`)
+    }
+    writeFileSync(marker, new Date().toISOString())
+    log.info('[aml-python] venv 供给完成')
+    return vpy
+  })()
+  try {
+    return await g.__amlVenvPromise
+  }
+  catch (err) {
+    g.__amlVenvPromise = undefined // 失败不缓存,下次重试
+    throw err
+  }
+}
+
+/**
+ * 作业子进程环境:白名单语义(cleanEnv,不继承 process.env)。
+ * Agent 编写的 train.py 运行在此环境中 —— 服务器 secrets(引擎 API key、
+ * DAQ_TSDB_URL、MinIO 凭据等)一律不可见;仅保留 Python 运行所需系统键。
+ */
+export function jobEnv(rt: AmlRuntime, jobDir: string): Record<string, string> {
+  const platformPyDir = platformPythonDir()
+  const pick = (k: string): string => (process.env[k] ? `${k}=${process.env[k] as string}` : '')
+  const sysEnv = ['PATH', 'PATHEXT', 'SYSTEMROOT', 'SYSTEMDRIVE', 'COMSPEC', 'WINDIR', 'TEMP', 'TMP', 'PROGRAMFILES', 'LANG', 'LC_ALL']
+    .map(pick)
+    .filter(s => s !== '')
+    .reduce<Record<string, string>>((acc, kv) => {
+      const eq = kv.indexOf('=')
+      acc[kv.slice(0, eq)] = kv.slice(eq + 1)
+      return acc
+    }, {})
+  return {
+    ...sysEnv,
+    AML_JOB_DIR: jobDir,
+    PYTHONPATH: platformPyDir,
+    PYTHONUNBUFFERED: '1',
+    PYTHONDONTWRITEBYTECODE: '1',
+    PYTHONIOENCODING: 'utf-8',
+    // 显式置空代理(白名单下本就不继承,双保险防止系统级 sitecustomize 注入)
+    HTTP_PROXY: '',
+    HTTPS_PROXY: '',
+    http_proxy: '',
+    https_proxy: '',
+  }
+}
+
+export { killHarnessProcess }

package/server/services/workshop/aml/retention.ts

@@ -0,0 +1,98 @@
+/**
+ * AML GC/保留策略(挂 24h 循环;防冗余堆积 —— 计划 §14.1):
+ *  1. 无引用且超过 retentionDays 的数据集:删快照目录 + 注册表行;
+ *  2. retired 模型工件超过 retiredKeepDays:删工件目录(注册表行保留,标 artifacts_pruned);
+ *  3. 失败作业目录(无任何实验成功)超过 7 天:删目录(注册表行保留)。
+ */
+import { existsSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { createLogger } from '../logger'
+import { amlSettings } from '../settings'
+import { getAmlRuntime } from './runtime'
+
+const log = createLogger('aml.retention')
+const DAY_MS = 24 * 3600_000
+const FAILED_JOB_KEEP_DAYS = 7
+
+export function sweepAmlRetention(now = Date.now()): { datasets: number, models: number, jobs: number } {
+  const rt = getAmlRuntime()
+  const s = amlSettings()
+  let removedDatasets = 0
+  let removedModels = 0
+  let removedJobs = 0
+
+  // 1. 无引用数据集
+  for (const ds of rt.repo.dataset.list({ limit: 500 })) {
+    const age = now - Date.parse(ds.createdAt)
+    if (age < s.dataset.retentionDays * DAY_MS) continue
+    const refs = rt.repo.dataset.referenceCount(ds.id)
+    if (refs.experiments > 0 || refs.models > 0) continue
+    try {
+      if (existsSync(ds.path)) rmSync(ds.path, { recursive: true, force: true })
+      rt.repo.dataset.remove(ds.id)
+      removedDatasets++
+    }
+    catch (err) {
+      log.warn(`[aml-retention] 数据集 ${ds.id} 清理失败:${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  // 2. retired 模型工件
+  for (const m of rt.repo.model.list({ stage: 'retired', limit: 500 })) {
+    if (m.artifactsPruned) continue
+    const age = now - Date.parse(m.promotedAt ?? m.createdAt)
+    if (age < s.model.retiredKeepDays * DAY_MS) continue
+    try {
+      if (existsSync(m.path)) rmSync(m.path, { recursive: true, force: true })
+      rt.repo.model.markPruned(m.id)
+      removedModels++
+    }
+    catch (err) {
+      log.warn(`[aml-retention] 模型 ${m.id} 工件清理失败:${err instanceof Error ? err.message : String(err)}`)
+    }
+  }
+
+  // 3. 失败/取消且终态超过 7 天的作业目录
+  for (const status of ['failed', 'cancelled', 'timeout', 'interrupted'] as const) {
+    for (const j of rt.repo.job.list({ status, limit: 200 })) {
+      if (!j.endedAt) continue
+      if (now - Date.parse(j.endedAt) < FAILED_JOB_KEEP_DAYS * DAY_MS) continue
+      const dir = join(rt.jobsDir, j.id)
+      try {
+        if (existsSync(dir)) rmSync(dir, { recursive: true, force: true })
+        removedJobs++
+      }
+      catch (err) {
+        log.warn(`[aml-retention] 作业 ${j.id} 目录清理失败:${err instanceof Error ? err.message : String(err)}`)
+      }
+    }
+  }
+
+  if (removedDatasets || removedModels || removedJobs) {
+    log.info(`[aml-retention] 清理完成:数据集 ${removedDatasets} / 模型工件 ${removedModels} / 作业目录 ${removedJobs}`)
+  }
+  return { datasets: removedDatasets, models: removedModels, jobs: removedJobs }
+}
+
+const g = globalThis as typeof globalThis & { __amlRetentionTimer?: ReturnType<typeof setInterval> }
+
+/** 启动 24h 循环(unref;HMR 幂等) */
+export function startAmlRetentionTimer(): void {
+  if (g.__amlRetentionTimer) return
+  g.__amlRetentionTimer = setInterval(() => {
+    try {
+      sweepAmlRetention()
+    }
+    catch (err) {
+      log.warn(`[aml-retention] 扫描失败(不阻断):${err instanceof Error ? err.message : String(err)}`)
+    }
+  }, 24 * 3600_000)
+  g.__amlRetentionTimer.unref()
+}
+
+export function stopAmlRetentionTimer(): void {
+  if (g.__amlRetentionTimer) {
+    clearInterval(g.__amlRetentionTimer)
+    g.__amlRetentionTimer = undefined
+  }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * AML 运行时装配:db + 数据根目录 + 仓储访问器(插件 workshop.ts 装配,REST/工具读取)。
+ * 数据落盘布局(<configRoot>/data/aml/):
+ *   datasets/<dsId>/   spec.json + manifest.json + report.json + arrays/*.f32
+ *   jobs/<jobId>/      job.json + workspace/(train.py, amlkit.py) + run.log + artifacts/
+ *   models/<modelId>/  model.onnx + io_spec.json(注册时从作业工件拷贝,不可变)
+ */
+import { join } from 'node:path'
+import type { DatabaseSync } from 'node:sqlite'
+import { AppError } from '../../../utils/errors'
+import { createAmlRepo, type AmlRepo } from './aml.repo'
+
+export interface AmlRuntime {
+  db: DatabaseSync
+  /** <configRoot>/data/aml 绝对路径 */
+  root: string
+  repo: AmlRepo
+  datasetsDir: string
+  jobsDir: string
+  modelsDir: string
+}
+
+const g = globalThis as typeof globalThis & { __amlRuntime?: AmlRuntime }
+
+export function configureAmlRuntime(db: DatabaseSync, dataDir: string): AmlRuntime {
+  if (g.__amlRuntime) return g.__amlRuntime
+  const root = join(dataDir, 'aml')
+  const rt: AmlRuntime = {
+    db,
+    root,
+    repo: createAmlRepo(db),
+    datasetsDir: join(root, 'datasets'),
+    jobsDir: join(root, 'jobs'),
+    modelsDir: join(root, 'models'),
+  }
+  g.__amlRuntime = rt
+  return rt
+}
+
+export function getAmlRuntime(): AmlRuntime {
+  if (!g.__amlRuntime) {
+    throw new AppError(503, 'AML_NOT_READY', 'AML 尚未初始化(workshop 插件未执行)')
+  }
+  return g.__amlRuntime
+}

package/server/services/workshop/aml/spec.ts

@@ -0,0 +1,63 @@
+/**
+ * AML 数据集规格:zod 校验(单一事实来源;REST 与 Agent 工具共用)。
+ * 隔离三元组 (lineId, productId, recipeId) 必填 —— 防 Recipe 串味是硬约束。
+ */
+import { z } from 'zod'
+import { AppError } from '../../../utils/errors'
+
+export const amlDatasetSpecSchema = z.object({
+  lineId: z.string().min(1),
+  productId: z.string().min(1),
+  recipeId: z.string().min(1),
+  /** 缺省 = 该配方全部已完结批次 */
+  runIds: z.array(z.string().min(1)).max(200).optional(),
+  nodes: z.array(z.object({
+    nodeId: z.string().min(1),
+    /** control = 可控输入(未来轨迹已知);target = 预测目标;feature = 仅历史特征 */
+    role: z.enum(['control', 'feature', 'target']),
+  })).min(2).max(64),
+  fromMs: z.number().int().nonnegative().optional(),
+  toMs: z.number().int().nonnegative().optional(),
+  /** 对齐节拍(ms),≥1000(与 daq 查询下限一致) */
+  beatMs: z.number().int().min(1000).max(3_600_000),
+  window: z.object({
+    historySteps: z.number().int().min(1).max(2048),
+    horizonSteps: z.number().int().min(1).max(512),
+  }),
+  cleaning: z.object({
+    /** Hampel 窗口半径(点数),0 = 关闭 */
+    hampelK: z.number().int().min(0).max(100).optional(),
+    /** 短缺口线性插值上限(ms) */
+    maxInterpMs: z.number().int().min(0).optional(),
+    /** 单 run 缺失率超过则整 run 丢弃 */
+    maxDropRatio: z.number().min(0).max(1).optional(),
+  }).optional(),
+  split: z.object({
+    valRatio: z.number().min(0).max(0.8),
+    testRatio: z.number().min(0).max(0.8),
+    seed: z.number().int(),
+  }).refine(s => s.valRatio + s.testRatio <= 0.9, { message: 'valRatio + testRatio 不得超过 0.9(须保留 train 切分)' }),
+  purpose: z.enum(['mpc_surrogate', 'quality_predict']),
+  note: z.string().max(2000).optional(),
+})
+
+export type AmlDatasetSpec = z.infer<typeof amlDatasetSpecSchema>
+
+export interface AmlNodeSpec {
+  nodeId: string
+  role: 'control' | 'feature' | 'target'
+}
+
+/** 解析失败抛 AppError(422,带 zod 首个 issue 的可读路径) */
+export function parseDatasetSpec(raw: unknown): AmlDatasetSpec {
+  const r = amlDatasetSpecSchema.safeParse(raw)
+  if (!r.success) {
+    const iss = r.error.issues[0]
+    if (!iss) throw new AppError(422, 'AML_SPEC_INVALID', '数据集规格不合法')
+    throw new AppError(422, 'AML_SPEC_INVALID', `数据集规格不合法:${iss.path.join('.')} ${iss.message}`)
+  }
+  if (r.data.nodes.filter(n => n.role === 'target').length === 0) {
+    throw new AppError(422, 'AML_SPEC_INVALID', '数据集规格不合法:至少需要 1 个 target 节点')
+  }
+  return r.data
+}