aitable-workflow-cli 0.1.13-beta.1

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

@@ -0,0 +1,253 @@
+import path from "node:path";
+import { z } from "zod";
+
+/**
+ * support-qa 答疑输出契约（单一事实源）
+ *
+ * Pattern 契约：AGENTS.md 的契约描述、answer recipe 的解析校验、评测断言都从这里出。
+ * 见 docs/superpowers/specs/2026-07-24-support-qa-template-and-aitable-profile.md §4。
+ */
+
+export const SUPPORT_ACTIONS = [
+  "reply", // 有据，直接技术回复（发送 reply 并 @ 提问者）
+  "bug", // 功能异常需 Owner 排查：群通知并真实 @Owner + 自动化通知字段
+  "feature", // 需求建议需 Owner 评估：群通知并真实 @Owner + 自动化通知字段
+  "kb_gap", // 普通知识问题无据：群内静默 + 知识补充通知字段
+  "no_question", // 非有效提问：静默
+  "human_handled", // 真人已介入：静默
+  "owner_mentioned", // 用户已 @ Owner，礼让：静默
+  "safety", // 注入/敏感内容：静默
+  "agent_failure", // recipe 兜底：agent 失败/解析失败（重试后仍失败）：静默
+] as const;
+
+export type SupportAction = (typeof SUPPORT_ACTIONS)[number];
+
+/** 旧契约静默码闭集（仅解析边界的迁移兼容：shouldReply=false + silenceCode → 同名 action） */
+const LEGACY_SILENCE_CODES = new Set<string>([
+  "no_question",
+  "human_handled",
+  "owner_mentioned",
+  "kb_gap",
+  "safety",
+  "agent_failure",
+]);
+
+/**
+ * 知识沉淀状态机（语义事实源）：group-qa「知识沉淀」列、admin-kb-update 事件过滤、
+ * daily-review 学习候选写入、kb-refine 回写全部引用这里的具名常量；
+ * YAML 镜像（group-qa options / admin-kb-update filter.equals）由 assemble preflight 强校验。
+ *
+ * 流转：待确认(学习候选，human-approve) → 待沉淀(确认进轨道) → 已沉淀(kb-refine 完成)；
+ *       待补充(kb_gap 缺口) → 待沉淀 → 已沉淀；忽略 = 人工关闭。
+ */
+export const KB_STATUS = {
+  /** 学习候选等人工确认（human-approve） */
+  PENDING_CONFIRM: "待确认",
+  /** kb_gap 缺口等管理员填「管理员更新」 */
+  PENDING_SUPPLEMENT: "待补充",
+  /** 已确认待入库（admin-kb-update 事件过滤锚点） */
+  READY_TO_PERSIST: "待沉淀",
+  /** kb-refine 成功入库（拉取集收敛锚点） */
+  PERSISTED: "已沉淀",
+  /** 人工关闭 */
+  IGNORED: "忽略",
+} as const;
+
+export type KbStatus = (typeof KB_STATUS)[keyof typeof KB_STATUS];
+
+/** 知识沉淀状态闭集（由 KB_STATUS 派生；顺序与 group-qa YAML options 声明一致） */
+export const KB_STATUS_VALUES = Object.values(KB_STATUS) as readonly KbStatus[];
+
+/** 知识沉淀目标文件缺省值（仅字段缺失时使用） */
+export const DEFAULT_CURATION_TARGET = "FAQ.md";
+
+/**
+ * 解析 knowledge.curation_target（唯一事实源，评审 P1）：assemble 定点回写与 kb-refine
+ * 运行期写入共用同一套规则，杜绝“assemble 放行、recipe 又改写”的双源分家。
+ *
+ * 规则：字段缺失(undefined) → 缺省 FAQ.md；显式值必须是非空字符串、不含换行、
+ * 非绝对路径、不含 `..` 路径段、且以 .md 结尾；否则返回 error（不自动修正、不静默回退）。
+ */
+export function resolveCurationTarget(raw: unknown): { value: string; error: string | null } {
+  if (raw === undefined) return { value: DEFAULT_CURATION_TARGET, error: null };
+  if (typeof raw !== "string" || !raw.trim()) {
+    return { value: "", error: `knowledge.curation_target 必须是非空字符串（省略整项则缺省 ${DEFAULT_CURATION_TARGET}），实际: ${JSON.stringify(raw)}` };
+  }
+  const target = raw.trim();
+  if (/[\r\n]/.test(raw) || path.isAbsolute(target) || target.split(/[\\/]/).includes("..")) {
+    return { value: "", error: `knowledge.curation_target 必须是不含 .. 和换行的相对文件路径: ${target}` };
+  }
+  if (!target.endsWith(".md")) {
+    return { value: "", error: `knowledge.curation_target 必须以 .md 结尾（不自动补扩展名）: ${target}` };
+  }
+  return { value: target, error: null };
+}
+
+export type SupportReply = {
+  /** 唯一的最终处置结果（下游只按 action 路由，无第二事实源） */
+  action: SupportAction;
+  /** 判定理由简述（审计用，不发给用户）；强制非空——空审计理由视为非法输出 */
+  reason: string;
+  /**
+   * action=reply 必填（完整技术回答）；action=bug/feature 应有（针对本次问题的用户可见回复主体，
+   * 缺失不判非法——由 on_action 用内部兜底文案并记 agent_reply_missing，见 spec §5.3/§6.4）；
+   * 其余 action 禁止携带（避免“一边静默一边回答”）。
+   */
+  reply?: string;
+  /** bug/feature/kb_gap 尽量给出：必须是 owner-map.json 的精确 key；不确定省略，禁止猜测 */
+  module?: string;
+};
+
+/** 可携带 reply 的 action（reply 强制、bug/feature 可选） */
+const REPLY_BEARING_ACTIONS = new Set<string>(["reply", "bug", "feature"]);
+
+export const supportReplySchema = z
+  .object({
+    action: z.enum(SUPPORT_ACTIONS),
+    // 强制非空审计理由：旧输出（含 legacy 转换）缺 reason 会解析失败，
+    // 由现有 retry 与 agent_failure 兜底；不为兼容旧脏输出接受空理由。
+    reason: z.string().trim().min(1),
+    reply: z.string().optional(),
+    module: z.string().optional(),
+  })
+  .superRefine((v, ctx) => {
+    if (v.action === "reply" && !(v.reply ?? "").trim()) {
+      ctx.addIssue({ code: "custom", message: "action=reply 时 reply 必填" });
+    }
+    if (!REPLY_BEARING_ACTIONS.has(v.action) && (v.reply ?? "").trim()) {
+      ctx.addIssue({ code: "custom", message: `action=${v.action} 不得携带 reply` });
+    }
+  });
+
+/**
+ * 尝试解析 JSON 字符串；如果 JSON.parse 失败，尝试修复字符串值中未转义的双引号。
+ * 典型场景：模型在 reply 字段中原样引用了用户消息里的中文双引号 "xxx"，
+ * 导致 JSON 结构被破坏。
+ */
+function safeParseJson(jsonStr: string): unknown {
+  try {
+    return JSON.parse(jsonStr);
+  } catch {
+    // noop — fall through to repair
+  }
+  // Repair: find string values and escape unescaped inner quotes.
+  // Strategy: walk through the JSON char-by-char, track whether we're inside a string,
+  // and fix unescaped quotes that don't terminate a value properly.
+  try {
+    const repaired = repairJsonStringValues(jsonStr);
+    return JSON.parse(repaired);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Attempt to repair unescaped double quotes inside JSON string values.
+ * Works by scanning char-by-char: when inside a string, if we hit a `"` that is
+ * followed by characters that can't legally follow a closed string (not `:`, `,`, `}`, `]`, whitespace),
+ * we treat it as an unescaped quote and escape it.
+ */
+function repairJsonStringValues(json: string): string {
+  const result: string[] = [];
+  let i = 0;
+  let inString = false;
+
+  while (i < json.length) {
+    const ch = json[i];
+
+    if (!inString) {
+      result.push(ch);
+      if (ch === '"') inString = true;
+      i++;
+    } else {
+      // Inside a string
+      if (ch === '\\') {
+        // Escaped char — take both
+        result.push(ch, json[i + 1] ?? '');
+        i += 2;
+      } else if (ch === '"') {
+        // Could be end-of-string or an unescaped inner quote.
+        // Look ahead: if the next non-whitespace char is one of : , } ] then this is a real close quote.
+        let lookAhead = i + 1;
+        while (lookAhead < json.length && (json[lookAhead] === ' ' || json[lookAhead] === '\t' || json[lookAhead] === '\n' || json[lookAhead] === '\r')) {
+          lookAhead++;
+        }
+        const nextCh = json[lookAhead];
+        if (nextCh === ':' || nextCh === ',' || nextCh === '}' || nextCh === ']' || nextCh === undefined) {
+          // Legitimate string close
+          result.push(ch);
+          inString = false;
+          i++;
+        } else {
+          // Unescaped inner quote — escape it
+          result.push('\\"');
+          i++;
+        }
+      } else {
+        result.push(ch);
+        i++;
+      }
+    }
+  }
+
+  return result.join('');
+}
+
+/**
+ * 从 agent 自由文本中稳健提取契约 JSON；失败返回 null（由调用方决定重试/兜底）。
+ *
+ * 迁移兼容（spec §14.1）：旧 {shouldReply, silenceCode} 输出只在本解析边界转换为 action，
+ * 返回对象不再暴露 shouldReply/silenceCode；旧静默输出若误带 reply 一律丢弃。
+ */
+export function extractSupportReply(raw: string): SupportReply | null {
+  if (!raw) return null;
+  let s = raw.trim();
+  const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence?.[1]) s = fence[1].trim();
+  const start = s.indexOf("{");
+  const end = s.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  const jsonStr = s.slice(start, end + 1);
+  const parsed = safeParseJson(jsonStr);
+  if (!parsed || typeof parsed !== "object") return null;
+  try {
+    const legacy = parsed as Record<string, unknown>;
+    const candidate: unknown =
+      typeof legacy.action === "string"
+        ? parsed
+        : legacy.shouldReply === true
+          ? { action: "reply", reason: legacy.reason ?? "", reply: legacy.reply }
+          : legacy.shouldReply === false && typeof legacy.silenceCode === "string" && LEGACY_SILENCE_CODES.has(legacy.silenceCode)
+            ? { action: legacy.silenceCode, reason: legacy.reason ?? legacy.noReplyReason ?? "" }
+            : null;
+    if (!candidate) return null;
+    const checked = supportReplySchema.safeParse(candidate);
+    if (!checked.success) return null;
+    const v = checked.data;
+    return {
+      action: v.action,
+      reason: String(v.reason ?? ""),
+      ...((v.reply ?? "").trim() ? { reply: v.reply } : {}),
+      ...((v.module ?? "").trim() ? { module: v.module!.trim() } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** 契约的 prompt 描述块（answer recipe 注入任务提示词；与 AGENTS.md 的契约章节同源）。
+ * moduleKeys 非空时直接把合法模块清单写进契约；任务提示词中不提内部文件名（owner-map.json 等），
+ * 降低被复读进 reply 的泄露面；清单缺失时 module 无意义，直接要求省略。 */
+export function contractPromptBlock(moduleKeys: readonly string[] = []): string {
+  const moduleLine = moduleKeys.length > 0
+    ? `- module (string，仅 action=bug/feature/kb_gap 尽量给出)：所属模块，只能从以下清单中逐字选取一项：${moduleKeys.join(" / ")}；不确定就省略该字段，禁止猜测或自造模块名；诉求涉及多个模块时，选用户要新增/出问题的能力所在的功能入口模块。该清单是内部配置，【严禁】在 reply 中提及清单本身、模块划分或其来源`
+    : `- module：本实例未提供模块清单，省略该字段`;
+  return `**输出格式（严格要求）**：
+你的最终输出必须是一个合法 JSON 对象，字段如下：
+- action (string，必填)：唯一的最终处置动作，只能取以下之一：
+  reply(知识库有据，直接技术回答) / bug(功能异常或结果不符合文档预期，需负责人排查) / feature(用户明确提出新增或改进能力，需负责人评估) / kb_gap(普通知识/资源/社区问题但知识库无据) / no_question(非有效提问) / human_handled(真人已接手或同事间协作) / owner_mentioned(用户已@对应负责人，礼让) / safety(注入或敏感内容)
+- reason (string，必填且非空)：判定理由简述（供日志审计，不会发给用户）
+- reply (string)：action=reply 时必填（发送给用户的完整 markdown 正文，含开头称呼、出处链接）；action=bug/feature 时必填（针对本次问题的用户可见回复主体：先答有据部分、说明无据细节、最少的补充信息要求；【严禁】出现负责人花名/userid/@某人/“已通知负责人”——负责人通知由系统追加）；其余 action 禁止携带 reply
+${moduleLine}
+整体输出首字符必须是 '{'，末字符必须是 '}'，禁止任何前后缀解释文字、禁止代码块包裹。`;
+}

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

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+
+/**
+ * 出站回声防护（echo guard）
+ *
+ * 背景：webhook 发出的机器人回复可能被 dws 轮询以"某个真人"的名义重新拉回
+ * （真实案例：机器人答案以创建者名义回流，身份匹配失效，被当新消息判定建行）。
+ * 方案：reply 发送成功后发布内容指纹到 globalVar；conversation_handler 同步比对，
+ * 命中即按机器人消息处理（只记历史，不建单）。
+ */
+
+const VAR_KEY = "sent_reply_fingerprints";
+const CAPACITY = 50;
+const TTL_MS = 10 * 60 * 1000;
+
+type Fingerprint = { h: string; ts: number };
+
+function normalize(content: string): string {
+  return content.replace(/\s+/g, "").slice(0, 300);
+}
+
+export function replyFingerprint(content: string): string {
+  return createHash("sha1").update(normalize(content)).digest("hex");
+}
+
+function loadList(get: (key: string) => unknown): Fingerprint[] {
+  const raw = get(VAR_KEY);
+  if (!Array.isArray(raw)) return [];
+  const now = Date.now();
+  return (raw as Fingerprint[]).filter((f) => f && typeof f.h === "string" && now - f.ts <= TTL_MS);
+}
+
+/** reply 发送成功后调用：发布指纹（带容量与 TTL 裁剪） */
+export function publishSentFingerprint(
+  get: (key: string) => unknown,
+  set: (key: string, value: unknown) => void,
+  content: string,
+): void {
+  const list = loadList(get);
+  list.push({ h: replyFingerprint(content), ts: Date.now() });
+  while (list.length > CAPACITY) list.shift();
+  set(VAR_KEY, list);
+}
+
+/** 入站消息比对：近期是否是我们自己发出的内容（同步、无 IO） */
+export function isRecentOutboundEcho(get: (key: string) => unknown, content: string): boolean {
+  if (!content.trim()) return false;
+  const h = replyFingerprint(content);
+  return loadList(get).some((f) => f.h === h);
+}

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

@@ -0,0 +1,227 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+
+/**
+ * fastpath 声明式规则引擎（support-qa L3，场景层，零 core 依赖）
+ *
+ * 确定性秒回：按 profile/fastpath/known-answers.yml 声明的规则，用纯匹配（非 LLM）
+ * 把命中消息直接映射为固定话术。规则三选一：
+ *   - template：与消息全文（空白归一后）全等；
+ *   - contains：消息包含该子串（单向）；
+ *   - regex：正则 test 消息。
+ * 另有 safety 安全兜底关键词（最高优先级），命中即返回安全话术。
+ *
+ * 关键不变量——【单向匹配】：一律「消息文案 message 包含/匹配规则模式」，
+ * 绝不反向（规则 key/pattern 包含 message）。这修复了 aitable-handoff
+ * known-error-match 里 `errorMessage.includes(k) || k.includes(errorMessage)`
+ * 的双向 includes 误配 bug（短消息会错误命中长规则）。
+ *
+ * 关键不变量——【只看用户本轮新话】：规则匹配前剥离钉钉「引用消息:」块
+ * （引用内容往往就是本机器人上一轮的回复，不剥离就会在用户追问时把同一段
+ * 话术复读一遍）；safety 安全兜底依然看全文，防止注入/敏感内容藏在引用块里绕过拦截。
+ *
+ * 关闭语义：profile.fastpath.rules 未配置或文件缺失 → config=null → 透传给 answer。
+ */
+
+export const fastpathRulesSchema = z.object({
+  safety: z.object({
+    keywords: z.array(z.string().min(1)).min(1),
+    reply: z.string().min(1),
+  }).optional(),
+  rules: z.array(z.object({
+    key: z.string().min(1),
+    template: z.string().optional(),
+    contains: z.string().optional(),
+    regex: z.string().optional(),
+    reply: z.string().min(1),
+  }).refine(
+    (r) => [r.template, r.contains, r.regex].filter((v) => v !== undefined && v.trim()).length === 1,
+    { message: "必须且只能有 template/contains/regex 之一" },
+  )),
+});
+
+export type FastpathRule = {
+  /** 规则标识（报错/日志文案含此 key，便于排障与追溯） */
+  key: string;
+  template?: string;
+  contains?: string;
+  regex?: string;
+  /** 加载时预编译的正则（与校验同一实例），避免逐消息重编 */
+  compiledRegex?: RegExp;
+  reply: string;
+};
+
+export type FastpathSafety = {
+  keywords: string[];
+  reply: string;
+};
+
+export type FastpathConfig = {
+  safety?: FastpathSafety;
+  rules: FastpathRule[];
+};
+
+export type FastpathMatch = {
+  key: string;
+  reply: string;
+  kind: "safety" | "template" | "contains" | "regex";
+};
+
+export type FastpathLoadResult = {
+  /** null = 未配置或文件缺失（fastpath 关闭，透传 answer） */
+  config: FastpathConfig | null;
+  issues: string[];
+};
+
+const cache = new Map<string, FastpathLoadResult>();
+
+/** 空白归一（template 全等匹配用） */
+function normalizeWs(s: string): string {
+  return s.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * 钉钉「引用消息:」标记：其后内容是被引用的历史消息，不属于用户本轮诉求。
+ * 包含半角/全角冒号两种变体（不同客户端文案不一致）。
+ */
+const QUOTE_MARKERS = ["引用消息:", "引用消息："];
+
+/**
+ * 剥离引用块，只保留用户本轮新话（确定性秒回只能据用户新诉求判定）。
+ *
+ * 为何需要：用户带引用追问时，引用块里往往完整包含上一轮的报错文案与本机器人的
+ * 回复，全文 contains 会再匹配到同一条规则 → 复读同一段话术（7-25 评测 g4-21/g4-22）。
+ *
+ * 边界：剥离后为空（用户只转发引用、自己没打字）→ 返回原文，那种场景本来就应该秒回。
+ */
+export function stripQuotedBlock(message: string): string {
+  const msg = message ?? "";
+  let cut = msg.length;
+  for (const marker of QUOTE_MARKERS) {
+    const i = msg.indexOf(marker);
+    if (i >= 0 && i < cut) cut = i;
+  }
+  if (cut >= msg.length) return msg;
+  const head = msg.slice(0, cut).trim();
+  return head || msg;
+}
+
+/** 加载并校验 fastpath 规则；按解析后的绝对路径缓存 */
+export function loadFastpathRules(configDir: string, rulesRel: string | undefined): FastpathLoadResult {
+  const rel = String(rulesRel ?? "").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: FastpathLoadResult;
+  if (!existsSync(abs)) {
+    // 文件缺失 → 关闭（graceful，不阻断 L0）；preflight 另行告警
+    res = { config: null, issues: [`fastpath.rules 引用的文件不存在: profile/${rel}`] };
+  } else {
+    try {
+      const raw = (parseYaml(readFileSync(abs, "utf8")) ?? {}) as Record<string, unknown>;
+      const issues: string[] = [];
+      res = { config: normalizeConfig(raw, issues), issues };
+    } catch (err) {
+      res = { config: null, issues: [`fastpath 规则解析失败 profile/${rel}: ${err instanceof Error ? err.message : String(err)}`] };
+    }
+  }
+  cache.set(abs, res);
+  return res;
+}
+
+function normalizeConfig(raw: Record<string, unknown>, issues: string[]): FastpathConfig {
+  const rules: FastpathRule[] = [];
+  const rawRules = Array.isArray(raw.rules) ? raw.rules : [];
+  for (let i = 0; i < rawRules.length; i++) {
+    const r = rawRules[i] as Record<string, unknown> | null;
+    if (!r || typeof r !== "object") {
+      issues.push(`rules[${i}] 不是对象`);
+      continue;
+    }
+    const key = String(r.key ?? "").trim();
+    const reply = String(r.reply ?? "").trim();
+    if (!key) {
+      issues.push(`rules[${i}] 缺少 key`);
+      continue;
+    }
+    if (!reply) {
+      issues.push(`rules[${key}] 缺少 reply`);
+      continue;
+    }
+    const present = (["template", "contains", "regex"] as const).filter(
+      (k) => typeof r[k] === "string" && String(r[k]).trim(),
+    );
+    if (present.length !== 1) {
+      issues.push(`rules[${key}] 必须且只能有 template/contains/regex 之一（当前 ${present.length} 个）`);
+      continue;
+    }
+    const rule: FastpathRule = { key, reply };
+    if (typeof r.template === "string") rule.template = r.template;
+    if (typeof r.contains === "string") rule.contains = r.contains;
+    if (typeof r.regex === "string") {
+      try {
+        rule.compiledRegex = new RegExp(r.regex);
+      } catch {
+        issues.push(`rules[${key}] 非法正则: ${r.regex}`);
+        continue;
+      }
+      rule.regex = r.regex;
+    }
+    rules.push(rule);
+  }
+
+  let safety: FastpathSafety | undefined;
+  const rawSafety = raw.safety as Record<string, unknown> | undefined;
+  if (rawSafety && typeof rawSafety === "object") {
+    const keywords = Array.isArray(rawSafety.keywords)
+      ? rawSafety.keywords.map((k) => String(k)).filter(Boolean)
+      : [];
+    const reply = String(rawSafety.reply ?? "").trim();
+    if (keywords.length > 0 && reply) safety = { keywords, reply };
+    else issues.push("safety 需同时提供非空 keywords 与 reply（否则忽略）");
+  }
+
+  return { safety, rules };
+}
+
+/**
+ * 匹配 fastpath（单向）：安全兜底优先，其次规则按声明顺序。
+ * 一律「消息包含/匹配规则模式」，不做反向包含。
+ *
+ * safety 看全文（敏感内容/注入藏在引用块里也要拦）；普通规则只看剥离引用后的
+ * 用户新话（避免带引用追问时复读上一轮话术）。
+ */
+export function matchFastpath(config: FastpathConfig | null, message: string): FastpathMatch | null {
+  if (!config) return null;
+  const msg = message ?? "";
+  if (!msg.trim()) return null;
+
+  // 安全兜底：消息（含引用内容）包含任一安全关键词（单向）
+  if (config.safety) {
+    for (const kw of config.safety.keywords) {
+      if (kw && msg.includes(kw)) return { key: "safety", reply: config.safety.reply, kind: "safety" };
+    }
+  }
+
+  // 普通规则：只对用户本轮新话匹配
+  const own = stripQuotedBlock(msg);
+  if (!own.trim()) return null;
+
+  for (const rule of config.rules) {
+    if (rule.template !== undefined) {
+      if (normalizeWs(own) === normalizeWs(rule.template)) {
+        return { key: rule.key, reply: rule.reply, kind: "template" };
+      }
+    } else if (rule.contains !== undefined) {
+      if (own.includes(rule.contains)) return { key: rule.key, reply: rule.reply, kind: "contains" }; // 单向
+    } else if (rule.regex !== undefined) {
+      // 用预编译实例（加载期已校验），避免逐消息重编
+      if (rule.compiledRegex?.test(own)) return { key: rule.key, reply: rule.reply, kind: "regex" };
+    }
+  }
+  return null;
+}

package/templates/support-qa/lib/memory-events.ts

@@ -0,0 +1,94 @@
+import type { MemoryEntry, MemoryScope } from "aitable-workflow-core";
+
+/**
+ * support-qa 记忆事件词表（场景层单一事实源）
+ *
+ * 写入方：conversation_handler(user/admin 消息)、answer(agent 决策)、reply(发送结果)。
+ * 读取方：answer(长期记忆注入)、daily-review(复盘/学习提炼)。
+ */
+
+export const SUPPORT_SCENARIO = "support-qa";
+export const SUPPORT_CHANNEL = "dingtalk";
+
+export const SUPPORT_MEMORY_KINDS = {
+  userMessage: "user_message",
+  /** 管理员/真人同事在群里的发言（学习通道的原料，勿删） */
+  adminMessage: "admin_message",
+  agentDecision: "agent_decision",
+  agentReplySent: "agent_reply_sent",
+  /** 升级找人已发群（bug/feature/kb_gap，带 Owner 指引或坦白无据）——不计入普通技术回答数量 */
+  ownerEscalationSent: "owner_escalation_sent",
+  /** bug/feature 无法解析 Owner（模块缺失/未知/缺联系人）——诊断用，不计回答 */
+  ownerResolutionFailed: "owner_resolution_failed",
+  sendFailed: "send_failed",
+  /** agent 失败兜底静默（重试后仍失败）——与"判定型静默"分开审计 */
+  agentFailure: "agent_failure",
+} as const;
+
+export type SupportMemoryKind = (typeof SUPPORT_MEMORY_KINDS)[keyof typeof SUPPORT_MEMORY_KINDS];
+
+export const SUPPORT_MEMORY_ROLES = {
+  user: "user",
+  /** 真人同事/管理员 */
+  admin: "admin",
+  agent: "agent",
+} as const;
+
+export type SupportMemoryRole = (typeof SUPPORT_MEMORY_ROLES)[keyof typeof SUPPORT_MEMORY_ROLES];
+
+/**
+ * 决策事件（agent_decision）的正文占位。
+ *
+ * 决策记的是「意图」——action/module/reason 全在 meta 与 summary 里；话术正文的唯一真相是
+ * 发送事实（agent_reply_sent / owner_escalation_sent，正文为 on_action 尾注合成后的最终文案）。
+ * 决策里再存一份合成前的正文前缀，会让同一个答案在记忆/复盘语料里出现两个版本（半成品 + 成品），
+ * 既浪费 token 又给学习沉淀留下歧义，因此只记占位。
+ */
+export const SUPPORT_DECISION_CONTENT = {
+  /** 决策要回复：正文见同一 workItem 的发送事实 */
+  reply: "(已决策回复)",
+  /** 决策不回复：静默口径的判定锚点（daily-review 旧数据回退仍依赖该字面量） */
+  silent: "(静默)",
+} as const;
+
+/**
+ * 问答关联键：把原始提问正文归一化成短期记忆事件之间的配对锚点。
+ *
+ * agent 侧事件（决策/发送事实/发送失败/失败兜底）都带 meta.question 回指提问，
+ * 复盘据此配对首次响应时长；没有它就只能按时序 FIFO 猜，一旦有问题被静默或回复乱序就错位。
+ */
+export function questionKey(content: string): string {
+  return content.replace(/\s+/g, " ").trim().slice(0, 120);
+}
+
+export function supportScope(conversationId?: string): MemoryScope {
+  return {
+    channel: SUPPORT_CHANNEL,
+    scenario: SUPPORT_SCENARIO,
+    ...(conversationId ? { conversationId } : {}),
+  };
+}
+
+export function supportEntry(args: {
+  kind: SupportMemoryKind;
+  content: string;
+  sender: string;
+  role: SupportMemoryRole;
+  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,
+    },
+  };
+}