@amaster.ai/pi-lark 0.1.4 → 0.1.6

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-apps/references/lark-apps-session-messages-list.md

@@ -0,0 +1,53 @@
+# apps +session-messages-list
+
+按 page_token 分页读取某个会话轮次（turn）的回复消息。运行时命令事实以 `lark-cli apps +session-messages-list --help` 为准。
+
+## 何时用
+
+用于拉取妙搭应用一轮对话（turn）产生的回复消息列表。只读，scope `spark:app:read`，用户身份。对仍在 running 的 turn 也可读——消息随生成增量出现，配合 `--page-token` 续拉新消息，可用于云端开发期间实时播报本轮进展。它不发消息、也不判断轮次状态；想知道某轮是否跑完、拿 `turn_id`，仍先用 `+session-get`。
+
+## 命令骨架
+
+```bash
+lark-cli apps +session-messages-list --app-id <app_id> --session-id <session_id> --turn-id <turn_id> [--page-token <token>]
+```
+
+| 旗标 | 必填 | 说明 |
+|------|:----:|------|
+| `--app-id` | 是 | 应用 ID |
+| `--session-id` | 是 | 会话 ID |
+| `--turn-id` | 是 | 轮次 ID，来自 `+session-get` 的 `latest_turn.turn_id` |
+| `--page-token` | 否 | string，上一页响应里的 `next_page_token`；首页省略 |
+
+## turn_id 来源
+
+`--turn-id` 不是用户能直接提供的，必须先跑 `+session-get` 拿 `latest_turn.turn_id`。没有 `turn_id` 时不要猜，先 `+session-get`。
+
+## 示例
+
+先取最新轮次的 `turn_id`，再拉第一页，最后用 `next_page_token` 续拉下一页：
+
+```bash
+# 1. 从 +session-get 提取 latest_turn.turn_id
+TURN_ID=$(lark-cli apps +session-get --app-id app_xxx --session-id conv_xxx -q '.data.latest_turn.turn_id')
+
+# 2. 拉第一页（省略 --page-token）
+lark-cli apps +session-messages-list --app-id app_xxx --session-id conv_xxx --turn-id "$TURN_ID"
+
+# 3. has_more=true 时，把上一页的 next_page_token 作为 --page-token 续拉
+lark-cli apps +session-messages-list --app-id app_xxx --session-id conv_xxx --turn-id "$TURN_ID" --page-token tok_next
+```
+
+## 输出契约
+
+- `data.messages[]`：每条含 `message_id`、`role`、`content`。
+- `data.next_page_token`（string）：下一页分页令牌，作为下次调用的 `--page-token`。**注意它在最后一页仍非空**（解码形如 `{"offset":N}`），不能用它是否为空判断还有没有下一页。
+- `data.has_more`（bool）：是否还有更多消息。**这是判断要不要续拉的唯一依据。**
+- pretty 输出为消息表 + 末行 `next_page_token: <token>  has_more: <bool>`；自动化取字段用 JSON 或 `-q`。
+- 业务失败（app/session/turn 不存在或 ID 写错）通常带 `error.hint` 指向 `+session-get`，优先转述 hint。
+
+## 分页规则
+
+单次调用只返回一页。Agent 自行续拉：把本次响应的 `next_page_token` 作为下次的 `--page-token`，直到 `has_more` 为 `false` 才停。首页不要传 `--page-token`。
+
+> ⚠️ **终止条件只看 `has_more`，不要拿 `next_page_token` 是否为空判断。** 即使 `has_more=false`（已是最后一页），后端仍会返回一个非空的 `next_page_token`（解码形如 `{"offset":N}`）；若以「token 非空就继续」为循环条件，会在末页之后继续翻出空页（每页 0 条），白费调用。读到 `has_more=false` 立即停止，不要再用该 token 续拉。

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

@@ -0,0 +1,30 @@
+# apps +update
+
+部分更新妙搭应用元信息。运行时命令事实以 `lark-cli apps +update --help` 为准。
+
+## 何时用
+
+只更新应用展示元信息。用户要改代码、发布内容、可见范围或数据库时，不走 `+update`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 至少提供一个：`--name` 或 `--description`。
+- 只发送用户提供的字段，不会清空未提供字段。
+
+## 示例
+
+```bash
+lark-cli apps +update --app-id app_xxx --name "审批系统"
+lark-cli apps +update --app-id app_xxx --description "用于部门审批流转"
+lark-cli apps +update --app-id app_xxx --name "审批系统" --description "用于部门审批流转" --dry-run
+```
+
+## 输出契约
+
+- 成功读取 `data.app`；响应是完整应用对象，不只是被修改字段。
+- 缺 `--app-id` 或没有提供 `--name` / `--description` 会在本地 validation 失败。
+
+## Agent 规则
+
+更新前复述要变更的字段；用户没有提到的字段不要补默认值。执行后只转述新的名称/描述和 app_id，不需要展开原始响应。

package/skills/lark-attendance/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: lark-attendance
+version: 1.0.0
+description: "飞书考勤打卡：查询自己的考勤打卡记录"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli attendance --help"
+---
+
+# attendance (v1)
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
+
+## 默认参数自动填充规则
+
+调用任何 API 时，以下参数 **必须自动填充，禁止向用户询问**：
+
+| 参数 | 固定值 | 说明                                 |
+|------|--------|------------------------------------|
+| `employee_type` | `"employee_no"` | `employee_type`始终等于`"employee_no"` |
+| `user_ids` | `[]`（空数组） | `user_ids`始终等于`[]`                 |
+
+### 填充示例
+
+当构建 `--params` 参数时，自动注入上述字段：
+- `employee_type` 保持 `"employee_no"` 不变
+
+当构建 `--data` 参数时，自动注入上述字段：
+```json
+{
+  "user_ids": [],
+  ...用户提供的参数
+}
+```
+
+> **注意**：`user_ids` 数组保持为空[]，`employee_type` 保持 `"employee_no"` 不变。
+
+## API Resources
+
+```bash
+lark-cli schema attendance.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli attendance <resource> <method> [flags]  # 调用 API
+```
+
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
+### user_tasks
+
+- `query` — 查询用户考勤打卡记录
+
+## 权限表
+
+| 方法 | 所需 scope |
+|------|-----------|
+| `user_tasks.query` | `attendance:task:readonly` |
+

package/skills/lark-base/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: lark-base
+version: 1.2.3
+description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli base --help"
+---
+
+# base
+
+## 何时使用
+
+使用本 skill：
+
+- 用户明确提到 Base / 多维表格 / bitable，或给出 `/base/` 链接。
+- 用户要在 Base 内建表、改表、管理字段、写记录、查记录、配视图。
+- 用户要在 Base 内做公式字段、lookup 字段、跨表计算、派生指标、筛选聚合、TopN、统计分析。
+- 用户要管理 Base 表单、仪表盘、workflow、高级权限或角色。
+- 用户要把旧 Base 聚合式命令或旧写法迁移到当前 `lark-cli base +...` shortcut。
+
+不要使用本 skill：
+
+- 只是认证、初始化配置、切换身份、处理 scope 或权限授权恢复，转 `lark-shared`。
+- 把本地 Excel / CSV / `.base` 导入成 Base，转 `lark-drive +import --type bitable`。
+- 泛化数据分析、字段设计、公式讨论，但没有 Base/多维表格上下文。
+
+## 使用边界
+
+- Base 业务操作只使用 `lark-cli base +...` shortcut，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。
+- 本轮 Base 不依赖 `lark-cli schema`。SKILL 只保留路由、风险和复杂 JSON/DSL；简单命令由命令自身的参数、tips 和错误恢复承接。
+- 用户要把 Excel / CSV / `.base` 导入成 Base 时，先转 `lark-cli drive +import --type bitable`，导入完成后再回到 Base 命令。
+- 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`；Base 文档只保留会影响 Base 路径选择的权限规则。
+
+## 先获取 Base Token 和所需 ID
+
+进入任何需要目标 Base 的 shortcut 前，必须先拿到可用的 `base_token`，以及当前任务需要的 `table_id` / `view_id` / `record_id` / `form_id` / `dashboard_id` / `workflow_id` 等真实 ID；不要把完整 URL、wiki token、workspace token 或孤立 raw token 直接当作 `--base-token`。
+
+- 用户输入 URL 或分享链接：先运行 `lark-cli base +url-resolve --url "<url>" --as user`，用返回的 `base_token` 和相关 ID 继续后续命令。
+- 用户输入 Base 标题、关键词或不确定名称：先运行 `lark-cli base +title-resolve --title "<keyword>" --as user`；`--title` 传入标题中的短关键词，不超过 30 个字符；过长标题先取最有区分度的短关键词；多候选时先让用户消歧，不要猜。
+- 文档嵌入 Base 标签：直接读取 `<bitable>` / `<base_refer>` 的 `token` 作为 `--base-token`，`table-id` 作为 `--table-id`，`view-id` 作为 `--view-id`；孤立 raw token 不走 `+url-resolve`。
+- 仍无法定位且用户不是要新建 Base 时，先反问用户要操作哪一个 Base；用户要新建时才用 `+base-create`。
+
+## 快速路由
+
+| 用户目标 | 优先命令 | 何时读 reference |
+|---|---|---|
+| 查 Base 本体 | `+base-get` | 用返回确认 Base 名称、owner、权限和可继续操作的 token |
+| 创建/复制 Base | `+base-create` / `+base-copy` | 新建时强烈推荐用 `--table-name` + `--fields` 同时配置新 Base 里唯一一个初始数据表的 name 和 schema；写入后报告新 Base 标识和 `permission_grant` |
+| 查看 Base 内资源目录 | `+base-block-list` | 想先了解一个 Base 里有哪些 table/docx/dashboard/workflow/folder 时优先用它；返回 ID 关系和 fewshot 看 `--help` |
+| 管理 Base 内资源目录 | `+base-block-create/move/rename/delete` | 创建或整理 Base 直接管理的 folder/table/docx/dashboard/workflow；资源内容继续用对应命令 |
+| 管理数据表 | `+table-list/get/create/update/delete` | 处理 table 的列出、详情、创建、重命名和删除 |
+| 列/查/删字段 | `+field-list/get/delete/search-options` | 写入前用 list/get 确认字段类型、选项、ID；删除前确认目标字段 |
+| 创建/更新字段 | `+field-create` / `+field-update` | 必读 [lark-base-field-json.md](references/lark-base-field-json.md)；公式读 [formula-field-guide.md](references/formula-field-guide.md)；lookup 读 [lookup-field-guide.md](references/lookup-field-guide.md)；命令细节读 [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md) |
+| 读记录明细 | `+record-get` / `+record-list` / `+record-search` | 涉及筛选、排序、Top/Bottom N、聚合、多表关联、全局结论时读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) |
+| 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读 [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) 和 [lark-base-cell-value.md](references/lark-base-cell-value.md) |
+| 附件字段 | `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` | 附件不要伪造成普通 CellValue；上传走本地文件，下载/删除按 file token 或字段定位 |
+| 删除记录 / 分享记录链接 / 历史 | `+record-delete` / `+record-share-link-create` / `+record-history-list` | 删除前确认 record；分享链接最多 100 条；历史读 [lark-base-record-history-list.md](references/lark-base-record-history-list.md)，只查单条记录，不做整表审计 |
+| 管理视图 | `+view-*` | `+view-set-filter` 读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)；其余配置先 get 现状，再按返回结构更新 |
+| 一次性聚合统计 | `+data-query` | 必读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) 和入口 [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md)；完整 DSL 再读 [lark-base-data-query.md](references/lark-base-data-query.md) |
+| 公式字段 | `+field-create/update --json '{"type":"formula",...}'` | 必读 [formula-field-guide.md](references/formula-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
+| Lookup 字段 | `+field-create/update --json '{"type":"lookup",...}'` | 必读 [lookup-field-guide.md](references/lookup-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
+| 表单提交 | `+form-submit` | 先读 [lark-base-form-detail.md](references/lark-base-form-detail.md) 获取题目、filter 和附件所需 `base_token`；提交 JSON 读 [lark-base-form-submit.md](references/lark-base-form-submit.md) |
+| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md) |
+| 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 [lark-base-form-detail.md](references/lark-base-form-detail.md)；删除前确认目标表单 |
+| 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md)；组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)；读取图表计算结果用 `+dashboard-block-get-data` |
+| Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [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)；list/get/enable/disable 只处理 workflow ID 与启停状态 |
+| 高级权限与角色 | `+advperm-*` / `+role-*` | 角色操作先读入口 [lark-base-role-guide.md](references/lark-base-role-guide.md)；角色 create/update 或解读完整配置再读权限 JSON SSOT [role-config.md](references/role-config.md)；系统角色不可删除；关闭高级权限会影响自定义角色 |
+
+## Base 心智模型
+
+- Base 曾用名 Bitable；返回字段、错误或旧文档里的 `bitable` 多为历史兼容，不代表应改走裸 API 或另一套命令。
+- `+base-block-list` 是查看一个 Base 内资源目录的新入口：它列出这个 Base 直接管理的 `folder/table/docx/dashboard/workflow`，适合先判断 Base 里有什么，再决定走 table、dashboard、workflow 或 docx 命令。
+- `base-block` 只负责资源目录管理，包括创建资源、移动到 folder、重命名和删除；具体资源内容仍走 table/dashboard/workflow 命令。
+- 新建 Base 时，强烈推荐一次性执行 `lark-cli base +base-create --name "<base>" --table-name "<table>" --fields '<field-json-array>'`，同时配置新 Base 里唯一一个初始数据表的 name 和 schema；使用 `--fields` 前先读 [lark-base-field-json.md](references/lark-base-field-json.md) 或复用 `+field-create` 的字段 JSON 形状，不要猜字段属性。
+- `+base-create` 不传 `--table-name` 和 `--fields` 时，会创建一个默认 schema 的初始数据表。
+- 表、字段、视图、workflow、dashboard block 的名称和 ID 必须来自真实返回，不要凭用户口述猜。
+- 存储字段可写；系统字段、`formula`、`lookup` 只读；附件字段走专用 attachment 命令。
+- 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`；需要长期显示在表中时，才新增 `formula` / `lookup` 字段。
+- `formula` 适合常规计算、条件判断、文本/日期处理和长期派生指标；`lookup` 适合明确的跨表查找、筛选后取值或聚合引用。
+- 写入、分析、公式、lookup、workflow、dashboard 前，先读取真实结构：表、字段、视图、关联表和 dashboard block 名称都以命令返回为准。
+- 跨表场景必须读取目标表结构；link 单元格中的关联 `record_id` 只是连接键，最终回答要回查并展示用户可读字段。
+
+## 身份与权限降级
+
+- 默认显式使用 `--as user` 操作用户资源；只有用户明确要求应用身份时，才直接用 `--as bot`。
+- user 身份报 scope/授权不足，或错误中包含 `missing_scopes` / `hint`，先转 `lark-shared` 做用户授权恢复，不要直接降级 bot。
+- user 身份报资源级无访问且无授权恢复提示时，才可用 `--as bot` 重试一次；bot 仍失败就停止重试并按权限错误处理。
+- `91403` 或明确不可访问错误不要循环换身份重试。
+- `+base-create` / `+base-copy` 若用 bot 身份执行，关注返回中的 `permission_grant`，并把用户是否可打开新 Base 告知用户。
+
+## 查询与统计规则
+
+涉及查询、统计或判断结论时，先阅读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)，并遵守：
+
+1. `+record-list` 的默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实，不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。
+2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制，应在 Base 云端查询能力中执行；不要先拉原始记录到本地上下文再手工筛选排序。
+3. `has_more=true` 或等价分页信号表示当前结果不是全量；除非用户只要样例/前 N 条，不能基于该页回答全局问题。
+4. 多表查询必须先确认关系字段和连接键；link 单元格里的 `record_id` 是关系键，不是用户可读答案。
+5. 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。
+6. 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`；要把结果长期显示在表里，才考虑新增 `formula` / `lookup` 字段。
+7. `+data-query` 可返回聚合结果或维度字段行，但维度行按字段组合去重且不返回 `record_id`；需要逐条记录、记录定位或完整行级字段时，再用 `+record-list` / `+record-search` / `+record-get` 回查。
+
+## 写入前置规则
+
+- 更新前先看命令说明：需要完整提交时，先读取并补齐当前配置，只改用户指定的内容，再按命令要求提交；支持局部修改时，按命令说明和 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)。
+- 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
+- 删除、角色更新、字段更新等高风险操作遵循 CLI 的 confirmation gate；目标不明确时先用 get/list 消歧。
+- 批量写入单批最多 200 条；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
+- `+record-batch-update` 是“同值批量更新”：同一份 patch 应用到全部 `record_id_list`，不要拿它做逐行不同值映射。
+- select/multiselect 写入未知选项可能触发平台新增选项；不是要新增时，先用 `+field-list` 或 `+field-search-options` 确认可选值。
+
+## 表单与视图细节
+
+- `+form-submit` 前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
+- 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。
+- `+view-set-filter` 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。
+- 视图适合持久化、共享和 UI 复用；一次性筛选/排序可先用 `+record-list` / `+record-search` 的 filter/sort 验证结果，再按需要沉淀为持久视图。
+
+## 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`。
+- 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` 只适用于自定义角色，系统角色不可删除；删除角色和关闭高级权限前必须确认目标和影响。
+
+## 常见恢复
+
+| 错误 / 现象 | 恢复动作 |
+|---|---|
+| `param baseToken is invalid` / `base_token invalid` | 检查是否把 wiki token、workspace token 或完整 URL 当成了 `--base-token`；按入口规则重新获取真实 `base_token` |
+| `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` | 移除只读字段，只写存储字段 |
+| `1254104` | 批量超过 200，分批调用 |
+| `1254291` | 并发写冲突，串行写入并在批次间短暂等待 |
+| `91403` | 无权限访问该 Base，按 `lark-shared` 权限流程处理，不要盲目重试 |
+
+## 保留 Reference
+
+- [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)：查询/统计/全局结论的选路 SOP
+- [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md)：聚合查询入口 fewshot 与 DSL SSOT
+- [lark-base-cell-value.md](references/lark-base-cell-value.md)：记录 CellValue 构造
+- [lark-base-field-json.md](references/lark-base-field-json.md)：字段 JSON 构造
+- [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)：公式与 lookup 字段
+- [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md)：字段创建/更新命令级补充
+- [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) / [lark-base-record-history-list.md](references/lark-base-record-history-list.md)：记录写入 JSON 与历史返回解释
+- [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)：视图筛选 JSON
+- [lark-base-form-detail.md](references/lark-base-form-detail.md) / [lark-base-form-submit.md](references/lark-base-form-submit.md) / [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)：表单详情、提交和复杂 JSON
+- [lark-base-dashboard.md](references/lark-base-dashboard.md) / [dashboard-block-data-config.md](references/dashboard-block-data-config.md) / [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md)：仪表盘、组件配置与图表结果协议
+- [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)：workflow 入口与 steps JSON SSOT
+- [lark-base-role-guide.md](references/lark-base-role-guide.md) / [role-config.md](references/role-config.md)：角色入口与权限 JSON SSOT