aitable-workflow-cli 0.1.13-beta.1

package/templates/aitable-handoff/workflows/admin-kb-update/recipes/kb-refine.recipe.ts

@@ -0,0 +1,131 @@
+import path from "node:path";
+import { z } from "zod";
+import { type RecipeDefinition, type RecipeContext, type RecipeResult } from "aitable-workflow-core";
+
+/**
+ * 知识提炼并写入本地知识库（管理员知识更新流的唯一步骤）
+ *
+ * 输入来自 kb_sync_handler 建的工单：原问题(question) + 对话上下文(context) + 管理员结论(adminUpdate)。
+ * 流程：coding agent 依据三者【提炼】出要追加的 Markdown 结论（只输出结论正文，不决定写哪个文件），
+ * 再由本 recipe 用 file toolkit 确定性追加到固定目标文件（config.kb_file，默认 faq.md，jail 在 base_dir 内），
+ * ~60s 自动重编生效。
+ *
+ * 不发群消息（本流无 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();
+}
+
+/** 目标 .md 路径清洗：拒绝绝对路径 / `..`，缺省 faq.md */
+function sanitizeFile(file: unknown): string {
+  const raw = typeof file === "string" ? file.trim() : "";
+  if (!raw || path.isAbsolute(raw) || raw.includes("..")) return "faq.md";
+  return raw.endsWith(".md") ? raw : `${raw}.md`;
+}
+
+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），默认 faq.md"),
+    }),
+  },
+
+  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();
+    const kbFile = sanitizeFile(config.kb_file);
+
+    if (!adminUpdate) {
+      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);
+
+    if (!result.response) {
+      log("coding agent 无有效响应，标记失败");
+      return { status: "success", output: { kb_synced: "失败" }, logs: ["agent 无响应 → 失败"] };
+    }
+
+    const content = extractContent(result.response);
+    if (!content) {
+      log("提炼结果为空，标记失败");
+      return {
+        status: "success",
+        output: { kb_synced: "失败" },
+        logs: ["提炼内容为空 → 失败", `原始: ${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: "success", output: { kb_synced: "失败" }, logs: ["file.append 失败 → 失败"] };
+    }
+
+    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,
+          { "知识沉淀": "已沉淀" },
+        );
+        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/aitable-handoff/workflows/admin-kb-update/recipes/kb_sync_handler.recipe.ts

@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import type {
+  EventHandlerRecipeDefinition,
+  HandlerInitContext,
+  HandlerInstance,
+} from "aitable-workflow-core";
+
+/**
+ * 管理员知识更新 — 事件过滤 + 去重 + 建单（dumb handler，不碰 toolkit）
+ *
+ * aitable_record 源监听「群问答表」，任何行的 cells 变化都会产出 record_created/record_updated。
+ * 本 handler 只做三件事：
+ *   1. 过滤：只处理「管理员更新」列非空的行；
+ *   2. 去重：按 hash(recordId + 管理员更新内容) 持久化到 seen 文件，
+ *      群问答流反复写该行触发的事件、重启后的重放都不会重复建单；
+ *   3. 建单：把 消息内容/对话上下文/管理员更新 复制进【本流】的知识更新表，
+ *      交给 kb_refine 步骤用 coding agent 提炼后写库。
+ *
+ * 真正的提炼与写库在 kb-refine.recipe（coding agent + file toolkit），本 handler 不做业务写入。
+ */
+
+type SeenState = { keys: string[] };
+
+/** 把 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 "";
+}
+
+function loadSeen(file: string, log: (m: string) => void): Set<string> {
+  try {
+    if (!existsSync(file)) return new Set();
+    const parsed = JSON.parse(readFileSync(file, "utf8")) as SeenState;
+    return new Set(Array.isArray(parsed.keys) ? parsed.keys : []);
+  } catch (error) {
+    log(`seen 文件加载失败，视为空: ${error instanceof Error ? error.message : String(error)}`);
+    return new Set();
+  }
+}
+
+function persistSeen(file: string, seen: Set<string>, log: (m: string) => void): void {
+  try {
+    mkdirSync(path.dirname(file), { recursive: true });
+    // 上限保护：只保留最近 5000 条，避免文件无限增长
+    const keys = [...seen].slice(-5000);
+    writeFileSync(file, JSON.stringify({ keys }), "utf8");
+  } catch (error) {
+    log(`seen 文件落盘失败: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+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("对话上下文列名，默认「对话上下文」"),
+      seen_file: z.string().optional().describe("去重状态文件（相对 configDir），默认 .state/admin-kb-seen.json"),
+    }),
+  },
+
+  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 ?? "对话上下文");
+    const seenFileRel = String(ctx.config.seen_file ?? ".state/admin-kb-seen.json");
+    const seenFile = path.isAbsolute(seenFileRel) ? seenFileRel : path.resolve(ctx.configDir, seenFileRel);
+    const seen = loadSeen(seenFile, ctx.log);
+
+    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 (seen.has(key)) {
+          ctx.log(`管理员更新已处理过（seen 命中），跳过: ${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,
+          },
+        });
+
+        seen.add(key);
+        persistSeen(seenFile, seen, ctx.log);
+      },
+      stop() {
+        // 无定时器/资源
+      },
+    };
+  },
+};
+
+export default recipe;

package/templates/aitable-handoff/workflows/admin-kb-update/workflow.yml

@@ -0,0 +1,125 @@
+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/table_id(group-qa 与 admin-kb-update 的监听表须指向同一张群问答表)
+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: 管理员知识更新 - 处理留痕
+
+# ─── Toolkit 配置 ─────────────────────────────────
+# coding 引擎继承全局 agent.engine（见 aitable-workflow.config.yml）
+toolkit_config:
+  file:
+    base_dir: wiki/faq-support # 写库 jail 根（相对 configDir）；与 faq-support 答疑读取的原始文档同一物理目录，追加即被读到
+
+# ─── 事件源：监听群问答表的「管理员更新」列 ─────────────
+event_sources:
+  - name: 管理员更新监听
+    type: aitable_record
+    handler: kb_sync_handler
+    config:
+      # 监听的是 group-qa 群问答表（管理员在该表某行填写「管理员更新」列）
+      source_table:
+        mode: reference
+        ref: workflow:group-qa.tracker
+      watch_mode: both # 新填/改写「管理员更新」都要捕获
+      poll_interval_ms: 300000 # 5分钟
+      resolve_field_names: true # cells 用字段名 key，handler 直接按「管理员更新」读
+      emit_existing: true # 首轮即对存量「待沉淀」行触发处理（不静默建基线）
+      # 服务端过滤：只拉「知识沉淀=待沉淀」的行，避免答疑记录增长后每轮全表拉取。
+      # 管理员想沉淀某行时把「知识沉淀」置为「待沉淀」；kb_refine 处理完自动回写「已沉淀」，使拉取集恒定收敛。
+      filter:
+        field: 知识沉淀
+        equals: 待沉淀
+    handler_config:
+      admin_field: "管理员更新"
+      question_field: "消息内容"
+      context_field: "对话上下文"
+      seen_file: ".state/admin-kb-seen.json"
+
+# ─── 步骤：唯一一步，coding agent 提炼后写库（无 reply_to_group → 不发群）─────
+steps:
+  - id: kb_refine
+    name: "提炼并写入知识库"
+    recipe: kb-refine
+    auto: true
+    config:
+      file:
+        base_dir: wiki/faq-support
+      kb_file: "钉钉AI表格FAQ.md" # 追加目标（相对 file.base_dir=wiki/faq-support）；agent 只产出结论正文，不决定文件
+    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__