@amaster.ai/pi-lark 0.1.8 → 0.1.10

package/skills/lark-base/references/{lark-base-field-json.md → lark-base-field-schema.md}

@@ -1,4 +1,4 @@
-# Base field JSON SSOT
+# Base Field Schema
 
 > 适用命令：`lark-cli base +field-create`、`lark-cli base +field-update`
 
@@ -10,9 +10,9 @@
 - `+field-create --json` 接受一个字段对象或非空字段对象数组。
 - `+field-update --json` 只接受一个字段对象。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
-- 字段默认值使用 `default_value`，直接传对应 CellValue；支持范围只有 `text`、`number`、静态 `select`、`datetime`、`user`。清空默认值传 `null`；省略表示创建时不设置、更新时不修改。
+- 字段默认值使用 `default_value`，直接传对应 CellValue；支持范围只有 `text`、`number`、静态 `select`、`datetime`、`user`。清空默认值传 `null`；创建时省略表示不设置。
 - 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。
-- `+field-update` 使用同样的字段 JSON 结构，但语义是 `PUT`；这是高风险写入操作，建议先 `+field-get` 再按目标状态全量提交，并带 `--yes`。
+- `+field-update` 是 override 式的完整覆盖 `PUT`，不是 partial update；先用 `+field-get` 读取当前定义，在其基础上修改目标属性，并把整个字段需要保留的可写配置完整写回，同时带 `--yes`。
 - `type=formula` 或 `type=lookup` 创建/更新前，必须先读对应 guide。
 
 推荐示例：
@@ -41,6 +41,7 @@
 | `lookup` | `type` `name` `from` `select` `where` | `aggregate` |
 | `auto_number` | `type` `name` | `style.rules` |
 | `attachment` / `location` / `checkbox` | `type` `name` | 无 |
+| `button` | `type` `name` `button_config.title` | 无 |
 
 所有类型都可额外传 `description`；上表的“常见补充字段”只列类型特有配置。
 
@@ -185,7 +186,7 @@
 - `icon` 默认 `star`
 - `icon` 可用：`star`、`heart`、`thumbsup`、`fire`、`smile`、`lightning`、`flower`、`number`
 - `min` 取值 `0..1`，默认 `1`
-- `max` 默认 `5`；常见或已文档化的范围为 `1..10`，但 CLI 不强制上限为 `10`。如果用户明确需要更大评分范围，优先确认平台能力或用 `+field-create/update --dry-run` 检查请求形状；平台拒绝后再建议改用普通数字或进度字段。
+- `max` 取值 `1..10`，默认 `5`
 
 ```json
 {
@@ -229,6 +230,8 @@
 
 #### 动态选项
 
+当新字段要引用或复用另一选项字段的选项列表时，优先使用 `dynamic_options_source`，避免重复定义和维护 `options`。
+
 支持字段：`multiple`、`dynamic_options_source`
 动态选项不支持 `default_value`。
 
@@ -264,7 +267,7 @@
 {
   "type": "datetime",
   "name": "截止时间",
-  "default_value": "2026-03-24 10:00:00"
+  "default_value": "2026-03-24 10:00"
 }
 ```
 
@@ -272,7 +275,7 @@
 
 默认值 / 约束：
 - `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`
-- `style.format` 只控制前端显示格式；当前可配置格式最多显示到分钟，底层时间值仍可保留秒级精度。
+- `style.format` 只控制 Base 前端展示，不影响 CLI 读取的 CellValue；前端当前最多配置到分钟级展示，底层时间值以毫秒级精度存储。
 
 常用写法：
 
@@ -305,12 +308,7 @@
 
 ### 3.6 user / group_chat
 
-人员字段和群字段都支持 `multiple`。
-`user` 支持 `default_value`：人员 CellValue 数组，元素可用 `{ "id": "ou_xxx" }` 或 `{ "$slot": "current_user" }`；不要猜用户 ID。`group_chat` 不支持默认值。
-
-默认值 / 约束：
-- `multiple` 默认 `true`
-- `user` 字段支持 `default_value` 配置，`group_chat` 字段不支持 `default_value` 配置。
+两者都支持 `multiple`（默认 `true`）；仅 `user` 支持人员数组 `default_value`，元素使用 `{ "id": "ou_xxx" }` 或 `{ "$slot": "current_user" }`，用户 ID 必须来自真实查询。
 
 ```json
 {
@@ -327,15 +325,7 @@
 
 ### 3.7 created_by / updated_by
 
-系统创建人 / 系统修改人字段；记录写入时应视为只读。
-
-```json
-{ "type": "created_by", "name": "创建人" }
-```
-
-```json
-{ "type": "updated_by", "name": "更新人" }
-```
+系统创建人和修改人字段，记录写入时只读：`{ "type": "created_by", "name": "创建人" }`、`{ "type": "updated_by", "name": "更新人" }`。
 
 ### 3.8 link
 
@@ -377,7 +367,7 @@
 
 ### 3.9 formula
 
-公式字段；`expression` 必填。创建/更新前先读 [formula-field-guide.md](formula-field-guide.md) 学习公式语法。
+公式字段；`expression` 必填。创建/更新前先读 [Formula Field](lark-base-field-formula.md) 学习公式语法。
 
 ```json
 {
@@ -389,34 +379,7 @@
 
 ### 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"
-}
-```
+查找引用字段使用 `from`、`select`、`where` 和可选 `aggregate`；结构、条件和聚合值必须按 [Lookup Field](lark-base-field-lookup.md) 构造。
 
 ### 3.11 auto_number
 
@@ -431,52 +394,7 @@
 }
 ```
 
-支持字段：`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" }
-```
+`style.rules` 包含 1–9 条规则：固定文本用 `{ "type":"text", "text":"TASK-" }`；递增序号用 `{ "type":"incremental_number", "length":4 }`（长度 1–9）；创建时间用 `{ "type":"created_time", "date_format":"yyyyMMdd" }`，格式支持 `yyyyMMdd`、`yyyyMM`、`yyMM`、`MMdd`、`yyyy`、`MM`、`dd`。
 
 自定义规则：
 
@@ -504,22 +422,28 @@
 { "type": "location", "name": "位置" }
 ```
 
-写入必须使用 `{lng,lat}`。location 读回会包含 `full_address`；筛选和 `location -> text` 类型转换按 `full_address` 字符串处理，只有公式能访问坐标。
+Location 读取为 `{lng,lat,full_address}`；写入只使用数字 `{lng,lat}`，`full_address` 由平台根据坐标解析，不允许手动指定；筛选行为按照 `full_address` 做字符串筛选，将 Location 当作文本列使用文本 operator。`location -> text` 时只保留 `full_address`。
 
 ```json
 { "type": "checkbox", "name": "完成" }
 ```
 
+### 3.13 button
+
+```json
+{ "type": "button", "name": "按钮", "button_config": { "title": "点击按钮" } }
+```
+
+绑定 Workflow 时，使用 `+button-rule-bind`；读取绑定关系时，使用 `+button-rule-get`；解除绑定用 `+button-rule-unbind`。
+
 ## 4. 创建与更新
 
 - `+field-create`：按目标字段配置直接构造 `--json`。
-- `+field-update`：使用同样的 JSON 结构，但语义是 `PUT`；建议先 `+field-get`，再按目标完整状态提交，并带 `--yes`。当 `type` 是 `auto_number` 时，更新编号规则本身就会把新规则应用到已有编号，无需额外参数，也不要在 JSON 里塞额外的底层实现参数。
+- `+field-update`：使用同样的 JSON 结构，但执行完整覆盖更新，不是局部 patch。先用 `+field-get` 读取当前定义，在其基础上修改目标属性；需要保留的名称、类型、样式、选项、默认值、描述及类型专属配置都应完整写回，并带 `--yes`。
 
 ## 5. 暂不支持字段
 
-Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂时都没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
-
-遇到暂不支持的字段类型时，直接说明 Base CLI 当前不支持并停止；不要猜测未注册的字段 JSON、service 或 schema，也不要用其他字段类型冒充目标能力。
+Object（对象字段）、Stage（流程字段）暂时没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
 
 ## 6. 易错点
 

package/skills/lark-base/references/lark-base-field-update.md

@@ -14,19 +14,6 @@ lark-cli base +field-update \
   --json '{"name":"状态","type":"select","multiple":false,"default_value":["Doing"],"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,"default_value":null,"description":"用于标记记录的直接负责人"}' \
-  --yes
-
-lark-cli base +field-update \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --field-id <field_id> \
-  --json '{"name":"编号","type":"auto_number","style":{"rules":[{"type":"text","text":"TASK-"},{"type":"created_time","date_format":"yyyyMM"},{"type":"text","text":"-"},{"type":"incremental_number","length":4}]}}' \
-  --yes
 ```
 
 ## 参数
@@ -49,19 +36,17 @@ lark-cli base +field-update \
 PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 ```
 
-当 `--json.type` 是 `auto_number` 时，仍然走同一个 v3 字段更新接口：更新自动编号规则后，接口现状就会把新规则应用到已有编号（这是接口默认行为，只是 agent 通常不知道），因此**不需要**任何额外开关或参数。只需要正常提交目标自动编号字段定义即可；如果用户要求“将修改用于已有编号”，直接执行这次 `+field-update` 就能达到效果，不要在 `--json` 里额外添加任何参数去“触发”重排。
-
 ## JSON 值规范
 
 - `--json` 必须是 **JSON 对象**，顶层直接传字段定义。
-- 更新语义是 `PUT`（全量字段配置更新），不要只传零散片段；至少显式包含 `name`、`type`，并补齐该类型所需关键配置。
+- 更新语义是 override 式的完整覆盖 `PUT`，不是 partial update；先读取当前定义，再提交整个字段需要保留的可写配置，不要只传零散片段。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
-- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；传 `null` 清空，省略表示不修改现有默认值。完整规则见 [lark-base-field-json.md](lark-base-field-json.md)。
+- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；传 `null` 清空。完整规则见 [Field Schema](lark-base-field-schema.md)。
 - `select` 更新时：`options` 仍按对象数组传，避免混入无效字段。
 - `link` 更新限制：
   - 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。
   - 现有 `link` 字段的 `bidirectional` 不能改。
-- `auto_number` 更新的 `style.rules` 支持 `text`、`created_time`、`incremental_number`。
+- 更新 `auto_number.style.rules` 会按新规则更新已有记录的编号；规则结构见 [Field Schema](lark-base-field-schema.md)。
 
 **推荐更新示例**
 
@@ -79,32 +64,17 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 }
 ```
 
-**字段说明示例**
-
-```json
-{
-  "name": "负责人",
-  "type": "user",
-  "multiple": false,
-  "description": "用于标记记录的直接负责人"
-}
-```
-
 ## 返回重点
 
 - 返回 `field` 和 `updated: true`。
-- `updated:true` 只表示更新请求成功，不表示字段结构、已有记录值或下游能力已经完成验证。`+field-update` 无法知道更新前的字段类型，因此成功响应会推荐执行 `+field-get`；若发生类型转换，还要抽样读取记录值。
-- 如果响应中的 `field.type` 与提交的 `type` 不一致，必须把它当作待核验的类型不匹配；不能返回完成态，也不能只根据其中任一类型推断更新成功。
-- 如果 API 报告本次更新没有产生任何变更（no-op），命令会如实返回该错误；这通常说明目标字段已是期望状态，不要机械重试同一份 `+field-update`。需要确认当前字段完整状态时执行 `+field-get`。
-- 如果返回 `field_get_recommended:true` 或 `next_step:"field_get"`，按提示读回字段；`auto_number` 更新后还应抽样读记录值确认编号已按新规则生成。
+- 按返回的 `next_step` 和 `verification_hint` 继续；类型转换涉及已有值时抽样读取记录。
 
 ## 工作流
 
 
-1. 建议先用 `+field-get` 拉现状，再做最小化修改。
+1. 先用 `+field-get` 读取当前定义，只改变目标属性，并把需要保留的其他可写配置完整写回。
 2. `formula/lookup` 类型更新前先阅读对应指南。
-3. 如果更新 `auto_number`，理解为“更新编号规则，同时把新规则应用到已有编号”；执行后按返回提示读回字段并在必要时抽样记录值。
-4. 如果这次更新会改变字段 `type` 先按下方“字段类型变更规则”判断能否执行。如果不修改 `type`，大多数场景都相对安全。
+3. 如果这次更新会改变字段 `type`，先按下方“字段类型变更规则”判断能否执行。如果不修改 `type`，大多数场景都相对安全。
 
 ## 字段类型变更规则
 
@@ -149,10 +119,10 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 
 只有在**整列数据丢失可接受**时，才允许对黑名单场景例外执行。
 
-- `EmptyColumn`: 该列为空
-- `FreshTableInit`: 新建空表初始化
-- `PrimaryFieldBootstrap`: 主列不能删，只能更新完成初始化
-- `ExplicitLossAccepted`: 用户明确接受整列数据丢失
+1. 该列为空。
+2. 正在初始化新建的空表。
+3. 主字段不能删除，需要通过更新完成初始化。
+4. 用户明确接受整列数据丢失。
 
 不满足以上条件时，不要转换。
 
@@ -167,14 +137,6 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
   - 可能影响视图 / 筛选 / 排序 / 公式 / lookup / 写入引用
 - 如果用户不接受风险：不要执行转换。
 
-### 完成态验证
-
-- `FieldReadback`: 读回字段结构，确认 `type` / `multiple` / `style` / `options`
-- `NoopReadback`: `+field-update` 返回 no-op 错误时，只能说明 API 报告没有产生变更；可以跳过重复 update，但不能替代 `FieldReadback`
-- `ValueReadback`: 抽样读回转换后的单元格值
-- `DownstreamReadback`: 若涉及看板 / 分组 / 排序 / lookup / 公式，继续读回结果
-- `CompletionRule`: 结构、值、下游能力都正确，才能回复“已完成”
-
 ## 坑点
 
 - ⚠️ 这是全量字段属性更新语义，不是 patch。
@@ -184,6 +146,6 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 ## 参考
 
 - 更新前读取当前字段，确认现有 `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 指南（更新查找引用前必读）
+- [Field Schema](lark-base-field-schema.md) — 字段 JSON 规范（推荐）
+- [Formula Field](lark-base-field-formula.md) — 更新公式前必读
+- [Lookup Field](lark-base-field-lookup.md) — 更新查找引用前必读

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

@@ -10,7 +10,7 @@ Filter 是一组「字段/操作符/值」条件的组合，用 `logic`（`and`
 - `+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 章节。
+本协议**不适用于 `+data-query`**。`+data-query` 支持过滤，但使用的是 LiteQuery DSL 的 `filters` 对象结构：`{"type":1,"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["有效"]}]}`，不是这里的 tuple 条件 `["状态","==","有效"]`。需要聚合查询时先返回 [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) 选路；SOP 选定 `+data-query` 后再读取 guide 和完整 DSL reference。
 
 ## 1. 顶层结构
 
@@ -60,12 +60,16 @@ value 类型取决于条件引用对象（字段 / 题目）的类型。
 
 ### `text`
 
-用字符串：
+用字符串；高频的片段包含 / 排除使用 `intersects` / `disjoint`，完整文本比较使用 `==` / `!=`：
 
 ```json
 ["标题", "intersects", "发布"]
 ```
 
+```json
+["标题", "disjoint", "内部"]
+```
+
 ### `location`
 
 location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
@@ -74,8 +78,6 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 ["位置", "intersects", "深圳"]
 ```
 
-不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
-
 ### `number` / `auto_number`
 
 用数字：
@@ -86,27 +88,27 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 
 ### `select`
 
-用选项名数组：
+用选项名数组；`intersects` 表示命中任意选项，`disjoint` 表示不包含其中任何选项：
 
 ```json
 ["状态", "intersects", ["Doing", "Blocked"]]
 ```
 
-### `user` / `created_by` / `updated_by`
+```json
+["状态", "disjoint", ["Archived"]]
+```
 
-用对象数组：
+### `user` / `group_chat` / `created_by` / `updated_by`
 
-> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
+用对象数组；人员使用 `ou_xxx`，群组使用 `oc_xxx`。不知道 ID 时，人员用 `lark-contact` 查询，群组用 `lark-im` 搜索。
 
 ```json
 ["负责人", "intersects", [{ "id": "ou_xxx" }]]
 ```
 
-### `group_chat`
-
-用对象数组：
-
-> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
+```json
+["负责人", "disjoint", [{ "id": "ou_xxx" }]]
+```
 
 ```json
 ["负责群", "intersects", [{ "id": "oc_xxx" }]]
@@ -151,29 +153,15 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 
 ### `formula` / `lookup`
 
-- 筛选值类型由字段计算结果类型动态决定。
-- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
-- 如果报错，再按错误提示把 `value` 改成对应类型。
-
-字符串示例：
-
-```json
-["风险说明", "intersects", "高风险"]
-```
-
-数字示例：
-
-```json
-["汇总分", ">=", 80]
-```
+value schema 随计算结果类型变化；拿不准时先读取字段定义，或根据错误提示修正 value 和 operator。
 
 ## 4. 易错点
 
 - 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
 - `user` / `group_chat` / `link` 不要写成单个标量。
-- `empty` / `non_empty` 不要硬塞无意义的 value。
+- `empty` / `non_empty` 统一表示格子为空 / 非空，不要传 value；标量空格子和多值字段没有任何元素都属于空。
 - 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
-- `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前配置或字段定义，或根据错误提示修正类型。
+- `formula` / `lookup` 的 value schema 是动态的；拿不准 value 类型时先读字段定义，或根据错误提示修正类型。
 
 ## 5. 参考
-- [lookup-field-guide.md](lookup-field-guide.md)
+- [Lookup Field](lark-base-field-lookup.md)

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

@@ -2,7 +2,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-向多维表格表单/问卷中批量添加问题。
+向多维表格表单/问卷中批量添加问题。可以新建字段并作为题目，也可以把已有字段加到表单中作为题目而不新建字段。
 
 ## 命令
 
@@ -54,6 +54,13 @@ lark-cli base +form-questions-create \
   --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":[["是否需要发票","==","是"]]}}]'
+
+# 把已有字段作为题目加到表单中，不新建字段
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"use_existing_field":true,"field_id":"fldEmail","title":"你的邮箱","description":"用于接收回执","required":true}]'
 ```
 
 ## 参数
@@ -70,7 +77,14 @@ lark-cli base +form-questions-create \
 
 ## `--questions` 格式
 
-每个问题对象支持以下字段：
+`--questions` 是 1~10 个问题对象的数组。每个对象二选一：
+
+- 新建字段题目：创建一个新字段，并把该字段作为表单题目。
+- 已有字段题目：把一个已存在字段加入表单，只改变该字段在表单中的可见性，不创建字段。
+
+### 形态 A：新建字段题目
+
+新建字段题目会在数据表中创建新字段，返回的 question `id` 就是新字段的 `field_id`。CLI 当前要求每个新建字段题目显式传 `title` 和 `type`。
 
 | 字段                    | 必填 | 说明 |
 |-----------------------|------|------|
@@ -84,6 +98,22 @@ lark-cli base +form-questions-create \
 | `style`               | 否 | 字段样式配置（见下方说明） |
 | `visible_rule`        | 否 | 题目显隐条件（见下方「`visible_rule` 显隐条件」） |
 
+### 形态 B：已有字段题目
+
+已有字段题目只把一个已存在字段加入表单，不新建字段，也不改变已有记录数据。适合把之前用 `+form-questions-delete --keep-field` 移出表单的题目重新加回，或把表里已有字段补充为表单题目。
+
+| 字段                    | 必填 | 说明 |
+|-----------------------|------|------|
+| `use_existing_field`  | **是** | 固定传 `true`，表示使用已有字段 |
+| `field_id`            | **是** | 已有字段的 ID 或字段名；推荐字段 ID，避免同名字段歧义。引用长度 1~100，较长字段名请改用字段 ID |
+| `title`               | 否 | 题目标题；省略时使用字段名 |
+| `description`         | 否 | 问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
+| `required`            | 否 | 是否必填（true/false），默认 false |
+| `option_display_mode` | 否 | 选项展示方式（仅已有字段为 `select` 时有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
+| `visible_rule`        | 否 | 题目显隐条件（见下方「`visible_rule` 显隐条件」） |
+
+已有字段题目不要携带字段定义属性，例如 `type`、`style`、`options`、`multiple`、`name`。服务端使用 strict schema，误传不属于该形态的字段会被拒绝。
+
 ### `style` 字段说明
 
 | 类型 | style 结构 | 说明 |
@@ -139,10 +169,11 @@ lark-cli base +form-questions-create \
 
 1. 先确定表单所属的真实 `table_id`，并在整个表单管理工作流中复用它；仅在 ID 缺失或归属不明确时调用 `+table-list`。
 2. 用 `+form-questions-list` 查看现有问题。问题 `id` 是承载该问题的 `field_id`，不是独立于数据表的临时 ID。
-3. 除非用户明确要求同名的独立问题，否则目标标题已经存在时用 `+form-questions-update` 更新必填状态、标题或描述；不要创建同名问题后再删除旧问题。
-4. 创建确实不存在的问题，或用户明确要求的同名独立问题，并报告新建的问题 ID。
+3. 需要把表里已有字段加进表单时，先用 `+field-list` 确认真实字段 ID 和字段类型，再用 `use_existing_field:true` + `field_id`；字段已经是可见题目时不要重复创建，改用 `+form-questions-update`。
+4. 除非用户明确要求同名的独立问题，否则目标标题已经存在时用 `+form-questions-update` 更新必填状态、标题或描述；不要创建同名问题后再删除旧问题。
+5. 创建确实不存在的问题，或用户明确要求的同名独立问题，并报告新建的问题 ID。
 
-`+form-questions-delete` 会删除承载问题的数据表字段，不能删除主字段问题。不要通过“新建重复问题再删除旧问题”来替换主字段。
+`+form-questions-delete` 默认会删除承载问题的数据表字段及记录数据；如果只是想把题目移出表单并保留字段，必须用 `+form-questions-delete --keep-field`。移出后可用本文的已有字段题目形态加回。
 
 ## 参考
 

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

@@ -51,7 +51,11 @@ lark-cli base +record-batch-create --base-token <base_token> --table-id <table_i
 ## 坑点
 
 - 每个 `create_records` 元素都是独立的记录字段对象，只提交该记录需要写入的字段。
-- 单次最多 200 条，超出需分批写入。
+- 单次最多 200 条；`1254104` 表示超过单批上限，拆成多个批次。
+- `1254045` 表示字段不存在，重新 `+field-list` 后使用真实字段名或 `field_id`。
+- `1254015` 表示 CellValue 类型不匹配，按真实 Field schema 和 CellValue 规范修正。
+- 返回 `ignored_fields` / `READONLY` 时，从普通 Record 写入中移除 Formula、Lookup、系统字段和自动编号等只读字段。
+- 同一 Table 连续批量写入使用串行执行；`1254291` 表示并发写冲突，短暂等待后重试当前批次。
 - `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
 
 ## 参考

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

@@ -45,9 +45,12 @@ lark-cli base +record-batch-update --base-token <base_token> --table-id <table_i
 
 ## 坑点
 
-- 单次最多更新 200 条记录，超过会被接口校验拒绝。
+- 单次最多更新 200 条记录；`1254104` 表示超过单批上限，拆成多个批次。
+- `1254045` 表示字段不存在，重新 `+field-list` 后使用真实字段名或 `field_id`。
+- `1254015` 表示 CellValue 类型不匹配，按真实 Field schema 和 CellValue 规范修正。
 - 命令不会自动做字段/行映射转换，传什么就发什么。
-- 如果字段映射包含只读字段，返回里可能出现 `ignored_fields`；这些字段不会被更新。
+- 如果字段映射包含只读字段，返回里可能出现 `ignored_fields` / `READONLY`；移除 Formula、Lookup、系统字段和自动编号等只读字段。
+- 同一 Table 连续批量写入使用串行执行；`1254291` 表示并发写冲突，短暂等待后重试当前批次。
 
 ## 参考
 

package/skills/lark-base/references/lark-base-record-history-list.md

@@ -2,6 +2,16 @@
 
 查询单条记录的变更历史。它返回历史事件，不返回记录当前值，也不支持整表审计扫描。
 
+## 使用前置
+
+`+record-history-list` 仅查询单条记录。调用前必须获得能唯一对应用户指定目标、且与 `table_id` 属于同一张表的 `record_id`。
+
+如果当前信息无法唯一确定目标记录，先向用户确认，必要时用 `+record-list` 辅助定位；不得自行选择记录，也不得扩展为批量或整表扫描。需要查询多条记录时，先确认范围，再逐条调用。
+
+用 `+record-list` 展示候选时，可重复传入 `--field-id` 做最小投影。字段名包含空格时，需要给完整值加引号，例如 `--field-id "Project Owner"`。
+
+用户明确指定某个视图的第 N 行时，先用同一 `view_id` 调用 `+record-list`，并将 `--offset` 设为 N-1、`--limit` 设为 1。默认 Markdown 输出从 `_record_id` 列读取唯一记录 ID；显式使用 `--format json` 时从 `.data.record_id_list[0]` 读取。`_record_id` 不是 JSON 顶层字段；视图或排序上下文不明确时仍需先确认。
+
 ## 推荐命令
 
 ```bash
@@ -16,14 +26,21 @@ lark-cli base +record-history-list \
   --record-id <record_id> \
   --page-size 30 \
   --max-version <next_max_version>
+
+lark-cli base +record-history-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id> \
+  --format pretty
 ```
 
 ## 返回解释
 
 - 历史条目通常按版本号降序返回，最新在前。
 - 每条历史包含版本号、操作人、操作时间、操作类型和字段变更。
-- `create_time` 是秒级 Unix 时间戳。
+- 默认 JSON 中的 `create_time` 是秒级 Unix 时间戳；`--format pretty` 会将其转换为带 UTC 偏移的本地时间，并和操作人、字段变化放在同一行。
 - `field_changes` 描述字段变更，重点看字段名/字段类型、`before` 和 `after`。
+- `--format pretty` 中空的 `before` 或 `after` 显示为 `-`；默认 JSON 保留原始值。
 - `activity_type` 常见值：`create`（创建记录）、`update`（编辑记录）、`delete`（删除记录）。
 
 以下字段类型的变化可能不会出现在 `field_changes` 中：
@@ -40,4 +57,4 @@ lark-cli base +record-history-list \
 ## 注意
 
 - `table-id` 和 `record-id` 必须来自同一张表。
-- 这是单条记录历史，不是表级审计；需要查多条记录时串行调用。
+- 这是单条记录历史，不是表级审计；用户明确要求查询多条记录时，先确认目标范围，再按记录串行调用。