@amaster.ai/pi-lark 0.1.5 → 0.1.6

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

@@ -4,7 +4,7 @@
 
 ## 何时用
 
-用户要看应用里有哪些表 / 某张表的结构、把单库应用拆成 dev/online 多环境、把数据导进导出表、查谁在什么时候改了表结构或表数据、开关行级审计、把开发环境的库结构发布到线上、把库恢复到过去某个时间点、或看数据库用量时。逐条执行 SQL 走 [`+db-execute`](lark-apps-db-execute.md)；文件存储（上传/下载文件）走 [`lark-apps-file.md`](lark-apps-file.md)。
+用户要看应用里有哪些表 / 某张表的结构、把单库应用拆成 dev/online 多环境、把数据导进导出表、查谁在什么时候改了表结构或表数据、开关行级审计、把开发环境的库结构发布到线上、把库恢复到过去某个时间点、或看数据库用量时。逐条执行 SQL 走 [`+db-execute`](lark-apps-db-execute.md)；文件存储（上传/下载文件）走 [`lark-apps-file.md`](lark-apps-file.md)。**建表 / 改表 / 写 SQL 的平台内容规范**（审计列、RLS、`user_profile`、禁用 SQL、PG 陷阱）见 [`lark-apps-db-execute.md`](lark-apps-db-execute.md) 的「平台 SQL 规范」。
 
 ## 命令一览
 
@@ -28,7 +28,7 @@
 
 ## 约定（先读）
 
-- **环境 `--environment dev|online`（所有 db 命令统一默认 `dev`）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分，写操作建议先在 `dev` 验。**注意：只有开启了多环境（`+db-env-create`）的应用才有 `dev` 分支；未开启多环境的应用其数据库在 `online`——对这类应用必须显式 `--environment online`，否则默认的 `dev` 分支不存在、会报错**。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义、`+db-recovery-*` 作用于当前库，二者**没有** `--environment`。
+- **环境 `--environment dev|online`（可省略）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分。省略 `--environment` 时 CLI 不带该参数、由服务端按应用形态自动选分支——多环境应用走 `dev`、未开多环境的走 `online`；要固定环境就显式传。唯一会报错的组合：对未开多环境的应用显式传 `--environment dev`（无 `dev` 分支）。写操作建议先在 `dev` 验（仅多环境应用有 `dev`）。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义，**没有** `--environment`。
 - **本地文件 / `--output` 用工作目录内相对路径**：导入 `--file ./orders.csv`、导出 `--output ./out.csv`；绝对路径、或经 `..`/符号链接越出工作目录的 `--output` 会被拒（validation / exit 2）。路径在别处先 `cd` 过去或改成相对路径。
 - **高危操作必须带 `--yes`**：`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply` 缺省会被确认关卡拦下；动手前先用对应的预览命令或 `--dry-run` 看清影响。
 - **时间参数按口语自然传**（`--since`/`--until`/`--target`），格式见末尾。
@@ -154,7 +154,7 @@ lark-cli apps +db-quota-get --app-id app_xxx --environment dev
 
 ## Agent 规则
 
-- 用户说「本地 / 开发库 / 调试库」优先 `--environment dev`，线上排查用 `--environment online`；数据面写操作（导入 / 审计开关）默认先在 `dev` 验再动 `online`。
+- 用户说「本地 / 开发库 / 调试库」优先 `--environment dev`，线上排查用 `--environment online`；数据面写操作（导入 / 审计开关）建议先在 `dev` 验再动 `online`。**注意省略 `--environment` 时写操作会落到服务端选中的分支——单环境应用即 `online`（生产）**：不确定应用是否多环境时，写操作显式传 `--environment`；显式 `dev` 在单环境应用上会安全报错（无 dev 分支），正好当「是否多环境」的探针用。
 - 看表用 `+db-table-list`，看结构用 `+db-table-get`（要建表语句加 `--format pretty`）；`+db-env-create` 仅用于存量单库拆多环境，新建的 full_stack 应用一般不需要。
 - 四个高危命令（`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply`）动手前先看清影响再带 `--yes`：发布 / 恢复先跑对应预览 `+db-env-diff` / `+db-recovery-diff`，导入无预览命令、可先 `--dry-run` 看请求或先在 `--environment dev` 验；不要静默追加 `--yes`，遇 confirmation_required（exit 10）按 lark-shared 协议向用户确认不可逆风险后再补 `--yes` 重试。
 - 导入 / 导出的本地路径用工作目录内相对路径；超大表导出会被行数 / 体积上限拒，改用 `+db-execute` 分批。

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

@@ -0,0 +1,43 @@
+# apps +get
+
+按 app_id 查询单个应用详情。运行时命令事实以 `lark-cli apps +get --help` 为准。
+
+## 何时用
+
+需要查看一个应用的类型、名称、描述、发布状态等详情时使用。如果只是按应用名模糊搜索定位 app_id，用 `+list --keyword`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 返回应用的完整信息：`app_id`、`app_type`、`name`、`description`、`icon_url`、`created_at`、`updated_at`、`is_published`。
+
+## 示例
+
+```bash
+lark-cli apps +get --app-id app_xxx
+lark-cli apps +get --app-id app_xxx --dry-run
+lark-cli apps +get --app-id app_xxx -q '.data.app.app_type'
+```
+
+## 输出契约
+
+- 成功读取 `data.app` 对象，包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `app_id` | string | 应用唯一标识 |
+| `app_type` | string | 应用类型（如 HTML、FULL_STACK、MODERN_HTML） |
+| `name` | string | 应用显示名称 |
+| `description` | string | 应用功能说明 |
+| `icon_url` | string | 应用图标 URL |
+| `created_at` | string | 创建时间（ISO 8601 UTC） |
+| `updated_at` | string | 最后更新时间（ISO 8601 UTC） |
+| `is_published` | boolean | 是否已发布 |
+
+- pretty 输出展示核心字段：`app_id`、`app_type`、`name`、`is_published`、`updated_at`。
+- `is_published=true` 只代表应用历史上有发布版本，不代表最新代码已部署。
+
+## Agent 规则
+
+- 用户已有 `app_id` 想查看详情时用 `+get`；只有应用名时用 `+list --keyword`。
+- 不要把 `cli_` 开头的飞书应用 ID 传给 `+get`，只接受 `app_` 开头的应用 ID。

package/skills/lark-apps/references/lark-apps-html-publish.md

@@ -23,8 +23,13 @@ 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'`。
+根据应用类型，输出字段不同：
+
+- **静态 HTML 应用**：`data.url` 是本轮发布后的访问链接，一步完成发布。
+- **其他 HTML 应用**：`data.release_id` 是发布标识，命令内部已完成产物上传和发布创建。用 `+release-get --app-id <app_id> --release-id <release_id>` 轮询发布状态直到 `finished`。
+
+判断走哪条路径：有 `url` 字段说明已直接发布完成；有 `release_id` 字段说明需要用 `+release-get` 轮询。
+
 - 业务失败如构建失败、应用不存在通常带 `error.hint`；优先转述 hint。网络/服务端失败则建议稍后重试。
 
 ## 链接边界

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

@@ -10,7 +10,6 @@
 
 - 必填：`--app-id`。
 - 可选：`--dir`，clone 目标目录；省略时默认 `./<app-id>`。
-- 可选：`--template`，空仓库脚手架模板；省略时当前回退 `nestjs-react-fullstack`。
 - 固定 checkout 分支：`sprint/default`。
 - `+init` 会初始化 Git 凭证、clone 仓库、切到工作分支并生成/同步本地项目。
 
@@ -18,7 +17,7 @@
 
 ```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 /absolute/path/my-app
 lark-cli apps +init --app-id app_xxx --dir ./my-app --dry-run
 ```
 

package/skills/lark-apps/references/lark-apps-openapi-key.md

@@ -76,4 +76,4 @@ CLI 提供三种互斥的 scope 表达方式：
 ## 不在本 skill 范围
 
 - OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。
-- 身份选择、权限不足处理（`permission_violations`→`console_url`）、exit-10 审批、通用"禁输出密钥"红线、高风险操作通用框架：见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不在此重复。
+- 身份选择、权限不足处理（`missing_scopes`→`console_url`）、exit-10 审批、通用"禁输出密钥"红线、高风险操作通用框架：见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不在此重复。

package/skills/lark-apps/references/lark-apps-release-create.md

@@ -21,8 +21,10 @@ lark-cli apps +release-create --app-id app_xxx --branch sprint/default --dry-run
 
 ## 输出契约
 
-- 成功读取 `data.release_id` 和 `data.status`；`release_id` 是后续 `+release-get` 的入参。
+- 成功读取 `data.release_id`、`data.status` 和 `data.sync`；`release_id` 是后续 `+release-get` 的入参。
+- `sync=true` 表示同步部署（服务端等待部署完成后才返回），`sync=false` 或缺失表示异步部署。
 - `status=publishing` 表示发布仍在进行；继续用 `+release-get` 轮询，轮询间隔应该为 20s。应用发布平均耗时大约 2min，整体超时时间大约 5min。
+- `status=finished` 表示部署已完成（同步部署时可能直接返回此状态）。
 - `+release-create` 返回 release 只代表发布已发起。只有 `+release-get` 对同一个 `release_id` 返回 `finished` 后，才能说本轮最新版本已部署。
 
 ## Agent 规则

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

@@ -0,0 +1,133 @@
+# apps role 域命令（应用角色）
+
+管理妙搭应用内的平台角色、角色成员，以及查询某个用户命中的角色。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；身份、授权和高风险确认遵循本域 [`SKILL.md`](../SKILL.md)。
+
+## 何时用
+
+用户要列出、查看、创建、更新或删除某个妙搭应用内的平台角色，管理角色的用户、部门或群成员，或查询某个用户在应用中命中的角色时使用。多维表格 / Base 的角色与权限走 `lark-base`；设置谁能访问应用走 `+access-scope-*`，不要路由到本命令域。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+role-list` | 分页列出角色，或按名称筛选角色 | `--app-id`、`--name`、`--page-size`/`--page-token` |
+| `+role-get` | 根据真实 `role_id` 读取角色详情 | `--app-id`、`--role-id` |
+| `+role-match-list` | 查询指定用户命中的角色 | `--app-id`、`--user-id` |
+| `+role-create` | 创建角色 | `--app-id`、`--name`、`--description`、`--role-id` |
+| `+role-update` | 更新角色名称或描述 | `--app-id`、`--role-id`、`--name`/`--description` |
+| `+role-delete` | 永久删除角色 | `--app-id`、`--role-id`、`--yes` |
+| `+role-member-list` | 查询角色的用户、部门和群成员 | `--app-id`、`--role-id`、`--member-type` |
+| `+role-member-add` | 向角色添加用户、部门或群成员 | `--app-id`、`--role-id`、`--users`/`--departments`/`--chats` |
+| `+role-member-remove` | 定向移除或清空角色成员 | `--app-id`、`--role-id`、成员参数或 `--all`、`--yes` |
+
+## 约定（先读）
+
+- `app_...` 标识的是妙搭应用，其角色和成员只使用 `apps +role-*` / `apps +role-member-*`；不要改走 Base 角色命令或裸 bitable API。
+- 角色名称不是 `role_id`。只有名称时优先用 `+role-list --name` 精确解析；若已取得完整分页列表，也可从中证明精确名称唯一命中。0 条如实报告，多条让用户消歧，唯一命中后才使用返回的真实 ID。
+- `+role-list` 返回 `has_more=true` 时，用本页 `page_token` 继续查询，直到 `has_more=false`；不要根据 `total` 补造条目。
+- `+role-list`、`+role-get`、`+role-match-list` 的角色数据分别位于 `data.items`、`data.role`、`data.roles`，不要混用。
+- 同一角色的写入及依赖该写入结果的操作必须串行。不同角色的独立操作只有在每次写入可单独追溯、失败不影响其它目标且分别验收时才可并行；否则保持串行。互不依赖的名称解析或只读查询可并行。
+
+## 各命令
+
+### 查询角色
+
+```bash
+lark-cli apps +role-list --app-id <app_id> --page-size 100
+lark-cli apps +role-list --app-id <app_id> --name '<exact_name>'
+lark-cli apps +role-get --app-id <app_id> --role-id <role_id>
+lark-cli apps +role-match-list --app-id <app_id> --user-id <ou_x>
+```
+
+整理角色列表时保留 `role_id`、`name` 和 `description`。不要猜测未知 `role_id`，也不要从同名候选中静默选择。
+`items=[]` 时直接报告当前没有角色；不要为表格补造“无”或 `N/A` 占位行。
+`+role-match-list --user-id` 只接受 `ou_...`；用户给的是姓名、邮箱或手机号时，先解析唯一 open ID，再查询命中角色。
+
+### 创建与更新
+
+```bash
+lark-cli apps +role-create --app-id <app_id> --name '<name>' \
+  --description '<description>'
+
+# 只修改名称
+lark-cli apps +role-update --app-id <app_id> --role-id <role_id> \
+  --name '<new_name>' --as user --format json
+
+# 只修改描述
+lark-cli apps +role-update --app-id <app_id> --role-id <role_id> \
+  --description '<new_description>' --as user --format json
+```
+
+- `--description` 和创建时的 `--role-id` 可选；仅在确实需要稳定 ID 时传 `--role-id`，创建后不能修改。
+- 更新时只传用户明确要求变更的字段。
+- 成功响应中的角色位于 `data.role`。只有用户要求独立验证，或结果将用于后续高风险操作时，才额外执行 `+role-get`。
+
+### 删除角色
+
+普通“删除某角色”请求只说明目标，**不等于不可逆确认**。如果用户尚未明确确认删除后果，本轮只能定位角色、读取完整成员并说明影响，最后请求确认；不得在同一轮自动追加 `--yes`。用户已明确确认不可逆删除时才继续。
+
+只有名称时仍按上述规则唯一解析，优先使用 `+role-list --name`。目标写前已不存在时立即停止，如实说明本次是 no-op、没有执行删除，不能把“当前不存在”表述为“删除成功”。
+
+删除前读取准确角色和完整成员范围，向用户说明 app、role、`users` / `departments` / `chats` 影响；得到不可逆删除确认后才使用 `--yes`：
+
+```bash
+lark-cli apps +role-get --app-id <app_id> --role-id <role_id>
+lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id>
+lark-cli apps +role-delete --app-id <app_id> --role-id <role_id> --yes
+```
+
+成功响应包含匹配的 `data.role_id` 和 `data.deleted=true`。只有用户明确要求独立验证删除结果时，才再用 `+role-list --name` 检查目标 ID 已不存在。
+
+### 成员 ID 解析
+
+成员 flags 只接受 open ID：用户 `ou_...`、部门 `od-...`、群 `oc_...`。用户已提供对应类型的合法 open ID 时直接使用；只有名称或邮箱时才解析。
+对象类型以用户语义为准，不能互换解析器：用户走通讯录用户搜索，部门走部门搜索，群走群搜索。
+
+```bash
+# 用户：每个姓名或邮箱单独查询。
+lark-cli contact +search-user --query '<姓名或邮箱>' \
+  --exclude-external-users --page-size 30
+
+# 部门：拉完分页，只接受唯一的 open_department_id。
+lark-cli api POST /open-apis/contact/v3/departments/search \
+  --params '{"user_id_type":"open_id","department_id_type":"open_department_id","page_size":50}' \
+  --data '{"query":"<部门名称>"}'
+
+# 群：拉完分页，只接受名称精确匹配的唯一 chat_id。
+lark-cli im +chat-search --query '<群名称>' --page-size 50
+```
+
+- 只接受与输入姓名、邮箱或群名精确匹配的唯一结果；部门搜索只接受完整 query 的唯一 `od-...`。0 条、多条或分页未完成时停止写入并让用户补充或消歧。
+- 多个对象逐个解析。全部解析成功且总数不超过 100 后，按类型放入一次成员写入；任一对象失败时不要部分写入，也不要自动拆批。
+
+### 成员操作
+
+```bash
+# 省略 --member-type，返回完整 users / departments / chats。
+lark-cli apps +role-member-list --app-id <app_id> --role-id <role_id>
+
+lark-cli apps +role-member-add --app-id <app_id> --role-id <role_id> \
+  --users ou_x,ou_y --departments od-x --chats oc_x
+
+lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> \
+  --users ou_x --yes
+
+# 清空成员，不删除角色。
+lark-cli apps +role-member-remove --app-id <app_id> --role-id <role_id> \
+  --all --yes
+```
+
+- `+role-member-list` 不分页；`--member-type` 只返回选中类型的字段，未返回的成员字段表示“未查询”而不是空。影响确认或完整比较时必须省略它。
+- 汇总 `--member-type` 结果时明确这是过滤投影，不得据此断言角色没有其它类型成员。
+- 用户要求 CLI 原生 table 时，直接执行 `+role-member-list --format table`；可原样转发或做事实摘要，不要先取 JSON 再手工重建一张替代表格。
+- 写入和依赖其结果的回读不得放进同一个并发批次；必须等待写入完整返回成功后，再单独发起回读。误并发时只能以写入完成后的新回读作为结果证据。
+- 添加前仅在用户要求独立证明或确认其他成员类型未变化时读取完整基线，并在写后完整回读；否则成功响应即可作为结果。
+- 定向移除前确认准确成员及影响。若需要证明结果，写后完整回读；不要把过滤结果当作完整成员集合。
+- `--all` 前读取完整成员范围并确认；成功后执行一次无过滤 `+role-member-list`，确认三个成员数组均为空。
+
+## 权限
+
+| 操作 | 所需 scope |
+|---|---|
+| list / get / member-list / match-list | `spark:app:read` |
+| create / update / delete / member-add / member-remove | `spark:app:write` |

package/skills/lark-base/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-base
-version: 1.2.2
+version: 1.2.3
 description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。"
 metadata:
   requires:
@@ -85,7 +85,7 @@ metadata:
 ## 身份与权限降级
 
 - 默认显式使用 `--as user` 操作用户资源；只有用户明确要求应用身份时，才直接用 `--as bot`。
-- user 身份报 scope/授权不足，或错误中包含 `permission_violations` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
+- user 身份报 scope/授权不足，或错误中包含 `missing_scopes` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
 - user 身份报资源级无访问且无授权恢复提示时，才可用 `--as bot` 重试一次；bot 仍失败就停止重试并按权限错误处理。
 - `91403` 或明确不可访问错误不要循环换身份重试。
 - `+base-create` / `+base-copy` 若用 bot 身份执行，关注返回中的 `permission_grant`，并把用户是否可打开新 Base 告知用户。
@@ -104,6 +104,8 @@ metadata:
 
 ## 写入前置规则
 
+- 更新前先看命令说明：需要完整提交时，先读取并补齐当前配置，只改用户指定的内容，再按命令要求提交；支持局部修改时，按命令说明和 reference 提交最小合法 payload。
+- 优先用写入返回确认结果；返回信息不足或任务明确要求核验时，再读回。
 - 写记录前先读字段结构；只写存储字段。系统字段、附件字段、`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)。
@@ -122,7 +124,7 @@ metadata:
 
 ## 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`。
+- 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` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
 
@@ -134,6 +136,8 @@ metadata:
 | `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 |
+| `Invalid discriminator value`（字段写入缺 `type`） | 按完整提交规则读取当前字段，只改目标内容后提交；不要只补 `type` 重试 |
+| filter 报 `value of type array` / `Only string values` | 用 record/view 的 tuple `--filter-json`（非 `+data-query` 对象型），value 按字段 type 选标量或数组；见 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md) |
 | 日期 / 人员 / 超链接字段报格式错误 | 日期用 `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` | 移除只读字段，只写存储字段 |

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

@@ -90,6 +90,10 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 
 `sort.order`：`asc`（升序）/ `desc`（降序）
 
+只要写 `sort` 对象，就需要明确排序方向。CLI 会把 `sort.type` 为 `group` 或 `view` 且缺少 `order` 的情况规范化为 `order:"asc"`；`sort.type:"value"` 必须显式写 `order:"asc"` 或 `order:"desc"`，因为指标值排序方向会改变业务含义。
+
+如果表中行序就是业务顺序，首次创建 block 时就一次性设置 `sort:{"type":"view","order":"asc"}` 保留行序，避免创建后再二次更新排序条件。
+
 示例 — 柱状图按销售额降序：
 
 ```json
@@ -169,9 +173,10 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 - 长度/结构
   - `group_by` 最多 2 个；每项 `field_name` 必填
   - `group_by[].sort.type` 取值 `group|value|view`；`order` 取值 `asc|desc`
-- 规范化（CLI 自动处理）
+- 规范化（CLI 自动处理；`--no-validate` 时不生效，`data_config` 原样透传给后端）
   - `series[].rollup` 自动转成大写（如 `sum` → `SUM`）
   - `group_by[].sort.type/order` 自动转成小写
+  - `group_by[].sort.type` 为 `group` 或 `view` 且缺少 `order` 时，自动补 `order:"asc"`；`value` 排序不会自动补方向
 - 本地校验（可通过 `--no-validate` 跳过）
   - `+dashboard-block-create` 默认对 `data_config` 做轻量校验；失败会聚合错误并给出修复建议
   - `+dashboard-block-update` 不做强类型校验，由后端验证具体字段
@@ -264,14 +269,35 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 
 漏斗图（流程转化）：
 
+先判断用户要看的数值语义：
+
+- **当前数量**：统计每个当前状态/阶段下有多少记录，例如“各环节当前数量”“当前阶段分布”。源表有状态/阶段字段时，直接用 `count_all:true` + `group_by`。
+- **累计数量**：统计到达该阶段及其后续阶段（后缀和）的累计数量，例如“流程转化”“从 A 到 B 各环节转化”。此口径假设流程单向、无跳阶/回退、记录不删除；不满足时须用状态变更历史，不能对当前快照累加。如果表中已有累计数量字段或阶段汇总表，直接用该字段画漏斗图；否则先计算累计数量，创建并写入 helper 汇总表后再画图。
+
+当前数量：
+
 ```json
 {
   "table_name": "表名",
-  "series": [{ "field_name": "数值字段", "rollup": "SUM" }],
+  "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":"view","order":"asc"} }]
+}
+```
+
+如果只有当前状态数据但用户要看流程转化，需要先按业务阶段顺序计算每个阶段的累计数量，再创建 helper 汇总表（如：阶段、累计数量），用 `+record-batch-create` 一次写入后，按“累计数量”模板创建漏斗图。helper 表行序就是业务顺序时，首次创建 block 时一次性设置好 `group_by.sort`。
+
+> ⚠️ 注意:helper 汇总表仅用于源表无法直接聚合出目标形态的场景（如上面的累计数量漏斗图）。只要能在源表上直接用 `group_by` + `rollup`（含 `AVERAGE`）算出，就不需要新建 helper 表。
+
 词云（文本频率）：
 
 ```json

package/skills/lark-base/references/lark-base-cell-value.md

@@ -16,15 +16,20 @@
 
 ## 2. 各类型 CellValue
 
-### 2.1 text / phone / url
+### 2.1 text
 
-用字符串。URL 字段也传 URL 字符串；普通文本里可以保留 Markdown 风格链接文本，平台会按字段类型处理。
+text 字段的 `style.type` 影响单元格检查逻辑：
+`type=plain` 传 Markdown 格式的字符串。
+`type=url` 传一个带 title 的 Markdown 格式链接，或单独传一个链接。
+`type=phone` 传合法电话号码。
+`type=email` 传合法邮箱字符串。
 
 ```json
 {
-    "标题": "Hello",
+    "标题": "Hello, [lark-cli](https://github.com/larksuite/cli)",
+    "官网": "[官网](https://example.com)",
     "联系电话": "1380000000000",
-    "官网": "https://example.com"
+    "邮箱": "owner@example.com"
 }
 ```
 

package/skills/lark-base/references/lark-base-dashboard-block-get-data.md

@@ -98,21 +98,21 @@ lark-cli base +dashboard-block-get \
 
 ## 返回结构总览
 
-服务端响应外层仍然是标准 OpenAPI 包装：
+CLI 成功输出使用标准 `{ok, identity, data}` 信封：
 
 ```json
 {
-  "code": 0,
-  "msg": "success",
+  "ok": true,
+  "identity": "user",
   "data": {
-    "dimensions": [...],
-    "measures": [...],
-    "main_data": [...]
+    "dimensions": [],
+    "measures": [],
+    "main_data": []
   }
 }
 ```
 
-其中 `data` 就是 CLI 图表协议本体。不同图表类型的 `data` 结构略有不同：
+其中 `identity` 是本次调用实际使用的身份，`data` 是 CLI 图表协议本体。不同图表类型的 `data` 结构略有不同：
 
 | 图表类型 | 一定有 | 可能有 |
 |----------|--------|--------|

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

@@ -19,12 +19,19 @@ Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**
 | 修改组件 | `+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` | 只在用户明确要求重排时执行；无法指定精确位置 |
+| 智能重排组件布局 | `+dashboard-arrange` | 用户明确要求重排，或本次会话新建仪表盘的收尾整理；无法指定精确位置 |
 
 ## 典型场景工作流
 
 ### 场景 1：从 0 到 1 创建仪表盘
 
+从 0 到 1 创建仪表盘时，按用户需求规划组件的类型和数量，并注意以下要点：
+
+- 聚合方式：创建指标卡或分布图时优先把聚合写进 `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` 仅两种情况使用：① 用户明确要求美化/重排；② 本次会话中从零新建的仪表盘，建完组件后做一次性布局整理。不是创建成功的必要步骤。
+
 示例：搭建一个销售数据分析仪表盘
 
 ```bash
@@ -63,6 +70,7 @@ lark-cli base +dashboard-block-create \
 
 # 第 5 步：组件创建完成后，使用 arrange 命令智能重排布局（可选但推荐）
 # 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
+# 若用户没有要求美化/重排，可先跳过此步骤；这不影响仪表盘和组件是否已创建成功
 lark-cli base +dashboard-arrange \
   --base-token xxx \
   --dashboard-id blk_xxx
@@ -125,11 +133,12 @@ lark-cli base +dashboard-block-update \
   --dashboard-id blk_xxx \
   --block-id chtxxxxxxxx \
   --data-config '{...}'
+
 ```
 
 ### 场景 4：重排仪表盘布局
 
-当用户明确要求对已有仪表盘进行布局重排或美化时使用。
+当用户明确要求对已有仪表盘进行布局重排或美化时使用（对本次会话从零新建的仪表盘，可在建完组件后直接做一次性整理，见场景 1）。
 
 > [!CAUTION]
 > - 排列结果是**服务端智能推荐**，不一定完全符合用户预期

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

@@ -347,28 +347,30 @@ value 使用预定义关键字机制，第一个元素为字符串常量名称
 |------|------|------|------|
 | `format` | string | 是 | 固定为 `"flat"`，表示返回扁平化的对象数组 |
 
-## API 出参详情
+## CLI 出参详情
+
+CLI 输出标准信封 `{ok, identity, data}`（失败时为 `{ok:false, identity, error}`）。
 
 **成功时：**
 
 ```json
-{"code": 0, "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}, "msg": ""}
+{"ok": true, "identity": "user", "data": {"main_data": [{"dim_city": {"value": "北京"}, "total_amount": {"value": 12345.00}}, ...]}}
 ```
 
 **失败时：**
 
 ```json
-{"code": 800004006, "data": {"error": {"code": 800004006, ...}}, "msg": "DSL validation failed"}
+{"ok": false, "identity": "user", "error": {"type": "api", "subtype": "unknown", "code": 800004006, "message": "...does not exist in table schema", "hint": "...", "log_id": "..."}}
 ```
 
 **Response 字段：**
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `code` | int | 状态码，0 为成功 |
-| `msg` | string | 错误信息 |
-| `data.main_data` | []object | 查询结果数组，每个元素为一行数据 |
-| `data.error` | object | 失败时的错误详情 |
+| `ok` | bool | 是否成功 |
+| `identity` | string | 执行身份：`user` / `bot` |
+| `data.main_data` | []object | 查询结果数组，每个元素为一行数据（成功时） |
+| `error` | object | 失败时的 typed 错误，含 `type` / `subtype` / `code` / `message` / `hint` / `log_id` |
 
 每行数据的字段值封装在 CellValue 中：
 

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

@@ -23,12 +23,12 @@ lark-cli base +field-create \
 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"}]}'
+  --json '{"name":"状态","type":"select","multiple":false,"default_value":["Todo"],"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)"}'
+  --json '{"name":"负责人","type":"user","multiple":false,"default_value":[{"$slot":"current_user"}],"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}'
 ```
 
 ## 参数
@@ -51,6 +51,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
 - `--json` 必须是 **JSON 对象**，顶层直接传字段定义，不要再套一层。
 - 顶层最少包含：`name`、`type`。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。
+- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；`datetime` / `user` 的动态填充用 `$slot`。完整规则见 [lark-base-field-json.md](lark-base-field-json.md)。
 - `type` 不同，必填子字段不同：
   - `select`：`multiple` 控制是否多选，`options` 定义静态选项，`dynamic_options_source` 定义动态选项来源。静态与动态选项配置二选一，不能同时传。
   - `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。
@@ -64,6 +65,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
   "name": "状态",
   "type": "select",
   "multiple": false,
+  "default_value": ["Todo"],
   "options": [
     { "name": "Todo", "hue": "Blue", "lightness": "Lighter" },
     { "name": "Done", "hue": "Green", "lightness": "Light" }