aitable-workflow-cli 0.1.23 → 0.1.24

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

@@ -1,183 +0,0 @@
----
-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/support-qa/profiles/aitable/skills/troubleshooting/import-openapi-e2e-troubleshooter/SKILL.md

@@ -1,459 +0,0 @@
----
-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` 在 `|` 左侧过滤