aitable-workflow-cli 0.1.13-beta.1

package/templates/support-qa/profiles/default/profile/profile.yml

@@ -0,0 +1,206 @@
+# support-qa Profile v2 — 业务包唯一配置入口（默认包：开箱可跑的完整配置）
+#
+# 两个轴：roles.*（角色定义）+ workflows.*（工作流配置）。
+# 本文件按 workflows/ 下各 recipe 的 meta.config（zod）逐字段生成，覆盖全部
+# 工作流 / 事件源 / 步骤——不是注释掉的清单，而是一份真正生效的配置。
+#
+# 填写约定：
+#   ⚠️  = 必须替换为你的业务值（已给可跑占位值，直接跑也不会崩）
+#   ""  = 留空待填；表 ID 类留空由 `setup` 自动建表并回写，无需手填
+#   ${env.X}        = 从 .env 读取（见 .env.example）
+#   ${globalVar.X}  = 运行时跨工作流活读，不要改
+#
+# 完整字段与语义见 docs/plans/2026-07-28-support-qa-profile-config-refactor-spec.md
+schema_version: 2
+
+# ─── 角色轴：完整 role 定义，严格遵循 core roleDefinitionSchema ──
+# id 由键名承载；name / persona 为必填（不可为空串），persona 支持内联字符串
+# 或 { file: } 引用（相对本目录，推荐长人设）。
+# 下列 4 个角色被 requiresAgent 的步骤消费，删掉会导致对应步骤无角色可用：
+#   support → answer   troubleshooter → troubleshoot
+#   kb-editor → kb_refine   daily-review → daily_review
+roles:
+  support:
+    name: "产品答疑助手" # ⚠️ 替换为你的产品助手称呼
+    # ⚠️ 替换为你的产品人设：说明「你是谁」「答疑边界」「关键词→文档索引」。
+    # 长人设建议改用文件引用：persona: { file: prompts/persona.md }
+    persona: |
+      你是一名群知识库答疑助手，只基于注入的知识库为用户答疑。
+      事实依据只能来自知识库；知识库没提到的功能不要断言"不支持"，
+      也不要臆造功能路径与参数。无法确定时保持静默，交由人工处理。
+    knowledge_scope:
+      kb_collections:
+        - wiki/support # ⚠️ 把产品帮助文档放进该目录（相对实例根），setup 会编译为知识库
+
+  troubleshooter:
+    name: 问题排查助手
+    persona: |
+      你是一名问题排查助手。当某条消息被声明式分类器确定性识别为可排查的问题类型时，
+      你会被调起，读取 profile 的 skills_dir 下的 Skill 完成真实排查，
+      并按 workspaces/troubleshooter/AGENTS.md 的 JSON 契约输出结果。
+
+  kb-editor:
+    name: 知识库编辑
+    persona: |
+      你是知识库编辑，负责把「管理员的权威结论」提炼成简洁、准确、可检索的 FAQ 条目。
+    guardrails:
+      - id: faithful-to-admin
+        rule: 严格忠实管理员结论，不臆造功能/路径/参数；管理员未提及的不要补充。
+        severity: warning
+      - id: output-conclusion-only
+        rule: 只输出要追加的 Markdown 结论正文，不输出文件名/JSON/前后缀说明。
+        severity: warning
+
+  config-syncer:
+    name: 配置同步器
+    persona: 你负责把远程 AI 表格里的群配置与管理员名单固化到本地文件，仅做数据搬运，不作答。
+
+  daily-review:
+    name: 每日复盘
+    persona: 你负责每日凌晨对各群昨日对话做复盘，仅做归纳整理，不对外发言。
+
+# ─── 工作流轴：config 按 workflowId → event_sources / steps 组织 ──
+# step 键 = workflow.yml 里的 steps[].id；event_source 键 = event_sources[].name
+workflows:
+  # ─────────────────────────────────────────────────────────────
+  # 群答疑主链：fastpath → troubleshoot → answer → on_action → reply_to_group
+  # ─────────────────────────────────────────────────────────────
+  group-qa:
+    toolkit_config:
+      messaging:
+        # 出站凭据二选一（`?` 后缀 = 可选引用，未配不报错），发群消息至少配其一：
+        # 群 Webhook 出站凭据(JSON map: credRef → {url, secret})：群配置表里每个群的
+        # 「凭据引用」按名字从本 map 解析；L0 默认出站方式。
+        webhook_creds: ${env.DINGTALK_WEBHOOK?}
+        # 企业机器人凭据(JSON map: credRef → {client_id, client_secret})：
+        # L2 双轨接入(stream 入站 + 会话内出站)时在 .env 配置 DINGTALK_ROBOTS，
+        # 并在 workflow.yml 追加 dingtalk_stream 事件源。
+        robot_creds: ${env.DINGTALK_ROBOTS?}
+      memory: { root_dir: "./.memory" }
+    event_sources:
+      群消息监听:
+        # 监听群名单由 config-sync 工作流发布到 globalVar，此处活读；
+        # 若删除 workflows/config-sync/ 则改为静态数组，如 ["cidAAA=="]。
+        conversation_ids: "${globalVar.group_pull_list}"
+        poll_interval_ms: 12000
+        image_mode: download # 图片本地化：download（鉴权下载）/ url / none
+        handler_config:
+          # 群机器人身份与真人名单来源，均由 config-sync 发布
+          conversation_ids: "${globalVar.group_configs}"
+          admins: "${globalVar.admins}"
+    steps:
+      # 确定性秒回：命中规则文件即秒回，不走 LLM
+      fastpath:
+        rules: fastpath/known-answers.yml # 相对 profile 目录；⚠️ 按产品补充已知问答
+
+      # 诊断升级：分类器命中 → 独立排查 Agent 读 Skill 真实排查
+      troubleshoot:
+        conversation_ids: "${globalVar.group_configs}" # 仅「是否排查问题」开启的群生效
+        classifiers: troubleshoot/classifiers.yml # 相对 profile 目录；⚠️ 按产品补充分类规则
+        skills_dir: "" # ⚠️ 排查 Skill 目录（相对实例根，如 skills/troubleshooting）；留空即整档关闭
+
+      # 主应答（LLM + 知识库）
+      answer:
+        # coding: { engine: qoder } # 可选：覆写本步 coding 引擎（缺省走全局 coding-agents 配置）
+        standby:
+          enabled: false # 追问补位：用户 @真人后超时无人回且用户追问时放行
+          wait_minutes: 30
+        # 模块→Owner 映射在 AI 表格「功能模块人员配置表」维护（模块-文本 + 人员-人员字段），
+        # 由 config-sync 定时拉取并发布 ${globalVar.module_owners}；表为空即无转人工
+
+      # 决策后处置（拍平 action）：只配留痕(track)与群里说不说话(group: answer|silent)。
+      # Owner 尾注不在这里配：bug/feature/kb_gap 且 module 能解析出 Owner 时 Runtime 自动附加；
+      # 通知渠道不在这里配：Runtime 只产出结构化通知字段，TODO/IM 由 AI 表格自动化按需发起
+      on_action:
+        # 功能模块人员配置来源（config-sync 发布）：bug/feature/kb_gap 升级时据此解析模块 Owner
+        module_owners: "${globalVar.module_owners}"
+        policies:
+          reply: { track: true, group: answer } # 有据回答：发群
+          bug: { track: true, group: answer } # Bug 升级：发群（Owner 可解析则自动附尾注）
+          feature: { track: true, group: answer } # 需求建议：发群（同上）
+          kb_gap: { track: true, group: silent } # 知识缺口：默认静默入收件箱；改 answer 即群内坦白无据+附 Owner 尾注
+          no_question: { track: false, group: silent } # 非提问：不建行（避免表被噪音刷屏）
+          human_handled: { track: false, group: silent } # 真人已处理：不建行
+          owner_mentioned: { track: true, group: silent } # 已 @到人：留痕
+          safety: { track: true, group: silent } # 安全拦截：留痕
+          agent_failure: { track: true, group: silent } # Agent 故障：留痕不发群
+
+      # 出站：按群配置的出站方式自动选路（webhook / 会话内）
+      reply_to_group:
+        group_configs: "${globalVar.group_configs}"
+
+  # ─────────────────────────────────────────────────────────────
+  # 配置同步：定时把群配置表 + 管理员表拉取并发布到 globalVar
+  # 供 group-qa / daily-review 活读；删除本工作流则上面改为静态数组
+  # ─────────────────────────────────────────────────────────────
+  config-sync:
+    event_sources:
+      定时同步:
+        interval_ms: 300000 # 5 分钟；也可改用 daily_at / cron
+        fire_immediately: true # 启动即同步一次，避免首轮空名单
+        event_type: config_sync_tick
+    steps:
+      config_sync:
+        # 三张表留空即可：setup 会自动建表（含字段/选项）并把 ID 回写到本文件
+        group_table: { baseId: "", tableId: "" }
+        admin_table: { baseId: "", tableId: "" }
+        owner_table: { baseId: "", tableId: "" } # 功能模块人员配置表（模块-文本 + 人员-人员）：bug/feature/kb_gap 升级时 @ 模块 Owner
+        group_var: "${globalVar.group_configs}"
+        pull_list_var: "${globalVar.group_pull_list}"
+        stream_var: "${globalVar.stream_robot_refs}"
+        admin_var: "${globalVar.admins}"
+        owner_var: "${globalVar.module_owners}"
+        empty_confirm_rounds: 2 # 空快照门禁：连续读到空达该轮数才真正清空（防读空抖动误清名单）；设 1 即即时清空
+
+  # ─────────────────────────────────────────────────────────────
+  # 管理员知识更新：管理员在群问答表补结论 → 提炼为 FAQ 条目落库
+  # ─────────────────────────────────────────────────────────────
+  admin-kb-update:
+    toolkit_config:
+      file: { base_dir: "${roles.support.knowledge_scope.kb_collections[0]}" }
+    event_sources:
+      管理员更新监听:
+        # 监听 group-qa 的工单表（引用形态，运行时解析，无需填 ID）
+        source_table: { mode: reference, ref: workflow:group-qa.tracker }
+        watch_mode: both
+        poll_interval_ms: 300000
+        resolve_field_names: true
+        emit_existing: true
+        filter: { field: 知识沉淀, equals: 待沉淀 }
+        handler_config:
+          admin_field: 管理员更新
+          question_field: 消息内容
+          context_field: 对话上下文
+    steps:
+      kb_refine:
+        # coding: { engine: qoder } # 可选：覆写本步 coding 引擎（缺省走全局 coding-agents 配置）
+        file: { base_dir: "${roles.support.knowledge_scope.kb_collections[0]}" }
+        kb_file: FAQ.md # 追加目标 .md（相对 file.base_dir）
+
+  # ─────────────────────────────────────────────────────────────
+  # 每日复盘：凌晨归纳昨日对话，产出统计 / 需求池 / 学习候选
+  # ─────────────────────────────────────────────────────────────
+  daily-review:
+    toolkit_config:
+      memory: { root_dir: "./.memory" }
+    event_sources:
+      每日复盘调度:
+        daily_at: "01:00"
+        timezone: Asia/Shanghai
+        event_type: daily_review_trigger
+        fire_immediately: false
+    steps:
+      daily_review:
+        conversation_ids: "${globalVar.group_configs}" # 复盘群来源（或改为静态数组）
+        # 两张表留空即可：setup 自动建表并回写
+        daily_stats_table: { baseId: "", tableId: "" }
+        product_backlog_table: { baseId: "", tableId: "" }
+        # 学习候选写回 group-qa 的工单表（引用形态，运行时解析）
+        learning_candidate_table:
+          baseId: { ref: workflow:group-qa.tracker.base_id }
+          tableId: { ref: workflow:group-qa.tracker.table_id }
+        saved_minutes_per_reply: 15 # 每条 Agent 回复折算节省的人工工时（分钟）
+        timezone: Asia/Shanghai # 与 cron 时区一致；远端 UTC 机器必须显式设置
+        learning:
+          from_admin_replies: true # 从真人解答提炼学习候选
+          review: human-approve # human-approve（人工确认）/ auto（自动入库）

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

@@ -0,0 +1,37 @@
+# troubleshoot 声明式分类器（support-qa L3，取代硬编码 issue-classifier.ts）
+#
+# 启用：在 profile/profile.yml 打开
+#   troubleshoot:
+#     skills_dir: skills/troubleshooting     # 相对实例根；目录不存在 → 整档关闭
+#     classifiers: troubleshoot/classifiers.yml
+# 另需在群配置表把该群的 troubleshootingEnabled 置真，才对该群启用（按群开关）。
+#
+# 每个分类器：
+#   issueType   ：命中后的问题类型标签（传给排查 Agent 作路由）
+#   reason      ：命中理由（审计/日志）
+#   patterns    ：匹配条件列表，每条 contains 或 regex 之一
+#   require_all ：默认 false（任一 pattern 命中即算）；true 时需全部命中
+#   extract     ：可选，字段名→正则（取第一个捕获组），把结构化证据带进排查 prompt
+# 按声明顺序匹配，返回第一个满足的分类器；都不命中 → 交语义答疑 answer。
+#
+# ⚠️ 本文件为通用示例（product-neutral），请按你的产品替换/删除后再启用。
+
+classifiers:
+  # 示例 1：单条件（任一命中）——报错模板类
+  - issueType: error_report
+    reason: 命中报错模板
+    patterns:
+      - contains: "ERR_EXAMPLE"
+    extract:
+      code: "ERR_EXAMPLE[_A-Z0-9]*"
+
+  # 示例 2：多条件同时命中（require_all）——需要两个关键词共现才判定
+  - issueType: compound_issue
+    reason: 同时包含标识 A 与标识 B
+    require_all: true
+    patterns:
+      - contains: "标识A"
+      - contains: "标识B"
+    extract:
+      idA: "标识A[:：=]\\s*([A-Za-z0-9_-]+)"
+      idB: "标识B[:：=]\\s*(\\d+)"

package/templates/support-qa/profiles/default/wiki/support//345/270/270/350/247/201/351/227/256/351/242/230.md

@@ -0,0 +1,10 @@
+# 常见问题（示例占位）
+
+> 这是 support-qa 模板的知识库占位文件。把你的产品帮助文档（Markdown）放入本目录
+> （profile.knowledge.collections 指向的目录），答疑助手只依据这里的内容作答。
+>
+> 建议每篇文章 frontmatter 携带 `original_sources`（在线原文链接），回复出处依赖它。
+
+## Q: 这是什么？
+
+A: support-qa 通用答疑工作流的示例知识库。替换本文件为真实产品文档后即可开始答疑。

package/templates/support-qa/workflows/admin-kb-update/recipes/kb-refine.recipe.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { type RecipeDefinition, type RecipeContext, type RecipeResult } from "aitable-workflow-core";
+import { KB_STATUS, resolveCurationTarget, DEFAULT_CURATION_TARGET } from "../../../lib/contract.js";
+
+/**
+ * 知识提炼并写入本地知识库（管理员知识更新流的唯一步骤）
+ *
+ * 输入来自 kb_sync_handler 建的工单：原问题(question) + 对话上下文(context) + 管理员结论(adminUpdate)。
+ * 流程：coding agent 依据三者【提炼】出要追加的 Markdown 结论（只输出结论正文，不决定写哪个文件），
+ * 再由本 recipe 用 file toolkit 确定性追加到固定目标文件（config.kb_file，缺省 FAQ.md，jail 在 base_dir 内），
+ * ~60s 自动重编生效。kb_file 规则收口在 contract.resolveCurationTarget（与 assemble 定点回写共用，
+ * 评审 P1）：不自动补扩展名、不静默回退，显式非法配置直接 failed。
+ *
+ * 不发群消息（本流无 reply 步骤）。提炼规范见执行 workspace 下的 AGENTS.md（CLI 自动读取）。
+ */
+
+/** 从 agent 响应中取出要追加的正文：剥离可能的 ``` 代码块围栏，其余原样 */
+function extractContent(raw: string): string {
+  if (!raw) return "";
+  const s = raw.trim();
+  const fence = s.match(/```(?:markdown|md)?\s*([\s\S]*?)```/i);
+  return (fence?.[1] ?? s).trim();
+}
+
+const recipe: RecipeDefinition = {
+  meta: {
+    id: "kb_refine",
+    name: "提炼并写入知识库",
+    role: "kb-editor",
+    description: "coding agent 依据问答与管理员结论提炼要追加的结论，file toolkit 写入本地知识库",
+    version: "1.0.0",
+    requiresAgent: true,
+    timeoutMs: 180_000,
+    config: z.object({
+      coding: z.object({ engine: z.string().optional() }).optional(),
+      file: z.object({ base_dir: z.string().optional() }).optional(),
+      kb_file: z.string().optional().describe(`追加目标 .md 文件（相对 file.base_dir），缺省 ${DEFAULT_CURATION_TARGET}`),
+    }),
+  },
+
+  async execute(ctx: RecipeContext): Promise<RecipeResult> {
+    const { input, toolkit, config, log } = ctx;
+    const adminUpdate = String(input.adminUpdate ?? "").trim();
+    const question = String(input.question ?? "").trim();
+    const context = String(input.context ?? "").trim();
+    const srcBaseId = String(input.srcBaseId ?? "").trim();
+    const srcTableId = String(input.srcTableId ?? "").trim();
+    const srcRecordId = String(input.srcRecordId ?? "").trim();
+    // 与 assemble 定点回写同源的目标文件规则（评审 P1）：显式非法配置是配置错误而非瞬时故障，
+    // 直接 failed 暴露（不自动修正到另一个文件，避免与 profile/workflow 声明值分家）
+    const kbTarget = resolveCurationTarget(config.kb_file);
+    if (kbTarget.error) {
+      log(`kb_file 配置非法，阻断写入: ${kbTarget.error}`);
+      return { status: "failed", output: { kb_synced: "失败" }, error: `kb_refine: ${kbTarget.error}`, logs: ["kb_file 配置非法 → failed（请修正 profile/workflow 配置）"] };
+    }
+    const kbFile = kbTarget.value;
+
+    if (!adminUpdate) {
+      // 空更新是数据问题而非瞬时故障，重试无益 → 保持 success 终态留痕
+      log("管理员更新为空，跳过（本流工单应始终带管理员更新）");
+      return { status: "success", output: { kb_synced: "失败" }, logs: ["管理员更新为空 → 跳过"] };
+    }
+
+    const prompt = `请把「管理员的权威结论」提炼成一条规范、可检索的知识库 FAQ 条目，并【只输出要追加到知识库的结论正文】。
+
+## 素材
+### 原始问题
+${question || "（未提供）"}
+### 对话上下文
+${context || "（无）"}
+### 管理员结论（权威依据，以此为准）
+${adminUpdate}
+
+## 输出要求
+- 只输出要追加的 Markdown 结论正文本身（形如 "## 问题\\n\\n答案"）；简洁、准确、可检索。
+- 不要输出目标文件名、不要输出 JSON、不要任何前后缀说明或代码块包裹。
+详细提炼规范见本工作目录下的 AGENTS.md。`;
+
+    // 执行 workspace（含该角色 AGENTS.md）由 coding toolkit 按角色自动准备，recipe 无需关心 workDir。
+    log(`kb_refine 调 coding agent 提炼: ${(question || adminUpdate).slice(0, 40)}`);
+    const result = await toolkit.coding.run(prompt);
+
+    // 以下三类失败均返回 status: "failed"（评审 P1）：触发引擎按 max_step_failures 重试；
+    // 重试耗尽后源行仍是「待沉淀」，handler 内存 seen 过期/重启后会重新建单——
+    // 收敛唯一锚点是成功回写「已沉淀」，知识更新不会因一次失败永久卡死。
+    if (!result.response) {
+      log("coding agent 无有效响应，标记失败（可重试）");
+      return { status: "failed", output: { kb_synced: "失败" }, error: "kb_refine: coding agent 无有效响应", logs: ["agent 无响应 → failed(可重试)"] };
+    }
+
+    const content = extractContent(result.response);
+    if (!content) {
+      log("提炼结果为空，标记失败（可重试）");
+      return {
+        status: "failed",
+        output: { kb_synced: "失败" },
+        error: "kb_refine: 提炼结果为空",
+        logs: ["提炼内容为空 → failed(可重试)", `原始: ${result.response.slice(0, 120)}`],
+      };
+    }
+
+    try {
+      await toolkit.file.append({ path: kbFile, content: `\n\n${content}\n` });
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      log(`写入知识库失败: ${kbFile} — ${msg}`);
+      return { status: "failed", output: { kb_synced: "失败" }, error: `kb_refine: 写入知识库失败 ${msg}`, logs: ["file.append 失败 → failed(可重试)"] };
+    }
+
+    const title = content.split("\n").find((l) => l.trim())?.replace(/^#+\s*/, "").slice(0, 40) ?? "";
+    log(`已追加到知识库: ${kbFile}（${content.length} 字，${title}）`);
+
+    // 回写 group-qa 源行「知识沉淀=已沉淀」，使事件源过滤集收敛（不再重复拉取该行）。
+    // 幂等：仅成功路径回写；失败只 log 不阻断，下轮源行仍为「待沉淀」会自动重试。
+    if (srcBaseId && srcTableId && srcRecordId) {
+      try {
+        await toolkit.table.updateRecordIn(
+          { baseId: srcBaseId, tableId: srcTableId },
+          srcRecordId,
+          { "知识沉淀": KB_STATUS.PERSISTED },
+        );
+        log(`已回写源行 ${srcRecordId} 知识沉淀=已沉淀`);
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        log(`回写源行知识沉淀失败（不阻断，下轮重试）: ${srcRecordId} — ${msg}`);
+      }
+    }
+
+    return {
+      status: "success",
+      output: { kb_synced: "已同步", kb_article: kbFile },
+      logs: [`已写入 ${kbFile}`, "答疑侧直接读取原文，追加即生效"],
+    };
+  },
+};
+
+export default recipe;

package/templates/support-qa/workflows/admin-kb-update/recipes/kb_sync_handler.recipe.ts

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import type {
+  EventHandlerRecipeDefinition,
+  HandlerInitContext,
+  HandlerInstance,
+} from "aitable-workflow-core";
+
+/**
+ * 管理员知识更新 — 事件过滤 + 去重 + 建单（dumb handler，不碰 toolkit）
+ *
+ * aitable_record 源监听「群问答表」（filter: 知识沉淀=待沉淀），产出 record_created/record_updated。
+ * 本 handler 只做三件事：
+ *   1. 过滤：只处理「管理员更新」列非空的行；
+ *   2. 去重：按 hash(recordId + 管理员更新内容) 做**进程内存 + TTL** 抑制——
+ *      只防同进程短窗口内的重复建单（同一行反复触发事件/emit_existing 首轮重放）；
+ *      **故意不持久化**：收敛的唯一锚点是 kb_refine 成功后回写源行「知识沉淀=已沉淀」
+ *      （事件源过滤集随之收敛）。若 kb_refine 失败（返回 failed → 引擎按 max_step_failures
+ *      重试），源行仍是「待沉淀」，进程重启/TTL 过期后 emit_existing 会重放建单，
+ *      天然构成失败恢复通道——持久 seen 会把失败行永久卡死（评审 P1）。
+ *   3. 建单：把 消息内容/对话上下文/管理员更新 复制进【本流】的知识更新表，
+ *      交给 kb_refine 步骤用 coding agent 提炼后写库。
+ */
+
+const SEEN_TTL_MS = 30 * 60 * 1000; // 覆盖 refine 执行 + 引擎重试窗口即可，无需更长
+const SEEN_CAPACITY = 1000;
+
+/** 把 aitable cell 值稳健地转成纯文本（兼容 string / number / {text}/{value} / 数组） */
+function cellToString(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return value.map(cellToString).filter(Boolean).join("\n");
+  if (typeof value === "object") {
+    const rec = value as Record<string, unknown>;
+    if (typeof rec.text === "string") return rec.text;
+    if (typeof rec.value === "string") return rec.value;
+    if (typeof rec.name === "string") return rec.name;
+  }
+  return "";
+}
+
+const recipe: EventHandlerRecipeDefinition = {
+  meta: {
+    id: "kb_sync_handler",
+    name: "管理员知识更新过滤器",
+    description: "过滤群问答表「管理员更新」列非空的行，短窗口去重后建知识更新工单（交给 kb_refine 提炼写库）",
+    config: z.object({
+      admin_field: z.string().optional().describe("管理员填结论的列名，默认「管理员更新」"),
+      question_field: z.string().optional().describe("原问题列名，默认「消息内容」"),
+      context_field: z.string().optional().describe("对话上下文列名，默认「对话上下文」"),
+    }),
+  },
+
+  create(ctx: HandlerInitContext): HandlerInstance {
+    const adminField = String(ctx.config.admin_field ?? "管理员更新");
+    const questionField = String(ctx.config.question_field ?? "消息内容");
+    const contextField = String(ctx.config.context_field ?? "对话上下文");
+    // 进程内存去重（key → 首见时间）；重启即清空（见文件头注释：这是特性不是缺陷）
+    const seen = new Map<string, number>();
+
+    function seenRecently(key: string): boolean {
+      const now = Date.now();
+      const at = seen.get(key);
+      if (at !== undefined && now - at <= SEEN_TTL_MS) return true;
+      seen.set(key, now);
+      // 容量/TTL 裁剪
+      if (seen.size > SEEN_CAPACITY) {
+        for (const [k, ts] of seen) {
+          if (now - ts > SEEN_TTL_MS) seen.delete(k);
+          if (seen.size <= SEEN_CAPACITY) break;
+        }
+      }
+      return false;
+    }
+
+    return {
+      onEvent(event) {
+        const cells = (event.payload?.cells ?? {}) as Record<string, unknown>;
+        const admin = cellToString(cells[adminField]).trim();
+        if (!admin) return; // 绝大多数群问答字段变更事件在此快速返回
+
+        const recordId = String(event.itemId ?? "");
+        const key = createHash("sha1").update(`${recordId}\u0000${admin}`).digest("hex");
+        if (seenRecently(key)) {
+          ctx.log(`管理员更新短窗口内已建单（seen TTL 命中），跳过: ${recordId}`);
+          return;
+        }
+
+        const question = cellToString(cells[questionField]).trim();
+        const context = cellToString(cells[contextField]).trim();
+
+        // 源行坐标：供 kb_refine 处理完回写 group-qa 源行「知识沉淀=已沉淀」，使拉取集收敛。
+        const payload = (event.payload ?? {}) as Record<string, unknown>;
+        const srcBaseId = typeof payload.baseId === "string" ? payload.baseId : "";
+        const srcTableId = typeof payload.tableId === "string" ? payload.tableId : "";
+
+        ctx.log(`捕获管理员更新（源行 ${recordId}），建知识更新工单`);
+        ctx.pushEvent({
+          action: "create_record",
+          fields: {
+            "标题": `知识更新: ${(question || admin).slice(0, 20)}`,
+            "消息内容": question,
+            "对话上下文": context,
+            "管理员更新": admin,
+            "源表BaseId": srcBaseId,
+            "源表TableId": srcTableId,
+            "源行RecordId": recordId,
+          },
+        });
+      },
+      stop() {
+        seen.clear();
+      },
+    };
+  },
+};
+
+export default recipe;

package/templates/support-qa/workflows/admin-kb-update/workflow.yml

@@ -0,0 +1,96 @@
+meta:
+  name: "管理员知识更新"
+  version: "1.0.0"
+  domain: kb_admin
+  description: "监听群问答表「知识沉淀=待沉淀」行的「管理员更新」列，coding agent 提炼后写入本地知识库（不发群消息）。知识飞轮三路进料（手工/缺口/学习候选）在此汇合入库"
+
+# ─── 通知配置 ─────────────────────────────────────
+notification:
+  channel: "none"
+
+# ─── 数据表（独立于群问答表：本流自己的「知识更新工单表」）─────
+# table_id 留空 → setup 自动建表并回写到本文件；不可与 group-qa 同表，
+# 否则 group-qa 的 reconcile 会把知识更新工单也当群问答处理。
+# ⚠️ 占位:部署前替换为你自己的 base_id
+tracker:
+  label: "管理员知识更新留痕表"
+  description: "记录知识沉淀内容的表格，提炼后写入本地知识库"
+  base_id: ""
+  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
+    - name: 知识库文章
+      type: text
+    - name: 知识库同步
+      type: singleSelect
+      options:
+        - 已同步
+        - 失败
+    - name: 源表BaseId
+      type: text
+    - name: 源表TableId
+      type: text
+    - name: 源行RecordId
+      type: text
+
+  views:
+    - id: default_grid
+      type: Grid
+      name: 表格
+      field_order:
+        - 标题
+        - 消息内容
+        - 管理员更新
+        - 知识库文章
+        - 知识库同步
+        - 状态
+        - 当前步骤
+        - 事件日志
+      description: 管理员知识更新 - 处理留痕
+
+# ─── 事件源：监听群问答表「知识沉淀=待沉淀」行的「管理员更新」列 ─────
+event_sources:
+  - name: 管理员更新监听
+    type: aitable_record
+    handler: kb_sync_handler
+
+# ─── 步骤：唯一一步，coding agent 提炼后写库（无 reply 步骤 → 不发群）─────
+steps:
+  - id: kb_refine
+    name: "提炼并写入知识库"
+    recipe: kb-refine
+    auto: true
+    input_mapping:
+      question: "消息内容"
+      context: "对话上下文"
+      adminUpdate: "管理员更新"
+      srcBaseId: "源表BaseId"
+      srcTableId: "源表TableId"
+      srcRecordId: "源行RecordId"
+    output_mapping:
+      kb_synced: "知识库同步"
+      kb_article: "知识库文章"
+
+edges:
+  - from: __start__
+    to: kb_refine
+  - from: kb_refine
+    to: __end__