agentworkshop 0.7.70 → 0.8.0

package/server/services/workshop/aml/model-registry.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @stylistic/member-delimiter-style */
 /**
  * AML 模型注册表:实验/模型登记 + 阶段流转(candidate → shadow → production → retired)。
  *
@@ -7,8 +8,9 @@
  *  - 每 (product, recipe, purpose) 至多一个 production:晋升事务里同组旧 production 顺次 retired;
  *  - 候选/退役工件 GC 由 retention 扫描处理(注册表行永留,artifacts_pruned 标记缺文件)。
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { createHash } from 'node:crypto'
 import { AppError } from '../../../utils/errors'
 import { recordOps } from '../ops/ops'
 import { broadcastSceneEvent } from '../scene-events'
@@ -18,6 +20,7 @@ import { getDcwRecipeRepo } from '../dcw/dcw-recipe.repo'
 import { getAmlRuntime } from './runtime'
 import type { AmlModelRow, AmlModelStage } from './aml.repo'
 import type { GateReport } from './gates'
+import { assertArtifactKind, type ArtifactKind } from '../process-model/contracts'
 
 export type { AmlModelRow, AmlModelStage }
 
@@ -119,23 +122,49 @@ export function registerModelFromJob(jobId: string, gates: GateReport, metricsJs
   )
   if (!gates.passed) return { experimentId: expId }
 
-  // 工件快照:artifacts → models/<modelId>/(不可变;注册表行指向这里)
+  // ===== 工件校验与登记(C11 两阶段;A12 类型分派)=====
+  const artifactsDir = join(rt.jobsDir, jobId, 'artifacts')
+  const descriptor = readArtifactDescriptor(artifactsDir, metricsJson)
+  assertArtifactFiles(artifactsDir, descriptor)
+
   const modelId = `mdl-${jobId.slice(4)}`
+  // 幂等:重试命中已登记模型 → 返回同一 id,不产生第二份
+  const existingModel = rt.repo.model.get(modelId)
+  if (existingModel) return { experimentId: expId, modelId }
+
   const modelDir = join(rt.modelsDir, modelId)
-  if (!existsSync(modelDir)) {
-    mkdirSync(modelDir, { recursive: true })
-    cpSync(join(job.artifactsPath ?? join(rt.jobsDir, jobId, 'artifacts')), modelDir, { recursive: true })
-    // io_spec 快照(预测服务的输入契约;norm 来自数据集 manifest,评估器已嵌入 metrics)
-    writeFileSync(join(modelDir, 'REGISTERED'), now)
+  // 阶段一(文件):先写 staging,校验通过后同盘 rename 到 models/<modelId>/
+  const staging = join(rt.modelsDir, `.staging-${modelId}`)
+  rmSync(staging, { recursive: true, force: true })
+  mkdirSync(staging, { recursive: true })
+  try {
+    cpSync(artifactsDir, staging, { recursive: true })
+    const required = descriptor.requiredFiles
+    for (const file of required) {
+      const p = join(staging, file)
+      if (!existsSync(p) || statSync(p).size === 0) throw new AppError(500, 'AML_ARTIFACT_INCOMPLETE', `登记前工件校验失败:${file} 缺失或为空`)
+    }
+    writeFileSync(join(staging, 'REGISTERED'), now)
+    writeFileSync(join(staging, 'artifact_manifest.json'), JSON.stringify({
+      kind: descriptor.kind, schemaVersion: descriptor.schemaVersion, entryFile: descriptor.entryFile,
+      requiredFiles: required, artifactHash: descriptor.artifactHash,
+    }, null, 2))
+    rmSync(modelDir, { recursive: true, force: true })
+    renameSync(staging, modelDir)
   }
-  const ioSpec = buildIoSpec(dataset.path, job.purpose)
-  // io_spec.json 同步落到模型实体目录:元数据行的 io_spec_json 是索引,实体自带契约
-  // 才能让 ./aml 单独拷贝后仍可被预测服务装配(与 dataset 的 spec.json 同一范式)
+  catch (err) {
+    // 失败清理 staging;已 rename 的目录保留为孤儿,由 entity 对账回收(不静默删)
+    rmSync(staging, { recursive: true, force: true })
+    throw err
+  }
+
+  const ioSpec = buildIoSpecForKind(dataset.path, job.purpose, descriptor.kind, metricsJson, modelDir)
   try {
     writeFileSync(join(modelDir, 'io_spec.json'), JSON.stringify(ioSpec, null, 2))
   }
   catch { /* 契约文件落盘失败不阻断注册(元数据行仍持有同一份) */ }
   const identity = deriveModelIdentity(job, dataset, modelId)
+  // 阶段二(DB):单条 INSERT;调用方在同一收口里把 done + model_id 写回作业行
   rt.repo.model.insert({
     id: modelId,
     experimentId: expId,
@@ -152,17 +181,101 @@ export function registerModelFromJob(jobId: string, gates: GateReport, metricsJs
     description: identity.description,
     lineId: identity.lineId,
     objectiveId: identity.objectiveId,
+    artifactKind: descriptor.kind,
+    schemaVersion: descriptor.schemaVersion,
+    modelInterface: ioSpec.modelInterface,
+    artifactHash: descriptor.artifactHash,
     createdAt: now,
   })
   recordOps({
     actor: job.agentId || 'aml', actorName: job.agentId || 'AML', actorKind: job.agentId ? 'agent' : 'system',
-    action: 'aml.model.register', kind: 'system', summary: `候选模型 ${modelId} 登记(门禁通过)「${identity.label}」`,
+    action: 'aml.model.register', kind: 'system', summary: `候选模型 ${modelId} 登记(门禁通过,工件 ${descriptor.kind})「${identity.label}」`,
     targetKind: 'aml_model', targetId: modelId,
     lineId: dataset.lineId, productId: dataset.productId, recipeId: dataset.recipeId,
   })
   return { experimentId: expId, modelId }
 }
 
+interface ArtifactDescriptor {
+  kind: ArtifactKind
+  schemaVersion: number
+  entryFile: string
+  requiredFiles: string[]
+  artifactHash: string
+}
+
+function sha256File(path: string): string {
+  return createHash('sha256').update(readFileSync(path)).digest('hex')
+}
+
+/** 工件完整性摘要:覆盖**全部** requiredFiles(含 metrics/sidecar),按清单顺序拼接。 */
+function sha256Files(dir: string, files: string[]): string {
+  const hash = createHash('sha256')
+  for (const file of [...files].sort()) {
+    hash.update(file)
+    hash.update(readFileSync(join(dir, file)))
+  }
+  return hash.digest('hex')
+}
+
+/** 工件类型判别:未知类型一律拒绝(不静默回落到 ONNX)。 */
+export function readArtifactDescriptor(artifactsDir: string, metricsJson: string): ArtifactDescriptor {
+  const manifestPath = join(artifactsDir, 'artifact_manifest.json')
+  if (existsSync(manifestPath)) {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { kind?: string, schemaVersion?: number, entryFile?: string, requiredFiles?: string[], artifactHash?: string }
+    const kind = assertArtifactKind(manifest.kind)
+    const entryFile = manifest.entryFile ?? 'model.json'
+    const requiredFiles = manifest.requiredFiles ?? [entryFile, 'metrics.json']
+    const hashable = requiredFiles.filter(f => existsSync(join(artifactsDir, f)))
+    return {
+      kind,
+      schemaVersion: manifest.schemaVersion ?? 1,
+      entryFile,
+      requiredFiles,
+      // 多文件摘要优先:只哈希入口文件无法发现 metrics/sidecar 被替换
+      artifactHash: hashable.length ? sha256Files(artifactsDir, hashable) : (manifest.artifactHash ?? ''),
+    }
+  }
+  // 旧链兼容:hybrid_manifest.json → hybrid_manifest@1;否则 ONNX 一步预测
+  const metrics = safeParseMetrics(metricsJson)
+  if (typeof metrics.artifactKind === 'string' && metrics.artifactKind) {
+    const kind = assertArtifactKind(metrics.artifactKind)
+    const entryFile = 'model.json'
+    return {
+      kind, schemaVersion: 1, entryFile, requiredFiles: [entryFile, 'metrics.json'],
+      artifactHash: existsSync(join(artifactsDir, entryFile)) ? sha256File(join(artifactsDir, entryFile)) : '',
+    }
+  }
+  if (existsSync(join(artifactsDir, 'hybrid_manifest.json'))) {
+    return {
+      kind: 'hybrid_manifest@1', schemaVersion: 1, entryFile: 'model.onnx', requiredFiles: ['model.onnx'],
+      artifactHash: typeof metrics.artifactHash === 'string' ? metrics.artifactHash : (existsSync(join(artifactsDir, 'model.onnx')) ? sha256File(join(artifactsDir, 'model.onnx')) : ''),
+    }
+  }
+  const stub = existsSync(join(artifactsDir, 'STUB'))
+  if (stub) return { kind: 'onnx_one_step@1', schemaVersion: 1, entryFile: 'STUB', requiredFiles: ['STUB'], artifactHash: '' }
+  return {
+    kind: 'onnx_one_step@1', schemaVersion: 1, entryFile: 'model.onnx', requiredFiles: ['model.onnx'],
+    artifactHash: existsSync(join(artifactsDir, 'model.onnx')) ? sha256File(join(artifactsDir, 'model.onnx')) : '',
+  }
+}
+
+function assertArtifactFiles(artifactsDir: string, descriptor: ArtifactDescriptor): void {
+  for (const file of descriptor.requiredFiles) {
+    const p = join(artifactsDir, file)
+    if (!existsSync(p)) throw new AppError(500, 'AML_ARTIFACT_MISSING', `工件校验失败:${descriptor.kind} 必需文件 ${file} 不存在`)
+  }
+}
+
+function safeParseMetrics(metricsJson: string): Record<string, unknown> {
+  try {
+    return JSON.parse(metricsJson || '{}') as Record<string, unknown>
+  }
+  catch {
+    return {}
+  }
+}
+
 function gatesSummary(gates: GateReport): string {
   return gates.checks.map(c => `${c.id}:${c.pass ? '✓' : '✗'}${c.value != null ? `(${typeof c.value === 'number' ? c.value.toFixed(3) : c.value})` : ''}`).join(' ')
 }
@@ -192,6 +305,65 @@ function buildIoSpec(datasetPath: string, purpose: string): Record<string, unkno
   }
 }
 
+/** 按工件类型生成 io_spec(G2.8 全链分派;旧 one_step 语义不动)。 */
+function buildIoSpecForKind(datasetPath: string, purpose: string, kind: ArtifactKind, metricsJson: string, modelDir: string): Record<string, unknown> & { modelInterface: string } {
+  if (kind === 'onnx_one_step@1' || kind === 'hybrid_manifest@1') {
+    return buildIoSpec(datasetPath, purpose) as Record<string, unknown> & { modelInterface: string }
+  }
+  const manifest = JSON.parse(readFileSync(join(datasetPath, 'manifest.json'), 'utf8')) as {
+    allNodes: string[]; controlNodes: string[]; targetNodes: string[]
+    shapes: { x: [number, number, number], u: [number, number, number], y: [number, number, number] }
+    norm: Record<string, { mean: number[], std: number[] }>; beatMs: number
+    variables?: Array<{ id: string, nodeId: string, role: string, unit: string, modelUnit?: string, scale: number, offset: number, delayMs?: number }>
+  }
+  const metrics = safeParseMetrics(metricsJson)
+  if (kind === 'linear_state_space@1') {
+    const artifact = JSON.parse(readFileSync(join(modelDir, 'model.json'), 'utf8')) as { mvOrder: string[], cvOrder: string[], arOrder: number, inputOrder: number, delaysSteps: Record<string, number>, K: number }
+    return {
+      version: 2,
+      purpose,
+      modelInterface: 'linear_state_space',
+      artifactKind: kind,
+      historySteps: manifest.shapes.x[1],
+      horizonSteps: manifest.shapes.u[1],
+      allNodes: manifest.allNodes,
+      controlNodes: manifest.controlNodes,
+      targetNodes: manifest.targetNodes,
+      mvOrder: artifact.mvOrder,
+      cvOrder: artifact.cvOrder,
+      arOrder: artifact.arOrder,
+      inputOrder: artifact.inputOrder,
+      delaysSteps: artifact.delaysSteps,
+      K: artifact.K,
+      variables: manifest.variables ?? [],
+      norm: manifest.norm,
+      beatMs: manifest.beatMs,
+      assumptions: '状态空间 rollout:sy=y 历史寄存器,su=输入延迟线;y(k)=Cx(k);Δu 基准 uPrev',
+      metricsSummary: metrics.artifactKind ? { artifactKind: metrics.artifactKind } : undefined,
+    }
+  }
+  const artifact = JSON.parse(readFileSync(join(modelDir, 'model.json'), 'utf8')) as { mvOrder: string[], cvOrder: string[], featureOrder: string[], order: number }
+  return {
+    version: 2,
+    purpose,
+    modelInterface: 'static_response',
+    artifactKind: kind,
+    historySteps: manifest.shapes.x[1],
+    horizonSteps: manifest.shapes.u[1],
+    allNodes: manifest.allNodes,
+    controlNodes: manifest.controlNodes,
+    targetNodes: manifest.targetNodes,
+    mvOrder: artifact.mvOrder,
+    cvOrder: artifact.cvOrder,
+    featureOrder: artifact.featureOrder,
+    order: artifact.order,
+    variables: manifest.variables ?? [],
+    norm: manifest.norm,
+    beatMs: manifest.beatMs,
+    assumptions: '稳态响应面:cv = f(MV);优化器按有界参数搜索',
+  }
+}
+
 export function parseIoSpec(model: AmlModelRow): ReturnType<typeof buildIoSpec> {
   return JSON.parse(model.ioSpecJson) as ReturnType<typeof buildIoSpec>
 }

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

@@ -8,9 +8,11 @@ import { createRequire } from 'node:module'
 import { AppError } from '../../../utils/errors'
 import { createLogger } from '../logger'
 import { getAmlRuntime } from './runtime'
+import type { AmlModelRow } from './aml.repo'
 import { parseIoSpec } from './model-registry'
 import { compileDeclarativeProvider } from './twin/declarative-provider'
 import { parsePhysicsSpec, type PhysicsSpec } from './twin/physics-spec'
+import { assertArxArtifactCurrent } from '../process-model/artifact-validation'
 
 const log = createLogger('aml.predict')
 
@@ -145,9 +147,9 @@ function hybridPhysicsNext(manifest: HybridArtifactManifest, io: IoSpec, history
 }
 
 export interface PredictRequest {
-  /** 历史(原始物理量):[historySteps][nAllNodes],顺序 = io_spec.allNodes */
+  /** 历史:[historySteps][nAllNodes],顺序 = io_spec.allNodes;ONNX 为原始物理量,typed 工件为模型单位(调用方负责 scale/offset)。 */
   history: number[][]
-  /** 未来控制轨迹(原始物理量):[≤horizonSteps][nControlNodes];缺省 = 持最后观测 */
+  /** 未来控制轨迹:[≤horizonSteps][nControlNodes];单位同 history,typed 列顺序 = mvOrder;缺省 = 持最后观测。 */
   controls?: number[][]
   /** 滚动步数(≤horizonSteps;缺省 = horizonSteps) */
   steps?: number
@@ -157,7 +159,7 @@ export interface PredictResult {
   modelId: string
   stage: string
   targetNodes: string[]
-  /** 原始物理量预测:[steps][nTargetNodes] */
+  /** 预测:[steps][nTargetNodes];ONNX 为原始物理量,typed 工件为模型单位。 */
   forecast: number[][]
   beatMs: number
   assumptions: string
@@ -171,10 +173,18 @@ export async function predictWithModel(
   const rt = getAmlRuntime()
   const row = rt.repo.model.get(modelId)
   if (!row) throw new AppError(404, 'AML_MODEL_MISSING', `模型 ${modelId} 不存在`)
+  const artifactKind = resolveArtifactKind(row)
   if (existsSync(join(row.path, 'STUB'))) {
     throw new AppError(409, 'AML_STUB_MODEL', '该模型为存根作业产物(AML_STUB),不含真实权重,不可用于预测')
   }
-  if (row.artifactsPruned || !existsSync(join(row.path, 'model.onnx'))) {
+  if (row.artifactsPruned) {
+    throw new AppError(410, 'AML_ARTIFACT_MISSING', `模型 ${modelId} 工件已被 GC 清理(artifacts_pruned),请用同配方数据重训`)
+  }
+  // 新工件类型分派(linear_state_space/static_response):不要求 model.onnx
+  if (artifactKind === 'linear_state_space@1' || artifactKind === 'static_response@1') {
+    return predictWithTypedArtifact(row, artifactKind, req)
+  }
+  if (!existsSync(join(row.path, 'model.onnx'))) {
     throw new AppError(410, 'AML_ARTIFACT_MISSING', `模型 ${modelId} 工件已被 GC 清理(artifacts_pruned),请用同配方数据重训`)
   }
   const io = parseIoSpec(row) as unknown as IoSpec
@@ -282,11 +292,31 @@ export async function predictProduction(
   return predictWithModel(m.id, req)
 }
 
-/** 注册时深检:ONNX 可加载 + 试推理形状正确(异步,REST 注册/晋升前调用) */
+/** 注册时深检:按工件类型分派(新工件校验 model.json 维度;ONNX 走试推理) */
 export async function verifyModelArtifact(modelId: string): Promise<{ ok: boolean, detail: string }> {
   const rt = getAmlRuntime()
   const row = rt.repo.model.get(modelId)
   if (!row) return { ok: false, detail: '模型不存在' }
+  const kind = resolveArtifactKind(row)
+  if (kind === 'linear_state_space@1' || kind === 'static_response@1') {
+    try {
+      const artifact = JSON.parse(readFileSync(join(row.path, 'model.json'), 'utf8')) as Record<string, unknown>
+      if (artifact.kind !== kind) return { ok: false, detail: `工件 kind=${String(artifact.kind)} 与注册类型 ${kind} 不一致` }
+      assertArxArtifactCurrent(artifact, modelId)
+      if (kind === 'linear_state_space@1') {
+        const stateDim = Number(artifact.stateDim)
+        const A = artifact.A as number[][]
+        if (!Array.isArray(A) || A.length !== stateDim || A.some(r => r.length !== stateDim)) return { ok: false, detail: '状态矩阵维度不一致' }
+      }
+      else if (!artifact.coefficients || typeof artifact.coefficients !== 'object') {
+        return { ok: false, detail: '响应面系数缺失' }
+      }
+      return { ok: true, detail: `${kind} 工件结构校验通过` }
+    }
+    catch (err) {
+      return { ok: false, detail: `工件加载失败:${err instanceof Error ? err.message : String(err)}` }
+    }
+  }
   if (!predictorAvailable()) return { ok: false, detail: 'onnxruntime-node 不可用' }
   try {
     const io = parseIoSpec(row) as unknown as IoSpec
@@ -312,6 +342,118 @@ export async function verifyModelArtifact(modelId: string): Promise<{ ok: boolea
   }
 }
 
+/** 历史行 artifactKind 为空:由 hybrid_manifest 存在性/默认 ONNX 推断(不伪造新语义)。 */
+export function resolveArtifactKind(row: AmlModelRow): string {
+  if (row.artifactKind) return row.artifactKind
+  return existsSync(join(row.path, 'hybrid_manifest.json')) ? 'hybrid_manifest@1' : 'onnx_one_step@1'
+}
+
+/**
+ * 新工件预测(linear_state_space / static_response):
+ * history[H][nAll]、controls 与 forecast 使用工件模型单位,此处不施加 scale/offset。
+ * allNodes/返回 targetNodes 为实际节点 ID;矩阵与系数顺序保留 mvOrder/cvOrder 的逻辑变量 ID。
+ */
+async function predictWithTypedArtifact(row: AmlModelRow, kind: string, req: PredictRequest): Promise<PredictResult> {
+  const io = parseIoSpec(row) as unknown as IoSpec & { mvOrder?: string[], cvOrder?: string[], featureOrder?: string[], variables?: Array<{ id: string, nodeId: string }> }
+  const H = io.historySteps
+  const nAll = io.allNodes.length
+  if (!Array.isArray(req.history) || req.history.length !== H || req.history.some(r => !Array.isArray(r) || r.length !== nAll)) {
+    throw new AppError(422, 'AML_INPUT_SHAPE', `history 形状须为 [${H}][${nAll}](节点顺序 = allNodes):${io.allNodes.join(',')}`)
+  }
+  const artifact = JSON.parse(readFileSync(join(row.path, 'model.json'), 'utf8')) as Record<string, unknown>
+  assertArxArtifactCurrent(artifact, row.id)
+  const mvOrder = (io.mvOrder ?? io.controlNodes) as string[]
+  const cvOrder = (io.cvOrder ?? io.targetNodes) as string[]
+  const resolveNodes = (order: string[]): string[] => order.map((id) => {
+    const mappings = (io.variables ?? []).filter(variable => variable.id === id)
+    if (mappings.length > 1) throw new AppError(500, 'AML_IO_UNSUPPORTED', `io_spec 的变量 ${id} 存在重复节点映射`)
+    // 旧 typed 工件直接以节点 ID 记录顺序;新工件通过 variables 映射,不改写冻结的逻辑顺序。
+    const nodeId = mappings.length ? mappings[0]?.nodeId : id
+    if (!nodeId || io.allNodes.filter(node => node === nodeId).length !== 1) {
+      throw new AppError(500, 'AML_IO_UNSUPPORTED', `io_spec 的变量 ${id} 缺少唯一的 allNodes 节点映射`)
+    }
+    return nodeId
+  })
+  const mvNodes = resolveNodes(mvOrder)
+  const cvNodes = resolveNodes(cvOrder)
+  if (new Set([...mvNodes, ...cvNodes]).size !== mvNodes.length + cvNodes.length) {
+    throw new AppError(500, 'AML_IO_UNSUPPORTED', 'io_spec 的多个 MV/CV 变量映射到同一节点')
+  }
+  const mvIdx = mvNodes.map(id => io.allNodes.indexOf(id))
+  const cvIdx = cvNodes.map(id => io.allNodes.indexOf(id))
+  const steps = Math.max(1, Math.min(req.steps ?? io.horizonSteps, io.horizonSteps))
+  const last = req.history[req.history.length - 1] ?? []
+
+  if (kind === 'static_response@1') {
+    const coefficients = artifact.coefficients as Record<string, number[]>
+    const featureOrder = (artifact.featureOrder ?? io.featureOrder ?? []) as string[]
+    const u = mvIdx.map((idx, m) => req.controls?.[0]?.[m] ?? last[idx] ?? 0)
+    const y = cvOrder.map(cv => evaluateStaticFeature(coefficients[cv] ?? [], featureOrder, mvOrder, u))
+    return {
+      modelId: row.id, stage: row.stage, targetNodes: cvNodes, forecast: Array.from({ length: steps }, () => [...y]),
+      beatMs: io.beatMs, assumptions: `${kind}: cv=f(MV) 稳态响应面;多步输出为同一稳态解`,
+    }
+  }
+
+  const A = artifact.A as number[][]
+  const B = artifact.B as number[][]
+  const C = artifact.C as number[][]
+  const D = artifact.D as number[][]
+  const bias = (artifact.bias ?? []) as number[]
+  const ar = Number(artifact.arOrder)
+  const K = Number(artifact.K)
+  const stateDim = Number(artifact.stateDim)
+  const layout = artifact.layout as { yOffset: number, uOffset: number }
+  const x = new Array<number>(stateDim).fill(0)
+  for (let j = 0; j < cvOrder.length; j++) {
+    for (let i = 0; i < ar; i++) x[layout.yOffset + j * ar + i] = req.history[H - 1 - i]?.[cvIdx[j]!] ?? 0
+  }
+  for (let m = 0; m < mvOrder.length; m++) {
+    for (let q = 0; q < K; q++) x[layout.uOffset + m * K + q] = req.history[H - 1 - q]?.[mvIdx[m]!] ?? 0
+  }
+  const forecast: number[][] = []
+  for (let k = 0; k < steps; k++) {
+    const u = mvIdx.map((idx, m) => req.controls?.[k]?.[m] ?? last[idx] ?? 0)
+    const next = new Array<number>(stateDim).fill(0)
+    for (let r = 0; r < stateDim; r++) {
+      let v = bias[r] ?? 0
+      for (let c = 0; c < stateDim; c++) v += (A[r]?.[c] ?? 0) * (x[c] ?? 0)
+      for (let m = 0; m < mvOrder.length; m++) v += (B[r]?.[m] ?? 0) * (u[m] ?? 0)
+      next[r] = v
+    }
+    for (let c = 0; c < stateDim; c++) x[c] = next[c]!
+    forecast.push(cvOrder.map((_id, j) => {
+      let y = 0
+      for (let c = 0; c < stateDim; c++) y += (C[j]?.[c] ?? 0) * (x[c] ?? 0)
+      for (let m = 0; m < mvOrder.length; m++) y += (D[j]?.[m] ?? 0) * (u[m] ?? 0)
+      return y
+    }))
+  }
+  return {
+    modelId: row.id, stage: row.stage, targetNodes: cvNodes, forecast,
+    beatMs: io.beatMs, assumptions: `${kind}: y(k)=Cx(k),x(k+1)=Ax(k)+Bu(k)+bias`,
+  }
+}
+
+function evaluateStaticFeature(coefficients: number[], featureOrder: string[], mvOrder: string[], u: number[]): number {
+  const byName = new Map<string, number>()
+  mvOrder.forEach((id, i) => byName.set(id, u[i] ?? 0))
+  let sum = 0
+  for (let k = 0; k < featureOrder.length; k++) {
+    const name = featureOrder[k]!
+    let value: number
+    if (name === 'bias') value = 1
+    else if (name.endsWith('^2')) value = (byName.get(name.slice(0, -2)) ?? 0) ** 2
+    else if (name.includes('*')) {
+      const [a, b] = name.split('*')
+      value = (byName.get(a!) ?? 0) * (byName.get(b!) ?? 0)
+    }
+    else value = byName.get(name) ?? 0
+    sum += (coefficients[k] ?? 0) * value
+  }
+  return sum
+}
+
 /** 供工具层:最近窗口组装(history 取自传入原始行,不做 DAQ 查询 —— 查询在工具层完成) */
 export function readIoSpecFor(modelId: string): IoSpec {
   const rt = getAmlRuntime()

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

@@ -7,3 +7,6 @@ onnxscript>=0.1
 onnxruntime>=1.18
 
 scipy==1.14.1
+# Optimizer Solver(linear MPC):与 scipy 同一共享 .venv,不建第二套环境。
+# 版本锁定与已安装解释器一致(osqp 1.x 的 OSQP()/setup/solve API)。
+osqp==1.1.3

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

@@ -19,6 +19,7 @@ import { resolveOnPath, spawnLineProcess } from '../agents/adapters/line-spawn'
 import { killHarnessProcess } from '../agents/harness-process'
 import { createLogger } from '../logger'
 import { amlSettings } from '../settings'
+import { assertEnvIdleForMaintenance } from './env-lease'
 import type { AmlRuntime } from './runtime'
 
 const log = createLogger('aml.py')
@@ -482,6 +483,11 @@ export function requirementsHash(): string {
   return createHash('sha256').update(content).update(idx).digest('hex').slice(0, 12)
 }
 
+/** 完整依赖锁摘要(与 marker 同源,单独暴露给 A7/A22 的"同一 lock hash"断言)。 */
+export function requirementsLockHash(): string {
+  return requirementsHash()
+}
+
 /** venv 就绪标记路径(内容摘要变更即视为需重建) */
 export function venvMarkerPath(rt: AmlRuntime): string {
   return join(venvDir(rt), `.aml-ok-${requirementsHash()}`)
@@ -491,12 +497,36 @@ export function isVenvReady(rt: AmlRuntime): boolean {
   return existsSync(venvMarkerPath(rt)) && existsSync(venvPythonPath(rt))
 }
 
+/**
+ * 环境身份(AML 训练与 Optimizer Solver 必须是同一解释器/同一 lock):
+ * 供 `/api/.../env` 与 `optimizer_capabilities` 报告,不参与就绪判定。
+ */
+export function venvIdentity(rt: AmlRuntime): {
+  pythonPath: string
+  marker: string
+  requirementsHash: string
+  platform: string
+  pythonVersion: string | null
+  ready: boolean
+} {
+  return {
+    pythonPath: venvPythonPath(rt),
+    marker: venvMarkerPath(rt),
+    requirementsHash: requirementsHash(),
+    platform: `${process.platform}-${process.arch}`,
+    pythonVersion: null,
+    ready: isVenvReady(rt),
+  }
+}
+
 /**
  * 共享 venv 供给(幂等):marker 文件校验 requirements+indexUrl 摘要;并发调用共享同一 Promise。
  * 返回 venv 内 python 绝对路径。force=true 时删掉旧 venv 重建(UI「重建环境」)。
  */
-export async function ensureVenv(rt: AmlRuntime, opts: { force?: boolean, onLog?: ProgressFn } = {}): Promise<string> {
+export async function ensureVenv(rt: AmlRuntime, opts: { force?: boolean, onLog?: ProgressFn, leaseHolder?: string } = {}): Promise<string> {
   if (opts.force) {
+    // 重建必须独占:有训练/求解读者时拒绝(不 rmSync 他们正在用的目录)
+    assertEnvIdleForMaintenance(opts.leaseHolder ?? 'ensure-venv-force')
     try {
       rmSync(venvDir(rt), { recursive: true, force: true })
       emitLog(opts.onLog, `已清理旧环境:${venvDir(rt)}`)
@@ -507,6 +537,8 @@ export async function ensureVenv(rt: AmlRuntime, opts: { force?: boolean, onLog?
     g.__amlVenvPromise = undefined
   }
   if (g.__amlVenvPromise && !opts.force) return g.__amlVenvPromise
+  // 未就绪 = 本次调用会安装依赖(改环境),同样要求在途读者为 0。
+  if (!opts.force && !isVenvReady(rt)) assertEnvIdleForMaintenance(opts.leaseHolder ?? 'ensure-venv-install')
   const task = (async () => {
     const vdir = venvDir(rt)
     const vpy = venvPythonPath(rt)
@@ -531,9 +563,12 @@ export async function ensureVenv(rt: AmlRuntime, opts: { force?: boolean, onLog?
     emitLog(opts.onLog, `开始供给 Python 环境(首次可能需数分钟下载依赖)…`)
 
     if (probe.uvPath) {
-      emitLog(opts.onLog, `uv venv ${vdir} --python ${basePython}`)
-      const mk = await runCapture(probe.uvPath, ['venv', vdir, '--python', basePython], VENV_CREATE_TIMEOUT_MS, opts.onLog)
-      if (mk.code !== 0) throw new AppError(500, 'AML_VENV_FAILED', `uv venv 失败:${mk.err.slice(-400)}`)
+      // 目录已存在时不要重复 `uv venv`(uv 会以 "already exists" 失败):只补依赖。
+      if (!existsSync(vpy)) {
+        emitLog(opts.onLog, `uv venv ${vdir} --python ${basePython}`)
+        const mk = await runCapture(probe.uvPath, ['venv', vdir, '--python', basePython], VENV_CREATE_TIMEOUT_MS, opts.onLog)
+        if (mk.code !== 0) throw new AppError(500, 'AML_VENV_FAILED', `uv venv 失败:${mk.err.slice(-400)}`)
+      }
       emitLog(opts.onLog, `uv pip install -r requirements.txt`)
       const inst = await runCapture(probe.uvPath, ['pip', 'install', '--python', vpy, '-r', reqPath, ...idxArgs], PIP_INSTALL_TIMEOUT_MS, opts.onLog)
       if (inst.code !== 0) throw new AppError(500, 'AML_VENV_FAILED', `依赖安装失败:${(inst.err || inst.out).slice(-400)}`)