agentworkshop 0.8.8 → 0.9.0

package/server/services/workshop/aml/action-coverage.ts

@@ -0,0 +1,253 @@
+/**
+ * 动作覆盖度(action coverage;科学探索计划 P3,docs/plans/2026-11-02-scientific-exploration-plan.md):
+ * 回答"这份数据在动作维度上到底有没有信息量"——预测精度高不代表动作维度被学到。
+ *
+ * 交给 G6 门的四个量:
+ *  - distinctLevels:控制量历史水平数(容差聚类)。<3 时无法区分线性/二次,也做不了正交阶梯;
+ *  - collinearityWithTime:|pearson(control, 时间序号)|。≈1 表示"档位"与"时间推进"是同一件事,
+ *    任何在该数据上学到的"效应"都可能只是漂移(事故形态:SP 降档 == 作业后半段);
+ *  - stepCount:水平切换次数。1 次单步(AB)只有 2 水平且极易与相位混淆,正交需要阶梯往返;
+ *  - saturationRatio:控制量落在观测极值(上/下沿)的样本占比。高值 = 长期贴边运行,
+ *    有效激励幅度远小于名义步长。
+ * 另附 levelPhaseMatrix(各水平的样本数与归一化时间位置),供人/Agent 直接看出"哪个水平只出现在后半段"。
+ *
+ * 另有 arxStepResponseGain:从 ARX 状态空间工件做阶跃仿真求稳态增益 ——
+ * 让"模型对某个 SP 到底有没有响应"变成一个可核对的数(P5 互审的模型侧通道)。
+ */
+import { pearson } from './stats'
+
+export interface ActionLevelInfo {
+  level: number
+  count: number
+  /** 该水平样本的平均归一化时间位置(0=最早,1=最晚) */
+  meanPhase: number
+}
+
+export interface ActionCoverage {
+  controlId: string
+  distinctLevels: number
+  stepCount: number
+  /** |pearson(control, 时间序号)|。注意 2 水平的理论上限是 0.866(不是 1),单靠它抓不住"纯阶梯" */
+  collinearityWithTime: number
+  /** 最长驻留水平的样本占比(≥0.9 → 激励不足提示;不是硬门) */
+  saturationRatio: number
+  levelPhaseMatrix: ActionLevelInfo[]
+  /** 每个水平的连续段数(1 = 该水平只出现在一个连续区间) */
+  levelBlocks: number[]
+  /** 所有水平都只出现一段 = 纯阶梯/单调斜坡:档位与时间推进不可分(正交需 ≥2 个来回) */
+  monolithicSequence: boolean
+  samples: number
+}
+
+export interface ActionCoverageThresholds {
+  minControlLevels: number
+  maxCollinearity: number
+}
+
+export interface ActionCoverageAssessment {
+  pass: boolean
+  reasons: string[]
+}
+
+/** 容差聚类水平(相对 1e-9 + 绝对 1e-12;与可辨识性引擎同口径) */
+function levelsOf(values: number[]): number[] {
+  const finite = values.filter(Number.isFinite).sort((a, b) => a - b)
+  const out: number[] = []
+  for (const v of finite) {
+    const last = out[out.length - 1]
+    const tol = last == null ? Infinity : Math.max(1e-12, Math.abs(v) * 1e-9)
+    if (last == null || Math.abs(v - last) > tol) out.push(v)
+  }
+  return out
+}
+
+/**
+ * 计算单控制列的覆盖度。values 为该控制量按时间顺序的实测/回显序列
+ * (跨 run 拼接时请按 run 分段调用再合并,避免把批次间的复位计成阶跃)。
+ */
+export function computeActionCoverage(controlId: string, values: number[]): ActionCoverage {
+  const finite = values.filter(Number.isFinite)
+  const n = finite.length
+  if (n === 0) {
+    return { controlId, distinctLevels: 0, stepCount: 0, collinearityWithTime: 0, saturationRatio: 0, levelPhaseMatrix: [], levelBlocks: [], monolithicSequence: false, samples: 0 }
+  }
+  const levels = levelsOf(finite)
+  // 水平切换次数(相邻样本跨水平)
+  const tolOf = (v: number): number => Math.max(1e-12, Math.abs(v) * 1e-9)
+  let stepCount = 0
+  for (let i = 1; i < n; i++) {
+    if (Math.abs(finite[i]! - finite[i - 1]!) > Math.max(tolOf(finite[i]!), tolOf(finite[i - 1]!))) stepCount++
+  }
+  // 时间共线(线性趋势)
+  const idx = finite.map((_, i) => i)
+  const collinearityWithTime = Math.abs(pearson(finite, idx))
+  // 最长驻留水平占比(激励不足的代理指标:控制量绝大部分时间停在同一档 = 有效激励样本很少)
+  const levelCounts = new Map<number, number>()
+  for (const v of finite) {
+    const level = levels.reduce((best, cand) => (Math.abs(v - cand) < Math.abs(v - best) ? cand : best), levels[0]!)
+    levelCounts.set(level, (levelCounts.get(level) ?? 0) + 1)
+  }
+  const saturationRatio = Math.max(...levelCounts.values()) / n
+  // 水平 × 相位
+  const levelPhaseMatrix: ActionLevelInfo[] = levels.map((level) => {
+    let count = 0
+    let phaseSum = 0
+    for (let i = 0; i < n; i++) {
+      if (Math.abs(finite[i]! - level) <= Math.max(tolOf(level), tolOf(finite[i]!))) {
+        count++
+        phaseSum += n > 1 ? i / (n - 1) : 0
+      }
+    }
+    return { level, count, meanPhase: count ? phaseSum / count : 0 }
+  })
+  // 水平 → 连续段数(段数=该水平出现后被别的水平打断的次数+1)。纯阶梯每档只有 1 段。
+  const levelIndex = finite.map(v => levels.findIndex(level => Math.abs(v - level) <= Math.max(tolOf(level), tolOf(v))))
+  const levelBlocks = levels.map((_, li) => {
+    let blocks = 0
+    let prevWasLevel = false
+    for (const cur of levelIndex) {
+      const isLevel = cur === li
+      if (isLevel && !prevWasLevel) blocks++
+      prevWasLevel = isLevel
+    }
+    return blocks
+  })
+  const monolithicSequence = levels.length >= 2 && levelBlocks.every(b => b === 1)
+  return { controlId, distinctLevels: levels.length, stepCount, collinearityWithTime, saturationRatio, levelPhaseMatrix, levelBlocks, monolithicSequence, samples: n }
+}
+
+/** G6 判定(阈值来自 amlSettings().gates) */
+export function assessActionCoverage(coverage: ActionCoverage, thresholds: ActionCoverageThresholds): ActionCoverageAssessment {
+  const reasons: string[] = []
+  if (coverage.samples === 0) {
+    reasons.push(`${coverage.controlId}: 无有效样本`)
+    return { pass: false, reasons }
+  }
+  let pass = true
+  if (coverage.distinctLevels < thresholds.minControlLevels) {
+    pass = false
+    reasons.push(`${coverage.controlId}: 仅 ${coverage.distinctLevels} 个水平(<${thresholds.minControlLevels});动作维度不足以识别,建议 ≥3 水平阶梯往返`)
+  }
+  if (coverage.collinearityWithTime > thresholds.maxCollinearity) {
+    pass = false
+    reasons.push(`${coverage.controlId}: 与时间序号 |r|=${coverage.collinearityWithTime.toFixed(3)}(>${thresholds.maxCollinearity});档位与时间推进共线,效应不可归因`)
+  }
+  if (coverage.stepCount === 0 && coverage.distinctLevels > 1) {
+    // 水平数>1 但无切换 = 拼接边界伪水平;不是正交激励
+    pass = false
+    reasons.push(`${coverage.controlId}: 无水平切换(疑似跨批次拼接);不构成阶梯激励`)
+  }
+  if (coverage.monolithicSequence) {
+    // 纯阶梯(每档只出现一段)无论档数多少都与时间推进不可分:
+    // 2 水平的 |r| 理论上限仅 0.866,直线阈值抓不住,必须用连续段判据
+    pass = false
+    reasons.push(`${coverage.controlId}: ${coverage.distinctLevels} 个水平各仅单一连续段(纯阶梯),档位与时间推进不可分;正交设计需 ≥2 个来回阶梯(ABAB/A→B→A)`)
+  }
+  if (coverage.saturationRatio >= 0.9) {
+    reasons.push(`${coverage.controlId}: ${(coverage.saturationRatio * 100).toFixed(0)}% 样本停在单一档位(激励不足),有效激励幅度可能远小于名义步长`)
+  }
+  return { pass, reasons }
+}
+
+/** 数据集级汇总(任一控制列不过 → 整体不过;无控制列 → 不适用,pass=true 且 detail 说明) */
+export function assessDatasetActionCoverage(
+  coverage: ActionCoverage[],
+  thresholds: ActionCoverageThresholds,
+): { pass: boolean, applicable: boolean, reasons: string[], per: Array<{ coverage: ActionCoverage, assessment: ActionCoverageAssessment }> } {
+  if (coverage.length === 0) {
+    return { pass: true, applicable: false, reasons: ['数据集未声明 role=control 节点,动作覆盖门不适用'], per: [] }
+  }
+  const per = coverage.map(c => ({ coverage: c, assessment: assessActionCoverage(c, thresholds) }))
+  return {
+    pass: per.every(p => p.assessment.pass),
+    applicable: true,
+    reasons: per.flatMap(p => p.assessment.reasons),
+    per,
+  }
+}
+
+// ---------- ARX 动作敏感度(阶跃仿真稳态增益) ----------
+
+export interface ArxArtifactLike {
+  A: number[][]
+  B: number[][]
+  C: number[][]
+  D: number[][]
+  mvOrder: string[]
+  cvOrder: string[]
+  /** 可选:归一化统计(把归一化增益折回物理单位) */
+  norm?: { u: { mean: number[], std: number[] }, y: { mean: number[], std: number[] } }
+}
+
+export interface ActionSensitivity {
+  controlId: string
+  /** 控制量 +1 单位(物理单位,若提供 norm)在目标上的稳态变化;按目标节点给出 */
+  gains: Record<string, number>
+  /** 仿真是否收敛(未收敛的增益不可用) */
+  converged: boolean
+  steps: number
+}
+
+/**
+ * 用工件自身的状态方程做单位阶跃仿真,求稳态增益:y_ss(j) = (C(I−A)⁻¹B + D) 的列。
+ * 数值上直接迭代 x_{k+1} = A x_k + B u, y_k = C x_k + D u,直到 |Δy| < 1e-10 或 5000 拍。
+ * 若提供 norm,再做物理单位换算:Δy_phys = Δy_norm · std_y / std_u。
+ */
+export function arxStepResponseGain(artifact: ArxArtifactLike, controlId: string): ActionSensitivity | null {
+  const m = artifact.mvOrder.indexOf(controlId)
+  if (m < 0) return null
+  const A = artifact.A
+  const B = artifact.B
+  const C = artifact.C
+  const D = artifact.D
+  const nState = A.length
+  const nY = C.length
+  if (!nState || !nY) return null
+  const u = new Array<number>(artifact.mvOrder.length).fill(0)
+  u[m] = 1
+  let x = new Array<number>(nState).fill(0)
+  const yOf = (xx: number[]): number[] => C.map((row, j) => row.reduce((s, c, i) => s + c * (xx[i] ?? 0), 0) + (D[j] ?? []).reduce((s, d, i) => s + d * (u[i] ?? 0), 0))
+  const y0 = yOf(x)
+  const maxSteps = 5000
+  let converged = false
+  let prev = y0
+  let steps = 0
+  for (let k = 0; k < maxSteps; k++) {
+    const next = new Array<number>(nState).fill(0)
+    for (let i = 0; i < nState; i++) {
+      let acc = 0
+      for (let j = 0; j < nState; j++) acc += (A[i]?.[j] ?? 0) * (x[j] ?? 0)
+      for (let q = 0; q < u.length; q++) acc += (B[i]?.[q] ?? 0) * (u[q] ?? 0)
+      next[i] = acc
+    }
+    x = next
+    const y = yOf(x)
+    steps = k + 1
+    const dy = y.reduce((a, v, j) => a + Math.abs(v - (prev[j] ?? 0)), 0)
+    prev = y
+    if (!Number.isFinite(dy)) return { controlId, gains: {}, converged: false, steps }
+    // 首拍 y 可能恰好不动(输入还没传到输出),必须跑过若干拍再判收敛,否则增益恒为 0
+    if (steps >= 10 && dy < 1e-10) {
+      converged = true
+      break
+    }
+  }
+  const gains: Record<string, number> = {}
+  const stdU = artifact.norm?.u.std[m]
+  prev.forEach((v, j) => {
+    const target = artifact.cvOrder[j] ?? `y${j}`
+    const stdY = artifact.norm?.y.std[j]
+    const physical = artifact.norm && stdU && Number.isFinite(stdU) && stdU !== 0 && stdY != null
+      ? (v / stdU) * stdY
+      : v
+    gains[target] = physical
+  })
+  return { controlId, gains, converged, steps }
+}
+
+/** 敏感度是否为"可分辨的耦合"(|gain| 超过给定下限,缺省 1e-9) */
+export function hasResolvableCoupling(sensitivity: ActionSensitivity | null, targetNodeId: string, minGain = 1e-9): boolean {
+  if (!sensitivity || !sensitivity.converged) return false
+  const g = sensitivity.gains[targetNodeId]
+  return typeof g === 'number' && Number.isFinite(g) && Math.abs(g) > minGain
+}

package/server/services/workshop/aml/causal-claim.ts

@@ -0,0 +1,68 @@
+/**
+ * 因果断言质量门(科学探索计划 P6):识别"无证据锚的因果叙述",供 KB 入库审批卡标记。
+ * 背景事故:一条"变厚由瓶坯/熔体温度驱动"的叙述无证据锚、不可追溯,进了 KB 之后
+ * 被下游 Agent 当事实检索之后 —— 知识污染。处置口径:**不禁止写入**,但必须
+ *  (a) 在审批卡显式标注 anecdotal; (b) 建议补 intervention:/ontology: 引用;
+ *  (c) 审核人可见"这条没有证据"。检索侧降权属 KB 侧能力(rag-bridge),本模块只给标记。
+ */
+
+export interface CausalClaimAssessment {
+  /** 文本是否包含因果措辞 */
+  isCausal: boolean
+  /** 是否带可追溯引用(intervention:/ontology:/pexp:/evidence:) */
+  hasEvidenceRef: boolean
+  /** 命中的引用 */
+  refs: string[]
+  /** 因果断言但无引用 → 仅供叙述(anecdotal),检索应降权 */
+  anecdotal: boolean
+  reasons: string[]
+}
+
+const CAUSAL_PATTERNS: Array<{ re: RegExp, label: string }> = [
+  { re: /导致|引起|造成|驱动|使得|促使|影响(?:了|着)/, label: '中文因果动词' },
+  { re: /因为[^。]{0,40}所以|由于[^。]{0,40}(因此|导致|使)/, label: '中文因果句式' },
+  { re: /降低|提升|增加|减少|改善|恶化|下调|上调|下降|上升[^。]{0,30}(厚度|重量|良率|偏差|缺陷|壁厚|克重)/, label: '指标变化断言' },
+  { re: /(厚度|重量|良率|偏差|缺陷|壁厚|克重)[^。]{0,30}(变化|波动|升高|降低|变大|变小)/, label: '指标响应断言' },
+  { re: /\b(causes?|caused by|drives?|driven by|leads? to|results? in|due to|because of)\b/i, label: 'English causal' },
+  { re: /\b(reduces?|increases?|improves?|degrades?)\b[^.]{0,40}\b(thickness|weight|yield|deviation|defect)\b/i, label: 'English metric claim' },
+]
+
+const EVIDENCE_REF_PATTERNS: Array<{ re: RegExp, label: string }> = [
+  { re: /\bintv[_-][a-z0-9-]+/i, label: 'intervention' },
+  { re: /\bpexp-[a-z0-9-]+/i, label: 'experiment-plan' },
+  { re: /\bev-[a-z0-9-]+/i, label: 'evidence' },
+  { re: /\bont-[a-z0-9_-]+@?\d*/i, label: 'ontology' },
+  { re: /(证据|evidence)\s*[:：]\s*\S+/, label: 'evidence-label' },
+  { re: /(干预|experiment|台账)\s*(id|记录)\s*[:：]\s*\S+/i, label: 'ledger-ref' },
+]
+
+/**
+ * 评估一段待入 KB 的文本。判定顺序:有因果措辞 → 才看引用;
+ * 非因果叙述不受本门约束(如纯读取事实/流程说明)。
+ */
+export function assessCausalClaim(text: string): CausalClaimAssessment {
+  const body = String(text ?? '')
+  const causalHits = CAUSAL_PATTERNS.filter(p => p.re.test(body)).map(p => p.label)
+  const refs = EVIDENCE_REF_PATTERNS.filter(p => p.re.test(body)).map(p => matchOf(p.re, body)).filter(Boolean)
+  const isCausal = causalHits.length > 0
+  const hasEvidenceRef = refs.length > 0
+  const anecdotal = isCausal && !hasEvidenceRef
+  const reasons: string[] = []
+  if (isCausal) reasons.push(`命中因果措辞(${causalHits.join('/')})`)
+  if (isCausal && hasEvidenceRef) reasons.push(`带可追溯引用(${refs.join(', ')})`)
+  if (anecdotal) reasons.push('因果断言无证据锚:仅按叙述(anecdotal)对待,检索应降权;建议补 intervention:<id>/ontology:<id>@<version> 引用')
+  return { isCausal, hasEvidenceRef, refs, anecdotal, reasons }
+}
+
+function matchOf(re: RegExp, text: string): string {
+  const m = text.match(re)
+  return m ? m[0].slice(0, 80) : ''
+}
+
+/** KB 入库审批卡的标注段(无因果 → 空数组) */
+export function causalClaimLines(a: CausalClaimAssessment): string[] {
+  if (!a.isCausal) return []
+  return a.anecdotal
+    ? [`[证据质量] ⚠ 无证据锚的因果断言(anecdotal):${a.reasons.join(';')}`]
+    : [`[证据质量] 因果断言带引用(${a.refs.join(', ')}),可按证据等级采用`]
+}

package/server/services/workshop/aml/dataset-builder.ts

@@ -21,6 +21,7 @@ import { amlSettings } from '../settings'
 import type { AmlDatasetSpec } from './spec'
 import { cleanPoints, alignToGrid } from './clean'
 import { summarize, lagCrossCorr, type SeriesSummary, type LagEstimate, type RunProfile } from './stats'
+import { computeActionCoverage, type ActionCoverage } from './action-coverage'
 import { getAmlRuntime } from './runtime'
 import type { AmlDatasetRow } from './aml.repo'
 
@@ -48,6 +49,8 @@ export interface AmlManifest {
   specVersion?: number
   recipeVersion?: number
   variables?: ProcessDatasetExtras['variables']
+  /** P3 动作覆盖度(v2 才写;v1 数据集读取方按缺失处理 = unknown,不追溯误杀) */
+  actionCoverage?: ActionCoverage[]
   artifacts?: { x: string, u: string, y: string, timestamps: string, mask: string, sidecar: string }
   provenance?: {
     lineId: string, productId: string, recipeId: string, recipeVersion: number, runIds: string[]
@@ -64,6 +67,8 @@ export interface AmlDatasetReport {
   runsUsed: string[]
   runsDropped: { runId: string, reason: string }[]
   windowCount: { train: number, val: number, test: number }
+  /** P3:每个 role=control 节点的动作覆盖度(无控制列时为空数组) */
+  actionCoverage?: ActionCoverage[]
 }
 
 export interface BuildDatasetResult {
@@ -486,6 +491,18 @@ export async function buildDataset(spec: AmlDatasetSpec, by: { id: string, kind:
     }
   }
 
+  // P3 动作覆盖度:按控制节点聚合跨 run 序列(水平聚类用全序列;切换次数按 run 内计,
+  // 避免批次边界的复位被当成阶跃激励)。v2 数据集写进 manifest(actionCoverage)供 G6 门,
+  // 也进 report 供 aml_dataset_stats 人读;v1 数据集不写 = unknown,G6 不追溯误杀。
+  const actionCoverage: ActionCoverage[] = ctrlIds.map((cid) => {
+    const perRun = [...runMatrices.values()]
+      .map(m => (m.rows.get(cid) ?? []).filter(v => typeof v === 'number' && Number.isFinite(v)))
+      .filter(v => v.length > 0)
+    const merged = computeActionCoverage(cid, perRun.flat())
+    const stepsWithinRuns = perRun.reduce((acc, series) => acc + computeActionCoverage(cid, series).stepCount, 0)
+    return { ...merged, stepCount: stepsWithinRuns }
+  })
+
   // 6. 落盘快照
   const dsId = `ds-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
   const dir = join(rt.datasetsDir, dsId)
@@ -551,6 +568,7 @@ export async function buildDataset(spec: AmlDatasetSpec, by: { id: string, kind:
     const v2 = {
       ...manifest,
       version: 2,
+      actionCoverage,
       dataKind: extras.trainerRef === 'static_response@1' ? 'static' : 'dynamic',
       specHash: extras.specRef,
       specVersion: extras.specVersion,
@@ -610,6 +628,7 @@ export async function buildDataset(spec: AmlDatasetSpec, by: { id: string, kind:
     runsUsed: [...runMatrices.keys()],
     runsDropped,
     windowCount: { train: split.train, val: split.val, test: split.test },
+    actionCoverage,
   }
   writeFileSync(join(dir, 'report.json'), JSON.stringify(report, null, 2))
 

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

@@ -8,6 +8,7 @@ import { join } from 'node:path'
 import { amlSettings } from '../settings'
 import type { AmlManifest } from './dataset-builder'
 import type { AmlDatasetRow } from './aml.repo'
+import { assessDatasetActionCoverage } from './action-coverage'
 
 export interface PlatformMetrics {
   oneStepVal?: { windows: number, nrmse: number } | null
@@ -38,7 +39,7 @@ export interface GateReport {
 export function evaluateGates(
   purpose: string,
   dataset: Pick<AmlDatasetRow, 'rowCount' | 'runIds'>,
-  manifest: Pick<AmlManifest, 'split'>,
+  manifest: Pick<AmlManifest, 'split' | 'actionCoverage'>,
   metrics: PlatformMetrics | undefined,
   artifactsDir: string,
 ): GateReport {
@@ -155,6 +156,49 @@ export function evaluateGates(
   }
   checks.push({ id: 'G5', name: '工件完整(按工件类型)', value: null, threshold: null, pass: g5pass, detail: g5detail })
 
+  // G6:动作覆盖度(科学探索计划 P3)。回答"这份数据在动作维度有没有信息量":
+  // 水平数不足 → 模型学不到动作;与时间共线 → 学到的"效应"可能只是漂移。
+  // v1 数据集无 actionCoverage 字段 = unknown(不追溯误杀,detail 如实说明)。
+  const coverage = manifest.actionCoverage
+  if (coverage === undefined) {
+    checks.push({
+      id: 'G6',
+      name: '动作覆盖(控制水平数/时间共线)',
+      value: null,
+      threshold: null,
+      pass: true,
+      detail: '数据集未携带动作覆盖度(v1 数据集/unknown):门禁不追溯,重建数据集(v2)后强制校验',
+    })
+  }
+  else if (coverage.length === 0) {
+    checks.push({
+      id: 'G6',
+      name: '动作覆盖(控制水平数/时间共线)',
+      value: null,
+      threshold: null,
+      pass: true,
+      detail: '数据集未声明 role=control 节点:动作覆盖门不适用(纯预测器,不可用于控制决策)',
+    })
+  }
+  else {
+    const assessment = assessDatasetActionCoverage(coverage, {
+      minControlLevels: g.minControlLevels,
+      maxCollinearity: g.maxCollinearity,
+    })
+    const minLevels = Math.min(...coverage.map(c => c.distinctLevels))
+    const maxR = Math.max(...coverage.map(c => c.collinearityWithTime))
+    checks.push({
+      id: 'G6',
+      name: '动作覆盖(控制水平数/时间共线)',
+      value: minLevels,
+      threshold: g.minControlLevels,
+      pass: assessment.pass,
+      detail: assessment.pass
+        ? `${coverage.length} 个控制节点,最少 ${minLevels} 个水平(≥${g.minControlLevels}),时间共线 max |r|=${maxR.toFixed(3)}(≤${g.maxCollinearity})`
+        : assessment.reasons.join(';'),
+    })
+  }
+
   return { passed: checks.every(c => c.pass), checks }
 }