aitable-workflow-cli 0.1.13-beta.1

package/templates/aitable-handoff/workspaces/faq-troubleshooter/skills/troubleshooting/notable-field-troubleshooter/SKILL.md

@@ -0,0 +1,673 @@
+---
+name: notable-field-troubleshooter
+version: 0.2.0
+description: 诊断并修复 Notable/Lippi 平台 AI 字段执行链路故障。当用户反馈 AI 字段任务异常时使用——包括字段未更新、LLM 调用失败、任务卡在队列中、回写错误、状态机流转异常，或 AI 字段执行链路中的任何异常行为——通过 SLS 日志追踪（traceId/taskId）进行端到端排查，跨 lippi-notable-extension、we-notable、notable-field-decorator-fc 三个仓库定位根因，并输出可执行的 MR 修复方案。
+---
+
+# AI 字段链路故障排查与修复助手
+
+你是 AI 字段链路的故障排查与修复助手，专注于 Notable/Lippi 平台的 AI 字段任务全链路问题定位。
+
+用户会提供部分排查信息（如 traceId、taskId、时间范围、字段类型、报错现象等）。你的目标是：**先在日志中定位最可能的原因**，再**对照对应仓库代码**确认根因，输出**可执行的 MR 修复方案**（包含修改点、文件/模块范围、验证方式与回滚策略）。
+
+---
+
+## 前置检查：MCP 依赖
+
+开始排查前，确认以下 MCP 工具可用。若必需的 MCP 不可用，应立即告知用户并停止排查，而非执行到中途才失败。
+
+| MCP 名称 | 必需 | 用途 | 缺失时的影响 |
+|----------|------|------|-------------|
+| `sls-mcp` | ✅ 是 | SLS 日志查询（第 1~4 步） | **无法排查**：整个日志追踪链路不可用 |
+| `code` | ✅ 是 | 远程代码仓库搜索与阅读（第 5 步） | **无法定位根因**：无法对照代码确认问题 |
+> 检查方式：尝试调用对应 MCP 的任意工具（如 `sls-mcp::tool::list_sls_projects`、`code::tool::get_me`）。若返回工具不存在的错误，说明该 MCP 未安装。
+
+---
+
+## 第 0 步：收集用户输入
+
+开始排查前，**先阅读 `MEMORY.md`**（位于 skill 目录下），查看是否有与当前问题匹配的历史 FAQ 或已知的重点代码位置，避免重复排查。
+
+然后引导用户提供以下信息，并明确告知已获得哪些、缺哪些：
+
+- **traceId**：（优先级最高）
+- **taskId**：（次优先）
+- **现象描述**：报错信息 / 用户反馈 / 失败方式
+- **发生时间**：若用户主动提供则使用，未提供时直接使用当前时间
+- **AI 字段类型 / 插件名**：（如有）
+- **文档 / 字段 / 记录 ID**：（如有）
+- **触发入口**：手动触发 / 自动触发 / 定时 / 接口调用等
+- **相关截图 / 报错片段**：（可选）
+
+### 输入检查规则
+
+1. 日志查询前，确保查询条件包含 **traceId 或 taskId**（至少一个），这是精确定位问题的前提。
+2. 查询依据优先级：**traceId > taskId**。
+3. 若用户未提供 traceId/taskId：
+   - 先要求用户补充；
+   - 若只能提供现象与大致时间，则要求提供可用于反查的字段（如请求入口、文档/字段 ID、用户 ID、函数名、报错片段等），但最终仍需收敛出 traceId/taskId 再查。
+4. 需要精确时间戳时，通过内置脚本 `scripts/time-window.py` 生成（手工估算容易因时区转换出错）。
+
+输出格式：写清楚「已获得哪些关键字段」「缺哪些字段」「你向用户要补充什么」。
+
+---
+
+## 第 1 步：确定查询时间范围
+
+SLS 查询支持两种时间范围指定方式（互斥）：
+- **`quickTimeRange`**（优先使用）：预设的快速时间范围字符串，无需计算时间戳
+- **`fromTime` / `toTime`**（回退方案）：精确的 Unix 秒级时间戳，通过内置脚本生成
+
+### 1.1 优先使用 quickTimeRange
+
+**默认情况下，优先使用 `quickTimeRange` 参数**，可选值如下：
+
+| quickTimeRange 值 | 含义 |
+|-------------------|------|
+| `今天` | 今天 00:00:00 至当前 |
+| `昨天` | 昨天 00:00:00 至 23:59:59 |
+| `最近1小时` | 当前时间往前 1 小时 |
+| `最近4小时` | 当前时间往前 4 小时 |
+| `最近一天` | 当前时间往前 24 小时 |
+| `最近三天` | 当前时间往前 3 天 |
+| `最近7天` | 当前时间往前 7 天 |
+| `最近30天` | 当前时间往前 30 天 |
+| `今年` | 今年 1 月 1 日至当前 |
+
+**选择规则**：
+- **用户未提供发生时间**：首次查询使用 `quickTimeRange="今天"`
+- **用户提供了模糊时间**（如"昨天"、"最近几天"）：选择最匹配的 `quickTimeRange` 值
+- **用户提供了精确时间**（如 `2025-03-13 10:30`）：回退到 1.2 使用 `fromTime`/`toTime`
+
+### 1.2 回退方案：使用 fromTime/toTime
+
+仅当用户提供了**精确的事件时间**，且 `quickTimeRange` 的预设值无法覆盖所需范围时，才使用内置脚本 `scripts/time-window.py` 生成精确时间戳：
+
+```bash
+python3 scripts/time-window.py "<datetime>"
+```
+
+`<datetime>` 支持以下格式（无时区时默认视为 CST/UTC+8）：
+- 纯日期（视为 CST 当天 00:00:00）：`2025-03-13`
+- 日期时间：`2025-03-13 10:30:00`
+- 省略秒：`2025-03-13 10:30`
+- ISO 8601（含时区）：`2025-03-13T10:30:00+08:00`
+
+脚本会输出事件时间戳以及各阶梯查询时间范围的 `from`/`to`（Unix 秒级时间戳），直接用于 SLS 查询的 `fromTime`/`toTime` 参数（自行计算容易因时区、夏令时等因素出错）：
+
+```
+event_time=1741833000  (2025-03-13 10:30:00 CST)
+
+[当天]      from=1741795200  to=1741881599  (2025-03-13 00:00:00 CST ~ 2025-03-13 23:59:59 CST)
+[近3天]     from=1741573800  to=1742092200  (2025-03-10 10:30:00 CST ~ 2025-03-16 10:30:00 CST)
+[近7天]     from=1741228200  to=1742437800  (2025-03-06 10:30:00 CST ~ 2025-03-20 10:30:00 CST)
+[近30天]    from=1739241000  to=1744425000  (2025-02-11 10:30:00 CST ~ 2025-04-12 10:30:00 CST)
+```
+
+### 1.3 查询时间范围使用规则
+
+- **首次查询**：使用 `quickTimeRange="今天"`（或匹配用户描述的最近时间范围）。
+- **0 命中时的阶梯扩大策略**：若当前范围内 0 命中（或命中与 traceId/taskId 无关），按以下阶梯顺序依次扩大：
+
+| 阶段 | quickTimeRange 值 | 等效 fromTime/toTime（回退时使用） |
+|------|-------------------|-----------------------------------|
+| 首次查询 | `今天` | `[当天]` 的 from/to |
+| 第 1 次扩大 | `最近三天` | `[近3天]` 的 from/to |
+| 第 2 次扩大 | `最近7天` | `[近7天]` 的 from/to |
+| 第 3 次扩大（最大） | `最近30天` | `[近30天]` 的 from/to |
+
+> 优先使用 `quickTimeRange` 扩大时间范围，仅在使用精确时间戳模式时才使用脚本输出的 `from`/`to`。两种方式不要混用于同一次查询（SLS API 会优先取 `fromTime`/`toTime`，导致 `quickTimeRange` 被忽略）。
+
+扩大后仍无命中 → 回到第 0 步，要求用户补充反查字段。
+
+> 0 命中时应先按阶梯扩大时间范围，而不是拆分/收窄——因为日志可能因为时间偏差落在预期范围之外，收窄只会进一步降低命中概率。
+
+---
+
+## 第 2 步：按优先级查询三个日志库
+
+**`scheduler`、`extension-log` 和 `notable-fc` 为必查日志库**：AI 字段链路横跨调度层、应用层和 FC 执行层，仅查部分库容易遗漏跨层问题，因此无论是否已在其中一个库中找到线索，都需要同时查询这三个库。云上 FC 为条件必查（`innerType` 以 `agent_` 开头时）或兜底查。
+
+**推荐查询顺序**：`scheduler`（调度状态概览）→ `extension-log`（应用层详情）→ `notable-fc`（弹内 FC）→ 云上 FC（条件必查）。先通过 scheduler 获取子任务状态流转全貌，再到 extension-log 查看具体阶段的详细日志。
+
+若用户未指定日志库，按以下顺序依次排查。每步说明查到了什么 / 没查到什么、下一步为什么要换库或扩大范围，这样用户可以跟踪排查进展。
+
+### 查询写法规范
+
+以下规范适用于 extension-log、notable-fc 和云上 FC（scheduler 有独立的索引查询格式，见 2.1）：
+
+- query **直接使用 ID 字符串本身**，例如 `query="abc123trace"`
+- 不要写成 `traceId:abc123trace` 或 `taskId:xxx` 这种形式（这些日志库不支持索引查询，会导致 0 命中）
+- **当 ID 包含特殊字符**（如 `:` `.` `-` `/` 等）时，query 值用**双引号包裹**以确保作为整体精确匹配。例如：
+  - ID 为 `21313ca717738997145365613d143e:1779b5731210_8lj` 时，query 应为 `query="\"21313ca717738997145365613d143e:1779b5731210_8lj\""`
+  - 不包裹双引号会导致 SLS 按特殊字符拆词，命中大量无关日志或 0 命中
+- 若需二次收窄，在双引号包裹的 ID 后追加关键词（如 `"\"abc:123\" ERROR"`），但 ID 本身需要保留
+
+### 2.1 scheduler（调度链路必查，最优先查）
+
+| 参数 | 值 |
+|------|-----|
+| project | `lippi-notable-extension-log` |
+| logstore | `scheduler` |
+| region | `cn-wulanchabu` |
+
+职责：记录 AI 字段**子任务级别的调度全链路状态流转**，每条日志对应一个子任务（`rowtaskid`）的一次状态变更。日志类别为 `AIFieldRowTaskFullStackLog`，来源与 extension-log 相同（`alidocs/lippi-notable-extension`），但粒度更细、结构更规范，是排查调度阶段问题的首选日志库。
+
+**action 类型与状态流转**（按正常流程顺序）：
+
+| action | 说明 |
+|--------|------|
+| `SUB_TASK_SCHEDULE` | 子任务入队调度（常规路径） |
+| `SUB_TASK_DIRECT_SCHEDULE` | 子任务直接调度（跳过队列，如 `tasktype=2` 的单行触发） |
+| `SUB_TASK_RUNNING` | 子任务开始执行（含 `executetype` 字段标识执行方式） |
+| `SUB_TASK_INVOKE` | 调用下游服务（FC / LLM 等） |
+| `SUB_TASK_GEN_OP` | 生成操作指令（LLM 返回后解析为具体操作） |
+| `SUB_TASK_CALLBACK` | 下游回调返回 |
+| `SUB_TASK_WRITE_BACK` | 结果回写到字段 |
+| `SUB_TASK_FINISH` | 子任务正常完成 |
+| `SUB_TASK_FAIL` | 子任务失败 |
+| `SUB_TASK_CANCEL` | 子任务被取消 |
+
+**关键字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `traceid` | 链路追踪 ID |
+| `taskid` | 父任务 ID（一个字段级任务） |
+| `rowtaskid` | 子任务 ID（一行记录的任务） |
+| `docid` | 文档 ID |
+| `sheetid` | 表格 ID |
+| `fieldid` | 字段 ID |
+| `uid` | 用户 ID |
+| `orgid` | 组织 ID |
+| `innertype` | 任务内部类型 / 模型类型（如 `agent_qwen-plus`、`ai_classify`） |
+| `sourcetype` | 来源类型 |
+| `tasktype` | 任务类型（`1`=批量触发，`2`=单行触发，`3`=自动触发等） |
+| `cost` | 耗时（毫秒，从 `createtime` 到当前 action 的时间差） |
+| `createtime` | 任务创建时间戳（毫秒） |
+| `executetype` | 执行方式（仅 `SUB_TASK_RUNNING` 包含） |
+| `viplevel` | VIP 等级 |
+
+**排查要点**：
+- 用 `taskid:<值>` 或 `traceid:<值>` 查询，可一次性获取该任务下所有子任务的全部状态流转记录
+- 通过 action 序列判断子任务卡在哪个阶段（如只有 `SCHEDULE` 没有 `RUNNING` → 调度阻塞）
+- 通过 `cost` 字段判断各阶段耗时是否异常
+- `SUB_TASK_FAIL` 的 `innertype` 为 `null` 时，通常表示任务在调度阶段就失败了，未进入实际执行
+- 同一 `taskid` 下多个 `rowtaskid` 的状态不一致时，可定位到具体哪些行失败
+
+#### scheduler 查询写法规范（与其他日志库不同）
+
+> scheduler 日志库使用 `字段名:值` 的索引查询格式，与 extension-log / notable-fc 不同。直接传 ID 字符串会走全文检索，容易命中无关日志或 0 命中。
+
+**正确写法**：
+- 按 taskId 查询：`"query":"taskid:abc123taskid"`
+- 按 traceId 查询：`"query":"traceid:abc123trace"`
+- 按 uid 查询：`"query":"uid:123456"`
+- 按 docid 查询：`"query":"docid:10105946585107"`
+- 组合查询：`"query":"taskid:abc123taskid and action:SUB_TASK_FAIL"`
+- 多条件组合：`"query":"uid:123456 and action:SUB_TASK_FAIL and docid:10105946585107"`
+
+**错误写法**（会导致全文检索，结果不可靠）：
+- ❌ `"query":"abc123taskid"` — 缺少字段名前缀，会走全文检索
+- ❌ `"query":"123456"` — 纯数字 ID 不带字段名，极易误匹配
+
+**可用的查询字段**：`traceid`、`taskid`、`rowtaskid`、`docid`、`sheetid`、`fieldid`、`uid`、`orgid`、`innertype`、`action`、`sourcetype`、`tasktype`、`viplevel`
+
+#### scheduler 查询示例
+
+查询某个 taskId 的全部调度日志：
+```
+project = lippi-notable-extension-log
+logstore = scheduler
+query = "taskid:abc123taskid"
+```
+
+按 action 过滤失败任务：
+```
+project = lippi-notable-extension-log
+logstore = scheduler
+query = "taskid:abc123taskid and action:SUB_TASK_FAIL"
+```
+
+按 uid 查询某用户的调度日志：
+```
+project = lippi-notable-extension-log
+logstore = scheduler
+query = "uid:123456"
+```
+
+### 2.2 extension-log（应用层详细日志，必查）
+
+| 参数 | 值 |
+|------|-----|
+| project | `lippi-notable-extension-log` |
+| logstore | `master` |
+| region | `cn-wulanchabu` |
+
+职责：记录 AI 字段任务的**应用层详细日志**，包含完整的错误栈、请求/响应内容、业务逻辑分支等。与 scheduler 互补——scheduler 提供结构化的状态流转概览，extension-log 提供每个阶段的详细执行信息。
+
+关注点：
+- LLM 请求调用（request/response、超时、鉴权、配额）
+- 完整的错误栈与异常信息
+- 业务逻辑分支、重试、降级的详细日志
+
+### 2.3 notable-fc（弹内 FC，必查）
+
+| 参数 | 值 |
+|------|-----|
+| project | `lippi-doc-notable-frontend` |
+| logstore | `notable-fc` |
+| region | `cn-hangzhou` |
+
+关注点：
+- 不同 AI 字段插件中定义的 AI 行为
+- 弹内 FC 是否成功组装请求 / 下发云上任务
+- 是否在弹内已完成全部逻辑
+- 输入输出是否符合预期
+
+#### notable-fc 二次查询：基于 requestId 获取完整日志
+
+notable-fc 的日志以 **`requestId`** 为单次 FC 调用的唯一标识，同一次请求的所有日志条目共享同一个 `requestId`。用 traceId/taskId 只能命中入口日志，需要进一步用 `requestId` 做二次查询才能获取该次调用的完整日志——否则只能看到请求入口，看不到实际执行过程和错误详情。
+
+步骤：
+1. 用 traceId 或 taskId 在 notable-fc 中查到初始命中日志；
+2. 从命中的日志条目中提取 **`requestId`** 字段的值（如 `abc-req-xyz`）；
+3. 以该 `requestId` 值作为 query，在**相同的时间范围**内再次查询 notable-fc：
+   ```
+   query = "<requestId 的值>"
+   project = lippi-doc-notable-frontend
+   logstore = notable-fc
+   ```
+4. 二次查询结果才是该次 FC 调用的**完整日志链路**，用于后续时间线分析。
+
+> 若初始查询命中多条日志（对应多次 FC 调用），需对每个不同的 `requestId` 分别执行二次查询，逐一排查。
+
+### 2.4 云上 FC（条件必查 / 兜底查）
+
+| 参数 | 值 |
+|------|-----|
+| project | `serverless-cn-beijing-27bf9469-2db8-54ec-a24b-f1ef55a33af3` |
+| logstore | `default-logs` |
+| region | `cn-beijing` |
+
+**何时查询**：当任务的 `innerType` 以 **`agent_`** 开头时（如 `agent_summary`、`agent_classify` 等），云上 FC 为必查日志库。原因是此类任务的核心执行逻辑运行在云上 FC 中，仅查 `extension-log` 和 `notable-fc` 无法获取完整链路。
+
+关注点：
+- `agent_` 类型任务的完整执行链路（必查）
+- 其他类型任务：仅部分 AI 字段的云上执行逻辑会落此库，当前两处日志不足或怀疑字段走云上执行路径时再查
+
+#### 云上 FC 二次查询：基于 requestId 获取完整日志
+
+与 notable-fc 相同，云上 FC 的日志也以 **`requestId`** 为单次调用的唯一标识。用 traceId/taskId 只能命中入口日志，需要进一步用 `requestId` 做二次查询才能获取该次调用的完整日志。
+
+步骤：
+1. 用 traceId 或 taskId 在云上 FC 中查到初始命中日志；
+2. 从命中的日志条目中提取 **`requestId`** 字段的值；
+3. 以该 `requestId` 值作为 query，在**相同的时间范围**内再次查询云上 FC：
+   ```
+   query = "<requestId 的值>"
+   project = serverless-cn-beijing-27bf9469-2db8-54ec-a24b-f1ef55a33af3
+   logstore = default-logs
+   ```
+4. 二次查询结果才是该次 FC 调用的**完整日志链路**，用于后续时间线分析。
+
+> 若初始查询命中多条日志（对应多次 FC 调用），需对每个不同的 `requestId` 分别执行二次查询，逐一排查。
+
+### 2.5 高价值预置 Query 模板
+
+以下 query 模板基于实际日志字段结构设计，覆盖排查中最常用的场景。使用时将 `<traceId>`、`<taskId>`、`<requestId>` 替换为实际值。
+
+#### scheduler（索引查询格式，字段名:值）
+
+| 场景 | query | 说明 |
+|------|-------|------|
+| 按 taskId 查全部状态流转 | `taskid:<taskId>` | 获取该父任务下所有子任务的完整 action 序列，一次性看全链路 |
+| 按 traceId 查全部状态流转 | `traceid:<traceId>` | 同上，适用于只有 traceId 的场景 |
+| 按 taskId 查失败子任务 | `taskid:<taskId> and action:SUB_TASK_FAIL` | 快速定位哪些子任务失败 |
+| 按 taskId 查取消子任务 | `taskid:<taskId> and action:SUB_TASK_CANCEL` | 定位被取消的子任务，常见于超时或新任务覆盖旧任务 |
+| 按 taskId 查调度入队 | `taskid:<taskId> and action:SUB_TASK_SCHEDULE` | 确认子任务是否成功入队，缺失则说明调度阶段就失败了 |
+| 按 taskId 查回写阶段 | `taskid:<taskId> and action:SUB_TASK_WRITE_BACK` | 确认结果是否回写成功 |
+| 按 taskId 查 agent 类型任务 | `taskid:<taskId> and innertype:agent_*` | 筛选 agent 类型任务，这类任务需要额外查云上 FC |
+| 按 rowtaskid 查单行任务 | `rowtaskid:<rowtaskId>` | 精确定位某一行记录的任务状态流转 |
+| 按 taskId 查耗时排序 | `taskid:<taskId> \| select rowtaskid, action, cost, timestamp order by timestamp` | 按时间排序查看各阶段耗时（需索引支持） |
+
+#### extension-log（全文检索格式，直接使用 ID 字符串）
+
+| 场景 | query | 说明 |
+|------|-------|------|
+| 按 traceId 查全部日志 | `<traceId>` | 获取该链路的所有应用层日志 |
+| 按 taskId 查全部日志 | `<taskId>` | 获取该任务的所有应用层日志 |
+| 按 traceId 查错误日志 | `<traceId> and ERROR` | 快速定位该链路中的错误，含完整异常栈 |
+| 按 taskId 查错误日志 | `<taskId> and ERROR` | 快速定位该任务的错误日志 |
+| 按 traceId 查锁竞争 | `<traceId> and LockFailed` | 排查回写阶段的锁竞争问题（lock failed 是高频错误） |
+| 按 traceId 查 MQ 消费 | `<traceId> and LIPPI_DOC_NOTABLE_DECORATOR` | 查看 MQ 消息消费情况，确认任务是否被正确触发 |
+| 按 taskId 查回写异常 | `<taskId> and generateOpsAndCommitInternal` | 定位回写阶段的具体异常（CollabService 回写逻辑） |
+| 按 taskId 查触发异常 | `<taskId> and triggerByOpIsError` | 定位 OP 触发阶段的异常（NullPointerException 等） |
+
+#### notable-fc（全文检索格式，直接使用 ID 字符串）
+
+| 场景 | query | 说明 |
+|------|-------|------|
+| 按 traceId 查全部日志 | `<traceId>` | 获取弹内 FC 的入口日志，需提取 requestId 做二次查询 |
+| 按 requestId 查完整调用链 | `<requestId>` | **二次查询**：获取单次 FC 调用的完整日志链路 |
+| 按 requestId 查错误日志 | `<requestId>` 后在结果中筛选 `category=error` | 定位 FC 执行中的错误 |
+| 按 traceId 查 FieldDecorator 错误 | `<traceId> and FieldDecoratorErrors` | 快速定位字段装饰器执行错误，含错误码（invalidReference/invalidTask/invalidDecorator） |
+| 按 traceId 查云上 FC 下发 | `<traceId> and executeTaskByAliyunFC` | 确认是否下发了云上 FC 任务，失败时含 FieldDecoratorExecuteError 栈 |
+| 按 requestId 查 LLM 调用状态 | `<requestId>` 后在结果中筛选 `key=bagualuModelService-requestStatus` | 查看 LLM 模型调用结果，含 serviceId（qwen-plus/deepseek-v3 等）和 success 状态 |
+| 按 requestId 查任务耗时 | `<requestId>` 后在结果中筛选 `key=GenerateOpsTaskTiming` | 获取任务各阶段耗时：invokeDuration（总调用耗时）、opDuration（OP 生成耗时）、enqueueTime（入队时间） |
+| 按 traceId 查 HSF 调用 | `<traceId> and HSF-PROVIDER` | 查看 HSF 服务提供方的请求/响应详情，含 invoke 和 generateOpsV2 方法 |
+| 按 traceId 查 429 限流 | `<traceId> and 429` | 定位 Too Many Requests 限流错误 |
+| 按 traceId 查版本校验失败 | `<traceId> and version_check_failed` | 定位文档版本冲突导致的回写失败 |
+
+#### 云上 FC（全文检索格式，直接使用 ID 字符串）
+
+| 场景 | query | 说明 |
+|------|-------|------|
+| 按 traceId 查全部日志 | `<traceId>` | 获取云上 FC 的入口日志，需提取 requestId 做二次查询 |
+| 按 requestId 查完整调用链 | `<requestId>` | **二次查询**：获取单次云上 FC 调用的完整日志链路 |
+| 按 taskId 查全部日志 | `<taskId>` | 适用于只有 taskId 的场景 |
+| 按 requestId 查执行计划 | `<requestId>` 后在结果中筛选 `message` 含 `planner` | 查看 AI 字段的执行计划（plan），含任务类型（CHAT_COMPLETION/WEB_SEARCH/MULTIMODAL_CHAT_COMPLETION） |
+| 按 requestId 查 LLM 调用 | `<requestId>` 后在结果中筛选 `message` 含 `chat_completion` | 查看 LLM 调用的详细过程 |
+| 按 requestId 查网页搜索 | `<requestId>` 后在结果中筛选 `message` 含 `WebCrawler` | 查看网页搜索/爬取的执行情况，`[WebCrawler] 智能服务调用失败` 是高频错误 |
+| 按 requestId 查回调错误 | `<requestId>` 后在结果中筛选 `message` 含 `Callback error` | 定位回调失败（如 502 错误），影响结果回传 |
+| 按 requestId 查请求体 | `<requestId>` 后在结果中筛选 `message` 含 `receive_body` | 查看云上 FC 收到的完整请求体，含 formData、fieldConfig、grays 等关键参数 |
+| 按 traceId 查 ERROR 级别 | `<traceId> and ERROR` | 快速定位云上 FC 中的错误日志 |
+
+#### 跨库联合排查模板
+
+以下是典型排查场景的跨库查询组合，按顺序执行：
+
+**场景 1：任务失败端到端排查**
+```
+1. scheduler:  taskid:<taskId> and action:SUB_TASK_FAIL     → 确认失败的子任务和 innertype
+2. scheduler:  taskid:<taskId>                               → 获取完整 action 序列，定位断点
+3. extension-log:  <traceId> and ERROR                       → 获取错误栈详情
+4. notable-fc:  <traceId>                                    → 获取 FC 入口日志，提取 requestId
+5. notable-fc:  <requestId>                                  → 二次查询获取完整 FC 日志
+6. 云上 FC（若 innertype 以 agent_ 开头）:  <traceId>        → 获取云上 FC 入口日志，提取 requestId
+7. 云上 FC:  <requestId>                                     → 二次查询获取完整云上 FC 日志
+```
+
+**场景 2：任务卡住未执行排查**
+```
+1. scheduler:  taskid:<taskId>                               → 检查 action 序列是否只有 SCHEDULE 没有 RUNNING
+2. scheduler:  taskid:<taskId> and action:SUB_TASK_CANCEL    → 检查是否被取消
+3. extension-log:  <traceId>                                 → 查看是否有调度相关日志
+4. extension-log:  <taskId> and LIPPI_DOC_NOTABLE_DECORATOR  → 检查 MQ 消息是否被消费
+```
+
+**场景 3：LLM 调用失败排查**
+```
+1. scheduler:  taskid:<taskId>                               → 确认任务到达 SUB_TASK_INVOKE 阶段
+2. notable-fc:  <traceId>                                    → 提取 requestId
+3. notable-fc:  <requestId>（筛选 bagualuModelService-requestStatus） → 检查 LLM 调用 success 状态和 serviceId
+4. 云上 FC（若 agent_ 类型）:  <requestId>（筛选 planner）   → 查看执行计划
+5. 云上 FC:  <requestId>（筛选 ERROR）                       → 查看具体错误信息
+```
+
+**场景 4：回写失败排查**
+```
+1. scheduler:  taskid:<taskId> and action:SUB_TASK_WRITE_BACK  → 确认是否到达回写阶段
+2. extension-log:  <taskId> and generateOpsAndCommitInternal   → 查看回写异常详情
+3. extension-log:  <traceId> and LockFailed                    → 检查是否锁竞争
+4. notable-fc:  <traceId>（筛选 GenerateOpsTaskTiming）        → 查看回写耗时
+5. notable-fc:  <traceId> and version_check_failed             → 检查版本冲突
+```
+
+---
+
+## 第 3 步：查询策略与分页约束
+
+1. `sls-mcp` 所有工具的 `limit` 参数最大为 **100**。
+2. **命中很多但看不全**（非 0 命中）：缩小时间范围 + 多次查询分段获取；二次过滤时 query 仍须包含 ID 字符串本身。
+3. **0 命中 / 疑似漏查**：先按第 1.3 阶梯扩大时间范围；扩大后出现大量命中，再用"缩小 + 分段"取全量关键片段。
+4. 每次查询都要在对话中展示：query 字符串、时间范围、扩大/拆分/收窄的理由。
+
+---
+
+## 第 4 步：建立链路时间线
+
+将关键日志按时间排序，形成可读时间线。优先使用 **scheduler 日志库的 action 序列**构建调度阶段时间线，再结合 extension-log / notable-fc / 云上 FC 的详细日志补充每个阶段的具体信息。
+
+### 4.1 调度阶段时间线（基于 scheduler 日志）
+
+以 `taskid` 或 `rowtaskid` 为维度，按时间排列 scheduler 中的 action 序列，至少覆盖以下节点（缺失时要指出缺哪个环节）：
+
+| 节点（action） | 说明 | 缺失时的排查方向 |
+|----------------|------|------------------|
+| `SUB_TASK_SCHEDULE` 或 `SUB_TASK_DIRECT_SCHEDULE` | 子任务是否入队调度 | 任务创建失败或未触发调度 |
+| `SUB_TASK_RUNNING` | 子任务是否开始执行 | 调度阻塞、队列堆积、资源不足 |
+| `SUB_TASK_INVOKE` | 是否调用下游服务 | 执行逻辑异常、前置校验失败 |
+| `SUB_TASK_GEN_OP` | LLM 是否返回并生成操作 | LLM 调用失败、超时、返回格式异常 |
+| `SUB_TASK_CALLBACK` | 下游是否回调 | 下游服务超时、网络异常 |
+| `SUB_TASK_WRITE_BACK` | 结果是否回写 | 回写逻辑异常、权限问题 |
+| `SUB_TASK_FINISH` / `SUB_TASK_FAIL` / `SUB_TASK_CANCEL` | 最终状态 | — |
+
+**关键分析维度**：
+- **action 序列完整性**：正常流程应为 `SCHEDULE → RUNNING → INVOKE → GEN_OP → CALLBACK → WRITE_BACK → FINISH`，缺失任何中间环节都表示该阶段出了问题
+- **耗时分析**：通过 `cost` 字段（毫秒）判断各阶段耗时，异常高耗时可能指向超时或阻塞
+- **批量任务一致性**：同一 `taskid` 下多个 `rowtaskid` 的最终状态是否一致，部分失败时定位具体行
+- **`innertype` 为 `null` 的 FAIL**：通常表示任务在调度阶段就失败了，未进入实际执行
+
+### 4.2 应用层详细时间线（基于 extension-log / notable-fc / 云上 FC）
+
+在 scheduler 时间线的基础上，结合其他日志库的详细日志，补充以下信息：
+
+| 节点 | 来源日志库 | 说明 |
+|------|-----------|------|
+| llm request/response | extension-log | LLM 调用的请求参数、响应内容、耗时 |
+| error stack | extension-log | 完整的异常栈信息 |
+| fc execution | notable-fc / 云上 FC | FC 内部的执行逻辑、插件行为 |
+| writeback detail | extension-log | 回写的具体内容与结果 |
+
+同时输出：
+
+**故障分类**（至少选一类，并说明证据）：
+- 输入参数 / Schema 不一致
+- 调度 / 队列 / 状态机异常
+- LLM 调用失败（鉴权、配额、超时、返回结构变更）
+- 云上 / 弹内执行分流错误
+- 业务逻辑 bug（边界条件、空值、并发、幂等）
+- 依赖服务异常（DB / HTTP 等）
+
+**证据不足点**：若仍无日志，回到第 1.3 继续扩大时间范围，或回到第 0 步补充反查条件。
+
+---
+
+## 第 5 步：代码仓库对照定位
+
+### 5.0 仓库路径与代码查看工具
+
+通过 `code` MCP 工具直接访问远程仓库主干分支的最新代码，无需本地 clone 或 git fetch。
+
+#### 仓库路径映射
+
+| 日志来源 | 仓库路径（`repo` 参数） | 职责 |
+|----------|------------------------|------|
+| scheduler / extension-log | `alidocs/lippi-notable-extension` | AI 字段任务创建 / 调度 / 执行；大模型服务请求实现 |
+| notable-fc | `alidocs/we-notable` | 弹内 FC 的 AI 字段插件执行逻辑 |
+| 云上 FC default-logs | `alidocs/notable-field-decorator-fc` | 云上 FC 的 AI 字段执行逻辑 |
+
+#### 代码查看工具选择
+
+根据排查需要，选择合适的 `code` MCP 工具：
+
+| 排查场景 | 推荐工具 | 说明 |
+|----------|---------|------|
+| 从日志中的错误信息 / 关键词定位代码 | `code::tool::search_code` | 精确文本搜索，适合搜索错误消息、函数名、类名等确切字符串 |
+| 根据功能描述查找相关代码 | `code::tool::repo_vector_search` | 语义搜索，适合用自然语言描述查找相关模块（如"任务调度状态机"） |
+| 查找类定义 / 方法定义 | `code::tool::search_classes` / `code::tool::search_methods` | 按类名或方法名搜索定义位置 |
+| 按文件名查找文件路径 | `code::tool::search_file_path` | 模糊匹配文件名或路径关键词 |
+| 阅读完整文件内容 | `code::tool::get_single_file` | 获取指定文件的完整内容（需指定 `ref`，通常为 `master` 或 `main`） |
+| 阅读文件指定行范围 | `code::tool::get_file_block` | 获取文件指定行区间的内容，适合大文件只看关键片段 |
+
+> 所有工具的 `repo` 参数使用上方仓库路径映射表中的值，`ref` 参数使用主干分支名（通常为 `master`）。
+
+根据日志来源，对照对应仓库代码，给出要看的模块/路径，并解释"为什么是这里"。
+
+### 5.1 scheduler / extension-log 命中 → `alidocs/lippi-notable-extension`
+
+职责：AI 字段任务创建 / 调度 / 执行；大模型服务请求实现。scheduler 和 extension-log（master）均来自此仓库，scheduler 记录调度状态机的结构化流转日志，master 记录应用层的详细执行日志。
+
+要求：
+- **scheduler 命中时**：根据 action 序列中断点，定位调度状态机的相关代码（如任务入队、执行分发、回调处理、回写逻辑）
+- **extension-log 命中时**：从日志中的类名 / 函数名 / 错误栈反推模块
+- 定位状态流转、重试 / 超时、异常处理
+- 确认日志字段（traceId/taskId/rowtaskid）是否完整透传
+
+典型搜索示例：
+```
+# 从错误栈中的类名精确搜索
+code::tool::search_code  repo="alidocs/lippi-notable-extension"  search="AIFieldTaskScheduler"
+
+# 语义搜索调度状态机逻辑
+code::tool::repo_vector_search  repo="alidocs/lippi-notable-extension"  question="AI字段子任务调度状态流转"
+
+# 阅读定位到的文件
+code::tool::get_single_file  repo="alidocs/lippi-notable-extension"  ref="master"  filePath="<定位到的文件路径>"
+```
+
+### 5.2 notable-fc 命中 → `alidocs/we-notable`
+
+职责：弹内 FC 的 AI 字段插件执行逻辑，包括各插件定义的 AI 行为、请求组装与云上任务下发。
+
+要求：
+- 从日志中的函数名 / 插件名 / 错误信息反推对应插件模块
+- 检查请求组装逻辑、输入输出格式是否符合预期
+- 确认是否在弹内已完成全部逻辑，还是需要下发云上任务
+- 与 extension / 云上 FC 的协议字段是否对齐
+
+典型搜索示例：
+```
+# 从日志中的错误信息精确搜索
+code::tool::search_code  repo="alidocs/we-notable"  search="<日志中的错误消息或函数名>"
+
+# 按插件名搜索
+code::tool::search_file_path  repo="alidocs/we-notable"  query="<插件名>"
+```
+
+### 5.3 云上 FC default-logs 命中 → `alidocs/notable-field-decorator-fc`
+
+职责：云上 FC 的 AI 字段执行逻辑。
+
+要求：
+- 检查 handler 入参校验、字段行为实现
+- 超时与重试策略
+- 与弹内 / extension 协议是否对齐
+
+典型搜索示例：
+```
+# 从日志中的 handler 名或错误信息搜索
+code::tool::search_code  repo="alidocs/notable-field-decorator-fc"  search="<handler名或错误关键词>"
+
+# 语义搜索执行逻辑
+code::tool::repo_vector_search  repo="alidocs/notable-field-decorator-fc"  question="<功能描述>"
+```
+
+---
+
+## 第 6 步：输出可执行的 MR 修复方案
+
+> 先完成第 4 步的时间线与故障分类再给修复建议——跳过日志分析直接给方案容易遗漏并发问题或上下游关联故障。
+
+按以下结构输出：
+
+### 1) 根因总结（基于日志证据）
+- 证据 1：
+- 证据 2：
+- 推断链路：
+
+### 2) 修复目标
+- 目标行为：
+- 覆盖边界条件：
+
+### 3) 改动范围（仓库 / 模块 / 文件级别）
+- 仓库：
+- 目录 / 文件（尽可能精确的路径或文件名模式）：
+- 关键函数 / 接口：
+
+### 4) 具体改动点（可落地）
+- 入参校验 / 默认值：
+- 状态机 / 调度流转修复：
+- 幂等与重试：
+- LLM 调用封装与错误处理：
+- 协议字段对齐（弹内 ↔ 云上 ↔ extension）：
+- 结构化日志补充（确保 traceId/taskId 可追踪，日志内容中应包含 ID 值本身以便直接 query 命中）：
+
+### 5) 兼容性与风险
+- 对存量任务 / 历史数据影响：
+- 是否需要灰度：
+- 回滚策略：
+
+### 6) 验证方案
+- 单测建议：
+- 集成 / 端到端测试建议：
+- 线上验证步骤（如何用 traceId/taskId 对照）：
+- 期望看到的关键日志 / 指标变化：
+
+### 7) 附加改进（可选）
+- 埋点 / 告警建议（如 ERROR 比例、超时率、队列堆积）：
+- 日志字段标准化建议：
+
+> 第 6 步完成后，排查尚未结束——还需要执行第 7 步更新 MEMORY.md，将排查经验沉淀下来供团队复用。
+
+---
+
+## 第 7 步：记录排查经验到 MEMORY.md
+
+每次排查完成后，先阅读 `MEMORY.md` 当前内容，然后追加本次排查产生的新知识。这样做的目的是将可复用的排查经验沉淀下来，避免团队重复排查相同问题。若本次排查确实没有任何新信息（所有发现均已存在于 `MEMORY.md` 中），在对话中说明"已检查 MEMORY.md，本次无新增内容"即可。
+
+### 需要记录的内容
+
+**FAQ（常见故障模式）**：当本次排查的故障模式具有通用性（非一次性的配置错误或偶发问题）时，按以下格式追加到 `MEMORY.md` 的 FAQ 部分：
+
+```markdown
+### <简短标题>
+- **现象**：用户看到的表现
+- **根因**：日志/代码层面的原因
+- **关联仓库**：涉及的代码仓库
+- **日志特征**：在哪个日志库中出现什么关键词可命中此问题
+```
+
+**重点代码位置**：当排查过程中定位到了某个仓库中与 AI 字段链路高度相关、但之前未记录的关键模块/文件/函数时，追加到 `MEMORY.md` 对应仓库的"重点代码位置"部分：
+
+```markdown
+- `<文件路径或模块>` — 简要说明职责/排查价值
+```
+
+### 记录原则
+
+- 只记录**有复用价值**的信息，不记录一次性的、特定于某个 traceId 的细节
+- 避免重复：追加前先检查 `MEMORY.md` 中是否已有相同或相似的记录
+- 保持简洁：每条 FAQ 控制在 4 行以内，每条代码位置控制在 1 行
+- **遵守模板格式**：FAQ 只包含"现象"、"根因"、"关联仓库"、"日志特征"四个字段，不添加额外字段（如"解法"、"排查时间"等），保持格式统一便于快速扫描
+- **追加到已有章节**：FAQ 追加到"## FAQ：常见故障模式"章节末尾、代码位置追加到"## 重点代码位置"下对应仓库的子章节末尾。不要创建新的顶级章节（如"本次排查新增记录"等），因为分散的章节会让后续查阅者难以找到信息
+
+
+---
+
+## 核心约束
+
+以下约束贯穿整个排查流程。之所以列为约束，是因为违反它们会直接导致排查结论不可靠或链路信息不完整。
+
+### 日志证据优先
+
+1. **结论基于日志证据**。排查的核心价值在于用日志事实还原故障链路，而非凭经验猜测。证据不足时，明确指出不足点并提出下一步查询条件或时间范围，而不是给出无依据的推测。
+2. **先完成时间线再给修复建议**。跳过第 4 步的时间线与故障分类直接给修复方案，容易遗漏并发问题或上下游关联故障。
+
+### 查询规范
+
+3. **时间范围规则**。详见第 1 步。要点：优先使用 `quickTimeRange`；仅在用户提供精确时间且预设值无法覆盖时才用 `fromTime`/`toTime`（通过 `scripts/time-window.py` 生成）；两种方式不可混用；0 命中时按阶梯扩大而非收窄。
+4. **SLS `limit` 上限为 100**。超出时采用"缩小时间范围 + 多次查询"策略获取完整数据。
+5. **查询必须包含 traceId 或 taskId**。不含具体 ID 的宽泛查询会命中大量无关日志，无法定位具体问题。若当前尚无 ID，先回到第 0 步引导用户补充，或通过文档 ID、用户 ID、报错片段等反查出 ID。
+6. **ID 查询写法因日志库而异**。extension-log / notable-fc / 云上 FC 中，query 直接使用 ID 字符串（含特殊字符时用双引号包裹）；scheduler 中则使用 `字段名:值` 索引格式。详见第 2 步各日志库的查询写法规范。
+
+### 日志库覆盖
+
+7. **三库必查**。`scheduler`、`extension-log`、`notable-fc` 每次排查都要查询，因为 AI 字段链路横跨调度层、应用层和 FC 执行层，仅查部分库容易遗漏跨层问题。即使某个库已找到明确线索，仍须查询其余库以获取完整链路视图。
+8. **`agent_` 类型任务加查云上 FC**。`innerType` 以 `agent_` 开头的任务，核心执行逻辑运行在云上 FC 中，仅查弹内三库无法获取完整链路。
+9. **FC 日志需 `requestId` 二次查询**。traceId/taskId 在 `notable-fc` 和云上 FC 中仅命中入口日志，完整调用链路需要提取 `requestId` 后二次查询。多条命中时需对每个不同的 `requestId` 分别查询。scheduler 无此限制——用 `taskid:<值>` 即可一次性获取全部状态流转记录。
+
+### 排查闭环
+
+10. **更新 MEMORY.md**（第 7 步）。排查产生的可复用知识（FAQ 模式、关键代码路径）需要沉淀，避免团队重复排查相同问题。若确实无新增内容，在对话中说明理由即可。