@fx-data/ai-diagnostics 0.1.20261107142011 → 0.1.20261111014808

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261107142011`，需要 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.20261107142011/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

@@ -30,6 +30,7 @@
 | 某个场景域的入手提示、候选假设与易错点 | 各域 `workflow.md`，见[知识目录](../knowledge/README.md) |
 | 安装、配置或恢复 SigNoZ MCP | [配置 SigNoZ MCP](../knowledge/common/topics/setup-signoz-mcp.md) |
 | 引擎任务定位、MetricOuts 正文获取与复用 | [Metric 获取](../knowledge/engine/queries.md) |
+| 慢或失败的引擎执行何时必须读取 Metric、跳过条件 | [Metric 获取](../knowledge/engine/queries.md) |
 | Metric 字段含义 | [Metric 解读](../knowledge/engine/conclusions.md) |
 | 常见引擎性能问题的判断方法 | [常见引擎性能问题](../knowledge/engine/topics/patterns.md) |
 | 分析表 / 组件 / 仪表板的业务概念、入口 span 与 attribute | [分析表](../knowledge/dataset/README.md)、[组件](../knowledge/component/README.md)、[仪表板](../knowledge/dashboard/README.md) |
@@ -39,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/common/workflow.md

@@ -15,7 +15,7 @@
 
 - OOM、超时、行数上限是直接失败条件，不是根因。报错位置多半在引擎，原因多半在业务场景：在引擎里看清撞了什么线以后，回到场景域找是什么让计算变得这么大：分析表是哪个步骤放大了数据，更新是哪个节点或哪个上游，组件和仪表板是查询、筛选、参数或绑定。建议也要落在这一层。
 - 已取消或没提交的执行（比如日志里有 `not submitted, skip finish`）根本没开始计算，有 task ID、Metric 链接或一个整数超时时长都证明不了算过。这时该解释的是取消链、等待或准入，没必要再去找计算统计。
-- 慢或失败的引擎执行，一般要看一眼 Metric 才能讲清物理上发生了什么。如果只看到业务层的 `polars query timeout`，先补读这次执行的属性，或者从同一个 trace 的提交日志里找回 task，别急着认定 Metric 拿不到。
+- 选定慢或失败的引擎执行后，按[Metric 获取要求](../engine/queries.md)主动取数并分析。如果只看到业务层的 `polars query timeout`，先补读这次执行的属性，或者从同一个 trace 的提交日志里找回 task，别急着认定 Metric 拿不到。
 - 用户说“之前没超限”“以前正常”，但近几天找不到这个对象成功的记录时，就直接告诉用户：近 N 天没找到成功记录，和“之前正常”对不上，请他确认是哪张表、什么时候开始异常。不要顺着用户的说法去解释“为什么这次变了”。
 - 单次失败不需要成功样本。用户要求对比，或者手上正好有可比的成功执行，再去对比，目标和基线各自固定自己的范围。
 - 业务解释和 Metric 谁也替代不了谁：慢 span 只告诉你慢在哪一段，Metric 只解释进入引擎以后的事。

package/content/knowledge/component/workflow.md

@@ -7,7 +7,7 @@
 - 先分清是图表编辑时的预览、仪表板里的组件请求，还是仪表板以外的图表预览。仪表板组件预览入口按[来源判定](../common/signals.md#仪表板组件预览入口)确认；来自仪表板的，直接转到[仪表板知识](../dashboard/workflow.md)。用户只说“图表慢、超时”时，第一步就是做这个区分。
 - 记下组件、绑定表、筛选、联动和权限上下文、环境、时间窗，以及用户感觉到的耗时。用精确 ID、请求上下文和时间窗缩小候选执行，不要按最慢的 span 挑。
 - 主要看三件事：一次是不是触发了多个查询，或者带了复杂的筛选、联动、聚合、排序；trace 里耗时集中在哪个阶段；绑定分析表的资源版本或更新状态和这次有没有关系。
-- 慢或失败的引擎执行，可以看[引擎知识](../engine/workflow.md)；线索指向分析表或更新时，转到对应的域。
+- 选定慢或失败的引擎执行后，进入[引擎排查](../engine/workflow.md)，按[Metric 获取要求](../engine/queries.md)补齐执行分析；线索指向分析表或更新时，转到对应的域。
 
 ## 常见现象与候选假设
 

package/content/knowledge/dashboard/workflow.md

@@ -6,26 +6,36 @@
 
 - 报错落在引擎里（超时、内存超限）时，引擎只说明撞了什么线，原因回到下面还原的业务计算里找。
 - **先分清是哪类取数**：筛选器取候选值只看它怎么算候选值、别的筛选器带来什么影响；组件取数看组件自己的查询。组件请求里带着筛选条件，不代表是筛选器自身取数。
+- **组件最终只显示少量数据，不代表只计算这些数据**：筛选器、参数、动态字段和行列权限都可能改变本次计算，使组件不能直接读取已有结果，而要展开来源表、关联、汇总等上游计算。重点看条件作用在哪张表、涉及哪些路径、实际多算了什么，不只看组件绑定表的大小或条件个数，见下面的[计算范围为何变大](#计算范围为何变大)。
 - **优先用 trace 的 span attribute 还原本次具体业务计算**：组件算哪些查询、用了哪些字段、聚合和排序；根表、绑定表、筛选字段所在表及它们之间的完整路径；筛选、参数、权限、自动联动、组件间联动各加了什么；数据范围有没有被父表路径、无关字段、重复分支或不合理的绑定放大。先据此判断计算复杂度，再看引擎，别一上来就按慢 span 找 Metric。
 - 筛选树多层或多分支时还原成完整的树，见[筛选树还原与交付](topics/filter-tree.md)；筛选器或动态字段只剩 ID 时见[名称关联取证](topics/name-binding.md)；怀疑上游被重算见[动态字段覆盖](topics/dynamic-fields.md)；默认详情缺业务 attribute 时按[取证例子](queries.md)定向补。
 - **筛选值变化后变慢**：能看出属于同一次筛选、或落在可靠时间边界内的组件请求，算这次受影响的集合；全部受影响组件刷新完成才是用户感觉的“好了”。分清是“影响范围大”还是“某一个算得慢”。没看到其他组件请求，不等于配置上绝对没有其他目标，要确认按[核对配置影响范围](conclusions.md#核对配置影响范围)读 targets。
-- 筛选字段绑在较上层父表、让组件走了更宽的数据链路，且请求内容、筛选树和资源关系能证明带来了额外计算时，可以当作性能原因；业务上能不能往下挪另说。
-- 慢或失败的引擎执行看[引擎知识](../engine/workflow.md)，业务上解释通了也最好补上。关键组件、绑定表或更新状态可疑时转[分析表](../dataset/workflow.md)或[更新](../update/workflow.md)。
+- 选定慢或失败的引擎执行后，进入[引擎排查](../engine/workflow.md)，按[Metric 获取要求](../engine/queries.md)补齐执行分析，再结合业务计算解释原因。关键组件、绑定表或更新状态可疑时转[分析表](../dataset/workflow.md)或[更新](../update/workflow.md)。
 
 ## 组件取数先做对照
 
 认出是仪表板里的组件计算后，主动去找这个组件单独预览的记录，不用等用户说“单独看是好的”。查找范围见[仪表板内外组件对照](../common/topics/baseline-comparison.md#仪表板内外组件对照)，可比性和成功判定见[组件计算对照怎么判断](topics/component-comparison.md#组件计算对照怎么判断)。
 
-- 单独预览成功、仪表板里失败或变慢：先看仪表板额外带进来的动态字段、参数、筛选、联动和权限；只因入口不同不能下结论。
+- 单独预览成功、仪表板里失败或变慢：逐项核对下面四类条件和联动，比较两侧直接读已有结果还是展开了上游计算；只因入口不同不能下结论。
 - 两边都异常：先查共同部分，即组件查询、输入数据和计算链。
 - 没找到对照：照样分析手上的异常 trace，同时提醒用户看看单独预览时是否也异常。仪表板里很快成功的请求只说明有另一条计算路径，不能当单独预览。
 
+## 计算范围为何变大
+
+筛选器、参数、动态字段、行列权限都要核对，不能看到其中一项就停止检查其他项。它们可能同时作用，也可能不增加计算；按本次请求、条件所在表和实际计划判断。
+
+- **筛选器**：筛选条件绑在较上层父表，或经多条路径影响组件时，可能需要展开来源表、关联和汇总，带来额外计算。看筛选绑定和最终条件树，核对条件所在表到组件查询表的完整路径；联动带来的条件也要计入。不能因筛选后返回更少，就认定计算一定更少。判断与展示见[筛选树](topics/filter-tree.md)，绑定调整的前提见[配置影响范围](conclusions.md#核对配置影响范围)。
+- **参数**：参数改变上游计算的输入或表达式，可能使已有结果无法直接复用；绑定越靠上游，受影响的计算链可能越长。核对本次参数、页面上的绑定表和实际展开的路径；筛选树为空也不能排除参数影响。深层绑定的候选现象与建议前提见[参数案例](../cases/dashboard-parameter-deep-binding.md)。
+- **动态字段**：替换上游计算字段后，下游可能需要按新字段重新展开计算。先确认本次是否有覆盖、覆盖在哪条表路径上，再核对实际计划；普通参数统计为空不能排除动态字段。取证与停止边界见[动态字段覆盖](topics/dynamic-fields.md)。
+- **行列权限**：权限条件及可见字段可能改变本次可读取的数据和查询计划；权限作用于上游表时，也可能带入额外的计算路径。核对本次权限上下文、作用表和实际计划，不把“有权限条件”直接当作重算原因。入口只有权限标记、没有作用位置时，保留为上下文，不猜挂到某张表，见[筛选树中的权限边界](topics/filter-tree.md#名称绑定与展示)。
+
+把条件带来的计算变化与资源压力对上：先看两侧直接读已有结果还是展开了上游，再看查询长度、涉及的表路径和对应 Metric 中的计划、数据规模、耗时及内存。查询变长、路径变深只是线索，不能单独证明是哪项条件导致超时或内存超限。建议落到已核实的绑定或计算上；调整筛选、参数、动态字段或权限前，都要确认结果口径和权限语义。
+
 ## 常见现象与候选假设
 
 - **筛选器自身取数慢**：来源表或绑定字段多、自动解析读的范围大；别的筛选器带进的条件让查询变大；来源表的上游状态成了关键路径。对比读进来的数据量和最后的候选值数量。配了多个字段不一定慢，“按钮组绑了几个大字段又是自动解析”只是假设，不直接建议改手动解析。
-- **组件取数慢**：组件自身查询复杂；筛选绑在较上层父表撑大了过滤树；参数、权限、自动联动或 `ComponentControl` 加了计算；一次动作触发多个组件，少数关键组件或共享上游拖慢整体。见过的情况：日期区间参数不是默认值，一打开就实时计算；每次调日期区间都触发大计算；参数或筛选绑在很深的上游。改默认值、改点查询、绑定下移都有业务前提。
-- **引擎优化器超时或内存超限，请求只带了参数**：参数绑在很深的上游父表上时，参数一变，上游存好的结果都用不了，整条上游链被实时展开，查询语句变得极长，引擎在优化阶段就超时（`Task execution timeout after ... (limit: ...)`）或算到内存超限。看 `previewComponent` 上 `controls.parameter_names` / `controls.parameter_bindings` 带了哪些参数、筛选树是否为空，再按[查询规模信号](../engine/signals.md#查询规模信号)看 `dax length`、`end get parent` 次数。对得上就是参数绑定层级的问题。参数绑在哪张表 trace 里看不到，请用户在参数设置里看；建议绑定挪到靠近组件的表上，挪之前确认业务口径。案例见[仪表板参数绑在深层父表](../cases/dashboard-parameter-deep-binding.md)。
-- **单独预览正常，仪表板里展开上游后超限**：核查过的案例里，单独预览直接读几行保存好的汇总；仪表板里失败那次带了上游动态字段覆盖，展开了几路明细、关联和缓存后撞上内存上限。同一仪表板也有很快成功的请求，“在仪表板里”本身解释不了差异。先看有没有动态字段覆盖、覆盖所在表到组件查询表的路径；名称映射补不出失败那次选的值，历史请求也不能冒充失败 trace 的属性。
+- **组件取数慢**：先区分组件自身查询重，还是上述条件扩大了计算范围；一次动作触发多个组件时，再分清影响范围与关键慢组件，不把请求数直接当作计算复杂度。
+- **查询语句很长、优化器超时或内存超限**：按[查询规模信号](../engine/signals.md#查询规模信号)看 `dax length`、上游查找和实际计划，再沿四类条件核对触发因素，不只查参数。优化器超时看对应错误中的 limit；内存超限看同 task 错误，不仅凭查询长度或内存峰值判定。
 
 ## 易错点
 

package/content/knowledge/dataset/workflow.md

@@ -8,7 +8,7 @@
 - 记下表、选中的步骤、环境、时间窗和配置版本。手上有精确的 trace 或请求，就围绕它分析。
 - 现象比较笼统时，把候选执行按类型和成功、失败粗分一下。不要从最慢的成功预览直接推断用户目标。
 - 报错落在引擎里（内存超限、行数超限、超时）时，引擎只说明撞了什么线，原因要回到步骤里找：哪一步把数据放大了，或者要攒齐整批数据，见[分析步骤](topics/steps.md#哪些步骤容易慢或爆内存)。
-- 慢或失败的分析表查询，可以看[引擎知识](../engine/workflow.md)解释物理上怎么算的；线索指向后台更新或组件、仪表板，就转到[更新](../update/workflow.md)或对应的域。
+- 选定慢或失败的引擎执行后，进入[引擎排查](../engine/workflow.md)，按[Metric 获取要求](../engine/queries.md)解释物理上怎么算的；线索指向后台更新或组件、仪表板，就转到[更新](../update/workflow.md)或对应的域。
 
 ## 常见现象与候选假设
 

package/content/knowledge/engine/queries.md

@@ -1,6 +1,8 @@
 # 引擎 · 查询方法
 
-engine Metric 用来解释已经锁定的执行：这次计算处理了多少数据、耗时和内存花在哪、因为什么失败。这里写怎么从 trace 找到任务、怎么取 Metric 正文；字段含义见[Metric 字段速查](topics/metric-fields.md)，判读口径见[能下什么结论](conclusions.md)。环境、时间、预算和大结果遵守[公共查询规则](../common/queries.md)。慢或失败的引擎执行通常值得读一下 Metric，明确没提交的除外。
+engine Metric 用来解释已经锁定的执行：这次计算处理了多少数据、耗时和内存花在哪、因为什么失败。这里写怎么从 trace 找到任务、怎么取 Metric 正文；字段含义见[Metric 字段速查](topics/metric-fields.md)，判读口径见[能下什么结论](conclusions.md)。环境、时间、预算和大结果遵守[公共查询规则](../common/queries.md)。
+
+选定慢或失败的引擎执行后，主动获取并分析对应 Metric，业务上的候选原因不能替代这一步。已有正文直接复用；只有明确未提交、用户不允许查询或按本页方法仍取不到时才跳过，并说明原因和结论限制。离线材料缺 Metric 时，明确列为待补材料，不把它写成可选建议。
 
 ## 目录
 

package/content/knowledge/engine/topics/metric-fields.md

@@ -45,7 +45,7 @@
 | 字段 | 是什么 | 诊断时怎么用 |
 |---|---|---|
 | `node_id` | 在哪个引擎节点上跑 | 同节点多个任务一起慢时，可以按它归类 |
-| `query_peak_memory`、`query_memory_limit` | 这个任务的内存峰值和上限 | 峰值贴近上限就是撞线了 |
+| `query_peak_memory`、`query_memory_limit` | 这个任务的内存峰值和上限 | 贴近上限表示内存压力大；是否超限以同 task 的错误为准 |
 | `query_memory_allocated`、`query_memory_deallocated` | 累计申请、释放的内存 | 是累计量，不是峰值，不能拿来和上限比 |
 | `global_current_memory`、`global_memory_limit` | 整个引擎节点当前占用和上限 | 任务自己不大、节点整体很满时，可能是被同节点的别的任务挤的 |
 | `spillBytes` | 吐磁盘的字节数 | 不为 0 说明写过磁盘 |

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#回填的后半段) |
 
 ## 更新
 
@@ -105,9 +110,23 @@
 | `taskName`、`metric`、`polars.taskId`、`QueryExecutor`、`v2.execute.query` | trace 上的引擎任务标识与统计链接 | [已有 trace 时取哪些字段](engine/queries.md#已有-trace-时取哪些字段) |
 | `elapsed_time`、`optimizer_cost`、`query_memory_limit`、`morsel_blocked_time`、`scanned_rows_num`、`table_scan_cache_result_queue_size` | MPP Metric 各层字段：任务总耗时、优化耗时、内存上限、执行单元挂起、读表行数、读表瓶颈 | [Metric 字段速查](engine/topics/metric-fields.md) |
 | `MetricOuts` | 引擎统计日志的 logger，按 task 和时间窗取 | [Metric 链接与任务日志](engine/queries.md#metric-链接与任务日志) |
-| `queryCount`、`rowCount`（查询埋点） | V1 查询埋点：尝试序号、返回行数的口径 | [V1 查询埋点与完成边界](engine/queries.md#v1-查询埋点与完成边界) |
+| `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.20261107142011",
-  "source_commit": "b51066664892517d5537116057fe705bf4ae6882",
+  "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": "bdacf88f93c5ad667aa591ebfa86deff55b9f0fe037189f73009ecfe14dace87",
-    "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",
@@ -27,13 +33,13 @@
     "knowledge/common/topics/query-example.md": "1f94c3d1f5dac77936ecb88f023a123fcaae228dd00303801a62ee94a3706cd1",
     "knowledge/common/topics/setup-signoz-mcp.md": "f5de34eed827f338bc8733eae8dc1faf0f78eb3ff88a8fc2cee54eff73160242",
     "knowledge/common/topics/start-and-anchors.md": "97fc86edd62eff227274e8a027a19a23dce60cfd999f7b5e480fdd4f8adee254",
-    "knowledge/common/workflow.md": "6be3fae959f955f6df243bff9c1b1b7f556584ed7afb9a6e28d79fed56b9b130",
+    "knowledge/common/workflow.md": "dc8dbcefa4967fc7f3dfcd575753486149068644bffb86fba5cb6541b9841336",
     "knowledge/component/README.md": "d0d99e14f9f36d74216306c892730f3fba838a01e40c7565e5bec53d28f09fda",
     "knowledge/component/concepts.md": "6e8c4c7a29fe1e3bc7ab964f6a8c59f6702a139c9640b2b7cf0c181f506fa9c5",
     "knowledge/component/conclusions.md": "dfcc38a6a36ca0e89bfeb5d300a2be00447d894de3879ecf508dead9ecd35343",
     "knowledge/component/queries.md": "c641ce3de9019c78462cc6bb152926908bfb3e2d3857f1d34d39df714fd281a9",
     "knowledge/component/signals.md": "e7c38f5b9d5b0a2220dd37f980c7c23db00982d598551c437d0a0b87de68b9d5",
-    "knowledge/component/workflow.md": "089e10354133b723f4eaa8c91194a7da8aefe246037d96dcc946cf61352d8f97",
+    "knowledge/component/workflow.md": "5217899817ff5e9b17ceb9989dc0021e34f5c58ff7deb861b64c4198aaa8fc96",
     "knowledge/dashboard/README.md": "a9454cdf63c3df04b142df39f19f6d422d1e0db67fdb8129c7dd51d07850f1b3",
     "knowledge/dashboard/concepts.md": "4694f2366c1112f2aaeaf22d298d9195ef77ee969b9a9dc6bf4457c771cd319a",
     "knowledge/dashboard/conclusions.md": "08541d4e3b678c5da0faa348d9ba8bedb23a6ad2ed67a13f4bd3f329df426420",
@@ -43,23 +49,23 @@
     "knowledge/dashboard/topics/dynamic-fields.md": "577e72a22ef6216f3278a6d7c5ee67c74274aba9cd825d1fff79d0293e6817aa",
     "knowledge/dashboard/topics/filter-tree.md": "53a8edc62b2554a8fb3cd385aafaf60c671cdaa88107d120e9f193e4d1306dd5",
     "knowledge/dashboard/topics/name-binding.md": "280cbebbd672746968b9a8100c40f552e46d214a72917928a7db6dc49eb339a9",
-    "knowledge/dashboard/workflow.md": "9d808dca933f8290654bfe76d7523069f29171341f25637f70af75875df1d0f7",
+    "knowledge/dashboard/workflow.md": "bbea78ffd6c18ac5ea908091a958811dd3fda8e8abf6e3ecf91112a28e1a5146",
     "knowledge/dataset/README.md": "2d2e36262da86d920b4c09f57fe67b0957aedc13f2d1d3d49d3c8bfad0266c21",
     "knowledge/dataset/concepts.md": "87f90d101f20d0233ca4f524eabd9c128d6060c9a22e940b903708e411c698aa",
     "knowledge/dataset/conclusions.md": "010389c78d6d78aef9f4792e21ba5c78eecce4da2fe2b47e9ee35602babb8dcc",
     "knowledge/dataset/queries.md": "3bb528f46d9c9b692c1893c9a1cf91f5a5667ae2efd6adf603b635c515e2c4ef",
     "knowledge/dataset/signals.md": "ce6b2d7874d22b914ba6af958f7b57aa5abaa69788a7a1c57a64e7de59419a2b",
     "knowledge/dataset/topics/steps.md": "dbff53413a0d4e5da5da99453c13cafa21c59238abc8197d948804d484cd21a6",
-    "knowledge/dataset/workflow.md": "d4ebd3dcc2e1ada06dc49b21e5f2c1a4a83e31e6620c6a76fe749c78931c586a",
+    "knowledge/dataset/workflow.md": "c92bde69195eb6cdec34d3cf025524a4a6a7af6fabade2d937fa78bd5840948b",
     "knowledge/engine/README.md": "d76b005708218863fc4fd6657bf731a430cdcb896db7883bf240c5e820ac1ea7",
     "knowledge/engine/concepts.md": "544988cada6afad13ce1ea4f19869cfb39e76730b8cfe3f6fde06b86991130fc",
     "knowledge/engine/conclusions.md": "ae1e2c805bf19143ebc3e92ae14ec81f3f094acd3ca120069442a3bbb1ae2128",
-    "knowledge/engine/queries.md": "012b80344e86aec707da5e92c2be2e92034ef9fc94970d9a5ece3134ec60a90c",
+    "knowledge/engine/queries.md": "bbbdc523be86fd98b6df98958ff6fe03e2656673a20e1f27fb3e72861a058936",
     "knowledge/engine/signals.md": "02ab7e88dc3ae155a0623108d3023149229e5c64cf358e383df419e4983278b5",
-    "knowledge/engine/topics/metric-fields.md": "7a2ce80b478592c375dfe34c511ab3a1963462a536aac887053c04c3386744d1",
+    "knowledge/engine/topics/metric-fields.md": "2171f383a7c49b38ecf49ed9a0a726b87eaaac6da9f48f00140f6758dd26f458",
     "knowledge/engine/topics/patterns.md": "c45555888c59f6b485343587bfe949c1b8fd198bbd65ba3d29cb296cc343869b",
     "knowledge/engine/workflow.md": "9f2036a4f65e50b02879fbb261d1f51b56a0fbae54b5ceeedd645912ec1d20e8",
-    "knowledge/signal-index.md": "432dd65f10ef357cf4fb4368eacd75e8d2c43b17869d4e67f9e735a459a82ee3",
+    "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.20261107142011",
+  "version": "0.1.20261111014808",
   "description": "FX数据诊断：Agent 诊断技能、知识与本地脚本",
   "type": "module",
   "license": "UNLICENSED",