aitable-workflow-cli 0.1.13-beta.1

package/templates/aitable-handoff/workflows/group-qa/recipes/issue-classifier.ts

@@ -0,0 +1,120 @@
+/**
+ * 问题排查确定性分类器。
+ *
+ * 规则对齐 conversation-handoff：
+ * 1. AI 字段标准失败模板优先；
+ * 2. 同时包含 docKey + 时间戳时判定为数据源问题；
+ * 3. 其余消息交给普通 answer。
+ */
+
+export type ParsedFailureFields = {
+  errorMessage: string;
+  sheetId: string;
+  recordId: string;
+  fieldId: string;
+  taskId: string;
+};
+
+export type ParsedDataSourceFields = {
+  docKey: string | null;
+  timestamp: string | null;
+  traceId: string | null;
+  taskId: string | null;
+};
+
+export type TroubleshootingRoute =
+  | {
+      route: "troubleshoot";
+      issueType: "ai_field";
+      reason: string;
+      reports: ParsedFailureFields[];
+    }
+  | {
+      route: "troubleshoot";
+      issueType: "data_source";
+      reason: string;
+      parsed: ParsedDataSourceFields;
+    }
+  | {
+      route: "answer";
+      reason: string;
+    };
+
+const FAILURE_REPORT_PATTERN =
+  /生成失败\s*\n+(.+?)\s*\n\n基础信息:\nSheet ID: ([^\n]+)\nRecord ID: ([^\n]+)\nField ID: ([^\n]+)\nTask ID: (\S+)/gs;
+const FAILURE_REPORT_FALLBACK_PATTERN =
+  /\n\n(.+?)\s*\n\n基础信息:\nSheet ID: ([^\n]+)\nRecord ID: ([^\n]+)\nField ID: ([^\n]+)\nTask ID: (\S+)/gs;
+
+/** 提取一条消息中的所有 AI 字段失败报告，按 taskId 去重。 */
+export function matchAllFailureReports(content: string): ParsedFailureFields[] {
+  if (!content) return [];
+  const results: ParsedFailureFields[] = [];
+  const seenTaskIds = new Set<string>();
+
+  for (const pattern of [FAILURE_REPORT_PATTERN, FAILURE_REPORT_FALLBACK_PATTERN]) {
+    for (const match of content.matchAll(pattern)) {
+      const taskId = match[5].trim();
+      if (seenTaskIds.has(taskId)) continue;
+      seenTaskIds.add(taskId);
+      results.push({
+        errorMessage: match[1].trim(),
+        sheetId: match[2].trim(),
+        recordId: match[3].trim(),
+        fieldId: match[4].trim(),
+        taskId,
+      });
+    }
+  }
+  return results;
+}
+
+/** 数据源排查沿用 conversation-handoff 的严格门槛：两个关键词必须同时存在。 */
+function isDataSourceIssue(content: string): boolean {
+  return content.includes("docKey") && content.includes("时间戳");
+}
+
+function parseDataSourceFields(content: string): ParsedDataSourceFields {
+  const docKeyMatch =
+    content.match(/docKey\s*[:::=]\s*([A-Za-z0-9_-]+)/) ??
+    content.match(/docKey\s*[\s\S]{0,4}([A-Za-z0-9]{16,})/);
+  const timestampMatch =
+    content.match(/时间戳\s*[:::=]\s*(\d{10,16})/) ??
+    content.match(/时间戳\s*[\s\S]{0,4}(\d{10,16})/);
+  const traceIdMatch =
+    content.match(/traceId\s*[:::=]\s*([A-Za-z0-9._:/-]+)/) ??
+    content.match(/trace[Ii]d\s*[\s\S]{0,4}([A-Fa-f0-9]{20,})/);
+  const taskIdMatch =
+    content.match(/taskId\s*[:::=]\s*([A-Fa-f0-9]{32})/) ??
+    content.match(/taskId\s*[:::=]\s*([A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12})/) ??
+    content.match(/task[Ii]d\s*[\s\S]{0,4}([A-Fa-f0-9]{32})/);
+
+  return {
+    docKey: docKeyMatch?.[1] ?? null,
+    timestamp: timestampMatch?.[1] ?? null,
+    traceId: traceIdMatch?.[1] ?? null,
+    taskId: taskIdMatch?.[1] ?? null,
+  };
+}
+
+export function classifyTroubleshootingIssue(content: string): TroubleshootingRoute {
+  const reports = matchAllFailureReports(content);
+  if (reports.length > 0) {
+    return {
+      route: "troubleshoot",
+      issueType: "ai_field",
+      reason: `命中 AI 字段标准失败模板（${reports.length} 条）`,
+      reports,
+    };
+  }
+
+  if (isDataSourceIssue(content)) {
+    return {
+      route: "troubleshoot",
+      issueType: "data_source",
+      reason: "同时包含 docKey 和时间戳，命中数据源问题规则",
+      parsed: parseDataSourceFields(content),
+    };
+  }
+
+  return { route: "answer", reason: "未命中确定性问题排查规则" };
+}

package/templates/aitable-handoff/workflows/group-qa/recipes/known-error-match.recipe.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { RecipeDefinition, RecipeContext, RecipeResult } from "aitable-workflow-core";
+import { matchAllFailureReports } from "./issue-classifier.js";
+
+const CONTENT_BLOCKED_KEYWORD = "由于可能涉及敏感内容或临时限制";
+const CONTENT_BLOCKED_REPLY = "抱歉，这条内容可能涉及敏感信息或触发了临时限制，暂时无法生成。可稍后重试；若持续失败，请调整输入内容或联系管理员。";
+
+type ErrorReplies = Record<string, string>;
+let cached: ErrorReplies | null = null;
+function loadErrorReplies(log: (m: string) => void): ErrorReplies {
+  if (cached) return cached;
+  try { cached = JSON.parse(readFileSync(fileURLToPath(new URL("../error-replies.json", import.meta.url)), "utf8")) as ErrorReplies; }
+  catch (e) { log(`error-replies.json 加载失败: ${e instanceof Error ? e.message : String(e)}`); cached = {}; }
+  return cached;
+}
+
+function findMatchingReply(errorMessage: string, replies: ErrorReplies): string | null {
+  if (replies[errorMessage]) return replies[errorMessage];
+  for (const [k, v] of Object.entries(replies)) {
+    if (errorMessage.includes(k) || k.includes(errorMessage)) return v;
+  }
+  return null;
+}
+
+const recipe: RecipeDefinition = {
+  meta: {
+    id: "known-error-match",
+    name: "已知错误秒回",
+    role: "message-classifier",
+    description: "结构化解析 AI 字段报错模板 + error-replies.json 双向匹配 + CONTENT_BLOCKED 安全兜底（不走 LLM）",
+    version: "2.0.0",
+    requiresAgent: false,
+    timeoutMs: 10_000,
+  },
+
+  async execute(ctx: RecipeContext): Promise<RecipeResult> {
+    const { input, log } = ctx;
+    const content = String(input.content ?? "");
+    const senderName = String(input.senderName ?? "").trim();
+    // 空消息透传,本步不产出可留痕内容 → on_demand 下不建行
+    if (!content.trim()) return { status: "success", output: {}, tracker: false, logs: ["空消息"] };
+
+    const reports = matchAllFailureReports(content);
+    if (reports.length === 0) {
+      log("未命中 AI 字段报错模板，交给 answer");
+      // 未命中 → 透传给 answer,本步不留痕
+      return { status: "success", output: {}, tracker: false, logs: ["未命中报错模板"] };
+    }
+    const replies = loadErrorReplies(log);
+    const greeting = senderName ? `Hi ${senderName}，` : "";
+
+    // 有任一 CONTENT_BLOCKED → 安全兜底秒回
+    if (reports.some((r) => r.errorMessage.includes(CONTENT_BLOCKED_KEYWORD))) {
+      log("命中内容安全拦截关键词，安全话术秒回");
+      return { status: "success", output: { message_category: "已知错误", answer: `${greeting}${CONTENT_BLOCKED_REPLY}` }, logs: ["CONTENT_BLOCKED 秒回"] };
+    }
+
+    // 收集命中 error-replies 的话术（多报错合并）
+    const matched = reports.map((r) => findMatchingReply(r.errorMessage, replies)).filter((x): x is string => Boolean(x));
+    if (matched.length > 0) {
+      const uniq = [...new Set(matched)];
+      const answer = `${greeting}以下是针对你反馈问题的说明与解决方案：\n\n${uniq.join("\n\n---\n\n")}`;
+      log(`命中已知错误 ${uniq.length} 条，秒回`);
+      return { status: "success", output: { message_category: "已知错误", answer }, logs: [`命中已知错误 ${uniq.length} 条`] };
+    }
+
+    // 命中报错模板但无已知话术 → UNKNOWN：透传给 answer（其可 Bug 无解转 Owner）
+    log("命中报错模板但无已知话术（UNKNOWN），透传给 answer");
+    // 透传给 answer 决策,本步不留痕(建行与否由 answer 是否回复决定)
+    return { status: "success", output: {}, tracker: false, logs: ["UNKNOWN → 透传 answer"] };
+  },
+};
+
+export default recipe;

package/templates/aitable-handoff/workflows/group-qa/recipes/memory-events.ts

@@ -0,0 +1,55 @@
+import type { MemoryEntry, MemoryScope } from "aitable-workflow-core";
+
+export const HANDOFF_SCENARIO = "aitable-handoff";
+export const HANDOFF_CHANNEL = "dingtalk";
+
+export const HANDOFF_MEMORY_KINDS = {
+  userMessage: "user_message",
+  humanReply: "human_reply",
+  agentDecision: "agent_decision",
+  agentReplySent: "agent_reply_sent",
+  knownErrorReplySent: "known_error_reply_sent",
+  sendFailed: "send_failed",
+} as const;
+
+export type HandoffMemoryKind = typeof HANDOFF_MEMORY_KINDS[keyof typeof HANDOFF_MEMORY_KINDS];
+
+export const HANDOFF_MEMORY_ROLES = {
+  user: "user",
+  human: "human",
+  agent: "agent",
+} as const;
+
+export type HandoffMemoryRole = typeof HANDOFF_MEMORY_ROLES[keyof typeof HANDOFF_MEMORY_ROLES];
+
+export function handoffScope(conversationId?: string): MemoryScope {
+  return {
+    channel: HANDOFF_CHANNEL,
+    scenario: HANDOFF_SCENARIO,
+    ...(conversationId ? { conversationId } : {}),
+  };
+}
+
+export function handoffEntry(args: {
+  kind: HandoffMemoryKind;
+  content: string;
+  sender: string;
+  role: HandoffMemoryRole;
+  conversationId: string;
+  timestamp?: string;
+  summary?: string;
+  meta?: Record<string, unknown>;
+}): MemoryEntry {
+  return {
+    timestamp: args.timestamp ?? new Date().toISOString(),
+    kind: args.kind,
+    content: args.content,
+    summary: args.summary ?? `${args.sender}: ${args.content.slice(0, 80)}`,
+    meta: {
+      sender: args.sender,
+      role: args.role,
+      conversationId: args.conversationId,
+      ...args.meta,
+    },
+  };
+}

package/templates/aitable-handoff/workflows/group-qa/recipes/reply-to-group.recipe.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import type { RecipeDefinition, RecipeContext, RecipeResult, ReplyToConversationOptions } from "aitable-workflow-core";
+import { resolveGlobalVarRef } from "aitable-workflow-core";
+import { HANDOFF_MEMORY_KINDS, HANDOFF_MEMORY_ROLES, handoffEntry, handoffScope } from "./memory-events.js";
+
+/** 群配置(config-sync 发布到 globalVar 的形状)：出站选路与凭据引用据此传给 replyToConversation。 */
+type GroupConfig = { groupId: string; inbound?: string; outbound?: string; credRef?: string };
+
+/** 按来源群活读配置；与事件源/config-sync 同源(${globalVar.group_configs})。 */
+function loadGroupConfig(ctx: RecipeContext, ref: string, conversationId: string): GroupConfig | null {
+  const list = resolveGlobalVarRef(ref, ctx.getGlobalVar) as GroupConfig[] | undefined;
+  if (!Array.isArray(list)) return null;
+  return list.find((g) => g.groupId === conversationId) ?? null;
+}
+
+const recipe: RecipeDefinition = {
+  meta: {
+    id: "reply-to-group",
+    name: "回复群消息",
+    role: "message-sender",
+    description: "通过 messaging toolkit 的 replyToConversation 自动选路回复（session sessionWebhook → webhook 降级），recipe 不感知传输细节",
+    version: "3.0.0",
+    requiresAgent: false,
+    timeoutMs: 30_000,
+    config: z.object({
+      messaging: z.object({
+        robot_creds: z.record(z.string(), z.object({
+          client_id: z.string(),
+          client_secret: z.string(),
+        })).optional(),
+        webhook_creds: z.record(z.string(), z.object({
+          url: z.string(),
+          secret: z.string().optional(),
+        })).optional(),
+      }).optional(),
+      group_configs: z
+        .string()
+        .optional()
+        .describe("群配置来源（globalVar 引用，默认 ${globalVar.group_configs}）：按群路由出站方式(preferWebhook)与凭据引用(credRef)，与事件源/config-sync 同源"),
+    }),
+  },
+
+  async execute(ctx: RecipeContext): Promise<RecipeResult> {
+    const { input, toolkit, log } = ctx;
+    const answer = String(input.answer ?? "");
+    const conversationId = String(input.conversationId ?? "");
+    const category = String(input.message_category ?? "");
+    const groupsRef = String(ctx.config.group_configs ?? "${globalVar.group_configs}");
+
+    // 未发送(静默/无群ID/无webhook) → on_demand 下不建行(纯静默消息不留痕；有正文时建行已由上游 answer/known_error 决定)
+    if (!answer.trim()) { log("无回答内容（静默），跳过"); return { status: "success", output: {}, tracker: false, logs: ["跳过：无回答"] }; }
+    if (!conversationId) { log("缺少群ID，跳过"); return { status: "success", output: {}, tracker: false, logs: ["跳过：群ID 为空"] }; }
+
+    // 按来源群配置选路：出站=webhook 的群强制走 webhook 降级(dws 入站无 sessionWebhook 可用)，
+    // 并用群的凭据引用(credRef)解析命名 webhook 凭据集；出站=session 则不干预，自动走机器人会话内回复。
+    const group = loadGroupConfig(ctx, groupsRef, conversationId);
+    const options: ReplyToConversationOptions = {};
+    if (group?.outbound === "webhook") {
+      options.preferWebhook = true;
+      if (group.credRef) options.credRef = group.credRef;
+    }
+
+    try {
+      const res = await toolkit.messaging.replyToConversation(conversationId, answer, options);
+      const via = res.via;
+      const reason = res.reason;
+      // skipped = 无可用通道、实际未发出：按失败处理，避免假成功掩盖故障(记 send_failed，不记已发送)。
+      if (via === "skipped") {
+        log(`未能发送到群 ${conversationId} (via=skipped${reason ? `, reason=${reason}` : ""})`);
+        try {
+          await toolkit.memory.append(
+            handoffScope(conversationId),
+            handoffEntry({
+              kind: HANDOFF_MEMORY_KINDS.sendFailed,
+              content: answer,
+              sender: "agent",
+              role: HANDOFF_MEMORY_ROLES.agent,
+              conversationId,
+              summary: `答疑机器人发送失败(via=skipped): ${reason ?? "无可用出站通道"}`,
+              meta: { category, sendStatus: "failed", via, ...(reason ? { reason } : {}) },
+            }),
+          );
+        } catch (memErr) {
+          log(`memory.append(send_failed) 失败(不影响主流程): ${memErr instanceof Error ? memErr.message : String(memErr)}`);
+        }
+        return { status: "failed", output: {}, error: `发送群消息失败(via=skipped): ${reason ?? "无可用出站通道"}`, logs: [`未发送(via=skipped)：${conversationId}`] };
+      }
+      log(`已发送到群 ${conversationId} (via=${via}${reason ? `, reason=${reason}` : ""})`);
+      // ─── 记忆叠加：发送成功后按分类写 reply_sent 短期记忆 ───
+      try {
+        await toolkit.memory.append(
+          handoffScope(conversationId),
+          handoffEntry({
+            kind: category === "已知错误" ? HANDOFF_MEMORY_KINDS.knownErrorReplySent : HANDOFF_MEMORY_KINDS.agentReplySent,
+            content: answer,
+            sender: "agent",
+            role: HANDOFF_MEMORY_ROLES.agent,
+            conversationId,
+            summary: `答疑机器人已发送(via=${via}): ${answer.slice(0, 80)}`,
+            meta: { category, sendStatus: "sent", via },
+          }),
+        );
+      } catch (memErr) {
+        log(`memory.append(reply_sent) 失败(不影响主流程): ${memErr instanceof Error ? memErr.message : String(memErr)}`);
+      }
+      return { status: "success", output: {}, logs: [`已发送(via=${via})：${conversationId}`] };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      log(`发送失败: ${msg}`);
+      // ─── 记忆叠加：发送失败写 send_failed 短期记忆 ───
+      try {
+        await toolkit.memory.append(
+          handoffScope(conversationId),
+          handoffEntry({
+            kind: HANDOFF_MEMORY_KINDS.sendFailed,
+            content: answer,
+            sender: "agent",
+            role: HANDOFF_MEMORY_ROLES.agent,
+            conversationId,
+            summary: `答疑机器人发送失败: ${msg}`,
+            meta: { category, sendStatus: "failed", error: msg },
+          }),
+        );
+      } catch (memErr) {
+        log(`memory.append(send_failed) 失败(不影响主流程): ${memErr instanceof Error ? memErr.message : String(memErr)}`);
+      }
+      return { status: "failed", output: {}, error: `发送群消息失败: ${msg}`, logs: [`发送失败: ${msg}`] };
+    }
+  },
+};
+
+export default recipe;

package/templates/aitable-handoff/workflows/group-qa/recipes/troubleshoot-issue.recipe.ts

@@ -0,0 +1,195 @@
+import path from "node:path";
+import { z } from "zod";
+import {
+  resolveGlobalVarRef,
+  type RecipeContext,
+  type RecipeDefinition,
+  type RecipeResult,
+} from "aitable-workflow-core";
+import { classifyTroubleshootingIssue, type TroubleshootingRoute } from "./issue-classifier.js";
+import { HANDOFF_MEMORY_KINDS, HANDOFF_MEMORY_ROLES, handoffEntry, handoffScope } from "./memory-events.js";
+
+type GroupConfig = {
+  groupId?: unknown;
+  troubleshootingEnabled?: unknown;
+};
+
+type TroubleshootingDecision = {
+  shouldReply: boolean;
+  status: "located" | "needs_more_info" | "unable";
+  reason: string;
+  reply?: string;
+  noReplyReason?: string;
+};
+
+/** Recipe 总超时 15 分钟；为输出解析、记忆写入等收尾操作预留 1 分钟。 */
+const RECIPE_TIMEOUT_MS = 15 * 60_000;
+const AGENT_EXECUTION_TIMEOUT_MS = 14 * 60_000;
+const TRUE_VALUES = new Set(["true", "1", "yes", "on", "是", "开启", "启用", "已勾选"]);
+
+function explicitTrue(value: unknown): boolean {
+  if (value === true || value === 1) return true;
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+/** 仅当前来源群明确开启时启用排查；群缺失、字段缺失和未知值都默认关闭。 */
+export function isGroupTroubleshootingEnabled(raw: unknown, conversationId: string): boolean {
+  if (!conversationId || !Array.isArray(raw)) return false;
+  const group = (raw as GroupConfig[]).find((candidate) => String(candidate?.groupId ?? "").trim() === conversationId);
+  return explicitTrue(group?.troubleshootingEnabled);
+}
+
+function extractDecision(raw: string): TroubleshootingDecision | null {
+  if (!raw) return null;
+  let text = raw.trim();
+  const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence?.[1]) text = fence[1].trim();
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+
+  try {
+    const value = JSON.parse(text.slice(start, end + 1)) as Partial<TroubleshootingDecision>;
+    if (typeof value.shouldReply !== "boolean") return null;
+    if (!value.status || !["located", "needs_more_info", "unable"].includes(value.status)) return null;
+    if (typeof value.reason !== "string" || !value.reason.trim()) return null;
+    if (value.shouldReply && (typeof value.reply !== "string" || !value.reply.trim())) return null;
+    if (!value.shouldReply && (typeof value.noReplyReason !== "string" || !value.noReplyReason.trim())) return null;
+    return value as TroubleshootingDecision;
+  } catch {
+    return null;
+  }
+}
+
+function routeEvidence(route: Exclude<TroubleshootingRoute, { route: "answer" }>): string {
+  if (route.issueType === "ai_field") {
+    return JSON.stringify({ issueType: route.issueType, reports: route.reports }, null, 2);
+  }
+  return JSON.stringify({ issueType: route.issueType, ...route.parsed }, null, 2);
+}
+
+function buildPrompt(args: {
+  route: Exclude<TroubleshootingRoute, { route: "answer" }>;
+  content: string;
+  context: string;
+  senderName: string;
+}): string {
+  const { route, content, context, senderName } = args;
+  const imageNote = /!\[图片\]\([^)]+\)/.test(content)
+    ? "\n本条消息包含本地图片引用。先使用 Read 打开图片，并将截图内容作为排查证据。\n"
+    : "";
+
+  return `开始处理前，完整读取并遵循工作目录下的 AGENTS.md，然后完整读取 skills/troubleshooting/SKILL.md，按路由 Skill 选择一个最具体的子 Skill 完成真实排查。
+
+本消息已由确定性规则识别为问题排查，不需要重新判断是否属于普通功能问答。
+
+## 确定性分类
+- 类型：${route.issueType}
+- 原因：${route.reason}
+- 已提取证据：
+${routeEvidence(route)}
+
+## 用户消息
+- 发送者：${senderName || "未知"}
+- 原始内容：
+${content}
+${context ? `\n## 近期对话历史\n${context}\n` : ""}${imageNote}
+完成排查后，严格按 AGENTS.md 的 JSON 契约输出最终结果。技术日志、代码位置和工具过程只能用于内部推理，reply 必须重新组织成简短的业务话术。`;
+}
+
+const recipe: RecipeDefinition = {
+  meta: {
+    id: "troubleshoot-issue",
+    name: "问题排查",
+    role: "faq-troubleshooter",
+    description: "确定性识别 AI 字段未知错误和数据源问题，并由独立排查 Agent 完成排查与回复",
+    version: "1.0.0",
+    requiresAgent: true,
+    timeoutMs: RECIPE_TIMEOUT_MS,
+    config: z.object({
+      conversation_ids: z
+        .string()
+        .optional()
+        .describe("群配置来源（默认 ${globalVar.group_configs}）：是否排查问题仅明确开启时生效"),
+    }),
+  },
+
+  async execute(ctx: RecipeContext): Promise<RecipeResult> {
+    const { input, toolkit, log } = ctx;
+    const content = String(input.content ?? "");
+    const context = String(input.context ?? "").trim();
+    const senderName = String(input.senderName ?? "").trim();
+    const preset = String(input.message_category ?? "").trim();
+    const conversationId = String(input.conversationId ?? "").trim();
+
+    if (preset === "已知错误") {
+      return { status: "success", output: {}, logs: ["已知错误已由上游处理"] };
+    }
+    if (!content.trim()) {
+      return { status: "success", output: {}, logs: ["空消息不进入问题排查"] };
+    }
+
+    const groupsRef = String(ctx.config.conversation_ids ?? "${globalVar.group_configs}");
+    const groupConfigs = resolveGlobalVarRef(groupsRef, ctx.getGlobalVar);
+    if (!isGroupTroubleshootingEnabled(groupConfigs, conversationId)) {
+      log(`群 ${conversationId || "(缺失)"} 未开启问题排查，交给 answer`);
+      return { status: "success", output: {}, logs: ["问题排查未开启"] };
+    }
+
+    const route = classifyTroubleshootingIssue(content);
+    if (route.route === "answer") {
+      log(`${route.reason}，交给 answer`);
+      return { status: "success", output: {}, logs: [route.reason] };
+    }
+
+    const roleId = ctx.roleContext?.id?.trim() || "faq-troubleshooter";
+    const workDir = path.resolve(ctx.configDir, "workspaces", roleId);
+    const prompt = buildPrompt({ route, content, context, senderName });
+    log(`命中 ${route.issueType} 问题排查，启动独立 Agent（workDir=${workDir}）`);
+
+    const result = await toolkit.coding.run(prompt, { workDir, timeoutMs: AGENT_EXECUTION_TIMEOUT_MS });
+    if (!result.response) {
+      log("问题排查 Agent 无输出，降级交给 answer");
+      return { status: "success", output: {}, logs: ["排查无输出 → answer 降级"] };
+    }
+
+    const decision = extractDecision(result.response);
+    if (!decision) {
+      log("问题排查输出无法解析，降级交给 answer");
+      return { status: "success", output: {}, logs: ["排查输出无效 → answer 降级"] };
+    }
+
+    const reason = decision.shouldReply ? decision.reason : decision.noReplyReason!;
+    const answer = decision.shouldReply ? decision.reply!.trim() : "";
+    const output = {
+      message_category: "问题排查",
+      reason,
+      answer,
+    };
+
+    if (conversationId) {
+      void toolkit.memory.append(
+        handoffScope(conversationId),
+        handoffEntry({
+          kind: HANDOFF_MEMORY_KINDS.agentDecision,
+          content: answer || "(静默)",
+          sender: "agent",
+          role: HANDOFF_MEMORY_ROLES.agent,
+          conversationId,
+          summary: `问题排查决策: ${decision.status} - ${reason}`,
+          meta: {
+            shouldReply: decision.shouldReply,
+            status: decision.status,
+            issueType: route.issueType,
+            handler: "troubleshoot-issue",
+          },
+        }),
+      ).catch((error) => log(`memory.append(troubleshooting) 失败(不影响主流程): ${error}`));
+    }
+
+    log(`问题排查完成: type=${route.issueType}, status=${decision.status}, shouldReply=${decision.shouldReply}`);
+    return { status: "success", output, logs: [`问题排查 ${decision.status}`, reason] };
+  },
+};
+
+export default recipe;