@amaster.ai/pi-lark 0.1.8 → 0.1.9

package/skills/lark-base/references/lark-base-filter-condition.md

@@ -10,7 +10,7 @@ Filter 是一组「字段/操作符/值」条件的组合，用 `logic`（`and`
 - `+record-list --filter-json` / `+record-search --filter-json` 的结构化记录筛选。
 - `+form-questions-create` / `+form-questions-update` 中的 `visible_rule` 显隐条件。
 
-本协议**不适用于 `+data-query`**。`+data-query` 支持过滤，但使用的是 LiteQuery DSL 的 `filters` 对象结构：`{"type":1,"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["有效"]}]}`，不是这里的 tuple 条件 `["状态","==","有效"]`。构造 `+data-query --dsl` 时请阅读 [lark-base-data-query.md](lark-base-data-query.md) 的 FilterGroup / Condition 章节。
+本协议**不适用于 `+data-query`**。`+data-query` 支持过滤，但使用的是 LiteQuery DSL 的 `filters` 对象结构：`{"type":1,"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["有效"]}]}`，不是这里的 tuple 条件 `["状态","==","有效"]`。需要聚合查询时先返回 [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) 选路；SOP 选定 `+data-query` 后再读取 guide 和完整 DSL reference。
 
 ## 1. 顶层结构
 
@@ -60,12 +60,16 @@ value 类型取决于条件引用对象（字段 / 题目）的类型。
 
 ### `text`
 
-用字符串：
+用字符串；高频的片段包含 / 排除使用 `intersects` / `disjoint`，完整文本比较使用 `==` / `!=`：
 
 ```json
 ["标题", "intersects", "发布"]
 ```
 
+```json
+["标题", "disjoint", "内部"]
+```
+
 ### `location`
 
 location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
@@ -74,8 +78,6 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 ["位置", "intersects", "深圳"]
 ```
 
-不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
-
 ### `number` / `auto_number`
 
 用数字：
@@ -86,27 +88,27 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 
 ### `select`
 
-用选项名数组：
+用选项名数组；`intersects` 表示命中任意选项，`disjoint` 表示不包含其中任何选项：
 
 ```json
 ["状态", "intersects", ["Doing", "Blocked"]]
 ```
 
-### `user` / `created_by` / `updated_by`
+```json
+["状态", "disjoint", ["Archived"]]
+```
 
-用对象数组：
+### `user` / `group_chat` / `created_by` / `updated_by`
 
-> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
+用对象数组；人员使用 `ou_xxx`，群组使用 `oc_xxx`。不知道 ID 时，人员用 `lark-contact` 查询，群组用 `lark-im` 搜索。
 
 ```json
 ["负责人", "intersects", [{ "id": "ou_xxx" }]]
 ```
 
-### `group_chat`
-
-用对象数组：
-
-> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
+```json
+["负责人", "disjoint", [{ "id": "ou_xxx" }]]
+```
 
 ```json
 ["负责群", "intersects", [{ "id": "oc_xxx" }]]
@@ -151,29 +153,15 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 
 ### `formula` / `lookup`
 
-- 筛选值类型由字段计算结果类型动态决定。
-- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
-- 如果报错，再按错误提示把 `value` 改成对应类型。
-
-字符串示例：
-
-```json
-["风险说明", "intersects", "高风险"]
-```
-
-数字示例：
-
-```json
-["汇总分", ">=", 80]
-```
+value schema 随计算结果类型变化；拿不准时先读取字段定义，或根据错误提示修正 value 和 operator。
 
 ## 4. 易错点
 
 - 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
 - `user` / `group_chat` / `link` 不要写成单个标量。
-- `empty` / `non_empty` 不要硬塞无意义的 value。
+- `empty` / `non_empty` 统一表示格子为空 / 非空，不要传 value；标量空格子和多值字段没有任何元素都属于空。
 - 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
-- `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前配置或字段定义，或根据错误提示修正类型。
+- `formula` / `lookup` 的 value schema 是动态的；拿不准 value 类型时先读字段定义，或根据错误提示修正类型。
 
 ## 5. 参考
-- [lookup-field-guide.md](lookup-field-guide.md)
+- [Lookup Field](lark-base-field-lookup.md)

package/skills/lark-base/references/lark-base-record-batch-create.md

@@ -51,7 +51,11 @@ lark-cli base +record-batch-create --base-token <base_token> --table-id <table_i
 ## 坑点
 
 - 每个 `create_records` 元素都是独立的记录字段对象，只提交该记录需要写入的字段。
-- 单次最多 200 条，超出需分批写入。
+- 单次最多 200 条；`1254104` 表示超过单批上限，拆成多个批次。
+- `1254045` 表示字段不存在，重新 `+field-list` 后使用真实字段名或 `field_id`。
+- `1254015` 表示 CellValue 类型不匹配，按真实 Field schema 和 CellValue 规范修正。
+- 返回 `ignored_fields` / `READONLY` 时，从普通 Record 写入中移除 Formula、Lookup、系统字段和自动编号等只读字段。
+- 同一 Table 连续批量写入使用串行执行；`1254291` 表示并发写冲突，短暂等待后重试当前批次。
 - `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
 
 ## 参考

package/skills/lark-base/references/lark-base-record-batch-update.md

@@ -45,9 +45,12 @@ lark-cli base +record-batch-update --base-token <base_token> --table-id <table_i
 
 ## 坑点
 
-- 单次最多更新 200 条记录，超过会被接口校验拒绝。
+- 单次最多更新 200 条记录；`1254104` 表示超过单批上限，拆成多个批次。
+- `1254045` 表示字段不存在，重新 `+field-list` 后使用真实字段名或 `field_id`。
+- `1254015` 表示 CellValue 类型不匹配，按真实 Field schema 和 CellValue 规范修正。
 - 命令不会自动做字段/行映射转换，传什么就发什么。
-- 如果字段映射包含只读字段，返回里可能出现 `ignored_fields`；这些字段不会被更新。
+- 如果字段映射包含只读字段，返回里可能出现 `ignored_fields` / `READONLY`；移除 Formula、Lookup、系统字段和自动编号等只读字段。
+- 同一 Table 连续批量写入使用串行执行；`1254291` 表示并发写冲突，短暂等待后重试当前批次。
 
 ## 参考
 

package/skills/lark-base/references/lark-base-record-query-and-analysis-cloud-sop.md

@@ -0,0 +1,145 @@
+# Base Record 查询与分析 Cloud SOP
+
+统一数据分析 SOP 将任务路由到 Cloud 时使用本 SOP。覆盖记录读取、筛选、排序、Top/Bottom N、聚合统计、分组聚合、多表关联和查询后写入前的目标定位。
+
+本文只管查询选路和正确性边界；先按下方 Intent -> Tool Path 选择原始记录查询或聚合查询，再读真实结构和现状：
+
+- 视图筛选: [lark-base-view-set-filter.md](lark-base-view-set-filter.md)
+- 记录读取: `+record-list` / `+record-search` / `+record-get`，先确认字段 ID、字段名、分页和投影范围
+
+## 0. 执行约定
+
+- “最高、最低、最新、最早、Top、Bottom、总数、全部、异常、最大、最小、最多、最少、优先级最高”等全局语义，在本路径中由 Base 云端查询服务完成筛选、排序或聚合。
+- 一次性原始记录查询优先用 `+record-list` / `+record-search` 的 filter/sort；聚合分析优先用 `+data-query`。
+- `+record-search` 用于关键词检索字段的展示文本；金额、状态、日期、空值、关联等结构化条件继续用 `--filter-json` 表达。
+- 不要依赖已有视图，除非用户明确指定该视图，或你已读取并验证其 filter/sort/projection 符合当前问题。
+- 内部 ID、`record_id`、关联记录 ID、open_id 和编码字段用于连接或定位；交付输出使用用户可读的真实字段值，用户明确要求 ID 时一并展示。
+- 每次读取必须做最小投影，并包含后续解释、回查或写入需要的业务 key。
+
+## 1. Intent -> Tool Path
+
+| 用户意图 | 首选路径 | 关键规则 |
+| --- | --- | --- |
+| 看几条、预览、示例 | `+record-list --limit N --field-id ...` | 保持局部语义 |
+| 已知 `record_id` | `+record-get` | 直接读取 |
+| 明确关键词 | `+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` | 读取 [data-query DSL reference](lark-base-data-query.md)，使用 filters/dimensions/measures/sort/limit |
+| 聚合后输出逐条记录 | `+data-query` 得到业务 key 或候选字段组合 -> `+record-list --filter-json` / `+record-get` 回查 | `+data-query` 维度行按字段组合去重且不返回 `record_id` |
+| 多表 / 多跳关联 | 以候选数最小的事实表为驱动表，沿业务 key 或 Link 逐跳回查 | 读出 Link 单元格的 `id`（目标表 `record_id`）后，到被关联表批量 `+record-get` 展示字段 |
+| 查询后写入 / 视图化 | 先用本 SOP 得到可复核的目标记录 id 集合 | 再进入记录写入或视图配置；高价值可复用查询可沉淀为持久视图 |
+
+## 2. Execution Patterns
+
+### 2.1 结构化原始记录与 TopN
+
+使用 `+record-list` 的 filter/sort 路径：
+
+1. `+field-list` 确认筛选字段、排序字段、展示字段、业务 key。
+2. 筛选使用 `--filter-json '<filter-json>'`。
+3. 排序用 `--sort-json`。
+4. `--field-id` 做最小投影，`--limit` 控制返回数量。
+
+Example: 结构化筛选 + TopN；示例展示文本包含、数字比较和 Select 集合相交三个常用谓词：
+
+```bash
+lark-cli base +record-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --filter-json '{"logic":"and","conditions":[["Title","intersects","Launch plan"],["Score",">=",80],["Status","intersects",["Doing"]]]}' \
+  --sort-json '[{"field":"Updated","desc":true}]' \
+  --field-id Name \
+  --field-id Title \
+  --field-id Score \
+  --limit 20
+```
+
+常用 `filter-json` condition fewshot 统一见 [Base Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md)；完整协议见 [Base Filter 条件结构](lark-base-filter-condition.md)。
+
+`--sort-json` 传排序数组，数组顺序就是优先级，`desc:true` 为降序，`desc:false` 为升序，最多 10 个排序条件。
+
+### 2.2 关键词检索后叠加结构化条件
+
+使用 `+record-search` 做关键词命中，结构化条件仍用 `--filter-json` 下推：
+
+```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","intersects",["Doing"]]]}' \
+  --sort-json '[{"field":"Updated","desc":true}]' \
+  --field-id Name \
+  --field-id Status \
+  --limit 20
+```
+
+金额、状态、日期、空值和关联字段等结构化条件使用 `--filter-json`；`+record-search` 处理展示文本关键词。
+
+### 2.3 聚合分析与 TopN
+
+使用 `+data-query`：
+
+- 让 Base 云端查询服务完成 filters、dimensions、measures、sort、pagination.limit。
+- `pagination.limit` 是 Base 云端查询服务中的结果限制，不是本地分页扫描。
+- 读取 [data-query DSL reference](lark-base-data-query.md) 中与当前查询有关的 fewshot、字段和协议。
+- `+data-query` 可返回聚合结果或维度字段行；维度字段行按字段组合去重且不返回 `record_id`，不能当逐条原始记录结果使用。
+- 需要输出逐条记录、记录定位或完整行级字段时，先用 `+data-query` 得到业务 key、分组值或候选字段组合，再用 `+record-list --filter-json` / `+record-get` 回查。
+
+Example: 分组计数：
+
+```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"}}'
+```
+
+Example: 汇总后取 TopN；需要过滤时按 `+data-query` 的 LiteQuery DSL reference 增加 `filters`：
+
+```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"}],"sort":[{"field_name":"total_amount","order":"desc"}],"pagination":{"limit":10},"shaper":{"format":"flat"}}'
+```
+
+### 2.4 视图化与复用
+
+一次性查询先用 `+record-list` / `+record-search` 的 filter/sort 验证。需要用户长期打开、共享或复用时，再把同一套 filter/sort 沉淀为视图。
+
+Example: 将已验证的筛选排序写入视图：
+
+```bash
+lark-cli base +view-set-filter \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --view-id <view_id> \
+  --json '{"logic":"and","conditions":[["Priority","intersects",["P0"]]]}'
+
+lark-cli base +view-set-sort \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --view-id <view_id> \
+  --json '{"sort_config":[{"field":"Priority","desc":true}]}'
+```
+
+手动配置和视图配置的优先级：
+
+1. `--filter-json` 覆盖 `--view-id` 保存的 view filter JSON。
+2. `--sort-json` 覆盖 `--view-id` 保存的 view sort config。
+3. 没有手动 filter/sort 时，`--view-id` 使用视图自身保存的 filter/sort。
+
+### 2.5 关系查询与回查
+
+- Link 单元格中的元素形如 `{"id":"rec_xxx"}`；`id` 是目标表的 `record_id`，用于关系连接。
+- 先用 `+field-list` 确认 link 字段的 `link_table`、业务唯一键和展示字段。
+- 从驱动表拿到候选记录后，用 Link 元素的 `id` 到目标表 `+record-get` 批量读取记录内容。
+- 多跳关系逐跳建立 `record_id/key -> 用户可读字段` 映射，交付目标表返回的真实业务字段。
+
+## 3. Range & Pagination Contract
+
+- `+record-list` 默认页、固定 `--limit` 和手工浏览输出都只覆盖已读取范围；模型上下文接收云端收敛后的最终小结果。
+- `has_more=true` 说明可能还有未读取数据，需要更新 offset 后继续读取，多次读取仍未读取完成时，采用其他方法完成任务需求，避免无限循环。
+- 对全局问题，只有 Base 云端查询服务已经通过 filter/sort/aggregate 收敛目标范围，或 `+data-query` 已在云端完成聚合、排序和限制时，才可以用有限返回形成结论。
+- 需要完整原始记录但云端能力无法把结果安全收敛到可返回范围时，明确说明能力边界；不要用手工分页、拆分下载或采样伪装成全局分析。

package/skills/lark-base/references/lark-base-record-query-and-analysis-sop.md

@@ -0,0 +1,233 @@
+# Base Record 查询、匹配与分析 SOP
+
+任何 Record 读取、预览、搜索、筛选、匹配、统计、聚合、TopN、多表或语义分析，以及写操作中的记录定位和结果验收，都先完整读取本 SOP。先区分需要 LLM 理解原文的语义分析与可程序化计算的确定性分析，再按数据规模与计算复杂度选择路径；即使用户直接要求解释、编写或排错 `+data-query` 命令或 DSL，也先由本 SOP 确认口径和路径，再读取底层 reference。
+
+## 分流决策
+
+1. 明确所有需要参与分析的表；上下文已有整表 `records_count` 时用于提前分流，否则直接按下文导出或探测，不为获取规模单独枚举表。
+2. 如果结论必须依赖 LLM 理解原始内容，例如开放文本打标、情绪或意图识别、主题归纳、语义分类、相似性判断或实体消歧，进入下文“LLM 语义分析”路径。
+3. 对于其余确定性查询，任一分析表已知超过 2000 行或 NDJSON 探测返回 `has_more=true` 时，先从任务意图中提取可在单表内独立执行的日期、状态、关键词等谓词，逐表下推后用 `--field-id '<一个简单标量字段>' --limit 2000 --format ndjson --output <probe>.ndjson --minimal-stdout` 复查。目标是每张表都达到 `has_more=false`；任一表无法压缩到 2000 行以内时，转 [Cloud SOP](lark-base-record-query-and-analysis-cloud-sop.md) 用云端的数据分析能力。
+4. 所有分析表都不超过 2000 行后：若只有一张表且短 jq 可清晰完成筛选、计数、简单分组/聚合/排序、TopN 可以使用 jq。
+5. 其余确定性任务比如多表、日历计算和复杂数据分析，在 Python 可用时使用 Python，否则进入 [Cloud SOP](lark-base-record-query-and-analysis-cloud-sop.md)。
+
+进入 Cloud 后先由 Cloud SOP 在原始记录查询与聚合查询之间选路；只有选定 `+data-query` 时才读取 [data-query DSL reference](lark-base-data-query.md)。
+
+## 执行与交付
+
+所有 records 读取统一使用 `--format ndjson --output <artifact>.ndjson`。NDJSON 将大记录集写入 records 文件，并在 stdout 返回包含摘要、列 schema 和 stats 的 manifest，避免把过长用户数据直接加载进模型上下文。用 Python 或数据分析引擎直接处理 records 文件。未传 `--limit` 时最多读取 2000 条；仅在探测、预览或用户明确要求前 N 条时缩小限制。
+
+### NDJSON 读取示例
+
+按任务替换真实 token、ID、投影、条件和 artifact 名称；`+record-search` 和 `+record-get` 使用相同的 NDJSON 输出参数。
+
+```bash
+lark-cli base +record-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <field> \
+  --format ndjson \
+  --output ./records.ndjson \
+  --as user
+```
+
+缩小大表记录范围时，展示文本关键词用 `+record-search`，日期、状态、数字、空值、选项、人员和关联等结构化条件用 `+record-list --filter-json`。
+
+### 单表谓词下推常用 example
+
+`+record-list` / `+record-search` 的 `--filter-json '<filter-json>'` 支持使用 tuple condition 下推单表谓词。以下示例用注释说明各条件的含义；实际传参时删除注释并使用标准 JSON：
+
+```jsonc
+{
+  "logic": "and", // 所有 conditions 同时成立；任意一个成立时使用 "or"
+  "conditions": [
+    ["标题", "==", "Launch plan"], // 文本全等
+    ["标题", "!=", "Archived plan"], // 文本不全等
+    ["标题", "intersects", "urgent"], // 文本包含目标片段
+    ["标题", "disjoint", "internal"], // 文本不包含目标片段
+    ["金额", ">=", 100], // 数字比较；支持 ==、!=、>、>=、<、<=
+    ["状态", "intersects", ["进行中", "暂停"]], // Select 集合相交：包含“进行中”或“暂停”任意一个选项
+    ["状态", "disjoint", ["已终止"]], // Select 集合无交集
+    ["已完成", "==", true], // Checkbox
+    ["负责人", "intersects", [{"id": "ou_xxx"}]], // 负责人包含某个人；intersects 表示包含数组中任意一个人员
+    ["负责人", "disjoint", [{"id": "ou_yyy"}]], // 负责人不包含指定人员中的任何一个
+    ["关联项目", "intersects", [{"id": "rec_xxx"}]], // 关联项目包含某个 record_id；intersects 表示包含数组中任意一条关联
+    ["备注", "non_empty"], // 格子非空；判断格子为空改用 ["备注", "empty"]
+    ["业务日期", "==", "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 日零点
+  ]
+}
+```
+
+全表分析的常规资源链路是 `+table-list` 确认目标表，并用已有整表 `records_count` 或 NDJSON `has_more` 确认规模；对所有参与分析的表并发执行 `+field-list` 读取所需 schema，再按上述 NDJSON 契约用 `+record-list` 导出记录。已有可信的 `table_id` 时可直接并发读取各表 `+field-list`。`+view-get` 可按需读取，作为用户持久化访问习惯的可选参考；其中的 filter、sort 与字段范围可辅助理解用户常用的查询范围和排序偏好，并结合当前任务确定最终口径。
+
+1. 每次读取使用任务所需的最小投影，并包含 JOIN、解释、回查或写入需要的业务 key。
+2. 全局结论以 `has_more=false` 的完整导出或 Cloud 聚合结果为依据；`has_more=true` 时继续收敛单表谓词或选择 Cloud 路径。
+3. 确定性分析选定一个分析引擎直接读取 NDJSON；模型上下文仅接收预览或最终小结果。
+4. Base 标量空值很常见；聚合前按用户口径确定空值是排除、按零计入还是进入分母。用户未指定且不同处理会实质改变结论时，说明空值数量、采用的口径及其影响；任务涉及业务键、展开、JOIN 或金额分摊时，同样明确目标粒度及与口径直接相关的重复或总量守恒。
+5. 最终结果保留真实表、查询范围和计算口径，展示用户可读字段；内部 ID 用于连接或定位。
+
+## 复用本轮 NDJSON
+
+Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否复用：
+
+1. 短时间内继续分析或表中数据低频变化时，谓词下推口径一致且已有列覆盖计算需求即可优先复用。
+2. 间隔较长或表中数据高频变化时，批量提取 manifests 的 `base_token/table_id/rev`，刷新相关表元数据并校验最新 `rev`；版本一致且谓词口径未变时复用，否则重新导出对应表。
+
+## LLM 语义分析
+
+先用任务中明确且不改变分析口径的确定性条件缩小数据范围；只有剩余判断必须依赖语义理解时，才将必要原文加载到模型上下文。
+
+开放文本打标、情绪或意图识别、主题归纳、语义分类、相似性判断和实体消歧等任务必须理解原文，最终判断由当前 LLM 在本地上下文中逐条完成。代码只用于确定性范围筛选、分批、结果持久化和最终汇总；除非用户明确要求规则法，不用关键词命中、词频、正则或规则打分替代语义判断。
+
+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。
+
+分析 artifact 使用相对路径输出到当前工作目录，例如 `--output ./records.ndjson`。
+
+```json
+{
+  "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": ["进行中"]
+    }
+  }
+}
+```
+
+- 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 直接读取文件。
+- `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"}]` |
+
+### 日期字段读取
+
+日期字段以带 offset 的 RFC3339 字符串序列化，并有两种分析语义：
+
+- **instant semantics**：计算真实时长、先后顺序或跨时区比较时，解析完整 RFC3339 值，以其表示的绝对时刻计算。
+- **local-calendar semantics**：按来源 Base 的日、周、月等本地日历分组时，使用序列化值中的本地日期，不先转 UTC，也不按 manifest `timezone` 重复换算。
+
+例如，`2026-03-20T23:30:00.000-05:00` 与 `2026-03-21T12:30:00.000+08:00` 表示同一时刻；前者若是来源 Base 的值，本地日报归入 3 月 20 日，而时长或排序计算应把它解析为绝对时刻。只构造任务实际需要的日期表示，并在分析引擎中使用具备 datetime 功能的列。
+
+## 读取与关系建模
+
+仅在 SOP 已选择 Python 路径后，按实际实现方式只读一份示例：
+
+- [Python 标准库示例](lark-base-data-analysis-python-stdlib.md)
+- [pandas 示例](lark-base-data-analysis-pandas.md)
+
+两份示例使用相同的五类场景：加载与日期解析、集合谓词、单数组展开、Link JOIN、多数组共现。场景语义和粒度规则以本 SOP 为准，示例只提供对应实现的最短代码。
+
+标准库足以清晰表达任务时直接使用；DataFrame 能明显简化计算时再选 pandas。已选择 pandas 但环境未安装时，网络可用且存在 `uv` 或 `pip` 才按需安装，优先使用 `uv run --no-project --with pandas python analyze.py`。
+
+将 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` 纵向合并。
+
+## 常见分析模式
+
+### 单表简单筛选与统计：jq
+
+NDJSON 每行是一条 record。单表短筛选、计数和简单聚合可直接用 jq；下面筛选“状态”包含“进行中”的记录，并统计记录数和金额合计：
+
+默认导出后使用本地 `jq -s`，同一 artifact 可反复查询而无需重新下载；本地 jq 不可用时，使用 Python 或其他数据分析引擎处理 records 文件。
+
+```bash
+lark-cli base +record-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id 状态 \
+  --field-id 金额 \
+  --format ndjson \
+  --output records.ndjson &&
+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
+```
+
+### 多值列：nested relation 与目标粒度
+
+Base 的反范式宽表会把零到多个 Select、人员、群组、Link 或附件元素嵌入一条 source record。多值单元格默认按无重复、无序集合建模：元素顺序不承担稳定业务语义，同一 source record 内可将元素视为唯一，因此其元素数等于去重元素数；跨 source record 出现的同一元素仍是不同事实或关系边。分析时将数组视为以 `record_id` 为 correlation key 的 nested relation，并先确定 target grain：
+
+- **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。任务确实需要元素粒度且估算规模可控时，可以直接展开。
+
+#### 多数组、fan-out 与 row-local Cartesian product
+
+同一 source record 中的独立数组默认建立为彼此独立的 lateral pipeline，分别展开并聚合回 target grain 后再连接，避免 many-to-many fan-out 和重复计量。只有问题明确要求分析元素组合或共现时，才同时展开形成 row-local Cartesian product。
+
+两个数组同时展开的准确 cardinality 为 `Σᵢ(|Aᵢ| × |Bᵢ|)`；可用 `records_count × avg_length_a × avg_length_b` 估算执行规模，并结合两列的 `max_length` 判断极端 fan-out。平均长度乘积不反映列间相关性，只用于成本估算。Base schema 不提供不同多值列之间的 positional contract；仅当额外业务契约明确声明位置对应语义时，才按 ordinality ZIP。
+
+### 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。
+
+### 跨表同类实体与指标
+
+- 多表 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/{role-config.md → lark-base-role-config.md}

@@ -1,6 +1,6 @@
-# Base role permission JSON SSOT
+# Base Role Permission Schema
 
-> **入口指南**: [lark-base-role-guide.md](lark-base-role-guide.md) | **相关命令**: `+role-create` · `+role-update` · `+role-get`
+> **模块入口**: [Advanced Permission 与 Role](lark-base-advanced-permission-and-role.md) | **相关命令**: `+role-create` · `+role-update` · `+role-get`
 
 本文档是角色权限 JSON（AdvPermBaseRoleConfig）的单一事实来源（SSOT），供 `+role-create` 和 `+role-update` 构造 `--json` 参数时参考。
 

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

@@ -62,4 +62,4 @@ lark-cli base +view-set-filter \
 ## 6. 参考
 
 - [lark-base-filter-condition.md](lark-base-filter-condition.md)：filter/visible_rule 条件结构公共协议 SSOT
-- [lookup-field-guide.md](lookup-field-guide.md)
+- [Lookup Field](lark-base-field-lookup.md)

package/skills/lark-base/references/lark-base-workflow-schema.md

@@ -3,7 +3,7 @@
 本文档是 Workflow `steps` JSON 的单一事实来源（SSOT），定义完整数据结构，适用于：
 - **查询场景**：理解 `+workflow-get` 返回的 `steps` 结构
 - **创建/修改场景**：构造 `+workflow-create` / `+workflow-update` 的 `--json` body
-> 💡 **本文档是纯字段参考**。如需**创建/修改**工作流的完整示例，请阅读 [workflow-guide.md](lark-base-workflow-guide.md)。
+> 💡 **本文档是纯字段参考**。如需**创建/修改**工作流的完整示例，请阅读 [Workflow](lark-base-workflow.md)。
 ---
 ## 📖 快速导航
 
@@ -1067,5 +1067,5 @@ $.{stepId}.{fieldId}.fileToken    → 文件 Token 列表（array<string>，仅
 
 ## 参考
 
-- [lark-base-workflow-guide.md](lark-base-workflow-guide.md) — 完整示例和构造技巧
+- [Workflow](lark-base-workflow.md) — 完整示例和构造技巧
 - 创建/更新时外层只承载 workflow 元信息，核心校验对象是 `steps`；列表只用于拿 workflow ID 和启停状态

package/skills/lark-base/references/{lark-base-workflow-guide.md → lark-base-workflow.md}

@@ -1,4 +1,4 @@
-# Workflow guide
+# Base Workflow
 
 本文档是 Workflow 的入口指南，帮助选择步骤组合、理解创建/更新边界，并引导到 steps JSON SSOT。
 

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

@@ -36,6 +36,7 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 | `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀。bot 可作为合法参会人，无需剔除 |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
 | `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。示例值："FREQ=DAILY;INTERVAL=1;UNTIL=<具体日期>" |
+| `--meeting-owner-id <ou_>` | 否 | 设置 VC 会议 owner。仅以应用（bot）身份在应用日历上操作时生效（需 `--as bot`）；owner 必须为本租户用户身份的 open_id（`ou_`） |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
 
 > 当用户表达'每周 X'、'每周重复'、'连续 N 周'时，必须使用 rrule 创建重复性日程，而非创建多个独立日程
@@ -49,7 +50,8 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 
 ## 高级用法（完整 API 命令）
 
-如需配置 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、参与人可选参加状态或全天日程等高级参数，请使用完整的 API 命令：
+> 优先策略：创建日程优先走 `+create`。遇到 `+create` 不支持的高级参数（如 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、参与人可选参加状态或全天日程等），**优先先用 `+create` 创建成功，再用完整 API update 对这些字段做编辑补齐**，而非整体改用完整 API 从零创建。
+
 **注意**：
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天。如果只有一天的话，开始日期和结束日期是相同。
 
@@ -60,11 +62,10 @@ lark-cli calendar event.attendees create \
   --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
   --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
 
-完整 API 命令的关键差异：
+完整 API 命令的关键差异和处理策略：
 - 时间参数是 **Unix 秒字符串**（非 ISO 8601）。换算时**禁止依赖容器默认时区**（常为 UTC，会导致 8 小时偏移），必须显式指定目标时区。
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
 - 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。
-- 设置会议 owner：`+create` 不支持，需用完整 API 命令在 `vchat.meeting_settings.owner_id` 中设置，且必须同时设置 `vchat.vc_type` 为 `vc`（代表该日程为 VC 视频会议）。仅当以应用（bot）身份在应用日历上操作时生效；owner 必须为用户身份（`ou_` open_id），不能为非用户或外部租户用户。
 
 ## 参会人类型
 

package/skills/lark-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-doc
-description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。文档评论走 lark-drive；表格或 Base 内部数据操作不在本 skill。"
+description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -33,7 +33,7 @@ metadata:
 ### 资源、画板与思维笔记
 
 - **插入本地素材 — [`+media-insert`](references/lark-doc-media-insert.md)**：在文末插入本地图片或文件。
-- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档中的图片、附件或素材。
+- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档或评论中的图片、附件或素材。
 - **下载素材 — [`+media-download`](references/lark-doc-media-download.md)**：下载文档中的图片、附件、素材或画板缩略图。
 - **Docx 封面 — [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md)**：下载、更新或删除 Docx 封面。
 - **画板 — [`画板工作流`](references/lark-doc-whiteboard.md)**：创建或更新画板时先读取工作流；更新已有画板必须复用现有 token，禁止新建空白画板；使用 [`whiteboard +update`](../lark-whiteboard/references/lark-whiteboard-update.md) 写入。
@@ -46,4 +46,4 @@ metadata:
 ## 不在本 Skill 范围
 
 - **Drive 文件级操作**：找文档、导入导出、云空间文件上传 / 下载 / 权限管理 → [`lark-drive`](../lark-drive/SKILL.md)。复制文档、创建副本或另存为副本时，按其指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文。
-- **文档评论**：添加、查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)。
+- **独立评论操作**：添加、分页查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)；只需紧凑评论上下文时，直接使用默认 JSON 响应的 `docs +fetch`。