@amaster.ai/pi-lark 0.1.8 → 0.1.10

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

@@ -15,12 +15,28 @@ Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**
 | 你想做什么 | 用这些命令 | 关键文档 |
 |------|-----------|---------|
 | 创建/删除/改名称 | `+dashboard-create/delete/update` | 本页下方「仪表盘管理」 |
-| 在仪表盘里添加组件 | `+dashboard-block-create` | 先定位 dashboard、表和字段，再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 构造 `data_config` |
-| 修改组件 | `+dashboard-block-update` | 先读 block 现状，再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 决定替换哪些顶层 key |
+| 在仪表盘里添加组件 | `+dashboard-block-create` | 先定位 dashboard、表和字段，再读 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 构造 `data_config` |
+| 修改组件 | `+dashboard-block-update` | 先读 block 现状，再读 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 决定替换哪些顶层 key |
+| 创建/更新时指定组件精确位置大小 | `+dashboard-block-create/update --position` | 本页下方「精确布局 --position vs +dashboard-arrange」 |
 | 查看仪表盘有哪些组件 | `+dashboard-get` 或 `+dashboard-block-list` | 本页下方「查看仪表盘」 |
 | 读取图表计算结果 | `+dashboard-block-get-data` | 返回图表最终数据协议；需要 block 元数据先用 `+dashboard-block-get` |
 | 智能重排组件布局 | `+dashboard-arrange` | 用户明确要求重排，或本次会话新建仪表盘的收尾整理；无法指定 `x/y/w/h`、精确位置或尺寸 |
 
+## 精确布局 --position vs +dashboard-arrange
+
+create/update 可选 `--position`，用 12 列栅格坐标精确指定单个组件的落点与大小：`{"x","y","w","h"}`，`x`/`y` 为左上角坐标（>=0），`w` 为宽度（1..12，且 `x+w<=12`），`h` 为高度（>=1）。它与 `name`/`type`/`data_config` 平级挂在请求体顶层。
+
+> [!IMPORTANT]
+> - **四个 key 必须齐全且都是数字**：`position` 按整体提交、不做逐字段合并，所以只传 `{"x":6}` 表达的不是"只挪位置不改大小"，而是一个缺了三项的位置。本地会拒绝残缺对象（含显式 `null`）。
+> - 坐标**取值不做本地校验**：越界、负值或重叠坐标会原样发给服务端，由服务端自动重排。调用方仍应优先规划 12 列范围内且不重叠的坐标，避免自动重排改变预期落点。
+> - 不传 `--position`：create 由服务端自动装箱，update 保持当前布局不变。
+> - 只有用户明确给出 `x/y/w/h`、具体行列/顺序、每个组件宽高或可直接换算的尺寸比例时才用 `--position`。"调整布局""美化""撑满""铺满"本身不算精确约束，没有组件级坐标或尺寸时优先用 `+dashboard-arrange` 整盘编排。
+> - 命令成功即视为写入成功，一般无需仅为读回位置再调用 `+dashboard-block-get` / `+dashboard-block-list`；成功响应不代表最终渲染位置已经过读回验证。
+
+## statistics 指标卡数值格式
+
+`statistics` 组件可在 create/update 的 `data_config.number_format` 中设置 `formatName` 和 `precision`。create 会校验组件类型和子字段；update 不接收 `--type`，只校验 `number_format` 子字段，再由服务端结合现有 block 类型裁决。枚举、精度范围、更新语义和可复制模板读取 [Dashboard Block 配置](lark-base-dashboard-block-config.md)。
+
 ## 典型场景工作流
 
 ### 场景 1：从 0 到 1 创建仪表盘
@@ -30,7 +46,7 @@ Dashboard 是 Base 中的数据可视化看板，可以把表格数据变成**
 - 聚合方式：创建指标卡或分布图时优先把聚合写进 `data_config`，只有 Top N、字段取值探索、复杂筛选校验或 helper 汇总表场景才先用 `+data-query`。
 - Dry-run 边界：已按模板构造的简单指标卡、分布图、趋势图不需要逐个 `--dry-run` 后再真实创建；只有在调试 JSON、检查请求体、复杂自造 `data_config` 或处理 API validation 错误时才 dry-run。
 - 验证方式：创建接口成功返回即表示写入成功。只有结果不确定时才用一次 `+dashboard-get` 或 `+dashboard-block-list` 确认仪表盘和组件存在；不要仅为确认创建而逐组件调用 `+dashboard-block-get-data`。
-- 布局方式：`+dashboard-arrange` 仅两种情况使用：① 用户明确要求美化/重排；② 本次会话中从零新建的仪表盘，建完组件后做一次性布局整理。不是创建成功的必要步骤。
+- 布局方式：用户没有给出组件级坐标或尺寸时，创建完成后用一次 `+dashboard-arrange` 整盘编排即可；只有用户明确给出可执行的精确布局约束时才在 create 中带 `--position`，此时通常不再需要 arrange。
 
 示例：搭建一个销售数据分析仪表盘
 
@@ -48,7 +64,7 @@ lark-cli base +field-list --base-token xxx --table-id <table_id>
 
 # 第 4 步：顺序创建每个组件（必须串行执行，不能并发）
 # 重要：创建组件前，先确定 dashboard_id、组件 name/type 和真实表字段
-# 再阅读 dashboard-block-data-config.md 了解 data_config 结构、组件类型和 filter 规则
+# 再阅读 lark-base-dashboard-block-config.md 了解 data_config 结构、组件类型和 filter 规则
 
 # 第 1 个组件
 lark-cli base +dashboard-block-create \
@@ -68,9 +84,10 @@ lark-cli base +dashboard-block-create \
 
 # 继续创建其他组件...
 
-# 第 5 步：组件创建完成后，使用 arrange 命令智能重排布局（可选但推荐）
+# 第 5 步：组件创建完成后，可按需使用 arrange 智能重排（未使用 --position 时可选）
 # 默认布局可能不够美观，arrange 会根据组件数量和类型自动优化布局
-# 若用户没有要求美化/重排，可先跳过此步骤；这不影响仪表盘和组件是否已创建成功
+# 若任一组件使用了显式 --position，跳过此步骤；除非用户明确同意放弃精确布局
+# 若用户没有要求美化/重排，也可跳过；这不影响仪表盘和组件是否已创建成功
 lark-cli base +dashboard-arrange \
   --base-token xxx \
   --dashboard-id blk_xxx
@@ -93,7 +110,7 @@ lark-cli base +field-list --base-token xxx --table-id <table_id>
 
 # 第 4 步：顺序创建每个新组件（必须串行执行，不能并发）
 # 重要：先确定 dashboard_id、组件 name/type 和真实表字段
-# 再阅读 dashboard-block-data-config.md 了解 data_config 结构
+# 再阅读 lark-base-dashboard-block-config.md 了解 data_config 结构
 lark-cli base +dashboard-block-create \
   --base-token xxx \
   --dashboard-id blk_xxx \
@@ -105,7 +122,7 @@ lark-cli base +dashboard-block-create \
 ### 场景 3：编辑已有组件
 
 > [!IMPORTANT]
-> `+dashboard-block-update` **不能修改组件的 `type`**（图表类型），只能更新 `name` 和 `data_config`。
+> `+dashboard-block-update` **不能修改组件的 `type`**（图表类型），只能更新 `name`、`data_config` 和可选的 `position`。
 > 如需更换组件类型，必须先删除再重新创建。
 
 ```bash
@@ -127,25 +144,26 @@ lark-cli base +field-list --base-token xxx --table-id <table_id>
 
 # 第 5 步：执行更新
 # 重要：先读取当前 block 的 name/type/data_config
-# 再阅读 dashboard-block-data-config.md 了解 data_config 更新规则
+# 再阅读 lark-base-dashboard-block-config.md 了解 data_config 更新规则
 lark-cli base +dashboard-block-update \
   --base-token xxx \
   --dashboard-id blk_xxx \
   --block-id chtxxxxxxxx \
-  --data-config '{...}'
+  --data-config '{...}' \
+  --position '{...}'   # 可选，只在需要调整布局时传
 
 ```
 
 ### 场景 4：重排仪表盘布局
 
-当用户明确要求对已有仪表盘进行布局重排或美化时使用（对本次会话从零新建的仪表盘，可在建完组件后直接做一次性整理，见场景 1）。
+当用户要求调整布局、重排、美化、撑满或铺满，但没有给出组件级坐标或尺寸时使用。定位仪表盘后用一次 `+dashboard-arrange` 整盘编排即可（对本次会话从零新建的仪表盘，在建完组件后编排一次）。
 
 > [!CAUTION]
 > - 排列结果是**服务端智能推荐**，不一定完全符合用户预期
-> - Dashboard shortcut 无法指定 `x/y/w/h`、精确位置或尺寸（如"第一排放 A""图表撑满整行"），排列逻辑是**自适应**的
+> - `+dashboard-arrange` 无法指定 `x/y/w/h`、精确位置或尺寸，排列逻辑是**自适应**的；只有用户明确给出可执行的组件级坐标、行列或尺寸约束时才改用 `--position`
 > - **不建议**在已有仪表盘上自动调用，除非用户明确要求
-> - 用户只要求一般性重排/美化时，可执行一次 `+dashboard-arrange`；用户要求精确结果时，先说明限制并询问是否接受自适应布局，接受后才执行，不能静默替代或声称精确满足
-> - 执行一次 `+dashboard-arrange` 后即停止；不要继续探测 raw `lark-cli api`、源码或未公开布局参数
+> - 用户只要求一般性重排、美化、撑满或铺满时，用 `+dashboard-arrange` 整盘编排
+> - 编排结果不理想时，可结合用户反馈再调整；不要为了凑效果去探测 raw `lark-cli api`、源码或未公开布局参数
 
 ```bash
 # 第 1 步：列出仪表盘，定位到目标仪表盘
@@ -169,7 +187,7 @@ lark-cli base +dashboard-arrange \
 
 1. 图表或指标卡：使用方式 D 读取计算结果。
 2. `text`：使用方式 C，正文位于 `data_config.text`；text 没有计算结果，但属于完整仪表盘内容。
-3. get-data 返回不支持的图表类型：先用方式 C 读取真实 `data_config`，确认 `table_name`、维度、指标、聚合与筛选，再按 [数据分析 SOP](lark-base-data-analysis-sop.md) 使用 `+data-query` 重建同口径结果。字段必须来自真实配置和表结构，不得猜测；无法等价重建时明确报告限制，不能静默省略该 block。
+3. get-data 返回不支持的图表类型：先用方式 C 读取真实 `data_config`，确认 `table_name`、维度、指标、聚合与筛选，再按 [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) 使用 `+data-query` 重建同口径结果。字段必须来自真实配置和表结构，不得猜测；无法等价重建时明确报告限制，不能静默省略该 block。
 
 ```bash
 # 第 1 步：列出仪表盘，定位到当前仪表盘
@@ -209,14 +227,14 @@ lark-cli base +dashboard-block-get-data --base-token xxx --block-id chtxxxxxxxx
 | 单个关键指标 | statistics | 指标卡组件 |
 | 富文本说明/标题/注释 | text | 文本组件（支持 Markdown） |
 
-详细组件类型和 data_config 完整规则：[dashboard-block-data-config.md](dashboard-block-data-config.md)
+详细组件类型和 data_config 完整规则：[Dashboard Block 配置](lark-base-dashboard-block-config.md)
 
 ## 常见问题
 
 **Q: 创建组件的命令和 data_config 怎么写？**
 A:
 1. 先确定 `dashboard_id`、组件 `name`、组件 `type` 和真实表字段
-2. 再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解：
+2. 再读 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 了解：
    - 全部组件类型的可复制模板
    - filter 筛选条件格式
    - 字段类型与操作符对应表
@@ -232,17 +250,17 @@ A: 常见原因：
 A: 不可以，必须串行执行。等上一个 `+dashboard-block-create` 完成后再执行下一个。
 
 **Q: 组件的 `type` 创建后能改吗？**
-A: 不能。`+dashboard-block-update` 只能修改 `name` 和 `data_config`，不能修改 `type`。
+A: 不能。`+dashboard-block-update` 只能修改 `name`、`data_config` 和 `position`，不能修改 `type`。
 
 **Q: 更新组件的命令和 data_config 怎么写？**
 A:
 1. 先读取当前 block，确认 `block_id`、当前 `type` 和已有 `data_config`
-2. 再读 [dashboard-block-data-config.md](dashboard-block-data-config.md) 了解 data_config 结构
+2. 再读 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 了解 data_config 结构
 
 **data_config 更新策略（顶层 key merge）**：
 - 只传入需要修改的顶层字段（如 `series`、`filter`）
 - 未传的顶层字段（如 `group_by`）自动保留原值
-- 但每个传入的字段内部是**全量替换**（如传新 `filter` 会完整覆盖旧 `filter`）
+- 但每个传入的字段内部通常是**全量替换**（如传新 `filter` 会完整覆盖旧 `filter`）；`number_format` 例外，按子字段合并，见 [Dashboard Block 配置](lark-base-dashboard-block-config.md) 的 number_format 小节
 
 **Q: 查看已有组件有什么用？**
 A: 在「添加新组件」或「编辑组件」前查看已有组件可以：

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

@@ -0,0 +1,93 @@
+# 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

@@ -0,0 +1,120 @@
+# 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-data-query.md

@@ -1,11 +1,9 @@
 
-# Base data-query DSL SSOT
+# Base data-query DSL reference
 
-> **入口指南**: [lark-base-data-query-guide.md](lark-base-data-query-guide.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)
 
-本文档是 `+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` 替代聚合查询。
+本文档合并常用 fewshot 与完整 DSL 协议。只有 [Record 查询与分析 SOP](lark-base-record-query-and-analysis-sop.md) 的 Cloud 路径选定 `+data-query` 后才读取，并优先定位与当前查询有关的示例、字段或错误协议。
 
 ## 限制
 
@@ -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
+- [Cloud SOP](lark-base-record-query-and-analysis-cloud-sop.md) — Cloud 路径的查询范围、下推、分页、`+record-list` / `+record-search` 回查和关系查询
 - [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范
-- [lark-base-field-json.md](lark-base-field-json.md) — 字段类型与 JSON 结构
+- [Field Schema](lark-base-field-schema.md) — 字段类型与 JSON 结构

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

@@ -2,15 +2,9 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-创建一个或多个字段；同一表的多个字段默认使用一次 JSON 数组输入。预计串行运行时间超过 caller/tool timeout 时按时间预算拆分，不按固定条数切块。
+创建一个或多个字段；同一表的多个字段优先使用一次 JSON 数组输入。
 
-## Agent 最小工作流
-
-1. 先判断是不是 `formula` / `lookup`。
-2. 如果是：先读对应 guide。
-3. 没读 guide 前，不要直接创建 formula / lookup 字段。
-4. 读完 guide 后，再构造 `--json` 并创建字段。
-5. 如果是跨表 formula / lookup，再补查**目标表**的结构。
+`formula` / `lookup` 创建前读取对应 guide；涉及跨表引用时同时读取目标表结构。
 
 ## 推荐命令
 
@@ -25,11 +19,6 @@ lark-cli base +field-create \
   --table-id <table_id> \
   --json '{"name":"状态","type":"select","multiple":false,"default_value":["Todo"],"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Done","hue":"Green","lightness":"Light"}]}'
 
-lark-cli base +field-create \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --json '{"name":"负责人","type":"user","multiple":false,"default_value":[{"$slot":"current_user"}],"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}'
-
 # 多个字段复用相同字段 JSON 形状，一次传非空数组
 lark-cli base +field-create \
   --base-token <base_token> \
@@ -56,10 +45,10 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
 ## JSON 值规范
 
 - `--json` 接受单个字段 **JSON 对象**，也接受多个字段对象组成的非空数组；不要再套 `fields` 等外层对象。
-- 数组按顺序创建字段，遇到首个失败即停止且不自动回滚已创建字段；需要原子写入时不要假设数组具备事务语义。
+- 数组按顺序创建字段，遇到首个失败即停止且不自动回滚；部分失败时保留 `items` 中的 `created` 项，按 `hint` 修正后只提交 `failed` 和 `not_attempted` 项，并保持依赖顺序。
 - 每个字段对象最少包含：`name`、`type`。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。
-- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；`datetime` / `user` 的动态填充用 `$slot`。完整规则见 [lark-base-field-json.md](lark-base-field-json.md)。
+- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；`datetime` / `user` 的动态填充用 `$slot`。完整规则见 [Field Schema](lark-base-field-schema.md)。
 - `type` 不同，必填子字段不同：
   - `select`：`multiple` 控制是否多选，`options` 定义静态选项，`dynamic_options_source` 定义动态选项来源。静态与动态选项配置二选一，不能同时传。
   - `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。
@@ -81,40 +70,8 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
 }
 ```
 
-**字段说明示例**
-
-```json
-{
-  "name": "负责人",
-  "type": "user",
-  "multiple": false,
-  "description": "用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"
-}
-```
-
-## 返回重点
-
-- 单字段返回 `field` 和 `created: true`；多字段完整返回服务端 `fields`、`total` 和 `created: true`。
-- 大数组成功时若不需要逐字段 ID，可追加 `--jq 'if .ok then (.data | {created,total,field_get_recommended,next_step,verification_hint}) else . end'` 控制 stdout 大小；失败分支仍保留完整部分失败明细。需要逐字段 ID 时不要使用该投影。
-- 数组部分失败返回 `ok:false`、`summary` 和有序 `items`，保留已创建字段及 ID、失败项和未执行项。`failed` 项保留 `type`、`subtype`、`code`、`hint`、`retryable`、`log_id`、`troubleshooter`，以及原 typed error 已有的扩展字段，例如权限错误的 `missing_scopes`、`identity`、`console_url` 或安全策略错误的 `challenge_url`；扩展键与部分失败账本的 `index`、`status`、`field`、`error` 冲突时，以带 `error_` 前缀的无冲突别名输出（例如 `field` → `error_field`）。
-- 部分失败统一返回 `next_step:"inspect_items"`；`field_get_recommended` 仅表示已创建字段是否建议读回。`retryable:true` 只表示该 `failed` 项可原样自动重试；否则先按该项 `hint` 完成授权或修正输入，再重新提交该项。`not_attempted` 项应单独继续。
-- 调用方超时且未收到命令终态输出时，不要重投整个数组；先按本次提交的字段名定向读回，再只提交缺失项。没有写前快照时，读回命中的同名项只能标记为 `ambiguous`，不得计作本轮 `created`。
-- 完整成功且返回 `field_get_recommended:false`、`next_step:"done"` 时直接结束；除非用户明确要求读回或额外属性，否则不要再执行 `+field-list/get`。确需核验时用 `--jq` 过滤 `+field-list`，不要把全部字段打印进上下文。
-- `field_get_recommended:true` 表示完成当前 `next_step` 后按 `verification_hint` 读回；完整成功时 `next_step:"field_get"` 表示可直接读回。`formula`、`lookup`、`link`、`auto_number` 等字段更适合读回确认服务端最终结构。
-
-## 工作流
-
-1. formula / lookup 字段必须先阅读对应指南；没读之前不要直接创建。
-2. 创建简单字段时，优先相信命令返回；只有用户要求精确核对额外属性，或返回建议读回时，才继续执行 `+field-get`。
-
-## 坑点
-
-- ⚠️ 这是写入操作，执行前必须确认。
-- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。
-- ⚠️ 不要把“每次创建后都 `+field-get`”当作固定流程；按返回里的 `field_get_recommended` 和 `next_step` 决定是否读回。
-
 ## 参考
 
-- [lark-base-field-json.md](lark-base-field-json.md) — 字段 JSON 规范（推荐）
-- [formula-field-guide.md](formula-field-guide.md) — formula 指南（创建公式必读）
-- [lookup-field-guide.md](lookup-field-guide.md) — lookup 指南（创建查找引用必读）
+- [Field Schema](lark-base-field-schema.md) — 字段 JSON 规范（推荐）
+- [Formula Field](lark-base-field-formula.md) — 创建公式必读
+- [Lookup Field](lark-base-field-lookup.md) — 创建查找引用必读

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

@@ -1,4 +1,4 @@
-# Base Formula Writing Guide
+# Base Formula Field
 
 ## Mandatory Read Acknowledgement
 

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

@@ -1,4 +1,4 @@
-# Base Lookup Field Configuration Guide
+# Base Lookup Field
 
 ## Mandatory Read Acknowledgement