agentworkshop 0.7.66 → 0.7.71

package/server/services/workshop/agents/mock-agent.ts

@@ -23,6 +23,7 @@ import type {
 } from './agent-interface'
 import type { A2AArtifact } from '../types/a2a'
 import type { WorkspaceTask } from '../types/task'
+import { failedRetryReady } from '../types/task'
 import { extractTaskMode, synthesizeGoalSummary } from '../runtime/execution-mode'
 
 /** 终态(§2.2):COMPLETED / FAILED / CANCELED */
@@ -168,8 +169,9 @@ export class MockAgentImpl implements AgentInterface {
     }
 
     // FAILED 且重试次数 < 3 → reassign 给空闲 worker(模式无关)
+    // 回退窗:与规则引擎同源 —— 避免 worker 尚未消费新 assign 就被下一次重试换 lease。
     for (const task of snapshot.tasks) {
-      if (task.state === 'FAILED' && task.retryCount < 3) {
+      if (task.state === 'FAILED' && task.retryCount < 3 && failedRetryReady(task, now)) {
         const worker = this.pickWorker(pool, now, task.assigneeId)
         if (worker) {
           decisions.push({ kind: 'reassign', taskId: task.id, toAgentId: worker.agentId })

package/server/services/workshop/agents/node-delegation.ts

@@ -12,6 +12,7 @@
  */
 import { AppError, ErrorCodes } from '../../../utils/errors'
 import { getAgentNodeBindingRepo, type AgentNodeBinding, type AgentNodeBindingMode, type AgentNodeBindingKind } from './node-bindings.repo'
+import { getToolApprovals } from './tool-approvals'
 
 export interface DelegationMember {
   id: string
@@ -143,7 +144,15 @@ export function revokeDelegation(input: DelegationRevokeInput): Array<{ nodeId:
         out.push({ nodeId, kind: b.kind, revoked: false })
         continue
       }
-      out.push({ nodeId, kind: b.kind, revoked: repo.unbind(b.id) })
+      const revoked = repo.unbind(b.id)
+      if (revoked) {
+        // 收回即失活:挂起审批按拒绝收敛(配方绑定连带 recipe:/参数节点审批单)
+        try {
+          getToolApprovals().cancelPendingForBinding(targetAgentId, b)
+        }
+        catch { /* 审批服务未接线时不影响收权 */ }
+      }
+      out.push({ nodeId, kind: b.kind, revoked })
     }
   }
   return out

package/server/services/workshop/agents/omp-agent/client.ts

@@ -7,7 +7,7 @@ import type { AgentRunContext } from '../agent-interface'
 import { OmpRpcClient } from '../adapters/omp-rpc-client'
 import { attachTerminalTap, markTerminalSessionExit } from '../harness-terminal'
 import { bindHarnessProcess, markHarnessProcessExit, registerHarnessProcess } from '../harness-process'
-import { hostToolsForRole } from '../host-tool-bridge'
+import { hostToolsForAgent } from '../host-tool-bridge'
 
 export abstract class OmpRpcAgentImplClient extends OmpRpcAgentImplEventMapping {
   protected async ensureClient(ctx: AgentRunContext): Promise<void> {
@@ -88,7 +88,7 @@ export abstract class OmpRpcAgentImplClient extends OmpRpcAgentImplEventMapping
 
       // 注册 host tools(按角色差异化:lead 全量,worker 剔除调度/团队管理专属工具)
       client.onHostToolCall(req => this.handleHostTool(req))
-      await client.send({ type: 'set_host_tools', tools: hostToolsForRole(this.agentRole, this.channelId) })
+      await client.send({ type: 'set_host_tools', tools: hostToolsForAgent(this.selfAgentId, this.agentRole, this.channelId) })
 
       // 上下文治理探测(feature-detect 一次;失败退化被动 usage 跟踪)+ 原生压缩兜底保持开启
       void this.probeContext(client).catch(() => {})

package/server/services/workshop/agents/omp-agent/lifecycle.ts

@@ -3,7 +3,7 @@
  * (拆分层,承 OmpRpcAgentImplContextGovernance;方法体与原文件逐行一致)
  */
 import { OmpRpcAgentImplContextGovernance } from './context-governance'
-import { hostToolsForRole } from '../host-tool-bridge'
+import { hostToolsForAgent } from '../host-tool-bridge'
 import { killHarnessProcess, markHarnessProcessExit } from '../harness-process'
 import { liveAgents } from './helpers'
 import { markTerminalSessionExit } from '../harness-terminal'
@@ -27,7 +27,7 @@ export abstract class OmpRpcAgentImplLifecycle extends OmpRpcAgentImplContextGov
   refreshPluginTools(): void {
     const client = this.client
     if (!client || !client.alive) return
-    void client.send({ type: 'set_host_tools', tools: hostToolsForRole(this.agentRole, this.channelId) }).catch(() => {})
+    void client.send({ type: 'set_host_tools', tools: hostToolsForAgent(this.selfAgentId, this.agentRole, this.channelId) }).catch(() => {})
   }
 
   /** harness 会话身份(§2.4;get_state 探测到才有;未探测到返回 null) */

package/server/services/workshop/agents/pi-agent.ts

@@ -21,7 +21,7 @@ import {
   type OneShotEngineSpec,
 } from './adapters/one-shot-cli-agent'
 import { resolveBridgePath } from './harness-env'
-import { hostToolsForRole } from './host-tool-bridge'
+import { hostToolsForAgent } from './host-tool-bridge'
 
 /** 安全路径段:agentId 白名单化(仅作为路径段使用) */
 function safeId(agentId: unknown): string {
@@ -72,7 +72,8 @@ const spec: OneShotEngineSpec = {
   prepare: (config) => {
     // 把本角色可见的 host tools 写成文件,扩展同步读取注册(agent 身份 env 已注入 pi 进程)
     const file = toolsFilePath(config)
-    const tools = hostToolsForRole(
+    const tools = hostToolsForAgent(
+      typeof config.agentId === 'string' ? config.agentId : '',
       config.role === 'lead' ? 'lead' : 'worker',
       typeof config.channelId === 'string' ? config.channelId : undefined,
     )

package/server/services/workshop/agents/plugin-governance.ts

@@ -0,0 +1,148 @@
+/**
+ * plugin-governance —— 插件工具的平台侧治理闸门(WP4b / WP8)。
+ *
+ * 背景:插件工具历史上只过「团队插件开关 + roles」两道,不经 grant-guard/tool-verify/HITL。
+ * 本模块把三类治理补齐到**所有分发路径共用的单点**(dispatchHostToolInner 与
+ * manager.invokeHostTool 都调用,原生/omp/REST/MCP 桥同源):
+ *   1. kb_agent 写知识库(action=ingest)必须挂 HITL 审批(缺省 action 的入库意图启发拦截);
+ *   2. 插件工具声明了 references 才做引用面校验(存量未声明插件行为不变);
+ *   3. 插件工具调用结果统一入 audit(action=plugin.tool.call)。
+ *
+ * 铁律:审批与校验都在服务端执行期发生;注入面(是否展示工具)不是安全边界。
+ */
+import { checkToolAgainstScope } from '../runtime/permission-scope'
+import { getToolApprovals } from './tool-approvals'
+import { verifyToolReferences } from './industrial/tool-verify'
+import { recordOps } from '../ops/ops'
+import type { HostToolResult } from './host-tool-bridge/types'
+
+export interface PluginGovernanceIdentity {
+  agentId: string
+  channelId: string
+  role: 'lead' | 'worker'
+  name: string
+}
+
+/** 知识库入库意图启发词(辅助防线;完备防线 = action=ingest 契约 + riskClass=write 治理) */
+const INGEST_INTENT_PATTERNS = [
+  /入库/,
+  /沉淀/,
+  /写(入|进)?知识库/,
+  /知识库[^。;]{0,12}(写|存|记)/,
+  /\bingest\b/i,
+  /\bindex\s+(this|the)\s+file\b/i,
+  /\badd\s+(to\s+)?(the\s+)?knowledge\s*base\b/i,
+]
+
+const KB_TOOL = 'kb_agent'
+
+/** 入库守卫是否启用(env 逃生门;关闭只影响启发拦截,action=ingest 审批始终生效) */
+function ingestGuardEnabled(): boolean {
+  return process.env.AW_KB_INGEST_GUARD !== '0'
+}
+
+function looksLikeIngest(prompt: string): boolean {
+  return INGEST_INTENT_PATTERNS.some(re => re.test(prompt))
+}
+
+/**
+ * kb_agent 写入治理:action=ingest → HITL 审批(批准才继续);action 缺省且 prompt 命中
+ * 入库意图 → 拒绝并提示改用 action=ingest。
+ * 返回 null = 放行。
+ */
+async function governKbAgent(identity: PluginGovernanceIdentity, toolName: string, args: Record<string, unknown>): Promise<HostToolResult | null> {
+  if (toolName !== KB_TOOL) return null
+  const action = String(args.action ?? '').trim().toLowerCase()
+  const prompt = String(args.prompt ?? '')
+  if (action && action !== 'query' && action !== 'ingest') {
+    return { text: `kb_agent.action 取值非法(${action}):只能是 query(只读)或 ingest(写知识库)。`, isError: true }
+  }
+  if (action !== 'ingest') {
+    if (ingestGuardEnabled() && looksLikeIngest(prompt)) {
+      return {
+        text: '工具调用被拒(kb_agent 入库守卫):检测到入库/沉淀意图但未声明 action=ingest。请改用 action=ingest 重试——入库会进入平台审批(HITL),批准后才会写入知识库。',
+        isError: true,
+      }
+    }
+    return null
+  }
+  // 写入知识库:显式人工审批(与配方/产线写同源审批服务;缺省超时=拒绝)
+  const detail = `知识库入库审批(kb_agent):\n${prompt.slice(0, 1200)}`
+  const decision = await getToolApprovals().request(identity.agentId, '', 'kb', detail, {
+    title: '知识库入库审批',
+    payload: { tool: 'kb_agent', action: 'ingest', prompt: prompt.slice(0, 2000), mode: String(args.mode ?? 'sync') },
+  })
+  if (!decision.approved) {
+    recordOps({
+      actor: identity.agentId, actorName: identity.name, actorKind: 'agent',
+      action: 'plugin.tool.denied', kind: 'system', level: 'warn',
+      targetKind: 'tool', targetId: toolName,
+      summary: `知识库入库被拒绝/超时(审批 ${decision.id})`,
+      detail: { decision: decision.id, comment: decision.comment, prompt: prompt.slice(0, 200) },
+    })
+    return { text: `知识库入库未获批准(审批 ${decision.id}:${decision.comment || '超时或人工拒绝'}),未写入知识库。`, isError: true }
+  }
+  return null
+}
+
+/**
+ * 插件工具治理入口。返回 null = 放行;返回结果 = 拒绝。
+ * 调用点:dispatch.ts 插件分支 / manager.invokeHostTool 插件分支(两处同源)。
+ */
+export async function governPluginToolCall(
+  identity: PluginGovernanceIdentity,
+  toolName: string,
+  args: Record<string, unknown>,
+  declared?: { references?: { atLeastOne?: unknown }, noRefs?: boolean },
+): Promise<HostToolResult | null> {
+  try {
+    const kbDenied = await governKbAgent(identity, toolName, args)
+    if (kbDenied) return kbDenied
+    // WP8②:插件显式声明 references 才做引用面校验(未声明存量零变化)
+    if (declared?.references) {
+      const denied = verifyToolReferences(identity.agentId, toolName, args, declared.references as Parameters<typeof verifyToolReferences>[3])
+      if (denied) return denied
+    }
+    return null
+  }
+  catch (err) {
+    // 治理层自身故障 → fail-closed(与 grant-guard / tool-verify 同纪律)
+    return {
+      text: `插件工具治理校验异常(${toolName}):${err instanceof Error ? err.message : String(err)}。请稍后重试;若持续出现请联系管理员。`,
+      isError: true,
+    }
+  }
+}
+
+/** 插件调用结果审计(WP8③;成功与失败都留痕,便于审计面回答「谁在何时调了插件工具」) */
+export function auditPluginToolCall(
+  identity: PluginGovernanceIdentity,
+  toolName: string,
+  result: { text?: string, isError?: boolean },
+): void {
+  try {
+    recordOps({
+      actor: identity.agentId,
+      actorName: identity.name,
+      actorKind: 'agent',
+      action: 'plugin.tool.call',
+      kind: 'system',
+      level: result.isError ? 'warn' : 'info',
+      targetKind: 'tool',
+      targetId: toolName,
+      summary: `插件工具调用:${toolName}(${result.isError ? '失败' : '成功'})`,
+      detail: { channelId: identity.channelId, role: identity.role, isError: Boolean(result.isError), text: String(result.text ?? '').slice(0, 400) },
+    })
+  }
+  catch { /* 审计失败不阻断工具结果 */ }
+}
+
+/** 供外部(测试/调用方)复用:知识库入库动作判定 */
+export function kbActionOf(args: Record<string, unknown>): 'query' | 'ingest' | 'invalid' {
+  const action = String(args.action ?? '').trim().toLowerCase()
+  if (!action) return 'query'
+  if (action === 'query' || action === 'ingest') return action
+  return 'invalid'
+}
+
+export { checkToolAgainstScope }

package/server/services/workshop/agents/plugin-tools.ts

@@ -11,6 +11,7 @@
  *    (agentId/channelId/role/name)回调插件 handler。
  */
 import { createLogger } from '../logger'
+import type { ToolRiskClass, ToolVerifySpec } from './tool-reference-spec'
 
 const log = createLogger('workshop.plugin-tools')
 
@@ -32,6 +33,16 @@ export interface OmpPluginTool {
   parameters: Record<string, unknown>
   /** 可用角色(缺省 lead+worker 均可) */
   roles?: OmpPluginToolRole[]
+  /**
+   * 引用面声明(WP8①;可选,存量插件零变化)。
+   * 声明后才走执行期引用校验(verifyToolReferences),未声明保持既有行为。
+   * 形状与 host-tools.json 的 `references` 完全一致。
+   */
+  references?: ToolVerifySpec
+  /** 显式无引用声明(与未声明区分;riskClass=write 且未声明会被注册期告警) */
+  noRefs?: boolean
+  /** 风险类别(read/write/admin;插件写操作接同源 HITL 与审计) */
+  riskClass?: ToolRiskClass
   /** 执行体:返回文本结果(isError=true → omp 端按工具错误呈现) */
   handler: (args: Record<string, unknown>, agent: OmpPluginAgentContext) => Promise<{ text: string, isError?: boolean }> | { text: string, isError?: boolean }
 }
@@ -83,12 +94,16 @@ export function registerPluginTool(plugin: string, tool: OmpPluginTool): void {
 /** 插件卸载/停用时移除其全部工具 */
 export function unregisterPluginTools(plugin: string): void {
   const st = state()
+  let changed = false
   for (const [k, tool] of [...st.byPlugin.entries()]) {
     if (k.startsWith(`${plugin}:`)) {
       st.byPlugin.delete(k)
       if (st.byName.get(tool.name) === tool) st.byName.delete(tool.name)
+      changed = true
     }
   }
+  // 卸载也必须广播:否则在跑 omp 会话仍保留旧 set_host_tools,工具目录也收不到 available=0。
+  if (changed) notifyToolChange()
 }
 
 /** 全部插件工具(工具名 → 定义;hostToolsForRole 合并与分发用) */

package/server/services/workshop/agents/registry.ts

@@ -37,6 +37,13 @@ export interface HarnessCapabilities {
   contextStats: boolean
   /** 平台可主动触发压缩(onTurnSettled 门控) */
   compact: boolean
+  /**
+   * 工具面刷新能力(C14):
+   *  - native      —— 支持服务端直接热更(omp set_host_tools);
+   *  - list_changed —— MCP bridge 轮询 + 客户端重列举(支持者 ≤15s);
+   *  - per_turn    —— 下一回合装配(pi 工具文件)。
+   */
+  toolRefresh?: 'native' | 'list_changed' | 'per_turn'
 }
 
 /**
@@ -270,7 +277,20 @@ export function isKnownHarness(harness: string): boolean {
 
 /** registry 元信息(前端下拉/能力徽标;不含实现) */
 export function harnessMetas(): Array<{ id: string, label: string, description: string, capabilities: HarnessCapabilities, continuityMode: HarnessContinuityMode, homepage: string }> {
-  return Object.values(HARNESS_REGISTRY).map(({ id, label, description, capabilities, continuityMode, homepage }) => ({ id, label, description, capabilities, continuityMode, homepage }))
+  return Object.values(HARNESS_REGISTRY).map(({ id, label, description, capabilities, continuityMode, homepage }) => ({
+    id, label, description, continuityMode, homepage,
+    capabilities: { ...capabilities, toolRefresh: toolRefreshOf(id) },
+  }))
+}
+
+/**
+ * 工具面刷新策略(C14):omp/mock 支持服务端热更;pi 每回合装配;
+ * 其余持久会话走 MCP bridge 的 list_changed(客户端支持时重列举)。
+ */
+export function toolRefreshOf(harness: string): 'native' | 'list_changed' | 'per_turn' {
+  if (harness === 'omp' || harness === 'mock') return 'native'
+  if (harness === 'pi') return 'per_turn'
+  return 'list_changed'
 }
 
 /** 某 harness 的连续性能力(§6.3;未知 harness 按 per_turn 最保守处理,不虚假承诺复用) */

package/server/services/workshop/agents/tool-approvals.ts

@@ -19,7 +19,7 @@ export interface ToolApproval {
   id: string
   agentId: string
   nodeId: string
-  kind: 'dcw' | 'daq'
+  kind: 'dcw' | 'daq' | 'kb'
   /** 人读摘要(节点名/物理量/目标值/窗口) */
   detail: string
   /** 结构化审批载荷(可选;整包方案审批 recipe-propose 存方案集+预检结果,前端渲染结构化审批卡) */
@@ -68,7 +68,7 @@ class ToolApprovalService {
    *  opts.timeoutMs 覆盖本单超时窗(expiresAt 与 timer 两处同源取值;缺省 = 全局 hitl_timeout_ms);
    *  opts.payload 携带结构化审批载荷(随 pending/history 落库,前端渲染结构化审批卡)。
    *  不传 opts 的既有调用(param_control/manual-approval/recipe 门)行为不变。 */
-  request(agentId: string, nodeId: string, kind: 'dcw' | 'daq', detail: string, opts?: { title?: string, timeoutMs?: number, payload?: unknown }): Promise<ToolApprovalDecision> {
+  request(agentId: string, nodeId: string, kind: 'dcw' | 'daq' | 'kb', detail: string, opts?: { title?: string, timeoutMs?: number, payload?: unknown }): Promise<ToolApprovalDecision> {
     // hold 模式(手动生产语义):审批不自动拒、周期催办;显式传 timeoutMs 的调用方
     // (整包方案 30min)同样被 hold 覆盖 —— 真人在环时"等人"优先于"限时"。
     const hold = securityHitlTimeoutMode() === 'hold'
@@ -200,9 +200,11 @@ class ToolApprovalService {
     })
   }
 
-  /** 审批锚点 → 产线 id(节点 id 直查;recipe:/recipe-propose: 前缀查配方产线) */
+  /** 审批锚点 → 产线 id(节点 id 直查;recipe:/recipe-propose:/optimizer-recipe: 前缀查配方产线) */
   private lineIdOf(nodeId: string): string {
-    const m = /^(?:recipe|recipe-propose):(.+)$/.exec(nodeId)
+    if (nodeId.startsWith('line-start:')) return nodeId.slice('line-start:'.length)
+    if (nodeId.startsWith('line-stop:')) return nodeId.slice('line-stop:'.length)
+    const m = nodeId.match(/^(?:recipe|recipe-propose|optimizer-recipe):(.+)$/)
     try {
       if (m) {
         const recipe = getDcwController().listRecipes().find(r => r.id === m[1])
@@ -234,7 +236,7 @@ class ToolApprovalService {
     // recipe_update 只写定义不触产线,排除;失败仅告警不反噬裁决主流程。
     if (approved) {
       try {
-        const m = entry.approval.nodeId.match(/^(?:recipe|recipe-propose):(.+)$/)
+        const m = entry.approval.nodeId.match(/^(?:recipe|recipe-propose|optimizer-recipe):(.+)$/)
         const payload = (entry.approval.payload ?? {}) as { op?: string, kind?: string }
         if (m && payload.op !== 'update') {
           const rawOp = String(payload.op)
@@ -289,6 +291,30 @@ class ToolApprovalService {
     return n
   }
 
+  /**
+   * 解绑/收回一条绑定对应的全部挂起审批:
+   *  - 节点/配方直绑:nodeId 原值;
+   *  - 配方绑定:除配方本身,还要清理 `recipe:<id>` / `recipe-propose:<id>` 审批单
+   *    与该配方参数节点上的挂起下发(optimization_explore 经配方授权的审批键是节点 id)。
+   * 2026-10-18 修复:此前只按 nodeId 等值匹配,删配方绑定不会取消配方审批单,
+   * 批准后越过撤权窗口照常执行。
+   */
+  cancelPendingForBinding(agentId: string, binding: { nodeId: string, kind: string }): number {
+    let n = this.cancelPendingFor(agentId, binding.nodeId)
+    if (binding.kind === 'recipe') {
+      n += this.cancelPendingFor(agentId, `recipe:${binding.nodeId}`)
+      n += this.cancelPendingFor(agentId, `recipe-propose:${binding.nodeId}`)
+      // SW5/D14:optimizer 下发卡同配方收敛(撤权后在飞卡零写)
+      n += this.cancelPendingFor(agentId, `optimizer-recipe:${binding.nodeId}`)
+      try {
+        const recipe = getDcwController().listRecipes().find(r => r.id === binding.nodeId)
+        for (const p of recipe?.params ?? []) n += this.cancelPendingFor(agentId, p.nodeId)
+      }
+      catch { /* 配方已删除 → 无参数节点可清理 */ }
+    }
+    return n
+  }
+
   /**
    * 回合终止时收敛该 Agent 的全部挂起审批(运行时 stop / 成员移除前置):
    * 按「拒绝(回合已中止,指令未执行)」落定,绝不自动批准;返回收敛摘要供

package/server/services/workshop/agents/tool-classes.ts

@@ -25,6 +25,7 @@ export const HYBRID_TWIN_DIRECT_WRITE_TOOL_NAMES = new Set([
   'dcw_control',
   'param_control',
   'dcw_rollback',
+  'recipe_create',
   'recipe_update',
   'recipe_rollback',
   'recipe_trial',
@@ -37,6 +38,7 @@ export const HYBRID_TWIN_DIRECT_WRITE_TOOL_NAMES = new Set([
 export const MES_READ_TOOL_NAMES = new Set([
   'mes_catalog',
   'mes_fetch',
+  'mes_export',
   'mes_dataset_read',
   'mes_datasets',
 ])

package/server/services/workshop/agents/tool-reference-kinds.ts

@@ -0,0 +1,2 @@
+/** 引用类别(独立叶子,避免声明模块与校验模块的类型循环) */
+export type ToolRefKind = 'node' | 'line' | 'recipe'

package/server/services/workshop/agents/tool-reference-spec.ts

@@ -0,0 +1,114 @@
+/**
+ * 工具引用面声明 —— 单一声明源(零依赖叶子模块)。
+ *
+ * 设计(2026-10-24 工具面计划 WP5):
+ *  - 工具是否接收引用型参数(node/line/recipe/dataset/job/model/plan/scene/optimizer 对象)、
+ *    该怎么校验,由工具定义自带 `references` 声明;显式无引用声明 `noRefs: true`。
+ *  - **声明在注册期强制、校验在执行期实时**:本模块只承载声明与查表,不缓存任何
+ *    授权判定(绑定面可在调用间隙被改写,归属必须每次重算 —— 见 tool-verify.ts)。
+ *  - 加载器(loader)从 host-tools.json 读出字段,目录装配(catalog)调用
+ *    registerToolReferenceDeclarations() 建立查表;插件工具经 registerPluginTool
+ *    携带同形字段(可选,存量插件零变化)。
+ *  - 命名映射(MCP annotations 预留):refs[].mode='read' ≈ readOnlyHint,
+ *    mode='write' ≈ destructiveHint;riskClass='write' → destructiveHint=true。
+ */
+import type { ToolRefKind as _RefKind } from './tool-reference-kinds'
+
+export type { ToolRefKind } from './tool-reference-kinds'
+
+/** 链式引用类别(经谱系回溯判定归属) */
+export type ToolChainKind = 'dataset' | 'job' | 'model' | 'plan' | 'scene' | 'binding' | 'run' | 'recommendation'
+
+export interface ToolRefRule {
+  param: string
+  kind: _RefKind
+  /** 语义标注(不改变判定逻辑):read=只声明读取该对象;write=会改写该对象 */
+  mode?: 'read' | 'write'
+}
+
+export interface ToolChainRule {
+  param: string
+  kind: ToolChainKind
+  mode?: 'read' | 'write'
+}
+
+/** 一个工具的引用面声明(与 VERIFY_SPECS 的元素同形,平移到数据面) */
+export interface ToolVerifySpec {
+  /** 必填引用:至少提供一个(缺省形状拒绝;hint 给 Agent 该传什么) */
+  atLeastOne?: Array<{ params: string[], hint: string }>
+  /** 浅层字符串引用参数 → 判定类别 */
+  refs?: ToolRefRule[]
+  /** 浅层节点 id 数组参数 */
+  nodeLists?: string[]
+  /** 深路径节点引用(如 'params[].node_id' / 'packages[].params[].node_id') */
+  deepNodeRefs?: string[]
+  /** 链式引用(dataset_id/job_id/model_id/plan_id/scene_id/binding_id/run_id/recommendation_id) */
+  chained?: ToolChainRule[]
+  /** 只读工具:节点只要归属可读产线即可引用(与频道绑线只读扩权同口径;写工具不得开启) */
+  readableLineNodes?: boolean
+}
+
+/** 工具风险类别(治理面与 MCP annotations 的公共输入) */
+export type ToolRiskClass = 'read' | 'write' | 'admin'
+
+/** 带声明字段的工具定义(host-tools.json / 插件注册共用形状) */
+export interface ToolWithReferenceDeclaration {
+  name: string
+  references?: ToolVerifySpec
+  noRefs?: boolean
+  riskClass?: ToolRiskClass
+}
+
+const specByName = new Map<string, ToolVerifySpec | null>()
+
+/** 装载声明表(目录装配时调用;重复调用幂等覆盖) */
+export function registerToolReferenceDeclarations(tools: ToolWithReferenceDeclaration[]): void {
+  specByName.clear()
+  for (const t of tools) {
+    if (!t || typeof t.name !== 'string') continue
+    if (t.references) specByName.set(t.name, t.references)
+    else if (t.noRefs) specByName.set(t.name, null)
+  }
+}
+
+/**
+ * 查声明:
+ *  - declared=true, spec=ToolVerifySpec → 按声明校验
+ *  - declared=true, spec=null            → 显式无引用(noRefs),不校验
+ *  - declared=false, spec=null           → 未声明(调用方决定告警/回滚到 legacy 表)
+ */
+export function declaredReferenceSpec(name: string): { declared: boolean, spec: ToolVerifySpec | null } {
+  if (specByName.has(name)) return { declared: true, spec: specByName.get(name) ?? null }
+  return { declared: false, spec: null }
+}
+
+/** 已声明工具名集合(测试/审计用) */
+export function declaredToolNames(): string[] {
+  return [...specByName.keys()].sort()
+}
+
+/** 声明是否「有实质校验内容」(空对象等价于 noRefs,但语义不同:空对象=声明过但无规则) */
+export function specHasRules(spec: ToolVerifySpec | null): boolean {
+  if (!spec) return false
+  return Boolean(
+    (spec.atLeastOne?.length)
+    || (spec.refs?.length)
+    || (spec.nodeLists?.length)
+    || (spec.deepNodeRefs?.length)
+    || (spec.chained?.length),
+  )
+}
+
+/**
+ * 登记制判定(纯函数;注册期调用):
+ *  - 'ok'                已声明(有 references 或显式 noRefs)
+ *  - 'undeclared-write'  写族未声明 → 拒绝登记(注入面与执行面双关)
+ *  - 'undeclared-read'   读族未声明 → 登记 + 告警(限期补齐)
+ */
+export function declarationVerdict(
+  tool: { references?: unknown, noRefs?: boolean },
+  isWriteFamily: boolean,
+): 'ok' | 'undeclared-write' | 'undeclared-read' {
+  if (tool.references || tool.noRefs) return 'ok'
+  return isWriteFamily ? 'undeclared-write' : 'undeclared-read'
+}