aitable-workflow-cli 0.1.13-beta.1

package/templates/support-qa/lib/action-dispatch.ts

@@ -0,0 +1,262 @@
+import type { SupportAction } from "./contract.js";
+import type { ActionPolicy } from "./profile.js";
+import { speaksInGroup } from "./profile.js";
+import type { OwnerResolution } from "./owner-resolver.js";
+
+/**
+ * Action 处置合成（纯函数层，spec §6/§7）
+ *
+ * 职责：按 action + 策略 + Owner 解析结果，确定性合成——
+ *   1. 最终群消息 finalReply（Agent 主体 + Runtime Owner 尾注；主体缺失用内部兜底文案）；
+ *   2. 渠道无关的自动化通知字段（AI 表格自动化选做 TODO/IM，Runtime 不发送）。
+ *
+ * 两个正交轴（重构后）：
+ *   轴1 群内可见性：profile 显式配 `group: answer | silent`（见 profile.speaksInGroup）；
+ *   轴2 Owner 指引：Runtime **派生**——`needsOwnerResolution(action)` 且 Owner 解析成功且群内说话。
+ *   所以 `answer` 也能带 Owner 尾注，不需要单独的「通知 Owner」档位。
+ *
+ * 内部默认文案（spec §7.2）：本期不向 Profile 暴露模板，先把行为做稳。
+ * Owner 提及形态由运行期的 (conversationId, Owner) 判定结果驱动：
+ * 能确认当前群可用 userId 才真实 @，否则只渲染花名。
+ */
+
+// ─── 轴2：需要找人的 action（单点判定） ───────────────
+
+/**
+ * 需要尝试解析并附加 Owner 指引的 action：
+ * bug/feature 找人排查或评估；kb_gap 找模块负责人补充文档。
+ */
+const OWNER_MENTION_ACTIONS = new Set<SupportAction>(["bug", "feature", "kb_gap"]);
+
+/**
+ * 是否需要解析 Owner（on-action 决定是否 resolveOwner、本模块决定是否附尾注，
+ * 两侧共用本判定，不再各自拄一份「哪些 action + 哪些档位才找人」的表达式）。
+ *
+ * 只看 action，**不看 group 档位、也不看 module 是否为空**：
+ * - 不看 group：群内静默时 Owner 仍需进通知字段（供自动化找人）；
+ * - 不看 module：module 缺失要让 resolveOwner 报 missing_module 才能保留
+ *   「Agent 该给 module 却没给」的监控信号（见 shouldRecordOwnerFailure）。
+ */
+export function needsOwnerResolution(action: SupportAction): boolean {
+  return OWNER_MENTION_ACTIONS.has(action);
+}
+
+/**
+ * Owner 解析失败是否值得记 owner_resolution_failed 事件：
+ * - bug/feature：必须找到人（module 缺失也是 Agent 该给没给的信号）→ 恒记；
+ * - kb_gap：Owner 是加分项，仅当给了 module 却查不到人（真配置缺口）才记，
+ *   避免大量无 module 的常态 kb_gap 刷满事件。
+ */
+export function shouldRecordOwnerFailure(action: SupportAction, module: string): boolean {
+  if (!needsOwnerResolution(action)) return false;
+  if (action === "bug" || action === "feature") return true;
+  return Boolean(String(module ?? "").trim());
+}
+
+/**
+ * 渲染尾注中的 Owner 提及文本：
+ * - ownerMentionUserId 非空 → ` @工号 `，由发送层配合 mentionUserIds 真实 @；
+ * - 空 → 花名纯文本，消息中绝不出现数字 uid。
+ */
+export function renderOwnerMention(
+  owner: { ownerName: string; ownerUserId: string },
+  ownerMentionUserId?: string,
+): string {
+  const s = String(ownerMentionUserId ?? "").trim();
+  if (s) {
+    return ` @${s.length < 6 ? s.padStart(6, "0") : s} `;
+  }
+  return ` **${owner.ownerName}** `;
+}
+
+// ─── 内部文案（不进 Profile 配置面） ─────────────────────
+
+// Owner 尾注（追加在主体之后）。话术对齐 aitable-handoff 基线的引导式口吻：
+// 「建议在群内 @X 帮你看一下」——不谎称已通知（是否真实 @ 到人由发送层 atUserIds 决定）；
+// mention 两侧已带空格，模板不再额外加空格
+const BUG_FOOTER = (mention: string, module: string) =>
+  `建议在群内${mention}帮你看一下，他负责${module}模块 🔧`;
+const FEATURE_FOOTER = (mention: string, module: string) =>
+  `建议在群内${mention}关注评估下这个诉求，他负责${module}模块。`;
+
+// 主体兜底文案（**不含**尾注；尾注由统一路径按需追加，避免两套拼接逻辑）
+const BUG_BODY_FALLBACK = (sender: string) =>
+  `Hi ${sender || "用户"}，从你描述的现象看，这个行为不太符合预期，还需要进一步排查。`;
+const FEATURE_BODY_FALLBACK = (sender: string) =>
+  `Hi ${sender || "用户"}，这个需求目前帮助文档中还没有明确说明。`;
+// kb_gap 契约禁止 Agent 携带 reply → 主体恒由内部合成（坦白无据，不静默也不编造）
+const KB_GAP_BODY = (sender: string) =>
+  `Hi ${sender || "用户"}，这个问题帮助文档暂时没有覆盖，我先记录为知识缺口，待文档补充后再帮你解答 🙏`;
+// Owner 未解析且 Agent 主体也缺失（bug/feature）：不写假 @、不静默——引导用户补充定位信息
+const OWNER_FAILED_CLARIFY_FALLBACK = (sender: string) =>
+  `Hi ${sender || "用户"}，从你的描述还不能确定问题属于哪个功能模块。方便补充下：在哪个页面、做了什么操作、实际结果和预期分别是什么？有报错的话带下截图，方便进一步定位。`;
+
+/** 按 action 选 Owner 尾注（kb_gap 复用 Bug 口吻「帮你看一下」——已拍板） */
+function ownerFooter(action: SupportAction, mention: string, module: string): string {
+  return action === "feature" ? FEATURE_FOOTER(mention, module) : BUG_FOOTER(mention, module);
+}
+
+/** Owner 已解析且 Agent 主体缺失时的内部主体（随后由统一路径追加尾注） */
+function resolvedBodyFallback(action: SupportAction, sender: string): string {
+  if (action === "feature") return FEATURE_BODY_FALLBACK(sender);
+  if (action === "kb_gap") return KB_GAP_BODY(sender);
+  return BUG_BODY_FALLBACK(sender);
+}
+
+/** Owner 未解析且 Agent 主体缺失时的内部主体（不追加尾注） */
+function unresolvedBodyFallback(action: SupportAction, sender: string): string {
+  return action === "kb_gap" ? KB_GAP_BODY(sender) : OWNER_FAILED_CLARIFY_FALLBACK(sender);
+}
+
+const NOTIFICATION_TITLES: Partial<Record<SupportAction, (module: string, brief: string) => string>> = {
+  bug: (module, brief) => `【Bug 待跟进】【${module || "未知模块"}】${brief}`,
+  feature: (module, brief) => `【需求建议】【${module || "未知模块"}】${brief}`,
+  kb_gap: (_module, brief) => `【知识缺口待补充】${brief}`,
+};
+
+/** 问题摘要归一：折叠空白、去掉本地图片标记、截断 80 字 */
+export function questionBrief(content: string): string {
+  return content
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 80);
+}
+
+/**
+ * Owner 尾注拼接（评审修正）：尾注插在正文末尾的来源引用块（`> 来源:…`）之前，
+ * 保持来源链接始终在最末一行（与 handoff 基线的阅读顺序一致：正文 → 找人 → 出处）；
+ * 末尾无引用块时直接追加。
+ */
+export function appendOwnerFooter(body: string, footer: string): string {
+  const lines = body.split("\n");
+  let end = lines.length;
+  while (end > 0 && lines[end - 1]!.trim() === "") end--;
+  let start = end;
+  while (start > 0 && lines[start - 1]!.trimStart().startsWith(">")) start--;
+  if (start < end && start > 0) {
+    const before = lines.slice(0, start).join("\n").trimEnd();
+    const quote = lines.slice(start, end).join("\n");
+    return `${before}\n\n${footer}\n\n${quote}`;
+  }
+  return `${body}\n\n${footer}`;
+}
+
+export type ActionDispatch = {
+  /** 最终发送到群的正文；空串 = 群内不说话 */
+  finalReply: string;
+  resolvedOwnerName: string;
+  resolvedOwnerUserId: string;
+  ownerResolutionStatus: "not_needed" | "resolved" | "failed";
+  notificationTitle: string;
+  notificationContent: string;
+  notificationTargetUserId: string;
+  /** 仅 Owner 已确认可在当前群真实 @ 时非空 */
+  mentionUserId: string;
+  /** bug/feature 但 Agent 未产出合法 reply（用了内部兜底文案）——监控 Prompt/Schema 稳定性 */
+  agentReplyMissing: boolean;
+};
+
+export type BuildActionDispatchArgs = {
+  action: SupportAction;
+  policy: ActionPolicy;
+  /** Agent 生成的用户可见回复主体（可空） */
+  reply: string;
+  module: string;
+  reason: string;
+  /** 原始用户消息（通知摘要用） */
+  content: string;
+  senderName: string;
+  conversationId: string;
+  /** 仅 needsOwnerResolution(action) 时由调用方解析后传入；其余传 null（误传也会被归一为 not_needed） */
+  owner: OwnerResolution | null;
+  /** Owner 已确认可在当前群真实 @ 时的 userId；空则渲染花名 */
+  ownerMentionUserId?: string;
+};
+
+function buildNotification(args: BuildActionDispatchArgs, ownerUserId: string): {
+  notificationTitle: string;
+  notificationContent: string;
+  notificationTargetUserId: string;
+} {
+  const title = NOTIFICATION_TITLES[args.action];
+  if (!title) return { notificationTitle: "", notificationContent: "", notificationTargetUserId: "" };
+  const brief = questionBrief(args.content);
+  const lines = [
+    `原始问题：${brief}`,
+    `发送人：${args.senderName || "未知"}`,
+    `处置动作：${args.action}`,
+    ...(args.module ? [`模块：${args.module}`] : []),
+    ...(args.reason ? [`判定理由：${args.reason}`] : []),
+    ...(args.conversationId ? [`来源群：${args.conversationId}`] : []),
+    ...(ownerUserId ? [`Owner userid：${ownerUserId}`] : []),
+  ];
+  return {
+    notificationTitle: title(args.module, brief),
+    notificationContent: lines.join("\n"),
+    notificationTargetUserId: ownerUserId,
+  };
+}
+
+/**
+ * 合成最终处置。两个正交轴分开判定：
+ *
+ * 轴1 群内可见性（profile.group）：
+ * - `silent` → 群里一句不说，仅留痕 + 通知字段（Owner 解析结果仍进通知 target）；
+ * - `answer` → 群里发正文。
+ *
+ * 轴2 Owner 指引（Runtime 派生，与轴1 无关）：
+ * - needsOwnerResolution(action) 且 Owner 已解析 → 主体 + Owner 尾注（主体缺失用内部主体）；
+ * - needsOwnerResolution(action) 但 Owner 未解析 → 主体照发不加尾注、不写假 @；
+ * - 其余 action（reply 等）→ 透传 Agent 正文。
+ */
+export function buildActionDispatch(args: BuildActionDispatchArgs): ActionDispatch {
+  const base: ActionDispatch = {
+    finalReply: "",
+    resolvedOwnerName: "",
+    resolvedOwnerUserId: "",
+    ownerResolutionStatus: "not_needed",
+    notificationTitle: "",
+    notificationContent: "",
+    notificationTargetUserId: "",
+    mentionUserId: "",
+    agentReplyMissing: false,
+  };
+
+  // 轴2：Owner 解析结果归一（不需要找人的 action 一律视为 not_needed，即使调用方误传 owner）
+  const ownerNeeded = needsOwnerResolution(args.action);
+  const owner = ownerNeeded && args.owner?.status === "resolved" ? args.owner : null;
+  const ownerFields = {
+    resolvedOwnerName: owner?.ownerName ?? "",
+    resolvedOwnerUserId: owner?.ownerUserId ?? "",
+    ownerResolutionStatus: (!ownerNeeded ? "not_needed" : owner ? "resolved" : "failed") as ActionDispatch["ownerResolutionStatus"],
+  };
+  const notification = buildNotification(args, owner?.ownerUserId ?? "");
+  const mentionUserId = owner ? String(args.ownerMentionUserId ?? "").trim() : "";
+
+  // 轴1：群内不说话 → 只出通知字段（kb_gap 的知识收件箱、bug/feature 的自动化找人都不丢）
+  if (!speaksInGroup(args.policy)) {
+    return { ...base, ...ownerFields, ...notification };
+  }
+
+  // 轴1：群内说话
+  const body = args.reply.trim();
+  // 契约禁止 kb_gap 携带 reply → 主体缺失是预期而非异常，不计 agent_reply_missing
+  const agentReplyMissing = !body && (args.action === "bug" || args.action === "feature");
+
+  // 轴2：派生判定是否附 Owner 尾注
+  const finalReply = owner
+    ? appendOwnerFooter(
+        body || resolvedBodyFallback(args.action, args.senderName),
+        ownerFooter(
+          args.action,
+          renderOwnerMention(owner, mentionUserId),
+          owner.module,
+        ),
+      )
+    : ownerNeeded
+      ? body || unresolvedBodyFallback(args.action, args.senderName)
+      : body;
+
+  return { ...base, finalReply, agentReplyMissing, ...ownerFields, ...notification, mentionUserId };
+}

package/templates/support-qa/lib/assemble-cli.ts

@@ -0,0 +1,30 @@
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { assembleProfile } from "./assemble.js";
+
+/**
+ * profile 装配 CLI（模板内工具，tsx 运行）
+ *
+ *   npm run assemble  → 校验 + 写盘（persona.md / owner-map.json / role kb_collections）
+ *   npm run check     → 仅严格校验（preflight，不写盘）；有 error 退出码 1
+ */
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CONFIG_DIR = path.resolve(HERE, "..");
+const checkOnly = process.argv.includes("--check");
+
+const { issues, wrote } = assembleProfile(CONFIG_DIR, { dryRun: checkOnly });
+
+for (const i of issues) {
+  console.log(`${i.level === "error" ? "✗" : "⚠"} [${i.level}] ${i.message}`);
+}
+for (const w of wrote) {
+  console.log(`✓ 已更新 ${path.relative(CONFIG_DIR, w)}`);
+}
+
+const errors = issues.filter((i) => i.level === "error").length;
+if (errors > 0) {
+  console.log(`\nprofile ${checkOnly ? "校验" : "装配"}失败：${errors} 个错误（未产出任何文件）`);
+  process.exit(1);
+}
+console.log(`\nprofile ${checkOnly ? "校验通过" : `装配完成（${wrote.length} 个文件更新）`}`);

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

@@ -0,0 +1,279 @@
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { SUPPORT_ACTIONS, KB_STATUS, KB_STATUS_VALUES } from "./contract.js";
+import { loadFastpathRules } from "./fastpath.js";
+import { isTroubleshootEnabled, loadClassifiers } from "./troubleshoot.js";
+
+/**
+ * 最小 profile 装配器（场景层，零 core 依赖）
+ *
+ * profile v2 重构后职责收敛：
+ *   1. roles.support.persona → 读取并写入 workspaces/support/persona.md
+ *      （AGENTS.md 基座第一段声明"人设以本目录 persona.md 为准"）；
+ *   2. preflight：group-qa 处置动作/知识沉淀 options 与 lib/contract.ts 常量强校验，
+ *      admin-kb-update 事件过滤校验，on_action policies 键/值闭集校验（action ⊆
+ *      SUPPORT_ACTIONS，group ∈ answer|silent，Owner 尾注由轴2派生不在此配），
+ *      L3 fastpath/troubleshoot 预检。
+ *
+ * 已删除的职责：
+ *   - escalation → owner-map/contacts.json 编译与校验：模块→Owner 映射已迁入 AI 表格
+ *     「功能模块人员配置表」，由 config-sync 拉取并发布 ${globalVar.module_owners}，
+ *     同时物化 workspaces/support/owner-map.json 供 answer Agent 的 module 闭集提示；
+ *   - role.yml kb_collections 同步（roles 已内联进 profile.yml）；
+ *   - admin-kb-update source-range 回写（由 ${roles.*} 内部引用 + 注入取代）。
+ *
+ * 两阶段执行：
+ *   阶段一 全量校验 + 生成写盘计划（任一 error → 不写任何文件，杜绝半成品）；
+ *   阶段二 按计划一次性写盘（内容不变不写，幂等）。
+ */
+
+export type AssembleIssue = { level: "error" | "warn"; message: string };
+export type AssembleResult = { issues: AssembleIssue[]; wrote: string[] };
+
+const WORKSPACE_DIR = path.join("workspaces", "support");
+const GENERATED_HEADER = "<!-- 由 lib/assemble.ts 依据 profile/profile.yml 生成，勿手改；改 profile 后重跑 npm run assemble -->";
+
+type WritePlanEntry = { file: string; content: string };
+
+function readRawProfile(configDir: string, issues: AssembleIssue[]): Record<string, unknown> | null {
+  const file = path.resolve(configDir, "profile", "profile.yml");
+  if (!existsSync(file)) {
+    issues.push({ level: "error", 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: "error", message: `profile.yml schema_version 必须为 2（当前: ${raw.schema_version ?? "缺失"}）。请按迁移指引升级。` });
+      return null;
+    }
+    return raw;
+  } catch (err) {
+    issues.push({ level: "error", message: `profile/profile.yml 解析失败: ${err instanceof Error ? err.message : String(err)}` });
+    return null;
+  }
+}
+
+/** 相对 profile 目录解析引用文件；不存在则记 error 并返回 null */
+function resolveRef(configDir: string, rel: string, label: string, issues: AssembleIssue[]): string | null {
+  const abs = path.resolve(configDir, "profile", rel);
+  if (!existsSync(abs)) {
+    issues.push({ level: "error", message: `${label} 引用的文件不存在: profile/${rel}` });
+    return null;
+  }
+  return abs;
+}
+
+/** collections 校验：trim、去空、必须是不含 .. 的相对路径、目录须存在 */
+function validateCollections(configDir: string, raw: unknown, issues: AssembleIssue[]): string[] {
+  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: "error", message: "roles.support.knowledge_scope.kb_collections 缺失、为空或含空字符串（必填）" });
+  }
+  const collections = list.filter(Boolean);
+  for (const c of collections) {
+    if (path.isAbsolute(c) || c.split(/[\\/]/).includes("..")) {
+      issues.push({ level: "error", message: `kb_collections 必须是实例内的相对路径（不含 ..）: ${c}` });
+      continue;
+    }
+    if (!existsSync(path.resolve(configDir, c))) {
+      issues.push({ level: "error", message: `kb_collections 目录不存在: ${c}` });
+    }
+  }
+  return collections;
+}
+
+/** 集合严格相等比较 */
+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;
+}
+
+export function assembleProfile(configDir: string, opts: { dryRun?: boolean } = {}): AssembleResult {
+  const issues: AssembleIssue[] = [];
+  const plan: WritePlanEntry[] = [];
+  const wrote: string[] = [];
+
+  // ─── 阶段一：全量校验 + 生成写盘计划 ───
+  const raw = readRawProfile(configDir, issues);
+  if (!raw) return { issues, wrote };
+
+  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"];
+
+  // basic validation
+  const roleName = typeof supportRole?.name === "string" ? supportRole.name.trim() : "";
+  if (!roleName) issues.push({ level: "error", message: "roles.support.name 缺失（必填）" });
+  const kbScope = supportRole?.knowledge_scope as Record<string, unknown> | undefined;
+  validateCollections(configDir, kbScope?.kb_collections, issues);
+
+  // 1) persona.md — 读 roles.support.persona（file 引用或内联字符串）
+  const personaField = supportRole?.persona;
+  let personaText = "";
+  if (typeof personaField === "string") {
+    personaText = `${GENERATED_HEADER}\n\n${personaField.trim()}`;
+  } else if (personaField && typeof personaField === "object" && "file" in personaField) {
+    const fileRel = String((personaField as { file: string }).file ?? "").trim();
+    if (!fileRel) {
+      issues.push({ level: "error", message: "roles.support.persona.file 为空" });
+    } else {
+      const abs = resolveRef(configDir, fileRel, "roles.support.persona.file", issues);
+      if (abs) {
+        const content = readFileSync(abs, "utf8").trim();
+        if (!content) {
+          issues.push({ level: "error", message: `roles.support.persona.file 文件内容为空: profile/${fileRel}` });
+        }
+        personaText = `${GENERATED_HEADER}\n\n${content}`;
+      }
+    }
+  } else if (supportRole) {
+    issues.push({ level: "error", message: "roles.support.persona 缺失（必填）" });
+  }
+  if (personaText) {
+    if (/忽略(上述|以上|通用)|必须回复所有|无据也(可以|要)回答|不用静默/.test(personaText)) {
+      issues.push({ level: "error", message: "persona 内容疑似放开通用闸门（只准收紧，不准放开），请修改后重试" });
+    }
+    plan.push({ file: path.resolve(configDir, WORKSPACE_DIR, "persona.md"), content: personaText });
+  }
+
+  // 2) escalation 已迁移：模块→Owner 映射改由 config-sync 从「功能模块人员配置表」拉取，
+  // 装配期不再编译/校验 owner-map×contacts（模块合法性由运行期快照判定）。
+
+  // 2b) on_action policies 闭集校验（读 workflows.group-qa.steps.on_action.policies）：
+  // 键必须 ⊆ SUPPORT_ACTIONS；group 只允许 answer / silent——group 只表达「群里说不说话」（轴1），
+  // Owner 指引由 Runtime 按「action 需要找人 + Owner 可解析」派生（轴2），不存在「通知 Owner」档位。
+  const onActionStep = getIn(groupQaWf, "steps", "on_action") as Record<string, unknown> | undefined;
+  const policiesRaw = onActionStep?.policies;
+  if (policiesRaw && typeof policiesRaw === "object") {
+    const configuredActions = Object.keys(policiesRaw);
+    const { extra } = diffSets(configuredActions, SUPPORT_ACTIONS);
+    if (extra.length > 0) {
+      issues.push({ level: "error", 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", 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", message: "workflows.group-qa.steps.on_silence 已废弃（拍平 action 后步为 on_action）：请迁移为 steps.on_action.policies（track/group）" });
+  }
+
+  // 3) group-qa preflight：处置动作/知识沉淀 options 与 contract 常量强校验
+  const groupQaFile = path.resolve(configDir, "workflows", "group-qa", "workflow.yml");
+  if (existsSync(groupQaFile)) {
+    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", message: `group-qa 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", message: `group-qa「${fieldName}」options 与 lib/contract.ts 不一致：缺[${missing.join(",")}] 多[${extra.join(",")}]` });
+        }
+      }
+    } catch (err) {
+      issues.push({ level: "error", message: `workflows/group-qa/workflow.yml 解析失败: ${err instanceof Error ? err.message : String(err)}` });
+    }
+  }
+
+  // 4) admin-kb-update filter preflight（从 profile v2 读取）
+  const adminKbWf = workflows["admin-kb-update"];
+  if (adminKbWf) {
+    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", message: `admin-kb-update 事件过滤 filter.equals="${filterEquals}" 必须为 "${KB_STATUS.READY_TO_PERSIST}"（否则知识更新轨道不拉单）` });
+    }
+  }
+
+  // 6) L3 fastpath 规则预检（warn：运行期缺失即优雅关闭，不阻断 L0 主环）
+  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 } = loadFastpathRules(configDir, fastpathRel);
+    for (const msg of fpIssues) issues.push({ level: "warn", message: `fastpath: ${msg}` });
+  }
+
+  // 7) L3 troubleshoot 预检（warn：整档可选且运行期缺失即优雅关闭）
+  const troubleshootStep = getIn(groupQaWf, "steps", "troubleshoot") as Record<string, unknown> | undefined;
+  const skillsDirRel = typeof troubleshootStep?.skills_dir === "string" ? troubleshootStep.skills_dir.trim() : "";
+  if (skillsDirRel && !isTroubleshootEnabled(configDir, skillsDirRel)) {
+    issues.push({ level: "warn", message: `troubleshoot: skills_dir 目录不存在，整档将关闭: ${skillsDirRel}` });
+  }
+  const classifiersRel = typeof troubleshootStep?.classifiers === "string" ? troubleshootStep.classifiers.trim() : "";
+  if (classifiersRel) {
+    const { issues: tsIssues } = loadClassifiers(configDir, classifiersRel);
+    for (const msg of tsIssues) issues.push({ level: "warn", message: `troubleshoot: ${msg}` });
+    // classifier.module 合法性不再在装配期交叉校验：模块闭集来自功能模块人员配置表
+    // （config-sync 运行期快照），拼写不匹配时运行期降级并记 owner_resolution_failed。
+  }
+
+  // ─── 阶段二：全过才写盘；任一 error 或 dryRun → 零写盘 ───
+  const hasError = issues.some((i) => i.level === "error");
+  if (opts.dryRun || hasError) return { issues, wrote };
+
+  for (const entry of plan) {
+    try {
+      const prev = existsSync(entry.file) ? readFileSync(entry.file, "utf8") : null;
+      if (prev === entry.content) continue;
+      mkdirSync(path.dirname(entry.file), { recursive: true });
+      writeFileSync(entry.file, entry.content, "utf8");
+      wrote.push(entry.file);
+    } catch (err) {
+      issues.push({ level: "error", message: `写盘失败 ${path.relative(configDir, entry.file)}: ${err instanceof Error ? err.message : String(err)}` });
+    }
+  }
+
+  return { issues, wrote };
+}
+
+// ─── 运行时兜底：进程内每 configDir 只装配一次，结果缓存供调用方决策 ───
+const assembledResults = new Map<string, AssembleResult>();
+
+export function ensureAssembled(configDir: string, log: (msg: string) => void): AssembleResult {
+  const cached = assembledResults.get(configDir);
+  if (cached) return cached;
+  let result: AssembleResult;
+  try {
+    result = assembleProfile(configDir);
+  } catch (err) {
+    result = { issues: [{ level: "error", message: `装配异常: ${err instanceof Error ? err.message : String(err)}` }], wrote: [] };
+  }
+  assembledResults.set(configDir, result);
+  for (const i of result.issues) log(`[profile-assemble][${i.level}] ${i.message}`);
+  if (result.wrote.length > 0) log(`[profile-assemble] 已更新: ${result.wrote.map((w) => path.relative(configDir, w)).join(", ")}`);
+  return result;
+}