agentworkshop 0.7.71 → 0.8.1

package/server/api/workshop/ontology/drafts/[draftId]/compile.ts

@@ -0,0 +1,39 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/compile — 编译预览(四类产物 + Rule Trace;不落库)
+ *
+ * body.currentBounds 可选(现行权威界):提供时强制「只收紧」。
+ * body.approvedOnly 可选:true 时模拟发布路径(未获批硬约束将被拒)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, compileDraft } from '@/server/services/workshop/ontology/ontology.service'
+import type { CompileOptions } from '@/server/services/workshop/ontology/contracts'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const currentBounds = body.currentBounds as CompileOptions['currentBounds'] | undefined
+  const preview = compileDraft(draftId, actorFromUser(user), {
+    approvedOnly: body.approvedOnly === true,
+    currentBounds,
+  })
+  return {
+    status: preview.result.status,
+    contentHash: preview.contentHash,
+    packHash: preview.packHash,
+    rulePackHash: preview.result.rulePackHash,
+    counts: {
+      compiled: preview.result.compiledCount,
+      guard: preview.result.guardCount,
+      explained: preview.result.explainedCount,
+      rejected: preview.result.rejectedCount,
+    },
+    artifacts: preview.result.artifacts,
+    traces: preview.result.traces,
+    issues: preview.result.issues,
+  }
+})

package/server/api/workshop/ontology/drafts/[draftId]/evidence.ts

@@ -0,0 +1,33 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/evidence — 登记证据(追加账本 + 写回草稿)
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, appendEvidence } from '@/server/services/workshop/ontology/ontology.service'
+
+const TARGET_KINDS = new Set(['entity', 'relation', 'rule', 'binding'])
+const LEVELS = new Set(['candidate_influence', 'observed_correlation', 'validated_control'])
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const targetKind = String(body.targetKind ?? '')
+  const level = String(body.level ?? '')
+  if (!TARGET_KINDS.has(targetKind)) throw new AppError(422, 'EVIDENCE_TARGET_INVALID', `targetKind 必须是 entity|relation|rule|binding(收到 ${targetKind})`)
+  if (!LEVELS.has(level)) throw new AppError(422, 'EVIDENCE_LEVEL_INVALID', `level 必须是 candidate_influence|observed_correlation|validated_control(收到 ${level})`)
+  const source = body.source
+  if (!source || typeof source !== 'object') throw new AppError(422, 'EVIDENCE_SOURCE_REQUIRED', 'source 必填(如 {type:"dataset_stats",datasetId,sha256})')
+  const detail = appendEvidence(draftId, actorFromUser(user), {
+    targetKind: targetKind as 'entity' | 'relation' | 'rule' | 'binding',
+    targetKey: String(body.targetKey ?? ''),
+    level: level as 'candidate_influence' | 'observed_correlation' | 'validated_control',
+    source: source as Parameters<typeof appendEvidence>[2]['source'],
+    sourceRef: typeof body.sourceRef === 'string' ? body.sourceRef : undefined,
+    note: typeof body.note === 'string' ? body.note : undefined,
+  })
+  return { draft: { id: detail.draft.id, rev: detail.draft.rev }, validation: detail.validation }
+})

package/server/api/workshop/ontology/drafts/[draftId]/publish.ts

@@ -0,0 +1,44 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/publish — 冻结为不可变版本(仅 admin)
+ *
+ * body.currentBounds 可选(提供时编译期强制「只收紧」)。
+ * 失败语义:422 VALIDATION_BLOCKED / ONTOLOGY_BINDING_INVALID / ONTOLOGY_NOT_APPROVED;
+ *           409 ONTOLOGY_VERSION_CONFLICT(并发发布)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireAdmin } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, getDraft, publishDraft } from '@/server/services/workshop/ontology/ontology.service'
+import type { CompileOptions } from '@/server/services/workshop/ontology/contracts'
+import { recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireAdmin(event)
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const result = publishDraft(draftId, actorFromUser(user), {
+    currentBounds: body.currentBounds as CompileOptions['currentBounds'] | undefined,
+  })
+  const draft = getDraft(draftId)
+  recordConfigAction(user, 'ontology.publish', { kind: 'ontology_version', id: `${result.version.id}@${result.version.version}` },
+    `发布本体 ${result.version.id}@${result.version.version}(编译 ${result.compile.compiledCount} / 守卫 ${result.compile.guardCount})`,
+    { ontologyId: result.version.id, version: result.version.version, packHash: result.packHash, revision: draft.rev })
+  return {
+    version: {
+      id: result.version.id, version: result.version.version, status: result.version.status,
+      contentHash: result.version.contentHash, parentVersion: result.version.parentVersion,
+      lineId: result.version.lineId, createdAt: result.version.createdAt,
+    },
+    packHash: result.packHash,
+    counts: {
+      compiled: result.compile.compiledCount,
+      guard: result.compile.guardCount,
+      explained: result.compile.explainedCount,
+      rejected: result.compile.rejectedCount,
+    },
+    issues: result.compile.issues,
+    draftRev: result.draft.rev,
+  }
+})

package/server/api/workshop/ontology/drafts/[draftId]/rules/[ruleId]/approval-decision.ts

@@ -0,0 +1,28 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/rules/:ruleId/approval-decision — 裁决批准申请
+ * body: { approvalId, approved, comment? }
+ *
+ * 自审禁止:起草人不能裁决自己的申请(单管理员实例由服务层打 solo_operator 豁免)。
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, decideRuleApproval } from '@/server/services/workshop/ontology/ontology.service'
+import { recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const approvalId = String(body.approvalId ?? '')
+  if (!approvalId) throw new AppError(422, 'APPROVAL_ID_REQUIRED', 'approvalId 必填')
+  const result = decideRuleApproval(draftId, approvalId, actorFromUser(user), {
+    approved: body.approved === true,
+    comment: typeof body.comment === 'string' ? body.comment : undefined,
+  })
+  recordConfigAction(user, 'ontology.rule.decide', { kind: 'ontology_approval', id: approvalId },
+    `裁决本体规则批准 ${approvalId}:${result.decision}`)
+  return result
+})

package/server/api/workshop/ontology/drafts/[draftId]/rules/[ruleId]/approval.ts

@@ -0,0 +1,17 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/rules/:ruleId/approval — 申请控制级批准(第二人裁决)
+ * 返回 { approvalId };后续 POST /api/workshop/ontology/approvals/:approvalId/decide。
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, requestRuleApproval } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  const ruleId = getRouterParam(event, 'ruleId') ?? ''
+  if (!draftId || !ruleId) throw new AppError(422, 'RULE_ID_REQUIRED', 'draftId/ruleId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  return requestRuleApproval(draftId, ruleId, actorFromUser(user))
+})

package/server/api/workshop/ontology/drafts/[draftId]/rules/[ruleId]/transition.ts

@@ -0,0 +1,32 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/rules/:ruleId/transition — 规则状态迁移
+ * body: { to, approvalId?, comment? }
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { ONTOLOGY_STATES, type OntologyState } from '@/server/services/workshop/ontology/contracts'
+import { actorFromUser, transitionRule } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  const ruleId = getRouterParam(event, 'ruleId') ?? ''
+  if (!draftId || !ruleId) throw new AppError(422, 'RULE_ID_REQUIRED', 'draftId/ruleId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const to = String(body.to ?? '') as OntologyState
+  if (!(ONTOLOGY_STATES as readonly string[]).includes(to)) {
+    throw new AppError(422, 'RULE_STATE_INVALID', `to 必须是 ${ONTOLOGY_STATES.join('|')}(收到 ${to})`)
+  }
+  const detail = transitionRule(draftId, ruleId, actorFromUser(user), {
+    to,
+    approvalId: typeof body.approvalId === 'string' ? body.approvalId : undefined,
+    comment: typeof body.comment === 'string' ? body.comment : undefined,
+  })
+  return {
+    draft: { id: detail.draft.id, rev: detail.draft.rev },
+    rule: detail.doc.rules.find(r => r.id === ruleId || r.key === ruleId),
+    validation: detail.validation,
+  }
+})

package/server/api/workshop/ontology/drafts/[draftId]/subgraph.ts

@@ -0,0 +1,24 @@
+/**
+ * GET /api/workshop/ontology/drafts/:draftId/subgraph?entity=&hops=&direction=&kinds=&limit=
+ *
+ * 草稿子图(供 /ontology 页面:图、表格与抽屉同源,不会出现「图画草稿、抽屉查已发布」的错位)。
+ * 只读;沿用草稿的属主/管理员访问规则(getDraftDetail 内部裁决)。
+ */
+import { getQuery, getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, getDraftDetail } from '@/server/services/workshop/ontology/ontology.service'
+import { parseSubgraphOptions } from '@/server/services/workshop/ontology/subgraph.core'
+import { requireEntityKey, subgraphAroundDoc } from '@/server/services/workshop/ontology/subgraph.service'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = resolveUser(event)
+  const query = getQuery(event)
+  const entityKey = requireEntityKey(query.entity)
+  const opts = parseSubgraphOptions(query)
+  const detail = getDraftDetail(draftId, actorFromUser(user))
+  return { draftId, subgraph: subgraphAroundDoc(detail.doc, entityKey, opts) }
+})

package/server/api/workshop/ontology/drafts/[draftId]/validate.ts

@@ -0,0 +1,16 @@
+/**
+ * POST /api/workshop/ontology/drafts/:draftId/validate — 全量校验(结构+活体绑定)
+ */
+import { getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, validateDraft } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const user = requireRole(event, ['admin', 'editor'])
+  const report = validateDraft(draftId, actorFromUser(user))
+  return report
+})

package/server/api/workshop/ontology/drafts/[draftId].ts

@@ -0,0 +1,52 @@
+/**
+ * GET    /api/workshop/ontology/drafts/:draftId — 草稿详情(含校验与绑定报告)
+ * PATCH  /api/workshop/ontology/drafts/:draftId — 保存整份文档(乐观锁 rev)
+ * DELETE /api/workshop/ontology/drafts/:draftId — 删除草稿
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole, resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import {
+  actorFromUser, deleteDraft, getDraftDetail, updateDraft,
+} from '@/server/services/workshop/ontology/ontology.service'
+import { recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const draftId = getRouterParam(event, 'draftId') ?? ''
+  if (!draftId) throw new AppError(422, 'DRAFT_ID_REQUIRED', 'draftId 缺失')
+  const method = event.method?.toUpperCase() ?? 'GET'
+
+  if (method === 'GET') {
+    const detail = getDraftDetail(draftId, actorFromUser(resolveUser(event)))
+    return {
+      draft: { id: detail.draft.id, ontologyId: detail.draft.ontologyId, baseVersion: detail.draft.baseVersion, rev: detail.draft.rev, ownerUserId: detail.draft.ownerUserId },
+      doc: detail.doc,
+      validation: detail.validation,
+      bindings: detail.bindings,
+    }
+  }
+
+  const user = requireRole(event, ['admin', 'editor'])
+  if (method === 'DELETE') {
+    deleteDraft(draftId, actorFromUser(user))
+    recordConfigAction(user, 'ontology.draft.delete', { kind: 'ontology_draft', id: draftId }, `删除本体草稿 ${draftId}`)
+    return { deleted: true }
+  }
+
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const expectedRev = Number(body.expectedRev)
+  if (!Number.isInteger(expectedRev)) throw new AppError(422, 'DRAFT_REV_REQUIRED', 'expectedRev 必填(乐观锁;取 GET 返回的 draft.rev)')
+  const detail = updateDraft(draftId, actorFromUser(user), {
+    doc: body.doc,
+    expectedRev,
+    strictBindings: body.strictBindings !== false,
+  })
+  recordConfigAction(user, 'ontology.draft.update', { kind: 'ontology_draft', id: draftId },
+    `保存本体草稿 ${draftId}(rev=${detail.draft.rev})`, { rev: detail.draft.rev, ontologyId: detail.draft.ontologyId })
+  return {
+    draft: { id: detail.draft.id, rev: detail.draft.rev, ontologyId: detail.draft.ontologyId },
+    validation: detail.validation,
+    bindings: detail.bindings,
+  }
+})

package/server/api/workshop/ontology/drafts/index.ts

@@ -0,0 +1,20 @@
+/**
+ * GET /api/workshop/ontology/drafts?ontologyId= — 我的(admin=全部)草稿列表
+ */
+import { getQuery } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { actorFromUser, listDrafts } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  const user = resolveUser(event)
+  const query = getQuery(event)
+  const ontologyId = typeof query.ontologyId === 'string' && query.ontologyId ? query.ontologyId : undefined
+  const drafts = listDrafts(actorFromUser(user), ontologyId ? { ontologyId } : {})
+  return {
+    drafts: drafts.map(d => ({
+      id: d.id, ontologyId: d.ontologyId, baseVersion: d.baseVersion, rev: d.rev,
+      ownerUserId: d.ownerUserId, createdAt: d.createdAt, updatedAt: d.updatedAt,
+    })),
+  }
+})

package/server/api/workshop/ontology/export/[ontologyId].ts

@@ -0,0 +1,50 @@
+/**
+ * GET /api/workshop/ontology/export/:ontologyId?version= — 导出发布快照(JSON bundle)
+ *
+ * 只读导出:供外部评审/互操作与 P1 RDF 导出的输入。
+ */
+import { getQuery, getRouterParam, setResponseHeader } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { getOntologyRepo } from '@/server/services/workshop/ontology/repo'
+import { getVersion } from '@/server/services/workshop/ontology/ontology.service'
+
+function parseCompiled(raw: string): unknown {
+  try {
+    return JSON.parse(raw || '{}') as unknown
+  }
+  catch {
+    return null
+  }
+}
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const ontologyId = getRouterParam(event, 'ontologyId') ?? ''
+  if (!ontologyId) throw new AppError(422, 'ONTOLOGY_ID_REQUIRED', 'ontologyId 缺失')
+  const query = getQuery(event)
+  const requested = query.version !== undefined ? Number(query.version) : undefined
+  const repo = getOntologyRepo()
+  const latest = Number.isInteger(requested) ? requested! : (repo.latestVersion(ontologyId, 'published')?.version ?? 0)
+  if (!latest) throw new AppError(404, 'VERSION_NOT_FOUND', `本体 ${ontologyId} 还没有已发布版本`)
+  const version = getVersion(ontologyId, latest)
+  const bundle = {
+    schemaVersion: 1,
+    ontologyId,
+    version: version.version,
+    status: version.status,
+    lineId: version.lineId,
+    contentHash: version.contentHash,
+    parentVersion: version.parentVersion,
+    createdAt: version.createdAt,
+    entities: repo.listEntities(version.id, version.version),
+    relations: repo.listRelations(version.id, version.version),
+    rules: repo.listRules(version.id, version.version),
+    bindings: repo.listBindings(version.id, version.version),
+    traces: repo.listTraces(version.id, version.version),
+    compiled: parseCompiled(version.compiledJson),
+  }
+  setResponseHeader(event, 'content-disposition', `attachment; filename="${ontologyId}-v${version.version}.json"`)
+  return bundle
+})

package/server/api/workshop/ontology/index.ts

@@ -0,0 +1,38 @@
+/**
+ * GET  /api/workshop/ontology — 本体清单(按产线过滤)+ 我的草稿概览
+ * POST /api/workshop/ontology — 创建草稿(单活跃 409)
+ */
+import { getQuery, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireRole, resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, createDraft, listDrafts, listOntologies } from '@/server/services/workshop/ontology/ontology.service'
+import { recordConfigAction } from '@/server/services/workshop/optimization/access'
+
+export default defineApiHandler(async (event) => {
+  const method = event.method?.toUpperCase() ?? 'GET'
+  if (method === 'GET') {
+    const user = resolveUser(event)
+    const query = getQuery(event)
+    const lineId = typeof query.lineId === 'string' && query.lineId ? query.lineId : undefined
+    const ontologies = listOntologies(lineId)
+    const drafts = listDrafts(actorFromUser(user), typeof query.ontologyId === 'string' ? { ontologyId: query.ontologyId } : {})
+    return {
+      ontologies,
+      drafts: drafts.map(d => ({ id: d.id, ontologyId: d.ontologyId, baseVersion: d.baseVersion, rev: d.rev, ownerUserId: d.ownerUserId, updatedAt: d.updatedAt })),
+    }
+  }
+  const user = requireRole(event, ['admin', 'editor'])
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const ontologyId = String(body.ontologyId ?? '').trim()
+  if (!ontologyId) throw new AppError(422, 'ONTOLOGY_ID_REQUIRED', 'ontologyId 必填(形如 ont-pva-line01)')
+  const draft = createDraft(actorFromUser(user), {
+    ontologyId,
+    lineId: typeof body.lineId === 'string' ? body.lineId : '',
+    name: typeof body.name === 'string' ? body.name : undefined,
+    cloneFromVersion: body.cloneFromVersion === true,
+  })
+  recordConfigAction(user, 'ontology.draft.create', { kind: 'ontology_draft', id: draft.id },
+    `创建本体草稿 ${draft.id}(${draft.ontologyId})`, { ontologyId: draft.ontologyId })
+  return { draft: { id: draft.id, ontologyId: draft.ontologyId, rev: draft.rev, baseVersion: draft.baseVersion } }
+})

package/server/api/workshop/ontology/scene.ts

@@ -0,0 +1,34 @@
+/**
+ * GET /api/workshop/ontology/scene?lineId= — 运行时语义子图(绑定面实体 + 关系 + 规则决策 + 守卫)
+ * GET /api/workshop/ontology/scene?lineId=&entity=&hops=&direction=&kinds=&limit= — 以实体为中心的邻接/多跳子图
+ *
+ * 这是 Agent 上下文与 MCP 只读工具的共同数据面;只读、只回已发布版本。
+ * 两个模式互不干扰:未给 entity 时行为与历史完全一致(全图);给了 entity 才走子图并校验新参数。
+ */
+import { getQuery } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { sceneSubgraph } from '@/server/services/workshop/ontology/ontology.service'
+import { parseSubgraphOptions } from '@/server/services/workshop/ontology/subgraph.core'
+import { requireEntityKey, subgraphAroundForLine } from '@/server/services/workshop/ontology/subgraph.service'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const query = getQuery(event)
+  const lineId = typeof query.lineId === 'string' ? query.lineId : ''
+  if (!lineId) throw new AppError(422, 'LINE_REQUIRED', 'lineId 必填')
+
+  // 子图模式:仅显式给出 entity 时启用,旧调用零漂移
+  if (query.entity !== undefined) {
+    const entityKey = requireEntityKey(query.entity)
+    const opts = parseSubgraphOptions(query)
+    const subgraph = subgraphAroundForLine(lineId, entityKey, opts)
+    if (!subgraph) return { lineId, active: false, subgraph: null }
+    return { lineId, active: true, subgraph }
+  }
+
+  const graph = sceneSubgraph(lineId, { limit: query.limit !== undefined ? Math.min(500, Math.max(1, Number(query.limit))) : 200 })
+  if (!graph) return { lineId, active: false, graph: null }
+  return { lineId, active: true, graph }
+})

package/server/api/workshop/ontology/traces/[ontologyId].ts

@@ -0,0 +1,19 @@
+/**
+ * GET /api/workshop/ontology/traces/:ontologyId?version=&ruleId= — 规则溯源(Rule Trace)
+ */
+import { getQuery, getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { getOntologyRepo } from '@/server/services/workshop/ontology/repo'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const ontologyId = getRouterParam(event, 'ontologyId') ?? ''
+  if (!ontologyId) throw new AppError(422, 'ONTOLOGY_ID_REQUIRED', 'ontologyId 缺失')
+  const query = getQuery(event)
+  const version = query.version !== undefined ? Number(query.version) : undefined
+  const ruleId = typeof query.ruleId === 'string' && query.ruleId ? query.ruleId : undefined
+  const traces = getOntologyRepo().listTraces(ontologyId, Number.isInteger(version) ? version : undefined)
+  return { ontologyId, traces: ruleId ? traces.filter(t => t.ruleId === ruleId) : traces }
+})

package/server/api/workshop/ontology/versions/[ontologyId]/compare.ts

@@ -0,0 +1,21 @@
+/**
+ * GET /api/workshop/ontology/versions/:ontologyId/compare?from=&to= — 版本差异(实体/关系/规则/绑定四段)
+ */
+import { getQuery, getRouterParam } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { compareVersions } from '@/server/services/workshop/ontology/ontology.service'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const ontologyId = getRouterParam(event, 'ontologyId') ?? ''
+  if (!ontologyId) throw new AppError(422, 'ONTOLOGY_ID_REQUIRED', 'ontologyId 缺失')
+  const query = getQuery(event)
+  const from = Number(query.from)
+  const to = Number(query.to)
+  if (!Number.isInteger(from) || !Number.isInteger(to)) {
+    throw new AppError(422, 'VERSION_REQUIRED', 'from/to 必须是整数版本号')
+  }
+  return compareVersions(ontologyId, from, to)
+})

package/server/api/workshop/ontology/versions/[ontologyId].ts

@@ -0,0 +1,42 @@
+/**
+ * GET  /api/workshop/ontology/versions/:ontologyId — 版本史
+ * POST /api/workshop/ontology/versions/:ontologyId — 退役某版本(body {version})
+ */
+import { getRouterParam, readBody } from 'h3'
+import { defineApiHandler } from '@/server/utils/response'
+import { requireAdmin, resolveUser } from '@/server/api/workshop/caller'
+import { AppError } from '@/server/utils/errors'
+import { actorFromUser, listVersions, retireVersion } from '@/server/services/workshop/ontology/ontology.service'
+
+function parseCompiled(raw: string): { counts?: unknown, packHash?: string } {
+  try {
+    return JSON.parse(raw || '{}') as { counts?: unknown, packHash?: string }
+  }
+  catch {
+    return {}
+  }
+}
+
+export default defineApiHandler(async (event) => {
+  const ontologyId = getRouterParam(event, 'ontologyId') ?? ''
+  if (!ontologyId) throw new AppError(422, 'ONTOLOGY_ID_REQUIRED', 'ontologyId 缺失')
+  const method = event.method?.toUpperCase() ?? 'GET'
+  if (method === 'GET') {
+    resolveUser(event)
+    return {
+      ontologyId,
+      versions: listVersions(ontologyId).map(v => ({
+        version: v.version, status: v.status, name: v.name, lineId: v.lineId,
+        parentVersion: v.parentVersion, contentHash: v.contentHash,
+        publishedBy: v.publishedBy, createdAt: v.createdAt,
+        compiled: parseCompiled(v.compiledJson),
+      })),
+    }
+  }
+  const user = requireAdmin(event)
+  const body = await readBody<Record<string, unknown>>(event) ?? {}
+  const version = Number(body.version)
+  if (!Number.isInteger(version)) throw new AppError(422, 'VERSION_REQUIRED', 'version 必填(整数)')
+  retireVersion(ontologyId, version, actorFromUser(user))
+  return { ontologyId, version, status: 'retired' }
+})