aitable-workflow-cli 0.1.15 → 0.1.16-beta.1786022310508

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

@@ -0,0 +1,294 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { isCapabilityEnabled, loadClassifierRules, loadReplyRules } from "./declarative-matcher.js";
+import type { PreflightIssue } from "aitable-workflow-core";
+import { SUPPORT_ACTIONS, KB_STATUS, KB_STATUS_VALUES } from "./contract.js";
+
+/**
+ * support-qa 实例 preflight（纯校验，零写盘）
+ *
+ * 由 core 的 preflight 扩展点在 `aitable-workflow config` 与 `run` / `setup` 启动期加载
+ * （约定：实例根 `lib/preflight.ts` 导出 `preflight(configDir)`）。
+ *
+ * 分档语义（core 按此决定停到什么程度）：
+ *   - fatal：实例级不可信 → 拒绝启动。profile.yml 结构错、persona 缺失/为空、
+ *            persona 疑似放开通用闸门（"闸门只准收紧不准放开"纪律的落点）。
+ *   - error：可归因到单个 workflow → 只停该轨道，其余工作流照跑。
+ *   - warn ：L3 可选能力关不上 → 该能力优雅关闭，主环照跑。
+ *
+ * 为什么不再写盘：persona 早已由 core 读取 profile 的 `persona: { file }` 并注入每次
+ * coding.run 的 prompt（registry.resolvePersonaFile → RoleContext → agent-adapter），
+ * 曾经生成的 workspaces/<role>/persona.md 是第二条冗余通路，已删。
+ * 但 core 对 persona 读取失败只 warn + 跳过该角色（会静默降级成 persona=role-id 的
+ * 临时角色），因此「persona.file 存在且非空」必须由本文件按 fatal 拦住。
+ */
+
+const GROUP_QA_WORKFLOW = "group-qa";
+const ADMIN_KB_WORKFLOW = "admin-kb-update";
+
+/** persona 疑似放开通用闸门的特征：闸门只准收紧，不准放开 */
+const PERSONA_GATE_RELAXING = /忽略(上述|以上|通用)|必须回复所有|无据也(可以|要)回答|不用静默/;
+
+function readRawProfile(configDir: string, issues: PreflightIssue[]): Record<string, unknown> | null {
+  const file = path.resolve(configDir, "profile", "profile.yml");
+  if (!existsSync(file)) {
+    issues.push({ level: "fatal", message: `profile/profile.yml 不存在: ${file}` });
+    return null;
+  }
+  try {
+    const raw = (parseYaml(readFileSync(file, "utf8")) ?? {}) as Record<string, unknown>;
+    if (raw.schema_version !== 2) {
+      issues.push({
+        level: "fatal",
+        message: `profile.yml schema_version 必须为 2（当前: ${raw.schema_version ?? "缺失"}）。请按迁移指引升级。`,
+      });
+      return null;
+    }
+    return raw;
+  } catch (err) {
+    issues.push({
+      level: "fatal",
+      message: `profile/profile.yml 解析失败: ${err instanceof Error ? err.message : String(err)}`,
+    });
+    return null;
+  }
+}
+
+/** collections 校验：trim、去空、必须是不含 .. 的相对路径、目录须存在 */
+function validateCollections(configDir: string, raw: unknown, issues: PreflightIssue[]): void {
+  const list = Array.isArray(raw)
+    ? raw.map((c) =>
+        typeof c === "string" ? c.trim()
+        : c && typeof c === "object" && "collection" in c ? String((c as { collection: string }).collection).trim()
+        : String(c ?? "").trim())
+    : [];
+  if (list.length === 0 || list.some((c) => !c)) {
+    issues.push({
+      level: "fatal",
+      message: "roles.support.knowledge_scope.kb_collections 缺失、为空或含空字符串（必填）",
+    });
+  }
+  for (const c of list.filter(Boolean)) {
+    if (path.isAbsolute(c) || c.split(/[\\/]/).includes("..")) {
+      issues.push({ level: "fatal", message: `kb_collections 必须是实例内的相对路径（不含 ..）: ${c}` });
+      continue;
+    }
+    if (!existsSync(path.resolve(configDir, c))) {
+      issues.push({ level: "fatal", message: `kb_collections 目录不存在: ${c}` });
+    }
+  }
+}
+
+/**
+ * persona 校验（两项都是 fatal，缺一不可）：
+ *   1. `{ file }` 引用的文件必须存在且内容非空——否则 core 会静默跳过该角色，
+ *      Agent 拿到的 persona 退化成角色 id 字面量，答疑质量无声崩塌；
+ *   2. 内容不得含"放开通用闸门"的措辞。
+ */
+function validatePersona(configDir: string, supportRole: Record<string, unknown> | undefined, issues: PreflightIssue[]): void {
+  if (!supportRole) return;
+  const personaField = supportRole.persona;
+  let personaText = "";
+
+  if (typeof personaField === "string") {
+    personaText = personaField.trim();
+    if (!personaText) {
+      issues.push({ level: "fatal", message: "roles.support.persona 为空字符串" });
+      return;
+    }
+  } else if (personaField && typeof personaField === "object" && "file" in personaField) {
+    const fileRel = String((personaField as { file: string }).file ?? "").trim();
+    if (!fileRel) {
+      issues.push({ level: "fatal", message: "roles.support.persona.file 为空" });
+      return;
+    }
+    const abs = path.resolve(configDir, "profile", fileRel);
+    if (!existsSync(abs)) {
+      issues.push({ level: "fatal", message: `roles.support.persona.file 引用的文件不存在: profile/${fileRel}` });
+      return;
+    }
+    personaText = readFileSync(abs, "utf8").trim();
+    if (!personaText) {
+      issues.push({ level: "fatal", message: `roles.support.persona.file 文件内容为空: profile/${fileRel}` });
+      return;
+    }
+  } else {
+    issues.push({ level: "fatal", message: "roles.support.persona 缺失（必填）" });
+    return;
+  }
+
+  if (PERSONA_GATE_RELAXING.test(personaText)) {
+    issues.push({
+      level: "fatal",
+      message: "persona 内容疑似放开通用闸门（只准收紧，不准放开），请修改后重试",
+    });
+  }
+}
+
+/** 集合严格相等比较 */
+function diffSets(actual: string[], expected: readonly string[]): { missing: string[]; extra: string[] } {
+  const a = new Set(actual);
+  const e = new Set(expected);
+  return { missing: expected.filter((v) => !a.has(v)), extra: actual.filter((v) => !e.has(v)) };
+}
+
+function getIn(obj: unknown, ...keys: string[]): unknown {
+  let current = obj;
+  for (const key of keys) {
+    if (!current || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+/**
+ * on_action policies 闭集校验：键必须 ⊆ SUPPORT_ACTIONS；group 只允许 answer / silent。
+ * group 只表达「群里说不说话」（轴1）；Owner 指引由 Runtime 按「action 需要找人 + Owner
+ * 可解析」派生（轴2），不存在「通知 Owner」档位。
+ */
+function validateOnActionPolicies(groupQaWf: unknown, issues: PreflightIssue[]): void {
+  const onActionStep = getIn(groupQaWf, "steps", "on_action") as Record<string, unknown> | undefined;
+  const policiesRaw = onActionStep?.policies;
+  if (policiesRaw && typeof policiesRaw === "object") {
+    const { extra } = diffSets(Object.keys(policiesRaw), SUPPORT_ACTIONS);
+    if (extra.length > 0) {
+      issues.push({
+        level: "error",
+        workflowId: GROUP_QA_WORKFLOW,
+        message: `on_action.policies 含未知 action [${extra.join(",")}]，合法值: [${SUPPORT_ACTIONS.join(",")}]`,
+      });
+    }
+    for (const [actionName, cfg] of Object.entries(policiesRaw as Record<string, { group?: unknown }>)) {
+      const group = cfg && typeof cfg === "object" ? cfg.group : undefined;
+      if (group === undefined) continue;
+      if (group !== "answer" && group !== "silent") {
+        issues.push({
+          level: "error",
+          workflowId: GROUP_QA_WORKFLOW,
+          message: `on_action.policies.${actionName}.group 只能是 answer / silent（Owner 尾注不在 group 里配，由 Runtime 按 action 与 Owner 解析结果派生），实际: ${JSON.stringify(group)}`,
+        });
+      }
+    }
+  }
+  // 旧 on_silence 步配置仍存在 → 提醒迁移（拍平 action 后该步已改名 on_action）
+  if (getIn(groupQaWf, "steps", "on_silence")) {
+    issues.push({
+      level: "warn",
+      workflowId: GROUP_QA_WORKFLOW,
+      message: "workflows.group-qa.steps.on_silence 已废弃（拍平 action 后步为 on_action）：请迁移为 steps.on_action.policies（track/group）",
+    });
+  }
+}
+
+/** group-qa 单选列 options 与 contract 常量的镜像强校验（双源分家会让路由静默错位） */
+function validateGroupQaFieldOptions(configDir: string, issues: PreflightIssue[]): void {
+  const groupQaFile = path.resolve(configDir, "workflows", GROUP_QA_WORKFLOW, "workflow.yml");
+  if (!existsSync(groupQaFile)) return;
+  try {
+    const wf = (parseYaml(readFileSync(groupQaFile, "utf8")) ?? {}) as Record<string, any>;
+    const defs = Array.isArray(wf?.tracker?.field_definitions) ? wf.tracker.field_definitions : [];
+    for (const [fieldName, expected] of [
+      ["处置动作", SUPPORT_ACTIONS],
+      ["知识沉淀", KB_STATUS_VALUES],
+    ] as const) {
+      const matched = defs.filter((d: any) => d?.name === fieldName);
+      if (matched.length !== 1) {
+        issues.push({
+          level: "error",
+          workflowId: GROUP_QA_WORKFLOW,
+          message: `field_definitions 中「${fieldName}」字段必须恰好 1 个，实际 ${matched.length} 个`,
+        });
+        continue;
+      }
+      const options = Array.isArray(matched[0]?.options) ? matched[0].options.map((o: any) => String(o)) : [];
+      const { missing, extra } = diffSets(options, expected);
+      if (missing.length > 0 || extra.length > 0) {
+        issues.push({
+          level: "error",
+          workflowId: GROUP_QA_WORKFLOW,
+          message: `「${fieldName}」options 与 lib/contract.ts 不一致：缺[${missing.join(",")}] 多[${extra.join(",")}]`,
+        });
+      }
+    }
+  } catch (err) {
+    issues.push({
+      level: "error",
+      workflowId: GROUP_QA_WORKFLOW,
+      message: `workflow.yml 解析失败: ${err instanceof Error ? err.message : String(err)}`,
+    });
+  }
+}
+
+/** admin-kb-update 事件过滤锚点：锚错了知识更新轨道根本不拉单 */
+function validateAdminKbFilter(workflows: Record<string, Record<string, unknown>>, issues: PreflightIssue[]): void {
+  const adminKbWf = workflows[ADMIN_KB_WORKFLOW];
+  if (!adminKbWf) return;
+  const esConfig = getIn(adminKbWf, "event_sources", "管理员更新监听") as Record<string, unknown> | undefined;
+  const filterEquals = typeof esConfig?.filter === "object" && esConfig.filter
+    ? String((esConfig.filter as Record<string, unknown>).equals ?? "")
+    : "";
+  if (filterEquals && filterEquals !== KB_STATUS.READY_TO_PERSIST) {
+    issues.push({
+      level: "error",
+      workflowId: ADMIN_KB_WORKFLOW,
+      message: `事件过滤 filter.equals="${filterEquals}" 必须为 "${KB_STATUS.READY_TO_PERSIST}"（否则知识更新轨道不拉单）`,
+    });
+  }
+}
+
+/** L3 可选能力预检（一律 warn：运行期缺失即优雅关闭，不阻断 L0 主环） */
+function validateOptionalCapabilities(configDir: string, groupQaWf: unknown, issues: PreflightIssue[]): void {
+  const fastpathStep = getIn(groupQaWf, "steps", "fastpath") as Record<string, unknown> | undefined;
+  const fastpathRel = typeof fastpathStep?.rules === "string" ? fastpathStep.rules.trim() : "";
+  if (fastpathRel) {
+    const { issues: fpIssues } = loadReplyRules(configDir, fastpathRel);
+    for (const msg of fpIssues) {
+      issues.push({ level: "warn", workflowId: GROUP_QA_WORKFLOW, message: `fastpath: ${msg}` });
+    }
+  }
+
+  const troubleshootStep = getIn(groupQaWf, "steps", "troubleshoot") as Record<string, unknown> | undefined;
+  const skillsDirRel = typeof troubleshootStep?.skills_dir === "string" ? troubleshootStep.skills_dir.trim() : "";
+  if (skillsDirRel && !isCapabilityEnabled(configDir, skillsDirRel)) {
+    issues.push({
+      level: "warn",
+      workflowId: GROUP_QA_WORKFLOW,
+      message: `troubleshoot: skills_dir 目录不存在，整档将关闭: ${skillsDirRel}`,
+    });
+  }
+  const classifiersRel = typeof troubleshootStep?.classifiers === "string" ? troubleshootStep.classifiers.trim() : "";
+  if (classifiersRel) {
+    const { issues: tsIssues } = loadClassifierRules(configDir, classifiersRel);
+    for (const msg of tsIssues) {
+      issues.push({ level: "warn", workflowId: GROUP_QA_WORKFLOW, message: `troubleshoot: ${msg}` });
+    }
+    // classifier.module 合法性不在此交叉校验：模块闭集来自功能模块人员配置表
+    // （config-sync 运行期快照），拼写不匹配时运行期降级并记 owner_resolution_failed。
+  }
+}
+
+/** core preflight 扩展点约定的导出 */
+export function preflight(configDir: string): PreflightIssue[] {
+  const issues: PreflightIssue[] = [];
+
+  const raw = readRawProfile(configDir, issues);
+  if (!raw) return issues; // profile 读不了，后续校验都无意义
+
+  const roles = (raw.roles ?? {}) as Record<string, Record<string, unknown>>;
+  const workflows = (raw.workflows ?? {}) as Record<string, Record<string, unknown>>;
+  const supportRole = roles.support;
+  const groupQaWf = workflows[GROUP_QA_WORKFLOW];
+
+  const roleName = typeof supportRole?.name === "string" ? supportRole.name.trim() : "";
+  if (!roleName) issues.push({ level: "fatal", message: "roles.support.name 缺失（必填）" });
+  validateCollections(configDir, (supportRole?.knowledge_scope as Record<string, unknown> | undefined)?.kb_collections, issues);
+  validatePersona(configDir, supportRole, issues);
+
+  validateOnActionPolicies(groupQaWf, issues);
+  validateGroupQaFieldOptions(configDir, issues);
+  validateAdminKbFilter(workflows, issues);
+  validateOptionalCapabilities(configDir, groupQaWf, issues);
+
+  return issues;
+}

package/templates/support-qa/package.json

@@ -5,10 +5,8 @@
   "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"
+    "run": "aitable-workflow run",
+    "setup": "aitable-workflow setup"
   },
   "dependencies": {
     "aitable-workflow-core": "^0.1.5",

package/templates/support-qa/profiles/aitable/profile/fastpath/known-answers.yml

@@ -1,6 +1,6 @@
 # fastpath 声明式规则（钉钉 AI 表格 profile）——由 error-replies.json(51) 迁移生成
 # 单向匹配：消息包含 contains 文案即秒回（key 便于排障追溯）；safety 安全兜底优先级最高。
-# 迁移来源：aitable-handoff known-error-match（双向 includes 已修为单向）。
+# 单向匹配不反向：短消息不会误命中长规则。
 
 safety:
   keywords: ["由于可能涉及敏感内容或临时限制"]

package/templates/support-qa/profiles/aitable/profile/troubleshoot/classifiers.yml

@@ -1,5 +1,5 @@
 # troubleshoot 声明式分类器（钉钉 AI 表格 profile）
-# 迁移自 aitable-handoff issue-classifier.ts：把硬编码正则收敛为声明式规则。
+# 把硬编码正则收敛为声明式分类规则。
 # 命中 → 由 troubleshoot 排查 Agent 读 skills_dir 的对应 Skill 完成排查；都不命中 → 交语义答疑。
 
 classifiers:

package/templates/support-qa/workflows/config-sync/recipes/config_sync.recipe.ts

@@ -1,12 +1,16 @@
-import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
-import { promisify } from "node:util";
 import { z } from "zod";
-import { normalizeByType, tableRefConfigSchema, globalVarRefPath, type RecipeDefinition, type RecipeContext, type RecipeResult } from "aitable-workflow-core";
+import { DwsClient, normalizeByType, tableRefConfigSchema, globalVarRefPath, type RecipeDefinition, type RecipeContext, type RecipeResult } from "aitable-workflow-core";
 import { normalizeModuleOwners, type ModuleOwners } from "../../../lib/owner-resolver.js";
 
-const execFileAsync = promisify(execFile);
+/**
+ * dws 命令统一走 core 的 DwsClient（而非自建 execFile）：拿到退避重试（消化 dws 后端
+ * 偶发 TIMEOUT / 伪 AUTH_PERMISSION_DENIED）与连续失败升级告警，并让 success=false /
+ * degraded=true 的响应直接抛错 —— 本 recipe 的三个拉取块都包在 try/catch 里降级为
+ * 「保留旧值」，比静默同步一份空快照安全。
+ */
+const dws = new DwsClient({ bin: "dws", timeoutMs: 30_000 });
 
 /** 从配置取 globalVar key：接受 "${globalVar.x}" 引用（解析出 x）或裸 key；空则回退默认。 */
 function varKey(raw: unknown, fallback: string): string {
@@ -33,8 +37,7 @@ type FetchResult<T> = { ok: true; data: T } | { ok: false; error: string };
 const CONTACT_CONCURRENCY = 5;
 
 async function dwsJson(args: string[], timeoutMs = 30_000): Promise<{ records: Rec[] }> {
-  const { stdout } = await execFileAsync("dws", args, { encoding: "utf-8", timeout: timeoutMs, maxBuffer: 5 * 1024 * 1024 });
-  const parsed = JSON.parse(stdout.trim()) as unknown;
+  const parsed = await dws.runJson(args, { timeoutMs });
   return { records: extractRecords(parsed) };
 }
 
@@ -49,8 +52,7 @@ function extractRecords(raw: unknown): Rec[] {
 }
 
 async function dwsRaw(args: string[], timeoutMs = 15_000): Promise<unknown> {
-  const { stdout } = await execFileAsync("dws", args, { encoding: "utf-8", timeout: timeoutMs, maxBuffer: 5 * 1024 * 1024 });
-  return JSON.parse(stdout.trim());
+  return dws.runJson(args, { timeoutMs });
 }
 
 /** 有界并发地映射：最多 limit 个任务同时进行，返回与输入等长的结果数组。 */

package/templates/support-qa/workflows/daily-review/recipes/daily_review.recipe.ts

@@ -19,7 +19,7 @@ import { KB_STATUS } from "../../../lib/contract.js";
  * 各群消息不内联进 prompt（单群 500 条可达数百 KB，会打爆 agent），而是落盘到工作目录下
  * .today/<序号>-<群ID>.md，prompt 只给文件清单让 agent 自行 Read；coding.run 结束即删除。
  *
- * 群列表适配：aitable-handoff 的群是动态的，由 config-sync 发布到 globalVar(group_configs)。
+ * 群列表适配：群是动态的，由 config-sync 发布到 globalVar(group_configs)。
  * step.config.conversation_ids 二选一：静态数组，或引用 ${globalVar.group_configs}（无隐式回退）。
  */
 

package/templates/support-qa/workflows/group-qa/recipes/answer.recipe.ts

@@ -3,7 +3,6 @@ import path from "node:path";
 import { z } from "zod";
 import type { RecipeDefinition, RecipeContext, RecipeResult } from "aitable-workflow-core";
 import { contractPromptBlock, extractSupportReply, type SupportReply } from "../../../lib/contract.js";
-import { profileAssembleGuard } from "../../../lib/profile-guard.js";
 import { SUPPORT_DECISION_CONTENT, SUPPORT_MEMORY_KINDS, SUPPORT_MEMORY_ROLES, questionKey, supportEntry, supportScope } from "../../../lib/memory-events.js";
 
 /**
@@ -73,12 +72,8 @@ const recipe: RecipeDefinition = {
       };
     }
 
-    // 装配前置（评审 P1/P3）：校验+装配 profile 产物；校验失败则阻断作答（agent_failure
-    // 静默留痕，运营可见），绝不带着错误/降级的 profile 继续调 agent 。同一闸门也前置在
-    // fastpath/troubleshoot（见 lib/profile-guard.ts），确保 L3 直出路径不绕过校验。
-    // 正式入口是 `npm run assemble`（写盘）/ `npm run check`（preflight）。
-    const guard = profileAssembleGuard(ctx, log);
-    if (guard) return guard;
+    // profile 校验已前移到启动期（core preflight 扩展点加载 lib/preflight.ts）：
+    // 配置错在 `aitable-workflow run` 启动瞬间就报，不再每条消息判一次再降级静默。
     const roleId = ctx.roleContext?.id?.trim() || "support";
     const workDir = path.resolve(ctx.configDir, "workspaces", roleId);
 

package/templates/support-qa/workflows/group-qa/recipes/conversation_handler.recipe.ts

@@ -11,7 +11,7 @@ import {
 } from "aitable-workflow-core";
 import { z } from "zod";
 import { SUPPORT_MEMORY_KINDS, SUPPORT_MEMORY_ROLES, supportEntry, supportScope } from "../../../lib/memory-events.js";
-import { isRecentOutboundEcho } from "../../../lib/echo-guard.js";
+import { echoWindow } from "../../../lib/guards.js";
 
 /**
  * 会话消息处理器（support-qa L0）
@@ -20,7 +20,7 @@ import { isRecentOutboundEcho } from "../../../lib/echo-guard.js";
  *   - onEvent 纯同步（无长 await）：回声过滤 → 摄入本轮消息 + 构建「近期对话上下文」→ pushEvent 建单。
  *   - 内存里按 conversationId 维护近期消息环形缓冲（容量/TTL 限制，重启清空）。
  *
- * 与 aitable-handoff 版的三处 Pattern 级差异：
+ * 三处 Pattern 级行为要点：
  *   1. 出站回声防护：reply 发布的内容指纹命中 → 按机器人消息处理（只记历史不建单），
  *      防 webhook 回复以真人名义回流造成自激（评测硬用例 G1）。
  *   2. 管理员/真人同事消息写入短期记忆（role=admin）：学习通道（daily-review 提炼
@@ -168,7 +168,7 @@ const recipe: EventHandlerRecipeDefinition = {
         const groupConfig = getGroupBots().get(conversationId);
         const botSets = groupConfig?.identity ?? emptySets;
         // 出站回声：webhook 回复以真人名义回流时身份匹配失效，用内容指纹兜底（G1）
-        const isEcho = isRecentOutboundEcho(ctx.getGlobalVar, content);
+        const isEcho = echoWindow.has(ctx.getGlobalVar, content);
         const isBot = isEcho || matchesIdentity(botSets, senderName, senderOpenId);
         const isAdmin = !isBot && matchesIdentity(adminSets, senderName, senderOpenId);
 

package/templates/support-qa/workflows/group-qa/recipes/fastpath.recipe.ts

@@ -1,7 +1,6 @@
 import { z } from "zod";
-import type { RecipeDefinition, RecipeContext, RecipeResult } from "aitable-workflow-core";
-import { profileAssembleGuard } from "../../../lib/profile-guard.js";
-import { loadFastpathRules, matchFastpath } from "../../../lib/fastpath.js";
+import { type RecipeDefinition, type RecipeContext, type RecipeResult } from "aitable-workflow-core";
+import { loadReplyRules, matchReplyRules } from "../../../lib/declarative-matcher.js";
 
 /**
  * fastpath 确定性秒回（support-qa L3，group-qa 首步，非 LLM）
@@ -15,7 +14,7 @@ import { loadFastpathRules, matchFastpath } from "../../../lib/fastpath.js";
  *   - 未命中任何规则 → 透传给 answer 走语义答疑（语义匹配不属于 fastpath）。
  *
  * 命中即建行：本步返回 output（含 answer）且不置 tracker:false，on_demand 下建行留痕
- * （与 aitable-handoff 已知错误秒回一致）。
+ * （已知错误秒回的建行语义）。
  */
 const recipe: RecipeDefinition = {
   meta: {
@@ -45,19 +44,14 @@ const recipe: RecipeDefinition = {
       return { status: "success", output: {}, tracker: false, logs: ["空消息，透传"] };
     }
 
-    // 装配闸门前置（评审 P1）：fastpath 命中即直出固定话术并让 answer 跳过，故 profile
-    // 装配错误时也必须阻断（与 answer 一致），不得带病秒回。
-    const guard = profileAssembleGuard(ctx, log);
-    if (guard) return guard;
-
-    const { config, issues } = loadFastpathRules(ctx.configDir, ctx.config.rules);
+    const { config, issues } = loadReplyRules(ctx.configDir, ctx.config.rules as string | undefined);
     for (const i of issues) log(`[fastpath] ${i}`);
     if (!config) {
       // 未配置/文件缺失 → fastpath 关闭，透传 answer
       return { status: "success", output: {}, tracker: false, logs: ["fastpath 未启用，透传"] };
     }
 
-    const match = matchFastpath(config, content);
+    const match = matchReplyRules(config, content);
     if (!match) {
       log("未命中 fastpath 规则，交给 answer");
       return { status: "success", output: {}, tracker: false, logs: ["未命中 fastpath"] };

package/templates/support-qa/workflows/group-qa/recipes/on-action.recipe.ts

@@ -2,10 +2,10 @@ import { existsSync } from "node:fs";
 import nodePath from "node:path";
 import { z } from "zod";
 import { resolveGlobalVarRef, type RecipeDefinition, type RecipeContext, type RecipeResult } from "aitable-workflow-core";
+import { resolveGroupMention } from "../../../lib/dingtalk-group-membership.js";
 import { SUPPORT_ACTIONS, type SupportAction, KB_STATUS } from "../../../lib/contract.js";
 import { DEFAULT_ON_ACTION, type ActionPolicy, type ActionPolicyOverrides } from "../../../lib/profile.js";
 import { resolveOwner, type OwnerResolution } from "../../../lib/owner-resolver.js";
-import { resolveOwnerGroupMention } from "../../../lib/owner-mention.js";
 import { buildActionDispatch, needsOwnerResolution, shouldRecordOwnerFailure } from "../../../lib/action-dispatch.js";
 import { SUPPORT_MEMORY_KINDS, SUPPORT_MEMORY_ROLES, supportEntry, supportScope } from "../../../lib/memory-events.js";
 
@@ -84,7 +84,9 @@ const recipe: RecipeDefinition = {
       const ownersRef = String(ctx.config.module_owners ?? "${globalVar.module_owners}");
       owner = resolveOwner(resolveGlobalVarRef(ownersRef, ctx.getGlobalVar), module);
       if (owner.status === "resolved") {
-        const mention = await resolveOwnerGroupMention(
+        // 能否真实 @：只校验 Owner 在不在当前群（联系人已由 config-sync 解析进快照）。
+        // 任何失败降级为 mode=name → 下游只渲染花名，不写假 @。
+        const mention = await resolveGroupMention(
           conversationId,
           { userId: owner.ownerUserId, openDingTalkId: owner.ownerOpenDingTalkId },
         );

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

@@ -1,12 +1,18 @@
 import { z } from "zod";
 import type { RecipeDefinition, RecipeContext, RecipeResult, ReplyToConversationOptions } from "aitable-workflow-core";
-import { resolveGlobalVarRef } from "aitable-workflow-core";
+import { createFingerprintWindow, resolveGlobalVarRef } from "aitable-workflow-core";
 import { SUPPORT_MEMORY_KINDS, SUPPORT_MEMORY_ROLES, questionKey, supportEntry, supportScope } from "../../../lib/memory-events.js";
-import { publishSentFingerprint } from "../../../lib/echo-guard.js";
-import { shouldRecordSendFailure } from "../../../lib/send-failure-guard.js";
+import { echoWindow } from "../../../lib/guards.js";
 import { needsOwnerResolution } from "../../../lib/action-dispatch.js";
 import type { SupportAction } from "../../../lib/contract.js";
 
+const sendFailureWindow = createFingerprintWindow({
+  key: "send_failure_marks",
+  ttlMs: 10 * 60 * 1000,
+  capacity: 50,
+  maxPartLength: [300, 300, 200],
+});
+
 /** 群配置(config-sync 发布到 globalVar 的形状)：出站选路与凭据引用据此传给 replyToConversation。 */
 type GroupConfig = { groupId: string; corpId?: string; inbound?: string; outbound?: string; credRef?: string };
 
@@ -20,7 +26,7 @@ function loadGroupConfig(ctx: RecipeContext, ref: string, conversationId: string
  * 回复群消息（support-qa L0）
  *
  * 通过 messaging toolkit 的 replyToConversation 自动选路（session sessionWebhook → webhook 降级），
- * recipe 不感知传输细节。发送可靠性不变量（继承 aitable-handoff 生产验证）：
+ * recipe 不感知传输细节。发送可靠性不变量（生产验证过）：
  *   - via=skipped 按失败处理（无可用通道 ≠ 已发送），记 send_failed；
  *     其中 configError（如 credRef 未命中 webhook_creds 命名集）返回 retryable=false，
  *     由调度层阻塞待人工改配置，不空转重试；
@@ -87,7 +93,7 @@ const recipe: RecipeDefinition = {
         log(`未能发送到群 ${conversationId} (via=skipped${reason ? `, reason=${reason}` : ""})`);
         const skipReason = reason ?? "无可用出站通道";
         // 重试风暴去重：同群+同待发内容+同原因在窗口内只留痕一次，重试只写日志
-        if (shouldRecordSendFailure(ctx.getGlobalVar, ctx.setGlobalVar, { conversationId, content: answer, reason: `skipped:${skipReason}` })) {
+        if (sendFailureWindow.mark(ctx.getGlobalVar, ctx.setGlobalVar, conversationId, answer, `skipped:${skipReason}`)) {
           try {
             await toolkit.memory.append(
               supportScope(conversationId),
@@ -119,7 +125,7 @@ const recipe: RecipeDefinition = {
       log(`已发送到群 ${conversationId} (via=${via}${reason ? `, reason=${reason}` : ""})`);
       // 回声防护：发布出站内容指纹（conversation_handler 据此识别回流消息）
       try {
-        publishSentFingerprint(ctx.getGlobalVar, ctx.setGlobalVar, answer);
+        echoWindow.mark(ctx.getGlobalVar, ctx.setGlobalVar, answer);
       } catch (fpErr) {
         log(`发布回声指纹失败(不影响主流程): ${fpErr instanceof Error ? fpErr.message : String(fpErr)}`);
       }
@@ -146,7 +152,7 @@ const recipe: RecipeDefinition = {
       const msg = error instanceof Error ? error.message : String(error);
       log(`发送失败: ${msg}`);
       // 与 skipped 分支同源的重试风暴去重（异常原因不同则各记一次）
-      if (shouldRecordSendFailure(ctx.getGlobalVar, ctx.setGlobalVar, { conversationId, content: answer, reason: `error:${msg}` })) {
+      if (sendFailureWindow.mark(ctx.getGlobalVar, ctx.setGlobalVar, conversationId, answer, `error:${msg}`)) {
         try {
           await toolkit.memory.append(
             supportScope(conversationId),

package/templates/support-qa/workflows/group-qa/recipes/troubleshoot.recipe.ts

@@ -7,20 +7,19 @@ import {
   type RecipeDefinition,
   type RecipeResult,
 } from "aitable-workflow-core";
-import { profileAssembleGuard } from "../../../lib/profile-guard.js";
 import {
-  classifyIssue,
-  isGroupTroubleshootingEnabled,
-  isTroubleshootEnabled,
-  loadClassifiers,
-  type ClassifyResult,
-} from "../../../lib/troubleshoot.js";
+  classifyMessage,
+  isCapabilityEnabled,
+  isGroupToggleEnabled,
+  loadClassifierRules,
+  type ClassifyMatch,
+} from "../../../lib/declarative-matcher.js";
 import { SUPPORT_DECISION_CONTENT, SUPPORT_MEMORY_KINDS, SUPPORT_MEMORY_ROLES, questionKey, supportEntry, supportScope } from "../../../lib/memory-events.js";
 
 /**
  * 问题排查（support-qa L3，group-qa 中段，requiresAgent）
  *
- * 声明式分类器（profile/troubleshoot/classifiers.yml）取代 handoff 硬编码 issue-classifier.ts：
+ * 声明式分类器（profile/troubleshoot/classifiers.yml）取代硬编码 issue-classifier：
  * 确定性识别问题类型 → 启动独立排查 Agent（读 skills_dir 的 Skill 完成真实排查）→ 按契约回复。
  *
  * 三重开关（任一不满足即透传给 answer，本步 tracker:false 不表态）：
@@ -80,7 +79,7 @@ function extractDecision(raw: string): TroubleshootDecision | null {
 }
 
 function buildPrompt(args: {
-  route: ClassifyResult;
+  route: ClassifyMatch;
   content: string;
   context: string;
   senderName: string;
@@ -182,15 +181,10 @@ const recipe: RecipeDefinition = {
       return { status: "success", output: {}, tracker: false, logs: ["空消息，透传"] };
     }
 
-    // 装配闸门前置（评审 P1）：排查命中即启动独立 Agent 并直出回复，故 profile
-    // 装配错误时必须阻断（与 answer 一致），不得带病启动排查作答。
-    const guard = profileAssembleGuard(ctx, log);
-    if (guard) return guard;
-
     const skillsDir = ctx.config.skills_dir as string | undefined;
 
     // 开关 1：整档开关（skills_dir 未配置或目录不存在 → 整档关闭）
-    if (!isTroubleshootEnabled(ctx.configDir, skillsDir)) {
+    if (!isCapabilityEnabled(ctx.configDir, skillsDir)) {
       log("troubleshoot 未启用（skills_dir 未配置或不存在），交给 answer");
       return { status: "success", output: {}, tracker: false, logs: ["troubleshoot 未启用"] };
     }
@@ -198,15 +192,15 @@ const recipe: RecipeDefinition = {
     // 开关 2：按群开关（群配置表 troubleshootingEnabled 明确为真）
     const groupsRef = String(ctx.config.conversation_ids ?? "${globalVar.group_configs}");
     const groupConfigs = resolveGlobalVarRef(groupsRef, ctx.getGlobalVar);
-    if (!isGroupTroubleshootingEnabled(groupConfigs, conversationId)) {
+    if (!isGroupToggleEnabled(groupConfigs, conversationId, "troubleshootingEnabled")) {
       log(`群 ${conversationId || "(缺失)"} 未开启问题排查，交给 answer`);
       return { status: "success", output: {}, tracker: false, logs: ["问题排查未开启"] };
     }
 
     // 开关 3：声明式分类命中
-    const { config, issues } = loadClassifiers(ctx.configDir, ctx.config.classifiers as string | undefined);
+    const { config, issues } = loadClassifierRules(ctx.configDir, ctx.config.classifiers as string | undefined);
     for (const i of issues) log(`[troubleshoot] ${i}`);
-    const route = classifyIssue(config, content);
+    const route = classifyMessage(config, content);
     if (!route) {
       log("未命中确定性排查分类，交给 answer");
       return { status: "success", output: {}, tracker: false, logs: ["未命中排查分类"] };

package/templates/support-qa/workspaces/support/AGENTS.md

@@ -1,6 +1,6 @@
 # 群知识库答疑助手 — Agent 执行规范（support-qa Pattern 基座）
 
-你是一名【群知识库答疑助手】。你的具体人设与负责的产品领域，以本目录下 `persona.md`（若存在，由 profile 注入）为准，下文统称"你负责的产品"。
+你是一名【群知识库答疑助手】。你的具体人设与负责的产品领域，以本次任务提示词开头注入的『# 角色设定』块为准（由 profile 的 `roles.support.persona` 提供），下文统称"你负责的产品"。
 
 你的任务：收到一条群消息后，先按【三、闸门规则】判定处置动作（action），再基于【知识库】提供准确解答，并【只输出一个严格 JSON 对象】。知识库有据时就尽量把问题答清楚（默认目标）；仅在无据 / 越界 / 有风险时才判无 reply 类 action。
 

package/templates/aitable-handoff/.env.example

@@ -1,17 +0,0 @@
-# LLM(知识库编译 + 技术问答推理)
-IDEALAB_API_KEY=your-idealab-key
-
-# 群 webhook(url+secret)来自 config-sync 发布的 globalVar:group_configs,无需在此配置
-# 管理员名单来自 config-sync 发布的 globalVar:admins
-# dws CLI 需在 PATH:消息拉取(群答疑)、aitable/contact(config-sync)
-
-# 钉钉企业机器人凭证(内部 robot 群):dingtalk_stream 入站 + messaging.robot 会话内 @人 出站,同一套凭据。
-# 占位:按你的应用命名并填真实值;勿写死到 workflow.yml 或表格。仅用外部 webhook 群可忽略。
-DINGTALK_CLIENT_ID=your-dingtalk-app-client-id
-DINGTALK_CLIENT_SECRET=your-dingtalk-app-client-secret
-
-# 钉钉 Stream 机器人凭据（credRef→凭据 的 JSON map）。
-DINGTALK_ROBOTS={"botA":{"client_id":"CHANGE_ME","client_secret":"CHANGE_ME"}}
-
-# 钉钉 Webhook 凭据（credRef→{url,secret?} 的 JSON map）；仅用 robot 回复的群可忽略
-DINGTALK_WEBHOOK={"default":{"url":"https://oapi.dingtalk.com/robot/send?access_token=CHANGE_ME","secret":"CHANGE_ME"}}