@amaster.ai/pi-lark 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -56,12 +56,12 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.10",
-    "typebox": "*",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "typebox": "1.3.7",
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.15"
+    "@amaster.ai/pi-shared": "0.1.17"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-apps/SKILL.md

@@ -35,6 +35,7 @@ lark-cli auth login --domain apps
 | HTML 应用 / 创意模式 — 写 HTML 页面/网站、静态页、PPT/deck、落地页、仪表盘、UI mockup、原型、线框图、视觉探索 | 加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） | [`creative-design/creative-design.md`](creative-design/creative-design.md) |
 | 旧版存量 HTML 应用（无 Git 管理）继续上传已有静态产物 | `+html-publish`（仅兼容旧链路；新建 html / 创意模式 / creative-design 产物不得使用） | [`lark-apps-html-publish.md`](references/lark-apps-html-publish.md) |
 | 开发已有应用 / 初始化本地仓库（开发方式已定为本地后；先解析 app_id，勿 `+create` 新建） | `+init`（或手动 `+git-credential-init` + 原生 git）。**执行前必读** [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md)，含端到端流程和领域规则 | [`lark-apps-init.md`](references/lark-apps-init.md), [`lark-apps-git-credential.md`](references/lark-apps-git-credential.md) |
+| 只要一份源码快照、不做本地开发；或要取**别人分享给你的**应用源码（你对其仓库无权限） | `+export`（下载 zip；不配 git 凭证、不建工作区）。要继续开发用 `+init` 而非本命令 | [`lark-apps-export.md`](references/lark-apps-export.md) |
 | 本地开发时 `.env.local` 损坏/丢失，重新拉取启动期环境变量 | `+env-pull` | [`lark-apps-env-pull.md`](references/lark-apps-env-pull.md) |
 | 管理应用环境变量（查看/设置/删除） | `+env-list`, `+env-set`, `+env-delete` | [`lark-apps-env.md`](references/lark-apps-env.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`, `+log-get`, `+trace-list`, `+trace-get`, `+metric-list`, `+analytics-list` | [`lark-apps-observability.md`](references/lark-apps-observability.md) |

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

@@ -75,6 +75,8 @@ lark-cli apps +db-env-create --app-id app_xxx --environment dev --sync-data --ye
 
 > 预览与发布同一端点，故 `+db-env-diff` 也需 `spark:app:write` scope（不是纯只读权限）。
 
+**发布审批拦截**：若应用的发布配置了审批，`+db-env-migrate` 会被服务端拒绝（`feature_not_available`，exit 1）。这**不是**参数问题：换 flag、重试都不会成功，也不要去跑 `+db-env-create`。改走应用发布：`lark-cli apps +release-create --app-id <app_id>`，或让用户在页面上发布。只有真发布被拦，`+db-env-diff` 预览照常可用。
+
 ```bash
 lark-cli apps +db-env-diff --app-id app_xxx
 lark-cli apps +db-env-migrate --app-id app_xxx --yes

package/skills/lark-apps/references/lark-apps-env-pull.md

@@ -1,6 +1,6 @@
 # apps +env-pull
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
 
 把妙搭应用 dev 启动期环境变量拉取到本地项目根的 `.env.local`。身份固定 `--as user`；scope `spark:app:read`。`--app-id` 必填，目标项目根默认当前工作目录（`--project-path` 可指定）。
 

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

@@ -1,6 +1,6 @@
 # apps env
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
 
 管理妙搭应用环境变量。查看用 `+env-list`，设置用 `+env-set`，删除用 `+env-delete`。没有单变量 get 命令；要确认某个 key 是否存在，使用 list 后用 `--jq` 过滤。
 

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

@@ -0,0 +1,62 @@
+# apps +export
+
+`+export` 把妙搭应用的源码打成 zip 下载到本地。运行时命令事实以 `lark-cli apps +export --help` 为准。
+
+## 何时用
+
+只要一份源码快照的场景：读代码、审计、归档、做静态分析、把源码喂给别的工具。
+
+**跨应用是它相对 `+init` 的核心价值**：创意应用的分享链接（`/page/<token>`）指向别人的应用，你对那个仓库没有权限，`git clone` 走不通；`+export` 只要求你对该应用有下载权限。
+
+## 不要用它的时候
+
+要继续开发就用 `+init`，不要用 `+export` 再手动 `git init`。两者产出不同：
+
+| | `+export` | `+init` |
+|---|---|---|
+| 产出 | 一个 zip | 完整 git 工作区 |
+| Git 凭证 | 不配 | 配好，可 push |
+| 本地环境变量 | 不拉 | 拉 `.env.local` |
+| 前提 | 对应用有下载权限 | 对**仓库**有权限 |
+
+用 `+export` 拿到的目录没有 git 历史、没有远端、没有凭证，改完发不回去。
+
+## 导出的是「最后一次提交」，不是沙箱当前状态
+
+服务端对远端仓库跑 `git archive`，从不读沙箱文件系统。用户在沙箱里改了文件但没提交或发布，**那些改动不在归档里**。
+
+这是设计如此，不是缺陷。若导出结果看起来"少了刚写的代码"，先确认改动是否已提交，而不是重试导出。
+
+## 命令骨架
+
+- `--app-id` 与 `--meta-token` **恰传其一**：前者是自己的应用，后者是分享链接里的 token。
+  两者作为独立字段走 `POST /apps/export` 的请求体（`app_id` / `meta_token`），服务端按传入的
+  字段区分，不再共用 path 段——调用方只有 token、没有 app_id 时也不用在路径里凑一个占位值。
+  - 两者都只收**裸标识符**。拿到的是整条链接（`.../app/<app_id>` 或 `.../page/<token>`）时，
+    只传最后一段——整条 URL 传进来会被本地拦下并提示，不会变成一个看起来像"应用不存在"的 404。
+- `--output` 可选，相对当前目录；省略时用服务端给的文件名（通常是 `<app_id>.zip`）。
+
+## 示例
+
+```bash
+lark-cli apps +export --app-id app_xxx --output ./src.zip
+lark-cli apps +export --app-id app_xxx                      # 存成 ./app_xxx.zip
+lark-cli apps +export --meta-token <share-token>            # 别人分享给你的应用
+lark-cli apps +export --app-id app_xxx --dry-run
+```
+
+## 输出契约
+
+- 成功时 stdout 是 JSON envelope，含 `output`（落盘的绝对路径）与 `size_bytes`；传了 `--app-id` 时还会回显 `app_id`。
+- 归档以流式写盘，不会整包驻留内存，大仓库也安全。
+- 失败时不会留下半个文件。
+
+## 错误处理
+
+| 情况 | 怎么办 |
+|---|---|
+| 应用尚未发布（`code 40901 app not published`） | 该应用是产物托管形态（如静态 HTML 应用），导出的是「最新已发布产物」，而它还没有成功发布过版本，此刻没有可导的东西。**先发布应用再重试**——不是 app_id 写错，重试也没用 |
+| 权限不足（403） | 你需要该应用的下载权限。**持有分享 token 不等于有权限** |
+| 应用不存在（404） | 用 `+list --keyword <name>` 核对 app_id |
+| 归档过大（413） | 超出导出体积上限，改用 `+git-credential-init` + 原生 git clone |
+| 参数报错 | `--app-id` 与 `--meta-token` 只能给一个，且必须给一个；两者都要裸标识符（不是整条链接） |

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

@@ -1,6 +1,6 @@
 # apps observability
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
 
 查询妙搭应用的线上运行观测和产品访问分析。所有 observability 命令只支持 `--environment online`；省略 `--environment` 时默认就是 online，传 dev 或其他环境是不支持的。不要使用旧的 `--env`，也不要使用短选项。
 

package/skills/lark-base/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-base
-version: 1.2.22
+version: 1.2.23
 description: "飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。"
 metadata:
   requires:
@@ -199,9 +199,9 @@ lark-cli base +record-batch-update \
 
 ### View
 
-View 是同一 Table records 上的持久化筛选、排序、分组和展示配置，共享底层 records，不产生数据副本。一次性查询直接使用 Record 读取；需要在 Base UI 中长期保存、共享或复用访问方式时使用 View。
+View 共享 Table 的底层记录；没有特殊展示需求时优先使用 `grid`。读取已有视图用 `+view-list` / `+view-get`。
 
-**读取 View：** 使用 `+view-list` / `+view-get`，并通过 `+view-get-filter` / `+view-get-sort` / `+view-get-group` / `+view-get-visible-fields` / `+view-get-timebar` / `+view-get-card` 读取持久化配置。**写入 View：** 使用 `+view-create` / `+view-rename` / `+view-delete` 管理 View，并通过对应的 `+view-set-*` 更新筛选、排序、分组、可见字段、时间轴和卡片配置；筛选结构读 [View filter](references/lark-base-view-set-filter.md)，由该文档继续路由公共 condition 协议。
+**所有 View 编辑前必读 [View 类型与生命周期](references/lark-base-view.md)**，包括创建、改名、配置修改（筛选、排序、分组、字段显隐、时间条、卡片）和删除。视图选型、适用配置及完整操作示例统一在该 reference 中。
 
 ### Form
 

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

@@ -1,6 +1,6 @@
 # BaseApp（应用模式）操作指引
 
-> 先读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。接口和组件字段以 CLI 当前版本的 API 元数据、[组件配置 reference](lark-base-app-block-data-config.md) 和服务端校验结果为准；不要从组件名称推断额外约束。
+> 先读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。接口和组件字段以 CLI 当前版本的 API 元数据、[组件配置 reference](lark-base-app-block-data-config.md) 和服务端校验结果为准；不要从组件名称推断额外约束。
 
 ## 不支持能力：先判断并停止
 

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

@@ -19,11 +19,12 @@ Block 的 `data_config` 字段因 `type` 不同而变化。本文档是 Dashboar
 | `radar` | 雷达图 |
 | `ranking` | 排行榜 |
 | `statistics` | 指标卡 |
+| `nps` | NPS 图 |
 | `text` | 文本（支持 Markdown） |
 
 ## 字段类型与操作符速查（AI 决策用）
 
-> 先用 `+field-list` / `+field-get` 确认字段 `type`；本节使用当前字段接口里的 canonical 类型名：`number`、`text`、`select`、`datetime`、`checkbox`、`user`。
+> 先用 `+field-list` / `+field-get` 确认字段 `type`；本节使用当前字段接口里的 canonical 类型名：`number`、`text`、`select`、`datetime`、`checkbox`、`user`。NPS 使用的 `Rating` 是 Dashboard 服务端识别的评分字段语义，不属于当前字段操作符速查里的通用筛选类型。
 
 ```
 text: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty
@@ -44,10 +45,11 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 | `table_name` | string | 关联数据表名称 |
 | `series` | `[{ "field_name": "xxx", "rollup": "SUM" }]` | 指标/Y 轴（与 `count_all` 二选一）。rollup 支持 `SUM` / `MAX` / `MIN` / `AVERAGE` |
 | `count_all` | boolean | COUNTA 聚合，统计所有记录数（与 `series` 二选一） |
-| `group_by` | `[{ "field_name": "xxx", "mode": "integrated", "sort": {...} }]` | X 轴分组维度。`mode` 必填，`sort` 可选，见下方说明 |
+| `group_by` | `[{ "field_name": "xxx", "mode": "integrated", "sort": {...} }]` | X 轴分组维度。`mode` 和 `sort` 的要求因组件类型而异，见下方说明 |
 | `filter` | object | 筛选条件 |
 | `filter.conjunction` | `"and"` / `"or"` | 筛选逻辑 |
 | `filter.conditions` | `[{ "field_name", "operator", "value" }]` | 筛选条件数组，value 类型因字段类型而异（见下方 filter 格式规则） |
+| `category_range` | `[min, detractorMax, passiveMax, max]` | NPS 三段边界，仅 `nps` 类型支持；首尾必须等于 Rating 字段量程，首尾匹配由服务端按字段元数据校验 |
 
 ### text 类型特殊结构
 
@@ -214,6 +216,7 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
   - 图表类型必填：`table_name`
   - text 类型必填：`text`
   - 互斥：`series` 与 `count_all` 二选一，且至少提供其一（仅图表类型）
+  - nps 类型必填：`table_name`、长度为 1 的 `group_by`；`group_by[0].mode` 可省略，省略时按 `integrated` 处理，显式传入时也只能为 `integrated`；不支持 `group_by[0].sort` 和 `series`；`count_all` 可省略，出现时只能为 `true`
   - text 类型**不支持**：`series`、`count_all`、`group_by`、`filter`
 - 长度/结构
   - `group_by` 最多 2 个；每项 `field_name` 必填
@@ -238,6 +241,7 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 - 看流程转化 → 漏斗图
 - 看多维度评分 → 雷达图
 - 显示单个指标 → 指标卡（统计数字或记录数）
+- 统计满意度评分分布 → NPS 图（一个 Rating 字段 + 可选分段）
 - 查看单维度 Top N → 排行榜
 
 最小柱状图：
@@ -394,6 +398,20 @@ user / created_by / updated_by: is, isNot, isEmpty, isNotEmpty
 }
 ```
 
+NPS 图（按 Rating 评分字段统计记录数）：
+
+```json
+{
+  "table_name": "问卷结果",
+  "group_by": [{ "field_name": "满意度评分", "mode": "integrated" }],
+  "category_range": [0, 6, 8, 10]
+}
+```
+
+NPS 的 `group_by[0].field_name` 必须指向 Base 的评分字段（Dashboard 内部识别为 `Rating` 语义）。调用方可通过 Base 字段详情或界面字段配置确认评分字段的最小值与最大值；CLI 只能做轻量 JSON 校验，字段类型、字段量程、`category_range` 首尾是否等于评分字段最小值和最大值由服务端按字段元数据校验。
+
+`category_range` 可省略，服务端会按 Rating 字段自身量程生成默认分段。显式传入时数组长度必须为 4，且首尾必须等于 Rating 字段最小值和最大值。
+
 指标卡（统计记录数）：
 
 ```json

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

@@ -1,6 +1,6 @@
 # Dashboard（仪表盘/数据看板）模块指引
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**组件**（图表、指标卡等）进行展示。
 

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

@@ -1,7 +1,7 @@
 
 # Base data-query DSL reference
 
-> **前置路由**: [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) | **认证或授权问题**: [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)
+> **前置路由**: [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) | **认证或授权问题**: [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)
 
 ## 限制
 

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

@@ -1,6 +1,6 @@
 # base +field-create
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 创建一个或多个字段；同一表的多个字段优先使用一次 JSON 数组输入。
 

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

@@ -1,6 +1,6 @@
 # base +field-update
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 更新一个已有字段。
 

package/skills/lark-base/references/lark-base-form-questions-create.md

@@ -1,6 +1,6 @@
 # base +form-questions-create
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 向多维表格表单/问卷中批量添加问题。可以新建字段并作为题目，也可以把已有字段加到表单中作为题目而不新建字段。
 

package/skills/lark-base/references/lark-base-form-questions-update.md

@@ -1,6 +1,6 @@
 # base +form-questions-update
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 批量更新多维表格表单/问卷中的问题配置（标题、描述、是否必填、显隐条件等）。
 

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

@@ -1,6 +1,6 @@
 # base +form-submit
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 通过表单分享链接填写并提交多维表格表单。仅支持分享模式（share_token），支持填写普通字段值和上传本地文件作为附件。
 

package/skills/lark-base/references/lark-base-view-set-filter.md

@@ -1,6 +1,6 @@
 # base +view-set-filter
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 更新视图筛选配置。
 

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

@@ -0,0 +1,109 @@
+# View：类型选择与生命周期
+
+所有 View 编辑前必读本参考，包括创建、改名、配置修改和删除。
+
+View 是同一 Table 的展示与组织方式，共享底层记录；创建视图不会复制记录。只创建满足当前需求的视图，不默认把五种类型全部建一遍。一次性查询用 Record 命令；需要用户长期浏览、处理或共享时创建 View。
+
+## 选择视图
+
+**Grid 是最常用的默认视图，方便查看、录入和修改数据。没有明确的特殊展示需求时使用 Grid，不因数据包含状态、日期或附件字段就自动创建其他类型。只有用户明确需要分栏处理、时间跨度比较、日历定位或卡片浏览时，才分别选择 Kanban、Gantt、Calendar 或 Gallery。**
+
+| 类型 | 展示方式与优势 | 何时选用 | 优先配置 |
+|---|---|---|---|
+| `grid` 表格 | 每行一条记录、每列一个字段，采用熟悉的表格形式，方便查看、录入和修改数据；可通过筛选、分组、排序调整展示。 | 最常用的默认视图；日常读写数据，没有特殊展示需求时优先使用。 | 可见字段及顺序；按需筛选、分组、排序。 |
+| `kanban` 看板 | 按分组字段横向排列列，每列展示该组的记录卡片；排序控制组内记录顺序。 | 需要按状态、阶段或类别分栏处理事项；优先选用有清晰选项的单选/多选字段作为分组依据。 | 分组字段、卡片可见字段、组内排序；有附件时可选封面。多选分组不可直接当作互斥分区统计。 |
+| `gantt` 甘特图 | 左侧为表格明细，右侧为同一批记录的时间条；可直观看到起止时间、持续时间及排期重叠。左侧支持可见字段、筛选、分组和排序。 | 每条记录代表具有时间跨度的任务、项目或其他实体，重点是比较排期。 | `timebar` 绑定开始、结束和标题字段；左侧通常只留 1–3 个关键字段，为时间轴留空间。 |
+| `calendar` 日历 | 将记录按时间字段定位到日历日期格，以事项形式展示；方便回答“某天有哪些事”。 | 发布计划、活动、预约、任务日期等，重点是按日/周/月浏览。 | `timebar` 绑定开始、结束和标题字段；配置展示字段和筛选。不要套用表格的通用分组、排序。 |
+| `gallery` 画册 | 记录直接以卡片排列，不按状态分栏；重点内容可配附件封面。 | 产品、素材、案例、人员等需要逐卡浏览的集合；不要求每条记录有图片。 | 卡片展示字段、可选封面、筛选与排序。 |
+
+选择捷径：**日常读写数据、无特殊展示需求 → grid；按状态/类别处理 → kanban；比较时间跨度 → gantt；按日期找事项 → calendar；浏览卡片内容 → gallery。** Gantt 和 Calendar 都能展示时间相关实体，区别是前者强调跨度与重叠，后者强调日期位置。
+
+## Few-shot：按目的创建与配置
+
+以下是相互独立的选型示例，不是一套必须全执行的步骤。`BASE_TOKEN`、`TABLE_ID` 使用已解析的真实资源坐标；字段名示例假定目标表已有相应字段，配置前用 `+field-list` 核实类型与名称。`--view-id` 接受真实 ID 或名称；示例使用新建视图的唯一名称，名称不唯一时使用实际返回 ID。
+
+### 表格查看与维护：grid
+
+需求：“按项目分组查看任务，优先显示最早截止的任务。”
+
+```bash
+# 默认视图；支持筛选、字段显隐、分组、排序；不支持时间条和卡片封面。
+# 创建 JSON 支持对象/数组，type 默认 grid；不要塞入 group_by/property，form 走 Form 命令。
+lark-cli base +view-create --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --json '{"name":"任务明细","type":"grid"}' --as user
+# visible_fields 是完整有序列表；遗漏即隐藏，不删除数据，主字段可能固定在首位。
+lark-cli base +view-set-visible-fields --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务明细" --json '{"visible_fields":["任务名称","项目","状态","截止时间"]}' --as user
+# group_config 最多 3 项，字段须适用于目标视图；空数组清除分组。
+lark-cli base +view-set-group --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务明细" --json '{"group_config":[{"field":"项目","desc":false}]}' --as user
+# sort_config 最多 10 项；空数组清除排序。配置 JSON 用对象包装，不传裸数组。
+lark-cli base +view-set-sort --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务明细" --json '{"sort_config":[{"field":"截止时间","desc":false}]}' --as user
+```
+
+### 按状态处理任务：kanban
+
+需求：“待办、进行中、已完成各一列，每列按截止时间排列。”前置：状态字段是包含相应选项的单选字段。
+
+```bash
+# 支持筛选、字段显隐、分组、排序、卡片封面；不支持时间条。
+# 优先按一个单选/多选字段分栏；group 的 desc 排列分组，sort 排列组内记录。
+lark-cli base +view-create --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --json '{"name":"任务看板","type":"kanban"}' --as user
+lark-cli base +view-set-group --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务看板" --json '{"group_config":[{"field":"状态","desc":false}]}' --as user
+lark-cli base +view-set-visible-fields --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务看板" --json '{"visible_fields":["任务名称","负责人","截止时间"]}' --as user
+lark-cli base +view-set-sort --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务看板" --json '{"sort_config":[{"field":"截止时间","desc":false}]}' --as user
+```
+
+### 比较任务排期：gantt
+
+需求：“查看任务开始到结束的排期，左侧只保留任务和负责人。”
+
+```bash
+# 支持筛选、字段显隐、分组、排序、时间条；不支持卡片封面。
+# timebar 必填开始、结束、标题；起止字段须为日期/时间且记录有值，按业务排期选择。
+lark-cli base +view-create --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --json '{"name":"任务排期","type":"gantt"}' --as user
+lark-cli base +view-set-timebar --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务排期" --json '{"start_time":"开始时间","end_time":"结束时间","title":"任务名称"}' --as user
+# 左侧通常保留 1–3 个关键字段，为时间轴留空间。
+lark-cli base +view-set-visible-fields --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "任务排期" --json '{"visible_fields":["任务名称","负责人"]}' --as user
+```
+
+### 按日期浏览活动：calendar
+
+需求：“在日历上查看每项活动的安排。”
+
+```bash
+# 支持筛选、字段显隐、时间条；不支持通用分组、排序和卡片封面。
+# timebar 必填开始、结束、标题；起止字段须为日期/时间且记录有值。
+lark-cli base +view-create --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --json '{"name":"活动日历","type":"calendar"}' --as user
+lark-cli base +view-set-timebar --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "活动日历" --json '{"start_time":"活动开始","end_time":"活动结束","title":"活动名称"}' --as user
+```
+
+### 浏览产品卡片：gallery
+
+需求：“以图片卡片浏览产品，展示名称、分类和价格。”前置：产品图片是附件字段。
+
+```bash
+# 支持筛选、字段显隐、排序、卡片封面；不支持分组和时间条。
+# cover_field 使用附件字段；传 null 清除封面。
+lark-cli base +view-create --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --json '{"name":"产品画册","type":"gallery"}' --as user
+lark-cli base +view-set-card --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "产品画册" --json '{"cover_field":"产品图片"}' --as user
+lark-cli base +view-set-visible-fields --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "产品画册" --json '{"visible_fields":["产品名称","分类","价格"]}' --as user
+```
+
+### 通用生命周期：发现、筛选、改名、清理
+
+```bash
+# 五种视图均支持查询、改名、删除；已有目标视图时直接配置它。
+# 修改已有配置先读对应 get（如 +view-get-group）；需要验收时再读回。
+# 批量创建逐项执行，可能部分成功；异常或同名冲突后先 list 确认，避免盲重试。
+lark-cli base +view-list --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --as user
+lark-cli base +view-get --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "$VIEW_ID" --as user
+
+# 只展示进行中的记录；复杂条件见下方筛选参考
+lark-cli base +view-set-filter --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "$VIEW_ID" --json '{"logic":"and","conditions":[["状态","intersects",["进行中"]]]}' --as user
+
+# 改名用 --name；创建用 --json 中的 name
+lark-cli base +view-rename --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "$VIEW_ID" --name "进行中任务" --as user
+
+# 用户明确要求且目标已确认时删除视图；不删除底层记录。
+lark-cli base +view-delete --base-token "$BASE_TOKEN" --table-id "$TABLE_ID" --view-id "$VIEW_ID" --as user --yes
+```
+
+筛选详细写法见 [View filter](lark-base-view-set-filter.md)；该文档继续路由公共条件协议。

package/skills/lark-calendar/references/lark-calendar-transfer.md

@@ -58,7 +58,7 @@ lark-cli im +chat-members-list --chat-id <chat_id> --member-types bot
 
 机器人的 open_id 同样是 `ou_` 开头；不要传 `cli_` 开头的 app_id，那是应用 ID，不是日程参与人身份。
 
-无论哪个方向，转让都要求转出方和接收方**同租户**，且接收方能通过高管模式的协作校验。
+无论哪个方向，转让都要求转出方和接收方**同租户**。
 
 ## 重复性日程
 

package/skills/lark-doc/references/lark-doc-media-download.md

@@ -1,7 +1,7 @@
 
 # docs +media-download（下载文档素材/画板缩略图）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 下载文档中的图片/文件素材（`file_token`），或下载画板缩略图（`whiteboard_id`）。当 `--output` 不带扩展名时，会根据响应的 `Content-Type` 自动补全扩展名。
 

package/skills/lark-doc/references/lark-doc-media-insert.md

@@ -1,7 +1,7 @@
 
 # docs +media-insert（文档末尾插入图片/文件）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 把"创建空 block → 上传文件 → 设置 token"三步合并成一个命令，在**文档末尾**插入本地图片或文件。
 

package/skills/lark-doc/references/lark-doc-media-preview.md

@@ -1,7 +1,7 @@
 
 # docs +media-preview（预览文档素材）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。
 

package/skills/lark-doc/references/lark-doc-resource-cover.md

@@ -1,6 +1,6 @@
 # docs +resource-*（Docx 封面图资源）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 Docx 封面图不是正文里的 `<img token="...">` 素材块。读取、更新、删除文档封面图时，使用 `docs +resource-download/+resource-update/+resource-delete --type cover`，不要使用 `+media-insert` 或 `+media-download --token <cover.token>` 让用户手动拼步骤。
 

package/skills/lark-drive/references/lark-drive-add-comment.md

@@ -1,7 +1,7 @@
 
 # drive +add-comment
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 给文档、受支持的 Drive 普通文件、电子表格、飞书幻灯片或 Base 添加评论。未指定位置时创建全文评论，但仅适用于 doc/docx、白名单 Drive file，以及解析为这些类型的 wiki；sheet、slides、Base(bitable) 必须指定 `--block-id`。不同类型的 `--block-id` 格式见下文。支持直接传 docx URL/token、旧版 doc URL（仅全文评论）、Drive file URL/token（**仅支持白名单扩展名，且只支持全文评论**）、sheet URL、slides URL、base/bitable URL，也支持传最终可解析为 doc/docx/file/sheet/slides/base(bitable) 的 wiki URL。
 

package/skills/lark-drive/references/lark-drive-apply-permission.md

@@ -1,7 +1,7 @@
 
 # drive +apply-permission（申请文档权限）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 本 skill 对应 shortcut：`lark-cli drive +apply-permission`。
 

package/skills/lark-drive/references/lark-drive-copy.md

@@ -1,7 +1,7 @@
 
 # drive +copy
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 复制一个 Drive 文件（在线文档、表格、多维表格、幻灯片、思维笔记或普通文件）到目标文件夹，生成一个内容相同的新副本。
 

package/skills/lark-drive/references/lark-drive-cover.md

@@ -1,6 +1,6 @@
 ## `drive +cover`
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和安全规则。
 
 列出或下载 Drive 文件的稳定封面预设。这个 shortcut 只暴露 `spec`，不暴露底层 `cover_option` 细节。
 

package/skills/lark-drive/references/lark-drive-create-folder.md

@@ -1,6 +1,6 @@
 # drive +create-folder（创建云空间/云盘/云存储文件夹）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 在飞书云空间（云盘/云存储）中创建一个新文件夹。该 shortcut 对原生 `drive files create_folder` 做了一层更适合日常使用的封装：`--folder-token` 可省略，此时会在调用者根目录创建；如果使用 `--as bot`，创建成功后 CLI 会尝试把新文件夹的可管理权限自动授予当前 CLI 用户。
 

package/skills/lark-drive/references/lark-drive-create-shortcut.md

@@ -1,7 +1,7 @@
 
 # drive +create-shortcut
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 在目标文件夹中为一个现有 Drive 文件创建快捷方式。
 

package/skills/lark-drive/references/lark-drive-delete.md

@@ -1,7 +1,7 @@
 
 # drive +delete
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 删除云空间（云盘/云存储）内的文件或文件夹。删除后资源会进入回收站。
 

package/skills/lark-drive/references/lark-drive-download.md

@@ -1,7 +1,7 @@
 
 # drive +download
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 从飞书云空间（云盘/云存储）下载文件到本地。下载对象是 Drive **文件**（上传的 PDF/zip/图片/音视频等文件），以及支持 Wiki URL / Wiki token。
 

package/skills/lark-drive/references/lark-drive-export-download.md

@@ -1,7 +1,7 @@
 
 # drive +export-download
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 根据导出任务产物的 `file_token` 下载本地文件。通常与 `drive +task_result --scenario export` 配合使用。
 

package/skills/lark-drive/references/lark-drive-export.md

@@ -1,7 +1,7 @@
 
 # drive +export
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 把 `doc` / `docx` / `sheet` / `bitable` / `slides`（也支持 Wiki URL / Wiki node token 自动解包）导出到本地文件。这个 shortcut 内置有限轮询：
 

package/skills/lark-drive/references/lark-drive-import.md

@@ -1,6 +1,6 @@
 # drive +import
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 将本地文件（如 Word、TXT、Markdown、Excel、PPTX 等）导入并转换为飞书在线云文档（docx、sheet、bitable、slides）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
 

package/skills/lark-drive/references/lark-drive-inspect.md

@@ -1,7 +1,7 @@
 
 # drive +inspect（文档 URL 检视：类型、标题、Token 解析）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 给定一个飞书文档 URL 或 bare token，返回其类型、标题和 canonical token。对 wiki URL 自动解包到底层文档。
 

package/skills/lark-drive/references/lark-drive-list-comments.md

@@ -1,6 +1,6 @@
 # drive +list-comments
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和权限处理。
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和权限处理。
 
 列出 doc/docx/sheet/file/slides/base(bitable)/apps 的评论卡片。优先传用户给出的完整 URL，shortcut 会自动识别类型；apps 为妙搭类型，支持 `/page/<token>` URL；如果传 wiki URL 或 `--token <wiki_token> --type wiki`，会先解析到真实文档。