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

package/templates/support-qa/lib/declarative-matcher.ts

@@ -0,0 +1,398 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+/**
+ * aitable-workflow — 声明式规则匹配引擎
+ *
+ * 把「命中哪条规则」从代码里的硬编码正则收敛为 YAML 声明。两个 preset 共用同一内核：
+ *
+ *   loadReplyRules      确定性秒回（命中即固定话术）：safety 关键词兜底 + rules[template|contains|regex]
+ *   loadClassifierRules 问题分类（命中即打标签并抽取证据）：classifiers[patterns, require_all, extract]
+ *
+ * 前者本质是后者的特例（无 require_all、无 extract、命中即回复），故合为一个模块。
+ *
+ * ─── 硬不变量（务必保留，都是踩过的坑）───
+ *
+ * 1. **单向匹配**：一律「消息包含/匹配规则模式」，绝不反向（规则模式包含消息）。
+ *    双向 includes 会让短消息错误命中长规则——这是早期 known-error-match
+ *    `errorMessage.includes(k) || k.includes(errorMessage)` 的实际 bug。
+ * 2. **只看用户本轮新话**：普通规则匹配前剥离钉钉「引用消息:」块。用户带引用追问时，
+ *    引用块里往往完整包含上一轮报错与机器人回复，不剥离就会复读同一段话术。
+ * 3. **safety 看全文**：安全兜底必须对含引用的原文匹配，防注入/敏感内容藏在引用块里绕过。
+ * 4. **优雅关闭**：未配置、文件缺失、解析失败 → config=null（调用方透传），不阻断主环。
+ *    单条规则非法只跳该条并记 issue，不整档失效。
+ * 5. **校验单一事实源**：合法性只由本文件的 normalize 逐条判定并产出 issues，
+ *    不再另外维护一份 zod schema（两套规则双写必然漂移）。
+ */
+
+// ─── 匹配条件 ────────────────────────────────────────────
+
+export type MatchPattern = {
+  contains?: string;
+  regex?: string;
+  /** 加载期预编译（与校验同一实例），避免逐消息重编 */
+  compiledRegex?: RegExp;
+};
+
+/** 钉钉「引用消息:」标记：其后内容是被引用的历史消息，不属于用户本轮诉求。
+ *  含半角/全角冒号两种变体（不同客户端文案不一致）。 */
+const QUOTE_MARKERS = ["引用消息:", "引用消息："];
+
+/**
+ * 剥离引用块，只保留用户本轮新话。
+ * 边界：剥离后为空（用户只转发引用、自己没打字）→ 返回原文。
+ */
+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;
+}
+
+/** 空白归一（template 全等匹配用） */
+function normalizeWs(s: string): string {
+  return s.replace(/\s+/g, " ").trim();
+}
+
+/** 单向测试：消息包含/匹配该 pattern */
+function testPattern(p: MatchPattern, message: string): boolean {
+  if (p.contains !== undefined) return message.includes(p.contains);
+  if (p.compiledRegex) return p.compiledRegex.test(message);
+  return false;
+}
+
+/** 归一化 patterns 列表：每条必须且只能有 contains/regex 之一 */
+function normalizePatterns(raw: unknown, label: string, issues: string[]): MatchPattern[] {
+  const out: MatchPattern[] = [];
+  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(`${label} 每条 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(`${label} 非法正则: ${rx}`);
+      }
+    }
+  }
+  return out;
+}
+
+/** 按绝对路径缓存加载结果（每种 preset 一张表，避免 key 冲突） */
+function makeLoader<T>(
+  subdir: string,
+  parse: (raw: Record<string, unknown>, issues: string[]) => T | null,
+  labels: { missing: string; parseFail: string },
+) {
+  const cache = new Map<string, { config: T | null; issues: string[] }>();
+  return (configDir: string, rel: string | undefined): { config: T | null; issues: string[] } => {
+    const trimmed = String(rel ?? "").trim();
+    if (!trimmed) return { config: null, issues: [] }; // 未配置 → 关闭
+    const abs = path.resolve(configDir, subdir, trimmed);
+    const hit = cache.get(abs);
+    if (hit) return hit;
+
+    let res: { config: T | null; issues: string[] };
+    if (!existsSync(abs)) {
+      // 文件缺失 → 优雅关闭（不阻断主环）；preflight 另行告警
+      res = { config: null, issues: [`${labels.missing}: ${subdir}/${trimmed}`] };
+    } else {
+      try {
+        const raw = (parseYaml(readFileSync(abs, "utf8")) ?? {}) as Record<string, unknown>;
+        const issues: string[] = [];
+        res = { config: parse(raw, issues), issues };
+      } catch (err) {
+        res = {
+          config: null,
+          issues: [`${labels.parseFail} ${subdir}/${trimmed}: ${err instanceof Error ? err.message : String(err)}`],
+        };
+      }
+    }
+    cache.set(abs, res);
+    return res;
+  };
+}
+
+// ─── preset 1：确定性秒回规则 ─────────────────────────────
+
+export type ReplyRule = {
+  /** 规则标识（报错/日志文案含此 key，便于排障与追溯） */
+  key: string;
+  template?: string;
+  contains?: string;
+  regex?: string;
+  compiledRegex?: RegExp;
+  reply: string;
+};
+
+export type SafetyRule = { keywords: string[]; reply: string };
+
+export type ReplyRulesConfig = {
+  safety?: SafetyRule;
+  rules: ReplyRule[];
+};
+
+export type ReplyMatch = {
+  key: string;
+  reply: string;
+  kind: "safety" | "template" | "contains" | "regex";
+};
+
+function parseReplyRules(raw: Record<string, unknown>, issues: string[]): ReplyRulesConfig {
+  const rules: ReplyRule[] = [];
+  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: ReplyRule = { 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: SafetyRule | 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 };
+}
+
+/** 加载秒回规则（相对 `<configDir>/profile/` 解析），按绝对路径缓存 */
+export const loadReplyRules = makeLoader<ReplyRulesConfig>(
+  "profile",
+  parseReplyRules,
+  { missing: "规则文件不存在", parseFail: "规则解析失败" },
+);
+
+/**
+ * 匹配秒回规则（单向）：安全兜底优先，其次规则按声明顺序。
+ *
+ * safety 看全文（敏感内容/注入藏在引用块里也要拦）；普通规则只看剥离引用后的用户新话。
+ */
+export function matchReplyRules(config: ReplyRulesConfig | null, message: string): ReplyMatch | 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;
+}
+
+// ─── preset 2：问题分类器 ─────────────────────────────────
+
+export type ClassifierRule = {
+  issueType: string;
+  /** 可选：命中时透传的路由模块名 */
+  module?: string;
+  reason: string;
+  patterns: MatchPattern[];
+  /** 默认 false（任一命中）；true 时需全部命中 */
+  requireAll: boolean;
+  /** 字段名 → 正则（取第一个捕获组）；未命中该字段填 null */
+  extract: Record<string, string>;
+};
+
+export type ClassifierRulesConfig = { classifiers: ClassifierRule[] };
+
+export type ClassifyMatch = {
+  issueType: string;
+  module?: string;
+  reason: string;
+  extracted: Record<string, string | null>;
+};
+
+function parseClassifierRules(raw: Record<string, unknown>, issues: string[]): ClassifierRulesConfig | null {
+  const out: ClassifierRule[] = [];
+  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, `classifiers[${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.length > 0 ? { classifiers: out } : null;
+}
+
+/** 加载分类器（相对 `<configDir>/profile/` 解析），按绝对路径缓存 */
+export const loadClassifierRules = makeLoader<ClassifierRulesConfig>(
+  "profile",
+  parseClassifierRules,
+  { missing: "分类器文件不存在", parseFail: "分类器解析失败" },
+);
+
+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。
+ */
+export function classifyMessage(config: ClassifierRulesConfig | null, message: string): ClassifyMatch | 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;
+}
+
+// ─── 整档 / 按群开关 ─────────────────────────────────────
+
+/**
+ * 某个可选能力是否整档启用：所需目录（如 skills_dir）已配置且存在。
+ * 未配置或目录缺失 → 关闭。路径相对实例根解析。
+ */
+export function isCapabilityEnabled(configDir: string, dirRel: string | undefined): boolean {
+  const rel = String(dirRel ?? "").trim();
+  if (!rel) return false;
+  return existsSync(path.resolve(configDir, rel));
+}
+
+type GroupToggleRow = Record<string, 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());
+}
+
+/**
+ * 按群开关：仅当群配置快照里该群的开关字段**明确为真**才启用。
+ * 群缺失、字段缺失、未知值一律关闭（宁可不做，不可乱做）。
+ */
+export function isGroupToggleEnabled(
+  raw: unknown,
+  conversationId: string,
+  field: string,
+  idField = "groupId",
+): boolean {
+  if (!conversationId || !Array.isArray(raw)) return false;
+  const group = (raw as GroupToggleRow[]).find(
+    (g) => String(g?.[idField] ?? "").trim() === conversationId,
+  );
+  return explicitTrue(group?.[field]);
+}

package/templates/support-qa/lib/dingtalk-group-membership.ts

@@ -0,0 +1,151 @@
+import { DwsClient, logger } from "aitable-workflow-core";
+
+/**
+ * aitable-workflow — 钉钉群成员在群判定（能不能真实 @ 到这个人）
+ *
+ * 用途：升级找人时要在群里 @ 负责人，但负责人未必在该群。@ 一个不在群的人钉钉不会
+ * 真正提醒到他，还会在消息里留下无意义的数字工号。故发送前先判定：
+ *   - 在群   → { mode: "at", userId }，由发送层配合 mentionUserIds 真实 @；
+ *   - 判不了 → { mode: "name" }，调用方只渲染花名，绝不写假 @、绝不出数字 uid。
+ *
+ * 硬不变量：**任何失败都降级为 `{ mode: "name" }`，绝不向主流程抛错。**
+ * 参数缺失、命令失败、超时、响应解析失败、人不在群——一律 name。找人是加分项，
+ * 不能因为它挂掉而让整条答疑链路失败。
+ *
+ * 命令统一走 DwsClient（而非自建 spawn）：拿到退避重试（消化 dws 后端偶发 TIMEOUT /
+ * 伪 AUTH_PERMISSION_DENIED）与连续失败升级告警。降级时打一条 debug/warn，不再无声失败。
+ *
+ * 结果按 (conversationId, userId, openDingTalkId) 缓存：TTL 10 分钟、上限 500 条、
+ * Map 插入顺序作轻量 LRU。群成员变动不频繁，缓存显著削减 dws 调用。
+ */
+
+export type GroupMention =
+  | { mode: "at"; userId: string }
+  | { mode: "name" };
+
+/** 待判定的联系人：userId 用于真实 @，openDingTalkId 用于群成员查询 */
+export type MentionCandidate = {
+  userId: string;
+  openDingTalkId?: string;
+};
+
+export type GroupMembershipDeps = {
+  /** 注入 dws 执行器（测试用）；缺省新建 DwsClient */
+  dws?: Pick<DwsClient, "runJson">;
+  /** dws 可执行文件名（对齐 settings.tracker.dws_bin），缺省 "dws" */
+  dwsBin?: string;
+  /** 注入时钟（测试用） */
+  now?: () => number;
+};
+
+type CacheEntry = { value: GroupMention; expiresAt: number };
+
+const DWS_TIMEOUT_MS = 8_000;
+const CACHE_TTL_MS = 10 * 60_000;
+const CACHE_MAX = 500;
+
+const memberCache = new Map<string, CacheEntry>();
+
+function getCached(key: string, now: number): GroupMention | undefined {
+  const hit = memberCache.get(key);
+  if (!hit) return undefined;
+  if (hit.expiresAt <= now) {
+    memberCache.delete(key);
+    return undefined;
+  }
+  // Map 插入顺序作为轻量 LRU；命中后移到队尾
+  memberCache.delete(key);
+  memberCache.set(key, hit);
+  return hit.value;
+}
+
+function setCached(key: string, value: GroupMention, expiresAt: number): void {
+  memberCache.delete(key);
+  memberCache.set(key, { value, expiresAt });
+  while (memberCache.size > CACHE_MAX) {
+    const oldest = memberCache.keys().next().value as string | undefined;
+    if (oldest === undefined) break;
+    memberCache.delete(oldest);
+  }
+}
+
+/** 从 dws 响应里取 result.members 数组；结构不符一律视为空 */
+function memberList(payload: unknown): Array<Record<string, unknown>> {
+  if (!payload || typeof payload !== "object") return [];
+  const result = (payload as Record<string, unknown>).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),
+      )
+    : [];
+}
+
+/** 兼容两种大小写拼写（不同 dws 版本返回不一致） */
+function readOpenDingTalkId(item: Record<string, unknown>): string {
+  const value = item.openDingTalkId ?? item.openDingtalkId;
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * 判定某联系人能否在目标群被真实 @。
+ *
+ * userId / openDingTalkId 由调用方从自己的联系人快照传入（本函数不做联系人解析），
+ * 这里只做「在不在这个群」的校验。
+ */
+export async function resolveGroupMention(
+  conversationId: string,
+  candidate: MentionCandidate,
+  deps: GroupMembershipDeps = {},
+): Promise<GroupMention> {
+  const cid = String(conversationId ?? "").trim();
+  const userId = String(candidate?.userId ?? "").trim();
+  const openDingTalkId = String(candidate?.openDingTalkId ?? "").trim();
+  const fallback: GroupMention = { mode: "name" };
+
+  if (!cid || !userId || !openDingTalkId) {
+    logger.debug("group-membership", "参数不足，降级为花名", {
+      hasCid: Boolean(cid), hasUserId: Boolean(userId), hasOpenId: Boolean(openDingTalkId),
+    });
+    return fallback;
+  }
+
+  const now = (deps.now ?? Date.now)();
+  const cacheKey = `${cid}\u0000${userId}\u0000${openDingTalkId}`;
+  const cached = getCached(cacheKey, now);
+  if (cached !== undefined) return cached;
+
+  const dws = deps.dws ?? new DwsClient({ bin: deps.dwsBin ?? "dws", timeoutMs: DWS_TIMEOUT_MS });
+
+  let result: GroupMention = fallback;
+  try {
+    // DwsClient.runJson 自动追加 --format json，这里不再手写
+    const payload = await dws.runJson(
+      ["chat", "group", "members", "list-by-ids", "--id", cid, "--users", openDingTalkId],
+      { timeoutMs: DWS_TIMEOUT_MS },
+    );
+    const matched = memberList(payload).some((m) => readOpenDingTalkId(m) === openDingTalkId);
+    if (matched) {
+      result = { mode: "at", userId };
+    } else {
+      logger.debug("group-membership", "联系人不在该群，降级为花名", { conversationId: cid });
+    }
+  } catch (error) {
+    // 找人是加分项：查询失败不影响主流程，但要留痕（此前是完全静默）
+    logger.warn("group-membership", "群成员查询失败，降级为花名", {
+      conversationId: cid,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    result = fallback;
+  }
+
+  setCached(cacheKey, result, now + CACHE_TTL_MS);
+  return result;
+}
+
+/** 仅供单测隔离模块级缓存 */
+export function resetGroupMembershipCache(): void {
+  memberCache.clear();
+}

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

@@ -0,0 +1,18 @@
+import { createFingerprintWindow } from "aitable-workflow-core";
+
+/**
+ * support-qa 出站回声防护（echo guard）
+ *
+ * 背景：webhook 发出的机器人回复可能被 dws 轮询以"某个真人"的名义重新拉回
+ * （真实案例：机器人答案以创建者名义回流，身份匹配失效，被当新消息判定建行）。
+ * 方案：reply 发送成功后发布内容指纹；conversation_handler 同步比对，
+ * 命中即按机器人消息处理（只记历史，不建单）。
+ */
+
+/** 出站内容指纹窗口：单 part = 回复正文（截断 300） */
+export const echoWindow = createFingerprintWindow({
+  key: "sent_reply_fingerprints",
+  ttlMs: 10 * 60 * 1000,
+  capacity: 50,
+  maxPartLength: 300,
+});

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

@@ -1,12 +1,64 @@
 import type { MemoryEntry, MemoryScope } from "aitable-workflow-core";
 
 /**
- * support-qa 记忆事件词表（场景层单一事实源）
+ * support-qa 记忆事件词表 + 工厂（场景层单一事实源）
  *
  * 写入方：conversation_handler(user/admin 消息)、answer(agent 决策)、reply(发送结果)。
  * 读取方：answer(长期记忆注入)、daily-review(复盘/学习提炼)。
  */
 
+// ─── 记忆事件工厂（从 core 下沉）────────────────────────────
+
+type MemoryEventsOptions = {
+  scenario: string;
+  channel: string;
+  questionKeyLength?: number;
+  summaryContentLength?: number;
+};
+
+type MemoryEntryArgs<Kind extends string = string, Role extends string = string> = {
+  kind: Kind;
+  content: string;
+  sender: string;
+  role: Role;
+  conversationId: string;
+  timestamp?: string;
+  summary?: string;
+  meta?: Record<string, unknown>;
+};
+
+type MemoryEvents<Kind extends string = string, Role extends string = string> = {
+  scope: (conversationId?: string) => MemoryScope;
+  entry: (args: MemoryEntryArgs<Kind, Role>) => MemoryEntry;
+  questionKey: (content: string) => string;
+};
+
+function createMemoryEvents<Kind extends string = string, Role extends string = string>(
+  options: MemoryEventsOptions,
+): MemoryEvents<Kind, Role> {
+  const { scenario, channel } = options;
+  const questionKeyLength = options.questionKeyLength ?? 120;
+  const summaryContentLength = options.summaryContentLength ?? 80;
+
+  return {
+    scope(conversationId?: string): MemoryScope {
+      return { channel, scenario, ...(conversationId ? { conversationId } : {}) };
+    },
+    entry(args: MemoryEntryArgs<Kind, Role>): MemoryEntry {
+      return {
+        timestamp: args.timestamp ?? new Date().toISOString(),
+        kind: args.kind,
+        content: args.content,
+        summary: args.summary ?? `${args.sender}: ${args.content.slice(0, summaryContentLength)}`,
+        meta: { sender: args.sender, role: args.role, conversationId: args.conversationId, ...args.meta },
+      };
+    },
+    questionKey(content: string): string {
+      return content.replace(/\s+/g, " ").trim().slice(0, questionKeyLength);
+    },
+  };
+}
+
 export const SUPPORT_SCENARIO = "support-qa";
 export const SUPPORT_CHANNEL = "dingtalk";
 
@@ -51,44 +103,11 @@ export const SUPPORT_DECISION_CONTENT = {
   silent: "(静默)",
 } as const;
 
-/**
- * 问答关联键：把原始提问正文归一化成短期记忆事件之间的配对锚点。
- *
- * agent 侧事件（决策/发送事实/发送失败/失败兜底）都带 meta.question 回指提问，
- * 复盘据此配对首次响应时长；没有它就只能按时序 FIFO 猜，一旦有问题被静默或回复乱序就错位。
- */
-export function questionKey(content: string): string {
-  return content.replace(/\s+/g, " ").trim().slice(0, 120);
-}
+const events = createMemoryEvents<SupportMemoryKind, SupportMemoryRole>({
+  scenario: SUPPORT_SCENARIO,
+  channel: SUPPORT_CHANNEL,
+});
 
-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,
-    },
-  };
-}
+export const supportScope = events.scope;
+export const supportEntry = events.entry;
+export const questionKey = events.questionKey;