@fx-data/ai-diagnostics 0.1.20261109015953 → 0.1.20261111015837

package/AGENT_SETUP.md

@@ -1,6 +1,6 @@
 # FX 数据诊断：Agent 安装与管理
 
-本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261109015953`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
+本文供执行安装与管理的 Agent 读取，不作为日常诊断的前置上下文。包版本为 `0.1.20261111015837`，需要 Node.js `>=22` 及 npm。用户只需表达安装、使用、更新或卸载意图，环境准备和客户端登记由 Agent 完成。
 
 用户明确要求安装、更新、回退、卸载或检查 FX 数据诊断时，也会触发薄 Skill，并直接执行对应管理命令，不先运行 `context` 或读取诊断规则；只有开始诊断时才按薄 Skill 加载内容。普通聊天不主动加载。
 
@@ -56,7 +56,7 @@
 
 用户明确要求用 FX 数据诊断分析问题后，按薄 Skill 调用一次稳定入口的 `context`，读取返回的 `agent_rules`，只加载当前问题需要的 Skill 和引用。CLI 同时在后台检查更新，固定本次调查返回的版本与 `pinned_cli`；同一调查继续复用，不重复调用稳定入口的 `context`。普通聊天和管理请求无需预加载诊断内容或检查更新。
 
-已有 SigNoZ MCP 直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
+已有 SigNoZ 查询途径（MCP、Skill 等）直接复用；实时查询受阻时才按包内配置 Skill 处理，凭据只保存在本机。Python 按需准备；独立解释器可通过 `FX_DATA_DIAGNOSTICS_PYTHON` 指定绝对路径。
 
 ## 更新与回退
 

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.20261111015837/AGENT_SETUP.md) 完成安装与管理。已有本地包时，优先读取包内 `AGENT_SETUP.md`；本地 `.tgz` 只需读取 `package/AGENT_SETUP.md`。按命令结果简短反馈，成功即结束；只有失败或结果不完整时才排错。

package/bin/core-ai.mjs

@@ -189,7 +189,7 @@ context 返回当前版本、内容路径和 agent_rules。读取 agent_rules，
 
 context、status、session 的 auto_update.notification，以及 python 标准错误中 fx_data_diagnostics.auto_update.notification，是更新提示。有提示时按 message 简短告知用户；无新版不打扰。不为获取状态额外调用 CLI 或轮询；本轮没有后续 CLI 调用时，下次使用再补报。更新成功只影响下次新诊断，失败继续使用本次版本。
 
-当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。通过 session 获取临时目录，保存日志和 Metric 正文，不写入安装内容。只有包内 Python 脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 MCP 直接复用；实时查询受阻时才读取 setup-signoz-mcp。
+当前调查固定使用首次 context 返回的 node、pinned_cli 和内容版本。脚本通过 <node> <pinned_cli> python <脚本绝对路径> ... 执行；Windows PowerShell 同样在带引号的 Node 路径前加 &。通过 session 获取临时目录，保存日志和 Metric 正文，不写入安装内容。只有包内 Python 脚本需要 Python；doctor 的 python.available=false 表示按需补齐，不代表安装失败。已有 SigNoZ 查询途径（MCP、Skill 等）直接复用；实时查询受阻时才读取 setup-signoz-mcp。
 
 用户要求更新时执行稳定入口 update，默认使用 latest；要求回退到上次更新前时执行 rollback，也可用 --version 指定版本。已保留版本校验通过后直接复用。各客户端的新调查共用切换后的版本，进行中调查继续使用原 pinned_cli。更新后按客户端要求刷新技能或新开聊天；安装副本不做 Git 更新。
 

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 核对每次执行、跳过原因、动作结果与回填进度 |
 | 其他报错、结果异常或偶发不可用 | 核对现象与执行记录，整理已确认事实和待验证问题 |
 
 性能问题已有各场景的知识和入口提示。其他问题先根据现有材料辅助分析。
@@ -19,7 +20,7 @@
 npm 安装：对 Agent 说“帮我安装并启用 FX 数据诊断，npm 包是 `@fx-data/ai-diagnostics`”，它会按包内 README 安装（优先复用已有的共享安装），再登记当前客户端的 Skill。需要 Node.js/npm，Python 按需准备。安装副本每次新诊断时在后台检查更新，不耽误当前排查，更新失败继续用旧版（设计见源码仓库 `maintainers/npm-cli.md`）。
 
 1. 用源码目录时，用支持 `AGENTS.md` 的客户端（如 Codex、Claude Code）打开本仓库，更新规则见[助手执行契约](AGENTS.md#使用前更新代码)。
-2. 诊断要查 SigNoZ 的 trace、日志和引擎统计。还没有连接时助手会自动配置，只需提供对应环境的 API Key（正式、测试分开）。
+2. 诊断要查 SigNoZ 的 trace、日志和引擎统计。还没有连接时助手会自动安装和配置，只需按提示在本机配置里填入对应环境的 API Key（正式、测试分开），不要把 Key 发在对话里。
 3. 只有离线材料（日志、trace 导出、Metric 文件）时不用配置，直接交给助手。
 
 ## 如何提问
@@ -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 查
+
+**列出每次执行**（默认最近 3 天；按周或更长周期执行、3 天内没有记录时，再放宽到覆盖一个周期）：
+
+```text
+body CONTAINS '[Workflow] executor result' AND body CONTAINS '<workflowId>'
+```
+
+每行有 `scene`、`chainId`、`actionCount`、`failedCount`、`success` 和 `trace_id`。
+
+**看全部相关记录**，包括没走到执行的（跳过、前置失败、调度触发）：
+
+```text
+body CONTAINS '<workflowId>'
+```
+
+用日志搜索即可。时间窗越长越慢，放宽时也只做日志搜索，不要按 `body` 分组做多天聚合，容易超时。
+
+## 看单次执行
+
+拿到 `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 搜日志，默认看最近 3 天，先按 [`[Workflow] executor result`](signals.md#定时执行的时间线) 列出每次执行的时间、触发方式、动作数和失败数。按周或更长周期执行、3 天内没有记录时，再放宽到覆盖一个周期。
+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/concepts.md

@@ -13,7 +13,7 @@
 
 `prod` 和 `production` 不是正式环境的别名。`prod` 在后端语境里是测试 SigNoZ 实例下的一个服务子环境；`production` 目前没有确认过的含义，不参与自动识别。
 
-有的客户端只连一个 SigNoZ MCP，靠工具的 `env` 参数切环境：正式环境传 `work`，测试环境按下面后端子环境的名字传；`env=prod` 查的是测试实例，不是正式环境。
+访问途径不限于每个环境一个 MCP：有的 MCP、Skill 或其他工具一个就能查多个环境，靠环境参数或选项切换。按它自己的环境名和说明对上正式、测试实例，常见约定是正式环境叫 `work`；这类工具里的 `prod` 同样指测试实例下的子环境，不是正式环境。
 
 推荐 MCP 名称只是为了各客户端叫法一致。客户端已有别的稳定名称就保留，以连接信息里的 URL 为准；调用方式和参数以当前客户端实际提供的工具为准。已经确认的环境和本轮成功的查询直接复用，不因为工具前缀不同就重新安装或验证。
 
@@ -45,5 +45,5 @@ SigNoZ 实例和后端 `service.name` 是两层信息。查后端请求时两者
 - 缺时间时不顺带让用户选环境。时间等入口默认值见[公共查询规则](queries.md)的“默认值速查”。
 - 环境一旦确认，这次诊断的 trace、日志和 metric 都只查这个环境，不混用别的环境的数据。
 - `service.environment` 这类 attribute 只能在当前实例里过滤，代替不了选实例。
-- MCP 能读某个环境的 SigNoZ，不代表业务页面链接也有同样的权限。
+- 工具能读某个环境的 SigNoZ，不代表业务页面链接也有同样的权限。
 - 测试和正式环境的 API Key 分开维护，不能混用或互相覆盖。

package/content/knowledge/common/queries.md

@@ -15,7 +15,7 @@
 
 | 情况 | 默认处理 |
 |---|---|
-| 未指定环境 | 默认 work（正式环境），显式环境、URL 和已确认范围优先；映射见[环境选择规则](concepts.md)。SigNoZ 工具带 `env` 参数时，正式环境传 `work`；`prod` 是测试实例下的子环境，不是正式环境 |
+| 未指定环境 | 默认 work（正式环境），显式环境、URL 和已确认范围优先；映射见[环境选择规则](concepts.md)。工具能切多个环境时按它的环境名选正式环境（常见是 `work`）；`prod` 是测试实例下的子环境，不是正式环境 |
 | 普通对象（tableId、widgetId、reportId 等）没有时间 | 完全缺少时间时合并询问一次时间，不同时要求选择环境，不要默认最近 7 天 |
 | 企业更新没有时间或只说“最近” | 企业更新无时间默认最近 24 小时，告知后直接查询，优先核对异常 |
 | 只有 dagId | dagId 不先追问时间，由助手管理检索窗口，命中后按实际记录恢复链范围 |
@@ -25,7 +25,7 @@
 
 ## 选择和调用工具
 
-- 先列出已连接 SigNoZ 的工具名，只读这次要用的那个工具的说明；读过一次就复用，不要把全部工具说明都输出一遍。调用方式以客户端实际的工具声明为准，按[环境选择规则](concepts.md)核对目标 URL，工具前缀和推荐名称不一样不用重配。
+- 先确认当前可用的 SigNoZ 查询途径（MCP 工具、Skill 等），只读这次要用的那个工具的说明；读过一次就复用，不要把全部工具说明都输出一遍。调用方式以该途径实际的声明或说明为准，按[环境选择规则](concepts.md)核对目标 URL，工具前缀和推荐名称不一样不用重配。
 - **已有 traceId 时**，便捷的 span 搜索和详情工具只返回 span 名、耗时、错误这些基本列，不带 `taskName`、`metric`、`data.request_context` 这类自定义 attribute。按这个顺序取：
   1. 日志按 `trace_id` 查一次，常常就能拿到报错原文、引擎任务 ID 和请求结束时间，比翻 trace 便宜。
   2. span 搜索按 `trace_id` 加 `has_error = true`、span 名或 `duration_nano` 取关键的几条 span，看时间线和错误。
@@ -46,6 +46,7 @@
 | tableId、widgetId、reportId 等资源 ID | 按默认或显式环境及发生时间，使用场景入口、服务和资源 attribute 寻找候选执行 |
 | 企业 ID（更新查询） | 复用已有时间；未提供时告知默认最近 24 小时后直接查询，先给更新概况并优先核对异常 |
 | dagId | 按更新链标识精确发现提交与节点，不要求用户先补时间或 trace；检索时间见[更新发现指引](../update/topics/discover-executions.md#检索时间) |
+| workflowId（自动化） | 未提供时间时默认最近 3 天，按日志正文精确查，见[按 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/topics/setup-signoz-mcp.md

@@ -1,6 +1,6 @@
 # 配置 SigNoZ MCP
 
-为当前 Agent 客户端配置 SigNoZ 只读访问。诊断需要实时查 SigNoZ，但当前客户端没有工具、无法启动、环境不明确、鉴权失败或只读查询不可用时读；已有可用的 SigNoZ 工具或只有离线材料时不需要。正常首次配置只向用户请求缺少的 API Key，安装模式、发行包、MCP 名称和配置格式由助手按当前环境确定。本主题只恢复 SigNoZ 访问能力，不分析业务问题；完成后回到原调查继续。
+为当前 Agent 客户端配置 SigNoZ 只读访问。诊断需要实时查 SigNoZ，但当前客户端没有工具、无法启动、环境不明确、鉴权失败或只读查询不可用时读；已有可用的 SigNoZ 查询途径（MCP、Skill 或其他工具，一个途径查多个环境也算）或只有离线材料时不需要。正常首次配置只需用户在本机填入缺少的 API Key，安装模式、发行包、MCP 名称和配置格式由助手按当前环境确定。本主题只恢复 SigNoZ 访问能力，不分析业务问题；完成后回到原调查继续。
 
 ## 目录
 
@@ -14,20 +14,20 @@
 ## 默认流程
 
 1. 确认目标环境：用户输入、现有配置或[环境知识](../concepts.md)，没指定就用 work，不让用户先选。`work` 是正式环境，`prod` 不是；不按工具顺序或 `service.environment` 猜实例。URL 和口头说法冲突时只让用户确认“测试环境”还是“正式环境”，确认前不写配置。默认连接不可用就修它，不改用测试环境。
-2. 当前客户端已有能确认目标 URL 的 SigNoZ 工具，就跳过安装配置（推荐名称不同不重配），做一次最小只读验证就回原任务；本轮已有成功查询直接复用。
+2. 当前客户端已有能查目标环境的 SigNoZ 途径，就跳过安装配置：不限于 MCP，Skill 或一个工具切多个环境都算，能从 URL 或它的环境名对上正式、测试即可（推荐名称不同不重配），做一次最小只读验证就回原任务；本轮已有成功查询直接复用。
 3. MCP Server 缺失或损坏时，简短告知尚未安装，按“安装 MCP Server”默认安装适配当前系统和 CPU 的产物，不让用户确认版本、下载源或路径。
-4. 没有目标环境的有效凭据时只请求一次 API Key，环境能唯一确定就一并说明，不再问 URL 或 MCP 名称。用户提供 API Key 就表示同意写入本次目标环境的配置，不再追加配置确认，直接按“接入当前客户端”配好。
-5. 重载并做最小只读验证；客户端必须由用户 Trust、启用或重启时，只提示这一步。成功后立即回到原调查，不把安装变成独立任务。
+4. 没有目标环境的有效凭据时，按“接入当前客户端”把配置写好，Key 位置留占位符，再请用户在本机填入一次，环境能唯一确定就一并说明，不再问 URL 或 MCP 名称，不再追加配置确认。不在对话里索取 Key：对话内容会发给模型服务并留在会话记录里。
+5. 用户填好后重载并做最小只读验证；客户端必须由用户 Trust、启用或重启时，只提示这一步。成功后立即回到原调查，不把安装变成独立任务。
 
 只配置当前正在运行的 Agent 客户端，不要因为发现 Cursor、Codex、WorkBuddy 等其他客户端的配置文件就切换目标。只有环境确定不了、平台不支持、同名配置冲突或配置方式确实判断不了时，才请用户补最小的信息。
 
 ## 交互与结果
 
 - 正常成功路径只说明 MCP 已准备好并继续原任务；不主动展示 checksum、压缩包、安装目录、完整配置或排障过程。
-- 安装后等待 Key 时，直接说明“当前没有可用的 SigNoZ MCP，已经完成安装，请提供 `<环境>` 的 API Key 以继续配置和诊断”。
-- 不回显用户提供的 API Key，也不把它写入仓库、知识、fixture 或报告；只写入当前客户端支持的本机配置。
+- 等待 Key 时，直接说明“当前没有可用的 SigNoZ MCP，已经完成安装和配置，请在 `<配置文件路径>` 填入 `<环境>` 的 API Key，填好后告诉我继续诊断”。
+- 用户仍把 Key 发在了对话里：不回显，按原流程写入本机配置，并提醒对话记录里已有这个 Key，建议诊断结束后在 SigNoZ 重新生成。
+- API Key 不写入仓库、知识、fixture 或报告，只存在当前客户端的本机配置或用户自己的环境变量里；配好一次后续诊断直接复用。
 - 失败时说明准确阻断和下一项最小动作，不用重装掩盖环境、凭据、权限或网络问题。
-
 ## 安装 MCP Server
 
 仅在 MCP Server 或客户端配置缺失、损坏时执行。安装程序不接收 SigNoZ URL 和 API Key，也不修改客户端配置。
@@ -41,9 +41,11 @@ python3 scripts/install_signoz_mcp.py
 Windows 使用系统自带 PowerShell，不依赖 Python：
 
 ```powershell
-powershell.exe -File scripts\install_signoz_mcp.ps1
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\install_signoz_mcp.ps1
 ```
 
+Windows 桌面版默认禁止运行脚本，`-File` 同样受限；`-ExecutionPolicy Bypass` 只作用于这一次进程，不修改系统设置。
+
 当前工作目录不是内容根目录时使用脚本的绝对路径。只有需要改变默认用户级安装目录时才传入 `--install-dir <absolute-directory>`（PowerShell 为 `-InstallDir <absolute-directory>`）。
 
 脚本会自动：
@@ -65,10 +67,11 @@ powershell.exe -File scripts\install_signoz_mcp.ps1
 server name     -> 目标环境对应的稳定名称
 command         -> 安装脚本返回的绝对路径
 SIGNOZ_URL      -> 已确认的 SigNoZ 地址
-SIGNOZ_API_KEY  -> 使用者提供的该环境凭据
+SIGNOZ_API_KEY  -> 占位符，由使用者自己填入该环境的凭据
 ```
 
-- Key 用客户端支持的本机持久方式保存，不回显，不写进仓库、项目配置、知识、fixture 或报告。
+- 默认写入当前客户端的用户级配置文件并留占位符，告诉用户文件路径和要填的字段，用户在助手之外（编辑器或自己的终端）填写，不经过对话。只有用户本来就用环境变量管理 Key 时才在配置里引用环境变量：从 Dock、开始菜单等图形界面启动的客户端常读不到 shell 配置里的变量，表现为配好了仍报 401。
+- 不写进仓库、项目配置、知识、fixture 或报告。
 - 测试和正式环境分别配置，不复用或覆盖凭据；默认连接缺凭据时只要该环境的 Key，不改用已可用的其他环境。
 - 增量修改已有配置，保留无关的 server 和字段；支持工具 allowlist 时只启用诊断需要的只读工具。
 
@@ -80,7 +83,7 @@ SIGNOZ_API_KEY  -> 使用者提供的该环境凭据
 |---|---|
 | 客户端看不到工具 | 配置是否加载、server 是否启用、是否需要重载 |
 | server 启动失败 | command、文件存在性、平台架构、执行权限 |
-| 401 | 没有凭据或凭据无效；URL 与凭据是否属于同一环境，只请求目标环境的 Key，不换用其他环境的 Key |
+| 401 | 没有凭据或凭据无效；URL 与凭据是否属于同一环境，只请用户补填目标环境的 Key，不换用其他环境的 Key |
 | 403 | 凭据有效但角色不够，只读查询至少需要 Viewer 级别；请使用者换用有读取权限的 Key |
 | 工具存在但报字段 / schema 错误 | 工具版本与说明不一致；重新读取当前工具声明或修复 MCP 版本，不沿用旧参数硬试 |
 | 查询不到目标数据 | 精确 ID、时间与环境是否正确 |

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,31 +1,37 @@
 {
   "schema_version": 1,
-  "version": "0.1.20261109015953",
-  "source_commit": "408a99053c5d8a3974331e546f154cb06d081cb8",
+  "version": "0.1.20261111015837",
+  "source_commit": "47e06c5b36165aac9fdbe9f6c09d227534f34726",
   "source_dirty": false,
-  "cli_sha256": "08aa66f145e51627bf71c9e12ec7ae01907e130ad9ce6056b2ea37262ce92be0",
+  "cli_sha256": "4a153c76eb03a90bcec67a5431d471cbdda09a1e7188bb6cefee818d43e89e26",
   "files": {
-    "AGENTS.md": "32bc0682d0b83e8359ca33b48a300348803916c102def8bacac8182a01cc04b2",
-    "README.md": "ec972703b6416ccf7b0f516afed1f9598c69e270731d4f00a5f836fffe5499a1",
+    "AGENTS.md": "674f7657f5ab6167154bd910d344c5bdb850a5c0598191d5f33b2976550badf3",
+    "README.md": "257068afe391bfe233d5bf0d7f3aa14136ad98bd3f1c49d427bd1a839240f1f7",
     "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": "288fe923b9b188584a3675cb50bd4d40141e8b3bbd1fc91fee993b4e63bbcaa6",
+    "knowledge/automation/signals.md": "52f2fd37beb655b06a5a3944418161bfacb46615a25ded952383fc58e6715742",
+    "knowledge/automation/workflow.md": "9453650fc096dd827a26f6a1ed657c71900291ac637db00c081db539b594930d",
     "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/concepts.md": "fa707268df82ec97203e8567cfaa080723416c7c837aacf2a3578ad77428cb87",
     "knowledge/common/conclusions.md": "3b91199925f4e3743aa2ac895e86390375adcb3c890bee27ba6dadd6e8f8adb0",
-    "knowledge/common/queries.md": "f9d4f759dcc3084b6e6598470b8d9e6473ad334afe5942b48170ccf570aaebf4",
-    "knowledge/common/signals.md": "33b9ecd96825f0e932d2e720139723b79f2b8e0347e3db098a90198ae0e019d1",
+    "knowledge/common/queries.md": "555118d24e121d453220a0ea526653e22798956234ed6fed51c4ece195cf0168",
+    "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",
     "knowledge/common/topics/query-budget.md": "d015d1414b96aa9e2d293892bf4ef262de7b0892be7a6b236ed108424e1cdfaa",
     "knowledge/common/topics/query-example.md": "1f94c3d1f5dac77936ecb88f023a123fcaae228dd00303801a62ee94a3706cd1",
-    "knowledge/common/topics/setup-signoz-mcp.md": "f5de34eed827f338bc8733eae8dc1faf0f78eb3ff88a8fc2cee54eff73160242",
+    "knowledge/common/topics/setup-signoz-mcp.md": "1172ed7719deef1902d017d725c9a5996dfac52073ecf6810e8885bfb4c3db8b",
     "knowledge/common/topics/start-and-anchors.md": "97fc86edd62eff227274e8a027a19a23dce60cfd999f7b5e480fdd4f8adee254",
     "knowledge/common/workflow.md": "dc8dbcefa4967fc7f3dfcd575753486149068644bffb86fba5cb6541b9841336",
     "knowledge/component/README.md": "d0d99e14f9f36d74216306c892730f3fba838a01e40c7565e5bec53d28f09fda",
@@ -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.20261111015837",
   "description": "FX数据诊断：Agent 诊断技能、知识与本地脚本",
   "type": "module",
   "license": "UNLICENSED",