@amaster.ai/pi-lark 0.1.9 → 0.1.10

package/README.md

@@ -14,9 +14,7 @@ Pi extension for [Lark/Feishu](https://www.feishu.cn/) workspace — calendar, d
 
 Add to `~/.pi/agent/settings.json` or a trusted project's `.pi/settings.json`:
 
-Project settings are loaded only after project trust is accepted. For
-environment-backed credentials, use user or agent settings because project
-settings do not expand `${ENV_VAR}`.
+Project settings are loaded only after project trust is accepted. For environment-backed credentials, use user or agent settings because project settings do not expand `${ENV_VAR}`.
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -61,7 +61,7 @@
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.9"
+    "@amaster.ai/pi-shared": "0.1.10"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-apps/SKILL.md

@@ -154,4 +154,4 @@ lark-cli apps +get --app-id <meta_token> -q '.data.app.app_id'
 ## 高影响动作：确认与预授权
 
 - **预授权判定**：判断用户是否表达了"放手做完、不用中途逐步问我"的意图——明确免确认（如"别问 / 直接做 / 自己定"），或要求一气呵成做到完成（如"做完部署上线给我"）。是 → 整个流程按合理默认往下走、不再逐步确认（含 clone 到派生目录、发布等）；否 → 缺失参数（如目录）该问就问、高影响动作先确认。
-- **禁止预授权判定底线**（即便已预授权也不豁免）：① 会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）先 `--dry-run` 确认；② `+role-delete`、`+role-member-remove --all`、批量移除成员必须先确认 app、role、成员范围和后果，不能从泛化"直接做"推导出 `--yes`；命令式"删除/移除某对象"只确定操作目标，不等于用户已确认不可逆后果，未明确确认时应在说明影响后停下请求确认；③ `+html-publish` 体积超限时（判据见 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)），立即停止并转述超限项。
+- **禁止预授权判定底线**（即便已预授权也不豁免）：① 会删/丢数据或不可逆的 DB 操作（判据见 [`lark-apps-db-execute.md`](references/lark-apps-db-execute.md)）先 `--dry-run` 确认；② `+role-delete`、`+role-member-remove --all`、批量移除成员必须先确认 app、role、成员范围和后果，不能从泛化"直接做"推导出 `--yes`；命令式"删除/移除某对象"只确定操作目标，不等于用户已确认不可逆后果，未明确确认时应在说明影响后停下请求确认；③ `+html-publish` 体积超限时（判据见 [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md)），立即停止并转述超限项；④ `+cache-clear` 会清空整个环境的缓存，「用户让我清缓存」只确定了操作目标、不等于确认了这次清空——未拿到对「清空该环境」的明确确认表述时，只出 `--dry-run` 预览或停下请求确认，不得首次调用即自带 `--yes`（判据表见 [`lark-apps-cache.md`](references/lark-apps-cache.md)）。

package/skills/lark-apps/references/lark-apps-cache.md

@@ -12,7 +12,7 @@
 |---|---|---|
 | `+cache-get` | 查一个缓存 key 的内容与信息 | `--key`、`--environment`、`--format` |
 | `+cache-delete` | 删一个缓存 key（重复删不会报错；不需 `--yes`） | `--key`、`--environment` |
-| `+cache-clear` | 清空指定环境下的全部缓存（**高危**） | `--environment`、`--yes` |
+| `+cache-clear` | 清空指定环境下的全部缓存（**高危，须先向用户二次确认**） | `--environment`、`--yes` |
 
 > 所有命令都需 `--app-id`。
 
@@ -20,7 +20,7 @@
 
 - **环境 `--environment dev|online`（可省略）**：缓存按运行环境隔离。不指定时按应用当前的环境配置自动选择——有多环境的应用默认落到开发环境 `dev`，没有多环境的就是线上 `online`；返回结果里的 `environment` 会告诉你这次实际操作的是哪个环境。想固定就显式传。
 - **缓存 key 用 `--key` 传**：传业务里使用的那个 key；是否合法（非空、长度等）由服务端校验，不合法会返回错误。
-- **风险分级**：`+cache-clear` 会清掉整个环境的缓存，是高危操作，不带 `--yes` 会被确认关卡拦下；`+cache-delete` 只删单个 key、影响小，不需 `--yes`。
+- **风险分级**：`+cache-clear` 会清掉整个环境的缓存，是高危操作，不带 `--yes` 会被确认关卡拦下，且**必须先拿到用户对本次清空的确认**（判据见 [+cache-clear](#cache-clear高危)）；`+cache-delete` 只删单个 key、影响小，不需 `--yes`。
 - **`+cache-get` 的内容有两种展示**：`--format json`（默认）原样返回缓存内容，适合精确比对；`--format pretty` 会把内容格式化展开，更便于阅读。
 
 ## 各命令
@@ -36,16 +36,49 @@ lark-cli apps +cache-get --app-id app_xxx --environment online --key <key> --for
 ```
 
 ### +cache-delete
-删一个缓存 key。**重复删、或删一个本就不存在的 key，都算成功**（返回删除数量 0）、不会报错；删中则返回删除数量 1。删掉后应用下次会自动重新取最新数据，影响小，故不需 `--yes`。
+删一个缓存 key。**重复删、或删一个本就不存在的 key，都算成功**（返回 `deleted_key_count=0`）、不会报错；删中则返回 `deleted_key_count=1`。删掉后应用下次会自动重新取最新数据，影响小，故不需 `--yes`。
+
+**响应里的 `deleted_key_count` 别读错**——它是「本次是否真的删掉了东西」的唯一判据：
+
+| `deleted_key_count` | 含义 | 该怎么向用户表述 |
+|---|---|---|
+| `1` | 命中并删掉了 | 「已删除该 key」 |
+| `0` | 请求成功，但没有删掉任何 key——这个 key **本来就不存在或已过期** | 「该 key 原本就不存在／已过期，无需删除」——**不要说成「已成功删除」** |
+
+要证明「删除生效了」，用「删前 `+cache-get` 确认存在 → `+cache-delete` 拿到 `deleted_key_count=1` → 删后 `+cache-get` 得到 `exists=false`」这条链；只靠删后一次 miss 是不够的，因为 key 从一开始就不存在时（`deleted_key_count=0`）结果完全一样。
 
 ```bash
 lark-cli apps +cache-delete --app-id app_xxx --environment dev --key <key>
 ```
 
 ### +cache-clear（高危）
-清空当前应用在**指定环境**下的全部缓存，用于定位不到具体 key 时的快速恢复。影响面是整个环境，必须带 `--yes`；返回本次清除的 key 数量。动手前可先 `--dry-run` 预览将要执行的操作。
+清空当前应用在**指定环境**下的全部缓存，用于定位不到具体 key 时的快速恢复。影响面是整个环境，必须带 `--yes`；返回本次清除的 key 数量。
+
+> [!CAUTION]
+> **默认流程是「先确认、后执行」，不是「直接清」。** 除下表判定为「已确认」的情形外，**不允许在首次调用就自己带上 `--yes`**——用户提出清理请求 ≠ 用户确认了这次清理。
+>
+> 未拿到确认时，你只能做这两件事之一，然后**停下来等用户回话**：
+> 1. 用 `--dry-run` 预览（不触发门禁、不产生任何真实清理），把将执行的请求给用户看；
+> 2. 或者干脆不调命令，直接把「应用 + 环境 + 会清掉该环境全部缓存」讲清楚并请用户确认。
+>
+> 已经拿到确认后，才在原命令末尾补 `--yes` 执行。**看到 exit 10 / `confirmation_required` 不是「补 `--yes` 重试」的信号**，它只是告诉你门禁生效了；该不该补，取决于用户有没有确认过。
+
+**什么算「已确认」（零歧义判据）**：看用户这轮的原话里，有没有对「清空这个环境」的授权表述。
+
+| 用户原话 | 算不算确认 | 你该做什么 |
+|---|---|---|
+| 「帮我清一下 app_xxx 的 online 环境缓存」 | ❌ 不算（这是请求，不是确认） | 先 `--dry-run` 或直接请用户确认，**停下等回话** |
+| 「清一下缓存」（连环境都没说） | ❌ 不算，且环境未定 | 请用户同时确认「清哪个环境」，**严禁自己选 `dev` 或 `online`** |
+| 「我确认清 dev，不要动 online」 | ✅ 算（含确认表述 + 明确环境） | 显式带 `--environment dev --yes` 执行 |
+| 「确认清 online，不用再问」／「是的，清吧」（承接你上一轮的确认提问） | ✅ 算 | 显式带 `--environment online --yes` 执行 |
+
+线上环境额外一条：`--environment online` 是生产数据，**即使用户已明确指名 online，也仍需要上表意义上的确认表述**才可执行；缺确认就只出 `--dry-run` 预览。
 
 ```bash
+# 1) 未确认：只预览，不清理（--dry-run 不触发门禁、不产生真实动作）
+lark-cli apps +cache-clear --app-id app_xxx --environment online --dry-run
+
+# 2) 用户确认后：补 --yes 执行
 lark-cli apps +cache-clear --app-id app_xxx --environment dev --yes
 ```
 
@@ -56,6 +89,6 @@ lark-cli apps +cache-clear --app-id app_xxx --environment dev --yes
 ## Agent 规则
 
 - **写操作先定环境**：`+cache-clear` / `+cache-delete` 不指定 `--environment` 时会落到自动选中的环境——**没有多环境的应用会直接作用到线上 `online`（生产）**。不确定应用有没有多环境时，写操作显式传 `--environment`；纯查看（`+cache-get`）影响小，可以省略。
-- **`+cache-clear` 会清掉整个环境的缓存**：执行前先跟用户确认环境无误、说明会清掉该环境全部缓存。已明确授权可直接带 `--yes`；遇到确认关卡（`confirmation_required`，exit 10）按 lark-shared 约定与用户确认后再补 `--yes` 重试，不要静默追加。
+- **`+cache-clear` 一律先确认再清**：不带确认就执行是本域最容易犯的错。**「用户让我清缓存」不构成授权**——授权指用户对「清空这个环境」有明确确认表述（判据表见 [+cache-clear](#cache-clear高危)）。没有它，就只出 `--dry-run` 预览或口头确认请求，然后停下等回话；**不要在首次调用就自带 `--yes`，也不要看到 exit 10 就补 `--yes` 重试**。拿到确认后再补 `--yes`，并始终显式带 `--environment`。
 - **排查缓存内容优先用 `+cache-get`**：想看结构化、易读的内容用 `--format pretty`；想拿原始内容做精确比对用默认 JSON。
 - **删 key 前先对齐 key**：用户只描述了业务含义、没给准确 key 时，先确认再删——删错影响也有限（应用会自动重建），但仍应避免误删。

package/skills/lark-base/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-base
-version: 1.2.19
-description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。"
+version: 1.2.21
+description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -18,16 +18,24 @@ metadata:
 
 ## 进入前必做：解析目标实体
 
-开始操作前先确定 `base_token` 和目标实体类型；上下文已提供 `<bitable>` / `<base_refer>` 标签及资源 ID 时直接使用。其余情况从两个入口解析：
+开始操作前先确定 `base_token` 和目标实体类型；上下文已提供 `<bitable>` / `<base_refer>` 标签及资源 ID 时直接使用。其余情况按意图选择入口：
 
 1. **URL 或分享链接：** `lark-cli base +url-resolve --url '<url>' --as user`。Base URL 根据返回的 `resource_type` / `block_type` 及 `table_id`、`view_id`、`record_id`、`dashboard_id`、`workflow_id`、`docx_token`、`share_token` 等坐标进入对应模块；BaseApp `/app/` URL 返回 `app_token`，并在链接携带时返回 `workspace_token` 和 `page_id`。实体类型以解析结果为准。
 2. **Base 标题或关键词：** `lark-cli base +title-resolve --title '<keyword>' --as user`。单一结果直接取得 `base_token`；多个候选结合标题、所有者和更新时间消歧，仍无法唯一确定时请用户选择。随后按下方 Base Block 资源模型定位目标实体。
-3. **BaseApp：** 优先使用真实 `/app/` URL；已有 `workspace_token` 时可用 `+workspace-entity-list --type baseapp` 定位。两者都没有时请用户补充应用链接或 Workspace，不按名称全局猜测 `app_token`。
+3. **已有 Base 候选列表：** 用户要列出已有 Base 候选，且需要按最近访问、owner、创建人、时间、类型等维度筛选/排序时，转 `lark-cli drive +search --doc-types bitable --as user`。按标题/关键词定位单个 Base 仍用 `+title-resolve`。常见候选列表命令：
+   - 最近访问：`lark-cli drive +search --doc-types bitable --sort open_time --opened-since 3m --page-size 20 --as user`
+   - 只列我拥有的：加 `--mine`；如果要列“我创建的”，用 `--created-by-me`。
+   - 从候选项拿到 URL 或 token 后，再用 `+url-resolve` 或 `+base-get` 进入 Base 业务命令。
+4. **BaseApp：** 优先使用真实 `/app/` URL；已有 `workspace_token` 时可用 `+workspace-entity-list --type baseapp` 定位。两者都没有时请用户补充应用链接或 Workspace，不按名称全局猜测 `app_token`。
 
 **读取 Base：** Base 信息用 `+base-get`，资源目录按下方 Base Block 资源模型读取。
 
 **写入 Base：** 创建新 Base 使用一次 `+base-create --name <base-name> --table-name <table-name> --fields '<field-array>'` 同时创建 Base、首表和 fields；`+base-copy` 复制整个 Base；Base 内资源统一按下方 Block 生命周期管理。
 
+## Base 模板中心
+
+模板中心是公开的 Base 模板库，不是用户云空间里的已有 Base。用户想用现成模板创建新 Base，且没有指向已有对象的锚点（没有 Base URL、没有“我的/最近访问的表”、没有具体已存在的 Base 名）时，可读取 [lark-base-template-center.md](references/lark-base-template-center.md) 查找模板中心模板；`+template-categories` 列出公开模板分类，`+template-list` 按分类列出公开模板，`+template-search` 按业务关键词搜索公开模板。
+
 ## Base Block 资源模型
 
 ```text
@@ -98,12 +106,21 @@ Form 依附于 Table，以 Field 作为题目，每次有效提交会创建一
 
 1. **读取 Table 中的表单配置：** 使用 `+form-list` / `+form-get` 读取表单，使用 `+form-questions-list` 读取题目配置；这些命令使用表单所属的 `base_token + table_id`。
 2. **创建或修改 Table 中的表单配置：** 使用 `+form-create` / `+form-update` / `+form-delete` 管理表单；题目由 Table Field 承载，question ID 对应 `field_id`，创建和更新分别读取 [questions create](references/lark-base-form-questions-create.md) / [questions update](references/lark-base-form-questions-update.md)，删除使用 `+form-questions-delete`。
-3. **填写分享表单并提交：** 对表单分享链接使用 `+url-resolve` 取得 `share_token`，按 [Form detail](references/lark-base-form-detail.md) 执行 `+form-detail` 读取真实题目、必填项和显示条件，再按 [Form submit](references/lark-base-form-submit.md) 构造字段与附件并执行 `+form-submit`。
+3. **管理表单分享：** 使用 `+form-share-get` / `+form-share-update` 管理启停、访问范围和匿名/登录要求；更新前先读取现状，每次只修改一个字段，布尔值显式传 `true` 或 `false`。
+4. **填写分享表单并提交：** 对表单分享链接使用 `+url-resolve` 取得 `share_token`，按 [Form detail](references/lark-base-form-detail.md) 执行 `+form-detail` 读取真实题目、必填项和显示条件，再按 [Form submit](references/lark-base-form-submit.md) 构造字段与附件并执行 `+form-submit`。
+
+表单题目和字段的关系：
+
+- `+form-questions-create` 支持两种形态：新建字段题目需要 `title` + `type`；已有字段题目需要 `use_existing_field:true` + `field_id`。已有字段题目只是把该字段加入表单，不创建新字段，也不改变已有记录数据；不要给该形态携带 `type`、`style`、`options` 等字段定义属性。
+- 创建问题前先 `+form-questions-list`。若目标标题已经存在，除非用户明确要求同名独立问题，否则优先用 `+form-questions-update` 修改题目配置，不要先创建同名问题再删除旧问题。
+- `+form-questions-delete` 是高风险写操作。默认会删除承载问题的底层 Field 及该字段所有记录数据；只想把题目移出表单并保留字段/数据时必须传 `--keep-field`。保留字段后可用 `+form-questions-create --questions '[{"use_existing_field":true,"field_id":"<field_id>"}]'` 加回表单。
 
 ## Dashboard Block
 
 Dashboard Block 是 Base Block 树中的仪表盘容器，负责承载页面主题、布局和内部组件集合，本身不表示某一项图表数据。使用 `+dashboard-list` 定位容器，`+dashboard-get` 读取容器信息，`+dashboard-update` 修改主题，`+dashboard-arrange` 统一编排内部组件布局。
 
+**管理 Dashboard 分享：** 使用 `+dashboard-share-get` / `+dashboard-share-update` 管理启停、访问范围和返回源 Base 入口；更新前先读取现状，每次只修改一个字段，显式 `false` 会被保留。
+
 容器内部的图表、指标卡和文本等组件在 Dashboard API 中也称为 Block，但不属于 Base Block 树。内部 Block 分为三条操作路径：
 
 1. **读取配置：** `+dashboard-block-list` / `+dashboard-block-get` 读取组件类型、布局和 `data_config`；文本组件的正文也属于配置。
@@ -160,5 +177,5 @@ Folder Block 只承担 Base 目录分组和层级组织。用 `+base-block-list
 ## 不在本 Skill 范围
 
 - 认证、初始化、scope、身份切换和授权恢复 → `lark-shared`
-- Excel、CSV、`.base` 等本地文件与 Base 之间的导入/导出 → `lark-drive`
+- Excel、CSV、`.base` 等本地文件与 Base 之间的导入/导出转 `lark-drive`；在线复制走 `+base-copy`
 - Base 内嵌 Docx 的正文编辑 → `lark-doc`；电子表格内容操作 → `lark-sheets`

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

@@ -99,6 +99,23 @@ lark-cli base +app-create \
 - `--theme-style` 可选，支持 `default|cloudBlue|fresh|softLight|future|technology`。
 - 记录输出中的 `app_token` 和 `workspace_token`。
 
+### 新建应用的默认 Page 复用
+
+`+app-create` 会同时生成一个系统默认 Page，但创建响应不返回它的 `page_id`。用户未明确要求其他页面结构时，创建 App 后先读取应用取得该 Page，将其重命名并直接用作用户所需的第一个页面；不要用 `+app-page-create` 另建第一个页面：
+
+```bash
+lark-cli base +app-get --app-token <app_token> --as user
+lark-cli base +app-page-update \
+  --app-token <app_token> \
+  --page-id <default_page_id> \
+  --name "<page_name>" \
+  --as user
+```
+
+在上述默认流程中，随后在这个 Page 上**逐个串行**执行 `+app-block-create`，同一 Page 的多个组件不得并发创建。只有用户确实需要额外页面时，才在复用默认 Page 之后调用 `+app-page-create`。用户明确要求保留默认 Page、另建独立页面或采用其他页面结构时，按用户要求处理。
+
+若 `+app-get` 暂时没有返回默认 Page，重新执行 `+app-get` 或 `+app-page-list` 获取它，不要创建替代 Page。若创建组件返回布局重叠，先停止同页的其他并发写入，用 `+app-block-list` 确认已成功组件，再留在原 Page 上串行重试失败步骤；不要通过新建 Page、删除默认 Page 或整页重建来规避冲突。
+
 ### 创建应用的自然语言编排
 
 先根据用户是否指定 Workspace 和现有 Base 选择流程，再调用原子 shortcut：
@@ -171,6 +188,7 @@ lark-cli base +app-page-update --app-token <app_token> --page-id <page_id> --nam
 lark-cli base +app-page-delete --app-token <app_token> --page-id <page_id> --yes
 ```
 
+- 对新建 App，用户未明确要求其他页面结构时，必须按[新建应用的默认 Page 复用](#新建应用的默认-page-复用)将系统默认 Page 用作用户所需的第一个页面；`+app-page-create` 只用于用户要求的额外页面。
 - 同一 App 内 Page 名称必须唯一。创建或更新名称前，CLI 会读取页面列表；更新时排除当前 Page。
 - 同一 Page 内组件名称必须唯一。`+app-block-create` 会分页读取该 Page 的全部组件并在创建前检查重名。
 - 本期没有 Page arrange，也没有 Block delete；Block 的 `type/sub_type` 创建后不可修改。详见[本期不支持的能力](#本期不支持的能力)。

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-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-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-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` 必须来自同一张表。
-- 这是单条记录历史，不是表级审计；需要查多条记录时串行调用。
+- 这是单条记录历史，不是表级审计；用户明确要求查询多条记录时，先确认目标范围，再按记录串行调用。