agentworkshop 0.7.48 → 0.7.50

package/server/services/workshop/aml/twin/calibration-worker.ts

@@ -0,0 +1,150 @@
+/**
+ * 持续校准 worker:消费 twin_update_runs 里排队的新数据信号,自动发起
+ * hybrid_residual 重训候选(冻结场景 + 最新编译 PhysicsSpec + 该配方最新数据集)。
+ *
+ * 纪律(plan §8.3/§9.4.3):
+ *  - 只生成 candidate;绝不自动晋升 production(晋升仍走 HITL + Twin Gate);
+ *  - 训练开关(AML_TWIN_TRAINING_ENABLED/CHANNEL_ENABLED)关闭时整个 worker 空转;
+ *  - 每条 run 状态机 queued → running(携带 job_id)→ succeeded/failed,
+ *    由 concludeJob 钩子收口;提交失败直接 failed,不阻塞后续信号。
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { DatabaseSync } from 'node:sqlite'
+import { createLogger } from '../../logger'
+import { submitJob } from '../job-orchestrator'
+import { getAmlRuntime } from '../runtime'
+import { amlTwinFeatureFlags } from './feature-flags'
+import { compileDeclarativeProvider } from './declarative-provider'
+import { validatePhysicsSpec, type PhysicsSpec } from './physics-spec'
+
+const log = createLogger('aml.twin-worker')
+
+interface UpdateRunRow {
+  id: string
+  requestId: string
+  dedupKey: string
+  sceneId: string
+  lineId: string
+  recipeId: string
+  state: string
+  payloadJson: string
+  createdAt: string
+}
+
+function frozenSceneLatest(db: DatabaseSync, sceneId: string): { sceneVersion: string, contract: Record<string, unknown>, objectiveProfileIds: string[] } | undefined {
+  const row = db.prepare(
+    `SELECT scene_version AS sceneVersion, contract_json AS contractJson FROM twin_scenes
+     WHERE scene_id = ? AND status = 'frozen' ORDER BY created_at DESC LIMIT 1`,
+  ).get(sceneId) as { sceneVersion?: string, contractJson?: string } | undefined
+  if (!row?.contractJson) return undefined
+  try {
+    const contract = JSON.parse(row.contractJson) as Record<string, unknown>
+    const ids = Array.isArray(contract.objectiveProfileIds) ? contract.objectiveProfileIds as string[] : []
+    return { sceneVersion: String(row.sceneVersion), contract, objectiveProfileIds: ids }
+  }
+  catch {
+    return undefined
+  }
+}
+
+/** 最近一次为该场景编译通过的 PhysicsSpec 工件(twin_physics_spec_compile 落盘) */
+function latestCompiledSpecForScene(root: string, sceneId: string): PhysicsSpec | undefined {
+  const dir = join(root, 'twins', 'physics-spec')
+  if (!existsSync(dir)) return undefined
+  const candidates: Array<{ at: string, spec: PhysicsSpec }> = []
+  for (const entry of readdirSync(dir)) {
+    const file = join(dir, entry, 'physics-spec.json')
+    if (!existsSync(file)) continue
+    try {
+      const artifact = JSON.parse(readFileSync(file, 'utf8')) as { sceneId?: string, spec?: unknown, compiledAt?: string }
+      if (artifact.sceneId !== sceneId || !artifact.spec) continue
+      const checked = validatePhysicsSpec(artifact.spec)
+      if (checked.valid && checked.spec) candidates.push({ at: String(artifact.compiledAt ?? ''), spec: checked.spec })
+    }
+    catch { /* 跳过损坏工件 */ }
+  }
+  candidates.sort((a, b) => b.at.localeCompare(a.at))
+  return candidates[0]?.spec
+}
+
+export function processQueuedTwinUpdates(): number {
+  const flags = amlTwinFeatureFlags()
+  if (!flags.channelEnabled || !flags.trainingEnabled) return 0
+  const rt = getAmlRuntime()
+  const queued = rt.db.prepare(
+    `SELECT id, request_id AS requestId, dedup_key AS dedupKey, scene_id AS sceneId, line_id AS lineId,
+            recipe_id AS recipeId, state, payload_json AS payloadJson, created_at AS createdAt
+     FROM twin_update_runs WHERE state = 'queued' ORDER BY created_at LIMIT 10`,
+  ).all() as unknown as UpdateRunRow[]
+  let dispatched = 0
+  for (const run of queued) {
+    const scene = frozenSceneLatest(rt.db, run.sceneId)
+    if (!scene) {
+      rt.db.prepare(`UPDATE twin_update_runs SET state = 'failed', error = ?, ended_at = ? WHERE id = ? AND state = 'queued'`)
+        .run(`场景 ${run.sceneId} 无冻结 SceneContract:先 twin_scene_compile/freeze 再请求校准`, new Date().toISOString(), run.id)
+      continue
+    }
+    const spec = latestCompiledSpecForScene(rt.root, run.sceneId)
+    if (!spec) {
+      rt.db.prepare(`UPDATE twin_update_runs SET state = 'failed', error = ?, ended_at = ? WHERE id = ? AND state = 'queued'`)
+        .run(`场景 ${run.sceneId} 无已编译 PhysicsSpec 工件:先 twin_physics_spec_compile`, new Date().toISOString(), run.id)
+      continue
+    }
+    const [dataset] = rt.repo.dataset.list({ lineId: run.lineId, ...(run.recipeId ? { recipeId: run.recipeId } : {}), limit: 1 })
+    if (!dataset) {
+      rt.db.prepare(`UPDATE twin_update_runs SET state = 'failed', error = ?, ended_at = ? WHERE id = ? AND state = 'queued'`)
+        .run(`产线 ${run.lineId}/配方 ${run.recipeId || '(任意)'} 无可用数据集:先 aml_dataset_build`, new Date().toISOString(), run.id)
+      continue
+    }
+    const claimed = rt.db.prepare(`UPDATE twin_update_runs SET state = 'running', started_at = ? WHERE id = ? AND state = 'queued'`)
+      .run(new Date().toISOString(), run.id)
+    if (Number(claimed.changes) !== 1) continue
+    try {
+      const manifest = compileDeclarativeProvider(spec).manifest
+      const job = submitJob({
+        datasetId: dataset.id,
+        jobKind: 'hybrid_residual',
+        sceneId: run.sceneId,
+        sceneVersion: scene.sceneVersion,
+        objectiveId: scene.objectiveProfileIds[0] ?? undefined,
+        physicsSpec: spec as unknown as Record<string, unknown>,
+        providerId: manifest.physicsModelId,
+        providerVersion: manifest.version,
+        providerHash: manifest.sourceHash,
+        modelName: `持续校准 ${run.sceneId}@${scene.sceneVersion}`,
+        modelDescription: `校准 worker 自动发起:${run.sceneId} 场景在产线 ${run.lineId}/配方 ${run.recipeId || '(任意)'} 的 hybrid 残差重训候选`,
+      })
+      const payload = { ...(JSON.parse(run.payloadJson || '{}') as Record<string, unknown>), jobId: job.id }
+      rt.db.prepare(`UPDATE twin_update_runs SET payload_json = ? WHERE id = ?`).run(JSON.stringify(payload), run.id)
+      dispatched += 1
+      log.info(`[twin-worker] 校准信号 ${run.id} → 训练作业 ${job.id}(scene=${run.sceneId}, dataset=${dataset.id})`)
+    }
+    catch (err) {
+      rt.db.prepare(`UPDATE twin_update_runs SET state = 'failed', error = ?, ended_at = ? WHERE id = ? AND state = 'running'`)
+        .run(`训练作业提交失败:${err instanceof Error ? err.message : String(err)}`, new Date().toISOString(), run.id)
+    }
+  }
+  return dispatched
+}
+
+/** concludeJob 钩子:按 job_id 收口 running 状态的校准 run(成功=候选就绪,失败=保留旧生产) */
+export function markTwinUpdateRunFinished(jobId: string, ok: boolean, error?: string): void {
+  try {
+    const rt = getAmlRuntime()
+    const rows = rt.db.prepare(`SELECT id, payload_json AS payloadJson FROM twin_update_runs WHERE state = 'running'`).all() as unknown as Array<{ id: string, payloadJson: string }>
+    for (const row of rows) {
+      try {
+        const payload = JSON.parse(row.payloadJson || '{}') as { jobId?: string }
+        if (payload.jobId !== jobId) continue
+        rt.db.prepare(`UPDATE twin_update_runs SET state = ?, error = ?, ended_at = ?, cooldown_until = ? WHERE id = ?`)
+          .run(ok ? 'succeeded' : 'failed', ok ? '' : (error ?? 'training failed'), new Date().toISOString(), new Date(Date.now() + 3600_000).toISOString(), row.id)
+        return
+      }
+      catch { /* payload 损坏的行跳过 */ }
+    }
+  }
+  catch (err) {
+    log.warn(`[twin-worker] 校准 run 收口失败(job=${jobId}):${err instanceof Error ? err.message : String(err)}`)
+  }
+}

package/server/services/workshop/aml/twin/channel-profile.ts

@@ -1,29 +1,43 @@
 import type { DatabaseSync } from 'node:sqlite'
+import { AppError } from '../../../../utils/errors'
 import { getAmlRuntime } from '../../aml/runtime'
 
+export type AmlChannelProfileKind = 'legacy' | 'hybrid_twin' | 'aml_training' | 'aml_optimization'
+export type OptimizationMode = 'exploration' | 'aml'
+
 export interface HybridChannelProfile {
   channelId: string
-  profile: 'legacy' | 'hybrid_twin'
+  profile: AmlChannelProfileKind
   capability: Record<string, unknown>
   sceneId?: string
   sceneVersion?: string
   sceneContract?: Record<string, unknown>
   objective?: Record<string, unknown>
   controlPolicy: 'recommendation_only' | 'hitl_governed' | 'bounded_auto'
+  providerId?: string
+  providerVersion?: string
+  providerHash?: string
+  scenePackId?: string
+  providerGeneration?: number
+  /** 工艺优化 Channel 绑定的 AML 模型(谱系+门禁校验通过后写入;解绑/探索模式为空) */
+  boundModelId?: string
+  boundAt?: string
+  /** 工艺优化 Channel 子模式:exploration(真实写入探索,无 MPC) | aml(绑定模型,trial/bayes) */
+  optimizationMode?: OptimizationMode
 }
 
 function repo(db: DatabaseSync) {
-  const upsert = db.prepare(`INSERT INTO aml_channel_profiles(channel_id,profile,capability_json,scene_id,scene_version,scene_contract_json,objective_json,control_policy,created_by,created_at,updated_at)
-    VALUES(?,?,?,?,?,?,?,?,?,?,?)
-    ON CONFLICT(channel_id) DO UPDATE SET profile=excluded.profile, capability_json=excluded.capability_json, scene_id=excluded.scene_id, scene_version=excluded.scene_version, scene_contract_json=excluded.scene_contract_json, objective_json=excluded.objective_json, control_policy=excluded.control_policy, updated_at=excluded.updated_at`)
-  const get = db.prepare(`SELECT channel_id AS channelId, profile, capability_json AS capabilityJson, scene_id AS sceneId, scene_version AS sceneVersion, scene_contract_json AS sceneContractJson, objective_json AS objectiveJson, control_policy AS controlPolicy FROM aml_channel_profiles WHERE channel_id=?`)
+  const upsert = db.prepare(`INSERT INTO aml_channel_profiles(channel_id,profile,capability_json,scene_id,scene_version,scene_contract_json,objective_json,control_policy,provider_id,provider_version,provider_hash,scene_pack_id,provider_generation,bound_model_id,bound_at,optimization_mode,created_by,created_at,updated_at)
+    VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+    ON CONFLICT(channel_id) DO UPDATE SET profile=excluded.profile, capability_json=excluded.capability_json, scene_id=excluded.scene_id, scene_version=excluded.scene_version, scene_contract_json=excluded.scene_contract_json, objective_json=excluded.objective_json, control_policy=excluded.control_policy, provider_id=excluded.provider_id, provider_version=excluded.provider_version, provider_hash=excluded.provider_hash, scene_pack_id=excluded.scene_pack_id, provider_generation=excluded.provider_generation, bound_model_id=excluded.bound_model_id, bound_at=excluded.bound_at, optimization_mode=excluded.optimization_mode, updated_at=excluded.updated_at`)
+  const get = db.prepare(`SELECT channel_id AS channelId, profile, capability_json AS capabilityJson, scene_id AS sceneId, scene_version AS sceneVersion, scene_contract_json AS sceneContractJson, objective_json AS objectiveJson, control_policy AS controlPolicy, provider_id AS providerId, provider_version AS providerVersion, provider_hash AS providerHash, scene_pack_id AS scenePackId, provider_generation AS providerGeneration, bound_model_id AS boundModelId, bound_at AS boundAt, optimization_mode AS optimizationMode FROM aml_channel_profiles WHERE channel_id=?`)
   return { upsert, get }
 }
 
 export function setHybridChannelProfile(input: Omit<HybridChannelProfile, 'channelId'> & { channelId: string, createdBy?: string }): HybridChannelProfile {
   const rt = getAmlRuntime()
   const now = new Date().toISOString()
-  repo(rt.db).upsert.run(input.channelId, input.profile, JSON.stringify(input.capability ?? {}), input.sceneId ?? null, input.sceneVersion ?? null, JSON.stringify(input.sceneContract ?? {}), JSON.stringify(input.objective ?? {}), input.controlPolicy ?? 'recommendation_only', input.createdBy ?? 'system', now, now)
+  repo(rt.db).upsert.run(input.channelId, input.profile, JSON.stringify(input.capability ?? {}), input.sceneId ?? null, input.sceneVersion ?? null, JSON.stringify(input.sceneContract ?? {}), JSON.stringify(input.objective ?? {}), input.controlPolicy ?? 'recommendation_only', input.providerId ?? null, input.providerVersion ?? null, input.providerHash ?? null, input.scenePackId ?? null, input.providerGeneration ?? null, input.boundModelId ?? null, input.boundAt ?? null, input.optimizationMode ?? null, input.createdBy ?? 'system', now, now)
   return input
 }
 
@@ -31,7 +45,9 @@ export function getChannelTwinProfile(channelId: string): HybridChannelProfile {
   try {
     const row = repo(getAmlRuntime().db).get.get(channelId) as Record<string, unknown> | undefined
     if (!row) return { channelId, profile: 'legacy', capability: {}, controlPolicy: 'recommendation_only' }
-    return { channelId, profile: String(row.profile) === 'hybrid_twin' ? 'hybrid_twin' : 'legacy', capability: JSON.parse(String(row.capabilityJson ?? '{}')), sceneId: row.sceneId ? String(row.sceneId) : undefined, sceneVersion: row.sceneVersion ? String(row.sceneVersion) : undefined, sceneContract: JSON.parse(String(row.sceneContractJson ?? '{}')), objective: JSON.parse(String(row.objectiveJson ?? '{}')), controlPolicy: (['recommendation_only', 'hitl_governed', 'bounded_auto'] as const).includes(row.controlPolicy as never) ? row.controlPolicy as HybridChannelProfile['controlPolicy'] : 'recommendation_only' }
+    const profile = (['legacy', 'hybrid_twin', 'aml_training', 'aml_optimization'] as const).includes(row.profile as never) ? row.profile as AmlChannelProfileKind : 'legacy'
+    const mode = row.optimizationMode === 'aml' || row.optimizationMode === 'exploration' ? (row.optimizationMode as OptimizationMode) : undefined
+    return { channelId, profile, capability: JSON.parse(String(row.capabilityJson ?? '{}')), sceneId: row.sceneId ? String(row.sceneId) : undefined, sceneVersion: row.sceneVersion ? String(row.sceneVersion) : undefined, sceneContract: JSON.parse(String(row.sceneContractJson ?? '{}')), objective: JSON.parse(String(row.objectiveJson ?? '{}')), controlPolicy: (['recommendation_only', 'hitl_governed', 'bounded_auto'] as const).includes(row.controlPolicy as never) ? row.controlPolicy as HybridChannelProfile['controlPolicy'] : 'recommendation_only', providerId: row.providerId ? String(row.providerId) : undefined, providerVersion: row.providerVersion ? String(row.providerVersion) : undefined, providerHash: row.providerHash ? String(row.providerHash) : undefined, scenePackId: row.scenePackId ? String(row.scenePackId) : undefined, providerGeneration: row.providerGeneration != null ? Number(row.providerGeneration) : undefined, boundModelId: row.boundModelId ? String(row.boundModelId) : undefined, boundAt: row.boundAt ? String(row.boundAt) : undefined, optimizationMode: mode }
   }
   catch {
     return { channelId, profile: 'legacy', capability: {}, controlPolicy: 'recommendation_only' }
@@ -41,3 +57,60 @@ export function getChannelTwinProfile(channelId: string): HybridChannelProfile {
 export function isHybridTwinChannel(channelId: string): boolean {
   return getChannelTwinProfile(channelId).profile === 'hybrid_twin'
 }
+
+export function isTrainingChannel(channelId: string): boolean {
+  return getChannelTwinProfile(channelId).profile === 'aml_training'
+}
+
+export function isOptimizationChannel(channelId: string): boolean {
+  return getChannelTwinProfile(channelId).profile === 'aml_optimization'
+}
+
+/**
+ * 孪生验证/寻优工具是否对该 Channel 放行:
+ * hybrid_twin(旧全功能) 恒可;aml_optimization 须显式 aml 模式且已绑定模型。
+ * 探索模式/未绑定 → 返回拒绝原因(工具层转「探索阶段」提示)。
+ */
+export function modelBackedToolPolicyFor(channelId: string): { allowed: boolean, reason?: string } {
+  const p = getChannelTwinProfile(channelId)
+  if (p.profile === 'hybrid_twin') return { allowed: true }
+  if (p.profile !== 'aml_optimization') return { allowed: false, reason: 'PROFILE_NOT_OPTIMIZATION' }
+  if (p.optimizationMode !== 'aml' || !p.boundModelId) return { allowed: false, reason: 'EXPLORATION_MODE_NO_MODEL' }
+  return { allowed: true }
+}
+
+/**
+ * 绑定模型校验(fail-closed):谱系(产线/产品/配方)与 Channel 场景一致 + Twin Gate 全过。
+ * 违反 → 409;返回模型行供调用方续用。
+ */
+export function assertModelBindableToChannel(channelId: string, modelId: string): { modelId: string, label: string, stage: string } {
+  const p = getChannelTwinProfile(channelId)
+  if (p.profile !== 'aml_optimization') throw new AppError(409, 'AML_BIND_NOT_OPTIMIZATION', '仅工艺优化 Channel(aml_optimization)可绑定 AML 模型。')
+  const rt = getAmlRuntime()
+  const model = rt.repo.model.get(modelId)
+  if (!model) throw new AppError(404, 'AML_MODEL_MISSING', `模型 ${modelId} 不存在。`)
+  if (model.stage !== 'production' && model.stage !== 'shadow') throw new AppError(409, 'AML_MODEL_STAGE', `模型 ${modelId} 处于 ${model.stage} 阶段,仅 production/shadow 可绑定(先在 AML 界面或训练 Channel 晋升)。`)
+  const dataset = rt.repo.dataset.get(model.datasetId)
+  if (!dataset) throw new AppError(409, 'AML_MODEL_DATASET_MISSING', `模型 ${modelId} 的数据集不存在,无法校验谱系。`)
+  const mismatch: string[] = []
+  if (p.sceneId && dataset.lineId && dataset.lineId !== sceneLineId(p)) mismatch.push(`产线 ${dataset.lineId} ≠ 场景产线`)
+  const metrics = (() => {
+    try {
+      return JSON.parse(model.metricsJson || '{}') as Record<string, unknown>
+    }
+    catch {
+      return {}
+    }
+  })()
+  const twin = metrics.twinEligibility as Record<string, unknown> | undefined
+  if (twin?.recommendationEligible !== true || twin?.uqPassed !== true || twin?.oodPassed !== true || twin?.physicsPassed !== true) {
+    throw new AppError(409, 'AML_MODEL_GATE_REQUIRED', `模型 ${modelId} 未通过场景级 Twin Gate(须先经 twin_gate_evaluate 全过),拒绝绑定。`)
+  }
+  if (mismatch.length > 0) throw new AppError(409, 'AML_MODEL_SCENE_MISMATCH', `模型谱系与 Channel 场景不一致:${mismatch.join(';')}(禁止跨配方投用)。`)
+  return { modelId: model.id, label: model.label || model.id, stage: model.stage }
+}
+
+function sceneLineId(p: HybridChannelProfile): string {
+  const contract = p.sceneContract as { lineId?: string } | undefined
+  return contract?.lineId ?? ''
+}

package/server/services/workshop/aml/twin/contracts.ts

@@ -25,6 +25,8 @@ export interface SceneContract {
   lineId: string
   productId?: string
   recipeId?: string
+  /** User-provided industrial scenario description; part of immutable scene provenance. */
+  scenarioPrompt?: string
   phases: string[]
   controls: SceneVariable[]
   states: SceneVariable[]
@@ -169,6 +171,7 @@ export const sceneContractSchema = z.object({
   lineId: z.string().min(1),
   productId: z.string().optional(),
   recipeId: z.string().optional(),
+  scenarioPrompt: z.string().max(20_000).optional(),
   phases: z.array(z.string().min(1)).min(1),
   controls: z.array(z.object({ id: z.string(), nodeId: z.string().optional(), role: z.literal('control'), physicalMeaning: z.string(), unit: z.string(), min: z.number().optional(), max: z.number().optional(), maxStep: z.number().positive().optional(), samplingPeriodMs: z.number().positive().optional(), phaseScope: z.array(z.string()).optional() })),
   states: z.array(z.any()),

package/server/services/workshop/aml/twin/declarative-provider.ts

@@ -0,0 +1,108 @@
+import { sha256, type PhysicsModelManifest, type SceneContract } from './contracts'
+import type { PhysicsInput, PhysicsModelProvider, PhysicsState, PhysicsStepResult, PhysicsTrajectory } from './physics-runtime'
+import { evaluatePhysicsExpression, parsePhysicsSpec, type PhysicsEquationSpec, type PhysicsSpec } from './physics-spec'
+
+export class DeclarativePhysicsProvider implements PhysicsModelProvider {
+  readonly spec: PhysicsSpec
+  readonly manifest: PhysicsModelManifest
+  private readonly stateEquations: PhysicsEquationSpec[]
+  private readonly observationEquations: PhysicsEquationSpec[]
+  private readonly guardEquations: PhysicsEquationSpec[]
+  private readonly parameters: Record<string, number>
+
+  constructor(input: PhysicsSpec) {
+    this.spec = parsePhysicsSpec(input)
+    this.stateEquations = this.spec.states
+    this.observationEquations = this.spec.observations
+    this.guardEquations = this.spec.guards ?? []
+    this.parameters = Object.fromEntries(this.spec.parameters.map(parameter => [parameter.id, parameter.value ?? parameter.defaultValue ?? 0]))
+    this.manifest = {
+      schemaVersion: 1,
+      createdAt: this.spec.provenance.createdAt ?? new Date().toISOString(),
+      createdBy: this.spec.provenance.createdBy,
+      physicsModelId: this.spec.modelId,
+      version: this.spec.version ?? '1.0.0',
+      sceneId: this.spec.sceneId,
+      backend: 'typescript',
+      stateVariables: this.spec.variables.filter(variable => variable.role === 'state').map(variable => variable.id),
+      controlVariables: this.spec.variables.filter(variable => variable.role === 'control').map(variable => variable.id),
+      disturbanceVariables: this.spec.variables.filter(variable => variable.role === 'disturbance').map(variable => variable.id),
+      parameters: Object.fromEntries(this.spec.parameters.map(parameter => [parameter.id, { value: parameter.value ?? parameter.defaultValue ?? 0, ...(parameter.min === undefined ? {} : { min: parameter.min }), ...(parameter.max === undefined ? {} : { max: parameter.max }), ...(parameter.unit ? { unit: parameter.unit } : {}) }])),
+      parameterPriors: Object.fromEntries(this.spec.parameters.map(parameter => [parameter.id, { min: parameter.min ?? parameter.value ?? parameter.defaultValue ?? 0, max: parameter.max ?? parameter.value ?? parameter.defaultValue ?? 0 }])),
+      sourceHash: sha256(this.spec),
+    }
+  }
+
+  initialize(snapshot: { stateEstimate: Record<string, number>, controlValues: Record<string, number> }): PhysicsState {
+    const state: PhysicsState = {}
+    for (const variable of this.spec.variables.filter(item => item.role === 'state')) state[variable.id] = snapshot.stateEstimate[variable.id] ?? snapshot.controlValues[variable.id] ?? variable.defaultValue ?? variable.min ?? 0
+    return state
+  }
+
+  step(input: PhysicsInput): PhysicsStepResult {
+    const dtSec = input.dtSec ?? this.spec.solver.dtSec
+    const values = { ...input.state, ...input.controls, ...(input.disturbances ?? {}) }
+    const context = { values, parameters: this.parameters, dtSec }
+    const nextState: PhysicsState = { ...input.state }
+    for (const equation of this.stateEquations) {
+      const base = equation.lhs.endsWith('_next') ? equation.lhs.slice(0, -5) : equation.lhs
+      const raw = this.safeEvaluate(equation, context)
+      nextState[base] = this.spec.solver.method === 'ode' ? (input.state[base] ?? 0) + dtSec * raw : raw
+    }
+    const outputValues = { ...values, ...nextState, ...Object.fromEntries(Object.entries(nextState).map(([key, value]) => [`${key}_next`, value])) }
+    const outputContext = { values: outputValues, parameters: this.parameters, dtSec }
+    const observations: Record<string, number> = {}
+    const guards: Record<string, number> = {}
+    for (const equation of this.observationEquations) observations[equation.lhs] = this.safeEvaluate(equation, outputContext)
+    for (const equation of this.guardEquations) guards[equation.lhs] = this.safeEvaluate(equation, outputContext)
+    return { state: nextState, observations, guards }
+  }
+
+  simulate(initial: PhysicsState, controls: Array<Record<string, number>>, disturbances: Record<string, number> = {}): PhysicsTrajectory {
+    let state = { ...initial }
+    const steps: PhysicsStepResult[] = []
+    const failures: string[] = []
+    for (const control of controls) {
+      const result = this.step({ state, controls: control, disturbances, dtSec: this.spec.solver.dtSec })
+      if ([...Object.values(result.state), ...Object.values(result.observations), ...Object.values(result.guards)].some(value => !Number.isFinite(value))) failures.push('PHYSICS_NON_FINITE')
+      for (const variable of this.spec.variables) {
+        const value = result.state[variable.id] ?? result.observations[variable.id] ?? result.guards[variable.id]
+        if (value !== undefined && ((variable.min !== undefined && value < variable.min) || (variable.max !== undefined && value > variable.max))) failures.push(`PHYSICS_BOUND:${variable.id}`)
+      }
+      state = result.state
+      steps.push(result)
+    }
+    return { steps, failures: [...new Set(failures)] }
+  }
+
+  evaluateConstraints(scene: SceneContract, trajectory: PhysicsTrajectory): Array<{ id: string, passed: boolean, detail: string, firstViolationStep?: number }> {
+    const constraints = scene.constraints.length > 0 ? scene.constraints : this.spec.constraints
+    return constraints.map((constraint) => {
+      let seen = false
+      for (let index = 0; index < trajectory.steps.length; index++) {
+        const step = trajectory.steps[index]
+        if (!step) continue
+        const value = step.observations[constraint.id] ?? step.guards[constraint.id] ?? step.state[constraint.id]
+        if (value === undefined) continue
+        seen = true
+        if (constraint.kind === 'hard_range' && ((constraint.min !== undefined && value < constraint.min) || (constraint.max !== undefined && value > constraint.max))) return { id: constraint.id, passed: false, detail: `${constraint.id}=${value} 越界`, firstViolationStep: index }
+      }
+      if (!seen) return { id: constraint.id, passed: false, detail: `约束 ${constraint.id} 无法映射到轨迹，失败关闭` }
+      return { id: constraint.id, passed: true, detail: '全轨迹通过' }
+    })
+  }
+
+  private safeEvaluate(equation: PhysicsEquationSpec, context: { values: Record<string, number>, parameters: Record<string, number>, dtSec: number }): number {
+    try {
+      return evaluatePhysicsExpression(equation.rhs, context)
+    }
+    catch { return Number.NaN }
+  }
+}
+
+export class GenericDeclarativeProvider extends DeclarativePhysicsProvider {}
+export function compileDeclarativeProvider(spec: PhysicsSpec): PhysicsModelProvider {
+  return new DeclarativePhysicsProvider(spec)
+}
+export const compilePhysicsSpec = compileDeclarativeProvider
+export const createDeclarativePhysicsProvider = compileDeclarativeProvider

package/server/services/workshop/aml/twin/feature-flags.ts

@@ -0,0 +1,63 @@
+export interface AmlTwinFeatureFlags {
+  channelEnabled: boolean
+  trainingEnabled: boolean
+  trialEnabled: boolean
+  mpcEnabled: boolean
+  governedWriteEnabled: boolean
+  boundedAutoEnabled: boolean
+}
+
+function flag(name: string, fallback: boolean): boolean {
+  const raw = process.env[name]
+  if (raw == null || raw.trim() === '') return fallback
+  return ['1', 'true', 'yes', 'on', 'enabled'].includes(raw.trim().toLowerCase())
+}
+
+/**
+ * AML Twin 的服务端 feature flags。在线写入默认关闭；推荐/试验路径默认保持可用，
+ * 这样可以继续跑 VirtualTrial 和 recommendation-only 验收而不会误触 PLC。
+ */
+export function amlTwinFeatureFlags(): AmlTwinFeatureFlags {
+  return {
+    channelEnabled: flag('AML_TWIN_CHANNEL_ENABLED', true),
+    trainingEnabled: flag('AML_TWIN_TRAINING_ENABLED', true),
+    trialEnabled: flag('AML_TWIN_TRIAL_ENABLED', true),
+    mpcEnabled: flag('AML_TWIN_MPC_ENABLED', true),
+    governedWriteEnabled: flag('AML_TWIN_GOVERNED_WRITE_ENABLED', false),
+    boundedAutoEnabled: flag('AML_TWIN_BOUNDED_AUTO_ENABLED', false),
+  }
+}
+
+export function twinCapabilityEnabled(capability: keyof AmlTwinFeatureFlags): boolean {
+  return amlTwinFeatureFlags()[capability]
+}
+
+export function assertTwinCapability(capability: 'channelEnabled' | 'trainingEnabled' | 'trialEnabled' | 'mpcEnabled'): void {
+  if (!amlTwinFeatureFlags()[capability]) throw new Error(`AML_TWIN_${capability.replace('Enabled', '').toUpperCase()}_DISABLED`)
+}
+
+export function twinWriteGuard(channelId: string, profile: { profile: string, controlPolicy?: string, capability?: Record<string, unknown> }): { allowed: true } | { allowed: false, code: string, message: string } {
+  if (profile.profile !== 'hybrid_twin') return { allowed: true }
+  const flags = amlTwinFeatureFlags()
+  if (!flags.channelEnabled) return { allowed: false, code: 'AML_TWIN_CHANNEL_DISABLED', message: 'AML Twin Channel 功能开关已关闭，拒绝在线写入。' }
+  if (profile.controlPolicy === 'recommendation_only' || !profile.controlPolicy) {
+    // 未通过 Twin Gate 时允许进入 exploration，但只允许下层 DCW 单步/60s
+    // 硬联锁；没有明确 capability 的旧频道仍保持 recommendation-only 禁写。
+    const cap = profile.capability ?? {}
+    const phase = String(cap.phase ?? cap.twinPhase ?? '').toLowerCase()
+    const safeExploration = cap.explorationWrite !== false && (
+      cap.explorationWrite === true
+      || cap.safeSmallStep === true
+      || ['discovery', 'exploration', 'calibration'].includes(phase)
+      // 兼容在本安全卡控上线前创建的 Hybrid Channel:它们没有 phase，
+      // 但只要不是显式关闭探索，就走服务端 stepLimit/60s 硬闸门。
+      || cap.mpcRecommendation === true
+      || Object.keys(cap).length === 0
+    )
+    if (safeExploration) return { allowed: true }
+    return { allowed: false, code: 'AML_TWIN_RECOMMENDATION_ONLY', message: `Hybrid Twin Channel ${channelId} 当前是 recommendation_only；直接 DCW/参数写入被平台拒绝，必须先进入明确标记的 exploration/safe_small_step 阶段并通过单步/60s 安全联锁。` }
+  }
+  if (profile.controlPolicy === 'hitl_governed' && !flags.governedWriteEnabled) return { allowed: false, code: 'AML_TWIN_GOVERNED_WRITE_DISABLED', message: 'hitl_governed 写入开关默认关闭；当前只允许 recommendation-only，未签发 WriteGrant。' }
+  if (profile.controlPolicy === 'bounded_auto' && !flags.boundedAutoEnabled) return { allowed: false, code: 'AML_TWIN_BOUNDED_AUTO_DISABLED', message: 'bounded_auto 写入开关默认关闭；当前只允许 recommendation-only，未签发 WriteGrant。' }
+  return { allowed: false, code: 'AML_TWIN_WRITE_GRANT_REQUIRED', message: 'Hybrid Twin 在线写入必须由平台签发经校验的 WriteGrant；Agent 不能直接伪造或绕过门禁。' }
+}

package/server/services/workshop/aml/twin/hybrid-provider.ts

@@ -0,0 +1,86 @@
+import { sha256, type SceneContract, type PhysicsModelManifest } from './contracts'
+import type { PhysicsInput, PhysicsModelProvider, PhysicsState, PhysicsStepResult, PhysicsTrajectory } from './physics-runtime'
+
+export type ResidualPrediction = Record<string, number>
+export type ResidualPredictor = (input: { physics: PhysicsStepResult, state: PhysicsState, controls: Record<string, number>, disturbances: Record<string, number>, dtSec: number }) => ResidualPrediction
+
+export interface HybridProviderOptions {
+  residualModelId?: string
+  residualModelVersion?: string
+  residualScale?: number
+  /** 默认只修正观测，不让未经验证的数据残差改变物理状态。 */
+  applyToState?: boolean
+}
+
+export function boundResidual(value: number, scale: number): number {
+  if (!Number.isFinite(value)) return 0
+  const limit = Math.max(0, Number.isFinite(scale) ? scale : 0)
+  return Math.min(limit, Math.max(-limit, value))
+}
+
+/**
+ * 物理主干 + 有界残差 Provider。
+ *
+ * 物理 Provider 始终先执行；残差模型只能在边界内修正观测（可选地修正状态），
+ * 且不拥有 DAQ/DCW 权限。VirtualTrial/MPC 只接收此 Provider 的 rollout。
+ */
+export class HybridPhysicsProvider implements PhysicsModelProvider {
+  readonly manifest: PhysicsModelManifest
+  private readonly base: PhysicsModelProvider
+  private readonly predictor: ResidualPredictor
+  private readonly residualScale: number
+  private readonly applyToState: boolean
+
+  constructor(base: PhysicsModelProvider, predictor: ResidualPredictor, options: HybridProviderOptions = {}) {
+    this.base = base
+    this.predictor = predictor
+    this.residualScale = Math.max(0, options.residualScale ?? 0.25)
+    this.applyToState = options.applyToState === true
+    this.manifest = {
+      ...base.manifest,
+      physicsModelId: `hybrid-${base.manifest.physicsModelId}`,
+      version: options.residualModelVersion ?? `${base.manifest.version}+residual`,
+      backend: 'pytorch',
+      sourceHash: sha256({ base: base.manifest, residualModelId: options.residualModelId ?? '', residualModelVersion: options.residualModelVersion ?? '', residualScale: this.residualScale, applyToState: this.applyToState }),
+    }
+  }
+
+  initialize(snapshot: { stateEstimate: Record<string, number>, controlValues: Record<string, number> }): PhysicsState {
+    return this.base.initialize(snapshot)
+  }
+
+  step(input: PhysicsInput): PhysicsStepResult {
+    const dtSec = input.dtSec ?? 1
+    const disturbances = input.disturbances ?? {}
+    const physics = this.base.step(input)
+    const rawResidual = this.predictor({ physics, state: input.state, controls: input.controls, disturbances, dtSec })
+    const residual = Object.fromEntries(Object.entries(rawResidual ?? {}).map(([key, value]) => [key, boundResidual(Number(value), this.residualScale)]))
+    const observations = { ...physics.observations }
+    for (const [key, delta] of Object.entries(residual)) observations[key] = (observations[key] ?? 0) + delta
+    const state = this.applyToState
+      ? Object.fromEntries(Object.entries(physics.state).map(([key, value]) => [key, Number(value) + (residual[key] ?? 0)]))
+      : physics.state
+    return { state, observations, guards: physics.guards }
+  }
+
+  simulate(initial: PhysicsState, controls: Array<Record<string, number>>, disturbances: Record<string, number> = {}): PhysicsTrajectory {
+    let state = { ...initial }
+    const steps: PhysicsStepResult[] = []
+    const failures: string[] = []
+    for (const control of controls) {
+      const result = this.step({ state, controls: control, disturbances, dtSec: 1 })
+      if ([...Object.values(result.state), ...Object.values(result.observations), ...Object.values(result.guards)].some(value => !Number.isFinite(value))) failures.push('HYBRID_NON_FINITE')
+      steps.push(result)
+      state = result.state
+    }
+    return { steps, failures: [...new Set(failures)] }
+  }
+
+  evaluateConstraints(scene: SceneContract, trajectory: PhysicsTrajectory): Array<{ id: string, passed: boolean, detail: string, firstViolationStep?: number }> {
+    return this.base.evaluateConstraints(scene, trajectory)
+  }
+}
+
+export function createHybridPhysicsProvider(base: PhysicsModelProvider, predictor: ResidualPredictor, options?: HybridProviderOptions): HybridPhysicsProvider {
+  return new HybridPhysicsProvider(base, predictor, options)
+}