@amaster.ai/pi-lark 0.1.2-beta.57 → 0.1.2-beta.59

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`。
 
@@ -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) — 更新查找引用前必读

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,11 +60,7 @@ value 类型取决于条件引用对象（字段 / 题目）的类型。
 
 ### `text`
 
-用字符串；`==` / `!=` 比较完整文本，`intersects` / `disjoint` 判断是否包含目标片段：
-
-```json
-["标题", "!=", "已归档"]
-```
+用字符串；高频的片段包含 / 排除使用 `intersects` / `disjoint`，完整文本比较使用 `==` / `!=`：
 
 ```json
 ["标题", "intersects", "发布"]
@@ -82,8 +78,6 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 ["位置", "intersects", "深圳"]
 ```
 
-不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
-
 ### `number` / `auto_number`
 
 用数字：
@@ -104,11 +98,9 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 ["状态", "disjoint", ["Archived"]]
 ```
 
-### `user` / `created_by` / `updated_by`
+### `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" }]]
@@ -118,12 +110,6 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 ["负责人", "disjoint", [{ "id": "ou_xxx" }]]
 ```
 
-### `group_chat`
-
-用对象数组：
-
-> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
-
 ```json
 ["负责群", "intersects", [{ "id": "oc_xxx" }]]
 ```
@@ -167,21 +153,7 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 
 ### `formula` / `lookup`
 
-- 筛选值类型由字段计算结果类型动态决定。
-- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
-- 如果报错，再按错误提示把 `value` 改成对应类型。
-
-字符串示例：
-
-```json
-["风险说明", "intersects", "高风险"]
-```
-
-数字示例：
-
-```json
-["汇总分", ">=", 80]
-```
+value schema 随计算结果类型变化；拿不准时先读取字段定义，或根据错误提示修正 value 和 operator。
 
 ## 4. 易错点
 
@@ -189,7 +161,7 @@ location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度
 - `user` / `group_chat` / `link` 不要写成单个标量。
 - `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-data-analysis-cloud.md → lark-base-record-query-and-analysis-cloud-sop.md}

@@ -1,4 +1,4 @@
-# Base cloud data analysis SOP
+# Base Record 查询与分析 Cloud SOP
 
 统一数据分析 SOP 将任务路由到 Cloud 时使用本 SOP。覆盖记录读取、筛选、排序、Top/Bottom N、聚合统计、分组聚合、多表关联和查询后写入前的目标定位。
 
@@ -25,7 +25,7 @@
 | 明确关键词 | `+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 guide](lark-base-data-query-guide.md)，使用 filters/dimensions/measures/sort/limit |
+| 聚合 / 分组 / 分组排序 | `+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 集合 | 再进入记录写入或视图配置；高价值可复用查询可沉淀为持久视图 |
@@ -55,7 +55,7 @@ lark-cli base +record-list \
   --limit 20
 ```
 
-常用 `filter-json` condition fewshot 统一见 [Base 数据表查询与分析 SOP](lark-base-data-analysis-sop.md)；完整协议见 [Base Filter 条件结构](lark-base-filter-condition.md)。
+常用 `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 个排序条件。
 
@@ -84,7 +84,7 @@ lark-cli base +record-search \
 
 - 让 Base 云端查询服务完成 filters、dimensions、measures、sort、pagination.limit。
 - `pagination.limit` 是 Base 云端查询服务中的结果限制，不是本地分页扫描。
-- 先读 [data-query guide](lark-base-data-query-guide.md)；需要 guide 未覆盖的字段类型、日期 value、DSL shape、限制或响应协议时再读 [DSL SSOT](lark-base-data-query.md)。
+- 读取 [data-query DSL reference](lark-base-data-query.md) 中与当前查询有关的 fewshot、字段和协议。
 - `+data-query` 可返回聚合结果或维度字段行；维度字段行按字段组合去重且不返回 `record_id`，不能当逐条原始记录结果使用。
 - 需要输出逐条记录、记录定位或完整行级字段时，先用 `+data-query` 得到业务 key、分组值或候选字段组合，再用 `+record-list --filter-json` / `+record-get` 回查。
 

package/skills/lark-base/references/{lark-base-data-analysis-sop.md → lark-base-record-query-and-analysis-sop.md}

@@ -1,20 +1,34 @@
-# Base 数据表查询与分析 SOP
+# Base Record 查询、匹配与分析 SOP
 
-数据表记录查询和分析任务先读本 SOP，包括记录预览、筛选、排序、去重、统计、聚合、TopN、多值计算、Link 或多表关联、复杂行级计算、全局结论和查询后写入。先区分需要 LLM 理解原文的语义分析与可程序化计算的确定性分析，再按任务所需数据规模与计算复杂度选择对应路径。用户直接要求解释、编写或排错 `+data-query` 命令或 DSL 时，直接读 [data-query guide](lark-base-data-query-guide.md)。
+任何 Record 读取、预览、搜索、筛选、匹配、统计、聚合、TopN、多表或语义分析，以及写操作中的记录定位和结果验收，都先完整读取本 SOP。先区分需要 LLM 理解原文的语义分析与可程序化计算的确定性分析，再按数据规模与计算复杂度选择路径；即使用户直接要求解释、编写或排错 `+data-query` 命令或 DSL，也先由本 SOP 确认口径和路径，再读取底层 reference。
 
 ## 分流决策
 
-1. 明确所有需要参与分析的表及其 `records_count`。
+1. 明确所有需要参与分析的表；上下文已有整表 `records_count` 时用于提前分流，否则直接按下文导出或探测，不为获取规模单独枚举表。
 2. 如果结论必须依赖 LLM 理解原始内容，例如开放文本打标、情绪或意图识别、主题归纳、语义分类、相似性判断或实体消歧，进入下文“LLM 语义分析”路径。
-3. 对于其余确定性查询，任一分析表超过 2000 行时，先从任务意图中为所有大表提取可在单表内独立执行的谓词，例如日期范围、状态和关键词，再按下文将谓词逐表下推，并用 `--field-id '<一个简单标量字段>' --limit 2000 --output <probe>.ndjson --minimal-stdout` 探测。目标是每张表都达到 `has_more=false`；任一表无法压缩到 2000 行以内时，转 [lark-base-data-analysis-cloud.md](lark-base-data-analysis-cloud.md) 用云端的数据分析能力。
+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-data-analysis-cloud.md)。
+5. 其余确定性任务比如多表、日历计算和复杂数据分析，在 Python 可用时使用 Python，否则进入 [Cloud SOP](lark-base-record-query-and-analysis-cloud-sop.md)。
 
-进入 Cloud 后先由 Cloud SOP 在原始记录查询与聚合查询之间选路；只有选定 `+data-query` 时才读取 data-query guide。
+进入 Cloud 后先由 Cloud SOP 在原始记录查询与聚合查询之间选路；只有选定 `+data-query` 时才读取 [data-query DSL reference](lark-base-data-query.md)。
 
 ## 执行与交付
 
-分析输入默认采用 `--output x.ndjson`；NDJSON 未显式传 `--limit` 时默认读取最多 2000 条，正式分析通常沿用该范围。窄投影探测、快速预览或用户明确要求前 N 条时再设置较小的 `--limit`。`--format json` 和 Markdown 适用于向用户即时展示的小结果。
+所有 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`。
 
@@ -45,7 +59,7 @@
 }
 ```
 
-全表分析的常规资源链路是 `+table-list` 确认目标表与规模，对所有参与分析的表并发执行 `+field-list` 读取所需 schema，再用 `+record-list` 导出记录；已有可信的 `table_id` 时可直接并发读取各表 `+field-list`。`+view-get` 可按需读取，作为用户持久化访问习惯的可选参考；其中的 filter、sort 与字段范围可辅助理解用户常用的查询范围和排序偏好，并结合当前任务确定最终口径。
+全表分析的常规资源链路是 `+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 路径。
@@ -53,16 +67,12 @@
 4. Base 标量空值很常见；聚合前按用户口径确定空值是排除、按零计入还是进入分母。用户未指定且不同处理会实质改变结论时，说明空值数量、采用的口径及其影响；任务涉及业务键、展开、JOIN 或金额分摊时，同样明确目标粒度及与口径直接相关的重复或总量守恒。
 5. 最终结果保留真实表、查询范围和计算口径，展示用户可读字段；内部 ID 用于连接或定位。
 
-`+table-list` / `+base-block-list` 返回的 `records_count` 表示整表行数；manifest 的 `records_count` 表示本次查询实际导出的行数。
-
 ## 复用本轮 NDJSON
 
 Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否复用：
 
 1. 短时间内继续分析或表中数据低频变化时，谓词下推口径一致且已有列覆盖计算需求即可优先复用。
-2. 间隔较长或表中数据高频变化时，批量提取 manifests 的 `base_token/table_id/rev`，并发执行 `+table-list` 校验最新 `rev`；版本一致且谓词口径未变时复用，否则重新导出对应表。
-
-> 例：本轮已按“日期在 2026 年”导出 `orders.ndjson`，用户继续要求按负责人聚合；谓词和所需列未变，直接复用。若间隔较长或该表频繁写入，manifest `rev=42` 与 `+table-list` 最新 `rev` 相同则复用，最新 `rev=43` 则重新导出。
+2. 间隔较长或表中数据高频变化时，批量提取 manifests 的 `base_token/table_id/rev`，刷新相关表元数据并校验最新 `rev`；版本一致且谓词口径未变时复用，否则重新导出对应表。
 
 ## LLM 语义分析
 
@@ -76,7 +86,7 @@ Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否
 
 ## Manifest
 
-`--output <path>.ndjson` 生成 `<path>.ndjson` 与 `<path>.manifest.json`；记录写入 NDJSON，stdout 返回 manifest，`--minimal-stdout` 只保留文件位置、文件字节数、`records_count` 和 `has_more`。
+`--output <path>.ndjson` 生成 `<path>.ndjson` 与 `<path>.manifest.json`；记录写入 NDJSON，stdout 返回 manifest。
 
 分析 artifact 使用相对路径输出到当前工作目录，例如 `--output ./records.ndjson`。
 
@@ -115,7 +125,6 @@ Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否
 
 - stdout 的 `records_count` 和 `has_more` 描述本次导出；确认后无需在分析代码中重读 manifest 或重新统计 NDJSON 行数。
 - `record_file_size_bytes` 是 NDJSON artifact 的实际字节数，用于选择一次读取、预览或分批方式；确定性计算由 jq/Python 直接读取文件。
-- manifest 的 `rev` 是导出首个响应页返回的 table revision；与 `+table-list` 返回的最新 `rev` 比较，可判断本轮 NDJSON 是否仍对应当前表版本。
 - `query_context` 保存导出查询范围；复用本轮 NDJSON 时结合原查询上下文确认谓词下推口径保持一致。
 - 仅在需要 `columns`、example、hint 或执行 artifact 复用判断时读取 `manifest_file`；满足复用条件后直接继续分析现有 NDJSON。
 - `ignored_fields` 和 `record_not_found` 仅在 stdout 返回时关注。
@@ -174,7 +183,7 @@ Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否
 
 NDJSON 每行是一条 record。单表短筛选、计数和简单聚合可直接用 jq；下面筛选“状态”包含“进行中”的记录，并统计记录数和金额合计：
 
-默认导出后使用本地 `jq -s`，同一 artifact 可反复查询而无需重新下载。表达式很短且只执行一次，或本地 jq 不可用时，可改用 `--jq-records '<expr>'` 等价 `jq -s '<expr>' records.ndjson`。使用 CLI 内置 jq 处理 NDJSON 记录时必须使用 `--jq-records`；通用 `--jq` 不支持 ndjson。
+默认导出后使用本地 `jq -s`，同一 artifact 可反复查询而无需重新下载；本地 jq 不可用时，使用 Python 或其他数据分析引擎处理 records 文件。
 
 ```bash
 lark-cli base +record-list \
@@ -182,8 +191,8 @@ lark-cli base +record-list \
   --table-id <table_id> \
   --field-id 状态 \
   --field-id 金额 \
-  --output records.ndjson \
-  --minimal-stdout &&
+  --format ndjson \
+  --output records.ndjson &&
 jq -s '
   map(select((.["状态"] | index("进行中")) != null)) as $records
   | ($records | map(.["金额"] | select(. != null))) as $amounts

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。