aitable-workflow-cli 0.1.13-beta.1

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

@@ -0,0 +1,183 @@
+---
+name: aitable-openapi-troubleshooter
+version: 0.3.0
+description: 排查 AI表格/文档 OpenAPI 线上错误。用户提供 requestId 或 traceId 时触发，按完整调用链（lippi-doc-solution → lippi-doc-notable → notable-fc → 回调 lippi-doc-notable HSF）逐层定位错误根因，判断是下游报错、FC 执行异常还是抖动/超时。
+allowed-tools: mcp__sls-mcp__list_sls_projects, mcp__sls-mcp__query_sls_logs, mcp__sls-mcp__query_sls_logs_full, mcp__sls-mcp__get_sls_log_detail
+---
+
+# OpenAPI 错误排查 Skill
+
+用户给出 requestId 或 traceId，在 SLS 日志中定位 AI表格/文档 OpenAPI 错误根因。
+
+## 整体架构
+
+```
+用户/OpenAPI平台 (pop-aliyun-com)
+  └─ lippi-doc-solution          【网关层】SLS: lippi-doc-solution / master / cn-wulanchabu
+       └─ lippi-doc-notable      【中间层】SLS: lippi-doc-notable / master / cn-wulanchabu
+            └─ notable-fc        【主执行层★】SLS: lippi-doc-notable-frontend / notable-fc / cn-hangzhou
+                 └─ lippi-doc-notable (HSF 回调)
+                      ↑ notable-fc 内部需要业务数据时（用户信息、文档信息等），
+                        会再次调用 lippi-doc-notable 上注册的 HSF 方法
+```
+
+**关键认知**：OpenAPI 的实际业务逻辑主要跑在 notable-fc 这个 FC 容器里。`lippi-doc-solution` 是网关，`lippi-doc-notable` 做简单权限校验后把请求转发给 notable-fc；notable-fc 执行业务时如果需要获取文档信息、用户信息等，会回调 `lippi-doc-notable` 的 HSF 接口。所以排查时要优先看 notable-fc 的日志。
+
+## SLS 资源清单
+
+| 层级 | SLS Project | Logstore | Region |
+|---|---|---|---|
+| 网关层 | `lippi-doc-solution` | `master` | `cn-wulanchabu` |
+| 中间层 | `lippi-doc-notable` | `master` | `cn-wulanchabu` |
+| **主执行层** | `lippi-doc-notable-frontend` | `notable-fc` | `cn-hangzhou` |
+
+## 排查路径
+
+### 第一步：从网关层确认请求基本信息
+
+用 requestId 或 traceId 在 `lippi-doc-solution` 查请求入口日志：
+
+```
+projectName: lippi-doc-solution
+logstoreName: master
+region: cn-wulanchabu
+query: <requestId 或 traceId>
+quickTimeRange: 最近7天（用户提供具体时间则用 fromTime/toTime）
+```
+
+提取关键字段：
+- `baseId` / `sheetIdOrName` —— 目标文档/表格
+- `appId` / `systemOrgId` / `userId` —— 调用方身份
+- `methodName` —— 调用的 OpenAPI 接口
+- `callerApp` —— 上游调用方（如 `pop-aliyun-com`）
+- `rt` / `errorCode` / `errorMessage`
+
+同时关注 `HSF-CLIENT-DIGEST` 日志判断网关层到中间层的调用是否正常。
+
+### 第二步：在 notable-fc 查主执行日志（核心）
+
+FC 容器是实际执行业务逻辑的地方，用 traceId 或 requestId 查：
+
+```
+projectName: lippi-doc-notable-frontend
+logstoreName: notable-fc
+region: cn-hangzhou
+query: <traceId 或 requestId>
+```
+
+重点看：
+- FC 内部的 ERROR / WARN 日志
+- notable-fc 向 lippi-doc-notable 发起 HSF 回调时的错误（如获取文档信息、用户信息失败）
+- 函数执行是否超时或冷启动
+
+### 第三步：必要时在 lippi-doc-notable 查中间层日志
+
+用于确认权限校验、转发阶段是否有问题，或者查看 notable-fc 回调过来的 HSF 方法执行情况：
+
+```
+projectName: lippi-doc-notable
+logstoreName: master
+region: cn-wulanchabu
+query: <traceId>
+```
+
+### 第四步：判断是抖动还是确定性错误
+
+**网关超时阈值：6000ms**。`lippi-doc-solution` 网关对下游的超时限制为 6s，超过后外部调用者会收到超时报错。排查时先看 `lippi-doc-solution` 的 `rt` 字段：
+- `rt >= 6000` → 网关超时，需重点看 notable-fc 是否执行慢或冷启动
+- `rt < 6000` 但有错误 → 下游确定性报错，看错误码和错误信息
+
+| 特征 | 判断 |
+|---|---|
+| `time=FAST`，rt 在几百ms内，有具体业务错误码 | 下游**确定性业务报错**，不是抖动 |
+| `time=SLOW` 或 `rt >= 6000` | **网关超时**，外部调用者同样收到报错，重点排查 notable-fc 执行耗时 |
+| 同时间段多个不同 baseId/userId 均报同一错误 | 服务级别问题，非单文档问题 |
+| 只有特定 baseId 报错 | 文档数据问题（文档不存在/被删除/权限） |
+| notable-fc 日志有冷启动或函数超时 | FC 容器层面问题，可能导致网关超时 |
+
+### 第五步：判断是偶现问题还是批量底层抖动（必查）
+
+**无论错误类型如何，都要做两个维度的交叉验证：**
+
+#### 5.1 横向：同时间段内其他文档是否有同样的问题？
+
+在 notable-fc 查询出错时间点前后 **±5 分钟**，搜索同类型的关键日志（去掉 baseId/docId 条件），看是否有大批量不同文档出现相同的慢或报错：
+
+```
+projectName: lippi-doc-notable-frontend
+logstoreName: notable-fc
+region: cn-hangzhou
+query: <关键方法名或错误关键词，不加 docId>
+fromTime/toTime: 出错时间点 ±5 分钟
+limit: 50
+```
+
+- **大量不同 docId 同时出现慢/报错** → 底层服务（OSS / HSF / 依赖中间件）在该时段出现整体抖动，属于**平台级问题**，不是文档本身的问题
+- **只有该 docId 出现问题** → 文档特有，继续下钻数据/权限层面
+
+典型场景：`getCheckpointAndOps` 的 cpDownloadTime / opsDownloadTime 同时在多个 docId 异常飙高 → OSS 访问慢
+
+#### 5.2 纵向：该文档历史上是否多次出现同样的问题？
+
+用具体的 docId/baseId 查询最近 7 天的同类日志：
+
+```
+projectName: lippi-doc-notable-frontend
+logstoreName: notable-fc
+region: cn-hangzhou
+query: <docId 或 baseId> AND <关键方法名或错误关键词>
+quickTimeRange: 最近7天
+```
+
+- **历史多次复现** → 该文档存在持续性问题（数据量过大、频繁写入、权限配置错误等），需针对该文档排查
+- **历史从未出现，仅此一次** → 结合 5.1 的横向结果，大概率是外部平台抖动的连带影响，无需针对文档处理
+
+#### 5.3 综合判断矩阵
+
+**⚠️ 前置闸门（必须先判错误类型，再决定要不要套抖动矩阵）**：下面的「横向×纵向」矩阵只对**时延/超时类**错误成立。先用第四步的判定：
+
+- **确定性业务报错（4xx，如 `InvalidRequest.ResourceNotFound`、`fail to find field`、参数/数据校验失败，且 `rt` 短、未超时）** → **不套抖动矩阵**。此时根因已在调用方的请求参数/数据，横向「同时段多文档同错」≠ 平台抖动，只说明**多个调用方各自请求都不对（调用方共性问题）**，绝不能误判成平台抖动。
+  - 横向大批量 → 调用方共性问题（多个客户端批量写入 schema/参数不匹配）
+  - 仅该文档 → 单一调用方/文档的请求参数错误
+- **超时 / 慢 / 未知类（`rt >= 6000`、`time=SLOW`、无明确业务错误码）** → 才用下面的抖动矩阵区分平台 vs 文档。
+
+| 横向（同时段其他文档） | 纵向（该文档历史） | 结论 |
+|---|---|---|
+| 大批量受影响 | 无历史复现 | **平台级抖动**（OSS/HSF/中间件），非文档问题 |
+| 大批量受影响 | 历史多次复现 | 平台抖动 + 文档本身也有性能问题，双重因素 |
+| 仅该文档受影响 | 历史多次复现 | **文档特有持续性问题**，需针对文档排查 |
+| 仅该文档受影响 | 无历史复现 | 偶发性异常，可能是单次资源竞争，观察为主 |
+
+> 真实踩坑（requestId `C127F54A`）：`insertRecords` 引用了目标表不存在的字段，同时段 ±5min 内 `fail to find field` 跨多个 docId 命中 528 条。若直接套矩阵会误判「平台级抖动」，但逐层证据均为各自表的确定性 4xx 校验错——正确结论是**调用方共性问题，非平台抖动**。
+
+## 常见错误模式
+
+### `fail to get document info` (errorCode: 5000001)
+- **位置**：通常是 notable-fc 内部回调 `lippi-doc-notable` 的 `getSheetFields` / `getDocumentInfo` 失败
+- **是抖动吗**：看 `time=FAST` 则为确定性报错
+- **可能原因**：文档不存在/已删除；notable HSF 服务在该时段异常
+
+### `internalError`
+- `lippi-doc-solution` 对下游错误的统一包装，需结合下游日志看真实错误码
+
+## AI表格接口范围（错误统计专用）
+
+统计 AI表格 OpenAPI 错误时，**只统计以下接口**，不含文档类接口：
+
+```
+deleteRecords, insertRecords, updateRecords, listRecord, getRecord, getRecords,
+createField, updateField, deleteField, getAllFields,
+createSheet, deleteSheet
+```
+
+**不包含**：`getRange`, `getAllSheets`, `docExport`, `getDelegatedDocContent`, `getSheet`, `updateRange`, `docAppendText`, `docBlocksQuery`, `getDocContent`, `updateSheet`, `docExportByDelegatedPermission` 等。
+
+## 输出格式
+
+排查结束后，输出：
+
+1. **发生时间** & **总耗时**
+2. **调用信息**（baseId、orgId、userId、methodName、callerApp）
+3. **错误链**：在哪一层报错（网关层 / 中间层 / notable-fc / FC 回调 HSF）
+4. **判断**：是抖动 / 确定性业务报错 / 文档数据问题 / FC 执行异常
+5. **建议**：下一步去哪个服务/日志继续排查

package/templates/aitable-handoff/workspaces/faq-troubleshooter/skills/troubleshooting/import-openapi-e2e-troubleshooter/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: import-openapi-e2e-troubleshooter
+version: 0.2.0
+description: >-
+  多维表导入 OpenAPI 端到端排查与监控技能。
+  两种模式：(1) 大盘模式——展示导入链路各层成功率、失败原因分布；
+  (2) 单次排查模式——用户提供 traceId / jobId / baseId / docId / importId 时，
+  追踪这一次导入从 OpenAPI 网关到 converter 转换的全链路失败根因。
+  触发词："导入排查"、"导入成功率"、"导入大盘"、"import troubleshoot"、
+  "导入失败"、"查导入链路"。
+allowed-tools: mcp__sls-mcp__list_sls_projects, mcp__sls-mcp__query_sls_logs, mcp__sls-mcp__query_sls_logs_full, mcp__sls-mcp__get_sls_log_detail, mcp__sls-mcp__count_sls_logs
+---
+
+# 多维表导入 OpenAPI 端到端排查
+
+## 整体架构
+
+```
+Client
+  └─ OpenAPI Gateway (pop-aliyun-com)
+       └─ lippi-doc-solution           【网关层】  SLS: lippi-doc-solution / master / cn-wulanchabu
+            └─ lippi-doc-notable        【业务层】  SLS: lippi-doc-notable / master / cn-wulanchabu
+                 ├─ lippi-doc-converter-notable  【转换层】SLS: lippi-doc-converter / master / cn-wulanchabu
+                 │    └─ CsvConvertServiceImpl / XlsxConvertService
+                 │         └─ lippi-doc-notable-core (HSF: isNotableCoreApiEnabled 等)
+                 └─ notable-fc          【写入层】  SLS: lippi-doc-notable-frontend / notable-fc / cn-hangzhou
+                      └─ 写入 records → lippi-doc-notable (HSF 回调)
+```
+
+**导入流程**：
+1. Client 调 `prepareImportUpload` → 获取上传链接和 importId
+2. Client 上传文件到 OSS
+3. Client 调 `executeImport` → lippi-doc-notable 创建导入会话，发 MQ 消息给 converter
+4. converter-notable 消费 MQ，下载文件并解析（CSV 走 Java CsvConvertServiceImpl，xlsx 走 Rust gRPC）
+5. converter-notable 写入数据到 notable（通过 notable-fc 或直接 HSF）
+6. 转换完成后回调 lippi-doc-notable 更新导入状态
+7. Client 轮询 `queryImportStatus` 获取最终结果
+
+**关键认知**：
+- solution 层的 `queryImportStatus` 返回 `IMPORT_FAILED` 时，`errorMessage` 只有 `"data import job failed: jobId=xxx"`，**没有有效信息**
+- 真正的失败原因在 **converter-notable 的 ERROR 日志**中，必须用 jobId 去 converter 层查
+- converter-notable 的错误日志几乎都会截断，**必须用 `get_sls_log_detail` 获取完整堆栈**
+
+## SLS 资源清单
+
+| 层级 | SLS Project | Logstore | Region | 说明 |
+|---|---|---|---|---|
+| 网关层 | `lippi-doc-solution` | `master` | `cn-wulanchabu` | 4 个 OpenAPI 的 HSF DIGEST/RESPONSE 日志 |
+| 业务层 | `lippi-doc-notable` | `master` | `cn-wulanchabu` | 导入会话管理、MQ 回调状态 |
+| **转换层** | `lippi-doc-converter` | `master` | `cn-wulanchabu` | converter-notable 的转换执行日志（**根因所在**） |
+| 写入层 | `lippi-doc-notable-frontend` | `notable-fc` | `cn-hangzhou` | FC 写入数据时的错误（行数超限、字段不存在等） |
+
+## 日志格式要点
+
+### solution 层（content 大字段，无独立索引列）
+
+所有字段都在 `content` 文本中，分析时用 `regexp_extract` 提取：
+
+```
+HSF-SERVER-DIGEST 格式:
+category=HSF-SERVER-DIGEST, rt=24, role=provider, clientIp=..., methodName=getImportEncryptPublicKey, time=FAST, serviceName=...ImportApiService_Open, callerApp=pop-aliyun-com, status=OK
+
+HSF-SERVER-RESPONSE 格式:
+category=HSF-SERVER-RESPONSE, role=provider, response={"result":{"phase":"COMPLETED","status":"success",...},"success":true}, ... methodName=queryImportStatus, ...
+
+traceId 位于 content 的第一个 | 分隔字段:
+2026-06-09 11:12:48.697|<traceId>|<rpcId>|...
+提取方式: regexp_extract(content, '^[^|]+\|([^|]+)\|', 1)
+```
+
+### converter-notable 层（独立索引列）
+
+有独立索引列：`traceId`、`level`、`logger`、`message`、`time` 等。
+关键日志：
+- `logger=SERVICE_DETAIL_LOGGER` + `ConverterNotableConvertJobConsumer` + `success=N` → 转换失败
+- `logger=SERVICE_DIGEST_LOGGER` + `setFailedStatusAndErrCode` → 设置失败状态
+
+### notable-fc 层（部分独立索引列）
+
+索引列：`errorCode`、`method`、`category`、`appType`、`success`、`docId`、`uid` 等。
+**非索引列**：`message`、`errorMsg`（需用全文检索过滤）。
+
+---
+
+## 模式一：大盘模式
+
+用户说"导入成功率"、"导入大盘"、"导入监控"时触发。
+
+### 第一步：查询 OpenAPI 网关层指标
+
+```
+projectName: lippi-doc-solution
+logstoreName: master
+region: cn-wulanchabu
+quickTimeRange: 最近7天（或用户指定的时间范围）
+```
+
+**查询 1 — 各接口调用量 + 成功率 + RT**：
+
+```sql
+HSF-SERVER-DIGEST and (getImportEncryptPublicKey or prepareImportUpload or executeImport or queryImportStatus)
+| select
+    regexp_extract(content, 'methodName=(\w+)', 1) as method_name,
+    count(distinct regexp_extract(content, '^[^|]+\|([^|]+)\|', 1)) as total,
+    sum(case when regexp_extract(content, 'status=(\w+)', 1) = 'OK' then 1 else 0 end) * 100.0 / count(1) as success_pct,
+    avg(cast(regexp_extract(content, 'rt=(\d+)', 1) as bigint)) as avg_rt,
+    approx_percentile(cast(regexp_extract(content, 'rt=(\d+)', 1) as bigint), 0.99) as p99_rt
+  group by regexp_extract(content, 'methodName=(\w+)', 1)
+  order by total desc
+```
+
+**查询 2 — 导入任务终态分布**：
+
+```sql
+HSF-SERVER-RESPONSE and queryImportStatus and (COMPLETED or FAILED or IMPORT_FAILED)
+| select
+    regexp_extract(content, '"phase":"(\w+)"', 1) as phase,
+    count(distinct regexp_extract(content, '^[^|]+\|([^|]+)\|', 1)) as cnt
+  group by regexp_extract(content, '"phase":"(\w+)"', 1)
+```
+
+**查询 3 — 端到端漏斗**：
+
+```sql
+HSF-SERVER-DIGEST and (getImportEncryptPublicKey or prepareImportUpload or executeImport or queryImportStatus)
+| select
+    regexp_extract(content, 'methodName=(\w+)', 1) as step,
+    count(distinct regexp_extract(content, '^[^|]+\|([^|]+)\|', 1)) as cnt
+  where regexp_extract(content, 'methodName=(\w+)', 1) in ('prepareImportUpload', 'executeImport', 'queryImportStatus')
+  group by regexp_extract(content, 'methodName=(\w+)', 1)
+```
+
+**查询 4 — 业务失败原因**：
+
+```sql
+HSF-SERVER-RESPONSE and queryImportStatus and IMPORT_FAILED
+| select
+    regexp_extract(content, '"errorCode":"([^"]+)"', 1) as error_code,
+    regexp_extract(content, '"errorMessage":"([^"]+)"', 1) as error_msg,
+    count(1) as cnt
+  group by
+    regexp_extract(content, '"errorCode":"([^"]+)"', 1),
+    regexp_extract(content, '"errorMessage":"([^"]+)"', 1)
+  order by cnt desc
+```
+
+### 第二步：查询 converter 转换层失败
+
+```
+projectName: lippi-doc-converter
+logstoreName: master
+region: cn-wulanchabu
+quickTimeRange: 最近7天
+```
+
+**查询 5 — 转换失败总量**：
+
+```sql
+ConverterNotableConvertJobConsumer and success=N | select count(1) as cnt
+```
+
+**查询 6 — 转换失败按 jobType 和 errorCode 分布**：
+
+```sql
+ConverterNotableConvertJobConsumer and success=N | select jobType, errorCode, count(1) as cnt group by jobType, errorCode order by cnt desc
+```
+
+### 第三步：查询 notable-fc 写入层失败
+
+```
+projectName: lippi-doc-notable-frontend
+logstoreName: notable-fc
+region: cn-hangzhou
+quickTimeRange: 最近7天
+```
+
+**查询 7 — FC 写入层失败总量**：
+
+```sql
+appType=IMPORT and success=false | select count(1) as cnt
+```
+
+**查询 8 — FC 写入层按方法分布**：
+
+```sql
+appType=IMPORT and success=false | select method, count(1) as cnt group by method order by cnt desc
+```
+
+**查询 9 — FC 写入层错误分类**（`message` 不是索引列，用全文检索分类，每个独立查询）：
+
+| 错误类型 | 查询语句（`|` 右侧统一用 `select count(1) as cnt`） |
+|---|---|
+| 限流 429 | `appType=IMPORT and success=false and "Too Many Requests" \| select count(1) as cnt` |
+| HSF 超时 | `appType=IMPORT and success=false and "no response in" \| select count(1) as cnt` |
+| 超行数上限 | `appType=IMPORT and success=false and "at most" and records \| select count(1) as cnt` |
+| 超表数上限 | `appType=IMPORT and success=false and "at most" and sheet \| select count(1) as cnt` |
+| 字段不存在 | `appType=IMPORT and success=false and "fail to find field" \| select count(1) as cnt` |
+| 线程池满 | `appType=IMPORT and success=false and "thread pool is full" \| select count(1) as cnt` |
+
+### 第四步：输出大盘报告
+
+```markdown
+## 多维表导入 OpenAPI 大盘（<时间范围>）
+
+### 一、OpenAPI 网关层
+| 接口 | 调用量 | HSF 成功率 | Avg RT | P99 RT |
+|---|---|---|---|---|
+| getImportEncryptPublicKey | X | X% | Xms | Xms |
+| prepareImportUpload | X | X% | Xms | Xms |
+| executeImport | X | X% | Xms | Xms |
+| queryImportStatus | X | X% | Xms | Xms |
+
+### 二、导入任务端到端结果
+| 终态 | 数量 | 占比 |
+|---|---|---|
+| COMPLETED (成功) | X | X% |
+| FAILED (失败) | X | X% |
+
+**业务成功率**: X / (X + X) = **X%**
+
+### 三、端到端漏斗
+prepareImportUpload: X → executeImport: X → queryImportStatus(终态): X
+
+### 四、converter 转换层失败
+| jobType | errorCode | 数量 |
+|---|---|---|
+| CSV_TO_NOTABLE_V2 | 80000001 | X |
+| ... | ... | ... |
+
+### 五、notable-fc 写入层失败
+| 错误类型 | 数量 |
+|---|---|
+| 限流 (429) | X |
+| HSF 超时 | X |
+| 超行数上限 | X |
+| ... | ... |
+```
+
+---
+
+## 模式二：单次排查模式
+
+用户提供 traceId / jobId / baseId / docId / importId 中任意一个时触发。
+
+### 第一步：提取标识符
+
+从用户输入中识别：
+- `traceId` — EagleEye traceId（32 位十六进制，如 `21076a0017810575336547930d009c`）
+- `jobId` — converter 转换任务 ID（如 `28375009612`）
+- `importId` — 导入会话 ID（如 `imp_182d186a226349f993d18f5e50a12b5c`）
+- `baseId` / `docId` — 目标文档 ID
+
+**标识符关联规则**：
+- traceId 贯穿全链路，可查所有层
+- jobId 出现在 converter 层和 notable 层的 MQ 回调日志中
+- importId 出现在 solution 层的 RESPONSE 日志和 notable 层的 ImportSessionServiceImpl 日志中
+- docId 出现在 converter 层和 notable-fc 层
+
+如果用户只给了其中一个，先查出关联的其他 ID，再逐层追踪。
+
+### 第二步：从 solution 网关层入手
+
+```
+projectName: lippi-doc-solution
+logstoreName: master
+region: cn-wulanchabu
+query: <traceId 或 importId>
+quickTimeRange: 最近30天
+limit: 20
+order: asc
+```
+
+提取：
+- 调用了哪个 OpenAPI（`methodName`）
+- HSF 层是否成功（`status=OK`）
+- `queryImportStatus` 的 response 中的 `phase`、`errorCode`、`errorMessage`
+- **提取 jobId**：从 `errorMessage` 中提取 `jobId=xxx`
+
+如果用户给的是 importId，从 RESPONSE 日志中找到对应的 jobId 和 traceId。
+
+### 第三步：到 converter 层查根因（核心）
+
+```
+projectName: lippi-doc-converter
+logstoreName: master
+region: cn-wulanchabu
+query: <jobId 或 traceId>
+quickTimeRange: 最近30天
+limit: 20
+order: asc
+```
+
+**重点找**：
+1. `ConverterNotableConvertJobConsumer` + `success=N` 的 ERROR 日志 → **必须用 `get_sls_log_detail` 获取完整内容**
+2. `setFailedStatusAndErrCode` 的 DIGEST 日志 → 提取 errCode
+3. `getConvertStatus` 的返回值 → 提取 `status=3`（失败）和 `errCode`
+
+从完整堆栈中提取：
+- `BusinessException` 的消息 → 真正的根因
+- `jobType`（`CSV_TO_NOTABLE_V2` / `XLSX_TO_NOTABLE_V2`）
+- `errorCode`（converter 层错误码）
+- `docId`、`uid`
+
+### 第四步：到 notable 业务层查会话状态
+
+```
+projectName: lippi-doc-notable
+logstoreName: master
+region: cn-wulanchabu
+query: <jobId 或 importId 或 traceId>
+quickTimeRange: 最近30天
+limit: 10
+order: asc
+```
+
+重点找：
+- `ImportSessionServiceImpl` + `MQ wake-up` → 导入会话被唤醒，提取 `status` 和 `errCode`
+- `ImportApiServiceImpl` + `executeImport` → 导入请求入口，提取 `dentryUuid`、`uid`、`hasEncryption`、`hasAppend`
+
+### 第五步：到 notable-fc 写入层查数据写入错误（按需）
+
+```
+projectName: lippi-doc-notable-frontend
+logstoreName: notable-fc
+region: cn-hangzhou
+query: <docId 或 traceId> and appType=IMPORT and success=false
+quickTimeRange: 最近30天
+limit: 10
+```
+
+重点看：
+- `method` — 哪个写入操作失败
+- `message` 中的 `errorCode` 和 `errorMsg`
+- `rt` — 是否超时
+
+### 第六步：横向验证（判断是否为批量问题）
+
+如果 converter 层发现是 HSF 超时或连接异常，检查同时段是否有批量失败：
+
+```
+projectName: lippi-doc-converter
+logstoreName: master
+region: cn-wulanchabu
+query: ConverterNotableConvertJobConsumer and success=N
+fromTime: <出错时间 - 300>
+toTime: <出错时间 + 300>
+```
+
+```sql
+| select errorCode, count(1) as cnt group by errorCode order by cnt desc
+```
+
+- 大量同时段失败 → 平台级抖动
+- 仅此一条 → 单任务问题
+
+### 第七步：输出排查报告
+
+```markdown
+## 导入失败排查报告
+
+**基本信息**
+- 时间：YYYY-MM-DD HH:MM:SS
+- 环境：prod / pre
+- traceId：xxx
+- jobId：xxx
+- importId：xxx
+- docId：xxx
+- uid：xxx
+
+**调用链路**
+```
+Client → OpenAPI Gateway
+  → lippi-doc-solution (methodName, rt=Xms, status=OK/FAIL)
+    → lippi-doc-notable (ImportApiServiceImpl, importId=xxx)
+      → lippi-doc-converter-notable (MQ, jobType=XXX)
+        → CsvConvertServiceImpl.xxx() ← 💥 根因
+      ← errCode=xxx, status=3(FAILED)
+    ← MQ 回调: "data import job failed: jobId=xxx"
+  ← queryImportStatus → phase=FAILED, errorCode=IMPORT_FAILED
+```
+
+**根因**：<一句话描述>
+
+**错误详情**
+- 所在层：converter-notable / notable-fc / notable
+- errorCode：xxx
+- 异常类：BusinessException / RpcException / ...
+- 异常消息：xxx
+- 代码位置：XxxServiceImpl.java:XXX
+
+**错误分类**：
+- [ ] 用户文件问题（CSV 内容为空、格式异常、二进制控制字符等）
+- [ ] 下游服务问题（notable-core 超时、连接断开等）
+- [ ] 平台限制（行数上限、表数上限、字段不存在等）
+- [ ] 系统 bug
+
+**是否为批量问题**：是/否（同时段 X 个任务失败）
+
+**建议**：
+- 给用户：xxx
+- 给研发：xxx
+```
+
+---
+
+## Converter 层常见错误码
+
+### CSV 链路（errorCode 7xxxx / 8xxxx，来自 Java CsvConvertServiceImpl）
+
+| errorCode | 异常特征 | 根因 | 建议 |
+|---|---|---|---|
+| `80000001` | `import sheet info is empty` | CSV 文件解析后无法提取有效 sheet 信息（空文件/格式不兼容） | 用户检查文件内容，确认非空 |
+| `70000015` | `Failed to invoke isNotableCoreApiEnabled` + `RpcException: timeout` | notable-core HSF 超时，converter 无法判断行数上限 | 平台侧问题，检查 notable-core 预发/生产状态 |
+| `70000015` | `Failed to invoke isNotableCoreApiEnabled` + `COMM_ERROR` / `connection closed` | notable-core 连接被断开 | 平台侧问题，检查 notable-core 节点稳定性 |
+| `70000016` | `Failed to check if notable core API is enabled` | notable-core 服务不可用，无法创建新 sheet | 平台侧问题 |
+| `70000016` | `sheet 'XXX' already exists` | 目标文档中已有同名 sheet（上次失败残留） | 用户删除残留 sheet 后重试 |
+| `70000037` | `CSV cell contains binary data` | CSV 单元格含二进制控制字符 | 用户用 Excel 打开后另存为 xlsx 重新导入 |
+
+### xlsx 链路（errorCode 3xxxx，来自 Rust gRPC）
+
+| errorCode | errMsg 特征 | 根因 | 建议 |
+|---|---|---|---|
+| `30019` | `read attribute 'r' error, value is '0'` | xlsx 中存在行号为 0 的非法行 | Excel/WPS 打开后另存 |
+| `30014` | `XMLDataIllegalError` | xlsx XML 数据不合法，文件可能损坏 | Excel/WPS 修复后重新导入 |
+| `30001` | `ZipError` | zip 解压失败，文件损坏或上传不完整 | 重新上传 |
+| `30002` | `FileEncryptedError` | 文件有密码保护 | 移除密码后重新导入 |
+| `30013` | `FileDataEmptyError` | 文件为空 | 确认文件内容 |
+| `30025` | `FileTypeError` | 非标准 xlsx 格式 | 确认文件格式 |
+
+## 注意事项
+
+- solution 层日志存在**双写**（两个路径同时采集），计数需用 `count(distinct traceId)` 去重
+- converter-notable 的 ERROR 日志**几乎都会截断**，`truncated=true` 时**必须**用 `get_sls_log_detail` 获取完整堆栈
+- `message` 字段在 notable-fc 不是索引列，无法在 `|` 右侧用 `regexp_extract`，需用全文检索（`|` 左侧）过滤
+- traceId 在不同服务中字段名可能是 `traceId` 或 `traceid`（大小写不一致），查询时用关键词搜索
+- 预发环境（`user_defined_id=lippi-doc-solution_pre`）和 生产环境（`_prod`）的失败要分开分析
+- 如果 converter 层查不到日志，可能是日志已过期（默认保留 30 天），或 jobId 不对
+- 导入 OpenAPI 的 4 个方法：`getImportEncryptPublicKey`、`prepareImportUpload`、`executeImport`、`queryImportStatus`
+
+### 各入口标识符的坑（验证结论）
+
+**traceId 入口**：
+- **traceId 跨 MQ 断链**：solution 层的 traceId 是 `queryImportStatus` 请求的（Client 轮询时产生），converter 层的 traceId 是 `executeImport` 请求的（触发转换时产生），**两者不同**
+- 不能用 solution 层的 traceId 直接搜 converter 层，必须先从 solution 层提取 jobId，再用 jobId 搜 converter
+- 从 solution 层提取 jobId 的方式：搜 traceId → 找到 `HSF-CLIENT-RESPONSE` 日志 → 从 response JSON 中提取 `dataJobId`
+
+**importId 入口**：
+- solution 层全文检索 importId **可以命中**（importId 出现在 prepareImportUpload / executeImport / queryImportStatus 三个阶段的日志中）
+- 从 `queryImportStatus` 的 IMPORT_FAILED 日志中提取 `dataJobId` → 下钻 converter 层
+
+**docId 入口**：
+- converter 层用 docId 搜索 **30 天范围容易超时**（SLS MCP HSF 超时），应缩小到 **7 天**
+- notable 层的 `ImportSessionServiceImpl` 和 `ImportApiServiceImpl` 日志中 **`docId` 字段为空**（`docId:""`），用 docId 搜不到 notable 层日志
+- solution 层不会直接出现 docId（solution 层用的是 baseId/dentryUuid）
+- docId 入口的正确路径：converter 层搜 docId → 提取 jobId → 用 jobId 反查 solution 层和 notable 层
+
+**converter 层 errorCode**：
+- `errorCode` 在 converter 的 `SERVICE_DETAIL_LOGGER` 日志中不是独立索引列，不能在 `|` 右侧直接引用
+- 正确做法：用全文检索 `errorCode=80000001` 在 `|` 左侧过滤