aitable-workflow-cli 0.1.13-beta.1

package/templates/support-qa/lib/owner-mention.ts

@@ -0,0 +1,140 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+export type OwnerGroupMention =
+  | { mode: "at"; userId: string }
+  | { mode: "name" };
+
+export type OwnerMentionCommandRunner = (
+  args: string[],
+  timeoutMs: number,
+) => Promise<unknown>;
+
+export type OwnerMentionDeps = {
+  runDws?: OwnerMentionCommandRunner;
+  now?: () => number;
+};
+
+type CacheEntry<T> = { value: T; expiresAt: number };
+
+const execFileAsync = promisify(execFile);
+const DWS_TIMEOUT_MS = 8_000;
+const MEMBER_CACHE_TTL_MS = 10 * 60_000;
+const MEMBER_CACHE_MAX = 500;
+
+const memberCache = new Map<string, CacheEntry<OwnerGroupMention>>();
+let commandRunnerOverride: OwnerMentionCommandRunner | undefined;
+
+function getCached<T>(
+  cache: Map<string, CacheEntry<T>>,
+  key: string,
+  now: number,
+): T | undefined {
+  const hit = cache.get(key);
+  if (!hit) return undefined;
+  if (hit.expiresAt <= now) {
+    cache.delete(key);
+    return undefined;
+  }
+  // Map 插入顺序作为轻量 LRU；命中后移到队尾。
+  cache.delete(key);
+  cache.set(key, hit);
+  return hit.value;
+}
+
+function setCached<T>(
+  cache: Map<string, CacheEntry<T>>,
+  key: string,
+  value: T,
+  expiresAt: number,
+  max: number,
+): void {
+  cache.delete(key);
+  cache.set(key, { value, expiresAt });
+  while (cache.size > max) {
+    const oldest = cache.keys().next().value as string | undefined;
+    if (oldest === undefined) break;
+    cache.delete(oldest);
+  }
+}
+
+async function defaultRunDws(args: string[], timeoutMs: number): Promise<unknown> {
+  const { stdout } = await execFileAsync("dws", args, {
+    encoding: "utf8",
+    timeout: timeoutMs,
+    maxBuffer: 5 * 1024 * 1024,
+  });
+  return JSON.parse(String(stdout));
+}
+
+function memberList(payload: unknown): Array<Record<string, unknown>> {
+  if (!payload || typeof payload !== "object") return [];
+  const obj = payload as Record<string, unknown>;
+  const result = obj.result;
+  if (!result || typeof result !== "object" || Array.isArray(result)) return [];
+  const members = (result as Record<string, unknown>).members;
+  return Array.isArray(members)
+    ? members.filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item))
+    : [];
+}
+
+function readOpenDingTalkId(item: Record<string, unknown>): string {
+  const value = item.openDingTalkId ?? item.openDingtalkId;
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * 判定 Owner 是否能在目标群真实 @。
+ *
+ * Owner 的 userId/openDingTalkId 由 config-sync 从功能模块人员配置表解析
+ * （dws contact user get→search 链路）后随快照传入，这里只做群成员在群校验。
+ * 任一参数、命令、超时或响应解析失败都返回 name；本函数不向主流程抛错。
+ */
+export async function resolveOwnerGroupMention(
+  conversationId: string,
+  owner: { userId: string; openDingTalkId?: string },
+  deps: OwnerMentionDeps = {},
+): Promise<OwnerGroupMention> {
+  const cid = String(conversationId ?? "").trim();
+  const userId = String(owner?.userId ?? "").trim();
+  const openDingTalkId = String(owner?.openDingTalkId ?? "").trim();
+  if (!cid || !userId || !openDingTalkId) return { mode: "name" };
+
+  const now = (deps.now ?? Date.now)();
+  const cacheKey = `${cid}\u0000${userId}\u0000${openDingTalkId}`;
+  const cached = getCached(memberCache, cacheKey, now);
+  if (cached !== undefined) return cached;
+
+  const fallback: OwnerGroupMention = { mode: "name" };
+  const runDws = deps.runDws ?? commandRunnerOverride ?? defaultRunDws;
+
+  let result: OwnerGroupMention = fallback;
+  try {
+    const payload = await runDws([
+      "chat", "group", "members", "list-by-ids",
+      "--id", cid,
+      "--users", openDingTalkId,
+      "--format", "json",
+      "--timeout", "8",
+    ], DWS_TIMEOUT_MS);
+    const matched = memberList(payload).some((member) => readOpenDingTalkId(member) === openDingTalkId);
+    if (matched) result = { mode: "at", userId };
+  } catch {
+    result = fallback;
+  }
+
+  setCached(memberCache, cacheKey, result, now + MEMBER_CACHE_TTL_MS, MEMBER_CACHE_MAX);
+  return result;
+}
+
+/** 仅供单测隔离模块级缓存。 */
+export function resetOwnerMentionCachesForTests(): void {
+  memberCache.clear();
+}
+
+/** 仅供 recipe 单测注入 dws runner；传 undefined 恢复真实命令。 */
+export function setOwnerMentionCommandRunnerForTests(
+  runner?: OwnerMentionCommandRunner,
+): void {
+  commandRunnerOverride = runner;
+}

package/templates/support-qa/lib/owner-resolver.ts

@@ -0,0 +1,94 @@
+/**
+ * Owner 身份确定性解析（spec §8）
+ *
+ * 输入 Agent 给出的 module，按「精确 key 查找，不做扩展词/模糊匹配/二次 LLM」解析：
+ *   module → 功能模块人员配置表快照（config-sync 发布到 ${globalVar.module_owners}）
+ *
+ * 快照由 config-sync 定时从 AI 表格「功能模块人员配置表」（模块-文本 + 人员-人员字段）
+ * 拉取，人员经 dws contact user get→search 链式解析出 userId/nick/openDingTalkId 后
+ * 才会入快照，因此本模块只做纯查找，不再回读文件、不再二次解析联系人。
+ *
+ * Owner 数组视为「主负责人 + 备选负责人」：取第一个 Owner 作为主负责人（群内只 @ 一人）。
+ */
+
+export type OwnerResolution =
+  | {
+      status: "resolved";
+      module: string;
+      ownerName: string;
+      ownerUserId: string;
+      ownerOpenDingTalkId?: string;
+    }
+  | {
+      status: "failed";
+      module: string;
+      reason: "missing_module" | "unknown_module" | "missing_contact" | "invalid_config";
+    };
+
+export type OwnerContact = {
+  userId: string;
+  nick: string;
+  openDingTalkId: string;
+};
+
+export type ModuleOwners = {
+  module: string;
+  owners: OwnerContact[];
+};
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function cellString(v: unknown): string {
+  return typeof v === "string" ? v.trim() : typeof v === "number" ? String(v) : "";
+}
+
+/**
+ * 模块人员快照标准化（config-sync 发布前与消费端共用）：
+ * 丢弃缺 module 的行、缺 userId/nick/openDingTalkId 的人；按 module 排序保证快照稳定。
+ */
+export function normalizeModuleOwners(raw: unknown): ModuleOwners[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value): ModuleOwners[] => {
+    const record = asRecord(value);
+    const module = cellString(record?.module);
+    if (!module) return [];
+    const owners = (Array.isArray(record?.owners) ? record.owners : [])
+      .flatMap((o): OwnerContact[] => {
+        const contact = asRecord(o);
+        const userId = cellString(contact?.userId);
+        const nick = cellString(contact?.nick);
+        const openDingTalkId = cellString(contact?.openDingTalkId);
+        return userId && nick && openDingTalkId ? [{ userId, nick, openDingTalkId }] : [];
+      });
+    return owners.length > 0 ? [{ module, owners }] : [];
+  }).sort((left, right) => (
+    left.module.localeCompare(right.module)
+    || JSON.stringify(left).localeCompare(JSON.stringify(right))
+  ));
+}
+
+export function resolveOwner(snapshot: unknown, rawModule: string): OwnerResolution {
+  const module = String(rawModule ?? "").trim();
+  if (!module) return { status: "failed", module, reason: "missing_module" };
+
+  const moduleOwners = normalizeModuleOwners(snapshot);
+  if (moduleOwners.length === 0) return { status: "failed", module, reason: "invalid_config" };
+
+  // 精确 module 匹配（禁止扩展词/子串/模糊匹配）
+  const matched = moduleOwners.find((entry) => entry.module === module);
+  if (!matched) return { status: "failed", module, reason: "unknown_module" };
+
+  const owner = matched.owners[0];
+  if (!owner) return { status: "failed", module, reason: "missing_contact" };
+  return {
+    status: "resolved",
+    module,
+    ownerName: owner.nick,
+    ownerUserId: owner.userId,
+    ownerOpenDingTalkId: owner.openDingTalkId,
+  };
+}

package/templates/support-qa/lib/profile-guard.ts

@@ -0,0 +1,55 @@
+import type { RecipeContext, RecipeResult } from "aitable-workflow-core";
+import { ensureAssembled } from "./assemble.js";
+
+/**
+ * L3 直出路径共享的 profile 装配闸门（评审 P1）
+ *
+ * fastpath / troubleshoot 排在 answer 之前，命中即直接产出回答并让 answer 跳过。若只有
+ * answer 做 ensureAssembled 校验，则 profile 装配错误（overlay 放开闸门、KB collection
+ * 缺失、role 解析失败等）下 fastpath / troubleshoot 仍可能带病作答，违背“profile 错误
+ * 阻断作答 / 闸门只准收紧”的纪律。故所有会直接产出回答的 recipe 在执行实际逻辑前都调用本闸门。
+ *
+ * 返回：
+ *   - RecipeResult —— 存在装配 error：阻断作答的 agent_failure 静默（tracker:false，
+ *     留痕与否交 on_action 按策略裁决）；
+ *   - RecipeResult —— 本次发生写入（wrote 非空）：配置刚被自动更新，同一进程内
+ *     已加载的 workflow/role 可能仍是旧值，阻断作答并提示重启（正常 npm 入口已在
+ *     进程启动前完成装配，不会走到这里；这是直接执行 aitable-workflow run 的兜底）；
+ *   - null —— 无 error 且无写入，放行。
+ *
+ * ensureAssembled 按 configDir 进程内缓存，重复调用（同一消息经 fastpath→troubleshoot→answer
+ * 多步）无额外磁盘开销。
+ */
+export function profileAssembleGuard(
+  ctx: RecipeContext,
+  log: (msg: string) => void,
+): RecipeResult | null {
+  const asm = ensureAssembled(ctx.configDir, log);
+  const errors = asm.issues.filter((i) => i.level === "error");
+  if (errors.length === 0 && asm.wrote.length === 0) return null;
+  if (errors.length > 0) {
+    log(`profile 校验失败（${errors.length} 个错误），阻断作答`);
+    return {
+      status: "success",
+      output: {
+        action: "agent_failure",
+        answer: "",
+        reason: `profile 校验失败: ${errors[0]!.message}`,
+      },
+      tracker: false, // 留痕与否由 on_action 按 agent_failure 策略裁决
+      logs: ["profile 校验失败 → 阻断作答", errors[0]!.message],
+    };
+  }
+  // 本次装配发生了写入：不在同一进程内带着刚改写的配置继续运行
+  log(`profile 配置已自动更新（${asm.wrote.length} 个文件），请重启进程后继续（推荐用 npm run run / npm run setup 入口）`);
+  return {
+    status: "success",
+    output: {
+      action: "agent_failure",
+      answer: "",
+      reason: "配置已自动更新，需重启进程后生效",
+    },
+    tracker: false,
+    logs: ["装配发生写入 → 阻断本次作答，请重启"],
+  };
+}

package/templates/support-qa/lib/profile.ts

@@ -0,0 +1,51 @@
+import type { SupportAction } from "./contract.js";
+
+/**
+ * support-qa 处置策略类型 + 默认值（拍平 action 模型）
+ *
+ * profile v2 后 loadProfile() 已废弃（由 core profile-loader 统一注入 ctx.config）：
+ * on-action 步从 ctx.config.policies 读逐 action 覆写（profile.yml 的
+ * workflows.group-qa.steps.on_action.policies 段），在 recipe 内与默认值 spread 合并
+ * （与 dev 基线 on_silence 的读取方式一致）；本文件仅保留类型与常量。
+ * group 合法值由 assemble preflight 闭集校验把关（answer/silent，无 notify_owner）。
+ */
+
+/**
+ * 群内行为（轴1：只管群里说不说话）：
+ * - `answer`：发送回答；
+ * - `silent`：群里不说话（留痕与通知字段不受影响）。
+ *
+ * 是否附 Owner 指引（轴2）**不由本字段控制**，由 Runtime 按
+ * 「action 是否需要找人 + Owner 能不能解析出来」派生（见 action-dispatch 的
+ * needsOwnerResolution）——两个轴正交，`answer` 也能带 Owner 尾注。
+ */
+export type GroupAction = "answer" | "silent";
+
+export type ActionPolicy = {
+  /** 是否建行留痕（tracker materialize） */
+  track: boolean;
+  /** 群里做什么（不用裸字段 silence：group: silent 只表示群内不说话，留痕由 track 单独表达） */
+  group: GroupAction;
+};
+
+/** profile.yml 里 policies 段的原始形状（逐 action 局部覆写） */
+export type ActionPolicyOverrides = Partial<Record<SupportAction, Partial<ActionPolicy>>>;
+
+/** 群内是否说话（轴1 的唯一判定点） */
+export function speaksInGroup(policy: ActionPolicy): boolean {
+  return policy.group !== "silent";
+}
+
+/** Pattern 默认 action 处置（spec §7.1）：可被 policies 逐项覆写（recipe 内 spread 合并） */
+export const DEFAULT_ON_ACTION: Record<SupportAction, ActionPolicy> = {
+  reply: { track: true, group: "answer" },
+  // bug/feature 群内说话；Owner 尾注由 Runtime 派生附加（不在 group 里表达）
+  bug: { track: true, group: "answer" },
+  feature: { track: true, group: "answer" },
+  kb_gap: { track: true, group: "silent" },
+  no_question: { track: false, group: "silent" },
+  human_handled: { track: false, group: "silent" },
+  owner_mentioned: { track: true, group: "silent" },
+  safety: { track: true, group: "silent" },
+  agent_failure: { track: true, group: "silent" },
+};

package/templates/support-qa/lib/send-failure-guard.ts

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+
+/**
+ * 发送失败留痕去重（send_failure guard）
+ *
+ * 背景：发送失败会被步骤重试 + 外层重投多次驱动（真实案例：同一条待发内容、同一
+ * "无可用 sessionWebhook" 原因，在 1.5 分钟内写了 18 条 send_failed）。失败重试本身是
+ * 对的，但每次尝试都往短期记忆里追加一条，会把同一个故障放大成十几条同质记录：
+ * 复盘的 sendFailedCount 被严重虚高，学习语料里也全是重复噪声。
+ *
+ * 方案：按「群 + 待发内容 + 失败原因」做窗口内去重——同一故障只记第一次；窗口过后
+ * 若仍失败则再记一次（作为"故障持续"的新信号）。不同内容或不同原因永不互相吞掉。
+ *
+ * 注意：这里去重的只是「留痕」，不改变发送重试与 step 失败语义。
+ */
+
+const VAR_KEY = "send_failure_marks";
+const CAPACITY = 50;
+const TTL_MS = 10 * 60 * 1000;
+
+type Mark = { h: string; ts: number };
+
+function loadList(get: (key: string) => unknown): Mark[] {
+  const raw = get(VAR_KEY);
+  if (!Array.isArray(raw)) return [];
+  const now = Date.now();
+  return (raw as Mark[]).filter((m) => m && typeof m.h === "string" && now - m.ts <= TTL_MS);
+}
+
+export function sendFailureFingerprint(args: { conversationId: string; content: string; reason: string }): string {
+  const normalized = [
+    args.conversationId,
+    args.content.replace(/\s+/g, "").slice(0, 300),
+    args.reason.replace(/\s+/g, "").slice(0, 200),
+  ].join("|");
+  return createHash("sha1").update(normalized).digest("hex");
+}
+
+/**
+ * 是否应为本次发送失败写短期记忆。
+ * 首次出现 → 登记并返回 true；窗口内同签名重试 → 返回 false（调用方只记日志）。
+ */
+export function shouldRecordSendFailure(
+  get: (key: string) => unknown,
+  set: (key: string, value: unknown) => void,
+  args: { conversationId: string; content: string; reason: string },
+): boolean {
+  const h = sendFailureFingerprint(args);
+  const list = loadList(get);
+  if (list.some((m) => m.h === h)) {
+    // 仍写回裁剪后的列表：顺带完成 TTL 清理，避免只读路径让过期项常驻
+    set(VAR_KEY, list);
+    return false;
+  }
+  list.push({ h, ts: Date.now() });
+  while (list.length > CAPACITY) list.shift();
+  set(VAR_KEY, list);
+  return true;
+}

package/templates/support-qa/lib/troubleshoot.ts

@@ -0,0 +1,236 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+
+/**
+ * troubleshoot 声明式分类器引擎（support-qa L3，场景层，零 core 依赖）
+ *
+ * 取代 aitable-handoff 硬编码的 issue-classifier.ts：把「命中哪种问题类型」从代码正则
+ * 收敛为 profile/troubleshoot/classifiers.yml 的声明式规则。每个分类器：
+ *   - issueType：命中后的问题类型标签（如 ai_field / data_source）；
+ *   - module   ：可选，命中后透传给下游的 Owner 模块名（必须是 owner-map.json 精确 key）；
+ *     未定位异常据此路由到模块 Owner，不再固定输出空 module；
+ *   - patterns ：匹配条件列表，每条 contains|regex；
+ *   - require_all：默认 false（任一命中）；true 时需全部命中（如数据源问题需
+ *                  docKey + 时间戳 同时存在）；
+ *   - extract  ：可选，字段名→正则（取第一个捕获组），把结构化证据带进排查 prompt。
+ *
+ * 分类结果为 null 表示「未命中确定性排查规则」→ 交给语义答疑 answer。
+ *
+ * 整档开关（gate）：
+ *   - profile.troubleshoot.skills_dir 未配置或该目录不存在 → 整档关闭（isTroubleshootEnabled=false）；
+ *   - 按群开关：群配置表 troubleshootingEnabled 明确为真才对该群启用（isGroupTroubleshootingEnabled）。
+ */
+
+const troubleshootPatternSchema = z.object({
+  contains: z.string().optional(),
+  regex: z.string().optional(),
+}).refine(
+  (p) => Boolean(p.contains?.trim()) !== Boolean(p.regex?.trim()),
+  { message: "必须且只能有 contains/regex 之一" },
+);
+
+export const classifiersSchema = z.object({
+  classifiers: z.array(z.object({
+    issueType: z.string().min(1),
+    reason: z.string().optional(),
+    patterns: z.array(troubleshootPatternSchema).min(1),
+    require_all: z.boolean().optional(),
+    extract: z.record(z.string(), z.string()).optional(),
+  })),
+});
+
+export type TroubleshootPattern = { contains?: string; regex?: string; compiledRegex?: RegExp };
+
+export type ClassifierDef = {
+  issueType: string;
+  /** 可选：Owner 路由模块名（owner-map.json 精确 key），命中时透传到分类结果 */
+  module?: string;
+  reason: string;
+  patterns: TroubleshootPattern[];
+  requireAll: boolean;
+  /** 字段名 → 正则（取第一个捕获组）；未命中该字段填 null */
+  extract: Record<string, string>;
+};
+
+export type TroubleshootConfig = { classifiers: ClassifierDef[] };
+
+export type ClassifyResult = {
+  issueType: string;
+  module?: string;
+  reason: string;
+  extracted: Record<string, string | null>;
+};
+
+export type TroubleshootLoadResult = {
+  /** null = 未配置或文件缺失/无有效分类器（交给 answer） */
+  config: TroubleshootConfig | null;
+  issues: string[];
+};
+
+const cache = new Map<string, TroubleshootLoadResult>();
+
+/** 加载并校验分类器；按解析后的绝对路径缓存 */
+export function loadClassifiers(configDir: string, classifiersRel: string | undefined): TroubleshootLoadResult {
+  const rel = String(classifiersRel ?? "").trim();
+  if (!rel) return { config: null, issues: [] };
+  const abs = path.resolve(configDir, "profile", rel);
+  const hit = cache.get(abs);
+  if (hit) return hit;
+
+  let res: TroubleshootLoadResult;
+  if (!existsSync(abs)) {
+    res = { config: null, issues: [`troubleshoot.classifiers 引用的文件不存在: profile/${rel}`] };
+  } else {
+    try {
+      const raw = (parseYaml(readFileSync(abs, "utf8")) ?? {}) as Record<string, unknown>;
+      const issues: string[] = [];
+      const classifiers = normalizeClassifiers(raw, issues);
+      res = { config: classifiers.length > 0 ? { classifiers } : null, issues };
+    } catch (err) {
+      res = { config: null, issues: [`troubleshoot 分类器解析失败 profile/${rel}: ${err instanceof Error ? err.message : String(err)}`] };
+    }
+  }
+  cache.set(abs, res);
+  return res;
+}
+
+function normalizeClassifiers(raw: Record<string, unknown>, issues: string[]): ClassifierDef[] {
+  const out: ClassifierDef[] = [];
+  const rawList = Array.isArray(raw.classifiers) ? raw.classifiers : [];
+  for (let i = 0; i < rawList.length; i++) {
+    const c = rawList[i] as Record<string, unknown> | null;
+    if (!c || typeof c !== "object") {
+      issues.push(`classifiers[${i}] 不是对象`);
+      continue;
+    }
+    const issueType = String(c.issueType ?? "").trim();
+    if (!issueType) {
+      issues.push(`classifiers[${i}] 缺少 issueType`);
+      continue;
+    }
+    const patterns = normalizePatterns(c.patterns, issueType, issues);
+    if (patterns.length === 0) {
+      issues.push(`classifiers[${issueType}] 无有效 patterns`);
+      continue;
+    }
+    const extract: Record<string, string> = {};
+    const rawExtract = c.extract as Record<string, unknown> | undefined;
+    if (rawExtract && typeof rawExtract === "object") {
+      for (const [field, rx] of Object.entries(rawExtract)) {
+        const pattern = String(rx ?? "");
+        try {
+          new RegExp(pattern);
+          extract[field] = pattern;
+        } catch {
+          issues.push(`classifiers[${issueType}].extract.${field} 非法正则: ${pattern}`);
+        }
+      }
+    }
+    out.push({
+      issueType,
+      ...(String(c.module ?? "").trim() ? { module: String(c.module).trim() } : {}),
+      reason: String(c.reason ?? `命中 ${issueType} 分类规则`).trim(),
+      patterns,
+      requireAll: c.require_all === true,
+      extract,
+    });
+  }
+  return out;
+}
+
+function normalizePatterns(raw: unknown, issueType: string, issues: string[]): TroubleshootPattern[] {
+  const out: TroubleshootPattern[] = [];
+  for (const p of Array.isArray(raw) ? raw : []) {
+    if (!p || typeof p !== "object") continue;
+    const rec = p as Record<string, unknown>;
+    const hasContains = typeof rec.contains === "string" && rec.contains.trim();
+    const hasRegex = typeof rec.regex === "string" && String(rec.regex).trim();
+    if (Boolean(hasContains) === Boolean(hasRegex)) {
+      issues.push(`classifiers[${issueType}] 每条 pattern 必须且只能有 contains/regex 之一`);
+      continue;
+    }
+    if (hasContains) {
+      out.push({ contains: String(rec.contains) });
+    } else {
+      const rx = String(rec.regex);
+      try {
+        out.push({ regex: rx, compiledRegex: new RegExp(rx) });
+      } catch {
+        issues.push(`classifiers[${issueType}] 非法正则: ${rx}`);
+      }
+    }
+  }
+  return out;
+}
+
+function testPattern(p: TroubleshootPattern, message: string): boolean {
+  if (p.contains !== undefined) return message.includes(p.contains);
+  if (p.compiledRegex) return p.compiledRegex.test(message);
+  return false;
+}
+
+function extractFields(extract: Record<string, string>, message: string): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (const [field, rx] of Object.entries(extract)) {
+    try {
+      const m = message.match(new RegExp(rx));
+      out[field] = m?.[1] ?? m?.[0] ?? null;
+    } catch {
+      out[field] = null;
+    }
+  }
+  return out;
+}
+
+/**
+ * 分类当前消息：按声明顺序返回第一个满足的分类器（require_all→全部 pattern 命中；否则任一命中）。
+ * 无命中返回 null（交语义答疑 answer）。
+ */
+export function classifyIssue(config: TroubleshootConfig | null, message: string): ClassifyResult | null {
+  if (!config) return null;
+  const msg = message ?? "";
+  if (!msg.trim()) return null;
+  for (const c of config.classifiers) {
+    const ok = c.requireAll
+      ? c.patterns.every((p) => testPattern(p, msg))
+      : c.patterns.some((p) => testPattern(p, msg));
+    if (ok) {
+      return {
+        issueType: c.issueType,
+        ...(c.module ? { module: c.module } : {}),
+        reason: c.reason,
+        extracted: extractFields(c.extract, msg),
+      };
+    }
+  }
+  return null;
+}
+
+// ─── 整档开关 ────────────────────────────────────────────
+
+/**
+ * troubleshoot 是否整档启用：profile.troubleshoot.skills_dir 已配置且该目录存在。
+ * skills_dir 相对实例根解析；未配置或目录缺失 → 整档关闭（spec §8）。
+ */
+export function isTroubleshootEnabled(configDir: string, skillsDir: string | undefined): boolean {
+  const rel = String(skillsDir ?? "").trim();
+  if (!rel) return false;
+  return existsSync(path.resolve(configDir, rel));
+}
+
+type GroupConfig = { groupId?: unknown; troubleshootingEnabled?: unknown };
+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());
+}
+
+/** 仅当来源群明确开启排查时启用；群缺失、字段缺失、未知值都默认关闭（继承 handoff 语义）。 */
+export function isGroupTroubleshootingEnabled(raw: unknown, conversationId: string): boolean {
+  if (!conversationId || !Array.isArray(raw)) return false;
+  const group = (raw as GroupConfig[]).find((g) => String(g?.groupId ?? "").trim() === conversationId);
+  return explicitTrue(group?.troubleshootingEnabled);
+}

package/templates/support-qa/npmrc

@@ -0,0 +1 @@
+registry=https://registry.anpm.alibaba-inc.com/

package/templates/support-qa/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "support-qa-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "通用群答疑助手（由 aitable-workflow init --template support-qa 生成）。业务差异全部在 profile/profile.yml。",
+  "scripts": {
+    "run": "npm run assemble && aitable-workflow run",
+    "setup": "npm run assemble && aitable-workflow setup",
+    "assemble": "tsx lib/assemble-cli.ts",
+    "check": "tsx lib/assemble-cli.ts --check"
+  },
+  "dependencies": {
+    "aitable-workflow-core": "^0.1.5",
+    "tsx": "^4.20.6",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.13"
+  }
+}