@amaster.ai/pi-lark 0.1.2-beta.60 → 0.1.2-beta.62

package/skills/lark-base/references/lark-base-dashboard-block-config.md

@@ -211,7 +211,7 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
   - `group_by[].sort.type` 为 `group` 或 `view` 且缺少 `order` 时，自动补 `order:"asc"`；`value` 排序不会自动补方向
 - 本地校验（可通过 `--no-validate` 跳过）
   - `+dashboard-block-create` 默认对 `data_config` 做轻量校验；失败会聚合错误并给出修复建议
-  - `+dashboard-block-update` 不做强类型校验，由后端验证具体字段
+  - `+dashboard-block-update` 不带 `--type`，所以不做按组件类型的强校验，字段由后端验证；但 `number_format` 子字段与 create 一样本地拦截（见下方 number_format 小节）
   - 仅需传入合法 JSON；CLI 不会擅自改写你的业务含义
 
 ## 可复制模板
@@ -372,6 +372,33 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 }
 ```
 
+### statistics 指标卡数值格式 number_format（可选）
+
+仅 `type: statistics` 支持在 `data_config` 里加可选 `number_format`，控制数值展示格式与精度；不传时服务端会补 `{"formatName":"digital"}`，`precision` 保持省略。其它组件类型不支持该字段：create 会被 CLI 直接拒绝（显式 `--no-validate` 可跳过），避免把后端严格 schema 错误延迟到请求阶段；update 不带 `--type`，由服务端结合组件现有类型裁决。
+
+- `formatName`（string，可选）：必须精确匹配下表 5 个枚举之一，**区分大小写**（不同于 `series[].rollup` 会被自动转成大写，这里不做规范化，`DIGITAL` 会被拒绝）。
+- `precision`（integer，可选）：小数位数，`0` 到 `9` 的整数；`2.5` 这类非整数会被本地拒绝。
+
+| formatName | 含义 | 示例（precision=2） |
+|------------|------|--------------------|
+| `digital` | 千分位数字（不传 `number_format` 时的服务端默认值） | `1,234.56` |
+| `digital_without_separator` | 无千分位数字 | `1234.56` |
+| `percentage_rounded` | 百分比 | `1,234.56%` |
+| `cyn_rounded` | 人民币金额 | `¥1,234.56` |
+| `dollar_rounded` | 美元金额 | `$1,234.56` |
+
+指标卡（金额，保留 2 位小数）：
+
+```json
+{
+  "table_name": "订单表",
+  "series": [{ "field_name": "金额", "rollup": "SUM" }],
+  "number_format": { "formatName": "dollar_rounded", "precision": 2 }
+}
+```
+
+> **更新时 `number_format` 按子字段合并**：例如现有 `{"formatName":"digital","precision":2}` 时只传 `{"number_format":{"precision":0}}`，服务端会保留 `formatName:"digital"` 并把精度改为 `0`。其它顶层 key 的更新策略见 [lark-base-dashboard.md](lark-base-dashboard.md)。
+
 文本组件（Markdown 富文本）：
 
 ```json

package/skills/lark-base/references/lark-base-dashboard.md

@@ -17,10 +17,26 @@ Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**
 | 创建/删除/改名称 | `+dashboard-create/delete/update` | 本页下方「仪表盘管理」 |
 | 在仪表盘里添加组件 | `+dashboard-block-create` | 先定位 dashboard、表和字段，再读 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 构造 `data_config` |
 | 修改组件 | `+dashboard-block-update` | 先读 block 现状，再读 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 决定替换哪些顶层 key |
+| 创建/更新时指定组件精确位置大小 | `+dashboard-block-create/update --position` | 本页下方「精确布局 --position vs +dashboard-arrange」 |
 | 查看仪表盘有哪些组件 | `+dashboard-get` 或 `+dashboard-block-list` | 本页下方「查看仪表盘」 |
 | 读取图表计算结果 | `+dashboard-block-get-data` | 返回图表最终数据协议；需要 block 元数据先用 `+dashboard-block-get` |
 | 智能重排组件布局 | `+dashboard-arrange` | 用户明确要求重排，或本次会话新建仪表盘的收尾整理；无法指定 `x/y/w/h`、精确位置或尺寸 |
 
+## 精确布局 --position vs +dashboard-arrange
+
+create/update 可选 `--position`，用 12 列栅格坐标精确指定单个组件的落点与大小：`{"x","y","w","h"}`，`x`/`y` 为左上角坐标（>=0），`w` 为宽度（1..12，且 `x+w<=12`），`h` 为高度（>=1）。它与 `name`/`type`/`data_config` 平级挂在请求体顶层。
+
+> [!IMPORTANT]
+> - **四个 key 必须齐全且都是数字**：`position` 按整体提交、不做逐字段合并，所以只传 `{"x":6}` 表达的不是"只挪位置不改大小"，而是一个缺了三项的位置。本地会拒绝残缺对象（含显式 `null`）。
+> - 坐标**取值不做本地校验**：越界、负值或重叠坐标会原样发给服务端，由服务端自动重排。调用方仍应优先规划 12 列范围内且不重叠的坐标，避免自动重排改变预期落点。
+> - 不传 `--position`：create 由服务端自动装箱，update 保持当前布局不变。
+> - 只有用户明确给出 `x/y/w/h`、具体行列/顺序、每个组件宽高或可直接换算的尺寸比例时才用 `--position`。"调整布局""美化""撑满""铺满"本身不算精确约束，没有组件级坐标或尺寸时优先用 `+dashboard-arrange` 整盘编排。
+> - 命令成功即视为写入成功，一般无需仅为读回位置再调用 `+dashboard-block-get` / `+dashboard-block-list`；成功响应不代表最终渲染位置已经过读回验证。
+
+## statistics 指标卡数值格式
+
+`statistics` 组件可在 create/update 的 `data_config.number_format` 中设置 `formatName` 和 `precision`。create 会校验组件类型和子字段；update 不接收 `--type`，只校验 `number_format` 子字段，再由服务端结合现有 block 类型裁决。枚举、精度范围、更新语义和可复制模板读取 [Dashboard Block 配置](lark-base-dashboard-block-config.md)。
+
 ## 典型场景工作流
 
 ### 场景 1：从 0 到 1 创建仪表盘
@@ -30,7 +46,7 @@ Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**
 - 聚合方式：创建指标卡或分布图时优先把聚合写进 `data_config`，只有 Top N、字段取值探索、复杂筛选校验或 helper 汇总表场景才先用 `+data-query`。
 - Dry-run 边界：已按模板构造的简单指标卡、分布图、趋势图不需要逐个 `--dry-run` 后再真实创建；只有在调试 JSON、检查请求体、复杂自造 `data_config` 或处理 API validation 错误时才 dry-run。
 - 验证方式：创建接口成功返回即表示写入成功。只有结果不确定时才用一次 `+dashboard-get` 或 `+dashboard-block-list` 确认仪表盘和组件存在；不要仅为确认创建而逐组件调用 `+dashboard-block-get-data`。
-- 布局方式：`+dashboard-arrange` 仅两种情况使用：① 用户明确要求美化/重排；② 本次会话中从零新建的仪表盘，建完组件后做一次性布局整理。不是创建成功的必要步骤。
+- 布局方式：用户没有给出组件级坐标或尺寸时，创建完成后用一次 `+dashboard-arrange` 整盘编排即可；只有用户明确给出可执行的精确布局约束时才在 create 中带 `--position`，此时通常不再需要 arrange。
 
 示例：搭建一个销售数据分析仪表盘
 
@@ -68,9 +84,10 @@ lark-cli base +dashboard-block-create \
 
 # 继续创建其他组件...
 
-# 第 5 步：组件创建完成后，使用 arrange 命令智能重排布局（可选但推荐）
+# 第 5 步：组件创建完成后，可按需使用 arrange 智能重排（未使用 --position 时可选）
 # 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
-# 若用户没有要求美化/重排，可先跳过此步骤；这不影响仪表盘和组件是否已创建成功
+# 若任一组件使用了显式 --position，跳过此步骤；除非用户明确同意放弃精确布局
+# 若用户没有要求美化/重排，也可跳过；这不影响仪表盘和组件是否已创建成功
 lark-cli base +dashboard-arrange \
   --base-token xxx \
   --dashboard-id blk_xxx
@@ -105,7 +122,7 @@ lark-cli base +dashboard-block-create \
 ### 场景 3：编辑已有组件
 
 > [!IMPORTANT]
-> `+dashboard-block-update` **不能修改组件的 `type`**（图表类型），只能更新 `name` 和 `data_config`。
+> `+dashboard-block-update` **不能修改组件的 `type`**（图表类型），只能更新 `name`、`data_config` 和可选的 `position`。
 > 如需更换组件类型，必须先删除再重新创建。
 
 ```bash
@@ -132,20 +149,21 @@ lark-cli base +dashboard-block-update \
   --base-token xxx \
   --dashboard-id blk_xxx \
   --block-id chtxxxxxxxx \
-  --data-config '{...}'
+  --data-config '{...}' \
+  --position '{...}'   # 可选，只在需要调整布局时传
 
 ```
 
 ### 场景 4：重排仪表盘布局
 
-当用户明确要求对已有仪表盘进行布局重排或美化时使用（对本次会话从零新建的仪表盘，可在建完组件后直接做一次性整理，见场景 1）。
+当用户要求调整布局、重排、美化、撑满或铺满，但没有给出组件级坐标或尺寸时使用。定位仪表盘后用一次 `+dashboard-arrange` 整盘编排即可（对本次会话从零新建的仪表盘，在建完组件后编排一次）。
 
 > [!CAUTION]
 > - 排列结果是**服务端智能推荐**，不一定完全符合用户预期
-> - Dashboard shortcut 无法指定 `x/y/w/h`、精确位置或尺寸（如"第一排放 A""图表撑满整行"），排列逻辑是**自适应**的
+> - `+dashboard-arrange` 无法指定 `x/y/w/h`、精确位置或尺寸，排列逻辑是**自适应**的；只有用户明确给出可执行的组件级坐标、行列或尺寸约束时才改用 `--position`
 > - **不建议**在已有仪表盘上自动调用，除非用户明确要求
-> - 用户只要求一般性重排/美化时，可执行一次 `+dashboard-arrange`；用户要求精确结果时，先说明限制并询问是否接受自适应布局，接受后才执行，不能静默替代或声称精确满足
-> - 执行一次 `+dashboard-arrange` 后即停止；不要继续探测 raw `lark-cli api`、源码或未公开布局参数
+> - 用户只要求一般性重排、美化、撑满或铺满时，用 `+dashboard-arrange` 整盘编排
+> - 编排结果不理想时，可结合用户反馈再调整；不要为了凑效果去探测 raw `lark-cli api`、源码或未公开布局参数
 
 ```bash
 # 第 1 步：列出仪表盘，定位到目标仪表盘
@@ -232,7 +250,7 @@ A: 常见原因：
 A: 不可以，必须串行执行。等上一个 `+dashboard-block-create` 完成后再执行下一个。
 
 **Q: 组件的 `type` 创建后能改吗？**
-A: 不能。`+dashboard-block-update` 只能修改 `name` 和 `data_config`，不能修改 `type`。
+A: 不能。`+dashboard-block-update` 只能修改 `name`、`data_config` 和 `position`，不能修改 `type`。
 
 **Q: 更新组件的命令和 data_config 怎么写？**
 A:
@@ -242,7 +260,7 @@ A:
 **data_config 更新策略（顶层 key merge）**：
 - 只传入需要修改的顶层字段（如 `series`、`filter`）
 - 未传的顶层字段（如 `group_by`）自动保留原值
-- 但每个传入的字段内部是**全量替换**（如传新 `filter` 会完整覆盖旧 `filter`）
+- 但每个传入的字段内部通常是**全量替换**（如传新 `filter` 会完整覆盖旧 `filter`）；`number_format` 例外，按子字段合并，见 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 的 number_format 小节
 
 **Q: 查看已有组件有什么用？**
 A: 在「添加新组件」或「编辑组件」前查看已有组件可以：

package/skills/lark-base/references/lark-base-data-query.md

@@ -3,8 +3,6 @@
 
 > **前置路由**: [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) | **认证或授权问题**: [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)
 
-本文档合并常用 fewshot 与完整 DSL 协议。只有 [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) 的 Cloud 路径选定 `+data-query` 后才读取，并优先定位与当前查询有关的示例、字段或错误协议。
-
 ## 限制
 
 - **权限要求**（按文档类型分流）：
@@ -75,7 +73,7 @@ lark-cli base +data-query \
 | 参数                     | 必填 | 说明 |
 |------------------------|------|------|
 | `--base-token <token>` | 是 | Base Token（base_token） |
-| `--dsl <json>`         | 是 | LiteQuery Protocol JSON DSL 查询语句 |
+| `--dsl <json>`         | 是 | LiteQuery Protocol JSON DSL 查询语句。注意，本工具 schema 与 record/view 查询的 schema 不同，需要充分阅读本文档后，编写正确的 DSL，避免与其他场景的 DSL 混淆。 |
 
 ## 如何从链接中解析参数
 
@@ -435,7 +433,7 @@ CLI 输出标准信封 `{ok, identity, data}`（失败时为 `{ok:false, identit
 5. 若候选记录包含 link 字段，提取关联 `record_id` 后到关联表用 `+record-get` 批量读取展示字段。
 6. 最终回答展示真实业务字段；内部 `record_id` 用于连接或定位。
 
-不要把 `data-query pagination.limit` 理解为分页扫描；它只限制 Base 云端查询服务返回的聚合结果行数，不支持 offset。需要逐条原始记录时按 Cloud SOP 的 `+record-list` / `+record-search` 回查规则处理。
+不要把 `data-query pagination.limit` 理解为分页扫描；它只限制 Base 云端查询服务返回的聚合结果行数，不支持 offset。需要逐条原始记录时按 [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) 的完整读取或回查路径处理。
 
 ## 坑点
 
@@ -453,6 +451,4 @@ CLI 输出标准信封 `{ok, identity, data}`（失败时为 `{ok:false, identit
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
-- [Cloud SOP](lark-base-record-query-and-analysis-cloud-sop.md) — Cloud 路径的查询范围、下推、分页、`+record-list` / `+record-search` 回查和关系查询
-- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
 - [Field Schema](lark-base-field-schema.md) — 字段类型与 JSON 结构

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

@@ -0,0 +1,170 @@
+# base field-extension
+
+字段插件用于扩展基础字段能力，当同行其他单元格更新时，触发 LLM 推理生成新单元格。当前公开支持的插件 ID 只有 `builtin_llm_completion`，已确认可用于文本、单选、数字字段，让目标字段基于 prompt 和字段引用生成内容，并可手动触发该字段的单元格异步更新任务。
+
+三个命令：
+
+- `+field-extension-get`：读取目标字段当前可识别的插件配置。
+- `+field-extension-update`：安装、更新或清空目标字段插件配置。
+- `+field-extension-update-cells`：对已配置字段插件的目标字段发起手动更新任务。
+
+## 何时使用字段插件
+
+用户明确要让某个已有字段根据其他字段自动生成内容、总结、分类、翻译、提取信息，且目标能力可以用 prompt 表达时，使用字段插件。当前已确认的目标字段类型是文本、单选、数字。
+
+字段插件只能建立在已有字段上，不能创建列 schema。新建字段仍使用 `+field-create`；修改字段类型、选项、名称等 schema 属性仍使用 `+field-update`。
+
+## 推荐命令
+
+```bash
+# 读取当前插件配置
+lark-cli base +field-extension-get \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <target_field_id> \
+  --as user
+
+# 安装或更新 LLM Completion 插件
+lark-cli base +field-extension-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <target_field_id> \
+  --json '{"extension_id":"builtin_llm_completion","inputs":{"prompt":[{"type":"text","text":"请根据 "},{"type":"field_ref","field":"需求描述"},{"type":"text","text":" 输出一句简洁结论。"}]}}' \
+  --as user \
+  --yes
+
+# 清空字段插件配置
+lark-cli base +field-extension-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <target_field_id> \
+  --json '{}' \
+  --as user \
+  --yes
+
+# 按视图范围触发整列更新
+lark-cli base +field-extension-update-cells \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <target_field_id> \
+  --type column \
+  --view-id <view_id> \
+  --as user \
+  --yes
+
+# 只更新指定记录
+lark-cli base +field-extension-update-cells \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <target_field_id> \
+  --type row \
+  --record-id <record_id_1> \
+  --record-id <record_id_2> \
+  --as user \
+  --yes
+```
+
+## 工作流
+
+1. 定位 Base、Table 和目标 Field。目标 Field 是承载插件输出的已有字段，不是 prompt 中被引用的输入字段。
+2. 用 `+field-extension-get` 读取当前配置。返回 `current_extension=null` 表示未配置、无法识别或存量配置无法转换。
+3. 构造 `+field-extension-update --json`。安装或更新时传 `extension_id=builtin_llm_completion` 和 `inputs.prompt`；清空时传 `{}`。
+4. 配置成功后，只有用户明确要立即生成或刷新已有单元格时，才调用 `+field-extension-update-cells` 发起异步生成任务。
+5. 需要验收结果时，等待任务完成或稍后用记录读取命令抽样查看目标字段单元格；`update_cells` 只返回任务 ID，不直接返回生成结果。
+
+## JSON 结构
+
+### 通用结构
+
+`+field-extension-update --json` 的顶层结构是字段插件配置 envelope。不同 `extension_id` 对应不同的 `inputs` 结构；不要把某个插件的 `inputs` 当成所有字段插件的固定结构。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `extension_id` | string | 插件 ID。当前公开只支持 `builtin_llm_completion` |
+| `inputs` | object | 插件配置对象，结构由 `extension_id` 决定 |
+
+清空字段插件配置时传空对象：
+
+```json
+{}
+```
+
+### `builtin_llm_completion`
+
+当前 `builtin_llm_completion` 用于让已有字段根据 prompt 生成内容。它的 `inputs` 结构如下：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `inputs.prompt` | PromptSegment[] | 有序 prompt 片段数组 |
+| `prompt[].type` | string | `text` 或 `field_ref` |
+| `prompt[].text` | string | `type=text` 时必填 |
+| `prompt[].field` | string | `type=field_ref` 时必填，可传当前表的字段 ID 或字段名 |
+
+安装或更新示例：
+
+```json
+{
+  "extension_id": "builtin_llm_completion",
+  "inputs": {
+    "prompt": [
+      {
+        "type": "text",
+        "text": "请根据 "
+      },
+      {
+        "type": "field_ref",
+        "field": "需求描述"
+      },
+      {
+        "type": "text",
+        "text": " 输出一句简洁的中文结论。"
+      }
+    ]
+  }
+}
+```
+
+`field_ref` 只能引用当前表中的其他字段，不能引用目标字段自身；附件字段和其他不支持字段不要作为引用字段。
+
+## 更新单元格
+
+`+field-extension-update-cells` 有两种范围：
+
+这是异步生成任务，响应只表示任务已创建。单元格越多，生成和写回通常耗时越久；整列更新尤其需要控制范围。
+
+| 范围 | 参数 | 语义 |
+|---|---|---|
+| `--type column` | 可选 `--view-id` | 更新目标字段在该视图范围内的单元格；不传 `--view-id` 时后端使用目标表首视图 |
+| `--type row` | 必填一个或多个 `--record-id` | 只更新这些记录上的目标字段单元格 |
+
+`--type row` 不要传 `--view-id`；`--type column` 不要传 `--record-id`。
+
+响应只返回：
+
+```json
+{
+  "task_id": "<task_id>"
+}
+```
+
+## 返回重点
+
+读取和写配置都返回 `current_extension`：
+
+- 已配置并可识别时，`current_extension.extension_id` 表示插件 ID，`current_extension.inputs` 是该插件对应的配置对象。
+- 未配置或当前无法识别时，`current_extension` 为 `null`。
+
+## 权限和风险
+
+- `+field-extension-get` 是只读命令，权限 `base:field:read`。
+- `+field-extension-update` 是高风险写命令，权限 `base:field:update`，会改变目标字段的自动生成配置，执行时必须带 `--yes`。
+- `+field-extension-update-cells` 是高风险写命令，权限 `base:record:update`，会触发目标字段单元格异步写回，执行时必须带 `--yes`。
+- 用户需要具备管理目标表或目标字段插件的权限才能触发更新任务；如果接口返回权限不足，先按 Base 权限或高级权限角色确认用户权限。
+
+## 注意事项
+
+- 目标字段必须是当前字段插件已支持的字段类型；当前已确认支持文本、单选、数字字段。不要把字段插件当成任意字段类型都可用的通用能力。
+- 写入插件配置后，自动更新会强制开启；当前不提供关闭自动更新的参数。
+- 读取接口中的 `field_ref.field` 通常返回字段名称；字段名称不可用时可能返回字段 ID。
+- `+field-extension-update` 不返回 `input_schemas`。
+- `+field-extension-update-cells --type column` 可能触发大量 AI 生成任务，单元格越多耗时通常越久；除非用户明确要求整列刷新，否则优先按 `--type row` 精确更新目标记录。

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

@@ -157,7 +157,7 @@ The `value` inside `{ "type": "constant", "value": ... }` varies by field type:
 | `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" }]` |
+| `link` | Record reference array | `[{ "id": "recxxx" }]`, `[{ "id": "recxxx" }, { "id": "recyyy" }]` |
 | `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 |

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

@@ -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`；上表的“常见补充字段”只列类型特有配置。
 
@@ -427,6 +428,14 @@ Location 读取为 `{lng,lat,full_address}`；写入只使用数字 `{lng,lat}`
 { "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`。
@@ -434,7 +443,7 @@ Location 读取为 `{lng,lat,full_address}`；写入只使用数字 `{lng,lat}`
 
 ## 5. 暂不支持字段
 
-Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂时都没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
+Object（对象字段）、Stage（流程字段）暂时没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
 
 ## 6. 易错点
 

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

@@ -40,7 +40,34 @@ Filter 是一组「字段/操作符/值」条件的组合，用 `logic`（`and`
 }
 ```
 
-## 2. operator
+## 2. 单表谓词下推常用 example
+
+`+record-list` / `+record-search` 的 `--filter-json '<filter-json>'` 也支持使用与视图相同的 tuple condition。以下示例用注释说明各条件的含义；实际传参时删除注释并使用标准 JSON：
+
+```jsonc
+{
+  "logic": "and", // 所有 conditions 同时成立；任意一个成立时使用 "or"
+  "conditions": [
+    ["标题", "==", "Launch plan"], // 文本全等
+    ["标题", "!=", "Archived plan"], // 文本不全等
+    ["标题", "intersects", "urgent"], // 文本包含目标片段
+    ["标题", "disjoint", "internal"], // 文本不包含目标片段
+    ["金额", ">=", 100], // 数字比较；支持 ==、!=、>、>=、<、<=
+    ["状态", "intersects", ["进行中", "暂停"]], // Select 集合相交：包含“进行中”或“暂停”任意一个选项
+    ["状态", "disjoint", ["已终止"]], // Select 集合无交集
+    ["已完成", "==", true], // Checkbox
+    ["负责人", "intersects", [{ "id": "ou_xxx" }]], // 负责人包含某个人；intersects 表示包含数组中任意一个人员
+    ["负责人", "disjoint", [{ "id": "ou_yyy" }]], // 负责人不包含指定人员中的任何一个
+    ["关联项目", "intersects", [{ "id": "recxxx" }]], // 关联项目包含某个 record_id；intersects 表示包含数组中任意一条关联
+    ["备注", "non_empty"], // 格子非空；判断格子为空改用 ["备注", "empty"]
+    ["业务日期", "==", "ExactDate(2026-08-07)"], // 具体一天：按 Base 时区匹配 2026-08-07 当天
+    ["发生时间", ">", "ExactDate(2024-01-31 23:59:59.999)"], // 日期不支持 >=；用 > 前一天最后一毫秒表达含当天的下界
+    ["发生时间", "<", "ExactDate(2024-03-01 00:00:00)"] // 2024 年 2 月范围上界：小于 3 月 1 日零点
+  ]
+}
+```
+
+## 3. operator
 
 可用 operator：
 - `==`
@@ -54,7 +81,7 @@ Filter 是一组「字段/操作符/值」条件的组合，用 `logic`（`and`
 - `empty`
 - `non_empty`
 
-## 3. value 写法
+## 4. value 写法
 
 value 类型取决于条件引用对象（字段 / 题目）的类型。
 
@@ -119,7 +146,7 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 用记录 id 对象数组：
 
 ```json
-["关联任务", "intersects", [{ "id": "rec_xxx" }]]
+["关联任务", "intersects", [{ "id": "recxxx" }]]
 ```
 
 ### `checkbox`
@@ -155,7 +182,7 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 
 value schema 随计算结果类型变化；拿不准时先读取字段定义，或根据错误提示修正 value 和 operator。
 
-## 4. 易错点
+## 5. 易错点
 
 - 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
 - `user` / `group_chat` / `link` 不要写成单个标量。
@@ -163,5 +190,5 @@ value schema 随计算结果类型变化；拿不准时先读取字段定义，
 - 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
 - `formula` / `lookup` 的 value schema 是动态的；拿不准 value 类型时先读字段定义，或根据错误提示修正类型。
 
-## 5. 参考
+## 6. 参考
 - [Lookup Field](lark-base-field-lookup.md)

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

@@ -21,7 +21,7 @@ lark-cli base +form-detail --share-token <share_token> --format pretty
 | `base_token` | 表单所属 Base；提交附件时必须传给 `+form-submit --base-token` |
 | `questions[].id` | 题目标识，通常对应字段 ID |
 | `questions[].title` | 提交时使用的字段名/题目名，以真实返回为准 |
-| `questions[].type` | 决定值格式；与字段类型和 `lark-base-cell-value.md` 对齐 |
+| `questions[].type` | 决定值格式；提交结构见 [form-submit](lark-base-form-submit.md) |
 | `questions[].required` | 判断必填项 |
 | `questions[].filter` | 判断题目是否对当前提交可见；被隐藏的问题不要填写 |
 

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-form-submit.md

@@ -86,7 +86,7 @@ lark-cli base +form-submit \
 
 #### fields（普通字段）
 
-`fields` 中的单元格值写法与 [`lark-base-cell-value.md`](lark-base-cell-value.md) 完全对齐，填写前应先阅读该文档了解各类型的构造规则：
+`fields` 中的常见单元格值按下方示例构造（与主 skill 一致）：
 
 ```json
 {
@@ -126,7 +126,7 @@ CLI 收到路径后会自动完成以下流程：
 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 内部自动完成。
+> Record 写入时附件走独立的 `+record-upload-attachment` 命令；`+form-submit` 则在 `attachments` 中传本地路径，由 CLI 自动上传。
 
 ### 从分享链接提取 share-token
 

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

@@ -10,7 +10,7 @@
 
 用 `+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 顶层字段；视图或排序上下文不明确时仍需先确认。
+用户明确指定某个视图的第 N 行时，先用同一 `view_id` 调用 `+record-list`，并将 `--offset` 设为 N-1、`--limit` 设为 1，再从唯一结果中取得 `record_id`。视图或排序上下文不明确时仍需先确认。
 
 ## 推荐命令