larksuite-cli/skill-template/domains/base.md

命名约定： Shortcut 命令组和原生 API / schema 都使用 lark-cli base ...。 分流规则： 如果用户要把本地文件导入成 Base / 多维表格 / bitable，第一步不是 base，而是 lark-cli drive +import --type bitable。

核心规则

1. 原生 API 命令路径必须完整 — 资源名是多级点分路径，不能省略前缀
   • lark-cli base table.records create ✅
   • lark-cli base records create ❌
2. 优先使用 Shortcut — 有 Shortcut 的操作不要手拼原生 API
3. 写记录前 — 先调用 table.fields list 获取字段 type/ui_type，再读 lark-base-cell-value.md；该文档是 CellValue 的 source of truth
4. 写字段前 — 先读 lark-base-field-json.md 确认字段类型 JSON 结构
5. 筛选查询前 — 先读 lark-base-view-set-filter.md，当前 base/v3 通过 view.filter update + table.records list 组合完成筛选读取
6. 批量上限 200 条/次 — 同一表建议串行写入，并在批次间延迟 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 快照导入成 Base / 多维表格”，必须先走 lark-cli drive +import --type bitable；只有导入完成后，才回到 lark-cli base ...

意图 → 命令索引

意图	推荐命令	备注
查表字段	table.fields list	写记录 / 更新前必调
查记录	table.records list	GET，简单列表，可附带 view_id
按视图筛选查询	view.filter update + table.records list	当前 base/v3 没有独立 search
把本地 Excel / CSV / .base 导入为 Base / 多维表格	lark-cli drive +import --type bitable	导入阶段属于 drive，不是 base
新增单条记录	table.records create	少量数据
更新记录	table.records patch	只传需要变更的字段
删除记录	table.records delete	单条删除
创建数据表	tables create	原生 API 直接在已有 Base 下建表
创建 / 更新字段	table.fields create/update	复杂字段建议先核对 schema
创建 / 管理视图	table.views create/list/patch	视图筛选条件通过 view.filter 更新

操作注意事项

• Base token 口径统一：无论 Shortcut 还是原生 API，都统一使用 base_token
• 附件字段：上传本地文件时只能走 lark-cli base +record-upload-attachment
• 地理位置字段：写入必须使用 {lng,lat}；读取、筛选和转文本等场景使用 full_address 字符串，筛选优先用包含匹配；只有公式能访问坐标
• 能力边界：当前 base/v3 原生 spec 以单表 / 单记录 / 视图筛选配置为主，批量写入和旧 search 场景优先走 unified Shortcut 组合能力
• 视图重命名确认规则：用户已经明确“把哪个视图改成什么名字”时，执行 table.views patch / 对应 shortcut 直接改名即可，不需要再补一句确认
• 删除确认规则（记录 / 字段 / 表）：执行 table.records delete / table.fields delete / tables delete 或对应 shortcut 时，如果用户已经明确要求删除且目标明确，可以直接执行；只有目标不明确时才先追问
• 创建 / 复制 Base 的友好性规则：创建或复制 Base 时，folder_token、time_zone、复制时的新名称都属于可选项；用户没特别要求时不要为这些参数额外打断
• 创建 / 复制 Base 的结果返回规范：成功后必须主动返回新 Base 的 token；如果返回结果里带可访问链接（如 base.url），也要一并返回

Wiki 链接特殊处理（特别关键！）

知识库链接（/wiki/TOKEN）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。

处理流程

1. 使用 wiki.spaces.get_node 查询节点信息

   lark-cli wiki spaces.get_node --params '{"token":"<wiki_token>"}'
   

2. 从返回结果中提取关键信息

   • node.obj_type：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
   • node.obj_token：真实的文档 token（用于后续操作）
   • node.title：文档标题

3. 根据 obj_type 选择后续命令

   obj_type	说明	后续命令
   docx	新版云文档	drive file.comments.*、docx.*
   doc	旧版云文档	drive file.comments.*
   sheet	电子表格	sheets.*
   bitable	多维表格	lark-cli base +...（优先）；如果 shortcut 不覆盖，再用 lark-cli base <resource> <method>；不要改走 lark-cli api /open-apis/bitable/v1/...
   slides	幻灯片	drive.*
   file	文件	drive.*
   mindnote	思维导图	drive.*

4. 把 wiki 解析出的 obj_token 当成 Base token 使用

   • 当 obj_type=bitable 时，node.obj_token 就是后续 base 命令应使用的真实 token
   • 不要把 wiki_token 直接塞给 --base-token

5. 如果已经报了 token 错，再回退检查 wiki

   • 如果命令返回 param baseToken is invalid、base_token invalid、not found，并且输入来自 /wiki/...，优先怀疑“把 wiki token 当成了 base token”
   • 重新执行 wiki.spaces.get_node
   • 确认 obj_type=bitable 后，用 node.obj_token 重试 lark-cli base ...

查询示例

# 查询 wiki 节点
lark-cli wiki spaces.get_node --params '{"token":"Pgrrwvr***********UnRb"}'

返回结果示例：

{
  "node": {
    "obj_type": "docx",
    "obj_token": "UAJh***********ccaE9nic",
    "title": "ai friendly 测试 - 1 副本",
    "node_type": "origin",
    "space_id": "6946***********839"
  }
}

常见错误速查

错误码	含义	解决方案
1254064	日期格式错误	传 YYYY-MM-DD HH:mm:ss 字符串，不要写相对时间
1254068	超链接格式错误	"https://example.com" 或 "[文本](https://example.com)"
1254066	人员字段错误	[{ "id": "ou_xxx" }]
1254045	字段名不存在	检查字段名（含空格、大小写）
1254015	字段值类型不匹配	先 list 字段，再按类型构造
param baseToken is invalid / base_token invalid	把 wiki token、workspace token 或其他 token 当成了 base_token	如果输入来自 /wiki/...，先查 wiki.spaces.get_node；当 obj_type=bitable 时，用 node.obj_token 作为 base_token 重试，不要改走 bitable/v1
1254104	批量超 200 条	分批调用
1254291	并发写冲突	串行写入 + 批次间延迟

参考文档

• lark-base-field-json.md — 字段类型 JSON 配置
• lark-base-cell-value.md — CellValue source of truth
• lark-base-view-set-filter.md — 查询筛选指南（filter / operator / sort / 分页）
• 具体命令示例由命令 --help 内置 tips 承接；复杂 JSON 只读上方保留 reference