aitable-workflow-cli 0.1.13-beta.1

package/templates/aitable-handoff/workflows/config-sync/recipes/config_sync.recipe.ts

@@ -0,0 +1,448 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { normalizeByType, tableRefConfigSchema, globalVarRefPath, type RecipeDefinition, type RecipeContext, type RecipeResult } from "aitable-workflow-core";
+
+const execFileAsync = promisify(execFile);
+
+/** 从配置取 globalVar key：接受 "${globalVar.x}" 引用（解析出 x）或裸 key；空则回退默认。 */
+function varKey(raw: unknown, fallback: string): string {
+  const s = String(raw ?? "").trim();
+  return globalVarRefPath(s) ?? (s || fallback);
+}
+
+type Cells = Record<string, unknown>;
+type Rec = { recordId: string; cells: Cells };
+export type GroupConfig = {
+  groupId: string;
+  groupName?: string;
+  inbound?: string;
+  outbound?: string;
+  credRef?: string;
+  botNick?: string;
+  troubleshootingEnabled: boolean;
+};
+export type AdminConfig = { userId: string; nick: string; openDingTalkId: string };
+type FetchResult<T> = { ok: true; data: T } | { ok: false; error: string };
+
+// 管理员 contact 解析的并发上限：避免 N 较大时同时拉起过多 dws 子进程。
+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;
+  return { records: extractRecords(parsed) };
+}
+
+/** dws record query/list 返回 `{ data: { records: [...] } }`，需 unwrap */
+function extractRecords(raw: unknown): Rec[] {
+  if (!raw || typeof raw !== "object") return [];
+  const rec = raw as Record<string, unknown>;
+  const payload = (rec.data ?? rec) as Record<string, unknown> | undefined;
+  if (!payload || typeof payload !== "object") return [];
+  const records = payload.records;
+  return Array.isArray(records) ? (records as 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());
+}
+
+/** 有界并发地映射：最多 limit 个任务同时进行，返回与输入等长的结果数组。 */
+async function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      results[index] = await fn(items[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+function cellText(v: unknown, fieldType?: string): string {
+  const normalized = normalizeByType(v, fieldType);
+  if (typeof normalized === "string") return normalized.trim();
+  if (typeof normalized === "number") return String(normalized);
+  return "";
+}
+
+/** 群配置开关：仅明确的真值开启；缺失、空值或未知格式一律关闭。 */
+export function cellBoolean(v: unknown): boolean {
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v === 1;
+  if (typeof v === "string") {
+    return ["true", "1", "yes", "on", "是", "开启", "启用", "已勾选"].includes(v.trim().toLowerCase());
+  }
+  if (Array.isArray(v)) return v.some(cellBoolean);
+  const record = asRecord(v);
+  if (!record) return false;
+  if ("value" in record) return cellBoolean(record.value);
+  if ("name" in record) return cellBoolean(record.name);
+  return false;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+/** 将快照标准化，避免 DWS 返回顺序或 JSON 格式变化造成伪更新。 */
+export function normalizeGroupConfigs(raw: unknown): GroupConfig[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value): GroupConfig[] => {
+    const record = asRecord(value);
+    const groupId = cellText(record?.groupId);
+    if (!groupId) return [];
+    const groupName = cellText(record?.groupName);
+    const inbound = cellText(record?.inbound);
+    const outbound = cellText(record?.outbound);
+    const credRef = cellText(record?.credRef);
+    const botNick = cellText(record?.botNick);
+    const troubleshootingEnabled = cellBoolean(record?.troubleshootingEnabled);
+
+    const normalized: GroupConfig = { groupId, troubleshootingEnabled };
+    if (groupName) normalized.groupName = groupName;
+    if (inbound) normalized.inbound = inbound;
+    if (outbound) normalized.outbound = outbound;
+    if (credRef) normalized.credRef = credRef;
+    if (botNick) normalized.botNick = botNick;
+    return [normalized];
+  }).sort((left, right) => (
+    left.groupId.localeCompare(right.groupId)
+    || JSON.stringify(left).localeCompare(JSON.stringify(right))
+  ));
+}
+
+export function normalizeAdminConfigs(raw: unknown): AdminConfig[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value): AdminConfig[] => {
+    const record = asRecord(value);
+    const userId = cellText(record?.userId);
+    const nick = cellText(record?.nick);
+    const openDingTalkId = cellText(record?.openDingTalkId);
+    return userId && nick && openDingTalkId ? [{ userId, nick, openDingTalkId }] : [];
+  }).sort((left, right) => (
+    left.userId.localeCompare(right.userId)
+    || JSON.stringify(left).localeCompare(JSON.stringify(right))
+  ));
+}
+
+/** 空快照门禁的计数游标（按目标 globalVar 派生，避免多份快照互相干扰）。 */
+export function emptyStreakKey(key: string): string {
+  return `${key}__empty_streak`;
+}
+
+/**
+ * 空快照发布门禁：远端读到空且旧值非空时，不立刻清空，先累计"连续读到空"轮数，
+ * 达到 rounds 轮才认定为真实清空。防的是"读成功但结果为空"这类抖动（表查询瞬时
+ * 返回 0 条、字段解析不到 userId 等）被当成"远端已清空"，把管理员/群名单误清 ——
+ * 管理员被清会让真人同事消息退化成普通用户提问；pull 名单被清会让机器人整群失聪。
+ * 旧值本来就是空，或本轮非空时，直接放行并复位计数。
+ */
+export function gateEmptySnapshot(
+  ctx: RecipeContext,
+  key: string,
+  nextCount: number,
+  rounds: number,
+): { allow: boolean; streak: number; rounds: number } {
+  const required = Math.max(1, Math.trunc(rounds) || 1);
+  const streakKey = emptyStreakKey(key);
+  const rawStreak = Math.trunc(Number(ctx.getGlobalVar(streakKey) ?? 0));
+  const prevStreak = Number.isFinite(rawStreak) && rawStreak > 0 ? rawStreak : 0;
+  const currentValue = ctx.getGlobalVar(key);
+  const currentCount = Array.isArray(currentValue) ? currentValue.length : 0;
+
+  if (nextCount > 0 || currentCount === 0) {
+    if (prevStreak !== 0) ctx.setGlobalVar(streakKey, 0);
+    return { allow: true, streak: 0, rounds: required };
+  }
+
+  const streak = prevStreak + 1;
+  ctx.setGlobalVar(streakKey, streak >= required ? 0 : streak);
+  return { allow: streak >= required, streak, rounds: required };
+}
+
+/** 快照计数留痕文案：暂缓清空时显式带上门禁轮次，便于 trace 上直接看出"被拦下"而非"真为 0"。 */
+function snapshotCountLabel(result: FetchResult<unknown[]>, gate?: { allow: boolean; streak: number; rounds: number }): string {
+  if (!result.ok) return "读取失败";
+  if (gate && !gate.allow) return `0(暂缓清空 ${gate.streak}/${gate.rounds})`;
+  return String(result.data.length);
+}
+
+/** 内容变化时发布到 globalVar；返回是否实际更新（用于留痕判定）。 */
+export function publishIfChanged<T>(
+  ctx: RecipeContext,
+  key: string,
+  nextRaw: unknown,
+  normalize: (raw: unknown) => T[],
+): boolean {
+  const next = normalize(nextRaw);
+  const current = normalize(ctx.getGlobalVar(key) ?? []);
+  if (JSON.stringify(current) === JSON.stringify(next)) return false;
+  ctx.setGlobalVar(key, next);
+  return true;
+}
+
+
+
+/** 从 dws field get 结果中提取字段名→字段ID 映射（兼容数组或 { data: { fields: [...] } } 嵌套） */
+interface FieldMeta { fieldId: string; type: string; }
+function extractFieldMap(raw: unknown): Map<string, FieldMeta> {
+  let arr: unknown[] = [];
+  if (Array.isArray(raw)) arr = raw;
+  else if (raw && typeof raw === "object") {
+    const rec = raw as Record<string, unknown>;
+    if (Array.isArray(rec.fields)) arr = rec.fields;
+    else if (Array.isArray(rec.result)) arr = rec.result;
+    else if (rec.data && typeof rec.data === "object") {
+      const data = rec.data as Record<string, unknown>;
+      if (Array.isArray(data.fields)) arr = data.fields;
+      else if (Array.isArray(data.result)) arr = data.result;
+    }
+  }
+  const map = new Map<string, FieldMeta>();
+  for (const field of arr) {
+    if (!field || typeof field !== "object") continue;
+    const rec = field as Record<string, unknown>;
+    const id = typeof rec.fieldId === "string" ? rec.fieldId : typeof rec.id === "string" ? rec.id : null;
+    const name = typeof rec.fieldName === "string" ? rec.fieldName : typeof rec.name === "string" ? rec.name : null;
+    const type = typeof rec.type === "string" ? rec.type : "text";
+    if (id && name) map.set(name, { fieldId: id, type });
+  }
+  return map;
+}
+
+async function fetchFieldMap(baseId: string, tableId: string): Promise<Map<string, FieldMeta>> {
+  const raw = await dwsRaw(["aitable", "field", "get", "--base-id", baseId, "--table-id", tableId, "--format", "json"]);
+  return extractFieldMap(raw);
+}
+
+/** 从 fieldMap 解析字段 ID（查不到则回退原值） */
+function resolveFieldKey(nameOrId: string, fieldMap: Map<string, FieldMeta>): string {
+  return fieldMap.get(nameOrId)?.fieldId ?? nameOrId;
+}
+/** 从 fieldMap 获取字段类型（查不到则 undefined，走 normalizeByType 默认） */
+function fieldType(nameOrId: string, fieldMap: Map<string, FieldMeta>): string | undefined {
+  return fieldMap.get(nameOrId)?.type;
+}
+
+const recipe: RecipeDefinition = {
+  meta: {
+    id: "config_sync",
+    name: "拉取并固化群/管理员配置",
+    role: "config-syncer",
+    description: "dws 拉群配置表 + 管理员表 + contact 解析 → 发布到 globalVar(group_configs/group_pull_list/admins)",
+    version: "1.0.0",
+    requiresAgent: false,
+    timeoutMs: 120_000,
+    config: z.object({
+      group_table: tableRefConfigSchema({
+        label: "群配置表",
+        description: "群配置表（读取群ID、群名称、入站方式、出站方式、凭据引用、机器人昵称、是否排查问题）",
+        access: "read",
+        ownership: "owned",
+        autoCreate: true,
+        defaultBase: "workflow.tracker.base_id",
+        setupSchema: {
+          fields: [
+            { name: "群ID", type: "text" },
+            { name: "群名称", type: "text" },
+            // 入站/出站双轴正交:
+            // 入站方式=dws(个人号轮询,进 pull 名单)/stream(企业机器人 WebSocket,@机器人触发);
+            // 出站方式=session(会话内 @提问者,依赖 stream 登记的 sessionWebhook)/webhook(命名 webhook 降级)。
+            // 用单选杜绝手填写错;具体用哪套 webhook 凭证由「凭据引用」在 messaging.robots/webhooks 命名空间内指定。
+            // 象限约束:出站=session 依赖入站=stream(sessionWebhook 只由 stream 登记);dws+session 物理不可能,运行期降级 webhook。
+            { name: "入站方式", type: "singleSelect", options: ["dws", "stream"] },
+            { name: "出站方式", type: "singleSelect", options: ["session", "webhook"] },
+            { name: "凭据引用", type: "text" },
+            { name: "机器人昵称", type: "text" },
+            { name: "是否排查问题", type: "checkbox" },
+          ],
+        },
+      }),
+      admin_table: tableRefConfigSchema({
+        label: "管理员配置表",
+        description: "管理员配置表（读取管理员名单）",
+        access: "read",
+        ownership: "owned",
+        autoCreate: true,
+        defaultBase: "workflow.tracker.base_id",
+        setupSchema: {
+          fields: [
+            { name: "管理员", type: "user" },
+          ],
+        },
+      }),
+      group_var: z.string().default("${globalVar.group_configs}").describe("发布群配置的目标 globalVar"),
+      pull_list_var: z.string().default("${globalVar.group_pull_list}").describe("发布 dws 轮询群列表的目标 globalVar"),
+      stream_var: z.string().default("${globalVar.stream_robot_refs}").describe("发布 stream 入站机器人 credRef 名单的目标 globalVar"),
+      admin_var: z.string().default("${globalVar.admins}").describe("发布管理员名单的目标 globalVar"),
+      empty_confirm_rounds: z.coerce.number().int().min(1).default(2)
+        .describe("空快照发布门禁轮数：远端读到空且旧值非空时，需连续读到空达到该轮数才真正清空；未达轮数保留旧值并留痕（防读空抖动误清群/管理员名单）。设 1 即恢复旧的即时清空行为"),
+    }),
+  },
+
+  async execute(ctx: RecipeContext): Promise<RecipeResult> {
+    const { config, log } = ctx;
+    const gt = config.group_table as { baseId: string; tableId: string };
+    const at = config.admin_table as { baseId: string; tableId: string };
+    const groupVar = varKey(config.group_var, "group_configs");
+    const pullListVar = varKey(config.pull_list_var, "group_pull_list");
+    const streamVar = varKey(config.stream_var, "stream_robot_refs");
+    const adminVar = varKey(config.admin_var, "admins");
+    const emptyConfirmRounds = Math.max(1, Math.trunc(Number(config.empty_confirm_rounds ?? 2)) || 1);
+
+    // 表自建后字段名固定，通过 field get 解析为字段ID再读取 cells
+    const GROUP_FIELDS = {
+      groupId: "群ID",
+      groupName: "群名称",
+      inbound: "入站方式",
+      outbound: "出站方式",
+      credRef: "凭据引用",
+      botNick: "机器人昵称",
+      troubleshootingEnabled: "是否排查问题",
+    };
+    const ADMIN_FIELDS = { user: "管理员" };
+
+    // 1) 群配置
+    let groupResult: FetchResult<GroupConfig[]>;
+    try {
+      const groupFieldMap = await fetchFieldMap(gt.baseId, gt.tableId);
+      const groupIdKey = resolveFieldKey(GROUP_FIELDS.groupId, groupFieldMap);
+      const groupNameKey = resolveFieldKey(GROUP_FIELDS.groupName, groupFieldMap);
+      const inboundKey = resolveFieldKey(GROUP_FIELDS.inbound, groupFieldMap);
+      const outboundKey = resolveFieldKey(GROUP_FIELDS.outbound, groupFieldMap);
+      const credRefKey = resolveFieldKey(GROUP_FIELDS.credRef, groupFieldMap);
+      const botNickKey = resolveFieldKey(GROUP_FIELDS.botNick, groupFieldMap);
+      const troubleshootingEnabledKey = resolveFieldKey(GROUP_FIELDS.troubleshootingEnabled, groupFieldMap);
+      const inboundType = fieldType(GROUP_FIELDS.inbound, groupFieldMap);
+      const outboundType = fieldType(GROUP_FIELDS.outbound, groupFieldMap);
+      const { records } = await dwsJson(["aitable", "record", "query", "--base-id", gt.baseId, "--table-id", gt.tableId, "--all", "--format", "json"]);
+      const groups = normalizeGroupConfigs(records.map((r) => ({
+        groupId: cellText(r.cells[groupIdKey], fieldType(GROUP_FIELDS.groupId, groupFieldMap)),
+        groupName: cellText(r.cells[groupNameKey], fieldType(GROUP_FIELDS.groupName, groupFieldMap)) || undefined,
+        inbound: cellText(r.cells[inboundKey], inboundType) || undefined,
+        outbound: cellText(r.cells[outboundKey], outboundType) || undefined,
+        credRef: cellText(r.cells[credRefKey], fieldType(GROUP_FIELDS.credRef, groupFieldMap)) || undefined,
+        botNick: cellText(r.cells[botNickKey], fieldType(GROUP_FIELDS.botNick, groupFieldMap)) || undefined,
+        troubleshootingEnabled: cellBoolean(r.cells[troubleshootingEnabledKey]),
+      })));
+      groupResult = { ok: true, data: groups };
+    } catch (e) {
+      const error = e instanceof Error ? e.message : String(e);
+      log(`群配置拉取失败,保留旧值: ${error}`);
+      groupResult = { ok: false, error };
+    }
+
+    // 2) 管理员 userId → nick/openId(contact 链式)。每个 userId 内部 get→search 需串行,
+    //    但不同 userId 之间用有界并发处理,避免 N 较大时串行阻塞过久。
+    let adminResult: FetchResult<AdminConfig[]>;
+    try {
+      const adminFieldMap = await fetchFieldMap(at.baseId, at.tableId);
+      const userKey = resolveFieldKey(ADMIN_FIELDS.user, adminFieldMap);
+      const { records } = await dwsJson(["aitable", "record", "list", "--base-id", at.baseId, "--table-id", at.tableId, "--all", "--format", "json"]);
+      const userIds = [...new Set(records.flatMap((r) => Array.isArray(r.cells[userKey]) ? (r.cells[userKey] as { userId?: string }[]).map((u) => u?.userId ?? "").filter(Boolean) : []))];
+      const resolutionErrors: string[] = [];
+      const resolved = await mapWithConcurrency(userIds, CONTACT_CONCURRENCY, async (uid) => {
+        try {
+          const got = await dwsRaw(["contact", "user", "get", "--ids", uid, "--format", "json"]) as { result?: { orgEmployeeModel?: { orgUserName?: string } }[] };
+          const name = got?.result?.[0]?.orgEmployeeModel?.orgUserName;
+          if (!name) throw new Error("未查询到组织内姓名");
+          const searched = await dwsRaw(["contact", "user", "search", "--query", name, "--format", "json"]) as { result?: { userId?: string; nick?: string; openDingTalkId?: string }[] };
+          const match = (searched?.result ?? []).find((u) => u.userId === uid);
+          if (match?.openDingTalkId && match?.nick) return { userId: uid, nick: match.nick, openDingTalkId: match.openDingTalkId };
+          throw new Error("未查询到匹配的 openDingTalkId/nick");
+        } catch (e) {
+          const error = `${uid}: ${e instanceof Error ? e.message : String(e)}`;
+          resolutionErrors.push(error);
+          log(`contact 解析失败 ${error}`);
+          return null;
+        }
+      });
+      if (resolutionErrors.length > 0) {
+        throw new Error(`${resolutionErrors.length} 名管理员解析失败: ${resolutionErrors.sort().join("; ")}`);
+      }
+      const admins = normalizeAdminConfigs(resolved.filter((a): a is AdminConfig => a !== null));
+      adminResult = { ok: true, data: admins };
+    } catch (e) {
+      const error = e instanceof Error ? e.message : String(e);
+      log(`管理员拉取失败,保留旧值: ${error}`);
+      adminResult = { ok: false, error };
+    }
+
+    // 3) 仅发布变化的成功快照到 globalVar。失败保留旧值；"成功但为空"需经 empty_confirm_rounds
+    //    门禁连续确认后才真正清空（单次读空视为抖动，保留旧值并留痕）。
+    const changed: string[] = [];
+    const failures: string[] = [];
+    const withheld: string[] = [];
+    let groupGate: { allow: boolean; streak: number; rounds: number } | undefined;
+    let adminGate: { allow: boolean; streak: number; rounds: number } | undefined;
+    if (groupResult.ok) {
+      groupGate = gateEmptySnapshot(ctx, groupVar, groupResult.data.length, emptyConfirmRounds);
+      if (!groupGate.allow) {
+        // 群配置是 pull/stream 名单的唯一来源，暂缓时三份派生快照必须一起不动，
+        // 否则会出现"群配置保旧、pull 名单被清空"的半清空态（机器人静默失聪）。
+        withheld.push(`群配置(读到空 ${groupGate.streak}/${groupGate.rounds} 轮，暂缓清空)`);
+        log(`群配置读到空但旧值非空，暂缓清空(第 ${groupGate.streak}/${groupGate.rounds} 轮)：群配置/pull 名单/stream 名单一并保留旧值`);
+      } else {
+        // 象限校验:出站=session 依赖入站=stream(sessionWebhook 只由 stream 登记),dws+session 物理不可能,告警(运行期降级 webhook)。
+        for (const g of groupResult.data) {
+          if (g.outbound === "session" && g.inbound !== "stream") {
+            log(`群配置象限告警 ${g.groupName ?? g.groupId}: 出站=session 依赖入站=stream,当前入站=${g.inbound ?? "空"},运行期将降级 webhook`);
+          }
+        }
+        if (publishIfChanged(ctx, groupVar, groupResult.data, normalizeGroupConfigs)) changed.push("群配置");
+        // 派生 pull 名单:只把入站=dws 的群写入(dws 轮询源监听),入站=stream 群走机器人 WebSocket 不入名单。
+        const pullIds = groupResult.data.filter((g) => g.inbound === "dws").map((g) => g.groupId);
+        if (publishIfChanged(ctx, pullListVar, pullIds, (v) => Array.isArray(v) ? v as string[] : [])) changed.push("pull 名单");
+        // 派生 stream 机器人名单:只把入站=stream 且有 credRef 的群的 credRef 去重写入(stream 源据此维护连接池)。
+        const streamRefs = [...new Set(
+          groupResult.data.filter((g) => g.inbound === "stream" && g.credRef).map((g) => g.credRef!),
+        )];
+        if (publishIfChanged(ctx, streamVar, streamRefs, (v) => Array.isArray(v) ? v as string[] : [])) changed.push("stream 名单");
+      }
+    } else {
+      failures.push(`群配置: ${groupResult.error}`);
+    }
+    if (adminResult.ok) {
+      adminGate = gateEmptySnapshot(ctx, adminVar, adminResult.data.length, emptyConfirmRounds);
+      if (!adminGate.allow) {
+        withheld.push(`管理员配置(读到空 ${adminGate.streak}/${adminGate.rounds} 轮，暂缓清空)`);
+        log(`管理员名单读到空但旧值非空，暂缓清空(第 ${adminGate.streak}/${adminGate.rounds} 轮)：保留旧名单，避免真人同事发言被误判为用户提问`);
+      } else if (publishIfChanged(ctx, adminVar, adminResult.data, normalizeAdminConfigs)) {
+        changed.push("管理员配置");
+      }
+    } else {
+      failures.push(`管理员配置: ${adminResult.error}`);
+    }
+
+    const shouldTrack = changed.length > 0 || failures.length > 0 || withheld.length > 0;
+    const syncResult = [
+      changed.length > 0 ? `已更新 ${changed.join("、")}` : "",
+      withheld.length > 0 ? `暂缓清空: ${withheld.join("；")}` : "",
+      failures.length > 0 ? `同步异常: ${failures.join("；")}` : "",
+    ].filter(Boolean).join("；") || "无变化";
+    const groupCount = snapshotCountLabel(groupResult, groupGate);
+    const adminCount = snapshotCountLabel(adminResult, adminGate);
+    log(`配置同步完成:${syncResult};群 ${groupCount}、管理员 ${adminCount}${shouldTrack ? "" : "(不留痕)"}`);
+    return {
+      status: "success",
+      output: { sync_result: syncResult, group_count: groupCount, admin_count: adminCount },
+      // 两份成功快照均无变化 → on_demand 模式下不建行；失败/暂缓清空仍留痕，便于发现同步异常。
+      ...(shouldTrack ? {} : { tracker: false }),
+      logs: [
+        `群 ${groupCount}`,
+        `管理员 ${adminCount}`,
+        ...(changed.length > 0 ? [`变更: ${changed.join("、")}`] : []),
+        ...withheld.map((item) => `暂缓: ${item}`),
+        ...failures.map((failure) => `失败: ${failure}`),
+      ],
+    };
+  },
+};
+export default recipe;

package/templates/aitable-handoff/workflows/config-sync/recipes/config_sync_handler.recipe.ts

@@ -0,0 +1,16 @@
+import type { EventHandlerRecipeDefinition, HandlerInitContext, HandlerInstance } from "aitable-workflow-core";
+
+const recipe: EventHandlerRecipeDefinition = {
+  meta: { id: "config_sync_handler", name: "配置同步触发器", description: "cron tick → 建一条配置同步工单" },
+  create(ctx: HandlerInitContext): HandlerInstance {
+    return {
+      onEvent(event) {
+        const firedAt = String(event.payload?.firedAt ?? new Date().toISOString());
+        ctx.log(`配置同步触发 @ ${firedAt}`);
+        ctx.pushEvent({ action: "create_record", fields: { "标题": `配置同步 ${firedAt}` } });
+      },
+      stop() {},
+    };
+  },
+};
+export default recipe;

package/templates/aitable-handoff/workflows/config-sync/workflow.yml

@@ -0,0 +1,73 @@
+meta:
+  name: "群/管理员配置同步"
+  version: "1.0.0"
+  domain: config_sync
+  description: "定时从固定 AI 表格拉取群配置与管理员,发布到 globalVar(group_configs/admins,供 group-qa 活读);不发群"
+
+notification:
+  channel: "none"
+
+tracker:
+  label: "群与管理员配置同步留痕表"
+  base_id: "" # 与其它工作流同 base;table_id 留空 setup 自动建表回写
+  table_id: ""
+  states:
+    initial: "待处理"
+    active: [ "处理中" ]
+    terminal: [ "已完成", "已关闭" ]
+    blocked: "已阻塞"
+  fields:
+    state: "状态"
+    title: "标题"
+    current_step: "当前步骤"
+    event_log: "事件日志"
+  field_definitions:
+    - name: 同步结果
+      type: text
+    - name: 群数量
+      type: text
+    - name: 管理员数量
+      type: text
+  views:
+    - id: default_grid
+      type: Grid
+      name: 表格
+      field_order: [ 标题, 同步结果, 群数量, 管理员数量, 状态, 当前步骤, 事件日志 ]
+      description: 配置同步留痕
+
+event_sources:
+  - name: 定时同步
+    type: cron_scheduler
+    handler: config_sync_handler
+    record_policy: on_demand # 无变更的 tick 不建行(见 config_sync recipe 的 tracker:false)
+    config:
+      interval_ms: 300000 # 5 分钟
+      fire_immediately: true
+      event_type: config_sync_tick
+
+steps:
+  - id: config_sync
+    name: "拉取并固化群/管理员配置"
+    recipe: config_sync
+    auto: true
+    config:
+      group_table:
+        baseId: ""
+        tableId: ""
+      admin_table:
+        baseId: ""
+        tableId: ""
+      group_var: "${globalVar.group_configs}"
+      pull_list_var: "${globalVar.group_pull_list}"
+      admin_var: "${globalVar.admins}"
+    input_mapping: {}
+    output_mapping:
+      sync_result: "同步结果"
+      group_count: "群数量"
+      admin_count: "管理员数量"
+
+edges:
+  - from: __start__
+    to: config_sync
+  - from: config_sync
+    to: __end__