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

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.2-beta.60",
+  "version": "0.1.2-beta.62",
   "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.2-beta.60"
+    "@amaster.ai/pi-shared": "0.1.2-beta.62"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-approval/SKILL.md

@@ -34,7 +34,7 @@ metadata:
 | 搜可发起定义 | `approvals search` | [`lark-approval-approvals-search.md`](references/lark-approval-approvals-search.md) |
 | 看审批定义详情/提单前确认表单与流程 | `approvals get` | [`lark-approval-approvals-get.md`](references/lark-approval-approvals-get.md)   |
 | 发起原生审批实例/提交请假审批/提交报销审批/创建审批实例 | `instances create` | [`lark-approval-initiate.md`](references/lark-approval-initiate.md)             |
-| 查待办/已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读） | [`lark-approval-tasks-query.md`](references/lark-approval-tasks-query.md)       |
+| 查/搜待办、已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读） | [`lark-approval-tasks-query.md`](references/lark-approval-tasks-query.md)       |
 | 看表单/进度/当前节点 | `instances get` | [`lark-approval-instances-get.md`](references/lark-approval-instances-get.md)   |
 | 同意审批 | `tasks approve` | [`lark-approval-tasks-approve.md`](references/lark-approval-tasks-approve.md)   |
 | 拒绝审批 | `tasks reject` | [`lark-approval-tasks-reject.md`](references/lark-approval-tasks-reject.md)     |
@@ -44,7 +44,7 @@ metadata:
 | 催办审批 | `tasks remind` | [`lark-approval-tasks-remind.md`](references/lark-approval-tasks-remind.md)     |
 | 撤回已发起审批 | `instances cancel` | [`lark-approval-instances-cancel.md`](references/lark-approval-instances-cancel.md) |
 | 给审批实例追加抄送 | `instances cc` | [`lark-approval-instances-cc.md`](references/lark-approval-instances-cc.md)     |
-| 按定义查已发起审批 | `instances initiated` | [`lark-approval-instances-initiated.md`](references/lark-approval-instances-initiated.md) |
+| 按定义/关键词查已发起审批 | `instances initiated` | [`lark-approval-instances-initiated.md`](references/lark-approval-instances-initiated.md) |
 
 处理链：
 

package/skills/lark-approval/references/lark-approval-instances-initiated.md

@@ -14,6 +14,9 @@ lark-cli approval instances initiated --params '{"page_size":20}' --as user
 # 只看某个审批定义下我发起的实例
 lark-cli approval instances initiated --params '{"definition_code":"<DEFINITION_CODE>","page_size":20}' --as user
 
+# 按关键词搜索我发起的实例
+lark-cli approval instances initiated --params '{"keyword":"测试","page_size":10}' --as user
+
 # 按发起时间范围筛选（秒级时间戳）
 lark-cli approval instances initiated --params '{"start_timestamp":"<START_SECONDS>","end_timestamp":"<END_SECONDS>","page_size":20}' --as user
 
@@ -33,6 +36,7 @@ lark-cli approval instances initiated --params '{"page_size":20}' --as user --dr
 |------|------|------|
 | `--params '{...}'` | 否 | 查询参数，使用 JSON 传入；不传时使用默认分页与筛选 |
 | `definition_code` | 否 | 审批定义 Code，用于只查看某个审批定义下我发起的实例 |
+| `keyword` | 否 | 搜索关键词；非空时走搜索链路，空或仅空格时保持普通列表链路 |
 | `start_timestamp` | 否 | 按发起时间筛选，时间范围开始值，秒级时间戳 |
 | `end_timestamp` | 否 | 按发起时间筛选，时间范围结束值，秒级时间戳 |
 | `locale` | 否 | 返回语言：`zh-CN`、`en-US`、`ja-JP` |
@@ -106,6 +110,7 @@ lark-cli approval instances initiated \
 
 - **这是定位“我发起的审批实例”的首选命令**：如果你的目标是撤回、抄送、查看某个已发起审批，优先从这里拿 `instance_code`。
 - **优先用 `definition_code` 缩小范围**：当你已知审批定义时，先筛掉无关实例，可显著提升可读性。
+- **需要搜索时传入 `keyword`**：搜索排序和普通列表排序不同，按搜索服务结果为准。
 - **按时间排查时使用 `start_timestamp` / `end_timestamp`**：这两个值都是秒级时间戳，用于按发起时间缩小结果范围。
 - **结果很多时优先 `--format table`**：适合人工快速浏览。
 - **`count` 只在第一页返回**：做分页处理时不要假设后续页还会带总数。

package/skills/lark-approval/references/lark-approval-tasks-add-sign.md

@@ -4,38 +4,81 @@
 给一个审批任务加签（用户级写操作）。通常先通过 `tasks query` 拿到 `task_id` 和 `instance_code`，确认目标任务后，再提供被加签人的用户 ID、加签方式等参数执行加签。
 
 > [!CAUTION]
-> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要对该审批任务加签且目标任务、加签对象、加签方式都无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
+> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要对该审批任务加签且目标任务、加签对象、加签方式都无误，再带 `--yes` 运行。用户已明确要求立即执行且列清本轮的加签、转交对象时，该确认覆盖这两个已明确的动作，不要逐条重复询问；不要在未获用户明确同意时静默追加 `--yes`。
 
 需要的 scopes: ["approval:task:write"]
 
+## 先选择加签类型
+
+`add_sign_type` 会影响当前用户的审批任务是否继续可操作，不能只按示例顺序或任意选择：
+
+| 用户意图 | `add_sign_type` | 处理方式 |
+|----------|-----------------|----------|
+| 明确说前加签 / “先让某人审核，我再审” | `1` | 前加签，并按用户要求选择 `approval_method` |
+| 明确说后加签 / “我处理完，再让某人审核” | `2` | 后加签，并按用户要求选择 `approval_method` |
+| “拉进来一起审” / “共同审核” / “一并确认” | `3` | 并加签；不传 `approval_method` |
+| 同一请求要求先加签、再转交当前用户这一环 | `3` | **必须并加签**；加签成功后再转交当前任务 |
+
+前加签或后加签可能推动当前用户的 task 流转，使原 `task_id` 不再支持后续转交。因此，“先加签，再把我这一环转交给其他人”不能使用前加签或后加签；先以 `add_sign_type: 3` 并加签，确认 `tasks add_sign` 成功后，再使用同一组 `instance_code` + `task_id` 执行 `tasks transfer`。
+
+只有在上下文完全无法判断是哪种加签方式、且不同选择会改变审批流程时，才向用户二次询问。用户已经说“一起审”或已经要求“加签后转交当前环节”时，信息足够，不要再询问加签类型。
+
+## 再选择 approval_method
+
+只有前加签、后加签需要 `approval_method`；并加签不传。先遵循用户明确指定的审批方式；用户未指定时，按人数和语义选择：
+
+| 加签人数与语义 | `approval_method` | 处理方式 |
+|----------------|-------------------|----------|
+| 只有 1 名加签人 | `1` | 使用或签；单人时或签、会签的实际效果相同，不再询问 |
+| 多人，明确“任一人审批即可” / “一人通过即可” | `1` | 或签；任一加签人完成审批即可 |
+| 多人，明确“所有人都要审批” / “全部确认” | `2` | 会签；所有加签人都必须完成审批 |
+| 多人，明确“依次审批” / “先 A 后 B” | `3` | 依次审批；每个人按 `add_sign_user_ids` 的数组顺序逐一审批 |
+| 多人，无法从上下文推断 | 不预设 | 询问用户选择或签、会签或依次审批，并说明三者效果 |
+
+依次审批必须保留用户给出的人员顺序。如果已经确定要依次审批，但上下文无法判断先后顺序，先询问人员顺序，再构造 `add_sign_user_ids`；不要自行排序。
+
 ## 命令
 
 ```bash
-# 先预览请求，不实际执行
+# 先预览并加签请求，不实际执行
 lark-cli approval tasks add_sign \
-  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":1,"add_sign_user_ids":["ou_xxx"],"approval_method":1,"comment":"前加签给财务复核"}' \
+  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":3,"add_sign_user_ids":["ou_xxx"],"comment":"请项目 owner 一起审核"}' \
   --params '{"user_id_type":"open_id"}' \
   --as user \
   --dry-run
 
-# 前加签（需要 approval_method）
+# 单人前加签：未指定方式时使用或签
 lark-cli approval tasks add_sign \
   --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":1,"add_sign_user_ids":["ou_xxx"],"approval_method":1,"comment":"请先补充审核"}' \
   --params '{"user_id_type":"open_id"}' \
   --as user \
   --yes
 
-# 后加签（需要 approval_method）
+# 多人后加签：所有人都需要审批，使用会签
+lark-cli approval tasks add_sign \
+  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":2,"add_sign_user_ids":["ou_xxx","ou_yyy"],"approval_method":2,"comment":"当前审批完成后请两位都完成审核"}' \
+  --params '{"user_id_type":"open_id"}' \
+  --as user \
+  --yes
+
+# 多人前加签：按数组中的人员顺序依次审批
 lark-cli approval tasks add_sign \
-  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":2,"add_sign_user_ids":["ou_xxx","ou_yyy"],"approval_method":2,"comment":"当前审批完成后请两位继续审核"}' \
+  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":1,"add_sign_user_ids":["ou_first","ou_second"],"approval_method":3,"comment":"请先由第一位审核，再由第二位审核"}' \
   --params '{"user_id_type":"open_id"}' \
   --as user \
   --yes
 
-# 并加签（常见场景可不传 approval_method）
+# 同一请求要求先加签、再转交：必须并加签；两条命令按顺序执行
 lark-cli approval tasks add_sign \
-  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":3,"add_sign_user_ids":["123456789"],"comment":"并加签给项目 owner"}' \
-  --params '{"user_id_type":"user_id"}' \
+  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":3,"add_sign_user_ids":["ou_reviewer"],"comment":"请一起审核"}' \
+  --params '{"user_id_type":"open_id"}' \
+  --as user \
+  --yes
+
+# 仅在上面的 add_sign 成功后，转交同一当前任务
+lark-cli approval tasks transfer \
+  --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","transfer_user_id":"ou_transferee","comment":"出差期间请代为处理"}' \
+  --params '{"user_id_type":"open_id"}' \
   --as user \
   --yes
 
@@ -56,7 +99,7 @@ lark-cli approval tasks add_sign \
 | `task_id` | 是 | 审批任务 ID；通常先通过 `tasks query` 获取 |
 | `add_sign_type` | 是 | 加签类型：`1` 前加签、`2` 后加签、`3` 并加签 |
 | `add_sign_user_ids` | 是 | 被加签人 ID 数组；需要和 `user_id_type` 保持一致 |
-| `approval_method` | 否 | 审批方式：`1` 或签、`2` 会签、`3` 依次审批；**仅在前加签、后加签时需要填写** |
+| `approval_method` | 否 | 审批方式：`1` 或签、`2` 会签、`3` 依次审批；**仅在前加签、后加签时需要填写**。单人未指定时使用 `1`；多人无法从语义推断时先询问用户 |
 | `comment` | 否 | 审批意见或加签说明，例如 `前加签给财务复核`、`请项目 owner 一并确认` |
 | `--params '{"user_id_type":"..."}'` | 否 | 查询参数 JSON；用于声明 `add_sign_user_ids` 内用户 ID 的类型 |
 | `user_id_type` | 否 | 用户 ID 类型：`user_id`、`union_id`、`open_id`；未显式指定时要特别确认被加签人的 ID 类型 |
@@ -69,19 +112,21 @@ lark-cli approval tasks add_sign \
 
 ### add_sign_type
 
-| 值 | 含义 |
-|----|------|
-| `1` | 前加签 |
-| `2` | 后加签 |
-| `3` | 并加签 |
+| 值 | 含义 | 对当前任务的影响 |
+|----|------|------------------|
+| `1` | 前加签 | 在当前审批前插入审批人，可能推动当前用户的 task 流转 |
+| `2` | 后加签 | 在当前审批后追加审批人，可能推动当前用户的 task 流转 |
+| `3` | 并加签 | 增加并行审批人；需要随后转交当前环节时使用 |
 
 ### approval_method
 
-| 值 | 含义 | 适用场景 |
+仅适用于前加签、后加签；并加签不传。
+
+| 值 | 含义 | 完成条件 |
 |----|------|----------|
-| `1` | 或签 | 前加签 / 后加签 |
-| `2` | 会签 | 前加签 / 后加签 |
-| `3` | 依次审批 | 前加签 / 后加签 |
+| `1` | 或签 | 任一加签人完成审批即可 |
+| `2` | 会签 | 所有加签人都必须完成审批 |
+| `3` | 依次审批 | 所有加签人按 `add_sign_user_ids` 数组顺序逐一审批 |
 
 ## 典型前置步骤
 
@@ -113,7 +158,10 @@ lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' -
 - **`add_sign_user_ids` 与 `user_id_type` 必须匹配**：例如传 open_id 就把 `user_id_type` 设为 `open_id`；不要混用。
 - **优先显式传 `user_id_type`**：这样 agent 更容易判断参数含义，也能减少 ID 类型不匹配带来的失败。
 - **`add_sign_type` 要和业务意图一致**：前加签是在当前审批前插入审批人，后加签是在当前审批后追加审批人，并加签则是增加并行审批人。
-- **前加签 / 后加签要补 `approval_method`**：不要遗漏，否则请求可能无法准确表达审批方式。
+- **加签后还要转交当前环节时必须并加签**：使用 `add_sign_type: 3`，等待加签成功后再用同一组任务参数转交；不要用前加签或后加签导致当前 task 提前流转。
+- **无法推断类型时才询问**：如果用户没有说明先后或并行关系，且后续动作也不能帮助判断，再请用户选择；不要对“一起审”或“加签后转交”重复提问。
+- **前加签 / 后加签要补 `approval_method`**：单人未指定时使用或签；多人优先按语义选择，无法推断时询问用户，不要静默默认。
+- **依次审批保留人员顺序**：按用户指定的先后顺序构造 `add_sign_user_ids`；顺序不明确时先询问，不要自行排序。
 - **优先从 `tasks query` 的待办列表拿任务参数**：尤其是 `topic=1` 的待办审批，最适合作为 add_sign 的输入来源。
 - **先检查是否支持 API 操作**：如果 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 执行处理动作，加签前应谨慎验证。
 - **`comment` 建议写明加签原因**：例如 `增加财务复核`、`增加项目 owner 并行确认`，方便相关人员理解上下文。

package/skills/lark-approval/references/lark-approval-tasks-query.md

@@ -14,6 +14,9 @@ lark-cli approval tasks query --params '{"topic":"1"}' --as user
 # 查询已办审批
 lark-cli approval tasks query --params '{"topic":"2"}' --as user
 
+# 按关键词搜索任务列表
+lark-cli approval tasks query --params '{"topic":"1","keyword":"测试","page_size":10}' --as user
+
 # 按任务时间范围筛选（秒级时间戳）
 lark-cli approval tasks query --params '{"topic":"1","start_timestamp":"<START_SECONDS>","end_timestamp":"<END_SECONDS>"}' --as user
 
@@ -31,6 +34,7 @@ lark-cli approval tasks query --params '{"topic":"1"}' --format table --as user
 | `--params '{"topic":"..."}'` | 是 | 查询参数，使用 JSON 传入 |
 | `topic` | 是 | 任务分组主题，见下方“topic 枚举” |
 | `definition_code` | 否 | 审批定义 Code，用于仅查询某个审批定义下的任务 |
+| `keyword` | 否 | 搜索关键词；非空时走搜索链路，空或仅空格时保持普通列表链路 |
 | `start_timestamp` | 否 | 按任务时间筛选，时间范围开始值，秒级时间戳 |
 | `end_timestamp` | 否 | 按任务时间筛选，时间范围结束值，秒级时间戳 |
 | `locale` | 否 | 返回语言：`zh-CN`、`en-US`、`ja-JP` |
@@ -80,6 +84,7 @@ lark-cli approval tasks query --params '{"topic":"1"}' --format table --as user
 
 - 常见处理链：先用 `tasks query` 拿到 `task_id` 和 `instance_code`，若用户需要查看详情、当前节点、表单内容、流程进度等内容，则调用 `instances get` 查看详情，最后执行 `tasks approve` / `tasks reject` / `tasks transfer` / `tasks add_sign` / `tasks rollback`。
 - 如果你只想看“已发起的审批实例”，使用 `instances initiated`；`tasks query` 更适合围绕“任务分组”来拉取列表。
+- 需要搜索任务标题、摘要或相关内容时传入 `keyword`；搜索排序和普通列表排序不同，按搜索服务结果为准。
 - 按时间排查任务时使用 `start_timestamp` / `end_timestamp` 缩小范围；这两个值都是秒级时间戳。
 - 需要继续翻页时，直接把上一次返回的 `page_token` 放回 `--params`。
 - 当结果量较大时，优先使用 `--format table` 提升可读性。

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
@@ -64,7 +72,7 @@ Block 的 `id` 按类型直接作为对应模块坐标：
 
 ## Table Block（The Core）
 
-Table 本身是 Base Block，也是 Base 的核心数据存储层；Field、Record、View 和 Form 是 Table 内部对象，不是 Base Block。业务数据查询、写入、关联、统计和分析都从 Table 开始；标准资源读取链路是 `+table-list → +field-list → +record-list` / `+record-search`，多表的 `+field-list` 可以并发执行；记录相关任务读取 [Record 查询与分析 SOP](references/lark-base-record-query-and-analysis-sop.md)。
+Table 本身是 Base Block，也是 Base 的核心数据存储层；Field、Record、View 和 Form 是 Table 内部对象，不是 Base Block。业务数据查询、写入、关联、统计和分析都从 Table 开始。先用 `+table-list` 定位 Table；字段名和目标已知的普通读取可直接进入 Record 命令，只有写入、筛选或关联等依赖字段类型/schema 的任务才补 `+field-list`。多表的 `+field-list` 可以并发执行。基础的 Record / CellValue 读写直接按下方路径；reference 只承载高级分析、完整协议和边界细节。
 
 **读取 Table：** `+table-list` 定位表，`+table-get` 读取详情。Table 专属复制使用 `+table-copy`，异步状态用 `+table-copy-status`；schema 和 records 由下方内部对象操作。
 
@@ -74,17 +82,120 @@ Table 下的大多数更新通过异步链路生效，接口成功返回后立
 
 Field 定义列 schema。`field_id` 是稳定列标识，`name` 是可修改的展示名称；Formula、Lookup、Link、Select 等属于 Field 类型或能力。
 
-**读取 Field：** `+field-list` / `+field-get` / `+field-search-options`。**写入 Field：** 已有 Table 中创建多个字段时，优先向一次 `+field-create --json` 传字段对象数组；单字段更新和删除用 `+field-update` / `+field-delete`。创建和更新分别读取 [field-create](references/lark-base-field-create.md) / [field-update](references/lark-base-field-update.md)，由命令文档继续路由 Field JSON、Formula 和 Lookup 协议。
+**读取 Field：** `+field-list` / `+field-get` / `+field-search-options`。**写入 Field：** 已有 Table 中创建多个字段时，优先向一次 `+field-create --json` 传字段对象数组；单字段更新和删除用 `+field-update` / `+field-delete`。创建和更新分别读取 [field-create](references/lark-base-field-create.md) / [field-update](references/lark-base-field-update.md)，由命令文档继续路由 Field JSON、Formula 和 Lookup 协议。`字段插件` 用于扩展基础字段能力：按同一行其他字段内容触发 LLM 生成，并写回已有目标字段；当前已确认目标字段支持文本、单选、数字，配置或触发前先读 [field-extension](references/lark-base-field-extension.md)。
 
 ### Record
 
 Record 是 Table 中的一行数据，包含该记录在各个 Field 下的 CellValue。系统 `record_id` 是表内稳定、非空且唯一的主键，Table 的主字段只是展示字段。
 
-**读取 Record：** 记录预览、筛选、匹配、统计、聚合、TopN、多表或语义分析，以及写前定位记录和写后验收，都必须先完整读取 [Record 查询与分析 SOP](references/lark-base-record-query-and-analysis-sop.md)，并由该 SOP 选择具体命令。**写入 Record：** 优先使用 [batch create](references/lark-base-record-batch-create.md) / [batch update](references/lark-base-record-batch-update.md) 创建或更新一条或多条记录，按其文档中的 CellValue 协议提交字段值。
+#### 1. 读取记录或单元格
+
+- 已知若干个 `record_id`：`+record-get --record-id <id1> --record-id <id2>`
+- 关键词搜索：`+record-search --keyword <text> --search-field <field>`；至少指定一个搜索字段。
+- 其余读取：`+record-list`；结构化条件和排序分别用 `--filter-json` / `--sort-json`。
+
+行数较大、需要服务端谓词下推时，`--filter-json` 使用 tuple condition；最常用的筛选与完整日期范围写法：
+
+```jsonc
+{
+  "logic": "and", // 全部条件成立；任一条件成立改为 "or"
+  "conditions": [
+    ["状态", "intersects", ["进行中", "暂停"]], // Select 命中任一选项
+    ["标题", "intersects", "urgent"], // 文本包含
+    ["备注", "non_empty"], // 非空；判断为空改用 "empty"，两者都不传 value
+    ["金额", ">=", 100], // 数字比较；支持 ==、!=、>、>=、<、<=
+    ["关联项目", "intersects", [{ "id": "recxxx" }]], // Link 包含目标记录
+    ["业务日期", "==", "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 日零点
+  ]
+}
+```
+
+完整操作符和各字段取值结构读取 [Filter 条件结构](references/lark-base-filter-condition.md)。
+
+所有读取都重复传 `--field-id` 做最小字段投影，并统一写入 NDJSON artifact：`--format ndjson --output <path>.ndjson`。每行是一条 Record JSON，stdout 摘要包含 `records_count` 和 `has_more` 用于分页判断。
+
+```bash
+# Example: 行数较大时先筛选 Status 包含 Doing 的记录，再导出 20 条作为局部预览
+lark-cli base +record-list \
+  --base-token <base_token> --table-id <table_id> \
+  --filter-json '{"logic":"and","conditions":[["Status","intersects",["Doing"]]]}' \
+  --field-id Name --field-id Status --field-id Score --limit 20 \
+  --format ndjson --output ./records-preview.ndjson --as user
 
-**Record 生命周期：** `+record-delete` 删除记录；`+record-share-link-create` 创建记录分享链接；`+record-history-list` 查询单条记录的变更事件，读取 [历史记录协议](references/lark-base-record-history-list.md)。附件使用 `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` 操作。
+PREVIEW_ROWS=5
+head -n "$PREVIEW_ROWS" ./records-preview.ndjson
+tail -n "$PREVIEW_ROWS" ./records-preview.ndjson
+```
+
+预计记录数少于 500 行时，建议不做谓词下推，直接拉取到本地用 jq 或 Python 处理；行数较大时可用 `--filter-json` 下推可表达的条件，正则、派生等无法下推的条件继续在本地处理。
+
+```bash
+# jq：对服务端筛选结果追加名称格式筛选，再投影必要字段
+jq -c 'select((.Name // "") | test("^Task-[0-9]+$")) | {record_id, Name}' ./records-preview.ndjson
 
-Record 中的 Select、人员、群组、Link、附件的 CellValue 通常是多值；Link 的目标 `table_id` 来自 Field schema，CellValue 中的 `id` 对应目标表 `record_id`。
+# Python：按行读取并做简单汇总
+python3 - <<'PY'
+import json
+
+with open("records-preview.ndjson", encoding="utf-8") as stream:
+    rows = (json.loads(line) for line in stream if line.strip())
+    print(sum((row.get("Score") or 0) for row in rows))
+PY
+```
+
+`--limit` 的缺省值是 2000，最大值是 2000，通常无需手动指定 limit 参数；支持 `--offset` 参数；只有 `has_more=false` 且查询范围符合问题时，才能当作完整结果。大表完整读取、View 范围读取、复杂 JOIN、集合/多值、时序、语义或专业统计分析时，读取 [Record 查询与分析 SOP](references/lark-base-record-query-and-analysis-sop.md)。
+
+#### 2. 新增记录或更新记录单元格
+
+一条 Record 是 `{字段名或 field_id: CellValue}`，常见 CellValue：
+
+```jsonc
+{
+  "标题": "Created from shortcut", // text: string
+  "官网": "[官网](https://example.com)", // text(url): 裸 URL 或 Markdown link
+  "联系电话": "13800000000", // text(phone): 合法电话号码字符串
+  "邮箱": "owner@example.com", // text(email): 合法邮箱字符串
+  "单选": ["Todo"], // select: array<string>；单选时数组最多一个值；
+  "标签": ["高优", "外部依赖"], // 多选 select: array<string>；必须是当前字段存在的选项；
+  "工时": 8, // number: double，不经过格式化的纯数字
+  "带时区时间": "2026-03-24T10:00:00+08:00", // datetime：带时区，遵循传入的时区
+  "不带时区时间": "2026-03-24 10:00", // datetime：不带时区，自动按当前 Base 时区转换
+  "毫秒时间戳": 1774317600000, // datetime：也支持 Unix 毫秒时间戳
+  "已完成": false, // checkbox: boolean
+  "负责人": [{ "id": "ou_123" }], // user(multiple=false): 数组最多一个元素
+  "协作人": [{ "id": "ou_123" }, { "id": "ou_456" }], // user(multiple=true): 数组可包含多个元素
+  "群聊": [{ "id": "oc_123" }, { "id": "oc_456" }], // group_chat(multiple=true)
+  "关联任务": [{ "id": "rec456" }], // link: array<{id}>，record_id 来自目标表
+  "坐标": { "lng": 116.397428, "lat": 39.90923 }, // location: {lng,lat}
+  "清空": null, // 清空单元格，传 null
+  "清空数组": [] // 清空数组类单元格，空数组和 null 都可以
+}
+```
+
+附件使用专用 shortcut 上传、下载或移除。created_at, updated_at, created_by, updated_by, auto_number, formula, lookup 类型字段只读，若误写入单元格会返回 `ignored_fields` 表示这些字段被静默过滤，其余字段正常写入。
+
+```bash
+# 新增：成功时返回 record_id_list
+lark-cli base +record-batch-create \
+  --base-token <base_token> --table-id <table_id> \
+  --json '{"create_records":[{"Name":"Task A","Status":["Todo"]},{"Name":"Task B","Score":20}]}' --as user
+
+# 更新：每条记录只提交要改变的字段
+lark-cli base +record-batch-update \
+  --base-token <base_token> --table-id <table_id> \
+  --json '{"update_records":{"<record_id_a>":{"Status":["Done"]},"<record_id_b>":{"Score":100}}}' --as user
+```
+
+大 payload 可用脚本生成 json 后用 `--json @file.json`。单批最多 200 条，超过后分批，同一 Table 串行写入；并行可能触发 `1254291` 并发冲突错误。
+
+#### 3. 其他 Record 操作
+
+- `+record-delete --base-token <base_token> --table-id <table_id> --record-id <id1> --record-id <id2>` 删除若干个记录
+- `+record-share-link-create --base-token <base_token> --table-id <table_id> --record-id <id1> --record-id <id2>` 创建记录分享链接
+- `+record-history-list` 查询单条记录的变更事件，读取 [历史记录协议](references/lark-base-record-history-list.md)
+- 附件必须使用 `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` 操作。
 
 ### View
 
@@ -98,12 +209,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 +280,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` 创建后不可修改。详见[本期不支持的能力](#本期不支持的能力)。