mirror of
https://github.com/larksuite/cli.git
synced 2026-07-07 00:55:53 +08:00
route base import guidance to drive +import (#368)
Change-Id: I12f86a343d79b8fb480084305ed34b54aa92fb94
This commit is contained in:
liujinkun2025
@@ -1,4 +1,5 @@
|
||||
> **命名约定：** Shortcut 命令组和原生 API / schema 都使用 `lark-cli base ...`。
|
||||
> **分流规则：** 如果用户要把本地文件导入成 Base / 多维表格 / bitable，第一步不是 `base`，而是 `lark-cli drive +import --type bitable`。
|
||||
|
||||
## 核心规则
|
||||
|
||||
@@ -12,6 +13,7 @@
|
||||
6. **批量上限 500 条/次** — 同一表建议串行写入，并在批次间延迟 0.5–1 秒
|
||||
7. **改名和删除按明确意图执行** — 视图重命名这类低风险改名操作，目标和新名称明确时可直接执行；删除记录 / 字段 / 表时，只要用户已经明确要求删除且目标明确，也可直接执行，不需要再补一次确认
|
||||
8. **不要走旧 bitable 路径** — Base 场景不要调用 `lark-cli api GET /open-apis/bitable/v1/...`；即使 wiki 解析结果是 `obj_type=bitable`，后续也应继续使用 `lark-cli base ...`
|
||||
9. **不要把本地文件导入误判成 Base 表内操作** — 如果目标是“把 Excel / CSV 导入成 Base / 多维表格”，必须先走 `lark-cli drive +import --type bitable`；只有导入完成后，才回到 `lark-cli base ...`
|
||||
|
||||
## 意图 → 命令索引
|
||||
|
||||
@@ -20,6 +22,7 @@
|
||||
| 查表字段 | `table.fields list` | 写记录 / 更新前必调 |
|
||||
| 查记录 | `table.records list` | GET，简单列表，可附带 `view_id` |
|
||||
| 按视图筛选查询 | `view.filter update` + `table.records list` | 当前 `base/v3` 没有独立 `search` |
|
||||
| 把本地文件导入为 Base / 多维表格 | `lark-cli drive +import --type bitable` | 导入阶段属于 `drive`，不是 `base` |
|
||||
| 新增单条记录 | `table.records create` | 少量数据 |
|
||||
| 更新记录 | `table.records patch` | 只传需要变更的字段 |
|
||||
| 删除记录 | `table.records delete` | 单条删除 |
|
||||
@@ -114,4 +117,4 @@ lark-cli wiki spaces.get_node --params '{"token":"Pgrrwvr***********UnRb"}'
|
||||
- [lark-base-shortcut-field-properties.md](../../skills/lark-base/references/lark-base-shortcut-field-properties.md) — 字段类型 property 配置
|
||||
- [lark-base-shortcut-record-value.md](../../skills/lark-base/references/lark-base-shortcut-record-value.md) — 记录值格式详解
|
||||
- [lark-base-view-set-filter.md](../../skills/lark-base/references/lark-base-view-set-filter.md) — 查询筛选指南（filter / operator / sort / 分页）
|
||||
- [examples.md](../../skills/lark-base/references/examples.md) — 完整操作示例（建表、导入、筛选、更新）
|
||||
- [examples.md](../../skills/lark-base/references/examples.md) — 完整操作示例（建表、筛选、更新）
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
|
||||
## 核心概念
|
||||
|
||||
> **导入分流规则：** 如果用户要把本地 Excel / CSV 导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
|
||||
|
||||
### 文档类型与 Token
|
||||
|
||||
飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 `file_token`。
|
||||
|
||||
@@ -13,10 +13,12 @@ metadata:
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。
|
||||
> **执行前必做：** 执行任何 `base` 命令前，必须先阅读对应命令的 reference 文档，再调用命令。
|
||||
> **命名约定：** 仅使用 `lark-cli base +...` 形式的命令。
|
||||
> **分流规则：** 如果用户要“把本地文件导入成 Base / 多维表格 / bitable”，第一步不是 `base`，而是 `lark-cli drive +import --type bitable`。只有导入完成后，才回到 `lark-cli base +...` 做表内操作。
|
||||
|
||||
## Agent 快速执行顺序
|
||||
|
||||
1. **先判断任务类型**
|
||||
- 本地文件导入成 Base / 多维表格 / bitable → 先切 `lark-cli drive +import --type bitable`
|
||||
- 临时统计 / 聚合分析 → `+data-query`
|
||||
- 要把结果长期显示在表里 → formula 字段
|
||||
- 用户明确要 lookup，或确实更适合 `from/select/where/aggregate` → lookup 字段
|
||||
@@ -37,6 +39,7 @@ metadata:
|
||||
- 不要没读 guide 就直接创建 formula / lookup 字段
|
||||
- 不要凭自然语言猜表名、字段名、公式表达式里的字段引用
|
||||
- 不要把系统字段、formula 字段、lookup 字段当成 `+record-upsert` 的写入目标
|
||||
- 不要把“本地 Excel / CSV 导入成 Base”误判成 `+base-create`、`+table-create` 或 `+record-upsert`；这一步必须先走 `lark-cli drive +import --type bitable`
|
||||
- 不要在 Base 场景改走 `lark-cli api GET /open-apis/bitable/v1/...`
|
||||
- 不要因为 wiki 解析结果里的 `obj_type=bitable` 就去找 `bitable.*`；在本 CLI 里应继续使用 `lark-cli base +...`
|
||||
|
||||
@@ -138,6 +141,7 @@ metadata:
|
||||
| 配置 / 查询视图 | `lark-cli base +view-*` | `list/get/create/delete/get-*/set-*/rename` |
|
||||
| 查看记录历史 | `lark-cli base +record-history-list` | 按表和记录查询变更历史 |
|
||||
| 按视图筛选查询 | `lark-cli base +view-set-filter` + `lark-cli base +record-list` | 组合调用 |
|
||||
| 把本地文件导入为 Base / 多维表格 | `lark-cli drive +import --type bitable` | 导入阶段属于 `drive`，不是 `base` |
|
||||
| 创建 / 获取 / 复制 Base | `lark-cli base +base-create` / `+base-get` / `+base-copy` | 原子命令 |
|
||||
| 列表 / 获取工作流 | `lark-cli base +workflow-list` / `+workflow-get` | 原子命令 |
|
||||
| 创建 / 更新工作流 | `lark-cli base +workflow-create` / `+workflow-update` | 使用 `--json`，必须阅读 schema |
|
||||
@@ -283,7 +287,7 @@ https://{domain}/base/{base-token}?table={table-id}&view={view-id}
|
||||
- [lark-base-workflow.md](references/lark-base-workflow.md) — workflow 命令索引
|
||||
- [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md) — `+workflow-create/+workflow-update` JSON body 数据结构详解，包含触发器及各类节点的配置规则（强烈推荐）
|
||||
- [lark-base-data-query.md](references/lark-base-data-query.md) — `+data-query` 聚合分析（DSL 结构、支持字段类型、聚合函数）
|
||||
- [examples.md](references/examples.md) — 完整操作示例（建表、导入、筛选、更新）
|
||||
- [examples.md](references/examples.md) — 完整操作示例（建表、筛选、更新）
|
||||
|
||||
## 命令分组
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: lark-drive
|
||||
version: 1.0.0
|
||||
description: "飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件。当用户需要上传或下载文件、整理云空间目录、查看文件详情、管理评论、管理文档权限、订阅用户评论变更事件时使用。"
|
||||
description: "飞书云空间：管理云空间中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件；也负责把本地 Word/Markdown/Excel/CSV 导入为飞书在线云文档（docx、sheet、bitable）。当用户需要上传或下载文件、整理云空间目录、查看文件详情、管理评论、管理文档权限、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base 时使用。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
@@ -12,6 +12,13 @@ metadata:
|
||||
|
||||
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
|
||||
|
||||
## 快速决策
|
||||
|
||||
- 用户要把本地 `.xlsx` / `.csv` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
|
||||
- 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
|
||||
- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
|
||||
- `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
|
||||
|
||||
## 核心概念
|
||||
|
||||
### 文档类型与 Token
|
||||
|
||||
@@ -4,6 +4,11 @@
|
||||
|
||||
将本地文件（如 Word、TXT、Markdown、Excel 等）导入并转换为飞书在线云文档（docx、sheet、bitable）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 当用户说“把本地 Excel / CSV 导入成 Base / 多维表格 / bitable 文档”时，第一步必须使用 `drive +import --type bitable`。
|
||||
> 这是 Drive 导入场景，不是 `lark-base` 的建表 / 写记录场景。
|
||||
> 只有导入完成并拿到新文档的 `token` / `url` 后，后续字段、记录、视图等表内操作才切换到 `lark-cli base +...`。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
@@ -13,6 +18,9 @@ lark-cli drive +import --file ./README.md --type docx
|
||||
# 导入 Excel 为电子表格 (sheet)
|
||||
lark-cli drive +import --file ./data.xlsx --type sheet
|
||||
|
||||
# 导入 Excel 为多维表格 / Base (bitable)
|
||||
lark-cli drive +import --file ./crm.xlsx --type bitable --name "客户台账"
|
||||
|
||||
# 导入到指定文件夹，并指定导入后的文件名
|
||||
lark-cli drive +import --file ./data.csv --type bitable --folder-token <FOLDER_TOKEN> --name "导入数据表"
|
||||
|
||||
@@ -54,6 +62,8 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
|
||||
| `.csv` | `sheet`, `bitable` | CSV 数据文件 |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 用户口头说的 “Base” / “多维表格” / “bitable”，在命令里统一对应 `--type bitable`。
|
||||
>
|
||||
> 文件扩展名与目标文档类型必须匹配，否则会返回验证错误：
|
||||
> - 文档类文件（.docx, .doc, .txt, .md, .html）**只能**导入为 `docx`
|
||||
> - `.xlsx` / `.csv` 文件**只能**导入为 `sheet` 或 `bitable`
|
||||
|
||||
Reference in New Issue
Block a user