@amaster.ai/pi-lark 0.1.9 → 0.1.11

package/skills/lark-base/references/lark-base-cell-value.md

@@ -1,165 +0,0 @@
-# base CellValue 规范（lark-base-cell-value）
-
-> 适用命令：`lark-cli base +record-batch-create`、`lark-cli base +record-batch-update`
-
-本文件定义 **shortcut 写记录** 时 `CellValue` 的推荐格式，目标是让 AI 一次写对。不同命令的外层 JSON 形状不同，但每个 cell 都以本文为 source of truth。
-
-## 1. 顶层规则（必须遵守）
-
-- `--json` 必须是 JSON 对象。
-- `+record-batch-create --json` 使用 `{"create_records":[{"字段名或字段ID": CellValue}, ...]}`，数组中的每个对象代表一条新 Record。
-- `+record-batch-update --json` 使用 `{"update_records":{"rec_xxx":{"字段名或字段ID": CellValue}, ...}}`，以 `record_id` 定位每条待更新 Record。
-- 一次 payload 里同一字段只用一种 key（字段名或字段 ID），不要重复。
-- 写入前先 `+field-list` 获取字段 `type/style/multiple`，再构造值。
-- 需要清空字段时优先传 `null`（字段允许清空时）。
-
-## 2. 各类型 CellValue
-
-### 2.1 text
-
-text 字段的 `style.type` 影响单元格检查逻辑：
-`type=plain` 传 Markdown 格式的字符串。
-`type=url` 传一个带 title 的 Markdown 格式链接，或单独传一个链接。
-`type=phone` 传合法电话号码。
-`type=email` 传合法邮箱字符串。
-
-```json
-{
-    "标题": "Hello, [lark-cli](https://github.com/larksuite/cli)",
-    "官网": "[官网](https://example.com)",
-    "联系电话": "1380000000000",
-    "邮箱": "owner@example.com"
-}
-```
-
-### 2.2 number
-
-用 JSON number，不要用带单位或千分位的字符串。货币、百分比、进度、评分等数字类字段也按数字写入，展示格式由字段配置决定。
-
-```json
-{
-    "工时": 12.5,
-    "预算": 3000,
-    "完成度": 0.65,
-    "评分": 4
-}
-```
-
-### 2.3 select（单选/多选）
-
-`select` 字段统一传选项名称数组。`multiple=false` 时数组只能包含一个元素，`multiple=true` 时可以包含多个元素。只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
-
-```json
-{
-    "单选": ["Todo"],
-    "多选": ["后端", "高优"]
-}
-```
-
-读取单元格时与写入的数据结构一致。
-
-### 2.4 datetime
-
-写入可省略时区偏移量，系统会按 Base 时区解析输入字符串；优先使用 `YYYY-MM-DD HH:mm`。Base 默认按分钟展示，但底层以毫秒级精度存储时间
-
-```json
-{
-    "截止时间": "2026-03-24 10:00"
-}
-```
-
-读取单元格时，日期时间输出为标准 RFC3339 字符串并固定保留三位毫秒，例如 `"2026-03-24T10:00:00.000+08:00"`。
-
-### 2.5 checkbox
-
-用 JSON boolean：`true` 或 `false`，不要用 `"true"`、`"是"`、`1`。
-
-```json
-{
-    "已完成": true
-}
-```
-
-### 2.6 user / group_chat
-
-`user` 和 `group_chat` 字段统一传对象数组。`multiple=false` 时数组只能包含一个元素，`multiple=true` 时可以包含多个元素。每个元素至少包含 `id`；人员字段传用户 ID（如 `ou_xxx`），群字段传群 ID（如 `oc_xxx`）。
-
-> **人员字段：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
-
-> **群组字段：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
-
-```json
-{
-    "负责人": [
-      { "id": "ou_xxx" },
-      { "id": "ou_xxx2" }
-    ],
-    "协作群": [
-      { "id": "oc_xxx" }
-    ]
-}
-```
-
-读取单元格时仍为对象数组，每个元素为 `{id, name}`，例如 `[{"id":"ou_xxx","name":"张三"}]`。
-
-### 2.7 link
-
-用对象数组，元素包含 `id`，值为目标记录的 `record_id`。不要传记录标题；先用 `+record-list` / `+record-search` 找到目标记录 ID。
-
-```json
-{
-    "关联任务": [
-      { "id": "<record_id>" }
-    ]
-}
-```
-
-读取单元格时与写入的数据结构一致。
-
-### 2.8 location
-
-- 读取：`{lng, lat, full_address}`，三个成员均非空。
-- 写入：`{lng, lat}`，经纬度均为数字；`full_address` 由平台根据坐标解析，不允许手动指定。
-- 筛选行为：按照 `full_address` 做字符串筛选，将 Location 当作文本列使用文本 operator。
-
-```json
-{
-    "坐标": {
-      "lng": 116.397428,
-      "lat": 39.90923
-    }
-}
-```
-
-
-### 2.9 attachment（不作为普通 CellValue 写入）
-
-读取单元格时，附件为数组，每个元素为 `{file_token, size, name}`，例如 `[{"file_token":"box_xxx","size":1024,"name":"report.pdf"}]`。
-
-- 追加附件：使用 `lark-cli base +record-upload-attachment --record-id <record_id> --field-id <field_id> --file <path>`；可重复 `--file` 一次追加多个附件，不能用普通记录操作接口写附件值。
-- 删除附件：使用 `lark-cli base +record-remove-attachment --record-id <record_id> --field-id <field_id> --file-token <file_token> --yes`；可重复 `--file-token` 一次删除同一单元格里的多个附件。
-- 下载附件：使用 `lark-cli base +record-download-attachment --record-id <record_id> --file-token <file_token> --output <dir>`；不传 `--file-token` 时下载整行所有附件，也可重复 `--file-token` 只下载指定附件。Base 附件必须用这个命令下载，用其他下载入口可能失败。
-
-## 3. 只读字段（不要写）
-
-写记录时，`auto_number`、`lookup`、`formula`、`created_at/updated_at`、`created_by/updated_by` 均为只读字段。
-
-写入只读字段通常不会更新数据；返回里可能出现 `ignored_fields`，reason 会说明 `READONLY`。看到这种返回时，不要重试同一 payload，应移除只读字段，只写存储字段。
-
-读取单元格时，`auto_number`、`formula`、`lookup` 为 `string | null`；`created_at`、`updated_at` 为 RFC3339 字符串或 `null`；`created_by`、`updated_by` 为 `array<{id, name}>`。
-
-## 4. 完整示例
-
-```json
-{
-    "标题": "Created from shortcut",
-    "状态": ["Todo"],
-    "标签": ["高优", "外部依赖"],
-    "工时": 8,
-    "截止时间": "2026-03-24 10:00",
-    "已完成": false,
-    "负责人": [{ "id": "ou_123" }],
-    "关联任务": [{ "id": "rec_456" }],
-    "坐标": { "lng": 116.397428, "lat": 39.90923 }
-}
-```

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

@@ -1,93 +0,0 @@
-# Base NDJSON：pandas 示例
-
-仅在统一数据分析 SOP 已选择 pandas 后读取。本页不重复 Base 的粒度与关系规则，只展示对应实现。
-
-示例假设 `records.ndjson` 包含 `record_id`、`日期`、`状态`、`金额`、`负责人`、`标签`、`关联客户`；`customers.ndjson` 包含 `record_id`、`客户名称`。多值列使用统一数据分析 SOP 定义的数组结构。
-
-## 加载与日期解析
-
-```python
-import pandas as pd
-
-records = pd.read_json("records.ndjson", lines=True)
-raw_dates = records["日期"].astype("string")
-records["日期_local"] = pd.to_datetime(
-    raw_dates.str.slice(0, 10), format="%Y-%m-%d", errors="coerce"
-)
-records["日期_instant"] = pd.to_datetime(
-    raw_dates, format="ISO8601", utc=True, errors="coerce"
-)
-```
-
-按来源 Base 的日、周、月分组使用 `日期_local`；计算真实时长、排序或跨时区比较使用 `日期_instant`。实际任务只需构造所需的一列。
-
-## 集合谓词：保持 record 粒度
-
-筛选“状态”包含“进行中”的记录，并在 record 粒度汇总：
-
-```python
-active = records[records["状态"].map(lambda values: "进行中" in values)]
-summary = {
-    "records_count": len(active),
-    "amount_sum": active["金额"].sum(min_count=1),
-}
-```
-
-## 单数组展开：切换到人员粒度
-
-```python
-owners = records[["record_id", "负责人"]].explode("负责人", ignore_index=True)
-owners = owners[owners["负责人"].notna()].assign(
-    user_id=lambda df: df["负责人"].map(lambda user: user["id"]),
-    user_name=lambda df: df["负责人"].map(lambda user: user["name"]),
-)
-by_owner = (
-    owners.groupby(["user_id", "user_name"], as_index=False)
-    .agg(records_count=("record_id", "nunique"))
-    .sort_values("records_count", ascending=False)
-)
-```
-
-## Link JOIN：先建立边表
-
-```python
-edges = (
-    records[["record_id", "关联客户"]]
-    .rename(columns={"record_id": "source_record_id"})
-    .explode("关联客户", ignore_index=True)
-)
-edges = edges[edges["关联客户"].notna()].assign(
-    target_record_id=lambda df: df["关联客户"].map(lambda link: link["id"])
-)[["source_record_id", "target_record_id"]]
-
-customers = pd.read_json("customers.ndjson", lines=True).rename(
-    columns={"record_id": "target_record_id"}
-)
-joined = edges.merge(
-    customers[["target_record_id", "客户名称"]],
-    on="target_record_id",
-    how="left",
-)
-```
-
-## 多数组共现：显式生成行内笛卡尔积
-
-连续两次 `explode` 表示同一 source record 内的 `负责人 × 标签`：
-
-```python
-pairs = (
-    records[["record_id", "负责人", "标签"]]
-    .explode("负责人", ignore_index=True)
-    .explode("标签", ignore_index=True)
-    .dropna(subset=["负责人", "标签"])
-    .assign(
-        user_id=lambda df: df["负责人"].map(lambda user: user["id"]),
-        user_name=lambda df: df["负责人"].map(lambda user: user["name"]),
-    )
-)
-cooccurrence = (
-    pairs.groupby(["user_id", "user_name", "标签"], as_index=False)
-    .agg(records_count=("record_id", "nunique"))
-    .sort_values("records_count", ascending=False)
-)
-```

package/skills/lark-base/references/lark-base-data-analysis-python-stdlib.md

@@ -1,120 +0,0 @@
-# Base NDJSON：Python 标准库示例
-
-仅在统一数据分析 SOP 已选择 Python 标准库后读取。本页不重复 Base 的粒度与关系规则，只展示对应实现。
-
-示例假设 `records.ndjson` 包含 `record_id`、`日期`、`状态`、`金额`、`负责人`、`标签`、`关联客户`；`customers.ndjson` 包含 `record_id`、`客户名称`。多值列使用统一数据分析 SOP 定义的数组结构。
-
-## 加载与日期解析
-
-NDJSON 每行是一条独立 JSON record；按行读取即可，不要先把文件整体载入字符串。
-
-```python
-import json
-from datetime import date, datetime
-
-
-def read_ndjson(path):
-    with open(path, encoding="utf-8") as stream:
-        for line in stream:
-            if line.strip():
-                yield json.loads(line)
-
-
-records = list(read_ndjson("records.ndjson"))
-for record in records:
-    raw_date = record["日期"]
-    record["日期_local"] = date.fromisoformat(raw_date[:10]) if raw_date else None
-    record["日期_instant"] = datetime.fromisoformat(raw_date) if raw_date else None
-```
-
-按来源 Base 的日、周、月分组使用 `日期_local`；计算真实时长、排序或跨时区比较使用 `日期_instant`。实际任务只需构造所需的一项。
-
-## 集合谓词：保持 record 粒度
-
-筛选“状态”包含“进行中”的记录，并在 record 粒度汇总：
-
-```python
-active = [record for record in records if "进行中" in record["状态"]]
-amounts = [record["金额"] for record in active if record["金额"] is not None]
-summary = {
-    "records_count": len(active),
-    "amount_sum": sum(amounts) if amounts else None,
-}
-```
-
-## 单数组展开：切换到人员粒度
-
-用嵌套循环表达 lateral expansion；按人员 `id` 聚合，`name` 只用于展示。
-
-```python
-from collections import defaultdict
-
-record_ids_by_owner = defaultdict(set)
-owner_names = {}
-for record in records:
-    for owner in record["负责人"]:
-        record_ids_by_owner[owner["id"]].add(record["record_id"])
-        owner_names[owner["id"]] = owner["name"]
-
-by_owner = sorted(
-    (
-        {
-            "user_id": user_id,
-            "user_name": owner_names[user_id],
-            "records_count": len(record_ids),
-        }
-        for user_id, record_ids in record_ids_by_owner.items()
-    ),
-    key=lambda row: (-row["records_count"], row["user_id"]),
-)
-```
-
-## Link JOIN：先建立目标表索引
-
-目标表的 `record_id` 是唯一主键，可直接建立哈希索引；Link 的 `id` 用于索引查找。
-
-```python
-customers = {
-    customer["record_id"]: customer
-    for customer in read_ndjson("customers.ndjson")
-}
-
-joined = []
-for record in records:
-    for link in record["关联客户"]:
-        customer = customers.get(link["id"])
-        joined.append(
-            {
-                "source_record_id": record["record_id"],
-                "target_record_id": link["id"],
-                "客户名称": customer["客户名称"] if customer else None,
-            }
-        )
-```
-
-## 多数组共现：显式生成行内笛卡尔积
-
-两层嵌套循环表示同一 source record 内的 `负责人 × 标签`：
-
-```python
-record_ids_by_pair = defaultdict(set)
-owner_names = {}
-for record in records:
-    for owner in record["负责人"]:
-        owner_names[owner["id"]] = owner["name"]
-        for tag in record["标签"]:
-            record_ids_by_pair[(owner["id"], tag)].add(record["record_id"])
-
-cooccurrence = sorted(
-    (
-        {
-            "user_id": user_id,
-            "user_name": owner_names[user_id],
-            "标签": tag,
-            "records_count": len(record_ids),
-        }
-        for (user_id, tag), record_ids in record_ids_by_pair.items()
-    ),
-    key=lambda row: (-row["records_count"], row["user_id"], row["标签"]),
-)
-```

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

@@ -1,63 +0,0 @@
-# base +record-batch-create
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-批量创建记录。
-
-## 适用场景（重点）
-
-- 适合导入 CSV / Excel、外部系统一次性写入新数据。
-- 先把每条输入数据映射为独立的字段对象，再组装到 `create_records`。
-
-## 推荐命令
-
-```bash
-lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> \
-  --json '{"create_records":[{"标题":"任务 A","状态":"Open"},{"标题":"任务 B","状态":"Done"}]}'
-
-lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> --json @batch-create.json
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
-| `--json <body>` | 是 | 批量创建请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
-
-## API
-
-`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_create`
-
-## `--json` 结构
-
-本节只说明 `+record-batch-create` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
-
-对象形态：
-
-```json
-{"create_records":[{"标题":"任务 A","状态":"Open"},{"标题":"任务 B","状态":"Done"}]}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `create_records` | `Array<Map<FieldNameOrID, CellValue>>` | 是 | 记录字段对象数组；每条记录可以提交不同字段，单次最多 200 条 |
-
-## 返回重点
-
-返回 `record_id_list` 和可选的 `ignored_fields`。
-
-## 坑点
-
-- 每个 `create_records` 元素都是独立的记录字段对象，只提交该记录需要写入的字段。
-- 单次最多 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` 确认目标选项存在。
-
-## 参考
-
-- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范

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

@@ -1,57 +0,0 @@
-# base +record-batch-update (batch update)
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-通过 `update_records` 为每条记录提交字段值。
-
-## 推荐命令
-
-```bash
-lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> \
-  --json '{"update_records":{"<record_id_a>":{"状态":["完成"]},"<record_id_b>":{"分数":20}}}'
-
-lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> --json @batch-update.json
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
-| `--json <body>` | 是 | 批量更新请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
-
-## API
-
-`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_update`
-
-## `--json` 结构
-
-本节只说明 `+record-batch-update` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
-
-对象形态：
-
-```json
-{"update_records":{"recA":{"状态":["完成"]},"recB":{"分数":20}}}
-```
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `update_records` | `Map<RecordID, Map<FieldNameOrID, CellValue>>` | 是 | record ID 到字段更新对象的映射（单次最多 200 条） |
-
-## 返回重点
-
-成功响应只包含可选的 `ignored_fields`；没有忽略字段时 `data` 为空对象。请求不会预先校验 record ID 是否存在，因此需要确认实际写入结果时，应再用 `+record-get` 读回目标记录。
-
-## 坑点
-
-- 单次最多更新 200 条记录；`1254104` 表示超过单批上限，拆成多个批次。
-- `1254045` 表示字段不存在，重新 `+field-list` 后使用真实字段名或 `field_id`。
-- `1254015` 表示 CellValue 类型不匹配，按真实 Field schema 和 CellValue 规范修正。
-- 命令不会自动做字段/行映射转换，传什么就发什么。
-- 如果字段映射包含只读字段，返回里可能出现 `ignored_fields` / `READONLY`；移除 Formula、Lookup、系统字段和自动编号等只读字段。
-- 同一 Table 连续批量写入使用串行执行；`1254291` 表示并发写冲突，短暂等待后重试当前批次。
-
-## 参考
-
-- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范

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

@@ -1,145 +0,0 @@
-# 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` 已在云端完成聚合、排序和限制时，才可以用有限返回形成结论。
-- 需要完整原始记录但云端能力无法把结果安全收敛到可返回范围时，明确说明能力边界；不要用手工分页、拆分下载或采样伪装成全局分析。