@amaster.ai/pi-lark 0.1.5 → 0.1.7

package/skills/lark-base/references/lark-base-filter-condition.md

@@ -0,0 +1,179 @@
+# Base Filter 条件结构（公共协议）
+
+Filter 是一组「字段/操作符/值」条件的组合，用 `logic`（`and` / `or`）把多条 `conditions` 连接起来，用于描述「满足什么条件」。视图筛选 `filter`、记录读取/搜索的 `--filter-json`、表单题目显隐条件 `visible_rule` 复用同一套 tuple 结构，本文件是其公共协议（SSOT）。
+
+## 0. 适用范围
+
+本协议只适用于以下场景：
+
+- `+view-set-filter` / `+view-get-filter` 的视图筛选配置。
+- `+record-list --filter-json` / `+record-search --filter-json` 的结构化记录筛选。
+- `+form-questions-create` / `+form-questions-update` 中的 `visible_rule` 显隐条件。
+
+本协议**不适用于 `+data-query`**。`+data-query` 支持过滤，但使用的是 LiteQuery DSL 的 `filters` 对象结构：`{"type":1,"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["有效"]}]}`，不是这里的 tuple 条件 `["状态","==","有效"]`。构造 `+data-query --dsl` 时请阅读 [lark-base-data-query.md](lark-base-data-query.md) 的 FilterGroup / Condition 章节。
+
+## 1. 顶层结构
+
+- 必须是 JSON 对象。
+- 顶层结构是 `{logic?, conditions?}`。
+- `logic` 默认 `and`；推荐只用 canonical 值 `and` / `or`。
+- `conditions` 默认空数组。
+- 每条条件写成 tuple：`[field, operator, value?]`。
+- `empty` / `non_empty` 可写成 2 项：`[field, "empty"]`、`[field, "non_empty"]`。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["状态", "intersects", ["Doing"]],
+    ["负责人", "intersects", [{ "id": "ou_xxx" }]],
+    ["截止时间", "empty"]
+  ]
+}
+```
+
+清空写法：
+
+```json
+{
+  "conditions": []
+}
+```
+
+## 2. operator
+
+可用 operator：
+- `==`
+- `!=`
+- `>`
+- `>=`
+- `<`
+- `<=`
+- `intersects`
+- `disjoint`
+- `empty`
+- `non_empty`
+
+## 3. value 写法
+
+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. 易错点
+
+- 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
+- `user` / `group_chat` / `link` 不要写成单个标量。
+- `empty` / `non_empty` 不要硬塞无意义的 value。
+- 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
+- `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前配置或字段定义，或根据错误提示修正类型。
+
+## 5. 参考
+- [lookup-field-guide.md](lookup-field-guide.md)

package/skills/lark-base/references/lark-base-form-questions-create.md

@@ -19,10 +19,7 @@ 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}
-  ]'
+  --questions '[{"type":"text","title":"您的姓名是？","required":true},{"type":"text","title":"您的联系方式是？","required":false}]'
 
 # 添加单选题（带选项）
 lark-cli base +form-questions-create \
@@ -50,6 +47,13 @@ lark-cli base +form-questions-create \
   --table-id <table_id> \
   --form-id <form_id> \
   --questions '[{"type":"text","title":"反馈建议","description":"更多详情请查看[帮助文档](https://example.com/help)"}]'  
+
+# 添加带显隐条件（visible_rule）的问题：当「是否需要发票」选择「是」时才显示「发票抬头」
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"select","title":"是否需要发票","required":true,"options":[{"name":"是","hue":"Blue"},{"name":"否","hue":"Gray"}]},{"type":"text","title":"发票抬头","visible_rule":{"logic":"and","conditions":[["是否需要发票","==","是"]]}}]'
 ```
 
 ## 参数
@@ -78,6 +82,7 @@ lark-cli base +form-questions-create \
 | `multiple`            | 否 | 是否多选（`select`/`user` 类型有效，bool） |
 | `options`             | 否 | 选项列表（仅 `select` 有效）：`[{"name":"选项1","hue":"Blue"}]`，hue 可选：`Red`/`Orange`/`Yellow`/`Green`/`Blue`/`Purple`/`Gray` |
 | `style`               | 否 | 字段样式配置（见下方说明） |
+| `visible_rule`        | 否 | 题目显隐条件（见下方「`visible_rule` 显隐条件」） |
 
 ### `style` 字段说明
 
@@ -88,6 +93,30 @@ lark-cli base +form-questions-create \
 | `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` |
 
+### `visible_rule` 显隐条件
+
+> **仅当用户明确要求为题目设置显隐条件（显示/隐藏逻辑）时，才需要读下面的结构说明；否则忽略本节。**
+
+`visible_rule` 控制题目在表单中的显示/隐藏：当条件满足时题目显示，不满足时隐藏；不传或 `conditions` 为空数组则题目始终显示。
+
+- **结构与视图筛选 `filter` 完全一致**，即 `{logic?, conditions?}`，共用同一套公共协议。
+- 与视图 `filter` 唯一的区别：`conditions` 中的 `field` 引用的是**同一表单内其他题目的题目名称或题目 ID**（推荐用题目 ID 以避免重名歧义），而不是数据表字段。
+- **只能引用前序题目**：条件只能引用排在当前题目之前的题目——创建时按 `questions` 数组顺序判定（可引用同批次更靠前的新题目或表单中已有题目），不支持循环引用。
+- 引用的题目必须真实存在，否则会报错。
+- 列出题目（`+form-questions-list`）会在每个题目对象中**原样返回** `visible_rule`；未设置显隐条件的题目返回 `null` 或 `conditions` 为空数组。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["是否需要发票", "==", "是"],
+    ["报销金额", ">=", 1000]
+  ]
+}
+```
+
+详细的 `visible_rule` 结构（顶层规则、operator 列表、各题目类型的 value 写法）请阅读 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
+
 ## 输出格式
 
 返回创建成功的问题列表：
@@ -108,11 +137,15 @@ lark-cli base +form-questions-create \
 > [!CAUTION]
 > 这是**写入操作** — 执行前必须向用户确认。
 
-1. 先用 `+form-questions-list` 查看现有问题
-2. 确认要添加的问题内容
-3. 执行命令并报告新建的问题 ID
+1. 先确定表单所属的真实 `table_id`，并在整个表单管理工作流中复用它；仅在 ID 缺失或归属不明确时调用 `+table-list`。
+2. 用 `+form-questions-list` 查看现有问题。问题 `id` 是承载该问题的 `field_id`，不是独立于数据表的临时 ID。
+3. 除非用户明确要求同名的独立问题，否则目标标题已经存在时用 `+form-questions-update` 更新必填状态、标题或描述；不要创建同名问题后再删除旧问题。
+4. 创建确实不存在的问题，或用户明确要求的同名独立问题，并报告新建的问题 ID。
+
+`+form-questions-delete` 会删除承载问题的数据表字段，不能删除主字段问题。不要通过“新建重复问题再删除旧问题”来替换主字段。
 
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-base-filter-condition.md](lark-base-filter-condition.md) — `visible_rule` / `filter` 条件结构公共协议
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-base/references/lark-base-form-questions-update.md

@@ -2,40 +2,60 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-批量更新多维表格表单/问卷中的问题（标题、描述、是否必填）。
+批量更新多维表格表单/问卷中的问题配置（标题、描述、是否必填、显隐条件等）。
+
+> [!CAUTION]
+> `+form-questions-update` 是**题目配置全量覆盖**，不是 patch。对每个传入的题目，未携带的属性会回落为默认值，显式传空字符串 / `null` / 空数组会直接写入空或清空；如果要保留现有属性，必须先用 `+form-questions-list` 查出现状，再把要保留的字段一起带回 `--questions`。
 
 ## 命令
 
 ```bash
-# 更新一个问题的标题
+# 先读取现有题目配置，作为 read-modify-write 的基线
+lark-cli base +form-questions-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id>
+
+# 更新一个问题的标题，同时带回要保留的 required / description / visible_rule 等字段
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[{"id":"q_001","title":"您的真实姓名是？"}]'
+  --questions '[{"id":"q_001","title":"您的真实姓名是？","description":"请填写真实姓名","required":true,"visible_rule":null}]'
 
-# 同时更新多个问题
+# 同时更新多个问题；每个对象都应是该题目的目标完整配置
 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}
-  ]'
+  --questions '[{"id":"q_001","title":"姓名（必填）","required":true},{"id":"q_002","title":"联系方式","required":false}]'
   
-# 更新问题描述（纯文本）
+# 更新问题描述（纯文本），同时带回要保留的 title / required / visible_rule
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","title":"您的姓名","description":"请填写您的真实姓名","required":true,"visible_rule":null}]'
+# 更新问题描述（含链接），同时带回要保留的 title / required / visible_rule
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[{"id":"q_001","description":"请填写您的真实姓名"}]'
-# 更新问题描述（含链接）
+  --questions '[{"id":"q_001","title":"反馈建议","description":"更多说明请参考[帮助文档](https://example.com/help)","required":false,"visible_rule":null}]'
+
+# 更新题目显隐条件（visible_rule），同时带回要保留的 title / description / required
 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)"}]'  
+  --questions '[{"id":"q_002","title":"发票抬头","description":"","required":false,"visible_rule":{"logic":"and","conditions":[["q_001","==","是"]]}}]'
+
+# 清空题目显隐条件（使题目始终显示），同时带回要保留的 title / description / required
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_002","title":"发票抬头","description":"","required":false,"visible_rule":null}]'
 ```
 
 ## 参数
@@ -52,15 +72,46 @@ lark-cli base +form-questions-update \
 
 ## `--questions` 格式
 
-每个问题对象必须包含 `id`，其余字段按需传入：
+每个问题对象必须包含 `id`。注意：对象不是增量 patch，而是该题目的目标完整配置；未携带字段会按服务端默认值重建。
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `id` | **是** | 问题 ID（field_id），不可修改 |
-| `title` | 否 | 新的问题标题 |
-| `description` | 否 | 新的问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
-| `required` | 否 | 是否必填 |
-| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
+| `title` | 否 | 目标问题标题；省略会回落为字段名，传空字符串会写入空标题（若服务端允许） |
+| `description` | 否 | 目标问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`）；省略或传空字符串都会清空描述 |
+| `required` | 否 | 目标是否必填；省略会回落为 `false` |
+| `option_display_mode` | 否 | 目标选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向；省略会回落默认展示方式 |
+| `visible_rule` | 否 | 目标题目显隐条件；传完整 `{logic, conditions}` 对象覆盖，传 `null` 或省略都会清空（见下方说明） |
+
+## 全量覆盖语义
+
+- 先执行 `+form-questions-list`，读取被更新题目的当前 `id`、`title`、`description`、`required`、`option_display_mode`、`visible_rule`。
+- 构造 `--questions` 时，只改用户明确要求变化的字段；所有仍要保留的字段必须按当前值一并传回。
+- 不要用“只传要改的字段”的方式更新题目。比如只传 `{"id":"q_002","title":"新标题"}` 会让 `description` 清空、`required` 回落为 `false`、`visible_rule` 清空。
+- 用户明确要求清空时才传空值：`description:""` 清空描述，`visible_rule:null` 清空显隐条件，`conditions:[]` 也表示无条件显示。
+
+### `visible_rule` 显隐条件
+
+> **仅当用户明确要求为题目设置或修改显隐条件（显示/隐藏逻辑）时，才需要读下面的结构说明；否则忽略本节。**
+
+`visible_rule` 控制题目显示/隐藏，**结构与视图筛选 `filter` 完全一致**（`{logic?, conditions?}`），共用同一套公共协议。
+
+- `conditions` 中的 `field` 引用**同一表单内其他题目的题目名称或题目 ID**（推荐用题目 ID）。
+- 更新时按表单中题目的**实际顺序**判定，只能引用排在当前题目之前的题目；不支持循环引用。
+- 更新 `visible_rule` 需传**完整**的 `{logic, conditions}` 对象（整体覆盖）；要保留现有显隐条件就必须把当前 `visible_rule` 原样带回；传 `null`、省略 `visible_rule` 或传空 `conditions` 都会使题目始终显示。
+- 列出题目（`+form-questions-list`）会在每个题目对象中**原样返回** `visible_rule`；未设置显隐条件的题目返回 `null` 或 `conditions` 为空数组。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["q_001", "==", "是"],
+    ["q_003", ">=", 1000]
+  ]
+}
+```
+
+详细的 `visible_rule` 结构（顶层规则、operator 列表、各题目类型的 value 写法）请阅读 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
 
 ## 输出格式
 
@@ -82,11 +133,13 @@ lark-cli base +form-questions-update \
 > [!CAUTION]
 > 这是**写入操作** — 执行前必须向用户确认。
 
-1. 先用 `+form-questions-list` 获取现有问题及其 `id`
-2. 构造包含 `id` 的更新数组
-3. 执行命令并报告更新结果
+1. 先用 `+form-questions-list` 获取现有问题及其 `id` 和完整配置。
+2. 以现有配置为基线，只修改用户明确要求变化的字段；要保留的字段必须原样带回。
+3. 构造包含 `id` 和目标完整配置的更新数组。
+4. 执行命令并报告更新结果。
 
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-base-filter-condition.md](lark-base-filter-condition.md) — `visible_rule` / `filter` 条件结构公共协议
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-base/references/lark-base-form-submit.md

@@ -4,6 +4,8 @@
 
 通过表单分享链接填写并提交多维表格表单。仅支持分享模式（share_token），支持填写普通字段值和上传本地文件作为附件。
 
+> **⚠️ 高风险写操作（high-risk-write）：** 本命令会向表单写入并提交数据，属于高风险写操作，必须额外传递 `--yes` 进行确认，否则会返回 `confirmation_required` 错误并退出。当用户明确要求提交且目标表单无歧义时，直接附加 `--yes`，无需再次询问。
+
 ## 填写前必读：先获取表单详情
 
 **在调用 `+form-submit` 之前，必须先使用 `+form-detail` 获取表单详情。** 原因如下：
@@ -21,10 +23,11 @@ lark-cli base +form-detail --share-token <share_token>
 
 # 2️⃣ 根据返回的 questions 列表，按 type 格式化值、检查 required、判断 filter 条件
 
-# 3️⃣ 再提交
+# 3️⃣ 再提交（高风险写操作，必须带 --yes）
 lark-cli base +form-submit \
   --share-token <share_token> \
-  --json '{"fields":{...}}'
+  --json '{"fields":{...}}' \
+  --yes
 ```
 
 `+form-detail` 的返回中要重点读取 `questions[].type`、`questions[].required`、题目 `filter` 和附件场景所需的 `data.base_token`。
@@ -35,7 +38,8 @@ lark-cli base +form-submit \
 # 基本提交（填写普通字段）
 lark-cli base +form-submit \
   --share-token <share_token> \
-  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}'
+  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}' \
+  --yes
 
 # 带附件提交（需要额外提供 --base-token）
 lark-cli base +form-submit \
@@ -47,15 +51,17 @@ lark-cli base +form-submit \
       "附件字段名": ["./report.pdf", "./photo.png"],
       "另一个附件字段": ["./doc.docx"]
     }
-  }'
+  }' \
+  --yes
 
 # 使用应用身份（bot）
 lark-cli base +form-submit \
   --share-token <share_token> \
   --json '{"fields":{...}}' \
-  --as bot
+  --as bot \
+  --yes
 
-# 预览 API 调用（不实际执行）
+# 预览 API 调用（不实际执行，dry-run 无需 --yes）
 lark-cli base +form-submit \
   --share-token <share_token> \
   --json '{"fields":{...}}' \
@@ -69,6 +75,7 @@ lark-cli base +form-submit \
 | `--share-token <token>` | 是 | 表单分享 Token（必填），从表单分享链接中提取 |
 | `--base-token <token>` | 条件必填 | Base token；**当 `--json` 包含 `attachments` 时必须提供**，用于将附件上传到 Base Drive Media |
 | `--json <json>` | 是 | JSON 对象，包含 `"fields"`（普通字段值）和 `"attachments"`（附件上传），详见下方说明 |
+| `--yes` | 是 | 确认高风险写操作。本命令为 high-risk-write，不带 `--yes` 会返回 `confirmation_required` |
 | `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
 | `--as` | 否 | 身份：user（默认）\| bot |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
@@ -138,7 +145,8 @@ https://www.example.com/share/base/form/shrbcvST8eZy0vk8zjVZ1CAXNye
 ```bash
 lark-cli base +form-submit \
   --share-token shrbcvST8eZy0vk8zjVZ1CAXNye \
-  --json '{"fields":{...}}'
+  --json '{"fields":{...}}' \
+  --yes
 ```
 
 ## 输出格式
@@ -158,6 +166,7 @@ lark-cli base +form-submit \
 
 ## 提示
 
+- **本命令为高风险写操作（high-risk-write），必须额外传递 `--yes` 确认**，否则返回 `confirmation_required` 并以非零码退出；`--dry-run` 预览除外
 - 本命令仅支持通过表单分享链接（share_token）提交，不支持通过 base_token + table_id + view_id 方式提交
 - **当 `--json` 包含 `attachments` 时，必须额外提供 `--base-token`**，因为附件上传到 Base Drive Media 需要指定目标 Base
 - 附件字段只需在 `--json.attachments` 中提供本地路径即可，CLI 自动完成校验、并行上传、Token 获取和合并写入

package/skills/lark-base/references/lark-base-record-batch-create.md

@@ -7,13 +7,13 @@
 ## 适用场景（重点）
 
 - 适合导入 CSV / Excel、外部系统一次性写入新数据。
-- 先把输入数据映射到合适的字段类型，再组装 `fields + rows`。
+- 先把每条输入数据映射为独立的字段对象，再组装到 `create_records`。
 
 ## 推荐命令
 
 ```bash
 lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> \
-  --json '{"fields":["标题","状态"],"rows":[["任务 A","Open"],["任务 B","Done"]]}'
+  --json '{"create_records":[{"标题":"任务 A","状态":"Open"},{"标题":"任务 B","状态":"Done"}]}'
 
 lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> --json @batch-create.json
 ```
@@ -34,23 +34,25 @@ lark-cli base +record-batch-create --base-token <base_token> --table-id <table_i
 
 本节只说明 `+record-batch-create` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
 
-对象形态：`{"fields":[...],"rows":[...]}`。
+对象形态：
+
+```json
+{"create_records":[{"标题":"任务 A","状态":"Open"},{"标题":"任务 B","状态":"Done"}]}
+```
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `fields` | `string[]` | 是 | 字段 ID 或字段名数组 |
-| `rows` | `CellValue[][]` | 是 | 二维数组，每一行按 `fields` 同序给 cell；单次最多 200 行 |
+| `create_records` | `Array<Map<FieldNameOrID, CellValue>>` | 是 | 记录字段对象数组；每条记录可以提交不同字段，单次最多 200 条 |
 
 ## 返回重点
 
-返回 `fields`、`field_id_list`、`record_id_list`、`data`，其中 `data` 与 `fields` 列顺序对齐。
+返回 `record_id_list` 和可选的 `ignored_fields`。
 
 ## 坑点
 
-- `fields` 与每行 `rows` 的列顺序必须一一对应。
-- 空单元格必须显式用 `null` 填充。
-- 单次最多 200 行，超出需分批写入。
-- select 写入未知选项时平台可能自动新增选项；如果不是要新增选项，先确认真实选项名。
+- 每个 `create_records` 元素都是独立的记录字段对象，只提交该记录需要写入的字段。
+- 单次最多 200 条，超出需分批写入。
+- `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
 
 ## 参考
 

package/skills/lark-base/references/lark-base-record-batch-update.md

@@ -2,13 +2,13 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-批量更新记录（将同一份 `patch` 批量应用到一批 `record_id_list`）。
+通过 `update_records` 为每条记录提交字段值。
 
 ## 推荐命令
 
 ```bash
 lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> \
-  --json '{"record_id_list":["<record_id>"],"patch":{"状态":"完成"}}'
+  --json '{"update_records":{"<record_id_a>":{"状态":["完成"]},"<record_id_b>":{"分数":20}}}'
 
 lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> --json @batch-update.json
 ```
@@ -29,23 +29,25 @@ lark-cli base +record-batch-update --base-token <base_token> --table-id <table_i
 
 本节只说明 `+record-batch-update` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
 
-对象形态：`{"record_id_list":[...],"patch":{...}}`。
+对象形态：
+
+```json
+{"update_records":{"recA":{"状态":["完成"]},"recB":{"分数":20}}}
+```
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `record_id_list` | `string[]` | 是 | 要更新的记录 ID 列表（单次最多 200 条） |
-| `patch` | `Map<FieldNameOrID, CellValue>` | 是 | 字段更新对象；key 是字段名或字段 ID，value 是 `CellValue`；同一份 `patch` 会应用到 `record_id_list` 内所有记录 |
+| `update_records` | `Map<RecordID, Map<FieldNameOrID, CellValue>>` | 是 | record ID 到字段更新对象的映射（单次最多 200 条） |
 
 ## 返回重点
 
-返回 `record_id_list`、`update`，可选返回 `ignored_fields`；`update` 可能为空对象。
+成功响应只包含可选的 `ignored_fields`；没有忽略字段时 `data` 为空对象。请求不会预先校验 record ID 是否存在，因此需要确认实际写入结果时，应再用 `+record-get` 读回目标记录。
 
 ## 坑点
 
-- 这是“同值批量更新”：所有 `record_id_list` 都应用同一份 `patch`。
-- `record_id_list` 最大 200 条，超过会被接口校验拒绝。
+- 单次最多更新 200 条记录，超过会被接口校验拒绝。
 - 命令不会自动做字段/行映射转换，传什么就发什么。
-- 如果 `patch` 包含只读字段，返回里可能出现 `ignored_fields`；这些字段不会被更新。
+- 如果字段映射包含只读字段，返回里可能出现 `ignored_fields`；这些字段不会被更新。
 
 ## 参考
 

package/skills/lark-base/references/lark-base-record-upsert.md

@@ -55,7 +55,7 @@ lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --r
 ## 坑点
 
 - 有 `--record-id` 就一定更新；不传就一定创建，不会自动查重或按业务键 upsert。
-- select 写入未知选项时平台可能自动新增选项；如果不是要新增选项，先用 `+field-list` / `+field-search-options` 确认真实选项名。
+- `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
 - 这是写入操作，执行前必须确认目标表和字段。
 
 ## 参考

package/skills/lark-base/references/lark-base-role-guide.md

@@ -6,6 +6,7 @@ This guide is the entry point for Base advanced permissions and roles. Use it to
 
 | Goal | Command | Notes |
 |------|---------|-------|
+| Check advanced permission status | `+base-get` | Read `data.base.is_advanced`. There is no `+advperm-get` command. |
 | 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. |
@@ -14,6 +15,16 @@ This guide is the entry point for Base advanced permissions and roles. Use it to
 | 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. |
 
+## Required order
+
+At the start of a role workflow, before the first `+role-list`, `+role-get`, `+role-create`, `+role-update`, or `+role-delete` call:
+
+1. Run `lark-cli base +base-get --base-token <base_token>` and inspect `data.base.is_advanced`.
+2. If `is_advanced` is `false`, run `+advperm-enable` before the role command. If the user did not authorize enabling advanced permissions, stop and explain the required precondition.
+3. Run the requested role commands only after `is_advanced` is `true` or `+advperm-enable` succeeds. Reuse that confirmed status for later role calls in the same workflow.
+
+Do not probe with `+advperm-get`: that command is not supported. Do not use an empty `+role-list` response to infer the advanced permission status; a disabled Base can also return an empty list.
+
 ## Safety boundaries
 
 - Role operations require advanced permissions to be enabled and the caller to be a Base admin.