agentworkshop 0.7.70 → 0.7.71

package/server/services/workshop/optimization/python/problems.py

@@ -0,0 +1,347 @@
+"""
+ProblemIR 编译/求解的数值实现(与 TS problem-builder 的离散语义逐项对齐)。
+
+- 线性 MPC:y_t = o_t + S_t·u(对 Δu 的稠密二次型),交给 OSQP;
+- 稳态响应面:经济代价 + CV 跟踪,SciPy SLSQP 有界约束优化。
+"""
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+# 求解器依赖在模块加载时导入(不在求解线程内做 lazy import:3.12 下线程内 import
+# 与主线程 stdin 阻塞读同时存在时会卡住导入锁)。
+import osqp  # type: ignore
+import scipy.sparse as sp  # type: ignore
+from scipy.optimize import minimize  # type: ignore
+
+
+def _as_matrix(flat: list[float], rows: int, cols: int) -> np.ndarray:
+    return np.asarray(flat, dtype=float).reshape((rows, cols))
+
+
+class LinearMpcProblem:
+    def __init__(self, ir: dict[str, Any]):
+        problem = ir["problem"]
+        dyn = problem["dynamics"]
+        self.state_dim = int(dyn["stateDim"])
+        self.mv_order = list(problem["mvOrder"])
+        self.cv_order = list(problem["cvOrder"])
+        self.mv_count = len(self.mv_order)
+        self.cv_count = len(self.cv_order)
+        self.horizon = int(ir["horizon"])
+        self.A = _as_matrix(dyn["A"], self.state_dim, self.state_dim)
+        self.B = _as_matrix(dyn["B"], self.state_dim, self.mv_count)
+        self.C = _as_matrix(dyn["C"], self.cv_count, self.state_dim)
+        self.D = _as_matrix(dyn["D"], self.cv_count, self.mv_count)
+        self.x0 = np.asarray(dyn["x0"], dtype=float)
+        self.bias = np.asarray(dyn.get("bias") or [0.0] * self.state_dim, dtype=float)
+        self.u_prev = np.asarray(problem["uPrev"], dtype=float)
+        self.cv_setpoints = np.asarray(problem["cvSetpoints"], dtype=float)
+        weights = ir["weights"]
+        self.q = np.asarray([float(weights["cv"].get(cv, 1.0)) for cv in self.cv_order], dtype=float)
+        self.r = np.asarray([float(weights["du"].get(mv, 0.0)) for mv in self.mv_order], dtype=float)
+        self.terminal = float(weights.get("terminal") or 0.0)
+        self.mv_bounds = problem["mvBounds"]
+        raw_cv_bounds = problem.get("cvBounds")
+        self.cv_bounds = [{} for _ in self.cv_order] if raw_cv_bounds is None else list(raw_cv_bounds)
+        if len(self.mv_bounds) != self.mv_count:
+            raise ValueError(f"mvBounds 维度 {len(self.mv_bounds)} != MV 数 {self.mv_count}")
+        if len(self.cv_bounds) != self.cv_count:
+            raise ValueError(f"cvBounds 维度 {len(self.cv_bounds)} != CV 数 {self.cv_count}")
+        self.sensitivity: list[np.ndarray] = []
+        self.offset: list[np.ndarray] = []
+        self._build_sensitivity()
+
+    def _build_sensitivity(self) -> None:
+        """y_t = offset_t + S_t·u,t=1..H(u 为 H 步 MV 序列)。"""
+        hm = self.horizon * self.mv_count
+        x_affine_A = np.zeros((self.state_dim, self.state_dim))
+        x_affine_b = np.zeros(self.state_dim)
+        # x_0 = x0(与 u 无关);逐步展开:x_t = A^t x0 + Σ_{s<t} A^{t-1-s} B u_s
+        powers = [np.eye(self.state_dim)]
+        for _ in range(self.horizon):
+            powers.append(powers[-1] @ self.A)
+        for t in range(1, self.horizon + 1):
+            bias_effect = np.zeros(self.state_dim)
+            for k in range(t):
+                bias_effect = bias_effect + powers[k] @ self.bias
+            off = powers[t] @ self.x0 + bias_effect
+            sens = np.zeros((self.cv_count, hm))
+            for s in range(t):
+                block = powers[t - 1 - s] @ self.B  # state effect of u_s
+                yblock = self.C @ block  # cv effect
+                for m in range(self.mv_count):
+                    sens[:, s * self.mv_count + m] += yblock[:, m]
+            # D 直通:y_t 含 D·u_{t-1}(u 序列第 t-1 个)
+            sens[:, (t - 1) * self.mv_count:(t * self.mv_count)] += self.D
+            self.sensitivity.append(sens)
+            self.offset.append(self.C @ off)
+        del x_affine_A, x_affine_b
+
+    def qp(self) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        hm = self.horizon * self.mv_count
+        P = np.zeros((hm, hm))
+        q = np.zeros(hm)
+        for t, (sens, off) in enumerate(zip(self.sensitivity, self.offset)):
+            w = self.q if t < self.horizon - 1 else self.q * (1.0 + self.terminal)
+            P += 2.0 * (sens.T @ (w[:, None] * sens))
+            q += 2.0 * (sens.T @ (w * (off - self.cv_setpoints)))
+        # Δu 惩罚:每个 MV 一个二阶差分矩阵 D,u_{-1}=uPrev。
+        # cost = Σ_m r_m · ||D u_m + c_m||²;P += 2r·DᵀD,q += 2r·Dᵀc。
+        for m in range(self.mv_count):
+            if self.r[m] <= 0:
+                continue
+            D = np.zeros((self.horizon, self.horizon))
+            c = np.zeros(self.horizon)
+            for t in range(self.horizon):
+                D[t, t] = 1.0
+                if t == 0:
+                    c[t] = -float(self.u_prev[m])
+                else:
+                    D[t, t - 1] = -1.0
+            idx = [t * self.mv_count + m for t in range(self.horizon)]
+            P[np.ix_(idx, idx)] += 2.0 * self.r[m] * (D.T @ D)
+            q[idx] += 2.0 * self.r[m] * (D.T @ c)
+        # 对称化
+        P = 0.5 * (P + P.T)
+        # 约束:l <= Az <= u(变量边界 + 速率)
+        rows = []
+        lows = []
+        highs = []
+        for t in range(self.horizon):
+            for m in range(self.mv_count):
+                idx = t * self.mv_count + m
+                row = np.zeros(hm)
+                row[idx] = 1.0
+                rows.append(row)
+                bounds = self.mv_bounds[m]
+                lows.append(float(bounds.get("min", -np.inf)))
+                highs.append(float(bounds.get("max", np.inf)))
+                max_step = bounds.get("maxStep")
+                if max_step is not None:
+                    row2 = np.zeros(hm)
+                    row2[idx] = 1.0
+                    prev = self.u_prev[m] if t == 0 else None
+                    if prev is not None:
+                        lows.append(-float(max_step) + prev)
+                        highs.append(float(max_step) + prev)
+                    else:
+                        row2[(t - 1) * self.mv_count + m] = -1.0
+                        lows.append(-float(max_step))
+                        highs.append(float(max_step))
+                    rows.append(row2)
+        # CV 有效域(软约束之外硬边界;首版按硬约束处理)
+        for t in range(self.horizon):
+            for j in range(self.cv_count):
+                bounds = self.cv_bounds[j] or {}
+                lo = bounds.get("min")
+                hi = bounds.get("max")
+                if lo is None and hi is None:
+                    continue
+                row = np.zeros(hm)
+                sens = self.sensitivity[t][j]
+                row += sens
+                rows.append(row)
+                lows.append(float(lo) - float(self.offset[t][j]) if lo is not None else -np.inf)
+                highs.append(float(hi) - float(self.offset[t][j]) if hi is not None else np.inf)
+        A = np.vstack(rows) if rows else np.zeros((0, hm))
+        return P, q, A, np.asarray(lows), np.asarray(highs)
+
+
+def _c_stdout_silenced():
+    """OSQP(C 库)会绕过 Python 的 sys.stdout 直接写 fd 1;协议要求 stdout 仅 JSONL。"""
+    import os
+    from contextlib import contextmanager
+
+    @contextmanager
+    def _ctx():
+        saved = os.dup(1)
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        try:
+            os.dup2(devnull, 1)
+            yield
+        finally:
+            os.dup2(saved, 1)
+            os.close(devnull)
+            os.close(saved)
+    return _ctx()
+
+
+def _assert_finite_ir(ir: dict[str, Any]) -> None:
+    """NaN/Inf 输入必须在进入求解器前拒绝(SLSQP 会把 NaN 误报成 inequality infeasible)。"""
+    if not check_finite(ir):
+        raise ValueError("ProblemIR 含 NaN/Inf;拒绝求解")
+
+
+def solve_linear_mpc(ir: dict[str, Any], cancel_check, max_chunk_iters: int = 400) -> dict[str, Any]:
+    if cancel_check():
+        return {"status": "cancelled", "message": "cancelled before solve"}
+    _assert_finite_ir(ir)
+    prob = LinearMpcProblem(ir)
+    P, q, A, low, high = prob.qp()
+    solver = osqp.OSQP()
+    solver.setup(
+        P=sp.csc_matrix(P), q=q, A=sp.csc_matrix(A), l=low, u=high,
+        verbose=False, polish=False, max_iter=max_chunk_iters,
+        eps_abs=1e-8, eps_rel=1e-8,
+    )
+    with _c_stdout_silenced():
+        result = solver.solve()
+        rounds = 0
+        while int(result.info.status_val) == osqp.constant("OSQP_MAX_ITER_REACHED") and rounds < 20:
+            if cancel_check():
+                return {"status": "cancelled", "message": "cancelled during iterations"}
+            rounds += 1
+            result = solver.solve()
+    status_val = int(result.info.status_val)
+    status_text = str(result.info.status)
+    solved = osqp.constant("OSQP_SOLVED")
+    solved_inaccurate = osqp.constant("OSQP_SOLVED_INACCURATE")
+    if result.x is None or status_val not in (solved, solved_inaccurate):
+        mapped = {
+            osqp.constant("OSQP_PRIMAL_INFEASIBLE"): 'infeasible',
+            osqp.constant("OSQP_PRIMAL_INFEASIBLE_INACCURATE"): 'infeasible',
+            osqp.constant("OSQP_DUAL_INFEASIBLE"): 'unbounded',
+            osqp.constant("OSQP_DUAL_INFEASIBLE_INACCURATE"): 'unbounded',
+            osqp.constant("OSQP_MAX_ITER_REACHED"): 'numerical_error',
+            osqp.constant("OSQP_TIME_LIMIT_REACHED"): 'timeout',
+            osqp.constant("OSQP_NON_CVX"): 'numerical_error',
+            osqp.constant("OSQP_SIGINT"): 'cancelled',
+        }.get(status_val, 'numerical_error')
+        return {
+            "status": mapped,
+            "message": status_text,
+            "iterations": int(getattr(result.info, "iter", 0)),
+        }
+    z = np.asarray(result.x, dtype=float).reshape((prob.horizon, prob.mv_count))
+    predicted = []
+    for sens, off in zip(prob.sensitivity, prob.offset):
+        predicted.append(off + sens @ z.reshape(-1))
+    # 平台同口径代价:全时域跟踪 + 终端 + Δu(不用 QP 的 0.5z'Pz+q'z,
+    # 那里缺常数项;A4 要求 Solver 与 TS 独立重算逐项一致)
+    cost = 0.0
+    for t, row in enumerate(predicted):
+        w = prob.q if t < prob.horizon - 1 else prob.q * (1.0 + prob.terminal)
+        cost += float(np.sum(w * (row - prob.cv_setpoints) ** 2))
+    for t in range(prob.horizon):
+        prev = prob.u_prev if t == 0 else z[t - 1]
+        cost += float(np.sum(prob.r * (z[t] - prev) ** 2))
+    return {
+        "status": "optimal" if status_val == solved else "feasible",
+        "controls": z.tolist(),
+        "predicted": [row.tolist() for row in predicted],
+        "cost": cost,
+        "iterations": int(getattr(result.info, "iter", 0)),
+        "backend": "osqp",
+        "solverVersion": getattr(osqp, "__version__", "unknown"),
+    }
+
+
+def solve_steady_response(ir: dict[str, Any], cancel_check) -> dict[str, Any]:
+    _assert_finite_ir(ir)
+    problem = ir["problem"]
+    mv_order = list(problem["mvOrder"])
+    cv_order = list(problem["cvOrder"])
+    feature_order = list(problem["featureOrder"])
+    coefficients = problem["coefficients"]
+    targets = np.asarray(problem["cvTargets"], dtype=float)
+    weights = ir["weights"]
+    economic = weights.get("economic") or {}
+    cv_weights = weights.get("cv") or {}
+    mv_bounds = problem["mvBounds"]
+    raw_cv_bounds = problem.get("cvBounds")
+    cv_bounds = [{} for _ in cv_order] if raw_cv_bounds is None else list(raw_cv_bounds)
+    if len(mv_bounds) != len(mv_order):
+        raise ValueError(f"mvBounds 维度 {len(mv_bounds)} != MV 数 {len(mv_order)}")
+    if len(cv_bounds) != len(cv_order):
+        raise ValueError(f"cvBounds 维度 {len(cv_bounds)} != CV 数 {len(cv_order)}")
+    x0 = np.asarray(problem["uPrev"], dtype=float)
+    lo = np.asarray([float(b.get("min", -1e9)) for b in mv_bounds])
+    hi = np.asarray([float(b.get("max", 1e9)) for b in mv_bounds])
+    for m, bounds in enumerate(mv_bounds):
+        if bounds.get("maxStep") is not None:
+            step = float(bounds["maxStep"])
+            lo[m] = max(lo[m], float(x0[m]) - step)
+            hi[m] = min(hi[m], float(x0[m]) + step)
+    if np.any(lo > hi):
+        return {"status": "infeasible", "message": "MV bounds and maxStep have no feasible intersection"}
+    x0 = np.clip(x0, lo, hi)
+
+    def features(u: np.ndarray) -> np.ndarray:
+        by_name = {name: float(u[i]) for i, name in enumerate(mv_order)}
+        out = []
+        for name in feature_order:
+            if name == "bias":
+                out.append(1.0)
+            elif name.endswith("^2"):
+                out.append(by_name.get(name[:-2], 0.0) ** 2)
+            elif "*" in name:
+                a, b = name.split("*", 1)
+                out.append(by_name.get(a, 0.0) * by_name.get(b, 0.0))
+            else:
+                out.append(by_name.get(name, 0.0))
+        return np.asarray(out)
+
+    def objective(u: np.ndarray) -> float:
+        cost = 0.0
+        for i, name in enumerate(mv_order):
+            cost += float(economic.get(name, 0.0)) * float(u[i])
+        feat = features(u)
+        for j, cv in enumerate(cv_order):
+            coef = np.asarray(coefficients[cv], dtype=float)
+            y = float(coef @ feat)
+            cost += float(cv_weights.get(cv, 0.0)) * (y - float(targets[j])) ** 2
+        return cost
+
+    def constraints():
+        cons = []
+        for j, cv in enumerate(cv_order):
+            bounds = cv_bounds[j] or {}
+            if bounds.get("min") is None and bounds.get("max") is None:
+                continue
+            coef = np.asarray(coefficients[cv], dtype=float)
+            def make(j=j, coef=coef, bounds=bounds):
+                def f(u: np.ndarray) -> float:
+                    return float(coef @ features(u))
+                return f
+            f = make()
+            if bounds.get("min") is not None:
+                cons.append({"type": "ineq", "fun": lambda u, f=f, lo=float(bounds["min"]): f(u) - lo})
+            if bounds.get("max") is not None:
+                cons.append({"type": "ineq", "fun": lambda u, f=f, hi=float(bounds["max"]): hi - f(u)})
+        return cons
+
+    if cancel_check():
+        return {"status": "cancelled", "message": "cancelled before solve"}
+    result = minimize(
+        objective, x0, method="SLSQP", bounds=list(zip(lo, hi)), constraints=constraints(),
+        options={"maxiter": 500, "ftol": 1e-10},
+    )
+    if not result.success:
+        return {"status": "infeasible", "message": str(result.message), "iterations": int(result.nit)}
+    controls = np.asarray(result.x, dtype=float)
+    feat = features(controls)
+    predicted = [float(np.asarray(coefficients[cv], dtype=float) @ feat) for cv in cv_order]
+    return {
+        "status": "optimal",
+        "controls": [controls.tolist()],
+        "predicted": [predicted],
+        "cost": float(result.fun),
+        "iterations": int(result.nit),
+        "backend": "scipy",
+        "solverVersion": "scipy",
+    }
+
+
+def check_finite(payload: Any) -> bool:
+    def walk(value: Any) -> bool:
+        if isinstance(value, float):
+            return math.isfinite(value)
+        if isinstance(value, list):
+            return all(walk(v) for v in value)
+        if isinstance(value, dict):
+            return all(walk(v) for v in value.values())
+        return True
+    return walk(payload)

package/server/services/workshop/optimization/python/worker.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+"""
+Optimizer Solver Worker(长驻子进程,NDJSON over stdin/stdout)。
+
+约束(plan B.9.3):
+  - stdout **只允许协议帧**;日志一律 stderr;
+  - 每进程同时只跑 1 个 solve;请求级 deadlineMs 由 TS 侧硬超时兜底;
+  - op: solve{cancel_check} / cancel / ping;
+  - 协作取消:主线程读 stdin 置位 Event;求解线程在迭代分段间检查;
+    不响应协作取消的长计算由 TS 直接终止本进程(单任务独占进程,安全兜底)。
+"""
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import traceback
+from typing import Any
+
+from problems import check_finite, solve_linear_mpc, solve_steady_response
+
+PROTOCOL_VERSION = 1
+
+_event = threading.Event()
+_cancel = threading.Event()
+_busy = threading.Event()
+_active_req: dict[str, Any] = {"reqId": None}
+
+
+def emit(frame: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(frame, ensure_ascii=False, separators=(",", ":")) + "\n")
+    sys.stdout.flush()
+
+
+def log(message: str) -> None:
+    sys.stderr.write(message + "\n")
+    sys.stderr.flush()
+
+
+def run_solve(req: dict[str, Any]) -> None:
+    req_id = str(req.get("reqId", ""))
+    _active_req["reqId"] = req_id
+    _cancel.clear()
+    payload = req.get("payload") or {}
+    ir = payload.get("problemIr")
+    try:
+        if not isinstance(ir, dict):
+            raise ValueError("payload.problemIr 必须是对象")
+        template = (ir.get("problem") or {}).get("template")
+        if template == "linear_mpc_quadratic@1":
+            result = solve_linear_mpc(ir, _cancel.is_set)
+        elif template == "steady_response@1":
+            result = solve_steady_response(ir, _cancel.is_set)
+        else:
+            result = {"status": "unsupported", "message": f"unsupported template: {template}"}
+        if not check_finite(result):
+            result = {"status": "numerical_error", "message": "solver produced NaN/Inf"}
+        emit({
+            "protocolVersion": PROTOCOL_VERSION,
+            "reqId": req_id,
+            "ok": True,
+            "result": result,
+            "diag": {"backend": result.get("backend"), "iterations": result.get("iterations")},
+        })
+    except Exception as exc:  # noqa: BLE001 - 协议层必须把任何异常变成 error 帧
+        log(traceback.format_exc())
+        emit({
+            "protocolVersion": PROTOCOL_VERSION,
+            "reqId": req_id,
+            "ok": False,
+            "error": {"code": "SOLVER_ERROR", "message": str(exc)},
+        })
+    finally:
+        _busy.clear()
+        _active_req["reqId"] = None
+
+
+def handle(req: dict[str, Any]) -> None:
+    op = req.get("op")
+    req_id = str(req.get("reqId", ""))
+    if req.get("protocolVersion") != PROTOCOL_VERSION:
+        emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": False, "error": {"code": "PROTOCOL_MISMATCH", "message": "protocolVersion must be 1"}})
+        return
+    if op == "ping":
+        emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": True, "result": {"pong": True, "busy": _busy.is_set()}})
+        return
+    if op == "cancel":
+        target = (req.get("payload") or {}).get("reqId") or req_id
+        if _active_req.get("reqId") == target:
+            _cancel.set()
+        emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": True, "result": {"cancelled": _cancel.is_set(), "target": target}})
+        return
+    if op == "solve":
+        if _busy.is_set():
+            emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": False, "error": {"code": "SOLVER_BUSY", "message": "worker 正在执行另一个 solve"}})
+            return
+        _busy.set()
+        thread = threading.Thread(target=run_solve, args=(req,), daemon=True)
+        thread.start()
+        return
+    emit({"protocolVersion": PROTOCOL_VERSION, "reqId": req_id, "ok": False, "error": {"code": "UNKNOWN_OP", "message": f"unknown op: {op}"}})
+
+
+def main() -> None:
+    emit({"protocolVersion": PROTOCOL_VERSION, "type": "ready", "diag": {"pid": __import__("os").getpid(), "python": sys.version.split()[0]}})
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except Exception:
+            emit({"protocolVersion": PROTOCOL_VERSION, "reqId": "", "ok": False, "error": {"code": "BAD_JSON", "message": "invalid JSON frame"}})
+            continue
+        handle(req)
+
+
+if __name__ == "__main__":
+    main()

package/server/services/workshop/optimization/recommendation.service.ts

@@ -0,0 +1,100 @@
+/**
+ * 建议生命周期(G3.7 / C10):
+ *  - 不可变、带 valid_until;
+ *  - 缺 UQ/OOD 证据 → unverified,UI/回执必须原样显示;
+ *  - 工况/配方/权限/revision 变化 → expired(不删除,保留审计)。
+ */
+import type { Recommendation, SolveCandidate } from './contracts'
+import { recommendationLabel } from './contracts'
+import { getRunRepo } from './run.repo'
+import { coverageThreshold } from './uq-evidence'
+
+export const RECOMMENDATION_TTL_MS = 15 * 60_000
+
+/** 建议 UQ 证据快照 = 工件 uq + artifactHash 锚 + 本次上下文 inputDistance(D2/D4/D5 单源) */
+export interface UqEvidence {
+  method?: 'split_conformal' | 'empirical_max'
+  qhatPerCv?: number[]
+  /** test 段实测 min_j coverage(旧字段 coverage 兼容读取) */
+  coverageTest?: number
+  coverage?: number
+  alpha?: number
+  horizon?: number
+  nValBlocks?: number
+  nValRuns?: number
+  nTestBlocks?: number
+  nTestRuns?: number
+  nUniqueTestSteps?: number
+  safetyFactor?: number
+  calibratedAt?: string
+  artifactHash?: string
+  calibrationFresh?: boolean
+  inputDistance?: number | null
+  evidenceVersion?: string
+}
+
+const OOD_DISTANCE_LIMIT = 3
+
+/** 只有显式携带完整校准证据才算 verified;缺省/不完整一律 unverified(不伪造)。 */
+export function classifyRecommendation(input: {
+  evidenceSource: 'simulation' | 'real' | 'unassessed'
+  uqEvidence: UqEvidence | null
+  candidateFeasible: boolean
+}): { status: 'verified' | 'unverified', reason: string } {
+  if (!input.candidateFeasible) return { status: 'unverified', reason: '候选未通过独立约束校验' }
+  if (input.evidenceSource !== 'simulation' && input.evidenceSource !== 'real') return { status: 'unverified', reason: '证据来源尚未评估' }
+  const uq = input.uqEvidence
+  if (!uq) return { status: 'unverified', reason: '缺工件 UQ 证据(旧工件/样本不足未发证)' }
+  const coverage = uq.coverageTest ?? uq.coverage
+  if (coverage == null || !Number.isFinite(coverage) || coverage < 0 || coverage > 1) return { status: 'unverified', reason: 'UQ coverage 必须是 [0,1] 范围内的有限数值' }
+  // D3 门限:0.8 硬底 + 分块修正;empirical_max 必须 1.0
+  const threshold = coverageThreshold({ method: uq.method ?? 'split_conformal', nTestRuns: uq.nTestRuns ?? 1 })
+  if (coverage < threshold) return { status: 'unverified', reason: `UQ coverage 不足(${coverage} < ${threshold.toFixed(3)},method=${uq.method ?? 'split_conformal'})` }
+  if (uq.calibrationFresh !== true) return { status: 'unverified', reason: 'UQ 校准已过期或未评估' }
+  if (uq.inputDistance == null) return { status: 'unverified', reason: 'inputDistance 未评估(norm 缺失/列序不符);不得按 0 乐观处理' }
+  if (!Number.isFinite(uq.inputDistance) || uq.inputDistance < 0) return { status: 'unverified', reason: 'inputDistance 必须是非负有限数值' }
+  if (uq.inputDistance > OOD_DISTANCE_LIMIT) return { status: 'unverified', reason: `当前操作点偏离训练分布(OOD):inputDistance=${uq.inputDistance.toFixed(2)} > ${OOD_DISTANCE_LIMIT}` }
+  return { status: 'verified', reason: 'UQ/OOD 证据完整(val 校准/test 实证,coverage 达 D3 门,操作点在域内)' }
+}
+
+export function createRecommendation(input: {
+  runId: string
+  candidate: SolveCandidate
+  candidateId: string
+  problemIrHash: string
+  modelArtifactHash: string
+  evidenceSource: 'simulation' | 'real' | 'unassessed'
+  uqEvidence: UqEvidence | null
+}): Recommendation {
+  const classified = classifyRecommendation({
+    evidenceSource: input.evidenceSource,
+    uqEvidence: input.uqEvidence,
+    candidateFeasible: input.candidate.feasible,
+  })
+  const id = `orec-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`
+  return getRunRepo().insertRecommendation({
+    id,
+    runId: input.runId,
+    candidateId: input.candidateId,
+    problemIrHash: input.problemIrHash,
+    modelArtifactHash: input.modelArtifactHash,
+    evidenceSource: input.evidenceSource,
+    uqEvidence: input.uqEvidence as Record<string, unknown> | null,
+    status: classified.status,
+    validUntil: new Date(Date.now() + RECOMMENDATION_TTL_MS).toISOString(),
+  })
+}
+
+export function expireRecommendations(filter: { runId?: string, bindingId?: string, problemIrHash?: string }): number {
+  return getRunRepo().expireWhere(filter)
+}
+
+export function assertRecommendationUsable(rec: Recommendation): Recommendation {
+  const expired = Date.parse(rec.validUntil) <= Date.now()
+  if (expired && rec.status !== 'expired') {
+    getRunRepo().expireWhere({ runId: rec.runId })
+    return { ...rec, status: 'expired', statusLabel: recommendationLabel('expired') }
+  }
+  if (rec.status === 'expired') return rec
+  return rec
+}

package/server/services/workshop/optimization/rest-auth.ts

@@ -0,0 +1,61 @@
+/**
+ * Optimizer REST 授权:登录 + 角色只是入口,必须再核验"该用户可支配该 Agent 实例"。
+ * 口径与 agent-tools/invoke 一致:admin 放行;其余必须是该 Channel 的成员/owner。
+ *
+ * 直接读 globalThis.__workshopManager(插件启动时装配):避免静态 import plugins/workshop
+ * 把 Nitro `#imports` 拖进本模块,便于单测注入假管理器。
+ */
+import { AppError } from '../../../utils/errors'
+import { getAmlRuntime } from '../aml/runtime'
+import type { ResolvedUser } from '../../../api/workshop/caller'
+import { getBindingRepo } from './binding.repo'
+import { revokeBinding } from './binding.service'
+import { getRunRepo } from './run.repo'
+
+interface ManagerLike {
+  deps: { repos: { channelAgents: { findById(id: string): { channelId: string } | undefined } } }
+  channelPermissionsOf(channelId: string, user: ResolvedUser): { isMember: boolean, canManage?: boolean }
+}
+
+export function assertAgentAccess(user: ResolvedUser, agentInstanceId: string, options: { manage?: boolean } = {}): { channelId: string } {
+  const manager = (globalThis as { __workshopManager?: ManagerLike }).__workshopManager
+  if (!manager) throw new AppError(503, 'WORKSHOP_NOT_READY', 'workshop 未就绪')
+  const row = manager.deps.repos.channelAgents.findById(agentInstanceId)
+  if (!row) {
+    // 模板 id(channel_agents 之外、agents 表内)给出可行动的具体错误,
+    // 而不是笼统的 404 —— 调用方需要知道"改用实例 id"。
+    let template: unknown
+    try {
+      template = getAmlRuntime().db.prepare('SELECT id FROM agents WHERE id = ?').get(agentInstanceId)
+    }
+    catch {
+      // AML 未初始化(单测/插件未启动)→ 保持既有 404 语义
+      template = undefined
+    }
+    if (template) {
+      throw new AppError(422, 'AGENT_TEMPLATE_ID_NOT_ALLOWED',
+        `传入的是 Agent 模板 id(${agentInstanceId});必须使用 Channel 实例 id(channel_agents.id)`)
+    }
+    throw new AppError(404, 'AGENT_NOT_FOUND', `Agent 实例 ${agentInstanceId} 不存在`)
+  }
+  if (user.role === 'admin') return { channelId: row.channelId }
+  const permissions = manager.channelPermissionsOf(row.channelId, user)
+  if (!permissions.isMember) {
+    throw new AppError(403, 'SCOPE_VIOLATION', '该 Agent 不属于当前用户所在 Channel,无权读取/代调用其优化器')
+  }
+  if (options.manage && !permissions.canManage) {
+    throw new AppError(403, 'SCOPE_VIOLATION', '无权管理该 Agent 所属 Channel 的优化器绑定')
+  }
+  return { channelId: row.channelId }
+}
+
+/** 管理授权通过后才撤权,避免拒绝请求使他人的建议失效。 */
+export function revokeBindingForUser(user: ResolvedUser, bindingId: string): void {
+  const binding = getBindingRepo().get(bindingId)
+  if (!binding) throw new AppError(404, 'BINDING_NOT_FOUND', `绑定 ${bindingId} 不存在`)
+  assertAgentAccess(user, binding.channelAgentId, { manage: true })
+  getRunRepo().expireWhere({ bindingId })
+  if (!revokeBinding(bindingId, user.id, user.name)) {
+    throw new AppError(404, 'BINDING_NOT_FOUND', `绑定 ${bindingId} 不存在`)
+  }
+}