diff --git a/skill-template/domains/base.md b/skill-template/domains/base.md index 14b6d1896..79c5acb42 100644 --- a/skill-template/domains/base.md +++ b/skill-template/domains/base.md @@ -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) — 完整操作示例(建表、筛选、更新) diff --git a/skill-template/domains/drive.md b/skill-template/domains/drive.md index 8a381acc1..6e329d0fb 100644 --- a/skill-template/domains/drive.md +++ b/skill-template/domains/drive.md @@ -1,6 +1,8 @@ ## 核心概念 +> **导入分流规则:** 如果用户要把本地 Excel / CSV 导入成 Base / 多维表格 / bitable,必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`;`lark-base` 只负责导入完成后的表内操作。 + ### 文档类型与 Token 飞书开放平台中,不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作(如添加评论、下载文件等)时,必须先获取正确的 `file_token`。 diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index 23f4abc87..6865f5156 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -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) — 完整操作示例(建表、筛选、更新) ## 命令分组 diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md index a8bcd58a1..aa882ecd1 100644 --- a/skills/lark-drive/SKILL.md +++ b/skills/lark-drive/SKILL.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 diff --git a/skills/lark-drive/references/lark-drive-import.md b/skills/lark-drive/references/lark-drive-import.md index ab176c60e..33a74235a 100644 --- a/skills/lark-drive/references/lark-drive-import.md +++ b/skills/lark-drive/references/lark-drive-import.md @@ -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 --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`