dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-aitable/references/aitable/aitable-datasource.md

@@ -0,0 +1,272 @@
+# datasource — 数据源同步管理
+
+将外部数据源（当前仅支持 OA 审批）同步到 AI 表格。完整链路：list-sources → (OA) 选择模板 → get-fields → create → sync-status → sync / update / get-config。
+
+## 命令一览
+
+| 命令 | 用途 | 读/写 |
+|------|------|-------|
+| `+datasource-list-sources` | 列出可用数据源条目，获取 processCode/name/iconUrl/url | 读 |
+| `+datasource-get-fields` | 获取可同步字段列表，用于决定 field-ids | 读 |
+| `+datasource-create` | 创建数据源表并触发首次全量同步 | 写 |
+| `+datasource-update` | 更新已有数据源表的同步配置 | 写 |
+| `+datasource-sync` | 手动触发一次同步（最多 5 张表） | 写 |
+| `+datasource-sync-status` | 查询同步任务状态（RUNNING/FINISHED/FAILED） | 读 |
+| `+datasource-get-config` | 获取数据源表当前同步配置 | 读 |
+
+## 典型工作流
+
+```
+Step 0    列出可用来源         +datasource-list-sources --base-id <B> --datasource-type OA
+                              → 返回 approvals 数组（通常含多个审批模板）
+
+Step 0.5  (OA 审批) 选择模板  list-sources 返回的 approvals 数组通常含多个审批模板，需确定目标：
+                              - 用户已指定名称（如"采购申请"）→ 按 name 精确/模糊匹配
+                                · 唯一命中 → 提取该条的 processCode/name/iconUrl/url，继续
+                                · 多候选 → 列出匹配项让用户消歧
+                                · 零命中 → 停止，提示用户确认名称或从完整列表选择
+                              - 用户未指定 → 列出候选模板清单（name + processCode），等用户选择
+                              - 禁止：未匹配直接选第一项、或凭记忆猜 processCode
+                              注：此步骤针对 OA 审批数据源（多模板场景）；其他数据源类型的
+                              list-sources 返回结构可能不同，按实际 result 解析即可，
+                              不一定需要选择步骤。
+
+Step 1    (可选) 获取可同步字段  +datasource-get-fields --base-id <B> --datasource-type OA --source-config '<JSON>'
+                              → 决定需要同步哪些字段，得到 field-ids
+
+Step 2    创建数据源           +datasource-create --base-id <B> --datasource-type OA --source-config '<JSON>'
+                              → sourceConfig 中的 processCode/name/iconUrl/url 来自 Step 0.5 选中的模板
+                              → 返回 tableId + taskId
+
+Step 3    查询同步结果         +datasource-sync-status --base-id <B> --table-id <T> --task-ids <TASK_ID>
+                              → FINISHED=完成，FAILED=看 errorCode 排查，RUNNING=轮询
+
+Step 4    (后续) 手动触发同步   +datasource-sync --base-id <B> --table-ids <T1>,<T2>
+                              → 返回新 taskId，再用 sync-status 查结果
+
+Step 5    (后续) 更新配置       +datasource-update --base-id <B> --table-id <T> --source-config '<JSON>' --auto
+                              → 更新后自动触发一次同步
+
+查看当前配置                  +datasource-get-config --base-id <B> --table-id <T>
+```
+
+## sourceConfig 字段协议
+
+以下字段协议仅适用于 OA 审批数据源（datasourceType=OA），其他数据源类型待后续开放。
+
+### 须从 list-sources 原样透传（必填）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| processCode | String | OA 审批流程编码 |
+| name | String | 展示名称 |
+| iconUrl | String | 图标 URL |
+| url | String | 跳转链接 |
+
+### 调用方自行设置
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| dataType | String | 是 | 数据范围类型：`time_range` / `start_time` / `recent_time` |
+| recentDays | String | 条件 | dataType=recent_time 时有效，取值 `7d`/`30d`/`1y`，默认 `30d` |
+| startDate | String | 条件 | dataType=time_range 或 start_time 时有效，`yyyy-MM-dd`，默认 30 天前 |
+| endDate | String | 条件 | dataType=time_range 时有效，`yyyy-MM-dd`，默认当天 |
+| keepRemovedFields | Boolean | 否 | 是否保留已删除字段，默认 false |
+| splitParentTableField | Boolean | 否 | 是否拆分父表字段 |
+
+> list-sources 返回的 keepRemovedFields / splitParentTableField / enableDataSyncOaDetailList 不要透传，由调用方按需设置。
+
+### 三种 dataType 最小示例
+
+```json
+// recent_time — 最近一段时间
+{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}
+
+// time_range — 指定起止日期
+{"processCode":"PROC-xxxx","name":"采购申请","dataType":"time_range","startDate":"2025-01-01","endDate":"2025-12-31","iconUrl":"...","url":"..."}
+
+// start_time — 从某日期至今
+{"processCode":"PROC-xxxx","name":"采购申请","dataType":"start_time","startDate":"2025-06-01","iconUrl":"...","url":"..."}
+```
+
+## autoSyncSetting 频率配置
+
+仅在 `--auto=true` 时生效。不传时使用下游默认自动同步策略。
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| syncType | 是 | `hourly`（按小时间隔）/ `scheduled`（定时触发） |
+| hourlyInterval | hourly 时 | 正整数，小时间隔 |
+| scheduleType | scheduled 时 | `daily` / `weekly` / `monthly` |
+| timeValue | scheduled 时 | `HH:mm` 触发时间 |
+| selectedMonthDays | monthly 时必填 | 每月几号触发，1-31 |
+| selectedWeekdays | weekly 时必填 | 每周哪几天触发，1=周一…7=周日 |
+| skipNonWorkingDay | 否 | 是否跳过非工作日，默认 false |
+
+示例：`{"syncType":"scheduled","scheduleType":"daily","timeValue":"09:00"}`
+
+## 命令详情
+
+### +datasource-list-sources — 列出可用数据源条目
+
+```bash
+dws aitable +datasource-list-sources --base-id BASE_ID --datasource-type OA --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 目标 Base ID |
+| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
+
+返回每条条目包含 `result`（下游原始 JSON 字符串）和 `sourceType`（OA 审批对应 2）。OA 审批场景下 result 为 approvals 数组：
+
+```json
+{
+  "approvals": [
+    {
+      "processCode": "PROC-xxxx",
+      "name": "采购申请",
+      "iconUrl": "https://...",
+      "url": "https://...",
+      "keepRemovedFields": false,
+      "splitParentTableField": false,
+      "enableDataSyncOaDetailList": false
+    }
+  ]
+}
+```
+
+调用方应自行解析 result，提取目标模板字段后构造 sourceConfig。
+
+### +datasource-get-fields — 获取可同步字段列表
+
+```bash
+dws aitable +datasource-get-fields --base-id BASE_ID --datasource-type OA \
+  --source-config '{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
+  --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 目标 Base ID |
+| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
+| `--source-config` | 是 | 源配置 JSON 字符串，结构同 create 的 --source-config |
+
+返回字段列表（字段 ID、名称、类型等），用于在 create/update 中指定 `--field-ids`。
+
+### +datasource-create — 创建数据源表
+
+```bash
+dws aitable +datasource-create --base-id BASE_ID --datasource-type OA \
+  --source-config '{"processCode":"PROC-xxxx","name":"采购申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
+  --format json
+
+# 开启自动同步 + 自定义频率
+dws aitable +datasource-create --base-id BASE_ID --datasource-type OA \
+  --source-config '...' --auto \
+  --auto-sync-setting '{"syncType":"scheduled","scheduleType":"daily","timeValue":"09:00"}' \
+  --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 目标 Base ID |
+| `--datasource-type` | 是 | 数据源类型，当前仅支持 `OA` |
+| `--source-config` | 是 | 源配置 JSON 字符串（见上方字段协议） |
+| `--auto` | 否 | 是否开启自动同步，默认 false；无论是否传入，CLI 都会把该字段下发给下游 |
+| `--auto-sync-setting` | 否 | 自动同步频率配置 JSON 字符串，仅 --auto=true 时生效 |
+| `--field-ids` | 否 | 需要同步的字段 ID 列表，不传时同步全部字段 |
+
+返回新建数据源表 tableId 和同步任务 taskId。创建后自动触发一次全量同步，需用 `+datasource-sync-status` 查最终结果。
+
+### +datasource-update — 更新数据源配置
+
+```bash
+# 仅开启自动同步
+dws aitable +datasource-update --base-id BASE_ID --table-id TABLE_ID --auto --format json
+
+# 更新源配置
+dws aitable +datasource-update --base-id BASE_ID --table-id TABLE_ID \
+  --source-config '{"processCode":"PROC-yyyy","name":"出差申请","dataType":"recent_time","recentDays":"30d","iconUrl":"...","url":"..."}' \
+  --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 目标 Base ID |
+| `--table-id` | 是 | 已有数据源表 ID（sync=true） |
+| `--source-config` | 否 | 新的源配置 JSON 字符串，不传时保持原配置；传入时整体覆盖 |
+| `--auto` | 否 | 是否开启自动同步，不传时保持原设置 |
+| `--auto-sync-setting` | 否 | 自动同步频率配置 JSON 字符串，仅 --auto=true 时生效；不传时保持原频率配置 |
+| `--field-ids` | 否 | 需要同步的字段 ID 列表，不传时保持现有字段配置 |
+
+更新后自动触发一次全量同步，返回新 taskId。
+
+### +datasource-sync — 手动触发同步
+
+```bash
+dws aitable +datasource-sync --base-id BASE_ID --table-ids TBL1,TBL2 --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 目标 Base ID |
+| `--table-ids` | 是 | 待同步的数据源表 ID 列表（sync=true），1-5 个 |
+
+返回结果包含文档链接，可打开查看同步进度。每张表独立提交，部分失败不影响其他表。
+
+### +datasource-sync-status — 按任务 ID 查询同步状态
+
+```bash
+dws aitable +datasource-sync-status --base-id BASE_ID --table-id TABLE_ID --task-ids TASK1,TASK2 --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 目标 Base ID |
+| `--table-id` | 是 | 数据源表 ID（sync=true） |
+| `--task-ids` | 是 | 同步任务 ID 列表（由 create/update/sync 返回），1-5 个 |
+
+任务状态：`RUNNING`（进行中）、`FINISHED`（完成）、`FAILED`（失败，含 errorCode + errorMessage）。
+
+### +datasource-get-config — 获取数据源配置
+
+```bash
+dws aitable +datasource-get-config --base-id BASE_ID --table-id TABLE_ID --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 目标 Base ID |
+| `--table-id` | 是 | 数据源表 ID（sync=true） |
+
+返回当前同步配置详情（sourceConfig、是否自动同步、同步状态等）。仅适用于数据源表，普通表会报错。
+
+## 错误码与排查
+
+| 场景 | 表现 | 排查 |
+|------|------|------|
+| 同步运行中重复触发 | errorCode=4014，status=FAILED | 幂等冲突，稍后重试即可 |
+| 非数据源表触发 sync | 参数错误返回 | 确认 table 的 sync=true，用 `+base-get` / `+table-list` 检查 |
+| sourceConfig 缺必填字段 | 创建/更新失败 | 检查 processCode/name/iconUrl/url 是否从 list-sources 原样透传 |
+| dataType 与时间字段不匹配 | 创建失败 | recent_time 需 recentDays；time_range 需 startDate+endDate；start_time 需 startDate |
+
+## 能力边界
+
+| 能力 | 状态 |
+|------|------|
+| OA 审批数据源 | 已支持 |
+| 其他数据源类型 | 待后续开放 |
+| 全量同步 | 已支持 |
+| 增量同步 | 待后续开放 |
+| 自动同步 | 已支持（--auto + autoSyncSetting） |
+| 删除数据源表 | 走普通表删除，不走 datasource 命令 |
+
+## 注意事项
+
+- sourceConfig 是 **JSON 字符串**（不是 JSON 对象），CLI flag 传入时需要用单引号包裹
+- list-sources 返回的 keepRemovedFields / splitParentTableField / enableDataSyncOaDetailList 不要透传，由调用方按需设置
+- create/update 后自动触发一次同步，返回 taskId；用 sync-status 查最终结果
+- sync 单次最多 5 张表，超出拆分多次调用
+- sync-status 单次最多 5 个 taskId，超出拆分多次调用
+- get-config 仅适用于数据源表（sync=true），普通表会报错

package/skills/dws/dingtalk-aitable/references/aitable/aitable-error-recovery.md

@@ -0,0 +1,128 @@
+# AI 表格错误恢复指南
+
+> 当 CLI 命令返回错误时，按本文档的映射表判断恢复动作。
+
+## 1. 错误响应结构
+
+```json
+{
+  "status": "error",
+  "summary": "Failed to create records",
+  "trace_id": "2104a64c17790723347215232e085e"
+}
+```
+
+- `status: "error"` 表示操作失败
+- `summary` 包含错误摘要信息
+- `trace_id` 用于问题追踪
+
+## 2. 常见错误与恢复动作
+
+### 2.1 记录操作错误
+
+| 错误现象 / summary | 原因 | 恢复动作 |
+|-------------------|------|---------|
+| `Failed to create records` | cellValue 格式错误或字段类型不匹配 | 先 `field get` 确认字段类型，再按 [cell-value](./aitable-cell-value.md) 规范重构值 |
+| `record not found` | record-id 不存在或已删除 | 用 `record query` 重新查询确认目标记录 |
+| rating 字段写入超出 max | 值超出字段配置范围 | 检查字段 config 的 min/max，确保值在范围内 |
+| singleSelect 写入对象格式但 id 不存在 | option id 无效 | 改用 name 字符串写入（推荐），或先 `field get` 获取有效 option id |
+
+### 2.2 字段操作错误
+
+| 错误现象 / summary | 原因 | 恢复动作 |
+|-------------------|------|---------|
+| `Failed to create field` | config 格式错误或必填项缺失 | 检查 [field-properties](./aitable-field-properties.md) 中该类型的必填 config |
+| `field not found` | field-id 不存在 | 用 `field get` 获取最新字段列表 |
+| formula 创建失败 | 公式语法错误或引用字段名不匹配 | 先 `field get` 确认字段精确名称，再检查公式语法（见 [formula-guide](./aitable-formula-guide.md)） |
+| 删除主字段失败 | 主字段（第一列）不可删除 | 改为更新字段名或类型，不能删除 |
+
+### 2.3 Base/Table 操作错误
+
+| 错误现象 / summary | 原因 | 恢复动作 |
+|-------------------|------|---------|
+| `base not found` | base-id 错误或无权限 | 确认 base-id 正确；尝试 `base list` 或 `base search` 重新定位 |
+| `table not found` | table-id 错误 | 用 `table get --base-id <baseId>` 不带 table-ids 查看所有表 |
+| 表名重复 | 同 Base 下已存在同名表 | 系统会自动续号（如"原名 1"），无需额外处理 |
+
+### 2.4 视图操作错误
+
+| 错误现象 / summary | 原因 | 恢复动作 |
+|-------------------|------|---------|
+| `view not found` | view-id 错误 | 用 `view get --base-id <baseId> --table-id <tableId>` 查看所有视图 |
+| 删除最后一个视图 | 表至少保留一个视图 | 不可删除唯一视图 |
+
+### 2.5 filters/sort 错误
+
+| 错误现象 / summary | 原因 | 恢复动作 |
+|-------------------|------|---------|
+| filters 无效被忽略 | 根节点不是 and/or，或 operands 格式错误 | 确保 filters 根节点是 `{"operator":"and"/"or", "operands":[...]}` 结构 |
+| sort 无效 | fieldId 不存在 | 先 `field get` 确认字段 ID |
+| 筛选结果为空 | 条件过严或字段值不匹配 | 放宽条件验证；注意 singleSelect 筛选值用 option name 或 id |
+
+### 2.6 导入导出错误
+
+| 错误现象 / summary | 原因 | 恢复动作 |
+|-------------------|------|---------|
+| 导出任务超时 | 数据量大，异步任务未完成 | 用 `export data --task-id <taskId>` 轮询直到完成 |
+| 导入文件格式错误 | 不支持的文件格式或文件损坏 | 确认文件为 .xlsx 格式且未加密 |
+
+## 3. 重试策略
+
+### 3.1 可重试的错误
+
+| 错误类型 | 重试方式 | 最大重试次数 |
+|---------|---------|------------|
+| 网络超时 / 5xx | 等待 2s 后原样重试 | 2 |
+| 导出任务未完成 | 轮询 task-id | 5（间隔 3s） |
+| 并发写入冲突 | 串行重试 | 1 |
+
+### 3.2 不可重试的错误（立即停止）
+
+| 错误类型 | 原因 | 处理方式 |
+|---------|------|---------|
+| 权限不足 / 403 | 用户对该 Base 无权限 | 停止操作，提示用户确认权限 |
+| 参数格式错误 | 请求结构不合法 | 修正参数后重试，不要原样重试 |
+| 资源不存在 / 404 | ID 错误或资源已删除 | 重新查询定位资源 |
+| 配额超限 / 429 | API 调用频率过高 | 等待后重试，并降低并发 |
+
+### 3.3 重试前检查清单
+
+在重试前，先确认：
+1. ❓ 错误是暂时性的还是永久性的？
+2. ❓ 参数有没有明显错误需要修正？
+3. ❓ 是否需要先查询最新状态再重试？
+
+## 4. 调试技巧
+
+### 4.1 使用 --verbose 获取详细信息
+
+```bash
+dws aitable record create \
+  --base-id <baseId> \
+  --table-id <tableId> \
+  --records '[...]' \
+  --verbose --format json
+```
+
+`--verbose` 会输出请求/响应的详细信息，帮助定位问题。
+
+### 4.2 使用 --dry-run 预览
+
+```bash
+dws aitable record create \
+  --base-id <baseId> \
+  --table-id <tableId> \
+  --records '[...]' \
+  --dry-run --format json
+```
+
+`--dry-run` 只预览不执行，适合在不确定参数是否正确时先验证。
+
+## 5. 错误预防最佳实践
+
+1. **写记录前先读字段结构** — `field get` 确认字段类型和 ID
+2. **写字段前先读 field-properties** — 确认 config 的必填项和格式
+3. **formula 字段先确认引用字段名** — `[字段名]` 必须精确匹配
+4. **options 更新传完整列表** — 更新 singleSelect/multipleSelect 的 options 是全量覆盖
+5. **大批量操作分批执行** — 单次最多 100 条记录
+6. **使用 --format json** — 确保输出可解析，方便错误判断

package/skills/dws/dingtalk-aitable/references/aitable/aitable-export-import.md

@@ -0,0 +1,113 @@
+# export & import — 导入导出
+
+## 导出数据（两阶段轮询）
+
+`export data` 为异步任务：首次调用可能只返回 `taskId`，需要继续轮询。
+
+> ⚠️ **`--format` 冲突警告**：`export data` 的 `--format` 是**导出格式**（excel/attachment 等），不是全局输出格式。**此命令禁止追加全局 `--format json`**，否则会覆盖导出格式导致 `INVALID_EXPORT_FORMAT` 错误。输出默认就是 JSON，无需额外指定。
+
+```bash
+# 第一步：创建任务（按 scope 传必要参数）——注意：不要加 --format json！
+dws aitable export data --base-id <BASE_ID> --scope table --table-id <TABLE_ID> --format excel --timeout-ms 1000
+
+# 第二步：拿 taskId 继续轮询，直到返回 downloadUrl
+dws aitable export data --base-id <BASE_ID> --task-id <TASK_ID> --timeout-ms 3000
+```
+
+### 参数约束
+
+| scope | 必传参数 |
+|-------|----------|
+| `all` | 只需 `--base-id` |
+| `table` | 必须 `--table-id` |
+| `view` | 必须 `--table-id` + `--view-id` |
+
+## 导入文件（三步流程）
+
+当用户要求将 Excel（`.xlsx`）或 CSV 文件完整导入 AI 表格时，**不需要自己解析文件内容**，直接使用文件级导入。
+
+> **无需手动解析 CSV/Excel 再逐条 record create**，效率极低且容易出错。
+
+```bash
+# 第 1 步：申请上传凭证
+dws aitable import upload --base-id <BASE_ID> \
+  --file-name data.xlsx --file-size <字节数> --format json
+# → 返回 uploadUrl 和 importId
+
+# 第 2 步：上传文件到 OSS（注意：Content-Type 必须设为空）
+curl -X PUT "<uploadUrl>" -H "Content-Type:" --data-binary @data.xlsx
+
+# 第 3 步：触发导入（新建表模式）
+dws aitable import data --import-id <importId> --format json
+# → 返回 status: success 和新建的 tableIds
+
+# 第 3 步（替代）：追加到已有表
+dws aitable import data --import-id <importId> --table-id <TABLE_ID> --format json
+# → 数据作为新行追加到指定表中
+```
+
+### 步骤说明
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 申请上传凭证 | `import upload --base-id <ID> --file-name <名称> --file-size <字节>` | `--file-size` 必须与实际文件大小一致 |
+| 上传文件 | HTTP PUT（curl 等） | **必须** 带 `-H "Content-Type:"` 将 Content-Type 设为空，否则 OSS 返回 403 |
+| 触发导入 | `import data --import-id <ID> [--table-id <TABLE_ID>]` | 同步等待，大多一次调用即返回结果；超时可用相同 importId 重试 |
+
+### import data 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--import-id` | ✅ | `import upload` 返回的 importId |
+| `--table-id` | ❌ | 传入时数据追加到该已有表；不传则每个 Sheet 新建独立的数据表 |
+| `--timeout` | ❌ | 最长等待秒数，默认且推荐 30 |
+| `--header-row` | ❌ | 表头所在行号（从 1 开始），数据从下一行读取。不传则自动识别 |
+| `--src-sheet-name` | ❌ | 源文件中的 Sheet 名称，多 Sheet 文件时指定。不传则用第一个 Sheet |
+| `--field-mapping` | ❌ | 字段映射 JSON（`{"目标字段名":"源列名"}`）。不传则按列名自动匹配 |
+
+### 两种导入模式
+
+| 模式 | 触发条件 | 效果 |
+|------|----------|------|
+| **新建表导入** | 不传 `--table-id` | 每个 Sheet 自动新建为独立数据表 |
+| **追加导入** | 传入 `--table-id` | 数据作为新行追加到指定已有表，按列名自动匹配字段 |
+
+### 支持的文件格式：xlsx vs csv
+
+| 特性 | xlsx | csv |
+|------|------|-----|
+| 新建表导入 | ✅ | ✅ |
+| 追加导入（`--table-id`） | ✅ | ✅ |
+| `--header-row` | ✅ | ❌ 不支持 |
+| `--src-sheet-name` | ✅（多 Sheet 支持） | ❌ 无 Sheet 概念 |
+| `--field-mapping` | ✅ | ✅ |
+
+> **CSV 限制**：CSV 没有 Sheet 概念，且表头固定为第一行，因此 `--header-row` 和 `--src-sheet-name` 对 CSV 均不可用。
+>
+> **建议**：需要指定表头行或多 Sheet 选择时，**必须使用 xlsx 格式**。CSV 仅适用于表头在第一行的简单导入场景。
+
+### 追加导入的字段匹配规则
+
+追加导入时，系统按以下规则将 Excel 列映射到目标表字段：
+
+1. **不传 `--field-mapping`（自动匹配）**：按字段名**精确匹配** Excel 列名和目标表字段名。如果没有任何一列匹配上，导入会失败。
+2. **传 `--field-mapping`（显式映射）**：按映射关系指定对应关系，key 为目标表字段名，value 为 Excel 列名。
+
+> **追加导入失败常见原因**：Excel 列名与目标表字段名不一致（如 Excel 是"销售姓名"但表字段是"姓名"），导致自动匹配 0 个字段，报错 `"Failed to build import sheet infos from preview data"`。
+>
+> **解决方案**：
+> 1. **首选**：创建目标表时，字段名与 Excel 表头列名**保持完全一致**
+> 2. **备选**：传 `--field-mapping '{"目标字段名":"Excel列名"}'` 手动指定映射
+> 3. **兜底**：如果 import data 多次失败，改用 `record create` 逐条写入
+
+### 适用场景
+
+- **新建表导入**：首次导入 Excel/CSV，让系统自动建表建字段
+- **追加到已有表**：已有数据表结构，需要把 Excel 数据批量写入 → 传 `--table-id`（推荐 xlsx）
+- **需要指定表头行**：源文件前几行非数据（如注释行）→ `--header-row`（必须用 xlsx）
+- **多 Sheet 文件**：只导入特定 Sheet → `--src-sheet-name`（必须用 xlsx）
+- **不适用**：需要复杂字段级控制（如只导入部分列、数据转换）→ 解析后用 `record create`
+
+> **导入数据无法整体撤销**：文件一旦导入成功，数据即写入表中，没有"撤销导入"操作。如需清理导入的测试数据，只能手动通过 `record delete` 逐条或批量删除记录；如果是新建表模式导入的，可以直接 `table delete` 删除整张表。因此：
+> - 测试/验证场景建议导入到**独立的测试表或测试 Base**，用完后整体删除
+> - 如果用户明确表示不想导入测试数据或要求先预览内容再决定，应先解析文件内容展示给用户确认，而非直接导入