agentworkshop 0.7.71 → 0.8.1

package/server/services/workshop/ontology/subgraph.core.ts

@@ -0,0 +1,300 @@
+/**
+ * 本体子图 BFS 纯核心 —— 零 DB / 零框架依赖,供 REST、Agent 工具与单测共用。
+ *
+ * 语义(与 docs/plans/2026-10-25-ontology-graph-visualization.md §2 一致):
+ *  - nodes 含 center(hop=0);limit 统计含 center
+ *  - edge.hop = max(hop(src), hop(dst));direction 由两端 hop 差决定(自环=loop)
+ *  - direction=both 返回已访问节点之间的全部诱导边(含 lateral);out/in 只保留不倒走该方向的边
+ *  - kinds 同时过滤遍历与输出;truncated 仅表示因 limit 未纳入可达节点
+ *  - 输出排序确定:nodes 按 (hop, key),edges 按 (hop, id)
+ */
+import { AppError } from '../../../utils/errors'
+import { ONTOLOGY_RELATION_KINDS, type OntologyRelationKind } from './contracts'
+
+export const SUBGRAPH_DEFAULT_HOPS = 1
+export const SUBGRAPH_MAX_HOPS = 3
+export const SUBGRAPH_DEFAULT_LIMIT = 50
+export const SUBGRAPH_MAX_LIMIT = 200
+
+export type SubgraphDirection = 'both' | 'out' | 'in'
+export type SubgraphEdgeDirection = 'out' | 'in' | 'lateral' | 'loop'
+
+export interface SubgraphBindingView {
+  platformKind: string
+  platformId: string
+  targetSub: string
+  direction: string
+  status: string
+  unitDeclared: string
+  unitTarget: string
+  scale: number
+  offset: number
+}
+
+export interface SubgraphEntityView {
+  key: string
+  kind: string
+  name: string
+  description: string
+  unit: string
+  role?: string
+  hop: number
+}
+
+export interface SubgraphEdgeView {
+  id: string
+  kind: string
+  srcKey: string
+  dstKey: string
+  evidenceTier: string
+  hop: number
+  direction: SubgraphEdgeDirection
+}
+
+export interface SubgraphAround {
+  ontologyId: string
+  version: number
+  lineId: string
+  center: SubgraphEntityView & { hop: 0, bindings: SubgraphBindingView[] }
+  nodes: SubgraphEntityView[]
+  edges: SubgraphEdgeView[]
+  truncated: boolean
+}
+
+export interface SubgraphEntityInput {
+  key: string
+  kind: string
+  name: string
+  description?: string
+  unit: string
+  role?: string
+}
+
+export interface SubgraphRelationInput {
+  id: string
+  kind: string
+  srcKey: string
+  dstKey: string
+  evidenceTier: string
+}
+
+export interface SubgraphBindingInput {
+  entityKey: string
+  platformKind: string
+  platformId: string
+  targetSub?: string
+  direction: string
+  status?: string
+  unitDeclared?: string
+  unitTarget?: string
+  scale?: number
+  offset?: number
+}
+
+export interface SubgraphGraphData {
+  entities: SubgraphEntityInput[]
+  relations: SubgraphRelationInput[]
+  bindings: SubgraphBindingInput[]
+}
+
+export interface SubgraphMeta {
+  ontologyId: string
+  version: number
+  lineId: string
+}
+
+export interface SubgraphOptions {
+  hops?: number
+  direction?: SubgraphDirection
+  /** null = 不过滤(与 parseSubgraphOptions 的解析结果可直接互传) */
+  kinds?: OntologyRelationKind[] | null
+  limit?: number
+}
+
+/** 已解析、已校验的选项(缺省值已落地) */
+export interface ResolvedSubgraphOptions {
+  hops: number
+  direction: SubgraphDirection
+  kinds: OntologyRelationKind[] | null
+  limit: number
+}
+
+const RELATION_KIND_SET = new Set<string>(ONTOLOGY_RELATION_KINDS)
+
+function isDirection(value: string): value is SubgraphDirection {
+  return value === 'both' || value === 'out' || value === 'in'
+}
+
+function parseInteger(value: unknown, fallback: number): number {
+  if (value === undefined || value === null || value === '') return fallback
+  const n = typeof value === 'number' ? value : Number(String(value))
+  if (!Number.isInteger(n)) return Number.NaN
+  return n
+}
+
+/** 解析并校验查询参数(未给则取缺省);kinds 支持逗号分隔或数组 */
+export function parseSubgraphOptions(raw: {
+  hops?: unknown
+  direction?: unknown
+  kinds?: unknown
+  limit?: unknown
+} = {}): ResolvedSubgraphOptions {
+  const hops = parseInteger(raw.hops, SUBGRAPH_DEFAULT_HOPS)
+  if (!Number.isInteger(hops) || hops < 1 || hops > SUBGRAPH_MAX_HOPS) {
+    throw new AppError(422, 'ONTOLOGY_SUBGRAPH_HOPS_INVALID', `hops 必须是 1-${SUBGRAPH_MAX_HOPS} 的整数`)
+  }
+  const directionRaw = typeof raw.direction === 'string' && raw.direction.trim() ? raw.direction.trim() : 'both'
+  if (!isDirection(directionRaw)) {
+    throw new AppError(422, 'ONTOLOGY_SUBGRAPH_DIRECTION_INVALID', 'direction 必须是 both/out/in')
+  }
+  const limit = parseInteger(raw.limit, SUBGRAPH_DEFAULT_LIMIT)
+  if (!Number.isInteger(limit) || limit < 1 || limit > SUBGRAPH_MAX_LIMIT) {
+    throw new AppError(422, 'ONTOLOGY_SUBGRAPH_LIMIT_INVALID', `limit 必须是 1-${SUBGRAPH_MAX_LIMIT} 的整数`)
+  }
+  let kinds: OntologyRelationKind[] | null = null
+  if (raw.kinds !== undefined && raw.kinds !== null) {
+    const list = (Array.isArray(raw.kinds) ? raw.kinds : String(raw.kinds).split(','))
+      .map(k => String(k).trim())
+      .filter(Boolean)
+    if (!list.length) {
+      throw new AppError(422, 'ONTOLOGY_SUBGRAPH_KIND_INVALID', 'kinds 不能为空(缺省表示全部)')
+    }
+    for (const kind of list) {
+      if (!RELATION_KIND_SET.has(kind)) {
+        throw new AppError(422, 'ONTOLOGY_SUBGRAPH_KIND_INVALID',
+          `未知关系类型「${kind}」;可选:${ONTOLOGY_RELATION_KINDS.join(', ')}`)
+      }
+    }
+    kinds = [...new Set(list)] as OntologyRelationKind[]
+  }
+  return { hops, direction: directionRaw, kinds, limit }
+}
+
+function bindingOf(bindings: SubgraphBindingInput[], entityKey: string): SubgraphBindingView[] {
+  return bindings
+    .filter(b => b.entityKey === entityKey)
+    .map(b => ({
+      platformKind: b.platformKind,
+      platformId: b.platformId,
+      targetSub: b.targetSub ?? '',
+      direction: b.direction,
+      status: b.status ?? 'active',
+      unitDeclared: b.unitDeclared ?? '',
+      unitTarget: b.unitTarget ?? '',
+      scale: typeof b.scale === 'number' ? b.scale : 1,
+      offset: typeof b.offset === 'number' ? b.offset : 0,
+    }))
+}
+
+function nodeOf(entity: SubgraphEntityInput, hop: number): SubgraphEntityView {
+  return {
+    key: entity.key,
+    kind: entity.kind,
+    name: entity.name,
+    description: entity.description ?? '',
+    unit: entity.unit,
+    role: entity.role,
+    hop,
+  }
+}
+
+/**
+ * 以 entityKey 为中心做 BFS,返回诱导子图。
+ * 中心实体不存在 → 404 ONTOLOGY_SUBGRAPH_ENTITY_NOT_FOUND。
+ */
+export function buildSubgraphAround(
+  entityKey: string,
+  data: SubgraphGraphData,
+  meta: SubgraphMeta,
+  options: SubgraphOptions = {},
+): SubgraphAround {
+  // 校验与缺省只有一处实现:服务层/路由/工具都不需要各自复制边界规则
+  const opts: ResolvedSubgraphOptions = parseSubgraphOptions(options)
+  const entityOf = new Map(data.entities.map(e => [e.key, e]))
+  const center = entityOf.get(entityKey)
+  if (!center) {
+    throw new AppError(404, 'ONTOLOGY_SUBGRAPH_ENTITY_NOT_FOUND',
+      `本体 ${meta.ontologyId}@${meta.version} 中不存在实体「${entityKey}」`)
+  }
+  const kindSet = opts.kinds ? new Set<string>(opts.kinds) : null
+  const relations = data.relations.filter(r => !kindSet || kindSet.has(r.kind))
+  const outAdj = new Map<string, string[]>()
+  const inAdj = new Map<string, string[]>()
+  for (const rel of relations) {
+    if (rel.srcKey === rel.dstKey) continue
+    if (!entityOf.has(rel.srcKey) || !entityOf.has(rel.dstKey)) continue
+    const outs = outAdj.get(rel.srcKey) ?? []
+    outs.push(rel.dstKey)
+    outAdj.set(rel.srcKey, outs)
+    const ins = inAdj.get(rel.dstKey) ?? []
+    ins.push(rel.srcKey)
+    inAdj.set(rel.dstKey, ins)
+  }
+
+  const hopOf = new Map<string, number>([[entityKey, 0]])
+  let truncated = false
+  let frontier = [entityKey]
+  let hop = 0
+  while (frontier.length && hop < opts.hops) {
+    hop += 1
+    const next: string[] = []
+    for (const key of frontier) {
+      const neighbours = opts.direction === 'in'
+        ? (inAdj.get(key) ?? [])
+        : opts.direction === 'out'
+          ? (outAdj.get(key) ?? [])
+          : [...(outAdj.get(key) ?? []), ...(inAdj.get(key) ?? [])]
+      for (const neighbour of neighbours) {
+        if (hopOf.has(neighbour)) continue
+        if (hopOf.size >= opts.limit) {
+          truncated = true
+          continue
+        }
+        hopOf.set(neighbour, hop)
+        next.push(neighbour)
+      }
+    }
+    frontier = next
+  }
+
+  const nodes = [...hopOf.entries()]
+    .map(([key, h]) => nodeOf(entityOf.get(key)!, h))
+    .sort((a, b) => (a.hop - b.hop) || a.key.localeCompare(b.key))
+
+  const edges: SubgraphEdgeView[] = []
+  for (const rel of relations) {
+    const srcHop = hopOf.get(rel.srcKey)
+    const dstHop = hopOf.get(rel.dstKey)
+    if (srcHop === undefined || dstHop === undefined) continue
+    // 单向模式只保留真正沿该方向跨了一跳的边;同跳横边(lateral)只在 both 模式展示
+    if (opts.direction === 'out' && dstHop !== srcHop + 1) continue
+    if (opts.direction === 'in' && srcHop !== dstHop + 1) continue
+    const direction: SubgraphEdgeDirection = rel.srcKey === rel.dstKey
+      ? 'loop'
+      : dstHop === srcHop + 1
+        ? 'out'
+        : srcHop === dstHop + 1
+          ? 'in'
+          : 'lateral'
+    edges.push({
+      id: rel.id,
+      kind: rel.kind,
+      srcKey: rel.srcKey,
+      dstKey: rel.dstKey,
+      evidenceTier: rel.evidenceTier,
+      hop: Math.max(srcHop, dstHop),
+      direction,
+    })
+  }
+  edges.sort((a, b) => (a.hop - b.hop) || a.id.localeCompare(b.id))
+
+  return {
+    ontologyId: meta.ontologyId,
+    version: meta.version,
+    lineId: meta.lineId,
+    center: { ...nodeOf(center, 0), hop: 0, bindings: bindingOf(data.bindings, entityKey) },
+    nodes,
+    edges,
+    truncated,
+  }
+}

package/server/services/workshop/ontology/subgraph.service.ts

@@ -0,0 +1,113 @@
+/**
+ * 本体子图服务层 —— 把仓储/草稿文档适配成纯核心需要的输入。
+ *
+ * 两条数据路径,语义必须分清:
+ *  - subgraphAroundForLine:只读**已发布**活跃版本(与 sceneSubgraph 同口径,供 Agent/MCP)
+ *  - subgraphAroundDoc:读**草稿**(供 /ontology 页面,画图与抽屉必须与表格同源)
+ */
+import { AppError } from '../../../utils/errors'
+import type { OntologyDraftDoc } from './contracts'
+import { getOntologyRepo } from './repo'
+import { resolveActiveOntology } from './ontology.service'
+import {
+  buildSubgraphAround, type SubgraphAround, type SubgraphGraphData, type SubgraphOptions,
+} from './subgraph.core'
+
+export interface OntologyVersionRef {
+  id: string
+  version: number
+  lineId: string
+}
+
+function versionRefOf(active: NonNullable<ReturnType<typeof resolveActiveOntology>>, lineId: string): OntologyVersionRef {
+  return { id: active.version.id, version: active.version.version, lineId }
+}
+
+/** 从已发布版本快照读取图数据 */
+export function loadVersionGraph(ref: OntologyVersionRef): SubgraphGraphData {
+  const repo = getOntologyRepo()
+  const entities = repo.listEntities(ref.id, ref.version)
+  const relations = repo.listRelations(ref.id, ref.version)
+  const bindings = repo.listBindings(ref.id, ref.version)
+  return {
+    entities: entities.map(e => ({
+      key: e.key, kind: e.kind, name: e.name, description: e.description, unit: e.unit, role: e.role,
+    })),
+    relations: relations.map(r => ({
+      id: r.id, kind: r.kind, srcKey: r.srcKey, dstKey: r.dstKey, evidenceTier: r.properties.evidenceTier,
+    })),
+    bindings: bindings.map(b => ({
+      entityKey: b.entityKey,
+      platformKind: b.platformKind,
+      platformId: b.platformId,
+      targetSub: b.targetSub,
+      direction: b.direction,
+      status: b.status,
+      unitDeclared: b.unitDeclared,
+      unitTarget: b.unitTarget,
+      scale: b.scale,
+      offset: b.offset,
+    })),
+  }
+}
+
+/** 指定已发布版本(调用方需自行校验归属) */
+export function subgraphAroundForVersion(
+  ref: OntologyVersionRef,
+  entityKey: string,
+  opts: SubgraphOptions = {},
+): SubgraphAround {
+  const meta = { ontologyId: ref.id, version: ref.version, lineId: ref.lineId }
+  return buildSubgraphAround(entityKey, loadVersionGraph(ref), meta, opts)
+}
+
+/**
+ * 产线活跃已发布版本的邻接子图;该产线无已发布本体 → null(与 scene 的 active:false 同语义)。
+ */
+export function subgraphAroundForLine(
+  lineId: string,
+  entityKey: string,
+  opts: SubgraphOptions = {},
+): SubgraphAround | null {
+  const active = resolveActiveOntology(lineId)
+  if (!active) return null
+  return subgraphAroundForVersion(versionRefOf(active, lineId), entityKey, opts)
+}
+
+/** 草稿文档的邻接子图(供 UI:图与抽屉同源) */
+export function subgraphAroundDoc(
+  doc: OntologyDraftDoc,
+  entityKey: string,
+  opts: SubgraphOptions = {},
+): SubgraphAround {
+  const ontologyId = typeof (doc as { ontologyId?: unknown }).ontologyId === 'string'
+    ? String((doc as { ontologyId?: unknown }).ontologyId)
+    : doc.name
+  const data: SubgraphGraphData = {
+    entities: doc.entities.map(e => ({
+      key: e.key, kind: e.kind, name: e.name, description: e.description, unit: e.unit, role: e.role,
+    })),
+    relations: doc.relations.map(r => ({
+      id: r.id, kind: r.kind, srcKey: r.srcKey, dstKey: r.dstKey, evidenceTier: r.properties.evidenceTier,
+    })),
+    bindings: doc.bindings.map(b => ({
+      entityKey: b.entityKey,
+      platformKind: b.platformKind,
+      platformId: b.platformId,
+      targetSub: b.targetSub,
+      direction: b.direction,
+      unitDeclared: b.unitDeclared,
+      unitTarget: b.unitTarget,
+      scale: b.scale,
+      offset: b.offset,
+    })),
+  }
+  return buildSubgraphAround(entityKey, data, { ontologyId, version: 0, lineId: doc.lineId }, opts)
+}
+
+/** 供路由复用的实体必填校验 */
+export function requireEntityKey(raw: unknown): string {
+  const value = typeof raw === 'string' ? raw.trim() : ''
+  if (!value) throw new AppError(422, 'ONTOLOGY_ENTITY_REQUIRED', 'entity 必填(实体 key,如 mv.hold_pressure)')
+  return value
+}

package/server/services/workshop/ontology/validator.ts

@@ -0,0 +1,218 @@
+/**
+ * 本体文档校验(零 DB 纯函数,可单测)。
+ *
+ * 只做结构/语义自洽判定;存在性、归属、读写能力等「活体」判定在
+ * semantic-binding.service(需要查 daq/dcw/recipe 真实对象)。
+ *
+ * fail-closed 原则:每条问题都带可行动 hint,禁止静默降级。
+ */
+import type { CompileIssue, EvidenceLevel, OntologyDraftDoc, OntologyEntity, OntologyRule } from './contracts'
+import {
+  ONTOLOGY_STATES,
+  RULE_ERROR_CODES,
+  entityUnitIssue,
+  evidenceLevelRank,
+  maxEvidenceLevel,
+  unitsCompatible,
+} from './contracts'
+
+export interface DraftStats {
+  entities: number
+  relations: number
+  rules: number
+  bindings: number
+  byState: Record<string, number>
+  byEvidence: Record<string, number>
+}
+
+export interface DraftValidationReport {
+  ok: boolean
+  issues: CompileIssue[]
+  stats: DraftStats
+}
+
+function issue(code: string, path: string, message: string, severity: 'error' | 'warning' = 'error', hint?: string, ruleId?: string): CompileIssue {
+  return { code, path, message, severity, hint, ruleId }
+}
+
+/** 规则 DSL 里出现的全部变量引用 */
+export function ruleVariableRefs(rule: OntologyRule): string[] {
+  const dsl = rule.dsl
+  switch (dsl.type) {
+    case 'bound': return [dsl.variableKey]
+    case 'rate': return [dsl.variableKey]
+    case 'linear_coupling': return [dsl.variableKey, dsl.ofKey]
+    case 'nonlinear': return [dsl.variableKey]
+    case 'state_condition': return [dsl.when.variableKey, dsl.forbid.variableKey]
+    case 'interlock': return dsl.variableKey ? [dsl.variableKey] : []
+    case 'informal': return []
+    default: return []
+  }
+}
+
+/** 规则证据能支持的最强级别 */
+export function ruleEvidenceLevel(rule: OntologyRule): EvidenceLevel | '' {
+  return maxEvidenceLevel(rule.evidence.map(e => e.level))
+}
+
+export function validateDraftDoc(doc: OntologyDraftDoc): DraftValidationReport {
+  const issues: CompileIssue[] = []
+  const entityByKey = new Map<string, OntologyEntity>()
+
+  // ---- 实体 ----
+  const seenKeys = new Set<string>()
+  doc.entities.forEach((entity, index) => {
+    if (seenKeys.has(entity.key)) {
+      issues.push(issue(RULE_ERROR_CODES.INVALID, `entities[${index}]`, `实体 key「${entity.key}」重复`, 'error', '实体 key 必须在单份本体文档内唯一'))
+    }
+    seenKeys.add(entity.key)
+    entityByKey.set(entity.key, entity)
+    if (entity.unit) {
+      const unitIssue = entityUnitIssue(entity)
+      if (unitIssue) issues.push(unitIssue)
+    }
+    if (entity.kind === 'process_variable' || entity.kind === 'quality_variable') {
+      if (!entity.role) {
+        issues.push(issue(RULE_ERROR_CODES.ROLE_UNRESOLVED, `entities[${entity.key}]`,
+          `变量实体「${entity.key}」缺少 role`, 'warning',
+          '缺 role 时无法参与 bound/rate 规则编译(编译器会拒绝);建议补 control/target/disturbance/feature/state/guard/observation'))
+      }
+    }
+  })
+
+  // ---- 关系 ----
+  const relationIds = new Set<string>()
+  const relationTriples = new Set<string>()
+  doc.relations.forEach((rel, index) => {
+    const path = `relations[${index}]`
+    if (relationIds.has(rel.id)) issues.push(issue(RULE_ERROR_CODES.INVALID, path, `关系 id「${rel.id}」重复`))
+    relationIds.add(rel.id)
+    const triple = `${rel.srcKey}|${rel.dstKey}|${rel.kind}`
+    if (relationTriples.has(triple)) {
+      issues.push(issue(RULE_ERROR_CODES.INVALID, path, `关系重复(${rel.srcKey} -${rel.kind}-> ${rel.dstKey})`))
+    }
+    relationTriples.add(triple)
+    if (rel.srcKey === rel.dstKey) {
+      issues.push(issue(RULE_ERROR_CODES.INVALID, path, `关系 ${rel.id} 自引用(src 与 dst 相同)`, 'warning'))
+    }
+    if (!entityByKey.has(rel.srcKey)) {
+      issues.push(issue(RULE_ERROR_CODES.UNKNOWN_ENTITY, path, `关系 ${rel.id} 的 srcKey「${rel.srcKey}」不存在`, 'error', '先在 entities 里定义该实体'))
+    }
+    if (!entityByKey.has(rel.dstKey)) {
+      issues.push(issue(RULE_ERROR_CODES.UNKNOWN_ENTITY, path, `关系 ${rel.id} 的 dstKey「${rel.dstKey}」不存在`, 'error', '先在 entities 里定义该实体'))
+    }
+    const tier = rel.properties.evidenceTier
+    const declaredMax = maxEvidenceLevel(rel.evidence.map(e => e.level))
+    if (rel.evidence.length > 0 && evidenceLevelRank(tier) > evidenceLevelRank(declaredMax)) {
+      issues.push(issue(RULE_ERROR_CODES.EVIDENCE_INSUFFICIENT, path,
+        `关系 ${rel.id} 声明证据档 ${tier} 高于其证据最高级别 ${declaredMax || '无'}`,
+        'error', '补足对应级别证据,或下调 evidenceTier'))
+    }
+    if ((rel.properties.gainPerUnit !== undefined || rel.properties.lagMs !== undefined) && tier !== 'validated_control') {
+      issues.push(issue(RULE_ERROR_CODES.EVIDENCE_INSUFFICIENT, path,
+        `关系 ${rel.id} 携带增益/时滞,但证据档为 ${tier}`,
+        'error', '增益与时滞只能来自受控验证(validated_control:run+crosscheck+outcome);否则请留空,仅作候选影响'))
+    }
+  })
+
+  // ---- 规则 ----
+  const ruleIds = new Set<string>()
+  const ruleKeys = new Set<string>()
+  doc.rules.forEach((rule, index) => {
+    const path = `rules[${index}]`
+    if (ruleIds.has(rule.id)) issues.push(issue(RULE_ERROR_CODES.INVALID, path, `规则 id「${rule.id}」重复`))
+    ruleIds.add(rule.id)
+    if (ruleKeys.has(rule.key)) issues.push(issue(RULE_ERROR_CODES.INVALID, path, `规则 key「${rule.key}」重复`))
+    ruleKeys.add(rule.key)
+    if (rule.kind !== rule.dsl.type) {
+      issues.push(issue(RULE_ERROR_CODES.INVALID, path,
+        `规则 ${rule.id} 的 kind(${rule.kind}) 与 dsl.type(${rule.dsl.type}) 不一致`,
+        'error', 'kind 决定编译形态,必须与 DSL 形态一致'))
+    }
+    for (const ref of ruleVariableRefs(rule)) {
+      if (!entityByKey.has(ref)) {
+        issues.push(issue(RULE_ERROR_CODES.UNKNOWN_ENTITY, path,
+          `规则 ${rule.id} 引用的实体「${ref}」不存在`, 'error', '先定义实体,或改用语义绑定后的平台变量', rule.id))
+      }
+    }
+    const level = ruleEvidenceLevel(rule)
+    // 硬约束只约束「数值强制」形态(bound/rate/nonlinear);state_condition 与 interlock
+    // 分别落运行时守卫 / PLC 解释层,不改变数值可行域,因此不要求 validated_control。
+    const numericHard = rule.constraintLevel === 'hard' && (rule.dsl.type === 'bound' || rule.dsl.type === 'rate' || rule.dsl.type === 'nonlinear')
+    if (numericHard && level !== 'validated_control') {
+      issues.push(issue(RULE_ERROR_CODES.EVIDENCE_INSUFFICIENT, path,
+        `规则 ${rule.id} 要求硬约束,但证据最高级别为 ${level || '无'}`,
+        'error', '硬约束只接受 validated_control(run+crosscheck+outcome);否则降为 soft 或改为 guard', rule.id))
+    }
+    if (rule.dsl.type === 'bound' && rule.dsl.min !== undefined && rule.dsl.max !== undefined && rule.dsl.min > rule.dsl.max) {
+      issues.push(issue(RULE_ERROR_CODES.RULE_CONFLICT, path,
+        `规则 ${rule.id} 的界区间为空(min ${rule.dsl.min} > max ${rule.dsl.max})`, 'error', '检查上下限是否写反', rule.id))
+    }
+    if (rule.dsl.type === 'nonlinear') {
+      // 简单阈值形态可由运行时守卫执行;复杂表达式需后端支持
+      const simple = /^\s*[a-z][a-z0-9_.]*\s*(<=|>=|<|>|==|!=)\s*-?\d+(?:\.\d+)?\s*$/.test(rule.dsl.expression)
+      if (!simple) {
+        issues.push(issue(RULE_ERROR_CODES.UNSUPPORTED_FORM, path,
+          `规则 ${rule.id} 的非线性表达式无法由运行时守卫执行`,
+          'warning', '建议改写为「变量 比较 阈值」形式,或落到 PhysicsSpec 由求解器/孪生后端支持', rule.id))
+      }
+    }
+  })
+
+  // ---- 语义绑定(草稿期) ----
+  const bindingIds = new Set<string>()
+  const bindingTriples = new Set<string>()
+  doc.bindings.forEach((binding, index) => {
+    const path = `bindings[${index}]`
+    if (bindingIds.has(binding.id)) issues.push(issue(RULE_ERROR_CODES.INVALID, path, `绑定 id「${binding.id}」重复`))
+    bindingIds.add(binding.id)
+    const triple = `${binding.entityKey}|${binding.platformKind}|${binding.platformId}`
+    if (bindingTriples.has(triple)) {
+      issues.push(issue(RULE_ERROR_CODES.INVALID, path, `绑定重复(实体 ${binding.entityKey} → ${binding.platformKind}:${binding.platformId})`))
+    }
+    bindingTriples.add(triple)
+    const entity = entityByKey.get(binding.entityKey)
+    if (!entity) {
+      issues.push(issue(RULE_ERROR_CODES.UNKNOWN_ENTITY, path, `绑定 ${binding.id} 的实体「${binding.entityKey}」不存在`))
+      return
+    }
+    if (entity.unit && binding.unitDeclared && !unitsCompatible(entity.unit, binding.unitDeclared)) {
+      issues.push(issue(RULE_ERROR_CODES.UNIT_MISMATCH, path,
+        `绑定 ${binding.id} 的声明单位「${binding.unitDeclared}」与实体「${entity.key}」单位「${entity.unit}」量纲不相容`))
+    }
+    if (binding.unitDeclared && binding.unitTarget && !unitsCompatible(binding.unitDeclared, binding.unitTarget)) {
+      issues.push(issue(RULE_ERROR_CODES.UNIT_MISMATCH, path,
+        `绑定 ${binding.id} 的单位「${binding.unitDeclared}」与目标单位「${binding.unitTarget}」量纲不相容`))
+    }
+    if (!Number.isFinite(binding.scale) || binding.scale === 0) {
+      issues.push(issue(RULE_ERROR_CODES.INVALID, path, `绑定 ${binding.id} 的 scale 必须为非零有限数(禁止兜底)`))
+    }
+    if (binding.platformKind === 'daq_node' && binding.direction !== 'read') {
+      issues.push(issue(RULE_ERROR_CODES.INVALID, path,
+        `绑定 ${binding.id} 把数采节点声明为 ${binding.direction}`, 'warning',
+        '平台数采节点通常是只读通道;写入应绑定 dcw_node 或 recipe_param(活体校验会拒绝)'))
+    }
+  })
+
+  const byState: Record<string, number> = {}
+  for (const state of ONTOLOGY_STATES) byState[state] = 0
+  for (const rule of doc.rules) byState[rule.status] = (byState[rule.status] ?? 0) + 1
+  const byEvidence: Record<string, number> = { candidate_influence: 0, observed_correlation: 0, validated_control: 0 }
+  for (const rule of doc.rules) {
+    const level = ruleEvidenceLevel(rule)
+    if (level) byEvidence[level] = (byEvidence[level] ?? 0) + 1
+  }
+
+  return {
+    ok: !issues.some(i => i.severity === 'error'),
+    issues,
+    stats: {
+      entities: doc.entities.length,
+      relations: doc.relations.length,
+      rules: doc.rules.length,
+      bindings: doc.bindings.length,
+      byState,
+      byEvidence,
+    },
+  }
+}

package/server/services/workshop/optimization/binding.repo.ts

@@ -111,6 +111,13 @@ export function createBindingRepo(db: DatabaseSync) {
       return row?.revision ?? 0
     },
 
+    /** 模型采纳重绑:绑定升到新 Profile 版本并 bump revision(在飞求解 BINDING_STALE 收敛)。 */
+    rebindVersion(id: string, toVersion: number): number {
+      const r = db.prepare('UPDATE optimizer_bindings SET profile_version = ?, revision = revision + 1, valid_from = ?, updated_at = ? WHERE id = ?')
+        .run(toVersion, new Date().toISOString(), new Date().toISOString(), id)
+      return Number(r.changes)
+    },
+
     removeByAgent(channelAgentId: string): number {
       const r = db.prepare('DELETE FROM optimizer_bindings WHERE channel_agent_id = ?').run(channelAgentId)
       return Number(r.changes)

package/server/services/workshop/optimization/contracts.ts

@@ -59,6 +59,8 @@ export interface OptimizationProfile {
   id: string
   version: number
   name?: string
+  /** 人读描述:这个求解器配置代表什么工况/目标(Agent 可写,UI 展示) */
+  description?: string
   modelRef: ModelRef
   problemTemplateRef: ProblemTemplateRef
   problemConfig: ProblemConfig
@@ -72,9 +74,23 @@ export interface OptimizationProfile {
   ownerUserId?: string
   /** 发布时冻结的问题结构 hash */
   problemIrHash?: string
+  /**
+   * 本体引用摘要(发布时冻结):**进 profileContentHash,绝不进 problemIrHash**。
+   * 漂移比对走独立校验(ONTOLOGY_PACK_DRIFTED),避免本体演化把旧 Profile
+   * 全部打成 PROBLEM_IR_CHANGED(与 D1/D12 同因)。
+   */
+  ontologyRefs?: OntologyRefSummary[]
   createdAt?: string
 }
 
+export interface OntologyRefSummary {
+  ontologyId: string
+  ontologyVersion: number
+  contentHash?: string
+  rulePackHash?: string
+  guardCount?: number
+}
+
 export function assertProfileSolverCompatible(profile: Pick<OptimizationProfile, 'solverRef' | 'modelRef' | 'problemTemplateRef'>): void {
   assertSolverSupportsArtifact(profile.solverRef, profile.modelRef.artifactKind, `profile model=${profile.modelRef.modelId}`)
   if (profile.solverRef === 'osqp_mpc@1' && profile.problemTemplateRef !== 'linear_mpc_quadratic@1') {