@fx-data/ai-diagnostics 0.1.20261109015953 → 0.1.20261111014808

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261109015953`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261111014808`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
 
 用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
 

package/README.md

@@ -38,4 +38,4 @@
 
 ---
 
-**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261109015953/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。
+**给 Agent：** 按 [Agent 执行说明](https://unpkg.com/@fx-data/ai-diagnostics@0.1.20261111014808/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。

package/content/AGENTS.md

@@ -30,6 +30,7 @@
 | 慢、超时、卡顿、内存超限、OOM、`MemoryLimitExceeded`、资源消耗异常、性能退化或回归 | [性能排查入口](knowledge/common/workflow.md)，再按场景进入对应知识域 |
 | 只想拿到或看懂一份 engine metric | [引擎知识](knowledge/engine/workflow.md) |
 | 只想弄清更新来源、request、chain/DAG、node attempt、requeue、load、listener、engine task，或核对更新计数 | [更新知识 · 解释更新记录](knowledge/update/workflow.md#解释更新记录) |
+| 自动化有没有跑、为什么没触发、通知没收到、回填失败，或给了 workflowId 查执行情况 | [自动化知识](knowledge/automation/workflow.md) |
 | 只想配置诊断环境，或实时查询被工具、连接问题挡住 | [配置 SigNoZ MCP](knowledge/common/topics/setup-signoz-mcp.md)，弄好后回到原问题 |
 | 其他问题：非性能报错、结果异常、稳定性问题 | 有报错原文就先查[信号索引 · 常见报错](knowledge/signal-index.md#常见报错)；没有专门入口，先说明这块覆盖有限，再按[问题定位方法](docs/architecture.md)结合已有材料分析 |
 
@@ -46,7 +47,7 @@
 
 ### 查找知识
 
-知识按域分（common、dataset、component、dashboard、update、engine），每个域的文件名都一样，完整说明见[知识目录](knowledge/README.md)：
+知识按域分（common、dataset、component、dashboard、update、engine、automation），每个域的文件名都一样，完整说明见[知识目录](knowledge/README.md)：
 
 1. **先认场景**：场景明确就直接进；不明确先看[场景识别](knowledge/common/signals.md)。第一次进某个域，先扫一眼它的 `workflow.md`，里面是从哪下手、常见现象和容易踩的坑。
 2. **按名称查**：手上有 span、属性、日志名或报错原文，查[信号索引](knowledge/signal-index.md)，它直接指到含义所在的章节；查完回到场景接着找原因。

package/content/README.md

@@ -10,6 +10,7 @@
 | 组件或仪表板加载慢 | 查询条件、筛选、参数、联动与组件取数 |
 | 更新慢、超时、内存超限 | 调度等待、依赖、计算、写入与重试 |
 | 更新来源或数量不清楚 | 触发来源、更新链路、节点与尝试次数 |
+| 自动化没触发、通知没收到或回填失败 | 按 workflowId 核对每次执行、跳过原因、动作结果与回填进度 |
 | 其他报错、结果异常或偶发不可用 | 核对现象与执行记录，整理已确认事实和待验证问题 |
 
 性能问题已有各场景的知识和入口提示。其他问题先根据现有材料辅助分析。
@@ -34,6 +35,8 @@ npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是
 
 > 客户怀疑重复更新，请根据这些日志区分更新请求、节点和重试次数。
 
+> 帮我看下 workflowId=xxx 这个自动化最近的执行情况，客户说昨晚没收到通知。
+
 已有材料可以直接交给助手：
 
 - 没说环境时默认查正式环境。

package/content/docs/index.md

@@ -40,6 +40,8 @@
 | 按输入选择更新取证配方 | [更新 · 选哪个配方](../knowledge/update/queries.md#选哪个配方) |
 | 更新的计数单位 / 允许的关联边 | [更新 · 计数单位与身份](../knowledge/update/concepts.md#计数单位与身份)、[关联边](../knowledge/update/topics/correlations.md#关联边) |
 | 更新记录的计数对账、判断矩阵与停止规则 | [更新 · 能下什么结论](../knowledge/update/conclusions.md) |
+| 按 workflowId 查自动化执行情况 | [自动化 · 按 workflowId 查](../knowledge/automation/queries.md#按-workflowid-查) |
+| 自动化的 `success=true` 能说明到哪、查不到记录时能说什么 | [自动化 · 能下什么结论](../knowledge/automation/conclusions.md) |
 | 答复格式、原因链展开、正文与附件分工、可执行排查方向 | [诊断结果交付](diagnostic-report.md) |
 | 交接研发的材料 | [诊断结果交付 · 交接研发](diagnostic-report.md#交接研发) |
 | 诊断后的需求反馈 | [需求反馈](diagnostic-feedback.md) |

package/content/docs/scenario-guide.md

@@ -53,6 +53,18 @@
 
 节点成功不一定发生了数据加载，也不等于整次更新完成；写没写进去看对应的完成记录。交付时说清时间或失败集中在哪个阶段、哪些关联已确认，缺哪段就说缺哪段，不按同表名或时间接近拼流程。
 
+## 自动化
+
+先用 workflowId 列出时间范围内的每次执行，再选要看的那次。按下面的过程找到断在哪一步，记录里没有的阶段不补：
+
+```text
+触发 → 前置检查和条件判断 → 动作执行 → 外部投递或回填写入
+```
+
+- 没执行：分清是调度没触发、条件没命中，还是前置检查报错。条件没命中不是故障。
+- 显示成功但没收到：成功只说明派发走完了，通知要看发送记录，回填要看后面的写入结果。
+- 交付：执行了几次、各成功失败多少、断在哪一步，能确认到“已发出”就不说“已送达”。细节见[自动化知识](../knowledge/automation/workflow.md)。
+
 ## 解释更新记录
 
 用户问“为什么有这么多次更新”，先确认在数什么：

package/content/knowledge/README.md

@@ -44,6 +44,7 @@
 | [dashboard](dashboard/README.md) | 仪表板 2.0的筛选器候选值与组件计算 | [排查入口](dashboard/workflow.md) |
 | [update](update/README.md) | 分析表更新（dispatch）：场景标签、逻辑事件、关联边、取证配方 | [解释更新记录与更新性能排查](update/workflow.md) |
 | [engine](engine/README.md) | 引擎执行统计（Metric）的获取与解读 | [排查入口](engine/workflow.md) |
+| [automation](automation/README.md) | 自动化的运行情况：定时和来源表更新触发、条件判断、通知、回填、存档 | [按 workflowId 查执行情况](automation/workflow.md) |
 | [cases](cases/README.md) | 已核实的诊断案例，只用于提出假设 | 提出候选原因前 |
 
-`cases` 是案例集，不按槽位分；其余六个域都按上面的槽位组织。
+`cases` 是案例集，不按槽位分；其余七个域都按上面的槽位组织。

package/content/knowledge/automation/README.md

@@ -0,0 +1,25 @@
+# 自动化知识
+
+自动化的运行情况：定时或来源表更新触发之后，条件判断、通知、回填、存档这些动作有没有执行，结果怎样。页面上叫“自动化”，日志和接口里叫 workflow。在 AI 对话里创建、修改自动化的过程不在本域。
+
+## 槽位
+
+每个知识域都按同样的槽位组织。按要做的事选槽位，只读命中的章节。
+
+| 要做什么 | 读 | 包含 |
+|---|---|---|
+| 这类问题从哪里入手 | [workflow.md](workflow.md) | 按 workflowId 查执行情况；常见现象的候选假设；易错点 |
+| 弄清概念是什么、怎么关联 | [concepts.md](concepts.md) | 触发方式、动作类型、各种标识、失效状态 |
+| 认出入口，看懂 span、attribute、日志和字段 | [signals.md](signals.md) | 各触发方式的日志时间线、trace 结构、跳过与失败信号、常见报错、回填的后半段 |
+| 看完日志和 trace，能下什么结论 | [conclusions.md](conclusions.md) | `success=true` 能说明到哪；查不到记录时能说什么 |
+| 写查询、选取证路径 | [queries.md](queries.md) | 按 workflowId、单次执行、失败概况的查询写法 |
+
+## 展开明细
+
+本域没有展开明细，所有内容都在上面的槽位里。
+
+## 关联
+
+- 相关知识域：[更新](../update/README.md)：来源表更新触发时，自动化跑在更新节点的同一条 trace 里
+- 相关知识域：[引擎](../engine/README.md)：条件判断和字段汇总的取数
+- 相关知识域：[通用](../common/README.md)：环境、时间和查询规则

package/content/knowledge/automation/concepts.md

@@ -0,0 +1,59 @@
+# 自动化 · 概念与关联
+
+一个自动化由“什么时候触发、满足什么条件、执行哪些动作”组成。一次执行按顺序走：触发 → 前置检查 → 条件判断 → 动作 → 结果记录。
+
+## 触发方式
+
+日志里的 `scene` 表示这次执行由什么触发。
+
+| `scene` | 页面含义 | 以谁的身份执行 | 动作并行方式 |
+|---|---|---|---|
+| `SCHEDULE` | 定时触发 | 自动化的所有者 | 一个动作顺序执行，多个动作并行 |
+| `BASE_TABLE_UPDATE` | 来源表更新后触发 | 这次更新任务的用户 | 并行 |
+| `MANUAL` | 手动触发单个动作 | 当前操作的用户 | 只有一个动作 |
+| `FILLBACK_FAILURE` | 回填最终失败后的附加通知 | 回填来源表的所有者 | 并行 |
+
+执行身份影响条件判断和字段汇总能读到的数据。回填、表存档、项目存档、飞书卡片还有各自的取数身份，以这次记录为准。
+
+同一个自动化的定时任务不会并发，上一轮没结束时下一轮会延后。
+
+## 条件判断
+
+配置了条件时，先算“来源表加上条件后有没有数据”，大于 0 行才执行动作。**条件只决定跑不跑，不筛选动作用的数据**：通知汇总、回填、存档按各自配置的表取数，可以和条件表不同。
+
+## 标识
+
+| 标识 | 是什么 | 用途 |
+|---|---|---|
+| workflowId | 自动化的稳定 ID，16 位十六进制或 UUID | 查这个自动化的全部执行 |
+| `chainId`（`workflow_runtime_` 开头） | 一次执行的 ID，每次都新生成 | 区分同一自动化的不同次执行 |
+| `trace_id` | 这次执行所在的 trace | 串起一次执行的全部日志和 span |
+| `commandId` | 一次执行里某个动作的 ID，每次都新生成 | 对应 `el=` 里的 `tag(...)` |
+| `operatorId` | 动作配置的稳定 ID | 同一动作跨多次执行比较 |
+| `fillBackId` | 回填目标（账号、应用、表单或多维表格） | 回填派发和消费日志的关联键，同一目标会跨多次执行 |
+
+## 动作类型
+
+日志里的节点名和页面动作对应如下。“动作返回时确认到哪”决定了 `executor result` 里的成功能说明什么。
+
+| 节点名 | 页面动作 | 动作返回时确认到哪 |
+|---|---|---|
+| `workflowSystemMessageAlertAction` | 系统消息 | 发送异常不算动作失败 |
+| `workflowSmsAlertAction` | 短信 | 消息已发布 |
+| `workflowDingTalkAlertAction` | 钉钉 | 消息已发布；手动触发时只确认已提交后台 |
+| `workflowWechatWorkAlertAction` | 企业微信 | 消息已发布 |
+| `workflowLarkAlertAction` | 飞书 | 消息已发布 |
+| `workflowRobotAlertAction` | 群机器人 | 已调用 webhook，调用失败算动作失败 |
+| `workflowLarkCardAction` | 飞书卡片 | 按接收人分别发送，单个接收人失败要看日志 |
+| `workflowJdyFillBackAction` | 简道云回填 | 只确认后台任务已提交，甚至可能跳过了 |
+| `workflowLarkFillBackAction` | 飞书多维表格回填 | 同上 |
+| `workflowTableArchiveAction` | 表存档 | 定时触发时已同步完成，或因版本、目标目录跳过；来源表更新时不执行；手动触发时只确认已提交后台 |
+| `workflowProjectArchiveAction` | 项目存档 | 手动触发时只确认已提交后台 |
+
+## 失效状态
+
+列表上的“失效”和“关闭”是两回事，对不同触发方式的影响也不同。
+
+- **定时**：前置检查抛错或某个动作失败会标失效，但定时注册还在，下一轮照常触发；开始一轮真正的动作执行时会清掉失效标记，所以它主要反映最近一轮。
+- **来源表更新**：触发时会筛掉已失效的自动化，失效后就不再执行，也不留下带 workflowId 的日志，要等配置修好。
+- **关闭**：定时任务碰到配置缺失、版本不支持等情况时会把自动化直接关闭并取消定时，之后不再触发，见[前置检查的跳过与失败](signals.md#前置检查的跳过与失败)。

package/content/knowledge/automation/conclusions.md

@@ -0,0 +1,34 @@
+# 自动化 · 能下什么结论
+
+回答“看完日志和 trace，能说明什么、不能说明什么”。
+
+## success=true 能说明到哪
+
+`[Workflow] executor result` 的 `success` 只统计动作派发这一层。`success=true` 能说明这次执行走完了、没有动作报告失败，不能说明：
+
+- **接收人收到了**：通知只确认到发布或调用平台。系统消息发送失败不计入失败；接收人还会按成员状态过滤；平台侧投递结果不在这些记录里。
+- **回填写进去了**：可能只是消息已发出，也可能跳过或派发失败，要看[回填的后半段](signals.md#回填的后半段)。
+- **存档做了**：版本不支持或没配目标目录时会跳过，仍算成功；来源表更新触发时表存档不执行。
+- **汇总数值是对的**：字段汇总计算失败时，通知仍会发出，变量显示错误占位值。
+
+`success=false` 能确认至少一个动作失败，失败的是哪个看 `[WorkflowAction] Execute failed`。多个动作相互独立，一个失败不影响其他动作继续。
+
+## 查不到记录时能说什么
+
+搜不到不等于没发生。先确认环境、workflowId 字符和时间窗没错，再按触发方式判断：
+
+| 触发方式 | 查到的情况 | 能说明什么 |
+|---|---|---|
+| 定时 | 时间窗内没有 `to be executed` | 调度没有触发。可能已关闭、已删除，或时间窗短于周期；具体是哪种，日志看不出，要看页面状态或交研发核对定时注册 |
+| 定时 | 有 `to be executed`，没有 `executor result` | 前置检查跳过或报错，同一 trace 里找原因 |
+| 来源表更新 | 这张表的更新成功，但没有这个 workflowId 的 `base table update start` | 触发前就被筛掉了：未启用、已失效、监听的不是这张表、版本不支持，或这次更新的场景不触发。日志不带 workflowId，分不清是哪种，先看页面状态 |
+| 来源表更新 | 有 `start`，没有 `executor prepared`，也没有报错 | 通常是条件未命中，记录里没有直接的证明 |
+
+## 不能混用的判断
+
+- 调度状态、列表失效和本次派发结果是三份不同的记录，互相不能替代；页面显示的状态以页面为准，日志只说明当次发生了什么。
+- 晚到的回填结果不会把较新一轮的自动化标成失效，但动作的调度状态没有这个保护，可能被旧结果覆盖。
+- 条件未命中不是失败，不会标失效。
+- 同一 `fillBackId` 会跨多次执行，按它串的时候要同时对时间或 `trace_id`。
+- 时间接近不算关联：来源表更新和自动化要在同一条 trace 里才算这次更新触发的。
+- 知识来自当前代码和线上记录，版本不同时以这次的实际记录为准，见[知识适用性](../common/conclusions.md#知识适用性)。

package/content/knowledge/automation/queries.md

@@ -0,0 +1,59 @@
+# 自动化 · 查询方法
+
+时间、环境和工具的公共规则见[公共查询规则](../common/queries.md)。下面的过滤都要带上这个环境的 `service.name`，正式环境是 `hihidata-jsy-default`。
+
+## 按 workflowId 查
+
+**列出每次执行**（默认最近 7 天，周期更长时放宽）：
+
+```text
+body CONTAINS '[Workflow] executor result' AND body CONTAINS '<workflowId>'
+```
+
+每行有 `scene`、`chainId`、`actionCount`、`failedCount`、`success` 和 `trace_id`。
+
+**看全部相关记录**，包括没走到执行的（跳过、前置失败、调度触发）：
+
+```text
+body CONTAINS '<workflowId>'
+```
+
+用日志搜索即可，7 天窗口可用。不要按 `body` 分组做 7 天聚合，容易超时。
+
+## 看单次执行
+
+拿到 `trace_id` 后，查这条 trace 的日志，用 `severity_text != 'DEBUG'` 去掉 Quartz 的调试行：
+
+```text
+trace_id = '<traceId>' AND severity_text != 'DEBUG'
+```
+
+存档和回填之后的数据同步也在这条 trace 里，日志可能很多。只关心自动化时，按 `[Workflow`、`component[`、`fill back`、`Execute failed` 这些关键词收窄。需要 span 结构时再读 trace 详情，结果较大，按[大结果](../common/topics/large-results.md)的方式落盘读取。
+
+## 失败概况
+
+看一段时间内动作失败都是什么原因，对 `exception.message` 分组计数：
+
+```text
+body CONTAINS '[WorkflowAction] Execute failed'
+```
+
+前置检查报错：
+
+```text
+thread.name = 'WorkFlowJob' AND body CONTAINS 'job error'
+```
+
+日志里没有可以按企业过滤的自动化字段，只有企业 ID 时请用户提供 workflowId。
+
+## 回填
+
+已知 `fillBackId` 时按正文搜；同一目标会跨多次执行，要再按时间或 `trace_id` 缩小：
+
+```text
+body CONTAINS '<fillBackId>'
+```
+
+## 来源表更新
+
+从自动化追到更新：`[Workflow] base table update start` 的 `trace_id` 就是这次更新节点的 trace，按[更新知识](../update/README.md)继续看。`triggerTableId` 是触发它的表。

package/content/knowledge/automation/signals.md

@@ -0,0 +1,141 @@
+# 自动化 · 入口与信号
+
+回答“一次自动化执行在日志和 trace 里长什么样，各条记录是什么意思”。
+
+## 目录
+
+- [认出自动化](#认出自动化)
+- [定时执行的时间线](#定时执行的时间线)
+- [来源表更新的时间线](#来源表更新的时间线)
+- [trace 结构](#trace-结构)
+- [前置检查的跳过与失败](#前置检查的跳过与失败)
+- [动作失败的常见报错](#动作失败的常见报错)
+- [回填的后半段](#回填的后半段)
+
+## 认出自动化
+
+| 信号 | 说明 |
+|---|---|
+| 根 span `QUARTZ WorkFlowJob` | 定时触发，日志的 `thread.name` 是 `WorkFlowJob` |
+| 根 span `update`，内有实际耗时的 `trigger_listener_WORK_FLOW` | 来源表更新触发，线程名是 `work-flow-` 开头 |
+| `POST /v2/workflow/trigger`，日志 `[Workflow] manual trigger start` / `finish` | 手动触发，失败直接返回给接口 |
+| `GET /v2/workflow/detail/{workflowId}` 等其他 `/v2/workflow/` 接口 | 查看或编辑配置，不是执行 |
+
+这些 span 上没有 workflowId 这类业务属性，按 workflowId 找执行要搜日志正文。
+
+## 定时执行的时间线
+
+正常的一次定时执行，日志按这个顺序出现，前后几条都带 workflowId（下面用 `<id>` 表示）：
+
+```text
+job: <id> to be executed, tenantId: ...        调度已触发
+[Workflow] schedule job start: workflowId=<id>
+                                               前置检查、条件判断（跳过时在这里结束）
+[Workflow] executor prepared: workflowId=<id>, scene=SCHEDULE, actionCount=1
+[Workflow] begin execute workflow chain: ..., chainId=workflow_runtime_..., el=THEN(node("<节点名>").tag("<commandId>"));
+[<traceId>]:[O]start component[<节点名>] execution
+[<traceId>]:component[<节点名>] finished in 1171 milliseconds
+[Workflow] executor result: ..., actionCount=1, failedCount=0, success=true
+[Workflow] schedule job finish: workflowId=<id>
+job: <id> has been executed, tenantId: ...
+```
+
+`start component` 和 `finished in` 不带 workflowId，要用 `trace_id` 串；`finished in` 是单个动作的耗时。`actionCount=0` 表示没有打开的动作，这一轮什么都没做。
+
+手动和回填失败通知也走 `executor prepared`、`begin execute`、`executor result` 这三条，`scene` 分别是 `MANUAL`、`FILLBACK_FAILURE`。
+
+## 来源表更新的时间线
+
+```text
+[Workflow] base table update start: workflowId=<id1>,<id2>, triggerTableId=<表>
+[Workflow] executor prepared / begin execute / executor result（每个自动化一组）
+[Workflow] base table update finish: workflowId=<id1>,<id2>, triggerTableId=<表>
+```
+
+一次更新可能同时触发多个自动化，所以 `start` 和 `finish` 里的 workflowId 用逗号拼接。没有触发时的日志都不带 workflowId：
+
+| 日志 | 含义 |
+|---|---|
+| `work flow not execute because no workflow matches the trigger` | 这张表没有符合条件的自动化（未启用、已失效、没有动作、或不是这张表的来源表更新）；绝大多数更新都是这条 |
+| `work flow not execute because of version,tableId:` | 企业版本或容量不支持自动化 |
+| `skip work flow id is <节点>, cause of update type is <场景>` | 活跃更新（2）或全局更新（14）不触发自动化，这里的 id 是更新节点 |
+
+有 `base table update start` 但某个自动化没有 `executor prepared`，通常是条件未命中，这个分支不打日志。这条更新链不是由基础表发起时（已确认的入口里，根是分析表就属于这种），也会直接结束，什么日志都没有。
+
+更新节点会等自动化派发返回，这段时间算在 `trigger_listener_WORK_FLOW` 里；这个 span 在一个节点里通常出现 3 次，只有一次有实际耗时，见[监听器](../update/topics/events-outcome.md#listener-invocation)。
+
+## trace 结构
+
+```text
+QUARTZ WorkFlowJob
+├─ QueryExecutor → count                条件判断（配置了条件才有）
+├─ workflow → grammarCheck              语法检查，不代表一次执行
+├─ IteratorQueryExecutor                动作取数（字段汇总等）
+├─ UPDATE fx_workflow                   登记本轮、写失效状态
+├─ UPDATE hi_schedule_status            写动作的调度状态
+└─ workflow_queue receive / lark_fill_back_queue receive / excel_append_sync_queue receive
+                                        回填消费、存档后的数据同步，耗时可能比根 span 还长
+```
+
+来源表更新时，这些内容挂在 `update` → `dispatch_node_task_exec` → `trigger_listener_WORK_FLOW` 下面。动作内部的步骤没有单独的 span。
+
+## 前置检查的跳过与失败
+
+定时任务在动作执行前的结果，只有 `execute <id> job error` 是 ERROR。
+
+| 日志 | 含义 | 之后还会触发吗 |
+|---|---|---|
+| `[WorkFlowJob] Skip workflow because trigger conditions have no data` | 条件未命中，这一轮不执行 | 会 |
+| `[WorkFlowJob] Skip workflow because schedule frequency is unavailable` | 当前版本不支持这个时间单位，跳过这一轮 | 会 |
+| `[WorkFlowJob] Skip disabled workflow` | 已关闭，取消定时 | 否 |
+| `[WorkFlowJob] Workflow metadata is missing` | 配置已不存在，取消定时；同一 id 反复出现说明定时注册还残留，不影响用户 | 否（残留时仍会空转） |
+| `[WorkFlowJob] Workflow asset or project is missing` | 自动化或所属项目已不存在，关闭并取消定时 | 否 |
+| `[WorkFlowJob] Workflow no longer contains a valid schedule` | 配置里已没有有效定时，关闭并取消定时 | 否 |
+| `[WorkFlowJob] Skip workflow because alert capacity is unavailable` | 企业版本或容量不支持自动化，关闭并取消定时 | 否 |
+| `[WorkFlowJob] Disable workflow because its next fire time cannot be persisted` | 下次触发时间算不出来，关闭并取消定时 | 否 |
+| `execute <id> job error`（`thread.name` 是 `WorkFlowJob`） | 前置检查报错，动作没有执行，自动化标为失效 | 会 |
+
+`execute <id> job error` 的原因看 `exception.message`：
+
+| `exception.message` | 含义 |
+|---|---|
+| `can't find table <表>.<schema>(version=0)` | 条件判断要读的表在引擎里找不到，查这张表的更新情况 |
+| `workflow trigger table does not exist:` | 条件绑定的来源表已不存在 |
+| `filtered workflow must contain trigger table` | 配了条件但没有来源表，配置不完整 |
+
+## 动作失败的常见报错
+
+`[WorkflowAction] Execute failed: commandId=..., workflowId=..., operatorId=...` 是后台执行时动作失败的日志，级别 ERROR，同时 `executor result` 的 `failedCount` 增加。原因看 `exception.message`：
+
+| `exception.message` | 一般表示 |
+|---|---|
+| `webhook address should not be empty` | 群机器人没有填写 webhook 地址，线上最常见 |
+| `404`、`405` | webhook 地址调用返回的 HTTP 状态，地址多半已失效 |
+| `incoming webhook access token invalid` | 飞书群机器人的 webhook 已失效 |
+| `"errcode":300005`（`token is not exist`） | 钉钉群机器人的 token 不存在 |
+| `"errcode":310000` | 钉钉机器人签名不匹配，密钥配置不对 |
+| `"errcode":400102` | 钉钉机器人已停用 |
+| `"errcode":410100`、`frequency limited` | 发送频率超过平台限制 |
+| `[DingTalkMessageChannelPublisher] publish dingtalk message failed`、`[WeComMessageChannelPublisher] publish wecom message failed` | 外层包装，真正原因看 `exception.stacktrace` 里的 Caused by |
+| `tenantId cannot find lark app info` | 企业没有可用的飞书应用信息 |
+| `template does not exist` | 飞书卡片模板不存在或未发布 |
+| `workflow operator execution table is unavailable` | 动作要用的表不可用 |
+| `widgetId ... does not belong to report` | 通知图片绑定的组件已不在这张仪表板上 |
+| `unsupported chart type:` | 通知图片不支持这种图表类型 |
+| 为空，且 `exception.type` 是 `WorkflowTriggerException` | 动作业务失败，原因在同一 trace 前面的日志，比如 `over capacity error in archive table`（存档超出容量） |
+
+未列出的按原文说明，平台返回的错误码去查对应平台的说明。
+
+## 回填的后半段
+
+后台触发时，回填动作只负责把数据导出并发到队列，真正的写入在后面异步进行，日志和派发在同一条 trace 里。这几条都不带 workflowId，用 `trace_id` 或 `fillBackId` 串。
+
+| 日志 | 阶段与含义 |
+|---|---|
+| `[WorkflowFillBack] Skip because fillBackId is blank` | 没有配置回填目标，跳过，但 `executor result` 仍是成功 |
+| `[WorkflowFillBack] Dispatch failed` | 派发失败，`executor result` 仍是成功；常见的 `some fields is loss` 表示映射的源字段已不存在 |
+| `[WorkflowFillBack] Message sent: tableId=..., fillBackId=..., count=` | 已发到队列，`count` 是待回填行数 |
+| `fillBack permits reach the limit` | 企业的并发额度用完，稍后重试，不是失败；量很大时说明在排队 |
+| `handler fill back start`、`handler lark fill back start` | 开始写简道云、飞书多维表格 |
+| `handler fill back success, ... successCount =` | 简道云写入成功；飞书成功时没有这条日志，没有失败日志时看 trace 是否走完 |
+| `something error when workflow, msg=`、`something jdy error happened when workflow` | 写入失败，`msg` 是外部平台返回的原文；之后会触发 `scene=FILLBACK_FAILURE` 的附加通知 |

package/content/knowledge/automation/workflow.md

@@ -0,0 +1,37 @@
+# 自动化 · 排查入口
+
+用户问某个自动化有没有跑、为什么没发、执行结果怎样时，从这里下手。
+
+## 按 workflowId 查执行情况
+
+大多数问题都从 workflowId 开始，查询写法见[按 workflowId 查](queries.md#按-workflowid-查)。
+
+1. 用 workflowId 搜日志，默认看最近 7 天，先按 [`[Workflow] executor result`](signals.md#定时执行的时间线) 列出每次执行的时间、触发方式、动作数和失败数。周期比 7 天长时放宽时间窗。
+2. 要看某一次，拿这次的 `trace_id` 查同一 trace 的日志。一次执行的条件判断、动作和回填都在这条 trace 里，动作级的日志不带 workflowId，只能这样串起来。
+3. 有失败就看 [`[WorkflowAction] Execute failed`](signals.md#动作失败的常见报错) 的异常消息。回填要继续看[回填的后半段](signals.md#回填的后半段)，第 1 步的成功只说明消息已经发出。
+4. 没有执行记录时，按触发方式核对[查不到记录时能说什么](conclusions.md#查不到记录时能说什么)。
+
+只有自动化名称或现象时，请用户给页面链接或 workflowId，名称在日志里搜不到。
+
+## 常见现象与候选假设
+
+- **到点没执行**：有 `to be executed` 但没有 `executor result`，多半是前置检查跳过或失败，见[前置检查的跳过与失败](signals.md#前置检查的跳过与失败)；常见的是条件未命中和条件用的表找不到。连 `to be executed` 都没有，说明调度没有触发。
+- **来源表更新了，自动化没跑**：先确认这张表的更新确实成功、更新场景不是活跃或全局更新，再看 workflowId 有没有 `base table update start`。有它但没有 `executor prepared`，通常是条件未命中，这个分支不打日志。
+- **显示成功但没收到**：`success=true` 不代表送达，见[success=true 能说明到哪](conclusions.md#successtrue-能说明到哪)。系统消息发送失败不算动作失败，查 `[WorkflowNotification] Send system message failed`；接收人被过滤或平台侧没投递，这些记录看不出来，要用平台侧的结果核对。
+- **通知发送失败**：多半是配置或外部平台问题，比如 webhook 没填或已失效、签名不对、机器人被停用、发送频率超限，对照[动作失败的常见报错](signals.md#动作失败的常见报错)。
+- **回填失败或一直没写进去**：分清卡在派发、排队还是外部写入，见[回填的后半段](signals.md#回填的后半段)。
+- **列表显示失效**：定时自动化前置检查报错或某个动作失败都会标失效，但定时仍会继续触发；来源表更新的自动化失效后不再触发，见[失效状态](concepts.md#失效状态)。
+- **更新节点变慢，怀疑自动化拖的**：看 `update` trace 里耗时最长的那个 `trigger_listener_WORK_FLOW`，更新节点会等自动化派发返回；回填的外部写入不在等待范围内。
+
+## 易错点
+
+- 时间窗内只看最新一次容易漏掉前面的失败，先列全再选。不同次执行分开说，一次成功抵消不了另一次失败。
+- 不要按 `[Workflow] base table update finish` 统计：绝大多数更新没有匹配的自动化，也会打这条日志，且 workflowId 为空。
+- `[Workflow]` 开头的日志都是 INFO，失败的 `success=false` 也一样，按日志级别过滤会漏掉。
+- `workflow` 这个 span 是语法检查里的一段，不代表一次执行，不要用它计数。
+- `skip work flow id is` 里的 id 是更新节点，不是 workflowId。
+- 日志时间是 UTC，给用户换成北京时间，定时任务尤其容易差 8 小时。
+
+## 交付
+
+说清楚看了哪个 workflowId、多长时间、一共执行几次、各成功失败多少，失败原因用业务语言讲（“群机器人没有填写 webhook 地址”），节点名换成页面上的动作名，对照见[动作类型](concepts.md#动作类型)。能确认到“已发出”就说已发出，不要说成“已送达”。

package/content/knowledge/common/queries.md

@@ -46,6 +46,7 @@
 | tableId、widgetId、reportId 等资源 ID | 按默认或显式环境及发生时间，使用场景入口、服务和资源 attribute 寻找候选执行 |
 | 企业 ID（更新查询） | 复用已有时间；未提供时告知默认最近 24 小时后直接查询，先给更新概况并优先核对异常 |
 | dagId | 按更新链标识精确发现提交与节点，不要求用户先补时间或 trace；检索时间见[更新发现指引](../update/topics/discover-executions.md#检索时间) |
+| workflowId（自动化） | 未提供时间时默认最近 7 天，按日志正文精确查，见[按 workflowId 查](../automation/queries.md#按-workflowid-查) |
 | 截图或 OCR 提取的 ID | 先核对字符并确认锚点可信度；存在相似字符歧义时请用户确认或粘贴原始文本 |
 | 只有现象 | 补充能够确定场景或资源、发生时间的最小信息；未指定环境默认 work，不直接发起宽查询 |
 

package/content/knowledge/common/signals.md

@@ -41,6 +41,7 @@
 | 组件 | [component/signals.md](../component/signals.md) |
 | 仪表板 | [dashboard/signals.md](../dashboard/signals.md) |
 | 更新 | [update/signals.md](../update/signals.md) |
+| 自动化（`QUARTZ WorkFlowJob`、`/v2/workflow/` 接口、`[Workflow]` 日志） | [automation/signals.md](../automation/signals.md) |
 
 认出是更新以后：要查慢或失败，进[更新性能排查](../update/workflow.md#更新性能排查)；要弄清更新来源、DAG、计数，或解释已有的运行记录，进[解释更新记录](../update/workflow.md#解释更新记录)。
 

package/content/knowledge/signal-index.md

@@ -10,6 +10,7 @@
 - [组件](#组件)
 - [仪表板](#仪表板)
 - [引擎](#引擎)
+- [自动化](#自动化)
 - [通用](#通用)
 
 ## 常见报错
@@ -38,6 +39,10 @@
 | `Task is failed by its parent failed`、`dependence failed` | 同一条链里上游节点失败，本节点没执行就跟着失败；沿 `fail parent` 往上找第一张自己报错的表 | [上游出错连带失败](update/signals.md#上游出错连带失败) |
 | `record failed`、`peakMem` | 更新失败后记到表上的指标：`peakMem-3` 是内存超限失败，`-1` 是其他错误 | [上游出错连带失败](update/signals.md#上游出错连带失败) |
 | `Tenant limit exceeded`、`resend execute info` | 租户额度用完转慢队列、等锁超时重派；都不是最终失败 | [capacity-deferred](update/topics/events-execution.md#capacity-deferred)、[lock-requeued](update/topics/events-execution.md#lock-requeued) |
+| `webhook address should not be empty`、`incoming webhook access token invalid`、`token is not exist` | 自动化的群机器人 webhook 没填或已失效，配置问题 | [动作失败的常见报错](automation/signals.md#动作失败的常见报错) |
+| `workflow operator execution table is unavailable`、`over capacity error in archive table` | 自动化动作要用的表不可用、存档超出容量 | [动作失败的常见报错](automation/signals.md#动作失败的常见报错) |
+| `workflow trigger table does not exist`、`filtered workflow must contain trigger table` | 自动化的条件绑定的表不存在或没配，动作没执行 | [前置检查的跳过与失败](automation/signals.md#前置检查的跳过与失败) |
+| `some fields is loss` | 自动化回填映射的源字段已不存在 | [回填的后半段](automation/signals.md#回填的后半段) |
 
 ## 更新
 
@@ -108,6 +113,20 @@
 | `queryCount`、`rowCount`（查询埋点） | V1 查询埋点：尝试序号、计数值及适用限制 | [V1 查询埋点与完成边界](engine/queries.md#v1-查询埋点与完成边界) |
 | `compute.retry.pipeline_parallelism_reduced` | 数据源湖写入内存不足后降并行度重试 | [更新 Write 链路](engine/queries.md#更新-write-链路) |
 
+## 自动化
+
+| 名称 | 是什么 | 说明在哪 |
+|---|---|---|
+| `QUARTZ WorkFlowJob`、`trigger_listener_WORK_FLOW` | 定时触发的根 span；来源表更新时的触发位置 | [认出自动化](automation/signals.md#认出自动化) |
+| `[Workflow] schedule job start`、`[Workflow] executor prepared`、`[Workflow] begin execute workflow chain`、`[Workflow] executor result` | 日志：定时执行的主线，带 workflowId | [定时执行的时间线](automation/signals.md#定时执行的时间线) |
+| `[Workflow] base table update start`、`work flow not execute because no workflow matches the trigger`、`skip work flow id is` | 日志：来源表更新触发、未触发 | [来源表更新的时间线](automation/signals.md#来源表更新的时间线) |
+| `[Workflow] manual trigger start` | 日志：手动触发 | [认出自动化](automation/signals.md#认出自动化) |
+| `[WorkFlowJob] Skip workflow because trigger conditions have no data`、`[WorkFlowJob] Workflow metadata is missing`、`job error` | 日志：定时前置检查的跳过与报错 | [前置检查的跳过与失败](automation/signals.md#前置检查的跳过与失败) |
+| `[WorkflowAction] Execute failed` | 日志：后台执行时动作失败，原因在 `exception.message` | [动作失败的常见报错](automation/signals.md#动作失败的常见报错) |
+| `[WorkflowFillBack] Message sent`、`[WorkflowFillBack] Dispatch failed`、`fillBack permits reach the limit`、`handler fill back success`、`something error when workflow` | 日志：回填的派发、排队、写入 | [回填的后半段](automation/signals.md#回填的后半段) |
+| `workflow_queue receive`、`lark_fill_back_queue receive` | 回填消费，和派发在同一条 trace | [trace 结构](automation/signals.md#trace-结构) |
+| `chainId`、`commandId`、`operatorId`、`fillBackId` | 一次执行、一个动作、动作配置、回填目标的标识 | [标识](automation/concepts.md#标识) |
+
 ## 通用
 
 | 名称 | 是什么 | 说明在哪 |

package/content-manifest.json

@@ -1,25 +1,31 @@
 {
   "schema_version": 1,
-  "version": "0.1.20261109015953",
-  "source_commit": "408a99053c5d8a3974331e546f154cb06d081cb8",
+  "version": "0.1.20261111014808",
+  "source_commit": "00de09f93317a0bcd269097ab0802c833572e602",
   "source_dirty": false,
   "cli_sha256": "08aa66f145e51627bf71c9e12ec7ae01907e130ad9ce6056b2ea37262ce92be0",
   "files": {
-    "AGENTS.md": "32bc0682d0b83e8359ca33b48a300348803916c102def8bacac8182a01cc04b2",
-    "README.md": "ec972703b6416ccf7b0f516afed1f9598c69e270731d4f00a5f836fffe5499a1",
+    "AGENTS.md": "674f7657f5ab6167154bd910d344c5bdb850a5c0598191d5f33b2976550badf3",
+    "README.md": "159cf89acdf515b8802d6d9ee3861aaa05683217777ac907e03c2c0a33f6fee6",
     "docs/architecture.md": "6a0d602927789ee6d463f26a7eab45661a730c3a87164ab44aae63235a191fb0",
     "docs/diagnostic-feedback.md": "6ebade7a0fc65171e0075a63f5d1f526407a5a30789fa7941df48995dab56918",
     "docs/diagnostic-report.md": "8cf3f19051062a44ecc23635d1ac4ad210863521290be11d808ec2d14c53ca84",
-    "docs/index.md": "3ebe2ea38f9378d9b8740d7eb6da9fd0f4612ca615f42d52f4ff71ffc059865e",
-    "docs/scenario-guide.md": "d8e8ac19b40fdc395a4433d6be47b93885472f6ac535936c0cc2f3f6672f97fa",
-    "knowledge/README.md": "b0ac5f8865b93947a79f9991c4310164536f69e26c884486b8080fa51c3c2fe4",
+    "docs/index.md": "6a9df42dd3205323af122774393b6cc57b896c571ae3c28f99034c1c3c8753f6",
+    "docs/scenario-guide.md": "b9e5da69a1cf50c8d65e96862ffed1d7558bdbb106e3b0826632bd41a5b1401e",
+    "knowledge/README.md": "04f337c10b33161eda142ba6e3af923b9b8f46b92208b64d1681e7c8b80c4088",
+    "knowledge/automation/README.md": "94b7dd70af66ab4f6b330190607cb5e3a20cbc05cc8cfe4437974e039c8cb42e",
+    "knowledge/automation/concepts.md": "33ed961fd260f56196e96fa49bce194d173ca312c92c14aa50f375308f01b944",
+    "knowledge/automation/conclusions.md": "a82d70ecfabbbce5134c7930735b362baa289abf12d1dab8c1ff66229859502e",
+    "knowledge/automation/queries.md": "73164b0a96215a3192d4e38416d357df674ccf332f33deff49392b424e0d568a",
+    "knowledge/automation/signals.md": "52f2fd37beb655b06a5a3944418161bfacb46615a25ded952383fc58e6715742",
+    "knowledge/automation/workflow.md": "1acb5d9326d7837c945e9a853de4f8031064e26a9236094d1aae859ae46677ad",
     "knowledge/cases/README.md": "43dc70f8e69ee64617e8af23234fb9729b3c45675cee768ba43acb218d4b3c62",
     "knowledge/cases/dashboard-parameter-deep-binding.md": "c358565293569766e42d6796969eb8808e2bbd4de777878bd798c1c7d0ed303f",
     "knowledge/common/README.md": "489cf194104d9f9fece5134e5ac3b8f22698e919885f146d775e252e8ee66627",
     "knowledge/common/concepts.md": "89c54ce7a23276c07e59ef8334105bc56519f551d1cc1e9b7ad6e52e1cb834ef",
     "knowledge/common/conclusions.md": "3b91199925f4e3743aa2ac895e86390375adcb3c890bee27ba6dadd6e8f8adb0",
-    "knowledge/common/queries.md": "f9d4f759dcc3084b6e6598470b8d9e6473ad334afe5942b48170ccf570aaebf4",
-    "knowledge/common/signals.md": "33b9ecd96825f0e932d2e720139723b79f2b8e0347e3db098a90198ae0e019d1",
+    "knowledge/common/queries.md": "5b6522d48ca8677d662d7eb56218dc24e09e87e0508693bdecc0fa004f015b89",
+    "knowledge/common/signals.md": "a8e5696e53186dbdb70d0e757356b318d608b63e0186eccbb8a3289dfdce1bed",
     "knowledge/common/topics/baseline-comparison.md": "143b7ee9df23ac276a603cf2c5866d2290fd2b4f1feb227d26b127f5fb14b02e",
     "knowledge/common/topics/large-results.md": "12d8a9e37fe51cc447b9245b680bae65b23d366745abc85e2215a8e896178286",
     "knowledge/common/topics/linked-traces.md": "831076c79a584e3de9b1f1e88488065196c1085beabfd270f90156d4bf9303e5",
@@ -59,7 +65,7 @@
     "knowledge/engine/topics/metric-fields.md": "2171f383a7c49b38ecf49ed9a0a726b87eaaac6da9f48f00140f6758dd26f458",
     "knowledge/engine/topics/patterns.md": "c45555888c59f6b485343587bfe949c1b8fd198bbd65ba3d29cb296cc343869b",
     "knowledge/engine/workflow.md": "9f2036a4f65e50b02879fbb261d1f51b56a0fbae54b5ceeedd645912ec1d20e8",
-    "knowledge/signal-index.md": "0e0d0dafe88bc17443a2b3d874703ed41a15e50f43a050070c93277cdbcae69e",
+    "knowledge/signal-index.md": "39d33257b1f18946f0ad55db172dd5d7ca8a3ff041a65d32975bb5df39a05163",
     "knowledge/update/README.md": "c20401cf360a424a974e52bb40ae80e760c5584fa557ab3e3712035a33a8ba4a",
     "knowledge/update/concepts.md": "e77334a69a5d85a0b12090143a4da7e4d727e78ef6f8235b6221b433f0a6bd1c",
     "knowledge/update/conclusions.md": "3c0ae1de501ec4794b036c44d5c920245870db46c49839779356a951e3757e90",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fx-data/ai-diagnostics",
-  "version": "0.1.20261109015953",
+  "version": "0.1.20261111014808",
   "description": "FX数据诊断：Agent 诊断技能、知识与本地脚本",
   "type": "module",
   "license": "UNLICENSED",