@amaster.ai/pi-lark 0.1.2-beta.55 → 0.1.2-beta.56

package/skills/lark-base/references/lark-base-data-analysis-sop.md

@@ -1,210 +1,221 @@
-# Base data analysis SOP
+# Base 数据表查询与分析 SOP
 
-Base 数据查询与分析任务的执行契约。覆盖记录读取、筛选、排序、Top/Bottom N、聚合统计、分组聚合、多表关联、临时分析和查询后写入前的目标定位。
+数据表记录查询和分析任务先读本 SOP，包括记录预览、筛选、排序、去重、统计、聚合、TopN、多值计算、Link 或多表关联、复杂行级计算、全局结论和查询后写入。先区分需要 LLM 理解原文的语义分析与可程序化计算的确定性分析，再按任务所需数据规模与计算复杂度选择对应路径。用户直接要求解释、编写或排错 `+data-query` 命令或 DSL 时，直接读 [data-query guide](lark-base-data-query-guide.md)。
 
-本文只管查询选路和正确性边界；具体操作前先读真实结构和现状，复杂 JSON 再跳到 reference：
+## 分流决策
 
-- `+data-query`: entry guide [lark-base-data-query-guide.md](lark-base-data-query-guide.md), full DSL SSOT [lark-base-data-query.md](lark-base-data-query.md)
-- 视图筛选: [lark-base-view-set-filter.md](lark-base-view-set-filter.md)
-- 记录读取: `+record-list` / `+record-search` / `+record-get`，先确认字段 ID、字段名、分页和投影范围
+1. 明确所有需要参与分析的表及其 `records_count`。
+2. 如果结论必须依赖 LLM 理解原始内容，例如开放文本打标、情绪或意图识别、主题归纳、语义分类、相似性判断或实体消歧，进入下文“LLM 语义分析”路径。
+3. 对于其余确定性查询，任一分析表超过 2000 行时，先从任务意图中为所有大表提取可在单表内独立执行的谓词，例如日期范围、状态和关键词，再按下文将谓词逐表下推，并用 `--field-id '<一个简单标量字段>' --limit 2000 --output <probe>.ndjson --minimal-stdout` 探测。目标是每张表都达到 `has_more=false`；任一表无法压缩到 2000 行以内时，转 [lark-base-data-analysis-cloud.md](lark-base-data-analysis-cloud.md) 用云端的数据分析能力。
+4. 所有分析表都不超过 2000 行后：若只有一张表且短 jq 可清晰完成筛选、计数、简单分组/聚合/排序、TopN 可以使用 jq。
+5. 其余确定性任务比如多表、日历计算和复杂数据分析，在 Python 可用时使用 Python，否则进入 [Cloud SOP](lark-base-data-analysis-cloud.md)。
 
-## 0. Hard Rules
+进入 Cloud 后先由 Cloud SOP 在原始记录查询与聚合查询之间选路；只有选定 `+data-query` 时才读取 data-query guide。
 
-- 全局问题不能用默认 `+record-list --limit N` 片面地回答。
-- `jq` / shell / 本地代码是在个人电脑或当前运行环境中处理已返回数据，只适合小范围结果；超过 200 行默认不推荐本地统计、排序或求极值，应改用 Base 云端查询服务的 filter/sort/aggregate。
-- “最高、最低、最新、最早、Top、Bottom、总数、全部、异常、最大、最小、最多、最少、优先级最高”等全局语义，必须在 Base 云端查询服务中完成筛选、排序或聚合。
-- 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`。
-- `+record-search` 用于关键词检索字段的展示文本；金额、状态、日期、空值、关联等结构化条件继续用 `--filter-json` 表达。
-- 不要依赖已有视图，除非用户明确指定该视图，或你已读取并验证其 filter/sort/projection 符合当前问题。
-- 交付输出必须使用用户可读的真实字段值；内部 ID、`record_id`、关联记录 ID、open_id、编码字段只可作为连接键或定位键，不能替代最终输出，除非用户明确要求输出这些键值。
-- 每次读取必须做最小投影，并包含后续解释、回查或写入需要的业务 key。
+## 执行与交付
 
-## 1. Intent -> Tool Path
+分析输入默认采用 `--output x.ndjson`；NDJSON 未显式传 `--limit` 时默认读取最多 2000 条，正式分析通常沿用该范围。窄投影探测、快速预览或用户明确要求前 N 条时再设置较小的 `--limit`。`--format json` 和 Markdown 适用于向用户即时展示的小结果。
 
-| 用户意图 | 首选路径 | 关键规则 |
-| --- | --- | --- |
-| 看几条、预览、示例 | `+record-list --limit N --field-id ...` | 保持局部语义；不要推广为全局结论 |
-| 已知 `record_id` | `+record-get` | 直接读取；不要 search/list 反查 |
-| 明确关键词 | `+record-search --keyword ... --search-field ... --field-id ...` | 必须显式指定 `--search-field`；可叠加 `--filter-json` |
-| 按条件找原始记录 | `+record-list --filter-json ...` | `filter-json` 与视图筛选结构一致，支持文本、数字、日期、选项、人员、群组、关联等值 |
-| 排序 / TopN 原始记录 | `+record-list --filter-json ... --sort-json ... --limit N` | 最高/最新用 `desc:true`，最低/最早用 `desc:false`；数组顺序表达优先级；最多 10 个排序条件 |
-| 聚合 / 分组 / 分组排序 | `+data-query` | 使用 filters/dimensions/measures/sort/limit |
-| 聚合后输出逐条记录 | `+data-query` 得到业务 key 或候选字段组合 -> `+record-list --filter-json` / `+record-get` 回查 | `+data-query` 维度行按字段组合去重且不返回 `record_id` |
-| 多表 / 多跳关联 | 以候选数最小的事实表为驱动表，沿业务 key 或 link `record_id` 逐跳回查 | 读出 link 单元格里的关联 `record_id` 后，到被关联表批量 `+record-get` 展示字段 |
-| 查询后写入 / 视图化 | 先用本 SOP 得到可复核的目标记录 id 集合 | 再进入记录写入或视图配置；高价值可复用查询可沉淀为持久视图 |
+缩小大表记录范围时，展示文本关键词用 `+record-search`，日期、状态、数字、空值、选项、人员和关联等结构化条件用 `+record-list --filter-json`。
 
-## 2. Execution Patterns
+### 单表谓词下推常用 example
 
-### 2.1 结构化原始记录与 TopN
+`+record-list` / `+record-search` 的 `--filter-json '<filter-json>'` 支持使用 tuple condition 下推单表谓词。以下示例用注释说明各条件的含义；实际传参时删除注释并使用标准 JSON：
 
-使用 `+record-list` 的 filter/sort 路径：
+```jsonc
+{
+  "logic": "and", // 所有 conditions 同时成立；任意一个成立时使用 "or"
+  "conditions": [
+    ["标题", "==", "Launch plan"], // 文本全等
+    ["标题", "intersects", "urgent"], // 文本包含目标片段
+    ["金额", ">=", 100], // 数字比较；支持 ==、!=、>、>=、<、<=
+    ["状态", "intersects", ["进行中", "暂停"]], // Select 集合相交：包含“进行中”或“暂停”任意一个选项
+    ["状态", "disjoint", ["已终止"]], // Select 集合无交集
+    ["已完成", "==", true], // Checkbox
+    ["负责人", "intersects", [{"id": "ou_xxx"}]], // 负责人包含某个人；intersects 表示包含数组中任意一个人员
+    ["关联项目", "intersects", [{"id": "rec_xxx"}]], // 关联项目包含某个 record_id；intersects 表示包含数组中任意一条关联
+    ["备注", "non_empty"], // 非空判断；标量 null 和多值空数组都是空
+    ["业务日期", "==", "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 日零点
+  ]
+}
+```
 
-1. `+field-list` 确认筛选字段、排序字段、展示字段、业务 key。
-2. 筛选只用 `--filter-json` 或 `--filter-json @file`。
-3. 排序用 `--sort-json`。
-4. `--field-id` 做最小投影，`--limit` 控制返回数量。
+全表分析的常规资源链路是 `+table-list` 确认目标表与规模，对所有参与分析的表并发执行 `+field-list` 读取所需 schema，再用 `+record-list` 导出记录；已有可信的 `table_id` 时可直接并发读取各表 `+field-list`。`+view-get` 可按需读取，作为用户持久化访问习惯的可选参考；其中的 filter、sort 与字段范围可辅助理解用户常用的查询范围和排序偏好，并结合当前任务确定最终口径。
 
-Example: string/number 条件 + TopN：
+1. 每次读取使用任务所需的最小投影，并包含 JOIN、解释、回查或写入需要的业务 key。
+2. 全局结论以 `has_more=false` 的完整导出或 Cloud 聚合结果为依据；`has_more=true` 时继续收敛单表谓词或选择 Cloud 路径。
+3. 确定性分析选定一个分析引擎直接读取 NDJSON；模型上下文仅接收预览或最终小结果。
+4. Base 标量空值很常见；聚合前按用户口径确定空值是排除、按零计入还是进入分母。用户未指定且不同处理会实质改变结论时，说明空值数量、采用的口径及其影响；任务涉及业务键、展开、JOIN 或金额分摊时，同样明确目标粒度及与口径直接相关的重复或总量守恒。
+5. 最终结果保留真实表、查询范围和计算口径，展示用户可读字段；内部 ID 用于连接或定位。
 
-```bash
-lark-cli base +record-list \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --filter-json '{"logic":"and","conditions":[["Title","==","Launch plan"],["Score",">=",80]]}' \
-  --sort-json '[{"field":"Updated","desc":true}]' \
-  --field-id Name \
-  --field-id Title \
-  --field-id Score \
-  --limit 20
-```
+`+table-list` / `+base-block-list` 返回的 `records_count` 表示整表行数；manifest 的 `records_count` 表示本次查询实际导出的行数。
 
-Example: 复杂筛选从文件读取：
+## 复用本轮 NDJSON
 
-```bash
-lark-cli base +record-list \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --filter-json @filter.json \
-  --sort-json '[{"field":"Priority","desc":true}]' \
-  --field-id Name \
-  --field-id Tags \
-  --limit 50
-```
+Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否复用：
 
-`filter-json` 与视图筛选结构一致。下面只列常用 fewshot；字段类型、operator、value 形状拿不准，或需要人员、群组、关联、空值、地理位置、formula / lookup 等完整筛选时，先读 [lark-base-view-set-filter.md](lark-base-view-set-filter.md)，再把同样的 filter JSON 传给 `--filter-json`。
+1. 短时间内继续分析或表中数据低频变化时，谓词下推口径一致且已有列覆盖计算需求即可优先复用。
+2. 间隔较长或表中数据高频变化时，批量提取 manifests 的 `base_token/table_id/rev`，并发执行 `+table-list` 校验最新 `rev`；版本一致且谓词口径未变时复用，否则重新导出对应表。
 
-文本 `==`：字段值等于目标文本。
-```json
-{"logic":"and","conditions":[["Title","==","Launch plan"]]}
-```
+> 例：本轮已按“日期在 2026 年”导出 `orders.ndjson`，用户继续要求按负责人聚合；谓词和所需列未变，直接复用。若间隔较长或该表频繁写入，manifest `rev=42` 与 `+table-list` 最新 `rev` 相同则复用，最新 `rev=43` 则重新导出。
 
-文本包含 / like：文本字段包含目标片段；operator 写 `intersects`。
-```json
-{"logic":"and","conditions":[["Title","intersects","urgent"]]}
-```
+## LLM 语义分析
 
-数字 `==`：字段值等于目标数字。
-```json
-{"logic":"and","conditions":[["Score","==",95]]}
-```
+先用任务中明确且不改变分析口径的确定性条件缩小数据范围；只有剩余判断必须依赖语义理解时，才将必要原文加载到模型上下文。
 
-日期 `==`：字段值等于目标日期；datetime / created_at / updated_at 用 `ExactDate(...)`。
-```json
-{"logic":"and","conditions":[["Due Date","==","ExactDate(2026-06-02)"]]}
-```
+开放文本打标、情绪或意图识别、主题归纳、语义分类、相似性判断和实体消歧等任务必须理解原文，最终判断由当前 LLM 在本地上下文中逐条完成。代码只用于确定性范围筛选、分批、结果持久化和最终汇总；除非用户明确要求规则法，不用关键词命中、词频、正则或规则打分替代语义判断。
 
-选项 `==`：字段值匹配单个选项；选项值使用选项名数组，单个选项也写数组。
-```json
-{"logic":"and","conditions":[["Priority","==",["P0"]]]}
-```
+1. 先把日期、状态、来源等不改变任务语义的确定性范围条件下推到 Base，只导出 `record_id`、判断所需原文和最终解释所需的最小字段集。
+2. 在读取正文前，先看 manifest 的 `record_file_size_bytes`；结合 `records_count` 以及所选字符串列的 `null_count`、`max_length` 判断正文相对当前上下文的规模，拿不准时先读取前 3 行再决定读取范围。
+3. 文件较小且上下文充足时，将必要记录读入上下文并直接完成语义分析；文件较大但任务仍必须理解全部原文时，先向用户说明原因和预计耗时，在确认后按文本体量分批处理。各批沿用同一判断口径，将 `record_id`、结构化判断和必要依据持续写入本地 artifact，最后统一汇总。
+
+## Manifest
+
+`--output <path>.ndjson` 生成 `<path>.ndjson` 与 `<path>.manifest.json`；记录写入 NDJSON，stdout 返回 manifest，`--minimal-stdout` 只保留文件位置、文件字节数、`records_count` 和 `has_more`。
+
+分析 artifact 使用相对路径输出到当前工作目录，例如 `--output ./records.ndjson`。
 
-选项 `intersects`：字段值与给定选项集合有交集，常用于多选或“命中任一选项”。
 ```json
-{"logic":"and","conditions":[["Tags","intersects",["P0","Blocked"]]]}
+{
+  "record_file": "/path/records.ndjson",
+  "record_file_size_bytes": 18432,
+  "manifest_file": "/path/records.manifest.json",
+  "records_count": 137,
+  "has_more": false,
+  "columns": {
+    "record_id": {"physical_type": "string", "stats": {"max_length": 15}},
+    "状态": {
+      "field_id": "fld_status",
+      "field_type": "select",
+      "physical_type": "array<string>",
+      "stats": {"empty_count": 3, "max_length": 2, "avg_length": 1.1},
+      "example": ["进行中"]
+    }
+  }
+}
 ```
 
-`--sort-json` 传排序数组，数组顺序就是优先级，`desc:true` 为降序，`desc:false` 为升序，最多 10 个排序条件。
+- manifest `columns` 是 NDJSON 物理 schema 的权威来源，包含 `field_id`、`field_type`、`physical_type`、`stats` 以及可选的真实 example 或 hint；它不替代完整 Base field schema，选项配置、数字格式、Link 目标表或 formula/lookup 定义影响任务时读取 `+field-list`。全空列按 hint 跳过，任务必须使用时显式 cast。
+- `stats` 只统计本次导出的 records；`null_count` 只计 JSON `null`，字符串长度按 Unicode 字符计数，数字 `avg` 排除 null，多值 `avg_length` 按全部 records（含 `[]`）计算。
+
+| 列类别 | `stats` |
+| --- | --- |
+| 普通字符串 | `null_count, max_length` |
+| 数字 | `null_count, min, max, avg` |
+| 日期 | `null_count, min, max` |
+| checkbox | `true_count` |
+| Location | `null_count` |
+| 多值列 | `empty_count, max_length, avg_length` |
+| 系统 `record_id` | `max_length` |
+
+- stdout 的 `records_count` 和 `has_more` 描述本次导出；确认后无需在分析代码中重读 manifest 或重新统计 NDJSON 行数。
+- `record_file_size_bytes` 是 NDJSON artifact 的实际字节数，用于选择一次读取、预览或分批方式；确定性计算由 jq/Python 直接读取文件。
+- manifest 的 `rev` 是导出首个响应页返回的 table revision；与 `+table-list` 返回的最新 `rev` 比较，可判断本轮 NDJSON 是否仍对应当前表版本。
+- `query_context` 保存导出查询范围；复用本轮 NDJSON 时结合原查询上下文确认谓词下推口径保持一致。
+- 仅在需要 `columns`、example、hint 或执行 artifact 复用判断时读取 `manifest_file`；满足复用条件后直接继续分析现有 NDJSON。
+- `ignored_fields` 和 `record_not_found` 仅在 stdout 返回时关注。
+
+## 数据库专家快速心智模型
+
+- Base table 是面向协作的反范式宽表；本地分析将每个导出表作为关系输入，不假设数据库级约束。
+- 每行是一条 record；系统 `record_id` 是表内真正的主键，由 Base 系统生成并维护，契约保证 `NOT NULL` 和 `UNIQUE`，分析代码无需再次检查空值或唯一性，也不可把它作为普通字段更新。Base 的“主字段”只是主要展示字段，不是主键。
+- NDJSON 业务列一律使用字段 `name` 作为 key，不使用 `field_id`；字段重命名会改变 key，对应的 `field_id` 仅记录在 manifest 列元数据中。
+- 除 `record_id` 外，不假设任何列满足 `NOT NULL`、`UNIQUE` 或业务键约束；仅当某列实际作为业务键参与关联或去重时处理空值和重复值。
+- checkbox 在 NDJSON 中始终为 `true` 或 `false`，上游空值会在导出时规范化为 `false`；其他标量列可空并使用 `null`。多值列始终非空，没有元素时用 `[]`；这些是序列化契约，不是业务约束。
+- NDJSON 的读取结构以 manifest `physical_type` 和下表为准，不等同于写记录时的 CellValue；`lark-base-cell-value.md` 在读写形态不一致的类型下提供对照说明。formula 和 lookup 在当前 NDJSON 中统一为字符串，不保留计算结果的原始类型。
+- 将 `physical_type` 和上述 CellValue 结构视为输入契约；一次性分析代码直接读取，不再逐格验证 `record_id`、数组或 struct 的运行时形状。
+- 未显式指定 sort 时不保证行顺序。
+
+### Physical type 快速参考
+
+| `field_type` | `physical_type` | 示例与语义 |
+| --- | --- | --- |
+| 系统 `record_id` | `string` | `"rec_xxx"`；系统主键 |
+| `text`、`formula`、`lookup`、`auto_number`、`not_support` | `string|null` | `"进行中"`；formula、lookup 不保留结果的原始类型 |
+| `datetime`、`created_at`、`updated_at` | `string|null` | `"2026-08-05T10:30:00.000+08:00"`；RFC3339，固定三位毫秒 |
+| `number` | `number|null` | `12.5`；JSON 整数和小数均为 number |
+| `checkbox` | `boolean` | `true`；上游空值已规范化为 `false` |
+| `select` | `array<string>` | `["进行中", "高优"]`；单选、多选读取均为名称数组 |
+| `location` | `struct<lng number, lat number, full_address string>|null` | `{"lng":116.39,"lat":39.90,"full_address":"北京市"}`；非空 Location 的三个成员均非空 |
+| `user`、`group_chat`、`created_by`、`updated_by` | `array<struct<id string, name string>>` | `[{"id":"ou_xxx","name":"张三"}]` |
+| `link` | `array<struct<id string>>` | `[{"id":"rec_xxx"}]`；schema 的 `table_id` 指定目标表，`id` 是目标 `record_id` |
+| `attachment` | `array<struct<file_token string, size number, name string>>` | `[{"file_token":"box_xxx","size":1024,"name":"report.pdf"}]` |
 
-### 2.2 关键词检索后叠加结构化条件
+### 日期字段读取
 
-使用 `+record-search` 做关键词命中，结构化条件仍用 `--filter-json` 下推：
+日期字段以带 offset 的 RFC3339 字符串序列化，并有两种分析语义：
 
-```bash
-lark-cli base +record-search \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --keyword Alice \
-  --search-field Name \
-  --filter-json '{"logic":"and","conditions":[["Status","!=","Done"]]}' \
-  --sort-json '[{"field":"Updated","desc":true}]' \
-  --field-id Name \
-  --field-id Status \
-  --limit 20
-```
+- **instant semantics**：计算真实时长、先后顺序或跨时区比较时，解析完整 RFC3339 值，以其表示的绝对时刻计算。
+- **local-calendar semantics**：按来源 Base 的日、周、月等本地日历分组时，使用序列化值中的本地日期，不先转 UTC，也不按 manifest `timezone` 重复换算。
 
-不要把 `+record-search` 当成金额、状态、日期、空值、关联字段的结构化筛选入口；这些条件继续写成 `--filter-json`。
+例如，`2026-03-20T23:30:00.000-05:00` 与 `2026-03-21T12:30:00.000+08:00` 表示同一时刻；前者若是来源 Base 的值，本地日报归入 3 月 20 日，而时长或排序计算应把它解析为绝对时刻。只构造任务实际需要的日期表示，并在分析引擎中使用具备 datetime 功能的列。
 
-### 2.3 聚合分析与 TopN
+## 读取与关系建模
 
-使用 `+data-query`：
+仅在 SOP 已选择 Python 路径后，按实际实现方式只读一份示例：
 
-- 让 Base 云端查询服务完成 filters、dimensions、measures、sort、pagination.limit。
-- `pagination.limit` 是 Base 云端查询服务中的结果限制，不是本地分页扫描。
-- 常用聚合 fewshot 先读 [lark-base-data-query-guide.md](lark-base-data-query-guide.md)；字段类型、日期 value、DSL shape 以 [lark-base-data-query.md](lark-base-data-query.md) 为准。
-- `+data-query` 可返回聚合结果或维度字段行；维度字段行按字段组合去重且不返回 `record_id`，不能当逐条原始记录结果使用。
-- 需要输出逐条记录、记录定位或完整行级字段时，先用 `+data-query` 得到业务 key、分组值或候选字段组合，再用 `+record-list --filter-json` / `+record-get` 回查。
+- [Python 标准库示例](lark-base-data-analysis-python-stdlib.md)
+- [pandas 示例](lark-base-data-analysis-pandas.md)
 
-Example: 分组计数：
+两份示例使用相同的五类场景：加载与日期解析、集合谓词、单数组展开、Link JOIN、多数组共现。场景语义和粒度规则以本 SOP 为准，示例只提供对应实现的最短代码。
 
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Status","alias":"status"}],"measures":[{"field_name":"Status","aggregation":"count","alias":"count"}],"shaper":{"format":"flat"}}'
-```
+标准库足以清晰表达任务时直接使用；DataFrame 能明显简化计算时再选 pandas。已选择 pandas 但环境未安装时，网络可用且存在 `uv` 或 `pip` 才按需安装，优先使用 `uv run --no-project --with pandas python analyze.py`。
 
-Example: 过滤后汇总并取 TopN：
+将 Base 反范式宽表映射为关系模型时，可将标量列视为 record attributes，将多值列视为以 `record_id` 为关联键的 nested relation，将 Link 视为跨表 adjacency list。多值列通过 lateral `explode` / `UNNEST` 切换粒度；Link 规范化为 bridge relation 后再 `merge` / `join` / `JOIN`；同类来源表先投影到 conformed fact schema，再用 `concat` / `UNION ALL` 纵向合并。
 
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Owner","alias":"owner"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"filters":{"type":1,"conjunction":"and","conditions":[{"field_name":"Status","operator":"is","value":["Done"]}]},"sort":[{"field_name":"total_amount","order":"desc"}],"pagination":{"limit":10},"shaper":{"format":"flat"}}'
-```
+## 常见分析模式
 
-### 2.4 视图化与复用
+### 单表简单筛选与统计：jq
 
-一次性查询先用 `+record-list` / `+record-search` 的 filter/sort 验证。需要用户长期打开、共享或复用时，再把同一套 filter/sort 沉淀为视图。
+NDJSON 每行是一条 record。单表短筛选、计数和简单聚合可直接用 jq；下面筛选“状态”包含“进行中”的记录，并统计记录数和金额合计：
 
-Example: 将已验证的筛选排序写入视图：
+默认导出后使用本地 `jq -s`，同一 artifact 可反复查询而无需重新下载。表达式很短且只执行一次，或本地 jq 不可用时，可改用 `--jq-records '<expr>'` 等价 `jq -s '<expr>' records.ndjson`。使用 CLI 内置 jq 处理 NDJSON 记录时必须使用 `--jq-records`；通用 `--jq` 不支持 ndjson。
 
 ```bash
-lark-cli base +view-set-filter \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --view-id <view_id> \
-  --json @filter.json
-
-lark-cli base +view-set-sort \
+lark-cli base +record-list \
   --base-token <base_token> \
   --table-id <table_id> \
-  --view-id <view_id> \
-  --json '{"sort_config":[{"field":"Priority","desc":true}]}'
+  --field-id 状态 \
+  --field-id 金额 \
+  --output records.ndjson \
+  --minimal-stdout &&
+jq -s '
+  map(select((.["状态"] | index("进行中")) != null)) as $records
+  | ($records | map(.["金额"] | select(. != null))) as $amounts
+  | {
+      records_count: ($records | length),
+      amount_sum: (
+        if ($amounts | length) > 0 then ($amounts | add) else null end
+      )
+    }
+' records.ndjson
 ```
 
-手动配置和视图配置的优先级：
-
-1. `--filter-json` 覆盖 `--view-id` 保存的 view filter JSON。
-2. `--sort-json` 覆盖 `--view-id` 保存的 view sort config。
-3. 没有手动 filter/sort 时，`--view-id` 使用视图自身保存的 filter/sort。
+### 多值列：nested relation 与目标粒度
 
-### 2.5 关系查询与回查
+Base 的反范式宽表会把零到多个 Select、人员、群组、Link 或附件元素嵌入一条 source record。多值单元格默认按无重复、无序集合建模：元素顺序不承担稳定业务语义，同一 source record 内可将元素视为唯一，因此其元素数等于去重元素数；跨 source record 出现的同一元素仍是不同事实或关系边。分析时将数组视为以 `record_id` 为 correlation key 的 nested relation，并先确定 target grain：
 
-- link 单元格通常是关联表 `record_id` 数组，不是用户可读内容，只是连接键。
-- 先用 `+field-list` 确认 link 字段的 `link_table`、业务唯一键和展示字段。
-- 从驱动表拿到候选记录后，用关联 `record_id` 到关联表 `+record-get` 批量读取记录内容。
-- 多跳关系逐跳建立 `record_id/key -> 用户可读字段` 映射；最终用户可读的信息。
+- **record grain**：包含、交集、子集和元素数量等问题直接使用集合谓词，不做 expansion。
+- **record-element grain**：通过 lateral `explode` / `UNNEST` 规范化为 `(source_record_id, element)` bridge relation。inner expansion 会丢弃空数组来源，outer expansion 会保留来源 record；回到 record 口径时按 `source_record_id` 聚合或去重。
+- **entity grain**：两侧分别规范化为 bridge relation，再按稳定 element key JOIN。人员和群组以 `id` 连接、以 `name` 展示；Select 以名称作为元素键，仅当字段共享同一业务值域时才可连接。
 
-禁止：
+使用列 `stats` 中的 `empty_count`、`avg_length` 和 `max_length` 做 expansion cardinality 与数据倾斜预估：单数组 inner expansion 的估算行数为 `records_count × avg_length`，outer expansion 还需加上 `empty_count`；结合 `max_length` 识别极端 fan-out 或 hot record。任务确实需要元素粒度且估算规模可控时，可以直接展开。
 
-- 把 link `record_id` 当最终输出。
-- 用 `+record-search` 搜 link `record_id`。
-- 基于 ID、自增编号、link 值做语义猜测；禁止依赖字段先验、样本记忆补全交付输出。
+#### 多数组、fan-out 与 row-local Cartesian product
 
-## 3. Range & Pagination Contract
+同一 source record 中的独立数组默认建立为彼此独立的 lateral pipeline，分别展开并聚合回 target grain 后再连接，避免 many-to-many fan-out 和重复计量。只有问题明确要求分析元素组合或共现时，才同时展开形成 row-local Cartesian product。
 
-- `+record-list` 默认页、固定 `--limit`、本地 `jq`、shell 管道、手工浏览输出，都只覆盖已读取范围；超过 200 行不要把本地处理当作推荐路径。
-- `has_more=true`、存在下一页 offset/page token、或返回行数等于 page size，都表示可能还有未读取数据。
-- 对全局问题，只有 Base 云端查询服务已经通过 filter/sort/aggregate 收敛目标范围，或 `+data-query` 已在云端完成聚合、排序和限制时，才可以用有限返回形成结论。
-- 必须全量导出时，按 `+record-list` 分页语义串行翻页；不要并发调用 `+record-list`。
+两个数组同时展开的准确 cardinality 为 `Σᵢ(|Aᵢ| × |Bᵢ|)`；可用 `records_count × avg_length_a × avg_length_b` 估算执行规模，并结合两列的 `max_length` 判断极端 fan-out。平均长度乘积不反映列间相关性，只用于成本估算。Base schema 不提供不同多值列之间的 positional contract；仅当额外业务契约明确声明位置对应语义时，才按 ordinality ZIP。
 
-## 4. Final Answer Check
+### Link：跨表 adjacency list
 
-形成交付输出前必须能确认：
+- Link 字段的完整 schema 以 `+field-list` 为准，其中 `table_id` 声明唯一目标 table；NDJSON 的 `[{"id":"rec_xxx"}]` 表示指向该表目标 `record_id` 的零到多条有向边。以 `table_id` 确定目标表，缺少可信 schema 时先补充 `+field-list`。
+- 将 Link 规范化为 `(source_record_id, target_record_id)` edge/bridge relation，再按 `target_record_id = 目标表.record_id` 执行外键式 JOIN。需要反向遍历时复用同一 edge relation 反向分组或连接；NDJSON 不隐含自动反向关系。
+- 多跳 Link 通过逐跳组合 edge relation 完成 traversal，并始终在各自 record-id domain 内连接。最终展示目标表的用户可读 attributes；已有 Link 时使用 Link edge relation，其他关联使用经过验证的 business key。
 
-- 问题范围是局部样例、单点定位、全局原始记录、聚合分析、多表关联，还是查询后写入。
-- 筛选、排序、聚合是否发生在 Base 云端查询服务中，而不是本地 `jq` / shell 中。
-- 如果使用 `jq` / shell，本地输入是否是 200 行以内的小范围结果；超过 200 行是否已改用 Base 云端查询服务查询。
-- 如果使用 `+record-list` / `+record-search`，是否处理了 `has_more`，且投影包含业务 key 和解释字段。
-- 如果涉及关系查询，是否按 `record_id` 或业务 key 精确回查，交付输出是否来自关联表真实字段。
-- 交付输出能追溯到表、字段、筛选条件、排序/聚合条件和连接键。
+### 跨表同类实体与指标
 
-任一项无法确认时，继续查询或明确说明只能得到局部结论。
+- 多表 users 等重复实体的事实分析，先把各表投影为 `(source_table, source_record_id, entity_id, metric...)` 的 conformed long fact schema，再 `UNION ALL` 并聚合到 entity grain。需要横向比较时，各表先聚合到相同 entity grain 再 JOIN，避免原始事实之间产生 many-to-many fan-out。
+- 没有 Link 时只能使用经过验证的 business key 关联。名称相似匹配属于 entity resolution，不属于普通 JOIN；应作为独立阶段输出匹配依据、置信度和未决项。

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

@@ -1,8 +1,6 @@
 # Base data-query guide
 
-This guide is the entry point for `+data-query`. Use it for common aggregation fewshots and command selection. For the complete DSL fields, operators, limits, and response details, use [lark-base-data-query.md](lark-base-data-query.md) as the DSL SSOT.
-
-Before using `+data-query`, also follow [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) to confirm that the task really needs aggregation instead of record listing or a temporary view.
+Read this guide after the [data analysis SOP](lark-base-data-analysis-sop.md) enters the Cloud path and selects `+data-query`, or directly when the user explicitly asks about the `+data-query` command or DSL. It provides common aggregation fewshots; use [lark-base-data-query.md](lark-base-data-query.md) only for complete DSL fields, operators, limits, response details, or error recovery.
 
 ## When to use
 

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

@@ -1,11 +1,9 @@
 
 # Base data-query DSL SSOT
 
-> **入口指南**: [lark-base-data-query-guide.md](lark-base-data-query-guide.md) | **前置条件**: 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+> **入口指南**: [lark-base-data-query-guide.md](lark-base-data-query-guide.md) | **认证或授权问题**: [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)
 
-本文档是 `+data-query` JSON DSL 的单一事实来源（SSOT），用于说明完整字段、操作符、限制、返回和错误恢复。常用 fewshot 与命令选择先读 [lark-base-data-query-guide.md](lark-base-data-query-guide.md)。
-
-查询类任务还必须先遵守 [`lark-base-data-analysis-sop.md`](lark-base-data-analysis-sop.md)。`+data-query` 适合让筛选、分组、聚合、排序和 TopN 在 Base 云端查询服务中执行；不要用默认分页的 `+record-list` 或本地 `jq` 替代聚合查询。
+本文档是 `+data-query` JSON DSL 的单一事实来源（SSOT），用于说明完整字段、操作符、限制、返回和错误恢复。数据表查询与分析先由 [data analysis SOP](lark-base-data-analysis-sop.md) 选路；Cloud SOP 选定 `+data-query` 后先读 [data-query guide](lark-base-data-query-guide.md)，guide 未覆盖需求或用户明确要求完整 DSL/API reference 时再读本文。
 
 ## 限制
 
@@ -432,12 +430,12 @@ CLI 输出标准信封 `{ok, identity, data}`（失败时为 `{ok:false, identit
 
 1. 用 `+data-query` 在 Base 云端查询服务中完成全局筛选、分组、聚合、排序和 TopN，得到业务 key、分组值或候选字段组合。
 2. 如果已经拿到候选记录的 `record_id`，用 `+record-get` 读取逐条记录字段。
-3. 如果拿到的是结构化业务 key（例如编号、状态、日期、金额等），用 `+record-list --filter-json` 做精确过滤后读取；不要用 `+record-search` 代替结构化条件。
+3. 如果拿到的是结构化业务 key（例如编号、状态、日期、金额等），用 `+record-list --filter-json` 做精确过滤后读取；`+record-search` 用于文本展示值关键词。
 4. 只有候选条件本身是文本展示值关键词时，才使用 `+record-search`，并用 `search_fields` 限定范围、`select_fields` 做投影。
 5. 若候选记录包含 link 字段，提取关联 `record_id` 后到关联表用 `+record-get` 批量读取展示字段。
-6. 最终回答业务字段，不要把内部 `record_id` 当作用户可读答案。
+6. 最终回答展示真实业务字段；内部 `record_id` 用于连接或定位。
 
-不要把 `data-query pagination.limit` 理解为分页扫描；它只限制 Base 云端查询服务返回的聚合结果行数，不支持 offset。需要全量原始记录导出时回到 data analysis SOP 的 `+record-list` 分页规则。
+不要把 `data-query pagination.limit` 理解为分页扫描；它只限制 Base 云端查询服务返回的聚合结果行数，不支持 offset。需要逐条原始记录时按 Cloud SOP 的 `+record-list` / `+record-search` 回查规则处理。
 
 ## 坑点
 
@@ -450,12 +448,11 @@ CLI 输出标准信封 `{ok, identity, data}`（失败时为 `{ok:false, identit
 - ⚠️ **数据表标识 `tableId` vs `tableName`**：datasource 中可以用 `tableId`（如 `tblXXX`）或 `tableName`（数据表的用户自定义显示名称），二选一，不要混用
 - ⚠️ **`pagination.limit` 最大 5000**：超过会报错，且不支持 offset，只支持 limit
 - ⚠️ **所有 alias 必须全局唯一**：dimensions 和 measures 之间的 alias 也不能重名
-- ⚠️ **不要用本地分页结果替代 data-query**：凡是全局计数、分组、聚合、排序 TopN，优先让 `+data-query` 在 Base 云端查询服务中执行；默认页 `+record-list` 后本地统计只能得到已读取范围内的结果
 
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
-- [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) — 查询范围、选路、下推、分页、`+record-list` / `+record-search` 回查和关系查询 SOP
+- [lark-base-data-analysis-cloud.md](lark-base-data-analysis-cloud.md) — Cloud 路径的查询范围、下推、分页、`+record-list` / `+record-search` 回查和关系查询 SOP
 - [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
 - [lark-base-field-json.md](lark-base-field-json.md) — 字段类型与 JSON 结构

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

@@ -264,7 +264,7 @@
 {
   "type": "datetime",
   "name": "截止时间",
-  "default_value": "2026-03-24 10:00:00"
+  "default_value": "2026-03-24 10:00"
 }
 ```
 
@@ -272,7 +272,7 @@
 
 默认值 / 约束：
 - `style.format` 默认 `yyyy/MM/dd` 可用格式：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`yyyy/MM/dd HH:mm Z`、`yyyy-MM-dd`、`yyyy-MM-dd HH:mm`、`yyyy-MM-dd HH:mm Z`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy`
-- `style.format` 只控制前端显示格式；当前可配置格式最多显示到分钟，底层时间值仍可保留秒级精度。
+- `style.format` 只控制 Base 前端展示，不影响 CLI 读取的 CellValue；前端当前最多配置到分钟级展示，底层时间值以毫秒级精度存储。
 
 常用写法：
 

package/skills/lark-base/references/lark-base-record-upsert.md

@@ -13,7 +13,7 @@ lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> \
 
 # 更新记录
 lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --record-id <record_id> \
-  --json '{"项目名称":"Apollo","状态":"完成","完成时间":"2026-03-24 10:00:00"}'
+  --json '{"项目名称":"Apollo","状态":"完成","完成时间":"2026-03-24 10:00"}'
 ```
 
 ## 参数
@@ -42,7 +42,7 @@ lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --r
 {
   "项目名称": "Apollo",
   "状态": "进行中",
-  "完成时间": "2026-03-24 10:00:00"
+  "完成时间": "2026-03-24 10:00"
 }
 ```
 

package/skills/lark-calendar/SKILL.md

@@ -21,6 +21,8 @@ metadata:
 - 查看/管理登录用户本人的日程 → `--as user`（默认，绝大多数场景）。
 - 查看/管理 bot 自己创建/拥有的日程 → `--as bot` 
 
+**对话人称映射**：「我」= 登录用户，「你」= 应用（bot）；作为字段取值的人称（参会人、会议 owner 等）不参与身份判定，如「你创建日程，邀请我、会议 owner 为我」→ `--as bot` 创建，登录用户仅作参会人与会议 owner。
+
 ```bash
 # 用户本人日程 → user
 lark-cli calendar +agenda --as user

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

@@ -61,6 +61,7 @@ lark-cli calendar event.attendees create \
   --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
 
 完整 API 命令的关键差异：
+- `+create` 在传入 `--attendee-ids`（即需要邀请其他参会人）时，会自动把当前身份一并加进参会人，但 `calendar events create` / `calendar event.attendees create` 等完整 API **不会**自动加。需自行把调用身份的 open_id 以 `type:user` 写入 attendees，与邀请的其他参会人合并去重后添加。open_id 用 `lark-cli auth status --json --verify` 获取：bot 取 `identities.bot.openId`（`--verify` 才会填充），user 取 `identities.user.openId`。
 - 时间参数是 **Unix 秒字符串**（非 ISO 8601）。换算时**禁止依赖容器默认时区**（常为 UTC，会导致 8 小时偏移），必须显式指定目标时区。
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
 - 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。

package/skills/lark-doc/SKILL.md

@@ -14,7 +14,7 @@ metadata:
 
 **CRITICAL：先判断场景，再读取该场景的参考文件；不要在任务开始时一次性读取全部参考文件。每个文件只在首次进入对应阶段时读取一次。**
 
-**身份：文档操作推荐显式指定 `--as user`。**
+**身份：文档操作推荐显式指定 `--as user`。例外：如果 `doc_token` / `note_doc_token` 等是从 bot 链路（如 `vc +detail --as bot` → `note +detail --as bot`）取得的，应继续显式使用 `--as bot`，不要无条件切回 user——身份延续规则见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。**
 
 **所有表示本地文件的 `@path` 均使用 `@./xxx` 形式的相对路径，并以运行 `lark-cli` 时的当前工作目录（CWD）为基准。**
 

package/skills/lark-drive/SKILL.md

@@ -21,17 +21,18 @@ metadata:
 ## 快速决策
 
 - 用户要把**已有 Wiki 节点移出知识库，放到 Drive 文件夹或“我的空间”根目录**：切到 `lark-wiki`，使用 `lark-cli wiki +move-to-drive`；不要把 Wiki token 直接交给 `drive +move`。这是会改变文档归属和权限继承的写操作，执行前确认源节点与目标位置。
-- 用户要**复制文档 / 创建副本 到云盘或者文件夹**时，使用 `lark-cli drive +copy`，用法见 [`references/lark-drive-copy.md`](references/lark-drive-copy.md)。如果是要复制文档 / 创建副本到知识库，使用 `wiki +node-copy`（见 [`lark-wiki-node-copy.md`](../lark-wiki/references/lark-wiki-node-copy.md)）。
+- 用户要**复制文档 / 创建副本 到云盘或者文件夹**时：已提供可直接使用的 URL 或 token，按 [`references/lark-drive-copy.md`](references/lark-drive-copy.md) 使用 `lark-cli drive +copy`；仅提供标题时，先按 [`references/lark-drive-search.md`](references/lark-drive-search.md) 使用 `drive +search` 唯一定位源资源，再按 copy reference 复制。如果是要复制文档 / 创建副本到知识库，使用 `wiki +node-copy`（见 [`lark-wiki-node-copy.md`](../lark-wiki/references/lark-wiki-node-copy.md)）。
 - 用户要**识别飞书 / doubao 云空间 URL 的类型和 token**时，可以先按 URL 路径形态做轻量判断；当路径已明确指向 docx / sheet / bitable / slides / file / folder 等资源时，可直接提取对应 token/type。传入 wiki URL、需要识别标题或 canonical URL、URL/token 有歧义，或后续操作依赖底层真实资源时，再使用 `lark-cli drive +inspect --url '<url>'` 进行识别；具体用法、失败处理和边界见 [`references/lark-drive-inspect.md`](references/lark-drive-inspect.md)。
 - 高风险写操作（删除、公开权限修改、owner 转移、版本删除/回滚、批量移动/覆盖/同步）必须同时满足三个条件才执行：目标已解析为该操作可直接使用的执行对象，执行细节已明确到可直接调用命令（例如删除的 file-token/type、公开权限修改的共享范围、owner 转移的目标 owner、版本删除/回滚的 version id、移动/覆盖/同步的目标位置和冲突策略），且用户在本轮明确确认执行这些具体目标和执行细节。用户只说“删除没用的文件”“开放/共享给大家”“改成开放”“覆盖/移动这些”只表示目标状态；先只读发现并列出候选、权限档位或执行方案，停止等待用户确认。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要”权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
+- 用户明确要**移除单个云文档协作者权限**时，使用 `lark-cli drive +member-remove`；先阅读 [`references/lark-drive-member-remove.md`](references/lark-drive-member-remove.md)。这是高风险写操作，真实执行必须确认准确的资源、成员 ID/type 和 wiki 权限范围，并显式传 `--yes`。
 - 用户要为指定飞书文档**设置 / 修改密级标签（secure label）**，或查询当前用户可用的密级标签，直接读取 [`references/lark-drive-secure-label.md`](references/lark-drive-secure-label.md)；这是 Drive 文件治理能力。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户要**查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置**，优先使用 `lark-cli drive +permission-get-setting`；它只读取目标自身设置，不递归审计文件夹子文档权限。裸 token 必须显式传 `--type`。
 - 用户要**按特定主题、关键词或内容线索跨容器查找资料，并统一收集到 Drive 文件夹或 Wiki 节点**，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`topic_move_collector`](references/lark-drive-workflow-topic-move-collector.md) workflow。该 workflow 负责搜索召回、内容验证、相关性分类、移动计划、写前确认和结果验证；禁止直接从 `drive +search` 或 `drive +move` 开始。
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`knowledge_organize`](references/lark-drive-workflow-knowledge-organize.md) workflow。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 按主题跨范围查找并集中归档，进入 `topic_move_collector`；对已知文件夹、文档库或知识库做目录盘点和结构重组，进入 `knowledge_organize`；只移动一个已明确资源时仍使用原子移动命令。
-- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
+- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`；按标题定位和处理重复候选时遵循 [`references/lark-drive-search.md`](references/lark-drive-search.md)。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
 - 用户要对**文档评论**做任何操作（添加评论、列表 / 批量查询、回复、获取 / 更新 / 删除回复、解决 / 恢复、reaction），按下方 Shortcuts 表选择对应的 `drive +<verb>` 评论命令，执行前先阅读该命令的 ref。按评论定位文档正文位置见 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md)。
 - 用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，仍按资源类型、URL 路径和 token 路由到本 skill；不要因为域名不是飞书而回退到 WebFetch。
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
@@ -154,6 +155,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+apply-permission`](references/lark-drive-apply-permission.md) | 以 user 身份向文档 owner 申请访问权限。 |
 | [`+member-add`](references/lark-drive-member-add.md) | 添加一个或最多 10 个 Drive 文档、文件、文件夹或 wiki 节点协作者/授权成员；封装 Drive permission member create/batch_create，真实写入需要 `--yes`。 |
 | [`+member-list`](references/lark-drive-member-list.md) | 查询 Drive 文档、文件、文件夹或 wiki 节点的协作者/授权成员列表。 |
+| [`+member-remove`](references/lark-drive-member-remove.md) | 移除一个 Drive 文档、文件、文件夹或 wiki 节点协作者；封装 Drive permission member delete，真实写入需要 `--yes`。 |
 | [`+permission-get-setting`](references/lark-drive-permission-get-setting.md) | 查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置；支持 URL 或裸 token + `--type`；不递归读取文件夹子文档权限。 |
 | [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签。 |
 | [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档的密级标签。 |

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

@@ -147,6 +147,7 @@ lark-cli drive +export \
 | `1069914` | token 非法或 token/type 不匹配；常见原因是把 Wiki node token 当作底层 `docx` / `sheet` / `bitable` token 使用，没有传 `--doc-type wiki` | 优先改用 `--url <Wiki URL>`；只有裸 Wiki token 时，用 `--token <WIKI_NODE_TOKEN> --doc-type wiki`。不确定 token 类型时，先用 `lark-cli drive +inspect --url <TOKEN> --type wiki` 检查是否能解包为 Wiki node；如果不是 Wiki token，再检查 token 来源、`--doc-type` 是否与实际资源类型一致 |
 | `1069902` | 没有当前导出任务所需权限 | 不要直接重试同一命令；先确认当前 `--as` 身份是否能访问该文档、是否有下载/导出权限，以及文档是否受分享、密级或租户策略限制。需要补权限时，让文档 owner 或管理员授权后再执行 |
 | `99991400` / `rate_limit` | OpenAPI 请求频率受限 | 立即停止并按错误 `hint` 处理：没有 `ticket` 时，至少等待 1 分钟后重跑原 `drive +export`；已有 `ticket` 时，只执行 `drive +task_result --scenario export` 续查，不要重复创建任务。持续限频时从 1 分钟开始指数退避 |
+| `9499` + `too many request(s)` | 导出任务接口的另一种限频响应；同一个 `9499` 在其它 Drive 接口也可能表示参数类型错误，CLI 会结合服务端消息区分 | 按 `rate_limit` 处理：立即停止，等待至少 1 分钟并指数退避；已有 `ticket` 时只续查该任务，不要重新创建 |
 | `99991679` | 缺少 OpenAPI scope | 按错误 envelope 中的 `missing_scopes` / `required_scope` / `hint` 补齐授权；常见方式是重新执行 `lark-cli auth login --scope "<缺失 scope>"`。补 scope 前不要反复重试导出命令 |
 
 ## 推荐续跑方式