@amaster.ai/pi-lark 0.1.8 → 0.1.9

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
 

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`
 
@@ -10,9 +10,9 @@
 - `+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。
 
 推荐示例：
@@ -185,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
 {
@@ -229,6 +229,8 @@
 
 #### 动态选项
 
+当新字段要引用或复用另一选项字段的选项列表时，优先使用 `dynamic_options_source`，避免重复定义和维护 `options`。
+
 支持字段：`multiple`、`dynamic_options_source`
 动态选项不支持 `default_value`。
 
@@ -264,7 +266,7 @@
 {
   "type": "datetime",
   "name": "截止时间",
-  "default_value": "2026-03-24 10:00:00"
+  "default_value": "2026-03-24 10:00"
 }
 ```
 
@@ -272,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；前端当前最多配置到分钟级展示，底层时间值以毫秒级精度存储。
 
 常用写法：
 
@@ -305,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
 {
@@ -327,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
 
@@ -377,7 +366,7 @@
 
 ### 3.9 formula
 
-公式字段；`expression` 必填。创建/更新前先读 [formula-field-guide.md](formula-field-guide.md) 学习公式语法。
+公式字段；`expression` 必填。创建/更新前先读 [Formula Field](lark-base-field-formula.md) 学习公式语法。
 
 ```json
 {
@@ -389,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
 
@@ -431,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`。
 
 自定义规则：
 
@@ -504,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": "完成" }
@@ -513,14 +430,12 @@
 ## 4. 创建与更新
 
 - `+field-create`：按目标字段配置直接构造 `--json`。
-- `+field-update`：使用同样的 JSON 结构，但语义是 `PUT`；建议先 `+field-get`，再按目标完整状态提交，并带 `--yes`。当 `type` 是 `auto_number` 时，更新编号规则本身就会把新规则应用到已有编号，无需额外参数，也不要在 JSON 里塞额外的底层实现参数。
+- `+field-update`：使用同样的 JSON 结构，但执行完整覆盖更新，不是局部 patch。先用 `+field-get` 读取当前定义，在其基础上修改目标属性；需要保留的名称、类型、样式、选项、默认值、描述及类型专属配置都应完整写回，并带 `--yes`。
 
 ## 5. 暂不支持字段
 
 Object（对象字段）、Button（按钮字段）、Stage（流程字段）暂时都没有被 CLI 支持。这些字段会展示为 `not_support` 字段并被保护：不允许修改，不允许读取内容。
 
-遇到暂不支持的字段类型时，直接说明 Base CLI 当前不支持并停止；不要猜测未注册的字段 JSON、service 或 schema，也不要用其他字段类型冒充目标能力。
-
 ## 6. 易错点
 
 - `select` 只有一个类型；不要写 `single_select` / `multi_select`，用 `multiple` 控制是否多选。

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

@@ -14,19 +14,6 @@ lark-cli base +field-update \
   --json '{"name":"状态","type":"select","multiple":false,"default_value":["Doing"],"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Doing","hue":"Orange","lightness":"Light"},{"name":"Done","hue":"Green","lightness":"Light"}]}' \
   --yes
 
-lark-cli base +field-update \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --field-id <field_id> \
-  --json '{"name":"负责人","type":"user","multiple":false,"default_value":null,"description":"用于标记记录的直接负责人"}' \
-  --yes
-
-lark-cli base +field-update \
-  --base-token <base_token> \
-  --table-id <table_id> \
-  --field-id <field_id> \
-  --json '{"name":"编号","type":"auto_number","style":{"rules":[{"type":"text","text":"TASK-"},{"type":"created_time","date_format":"yyyyMM"},{"type":"text","text":"-"},{"type":"incremental_number","length":4}]}}' \
-  --yes
 ```
 
 ## 参数
@@ -49,19 +36,17 @@ lark-cli base +field-update \
 PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 ```
 
-当 `--json.type` 是 `auto_number` 时，仍然走同一个 v3 字段更新接口：更新自动编号规则后，接口现状就会把新规则应用到已有编号（这是接口默认行为，只是 agent 通常不知道），因此**不需要**任何额外开关或参数。只需要正常提交目标自动编号字段定义即可；如果用户要求“将修改用于已有编号”，直接执行这次 `+field-update` 就能达到效果，不要在 `--json` 里额外添加任何参数去“触发”重排。
-
 ## JSON 值规范
 
 - `--json` 必须是 **JSON 对象**，顶层直接传字段定义。
-- 更新语义是 `PUT`（全量字段配置更新），不要只传零散片段；至少显式包含 `name`、`type`，并补齐该类型所需关键配置。
+- 更新语义是 override 式的完整覆盖 `PUT`，不是 partial update；先读取当前定义，再提交整个字段需要保留的可写配置，不要只传零散片段。
 - 所有字段类型都支持可选 `description`；支持纯文本，也支持 Markdown 链接。
-- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；传 `null` 清空，省略表示不修改现有默认值。完整规则见 [lark-base-field-json.md](lark-base-field-json.md)。
+- 需要字段默认值时传 `default_value`，直接使用字段对应 CellValue；传 `null` 清空。完整规则见 [Field Schema](lark-base-field-schema.md)。
 - `select` 更新时：`options` 仍按对象数组传，避免混入无效字段。
 - `link` 更新限制：
   - 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。
   - 现有 `link` 字段的 `bidirectional` 不能改。
-- `auto_number` 更新的 `style.rules` 支持 `text`、`created_time`、`incremental_number`。
+- 更新 `auto_number.style.rules` 会按新规则更新已有记录的编号；规则结构见 [Field Schema](lark-base-field-schema.md)。
 
 **推荐更新示例**
 
@@ -79,32 +64,17 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 }
 ```
 
-**字段说明示例**
-
-```json
-{
-  "name": "负责人",
-  "type": "user",
-  "multiple": false,
-  "description": "用于标记记录的直接负责人"
-}
-```
-
 ## 返回重点
 
 - 返回 `field` 和 `updated: true`。
-- `updated:true` 只表示更新请求成功，不表示字段结构、已有记录值或下游能力已经完成验证。`+field-update` 无法知道更新前的字段类型，因此成功响应会推荐执行 `+field-get`；若发生类型转换，还要抽样读取记录值。
-- 如果响应中的 `field.type` 与提交的 `type` 不一致，必须把它当作待核验的类型不匹配；不能返回完成态，也不能只根据其中任一类型推断更新成功。
-- 如果 API 报告本次更新没有产生任何变更（no-op），命令会如实返回该错误；这通常说明目标字段已是期望状态，不要机械重试同一份 `+field-update`。需要确认当前字段完整状态时执行 `+field-get`。
-- 如果返回 `field_get_recommended:true` 或 `next_step:"field_get"`，按提示读回字段；`auto_number` 更新后还应抽样读记录值确认编号已按新规则生成。
+- 按返回的 `next_step` 和 `verification_hint` 继续；类型转换涉及已有值时抽样读取记录。
 
 ## 工作流
 
 
-1. 建议先用 `+field-get` 拉现状，再做最小化修改。
+1. 先用 `+field-get` 读取当前定义，只改变目标属性，并把需要保留的其他可写配置完整写回。
 2. `formula/lookup` 类型更新前先阅读对应指南。
-3. 如果更新 `auto_number`，理解为“更新编号规则，同时把新规则应用到已有编号”；执行后按返回提示读回字段并在必要时抽样记录值。
-4. 如果这次更新会改变字段 `type` 先按下方“字段类型变更规则”判断能否执行。如果不修改 `type`，大多数场景都相对安全。
+3. 如果这次更新会改变字段 `type`，先按下方“字段类型变更规则”判断能否执行。如果不修改 `type`，大多数场景都相对安全。
 
 ## 字段类型变更规则
 
@@ -149,10 +119,10 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 
 只有在**整列数据丢失可接受**时，才允许对黑名单场景例外执行。
 
-- `EmptyColumn`: 该列为空
-- `FreshTableInit`: 新建空表初始化
-- `PrimaryFieldBootstrap`: 主列不能删，只能更新完成初始化
-- `ExplicitLossAccepted`: 用户明确接受整列数据丢失
+1. 该列为空。
+2. 正在初始化新建的空表。
+3. 主字段不能删除，需要通过更新完成初始化。
+4. 用户明确接受整列数据丢失。
 
 不满足以上条件时，不要转换。
 
@@ -167,14 +137,6 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
   - 可能影响视图 / 筛选 / 排序 / 公式 / lookup / 写入引用
 - 如果用户不接受风险：不要执行转换。
 
-### 完成态验证
-
-- `FieldReadback`: 读回字段结构，确认 `type` / `multiple` / `style` / `options`
-- `NoopReadback`: `+field-update` 返回 no-op 错误时，只能说明 API 报告没有产生变更；可以跳过重复 update，但不能替代 `FieldReadback`
-- `ValueReadback`: 抽样读回转换后的单元格值
-- `DownstreamReadback`: 若涉及看板 / 分组 / 排序 / lookup / 公式，继续读回结果
-- `CompletionRule`: 结构、值、下游能力都正确，才能回复“已完成”
-
 ## 坑点
 
 - ⚠️ 这是全量字段属性更新语义，不是 patch。
@@ -184,6 +146,6 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
 ## 参考
 
 - 更新前读取当前字段，确认现有 `type` 和具体配置细节，再决定是原地更新还是新建字段迁移。
-- [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) — 更新查找引用前必读