aitable-workflow-cli 0.1.13-beta.1

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

@@ -0,0 +1,485 @@
+---
+name: aitable-import-troubleshooter
+version: 0.3.0
+description: 导入失败诊断技能：根据用户提供的 traceId / docKey / importId，查询 SLS 日志并结合代码分析给出根因与话术
+---
+
+# 导入失败诊断
+
+当用户粘贴类似以下内容时触发本技能：
+
+```
+导入失败：导入失败，请稍后重试
+
+基础信息:
+docKey：Lk3lbmbAXzKvGOm9
+importId：008d5b07-8b72-42d5-899e-f3cb3e874114
+traceId：2110403d17791690576326160e09de
+```
+
+---
+
+## 服务架构与代码仓库
+
+### 调用链路
+
+导入有 3 个用户入口，全部汇聚到 `lippi-doc-notable` 的统一方法，再分发到 converter 处理：
+
+```
+┌─ 前端用户 ─── we-notable（HTTP 接口）──────────┐
+├─ MCP ──────── lippi-doc-notable-mcp（HSF）──────┼──▶ lippi-doc-notable（统一入口）──▶ lippi-doc-converter-notable ─┬──▶ CSV 纯 Java 处理
+└─ OpenAPI ──── lippi-doc-solution（HSF）──────────┘         │                                         └──▶ dimension-rs（xlsx gRPC）
+                                                             │
+                                                             └──▶ [异步场景] notable-fc（we-notable 仓库内）
+```
+
+- **前端**：用户在 we-notable 界面发起导入，通过 HTTP 调用 lippi-doc-notable
+- **MCP**：AI Agent 通过 MCP 协议调用 lippi-doc-notable-mcp，mcp 服务再通过 HSF 调用 lippi-doc-notable
+- **OpenAPI**：外部开发者通过 OpenAPI 调用 lippi-doc-solution，solution 再通过 HSF 调用 lippi-doc-notable
+
+### 服务列表
+
+| 服务 | 角色 | 接口类型 | 语言 | 代码仓库 |
+|------|------|----------|------|----------|
+| we-notable | 前端入口 + notable-fc（异步 FC） | HTTP（提供给浏览器） | TypeScript / Node.js | https://code.alibaba-inc.com/alidocs/we-notable/tree/master |
+| lippi-doc-notable-mcp | MCP 入口 | HSF（暴露给 MCP 调用方） | Java | https://code.alibaba-inc.com/alidocs/lippi-doc-notable-mcp/tree/master |
+| lippi-doc-solution | OpenAPI 入口 | HSF（暴露给 OpenAPI 网关） | Java | https://code.alibaba-inc.com/alidocs/lippi-doc-solution |
+| lippi-doc-notable | **核心调度**（统一入口方法） | HTTP（接收前端）+ HSF（接收 MCP/OpenAPI） | Java | https://code.alibaba-inc.com/alidocs/lippi-doc-notable |
+| lippi-doc-converter-notable | 文件转换主服务（CSV 链路 + xlsx 调度） | Java + gRPC（调 Rust） | Java | https://code.alibaba-inc.com/alidocs/lippi-doc-converter-notable/ |
+| dimension-rs | xlsx 文件解析与转换 | gRPC（被 converter 调用） | Rust | https://code.alibaba-inc.com/alidocs/dimension-rs/codereview |
+
+### 排查时的日志查看顺序
+
+绝大多数导入问题在 `lippi-doc-converter-notable` 的 SLS 中即可定位。按以下顺序排查：
+
+1. **lippi-doc-converter-notable**（首选）— CSV 链路全程 + xlsx 链路的 Java 侧 + dimension-rs gRPC 调用结果，覆盖 90%+ 的问题
+2. **lippi-doc-notable**（converter 无异常时）— 任务是否正确下发、converter 回调是否正常处理
+3. **入口侧服务**（notable 也无异常时）— we-notable / lippi-doc-notable-mcp / lippi-doc-solution，看请求是否正确到达 notable
+
+### 关键代码路径（按排查频率排序）
+
+**lippi-doc-notable 统一入口（Java）**：
+- 统一方法：`ImportServiceImpl.importFile(FileConvertParam)` → 调用 `FileConvertManager.convertImportFile(param, XLSX_IMPORT_CALLER_ID)`
+  - 代码位置：`lippi-doc-notable-service/.../ImportServiceImpl.java:379`
+- **前端入口（HTTP）**：`ImportController`
+  - `POST /api/import/task`（`ImportController.java:201`）
+  - `POST /api/import/v2/data/task`（`ImportController.java:231`）
+  - `POST /api/import/v2/preview/task`（`ImportController.java:274`）
+- **MCP/OpenAPI 入口（HSF）**：`ImportApiServiceImpl`（`ImportApiServiceImpl.java:285,400`）
+  - `submitPreviewJob(CreateImportTaskRequest)`
+  - `buildAndSubmitImport(BuildAndSubmitImportRequest)`
+  - OpenAPI 链路额外走 `ImportSessionServiceImpl.execute()` → `triggerDataJob()`（`ImportSessionServiceImpl.java:131,346`）
+- 3 个入口全部汇聚到 `importFile()`，再由 `FileConvertManager` 通过 HSF 下发到 `lippi-doc-converter-notable`
+
+**lippi-doc-converter-notable — CSV 链路（Java）**：
+- 消费入口：`ConverterNotableConvertJobConsumer` — 接收任务，调度转换
+- CSV 解析：`Csv2NotableConverter` — CSV → Notable 数据模型转换
+- 写入 Notable：`NotableDataWriter` — 调用 Notable HSF 接口写入数据
+- 错误码定义：`ErrorCodeEnum`（`lippi-doc-converter-notable-model/.../enums/ErrorCodeEnum.java`）— 7xxxx + 8xxxx 系列
+
+**lippi-doc-converter-notable — xlsx 调度（Java）**：
+- gRPC 客户端：调用 dimension-rs 的 gRPC 接口
+- 结果处理：接收 Rust 返回的转换结果，写入 Notable
+
+**dimension-rs — xlsx 解析（Rust）**：
+- gRPC 入口：`ConvertService` — 接收 Java 侧的 gRPC 调用
+- xlsx 解析：`XlsxParser` — 解析 xlsx zip 包内的 XML
+- 错误码定义：`error.rs` — 3xxxx 系列错误码枚举
+
+**Notable 写入（Java，lippi-doc-converter-notable 内）**：
+- HSF 调用：调用 lippi-doc-notable 的写入接口写入 sheet / row / cell
+- 冲突检测：检查同名 sheet 是否已存在
+
+---
+
+## SLS 日志源配置
+
+不同服务的日志分布在不同 SLS project 中，按需查询：
+
+| 服务 | SLS project | logstore | region | 说明 |
+|------|-------------|----------|--------|------|
+| lippi-doc-converter-notable（主） | lippi-doc-converter | master | cn-wulanchabu | **主要查询入口**，包含 Java 侧全部日志（CSV 链路 + xlsx 链路的 Java 部分）+ dimension-rs 的 `GRPC_RUST_LOG`，覆盖 90%+ 问题 |
+| lippi-doc-notable | lippi-doc-notable | master | cn-wulanchabu | 核心调度服务日志。当 converter 侧无报错但导入仍失败时查这里（任务是否下发、回调是否处理） |
+| lippi-doc-notable-mcp | lippi-doc-notable | notable-mcp | cn-wulanchabu | MCP 入口日志（与 notable 共享 project，不同 logstore）。当 MCP 调用方报错但 notable 无日志时查这里 |
+| lippi-doc-solution | lippi-doc-solution | master | cn-wulanchabu | OpenAPI 入口日志。当 OpenAPI 调用方报错但 notable 无日志时查这里 |
+| we-notable（前端服务端） | lippi-doc-notable-frontend | notable-app | cn-hangzhou | 前端服务端日志。前端问题表现为"后端日志 success=Y 但用户看到失败"时查这里 |
+| notable-fc（异步 FC） | lippi-doc-notable-frontend | notable-fc | cn-hangzhou | FC 执行日志（与 we-notable 共享 project，不同 logstore），异步任务排查时查这里 |
+
+**注意**：当前绝大多数导入问题都能在 `lippi-doc-converter / master / cn-wulanchabu` 中定位。只有当 converter 侧日志正常但用户仍报告失败时，才需要查其他 SLS 源。
+
+---
+
+## 操作流程
+
+### 第一步：提取关键信息
+
+从用户消息中提取：
+- `traceId`（必须）— 32 位十六进制字符串，匹配模式如 `traceId[：:]\s*([0-9a-fA-F]{32})`；也可能是 16 字节 hex（不含横杠），注意与 `importId`（UUID 含横杠）区分
+- `docKey`（可选）— 用于辅助定位和备用查询
+- `importId`（可选）— UUID 格式（含 `-`），用于辅助定位
+- 用户描述的报错文案（可选）— 辅助判断前端展示的错误类型
+
+### 第二步：查询 SLS 日志
+
+**首次查询**：使用 `mcp__sls-mcp__query_sls_logs` 工具：
+
+```
+projectName: lippi-doc-converter
+logstoreName: master
+region: cn-wulanchabu
+query: <traceId>
+quickTimeRange: 最近30天
+limit: 100
+order: asc
+```
+
+> 直接用 30 天范围，避免「最近7天」刚好卡在边界导致漏查（实际 SLS 日志保留 >7 天，30 天范围内数据均可查）。**如果返回条数 = limit（100 条），用 `offset` 分页拉取剩余条目**，避免关键日志被截在第二页。
+
+**降级查询**（首次查询返回 0 条结果时，按顺序尝试）：
+
+1. **大小写反转**：traceId 全大写 ↔ 全小写再查一次
+2. **用精确时间范围重试**：如果用户能提供导入发生的大致时间，用 `fromTime`/`toTime`（Unix 秒）精确卡当天窗口重试，避免 `quickTimeRange` 的相对时间计算误差
+3. **用 docKey 查询**：`query: <docKey>`，同 project/logstore/region
+4. **用 importId 查询**：`query: <importId>`，同 project/logstore/region
+5. **查其他 SLS 源**（根据入口类型选择）：
+   - **OpenAPI 入口** → `lippi-doc-solution / master / cn-wulanchabu`
+   - **MCP 入口** → `lippi-doc-notable / notable-mcp / cn-wulanchabu`
+   - **前端入口** → `lippi-doc-notable-frontend / notable-app / cn-hangzhou`
+   - **不确定入口** → 依次查 `lippi-doc-notable / master / cn-wulanchabu` → `lippi-doc-solution / master / cn-wulanchabu`
+6. **以上均无结果**：告知用户"未查到相关日志，请确认：① traceId 是否正确 ② 导入是否超过 30 天 ③ 联系研发确认日志采集是否正常"
+
+### 第三步：分析日志，提取关键字段
+
+**3.1 判断文件类型和处理链路**
+
+从 `ConverterNotableConvertJobConsumer` + `success=N` 的条目提取 `jobType`：
+
+- `jobType` 包含 `XLSX` → **xlsx 链路**，经过 Rust gRPC 处理
+- `jobType` 包含 `CSV` + `PREVIEW` → **CSV 预览链路**，纯 Java 处理
+- `jobType` 包含 `CSV` + `V2` → **CSV 正式导入链路**，纯 Java 处理（写入 Notable 文档）
+
+**如果找不到 `jobType` 字段**，尝试以下 fallback：
+- 搜索日志中是否出现 `XLSX_TO_` / `CSV_TO_` 等关键词
+- 搜索是否有 `GRPC_RUST_LOG` 条目 → 有则为 xlsx 链路
+- 搜索 `csv2notable` 关键词 → 有则为 CSV 链路
+- 以上都无法判断，在报告中注明"无法确定文件类型"并列出所有错误日志
+
+**3.2 xlsx 链路日志分析**
+
+按优先级查找以下条目：
+
+1. **GRPC_RUST_LOG** + `success=N` → 提取 `errMsg`、`errCode`、`cost`、`stage`
+2. **GRPC_RUST_LOG** + `method=` → 提取转换类型（`Xlsx2PreviewData` / `ImportDataV2`）和文件大小（`originFileSize`）
+3. **SERVICE_DETAIL_LOGGER** + `GrpcConvert` → 提取完整 `result` 和 `cost`
+
+`result` 字段是嵌套 JSON，重点关注：
+- `result.success` — 是否成功
+- `result.errCode` — 错误码
+- `result.errMsg` — 错误消息（可能包含 Rust panic 信息）
+- `result.data` — 正常时有转换结果，异常时为空
+
+**3.3 CSV 链路日志分析**
+
+按优先级查找以下条目：
+
+1. **SERVICE_DETAIL_LOGGER** + `ConverterNotableConvertJobConsumer` + `success=N`
+   - ⚠️ **几乎必截断**（`truncated=true`），`Caused by:` 在截断部分
+   - **必须**调用 `mcp__sls-mcp__get_sls_log_detail` 获取完整内容
+   - 参数说明：
+     - `projectName: lippi-doc-converter`
+     - `logstoreName: master`
+     - `region: cn-wulanchabu`
+     - `logTime`: 从 `query_sls_logs` 返回的该条日志的 `__time__` 字段（Unix 时间戳，秒）
+     - `query`: 原 traceId
+   - 完整日志中重点看 `Caused by:` 或顶层 `BusinessException` 消息
+   - ⚠️ **如果 `get_sls_log_detail` 调用失败**（工具报错、无匹配日志等），回退使用已截断的内容，并在报告中注明"无法获取完整堆栈，诊断基于截断日志"
+   - ⚠️ **xlsx 链路同样注意截断**：`GrpcConvert` 的 `result` JSON 较大时也可能截断，若 `result` 字段内容不完整，同样调用 `get_sls_log_detail` 展开
+
+2. **SERVICE_DETAIL_LOGGER** + `category=convertAndInsertData`（正式导入阶段特有）→ 直接展示写入 Notable 时的错误
+
+3. `errorCode` 字段 — 在 `ConverterNotableConvertJobConsumer` 的日志中，与 `success=N` 同一条目
+
+**3.4 多日志条目的决策规则**
+
+一个 traceId 可能对应多条日志，按以下规则处理：
+
+- **PREVIEW 和 V2 阶段的错误分开诊断**，分别输出诊断结论。两者是独立的处理阶段
+- **同一阶段多条错误时**，优先取时间最早的错误（根因通常最早出现，后续错误可能是级联影响）
+- **如果有 `ConverterNotableConvertJobConsumer` + `success=N` 的日志**，优先以它为准（包含完整异常链和错误码）
+- **如果同时有 Rust 和 Java 报错**，Rust 错误通常是根因（Java 侧只是接收 gRPC 错误后包装抛出）
+
+**3.5 日志字段缺失的 fallback**
+
+| 缺失字段 | fallback 策略 |
+|----------|---------------|
+| `jobType` | 搜索日志全文中的 `XLSX_TO_` / `CSV_TO_` / `GRPC_RUST_LOG` / `csv2notable` 关键词 |
+| `errCode` / `errorCode` | 搜索 `error` / `exception` / `fail` 关键词，从异常堆栈中推断 |
+| `cost` | 如果日志中有 `startTime` 和 `endTime`，手动计算差值 |
+| `originFileSize` | 尝试从日志中的 OSS URL 或 `fileUrl` 字段推断文件名和大小 |
+| `success` | 如果整条日志没有任何错误信息且没有异常堆栈，视为成功 |
+
+### 第四步：根据错误码/错误信息做根因匹配
+
+#### xlsx 链路（errCode 为 3xxxx，来自 Rust）
+
+| 错误码 | 枚举名 | errMsg 特征 | 根因 | 建议话术 |
+|--------|--------|-------------|------|----------|
+| 30019 | `ReadAttributeError` | `read attribute 'r' error, value is '0'` | xlsx 文件中存在行号为 0 的非法行元素（`<row r="0">`），不符合 OOXML 规范。**dimension-rs 已做容错（`row_num.max(1)`），commit `25b313b`（2026-05-19）**，需确认生产版本是否包含该修复 | **文件格式异常**：您的文件中存在非标准行号记录，可能是由特定软件导出时生成的格式异常。建议在 Excel 或 WPS 中打开该文件后另存为新 xlsx，再重新导入。 |
+| 30019 | `ReadAttributeError` | 其他 `ReadAttributeError` | xlsx XML 中某属性值无法解析（行/列号格式异常） | **文件格式异常**：文件内部存在无法识别的格式，建议重新用 Excel/WPS 打开后另存再导入。 |
+| 30014 | `XMLDataIllegalError` | `XMLDataIllegalError` | xlsx 内部 XML 数据不合法，文件可能已损坏 | **文件已损坏**：文件内部结构异常，无法完成导入。请检查文件是否完整，或尝试用 Excel/WPS 修复后重新导入。 |
+| 30001 | `ZipError` | `ZipError` | zip 解压失败，文件可能损坏或未完整上传 | **文件损坏或上传不完整**：文件无法正常读取，可能在上传过程中出现了问题。请重新上传，或检查原始文件是否可以正常打开。 |
+| 30002 | `FileEncryptedError` | `FileEncryptedError` | 文件有密码保护 | **文件被加密**：您的文件设置了密码保护，系统无法读取。请先在 Excel/WPS 中移除密码保护后再导入。 |
+| 30013 | `FileDataEmptyError` | `FileDataEmptyError` | 文件为空或读取不到有效数据 | **文件为空**：文件中未检测到有效数据，请确认文件内容后重试。 |
+| 30025 | `FileTypeError` | `FileTypeError` | 文件类型不匹配（非标准 xlsx） | **文件格式不支持**：系统仅支持标准 xlsx 格式。请确认文件后缀与实际格式一致，或在 Excel/WPS 中另存为 xlsx 后重新导入。 |
+| 30026 | `ConvertError` | `ConvertError` | 转换过程中出现业务错误 | **转换失败**：文件在处理过程中出现错误，请稍后重试。若持续失败请联系技术支持。 |
+| 30004/30005 | `XmlError` / `XmlDeError` | `XmlError` / `XmlDeError` | XML 解析/反序列化错误，文件结构异常 | **文件结构异常**：文件内部格式存在问题，建议在 Excel/WPS 中重新打开并另存后导入。 |
+| 30007 | `XMLReadError` | `XMLReadError` | XML 读取错误，xlsx 内 XML 无法正常读取（文件可能损坏或格式异常） | **文件读取失败**：文件内部 XML 无法正常读取，可能是文件损坏或格式异常。建议重新上传。 |
+| 30008 | `NumError` | `NumError` (`parse int error`) | 数值解析错误，xlsx 中某单元格数值无法解析（可能是异常大的数字或非数字内容） | **数据格式异常**：文件中存在无法识别的数值格式。建议检查文件中的数据，确保数值格式正确后重新导入。 |
+| 30003 | `IoError` | `IoError` | 文件读写 IO 异常 | **IO 异常**：系统在读写文件时出现错误。请稍后重试。 |
+| 30006 | `Utf8Error` | `Utf8Error` | xlsx 内部字符串 UTF-8 编码异常 | **编码异常**：文件内部字符编码异常，建议在 Excel/WPS 中打开后另存再导入。 |
+| 35001 | `XlsxFileIsIllegal` (code=1) | `field meta missing` | xlsx 中 sheet 缺少字段元数据 | **文件格式异常**：文件中缺少必要的字段定义信息，建议在 Excel/WPS 中重新编辑并另存后导入。 |
+| 35002 | `XlsxFileIsIllegal` (code=2) | `no sheet in xlsx` | xlsx 文件中没有 sheet | **文件为空**：文件中未找到有效的工作表，请确认文件包含数据后重新导入。 |
+| 10005 | (gRPC 层硬编码) | `Import download xlsx file error` | 下载 xlsx 文件失败（OSS 下载异常）。**需结合时间线判断**：① 如果任务创建与执行之间有**超过数十分钟的延迟**（如 19:47 创建、22:01 才执行），叠加 OSS HTTP 403，根因是 **MetaQ 消费阻塞导致 OSS 签名 URL 过期**；② 如果几乎无延迟即失败，根因是 OSS 本身不可达或文件不存在 | **下载失败**：系统在下载文件时遇到了问题。请稍后重试，若持续失败请联系技术支持。（若为 MetaQ 阻塞导致的 URL 过期，重新上传即可，无需特殊处理） |
+
+#### CSV 链路（errorCode 为 7xxxx，来自 Java）
+
+| 错误码 | 枚举名 | Caused by 特征 | 根因 | 建议话术 |
+|--------|--------|----------------|------|----------|
+| 70000037 | `CSV_2_NOTABLE_V2_CONVERT_FAILED` | `CSV cell contains binary data (N+ control characters detected)` | CSV 文件中某个单元格包含大量二进制控制字符（非可打印文本），文件内容非法，可能是将非文本文件改后缀为 csv，或导出时编码异常 | **文件内容非法**：您的 CSV 文件中存在无法识别的非文本数据。建议用本地 Excel 客户端打开该 CSV 文件，另存为标准 xlsx 格式后重新导入。 |
+| 70000037 | `CSV_2_NOTABLE_V2_CONVERT_FAILED` | 其他 `BusinessException: csv2notable` | CSV 正式导入阶段转换业务异常（具体原因看堆栈） | **文件处理失败**：CSV 文件解析时出现错误。建议用本地 Excel 客户端打开该文件，另存为标准 xlsx 格式后重新导入。 |
+| 70000035 | `CSV_2_NOTABLE_CONVERT_FAILED` | — | CSV 预览阶段转换失败（旧链路） | **文件处理失败**：CSV 文件解析时出现错误。建议用 Excel 打开后另存为标准格式重新导入。 |
+| 70000036 | `XLSX_2_NOTABLE_V2_CONVERT_FAILED` | — | xlsx V2 正式导入阶段转换失败（非 Rust 侧问题，Java 侧处理异常） | **处理失败**：xlsx 文件在写入 Notable 阶段遇到问题，请稍后重试。若持续失败请联系技术支持。 |
+| 70000016 | `HSF_SERVER_BIZ_FAILED` | `sheet 'XXX' already exists` | 正式导入阶段，在目标 Notable 文档中创建同名 sheet 时发现已存在（上次导入失败残留，或用户手动创建过同名 sheet） | **表格名称冲突**：您的文档中已存在名为「XXX」的表格，导入时无法重复创建。请删除或重命名目标文档中已有的「XXX」表格后，重新发起导入。（该表格可能是上次导入失败留下的残留，可直接删除后重试。） |
+| 70000016 | `HSF_SERVER_BIZ_FAILED` | `fc invoke error` | 调用 Notable `createNewSheet` HSF 接口时，Notable 内部 FC（Function Compute）执行失败（如超时、代码异常等）。**需进一步排查 Notable 侧日志**确定 FC 失败的具体原因 | **服务异常**：导入过程中系统服务出现了临时错误。建议稍后重试，若持续失败请联系技术支持并提供 traceId。 |
+| 70000017 | `HSF_SERVER_TIMEOUT` | `HSF timeout` / `timeout` | 调用下游 Notable HSF 接口超时（写入数据耗时过长或下游响应慢） | **服务超时**：写入数据时服务端响应超时。请稍后重试，若文件较大建议拆分后分批导入。 |
+| 70000005 | `HSF_REQUEST_FAILED` | `HSF request failed` | 调用下游 HSF 服务失败（网络断开、服务不可用等） | **服务异常**：系统服务暂时不可用。请稍后重试，若持续失败请联系技术支持。 |
+| 70000026 | `DOWNLOAD_FILE_FAILED` | `download failed` | 从 OSS 下载文件失败（OSS 访问异常或文件链接过期） | **文件下载失败**：系统无法获取您的文件。请重新上传后重试。 |
+| 80000005 | `OVER_SINGLE_IMPORT_ROW_LIMIT` | `over single import row limit` | 单次导入行数超过系统上限 | **行数超限**：您的文件行数超过了系统支持的单次导入上限。建议拆分文件后分批导入。 |
+| 任意 (Java) | `MalformedInputException` / `UnmappableCharacterException` | `MalformedInputException` / `CharacterCodingException` | CSV 文件编码不是 UTF-8（可能是 GBK/GB2312），Java NIO 读取时字符解码失败 | **文件编码不支持**：您的 CSV 文件编码格式不被支持（系统仅支持 UTF-8）。建议用 Excel 打开后另存为 UTF-8 编码的 CSV，或直接另存为 xlsx 格式后重新导入。 |
+| 70000000 | `SERVER_ERROR` | — | 系统内部未知错误 | **系统异常**：导入过程中遇到了系统内部错误。请稍后重试，若持续失败请联系技术支持并提供 traceId。 |
+
+#### 跨服务基础设施错误（notable → reformer → converter → MQ 链路失败）
+
+这类错误**不在 3xxxx/7xxxx 业务错误码体系内**，而是 HSF / MQ 基础设施层失败逐层包装上抛，最终在 notable 侧表现为裸 HTTP 500（前端文案统一为「导入失败，请稍后重试」）。特征是 notable error 日志里出现 `[FileConvertApiService#convert] - The HSF service invocation failed, errorCode => 10006`，需顺 traceId 下钻到 converter 才能看到真实根因。
+
+| 错误码链 | 根因日志特征（converter/reformer） | 根因 | 建议话术 |
+|----------|-----------------------------------|------|----------|
+| HTTP 500 → HSF `10006` → converter `60000000` → MQ `CODE: 13` | `category=MetaqProducer_send, ... errorMsg=CODE: 13 DESC: the message body size over max value, MAX: 262144`（`NotableTaskSender.sendTask` → `Validators.checkMessage`） | **导入任务 MQ 消息体超过 RocketMQ 单条上限 256KB（262144 bytes）**。常见于**宽表 + 增量导入**：jobType=90（notable_v2）的 convert job 把完整 `importSheetInfo`（含 `colToFieldMap` 列映射）塞进 `srcAddr.headers` 撑爆；jobType=89（preview）消息体小所以预览能成功 | **任务过大**：您的文件没有问题（预览已成功），失败原因是这次导入的**任务配置过大，超过系统单条任务大小限制**，常见于列数较多的增量导入。建议：① 减少本次映射的列数、分批导入；② 或改用「新建表格」方式（非增量）导入；③ 仍失败请联系技术支持（需服务端优化任务下发）。 |
+| HTTP 500 → HSF `10006` → converter `60000000` | converter/reformer 侧 `HSF_ERROR` 但无 `CODE: 13`（如 NPE、下游超时、依赖不可用等） | converter 创建/触发 convert job 时内部异常（非消息体超限），具体看 converter error 日志堆栈 | **系统异常**：导入过程中系统出现临时错误。请稍后重试，若持续失败请联系技术支持并提供 traceId：`<traceId>`。 |
+
+> ⚠️ **关键排查动作**：当 notable error 日志只看到 `HSF service invocation failed, errorCode => 10006` 时，**必须**用同一条 V2 后端 traceId 去 `lippi-doc-converter / master` 下钻（重点看 `level=ERROR` 的 `MetaqProducer`、`HSF_ERROR`、`JobApiManager` 条目），否则只能定位到"HSF 调用失败"这一层、看不到真实根因。
+
+#### 通用兜底
+
+| 场景 | 建议话术 |
+|------|----------|
+| 错误码未在上表中 | **系统异常**：导入过程中遇到了系统错误（错误码：`<errCode>`），已记录日志。请稍后重试，若持续失败请联系技术支持并提供 traceId：`<traceId>`。 |
+| 完全没有错误日志但用户报告失败 | **状态不确定**：系统日志中未找到该次导入的错误记录。可能是前端展示异常或回调丢失，请联系技术支持排查。 |
+| 日志显示 success=Y 但用户报告失败 | **疑似前端/回调问题**：后端日志显示导入已成功，但前端可能未及时刷新或回调消息丢失。建议用户刷新页面检查数据是否已导入，若仍无数据请联系技术支持。 |
+
+### 第五步：补充上下文信息
+
+从日志中额外提取：
+
+- **文件类型**：从 `jobType` 字段判断
+  - `XLSX_TO_*` → xlsx
+  - `CSV_TO_*_PREVIEW` → CSV 预览
+  - `CSV_TO_*_V2` → CSV 正式导入
+- **所处阶段**：`PREVIEW` = 预览阶段（文件解析），`V2` = 正式导入阶段（写入 Notable）。同一次操作先跑 PREVIEW 再跑 V2，两个阶段的错误要分开诊断
+- **文件大小**：
+  - xlsx 链路从 `GRPC_RUST_LOG` 的 `originFileSize` 取
+    - **注意**：底层变量值是 **bytes**（Rust `xlsx.len()` 返回字节数），但 Rust 日志打印时已除以 1024.0 并附 `kb` 后缀（如 `originFileSize=15.00kb` ≈ 15360 bytes）。报告中需区分：从日志字符串直接读取→已是 KB；从变量/字段取值→是 bytes
+    - 转换参考：`102400 bytes = 100 KB`，`20971520 bytes = 20 MB`
+    - Java 侧 `fileSize` 字段也是 bytes（来源 OSS `SimplifiedObjectMeta.getSize()`）
+  - CSV 链路日志中通常没有文件大小，可从 OSS URL 中的文件名推断
+  - **大文件阈值**：xlsx > 20MB（20971520 bytes）时注意维度限制；dimension-rs `FileSizeLimit` 默认限制 200MB（`209715200 bytes`），Java 侧 `maxResourceFileTransferSize` 限制 1GB
+- **转换耗时**：`cost` 字段（毫秒）
+  - 耗时 < 200ms 就失败 → 大概率是文件本身问题（格式错误、加密等），未到实际处理阶段
+  - 耗时 > 60s → 大概率是超时问题或文件过大
+- **处理阶段**（xlsx 链路 `stage` 字段）：
+  - `DownloadXlsx` — 下载文件阶段，失败多为网络/OSS 问题
+  - `Xlsx2PreviewData` — 预览数据转换阶段，失败多为文件内容问题
+  - `ImportDataV2` — 正式导入阶段，失败多为文件内容或 Notable 写入问题
+- **文件名编码**：如果文件名包含中文或特殊字符，注意日志中可能出现 URL 编码（`%E4%BD%A0%E5%A5%BD`），报告中需解码展示
+
+### 第六步：检查后续是否成功
+
+在输出诊断报告前，额外检查：
+
+1. 用 `docKey` 或 `importId` 查询同一时间窗口内是否有**后续成功的导入记录**（`success=Y`）
+2. 如果找到后续成功记录，在报告中注明："该次导入失败后，用户已于 `<时间>` 重新导入成功。本次失败可能为偶发问题。"
+3. 如果没有后续成功记录，正常输出诊断报告
+4. **如果用户只提供了 traceId（无 docKey 和 importId）**，跳过本步骤，报告中注明"无法确认后续状态（缺少 docKey 或 importId）"
+
+### 第七步：输出诊断报告
+
+输出格式：
+
+```
+## 诊断结果
+
+**根因**：<一句话描述根本原因>
+
+**错误详情**：
+- 错误码：<errCode>
+- 错误信息：<errMsg>
+- 文件类型：<xlsx / CSV>
+- 处理阶段：<PREVIEW 预览 / V2 正式导入>
+- 处理步骤：<stage，如 DownloadXlsx / Xlsx2PreviewData>
+- 文件大小：<可读格式，如 2.3 MB>
+- 转换耗时：<cost>ms
+- traceId：<traceId>
+
+**建议话术**（给用户）：
+<话术正文>
+
+**技术说明**（给研发）：
+- 错误来源：<Rust gRPC / Java 消费端 / Notable HSF 调用>
+- 关键代码路径：<如 ConverterNotableConvertJobConsumer → Csv2NotableConverter>
+- 异常堆栈摘要：<关键几行>
+- 是否有已知修复：<如 row_num.max(1) 修复，需确认生产版本>
+- 是否需要人工介入：<是/否，以及建议的修复方向>
+
+**后续状态**：<是否有后续成功记录 / 无>
+
+**进一步排查**（仅 OpenAPI 链路）：
+如果本次导入来自 OpenAPI 入口（通过 lippi-doc-solution），推荐使用 `import-openapi-e2e-troubleshooter` 技能做端到端排查：
+https://open.aone.alibaba-inc.com/console/platform/aitable-plugin/skill/import-openapi-e2e-troubleshooter
+该技能覆盖 OpenAPI 完整调用链（lippi-doc-solution → lippi-doc-notable → converter），可定位本技能无法覆盖的网关层和鉴权层问题。
+```
+
+---
+
+## 注意事项
+
+- **traceId 大小写不一致**：在不同服务的日志里字段名可能是 `traceId` 或 `traceid`，查询时用关键词搜索（`query: <traceId>`），不要用索引查询（`traceId:xxx`）
+- **CSV 链路没有 GRPC_RUST_LOG 条目**：这是正常现象，不是日志丢失
+- **截断日志必须展开**：`ConverterNotableConvertJobConsumer` 的错误日志几乎都会截断，`Caused by:` 在截断部分，必须调 `get_sls_log_detail` 才能拿到真正的根因
+- **`row is 0` 错误**：当 xlsx errMsg 包含 `row is 0` 时，技术说明中需指出：dimension-rs 仓库已在 commit `25b313b`（2026-05-19，作者：李普阳 `puyang.lpy`）中做容错，将 `row_num == 0` 时的 `ReadAttributeError` 抛出改为 `row_num.max(1)` 静默修正为行号 1（8 处，分在 `dimension/src/check_point.rs` 和 `dimension/src/lib.rs`），对应上线 tag `tags/20260519141504843_lippi-doc-notable-rust-grpc`。**注意**：`dimension/src/lib.rs:759` 的 `extract_row_number_from_attrs` 函数未做此容错（旧链路），调用方通过 `row_num < start_row` 判断跳过，不影响正常流程
+- **大文件 OOM**：xlsx > 20MB 失败时，额外检查日志中是否有 OOM / `out of memory` / `allocation failed` 相关报错
+- **CSV 编码问题**：CSV 文件如果是 GBK/GB2312 编码，Java 侧可能报 `MalformedInputException`，建议用户转为 UTF-8
+- **SLS 日志保留期**：SLS 日志默认保留 90 天，超过 90 天的日志无法查询
+- **OpenAPI 链路推荐进阶排查**：如果诊断出导入来自 OpenAPI 入口（lippi-doc-solution），在报告末尾推荐使用 [`import-openapi-e2e-troubleshooter`](https://open.aone.alibaba-inc.com/console/platform/aitable-plugin/skill/import-openapi-e2e-troubleshooter) 技能，该技能覆盖 OpenAPI 完整调用链（网关 → 鉴权 → 业务），可定位本技能无法覆盖的上游问题
+- **PREVIEW 成功但 V2 未触发**：如果日志中只看到 `XLSX_TO_NOTABLE_PREVIEW`（jobType=89）且 `success=Y`，但没有 `XLSX_TO_NOTABLE_V2`（jobType=90）日志，说明预览阶段完成但正式导入阶段从未被触发。常见原因：① 用户在前端看到预览后未点击"确认导入" ② Notable 处理 PREVIEW 回调时出错，导致 V2 未下发 ③ **MetaQ 消费者阻塞**（某台机器消费进程卡住，V2 job 堆积在队列中未被消费）。此时需到 **lippi-doc-notable** SLS 查 `POST /api/import/v2/preview/task` 和 `GET /api/import/v2/task/<taskId>` 的 HTTP 日志，确认任务状态流转
+- **MetaQ 阻塞特征**：当日志中同时出现以下模式时，高度疑似 MetaQ 消费者阻塞：① `createConvertJob` 与 `ConverterNotableConvertJobConsumer` 之间延迟超过数十分钟 ② PREVIEW 成功但 V2 始终未到 ③ 同一时间段多个不同 traceId 均表现为"PREVIEW 正常、V2 缺失"或"大量延迟消费"。这种场景的错误码可能是 10005（OSS URL 过期）或无错误码（纯粹未消费）
+- **PREVIEW 与 V2 是两个独立的后端 traceId**：前端埋点（`notable-app`）的 `import_file_request_params` / `import_file_fail` 会**复用预览阶段的 traceId**，但正式导入请求到后端会生成**全新的 EagleEye traceId**。因此用前端 traceId 在 notable/converter 只能查到预览（jobType=89、全 success=Y），查不到真正失败的 V2。**正确做法**：拿 docId + `"import/v2/data/task"` 在 `lippi-doc-notable / master` 按时间窗扫，找到 `N|500`（或 `success=false`）那条 HTTP-DIGEST，其 traceId 才是 V2 的真实 traceId，再用它下钻 converter
+- **HSF 10006 必须下钻 converter**：notable error 日志的 `HSF service invocation failed, errorCode => 10006` 只是"调用下游失败"的外层包装，真实根因（如 MQ `CODE: 13` 消息体超 256KB、converter `60000000`）只在 `lippi-doc-converter / master` 的 `level=ERROR` 日志里。详见上文「跨服务基础设施错误」表
+
+---
+
+## 示例：完整诊断流程
+
+### 示例 1：xlsx 链路 — 行号异常
+
+**用户输入**：
+```
+导入失败：导入失败，请稍后重试
+docKey：abc123
+traceId：0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d
+```
+
+**第一步**：提取 traceId = `0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d`
+
+**第二步**：查询 SLS
+```
+projectName: lippi-doc-converter
+logstoreName: master
+region: cn-wulanchabu
+query: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d
+quickTimeRange: 最近30天
+limit: 100
+order: asc
+```
+
+**第三步**：返回 5 条日志，找到：
+- `ConverterNotableConvertJobConsumer` + `success=N` → `jobType=XLSX_TO_PREVIEW` → xlsx 链路
+- `GRPC_RUST_LOG` + `success=N` → `errCode=30019`, `errMsg=read attribute 'r' error, value is '0'`, `stage=Xlsx2PreviewData`, `cost=45`
+
+**第四步**：匹配错误码 → 30019 + `read attribute 'r' error, value is '0'` → 行号为 0 的非法行
+
+**第五步**：
+- 文件大小：`originFileSize=100.00kb`（日志已除以 1024 显示，实际约 100 KB）
+- 耗时：45ms（< 200ms，说明在解析阶段就失败了，符合文件格式问题）
+
+**第七步**：输出报告
+```
+## 诊断结果
+
+**根因**：xlsx 文件中存在行号为 0 的非法行元素（`<row r="0">`），不符合 OOXML 规范
+
+**错误详情**：
+- 错误码：30019
+- 错误信息：read attribute 'r' error, value is '0'
+- 文件类型：xlsx
+- 处理阶段：PREVIEW 预览
+- 处理步骤：Xlsx2PreviewData
+- 文件大小：100 KB
+- 转换耗时：45ms
+- traceId：0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d
+
+**建议话术**（给用户）：
+**文件格式异常**：您的文件中存在非标准行号记录，可能是由特定软件导出时生成的格式异常。
+建议在 Excel 或 WPS 中打开该文件后另存为新 xlsx，再重新导入。
+
+**技术说明**（给研发）：
+- 错误来源：Rust gRPC（dimension-rs）
+- 关键代码路径：ConvertService → XlsxParser → row 解析
+- errMsg 包含 `value is '0'`，说明 xlsx XML 中存在 `<row r="0">` 元素
+- 已有容错修复 `row_num.max(1)`，需确认生产版本是否已包含
+- 无需人工介入，用户另存文件即可解决
+
+**后续状态**：未查到后续成功记录
+```
+
+### 示例 2：CSV 链路 — 日志截断需展开
+
+**用户输入**：
+```
+导入失败
+traceId：1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
+```
+
+**第二步**：查询 SLS，返回 3 条日志
+
+**第三步**：
+- 找到 `ConverterNotableConvertJobConsumer` + `success=N` → `jobType=CSV_TO_NOTABLE_V2` → CSV 正式导入链路
+- 该条日志 `truncated=true`，只看到 `BusinessException: csv2notable`，`Caused by:` 被截断
+- 调用 `get_sls_log_detail`：
+  ```
+  projectName: lippi-doc-converter
+  logstoreName: master
+  region: cn-wulanchabu
+  logTime: 1718438400  （从该条日志的 __time__ 字段获取）
+  query: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
+  ```
+- 完整日志中 `Caused by: java.lang.IllegalArgumentException: sheet '销售数据' already exists`
+
+**第四步**：匹配 → errorCode 70000016 + `sheet 'XXX' already exists` → 同名 sheet 冲突
+
+**第五步**：文件类型=CSV，阶段=V2，无文件大小日志
+
+**第六步**：未查到后续成功记录
+
+**第七步**：
+```
+## 诊断结果
+
+**根因**：CSV 正式导入阶段，目标 Notable 文档中已存在名为「销售数据」的 sheet，创建同名 sheet 时发生冲突
+
+**错误详情**：
+- 错误码：70000016（HSF_SERVER_BIZ_FAILED）
+- 错误信息：sheet '销售数据' already exists
+- 文件类型：CSV
+- 处理阶段：V2 正式导入
+- 转换耗时：—（无 cost 记录）
+
+**建议话术**（给用户）：
+**表格名称冲突**：您的文档中已存在名为「销售数据」的表格，导入时无法重复创建。
+请删除或重命名目标文档中已有的「销售数据」表格后，重新发起导入。
+
+**技术说明**（给研发）：
+- 错误来源：Java 消费端（ConverterNotableConvertJobConsumer）
+- 关键代码路径：NotableSheetApiServiceImpl.createSheet → HSF sheetApiService.createNewSheet
+- 堆栈：BusinessException from HSF_SERVER_BIZ_FAILED
+- 是否需要人工介入：否，用户清理同名 sheet 即可解决
+```