agentworkshop 0.7.71 → 0.8.1

package/server/services/workshop/agents/industrial/grant-guard.ts

@@ -32,6 +32,15 @@ const WRITE_TOOLS = new Set([
   // 产线管理面(启停直接改物理状态与批次窗口)
   'line_start',
   'line_stop',
+  // 模型采纳(OW-adopt):改变求解器运行的模型工件(控制面写向,HITL 卡裁决)
+  'optimizer_profile_propose',
+  // 本体(ONT):知识起草与发布提议属产线域写向动作(不写设备,但会改变控制侧知识来源)
+  'ontology_draft_create',
+  'ontology_draft_update',
+  'ontology_draft_autofix',
+  'ontology_publish_propose',
+  // AML 模型人读身份(名称/描述)维护:写元数据,不触达产线设备
+  'aml_model_annotate',
 ])
 
 /** 无需复核的纯协作/管理面工具(不触达产线数据) */
@@ -42,6 +51,15 @@ const GRANT_EXEMPT = new Set([
   'exp_collect',
 ])
 
+function draftLineId(draftJson: string): string {
+  try {
+    return (JSON.parse(draftJson || '{}') as { lineId?: string }).lineId ?? ''
+  }
+  catch {
+    return ''
+  }
+}
+
 interface GuardIdentity {
   agentId: string
   channelId: string
@@ -77,6 +95,61 @@ async function resolveTargetLines(agentId: string, toolName: string, args: Recor
     const l = await nodeIdLine(id)
     if (l) lines.add(l)
   }
+  // 本体草稿 → 授权锚产线(草稿 doc.lineId;空则取该本体最近版本的 lineId)。
+  // 缺口修复(计划 ONT-13):draft_id 不在原解析面时 lineSet 为空会直接放行 operate 判定。
+  const draftId = one(args.draft_id ?? args.draftId)
+  if (draftId) {
+    const { getAmlRuntime } = await import('@/server/services/workshop/aml/runtime')
+    const db = getAmlRuntime().db
+    const row = db.prepare('SELECT ontology_id AS ontologyId, draft_json AS draftJson FROM ontology_drafts WHERE id = ?').get(draftId) as
+      { ontologyId?: string, draftJson?: string } | undefined
+    if (row) {
+      let lineId = draftLineId(row.draftJson ?? '')
+      if (!lineId && row.ontologyId) {
+        const v = db.prepare('SELECT line_id AS lineId FROM ontology_versions WHERE id = ? ORDER BY version DESC LIMIT 1').get(row.ontologyId) as { lineId?: string } | undefined
+        lineId = v?.lineId ?? ''
+      }
+      if (lineId) lines.add(lineId)
+    }
+  }
+  // 模型采纳:profile_id → 该 Agent 对该 Profile 绑定所在产线(经 profile→spec)
+  const adoptProfileId = one(args.profile_id)
+  if (adoptProfileId) {
+    const { getAmlRuntime } = await import('@/server/services/workshop/aml/runtime')
+    const db = getAmlRuntime().db
+    const b = db.prepare('SELECT id FROM optimizer_bindings WHERE channel_agent_id = ? AND profile_id = ? LIMIT 1').get(agentId, adoptProfileId) as { id?: string } | undefined
+    const bindingId2 = b?.id ?? ''
+    if (bindingId2) {
+      const prof = db.prepare('SELECT process_spec_ref AS specRef FROM optimizer_profiles WHERE id = ? ORDER BY version DESC LIMIT 1').get(adoptProfileId) as { specRef?: string } | undefined
+      const [specId] = (prof?.specRef ?? '').split('@')
+      if (specId) {
+        const spec = db.prepare('SELECT line_id AS lineId FROM process_model_specs WHERE id = ?').get(specId) as { lineId?: string } | undefined
+        if (spec?.lineId) lines.add(spec.lineId)
+      }
+    }
+  }
+  // AML 模型 → 数据集所属产线(model_id 元数据写/引用面)
+  const modelIdArg = one(args.model_id ?? args.modelId)
+  if (modelIdArg) {
+    const { getAmlRuntime } = await import('@/server/services/workshop/aml/runtime')
+    const db = getAmlRuntime().db
+    const m = db.prepare('SELECT dataset_id AS datasetId FROM aml_models WHERE id = ?').get(modelIdArg) as { datasetId?: string } | undefined
+    if (m?.datasetId) {
+      const d = db.prepare('SELECT line_id AS lineId FROM aml_datasets WHERE id = ?').get(m.datasetId) as { lineId?: string } | undefined
+      if (d?.lineId) lines.add(d.lineId)
+    }
+  }
+  // 本体版本 → 版本产线(版本比较的归属面)
+  const ontologyId = one(args.ontology_id ?? args.ontologyId)
+  if (ontologyId) {
+    const { getAmlRuntime } = await import('@/server/services/workshop/aml/runtime')
+    const db = getAmlRuntime().db
+    const wantsVersion = args.version !== undefined ? Number(args.version) : Number.NaN
+    const v = Number.isInteger(wantsVersion)
+      ? db.prepare('SELECT line_id AS lineId FROM ontology_versions WHERE id = ? AND version = ?').get(ontologyId, wantsVersion) as { lineId?: string } | undefined
+      : db.prepare(`SELECT line_id AS lineId FROM ontology_versions WHERE id = ? AND status = 'published' ORDER BY version DESC LIMIT 1`).get(ontologyId) as { lineId?: string } | undefined
+    if (v?.lineId) lines.add(v.lineId)
+  }
   // Optimizer 绑定 → 目标产线(Profile → ProcessModelSpec.lineId);只读工具同样受线授权约束
   const bindingId = one(args.binding_id ?? args.bindingId)
   if (bindingId) {

package/server/services/workshop/agents/industrial/index.ts

@@ -1,32 +1,38 @@
-/**
- * 工业工具族(daq_query / dcw_* / param_* / ops_* / recipe_* / aml_*)
- *
- * 由原单文件按职责拆分而来;此处保持**原文件的公开 API 与 import 路径不变**
- * (目录 index 解析),外部调用方无需改动。
- *
- * 模块划分:
- *   dcw-tools.ts           节点清单、数控下发/回读(dcw_control / dcw_read)
- *   param-tools.ts         工艺参数读写(param_control / param_read)与量程/容差辅助
- *   daq-tools.ts           数采查询与帧检索(daq_query / daq_frames)
- *   dcw-judge-tools.ts     判定与回滚(dcw_judge / dcw_rollback / dcw_journal)与绑定鉴权
- *   ops-tools.ts           运维日志与配方变更史(ops_log / recipe_* / line_context)
- *   aml-dataset-tools.ts   AML 数据集与节点目录(aml_node_catalog / aml_dataset_*)
- *   aml-job-tools.ts       AML 作业与模型(aml_job_* / aml_leaderboard / aml_model_*)
- *   mes-tools.ts           MES 数据集面(mes_catalog / mes_fetch / mes_export / mes_dataset_read / mes_datasets)
- */
-export { toolMyIndustrialNodes, toolDcwControl } from './dcw-tools'
-export { toolParamControl } from './param-tools'
-export { toolDaqQuery, toolDaqFrames } from './daq-tools'
-export { toolDaqExport } from './daq-export'
-export { toolDcwJudge, toolDcwRollback, toolDcwJournal } from './dcw-judge-tools'
-export { toolOpsLog, toolRecipeLog, toolRecipeCatalog, toolRecipeCreate, toolLineContext, toolRecipeVersions, toolRecipeUpdate, toolRecipeRollback, toolRecipeTrial, toolRecipeApply } from './ops-tools'
-export { toolMesCatalog, toolMesFetch, toolMesExport, toolMesDatasetRead, toolMesDatasets } from './mes-tools'
-export { toolAmlNodeCatalog, toolAmlDatasetBuild, toolAmlDatasetStats } from './aml-dataset-tools'
-export { toolAmlJobSubmit, toolAmlJobStatus, toolAmlJobLogs, toolAmlJobCancel, toolAmlLeaderboard, toolAmlModelFind, toolAmlModelPromote, toolAmlModelReference, toolAmlTrainingPlanList, toolAmlTrainingPlanTrain, toolAmlTrainingPlanCreate } from './aml-job-tools'
-
-export { toolOptimizationExplore } from './optimization-tools'
-export { toolTwinProviderCatalog, toolTwinSceneDiscover, toolTwinSceneCompile, toolTwinSceneFreeze, toolTwinSceneRead, toolTwinPhysicsSpecDraft, toolTwinPhysicsSpecValidate, toolTwinPhysicsSpecCompile, toolTwinSnapshotCreate, toolTwinTrialRun, toolMpcOptimize, toolTwinGateEvaluate, toolTwinCalibrationRequest, toolTwinBayesOptimize } from './twin-tools'
-export { toolAmlActivity } from './aml-activity'
-export { toolRecipePropose } from './recipe-propose-tools'
-export { toolLineStart, toolLineStop, toolLineStatus } from './line-tools'
-export { toolAnalysisSave, toolAnalysisQuery } from './analysis-tools'
+/**
+ * 工业工具族(daq_query / dcw_* / param_* / ops_* / recipe_* / aml_*)
+ *
+ * 由原单文件按职责拆分而来;此处保持**原文件的公开 API 与 import 路径不变**
+ * (目录 index 解析),外部调用方无需改动。
+ *
+ * 模块划分:
+ *   dcw-tools.ts           节点清单、数控下发/回读(dcw_control / dcw_read)
+ *   param-tools.ts         工艺参数读写(param_control / param_read)与量程/容差辅助
+ *   daq-tools.ts           数采查询与帧检索(daq_query / daq_frames)
+ *   dcw-judge-tools.ts     判定与回滚(dcw_judge / dcw_rollback / dcw_journal)与绑定鉴权
+ *   ops-tools.ts           运维日志与配方变更史(ops_log / recipe_* / line_context)
+ *   aml-dataset-tools.ts   AML 数据集与节点目录(aml_node_catalog / aml_dataset_*)
+ *   aml-job-tools.ts       AML 作业与模型(aml_job_* / aml_leaderboard / aml_model_*)
+ *   mes-tools.ts           MES 数据集面(mes_catalog / mes_fetch / mes_export / mes_dataset_read / mes_datasets)
+ */
+export { toolMyIndustrialNodes, toolDcwControl } from './dcw-tools'
+export { toolParamControl } from './param-tools'
+export { toolDaqQuery, toolDaqFrames } from './daq-tools'
+export { toolDaqExport } from './daq-export'
+export { toolDcwJudge, toolDcwRollback, toolDcwJournal } from './dcw-judge-tools'
+export { toolOpsLog, toolRecipeLog, toolRecipeCatalog, toolRecipeCreate, toolLineContext, toolRecipeVersions, toolRecipeUpdate, toolRecipeRollback, toolRecipeTrial, toolRecipeApply } from './ops-tools'
+export { toolMesCatalog, toolMesFetch, toolMesExport, toolMesDatasetRead, toolMesDatasets } from './mes-tools'
+export { toolAmlNodeCatalog, toolAmlDatasetBuild, toolAmlDatasetStats } from './aml-dataset-tools'
+export { toolAmlJobSubmit, toolAmlJobStatus, toolAmlJobLogs, toolAmlJobCancel, toolAmlLeaderboard, toolAmlModelFind, toolAmlModelPromote, toolAmlModelReference, toolAmlModelAnnotate, toolAmlTrainingPlanList, toolAmlTrainingPlanTrain, toolAmlTrainingPlanCreate } from './aml-job-tools'
+
+export { toolOptimizationExplore } from './optimization-tools'
+export { toolTwinProviderCatalog, toolTwinSceneDiscover, toolTwinSceneCompile, toolTwinSceneFreeze, toolTwinSceneRead, toolTwinPhysicsSpecDraft, toolTwinPhysicsSpecValidate, toolTwinPhysicsSpecCompile, toolTwinSnapshotCreate, toolTwinTrialRun, toolMpcOptimize, toolTwinGateEvaluate, toolTwinCalibrationRequest, toolTwinBayesOptimize } from './twin-tools'
+export { toolAmlActivity } from './aml-activity'
+export { toolRecipePropose } from './recipe-propose-tools'
+export { toolLineStart, toolLineStop, toolLineStatus } from './line-tools'
+export { toolAnalysisSave, toolAnalysisQuery } from './analysis-tools'
+export { toolOptimizerProfilePropose } from './optimizer-tools'
+export {
+  toolOntologySceneInspect, toolOntologyNodeNeighbors, toolOntologyDraftCreate, toolOntologyDraftValidate, toolOntologyDraftAutofix,
+  toolOntologyDraftUpdate, toolOntologyRuleExplain, toolOntologyCompilePreview,
+  toolOntologyPublishPropose, toolOntologyVersionCompare,
+} from './ontology-tools'

package/server/services/workshop/agents/industrial/ontology-tools.ts

@@ -0,0 +1,380 @@
+/**
+ * 本体工具族(10 件)—— Agent 侧的「读 / 邻接 / 起草 / 校验 / 解释 / 编译预览 / 提议发布 / 版本比较」。
+ *
+ * 治理:本族由 grant-guard(WVO: draft_create/draft_update/draft_autofix/publish_propose 属写族)
+ * 与 tool-verify(引用面)复核;**没有**任何工具能直接发布版本或写设备 ——
+ * 发布仅 admin 在 REST 面执行,Agent 只能 draft_create 起草、publish_propose 提请第二人批准。
+ *
+ * 归属:Agent 起草的草稿 owner = agentId(审计可见 actorKind='agent');
+ * 读取面按 agentOpsScope 的产线/节点范围收窄。
+ */
+import type { HostToolResult } from '../host-tool-bridge/types'
+import { AppError } from '../../../../utils/errors'
+import { agentOpsScope } from './ops-tools'
+import { getOntologyRepo, parseDraftRow } from '../../ontology/repo'
+import type { Actor } from '../../ontology/ontology.service'
+import {
+  compileDraft, createDraft, getDraft, requestRuleApproval, sceneSubgraph,
+  updateDraft, validateDraft, compareVersions, getVersion, listVersions, autoFixDraft,
+} from '../../ontology/ontology.service'
+import { parseSubgraphOptions } from '../../ontology/subgraph.core'
+import { subgraphAroundForLine } from '../../ontology/subgraph.service'
+
+import type { OntologyDraftDoc } from '../../ontology/contracts'
+
+function agentActor(agentId: string): Actor {
+  return { userId: agentId, role: 'editor', actorKind: 'agent' }
+}
+
+function readableLines(agentId: string): string[] {
+  const scope = agentOpsScope(agentId)
+  if (!scope) return []
+  return [...new Set([...scope.lineIds, ...scope.boundLineIds])]
+}
+
+function assertLineInScope(agentId: string, lineId: string): void {
+  const lines = readableLines(agentId)
+  if (lines.length === 0) {
+    throw new AppError(403, 'ONTOLOGY_SCOPE_VIOLATION', '本 Agent 没有绑定任何产线/节点,无法读取本体语义面')
+  }
+  if (!lines.includes(lineId)) {
+    throw new AppError(403, 'ONTOLOGY_SCOPE_VIOLATION',
+      `产线 ${lineId} 不在本 Agent 的可读范围(${lines.join(', ')});如需跨线请让用户绑定该产线节点或绑定频道产线`)
+  }
+}
+
+function ok(text: string): HostToolResult {
+  return { text }
+}
+
+function fail(text: string): HostToolResult {
+  return { text, isError: true }
+}
+
+function json(value: unknown): string {
+  return JSON.stringify(value, null, 2)
+}
+
+function stringArg(args: Record<string, unknown>, key: string): string {
+  const value = args[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/** 1) 场景语义子图(只读,分页) */
+export async function toolOntologySceneInspect(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const lineId = stringArg(args, 'line_id')
+  if (!lineId) return fail('ontology_scene_inspect 需要 line_id(line_context 可看到当前产线 id)')
+  try {
+    assertLineInScope(agentId, lineId)
+    const limit = Math.min(200, Math.max(1, Number(args.limit ?? 50)))
+    const offset = Math.max(0, Number(args.offset ?? 0))
+    const graph = sceneSubgraph(lineId, { limit: limit + offset })
+    if (!graph) return ok(`产线 ${lineId} 尚未发布任何本体(0 实体/0 规则);可先用 ontology_draft_create 起草。`)
+    const page = graph.entities.slice(offset, offset + limit)
+    const query = stringArg(args, 'query').toLowerCase()
+    const filtered = query
+      ? page.filter(e => `${e.key} ${e.name} ${e.kind}`.toLowerCase().includes(query))
+      : page
+    return ok([
+      `本体 ${graph.ontologyId}@${graph.version}(产线 ${lineId})`,
+      `实体 ${graph.entities.length} / 关系 ${graph.relations.length} / 规则 ${graph.rules.length} / 守卫 ${graph.guards.length}`,
+      `本页实体 ${filtered.length}(offset=${offset},limit=${limit})${query ? `;筛选"${query}"` : ''}:`,
+      ...filtered.map(e => `- ${e.key} [${e.kind}/${e.role ?? '未定角色'}] ${e.name} ${e.unit ? `(${e.unit})` : ''}`
+        + `${e.bindings.length ? ` ← ${e.bindings.map(b => `${b.platformKind}:${b.platformId}${b.targetSub ? `#${b.targetSub}` : ''}(${b.direction})`).join(', ')}` : '(未绑定)'}`),
+      graph.relations.length ? `关系:` : '',
+      ...graph.relations.slice(0, 30).map(r => `- ${r.srcKey} -${r.kind}-> ${r.dstKey} [${r.evidenceTier}]`),
+      graph.rules.length ? '规则:' : '',
+      ...graph.rules.slice(0, 30).map(r => `- ${r.id} ${r.kind} status=${r.status} decision=${r.decision}${r.message ? `:${r.message}` : ''}`),
+      graph.entities.length > offset + limit ? '还有更多实体:增大 offset 继续分页。' : '',
+    ].filter(Boolean).join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 2) 节点邻接/多跳子图(只读):回答「这个节点关联哪些边、间接关联什么」 */
+export async function toolOntologyNodeNeighbors(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const lineId = stringArg(args, 'line_id')
+  const entityKey = stringArg(args, 'entity_key')
+  if (!lineId) return fail('ontology_node_neighbors 需要 line_id(line_context 可看到当前产线 id)')
+  if (!entityKey) return fail('ontology_node_neighbors 需要 entity_key(可先用 ontology_scene_inspect 查实体 key)')
+  try {
+    assertLineInScope(agentId, lineId)
+    const opts = parseSubgraphOptions({
+      hops: args.hops,
+      direction: args.direction,
+      kinds: args.kinds,
+    })
+    const sub = subgraphAroundForLine(lineId, entityKey, opts)
+    if (!sub) return ok(`产线 ${lineId} 尚未发布任何本体(0 实体/0 规则);可先用 ontology_draft_create 起草。`)
+    const neighbors = sub.nodes.filter(n => n.hop > 0)
+    return ok([
+      `邻接子图: center=${entityKey} 本体=${sub.ontologyId}@${sub.version} hops=${opts.hops} direction=${opts.direction}`
+      + ` nodes=${sub.nodes.length} edges=${sub.edges.length}${sub.truncated ? ' truncated=true(受 limit 截断)' : ''}`,
+      `中心: ${sub.center.key} [${sub.center.kind}/${sub.center.role ?? '未定角色'}] ${sub.center.name}`
+      + `${sub.center.unit ? `(${sub.center.unit})` : ''}${sub.center.description ? ` — ${sub.center.description}` : ''}`
+      + `${sub.center.bindings.length ? ` ← ${sub.center.bindings.map(b => `${b.platformKind}:${b.platformId}${b.targetSub ? `#${b.targetSub}` : ''}(${b.direction},${b.status})`).join(', ')}` : '(未绑定)'}`,
+      neighbors.length ? '邻居节点:' : '邻居节点: (无)',
+      ...neighbors.map(n => `- ${n.key} hop=${n.hop} [${n.kind}/${n.role ?? '未定角色'}] ${n.name}`
+        + `${n.unit ? `(${n.unit})` : ''}`),
+      sub.edges.length ? '关联边:' : '关联边: (无)',
+      ...sub.edges.map(e => `- ${e.id} kind=${e.kind} ${e.srcKey} -> ${e.dstKey} hop=${e.hop} dir=${e.direction} tier=${e.evidenceTier}`),
+      '提示:需要规则/守卫/绑定全貌用 ontology_scene_inspect;解释单条规则用 ontology_rule_explain;版本差异用 ontology_version_compare。',
+    ].join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 3) 创建草稿(可空白起点或克隆已发布版本) */
+export async function toolOntologyDraftCreate(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const ontologyId = stringArg(args, 'ontology_id')
+  const lineId = stringArg(args, 'line_id')
+  if (!ontologyId) return fail('ontology_draft_create 需要 ontology_id(形如 ont-pva-line01)')
+  try {
+    if (lineId) assertLineInScope(agentId, lineId)
+    const draft = createDraft(agentActor(agentId), {
+      ontologyId,
+      lineId,
+      name: stringArg(args, 'name') || undefined,
+      cloneFromVersion: args.clone_from_version === true,
+    })
+    const doc = parseDraftRow(getDraft(draft.id))
+    return ok([
+      `已创建草稿 ${draft.id}(本体 ${ontologyId},rev=${draft.rev}${draft.baseVersion ? `,基线 v${draft.baseVersion}` : ''})`,
+      `当前内容:实体 ${doc.entities.length} / 关系 ${doc.relations.length} / 规则 ${doc.rules.length} / 绑定 ${doc.bindings.length}`,
+      '下一步:用 ontology_draft_validate 校验,或直接提交整份文档(update 由平台 REST 完成)。',
+    ].join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 3) 校验草稿(结构 + 活体绑定) */
+export async function toolOntologyDraftValidate(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const draftId = stringArg(args, 'draft_id')
+  if (!draftId) return fail('ontology_draft_validate 需要 draft_id')
+  try {
+    const report = validateDraft(draftId, agentActor(agentId))
+    const errors = report.issues.filter(i => i.severity === 'error')
+    const warnings = report.issues.filter(i => i.severity === 'warning')
+    const bindingFailures = report.bindings.failures
+    return ok([
+      `草稿 ${draftId}:${report.ok && report.bindings.ok ? '校验通过' : '校验未通过'}`,
+      `实体 ${report.stats.entities} / 关系 ${report.stats.relations} / 规则 ${report.stats.rules} / 绑定 ${report.stats.bindings}`,
+      `生命周期分布:${Object.entries(report.stats.byState).filter(([, n]) => n > 0).map(([k, n]) => `${k}=${n}`).join(', ') || '无'}`,
+      errors.length ? `错误 ${errors.length}:` : '无错误',
+      ...errors.slice(0, 20).map(i => `- [${i.code}] ${i.path}: ${i.message}${i.hint ? ` → ${i.hint}` : ''}`),
+      warnings.length ? `警告 ${warnings.length}:` : '',
+      ...warnings.slice(0, 10).map(i => `- [${i.code}] ${i.path}: ${i.message}`),
+      bindingFailures.length ? `绑定失败 ${bindingFailures.length}:` : '',
+      ...bindingFailures.slice(0, 10).map(f => `- [${f.code}] ${f.message}`),
+    ].filter(Boolean).join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 3b) 自动修复草稿(安全规范化;证据不伪造,平台绑定漂移仍如实报告) */
+export async function toolOntologyDraftAutofix(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const draftId = stringArg(args, 'draft_id')
+  if (!draftId) return fail('ontology_draft_autofix 需要 draft_id')
+  try {
+    const detail = autoFixDraft(draftId, agentActor(agentId))
+    const errors = detail.validation.issues.filter(i => i.severity === 'error')
+    return ok([
+      detail.fixes.length
+        ? `草稿 ${draftId} 自动修复 ${detail.fixes.length} 项(rev=${detail.draft.rev}):`
+        : `草稿 ${draftId} 无需修复(rev=${detail.draft.rev})。`,
+      ...detail.fixes.slice(0, 20).map(f => `- [${f.code}] ${f.path}: ${f.message}`),
+      `修复后校验:${detail.validation.ok ? '通过' : `未通过(${errors.length} 个错误)`}${detail.bindings.ok ? '' : `;绑定失败 ${detail.bindings.failures.length} 项(平台侧,需核对真实节点/配方)`}`,
+      errors.length ? '剩余错误:' : '',
+      ...errors.slice(0, 10).map(i => `- [${i.code}] ${i.path}: ${i.message}`),
+      detail.validation.ok ? '下一步:ontology_draft_validate 复核 → ontology_publish_propose 提请发布。' : '剩余错误需补充真实证据/实体后再修复,不能由自动修复伪造。',
+    ].filter(Boolean).join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 4) 规则解释(DSL + 决策 + 人读来源) */
+export async function toolOntologyRuleExplain(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const ruleId = stringArg(args, 'rule_id')
+  const draftId = stringArg(args, 'draft_id')
+  const ontologyId = stringArg(args, 'ontology_id')
+  const versionArg = args.version !== undefined ? Number(args.version) : undefined
+  if (!ruleId) return fail('ontology_rule_explain 需要 rule_id')
+  try {
+    if (draftId) {
+      const detail = validateDraft(draftId, agentActor(agentId)) // 顺带确保归属可读
+      const doc: OntologyDraftDoc = parseDraftRow(getDraft(draftId))
+      const rule = doc.rules.find(r => r.id === ruleId || r.key === ruleId)
+      if (!rule) return fail(`草稿 ${draftId} 中没有规则 ${ruleId}`)
+      const preview = compileDraft(draftId, agentActor(agentId))
+      const trace = preview.result.traces.find(t => t.ruleId === rule.id)
+      return ok([
+        `规则 ${rule.id}(${rule.key})kind=${rule.kind} 约束级别=${rule.constraintLevel} 状态=${rule.status}`,
+        `DSL:${json(rule.dsl)}`,
+        `证据:${rule.evidence.map(e => `${e.level}(${e.source.type})`).join(', ') || '无'}`,
+        trace ? `编译决策:${trace.decision}${trace.decisionCode ? `[${trace.decisionCode}]` : ''} — ${trace.message}` : '尚未编译',
+        `规则修订 hash:${trace?.ruleRevision.slice(0, 16) ?? 'n/a'}`,
+        `文档告警:${detail.issues.length}`,
+      ].join('\n'))
+    }
+    if (ontologyId) {
+      const traces = getOntologyRepo().listTraces(ontologyId, Number.isInteger(versionArg) ? versionArg : undefined)
+      const trace = traces.find(t => t.ruleId === ruleId)
+      if (!trace) return fail(`本体 ${ontologyId} 的已发布版本中没有规则 ${ruleId} 的溯源行`)
+      const repo = getOntologyRepo()
+      const version = getVersion(ontologyId, trace.version)
+      const rule = repo.listRules(version.id, version.version).find(r => r.id === ruleId)
+      return ok([
+        `规则 ${trace.ruleId}(本体 ${ontologyId}@${trace.version})`,
+        `DSL:${rule ? json(rule.dsl) : '快照缺失'}`,
+        `证据级别:${trace.evidenceLevel || '无'} 约束级别:${trace.constraintLevel}`,
+        `编译决策:${trace.decision}${trace.decisionCode ? `[${trace.decisionCode}]` : ''} — ${trace.message}`,
+        `产物:${trace.artifacts.map(a => `${a.kind}${a.ref ? `:${a.ref}` : ''}`).join(', ') || '无(仅解释)'}`,
+        `适用域:line=${trace.scope.lineId || '全局'} recipe=${trace.scope.recipeId || '-'} condition=${trace.scope.conditionId || '-'}`,
+      ].join('\n'))
+    }
+    return fail('ontology_rule_explain 需要 draft_id 或 ontology_id 之一')
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 5) 编译预览(四类产物 + 规则溯源;不落库) */
+export async function toolOntologyCompilePreview(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const draftId = stringArg(args, 'draft_id')
+  if (!draftId) return fail('ontology_compile_preview 需要 draft_id')
+  try {
+    const preview = compileDraft(draftId, agentActor(agentId), { approvedOnly: args.approved_only === true })
+    const counts = {
+      compiled: preview.result.compiledCount, guard: preview.result.guardCount,
+      explained: preview.result.explainedCount, rejected: preview.result.rejectedCount,
+    }
+    const mv = preview.result.artifacts.problemIr.mvBounds
+    const cv = preview.result.artifacts.problemIr.cvBounds
+    const lines = [
+      `编译状态:${preview.result.status}(compiled=${counts.compiled} guard=${counts.guard} explained=${counts.explained} rejected=${counts.rejected})`,
+      `contentHash=${preview.contentHash.slice(0, 16)} packHash=${preview.packHash.slice(0, 16)} rulePackHash=${preview.result.rulePackHash.slice(0, 16)}`,
+      Object.keys(mv).length ? `mvBounds:${json(mv)}` : 'mvBounds:空',
+      Object.keys(cv).length ? `cvBounds:${json(cv)}` : 'cvBounds:空',
+      preview.result.artifacts.controlGuard.guards.length
+        ? `运行时守卫 ${preview.result.artifacts.controlGuard.guards.length}:`
+        : '运行时守卫:无',
+      ...preview.result.artifacts.controlGuard.guards.map(g => `- ${g.id} 当 ${g.when.variableKey} ${g.when.op} ${String(g.when.value)} 时禁止 ${g.forbid.kind}(${g.forbid.variableKey}) [${g.onViolate}]`),
+      preview.result.artifacts.processModel.featureCandidates.length
+        ? `训练特征候选 ${preview.result.artifacts.processModel.featureCandidates.length},时滞先验 ${preview.result.artifacts.processModel.delayPriors.length}`
+        : '',
+      preview.result.issues.length ? `告警/拒绝 ${preview.result.issues.length}:` : '无告警',
+      ...preview.result.issues.slice(0, 15).map(i => `- [${i.code}] ${i.ruleId ?? i.path}: ${i.message}`),
+    ]
+    return ok(lines.filter(Boolean).join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 6) 提议发布(只能申请第二人批准;不能自行发布) */
+export async function toolOntologyPublishPropose(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const draftId = stringArg(args, 'draft_id')
+  if (!draftId) return fail('ontology_publish_propose 需要 draft_id')
+  try {
+    const actor = agentActor(agentId)
+    const draft = getDraft(draftId)
+    if (draft.ownerUserId && draft.ownerUserId !== actor.userId) {
+      throw new AppError(403, 'DRAFT_SCOPE_VIOLATION', `草稿 ${draftId} 不属于本 Agent`)
+    }
+    const doc = parseDraftRow(draft)
+    const validated = doc.rules.filter(r => r.status === 'validated')
+    const pending = doc.rules.filter(r => r.status === 'reviewed')
+    const proposed = doc.rules.filter(r => r.status === 'proposed')
+    if (validated.length === 0) {
+      return ok([
+        `草稿 ${draftId} 没有处于 validated 的规则可提请控制级批准。`,
+        `当前:proposed=${proposed.length} reviewed=${pending.length} validated=0 approved=${doc.rules.filter(r => r.status === 'approved_for_control').length}`,
+        '请先由人完成 proposed→reviewed→validated(需要 observed/validated 级证据)。',
+      ].join('\n'))
+    }
+    const approvals = validated.map(rule => requestRuleApproval(draftId, rule.id, actor))
+    // 记一条「提请发布」提案(不改变规则状态;真正的发布需 admin 在 REST 面执行)
+    getOntologyRepo().appendPublishLog({
+      id: `opl-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
+      ontologyId: draft.ontologyId,
+      version: draft.baseVersion ?? 0,
+      action: 'publish.propose',
+      actor: agentId,
+      actorKind: 'agent',
+      soloOperator: 0,
+      approvalId: approvals[0]?.approvalId ?? null,
+      detailJson: JSON.stringify({ draftId, rules: approvals.map(a => a.ruleId) }),
+      createdAt: new Date().toISOString(),
+    })
+    return ok([
+      `已为 ${approvals.length} 条 validated 规则提请第二人批准(草稿 ${draftId},本体 ${draft.ontologyId}):`,
+      ...approvals.map(a => `- 规则 ${a.ruleId} → approvalId=${a.approvalId}`),
+      '注意:批准由人类在 /ontology 审批面裁决;批准后仍需 admin 执行 publish 才会冻结为不可变版本。',
+      '本工具不会写设备,也不会绕过 HITL/D13。',
+    ].join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 7) 版本比较(只读) */
+export async function toolOntologyVersionCompare(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const ontologyId = stringArg(args, 'ontology_id')
+  const from = Number(args.from ?? args.from_version)
+  const to = Number(args.to ?? args.to_version)
+  if (!ontologyId) return fail('ontology_version_compare 需要 ontology_id')
+  try {
+    void readableLines(agentId)
+    if (!Number.isInteger(from) || !Number.isInteger(to)) {
+      const versions = listVersions(ontologyId)
+      if (versions.length === 0) return ok(`本体 ${ontologyId} 还没有版本`)
+      return ok([
+        `本体 ${ontologyId} 版本:${versions.map(v => `v${v.version}(${v.status})`).join(', ')}`,
+        '给出 from 与 to 可查看四段差异(实体/关系/规则/绑定)。',
+      ].join('\n'))
+    }
+    const diff = compareVersions(ontologyId, from, to)
+    const section = (name: string, part: { added: string[], removed: string[], changed: string[] }) =>
+      `${name}:+${part.added.length}/-${part.removed.length}/±${part.changed.length}`
+      + (part.added.length ? ` 新增[${part.added.slice(0, 8).join(',')}]` : '')
+      + (part.removed.length ? ` 删除[${part.removed.slice(0, 8).join(',')}]` : '')
+      + (part.changed.length ? ` 变更[${part.changed.slice(0, 8).join(',')}]` : '')
+    return ok([
+      `本体 ${ontologyId}:v${from} → v${to}`,
+      section('实体', diff.entities),
+      section('关系', diff.relations),
+      section('规则', diff.rules),
+      section('绑定', diff.bindings),
+    ].join('\n'))
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}
+
+/** 内部:更新草稿(供后续工具扩展;当前 7 工具中无直接暴露) */
+export async function toolOntologyDraftUpdate(agentId: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const draftId = stringArg(args, 'draft_id')
+  const expectedRev = Number(args.expected_rev)
+  if (!draftId || !Number.isInteger(expectedRev)) return fail('ontology_draft_update 需要 draft_id 与 expected_rev')
+  try {
+    const detail = updateDraft(draftId, agentActor(agentId), { doc: args.doc, expectedRev })
+    return ok(`草稿 ${draftId} 已保存(rev=${detail.draft.rev});校验:${detail.validation.ok ? '通过' : '未通过'}`)
+  }
+  catch (err) {
+    return fail((err as Error).message)
+  }
+}