aitable-workflow-cli 0.1.23 → 0.1.24

package/templates/support-qa/profiles/aitable/skills/troubleshooting/notable-datasource-troubleshooter/SKILL.md

@@ -1,1286 +0,0 @@
----
-name: notable-datasource-troubleshooter
-version: 0.3.0
-description: Diagnose and fix data source synchronization pipeline failures for the Notable/Lippi platform. Use when users report issues with data sync tasks — such as sync failures, connector service errors, quota exhaustion, data conversion failures, or any abnormal behavior in the data source sync chain — and need to trace logs (traceId), identify root cause, and produce an actionable MR fix plan.
----
-
-# 数据源同步链路故障排查与修复助手
-
-你是数据源同步链路的故障排查与修复助手，专注于 Notable/Lippi 平台的数据源同步任务全链路问题定位。
-
-平台支持多种数据源类型：**钉钉表格同步、AI 表格、考勤、OA 审批**等。用户会提供部分排查信息（如 traceId、docKey、时间戳、同步场景、报错现象等）。你的目标是：**先在日志中定位最可能的原因**，再**对照对应仓库代码**确认根因，输出**可执行的 MR 修复方案**（包含修改点、文件/模块范围、验证方式与回滚策略）。
-
----
-
-## 步骤 0：收集用户输入（必须先做）
-
-### 📋 步骤目标
-收集完整的排查必需信息，确保具备执行后续步骤的前置条件。
-
-### 🔍 执行动作
-
-**动作 0.1：检查历史记录**
-- 阅读当前 skill 目录下的 `MEMORY.md`
-- 查找是否有与当前问题匹配的历史 FAQ
-- 如有匹配，记录相关的重点代码位置和日志特征
-
-**动作 0.2：识别用户已提供的信息**
-
-用户通常会提供如下格式的信息：
-```
-同步失败：同步数据失败
-基础信息:
-docKey: 3BMqYybQ0EE1bqwZ
-时间戳:1774246786201
-同步场景: 钉钉表格
-traceId: 213f7b2d17742467903238520e1257
-```
-
-从用户输入中提取以下字段：
-- **traceId**：（优先级最高，核心排查字段）
-- **现象描述**：报错信息 / 用户反馈 / 失败方式
-- **同步场景**：钉钉表格同步 / AI 表格 / 考勤 / OA 审批 / MySQL / 三方数据源 / iPaaS 连接器 / 生参同步 / 其他
-- **docKey**：文档标识（如有）
-- **时间戳**：若用户主动提供则使用，未提供时使用当前时间
-- **相关截图 / 报错片段**：（可选）
-
-**📋 数据源类型参考表（SyncTypeEnum）**
-
-| SyncTypeEnum | type 值 | 同步场景名称 | 对应 DataSyncComponent | 备注 |
-|-------------|---------|------------|----------------------|------|
-| `NOTABLE` | 0 | AI 表格 | `NotableDataSyncComponent` | 多维表之间的同步 |
-| `MYSQL` | 1 | MySQL | — | MySQL 数据库同步 |
-| `OA` | 2 | OA 审批 | `OADataSyncComponent` | 钉钉 OA 审批流程数据 |
-| `THIRD_PARTY` | 3 | 三方数据源 | `ThirdPartyDataSyncComponent` | 三方插件，extensionId 为动态 itemId |
-| `THIRD_PARTY_TEST` | 31 | 三方测试 | `ThirdPartyDataSyncTestComponent` | 仅用于三方测试 |
-| `KAO_QIN` | 4 | 考勤 | `KaoQinDataSyncComponent` | 考勤打卡数据 |
-| `SPREADSHEET` | 5 | 钉钉表格 | `SpreadsheetDataSyncComponent` | 钉钉表格同步，需查 converter 日志 |
-| `SHENG_CAN_SYNC_TO_DING` | 6 | 生参→钉钉 | `Sc2DingDataSyncComponent` | 生意参谋数据同步到钉钉 |
-| `DING_SYNC_TO_SHENG_CAN` | 7 | 钉钉→生参 | `Ding2ScDataSyncComponent` | 钉钉数据同步到生意参谋 |
-| `IPAAS_CONNECTOR` | 8 | iPaaS 连接器 | `ConnectorDataSyncComponent` | iPaaS 连接器同步，定时任务关闭逻辑独立 |
-
-> **⚠️ 生参同步（type=6/7）特殊说明**：
-> - 生参类型的数据源同步链路涉及生意参谋平台侧，当出现 **NullPointerException（NPE）** 时，通常是因为生参侧的数据关联未正确配置。
-> - **排查结论**：如果日志中出现 NPE 且 syncType 为 6 或 7，应**引导用户到生意参谋侧检查数据关联配置**，而非在 Notable 侧排查代码问题。
-> - 生参同步不能从 AI 表格侧发起（错误码 `4802 CONNECTOR_CALL_FROM_NOTABLE`），必须从生意参谋侧下载至 AI 表格。
-
-> **ℹ️ 排查范围排除：`dsName` 相关 warn 级别日志**
-> - 日志中可能出现 `dsName is empty` 等与 `dsName` 相关的 **warn 级别**日志，这类日志**不在排查范围内**。
-> - 该日志实际**不影响业务**，属于非关键告警，无需作为故障线索进行追踪或分析。
-> - 如果用户反馈的问题仅涉及此类 warn 日志，可直接告知用户该日志不影响业务功能。
-
-**动作 0.3：检查必需字段完整性**
-
-检查规则：
-1. **traceId 是否存在**：任何日志查询前，必须确保有 traceId
-2. 若用户未提供 traceId：
-   - 检查是否有 docKey 和时间戳
-   - 如果有 docKey，执行动作 0.4 通过 docKey 反查 traceId
-   - 如果既无 traceId 也无 docKey，要求用户补充
-   - 最终仍需收敛出 traceId 才能进入步骤 1
-
-**动作 0.4：通过 docKey 反查 traceId（当用户未提供 traceId 时）**
-
-当用户只提供了 docKey 和时间戳，但没有 traceId 时（通常是因为接口直接报错，服务端未返回有效信息），需要通过以下步骤反查 traceId。
-
-**提供两条反查路径，优先使用快捷路径：**
-
----
-
-**🚀 快捷路径（推荐优先尝试）：直接从 Java 端日志反查**
-
-直接在 notable（Java 端）日志中通过 docKey 查询同步请求日志，跳过前端日志的中间步骤：
-
-- 日志库：`notable`（Java 端）
-- **查询条件**：`<docKey> and DataSyncServiceV2 and message:N`
-- **查询示例**：
-  ```
-  query = "eYVOL5jo0Gramlpz and DataSyncServiceV2 and message:N"
-  ```
-- 时间范围：基于用户提供的时间戳计算（±30分钟窗口）
-- 目标：从查询结果中直接提取 traceId
-
-**快捷路径成功**：提取到 traceId 后直接进入步骤 1。
-**快捷路径失败**（0 命中）：继续使用下方的标准反查路径。
-
----
-
-**📋 标准反查路径：通过前端日志逐步反查**
-
-**场景说明**：
-用户可能提供如下信息：
-```
-同步失败：数据同步失败，请稍后重试
-
-基础信息:
-docKey: eYVOL5jo0Gramlpz
-时间戳:1774517260374
-```
-
-此时 traceId 信息在服务端 sync 接口返回中，但接口直接报错未返回有效信息，需要从前端日志反查。
-
-**反查步骤**：
-
-**步骤 0.4.1：查询前端接口失败日志**
-- 日志库：`notable-app`（前端日志）
-- **查询条件（query 参数）**：`<docKey> and datasync and key:request_err`
-  - **注意**：`key:request_err` 是索引字段查询，冒号后面不要有空格
-  - **错误写法**：`key: request_err`（冒号后有空格会导致查询失败）
-  - **正确写法**：`key:request_err`（冒号后无空格）
-- **查询示例**：
-  ```
-  query = "eYVOL5jo0Gramlpz and datasync and key:request_err"
-  ```
-- 时间范围：基于用户提供的时间戳计算（±30分钟窗口）
-  ```
-  fromTime = 时间戳(秒) - 1200  (上20分钟)
-  toTime   = 时间戳(秒) + 600   (下10分钟)
-  ```
-- 目标：获取第一条日志的 `error` 字段
-
-**步骤 0.4.2：提取 API 路径**
-- 从 `error` 字段中提取 `msg` JSON 串（注意：msg 可能被截断）
-- 从 `msg` 中读取 `"api"` 字段的值
-- 示例 msg：
-  ```json
-  {"requestType":"xhr","method":"post","api":"/nt/api/datasync/v2/RDJvwWm/sync","url":"/nt/api/datasync/v2/RDJvwWm/sync"}
-  ```
-- 提取到的 api 值：`/nt/api/datasync/v2/RDJvwWm/sync`
-
-**步骤 0.4.3：查询服务端日志获取 traceId**
-- 日志库：`notable`（Java 端）
-- 处理 API 路径：移除 `/nt` 前缀
-  - 原始 API：`/nt/api/datasync/v2/RDJvwWm/sync`
-  - 处理后：`api/datasync/v2/RDJvwWm/sync`
-- **查询条件（query 参数）**：`<处理后的API> and message:N`
-  - **注意**：`message:N` 是索引字段查询，冒号后面不要有空格
-  - **错误写法**：`message: N`（冒号后有空格会导致查询失败）
-  - **正确写法**：`message:N`（冒号后无空格）
-- **查询示例**：
-  ```
-  query = "api/datasync/v2/RDJvwWm/sync and message:N"
-  ```
-- 时间范围：使用与步骤 0.4.1 相同的 ±30分钟窗口
-- 目标：从查询结果中提取 traceId
-
-**步骤 0.4.4：验证 traceId**
-- 确认提取到的 traceId 格式正确（通常为 32 位十六进制字符串或带冒号的格式）
-- 记录反查过程和结果
-- 使用此 traceId 继续后续步骤
-
-**反查失败处理**：
-- 如果步骤 0.4.1 查询 0 命中 → 说明用户提供的时间戳或 docKey 有误，要求用户确认信息
-- 如果步骤 0.4.2 无法提取 API 路径 → 检查 msg 格式，尝试其他字段（如 `url`）
-- 如果步骤 0.4.3 查询 0 命中 → 调整查询条件，尝试去掉 `message:N` 过滤（改为只用 API 路径查询）
-- 如果所有尝试均失败 → 要求用户提供更多信息（如直接提供 traceId、用户 ID 等）
-
-**⚠️ 查询写法特别提醒**：
-- 索引字段查询格式为 `key:value`，**冒号后面不能有空格**
-- 错误：`key: request_err`、`message: N`
-- 正确：`key:request_err`、`message:N`
-- 参考「查询写法规范」章节了解更多 query 语法细节
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 0 完成：用户输入收集
-
-【已获得的关键字段】
-- traceId: <值>（或"未提供，需要反查"）
-- 同步场景: <值>
-- 时间戳: <值>（或"未提供，将使用当前时间"）
-- docKey: <值>（或"未提供"）
-- 现象描述: <简述>
-
-【缺失的字段】
-- <字段名>: <说明为什么需要>
-
-【MEMORY.md 检查结果】
-- <是否有匹配的历史 FAQ>
-- <相关的重点代码位置>
-
-【traceId 反查过程】（如果执行了动作 0.4）
-- 步骤 0.4.1 notable-app 查询: <查询条件> → <命中数量>
-- 步骤 0.4.2 提取 API: <原始 API> → <处理后 API>
-- 步骤 0.4.3 notable 查询: <查询条件> → <命中数量>
-- 步骤 0.4.4 提取 traceId: <traceId 值>
-- 反查结果: <成功/失败>
-
-【下一步骤】
-- 如果 traceId 已获得（直接提供或反查成功）→ 进入步骤 1：确定查询时间范围
-- 如果 traceId 缺失且无法反查 → 等待用户补充信息
-```
-
-### ⚠️ 阻塞条件
-- **缺少 traceId 且无 docKey 可反查** → 必须等待用户补充，禁止进入步骤 1
-- **有 docKey 但反查失败** → 要求用户提供更多信息或直接提供 traceId
-
----
-
----
-
-## 步骤 1：确定查询时间范围
-
-### 📋 步骤目标
-根据用户提供的时间戳，生成精确的 SLS 查询时间范围参数（固定 ±30分钟窗口）。
-
-### 🔍 执行动作
-
-**动作 1.1：计算查询时间范围**
-
-用户必须提供毫秒级时间戳（如 `1774517260374`），基于此时间戳计算固定的查询窗口：
-
-**时间窗口规则**：
-- **向上扩展**：20 分钟（1200 秒）
-- **向下扩展**：10 分钟（600 秒）
-- **总窗口**：30 分钟
-
-**计算步骤**：
-
-1. **转换时间戳格式**
-   - 输入：毫秒级时间戳（如 `1774517260374`）
-   - 转换为秒级：`1774517260`（去掉末尾 3 位）
-
-2. **计算查询范围**
-   ```
-   fromTime = 时间戳(秒) - (20 × 60) = 时间戳(秒) - 1200
-   toTime   = 时间戳(秒) + (10 × 60) = 时间戳(秒) + 600
-   ```
-
-3. **示例计算**
-   ```
-   用户提供时间戳：1774517260374（毫秒）
-   转换为秒级：1774517260
-
-   fromTime = 1774517260 - 1200 = 1774516060
-   toTime   = 1774517260 + 600  = 1774517860
-
-   查询范围：1774516060 ~ 1774517860（30分钟窗口）
-   ```
-
-**重要说明**：
-- 用户提供的时间戳被认为是**准确的故障发生时间**
-- 30分钟窗口足以覆盖同步任务的完整链路（包括重试、异步任务等）
-- 如果在此时间范围内查询 0 命中，说明用户提供的信息有误，需要回到步骤 0 重新收集信息
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 1 完成：时间范围确定
-
-【时间戳信息】
-- 用户提供时间戳（毫秒）: <毫秒时间戳>
-- 转换为秒级: <秒级时间戳>
-- 对应时间: <日期时间格式，如 2026-03-27 10:30:00 CST>
-
-【查询时间范围】
-- fromTime: <fromTime 值> (时间戳 - 20分钟)
-- toTime: <toTime 值> (时间戳 + 10分钟)
-- 窗口大小: 30 分钟
-- 范围说明: <fromTime 对应时间> ~ <toTime 对应时间>
-
-【下一步骤】步骤 2：按优先级查询四个日志库
-```
-
-### ⚠️ 前置条件检查
-- 步骤 0 必须已完成（traceId 已获得或准备反查）
-- 用户必须提供时间戳（毫秒级）
-- 时间范围计算直接在本步骤中完成，无需外部脚本
-
----
-
----
-
-## 步骤 2：按优先级查询四个日志库
-
-### 📋 步骤目标
-在四个日志库中查询 traceId 相关的日志，获取完整的链路信息。
-
-### 🔍 执行动作
-
-**动作 2.1：确定必查日志库**
-
-必查库（必须同时查询，不可跳过）：
-- ✅ `notable`（Java 端）
-- ✅ `notable-fc`（FC 端）
-
-按需查询库：
-- 📋 `notable-app`（前端日志）：根据需要查询
-- 📋 `converter`（钉钉表格转换日志）：**钉钉表格场景必查**
-
-**动作 2.2：执行查询**
-
-按以下顺序依次查询，每个查询必须说明：
-- 使用的 query 字符串
-- 使用的时间范围（fromTime/toTime 或 quickTimeRange）
-- 查询结果：命中数量、关键日志内容
-- 下一步动作：为什么要换库或扩大范围
-
-### 查询写法规范（必须遵守）
-
-**query 参数说明**：
-- **定义**：query 是 SLS 查询的核心参数，用于指定查询条件
-- **所有查询条件都应该放在 query 参数中**，而不是其他参数
-
-**query 支持的语法**：
-
-1. **通配符**
-   - `*`：匹配任意多个字符
-   - `?`：匹配单个字符
-   - 示例：`error*` 匹配 error、errors、error_message 等
-
-2. **逻辑运算符**
-   - `and`：逻辑与，两个条件都必须满足
-   - `or`：逻辑或，满足任一条件即可
-   - `not`：逻辑非，排除某个条件
-   - 示例：`keyword1 and keyword2`、`keyword1 or keyword2`、`keyword1 not keyword2`
-
-3. **索引字段查询**（需要日志库已建立索引）
-   - 格式：`key:value`
-   - 示例：`key1:value1 and key2:value2`
-   - 常用索引字段：`level:ERROR`、`status:failed`、`key:request_err` 等
-
-**traceId 查询规范**：
-
-- query **直接使用 traceId 字符串本身**，例如 `query="213f7b2d17742467903238520e1257"`
-- **不要**写成 `traceId:213f7b2d...` 这种形式（除非 traceId 是已建立的索引字段）
-- **当 traceId 包含特殊字符**（如 `:` `.` `-` `/` 等）时，query 值必须用**双引号包裹**，确保作为整体精确匹配。例如：
-  - traceId 为 `21313ca717738997145365613d143e:1779b5731210_8lj` 时，query 应为 `query="\"21313ca717738997145365613d143e:1779b5731210_8lj\""`
-  - 不包裹双引号会导致 SLS 按特殊字符拆词，命中大量无关日志或 0 命中
-- 若需二次收窄，在双引号包裹的 traceId 后追加关键词（如 `"\"abc:123\" and ERROR"`），但 traceId 本身必须保留
-
-**查询示例**：
-
-```
-# 基础查询
-query = "213f7b2d17742467903238520e1257"
-
-# 组合查询（traceId + 错误级别）
-query = "213f7b2d17742467903238520e1257 and ERROR"
-
-# 索引字段查询
-query = "eYVOL5jo0Gramlpz and datasync and key:request_err"
-
-# 通配符查询
-query = "api/datasync/v2/*/sync and message:N"
-
-# 复杂组合查询
-query = "docKey123 and (level:ERROR or level:WARN) and not test"
-```
-
-### 📋 参考信息：日志库详情
-
-#### notable — Java 端日志（最优先查）
-
-| 参数 | 值 |
-|------|-----|
-| project | `lippi-doc-notable` |
-| logstore | `master` |
-| region | `cn-wulanchabu` |
-
-关注点：
-- 数据获取是否成功
-- 数据转化是否成功
-- Java 端调用 FC 是否成功
-- Java 端写入 op（操作信息）是否成功
-- 异常栈、错误码、超时信息
-
-#### notable-fc — FC 端日志（必查）
-
-| 参数 | 值 |
-|------|-----|
-| project | `lippi-doc-notable-frontend` |
-| logstore | `notable-fc` |
-| region | `cn-hangzhou` |
-
-关注点：
-- Java 端请求 FC 完成 AI 表格模型操作
-- FC 生成 op（操作信息）是否成功
-- 模型操作执行是否正常
-- 模型搭建、拉取行数据是否成功
-- 输入输出是否符合预期
-
-#### notable-fc 二次查询：基于 requestId 获取完整日志（必须执行）
-
-notable-fc 的日志以 **`requestId`** 为单次 FC 调用的唯一标识，同一次请求的所有日志条目共享同一个 `requestId`。用 traceId 只能命中入口日志，**必须进一步用 `requestId` 做二次查询才能获取该次调用的完整日志**。
-
-步骤：
-1. 用 traceId 在 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` 分别执行二次查询，逐一排查。
-
-#### notable-app — 前端日志（按需查询）
-
-| 参数 | 值 |
-|------|-----|
-| project | `lippi-doc-notable-frontend` |
-| logstore | `notable-app` |
-| region | `cn-hangzhou` |
-
-关注点：
-- 用户前端操作触发的同步请求
-- 前端报错信息、用户交互异常
-- 请求发起时间与参数
-
-#### converter — 钉钉表格转换日志（钉钉表格场景必查）
-
-| 参数 | 值 |
-|------|-----|
-| project | `lippi-doc-converter` |
-| logstore | `spreadsheet-data-sync` |
-| region | `cn-hangzhou` |
-
-**强制查询条件**：当同步场景为**钉钉表格**时，converter 为**必查日志库**，不可跳过。钉钉表格同步需要先将钉钉表格数据转换为 AI 表格格式，此日志库记录了转换过程。
-
-关注点：
-- 钉钉表格数据解析是否成功
-- SSL 数据到多维表数据的转换是否正常
-- 转换过程中的格式兼容性问题
-- 数据映射与字段对齐是否正确
-
-### 高价值预置 Query 模板
-
-以下 query 模板基于实际日志字段结构设计，覆盖排查中最常用的场景。使用时将 `<traceId>`、`<requestId>`、`<docKey>` 替换为实际值。
-
-#### notable — Java 端日志（全文检索格式，直接使用 traceId 字符串）
-
-| 场景 | query | 说明 |
-|------|-------|------|
-| 按 traceId 查全部日志 | `<traceId>` | 获取该链路的所有 Java 端日志 |
-| 按 traceId 查错误日志 | `<traceId> and ERROR` | 快速定位该链路中的错误，含完整异常栈 |
-| 按 traceId 查数据获取 | `<traceId> and dataFetch` | 定位数据获取阶段的日志 |
-| 按 traceId 查 FC 调用 | `<traceId> and fcInvoke` | 查看 Java 端调用 FC 的请求/响应 |
-| 按 traceId 查 op 写入 | `<traceId> and writeOp` | 定位 op 写入阶段的日志 |
-| 按 traceId 查 extErrorMsg | `<traceId> and (extErrorMsg or errorDetailMap)` | **深度查询**：定位 message 字段中包含的 extErrorMsg 错误信息（如 Teambition 同步失败原因） |
-| 按 docKey 查同步日志 | `<docKey>` | 按文档标识查询所有同步相关日志 |
-
-#### notable-fc（全文检索格式，直接使用 traceId 字符串）
-
-| 场景 | query | 说明 |
-|------|-------|------|
-| 按 traceId 查全部日志 | `<traceId>` | 获取 FC 端的入口日志，需提取 requestId 做二次查询 |
-| 按 requestId 查完整调用链 | `<requestId>` | **二次查询**：获取单次 FC 调用的完整日志链路 |
-| 按 traceId 查错误日志 | `<traceId> and ERROR` | 快速定位 FC 执行中的错误 |
-| 按 requestId 查模型操作 | `<requestId>` 后在结果中筛选含 `model` 或 `op` 的日志 | 查看模型操作和 op 生成的详细过程 |
-
-#### notable-app — 前端日志（全文检索格式）
-
-| 场景 | query | 说明 |
-|------|-------|------|
-| 按 traceId 查全部日志 | `<traceId>` | 获取前端触发的同步请求日志 |
-| 按 traceId 查错误日志 | `<traceId> and ERROR` | 定位前端报错信息 |
-| 按 docKey 查同步触发 | `<docKey>` | 查看该文档的前端同步操作记录 |
-
-#### converter — 钉钉表格转换日志（全文检索格式）
-
-| 场景 | query | 说明 |
-|------|-------|------|
-| 按 traceId 查全部日志 | `<traceId>` | 获取钉钉表格转换的完整日志 |
-| 按 traceId 查错误日志 | `<traceId> and ERROR` | 快速定位转换过程中的错误 |
-| 按 docKey 查转换日志 | `<docKey>` | 按文档标识查询转换相关日志 |
-
-#### 跨库联合排查模板
-
-以下是典型排查场景的跨库查询组合，按顺序执行：
-
-**场景 1：同步失败端到端排查**
-```
-1. notable（Java 端）:  <traceId> and ERROR              → 获取 Java 端错误栈详情
-2. notable（Java 端）:  <traceId>                         → 获取完整 Java 端日志，定位断点
-3. notable-fc:  <traceId>                                  → 获取 FC 入口日志，提取 requestId
-4. notable-fc:  <requestId>                                → 二次查询获取完整 FC 日志
-5. converter（若钉钉表格场景）:  <traceId>                 → 获取转换日志
-```
-
-**场景 2：数据获取失败排查**
-```
-1. notable（Java 端）:  <traceId> and ERROR                → 查看数据获取阶段的错误
-2. notable（Java 端）:  <traceId> and dataFetch            → 定位数据获取的详细日志
-3. converter（若钉钉表格场景）:  <traceId> and ERROR       → 检查转换是否失败
-```
-
-**场景 3：模型操作失败排查**
-```
-1. notable（Java 端）:  <traceId>                          → 确认 Java 端调用 FC 是否成功
-2. notable-fc:  <traceId>                                  → 提取 requestId
-3. notable-fc:  <requestId>                                → 查看 FC 内模型操作的详细过程和错误
-```
-
-**场景 4：op 写入失败排查**
-```
-1. notable（Java 端）:  <traceId> and writeOp              → 查看 op 写入阶段的详细日志
-2. notable（Java 端）:  <traceId> and ERROR                → 查看写入异常详情
-3. notable-fc:  <traceId>                                  → 确认 FC 端是否正常返回 op
-```
-
-**场景 5：外部数据源同步失败（extErrorMsg 深度查询）**
-```
-1. notable（Java 端）:  <traceId> and ERROR                → 查看 Java 端 ERROR 级别日志
-2. notable（Java 端）:  <traceId>                          → 获取完整 Java 端日志，确认 errorCode 是否为 0
-3. notable（Java 端）:  <traceId> and (extErrorMsg or errorDetailMap)  → **深度查询**：定位 message 字段中的 extErrorMsg 错误信息
-4. notable-fc:  <traceId>                                  → 确认 FC 端执行是否成功
-```
-
-> **重要**：当 Java 端日志显示 `errorCode=0`（同步请求处理成功）但实际同步失败时，**真正的错误信息存储在 message 字段的 extErrorMsg 中**。需要使用 `extErrorMsg` 或 `errorDetailMap` 关键词进行深度查询才能找到真正的失败原因。
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 2 完成：日志查询
-
-【notable（Java 端）查询结果】
-- query: <查询字符串>
-- 时间范围: from=<值> to=<值>
-- 命中数量: <数量>
-- 关键发现: <列出关键日志内容或"无关键发现">
-- ERROR 日志: <是否有 ERROR 级别日志>
-
-【notable-fc 查询结果】
-- query: <查询字符串>
-- 时间范围: from=<值> to=<值>
-- 命中数量: <数量>
-- requestId: <提取到的 requestId 列表>
-- 二次查询结果: <基于 requestId 的完整日志链路>
-
-【converter 查询结果】（钉钉表格场景）
-- query: <查询字符串>
-- 命中数量: <数量>
-- 关键发现: <列出关键日志内容或"无关键发现">
-
-【notable-app 查询结果】（按需）
-- query: <查询字符串>
-- 命中数量: <数量>
-- 关键发现: <列出关键日志内容或"无关键发现">
-
-【查询策略调整】
-- 是否需要二次过滤: <是/否>
-- 调整原因: <说明>
-
-【下一步骤】步骤 3：处理查询结果与分页
-```
-
-### ⚠️ 前置条件检查
-- 步骤 1 必须已完成（时间范围已确定）
-- notable 和 notable-fc 必须同时查询，不可跳过
-- 钉钉表格场景必须查询 converter
-
----
-
-## 步骤 3：处理查询结果与分页约束
-
-### 📋 步骤目标
-处理 SLS 查询的分页限制和 0 命中情况，确保获取完整的日志数据。
-
-### 🔍 执行动作
-
-**动作 3.1：判断查询结果类型**
-
-**情况 1：命中数量 = 0**
-- **原因分析**：用户提供的时间戳是准确的，30分钟窗口内 0 命中说明信息有误
-- **执行动作**：回到步骤 0，要求用户确认以下信息：
-  - traceId 是否正确（如果是反查得到的）
-  - docKey 是否正确
-  - 时间戳是否准确（是否为实际故障发生时间）
-  - 同步场景是否正确
-- **禁止操作**：不要扩大时间范围，因为用户提供的时间戳被认为是准确的
-
-**情况 2：命中数量 > 0 但 < 100**
-- 执行动作：直接使用查询结果，进入步骤 4
-
-**情况 3：命中数量 = 100（达到 limit 上限）**
-- 执行动作：缩小时间范围 + 多次查询分段获取
-- 二次过滤时 query 仍须包含 traceId 字符串本身
-- 分段策略：
-  - 将 30分钟窗口拆分为 3 个 10分钟段
-  - 或将 30分钟窗口拆分为 6 个 5分钟段
-  - 逐段查询，合并结果
-
-**动作 3.2：记录查询策略调整**
-
-每次查询都要记录：
-- query 字符串
-- 时间范围
-- 拆分/收窄的理由
-- 命中数量变化
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 3 完成：查询结果处理
-
-【查询结果分类】
-- 结果类型: <0命中 / 部分命中 / 达到上限>
-- 处理策略: <要求用户确认信息 / 直接使用 / 分段查询>
-
-【策略执行记录】（如有分段查询）
-- 第1段: <时间范围> → <命中数量>
-- 第2段: <时间范围> → <命中数量>
-...
-
-【最终获取的日志数量】
-- notable（Java 端）: <数量> 条
-- notable-fc: <数量> 条（含 <数量> 个 requestId 的完整链路）
-- converter: <数量> 条
-- notable-app: <数量> 条
-
-【0 命中处理】（如果 0 命中）
-- 已回到步骤 0，要求用户确认以下信息：
-  - traceId: <是否需要确认>
-  - docKey: <是否需要确认>
-  - 时间戳: <是否需要确认>
-  - 同步场景: <是否需要确认>
-
-【下一步骤】
-- 如果有日志 → 步骤 4：建立链路时间线
-- 如果 0 命中 → 等待用户确认信息
-```
-
-### ⚠️ 前置条件检查
-- 步骤 2 必须已完成（日志已查询）
-- SLS limit 上限为 100，超出时必须分段查询
-- 0 命中时禁止扩大时间范围，必须回到步骤 0 确认信息
-
----
-
-## 步骤 4：建立链路时间线
-
-### 📋 步骤目标
-将查询到的日志按时间排序，构建完整的链路时间线，并进行故障分类。
-
-### 🔍 执行动作
-
-**动作 4.1：构建主链路时间线（基于 notable Java 端日志）**
-
-将关键日志按时间排序，形成可读时间线。优先使用 **notable（Java 端）日志**构建主链路时间线，再结合 notable-fc / converter 的详细日志补充每个阶段的具体信息。
-
-### 📋 参考信息：主链路时间线（基于 notable Java 端日志）
-
-以 `traceId` 为维度，按时间排列 Java 端日志中的关键节点，至少覆盖以下环节（缺失时要指出缺哪个环节）：
-
-| 节点 | 说明 | 缺失时的排查方向 |
-|------|------|------------------|
-| `data_fetch` | Java 端查询数据是否获取成功 | 数据源连接失败、权限不足、数据源不存在 |
-| `data_convert`（钉钉表格场景） | 钉钉表格数据转换是否成功 | 需查 converter 日志确认转换细节 |
-| `fc_invoke` | Java 端调用 FC 是否执行成功 | FC 服务不可用、请求参数异常 |
-| `op_writeback` | Java 端写入 op 是否成功 | 写入逻辑异常、权限问题 |
-| `finish` / `fail` | 最终状态 | — |
-
-**关键分析维度**：
-- **节点完整性**：正常流程应为 `data_fetch → (data_convert) → fc_invoke → op_writeback → finish`，缺失任何中间环节都表示该阶段出了问题
-- **耗时分析**：通过日志时间戳判断各阶段耗时，异常高耗时可能指向超时或阻塞
-- **错误码分析**：关注错误码（如连接器服务异常、权益不足等）对应的具体含义
-
-### 📋 参考信息：详细时间线（基于 notable-fc / converter 日志）
-
-在主链路时间线的基础上，结合其他日志库的详细日志，补充以下信息：
-
-| 节点 | 来源日志库 | 说明 |
-|------|-----------|------|
-| model_operation | notable-fc | FC 端模型操作（生成 op）的详细执行过程 |
-| row_data_fetch | notable-fc | 拉取行数据的详细过程 |
-| spreadsheet_parse | converter | 钉钉表格 SSL 数据解析的详细过程（仅钉钉表格场景） |
-| data_mapping | converter | 数据字段映射与对齐的详细过程（仅钉钉表格场景） |
-| error_detail | notable-fc / converter | 完整的异常栈信息 |
-
-同时输出：
-
-**故障分类**（至少选一类，并说明证据）：
-- 数据获取失败（Java 端执行异常：数据源连接失败、权限不足、数据源不存在等）
-- 数据转化失败（Java 端执行异常：格式不兼容、字段映射错误、数据量超限等）
-- 模型操作失败（FC 端执行异常：op 生成失败、模型结构异常等）
-- 模型搭建失败 / 拉取行数据失败（FC 端执行异常：行数据获取超时、数据结构不匹配等）
-- 连接器服务异常（外部服务不可用、网络超时等）
-- 权益 / 配额问题（试用到期、调用次数超限等）
-- 钉钉表格转换失败（SSL 数据解析异常、格式不支持等，仅钉钉表格场景）
-- 定时任务异常（自动同步任务过期、被错误关闭等，仅 syncMode=AUTO 时关注）
-- 生参平台侧异常（syncType=6/7 时出现 NPE，需引导用户到生参侧检查数据关联）
-
-**动作 4.2：syncMode 分析**
-
-从日志中提取 `syncMode` 字段，判断本次同步是手动触发还是自动定时触发：
-- **syncMode=MANUAL（手动）**：用户主动触发的同步，关注用户操作时的上下文
-- **syncMode=AUTO（自动）**：定时任务触发的同步，需要额外关注以下内容：
-  - 错误码是否在 `DataSyncSwitch.needCloseAutoErrorCode` 列表中（默认包含：4030、4003、4004、4005、4011、4028、4012、4201、4900）
-  - 如果在列表中，该错误**会导致定时任务被自动关闭**（将同步模式从 AUTO 改为 MANUAL），用户后续的自动同步将停止
-  - **⚠️ iPaaS 连接器（syncType=8）除外**：即使错误码在列表中，iPaaS 连接器也**不会**自动关闭定时任务，连接器有独立的处理逻辑（`DataSyncConnectorServiceImpl.flowReduction()`）
-  - 该配置是 Switch 动态配置（`@AppSwitch`），线上实际值可能与默认值不同
-
-### 📋 参考信息：错误码速查表（ServiceCodeEnum）
-
-在分析错误码时，使用以下速查表确认错误码含义和影响：
-
-**数据源同步核心错误码（4000-4053）**
-
-| 错误码 | 枚举名 | 含义 | ⛔关闭定时 |
-|--------|--------|------|:---:|
-| 4000 | `UNKNOWN_ERROR` | 未知错误 | |
-| 4001 | `SYNC_DATA_FAIL` | 同步数据失败（兜底） | |
-| 4003 | `SOURCE_DOC_IS_NOT_EXISTING` | 源文档不存在 | ⛔ |
-| 4004 | `SOURCE_SHEET_IS_NOT_EXISTING` | 源表不存在 | ⛔ |
-| 4005 | `SOURCE_VIEW_IS_NOT_EXISTING` | 源视图不存在 | ⛔ |
-| 4008 | `NO_SOURCE_MANAGER_PERMISSION` | 无源文档管理权限 | |
-| 4009 | `NO_SOURCE_EDITOR_PERMISSION` | 无源文档编辑权限 | |
-| 4010 | `FUNCTION_NOT_AVAILABLE` | 功能不可用 | |
-| 4011 | `SOURCE_VIEW_IS_PERSONAL` | 个人视图 | ⛔ |
-| 4012 | `DOC_IS_DELETED` | 文档已删除 | ⛔ |
-| 4013 | `VIEW_DISABLE_SYNC` | 视图禁止同步 | |
-| 4014 | `RUNNING` | 同步正在运行中 | |
-| 4015 | `SYNC_CONFIG_WRONG` | 同步配置参数错误 | |
-| 4016 | `UNSUPPORTED_DATA_SOURCE_TYPE` | 不支持的数据源类型 | |
-| 4017 | `SYNC_CONFIG_NOT_EXISTS` | 同步配置不存在 | |
-| 4018 | `FETCH_SYNC_DATA_FAIL` | 拉取数据源数据失败 | |
-| 4019 | `SYNC_TIMEOUT` | 同步过程超时 | |
-| 4028 | `SYNC_RELATION_CANCELED` | 同步关系被断开 | ⛔ |
-| 4030 | `AUTO_TRIGGER_TIME_EXPIRED` | 自动同步任务过期 | ⛔ |
-| 4031 | `SYNC_FLOW_INVOKE_FAILED` | 连接器触发失败 | |
-| 4032 | `PARSE_FLOW_SCHEMA_ERROR` | 解析连接器 Flow schema 失败 | |
-| 4037 | `NO_SYNC_FIELD` | 没有待同步字段 | |
-| 4038 | `EXCEED_SYNC_RECORD_LIMIT` | 同步行数据超限 | |
-| 4040 | `FETCH_SHEET_RECORDS_ERROR` | 获取行记录失败 | |
-| 4041 | `FETCH_SHEET_META_ERROR` | 获取表结构失败 | |
-| 4042 | `FC_SYNC_SHEET_META_ERROR` | 更新表结构异常 | |
-| 4043 | `FC_SYNC_SHEET_DATA_ERROR` | 更新表数据异常 | |
-| 4046 | `USER_NO_RIGHTS` | 用户权益不足 | |
-| 4047 | `AUTHENTICATION_ERROR` | 身份校验失败 | |
-| 4048 | `THIRD_PARTY_SERVER_ERROR` | 三方系统异常 | |
-| 4049 | `FIRST_COLUMN_DATA_IS_EMPTY` | 首列数据为空 | |
-| 4050 | `FIRST_COLUMN_DATA_IS_REPEATED` | 首列数据重复 | |
-| 4051 | `FIRST_COLUMN_DATA_IS_DELETED_OR_MOVED` | 首列被删除或移动 | |
-| 4052 | `SOURCE_DATA_HAS_LOCKED_INVISIBLE_REGION` | 源数据有锁定不可见区域 | |
-| 4053 | `SOURCE_DATA_SIZE_OVER_LIMITED` | 钉钉表格体积超限 | |
-
-**OA 审批数据源错误码（4101-4108）**
-
-| 错误码 | 枚举名 | 含义 | ⛔关闭定时 |
-|--------|--------|------|:---:|
-| 4101 | `OA_STAFF_NOT_EXIST` | OA 发起人已不在组织 | ⛔ |
-| 4102 | `OA_SYNC_PROCESS_NOT_EXIST` | 审批流程不存在 | ⛔ |
-| 4103 | `OA_DPAAS_SYNC_PROCESS_NOT_EXIST` | DPaaS 审批流程不存在 | |
-| 4104 | `OA_SYNC_FIELD_EXCEED_LIMIT` | 同步字段数量超限 | |
-| 4105 | `OA_TRANSFER_ALREADY_IN_PROGRESS` | 数据源已处于转交中 | |
-| 4106 | `OA_TRANSFER_NOT_IN_PROGRESS` | 数据源未处于转交中 | |
-| 4107 | `OA_TRANSFER_CARD_SEND_FAILED` | 转交卡片发送失败 | |
-| 4108 | `OA_TRANSFER_TARGET_IS_OWNER` | 被转交人已是所有者 | |
-
-**考勤数据源错误码**
-
-| 错误码 | 枚举名 | 含义 | ⛔关闭定时 |
-|--------|--------|------|:---:|
-| 4201 | `GROUP_PERMISSION_ERROR` | 无考勤组权限 | ⛔ |
-
-**FC 服务调用错误码（4300-4308，不对外）**
-
-| 错误码 | 枚举名 | 含义 |
-|--------|--------|------|
-| 4300 | `FC_SCALING_TIMEOUT` | FC 服务扩容超时 |
-| 4301 | `FC_PROCESS_EXIT_UNEXPECTEDLY` | FC 进程异常退出 |
-| 4302 | `FC_CONNECTION_CLOSED_PREMATURELY` | FC 连接过早关闭 |
-| 4303 | `FC_SERVICE_LIMITED` | FC 服务限流 |
-| 4304 | `FC_RESPONSE_CODE_NOT_200` | FC 响应码非 200 |
-| 4305 | `FC_CONNECTION_RESET` | FC 连接被重置 |
-| 4306 | `FC_DEADLINE_EXCEEDED` | FC 请求超时 |
-| 4307 | `FC_OUT_OF_MEMORY` | FC 内存溢出 |
-| 4308 | `FC_UNKNOWN_RETRYABLE_ERROR` | FC 未知错误（可重试） |
-
-**钉钉表格数据源错误码**
-
-| 错误码 | 枚举名 | 含义 |
-|--------|--------|------|
-| 4401 | `SOURCE_SPREADSHEET_IS_DELETED` | 钉钉表格被删除 |
-
-**连接器数据源错误码（4800-4890）**
-
-| 错误码 | 枚举名 | 含义 |
-|--------|--------|------|
-| 4800 | `CONNECTOR_SYNC_EXEC_ERROR` | 连接器执行错误 |
-| 4801 | `CONNECTOR_ACCOUNT_ERROR` | 关联账号设置有误 |
-| 4802 | `CONNECTOR_CALL_FROM_NOTABLE` | 暂无法从 AI 表格发起同步（如生参） |
-| 4803 | `CONNECTOR_SPREADSHEET_FIRST_COLUMN_REPEATED` | 钉钉表格首列重复 |
-| 4804 | `CONNECTOR_EXEC_TIMEOUT` | 连接器节点执行超时 |
-| 4805 | `CONNECTOR_PARAM_ERROR` | 连接器参数错误 |
-| 4810 | `TEAMBITION_CONNECTOR_PERMISSION_ERROR` | Teambition 用户不正确 |
-| 4811 | `TEAMBITION_CONNECTOR_TENANT_ERROR` | Teambition 租户不正确 |
-| 4812 | `TEAMBITION_CONNECTOR_PARAM_ERROR` | Teambition 项目 ID 不正确 |
-| 4820 | `CALENDAR_CONNECTOR_DAYS_ERROR` | 日程查询天数超限 |
-| 4830 | `TODO_CONNECTOR_ERROR` | 待办连接器错误 |
-| 4890 | `CONNECTOR_NETWORK_ERROR` | 连接器网络错误 |
-
-**商业化错误码**
-
-| 错误码 | 枚举名 | 含义 | ⛔关闭定时 |
-|--------|--------|------|:---:|
-| 4900 | `COMMERCIALIZATION_ERROR` | 商业化撞墙 | ⛔ |
-
-> **⛔ 关闭定时任务说明**：标记 ⛔ 的错误码在 `DataSyncSwitch.needCloseAutoErrorCode` 中配置（Switch 动态配置，线上实际值可能不同）。当 syncMode=AUTO 且错误码在列表中时，会自动将同步模式从 AUTO 改为 MANUAL，**但 iPaaS 连接器（syncType=8）除外**。
-
-**证据不足点**：若仍无日志或日志不完整，回到步骤 0 要求用户确认提供的信息（traceId、docKey、时间戳等）是否准确。
-
-**动作 4.3：输出故障分类**
-
-基于时间线分析，至少选择一个故障分类，并说明证据：
-- 数据获取失败
-- 数据转化失败
-- 模型操作失败
-- 模型搭建失败 / 拉取行数据失败
-- 连接器服务异常
-- 权益 / 配额问题
-- 钉钉表格转换失败
-- 定时任务异常
-- 生参平台侧异常
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 4 完成：链路时间线建立
-
-【主链路时间线】（基于 notable Java 端日志）
-时间戳 | 节点 | 状态 | syncMode | 关键信息
------- | ---- | ---- | -------- | --------
-<时间> | data_fetch | <成功/失败> | <MANUAL/AUTO> | <关键信息>
-<时间> | data_convert | <成功/失败> | — | <关键信息>（钉钉表格场景）
-<时间> | fc_invoke | <成功/失败> | — | <关键信息>
-<时间> | op_writeback | <成功/失败> | — | <关键信息>
-<时间> | finish/fail | <最终状态> | — | <关键信息>
-
-【详细时间线】（基于 notable-fc / converter 日志）
-时间戳 | 节点 | 来源 | 关键信息
------- | ---- | ---- | --------
-<时间> | model_operation | notable-fc | <关键信息>
-<时间> | row_data_fetch | notable-fc | <关键信息>
-<时间> | spreadsheet_parse | converter | <关键信息>（钉钉表格场景）
-<时间> | data_mapping | converter | <关键信息>（钉钉表格场景）
-
-【节点完整性分析】
-- 缺失节点: <列出缺失的节点>
-- 缺失原因推断: <说明>
-
-【耗时分析】
-- data_fetch 耗时: <时长>
-- fc_invoke 耗时: <时长>
-- op_writeback 耗时: <时长>
-- 异常耗时节点: <列出>
-
-【syncMode 分析】
-- syncMode: <MANUAL/AUTO>
-- 是否自动同步: <是/否>
-- 错误码是否在 needCloseAutoErrorCode 列表中: <是/否>
-- 定时任务影响: <该错误会导致定时任务被关闭 / 无影响 / iPaaS连接器除外>
-
-【故障分类】
-- 分类: <故障类型>
-- 证据 1: <日志证据>
-- 证据 2: <日志证据>
-- 推断链路: <说明故障发生的完整链路>
-
-【证据不足点】
-- <列出仍需补充的信息>
-
-【下一步骤】步骤 5：代码仓库对照定位
-```
-
-### ⚠️ 前置条件检查
-- 步骤 3 必须已完成（日志已完整获取）
-- 必须先完成时间线分析，才能进入步骤 6 给出修复方案
-- 故障分类必须基于日志证据，不可凭经验猜测
-
----
-
-## 步骤 5：代码仓库对照定位
-
-### 📋 步骤目标
-根据日志中的错误信息和时间线分析，定位到具体的代码模块和文件。
-
-### 🔍 执行动作
-
-**动作 5.1：确定需要查看的仓库**
-
-根据步骤 4 的故障分类，确定需要查看的仓库：
-
-| 日志来源 | 仓库路径（`repo` 参数） | 职责 |
-|----------|------------------------|------|
-| notable（Java 端） | `alidocs/lippi-doc-notable` | 数据源同步的 Java 端核心逻辑 |
-| notable-fc | `alidocs/we-notable` | FC 端的数据源同步逻辑（`apps/notable-node` 为 FC 逻辑，`apps/we-notable` 为前端逻辑） |
-| converter | `alidocs/lippi-aitable-data-sync` | 钉钉表格数据解析与同步 |
-
-通过 `code` MCP 工具直接访问远程仓库主干分支的最新代码，无需本地 clone。
-
-**DataSyncComponent 实现类映射表（按 SyncTypeEnum 路由）**
-
-不同数据源类型的同步逻辑由不同的 Component 实现类处理，路由配置在 `ComponentConfig.java` 中：
-
-| SyncTypeEnum | type 值 | DataSyncComponent 实现类 | 所在仓库 | 说明 |
-|-------------|---------|-------------------------|---------|------|
-| `NOTABLE` | 0 | `NotableDataSyncComponentImpl` | lippi-doc-notable | Notable 自身表同步 |
-| `MYSQL` | 1 | `MysqlDataSyncComponentImpl` | lippi-doc-notable | MySQL 数据库同步 |
-| `OA` | 2 | `OADataSyncComponentImpl` | lippi-doc-notable | OA 审批同步 |
-| `THIRD_PARTY` | 3 | `ThirdPartyDataSyncComponentImpl` | lippi-doc-notable | 三方插件同步 |
-| `KAO_QIN` | 4 | `KaoQinDataSyncComponentImpl` | lippi-doc-notable | 考勤打卡同步 |
-| `SPREADSHEET` | 5 | `SpreadsheetDataSyncComponentImpl` | lippi-doc-notable | 钉钉表格同步 |
-| `SHENG_CAN_SYNC_TO_DING` | 6 | `Sc2DingDataSyncComponentImpl` | lippi-doc-notable | 生参→钉钉同步 |
-| `DING_SYNC_TO_SHENG_CAN` | 7 | `Ding2ScDataSyncComponentImpl` | lippi-doc-notable | 钉钉→生参同步 |
-| `IPAAS_CONNECTOR` | 8 | `ConnectorDataSyncComponentImpl` | lippi-doc-notable | iPaaS 连接器同步 |
-
-> **排查提示**：根据日志中的 `syncType` 值，可以快速定位到对应的 Component 实现类，从而缩小代码搜索范围。例如 `syncType=2` 时，应重点查看 `OADataSyncComponentImpl` 的逻辑。
-
-**动作 5.2：执行代码搜索**
-
-根据日志中的关键信息，选择合适的搜索工具：
-
-| 排查场景 | 推荐工具 | 说明 |
-|----------|---------|------|
-| 从日志中的错误信息 / 类名 / 函数名定位代码 | `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"` |
-| 阅读文件指定行范围 | `code::tool::get_file_block` | 适合大文件只看关键片段 |
-
-典型搜索示例：
-```
-# 从错误栈中的类名精确搜索（Java 端）
-code::tool::search_code  repo="alidocs/lippi-doc-notable"  search="<日志中的类名或错误消息>"
-
-# 语义搜索数据同步逻辑（Java 端）
-code::tool::repo_vector_search  repo="alidocs/lippi-doc-notable"  question="数据源同步数据获取逻辑"
-
-# 从日志中的错误信息精确搜索（FC 端）
-code::tool::search_code  repo="alidocs/we-notable"  search="<日志中的错误消息或函数名>"
-
-# 从日志中的错误信息搜索（converter）
-code::tool::search_code  repo="alidocs/lippi-aitable-data-sync"  search="<错误关键词>"
-
-# 阅读定位到的文件
-code::tool::get_single_file  repo="<仓库路径>"  ref="master"  filePath="<定位到的文件路径>"
-```
-
-**动作 5.3：阅读关键代码**
-
-定位到文件后，使用 `code::tool::get_single_file` 或 `code::tool::get_file_block` 阅读代码，重点关注：
-- 错误产生的具体位置（类名 / 方法名 / 行号）
-- 异常处理逻辑是否完善
-- traceId 是否完整透传
-- 协议字段是否对齐（Java 端 ↔ FC 端 ↔ converter）
-
-**动作 5.4：确认根因**
-
-对照代码逻辑，确认：
-- 日志中的错误是在哪个模块/函数中产生的
-- 为什么会产生这个错误
-- 是否有异常处理逻辑
-- traceId 是否完整透传
-- 协议字段是否对齐（Java 端 ↔ FC 端 ↔ converter）
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 5 完成：代码定位
-
-【需要查看的仓库】
-- notable（Java 端）: <是/否> - <原因>
-- notable-fc: <是/否> - <原因>
-- converter: <是/否> - <原因>
-
-【代码搜索记录】
-1. 仓库: <仓库名>
-   - 搜索工具: <工具名>
-   - 搜索关键词: <关键词>
-   - 搜索结果: <定位到的文件/类/方法>
-
-2. 仓库: <仓库名>
-   - 搜索工具: <工具名>
-   - 搜索关键词: <关键词>
-   - 搜索结果: <定位到的文件/类/方法>
-
-【关键代码位置】
-- 文件路径: <路径>
-- 类名: <类名>
-- 方法名: <方法名>
-- 行号范围: <起始行-结束行>
-- 代码职责: <说明>
-
-【根因确认】
-- 错误产生位置: <模块/函数>
-- 错误产生原因: <说明>
-- 异常处理逻辑: <是否存在，是否完善>
-- traceId 透传: <是否完整>
-- 协议字段对齐: <是否对齐>
-
-【下一步骤】步骤 6：输出可执行的 MR 修复方案
-```
-
-### ⚠️ 前置条件检查
-- 步骤 4 必须已完成（时间线已建立，故障已分类）
-- 代码定位必须基于日志证据，不可凭经验猜测
-- 必须确认根因后才能进入步骤 6
-
----
-
-## 步骤 6：输出可执行的 MR 修复方案
-
-### 📋 步骤目标
-基于日志证据和代码分析，输出可执行的 MR 修复方案。
-
-### 🔍 执行动作
-
-**动作 6.1：总结根因**
-
-基于步骤 4 的时间线和步骤 5 的代码分析，总结根因。
-
-**动作 6.2：制定修复方案**
-
-按以下结构输出修复方案。
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 6 完成：MR 修复方案
-
-### 1) 根因总结（基于日志证据）
-- 证据 1：
-- 证据 2：
-- 推断链路：
-
-### 2) 修复目标
-- 目标行为：
-- 覆盖边界条件：
-
-### 3) 改动范围（仓库 / 模块 / 文件级别）
-- 仓库：
-- 目录 / 文件（尽可能精确的路径或文件名模式）：
-- 关键函数 / 接口：
-
-### 4) 具体改动点（可落地）
-- 入参校验 / 默认值：
-- 数据获取与转化逻辑修复：
-- FC 调用与模型操作修复：
-- op 写入与回写逻辑修复：
-- 协议字段对齐（Java 端 ↔ FC 端 ↔ converter）：
-- 结构化日志补充（必须确保 traceId 可追踪，日志内容中应包含 traceId 值本身以便直接 query 命中）：
-
-### 5) 兼容性与风险
-- 对存量数据 / 历史同步任务影响：
-- 是否需要灰度：
-- 回滚策略：
-
-### 6) 验证方案
-- 单测建议：
-- 集成 / 端到端测试建议：
-- 线上验证步骤（如何用 traceId 对照）：
-- 期望看到的关键日志 / 指标变化：
-
-### 7) 附加改进（可选）
-- 埋点 / 告警建议（如 ERROR 比例、同步失败率、转换超时率）：
-- 日志字段标准化建议：
-```
-
-【下一步骤】步骤 7：记录排查经验到 MEMORY.md
-
-### ⚠️ 前置条件检查
-- 步骤 4 必须已完成（时间线已建立）
-- 步骤 5 必须已完成（代码已定位，根因已确认）
-- 修复方案必须基于日志证据和代码分析，不可凭经验猜测
-
----
-
-## 步骤 7：记录排查经验到 MEMORY.md
-
-### 📋 步骤目标
-将本次排查产生的可复用知识沉淀到 MEMORY.md，避免团队重复排查相同问题。
-
-### 🔍 执行动作
-
-**动作 7.1：阅读当前 MEMORY.md**
-
-先阅读当前 skill 目录下的 `MEMORY.md`，了解已有的 FAQ 和重点代码位置。
-
-**动作 7.2：判断是否有新增内容**
-
-检查本次排查是否产生了新的可复用知识：
-- 故障模式是否具有通用性（非一次性的配置错误或偶发问题）
-- 定位到的代码位置是否之前未记录
-- 如果所有发现均已存在于 MEMORY.md 中，说明"已检查 MEMORY.md，本次无新增内容"
-
-**动作 7.3：追加新内容到 MEMORY.md**
-
-将本次排查产生的新知识追加到 MEMORY.md，避免团队重复排查相同问题。若本次排查确实没有任何新信息，在对话中说明"已检查 MEMORY.md，本次无新增内容"即可。
-
-### 需要记录的内容
-
-**FAQ（常见故障模式）**：当本次排查的故障模式具有通用性（非一次性的配置错误或偶发问题）时，按以下格式追加到 `MEMORY.md` 的 FAQ 部分：
-
-```markdown
-### <简短标题>
-- **现象**：用户看到的表现
-- **根因**：日志/代码层面的原因
-- **关联仓库**：涉及的代码仓库
-- **日志特征**：在哪个日志库中出现什么关键词可命中此问题
-```
-
-**重点代码位置**：当排查过程中定位到了某个仓库中与数据源同步链路高度相关、但之前未记录的关键模块/文件/函数时，追加到 `MEMORY.md` 对应仓库的"重点代码位置"部分：
-
-```markdown
-- `<文件路径或模块>` — 简要说明职责/排查价值
-```
-
-### 记录原则
-
-- 只记录**有复用价值**的信息，不记录一次性的、特定于某个 traceId 的细节
-- 避免重复：追加前先检查 `MEMORY.md` 中是否已有相同或相似的记录
-- 保持简洁：每条 FAQ 控制在 4 行以内，每条代码位置控制在 1 行
-- **遵守模板格式**：FAQ 只包含"现象"、"根因"、"关联仓库"、"日志特征"四个字段，不添加额外字段（如"解法"、"排查时间"等），保持格式统一便于快速扫描
-- **追加到已有章节**：FAQ 追加到"## FAQ：常见故障模式"章节末尾、代码位置追加到"## 重点代码位置"下对应仓库的子章节末尾。不要创建新的顶级章节（如"本次排查新增记录"等），因为分散的章节会让后续查阅者难以找到信息
-
-### ✅ 步骤输出格式
-
-必须按以下格式输出本步骤结果：
-
-```
-✅ 步骤 7 完成：MEMORY.md 更新
-
-【MEMORY.md 检查结果】
-- 已阅读当前 MEMORY.md: <是/否>
-- 是否有新增内容: <是/否>
-
-【新增 FAQ】（如有）
-### <简短标题>
-- **现象**：<用户看到的表现>
-- **根因**：<日志/代码层面的原因>
-- **关联仓库**：<涉及的代码仓库>
-- **日志特征**：<在哪个日志库中出现什么关键词可命中此问题>
-
-【新增重点代码位置】（如有）
-- `<文件路径或模块>` — <简要说明职责/排查价值>
-
-【无新增内容说明】（如无新增）
-- 原因: <说明为什么本次排查没有产生新的可复用知识>
-
-【排查任务完成】
-✅ 所有 7 个步骤已完成
-✅ 排查经验已沉淀到 MEMORY.md
-```
-
-### ⚠️ 前置条件检查
-- 步骤 6 必须已完成（修复方案已输出）
-- 必须先阅读 MEMORY.md 再判断是否有新增内容
-- 新增内容必须追加到已有章节，不可创建新章节
-
----
-
-## 核心约束（必须严格遵守）
-
-以下约束贯穿整个排查流程。违反这些约束会直接导致排查结论不可靠或链路信息不完整。
-
-### 步骤执行约束
-
-0. **严格按照步骤顺序执行**
-   - 必须按 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 的顺序执行
-   - 每个步骤完成后必须输出该步骤的结果
-   - 禁止跳步或并行执行
-   - 每个步骤必须检查前置条件是否满足
-
-### 日志证据优先
-
-1. **结论基于日志证据**
-   - 排查的核心价值在于用日志事实还原故障链路，而非凭经验猜测
-   - 证据不足时，明确指出不足点并提出下一步查询条件或时间范围
-   - 禁止给出无依据的推测
-
-2. **先完成时间线再给修复建议**
-   - 跳过步骤 4 的时间线与故障分类直接给修复方案，容易遗漏并发问题或上下游关联故障
-   - 步骤 6 必须在步骤 4 和步骤 5 完成后才能执行
-
-### 查询规范
-
-3. **时间范围固定为 ±30分钟**
-   - 基于用户提供的准确时间戳计算：fromTime = 时间戳(秒) - 1200，toTime = 时间戳(秒) + 600
-   - 禁止扩大时间范围，0 命中时直接认为信息有误
-   - 在步骤 1 中计算时间范围
-
-4. **SLS `limit` 上限为 100**
-   - 超出时采用"缩小时间范围 + 多次查询"策略获取完整数据
-   - 在步骤 3 中处理分页问题
-
-5. **查询必须包含 traceId**
-   - 不含具体 traceId 的宽泛查询会命中大量无关日志，无法定位具体问题
-   - 若当前尚无 traceId，先回到步骤 0 引导用户补充
-   - 或通过 docKey、时间戳反查出 traceId（步骤 0.4）
-
-6. **traceId 查询写法**
-   - query 直接使用 traceId 字符串本身（如 `"213f7b2d17742467903238520e1257"`）
-   - 不使用 `traceId:xxx` 写法
-   - 含特殊字符时用双引号包裹，防止 SLS 拆词导致误匹配或漏匹配
-   - 详见步骤 2 查询写法规范
-
-7. **extErrorMsg 深度查询**
-   - 当 Java 端日志显示 `errorCode=0`（同步请求处理成功）但实际同步失败时
-   - 真正的错误信息存储在 message 字段的 extErrorMsg 中
-   - 需要使用 `extErrorMsg` 或 `errorDetailMap` 关键词在 INFO 级别日志中进行深度查询
-
-### 日志库覆盖
-
-8. **双库必查**
-   - `notable（Java 端）` 和 `notable-fc` 每次排查都要查询
-   - 数据源同步链路横跨 Java 端和 FC 执行层，仅查部分库容易遗漏跨层问题
-   - 即使某个库已找到明确线索，仍须查询另一个以获取完整链路视图
-   - 在步骤 2 中执行
-
-9. **钉钉表格场景加查 converter**
-   - 同步场景为钉钉表格时，数据转换逻辑运行在 converter 中
-   - 必须查询 `lippi-doc-converter : master` 日志以获取完整链路
-   - 在步骤 2 中执行
-
-10. **FC 日志需 `requestId` 二次查询**
-    - traceId 在 `notable-fc` 中仅命中入口日志
-    - 完整调用链路需要提取 `requestId` 后二次查询
-    - 多条命中时需对每个不同的 `requestId` 分别查询
-    - 在步骤 2 中执行
-
-### 排查闭环
-
-11. **更新 MEMORY.md**（步骤 7）
-    - 排查产生的可复用知识（FAQ 模式、关键代码路径）需要沉淀
-    - 避免团队重复排查相同问题
-    - 若确实无新增内容，在对话中说明理由即可
-    - 步骤 7 是排查流程的最后一步，不可跳过
-
----
-
-## 快速检查清单
-
-在开始排查前，使用此清单确认你理解了执行要求：
-
-- [ ] 我已理解必须按 0→1→2→3→4→5→6→7 的顺序执行
-- [ ] 我已理解每个步骤完成后必须输出该步骤的结果
-- [ ] 我已理解禁止跳步或并行执行
-- [ ] 我已理解每个步骤都有前置条件检查
-- [ ] 我已理解用户必须提供时间戳，时间范围固定为 ±30分钟
-- [ ] 我已理解 0 命中时禁止扩大时间范围，必须回到步骤 0 确认信息
-- [ ] 我已理解 notable 和 notable-fc 必须同时查询
-- [ ] 我已理解钉钉表格场景必须查询 converter
-- [ ] 我已理解 FC 日志需要 requestId 二次查询
-- [ ] 我已理解必须先完成时间线（步骤 4）再给修复方案（步骤 6）
-- [ ] 我已理解必须更新 MEMORY.md（步骤 7）
-
-开始排查时，从步骤 0 开始执行。