aitable-workflow-cli 0.1.13-beta.1

package/templates/aitable-handoff/workflows/daily-review/workflow.yml

@@ -0,0 +1,92 @@
+meta:
+  name: "每日复盘"
+  version: "1.0.0"
+  domain: daily_review
+  description: "每日凌晨读取各群昨日短期记忆,coding agent 压缩/统计/需求Bug 抽取,写长期记忆+每日统计表+产品需求池;有活动才留痕(不发群)"
+
+notification:
+  channel: "none"
+
+# ─── 复盘留痕表(每个有活动的复盘日留一行运行记录;table_id 留空 setup 自动建表回写)──
+# ⚠️ 占位:部署前替换为你自己的 base_id/table_id;不可与 group-qa 同表
+tracker:
+  label: "每日复盘留痕表"
+  description: "记录每日复盘运行:日期/处理群数/需求Bug数/摘要"
+  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: 需求Bug数
+      type: text
+    - name: 摘要
+      type: text
+  views:
+    - id: default_grid
+      type: Grid
+      name: 表格
+      field_order: [ 标题, 复盘日期, 处理群数, 需求Bug数, 摘要, 状态, 当前步骤, 事件日志 ]
+      description: 每日复盘留痕
+
+# ─── Toolkit：ai 兜底 JSON、coding 跑 AGENTS.md、memory 与 group-qa 同库(读短期记忆)──
+# coding 引擎继承全局 agent.engine（见 aitable-workflow.config.yml）
+toolkit_config:
+  memory:
+    root_dir: "./.memory"
+
+# ─── 事件源：cron 每日触发,on_demand(无活动不建行)──
+event_sources:
+  - name: 每日复盘调度
+    type: cron_scheduler
+    handler: daily_review_handler
+    record_policy: on_demand
+    config:
+      daily_at: "01:00"
+      timezone: "Asia/Shanghai"
+      event_type: daily_review_trigger
+      fire_immediately: false # 真实环境关闭自动触发
+
+steps:
+  - id: daily_review
+    name: "每日复盘"
+    recipe: daily_review
+    auto: true
+    config:
+      # 复盘群来源：静态 conversationId 数组，或引用 ${globalVar.group_configs}（与群消息监听同源）
+      conversation_ids: "${globalVar.group_configs}"
+      # 每日统计表 / 产品需求池:tableId 留空则 setup 自动建表
+      daily_stats_table:
+        baseId: ""
+        tableId: ""
+        mode: owned
+      product_backlog_table:
+        baseId: ""
+        tableId: ""
+      # 每条 Agent 回复节省的人工工时(分钟)
+      saved_minutes_per_reply: 15
+      # 复盘日期计算时区(应与上面 event_sources 的 timezone 一致)
+      # ⚠️ 远端/容器常运行在 UTC,若不显式设置会把"昨天"算错一天(读不到昨日记忆)
+      timezone: "Asia/Shanghai"
+    output_mapping:
+      review_date: "复盘日期"
+      group_count: "处理群数"
+      needs_bug_count: "需求Bug数"
+      summary: "摘要"
+
+edges:
+  - from: __start__
+    to: daily_review
+  - from: daily_review
+    to: __end__

package/templates/aitable-handoff/workflows/group-qa/error-replies.json

@@ -0,0 +1,53 @@
+{
+  "AI字段配置异常，请检查后重试": "**原因说明：** 字段模板的任务参数非法或配置数据损坏，服务端无法正常执行该任务。\n\n**解决方案：**\na. 编辑字段模板，检查配置项是否填写完整\nb. 确认引用的字段和参数设置正确\nc. 如果问题持续，尝试删除该字段模板后重新创建",
+  "指令引用字段已被删除或为非法字段，请修改配置后重试": "**原因说明：** 字段模板依赖的引用字段已被删除、修改或不存在，导致无法正常执行。\n\n**解决方案：**\na. 编辑字段模板配置，重新选择一个有效的引用字段\nb. 如果引用字段被误删，可通过操作历史恢复",
+  "所选字段形成循环引用，数据处理异常，请检查": "**原因说明：** 多个字段模板之间形成了循环依赖关系（如字段 A 引用字段 B，字段 B 又引用字段 A），导致无法正常计算。\n\n**解决方案：**\na. 检查字段模板之间的引用关系\nb. 调整引用链路，确保不存在环形依赖\nc. 如果不确定哪些字段形成了循环，可以逐个检查字段模板的引用配置",
+  "当前 AI 表格归属其他组织，AI 功能仅限该组织成员使用。请联系文档所有者操作或申请加入后重试。": "**原因说明：** 你当前所在的组织与 AI 表格所属的组织不同，AI 功能不支持跨组织调用。\n\n**解决方案：**\na. 确认你在正确的组织环境下操作\nb. 联系文档所有者帮你执行操作\nc. 申请加入该组织后重试",
+  "引用的字段中没有找到合适的附件，AI无法为你生成内容。目前支持钉钉文档和本地文件（文件类型：.pdf .docx .png .jpeg .jpg .webp）": "**原因说明：** 字段模板引用的字段中不包含支持的附件类型，或附件字段为空。\n\n**解决方案：**\na. 确认引用的附件字段中有文件\nb. 检查附件格式是否在支持范围内（.pdf .docx .png .jpeg .jpg .webp）\nc. 如果附件格式不支持，请转换为支持的格式后重新上传",
+  "附件文件超出大小限制：图片不超过10 MB，视频和音频不超过1 GB，PDF 不超过 50 MB": "**原因说明：** 附件文件大小超出了字段模板的处理上限。\n\n**解决方案：**\na. 压缩或裁剪附件文件\nb. 图片确保不超过 10 MB\nc. 视频和音频确保不超过 1 GB\nd. PDF 确保不超过 50 MB",
+  "引用字段不能为空，请填写后重试": "**原因说明：** 字段模板配置中引用了某个字段，但该字段的值为空。\n\n**解决方案：**\n方案一：在引用的字段中填写内容后重试\n方案二：打开字段配置面板，设置允许引用字段为空",
+  "你没有权限访问该文件，请检查权限后再试": "**原因说明：** 字段模板引用的附件或文档，当前用户没有查看/下载权限。\n\n**解决方案：**\na. 确认你对引用的文件有查看或下载权限\nb. 联系文件所有者授予权限后重试",
+  "AI字段使用超限，请明日再试。建议通过关闭自动更新以减少不必要的AI算力消耗。": "**原因说明：** 当日字段模板执行次数已达到每日上限。\n\n**解决方案：**\na. 等待次日额度自动刷新后再执行\nb. 关闭不必要的自动更新，减少 AI 算力消耗\nc. 合理规划执行频率，避免不必要的重复执行",
+  "当前AI字段正在运行中": "**原因说明：** 同一字段已有正在执行的任务，不能重复提交。\n\n**解决方案：**\na. 等待当前任务执行完成后再发起新任务\nb. 如果任务长时间未完成，可以尝试取消后重新执行",
+  "AI字段运行超时，请稍后重试": "**原因说明：** 字段模板的子任务执行时间超过了系统限制。\n\n**解决方案：**\na. 减少单次执行的数据量，分批执行\nb. 稍后重试\nc. 如果不是付费用户，可能会因为资源有限，任务过多，在 6 小时内任务没有执行导致超时",
+  "数据写入失败，请稍后重试": "**原因说明：** 字段模板执行结果在写入表格时失败，可能是网络问题或权限问题。\n\n**解决方案：**\na. 检查表格是否有写入权限\nb. 稍后重试\nc. 如果持续失败，请联系开发者排查",
+  "系统错误，请联系技术支持": "**原因说明：** FaaS 插件执行过程中出现未知系统异常。\n\n**解决方案：**\na. 稍后重试\nb. 如果持续出现，请联系插件开发者或技术支持",
+  "字段模板运行超时，请联系插件开发者": "**原因说明：** FaaS 插件执行时间超过了系统限制。\n\n**解决方案：**\na. 减少单次处理的数据量\nb. 联系插件开发者优化性能",
+  "字段模板运行错误，请联系插件开发者": "**原因说明：** FaaS 插件运行时出现异常。\n\n**解决方案：**\na. 联系插件开发者排查问题\nb. 检查字段模板配置是否正确",
+  "请求的服务超出限制，请稍后重试": "**原因说明：** FaaS 插件请求频率超过了限制。\n\n**解决方案：**\na. 降低执行频率，分批执行\nb. 稍后重试",
+  "账号用量已耗尽，请检查配置并重试": "**原因说明：** FaaS 插件的调用额度已耗尽。\n\n**解决方案：**\na. 联系插件开发者确认额度情况\nb. 检查是否有其他可用的账号配置",
+  "字段模板配置错误，请联系插件开发者": "**原因说明：** FaaS 插件配置参数有误。\n\n**解决方案：**\na. 检查字段模板配置，确认参数填写正确\nb. 联系插件开发者获取正确的配置方式",
+  "授权错误，请检查是否正确关联账号": "**原因说明：** FaaS 插件的授权信息无效或已过期。\n\n**解决方案：**\na. 重新关联账号授权\nb. 检查授权是否已过期，如已过期请重新授权",
+  "当前算粒资源不足，请开通后继续使用": "**原因说明：** 当前用户或组织的 AI 算粒额度不足，无法继续执行字段模板。\n\n**解决方案：**\na. 前往算粒管理页面查看剩余额度\nb. 联系组织管理员充值或调整额度分配\nc. 等待额度按周期自动刷新",
+  "暂不支持当前模型": "**原因说明：** 字段模板配置的 AI 模型不被当前系统支持。\n\n**解决方案：**\na. 编辑字段模板，更换为支持的模型\nb. 联系管理员确认当前可用的模型列表",
+  "输入内容长度超出上限，请缩短自定义提示/要求内容或者引用内容": "**原因说明：** 输入的提示词（Prompt）或引用的内容长度超过了模型的最大限制。\n\n**解决方案：**\na. 精简自定义提示词内容\nb. 减少引用字段中的文本长度\nc. 如果引用了多个字段，尝试减少引用字段数量",
+  "参考图需满足：格式为 PNG，且分辨率不超过 1280×1280 像素": "**原因说明：** 图片编辑场景中，参考图的格式或分辨率不符合要求。\n\n**解决方案：**\na. 将参考图转换为 PNG 格式\nb. 确保图片分辨率不超过 1280×1280 像素\nc. 使用图片编辑工具调整后重新上传",
+  "图片分辨率过大或过小，请调整后重试": "**原因说明：** 图片分辨率不在支持的范围内。\n\n**解决方案：**\na. 调整图片分辨率到合适的范围\nb. 重新上传调整后的图片",
+  "图片尺寸必须在384到5000像素之间": "**原因说明：** 图片的宽或高尺寸不在 384 到 5000 像素的范围内。\n\n**解决方案：**\na. 使用图片编辑工具调整图片尺寸\nb. 确保宽和高都在 384 到 5000 像素之间",
+  "文字超过限制，请缩短文本内容": "**原因说明：** 输入的文本内容长度超过了音频生成的处理上限。\n\n**解决方案：**\na. 缩短输入的文本内容\nb. 将长文本拆分为多段分别生成",
+  "视频分辨率和时长不匹配，请调整后重试": "**原因说明：** 视频文件的分辨率和时长组合超出了处理能力。\n\n**解决方案：**\na. 降低视频分辨率或缩短视频时长\nb. 压缩视频文件后重试",
+  "文档不存在或没有权限，请检查后重试": "**原因说明：** 引用的文档不存在或当前用户没有访问权限。\n\n**解决方案：**\na. 确认引用的文档仍然存在\nb. 确认你对该文档有查看权限\nc. 联系文档所有者授予权限",
+  "文件类型不支持": "**原因说明：** 当前字段模板不支持该文件类型。\n\n**解决方案：**\na. 查看字段模板支持的文件类型列表\nb. 将文件转换为支持的格式后重新上传",
+  "文件大小超出限制": "**原因说明：** 文件大小超过了字段模板的处理上限。\n\n**解决方案：**\na. 压缩文件或拆分为更小的文件\nb. 确保文件大小在限制范围内",
+  "文件页数超出限制": "**原因说明：** 文件页数超过了字段模板的处理上限。\n\n**解决方案：**\na. 减少文件页数后重试\nb. 将文件拆分为多个较小的文件分别处理",
+  "文件内容为空": "**原因说明：** 引用的文件内容为空，无法进行处理。\n\n**解决方案：**\na. 确认文件内容不为空\nb. 重新上传包含内容的文件",
+  "音频文件解码失败，请检查文件格式": "**原因说明：** 音频文件无法正常解码，可能是文件格式不标准或文件损坏。\n\n**解决方案：**\na. 检查音频文件格式是否正确\nb. 尝试使用音频编辑工具重新编码后上传\nc. 更换为其他格式的音频文件",
+  "音频文件采样率不符合要求": "**原因说明：** 音频文件的采样率不在支持的范围内。\n\n**解决方案：**\na. 使用音频编辑工具转换采样率\nb. 重新上传符合要求的音频文件",
+  "音频文件过长，请缩短音频时长": "**原因说明：** 音频文件时长超过了处理上限。\n\n**解决方案：**\na. 裁剪音频文件，确保时长在限制范围内\nb. 将长音频拆分为多段分别处理",
+  "音频有效时长过短": "**原因说明：** 音频文件的有效时长过短，无法进行处理。\n\n**解决方案：**\na. 使用更长的音频文件\nb. 确保音频中包含足够的有效内容",
+  "文件加密或损坏，请检查后重试": "**原因说明：** 文件被加密保护或文件已损坏，无法正常读取。\n\n**解决方案：**\na. 解除文件的加密保护\nb. 重新获取未损坏的文件\nc. 尝试用其他工具打开文件确认是否可正常读取",
+  "视频时长超出限制，请缩短视频后重试": "**原因说明：** 视频文件时长超过了字段模板的最大处理限制。\n\n**解决方案：**\na. 裁剪视频，确保时长在限制范围内\nb. 将长视频拆分为多段分别处理",
+  "因运单号无效或缺失查询信息，暂时无法查询相关物流信息，暂不支持国际物流，如运单号存在，可以去菜鸟裹裹平台查询是否存在物流信息": "**原因说明：** 物流字段受限于底层物流查询服务（菜鸟物流），不保证百分百稳定和准确，所以可能会出现不支持或者查不到的情况。\n\n**解决方案：**\n1. 顺丰要手机号\n2. 海外快递不支持\n3. 查询可能有延迟，部分快递刷新不及时，可以稍后重试\n4. 极兔基本不能支持\n5. 韵达查询经常失败，可以闲时再试\n6. 非淘天的包裹都有可能失败\n7. 能不能查到可以去菜鸟裹裹平台确认一下",
+  "因运单号无效或缺失查询信息，暂时无法查询相关物流信息，暂不支持国际物流，顺丰需要添加手机号，如运单号存在，可以去菜鸟裹裹平台查询是否存在物流信息": "**原因说明：** 物流字段受限于底层物流查询服务（菜鸟物流），不保证百分百稳定和准确，所以可能会出现不支持或者查不到的情况。\n\n**解决方案：**\n1. 顺丰要手机号\n2. 海外快递不支持\n3. 查询可能有延迟，部分快递刷新不及时，可以稍后重试\n4. 极兔基本不能支持\n5. 韵达查询经常失败，可以闲时再试\n6. 非淘天的包裹都有可能失败\n7. 能不能查到可以去菜鸟裹裹平台确认一下",
+  "引用的字段中没有找到图片，AI无法为你生成内容": "**原因说明：** 当前使用的 AI 字段需要引用合法的图片才能使用。\n\n**解决方案：**\n1. 修改 AI 字段配置，正确引用合法图片",
+  "引用字段不是链接类型或链接字段为空": "**原因说明：** AI 链接阅读字段引用的字段不是链类型，或者链接字段的值为空。\n\n**解决方案：**\na. 检查字段模板配置，确保引用的字段是链接类型\nb. 确认链接字段中有有效的链接内容\nc. 如果链接字段为空，请先填写链接后重试",
+  "没有权限访问钉钉文档": "**原因说明：** AI 链接阅读字段引用的钉钉文档，当前用户没有访问权限。\n\n**解决方案：**\na. 确认你对引用的钉钉文档有查看权限\nb. 联系文档所有者授予权限后重试",
+  "不支持的钉钉文档类型": "**原因说明：** AI 链接阅读字段引用的钉钉文档类型不被支持（如钉钉表格）。\n\n**解决方案：**\na. 当前仅支持钉钉文档（adoc），不支持钉钉表格（axls、able）\nb. 请更换为支持的文档类型后重试",
+  "引用字段内容为空或配置错误": "**原因说明：** AI 字段配置中引用的字段内容为空，或者字段配置不正确。\n\n**解决方案：**\na. 检查引用字段是否有内容\nb. 确认字段模板配置中的引用字段设置正确\nc. 如果是自定义提示词为空，请填写提示词内容",
+  "AI 返回结果类型不符合预期": "**原因说明：** AI 返回的结果无法转换为目标字段类型（如数字、金额、图片等）。\n\n**解决方案：**\na. 检查提示词是否明确要求 AI 返回特定格式的内容\nb. 调整提示词，使其更明确地指导 AI 生成符合要求的结果\nc. 如果是数字字段，确保 AI 返回的是纯数字\nd. 如果是图片字段，确保 AI 能够生成有效的图片资源",
+  "岗位描述为空": "**原因说明：** AI 招聘字段中的岗位描述字段为空，无法进行候选人匹配分析。\n\n**解决方案：**\na. 在岗位描述字段中填写详细的岗位要求\nb. 确保岗位描述包含关键信息（如技能要求、工作经验等）",
+  "视频文件无效或格式不支持": "**原因说明：** AI 视频理解字段引用的文件不是有效的视频文件，或视频格式不被支持。\n\n**解决方案：**\na. 确认上传的文件是视频文件\nb. 检查视频格式是否在支持列表中（mp4、mov、mkv、avi、wmv、rmvb、asf、asx、3gp、m4v、flv、vob、webm、mpg、mts）\nc. 如果格式不支持，请转换为支持的格式后重新上传",
+  "音频文件格式不支持": "**原因说明：** AI 音频转写字段引用的音频文件格式不被支持。\n\n**解决方案：**\na. 检查音频文件格式是否在支持列表中\nb. 对于 AI 音频转写（通用）：支持 mp3、amr、wav、3gp、3gpp、aac、mp4、avi、mkv、mov、flv、wmv 格式\nc. 对于 AI 音频转写（中文）：支持 aac、amr、avi、flac、flv、m4a、wav、mkv、mov、mp3、mp4、mpeg、ogg、opus、webm、wma、wmv 格式\nd. 将音频文件转换为支持的格式后重新上传",
+  "网络连接失败，请确保链接是公网可访问的有效地址": "**原因说明：** AI 链接阅读字段引用的链接无法访问，可能是内网地址或链接已失效。\n\n**解决方案：**\na. 确认链接是公网可访问的有效地址\nb. 在浏览器中测试链接是否能正常打开\nc. 如果是内网地址，请更换为公网可访问的链接",
+  "Coze 请求失败": "**原因说明：** AI 字段调用 Coze 工作流时请求失败，通常是 Coze 侧的配置问题，与 AI 字段本身无关。\n\n**排查方式：**\n请先查看报错信息中的「业务信息」部分（cozeErrorCode 和 cozeErrorMsg），里面包含了 Coze 返回的具体错误原因，大部分情况下看这个就能定位问题。\n\n**解决方案：**\na. 根据业务信息中的错误提示，检查 Coze 工作流的对应配置\nb. 在 Coze 平台的 Playground 中直接测试工作流，确认是否正常\nc. 如果 Playground 正常但 AI 字段调用失败，可以直接调用 Coze API 接口（https://api.coze.cn/v1/workflow/run）验证\nd. 检查 Coze 工作流中各节点的参数配置，确保请求参数和端点配置正确"
+}

package/templates/aitable-handoff/workflows/group-qa/recipes/answer.recipe.ts

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import type { RecipeDefinition, RecipeContext, RecipeResult } from "aitable-workflow-core";
+import { HANDOFF_MEMORY_KINDS, HANDOFF_MEMORY_ROLES, handoffEntry, handoffScope } from "./memory-events.js";
+
+/**
+ * 单 agent 应答（对齐 conversation-handoff 的 answerWithAgent）
+ *
+ * 不走独立 LLM 分类：一次 coding.run 让 agent 自己依据注入的知识库(直读原文) + 近期对话上下文，
+ * 按 AGENTS.md 契约返回严格 JSON：{ shouldReply, noReplyReason, reply }
+ * - shouldReply=true：依据 KB 作答，reply 为面向用户正文；
+ * - shouldReply=false：闲聊/收到/谢谢/同事已接手/自指元问题/文档未覆盖 → 静默（noReplyReason 记原因）。
+ *
+ * 命中已知错误或问题排查（由上游 Recipe 设置消息分类）时直接跳过。
+ * 注：管理员知识更新已拆到独立 workflow（admin-kb-update），本流不再判定「知识补充」。
+ */
+
+type AgentDecision = {
+  shouldReply?: boolean;
+  noReplyReason?: string;
+  reply?: string;
+};
+
+/** 从 agent 自由文本中稳健提取 JSON 对象；失败返回 null */
+function extractDecision(raw: string): AgentDecision | 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 === -1 || end <= start) return null;
+  try {
+    return JSON.parse(s.slice(start, end + 1)) as AgentDecision;
+  } catch {
+    return null;
+  }
+}
+
+const recipe: RecipeDefinition = {
+  meta: {
+    id: "answer",
+    name: "单 agent 应答",
+    role: "faq-support",
+    description: "一次 agent 调用决定 回复/类别/原因，并给出面向用户的回答",
+    version: "1.0.0",
+    requiresAgent: true,
+    timeoutMs: 180_000,
+    config: z.object({
+      coding: z.object({ engine: z.string().optional() }).optional(),
+    }),
+  },
+
+  async execute(ctx: RecipeContext): Promise<RecipeResult> {
+    const { input, toolkit, log } = ctx;
+    const content = String(input.content ?? "");
+    const context = String(input.context ?? "").trim();
+    const senderName = String(input.senderName ?? "").trim();
+    const preset = String(input.message_category ?? "").trim();
+    const conversationId = String(input.conversationId ?? "").trim();
+
+    // 上游 Recipe 已经完成处理 → 透传，不再起普通答疑 agent
+    if (preset === "已知错误" || preset === "问题排查") {
+      log(`${preset}已由上游 Recipe 处理，answer 跳过`);
+      // 建行与否由上游 known_error_match(命中→建行) 决定，本步透传不额外留痕
+      return { status: "success", output: {}, tracker: false, logs: [`透传：${preset}`] };
+    }
+
+    if (!content.trim()) {
+      // 静默(空消息) → on_demand 下不建行
+      return {
+        status: "success",
+        output: { message_category: "静默", answer: "" },
+        tracker: false,
+        logs: ["空消息 → 静默"],
+      };
+    }
+
+    const roleId = ctx.roleContext?.id?.trim() || "faq-support";
+    const workDir = path.resolve(ctx.configDir, "workspaces", roleId);
+
+    let memSection = "";
+    try {
+      const longTerm = await toolkit.memory.readLongTerm(handoffScope()).catch(() => "");
+      if (longTerm && longTerm.trim()) {
+        fs.mkdirSync(workDir, { recursive: true });
+        fs.writeFileSync(path.join(workDir, ".long-term.md"), longTerm, "utf8");
+        memSection = `\n## 长期记忆（可用，仅作辅助上下文，不作事实依据）
+- 近期群聊复盘沉淀的高频问题与趋势已写入工作目录下的 .long-term.md，可按需 Read/Grep 搜索以理解语境；一切事实依据仍只能来自知识库，不得据此作答。\n`;
+        log(`已写入长期记忆到 ${path.join(workDir, ".long-term.md")} (${longTerm.length} 字符)，agent 可 Read/Grep 搜索`);
+      }
+    } catch (err) {
+      log(`写入长期记忆失败(不影响主流程): ${err}`);
+    }
+
+    // 消息含内联图片（download 模式已把群图片落地为 ![图片](本地路径)）时，
+    // 明确要求 agent 先 Read 看图并结合图片内容理解用户真实问题。
+    const hasImage = /!\[图片\]\([^)]+\)/.test(content);
+    const imageNote = hasImage
+      ? "\n**本条消息包含图片**（已内联为 `![图片](路径)`）：请先用 Read 打开该图片，结合图片内容（多为报错截图/操作截图）理解用户的真实问题后再作答。\n"
+      : "";
+
+    const prompt = `开始处理前，必须先使用 Read 读取并完整遵循本工作目录下的 AGENTS.md，将其作为本次答疑的完整业务执行规范。
+如果 AGENTS.md 的路由规则要求读取某个 skills/*/SKILL.md，必须先读取并完整遵循对应 Skill，再继续检索文档和组织回答；不得跳过 Skill 路由。
+
+用户在钉钉群中提出了以下问题，请基于本工作目录 help-center/ 下的官方帮助文档为用户提供准确、详细的解答。
+
+在对话历史中，标记为"(答疑机器人/即你自己之前的回复)"的消息就是你之前发出的回复。
+${memSection}
+**输出格式（严格要求）**：
+你的最终输出必须是一个合法 JSON 对象，包含以下字段：
+- shouldReply (boolean)：是否需要回复用户。非有效提问（收到/谢谢/闲聊等）或真人同事已介入时为 false
+- noReplyReason (string，仅 shouldReply=false 时必填)：不回复的原因简述（供日志审计）
+- reply (string，仅 shouldReply=true 时必填)：要发送给用户的 markdown 正文（含 Hi 开头、出处链接等所有可见内容）
+整体输出首字符必须是 '{'，末字符必须是 '}'，禁止任何前后缀解释文字、禁止代码块包裹。
+
+reply 是直接发送给群用户的最终话术，不是排查报告。Skill 的步骤输出、日志证据、工具调用和代码定位只用于内部推理，禁止出现在 reply 中。reply 只保留业务化的简短结论，以及用户确实需要执行的最少操作；不得包含源码/类名/方法名/文件路径、内部服务调用链、内部字段 ID、内部错误码映射过程或责任归属判断，也不要使用“根因分析”“错误链路”“建议用户操作”等内部分析标题。
+
+示例（仅用于说明格式，内容请按用户的真实问题作答）：
+{"shouldReply":true,"reply":"Hi 小明，AI 表格支持最大 20 万行。\\n\\n> 来源:https://wolai.dingtalk.com/xxx"}
+{"shouldReply":false,"noReplyReason":"用户表示感谢，非有效提问"}
+
+要求：
+1. 当你在 reply 中提及来源或引用文档时，出处取该文章 frontmatter 里 original_sources 字段的在线链接（格式为 > 来源:https://wolai.dingtalk.com/...）；frontmatter 的 sources 是本地文件路径，严禁作为出处或出现在 reply 中。
+2. reply 开头先用「Hi ${senderName || "用户"}，」打招呼，然后直接给出解答内容，不要以「您好！关于您提到的……」之类的寒暄复述。
+${context ? `\n以下是群聊中近期的对话历史（帮助你理解用户当前问题的上下文，如追问、反馈、是否已被同事接手）：\n---\n${context}\n---\n` : ""}
+${imageNote}用户问题（发送者：${senderName || "未知"}）：
+${content}`;
+
+    // 执行 workspace（含 AGENTS.md + 注入的知识库(wiki 符号链接) + 本次写入的 .long-term.md）与 coding toolkit 默认一致。
+    log(`answer prompt 就绪（workDir=${workDir}）: ${content.slice(0, 60)}`);
+    const result = await toolkit.coding.run(prompt, { workDir });
+
+    if (!result.response) {
+      log("coding agent 未产出有效响应，兜底静默");
+      return {
+        status: "success",
+        output: { message_category: "静默", answer: "", reason: "agent 无有效响应，兜底静默" },
+        tracker: false, // 静默 → on_demand 下不建行
+        logs: ["agent 失败 → 静默"],
+      };
+    }
+
+    const decision = extractDecision(result.response);
+    if (!decision || typeof decision.shouldReply !== "boolean") {
+      log("JSON 解析失败，兜底静默");
+      return {
+        status: "success",
+        output: { message_category: "静默", answer: "", reason: "JSON 解析失败，兜底静默" },
+        tracker: false, // 静默 → on_demand 下不建行
+        logs: ["解析失败 → 静默", `原始: ${result.response.slice(0, 120)}`],
+      };
+    }
+
+    // handoff 契约 {shouldReply, noReplyReason, reply} → 派生本流输出键（message_category/reason/answer）
+    const shouldReply = decision.shouldReply === true;
+    const category = shouldReply ? "技术问答" : "静默";
+    const reason = String(decision.noReplyReason ?? "");
+    const reply = String(decision.reply ?? "");
+
+    const output: Record<string, unknown> = {
+      message_category: category,
+      reason,
+      answer: shouldReply ? reply : "",
+    };
+
+    // ─── 记忆叠加：追加 agent_decision 记忆（fire-and-forget） ───
+    // 真正的已发送事件由 reply-to-group 在发送成功后写入，避免发送失败也被统计为 answered。
+    if (conversationId) {
+      void toolkit.memory.append(
+        handoffScope(conversationId),
+        handoffEntry({
+          kind: HANDOFF_MEMORY_KINDS.agentDecision,
+          content: shouldReply ? reply.slice(0, 200) : "(静默)",
+          sender: "agent",
+          role: HANDOFF_MEMORY_ROLES.agent,
+          conversationId,
+          summary: `答疑机器人决策: ${category}${shouldReply ? ` - ${reply.slice(0, 80)}` : ` - ${reason}`}`,
+          meta: { shouldReply, reason },
+        }),
+      ).catch((err) => log(`memory.append(agent_decision) 失败(不影响主流程): ${err}`));
+    }
+
+    log(`分类=${category}（${reason || "无理由"}），shouldReply=${shouldReply}`);
+    // 技术问答且有正文 → 建行留痕；静默(answer 为空) → on_demand 下不建行
+    const willReply = Boolean(String(output.answer ?? "").trim());
+    return {
+      status: "success",
+      output,
+      ...(willReply ? {} : { tracker: false }),
+      logs: [`分类 ${category}`, reason ? `理由: ${reason}` : ""].filter(Boolean),
+    };
+  },
+};
+
+export default recipe;

package/templates/aitable-handoff/workflows/group-qa/recipes/conversation_handler.recipe.ts

@@ -0,0 +1,294 @@
+import type {
+  EventContext,
+  EventHandlerRecipeDefinition,
+  HandlerInitContext,
+  HandlerInstance,
+} from "aitable-workflow-core";
+import {
+  resolveDingTalkStreamMessageEventContext,
+  resolveDingTalkWebhookMentionEventContext,
+  resolveGlobalVarRef,
+} from "aitable-workflow-core";
+import { HANDOFF_MEMORY_KINDS, HANDOFF_MEMORY_ROLES, handoffEntry, handoffScope } from "./memory-events.js";
+import { z } from "zod";
+
+/**
+ * 会话消息处理器（合并版 + 近期对话上下文）
+ *
+ * 事件源只产出统一的 message_received。本 handler 是长活单例：
+ *   - onEvent 纯同步（无长 await）：摄入本轮消息 + 从内存历史构建「近期对话上下文」+ pushEvent 建单。
+ *   - 内存里按 conversationId 维护近期消息环形缓冲（容量/TTL 限制，重启清空，语义对齐 CH recentHistory）。
+ *
+ * 名单来源（均来自 handler_config，ctx.config，值由 config-sync 发布到 globalVar）：
+ *   - groups_var   → 群配置 globalVar（默认 group_configs，形如 [{groupId, botNick}]）：读每群机器人身份
+ *                    （按 botNick 花名匹配）；机器人自身消息只记历史不建单，
+ *                    历史标记 (答疑机器人/即你自己之前的回复)
+ *   - admins_var   → 真人同事/管理员名单 globalVar（默认 admins，形如
+ *                    [{nick, openDingTalkId}]）：openDingTalkId 优先按 ID 匹配，nick 花名兜底；历史标记 (真人同事)
+ *   - 其他         → 无标记（普通用户）
+ * 供 answer agent 判断「追问 / 同事已接手」、理解指代。
+ *
+ * 匹配策略：群消息里花名(sender)并不唯一、可能重名或被改，openDingTalkId 才稳定唯一。
+ * 因此统一「先按 openDingTalkId 精确匹配，匹配不到再用花名兜底」。
+ *
+ * 图片已由基建内联进 content（`![图片](本地路径)`），无需单独字段：content 直接带图。
+ */
+
+const HISTORY_CAPACITY = 20;
+const HISTORY_TTL_MS = 30 * 60 * 1000;
+const IMAGE_MARK = "![图片]";
+const CONFIG_CACHE_TTL_MS = 30 * 1000;
+
+type HistoryEntry = { sender: string; openId: string; content: string; ts: number };
+/** 一组身份匹配集合：openDingTalkId 精确集 + 花名兜底集 */
+type IdentitySets = { ids: Set<string>; nicks: Set<string> };
+type GroupRuntimeConfig = {
+  identity: IdentitySets;
+  inbound: string;
+  outbound: string;
+  credRef: string;
+};
+
+function parseNicks(raw: unknown): Set<string> {
+  const arr = Array.isArray(raw) ? raw.map(String) : String(raw ?? "").split(/[,，]/);
+  return new Set(arr.map((s) => s.trim()).filter(Boolean));
+}
+
+/** 先按 openDingTalkId 精确匹配，匹配不到再用花名兜底 */
+function matchesIdentity(sets: IdentitySets, sender: string, openId: string): boolean {
+  if (openId && sets.ids.has(openId)) return true;
+  return !!sender && sets.nicks.has(sender);
+}
+
+/**
+ * 从 globalVar 群配置数组（形如 [{groupId, botNick}]，由 config-sync 发布）读每群机器人身份。
+ * 非数组/空 → 空 Map。
+ */
+function loadGroupBots(list: unknown): Map<string, GroupRuntimeConfig> {
+  const map = new Map<string, GroupRuntimeConfig>();
+  for (const g of Array.isArray(list) ? list : []) {
+    if (!g || typeof g !== "object") continue;
+    const rec = g as Record<string, unknown>;
+    const gid = String(rec.groupId ?? "").trim();
+    if (gid) {
+      map.set(gid, {
+        identity: { ids: new Set(), nicks: parseNicks(rec.botNick) },
+        inbound: String(rec.inbound ?? "").trim(),
+        outbound: String(rec.outbound ?? "").trim(),
+        credRef: String(rec.credRef ?? "").trim(),
+      });
+    }
+  }
+  return map;
+}
+
+/**
+ * 从 globalVar 管理员名单读身份集；内容为 [{nick, openDingTalkId}]、[{nick}] 或 ["花名"]。
+ * 非数组/空 → 空集。
+ */
+function loadAdmins(list: unknown): IdentitySets {
+  const ids = new Set<string>();
+  const nicks = new Set<string>();
+  for (const e of Array.isArray(list) ? list : []) {
+    if (typeof e === "string") {
+      const nick = e.trim();
+      if (nick) nicks.add(nick);
+    } else if (e && typeof e === "object") {
+      const rec = e as Record<string, unknown>;
+      const nick = String(rec.nick ?? "").trim();
+      const openId = String(rec.openDingTalkId ?? "").trim();
+      if (nick) nicks.add(nick);
+      if (openId) ids.add(openId);
+    }
+  }
+  return { ids, nicks };
+}
+
+function roleTag(sender: string, openId: string, botSets: IdentitySets, adminSets: IdentitySets): string {
+  if (matchesIdentity(botSets, sender, openId)) return "(答疑机器人/即你自己之前的回复)";
+  if (matchesIdentity(adminSets, sender, openId)) return "(真人同事)";
+  return "";
+}
+
+/**
+ * TTL 懒加载缓存：首次或到期后重新执行 loader，未到期复用上次结果。
+ * 把"何时刷新"的簿记收敛在函数内部，调用方只管取值。
+ */
+function ttlCached<T>(loader: () => T, ttlMs: number): () => T {
+  let cache: T | null = null;
+  let loadedAt = 0;
+  return () => {
+    const now = Date.now();
+    if (cache === null || now - loadedAt > ttlMs) {
+      cache = loader();
+      loadedAt = now;
+    }
+    return cache;
+  };
+}
+
+const recipe: EventHandlerRecipeDefinition = {
+  meta: {
+    id: "conversation_handler",
+    name: "会话消息处理器",
+    description: "message_received → 构建近期对话上下文 → 创建工单",
+    // handler_config 的 schema：供 design/sync/inspect 校验与提示如何配置
+    config: z.object({
+      conversation_ids: z
+        .string()
+        .optional()
+        .describe("群配置来源（引用 config-sync 发布的 globalVar，默认 ${globalVar.group_configs}，形如 [{groupId, botNick}]）：读取每群机器人身份（按 botNick 花名匹配），机器人自身消息只记历史不建单，历史标记 (答疑机器人/即你自己之前的回复)"),
+      admins: z
+        .string()
+        .optional()
+        .describe("真人同事名单来源（引用 globalVar，默认 ${globalVar.admins}，形如 [{nick, openDingTalkId}] 或 [\"花名\"]）：openDingTalkId 优先按 ID 匹配、nick 花名兜底，在对话上下文标记为(真人同事)，供判断是否已被接手"),
+    }),
+  },
+
+  create(ctx: HandlerInitContext): HandlerInstance {
+    const histories = new Map<string, HistoryEntry[]>();
+    const emptySets: IdentitySets = { ids: new Set(), nicks: new Set() };
+    // 与事件源同源，均为 globalVar 引用（默认 group_configs / admins）；运行期活读。
+    const groupsRef = String(ctx.config.conversation_ids ?? "${globalVar.group_configs}");
+    const adminsRef = String(ctx.config.admins ?? "${globalVar.admins}");
+    // 用 TTL 懒刷新避免每事件重建 Set。
+    const getAdmins = ttlCached(
+      () => loadAdmins(resolveGlobalVarRef(adminsRef, ctx.getGlobalVar)),
+      CONFIG_CACHE_TTL_MS,
+    );
+    const getGroupBots = ttlCached(
+      () => loadGroupBots(resolveGlobalVarRef(groupsRef, ctx.getGlobalVar)),
+      CONFIG_CACHE_TTL_MS,
+    );
+
+    return {
+      onEvent(event) {
+        const payload = event.payload;
+        const content = String(payload.content ?? "");
+        const hasImage = content.includes(IMAGE_MARK);
+        if (!content.trim() && !hasImage) {
+          ctx.log("消息内容为空且无图片，跳过(不 push)");
+          return;
+        }
+
+        const senderName = String(payload.senderName ?? payload.sender ?? payload.firstSender ?? "");
+        const senderOpenId = String(payload.senderOpenDingTalkId ?? "").trim();
+        const messageId = String(payload.messageId ?? "");
+        const sendTime = String(payload.firstSendTime ?? new Date().toISOString());
+        const conversationId = String(payload.conversationId ?? "");
+        const now = Date.parse(sendTime) || Date.now();
+        const adminSets = getAdmins();
+        const groupConfig = getGroupBots().get(conversationId);
+        const botSets = groupConfig?.identity ?? emptySets;
+        const isBot = matchesIdentity(botSets, senderName, senderOpenId);
+        const isAdmin = matchesIdentity(adminSets, senderName, senderOpenId);
+
+        // 1) 取该群历史，裁剪过期，构建「当前之前」的对话上下文（带角色标记）
+        const prior = (histories.get(conversationId) ?? []).filter((e) => now - e.ts <= HISTORY_TTL_MS);
+        const contextText =
+          prior.length > 0
+            ? [
+                "以下是群聊中近期的对话历史(帮助理解当前问题的上下文，如追问、反馈、是否已被同事接手):",
+                "---",
+                ...prior.map((e, i) => `[历史消息 ${i + 1}] ${e.sender}${roleTag(e.sender, e.openId, botSets, adminSets)}: ${e.content}`),
+                "---",
+              ].join("\n")
+            : "";
+
+        // 2) 追加当前消息到历史并按容量裁剪（机器人消息也入历史，作为后续上下文/角色标记）
+        prior.push({ sender: senderName, openId: senderOpenId, content, ts: now });
+        while (prior.length > HISTORY_CAPACITY) prior.shift();
+        histories.set(conversationId, prior);
+
+        // 机器人自己的消息只记录进历史，不建工单（不 push = skip）
+        if (isBot) {
+          ctx.log(`机器人消息，仅记录进历史不建单: ${senderName}`);
+          return;
+        }
+
+        // 真人同事/管理员自己发的消息：仅记录进历史（供后续用户提问时标注"同事已接手"上下文），不建单不回复
+        if (isAdmin) {
+          ctx.log(`真人同事消息，仅记录进历史不建单: ${senderName}`);
+          return;
+        }
+
+        ctx.log(`处理群消息: 来自 ${senderName}${hasImage ? "(含图片)" : ""}, 历史 ${prior.length - 1} 条`);
+
+        const dingtalk = payload.dingtalk && typeof payload.dingtalk === "object"
+          ? payload.dingtalk as Record<string, unknown>
+          : undefined;
+        // 事件上下文只携带 Stream 原始标识；校验完整性和群配置匹配后再交给消费者组装运行状态。
+        let eventContext: EventContext | undefined;
+        if (groupConfig?.inbound === "stream" && groupConfig.outbound === "session") {
+          if (!groupConfig.credRef) {
+            ctx.log("跳过处理态表情: stream + session 群配置缺少 credRef");
+          } else if (!dingtalk) {
+            ctx.log("跳过处理态表情: payload.dingtalk 缺失");
+          } else {
+            const resolvedContext = resolveDingTalkStreamMessageEventContext({
+              type: "dingtalk_stream_message",
+              openMsgId: dingtalk.openMsgId,
+              conversationId: dingtalk.conversationId,
+              robotCode: dingtalk.robotCode,
+              credRef: dingtalk.credRef,
+            });
+            if (!resolvedContext) {
+              ctx.log("跳过处理态表情: payload.dingtalk 缺少 openMsgId/conversationId/robotCode/credRef");
+            } else if (groupConfig.credRef !== resolvedContext.credRef) {
+              ctx.log("跳过处理态表情: 群配置 credRef 与入站 credRef 不匹配");
+            } else if (resolvedContext.conversationId !== conversationId) {
+              ctx.log("跳过处理态表情: 入站 conversationId 与消息 conversationId 不匹配");
+            } else {
+              eventContext = {
+                ...resolvedContext,
+                conversationId,
+              };
+            }
+          }
+        } else if (groupConfig?.outbound === "webhook") {
+          // 自定义机器人 Webhook 的 @人身份只跟随本次瞬态 WorkItem，不写入 Tracker。
+          // 任一字段缺失时不附加上下文，消费端会正常发送但不 @ 人。
+          eventContext = resolveDingTalkWebhookMentionEventContext({
+            type: "dingtalk_webhook_mention",
+            conversationId,
+            senderOpenDingTalkId: senderOpenId,
+            senderName,
+          });
+        }
+        if (eventContext?.type === "dingtalk_stream_message") {
+          ctx.toolkit.messaging?.beginDingTalkProcessingFeedback?.(eventContext);
+        }
+
+        ctx.pushEvent({
+          action: "create_record",
+          fields: {
+            "消息内容": content,
+            "发送人": senderName,
+            "发送时间": sendTime,
+            "群ID": conversationId,
+            "对话上下文": contextText,
+          },
+          ...(eventContext ? { eventContext } : {}),
+        });
+
+        // ─── 记忆叠加：追加短期记忆（fire-and-forget，不阻塞 onEvent） ───
+        // 走到这里必是普通用户消息（机器人/真人同事已在上方提前返回），故固定 user 角色。
+        // 短期记忆按群隔离（含 conversationId），daily-review 按群读取后压缩为共享长期记忆
+        void ctx.toolkit.memory.append(handoffScope(conversationId), handoffEntry({
+          timestamp: sendTime,
+          kind: HANDOFF_MEMORY_KINDS.userMessage,
+          content,
+          sender: senderName,
+          role: HANDOFF_MEMORY_ROLES.user,
+          conversationId,
+          meta: { messageId, hasImage },
+        })).catch((err) => ctx.log(`memory.append 失败(不影响主流程): ${err}`));
+      },
+      stop() {
+        histories.clear();
+      },
+    };
+  },
+};
+
+export default recipe;