agentworkshop 0.7.44 → 0.7.46

package/server/services/workshop/agents/host-tool-bridge/dispatch.ts

@@ -0,0 +1,167 @@
+/**
+ * dispatchHostTool —— 全引擎唯一工具分发入口,只做前置校验 + 路由。
+ *
+ * 分发语义与原实现逐字节对齐:插件工具优先 → workspace 协作/任务/记忆面 →
+ * 工业工具族 → 插件兜底 → 未知工具报错。各工具族的实现体在 tools/* 中按行搬运,
+ * 原先闭包捕获的 (identity / state / args / ws) 一律改为显式参数。
+ *
+ * 两处必须保持的细节:
+ *  - `return await handler(...)`:处理器在 try 内 await,异常才会落回本层的
+ *    「工具执行异常」结果(直接 return 未 await 的 promise 会漏掉这个 catch);
+ *  - 工业工具族在 `getWorkspace()` 门控**之前**分流(只依赖 agentId)。
+ */
+import { getChannelPluginsRepo } from '../../db/channel-plugins.repo'
+import { isHybridTwinChannel } from '../../aml/twin/channel-profile'
+import { listPluginTools, pluginOfTool } from '../plugin-tools'
+import type { HostToolBridgeContext, HostToolCall, HostToolResult } from './types'
+import { INDUSTRIAL_TOOL_NAMES, dispatchIndustrialTool } from './tools/industrial'
+import { handleCompleteTask, handleReportProgress } from './tools/progress'
+import { handleCancelTask, handleDispatchTask, handleGetMyTaskQueue, handleGetTaskDetails, handleListChannelTasks, handleReassignTask, handleRefuseTask, handleSubmitTask, handleUpdateTask } from './tools/tasks'
+import { handleBroadcastMessage, handleListOtherTeams, handlePollMessages, handleReadChannelMail, handleSearchOtherTeamsMemory, handleSendCrossChannelMessage, handleSendMessageToAgent } from './tools/messaging'
+import { handleSaveMemory, handleSearchMemory } from './tools/memory'
+import { handleCreateTeamAgent, handleGetQueueOverview, handleListTeamAgents, handleRemoveTeamAgent, handleUpdateTeamAgent } from './tools/team'
+
+/**
+ * 分发一次 host tool 调用(全引擎唯一入口):
+ * 插件工具优先 → workspace 面 → 工业工具族 → 插件兜底 → 未知工具。
+ */
+export async function dispatchHostTool(ctx: HostToolBridgeContext, req: HostToolCall): Promise<HostToolResult> {
+  const identity = ctx.identity
+  const state = ctx.state
+  // 插件工具分发(ctx.omp.registerTool 注册的自定义工具;不依赖 workspace,优先于内置面)
+  const pluginTool = listPluginTools().get(req.toolName)
+  if (pluginTool) {
+    // 团队级插件开关:显式关闭的插件,其工具在该团队拒绝执行(与注入过滤同源)
+    const channelOff = getChannelPluginsRepo().explicitFor(identity.channelId)
+    const owner = pluginOfTool(req.toolName)
+    if (channelOff && owner && channelOff.get(owner) === false) {
+      return {
+        text: `该团队未启用插件「${owner}」,${req.toolName} 不可用。可在团队设置→插件中开启。`,
+        isError: true,
+      }
+    }
+    try {
+      return await pluginTool.handler(req.arguments ?? {}, identity)
+    }
+    catch (err) {
+      return {
+        text: `工具执行异常(${req.toolName}): ${err instanceof Error ? err.message : String(err)}`,
+        isError: true,
+      }
+    }
+  }
+  const args = req.arguments ?? {}
+
+  if ((req.toolName.startsWith('twin_') || req.toolName === 'mpc_optimize') && !isHybridTwinChannel(identity.channelId)) {
+    return { text: `Channel ${identity.channelId} 未启用 hybrid_twin profile，Twin/MPC 工具拒绝执行。`, isError: true }
+  }
+
+  // 工业工具族不依赖 workspace(只按 agentId 查绑定与节点),先于 workspace 门控执行 ——
+  // 否则 worker 首回合前的 REST/MCP 直调(my_industrial_nodes 等)会被误拒
+  if (INDUSTRIAL_TOOL_NAMES.has(req.toolName)) {
+    return await dispatchIndustrialTool(identity.agentId, req.toolName, args)
+  }
+
+  const ws = ctx.getWorkspace()
+  if (!ws) {
+    return { text: 'workspace 未就绪', isError: true }
+  }
+
+  try {
+    switch (req.toolName) {
+      case 'report_progress':
+        return await handleReportProgress(args, state, ws)
+      case 'complete_task':
+        return await handleCompleteTask(args, state, ws)
+      case 'submit_task':
+        return await handleSubmitTask(args, state, ws)
+      case 'dispatch_task':
+        return await handleDispatchTask(args, ws)
+      case 'send_message_to_agent':
+        return await handleSendMessageToAgent(args, state, ws)
+      case 'send_cross_channel_message':
+        return await handleSendCrossChannelMessage(args, ws)
+      case 'list_other_teams':
+        return await handleListOtherTeams(ws)
+      case 'search_other_teams_memory':
+        return await handleSearchOtherTeamsMemory(args, ws)
+      case 'refuse_task':
+        return await handleRefuseTask(args, ws)
+      case 'poll_messages':
+        return await handlePollMessages(args, state, ws)
+      case 'read_channel_mail':
+        return await handleReadChannelMail(args, ws)
+      case 'broadcast_message':
+        return await handleBroadcastMessage(args, identity, ws)
+      case 'list_channel_tasks':
+        return await handleListChannelTasks(ws)
+      case 'get_my_task_queue':
+        return await handleGetMyTaskQueue(identity, ws)
+      case 'get_queue_overview':
+        return await handleGetQueueOverview(ws)
+      case 'reassign_task':
+        return await handleReassignTask(args, ws)
+      case 'update_task':
+        return await handleUpdateTask(args, ws)
+      case 'cancel_task':
+        return await handleCancelTask(args, ws)
+      case 'list_team_agents':
+        return await handleListTeamAgents(ws)
+      case 'get_task_details':
+        return await handleGetTaskDetails(args, ws)
+      case 'search_memory':
+        return await handleSearchMemory(args, ws)
+      case 'save_memory':
+        return await handleSaveMemory(args, ws)
+      case 'create_team_agent':
+        return await handleCreateTeamAgent(args, ws)
+      case 'update_team_agent':
+        return await handleUpdateTeamAgent(args, ws)
+      case 'remove_team_agent':
+        return await handleRemoveTeamAgent(args, ws)
+
+      // 工业工具族的名册(实现在 tools/industrial.ts):上面 workspace 门控前已分流,
+      // 这里保留同名路由标签,与原分发表逐条对齐(不可达,行为与原实现一致)。
+      case 'my_industrial_nodes':
+      case 'aml_node_catalog':
+      case 'aml_dataset_build':
+      case 'aml_dataset_stats':
+      case 'aml_job_submit':
+      case 'aml_job_status':
+      case 'aml_job_logs':
+      case 'aml_job_cancel':
+      case 'aml_leaderboard':
+      case 'aml_model_promote':
+      case 'aml_model_reference':
+      case 'twin_scene_read':
+      case 'twin_snapshot_create':
+      case 'twin_trial_run':
+      case 'mpc_optimize':
+      case 'twin_gate_evaluate':
+      case 'twin_calibration_request':
+      case 'dcw_control':
+      case 'dcw_read':
+      case 'param_control':
+      case 'param_read':
+      case 'daq_query':
+      case 'daq_frames':
+      case 'dcw_judge':
+      case 'dcw_rollback':
+      case 'dcw_journal':
+      case 'ops_log':
+      case 'recipe_log':
+      case 'line_context':
+      case 'recipe_versions':
+      case 'recipe_update':
+      case 'recipe_rollback':
+        return await dispatchIndustrialTool(identity.agentId, req.toolName, args)
+    }
+    return { text: `未知工具: ${req.toolName}`, isError: true }
+  }
+  catch (err) {
+    return {
+      text: `工具执行异常(${req.toolName}): ${err instanceof Error ? err.message : String(err)}`,
+      isError: true,
+    }
+  }
+}

package/server/services/workshop/agents/host-tool-bridge/index.ts

@@ -0,0 +1,15 @@
+/**
+ * server/services/workshop/agents/host-tool-bridge.ts 拆分后的门面(目录 index 解析,
+ * 外部 import 路径与导出 API 完全不变)。
+ *
+ * 结构:
+ *   types.ts     HostToolCall / HostToolResult / HostToolSessionState / HostToolBridgeContext
+ *   session.ts   会话态 createSessionState 与 partsToText
+ *   catalog.ts   HOST_TOOLS / LEAD_ONLY_TOOL_NAMES / 占位符注入 / hostToolsForRole
+ *   dispatch.ts  dispatchHostTool(前置校验 + 路由)
+ *   tools/       按工具族拆分的处理器:industrial / progress / tasks / messaging / memory / team
+ */
+export { HOST_TOOLS, LEAD_ONLY_TOOL_NAMES, hostToolsForRole } from './catalog'
+export type { HostToolBridgeContext, HostToolCall, HostToolResult, HostToolSessionState } from './types'
+export { createSessionState, partsToText } from './session'
+export { dispatchHostTool } from './dispatch'

package/server/services/workshop/agents/host-tool-bridge/session.ts

@@ -0,0 +1,22 @@
+/**
+ * 会话态构造与消息文本提取(原 host-tool-bridge.ts 的模块级纯函数,按行搬运)。
+ */
+import type { Part } from '../../types/a2a'
+import type { HostToolSessionState } from './types'
+
+export function createSessionState(): HostToolSessionState {
+  return { currentTaskId: null, sourceChatMessageId: null, sourceChatDeliveryId: null, replyContext: null }
+}
+
+/** 从消息 parts 提取纯文本(多 harness 共用) */
+export function partsToText(parts: Part[]): string {
+  return parts
+    .map((p) => {
+      if ('text' in p) return p.text
+      if ('data' in p) return JSON.stringify(p.data)
+      if ('url' in p) return p.url
+      if ('raw' in p) return p.raw
+      return ''
+    })
+    .join('\n')
+}

package/server/services/workshop/agents/host-tool-bridge/tools/industrial.ts

@@ -0,0 +1,64 @@
+/**
+ * 工业工具族(my_industrial_nodes / aml_* / dcw_* / param_* / daq_* / ops_log / recipe_* / line_context)。
+ *
+ * 原 dispatchHostTool 首个 switch 的 26 个转发分支按行搬运到本模块:每个分支都只是
+ * 「按 agentId 查绑定与节点后转交 industrial 模块的同名函数」,因此把闭包捕获的
+ * (identity.agentId, args) 收敛为显式参数,并整理成「工具名 → 处理器」一张表。
+ * 工具名集合与处理器表同源(INDUSTRIAL_TOOL_NAMES 由表键导出),不会出现有名字无处理器的分支。
+ *
+ * 该族**不依赖 workspace**,由 dispatch 在 workspace 门控之前分流(保持原分发顺序)。
+ */
+import type { HostToolResult } from '../types'
+import { toolAmlDatasetBuild, toolAmlDatasetStats, toolAmlJobCancel, toolAmlJobLogs, toolAmlJobStatus, toolAmlJobSubmit, toolAmlLeaderboard, toolAmlModelPromote, toolAmlModelReference, toolAmlNodeCatalog, toolDaqFrames, toolDaqQuery, toolDcwControl, toolDcwJudge, toolDcwJournal, toolDcwRead, toolDcwRollback, toolLineContext, toolMyIndustrialNodes, toolOpsLog, toolParamControl, toolParamRead, toolRecipeLog, toolRecipeRollback, toolRecipeUpdate, toolRecipeVersions, toolTwinSceneRead, toolTwinSnapshotCreate, toolTwinTrialRun, toolMpcOptimize, toolTwinGateEvaluate, toolTwinCalibrationRequest } from '../../industrial'
+
+type IndustrialToolHandler = (agentId: string, args: Record<string, unknown>) => Promise<HostToolResult>
+
+/** 工具名 → 转发处理器(顺序与原 dispatch 首个 switch 的分支顺序一致) */
+const INDUSTRIAL_HANDLERS = new Map<string, IndustrialToolHandler>([
+  ['my_industrial_nodes', agentId => toolMyIndustrialNodes(agentId)],
+  ['aml_node_catalog', agentId => toolAmlNodeCatalog(agentId)],
+  ['aml_dataset_build', (agentId, args) => toolAmlDatasetBuild(agentId, args as Parameters<typeof toolAmlDatasetBuild>[1])],
+  ['aml_dataset_stats', (agentId, args) => toolAmlDatasetStats(agentId, args as Parameters<typeof toolAmlDatasetStats>[1])],
+  ['aml_job_submit', (agentId, args) => toolAmlJobSubmit(agentId, args as Parameters<typeof toolAmlJobSubmit>[1])],
+  ['aml_job_status', (agentId, args) => toolAmlJobStatus(agentId, args as Parameters<typeof toolAmlJobStatus>[1])],
+  ['aml_job_logs', (agentId, args) => toolAmlJobLogs(agentId, args as Parameters<typeof toolAmlJobLogs>[1])],
+  ['aml_job_cancel', (agentId, args) => toolAmlJobCancel(agentId, args as Parameters<typeof toolAmlJobCancel>[1])],
+  ['aml_leaderboard', (agentId, args) => toolAmlLeaderboard(agentId, args as Parameters<typeof toolAmlLeaderboard>[1])],
+  ['aml_model_promote', (agentId, args) => toolAmlModelPromote(agentId, args as Parameters<typeof toolAmlModelPromote>[1])],
+  ['aml_model_reference', (agentId, args) => toolAmlModelReference(agentId, args as Parameters<typeof toolAmlModelReference>[1])],
+  ['twin_scene_read', (agentId, args) => toolTwinSceneRead(agentId, args)],
+  ['twin_snapshot_create', (agentId, args) => toolTwinSnapshotCreate(agentId, args)],
+  ['twin_trial_run', (agentId, args) => toolTwinTrialRun(agentId, args)],
+  ['mpc_optimize', (agentId, args) => toolMpcOptimize(agentId, args)],
+  ['twin_gate_evaluate', (agentId, args) => toolTwinGateEvaluate(agentId, args)],
+  ['twin_calibration_request', (agentId, args) => toolTwinCalibrationRequest(agentId, args)],
+  ['dcw_control', (agentId, args) => toolDcwControl(agentId, args as { node_id?: string, value?: number | string, hypothesis?: string, task_id?: string })],
+  ['dcw_read', (agentId, args) => toolDcwRead(agentId, args as { node_id?: string })],
+  ['param_control', (agentId, args) => toolParamControl(agentId, args as { param?: string, value?: number | string, hypothesis?: string, task_id?: string, line_id?: string })],
+  ['param_read', (agentId, args) => toolParamRead(agentId, args as { param?: string, line_id?: string })],
+  ['daq_query', (agentId, args) => toolDaqQuery(agentId, args as Parameters<typeof toolDaqQuery>[1])],
+  ['daq_frames', (agentId, args) => toolDaqFrames(agentId, args as Parameters<typeof toolDaqFrames>[1])],
+  ['dcw_judge', (agentId, args) => toolDcwJudge(agentId, args as { record_id?: string, verdict?: string, reason?: string })],
+  ['dcw_rollback', (agentId, args) => toolDcwRollback(agentId, args as { record_id?: string, node_id?: string, to?: string })],
+  ['dcw_journal', (agentId, args) => toolDcwJournal(agentId, args as { node_id?: string, recipe_id?: string, limit?: number | string })],
+  ['ops_log', (agentId, args) => toolOpsLog(agentId, args as Parameters<typeof toolOpsLog>[1])],
+  ['recipe_log', (agentId, args) => toolRecipeLog(agentId, args as Parameters<typeof toolRecipeLog>[1])],
+  ['line_context', (agentId, args) => toolLineContext(agentId, args as { line_id?: string })],
+  ['recipe_versions', (agentId, args) => toolRecipeVersions(agentId, args as { recipe_id?: string, limit?: number | string })],
+  ['recipe_update', (agentId, args) => toolRecipeUpdate(agentId, args as Parameters<typeof toolRecipeUpdate>[1])],
+  ['recipe_rollback', (agentId, args) => toolRecipeRollback(agentId, args as Parameters<typeof toolRecipeRollback>[1])],
+])
+
+/** 工业工具名集合(与 INDUSTRIAL_HANDLERS 同源;dispatch 据此在 workspace 门控前分流) */
+export const INDUSTRIAL_TOOL_NAMES: ReadonlySet<string> = new Set(INDUSTRIAL_HANDLERS.keys())
+
+/**
+ * 工业工具族分发:按工具名转交 industrial 模块(调用参数与该族原分支逐字一致)。
+ * 调用方先经 INDUSTRIAL_TOOL_NAMES 判断,故「未登记的工具名」不可达 —— 仍然显式拒绝,
+ * 避免静默返回与未知工具混淆。
+ */
+export function dispatchIndustrialTool(agentId: string, toolName: string, args: Record<string, unknown>): Promise<HostToolResult> {
+  const handler = INDUSTRIAL_HANDLERS.get(toolName)
+  if (!handler) return Promise.reject(new Error(`未知工业工具: ${toolName}`))
+  return handler(agentId, args)
+}

package/server/services/workshop/agents/host-tool-bridge/tools/memory.ts

@@ -0,0 +1,44 @@
+/**
+ * 记忆面(search_memory / save_memory)——原 dispatchHostTool 两个 case 的函数体按行搬运。
+ */
+import type { AgentWorkspace } from '../../agent-interface'
+import type { HostToolResult } from '../types'
+
+export async function handleSearchMemory(args: Record<string, unknown>, ws: AgentWorkspace): Promise<HostToolResult> {
+  const query = args.query as string
+  const scope = (args.scope as 'auto' | 'private' | 'shared' | undefined) ?? 'auto'
+  const snippets = await ws.recallMemory({ query, scope, limit: args.limit as number | undefined })
+  if (snippets.length === 0) {
+    return { text: `记忆检索无命中(query="${query}", scope=${scope})。可尝试更换关键词或放宽 scope。` }
+  }
+  const lines = snippets.map((s) => {
+    // §7.4:每条记忆标注来源 Channel / task / root / 可见性,便于判断可信来源
+    const provenance = [
+      s.source,
+      s.kind,
+      `score=${s.score}`,
+      s.visibility ?? '',
+      s.channelId ? `channel=${s.channelId.slice(0, 8)}` : '',
+      s.taskId ? `task=${s.taskId.slice(0, 8)}` : '',
+      s.rootId ? `root=${s.rootId.slice(0, 8)}` : '',
+      s.createdAt ? s.createdAt.slice(0, 16).replace('T', ' ') : '',
+    ].filter(Boolean).join(' · ')
+    return `  [${provenance}] ${s.title}\n    ${s.content}`
+  })
+  return { text: `记忆检索结果(${snippets.length} 条, scope=${scope}):\n${lines.join('\n')}` }
+}
+
+export async function handleSaveMemory(args: Record<string, unknown>, ws: AgentWorkspace): Promise<HostToolResult> {
+  const title = args.title as string
+  const content = args.content as string
+  const scope = args.scope as 'private' | 'shared'
+  const saved = await ws.saveMemory({
+    title,
+    content,
+    importance: args.importance as number | undefined,
+    scope,
+    dedupKey: args.dedup_key as string | undefined,
+  })
+  const where = scope === 'shared' ? 'Channel 公共记忆(全员可检索)' : '本人私有记忆'
+  return { text: `已沉淀到${where}: "${title}"(dedupKey=${saved.dedupKey})` }
+}

package/server/services/workshop/agents/host-tool-bridge/tools/messaging.ts

@@ -0,0 +1,182 @@
+/**
+ * 通信面(send_message_to_agent / send_cross_channel_message / list_other_teams /
+ * search_other_teams_memory / poll_messages / read_channel_mail / broadcast_message)
+ * ——原 dispatchHostTool 对应 case 的函数体按行搬运,闭包捕获的变量改为显式参数。
+ */
+import type { AgentWorkspace } from '../../agent-interface'
+import type { HostToolBridgeContext, HostToolResult, HostToolSessionState } from '../types'
+import { partsToText } from '../session'
+
+export async function handleSendMessageToAgent(
+  args: Record<string, unknown>,
+  state: HostToolSessionState,
+  ws: AgentWorkspace,
+): Promise<HostToolResult> {
+  const toAgentId = args.to_agent_id as string
+  const message = args.message as string
+  // 回执自动实时:回复(in_reply_to)默认提升为 immediate——
+  // 接收方正等待该结果,realtime 路由会把回复直接注入其运行中的会话
+  let priority = (args.priority as string | undefined) ?? 'task'
+  const metadata: Record<string, unknown> = {}
+  if (args.require_reply === true) metadata['x-aw-require-reply'] = 'true'
+  let inReplyTo = args.in_reply_to as string | undefined
+  // 自动关联兜底:LLM 省略 in_reply_to 时,按待回执上下文盖章
+  const replyCtx = state.replyContext
+  state.replyContext = null
+  if (!inReplyTo && replyCtx && replyCtx.fromId === toAgentId) {
+    inReplyTo = replyCtx.messageId
+  }
+  if (inReplyTo) {
+    metadata['x-aw-in-reply-to'] = inReplyTo
+    if (priority === 'task') priority = 'immediate'
+  }
+  metadata['x-aw-msg-priority'] = priority
+  const sent = await ws.sendMessage({ toAgentId, parts: [{ text: message }], metadata })
+  const triggerNote = inReplyTo
+    ? `(回复 ${inReplyTo.slice(0, 8)}…,已实时推送给对方)`
+    : metadata['x-aw-require-reply'] === 'true' ? '(已要求对方回复)' : ''
+  return { text: `消息 ${sent.messageId.slice(0, 8)}… 已发送给 ${toAgentId}(priority=${priority})${triggerNote}` }
+}
+
+export async function handleSendCrossChannelMessage(args: Record<string, unknown>, ws: AgentWorkspace): Promise<HostToolResult> {
+  const toChannelId = args.to_channel_id as string
+  const message = args.message as string
+  if (!toChannelId || !message) return { text: '缺少 to_channel_id 或 message', isError: true }
+  try {
+    const r = await ws.sendCrossChannelMessage({
+      toChannelId,
+      parts: [{ text: message }],
+      requireReply: args.require_reply === true,
+      inReplyTo: args.in_reply_to as string | undefined,
+    })
+    const note = args.require_reply === true ? '(已要求对方 Leader 回复)' : ''
+    return { text: `跨 Channel 消息 ${r.messageId.slice(0, 8)}… 已送达 channel「${r.toChannelName}」的 Leader(${r.toLeadAgentId.slice(0, 8)}…)${note}。对方将按你的信息需求处理;其回复会经 mailbox 到达你这里。` }
+  }
+  catch (err) {
+    return { text: `跨 Channel 发送失败: ${err instanceof Error ? err.message : String(err)}(仅 Leader 可跨 Channel 通信)`, isError: true }
+  }
+}
+
+export async function handleListOtherTeams(ws: AgentWorkspace): Promise<HostToolResult> {
+  const teams = await ws.listOtherTeams()
+  if (teams.length === 0) return { text: '当前没有其他团队(或均未启用)。' }
+  const text = teams.map((t) => {
+    const active = t.activeTasks.length > 0
+      ? t.activeTasks.map(x => `「${x.title}」(${x.state})`).join('、')
+      : '无进行中任务'
+    const done = t.recentCompleted.length > 0
+      ? t.recentCompleted.map(x => `「${x.title}」`).join('、')
+      : '无'
+    const mem = t.sharedMemories > 0 ? `共享记忆 ${t.sharedMemories} 条(可检索)` : '暂无共享记忆'
+    return `- ${t.name}${t.description ? `(${t.description})` : ''} · lead=${t.leadName ?? '?'} · ${mem}\n  进行中: ${active}\n  近期完成: ${done}\n  channel_id: ${t.channelId}`
+  }).join('\n')
+  return { text: `其他团队概览:\n${text}\n(需要协作时用 send_cross_channel_message 向对应团队 Leader 发信;查具体知识用 search_other_teams_memory)` }
+}
+
+export async function handleSearchOtherTeamsMemory(args: Record<string, unknown>, ws: AgentWorkspace): Promise<HostToolResult> {
+  const query = (args.query as string | undefined) ?? ''
+  if (!query) return { text: '缺少 query', isError: true }
+  const rows = await ws.searchOtherTeamsMemory({ query, limit: Number(args.limit ?? 5) })
+  if (rows.length === 0) return { text: `其他团队的共享记忆中没有命中「${query}」的内容。` }
+  const text = rows.map((r) => {
+    // §7.4:来源 Channel + root/task + 时间 + 可见性必须一起呈现,便于 Lead 判断可信来源
+    const provenance = [
+      `[${r.channelName}]`,
+      r.createdAt.slice(0, 10),
+      r.visibility ?? 'cross-channel',
+      r.taskId ? `task=${r.taskId.slice(0, 8)}` : '',
+      r.rootId ? `root=${r.rootId.slice(0, 8)}` : '',
+    ].filter(Boolean).join(' · ')
+    return `- ${provenance} 「${r.title}」: ${r.content}`
+  }).join('\n')
+  return { text: `其他团队共享记忆命中 ${rows.length} 条:\n${text}` }
+}
+
+export async function handlePollMessages(
+  args: Record<string, unknown>,
+  state: HostToolSessionState,
+  ws: AgentWorkspace,
+): Promise<HostToolResult> {
+  const limit = (args.limit as number | undefined) ?? 10
+  const waitSec = Math.min(180, Math.max(0, Number(args.wait_seconds ?? 0) || 0))
+  const msgs = await ws.waitMailbox(limit, waitSec * 1000)
+  if (msgs.length === 0) {
+    return {
+      text: waitSec > 0
+        ? `等待 ${waitSec}s 后收件箱仍为空。若此前已有"[实时消息 from X]"注入你的会话,那就是回复本身(无需再轮询);否则可继续处理其他工作,对方回复会以新回合送达。`
+        : '收件箱为空(无未消费消息)。等待回复请用 wait_seconds 参数阻塞等待,不要反复空轮询。',
+    }
+  }
+  // 读即取:协作消息(非任务投递)取出即确认;任务指派(assign)不确认
+  const ackIds = msgs
+    .filter(m => !m.metadata?.['x-aw-task-kind'])
+    .map(m => m.messageId)
+  if (ackIds.length > 0) await ws.ackMailbox(ackIds)
+  const trigger = msgs.find(m =>
+    m.metadata?.['x-aw-require-reply'] === 'true'
+    && typeof m.metadata?.['x-aw-from-agent'] === 'string')
+  if (trigger) {
+    state.replyContext = {
+      fromId: String(trigger.metadata!['x-aw-from-agent']),
+      messageId: trigger.messageId,
+    }
+  }
+  const text = msgs.map((m, i) => {
+    const from = m.metadata?.['x-aw-from-agent'] ?? '?'
+    const reply = m.metadata?.['x-aw-in-reply-to']
+      ? ` (回复 ${String(m.metadata['x-aw-in-reply-to']).slice(0, 8)}…)`
+      : ''
+    const needReply = m.metadata?.['x-aw-require-reply'] === 'true'
+      ? ` [需回复:用 send_message_to_agent 回 ${from},in_reply_to=${m.messageId}]`
+      : ''
+    const body = m.parts.map(p => 'text' in p ? p.text : '').join(' ')
+    return `  [${i + 1}/${msgs.length}] [from ${from}]${needReply}${reply} ${body.slice(0, 2000)}`
+  }).join('\n')
+  return {
+    text:
+      `未消费消息(${msgs.length},已读即取):\n${text}`
+      + (msgs.length > 1
+        ? '\n(收到多条:请按编号逐条处理并逐条回复,不要只回应最后一条或合并敷衍)'
+        : ''),
+  }
+}
+
+export async function handleReadChannelMail(args: Record<string, unknown>, ws: AgentWorkspace): Promise<HostToolResult> {
+  const limit = (args.limit as number | undefined) ?? 50
+  const agentId = args.agent_id as string | undefined
+  const mails = await ws.listMail({ limit, agentId })
+  if (mails.length === 0) return { text: 'Channel 无邮件记录(或该成员无往来)' }
+  const text = mails.map((m) => {
+    const from = m.fromAgentId ?? '(系统)'
+    const to = m.toAgentId ?? '(广播)'
+    const body = partsToText(m.parts).trim().slice(0, 2000)
+    const reply = m.metadata?.['x-aw-in-reply-to']
+      ? ` [回复 ${String(m.metadata['x-aw-in-reply-to']).slice(0, 8)}…]`
+      : ''
+    const label = m.metadata?.['x-aw-task-kind'] === 'assign'
+      ? '[任务指派]'
+      : m.metadata?.['x-aw-msg-priority'] === 'immediate' ? '[实时]' : '[协作]'
+    const state = m.state === 'pending' ? '未读' : m.state === 'consuming' ? '处理中' : '已读'
+    return `  ${m.createdAt.slice(11, 19)} ${label} ${from} → ${to} (${state})${reply}: ${body || '(空)'}`
+  }).join('\n')
+  return { text: `Channel 邮件(${mails.length},倒序;可传 agent_id 查看指定成员信箱):\n${text}` }
+}
+
+export async function handleBroadcastMessage(
+  args: Record<string, unknown>,
+  identity: HostToolBridgeContext['identity'],
+  ws: AgentWorkspace,
+): Promise<HostToolResult> {
+  const message = args.message as string
+  const priority = (args.priority as string | undefined) ?? 'task'
+  const agents = await ws.listAgents()
+  const others = agents.filter(a => a.id !== identity.agentId)
+  for (const agent of others) {
+    await ws.sendMessage({
+      toAgentId: agent.id,
+      parts: [{ text: message }],
+      metadata: { 'x-aw-msg-priority': priority },
+    })
+  }
+  return { text: `已广播给 ${others.length} 个 agent(priority=${priority})` }
+}

package/server/services/workshop/agents/host-tool-bridge/tools/progress.ts

@@ -0,0 +1,84 @@
+/**
+ * 进度与完成面(report_progress / complete_task)——原 dispatchHostTool 两个 case 的函数体按行搬运。
+ * 闭包捕获的三样东西改为显式参数:args(调用参数)、state(会话态,完成时清空 currentTaskId)、ws。
+ */
+import { randomUUID } from 'node:crypto'
+import type { AgentWorkspace } from '../../agent-interface'
+import type { A2AArtifact } from '../../../types/a2a'
+import type { HostToolResult, HostToolSessionState } from '../types'
+
+export async function handleReportProgress(
+  args: Record<string, unknown>,
+  state: HostToolSessionState,
+  ws: AgentWorkspace,
+): Promise<HostToolResult> {
+  const progress = args.progress as number
+  const message = args.message as string | undefined
+  const taskId = state.currentTaskId
+  if (!taskId) return { text: '无当前任务上下文', isError: true }
+  await ws.reportTask({ taskId, progress, message })
+  return { text: `进度已上报: ${progress}%${message ? ` (${message})` : ''}` }
+}
+
+export async function handleCompleteTask(
+  args: Record<string, unknown>,
+  state: HostToolSessionState,
+  ws: AgentWorkspace,
+): Promise<HostToolResult> {
+  const summary = args.summary as string
+  const deliverable = args.deliverable as string | undefined
+  const taskId = (args.task_id as string | undefined) ?? state.currentTaskId
+  if (!taskId) return { text: '无任务 ID', isError: true }
+  // 父任务保护:有未完成子任务时拒绝完成(lead 须等 worker 交付)
+  const allTasks = await ws.listTasks()
+  const incompleteChildren = allTasks.filter(t => t.parentId === taskId && t.state !== 'COMPLETED')
+  if (incompleteChildren.length > 0) {
+    return {
+      text: `任务 ${taskId} 有 ${incompleteChildren.length} 个未通过验收的子任务(包含失败/取消)。请先解决或重新指派，再由 Lead 检查交付物并提交验收总结。`,
+      isError: true,
+    }
+  }
+  // 终态幂等:任务已被平台收口(看门狗取消/调度器完成)时不撞状态机 ——
+  // 给 Agent 明确的"无需再完成,继续下一项"信号,杜绝重复重试烧 token
+  const current = await ws.getTask(taskId)
+  if (current && current.state !== 'SUBMITTED' && current.state !== 'ASSIGNED' && current.state !== 'WORKING' && current.state !== 'WAITING') {
+    if (current.state === 'COMPLETED') {
+      return { text: `任务 ${taskId} 已是完成状态(可能已被平台收口),无需重复完成。` }
+    }
+    try {
+      const q = await ws.myQueue()
+      const next = q.queued[0]
+      return {
+        text: `任务 ${taskId} 已被平台${current.state === 'CANCELED' ? '取消(如停滞回收/上级作废)' : '判定失败'},不能再标记完成 —— 这不是你的错误,也无需重试。${next ? `队列还有 ${q.queued.length} 项,下一项「${next.title}」即将开始,请继续处理。` : '队列为空,保持待命。'}`,
+        isError: false,
+      }
+    }
+    catch {
+      return { text: `任务 ${taskId} 已被平台${current.state === 'CANCELED' ? '取消' : '判定失败'},无需再完成,请继续处理队列下一项。` }
+    }
+  }
+  const artifacts: A2AArtifact[] = []
+  if (deliverable || summary) {
+    artifacts.push({
+      artifactId: randomUUID(),
+      name: 'deliverable',
+      parts: [{ text: deliverable ?? summary }],
+    })
+  }
+  await ws.completeTask(taskId, artifacts)
+  state.currentTaskId = null
+  // 完成即衔接:报告队列余量与下一项(状态同步 + 驱动继续处理)
+  try {
+    const q = await ws.myQueue()
+    const next = q.queued[0]
+    if (next) {
+      return {
+        text: `任务 ${taskId} 已完成(状态已同步为 COMPLETED)。你的队列还有 ${q.queued.length} 项待处理,下一项:「${next.title}」(即将自动开始;收到任务指派消息后按工作流执行,完成后同样调用 complete_task)。`,
+      }
+    }
+    return { text: `任务 ${taskId} 已完成(状态已同步为 COMPLETED),队列为空。保持待命:新任务/实时消息会自动到达你的信箱。` }
+  }
+  catch {
+    return { text: `任务 ${taskId} 已完成(状态已同步为 COMPLETED)。` }
+  }
+}