@amaster.ai/pi-lark 0.1.7 → 0.1.9

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 数组输入。
 
-## Agent 最小工作流
-
-1. 先判断是不是 `formula` / `lookup`。
-2. 如果是：先读对应 guide。
-3. 没读 guide 前，不要直接创建 formula / lookup 字段。
-4. 读完 guide 后，再构造 `--json` 并创建字段。
-5. 如果是跨表 formula / lookup，再补查**目标表**的结构。
+`formula` / `lookup` 创建前读取对应 guide；涉及跨表引用时同时读取目标表结构。
 
 ## 推荐命令
 
@@ -25,10 +19,11 @@ 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"}]}'
 
+# 多个字段复用相同字段 JSON 形状，一次传非空数组
 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 '[{"name":"备注","type":"text"},{"name":"优先级","type":"select","multiple":false,"options":[{"name":"高"},{"name":"低"}]}]'
 ```
 
 ## 参数
@@ -37,7 +32,8 @@ lark-cli base +field-create \
 |------|------|------|
 | `--base-token <token>` | 是 | Base Token |
 | `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
-| `--json <body>` | 是 | 字段属性 JSON 对象 |
+| `--json <body>` | 是 | 单个字段 JSON 对象，或多个字段对象组成的非空数组 |
+
 ## API 入参详情
 
 **HTTP 方法和路径：**
@@ -48,10 +44,11 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
 
 ## JSON 值规范
 
-- `--json` 必须是 **JSON 对象**，顶层直接传字段定义，不要再套一层。
-- 顶层最少包含：`name`、`type`。
+- `--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`。
@@ -73,37 +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`。
-- 如果返回 `field_get_recommended:false` 且 `next_step:"done"`，表示本次是简单字段创建，通常不需要立刻执行 `+field-get`。
-- 如果返回 `field_get_recommended:true` 或 `next_step:"field_get"`，按 `verification_hint` 读回字段；`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
 

package/skills/lark-base/references/{lark-base-field-json.md → lark-base-field-schema.md}

@@ -1,4 +1,4 @@
-# Base field JSON SSOT
+# Base Field Schema
 
 > 适用命令：`lark-cli base +field-create`、`lark-cli base +field-update`
 
@@ -6,12 +6,13 @@
 
 ## 1. 顶层规则（必须遵守）
 
-- `--json` 必须是 JSON 对象。
-- 顶层统一使用：`type` + `name` + 类型特有字段。
+- 单个字段定义始终是 JSON 对象，每个字段对象统一使用：`type` + `name` + 类型特有字段。
+- `+field-create --json` 接受一个字段对象或非空字段对象数组。
+- `+field-update --json` 只接受一个字段对象。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
-- 字段默认值使用 `default_value`，直接传对应 CellValue；支持范围只有 `text`、`number`、静态 `select`、`datetime`、`user`。清空默认值传 `null`；省略表示创建时不设置、更新时不修改。
+- 字段默认值使用 `default_value`，直接传对应 CellValue；支持范围只有 `text`、`number`、静态 `select`、`datetime`、`user`。清空默认值传 `null`；创建时省略表示不设置。
 - 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。
-- `+field-update` 使用同样的字段 JSON 结构，但语义是 `PUT`；这是高风险写入操作，建议先 `+field-get` 再按目标状态全量提交，并带 `--yes`。
+- `+field-update` 是 override 式的完整覆盖 `PUT`，不是 partial update；先用 `+field-get` 读取当前定义，在其基础上修改目标属性，并把整个字段需要保留的可写配置完整写回，同时带 `--yes`。
 - `type=formula` 或 `type=lookup` 创建/更新前，必须先读对应 guide。
 
 推荐示例：
@@ -184,7 +185,7 @@
 - `icon` 默认 `star`
 - `icon` 可用：`star`、`heart`、`thumbsup`、`fire`、`smile`、`lightning`、`flower`、`number`
 - `min` 取值 `0..1`，默认 `1`
-- `max` 默认 `5`；常见或已文档化的范围为 `1..10`，但 CLI 不强制上限为 `10`。如果用户明确需要更大评分范围，优先确认平台能力或用 `+field-create/update --dry-run` 检查请求形状；平台拒绝后再建议改用普通数字或进度字段。
+- `max` 取值 `1..10`，默认 `5`
 
 ```json
 {
@@ -228,6 +229,8 @@
 
 #### 动态选项
 
+当新字段要引用或复用另一选项字段的选项列表时，优先使用 `dynamic_options_source`，避免重复定义和维护 `options`。
+
 支持字段：`multiple`、`dynamic_options_source`
 动态选项不支持 `default_value`。
 
@@ -263,7 +266,7 @@
 {
   "type": "datetime",
   "name": "截止时间",
-  "default_value": "2026-03-24 10:00:00"
+  "default_value": "2026-03-24 10:00"
 }
 ```
 
@@ -271,7 +274,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；前端当前最多配置到分钟级展示，底层时间值以毫秒级精度存储。
 
 常用写法：
 
@@ -304,12 +307,7 @@
 
 ### 3.6 user / group_chat
 
-人员字段和群字段都支持 `multiple`。
-`user` 支持 `default_value`：人员 CellValue 数组，元素可用 `{ "id": "ou_xxx" }` 或 `{ "$slot": "current_user" }`；不要猜用户 ID。`group_chat` 不支持默认值。
-
-默认值 / 约束：
-- `multiple` 默认 `true`
-- `user` 字段支持 `default_value` 配置，`group_chat` 字段不支持 `default_value` 配置。
+两者都支持 `multiple`（默认 `true`）；仅 `user` 支持人员数组 `default_value`，元素使用 `{ "id": "ou_xxx" }` 或 `{ "$slot": "current_user" }`，用户 ID 必须来自真实查询。
 
 ```json
 {
@@ -326,15 +324,7 @@
 
 ### 3.7 created_by / updated_by
 
-系统创建人 / 系统修改人字段；记录写入时应视为只读。
-
-```json
-{ "type": "created_by", "name": "创建人" }
-```
-
-```json
-{ "type": "updated_by", "name": "更新人" }
-```
+系统创建人和修改人字段，记录写入时只读：`{ "type": "created_by", "name": "创建人" }`、`{ "type": "updated_by", "name": "更新人" }`。
 
 ### 3.8 link
 
@@ -376,7 +366,7 @@
 
 ### 3.9 formula
 
-公式字段；`expression` 必填。创建/更新前先读 [formula-field-guide.md](formula-field-guide.md) 学习公式语法。
+公式字段；`expression` 必填。创建/更新前先读 [Formula Field](lark-base-field-formula.md) 学习公式语法。
 
 ```json
 {
@@ -388,34 +378,7 @@
 
 ### 3.10 lookup
 
-查找引用字段；`from`、`select`、`where` 必填，`aggregate` 可选。创建/更新前先读 [lookup-field-guide.md](lookup-field-guide.md)。
-
-支持字段：`from`、`select`、`where`、`aggregate`
-
-默认值 / 约束：
-- `from`、`select`、`where` 必填
-- `aggregate` 默认 `raw_value` 代表不进行聚合，直接返回 select 回的原始值
-- `aggregate` 可用：`raw_value`、`sum`、`average`、`counta`、`unique_counta`、`max`、`min`、`unique`
-- `where.logic` 默认 `and`，仅支持 `and` / `or`
-- `where.conditions` 至少 1 条
-- `conditions` 每项是三元组 `[field, op, value?]`
-
-```json
-{
-  "type": "lookup",
-  "name": "状态汇总",
-  "from": "任务表",
-  "select": "状态",
-  "where": {
-    "logic": "and",
-    "conditions": [
-      ["负责人", "==", { "type": "field_ref", "field": "当前负责人" }],
-      ["状态", "non_empty", null]
-    ]
-  },
-  "aggregate": "raw_value"
-}
-```
+查找引用字段使用 `from`、`select`、`where` 和可选 `aggregate`；结构、条件和聚合值必须按 [Lookup Field](lark-base-field-lookup.md) 构造。
 
 ### 3.11 auto_number
 
@@ -430,52 +393,7 @@
 }
 ```
 
-支持字段：`style.rules`
-
-默认值 / 约束：
-- `style.rules` 是规则数组，数量 `1..9`
-- 默认规则：
-
-```json
-{
-  "style": {
-    "rules": [
-      { "type": "text", "text": "NO." },
-      { "type": "incremental_number", "length": 3 }
-    ]
-  }
-}
-```
-
-#### `text`
-
-支持字段：`text`
-
-```json
-{ "type": "text", "text": "TASK-" }
-```
-
-#### `incremental_number`
-
-支持字段：`length`
-
-默认值 / 约束：
-- `length` 取值 `1..9`
-
-```json
-{ "type": "incremental_number", "length": 4 }
-```
-
-#### `created_time`
-
-支持字段：`date_format`
-
-默认值 / 约束：
-- `date_format` 可用：`yyyyMMdd`、`yyyyMM`、`yyMM`、`MMdd`、`yyyy`、`MM`、`dd`
-
-```json
-{ "type": "created_time", "date_format": "yyyyMMdd" }
-```
+`style.rules` 包含 1–9 条规则：固定文本用 `{ "type":"text", "text":"TASK-" }`；递增序号用 `{ "type":"incremental_number", "length":4 }`（长度 1–9）；创建时间用 `{ "type":"created_time", "date_format":"yyyyMMdd" }`，格式支持 `yyyyMMdd`、`yyyyMM`、`yyMM`、`MMdd`、`yyyy`、`MM`、`dd`。
 
 自定义规则：
 
@@ -503,7 +421,7 @@
 { "type": "location", "name": "位置" }
 ```
 
-写入必须使用 `{lng,lat}`。location 读回会包含 `full_address`；筛选和 `location -> text` 类型转换按 `full_address` 字符串处理，只有公式能访问坐标。
+Location 读取为 `{lng,lat,full_address}`；写入只使用数字 `{lng,lat}`，`full_address` 由平台根据坐标解析，不允许手动指定；筛选行为按照 `full_address` 做字符串筛选，将 Location 当作文本列使用文本 operator。`location -> text` 时只保留 `full_address`。
 
 ```json
 { "type": "checkbox", "name": "完成" }
@@ -512,7 +430,7 @@
 ## 4. 创建与更新
 
 - `+field-create`：按目标字段配置直接构造 `--json`。
-- `+field-update`：使用同样的 JSON 结构，但语义是 `PUT`；建议先 `+field-get`，再按目标完整状态提交，并带 `--yes`。当 `type` 是 `auto_number` 时，更新编号规则本身就会把新规则应用到已有编号，无需额外参数，也不要在 JSON 里塞额外的底层实现参数。
+- `+field-update`：使用同样的 JSON 结构，但执行完整覆盖更新，不是局部 patch。先用 `+field-get` 读取当前定义，在其基础上修改目标属性；需要保留的名称、类型、样式、选项、默认值、描述及类型专属配置都应完整写回，并带 `--yes`。
 
 ## 5. 暂不支持字段