agentworkshop 0.8.0 → 0.8.1

package/server/services/workshop/db/database/open.ts

@@ -1,97 +1,97 @@
-/**
- * 打开/初始化数据库(PRAGMA、建表、种子、sqlite-vec)
- * (由 server/services/workshop/db/database.ts 按职责拆出;内容逐行原文搬运)
- */
-import type * as sqliteVec from 'sqlite-vec'
-import { DatabaseSync } from 'node:sqlite'
-import { SCHEMA_SQL } from './schema'
-import { createRequire } from 'node:module'
-import { migrateAddColumn, migrateAgentTeamExecutionLeaseColumns, migrateAgentTeamTaskGuardrailColumns, migrateAgentTeamTaskGuardrails, migrateAgentTeamTaskQueueColumns, migrateAmlChannelOptimizationColumns, migrateAmlModelIdentityColumns, migrateAnalysisEditColumns, migrateApprovalPayloadColumns, migrateAuditQueryIndexes, migrateAuditScopeColumn, migrateDropOwnerFks, migrateDualDriveColumns, migrateGroupChatV17, migrateLegacySchema, migrateMissingForeignKeys, migrateAmlTwinProviderColumns, migrateOptimizerFoundationColumns, migrateAgentTokenGraceColumns } from './migrations'
-import { seedDefaultWorkshopData } from './seed'
-
-export const require = createRequire(import.meta.url)
-export function openWorkshopDb(path: string): DatabaseSync {
-  // allowExtension + 尝试加载 sqlite-vec(向量检索);失败静默降级纯 FTS(受控环境可能禁扩展)
-  const db = new DatabaseSync(path, { allowExtension: true })
-  // busy_timeout:retention/backup 等第二连接持写锁时,主连接等待而非立即 SQLITE_BUSY
-  db.exec('PRAGMA busy_timeout = 5000')
-  try {
-    const { getLoadablePath } = require('sqlite-vec') as typeof sqliteVec
-    db.loadExtension(getLoadablePath())
-  }
-  catch {
-    // 扩展不可用:记忆系统自动退化为 FTS-only(vecInit 将失败并禁用向量)
-  }
-  initWorkshopDb(db)
-  return db
-}
-
-/** 对已打开的库执行初始化:WAL + 外键约束 + 建表 + 增量迁移 */
-export function initWorkshopDb(db: DatabaseSync): void {
-  db.exec('PRAGMA journal_mode = WAL;')
-  // S6:synchronous=NORMAL(WAL 推荐档)——与 TSDB 仿真库对齐;断电最多丢最后一个事务,不损坏库
-  db.exec('PRAGMA synchronous = NORMAL;')
-  db.exec('PRAGMA foreign_keys = ON;')
-  db.exec(SCHEMA_SQL)
-  // Add guardrail metadata before any legacy tasks-table rebuild so values can be copied safely.
-  migrateAgentTeamTaskGuardrailColumns(db)
-  migrateAgentTeamTaskQueueColumns(db)
-  migrateLegacySchema(db)
-  migrateAddColumn(db, 'channels', 'scenario_prompt', 'TEXT NOT NULL DEFAULT \'\'')
-  // v11:channel 级默认 LLM(四引擎统一注入面;成员 config 显式指定时优先)
-  migrateAddColumn(db, 'channels', 'llm_json', 'TEXT NOT NULL DEFAULT \'\'')
-  // 派发路由理由(koda RouteDecision 借鉴):lead 派发留痕"为什么派给他",供审计与前端呈现
-  migrateAddColumn(db, 'tasks', 'route_reason', 'TEXT NOT NULL DEFAULT \'\'')
-  // v10:模板可见性列(既有库补列;默认 private,仅属主可见)
-  migrateAddColumn(db, 'agents', 'visibility', 'TEXT NOT NULL DEFAULT \'private\'')
-  migrateAddColumn(db, 'teams', 'visibility', 'TEXT NOT NULL DEFAULT \'private\'')
-  // 回填:内置/遗留公共模板(owner NULL)强制 public —— 升级后保持全员可读可用
-  db.exec('UPDATE agents SET visibility = \'public\' WHERE owner_user_id IS NULL')
-  db.exec('UPDATE teams SET visibility = \'public\' WHERE owner_user_id IS NULL')
-  // 运维日志(OpsLog)维度列:既有库补列(新库由上方 DDL 直建)
-  migrateAddColumn(db, 'audit_log', 'line_id', 'TEXT NOT NULL DEFAULT \'\'')
-  migrateAddColumn(db, 'audit_log', 'product_id', 'TEXT NOT NULL DEFAULT \'\'')
-  migrateAddColumn(db, 'audit_log', 'recipe_id', 'TEXT NOT NULL DEFAULT \'\'')
-  migrateAddColumn(db, 'audit_log', 'kind', 'TEXT NOT NULL DEFAULT \'\'')
-  migrateAddColumn(db, 'audit_log', 'summary', 'TEXT NOT NULL DEFAULT \'\'')
-  // 2026-10-08 写控 ACK 鉴定:严重级列(info/warn/error;既有库补列,历史行按 info 语义)
-  migrateAddColumn(db, 'audit_log', 'level', 'TEXT NOT NULL DEFAULT \'info\'')
-  // 2026-10-19 产线日志显式域标识(scope=line|system;老库按 line_id 回填并强制不变量)
-  migrateAuditScopeColumn(db)
-  // 2026-10-19 产线日志查询索引(必须在补列之后:老库缺列时建索引会中断初始化)
-  migrateAuditQueryIndexes(db)
-  migrateMissingForeignKeys(db)
-  // Run after legacy task-table rebuilds so guardrail metadata and its index survive upgrades.
-  migrateAgentTeamTaskQueueColumns(db)
-  migrateAgentTeamExecutionLeaseColumns(db)
-  migrateAgentTeamTaskGuardrails(db)
-  migrateDropOwnerFks(db)
-  migrateGroupChatV17(db)
-  migrateAmlTwinProviderColumns(db)
-  migrateAmlModelIdentityColumns(db)
-  migrateAmlChannelOptimizationColumns(db)
-  // 产线 Co-Pilot P2:审批历史结构化载荷列(payload_json/choice;既有库补列,新库 DDL 已含)
-  migrateApprovalPayloadColumns(db)
-  // v27:数据分析报告人工修订列(updated_*;既有库补列,新库 DDL 已含)
-  migrateAnalysisEditColumns(db)
-  // v29:Optimizer/Process Model 地基列(工件类型判别、谱系引用、legacy 标记)
-  migrateOptimizerFoundationColumns(db)
-  // v30:双驱动收敛列(下发状态机/谱系/多工况 hash/资格谱系;总计划 SW2–SW5)
-  migrateDualDriveColumns(db)
-  // v31(WP3):agent token 轮换宽限列(prev_token/prev_token_until;既有库补列)
-  migrateAgentTokenGraceColumns(db)
-  // v32(ONT):Profile 冻结本体引用摘要(缺省 [] = 无本体约束域;只前滚,不回填)
-  migrateAddColumn(db, 'optimizer_profiles', 'ontology_refs_json', 'TEXT NOT NULL DEFAULT \'[]\'')
-  seedDefaultWorkshopData(db)
-}
-
-/**
- * v17 迁移:群聊/成员/HITL 相关列与不变量回填。
- *
- * 规则(主计划 §3.1 / §13.7):
- * - 既有 owner 非 NULL 的 Channel 一律 private + owner_approve + owner_only + chat_enabled=0,
- *   即**默认不改变任何既有可见性/权限行为**。
- * - owner 为 NULL 的遗留 Channel 同样保持 private + chat_enabled=0:不能被自动变成公开群聊;
- *   必须由 admin 显式认领(写 owner_user_id)后再由 owner 开启群聊。
- * - 每个 owner 非 NULL 的 Channel 必须恰好一条 active owner 成员记录(缺失则补写)。
- */
+/**
+ * 打开/初始化数据库(PRAGMA、建表、种子、sqlite-vec)
+ * (由 server/services/workshop/db/database.ts 按职责拆出;内容逐行原文搬运)
+ */
+import type * as sqliteVec from 'sqlite-vec'
+import { DatabaseSync } from 'node:sqlite'
+import { SCHEMA_SQL } from './schema'
+import { createRequire } from 'node:module'
+import { migrateAddColumn, migrateAgentTeamExecutionLeaseColumns, migrateAgentTeamTaskGuardrailColumns, migrateAgentTeamTaskGuardrails, migrateAgentTeamTaskQueueColumns, migrateAmlChannelOptimizationColumns, migrateAmlModelIdentityColumns, migrateAnalysisEditColumns, migrateApprovalPayloadColumns, migrateAuditQueryIndexes, migrateAuditScopeColumn, migrateDropOwnerFks, migrateDualDriveColumns, migrateGroupChatV17, migrateLegacySchema, migrateMissingForeignKeys, migrateAmlTwinProviderColumns, migrateOptimizerFoundationColumns, migrateAgentTokenGraceColumns } from './migrations'
+import { seedDefaultWorkshopData } from './seed'
+
+export const require = createRequire(import.meta.url)
+export function openWorkshopDb(path: string): DatabaseSync {
+  // allowExtension + 尝试加载 sqlite-vec(向量检索);失败静默降级纯 FTS(受控环境可能禁扩展)
+  const db = new DatabaseSync(path, { allowExtension: true })
+  // busy_timeout:retention/backup 等第二连接持写锁时,主连接等待而非立即 SQLITE_BUSY
+  db.exec('PRAGMA busy_timeout = 5000')
+  try {
+    const { getLoadablePath } = require('sqlite-vec') as typeof sqliteVec
+    db.loadExtension(getLoadablePath())
+  }
+  catch {
+    // 扩展不可用:记忆系统自动退化为 FTS-only(vecInit 将失败并禁用向量)
+  }
+  initWorkshopDb(db)
+  return db
+}
+
+/** 对已打开的库执行初始化:WAL + 外键约束 + 建表 + 增量迁移 */
+export function initWorkshopDb(db: DatabaseSync): void {
+  db.exec('PRAGMA journal_mode = WAL;')
+  // S6:synchronous=NORMAL(WAL 推荐档)——与 TSDB 仿真库对齐;断电最多丢最后一个事务,不损坏库
+  db.exec('PRAGMA synchronous = NORMAL;')
+  db.exec('PRAGMA foreign_keys = ON;')
+  db.exec(SCHEMA_SQL)
+  // Add guardrail metadata before any legacy tasks-table rebuild so values can be copied safely.
+  migrateAgentTeamTaskGuardrailColumns(db)
+  migrateAgentTeamTaskQueueColumns(db)
+  migrateLegacySchema(db)
+  migrateAddColumn(db, 'channels', 'scenario_prompt', 'TEXT NOT NULL DEFAULT \'\'')
+  // v11:channel 级默认 LLM(四引擎统一注入面;成员 config 显式指定时优先)
+  migrateAddColumn(db, 'channels', 'llm_json', 'TEXT NOT NULL DEFAULT \'\'')
+  // 派发路由理由(koda RouteDecision 借鉴):lead 派发留痕"为什么派给他",供审计与前端呈现
+  migrateAddColumn(db, 'tasks', 'route_reason', 'TEXT NOT NULL DEFAULT \'\'')
+  // v10:模板可见性列(既有库补列;默认 private,仅属主可见)
+  migrateAddColumn(db, 'agents', 'visibility', 'TEXT NOT NULL DEFAULT \'private\'')
+  migrateAddColumn(db, 'teams', 'visibility', 'TEXT NOT NULL DEFAULT \'private\'')
+  // 回填:内置/遗留公共模板(owner NULL)强制 public —— 升级后保持全员可读可用
+  db.exec('UPDATE agents SET visibility = \'public\' WHERE owner_user_id IS NULL')
+  db.exec('UPDATE teams SET visibility = \'public\' WHERE owner_user_id IS NULL')
+  // 运维日志(OpsLog)维度列:既有库补列(新库由上方 DDL 直建)
+  migrateAddColumn(db, 'audit_log', 'line_id', 'TEXT NOT NULL DEFAULT \'\'')
+  migrateAddColumn(db, 'audit_log', 'product_id', 'TEXT NOT NULL DEFAULT \'\'')
+  migrateAddColumn(db, 'audit_log', 'recipe_id', 'TEXT NOT NULL DEFAULT \'\'')
+  migrateAddColumn(db, 'audit_log', 'kind', 'TEXT NOT NULL DEFAULT \'\'')
+  migrateAddColumn(db, 'audit_log', 'summary', 'TEXT NOT NULL DEFAULT \'\'')
+  // 2026-10-08 写控 ACK 鉴定:严重级列(info/warn/error;既有库补列,历史行按 info 语义)
+  migrateAddColumn(db, 'audit_log', 'level', 'TEXT NOT NULL DEFAULT \'info\'')
+  // 2026-10-19 产线日志显式域标识(scope=line|system;老库按 line_id 回填并强制不变量)
+  migrateAuditScopeColumn(db)
+  // 2026-10-19 产线日志查询索引(必须在补列之后:老库缺列时建索引会中断初始化)
+  migrateAuditQueryIndexes(db)
+  migrateMissingForeignKeys(db)
+  // Run after legacy task-table rebuilds so guardrail metadata and its index survive upgrades.
+  migrateAgentTeamTaskQueueColumns(db)
+  migrateAgentTeamExecutionLeaseColumns(db)
+  migrateAgentTeamTaskGuardrails(db)
+  migrateDropOwnerFks(db)
+  migrateGroupChatV17(db)
+  migrateAmlTwinProviderColumns(db)
+  migrateAmlModelIdentityColumns(db)
+  migrateAmlChannelOptimizationColumns(db)
+  // 产线 Co-Pilot P2:审批历史结构化载荷列(payload_json/choice;既有库补列,新库 DDL 已含)
+  migrateApprovalPayloadColumns(db)
+  // v27:数据分析报告人工修订列(updated_*;既有库补列,新库 DDL 已含)
+  migrateAnalysisEditColumns(db)
+  // v29:Optimizer/Process Model 地基列(工件类型判别、谱系引用、legacy 标记)
+  migrateOptimizerFoundationColumns(db)
+  // v30:双驱动收敛列(下发状态机/谱系/多工况 hash/资格谱系;总计划 SW2–SW5)
+  migrateDualDriveColumns(db)
+  // v31(WP3):agent token 轮换宽限列(prev_token/prev_token_until;既有库补列)
+  migrateAgentTokenGraceColumns(db)
+  // v32(ONT):Profile 冻结本体引用摘要(缺省 [] = 无本体约束域;只前滚,不回填)
+  migrateAddColumn(db, 'optimizer_profiles', 'ontology_refs_json', 'TEXT NOT NULL DEFAULT \'[]\'')
+  seedDefaultWorkshopData(db)
+}
+
+/**
+ * v17 迁移:群聊/成员/HITL 相关列与不变量回填。
+ *
+ * 规则(主计划 §3.1 / §13.7):
+ * - 既有 owner 非 NULL 的 Channel 一律 private + owner_approve + owner_only + chat_enabled=0,
+ *   即**默认不改变任何既有可见性/权限行为**。
+ * - owner 为 NULL 的遗留 Channel 同样保持 private + chat_enabled=0:不能被自动变成公开群聊;
+ *   必须由 admin 显式认领(写 owner_user_id)后再由 owner 开启群聊。
+ * - 每个 owner 非 NULL 的 Channel 必须恰好一条 active owner 成员记录(缺失则补写)。
+ */

package/server/services/workshop/db/database/schema.ts

@@ -896,6 +896,7 @@ CREATE TABLE IF NOT EXISTS optimizer_profiles (
   id                    TEXT NOT NULL,
   version               INTEGER NOT NULL DEFAULT 1,
   name                  TEXT NOT NULL DEFAULT '',
+  description           TEXT NOT NULL DEFAULT '',
   model_ref             TEXT NOT NULL,
   model_artifact_hash   TEXT NOT NULL DEFAULT '',
   model_artifact_kind   TEXT NOT NULL DEFAULT '',

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

@@ -0,0 +1,198 @@
+/**
+ * 本体草稿自动修复 —— 只做「安全、确定、幂等」的规范化,绝不伪造证据。
+ *
+ * 可自动修复(修复后有 fix 记录):
+ *  1. DOC_DESCRIPTION / ENTITY_DESCRIPTION / RULE_DESCRIPTION:补人读描述,
+ *     让 Agent 与用户一眼看出这个模型代表什么;
+ *  2. ENTITY_DIMENSION:量纲跟随单位(复合/未知单位不强行声明量纲,避免误配);
+ *  3. SCOPE_LINE:B 规则/绑定作用域回填文档产线;
+ *  4. BINDING_UNIT / BINDING_SCALE:绑定声明单位回填实体单位;scale=0 归一为 1;
+ *  5. ORPHAN_RELATION / ORPHAN_BINDING:悬空引用(实体不存在)确定性移除;
+ *  6. DUPLICATE_ID:完全重复的项去重;同 id 不同内容追加 `-dupN` 后缀保留两份;
+ *  7. RULE_STATUS_DOWNGRADE:证据未达 validated_control 的硬约束(bound/rate/nonlinear)
+ *     不允许停在 approved_for_control —— 回退到 validated(证据不可自动伪造)。
+ *
+ * 不作为自动修复(仍需人/Agent 补真实信息,由 validator 报告):
+ *  - 证据缺失/级别不足(需真实数据或专家记录);
+ *  - 未知实体引用之外的语义冲突(RULE_CONFLICT);
+ *  - 平台侧绑定漂移(节点/配方不存在、单位与真实对象不符)。
+ */
+import { dimensionOf } from '@/shared/dimensions'
+import { validateDraftDoc } from './validator'
+import type { OntologyDraftDoc, OntologyEntity, OntologyRule } from './contracts'
+
+export interface OntologyAutoFix {
+  code: string
+  path: string
+  message: string
+}
+
+export interface AutoFixOutcome {
+  doc: OntologyDraftDoc
+  fixes: OntologyAutoFix[]
+  /** 修复后的校验结论(便于调用方一次看清还剩什么) */
+  validation: ReturnType<typeof validateDraftDoc>
+}
+
+const EVIDENCE_RANK: Record<string, number> = {
+  candidate_influence: 0,
+  observed_correlation: 1,
+  validated_control: 2,
+}
+
+const CONTROL_HARD_KINDS = new Set(['bound', 'rate', 'nonlinear'])
+
+function bestEvidenceLevel(rule: OntologyRule): string {
+  return rule.evidence.reduce((best, item) => (
+    (EVIDENCE_RANK[item.level] ?? 0) > (EVIDENCE_RANK[best] ?? 0) ? item.level : best
+  ), 'candidate_influence')
+}
+
+function ruleDescription(rule: OntologyRule): string {
+  const dsl = rule.dsl
+  switch (dsl.type) {
+    case 'bound': {
+      const range = [dsl.min != null ? `≥${dsl.min}` : '', dsl.max != null ? `≤${dsl.max}` : ''].filter(Boolean).join(' 且 ')
+      return `${dsl.variableKey} 界限${range ? `(${range}${dsl.unit ? ` ${dsl.unit}` : ''})` : ''}`
+    }
+    case 'rate':
+      return `${dsl.variableKey} 变化率上限 ${dsl.maxStep}${dsl.unit ? ` ${dsl.unit}` : ''}/步`
+    case 'state_condition':
+      return dsl.message?.trim() || `当 ${dsl.when.variableKey} ${dsl.when.op} ${dsl.when.value} 时禁止 ${dsl.forbid.variableKey} 增量`
+    case 'interlock':
+      return dsl.text
+    case 'linear_coupling':
+      return `${dsl.variableKey} 线性耦合于 ${dsl.ofKey}`
+    case 'nonlinear':
+      return `${dsl.variableKey} 非线性约束:${dsl.expression}`
+    default:
+      return dsl.text
+  }
+}
+
+function entityDimension(entity: OntologyEntity): string {
+  const computed = dimensionOf(entity.unit)
+  // 复合/未知单位自成一域(如 mm/s),不强行声明量纲 —— 留空表示「不主张相容性」
+  if (computed.startsWith('compound:') || computed.startsWith('unit:')) return ''
+  return computed
+}
+
+function scopeLineOf(doc: OntologyDraftDoc): string {
+  return String(doc.lineId ?? '').trim()
+}
+
+/** 修复本体草稿(纯函数;返回新对象,不修改入参) */
+export function autoFixDraftDoc(input: OntologyDraftDoc): AutoFixOutcome {
+  const doc: OntologyDraftDoc = JSON.parse(JSON.stringify(input)) as OntologyDraftDoc
+  const fixes: OntologyAutoFix[] = []
+  const lineId = scopeLineOf(doc)
+
+  // ── 1. 文档描述 ──
+  if (!String(doc.description ?? '').trim()) {
+    doc.description = `${doc.name}${lineId ? `(产线 ${lineId})` : '(全局本体)'} —— 实体 ${doc.entities.length} / 关系 ${doc.relations.length} / 规则 ${doc.rules.length} / 绑定 ${doc.bindings.length}`
+    fixes.push({ code: 'DOC_DESCRIPTION', path: 'description', message: '补写文档描述(供 Agent 与用户理解模型含义)' })
+  }
+
+  // ── 2. 实体:描述 + 量纲 ──
+  doc.entities = doc.entities.map((entity, index) => {
+    const next = { ...entity }
+    if (!String(next.description ?? '').trim()) {
+      next.description = next.name
+      fixes.push({ code: 'ENTITY_DESCRIPTION', path: `entities[${index}]`, message: `实体「${next.key}」补描述为名称` })
+    }
+    const dimension = entityDimension(next)
+    if ((next.dimension ?? '') !== dimension) {
+      fixes.push({ code: 'ENTITY_DIMENSION', path: `entities[${entity.key}]`, message: `量纲「${next.dimension || '空'}」→「${dimension || '空'}」(跟随单位 ${next.unit || '无量纲'})` })
+      next.dimension = dimension
+    }
+    return next
+  })
+  const entityKeys = new Set(doc.entities.map(e => e.key))
+  const entityByKey = new Map(doc.entities.map(e => [e.key, e]))
+
+  // ── 3. 关系:悬空引用移除 + 去重 ──
+  const relationIds = new Map<string, number>()
+  doc.relations = doc.relations.filter((relation, index) => {
+    if (!entityKeys.has(relation.srcKey) || !entityKeys.has(relation.dstKey)) {
+      fixes.push({ code: 'ORPHAN_RELATION', path: `relations[${index}]`, message: `关系「${relation.id}」引用不存在的实体,已移除` })
+      return false
+    }
+    const seen = relationIds.get(relation.id)
+    if (seen != null) {
+      const first = doc.relations[seen]
+      if (JSON.stringify(first) === JSON.stringify(relation)) {
+        fixes.push({ code: 'DUPLICATE_ID', path: `relations[${index}]`, message: `关系「${relation.id}」完全重复,已去重` })
+        return false
+      }
+      relation.id = `${relation.id}-dup${index}`
+      fixes.push({ code: 'DUPLICATE_ID', path: `relations[${index}]`, message: `关系 id 冲突,已改为「${relation.id}」保留两份` })
+    }
+    relationIds.set(relation.id, index)
+    return true
+  })
+
+  // ── 4. 规则:描述/作用域/状态回退 ──
+  doc.rules = doc.rules.map((rule, index) => {
+    const next = { ...rule, scope: { ...rule.scope } }
+    if (!String(next.description ?? '').trim()) {
+      next.description = ruleDescription(next)
+      fixes.push({ code: 'RULE_DESCRIPTION', path: `rules[${index}]`, message: `规则「${next.id}」补描述` })
+    }
+    if (lineId && !String(next.scope.lineId ?? '').trim()) {
+      next.scope.lineId = lineId
+      fixes.push({ code: 'SCOPE_LINE', path: `rules[${index}]`, message: `规则「${next.id}」作用域回填产线 ${lineId}` })
+    }
+    if (next.status === 'approved_for_control' && CONTROL_HARD_KINDS.has(`${next.kind}`)) {
+      const level = bestEvidenceLevel(next)
+      if ((EVIDENCE_RANK[level] ?? 0) < (EVIDENCE_RANK.validated_control ?? 2)) {
+        next.status = 'validated'
+        fixes.push({ code: 'RULE_STATUS_DOWNGRADE', path: `rules[${index}]`, message: `规则「${next.id}」证据级别 ${level} 不足控制级,状态回退为 validated(证据不可自动伪造)` })
+      }
+    }
+    return next
+  })
+
+  // ── 5. 绑定:悬空移除 / 单位回填 / scale 归一 / 作用域 ──
+  const bindingIds = new Map<string, number>()
+  doc.bindings = doc.bindings.filter((binding, index) => {
+    if (!entityKeys.has(binding.entityKey)) {
+      fixes.push({ code: 'ORPHAN_BINDING', path: `bindings[${index}]`, message: `绑定「${binding.id}」引用的实体不存在,已移除` })
+      return false
+    }
+    const seen = bindingIds.get(binding.id)
+    if (seen != null) {
+      const first = doc.bindings[seen]
+      if (JSON.stringify(first) === JSON.stringify(binding)) {
+        fixes.push({ code: 'DUPLICATE_ID', path: `bindings[${index}]`, message: `绑定「${binding.id}」完全重复,已去重` })
+        return false
+      }
+      binding.id = `${binding.id}-dup${index}`
+      fixes.push({ code: 'DUPLICATE_ID', path: `bindings[${index}]`, message: `绑定 id 冲突,已改为「${binding.id}」保留两份` })
+    }
+    bindingIds.set(binding.id, index)
+    return true
+  }).map((binding, index) => {
+    const next = { ...binding }
+    const entity = entityByKey.get(next.entityKey)
+    const unit = String(entity?.unit ?? '').trim()
+    if (unit && !String(next.unitDeclared ?? '').trim()) {
+      next.unitDeclared = unit
+      fixes.push({ code: 'BINDING_UNIT', path: `bindings[${index}]`, message: `绑定「${next.id}」声明单位回填 ${unit}` })
+    }
+    if (unit && !String(next.unitTarget ?? '').trim()) {
+      next.unitTarget = unit
+      fixes.push({ code: 'BINDING_UNIT', path: `bindings[${index}]`, message: `绑定「${next.id}」目标单位回填 ${unit}` })
+    }
+    if (!Number.isFinite(next.scale) || next.scale === 0) {
+      next.scale = 1
+      fixes.push({ code: 'BINDING_SCALE', path: `bindings[${index}]`, message: `绑定「${next.id}」scale 非法,归一为 1` })
+    }
+    if (lineId && (!String(next.scope ?? '').trim() || String(next.scope).trim() === 'global')) {
+      next.scope = `line:${lineId}`
+      fixes.push({ code: 'SCOPE_LINE', path: `bindings[${index}]`, message: `绑定「${next.id}」作用域回填 line:${lineId}` })
+    }
+    return next
+  })
+
+  return { doc, fixes, validation: validateDraftDoc(doc) }
+}

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

@@ -252,6 +252,8 @@ export type BindingDraft = z.infer<typeof bindingDraftSchema>
 export const ontologyDraftDocSchema = z.object({
   schemaVersion: z.literal(ONTOLOGY_SCHEMA_VERSION),
   name: z.string().min(1).max(200),
+  /** 人读描述:这个本体代表哪段工况、约束什么(Agent 可写,autofix 会补默认值) */
+  description: z.string().max(2000).default(''),
   /** 授权锚;空 = 全局本体(仅 admin 可发布) */
   lineId: z.string().max(120).default(''),
   entities: z.array(ontologyEntitySchema).default([]),
@@ -263,7 +265,7 @@ export const ontologyDraftDocSchema = z.object({
 export type OntologyDraftDoc = z.infer<typeof ontologyDraftDocSchema>
 
 export function emptyDraftDoc(ontologyId: string, lineId = ''): OntologyDraftDoc {
-  return { schemaVersion: ONTOLOGY_SCHEMA_VERSION, name: ontologyId, lineId, entities: [], relations: [], rules: [], bindings: [], note: '' }
+  return { schemaVersion: ONTOLOGY_SCHEMA_VERSION, name: ontologyId, description: '', lineId, entities: [], relations: [], rules: [], bindings: [], note: '' }
 }
 
 export function parseDraftDoc(value: unknown): OntologyDraftDoc {

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

@@ -8,3 +8,5 @@ export * from './guards'
 export * from './repo'
 export * from './semantic-binding.service'
 export * from './ontology.service'
+export * from './subgraph.core'
+export * from './subgraph.service'

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

@@ -43,6 +43,7 @@ import {
 } from './repo'
 import { detectBindingDrift, validateDraftBindings } from './semantic-binding.service'
 import { getDcwController } from '../dcw/dcw-controller'
+import { autoFixDraftDoc, type OntologyAutoFix } from './autofix'
 import { validateDraftDoc, type DraftValidationReport } from './validator'
 
 export interface Actor {
@@ -185,6 +186,7 @@ function cloneVersionDoc(version: VersionRow): OntologyDraftDoc {
   return {
     schemaVersion: ONTOLOGY_SCHEMA_VERSION,
     name: version.name || version.id,
+    description: '',
     lineId: version.lineId,
     entities,
     relations,
@@ -272,6 +274,50 @@ export function deleteDraft(draftId: string, actor: Actor): void {
   log({ ontologyId: draft.ontologyId, action: 'draft.delete', actor, detail: { draftId } })
 }
 
+/**
+ * 自动修复草稿(Agent 工具与 UI「自动修复」共用):
+ * 与 updateDraft 同一写路径(乐观锁 rev + 审计),区别有两点:
+ *  - strictBindings=false:平台侧绑定漂移不阻塞文档内安全修复的落库;
+ *  - 允许「部分修复」落库:自动修复后仍有不可自动修复的错误(如证据缺失)时,
+ *    已做的安全规范化照样保存,剩余错误随 validation 原样返回 —— 否则修复器
+ *    在历史/导入的脏草稿上会因残余错误整体回滚,等于不可用。
+ * 证据永不伪造:残余错误只能由人/Agent 补真实证据后再次校验。
+ */
+export function autoFixDraft(draftId: string, actor: Actor): {
+  draft: DraftRow
+  doc: OntologyDraftDoc
+  validation: DraftValidationReport
+  bindings: ReturnType<typeof validateDraftBindings>
+  fixes: OntologyAutoFix[]
+} {
+  requireEditor(actor, '自动修复本体草稿')
+  const draft = getDraft(draftId)
+  requireDraftAccess(draft, actor, { write: true })
+  const { doc, fixes, validation } = autoFixDraftDoc(parseDraftRow(draft))
+  const bindings = validateDraftBindings(doc, { lineId: doc.lineId })
+  if (!fixes.length) {
+    return { draft, doc, validation, bindings, fixes }
+  }
+  let updated: DraftRow
+  if (validation.ok) {
+    // 修复后完全合法:走标准写路径(含活体绑定复核与审计)
+    const detail = updateDraft(draftId, actor, { doc, expectedRev: draft.rev, strictBindings: false })
+    updated = detail.draft
+  }
+  else {
+    // 部分修复:直接落库(乐观锁 + 审计),残余错误由回执暴露,不静默掩盖
+    updated = getOntologyRepo().updateDraft(draftId, JSON.stringify(doc), draft.rev)
+  }
+  log({
+    ontologyId: updated.ontologyId,
+    version: updated.baseVersion ?? 0,
+    action: 'draft.autofix',
+    actor,
+    detail: { draftId, rev: updated.rev, fixes: fixes.length, residualErrors: validation.issues.filter(i => i.severity === 'error').length },
+  })
+  return { draft: updated, doc, validation, bindings, fixes }
+}
+
 // ===== 校验 / 编译预览 =====
 
 export function validateDraft(draftId: string, actor: Actor): DraftValidationReport & { bindings: ReturnType<typeof validateDraftBindings> } {