Compare commits
4 Commits
e37dea886b
...
93945b626c
| Author | SHA1 | Date | |
|---|---|---|---|
| 93945b626c | |||
| 4598370fd2 | |||
| c5f4209d33 | |||
| a7883dbed9 |
35
.agents/skills/lark-approval/SKILL.md
Normal file
35
.agents/skills/lark-approval/SKILL.md
Normal file
@ -0,0 +1,35 @@
|
||||
---
|
||||
name: lark-approval
|
||||
version: 1.1.0
|
||||
description: "飞书审批：当前用户审批的查询与全部处理操作，覆盖待本人审批的任务与本人发起的实例。审批待办不是飞书任务（任务类待办走 lark-task）；不负责创建审批定义和发起新审批。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli approval --help"
|
||||
---
|
||||
|
||||
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
|
||||
|
||||
所有命令默认 `--as user`（审批是人的动作）。调用前先 `lark-cli schema approval.<resource>.<method>` 查参数结构，不要猜字段。
|
||||
|
||||
## 选哪个命令
|
||||
|
||||
| 想做什么 | 命令 |
|
||||
|---|---|
|
||||
| 查待办/已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读）|
|
||||
| 看表单/进度/当前节点 | `instances get` |
|
||||
| 同意/拒绝 | `tasks approve` / `tasks reject` |
|
||||
| 转交/加签/退回 | `tasks transfer` / `tasks add_sign` / `tasks rollback` |
|
||||
| 催办 | `tasks remind` |
|
||||
| 撤回/抄送/按定义查已发起 | `instances cancel` / `instances cc` / `instances initiated` |
|
||||
|
||||
处理链：`tasks query` 拿 `instance_code` + `task_id`（操作必须成对带上）→ 需要细节再 `instances get` → 执行操作。
|
||||
|
||||
```bash
|
||||
lark-cli approval tasks query --params '{"topic":"1"}' --as user
|
||||
lark-cli approval tasks approve --data '{"instance_code":"<ic>","task_id":"<tid>","comment":"同意"}' --as user
|
||||
```
|
||||
|
||||
## 不在本 skill 范围
|
||||
|
||||
创建审批定义/发起新审批（走飞书客户端或审批管理后台）；非审批类待办 → [`lark-task`](../lark-task/SKILL.md)
|
||||
71
.agents/skills/lark-apps/SKILL.md
Normal file
71
.agents/skills/lark-apps/SKILL.md
Normal file
@ -0,0 +1,71 @@
|
||||
---
|
||||
name: lark-apps
|
||||
version: 1.0.0
|
||||
description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、HTML静态站点发布、本地全栈开发、云端生成迭代。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站给人看，或提到妙搭/Spark/Miaoda、应用数据库、可见范围时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli apps --help; lark-cli apps +<cmd> --help"
|
||||
---
|
||||
|
||||
# apps (v1)
|
||||
|
||||
妙搭应用属于用户资产。默认用 `--as user`；认证、scope、exit-10、高风险确认、`_notice` 等通用处理只读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不要在本 skill 里复制。妙搭应用有三条开发路径：**本地全栈**（拉源码本地写）/ **HTML 托管**（发布静态产物）/ **云端会话**（妙搭 AI 生成）。
|
||||
|
||||
## 意图路由
|
||||
|
||||
按具体操作查命令（开发路径先用下方「选择开发路径」判定表定好再进来取命令）：
|
||||
|
||||
| 用户意图 | 先用 | 按需读取 |
|
||||
|---|---|---|
|
||||
| 创建**新**应用资产、拿 app_id | `+create` | [`lark-apps-create.md`](references/lark-apps-create.md) |
|
||||
| 找已有 app_id、按名字过滤应用 | `+list --keyword <name>` | [`lark-apps-list.md`](references/lark-apps-list.md) |
|
||||
| 改应用名或描述 | `+update` | [`lark-apps-update.md`](references/lark-apps-update.md) |
|
||||
| 发布本地 `index.html` 或静态目录为可访问 URL | `+html-publish` | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
|
||||
| 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git） | [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md), [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
|
||||
| 本地开发时 `.env.local` 损坏/丢失，重新拉取启动期环境变量 | `+env-pull` | [`lark-apps-env-pull.md`](references/lark-apps-env-pull.md) |
|
||||
| 看表、看 schema、跑 SQL、初始化 dev/online 多环境 DB | `+db-table-list`, `+db-table-get`, `+db-execute`, `+db-env-create` | 对应 `lark-apps-db-*.md` |
|
||||
| **部署/上线全栈应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）, `+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）, `+release-list` | [`lark-apps-release-create.md`](references/lark-apps-release-create.md), [`lark-apps-release-get.md`](references/lark-apps-release-get.md), [`lark-apps-release-list.md`](references/lark-apps-release-list.md) |
|
||||
| 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference |
|
||||
| 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |
|
||||
|
||||
## 选择开发路径（进意图路由前先判这步）
|
||||
|
||||
新建必先定 **app_type** 和**开发方式**两件正交的事；修改已有先按「app_id 获取」指认到 app，指认不到就问用户，不擅自 `+create`。开发方式（本地 vs 云端）只看用户对"谁来写代码"的偏好，与应用复杂度、要不要数据库无关。
|
||||
|
||||
| 信号 | 判定 |
|
||||
|---|---|
|
||||
| 静态展示 / 单页 / PPT/demo / 无后端状态 | `app_type=html`，跳过本地/云端轴，开发完按 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)（含"未提部署→先问是否发布"） |
|
||||
| 登录 / 数据库 / 持久化 / 多人协作 / 增删改查 / 报名 / 投票 / 站会 / OKR / 泛称"系统·工具" | `app_type=full_stack` |
|
||||
| 用户要自己写 / 本地 IDE·code agent / 拉源码到本地 / 交研发 | 本地全栈，读 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) |
|
||||
| 让妙搭 AI 云端生成 / 对话式 / 自己不碰代码 | 云端会话，读 [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) |
|
||||
| 未表达"谁来写"偏好 | **必须先问**（本地代码开发 vs 云端 AI 生成）；选定前不擅自选边、不暗示默认，不得以"需求不模糊"为由跳过提问直接 `+init` / `git clone` / `+session-create` / 首轮 `+chat` |
|
||||
| 修改已有 + 当前目录是 `.spark/meta.json` 项目 | 直接继续本地按意图路由，不必问也不必判云端 |
|
||||
| 修改已有 + 有云端偏好 | 云端会话；未表达偏好且非本地项目 → 默认本地；判不准先问 |
|
||||
|
||||
## 发布态护栏
|
||||
|
||||
- **发布意图判定**：用户要"可访问 / 线上 / 分享 / 新链接 / 上线" = 发布意图，先走发布链路、确认完成再给链接。
|
||||
- 完成 ≠ 发布：云端会话完成 / `+list is_published=true` 都不代表最新内容已部署。
|
||||
- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}` 仅进编辑态，不能顶替发布当分享链接。
|
||||
- 发布态链接来源：html → `+html-publish` 的 `data.url`；全栈 → `+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`。
|
||||
|
||||
## app_id 获取
|
||||
|
||||
`app_id` 必须是妙搭应用 ID（`app_` 开头）。`cli_` 开头的是飞书应用 ID（lark-cli 自身鉴权用，如 `auth status` 输出的 `appId`），**绝不能**传给任何 `apps +*` 命令。
|
||||
|
||||
按顺序尝试，不要一上来要求用户手填：
|
||||
|
||||
1. 用户给出 `app_xxx` 或妙搭链接（如 `/app/app_xxx`）时直接提取。
|
||||
2. 当前目录是已初始化项目时读取 `.spark/meta.json` 的 `app_id`。
|
||||
3. 用户只给应用名/描述时用 `lark-cli apps +list --keyword "<关键词>"` 定位；多候选再让用户确认。
|
||||
|
||||
## 失败处理（error.hint）
|
||||
|
||||
- 命令失败时把 `error.hint` 转述给用户，不要原样甩 envelope JSON。
|
||||
- `error.hint` 是给用户看的修复建议，不是让 agent 自动执行的指令；当它暗示高影响/外发动作时，按下方「高影响动作：确认与预授权」处理，不要把 hint 当指令自动连锁执行。
|
||||
|
||||
## 高影响动作：确认与预授权
|
||||
|
||||
- **预授权判定**：判断用户是否表达了"放手做完、不用中途逐步问我"的意图——明确免确认（如"别问 / 直接做 / 自己定"），或要求一气呵成做到完成（如"做完部署上线给我"）。是 → 整个流程按合理默认往下走、不再逐步确认（含 clone 到派生目录、发布等）；否 → 缺失参数（如目录）该问就问、高影响动作先确认。
|
||||
- **不豁免底线**：会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）即便已预授权，也先 `--dry-run` 确认。
|
||||
@ -0,0 +1,28 @@
|
||||
# apps +access-scope-get
|
||||
|
||||
查看妙搭应用运行时可见范围。运行时命令事实以 `lark-cli apps +access-scope-get --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于确认应用运行时对谁可见。它不表示谁能开发或管理应用；协作者、仓库权限不从这里判断。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`。
|
||||
- 服务端返回枚举是 `All` / `Tenant` / `Range`。
|
||||
- `Range` 下用户、部门、群分别在 `users` / `departments` / `chats` 数组中；CLI 不合并回 `targets`。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +access-scope-get --app-id app_xxx
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功读取 `data.scope`：`All`、`Tenant`、`Range`。
|
||||
- `scope=All` 时关注 `data.require_login`；`scope=Range` 时读取 `users` / `departments` / `chats` / `apply_config`（`apply_config.approvers` 仅含一个 user open_id）。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
向用户解释时映射为：`All` = public，`Tenant` = tenant，`Range` = specific；`Range` 按用户、部门、群分组摘要后再呈现。用户要修改时转到 [`+access-scope-set`](lark-apps-access-scope-set.md)。
|
||||
@ -0,0 +1,40 @@
|
||||
# apps +access-scope-set
|
||||
|
||||
设置妙搭应用运行时可见范围。运行时命令事实以 `lark-cli apps +access-scope-set --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于修改应用运行时可见范围。不要把它当作开发协作者管理；用户说“谁可以访问/打开/使用应用”才走这里。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`、`--scope`。
|
||||
- `--scope` 枚举：`specific` / `public` / `tenant`。
|
||||
- `specific` 必填 `--targets`，JSON 数组元素形如 `{"type":"user|department|chat","id":"..."}`。
|
||||
- `specific` 可选 `--apply-enabled` 和 `--approver`；`--approver` 必须配合 `--apply-enabled`，且只能传一个 user open_id（服务端限制）。
|
||||
- `public` 必须显式传 `--require-login=true|false`。
|
||||
- `tenant` 不允许额外 target/apply/login flag。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
|
||||
|
||||
lark-cli apps +access-scope-set --app-id app_xxx --scope public --require-login=true
|
||||
|
||||
lark-cli apps +access-scope-set --app-id app_xxx --scope specific \
|
||||
--targets '[{"type":"user","id":"ou_xxx"},{"type":"chat","id":"oc_xxx"}]'
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功时 `data` 可能为空；根据已执行的 `--scope` 和 targets 给用户总结结果。
|
||||
- 互斥参数错误会在本地 validation 阶段失败，不会发请求。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
这是运行时访问范围，不是开发协作者权限。收窄可见范围前向用户说明影响，并在执行前确认目标用户、部门或群。
|
||||
|
||||
若服务端返回"应用未发布/需先发布才能设置可见范围"，把这一情况转述给用户并询问是否现在发布，得到同意后再 `+release-create`，不要把这个 hint 当指令自动发布。
|
||||
|
||||
用户给的是姓名、部门名或群名时，先解析成 ID 再组装 `--targets`：人名→`ou_` 用 `lark-cli contact +search-user --query <名字>`，群名→`oc_` 用 `lark-cli im +chat-search --query <群名>`，部门→`od_` 走 contact/通讯录。多候选时展示名称和 ID 让用户选，不要要求用户手填 `ou_` / `od_` / `oc_`。
|
||||
119
.agents/skills/lark-apps/references/lark-apps-cloud-dev.md
Normal file
119
.agents/skills/lark-apps/references/lark-apps-cloud-dev.md
Normal file
@ -0,0 +1,119 @@
|
||||
# lark-apps 云端会话开发
|
||||
|
||||
适用：用户希望让云端妙搭 Agent 生成或迭代应用，而不是把代码拉到本地开发。
|
||||
|
||||
## 核心流程
|
||||
|
||||
整个开发在云端进行：本地只负责「发消息 + 轮询状态」，不拉源码、不产出代码、不启动本地 dev server。所有 session/chat 命令都以用户身份执行（`--as user`）。
|
||||
|
||||
### 资源模型：app → session → turn
|
||||
|
||||
三层父子关系，下层都挂在上层之下：
|
||||
|
||||
- **app（应用资产）**：一个妙搭应用，由 `+create` 创建并拿到 `app_id`。云端生成应用类型用 `full_stack`。
|
||||
- **session（会话）**：一个 app 下的一段独立对话上下文，由 `+session-create` 创建并拿到 `session_id`。一个 app 可有多个 session；`is_active` 表示该 session 当前是否可写（可发起对话）。
|
||||
- **turn（轮）**：一个 session 里的一轮交互 = 一条用户消息 + 妙搭 Agent 针对它的生成/迭代。`+chat` 发一条消息就发起一轮；轮的句柄是 `turn_id`，状态看 `latest_turn.status`。
|
||||
|
||||
### 执行模型：异步 + 轮询
|
||||
|
||||
`+chat` 把消息入队后**立即返回、不等生成完成，响应不带 `turn_id`**；本轮状态与轮询节奏全靠 `+session-get` 读 `latest_turn.status` / `is_streaming` / `next_poll_after_ms`。
|
||||
|
||||
`+session-get` 关键字段：
|
||||
|
||||
- `is_streaming`：当前是否有一轮正在跑（`true`=还在生成）。
|
||||
- `latest_turn.status`：最近一轮的状态，只有 `running` / `completed` / `failed` / `cancelled`。
|
||||
- `latest_turn.turn_id`：最近一轮的句柄（`+session-stop --turn-id` 用它）。
|
||||
- `latest_turn.user_message`：本轮用户发的消息。
|
||||
- `latest_turn.messages`：这一轮里妙搭 Agent 执行产生的消息列表，按时序排列、每条带 `role`（用户消息、模型回复、工具调用等都在内，role 取值如 `user` / `assistant` / `tool`）。要回看本轮做了什么、结果如何，读这个列表。
|
||||
- `queued_messages` / `queued_count`：还没开始跑、排在后面的消息。
|
||||
- `next_poll_after_ms`：建议的下次轮询间隔（毫秒，固定值）；非空时优先用它。
|
||||
|
||||
轮询规则：
|
||||
|
||||
- 节奏按 [初始化 vs 增量修改](#初始化-vs-增量修改) 判定：增量 5-10 秒一次；初始化 60-120 秒一次；`next_poll_after_ms` 非空时用它。
|
||||
- `is_streaming=true`、`building` / `running` / `streaming` 表示仍在生成，继续轮询，不傻等也不提前放弃；初始化阶段单次 sleep 拉到 60-120 秒，进入 `streaming` 或属增量修改时切回 5-10 秒。
|
||||
- `is_streaming=false` 且 `latest_turn.status=completed` 表示本轮完成，可发下一条。
|
||||
- `failed` / `cancelled` 时转述错误字段或 hint，由用户决定是否重试，不要静默重发。
|
||||
- 不知道某 app 有哪些 session 时，先 `+session-list --app-id <id>`，再选最近活跃的或让用户确认，别直接猜 `session_id`。
|
||||
- 要中止正在运行的一轮，从 `+session-get` 的 `latest_turn.turn_id` 取值，再调用 `+session-stop --turn-id <turn_id>`。
|
||||
|
||||
### 典型链路
|
||||
|
||||
```bash
|
||||
# 1) 建 app，拿 app_id（云端生成走 full_stack）
|
||||
lark-cli apps +create --name "待办应用" --app-type full_stack \
|
||||
--description "支持新增、完成、筛选待办"
|
||||
|
||||
# 2) 在该 app 下建 session，拿 session_id
|
||||
lark-cli apps +session-create --app-id app_xxx
|
||||
|
||||
# 3) 发消息发起一轮（异步入队，立即返回，无 turn_id）
|
||||
lark-cli apps +chat --app-id app_xxx --session-id sess_xxx --message "做一个待办清单页面"
|
||||
|
||||
# 4) 轮询本轮状态；完成后从 latest_turn.messages 读取结果
|
||||
lark-cli apps +session-get --app-id app_xxx --session-id sess_xxx
|
||||
|
||||
# 找该 app 已有的会话（续聊/不确定 session 时用）
|
||||
lark-cli apps +session-list --app-id app_xxx
|
||||
```
|
||||
|
||||
## 完成态不等于发布态
|
||||
|
||||
通用发布态判定（is_published 语义、开发态链接拼接、发布态链接来源）见 SKILL.md「发布态护栏」。本 reference 只补云端会话特有的措辞：
|
||||
|
||||
- `+session-get` 返回 `is_streaming=false` 且 `latest_turn.status=completed`，只说明本轮云端生成/迭代结束，不等于已发布部署。
|
||||
- 如果只完成了云端会话、没有确认发布完成，就明确告诉用户“开发态链接可进入继续编辑，发布态是否为最新版本尚未确认”。
|
||||
|
||||
## 需求发送
|
||||
|
||||
- 只有用户明确选择云端路径，或明确说“让妙搭 Agent / 云端 AI 生成/迭代”时，才进入本 reference；不要因为用户只说“做个 X”或“给我链接”就默认云端。
|
||||
- 进入云端路径后，极简需求也可直接发起生成，例如“做个投票工具”“做个站会小应用”。先建 `full_stack` app，再用 `+chat --message "<用户原话>"` 透传需求，不编造实体、字段或业务细节。
|
||||
- 如果需求过泛，可在 `+chat --message` 中保留原话，并只补一句“请先生成通用版本，后续可继续迭代”，不要用多轮追问阻塞生成。
|
||||
|
||||
## 会话落点
|
||||
|
||||
| 情形 | 动作 |
|
||||
|---|---|
|
||||
| 全新应用 + 云端生成 | 先 `+create --app-type full_stack` 拿 `app_id`，再 `+session-create` -> `+chat` |
|
||||
| 已知 app_id，用户没指定会话 | 先 `+session-list`；有活跃会话时问用户继续现有还是新开 |
|
||||
| 用户说“新开一段/换个话题” | `+session-create` 后再 `+chat` |
|
||||
| 用户说“接着刚才” | 复用上下文 session_id；拿不到就 `+session-list` 让用户选 |
|
||||
| 用户问会话“进行到哪一步/当前状态/最新进展” | 用 `+session-get --session-id <sid>` 读状态。`+session-list` 只负责发现/选择会话，不含执行状态；它返回空不等于无状态可查（session_id 也可能来自上下文），别用 `+session-list`/`+release-list` 代替 `+session-get` 回答进度 |
|
||||
|
||||
## 初始化 vs 增量修改
|
||||
|
||||
`+chat` 单轮的耗时差距很大，取决于目标 app 是否**已初始化**。两者的轮询节奏不同，**`+chat` 前先把状态判定清楚**，不要拿"是不是第一次发消息"当代理判断——session 是新建的不代表 app 没初始化过。
|
||||
|
||||
### 判定规则
|
||||
|
||||
**已初始化**（满足任一即认为已初始化）：
|
||||
|
||||
1. 本地存在该 app 的项目目录（已 `+init` 或 clone 过），**且** git commit 数 > 2；
|
||||
2. 应用维度（云端）至少有一个已提交的版本，按以下任一信号判断：
|
||||
- `lark-cli apps +session-get --app-id <app_id> --session-id <session_id>` 的返回里出现已提交版本信息；
|
||||
- 在 `lark-cli apps +list`（必要时配 `--keyword <name>` 定位）的目标 app 条目里 `is_published: true`。
|
||||
|
||||
**未初始化**（两个条件同时成立）：
|
||||
|
||||
1. 本地不存在该 app 的项目目录；
|
||||
2. 应用维度没有任何已提交版本（即上面两路云端信号都判 false）。
|
||||
|
||||
### 两种 `+chat` 的行为
|
||||
|
||||
| 状态 | 服务端动作 | 单轮耗时 | 轮询建议 |
|
||||
|---|---|---|---|
|
||||
| 已初始化 → **增量修改** | 云端 Agent 在已有云端工作区上对**已提交代码**做局部修改，跳过方案设计与首次生成 | 通常分钟级 | `next_poll_after_ms` 为空时 5-10 秒一次 |
|
||||
| 未初始化 → **首次初始化 + 生成** | 服务端跑完整的应用初始化流程：需求分析、技术方案、数据模型、UI 与后端代码生成、首版代码提交到云端工作区 | 视需求复杂度，**通常 20~50 分钟** | `next_poll_after_ms` 为空时 60-120 秒一次 |
|
||||
|
||||
初始化阶段 `+session-get` 可能长时间持续返回 `building` / `running`，是正常状态，**不要按失败处理，也不要催用户**。
|
||||
|
||||
## 字段注意
|
||||
|
||||
所有字段统一 snake_case，顶层和嵌套 turn 字段都一样：`session_id`、`is_active`、`is_streaming`、`next_poll_after_ms`、`latest_turn.turn_id`、`latest_turn.status`、`latest_turn.user_message`、`latest_turn.messages`。
|
||||
|
||||
`+session-stop` 只停止正在运行的当前轮，不关闭会话；停完仍可继续 `+chat`。
|
||||
|
||||
## 不适用
|
||||
|
||||
- 用户已有本地 HTML/dist，要马上发布 URL：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
|
||||
- 用户要本地写代码、改仓库、跑 dev server：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。
|
||||
40
.agents/skills/lark-apps/references/lark-apps-create.md
Normal file
40
.agents/skills/lark-apps/references/lark-apps-create.md
Normal file
@ -0,0 +1,40 @@
|
||||
# apps +create
|
||||
|
||||
创建妙搭应用。运行时命令事实以 `lark-cli apps +create --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用来创建应用资产并拿到 `app_id`。它不负责把自然语言需求交给云端 Agent：用户要“帮我生成/迭代应用”时，先创建 `full_stack` app，再进入 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md) 用 `+session-create` / `+chat` 提交需求。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--name`、`--app-type`。
|
||||
- app type 语义取值为 `html` / `full_stack`；CLI 会把输入归一成小写后校验。
|
||||
- 可选：`--description`、`--icon-url`。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +create --name "客户调研问卷" --app-type html
|
||||
|
||||
lark-cli apps +create --name "审批系统" --app-type full_stack \
|
||||
--description "部门审批系统，支持登录、提交申请、多级审批"
|
||||
|
||||
lark-cli apps +create --name "Demo" --app-type html --dry-run
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功默认 JSON envelope 中读取 `data.app.app_id`，同时可用 `data.app.name` / `description` 向用户确认结果。
|
||||
- pretty 输出只适合人看；后续命令需要 app_id 时，用 JSON 或 `--jq '.data.app.app_id'`。
|
||||
|
||||
## app type 与命名
|
||||
|
||||
- `--app-type` 取值与判定信号见 SKILL.md「选择开发路径」，此处不重复。
|
||||
- 用户只给自然语言需求时，据此生成简洁的 `--name` 和一句 `--description` 直接创建；不满意再用 `+update` 改。
|
||||
|
||||
创建后按用户路径继续：
|
||||
|
||||
- 发布现成 HTML/静态目录：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
|
||||
- 本地全栈开发：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。
|
||||
- 云端 Agent 生成/迭代：读 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md)。
|
||||
@ -0,0 +1,31 @@
|
||||
# apps +db-env-create
|
||||
|
||||
把存量单库应用初始化为 `dev` / `online` 多环境数据库。运行时命令事实以 `lark-cli apps +db-env-create --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
仅用于存量单库应用需要拆成 `dev` / `online` 两套数据库的场景。普通查看表、查 schema、执行 SQL 不需要先初始化。注意：通过 `+create --app-type full_stack` 新建的应用通常已自带多环境，无需再初始化（重复初始化会返回「已初始化」错误）。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`。
|
||||
- `--env`：要创建的环境，由调用方传入，目前只支持 `dev`（默认 `dev`）。
|
||||
- `--sync-data`：bool 开关，传 `--sync-data` 则把现有 online 数据复制到新环境；不传则不复制（默认）。
|
||||
- risk 是 `high-risk-write`；单库拆成 dev/online 后不可逆。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +db-env-create --app-id app_xxx --env dev --dry-run
|
||||
lark-cli apps +db-env-create --app-id app_xxx --env dev --sync-data --yes
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功读取 `data.status`、`data.environments`、`data.data_synced`；pretty 会提示是否初始化、多环境列表、是否同步数据。
|
||||
- 未确认时返回 `confirmation_required` / exit 10；按 lark-shared 询问用户后再补 `--yes` 重试。
|
||||
- 如果服务端提示已启用多环境（`Multi-env is already initialized`），转述状态即可，不要重复初始化。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
不要静默追加 `--yes`。遇到 confirmation_required 时，按 `lark-shared` 的 exit-10 协议向用户确认不可逆风险；用户明确同意后才在原 argv 末尾追加 `--yes` 重试。
|
||||
40
.agents/skills/lark-apps/references/lark-apps-db-execute.md
Normal file
40
.agents/skills/lark-apps/references/lark-apps-db-execute.md
Normal file
@ -0,0 +1,40 @@
|
||||
# apps +db-execute
|
||||
|
||||
经妙搭服务端在应用数据库执行 SQL。运行时命令事实以 `lark-cli apps +db-execute --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于通过妙搭服务端执行应用数据库 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个 shortcut。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`，以及 `--sql` / `--file` 二选一（互斥）。
|
||||
- `--sql`：内联 SQL 文本；传 `-` 时从 stdin 读。绝对路径文件经 stdin 传入：`--sql - < <absolute-path>`（shell 解析路径，CLI 仅接收内容）。
|
||||
- `--file`：`.sql` 文件路径，需为工作目录内的相对路径（如 `--file ./migration.sql`）；绝对路径、或经 `..`/符号链接越出工作目录的路径会被拒绝。文件不在工作目录内时，改用 `--sql - < <文件路径>` 经 stdin 传入。
|
||||
- `--env` 枚举：`dev` / `online`，**默认 `dev`**；需要操作线上环境数据库时，显式指定 `--env online`。
|
||||
- risk 是 `high-risk-write`（SQL 可含 DML/DDL）：任何执行都需 `--yes`，否则返回 `confirmation_required` / exit 10。`--dry-run` 预览不需要 `--yes`。
|
||||
- CLI 永远传 `transactional=false`；不默认包事务。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +db-execute --app-id app_xxx --env dev --sql "select * from orders limit 5" --yes
|
||||
lark-cli apps +db-execute --app-id app_xxx --env dev --file ./migration.sql --dry-run
|
||||
# 绝对路径文件 / cwd 不固定：经 stdin 传入
|
||||
lark-cli apps +db-execute --app-id app_xxx --env dev --sql - --yes < /Users/.../migrations/0001_init.sql
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功默认 JSON 读取 `data.results[]`；每个元素对应一条 SQL，常见字段有 `sql_type`、`data`、`record_count`、`affected_rows`。
|
||||
- pretty 会按 SELECT/DML/DDL 自适应渲染；多语句会逐条显示 Statement 摘要。
|
||||
- 失败可能仍有前序语句已执行；此时 stdout 输出 `ok:false` 的 envelope（exit 非 0），从 `data` 读 `results[]`（全部逐条结果，失败语句 `sql_type` 为 `ERROR`）、`statement_index`、`error_code`、`error_message`、`rolled_back` 和 `note`，决定从哪条继续。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
- 该命令为 high-risk-write，执行一律需 `--yes`；无 `--yes` 会返回 `confirmation_required` / exit 10。
|
||||
- **只读查询、以及不删除/不丢失既有数据且可撤回的语句**：已授权时可直接带 `--yes` 执行。
|
||||
- **会删除或丢失既有数据、或难以撤回的语句**：先 `--dry-run` 预览（无需 `--yes`），向用户确认后再带 `--yes` 执行；不要在用户不知情时自动补 `--yes`。
|
||||
- 多语句失败时，失败前的语句可能已经 auto-commit。不要整批重跑；按错误 detail/hint 修失败语句，并从剩余语句继续。
|
||||
- 如果需要原子性，让用户在 SQL 内显式写 `BEGIN` / `COMMIT`，不要假设 CLI 会包事务。
|
||||
- 不要把数据库连接串从 env 中取出来裸连。
|
||||
@ -0,0 +1,29 @@
|
||||
# apps +db-table-get
|
||||
|
||||
查看妙搭应用数据库某张表的结构。运行时命令事实以 `lark-cli apps +db-table-get --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于查看已知表的字段、索引、约束，或给 SQL/迁移生成提供依据。只想知道有哪些表时先 `+db-table-list`。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`、`--table`。
|
||||
- `--env` 枚举：`dev` / `online`，默认 `online`。
|
||||
- `--format pretty` 会向服务端请求 DDL，并直接输出 DDL 文本；默认 JSON 返回结构化 columns/indexes/constraints/stats。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +db-table-get --app-id app_xxx --table orders
|
||||
lark-cli apps +db-table-get --app-id app_xxx --table orders --env dev --format pretty
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 默认 JSON 读取 `data.name`、`columns`、`indexes`、`constraints`、`estimated_row_count`、`size_bytes`。
|
||||
- `--format pretty` stdout 是服务端返回的 DDL 文本，不是 JSON envelope；需要建表语句时可原样给用户。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
需要给用户看建表语句或迁移参照时用 `--format pretty`；需要程序化分析字段/索引/约束时保留默认 JSON。
|
||||
@ -0,0 +1,31 @@
|
||||
# apps +db-table-list
|
||||
|
||||
列出妙搭应用某个数据库环境的数据表。运行时命令事实以 `lark-cli apps +db-table-list --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于先摸清应用数据库里有哪些表，或在用户只给业务对象名时定位可能的表名。已知表名且要字段/索引时直接用 `+db-table-get`。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`。
|
||||
- `--env` 枚举：`dev` / `online`，默认 `online`。
|
||||
- 分页：`--page-size` 默认 20，`--page-token` 使用上一页 cursor。
|
||||
- pretty 输出列包含 `name`、`description`、`estimated_row_count`、`size`、`columns`（列数）。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +db-table-list --app-id app_xxx
|
||||
lark-cli apps +db-table-list --app-id app_xxx --env dev --page-size 50
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功读取 `data.items[]`；每项字段是 `name`、`description`、`estimated_row_count`、`size_bytes`、`column_count`（列数）。CLI 默认不透出每表完整 `columns[]`（与 `+db-table-get` 重复且放大 token），只给 `column_count`；要完整列定义/索引/约束用 `+db-table-get`。
|
||||
- pretty 输出是 5 列扫描表：`name`、`description`、`estimated_row_count`、`size`、`columns`（即列数）。
|
||||
- 若响应带 `has_more=true`，用返回的 `page_token` / `next_page_token` 翻页。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
用户说“本地/开发库/调试库”时优先 `--env dev`；线上问题排查用 `--env online`。如果 dev 返回服务端错误提示未初始化，多环境入口是 [`+db-env-create`](lark-apps-db-env-create.md)。
|
||||
35
.agents/skills/lark-apps/references/lark-apps-env-pull.md
Normal file
35
.agents/skills/lark-apps/references/lark-apps-env-pull.md
Normal file
@ -0,0 +1,35 @@
|
||||
# apps +env-pull
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
|
||||
|
||||
把妙搭应用的启动期环境变量拉取到本地项目根的 `.env.local`。身份固定 `--as user`；scope `spark:app:read`。`--app-id` 必填，目标项目根默认当前工作目录（`--project-path` 可指定）。
|
||||
|
||||
## 何时别用（核心反模式）
|
||||
|
||||
**通常不需要手动跑**——脚手架的 `npm run dev` 在起本地开发时会自动后台拉取（非阻塞）。手动再跑会重复做同样的事，并把用户刚改完的 `.env.local` 临时改动覆盖掉。
|
||||
|
||||
只在这些兜底场景用：
|
||||
|
||||
- 不通过 `npm run dev` 启动（直接跑 `node` / IDE debug）。
|
||||
- `.env.local` 被改坏 / 删除，想重新同步。
|
||||
|
||||
## 行为
|
||||
|
||||
- **合并、不清空**：写入 `.env.local` 时保留你手写的内容与注释——命中的 key 替换值，新 key 追加，不整体覆盖。
|
||||
- **安全护栏**：返回的 envelope **不会回显任何 env key / value**（防止 token / 数据库凭据泄漏到日志或 CI 输出）。要看实际值请直接读 `.env.local`。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +env-pull --app-id app_xxx
|
||||
```
|
||||
|
||||
## 失败处理
|
||||
|
||||
`missing_scope`（没拿到 `spark:app:read`）时，按 lark-shared 引导 `lark-cli auth login --domain apps`。其余失败优先转述 `error.hint` / `error.message`。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-apps](../SKILL.md) — 妙搭应用全部命令 + 心智模型
|
||||
- [lark-apps-local-dev](lark-apps-local-dev.md) — 本地全栈开发端到端流程
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
@ -0,0 +1,37 @@
|
||||
# apps Git credential
|
||||
|
||||
妙搭 Git 凭证用于本地原生 `git clone/pull/push`。运行时命令事实以 `lark-cli apps +git-credential-init --help`、`+git-credential-list --help`、`+git-credential-remove --help` 为准。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
lark-cli apps +git-credential-init --app-id app_xxx
|
||||
lark-cli apps +git-credential-list
|
||||
lark-cli apps +git-credential-remove --app-id app_xxx
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- `+git-credential-init` 成功后读取 `data.repository_url`；不要展示或保存其中的凭据细节，只用于下一步 `git clone`。
|
||||
- `+git-credential-list` 返回本地记录和状态；可用来判断是否需要重新 init。
|
||||
- `+git-credential-remove` 只清本地配置；成功后告知不会删除云端应用或仓库。
|
||||
|
||||
## 行为规则
|
||||
|
||||
- `+git-credential-init` 返回 `repository_url`，并配置 URL-scoped Git credential helper。后续 clone/pull/push 使用原生 git。
|
||||
- `+git-credential-list` 列出本地已配置的妙搭 Git 凭证，不需要 `--app-id`。
|
||||
- `+git-credential-remove` 只移除本地凭证/helper，不删除云端应用或仓库。
|
||||
- 看到 Repository URL 后继续：
|
||||
|
||||
```bash
|
||||
git clone <repository_url>
|
||||
cd <repo>
|
||||
git checkout sprint/default
|
||||
```
|
||||
|
||||
## Agent 规则
|
||||
|
||||
- 不要手动打印、保存或拼接 token。
|
||||
- clone、pull、push、diff、log 等代码仓库操作都使用原生 `git`；不存在 `apps +pull` / `apps +push` / `apps code +read` 这类代码读写 shortcut，不要臆造。
|
||||
- 不要 push/force-push `main`；`main` 是发布态快照，由 `apps +release-create` 成功后服务端推进，直推/force-push 会被服务端护栏拒绝。
|
||||
- Git 认证失败、本地凭证损坏或 helper 缺失时，重新执行 `+git-credential-init --app-id <id>` 覆盖本地配置；不要让用户复制 token 到 remote URL。
|
||||
@ -0,0 +1,51 @@
|
||||
# apps +html-publish
|
||||
|
||||
把本地 HTML 文件或静态目录发布为妙搭应用访问 URL。运行时命令事实以 `lark-cli apps +html-publish --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于把已经存在的本地 HTML 文件或静态产物目录发布成妙搭访问 URL。它不负责生成 HTML 内容，也不负责全栈应用代码发布。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`、`--path`。
|
||||
- `--path` 可以是单个文件或目录；入口必须是 `index.html`。
|
||||
- 可选：`--allow-sensitive`，跳过凭据文件扫描。
|
||||
- 客户端会打包 tar.gz 并上传发布；压缩包上限当前为 20MB，未压缩候选文件总量也有保护上限。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +create --name "Demo" --app-type html
|
||||
lark-cli apps +html-publish --app-id app_xxx --path ./dist
|
||||
lark-cli apps +html-publish --app-id app_xxx --path ./index.html --dry-run
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功默认 JSON envelope 只关心 `data.url`；这是本轮 HTML 发布后的发布态访问链接。
|
||||
- pretty 输出为 `url: <url>`，适合人看；自动化取字段用 JSON 或 `--jq '.data.url'`。
|
||||
- 业务失败如构建失败、应用不存在通常带 `error.hint`；优先转述 hint。网络/服务端失败则建议稍后重试。
|
||||
|
||||
## 链接边界
|
||||
|
||||
- 开发态链接可由 `app_id` 拼出：`https://miaoda.feishu.cn/app/{app_id}`，用于进入妙搭编辑/开发态。
|
||||
- 发布态访问链接以本命令成功返回的 `data.url` 为准。
|
||||
- 重新发布前，`+list` 的 `is_published=true` 只能说明历史上发布过，不代表当前本地产物已经部署。
|
||||
|
||||
## 预览与发布边界
|
||||
|
||||
- 用户只说“用 HTML 写个 PPT/页面给我看看”时，先生成本地文件或目录，返回路径并问是否发布到妙搭分享；不要默认创建应用或部署。
|
||||
- 用户明确说“部署出去/发链接/可分享”时，才创建 `html` 应用并用 `+html-publish`。
|
||||
- 用户要发布但没有 app_id 时，先 `+create --app-type html` 创建应用；应用名可从页面/站点主题生成，不要让用户手动提供 app_id。
|
||||
- 若产物首页不是 `index.html`，发布前改名或复制为 `index.html`；目录发布时只传干净产物目录，例如 `./dist`。`.git` 目录会被自动排除，不会进入压缩包；`node_modules`、源码缓存等仍建议手动精简以控制包体。
|
||||
- 重新部署同一个 HTML 应用时复用原 `app_id`，只重新执行 `+html-publish --app-id <id> --path <dir-or-index.html>`。
|
||||
|
||||
## 安全规则
|
||||
|
||||
默认会拦截 `.env`、`.npmrc`、`.aws/credentials` 等凭据文件。只有用户明确要发布凭据示例文件或教程内容时，才追加 `--allow-sensitive`；追加前先说明将包含哪些敏感候选文件。
|
||||
|
||||
## 常见失败
|
||||
|
||||
- 缺少 `index.html`：目录根放置 `index.html`，或单文件路径直接指向名为 `index.html` 的文件。
|
||||
- 包体过大：让用户精简 `--path`，不要把源码、依赖目录、构建缓存一起发布。
|
||||
36
.agents/skills/lark-apps/references/lark-apps-init.md
Normal file
36
.agents/skills/lark-apps/references/lark-apps-init.md
Normal file
@ -0,0 +1,36 @@
|
||||
# apps +init
|
||||
|
||||
`+init` 初始化妙搭应用的代码（clone 仓库、scaffold/同步源码、拉取本地环境变量）。运行时命令事实以 `lark-cli apps +init --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于把妙搭全栈应用源码拉到本地并准备开发环境。用户只是要云端 Agent 生成应用时，不要初始化本地仓库。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`。
|
||||
- 可选：`--dir`，clone 目标目录；省略时默认 `./<app-id>`。
|
||||
- 可选：`--template`，空仓库脚手架模板；省略时当前回退 `nestjs-react-fullstack`。
|
||||
- 固定 checkout 分支：`sprint/default`。
|
||||
- `+init` 会初始化 Git 凭证、clone 仓库、切到工作分支并生成/同步本地项目。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +init --app-id app_xxx --dir ./my-app
|
||||
lark-cli apps +init --app-id app_xxx --dir /absolute/path/my-app --template nestjs-react-fullstack
|
||||
lark-cli apps +init --app-id app_xxx --dir ./my-app --dry-run
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 真跑时 stdout 是 JSON envelope；stderr 会有 `->` / `→` 进度行。成功读 stdout，失败解析 stderr 末尾的 JSON 错误。
|
||||
- 成功普通初始化读取 `data.clone_path`、`branch`、`committed`、`pushed`；`repository_url` 已脱敏，不要当凭据使用。
|
||||
- `scaffold=already_initialized` 表示目录已初始化：跳过 clone/scaffold/commit，但仍会执行一次 env-pull 刷新本地环境变量（输出含 `env_pulled`，成功时含 `env_file`，失败时含 `env_pull_error` 且退出码仍为 0）；此时通常没有 `repository_url` / `branch`。
|
||||
- `--dry-run` 只打印计划，不执行 git / npx；若输出含 `dir_error`，真跑前先让用户换目录。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
- 目标目录必须不存在、为空目录，或已含 `.spark/meta.json` 的已初始化仓库。
|
||||
- 目标目录已含 `.spark/meta.json` 时，`+init` 会跳过 clone/scaffold，但仍执行一次 env-pull 刷新本地环境变量；告知用户“仓库已初始化，本地环境变量已刷新，可直接开发”，不要误报失败或重复 clone。
|
||||
- `+init` 输出没有必要原样复述；告诉用户 clone path、分支和下一步即可。
|
||||
37
.agents/skills/lark-apps/references/lark-apps-list.md
Normal file
37
.agents/skills/lark-apps/references/lark-apps-list.md
Normal file
@ -0,0 +1,37 @@
|
||||
# apps +list
|
||||
|
||||
列出当前用户可见的妙搭应用，用于从应用名定位 `app_id`。运行时命令事实以 `lark-cli apps +list --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
在下游操作需要 `app_id`、而用户只给了应用名/描述时,用 `--keyword` 定位。无明确目的的全量枚举会浪费上下文,优先按关键词缩小范围。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 支持 `--keyword` 按应用名模糊搜索。
|
||||
- `--ownership` 枚举：`all` / `mine` / `shared`（默认 `all` = 我创建的 + 共享给我的；`mine` = 仅我创建；`shared` = 仅共享给我）。
|
||||
- `--app-type` 枚举：`html` / `full_stack`。
|
||||
- 分页：`--page-size` 默认 20，`--page-token` 传上一页 cursor。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +list --keyword "审批"
|
||||
lark-cli apps +list --ownership mine --app-type full_stack
|
||||
lark-cli apps +list --page-token "<cursor>"
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功读取 `data.items[]`；保留字段为 `description`、`app_id`、`name`、`is_published`、`online_url`、`updated_at`，用于候选展示的核心字段是 `name`、`app_id`、`updated_at`。
|
||||
- `is_published=true` 只代表应用历史上有发布版本，不代表最新云端会话、最新代码提交或最新 HTML 产物已经部署。
|
||||
- `online_url` 是当前已有发布态入口；若你没有在本轮确认发布完成，不要把它描述成“最新版本链接”。
|
||||
- 默认输出已裁掉 `icon_url`（图片 URL，agent 无法渲染）和 `created_at`（与 `updated_at` 冗余）；需要时可用 `--jq` 过滤上述保留字段。
|
||||
- `data.items` 可能为空；不要把空列表当失败。
|
||||
- 若有 `has_more=true`，用返回的 `page_token` / `next_page_token` 继续翻页。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
多候选时展示名称、app_id、updated_at 让用户确认。用户描述里已经有 `app_xxx` 或妙搭链接时，直接提取，不再 `+list`。
|
||||
|
||||
把 `+list` 当定位工具和发布态快照工具，不要把 `is_published` 当部署完成证明。需要证明“最新内容已上线”时，使用对应发布命令的完成状态：全栈看 `+release-get` 的 `finished`，HTML 看 `+html-publish` 的成功返回。
|
||||
76
.agents/skills/lark-apps/references/lark-apps-local-dev.md
Normal file
76
.agents/skills/lark-apps/references/lark-apps-local-dev.md
Normal file
@ -0,0 +1,76 @@
|
||||
# lark-apps 本地全栈开发
|
||||
|
||||
适用：用户要把妙搭全栈应用源码拉到本地，用本地 code agent/IDE 开发、调试数据库，再发布。
|
||||
|
||||
## 新建 vs 已有应用
|
||||
|
||||
新建还是修改已有，由上方入口（SKILL.md「选择开发路径」）判定；进到本地流程后按分支走：
|
||||
|
||||
- **新建**：从 `+create` 开始走下面的端到端流程。
|
||||
- **已有应用**（本地还没有源码）：跳过 `+create`，先按下方「存量应用入口」拿 `app_id`，再 `+init`（或 `+git-credential-init` + `git clone`）把它拉到本地，然后照常开发。
|
||||
|
||||
## 端到端流程（新建应用）
|
||||
|
||||
`+create(full_stack)` -> `+init`（或手动 `+git-credential-init` + `git clone`）-> `npm install && npm run dev` -> 按需 `+db-*` 调库 -> `git add` + `git commit`（提交本次改动）-> `git push origin sprint/default` -> `+release-create` -> `+release-get`。
|
||||
|
||||
```bash
|
||||
# 新建 full_stack 应用
|
||||
lark-cli apps +create --name "审批系统" --app-type full_stack \
|
||||
--description "支持登录、提交申请、多级审批、状态查询"
|
||||
|
||||
# 初始化本地仓库（--dir 取值见下方「领域规则」，勿照抄此处示例值）
|
||||
lark-cli apps +init --app-id app_xxx --dir ./approval-app
|
||||
|
||||
# 进入仓库后按项目脚手架启动
|
||||
cd ./approval-app
|
||||
npm install
|
||||
npm run dev
|
||||
|
||||
# 开发完成后：提交本次改动 -> git push origin sprint/default -> +release-create。
|
||||
# +release-create 部署的是远端 sprint/default 上已 push 的代码，不是本地工作区——没 commit + push 的改动不会进入发布。
|
||||
git add <本次开发的文件> # 提交粒度见下方「改完代码后部署上线」
|
||||
git commit -m "feat: ..."
|
||||
git push origin sprint/default
|
||||
lark-cli apps +release-create --app-id app_xxx
|
||||
```
|
||||
|
||||
`+init` 是推荐便捷入口；想逐步手动控制时，先 `+git-credential-init` 拿 `repository_url`，再用原生 `git clone` / `git checkout sprint/default`。
|
||||
|
||||
## 改完代码后部署上线
|
||||
|
||||
已拉到本地、改完代码，用户说"推上去""部署""上线""发布到云端"时，按此序列。
|
||||
|
||||
> `+release-create` 部署的是远端 `sprint/default` 上**已 push** 的代码，不是你本地工作区——未 commit / 未 push 的改动不会进入这次发布。所以发布前务必先把本次改动提交并推送。
|
||||
|
||||
1. `git status` 看本次改动；`git add <本次相关文件>` 暂存后 `git commit` 提交。只提交本次任务相关的改动即可，无关的零散文件不必强求清空——发布门禁是「**本次相关改动已提交并推送**」，不是「工作区绝对干净」。
|
||||
2. `git push origin sprint/default` 把工作分支推到云端（遇非 fast-forward：先 `git pull --rebase origin sprint/default` 解决冲突再推，绝不 force-push）。
|
||||
3. `lark-cli apps +release-create --app-id <app_id>` 发起部署上线，记下返回的 `release_id`。
|
||||
4. `lark-cli apps +release-get --app-id <app_id> --release-id <release_id>` 轮询：`publishing` 继续轮询；`finished` 成功时该命令输出已含 `online_url`，直接读取它返回给用户（这是本轮发布完成后的可分享链接），无需再调 `+list`；`failed` 时该命令输出已含 `error_logs`，直接据此给出失败原因（`+list` 仅作独立查询入口）。
|
||||
|
||||
## 领域规则
|
||||
|
||||
- 代码读写走原生 `git`；CLI 负责凭证、初始化、发布和数据库调试。不存在 `apps +pull` / `apps +push` / `apps code +read` 这类代码读写 shortcut，不要臆造。
|
||||
- `+init` 会编排 `+git-credential-init`、`git clone`、切到 `sprint/default`、运行脚手架，并在有变更时提交/推送。
|
||||
- `+init --dir` 选目录：用户已预授权或表达"不要询问"（见 SKILL.md「预授权判定」）→ 按应用名派生 `./<app-name>` 直接传 `--dir`、不停问；否则先问用户用哪个目录再传。目标已存在/非空时回问换目录。
|
||||
- `sprint/default` 是工作分支；`main` 是发布态快照，由 `+release-create` 成功后服务端 fast-forward 推进；服务端护栏禁直推 `main`、拒 force-push、要求 `sprint/default` fast-forward。
|
||||
- 已拉到本地后，pull/push/diff/log 都用原生 git；云端 `sprint/default` 比本地新时，先 `git pull --rebase origin sprint/default`，解决冲突后再 push 和 publish。
|
||||
- 环境变量由脚手架在本地启动时处理；需要手动刷新时用 `+env-pull`。
|
||||
- DB 调试用 `+db-table-list` / `+db-table-get` / `+db-execute`；不要裸连数据库或自行拼连接串。
|
||||
- DB 分 `dev` / `online`；日常调试优先 `--env dev`。dev 的库结构变更要上线时，仍按应用发布链路走 `+release-create`，不要另造“数据库发布”步骤。
|
||||
- 存量单库应用需要 dev/online 多环境时，用 `+db-env-create --env dev`。这是不可逆 high-risk 操作。
|
||||
- 只从 `+list` 看到 `is_published=true`，不能证明本地刚推送的代码已经部署；必须有本轮 `+release-get finished`。
|
||||
|
||||
## 存量应用入口
|
||||
|
||||
已有项目目录先读 `.spark/meta.json` 取 `app_id`；没有本地项目但知道应用名时用：
|
||||
|
||||
```bash
|
||||
lark-cli apps +list --keyword "应用名"
|
||||
```
|
||||
|
||||
拿到 `app_id` 后再 `+init` 或 `+git-credential-init`。
|
||||
|
||||
## 何时不用
|
||||
|
||||
- 用户只想发布现成 HTML / 静态目录拿分享链接：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
|
||||
- 用户明确要云端妙搭 Agent 生成/迭代，而不是本地写代码：读 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md)。
|
||||
@ -0,0 +1,30 @@
|
||||
# apps +release-create
|
||||
|
||||
为妙搭应用创建发布 release。运行时命令事实以 `lark-cli apps +release-create --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于把全栈应用的代码分支推进到发布流程。它不是 HTML 静态发布入口；本地 `index.html` / `dist` 要读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`。
|
||||
- 可选：`--branch`；省略时服务端使用默认发布分支。
|
||||
- 返回 `release_id` 和 `status`，后续用 `+release-get` 轮询。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +release-create --app-id app_xxx
|
||||
lark-cli apps +release-create --app-id app_xxx --branch sprint/default --dry-run
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功读取 `data.release_id` 和 `data.status`；`release_id` 是后续 `+release-get` 的入参。
|
||||
- `status=publishing` 表示发布仍在进行；继续用 `+release-get` 轮询。
|
||||
- `+release-create` 返回 release 只代表发布已发起。只有 `+release-get` 对同一个 `release_id` 返回 `finished` 后，才能说本轮最新版本已部署。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
`+release-create` 部署的是远端 `sprint/default` 上已 push 的代码，不是本地工作区——本地若有你修改但未推送的改动，需要先 `git add` + `git commit` 并 `git push` 到 `sprint/default`，否则这些改动不会进入这次发布。发布后若 status 是 `publishing`，用 [`+release-get`](lark-apps-release-get.md) 查询。`+release-create` 部署上线属高影响动作——作为别的命令的连带前置时，按 SKILL.md「高影响动作：确认与预授权」先征得用户同意再发布。
|
||||
28
.agents/skills/lark-apps/references/lark-apps-release-get.md
Normal file
28
.agents/skills/lark-apps/references/lark-apps-release-get.md
Normal file
@ -0,0 +1,28 @@
|
||||
# apps +release-get
|
||||
|
||||
按 release ID 查询单次发布详情。运行时命令事实以 `lark-cli apps +release-get --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用于跟进已知 `release_id` 的发布状态。没有 `release_id` 时先读 [`lark-apps-release-list.md`](lark-apps-release-list.md)，不要让用户手填。
|
||||
|
||||
`release_id` 是妙搭发布 ID（`+release-create` 返回），不是飞书审批实例号；查发布进度/失败都在 `apps +release-*` 命令族内完成，不要路由到 lark-approval。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`、`--release-id`。
|
||||
- `release_id` 来自 `+release-create` 或 `+release-list`。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +release-get --app-id app_xxx --release-id release_yyy
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功可能直接返回 release 字段，也可能包在 `data.release`；读取 `release_id`、`status`、`created_at`、`updated_at`，以及 `commit_id`（本轮发布对应的 git commit SHA，pretty 输出在其非空时展示一行）。
|
||||
- `status=publishing` 继续轮询。此时尚无 `online_url`；不要拿其它链接（如 `+list` 里的应用主页 / 开发态预览 URL）冒充"本轮发布的访问链接"——只回报 `release_id`、`status`，并说明 `finished` 后才有 `online_url`。
|
||||
- `status=finished` 发布成功——**本命令输出已含 `online_url`，直接读取它作为本轮发布的线上访问链接**返回用户，无需再调 `+list`（`+list` 仍可用于按应用名浏览，但不是发布主流程的必经步骤）。
|
||||
- `status=failed` 发布失败——**本命令输出已含 `error_logs`（`step`/`error_log`），直接据此向用户转述关键失败步骤和可行动修复**。
|
||||
- 只有当这个 `release_id` 已返回 `finished`，随后读到的 `online_url` 才能被表述为"本轮发布后的访问链接"。单独从 `+list` 看到 `is_published=true` 不能证明最新版本已部署。
|
||||
@ -0,0 +1,31 @@
|
||||
# apps +release-list
|
||||
|
||||
分页查询妙搭应用发布历史，最新发布在前。运行时命令事实以 `lark-cli apps +release-list --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
用户问"最近发布""历史版本""上次为什么失败"，但没有提供 `release_id` 时使用。拿到候选 release 后再接 `+release-get`。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`。
|
||||
- 可选 `--status`：`publishing` / `finished` / `failed`。
|
||||
- 可选 `--page-size`：默认 20，最大 500；总是发送给服务端。
|
||||
- 可选 `--page-token`：上一页 cursor。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +release-list --app-id app_xxx --page-size 10
|
||||
lark-cli apps +release-list --app-id app_xxx --status failed
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功读取 `data.releases[]`；关键字段是 `release_id`、`status`、`created_at`、`updated_at`。
|
||||
- `release_id` 用于继续查 `+release-get`。
|
||||
- 若 `has_more=true`，用 `next_page_token` / `page_token` 翻页。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
用户限定只看 N 条（"最近 N 条""最新 N 个""只要前 N 条"）时用 `--page-size N`（如"最近一次发布"→ `--page-size 1`），而不是取全量再本地截断。
|
||||
30
.agents/skills/lark-apps/references/lark-apps-update.md
Normal file
30
.agents/skills/lark-apps/references/lark-apps-update.md
Normal file
@ -0,0 +1,30 @@
|
||||
# apps +update
|
||||
|
||||
部分更新妙搭应用元信息。运行时命令事实以 `lark-cli apps +update --help` 为准。
|
||||
|
||||
## 何时用
|
||||
|
||||
只更新应用展示元信息。用户要改代码、发布内容、可见范围或数据库时，不走 `+update`。
|
||||
|
||||
## 命令骨架
|
||||
|
||||
- 必填：`--app-id`。
|
||||
- 至少提供一个：`--name` 或 `--description`。
|
||||
- 只发送用户提供的字段，不会清空未提供字段。
|
||||
|
||||
## 示例
|
||||
|
||||
```bash
|
||||
lark-cli apps +update --app-id app_xxx --name "审批系统"
|
||||
lark-cli apps +update --app-id app_xxx --description "用于部门审批流转"
|
||||
lark-cli apps +update --app-id app_xxx --name "审批系统" --description "用于部门审批流转" --dry-run
|
||||
```
|
||||
|
||||
## 输出契约
|
||||
|
||||
- 成功读取 `data.app`；响应是完整应用对象，不只是被修改字段。
|
||||
- 缺 `--app-id` 或没有提供 `--name` / `--description` 会在本地 validation 失败。
|
||||
|
||||
## Agent 规则
|
||||
|
||||
更新前复述要变更的字段；用户没有提到的字段不要补默认值。执行后只转述新的名称/描述和 app_id，不需要展开原始响应。
|
||||
57
.agents/skills/lark-attendance/SKILL.md
Normal file
57
.agents/skills/lark-attendance/SKILL.md
Normal file
@ -0,0 +1,57 @@
|
||||
---
|
||||
name: lark-attendance
|
||||
version: 1.0.0
|
||||
description: "飞书考勤打卡：查询自己的考勤打卡记录"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli attendance --help"
|
||||
---
|
||||
|
||||
# attendance (v1)
|
||||
|
||||
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
|
||||
|
||||
## 默认参数自动填充规则
|
||||
|
||||
调用任何 API 时，以下参数 **必须自动填充，禁止向用户询问**：
|
||||
|
||||
| 参数 | 固定值 | 说明 |
|
||||
|------|--------|------------------------------------|
|
||||
| `employee_type` | `"employee_no"` | `employee_type`始终等于`"employee_no"` |
|
||||
| `user_ids` | `[]`（空数组） | `user_ids`始终等于`[]` |
|
||||
|
||||
### 填充示例
|
||||
|
||||
当构建 `--params` 参数时，自动注入上述字段：
|
||||
- `employee_type` 保持 `"employee_no"` 不变
|
||||
|
||||
当构建 `--data` 参数时，自动注入上述字段：
|
||||
```json
|
||||
{
|
||||
"user_ids": [],
|
||||
...用户提供的参数
|
||||
}
|
||||
```
|
||||
|
||||
> **注意**：`user_ids` 数组保持为空[]，`employee_type` 保持 `"employee_no"` 不变。
|
||||
|
||||
## API Resources
|
||||
|
||||
```bash
|
||||
lark-cli schema attendance.<resource>.<method> # 调用 API 前必须先查看参数结构
|
||||
lark-cli attendance <resource> <method> [flags] # 调用 API
|
||||
```
|
||||
|
||||
> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
|
||||
|
||||
### user_tasks
|
||||
|
||||
- `query` — 查询用户考勤打卡记录
|
||||
|
||||
## 权限表
|
||||
|
||||
| 方法 | 所需 scope |
|
||||
|------|-----------|
|
||||
| `user_tasks.query` | `attendance:task:readonly` |
|
||||
|
||||
166
.agents/skills/lark-base/SKILL.md
Normal file
166
.agents/skills/lark-base/SKILL.md
Normal file
@ -0,0 +1,166 @@
|
||||
---
|
||||
name: lark-base
|
||||
version: 1.2.2
|
||||
description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli base --help"
|
||||
---
|
||||
|
||||
# base
|
||||
|
||||
## 何时使用
|
||||
|
||||
使用本 skill：
|
||||
|
||||
- 用户明确提到 Base / 多维表格 / bitable，或给出 `/base/` 链接。
|
||||
- 用户要在 Base 内建表、改表、管理字段、写记录、查记录、配视图。
|
||||
- 用户要在 Base 内做公式字段、lookup 字段、跨表计算、派生指标、筛选聚合、TopN、统计分析。
|
||||
- 用户要管理 Base 表单、仪表盘、workflow、高级权限或角色。
|
||||
- 用户要把旧 Base 聚合式命令或旧写法迁移到当前 `lark-cli base +...` shortcut。
|
||||
|
||||
不要使用本 skill：
|
||||
|
||||
- 只是认证、初始化配置、切换身份、处理 scope 或权限授权恢复，转 `lark-shared`。
|
||||
- 把本地 Excel / CSV / `.base` 导入成 Base，转 `lark-drive +import --type bitable`。
|
||||
- 泛化数据分析、字段设计、公式讨论，但没有 Base/多维表格上下文。
|
||||
|
||||
## 使用边界
|
||||
|
||||
- Base 业务操作只使用 `lark-cli base +...` shortcut，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。
|
||||
- 本轮 Base 不依赖 `lark-cli schema`。SKILL 只保留路由、风险和复杂 JSON/DSL；简单命令由命令自身的参数、tips 和错误恢复承接。
|
||||
- 用户要把 Excel / CSV / `.base` 导入成 Base 时，先转 `lark-cli drive +import --type bitable`，导入完成后再回到 Base 命令。
|
||||
- 用户只给 Base 名称或关键词时，先用 `lark-cli drive +search --query <keyword> --doc-types bitable` 定位资源。
|
||||
- Base 命令必须先有 `base_token` 或可解析出的 Base URL。没有 token 时：用户要新建就用 `+base-create`；用户给标题/关键词就搜 `lark-cli drive +search --query "<base title>" --doc-types bitable --only-title --as user`；仍无法定位时，反问用户具体是哪一个 Base。
|
||||
- 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`；Base 文档只保留会影响 Base 路径选择的权限规则。
|
||||
|
||||
## 快速路由
|
||||
|
||||
| 用户目标 | 优先命令 | 何时读 reference |
|
||||
|---|---|---|
|
||||
| 查 Base 本体 | `+base-get` | 用返回确认 Base 名称、owner、权限和可继续操作的 token |
|
||||
| 创建/复制 Base | `+base-create` / `+base-copy` | 新建时强烈推荐用 `--table-name` + `--fields` 同时配置新 Base 里唯一一个初始数据表的 name 和 schema；写入后报告新 Base 标识和 `permission_grant` |
|
||||
| 查看 Base 内资源目录 | `+base-block-list` | 想先了解一个 Base 里有哪些 table/docx/dashboard/workflow/folder 时优先用它；返回 ID 关系和 fewshot 看 `--help` |
|
||||
| 管理 Base 内资源目录 | `+base-block-create/move/rename/delete` | 创建或整理 Base 直接管理的 folder/table/docx/dashboard/workflow；资源内容继续用对应命令 |
|
||||
| 管理数据表 | `+table-list/get/create/update/delete` | 处理 table 的列出、详情、创建、重命名和删除 |
|
||||
| 列/查/删字段 | `+field-list/get/delete/search-options` | 写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段 |
|
||||
| 创建/更新字段 | `+field-create` / `+field-update` | 必读 [lark-base-field-json.md](references/lark-base-field-json.md)；公式读 [formula-field-guide.md](references/formula-field-guide.md)；lookup 读 [lookup-field-guide.md](references/lookup-field-guide.md)；命令细节读 [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md) |
|
||||
| 读记录明细 | `+record-get` / `+record-list` / `+record-search` | 涉及筛选、排序、Top/Bottom N、聚合、多表关联、全局结论时读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) |
|
||||
| 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读 [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) 和 [lark-base-cell-value.md](references/lark-base-cell-value.md) |
|
||||
| 附件字段 | `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` | 附件不要伪造成普通 CellValue；上传走本地文件，下载/删除按 file token 或字段定位 |
|
||||
| 删除记录 / 分享记录链接 / 历史 | `+record-delete` / `+record-share-link-create` / `+record-history-list` | 删除前确认 record；分享链接最多 100 条；历史读 [lark-base-record-history-list.md](references/lark-base-record-history-list.md)，只查单条记录，不做整表审计 |
|
||||
| 管理视图 | `+view-*` | `+view-set-filter` 读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)；其余配置先 get 现状，再按返回结构更新 |
|
||||
| 一次性聚合统计 | `+data-query` | 必读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) 和入口 [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md)；完整 DSL 再读 [lark-base-data-query.md](references/lark-base-data-query.md) |
|
||||
| 公式字段 | `+field-create/update --json '{"type":"formula",...}'` | 必读 [formula-field-guide.md](references/formula-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
|
||||
| Lookup 字段 | `+field-create/update --json '{"type":"lookup",...}'` | 必读 [lookup-field-guide.md](references/lookup-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
|
||||
| 表单提交 | `+form-submit` | 先读 [lark-base-form-detail.md](references/lark-base-form-detail.md) 获取题目、filter 和附件所需 `base_token`；提交 JSON 读 [lark-base-form-submit.md](references/lark-base-form-submit.md) |
|
||||
| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md) |
|
||||
| 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 [lark-base-form-detail.md](references/lark-base-form-detail.md)；删除前确认目标表单 |
|
||||
| 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md)；组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)；读取图表计算结果用 `+dashboard-block-get-data` |
|
||||
| Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；list/get/enable/disable 只处理 workflow ID 与启停状态 |
|
||||
| 高级权限与角色 | `+advperm-*` / `+role-*` | 角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；角色 create/update 或解读完整配置再读权限 JSON SSOT [role-config.md](references/role-config.md)；系统角色不可删除；关闭高级权限会影响自定义角色 |
|
||||
|
||||
## Base 心智模型
|
||||
|
||||
- Base 曾用名 Bitable；返回字段、错误或旧文档里的 `bitable` 多为历史兼容，不代表应改走裸 API 或另一套命令。
|
||||
- `+base-block-list` 是查看一个 Base 内资源目录的新入口：它列出这个 Base 直接管理的 `folder/table/docx/dashboard/workflow`，适合先判断 Base 里有什么，再决定走 table、dashboard、workflow 或 docx 命令。
|
||||
- `base-block` 只负责资源目录管理，包括创建资源、移动到 folder、重命名和删除；具体资源内容仍走 table/dashboard/workflow 命令。
|
||||
- 新建 Base 时，强烈推荐一次性执行 `lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>'`，同时配置新 Base 里唯一一个初始数据表的 name 和 schema；使用 `--fields` 前先读 [lark-base-field-json.md](references/lark-base-field-json.md) 或复用 `+field-create` 的字段 JSON 形状，不要猜字段属性。
|
||||
- `+base-create` 不传 `--table-name` 和 `--fields` 时，会创建一个默认 schema 的初始数据表。
|
||||
- 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回，不要凭用户口述猜。
|
||||
- 存储字段可写；系统字段、`formula`、`lookup` 只读；附件字段走专用 attachment 命令。
|
||||
- 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`；需要长期显示在表中时，才新增 `formula` / `lookup` 字段。
|
||||
- `formula` 适合常规计算、条件判断、文本/日期处理和长期派生指标；`lookup` 适合明确的跨表查找、筛选后取值或聚合引用。
|
||||
- 写入、分析、公式、lookup、workflow、dashboard 前，先读取真实结构：表、字段、视图、关联表和 dashboard block 名称都以命令返回为准。
|
||||
- 跨表场景必须读取目标表结构；link 单元格中的关联 `record_id` 只是连接键，最终回答要回查并展示用户可读字段。
|
||||
|
||||
## 身份与权限降级
|
||||
|
||||
- 默认显式使用 `--as user` 操作用户资源；只有用户明确要求应用身份时，才直接用 `--as bot`。
|
||||
- user 身份报 scope/授权不足，或错误中包含 `permission_violations` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
|
||||
- user 身份报资源级无访问且无授权恢复提示时，才可用 `--as bot` 重试一次；bot 仍失败就停止重试并按权限错误处理。
|
||||
- `91403` 或明确不可访问错误不要循环换身份重试。
|
||||
- `+base-create` / `+base-copy` 若用 bot 身份执行，关注返回中的 `permission_grant`，并把用户是否可打开新 Base 告知用户。
|
||||
|
||||
## 查询与统计规则
|
||||
|
||||
涉及查询、统计或判断结论时，先阅读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)，并遵守：
|
||||
|
||||
1. `+record-list` 的默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实，不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。
|
||||
2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制，应在 Base 云端查询能力中执行；不要先拉原始记录到本地上下文再手工筛选排序。
|
||||
3. `has_more=true` 或等价分页信号表示当前结果不是全量；除非用户只要样例/前 N 条，不能基于该页回答全局问题。
|
||||
4. 多表查询必须先确认关系字段和连接键；link 单元格里的 `record_id` 是关系键，不是用户可读答案。
|
||||
5. 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。
|
||||
6. 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`；要把结果长期显示在表里，才考虑新增 `formula` / `lookup` 字段。
|
||||
7. `+data-query` 可返回聚合结果或维度字段行，但维度行按字段组合去重且不返回 `record_id`；需要逐条记录、记录定位或完整行级字段时，再用 `+record-list` / `+record-search` / `+record-get` 回查。
|
||||
|
||||
## 写入前置规则
|
||||
|
||||
- 写记录前先读字段结构；只写存储字段。系统字段、附件字段、`formula`、`lookup` 不作为普通记录写入目标。
|
||||
- 附件上传、下载、删除走专用 `+record-*-attachment` 命令。
|
||||
- 写字段前先读 [lark-base-field-json.md](references/lark-base-field-json.md)；涉及 `formula` / `lookup` 时必须读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)。
|
||||
- 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
|
||||
- 删除、角色更新、字段更新等高风险操作遵循 CLI 的 confirmation gate；目标不明确时先用 get/list 消歧。
|
||||
- 批量写入单批最多 200 条；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
|
||||
- `+record-batch-update` 是“同值批量更新”：同一份 patch 应用到全部 `record_id_list`，不要拿它做逐行不同值映射。
|
||||
- select/multiselect 写入未知选项可能触发平台新增选项；不是要新增时，先用 `+field-list` 或 `+field-search-options` 确认可选值。
|
||||
|
||||
## 表单与视图细节
|
||||
|
||||
- `+form-submit` 前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
|
||||
- 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。
|
||||
- `+view-set-filter` 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。
|
||||
- 视图适合持久化、共享和 UI 复用；一次性筛选/排序可先用 `+record-list` / `+record-search` 的 filter/sort 验证结果，再按需要沉淀为持久视图。
|
||||
|
||||
## Token 与链接
|
||||
|
||||
| 输入类型 | 含义 / 正确处理方式 |
|
||||
|---|---|
|
||||
| `/base/{token}` | 普通 Base 链接；提取 `/base/` 后的 token 作为 `--base-token` |
|
||||
| `/wiki/{token}` | Wiki 节点链接；先 `wiki +node-get`，当 `data.obj_type=bitable` 时使用 `data.obj_token` 作为 `--base-token` |
|
||||
| `/base/{token}?table={id}` | `table` 参数用于定位 Base 内对象：`tbl` 开头是数据表 `--table-id`；`blk` 开头是 dashboard ID；`wkf` 开头是 workflow ID |
|
||||
| `/base/{token}?view={id}` | `view` 参数用于定位表视图，提取为 `--view-id`；通常还需要确认 `table` 参数或先查表结构 |
|
||||
| `/share/base/form/{shareToken}` | 表单分享链接；这是表单 share token，走 `+form-detail` / `+form-submit --share-token <shareToken>` |
|
||||
| `/share/base/view/{shareToken}` | 视图分享链接；具有分享权限语义，暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开 |
|
||||
| `/share/base/dashboard/{shareToken}` | 仪表盘分享链接；具有分享权限语义，暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开 |
|
||||
| `/record/{shareToken}` | 记录分享链接；暂不支持用 CLI 直接访问，引导用户在浏览器或飞书客户端打开。若用户想生成现有记录的分享链接，用 `+record-share-link-create --base-token <base_token> --table-id <table_id> --record-ids <record_id>` |
|
||||
| `/base/workspace/{token}` | BaseApp / workspace 链接；暂不支持用 CLI 直接访问 |
|
||||
|
||||
`wiki +node-get` 返回非 `bitable` 时，不继续使用 Base 命令：`docx` 转文档，`sheet` 转表格，其他云空间对象转对应 skill 或 drive。
|
||||
|
||||
## Dashboard / Workflow / Role
|
||||
|
||||
- Dashboard 的复杂点是 block 的 `data_config`，不是 list/get/create/delete 命令参数。创建或更新 block 前先读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)，组件必须串行创建；`+dashboard-arrange` 是服务端智能布局，只在用户明确要求重排/美化时执行。`+dashboard-block-get-data` 读取图表最终计算结果，不返回 block 名称、类型、布局或 `data_config`；需要元数据先用 `+dashboard-block-get`。
|
||||
- Workflow 的复杂点是 `steps` 结构。创建、更新或解释完整 workflow 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；enable/disable/list 只需确认 workflow ID、当前启停状态和用户意图。
|
||||
- Role 的复杂点是权限 JSON。角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；`+role-create` 只支持自定义角色；`+role-update` 是 delta merge；角色 create/update 或解读完整配置时读权限 JSON SSOT [role-config.md](references/role-config.md)。`+role-delete` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
|
||||
|
||||
## 常见恢复
|
||||
|
||||
| 错误 / 现象 | 恢复动作 |
|
||||
|---|---|
|
||||
| `param baseToken is invalid` / `base_token invalid` | 检查是否把 wiki token、workspace token 或完整 URL 当成了 `--base-token`；按 `Token 与链接` 重新定位真实 Base token |
|
||||
| `not found` 且输入来自 Wiki 链接 | 优先检查是否把 wiki token 当成 base token，不要立刻改走裸 API |
|
||||
| `1254045` 字段名不存在 | 重新 `+field-list`，使用真实字段名或字段 ID；注意空格、大小写和跨表字段 |
|
||||
| `1254015` 字段值类型不匹配 | 先 `+field-list`，再按 [lark-base-cell-value.md](references/lark-base-cell-value.md) 构造 CellValue |
|
||||
| 日期 / 人员 / 超链接字段报格式错误 | 日期用 `YYYY-MM-DD HH:mm:ss`；人员用 `[{ "id": "ou_xxx" }]`；超链接用 URL 或 markdown link 字符串 |
|
||||
| formula / lookup 创建失败 | 先读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)，再按 guide 重建请求 |
|
||||
| `ignored_fields` / `READONLY` | 移除只读字段，只写存储字段 |
|
||||
| `1254104` | 批量超过 200，分批调用 |
|
||||
| `1254291` | 并发写冲突，串行写入并在批次间短暂等待 |
|
||||
| `91403` | 无权限访问该 Base，按 `lark-shared` 权限流程处理，不要盲目重试 |
|
||||
|
||||
## 保留 Reference
|
||||
|
||||
- [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)：查询/统计/全局结论的选路 SOP
|
||||
- [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md)：聚合查询入口 fewshot 与 DSL SSOT
|
||||
- [lark-base-cell-value.md](references/lark-base-cell-value.md)：记录 CellValue 构造
|
||||
- [lark-base-field-json.md](references/lark-base-field-json.md)：字段 JSON 构造
|
||||
- [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)：公式与 lookup 字段
|
||||
- [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md)：字段创建/更新命令级补充
|
||||
- [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) / [lark-base-record-history-list.md](references/lark-base-record-history-list.md)：记录写入 JSON 与历史返回解释
|
||||
- [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)：视图筛选 JSON
|
||||
- [lark-base-form-detail.md](references/lark-base-form-detail.md) / [lark-base-form-submit.md](references/lark-base-form-submit.md) / [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)：表单详情、提交和复杂 JSON
|
||||
- [lark-base-dashboard.md](references/lark-base-dashboard.md) / [dashboard-block-data-config.md](references/dashboard-block-data-config.md) / [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md)：仪表盘、组件配置与图表结果协议
|
||||
- [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)：workflow 入口与 steps JSON SSOT
|
||||
- [lark-base-role-guide.md](references/lark-base-role-guide.md) / [role-config.md](references/role-config.md)：角色入口与权限 JSON SSOT
|
||||
@ -0,0 +1,350 @@
|
||||
# dashboard block data_config SSOT
|
||||
|
||||
Block 的 `data_config` 字段因 `type` 不同而变化。本文档是 dashboard block `data_config` 的单一事实来源（SSOT），包含组件类型、字段结构、筛选格式、约束和可复制模板。
|
||||
|
||||
## 支持的组件类型（`type` 枚举）
|
||||
|
||||
| type 值 | 说明 |
|
||||
|---------|------|
|
||||
| `column` | 柱状图 |
|
||||
| `bar` | 条形图 |
|
||||
| `line` | 折线图 |
|
||||
| `pie` | 饼图 |
|
||||
| `ring` | 环形图 |
|
||||
| `area` | 面积图 |
|
||||
| `combo` | 组合图 |
|
||||
| `scatter` | 散点图 |
|
||||
| `funnel` | 漏斗图 |
|
||||
| `wordCloud` | 词云 |
|
||||
| `radar` | 雷达图 |
|
||||
| `statistics` | 指标卡 |
|
||||
| `text` | 文本（支持 Markdown） |
|
||||
|
||||
## 字段类型与操作符速查（AI 决策用）
|
||||
|
||||
> 先用 `+field-list` / `+field-get` 确认字段 `type`；本节使用当前字段接口里的 canonical 类型名：`number`、`text`、`select`、`datetime`、`checkbox`、`user`。
|
||||
|
||||
```
|
||||
text: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
|
||||
number: is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty
|
||||
select（multiple=false）: is, isNot, isEmpty, isNotEmpty
|
||||
select（multiple=true）: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
|
||||
datetime: is, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty
|
||||
checkbox: is (value: true/false)
|
||||
user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
|
||||
```
|
||||
|
||||
## data_config 通用结构
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `table_name` | string | 关联数据表名称 |
|
||||
| `series` | `[{ "field_name": "xxx", "rollup": "SUM" }]` | 指标/Y 轴（与 `count_all` 二选一）。rollup 支持 `SUM` / `MAX` / `MIN` / `AVERAGE` |
|
||||
| `count_all` | boolean | COUNTA 聚合，统计所有记录数（与 `series` 二选一） |
|
||||
| `group_by` | `[{ "field_name": "xxx", "mode": "integrated", "sort": {...} }]` | X 轴分组维度。`mode` 必填，`sort` 可选，见下方说明 |
|
||||
| `filter` | object | 筛选条件 |
|
||||
| `filter.conjunction` | `"and"` / `"or"` | 筛选逻辑 |
|
||||
| `filter.conditions` | `[{ "field_name", "operator", "value" }]` | 筛选条件数组，value 类型因字段类型而异（见下方 filter 格式规则） |
|
||||
|
||||
### text 类型特殊结构
|
||||
|
||||
`text` 类型组件用于展示富文本内容，**不需要数据源配置**（无 `table_name`、`series`、`group_by`、`filter`）。
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `text` | string | **必填**。支持 Markdown 语法，详见下方说明 |
|
||||
|
||||
**支持的 Markdown 语法：**
|
||||
|
||||
| 语法 | 示例 | 效果 |
|
||||
|------|------|------|
|
||||
| 一级标题 | `# 标题` | 大标题 |
|
||||
| 二级标题 | `## 标题` | 中标题 |
|
||||
| 三级标题 | `### 标题` | 小标题 |
|
||||
| 加粗 | `**文字**` | **文字** |
|
||||
| 斜体 | `*文字*` | *文字* |
|
||||
| 删除线 | `~~文字~~` | ~~文字~~ |
|
||||
| 有序列表 | `1. 项目` | 1. 项目 |
|
||||
| 无序列表 | `- 项目` | - 项目 |
|
||||
|
||||
> **注意**：以上未提及的 Markdown 语法（如链接、图片、代码块、表格等）均不支持。
|
||||
|
||||
## group_by 详细说明
|
||||
|
||||
### mode 枚举
|
||||
|
||||
| mode | 含义 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| `integrated` | 聚合分组（默认） | 绝大部分场景，按字段值分组统计 |
|
||||
| `enumerated` | 多值拆分统计 | 多选、人员等多值字段，将每个选项/人员拆开独立统计 |
|
||||
|
||||
> 多选、人员等多值字段默认用 `enumerated`；其他字段默认用 `integrated`。
|
||||
|
||||
### sort 排序
|
||||
|
||||
| sort.type | 含义 | 典型场景 |
|
||||
|-----------|------|----------|
|
||||
| `group` | 按横轴值排序 | 按月份升序、按品类名字母序 |
|
||||
| `value` | 按纵轴值排序 | 按销售额从大到小 |
|
||||
| `view` | 按数据源记录顺序 | 保持原表行序（不常用） |
|
||||
|
||||
`sort.order`：`asc`（升序）/ `desc`（降序）
|
||||
|
||||
示例 — 柱状图按销售额降序：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "订单表",
|
||||
"series": [{ "field_name": "金额", "rollup": "SUM" }],
|
||||
"group_by": [{ "field_name": "类别", "mode": "integrated", "sort": {"type": "value", "order": "desc"} }]
|
||||
}
|
||||
```
|
||||
|
||||
## filter 格式规则
|
||||
|
||||
**基本结构：**
|
||||
|
||||
```json
|
||||
{
|
||||
"filter": {
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{ "field_name": "字段名", "operator": "操作符", "value": "值" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**多条件示例（and/or）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"filter": {
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{ "field_name": "状态", "operator": "is", "value": "已完成" },
|
||||
{ "field_name": "金额", "operator": "isGreater", "value": 1000 }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**操作符：**
|
||||
|
||||
| 操作符 | 含义 | 是否需要 value |
|
||||
|--------|------|---------------|
|
||||
| `is` | 等于 | 是 |
|
||||
| `isNot` | 不等于 | 是 |
|
||||
| `contains` | 包含 | 是 |
|
||||
| `doesNotContain` | 不包含 | 是 |
|
||||
| `isEmpty` | 为空 | 否 |
|
||||
| `isNotEmpty` | 不为空 | 否 |
|
||||
| `isGreater` | 大于 | 是 |
|
||||
| `isGreaterEqual` | 大于等于 | 是 |
|
||||
| `isLess` | 小于 | 是 |
|
||||
| `isLessEqual` | 小于等于 | 是 |
|
||||
|
||||
**各字段类型的 value 格式：**
|
||||
|
||||
| 字段类型 | value 类型 | 适用操作符 | 示例 |
|
||||
|----------|-----------|-----------|------|
|
||||
| `text` | string | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | `{"field_name":"姓名","operator":"contains","value":"张"}` |
|
||||
| `number` | number | is, isNot, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | `{"field_name":"金额","operator":"isGreater","value":0}` |
|
||||
| `select` (`multiple=false`) | string（选项名） | is, isNot, isEmpty, isNotEmpty | `{"field_name":"状态","operator":"is","value":"已完成"}` |
|
||||
| `select` (`multiple=true`) | string[]（选多个）/ string（选单个） | is, isNot, contains, doesNotContain, isEmpty, isNotEmpty | 多选传数组如 `["标签1","标签2"]`；单选传单个字符串 |
|
||||
| `datetime` / `created_at` / `updated_at` | number（Unix 毫秒时间戳，13位） | is, isGreater, isGreaterEqual, isLess, isLessEqual, isEmpty, isNotEmpty | `{"field_name":"创建日期","operator":"isGreater","value":1704038400000}` |
|
||||
| `checkbox` | boolean | is | `{"field_name":"已审核","operator":"is","value":true}` |
|
||||
| `user` / `created_by` / `updated_by` | string 或 string[]（用户 ID，格式 `ou_xxx`）。不知道 `open_id` 时先用 `lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user` 查 id。 | is, isNot, isEmpty, isNotEmpty | `{"field_name":"负责人","operator":"is","value":"ou_xxxxxxxxxxxxxxxx"}` |
|
||||
| 所有类型（为空/不为空） | 不需要 value | isEmpty, isNotEmpty | `{"field_name":"备注","operator":"isEmpty"}` |
|
||||
|
||||
> `value` 类型为 `string | number | boolean | string[]`，需根据字段类型匹配正确格式
|
||||
|
||||
## 约束与本地校验
|
||||
|
||||
- 必填与互斥
|
||||
- 图表类型必填：`table_name`
|
||||
- text 类型必填：`text`
|
||||
- 互斥：`series` 与 `count_all` 二选一，且至少提供其一（仅图表类型）
|
||||
- text 类型**不支持**：`series`、`count_all`、`group_by`、`filter`
|
||||
- 长度/结构
|
||||
- `group_by` 最多 2 个；每项 `field_name` 必填
|
||||
- `group_by[].sort.type` 取值 `group|value|view`；`order` 取值 `asc|desc`
|
||||
- 规范化（CLI 自动处理）
|
||||
- `series[].rollup` 自动转成大写（如 `sum` → `SUM`）
|
||||
- `group_by[].sort.type/order` 自动转成小写
|
||||
- 本地校验（可通过 `--no-validate` 跳过）
|
||||
- `+dashboard-block-create` 默认对 `data_config` 做轻量校验；失败会聚合错误并给出修复建议
|
||||
- `+dashboard-block-update` 不做强类型校验，由后端验证具体字段
|
||||
- 仅需传入合法 JSON；CLI 不会擅自改写你的业务含义
|
||||
|
||||
## 可复制模板
|
||||
|
||||
**按意图选择模板：**
|
||||
- 比较不同类别数值 → 柱状图 / 条形图
|
||||
- 看趋势变化 → 折线图 / 面积图
|
||||
- 看占比分布 → 饼图 / 环形图 / 词云
|
||||
- 多指标对比 → 组合图
|
||||
- 看两变量关系 → 散点图
|
||||
- 看流程转化 → 漏斗图
|
||||
- 看多维度评分 → 雷达图
|
||||
- 显示单个指标 → 指标卡（统计数字或记录数）
|
||||
|
||||
最小柱状图：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
|
||||
"group_by": [{ "field_name": "分组字段", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
最小饼图/环形图（按分类字段统计行数占比）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"count_all": true,
|
||||
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
折线图（按月趋势）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [{ "field_name": "金额", "rollup": "SUM" }],
|
||||
"group_by": [{ "field_name": "月份", "mode": "integrated", "sort": {"type":"group","order":"asc"} }]
|
||||
}
|
||||
```
|
||||
|
||||
条形图（横向柱状图）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
|
||||
"group_by": [{ "field_name": "分组字段", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
面积图（趋势填充）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
|
||||
"group_by": [{ "field_name": "时间字段", "mode": "integrated", "sort": {"type":"group","order":"asc"} }]
|
||||
}
|
||||
```
|
||||
|
||||
组合图（柱+线等多指标对比）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [
|
||||
{ "field_name": "指标1", "rollup": "SUM" },
|
||||
{ "field_name": "指标2", "rollup": "SUM" }
|
||||
],
|
||||
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
散点图（两变量相关性）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [{ "field_name": "Y轴字段（数值/指标）", "rollup": "SUM" }],
|
||||
"group_by": [{ "field_name": "X轴字段（分类/维度）", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
漏斗图（流程转化）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [{ "field_name": "数值字段", "rollup": "SUM" }],
|
||||
"group_by": [{ "field_name": "状态字段", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
词云（文本频率）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"count_all": true,
|
||||
"group_by": [{ "field_name": "文本字段", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
雷达图（多维度评分）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "表名",
|
||||
"series": [
|
||||
{ "field_name": "维度1", "rollup": "SUM" },
|
||||
{ "field_name": "维度2", "rollup": "SUM" },
|
||||
{ "field_name": "维度3", "rollup": "SUM" }
|
||||
],
|
||||
"group_by": [{ "field_name": "分类字段", "mode": "integrated" }]
|
||||
}
|
||||
```
|
||||
|
||||
指标卡（统计数字）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "数据表",
|
||||
"series": [{ "field_name": "数字", "rollup": "SUM" }]
|
||||
}
|
||||
```
|
||||
|
||||
指标卡（统计记录数）：
|
||||
|
||||
```json
|
||||
{
|
||||
"table_name": "数据表",
|
||||
"count_all": true
|
||||
}
|
||||
```
|
||||
|
||||
文本组件（Markdown 富文本）：
|
||||
|
||||
```json
|
||||
{
|
||||
"text": "# 🚀 一级标题\n这是一个 **加粗** *斜体* ~~删除线~~ 的示例。\n\n## 📌 二级标题\n1. 有序列表项 1\n2. 有序列表项 2\n\n### 📌 三级标题\n- 无序列表项 1\n- 无序列表项 2"
|
||||
}
|
||||
```
|
||||
|
||||
> **注意**：text 类型组件不需要 `table_name`、`series`、`group_by`、`filter` 等数据源相关字段。
|
||||
|
||||
## 常见错误与修复
|
||||
|
||||
- 同时存在 `series` 与 `count_all`
|
||||
- 现象：后端/本地校验报互斥错误
|
||||
- 修复：见「关键约束」章节的二选一规则
|
||||
- 缺少 `table_name`
|
||||
- 现象：本地校验缺少必填字段
|
||||
- 修复：指定数据源表名（使用表名，非表 ID）
|
||||
- `series[].rollup` 大小写/取值不合法
|
||||
- 现象：本地校验提示枚举不支持
|
||||
- 修复：改为 `SUM|MAX|MIN|AVERAGE` 中之一（不区分大小写，CLI 会统一为大写；计数请使用 `count_all:true`）
|
||||
- `group_by` 超出 2 个或字段名为空
|
||||
- 修复：保留前 2 个，或补齐 `field_name`
|
||||
- 排序枚举不合法
|
||||
- 修复：`group_by.sort.type` 仅能为 `group|value|view`；`order` 为 `asc|desc`
|
||||
- filter 写法不规范
|
||||
- 修复：`conjunction` 取 `and|or`；`conditions[].operator` 必须在本页表格列举的范围内；除 `isEmpty/isNotEmpty` 外需提供 `value`
|
||||
|
||||
## 坑点
|
||||
|
||||
- **`count_all` 与 `series` 二选一** — 两者不能同时使用
|
||||
- **filter `value` 类型因字段而异** — 文本/单选为 string，数字为 number，日期为毫秒时间戳，多选/人员可为 string[]，复选框为 boolean；`isEmpty`/`isNotEmpty` 不需要 value
|
||||
- **`data_config` 结构随 `type` 变化** — 不同组件类型的字段不同，创建前务必确认类型对应的字段
|
||||
- **表名用 name，不是 ID** — `table_name` 对应的是表名称（如「订单表」），不是 `table_id`
|
||||
737
.agents/skills/lark-base/references/formula-field-guide.md
Normal file
737
.agents/skills/lark-base/references/formula-field-guide.md
Normal file
@ -0,0 +1,737 @@
|
||||
# Base Formula Writing Guide
|
||||
|
||||
## Mandatory Read Acknowledgement
|
||||
|
||||
When creating or updating a formula field with `lark-cli base +field-create/+field-update --json ...` and `type` is `formula`, you should read this guide first and only then add `--i-have-read-guide` to the command.
|
||||
|
||||
Do **not** proactively add `--i-have-read-guide` before reading this guide. Without it, the CLI will fail fast and direct you back to this guide.
|
||||
|
||||
When using `+field-update`, also pass `--yes`: field update is a high-risk `PUT` operation because changing a field definition can affect the whole column.
|
||||
|
||||
## Default strategy
|
||||
|
||||
**All cross-table references, aggregations, and computed fields should use Formula fields by default.** Do NOT use Lookup fields unless the user explicitly requests it. Formula is a strict superset of Lookup — anything Lookup can do, Formula can do with a single expression.
|
||||
|
||||
## Usage
|
||||
|
||||
When creating a formula field, the Agent should:
|
||||
|
||||
1. Get all table names: `lark-cli base +table-list --base-token <base>` — returns `items[].table_name`
|
||||
2. Get table structure: `lark-cli base +table-get --base-token <base> --table-id <table>` — returns `fields[]`
|
||||
3. If the formula references other tables, also get those tables' structures
|
||||
4. Write the formula expression following this guide
|
||||
5. Construct the Formula field JSON and submit it to create or update the field
|
||||
|
||||
**Key constraints**:
|
||||
|
||||
- The JSON must include `"type": "formula"` — this field is required
|
||||
- Table names and field names in the formula must **exactly match** those returned by `+table-list` / `+table-get`
|
||||
- The `expression` value is a string containing the formula expression; double quotes inside the expression must be properly escaped in JSON (e.g. `\"text\"`)
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Core Concepts — Scalar vs List
|
||||
|
||||
This is the foundation of formula logic. You must determine this before writing any formula.
|
||||
|
||||
| Syntax | Meaning | Return type | Example |
|
||||
| --------------------- | -------------------------------------------- | ---------------------- | -------------------------------------------- |
|
||||
| `[Field]` | Value of this field in the current row | Scalar (single value) | `[Name]` → `"Alice"` |
|
||||
| `[TableName].[Field]` | All values of this field in the target table | List (multiple values) | `[Employees].[Name]` → `["Alice","Bob",...]` |
|
||||
| `[TableName]` | The target table (entire table) | Table reference | Used as data range for FILTER/COUNTIF etc. |
|
||||
|
||||
**Rules**:
|
||||
|
||||
- Scalars can be used directly in operations: `[Price] * [Quantity]`
|
||||
- Lists cannot be used as scalars — they must be processed first: use `SUM()` for sum, `ARRAYJOIN(",")` for joining, `FIRST()`/`LAST()`/`NTH()` for single value extraction
|
||||
- Link field access `[LinkField].[TargetField]` returns a list (values of the target field for all linked records)
|
||||
- **LISTCOMBINE flattening rule**: When a FILTER's result column is itself a multi-value field (`select` with `multiple=true`, `link`, etc.), it produces a 2D array and **must** be flattened with `.LISTCOMBINE()`; for single-value fields (`number`, `text`, etc.) it can be omitted, but adding it is never wrong:
|
||||
|
||||
```
|
||||
[Table].FILTER(CurrentValue.[Field] = [Value]).[Tags].LISTCOMBINE() ← required for multi-value columns
|
||||
[Table].FILTER(CurrentValue.[Field] = [Value]).[NumberCol].LISTCOMBINE() ← optional for single-value columns
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Data Types and Type Conversion
|
||||
|
||||
### Field storage types
|
||||
|
||||
| Type | Description | Supported operations |
|
||||
|------|-------------|----------------------|
|
||||
| `number` | Stored as numeric value | Math operations, comparisons, auto-converts to string for concatenation |
|
||||
| `text` | Stored as string | String operations; can participate in math if content is numeric, otherwise errors |
|
||||
| `datetime` | Date object | Date functions, add/subtract with numbers; auto-converts to default format string when using `&` — use TEXT to format first for controlled output |
|
||||
| `select` (`multiple=true`) | Data list | List functions, CONTAIN checks |
|
||||
| `link` | Links to other table records | Chained access `[LinkField].[Field]`, result is a list |
|
||||
| `checkbox` | TRUE/FALSE | Logical operations; auto-converts to number when compared with numbers |
|
||||
|
||||
### Implicit type conversion
|
||||
|
||||
| Scenario | Conversion rule |
|
||||
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| Number + Float | → Float |
|
||||
| Date + Number | → Date (adds/subtracts days). Use `+`/`-` for whole days, use `DURATION()` for hour/minute/second precision |
|
||||
| Date - Date | → Duration |
|
||||
| Boolean compared with Number | Boolean auto-converts to number (TRUE=1, FALSE=0) |
|
||||
| `&` concatenation | Both sides auto-convert to string |
|
||||
|
||||
### Type consistency in comparisons
|
||||
|
||||
When using comparison operators (`>`, `>=`, `<`, `<=`, `=`, `!=`), **both sides should be the same type** to avoid semantic errors or unexpected results.
|
||||
|
||||
**Principle**: When types differ, explicitly convert one side rather than relying on implicit conversion:
|
||||
|
||||
- `number` vs `text` → use `VALUE()` to convert text to number
|
||||
- `datetime` vs `text` → use `TEXT()` to convert date to text
|
||||
- `datetime` vs `datetime` equality → dates include time components, so direct `=` comparison may fail due to different hours/minutes/seconds. For day-level equality, convert to text first: `TEXT([DateA], "YYYY/MM/DD") = TEXT([DateB], "YYYY/MM/DD")`
|
||||
- `select` and `user` fields can be compared with both same-type values and text
|
||||
- `text` fields in numeric aggregation (SUM/AVERAGE/MIN/MAX etc.) → convert to number with `VALUE()` first. For FILTER results, use `.MAP(VALUE(CurrentValue)).SUM()`
|
||||
|
||||
---
|
||||
|
||||
## Section 3: CurrentValue
|
||||
|
||||
**CurrentValue is the iteration variable in FILTER/MAP/COUNTIF/SUMIF functions, representing the "current item" being processed in the data range.**
|
||||
|
||||
### CurrentValue meaning in different contexts
|
||||
|
||||
| Data range type | CurrentValue represents | Access pattern | Example |
|
||||
| ---------------------------- | ----------------------- | --------------------------- | --------------------------------------------------------- |
|
||||
| Entire table `[TableName]` | A row in the table | `CurrentValue.[FieldName]` | `[Orders].FILTER(CurrentValue.[Amount] > 100).[Customer]` |
|
||||
| Column `[TableName].[Field]` | A single field value | Use `CurrentValue` directly | `[Orders].[Amount].FILTER(CurrentValue > 100)` |
|
||||
| `select` (`multiple=true`) field `[Tags]` | One option | Use `CurrentValue` directly | `[Tags].FILTER(CurrentValue = "Important")` |
|
||||
| LIST-generated list | One element | Use `CurrentValue` directly | `LIST(1,2,3).MAP(CurrentValue * 2)` |
|
||||
|
||||
### Key rules
|
||||
|
||||
1. **When data range is a table**, use `CurrentValue.[FieldName]` to access row fields
|
||||
2. **When data range is a column/list**, use `CurrentValue` directly for the element value — **cannot** use `CurrentValue.[FieldName]`
|
||||
3. CurrentValue can **only** appear inside the condition/mapping parameters of FILTER/MAP/COUNTIF/SUMIF functions
|
||||
4. To reference the current table's field value in a condition, write `[FieldName]` directly — it refers to the formula row's value, not a property of CurrentValue
|
||||
|
||||
### Anti-patterns
|
||||
|
||||
| Wrong | Reason | Correct |
|
||||
| ---------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| `[Table].[Col].FILTER(CurrentValue.[Col] > 0)` | Data range is a column; CurrentValue is a scalar, cannot use `.` to access fields | `[Table].[Col].FILTER(CurrentValue > 0)` |
|
||||
| `[Table].FILTER(CurrentValue > 100)` | Data range is a table; CurrentValue is a row, cannot compare directly | `[Table].FILTER(CurrentValue.[Amount] > 100).[Amount]` |
|
||||
| `CurrentValue + 1` (at top level) | CurrentValue can only be used inside iteration functions | Use inside MAP/FILTER etc. |
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Operators
|
||||
|
||||
Base formulas **only allow** the following operators. `like`, `in`, `<>`, `**`, `^` etc. are prohibited.
|
||||
|
||||
| Category | Operators | Description |
|
||||
| ------------- | -------------------------- | -------------------------------------------------------------------------- |
|
||||
| Arithmetic | `+` `-` `*` `/` `%` | Add, subtract, multiply, divide, modulo (`%` is equivalent to `MOD()`) |
|
||||
| Comparison | `>` `>=` `<` `<=` `=` `!=` | Greater than, greater or equal, less than, less or equal, equal, not equal |
|
||||
| Logical | `&&` `\|\|` | AND, OR |
|
||||
| Concatenation | `&` | Text concatenation; non-text values auto-convert to string |
|
||||
|
||||
**Important**:
|
||||
|
||||
- Equality uses `=` (single equals), not `==`
|
||||
- Not-equal uses `!=`, not `<>`
|
||||
- String concatenation uses `&`, not `+`
|
||||
- Both `&&`/`||` and AND()/OR() functions are supported
|
||||
|
||||
---
|
||||
|
||||
## Section 5: Link Fields and Cross-Table References
|
||||
|
||||
### Link field description
|
||||
|
||||
When a field type is described as `FieldName: Link [target table: X, foreign key: Y]`, it links to target table X using field Y as the join key.
|
||||
|
||||
### Chained cross-table access
|
||||
|
||||
```
|
||||
[LinkField].[TargetField]
|
||||
```
|
||||
|
||||
Retrieves the target field values for all linked records as a list. Supports continued chaining: `[LinkA].[LinkB].[Field]`.
|
||||
|
||||
### Equivalent expanded form
|
||||
|
||||
- Multi-value link: `[TargetTableX].FILTER([LinkField].CONTAIN(CurrentValue.[Y])).[TargetField].LISTCOMBINE()`
|
||||
- Single-value link: `[TargetTableX].FILTER(CurrentValue.[Y] = [LinkField]).[TargetField].LISTCOMBINE()`
|
||||
|
||||
(`.LISTCOMBINE()` is required when `[TargetField]` is a multi-value field; optional for single-value fields)
|
||||
|
||||
### Notes
|
||||
|
||||
- Link fields typically return **lists** (possibly empty)
|
||||
- To output a single value, use aggregation (SUM/MAX), joining (ARRAYJOIN), or extraction (FIRST/LAST/NTH)
|
||||
- Do not nest FILTER inside FILTER for cross-table queries — prefer link field chained access
|
||||
|
||||
---
|
||||
|
||||
## Section 6: Function Call Conventions
|
||||
|
||||
### Two calling styles
|
||||
|
||||
| Style | Format | Description |
|
||||
| ---------- | ------------------ | ----------------------------------- |
|
||||
| Functional | `FUNC(arg1, arg2)` | Works for all functions |
|
||||
| Chained | `arg1.FUNC(arg2)` | Moves the first argument before `.` |
|
||||
|
||||
**Rules**:
|
||||
|
||||
- Zero-argument functions cannot be chained: `NOW()`, `TODAY()`, `PI()`, `TRUE()`, `FALSE()`
|
||||
- SORTBY can **only** be chained: `[Table].SORTBY([Table].[SortCol]).[OutputCol]`. The sort column always uses the original table's column name (`[TableName].[Field]` format); the engine aligns rows internally, even when the data range is a FILTER result
|
||||
- FILTER is recommended to be chained: `[Table].FILTER(condition).[OutputCol]`
|
||||
|
||||
### FILTER / SORTBY result column rules
|
||||
|
||||
- **When data range is a table** `[TableName]`, FILTER / SORTBY returns a table reference. The chain **must** end with `.[Field]` to specify the result column, otherwise the formula fails:
|
||||
|
||||
```
|
||||
Correct: [Sales].FILTER(CurrentValue.[Amount] > 100).[Customer]
|
||||
Correct: [Sales].FILTER(condition).SORTBY([Sales].[SortCol]).[Customer] ← result column at end of chain
|
||||
Wrong: [Sales].FILTER(CurrentValue.[Amount] > 100) ← missing result column
|
||||
```
|
||||
|
||||
- **When data range is a column** `[TableName].[Field]` or a list, FILTER returns the filtered list directly — **no** result column needed:
|
||||
|
||||
```
|
||||
Correct: [Sales].[Amount].FILTER(CurrentValue > 100)
|
||||
```
|
||||
|
||||
After the result column, it's recommended to flatten with `.LISTCOMBINE()` first (especially when the result column is a multi-value field), then chain aggregation functions:
|
||||
|
||||
```
|
||||
[Sales].FILTER(CurrentValue.[Amount] > 100).[Amount].LISTCOMBINE().SUM()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 7: Hard Constraints
|
||||
|
||||
1. **Nesting prohibition**: FILTER / SUMIF / COUNTIF / MAP **must not be nested** inside each other's condition/mapping expressions. None of these functions can appear inside the condition or mapping parameter of another.
|
||||
- Prohibited: `[Table1].FILTER(CurrentValue.[Col] = [Table2].FILTER(...).[Col])` ← FILTER inside FILTER condition
|
||||
- Prohibited: `[Table].MAP([Table2].MAP(...))` ← MAP inside MAP mapping
|
||||
- **Allowed**: `[Table].FILTER(cond1).[Col].FILTER(cond2)` ← chained call; the first FILTER's output is the second's data range, not nesting
|
||||
|
||||
2. **Function whitelist**: Only use functions listed in Section 8. No unlisted functions.
|
||||
|
||||
3. **Exact name matching**: Table names and field names in formulas must **exactly match** those returned by `+table-get` — no renaming or adding spaces.
|
||||
|
||||
4. **Operator whitelist**: Only use operators listed in Section 4.
|
||||
|
||||
5. **Strings use double quotes**: Strings must be wrapped in double quotes `"`, single quotes are not supported.
|
||||
|
||||
6. **Do not use LOOKUP**: FILTER is a superset of LOOKUP. All LOOKUP formulas can be rewritten with FILTER. Use FILTER exclusively to reduce complexity.
|
||||
|
||||
---
|
||||
|
||||
## Section 8: Complete Function Reference
|
||||
|
||||
### 8.1 Logic functions
|
||||
|
||||
| Function | Signature | Return type | Description |
|
||||
| ------------- | ------------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| IF | `IF(condition, true_val, [false_val])` | Matches branch type | Returns true_val when TRUE, false_val otherwise; omitting false_val returns false (not null) |
|
||||
| IFS | `IFS(cond1, val1, cond2, val2, ...)` | Matches branch type | Multi-condition branching; returns value for the first TRUE condition |
|
||||
| SWITCH | `SWITCH(expr, match1, result1, [match2, result2, ...], [default])` | Matches branch type | Matches expression value and returns corresponding result |
|
||||
| IFERROR | `IFERROR(expr, fallback)` | Matches branch type | Returns fallback when expression errors |
|
||||
| IFBLANK | `IFBLANK(expr, fallback)` | Matches branch type | Returns fallback when expression is blank (blank = NULL/empty string/empty list) |
|
||||
| AND | `AND(cond1, cond2, ...)` | Boolean | TRUE when all conditions are TRUE |
|
||||
| OR | `OR(cond1, cond2, ...)` | Boolean | TRUE when any condition is TRUE |
|
||||
| NOT | `NOT(condition)` | Boolean | Logical negation |
|
||||
| ISBLANK | `ISBLANK(value)` | Boolean | Tests if blank (NULL/empty string/empty list are blank; 0 and FALSE are not) |
|
||||
| ISNULL | `ISNULL(value)` | Boolean | Tests if NULL (only NULL is true; empty string is not) |
|
||||
| ISERROR | `ISERROR(expr)` | Boolean | Tests if expression errors |
|
||||
| ISNUMBER | `ISNUMBER(value)` | Boolean | Tests if value is a number |
|
||||
| CONTAIN | `CONTAIN(search_range, value, ...)` | Boolean | Tests if a list or `select` (`multiple=true`) contains the value; **does NOT do text substring matching** |
|
||||
| CONTAINSALL | `CONTAINSALL(search_range, value, ...)` | Boolean | Tests if a list or `select` (`multiple=true`) contains all specified values |
|
||||
| CONTAINSONLY | `CONTAINSONLY(search_range, value, ...)` | Boolean | Tests if a list or `select` (`multiple=true`) contains only the specified values |
|
||||
| TRUE | `TRUE()` | Boolean | Returns TRUE |
|
||||
| FALSE | `FALSE()` | Boolean | Returns FALSE |
|
||||
| RECORD_ID | `RECORD_ID()` | Text | Returns the current row's record ID |
|
||||
| RANDOMBETWEEN | `RANDOMBETWEEN(min_int, max_int, [keep_updating])` | Number | Random integer in the specified range |
|
||||
| RANDOMITEM | `RANDOMITEM(list, [keep_updating])` | Matches element type | Randomly picks one element from a list |
|
||||
|
||||
### 8.2 Numeric functions
|
||||
|
||||
| Function | Signature | Return type | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| SUM | `SUM(val1, val2, ...)` | Number | Sum; accepts multiple values or a list |
|
||||
| AVERAGE | `AVERAGE(val1, val2, ...)` | Number | Average |
|
||||
| MAX | `MAX(val1, val2, ...)` | Number | Maximum |
|
||||
| MIN | `MIN(val1, val2, ...)` | Number | Minimum |
|
||||
| MEDIAN | `MEDIAN(val1, val2, ...)` | Number | Median |
|
||||
| COUNTA | `COUNTA(val1, val2, ...)` | Number | Count of non-blank values |
|
||||
| COUNTIF | `COUNTIF(data_range, condition)` | Number | Count matching items. Data range can be a **table** (CurrentValue is a row, use `CurrentValue.[Field]`) or a **column** (CurrentValue is a scalar value) |
|
||||
| SUMIF | `SUMIF(data_range, condition)` | Number | Sum matching values. Data range **must be a numeric column** (e.g. `[Table].[NumField]`); CurrentValue is each value in that column (scalar), cannot use `CurrentValue.[Field]` to access other fields. For cross-field conditions, use FILTER+SUM instead |
|
||||
| ROUND | `ROUND(number, digits)` | Number | Round. digits: 1=one decimal, 0=integer, -1=tens place |
|
||||
| ROUNDUP | `ROUNDUP(number, digits)` | Number | Round away from zero. Same digits semantics as ROUND |
|
||||
| ROUNDDOWN | `ROUNDDOWN(number, digits)` | Number | Round toward zero. Same digits semantics as ROUND |
|
||||
| FLOOR | `FLOOR(number, [base])` | Number | Round down to nearest multiple of base (default 1) |
|
||||
| CEILING | `CEILING(number, [base])` | Number | Round up to nearest multiple of base (default 1) |
|
||||
| ABS | `ABS(number)` | Number | Absolute value |
|
||||
| INT | `INT(number)` | Integer | Truncate to integer |
|
||||
| MOD | `MOD(dividend, divisor)` | Number | Modulo |
|
||||
| POWER | `POWER(base, exponent)` | Number | Exponentiation |
|
||||
| QUOTIENT | `QUOTIENT(dividend, divisor)` | Number | Integer division |
|
||||
| VALUE | `VALUE(text)` | Number | Convert text to number |
|
||||
| ISODD | `ISODD(number)` | Boolean | Tests if number is odd |
|
||||
| RANK | `RANK(value, search_range, [ascending])` | Number | Rank of value in range; default descending |
|
||||
| SEQUENCE | `SEQUENCE(start, end, [step])` | List | Generate number sequence |
|
||||
| PI | `PI()` | Number | Pi constant |
|
||||
| SIN/COS/TAN/ASIN/ACOS/ATAN/ATAN2/SINH/COSH/TANH/ASINH/ACOSH/ATANH | `func(radians_or_value)` | Number | Trigonometric and hyperbolic functions; arguments in radians |
|
||||
|
||||
### 8.3 Text functions
|
||||
|
||||
| Function | Signature | Return type | Description |
|
||||
| --------------- | ---------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| CONCATENATE | `CONCATENATE(text1, text2, ...)` | Text | Concatenate multiple texts; supports lists as input |
|
||||
| LEN | `LEN(text)` | Number | Character count |
|
||||
| LEFT | `LEFT(text, [count])` | Text | Extract from left; default 1 |
|
||||
| RIGHT | `RIGHT(text, [count])` | Text | Extract from right; default 1 |
|
||||
| MID | `MID(text, start, count)` | Text | Extract from middle |
|
||||
| FIND | `FIND(search_val, search_range, [start])` | Number | Find substring position (case-sensitive); returns -1 if not found |
|
||||
| REPLACE | `REPLACE(text, start, count, new_text)` | Text | Replace by position |
|
||||
| SUBSTITUTE | `SUBSTITUTE(text, old_text, new_text, [occurrence])` | Text | Replace by content; can specify which occurrence |
|
||||
| UPPER | `UPPER(text)` | Text | Convert to uppercase |
|
||||
| LOWER | `LOWER(text)` | Text | Convert to lowercase |
|
||||
| TRIM | `TRIM(text)` | Text | Remove leading/trailing spaces |
|
||||
| TEXT | `TEXT(value, format)` | Text | Format output. Date formats: `"YYYY-MM-DD"`, `"YYYY/MM/DD hh:mm:ss"`; number formats: `"00"`, `"000.00"` |
|
||||
| CONTAINTEXT | `CONTAINTEXT(text, search_text)` | Boolean | Tests if text contains substring (text substring matching) |
|
||||
| SPLIT | `SPLIT(text, delimiter)` | List | Split text by delimiter |
|
||||
| TODATE | `TODATE(value)` | Date | Convert date string to date type |
|
||||
| CHAR | `CHAR(number)` | Text | ASCII code to character |
|
||||
| FORMAT | `FORMAT(template, [val1, val2, ...])` | Text | Template string formatting; use `{1}`, `{2}` as placeholders |
|
||||
| HYPERLINK | `HYPERLINK(url, [display_text])` | Hyperlink | Create a hyperlink |
|
||||
| ENCODEURL | `ENCODEURL(text)` | Text | URL encode |
|
||||
| REGEXMATCH | `REGEXMATCH(text, regex)` | Boolean | Regex match test |
|
||||
| REGEXEXTRACT | `REGEXEXTRACT(text, regex)` | List | Extract first match's capture groups |
|
||||
| REGEXEXTRACTALL | `REGEXEXTRACTALL(text, regex)` | 2D List | Extract all matches |
|
||||
| REGEXREPLACE | `REGEXREPLACE(text, regex, replacement)` | Text | Regex replace |
|
||||
|
||||
### 8.4 Date functions
|
||||
|
||||
| Function | Signature | Return type | Description |
|
||||
| ----------- | ----------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| NOW | `NOW()` | Date | Current date and time |
|
||||
| TODAY | `TODAY()` | Date | Current date (midnight) |
|
||||
| DATE | `DATE(year, month, day)` | Date | Construct a date |
|
||||
| YEAR | `YEAR(date)` | Number | Extract year |
|
||||
| MONTH | `MONTH(date)` | Number | Extract month |
|
||||
| DAY | `DAY(date)` | Number | Extract day |
|
||||
| HOUR | `HOUR(date)` | Number | Extract hour |
|
||||
| MINUTE | `MINUTE(date)` | Number | Extract minute |
|
||||
| SECOND | `SECOND(date)` | Number | Extract second |
|
||||
| WEEKDAY | `WEEKDAY(date, [type])` | Number | Day of week |
|
||||
| WEEKNUM | `WEEKNUM(date, [type])` | Number | Week number |
|
||||
| DAYS | `DAYS(end_date, start_date)` | Number | Days between two dates (end - start), includes decimals. **Note parameter order: end date comes first** |
|
||||
| DATEDIF | `DATEDIF(start_date, end_date, [unit])` | Number | Whole days/months/years between dates. Unit: `"D"`(default)/`"M"`/`"Y"`. **Start must be before end** |
|
||||
| DURATION | `DURATION(days, [hours], [minutes], [seconds])` | Duration | Create a duration for date arithmetic |
|
||||
| EDATE | `EDATE(date, months)` | Date | Date N months later |
|
||||
| EOMONTH | `EOMONTH(date, [months])` | Date | End of month N months later; months default 0 |
|
||||
| WORKDAY | `WORKDAY(start_date, days, [holidays])` | Date | Date N workdays later (skips weekends and holidays) |
|
||||
| NETWORKDAYS | `NETWORKDAYS(start_date, end_date, [holidays])` | Number | Workdays between dates (inclusive) |
|
||||
|
||||
### 8.5 List functions
|
||||
|
||||
| Function | Signature | Return type | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| LIST | `LIST(val1, val2, ...)` | List | Create a list |
|
||||
| FIRST | `FIRST(list)` | Scalar | First element |
|
||||
| LAST | `LAST(list)` | Scalar | Last element |
|
||||
| NTH | `NTH(list, index)` | Scalar | Nth element (1-based) |
|
||||
| FILTER | `[Table].FILTER(condition).[ResultCol]` or `[Table].[Col].FILTER(condition)` | List | Filter by condition. When data range is a table, result column is **required**; when it's a column/list, it's not needed. Use CurrentValue in conditions. Add `.LISTCOMBINE()` when result column is multi-value |
|
||||
| MAP | `data_range.MAP(mapping_expr)` | List | Apply mapping to each element. Use CurrentValue in mapping |
|
||||
| SORT | `SORT(list, [ascending])` | List | Sort; default ascending (TRUE) |
|
||||
| SORTBY | `[Table].SORTBY([Table].[SortCol], [ascending]).[OutputCol]` | List | Sort by column then extract output column. **Chain-only, must include output column** |
|
||||
| UNIQUE | `UNIQUE(list)` | List | Deduplicate |
|
||||
| ARRAYJOIN | `ARRAYJOIN(list, [delimiter])` | Text | Join list elements as text; default comma-separated |
|
||||
| LISTCOMBINE | `LISTCOMBINE(val1, [val2, ...])` or `list.LISTCOMBINE()` | List | Two uses: (1) merge values/lists into one list; (2) chained call to flatten 2D array (commonly used when FILTER result column is a multi-value field) |
|
||||
| DISTANCE | `DISTANCE(location1, location2)` | Number | Distance between two geographic locations (km) |
|
||||
|
||||
---
|
||||
|
||||
## Section 9: Commonly Confused Functions
|
||||
|
||||
### CONTAIN vs CONTAINTEXT
|
||||
|
||||
| | CONTAIN | CONTAINTEXT |
|
||||
| ----------- | -------------------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| Purpose | Tests if a **list / `select` (`multiple=true`)** contains a value | Tests if **text** contains a substring |
|
||||
| Example | `[Tags].CONTAIN("Urgent")` | `[Notes].CONTAINTEXT("completed")` |
|
||||
| Wrong usage | `CONTAIN([Notes], "completed")` — cannot do substring matching | `CONTAINTEXT([Tags], "Urgent")` — Tags is a list, not text |
|
||||
|
||||
### ISBLANK vs ISNULL
|
||||
|
||||
| | ISBLANK | ISNULL |
|
||||
| ----------------- | ------- | ------ |
|
||||
| NULL | TRUE | TRUE |
|
||||
| `""` empty string | TRUE | FALSE |
|
||||
| Empty list `[]` | TRUE | FALSE |
|
||||
| `0` | FALSE | FALSE |
|
||||
| `FALSE` | FALSE | FALSE |
|
||||
|
||||
### DAYS vs DATEDIF
|
||||
|
||||
| | DAYS | DATEDIF |
|
||||
| --------------- | ------------------------------------------------------------ | ----------------------------------------- |
|
||||
| Parameter order | `DAYS(end, start)` — end first | `DATEDIF(start, end, unit)` — start first |
|
||||
| Precision | Includes decimals (hours/minutes/seconds as fractional days) | Integer only (whole days/months/years) |
|
||||
| Negative values | Returns negative when start is after end | **Errors** when start is after end |
|
||||
|
||||
### SUM vs SUMIF
|
||||
|
||||
| | SUM | SUMIF |
|
||||
| --------- | ---------------------------------------------- | -------------------------------------------------------------- |
|
||||
| Purpose | Sum all values | Sum values **matching a condition** |
|
||||
| Arguments | `SUM(val1, val2, ...)` or `SUM([Table].[Col])` | `SUMIF(data_range, condition)` with CurrentValue in condition |
|
||||
| Example | `SUM([Orders].[Amount])` — sum all | `SUMIF([Orders].[Amount], CurrentValue > 100)` — sum only >100 |
|
||||
|
||||
### FILTER+aggregation vs COUNTIF/SUMIF
|
||||
|
||||
| | FILTER+aggregation | COUNTIF/SUMIF |
|
||||
| ----------- | ----------------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| Nature | Filter then aggregate (two steps) | One-step (syntactic sugar) |
|
||||
| Equivalence | `[Table].FILTER(cond).[Col].LISTCOMBINE().SUM()` | `SUMIF([Table].[Col], cond)` (only when condition involves only column values) |
|
||||
| When to use | Conditions span multiple fields, or multi-step needed | Conditions only involve column values (e.g. `CurrentValue > 100`) |
|
||||
|
||||
---
|
||||
|
||||
## Section 10: Decision Trees
|
||||
|
||||
### Cross-table queries: which approach?
|
||||
|
||||
```
|
||||
Need data from another table?
|
||||
├─ Current table has a link field to the target table?
|
||||
│ ├─ Yes → Use chained access: [LinkField].[TargetField]
|
||||
│ │ Need aggregation? → .SUM() / .ARRAYJOIN(",") / .FIRST()
|
||||
│ └─ No → Need to match by field value?
|
||||
│ ├─ Field matching or complex filtering → [TargetTable].FILTER(CurrentValue.[MatchField] = [Value]).[OutputCol]
|
||||
│ └─ Only counting or summing → COUNTIF([TargetTable], condition) / FILTER+SUM
|
||||
```
|
||||
|
||||
### Conditional logic: IF vs IFS vs SWITCH?
|
||||
|
||||
```
|
||||
Need conditional logic?
|
||||
├─ Single condition → IF(condition, true_val, false_val)
|
||||
├─ Multiple mutually exclusive conditions (if-elseif-else) → IFS(cond1, val1, cond2, val2, ...)
|
||||
├─ Matching a value against fixed options → SWITCH(expr, option1, result1, option2, result2, ..., default)
|
||||
└─ Need error handling?
|
||||
├─ Catch errors → IFERROR(expr, fallback)
|
||||
└─ Catch blanks → IFBLANK(expr, fallback)
|
||||
```
|
||||
|
||||
### Aggregation: which function?
|
||||
|
||||
```
|
||||
Need to aggregate data?
|
||||
├─ Sum/average/max/min for entire column → SUM/AVERAGE/MAX/MIN([Table].[Col])
|
||||
├─ Count non-blank → COUNTA([Table].[Col])
|
||||
├─ Conditional count → COUNTIF([Table], CurrentValue.[Field] = [Value])
|
||||
├─ Conditional sum (column-only condition) → SUMIF([Table].[Col], CurrentValue > threshold)
|
||||
├─ Conditional sum (cross-field condition) → [Table].FILTER(CurrentValue.[Field]=value).[NumCol].LISTCOMBINE().SUM()
|
||||
├─ Count unique → [Table].[Col].UNIQUE().COUNTA()
|
||||
└─ Ranking → RANK([Value], [Table].[Col])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 11: Common Formula Patterns
|
||||
|
||||
### Pattern 1: Cross-table conditional count
|
||||
|
||||
Count rows in target table matching a condition:
|
||||
|
||||
```
|
||||
[TargetTable].COUNTIF(CurrentValue.[MatchField] = [CurrentTableField])
|
||||
```
|
||||
|
||||
### Pattern 2: Cross-table conditional sum
|
||||
|
||||
Filter target table by current row's value, then sum:
|
||||
|
||||
```
|
||||
[TargetTable].FILTER(CurrentValue.[MatchField] = [CurrentTableField]).[NumCol].LISTCOMBINE().SUM()
|
||||
```
|
||||
|
||||
SUMIF works when data range is a column and conditions only involve column values:
|
||||
|
||||
```
|
||||
SUMIF([TargetTable].[NumCol], CurrentValue > 100)
|
||||
```
|
||||
|
||||
Note: COUNTIF can use a table as data range (only counting, no specific column needed), but SUMIF's data range **must be a numeric column** (needs values to sum), so `CurrentValue` is each value in that column (scalar) — cannot use `CurrentValue.[OtherField]` to access other fields. For cross-field conditions, use FILTER with a table as data range.
|
||||
|
||||
### Pattern 3: Cross-table lookup
|
||||
|
||||
```
|
||||
[TargetTable].FILTER(CurrentValue.[MatchCol] = [CurrentTableField]).[ReturnCol]
|
||||
```
|
||||
|
||||
### Pattern 4: Link field values + aggregation
|
||||
|
||||
```
|
||||
SUM([LinkField].[NumField])
|
||||
[LinkField].[TextField].UNIQUE().ARRAYJOIN(",")
|
||||
```
|
||||
|
||||
### Pattern 5: Conditional text concatenation
|
||||
|
||||
```
|
||||
IF([Condition], "prefix" & [Field] & "suffix", "default text")
|
||||
```
|
||||
|
||||
### Pattern 6: Date difference
|
||||
|
||||
```
|
||||
DATEDIF([StartDate], [EndDate], "D") & " days"
|
||||
DAYS([EndDate], [StartDate])
|
||||
```
|
||||
|
||||
### Pattern 7: List element mapping
|
||||
|
||||
```
|
||||
[SelectField(which multiple=true)].MAP(CurrentValue & " tag")
|
||||
SPLIT([TextField], ",").MAP(TRIM(CurrentValue))
|
||||
```
|
||||
|
||||
### Pattern 8: Cross-table with sorting
|
||||
|
||||
```
|
||||
[TargetTable].SORTBY([TargetTable].[SortCol], FALSE).[OutputCol]
|
||||
[TargetTable].FILTER(CurrentValue.[Field] = [Value]).SORTBY([TargetTable].[SortCol]).[OutputCol]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 12: Anti-Pattern Collection
|
||||
|
||||
### Mistake 1: Extra argument in MAP
|
||||
|
||||
```
|
||||
Wrong: [Table].[Col].MAP([Table2].[Col], CurrentValue + 1)
|
||||
Correct: [Table].[Col].MAP(CurrentValue + 1)
|
||||
```
|
||||
|
||||
Reason: MAP takes only two arguments (data range + mapping expression), no "lookup range".
|
||||
|
||||
### Mistake 2: Inverted FILTER syntax
|
||||
|
||||
```
|
||||
Wrong: condition.[Table].FILTER()
|
||||
Correct: [Table].FILTER(condition).[ResultCol] (result column required when data range is a table)
|
||||
```
|
||||
|
||||
Reason: FILTER's data range comes first, condition is passed as the argument.
|
||||
|
||||
### Mistake 3: Using CurrentValue.[Field] on a column range
|
||||
|
||||
```
|
||||
Wrong: SUMIF([Sales].[Revenue], CurrentValue.[Salesperson] = [Name])
|
||||
Correct: [Sales].FILTER(CurrentValue.[Salesperson] = [Name]).[Revenue].LISTCOMBINE().SUM()
|
||||
```
|
||||
|
||||
Reason: `SUMIF([Sales].[Revenue], ...)` uses "Revenue" column as data range. CurrentValue is each revenue value (scalar), not a row — cannot use `.` to access other fields. Use FILTER with the table as data range for cross-field conditions.
|
||||
|
||||
### Mistake 4: Missing result column after FILTER
|
||||
|
||||
```
|
||||
Wrong: [Sales].FILTER(CurrentValue.[Amount] > 100)
|
||||
Correct: [Sales].FILTER(CurrentValue.[Amount] > 100).[Customer]
|
||||
```
|
||||
|
||||
Reason: FILTER on a table returns a table reference; must specify result column with `.[Field]` at the end.
|
||||
|
||||
### Mistake 5: Nested FILTER
|
||||
|
||||
```
|
||||
Wrong: [Table1].FILTER(CurrentValue.[ID] = [Table2].FILTER(CurrentValue.[Status]="Done").[ID])
|
||||
Correct: [Table1].FILTER(CurrentValue.[ID] = [CurrentRowField]).[OutputCol]
|
||||
```
|
||||
|
||||
Reason: FILTER/MAP/SUMIF/COUNTIF cannot be nested inside each other's conditions. Split into multiple steps or use link fields.
|
||||
|
||||
### Mistake 6: SORTBY without output column
|
||||
|
||||
```
|
||||
Wrong: [Table].SORTBY([Table].[Col])
|
||||
Correct: [Table].SORTBY([Table].[Col]).[OutputCol]
|
||||
```
|
||||
|
||||
Reason: SORTBY must have an output column at the end; otherwise the result cannot be represented as an array.
|
||||
|
||||
### Mistake 7: SORTBY sort column without table name
|
||||
|
||||
```
|
||||
Wrong: [Table].SORTBY([Col]).[OutputCol]
|
||||
Correct: [Table].SORTBY([Table].[Col]).[OutputCol]
|
||||
```
|
||||
|
||||
Reason: SORTBY's sort column must use `[TableName].[FieldName]` format.
|
||||
|
||||
### Mistake 8: Using CONTAIN for text substring matching
|
||||
|
||||
```
|
||||
Wrong: CONTAIN([Notes], "urgent")
|
||||
Correct: CONTAINTEXT([Notes], "urgent")
|
||||
```
|
||||
|
||||
Reason: CONTAIN checks if a list or `select` (`multiple=true`) contains a whole value, not substring matching. Use CONTAINTEXT for text substrings.
|
||||
|
||||
### Mistake 9: Date concatenation without formatting
|
||||
|
||||
```
|
||||
Not recommended: "Deadline: " & [DateField] ← output format is uncontrolled
|
||||
Recommended: "Deadline: " & TEXT([DateField], "YYYY-MM-DD")
|
||||
```
|
||||
|
||||
Reason: Concatenating a date with `&` won't error, but uses the default format. Use TEXT to specify the format explicitly.
|
||||
|
||||
### Mistake 10: Reversed DAYS parameter order
|
||||
|
||||
```
|
||||
Wrong: DAYS([StartDate], [EndDate]) → returns negative
|
||||
Correct: DAYS([EndDate], [StartDate]) → returns positive
|
||||
```
|
||||
|
||||
Reason: DAYS parameter order is end date first, start date second.
|
||||
|
||||
### Mistake 11: Chaining zero-argument functions
|
||||
|
||||
```
|
||||
Wrong: TODAY.DAYS([Date])
|
||||
Correct: TODAY().DAYS([Date])
|
||||
```
|
||||
|
||||
Reason: NOW, TODAY, PI and other zero-argument functions must include parentheses.
|
||||
|
||||
---
|
||||
|
||||
## Section 13: Complete Examples
|
||||
|
||||
### Example 1: Employee sales summary
|
||||
|
||||
**Table structure** (from `+table-get`):
|
||||
|
||||
- Employees: EmployeeID (Text), Name (Text), Department (Text)
|
||||
- Sales: ContractID (Number), SalespersonID (Text), Quantity (Number), Total (Number)
|
||||
|
||||
**Current table**: Employees
|
||||
|
||||
**Requirement**: For each employee, output "Sold XX orders" if they have sales records, otherwise "No sales records".
|
||||
|
||||
**Formula**:
|
||||
|
||||
```
|
||||
IF(
|
||||
[Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1,
|
||||
"Sold " & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & " orders",
|
||||
"No sales records"
|
||||
)
|
||||
```
|
||||
|
||||
**Field JSON**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "formula",
|
||||
"name": "Sales Summary",
|
||||
"expression": "IF([Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) >= 1, \"Sold \" & [Sales].COUNTIF(CurrentValue.[SalespersonID] = [EmployeeID]) & \" orders\", \"No sales records\")"
|
||||
}
|
||||
```
|
||||
|
||||
**Explanation**: `[Sales].COUNTIF(...)` uses the entire Sales table as data range. CurrentValue represents each row in Sales, accessing `CurrentValue.[SalespersonID]` for that row's salesperson. `[EmployeeID]` refers to the current row in the Employees table (where the formula lives).
|
||||
|
||||
### Example 2: Chained cross-table access via link fields
|
||||
|
||||
**Table structure**:
|
||||
|
||||
- Orders: ID (`auto_number`), OrderItems (`link` [target: OrderItems, foreign key: ID])
|
||||
- OrderItems: ID (`auto_number`), Product (`link` [target: Products, foreign key: ID])
|
||||
- Products: ID (`auto_number`), ProductName (`text`)
|
||||
|
||||
**Current table**: Orders
|
||||
|
||||
**Requirement**: Deduplicate and comma-join all product names from linked order items.
|
||||
|
||||
**Formula**:
|
||||
|
||||
```
|
||||
[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(",")
|
||||
```
|
||||
|
||||
**Field JSON**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "formula",
|
||||
"name": "Product List",
|
||||
"expression": "[OrderItems].[Product].[ProductName].UNIQUE().ARRAYJOIN(\",\")"
|
||||
}
|
||||
```
|
||||
|
||||
**Explanation**: `[OrderItems]` gets linked order item records, `.[Product]` expands to each item's linked product, `.[ProductName]` gets all product names, `.UNIQUE()` deduplicates, `.ARRAYJOIN(",")` joins with commas.
|
||||
|
||||
### Example 3: Cross-table filter + sort
|
||||
|
||||
**Table structure**:
|
||||
|
||||
- Projects: ProjectName (Text), Status (Text), Owner (Text)
|
||||
- Tasks: TaskName (Text), Project (Text), Priority (Number), DueDate (Date)
|
||||
|
||||
**Current table**: Projects
|
||||
|
||||
**Requirement**: Find the highest-priority (lowest number) task name for the current project.
|
||||
|
||||
**Formula**:
|
||||
|
||||
```
|
||||
FIRST(
|
||||
[Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName]
|
||||
)
|
||||
```
|
||||
|
||||
**Field JSON**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "formula",
|
||||
"name": "Top Priority Task",
|
||||
"expression": "FIRST([Tasks].FILTER(CurrentValue.[Project] = [ProjectName]).SORTBY([Tasks].[Priority], TRUE).[TaskName])"
|
||||
}
|
||||
```
|
||||
|
||||
**Explanation**: `[Tasks].FILTER(CurrentValue.[Project] = [ProjectName])` filters tasks belonging to the current project. `.SORTBY([Tasks].[Priority], TRUE)` sorts by priority ascending. `.[TaskName]` extracts task names. `FIRST(...)` gets the first one (highest priority).
|
||||
|
||||
---
|
||||
|
||||
## Section 14: Translating User Requirements to Formulas
|
||||
|
||||
When the user describes their formula need in natural language, follow these rules to convert it into a precise expression:
|
||||
|
||||
1. **Numbers must use precise values**: "less than 80%" → field value less than `0.8`. "above 1000" → `>= 1000`.
|
||||
2. **Interval boundaries**: "above/below/within" = closed (inclusive); "less than/more than/outside" = open (exclusive).
|
||||
3. **Branching logic** must be organized as an ordered list with a fallback branch. Each branch has a condition and output.
|
||||
- Example: "return risk level for 1-3" → `IFS([Value] = 1, "low", [Value] = 2, "medium", [Value] = 3, "high")` with an `IFERROR` or trailing empty-string fallback.
|
||||
4. **Multi-level branches must be flattened** to a single level. Nested if-else chains → flat IFS.
|
||||
5. **Branch conditions must be mutually exclusive**. If the user's conditions overlap, rewrite to eliminate ambiguity.
|
||||
6. **Reorder branches by logical priority** if the user's order is illogical (e.g., check specific conditions before catch-all).
|
||||
|
||||
---
|
||||
|
||||
## Section 15: Constraint Summary
|
||||
|
||||
- Request body must include `"type": "formula"` — this field is required
|
||||
- Only use functions and operators listed in this document
|
||||
- FILTER/SUMIF/COUNTIF/MAP must not be nested inside each other's conditions (chained calls are not nesting)
|
||||
- Do not use LOOKUP — use FILTER exclusively
|
||||
- Table and field names must exactly match `+table-get` output
|
||||
- Strings must use double quotes `"`
|
||||
- Format dates with TEXT before concatenating, to control output format
|
||||
- SORTBY can only be chained and must include an output column
|
||||
- Link fields return lists — aggregate or extract single values before output
|
||||
153
.agents/skills/lark-base/references/lark-base-cell-value.md
Normal file
153
.agents/skills/lark-base/references/lark-base-cell-value.md
Normal file
@ -0,0 +1,153 @@
|
||||
# base CellValue 规范（lark-base-cell-value）
|
||||
|
||||
> 适用命令：`lark-cli base +record-upsert`、`lark-cli base +record-batch-create`、`lark-cli base +record-batch-update`
|
||||
|
||||
本文件定义 **shortcut 写记录** 时 `CellValue` 的推荐格式，目标是让 AI 一次写对。不同命令的外层 JSON 形状不同，但每个 cell 都以本文为 source of truth。
|
||||
|
||||
## 1. 顶层规则（必须遵守）
|
||||
|
||||
- `--json` 必须是 JSON 对象。
|
||||
- `+record-upsert`：顶层直接传字段映射：`{"字段名或字段ID": CellValue}`。
|
||||
- `+record-batch-create`：`rows` 是 `CellValue[][]`，列顺序由 `fields` 决定。
|
||||
- `+record-batch-update`：`patch` 是 `Map<FieldNameOrID, CellValue>`，同一份 `patch` 会应用到所有 `record_id_list`。
|
||||
- 一次 payload 里同一字段只用一种 key（字段名或字段 ID），不要重复。
|
||||
- 写入前先 `+field-list` 获取字段 `type/style/multiple`，再构造值。
|
||||
- 需要清空字段时优先传 `null`（字段允许清空时）。
|
||||
|
||||
## 2. 各类型 CellValue
|
||||
|
||||
### 2.1 text / phone / url
|
||||
|
||||
用字符串。URL 字段也传 URL 字符串；普通文本里可以保留 Markdown 风格链接文本，平台会按字段类型处理。
|
||||
|
||||
```json
|
||||
{
|
||||
"标题": "Hello",
|
||||
"联系电话": "1380000000000",
|
||||
"官网": "https://example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 number
|
||||
|
||||
用 JSON number，不要用带单位或千分位的字符串。货币、百分比、进度、评分等数字类字段也按数字写入，展示格式由字段配置决定。
|
||||
|
||||
```json
|
||||
{
|
||||
"工时": 12.5,
|
||||
"预算": 3000,
|
||||
"完成度": 0.65,
|
||||
"评分": 4
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 select（单选/多选）
|
||||
|
||||
单选用选项名字符串；多选用选项名数组。选项名建议与字段配置一致；写入未知选项时平台可能自动新增选项，因此不要把自然语言近义词当成已有选项传入。
|
||||
|
||||
```json
|
||||
{
|
||||
"单选": "Todo",
|
||||
"多选": ["后端", "高优"]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 datetime
|
||||
|
||||
优先用 `YYYY-MM-DD HH:mm:ss` 字符串，这是最稳妥的写法，也和常见 API 输出更容易对齐。不要写相对时间（如“明天上午”）。
|
||||
|
||||
```json
|
||||
{
|
||||
"截止时间": "2026-03-24 10:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.5 checkbox
|
||||
|
||||
用 JSON boolean：`true` 或 `false`，不要用 `"true"`、`"是"`、`1`。
|
||||
|
||||
```json
|
||||
{
|
||||
"已完成": true
|
||||
}
|
||||
```
|
||||
|
||||
### 2.6 user / group_chat
|
||||
|
||||
用对象数组，元素至少包含 `id`。人员字段传用户 ID（如 `ou_xxx`），群字段传群 ID（如 `oc_xxx`）；单值/多值都统一使用数组。
|
||||
|
||||
> **人员字段：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
|
||||
|
||||
> **群组字段：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
|
||||
|
||||
```json
|
||||
{
|
||||
"负责人": [
|
||||
{ "id": "ou_xxx" },
|
||||
{ "id": "ou_xxx2" }
|
||||
],
|
||||
"协作群": [
|
||||
{ "id": "oc_xxx" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.7 link
|
||||
|
||||
用对象数组，元素包含 `id`，值为目标记录的 `record_id`。不要传记录标题；先用 `+record-list` / `+record-search` 找到目标记录 ID。
|
||||
|
||||
```json
|
||||
{
|
||||
"关联任务": [
|
||||
{ "id": "<record_id>" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.8 location
|
||||
|
||||
写入对象必须使用 `{lng, lat}`，两者都是数字；`lng` 是经度，`lat` 是纬度。不需要手动传 `full_address`，平台会根据坐标解析地址。
|
||||
|
||||
```json
|
||||
{
|
||||
"坐标": {
|
||||
"lng": 116.397428,
|
||||
"lat": 39.90923
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
读取、筛选、转文本等场景使用 `full_address` 字符串；只有公式能访问坐标。如果用户只给地址文本，先获取或确认坐标后再写入；不要把仅有地址文本直接当作 location CellValue。
|
||||
|
||||
### 2.9 attachment（不作为普通 CellValue 写入）
|
||||
|
||||
- 追加附件：使用 `lark-cli base +record-upload-attachment --record-id <record_id> --field-id <field_id> --file <path>`；可重复 `--file` 一次追加多个附件，不能用普通记录操作接口写附件值。
|
||||
- 删除附件：使用 `lark-cli base +record-remove-attachment --record-id <record_id> --field-id <field_id> --file-token <file_token> --yes`；可重复 `--file-token` 一次删除同一单元格里的多个附件。
|
||||
- 下载附件：使用 `lark-cli base +record-download-attachment --record-id <record_id> --file-token <file_token> --output <dir>`；不传 `--file-token` 时下载整行所有附件，也可重复 `--file-token` 只下载指定附件。Base 附件必须用这个命令下载，用其他下载入口可能失败。
|
||||
|
||||
## 3. 只读字段（不要写）
|
||||
|
||||
以下字段在写记录时应视为只读：
|
||||
- `auto_number`
|
||||
- `lookup`
|
||||
- `formula`
|
||||
- `created_at` / `updated_at`
|
||||
- `created_by` / `updated_by`
|
||||
|
||||
写入只读字段通常不会更新数据；返回里可能出现 `ignored_fields`，reason 会说明 `READONLY`。看到这种返回时，不要重试同一 payload，应移除只读字段，只写存储字段。
|
||||
|
||||
## 4. 完整示例
|
||||
|
||||
```json
|
||||
{
|
||||
"标题": "Created from shortcut",
|
||||
"状态": "Todo",
|
||||
"标签": ["高优", "外部依赖"],
|
||||
"工时": 8,
|
||||
"截止时间": "2026-03-24 10:00:00",
|
||||
"已完成": false,
|
||||
"负责人": [{ "id": "ou_123" }],
|
||||
"关联任务": [{ "id": "rec_456" }],
|
||||
"坐标": { "lng": 116.397428, "lat": 39.90923 }
|
||||
}
|
||||
```
|
||||
@ -0,0 +1,717 @@
|
||||
# base +dashboard-block-get-data
|
||||
|
||||
> **前置条件：** 先阅读 [lark-base-dashboard.md](lark-base-dashboard.md) 了解 dashboard 整体工作流。
|
||||
|
||||
获取仪表盘图表组件（block）的**最终计算结果**，返回一份适合 AI 直接消费的图表协议 JSON。
|
||||
|
||||
这个命令适合以下场景：
|
||||
|
||||
1. 读取柱状图 / 条形图 / 折线图 / 饼图 / 环形图 / 面积图 / 组合图 / 散点图 / 漏斗图 / 雷达图 / 词云 / 指标卡的**实际计算结果**；
|
||||
2. 把图表结果交给 AI 做后续总结、趋势解释、同比/环比说明、异常点提取；
|
||||
3. 在**不读取原始记录**的前提下，直接消费图表层已经聚合好的结果；
|
||||
4. 验证某个图表当前展示的数据是否符合预期。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> - 本命令返回的是**图表结果协议**，不是 block 元数据；
|
||||
> - 如果你需要 `name`、`type`、`layout`、`data_config` 等配置，请先用 `+dashboard-block-get`；
|
||||
> - 文本组件（`text`）不涉及计算，不适用本命令；
|
||||
|
||||
## 一句话理解
|
||||
|
||||
`+dashboard-block-get-data` = **拿图表“算出来的结果”**，而不是拿图表“怎么配置的”。
|
||||
|
||||
---
|
||||
|
||||
## 支持的图表类型
|
||||
|
||||
当前支持以下图表类型的数据计算与返回：
|
||||
|
||||
### 二维图表（10 种）
|
||||
|
||||
- 柱状图
|
||||
- 条形图
|
||||
- 折线图
|
||||
- 饼图
|
||||
- 环形图
|
||||
- 面积图
|
||||
- 组合图
|
||||
- 散点图
|
||||
- 漏斗图
|
||||
- 雷达图
|
||||
|
||||
### 特殊类型（2 种）
|
||||
|
||||
- 词云
|
||||
- 指标卡（statistics）
|
||||
|
||||
> [!CAUTION]
|
||||
> 文本组件虽然也属于 dashboard block，但它不产生可计算数据，因此不会返回本协议。
|
||||
|
||||
---
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
lark-cli base +dashboard-block-get-data \
|
||||
--base-token bascn***************CtadY \
|
||||
--block-id chtxxxxxxxx
|
||||
```
|
||||
|
||||
如果你还不知道目标 block 的 ID，典型顺序是：
|
||||
|
||||
```bash
|
||||
# 先看仪表盘里有哪些组件
|
||||
lark-cli base +dashboard-block-list \
|
||||
--base-token bascn***************CtadY \
|
||||
--dashboard-id blkxxxxxxxx
|
||||
|
||||
# 再读取某个组件的最终计算结果
|
||||
lark-cli base +dashboard-block-get-data \
|
||||
--base-token bascn***************CtadY \
|
||||
--block-id chtxxxxxxxx
|
||||
```
|
||||
|
||||
如果你需要先确认组件类型、名称或 `data_config`，请先执行：
|
||||
|
||||
```bash
|
||||
lark-cli base +dashboard-block-get \
|
||||
--base-token bascn***************CtadY \
|
||||
--dashboard-id blkxxxxxxxx \
|
||||
--block-id chtxxxxxxxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token，标识目标多维表格 |
|
||||
| `--block-id <id>` | 是 | 图表 Block ID，即目标组件的唯一标识 |
|
||||
| `--format <fmt>` | 否 | 输出格式，遵循 CLI 全局输出格式规则 |
|
||||
| `--dry-run` | 否 | 只预览 API 调用，不真正执行 |
|
||||
|
||||
> [!TIP]
|
||||
> 这个命令**不需要** `--dashboard-id`。只要 `base_token + block_id` 即可定位并读取图表结果。
|
||||
|
||||
---
|
||||
|
||||
## 返回结构总览
|
||||
|
||||
服务端响应外层仍然是标准 OpenAPI 包装：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"dimensions": [...],
|
||||
"measures": [...],
|
||||
"main_data": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
其中 `data` 就是 CLI 图表协议本体。不同图表类型的 `data` 结构略有不同：
|
||||
|
||||
| 图表类型 | 一定有 | 可能有 |
|
||||
|----------|--------|--------|
|
||||
| 二维图表 | `dimensions` / `measures` / `main_data` | 无 |
|
||||
| 词云 | `dimensions` / `measures` / `main_data` | 无 |
|
||||
| 指标卡 | `dimensions` / `measures` / `main_data` | `comparison_data` / `trend_data` |
|
||||
|
||||
---
|
||||
|
||||
## 协议字段说明
|
||||
|
||||
### 1) `dimensions`
|
||||
|
||||
维度定义数组，告诉你主结果里每个 `dim_*` key 代表什么字段。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"field_name": "文本",
|
||||
"alias": "dim_5bKp"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
字段含义：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `field_name` | 维度字段显示名称 |
|
||||
| `alias` | 维度别名，在 `main_data` / `trend_data` 中作为 key 使用 |
|
||||
|
||||
### 2) `measures`
|
||||
|
||||
指标定义数组，告诉你每个 `me_*` key 代表什么聚合指标。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"field_name": "Count",
|
||||
"aggregation": "count_all",
|
||||
"alias": "me_Y291bnRfYWxsX0NvdW50"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
字段含义：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `field_name` | 统计该指标时所使用的字段名称；当 `aggregation = count_all` 时固定为 `Count`，表示统计记录总数 |
|
||||
| `aggregation` | 聚合方式，常见值：`count_all` / `count` / `sum` / `avg` / `min` / `max` |
|
||||
| `alias` | 指标别名，在 `main_data` / `comparison_data` / `trend_data` 中作为 key 使用 |
|
||||
|
||||
例如：
|
||||
|
||||
- 如果统计“销售额”的求和，则 `field_name = 销售额`、`aggregation = sum`
|
||||
- 如果统计记录总数，则 `field_name = Count`、`aggregation = count_all`
|
||||
|
||||
### 3) `main_data`
|
||||
|
||||
主结果集。每一行都是一个对象，key 不是字段名本身，而是 `dimensions` / `measures` 中声明过的 `alias`。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"dim_5bKp": {"value": "A"},
|
||||
"me_Y291bnRfYWxsX0NvdW50": {"value": 3}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 4) `comparison_data`
|
||||
|
||||
仅指标卡可能返回。表示同/环比的两个值，顺序固定为：
|
||||
|
||||
1. 当前周期值
|
||||
2. 对比周期值
|
||||
|
||||
> [!NOTE]
|
||||
> 原始协议里通常**不直接展示周期名称**，只提供对应的值。因此解释“同比”还是“环比”、以及比较窗口具体是什么，通常要结合组件配置或 UI 上下文理解。
|
||||
|
||||
### 5) `trend_data`
|
||||
|
||||
仅指标卡可能返回。表示时间序列趋势，每一行通常包含一个时间维度和一个指标值。
|
||||
|
||||
---
|
||||
|
||||
## alias 规则与读取方式
|
||||
|
||||
你不应该把 alias 当成人类可读字段名，而应把它视为**结果表里的列 ID**。
|
||||
|
||||
常见生成规则：
|
||||
|
||||
- 维度 alias：`dim_` + `base64(field_name)`
|
||||
- 指标 alias：`me_` + `base64(aggregation + "_" + field_name)`
|
||||
|
||||
> [!NOTE]
|
||||
> 为了便于阅读，本文档中的部分示例会使用**简化后的 alias**（例如 `dim_xxx`、`me_xxx` 或较短的示例值），不保证和真实返回值逐字符一致。
|
||||
> 在实际读取结果时，应始终以 `dimensions` / `measures` 中声明的 alias 为准，而不要假设所有示例都严格展开成完整编码值。
|
||||
|
||||
例如：
|
||||
|
||||
```json
|
||||
{
|
||||
"dimensions": [
|
||||
{"field_name": "文本", "alias": "dim_5bKp"}
|
||||
],
|
||||
"measures": [
|
||||
{"field_name": "Count", "aggregation": "count_all", "alias": "me_xxx"}
|
||||
],
|
||||
"main_data": [
|
||||
{
|
||||
"dim_5bKp": {"value": "A"},
|
||||
"me_xxx": {"value": 3}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
应解读为：
|
||||
|
||||
- `dim_5bKp` 对应字段“文本”，取值是 `A`
|
||||
- `me_xxx` 对应指标 `count_all(Count)`，取值是 `3`
|
||||
|
||||
> [!TIP]
|
||||
> 读取结果时，**先看 `dimensions` / `measures`，再解 `main_data`**。不要仅凭 alias 名字猜含义。
|
||||
|
||||
---
|
||||
|
||||
## 各图表类型的协议细节
|
||||
|
||||
### 一、二维图表
|
||||
|
||||
适用于：柱状图、条形图、折线图、饼图、环形图、面积图、组合图、散点图、漏斗图、雷达图。
|
||||
|
||||
#### 结构特征
|
||||
|
||||
- `dimensions`：通常有 `1~2` 个维度
|
||||
- 不分组聚合时：通常 1 个维度
|
||||
- 开启分组聚合时：通常 2 个维度
|
||||
- `measures`：指标定义数组
|
||||
- `main_data`：按“维度组合”展开后的行数据
|
||||
|
||||
#### 这类数据代表什么
|
||||
|
||||
二维图表返回的本质上是一张**聚合结果表**：
|
||||
|
||||
- 每一行代表一个维度值，或一组维度组合；
|
||||
- 每一个 measure 值代表该维度下算出来的指标结果；
|
||||
- 如果图表开启了分组聚合，那么每一行表示“主维度 + 分组维度”的一个组合结果；
|
||||
- 如果图表是折线图、面积图这类带时间轴的图，通常可以把第一维理解为横轴、把 measure 理解为纵轴数值；
|
||||
- 如果图表是饼图、环形图这类占比图，通常可以把每一行理解为一个扇区对应的分类及其数值。
|
||||
|
||||
换句话说，AI 在读取这类结果时，可以把它当作“按某些维度聚合后的统计明细表”，适合进一步做排序、Top N、占比解释、分组对比和趋势总结。
|
||||
|
||||
#### 示例 1：普通二维图表（无分组聚合）
|
||||
|
||||
```json
|
||||
{
|
||||
"dimensions": [
|
||||
{
|
||||
"field_name": "文本",
|
||||
"alias": "dim_5bKp"
|
||||
}
|
||||
],
|
||||
"measures": [
|
||||
{
|
||||
"aggregation": "count_all",
|
||||
"field_name": "Count",
|
||||
"alias": "me_Y291bnRfYWxsX0NvdW50"
|
||||
}
|
||||
],
|
||||
"main_data": [
|
||||
{
|
||||
"dim_5bKp": {"value": "A"},
|
||||
"me_Y291bnRfYWxsX0NvdW50": {"value": 3}
|
||||
},
|
||||
{
|
||||
"dim_5bKp": {"value": "B"},
|
||||
"me_Y291bnRfYWxsX0NvdW50": {"value": 2}
|
||||
},
|
||||
{
|
||||
"dim_5bKp": {"value": "C"},
|
||||
"me_Y291bnRfYWxsX0NvdW50": {"value": 2}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
可解读为：
|
||||
|
||||
- 维度字段是“文本”
|
||||
- 指标是“按记录总数统计”
|
||||
- 当“文本”字段为 `A` 时，对应的 `Count` 指标值是 `3`
|
||||
- 当“文本”字段为 `B` 时，对应的 `Count` 指标值是 `2`
|
||||
- 当“文本”字段为 `C` 时，对应的 `Count` 指标值是 `2`
|
||||
|
||||
#### 示例 2：二维图表（开启分组聚合）
|
||||
|
||||
```json
|
||||
{
|
||||
"dimensions": [
|
||||
{
|
||||
"field_name": "文本",
|
||||
"alias": "dim_5bKp"
|
||||
},
|
||||
{
|
||||
"field_name": "单选",
|
||||
"alias": "dim_5aSl"
|
||||
}
|
||||
],
|
||||
"measures": [
|
||||
{
|
||||
"aggregation": "count_all",
|
||||
"field_name": "Count",
|
||||
"alias": "me_YW91bnR"
|
||||
}
|
||||
],
|
||||
"main_data": [
|
||||
{
|
||||
"dim_5bKp": {"value": "A"},
|
||||
"dim_5aSl": {"value": "a-1"},
|
||||
"me_YW91bnR": {"value": 2}
|
||||
},
|
||||
{
|
||||
"dim_5bKp": {"value": "A"},
|
||||
"dim_5aSl": {"value": "a-2"},
|
||||
"me_YW91bnR": {"value": 1}
|
||||
},
|
||||
{
|
||||
"dim_5bKp": {"value": "B"},
|
||||
"dim_5aSl": {"value": "b-1"},
|
||||
"me_YW91bnR": {"value": 1}
|
||||
},
|
||||
{
|
||||
"dim_5bKp": {"value": "C"},
|
||||
"dim_5aSl": {"value": "c-1"},
|
||||
"me_YW91bnR": {"value": 2}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
可解读为：
|
||||
|
||||
- 第一维是“文本”，第二维是“单选”，指标是“按记录总数统计”
|
||||
- 当“文本”字段为 `A`、且“单选”字段为 `a-1` 时，对应的指标值是 `2`
|
||||
- 当“文本”字段为 `A`、且“单选”字段为 `a-2` 时，对应的指标值是 `1`
|
||||
- 当“文本”字段为 `B`、且“单选”字段为 `b-1` 时，对应的指标值是 `1`
|
||||
- 当“文本”字段为 `C`、且“单选”字段为 `c-1` 时，对应的指标值是 `2`
|
||||
- 如果按“文本”字段汇总，那么“文本”字段为 `A` 时总指标值是 `3`；为 `B` 时总指标值是 `1`；为 `C` 时总指标值是 `2`
|
||||
|
||||
---
|
||||
|
||||
### 二、词云
|
||||
|
||||
#### 结构特征
|
||||
|
||||
词云协议仍然沿用 `dimensions + measures + main_data` 的结构，但语义稍有不同：
|
||||
|
||||
- `dimensions` 对应被分词的字段；
|
||||
- `main_data` 每一行代表一个词；
|
||||
- `measure` 的 value 表示按该词分组后计算出来的统计值。
|
||||
|
||||
#### 这类数据代表什么
|
||||
|
||||
词云返回的不是“原文列表”，而是**按词分组后的聚合统计结果**：
|
||||
|
||||
- `dimensions` 定义的是被分词的来源字段；
|
||||
- `measure` 对应的是该词在当前图表统计范围内对应的统计值，具体含义取决于聚合方式和指标字段；
|
||||
- `main_data` 的每一行都可以理解成“某个词 + 该词对应的统计结果”，其中该维度的具体 value 就是拆分出来的词；
|
||||
- 返回结果通常已经结合图表当前过滤条件、时间范围、数据权限等上下文计算完成。
|
||||
|
||||
因此，AI 读取词云数据时，更适合做“关键词排序”“热点词解释”“按词聚合结果分析”“主题归纳”，而不是把它当成逐条文本记录去理解。
|
||||
|
||||
#### 示例
|
||||
|
||||
```json
|
||||
{
|
||||
"dimensions": [
|
||||
{
|
||||
"field_name": "文本",
|
||||
"alias": "dim_5bKp"
|
||||
}
|
||||
],
|
||||
"measures": [
|
||||
{
|
||||
"aggregation": "count_all",
|
||||
"field_name": "Count",
|
||||
"alias": "me_YW91bnR"
|
||||
}
|
||||
],
|
||||
"main_data": [
|
||||
{
|
||||
"dim_5bKp": {"value": "A"},
|
||||
"me_YW91bnR": {"value": 3}
|
||||
},
|
||||
{
|
||||
"dim_5bKp": {"value": "B"},
|
||||
"me_YW91bnR": {"value": 2}
|
||||
},
|
||||
{
|
||||
"dim_5bKp": {"value": "C"},
|
||||
"me_YW91bnR": {"value": 2}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
可解读为：
|
||||
|
||||
- 被统计的分词字段是“文本”
|
||||
- 当前示例里的 measure 是 `count_all(Count)`，所以这里的统计值可以理解为“按词分组后的记录总数”
|
||||
- 当分词结果为 `A` 时，对应的统计值是 `3`
|
||||
- 当分词结果为 `B` 时，对应的统计值是 `2`
|
||||
- 当分词结果为 `C` 时，对应的统计值是 `2`
|
||||
- 按统计值排序，分词结果 `A` 对应的值最高
|
||||
- 分词结果 `B` 和 `C` 的统计值相同，说明它们处于同一梯队
|
||||
|
||||
---
|
||||
|
||||
### 三、指标卡（statistics）
|
||||
|
||||
指标卡除了主值外，还可能包含同/环比与趋势结果，是本命令里结构最特殊的一类。
|
||||
|
||||
#### 结构特征
|
||||
|
||||
- `measures`：**有且仅有一个指标**
|
||||
- `main_data`：通常只有一行，表示总指标值
|
||||
- `comparison_data`：可选，表示当前周期值与对比周期值
|
||||
- `trend_data`：可选，表示趋势序列
|
||||
- `dimensions`：可能包含同/环比日期字段、趋势日期字段
|
||||
|
||||
#### 这类数据代表什么
|
||||
|
||||
指标卡返回的核心是一个**主指标摘要**，外加可选的比较信息和趋势信息：
|
||||
|
||||
- `main_data` 表示当前卡片最核心、最醒目的那个主值；它通常是某个表的记录总数，或某个字段的聚合值，本身**不带时间周期概念**；
|
||||
- `comparison_data` 表示用于同/环比展示的两个数值，通常是“当前周期值”和“对比周期值”；它们表示某个时间周期下的记录总数，或某个字段的聚合值；
|
||||
- `trend_data` 表示这个指标在一段时间内的变化轨迹，用来支持走势判断；
|
||||
- `dimensions` 在指标卡里通常不是拿来做主分组展示，而是给 `trend_data` 或同/环比相关日期字段提供语义说明。
|
||||
|
||||
例如：
|
||||
|
||||
- `main_data = 7` 可以理解为当前卡片展示的主数据，比如某张表当前总记录数是 `7`；
|
||||
- `comparison_data[0] = 6` 则表示某个比较周期下的当前值，比如“本月记录总数 = 6”；
|
||||
- 因此，`main_data` 与 `comparison_data[0]` **不一定相等**，因为两者表达的口径并不完全相同。
|
||||
|
||||
因此，AI 在解读指标卡时，应该优先回答这几个问题：
|
||||
|
||||
1. 当前主值是多少；
|
||||
2. 和对比周期相比是上升、下降还是持平；
|
||||
3. 趋势整体是增长、波动还是下滑；
|
||||
4. 是否存在明显的异常峰值或低谷。
|
||||
|
||||
> [!NOTE]
|
||||
> 当指标卡**同时指定同/环比和趋势**时，`dimensions` 中日期维度的顺序是固定的：
|
||||
> 1. 第一个元素是**趋势**对应的日期维度；
|
||||
> 2. 第二个元素是**同/环比**对应的日期维度。
|
||||
>
|
||||
> 另外要注意：`comparison_data` 自身通常**不直接携带日期字段**，它只给出“当前周期值 / 对比周期值”。
|
||||
> `dimensions` 中的第一个日期维度会直接出现在 `trend_data` 中，作为趋势序列的时间列；
|
||||
> 第二个日期维度则主要用于补充“该卡片配置了哪类比较相关日期字段”的语义。
|
||||
|
||||
#### 示例
|
||||
|
||||
```json
|
||||
{
|
||||
"dimensions": [
|
||||
{
|
||||
"field_name": "日期",
|
||||
"alias": "dim_ZGF0ZQ"
|
||||
},
|
||||
{
|
||||
"field_name": "日期2",
|
||||
"alias": "dim_ZGF0ZTI"
|
||||
}
|
||||
],
|
||||
"measures": [
|
||||
{
|
||||
"aggregation": "count_all",
|
||||
"field_name": "Count",
|
||||
"alias": "me_YW91b"
|
||||
}
|
||||
],
|
||||
"main_data": [
|
||||
{
|
||||
"me_YW91b": {"value": 7}
|
||||
}
|
||||
],
|
||||
"comparison_data": [
|
||||
{
|
||||
"me_YW91b": {"value": 6}
|
||||
},
|
||||
{
|
||||
"me_YW91b": {"value": 0}
|
||||
}
|
||||
],
|
||||
"trend_data": [
|
||||
{
|
||||
"dim_ZGF0ZQ": {"value": "2026-01-15"},
|
||||
"me_YW91b": {"value": 1}
|
||||
},
|
||||
{
|
||||
"dim_ZGF0ZQ": {"value": "2026-01-17"},
|
||||
"me_YW91b": {"value": 1}
|
||||
},
|
||||
{
|
||||
"dim_ZGF0ZQ": {"value": "2026-03-22"},
|
||||
"me_YW91b": {"value": 1}
|
||||
},
|
||||
{
|
||||
"dim_ZGF0ZQ": {"value": "2026-04-24"},
|
||||
"me_YW91b": {"value": 2}
|
||||
},
|
||||
{
|
||||
"dim_ZGF0ZQ": {"value": "2026-05-01"},
|
||||
"me_YW91b": {"value": 1}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
可解读为：
|
||||
|
||||
- 当前主指标值 = `7`
|
||||
- 当前主指标值不带时间周期概念，可理解为当前卡片主数据
|
||||
- comparison_data[0] = 当前周期值 `6`，例如某个时间周期（如本月）下的统计值
|
||||
- comparison_data[1] = 对比周期值 `0`
|
||||
- `dimensions[0]` 对应趋势日期维度，因此实际出现在 `trend_data` 里
|
||||
- `dimensions[1]` 对应同/环比相关的日期维度，用来补充比较语义
|
||||
- trend_data 展示该指标随时间的变化序列
|
||||
- 从 comparison_data 看，当前周期相较对比周期是上升的，并且对比周期值为 0
|
||||
- 从 trend_data 看，这个指标并不是每天都有值，而是在若干离散日期出现
|
||||
- 趋势序列里的最高点出现在 `2026-04-24`，值为 `2`
|
||||
- 其余出现的日期大多为 `1`，说明整体上有波动，但暂时没有持续快速增长的趋势
|
||||
|
||||
> [!NOTE]
|
||||
> `comparison_data` 只告诉你“当前值 / 对比值”，**不额外标出日期区间文本**。如果用户需要完整说明“和上周比”还是“和上月比”，通常要结合组件配置或界面上下文进一步判断。
|
||||
|
||||
---
|
||||
|
||||
## 如何正确解读返回值
|
||||
|
||||
建议按下面顺序阅读：
|
||||
|
||||
1. **先看 `dimensions`**：确认每个 `dim_*` alias 对应哪个字段；
|
||||
2. **再看 `measures`**：确认每个 `me_*` alias 是什么聚合方式；
|
||||
3. **最后读 `main_data` / `comparison_data` / `trend_data`**：把 alias 还原成“字段名 + 指标名”再做解释。
|
||||
|
||||
### 推荐解释模板
|
||||
|
||||
如果要把结果转成自然语言，建议不要只“复述数值”，而应尽量覆盖下面几个层次：
|
||||
|
||||
1. **先解释指标含义**：说明 measure 代表“记录总数”“某字段求和”“平均值”等；
|
||||
2. **再给出核心结果**：明确当前主值、主要分类、主要组合或主要词项；
|
||||
3. **做排序或 Top N 提炼**：指出最高、最低、前几名、同一梯队；
|
||||
4. **补充分组/对比关系**：如果有第二维或 comparison_data，就说明比较对象和差异；
|
||||
5. **分析趋势或异常点**：如果有时间序列，指出上升、下降、波动、峰值、低谷；
|
||||
6. **最后给一句结论**：总结最值得关注的信息。
|
||||
|
||||
可参考下面模板：
|
||||
|
||||
- 二维图表：
|
||||
- 基础模板：`按 <维度字段> 统计，当前指标 <指标含义>；其中 <维度值1>=<指标值1>，<维度值2>=<指标值2> ...`
|
||||
- 增强模板：`按 <维度字段> 统计，当前指标表示 <指标含义>。从结果看，<Top1维度值> 的值最高，为 <Top1值>；<Top2维度值> 和 <Top3维度值> 紧随其后。若按 Top N 看，前 <N> 项合计贡献了 ...；若看低值项，<低值维度值> 最低，为 <低值>。整体上，<一句总结>`
|
||||
|
||||
- 分组聚合图表：
|
||||
- 基础模板：`按 <维度1> 统计，并以 <维度2> 分组，得到 <组合1>=<值1>，<组合2>=<值2> ...`
|
||||
- 增强模板：`当前指标表示 <指标含义>。按 <维度1> 拆分后，不同 <维度2> 组之间存在明显差异：例如 <组合1> = <值1>，<组合2> = <值2>。如果按 <维度1> 汇总，<Top1维度1值> 总值最高，为 <汇总值>；如果看组内对比，<某组> 在 <某维度1值> 下表现最强 / 最弱。整体说明 <一句总结>`
|
||||
|
||||
- 词云：
|
||||
- 基础模板：`按分词结果统计，当前指标表示 <指标含义>；其中 <词1>=<统计值1>，<词2>=<统计值2> ...`
|
||||
- 增强模板：`当前词云反映的是“按词分组后的 <指标含义>”。从结果看，<Top1词> 的值最高，为 <值1>，说明它是当前最突出的关键词；<Top2词>、<Top3词> 处于第二梯队。如果按 Top N 看，主要关注词集中在 <主题A>、<主题B>；如果有多个词数值接近，可归为同一热点层级。整体上，这组词更适合用来总结 <主题/热点/关注点>`
|
||||
|
||||
- 指标卡：
|
||||
- 基础模板：`当前主指标值为 <main_data>；当前周期值为 <comparison_data[0]>；对比周期值为 <comparison_data[1]>；趋势上 ...`
|
||||
- 增强模板：`当前主指标表示 <指标含义>，主值为 <main_data>。若看周期比较，当前周期值为 <comparison_data[0]>，对比周期值为 <comparison_data[1]>，因此整体表现为 <上升/下降/持平>。若看趋势序列，最高点出现在 <日期>，值为 <峰值>；最低点出现在 <日期>，值为 <低值>；整体走势表现为 <持续增长/阶段波动/明显回落>。如果需要给出结论，可总结为：<一句总结>`
|
||||
|
||||
> [!TIP]
|
||||
> 当用户明确要求“帮我分析”“帮我总结”“帮我找异常 / Top N / 趋势”时，优先采用增强模板，而不是只逐条复述原始数值。
|
||||
|
||||
---
|
||||
|
||||
## 常见工作流
|
||||
|
||||
### 场景 1：用户要“拿这个图表当前展示的数据”
|
||||
|
||||
```bash
|
||||
# 如果已知 block_id，直接读结果
|
||||
lark-cli base +dashboard-block-get-data \
|
||||
--base-token xxx \
|
||||
--block-id chtxxxxxxxx
|
||||
```
|
||||
|
||||
### 场景 2：用户说“帮我分析这个图表”，但你还不知道它是什么组件
|
||||
|
||||
```bash
|
||||
# 先看组件配置，确认它是不是支持计算的图表类型
|
||||
lark-cli base +dashboard-block-get \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx \
|
||||
--block-id chtxxxxxxxx
|
||||
|
||||
# 再读最终计算结果
|
||||
lark-cli base +dashboard-block-get-data \
|
||||
--base-token xxx \
|
||||
--block-id chtxxxxxxxx
|
||||
```
|
||||
|
||||
### 场景 3：用户要找“仪表盘里哪个图的结果异常”
|
||||
|
||||
```bash
|
||||
# 先列组件
|
||||
lark-cli base +dashboard-block-list \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx
|
||||
|
||||
# 再针对可疑 block 逐个取结果
|
||||
lark-cli base +dashboard-block-get-data \
|
||||
--base-token xxx \
|
||||
--block-id chtxxxxxxxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 何时优先用这个命令
|
||||
|
||||
- 用户说“帮我拿这个图表算出来的数据 / 结果 / 指标”
|
||||
- 用户已经知道 `block_id`，目标是**读取结果**而不是看配置
|
||||
- 用户后续还要让 AI 对图表结果做解释、归纳、比较、总结
|
||||
- 你只关心图表层的聚合产出，不需要回到底表逐条读记录
|
||||
|
||||
## 何时不要误用
|
||||
|
||||
- 想看 block 的 `data_config`、名称、类型、布局 → 用 `+dashboard-block-get`
|
||||
- 想列出仪表盘里有哪些组件 → 用 `+dashboard-block-list`
|
||||
- 想修改或新建组件 → 用 `+dashboard-block-update` / `+dashboard-block-create`
|
||||
- 想看原始记录明细，而不是图表聚合结果 → 回到 `record-*`
|
||||
- 目标是文本组件 → 本命令不适用
|
||||
|
||||
---
|
||||
|
||||
## 常见误区
|
||||
|
||||
### 误区 1：把这个命令当成“获取 block 详情”
|
||||
|
||||
不是。这个命令不返回：
|
||||
|
||||
- block 名称
|
||||
- block 类型
|
||||
- layout
|
||||
- `data_config`
|
||||
- 所属 dashboard 信息
|
||||
|
||||
这些都应该通过 `+dashboard-block-get` 获取。
|
||||
|
||||
### 误区 2：以为它返回的是原始记录
|
||||
|
||||
不是。它返回的是**图表聚合后的最终结果**。如果图表本身做了过滤、分组、聚合、时间窗口限制，返回值反映的是图表视角，不是原始表全量明细。
|
||||
|
||||
### 误区 3：直接把 alias 当真实字段名读
|
||||
|
||||
不应该。alias 只是协议里的键，必须结合 `dimensions` / `measures` 还原语义。
|
||||
|
||||
### 误区 4：看到指标卡的 `comparison_data` 就以为已经知道“同比/环比周期文本”
|
||||
|
||||
不一定。它只给出比较值，不一定给出周期标签。若要精确解释比较窗口，通常还需要组件配置或 UI 上下文。
|
||||
|
||||
---
|
||||
|
||||
## dry-run 用途
|
||||
|
||||
可用来确认最终会调用的接口路径：
|
||||
|
||||
```bash
|
||||
lark-cli base +dashboard-block-get-data \
|
||||
--base-token bascn_example_token \
|
||||
--block-id chtxxxxxxxx \
|
||||
--dry-run \
|
||||
--format pretty
|
||||
```
|
||||
|
||||
你应能看到类似：
|
||||
|
||||
```text
|
||||
GET /open-apis/base/v3/bases/bascn_example_token/dashboards/blocks/chtxxxxxxxx/data
|
||||
```
|
||||
|
||||
适合在以下场景使用：
|
||||
|
||||
- 校验 `base_token` / `block_id` 是否传对；
|
||||
- 调试 agent 生成的命令；
|
||||
- 编写自动化测试时确认请求结构。
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base-dashboard.md](lark-base-dashboard.md) — dashboard 模块总指引
|
||||
- `+dashboard-block-get` — 获取 block 元数据
|
||||
- [dashboard-block-data-config.md](dashboard-block-data-config.md) — data_config 结构和组件类型说明
|
||||
238
.agents/skills/lark-base/references/lark-base-dashboard.md
Normal file
238
.agents/skills/lark-base/references/lark-base-dashboard.md
Normal file
@ -0,0 +1,238 @@
|
||||
# Dashboard（仪表盘/数据看板）模块指引
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**组件**（图表、指标卡等）进行展示。
|
||||
|
||||
## 核心概念
|
||||
|
||||
- **Dashboard（仪表盘）**：容器，包含多个组件
|
||||
- **Block（组件）**：仪表盘中的单个可视化元素（柱状图、折线图、饼图、指标卡等）
|
||||
- **data_config**：组件的数据源配置（表名、字段、分组等）
|
||||
|
||||
## 能力速览
|
||||
|
||||
| 你想做什么 | 用这些命令 | 关键文档 |
|
||||
|------|-----------|---------|
|
||||
| 创建/删除/改名称 | `+dashboard-create/delete/update` | 本页下方「仪表盘管理」 |
|
||||
| 在仪表盘里添加组件 | `+dashboard-block-create` | 先定位 dashboard、表和字段，再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 构造 `data_config` |
|
||||
| 修改组件 | `+dashboard-block-update` | 先读 block 现状，再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 决定替换哪些顶层 key |
|
||||
| 查看仪表盘有哪些组件 | `+dashboard-get` 或 `+dashboard-block-list` | 本页下方「查看仪表盘」 |
|
||||
| 读取图表计算结果 | `+dashboard-block-get-data` | 返回图表最终数据协议；需要 block 元数据先用 `+dashboard-block-get` |
|
||||
| 智能重排组件布局 | `+dashboard-arrange` | 只在用户明确要求重排时执行；无法指定精确位置 |
|
||||
|
||||
## 典型场景工作流
|
||||
|
||||
### 场景 1：从 0 到 1 创建仪表盘
|
||||
|
||||
示例：搭建一个销售数据分析仪表盘
|
||||
|
||||
```bash
|
||||
# 第 1 步：创建空白仪表盘
|
||||
lark-cli base +dashboard-create --base-token xxx --name "销售数据分析"
|
||||
# 记录返回的 dashboard_id
|
||||
|
||||
# 第 2 步：获取数据源信息
|
||||
lark-cli base +table-list --base-token xxx
|
||||
lark-cli base +field-list --base-token xxx --table-id <table_id>
|
||||
|
||||
# 第 3 步：规划应该创建哪些组件（根据用户需求确定组件类型和数量）
|
||||
# 例如：总销售额（指标卡）、月度趋势（折线图）、品类占比（饼图）
|
||||
|
||||
# 第 4 步：顺序创建每个组件（必须串行执行，不能并发）
|
||||
# 重要：创建组件前，先确定 dashboard_id、组件 name/type 和真实表字段
|
||||
# 再阅读 dashboard-block-data-config.md 了解 data_config 结构、组件类型和 filter 规则
|
||||
|
||||
# 第 1 个组件
|
||||
lark-cli base +dashboard-block-create \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx \
|
||||
--name "总销售额" \
|
||||
--type statistics \
|
||||
--data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}]}'
|
||||
|
||||
# 第 2 个组件（等上一个完成后再执行）
|
||||
lark-cli base +dashboard-block-create \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx \
|
||||
--name "月度趋势" \
|
||||
--type line \
|
||||
--data-config '{"table_name":"订单表","series":[{"field_name":"金额","rollup":"SUM"}],"group_by":[{"field_name":"月份","mode":"integrated"}]}'
|
||||
|
||||
# 继续创建其他组件...
|
||||
|
||||
# 第 5 步：组件创建完成后，使用 arrange 命令智能重排布局（可选但推荐）
|
||||
# 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
|
||||
lark-cli base +dashboard-arrange \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx
|
||||
```
|
||||
|
||||
### 场景 2：在已有仪表盘上添加新组件
|
||||
|
||||
```bash
|
||||
# 第 1 步：列出仪表盘，定位到当前仪表盘
|
||||
lark-cli base +dashboard-list --base-token xxx
|
||||
# 获取目标 dashboard_id
|
||||
|
||||
# 第 2 步：根据用户诉求规划组件类型和数据源
|
||||
# 建议先查看当前仪表盘已有组件，避免重复创建，或作为参考
|
||||
lark-cli base +dashboard-get --base-token xxx --dashboard-id blk_xxx
|
||||
|
||||
# 第 3 步：获取数据源信息
|
||||
lark-cli base +table-list --base-token xxx
|
||||
lark-cli base +field-list --base-token xxx --table-id <table_id>
|
||||
|
||||
# 第 4 步：顺序创建每个新组件（必须串行执行，不能并发）
|
||||
# 重要：先确定 dashboard_id、组件 name/type 和真实表字段
|
||||
# 再阅读 dashboard-block-data-config.md 了解 data_config 结构
|
||||
lark-cli base +dashboard-block-create \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx \
|
||||
--name "新组件名" \
|
||||
--type column \
|
||||
--data-config '{...}'
|
||||
```
|
||||
|
||||
### 场景 3：编辑已有组件
|
||||
|
||||
> [!IMPORTANT]
|
||||
> `+dashboard-block-update` **不能修改组件的 `type`**（图表类型），只能更新 `name` 和 `data_config`。
|
||||
> 如需更换组件类型，必须先删除再重新创建。
|
||||
|
||||
```bash
|
||||
# 第 1 步：列出仪表盘，定位到当前仪表盘
|
||||
lark-cli base +dashboard-list --base-token xxx
|
||||
|
||||
# 第 2 步：列出组件，获取到目标组件
|
||||
lark-cli base +dashboard-block-list --base-token xxx --dashboard-id blk_xxx
|
||||
# 获取目标 block_id
|
||||
# 提示：查看已有组件可作为参考，或检查是否重复创建相似组件
|
||||
|
||||
# 第 3 步：获取组件当前详情
|
||||
lark-cli base +dashboard-block-get --base-token xxx --dashboard-id blk_xxx --block-id chtxxxxxxxx
|
||||
|
||||
# 第 4 步：根据用户编辑诉求准备更新
|
||||
# 如果编辑诉求涉及数据源变更，需要先获取数据源信息
|
||||
lark-cli base +table-list --base-token xxx
|
||||
lark-cli base +field-list --base-token xxx --table-id <table_id>
|
||||
|
||||
# 第 5 步：执行更新
|
||||
# 重要：先读取当前 block 的 name/type/data_config
|
||||
# 再阅读 dashboard-block-data-config.md 了解 data_config 更新规则
|
||||
lark-cli base +dashboard-block-update \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx \
|
||||
--block-id chtxxxxxxxx \
|
||||
--data-config '{...}'
|
||||
```
|
||||
|
||||
### 场景 4：重排仪表盘布局
|
||||
|
||||
当用户明确要求对已有仪表盘进行布局重排或美化时使用。
|
||||
|
||||
> [!CAUTION]
|
||||
> - 排列结果是**服务端智能推荐**，不一定完全符合用户预期
|
||||
> - 无法指定具体位置（如"第一排放 A，第二排放 B"），排列逻辑是**自适应**的
|
||||
> - **不建议**在已有仪表盘上自动调用，除非用户明确要求
|
||||
|
||||
```bash
|
||||
# 第 1 步：列出仪表盘，定位到目标仪表盘
|
||||
lark-cli base +dashboard-list --base-token xxx
|
||||
|
||||
# 第 2 步：执行智能重排
|
||||
lark-cli base +dashboard-arrange \
|
||||
--base-token xxx \
|
||||
--dashboard-id blk_xxx
|
||||
```
|
||||
|
||||
### 场景 5：读取仪表盘或组件现状
|
||||
|
||||
**选择查询方式：**
|
||||
- 想看仪表盘整体结构（含主题、所有组件名称和类型）→ 用 **方式 A**
|
||||
- 只想快速查看有哪些组件 → 用 **方式 B**
|
||||
- 想看某个组件的详细 data_config 配置 → 用 **方式 C**
|
||||
- 想看某个图表/指标卡实际算出来的数据 → 用 **方式 D**
|
||||
|
||||
```bash
|
||||
# 第 1 步：列出仪表盘，定位到当前仪表盘
|
||||
lark-cli base +dashboard-list --base-token xxx
|
||||
|
||||
# 第 2 步：根据用户诉求查看详情
|
||||
|
||||
# 方式 A：查看仪表盘整体情况（包含所有组件列表）
|
||||
lark-cli base +dashboard-get --base-token xxx --dashboard-id blk_xxx
|
||||
|
||||
# 方式 B：列出所有组件
|
||||
lark-cli base +dashboard-block-list --base-token xxx --dashboard-id blk_xxx
|
||||
|
||||
# 方式 C：查看某个组件的详细配置
|
||||
lark-cli base +dashboard-block-get --base-token xxx --dashboard-id blk_xxx --block-id chtxxxxxxxx
|
||||
|
||||
# 方式 D：查看某个图表组件的计算结果（AI 友好的 chart protocol）
|
||||
lark-cli base +dashboard-block-get-data --base-token xxx --block-id chtxxxxxxxx
|
||||
|
||||
# 最后：把获取到的现状信息整理好告诉用户
|
||||
```
|
||||
|
||||
## 组件类型选择
|
||||
|
||||
组件 `type` 决定展示形式：
|
||||
|
||||
| 用户想看什么 | 选什么 type | 说明 |
|
||||
|-------------|------------|------|
|
||||
| 数据趋势（时间变化） | line | 折线图组件 |
|
||||
| 类别比较（谁高谁低） | column | 柱状图组件 |
|
||||
| 占比分布（各部分比例） | pie | 饼图组件 |
|
||||
| 单个关键指标 | statistics | 指标卡组件 |
|
||||
| 富文本说明/标题/注释 | text | 文本组件（支持 Markdown） |
|
||||
|
||||
详细组件类型和 data_config 完整规则：[dashboard-block-data-config.md](dashboard-block-data-config.md)
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Q: 创建组件的命令和 data_config 怎么写？**
|
||||
A:
|
||||
1. 先确定 `dashboard_id`、组件 `name`、组件 `type` 和真实表字段
|
||||
2. 再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解：
|
||||
- 全部组件类型的可复制模板
|
||||
- filter 筛选条件格式
|
||||
- 字段类型与操作符对应表
|
||||
|
||||
**Q: 为什么组件创建失败了？**
|
||||
A: 常见原因：
|
||||
- `table_name` 用了 table_id 而不是表名（必须用表名称，如「订单表」）
|
||||
- `series` 和 `count_all` 同时存在（必须二选一，互斥）
|
||||
- 字段名拼写错误（必须用 `+field-list` 获取的真实字段名，禁止猜测）
|
||||
- 组件创建并发执行（必须串行，等上一个完成再执行下一个）
|
||||
|
||||
**Q: 可以一次创建多个组件吗？**
|
||||
A: 不可以，必须串行执行。等上一个 `+dashboard-block-create` 完成后再执行下一个。
|
||||
|
||||
**Q: 组件的 `type` 创建后能改吗？**
|
||||
A: 不能。`+dashboard-block-update` 只能修改 `name` 和 `data_config`，不能修改 `type`。
|
||||
|
||||
**Q: 更新组件的命令和 data_config 怎么写？**
|
||||
A:
|
||||
1. 先读取当前 block，确认 `block_id`、当前 `type` 和已有 `data_config`
|
||||
2. 再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解 data_config 结构
|
||||
|
||||
**data_config 更新策略（顶层 key merge）**：
|
||||
- 只传入需要修改的顶层字段（如 `series`、`filter`）
|
||||
- 未传的顶层字段（如 `group_by`）自动保留原值
|
||||
- 但每个传入的字段内部是**全量替换**（如传新 `filter` 会完整覆盖旧 `filter`）
|
||||
|
||||
**Q: 查看已有组件有什么用？**
|
||||
A: 在「添加新组件」或「编辑组件」前查看已有组件可以：
|
||||
- 了解当前仪表盘已有哪些可视化
|
||||
- 避免重复创建相似的组件
|
||||
- 参考已有组件的 data_config 结构作为模板
|
||||
|
||||
**Q: 我想直接拿图表算好的结果给 AI 分析，应该用什么？**
|
||||
A: 用 `+dashboard-block-get-data`。它返回图表协议 JSON（常见字段包括 `dimensions`、`measures`、`main_data`，指标卡可能还有 `comparison_data`、`trend_data`），不返回 block 名称、类型、布局或 `data_config`；需要这些元数据时先用 `+dashboard-block-get`。
|
||||
|
||||
## 写入前检查
|
||||
|
||||
- 创建 block 前必须知道 `base_token`、`dashboard_id`、组件 `name/type` 和 `data_config`。
|
||||
- 更新 block 前必须知道 `base_token`、`dashboard_id`、`block_id`，并读过当前 block。
|
||||
- `data_config` 中使用表名和字段名，不使用 table_id / field_id；名称必须来自 `+table-list` / `+field-list` 的真实返回。
|
||||
@ -0,0 +1,210 @@
|
||||
# Base data analysis SOP
|
||||
|
||||
Base 数据查询与分析任务的执行契约。覆盖记录读取、筛选、排序、Top/Bottom N、聚合统计、分组聚合、多表关联、临时分析和查询后写入前的目标定位。
|
||||
|
||||
本文只管查询选路和正确性边界；具体操作前先读真实结构和现状，复杂 JSON 再跳到 reference：
|
||||
|
||||
- `+data-query`: entry guide [lark-base-data-query-guide.md](lark-base-data-query-guide.md), full DSL SSOT [lark-base-data-query.md](lark-base-data-query.md)
|
||||
- 视图筛选: [lark-base-view-set-filter.md](lark-base-view-set-filter.md)
|
||||
- 记录读取: `+record-list` / `+record-search` / `+record-get`，先确认字段 ID、字段名、分页和投影范围
|
||||
|
||||
## 0. Hard Rules
|
||||
|
||||
- 全局问题不能用默认 `+record-list --limit N` 片面地回答。
|
||||
- `jq` / shell / 本地代码是在个人电脑或当前运行环境中处理已返回数据，只适合小范围结果；超过 200 行默认不推荐本地统计、排序或求极值，应改用 Base 云端查询服务的 filter/sort/aggregate。
|
||||
- “最高、最低、最新、最早、Top、Bottom、总数、全部、异常、最大、最小、最多、最少、优先级最高”等全局语义，必须在 Base 云端查询服务中完成筛选、排序或聚合。
|
||||
- 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`。
|
||||
- `+record-search` 用于关键词检索字段的展示文本；金额、状态、日期、空值、关联等结构化条件继续用 `--filter-json` 表达。
|
||||
- 不要依赖已有视图，除非用户明确指定该视图，或你已读取并验证其 filter/sort/projection 符合当前问题。
|
||||
- 交付输出必须使用用户可读的真实字段值；内部 ID、`record_id`、关联记录 ID、open_id、编码字段只可作为连接键或定位键，不能替代最终输出，除非用户明确要求输出这些键值。
|
||||
- 每次读取必须做最小投影，并包含后续解释、回查或写入需要的业务 key。
|
||||
|
||||
## 1. Intent -> Tool Path
|
||||
|
||||
| 用户意图 | 首选路径 | 关键规则 |
|
||||
| --- | --- | --- |
|
||||
| 看几条、预览、示例 | `+record-list --limit N --field-id ...` | 保持局部语义；不要推广为全局结论 |
|
||||
| 已知 `record_id` | `+record-get` | 直接读取；不要 search/list 反查 |
|
||||
| 明确关键词 | `+record-search --keyword ... --search-field ... --field-id ...` | 必须显式指定 `--search-field`；可叠加 `--filter-json` |
|
||||
| 按条件找原始记录 | `+record-list --filter-json ...` | `filter-json` 与视图筛选结构一致，支持文本、数字、日期、选项、人员、群组、关联等值 |
|
||||
| 排序 / TopN 原始记录 | `+record-list --filter-json ... --sort-json ... --limit N` | 最高/最新用 `desc:true`，最低/最早用 `desc:false`；数组顺序表达优先级；最多 10 个排序条件 |
|
||||
| 聚合 / 分组 / 分组排序 | `+data-query` | 使用 filters/dimensions/measures/sort/limit |
|
||||
| 聚合后输出逐条记录 | `+data-query` 得到业务 key 或候选字段组合 -> `+record-list --filter-json` / `+record-get` 回查 | `+data-query` 维度行按字段组合去重且不返回 `record_id` |
|
||||
| 多表 / 多跳关联 | 以候选数最小的事实表为驱动表，沿业务 key 或 link `record_id` 逐跳回查 | 读出 link 单元格里的关联 `record_id` 后，到被关联表批量 `+record-get` 展示字段 |
|
||||
| 查询后写入 / 视图化 | 先用本 SOP 得到可复核的目标记录 id 集合 | 再进入记录写入或视图配置；高价值可复用查询可沉淀为持久视图 |
|
||||
|
||||
## 2. Execution Patterns
|
||||
|
||||
### 2.1 结构化原始记录与 TopN
|
||||
|
||||
使用 `+record-list` 的 filter/sort 路径：
|
||||
|
||||
1. `+field-list` 确认筛选字段、排序字段、展示字段、业务 key。
|
||||
2. 筛选只用 `--filter-json` 或 `--filter-json @file`。
|
||||
3. 排序用 `--sort-json`。
|
||||
4. `--field-id` 做最小投影，`--limit` 控制返回数量。
|
||||
|
||||
Example: string/number 条件 + TopN：
|
||||
|
||||
```bash
|
||||
lark-cli base +record-list \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--filter-json '{"logic":"and","conditions":[["Title","==","Launch plan"],["Score",">=",80]]}' \
|
||||
--sort-json '[{"field":"Updated","desc":true}]' \
|
||||
--field-id Name \
|
||||
--field-id Title \
|
||||
--field-id Score \
|
||||
--limit 20
|
||||
```
|
||||
|
||||
Example: 复杂筛选从文件读取：
|
||||
|
||||
```bash
|
||||
lark-cli base +record-list \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--filter-json @filter.json \
|
||||
--sort-json '[{"field":"Priority","desc":true}]' \
|
||||
--field-id Name \
|
||||
--field-id Tags \
|
||||
--limit 50
|
||||
```
|
||||
|
||||
`filter-json` 与视图筛选结构一致。下面只列常用 fewshot；字段类型、operator、value 形状拿不准，或需要人员、群组、关联、空值、地理位置、formula / lookup 等完整筛选时，先读 [lark-base-view-set-filter.md](lark-base-view-set-filter.md)，再把同样的 filter JSON 传给 `--filter-json`。
|
||||
|
||||
文本 `==`：字段值等于目标文本。
|
||||
```json
|
||||
{"logic":"and","conditions":[["Title","==","Launch plan"]]}
|
||||
```
|
||||
|
||||
文本包含 / like：文本字段包含目标片段；operator 写 `intersects`。
|
||||
```json
|
||||
{"logic":"and","conditions":[["Title","intersects","urgent"]]}
|
||||
```
|
||||
|
||||
数字 `==`：字段值等于目标数字。
|
||||
```json
|
||||
{"logic":"and","conditions":[["Score","==",95]]}
|
||||
```
|
||||
|
||||
日期 `==`：字段值等于目标日期；datetime / created_at / updated_at 用 `ExactDate(...)`。
|
||||
```json
|
||||
{"logic":"and","conditions":[["Due Date","==","ExactDate(2026-06-02)"]]}
|
||||
```
|
||||
|
||||
选项 `==`：字段值匹配单个选项；选项值使用选项名数组，单个选项也写数组。
|
||||
```json
|
||||
{"logic":"and","conditions":[["Priority","==",["P0"]]]}
|
||||
```
|
||||
|
||||
选项 `intersects`：字段值与给定选项集合有交集，常用于多选或“命中任一选项”。
|
||||
```json
|
||||
{"logic":"and","conditions":[["Tags","intersects",["P0","Blocked"]]]}
|
||||
```
|
||||
|
||||
`--sort-json` 传排序数组，数组顺序就是优先级，`desc:true` 为降序，`desc:false` 为升序，最多 10 个排序条件。
|
||||
|
||||
### 2.2 关键词检索后叠加结构化条件
|
||||
|
||||
使用 `+record-search` 做关键词命中，结构化条件仍用 `--filter-json` 下推：
|
||||
|
||||
```bash
|
||||
lark-cli base +record-search \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--keyword Alice \
|
||||
--search-field Name \
|
||||
--filter-json '{"logic":"and","conditions":[["Status","!=","Done"]]}' \
|
||||
--sort-json '[{"field":"Updated","desc":true}]' \
|
||||
--field-id Name \
|
||||
--field-id Status \
|
||||
--limit 20
|
||||
```
|
||||
|
||||
不要把 `+record-search` 当成金额、状态、日期、空值、关联字段的结构化筛选入口；这些条件继续写成 `--filter-json`。
|
||||
|
||||
### 2.3 聚合分析与 TopN
|
||||
|
||||
使用 `+data-query`：
|
||||
|
||||
- 让 Base 云端查询服务完成 filters、dimensions、measures、sort、pagination.limit。
|
||||
- `pagination.limit` 是 Base 云端查询服务中的结果限制，不是本地分页扫描。
|
||||
- 常用聚合 fewshot 先读 [lark-base-data-query-guide.md](lark-base-data-query-guide.md)；字段类型、日期 value、DSL shape 以 [lark-base-data-query.md](lark-base-data-query.md) 为准。
|
||||
- `+data-query` 可返回聚合结果或维度字段行；维度字段行按字段组合去重且不返回 `record_id`，不能当逐条原始记录结果使用。
|
||||
- 需要输出逐条记录、记录定位或完整行级字段时，先用 `+data-query` 得到业务 key、分组值或候选字段组合，再用 `+record-list --filter-json` / `+record-get` 回查。
|
||||
|
||||
Example: 分组计数：
|
||||
|
||||
```bash
|
||||
lark-cli base +data-query \
|
||||
--base-token <base_token> \
|
||||
--dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Status","alias":"status"}],"measures":[{"field_name":"Status","aggregation":"count","alias":"count"}],"shaper":{"format":"flat"}}'
|
||||
```
|
||||
|
||||
Example: 过滤后汇总并取 TopN：
|
||||
|
||||
```bash
|
||||
lark-cli base +data-query \
|
||||
--base-token <base_token> \
|
||||
--dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Owner","alias":"owner"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"filters":{"type":1,"conjunction":"and","conditions":[{"field_name":"Status","operator":"is","value":["Done"]}]},"sort":[{"field_name":"total_amount","order":"desc"}],"pagination":{"limit":10},"shaper":{"format":"flat"}}'
|
||||
```
|
||||
|
||||
### 2.4 视图化与复用
|
||||
|
||||
一次性查询先用 `+record-list` / `+record-search` 的 filter/sort 验证。需要用户长期打开、共享或复用时，再把同一套 filter/sort 沉淀为视图。
|
||||
|
||||
Example: 将已验证的筛选排序写入视图：
|
||||
|
||||
```bash
|
||||
lark-cli base +view-set-filter \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--view-id <view_id> \
|
||||
--json @filter.json
|
||||
|
||||
lark-cli base +view-set-sort \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--view-id <view_id> \
|
||||
--json '{"sort_config":[{"field":"Priority","desc":true}]}'
|
||||
```
|
||||
|
||||
手动配置和视图配置的优先级：
|
||||
|
||||
1. `--filter-json` 覆盖 `--view-id` 保存的 view filter JSON。
|
||||
2. `--sort-json` 覆盖 `--view-id` 保存的 view sort config。
|
||||
3. 没有手动 filter/sort 时，`--view-id` 使用视图自身保存的 filter/sort。
|
||||
|
||||
### 2.5 关系查询与回查
|
||||
|
||||
- link 单元格通常是关联表 `record_id` 数组，不是用户可读内容，只是连接键。
|
||||
- 先用 `+field-list` 确认 link 字段的 `link_table`、业务唯一键和展示字段。
|
||||
- 从驱动表拿到候选记录后，用关联 `record_id` 到关联表 `+record-get` 批量读取记录内容。
|
||||
- 多跳关系逐跳建立 `record_id/key -> 用户可读字段` 映射；最终用户可读的信息。
|
||||
|
||||
禁止：
|
||||
|
||||
- 把 link `record_id` 当最终输出。
|
||||
- 用 `+record-search` 搜 link `record_id`。
|
||||
- 基于 ID、自增编号、link 值做语义猜测；禁止依赖字段先验、样本记忆补全交付输出。
|
||||
|
||||
## 3. Range & Pagination Contract
|
||||
|
||||
- `+record-list` 默认页、固定 `--limit`、本地 `jq`、shell 管道、手工浏览输出，都只覆盖已读取范围；超过 200 行不要把本地处理当作推荐路径。
|
||||
- `has_more=true`、存在下一页 offset/page token、或返回行数等于 page size，都表示可能还有未读取数据。
|
||||
- 对全局问题，只有 Base 云端查询服务已经通过 filter/sort/aggregate 收敛目标范围，或 `+data-query` 已在云端完成聚合、排序和限制时，才可以用有限返回形成结论。
|
||||
- 必须全量导出时，按 `+record-list` 分页语义串行翻页；不要并发调用 `+record-list`。
|
||||
|
||||
## 4. Final Answer Check
|
||||
|
||||
形成交付输出前必须能确认：
|
||||
|
||||
- 问题范围是局部样例、单点定位、全局原始记录、聚合分析、多表关联，还是查询后写入。
|
||||
- 筛选、排序、聚合是否发生在 Base 云端查询服务中，而不是本地 `jq` / shell 中。
|
||||
- 如果使用 `jq` / shell，本地输入是否是 200 行以内的小范围结果；超过 200 行是否已改用 Base 云端查询服务查询。
|
||||
- 如果使用 `+record-list` / `+record-search`，是否处理了 `has_more`，且投影包含业务 key 和解释字段。
|
||||
- 如果涉及关系查询，是否按 `record_id` 或业务 key 精确回查，交付输出是否来自关联表真实字段。
|
||||
- 交付输出能追溯到表、字段、筛选条件、排序/聚合条件和连接键。
|
||||
|
||||
任一项无法确认时，继续查询或明确说明只能得到局部结论。
|
||||
@ -0,0 +1,61 @@
|
||||
# Base data-query guide
|
||||
|
||||
This guide is the entry point for `+data-query`. Use it for common aggregation fewshots and command selection. For the complete DSL fields, operators, limits, and response details, use [lark-base-data-query.md](lark-base-data-query.md) as the DSL SSOT.
|
||||
|
||||
Before using `+data-query`, also follow [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) to confirm that the task really needs aggregation instead of record listing or a temporary view.
|
||||
|
||||
## When to use
|
||||
|
||||
Use `+data-query` when the user asks for server-side:
|
||||
|
||||
- group by / aggregation
|
||||
- sum, average, min, max, count, distinct count
|
||||
- filtered aggregation
|
||||
- sorted Top N or Bottom N
|
||||
- global statistical conclusions
|
||||
|
||||
`+data-query` can return dimension field rows, but those rows are grouped by dimension values and do not include `record_id`. Use `+record-list`, `+record-search`, or `+record-get` for row-level output, record identity, or full raw record details.
|
||||
|
||||
## Common Fewshots
|
||||
|
||||
Count records by a category field:
|
||||
|
||||
```bash
|
||||
lark-cli base +data-query \
|
||||
--base-token <base_token> \
|
||||
--dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Status","alias":"status"}],"measures":[{"field_name":"Status","aggregation":"count","alias":"count"}],"shaper":{"format":"flat"}}'
|
||||
```
|
||||
|
||||
Sum a number field by category and return Top 10:
|
||||
|
||||
```bash
|
||||
lark-cli base +data-query \
|
||||
--base-token <base_token> \
|
||||
--dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Region","alias":"region"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"sort":[{"field_name":"total_amount","order":"desc"}],"pagination":{"limit":10},"shaper":{"format":"flat"}}'
|
||||
```
|
||||
|
||||
Aggregate only records matching a filter:
|
||||
|
||||
```bash
|
||||
lark-cli base +data-query \
|
||||
--base-token <base_token> \
|
||||
--dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Owner","alias":"owner"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"filters":{"type":1,"conjunction":"and","conditions":[{"field_name":"Status","operator":"is","value":["Done"]}]},"shaper":{"format":"flat"}}'
|
||||
```
|
||||
|
||||
Use `tableName` when the table ID is unavailable but the table name is known:
|
||||
|
||||
```bash
|
||||
lark-cli base +data-query \
|
||||
--base-token <base_token> \
|
||||
--dsl '{"datasource":{"type":"table","table":{"tableName":"Orders"}},"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"shaper":{"format":"flat"}}'
|
||||
```
|
||||
|
||||
## Routing to the DSL SSOT
|
||||
|
||||
Read [lark-base-data-query.md](lark-base-data-query.md) when you need:
|
||||
|
||||
- the full DSL field reference
|
||||
- supported aggregations and field types
|
||||
- filter operator details
|
||||
- pagination and result limits
|
||||
- response shape and error recovery
|
||||
452
.agents/skills/lark-base/references/lark-base-data-query.md
Normal file
452
.agents/skills/lark-base/references/lark-base-data-query.md
Normal file
@ -0,0 +1,452 @@
|
||||
|
||||
# Base data-query DSL SSOT
|
||||
|
||||
> **入口指南**: [lark-base-data-query-guide.md](lark-base-data-query-guide.md) | **前置条件**: 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
本文档是 `+data-query` JSON DSL 的单一事实来源（SSOT），用于说明完整字段、操作符、限制、返回和错误恢复。常用 fewshot 与命令选择先读 [lark-base-data-query-guide.md](lark-base-data-query-guide.md)。
|
||||
|
||||
查询类任务还必须先遵守 [`lark-base-data-analysis-sop.md`](lark-base-data-analysis-sop.md)。`+data-query` 适合让筛选、分组、聚合、排序和 TopN 在 Base 云端查询服务中执行；不要用默认分页的 `+record-list` 或本地 `jq` 替代聚合查询。
|
||||
|
||||
## 限制
|
||||
|
||||
- **权限要求**（按文档类型分流）：
|
||||
- **普通多维表格**：调用者拥有文档的**阅读权限**即可
|
||||
- **高级权限多维表格**：调用者必须是文档管理员，拥有 **FA（Full Access / 完全访问权限）**
|
||||
|
||||
权限不足时返回权限错误。
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
# 按字段分组计数
|
||||
lark-cli base +data-query \
|
||||
--base-token MAGObxxxxx \
|
||||
--dsl '{
|
||||
"datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}},
|
||||
"dimensions": [{"field_name": "城市", "alias": "dim_city"}],
|
||||
"measures": [{"field_name": "城市", "aggregation": "count", "alias": "count"}],
|
||||
"shaper": {"format": "flat"}
|
||||
}'
|
||||
|
||||
# 带过滤条件 + 排序 + 限制条数
|
||||
lark-cli base +data-query \
|
||||
--base-token MAGObxxxxx \
|
||||
--dsl '{
|
||||
"datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}},
|
||||
"dimensions": [{"field_name": "城市", "alias": "dim_city"}],
|
||||
"measures": [{"field_name": "金额", "aggregation": "sum", "alias": "total_amount"}],
|
||||
"filters": {
|
||||
"type": 1,
|
||||
"conjunction": "and",
|
||||
"conditions": [{"field_name": "城市", "operator": "isNot", "value": [""]}]
|
||||
},
|
||||
"sort": [{"field_name": "total_amount", "order": "desc"}],
|
||||
"pagination": {"limit": 100},
|
||||
"shaper": {"format": "flat"}
|
||||
}'
|
||||
|
||||
# 使用 tableName（表名）代替 tableId
|
||||
lark-cli base +data-query \
|
||||
--base-token MAGObxxxxx \
|
||||
--dsl '{
|
||||
"datasource": {"type": "table", "table": {"tableName": "销售数据"}},
|
||||
"measures": [{"field_name": "金额", "aggregation": "sum", "alias": "total"}],
|
||||
"shaper": {"format": "flat"}
|
||||
}'
|
||||
|
||||
# 聚合或维度查询后如需读取逐条记录，先让 data-query 返回可回查的业务 key
|
||||
lark-cli base +data-query \
|
||||
--base-token MAGObxxxxx \
|
||||
--dsl '{
|
||||
"datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}},
|
||||
"dimensions": [{"field_name": "业务编号", "alias": "biz_key"}],
|
||||
"measures": [{"field_name": "指标值", "aggregation": "max", "alias": "max_value"}],
|
||||
"filters": {
|
||||
"type": 1,
|
||||
"conjunction": "and",
|
||||
"conditions": [{"field_name": "状态", "operator": "is", "value": ["有效"]}]
|
||||
},
|
||||
"sort": [{"field_name": "max_value", "order": "desc"}],
|
||||
"pagination": {"limit": 10},
|
||||
"shaper": {"format": "flat"}
|
||||
}'
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------------------------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token（base_token） |
|
||||
| `--dsl <json>` | 是 | LiteQuery Protocol JSON DSL 查询语句 |
|
||||
|
||||
## 如何从链接中提取参数
|
||||
|
||||
用户通常会提供如下 URL：
|
||||
|
||||
```
|
||||
https://example.feishu.cn/base/<base_token>?table=<table_id>
|
||||
```
|
||||
|
||||
- `--base-token`：取 `/base/` 后面的字符串
|
||||
- DSL 中的 `tableId`：取 `table=` 后面的值
|
||||
|
||||
## API 入参详情
|
||||
|
||||
**HTTP 方法和路径：**
|
||||
|
||||
```
|
||||
POST /open-apis/base/v3/bases/:base_token/data/query
|
||||
```
|
||||
|
||||
**Path 参数：**
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `base_token` | 是 | Base Token |
|
||||
|
||||
**Request Body — DSL 结构：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `datasource` | object | 是 | 数据源，包含 `type`（固定 `"table"`）和 `table` 对象 |
|
||||
| `datasource.table.tableId` | string | 二选一 | 目标数据表 ID |
|
||||
| `datasource.table.tableName` | string | 二选一 | 目标数据表名称 |
|
||||
| `dimensions` | Dimension[] | 否* | 分组维度字段（GROUP BY） |
|
||||
| `measures` | Measure[] | 否* | 聚合度量字段 |
|
||||
| `filters` | FilterGroup | 否 | 过滤条件（WHERE） |
|
||||
| `sort` | Sort[] | 否 | 排序规则 |
|
||||
| `pagination` | object | 否 | 限制返回行数，`{limit: N}`，最大 5000 |
|
||||
| `shaper` | object | 否 | 结果格式，固定 `{format: "flat"}` |
|
||||
|
||||
> \* `dimensions` 和 `measures` 至少填写一个。
|
||||
|
||||
**Dimension 字段：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `field_name` | string | 是 | 字段名称 |
|
||||
| `alias` | string | 否 | 输出列别名，需全局唯一 |
|
||||
|
||||
**Measure 字段：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `field_name` | string | 是 | 字段名称 |
|
||||
| `aggregation` | string | 是 | 聚合函数：`sum`、`avg`、`min`、`max`、`count`、`count_all`、`distinct_count` |
|
||||
| `alias` | string | 否 | 输出列别名，需全局唯一 |
|
||||
|
||||
**聚合函数适用字段类型：**
|
||||
|
||||
| 聚合函数 | 适用字段类型 |
|
||||
|----------|-------------|
|
||||
| `sum` / `avg` | `number` |
|
||||
| `min` / `max` | `number`、`datetime` |
|
||||
| `count` | 全字段适用，计数非空值 |
|
||||
| `count_all` | 全字段适用，计数所有行 |
|
||||
| `distinct_count` | 全字段适用 |
|
||||
|
||||
> `number` 包含 `style.type` 为 `progress` / `currency` / `rating` 等所有子类型。
|
||||
|
||||
**FilterGroup：**
|
||||
|
||||
```json
|
||||
{
|
||||
"filters": {
|
||||
"type": 1,
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{"field_name": "城市", "operator": "is", "value": ["北京"]}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `type` | int | 是 | 固定填 `1` |
|
||||
| `conjunction` | string | 否 | 条件组合逻辑：`"and"` 或 `"or"`，默认 `"and"` |
|
||||
| `conditions` | Condition[] | 否 | 条件列表 |
|
||||
|
||||
**Condition：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `field_name` | string | 是 | 字段名称（必须与表中字段名精确匹配） |
|
||||
| `operator` | string | 是 | 运算符（见下方运算符表） |
|
||||
| `value` | string[] | 是 | 条件值数组；`isEmpty`/`isNotEmpty` 时**必须**传空数组 `[]` |
|
||||
|
||||
**运算符：**
|
||||
|
||||
| 运算符 | 说明 |
|
||||
|--------|------|
|
||||
| `is` | 等于 |
|
||||
| `isNot` | 不等于 |
|
||||
| `contains` | 包含 |
|
||||
| `doesNotContain` | 不包含 |
|
||||
| `isEmpty` | 为空 |
|
||||
| `isNotEmpty` | 不为空 |
|
||||
| `isGreater` | 大于 |
|
||||
| `isGreaterEqual` | 大于等于 |
|
||||
| `isLess` | 小于 |
|
||||
| `isLessEqual` | 小于等于 |
|
||||
|
||||
> 各运算符的适用字段类型见下方「按各字段类型筛选时 value 格式详解」。
|
||||
|
||||
**按各字段类型筛选时 value 格式详解：**
|
||||
|
||||
*`text`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` / `isNot` / `contains` / `doesNotContain` | `["文本内容"]` | 仅 1 个 | `["Hello"]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`：文本无自然顺序，比较运算无意义。
|
||||
> `text` 也覆盖电话、超链接、邮箱、条码字段；通过 `style.type` 区分（`plain`（默认）/ `phone` / `url` / `email` / `barcode`），运算符集合一致。
|
||||
> 当 `style.type=url` 时，value 筛选的是链接显示名称，而不是 URL 本身。
|
||||
|
||||
*`number`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` / `isNot` / `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual` | `["数字字符串"]` | 仅 1 个 | `["23.4"]`、`["-100"]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> value 必须为合法数字的字符串形式。
|
||||
> `number` 也覆盖货币、进度、评分字段；通过 `style.type` 区分（`plain`（默认）/ `currency` / `progress` / `rating`），运算符集合一致，仅 value 解释不同：
|
||||
> - 当 `style.type=progress` 时，34% 对应 0.34 而不是 34。
|
||||
> - 当 `style.type=rating` 时，必须输入整数，代表评分。
|
||||
|
||||
*`auto_number`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` / `isNot` / `contains` / `doesNotContain` | `["编号字符串"]` | 仅 1 个 | `["00001"]` |
|
||||
| `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual` | `["编号字符串"]` | 仅 1 个 | `["00010"]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
*`select`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` / `isNot` | `["选项名"]` | **仅 1 个** | `["选项A"]` |
|
||||
| `contains` / `doesNotContain` | `["选项A", "选项B"]` | 可多个 | `["选项A", "选项B"]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`：选项为枚举值，无自然顺序。
|
||||
> 通过 `multiple` 区分单选（`multiple=false`，默认）/ 多选（`multiple=true`）。
|
||||
|
||||
*`user` / `created_by` / `updated_by`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------------------------|
|
||||
| `is` / `isNot` | `["用户ID1", "用户ID2"]` | **可多个** | `["ou_aaa", "ou_bbb"]` |
|
||||
| `contains` / `doesNotContain` | `["用户ID1", "用户ID2"]` | 可多个 | `["ou_aaa", "ou_bbb"]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`：人员无法比大小。
|
||||
> 用户 ID 使用 `open_id`（`ou_` 前缀），接口层会自动做 ID 转换。
|
||||
|
||||
*`group_chat`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` / `isNot` | `["群组ID1", "群组ID2"]` | 可多个 | `["oc_aaa", "oc_bbb"]` |
|
||||
| `contains` / `doesNotContain` | `["群组ID1", "群组ID2"]` | 可多个 | `["oc_aaa", "oc_bbb"]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`：群组无法比大小。
|
||||
|
||||
*`link`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` / `isNot` | `["recId1", "recId2"]` | 可多个 | `["recAAA", "recBBB"]` |
|
||||
| `contains` / `doesNotContain` | `["recId1", "recId2"]` | 可多个 | `["recAAA", "recBBB"]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`：关联记录无法比大小。
|
||||
> value 传关联表记录的 `record_id`。
|
||||
> 双向关联（创建时设 `bidirectional=true`）也属于 `link` 类型，运算符与单向关联一致。
|
||||
|
||||
*`location`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` / `isNot` / `contains` / `doesNotContain` | `["地址文本"]` | 仅 1 个 | `["北京市朝阳区..."]` |
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`：地理位置无自然顺序。
|
||||
> location 按 `full_address` 字符串筛选，不支持经纬度空间筛选；查城市/片区时优先用 `contains`，避免用 `is` 匹配短地址词。
|
||||
|
||||
*`checkbox`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `is` | `["true"]` 或 `["false"]` | 仅 1 个 | `["true"]` |
|
||||
|
||||
> 仅支持 `is` 运算符，不支持其他运算符。
|
||||
|
||||
*`datetime` / `created_at` / `updated_at`*
|
||||
|
||||
日期字段仅支持 `is`、`isEmpty`、`isNotEmpty`、`isGreater`、`isLess` 五种运算符。
|
||||
|
||||
value 使用预定义关键字机制，第一个元素为字符串常量名称：
|
||||
|
||||
| 关键字 | 说明 | value 格式 | 支持的运算符 |
|
||||
|--------|------|-----------|-------------|
|
||||
| `ExactDate` | 精确日期 | `["ExactDate", "1773187200000"]`（毫秒时间戳） | `is`、`isGreater`、`isLess` |
|
||||
| `Today` | 今天 | `["Today"]` | `is`、`isGreater`、`isLess` |
|
||||
| `Tomorrow` | 明天 | `["Tomorrow"]` | `is`、`isGreater`、`isLess` |
|
||||
| `Yesterday` | 昨天 | `["Yesterday"]` | `is`、`isGreater`、`isLess` |
|
||||
| `CurrentWeek` | 本周 | `["CurrentWeek"]` | 仅 `is` |
|
||||
| `LastWeek` | 上周 | `["LastWeek"]` | 仅 `is` |
|
||||
| `CurrentMonth` | 本月 | `["CurrentMonth"]` | 仅 `is` |
|
||||
| `LastMonth` | 上月 | `["LastMonth"]` | 仅 `is` |
|
||||
| `TheLastWeek` | 过去七天 | `["TheLastWeek"]` | 仅 `is` |
|
||||
| `TheNextWeek` | 未来七天 | `["TheNextWeek"]` | 仅 `is` |
|
||||
| `TheLastMonth` | 过去三十天 | `["TheLastMonth"]` | 仅 `is` |
|
||||
| `TheNextMonth` | 未来三十天 | `["TheNextMonth"]` | 仅 `is` |
|
||||
|
||||
> - **ExactDate 时区行为**：毫秒时间戳在实际筛选时会被转为**文档时区当天零点**，跨时区场景需注意日期可能偏移一天。
|
||||
> - **范围型关键字**（`CurrentWeek`、`LastWeek`、`CurrentMonth`、`LastMonth`、`TheLastWeek`、`TheNextWeek`、`TheLastMonth`、`TheNextMonth`）仅支持 `is` 运算符。
|
||||
> - **关键字大小写敏感**：`ExactDate`、`Today`、`CurrentWeek` 等首字母大写，写错大小写会导致校验失败。
|
||||
|
||||
*`attachment`*
|
||||
|
||||
| 运算符 | value 格式 | 元素个数 | 示例 |
|
||||
|--------|-----------|---------|------|
|
||||
| `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` |
|
||||
|
||||
> 附件字段仅支持 `isEmpty` 和 `isNotEmpty`，不支持其他运算符。
|
||||
|
||||
*`formula` / `lookup`*
|
||||
|
||||
公式和查找引用字段的运算符和 value 格式 **取决于其结果数据类型**，按结果类型参照上方对应字段类型的规则。例如：
|
||||
|
||||
- 公式结果为数字 → 按 `number` 规则
|
||||
- 公式结果为日期 → 按 `datetime` 规则
|
||||
- 公式结果为单选 → 按 `select` 规则
|
||||
|
||||
**Sort 字段：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `field_name` | string | 是 | 字段名称或 alias |
|
||||
| `order` | string | 否 | `"asc"`（默认）或 `"desc"` |
|
||||
|
||||
**Pagination 字段：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `limit` | int | 否 | 返回记录数上限，必须为正整数，最大 5000；不填时使用系统默认值。不支持 offset |
|
||||
|
||||
**Shaper 字段：**
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `format` | string | 是 | 固定为 `"flat"`，表示返回扁平化的对象数组 |
|
||||
|
||||
## API 出参详情
|
||||
|
||||
**成功时：**
|
||||
|
||||
```json
|
||||
{"code": 0, "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}, "msg": ""}
|
||||
```
|
||||
|
||||
**失败时：**
|
||||
|
||||
```json
|
||||
{"code": 800004006, "data": {"error": {"code": 800004006, ...}}, "msg": "DSL validation failed"}
|
||||
```
|
||||
|
||||
**Response 字段：**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | int | 状态码，0 为成功 |
|
||||
| `msg` | string | 错误信息 |
|
||||
| `data.main_data` | []object | 查询结果数组，每个元素为一行数据 |
|
||||
| `data.error` | object | 失败时的错误详情 |
|
||||
|
||||
每行数据的字段值封装在 CellValue 中：
|
||||
|
||||
```json
|
||||
{
|
||||
"dim_city": {
|
||||
"value": "北京"
|
||||
},
|
||||
"total_amount": {
|
||||
"value": 12345.00
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `value`：展示值（人员名称、选项名称、格式化日期等）
|
||||
|
||||
## 返回值
|
||||
|
||||
命令成功后输出 `data` 字段的内容：
|
||||
|
||||
```json
|
||||
{
|
||||
"main_data": [
|
||||
{
|
||||
"dim_city": {"value": "直营"},
|
||||
"measure_count": {"value": 1}
|
||||
},
|
||||
{
|
||||
"dim_city": {"value": "加盟"},
|
||||
"measure_count": {"value": 2}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 工作流
|
||||
|
||||
1. 确认 base-token 和 table-id
|
||||
2. **先查表结构**：执行 `lark-cli base +field-list --base-token <base_token> --table-id <table_id>`
|
||||
3. 从返回的字段列表中获取 field_name（DSL 中使用的字段名称）
|
||||
4. 根据字段信息构造 DSL JSON
|
||||
5. 执行 +data-query
|
||||
6. 解读返回结果：
|
||||
- 结果在 `data.main_data` 数组中，每个元素代表一行
|
||||
- 每行对象的 key 为 DSL 中指定的 `alias`；未指定 alias 时，key 为自动生成的列名
|
||||
- 每个 value 是 CellValue 对象，实际值在 `value` 字段中，如 `{"value": "北京"}` 或 `{"value": 12345.00}`
|
||||
- 失败时结果在 `data.error` 中，包含具体错误码和信息
|
||||
|
||||
## 与记录读取组合
|
||||
|
||||
`+data-query` 可返回聚合结果，也可在只传 `dimensions` 时返回维度字段行；这些维度行按字段组合去重，不包含 `record_id`，不能等同于逐条原始记录。需要输出聚合结果对应的原始记录字段、展示值、记录定位信息或关联表字段时，按以下方式组合：
|
||||
|
||||
1. 用 `+data-query` 在 Base 云端查询服务中完成全局筛选、分组、聚合、排序和 TopN，得到业务 key、分组值或候选字段组合。
|
||||
2. 如果已经拿到候选记录的 `record_id`，用 `+record-get` 读取逐条记录字段。
|
||||
3. 如果拿到的是结构化业务 key（例如编号、状态、日期、金额等），用 `+record-list --filter-json` 做精确过滤后读取；不要用 `+record-search` 代替结构化条件。
|
||||
4. 只有候选条件本身是文本展示值关键词时，才使用 `+record-search`，并用 `search_fields` 限定范围、`select_fields` 做投影。
|
||||
5. 若候选记录包含 link 字段，提取关联 `record_id` 后到关联表用 `+record-get` 批量读取展示字段。
|
||||
6. 最终回答业务字段，不要把内部 `record_id` 当作用户可读答案。
|
||||
|
||||
不要把 `data-query pagination.limit` 理解为分页扫描；它只限制 Base 云端查询服务返回的聚合结果行数，不支持 offset。需要全量原始记录导出时回到 data analysis SOP 的 `+record-list` 分页规则。
|
||||
|
||||
## 坑点
|
||||
|
||||
- ⚠️ **必须先查表结构**：DSL 的 `field_name` 必须与表中字段名称精确匹配（区分大小写），不能凭猜测构造。先用 `lark-cli base +field-list --base-token <base_token> --table-id <table_id>` 获取真实字段名
|
||||
- ⚠️ **权限要求按文档类型分流**：普通多维表格只需文档**阅读权限**；高级权限多维表格必须是文档管理员（**FA / Full Access**），否则返回权限错误
|
||||
- ⚠️ **alias 不支持中文**：dimensions 和 measures 的 alias 必须使用英文（如 `dim_city`、`total_amount`），中文 alias 会导致错误
|
||||
- ⚠️ **API 路径是 `base/v3`**：本接口路径为 `/open-apis/base/v3/bases/:base_token/data/query`，不是 `bitable/v1`。两者完全不同，用错版本号会返回 `[2200] Internal Error`
|
||||
- ⚠️ **`dimensions` 和 `measures` 至少填一个**：两个都不填会返回 DSL 校验错误
|
||||
- ⚠️ **`shaper` 必须为 `{"format": "flat"}`**：不填或填其他值会导致结果格式不可预期，建议始终显式指定
|
||||
- ⚠️ **数据表标识 `tableId` vs `tableName`**：datasource 中可以用 `tableId`（如 `tblXXX`）或 `tableName`（数据表的用户自定义显示名称），二选一，不要混用
|
||||
- ⚠️ **`pagination.limit` 最大 5000**：超过会报错，且不支持 offset，只支持 limit
|
||||
- ⚠️ **所有 alias 必须全局唯一**：dimensions 和 measures 之间的 alias 也不能重名
|
||||
- ⚠️ **不要用本地分页结果替代 data-query**：凡是全局计数、分组、聚合、排序 TopN，优先让 `+data-query` 在 Base 云端查询服务中执行；默认页 `+record-list` 后本地统计只能得到已读取范围内的结果
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base](../SKILL.md) — 多维表格全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
- [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) — 查询范围、选路、下推、分页、`+record-list` / `+record-search` 回查和关系查询 SOP
|
||||
- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
|
||||
- [lark-base-field-json.md](lark-base-field-json.md) — 字段类型与 JSON 结构
|
||||
103
.agents/skills/lark-base/references/lark-base-field-create.md
Normal file
103
.agents/skills/lark-base/references/lark-base-field-create.md
Normal file
@ -0,0 +1,103 @@
|
||||
# base +field-create
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
创建一个字段。
|
||||
|
||||
## Agent 最小工作流
|
||||
|
||||
1. 先判断是不是 `formula` / `lookup`。
|
||||
2. 如果是：先读对应 guide。
|
||||
3. 没读 guide 前，不要直接创建 formula / lookup 字段。
|
||||
4. 读完 guide 后，再构造 `--json` 并创建字段。
|
||||
5. 如果是跨表 formula / lookup，再补查**目标表**的结构。
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
lark-cli base +field-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--json '{"name":"预算","type":"number","style":{"type":"plain","precision":2}}'
|
||||
|
||||
lark-cli base +field-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Done","hue":"Green","lightness":"Light"}]}'
|
||||
|
||||
lark-cli base +field-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}'
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token |
|
||||
| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
|
||||
| `--json <body>` | 是 | 字段属性 JSON 对象 |
|
||||
## API 入参详情
|
||||
|
||||
**HTTP 方法和路径：**
|
||||
|
||||
```
|
||||
POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
|
||||
```
|
||||
|
||||
## JSON 值规范
|
||||
|
||||
- `--json` 必须是 **JSON 对象**，顶层直接传字段定义，不要再套一层。
|
||||
- 顶层最少包含：`name`、`type`。
|
||||
- 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。
|
||||
- `type` 不同，必填子字段不同：
|
||||
- `select`：`multiple` 控制是否多选，`options` 定义静态选项，`dynamic_options_source` 定义动态选项来源。静态与动态选项配置二选一，不能同时传。
|
||||
- `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。
|
||||
- `formula`：必须有 `expression`；先读 formula guide，再创建。
|
||||
- `lookup`：必须有 `from`、`select`、`where`；先读 lookup guide，再创建。
|
||||
|
||||
**正确（base +field-create）**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "状态",
|
||||
"type": "select",
|
||||
"multiple": false,
|
||||
"options": [
|
||||
{ "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
|
||||
{ "name": "Done", "hue": "Green", "lightness": "Light" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "负责人",
|
||||
"type": "user",
|
||||
"multiple": false,
|
||||
"description": "用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"
|
||||
}
|
||||
```
|
||||
|
||||
## 返回重点
|
||||
|
||||
- 返回 `field` 和 `created: true`。
|
||||
|
||||
## 工作流
|
||||
|
||||
|
||||
1. formula / lookup 字段必须先阅读对应指南；没读之前不要直接创建。
|
||||
|
||||
## 坑点
|
||||
|
||||
- ⚠️ 这是写入操作，执行前必须确认。
|
||||
- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base-field-json.md](lark-base-field-json.md) — 字段 JSON 规范（推荐）
|
||||
- [formula-field-guide.md](formula-field-guide.md) — formula 指南（创建公式必读）
|
||||
- [lookup-field-guide.md](lookup-field-guide.md) — lookup 指南（创建查找引用必读）
|
||||
489
.agents/skills/lark-base/references/lark-base-field-json.md
Normal file
489
.agents/skills/lark-base/references/lark-base-field-json.md
Normal file
@ -0,0 +1,489 @@
|
||||
# Base field JSON SSOT
|
||||
|
||||
> 适用命令：`lark-cli base +field-create`、`lark-cli base +field-update`
|
||||
|
||||
本文档定义 `+field-create` / `+field-update` 写字段时 `--json` 的推荐格式，是字段类型与字段 JSON 结构的 source of truth。目标不是复刻完整 schema，而是让 agent 稳定产出正确 payload。
|
||||
|
||||
## 1. 顶层规则（必须遵守）
|
||||
|
||||
- `--json` 必须是 JSON 对象。
|
||||
- 顶层统一使用：`type` + `name` + 类型特有字段。
|
||||
- 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
|
||||
- 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。
|
||||
- `+field-update` 使用同样的字段 JSON 结构，但语义是 `PUT`；这是高风险写入操作，建议先 `+field-get` 再按目标状态全量提交，并带 `--yes`。
|
||||
- `type=formula` 或 `type=lookup` 创建/更新前，必须先读对应 guide。
|
||||
|
||||
推荐示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "text",
|
||||
"name": "需求背景",
|
||||
"description": "记录需求背景与已知约束"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 字段速查
|
||||
|
||||
| 类型 | 最小必填字段 | 常见补充字段 |
|
||||
|------|--------------|-------------|
|
||||
| `text` | `type` `name` | `style.type` |
|
||||
| `number` | `type` `name` | `style` |
|
||||
| `select` | `type` `name` | `multiple` + `options`，或 `multiple` + `dynamic_options_source` |
|
||||
| `datetime` | `type` `name` | `style.format` |
|
||||
| `created_at` / `updated_at` | `type` `name` | `style.format` |
|
||||
| `user` / `group_chat` | `type` `name` | `multiple` |
|
||||
| `created_by` / `updated_by` | `type` `name` | 无 |
|
||||
| `link` | `type` `name` `link_table` | `bidirectional` `bidirectional_link_field_name` |
|
||||
| `formula` | `type` `name` `expression` | 无 |
|
||||
| `lookup` | `type` `name` `from` `select` `where` | `aggregate` |
|
||||
| `auto_number` | `type` `name` | `style.rules` |
|
||||
| `attachment` / `location` / `checkbox` | `type` `name` | 无 |
|
||||
|
||||
所有类型都可额外传 `description`；上表的“常见补充字段”只列类型特有配置。
|
||||
|
||||
## 3. 各类型写法
|
||||
|
||||
### 3.1 text
|
||||
|
||||
文本字段；电话、超链接、邮箱、条码也都属于 `text`，通过 `style.type` 区分。
|
||||
|
||||
最小写法（默认 `style.type` 为 `plain`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "text",
|
||||
"name": "标题"
|
||||
}
|
||||
```
|
||||
|
||||
常用写法：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "text",
|
||||
"name": "标题",
|
||||
"description": "主标题字段"
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "text",
|
||||
"name": "联系电话",
|
||||
"style": { "type": "phone" }
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "text",
|
||||
"name": "官网",
|
||||
"style": { "type": "url" }
|
||||
}
|
||||
```
|
||||
|
||||
常用 `style.type`：`plain`（默认）、`phone`、`url`、`email`、`barcode`。
|
||||
|
||||
### 3.2 number
|
||||
|
||||
数字字段；货币、进度、评分都属于 `number`，通过 `style.type` 区分。
|
||||
|
||||
最小写法（默认 `style.type` 为 `plain`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "number",
|
||||
"name": "工时"
|
||||
}
|
||||
```
|
||||
|
||||
`style` 是按 `type` 区分的对象；不同 `style.type` 的内部字段不一样，不要混传。
|
||||
|
||||
#### `plain`
|
||||
|
||||
支持字段：`precision`、`percentage`、`thousands_separator`
|
||||
|
||||
默认值 / 约束：
|
||||
- `precision` 取值 `0..4`，默认 `2`
|
||||
- `percentage` 默认 `false`
|
||||
- `thousands_separator` 默认 `false`
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "number",
|
||||
"name": "工时",
|
||||
"style": {
|
||||
"type": "plain",
|
||||
"precision": 2,
|
||||
"percentage": false,
|
||||
"thousands_separator": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `currency`
|
||||
|
||||
支持字段：`precision`、`currency_code`
|
||||
|
||||
默认值 / 约束：
|
||||
- `precision` 取值 `0..4`，默认 `2`
|
||||
- `currency_code` 必填，如 `CNY`、`USD`、`EUR`
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "number",
|
||||
"name": "预算",
|
||||
"style": { "type": "currency", "precision": 2, "currency_code": "CNY" }
|
||||
}
|
||||
```
|
||||
|
||||
#### `progress`
|
||||
|
||||
支持字段：`percentage`、`color`
|
||||
|
||||
默认值 / 约束：
|
||||
- `percentage` 默认 `true`
|
||||
- `color` 必填
|
||||
- `color` 可用：`Blue`、`Purple`、`DarkGreen`、`Green`、`Cyan`、`Orange`、`Red`、`Gray`、`WhiteToBlueGradient`、`WhiteToPurpleGradient`、`WhiteToOrangeGradient`、`GreenToRedGradient`、`RedToGreenGradient`、`BlueToPinkGradient`、`PinkToBlueGradient`、`SpectralGradient`
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "number",
|
||||
"name": "完成度",
|
||||
"style": { "type": "progress", "percentage": true, "color": "Blue" }
|
||||
}
|
||||
```
|
||||
|
||||
#### `rating`
|
||||
|
||||
支持字段：`icon`、`min`、`max`
|
||||
|
||||
默认值 / 约束：
|
||||
- `icon` 默认 `star`
|
||||
- `icon` 可用：`star`、`heart`、`thumbsup`、`fire`、`smile`、`lightning`、`flower`、`number`
|
||||
- `min` 取值 `0..1`，默认 `1`
|
||||
- `max` 取值 `1..10`，默认 `5`
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "number",
|
||||
"name": "评分",
|
||||
"style": { "type": "rating", "icon": "star", "min": 1, "max": 5 }
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 select
|
||||
|
||||
单选和多选都使用 `select`；用 `multiple` 区分。`multiple` 默认 `false`。静态选项用 `options`，动态选项用 `dynamic_options_source`；两者不要同时传。
|
||||
|
||||
#### 静态选项
|
||||
|
||||
支持字段：`multiple`、`options`
|
||||
|
||||
默认值 / 约束：
|
||||
- `multiple` 默认 `false`
|
||||
- `options` 最多 `10000` 项
|
||||
- `options[]` 结构是 `{name, hue?, lightness?}`
|
||||
- `options[].name` 必填
|
||||
- `options[].hue` 可用：`Red`、`Orange`、`Yellow`、`Lime`、`Green`、`Turquoise`、`Wathet`、`Blue`、`Carmine`、`Purple`、`Gray` 缺省值为 `Blue`
|
||||
- `options[].lightness` 可用：`Lighter`、`Light`、`Standard`、`Dark`、`Darker` 缺省值为 `Lighter`
|
||||
- 选项里没有 `id`，只有 `name`。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "select",
|
||||
"name": "状态",
|
||||
"multiple": false,
|
||||
"options": [
|
||||
{ "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
|
||||
{ "name": "Done", "hue": "Green", "lightness": "Light" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 动态选项
|
||||
|
||||
支持字段：`multiple`、`dynamic_options_source`
|
||||
|
||||
默认值 / 约束：
|
||||
- `multiple` 默认 `false`
|
||||
- `dynamic_options_source` 结构是 `{table_id, field_id}`
|
||||
- `dynamic_options_source.table_id` 填来源表 id 或表名
|
||||
- `dynamic_options_source.field_id` 填来源字段 id 或字段名
|
||||
- `dynamic_options_source` 仅创建支持；更新已有字段时不要传
|
||||
- 引用选项条件 / 级联筛选条件：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "select",
|
||||
"name": "动态状态",
|
||||
"multiple": false,
|
||||
"dynamic_options_source": {
|
||||
"table_id": "选项表",
|
||||
"field_id": "候选状态"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 datetime
|
||||
|
||||
手动填写的日期/时间字段。系统时间用 `created_at` / `updated_at`。
|
||||
|
||||
最小写法：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "datetime",
|
||||
"name": "截止时间"
|
||||
}
|
||||
```
|
||||
|
||||
支持字段：`style.format`
|
||||
|
||||
默认值 / 约束：
|
||||
- `style.format` 默认 `yyyy/MM/dd` 可用格式：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`yyyy/MM/dd HH:mm Z`、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm Z`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy`
|
||||
|
||||
常用写法：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "datetime",
|
||||
"name": "截止时间",
|
||||
"style": { "format": "yyyy-MM-dd HH:mm" }
|
||||
}
|
||||
```
|
||||
|
||||
### 3.5 created_at / updated_at
|
||||
|
||||
系统创建时间 / 系统更新时间字段；可配显示格式，但记录写入时应视为只读。
|
||||
|
||||
支持字段：`style.format`
|
||||
|
||||
默认值 / 约束：
|
||||
- `style.format` 默认 `yyyy/MM/dd`
|
||||
- 可用格式：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`yyyy/MM/dd HH:mm Z`、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm Z`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy`
|
||||
|
||||
```json
|
||||
{ "type": "created_at", "name": "创建时间" }
|
||||
```
|
||||
|
||||
```json
|
||||
{ "type": "updated_at", "name": "更新时间", "style": { "format": "yyyy/MM/dd HH:mm" } }
|
||||
```
|
||||
|
||||
### 3.6 user / group_chat
|
||||
|
||||
人员字段和群字段都支持 `multiple`。
|
||||
|
||||
默认值 / 约束：
|
||||
- `multiple` 默认 `true`
|
||||
|
||||
```json
|
||||
{ "type": "user", "name": "负责人", "multiple": true }
|
||||
```
|
||||
|
||||
```json
|
||||
{ "type": "group_chat", "name": "负责群", "multiple": true }
|
||||
```
|
||||
|
||||
### 3.7 created_by / updated_by
|
||||
|
||||
系统创建人 / 系统修改人字段；记录写入时应视为只读。
|
||||
|
||||
```json
|
||||
{ "type": "created_by", "name": "创建人" }
|
||||
```
|
||||
|
||||
```json
|
||||
{ "type": "updated_by", "name": "更新人" }
|
||||
```
|
||||
|
||||
### 3.8 link
|
||||
|
||||
关联字段；`link_table` 必填。
|
||||
|
||||
支持字段：`link_table`、`bidirectional`、`bidirectional_link_field_name`
|
||||
|
||||
默认值 / 约束：
|
||||
- `link_table` 必填
|
||||
- `link` 字段的单元格表示“当前记录关联到的对侧表记录集合”
|
||||
- `bidirectional` 默认 `false`
|
||||
- `bidirectional=true` 时，会在被关联表自动创建一个反向关联字段。任一侧记录的关联关系发生变更时，另一侧对应记录会自动同步更新
|
||||
- `bidirectional_link_field_name` 仅在 `bidirectional=true` 时使用
|
||||
- 关联字段筛选：这个功能在 Base 前端支持，属于 UI-only 属性，OpenAPI 里不支持，CLI 不能读取、创建或更新；不要根据接口返回缺失判断未配置
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "link",
|
||||
"name": "关联任务",
|
||||
"link_table": "任务表"
|
||||
}
|
||||
```
|
||||
|
||||
双向关联：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "link",
|
||||
"name": "关联任务",
|
||||
"link_table": "任务表",
|
||||
"bidirectional": true,
|
||||
"bidirectional_link_field_name": "反向关联"
|
||||
}
|
||||
```
|
||||
|
||||
更新时注意：
|
||||
- `link` 不允许转换为其他类型，其他类型也不能转换为 `link`。
|
||||
- 现有 `link` 字段的 `bidirectional` 不能改。
|
||||
|
||||
### 3.9 formula
|
||||
|
||||
公式字段；`expression` 必填。创建/更新前先读 [formula-field-guide.md](formula-field-guide.md) 学习公式语法。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "formula",
|
||||
"name": "合计",
|
||||
"expression": "1+1"
|
||||
}
|
||||
```
|
||||
|
||||
### 3.10 lookup
|
||||
|
||||
查找引用字段；`from`、`select`、`where` 必填，`aggregate` 可选。创建/更新前先读 [lookup-field-guide.md](lookup-field-guide.md)。
|
||||
|
||||
支持字段：`from`、`select`、`where`、`aggregate`
|
||||
|
||||
默认值 / 约束：
|
||||
- `from`、`select`、`where` 必填
|
||||
- `aggregate` 默认 `raw_value` 代表不进行聚合，直接返回 select 回的原始值
|
||||
- `aggregate` 可用：`raw_value`、`sum`、`average`、`counta`、`unique_counta`、`max`、`min`、`unique`
|
||||
- `where.logic` 默认 `and`，仅支持 `and` / `or`
|
||||
- `where.conditions` 至少 1 条
|
||||
- `conditions` 每项是三元组 `[field, op, value?]`
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "lookup",
|
||||
"name": "状态汇总",
|
||||
"from": "任务表",
|
||||
"select": "状态",
|
||||
"where": {
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["负责人", "==", { "type": "field_ref", "field": "当前负责人" }],
|
||||
["状态", "non_empty", null]
|
||||
]
|
||||
},
|
||||
"aggregate": "raw_value"
|
||||
}
|
||||
```
|
||||
|
||||
### 3.11 auto_number
|
||||
|
||||
自动编号字段；不写 `style.rules` 时使用默认规则：`NO.001`。
|
||||
|
||||
最小写法：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "auto_number",
|
||||
"name": "编号"
|
||||
}
|
||||
```
|
||||
|
||||
支持字段：`style.rules`
|
||||
|
||||
默认值 / 约束：
|
||||
- `style.rules` 是规则数组，数量 `1..9`
|
||||
- 默认规则：
|
||||
|
||||
```json
|
||||
{
|
||||
"style": {
|
||||
"rules": [
|
||||
{ "type": "text", "text": "NO." },
|
||||
{ "type": "incremental_number", "length": 3 }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `text`
|
||||
|
||||
支持字段：`text`
|
||||
|
||||
```json
|
||||
{ "type": "text", "text": "TASK-" }
|
||||
```
|
||||
|
||||
#### `incremental_number`
|
||||
|
||||
支持字段：`length`
|
||||
|
||||
默认值 / 约束：
|
||||
- `length` 取值 `1..9`
|
||||
|
||||
```json
|
||||
{ "type": "incremental_number", "length": 4 }
|
||||
```
|
||||
|
||||
#### `created_time`
|
||||
|
||||
支持字段：`date_format`
|
||||
|
||||
默认值 / 约束：
|
||||
- `date_format` 可用：`yyyyMMdd`、`yyyyMM`、`yyMM`、`MMdd`、`yyyy`、`MM`、`dd`
|
||||
|
||||
```json
|
||||
{ "type": "created_time", "date_format": "yyyyMMdd" }
|
||||
```
|
||||
|
||||
自定义规则：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "auto_number",
|
||||
"name": "编号",
|
||||
"style": {
|
||||
"rules": [
|
||||
{ "type": "text", "text": "TASK-" },
|
||||
{ "type": "created_time", "date_format": "yyyyMMdd" },
|
||||
{ "type": "incremental_number", "length": 4 }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.12 attachment / location / checkbox
|
||||
|
||||
```json
|
||||
{ "type": "attachment", "name": "附件" }
|
||||
```
|
||||
|
||||
```json
|
||||
{ "type": "location", "name": "位置" }
|
||||
```
|
||||
|
||||
写入必须使用 `{lng,lat}`。location 读回会包含 `full_address`；筛选和 `location -> text` 类型转换按 `full_address` 字符串处理，只有公式能访问坐标。
|
||||
|
||||
```json
|
||||
{ "type": "checkbox", "name": "完成" }
|
||||
```
|
||||
|
||||
## 4. 创建与更新
|
||||
|
||||
- `+field-create`：按目标字段配置直接构造 `--json`。
|
||||
- `+field-update`：使用同样的 JSON 结构，但语义是 `PUT`；建议先 `+field-get`，再按目标完整状态提交，并带 `--yes`。
|
||||
|
||||
## 5. 暂不支持字段
|
||||
|
||||
Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂时都没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
|
||||
|
||||
## 6. 易错点
|
||||
|
||||
- `select` 只有一个类型；不要写 `single_select` / `multi_select`，用 `multiple` 控制是否多选。
|
||||
- `number` 的精度、货币、进度、评分配置都放在 `style` 下，不要写顶层 `precision`。
|
||||
- `datetime` 是手动日期字段；系统时间请改用 `created_at` / `updated_at`。
|
||||
- `formula` / `lookup` 没读 guide 前不要直接写。
|
||||
171
.agents/skills/lark-base/references/lark-base-field-update.md
Normal file
171
.agents/skills/lark-base/references/lark-base-field-update.md
Normal file
@ -0,0 +1,171 @@
|
||||
# base +field-update
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
更新一个已有字段。
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
lark-cli base +field-update \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--field-id <field_id> \
|
||||
--json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Doing","hue":"Orange","lightness":"Light"},{"name":"Done","hue":"Green","lightness":"Light"}]}' \
|
||||
--yes
|
||||
|
||||
lark-cli base +field-update \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--field-id <field_id> \
|
||||
--json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人"}' \
|
||||
--yes
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token |
|
||||
| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
|
||||
| `--field-id <id_or_name>` | 是 | 字段 ID 或字段名 |
|
||||
| `--json <body>` | 是 | 字段属性 JSON 对象 |
|
||||
| `--yes` | 是 | 确认执行高风险字段更新 |
|
||||
|
||||
> 这是**高风险写入操作**。`+field-update` 使用 `PUT` 全量字段定义语义；改变字段类型或关键配置可能影响整列已有数据的解释、展示或可用性。CLI 层要求显式传 `--yes`；如果用户已经明确目标和期望更新，可直接执行并带上 `--yes`。
|
||||
|
||||
## API 入参详情
|
||||
|
||||
**HTTP 方法和路径：**
|
||||
|
||||
```
|
||||
PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
|
||||
```
|
||||
|
||||
## JSON 值规范
|
||||
|
||||
- `--json` 必须是 **JSON 对象**，顶层直接传字段定义。
|
||||
- 更新语义是 `PUT`（全量字段配置更新），不要只传零散片段；至少显式包含 `name`、`type`，并补齐该类型所需关键配置。
|
||||
- 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
|
||||
- `select` 更新时：`options` 仍按对象数组传，避免混入无效字段。
|
||||
- `link` 更新限制：
|
||||
- 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。
|
||||
- 现有 `link` 字段的 `bidirectional` 不能改。
|
||||
|
||||
**推荐更新示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "状态",
|
||||
"type": "select",
|
||||
"multiple": false,
|
||||
"options": [
|
||||
{ "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
|
||||
{ "name": "Doing", "hue": "Orange", "lightness": "Light" },
|
||||
{ "name": "Done", "hue": "Green", "lightness": "Light" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "负责人",
|
||||
"type": "user",
|
||||
"multiple": false,
|
||||
"description": "用于标记记录的直接负责人"
|
||||
}
|
||||
```
|
||||
|
||||
## 返回重点
|
||||
|
||||
- 返回 `field` 和 `updated: true`。
|
||||
|
||||
## 工作流
|
||||
|
||||
|
||||
1. 建议先用 `+field-get` 拉现状，再做最小化修改。
|
||||
2. `formula/lookup` 类型更新前先阅读对应指南。
|
||||
3. 如果这次更新会改变字段 `type` 先按下方“字段类型变更规则”判断能否执行。如果不修改 `type`，大多数场景都相对安全。
|
||||
|
||||
## 字段类型变更规则
|
||||
|
||||
字段类型变更采用白名单机制：**只允许白名单转换**；未命中白名单时，**不建议用 CLI 转换字段类型** 除非用户明确知道风险并同意。
|
||||
|
||||
### 允许直接转换 type
|
||||
|
||||
先 `+field-get` / `+field-list` 看结构，再抽样读值；只有命中以下规则时，转换才是比较安全的。
|
||||
|
||||
#### 相对安全
|
||||
|
||||
| 目标类型 | 允许的源类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `text` | `number`、`select`、`datetime`、`created_at`、`updated_at`、`location`（只保留 `full_address`）、`auto_number`、`checkbox` | 保留字符串表示；丢失原类型语义和结构化能力 |
|
||||
| `number` | `text`、`number`、`datetime`、`created_at`、`updated_at`、`checkbox` | 保留可解析的数字值；无法解析的值会变空，原文本格式会丢失 |
|
||||
| `datetime` | `text`、`number`、`datetime`、`created_at`、`updated_at` | 保留可解析的时间字符串和时间戳；无法解析的值会变空，原文本格式会丢失 |
|
||||
| `select` | `text -> select`、`number -> select`、`single select -> multi select` | 只有完全匹配目标选项名的值会转成对应选项；没匹配上的值会被丢弃 |
|
||||
|
||||
#### 可执行但会截断 / 重算
|
||||
|
||||
- `select(multi) -> select(single)`: 只保留第一个值，其余值会被丢弃。
|
||||
- `user(multi) -> user(single)`: 只保留第一个人员，其余值会被丢弃。
|
||||
- `group_chat(multi) -> group_chat(single)`: 只保留第一个群，其余值会被丢弃。
|
||||
|
||||
#### 无状态字段可直接转换
|
||||
|
||||
- `created_at`、`created_by`、`updated_at`、`updated_by`、`formula`、`lookup`: 这类字段值由系统或计算逻辑生成，不承载独立存储数据；可以执行类型转换，不必担心破坏原始记录值，但仍要做下游读回验证。
|
||||
|
||||
### 一律不要用 CLI 转换
|
||||
|
||||
以下场景全部视为黑名单；默认要求用户改到 Web 页面手动完成，或改走“新建字段 + 数据迁移”。
|
||||
|
||||
- `any -> checkbox`
|
||||
- `any -> user`
|
||||
- `any -> group_chat`
|
||||
- `any -> attachment`
|
||||
- `any -> location`
|
||||
- `link` 类型变更
|
||||
- 任意涉及动态 / 静态选项来源切换的 `select` 类型变更
|
||||
|
||||
### 可例外继续执行的场景
|
||||
|
||||
只有在**整列数据丢失可接受**时，才允许对黑名单场景例外执行。
|
||||
|
||||
- `EmptyColumn`: 该列为空
|
||||
- `FreshTableInit`: 新建空表初始化
|
||||
- `PrimaryFieldBootstrap`: 主列不能删，只能更新完成初始化
|
||||
- `ExplicitLossAccepted`: 用户明确接受整列数据丢失
|
||||
|
||||
不满足以上条件时，不要转换。
|
||||
|
||||
### 非白名单场景如何处理
|
||||
|
||||
- 命中白名单时：建议直接原地转换，再做读回验证。
|
||||
- 未命中白名单时：先询问用户是否仍要执行转换，并明确说明风险：
|
||||
- 无状态字段除外；这类字段可以直接转换
|
||||
- 可能整列变空
|
||||
- 可能只保留第一个值
|
||||
- 可能只保留字符串表示，丢失原类型语义和结构化能力
|
||||
- 可能影响视图 / 筛选 / 排序 / 公式 / lookup / 写入引用
|
||||
- 如果用户不接受风险：不要执行转换。
|
||||
|
||||
### 完成态验证
|
||||
|
||||
- `FieldReadback`: 读回字段结构，确认 `type` / `multiple` / `style` / `options`
|
||||
- `ValueReadback`: 抽样读回转换后的单元格值
|
||||
- `DownstreamReadback`: 若涉及看板 / 分组 / 排序 / lookup / 公式，继续读回结果
|
||||
- `CompletionRule`: 结构、值、下游能力都正确，才能回复“已完成”
|
||||
|
||||
## 坑点
|
||||
|
||||
- ⚠️ 这是全量字段属性更新语义，不是 patch。
|
||||
- ⚠️ 这是高风险写入操作，执行时必须带 `--yes`。
|
||||
- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。
|
||||
|
||||
## 参考
|
||||
|
||||
- 更新前读取当前字段，确认现有 `type` 和具体配置细节，再决定是原地更新还是新建字段迁移。
|
||||
- [lark-base-field-json.md](lark-base-field-json.md) — 字段 JSON 规范（推荐）
|
||||
- [formula-field-guide.md](formula-field-guide.md) — formula 指南（更新公式前必读）
|
||||
- [lookup-field-guide.md](lookup-field-guide.md) — lookup 指南（更新查找引用前必读）
|
||||
71
.agents/skills/lark-base/references/lark-base-form-detail.md
Normal file
71
.agents/skills/lark-base/references/lark-base-form-detail.md
Normal file
@ -0,0 +1,71 @@
|
||||
# base +form-detail
|
||||
|
||||
通过表单分享 token 读取表单详情。只读操作，适合在提交表单前解析题目结构、必填项、显示条件和附件提交所需的 Base token。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 用户给出 `/share/base/form/{shareToken}` 表单分享链接，先提取最后一段作为 `--share-token`。
|
||||
- 准备调用 `+form-submit` 前，必须先用 `+form-detail` 读取 `questions[]`。
|
||||
- 只知道分享链接、还不知道 `base-token` / `table-id` / `form-id` 时，用 `+form-detail`；已在 Base 内部管理表单时，才用 `+form-get`。
|
||||
|
||||
```bash
|
||||
lark-cli base +form-detail --share-token <share_token> --format pretty
|
||||
```
|
||||
|
||||
## 读取重点
|
||||
|
||||
`+form-detail` 返回的关键字段：
|
||||
|
||||
| 字段 | 用途 |
|
||||
|---|---|
|
||||
| `base_token` | 表单所属 Base；提交附件时必须传给 `+form-submit --base-token` |
|
||||
| `questions[].id` | 题目标识，通常对应字段 ID |
|
||||
| `questions[].title` | 提交时使用的字段名/题目名，以真实返回为准 |
|
||||
| `questions[].type` | 决定值格式；与字段类型和 `lark-base-cell-value.md` 对齐 |
|
||||
| `questions[].required` | 判断必填项 |
|
||||
| `questions[].filter` | 判断题目是否对当前提交可见；被隐藏的问题不要填写 |
|
||||
|
||||
题目除固定字段外，会按类型携带动态配置，例如 `select.options` / `select.multiple`、`number.style`、`datetime.style.format`、`user.multiple`、`link.link_table`、`formula.expression`、`lookup.from/select/where/aggregate`。提交前按返回结构构造值，不要猜题目类型或选项。
|
||||
|
||||
## filter 显示条件
|
||||
|
||||
`questions[].filter` 控制题目显示/隐藏：
|
||||
|
||||
```json
|
||||
{
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{"field_name": "是否携带家属", "operator": "is", "value": ["是"]},
|
||||
{"field_name": "参与人数", "operator": "isGreater", "value": [1]}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `conjunction` 为 `and` / `or`，表示条件全部满足或任一满足。
|
||||
- `conditions[].field_name` 引用其他题目的 `title`。
|
||||
- `conditions[].operator` 常见为 `is`、`isNot`、`contains`、`doesNotContain`、`isEmpty`、`isNotEmpty`、`isGreater`、`isGreaterEqual`、`isLess`、`isLessEqual`。
|
||||
- `isEmpty` / `isNotEmpty` 不需要 `value`。
|
||||
- 附件题目的 filter 只适合 `isEmpty` / `isNotEmpty`。
|
||||
|
||||
如果当前已填写值不满足某题目的 `filter`，该题目视为隐藏，不应放入 `+form-submit --json.fields` 或 `--json.attachments`。
|
||||
|
||||
## 与 form-submit 的关系
|
||||
|
||||
提交普通字段：
|
||||
|
||||
```bash
|
||||
lark-cli base +form-submit \
|
||||
--share-token <share_token> \
|
||||
--json '{"fields":{"姓名":"张三","评分":5}}'
|
||||
```
|
||||
|
||||
提交附件字段：
|
||||
|
||||
```bash
|
||||
lark-cli base +form-submit \
|
||||
--share-token <share_token> \
|
||||
--base-token <base_token_from_form_detail> \
|
||||
--json '{"fields":{"姓名":"张三"},"attachments":{"附件":["./report.pdf"]}}'
|
||||
```
|
||||
|
||||
附件字段不要写进 `fields`；放在顶层 `attachments`，值为本地文件路径数组。
|
||||
@ -0,0 +1,118 @@
|
||||
# base +form-questions-create
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
向多维表格表单/问卷中批量添加问题。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 添加一个文本必填问题
|
||||
lark-cli base +form-questions-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"type":"text","title":"您的姓名是？","required":true}]'
|
||||
|
||||
# 添加多个问题（按顺序排列）
|
||||
lark-cli base +form-questions-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[
|
||||
{"type":"text","title":"您的姓名是？","required":true},
|
||||
{"type":"text","title":"您的联系方式是？","required":false}
|
||||
]'
|
||||
|
||||
# 添加单选题（带选项）
|
||||
lark-cli base +form-questions-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"type":"select","title":"满意度评价","required":true,"multiple":false,"options":[{"name":"非常满意","hue":"Green"},{"name":"满意","hue":"Blue"},{"name":"一般","hue":"Yellow"}]}]'
|
||||
|
||||
# 添加评分题
|
||||
lark-cli base +form-questions-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"type":"number","title":"服务评分","style":{"type":"rating","icon":"star","min":1,"max":5}}]'
|
||||
|
||||
# 添加带描述的问题（纯文本）
|
||||
lark-cli base +form-questions-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"type":"text","title":"您的姓名","description":"请填写真实姓名"}]'
|
||||
# 添加带描述的问题（含链接）
|
||||
lark-cli base +form-questions-create \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"type":"text","title":"反馈建议","description":"更多详情请查看[帮助文档](https://example.com/help)"}]'
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token（base_token） |
|
||||
| `--table-id <id>` | 是 | 数据表 ID |
|
||||
| `--form-id <id>` | 是 | 表单 ID |
|
||||
| `--questions <json>` | 是 | 问题 JSON 数组，最多 10 个（见下方格式） |
|
||||
| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
|
||||
| `--as` | 否 | 身份：user（默认）\| bot |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## `--questions` 格式
|
||||
|
||||
每个问题对象支持以下字段：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|-----------------------|------|------|
|
||||
| `title` | **是** | 问题标题（字段名） |
|
||||
| `type` | **是** | 题目类型：`text`、`number`、`select`、`datetime`、`user`、`attachment`、`location` |
|
||||
| `description` | 否 | 问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
|
||||
| `required` | 否 | 是否必填（true/false） |
|
||||
| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
|
||||
| `multiple` | 否 | 是否多选（`select`/`user` 类型有效，bool） |
|
||||
| `options` | 否 | 选项列表（仅 `select` 有效）：`[{"name":"选项1","hue":"Blue"}]`，hue 可选：`Red`/`Orange`/`Yellow`/`Green`/`Blue`/`Purple`/`Gray` |
|
||||
| `style` | 否 | 字段样式配置（见下方说明） |
|
||||
|
||||
### `style` 字段说明
|
||||
|
||||
| 类型 | style 结构 | 说明 |
|
||||
|------|------|------|
|
||||
| `text` | `{"type":"plain"}` | 当前仅支持 `plain` |
|
||||
| `number` | `{"type":"plain","precision":2}` | precision 为小数位数 |
|
||||
| `number`（评分） | `{"type":"rating","icon":"star","min":1,"max":5}` | icon 可选：`star`/`heart`/`thumbsup`/`fire`/`smile`/`lightning`/`flower`/`number` |
|
||||
| `datetime` | `{"format":"yyyy/MM/dd"}` | format 可选：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy` |
|
||||
|
||||
## 输出格式
|
||||
|
||||
返回创建成功的问题列表：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"items": [
|
||||
{"id": "q_001", "title": "您的姓名是？", "required": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 工作流
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作** — 执行前必须向用户确认。
|
||||
|
||||
1. 先用 `+form-questions-list` 查看现有问题
|
||||
2. 确认要添加的问题内容
|
||||
3. 执行命令并报告新建的问题 ID
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base](../SKILL.md) — 多维表格全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
@ -0,0 +1,92 @@
|
||||
# base +form-questions-update
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
批量更新多维表格表单/问卷中的问题（标题、描述、是否必填）。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 更新一个问题的标题
|
||||
lark-cli base +form-questions-update \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"id":"q_001","title":"您的真实姓名是？"}]'
|
||||
|
||||
# 同时更新多个问题
|
||||
lark-cli base +form-questions-update \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[
|
||||
{"id":"q_001","title":"姓名（必填）","required":true},
|
||||
{"id":"q_002","title":"联系方式","required":false}
|
||||
]'
|
||||
|
||||
# 更新问题描述（纯文本）
|
||||
lark-cli base +form-questions-update \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"id":"q_001","description":"请填写您的真实姓名"}]'
|
||||
# 更新问题描述（含链接）
|
||||
lark-cli base +form-questions-update \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--form-id <form_id> \
|
||||
--questions '[{"id":"q_001","description":"更多说明请参考[帮助文档](https://example.com/help)"}]'
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token（base_token） |
|
||||
| `--table-id <id>` | 是 | 数据表 ID |
|
||||
| `--form-id <id>` | 是 | 表单 ID |
|
||||
| `--questions <json>` | 是 | 问题更新 JSON 数组，最多 10 个（见下方格式） |
|
||||
| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
|
||||
| `--as` | 否 | 身份：user（默认）\| bot |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## `--questions` 格式
|
||||
|
||||
每个问题对象必须包含 `id`，其余字段按需传入：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | **是** | 问题 ID（field_id），不可修改 |
|
||||
| `title` | 否 | 新的问题标题 |
|
||||
| `description` | 否 | 新的问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
|
||||
| `required` | 否 | 是否必填 |
|
||||
| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
|
||||
|
||||
## 输出格式
|
||||
|
||||
返回更新后的问题列表：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"items": [
|
||||
{"id": "q_001", "title": "姓名（必填）", "required": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 工作流
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作** — 执行前必须向用户确认。
|
||||
|
||||
1. 先用 `+form-questions-list` 获取现有问题及其 `id`
|
||||
2. 构造包含 `id` 的更新数组
|
||||
3. 执行命令并报告更新结果
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base](../SKILL.md) — 多维表格全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
170
.agents/skills/lark-base/references/lark-base-form-submit.md
Normal file
170
.agents/skills/lark-base/references/lark-base-form-submit.md
Normal file
@ -0,0 +1,170 @@
|
||||
# base +form-submit
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
通过表单分享链接填写并提交多维表格表单。仅支持分享模式（share_token），支持填写普通字段值和上传本地文件作为附件。
|
||||
|
||||
## 填写前必读：先获取表单详情
|
||||
|
||||
**在调用 `+form-submit` 之前，必须先使用 `+form-detail` 获取表单详情。** 原因如下：
|
||||
|
||||
1. **字段类型匹配**：每个题目的 `type` 决定了值的格式（文本、数字、选项、人员、日期等），需根据类型正确构造 `fields` 中的值
|
||||
2. **必填校验**：通过 `questions[].required` 判断哪些题目为必填项，避免遗漏
|
||||
3. **显示条件过滤**：部分题目带有 `filter`（显示/隐藏逻辑），需根据用户已填的其他题目值判断该题目是否应该出现——**不应填写被 filter 隐藏的题目**
|
||||
4. **获取 base_token（附件场景必用）**：`+form-detail` 返回的 `data.base_token` 是该表单所属的多维表格标识。当表单包含附件字段时，提交时必须通过 `--base-token` 传入此值，因为附件需要上传到该 Base 的 Drive Media 中
|
||||
|
||||
典型流程：
|
||||
|
||||
```bash
|
||||
# 1️⃣ 先获取表单详情，了解所有题目
|
||||
lark-cli base +form-detail --share-token <share_token>
|
||||
|
||||
# 2️⃣ 根据返回的 questions 列表，按 type 格式化值、检查 required、判断 filter 条件
|
||||
|
||||
# 3️⃣ 再提交
|
||||
lark-cli base +form-submit \
|
||||
--share-token <share_token> \
|
||||
--json '{"fields":{...}}'
|
||||
```
|
||||
|
||||
`+form-detail` 的返回中要重点读取 `questions[].type`、`questions[].required`、题目 `filter` 和附件场景所需的 `data.base_token`。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 基本提交（填写普通字段）
|
||||
lark-cli base +form-submit \
|
||||
--share-token <share_token> \
|
||||
--json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}'
|
||||
|
||||
# 带附件提交（需要额外提供 --base-token）
|
||||
lark-cli base +form-submit \
|
||||
--share-token <share_token> \
|
||||
--base-token <base_token> \
|
||||
--json '{
|
||||
"fields": {"服务评分": 5, "评价内容": "好"},
|
||||
"attachments": {
|
||||
"附件字段名": ["./report.pdf", "./photo.png"],
|
||||
"另一个附件字段": ["./doc.docx"]
|
||||
}
|
||||
}'
|
||||
|
||||
# 使用应用身份（bot）
|
||||
lark-cli base +form-submit \
|
||||
--share-token <share_token> \
|
||||
--json '{"fields":{...}}' \
|
||||
--as bot
|
||||
|
||||
# 预览 API 调用（不实际执行）
|
||||
lark-cli base +form-submit \
|
||||
--share-token <share_token> \
|
||||
--json '{"fields":{...}}' \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--share-token <token>` | 是 | 表单分享 Token（必填），从表单分享链接中提取 |
|
||||
| `--base-token <token>` | 条件必填 | Base token；**当 `--json` 包含 `attachments` 时必须提供**，用于将附件上传到 Base Drive Media |
|
||||
| `--json <json>` | 是 | JSON 对象，包含 `"fields"`（普通字段值）和 `"attachments"`（附件上传），详见下方说明 |
|
||||
| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
|
||||
| `--as` | 否 | 身份：user（默认）\| bot |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
### --json 结构说明
|
||||
|
||||
`--json` 是一个 JSON 对象，包含两个部分：
|
||||
|
||||
#### fields（普通字段）
|
||||
|
||||
`fields` 中的单元格值写法与 [`lark-base-cell-value.md`](lark-base-cell-value.md) 完全对齐，填写前应先阅读该文档了解各类型的构造规则：
|
||||
|
||||
```json
|
||||
{
|
||||
"文本字段": "Hello World",
|
||||
"电话字段": "13800000000",
|
||||
"超链接字段": "https://example.com",
|
||||
"数字字段": 12.5,
|
||||
"单选字段": "选项A",
|
||||
"多选字段": ["选项A", "选项B"],
|
||||
"时间字段": "2026-04-27 14:30:00",
|
||||
"复选框字段": true,
|
||||
"人员字段": [{ "id": "ou_7094d131420c8749632145f08fbf114a" }],
|
||||
"关联字段": [{ "id": "recXXXXXXXXXXXX" }],
|
||||
"地理位置字段": { "lng": 116.397428, "lat": 39.90923 }
|
||||
}
|
||||
```
|
||||
|
||||
> **注意：附件类型字段不要写在 `fields` 里。** `fields` 中不包含附件，附件有独立的填写方式，见下方「attachments（附件上传）」章节。
|
||||
|
||||
> 自动编号、公式、创建/修改人、创建/修改时间等系统字段会自动填入，无需手动传入。
|
||||
|
||||
#### attachments（附件上传）
|
||||
|
||||
**附件字段的填写方式与 `fields` 中的普通单元格完全不同**，不能在 `fields` 里传 `file_token` 或其他附件格式。必须将附件字段单独放在 `--json` 的顶层 `attachments` 对象中，值为**本地文件路径数组**（不是 token）：
|
||||
|
||||
```json
|
||||
{
|
||||
"attachments": {
|
||||
"附件字段名": ["./report.pdf", "./photo.png"],
|
||||
"另一个附件字段": ["./doc.docx"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
CLI 收到路径后会自动完成以下流程：
|
||||
1. 校验所有文件（存在性、大小 ≤2GB、常规文件）
|
||||
2. 并行上传到 Base Drive Media（并发上限 5，跨字段重复路径自动去重）
|
||||
3. 获取 `file_token` 后合并到最终表单提交内容中
|
||||
|
||||
> 与 [`lark-base-cell-value.md`](lark-base-cell-value.md) 中 Record 场景的附件写法不同：Record 写入时附件走独立的 `+record-upload-attachment` 命令；而 `+form-submit` 只需在 `attachments` 中传本地路径，上传由 CLI 内部自动完成。
|
||||
|
||||
### 从分享链接提取 share-token
|
||||
|
||||
用户提供形如以下格式的表单分享链接时：
|
||||
|
||||
```
|
||||
https://www.example.com/share/base/form/shrbcvST8eZy0vk8zjVZ1CAXNye
|
||||
```
|
||||
|
||||
**提取方式：** 取 URL 路径最后一段作为 `--share-token`。
|
||||
|
||||
以上述链接为例：
|
||||
|
||||
- `share-token` = `shrbcvST8eZy0vk8zjVZ1CAXNye`
|
||||
|
||||
```bash
|
||||
lark-cli base +form-submit \
|
||||
--share-token shrbcvST8eZy0vk8zjVZ1CAXNye \
|
||||
--json '{"fields":{...}}'
|
||||
```
|
||||
|
||||
## 输出格式
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `can_submit_again` | bool | 是否可以再次填写 |
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"can_submit_again": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 提示
|
||||
|
||||
- 本命令仅支持通过表单分享链接（share_token）提交，不支持通过 base_token + table_id + view_id 方式提交
|
||||
- **当 `--json` 包含 `attachments` 时，必须额外提供 `--base-token`**，因为附件上传到 Base Drive Media 需要指定目标 Base
|
||||
- 附件字段只需在 `--json.attachments` 中提供本地路径即可，CLI 自动完成校验、并行上传、Token 获取和合并写入
|
||||
- 限流：单应用 20 QPS，单用户 5 QPS
|
||||
- 权限要求：`base:form:update`；使用 attachments 时还需 `docs:document.media:upload`
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base](../SKILL.md) — 多维表格全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
@ -0,0 +1,57 @@
|
||||
# base +record-batch-create
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
批量创建记录。
|
||||
|
||||
## 适用场景（重点）
|
||||
|
||||
- 适合导入 CSV / Excel、外部系统一次性写入新数据。
|
||||
- 先把输入数据映射到合适的字段类型，再组装 `fields + rows`。
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> \
|
||||
--json '{"fields":["标题","状态"],"rows":[["任务 A","Open"],["任务 B","Done"]]}'
|
||||
|
||||
lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> --json @batch-create.json
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token |
|
||||
| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
|
||||
| `--json <body>` | 是 | 批量创建请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
|
||||
|
||||
## API
|
||||
|
||||
`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_create`
|
||||
|
||||
## `--json` 结构
|
||||
|
||||
本节只说明 `+record-batch-create` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
|
||||
|
||||
对象形态：`{"fields":[...],"rows":[...]}`。
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `fields` | `string[]` | 是 | 字段 ID 或字段名数组 |
|
||||
| `rows` | `CellValue[][]` | 是 | 二维数组，每一行按 `fields` 同序给 cell；单次最多 200 行 |
|
||||
|
||||
## 返回重点
|
||||
|
||||
返回 `fields`、`field_id_list`、`record_id_list`、`data`，其中 `data` 与 `fields` 列顺序对齐。
|
||||
|
||||
## 坑点
|
||||
|
||||
- `fields` 与每行 `rows` 的列顺序必须一一对应。
|
||||
- 空单元格必须显式用 `null` 填充。
|
||||
- 单次最多 200 行，超出需分批写入。
|
||||
- select 写入未知选项时平台可能自动新增选项；如果不是要新增选项，先确认真实选项名。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
|
||||
@ -0,0 +1,52 @@
|
||||
# base +record-batch-update (batch update)
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
批量更新记录（将同一份 `patch` 批量应用到一批 `record_id_list`）。
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> \
|
||||
--json '{"record_id_list":["<record_id>"],"patch":{"状态":"完成"}}'
|
||||
|
||||
lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> --json @batch-update.json
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token |
|
||||
| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
|
||||
| `--json <body>` | 是 | 批量更新请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
|
||||
|
||||
## API
|
||||
|
||||
`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_update`
|
||||
|
||||
## `--json` 结构
|
||||
|
||||
本节只说明 `+record-batch-update` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
|
||||
|
||||
对象形态：`{"record_id_list":[...],"patch":{...}}`。
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `record_id_list` | `string[]` | 是 | 要更新的记录 ID 列表（单次最多 200 条） |
|
||||
| `patch` | `Map<FieldNameOrID, CellValue>` | 是 | 字段更新对象；key 是字段名或字段 ID，value 是 `CellValue`；同一份 `patch` 会应用到 `record_id_list` 内所有记录 |
|
||||
|
||||
## 返回重点
|
||||
|
||||
返回 `record_id_list`、`update`，可选返回 `ignored_fields`；`update` 可能为空对象。
|
||||
|
||||
## 坑点
|
||||
|
||||
- 这是“同值批量更新”：所有 `record_id_list` 都应用同一份 `patch`。
|
||||
- `record_id_list` 最大 200 条，超过会被接口校验拒绝。
|
||||
- 命令不会自动做字段/行映射转换，传什么就发什么。
|
||||
- 如果 `patch` 包含只读字段，返回里可能出现 `ignored_fields`；这些字段不会被更新。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
|
||||
@ -0,0 +1,43 @@
|
||||
# base +record-history-list
|
||||
|
||||
查询单条记录的变更历史。它返回历史事件，不返回记录当前值，也不支持整表审计扫描。
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
lark-cli base +record-history-list \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--record-id <record_id>
|
||||
|
||||
lark-cli base +record-history-list \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--record-id <record_id> \
|
||||
--page-size 30 \
|
||||
--max-version <next_max_version>
|
||||
```
|
||||
|
||||
## 返回解释
|
||||
|
||||
- 历史条目通常按版本号降序返回，最新在前。
|
||||
- 每条历史包含版本号、操作人、操作时间、操作类型和字段变更。
|
||||
- `create_time` 是秒级 Unix 时间戳。
|
||||
- `field_changes` 描述字段变更，重点看字段名/字段类型、`before` 和 `after`。
|
||||
- `activity_type` 常见值：`create`（创建记录）、`update`（编辑记录）、`delete`（删除记录）。
|
||||
|
||||
以下字段类型的变化可能不会出现在 `field_changes` 中：
|
||||
|
||||
- 计算字段：`formula`、`lookup`
|
||||
- 系统字段：自动编号、创建时间、创建人、修改时间、修改人
|
||||
|
||||
## 翻页
|
||||
|
||||
- 首次请求不传 `--max-version`。
|
||||
- 如果返回 `has_more=true`，取返回中的 `next_max_version` 作为下一次请求的 `--max-version`。
|
||||
- `--page-size` 默认 30，最大 50。
|
||||
|
||||
## 注意
|
||||
|
||||
- `table-id` 和 `record-id` 必须来自同一张表。
|
||||
- 这是单条记录历史，不是表级审计；需要查多条记录时串行调用。
|
||||
@ -0,0 +1,63 @@
|
||||
# base +record-upsert
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
创建记录，或在带 `--record-id` 时更新记录。
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
# 创建记录
|
||||
lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> \
|
||||
--json '{"项目名称":"Apollo","状态":"进行中"}'
|
||||
|
||||
# 更新记录
|
||||
lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --record-id <record_id> \
|
||||
--json '{"项目名称":"Apollo","状态":"完成","完成时间":"2026-03-24 10:00:00"}'
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--base-token <token>` | 是 | Base Token |
|
||||
| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
|
||||
| `--record-id <id>` | 否 | 传入时走更新，不传时走创建 |
|
||||
| `--json <body>` | 是 | 字段写入对象，类型 `Map<FieldNameOrID, CellValue>` |
|
||||
|
||||
## API
|
||||
|
||||
- 创建：`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records`
|
||||
- 更新：带 `--record-id` 时改走 `PATCH /records/:record_id`
|
||||
|
||||
## `--json` 结构
|
||||
|
||||
- `--json` 必须是 **JSON object map**，形状是 `Map<FieldNameOrID, CellValue>`。
|
||||
- key 是字段名或字段 ID；value 是该字段的 `CellValue`。
|
||||
- 一次请求里同一字段只用一种标识，避免重复写入冲突。
|
||||
- 写入前先 `+field-list` 确认字段类型和字段名/ID。
|
||||
- CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
|
||||
|
||||
```json
|
||||
{
|
||||
"项目名称": "Apollo",
|
||||
"状态": "进行中",
|
||||
"完成时间": "2026-03-24 10:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
## 返回重点
|
||||
|
||||
- 创建时返回 `record` 和 `created: true`。
|
||||
- 更新时返回 `record` 和 `updated: true`。
|
||||
- 如果写入了 `formula / lookup / created_at / updated_at / created_by / updated_by` 等只读字段，返回里可能出现 `ignored_fields`，这些字段不会被更新。
|
||||
|
||||
## 坑点
|
||||
|
||||
- 有 `--record-id` 就一定更新；不传就一定创建，不会自动查重或按业务键 upsert。
|
||||
- select 写入未知选项时平台可能自动新增选项；如果不是要新增选项，先用 `+field-list` / `+field-search-options` 确认真实选项名。
|
||||
- 这是写入操作，执行前必须确认目标表和字段。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
|
||||
65
.agents/skills/lark-base/references/lark-base-role-guide.md
Normal file
65
.agents/skills/lark-base/references/lark-base-role-guide.md
Normal file
@ -0,0 +1,65 @@
|
||||
# Base advanced permission and role guide
|
||||
|
||||
This guide is the entry point for Base advanced permissions and roles. Use it to choose commands and understand safety boundaries. For the permission JSON itself, use [role-config.md](role-config.md) as the SSOT.
|
||||
|
||||
## Command selection
|
||||
|
||||
| Goal | Command | Notes |
|
||||
|------|---------|-------|
|
||||
| Enable advanced permissions | `+advperm-enable` | Required before creating or updating roles. Caller must be a Base admin. |
|
||||
| Disable advanced permissions | `+advperm-disable` | High-risk write. Disabling invalidates existing custom roles. |
|
||||
| Locate roles | `+role-list` | Returns role summaries. Use `+role-get` for full config. |
|
||||
| Inspect one role | `+role-get` | Use before updating a role or deciding whether a role can be deleted. |
|
||||
| Create a custom role | `+role-create` | Supports `custom_role` only. Read [role-config.md](role-config.md) before constructing `--json`. |
|
||||
| Update a role | `+role-update` | Delta merge. Read current config first, then send only intended changes. |
|
||||
| Delete a role | `+role-delete` | Custom roles only. System roles cannot be deleted. |
|
||||
|
||||
## Safety boundaries
|
||||
|
||||
- Role operations require advanced permissions to be enabled and the caller to be a Base admin.
|
||||
- `+role-create` creates custom roles only.
|
||||
- `+role-delete` is only for custom roles. System roles such as editor/reader can be configured within supported limits, but cannot be deleted.
|
||||
- `+role-update` uses delta merge: omitted fields remain unchanged, but identity fields such as `role_name` and `role_type` should match the current target role.
|
||||
- `+advperm-disable` invalidates existing custom roles; confirm the target Base and user intent before passing `--yes`.
|
||||
|
||||
## Common Fewshots
|
||||
|
||||
Use these fewshots for simple role changes. For table, field, record, dashboard, docx, or filter permission details, switch to [role-config.md](role-config.md).
|
||||
|
||||
Create a custom role that keeps copy/download disabled:
|
||||
|
||||
```bash
|
||||
lark-cli base +role-create \
|
||||
--base-token <base_token> \
|
||||
--json '{"role_name":"Reviewer","role_type":"custom_role","base_rule_map":{"copy":false,"download":false}}'
|
||||
```
|
||||
|
||||
Rename a role while preserving its type:
|
||||
|
||||
```bash
|
||||
lark-cli base +role-update \
|
||||
--base-token <base_token> \
|
||||
--role-id <role_id> \
|
||||
--json '{"role_name":"Finance Reviewer","role_type":"custom_role"}' \
|
||||
--yes
|
||||
```
|
||||
|
||||
Grant read-only access to one table:
|
||||
|
||||
```bash
|
||||
lark-cli base +role-update \
|
||||
--base-token <base_token> \
|
||||
--role-id <role_id> \
|
||||
--json '{"role_name":"Finance Reviewer","role_type":"custom_role","table_rule_map":{"Orders":{"perm":"read_only"}}}' \
|
||||
--yes
|
||||
```
|
||||
|
||||
## JSON SSOT
|
||||
|
||||
Use [role-config.md](role-config.md) for:
|
||||
|
||||
- `AdvPermBaseRoleConfig` top-level structure.
|
||||
- `base_rule_map`, `table_rule_map`, `dashboard_rule_map`, and `docx_rule_map`.
|
||||
- Table, view, field, record, dashboard, and docx permission values.
|
||||
- Filter permission JSON.
|
||||
- Default permission strategy and risk rules.
|
||||
189
.agents/skills/lark-base/references/lark-base-view-set-filter.md
Normal file
189
.agents/skills/lark-base/references/lark-base-view-set-filter.md
Normal file
@ -0,0 +1,189 @@
|
||||
# base +view-set-filter
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
更新视图筛选配置。
|
||||
|
||||
## 1. 顶层规则
|
||||
|
||||
- `--json` 必须是 JSON 对象。
|
||||
- 顶层结构是 `{logic?, conditions?}`。
|
||||
- `logic` 默认 `and`；推荐只用 canonical 值 `and` / `or`。
|
||||
- `conditions` 默认空数组。
|
||||
- 每条条件写成 tuple：`[field, operator, value?]`。
|
||||
- `empty` / `non_empty` 可写成 2 项：`[field, "empty"]`、`[field, "non_empty"]`。
|
||||
- 支持 `filter` 的视图类型：`grid`、`kanban`、`gallery`、`calendar`、`gantt`。
|
||||
|
||||
## 2. operator
|
||||
|
||||
可用 operator：
|
||||
- `==`
|
||||
- `!=`
|
||||
- `>`
|
||||
- `>=`
|
||||
- `<`
|
||||
- `<=`
|
||||
- `intersects`
|
||||
- `disjoint`
|
||||
- `empty`
|
||||
- `non_empty`
|
||||
|
||||
## 3. value 写法
|
||||
|
||||
### `text`
|
||||
|
||||
用字符串：
|
||||
|
||||
```json
|
||||
["标题", "intersects", "发布"]
|
||||
```
|
||||
|
||||
### `location`
|
||||
|
||||
location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
|
||||
|
||||
```json
|
||||
["位置", "intersects", "深圳"]
|
||||
```
|
||||
|
||||
不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
|
||||
|
||||
### `number` / `auto_number`
|
||||
|
||||
用数字：
|
||||
|
||||
```json
|
||||
["工时", ">=", 3.5]
|
||||
```
|
||||
|
||||
### `select`
|
||||
|
||||
用选项名数组：
|
||||
|
||||
```json
|
||||
["状态", "intersects", ["Doing", "Blocked"]]
|
||||
```
|
||||
|
||||
### `user` / `created_by` / `updated_by`
|
||||
|
||||
用对象数组：
|
||||
|
||||
> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
|
||||
|
||||
```json
|
||||
["负责人", "intersects", [{ "id": "ou_xxx" }]]
|
||||
```
|
||||
|
||||
### `group_chat`
|
||||
|
||||
用对象数组：
|
||||
|
||||
> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
|
||||
|
||||
```json
|
||||
["负责群", "intersects", [{ "id": "oc_xxx" }]]
|
||||
```
|
||||
|
||||
### `link`
|
||||
|
||||
用记录 id 对象数组：
|
||||
|
||||
```json
|
||||
["关联任务", "intersects", [{ "id": "rec_xxx" }]]
|
||||
```
|
||||
|
||||
### `checkbox`
|
||||
|
||||
用布尔值：
|
||||
|
||||
```json
|
||||
["完成", "==", true]
|
||||
```
|
||||
|
||||
### `datetime` / `created_at` / `updated_at`
|
||||
|
||||
用相对时间关键字或 `ExactDate(...)`：
|
||||
|
||||
```json
|
||||
["截止时间", "==", "ExactDate(2026-01-01)"]
|
||||
```
|
||||
|
||||
```json
|
||||
["截止时间", "==", "ExactDate(2026-01-01 11:30)"]
|
||||
```
|
||||
|
||||
```json
|
||||
["截止时间", "==", "Today"]
|
||||
```
|
||||
|
||||
可用关键字：
|
||||
- `Today`
|
||||
- `Yesterday`
|
||||
- `Tomorrow`
|
||||
|
||||
### `formula` / `lookup`
|
||||
|
||||
- 筛选值类型由字段计算结果类型动态决定。
|
||||
- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
|
||||
- 如果报错，再按错误提示把 `value` 改成对应类型。
|
||||
|
||||
字符串示例：
|
||||
|
||||
```json
|
||||
["风险说明", "intersects", "高风险"]
|
||||
```
|
||||
|
||||
数字示例：
|
||||
|
||||
```json
|
||||
["汇总分", ">=", 80]
|
||||
```
|
||||
|
||||
## 4. 推荐命令
|
||||
|
||||
```bash
|
||||
lark-cli base +view-set-filter \
|
||||
--base-token <base_token> \
|
||||
--table-id <table_id> \
|
||||
--view-id <view_id> \
|
||||
--json '{"logic":"and","conditions":[["状态","intersects",["Doing"]],["负责人","intersects",[{"id":"ou_xxx"}]],["截止时间","empty"]]}'
|
||||
```
|
||||
|
||||
## 5. JSON 写法
|
||||
|
||||
```json
|
||||
{
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["状态", "intersects", ["Doing"]],
|
||||
["负责人", "intersects", [{ "id": "ou_xxx" }]],
|
||||
["截止时间", "empty"]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
清空写法：
|
||||
|
||||
```json
|
||||
{
|
||||
"conditions": []
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 使用建议
|
||||
|
||||
- 先读取当前筛选配置，理解现有 `logic` 和 `conditions` 的组合关系；只替换用户要求变更的条件，未提到的条件默认保留。
|
||||
- 优先传字段 id，不要依赖字段名。
|
||||
- 需要清空全部筛选时，直接传 `{"conditions":[]}`。
|
||||
|
||||
## 7. 易错点
|
||||
|
||||
- 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
|
||||
- `user` / `group_chat` / `link` 不要写成单个标量。
|
||||
- `empty` / `non_empty` 不要硬塞无意义的 value。
|
||||
- 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
|
||||
- `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前 filter 或字段定义，或根据错误提示修正类型。
|
||||
|
||||
## 8. 参考
|
||||
|
||||
- [lookup-field-guide.md](lookup-field-guide.md)
|
||||
830
.agents/skills/lark-base/references/lark-base-workflow-guide.md
Normal file
830
.agents/skills/lark-base/references/lark-base-workflow-guide.md
Normal file
@ -0,0 +1,830 @@
|
||||
# Workflow guide
|
||||
|
||||
本文档是 Workflow 的入口指南，帮助选择步骤组合、理解创建/更新边界，并引导到 steps JSON SSOT。
|
||||
|
||||
> **配套文档**:
|
||||
> - Workflow 的数据结构参考：[lark-base-workflow-schema.md](lark-base-workflow-schema.md)
|
||||
> - 创建/更新时重点构造 `title`、`status` 和 `steps`；复杂度集中在 `steps[].type/data/next`
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 最简单的 Workflow
|
||||
|
||||
新增记录时发送消息通知：
|
||||
|
||||
```json
|
||||
{
|
||||
"client_token": "1704067200",
|
||||
"title": "新订单自动通知",
|
||||
"steps": [
|
||||
{
|
||||
"id": "trigger_1",
|
||||
"type": "AddRecordTrigger",
|
||||
"title": "监控新订单",
|
||||
"next": "action_1",
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"watched_field_name": "订单号"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "action_1",
|
||||
"type": "LarkMessageAction",
|
||||
"title": "发送通知",
|
||||
"next": null,
|
||||
"data": {
|
||||
"receiver": [{ "value_type": "user", "value": {"id": "ou_xxxx", "name": "张三"} }],
|
||||
"send_to_everyone": false,
|
||||
"title": [{ "value_type": "text", "value": "新订单提醒" }],
|
||||
"content": [
|
||||
{ "value_type": "text", "value": "收到新订单" }
|
||||
],
|
||||
"btn_list": []
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 场景速查表
|
||||
|
||||
| 场景 | 步骤组合 | 示例 |
|
||||
|------|---------|------|
|
||||
| 新增触发+通知 | AddRecordTrigger → LarkMessageAction | [下方](#示例1-新增记录触发--发送消息) |
|
||||
| 按钮点击+调用外部接口+写入日志 | ButtonTrigger → HTTPClientAction → AddRecordAction | [下方](#示例-6-按钮触发--调用外部接口--写入同步日志) |
|
||||
| 定时+循环 | TimerTrigger → FindRecordAction → Loop → LarkMessageAction | [下方](#示例2-定时触发--查找记录--循环遍历--发送消息) |
|
||||
| 条件判断 | ... → IfElseBranch → 分支处理 | [下方](#示例3-条件分支-ifelsebranch) |
|
||||
| 多路分类 | ... → SwitchBranch → 多分支处理 | [下方](#示例4-多路分支-switchbranch) |
|
||||
| 复杂组合 | 定时+查找+循环+分支+消息 | [下方](#示例5-组合场景-定时查找循环分支消息) |
|
||||
|
||||
---
|
||||
|
||||
## 完整示例
|
||||
|
||||
### 示例 1: 新增记录触发 + 发送消息
|
||||
|
||||
**场景**: 当订单表新增记录时，发送飞书消息通知负责人。
|
||||
|
||||
```json
|
||||
{
|
||||
"client_token": "1704067201",
|
||||
"title": "新订单自动通知",
|
||||
"steps": [
|
||||
{
|
||||
"id": "step_trigger",
|
||||
"type": "AddRecordTrigger",
|
||||
"title": "新增订单时触发",
|
||||
"next": "step_notify",
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"watched_field_name": "订单号",
|
||||
"condition_list": null
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_notify",
|
||||
"type": "LarkMessageAction",
|
||||
"title": "发送订单通知",
|
||||
"next": null,
|
||||
"data": {
|
||||
"receiver": [{ "value_type": "ref", "value": "$.step_trigger.fldManager" }],
|
||||
"send_to_everyone": false,
|
||||
"title": [{ "value_type": "text", "value": "新订单提醒" }],
|
||||
"content": [
|
||||
{ "value_type": "text", "value": "客户 " },
|
||||
{ "value_type": "ref", "value": "$.step_trigger.fldCustomer" },
|
||||
{ "value_type": "text", "value": " 创建了新订单，金额：¥" },
|
||||
{ "value_type": "ref", "value": "$.step_trigger.fldAmount" }
|
||||
],
|
||||
"btn_list": [
|
||||
{
|
||||
"text": "查看订单",
|
||||
"btn_action": "openLink",
|
||||
"link": [{ "value_type": "ref", "value": "$.step_trigger.recordLink" }]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键点**:
|
||||
- `AddRecordTrigger` 监控 `table_name` 表的 `watched_field_name` 字段
|
||||
- 使用 `ref` 引用触发器输出的字段值（注意是 fieldId，不是字段名）
|
||||
- `recordLink` 是触发器内置输出，表示记录链接
|
||||
|
||||
---
|
||||
|
||||
### 示例 2: 定时触发 + 查找记录 + 循环遍历 + 发送消息
|
||||
|
||||
**场景**: 每天早上 9 点，查找所有待处理订单，给每个客户发送提醒。
|
||||
|
||||
```json
|
||||
{
|
||||
"client_token": "1704067202",
|
||||
"title": "每日待处理订单提醒",
|
||||
"steps": [
|
||||
{
|
||||
"id": "step_timer",
|
||||
"type": "TimerTrigger",
|
||||
"title": "每天早上9点触发",
|
||||
"next": "step_find_orders",
|
||||
"data": {
|
||||
"rule": "DAILY",
|
||||
"start_time": "2025-01-01 09:00",
|
||||
"is_never_end": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_find_orders",
|
||||
"type": "FindRecordAction",
|
||||
"title": "查找所有待处理订单",
|
||||
"next": "step_loop_customers",
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"field_names": ["客户名称", "订单金额", "客户联系方式"],
|
||||
"should_proceed_when_no_results": false,
|
||||
"filter_info": {
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"field_name": "状态",
|
||||
"operator": "is",
|
||||
"value": [{ "value_type": "option", "value": { "name": "待处理" } }]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_loop_customers",
|
||||
"type": "Loop",
|
||||
"title": "遍历每个订单",
|
||||
"children": {
|
||||
"links": [
|
||||
{ "kind": "loop_start", "to": "step_send_reminder" }
|
||||
]
|
||||
},
|
||||
"next": null,
|
||||
"data": {
|
||||
"loop_mode": "continue",
|
||||
"max_loop_times": 100,
|
||||
"data": [{
|
||||
"value_type": "ref",
|
||||
"value": "$.step_find_orders.fieldRecords"
|
||||
}]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_send_reminder",
|
||||
"type": "LarkMessageAction",
|
||||
"title": "发送催办消息",
|
||||
"next": null,
|
||||
"data": {
|
||||
"receiver": [{
|
||||
"value_type": "ref",
|
||||
"value": "$.step_loop_customers.item.fldContact"
|
||||
}],
|
||||
"send_to_everyone": false,
|
||||
"title": [{ "value_type": "text", "value": "订单处理提醒" }],
|
||||
"content": [
|
||||
{ "value_type": "text", "value": "您好，您的订单 " },
|
||||
{ "value_type": "ref", "value": "$.step_loop_customers.item.fldName" },
|
||||
{ "value_type": "text", "value": " 金额 ¥" },
|
||||
{ "value_type": "ref", "value": "$.step_loop_customers.item.fldAmount" },
|
||||
{ "value_type": "text", "value": " 正在处理中。" }
|
||||
],
|
||||
"btn_list": []
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键点**:
|
||||
- `Loop.data` 必须传入 `ref` 类型的数据源（通常是 FindRecordAction 的 `fieldRecords`）
|
||||
- `Loop.children.links` 必须包含 `kind: "loop_start"` 的链接指向循环体
|
||||
- 循环体内用 `$.{loopStepId}.item.{fieldId}` 引用当前遍历记录的字段
|
||||
- `$.{loopStepId}.index` 获取当前索引（从 0 开始）
|
||||
|
||||
---
|
||||
|
||||
### 示例 3: 条件分支（IfElseBranch）
|
||||
|
||||
**场景**: 根据订单金额判断，大额订单通知主管审批，小额订单自动通过。
|
||||
|
||||
```json
|
||||
{
|
||||
"client_token": "1704067203",
|
||||
"title": "订单金额自动判断",
|
||||
"steps": [
|
||||
{
|
||||
"id": "step_trigger",
|
||||
"type": "AddRecordTrigger",
|
||||
"title": "新增订单时触发",
|
||||
"next": "step_check_amount",
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"watched_field_name": "订单金额"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_check_amount",
|
||||
"type": "IfElseBranch",
|
||||
"title": "判断是否为大额订单",
|
||||
"children": {
|
||||
"links": [
|
||||
{ "kind": "if_true", "to": "step_notify_manager", "label": "high", "desc": "金额>=10000" },
|
||||
{ "kind": "if_false", "to": "step_auto_approve", "label": "normal", "desc": "金额<10000" }
|
||||
]
|
||||
},
|
||||
"next": "step_log",
|
||||
"data": {
|
||||
"condition": {
|
||||
"conjunction": "or",
|
||||
"conditions": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"left_value": { "value_type": "ref", "value": "$.step_trigger.fldAmount" },
|
||||
"operator": "isGreaterEqual",
|
||||
"right_value": [{ "value_type": "number", "value": 10000 }]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_notify_manager",
|
||||
"type": "LarkMessageAction",
|
||||
"title": "通知主管审批大额订单",
|
||||
"next": "step_log",
|
||||
"data": {
|
||||
"receiver": [{ "value_type": "user", "value": {"id": "ou_manager", "name": "主管"} }],
|
||||
"send_to_everyone": false,
|
||||
"title": [{ "value_type": "text", "value": "大额订单待审批" }],
|
||||
"content": [
|
||||
{ "value_type": "text", "value": "有大额订单 ¥" },
|
||||
{ "value_type": "ref", "value": "$.step_trigger.fldAmount" },
|
||||
{ "value_type": "text", "value": " 需要您审批" }
|
||||
],
|
||||
"btn_list": []
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_auto_approve",
|
||||
"type": "SetRecordAction",
|
||||
"title": "自动标记小额订单为已审核",
|
||||
"next": "step_log",
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"ref_info": { "step_id": "step_trigger" },
|
||||
"field_values": [
|
||||
{
|
||||
"field_name": "审批状态",
|
||||
"value": [{ "value_type": "option", "value": { "name": "已自动审核" } }]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_log",
|
||||
"type": "GenerateAiTextAction",
|
||||
"title": "生成订单处理日志",
|
||||
"next": null,
|
||||
"data": {
|
||||
"prompt": [
|
||||
{ "value_type": "text", "value": "请生成订单处理日志，金额：" },
|
||||
{ "value_type": "ref", "value": "$.step_trigger.fldAmount" }
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键点**:
|
||||
- `IfElseBranch.children.links` 必须包含 `if_true` 和 `if_false` 两个分支
|
||||
- `next` 指向两个分支汇合后的步骤（可选，为 null 则分支结束）
|
||||
- `condition` 使用 OrGroup 结构，支持 `(A and B) or (C and D)` 的复杂条件
|
||||
- 分支内可以用 `ref_info` 引用触发记录，用 `filter_info` 批量筛选记录
|
||||
|
||||
---
|
||||
|
||||
### 示例 4: 多路分支（SwitchBranch）
|
||||
|
||||
**场景**: 根据订单优先级（P0/P1/P2）执行不同的处理流程。
|
||||
|
||||
```json
|
||||
{
|
||||
"client_token": "1704067204",
|
||||
"title": "按优先级分类处理订单",
|
||||
"steps": [
|
||||
{
|
||||
"id": "step_trigger",
|
||||
"type": "AddRecordTrigger",
|
||||
"title": "新增订单时触发",
|
||||
"next": "step_classify",
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"watched_field_name": "优先级"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_classify",
|
||||
"type": "SwitchBranch",
|
||||
"title": "按优先级分类",
|
||||
"children": {
|
||||
"links": [
|
||||
{ "kind": "case", "to": "step_p0_handler", "label": "p0", "desc": "P0-紧急" },
|
||||
{ "kind": "case", "to": "step_p1_handler", "label": "p1", "desc": "P1-高优先级" },
|
||||
{ "kind": "case", "to": "step_p2_handler", "label": "p2", "desc": "P2-普通" },
|
||||
{ "kind": "case", "to": "step_other_handler", "label": "other", "desc": "其他" }
|
||||
]
|
||||
},
|
||||
"next": null,
|
||||
"data": {
|
||||
"mode": "exclusive",
|
||||
"no_match_action": "classifyToOther",
|
||||
"child_branch_list": [
|
||||
{
|
||||
"name": "P0-紧急",
|
||||
"condition": {
|
||||
"conjunction": "or",
|
||||
"conditions": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"left_value": { "value_type": "ref", "value": "$.step_trigger.fldPriority" },
|
||||
"operator": "is",
|
||||
"right_value": [{ "value_type": "option", "value": { "name": "P0" } }]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "P1-高优先级",
|
||||
"condition": {
|
||||
"conjunction": "or",
|
||||
"conditions": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"left_value": { "value_type": "ref", "value": "$.step_trigger.fldPriority" },
|
||||
"operator": "is",
|
||||
"right_value": [{ "value_type": "option", "value": { "name": "P1" } }]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "P2-普通",
|
||||
"condition": {
|
||||
"conjunction": "or",
|
||||
"conditions": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"left_value": { "value_type": "ref", "value": "$.step_trigger.fldPriority" },
|
||||
"operator": "is",
|
||||
"right_value": [{ "value_type": "option", "value": { "name": "P2" } }]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_p0_handler",
|
||||
"type": "LarkMessageAction",
|
||||
"title": "P0紧急处理",
|
||||
"next": null,
|
||||
"data": {
|
||||
"receiver": [{ "value_type": "user", "value": {"id": "ou_director", "name": "总监"} }],
|
||||
"send_to_everyone": false,
|
||||
"title": [{ "value_type": "text", "value": "🚨 P0 紧急订单" }],
|
||||
"content": [{ "value_type": "text", "value": "有新的 P0 紧急订单需要立即处理" }],
|
||||
"btn_list": []
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_p1_handler",
|
||||
"type": "SetRecordAction",
|
||||
"title": "标记高优先级",
|
||||
"next": null,
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"ref_info": { "step_id": "step_trigger" },
|
||||
"field_values": [
|
||||
{ "field_name": "处理状态", "value": [{ "value_type": "text", "value": "高优先级待处理" }] }
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_p2_handler",
|
||||
"type": "Delay",
|
||||
"title": "普通订单延迟处理",
|
||||
"next": null,
|
||||
"data": { "duration": 60 }
|
||||
},
|
||||
{
|
||||
"id": "step_other_handler",
|
||||
"type": "SetRecordAction",
|
||||
"title": "标记其他订单",
|
||||
"next": null,
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"ref_info": { "step_id": "step_trigger" },
|
||||
"field_values": [
|
||||
{ "field_name": "处理状态", "value": [{ "value_type": "text", "value": "待分类" }] }
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键点**:
|
||||
- `SwitchBranch` 适合 3 路及以上的分支场景（少于 3 路用 `IfElseBranch` 更简洁）
|
||||
- `children.links` 中 `kind: "case"` 的 `label` 对应 `child_branch_list` 中的条件
|
||||
- `mode: "exclusive"` 表示排他执行（第一个匹配的分支执行后停止）
|
||||
- `no_match_action: "classifyToOther"` 表示无匹配时走最后一个 `case`（兜底分支）
|
||||
|
||||
---
|
||||
|
||||
### 示例 5: 组合场景（定时+查找+循环+分支+消息）
|
||||
|
||||
**场景**: 每天早上 9 点，查找昨天的订单，按金额分级，给不同级别的销售发送不同的通知。
|
||||
|
||||
```json
|
||||
{
|
||||
"client_token": "1704067205",
|
||||
"title": "每日订单分级通知",
|
||||
"steps": [
|
||||
{
|
||||
"id": "step_timer",
|
||||
"type": "TimerTrigger",
|
||||
"title": "每天早上9点触发",
|
||||
"next": "step_find_orders",
|
||||
"data": {
|
||||
"rule": "DAILY",
|
||||
"start_time": "2025-01-01 09:00",
|
||||
"is_never_end": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_find_orders",
|
||||
"type": "FindRecordAction",
|
||||
"title": "查找昨天所有订单",
|
||||
"next": "step_loop",
|
||||
"data": {
|
||||
"table_name": "订单表",
|
||||
"field_names": ["订单号", "客户名称", "金额", "销售负责人"],
|
||||
"should_proceed_when_no_results": false,
|
||||
"filter_info": {
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{ "field_name": "创建时间", "operator": "isGreaterEqual", "value": [{ "value_type": "date", "value": "yesterday" }] }
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_loop",
|
||||
"type": "Loop",
|
||||
"title": "遍历每个订单",
|
||||
"children": {
|
||||
"links": [
|
||||
{ "kind": "loop_start", "to": "step_classify" }
|
||||
]
|
||||
},
|
||||
"next": "step_summary",
|
||||
"data": {
|
||||
"loop_mode": "continue",
|
||||
"max_loop_times": 500,
|
||||
"data": [{ "value_type": "ref", "value": "$.step_find_orders.fieldRecords" }]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_classify",
|
||||
"type": "SwitchBranch",
|
||||
"title": "按金额分类",
|
||||
"children": {
|
||||
"links": [
|
||||
{ "kind": "case", "to": "step_vip_notify", "label": "vip", "desc": "VIP >= 10万" },
|
||||
{ "kind": "case", "to": "step_normal_notify", "label": "normal", "desc": "普通 < 10万" }
|
||||
]
|
||||
},
|
||||
"next": null,
|
||||
"data": {
|
||||
"mode": "exclusive",
|
||||
"no_match_action": "fail",
|
||||
"child_branch_list": [
|
||||
{
|
||||
"name": "VIP订单",
|
||||
"condition": {
|
||||
"conjunction": "or",
|
||||
"conditions": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"left_value": { "value_type": "ref", "value": "$.step_loop.item.fldAmount" },
|
||||
"operator": "isGreaterEqual",
|
||||
"right_value": [{ "value_type": "number", "value": 100000 }]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "普通订单",
|
||||
"condition": {
|
||||
"conjunction": "or",
|
||||
"conditions": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"conditions": [
|
||||
{
|
||||
"left_value": { "value_type": "ref", "value": "$.step_loop.item.fldAmount" },
|
||||
"operator": "isLess",
|
||||
"right_value": [{ "value_type": "number", "value": 100000 }]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_vip_notify",
|
||||
"type": "LarkMessageAction",
|
||||
"title": "VIP订单通知",
|
||||
"next": null,
|
||||
"data": {
|
||||
"receiver": [{ "value_type": "ref", "value": "$.step_loop.item.fldSales" }],
|
||||
"send_to_everyone": false,
|
||||
"title": [{ "value_type": "text", "value": "🌟 VIP大额订单" }],
|
||||
"content": [
|
||||
{ "value_type": "text", "value": "恭喜！您有一笔 VIP 订单 ¥" },
|
||||
{ "value_type": "ref", "value": "$.step_loop.item.fldAmount" },
|
||||
{ "value_type": "text", "value": "，客户：" },
|
||||
{ "value_type": "ref", "value": "$.step_loop.item.fldCustomer" }
|
||||
],
|
||||
"btn_list": []
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_normal_notify",
|
||||
"type": "LarkMessageAction",
|
||||
"title": "普通订单通知",
|
||||
"next": null,
|
||||
"data": {
|
||||
"receiver": [{ "value_type": "ref", "value": "$.step_loop.item.fldSales" }],
|
||||
"send_to_everyone": false,
|
||||
"title": [{ "value_type": "text", "value": "新订单通知" }],
|
||||
"content": [
|
||||
{ "value_type": "text", "value": "您有一笔新订单 ¥" },
|
||||
{ "value_type": "ref", "value": "$.step_loop.item.fldAmount" }
|
||||
],
|
||||
"btn_list": []
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_summary",
|
||||
"type": "GenerateAiTextAction",
|
||||
"title": "生成日报",
|
||||
"next": null,
|
||||
"data": {
|
||||
"prompt": [
|
||||
{ "value_type": "text", "value": "请生成昨日订单处理日报" }
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 示例 6: 按钮触发 + 调用外部接口 + 写入同步日志
|
||||
|
||||
**场景**: 在「客户线索表」里给每条记录配置一个“同步到 CRM”按钮。销售点击按钮后，Workflow 调用外部 CRM 接口同步当前线索，再在「同步日志表」新增一条记录，方便后续审计和排查。
|
||||
|
||||
```json
|
||||
{
|
||||
"client_token": "1704067206",
|
||||
"title": "线索一键同步到 CRM",
|
||||
"steps": [
|
||||
{
|
||||
"id": "step_button_trigger",
|
||||
"type": "ButtonTrigger",
|
||||
"title": "点击同步到 CRM 按钮时触发",
|
||||
"next": "step_call_crm_api",
|
||||
"data": {
|
||||
"button_type": "buttonField",
|
||||
"table_name": "客户线索表"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_call_crm_api",
|
||||
"type": "HTTPClientAction",
|
||||
"title": "调用 CRM 同步接口",
|
||||
"next": "step_add_sync_log",
|
||||
"data": {
|
||||
"method": "POST",
|
||||
"url": [
|
||||
{ "value_type": "text", "value": "https://api.example-crm.com/v1/leads/sync" }
|
||||
],
|
||||
"headers": [
|
||||
{ "key": "Content-Type", "value": [{ "value_type": "text", "value": "application/json" }] },
|
||||
{ "key": "X-System", "value": [{ "value_type": "text", "value": "lark_base_workflow" }] }
|
||||
],
|
||||
"body_type": "raw",
|
||||
"raw_body": [
|
||||
{ "value_type": "text", "value": "{\"lead_name\":\"" },
|
||||
{ "value_type": "ref", "value": "$.step_button_trigger.fldLeadName" },
|
||||
{ "value_type": "text", "value": "\",\"mobile\":\"" },
|
||||
{ "value_type": "ref", "value": "$.step_button_trigger.fldMobile" },
|
||||
{ "value_type": "text", "value": "\",\"company\":\"" },
|
||||
{ "value_type": "ref", "value": "$.step_button_trigger.fldCompany" },
|
||||
{ "value_type": "text", "value": "\",\"owner\":\"" },
|
||||
{ "value_type": "ref", "value": "$.step_button_trigger.fldOwner" },
|
||||
{ "value_type": "text", "value": "\",\"source_record_id\":\"" },
|
||||
{ "value_type": "ref", "value": "$.step_button_trigger.recordId" },
|
||||
{ "value_type": "text", "value": "\"}" }
|
||||
],
|
||||
"response_type": "json",
|
||||
"response_value": "{\"success\":true,\"message\":\"lead synced successfully\"}"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "step_add_sync_log",
|
||||
"type": "AddRecordAction",
|
||||
"title": "写入同步日志",
|
||||
"next": null,
|
||||
"data": {
|
||||
"table_name": "同步日志表",
|
||||
"field_values": [
|
||||
{
|
||||
"field_name": "线索名称",
|
||||
"value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldLeadName" }]
|
||||
},
|
||||
{
|
||||
"field_name": "手机号",
|
||||
"value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldMobile" }]
|
||||
},
|
||||
{
|
||||
"field_name": "公司名称",
|
||||
"value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldCompany" }]
|
||||
},
|
||||
{
|
||||
"field_name": "负责人",
|
||||
"value": [{ "value_type": "ref", "value": "$.step_button_trigger.fldOwner" }]
|
||||
},
|
||||
{
|
||||
"field_name": "来源记录ID",
|
||||
"value": [{ "value_type": "ref", "value": "$.step_button_trigger.recordId" }]
|
||||
},
|
||||
{
|
||||
"field_name": "同步状态",
|
||||
"value": [{ "value_type": "text", "value": "已提交 CRM 同步" }]
|
||||
},
|
||||
{
|
||||
"field_name": "同步是否成功",
|
||||
"value": [{ "value_type": "ref", "value": "$.step_call_crm_api.body.success" }]
|
||||
},
|
||||
{
|
||||
"field_name": "同步结果说明",
|
||||
"value": [{ "value_type": "ref", "value": "$.step_call_crm_api.body.message" }]
|
||||
},
|
||||
{
|
||||
"field_name": "备注",
|
||||
"value": [{ "value_type": "text", "value": "由按钮触发自动发起同步请求" }]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键点**:
|
||||
- `ButtonTrigger` 适合“人工确认后再执行”的场景，比如同步 CRM、推送 ERP、发起审批等
|
||||
- `button_type: "buttonField"` 表示按钮挂在记录上，因此可以直接引用当前记录的字段和值
|
||||
- `HTTPClientAction.raw_body` 可以通过 `text + ref + text` 的方式动态拼接 JSON 请求体
|
||||
- `HTTPClientAction` 的输出引用规则是：`response_type=none` 时不可引用；`response_type=text` 时只能用 `$.stepId` 引整个文本；`response_type=json` 时用 `$.stepId.body` 引整个 body、用 `$.stepId.body.字段名` 引 body 中字段，同时 `$.stepId.status_code` 表示 HTTP 返回状态码
|
||||
- `HTTPClientAction.response_value` 中声明了哪些字段，后续节点就只能引用这些字段；例如 `$.step_call_crm_api.body.success`、`$.step_call_crm_api.body.message`
|
||||
- `AddRecordAction` 常用于写日志表、操作审计表、同步结果表，便于追踪谁在什么时候触发了外部调用
|
||||
- 示例里的 `fldLeadName` / `fldMobile` / `fldCompany` / `fldOwner` 只是占位的 fieldId，请以实际表字段 ID 为准
|
||||
|
||||
---
|
||||
|
||||
## 构造技巧
|
||||
|
||||
### Loop 构造要点
|
||||
|
||||
1. **数据源**: `Loop.data` 必须传入 `ref` 类型，通常是 `FindRecordAction` 的 `fieldRecords`
|
||||
2. **循环体**: `children.links` 必须包含 `kind: "loop_start"` 指向循环体入口
|
||||
3. **引用**: 循环体内用 `$.{loopStepId}.item.{fieldId}` 引用当前元素
|
||||
4. **索引**: 用 `$.{loopStepId}.index` 获取当前索引（从 0 开始）
|
||||
|
||||
### 分支构造要点
|
||||
|
||||
1. **IfElseBranch**:
|
||||
- 适合二元判断（是/否、大于/小于）
|
||||
- `children.links` 必须包含 `if_true` 和 `if_false`
|
||||
- 可以用 `next` 指向汇合点
|
||||
|
||||
2. **SwitchBranch**:
|
||||
- 适合多路分类（3路及以上）
|
||||
- `label` 对应 `child_branch_list` 中的条件顺序
|
||||
- 建议加一个兜底分支（其他）
|
||||
|
||||
### 字段值构造
|
||||
|
||||
| 字段类型 | value_type | 示例 |
|
||||
|---------|------------|------|
|
||||
| 文本 | `text` | `{"value_type": "text", "value": "张三"}` |
|
||||
| 数字 | `number` | `{"value_type": "number", "value": 100}` |
|
||||
| 单选 | `option` | `{"value_type": "option", "value": {"name": "已完成"}}` |
|
||||
| 人员 | `user` | `{"value_type": "user", "value": {"id": "ou_xxxx"}}` |
|
||||
| 引用 | `ref` | `{"value_type": "ref", "value": "$.step_1.fldxxx"}` |
|
||||
|
||||
---
|
||||
|
||||
## 常见错误避免
|
||||
|
||||
### Top 10 高频错误
|
||||
|
||||
| # | 错误信息 | 原因 | 解决方案 |
|
||||
|---|---------|------|---------|
|
||||
| 1 | `path "xxx" does not exist in the output path tree` | ref 引用路径错误或 stepId 不存在 | 检查 stepId 是否在 steps 数组中；使用 fieldId 而非字段名；确保路径以 `$.` 开头 |
|
||||
| 2 | `recordInfo.conditions must be non-empty` | `condition_list` 为空数组 `[]` | 改用 `null` 或省略该字段 |
|
||||
| 3 | `At least one of filter info and ref info is required` | SetRecordAction/FindRecordAction 缺少定位条件 | 必须提供 `filter_info` 或 `ref_info` 之一 |
|
||||
| 4 | `client token is empty` | 缺少 `client_token` | 每次请求传入唯一值（时间戳或随机字符串） |
|
||||
| 5 | `valueType 'text' not allowed for fieldType '3'` | select 类型字段值格式错误 | 改用 `option` 类型 |
|
||||
| 6 | `Undefined Step Type` | 使用了不支持的 StepType | 使用 `AddRecordTrigger` 而非 `CreateRecordTrigger` |
|
||||
| 7 | `prompt references an unknown reference from step` | 引用的 stepId 不存在 | 确保引用的 step 在同一 workflow 的 steps 数组中 |
|
||||
| 8 | `[2200] Internal Error` | 1. steps[].id 重复 2. next/children.links 引用了不存在的 step | 确保所有 step id 唯一；检查引用关系 |
|
||||
| 9 | 工作流结构不完整 | Branch/Loop 节点缺少 `children` | 仅 Branch（IfElseBranch/SwitchBranch）和 Loop 节点需要 `children`，Trigger/Action 节点无需设置 |
|
||||
| 10 | 嵌套分支过于复杂 | 多层 IfElseBranch 嵌套 | 3+ 路分支用 SwitchBranch 替代嵌套 IfElseBranch |
|
||||
|
||||
### 其他常见错误
|
||||
|
||||
**1. condition_list 为空数组**
|
||||
```json
|
||||
// ❌ 错误
|
||||
{ "condition_list": [] }
|
||||
|
||||
// ✅ 正确
|
||||
{ "condition_list": null }
|
||||
// 或省略该字段
|
||||
```
|
||||
|
||||
**2. filter_info 和 ref_info 同时提供**
|
||||
```json
|
||||
// ❌ 错误
|
||||
{ "filter_info": {...}, "ref_info": {...} }
|
||||
|
||||
// ✅ 正确（二选一）
|
||||
{ "filter_info": {...}, "ref_info": null }
|
||||
{ "filter_info": null, "ref_info": {...} }
|
||||
```
|
||||
|
||||
**3. 使用字段名而非 fieldId**
|
||||
```json
|
||||
// ❌ 错误
|
||||
{ "value": "$.step_1.客户名称" }
|
||||
|
||||
// ✅ 正确
|
||||
{ "value": "$.step_1.fldXXXXXXXX" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-base-workflow-schema.md](lark-base-workflow-schema.md) — 字段定义参考
|
||||
- 创建/更新前先确认真实表名、字段名和目标 workflow ID；`steps` 结构按 schema 构造，不凭自然语言猜 `type`
|
||||
1071
.agents/skills/lark-base/references/lark-base-workflow-schema.md
Normal file
1071
.agents/skills/lark-base/references/lark-base-workflow-schema.md
Normal file
File diff suppressed because it is too large
Load Diff
512
.agents/skills/lark-base/references/lookup-field-guide.md
Normal file
512
.agents/skills/lark-base/references/lookup-field-guide.md
Normal file
@ -0,0 +1,512 @@
|
||||
# Base Lookup Field Configuration Guide
|
||||
|
||||
## Mandatory Read Acknowledgement
|
||||
|
||||
When creating or updating a lookup field with `lark-cli base +field-create/+field-update --json ...` and `type` is `lookup`, you should read this guide first and only then add `--i-have-read-guide` to the command.
|
||||
|
||||
Do **not** proactively add `--i-have-read-guide` before reading this guide. Without it, the CLI will fail fast and direct you back to this guide.
|
||||
|
||||
When using `+field-update`, also pass `--yes`: field update is a high-risk `PUT` operation because changing a field definition can affect the whole column.
|
||||
|
||||
## Default strategy
|
||||
|
||||
**Use Formula fields by default for cross-table references and aggregations.** Only use Lookup fields when the user explicitly requests a Lookup field. Formula is a strict superset of Lookup — anything Lookup can do, Formula can do with a single expression.
|
||||
|
||||
## Usage
|
||||
|
||||
When creating a lookup field, the Agent should:
|
||||
|
||||
1. Get all table names: `lark-cli base +table-list --base-token <base>` — returns `items[].table_name`
|
||||
2. Get table structure: `lark-cli base +table-get --base-token <base> --table-id <table>` — returns `fields[]`
|
||||
3. If the lookup references other tables, also get those tables' structures
|
||||
4. Determine the four elements: from (source table), select (source field), where (filter), aggregate (aggregation)
|
||||
5. Construct the Lookup field JSON and submit it to create or update the field
|
||||
|
||||
**Key constraints**:
|
||||
|
||||
- Table names and field names must **exactly match** those returned by `+table-list` / `+table-get`
|
||||
- The `from` table must be in the same Base
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Core Concepts — Four-Element Model
|
||||
|
||||
A Lookup field is defined by five fields:
|
||||
|
||||
| Field | Meaning | JSON key | Required |
|
||||
|-------|---------|----------|----------|
|
||||
| **type** | Must be `"lookup"` | `type` | Yes |
|
||||
| **from** | Source table to pull data from | `from` | Yes |
|
||||
| **select** | Field in the source table to retrieve | `select` | Yes |
|
||||
| **where** | Filter conditions on the source table | `where` | Yes (at least one condition) |
|
||||
| **aggregate** | How to aggregate multiple matching records | `aggregate` | No (default: `raw_value`) |
|
||||
|
||||
**SQL analogy**:
|
||||
|
||||
```
|
||||
SELECT [select field]
|
||||
FROM [from table]
|
||||
WHERE [filter conditions]
|
||||
GROUP BY [aggregate function]
|
||||
```
|
||||
|
||||
**Row-level matching (most important concept)**:
|
||||
|
||||
A Lookup field is computed row-by-row — for each row in the current table, it filters the source table to find "related" records. **The filter defines what "related" means.**
|
||||
|
||||
```
|
||||
Current table row 1 → filter source table → matching records → select field → aggregate → result
|
||||
Current table row 2 → filter source table → matching records → select field → aggregate → result
|
||||
...
|
||||
```
|
||||
|
||||
**Rule: Whenever the current table and the source table have a row-level correspondence (matching by some field value), you must specify a filter.**
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Lookup vs Link vs Formula
|
||||
|
||||
Lookup and Link serve **different purposes**. Creating a Lookup does NOT require a Link field to exist first.
|
||||
|
||||
| Dimension | Link | Lookup | Formula |
|
||||
|-----------|------|--------|---------|
|
||||
| Purpose | Establish record relationships (read-write) | Pull and aggregate data from another table (read-only) | Compute values from expressions (read-only) |
|
||||
| When to use | "link" / "associate" / "bind" two tables | "look up" / "reference" / "aggregate" / "count" from another table | Calculations, text manipulation, conditional logic |
|
||||
|
||||
**Common mistake**: Creating a Link field just to create a Lookup. If two tables share a matching text/number field, Lookup can match directly — no Link required.
|
||||
|
||||
**Selection decision tree**:
|
||||
|
||||
```
|
||||
What does the user need?
|
||||
├─ "Link"/"associate"/"bind" records between tables → Link
|
||||
├─ "Look up"/"reference"/"aggregate"/"count" from another table → Lookup
|
||||
│ ├─ Needs aggregation (sum/count/average)? → Lookup + aggregate
|
||||
│ └─ Just reference a value? → Lookup (aggregate = null)
|
||||
├─ Calculations/text manipulation within current table → Formula
|
||||
└─ Access linked record's field → Prefer Lookup (more intuitive), or Formula chain access
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Filter Condition Rules
|
||||
|
||||
**You must provide a `where` with at least one condition.** Improper conditions cause every row to pull all records from the source table.
|
||||
|
||||
### The Iron Rule: field belongs to source table
|
||||
|
||||
```
|
||||
filter condition:
|
||||
field → must be a field in the FROM table (source table)
|
||||
value → constant or reference to a field in the CURRENT table
|
||||
```
|
||||
|
||||
### How to find the matching field pair
|
||||
|
||||
**With a Link field (most common)**: The match is between the **Link field** and the **target table's primary field**.
|
||||
|
||||
```
|
||||
Link is in the source table → source.linkField matches current.primaryField
|
||||
Link is in the current table → source.primaryField matches current.linkField
|
||||
```
|
||||
|
||||
**Without a Link field**: Two tables share a field with the same meaning — match directly.
|
||||
|
||||
### Where condition structure
|
||||
|
||||
Each condition is a **tuple** (array) of 2 or 3 elements: `[field, operator, value?]`
|
||||
|
||||
```json
|
||||
{
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["<source table field>", "<operator>", { "type": "constant", "value": "<val>" }]
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
For `empty` / `non_empty`, the value can be omitted (2-element tuple):
|
||||
|
||||
```json
|
||||
["<source table field>", "empty"]
|
||||
```
|
||||
|
||||
### Two value formats
|
||||
|
||||
**Constant value** — for fixed conditions (e.g., "status is completed"):
|
||||
|
||||
```json
|
||||
["状态", "==", { "type": "constant", "value": "已完成" }]
|
||||
```
|
||||
|
||||
**Field reference** — for dynamic per-row matching (e.g., "match current row's project"):
|
||||
|
||||
```json
|
||||
["项目名", "==", { "type": "field_ref", "field": "项目名" }]
|
||||
```
|
||||
|
||||
**Decision guide**: Fixed condition (e.g., "status is completed") → `constant`. Dynamic condition (e.g., "match current record's project ID") → `field_ref`.
|
||||
|
||||
### Constant value format by field type
|
||||
|
||||
The `value` inside `{ "type": "constant", "value": ... }` varies by field type:
|
||||
|
||||
| Field type | Constant value format | Example |
|
||||
|-----------|----------------------|---------|
|
||||
| `text` | String | `"已完成"` |
|
||||
| `number` | Number | `100`, `0.8` |
|
||||
| `datetime` / `created_at` / `updated_at` | String | `"ExactDate(2025-01-01)"`, `"ExactDate(2025-01-01 09:30)"`, `"Today"`, `"Yesterday"`, `"Tomorrow"` |
|
||||
| `select` (`multiple=false/true`) | Option name array | `["Todo"]`, `["Todo", "Done"]` |
|
||||
| `link` | Record reference array | `[{ "id": "rec_xxx" }]`, `[{ "id": "rec_xxx" }, { "id": "rec_yyy" }]` |
|
||||
| `user` / `created_by` / `updated_by` | User reference array | `[{ "id": "ou_xxx" }]`, `[{ "id": "ou_xxx" }, { "id": "ou_yyy" }]` |
|
||||
| `checkbox` | Boolean | `true`, `false` |
|
||||
| `attachment` / `location` | Only `empty` / `non_empty` | value must be `null` or omitted |
|
||||
| `auto_number` | Not supported for constant comparison | Use dynamic field\_ref instead |
|
||||
| `formula` / `lookup` (exact type) | Follow the underlying type rules | — |
|
||||
| `formula` / `lookup` (fuzzy type) | String | `"some text"` |
|
||||
|
||||
**`datetime` notes**:
|
||||
- Supported datetime constant values are `ExactDate(...)`, `Today`, `Yesterday`, `Tomorrow`
|
||||
- Date-only fields use `ExactDate(YYYY-MM-DD)`
|
||||
- Fields that include time use `ExactDate(YYYY-MM-DD HH:mm)`
|
||||
- For complex or relative date filtering, consider using a Formula field instead
|
||||
|
||||
### Dynamic field reference — set comparison semantics
|
||||
|
||||
When using `{ "type": "field_ref", "field": "..." }`, values from both sides are first **converted to sets** at runtime, then compared using set operations:
|
||||
|
||||
- **`==`**: Sets are exactly equal (strict matching)
|
||||
- **`intersects`**: Sets have a non-empty intersection (most commonly used)
|
||||
|
||||
**Conversion rules by field type**:
|
||||
|
||||
| Field type | Converted to |
|
||||
|-----------|-------------|
|
||||
| `text` | Single-element string set |
|
||||
| `number` / `auto_number` / `datetime` | Single-element number set |
|
||||
| `select` (`multiple=false/true`) | Set of option name strings |
|
||||
| `user` / `created_by` / `updated_by` | Set of user name strings |
|
||||
| `link` | Set of linked records' primary field string representations |
|
||||
| `formula` / `lookup` | The computed value set |
|
||||
|
||||
**Examples**:
|
||||
- User field `["name1", "name2"]` **intersects** text `"name1"` → true; **==** text `"name1"` → false (sets not equal)
|
||||
- User field `["name1"]` **==** text `"name1"` → true (single-element sets are equal)
|
||||
- Link field referencing records → converted to primary field strings, then compared
|
||||
|
||||
### Supported operators
|
||||
|
||||
| Operator | Meaning | Applicable field types |
|
||||
|----------|---------|-----------------|
|
||||
| `==` | Equal (exact match) | All types |
|
||||
| `!=` | Not equal | All types |
|
||||
| `>` | Greater than | `number`, `datetime` |
|
||||
| `>=` | Greater than or equal | `number`, `datetime` |
|
||||
| `<` | Less than | `number`, `datetime` |
|
||||
| `<=` | Less than or equal | `number`, `datetime` |
|
||||
| `intersects` | Has intersection (non-empty overlap) | All types (most commonly used for dynamic field\_ref) |
|
||||
| `disjoint` | No intersection | All types |
|
||||
| `empty` | Field is empty | All types (value must be null or omitted) |
|
||||
| `non_empty` | Field is not empty | All types (value must be null or omitted) |
|
||||
|
||||
### Constraints
|
||||
|
||||
- **Only one level of and/or** — nesting (e.g., `{ and: [{ or: [...] }] }`) is not supported
|
||||
- **At least one condition** — empty conditions array will error
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Aggregate Rules
|
||||
|
||||
| Aggregate | Common user phrasing | Select field should be | Result type |
|
||||
|-----------|---------------------|----------------------|-------------|
|
||||
| `sum` | "total" / "sum" / "cumulative amount" | `number` field (e.g., amount) | Number |
|
||||
| `average` | "average" / "mean" | `number` field | Number |
|
||||
| `max` | "maximum" / "latest" / "most recent" | `number` / `datetime` field | Same as source |
|
||||
| `min` | "minimum" / "earliest" | `number` / `datetime` field | Same as source |
|
||||
| `counta` | "count" / "how many" / "total number" | Any field | Number |
|
||||
| `unique_counta` | "count distinct" / "how many different" | Field to deduplicate | Number |
|
||||
| `unique` | "list distinct" / "which ones" / "show different" | Field to display | List |
|
||||
| `raw_value` | "list all" / "show all values" (default) | Field to display | List |
|
||||
|
||||
**Common confusion**: `unique` returns a **deduplicated list**, `unique_counta` returns a **count**. "Which categories are involved" → `unique`; "How many categories" → `unique_counta`.
|
||||
|
||||
**Important**:
|
||||
- Enum values are **snake_case lowercase**: `sum` not `Sum`, `average` not `Average`
|
||||
- **Count is `counta`, NOT `count`** — this is the most common enum mistake
|
||||
|
||||
---
|
||||
|
||||
## Section 5: Hard Constraints
|
||||
|
||||
1. **Always write a filter**: The `where` field is required with at least one condition. Whenever the current table and source table have row-level correspondence, the condition should express that relationship.
|
||||
2. **Lookup fields are read-only**: Cell values cannot be manually set.
|
||||
3. **Create Lookup after all dependent fields exist**: The source table and referenced fields must exist before creating the Lookup field.
|
||||
4. **Source table must be in the same Base**: Cross-Base lookups are not supported.
|
||||
5. **Changing `from` requires changing `select`**: Updating the source table without updating the select field will error.
|
||||
|
||||
---
|
||||
|
||||
## Section 6: Decision Trees
|
||||
|
||||
### How to build the filter
|
||||
|
||||
```
|
||||
Step 1: Analyze the filtering semantics in the user's request
|
||||
"Count artworks per exhibition" → filter: belongs to exhibition = current exhibition
|
||||
"Sum completed order amounts" → filter: status = completed AND project = current project
|
||||
|
||||
Step 2: Find the matching field pair
|
||||
├─ Tables have a Link relationship?
|
||||
│ ├─ Link is in source table → source.linkField matches current.primaryField
|
||||
│ └─ Link is in current table → source.primaryField matches current.linkField
|
||||
├─ Tables share same-meaning text/number field? → source.field matches current.field
|
||||
└─ Also need constant filtering? → AND combination
|
||||
```
|
||||
|
||||
### Which aggregate?
|
||||
|
||||
```
|
||||
How to handle multiple matching records?
|
||||
├─ Show all values as-is → raw_value (default)
|
||||
├─ Show deduplicated list → unique
|
||||
├─ Sum → sum
|
||||
├─ Average → average
|
||||
├─ Maximum / minimum → max / min
|
||||
├─ Count records → counta
|
||||
└─ Count distinct → unique_counta
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 7: Common Configuration Patterns
|
||||
|
||||
> Patterns are categorized by **filter matching method**. Aggregate choice is independent — see Section 4.
|
||||
|
||||
### Pattern 1: Aggregate from a linked table (Link is in the source table)
|
||||
|
||||
**Scenario**: "Count artworks per exhibition", "Sum order amounts per project"
|
||||
|
||||
When the source table has a Link pointing to the current table:
|
||||
|
||||
```
|
||||
Exhibition table: ExhibitionName (primaryField) ← current table
|
||||
Artwork table: ArtworkName (primaryField), ← source table (Link is here)
|
||||
Exhibition (Link → Exhibition table)
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "lookup",
|
||||
"name": "Artwork Count",
|
||||
"from": "Artwork table",
|
||||
"select": "ArtworkName",
|
||||
"aggregate": "counta",
|
||||
"where": {
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["Exhibition", "intersects", { "type": "field_ref", "field": "ExhibitionName" }]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 2: Reference a linked record's field (Link is in the current table)
|
||||
|
||||
**Scenario**: "Show supplier's contact person", "Display warehouse manager"
|
||||
|
||||
When the current table has a Link pointing to the source table:
|
||||
|
||||
```
|
||||
Supplier table: SupplierName (primaryField), Contact (Text) ← source table
|
||||
Inventory table: ProductName (primaryField), ← current table (Link is here)
|
||||
Supplier (Link → Supplier table)
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "lookup",
|
||||
"name": "Supplier Contact",
|
||||
"from": "Supplier table",
|
||||
"select": "Contact",
|
||||
"where": {
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["SupplierName", "intersects", { "type": "field_ref", "field": "Supplier" }]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 3: Match by same-meaning field (no Link)
|
||||
|
||||
**Scenario**: "Sum order amounts per project" (tables share a "ProjectName" field but no Link)
|
||||
|
||||
```
|
||||
Project table: ProjectName (primaryField) ← current table
|
||||
Order table: OrderID (primaryField), ProjectName (Text), ← source table
|
||||
Amount (Number)
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "lookup",
|
||||
"name": "Order Total",
|
||||
"from": "Order table",
|
||||
"select": "Amount",
|
||||
"aggregate": "sum",
|
||||
"where": {
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["ProjectName", "==", { "type": "field_ref", "field": "ProjectName" }]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 4: Dynamic matching + constant filtering
|
||||
|
||||
**Scenario**: "Only count completed orders", "Only sum approved budgets"
|
||||
|
||||
Combine row-level matching with fixed-value filtering using `logic: "and"`:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "lookup",
|
||||
"name": "Completed Order Amount",
|
||||
"from": "Order table",
|
||||
"select": "Amount",
|
||||
"aggregate": "sum",
|
||||
"where": {
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["Manager", "==", { "type": "field_ref", "field": "EmployeeName" }],
|
||||
["Status", "==", { "type": "constant", "value": "Completed" }]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 5: Date filtering with constant value
|
||||
|
||||
**Scenario**: "Look up orders created after 2025-01-01", "Sum today's sales"
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "lookup",
|
||||
"name": "Recent Orders",
|
||||
"from": "Order table",
|
||||
"select": "Amount",
|
||||
"aggregate": "sum",
|
||||
"where": {
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
["ProjectName", "==", { "type": "field_ref", "field": "ProjectName" }],
|
||||
["CreatedDate", ">=", { "type": "constant", "value": "ExactDate(2025-01-01)" }]
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 8: Anti-Pattern Collection
|
||||
|
||||
### Mistake 1: Omitting where (most common)
|
||||
|
||||
```json
|
||||
// Wrong: no where, every row pulls all records
|
||||
{ "type": "lookup", "name": "Artwork Count", "from": "Artwork table", "select": "ArtworkName", "aggregate": "counta" }
|
||||
|
||||
// Correct: where with Link relationship
|
||||
{ "type": "lookup", "name": "Artwork Count", "from": "Artwork table", "select": "ArtworkName", "aggregate": "counta",
|
||||
"where": { "logic": "and", "conditions": [
|
||||
["Exhibition", "intersects", { "type": "field_ref", "field": "ExhibitionName" }]
|
||||
]}}
|
||||
```
|
||||
|
||||
### Mistake 2: Wrong value type — confusing constant vs field_ref
|
||||
|
||||
```json
|
||||
// Wrong: using constant for a dynamic join
|
||||
["ProjectName", "==", { "type": "constant", "value": "ProjectName" }]
|
||||
|
||||
// Correct: use field_ref for dynamic per-row matching
|
||||
["ProjectName", "==", { "type": "field_ref", "field": "ProjectName" }]
|
||||
```
|
||||
|
||||
### Mistake 3: Using `count` instead of `counta`
|
||||
|
||||
```json
|
||||
// Wrong
|
||||
{ "aggregate": "count" }
|
||||
|
||||
// Correct
|
||||
{ "aggregate": "counta" }
|
||||
```
|
||||
|
||||
### Mistake 4: Wrong case for aggregate values
|
||||
|
||||
```json
|
||||
// Wrong
|
||||
{ "aggregate": "SUM" }
|
||||
{ "aggregate": "Sum" }
|
||||
|
||||
// Correct — snake_case lowercase
|
||||
{ "aggregate": "sum" }
|
||||
{ "aggregate": "average" }
|
||||
```
|
||||
|
||||
### Mistake 5: Nested where conditions
|
||||
|
||||
```json
|
||||
// Wrong: nesting not supported
|
||||
{ "logic": "and", "conditions": [
|
||||
{ "logic": "or", "conditions": [...] }
|
||||
]}
|
||||
|
||||
// Correct: only one level
|
||||
{ "logic": "and", "conditions": [cond1, cond2, cond3] }
|
||||
```
|
||||
|
||||
### Mistake 6: Confusing Lookup with Link
|
||||
|
||||
The user says "aggregate order amounts" — use Lookup, not Link. Link establishes relationships; Lookup retrieves and aggregates data.
|
||||
|
||||
### Mistake 7: Using object format instead of tuple for conditions
|
||||
|
||||
```json
|
||||
// Wrong: object format
|
||||
{ "fieldRef": "Status", "operator": "is", "value": { "type": "constant", "value": "Done" } }
|
||||
|
||||
// Correct: tuple format [field, operator, value?]
|
||||
["Status", "==", { "type": "constant", "value": "Done" }]
|
||||
```
|
||||
|
||||
### Mistake 8: Missing `type` field
|
||||
|
||||
```json
|
||||
// Wrong: no type field
|
||||
{ "name": "Total", "from": "Orders", "select": "Amount", "aggregate": "sum", "where": { ... } }
|
||||
|
||||
// Correct: must include type
|
||||
{ "type": "lookup", "name": "Total", "from": "Orders", "select": "Amount", "aggregate": "sum", "where": { ... } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 9: Constraint Summary
|
||||
|
||||
- `type` must be `"lookup"` — this field is required in the request body
|
||||
- `where` is required with at least one condition — always specify a filter
|
||||
- Conditions use **tuple format**: `[field, operator, value?]` — NOT object format
|
||||
- Lookup fields are read-only — values cannot be manually set
|
||||
- Source table and referenced fields must exist before creating the Lookup
|
||||
- Condition field (first element of tuple) must reference a field in the source table, not the current table
|
||||
- Where supports only one level of and/or — no nesting
|
||||
- Aggregate values are snake_case lowercase: `sum`, `counta`, `unique_counta` (NOT `count`)
|
||||
- Operators: `==`, `!=`, `>`, `>=`, `<`, `<=`, `intersects`, `disjoint`, `empty`, `non_empty`
|
||||
- Table and field names must exactly match `+table-get` output
|
||||
- `datetime` constant values use string format: `ExactDate(YYYY-MM-DD)` / `ExactDate(YYYY-MM-DD HH:mm)` / `Today` / `Yesterday` / `Tomorrow`
|
||||
- `select` constant values use option names;
|
||||
- `link` / `user` constant values use `{id}` object arrays
|
||||
549
.agents/skills/lark-base/references/role-config.md
Normal file
549
.agents/skills/lark-base/references/role-config.md
Normal file
@ -0,0 +1,549 @@
|
||||
# Base role permission JSON SSOT
|
||||
|
||||
> **入口指南**: [lark-base-role-guide.md](lark-base-role-guide.md) | **相关命令**: `+role-create` · `+role-update` · `+role-get`
|
||||
|
||||
本文档是角色权限 JSON（AdvPermBaseRoleConfig）的单一事实来源（SSOT），供 `+role-create` 和 `+role-update` 构造 `--json` 参数时参考。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [顶层结构 (AdvPermBaseRoleConfig)](#顶层结构-advpermbaseroleconfig)
|
||||
- [角色类型 (RoleType)](#角色类型-roletype)
|
||||
- [读取与更新角色](#读取与更新角色)
|
||||
- [Base 级权限 (BaseRuleMap)](#base-级权限-baserulemap)
|
||||
- [仪表盘权限 (DashboardRule)](#仪表盘权限-dashboardrule)
|
||||
- [文档权限 (DocxRule)](#文档权限-docxrule)
|
||||
- [数据表权限 (TableRule)](#数据表权限-tablerule)
|
||||
- [表级权限 (TablePerm)](#表级权限-tableperm)
|
||||
- [视图权限 (ViewRule)](#视图权限-viewrule)
|
||||
- [字段权限 (FieldRule)](#字段权限-fieldrule)
|
||||
- [记录权限 (RecordRule)](#记录权限-recordrule)
|
||||
- [筛选条件 (FilterRuleGroup)](#筛选条件-filterrulegroup)
|
||||
- [默认权限策略与风控规则](#默认权限策略与风控规则)
|
||||
- [默认关闭项](#默认关闭项)
|
||||
- [权限对象选择](#权限对象选择)
|
||||
- [记录操作默认策略](#记录操作默认策略)
|
||||
- [field_perms 构造 SOP](#field_perms-构造-sop)
|
||||
- [视图权限默认策略](#视图权限默认策略)
|
||||
|
||||
---
|
||||
|
||||
## 顶层结构 (AdvPermBaseRoleConfig)
|
||||
|
||||
```json
|
||||
{
|
||||
"role_name": "财务审核员",
|
||||
"role_type": "custom_role",
|
||||
"base_rule_map": { "copy": false, "download": false },
|
||||
"table_rule_map": { "订单表": { "perm": "edit", "...": "..." } },
|
||||
"dashboard_rule_map": { "销售看板": { "perm": "read_only" } },
|
||||
"docx_rule_map": { "文档A": { "perm": "edit", "allow_download": true } }
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|----|------|
|
||||
| `role_name` | string | 是 | 角色名称，不能为空 |
|
||||
| `role_type` | string | 是 | 角色类型，见 [RoleType](#角色类型-roletype) |
|
||||
| `base_rule_map` | map\<string, bool\> | 是 | Base 级权限，见 [BaseRuleMap](#base-级权限-baserulemap) |
|
||||
| `table_rule_map` | map\<string, TableRule\> | 否 | 数据表权限，key 为表名 |
|
||||
| `dashboard_rule_map` | map\<string, DashboardRule\> | 否 | 仪表盘权限，key 为仪表盘名称 |
|
||||
| `docx_rule_map` | map\<string, DocxRule\> | 否 | 文档权限（仅单品模式），key 为文档名称 |
|
||||
|
||||
---
|
||||
|
||||
## 角色类型 (RoleType)
|
||||
|
||||
| 值 | 说明 |
|
||||
|------|------|
|
||||
| `editor` | 系统角色：编辑者 |
|
||||
| `reader` | 系统角色：阅读者 |
|
||||
| `custom_role` | 自定义角色 |
|
||||
|
||||
**注意**:
|
||||
- 创建接口（`+role-create`）仅支持 `custom_role`
|
||||
- 更新接口（`+role-update`）支持 `editor` / `reader` / `custom_role`
|
||||
|
||||
---
|
||||
|
||||
## 读取与更新角色
|
||||
|
||||
- `+role-list` 用于定位角色，返回角色摘要；系统角色和自定义角色都可能出现在列表中。
|
||||
- `+role-get` 返回完整权限配置。更新前先用它确认当前 `role_name`、`role_type` 和已有权限结构。
|
||||
- `+role-update` 是 delta merge，只提交需要变更的字段；但 `role_name` 和 `role_type` 仍要带当前值，避免误改角色身份信息。
|
||||
- `+role-delete` 仅适用于自定义角色；系统角色可以在权限上限内调整配置，但不可删除。
|
||||
|
||||
---
|
||||
|
||||
## Base 级权限 (BaseRuleMap)
|
||||
|
||||
1. 默认值均为 `false`，当需要启用时设置为 `true`。
|
||||
2. 在新增角色和修改角色时需要默认带上这个字段，**严禁**在用户未明确要求的情况下将其设置为 `true`。
|
||||
|
||||
```json
|
||||
{
|
||||
"base_rule_map": {
|
||||
"copy": true,
|
||||
"download": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Key | 说明 |
|
||||
|-----|------|
|
||||
| `copy` | 允许复制多维表格内容 |
|
||||
| `download` | 允许创建副本、下载、打印多维表格 |
|
||||
|
||||
---
|
||||
|
||||
## 仪表盘权限 (DashboardRule)
|
||||
|
||||
```json
|
||||
{
|
||||
"dashboard_rule_map": {
|
||||
"销售看板": { "perm": "read_only" },
|
||||
"内部数据": { "perm": "no_perm" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `perm` | string | 仪表盘权限 |
|
||||
|
||||
**perm 可选值**:
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `read_only` | 仅可阅读 |
|
||||
| `no_perm` | 无权限 |
|
||||
|
||||
---
|
||||
|
||||
## 文档权限 (DocxRule)
|
||||
|
||||
> ⚠️ 仅在单品模式（`is_base_solo = true`）下可用。
|
||||
|
||||
```json
|
||||
{
|
||||
"docx_rule_map": {
|
||||
"文档A": { "perm": "edit", "allow_download": true },
|
||||
"文档B": { "perm": "read_only" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `perm` | string | 是 | 文档权限 |
|
||||
| `allow_download` | bool | 否 | 是否允许下载/导出 |
|
||||
|
||||
**perm 可选值**:
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `edit` | 可编辑 |
|
||||
| `read_only` | 仅可阅读 |
|
||||
| `no_perm` | 无权限 |
|
||||
|
||||
---
|
||||
|
||||
## 数据表权限 (TableRule)
|
||||
|
||||
```json
|
||||
{
|
||||
"table_rule_map": {
|
||||
"订单表": {
|
||||
"perm": "edit",
|
||||
"view_rule": { "..." : "..." },
|
||||
"record_rule": { "..." : "..." },
|
||||
"field_rule": { "..." : "..." }
|
||||
},
|
||||
"用户表": {
|
||||
"perm": "read_only"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `perm` | string | 表级权限，见 [TablePerm](#表级权限-tableperm) |
|
||||
| `view_rule` | ViewRule | 视图权限配置 |
|
||||
| `record_rule` | RecordRule | 记录权限配置 |
|
||||
| `field_rule` | FieldRule | 字段权限配置 |
|
||||
|
||||
**注意**: 当 `perm` 为 `no_perm` 时，`view_rule`、`record_rule`、`field_rule` 均无须再设置。
|
||||
|
||||
---
|
||||
|
||||
### 表级权限 (TablePerm)
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `manage` | 可管理 |
|
||||
| `edit` | 可编辑 |
|
||||
| `read_only` | 仅可阅读 |
|
||||
| `no_perm` | 无权限（此时不能再设置视图、记录和字段的权限） |
|
||||
|
||||
---
|
||||
|
||||
### 视图权限 (ViewRule)
|
||||
|
||||
```json
|
||||
{
|
||||
"view_rule": {
|
||||
"allow_edit": true,
|
||||
"visibility": {
|
||||
"all_visible": false,
|
||||
"visible_views": ["表格视图", "看板视图"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|----------------------------|
|
||||
| `allow_edit` | bool | 可新增、删除、修改视图；表权限为 `edit` 时默认为 `true`，表权限为 `read_only` 或用户明确限制时为 `false` |
|
||||
| `visibility` | object | 可见的视图配置 |
|
||||
| `visibility.all_visible` | bool | 是否全部可见 |
|
||||
| `visibility.visible_views` | []string | 可见视图名称 列表 |
|
||||
|
||||
**⚠️ 核心规则：`view_rule` 必须同时包含 `allow_edit` 和 `visibility` 两个字段，缺一不可。**
|
||||
|
||||
输出 `view_rule` 时，**必须**使用以下完整结构，根据场景选择对应模板：
|
||||
|
||||
```json
|
||||
// 情况 A：表权限为 edit 且用户未明确限制 → allow_edit 默认为 true，全部可见
|
||||
{
|
||||
"view_rule": {
|
||||
"allow_edit": true,
|
||||
"visibility": {
|
||||
"all_visible": true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 情况 B：表权限为 read_only，或用户明确说不可编辑视图 → 全部可见、不可编辑
|
||||
{
|
||||
"view_rule": {
|
||||
"allow_edit": false,
|
||||
"visibility": {
|
||||
"all_visible": true
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 情况 C：用户提及了具体视图 → 仅指定视图可见（allow_edit 仍按 A/B 规则判断）
|
||||
{
|
||||
"view_rule": {
|
||||
"allow_edit": true,
|
||||
"visibility": {
|
||||
"all_visible": false,
|
||||
"visible_views": ["表格视图", "看板视图"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**注意**:
|
||||
- 当 `all_visible` 为 `false` 时，`visible_views` 不可为空，必须指定至少一个可见视图
|
||||
- `biz_type` 为 `query_form_view` 的视图不可放在 `visible_views` 中（不能配置可见性）
|
||||
|
||||
---
|
||||
|
||||
### 字段权限 (FieldRule)
|
||||
|
||||
```json
|
||||
{
|
||||
"field_rule": {
|
||||
"field_perm_mode": "specify",
|
||||
"field_perms": {
|
||||
"金额": "edit",
|
||||
"备注": "read",
|
||||
"密码": "no_perm"
|
||||
},
|
||||
"allow_edit_and_modify_option_fields": [],
|
||||
"allow_edit_and_download_file_fields": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `field_perm_mode` | string | 字段权限模式 |
|
||||
| `field_perms` | map\<string, string\> | 字段名 → 权限，仅 `field_perm_mode` 为 `specify` 时有效 |
|
||||
| `allow_edit_and_modify_option_fields` | []string | 允许增删改选项的字段名列表 |
|
||||
| `allow_edit_and_download_file_fields` | []string | 允许下载附件的字段名列表 |
|
||||
|
||||
**field_perm_mode 可选值**:
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `all_edit` | 所有字段可编辑，但选项不可增删改 |
|
||||
| `all_read` | 所有字段可读 |
|
||||
| `specify` | 指定字段权限（可进一步设置 `field_perms` 和选项增删改权限） |
|
||||
| `no_perm` | 无权限 |
|
||||
|
||||
**field_perms 中单个字段的权限值**:
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `edit` | 可编辑（含新增和阅读权限） |
|
||||
| `create` | 可新增（含阅读权限） |
|
||||
| `read` | 可阅读 |
|
||||
| `no_perm` | 无权限 |
|
||||
|
||||
**⚠️ field_perms 重要规则**:
|
||||
1. 写入前必须先查看字段的 `type`
|
||||
2. `formula` / `lookup` / `auto_number` 类型字段**必须强制**降级为 `read` 或 `no_perm`，**严禁**设为 `edit`
|
||||
3. 必须输出除 4 个系统字段外的所有字段
|
||||
4. `allow_edit_and_modify_option_fields`：仅当用户明确要求"允许增删改选项"时才配置，否则必须为空数组 `[]`。仅支持 `select` 类型字段
|
||||
5. `allow_edit_and_download_file_fields`：用户没有要求时不要设置，且仅 `field_perm_mode` 为 `specify` 时才能设置
|
||||
|
||||
---
|
||||
|
||||
### 记录权限 (RecordRule)
|
||||
|
||||
```json
|
||||
{
|
||||
"record_rule": {
|
||||
"record_operations": ["add"],
|
||||
"edit_filter_rule_group": {
|
||||
"conjunction": "and",
|
||||
"filter_rules": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"filters": [
|
||||
{
|
||||
"field_name": "部门",
|
||||
"operator": "is",
|
||||
"filter_values": ["财务部"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"other_record_all_read": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `record_operations` | []string | 记录操作权限，仅 `TablePerm = edit` 时有效 |
|
||||
| `edit_filter_rule_group` | FilterRuleGroup | 可编辑记录的筛选条件，范围为所有记录时此字段为空 |
|
||||
| `other_record_all_read` | bool | 是否可阅读所有记录。都可读时为 `true`，其他情况为 `false` |
|
||||
| `read_filter_rule_group` | FilterRuleGroup | 可阅读记录的额外筛选规则。仅当可阅读范围与可编辑范围不一致时设置（依赖 `other_record_all_read = false`） |
|
||||
|
||||
**record_operations 可选值**:
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `add` | 可新增记录 |
|
||||
| `delete` | 可删除记录 |
|
||||
|
||||
---
|
||||
|
||||
### 筛选条件 (FilterRuleGroup)
|
||||
|
||||
```json
|
||||
{
|
||||
"conjunction": "and",
|
||||
"filter_rules": [
|
||||
{
|
||||
"conjunction": "and",
|
||||
"filters": [
|
||||
{
|
||||
"field_name": "部门",
|
||||
"operator": "is",
|
||||
"filter_values": ["财务部"]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**FilterRuleGroup 结构**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `conjunction` | string | 逻辑连接词：`and` / `or` |
|
||||
| `filter_rules` | []FilterRule | 筛选规则数组 |
|
||||
|
||||
**FilterRule 结构**:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `conjunction` | string | 逻辑连接词，默认 `and` |
|
||||
| `filters` | []Filter | 筛选条件数组 |
|
||||
|
||||
**Filter 结构**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `field_name` | string | 是 | 字段名。仅限 `can_filter` 为 `true` 的字段。若服务端要求当前用户类条件，可按 API 返回结构处理 |
|
||||
| `operator` | string | 是 | 操作符，见下表 |
|
||||
| `field_type` | string | 否 | 通常由服务端 filterFiller 补全；Agent 判断字段类型时以 `+field-list` / 字段操作接口的 `type` 为准，常见可筛选类型包括 `select`、`user`、`created_by`、`number` 及部分 `formula` / `lookup` |
|
||||
| `reference_type` | string | 条件 | 引用类型。`field_type` 为公式或引用字段时必须赋值，其他情况不能赋值 |
|
||||
| `filter_values` | []string | 条件 | 筛选值。`operator` 为 `isEmpty` / `isNotEmpty` 时不设置，字段类型为 `user` 时也无需设置，其他情况必须设置。值为选项的 `name` |
|
||||
| `field_ui_type` | string | 条件 | 该字段有值时一定要填 |
|
||||
| `is_invalid` | bool | 否 | 判断筛选条件是否有效 |
|
||||
|
||||
**operator 可选值**:
|
||||
|
||||
| 值 | 说明 |
|
||||
|----|------|
|
||||
| `is` | 等于 |
|
||||
| `isNot` | 不等于 |
|
||||
| `contains` | 包含 |
|
||||
| `doesNotContain` | 不包含 |
|
||||
| `isEmpty` | 为空 |
|
||||
| `isNotEmpty` | 不为空 |
|
||||
| `isGreater` | 大于 |
|
||||
| `isGreaterEqual` | 大于等于 |
|
||||
| `isLess` | 小于 |
|
||||
| `isLessEqual` | 小于等于 |
|
||||
|
||||
**注意**:
|
||||
- `field_type`、`field_ui_type`、`reference_type` 在创建/更新角色时由服务端 filterFiller 自动补全，客户端通常只需传 `field_name`、`operator`、`filter_values`
|
||||
|
||||
---
|
||||
|
||||
## 默认权限策略与风控规则
|
||||
|
||||
构造角色配置 JSON 时，采用 **默认拒绝与权限最小化** 策略。用户未明确提及的权限一律不开放，不因"合理猜测""常见做法"主动扩展权限范围。
|
||||
|
||||
### 默认关闭项
|
||||
|
||||
以下能力在用户未明确说明时**默认关闭**：
|
||||
|
||||
| 能力 | 默认值 | 开启条件 |
|
||||
|------|--------|----------|
|
||||
| 未提及的数据表的任何访问 | `no_perm` | 用户明确提及该表 |
|
||||
| 仪表盘访问 | 不配置 | 用户明确提及该仪表盘 |
|
||||
| `base_rule_map.copy` | `false` | 用户明确要求"允许复制" |
|
||||
| `base_rule_map.download` | `false` | 用户明确要求"允许下载/打印/副本" |
|
||||
|
||||
### 默认开启项（条件性）
|
||||
|
||||
以下能力在特定条件下**默认开启**，用户明确限制时才排除：
|
||||
|
||||
| 能力 | 默认值 | 排除条件 |
|
||||
|------|--------|----------|
|
||||
| `record_operations` 中的 `delete` | **包含**（`perm = edit` 时） | 用户明确限制时才排除 |
|
||||
| `view_rule.allow_edit` | **`true`**（`perm = edit` 时） | 用户明确限制"不可编辑视图"或 `perm = read_only` 时设为 `false` |
|
||||
|
||||
---
|
||||
|
||||
### Editor / Reader 的权限上限规则
|
||||
1. 对 Editor 与 Reader，系统允许修改其权限配置，但同时施加以下封顶约束：
|
||||
2. Reader 的任一权限项 不允许超过「仅可阅读」
|
||||
3. Reader 不允许拥有任何可编辑、可新增、可删除相关权限; Editor 的权限可被修改，但其能力范围受高级权限能力封顶。
|
||||
|
||||
### 权限对象选择
|
||||
|
||||
**注意**:
|
||||
- 仅对用户明确指向的权限对象生成配置（明确提及的表名、仪表盘名，或可解析为唯一对象的指代如"当前表""这张表"）
|
||||
- **严禁**基于业务常识、岗位职责、名称相似性或其他角色的历史配置推断或扩展权限对象
|
||||
- 用户未明确提及的对象不生成任何权限配置，视为 `no_perm`
|
||||
|
||||
---
|
||||
|
||||
### 记录操作默认策略
|
||||
|
||||
**注意**:
|
||||
- 用户未提及时，表权限为 `edit` 时默认同时包含 `add` 和 `delete`，默认不包含 `delete` 的情况仅适用于用户明确限制操作的场景
|
||||
- 阅读范围默认对齐编辑范围：用户仅描述可编辑范围、未说明阅读范围时，可阅读范围与可编辑范围保持一致，不主动扩大
|
||||
- 当可读范围与可编辑范围一致时，**不得**生成 `read_filter_rule_group`；应设置 `other_record_all_read = false` 且 `read_filter_rule_group = null`
|
||||
|
||||
**⚠️ 记录操作限制**:
|
||||
1. `perm` 为 `read_only` 时，`record_rule.record_operations` **只能为空**
|
||||
2. 同步表（`is_sync = true`）**严禁**新增和删除记录
|
||||
|
||||
---
|
||||
|
||||
### field_perms 构造 SOP
|
||||
|
||||
在生成 `field_perms` 时，**严禁**依赖模糊的"继承"概念，必须按以下步骤执行：
|
||||
|
||||
| 步骤 | 操作 | 说明 |
|
||||
|------|------|------|
|
||||
| 1. 基准设定 | `perm = edit` → 全部字段预设 `"edit"`；`perm = read_only` → 全部预设 `"read"` | 基于 `base_table_info` 中的全量字段 |
|
||||
| 2. 物理降级 | `formula` / `lookup` / `auto_number` 及系统字段 → 强制降级为 `"read"` | 不可变字段严禁设为 `edit` |
|
||||
| 3. 用户覆盖 | 仅对用户**显式指定**了特定权限的字段应用 `no_perm` / `read` / `create` | 未显式指定的保持基准值 |
|
||||
| 4. 反筛选误判 | 用于 `filter_rules` 的字段，若基准为 `"edit"` 且用户未要求降级 → **保持 `"edit"`** | 筛选条件不影响字段可编辑性 |
|
||||
| 5. 筛选依赖兜底 | 出现在 `filter_rules` 中的字段**不允许**遗漏，权限至少为 `"read"` | 最终校验步骤 |
|
||||
|
||||
**⚠️ field_perm_mode 选择规则**:
|
||||
1. 用户以"所有字段""全字段"等整体性表述描述且不要求选项增删改时，**必须**使用 `all_edit` / `all_read`，**严禁**变为逐字段 `specify`
|
||||
2. 仅在以下情况使用 `specify`：用户明确提出字段级差异需求、不同字段权限目标存在显著差异、或明确要求配置选项增删改权限
|
||||
3. 系统字段硬性约束导致的自动降级**不视为**差异，不触发 `specify`
|
||||
4. 对"仅""只能""部分"等约束定语，范围外的字段按定语的反方向设置
|
||||
|
||||
**⚠️ 同步表限制**: `is_sync = true` 的表**严禁**设置字段为 `edit` 或 `create`
|
||||
|
||||
---
|
||||
|
||||
### 视图权限默认策略
|
||||
|
||||
**判断流程（必须按顺序执行，命中即停）**:
|
||||
|
||||
1. **先判断用户是否提及了具体视图名称**（如"看板视图可见""甘特图不可编辑"等）
|
||||
- **是** → `all_visible = false`，`visible_views` 仅包含用户明确提及为"可见"的视图名称（非 viewID）；未提及的视图视为不可见
|
||||
- **否**（用户完全未提及任何视图）→ `all_visible = true`
|
||||
2. `allow_edit` 在表权限为 `edit` 时**默认为 `true`**；仅当用户明确限制"不可编辑视图"时才设为 `false`。设为 `true` 时仍**必须**包含 `visibility` 字段（参考视图权限 情况 A）
|
||||
3. `all_visible` 为 `false` 时，`visible_views` **不可为空**，必须至少包含一个视图
|
||||
|
||||
**❌ 常见错误 — 缺少 `visibility` 字段：**
|
||||
```json
|
||||
// 错误！缺少 visibility
|
||||
{ "view_rule": { "allow_edit": false } }
|
||||
```
|
||||
**✅ 正确写法：**
|
||||
```json
|
||||
// 即使全部可见，也必须显式写出 visibility
|
||||
{ "view_rule": { "allow_edit": false, "visibility": { "all_visible": true } } }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 字段类型与筛选算子的强约束关系
|
||||
|
||||
当字段被用于记录筛选条件时，字段操作接口返回的 `type` 与可用算子存在固定绑定关系：
|
||||
|
||||
**`user` / `created_by` 类型字段：**
|
||||
- 仅允许使用 `contains` 算子
|
||||
- 不允许使用 `is`、`isNot` 等精确匹配算子
|
||||
- 这是当前成员匹配模式，筛选条件中无需填写具体成员值；不要在 `filter_values` 中写入姓名或用户 ID
|
||||
|
||||
**`select` (`multiple=false`) 类型字段：**
|
||||
- `is` 与 `isNot` 算子仅允许用于匹配**单一选项**，不得用于多个值
|
||||
- 当用户表达"字段值等于/不等于某一个具体选项"（如"出勤状态不等于出勤"）时，Agent 必须使用 `is` / `isNot`，且 filter_values 仅包含单一值。
|
||||
- 当用户表达"字段值等于/不等于多个选项集合"（如"学历不是专科和其他"）时，Agent 必须使用 `contains` / `doesNotContain`，并将多个选项填入 filter_values。
|
||||
- `contains` / `doesNotContain`中的filter_values可包含多个值，表示或关系
|
||||
|
||||
**`select` (`multiple=true`) 类型字段：**
|
||||
- `is` / `isNot`：filter_values 允许填写多个选项
|
||||
- 当 operator = is 且勾选 A、B 时，语义为该字段**同时包含** A 和 B（A&B），不是"等于 A 或等于 B"
|
||||
- 当用户表达"包含任一选项"时，除了可以使用 contains 实现外，也可以使用 is 并且配套通过 filter_rules.conjunction = or 实现
|
||||
- `contains` / `doesNotContain`：用于表达"包含任一选项/不包含任一选项"，filter_values 可填写多个选项（系统按"任一匹配"处理）；若要表达"等于 A 或等于 B"，应拆成多条筛选条件并用「或」组合。
|
||||
|
||||
**百分比字段**
|
||||
- 对于 query 中“数字”的筛选条件时，如果涉及到百分比，要原封不动地还原用户给你的数值（百分比都变成小数）。比如“大于 20%”则变成“大于 0.2”、“xx 率小于 60”则变成“小于 0.6”。
|
||||
|
||||
### 被用于筛选的字段的 field_perms 权限强制要求
|
||||
|
||||
当某字段（系统字段没有此要求）被用于「满足特定条件的记录」中的筛选条件时，系统将根据当前数据表权限与记录权限，自动施加以下**不可变约束**：
|
||||
|
||||
**筛选字段的读写一致性：**
|
||||
- 若表权限为 edit，且字段类型属于【可编辑字段】，则筛选字段必须保持 edit 权限，除非用户显式要求降级。
|
||||
- 严禁因为字段被用作筛选条件而将其降级为 read。筛选条件仅要求字段可见，不要求字段只读。
|
||||
|
||||
**新增记录时的字段最低权限：**
|
||||
- 当且仅当记录权限包含「可新增记录」时，字段至少为可新增（create），用于保证在新增记录时筛选条件字段可被正确写入。
|
||||
- 若当前记录权限为「仅可阅读」，则不触发该约束。
|
||||
|
||||
**字段是否可编辑（edit）不作强制要求**，由具体权限方案决定，不属于 infra 强制约束范围。
|
||||
|
||||
上述由系统自动施加的字段权限，不可被手动取消或降级。
|
||||
132
.agents/skills/lark-calendar/SKILL.md
Normal file
132
.agents/skills/lark-calendar/SKILL.md
Normal file
@ -0,0 +1,132 @@
|
||||
---
|
||||
name: lark-calendar
|
||||
version: 1.0.0
|
||||
description: "飞书日历：管理日历日程和会议室。查看/搜索日程、创建/更新日程、管理参会人、查询忙闲和推荐时段、预定会议室。当用户需要查看日程安排、创建/修改会议、查询/预定会议室时使用。不负责：查询过去的视频会议记录（走 lark-vc）、待办任务（走 lark-task）。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli calendar --help"
|
||||
---
|
||||
|
||||
# calendar (v4)
|
||||
|
||||
开始前先读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)（认证、权限处理）。
|
||||
|
||||
**CRITICAL — 凡涉及预约日程/会议或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！**
|
||||
|
||||
## 身份
|
||||
|
||||
日程操作默认使用 `--as user`（查看和管理当前用户的日程）。`--as bot` 只能访问 bot 自己的（空）日历，会拿到空结果——不要用 bot 身份查用户日程。
|
||||
|
||||
```bash
|
||||
# BAD — bot 身份查用户日程，返回空列表
|
||||
lark-cli calendar +agenda --as bot
|
||||
|
||||
# GOOD — user 身份查日程
|
||||
lark-cli calendar +agenda --as user
|
||||
```
|
||||
|
||||
## Shortcuts
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
|
||||
| [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
|
||||
| [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 |
|
||||
| [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和 RSVP 状态 |
|
||||
| [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
|
||||
| [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
|
||||
| [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
|
||||
|
||||
## 前置条件路由
|
||||
|
||||
| 场景 | 前置要求 |
|
||||
|------|----------|
|
||||
| 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
|
||||
| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
|
||||
| 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
|
||||
| 调用任何 Shortcut | 先读其对应 reference 文档 |
|
||||
|
||||
## 核心概念
|
||||
|
||||
- **日程实例（Instance）**：重复性日程展开后的具体时间实例。操作重复日程的某次实例时，必须先定位该实例的 `event_id`，禁止使用原重复日程的 `event_id`。
|
||||
- **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
|
||||
- **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
|
||||
- **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
|
||||
|
||||
## 术语映射
|
||||
|
||||
用户日常说的"帮我约个日历""查一下今天的日历"，实际意图是针对**日程（Event）**的创建或查询，而非操作日历（Calendar）容器本身。自动将口语化的"日历"意图映射为"日程"操作。
|
||||
|
||||
## 意图路由
|
||||
|
||||
| 用户意图 | 路由到 |
|
||||
|----------|--------|
|
||||
| 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
|
||||
| 查询日历/日程或未来时间的会议 | 本 skill |
|
||||
| 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
|
||||
|
||||
## 任务类型分流
|
||||
|
||||
处理"预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间"时，必须先判断新建 vs 编辑：
|
||||
|
||||
- **编辑已有日程的强信号**：用户提到已存在的日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（添加、移除、改到、换会议室、调整时间）。默认走编辑流，绝不能按新建处理。
|
||||
- **新建日程**：用户表达新增意图（"新约一个会""创建一个日程""安排一次会议"），且没有指向既有日程的修改动作。
|
||||
|
||||
## 时间推断规范
|
||||
|
||||
- **星期的定义**：周一是一周的第一天，周日是最后一天。计算"下周一"等相对日期时，基于当前真实日期推算。
|
||||
- **一天的范围**：用户提到"明天""今天"等泛指某天时，时间范围应覆盖整天，不要自行缩减。
|
||||
- **历史时间约束**：不能预约已经完全过去的时间。唯一例外是"跨越当前时间"的日程（开始在过去、结束在未来）。
|
||||
|
||||
## 会议室规则
|
||||
|
||||
- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)。
|
||||
- `+room-find` 的时间输入必须是确定时间块，不能是时间区间搜索。
|
||||
- 用户仅要求"查会议室"但未提供明确时间时，必须先调用 `+suggestion` 获取可用时间块，再将时间块交给 `+room-find`。严禁猜测时间盲目调用。
|
||||
- 编辑已有日程时，"添加会议室"默认是增量语义，保留已有会议室；只有用户明确说"更换会议室""移除会议室"时才删除旧会议室。
|
||||
|
||||
## API Resources
|
||||
|
||||
```bash
|
||||
lark-cli calendar <resource> <method> [flags]
|
||||
```
|
||||
|
||||
### calendars
|
||||
|
||||
- `create` — 创建共享日历
|
||||
- `delete` — 删除共享日历
|
||||
- `get` — 查询日历信息
|
||||
- `list` — 查询日历列表
|
||||
- `patch` — 更新日历信息
|
||||
- `primary` — 查询用户主日历
|
||||
- `search` — 搜索日历
|
||||
|
||||
### event.attendees
|
||||
|
||||
- `batch_delete` — 删除日程参与人
|
||||
- `create` — 添加日程参与人
|
||||
- `list` — 获取日程参与人列表
|
||||
|
||||
### events
|
||||
|
||||
- `create` — 创建日程
|
||||
- `delete` — 删除日程
|
||||
- `get` — 获取日程
|
||||
- `instance_view` — 查询日程视图
|
||||
- `patch` — 更新日程
|
||||
- `search_event` — 搜索日程（仅返回 日程ID/主题/时间，详情需走 `events get`）
|
||||
- `share_info` — 获取日程分享链接
|
||||
|
||||
### freebusys
|
||||
|
||||
- `list` — 查询主日历日程忙闲信息
|
||||
|
||||
## 不在本 skill 范围
|
||||
|
||||
- 查询过去的视频会议记录 → [lark-vc](../lark-vc/SKILL.md)
|
||||
- 待办任务管理 → [lark-task](../lark-task/SKILL.md)
|
||||
- 会议室物理设施管理 → 管理员后台
|
||||
|
||||
**注意（强制性）：**
|
||||
- 涉及日期（时间）字符串与时间戳的相互转换时，务必调用系统命令或脚本代码等外部工具进行处理，以确保转换的绝对准确。违者将导致严重的逻辑错误！
|
||||
@ -0,0 +1,78 @@
|
||||
|
||||
# calendar +agenda
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
查看近期日程安排。只读操作，不修改任何日程。
|
||||
|
||||
需要的scopes: ["calendar:calendar.event:read"]
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 查看今天日程（默认）
|
||||
lark-cli calendar +agenda
|
||||
|
||||
# 自定义时间范围（ISO 8601）
|
||||
lark-cli calendar +agenda --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
|
||||
|
||||
# 自定义时间范围（仅日期）
|
||||
lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17
|
||||
|
||||
# 人类可读格式输出
|
||||
lark-cli calendar +agenda --format pretty
|
||||
|
||||
# 指定日历
|
||||
lark-cli calendar +agenda --calendar-id cal_xxx
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期，默认当天） |
|
||||
| `--end <time>` | 否 | 结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） |
|
||||
| `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
|
||||
| `--format` | 否 | 输出格式：json（默认） \| pretty |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## 时间格式
|
||||
|
||||
`--start` 和 `--end` 支持以下格式：
|
||||
|
||||
| 格式 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| ISO 8601 | `2026-03-10T14:00:00+08:00` | 完整格式 |
|
||||
| 日期+时间 | `2026-03-10 14:00:00` | 自动补全时区 |
|
||||
| 仅日期 | `2026-03-10` | start 取 00:00:00，end 取 23:59:59 |
|
||||
| Unix 时间戳 | `1741564800` | 秒级时间戳 |
|
||||
|
||||
## 输出格式
|
||||
|
||||
**将结果整理为易读的日程表：**
|
||||
|
||||
```
|
||||
## 2026-03-10 周一
|
||||
|
||||
09:00 - 09:30 站会
|
||||
10:00 - 11:00 产品评审
|
||||
14:00 - 15:00 与 Alice 1:1
|
||||
|
||||
## 2026-03-11 周二
|
||||
|
||||
（无日程）
|
||||
```
|
||||
|
||||
**注意：按日期分组，并严格按照开始时间升序（从早到晚的时间线）排序输出。** 显示标题、时长
|
||||
|
||||
## 提示
|
||||
|
||||
- 已取消的日程会自动过滤，无需额外处理。
|
||||
- 如无日程，告知用户"日程清空"。
|
||||
- 大于 40 天的时间范围会自动拆分查询并合并结果。
|
||||
- 查看多个日历：先用 `lark-cli calendar calendars list --page-all` 列出日历列表，再逐个查询。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar](../SKILL.md) -- 日历全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
106
.agents/skills/lark-calendar/references/lark-calendar-create.md
Normal file
106
.agents/skills/lark-calendar/references/lark-calendar-create.md
Normal file
@ -0,0 +1,106 @@
|
||||
|
||||
# calendar +create
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
创建日程并按需邀请参会人。
|
||||
|
||||
需要的scopes: ["calendar:calendar.event:create","calendar:calendar.event:update"]
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
# 创建日程 + 邀请参会人（ISO 8601 时间）
|
||||
lark-cli calendar +create \
|
||||
--summary "产品评审" \
|
||||
--start "2026-03-12T14:00+08:00" \
|
||||
--end "2026-03-12T15:00+08:00" \
|
||||
--attendee-ids ou_aaa,ou_bbb
|
||||
|
||||
# 无参会人
|
||||
lark-cli calendar +create \
|
||||
--summary "午餐" \
|
||||
--start "2026-03-12T12:00+08:00" \
|
||||
--end "2026-03-12T13:00+08:00"
|
||||
|
||||
# 指定日历
|
||||
lark-cli calendar +create --summary "..." --start "..." --end "..." \
|
||||
--calendar-id cal_xxx
|
||||
```
|
||||
|
||||
参数：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--summary <text>` | 否 | 日程标题。注意：标题中不应该出现时间、地点、人物信息 |
|
||||
| `--start <time>` | 是 | 开始时间（ISO 8601，如 `2026-03-12T14:00+08:00`） |
|
||||
| `--end <time>` | 是 | 结束时间（ISO 8601） |
|
||||
| `--description <text>` | 否 | 日程详细描述。提供会议议程、活动内容、注意事项或链接等。与 summary 配合使用，仅关注当前日程信息 |
|
||||
| `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀 |
|
||||
| `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
|
||||
| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
> **⚠️ `rrule` 规则限制：飞书日历系统不支持 `COUNT` 参数。遇到限制重复次数的需求，必须根据开始时间和频率自行推算并转换成 `UNTIL=<具体日期>` 格式。**
|
||||
> 自动设置 `attendee_ability: "can_modify_event"`，参会人可查看彼此并编辑日程。
|
||||
> 自动设置 `free_busy_status: "busy"`，默认日程忙闲状态为忙碌。
|
||||
> 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。
|
||||
> 自动设置 `vchat: {"vc_type": "vc"}`，默认日程包含飞书视频会议。如需其他视频会议类型或不含视频会议，请使用完整 API 命令。
|
||||
> 失败保护：若添加参会人失败（如 open_id 错误），CLI 会自动删除刚创建的空日程（回滚，不通知参会人）。
|
||||
|
||||
## 高级用法（完整 API 命令）
|
||||
|
||||
如需配置 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、参与人可选参加状态或全天日程等高级参数，请使用完整的 API 命令：
|
||||
**注意**：
|
||||
- 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天。如果只有一天的话，开始日期和结束日期是相同。
|
||||
|
||||
```bash
|
||||
# 第一步：创建日程（含高级参数）
|
||||
## 查看完整参数定义
|
||||
lark-cli schema calendar.events.create
|
||||
## 创建日程
|
||||
lark-cli calendar events create \
|
||||
--params '{"calendar_id":"<CALENDAR_ID>"}' \
|
||||
--data '{
|
||||
"summary": "技术分享：CLI 架构设计",
|
||||
"start_time": { "timestamp": "1741586400" },
|
||||
"end_time": { "timestamp": "1741593600" }
|
||||
}'
|
||||
|
||||
# 第二步：添加参会人（使用第一步返回的 calendar_id 和 event_id）
|
||||
## 查看完整参数定义
|
||||
lark-cli schema calendar.event.attendees.create
|
||||
## 添加参会人
|
||||
lark-cli calendar event.attendees create \
|
||||
--params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
|
||||
--data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}'
|
||||
|
||||
# 可选第三步（推荐）：若第二步失败，回滚删除空日程
|
||||
## 查看完整参数定义
|
||||
lark-cli schema calendar.events.delete
|
||||
## 删除空日程
|
||||
lark-cli calendar events delete \
|
||||
--params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>","need_notification":false}'
|
||||
|
||||
```
|
||||
|
||||
> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
|
||||
> 当你手动拆成两步执行时，建议保留“失败后回滚删除”的第三步，避免遗留空日程。
|
||||
|
||||
## 参会人类型
|
||||
|
||||
| `type` | `user_id` 格式 | 说明 |
|
||||
|--------|---------------|------|
|
||||
| `user` | `ou_xxx`（open_id） | 飞书用户 |
|
||||
| `group` | `oc_xxx` | 飞书群组 |
|
||||
| `resource` | `omm_xxx` | 会议室 |
|
||||
| `third_party` | 邮箱地址 | 外部参会人 |
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作** -- 执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar](../SKILL.md) -- 日历全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
- [lark-calendar-suggestion](lark-calendar-suggestion.md) -- 根据非明确时间或一段时间范围，推荐多个可用时间块方案
|
||||
@ -0,0 +1,124 @@
|
||||
|
||||
# calendar +freebusy
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
|
||||
|
||||
查询用户主日历的忙闲信息，返回指定时间范围内的忙碌时段列表和rsvp的状态。
|
||||
|
||||
需要的scopes: ["calendar:calendar.free_busy:read"]
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 查询当前用户今天的忙闲（默认）
|
||||
lark-cli calendar +freebusy
|
||||
|
||||
# 自定义时间范围（仅日期）
|
||||
lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12
|
||||
|
||||
# 自定义时间范围（完整 ISO 8601）
|
||||
lark-cli calendar +freebusy --start "2026-03-11T08:00:00+08:00" --end "2026-03-11T18:00:00+08:00"
|
||||
|
||||
# 查询指定用户的忙闲信息
|
||||
lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
|
||||
|
||||
# 人类可读格式输出
|
||||
lark-cli calendar +freebusy --format pretty
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--start <time>` | 否 | 查询开始时间（ISO 8601 或仅日期，默认当天） |
|
||||
| `--end <time>` | 否 | 查询结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） |
|
||||
| `--user-id <open_id>` | 否 | 目标查询用户 ID（`ou_` 前缀）。省略时默认查询当前登录用户，bot 身份调用时必须明确指定 |
|
||||
| `--format` | 否 | 输出格式：json（默认） \| pretty |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## 时间格式
|
||||
|
||||
`--start` 和 `--end` 支持以下格式：
|
||||
|
||||
| 格式 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| ISO 8601 | `2026-03-11T09:00:00+08:00` | 完整格式 |
|
||||
| 日期+时间 | `2026-03-11 09:00:00` | 自动补全时区 |
|
||||
| 仅日期 | `2026-03-11` | start 取 00:00:00，end 取 23:59:59 |
|
||||
| Unix 时间戳 | `1741564800` | 秒级时间戳 |
|
||||
|
||||
## 输出示例
|
||||
|
||||
### 表格格式
|
||||
|
||||
```
|
||||
start end rsvp_status
|
||||
---------------- ---------------- -----------
|
||||
2026-03-11 10:00 2026-03-11 10:30 接受
|
||||
2026-03-11 14:00 2026-03-11 15:00 待定
|
||||
|
||||
共 2 个忙碌时段
|
||||
```
|
||||
|
||||
### JSON 格式
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"start_time": "2026-03-11T10:00:00+08:00",
|
||||
"end_time": "2026-03-11T10:30:00+08:00",
|
||||
"rsvp_status": "accept"
|
||||
},
|
||||
{
|
||||
"start_time": "2026-03-11T14:00:00+08:00",
|
||||
"end_time": "2026-03-11T15:00:00+08:00",
|
||||
"rsvp_status": "tentative"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 典型场景
|
||||
|
||||
### 1. 查找日程会议空闲时段
|
||||
|
||||
```bash
|
||||
# 查询今天的忙碌时段
|
||||
lark-cli calendar +freebusy
|
||||
|
||||
# 查询工作时间段
|
||||
lark-cli calendar +freebusy \
|
||||
--start "2026-03-11T08:00:00+08:00" \
|
||||
--end "2026-03-11T18:00:00+08:00"
|
||||
```
|
||||
|
||||
### 2. 检查团队成员可用性
|
||||
|
||||
```bash
|
||||
# 查询多个成员，对比找出共同空闲时间
|
||||
lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_a
|
||||
lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_b
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **只查询主日历** — 此命令只返回用户主日历的忙闲信息，不包括其他订阅日历
|
||||
2. **隐私保护** — 只返回忙碌时段的起止时间，不包含日程标题、描述等详细信息
|
||||
3. **bot 身份** — bot 必须通过 `--user-id` 指定要查询的用户
|
||||
|
||||
## 与其他命令对比
|
||||
|
||||
| 命令 | 用途 | 输出内容 |
|
||||
|------|------|----------|
|
||||
| `calendar +freebusy` | 查询忙闲时段 | 只返回忙碌时段列表（无日程详情） |
|
||||
| `calendar +agenda` | 查看日程安排 | 返回完整日程列表（含标题、描述等） |
|
||||
|
||||
**选择建议**：
|
||||
- **仅需了解是否有空** → 使用 `+freebusy`（更快，隐私保护）
|
||||
- **需要查看日程详情** → 使用 `+agenda`
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar-agenda](lark-calendar-agenda.md) — 查看日程安排
|
||||
- [lark-calendar-create](lark-calendar-create.md) — 创建日程
|
||||
- [lark-calendar-suggestion](lark-calendar-suggestion.md) — 根据非明确时间或一段时间范围，推荐多个可用时间块方案
|
||||
- [lark-calendar](../SKILL.md) — 日历完整 API
|
||||
@ -0,0 +1,113 @@
|
||||
# calendar +room-find
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
|
||||
|
||||
针对一个或多个时间块查找/搜索可用会议室。会议室是日程的一种资源型参与人，不能脱离日程单独预定。
|
||||
|
||||
需要的 scopes: ["calendar:calendar.free_busy:read"]
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 已知一个或多个待选时间块，需要查找可用会议室
|
||||
- 需要在一组连续编号的会议室中批量搜索可用房间（如"帮我约一个 16~20 号之间的会议室"）
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
lark-cli calendar +room-find \
|
||||
--slot "2026-03-27T14:00:00+08:00~2026-03-27T15:00:00+08:00" \
|
||||
--slot "2026-03-27T16:00:00+08:00~2026-03-27T17:00:00+08:00" \
|
||||
--attendee-ids "ou_xxx,ou_yyy" \
|
||||
--city "北京" \
|
||||
--building "学清嘉创大厦B座" \
|
||||
--floor "F2" \
|
||||
--event-rrule "FREQ=DAILY;INTERVAL=1"
|
||||
```
|
||||
|
||||
### 批量会议室名称查询
|
||||
|
||||
当用户想在一组编号会议室中挑选可用房间时，可用英文逗号拼接多个会议室名称传入 `--room-name`：
|
||||
|
||||
```bash
|
||||
# 场景：帮我约一个 16~20 号之间的会议室
|
||||
lark-cli calendar +room-find \
|
||||
--slot "2026-03-27T14:00:00+08:00~2026-03-27T15:00:00+08:00" \
|
||||
--room-name "16,17,18,19,20"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 场景：查找 木星 或 火星 会议室
|
||||
lark-cli calendar +room-find \
|
||||
--slot "2026-03-27T14:00:00+08:00~2026-03-27T15:00:00+08:00" \
|
||||
--room-name "木星,火星"
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--slot <start~end>` | 是 | 期望查询的时间块，格式需遵循 `开始时间~结束时间`。若存在多个候选时间块，可重复传入此参数。 |
|
||||
| `--city <text>` | 否 | 会议室所在城市强约束。**仅当**用户明确说出具体城市（如北京、上海）时才提取，**严禁**根据园区或楼宇名称自行联想或补全。 |
|
||||
| `--building <text>` | 否 | 会议室所在楼宇强约束，承载城市以下、楼层以上的办公区/园区/楼栋描述。|
|
||||
| `--floor <text>` | 否 | 仅用于筛选会议室所在楼层。应先做归一化，再传递规范值；例如 `2楼` / `二楼` / `2F` 统一为 `F2`。注意：此参数只筛选楼层，不可混入区域定位（如“A区”）或具体会议室号。 |
|
||||
| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名或会议室号（如"木星""02"）时使用。当用户需要在一组编号会议室中搜索时（如"帮我约 16~20 号的会议室"），应将编号展开为逗号分隔列表，如 `"16,17,18,19,20"`。应优先传递去后缀、去冗余后的规范名，例如 `木星会议室` → `木星`，`会议室 02` / `02会议室` → `02`。 |
|
||||
| `--min-capacity <n>` | 否 | 会议室最小容纳人数。当用户明确参会人数或提出“至少容纳N人”等要求时，提取数字放入此参数，必须为正整数。 |
|
||||
| `--max-capacity <n>` | 否 | 会议室最大容纳人数。用于过滤过大空间，必须为正整数。 |
|
||||
| `--attendee-ids <id_list>` | 否 | 参会对象 ID 列表。支持用户 ID（`ou_` 前缀）和群组 ID（`oc_` 前缀），多个 ID 以逗号分隔。 |
|
||||
| `--event-rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" |
|
||||
| `--timezone <tz>` | 否 | 对话中明确提及的预约日程所使用的时区（默认取用户设备时区，例如 `Asia/Shanghai`） |
|
||||
|
||||
## 规则
|
||||
|
||||
- 多个 `--slot` 会由 CLI 内部并发调用单时间块接口，再聚合成一次输出
|
||||
- `+room-find` 的时间输入必须是**确定时间块**，不是时间区间搜索。
|
||||
- 如果是重复性日程，必须校验返回中的 `reserve_until_time`（该会议室最晚可预约时间）是否覆盖 `event-rrule` 对应的重复范围。
|
||||
- `--city` 仅在用户明确说出城市时才提取；不要仅凭 `望京办公室`、`漕河泾园区`、`南山办公室` 这类位置名自动补城市。
|
||||
- 若已经提取了 `--city`，则 `--building` 中不要再重复携带城市前缀。例如用户说 `北京学清嘉创大厦B座` 时，应提取为 `--city "北京"` 与 `--building "学清嘉创大厦B座"`，不要把 `北京学清嘉创大厦B座` 原样整体传入 `--building`。
|
||||
- 同一语义槽位只保留一个规范值。例如用户说“2楼”，应转换为 `--floor "F2"`；**禁止**同时传 `2楼 F2` 这类重复楼层信息。
|
||||
- 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。若短词更像楼层/区域定位（如 `2L`、`2F`），优先落到 `--floor`，不要默认落到 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
|
||||
- 对会议室名要做轻量归一化：`木星会议室` 应提取为 `--room-name "木星"`；`会议室 02` / `02会议室` 应提取为 `--room-name "02"`。
|
||||
- **多会议室名称场景**：当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如：
|
||||
- "帮我约 16~20 号的会议室" → `--room-name "16,17,18,19,20"`
|
||||
- "查下木星和火星是否有空" → `--room-name "木星,火星"`
|
||||
- "看看 01、02、03 会议室" → `--room-name "01,02,03"`
|
||||
- 对复合会议室号要优先拆分结构化信息：`F3-05` / `F5-07` / `3楼-08` 这类表达，若可稳定识别楼层与会议室号，应优先提取为 `--floor "F3"` + `--room-name "05"`、`--floor "F5"` + `--room-name "07"`、`--floor "F3"` + `--room-name "08"`，不要把整段直接作为 `--room-name`。
|
||||
- 当提供了会议室搜索筛选条件时，返回结果也**不保证**与搜索词完全字面匹配。底层可能会结合邻近楼层做推荐，例如用户搜索 `2层`，即使 `2层` 没有空闲会议室，也可能返回相近的 `3层` 候选。这不应被误判为接口返回异常。
|
||||
|
||||
## 输出格式
|
||||
|
||||
**将返回的候选会议室整理为易读的结构化排版向用户展示。严禁将时间和会议室名称放在同一行展示，必须分行并使用编号列表呈现可用会议室，严禁揉成一团纯文本堆叠。**
|
||||
|
||||
```text
|
||||
## 2026-03-27 周五
|
||||
|
||||
[选项 1] 14:00 - 15:00
|
||||
可用会议室：
|
||||
1. 学清嘉创大厦B座-F2-02🎦(7人)
|
||||
2. 学清嘉创大厦B座-F3-05🎦(11人)
|
||||
|
||||
💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
|
||||
```
|
||||
|
||||
> **AI 行为指导：**
|
||||
> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示。**严禁将时间与会议室名称输出在同一行**。以清晰的分行列表呈现可用会议室，并直接询问用户意向。默认原样展示完整 `room_name`；不要擅自缩写、截断、改写，或仅提取楼层及会议室号替代完整名称。
|
||||
> - **`room_name` 必须逐字透传**：展示给用户的会议室名称，必须直接使用 CLI/API 返回的 `room_name` 原值。禁止提取楼层、会议室号、容量、视频能力后重组成新的名称，禁止意译、缩写、去前缀、去后缀，或仅保留"便于阅读"的摘要名。
|
||||
> - **主动识别区间/多名称意图**：当用户提到"帮我约 XX 到 YY 号的会议室""XX~YY 之间的会议室"或一次列出多个会议室名称时，将所有目标名称展开为英文逗号分隔列表，传入 `--room-name`。例如"帮我约 16 到 20 号的会议室"应生成 `--room-name "16,17,18,19,20"`。
|
||||
> - **重复日程要明确阻断原因与自动缩短**：若某候选会议室的 `reserve_until_time` 无法覆盖重复性日程，**必须**向用户明确说明该会议室最长可约至何时。若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。不能直接按原规则继续。
|
||||
> - **正确解释推荐结果**：如果返回结果与用户输入条件不完全字面一致，先说明底层可能返回邻近位置或相近条件的推荐候选，不要直接将其判定为异常。
|
||||
> - **默认减少用户输入成本**：应主动引导用户不必一开始就提供很详细的会议室搜索条件。只要时间块已明确，用户直接表达“想约会议室”即可，先基于当前信息查询候选；只有在用户对结果不满意时，再引导其补充更具体的楼宇、楼层、会议室名或容量条件。
|
||||
|
||||
**字段说明：**
|
||||
|
||||
| 字段名 | 说明 |
|
||||
| :--- | :--- |
|
||||
| `room_id` | 会议室唯一标识，用于后续创建日程时添加为会议室参与人使用。 |
|
||||
| `room_name` | 会议室名称，默认原样完整展示给用户，不要自行缩写、截断、改写，也不要用楼层及会议室号摘要替代原值。 |
|
||||
| `capacity` | 会议室最大容纳人数。 |
|
||||
| `reserve_until_time` | 该会议室当前允许被预约到的最晚时间点，用于校验重复性日程是否超期。 |
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar-create](lark-calendar-create.md)
|
||||
- [lark-calendar-suggestion](lark-calendar-suggestion.md)
|
||||
- [lark-calendar](../SKILL.md) — 日历完整 API
|
||||
@ -0,0 +1,42 @@
|
||||
# calendar +rsvp
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
回复指定的日程，更新当前用户的 RSVP 状态（接受、拒绝或待定）。
|
||||
|
||||
需要的scopes: ["calendar:calendar.event:reply"]
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 回复日程为接受 (使用主日历)
|
||||
lark-cli calendar +rsvp --event-id evt_xxx --rsvp-status accept
|
||||
|
||||
# 回复日程为拒绝
|
||||
lark-cli calendar +rsvp --event-id evt_xxx --rsvp-status decline
|
||||
|
||||
# 回复日程为待定
|
||||
lark-cli calendar +rsvp --event-id evt_xxx --rsvp-status tentative
|
||||
|
||||
# 指定其他日历下的日程
|
||||
lark-cli calendar +rsvp --calendar-id cal_xxx --event-id evt_xxx --rsvp-status accept
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--event-id <id>` | **是** | 日程 ID |
|
||||
| `--rsvp-status <status>` | **是** | 回复状态，可选值：`accept` (接受), `decline` (拒绝), `tentative` (待定) |
|
||||
| `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## 提示
|
||||
|
||||
- 只能回复你被邀请的日程。
|
||||
- 调用前通常需要通过 `+agenda` 等命令获取到具体的 `event-id`。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar](../SKILL.md) -- 日历全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,265 @@
|
||||
# 预约/改约日程或会议、查询/搜索可用会议室的工作流
|
||||
|
||||
## CRITICAL 执行摘要（先按这个骨架执行，再看下方细则）
|
||||
|
||||
- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。** 不要把“预约/查会议室”默认等同于“新建”。
|
||||
- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。** 用户一旦给出了既有日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（加人、删人、改时间、换会议室等），默认走编辑流。
|
||||
- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，避免把用户带入表单式问答。
|
||||
- **新建流先补默认值，编辑流先继承已定位日程信息。** 默认值包括标题、参会人、时长，以及在“完全无时间信息”时的默认时间范围；编辑流则优先复用已定位日程的标题、时间、已有参与人和会议室信息作为基线。
|
||||
- **只有三类场景才主动追问用户**：存在时间冲突、搜索结果无法唯一确定、时间语义本身有歧义。
|
||||
- **编辑流的时间基准必须明确。** 如果编辑时不改时间，则后续会议室搜索必须基于已定位日程的原始起止时间；如果既改时间又加会议室，必须先确定最终时间，再基于该时间搜索会议室。
|
||||
- **编辑流中“新增会议室”默认是增量语义。** 如果用户说的是“加会议室/再加一个会议室”，最终 `+update` 只做 `add`，默认保留已有会议室；只有在用户明确说“更换会议室/移除会议室”时，才执行旧会议室删除。
|
||||
- **明确时间**：若需要会议室，先 `+room-find`；再 `+freebusy` 判断参会人忙闲；有冲突时先说明冲突，再让用户决定继续当前时间还是改走 `+suggestion`。
|
||||
- **模糊时间或无时间信息**：先 `+suggestion` 产出候选时间块；若需要会议室，再把这些时间块批量交给 `+room-find`，将“候选时间 + 对应可用会议室”一次性展示给用户选择。
|
||||
- **BLOCKING REQUIREMENT: 只要面临时间方案（模糊时间/无时间）或会议室方案（需要会议室）的选择，必须先向用户展示选项并等待用户明确确认，绝对禁止在未获用户确认的情况下直接执行创建新日程或更新既有日程。**
|
||||
- **用户选中了 `+suggestion` 返回的候选时间块后，不要再次调用 `+freebusy`。** 用户确认后直接进入最终落地操作：创建新日程，或更新既有日程。
|
||||
- **当用户说“查会议室”“找会议室”“搜可用会议室”时，默认意图是查会议室可用性，不是检索会议室资源名录。**
|
||||
- **必须按顺序执行。** 不要跳过“任务类型判定”“目标日程定位（编辑流）”“补默认值/继承基线信息”“判断时间明确性”这些前置步骤。
|
||||
|
||||
> **💡 核心原则：做智能助理，充分利用默认值规则（如默认标题、时长、参与人等）自动补全信息。极力避免像“表单填写机”一样频繁打断并反问用户，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。**
|
||||
|
||||
## 严禁行为
|
||||
|
||||
- **严禁在未读取对应子命令文档（如 `lark-calendar-room-find.md`、`lark-calendar-suggestion.md`）的情况下直接调用命令！** 必须先阅读文档掌握最新参数要求与规范。
|
||||
- **严禁在尚未判断“新建”还是“编辑”之前，就直接进入创建日程或查会议室动作。**
|
||||
- **严禁把“给明天上午的‘产品发布会’加人/加群/加会议室”这类带有既有日程锚点 + 修改动词的请求，当成新建日程。** 这类请求必须先定位目标日程。
|
||||
- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一的 `event_id` 前，不得调用 `+update`、也不得基于猜测时间去查会议室。
|
||||
- **严禁在用户仅要求“查会议室”但未提供明确时间时，直接调用 `+room-find`！** 必须先默认一个合理时间范围，调用 `+suggestion` 拿到候选时间块，再将时间块传给 `+room-find`。
|
||||
- **不要在用户完全没给时间时，直接反问“你想约什么时候”。** 先补一个合理时间范围，再进入 `+suggestion`。
|
||||
- **不要在“需要会议室 + 时间模糊”的场景下，先让用户只选时间。** 应先批量查出每个候选时间对应的可用会议室，再让用户一次性完成选择。
|
||||
- **不要在用户已经选中 `+suggestion` 候选时间后，再重复调用 `+freebusy`。**
|
||||
- **不要在用户未明确说出城市时，仅凭园区/办公室名自动补城市。**
|
||||
- **严禁在面临时间方案或会议室方案的选择时（模糊时间、无时间或需要会议室），未经用户确认就擅自创建新日程或更新既有日程。**
|
||||
|
||||
## 适用场景
|
||||
|
||||
- “帮我约个会”
|
||||
- “下周找时间和 XX 开会”
|
||||
- “帮我订个会议室”
|
||||
- “帮我找/搜索一个可用的会议室”
|
||||
- “帮我推荐一个我以前常用的会议室”
|
||||
- “查询明天下午可用的会议室”
|
||||
- “明天下午3点约个日程/日历”
|
||||
- “把明天上午的日程‘产品发布会’加上 小明
|
||||
- “给下周一的周会换个会议室”
|
||||
- “把这个日程改到明天下午，并加上学清 F201”
|
||||
|
||||
## 核心概念
|
||||
|
||||
- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。**
|
||||
- **预定或查找会议室，均需先确定时间块。** 在推荐可用会议室后，应顺势引导用户完成最终的**日程落地**操作：创建新日程，或更新既有日程。
|
||||
|
||||
## CRITICAL 约束
|
||||
|
||||
- **在调用任何具体的 CLI 子命令（如 `+room-find`、`+suggestion`、`+freebusy`、`+create`）前，必须先读取其对应的 Markdown 文档。** 禁止仅凭记忆组装命令参数，以确保符合各命令最新的业务约束和格式规范。
|
||||
- **当用户说“查会议室”“找会议室”“搜可用会议室”等，默认意图是查询会议室可用性，而不是检索会议室资源名录。**
|
||||
- **必须严格按照下方【工作流】的步骤顺序完成任务。特别是单独查会议室时，若无明确时间，强制先走“模糊时间/无时间信息”分支调用 `+suggestion`。**
|
||||
|
||||
## 任务类型判定
|
||||
|
||||
| 类型 | 典型语言信号 | 第一动作 |
|
||||
|------|--------------|----------|
|
||||
| 新建日程 | “约个会”“安排一个会议”“新建日程”“帮我订个会议室开会” | 补默认值，再进入时间判断 |
|
||||
| 编辑已有日程 | “给某个日程加人/删人/加群/加会议室”“把某个日程改到…”“给这场会换个会议室” | 先定位目标日程 `event_id`，再进入后续流程 |
|
||||
|
||||
进一步规则：
|
||||
|
||||
- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`、某次实例）和**修改动词**（添加、移除、调整、改到、换、延后、提前），默认判定为**编辑已有日程**。
|
||||
- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`，不能直接拿原重复日程的 `event_id` 做更新。
|
||||
|
||||
## 工作流
|
||||
|
||||
### 1. 编辑已有日程：先定位目标日程
|
||||
|
||||
一旦判定为编辑流，必须先定位目标日程；没有 `event_id` 就不能继续后续修改动作。
|
||||
|
||||
定位规则：
|
||||
|
||||
- 优先利用用户给出的标题、日期、时间范围、`这个日程/这场会` 等锚点，通过 `+agenda`、`events search_event` 或实例视图缩小范围。
|
||||
- 如果命中多个候选日程，必须向用户展示候选项并要求确认，禁止自行猜测。
|
||||
- 如果是重复性日程的某一次实例，必须继续定位到该次实例的 `event_id`。
|
||||
|
||||
编辑流分支规则：
|
||||
|
||||
- **仅增删普通参会人/群组，不改时间，也不涉及会议室**：定位完成后可直接进入最终 `+update`。
|
||||
- **新增会议室，但不改时间**：必须基于已定位日程的当前 `start/end` 作为时间块执行 `+room-find`，不能因为用户没重复说时间就退回“无时间信息”。
|
||||
- **既改时间，又新增会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；最终只增量添加新会议室，不自动删除已有会议室。
|
||||
- **既改时间，又更换会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；只有在用户明确表达“更换”时，最终才执行“移除旧会议室 + 添加新会议室”。
|
||||
- **只改时间，不涉及会议室**：沿用下方时间工作流，但最终落地必须是 `+update`，不是 `+create`。
|
||||
|
||||
### 2. 新建日程：智能推断默认值
|
||||
以下信息智能推断，减少频繁询问用户：
|
||||
|
||||
- **标题**：根据上下文自动生成，例如“沟通对齐”“需求讨论”；如无法推断，默认为“会议”
|
||||
- **参会人**：如未明确指定其他人，默认参会人仅为**用户自己**
|
||||
- **时长**：基于会议类型和上下文动态推断；如无法推断，默认为 30 分钟
|
||||
- **无任何时间信息**：默认推断一个合理区间（如“今天”或“近两天”），并进入时间推荐流程，禁止询问用户
|
||||
|
||||
当搜索特定参与人（人、群）出现多个结果无法唯一确定时，必须询问用户进行选择确认，并将该偏好记录为长期记忆，以便后续自动识别。
|
||||
|
||||
### 3. 判断时间是否明确
|
||||
|
||||
这一步判断的是**最终要落地的目标时间**，不是只看用户原句里有没有重复说时间。
|
||||
|
||||
时间基准规则：
|
||||
|
||||
- **新建流**：使用用户给出的时间，或默认补全出的时间范围作为时间基准。
|
||||
- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是时间基准。后续如需查会议室，直接使用这个明确时间块。
|
||||
- **编辑流且改时间**：用户想改到的新时间才是时间基准；若表达模糊，则进入 `+suggestion`。
|
||||
|
||||
分两类处理：
|
||||
|
||||
- **明确时间**：如“明天下午3点”
|
||||
- **模糊时间**：如“明天下午”“下周找个时间”
|
||||
|
||||
### 4. 明确时间
|
||||
|
||||
明确时间时，需先判断是否需要会议室，如果需要，提前查询会议室；然后判断是否有时间冲突。这里的“明确时间”既可以来自用户直接表达，也可以来自已定位日程的原始时间。
|
||||
详见 [`+room-find`](./lark-calendar-room-find.md) 与 [`+freebusy`](./lark-calendar-freebusy.md)。
|
||||
|
||||
```bash
|
||||
# 1. 如果需要会议室，提前查询会议室
|
||||
lark-cli calendar +room-find \
|
||||
--slot "<start>~<end>" \
|
||||
--attendee-ids "<ids>" \
|
||||
--city "<city>" \
|
||||
--building "<building>" \
|
||||
--floor "<F2>" \
|
||||
--room-name "<room_name>"
|
||||
|
||||
# 2. 查询当前用户及其他参会人忙闲
|
||||
# （如果有多名参会人，需分别调用查询：--user-id "<ou_xxx>"）
|
||||
lark-cli calendar +freebusy --start "<start>" --end "<end>"
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- **参会人过多或包含群组时的处理**：
|
||||
- 如果参与人过多（例如超过 5 人），为避免高耗时，仅需查询**当前用户（自己）**及少数核心人员的忙闲状态即可。
|
||||
- 如果参与人中包含**群组**，无需展开群组成员查询其忙闲状态。
|
||||
- **编辑已有日程且不改时间，只新增会议室时**：这里的 `--slot` 必须来自已定位日程的当前 `start/end`。
|
||||
- **编辑已有日程且既改时间又加会议室时**：这里的 `--slot` 必须来自候选新时间，而不是旧时间；如果用户是“新增会议室”，后续落地只做添加，不删除旧会议室。
|
||||
- **如果没有冲突**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
|
||||
- **如果有冲突**：必须先说明冲突情况，询问用户继续选择这个时间还是换个时间
|
||||
- **如果说换个时间**：放弃当前时间，转入【模糊时间】流程，调用 `+suggestion` 推荐多个可用时间块
|
||||
- **如果继续选择这个时间**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
|
||||
- 位置信息要优先拆到结构化字段：用户明确说了城市才提取 `--city`；`--building` 不要再重复携带城市前缀。
|
||||
- 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。像 `2L`、`2F` 这类更像楼层或区域定位的短词，优先视为 `--floor`，不要默认当作 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
|
||||
- 会议室名要做轻量归一化：`木星会议室` -> `--room-name "木星"`；`会议室 02` / `02会议室` -> `--room-name "02"`。
|
||||
- 对 `F3-05` / `F5-07` / `3楼-08` 这类复合表达，若能稳定识别楼层与会议室号，应优先提取为 `--floor + --room-name`，不要把整段直接退化成 `--room-name`。
|
||||
|
||||
### 5. 模糊时间或无时间信息
|
||||
|
||||
先调用：
|
||||
详见 [`+suggestion`](./lark-calendar-suggestion.md)；若需要会议室，再结合 [`+room-find`](./lark-calendar-room-find.md)。
|
||||
|
||||
```bash
|
||||
lark-cli calendar +suggestion \
|
||||
--start "<range_start>" \
|
||||
--end "<range_end>" \
|
||||
--attendee-ids "<ids>" \
|
||||
--duration-minutes <n> \
|
||||
--event-rrule "<rrule>"
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- 若用户完全没有提供时间信息，应先默认一个合理区间后再调用 `+suggestion`
|
||||
- 编辑流中，若用户表达的是“改到明天下午”“下周找个时间再约”这类模糊新时间，则基于用户期望的新时间范围调用 `+suggestion`；不要继续沿用旧时间。
|
||||
- **不需要会议室**：获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入最终落地操作：创建新日程，或更新既有日程。
|
||||
- **需要会议室**：获取多个候选时间块后，**不要急于让用户选时间**。先将这些时间块一次性交给 `calendar +room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化分行展示，让用户一次性完成选择。（**注意：即使用户最初只说“查会议室”，且未带时间，也必须强制走到这一步，先 suggestion 再 room-find**）。
|
||||
- 用户一旦选择了 `+suggestion` 返回的时间块，**无需再次调用 `+freebusy`**
|
||||
|
||||
### 6. 模糊语义消解与长期记忆构建
|
||||
|
||||
针对用户专属的时间表达习惯或存在歧义的时间场景，严禁主观臆断。典型例子包括：
|
||||
|
||||
- “上班后”
|
||||
- “下班前”
|
||||
- 未明确上下午的 12 小时制时间表达
|
||||
|
||||
处理规则：
|
||||
|
||||
- 应主动澄清真实意图，而不是自行猜测
|
||||
- 当用户给出澄清后，应将这类个性化定义沉淀为长期偏好，推动后续直接理解类似表达
|
||||
|
||||
### 7. 重复性日程
|
||||
|
||||
若当前会议为重复性日程，调用 `+room-find` 时需携带 `--event-rrule`。
|
||||
|
||||
必须检查返回中的：
|
||||
|
||||
- `reserve_until_time`
|
||||
|
||||
若候选会议室的可预约上限早于重复规则覆盖范围，**不要直接按原规则落地日程**。应：
|
||||
|
||||
- 向用户明确说明该会议室最长可约至何时。
|
||||
- 若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。
|
||||
|
||||
### 8. 落地日程变更
|
||||
|
||||
用户确认后调用：
|
||||
如果是新建会议，详见 [`+create`](./lark-calendar-create.md)。
|
||||
如果是更新既有日程，详见 [`+update`](./lark-calendar-update.md)。必须先定位目标 `event_id`，再按用户意图用 `+update` 独立执行字段更新、添加参会人/会议室、移除参会人/会议室，或组合这些动作。若用户意图是“新增会议室”，默认仅追加 `room_id`，不移除已有会议室。
|
||||
|
||||
```bash
|
||||
lark-cli calendar +create \
|
||||
--summary "..." \
|
||||
--start "<start>" \
|
||||
--end "<end>" \
|
||||
--attendee-ids "ou_xxx,oc_xxx,omm_xxx"
|
||||
|
||||
lark-cli calendar +update \
|
||||
--event-id "<event_id>" \
|
||||
--start "<start>" \
|
||||
--end "<end>" \
|
||||
--add-attendee-ids "omm_new_room"
|
||||
|
||||
# 仅当用户明确要求“更换会议室”时，才同时移除旧会议室并添加新会议室
|
||||
lark-cli calendar +update \
|
||||
--event-id "<event_id>" \
|
||||
--remove-attendee-ids "omm_old_room" \
|
||||
--add-attendee-ids "omm_new_room"
|
||||
```
|
||||
|
||||
规则：
|
||||
- 新建日程时，可使用 `+create`
|
||||
- 更新既有日程时，优先使用 `+update`。改时间/标题/描述、添加参会人/会议室、移除参会人/会议室可以分别独立执行；
|
||||
- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新按标题猜测一次目标日程。
|
||||
- 编辑流中如果只是新增群组或普通参会人，不涉及时间和会议室，可直接 `+update --add-attendee-ids ...`。
|
||||
- 编辑流中如果是“新增会议室但不改时间”，必须先基于目标日程原始时间查到可用会议室，再 `+update --add-attendee-ids "<room_id>"`；默认保留已有会议室。
|
||||
- 编辑流中如果是“既改时间又新增会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间与新增会议室；默认保留已有会议室。
|
||||
- 编辑流中如果是“既改时间又更换会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间、移除旧会议室并添加新会议室。
|
||||
- 需要会议室时，将选中的 `room_id` 写入最终落地请求的参与人列表
|
||||
- 展示会议室候选时，必须保留 CLI/API 返回的完整 `room_name` 原值；允许附加“推断说明”，但禁止用摘要名、楼层及会议室号、容量/视频标签重组后的名称替换原值
|
||||
|
||||
## 用户展示建议
|
||||
|
||||
当向用户展示多个时间块及对应的多个会议室时，**必须使用结构化清晰的格式排版**。**严禁将时间与会议室名称放在同一行展示**，必须分行并使用编号列表呈现可用会议室，严禁将所有信息揉成一团纯文本堆叠。
|
||||
|
||||
**推荐展示格式参考：**
|
||||
|
||||
```text
|
||||
## 2026-03-27 周五
|
||||
|
||||
[选项 1] 14:00 - 15:00（参会人均空闲）
|
||||
可用会议室：
|
||||
1. 学清嘉创大厦B座-F2-02🎦(7人)
|
||||
2. 学清嘉创大厦B座-F2-05🎦(10人)
|
||||
|
||||
[选项 2] 16:00 - 17:00（参会人均空闲）
|
||||
可用会议室：
|
||||
1. 学清嘉创大厦B座-F3-01🎦(6人)
|
||||
2. 学清嘉创大厦B座-F3-06🎦(8人)
|
||||
|
||||
💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar-room-find.md](./lark-calendar-room-find.md)
|
||||
- [lark-calendar-freebusy.md](./lark-calendar-freebusy.md)
|
||||
- [lark-calendar-suggestion.md](./lark-calendar-suggestion.md)
|
||||
- [lark-calendar-create.md](./lark-calendar-create.md)
|
||||
- [lark-shared](../../lark-shared/SKILL.md)
|
||||
- [lark-calendar](../SKILL.md)
|
||||
@ -0,0 +1,125 @@
|
||||
# calendar +suggestion
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
|
||||
|
||||
根据非明确时间或一段时间范围，推荐多个可用时间块方案。帮助用户解决协调时间的难题。
|
||||
|
||||
**调用时机 (Agent Guidance):**
|
||||
- ✅ **当用户需求涉及寻找时间块，且时间未完全确定**（如`今天`、`近三天`、`本周`、`下午`, `无时间描述`）时，调用此工具来获取推荐时间块给用户选择（包括但不限于预约日程）。
|
||||
- ❌ **当用户已经明确了具体的时间点**（如`今天下午3点`），则**不需要**调用此工具
|
||||
|
||||
需要的scopes: ["calendar:calendar.free_busy:read"]
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 获取默认的时间推荐方案（搜索范围：当前时刻至当天结束）
|
||||
lark-cli calendar +suggestion
|
||||
|
||||
# 获取指定时间区间内的推荐方案（支持日期简写或完整 ISO 8601）
|
||||
lark-cli calendar +suggestion \
|
||||
--start "2026-03-19" \
|
||||
--end "2026-03-20"
|
||||
|
||||
# 结合参与人及会议时长获取推荐方案（时长单位：分钟）
|
||||
# --attendee-ids 支持传入用户（ou_ 前缀）和群组（oc_ 前缀）混合列表
|
||||
lark-cli calendar +suggestion \
|
||||
--start "2026-03-19T14:00:00+08:00" \
|
||||
--end "2026-03-19T18:00:00+08:00" \
|
||||
--attendee-ids ou_xxx,oc_yyy \
|
||||
--duration-minutes 60
|
||||
|
||||
# 排除特定时间段
|
||||
lark-cli calendar +suggestion \
|
||||
--start "2026-03-19T08:00:00+08:00" \
|
||||
--end "2026-03-19T18:00:00+08:00" \
|
||||
--exclude "2026-03-19T12:00:00+08:00~2026-03-19T13:00:00+08:00"
|
||||
|
||||
# JSON 格式输出
|
||||
lark-cli calendar +suggestion \
|
||||
--start "2026-03-19T08:00:00+08:00" \
|
||||
--end "2026-03-19T18:00:00+08:00" \
|
||||
--format json
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
| ------------------------------- | ----- | ------------------------------------------------------------------- |
|
||||
| `--start <time>` | 否 | 搜索区间开始时间（支持日期/ISO 8601等格式，默认**当前时间**） |
|
||||
| `--end <time>` | 否 | 搜索区间结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） |
|
||||
| `--attendee-ids <id_list>` | 否 | 目标参与人 ID 列表。提取对应实体的 ID。支持用户（`ou_` 前缀）和群组（`oc_` 前缀）。多个 ID 使用英文逗号分隔 |
|
||||
| `--event-rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" |
|
||||
| `--duration-minutes <min>` | 否 | 会议时长（分钟）。优先使用用户显式指定的值，若未指定则尝试根据上下文推断，推断失败则不传 |
|
||||
| `--timezone <tz>` | 否 | 对话中明确提及的预约日程所使用的时区（默认取用户设备时区，例如 `Asia/Shanghai`） |
|
||||
| `--exclude <times>` | 否 | 排除的时间块，支持 `start~end` 格式（如 `2026-03-19T12:00:00+08:00~2026-03-19T13:00:00+08:00`），多个用逗号分隔 |
|
||||
| `--format <flag>` | 否 | 输出格式（固定为 `json`） |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## 时间格式
|
||||
|
||||
`--start`、`--end` 以及 `--exclude` 支持以下格式自动解析：
|
||||
|
||||
| 格式 | 示例 | 说明 |
|
||||
| ------------- | --------------------------- | -------------------- |
|
||||
| ISO 8601 | `2026-03-19T08:40:29+08:00` | 完整格式，精确包含日期、时间及带冒号的时区偏移 |
|
||||
| 日期+时间 | `2026-03-19 08:40:29` | 自动补全时区 |
|
||||
| 仅日期 | `2026-03-19` | start 取 00:00:00，end 取 23:59:59 |
|
||||
| Unix 时间戳 | `1741564800` | 秒级时间戳 |
|
||||
|
||||
## 输出格式
|
||||
|
||||
**将推荐结果整理为易读的选项列表，并附上润色后的推荐理由：**
|
||||
|
||||
```text
|
||||
## 2026-03-19 周四
|
||||
|
||||
- **选项 1：10:00 - 10:30**
|
||||
推荐理由：所有参与者均空闲。
|
||||
|
||||
```
|
||||
> **AI 行为指导：**
|
||||
> - **结构化展示选项与理由**：以清晰的列表呈现推荐时间方案，并直接询问用户意向。**必须**结合“用户原始需求”与“推荐理由”说明每个时间块的优势，输出话术需简明、直接、无歧义。
|
||||
> - **如实反馈冲突情况**：注意，返回的推荐方案不一定都是完全空闲的（即使明确要求找空闲时间，系统在难以满足时也会返回包含忙闲冲突的方案）。判断推荐方案是否完全空闲，可以从推荐理由中是否表达了“完全空闲”或“没有任何忙闲冲突”来判断。如果推荐方案存在忙闲冲突，**必须**在展示方案时向用户如实说明冲突情况，绝不能误导用户认为是完全空闲。
|
||||
> - **主动提供优化建议**：当满足以下任一条件时（1. 返回结果包含 `ai_action_guidance` 字段内容；2. 用户要求找个空闲时间，但所有推荐方案都不是完全空闲的），你**必须**主动提供优化建议。若存在 `ai_action_guidance` 字段，需严格依据其核心意图生成引导话术；否则，请基于实际冲突情况主动提供合理的替代方案（如：建议调整时间范围、会议时长或参与人）。
|
||||
|
||||
## 典型场景
|
||||
|
||||
### 1. 查找多人的共同空闲会议时间
|
||||
|
||||
```bash
|
||||
# 指定两名参与人，并要求找一个 45 分钟的空闲时段
|
||||
lark-cli calendar +suggestion \
|
||||
--start "2026-03-19T08:00:00+08:00" \
|
||||
--end "2026-03-19T18:00:00+08:00" \
|
||||
--attendee-ids ou_member_a,ou_member_b \
|
||||
--duration-minutes 45
|
||||
```
|
||||
|
||||
### 2. 用户对当前推荐不满意，要求“换一批”
|
||||
|
||||
```bash
|
||||
# 将上一次推荐的时段作为排除条件传入
|
||||
lark-cli calendar +suggestion \
|
||||
--start "2026-03-19T08:00:00+08:00" \
|
||||
--end "2026-03-19T18:00:00+08:00" \
|
||||
--exclude "2026-03-19T10:00:00+08:00~2026-03-19T10:30:00+08:00"
|
||||
```
|
||||
|
||||
## 与其他命令对比
|
||||
|
||||
| 命令 | 用途 | 输出内容 |
|
||||
| ---------------------- | -------- | ------------------- |
|
||||
| `calendar +suggestion` | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 | 返回多个推荐时段及其理由，以及后续建议 |
|
||||
| `calendar +freebusy` | 查询忙闲时段 | 只返回忙碌时段列表和rsvp状态（无日程详情） |
|
||||
|
||||
**选择建议**：
|
||||
|
||||
- **寻找可用时间（含开会等场景）** → 优先使用 `+suggestion`，直接获取智能推荐方案
|
||||
- **了解个人当前忙碌情况** → 使用 `+freebusy`
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar-create](lark-calendar-create.md) — 创建日程
|
||||
- [lark-calendar-freebusy](lark-calendar-freebusy.md) — 查询忙闲时段和rsvp状态
|
||||
- [lark-calendar](../SKILL.md) — 日历完整 API
|
||||
105
.agents/skills/lark-calendar/references/lark-calendar-update.md
Normal file
105
.agents/skills/lark-calendar/references/lark-calendar-update.md
Normal file
@ -0,0 +1,105 @@
|
||||
# calendar +update
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
更新既有日程字段，或独立增量添加/移除参会人和会议室。
|
||||
|
||||
`+update` 支持三类互相独立的动作：更新日程字段、添加参会人/会议室、移除参会人/会议室。它们可以单独执行，也可以在同一次命令中组合执行。
|
||||
|
||||
需要的 scopes: ["calendar:calendar.event:update"]
|
||||
|
||||
## 推荐命令
|
||||
|
||||
```bash
|
||||
# 更新标题、描述、时间
|
||||
lark-cli calendar +update \
|
||||
--event-id "<EVENT_ID>" \
|
||||
--summary "产品评审" \
|
||||
--description "评审需求范围、排期与风险" \
|
||||
--start "2026-03-12T14:00+08:00" \
|
||||
--end "2026-03-12T15:00+08:00"
|
||||
|
||||
# 增量添加参会人和会议室
|
||||
lark-cli calendar +update \
|
||||
--event-id "<EVENT_ID>" \
|
||||
--add-attendee-ids "ou_aaa,ou_bbb,omm_room"
|
||||
|
||||
# 移除参会人和会议室
|
||||
lark-cli calendar +update \
|
||||
--event-id "<EVENT_ID>" \
|
||||
--remove-attendee-ids "ou_aaa,omm_room"
|
||||
|
||||
# 同时更新日程信息、移除旧会议室、添加新会议室
|
||||
lark-cli calendar +update \
|
||||
--event-id "<EVENT_ID>" \
|
||||
--summary "产品评审" \
|
||||
--start "2026-03-12T15:00+08:00" \
|
||||
--end "2026-03-12T16:00+08:00" \
|
||||
--remove-attendee-ids "omm_old_room" \
|
||||
--add-attendee-ids "omm_new_room"
|
||||
```
|
||||
|
||||
参数：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程要先定位到目标实例的 `event_id`，不要直接使用原重复日程 ID |
|
||||
| `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
|
||||
| `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
|
||||
| `--description <text>` | 否 | 新日程描述。目前 API 方式不支持编辑富文本描述；如果日程描述通过客户端编辑为富文本内容，则使用 API 更新描述会导致富文本格式丢失。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空 |
|
||||
| `--start <time>` | 否 | 新开始时间（ISO 8601，如 `2026-03-12T14:00+08:00`）。更新日程时间时必须同时传 `--end` |
|
||||
| `--end <time>` | 否 | 新结束时间（ISO 8601）。更新日程时间时必须同时传 `--start` |
|
||||
| `--rrule <rrule>` | 否 | 新重复规则（RFC5545）。**不要使用 COUNT；如需限制次数，推算后转为 UNTIL** |
|
||||
| `--add-attendee-ids <id_list>` | 否 | 增量添加参会人/会议室，逗号分隔。支持用户 `ou_`、群组 `oc_`、会议室 `omm_` |
|
||||
| `--remove-attendee-ids <id_list>` | 否 | 增量移除参会人/会议室，逗号分隔。支持用户 `ou_`、群组 `oc_`、会议室 `omm_` |
|
||||
| `--notify` | 否 | 是否发送更新通知，默认 `true`。可用 `--notify=false` 静默更新 |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
至少需要提供一个动作：`--summary`、`--description`、`--start/--end`、`--rrule`、`--add-attendee-ids` 或 `--remove-attendee-ids`。
|
||||
|
||||
## 使用规则
|
||||
|
||||
- `--add-attendee-ids` 是**增量添加**，不是替换最终参与人列表。不要用它表达“只保留这些人”。
|
||||
- 对 `--summary`、`--description`，CLI 以“是否显式传入该 flag”判断是否更新，而不是以“值是否为空”判断；如果显式传入空字符串，会把对应字段清空。
|
||||
- 只想增删参会人或会议室时，不需要同时传 `--summary`、`--start`、`--end` 等日程字段。
|
||||
- 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
|
||||
- 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
|
||||
- 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
|
||||
- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`events search_event` 或实例视图定位该实例的 `event_id`。
|
||||
- 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
|
||||
- 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
|
||||
|
||||
## 高级用法（完整 API 命令）
|
||||
|
||||
`+update` 只覆盖标题、描述、时间、重复规则，以及参会人/会议室的增量添加或移除。
|
||||
|
||||
如需更新 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、`color`（颜色）、附件、视频会议信息、全天日程，或在新增参会人时配置可选参加状态 等高级参数，请改用完整的 API 命令。建议先通过 `lark-cli schema calendar.events.patch`、`lark-cli schema calendar.event.attendees.create`、`lark-cli schema calendar.event.attendees.batch_delete` 查看完整参数定义。
|
||||
|
||||
> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
|
||||
|
||||
## 预约/改约会议室场景
|
||||
|
||||
如果用户要“改会议时间”“换会议室”“给现有日程加会议室”，必须先阅读 [`lark-calendar-schedule-meeting.md`](lark-calendar-schedule-meeting.md) 并按其中工作流处理：
|
||||
|
||||
- 明确时间且需要会议室：先 `+room-find`，再按需 `+freebusy`，用户确认后再 `+update`。
|
||||
- 模糊时间或无时间：先 `+suggestion`，如需会议室再批量 `+room-find`，用户确认后再 `+update`。
|
||||
- 面临时间方案或会议室方案选择时，必须先展示候选方案并等待用户确认。
|
||||
|
||||
## 参会人类型
|
||||
|
||||
| 前缀 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `ou_` | user | 飞书用户 open_id |
|
||||
| `oc_` | chat | 飞书群组 |
|
||||
| `omm_` | resource | 会议室 |
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作**。执行前必须确认用户意图，特别是移除参会人/会议室或移动会议时间。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-calendar](../SKILL.md) -- 日历全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
- [lark-calendar-schedule-meeting](lark-calendar-schedule-meeting.md) -- 预约/改约会议与会议室工作流
|
||||
- [lark-calendar-room-find](lark-calendar-room-find.md) -- 查找可用会议室
|
||||
- [lark-calendar-freebusy](lark-calendar-freebusy.md) -- 查询忙闲
|
||||
59
.agents/skills/lark-contact/SKILL.md
Normal file
59
.agents/skills/lark-contact/SKILL.md
Normal file
@ -0,0 +1,59 @@
|
||||
---
|
||||
name: lark-contact
|
||||
version: 1.0.0
|
||||
description: "飞书 / Lark 通讯录:按姓名 / 邮箱解析成 open_id,或按 open_id 反查姓名 / 部门 / 邮箱 / 联系方式 / 个人状态 / 签名。当用户提到某人姓名要下一步发消息 / 排日程,或拿到 open_id 想查具体信息时使用。不负责部门树遍历、按部门列员工、组织架构图,这类需求走原生 OpenAPI。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli contact --help"
|
||||
---
|
||||
|
||||
# contact (v2)
|
||||
|
||||
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
|
||||
|
||||
## 选哪个命令
|
||||
|
||||
**user 身份和 bot 身份是两条完全独立的路径**。先确定当前身份,再按下表选命令:
|
||||
|
||||
| 想做什么 | user 身份 | bot 身份 |
|
||||
|---|---|---|
|
||||
| 按姓名 / 邮箱搜员工拿 open_id | [`+search-user`](references/lark-contact-search-user.md) | 不支持 |
|
||||
| 已知 open_id 取他人资料 | `+search-user --user-ids <id>` | [`+get-user --user-id <id>`](references/lark-contact-get-user.md) |
|
||||
| 查看自己 | `+get-user` 或 `+search-user --user-ids me` | 不支持 |
|
||||
| 查同事的个人状态 / 签名 | `user_profiles batch_query` | 不支持 |
|
||||
|
||||
已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 [`lark-im`](../lark-im/SKILL.md) / [`lark-calendar`](../lark-calendar/SKILL.md)。
|
||||
|
||||
## 典型场景
|
||||
|
||||
找张三给他发消息:先搜,确认 open_id,再发:
|
||||
|
||||
```bash
|
||||
lark-cli contact +search-user --query "张三" --has-chatted --as user
|
||||
lark-cli im +messages-send --user-id ou_xxx --text "Hi!"
|
||||
```
|
||||
|
||||
批量查同事的个人状态 / 个性签名(先用 schema 看参数)。
|
||||
|
||||
```bash
|
||||
lark-cli schema contact.user_profiles.batch_query
|
||||
lark-cli contact user_profiles batch_query \
|
||||
--params '{"user_id_type":"open_id"}' \
|
||||
--data '{"user_ids":["ou_xxx","ou_yyy"],"query_option":{"include_personal_status":true,"include_description":true}}' \
|
||||
--as user
|
||||
```
|
||||
|
||||
搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **41050 / Permission denied** 受当前身份的可见范围限制(两条命令都可能遇到)。换 bot 身份或让管理员调整可见范围,细节见 [`lark-shared`](../lark-shared/SKILL.md)。
|
||||
- **跨租户用户**(`is_cross_tenant=true`)多数业务字段为空字符串,这是飞书可见性规则,下游做空值兜底。
|
||||
- **ID 类型**:默认 `open_id`。`+get-user` 可改 `--user-id-type union_id|user_id`;`+search-user` 只接受 `open_id`。
|
||||
|
||||
## 不在本 skill 范围
|
||||
|
||||
- 发消息 / 查聊天记录 → [`lark-im`](../lark-im/SKILL.md)
|
||||
- 排日程 / 邀请会议 → [`lark-calendar`](../lark-calendar/SKILL.md)
|
||||
- 部门树 / 按部门列员工 / 组织架构 → [`lark-openapi-explorer`](../lark-openapi-explorer/SKILL.md) 查找原生接口
|
||||
@ -0,0 +1,19 @@
|
||||
# +get-user
|
||||
|
||||
按 ID 取用户基本信息(姓名等)。
|
||||
|
||||
```bash
|
||||
# 取自己
|
||||
lark-cli contact +get-user --as user
|
||||
|
||||
# bot 按 ID 取他人
|
||||
lark-cli contact +get-user --user-id ou_xxx --as bot
|
||||
|
||||
# 按 union_id / user_id 取(默认 open_id)
|
||||
lark-cli contact +get-user --user-id <id> --user-id-type union_id --as bot
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **user 身份按 ID 取他人请用 `+search-user --user-ids <id>`**,字段比本命令多(部门 / 邮箱 / 是否激活等)。本命令的 user 模式只回很少字段。
|
||||
- **`--as bot` 必须传 `--user-id`**:不传会直接报错(只有 user 身份能省略 `--user-id` 取自己)。
|
||||
@ -0,0 +1,124 @@
|
||||
# +search-user
|
||||
|
||||
仅 user 身份。需要 scope `contact:user:search`。
|
||||
|
||||
## 适用范围
|
||||
|
||||
- ✅ 已知姓名 / 邮箱 / 「聊过的人」想找出 open_id
|
||||
- ✅ 已知一组 open_id 想批量校验或回填字段(`--user-ids`,最多 100,支持 `me`)
|
||||
- ✅ 按聊天关系 / 在职状态 / 租户边界 / 企业邮箱等维度筛选员工
|
||||
- ❌ 已知 open_id 想拿完整 profile → 用 `+get-user --as bot`
|
||||
- ❌ 已知 open_id 想发消息 → 直接走 `lark-im`,不经过本命令
|
||||
|
||||
## 关键 flag
|
||||
|
||||
`--query` / `--queries` / `--user-ids` / bool filter 至少传一个。bool filter 显式传 `=false` 会报错——不传等于不过滤。
|
||||
|
||||
| Flag | 作用 |
|
||||
|---|---|
|
||||
| `--query <text>` | 关键词(姓名 / 邮箱 / 手机号),≤ 50 rune |
|
||||
| `--queries <csv>` | 多个关键词并行搜,**最多 20 条**;与 `--query` / `--user-ids` 互斥;输出新 shape(见下) |
|
||||
| `--user-ids <csv>` | open_id 列表,≤ 100;支持 `me` 表示自己;与 `--query` 同传时把搜索范围限定在该集合 |
|
||||
| `--has-chatted` | 仅搜聊过天的 |
|
||||
| `--has-enterprise-email` | 仅搜有企业邮箱的 |
|
||||
| `--exclude-external-users` | 仅搜同租户(排除外部联系人) |
|
||||
| `--left-organization` | 仅搜已离职的 |
|
||||
| `--lang <locale>` | 覆盖 `localized_name` 的语种(如 `zh_cn` / `en_us` / `ja_jp`) |
|
||||
| `--page-size <n>` | 单页大小 1-30,默认 20 |
|
||||
|
||||
## 常用例子
|
||||
|
||||
```bash
|
||||
# 按姓名搜,看候选确认是哪个张三
|
||||
lark-cli contact +search-user --query "张三" --has-chatted
|
||||
|
||||
# 按完整邮箱搜(命中通常唯一,适合作后续命令的输入)
|
||||
lark-cli contact +search-user --query "alice@example.com"
|
||||
|
||||
# 查看自己
|
||||
lark-cli contact +search-user --user-ids me
|
||||
|
||||
# 批量回填:已知一组 open_id,取姓名 / 邮箱 / 部门
|
||||
lark-cli contact +search-user --user-ids "ou_a,ou_b,ou_c" --format json
|
||||
|
||||
# 多 filter 组合:同租户的、有企业邮箱的「王」姓员工
|
||||
lark-cli contact +search-user --query "王" --exclude-external-users --has-enterprise-email
|
||||
|
||||
# filter-only 枚举:列出所有"聊过天的离职同事"(无关键词)
|
||||
lark-cli contact +search-user --has-chatted --left-organization
|
||||
```
|
||||
|
||||
## 批量并行查询 (fanout)
|
||||
|
||||
一次查多个名字:
|
||||
|
||||
```bash
|
||||
lark-cli contact +search-user --queries "Alice,Bob,张三"
|
||||
```
|
||||
|
||||
- 每行 user 带 `matched_query`,标识来自哪个 query
|
||||
- `queries[]` 每个输入一条 `{query, error?, has_more}`,失败的有 `error`
|
||||
- 部分失败不影响其它 query;全部失败才 exit 非 0
|
||||
|
||||
```bash
|
||||
# bool filter 对每个 query 都生效
|
||||
lark-cli contact +search-user --queries "Alice,Bob" --has-chatted
|
||||
|
||||
# 与 --query / --user-ids 互斥
|
||||
lark-cli contact +search-user --queries "a" --query "b" # ❌ exit 2
|
||||
```
|
||||
|
||||
约束:
|
||||
- 最多 20 条; 每条 ≤ 50 字符
|
||||
- 重复条目静默去重;全空 csv (`,,,`) 报错
|
||||
|
||||
## 同名 disambiguation
|
||||
|
||||
搜常见姓名常返回多条同名结果。后续操作若有副作用(发消息、邀请会议等),把候选列给用户挑;**不要擅自选**。
|
||||
|
||||
筛选信号(可信度从高到低):`chat_recency_hint`(近期联系过) > `enterprise_email` 前缀 > `department` 关键词。`localized_name` 同名时无区分作用。
|
||||
|
||||
```bash
|
||||
# 用 jq 按部门精筛
|
||||
lark-cli contact +search-user --query "张三" \
|
||||
--jq '.data.users[] | select(.department | contains("<部门关键词>"))'
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- **不会自动翻页**。`has_more=true` 表示需要 refine query。
|
||||
- **`--lang` 只影响输出展示名**,不影响匹配字段。
|
||||
- **`--query` 与 `--user-ids` 同时设**:`--user-ids` 限定搜索范围,`--query` 在该集合内匹配。
|
||||
|
||||
## 输出字段 contract
|
||||
|
||||
跨租户用户(`is_cross_tenant=true`)的业务字段可能为空字符串,需做空值兜底。
|
||||
|
||||
| 字段 | 类型 | 说明 | 跨租户 |
|
||||
|---|---|---|---|
|
||||
| `open_id` | string | 稳定标识,后续命令的输入 | 始终非空 |
|
||||
| `localized_name` | string | 按 `--lang` / brand 选出的展示名 | 始终非空(兜底为 open_id) |
|
||||
| `email` | string | 个人邮箱 | 可能为空 |
|
||||
| `enterprise_email` | string | 企业邮箱 | 可能为空 |
|
||||
| `is_activated` | bool | 是否已激活飞书账号(未激活也可投递消息,但用户可能看不到) | 可能 false |
|
||||
| `is_cross_tenant` | bool | 是否跨租户用户(同公司=false,外部联系人=true) | — |
|
||||
| `p2p_chat_id` | string | 与当前用户的 P2P 会话 ID(`oc_...`);空表示从未私聊过。可作为接受 `--chat-id` 的 IM 命令的输入 | 可能为空 |
|
||||
| `has_chatted` | bool | `p2p_chat_id != ""` 的派生字段 | — |
|
||||
| `department` | string | 部门路径,服务端可能用 `-` 拼层级,层级数不固定。**按可子串匹配的字符串处理** | 可能为空 |
|
||||
| `signature` | string (optional) | 用户个性签名;空时字段不出现 | 可能不出现 |
|
||||
| `chat_recency_hint` | string | 最近联系的提示文案,仅供展示 | 可能为空 |
|
||||
| `match_segments` | string[] | 关键词命中的字符串片段,用于高亮展示;无命中则为空数组 | — |
|
||||
|
||||
### `--queries` 模式额外字段
|
||||
|
||||
`data.users[]` 每条多 `matched_query` (string),指明本行来自哪个 query。
|
||||
|
||||
`data.queries[]` 按输入顺序、dedup 后每个 query 一条:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `query` | string | 该输入 |
|
||||
| `error` | string (optional) | 失败原因;成功时不出现 |
|
||||
| `has_more` | bool | 该 query 还有更多结果 |
|
||||
|
||||
fanout 模式无顶层 `data.has_more`。
|
||||
80
.agents/skills/lark-doc/SKILL.md
Normal file
80
.agents/skills/lark-doc/SKILL.md
Normal file
@ -0,0 +1,80 @@
|
||||
---
|
||||
name: lark-doc
|
||||
version: 2.0.0
|
||||
description: "飞书云文档（Docx / Wiki 文档，v2 API）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli docs --api-version v2 --help; lark-cli docs +create --api-version v2 --help; lark-cli docs +fetch --api-version v2 --help; lark-cli docs +update --api-version v2 --help"
|
||||
---
|
||||
|
||||
# docs (v2)
|
||||
|
||||
**身份：文档操作默认使用 `--as user`。首次使用前执行 `lark-cli auth login`。**
|
||||
|
||||
> **CRITICAL — API 版本：本 skill 使用 v2 API。执行 `docs +create`、`docs +fetch`、`docs +update` 时必须显式传入 `--api-version v2`。**
|
||||
|
||||
```bash
|
||||
# 常用示例
|
||||
lark-cli docs +fetch --api-version v2 --doc "文档URL或token"
|
||||
lark-cli docs +create --api-version v2 --content '<title>标题</title><p>内容</p>'
|
||||
lark-cli docs +update --api-version v2 --doc "文档URL或token" --command append --content '<p>内容</p>'
|
||||
```
|
||||
|
||||
## 前置条件 — 执行操作前必读
|
||||
|
||||
**CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
|
||||
1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
|
||||
2. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
|
||||
3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
|
||||
|
||||
**未读完以上文件就执行相应操作会导致参数选择错误、格式错误或样式不达标。**
|
||||
|
||||
> **格式选择规则（全局）：**
|
||||
> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
|
||||
> - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
|
||||
|
||||
## 快速决策
|
||||
- 用户需要“某个 block 的直达链接 / 锚点链接”时：返回 `文档基础 URL#block_id`。如果当前只有文档 URL 没有 block_id，先用 `docs +fetch --detail with-ids` 拿到目标 block 的 id
|
||||
- 例：
|
||||
- 已知文档 URL = `https://xxx.feishu.cn/docx/doxcn123`
|
||||
- 已知 block_id = `blkcn456`
|
||||
- 应返回 `https://xxx.feishu.cn/docx/doxcn123#blkcn456`
|
||||
- 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
|
||||
- 写文档时，重要信息（核心流程、架构、对比、风险、路线图、关键指标、因果关系）优先规划为画板，不要只用文字或表格承载
|
||||
- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
|
||||
- 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
|
||||
- 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
|
||||
- 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
|
||||
- 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
|
||||
- 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到 `lark-drive` 处理
|
||||
- 文档内容中出现嵌入的 `<sheet>`、`<bitable>` 或 `<cite file-type="sheets|bitable">` 标签时 → **必须主动提取 token 并切到对应技能下钻读取内部数据**，不能只呈现标签本身
|
||||
|
||||
| 标签 / 属性 | 提取字段 | 切到技能 |
|
||||
|-|-|-|
|
||||
| `<sheet token="..." sheet-id="...">` | `token` -> spreadsheet_token, `sheet-id` | [`lark-sheets`](../lark-sheets/SKILL.md) |
|
||||
| `<bitable token="..." table-id="...">` | `token` -> app_token, `table-id` | [`lark-base`](../lark-base/SKILL.md) |
|
||||
| `<cite type="doc" file-type="sheets" token="..." sheet-id="...">` | 同 `<sheet>` | [`lark-sheets`](../lark-sheets/SKILL.md) |
|
||||
| `<cite type="doc" file-type="bitable" token="..." table-id="...">` | 同 `<bitable>` | [`lark-base`](../lark-base/SKILL.md) |
|
||||
| `<vc-transcribe-tab vc-node-id="...">` | `vc-node-id` -> note_id | [`lark-note`](../lark-note/SKILL.md)：先 `note +detail --note-id <vc-node-id>` |
|
||||
| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch --api-version v2` 读取 src-token 文档，定位 block |
|
||||
|
||||
## Shortcuts（推荐优先使用）
|
||||
|
||||
Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
|
||||
| [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown) |
|
||||
| [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
|
||||
| [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer `--from-clipboard` when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use `--file` only for on-disk sources. |
|
||||
| [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
|
||||
| [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |
|
||||
| [`+whiteboard-update`](../lark-whiteboard/references/lark-whiteboard-update.md) | Alias of `whiteboard +update`. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer `whiteboard +update`; refer to lark-whiteboard skill for details. |
|
||||
|
||||
## 不在本 Skill 范围
|
||||
|
||||
- 文档评论管理 → [`lark-drive`](../lark-drive/SKILL.md)
|
||||
- 电子表格或 Base 的数据操作 → [`lark-sheets`](../lark-sheets/SKILL.md) / [`lark-base`](../lark-base/SKILL.md)
|
||||
- 云空间文件上传、下载、权限管理 → [`lark-drive`](../lark-drive/SKILL.md)
|
||||
86
.agents/skills/lark-doc/references/lark-doc-create.md
Normal file
86
.agents/skills/lark-doc/references/lark-doc-create.md
Normal file
@ -0,0 +1,86 @@
|
||||
# docs +create（创建飞书云文档）
|
||||
|
||||
> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
|
||||
> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
|
||||
> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
|
||||
> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
|
||||
>
|
||||
> **未读完以上文件就生成内容会导致格式错误或样式不达标。**
|
||||
|
||||
从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
|
||||
|
||||
> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 创建 XML 文档（默认格式，推荐）
|
||||
lark-cli docs +create --api-version v2 --content '<title>项目计划</title><h1>目标</h1><ul><li>目标 1</li><li>目标 2</li></ul>'
|
||||
|
||||
# 创建到指定文件夹（XML）
|
||||
lark-cli docs +create --api-version v2 --parent-token fldcnXXXX --content '<title>标题</title><p>首段内容</p>'
|
||||
|
||||
# 创建到个人知识库（XML）
|
||||
lark-cli docs +create --api-version v2 --parent-position my_library --content '<title>标题</title><p>内容</p>'
|
||||
|
||||
# 仅当用户明确要求时才使用 Markdown
|
||||
lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项目计划\n\n## 目标\n\n- 目标 1\n- 目标 2'
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "user",
|
||||
"data": {
|
||||
"document": {
|
||||
"document_id": "doxcnXXXXXXXXXXXXXXXXXXX",
|
||||
"revision_id": 1,
|
||||
"url": "https://xxx.feishu.cn/docx/doxcnXXXXXXXXXXXXXXXXXXX",
|
||||
"new_blocks": [
|
||||
{ "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **`document.new_blocks`**：本次操作新增的 block 列表（如画板）。`block_id` 可用于 `docs +update` 的 `--block-id` 做精确编辑；`block_token` 是资源块（如画板）的 token，可交给 `lark-whiteboard` 等 skill 继续操作
|
||||
|
||||
> \[!IMPORTANT]
|
||||
> 如果文档是**以应用身份（bot）创建**的，如 `lark-cli docs +create --as bot` 在文档创建成功后，CLI 会**尝试为当前 CLI 用户自动授予该文档的 `full_access`（可管理权限）**。
|
||||
>
|
||||
> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
|
||||
> - `status = granted`：当前 CLI 用户已获得该文档的可管理权限
|
||||
> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
|
||||
> - `status = failed`：文档已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档
|
||||
>
|
||||
> `permission_grant.perm = full_access` 表示该资源已授予”可管理权限”。
|
||||
>
|
||||
> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
| ------------------- | -- |---------------------------------------------|
|
||||
| `--api-version` | 是 | 固定传 `v2` |
|
||||
| `--content` | 是 | 文档内容（XML 或 Markdown 格式） |
|
||||
| `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
|
||||
| `--parent-token` | 否 | 父文件夹或知识库节点 token（与 `--parent-position` 互斥） |
|
||||
| `--parent-position` | 否 | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- 文档标题从内容中自动提取（XML `<title>` 或 Markdown `#`），不要在内容开头重复写标题
|
||||
- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
|
||||
- **视觉丰富度**：必须遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block 丰富文档
|
||||
|
||||
## 参考
|
||||
|
||||
- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
|
||||
- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
|
||||
- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
|
||||
- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
|
||||
- [`lark-doc-update.md`](lark-doc-update.md) — 更新文档
|
||||
- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
|
||||
137
.agents/skills/lark-doc/references/lark-doc-fetch.md
Normal file
137
.agents/skills/lark-doc/references/lark-doc-fetch.md
Normal file
@ -0,0 +1,137 @@
|
||||
|
||||
# docs +fetch（获取飞书云文档）
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 获取文档（默认 XML，simple）
|
||||
lark-cli docs +fetch --api-version v2 --doc "https://xxx.feishu.cn/docx/Z1Fj...tnAc"
|
||||
|
||||
# Markdown 格式
|
||||
lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --doc-format markdown
|
||||
|
||||
# 带 block ID（用于后续 block 级更新）
|
||||
lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --detail with-ids
|
||||
|
||||
# 只拿目录
|
||||
lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --scope outline --max-depth 3
|
||||
|
||||
# 按 block id 区间精读
|
||||
lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
|
||||
--scope range --start-block-id blkA --end-block-id blkB --detail with-ids
|
||||
|
||||
# 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）
|
||||
lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
|
||||
--scope section --start-block-id <标题id> --detail with-ids
|
||||
|
||||
# 按关键词定位（多关键词用 | 分隔，任一命中即返回）
|
||||
lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
|
||||
--scope keyword --keyword "部署|发布|上线"
|
||||
```
|
||||
|
||||
## 选 `--detail`（每块详细度）
|
||||
|
||||
| 意图 | `--detail` | 说明 |
|
||||
|------|-----------|------|
|
||||
| **只读**：浏览或总结文档内容 | `simple`（默认） | 简洁 XML/Markdown，不含 block ID、样式属性、引用元数据 |
|
||||
| **定位**：需要 block ID 与其他业务交互 | `with-ids` | 包含 block ID（如 `<p id="blkcnXXXX">`），可用于 `+update` 的 `--block-id`，也可用于拼接 `文档URL#block_id` 形式的直达链接 |
|
||||
| **编辑**：任何修改文档内容的需求 | `full` | 包含 block ID + 样式属性 + 引用元数据，提供完整文档结构信息 |
|
||||
|
||||
## 选 `--scope`（读取范围）
|
||||
|
||||
`--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。**
|
||||
|
||||
| 模式 | 何时用 | 关键参数 | 行为要点 |
|
||||
|-|-|-|-|
|
||||
| `outline` | 不知道结构，先看目录 | `--max-depth`（标题层级上限） | 扁平列出所有标题，**包括嵌在容器里的内嵌标题**（如 callout 里的 h3）；这些 id 可直接作后续 `section` / `range` 端点 |
|
||||
| `section` | 读某个标题对应的整节 | `--start-block-id`（必填） | 顶层标题 → 展开到下一同级/更高级标题前；容器内节点（含内嵌标题） → 按"最小包容单元"返回容器/表格切片，不做 heading 扩展；顶层非标题块 → 仅该块 |
|
||||
| `range` | 已知精确起止 | `--start-block-id` / `--end-block-id` 至少一个；`-1` = 读到末尾 | 两端同顶层 → 顶层序列切片；两端同一容器 → 容器整体；两端同一表格 → 瘦身切片；**跨顶层 → 端点所在顶层块整块输出，不做瘦身** |
|
||||
| `keyword` | 只有模糊关键词 | `--keyword`（**多级自动 fallback**：子串 → 归一化 → 分词形变 → RE2 正则；`\|` 分隔多分支 OR） | 每处命中按"最小包容单元"输出；**自动去重**（同容器多命中 → 单个容器，同表格多行命中 → 合并切片） |
|
||||
|
||||
> 💡 **多关键词用 `\|` 拼接（OR 语义，任一命中即返回）**：例 `"部署\|发布\|上线"`，三词任一命中都进结果，适合**同义词/别名/多业务术语**一次召回（如 `bug\|缺陷\|故障`）。
|
||||
|
||||
**设置 `--scope` 时共用** `--context-before` / `--context-after` / `--max-depth`。
|
||||
|
||||
- `--max-depth`：`outline` = 标题层级上限（3 = h1~h3）；其它模式 = 被选块的子树遍历深度（`-1` 不限，`0` 仅块自身）。
|
||||
- `--context-before/--context-after`：**只对整块顶层单元生效**；命中落在容器/表格内（返回容器或切片）时 before/after 被忽略，需要更大范围改用 `section` / `range` 显式指定。
|
||||
|
||||
**决策顺序**（核心原则：**局部获取优于全量获取**，根据需求形态选起点，必要时多步组合收敛范围）：
|
||||
1. 需求**直接给出待查的具体术语/错误码/标识** → 直接走 `keyword` 粗匹配（多级 fallback 自动覆盖形变），需要更大上下文时用返回的 `top-block-id` 走 `section` / `range`
|
||||
2. 需求**指向某个章节/标题**（"修改 XX 章"、"总结第 3 节"、"关于 xx 的内容"）→ 先 `outline --max-depth 3` 拿目录 → `section --start-block-id <标题id>` 精读
|
||||
3. 已知**精确起止 / 跨节连续区间** → `range`
|
||||
4. **结构未知且无明确关键词/章节线索** → `outline` 探测，再回到 2/3
|
||||
5. **兜底**：仅在确需整篇时才省略 `--scope`；不要为省事直接读整篇
|
||||
|
||||
## 局部读取的输出结构：`<fragment>` 与 `<excerpt>`
|
||||
|
||||
设置 `--scope` 时返回的 `content` 被一个 `<fragment>` 节点包裹，属性包含 `mode` / `requested-start` / `requested-end` / `keyword`（按需）。子节点只有两种形态：
|
||||
|
||||
- **顶层块**：完整块直接作为 `<fragment>` 的子节点，无额外包裹。
|
||||
- **`<excerpt top-block-id="..." parent-block-path="...">`**：非顶层节选（容器整体 / 表格瘦身切片）。
|
||||
- `top-block-id`：所在顶层块 id，想看该块全貌时作 `section` / `range` 锚点再拉一次。
|
||||
- `parent-block-path`：从顶层块到 excerpt 内容直接父节点的 id 路径，`/` 分隔（表格切片时即表格自身 id）。
|
||||
|
||||
**看到 `<excerpt>` 即意味着这是节选**，不能假设看到了该顶层块的全貌。
|
||||
|
||||
**表格默认瘦身**：即便 `<table>` 本身是顶层块也只返回 thead + 命中 tr。想拿整张表 → `range --start-block-id <table-id> --end-block-id <table-id>`；切片范围恰好覆盖全部 tr 时 SDK 自动升级为整块、不包 `<excerpt>`。
|
||||
|
||||
## 返回值
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "user",
|
||||
"data": {
|
||||
"document": {
|
||||
"document_id": "doxcnXXXX",
|
||||
"revision_id": 12,
|
||||
"content": "<title>标题</title><p>文档内容...</p>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`content` 的格式由 `--doc-format` 决定。设置 `--scope` 时会被 `<fragment>` 包裹，详见上文"局部读取的输出结构"。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--api-version` | 是 | 固定传 `v2` |
|
||||
| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |
|
||||
| `--doc-format` | 否 | `xml`（默认）\| `markdown` \| `text` |
|
||||
| `--detail` | 否 | `simple`（默认）\| `with-ids` \| `full` |
|
||||
| `--revision-id` | 否 | 文档版本号，`-1` = 最新（默认） |
|
||||
| `--scope` | 否 | `outline` \| `range` \| `keyword` \| `section`（省略 = 读整篇） |
|
||||
| `--start-block-id` | 否 | `range`/`section` 起始/锚点 id（`section` 必填） |
|
||||
| `--end-block-id` | 否 | `range` 结束 id；`-1` 表示读到末尾 |
|
||||
| `--keyword` | 否 | `keyword` 模式关键词，**4 层自动 fallback**（子串 → 归一化 → 分词形变 → RE2 正则）；`\|` 分隔多分支 OR |
|
||||
| `--context-before` | 否 | 命中前拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
|
||||
| `--context-after` | 否 | 命中后拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
|
||||
| `--max-depth` | 否 | `outline` = 标题层级上限；其它 = 子树深度（`-1` 不限，默认） |
|
||||
| `--format` | 否 | `json`（默认）\| `pretty` |
|
||||
|
||||
## 图片、文件、画板的处理
|
||||
|
||||
**文档中的素材以 XML 标签形式出现：**
|
||||
|
||||
```xml
|
||||
<img token="..." url="https://..." width="..." height="..."/>
|
||||
<source token="..." url="https://..." name="skills.zip"/>
|
||||
<whiteboard token="..."/>
|
||||
```
|
||||
|
||||
- `<img>` / `<source>` 带 `url` 时，直接用该 URL 下载即可（普通 HTTP GET），无需走 shortcut。
|
||||
- 没有 `url`、或只想预览 → `docs +media-preview --token <token> --output ./preview_media`
|
||||
- 明确下载，或目标是 `<whiteboard>`（画板只能走 shortcut） → `docs +media-download --token <token> --output ./downloaded_media`
|
||||
|
||||
## 嵌入电子表格 / 多维表格
|
||||
|
||||
返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch --api-version v2` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-create](lark-doc-create.md) — 创建文档
|
||||
- [lark-doc-update](lark-doc-update.md) — 更新文档
|
||||
- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
|
||||
- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材/画板缩略图
|
||||
76
.agents/skills/lark-doc/references/lark-doc-md.md
Normal file
76
.agents/skills/lark-doc/references/lark-doc-md.md
Normal file
@ -0,0 +1,76 @@
|
||||
# Markdown 格式参考
|
||||
|
||||
`docs +fetch --api-version v2` / `docs +create --api-version v2` / `docs +update --api-version v2` 使用 `--doc-format markdown` 时适用。
|
||||
|
||||
## 转义规则
|
||||
|
||||
> **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。
|
||||
|
||||
### 无条件转义（行内生效，任何位置都要转义）
|
||||
|
||||
| 符号 | Markdown 语法用途 | 转义写法 | 示例 |
|
||||
|------|-------------------|----------|------|
|
||||
| `\` | 转义符本身 | `\\` | `C:\\Users` → C:\Users |
|
||||
| `` ` `` | 行内代码 | `` \` `` | `` 用 \` 包裹 `` |
|
||||
| `*` | 斜体 / 加粗 | `\*` | `3 \* 5 = 15` → 3 \* 5 = 15 |
|
||||
| `_` | 斜体 / 加粗 | `\_` | `foo\_bar\_baz` → foo\_bar\_baz |
|
||||
| `[` `]` | 链接文本 | `\[` `\]` | `\[非链接\]` |
|
||||
| `$` | 数学公式定界 | `\$` | `价格 \$100` |
|
||||
| `~` | 删除线（GFM `~~text~~`） | `\~` | `a\~\~b\~\~c` → a~~b~~c |
|
||||
| `<` | XML 标签起始（`<b>`、`<img>` 等会被当作标签解析并生效） | `\<` | 字面量 `<b>` 须写为 `\<b>`；`a < b` 建议写为 `a \< b` |
|
||||
|
||||
### 位置敏感转义（仅在特定位置才需要转义）
|
||||
|
||||
| 符号 | Markdown 语法用途 | 转义条件 | 示例 |
|
||||
|------|-------------------|----------|------|
|
||||
| `#` | 标题 | **仅行首**（去除前导空白后）| 行首 `\# 这不是标题`；行内 `A # B` 无需转义 |
|
||||
| `+` | 无序列表 | **仅行首**（去除前导空白后）| 行首 `\+ item`；行内 `1 + 2` 无需转义 |
|
||||
| `-` | 无序列表 / 分隔线 | **仅行首**（去除前导空白后）| 行首 `\- item`；行内 `A - B` 无需转义 |
|
||||
| `>` | 引用块 | **仅行首**（去除前导空白后）| 行首 `\> 不是引用`；行内 `a > b` 无需转义 |
|
||||
| `\|` | 表格 cell 分隔 | **仅在 GFM 表格 cell 内** | cell 内 `A \| B`；行内普通文本 `a \| b` 无需转义 |
|
||||
|
||||
**不需要转义的场景：**
|
||||
- 在 `` ` `` 行内代码或 ` ``` ` 代码块内，所有符号均为字面量，无需转义
|
||||
- `$...$` 数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响
|
||||
|
||||
**导出已转义，不要反转义：**
|
||||
`docs +fetch --api-version v2 --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**
|
||||
|
||||
**写入时必须转义：**
|
||||
使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。
|
||||
|
||||
**导出 → 更新 工作流示例：**
|
||||
|
||||
1. `docs +fetch --api-version v2` 导出得到 `C:\\Users\\test\[1\]`
|
||||
2. 用 `str_replace --pattern 'C:\\Users\\test\[1\]'` 匹配（直接使用导出的转义形式）
|
||||
3. `--content` 中的替换内容也要保持转义：`C:\\Users\\prod\[2\]`
|
||||
|
||||
自行构造 Markdown 内容写入时同理：如字面文本 `a]b` 应写为 `a\]b`，`C:\Users` 应写为 `C:\\Users`。
|
||||
|
||||
## Shell 传参
|
||||
- **首选文件传参**：`--content` 支持 `@path/to/file.md`（读文件）和 `-`（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以 `@` 开头时用 `@@` 转义（`--pattern` 不支持 `@file`）
|
||||
- **⚠️ `@file` 路径限制**：`@file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下（如 `./_content.md`），用完自行清理。
|
||||
- **默认用单引号 `'...'`**：完全字面量，`$`、`` ` ``、`\`、`>`、`\<b>` 等全部原样保留
|
||||
- **双引号 `"..."`**：会展开 `$变量`、反引号和 `$(...)` 命令替换，`\` 仍参与转义，易踩坑
|
||||
- **`$'...'` ANSI-C 引号**：按 C 转义解析，`\n`=换行、`\\`=单个 `\`；**zsh 下未知转义（如 `\<`）的 `\` 会被吞**，要保留字面 `\` 必须写 `\\`。只在确实需要 `\n`/`\t` 时用
|
||||
- **多行内容**：用 `<<'EOF'` heredoc，EOF 必须带引号，否则仍展开 `$`
|
||||
- **`\n` 在 `'...'` 和 `"..."` 里都是字面量**，不是换行；要真换行用 `$'...\n...'` 或 heredoc
|
||||
|
||||
## 图片语法
|
||||
|
||||
Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下载：
|
||||
```markdown
|
||||
|
||||
```
|
||||
- `alt text` 为图片描述（可选，可留空）
|
||||
- URL 支持 `http://` 和 `https://` 协议
|
||||
- 对应的 XML 格式为：`<img href="https://example.com/photo.png"/>`
|
||||
|
||||
## Markdown 不支持的 Block 类型
|
||||
|
||||
非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。
|
||||
> **⚠️ XML 标签会被解析并生效**：即使在 `--doc-format markdown` 下，`<b>`、`<u>`、`<img>` 等 XML 标签也会被识别为对应的富文本节点，**不会**按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的 `<tag>`），必须转义左尖括号：`\<b>`、`\<img>`。
|
||||
|
||||
## 参考
|
||||
|
||||
- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
|
||||
@ -0,0 +1,50 @@
|
||||
|
||||
# docs +media-download（下载文档素材/画板缩略图）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
下载文档中的图片/文件素材（`file_token`），或下载画板缩略图（`whiteboard_id`）。当 `--output` 不带扩展名时，会根据响应的 `Content-Type` 自动补全扩展名。
|
||||
|
||||
## 选择规则
|
||||
|
||||
- 用户明确说“下载素材”时，使用 `docs +media-download`
|
||||
- 用户只是想查看、预览图片或文件素材时，优先使用 [`docs +media-preview`](lark-doc-media-preview.md)
|
||||
- 如果目标明确是画板 / whiteboard / 画板缩略图，继续使用 `docs +media-download --type whiteboard`；`+media-preview` 不支持画板
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 下载图片/文件素材（默认 type=media）
|
||||
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset
|
||||
|
||||
# 指定输出文件名（带扩展名则不会自动补全）
|
||||
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset.png
|
||||
|
||||
# 下载画板缩略图（whiteboard token）
|
||||
lark-cli docs +media-download --type whiteboard --token "wbcnxxxxxxxx" --output ./whiteboard
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--token <token>` | 是 | 资源 token：素材为 `file_token`，画板为 `whiteboard_id` |
|
||||
| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
|
||||
| `--type <type>` | 否 | `media`（默认）或 `whiteboard` |
|
||||
|
||||
## token 从哪里来
|
||||
|
||||
- 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含：
|
||||
- 图片：`<image token="..." .../>`
|
||||
- 文件：`<file token="..." name="..."/>`
|
||||
- 画板：`<whiteboard token="..."/>`
|
||||
|
||||
## 排障
|
||||
|
||||
- 如果报错返回的信息包含 `HTTP 403`，且目标是图片/文件素材，可以改成调用 [`docs +media-preview`](lark-doc-media-preview.md) 看是否能先预览内容
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
|
||||
- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
114
.agents/skills/lark-doc/references/lark-doc-media-insert.md
Normal file
114
.agents/skills/lark-doc/references/lark-doc-media-insert.md
Normal file
@ -0,0 +1,114 @@
|
||||
|
||||
# docs +media-insert（文档末尾插入图片/文件）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
把"创建空 block → 上传文件 → 设置 token"三步合并成一个命令，在**文档末尾**插入本地图片或文件。
|
||||
|
||||
## 来源选择（Agent 必读）
|
||||
|
||||
> **最高优先级：用户明确指定了来源，就严格按用户的来。** 下面的启发式只在用户没表态时生效。
|
||||
>
|
||||
> - 用户说"把这张截图插进去"、"用剪切板里的图"、"我刚复制的" → 无条件走 `--from-clipboard`。
|
||||
> - 用户说"用 `~/Downloads/foo.png`"、"插本地这个文件"、给了具体路径 → 无条件走 `--file`。
|
||||
> - 用户两者都没说清 → 按下表的启发式推断。
|
||||
>
|
||||
> 即使推断看起来更"优"（比如用户说了路径但你觉得走剪切板更省事），也**不要自作主张**换来源。要换，先问。
|
||||
|
||||
按下列顺序判断，**不要反向做**：
|
||||
|
||||
| 用户的图片来源 | 命令 | 禁止做法 |
|
||||
|----------------|------|----------|
|
||||
| 图片已经在剪切板里（截图快捷键、从飞书/浏览器复制、从设计稿复制） | `--from-clipboard` | ❌ 不要先把剪切板存到本地文件再用 `--file`。多一步文件 I/O，还得清理临时文件。 |
|
||||
| 图片是磁盘上的真实文件 | `--file <path>` | — |
|
||||
| 图片是 URL | 先下载到本地 → `--file`；或用 `drive` 相关命令 | — |
|
||||
|
||||
`--from-clipboard` 走进程内存直传，不产生临时文件；macOS / Windows 内置支持，Linux 需要 `xclip` 或 `wl-paste` 或 `xsel` 任一。
|
||||
|
||||
### 剪切板为空时的 fallback
|
||||
|
||||
`--from-clipboard` 失败（剪切板里不是图片 / 没有图片 / Linux 上三个工具都没装）时，命令会返回 `clipboard contains no image data`（或类似的平台错误）。**这不是错误退出理由，而是 fallback 信号。**
|
||||
|
||||
**Agent 的标准处置顺序**（每一步失败再进下一步，不要并行）：
|
||||
|
||||
1. 先用 `--from-clipboard` 试一次。
|
||||
2. 如果返回"no image data"类错误，**向用户明确说明剪切板里没有可识别的图片**，请用户提供本地文件路径或重新复制一张图。
|
||||
3. 拿到本地路径后，用 `--file <path>` 重试**同一条插入命令**（其他参数如 `--doc` / `--align` / `--caption` 保持不变）。
|
||||
|
||||
**禁止做法**：
|
||||
- ❌ 不要悄悄把空剪切板当"成功但没插入"处理。必须提示用户。
|
||||
- ❌ 不要在剪切板失败后自行瞎猜某个本地文件路径（比如最近修改的 png）。必须让用户给路径。
|
||||
- ❌ 不要用"先让用户保存剪切板到磁盘再 `--file`"的建议绕过 `--from-clipboard`，当且仅当剪切板确实没图片时才退回本地路径。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 🟢 推荐：从剪切板直接插入（无需先存盘）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard
|
||||
|
||||
# 从本地文件插入
|
||||
# 除了上传本地文件，还可以在 `docs +update` 时直接通过网络 URL 插入图片，无需先下载到本地：
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \
|
||||
--block-id "目标 block_id" \
|
||||
--content '<img href="https://example.com/photo.png"/>'
|
||||
|
||||
# 插入图片（默认）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --file ./image.png
|
||||
|
||||
# doc 支持直接传 docx URL（自动提取 document_id）
|
||||
lark-cli docs +media-insert --doc "https://xxx.feishu.cn/docx/doxcnXXX" --from-clipboard
|
||||
|
||||
# 如果上一步是 create-doc，优先传返回值里的 doc_id
|
||||
# 不要把 /wiki/... 形式的 doc_url 直接传给 docs +media-insert
|
||||
lark-cli docs +media-insert --doc doxcnReturnedByCreateDoc --file ./image.png
|
||||
|
||||
# 插入文件（非图片）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --file ./spec.pdf --type file
|
||||
|
||||
# 图片对齐与描述（caption）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --align center --caption "架构图"
|
||||
|
||||
# Insert image with explicit display width (height auto-computed from aspect ratio)
|
||||
lark-cli docs +media-insert --doc doxcnXXX --file ./banner.png --width 800 --align center
|
||||
|
||||
# Insert image with explicit width and height
|
||||
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --width 800 --height 447 --caption "architecture diagram"
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--doc <id>` | 是 | 文档 ID 或 docx URL（仅支持 `/docx/<document_id>` 形式自动提取；**不支持 `/wiki/...` URL 自动提取**） |
|
||||
| `--from-clipboard` | 二选一 | 从系统剪切板读取图片（与 `--file` 互斥）。macOS/Windows 内置支持，Linux 需要 `xclip` / `wl-paste` / `xsel` 之一。 |
|
||||
| `--file <path>` | 二选一 | 本地文件路径（文件大于 20MB 时自动切换分片上传） |
|
||||
| `--type <type>` | 否 | `image`（默认）或 `file`。`--from-clipboard` 目前只产出 image。 |
|
||||
| `--align <align>` | 否 | 仅图片：`left` / `center`（默认）/ `right` |
|
||||
| `--caption <text>` | 否 | 仅图片：图片描述 |
|
||||
| `--width <px>` | 否 | Image display width in pixels (only for `--type=image`). If `--height` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
|
||||
| `--height <px>` | 否 | Image display height in pixels (only for `--type=image`). If `--width` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 如果上一步是 [`lark-doc-create`](lark-doc-create.md)，并且它在知识库/知识空间场景下返回的是 `/wiki/...` 形式的 `doc_url`，后续调用 `docs +media-insert` 时应优先传 `doc_id`，不要直接传这个 `doc_url`。
|
||||
|
||||
## 平台注意（仅 `--from-clipboard`）
|
||||
|
||||
| 平台 | 依赖 | 典型错误 |
|
||||
|------|------|---------|
|
||||
| macOS | osascript（内置） | 剪切板为空 / 不是图片 → "clipboard contains no image data" |
|
||||
| Windows | PowerShell + System.Windows.Forms（内置） | 同上 |
|
||||
| Linux | `xclip` 或 `wl-paste` 或 `xsel` 任一 | 都没安装 → 报错会提示用发行版包管理器安装 |
|
||||
|
||||
命令不支持读取 TIFF 等非 PNG/JPEG/GIF/WebP/BMP 的冷门格式；遇到这类剪切板会返回 "contains no image data"，此时才考虑先用系统工具转成文件再 `--file`。
|
||||
|
||||
## 输出
|
||||
|
||||
命令成功后会输出 JSON，包含：`document_id`、`block_id`、`file_token`、`file_name`（剪切板路径下为 `clipboard.png`）、`type`。
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作**（会修改文档内容）—— 执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
41
.agents/skills/lark-doc/references/lark-doc-media-preview.md
Normal file
41
.agents/skills/lark-doc/references/lark-doc-media-preview.md
Normal file
@ -0,0 +1,41 @@
|
||||
|
||||
# docs +media-preview（预览文档素材）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。
|
||||
|
||||
## 选择规则
|
||||
|
||||
- 用户说“看一下素材 / 图片 / 附件”“预览一下”时，优先使用 `docs +media-preview`
|
||||
- 用户明确说“下载”时，使用 [`docs +media-download`](lark-doc-media-download.md)
|
||||
- 如果目标明确是画板 / whiteboard / 画板缩略图，不要使用 `+media-preview`，改用 `docs +media-download --type whiteboard`
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 预览图片/文件素材
|
||||
lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset
|
||||
|
||||
# 指定输出文件名（带扩展名则不会自动补全）
|
||||
lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset.png
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--token <token>` | 是 | 素材 token，即 `file_token` |
|
||||
| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
|
||||
|
||||
## token 从哪里来
|
||||
|
||||
- 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含：
|
||||
- 图片：`<image token="..." .../>`
|
||||
- 文件：`<file token="..." name="..."/>`
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
|
||||
- [lark-doc-media-download](lark-doc-media-download.md) — 明确下载素材，或下载画板缩略图
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
251
.agents/skills/lark-doc/references/lark-doc-update.md
Normal file
251
.agents/skills/lark-doc/references/lark-doc-update.md
Normal file
@ -0,0 +1,251 @@
|
||||
|
||||
# docs +update（更新飞书云文档）
|
||||
|
||||
> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
|
||||
> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
|
||||
> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
|
||||
> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
|
||||
>
|
||||
> **未读完以上文件就生成内容会导致格式错误或样式不达标。**
|
||||
|
||||
通过八种指令精确更新飞书云文档。支持字符串级别和 block 级别的操作。
|
||||
|
||||
> **⚠️ 格式选择规则：**
|
||||
> - **局部精修**（`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after`）：优先使用 XML（默认）。XML 能稳定表达 block 结构和样式，精准编辑更可控；不要因为 Markdown 写起来更简单就自行切换。
|
||||
> - **整段写入**（`append` / `overwrite`）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件或明确要求 Markdown 时直接用 Markdown；否则默认 XML。
|
||||
>
|
||||
> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --api-version v2 --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--api-version` | 是 | 固定传 `v2` |
|
||||
| `--doc` | 是 | 文档 URL 或 token |
|
||||
| `--command` | 是 | 操作指令（见下方指令速查表） |
|
||||
| `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
|
||||
| `--content` | 视指令 | 写入内容（`str_replace` 传空字符串可实现删除） |
|
||||
| `--pattern` | 视指令 | 匹配文本（str_replace） |
|
||||
| `--block-id` | 视指令 | 目标 block ID（block_* 操作），逗号分隔可批量删除，-1 表示末尾 |
|
||||
| `--src-block-ids` | 视指令 | 源 block ID（逗号分隔），用于 block_copy_insert_after / block_move_after |
|
||||
| `--revision-id` | 否 | 基准版本号，-1 = 最新（默认 `-1`） |
|
||||
|
||||
## 指令速查表
|
||||
|
||||
| 指令 | 说明 | 必需参数 |
|
||||
|------|------|----------|
|
||||
| `str_replace` | 全文文本查找替换（replacement 支持富文本标签；`--content` 传空字符串即为删除） | `--pattern` `--content` |
|
||||
| `block_insert_after` | 在指定 block 之后插入新内容 | `--block-id` `--content` |
|
||||
| `block_copy_insert_after` | 复制源 block 并插入到锚点之后（源块不变） | `--block-id` `--src-block-ids` |
|
||||
| `block_replace` | 替换指定 block（同一 block 仅限一次） | `--block-id` `--content` |
|
||||
| `block_delete` | 删除指定 block（逗号分隔可批量） | `--block-id` |
|
||||
| `overwrite` | ⚠️ 清空文档后全文重写（可能丢失图片、评论） | `--content` |
|
||||
| `append` | ⚠️ 在文档**末尾**追加内容（等价于 `block_insert_after --block-id -1`）。**不适用于逐章填充**——逐章写入请用 `block_insert_after` 并指定对应标题的 `--block-id` | `--content` |
|
||||
| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` |
|
||||
|
||||
## 指令示例
|
||||
|
||||
### str_replace — 全文文本替换
|
||||
|
||||
> **匹配范围：**
|
||||
> - **XML 模式（默认）**：`--pattern` 只支持**行内匹配**，不能跨 block / 跨段落匹配。涉及整段或多 block 的改动，请改用 `block_replace`。
|
||||
> - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行匹配**，可以用多行字符串匹配并替换一整段内容。
|
||||
> - 还支持**`前缀...后缀` 省略号语法**：用 `...`（三个英文句点）串联起始与结束片段，匹配从前缀到后缀之间的全部内容（含中间被省略部分）。适合一段很长、但首尾特征明显的文本，避免把整段都塞进 `--pattern`。
|
||||
> - 前缀、后缀本身仍遵循 Markdown 转义规则；省略号中间的内容**会被替换**为 `--content` 的完整文本，不会被保留。
|
||||
|
||||
```bash
|
||||
# 简单文本替换
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
|
||||
--pattern "张三" --content "李四"
|
||||
|
||||
# 替换为富文本（加粗 + 链接）
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
|
||||
--pattern "旧链接" --content '<b>新链接</b> <a href="https://example.com">点击查看</a>'
|
||||
|
||||
# 仅当用户明确要求时才使用 Markdown
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
|
||||
--doc-format markdown --pattern "旧内容" --content "新内容"
|
||||
|
||||
# Markdown 模式下支持跨行匹配（--pattern 与 --content 都需要真实换行；"..."/'...' 里的 \n 是字面量）
|
||||
# 多行内容推荐 heredoc 或 --content @file.md，避免 shell 转义踩坑
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
|
||||
--doc-format markdown \
|
||||
--pattern "$(printf '## 旧标题\n\n第一段原文\n\n第二段原文')" \
|
||||
--content - <<'EOF'
|
||||
## 新标题
|
||||
|
||||
改写后的第一段
|
||||
|
||||
改写后的第二段
|
||||
EOF
|
||||
|
||||
# Markdown 模式下使用 `前缀...后缀` 省略号匹配首尾特征明显的大段内容
|
||||
# 下例会把「## 旧标题」到「结束语。」之间的所有内容整体替换
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
|
||||
--doc-format markdown \
|
||||
--pattern "## 旧标题...结束语。" \
|
||||
--content - <<'EOF'
|
||||
## 新标题
|
||||
|
||||
重写后的正文...
|
||||
|
||||
新的结束语。
|
||||
EOF
|
||||
|
||||
# 删除文本：--content 传空字符串即可
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
|
||||
--pattern "废弃的内容" --content ""
|
||||
```
|
||||
|
||||
### block_insert_after — 在指定 block 之后插入
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \
|
||||
--block-id "目标 block_id" \
|
||||
--content '<h2>新章节</h2><ul><li>要点 1</li><li>要点 2</li></ul>'
|
||||
```
|
||||
|
||||
### block_replace — 替换指定 block
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace \
|
||||
--block-id "目标 block_id" \
|
||||
--content '<p>替换后的段落内容</p>'
|
||||
```
|
||||
|
||||
### block_delete — 删除指定 block
|
||||
|
||||
```bash
|
||||
# 删除多个块时用逗号 "," 分隔
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_delete \
|
||||
--block-id "block_id_1,block_id_2,block_id_3"
|
||||
```
|
||||
|
||||
### overwrite — 全文覆盖
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command overwrite \
|
||||
--content '<title>全新文档</title><h1>概述</h1><p>新的内容</p>'
|
||||
```
|
||||
|
||||
> ⚠️ 会清空文档后重写，可能丢失图片、评论等。仅在需要完全重建文档时使用。
|
||||
|
||||
### append — 在文档末尾追加
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command append \
|
||||
--content '<h2>新增章节</h2><p>追加的内容</p>'
|
||||
```
|
||||
|
||||
> 等价于 `block_insert_after --block-id -1`，无需先获取 block ID。
|
||||
|
||||
### block_copy_insert_after — 复制块并插入
|
||||
|
||||
将一个或多个源块复制到锚点块之后，源块保持不变。`--src-block-ids` 为逗号分隔的源块 ID，按顺序依次插入到锚点之后。
|
||||
|
||||
```bash
|
||||
# 复制多个块（按顺序插入：anchor → a → b → c）
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_copy_insert_after \
|
||||
--block-id "锚点 block_id" \
|
||||
--src-block-ids "block_a,block_b,block_c"
|
||||
```
|
||||
|
||||
### block_move_after — 移动已有 block
|
||||
|
||||
将文档中已有的 block 移动到指定锚点之后。使用 `--src-block-ids` 指定要移动的块 ID，无需 `--content`。
|
||||
|
||||
```bash
|
||||
# 移动到页面末尾
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_move_after \
|
||||
--block-id "-1表示末尾，page_id表示开头，blk" \
|
||||
--src-block-ids "block_a,block_b"
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "user",
|
||||
"data": {
|
||||
"document": {
|
||||
"revision_id": 13,
|
||||
"new_blocks": [
|
||||
{ "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
|
||||
]
|
||||
},
|
||||
"result": "success",
|
||||
"updated_blocks_count": 3,
|
||||
"warnings": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `result` | `success` \| `partial_success` \| `failed` |
|
||||
| `updated_blocks_count` | 实际更新的 block 数量 |
|
||||
| `warnings` | 警告信息列表 |
|
||||
| `document.new_blocks` | 本次操作新增的 block 列表（如画板）。`block_id` 可用于后续精确编辑；`block_token` 是资源块 token（如画板）可交给 `lark-whiteboard` 等 skill 继续操作 |
|
||||
|
||||
## 典型工作流
|
||||
|
||||
### 精确 block 级更新
|
||||
|
||||
1. **获取文档内容和 block ID**：
|
||||
```bash
|
||||
lark-cli docs +fetch --api-version v2 --doc "<doc_id>" --detail with-ids
|
||||
```
|
||||
|
||||
2. **定位目标 block**：从返回的 XML 中找到要修改的 block 及其 `id` 属性
|
||||
|
||||
3. **执行更新**：
|
||||
```bash
|
||||
# 替换特定 block
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace \
|
||||
--block-id "blkcnXXXX" --content "<p>新内容</p>"
|
||||
|
||||
# 在某 block 后插入
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \
|
||||
--block-id "blkcnXXXX" --content "<h2>追加的章节</h2>"
|
||||
```
|
||||
|
||||
### 简单文本替换
|
||||
|
||||
不需要 block ID，直接匹配替换：
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
|
||||
--pattern "v1.0" --content "v2.0"
|
||||
```
|
||||
|
||||
## 画板处理
|
||||
|
||||
> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch --api-version v2` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。
|
||||
|
||||
画板的语法选型与插入示例见 [`lark-doc-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **精确操作优于全文覆盖**：使用 `block_replace`/`block_insert_after` 精确修改，避免 `overwrite` 全文覆盖
|
||||
- **str_replace 的匹配范围取决于格式**：
|
||||
- **XML 模式（默认）**：`--pattern` 只支持**行内**匹配，不支持跨行 / 跨 block。段落、整块或容器级（列表、表格、分栏、引用块等）改动请改用 `block_replace` 指定 block_id 重建。
|
||||
- **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行**匹配，还支持 `前缀...后缀` 省略号语法（用 `...` 串联首尾片段匹配一大段内容），可以一次替换多行文本；但仍建议优先按最小片段匹配，跨 block 容器级重写仍优先用 `block_replace`，避免副作用。
|
||||
- **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block
|
||||
- **str_replace 的 replacement 支持富文本**：可以用行内标签 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本
|
||||
- **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace
|
||||
- **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除
|
||||
- **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全：
|
||||
1. 用 `block_insert_after` 在目标位置插入新的富文本结构
|
||||
2. 用 `block_delete` 批量删除旧的 block
|
||||
3. 这样可以保留文档中其他不相关的内容（图片、评论等）
|
||||
- **视觉丰富度**：插入或替换内容时，同样遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block
|
||||
|
||||
## 参考
|
||||
|
||||
- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
|
||||
- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
|
||||
- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
|
||||
- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
|
||||
- [`lark-doc-create.md`](lark-doc-create.md) — 创建文档
|
||||
- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
|
||||
154
.agents/skills/lark-doc/references/lark-doc-whiteboard.md
Normal file
154
.agents/skills/lark-doc/references/lark-doc-whiteboard.md
Normal file
@ -0,0 +1,154 @@
|
||||
# lark-doc 画板处理指南
|
||||
|
||||
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
## 两个 Skill 的职责边界
|
||||
|
||||
| Skill | 核心职责 | 约束 |
|
||||
|-------------------|-----------------------------------------------------------|---------------------------------|
|
||||
| `lark-doc` | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容； |
|
||||
| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板 | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |
|
||||
|
||||
## 画板优先规则
|
||||
|
||||
写文档时，重要信息优先画板化。遇到核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，不要只用段落或表格承载；除非内容只是一次性补充说明，否则应规划为画板。
|
||||
|
||||
同一篇文档可以有多个画板。优先设计多个聚焦画板，而不是把所有信息塞进一张大图。
|
||||
|
||||
## 文档与画板协同流程
|
||||
|
||||
### 步骤 1：识别画板机会
|
||||
|
||||
| 场景 | 入口 |
|
||||
|-------------------------|-----------------------------------------------------------|
|
||||
| 文档中需要思维导图、时序图、类图、饼图、甘特图 | 步骤 2A:使用 mermaid 插入图表 |
|
||||
| 文档中需要插入其他图表/自定义图形 | 步骤 2B: 使用 SVG 插入图表 |
|
||||
| 已有画板需要更新内容 | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3B |
|
||||
| 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ⚠️ **分别对每个图表进行决策**
|
||||
|
||||
如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B
|
||||
中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动
|
||||
SubAgent 插入 SVG。
|
||||
|
||||
建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表
|
||||
|
||||
### 步骤 2A: 使用 mermaid 插入图表
|
||||
|
||||
```xml
|
||||
|
||||
<whiteboard type="mermaid">
|
||||
mermaid 代码...
|
||||
</whiteboard>
|
||||
```
|
||||
|
||||
### 步骤 2B: SubAgent 使用 SVG 插入图表
|
||||
|
||||
主 Agent 启动 SubAgent，让它用 `docs +create --api-version v2` / `docs +update --api-version v2` 插入：
|
||||
|
||||
```xml
|
||||
|
||||
<whiteboard type="svg">
|
||||
<svg...>...
|
||||
</svg>
|
||||
</whiteboard>
|
||||
```
|
||||
|
||||
Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：
|
||||
|
||||
- doc token、插入位置（标题 / block_id / command）
|
||||
- 图表目标、受众、源段落或数据
|
||||
- 要求读取 `lark-doc-xml.md`；不需要读取 `lark-whiteboard`
|
||||
- SVG 必须完整自包含：包含 `<svg>` 根节点和 `viewBox`，不引用外部图片、脚本、远程资源
|
||||
|
||||
#### 画板 SVG 设计指南
|
||||
|
||||
使用 SVG 插入画板时，最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)
|
||||
**核心心智纠正 (重要)**：
|
||||
|
||||
- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `<rect>` 的方正卡片网格, 极其死板单调, *
|
||||
*这将被视为不及格！**
|
||||
- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`<path>`), 连接指引 (`流畅的 <path>`), 各种环境氛围点缀,
|
||||
大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！
|
||||
|
||||
##### SVG 设计 Workflow
|
||||
|
||||
###### 1. 想清楚要画什么
|
||||
|
||||
- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
|
||||
- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
|
||||
- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构
|
||||
|
||||
###### 2. 写 SVG
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `<rect>` 牢笼, 严禁通篇用矩形和文字应付用户
|
||||
> 操作边界约束：
|
||||
|
||||
- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
|
||||
- 文字用 `<text>`(不是 `<path>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
|
||||
- 连线使用正交折线替代斜直线(`<polyline>` 带水平/垂直折点)视觉效果更好
|
||||
- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲
|
||||
|
||||
###### 画板怎么处理 SVG
|
||||
|
||||
画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但
|
||||
`<radialGradient>` / `<filter>` / `<clipPath>` 等装饰特性画板完全不支持，会导致渲染问题（见下方⚠️）
|
||||
**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**
|
||||
|
||||
**可识别的元素**
|
||||
|
||||
- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
|
||||
- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
|
||||
- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
|
||||
- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
|
||||
- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ⚠️ ** 不支持的装饰特性**
|
||||
|
||||
- `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>` → 画板都不支持，**请避免使用，否则会导致画板渲染问题
|
||||
**
|
||||
|
||||
###### 3.插入后审查
|
||||
|
||||
插入画板后，可以从返回值使用 lark-cli 指令，将画板内容导出为 png
|
||||
图片。若是对设计不满意，可以修改后，删除原来的画板再重新插入，或是调用 [
|
||||
`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) 编辑。
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +query \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output_as image \
|
||||
--output ./preview.png
|
||||
```
|
||||
|
||||
### 步骤 3B：编辑已有画板 — 启动 lark-whiteboard SubAgent
|
||||
|
||||
复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 `lark-whiteboard` 的渲染和写入流程。
|
||||
|
||||
复杂图 SubAgent 的最小上下文：
|
||||
|
||||
- board_token
|
||||
- 图表目标、推荐画板类型、受众
|
||||
- 与图表直接相关的源段落或数据
|
||||
- 要求读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，按其完整流程写入该 board_token
|
||||
|
||||
多个画板互不依赖时，可并行启动多个 SubAgent；每个 SubAgent 只负责一个画板或一个 SVG 插入点，不要互相复用上下文。
|
||||
|
||||
### 步骤 4：完成校验
|
||||
|
||||
- Mermaid: 确认插入的是 `<whiteboard type="mermaid">`，且内容 mermaid 语法完整
|
||||
- SVG: 确认插入的是 `<whiteboard type="svg">`，且内容是完整 `<svg ...>...</svg>`
|
||||
- 不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成
|
||||
|
||||
---
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 关联参考
|
||||
|
||||
- 画板查询/创作/修改/渲染写入：[`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)
|
||||
177
.agents/skills/lark-doc/references/lark-doc-xml.md
Normal file
177
.agents/skills/lark-doc/references/lark-doc-xml.md
Normal file
@ -0,0 +1,177 @@
|
||||
基于 HTML 子集的 XML 格式描述飞书文档内容。
|
||||
|
||||
# 一、标准 HTML 标签
|
||||
p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr, img, b, em, u, del, a, br, span 语义不变
|
||||
|
||||
# 二、扩展标签速查表
|
||||
## 块级标签
|
||||
|标签|说明|关键属性|
|
||||
|-|-|-|
|
||||
| `<title>` | 文档标题（每篇唯一）| `align` |
|
||||
| `<checkbox>` | 待办项| `done="true"\|"false"` |
|
||||
|
||||
## 容器标签
|
||||
|标签|说明|关键属性|
|
||||
|-|-|-|
|
||||
| `<callout>` | 高亮框，子块仅支持文本、标题、列表、待办、引用 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
|
||||
| `<grid>` + `<column>` | 分栏布局，各列 width-ratio 之和为 1 | `width-ratio` |
|
||||
| `<whiteboard>` | 嵌入画板 | `type`: `blank` \| `mermaid` \| `plantuml` \| `svg` |
|
||||
| `<pre>` | （代码块，内含 `code`）| `lang`, `caption` |
|
||||
| `<figure>` | 视图容器 | `view-type` |
|
||||
| `<bookmark>` | 书签链接 | `<bookmark name="标题" href="https://..."></bookmark>`，必传 name 和 href |
|
||||
|
||||
## 行内组件
|
||||
| 标签 | 说明 | 关键属性 |
|
||||
|-|-|-|
|
||||
| `<cite type="user">` | @人 | `<cite type="user" user-id="userID"></cite>` |
|
||||
| `<cite type="doc">` | @文档 | `<cite type="doc" doc-id="docx_token"></cite>` |
|
||||
| `<latex>` | 行内公式 | `<latex>E = mc^2</latex>` |
|
||||
| `<img>` | 图片（可独立成块或内联） | `<img width="800" height="600" caption="说明" name="图.png" href="http 或 https"/>` |
|
||||
| `<source>` | 文件附件（可独立成块或内联） | `<source name="报告.pdf"/>` |
|
||||
| `<a type="url-preview">` | 预览卡片 | `<a type="url-preview" href="...">标题</a>` |
|
||||
| `<button>` | 操作按钮 | `background-color`、`src`，必须包含 `action=OpenLink\|DuplicatePage\|FollowPage` |
|
||||
| `<time>` | 提醒 | 必包含 `expire-time`、`notify-time`（毫秒时间戳）、`should-notify=true\|false` |
|
||||
|
||||
## 文本块通用属性
|
||||
- `align` — `"left"`|`"center"`|`"right"`（适用于 p / h1-h9 / li / checkbox）
|
||||
- 有序列表项用 `seq="auto"` 自动编号
|
||||
|
||||
# 三、资源块
|
||||
|
||||
文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：
|
||||
|
||||
- `<img>` — `<img href="https://..."/>` 上传网络图片
|
||||
- `<whiteboard>` — 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；复杂图使用 `<whiteboard type="blank"></whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；
|
||||
- `<sheet>` — `<sheet type="blank"></sheet>` 空白；`<sheet sheet-id="SID" token="TOKEN"></sheet>` 复制已有
|
||||
- `<task>` — `<task task-id="GUID"></task>`，必传 task-id（任务 guid）
|
||||
- `<chat_card>` — `<chat_card chat-id="CHAT_ID"></chat_card>`，必传 chat-id
|
||||
- `<sub-page-list>` — `<sub-page-list></sub-page-list>` 子页面列表块；仅 wiki 文档可插入
|
||||
- bitable、base_ref、synced_reference、synced_source、okr — 不可创建，仅支持移动
|
||||
|
||||
# 四、块级复制与移动
|
||||
|
||||
## 移动（block_move_after）
|
||||
支持**所有**块类型（块级标签、容器标签、行内组件、资源块），使用 `docs +update --command block_move_after --block-id "<锚点>" --src-block-ids "id1,id2"`。
|
||||
|
||||
## 复制（block_copy_insert_after）
|
||||
- **基础标签**（块级标签、容器标签、行内组件）：均支持复制
|
||||
- **资源块**：仅 img、source、whiteboard、sheet、chat_card、sub-page-list 支持复制；task、bitable、base_ref、synced_reference、synced_source、okr 不支持复制
|
||||
|
||||
使用 `docs +update --command block_copy_insert_after --block-id "<锚点>" --src-block-ids "id1,id2"`。
|
||||
|
||||
> 详见 [lark-doc-update.md](lark-doc-update.md)。
|
||||
|
||||
# 五、补充规则
|
||||
|
||||
## 富文本样式嵌套顺序
|
||||
- 行内样式标签必须按以下固定顺序嵌套（外 → 内），关闭顺序严格反转：`<a> → <b> → <em> → <del> → <u> → <code> → <span> → 文本内容`
|
||||
|
||||
## 列表分组
|
||||
- 连续同类型列表项自动合并为一个 `<ul>` 或 `<ol>`
|
||||
- 嵌套子列表放在 `<li>` 内部
|
||||
- 新增列表项必须包在 `<ul>` 或 `<ol>` 内：
|
||||
```xml
|
||||
<ul>
|
||||
<li>第一项</li>
|
||||
<li>第二项</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
|
||||
## 用户名写入规则
|
||||
|
||||
- 当从 IM 消息、日历、审批、任务等来源获取到用户的 `open_id` 时，写入文档**必须**使用 `<cite type="user" user-id="open_id">` 标签，而非纯文本名字。这样文档中会渲染为可点击的 @人。
|
||||
- 典型场景：IM 消息的 `sender`、`mentions`、reactions 的 `operator`、卡片消息中引用的用户、系统消息中的用户名、合并转发中的用户名。
|
||||
- 当只有纯文本名字而没有 `open_id` 时（如系统消息、合并转发内容），先通过 `lark-cli contact +search-user --query "名字" --as user` 反查 `open_id`，再写入 cite 标签。
|
||||
|
||||
## 表格扩展
|
||||
标准 HTML table 结构不变，扩展点：
|
||||
- `<colgroup>` / `<col>` 定义列宽，紧跟 `<table>` 之后：`<col span="2" width="100"/>`
|
||||
- `<th>` / `<td>` 增加 `background-color` 和 `vertical-align`（top | middle | bottom）
|
||||
- 有表头时第一行在 `<thead>` 用 `<th>`，其余在 `<tbody>` 用 `<td>`
|
||||
- 合并单元格仅起始格输出 `colspan` / `rowspan`，被合并的格不出现
|
||||
|
||||
# 六、美化系统
|
||||
- 颜色优先使用命名色，也可写 `rgb(r,g,b)` / `rgba(r,g,b,a)`。**基础色（7 色）**：red, orange, yellow, green, blue, purple, gray
|
||||
| 属性 | 支持的命名色 |
|
||||
|-|-|
|
||||
| 文字颜色 `<span text-color>` | 基础色 |
|
||||
| 高亮框字色 `<callout text-color>` | 基础色 |
|
||||
| 高亮框边框 `<callout border-color>` | 基础色 |
|
||||
| 文字背景 `<span background-color>` | 基础色 + `light-{色}` + `medium-gray` |
|
||||
| 高亮框填充 `<callout background-color>` | `gray` + `light-{色}` + `medium-{色}` |
|
||||
| 单元格背景 `<th/td background-color>` | 同文字背景 |
|
||||
| 按钮背景 `<button background-color>` | 同文字背景 |
|
||||
- 常用 emoji： 💡(默认)✅❌📝❓❗👍❤️📌🏁⭐
|
||||
|
||||
# 七、**重要规则**
|
||||
## 转义规则：标签本身 **禁止转义**，只有标签内部的文本内容才需要转义
|
||||
|
||||
**错误** ❌：`<p>内容</p>`（把标签也转义了）
|
||||
**正确** ✅：`<p>A & B 的对比：1 < 2</p>`（标签保持原样，文本中的 `&` 和 `<` 才转义）
|
||||
|
||||
转义字符表：
|
||||
- `<` → `<`
|
||||
- `>` → `>`
|
||||
- `&` → `&`
|
||||
- `\n`（换行符） → `<br/>`
|
||||
|
||||
|
||||
# 八、完整示例
|
||||
|
||||
```xml
|
||||
<title>文档标题</title>
|
||||
|
||||
<h1>一级标题</h1>
|
||||
|
||||
<p><b>加粗文本</b>，<span text-color="green">绿色文本</span></p>
|
||||
|
||||
<callout emoji="💡" background-color="light-yellow" border-color="yellow">
|
||||
<p>高亮框内容，子块仅支持文本/标题/列表/待办/引用</p>
|
||||
</callout>
|
||||
|
||||
<checkbox done="true">已完成事项</checkbox>
|
||||
<checkbox done="false">未完成事项</checkbox>
|
||||
|
||||
<grid>
|
||||
<column width-ratio="0.5">
|
||||
<p>左栏</p>
|
||||
</column>
|
||||
<column width-ratio="0.5">
|
||||
<p>右栏</p>
|
||||
</column>
|
||||
</grid>
|
||||
|
||||
<table>
|
||||
<colgroup><col span="2" width="120"/></colgroup>
|
||||
<thead><tr><th background-color="light-gray">表头</th><th background-color="light-gray">表头</th></tr></thead>
|
||||
<tbody><tr><td>单元格</td><td>单元格</td></tr></tbody>
|
||||
</table>
|
||||
|
||||
<p><cite type="doc" doc-id="DOC_TOKEN"></cite> <cite type="user" user-id="USER_ID"></cite></p>
|
||||
|
||||
<ol><li seq="auto">第一项</li><li seq="auto">第二项</li></ol>
|
||||
|
||||
<p><a type="url-preview" href="https://example.com">链接标题</a></p>
|
||||
|
||||
<p><latex>E = mc^2</latex></p>
|
||||
|
||||
<pre lang="go" caption="示例"><code>fmt.Println("hello")</code></pre>
|
||||
|
||||
<hr/>
|
||||
|
||||
<source name="文件名.pdf"/>
|
||||
<img src="IMG_TOKEN" width="800" height="400" caption="说明" name="图.png"/>
|
||||
<img href="https://example.com/photo.png"/>
|
||||
|
||||
<button action="OpenLink" src="https://example.com">按钮文字</button>
|
||||
|
||||
<time expire-time="1775916000000" notify-time="1775912400000" should-notify="false">时间戳毫秒</time>
|
||||
|
||||
<cite type="citation"><a href="https://example.com">引文标题</a></cite>
|
||||
<bookmark name="书签标题" href="https://example.com"></bookmark>
|
||||
|
||||
<task task-id="TASK_GUID"></task>
|
||||
<chat_card chat-id="CHAT_ID"></chat_card>
|
||||
<sub-page-list></sub-page-list>
|
||||
```
|
||||
@ -0,0 +1,59 @@
|
||||
# 从零创作工作流
|
||||
|
||||
用户提供主题、需求或简要说明，需要生成一份新的飞书文档时，遵循本工作流。
|
||||
|
||||
## 核心方法论 — Code-Act Loop
|
||||
|
||||
通过自适应的 **Code-Act Loop** 驱动文档创作，而非固定模板式的工作流。每次任务都循环执行：
|
||||
|
||||
1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
|
||||
2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
|
||||
3. **Observe（观察）** — 检查命令输出，验证正确性，核查样式是否达标
|
||||
4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
|
||||
|
||||
循环在文档达到质量标准且满足用户需求时结束。不要试图一次性产出完美内容——迭代打磨效果更好。根据用户实际需求灵活决定文档结构和版块，而不是套用固定模板。
|
||||
|
||||
|
||||
## 典型 Code-Act Loop 流程
|
||||
|
||||
### 第一波 — 规划与骨架（串行）
|
||||
|
||||
1. 分析用户需求：受众、目的、范围
|
||||
2. 设计大纲——每个 h1/h2 章节至少规划 1 个非文本 block；承载重要信息的章节优先规划画板
|
||||
3. `docs +create --api-version v2` **只建骨架**：标题 + 开头 `<callout>` + 各级标题 + 每节一句占位摘要
|
||||
- ⚠️ **不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
|
||||
- 完整内容留到第二波，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
|
||||
- ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理。
|
||||
|
||||
### 第二波 — 内容撰写（并行 Agent）
|
||||
|
||||
4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：
|
||||
- 文档 token、负责的章节范围、期望的 block 类型
|
||||
- `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取）
|
||||
- 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容
|
||||
|
||||
### 第三波 — 整合审查 + 画板意图识别（串行）
|
||||
|
||||
5. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
|
||||
6. 评估样式达标（富 block 密度、元素多样性、连续 `<p>` 数量）
|
||||
7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
|
||||
|
||||
### 第四波 — 画板与润色（并行 Agent）
|
||||
|
||||
8. **优先处理第三波识别出的画板需求**：
|
||||
参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
|
||||
9. Spawn 内容改写 Agent 定向润色：
|
||||
- 文字密集章节转为 `<table>`/`<grid>`/`<callout>`
|
||||
- 主要章节间补充 `<hr/>`
|
||||
- 本地图片使用 `docs +media-insert` 插入
|
||||
|
||||
|
||||
## Agent 子任务要求
|
||||
|
||||
内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。
|
||||
|
||||
Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。
|
||||
|
||||
SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
|
||||
|
||||
已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
|
||||
85
.agents/skills/lark-doc/references/style/lark-doc-style.md
Normal file
85
.agents/skills/lark-doc/references/style/lark-doc-style.md
Normal file
@ -0,0 +1,85 @@
|
||||
# 文档样式指南
|
||||
|
||||
创建或编辑文档时，必须遵循本指南，使用结构化 block 提升可读性和视觉层次。
|
||||
|
||||
## 一、核心原则
|
||||
|
||||
1. **结构优于文字**：能用结构化 block 表达的信息，不用纯文本段落
|
||||
2. **Front-load 结论**：文档以 `<callout>` 开头概括核心结论；每章节首段点明要旨
|
||||
3. **视觉节奏**：连续纯文本不超过 3 段；不同主题章节间用 `<hr/>` 分隔
|
||||
4. **风格一致**：同类信息使用同类元素，全篇风格统一
|
||||
5. **重要信息画板化**：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达
|
||||
|
||||
## 二、元素选择指南
|
||||
|
||||
涉及图表需求时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。
|
||||
|
||||
| 场景 | 推荐方案 |
|
||||
|--------------------------------------------|---------------------------------------|
|
||||
| 核心结论 / 摘要 / 注意事项 | `<callout>` + emoji + 背景色 |
|
||||
| 重要方案对比 / 优劣势 / Before vs After | `<grid>` 2 列分栏；SVG SubAgent |
|
||||
| 简短低风险对比 | `<grid>` 2 列分栏 |
|
||||
| 3+ 属性的结构化数据 / 指标表 | `<table>` + 表头背景色 |
|
||||
| 任务清单 / 检查项 | `<checkbox>` |
|
||||
| 代码片段 | `<pre lang="x" caption="说明">` |
|
||||
| 引用 / 公式 | `<blockquote>` / `<latex>` |
|
||||
| 操作入口 / 跳转链接 | `<button>` / `<a type="url-preview">` |
|
||||
| 流程图 / 时间线 / 示意图 / 自定义图形 / 架构图 / 数据图 / 思维导图等 | 画板图表 |
|
||||
|
||||
|
||||
### 画板意图识别
|
||||
|
||||
撰写或审查每个段落/章节时，**必须判断该内容是否适合用图表达**。满足以下任一特征时，应使用画板而非纯文本；如果该内容承载章节核心结论、关键决策或主要论据，即使结构较简单也优先画板化：
|
||||
|
||||
| 内容特征 | 信号词 / 模式 | 推荐画板类型 |
|
||||
|-|-|-|
|
||||
| 多步骤的操作流程或决策路径 | "先…然后…最后"、"步骤 1/2/3"、"如果…则…否则" | 流程图 / 泳道图 |
|
||||
| 系统或模块间的依赖与交互 | "调用"、"依赖"、"上游/下游"、"请求→响应" | 架构图 |
|
||||
| 上下级或从属关系 | "汇报给"、"下属"、"隶属"、"团队结构" | 组织架构图 |
|
||||
| 时间线或阶段演进 | "Q1/Q2"、"里程碑"、"阶段一→阶段二"、日期序列 | 时间线 / 里程碑 |
|
||||
| 因果分析或问题归因 | "根因"、"原因"、"导致"、"影响因素" | 鱼骨图 |
|
||||
| 两个及以上方案/对象的多维度对比 | "vs"、"方案 A/B"、"优劣"、"对比" | 对比图 |
|
||||
| 层级递进或优先级排序 | "基础→进阶→高级"、"L1/L2/L3"、"核心→外围" | 金字塔图 |
|
||||
| 数值趋势或周期变化 | 带数字的时间序列、"增长/下降"、百分比变化 | 折线图 / 柱状图 |
|
||||
| 漏斗或转化率 | "转化率"、"漏斗"、"从…到…留存" | 漏斗图 |
|
||||
| 发散或归纳的思维结构 | "要点"、"维度"、"分支"、多层嵌套列表 | 思维导图 |
|
||||
| 循环或飞轮效应 | "正循环"、"飞轮"、"闭环"、"A 驱动 B 驱动 C" | 飞轮图 |
|
||||
| 占比分布 | "占比"、"份额"、"分布"、百分比加总 ≈100% | 饼图 / 树状图 |
|
||||
|
||||
**判断规则：**
|
||||
- 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本
|
||||
- 低重要度、局部辅助信息才用 `<table>` / `<grid>` / `<callout>` 承载
|
||||
- 确定需要插入哪些图表后，参照 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的方式，插入图表画板。
|
||||
|
||||
## 三、颜色语义
|
||||
|
||||
全篇保持语义一致，同一语义必须使用同一颜色：
|
||||
|
||||
| 语义 | emoji 前缀 | callout 背景色 | 文字色 |
|
||||
|-|-|-|-|
|
||||
| 信息、说明 | ℹ️ "说明：" | `light-blue` | `blue` |
|
||||
| 成功、推荐 | ✅ "推荐：" | `light-green` | `green` |
|
||||
| 警告 / 错误 / 风险 | ⚠️❌ | `light-red` | `red` |
|
||||
| 注意、待确认 | ❗"注意：" | `light-yellow` | `yellow` |
|
||||
| 中性、辅助 | — | `light-gray` | — |
|
||||
|
||||
- 表头统一 `background-color="light-gray"`
|
||||
- 关键指标用 `<span text-color="green/red">` 突出，**必须同时用 ↑↓ 或 +/- 标注方向**（色觉无障碍）
|
||||
|
||||
## 四、排版规范
|
||||
|
||||
- 标题层级 ≤ 4 层，段落单段 ≤ 5 行，列表嵌套 ≤ 2 层，Grid ≤ 3 列
|
||||
- 文档开头用 `<callout>` front-load 结论。
|
||||
|
||||
## 五、丰富度自检
|
||||
|
||||
生成内容后必须自检，**未达标时主动优化**：
|
||||
|
||||
| 指标 | 达标标准 |
|
||||
|-|-|
|
||||
| 富 block 密度 | ≥ 40%（非纯文本 block 数 ÷ 总 block 数） |
|
||||
| 元素多样性 | ≥ 3 种不同 block 类型 |
|
||||
| 连续纯文本 | ≤ 3 段连续 `<p>` |
|
||||
| 章节丰富度 | 每 h1/h2 ≥ 1 个非纯文本 block |
|
||||
| 开头 callout | 必须 |
|
||||
| 视觉节奏 | 不同主题章节间有 `<hr/>` |
|
||||
@ -0,0 +1,55 @@
|
||||
# 改写增强工作流
|
||||
|
||||
用户提供已有文档链接或 token，需要改写、润色、补充或重排版时，遵循本工作流。
|
||||
|
||||
## 核心方法论 — Code-Act Loop
|
||||
通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行：
|
||||
1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
|
||||
2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
|
||||
3. **Observe（观察）** — 检查命令输出，验证正确性，核查样式是否达标
|
||||
4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
|
||||
|
||||
## 核心原则：精准手术优于全量覆盖
|
||||
1. **精准手术**：只改用户指定的 block，不改其他 block。
|
||||
2. **全量覆盖**：如果用户明确要改整篇，才用 `overwrite` 命令。
|
||||
3. **保真约束**：改写时原文里的 `<cite type="user">`（@人）、`<cite type="doc">`（@文档）、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等行内组件和资源块一律原样保留（含所有 token / user-id / doc-id 属性），不许替换成纯文本姓名、链接或占位符。
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 第一波 — 分析 + 画板意图识别（串行）
|
||||
|
||||
1. **选择读取范围**（节省上下文的关键）：
|
||||
- 用户只改某一节 / 文档较大 → 先 `docs +fetch --api-version v2 --scope outline --max-depth 2` 拿目录，再 `docs +fetch --api-version v2 --scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）
|
||||
- 需要精确跨节区间 → `docs +fetch --api-version v2 --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
|
||||
- 用户只给了模糊关键词 → `docs +fetch --api-version v2 --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
|
||||
- 用户明确要改整篇 → `docs +fetch --api-version v2 --detail with-ids`
|
||||
- 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) "意图引导：选择正确的 --scope"
|
||||
2. 系统性评估：结构清晰度、富 block 密度（≥40%）、元素多样性（≥3种）、连续 `<p>` 是否超过 3 段、是否有开头 callout 和章节 `<hr/>`
|
||||
3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
|
||||
4. 向用户简要说明改进计划（包含识别出的画板机会）
|
||||
|
||||
### 第二波 — 定向改写（并行 Agent）
|
||||
|
||||
5. **优先处理第一波识别出的画板候选段落**：
|
||||
参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
|
||||
6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：（见 `lark-doc-style.md`）
|
||||
- 开头适当添加 `<callout>`、重组引言
|
||||
- 纯文本转为 `<grid>`/`<table>`/`<callout>`
|
||||
- 添加低重要度对比分栏、关键提示等富 block；画板类需求只走第 5 步
|
||||
|
||||
### 第三波 — 验证（串行）
|
||||
|
||||
7. 获取更新后文档局部内容，重新检查样式指标
|
||||
8. 未达标则定向修正，向用户呈现结果
|
||||
|
||||
## Agent 子任务要求
|
||||
|
||||
内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。
|
||||
|
||||
Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。
|
||||
|
||||
SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
|
||||
|
||||
已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
|
||||
|
||||
**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --api-version v2 --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。
|
||||
204
.agents/skills/lark-drive/SKILL.md
Normal file
204
.agents/skills/lark-drive/SKILL.md
Normal file
@ -0,0 +1,204 @@
|
||||
---
|
||||
name: lark-drive
|
||||
version: 1.0.0
|
||||
description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli drive --help"
|
||||
---
|
||||
|
||||
# drive (v1)
|
||||
|
||||
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
|
||||
|
||||
> **术语说明：** 飞书云空间也常被称为"云盘"、"云存储"、"网盘"或"我的空间"，这些说法通常指的是同一个产品，是飞书官方的云端文件存储与管理中心。
|
||||
|
||||
> **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
|
||||
|
||||
## 快速决策
|
||||
|
||||
- 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
|
||||
- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
|
||||
- 用户要**根据文档评论定位正文位置**，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（`file_type=docx`）的文档支持通过 `need_relation=true` 返回评论位置，其他类型暂不支持，具体用法需要先阅读 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md) 了解。
|
||||
- 用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，仍按资源类型、URL 路径和 token 路由到本 skill；不要因为域名不是飞书而回退到 WebFetch。
|
||||
- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
|
||||
- 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
|
||||
- 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
|
||||
- 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
|
||||
- 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
|
||||
- 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
|
||||
- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
|
||||
- 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 `lark-cli drive +create-folder`。
|
||||
- 用户要查看某个文件有哪些可下载预览格式，或想下载 PDF / HTML / 文本 / 图片等预览产物，使用 `lark-cli drive +preview`。
|
||||
- 用户要获取某个文件的封面图，优先使用 `lark-cli drive +cover`；先 `--list-only` 看规格，再选 `--spec` 下载。
|
||||
- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
|
||||
- `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
|
||||
- 用户给的是 wiki URL / token，且后续还没明确底层资源类型时，先用 `lark-cli drive +inspect` 解包；`+inspect` 失败后不要自动切到别的写接口继续尝试，先按错误提示处理权限、scope 或链接问题。
|
||||
- `drive +inspect` / `drive +upload` 遇到 `not found`、`permission denied`、`missing scope` 时，默认停止重试；只有 `rate limit` 或临时网络错误才适合有限重试。
|
||||
|
||||
## 修改标题
|
||||
- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
|
||||
|
||||
## 核心概念
|
||||
|
||||
### 文档类型与 Token
|
||||
|
||||
飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 `file_token`。
|
||||
|
||||
### 文档 URL 格式与 Token 处理
|
||||
|
||||
| URL 格式 | 示例 | Token 类型 | 处理方式 |
|
||||
|----------|---------------------------------------------------------|-----------|----------|
|
||||
| `/docx/` | `https://example.larksuite.com/docx/doxcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/doc/` | `https://example.larksuite.com/doc/doccnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/wiki/` | `https://example.larksuite.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | 不能直接当底层 `file_token`；优先用 `drive +inspect` 解包获取 `obj_token` |
|
||||
| `/sheets/` | `https://example.larksuite.com/sheets/shtcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/drive/folder/` | `https://example.larksuite.com/drive/folder/fldcnxxxx` | `folder_token` | URL 路径中的 token 作为文件夹 token 使用 |
|
||||
|
||||
### Wiki 链接特殊处理
|
||||
|
||||
```bash
|
||||
lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
|
||||
```
|
||||
|
||||
知识库链接背后可能是 docx、sheet、bitable、slides、file 等不同对象。后续要做评论、下载、导出或内容读取时，优先用 `drive +inspect` 拿到 `type`、`token`、`title`、`url`；完整手动解析和跨 skill 路由见共享文档 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。不要只根据 `/wiki/<token>` 猜底层类型。
|
||||
|
||||
### 常见操作 Token 需求
|
||||
|
||||
| 操作 | 需要的 Token | 说明 |
|
||||
|------|-------------|------|
|
||||
| 读取文档内容 | `file_token` / 通过 `docs +fetch --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL |
|
||||
| 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block_id，`sheet` 使用 `<sheetId>!<cell>`，`slides` 使用 `<slide-block-type>!<xml-id>`，且都支持最终解析到对应类型的 wiki URL；Drive file 不支持局部评论 |
|
||||
| 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL |
|
||||
| 下载文件 | `file_token` | 从文件 URL 中直接提取 |
|
||||
| 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token |
|
||||
| 列出文档评论 | `file_token` | 同添加评论 |
|
||||
|
||||
### 评论能力入口
|
||||
|
||||
- 添加评论优先使用 [`+add-comment`](references/lark-drive-add-comment.md)：review / 审阅 / 校对场景默认尽量创建局部评论，不要把多个可定位问题合并为一条全文评论。
|
||||
- 评论查询、统计、排序、回复限制，先读 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。
|
||||
- 需要根据评论定位正文位置时，先确认目标是 `file_type=docx`，再读 [`lark-drive-comment-location.md`](references/lark-drive-comment-location.md)；其他文档类型暂不支持返回定位字段。
|
||||
- reaction / 表情相关操作先读 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)；只有用户明确需要 reaction 信息时才带 `need_reaction=true`。
|
||||
|
||||
### 典型错误与解决方案
|
||||
|
||||
| 错误信息 | 原因 | 解决方案 |
|
||||
|----------|------|----------|
|
||||
| `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
|
||||
| `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
|
||||
| `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides） |
|
||||
|
||||
### 权限能力入口
|
||||
|
||||
- 用户要管理 Drive 文档/文件协作者、公开权限、授权当前应用访问文档，或处理 `permission.public.patch` 的 `91009` / `91010` / `91011` / `91012` 错误时，先读 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
|
||||
- 用户只是没有访问权限并希望向 owner 申请访问，优先使用 [`+apply-permission`](references/lark-drive-apply-permission.md)。
|
||||
- 普通 scope、身份或登录问题仍按 [`lark-shared`](../lark-shared/SKILL.md) 处理；不要把租户安全策略、对外分享、密级拦截简单归类为缺 scope。
|
||||
|
||||
## 不在本 skill 范围
|
||||
|
||||
- 文档正文读取、总结、创建、编辑、图片/附件插入或下载：使用 [`lark-doc`](../lark-doc/SKILL.md)。
|
||||
- 电子表格单元格、筛选、公式、样式等表内操作：使用 [`lark-sheets`](../lark-sheets/SKILL.md)。
|
||||
- Base / 多维表格内部的表、字段、记录、视图、仪表盘等操作：使用 [`lark-base`](../lark-base/SKILL.md)。
|
||||
- 知识空间、Wiki 节点层级、空间成员管理：使用 [`lark-wiki`](../lark-wiki/SKILL.md)；上传本地文件到 wiki 节点仍用 `drive +upload --wiki-token`。
|
||||
- 原生 Markdown 文件读取、写入、patch、diff：使用 [`lark-markdown`](../lark-markdown/SKILL.md)；把 Markdown 导入成在线 docx 才用 `drive +import --type docx`。
|
||||
|
||||
## Shortcuts（推荐优先使用）
|
||||
|
||||
Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）。有 Shortcut 的操作优先使用。
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|----------|
|
||||
| [`+search`](references/lark-drive-search.md) | 搜索文档、Wiki、表格、文件夹等云空间对象；支持 `--edited-since`、`--mine`、`--doc-types` 等扁平 flag。 |
|
||||
| [`+upload`](references/lark-drive-upload.md) | 上传本地文件到 Drive 文件夹或 wiki 节点。 |
|
||||
| [`+create-folder`](references/lark-drive-create-folder.md) | 新建 Drive 文件夹，支持父文件夹与 bot 创建后自动授权。 |
|
||||
| [`+download`](references/lark-drive-download.md) | 下载 Drive 文件到本地。 |
|
||||
| [`+preview`](references/lark-drive-preview.md) | 查看或下载文件的 PDF / HTML / 文本 / 图片等预览产物。 |
|
||||
| [`+cover`](references/lark-drive-cover.md) | 查看或下载文件封面图规格。 |
|
||||
| [`+status`](references/lark-drive-status.md) | 比较本地目录与 Drive 文件夹差异；默认按 SHA-256 精确比较，`--quick` 使用修改时间近似比较。 |
|
||||
| [`+pull`](references/lark-drive-pull.md) | 从 Drive 拉取文件到本地目录，支持重复远端路径处理和增量模式。 |
|
||||
| `+sync` | 双向同步本地目录与 Drive 文件夹：拉取 `new_remote`、推送 `new_local`，`modified` 按 `--on-conflict=remote-wins\|local-wins\|keep-both\|ask` 处理；`--quick` 用修改时间近似比较；`--on-duplicate-remote` 支持 `fail` / `newest` / `oldest`；只同步 `type=file`，跳过在线文档和 shortcut，且不会删除两端多余文件。 |
|
||||
| [`+push`](references/lark-drive-push.md) | 将本地目录推送到 Drive 文件夹，支持 skip / smart / overwrite 与确认后删除远端。 |
|
||||
| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | 在另一个文件夹里创建现有 Drive 文件的快捷方式。 |
|
||||
| [`+add-comment`](references/lark-drive-add-comment.md) | 给 doc/docx/file/sheet/slides 添加评论；评论统计、回复和 reaction 细则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。 |
|
||||
| [`+export`](references/lark-drive-export.md) | 将 doc/docx/sheet/bitable/slides 导出为本地文件。 |
|
||||
| [`+export-download`](references/lark-drive-export-download.md) | 根据导出产物的 file_token 下载文件。 |
|
||||
| [`+import`](references/lark-drive-import.md) | 将本地文件导入为飞书在线文档、表格、多维表格或幻灯片。 |
|
||||
| [`+version-history`](references/lark-drive-version-history.md) | 查看文件历史版本。 |
|
||||
| [`+version-get`](references/lark-drive-version-get.md) | 下载指定历史版本。 |
|
||||
| [`+version-revert`](references/lark-drive-version-revert.md) | 回滚到指定历史版本。 |
|
||||
| [`+version-delete`](references/lark-drive-version-delete.md) | 删除指定历史版本。 |
|
||||
| [`+move`](references/lark-drive-move.md) | 移动 Drive 文件或文件夹；Wiki 层级移动走 `lark-wiki`。 |
|
||||
| [`+delete`](references/lark-drive-delete.md) | 删除 Drive 文件或文件夹，文件夹删除会轮询异步任务。 |
|
||||
| [`+task_result`](references/lark-drive-task-result.md) | 查询 import/export/move/delete 等异步任务结果。 |
|
||||
| [`+inspect`](references/lark-drive-inspect.md) | 检视 URL 的类型、标题和 canonical token；wiki URL 会自动解包到底层文档。 |
|
||||
| [`+apply-permission`](references/lark-drive-apply-permission.md) | 以 user 身份向文档 owner 申请访问权限。 |
|
||||
| [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签。 |
|
||||
| [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档的密级标签。 |
|
||||
|
||||
## API Resources
|
||||
|
||||
```bash
|
||||
lark-cli schema drive.<resource>.<method> # 调用 API 前必须先查看参数结构
|
||||
lark-cli drive <resource> <method> [flags] # 调用 API
|
||||
```
|
||||
|
||||
> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
|
||||
>
|
||||
> **高频原生命令：** 读取 Drive 文件夹清单时使用 `drive files list`，必须按 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md) 的模板通过 `--params` 传 `folder_token` / `page_token`，并手动处理分页；不要把 `--page-all` 输出直接交给 JSON 解析脚本。
|
||||
|
||||
### files
|
||||
|
||||
- `copy` — 复制文件
|
||||
- `create_folder` — 新建文件夹
|
||||
- `list` — 获取文件夹下的清单；使用前阅读 [`references/lark-drive-files-list.md`](references/lark-drive-files-list.md)
|
||||
- `patch` — 修改文件标题
|
||||
|
||||
### file.comments
|
||||
|
||||
- `batch_query` — 批量获取评论
|
||||
- `create_v2` — 添加全文/局部（划词）评论
|
||||
- `list` — 分页获取文档评论
|
||||
- `patch` — 解决/恢复 评论
|
||||
|
||||
### file.comment.replys
|
||||
|
||||
- `create` — 添加回复
|
||||
- `delete` — 删除回复
|
||||
- `list` — 获取回复
|
||||
- `update` — 更新回复
|
||||
|
||||
### permission.members
|
||||
|
||||
- `auth` —
|
||||
- `create` — 增加协作者权限
|
||||
- `transfer_owner` —
|
||||
|
||||
### metas
|
||||
|
||||
- `batch_query` — 获取文档元数据
|
||||
|
||||
### user
|
||||
|
||||
- `remove_subscription` — 取消订阅用户、应用维度事件
|
||||
- `subscription` — 订阅用户、应用维度事件（本次开放评论添加事件）
|
||||
- `subscription_status` — 查询用户、应用对指定事件的订阅状态
|
||||
|
||||
### file.statistics
|
||||
|
||||
- `get` — 获取文件统计信息
|
||||
|
||||
### file.view_records
|
||||
|
||||
- `list` — 获取文档的访问者记录
|
||||
|
||||
### file.comment.reply.reactions
|
||||
|
||||
- `update_reaction` — 添加/删除 reaction
|
||||
|
||||
### quota_details
|
||||
|
||||
- `get` — 获取当前用户的容量信息，包含各业务使用量、租户配额是否超限、用户配额、所在部门配额
|
||||
- 仅支持 `--as user`，不要使用默认的 bot 身份
|
||||
- `quota_detail_id` 传当前用户的 `user_id`
|
||||
182
.agents/skills/lark-drive/references/lark-drive-add-comment.md
Normal file
182
.agents/skills/lark-drive/references/lark-drive-add-comment.md
Normal file
@ -0,0 +1,182 @@
|
||||
|
||||
# drive +add-comment
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
给文档、受支持的 Drive 普通文件、电子表格或飞书幻灯片添加评论。底层统一走 `/open-apis/drive/v1/files/:file_token/new_comments`（`create_v2`）接口；未指定位置时省略 `anchor` 创建全文评论，指定 `--block-id` 时传入 `anchor.block_id` 创建局部评论。支持直接传 docx URL/token、旧版 doc URL（仅全文评论）、Drive file URL/token（**仅支持白名单扩展名，且只支持全文评论**）、sheet URL、slides URL，也支持传最终可解析为 doc/docx/file/sheet/slides 的 wiki URL。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 默认：未指定位置时添加全文评论
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/docx/<DOC_ID>" \
|
||||
--content '[{"type":"text","text":"请补充发布说明"}]'
|
||||
|
||||
# 也可以显式指定为全文评论；旧版 doc URL 仅支持全文评论
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/doc/<DOC_ID>" \
|
||||
--full-comment \
|
||||
--content '[{"type":"text","text":"请补充旧版文档的背景信息"}]'
|
||||
|
||||
# wiki 链接也可以，shortcut 会先解析到真实 doc/docx token
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
|
||||
--content '[{"type":"text","text":"这里需要一段全文评论"}]'
|
||||
|
||||
# 给受支持的 Drive 普通文件添加全文评论
|
||||
# 注意：CLI 会先查询 drive metas，只有白名单扩展名才允许评论
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/file/<FILE_TOKEN>" \
|
||||
--content '[{"type":"text","text":"请补充文件说明"}]'
|
||||
|
||||
# 裸 token 也支持，但必须显式声明 --type file
|
||||
lark-cli drive +add-comment \
|
||||
--doc "<FILE_TOKEN>" --type file \
|
||||
--content '[{"type":"text","text":"请补充目录说明"}]'
|
||||
|
||||
# 给 docx 文档的指定 block 添加局部评论（block_id 可通过 docs +fetch --api-version v2 --detail with-ids 获取）
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/docx/<DOC_ID>" \
|
||||
--block-id "<BLOCK_ID>" \
|
||||
--content '[{"type":"text","text":"请补充流程说明"}]'
|
||||
|
||||
# wiki 链接也支持局部评论；解析结果可以是 docx/sheet/slides，block-id 格式按目标类型传
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
|
||||
--block-id "<BLOCK_ID>" \
|
||||
--content '[{"type":"text","text":"请补充更细的开发步骤"}]'
|
||||
|
||||
# 组合文本、@用户、链接元素
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/docx/<DOC_ID>" \
|
||||
--block-id "<BLOCK_ID>" \
|
||||
--content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理，参考 "},{"type":"link","text":"https://example.com"}]'
|
||||
|
||||
# 给电子表格单元格添加评论（--block-id 格式为 <sheetId>!<cell>）
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/sheets/<SHEET_TOKEN>" \
|
||||
--block-id "<SHEET_ID>!D6" \
|
||||
--content '[{"type":"text","text":"请检查此单元格数据"}]'
|
||||
|
||||
# wiki 链接指向的 sheet 也支持
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
|
||||
--block-id "<SHEET_ID>!A1" \
|
||||
--content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 确认"}]'
|
||||
|
||||
# 给幻灯片元素添加评论（--block-id 格式为 <slide-block-type>!<xml-id>）
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
|
||||
--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
|
||||
--content '[{"type":"text","text":"请调整这个元素的位置"}]'
|
||||
|
||||
# 例如：给整页 slide 添加评论
|
||||
# <slide id="pkk"> ... </slide> => --block-id slide!pkk
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
|
||||
--block-id "slide!pkk" \
|
||||
--content '[{"type":"text","text":"这一页需要补充过渡说明"}]'
|
||||
|
||||
# 例如：给图片元素添加评论
|
||||
# <img id="bPk" ... /> => --block-id img!bPk
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
|
||||
--block-id "img!bPk" \
|
||||
--content '[{"type":"text","text":"这张图片建议换成更清晰的版本"}]'
|
||||
|
||||
# 例如：给文本 shape 添加评论
|
||||
# <shape type="text" id="bPq"> ... </shape> => --block-id shape!bPq
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/slides/<PRESENTATION_ID>" \
|
||||
--block-id "shape!bPq" \
|
||||
--content '[{"type":"text","text":"这段文案可以再精简"}]'
|
||||
|
||||
# wiki 链接指向的 slides 也支持
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/wiki/<WIKI_TOKEN>" \
|
||||
--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
|
||||
--content '[{"type":"text","text":"这里需要补充说明"}]'
|
||||
|
||||
# 传裸 token 时需要 --type 指定文档类型
|
||||
lark-cli drive +add-comment \
|
||||
--doc "<SHEET_TOKEN>" --type sheet \
|
||||
--block-id "<SHEET_ID>!D6" \
|
||||
--content '[{"type":"text","text":"请检查"}]'
|
||||
|
||||
lark-cli drive +add-comment \
|
||||
--doc "<DOCX_TOKEN>" --type docx \
|
||||
--content '[{"type":"text","text":"全文评论"}]'
|
||||
|
||||
# 裸 token + 已知 block_id 的局部评论
|
||||
lark-cli drive +add-comment \
|
||||
--doc "<PRESENTATION_ID>" --type slides \
|
||||
--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>" \
|
||||
--content '[{"type":"text","text":"slide block comment"}]'
|
||||
|
||||
# 裸 token + 已知 block_id 的局部评论
|
||||
lark-cli drive +add-comment \
|
||||
--doc "<DOCX_TOKEN>" --type docx \
|
||||
--block-id "<BLOCK_ID>" \
|
||||
--content '[{"type":"text","text":"请 "},{"type":"mention_user","text":"ou_xxx"},{"type":"text","text":" 处理，参考 "},{"type":"link","text":"https://example.com"}]'
|
||||
|
||||
# 如果需要更底层的原生 API，也可以直接调用 V2 协议
|
||||
lark-cli schema drive.file.comments.create_v2
|
||||
|
||||
lark-cli drive file.comments create_v2 \
|
||||
--params '{"file_token":"<DOC_TOKEN>"}' \
|
||||
--data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'
|
||||
|
||||
# 预览底层调用链
|
||||
lark-cli drive +add-comment \
|
||||
--doc "https://example.larksuite.com/docx/<DOC_ID>" \
|
||||
--block-id "<BLOCK_ID>" \
|
||||
--content '[{"type":"text","text":"请补充流程说明"}]' \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--doc` | 是 | 文档 URL / token、file / sheet / slides URL，或可解析到 `doc`/`docx`/`file`/`sheet`/`slides` 的 wiki URL |
|
||||
| `--type` | 裸 token 时必填 | 文档类型：`doc`、`docx`、`file`、`sheet`、`slides`。URL 输入时自动识别，无需传 |
|
||||
| `--content` | 是 | `reply_elements` JSON 数组字符串。示例：`'[{"type":"text","text":"文本"},{"type":"mention_user","text":"ou_xxx"},{"type":"link","text":"https://example.com"}]'` |
|
||||
| `--full-comment` | 否 | 显式指定创建全文评论；未传 `--block-id` 时也会默认走全文评论（不适用于 sheet） |
|
||||
| `--block-id` | 局部评论时必填 | 目标块 ID，可通过 `docs +fetch --api-version v2 --detail with-ids` 获取。**Sheet 评论**：格式为 `<sheetId>!<cell>`（如 `a281f9!D6`） |
|
||||
|
||||
## 行为说明
|
||||
|
||||
- **局部评论需要先获取 block ID**：先调用 `docs +fetch --api-version v2 --doc <TOKEN> --detail with-ids` 获取带有 block ID 的文档内容，然后使用 `--block-id` 指定目标块。
|
||||
- **Review 场景优先局部评论**：审阅、校对、逐条指出问题时，必须先尝试定位到具体 block / 单元格 / slide 元素，并逐问题创建局部评论；不要把所有问题合并成一条全文评论。
|
||||
- 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终可解析为 `doc`/`docx`/`file` 的 wiki URL。
|
||||
- **Drive file 评论**：仅支持白名单扩展名的普通文件。当前支持：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。
|
||||
- **Drive file 暂不支持**：`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件会被 CLI 拒绝，并提示“当前还不支持这种类型的评论”。这些类型虽然可能接受 OpenAPI 请求，但在页面评论展示上存在问题。
|
||||
- **Drive file 只支持全文评论**：file 目标不支持局部评论，不允许传 `--block-id` 或 `--selection-with-ellipsis`。由于当前 OpenAPI 要求 file 评论传入非空 `anchor.block_id`，CLI 会固定传占位值 `test`，UI 上仍表现为文件全文评论。
|
||||
- 传 `--block-id` 时，shortcut 创建**局部评论（划词评论）**；该模式支持 `docx`、`sheet`、`slides`，以及最终可解析为这些类型的 wiki URL。
|
||||
- **Sheet 评论**：当 `--doc` 为 sheet URL 或 wiki 解析为 sheet 时，使用 `--block-id "<sheetId>!<cell>"` 指定单元格（如 `a281f9!D6`）；sheet 没有全文评论，`--full-comment` 不可用。
|
||||
- **Slide 评论**：当 `--doc` 为 slides URL、`--type slides`，或 wiki 解析为 slides 时，必须传 `--block-id "<SLIDE_BLOCK_TYPE>!<XML_ELEMENT_ID>"`。CLI 会将其拆分映射到 `anchor.block_id` / `anchor.slide_block_type`。此时 `--full-comment` 和 `--selection-with-ellipsis` 不可用。
|
||||
- **Slide 参数映射示例**：`--block-id` 由 PPT XML 元素类型和元素 `id` 组成。例如：
|
||||
- `<slide id="pkk">` 对应 `--block-id slide!pkk`，表示给整页评论。
|
||||
- `<img id="bPk" ... />` 对应 `--block-id img!bPk`，表示给图片元素评论。
|
||||
- `<shape type="text" id="bPq">...</shape>` 对应 `--block-id shape!bPq`，表示给文本 shape 评论。
|
||||
|
||||
- `--content` 接收结构化评论元素数组；`type` 支持 `text`、`mention_user`、`link`。为便于书写，`mention_user` / `link` 元素可以直接把用户 ID 或链接地址放在 `text` 字段中，shortcut 会转换成 OpenAPI 所需字段。
|
||||
- `type=text` 的评论文本不能直接包含 `<`、`>`；应优先传 `<`、`>`。shortcut 在发送前也会自动将 `<`、`>` 转义为 `<`、`>` 作为兜底。
|
||||
- **所有 `type=text` 元素的字符总和 ≤ 10000**（按字符算，中英文 / 符号一视同仁）。超过会被 shortcut 在发送前拒绝，并指出累计超长的元素。**拆成多个 text element 不能绕过这个上限**——上限是总额，不是每元素。需要更长内容就缩短或拆成多条评论。
|
||||
- 长度限制只对 `type=text` 生效，`mention_user` / `link` 不计入。
|
||||
- 写入评论前会自动生成符合 OpenAPI 定义的请求体：
|
||||
- 统一接口：`POST /new_comments`
|
||||
- 统一字段：`file_type` + `reply_elements`
|
||||
- 全文评论：省略 `anchor`
|
||||
- 局部评论：传入 `anchor.block_id`
|
||||
- `--dry-run` 仅预览调用链和请求体，不会实际写入。
|
||||
- 如果需要更底层的控制，仍可改用 `lark-cli schema drive.file.comments.create_v2` + `lark-cli drive file.comments create_v2`。
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作** —— 执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,77 @@
|
||||
|
||||
# drive +apply-permission（申请文档权限）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
本 skill 对应 shortcut：`lark-cli drive +apply-permission`。
|
||||
|
||||
向云文档 **Owner** 发起 `view` 或 `edit` 权限申请。申请会以卡片形式推送给 Owner，由 Owner 决定是否通过。
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作** —— 会给 Owner 发推送通知，不要批量或自动化调用。可以先用 `--dry-run` 预览。
|
||||
|
||||
## 身份要求
|
||||
|
||||
- **仅支持 `user` 身份**（使用 `user_access_token`），不支持 `bot` / `tenant_access_token`；shortcut 已在 `AuthTypes` 中强制限定为 `user`，使用 bot 会被拒。
|
||||
- 所需 scope：`docs:permission.member:apply`（若用户缺权限会走统一的 permission 错误路径）。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 通过 URL 申请（type 自动从 URL 推断）
|
||||
lark-cli drive +apply-permission \
|
||||
--token "https://example.larksuite.com/docx/doxcnxxxxxxxxx" \
|
||||
--perm view \
|
||||
--remark "安全评估：需查看需求文档内容" --as user
|
||||
|
||||
# 通过 bare token + 显式 --type
|
||||
lark-cli drive +apply-permission \
|
||||
--token "doxcnxxxxxxxxx" --type docx \
|
||||
--perm edit --as user
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--token` | 是 | 目标文档 token 或完整 URL（`/docx/`、`/sheets/`、`/base/`、`/bitable/`、`/file/`、`/wiki/`、`/doc/`、`/mindnote/`、`/slides/` 路径里的 token 会被自动提取） |
|
||||
| `--type` | 否 | 目标类型，可选值 `doc` / `sheet` / `file` / `wiki` / `bitable` / `docx` / `mindnote` / `slides`。传 URL 时可由 shortcut 自动推断；bare token 必须显式传 |
|
||||
| `--perm` | 是 | 申请的权限，仅支持 `view` 或 `edit`（**不支持 `full_access`**，CLI 侧会直接拒绝） |
|
||||
| `--remark` | 否 | 备注，会显示在权限申请卡片上 |
|
||||
| `--dry-run` | 否 | 仅打印请求内容，不实际发送 |
|
||||
|
||||
## 输出
|
||||
|
||||
API 成功时返回空 `data`（仅 `code: 0, msg: "success"`），对应 CLI 输出：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "user",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
## 频率限制
|
||||
|
||||
- **应用级**：每应用每租户每分钟最多 10 次。
|
||||
- **用户级**：同一用户对**同一篇文档**一天不超过 5 次。
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误码 | 含义 | CLI 处理 |
|
||||
|---|---|---|
|
||||
| `1063006` | 申请次数已达上限（5 次/日） | CLI 自动加 hint：`permission-apply quota reached: each user may request access on the same document at most 5 times per day` |
|
||||
| `1063007` | 当前文档无法申请（如：文档禁用外部申请、申请者已拥有对应权限、目标类型不支持 apply） | CLI 自动加 hint：`this document does not accept a permission-apply request ... contact the owner directly` |
|
||||
| `1063002` | 无操作权限（如该租户关闭了外部申请） | 由统一 permission 错误路径处理 |
|
||||
| `1063004` | 用户所在组织无分享权限 | 由统一 permission 错误路径处理 |
|
||||
| `1063005` | 资源已删除 | 需要确认目标文档/节点是否仍存在 |
|
||||
| `1066001/1066002` | 服务端异常 / 并发冲突 | 稍后重试 |
|
||||
|
||||
## 与 wiki URL 的关系
|
||||
|
||||
传入 `/wiki/<node_token>` 时，shortcut 会直接用 `node_token` 作为路径参数并以 `type=wiki` 调用接口。如果需要先把 wiki 节点解析成 `obj_token`（例如想显式对底层 docx 申请），自行先调 `wiki spaces get_node` 拿 `obj_token + obj_type`，再用 bare token + `--type docx` 调本命令。
|
||||
|
||||
## 参考
|
||||
|
||||
- OpenAPI 端点：`POST /open-apis/drive/v1/permissions/:token/members/apply`
|
||||
@ -0,0 +1,193 @@
|
||||
# 文档评论定位字段
|
||||
|
||||
当用户需要根据评论定位文档正文位置、对文档做 review、区分多处相同引用文本，或把评论落点映射到 `docs +fetch --detail with-ids` 的内容时，docx 文档的评论查询必须带 `need_relation=true`。
|
||||
|
||||
## 适用范围
|
||||
|
||||
- 当前只有 `file_type=docx` 支持通过 `need_relation=true` 查询评论的位置，并返回可用于定位正文 block 的 `relation`、`parent_type`、`parent_token` 等字段。
|
||||
- 其他文件类型暂不支持通过 `need_relation` 查询评论位置。遇到 sheet、bitable、slides、普通文件等类型的评论时，不要承诺可以用 `need_relation` 精确定位正文位置，应退回普通评论字段、对应资源能力下钻或人工确认。
|
||||
|
||||
## 调用方式
|
||||
|
||||
分页列出评论时，把 `need_relation` 放在 query params：
|
||||
|
||||
```bash
|
||||
lark-cli drive file.comments list \
|
||||
--params '{"file_token":"<doc_token>","file_type":"docx","is_solved":false,"need_relation":true}'
|
||||
```
|
||||
|
||||
已知评论 ID 批量查询时，把 `need_relation` 放在请求体里：
|
||||
|
||||
```bash
|
||||
lark-cli drive file.comments batch_query \
|
||||
--params '{"file_token":"<doc_token>","file_type":"docx"}' \
|
||||
--data '{"comment_ids":["<comment_id>"],"need_relation":true}'
|
||||
```
|
||||
|
||||
同时获取文档内容，并要求返回 block id：
|
||||
|
||||
```bash
|
||||
lark-cli docs +fetch --api-version v2 --doc '<doc_token_or_url>' --detail with-ids
|
||||
```
|
||||
|
||||
## 字段含义
|
||||
|
||||
- `relation`：评论在文档内容中的结构化位置。`relation.relation` 是一个 JSON 字符串，需要再解析一次；其中 `positionInfo.blockID` 是最关键字段，用于匹配 `docs +fetch --detail with-ids` 返回的文档 block。
|
||||
- `relation.content_deleted`：评论引用的内容是否已被删除。为 `true` 时，不要假设还能在当前正文中找到原位置。
|
||||
- `parent_type`：评论所在的父级嵌入资源类型。常见值包括 `SHEET_BLOCK`、`BITABLE_BLOCK`、`WHITEBOARD_BLOCK`，表示评论落在文档内嵌电子表格、多维表格或画板内部。
|
||||
- `parent_token`：父级嵌入资源 token。对 sheet / bitable / whiteboard 内部评论，服务端可能无法给出内部单元格、记录或画板节点的文档 block 级 `relation`，但可以通过 `parent_type` + `parent_token` 定位到文档里的父级嵌入 block。
|
||||
|
||||
## 准确度分级
|
||||
|
||||
输出定位结论时，必须区分以下三类，不要把弱推断说成精确定位：
|
||||
|
||||
| 等级 | 判定条件 | 输出口径 |
|
||||
|---|---|---|
|
||||
| `relation 精确` | `relation.relation` 中有 `positionInfo.blockID`，且能在 `docs +fetch --detail with-ids` 中匹配到同一 block | 可说“准确定位到 block” |
|
||||
| `父级资源精确，内部需下钻` | 只有父级嵌入资源的 `blockID` / `parent_type` / `parent_token`，或内部资源的 `positionInfo` 为空 | 可说“准确定位到嵌入资源；内部单元格/记录/节点需用对应 skill 下钻确认” |
|
||||
| `弱匹配/推断` | 只能依赖 `quote`、序号、当前展示顺序或文本搜索 | 必须标明“推断”，说明歧义来源和需要的补充信息 |
|
||||
|
||||
## 返回示例
|
||||
|
||||
普通 docx block 上的评论会返回 `relation`。注意 `relation.relation` 本身是字符串，需要再 JSON parse 一次：
|
||||
|
||||
```json
|
||||
{
|
||||
"comment_id": "7646774324967295982",
|
||||
"quote": "code2",
|
||||
"relation": {
|
||||
"content_deleted": false,
|
||||
"relation": "{\"22-doc_token_xxx\":{\"objType\":22,\"index\":2,\"objVersion\":10,\"positionInfo\":{\"blockID\":\"block_id_xxx\"}}}"
|
||||
},
|
||||
"parent_type": null,
|
||||
"parent_token": null
|
||||
}
|
||||
```
|
||||
|
||||
把 `relation.relation` 再解析后，取 `positionInfo.blockID`：
|
||||
|
||||
```json
|
||||
{
|
||||
"22-doc_token_xxx": {
|
||||
"objType": 22,
|
||||
"index": 2,
|
||||
"objVersion": 10,
|
||||
"positionInfo": {
|
||||
"blockID": "block_id_xxx"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
然后在 `docs +fetch --detail with-ids` 的结果里查找同一个 block id，例如：
|
||||
|
||||
```json
|
||||
{
|
||||
"block_id": "block_id_xxx",
|
||||
"block_type": "code",
|
||||
"text": "code1\ncode2"
|
||||
}
|
||||
```
|
||||
|
||||
嵌入 sheet / bitable / whiteboard 内部评论可能没有可用 `relation`，但会返回父级标记：
|
||||
|
||||
```json
|
||||
{
|
||||
"comment_id": "7646775036988148672",
|
||||
"quote": "记录 2",
|
||||
"relation": null,
|
||||
"parent_type": "BITABLE_BLOCK",
|
||||
"parent_token": "bitable_app_token_xxx_table_id_xxx"
|
||||
}
|
||||
```
|
||||
|
||||
这种情况下，用 `parent_type` 判断目标是嵌入资源，再用 `parent_token` 匹配 `docs +fetch --detail with-ids` 中的 bitable / sheet block。定位粒度是文档里的父级嵌入 block，不是内部记录、字段或单元格。
|
||||
|
||||
画板内部评论的返回形态类似：
|
||||
|
||||
```json
|
||||
{
|
||||
"comment_id": "7646775036988148673",
|
||||
"quote": "画板节点文本",
|
||||
"relation": null,
|
||||
"parent_type": "WHITEBOARD_BLOCK",
|
||||
"parent_token": "whiteboard_token_xxx"
|
||||
}
|
||||
```
|
||||
|
||||
此时 `parent_token` 对应 `docs +fetch --detail with-ids` 结果中 `<whiteboard>` 的 `token` 属性，例如：
|
||||
|
||||
```xml
|
||||
<whiteboard id="whiteboard_block_id_xxx" token="whiteboard_token_xxx"></whiteboard>
|
||||
```
|
||||
|
||||
匹配到这个 `<whiteboard>` 后，`id` 就是文档正文里的父级画板 block id。定位粒度是文档里的画板 block；如果需要继续定位到画板内部具体节点，需要再用画板能力读取画板内部结构。
|
||||
|
||||
## 定位流程
|
||||
|
||||
1. 确认目标是 `file_type=docx`；只有 docx 文档支持通过 `need_relation` 查询评论位置。
|
||||
2. 用 `drive file.comments list` 或 `drive file.comments batch_query` 获取评论，并带 `need_relation=true`。
|
||||
3. 用 `docs +fetch --api-version v2 --detail with-ids` 获取文档内容。
|
||||
4. 对每条评论先看 `relation`：
|
||||
- 如果存在 `relation.relation`，解析这个 JSON 字符串。
|
||||
- 从解析结果里取 `positionInfo.blockID`。
|
||||
- 在 `docs +fetch` 结果中查找相同 block id，这就是评论对应的文档 block。
|
||||
5. 如果没有可用 `relation`，但有 `parent_type` 和 `parent_token`：
|
||||
- `SHEET_BLOCK`：定位到文档中的 sheet 嵌入 block；`parent_token` 通常包含 sheet token 和 sheet id，必要时取 `_` 前的 token 与文档 block 的嵌入资源 token 对比。
|
||||
- `BITABLE_BLOCK`：定位到文档中的 bitable 嵌入 block；`parent_token` 通常包含 bitable app token 和 table id，必要时取 `_` 前的 token 与文档 block 的嵌入资源 token 对比。
|
||||
- `WHITEBOARD_BLOCK`：定位到文档中的 whiteboard 嵌入 block；`parent_token` 对应 `docs +fetch --detail with-ids` 中 `<whiteboard>` 的 `token` 属性。
|
||||
- 这种场景能定位到父级嵌入 block，但通常不能仅凭评论接口定位到嵌入资源内部的具体单元格、字段、记录或画板节点。
|
||||
6. 只有在 `relation`、`parent_type`、`parent_token` 都缺失时，才退回使用 `quote` 文本做弱匹配；`quote` 是评论接口返回的引用文本字段。弱匹配不能区分多处相同文本。
|
||||
|
||||
## 嵌入资源内部定位
|
||||
|
||||
### Sheet 内部评论
|
||||
|
||||
- `parent_token` 常见格式是 `<spreadsheet_token>_<sheet_id>`；也可能在 `relation.relation` 中看到 `subToken` 为 `3-<spreadsheet_token>`。
|
||||
- 评论接口通常只把 `positionInfo.blockID` 指到文档里的 `<sheet>` block，内部 sheet 的 `positionInfo` 可能为空。
|
||||
- 如果 `quote` 是 `C3`、`A1` 这类单元格坐标，可拆出 `spreadsheet_token` / `sheet_id` 后用 `lark-sheets` 读取该单元格确认：
|
||||
|
||||
```bash
|
||||
lark-cli sheets +read \
|
||||
--spreadsheet-token '<spreadsheet_token>' \
|
||||
--sheet-id '<sheet_id>' \
|
||||
--range '<cell>'
|
||||
```
|
||||
|
||||
- 准确度口径：父级 sheet block 可由 relation/parent token 精确定位；单元格坐标若只来自 `quote`，应说明“单元格来自 quote，已通过 sheets 读取验证”，不要说它来自 `positionInfo`。
|
||||
|
||||
### Bitable / Base 内部评论
|
||||
|
||||
- `parent_token` 常见格式是 `<base_token>_<table_id>`，其中 `table_id` 通常以 `tbl` 开头。解析时优先按最后一个 `_tbl` 边界拆分，避免 base token 内出现 `_` 时误拆。
|
||||
- 评论接口可能只返回 `parent_type=BITABLE_BLOCK` 和 `parent_token`，没有 `relation`；即使有 relation，也通常只足够定位到文档里的 `<bitable>` block。
|
||||
- 下钻读取时切到 `lark-base`，最少确认表、字段、记录：
|
||||
|
||||
```bash
|
||||
lark-cli base +table-list --base-token '<base_token>'
|
||||
lark-cli base +field-list --base-token '<base_token>' --table-id '<table_id>'
|
||||
lark-cli base +record-list --base-token '<base_token>' --table-id '<table_id>' --limit 200 --format json
|
||||
```
|
||||
|
||||
- 如果 `quote` 是某个稳定业务值，优先用字段/记录数据做精确匹配；如果 `quote` 只是“第 N 条”“第 N 行”这类 UI 序号，只能基于当前记录顺序推断对应记录，必须输出为“推断”，并说明评论接口没有返回 `record_id` / `field_id`。
|
||||
- 如果 `record-list` 返回 `has_more=true`，不要基于第一页下全局结论；继续分页或说明只能覆盖已读取范围。
|
||||
- 需要写入时，如果评论没有字段信息，不要自行猜字段；除非用户给出默认规则，否则请求用户确认字段，或明确说明将使用哪个字段作为默认。
|
||||
|
||||
### Whiteboard 内部评论
|
||||
|
||||
- `parent_token` 对应文档 XML 中 `<whiteboard token="...">`；先用它匹配文档里的 whiteboard block。
|
||||
- 若要定位画板内部节点，切到 `lark-whiteboard` 读取 raw 节点结构：
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +query \
|
||||
--whiteboard-token '<whiteboard_token>' \
|
||||
--output_as raw
|
||||
```
|
||||
|
||||
- 如果 raw 节点中存在唯一匹配 `quote` 的文本节点，可定位到该节点；如果有多个相同文本节点，仍然是弱匹配，需要结合位置、样式、用户描述或人工确认。
|
||||
- 修改画板节点前，先说明匹配到的节点 id 和文本；复杂画板不要只凭 `quote` 批量替换全部同名节点。
|
||||
|
||||
## 使用原则
|
||||
|
||||
- Review 文档时，不要只依赖 `quote` 文本定位评论；多处相同文本会产生歧义。
|
||||
- 能拿到 `relation.positionInfo.blockID` 时，以 block id 为准，再用 block 内容理解上下文。
|
||||
- 对嵌入 sheet / bitable / whiteboard 内的评论，以父级嵌入 block 作为文档正文定位点；如需继续定位到表格单元格、多维表格记录或画板内部节点，需要再调用对应 sheet / bitable / whiteboard 能力读取内部数据。
|
||||
@ -0,0 +1,72 @@
|
||||
# Drive 评论查询、统计与回复指南
|
||||
|
||||
> 前置条件：先阅读 [`../SKILL.md`](../SKILL.md) 的“评论能力入口”，添加评论参数细节见 [`lark-drive-add-comment.md`](lark-drive-add-comment.md)，reaction 见 [`lark-drive-reactions.md`](lark-drive-reactions.md)。
|
||||
|
||||
## 评论模式
|
||||
|
||||
- `drive +add-comment` 支持全文评论和局部评论。
|
||||
- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc` / `docx` / `file` 的 wiki URL。
|
||||
- 局部评论：传 `--block-id` 时启用；`docx` 支持文本定位或 block id，`sheet` 支持 `<sheetId>!<cell>`，`slides` 支持 `<slide-block-type>!<xml-id>`，wiki URL 解析到这些类型时也支持对应局部评论。
|
||||
- Drive file 只支持全文评论，不支持局部评论。支持扩展名：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件暂不支持。
|
||||
- Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论。
|
||||
- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
|
||||
- `slides` 评论要求显式传 `--block-id <slide-block-type>!<xml-id>`；CLI 会将其拆分后写入 `anchor.block_id` 和 `anchor.slide_block_type`。其中 `<xml-id>` 是 PPT XML 协议中的元素 `id`；不支持 `--selection-with-ellipsis` 和 `--full-comment`。
|
||||
- 评论写入内容里的文本不能直接出现 `<`、`>`；提交前应转义为 `<`、`>`。`drive +add-comment` 会对 `type=text` 文本元素自动兜底转义；直接调用原生评论 API 时需要自行转义。
|
||||
- 如果 wiki 解析后不是 `doc` / `docx` / `file` / `sheet` / `slides`，不要用 `+add-comment`。
|
||||
|
||||
## 查询默认口径
|
||||
|
||||
`drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到要包含已解决评论，仍然按默认口径查询未解决评论。仅当用户明确要求包含已解决评论时，才可省略 `is_solved` 参数。
|
||||
|
||||
```bash
|
||||
# 默认查询：仅未解决评论
|
||||
lark-cli drive file.comments list --params '{"file_token":"xxx","file_type":"docx","is_solved":false}'
|
||||
|
||||
# 包含已解决评论：仅当用户明确要求时使用
|
||||
lark-cli drive file.comments list --params '{"file_token":"xxx","file_type":"docx"}'
|
||||
```
|
||||
|
||||
## 评论卡片与统计
|
||||
|
||||
- `drive file.comments list` 返回的 `items` 是评论卡片列表，每个 `item` 对应用户界面中的一张评论卡片，不是平铺的互动消息列表。
|
||||
- 创建第一条评论时会同时创建该卡片里的第一条 reply；真正承载正文的是 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的“评论本身”。
|
||||
- 统计“评论数”或“评论卡片数”：统计 `items` 长度；全量统计时对所有分页返回的 `items` 长度累加。
|
||||
- 统计“回复数”：统计所有 `item.reply_list.replies` 长度之和，再减去 `items` 长度。
|
||||
- 统计“总互动数”：统计所有 `item.reply_list.replies` 长度之和，包含每张评论卡片里的首条评论。
|
||||
- 如果 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中；需要继续调用 `drive file.comment.replys list` 拉全后，再做全量回复数或总互动数统计。
|
||||
|
||||
## 排序
|
||||
|
||||
- 只有当用户明确提到“最新评论”“最后评论”“最早评论”时，才需要按 `create_time` 排序。
|
||||
- 排序前必须拉完所有评论分页，不能只取第一页。
|
||||
- “最新评论”/“最后评论”：按 `create_time` 降序取第一条。
|
||||
- “最早评论”：按 `create_time` 升序取第一条。
|
||||
- 用户只说“第一条评论”时，直接使用 `drive file.comments list` 返回的第一条，不需要额外排序。
|
||||
|
||||
## 回复限制
|
||||
|
||||
- 回复前先检查目标评论状态。
|
||||
- `is_whole=true` 的全文评论不支持回复；遇到时提示“全文评论不支持回复”。
|
||||
- `is_solved=true` 的已解决评论不支持回复；遇到时提示“该评论已被解决，无法回复”。
|
||||
- 当目标评论不能回复时，只提示限制，不要自动替用户寻找其他可回复评论。
|
||||
|
||||
## batch_query 与 list
|
||||
|
||||
- `drive file.comments batch_query` 用于已知评论 ID 后的批量查询，需要传入具体评论 ID 列表。
|
||||
- `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论、获取最新或最后 N 条评论等场景。
|
||||
|
||||
## 评论定位字段
|
||||
|
||||
- 需要根据评论定位到文档正文位置时（例如根据评论 review 文档、区分多处相同引用文本、把评论落点映射到 `docs +fetch` 的 block），先确认目标是 `file_type=docx`，再阅读 [`lark-drive-comment-location.md`](lark-drive-comment-location.md)。
|
||||
- 其他文档类型暂不支持返回定位字段。
|
||||
|
||||
## 原生 API
|
||||
|
||||
需要更底层地直接调用评论 V2 协议时，先查看 schema，再调用原生命令。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
|
||||
|
||||
```bash
|
||||
lark-cli schema drive.file.comments.create_v2
|
||||
lark-cli drive file.comments create_v2 \
|
||||
--params '{"file_token":"<DOC_TOKEN>"}' \
|
||||
--data '{"file_type":"docx","reply_elements":[{"type":"text","text":"全文评论内容"}]}'
|
||||
```
|
||||
79
.agents/skills/lark-drive/references/lark-drive-cover.md
Normal file
79
.agents/skills/lark-drive/references/lark-drive-cover.md
Normal file
@ -0,0 +1,79 @@
|
||||
## `drive +cover`
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
|
||||
|
||||
列出或下载 Drive 文件的稳定封面预设。这个 shortcut 只暴露 `spec`，不暴露底层 `cover_option` 细节。
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
# 列出内置封面规格
|
||||
lark-cli drive +cover \
|
||||
--file-token "<FILE_TOKEN>" \
|
||||
--list-only
|
||||
|
||||
# 下载 square 规格封面
|
||||
lark-cli drive +cover \
|
||||
--file-token "<FILE_TOKEN>" \
|
||||
--spec square \
|
||||
--output ./artifacts/report-cover
|
||||
|
||||
# 下载默认大图封面，并在文件冲突时覆盖
|
||||
lark-cli drive +cover \
|
||||
--file-token "<FILE_TOKEN>" \
|
||||
--spec default \
|
||||
--output ./artifacts/report-cover.png \
|
||||
--if-exists overwrite
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file-token` | 是 | Drive 文件 token |
|
||||
| `--spec` | 条件必填 | 封面预设：`default` / `icon` / `grid` / `small` / `middle` / `big` / `square` |
|
||||
| `--version` | 否 | 文件版本号 |
|
||||
| `--list-only` | 否 | 仅返回可选规格，不下载 |
|
||||
| `--output` | 条件必填 | 下载到本地的输出路径 |
|
||||
| `--if-exists` | 否 | 输出冲突策略：`error`（默认）/ `overwrite` / `rename` |
|
||||
|
||||
### 输出约定
|
||||
|
||||
- 查询态返回：
|
||||
- `mode=list`
|
||||
- `file_token`
|
||||
- `candidates[]`
|
||||
- `next_action`
|
||||
- 下载态返回：
|
||||
- `mode=download`
|
||||
- `file_token`
|
||||
- `selected_spec`
|
||||
- `output_path`
|
||||
- `status`
|
||||
|
||||
### 内置规格
|
||||
|
||||
- `default` -- 标准大图封面
|
||||
- `icon` -- 列表小图标
|
||||
- `grid` -- 网格/卡片流小封面
|
||||
- `small` -- PC 小图
|
||||
- `middle` -- 中等尺寸封面
|
||||
- `big` -- 偏移动端的大图封面
|
||||
- `square` -- 正方形裁剪封面
|
||||
|
||||
### 关键约束
|
||||
|
||||
- 不传 `--list-only` 时，必须显式传 `--spec` 和 `--output`
|
||||
- `drive +cover` 只返回静态预设规格，不伪造后端“可下载状态”
|
||||
- 不返回底层 `bus_type` / `platform` / `width` / `height` / `policy` 等实现细节
|
||||
- 下载时直接调用 `preview_download`
|
||||
- 未显式带扩展名时，会优先根据响应头补扩展名，缺失时回退到 `.png`
|
||||
|
||||
### 错误提示
|
||||
|
||||
- 下载某个 `--spec` 时如果返回 **HTTP 404**，表示这个文件**没有该规格对应的封面产物**，应视为“该规格不可用”，而不是默认按网络抖动或临时失败处理
|
||||
|
||||
### 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- Drive 总入口
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,73 @@
|
||||
# drive +create-folder（创建云空间/云盘/云存储文件夹）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
在飞书云空间（云盘/云存储）中创建一个新文件夹。该 shortcut 对原生 `drive files create_folder` 做了一层更适合日常使用的封装：`--folder-token` 可省略，此时会在调用者根目录创建；如果使用 `--as bot`，创建成功后 CLI 会尝试把新文件夹的可管理权限自动授予当前 CLI 用户。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 在根目录创建文件夹
|
||||
lark-cli drive +create-folder \
|
||||
--name "周报归档"
|
||||
|
||||
# 在指定父文件夹下创建子文件夹
|
||||
lark-cli drive +create-folder \
|
||||
--folder-token <PARENT_FOLDER_TOKEN> \
|
||||
--name "2026-W16"
|
||||
|
||||
# 预览底层调用
|
||||
lark-cli drive +create-folder \
|
||||
--folder-token <PARENT_FOLDER_TOKEN> \
|
||||
--name "分析资料" \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
成功后会返回一个 JSON 对象，常见字段包括：
|
||||
|
||||
- `folder_token`：新建文件夹 token，可直接用于后续 `drive +move`、`drive +upload` 等命令
|
||||
- `url`：新建文件夹链接（如果接口返回）
|
||||
- `name`：文件夹名称
|
||||
- `parent_folder_token`：父文件夹 token；为空字符串表示创建在根目录
|
||||
- `permission_grant`（可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 如果文件夹是**以应用身份（bot）创建**的，如 `lark-cli drive +create-folder --as bot`，在创建成功后 CLI 会**尝试为当前 CLI 用户自动授予该文件夹的 `full_access`（可管理权限）**。
|
||||
>
|
||||
> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
|
||||
> - `status = granted`：当前 CLI 用户已获得该文件夹的可管理权限
|
||||
> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
|
||||
> - `status = failed`：文件夹已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文件夹
|
||||
>
|
||||
> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
|
||||
>
|
||||
> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--name` | 是 | 文件夹名称，不能为空，最长 256 字节 |
|
||||
| `--folder-token` | 否 | 父文件夹 token；省略时表示在调用者根目录创建 |
|
||||
|
||||
## 行为说明
|
||||
|
||||
- **根目录创建**：不传 `--folder-token` 时，shortcut 会向 API 显式传空字符串 `folder_token=""`，让后端按“根目录”语义创建
|
||||
- **bot 自动授权**：只有在 `--as bot` 时，结果才会额外带上 `permission_grant`
|
||||
- **原生 API 仍可用**：如果用户明确要求按底层 API 字段调用，仍可继续使用 `lark-cli drive files create_folder`
|
||||
|
||||
## 推荐场景
|
||||
|
||||
- 用户说“在云空间（云盘/云存储）新建一个文件夹 / 目录”时，优先使用 `drive +create-folder`
|
||||
- 用户给了父文件夹链接或 token，需要在其下继续分层建目录时，传 `--folder-token`
|
||||
- 如果后续还要上传文件、移动文件、建子目录，优先复用返回值里的 `folder_token`
|
||||
|
||||
> [!CAUTION]
|
||||
> `drive +create-folder` 是**写入操作**，执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,103 @@
|
||||
|
||||
# drive +create-shortcut
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
在目标文件夹中为一个现有 Drive 文件创建快捷方式。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 为普通文件创建快捷方式
|
||||
lark-cli drive +create-shortcut \
|
||||
--folder-token <TARGET_FOLDER_TOKEN> \
|
||||
--file-token <FILE_TOKEN> \
|
||||
--type file
|
||||
|
||||
# 为新版文档创建快捷方式
|
||||
lark-cli drive +create-shortcut \
|
||||
--folder-token <TARGET_FOLDER_TOKEN> \
|
||||
--file-token <DOCX_TOKEN> \
|
||||
--type docx
|
||||
|
||||
# 为电子表格创建快捷方式
|
||||
lark-cli drive +create-shortcut \
|
||||
--folder-token <TARGET_FOLDER_TOKEN> \
|
||||
--file-token <SHEET_TOKEN> \
|
||||
--type sheet
|
||||
|
||||
# 仅预览即将发起的请求，不真正执行
|
||||
lark-cli drive +create-shortcut \
|
||||
--folder-token <TARGET_FOLDER_TOKEN> \
|
||||
--file-token <DOCX_TOKEN> \
|
||||
--type docx \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--folder-token` | 是 | 目标父文件夹 token |
|
||||
| `--file-token` | 是 | 源文件 token，表示被引用的原始文件 |
|
||||
| `--type` | 是 | 源文件类型，推荐值：`file`、`docx`、`doc`、`sheet`、`bitable`、`mindnote`、`slides` |
|
||||
|
||||
## 输入规则
|
||||
|
||||
- 该 shortcut 的最小输入是 `--folder-token` + `--file-token` + `--type`
|
||||
- CLI 层会把 `--file-token` 和 `--type` 组装为底层 API 所需的 `refer_entity`
|
||||
- `--file-token` 必须是 Drive 文件 token，不要直接传 wiki 节点 token
|
||||
- 如果来源是 `/wiki/...` 链接，必须先按 [`lark-drive`](../SKILL.md) 中的 wiki 解析流程拿到真实 `obj_token`，再创建快捷方式
|
||||
- 目标位置必须是云空间（云盘/云存储）文件夹；这个 shortcut 不是“复制文件内容”，而是“在另一个文件夹里挂一个引用入口”
|
||||
|
||||
## 类型说明
|
||||
|
||||
| 类型 | 说明 |
|
||||
|------|------|
|
||||
| `file` | 普通文件 |
|
||||
| `docx` | 新版云文档 |
|
||||
| `doc` | 旧版云文档 |
|
||||
| `sheet` | 电子表格 |
|
||||
| `bitable` | 多维表格 |
|
||||
| `mindnote` | 思维笔记 |
|
||||
| `slides` | 幻灯片 |
|
||||
|
||||
## 行为说明
|
||||
|
||||
- 成功时会调用 `POST /open-apis/drive/v1/files/create_shortcut`
|
||||
- 该 shortcut 继承通用能力，可配合 `--as user|bot|auto`、`--format`、`--jq`、`--dry-run` 使用
|
||||
- `--dry-run` 只输出请求方法、路径、身份和请求体预览，不会真正创建快捷方式
|
||||
- 这是写入操作；执行前应确认目标文件夹和源文件都准确无误
|
||||
|
||||
## 限制
|
||||
|
||||
- 该接口不支持并发调用
|
||||
- 调用频率上限为 5 QPS，且 10000 次/天
|
||||
- 不支持跨租户、跨地域创建快捷方式
|
||||
- 不支持跨品牌创建快捷方式
|
||||
- 如果目标父文件夹单层挂载数量超过限制，会返回 `1062507`
|
||||
|
||||
## 权限要求
|
||||
|
||||
- 当前调用身份需要能访问源文件
|
||||
- 当前调用身份需要对目标文件夹有编辑权限
|
||||
- 如果权限不足，常见表现为 `1061004 forbidden`
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误码 / 错误信息 | 原因 | 处理建议 |
|
||||
|------|------|------|
|
||||
| `1061002 params error` | 缺少必填参数，或 `--file-token` / `--type` 组合无法构成有效源文件信息 | 检查 `--file-token`、`--type` 是否完整且匹配；如显式传了 `--folder-token`，再确认其值有效 |
|
||||
| `1061003 not found` | 源文件或目标文件夹不存在 | 重新确认 token 是否正确、资源是否已删除 |
|
||||
| `1061004 forbidden` | 对源文件没有访问权限，或对目标文件夹没有编辑权限 | 切换到有权限的身份，或先授予文档 / 文件夹权限 |
|
||||
| `1061005 auth failed` | 身份类型或 access token 不正确 | 检查 `--as` 使用的身份及当前登录态 |
|
||||
| `1061007 file has been delete` | 源文件已删除 | 确认原文件仍存在，再重新执行 |
|
||||
| `1062507 parent node out of sibling num` | 目标文件夹单层挂载数超过上限 | 清理目标目录，或换一个父文件夹 |
|
||||
| `1061045 resource contention occurred, please retry` | 平台内部资源争抢 | 稍后重试，不要并发重复调用 |
|
||||
| `1064510 cross tenant and unit not support` | 跨租户或跨地域请求 | 改为在同租户、同地域范围内操作 |
|
||||
| `1064511 cross brand not support` | 跨品牌请求 | 改为在同品牌环境内操作 |
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
79
.agents/skills/lark-drive/references/lark-drive-delete.md
Normal file
79
.agents/skills/lark-drive/references/lark-drive-delete.md
Normal file
@ -0,0 +1,79 @@
|
||||
|
||||
# drive +delete
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
删除云空间（云盘/云存储）内的文件或文件夹。删除后资源会进入回收站。
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**高风险写操作**。CLI 层要求显式传 `--yes`；如果用户已经明确要求删除且目标明确，直接执行并带上 `--yes`。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 删除普通文件
|
||||
lark-cli drive +delete \
|
||||
--file-token <FILE_TOKEN> \
|
||||
--type file \
|
||||
--yes
|
||||
|
||||
# 删除在线文档
|
||||
lark-cli drive +delete \
|
||||
--file-token <DOCX_TOKEN> \
|
||||
--type docx \
|
||||
--yes
|
||||
|
||||
# 删除文件夹（异步操作，会自动有限轮询任务状态）
|
||||
lark-cli drive +delete \
|
||||
--file-token <FOLDER_TOKEN> \
|
||||
--type folder \
|
||||
--yes
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file-token` | 是 | 需要删除的文件或文件夹 token |
|
||||
| `--type` | 是 | 文件类型，可选值：`file`、`docx`、`bitable`、`doc`、`sheet`、`mindnote`、`folder`、`shortcut`、`slides` |
|
||||
| `--yes` | 是 | 确认执行高风险删除操作 |
|
||||
|
||||
## 行为说明
|
||||
|
||||
- **普通文件删除**：同步操作，成功时直接返回 `deleted=true`
|
||||
- **文件夹删除**：异步操作，接口返回 `task_id`，shortcut 会先做有限轮询；如果在轮询窗口内完成，则直接返回成功结果
|
||||
- **轮询超时不是失败**：文件夹删除内置最多轮询 30 次、每次间隔 2 秒；如果轮询结束任务仍未完成，会返回 `task_id`、`status`、`ready=false`、`timed_out=true` 和 `next_command`
|
||||
- **继续查询**：当看到 `next_command` 时，改用 `lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>` 继续查询
|
||||
- **状态值**：`task_check` 的服务端状态通常是 `success`、`fail`、`process`
|
||||
|
||||
## 推荐续跑方式
|
||||
|
||||
```bash
|
||||
# 第一步：先直接删除文件夹
|
||||
lark-cli drive +delete \
|
||||
--file-token <FOLDER_TOKEN> \
|
||||
--type folder \
|
||||
--yes
|
||||
|
||||
# 如果返回 ready=false / timed_out=true，再继续查
|
||||
lark-cli drive +task_result \
|
||||
--scenario task_check \
|
||||
--task-id <TASK_ID>
|
||||
```
|
||||
|
||||
## 限制
|
||||
|
||||
- 该 shortcut 仅支持云空间（云盘/云存储）文件或文件夹，不支持 wiki 文档
|
||||
- 该接口不支持并发调用
|
||||
- 调用频率上限为 5 QPS 且 10000 次/天
|
||||
|
||||
## 权限要求
|
||||
|
||||
- 删除文件时，调用身份需要满足以下其一：
|
||||
- 是文件所有者，并且拥有该文件所在父文件夹的编辑权限
|
||||
- 不是文件所有者，但拥有该父文件夹的 owner 或 full access 权限
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
31
.agents/skills/lark-drive/references/lark-drive-download.md
Normal file
31
.agents/skills/lark-drive/references/lark-drive-download.md
Normal file
@ -0,0 +1,31 @@
|
||||
|
||||
# drive +download
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
从飞书云空间（云盘/云存储）下载文件到本地。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 下载到指定路径
|
||||
lark-cli drive +download --file-token boxbc_xxx --output ./report.pdf
|
||||
|
||||
# 只提供 token，默认保存为当前目录下同名文件
|
||||
lark-cli drive +download --file-token boxbc_xxx
|
||||
```
|
||||
|
||||
## URL 解析
|
||||
|
||||
从飞书文件 URL 提取 token：
|
||||
|
||||
```
|
||||
https://xxx.feishu.cn/drive/file/boxbc_xxx
|
||||
^^^^^^^^^
|
||||
file_token
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,50 @@
|
||||
|
||||
# drive +export-download
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
根据导出任务产物的 `file_token` 下载本地文件。通常与 `drive +task_result --scenario export` 配合使用。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 使用服务端返回的文件名下载到当前目录
|
||||
lark-cli drive +export-download \
|
||||
--file-token "<EXPORTED_FILE_TOKEN>"
|
||||
|
||||
# 下载到指定目录
|
||||
lark-cli drive +export-download \
|
||||
--file-token "<EXPORTED_FILE_TOKEN>" \
|
||||
--output-dir ./exports
|
||||
|
||||
# 指定本地文件名
|
||||
lark-cli drive +export-download \
|
||||
--file-token "<EXPORTED_FILE_TOKEN>" \
|
||||
--file-name "weekly-report.pdf" \
|
||||
--output-dir ./exports
|
||||
|
||||
# 允许覆盖
|
||||
lark-cli drive +export-download \
|
||||
--file-token "<EXPORTED_FILE_TOKEN>" \
|
||||
--overwrite
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file-token` | 是 | 导出完成后的产物 token |
|
||||
| `--file-name` | 否 | 覆盖默认文件名 |
|
||||
| `--output-dir` | 否 | 本地输出目录，默认当前目录 |
|
||||
| `--overwrite` | 否 | 覆盖已存在文件 |
|
||||
|
||||
## 使用顺序
|
||||
|
||||
1. 用 `drive +export` 发起导出
|
||||
2. 如果返回 `ticket` / `next_command`，用 `drive +task_result --scenario export --ticket <ticket> --file-token <source_token>` 继续查
|
||||
3. 查到 `file_token` 后，用 `drive +export-download` 下载
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
135
.agents/skills/lark-drive/references/lark-drive-export.md
Normal file
135
.agents/skills/lark-drive/references/lark-drive-export.md
Normal file
@ -0,0 +1,135 @@
|
||||
|
||||
# drive +export
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
把 `doc` / `docx` / `sheet` / `bitable` / `slides` 导出到本地文件。这个 shortcut 内置有限轮询：
|
||||
|
||||
- 如果导出任务在轮询窗口内完成，会直接下载到本地目录
|
||||
- 如果轮询结束仍未完成，会返回 `ticket`、`ready=false`、`timed_out=true` 和 `next_command`
|
||||
- 后续继续查结果时，改用 `drive +task_result --scenario export`
|
||||
- 拿到 `file_token` 后，改用 `drive +export-download`
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 导出新版文档为 pdf，默认保存到当前目录
|
||||
lark-cli drive +export \
|
||||
--token "<DOCX_TOKEN>" \
|
||||
--doc-type docx \
|
||||
--file-extension pdf
|
||||
|
||||
# 导出旧版文档为 docx
|
||||
lark-cli drive +export \
|
||||
--token "<DOC_TOKEN>" \
|
||||
--doc-type doc \
|
||||
--file-extension docx
|
||||
|
||||
# 导出 docx 为 markdown（Lark-flavored Markdown）
|
||||
# 注意：markdown 只支持 docx
|
||||
lark-cli drive +export \
|
||||
--token "<DOCX_TOKEN>" \
|
||||
--doc-type docx \
|
||||
--file-extension markdown
|
||||
|
||||
# 导出电子表格为 xlsx
|
||||
lark-cli drive +export \
|
||||
--token "<SHEET_TOKEN>" \
|
||||
--doc-type sheet \
|
||||
--file-extension xlsx \
|
||||
--output-dir ./exports
|
||||
|
||||
# 导出幻灯片为 pptx
|
||||
lark-cli drive +export \
|
||||
--token "<SLIDES_TOKEN>" \
|
||||
--doc-type slides \
|
||||
--file-extension pptx \
|
||||
--output-dir ./exports
|
||||
|
||||
# 导出幻灯片为 pdf
|
||||
lark-cli drive +export \
|
||||
--token "<SLIDES_TOKEN>" \
|
||||
--doc-type slides \
|
||||
--file-extension pdf \
|
||||
--output-dir ./exports
|
||||
|
||||
# 指定本地文件名（会按导出格式自动补扩展名）
|
||||
lark-cli drive +export \
|
||||
--token "<DOCX_TOKEN>" \
|
||||
--doc-type docx \
|
||||
--file-extension pdf \
|
||||
--file-name "weekly-report.pdf" \
|
||||
--output-dir ./exports
|
||||
|
||||
# 导出电子表格或多维表格为 csv 时，必须传 sub_id
|
||||
lark-cli drive +export \
|
||||
--token "<SHEET_OR_BITABLE_TOKEN>" \
|
||||
--doc-type "<sheet|bitable>" \
|
||||
--file-extension csv \
|
||||
--sub-id "<SUB_ID>" \
|
||||
--output-dir ./exports
|
||||
|
||||
# 导出多维表格为 .base 快照（只支持 bitable）
|
||||
lark-cli drive +export \
|
||||
--token "<BITABLE_TOKEN>" \
|
||||
--doc-type bitable \
|
||||
--file-extension base \
|
||||
--output-dir ./exports
|
||||
|
||||
# 允许覆盖已存在文件
|
||||
lark-cli drive +export \
|
||||
--token "<DOCX_TOKEN>" \
|
||||
--doc-type docx \
|
||||
--file-extension pdf \
|
||||
--overwrite
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--token` | 是 | 源文档 token |
|
||||
| `--doc-type` | 是 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` / `slides` |
|
||||
| `--file-extension` | 是 | 导出格式：`docx` / `pdf` / `xlsx` / `csv` / `markdown` / `base` / `pptx` |
|
||||
| `--sub-id` | 条件必填 | 当 `sheet` / `bitable` 导出为 `csv` 时必填 |
|
||||
| `--file-name` | 否 | 覆盖默认本地文件名；如未带扩展名，会按 `--file-extension` 自动补齐 |
|
||||
| `--output-dir` | 否 | 本地输出目录，默认当前目录 |
|
||||
| `--overwrite` | 否 | 覆盖已存在文件 |
|
||||
|
||||
## 关键约束
|
||||
|
||||
- `markdown` 只支持 `docx`
|
||||
- `base` 只支持 `bitable`
|
||||
- `pptx` 只支持 `slides`
|
||||
- `slides` 支持导出为 `pptx` / `pdf`
|
||||
- `sheet` / `bitable` 导出为 `csv` 时必须带 `--sub-id`
|
||||
- shortcut 内部固定有限轮询：最多 10 次，每次间隔 5 秒
|
||||
- 轮询超时不是失败；会返回 `ticket`、`timed_out=true` 和 `next_command`，供后续继续查询
|
||||
|
||||
## 推荐续跑方式
|
||||
|
||||
```bash
|
||||
# 第一步：先尝试直接导出
|
||||
lark-cli drive +export \
|
||||
--token "<DOCX_TOKEN>" \
|
||||
--doc-type docx \
|
||||
--file-extension pdf \
|
||||
--file-name "weekly-report.pdf"
|
||||
|
||||
# 如果返回 ready=false / timed_out=true，再继续查
|
||||
lark-cli drive +task_result \
|
||||
--scenario export \
|
||||
--ticket "<TICKET>" \
|
||||
--file-token "<DOCX_TOKEN>"
|
||||
|
||||
# 查到 file_token 后下载
|
||||
lark-cli drive +export-download \
|
||||
--file-token "<EXPORTED_FILE_TOKEN>" \
|
||||
--file-name "weekly-report.pdf" \
|
||||
--output-dir ./exports
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
158
.agents/skills/lark-drive/references/lark-drive-files-list.md
Normal file
158
.agents/skills/lark-drive/references/lark-drive-files-list.md
Normal file
@ -0,0 +1,158 @@
|
||||
# drive files list（原生 API：读取 Drive 文件夹清单）
|
||||
|
||||
`drive files list` 是原生 API 命令，不是 shortcut。它用于读取 Drive 根目录或某个 Drive 文件夹的直接子项；如果要递归盘点目录树，Agent 必须基于返回的子文件夹 token 继续调用本命令。
|
||||
|
||||
## 什么时候使用
|
||||
|
||||
| 场景 | 是否使用 | 说明 |
|
||||
|------|----------|------|
|
||||
| 盘点一个已确认的 Drive 文件夹树 | 使用 | 从目标 `folder_token` 开始递归列取 |
|
||||
| 盘点用户明确确认的 Drive 根目录 | 使用 | 第一层用空 `folder_token`，子文件夹继续按普通文件夹递归 |
|
||||
| 验证移动 / 创建后的实际位置 | 使用 | 读取目标目录直接子项，再按需递归验证 |
|
||||
| 根据关键词、标题、时间、owner 找资源 | 不使用 | 优先用 `drive +search` |
|
||||
| 读取 Docx 正文内容 | 不使用 | 用 `docs +fetch --api-version v2` |
|
||||
| 读取 Sheet / Base 内部数据 | 不使用 | 切到 `lark-sheets` / `lark-base` |
|
||||
|
||||
## 标准命令模板
|
||||
|
||||
读取普通文件夹：
|
||||
|
||||
```bash
|
||||
lark-cli drive files list \
|
||||
--params '{"folder_token":"<folder_token>","page_size":200}' \
|
||||
--format json
|
||||
```
|
||||
|
||||
继续翻页：
|
||||
|
||||
```bash
|
||||
lark-cli drive files list \
|
||||
--params '{"folder_token":"<folder_token>","page_size":200,"page_token":"<PAGE_TOKEN>"}' \
|
||||
--format json
|
||||
```
|
||||
|
||||
读取当前用户 Drive 根目录的直接子项：
|
||||
|
||||
```bash
|
||||
lark-cli drive files list \
|
||||
--params '{"folder_token":"","page_size":200}' \
|
||||
--format json
|
||||
```
|
||||
|
||||
也可以省略 `folder_token` 字段来请求根目录，但在 Agent 编排中建议显式传空字符串，避免把“忘记传参数”和“确认请求根目录”混在一起。
|
||||
|
||||
## 参数规则
|
||||
|
||||
1. `folder_token` 必须放在 `--params` JSON 里；不要使用不存在的 `--folder-token` flag。
|
||||
2. `page_token` 必须放在 `--params` JSON 里；不要依赖 shell 变量拼接不完整的 JSON。
|
||||
3. `page_size` 建议显式设置为 `200`。如果服务端或环境返回参数错误，再降级到服务端允许的值，并记录降级原因。
|
||||
4. 调用前如果不确定字段结构，先运行 `lark-cli schema drive.files.list` 查看 `--params` 结构。
|
||||
|
||||
## 返回结构与解析
|
||||
|
||||
`--format json` 输出中，Agent 只使用 `data` 中符合 `schema drive.files.list` 的 API 返回字段。
|
||||
|
||||
常用字段：
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `data.files` | 当前页直接子项列表 |
|
||||
| `data.has_more` | 当前目录是否还有下一页 |
|
||||
| `data.next_page_token` | 下一页 token；当 `has_more=true` 时放回 `--params.page_token` |
|
||||
| `data.files[].type` | 文件类型；等于 `folder` 时可递归 |
|
||||
| `data.files[].token` | 当前资源 token；文件夹递归时作为下一层 `folder_token` |
|
||||
| `data.files[].name` | 生成路径和展示标题 |
|
||||
| `data.files[].url` | 资源浏览器链接 |
|
||||
| `data.files[].owner_id` | 资源所有者 |
|
||||
| `data.files[].created_time` / `data.files[].modified_time` | 创建 / 更新时间 |
|
||||
|
||||
字段名以 `schema drive.files.list` 为准。Agent MUST 以实际返回为准；如果字段缺失，先用 `schema drive.files.list` 或一页样本确认结构，不要猜测。
|
||||
|
||||
## 根目录语义
|
||||
|
||||
1. `folder_token` 为空字符串或省略时，请求的是当前调用用户的 Drive 根目录直接子项。
|
||||
2. 根目录返回值不是递归结果；不能把根目录第一页或直接子项数量当作整个云空间资源总量。
|
||||
3. 根目录只作为目录树起点。返回的子文件夹必须用其自己的 `folder_token` 继续调用 `drive files list`。
|
||||
4. 根据 schema 描述，根目录第一层清单不支持分页且不返回快捷方式；不要基于根目录响应推断子文件夹内容、根目录第一层快捷方式或无法分页的根目录剩余项已经被覆盖。
|
||||
|
||||
## 递归盘点规则
|
||||
|
||||
1. 只对返回项中的 `folder` 类型继续递归。
|
||||
2. 每个目录独立维护分页状态；一个目录的 `page_token` 不可复用于其他目录。
|
||||
3. 对每个目录持续请求，直到返回 `has_more=false`。非根目录的普通文件夹清单可能返回 `type=shortcut` 条目；不要假设这些条目会携带 `shortcut_info` 目标信息。
|
||||
4. 递归过程中生成稳定 `path`；不要只保存标题，否则同名资源无法区分。
|
||||
5. URL、owner、创建时间和更新时间优先使用 `files.list` 返回字段；如果字段缺失或需要批量补齐，再使用 `drive metas batch_query`。不要从标题或路径猜元数据。
|
||||
6. 深度、数量、每目录页数等限制只能作为内部批次 checkpoint；不能作为递归完成条件。
|
||||
7. 达到深度 checkpoint 时，把更深层子文件夹加入 continuation queue，并在下一批从这些子文件夹继续，保留原始 `path`。
|
||||
8. 达到数量 checkpoint 时，保存当前目录、当前页 token、剩余目录队列和已收集资源计数，并立即继续下一批；不要进入分析或规划阶段。
|
||||
|
||||
### 递归算法
|
||||
|
||||
Agent 盘点 Drive 文件夹树时，按以下顺序执行：
|
||||
|
||||
1. 初始化待处理队列，放入起点目录：
|
||||
- 普通文件夹：`{folder_token:"<folder_token>", path:"<folder_name>"}`
|
||||
- Drive 根目录：`{folder_token:"", path:""}`
|
||||
2. 从队列取出一个目录，请求第一页。
|
||||
3. 用 `(folder_token, page_token)` 生成当前页 key；同一页 key 只允许追加一次，避免 retry 时重复计数。
|
||||
4. 从 `data.files` 取当前页直接子项，按 `dedupe_key` 去重后生成 `path` 并加入结果集。
|
||||
5. 如果新追加的子项是 `folder`，把子文件夹 token、子路径和 depth 加入队列。
|
||||
6. 如果 `has_more=true`，取 `data.next_page_token` 继续请求同一目录下一页。
|
||||
7. 同一目录分页结束后，再处理队列中的下一个目录。
|
||||
8. 如果达到深度、数量或每目录页数 checkpoint，把当前目录 / 页 token / 剩余队列 / 已访问页 key / dedupe key 写入 continuation queue，并继续下一批。
|
||||
9. 普通队列和 continuation queue 都为空，且没有分页 blocker 时，才可以认为本次确认范围盘点完成。
|
||||
|
||||
简化伪代码：
|
||||
|
||||
```text
|
||||
queue = [root_or_start_folder]
|
||||
visited_pages = set()
|
||||
dedupe_keys = set()
|
||||
while queue not empty:
|
||||
folder = queue.pop()
|
||||
page_token = folder.page_token or ""
|
||||
retry_without_token = 0
|
||||
while true:
|
||||
page_key = (folder.folder_token, page_token or "first")
|
||||
page = drive files list(folder.folder_token, page_token)
|
||||
if page_key not in visited_pages:
|
||||
append only files whose dedupe_key is not in dedupe_keys
|
||||
enqueue newly appended child folders with folder_token, path, and depth
|
||||
add page_key to visited_pages
|
||||
if page.has_more != true:
|
||||
break
|
||||
next = page.next_page_token
|
||||
if next is empty:
|
||||
retry_without_token += 1
|
||||
if retry_without_token >= 3:
|
||||
record pagination blocker for folder
|
||||
break
|
||||
continue
|
||||
page_token = next
|
||||
retry_without_token = 0
|
||||
```
|
||||
|
||||
## 分页与异常
|
||||
|
||||
1. 默认手动处理 `has_more` 和返回中的 `next_page_token`。
|
||||
2. 不要使用 `--page-all` 作为脚本 JSON 解析输入；自动翻页输出可能不适合直接 `json.loads`。
|
||||
3. 如果 `has_more=true` 但没有可用的 `next_page_token`，重试同一页最多 3 次。
|
||||
4. 重试后仍无 continuation token 时，记录受影响的目录和 pagination blocker，停止扩展该目录；不要无限循环，也不要宣称该目录已完整覆盖。
|
||||
5. 如果触发深度、数量或每目录页数限制，把它视为批处理 checkpoint；在确认范围内继续下一批，而不是把当前结果说成完整。
|
||||
6. 不要因为达到 `max_depth=3`、`max_items=500` 或类似单批阈值就结束盘点；只有队列耗尽或遇到权限 / API / 工具预算 blocker 才能结束当前确认范围的盘点。
|
||||
|
||||
## JSON 解析规则
|
||||
|
||||
1. stdout 是数据通道。脚本解析 JSON 时只读取 stdout。
|
||||
2. stderr 可能包含刷新 token、进度、warning 或其他提示；不要把 stderr 合并进 JSON 输入，例如不要用 `2>&1` 后再 `json.loads`。
|
||||
3. 使用 `--format json` 保持 stdout 为结构化 JSON；解析 Drive 文件清单时只读取 `data.files` / `data.has_more` / `data.next_page_token` 等 schema 字段。
|
||||
4. 不要用根目录响应数量或当前页数量推断递归总量；递归总量必须由实际遍历并去重后的资源集合计算。
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误用法 | 问题 | 正确做法 |
|
||||
|----------|------|----------|
|
||||
| `lark-cli drive files list --folder-token <token>` | `files.list` 不提供 `--folder-token` flag | 使用 `--params '{"folder_token":"<token>"}'` |
|
||||
| 根目录返回 N 项就认为云空间只有 N 项 | 根目录只返回直接子项，不是递归结果 | 对返回的子文件夹继续递归 |
|
||||
| `--page-all \| python json.loads(...)` | 自动翻页输出不适合作为单个 JSON 对象解析 | 手动使用 `page_token` 翻页并逐页解析 |
|
||||
| `cmd 2>&1` 后解析 JSON | stderr 提示污染 JSON 输入 | 只解析 stdout，stderr 作为日志处理 |
|
||||
165
.agents/skills/lark-drive/references/lark-drive-import.md
Normal file
165
.agents/skills/lark-drive/references/lark-drive-import.md
Normal file
@ -0,0 +1,165 @@
|
||||
# drive +import
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
将本地文件（如 Word、TXT、Markdown、Excel、PPTX 等）导入并转换为飞书在线云文档（docx、sheet、bitable、slides）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 当用户说“把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable 文档”时，第一步必须使用 `drive +import --type bitable`。
|
||||
> 这是 Drive 导入场景，不是 `lark-base` 的建表 / 写记录场景。
|
||||
> 只有导入完成并拿到新文档的 `token` / `url` 后，后续字段、记录、视图等表内操作才切换到 `lark-cli base +...`。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 导入 Word 为新版文档 (docx)
|
||||
lark-cli drive +import --file ./report.docx --type docx
|
||||
lark-cli drive +import --file ./legacy.doc --type docx
|
||||
|
||||
# 导入 Markdown 为新版文档 (docx)
|
||||
lark-cli drive +import --file ./README.md --type docx
|
||||
|
||||
# 导入纯文本为新版文档 (docx)
|
||||
lark-cli drive +import --file ./notes.txt --type docx
|
||||
|
||||
# 导入 HTML 为新版文档 (docx)
|
||||
lark-cli drive +import --file ./page.html --type docx
|
||||
|
||||
# 导入 Excel 为电子表格 (sheet)
|
||||
lark-cli drive +import --file ./data.xlsx --type sheet
|
||||
|
||||
# 导入 Excel 97-2003 (.xls) 为电子表格 (sheet)
|
||||
lark-cli drive +import --file ./legacy.xls --type sheet
|
||||
|
||||
# 导入 CSV 为电子表格 (sheet)
|
||||
lark-cli drive +import --file ./data.csv --type sheet
|
||||
|
||||
# 导入 Excel 为多维表格 / Base (bitable)
|
||||
lark-cli drive +import --file ./crm.xlsx --type bitable --name "客户台账"
|
||||
|
||||
# 导入 .base 快照为多维表格 / Base (bitable)（文件不能超过 20MB）
|
||||
lark-cli drive +import --file ./snapshot.base --type bitable --name "快照还原"
|
||||
|
||||
# 导入 PPTX 为飞书幻灯片 (slides)（文件不能超过 500MB）
|
||||
lark-cli drive +import --file ./deck.pptx --type slides --name "项目汇报"
|
||||
|
||||
# 导入到指定文件夹，并指定导入后的文件名
|
||||
lark-cli drive +import --file ./data.csv --type bitable --folder-token <FOLDER_TOKEN> --name "导入数据表"
|
||||
|
||||
# 导入数据到已有的多维表格（不新建，数据挂载到目标多维表格中）
|
||||
lark-cli drive +import --file ./data.xlsx --type bitable --target-token <BASE_TOKEN>
|
||||
|
||||
# 预览底层调用链（上传 -> 创建任务 -> 轮询）
|
||||
lark-cli drive +import --file ./README.md --type docx --dry-run
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file` | 是 | 本地文件路径，根据文件后缀名自动推断 `file_extension`；文件需满足对应格式的导入大小限制，超过 20MB 且仍在允许范围内时会自动切换分片上传 |
|
||||
| `--type` | 是 | 导入目标云文档格式。可选值：`docx` (新版文档)、`sheet` (电子表格)、`bitable` (多维表格)、`slides` (飞书幻灯片) |
|
||||
| `--folder-token` | 否 | 目标文件夹 token，不传则请求中的 `point.mount_key` 为空字符串，Import API 会将其解释为导入到云空间（云盘/云存储）根目录 |
|
||||
| `--name` | 否 | 导入后的在线云文档名称，不传默认使用本地文件名去掉扩展名后的结果 |
|
||||
| `--target-token` | 否 | 已有的多维表格 token，将数据导入到该多维表格中（**仅支持 `--type bitable`**）；传入后数据会挂载到目标多维表格而非新建一个 |
|
||||
|
||||
## 行为说明
|
||||
|
||||
- **完整执行流程**：此 shortcut 内部封装了完整流程：
|
||||
1. 自动上传源文件获取 `file_token`：
|
||||
- 20MB 及以下：调用素材上传接口 `POST /open-apis/drive/v1/medias/upload_all`
|
||||
- 超过 20MB：自动切换为分片上传 `upload_prepare -> upload_part -> upload_finish`
|
||||
2. 调用 `import_tasks` 接口发起导入任务，自动根据本地文件提取扩展名并构造挂载点（`mount_point`）参数
|
||||
3. 自动轮询查询导入任务状态；如果在内置轮询窗口内完成，则直接返回导入结果；如果仍未完成，则返回 `ticket`、当前状态和后续查询命令
|
||||
- **默认根目录行为**：不传 `--folder-token` 时，shortcut 会保留空的 `point.mount_key`，Lark Import API 会将其视为"导入到调用者根目录"。
|
||||
- **导入到已有 bitable**：当 `--type bitable` 且传了 `--target-token` 时，请求 body 中会增加一个 `token` 字段指向目标多维表格的 token，point 挂载点逻辑不变。数据会挂载到该已有多维表格中，而非创建新文档。
|
||||
|
||||
### 支持的文件类型转换
|
||||
|
||||
本地文件扩展名与目标云文档类型的对应关系如下：
|
||||
|
||||
| 本地文件扩展名 | 可导入为 | 说明 |
|
||||
|--------------|---------|------|
|
||||
| `.docx`, `.doc` | `docx` | Microsoft Word 文档 |
|
||||
| `.txt` | `docx` | 纯文本文件 |
|
||||
| `.md`, `.markdown`, `.mark` | `docx` | Markdown 文档 |
|
||||
| `.html` | `docx` | HTML 文档 |
|
||||
| `.xlsx` | `sheet`, `bitable` | Microsoft Excel 表格 |
|
||||
| `.xls` | `sheet` | Microsoft Excel 97-2003 表格 |
|
||||
| `.csv` | `sheet`, `bitable` | CSV 数据文件 |
|
||||
| `.base` | `bitable` | 多维表格快照文件 |
|
||||
| `.pptx` | `slides` | Microsoft PowerPoint 演示文稿 |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 用户口头说的 “Base” / “多维表格” / “bitable”，在命令里统一对应 `--type bitable`。
|
||||
>
|
||||
> 文件扩展名与目标文档类型必须匹配，否则会返回验证错误：
|
||||
> - 文档类文件（.docx, .doc, .txt, .md, .html）**只能**导入为 `docx`
|
||||
> - `.xlsx` / `.csv` 文件**只能**导入为 `sheet` 或 `bitable`
|
||||
> - `.xls` 文件**只能**导入为 `sheet`
|
||||
> - `.base` 文件**只能**导入为 `bitable`
|
||||
> - `.pptx` 文件**只能**导入为 `slides`
|
||||
> - 例如：`.csv` 文件不能导入为 `docx`，`.md` 文件不能导入为 `sheet`
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 如果在线文档是**以应用身份（bot）导入创建**的，如 `lark-cli drive +import --as bot`，当某次结果**已经返回最终在线文档目标**后，CLI 会**尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
|
||||
>
|
||||
> 这个自动授权有两种触发时机：
|
||||
> - `drive +import` 的内置轮询窗口内已经完成，直接在 `+import` 中进行自动授权
|
||||
> - `drive +import` 先返回 `ready=false` / `timed_out=true`，之后你再执行 `lark-cli drive +task_result --scenario import --ticket <TICKET>`，当该查询第一次拿到最终在线文档目标时会自动授权
|
||||
>
|
||||
> 只有在已经拿到最终在线文档目标的那次结果里，才会返回 `permission_grant` 字段，明确说明授权结果：
|
||||
> - `status = granted`：当前 CLI 用户已获得该导入结果的可管理权限
|
||||
> - `status = skipped`：本地没有可用的当前用户 `open_id`，或当前结果还没有可授权目标，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
|
||||
> - `status = failed`：导入已成功返回最终在线文档，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档
|
||||
>
|
||||
> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
|
||||
>
|
||||
> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
|
||||
|
||||
### 文件大小限制
|
||||
|
||||
除扩展名与目标类型匹配外，`drive +import` 还会在本地上传前校验格式级大小限制：
|
||||
|
||||
| 本地文件扩展名 | 导入目标 | 大小上限 |
|
||||
|--------------|---------|---------|
|
||||
| `.docx`, `.doc` | `docx` | 600MB |
|
||||
| `.txt` | `docx` | 20MB |
|
||||
| `.md`, `.mark`, `.markdown` | `docx` | 20MB |
|
||||
| `.html` | `docx` | 20MB |
|
||||
| `.xlsx` | `sheet`, `bitable` | 800MB |
|
||||
| `.csv` | `sheet` | 20MB |
|
||||
| `.csv` | `bitable` | 100MB |
|
||||
| `.xls` | `sheet` | 20MB |
|
||||
| `.base` | `bitable` | 20MB |
|
||||
| `.pptx` | `slides` | 500MB |
|
||||
|
||||
- 如果文件超出对应上限，shortcut 会在真正上传前直接返回验证错误。
|
||||
- “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。
|
||||
|
||||
- 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
|
||||
- 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
|
||||
- `ready=false`
|
||||
- `timed_out=true`
|
||||
- `next_command`：可直接复制执行的后续查询命令，例如 `lark-cli drive +task_result --scenario import --ticket <TICKET>`
|
||||
- 若使用 `--as bot` 且内置轮询窗口内已经拿到最终在线文档，输出还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予可管理权限。
|
||||
- 若使用 `--as bot` 但当前只返回 `ready=false`，此时还不会返回 `permission_grant`；应继续执行返回值里的 `next_command`，等 `drive +task_result --scenario import` 拿到最终文档后再触发自动授权。
|
||||
- 如果文件扩展名不被支持，执行时将抛出验证错误。
|
||||
|
||||
### 超时后的继续查询
|
||||
|
||||
当 `+import` 的内置轮询窗口结束但任务尚未完成时，使用返回结果中的 `ticket` 继续查询：
|
||||
|
||||
```bash
|
||||
lark-cli drive +task_result --scenario import --ticket <TICKET>
|
||||
```
|
||||
|
||||
如果这里最终返回 `ready=true` 且使用的是 `--as bot`，结果还会额外带上 `permission_grant`，用于说明是否已自动为当前 CLI 用户授予可管理权限。
|
||||
|
||||
> [!CAUTION]
|
||||
> `drive +import` 是**写入操作** —— 执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
50
.agents/skills/lark-drive/references/lark-drive-inspect.md
Normal file
50
.agents/skills/lark-drive/references/lark-drive-inspect.md
Normal file
@ -0,0 +1,50 @@
|
||||
|
||||
# drive +inspect（文档 URL 检视：类型、标题、Token 解析）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
给定一个飞书文档 URL 或 bare token，返回其类型、标题和 canonical token。对 wiki URL 自动解包到底层文档。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 检视一个 docx URL
|
||||
lark-cli drive +inspect --url 'https://xxx.feishu.cn/docx/doxcnXXX'
|
||||
|
||||
# 检视一个 wiki URL（自动解包到底层文档）
|
||||
lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
|
||||
|
||||
# bare token 需要指定 --type
|
||||
lark-cli drive +inspect --url doxcnXXX --type docx
|
||||
|
||||
# 格式化输出
|
||||
lark-cli drive +inspect --url 'https://xxx.feishu.cn/base/bascnXXX' --format pretty
|
||||
```
|
||||
|
||||
## 输出
|
||||
|
||||
JSON 输出包含以下字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `input_url` | 原始输入 URL |
|
||||
| `type` | 文档类型（docx, doc, sheet, bitable, wiki, file, folder, mindnote, slides） |
|
||||
| `title` | 文档标题 |
|
||||
| `token` | canonical file token |
|
||||
| `url` | 重建的 canonical URL |
|
||||
| `wiki_node` | 仅 wiki URL：包含 `space_id`, `node_token`, `obj_token`, `obj_type` |
|
||||
|
||||
## 典型场景
|
||||
|
||||
| 场景 | 命令 |
|
||||
|------|------|
|
||||
| 用户给了一个 URL，想知道它是什么类型的文档 | `lark-cli drive +inspect --url '<url>'` |
|
||||
| wiki 链接需要拿到底层文档的 token 来做后续操作 | `lark-cli drive +inspect --url '<wiki_url>'`，取输出中的 `token` |
|
||||
| 只有 token 没有 URL | `lark-cli drive +inspect --url <token> --type <type>` |
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `--url` 为必填参数
|
||||
- 当 `--url` 是 bare token（非完整 URL）时，`--type` 也是必填的
|
||||
- wiki URL 会自动调用 `get_node` API 解包，输出中 `type` 和 `token` 是底层文档的类型和 token
|
||||
- 支持 `--dry-run` 查看将调用的 API 步骤
|
||||
120
.agents/skills/lark-drive/references/lark-drive-move.md
Normal file
120
.agents/skills/lark-drive/references/lark-drive-move.md
Normal file
@ -0,0 +1,120 @@
|
||||
|
||||
# drive +move
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
将文件或文件夹移动到用户云空间（云盘/云存储）的其他位置。
|
||||
|
||||
## 与 `wiki +move` 的区别
|
||||
|
||||
- `drive +move` 只处理 **Drive 文件夹树内部** 的位置调整，目标位置用 `--folder-token` 表示
|
||||
- `wiki +move` 处理的是 **Wiki 知识空间 / 页面层级**：要么移动已有 Wiki 节点，要么把 Drive 文档迁入 Wiki
|
||||
- 如果用户说“移动到某个文件夹”“移动到我的空间根目录”，应使用 `drive +move`
|
||||
- 如果用户说“移动到某个知识库 / 页面下”“迁入 Wiki / 知识空间”，应使用 `wiki +move`
|
||||
- 如果用户说“移动到我的文档库 / 我的知识库 / 个人知识库 / my_library”，不要使用 `drive +move`；先按 Wiki 目标处理
|
||||
- `我的文档库` 不是 Drive root folder，也不是 `--folder-token` 省略后的默认目的地
|
||||
- `drive +move` 不支持 wiki 文档；如果目标是 Wiki，不要尝试用 `drive +move` 代替
|
||||
|
||||
## 不要误用到 `我的文档库`
|
||||
|
||||
下面几种说法都**不应该**触发 `drive +move`：
|
||||
|
||||
- `移动到我的文档库`
|
||||
- `放到我的知识库`
|
||||
- `迁入个人知识库`
|
||||
- `move to My Document Library`
|
||||
|
||||
这些目标都应该先走 Wiki 解析流程：
|
||||
|
||||
```bash
|
||||
lark-cli wiki spaces get --params '{"space_id":"my_library"}'
|
||||
```
|
||||
|
||||
拿到真实 `space_id` 后，再改用 `wiki +move`。不要因为 `drive +move` 可以省略 `--folder-token` 就把它当作“我的文档库”的近似目标。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 移动文件到指定文件夹
|
||||
lark-cli drive +move \
|
||||
--file-token <FILE_TOKEN> \
|
||||
--type file \
|
||||
--folder-token <TARGET_FOLDER_TOKEN>
|
||||
|
||||
# 移动文档到指定文件夹
|
||||
lark-cli drive +move \
|
||||
--file-token <DOCX_TOKEN> \
|
||||
--type docx \
|
||||
--folder-token <TARGET_FOLDER_TOKEN>
|
||||
|
||||
# 移动文件夹（异步操作，会自动有限轮询任务状态）
|
||||
lark-cli drive +move \
|
||||
--file-token <FOLDER_TOKEN> \
|
||||
--type folder \
|
||||
--folder-token <TARGET_FOLDER_TOKEN>
|
||||
|
||||
# 移动到根文件夹（不指定 --folder-token）
|
||||
lark-cli drive +move \
|
||||
--file-token <FILE_TOKEN> \
|
||||
--type file
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file-token` | 是 | 需要移动的文件或文件夹 token |
|
||||
| `--type` | 是 | 文件类型，可选值：`file` (普通文件)、`docx` (新版文档)、`bitable` (多维表格)、`doc` (旧版文档)、`sheet` (电子表格)、`mindnote` (思维笔记)、`folder` (文件夹)、`slides` (幻灯片) |
|
||||
| `--folder-token` | 否 | 目标文件夹 token，不指定则移动到根文件夹 |
|
||||
|
||||
## 文件类型说明
|
||||
|
||||
| 类型 | 说明 |
|
||||
|------|------|
|
||||
| `file` | 普通文件 |
|
||||
| `docx` | 新版云文档 |
|
||||
| `doc` | 旧版云文档 |
|
||||
| `sheet` | 电子表格 |
|
||||
| `bitable` | 多维表格 |
|
||||
| `mindnote` | 思维笔记 |
|
||||
| `slides` | 幻灯片 |
|
||||
| `folder` | 文件夹（移动文件夹是异步操作） |
|
||||
|
||||
## 行为说明
|
||||
|
||||
- **普通文件移动**：同步操作，立即完成
|
||||
- **文件夹移动**：异步操作，接口返回 `task_id`，shortcut 会先做有限轮询；如果在轮询窗口内完成，则直接返回成功结果
|
||||
- **轮询超时不是失败**：文件夹移动内置最多轮询 30 次、每次间隔 2 秒；如果轮询结束任务仍未完成，会返回 `task_id`、`status`、`ready=false`、`timed_out=true` 和 `next_command`
|
||||
- **继续查询**：当看到 `next_command` 时，改用 `lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>` 继续查询
|
||||
- **目标文件夹**：如果不指定 `--folder-token`，文件将被移动到用户的根文件夹（"我的空间"）
|
||||
- **不要混淆产品概念**：这里的“根文件夹 / 我的空间”仅属于 Drive 文件夹树，不等于 Wiki 的“我的文档库”
|
||||
- **权限要求**：需要被移动文件的可管理权限、被移动文件所在位置的编辑权限、目标位置的编辑权限
|
||||
|
||||
## 推荐续跑方式
|
||||
|
||||
```bash
|
||||
# 第一步：先直接移动文件夹
|
||||
lark-cli drive +move \
|
||||
--file-token <FOLDER_TOKEN> \
|
||||
--type folder \
|
||||
--folder-token <TARGET_FOLDER_TOKEN>
|
||||
|
||||
# 如果返回 ready=false / timed_out=true，再继续查
|
||||
lark-cli drive +task_result \
|
||||
--scenario task_check \
|
||||
--task-id <TASK_ID>
|
||||
```
|
||||
|
||||
## 限制
|
||||
|
||||
- 被移动的文件不支持 wiki 文档
|
||||
- 该接口不支持并发调用
|
||||
- 调用频率上限为 5 QPS 且 10000 次/天
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作** —— 执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,41 @@
|
||||
# Drive 权限与授权指南
|
||||
|
||||
> 前置条件：通用认证、scope 与 `--as` 规则见 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
|
||||
|
||||
## 何时读取
|
||||
|
||||
- 用户要修改文档公开权限，尤其是 `drive permission.public patch` 返回 `91009` / `91010` / `91011` / `91012`。
|
||||
- 用户要给文档、文件、文件夹、Wiki 或 slides 增加协作者权限，或把访问权限授予当前应用（bot）自身。
|
||||
- 用户遇到 `permission denied`，但错误表现更像租户对外分享、安全策略或密级拦截，而不是普通 scope 缺失。
|
||||
|
||||
如果用户只是想向文档 owner 申请访问权限，优先使用 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)。
|
||||
|
||||
## 公开权限错误码
|
||||
|
||||
调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。
|
||||
|
||||
| 错误码 | 含义 | 给用户的引导 |
|
||||
|--------|------|--------------|
|
||||
| `91009` | 对外分享被租户安全策略管控，当前用户无法开启 | 提示用户：对外分享能力被租户安全策略统一管控，无法通过 API 或当前用户直接开启；需要联系租户管理员调整组织级对外分享策略。 |
|
||||
| `91010` | 文档对外分享未打开 | 提示用户：当前文档尚未打开对外分享，请先在文档权限设置中打开对外分享，再重试 `permission.public.patch`。 |
|
||||
| `91011` | 对外分享被文档密级管控 | 提示用户：对外分享被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
|
||||
| `91012` | 权限设置被文档密级管控 | 提示用户：该权限设置被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
|
||||
|
||||
当用户最初提供的是文档 URL，遇到 `91011` 或 `91012` 时直接把该 URL 原样返回给用户作为操作入口；如果上下文只有 token，需要先尽量通过已有上下文、搜索结果或元数据恢复目标文档 URL，再给出可点击的文档 URL。
|
||||
|
||||
## 授权当前应用访问文档
|
||||
|
||||
需要将文档权限授予当前应用（bot）自身时：
|
||||
|
||||
1. 先执行 `lark-cli api GET /open-apis/bot/v3/info --as bot`，从返回值取 `bot.open_id`。
|
||||
2. 再调用 `lark-cli drive permission.members create`，用 `member_type=openid`、`member_id=<bot_open_id>` 授权。
|
||||
|
||||
```bash
|
||||
lark-cli drive permission.members create \
|
||||
--params '{"token":"<doc_token>","type":"<resource_type>"}' \
|
||||
--data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
|
||||
```
|
||||
|
||||
此方式仅适用于授权给当前应用。授权给其他用户时，直接使用对方的 open_id，无需调用 bot info 接口。
|
||||
|
||||
`<resource_type>` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。
|
||||
87
.agents/skills/lark-drive/references/lark-drive-preview.md
Normal file
87
.agents/skills/lark-drive/references/lark-drive-preview.md
Normal file
@ -0,0 +1,87 @@
|
||||
## `drive +preview`
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
|
||||
|
||||
列出或下载 Drive 文件可用的预览产物。这个 shortcut 不猜测默认类型：
|
||||
|
||||
- 只想看候选项时，用 `--list-only`
|
||||
- 想下载时，必须显式传 `--type` 和 `--output`
|
||||
- 如果某个候选项还在生成中，会返回结构化错误并提示先重新 `--list-only`
|
||||
|
||||
### 命令
|
||||
|
||||
```bash
|
||||
# 列出可用预览候选项
|
||||
lark-cli drive +preview \
|
||||
--file-token "<FILE_TOKEN>" \
|
||||
--list-only
|
||||
|
||||
# 下载 PDF 预览
|
||||
lark-cli drive +preview \
|
||||
--file-token "<FILE_TOKEN>" \
|
||||
--type pdf \
|
||||
--output ./artifacts/report
|
||||
|
||||
# 下载文本预览，并在目标已存在时自动改名
|
||||
lark-cli drive +preview \
|
||||
--file-token "<FILE_TOKEN>" \
|
||||
--type text \
|
||||
--output ./artifacts/report \
|
||||
--if-exists rename
|
||||
|
||||
# 指定版本号查询/下载
|
||||
lark-cli drive +preview \
|
||||
--file-token "<FILE_TOKEN>" \
|
||||
--version "12" \
|
||||
--type html \
|
||||
--output ./artifacts/report.html
|
||||
```
|
||||
|
||||
### 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file-token` | 是 | Drive 文件 token |
|
||||
| `--type` | 条件必填 | 预览类型；优先使用 `--list-only` 返回的 `type`，如 `pdf` / `html` / `text` / `png` / `jpg` / `source_file` |
|
||||
| `--version` | 否 | 文件版本号 |
|
||||
| `--list-only` | 否 | 仅返回候选项，不下载 |
|
||||
| `--output` | 条件必填 | 下载到本地的输出路径 |
|
||||
| `--if-exists` | 否 | 输出冲突策略：`error`（默认）/ `overwrite` / `rename` |
|
||||
|
||||
### 输出约定
|
||||
|
||||
- 查询态返回：
|
||||
- `mode=list`
|
||||
- `file_token`
|
||||
- `candidates[]`
|
||||
- `next_action`
|
||||
- 下载态返回：
|
||||
- `mode=download`
|
||||
- `file_token`
|
||||
- `selected_type`
|
||||
- `output_path`
|
||||
- `status`
|
||||
|
||||
### 候选项字段
|
||||
|
||||
`candidates[]` 中每个对象包含：
|
||||
|
||||
- `type`
|
||||
- `type_code`
|
||||
- `label`
|
||||
- `status`
|
||||
- `status_code`
|
||||
- `downloadable`
|
||||
- `reason`（可选）
|
||||
|
||||
### 关键约束
|
||||
|
||||
- 不传 `--list-only` 时，必须显式传 `--type` 和 `--output`
|
||||
- 不会隐式选择“第一个候选项”作为默认下载目标
|
||||
- 候选项状态来自后端 `preview_status` 枚举，例如 `READY` / `PROCESSING` / `FAILED` / `NO_SUPPORT`
|
||||
- 本地文件名在未显式带扩展名时，会结合响应头自动补扩展名
|
||||
|
||||
### 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- Drive 总入口
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
137
.agents/skills/lark-drive/references/lark-drive-pull.md
Normal file
137
.agents/skills/lark-drive/references/lark-drive-pull.md
Normal file
@ -0,0 +1,137 @@
|
||||
|
||||
# drive +pull
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
把飞书云空间（云盘/云存储）的某个文件夹**单向、文件级**镜像到本地目录（Drive → 本地）。命令递归列出 `--folder-token` 下所有 `type=file` 的文件，逐一下载到 `--local-dir` 对应的相对路径，子文件夹自动复刻为本地目录。
|
||||
|
||||
> ⚠️ **不是 directory-level mirror**：`--delete-local` 只删除本地"多余"的常规文件，不删除空目录。如果云端把整个子文件夹删了，对应的本地子目录会留空（里面的文件被清掉，目录本身保留）；想精确同步目录结构请自己 `rmdir` 处理空壳。
|
||||
|
||||
输出按"动作"分类：
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `summary.downloaded` | 成功下载的文件数 |
|
||||
| `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需下载”而跳过的文件数 |
|
||||
| `summary.failed` | 下载或写盘失败的文件数 |
|
||||
| `summary.deleted_local` | 启用 `--delete-local --yes` 时删除的本地文件数 |
|
||||
| `items[]` | 每个文件的明细（`rel_path` / `file_token` / `source_id` / `action` / 失败时的 `error`） |
|
||||
|
||||
`summary.failed > 0` 时命令以 **非零状态码**（`exit=1`，`error.type=partial_failure`）退出，且同一份 `summary + items` 会在 `error.detail` 里返回；脚本/agent 直接通过 exit code 判断成败即可，不需要再去解 `summary.failed`。
|
||||
|
||||
## 远端同名文件冲突
|
||||
|
||||
如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（`error.type=duplicate_remote_path`），且不会下载、覆盖或删除任何本地文件。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
|
||||
|
||||
| 策略 | 行为 |
|
||||
|------|------|
|
||||
| `fail` | 默认。返回所有冲突条目的完整信息，不写盘 |
|
||||
| `rename` | 仅适用于 duplicate file。下载全部重复文件；第一个保留原名，后续文件使用稳定 hash 后缀生成唯一文件名；若短后缀目标已被占用，会自动升级到更强后缀 |
|
||||
| `newest` | 只下载 `modified_time` 最新的远端文件 |
|
||||
| `oldest` | 只下载 `created_time` 最早的远端文件 |
|
||||
|
||||
`rename` 命名规则稳定且可追溯：`report.pdf` 的后续重复项会落盘为 `report__lark_<hash>.pdf`，例如 `report__lark_3a2f4c5d6e7f.pdf`。如果这个短 hash 目标名已经被同目录下的其他远端对象占用，CLI 会自动改用更长的稳定 hash，必要时再追加序号后缀，直到目标名唯一。此模式下 `items[]` 不再返回可直接复用的 Drive `file_token`；CLI 会在 `source_id` 中返回稳定 hash 标识符，供日志、比对和人工排查使用。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 基础用法 —— 把云端 fldcXXX 镜像到 ./repo
|
||||
lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx
|
||||
|
||||
# 推荐的重复同步用法：smart 会按 modified_time 跳过已经对齐的本地文件
|
||||
lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--if-exists smart
|
||||
|
||||
# 已存在的本地文件保持不动
|
||||
lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--if-exists skip
|
||||
|
||||
# 云端有多个同名二进制文件时，显式下载全部并用稳定 hash 后缀改名
|
||||
lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--on-duplicate-remote rename
|
||||
|
||||
# 文件级镜像：下载新文件 + 删除云端没有的本地文件（不删空目录）
|
||||
# （--delete-local 必须搭配 --yes，否则会被 Validate 直接拒绝）
|
||||
lark-cli drive +pull --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--delete-local --yes
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 标志 | 必填 | 类型 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃出 cwd 的相对路径会被 CLI 直接拒绝） |
|
||||
| `--folder-token` | 是 | string | 源 Drive 文件夹 token |
|
||||
| `--if-exists` | 否 | enum | 本地文件已存在时的策略：`overwrite`（**默认**，Drive 作为权威源时使用）/ `smart`（**推荐用于重复增量同步**；当本地 mtime 已与远端 `modified_time` 匹配或更新时跳过下载）/ `skip` |
|
||||
| `--on-duplicate-remote` | 否 | enum | 云端多个条目映射到同一个 `rel_path` 时的策略：`fail`（默认）；如果冲突全是 `type=file`，还可选 `rename` / `newest` / `oldest` |
|
||||
| `--delete-local` | 否 | bool | 删除本地"云端没有的常规文件"（**不删空目录**，因此是 file-level mirror）；**必须配合 `--yes`** |
|
||||
| `--yes` | 否 | bool | 确认 `--delete-local`；不传时该破坏性操作在 Validate 阶段被拒绝 |
|
||||
|
||||
## 比较与下载范围
|
||||
|
||||
- **只下载 Drive `type=file` 的二进制文件**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）会被跳过 —— 它们没有等价的本地二进制可写盘，否则会变成产生噪声的"假"下载。
|
||||
- 子文件夹会递归遍历；rel_path 形如 `sub1/sub2/file.txt`，本地缺失的父目录会被自动创建。
|
||||
- 已存在的本地文件按 `--if-exists` 决定 `overwrite` / `smart` / `skip`。其中 **`smart` 是推荐的重复同步模式**：只要本地 mtime 在远端时间精度下已经等于或晚于远端 `modified_time`，就跳过下载；时间戳缺失/非法时会退回安全路径继续下载，不会盲跳。想做 `keep-both` 这类的仍需自己改名再 pull。
|
||||
- 云端同名冲突默认失败；只有“冲突全是 `type=file`”且传了 `--on-duplicate-remote rename|newest|oldest` 时才会继续。
|
||||
|
||||
## --delete-local 的安全行为
|
||||
|
||||
`--delete-local` 是命令里**唯一的破坏性 flag**，会按"本地有但云端没有"清理本地常规文件。设计上把它跟 `--yes` 强绑定，且与下载阶段的失败联动：
|
||||
|
||||
- `--delete-local`（无 `--yes`）→ Validate 直接报错：`--delete-local requires --yes`，没有任何下载、列表请求或删除发生。
|
||||
- `--delete-local --yes`，**且下载阶段全部成功** → 扫一遍 `--local-dir` 下所有常规文件，把不在云端清单里的逐个 `os.Remove`。**只删常规文件，不删目录**：远端文件夹被删除后，对应本地目录会保留空壳。
|
||||
- `--delete-local --yes`，**但下载阶段有任何条目失败** → **跳过整个删除阶段**，命令以 `partial_failure` 非零退出。设计意图：避免出现"前面下载失败、后面继续删本地文件"的半同步状态；操作者修好下载错误后再重跑即可。
|
||||
- 远端同名文件冲突且使用默认 `fail` → 在下载阶段前失败，删除阶段不会运行。
|
||||
- 不传 `--delete-local` → `summary.deleted_local` 永远是 0；命令对本地"多余"文件视而不见。
|
||||
|
||||
第 6 章里把 `+pull --delete-local` 标了 `high-risk-write`，CLI 这边的实现等价于"未传 `--yes` 时拒绝执行"，符合该约束的精神。
|
||||
|
||||
## 输出 schema
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": {
|
||||
"downloaded": 0,
|
||||
"skipped": 0,
|
||||
"failed": 0,
|
||||
"deleted_local": 0
|
||||
},
|
||||
"items": [
|
||||
{"rel_path": "...", "file_token": "...", "action": "downloaded"},
|
||||
{"rel_path": "...", "source_id": "hash_3a2f4c5d6e7f", "action": "downloaded"},
|
||||
{"rel_path": "...", "source_id": "hash_3a2f4c5d6e7f", "action": "failed", "error": "..."},
|
||||
{"rel_path": "...", "action": "deleted_local"},
|
||||
{"rel_path": "...", "action": "delete_failed", "error": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`rel_path` 始终用 `/` 作为分隔符（跨平台一致）。删除条目（`deleted_local` / `delete_failed`）没有 `file_token`。`rename` 模式下，duplicate 文件条目会返回 `source_id` 而不是可调用 API 的真实 `file_token`；其余模式仍返回真实 `file_token`。
|
||||
|
||||
## 性能注意
|
||||
|
||||
- 默认 `overwrite` 下，重复跑会重新下载所有命中的同名文件；`skip` 下则完全不碰已存在文件；**`smart` 下才会按 `modified_time` 跳过已经对齐的本地文件**，适合重复增量同步。
|
||||
- 想更精细地控制下载量，可以先 `+status` 找出 `new_remote` 和 `modified`，再只对这些文件单独 `+download`；或者直接在整目录同步时使用 `--if-exists smart`。
|
||||
- 大文件会用 SDK 的流式下载（不会把整个 body 读进内存），但本地磁盘空间需要够。
|
||||
|
||||
## 所需 scope
|
||||
|
||||
| 操作 | scope |
|
||||
|------|-------|
|
||||
| 列出文件夹 / 子目录 | `drive:drive.metadata:readonly` |
|
||||
| 下载文件 | `drive:file:download` |
|
||||
|
||||
如果当前 token 缺这些 scope，命令会直接报 `missing_scope` 并提示重新登录。`drive:drive` 在部分企业被策略禁用，所以 +pull 故意只声明上面这两个细粒度 scope。
|
||||
|
||||
## 范围限制
|
||||
|
||||
`--local-dir` 只接受 cwd 内的相对路径。CLI 会先 `EvalSymlinks` 整条路径，再判断它是否仍落在 cwd 内 —— **指向 cwd 外的符号链接也会被拒**，"在 cwd 内放一条软链指向外面" 这条捷径走不通，会直接撞上 `unsafe file path`。
|
||||
|
||||
如果用户想 pull 到 cwd 之外的目录，**不要 agent 自己 `cd` 绕过**。可以选：让用户在外部把 agent 工作目录切换到目标的祖先后重启会话；或者把目标整体物理移动 / 拷贝到 cwd 内（不是软链）；或者直接放弃这次同步，改用别的方式。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) —— 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
|
||||
- [lark-drive-status](lark-drive-status.md) —— 下载前先看差异
|
||||
- [lark-drive-download](lark-drive-download.md) —— 单文件按需拉取
|
||||
162
.agents/skills/lark-drive/references/lark-drive-push.md
Normal file
162
.agents/skills/lark-drive/references/lark-drive-push.md
Normal file
@ -0,0 +1,162 @@
|
||||
|
||||
# drive +push
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
把本地目录**单向、文件级**镜像到飞书云空间（云盘/云存储）的某个文件夹（本地 → Drive）。命令递归列出 `--folder-token` 下的远端清单，遍历 `--local-dir` 的所有常规文件，按相对路径在 Drive 上新建、覆盖或跳过；可选地（`--delete-remote --yes`）删除云端"本地没有"的 `type=file`。
|
||||
|
||||
> **"文件级镜像"≠"目录镜像"。** 命令只在文件维度收敛差异：本地多了文件就上传，本地少了文件且开了 `--delete-remote --yes` 就删远端文件。**远端只有的空目录、本地已删除的目录**都不会被收敛，云端目录树的多余结构不会被清理。如果需要"目录也要保持完全一致"，得自行先 `+status` 找差异、再手动处理多余目录。
|
||||
|
||||
输出按"动作"分类：
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `summary.uploaded` | 成功新建或覆盖的文件数 |
|
||||
| `summary.skipped` | 因 `--if-exists=skip` 或 `--if-exists=smart` 命中“无需传输”而跳过的文件数 |
|
||||
| `summary.failed` | 上传 / 覆盖 / 建目录 / 删除失败的条目数；**只要不为 0，命令就以非零状态退出**（结构化 `items[]` 仍在 stdout 上） |
|
||||
| `summary.deleted_remote` | 启用 `--delete-remote --yes` 时删除的云端文件数 |
|
||||
| `items[]` | 每个条目的明细（`rel_path` / `file_token` / `action` / 覆盖时的 `version` / `size_bytes` / 失败时的 `error`） |
|
||||
|
||||
`items[].action` 取值：`uploaded` / `overwritten` / `skipped` / `folder_created` / `deleted_remote` / `failed` / `delete_failed`。
|
||||
|
||||
> 本地目录（包括空目录）会被镜像到 Drive；新建的子目录会以 `action: "folder_created"` 出现在 `items[]` 里，但**不计入** `summary.uploaded`（该字段只数文件）。已存在的远端目录复用其 token，不会重复 `create_folder`，也不会出现在 `items[]` 里。
|
||||
|
||||
## 远端同名文件冲突
|
||||
|
||||
如果 Drive 中多个条目映射到同一个 `rel_path`，默认直接失败（`error.type=duplicate_remote_path`），且不会上传、覆盖或进入 `--delete-remote` 删除阶段。只有“多个 `type=file` 同名”的场景支持显式策略；`file-folder` 这类异构冲突始终直接失败。
|
||||
|
||||
| 策略 | 行为 |
|
||||
|------|------|
|
||||
| `fail` | 默认。返回所有冲突条目的完整信息，不写远端 |
|
||||
| `newest` | 只把本地文件与 `modified_time` 最新的远端文件对齐 |
|
||||
| `oldest` | 只把本地文件与 `created_time` 最早的远端文件对齐 |
|
||||
|
||||
`+push` 不提供 `rename`：本地一个文件无法表达要覆盖多个远端对象。若用户想保留多个云端副本，应先显式整理云端文件，再重新 push。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 基础用法 —— 把本地 ./repo 推送到云端 fldcXXX
|
||||
# 默认 --if-exists=skip：已经存在的远端文件保持不动，只新增、不覆盖。
|
||||
lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx
|
||||
|
||||
# 重复同步时可用 smart 做增量优化：它会按 modified_time 跳过已对齐的远端文件；但如果远端更旧，仍会继续走覆盖路径
|
||||
lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--if-exists smart
|
||||
|
||||
# 显式覆盖远端同名文件（依赖 upload_all 的灰度协议字段，详见下文"覆盖语义"）
|
||||
lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--if-exists overwrite
|
||||
|
||||
# 云端已有多个同名二进制文件时，显式选择一个远端目标再覆盖
|
||||
lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--if-exists overwrite --on-duplicate-remote newest
|
||||
|
||||
# 文件级镜像同步：上传 / 覆盖 + 删除本地不存在的远端文件
|
||||
# （--delete-remote 必须搭配 --yes，否则会被 Validate 直接拒绝；
|
||||
# 且 Validate 阶段会动态检查 space:document:delete scope，缺权限会立刻失败，
|
||||
# 不会出现"上传成功了但是后面删除阶段挂了"的半同步状态）
|
||||
lark-cli drive +push --local-dir ./repo --folder-token fldcnxxxxxxxxx \
|
||||
--if-exists overwrite --delete-remote --yes
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 标志 | 必填 | 类型 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃出 cwd 的相对路径会被 CLI 直接拒绝） |
|
||||
| `--folder-token` | 是 | string | 目标 Drive 文件夹 token |
|
||||
| `--if-exists` | 否 | enum | 远端文件已存在时的策略：`skip`（**默认**，安全）/ `smart`（用于重复增量同步；当远端 `modified_time` 已匹配或更新时跳过上传，否则继续走覆盖路径）/ `overwrite`（依赖灰度后端协议，详见"覆盖语义"） |
|
||||
| `--on-duplicate-remote` | 否 | enum | 云端多个条目映射到同一个 `rel_path` 时的策略：`fail`（默认）；如果冲突全是 `type=file`，还可选 `newest` / `oldest` |
|
||||
| `--delete-remote` | 否 | bool | 删除云端本地不存在的文件（文件级镜像；**不会**清理远端只有的目录）；**必须配合 `--yes`**，且 Validate 阶段会动态检查 `space:document:delete` scope |
|
||||
| `--yes` | 否 | bool | 确认 `--delete-remote`；不传时该破坏性操作在 Validate 阶段被拒绝 |
|
||||
|
||||
## 上传与目录复刻范围
|
||||
|
||||
- **只上传 / 覆盖 / 删除 Drive `type=file`**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）即使在同一 rel_path 下出现，也不会被覆盖或删除 —— 它们没有等价的本地二进制。
|
||||
- **本地目录结构整体被镜像**：所有子目录（含**空目录**）会按需在 Drive 上 `create_folder`；同名远端目录复用其 token，不重建。空目录不计入 `summary.uploaded`，但会在 `items[]` 里以 `folder_created` 形式留痕。
|
||||
- 已存在的远端文件按 `--if-exists` 决定 `overwrite` / `smart` / `skip`。其中 `smart` 是**增量优化模式**：只要远端 `modified_time` 在同等时间精度下已经等于或晚于本地 mtime，就跳过上传；时间戳缺失/非法时会退回安全路径继续上传，不会盲跳。**但如果远端更旧，`smart` 会继续走和 `overwrite` 相同的覆盖路径，因此也继承同样的 rollout / version 返回 caveat。** 想做 `keep-both` 这类的仍需自行改名再 push。
|
||||
- 云端同名冲突默认失败；只有“冲突全是 `type=file`”且传了 `--on-duplicate-remote newest|oldest` 时才会选择一个远端文件继续。启用 `--delete-remote` 时，未被选中的 duplicate sibling 也会被删除，最终远端只保留一个被选中的文件副本；只有在 `--if-exists=overwrite` 成功时，才能保证该副本内容与本地对齐。
|
||||
|
||||
## 覆盖语义
|
||||
|
||||
`--if-exists=overwrite` 走 `POST /open-apis/drive/v1/files/upload_all`，并在 form 中带上现有文件的 `file_token`，由后端原地更新内容并返回新版本号。`items[].version` 字段会回填该版本号。
|
||||
|
||||
`--if-exists=smart` 是给“重复跑同步”的场景增加的增量优化：当远端 `modified_time` 在同等时间精度下已经等于或晚于本地 mtime 时，命令会把该文件计为 `skipped`；时间戳缺失、非法或更旧时，则继续走正常上传/覆盖路径。**也就是说，只要 smart 判定“远端不够新”，它就会进入与 `--if-exists=overwrite` 相同的覆盖实现，因此在未 rollout version 字段的 tenant 上仍可能非零失败。**
|
||||
|
||||
> **为什么默认是 `skip` 而不是 `overwrite`：** `upload_all` 接受 `file_token` 字段、并在响应里返回 `version` 是设计文档（Drive 同步盘）规定的协议；此后端尚在灰度发布。在还未开通该字段的 tenant 上，`--if-exists=overwrite` 会因"无 version 返回"而把对应文件标成 `failed`，整次 `+push` 也会因此非零退出。所以默认值故意定为 `skip`：第一次往一个已经有内容的目录里 push，不会因为协议没到位就把整次运行打挂；要真的覆盖远端，必须显式带 `--if-exists overwrite`。新建上传不依赖该字段，不受影响。
|
||||
|
||||
大文件（>20MB）会自动切到三段式 `upload_prepare` / `upload_part` / `upload_finish`；该路径下 `version` 暂未在响应中返回，覆盖结果中 `items[].version` 会留空，但 `file_token` 与 `action: overwritten` 仍会正确产出。
|
||||
|
||||
## --delete-remote 的安全行为
|
||||
|
||||
`--delete-remote` 是命令里**唯一的破坏性 flag**，会按"远端有但本地没有"逐个 `DELETE /open-apis/drive/v1/files/<token>?type=file` 清理云端副本。设计上把它跟 `--yes` 强绑定：
|
||||
|
||||
- `--delete-remote`（无 `--yes`）→ Validate 直接报错：`--delete-remote requires --yes`，不会发起任何列表 / 上传 / 删除请求。
|
||||
- `--delete-remote --yes` → Validate 阶段还会**动态做一次** `space:document:delete` 的 scope 预检：缺这条 scope 时整次运行立刻失败、不发任何上传请求，避免出现"上传都成功了，但删除阶段才报 missing_scope"的半同步状态。
|
||||
- `--delete-remote --yes`（且 scope 已授权）→ 正常执行：先把本地文件 push 上去，再扫一遍远端 `type=file` 列表，把不在本地清单里的逐个删除。**任何上传 / 覆盖 / 建目录失败时，整段 `--delete-remote` 阶段会被跳过**（stderr 上有提示），命令以非零状态退出，远端不会被破坏。
|
||||
- 远端同名冲突且使用默认 `fail`，或冲突里混有 folder / 其他非 `type=file` 对象 → 在上传阶段前失败，删除阶段不会运行。
|
||||
- 不传 `--delete-remote` → `summary.deleted_remote` 永远是 0；命令对远端"多余"文件视而不见。
|
||||
- 在线文档（docx / sheet / bitable / ...）和快捷方式即使本地完全没有同名文件，也**不会**进入删除候选，因为它们从来不进 `summary.uploaded` 的对齐域。
|
||||
- **远端只有的空目录、本地已删除的目录**也不会被清理 —— 这是"文件级镜像"的语义边界，命令不会对目录结构做主动收敛。
|
||||
|
||||
第 6 章里把 `+push --delete-remote` 标了 `high-risk-write`，CLI 这边的实现等价于"未传 `--yes` 时拒绝执行 + 动态 scope 预检"，符合该约束的精神。
|
||||
|
||||
## 输出 schema
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": {
|
||||
"uploaded": 0,
|
||||
"skipped": 0,
|
||||
"failed": 0,
|
||||
"deleted_remote": 0
|
||||
},
|
||||
"items": [
|
||||
{"rel_path": "...", "file_token": "...", "action": "folder_created"},
|
||||
{"rel_path": "...", "file_token": "...", "action": "uploaded", "size_bytes": 0},
|
||||
{"rel_path": "...", "file_token": "...", "action": "overwritten", "version": "...", "size_bytes": 0},
|
||||
{"rel_path": "...", "file_token": "...", "action": "skipped", "size_bytes": 0},
|
||||
{"rel_path": "...", "action": "failed", "size_bytes": 0, "error": "..."},
|
||||
{"rel_path": "...", "file_token": "...", "action": "deleted_remote"},
|
||||
{"rel_path": "...", "file_token": "...", "action": "delete_failed", "error": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`rel_path` 始终用 `/` 作为分隔符（跨平台一致）。
|
||||
|
||||
## 性能注意
|
||||
|
||||
- 默认 `skip` 下，已存在的远端文件一律不碰；`overwrite` 下，重复跑会重传所有命中的同名文件；`smart` 下会按 `modified_time` 跳过已对齐的远端文件，但对“远端更旧”的文件仍会进入覆盖路径，因此它减少的是**不必要的重传**，不是把覆盖风险完全拿掉。
|
||||
- 想更精细地控制传输量，可以先 `+status` 找出 `new_local` 和 `modified`，再只对这些文件单独上传 / 覆盖；或者直接在整目录同步时使用 `--if-exists smart`。
|
||||
- 大文件会用三段式分片上传（不会把整个 body 读进内存），但本地磁盘和上行带宽需要够。
|
||||
|
||||
## 所需 scope
|
||||
|
||||
| 操作 | scope | 是否在命令上预声明 |
|
||||
|------|-------|-------------------|
|
||||
| 列出文件夹 / 子目录 | `drive:drive.metadata:readonly` | ✅ 预声明 |
|
||||
| 上传 / 覆盖文件 | `drive:file:upload` | ✅ 预声明 |
|
||||
| 新建子目录（`create_folder`） | `space:folder:create` | ✅ 预声明 |
|
||||
| 删除文件（仅 `--delete-remote --yes`） | `space:document:delete` | ⚙️ 不在命令默认 Scopes 里，但在 `--delete-remote --yes` 时由 Validate 动态预检 |
|
||||
|
||||
`drive:drive` 在部分企业被策略禁用，所以 +push 故意只声明上面这几条细粒度 scope。
|
||||
|
||||
> **关于 `space:document:delete`：** 框架的 scope 预检（`runner.go: checkShortcutScopes`）会在 `Validate` 和 `--dry-run` 之前就把命令上声明的 scope 全检查一遍；如果把删除 scope 也预声明，**普通上传或 dry-run** 都会因为没授权删除权限而被拦下来。所以这一项不放在命令的默认 Scopes 里，而是在 Validate 中**条件触发**：只有 `--delete-remote --yes` 同时打开时才会调用 `runtime.EnsureScopes([]string{"space:document:delete"})` 做一次动态前置校验。这样既保留了"普通上传不需要删除权限"的便利，又能在真要做镜像删除前把 scope 缺失暴露出来，避免出现"上传成功 → 删除阶段才挂"的半同步状态。
|
||||
>
|
||||
> 想一次性把权限补齐：`lark-cli auth login --scope "drive:drive.metadata:readonly drive:file:upload space:folder:create space:document:delete"`。
|
||||
|
||||
## 范围限制
|
||||
|
||||
`--local-dir` 只接受 cwd 内的相对路径。CLI 会先 `EvalSymlinks` 整条路径，再判断它是否仍落在 cwd 内 —— **指向 cwd 外的符号链接也会被拒**，"在 cwd 内放一条软链指向外面" 这条捷径走不通，会直接撞上 `unsafe file path`。
|
||||
|
||||
如果用户想 push cwd 之外的目录，**不要 agent 自己 `cd` 绕过**。可以选：让用户在外部把 agent 工作目录切换到目标的祖先后重启会话；或者把目标整体物理移动 / 拷贝到 cwd 内（不是软链）；或者直接放弃这次同步，改用别的方式。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) —— 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
|
||||
- [lark-drive-status](lark-drive-status.md) —— 上传前先看差异（避免全量回写）
|
||||
- [lark-drive-pull](lark-drive-pull.md) —— Drive → 本地的对称命令
|
||||
- [lark-drive-upload](lark-drive-upload.md) —— 单文件按需上传
|
||||
113
.agents/skills/lark-drive/references/lark-drive-reactions.md
Normal file
113
.agents/skills/lark-drive/references/lark-drive-reactions.md
Normal file
@ -0,0 +1,113 @@
|
||||
# drive reactions
|
||||
|
||||
> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论入口，再阅读 [`lark-drive-comments-guide.md`](lark-drive-comments-guide.md) 了解评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；同时阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才带 `need_reaction=true`；写入时统一使用 `drive file.comment.reply.reactions update_reaction`，操作对象始终是 `reply_id`。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **`reaction_type` 只能使用本文下方“完整 `reaction_type` 列表”中定义的枚举值。**
|
||||
> 不要自由填写、不要根据自然语言临时编造、也不要把列表里的 mixed-case 值改写成别的大小写形式。需要写入时，只能从下方枚举中原样选择并传参。
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 用户明确要求查看评论 / 回复上的 reaction（表情）。
|
||||
- 用户要统计某条评论卡片有哪些表情、各表情数量，或要看谁点了什么。
|
||||
- 用户要给评论或回复添加 / 删除 reaction。
|
||||
|
||||
## 查询规则
|
||||
|
||||
- `drive file.comments list`、`drive file.comments batch_query`、`drive file.comment.replys list` 都支持通过指定`need_reaction`查询reaction信息。
|
||||
- `need_reaction` 只在用户明确需要 reaction 信息时再带；如果用户只关心评论正文、回复正文、评论数 / 回复数，默认不要加。
|
||||
- 遍历评论卡片并顺带拿 reaction：使用 `drive file.comments list`。
|
||||
- 已知评论 ID，批量查看 reaction：使用 `drive file.comments batch_query`，并在请求体里带 `need_reaction=true`。
|
||||
- 某张评论卡片下继续翻页拉 reply reaction：使用 `drive file.comment.replys list`。
|
||||
- 如果 `drive file.comments list` 返回的某个 `item.has_more=true`，且用户要完整的 reply reaction 数据，后续每一页 `drive file.comment.replys list` 都要持续带 `need_reaction=true`。
|
||||
|
||||
## 查询示例
|
||||
|
||||
```bash
|
||||
# 遍历评论卡片，并把 reaction 一起拿回来
|
||||
lark-cli drive file.comments list \
|
||||
--params '{"file_token":"<DOC_TOKEN>","file_type":"docx","need_reaction":true}'
|
||||
|
||||
# 已知 comment_id，批量查询评论卡片 reaction
|
||||
lark-cli drive file.comments batch_query \
|
||||
--params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
|
||||
--data '{"comment_ids":["<COMMENT_ID>"],"need_reaction":true}'
|
||||
|
||||
# 继续翻某张评论卡片下的 replies，并把 reaction 一起拿回来
|
||||
lark-cli drive file.comment.replys list \
|
||||
--params '{"file_token":"<DOC_TOKEN>","comment_id":"<COMMENT_ID>","file_type":"docx","need_reaction":true}'
|
||||
```
|
||||
|
||||
## 写入规则
|
||||
|
||||
- 添加 / 删除 reaction 时，使用 `drive file.comment.reply.reactions update_reaction`。
|
||||
- 请求里必须带正确的 `file_type`，并在 body 中传 `action=add|delete`、`reply_id`、`reaction_type`。
|
||||
- `update_reaction` 的操作对象是 `reply_id`，不是 `comment_id`。
|
||||
- 如果用户说要给“这条评论”加 / 删 reaction，通常需要定位到该评论卡片首条 reply 的 `reply_id` 再操作。
|
||||
|
||||
## 写入示例
|
||||
|
||||
```bash
|
||||
# 给某条 reply 添加一个点赞 reaction
|
||||
lark-cli drive file.comment.reply.reactions update_reaction \
|
||||
--params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
|
||||
--data '{"action":"add","reply_id":"<REPLY_ID>","reaction_type":"THUMBSUP"}'
|
||||
|
||||
# 删除某条 reply 上已有的 DONE reaction
|
||||
lark-cli drive file.comment.reply.reactions update_reaction \
|
||||
--params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}' \
|
||||
--data '{"action":"delete","reply_id":"<REPLY_ID>","reaction_type":"DONE"}'
|
||||
```
|
||||
|
||||
> [!CAUTION]
|
||||
> `update_reaction` 是写入操作。执行前必须确认用户意图，不要默认替用户点表情。
|
||||
|
||||
## `reaction_type` 使用规则
|
||||
|
||||
- `reaction_type` 必须传平台定义的枚举字符串，大小写敏感。
|
||||
- 不要擅自把 mixed-case 值改成全大写，例如 `Yes`、`No`、`Get`、`EatingFood`、`CheckMark`、`CrossMark` 都要按原值传。
|
||||
- **不要编造列表外的 `reaction_type`，也不要把自然语言描述臆造成平台未定义的新枚举**。
|
||||
- 如果用户给的是自然语言语义（如“点赞”“在处理中”“确认一下”），可以在下方枚举列表内选择语义最接近的现有值；如果是近似映射，应在执行时明确告知用户。
|
||||
|
||||
## 常见语义联想
|
||||
|
||||
- `Yes`：确认 / 同意 / 批准。
|
||||
- `No`：拒绝 / 不同意 / 否定。
|
||||
- `DONE`：已完成 / 已处理。
|
||||
- `Typing`：正在输入 / 正在处理中 / 正在跟进（近似语义）。
|
||||
- `OK`：好的 / 收到 / 确认一下。
|
||||
- `THUMBSUP`：点赞 / 认可。
|
||||
- `LGTM`：看起来没问题 / 可以继续。
|
||||
|
||||
## 完整 `reaction_type` 列表
|
||||
|
||||
以下枚举按当前 Drive 评论 reaction 指引维护，使用时请保持原样：
|
||||
|
||||
```text
|
||||
ANGRY, APPLAUSE, ATTENTION, AWESOME, BEAR, BEER, BETRAYED, BIGKISS
|
||||
BLACKFACE, BLUBBER, BLUSH, BOMB, CAKE, CHUCKLE, CLAP, CLEAVER
|
||||
COMFORT, CRAZY, CRY, CUCUMBER, DETERGENT, DIZZY, DONE, DONNOTGO
|
||||
DROOL, DROWSY, DULL, DULLSTARE, EATING, EMBARRASSED, ENOUGH, ERROR
|
||||
EYESCLOSED, FACEPALM, FINGERHEART, FISTBUMP, FOLLOWME, FROWN, GIFT, GLANCE
|
||||
GOODJOB, HAMMER, HAUGHTY, HEADSET, HEART, HEARTBROKEN, HIGHFIVE, HUG
|
||||
HUSKY, INNOCENTSMILE, JIAYI, JOYFUL, KISS, LAUGH, LIPS, LOL
|
||||
LOOKDOWN, LOVE, MONEY, MUSCLE, NOSEPICK, OBSESSED, OK, PARTY
|
||||
PETRIFIED, POOP, PRAISE, PROUD, PUKE, RAINBOWPUKE, ROSE, SALUTE
|
||||
SCOWL, SHAKE, SHHH, SHOCKED, SHOWOFF, SHY, SICK, SILENT
|
||||
SKULL, SLAP, SLEEP, SLIGHT, SMART, SMILE, SMIRK, SMOOCH
|
||||
SMUG, SOB, SPEECHLESS, SPITBLOOD, STRIVE, SWEAT, TEARS, TEASE
|
||||
TERROR, THANKS, THINKING, THUMBSUP, TOASTED, TONGUE, TRICK, UPPERLEFT
|
||||
WAIL, WAVE, WELLDONE, WHAT, WHIMPER, WINK, WITTY, WOW
|
||||
WRONGED, XBLUSH, YAWN, YEAH, FIREWORKS, BULL, CALF, AWESOMEN
|
||||
2021, CANDIEDHAWS, REDPACKET, FORTUNE, LUCK, FIRECRACKER, Yes, No
|
||||
Get, LGTM, Lemon, EatingFood, Hundred, MinusOne, ThumbsDown, Fire
|
||||
OKR, Drumstick, BubbleTea, Loudspeaker, Pin, Coffee, Alarm, Trophy
|
||||
Music, Typing, Pepper, CheckMark, CrossMark
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
266
.agents/skills/lark-drive/references/lark-drive-search.md
Normal file
266
.agents/skills/lark-drive/references/lark-drive-search.md
Normal file
@ -0,0 +1,266 @@
|
||||
|
||||
# drive +search（云空间/云盘/云存储搜索：扁平 flag，面向自然语言场景）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
基于 Search v2 接口 `POST /open-apis/search/v2/doc_wiki/search`，以**用户身份**统一搜索云空间（云盘/云存储）对象。
|
||||
|
||||
核心特性：
|
||||
|
||||
- 把常用过滤条件全部**扁平化为独立 flag**（`--edited-since`、`--mine`、`--doc-types`、`--folder-tokens` 等），不再要求用户或 AI 手写嵌套 `--filter` JSON
|
||||
- 额外暴露了 4 个"我"维度：`my_edit_time`（我编辑过）、`my_comment_time`（我评论过）、`open_time`（我打开过）、`create_time`（文档创建时间）——直接对应用户自然语言里的"最近我编辑过的"、"我评论过的"等表达
|
||||
- 自动处理 `my_edit_time` / `my_comment_time` 的小时级聚合（服务端存储粒度）：亚小时输入会向整点 snap，并在 stderr 打出提示
|
||||
- `--mine` 一键从当前登录用户的 open_id 填 `creator_ids`，不必再先去查 contact（注意 `creator_ids` 服务端按 **owner / 文档归属人** 语义匹配，不是“最初创建人”，详见下文「身份维度」）
|
||||
|
||||
> **资源发现入口统一**：`drive +search` 同样返回 `SHEET` / `Base` / `FOLDER` 等全部云空间（云盘/云存储）对象，不只是文档 / Wiki。用户说"找一个表格"、"找报表"、"最近打开的表格"时，也从这里开始；定位后再切到对应业务 skill（如 `lark-sheets`）做对象内部操作。
|
||||
|
||||
## 命令
|
||||
|
||||
> **关键约束：搜索关键词必须通过 `--query` 传递。**
|
||||
> 正确：`lark-cli drive +search --query "方案"`
|
||||
> 错误：`lark-cli drive +search 方案`
|
||||
> `+search` 不接受位置参数；空 `--query` 或省略 `--query` 表示纯靠 filter 浏览（合法）。
|
||||
>
|
||||
> **列表型请求不要硬塞关键词**：如果用户只是要求"我这月创建的所有文档"、"最近半年我编辑过的文档"、"按类型分类统计"这类范围浏览 / 汇总请求，且没有给出标题片段或业务关键词，应使用 `--query ""` 搭配 `--mine`、`--created-*`、`--edited-*`、`--doc-types` 等过滤条件。不要把"查找"、"所有文档"、"最近更新过"、"按类型分类统计"这类动作词或统计意图放进 `--query`，否则会把本来应靠 filter 命中的结果过度收窄。
|
||||
|
||||
### 自然语言 → 命令映射速查
|
||||
|
||||
| 用户说 | 命令 |
|
||||
|---|---|
|
||||
| 我这月创建的所有文档，按类型分类统计 | `lark-cli drive +search --query "" --mine --created-since "<YYYY-MM-DD>" --created-until "<YYYY-MM-DD>"` |
|
||||
| 最近半年我编辑过的文档，看看哪些最近更新过 | `lark-cli drive +search --query "" --edited-since 6m --sort edit_time` |
|
||||
| 最近一个月我编辑过的文档 | `lark-cli drive +search --query "" --edited-since 1m` |
|
||||
| 最近一个月我编辑过 且 我评论过的 | `lark-cli drive +search --query "" --edited-since 1m --commented-since 1m` |
|
||||
| 最近一周我打开过的表格 | `lark-cli drive +search --query "" --opened-since 7d --doc-types sheet` |
|
||||
| 我 owner 的所有文档（owner 语义，非"我最初创建"） | `lark-cli drive +search --query "" --mine` |
|
||||
| 我 owner、30-60 天前创建的文档（粗略"上个月"，按 30 天滑窗算；`--mine` 是 owner，`--created-*` 才是文档创建时间） | `lark-cli drive +search --query "" --mine --created-since 2m --created-until 1m` |
|
||||
| 我 owner、2026 年 3 月创建的文档（精确日历月；同上，owner + 创建时间窗两个维度） | `lark-cli drive +search --query "" --mine --created-since 2026-03-01 --created-until 2026-04-01` |
|
||||
| 关键词"预算"，最近一周我打开过，按编辑时间降序 | `lark-cli drive +search --query 预算 --opened-since 7d --sort edit_time` |
|
||||
| 某个 wiki space 下、我 owner 且 30-60 天前创建的 | `lark-cli drive +search --query "" --mine --space-ids space_xxx --created-since 2m --created-until 1m` |
|
||||
| 张三 owner / 负责的文档（注意是 owner 语义，不是张三最初创建的）| `lark-cli drive +search --query "" --creator-ids ou_zhangsan` |
|
||||
| 我最近 3 个月评论过的 docx | `lark-cli drive +search --query "" --commented-since 3m --doc-types docx` |
|
||||
|
||||
### 更多示例
|
||||
|
||||
```bash
|
||||
# 纯关键词搜索
|
||||
lark-cli drive +search --query "季度总结"
|
||||
|
||||
# 使用服务端 query 高级语法
|
||||
lark-cli drive +search --query 'intitle:方案'
|
||||
lark-cli drive +search --query '"季度 总结"'
|
||||
lark-cli drive +search --query '方案 OR 草稿'
|
||||
lark-cli drive +search --query '方案 -草稿'
|
||||
|
||||
# 只搜某个文件夹下的文档
|
||||
lark-cli drive +search --query 方案 --folder-tokens fld_123456
|
||||
|
||||
# 只搜某个知识空间下的 Wiki
|
||||
lark-cli drive +search --query 研发规范 --space-ids space_1234567890fedcba
|
||||
|
||||
# 指定群内分享过的文档
|
||||
lark-cli drive +search --query 方案 --chat-ids oc_1234567890abcdef
|
||||
|
||||
# 只搜标题 / 只搜评论
|
||||
lark-cli drive +search --query 周报 --only-title
|
||||
lark-cli drive +search --query 延期原因 --only-comment
|
||||
|
||||
# 人类可读格式
|
||||
lark-cli drive +search --query OKR --format pretty
|
||||
|
||||
# 翻页（--format json 先拿 page_token）
|
||||
lark-cli drive +search --query 方案 --format json
|
||||
lark-cli drive +search --query 方案 --page-token '<PAGE_TOKEN>'
|
||||
```
|
||||
|
||||
### 列表 / 统计型请求的执行步骤
|
||||
|
||||
对"所有文档"、"按类型分类统计"、"最近更新过"这类请求，不要只跑一次搜索后直接回答。标准流程：
|
||||
|
||||
1. 先把自然语言拆成过滤条件：所有权（`--mine` / `--creator-ids`）、时间维度（`--created-*` / `--edited-*` / `--opened-*` / `--commented-*`）、类型（`--doc-types`）、空间或文件夹范围。
|
||||
2. 没有真实业务关键词时保持 `--query ""`；不要把"所有文档"、"统计"、"最近更新"放进 query。
|
||||
3. 检查返回结果的 `doc_type` / `result_meta.doc_types`、创建/编辑时间和 URL/token 是否与过滤目标一致；明显不符合的结果不要计入答案。
|
||||
4. 用户要求"所有 / 全量 / 统计"时按 `has_more` 翻页并累积去重；不要只用第一页推断总量。返回体里的 `total` 不可靠，统计要以实际去重后的结果为准。
|
||||
5. 汇总时按真实返回字段分组，例如按 `doc_type` 统计 DOCX、SHEET、BITABLE、WIKI、FILE 等，不要凭标题猜类型。
|
||||
|
||||
### 内容检索型请求的 query 扩展
|
||||
|
||||
用户问的是原因、结论、方案、对比等内容问题时，`--query` 应保留业务关键词，但不要只用整句原问。先用核心实体 + 主题词搜索，再按结果调整：
|
||||
|
||||
- "东南亚服务器成本为何较其他区域贵" → 先搜 `"东南亚 服务器 成本"`，如果召回不足，再搜 `"服务器 成本 区域"`、`"非洲 欧洲 服务器 成本"`、`"机房 成本 费用"` 等同主题扩展词。
|
||||
- "某项目发布会重点" → 先搜项目名 + "发布会" + "重点/功能/一览"，再按标题和摘要判断是否需要只搜标题或扩大到正文。
|
||||
|
||||
每轮扩展都要保留非污染、可解释的 evidence（URL/token/标题/摘要）；不能因为某个扩展词搜到高相似标题就跳过证据核验。
|
||||
|
||||
## 参数
|
||||
|
||||
### 核心
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|---|---|---|
|
||||
| `--query <text>` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览 |
|
||||
| `--page-size <n>` | 否 | 每页数量，默认 15，最大 20。超过 20 自动 clamp；非正数（≤0）回落 15；**非数字值直接返回 validation 错误** |
|
||||
| `--page-token <token>` | 否 | 上一次响应里的 `page_token`，用于翻页 |
|
||||
| `--format` | 否 | `json`（默认）/ `pretty` |
|
||||
|
||||
### 身份（owner 维度，API 字段名 `creator_ids`）
|
||||
|
||||
> **语义说明（重要）**：`creator_ids`（含 `--mine` / `--creator-ids`）虽然 OpenAPI 字段名是 “creator”，但服务端实际按 **owner（文档归属人 / 负责人）** 语义匹配，**不是“最初创建人”**：我创建后转交他人的文档不会命中，他人创建后转给我（我成为 owner）的会命中。用户说“我的 / 我创建的 / 我负责的”文档都路由到 `--mine`，但要清楚它返回的是“我 owner 的”。
|
||||
|
||||
| 参数 | 映射 | 说明 |
|
||||
|---|---|---|
|
||||
| `--mine` | `creator_ids = [当前用户 open_id]` | bool。一键“我 owner 的”（**不是**“我最初创建的”）；从当前登录用户身份（`runtime.UserOpenId()`）解析 open_id，取不到直接报错（提示运行 `lark-cli auth login`） |
|
||||
| `--creator-ids ou_x,ou_y` | `creator_ids = [...]` | 显式 open_id 列表，逗号分隔，按 **owner** 匹配；**与 `--mine` 互斥** |
|
||||
|
||||
### 时间维度（每个维度一对 since/until）
|
||||
|
||||
| 参数 | 映射 API 字段 | 是否小时 snap |
|
||||
|---|---|---|
|
||||
| `--edited-since` / `--edited-until` | `my_edit_time.start` / `.end` | ✅ start 向下取整，end 向上取整 |
|
||||
| `--commented-since` / `--commented-until` | `my_comment_time.start` / `.end` | ✅ 同上 |
|
||||
| `--opened-since` / `--opened-until` | `open_time.start` / `.end` | ❌ 原样透传 |
|
||||
| `--created-since` / `--created-until` | `create_time.start` / `.end` | ❌ 原样透传（文档创建时间，非"我"语义）|
|
||||
|
||||
### 作用域
|
||||
|
||||
| 参数 | 映射 | 说明 |
|
||||
|---|---|---|
|
||||
| `--doc-types docx,sheet` | `doc_types` | 逗号分隔。允许值：`doc,sheet,bitable,mindnote,file,wiki,docx,folder,catalog,slides,shortcut` |
|
||||
| `--folder-tokens fld_a,fld_b` | `folder_tokens`（仅 doc_filter） | 存在时只发 `doc_filter`；**与 `--space-ids` 互斥** |
|
||||
| `--space-ids sp_x` | `space_ids`（仅 wiki_filter） | 存在时只发 `wiki_filter`；**与 `--folder-tokens` 互斥** |
|
||||
| `--chat-ids oc_x` | `chat_ids` | 逗号分隔 |
|
||||
| `--sharer-ids ou_x` | `sharer_ids` | 逗号分隔，open_id |
|
||||
|
||||
### 其他
|
||||
|
||||
| 参数 | 映射 | 说明 |
|
||||
|---|---|---|
|
||||
| `--only-title` | `only_title: true` | bool |
|
||||
| `--only-comment` | `only_comment: true` | bool |
|
||||
| `--sort <value>` | `sort_type`（转大写枚举） | 允许值：`default, edit_time, edit_time_asc, open_time, create_time` |
|
||||
|
||||
> `--sort`：CLI 只暴露服务端**正式支持**的 5 个值。服务端 enum 里 `CREATE_TIME_ASC` 协议标注"暂不支持"，`ENTITY_CREATE_TIME_ASC` / `ENTITY_CREATE_TIME_DESC` 已废弃，CLI 直接不放出来，传了会被 cobra enum 校验拒掉。
|
||||
|
||||
## 时间值格式
|
||||
|
||||
所有 `--*-since` / `--*-until` 共用：
|
||||
|
||||
| 输入 | 含义 |
|
||||
|---|---|
|
||||
| `7d` / `30d` | N 天前的当前时刻 |
|
||||
| `1m` | 30 天前（固定 30 天，**不是**日历月）|
|
||||
| `3m` / `6m` | 90 / 180 天前 |
|
||||
| `1y` | 365 天前 |
|
||||
| `2026-04-01` | 本地时区 00:00:00 |
|
||||
| `2026-04-01 10:00:00` / `2026-04-01T10:00:00` | 本地时区具体时刻 |
|
||||
| `2026-04-01T10:00:00+08:00` | RFC3339 带时区 |
|
||||
| `1743523200`（≥ 10 位纯数字）| Unix 秒直接透传 |
|
||||
|
||||
> `m` 绑定 month（30 天），不支持 minute——因为 `my_edit_time` / `my_comment_time` 在服务端是小时聚合，分钟粒度没意义。
|
||||
|
||||
## 小时聚合（my_edit_time / my_comment_time）
|
||||
|
||||
服务端对这两个字段按整点聚合，亚小时输入会被 CLI 向整点对齐：
|
||||
|
||||
```text
|
||||
start: floor 到整点 16:23:45 → 16:00:00
|
||||
end: ceil 到整点 16:23:45 → 17:00:00
|
||||
```
|
||||
|
||||
发生对齐时，stderr 会打印一条 notice，例如：
|
||||
|
||||
```text
|
||||
notice: my_edit_time has hour-level granularity server-side;
|
||||
start 2026-04-22 16:23:00 → 2026-04-22 16:00:00
|
||||
end 2026-04-22 16:28:00 → 2026-04-22 17:00:00
|
||||
```
|
||||
|
||||
stdout 的 JSON 输出不受影响。`open_time` / `create_time` 不做 snap。
|
||||
|
||||
## 输出
|
||||
|
||||
- `--format json`（默认）：`{ total, has_more, page_token, results: [...] }`；所有 `*_time` 字段递归补 `*_time_iso`
|
||||
- `--format pretty`：4 列 table —— `type | title | edit_time | url`
|
||||
- `title_highlighted` / `summary_highlighted` 可能包含 `<h>` / `<hb>` 高亮标签，客户端对比前需先剥离
|
||||
|
||||
> **注意**：返回体里的 `total` 字段不够准确（官方确认，仅供参考）。需要精确统计的场景，按实际 `results` 做去重和累加，不要把 `total` 当结果数承诺。
|
||||
|
||||
## 决策规则
|
||||
|
||||
- **身份快捷方式**：用户说“我的 / 我创建的 / 我负责的”文档，直接 `--mine` 即可，不需要先查 contact 拿 open_id。注意 `--mine` 是 **owner** 语义（我归属/负责的），不是“我最初创建的”——转交出去的不算、转交给我的算。
|
||||
- **时间维度选择**：
|
||||
- "我编辑的"、"我修改的" → `--edited-since` / `--edited-until`
|
||||
- "我评论的"、"我回复过的" → `--commented-since` / `--commented-until`
|
||||
- "我看过的"、"我打开过的"、"最近看过的" → `--opened-since` / `--opened-until`
|
||||
- "创建于"、"新建的"（文档整体维度，与"我"无关）→ `--created-since` / `--created-until`
|
||||
- **作用域选择**：
|
||||
- "某个文件夹下" → `--folder-tokens`（doc-only）
|
||||
- "某个 wiki 空间下" → `--space-ids`（wiki-only）
|
||||
- 两者不能同时使用，混用会报错
|
||||
- **身份 flag 互斥**：`--mine` 和 `--creator-ids` 不要同时传，会直接报错。“我和张三的”（owner）用 `--creator-ids ou_me,ou_zhangsan`（需要先拿到自己 open_id，但这种场景少见）。
|
||||
- **实体补全**：
|
||||
- 用户说"某个群里"，先用 `lark-im` 查 `chat_id`
|
||||
- 用户说“某人的 / 某人分享的”（非自己；`--creator-ids` 按 owner 匹配），先用 `lark-contact` 查 open_id，再填 `--creator-ids` / `--sharer-ids`
|
||||
- **查询语义下推**：`--query` 支持的服务端高级语法（`intitle:`、`""`、`OR`、`-`）优先使用，不要先模糊搜再在客户端二次过滤。
|
||||
- **query 填写边界**：只有标题片段、业务名词、项目名、会议名、文件内容关键词才应进入 `--query`。仅描述动作、时间范围、所有权、统计方式的词不算关键词，保持 `--query ""` 并依赖 filters。
|
||||
- **证据核验**：列表/统计类答案必须来自搜索结果中的实际 URL/token 和类型/时间字段；内容问答必须能指出使用了哪些非污染候选。没有可验证候选时先扩大 query 或翻页，不要直接编总结。
|
||||
- **时间表达**：
|
||||
- 模糊相对时间（"最近半年"、"过去 30 天"、"最近一周"）→ `--*-since 6m` / `--*-since 30d` / `--*-since 7d`，不展开成 ISO 时间
|
||||
- **日历表达**（"上个月"、"上周"、"本月"、"前年"、"今年 3 月"等明确日历单位）→ **必须算出绝对 `YYYY-MM-DD` 边界**（如"上个月" = 上一个日历月的 1 号 → 当月 1 号），**不要近似成 `1m`/`2m`**：CLI 里 `m` 是固定 30 天、`y` 固定 365 天，跟日历差 0-3 天，月末月初尤其容易偏出去
|
||||
- 文档中的 `"<YYYY-MM-DD>"` 是运行时占位符：执行命令前按当前日期计算并替换。例如"本月"应替换为本月第一天和下月第一天，不要把示例生成时的月份硬编码进答案
|
||||
- 绝对日期 → 直接 `YYYY-MM-DD` 或 RFC3339
|
||||
- **分页策略**：默认只返回第一页，并说明 `has_more` 和下一页命令。只有用户明确要"全部 / 全量 / 继续翻"才继续。单轮翻页上限 5 页。
|
||||
- **原始返回**：用户要求"原始数据"、"接口返回"时用 `--format json`，不做客户端精确过滤或摘要重写。
|
||||
|
||||
## 权限
|
||||
|
||||
| 操作 | 所需 scope |
|
||||
|---|---|
|
||||
| 搜索云空间（云盘/云存储）对象（文档 / Wiki / 表格等资源发现） | `search:docs:read` |
|
||||
|
||||
## 常见错误
|
||||
|
||||
| code | 含义 | 处理 |
|
||||
|---|---|---|
|
||||
| `99992351` | `--creator-ids` / `--sharer-ids` 里有 open_id 超出**应用的通讯录可见范围**，服务端拒绝识别 | 让管理员在开发者后台把这些用户加进应用的"通讯录可见性"授权里；或把超出范围的 open_id 从参数里去掉。这和 `search:docs:read` scope 不是一回事 —— 是"应用能看见哪些人"而不是"应用能调用哪个接口" |
|
||||
|
||||
## 时间范围自动裁剪（`--opened-*` 专有）
|
||||
|
||||
服务端对 `open_time` 过滤**每次请求最多支持 3 个月**（90 天）窗口。其他三个时间维度（`--edited-*` / `--commented-*` / `--created-*`）**不受影响**。
|
||||
|
||||
CLI 在发请求前会检查 `--opened-since` 到有效 `--opened-until`（没传则取 `now`）的跨度：
|
||||
|
||||
| 跨度 | 行为 |
|
||||
|---|---|
|
||||
| ≤ 90 天 | 原样透传 |
|
||||
| 91 ~ 365 天 | **自动裁剪**到"最近一个 90 天 slice"，stderr 打一条 notice 列出所有剩余 slice 的 `--opened-since` / `--opened-until` 参数值 |
|
||||
| > 365 天 | 直接报 validation 错，要求缩小范围或自行拆分多次查询 |
|
||||
|
||||
Notice 示例（用户原本要求"过去 8 个月"，会被拆成 3 个 slice）：
|
||||
|
||||
```text
|
||||
notice: --opened-* window spans 240 days (~8 months), exceeds the server-side 3-month (90-day) limit.
|
||||
this query was narrowed to the most recent slice; 3 slices total:
|
||||
[slice 1/3 current] --opened-since 2026-01-24T21:54:02+08:00 --opened-until 2026-04-24T21:54:02+08:00
|
||||
[slice 2/3] --opened-since 2025-10-26T21:54:02+08:00 --opened-until 2026-01-24T21:54:02+08:00
|
||||
[slice 3/3] --opened-since 2025-08-27T21:54:02+08:00 --opened-until 2025-10-26T21:54:02+08:00
|
||||
pagination: paginate within a slice via --page-token using that slice's --opened-since / --opened-until values verbatim (NOT the original relative time like '1y' / '8m' — relative times re-resolve against time.Now() and would mismatch the page_token); switch to the next slice's --opened-* flags only after has_more=false, and do not carry --page-token across slices.
|
||||
```
|
||||
|
||||
### Agent 看到 notice 时的处理
|
||||
|
||||
**标准流程（分页 × slice 的先后顺序）：**
|
||||
|
||||
1. **跑 slice 1**（本次请求已自动裁剪到这个窗口），把结果呈现给用户
|
||||
2. **先在当前 slice 内翻页**：返回的 `has_more = true` 且用户想看更多时，把 `--opened-since` / `--opened-until` 改成 notice 里 `[slice 1/N current]` 行给出的**具体时间值**（**不要继续用原始的 `--opened-since 1y` 这种相对值**——CLI 每次调用都按 `time.Now()` 重算窗口，相对值 + `--page-token` 一起跑会让 page_token 绑到一个漂移的窗口上、结果静默失真），加 `--page-token` 继续翻，直到 `has_more = false`
|
||||
3. **再切换到下一个 slice**：当前 slice 翻完后，如果用户还要"更老的"，用 notice 里列的 slice 2 的 `--opened-since` / `--opened-until` 值，**其他 flag（`--query`、`--doc-types`、`--page-size`、`--sort`……）保持原样，`--page-token` 不带**，重新发请求
|
||||
4. **依次递推**：slice 2 翻完后切 slice 3，以此类推
|
||||
5. 用户只对最近一段感兴趣时，跳过第 3 步及以后 —— 避免无意义的 API 调用
|
||||
|
||||
> `--page-token` 只在单 slice 上下文内有效；切 slice 时不要把上一个 slice 的 `page_token` 带过去。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- `--sort` 在**单 slice 内部**是正确的。跨 slice 的全局 sort（例如"过去一年我打开过的，按 edit_time desc 排"）不被 CLI 保证，需要 agent 自行拉完多个 slice 后在客户端 re-sort 再呈现
|
||||
- 裁剪只改 request 发出去的 `open_time` 范围，`--query` / 其他 filter 不动
|
||||
- 最后一个（最老的）slice 常常不足 90 天，这是正常的截断
|
||||
@ -0,0 +1,52 @@
|
||||
# drive +secure-label-list / +secure-label-update（云文档密级标签）
|
||||
|
||||
## 何时使用
|
||||
|
||||
- `drive +secure-label-list`：查询当前用户可用的密级标签，先拿到目标 `id`。
|
||||
- `drive +secure-label-update`：把目标云文档调整为指定密级标签。
|
||||
|
||||
这两个 shortcut 都使用用户身份（`--as user`）。修改密级前，通常先执行 `+secure-label-list` 确认可用标签 ID。
|
||||
|
||||
## 查询可用密级标签
|
||||
|
||||
```bash
|
||||
lark-cli drive +secure-label-list --page-size 10 --lang zh
|
||||
```
|
||||
|
||||
可选参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--page-size` | 分页大小，范围 `1..10`，默认 `10` |
|
||||
| `--page-token` | 上一页响应里的 `page_token` |
|
||||
| `--lang` | 标签语言：`zh`、`en`、`ja` |
|
||||
|
||||
底层接口：`GET /open-apis/drive/v2/my_secure_labels`。
|
||||
|
||||
## 修改文档密级
|
||||
|
||||
```bash
|
||||
lark-cli drive +secure-label-update \
|
||||
--token "https://example.feishu.cn/docx/doxcnxxxx" \
|
||||
--label-id "7217780879644737539"
|
||||
```
|
||||
|
||||
参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--token` | 目标文档 URL 或 bare token；URL 可自动推断 `--type` |
|
||||
| `--type` | bare token 必填；URL 输入时可省略。可选：`doc`、`docx`、`sheet`、`file`、`bitable`、`mindnote`、`slides` |
|
||||
| `--label-id` | 要设置的密级标签 ID |
|
||||
|
||||
底层接口：`PATCH /open-apis/drive/v2/files/:file_token/secure_label`，query 参数 `type`，请求体 `{ "id": "<label-id>" }`。
|
||||
|
||||
## 错误处理
|
||||
|
||||
CLI 不会在 shortcut 中为密级错误码追加专用 hint；agent 必须根据返回的 `error.code` 做以下引导。
|
||||
|
||||
| 错误码 | 含义 | 引导 |
|
||||
|--------|------|------|
|
||||
| `1063013` | 密级降级需要审批 | 提示用户打开目标文档，在文档界面完成密级降级审批后重试；如果用户传入的是文档 URL，必须把该 URL 一并给用户作为操作入口 |
|
||||
|
||||
遇到 `1063013` 时，不要继续重试 API，也不要提示补 scope；这是文档侧审批流程要求，需要用户到文档里操作。
|
||||
137
.agents/skills/lark-drive/references/lark-drive-status.md
Normal file
137
.agents/skills/lark-drive/references/lark-drive-status.md
Normal file
@ -0,0 +1,137 @@
|
||||
|
||||
# drive +status
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
按 **精确 SHA-256**（默认）或 **快速 modified_time**（`--quick`）比较本地目录与飞书云空间（云盘/云存储）文件夹，输出四类差异：
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `new_local` | 仅本地存在 |
|
||||
| `new_remote` | 仅云端存在 |
|
||||
| `modified` | 双端都存在且本次检测判定为已变更：`detection=exact` 时表示 hash 不一致；`detection=quick` 时表示本地 mtime 与远端 `modified_time` 不一致，或远端时间戳不可可信 |
|
||||
| `unchanged` | 双端都存在且本次检测判定为未变更：`detection=exact` 时表示 hash 一致；`detection=quick` 时表示本地 mtime 与远端 `modified_time` 相等 |
|
||||
|
||||
只读命令：
|
||||
|
||||
- 默认 `detection=exact`：双端都有的文件会从云端拉一份字节流过来在内存里算 hash，不下载落盘，但大目录 / 大文件会有可观的网络流量。
|
||||
- 传 `--quick` 后 `detection=quick`：只比较本地 mtime 与远端 `modified_time`，**不下载远端文件内容**，适合先做快速预检查；它是 best-effort，不等同于严格内容一致性判断。
|
||||
|
||||
## 远端同名文件冲突
|
||||
|
||||
如果 Drive 中多个条目映射到同一个 `rel_path`，`+status` 会在下载/hash 前直接失败，返回 `error.type=duplicate_remote_path`，并在 `error.detail.duplicates_remote[]` 中列出该路径下所有冲突条目的 `file_token`、`type`、名称、大小和时间字段；其中 `created_time`、`modified_time` 缺失时会省略，`size` 在缺失或为 `0` 时都可能被省略。不要把这种情况当成普通 `modified`；它表示同步域本身有歧义，需要先整理云端结构，或在 `+pull` / `+push` 中仅对“duplicate file”场景显式选择冲突策略。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 基础用法 —— 两个必填参数
|
||||
lark-cli drive +status \
|
||||
--local-dir ./repo \
|
||||
--folder-token fldcnxxxxxxxxx
|
||||
|
||||
# 快速模式 —— 只比较 modified_time，不下载远端文件内容
|
||||
lark-cli drive +status \
|
||||
--local-dir ./repo \
|
||||
--folder-token fldcnxxxxxxxxx \
|
||||
--quick
|
||||
|
||||
# 只看判定为 modified 的项（exact=hash 不一致；quick=mtime 不一致）（结合 --jq 过滤）
|
||||
lark-cli drive +status \
|
||||
--local-dir ./repo \
|
||||
--folder-token fldcnxxxxxxxxx \
|
||||
--jq '.modified'
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 标志 | 必填 | 类型 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `--local-dir` | 是 | path | 本地根目录（**必须是 cwd 的相对路径**；绝对路径或逃逸到 cwd 外的相对路径会被 CLI 直接拒绝） |
|
||||
| `--folder-token` | 是 | string | Drive 文件夹 token |
|
||||
| `--quick` | 否 | bool | 快速模式：只比较本地 mtime 与远端 `modified_time`，跳过远端下载和 SHA-256 计算；输出里的 `detection` 会变成 `quick` |
|
||||
|
||||
## 输出 schema
|
||||
|
||||
成功时：
|
||||
|
||||
```json
|
||||
{
|
||||
"detection": "exact",
|
||||
"new_local": [{"rel_path": "..."}],
|
||||
"new_remote": [{"rel_path": "...", "file_token": "..."}],
|
||||
"modified": [{"rel_path": "...", "file_token": "..."}],
|
||||
"unchanged": [{"rel_path": "...", "file_token": "..."}]
|
||||
}
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
- `detection=exact`：默认模式，双端都有的文件会下载远端字节流并做 SHA-256 比较。
|
||||
- `detection=quick`：`--quick` 模式，只按本地 mtime 与远端 `modified_time` 做 best-effort 判断。
|
||||
|
||||
`rel_path` 始终用 `/` 作为分隔符（跨平台一致），相对于 `--local-dir` 或 `--folder-token` 的根。仅本地存在时没有 `file_token` 字段。
|
||||
|
||||
远端同名文件冲突时：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"error": {
|
||||
"type": "duplicate_remote_path",
|
||||
"message": "multiple Drive entries map to the same rel_path",
|
||||
"detail": {
|
||||
"duplicates_remote": [
|
||||
{
|
||||
"rel_path": "dup.txt",
|
||||
"entries": [
|
||||
{"file_token": "<full_file_token>", "type": "file", "name": "dup.txt", "size": 5, "created_time": "1730000000", "modified_time": "1730000000"},
|
||||
{"file_token": "<folder_token>", "type": "folder", "name": "dup.txt", "created_time": "1730000060", "modified_time": "1730000060"}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 比较范围
|
||||
|
||||
- **只比对 Drive `type=file` 的二进制文件**。在线文档（`docx` / `sheet` / `bitable` / `mindnote` / `slides`）和快捷方式（`shortcut`）都被跳过 —— 它们没有等价的本地二进制可对齐，否则会在 `new_remote` 里产生大量误报。
|
||||
- 子文件夹会递归遍历；rel_path 形如 `sub1/sub2/file.txt`。
|
||||
- 多个远端条目映射到同一个 rel_path 时不做隐式选择，默认失败。
|
||||
- 本地侧只比对常规文件（regular file）；符号链接、设备文件等被忽略。
|
||||
- `--quick` 模式下，双端都有的文件只在 **远端时间精度** 下比较 `modified_time` / 本地 mtime：相等才记为 `unchanged`，否则记为 `modified`；远端时间戳缺失或非法时，走保守路径记为 `modified`，不会盲判 `unchanged`。
|
||||
|
||||
## 范围限制
|
||||
|
||||
`+status` 的本地侧只接受 cwd 下的相对路径。如果用户想比对的目录在 cwd 之外，**不要 agent 自己 `cd` 绕过**；让用户在合适的祖先目录重新启动 agent 后再跑。注意：把目标软链接到 cwd 内**也不行**——路径校验会先 `EvalSymlinks` 再判定是否越界，链接最终指向的真实目录如果在 cwd 之外，仍然会被 `unsafe file path` 拒掉。CLI 会在路径越界时直接报错，无需在 skill 这一层提前手动校验。
|
||||
|
||||
## 典型用法
|
||||
|
||||
把 +status 当作"先看差异、再决定怎么同步"的只读探针。常见接驳场景：
|
||||
|
||||
- 想知道云端有什么本地没有的内容 → 看 `new_remote`，按需选择性拉取（`drive +download --file-token <token>`）。
|
||||
- 想把本地新增的内容推到云端 → 看 `new_local`，再 `drive +upload --file <path> --folder-token <parent>`（注意 +upload 不接受 0 字节文件）。
|
||||
- 想知道哪些文件在云端被同事改过 → 看 `modified`，逐个 `drive +download` 查内容差异。
|
||||
|
||||
## 性能注意
|
||||
|
||||
- 默认 `detection=exact` 下，`unchanged` + `modified` 的总字节数 = 本次需从云端下载的流量。100GB 的双端共享内容意味着 100GB 网络往返。
|
||||
- `--quick` / `detection=quick` 下，不会下载双端共有文件的远端内容，执行时间更接近 `O(文件数量)`，而不是 `O(总文件大小)`。
|
||||
- 仅一侧存在的文件不会被下载。
|
||||
- 默认模式的 hash 计算在内存里流式做（io.Copy → sha256.New），不会把云端文件落到磁盘。
|
||||
|
||||
## 所需 scope
|
||||
|
||||
| 操作 | scope |
|
||||
|------|-------|
|
||||
| 列出文件夹 / 子目录 | `drive:drive.metadata:readonly` |
|
||||
| 下载并 hash 文件 | `drive:file:download` |
|
||||
|
||||
默认会先要求 `drive:drive.metadata:readonly`。在 `detection=exact` 路径（默认，不传 `--quick`）下，CLI 还会额外要求 `drive:file:download`；传 `--quick` 时不会要求下载 scope。如果当前 token 缺本次执行路径需要的 scope，命令会报 `missing_scope` 并提示重新登录。`drive:drive` 在部分企业被策略禁用，所以 +status 故意只依赖上面这些细粒度 scope。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) —— 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) —— 认证和全局参数
|
||||
- [lark-drive-upload](lark-drive-upload.md) / [lark-drive-download](lark-drive-download.md) —— 把 +status 输出接到推/拉动作上
|
||||
302
.agents/skills/lark-drive/references/lark-drive-task-result.md
Normal file
302
.agents/skills/lark-drive/references/lark-drive-task-result.md
Normal file
@ -0,0 +1,302 @@
|
||||
|
||||
# drive +task_result
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹、Wiki 节点 / 文档迁入 Wiki 等多种异步任务的结果查询，统一接口方便调用。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 对于 `import` 场景，如果使用 `--as bot` 且这次查询**已经拿到最终在线文档目标**（`ready=true` 且返回了最终 `token` / `url`），CLI 会**再次尝试为当前 CLI 用户自动授予该资源的 `full_access`（可管理权限）**。
|
||||
>
|
||||
> 此时结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
|
||||
> - `status = granted`：当前 CLI 用户已获得该导入结果的可管理权限
|
||||
> - `status = skipped`：本地没有可用的当前用户 `open_id`，或最终结果缺少可授权的在线文档目标，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
|
||||
> - `status = failed`：导入结果已就绪，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档
|
||||
>
|
||||
> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
|
||||
>
|
||||
> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 查询导入任务结果
|
||||
lark-cli drive +task_result \
|
||||
--scenario import \
|
||||
--ticket <IMPORT_TICKET>
|
||||
|
||||
# 查询导出任务结果
|
||||
lark-cli drive +task_result \
|
||||
--scenario export \
|
||||
--ticket <EXPORT_TICKET> \
|
||||
--file-token <SOURCE_DOC_TOKEN>
|
||||
|
||||
# 查询移动/删除文件夹任务状态
|
||||
lark-cli drive +task_result \
|
||||
--scenario task_check \
|
||||
--task-id <TASK_ID>
|
||||
|
||||
# 查询 Wiki 移动任务结果（wiki +move 异步超时后的续跑）
|
||||
lark-cli drive +task_result \
|
||||
--scenario wiki_move \
|
||||
--task-id <TASK_ID>
|
||||
|
||||
# 查询 Wiki 删除知识空间任务结果（wiki +delete-space 异步超时后的续跑）
|
||||
lark-cli drive +task_result \
|
||||
--scenario wiki_delete_space \
|
||||
--task-id <TASK_ID>
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (移动/删除文件夹任务)、`wiki_move` (Wiki 移动任务)、`wiki_delete_space` (Wiki 删除知识空间任务) |
|
||||
| `--ticket` | 条件必填 | 异步任务 ticket，**import/export 场景必填** |
|
||||
| `--task-id` | 条件必填 | 异步任务 ID，**task_check / wiki_move / wiki_delete_space 场景必填** |
|
||||
| `--file-token` | 条件必填 | 导出任务对应的源文档 token，**export 场景必填** |
|
||||
|
||||
## 场景说明
|
||||
|
||||
| 场景 | 说明 | 所需参数 |
|
||||
|------|------|----------|
|
||||
| `import` | 文档导入任务（如将本地文件导入为云文档） | `--ticket` |
|
||||
| `export` | 文档导出任务（如云文档导出为 PDF/Word） | `--ticket`、`--file-token` |
|
||||
| `task_check` | 文件夹移动/删除任务 | `--task-id` |
|
||||
| `wiki_move` | Wiki 移动任务（`wiki +move` 的 docs-to-wiki 异步流程，超时后续跑用） | `--task-id` |
|
||||
| `wiki_delete_space` | Wiki 删除知识空间任务（`wiki +delete-space` 的异步流程，超时后续跑用） | `--task-id` |
|
||||
|
||||
## 返回结果
|
||||
|
||||
### Import 场景返回
|
||||
|
||||
```json
|
||||
{
|
||||
"scenario": "import",
|
||||
"ticket": "<IMPORT_TICKET>",
|
||||
"type": "sheet",
|
||||
"ready": true,
|
||||
"failed": false,
|
||||
"job_status": 0,
|
||||
"job_status_label": "success",
|
||||
"job_error_msg": "success",
|
||||
"token": "<IMPORTED_DOC_TOKEN>",
|
||||
"url": "https://example.feishu.cn/sheets/<IMPORTED_DOC_TOKEN>",
|
||||
"extra": ["2000"],
|
||||
"permission_grant": {
|
||||
"status": "granted",
|
||||
"perm": "full_access",
|
||||
"member_type": "openid",
|
||||
"user_open_id": "<CURRENT_USER_OPEN_ID>",
|
||||
"message": "Granted the current CLI user full_access (可管理权限) on the new spreadsheet."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `ready`: 是否已经导入完成，可直接使用 `token` / `url`
|
||||
- `failed`: 是否已经失败
|
||||
- `job_status`: 服务端返回的原始状态码
|
||||
- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
|
||||
- `token`: 导入后的文档 token
|
||||
- `url`: 导入后的文档链接
|
||||
- `permission_grant`: 仅 `--as bot` 且这次查询已经拿到最终在线文档目标时返回，用于说明是否已自动为当前 CLI 用户授予可管理权限；如果当前仍是 `ready=false`，则不会返回这个字段
|
||||
|
||||
### Export 场景返回
|
||||
|
||||
```json
|
||||
{
|
||||
"scenario": "export",
|
||||
"ticket": "<EXPORT_TICKET>",
|
||||
"ready": true,
|
||||
"failed": false,
|
||||
"file_extension": "pdf",
|
||||
"type": "doc",
|
||||
"file_name": "docName",
|
||||
"file_token": "<EXPORTED_FILE_TOKEN>",
|
||||
"file_size": 34356,
|
||||
"job_error_msg": "success",
|
||||
"job_status": 0,
|
||||
"job_status_label": "success"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `ready`: 是否已经完成导出，可直接使用 `file_token`
|
||||
- `failed`: 是否已经失败
|
||||
- `job_status`: 服务端返回的原始状态码
|
||||
- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
|
||||
- `file_token`: 导出文件的 token，用于下载
|
||||
- `file_extension`: 导出文件扩展名
|
||||
- `file_size`: 导出文件大小（字节）
|
||||
|
||||
### Task_check 场景返回
|
||||
|
||||
```json
|
||||
{
|
||||
"scenario": "task_check",
|
||||
"task_id": "<TASK_ID>",
|
||||
"status": "success",
|
||||
"ready": true,
|
||||
"failed": false
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `status`: 任务状态，`success`=成功，`failed`=失败，`pending`=处理中
|
||||
- `ready`: 是否已经完成
|
||||
- `failed`: 是否已经失败
|
||||
|
||||
### Wiki_move 场景返回
|
||||
|
||||
```json
|
||||
{
|
||||
"scenario": "wiki_move",
|
||||
"task_id": "<TASK_ID>",
|
||||
"ready": true,
|
||||
"failed": false,
|
||||
"status": 0,
|
||||
"status_msg": "success",
|
||||
"wiki_token": "wikcnXXX",
|
||||
"node_token": "wikcnXXX",
|
||||
"space_id": "<TARGET_SPACE_ID>",
|
||||
"obj_token": "<OBJ_TOKEN>",
|
||||
"obj_type": "docx",
|
||||
"parent_node_token": "",
|
||||
"node_type": "origin",
|
||||
"origin_node_token": "",
|
||||
"title": "项目计划",
|
||||
"has_child": false,
|
||||
"node": {
|
||||
"space_id": "<TARGET_SPACE_ID>",
|
||||
"node_token": "wikcnXXX",
|
||||
"obj_token": "<OBJ_TOKEN>",
|
||||
"obj_type": "docx",
|
||||
"parent_node_token": "",
|
||||
"node_type": "origin",
|
||||
"origin_node_token": "",
|
||||
"title": "项目计划",
|
||||
"has_child": false
|
||||
},
|
||||
"move_results": [
|
||||
{
|
||||
"status": 0,
|
||||
"status_msg": "success",
|
||||
"node": { "...": "同上" }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `ready`: 所有 `move_results[].status` 都为 `0` 时为 `true`
|
||||
- `failed`: 任一 `move_results[].status` 小于 `0` 时为 `true`
|
||||
- `status` / `status_msg`: 第一个 move_result 的状态码 / 标签（无结果时回退为 `1` / `processing`）
|
||||
- `wiki_token` / `node_token`: 移入 Wiki 后的目标节点 token（首个结果有 `node.node_token` 时镜像到顶层，便于下游脚本使用）
|
||||
- `space_id`、`obj_token`、`obj_type`、`title` 等：从首个 `move_results[0].node` 平铺到顶层，方便直接引用
|
||||
- `move_results`: 保留完整列表（适用于一次任务移动多个文档的场景）
|
||||
|
||||
### Wiki_delete_space 场景返回
|
||||
|
||||
```json
|
||||
{
|
||||
"scenario": "wiki_delete_space",
|
||||
"task_id": "<TASK_ID>",
|
||||
"ready": true,
|
||||
"failed": false,
|
||||
"status": "success",
|
||||
"status_msg": "success"
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `ready`: `status=success` 时为 `true`
|
||||
- `failed`: `status=failure` 或 `failed` 时为 `true`；未知非成功状态（如 `processing`）视为进行中
|
||||
- `status`: 服务端返回的原始 `delete_space_result.status`
|
||||
- `status_msg`: 优先使用 `delete_space_result.status_msg`，否则回落到 `status`，再回落到 `processing`
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 配合 +import 使用
|
||||
|
||||
```bash
|
||||
# 1. 创建导入任务
|
||||
lark-cli drive +import --file ./data.xlsx --type sheet
|
||||
# 若任务很快完成：直接返回 token / url
|
||||
# 若内置轮询超时：返回 ready=false、ticket 和 next_command
|
||||
|
||||
# 2. 轮询导入结果
|
||||
lark-cli drive +task_result --scenario import --ticket <IMPORT_TICKET>
|
||||
# 如果这里返回 ready=true 且使用 --as bot，结果还会包含 permission_grant
|
||||
```
|
||||
|
||||
### 配合 +move 使用
|
||||
|
||||
```bash
|
||||
# 1. 移动文件夹（异步操作）
|
||||
lark-cli drive +move --file-token <FOLDER_TOKEN> --type folder --folder-token <TARGET_FOLDER_TOKEN>
|
||||
# 若轮询窗口内完成：直接返回 ready=true
|
||||
# 若内置轮询结束仍未完成：返回 ready=false、task_id 和 next_command
|
||||
|
||||
# 2. 轮询移动结果
|
||||
lark-cli drive +task_result --scenario task_check --task-id <TASK_ID>
|
||||
```
|
||||
|
||||
### 配合 wiki +move 使用
|
||||
|
||||
```bash
|
||||
# 1. 把 Drive 文档迁入 Wiki（异步任务可能返回 task_id）
|
||||
lark-cli wiki +move --obj-type docx --obj-token <DOC_TOKEN> --target-space-id <TARGET_SPACE_ID>
|
||||
# 若内置轮询窗口内完成：直接返回 ready=true 和 wiki_token
|
||||
# 若轮询窗口结束仍未完成：返回 ready=false、task_id、timed_out=true 和 next_command
|
||||
|
||||
# 2. 续跑查询 Wiki 移动结果（next_command 即下面这条）
|
||||
lark-cli drive +task_result --scenario wiki_move --task-id <TASK_ID> --as user
|
||||
```
|
||||
|
||||
> **身份保持一致**：续跑命令的 `--as` 必须与原 `wiki +move` 调用一致；`wiki +move` 的 `next_command` 已自动带上正确的 `--as`。
|
||||
|
||||
### 配合 wiki +delete-space 使用
|
||||
|
||||
```bash
|
||||
# 1. 删除知识空间（高风险写操作，必须显式带 --yes；接口可能同步返回空 task_id，也可能返回异步 task_id）
|
||||
lark-cli wiki +delete-space --space-id <SPACE_ID> --yes
|
||||
# 若同步返回：直接 ready=true
|
||||
# 若轮询窗口结束仍未完成：返回 ready=false、task_id、timed_out=true 和 next_command
|
||||
|
||||
# 2. 续跑查询 Wiki 删除结果（next_command 即下面这条）
|
||||
lark-cli drive +task_result --scenario wiki_delete_space --task-id <TASK_ID> --as user
|
||||
```
|
||||
|
||||
### 配合 +export 使用
|
||||
|
||||
```bash
|
||||
# 1. 发起导出
|
||||
lark-cli drive +export --token <SOURCE_DOC_TOKEN> --doc-type docx --file-extension pdf
|
||||
# 若轮询窗口内完成：直接下载本地文件
|
||||
# 若内置轮询结束仍未完成：返回 ready=false、ticket 和 next_command
|
||||
|
||||
# 2. 继续查询导出结果
|
||||
lark-cli drive +task_result --scenario export --ticket <EXPORT_TICKET> --file-token <SOURCE_DOC_TOKEN>
|
||||
|
||||
# 3. 拿到 file_token 后下载
|
||||
lark-cli drive +export-download --file-token <EXPORTED_FILE_TOKEN>
|
||||
```
|
||||
|
||||
## 权限要求
|
||||
|
||||
| 场景 | 所需 scope |
|
||||
|------|-----------|
|
||||
| import | `drive:drive.metadata:readonly` |
|
||||
| export | `drive:drive.metadata:readonly` |
|
||||
| task_check | `drive:drive.metadata:readonly` |
|
||||
| wiki_move | `wiki:space:read` |
|
||||
| wiki_delete_space | `wiki:space:read` |
|
||||
|
||||
> [!NOTE]
|
||||
> `import` 场景在 `--as bot` 且任务最终就绪时，还可能额外尝试一次协作者授权；如果 `permission_grant.status = failed`，请根据失败信息检查应用是否具备相应的文档协作者授权能力。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
101
.agents/skills/lark-drive/references/lark-drive-upload.md
Normal file
101
.agents/skills/lark-drive/references/lark-drive-upload.md
Normal file
@ -0,0 +1,101 @@
|
||||
|
||||
# drive +upload
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
上传本地文件到飞书云空间（云盘/云存储）。目标位置可以是 Drive 文件夹，也可以是 wiki 节点。
|
||||
|
||||
## 快速决策
|
||||
- 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../../lark-markdown/SKILL.md)。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 上传到 Drive 文件夹
|
||||
lark-cli drive +upload --file ./report.pdf --folder-token fldbc_xxx
|
||||
|
||||
# 上传到 wiki 节点
|
||||
lark-cli drive +upload --file ./report.pdf --wiki-token wikcn_xxx
|
||||
|
||||
# 不指定目标时，上传到调用者的 Drive 根目录
|
||||
lark-cli drive +upload --file ./report.pdf
|
||||
|
||||
# 自定义上传后的文件名
|
||||
lark-cli drive +upload --file ./report.pdf --name "季度总结.pdf"
|
||||
|
||||
# 覆盖已存在文件（原地覆盖，保留 file_token）
|
||||
lark-cli drive +upload --file ./report.pdf --file-token boxcn_existing_file
|
||||
|
||||
# 原生命令（高级/分片上传）：预上传 + 完成上传
|
||||
lark-cli drive files upload_prepare --data '{
|
||||
"file_name": "report.pdf",
|
||||
"parent_type": "explorer",
|
||||
"parent_node": "fldbc_xxx",
|
||||
"size": 1048576,
|
||||
"file_token": "boxcn_existing_file"
|
||||
}'
|
||||
lark-cli drive files upload_finish --data '{
|
||||
"upload_id": "<UPLOAD_ID>",
|
||||
"block_num": 1
|
||||
}'
|
||||
|
||||
# 查看完整参数定义
|
||||
lark-cli schema drive.files.upload_prepare
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 如果文件是**以应用身份（bot）新建上传**的，如 `lark-cli drive +upload --as bot` 在上传成功后，CLI 会**尝试为当前 CLI 用户自动授予该文件的 `full_access`（可管理权限）**。
|
||||
>
|
||||
> 如果这次调用传了 `--file-token`，表示是在**覆盖已有文件**，CLI **不会**额外修改该文件权限。
|
||||
>
|
||||
> 以应用身份上传时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
|
||||
> - `status = granted`：当前 CLI 用户已获得该文件的可管理权限
|
||||
> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
|
||||
> - `status = failed`：文件已上传成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文件
|
||||
>
|
||||
> `permission_grant.perm = full_access` 表示该资源已授予“可管理权限”。
|
||||
>
|
||||
> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
|
||||
|
||||
> [!TIP]
|
||||
> 当底层上传接口返回版本号时，shortcut 会在结果里额外透出 `version`。
|
||||
|
||||
## 目标位置选择（关键）
|
||||
|
||||
- 上传到 Drive 文件夹：传 `--folder-token <folder_token>`，shortcut 会发送 `parent_type=explorer`
|
||||
- 上传到 wiki 节点：传 `--wiki-token <wiki_token>`，shortcut 会发送 `parent_type=wiki`
|
||||
- 上传到 Drive 根目录：`--folder-token` 和 `--wiki-token` 都不传
|
||||
- 覆盖已有文件：额外传 `--file-token <existing_file_token>`；shortcut 会把它原样透传到底层 `upload_all` / `upload_prepare`，让后端按覆盖语义写入
|
||||
- bot 模式下，`--file-token` 覆盖只改文件内容；不会额外给当前 CLI 用户补 `full_access`
|
||||
- 不要传空目标值：`--folder-token ""` / `--wiki-token ""` 会被视为参数错误；如需上传到 Drive 根目录，应直接省略这两个参数
|
||||
- 不要传空 `--file-token`：如需新建上传，直接省略该参数；显式传空字符串会报错
|
||||
- `--folder-token` 和 `--wiki-token` 互斥，不要同时传
|
||||
- `--wiki-token` 传的是 **wiki node token**，不是 `space_id`
|
||||
|
||||
Shortcut 参数：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file` | 是 | 本地文件路径 |
|
||||
| `--file-token` | 否 | 已存在文件的 token；传入后按“覆盖已有文件”语义上传 |
|
||||
| `--folder-token` | 否 | 目标文件夹 token；与 `--wiki-token` 互斥；省略时默认为 Drive 根目录；显式传空字符串会报错 |
|
||||
| `--wiki-token` | 否 | 目标 wiki 节点 token；与 `--folder-token` 互斥；会映射为 `parent_type=wiki`、`parent_node=<wiki_token>`；显式传空字符串会报错 |
|
||||
| `--name` | 否 | 上传后的文件名；默认使用本地文件名 |
|
||||
|
||||
参数（预上传 `--data` JSON body）：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `file_name` | 是 | 文件名 |
|
||||
| `parent_type` | 是 | 父节点类型；上传到文件夹 / 根目录时用 `"explorer"`，上传到 wiki 节点时用 `"wiki"` |
|
||||
| `parent_node` | 是 | 父节点 token；`explorer` 时传文件夹 token（根目录可为空字符串），`wiki` 时传 wiki node token |
|
||||
| `size` | 是 | 文件大小（字节） |
|
||||
| `file_token` | 否 | 已存在文件 token；传入后覆盖该文件内容 |
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作** —— 执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,38 @@
|
||||
# drive +version-delete
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
删除指定的历史版本。该 shortcut 同时支持 `--as user` 和 `--as bot`；自动化场景推荐使用 `--as bot`。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
lark-cli drive +version-delete \
|
||||
--file-token boxcnxxxxxxxx \
|
||||
--version 7633658129540910621 \
|
||||
--yes \
|
||||
--as bot
|
||||
|
||||
lark-cli drive +version-delete \
|
||||
--file-token boxcnxxxxxxxx \
|
||||
--version 7633658129540910621 \
|
||||
--yes \
|
||||
--as user
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file-token` | 是 | 目标文件 token |
|
||||
| `--version` | 是 | `drive +version-history` 返回的长数字 `version` 字段，不是 `tag` |
|
||||
| `--yes` | 是 | 确认执行高风险删除操作 |
|
||||
|
||||
## 返回值
|
||||
|
||||
无额外业务字段，以命令成功 / 失败为准。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
@ -0,0 +1,71 @@
|
||||
# drive +version-get
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
下载指定版本的文件内容。该 shortcut 同时支持 `--as user` 和 `--as bot`；自动化场景推荐使用 `--as bot`。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
lark-cli drive +version-get \
|
||||
--file-token boxcnxxxxxxxx \
|
||||
--version 7633658129540910621 \
|
||||
--as bot
|
||||
|
||||
lark-cli drive +version-get \
|
||||
--file-token boxcnxxxxxxxx \
|
||||
--version 7633658129540910621 \
|
||||
--as user
|
||||
|
||||
lark-cli drive +version-get \
|
||||
--file-token boxcnxxxxxxxx \
|
||||
--version 7633658129540910621 \
|
||||
--output ./downloads/ \
|
||||
--as bot
|
||||
|
||||
lark-cli drive +version-get \
|
||||
--file-token boxcnxxxxxxxx \
|
||||
--version 7633658129540910621 \
|
||||
--output ./artifact.bin \
|
||||
--overwrite \
|
||||
--as bot
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file-token` | 是 | 目标文件 token |
|
||||
| `--version` | 是 | `drive +version-history` 返回的长数字 `version` 字段，不是 `tag` |
|
||||
| `--output` | 否 | 本地保存路径或目录；省略时保存到当前目录，并优先使用服务端文件名 |
|
||||
| `--overwrite` | 否 | 覆盖已存在的本地输出文件 |
|
||||
|
||||
## 关键行为
|
||||
|
||||
- 省略 `--output` 时，CLI 保存到当前目录，并优先使用服务端文件名
|
||||
- `--output` 指向已存在目录，或以 `/` / `\\` 结尾时，CLI 会使用远端文件名保存
|
||||
- `--output` 是文件路径且没有后缀时，CLI 会像 `docs +media-download` 一样尝试从响应头推断后缀；推不出来就保持无后缀
|
||||
- 目标文件已存在时，只有显式传 `--overwrite` 才会覆盖
|
||||
|
||||
## 返回值
|
||||
|
||||
返回值：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "bot",
|
||||
"data": {
|
||||
"file_token": "boxcnxxxxxxxx",
|
||||
"version": "7633658129540910621",
|
||||
"file_name": "artifact.bin",
|
||||
"saved_path": "/abs/path/artifact.bin",
|
||||
"size_bytes": 12345
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-drive](../SKILL.md) -- 云空间（云盘/云存储）全部命令
|
||||
- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user