agentworkshop 0.7.66 → 0.7.70

package/server/services/workshop/runtime/scheduler-loop/rules.ts

@@ -5,7 +5,7 @@
 import { SchedulerLoopSnapshot } from './snapshot'
 import type { SchedulerDecision } from './types'
 import type { SupervisionDecision, SupervisionSnapshot } from '../../agents/agent-interface'
-import { TERMINAL_TASK_STATES } from '../../types/task'
+import { failedRetryReady, TERMINAL_TASK_STATES } from '../../types/task'
 
 export abstract class SchedulerLoopRules extends SchedulerLoopSnapshot {
   /** 内置规则引擎兜底(harness 无关) */
@@ -28,6 +28,9 @@ export abstract class SchedulerLoopRules extends SchedulerLoopSnapshot {
         if (!task.parentId) continue
         // ROOT_TIMEOUT 已是超时收口结果,不能被恢复规则重新派发。
         if (task.closeReason === 'ROOT_TIMEOUT') continue
+        // 回退窗:worker 尚未消费本次 FAILED 后重投的 assign 时不再抢先换 lease,
+        // 否则 3 次重试会在 0.4s 内全部变成「旧执行代次」丢弃(实测)。
+        if (!failedRetryReady(task, now)) continue
         if (task.retryCount < 3) {
           const other = this.pickWorker(pool, now, task.assigneeId)
           if (other) {

package/server/services/workshop/runtime/task-engine/transition.ts

@@ -2,6 +2,7 @@
  * TaskEngineTransition —— 状态跃迁与事件应用
  * (拆分层,承 TaskEngineCreate;方法体与原文件逐行一致)
  */
+import { randomUUID } from 'node:crypto'
 import { TaskEngineCreate } from './create'
 import type { AgentEvent } from '../../agents/agent-interface'
 import type { TaskState, WorkspaceTask } from '../../types/task'
@@ -121,6 +122,19 @@ export abstract class TaskEngineTransition extends TaskEngineCreate {
         // 取消触发的 abort 让 omp 回合报 "Interrupted by user")直接忽略 ——
         // 否则会对已 CANCELED 任务撞状态机抛非法迁移(崩溃噪声 + 触发无谓重投)
         if (task.state !== 'WORKING') break
+        // 失败原因入 history:旧实现只迁移 FAILED,任务行 history 为空,
+        // 事后只能从进程日志里猜「为什么失败」(2026-10-19 CANCELED/CHILD_RETRIES_EXHAUSTED 复盘痛点)。
+        {
+          const history = [...task.history, {
+            messageId: randomUUID(),
+            contextId: task.channelId,
+            role: 'ROLE_AGENT' as const,
+            parts: [{ text: `执行失败(${event.error.code}): ${String(event.error.message || '').slice(0, 1000)}` }],
+            metadata: { 'x-aw-system': 'task-failure', 'x-aw-error-code': event.error.code },
+          }]
+          if (history.length > TASK_HISTORY_CAP) history.splice(0, history.length - TASK_HISTORY_CAP)
+          this.repos.tasks.update(taskId, { history })
+        }
         this.transition(taskId, 'FAILED', task.assigneeId)
         break
       }

package/server/services/workshop/tools/catalog-view.ts

@@ -0,0 +1,256 @@
+/**
+ * 工具目录视图:把注册表元数据 + 硬规则资格 + Channel 选择合成为透明化行。
+ *
+ * 读路径无副作用(不写库、不同步);注册表为空时用运行时快照兜底展示。
+ * 硬规则资格完全复用 scopeHostToolsForRole,避免 UI 与注入面两套规则。
+ */
+import { scopeHostToolsForRole } from '../agents/host-tool-bridge/catalog'
+import { pluginManifest } from '../plugins/host.mjs'
+import { getToolRegistryRepo, type ToolRegistryRow, type ToolRole } from '../db/tool-registry.repo'
+import { buildToolRegistrySnapshot } from './registry'
+import { getPolicySnapshot, isChannelToolEnabled } from './policy'
+import type { ToolBlockReason, ToolExclusion } from './types'
+
+export interface ToolEligibilityView {
+  eligible: boolean
+  reason: ToolBlockReason
+  message: string
+}
+
+export interface ToolCatalogRow {
+  name: string
+  label: string
+  description: string
+  source: 'builtin' | 'plugin'
+  plugin: string | null
+  pluginScope: string | null
+  group: string
+  roles: ToolRole[]
+  parameters: Record<string, unknown>
+  available: boolean
+  channelEnabled: boolean
+  eligibility: Record<ToolRole, ToolEligibilityView>
+  effective: Record<ToolRole, boolean>
+}
+
+export interface ChannelToolView {
+  channelId: string
+  mode: 'all' | 'selected'
+  source: 'default' | 'explicit'
+  updatedBy: string
+  updatedAt: string | null
+  stats: {
+    total: number
+    available: number
+    eligibleLead: number
+    eligibleWorker: number
+    effectiveLead: number
+    effectiveWorker: number
+    blocked: number
+    channelDisabled: number
+  }
+  tools: ToolCatalogRow[]
+}
+
+export interface GlobalToolRow extends Omit<ToolCatalogRow, 'channelEnabled' | 'eligibility' | 'effective'> {
+  firstSeenAt: string
+  updatedAt: string
+  definitionHash: string
+  channels: Array<{ id: string, name: string, mode: 'all' | 'selected', enabled: boolean }>
+}
+
+export interface GlobalToolView {
+  lastSyncedAt: string | null
+  stats: { total: number, builtin: number, plugin: number, available: number, disabledByChannels: number }
+  tools: GlobalToolRow[]
+}
+
+function availableRows(): ToolRegistryRow[] {
+  let rows: ToolRegistryRow[] = []
+  try {
+    rows = getToolRegistryRepo().list()
+  }
+  catch { /* DB 不可用 → 运行时快照兜底 */ }
+  if (rows.length > 0) return rows
+  return buildToolRegistrySnapshot().map(row => ({
+    name: row.name,
+    source: row.source,
+    pluginName: row.pluginName ?? '',
+    pluginScope: row.pluginScope ?? '',
+    label: row.label ?? row.name,
+    description: row.description,
+    parameters: row.parameters ?? {},
+    roles: row.roles ?? ['lead', 'worker'],
+    group: row.group ?? '',
+    metadata: row.metadata ?? {},
+    definitionHash: row.definitionHash,
+    available: true,
+    firstSeenAt: '',
+    lastSeenAt: '',
+    updatedAt: '',
+  }))
+}
+
+function pluginState(): { known: boolean, enabled: Set<string> } {
+  try {
+    const manifest = pluginManifest()
+    return { known: manifest.length > 0, enabled: new Set(manifest.filter(p => p.enabled).map(p => p.name)) }
+  }
+  catch {
+    return { known: false, enabled: new Set() }
+  }
+}
+
+function scopeFor(role: ToolRole, channelId: string): { names: Set<string>, excluded: Map<string, ToolExclusion> } {
+  const scope = scopeHostToolsForRole(role, channelId)
+  return { names: new Set(scope.tools.map(t => t.name)), excluded: scope.excluded }
+}
+
+function reasonFor(
+  name: string,
+  row: ToolRegistryRow,
+  scope: { names: Set<string>, excluded: Map<string, ToolExclusion> },
+  available: boolean,
+  channelEnabled: boolean,
+): ToolEligibilityView {
+  if (!available) {
+    return { eligible: false, reason: 'UNAVAILABLE', message: '插件未安装或加载失败' }
+  }
+  if (!scope.names.has(name)) {
+    const ex = scope.excluded.get(name)
+    if (ex) return { eligible: false, reason: ex.reason, message: ex.message }
+    return row.source === 'plugin'
+      ? { eligible: false, reason: 'PLUGIN_DISABLED', message: '插件未启用或未注册' }
+      : { eligible: false, reason: 'PROFILE_DENIED', message: '当前 Channel 档位不开放该工具' }
+  }
+  if (!channelEnabled) {
+    return { eligible: true, reason: 'CHANNEL_TOOL_DISABLED', message: '本 Channel 未启用该工具' }
+  }
+  return { eligible: true, reason: 'OK', message: '' }
+}
+
+export function buildChannelToolView(channelId: string): ChannelToolView {
+  const rows = availableRows()
+  const policy = getPolicySnapshot(channelId)
+  const leadScope = scopeFor('lead', channelId)
+  const workerScope = scopeFor('worker', channelId)
+  const plugins = pluginState()
+
+  const tools: ToolCatalogRow[] = rows.map((row) => {
+    const available = row.available && (row.source !== 'plugin' || !plugins.known || plugins.enabled.has(row.pluginName))
+    const channelEnabled = isChannelToolEnabled(policy, row.name)
+    const lead = reasonFor(row.name, row, leadScope, available, channelEnabled)
+    const worker = reasonFor(row.name, row, workerScope, available, channelEnabled)
+    return {
+      name: row.name,
+      label: row.label,
+      description: row.description,
+      source: row.source,
+      plugin: row.pluginName || null,
+      pluginScope: row.pluginScope || null,
+      group: row.group,
+      roles: row.roles,
+      parameters: row.parameters,
+      available,
+      channelEnabled,
+      eligibility: { lead, worker },
+      effective: {
+        lead: lead.eligible && channelEnabled,
+        worker: worker.eligible && channelEnabled,
+      },
+    }
+  }).sort((a, b) => {
+    if (a.source !== b.source) return a.source === 'builtin' ? -1 : 1
+    const g = a.group.localeCompare(b.group)
+    return g !== 0 ? g : a.name.localeCompare(b.name)
+  })
+
+  return {
+    channelId,
+    mode: policy.mode,
+    source: policy.source,
+    updatedBy: policy.updatedBy,
+    updatedAt: policy.updatedAt,
+    stats: {
+      total: tools.length,
+      available: tools.filter(t => t.available).length,
+      eligibleLead: tools.filter(t => t.eligibility.lead.eligible).length,
+      eligibleWorker: tools.filter(t => t.eligibility.worker.eligible).length,
+      effectiveLead: tools.filter(t => t.effective.lead).length,
+      effectiveWorker: tools.filter(t => t.effective.worker).length,
+      blocked: tools.filter(t => !t.eligibility.lead.eligible && !t.eligibility.worker.eligible).length,
+      channelDisabled: tools.filter(t => !t.channelEnabled && (t.eligibility.lead.eligible || t.eligibility.worker.eligible)).length,
+    },
+    tools,
+  }
+}
+
+/** 全局目录:工具元数据 + 被哪些 Channel 停用 */
+export function buildGlobalToolView(): GlobalToolView {
+  const rows = availableRows()
+  const repo = getToolRegistryRepo()
+  let policies: ReturnType<typeof repo.listPolicies> = []
+  let settings: ReturnType<typeof repo.listAllSettings> = []
+  let names = new Map<string, string>()
+  try {
+    policies = repo.listPolicies()
+    settings = repo.listAllSettings()
+    names = repo.channelNames()
+  }
+  catch { /* DB 不可用 → 无 Channel 使用信息 */ }
+
+  const settingByChannel = new Map<string, Map<string, boolean>>()
+  for (const s of settings) {
+    const m = settingByChannel.get(s.channelId) ?? new Map<string, boolean>()
+    m.set(s.toolName, s.enabled)
+    settingByChannel.set(s.channelId, m)
+  }
+
+  const tools: GlobalToolRow[] = rows.map((row) => {
+    const channels: GlobalToolRow['channels'] = []
+    for (const p of policies) {
+      const setting = settingByChannel.get(p.channelId)
+      const enabled = p.mode === 'selected'
+        ? setting?.get(row.name) === true
+        : setting?.get(row.name) !== false
+      if (!enabled) {
+        channels.push({ id: p.channelId, name: names.get(p.channelId) ?? p.channelId, mode: p.mode, enabled })
+      }
+    }
+    return {
+      name: row.name,
+      label: row.label,
+      description: row.description,
+      source: row.source,
+      plugin: row.pluginName || null,
+      pluginScope: row.pluginScope || null,
+      group: row.group,
+      roles: row.roles,
+      parameters: row.parameters,
+      available: row.available,
+      firstSeenAt: row.firstSeenAt,
+      updatedAt: row.updatedAt,
+      definitionHash: row.definitionHash,
+      channels,
+    }
+  })
+
+  return {
+    lastSyncedAt: (() => {
+      try {
+        return repo.lastSyncedAt()
+      }
+      catch {
+        return null
+      }
+    })(),
+    stats: {
+      total: rows.length,
+      builtin: rows.filter(r => r.source === 'builtin').length,
+      plugin: rows.filter(r => r.source === 'plugin').length,
+      available: rows.filter(r => r.available).length,
+      disabledByChannels: tools.reduce((n, t) => n + t.channels.length, 0),
+    },
+    tools,
+  }
+}

package/server/services/workshop/tools/policy.ts

@@ -0,0 +1,100 @@
+/**
+ * Channel 级工具策略:选择模式 / 逐工具开关 / 执行闸门。
+ *
+ * 硬边界:本模块只负责“在已合格工具集合里做减法”。角色、Channel profile、写守卫、
+ * 插件总开关仍由 host-tool-bridge/catalog 与 dispatch 的既有规则决定;Channel 选择
+ * 不能把被硬规则排除的工具打开。
+ *
+ * 无策略行(默认)= mode='all' + 全部合格工具启用,保证存量 Channel 行为不变。
+ */
+import { getToolRegistryRepo, type ChannelToolPolicySnapshot, type ToolPolicyMode } from '../db/tool-registry.repo'
+import { createLogger } from '../logger'
+
+const log = createLogger('workshop.tool-policy')
+
+let warnedAt = 0
+
+/** 读取策略;DB 故障时降级为默认(全部合格工具启用)并限频告警。 */
+export function getPolicySnapshot(channelId: string): ChannelToolPolicySnapshot {
+  const fallback: ChannelToolPolicySnapshot = {
+    channelId,
+    mode: 'all',
+    source: 'default',
+    updatedBy: '',
+    updatedAt: null,
+    settings: new Map(),
+  }
+  if (!channelId) return fallback
+  try {
+    return getToolRegistryRepo().snapshot(channelId)
+  }
+  catch (err) {
+    if (Date.now() - warnedAt > 60_000) {
+      warnedAt = Date.now()
+      log.warn(`读取 Channel 工具策略失败,降级为默认全启用: ${err instanceof Error ? err.message : String(err)}`)
+    }
+    return fallback
+  }
+}
+
+/** 该 Channel 是否启用某工具(不考虑角色/profile/写守卫)。 */
+export function isChannelToolEnabled(policy: ChannelToolPolicySnapshot, name: string): boolean {
+  if (policy.mode === 'selected') return policy.settings.get(name) === true
+  return policy.settings.get(name) !== false
+}
+
+/** 在已合格工具集合上应用 Channel 选择。无 channelId = 不裁剪(兼容旧调用)。 */
+export function applyChannelToolPolicy<T extends { name: string }>(tools: T[], channelId?: string): T[] {
+  if (!channelId) return tools
+  const policy = getPolicySnapshot(channelId)
+  if (policy.source === 'default') return tools
+  return tools.filter(t => isChannelToolEnabled(policy, t.name))
+}
+
+export type ToolGateReason = 'CHANNEL_TOOL_DISABLED' | 'UNAVAILABLE'
+
+export interface ToolGateResult {
+  blocked: boolean
+  reason?: ToolGateReason
+  message?: string
+}
+
+/**
+ * 执行面闸门:
+ *  - 未知工具不在这里拦截(保持既有“未知工具”错误语义);
+ *  - 目录中存在但当前未注册(unavailable)→ 拒绝;
+ *  - 本 Channel 显式停用 → 拒绝。
+ */
+export function channelToolGate(channelId: string, toolName: string): ToolGateResult {
+  if (!channelId) return { blocked: false }
+  let row: ReturnType<ReturnType<typeof getToolRegistryRepo>['get']>
+  try {
+    row = getToolRegistryRepo().get(toolName)
+  }
+  catch {
+    // 目录不可读时不阻断执行(硬安全规则仍在);与策略读取同一 fail-open 口径
+    return { blocked: false }
+  }
+  if (!row) return { blocked: false }
+  if (!row.available) {
+    return {
+      blocked: true,
+      reason: 'UNAVAILABLE',
+      message: `工具「${toolName}」当前未注册(来源插件未安装或加载失败),不可调用。请让管理员在插件管理中启用对应插件后重试。`,
+    }
+  }
+  const policy = getPolicySnapshot(channelId)
+  if (!isChannelToolEnabled(policy, toolName)) {
+    return {
+      blocked: true,
+      reason: 'CHANNEL_TOOL_DISABLED',
+      message: `本 Channel 已在「设置 → 工具」中停用「${toolName}」。请让 Channel 属主在工具管理中启用后重试;硬规则排除的工具不能通过开关绕过。`,
+    }
+  }
+  return { blocked: false }
+}
+
+/** API 写入前的模式校验 */
+export function normalizeMode(value: unknown): ToolPolicyMode {
+  return value === 'selected' ? 'selected' : 'all'
+}

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

@@ -0,0 +1,263 @@
+/**
+ * 工具注册表同步服务:把运行时工具定义投影到 `tool_registry`。
+ *
+ * 事实源仍是:
+ *  - 内置:`HOST_TOOLS`(host-tools.json 加载结果)
+ *  - 插件:`listPluginTools()`(ctx.omp.registerTool 运行时注册)
+ *
+ * 本模块只写元数据,不参与执行;执行仍走 host-tool-bridge / 插件 handler。
+ * 同步幂等:插件注册/卸载、宿主重载、进程启动、手动 API 均可重复调用。
+ */
+import { createHash } from 'node:crypto'
+import { HOST_TOOLS } from '../agents/host-tool-bridge/catalog'
+import { LEAD_ONLY_TOOL_NAMES } from '../agents/tool-classes'
+import { listPluginTools, onPluginToolsChange, pluginOfTool } from '../agents/plugin-tools'
+import { pluginManifest } from '../plugins/host.mjs'
+import { createLogger } from '../logger'
+import {
+  getToolRegistryRepo,
+  type ToolRegistryUpsert,
+  type ToolRole,
+} from '../db/tool-registry.repo'
+
+const log = createLogger('workshop.tool-registry')
+
+export interface ToolRegistrySyncResult {
+  builtin: number
+  plugin: number
+  total: number
+  unavailable: number
+  at: string
+  reason: string
+}
+
+interface SyncState {
+  last: ToolRegistrySyncResult | null
+  lastError: string
+  timer: ReturnType<typeof setTimeout> | null
+  inFlight: boolean
+  subscribed: boolean
+}
+
+const g = globalThis as typeof globalThis & { __awToolRegistrySync?: SyncState }
+
+function state(): SyncState {
+  return g.__awToolRegistrySync ??= {
+    last: null,
+    lastError: '',
+    timer: null,
+    inFlight: false,
+    subscribed: false,
+  }
+}
+
+/** 稳定序列化(键排序),用于定义哈希;不可序列化值降级为字符串描述。 */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  const obj = value as Record<string, unknown>
+  return `{${Object.keys(obj).sort().map(k => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',')}}`
+}
+
+function safeParameters(value: unknown): { parameters: Record<string, unknown>, error?: string } {
+  try {
+    const clone = JSON.parse(JSON.stringify(value ?? {}))
+    return {
+      parameters: clone && typeof clone === 'object' && !Array.isArray(clone) ? clone as Record<string, unknown> : {},
+    }
+  }
+  catch (err) {
+    return {
+      parameters: {},
+      error: err instanceof Error ? err.message : String(err),
+    }
+  }
+}
+
+/** 展示分组:只影响 UI 归类,不影响权限/注入。 */
+const GROUP_BY_PREFIX: Record<string, string> = {
+  report: 'task',
+  complete: 'task',
+  submit: 'task',
+  dispatch: 'task',
+  reassign: 'task',
+  update: 'task',
+  cancel: 'task',
+  refuse: 'task',
+  get: 'task',
+  list: 'team',
+  create: 'team',
+  remove: 'team',
+  send: 'messaging',
+  broadcast: 'messaging',
+  poll: 'messaging',
+  read: 'messaging',
+  save: 'memory',
+  search: 'memory',
+  daq: 'daq',
+  dcw: 'dcw',
+  ops: 'line',
+  line: 'line',
+  recipe: 'recipe',
+  mes: 'mes',
+  aml: 'aml',
+  twin: 'twin',
+  mpc: 'twin',
+  optimization: 'twin',
+  team: 'team',
+  exp: 'experience',
+  analysis: 'analysis',
+}
+
+function groupOf(name: string, source: 'builtin' | 'plugin', pluginName: string): string {
+  if (source === 'plugin') return pluginName ? `plugin:${pluginName}` : 'plugin'
+  const prefix = name.split('_')[0] ?? name
+  return GROUP_BY_PREFIX[prefix] ?? prefix
+}
+
+function builtinRoles(name: string): ToolRole[] {
+  return LEAD_ONLY_TOOL_NAMES.has(name) ? ['lead'] : ['lead', 'worker']
+}
+
+function hashOf(row: Omit<ToolRegistryUpsert, 'definitionHash'>): string {
+  return createHash('sha256').update(stableStringify({
+    name: row.name,
+    source: row.source,
+    pluginName: row.pluginName ?? '',
+    label: row.label ?? '',
+    description: row.description,
+    parameters: row.parameters ?? {},
+    roles: row.roles ?? [],
+    group: row.group ?? '',
+  })).digest('hex')
+}
+
+/** 当前运行时快照(不写库;单测可直接断言)。 */
+export function buildToolRegistrySnapshot(): ToolRegistryUpsert[] {
+  const out = new Map<string, ToolRegistryUpsert>()
+  for (const tool of HOST_TOOLS) {
+    const safe = safeParameters(tool.parameters)
+    const base: Omit<ToolRegistryUpsert, 'definitionHash'> = {
+      name: tool.name,
+      source: 'builtin',
+      pluginName: '',
+      pluginScope: '',
+      label: tool.label ?? tool.name,
+      description: tool.description,
+      parameters: safe.parameters,
+      roles: builtinRoles(tool.name),
+      group: groupOf(tool.name, 'builtin', ''),
+      metadata: {
+        builtin: true,
+        hidden: Boolean(tool.hidden),
+        ...(safe.error ? { schemaError: safe.error } : {}),
+      },
+    }
+    out.set(tool.name, { ...base, definitionHash: hashOf(base) })
+  }
+
+  let manifest = new Map<string, { version?: string, scope?: string }>()
+  try {
+    manifest = new Map(pluginManifest().map(p => [p.name, { version: p.version, scope: p.scope }]))
+  }
+  catch {
+    // 插件宿主未初始化(单测/极早启动):仍登记插件工具,scope 留空
+  }
+
+  for (const [name, tool] of listPluginTools()) {
+    // 内置同名优先(registerPluginTool 已告警);目录与执行面同口径
+    if (out.has(name)) continue
+    const owner = pluginOfTool(name) ?? ''
+    const meta = manifest.get(owner)
+    const safe = safeParameters(tool.parameters)
+    const base: Omit<ToolRegistryUpsert, 'definitionHash'> = {
+      name,
+      source: 'plugin',
+      pluginName: owner,
+      pluginScope: String(meta?.scope ?? ''),
+      label: tool.label ?? name,
+      description: tool.description,
+      parameters: safe.parameters,
+      roles: tool.roles && tool.roles.length > 0 ? [...tool.roles] : ['lead', 'worker'],
+      group: groupOf(name, 'plugin', owner),
+      metadata: {
+        builtin: false,
+        plugin: owner,
+        pluginVersion: meta?.version ?? '',
+        pluginScope: meta?.scope ?? '',
+        ...(safe.error ? { schemaError: safe.error } : {}),
+      },
+    }
+    out.set(name, { ...base, definitionHash: hashOf(base) })
+  }
+
+  return [...out.values()]
+}
+
+/** 同步一次(同步 SQLite;调用方需要异步时自行包 Promise)。 */
+export function syncToolRegistry(reason = 'manual'): ToolRegistrySyncResult {
+  const st = state()
+  if (st.inFlight) {
+    // 并发同步(插件批量注册):返回上次结果,避免重入事务
+    return st.last ?? { builtin: 0, plugin: 0, total: 0, unavailable: 0, at: new Date().toISOString(), reason: `${reason}:coalesced` }
+  }
+  st.inFlight = true
+  try {
+    const repo = getToolRegistryRepo()
+    const rows = buildToolRegistrySnapshot()
+    repo.upsertMany(rows)
+    const unavailable = repo.markUnavailableExcept(rows.map(r => r.name))
+    const counts = repo.counts()
+    const result: ToolRegistrySyncResult = {
+      builtin: counts.builtin,
+      plugin: counts.plugin,
+      total: counts.total,
+      unavailable,
+      at: new Date().toISOString(),
+      reason,
+    }
+    st.last = result
+    st.lastError = ''
+    log.info(`synced builtin=${result.builtin} plugin=${result.plugin} unavailable=${result.unavailable} total=${result.total} (${reason})`)
+    return result
+  }
+  catch (err) {
+    st.lastError = err instanceof Error ? err.message : String(err)
+    log.warn(`同步失败(${reason}): ${st.lastError}`)
+    throw err
+  }
+  finally {
+    st.inFlight = false
+  }
+}
+
+/** 防抖同步(插件注册/卸载/重载会连续触发)。 */
+export function scheduleToolRegistrySync(reason = 'change', delayMs = 150): void {
+  const st = state()
+  if (st.timer) clearTimeout(st.timer)
+  st.timer = setTimeout(() => {
+    st.timer = null
+    try {
+      syncToolRegistry(reason)
+    }
+    catch { /* 已记录;不拖垮插件装载/请求 */ }
+  }, delayMs)
+  st.timer.unref?.()
+}
+
+/** 启动装配:先同步一次,再订阅插件工具变更(幂等)。 */
+export function initToolRegistrySync(): void {
+  try {
+    syncToolRegistry('boot')
+  }
+  catch { /* boot 同步失败不阻断服务;手动 sync/插件变更会重试 */ }
+  const st = state()
+  if (st.subscribed) return
+  st.subscribed = true
+  onPluginToolsChange(() => scheduleToolRegistrySync('plugin-tools-change'))
+}
+
+export function getToolRegistrySyncState(): { last: ToolRegistrySyncResult | null, lastError: string } {
+  const st = state()
+  return { last: st.last, lastError: st.lastError }
+}

package/server/services/workshop/tools/types.ts

@@ -0,0 +1,19 @@
+/** 工具治理共享类型(目录/策略/UI 共用;纯类型,零运行时依赖)。 */
+
+export type ToolBlockReason
+  = | 'OK'
+    | 'ROLE_DENIED'
+    | 'PROFILE_DENIED'
+    | 'WRITE_GUARD'
+    | 'PLUGIN_DISABLED'
+    | 'CHANNEL_PLUGIN_DISABLED'
+    | 'CHANNEL_TOOL_DISABLED'
+    | 'UNAVAILABLE'
+    | 'UNKNOWN'
+
+export interface ToolExclusion {
+  reason: Exclude<ToolBlockReason, 'OK'>
+  message: string
+}
+
+export type ToolRoleName = 'lead' | 'worker'