diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index 0a8218087..b3585ad48 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -12,6 +12,7 @@ metadata: > **前置条件:** 先阅读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)。 > **执行前必做:** 执行任何 `base` 命令前,必须先阅读对应命令的 reference 文档,再调用命令。 +> **查询类任务必做:** 涉及筛选、排序、Top/Bottom N、聚合、多表关联、查询后写入或判断全局结论时,必须先阅读 [`references/lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md),再选择 `record / view / data-query` 路径。 > **命名约定:** Base 业务命令仅使用 `lark-cli base +...` 形式;如需先解析 Wiki 链接,可先调用 `lark-cli wiki ...`。 > **分流规则:** 如果用户要“把本地文件导入成 Base / 多维表格 / bitable”,第一步不是 `base`,而是 `lark-cli drive +import --type bitable`;导入完成后再回到 `lark-cli base +...` 做表内操作。 @@ -104,7 +105,7 @@ metadata: | 命令 | 用途 / 何时使用 | 必读 reference | 路由提醒 | |------|------------------|----------------|----------| -| `+record-search / +record-list / +record-get` | 按关键词检索记录、读取记录明细 / 分页导出,或按 ID 获取一条或多条记录 | [`lark-base-record-read-sop.md`](references/lark-base-record-read-sop.md) | 记录读取统一先读 read SOP guide:已知 `record_id` 用 `+record-get`;明确关键词用 `+record-search`;普通明细用 `+record-list`;明确筛选 / 排序 / Top N 用临时视图投影后 `+record-list --view-id`;统计聚合才分流到 `+data-query`;`+record-get` 支持重复 `--record-id` 或 `--json` 读取多条记录 | +| `+record-search / +record-list / +record-get` | 按关键词检索记录、读取记录明细 / 分页导出,或按 ID 获取一条或多条记录 | [`lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md) | 记录读取统一先读 data analysis SOP:已知 `record_id` 用 `+record-get`;明确关键词用 `+record-search`;普通明细用 `+record-list`;明确筛选 / 排序 / Top N 用临时视图投影后 `+record-list --view-id`;统计聚合才分流到 `+data-query`;`+record-get` 支持重复 `--record-id` 或 `--json` 读取多条记录 | | `+record-upsert / +record-batch-create / +record-batch-update` | 创建、更新或批量写入记录 | [`lark-base-record-upsert.md`](references/lark-base-record-upsert.md)、[`lark-base-record-batch-create.md`](references/lark-base-record-batch-create.md)、[`lark-base-record-batch-update.md`](references/lark-base-record-batch-update.md)、[`lark-base-cell-value.md`](references/lark-base-cell-value.md) | 写前先 `+field-list`;只写存储字段;`+record-batch-update` 为同值更新(同一 patch 应用到多条记录);批量单次不超过 `200` 条;附件不要走这里 | | `+record-upload-attachment` | 给已有记录上传附件 | [`lark-base-record-upload-attachment.md`](references/lark-base-record-upload-attachment.md) | 附件上传专用链路,不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 | | `lark-cli docs +media-download` | 下载 Base 附件文件到本地 | [`../lark-doc/references/lark-doc-media-download.md`](../lark-doc/references/lark-doc-media-download.md) | Base 附件的 `file_token` 从 `+record-get` 返回的附件字段数组里取;**不要用 `lark-cli drive +download`**(对 Base 附件返回 403) | @@ -120,7 +121,7 @@ metadata: |------|------------------|----------------|----------| | `+view-list / +view-get` | 列出视图,或获取视图详情 | [`lark-base-view-list.md`](references/lark-base-view-list.md)、[`lark-base-view-get.md`](references/lark-base-view-get.md) | `+view-list` 只能串行执行;`+view-get` 适合查看已有视图配置 | | `+view-create / +view-delete / +view-rename` | 创建、删除或重命名视图 | [`lark-base-view-create.md`](references/lark-base-view-create.md)、[`lark-base-view-delete.md`](references/lark-base-view-delete.md)、[`lark-base-view-rename.md`](references/lark-base-view-rename.md) | 创建前先确认表和视图类型;删除前先确认目标;用户已明确新名字时可直接重命名 | -| `+view-get-filter / +view-set-filter` | 读取或配置筛选条件 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md)、[`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-record-read-sop.md`](references/lark-base-record-read-sop.md) | 常与 `+record-list` 组合,用于按视图筛选读取 | +| `+view-get-filter / +view-set-filter` | 读取或配置筛选条件 | [`lark-base-view-get-filter.md`](references/lark-base-view-get-filter.md)、[`lark-base-view-set-filter.md`](references/lark-base-view-set-filter.md)、[`lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md) | 常与 `+record-list` 组合,用于按视图筛选读取 | | `+view-get-sort / +view-set-sort` | 读取或配置排序 | [`lark-base-view-get-sort.md`](references/lark-base-view-get-sort.md)、[`lark-base-view-set-sort.md`](references/lark-base-view-set-sort.md) | 字段名必须来自真实结构 | | `+view-get-group / +view-set-group` | 读取或配置分组 | [`lark-base-view-get-group.md`](references/lark-base-view-get-group.md)、[`lark-base-view-set-group.md`](references/lark-base-view-set-group.md) | 字段名必须来自真实结构 | | `+view-get-visible-fields / +view-set-visible-fields` | 读取或配置视图可见字段 | [`lark-base-view-get-visible-fields.md`](references/lark-base-view-get-visible-fields.md)、[`lark-base-view-set-visible-fields.md`](references/lark-base-view-set-visible-fields.md) | 用于控制视图中的字段顺序与可见性;字段名必须来自真实结构 | @@ -228,14 +229,24 @@ metadata: | 基于视图做筛选读取 | `+view-set-filter` + `+record-list` | 不要跳过视图筛选直接猜条件 | | 本地 Excel / CSV / `.base` 导入为 Base | `lark-cli drive +import --type bitable` | 不要误走 `+base-create`、`+table-create` 或 `+record-upsert` | -### 3.3 表名、字段名与表达式引用 +### 3.3 查询执行契约 + +涉及查询、统计或判断结论时,先阅读 [`references/lark-base-data-analysis-sop.md`](references/lark-base-data-analysis-sop.md),并遵守以下高优先级规则: + +1. `+record-list` 默认页、固定 `--limit` 和本地 `jq` 只能证明已读取范围内的事实,不能直接支撑全局最值、全量计数、Top/Bottom N、异常识别或分组结论。 +2. 能由 Base 表达的筛选、排序、投影、聚合、分组和限制,应在 Base 云端查询服务中执行;不要先拉明细到本地上下文再手工筛选排序。 +3. `has_more=true` 或等价分页信号表示当前结果不是全量;除非用户只要样例/前 N 条,不能基于该页回答全局问题。 +4. 多表查询必须先确认关系字段和连接键;link 单元格里的 `record_id` 是关系键,不是用户可读答案。 +5. 最终答案必须能追溯到真实表、真实字段、查询范围、筛选/排序/聚合条件和必要的连接键。 + +### 3.4 表名、字段名与表达式引用 1. 表名、字段名必须精确匹配真实返回,来源应是 `+table-list / +table-get / +field-list`。 2. 不要凭自然语言猜名称,不要自行改写用户口述中的表名、字段名。 3. `formula / lookup / data-query / workflow` 中出现的名称同样必须精确匹配;表达式引用、where 条件、DSL 字段名、workflow 配置都遵守同一规则。 4. 跨表场景必须额外读取目标表结构,不能只看当前表。 -### 3.4 Token 与链接 +### 3.5 Token 与链接 这是高优先级章节。只要用户输入里出现链接、token,或报错涉及 `baseToken` / `wiki_token` / `obj_token`,都应优先回到这里检查。 @@ -254,7 +265,7 @@ metadata: | `slides` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | | `mindnote` | 转到 Drive 相关 skill | 不继续使用本 skill 的 Base 命令 | -### 3.5 身份选择与权限降级策略 +### 3.6 身份选择与权限降级策略 多维表格通常属于用户的个人或团队资源。**默认应优先使用 `--as user`(用户身份)执行所有 Base 操作**,始终显式指定身份。 @@ -282,10 +293,11 @@ lark-cli auth login --domain base 1. 先判断任务属于哪个模块,选对命令族。 2. 如果用户给了链接,先解析 token,不要把 wiki token、完整 URL 或其他对象 ID 误当成 `base_token`。 -3. 先拿结构,再写命令,避免猜表名、字段名、表达式引用。 -4. 定位到命令后,先读对应 reference,再执行命令。 -5. 执行命令,并按返回结果判断下一步。 -6. 回复时返回关键结果和后续可继续操作的信息,方便 agent 链式执行下一步。 +3. 如果是查询类任务,先判断问题范围,阅读 data analysis SOP,再决定使用 `record / view / data-query`。 +4. 先拿结构,再写命令,避免猜表名、字段名、表达式引用。 +5. 定位到命令后,先读对应 reference,再执行命令。 +6. 执行命令,并按返回结果判断下一步。 +7. 回复时返回关键结果和后续可继续操作的信息,方便 agent 链式执行下一步。 ### 4.2 不可违反规则 @@ -297,11 +309,12 @@ lark-cli auth login --domain base 6. 只写可写字段;系统字段、附件字段、`formula`、`lookup` 默认不作为普通记录写入目标。 7. 聚合分析与取数分流;统计走 `+data-query`,关键词检索走 `+record-search`,明细走 `+record-list / +record-get`。 8. 筛选查询按视图能力执行;先用 `+view-set-filter` 配置筛选,再结合 `+record-list` 读取。 -9. Base 场景不要改走裸 API,不要切去 `lark-cli api /open-apis/bitable/v1/...`。 -10. 统一使用 `--base-token`。 -11. workflow 场景先读 schema,不要凭自然语言猜 `type`。 -12. dashboard 场景先读 guide;提到图表、看板、block 就先进入 dashboard 模块。 -13. formula / lookup 场景先读 guide;没读 guide 前不要直接创建或更新。 +9. 全局查询不得基于默认分页、小 `--limit` 或未证明全量的本地 `jq` 结果下结论。 +10. Base 场景不要改走裸 API,不要切去 `lark-cli api /open-apis/bitable/v1/...`。 +11. 统一使用 `--base-token`。 +12. workflow 场景先读 schema,不要凭自然语言猜 `type`。 +13. dashboard 场景先读 guide;提到图表、看板、block 就先进入 dashboard 模块。 +14. formula / lookup 场景先读 guide;没读 guide 前不要直接创建或更新。 ### 4.3 并发、分页与批量限制 diff --git a/skills/lark-base/references/lark-base-data-analysis-sop.md b/skills/lark-base/references/lark-base-data-analysis-sop.md new file mode 100644 index 000000000..45694a965 --- /dev/null +++ b/skills/lark-base/references/lark-base-data-analysis-sop.md @@ -0,0 +1,88 @@ +# Base data analysis SOP + +Base 数据查询与分析任务的执行契约。覆盖记录读取、筛选、排序、Top/Bottom N、聚合统计、分组聚合、多表关联、临时分析和查询后写入前的目标定位。 + +具体命令参数不要在本文猜;需要时跳到对应 reference: + +- `+data-query`: [lark-base-data-query.md](lark-base-data-query.md) +- 视图筛选/排序/投影: [lark-base-view-set-filter.md](lark-base-view-set-filter.md), [lark-base-view-set-sort.md](lark-base-view-set-sort.md), [lark-base-view-set-visible-fields.md](lark-base-view-set-visible-fields.md) +- 记录读取: [lark-base-record.md](lark-base-record.md) + +## 0. Hard Rules + +- 全局问题不能用默认 `+record-list --limit N` 片面地回答。 +- `jq` / shell / 本地代码是在个人电脑或当前运行环境中处理已返回数据,只适合小范围结果;超过 200 行默认不推荐本地统计、排序或求极值,应改用 Base 云端查询服务的 filter/sort/aggregate。 +- “最高、最低、最新、最早、Top、Bottom、总数、全部、异常、最大、最小、最多、最少、优先级最高”等全局语义,必须在 Base 云端查询服务中完成筛选、排序或聚合。 +- `+record-search` 用于关键词检索字段的展示文本;可搜多类字段,但匹配的是文本表示(如人员命中 name),不要用它替代金额、状态、日期、空值等结构化条件。 +- 不要依赖已有视图,除非用户明确指定该视图,或你已读取并验证其 filter/sort/projection 符合当前问题。 +- 最终答案必须使用用户可读的展示值;内部 ID、`record_id`、关联记录 ID、open_id、编码字段只能作为连接键,不能替代最终答案,除非用户明确要求输出 ID。 +- 每次读取必须做最小投影,并包含后续解释、回查或写入需要的业务 key。 + +## 1. Intent -> Tool Path + +| 用户意图 | 首选路径 | 关键规则 | +| --- | --- | --- | +| 看几条、预览、示例 | `+record-list --limit N` | 保持局部语义;不要推广为全局结论 | +| 已知 `record_id` | `+record-get` | 直接读取;不要 search/list 反查 | +| 明确关键词 | `+record-search` | 按字段展示文本命中;使用 `search_fields` 限定匹配范围、`select_fields` 投影降低返回内容 token 量 | +| 按条件找明细记录 | 先创建临时视图设置筛选和可见字段,再用 `+record-list --view-id` 读取 | 条件字段来自 `+field-list`;不要先读全表再本地过滤 | +| 排序 / TopN 原始记录 | 临时视图 filter/sort/projection -> `+record-list --view-id --limit N` | 最高/最新降序,最低/最早升序 | +| 聚合 / 分组 / 分组排序 | `+data-query` | 使用 filters/dimensions/measures/sort/limit | +| 聚合后输出实体名 | `+data-query` 得到业务 key -> record 路径回查明细 | `+data-query` 不返回原始记录或 link 明细 | +| 多表 / 多跳关联 | 以候选数最小的事实表为驱动表,沿业务 key 或 link `record_id` 逐跳回查 | 读出 link 单元格里的关联 `record_id` 后,到被关联表批量 `+record-get` 展示字段,并在回答用结果中合并展示 | +| 查询后写入 / 视图化 | 先用本 SOP 得到可复核的目标记录 id 集合 | 再进入记录写入或视图配置;高价值可复用查询优先沉淀为持久视图 | + +## 2. Execution Patterns + +### 2.1 结构化明细与 TopN + +使用视图路径: + +1. `+field-list` 确认筛选字段、排序字段、展示字段、业务 key。 +2. `+view-create` 创建 grid 视图。 +3. 设置 filter/sort/visible fields。 +4. `+record-list --view-id --limit ` 读取结果。 + +不要从未筛选、未排序的全表输出中手动挑选。一次性查询可用临时视图;如果这个筛选/排序结果对用户后续查看有价值,应保留为持久视图,不要删除,并在回答中告知用户视图名称和用途。视图参数细节见 view-set references。 + +### 2.2 聚合分析与 TopN + +使用 `+data-query`: + +- 让 Base 云端查询服务完成 filters、dimensions、measures、sort、pagination.limit。 +- `pagination.limit` 是 Base 云端查询服务中的聚合结果限制,不是本地分页扫描。 +- 需要输出明细或名称时,先拿业务 key,再用 record 路径精确回查。 +- 字段类型、日期 value、DSL shape 以 [lark-base-data-query.md](lark-base-data-query.md) 为准。 + +### 2.3 关系查询与回查 + +- link 单元格通常是关联表 `record_id` 数组,不是用户可读名称。 +- 先用 `+field-list` 确认 link 字段的 `link_table`、业务唯一键和展示字段。 +- 从驱动表拿到候选记录后,用关联 `record_id` 到关联表 `+record-get` 批量读取展示字段。 +- 多跳关系逐跳建立 `record_id/key -> 展示字段` 映射;最终输出业务名称或用户要求字段。 + +禁止: + +- 把 link `record_id` 当最终答案。 +- 用 `+record-search` 搜 link `record_id`。 +- 凭 ID 猜名称、负责人、门店、供应商。 + +## 3. Range & Pagination Contract + +- `+record-list` 默认页、固定 `--limit`、本地 `jq`、shell 管道、手工浏览输出,都只覆盖已读取范围;超过 200 行不要把本地处理当作推荐路径。 +- `has_more=true`、存在下一页 offset/page token、或返回行数等于 page size,都表示可能还有未读取数据。 +- 对全局问题,只有 Base 云端查询服务已经通过 filter/sort/aggregate 收敛目标范围,或 `data-query` 已在云端完成聚合、排序和限制时,才可以用有限返回作答。 +- 必须全量导出时,按 CLI 分页语义串行翻页;不要并发调用 `+record-list`。 + +## 4. Final Answer Check + +回答前必须能确认: + +- 问题范围是局部样例、单点定位、全局明细、聚合分析、多表关联,还是查询后写入。 +- 筛选、排序、聚合是否发生在 Base 云端查询服务中,而不是本地 `jq` / shell 中。 +- 如果使用 `jq` / shell,本地输入是否是 200 行以内的小范围结果;超过 200 行是否已改用 Base 云端查询服务查询。 +- 如果使用 `+record-list`,是否处理了 `has_more`,且投影包含业务 key 和解释字段。 +- 如果涉及关系查询,是否按 `record_id` 或业务 key 精确回查,最终答案是否来自关联表真实字段。 +- 最终答案能追溯到表、字段、筛选条件、排序/聚合条件和连接键。 + +任一项无法确认时,继续查询或明确说明只能得到局部结论。 diff --git a/skills/lark-base/references/lark-base-data-query.md b/skills/lark-base/references/lark-base-data-query.md index 9eae81c95..b63ee2e7f 100644 --- a/skills/lark-base/references/lark-base-data-query.md +++ b/skills/lark-base/references/lark-base-data-query.md @@ -5,6 +5,8 @@ 对多维表格数据进行聚合查询(分组、过滤、排序、聚合计算),基于以下语法的 JSON DSL: +查询类任务还必须先遵守 [`lark-base-data-analysis-sop.md`](lark-base-data-analysis-sop.md)。`+data-query` 适合让筛选、分组、聚合、排序和 TopN 在 Base 云端查询服务中执行;不要用默认分页的 `+record-list` 或本地 `jq` 替代聚合查询。 + ## 限制 - **权限要求**(按文档类型分流): @@ -51,6 +53,23 @@ lark-cli base +data-query \ "measures": [{"field_name": "金额", "aggregation": "sum", "alias": "total"}], "shaper": {"format": "flat"} }' + +# 聚合后如需读取明细,先让 data-query 返回可回查的业务 key +lark-cli base +data-query \ + --base-token MAGObxxxxx \ + --dsl '{ + "datasource": {"type": "table", "table": {"tableId": "tblxxxxxxxx"}}, + "dimensions": [{"field_name": "业务编号", "alias": "biz_key"}], + "measures": [{"field_name": "指标值", "aggregation": "max", "alias": "max_value"}], + "filters": { + "type": 1, + "conjunction": "and", + "conditions": [{"field_name": "状态", "operator": "is", "value": ["有效"]}] + }, + "sort": [{"field_name": "max_value", "order": "desc"}], + "pagination": {"limit": 10}, + "shaper": {"format": "flat"} + }' ``` ## 参数 @@ -397,6 +416,19 @@ value 使用预定义关键字机制,第一个元素为字符串常量名称 - 每个 value 是 CellValue 对象,实际值在 `value` 字段中,如 `{"value": "北京"}` 或 `{"value": 12345.00}` - 失败时结果在 `data.error` 中,包含具体错误码和信息 +## 与记录读取组合 + +`+data-query` 不返回原始记录或 link 字段明细。需要输出聚合结果对应的原始记录字段、展示值或关联表字段时,按以下方式组合: + +1. 用 `+data-query` 在 Base 云端查询服务中完成全局筛选、分组、聚合、排序和 TopN,得到业务 key、分组值或候选范围。 +2. 如果已经拿到候选记录的 `record_id`,用 `+record-get` 读取明细字段。 +3. 如果拿到的是结构化业务 key(例如编号、状态、日期、金额等),优先创建临时视图做精确过滤后再 `+record-list --view-id` 读取;不要用 `+record-search` 代替结构化条件。 +4. 只有候选条件本身是文本展示值关键词时,才使用 `+record-search`,并用 `search_fields` 限定范围、`select_fields` 做投影。 +5. 若候选记录包含 link 字段,提取关联 `record_id` 后到关联表用 `+record-get` 批量读取展示字段。 +6. 最终回答业务字段,不要把内部 `record_id` 当作用户可读答案。 + +不要把 `data-query pagination.limit` 理解为分页扫描;它只限制 Base 云端查询服务返回的聚合结果行数,不支持 offset。需要全量明细导出时回到 data analysis SOP 的 record 分页规则。 + ## 坑点 - ⚠️ **必须先查表结构**:DSL 的 `field_name` 必须与表中字段名称精确匹配(区分大小写),不能凭猜测构造。先用 `lark-cli base +field-list --base-token --table-id ` 获取真实字段名 @@ -408,10 +440,12 @@ value 使用预定义关键字机制,第一个元素为字符串常量名称 - ⚠️ **数据表标识 `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 明细回查和关系查询 SOP - [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范 - [lark-base-shortcut-field-properties.md](lark-base-shortcut-field-properties.md) — shortcut 字段类型与 JSON 结构 diff --git a/skills/lark-base/references/lark-base-record-read-sop.md b/skills/lark-base/references/lark-base-record-read-sop.md deleted file mode 100644 index d4abb2a3f..000000000 --- a/skills/lark-base/references/lark-base-record-read-sop.md +++ /dev/null @@ -1,86 +0,0 @@ -# base record read SOP - -> **前置条件:** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限处理和全局参数。 - -记录读取由 6 个功能组合完成:选路、字段投影、视图预处理、分页与范围、返回结构解释、link 关联读取。 - -## 1. 读取选路 - -| 场景 | 使用方式 | 规则 | -|------|------|------| -| 已知 `record_id` | `+record-get` | 只读单条记录,不要用 search/list 反查。 | -| 明确关键词检索 | `+record-search` | 只用于文本关键词检索;金额、状态、日期等结构化条件不要用 search。 | -| 普通明细读取 / 导出 / 查看前 N 条 | `+record-list` | 优先加 `--view-id` 时只读该视图可见记录与可见字段;或者加 `--field-id` 手动裁剪字段;不传 `--view-id` 时会读取全表。 | -| 明确筛选 / 排序 / Top N / Bottom N 且需要原始记录或 `record_id` | 创建带 filter + sort 的临时视图 + `+record-list --view-id` | 让视图完成 filter/sort projection,LLM 不擅长手工筛选排序,建议用视图完成。 | -| 统计 / 聚合结果且不需要 `record_id` | 转到 [`lark-base-data-query.md`](lark-base-data-query.md) | `data-query` 是特殊分析 DSL,不是记录读取工具。 | - -## 2. 字段投影 - -- `FieldListFirst`: 不清楚字段结构时先 `+field-list`,确认筛选字段、排序字段、展示字段、关联字段、业务唯一键字段。 -- `UseRealField`: 字段名和字段 ID 必须来自 `+field-list` 返回,不要凭自然语言猜字段名。 -- `MinimalProjection`: 每次读取只返回本次任务需要的字段;`+record-list` 用重复 `--field-id`,视图读取用 `+view-set-visible-fields`。 -- `FieldScopePriority`: 返回字段优先级为显式投影字段(`+record-list --field-id` / `record-search select_fields`) > 视图可见字段 > 全表字段;需要稳定列范围时必须显式投影。 -- `LongFieldAvoidance`: 默认不要读取 `trace`、`raw`、长文本、附件等高噪声字段,除非任务明确需要。 -- `BusinessKey`: 后续要定位、更新或解释记录时,投影中必须包含可识别业务字段,例如订单号、日报ID、姓名、编号。 - -## 3. 视图预处理 - -适用于结构化筛选、排序、最高/最低、倒数、Top/Bottom N、按条件找记录等场景。 - -1. `+field-list` 获取字段 ID、字段名和字段类型。 -2. `+view-create` 创建临时 `grid` 视图,名称带任务语义,例如 `tmp_query_销售额升序`。 -3. `+view-set-filter` 设置筛选条件;空值是否参与必须按用户语义判断。 -4. `+view-set-sort` 设置排序条件;最高/最新用降序,最低/最早/倒数用升序。 -5. `+view-set-visible-fields` 设置投影字段,只保留业务键、排序字段、筛选解释字段、需要展示或二跳的字段。 -6. `+record-list --view-id --limit ` 读取结果;不要再从未排序全表输出中手动挑选。 - -## 4. 分页与范围 - -- `ViewScope`: URL 带 `view_id` 时先判断用户是否要求“该视图下”;全表问题不要误用 URL 视图范围,应该根据需求创建合适的临时视图完成查询任务。 -- `ViewIdScope`: `+record-list --view-id` 是作用域参数;仅用于用户指定的视图,或本次任务主动创建的临时筛选 / 排序 / 投影视图。 -- `NeedAllPages`: 用户要求全部、导出、统计、最高/最低且未用视图/limit 限定时,必须检查 `has_more` 并串行翻页。 -- `LimitWhenScoped`: 用户只要示例、前 N 条、Top/Bottom N,使用 `--limit` 控制结果规模。 -- `NoConcurrentList`: `+record-list` 禁止并发调用;分页和多表读取必须串行。 -- `DataQueryScope`: `data-query` 的筛选 DSL 与视图筛选不是同一套语法;不要混用。 - -## 5. 返回结构解释 - -- `ColumnMapping`: `fields` / `field_id_list` 定义 `data` 每列含义;解释记录前先建立列到字段名的映射。 -- `RowMapping`: `record_id_list[i]` 与 `data[i]` 是同一行;需要后续定位、更新或关联时,按下标整理成 `record_id + 字段名:值` 的小表。 -- `BusinessMatch`: 后续引用目标记录时按业务字段匹配,不靠肉眼数行号。 -- `FieldType`: 按字段类型解释值;数字、货币、日期、人员、formula、lookup、attachment、link 不要当普通文本处理。 -- `EmptyValue`: 空值参与筛选或排序前必须明确语义;不要默认把空值当 `0`、空字符串或有效状态。 -- `AnswerCheck`: 最终回答前复核答案记录来自读取结果、筛选排序已应用、字段含义和 record_id 映射无误。 - -## 6. link 关联字段读取 - -link 字段是关联单元格;读取结果通常是关联表的 `record_id` 数组,不是用户可读名称。 - -| 步骤 | 做法 | -|------|------| -| 识别 link 字段 | 用 `+field-list` 查看字段类型为 `link`,并读取 `link_table` 确认关联目标表。 | -| 读取当前表 | 在当前表 `+record-list` / `+record-get` 中保留 link 字段和业务键字段。 | -| 解析单元格值 | link 单元格通常形如 `[{"id":"rec..."}]`;提取其中每个 `id` 作为关联表 `record_id`。 | -| 读取关联表 | 到 `link_table` 使用 `+record-get --record-id ` 或裁剪后的 `+record-list` 读取显示字段。 | -| 建立映射 | 形成 `关联record_id -> 显示字段值` 映射,再回填当前表结果。 | -| 多值处理 | 多个关联值保持原顺序;可去重批量读取,但回答时按原单元格顺序输出。 | - -禁止事项: - -- 不要把 link 单元格里的 `record_id` 当作最终答案。 -- 不要用 `+record-search` 搜索 link `record_id` 来查关联记录。 -- 不要凭关联 `record_id` 猜名称、负责人、门店等显示值。 -- 不要只看当前表字段名推断关联表结构;跨表读取前必须拿关联表字段结构。 - -## 7. 命令 help - -- `HelpFirst`: 参数、示例、JSON shape 和取值约束以 `lark-cli base +record-get --help`、`+record-search --help`、`+record-list --help` 为准。 -- `RecordSearchJson`: 构造 `+record-search --json` 前先看 `+record-search --help`,确认 `keyword/search_fields/select_fields/view_id/offset/limit` 的结构和约束。 -- `RecordListProjection`: 构造 `+record-list` 前先看 `+record-list --help`,确认 `--field-id`、`--view-id`、`--offset`、`--limit` 的语义。 - -## 参考 - -- [lark-base-view-set-filter.md](lark-base-view-set-filter.md) -- [lark-base-view-set-sort.md](lark-base-view-set-sort.md) -- [lark-base-view-set-visible-fields.md](lark-base-view-set-visible-fields.md) -- [lark-base-data-query.md](lark-base-data-query.md) diff --git a/skills/lark-base/references/lark-base-record.md b/skills/lark-base/references/lark-base-record.md index 79af29188..66df82aba 100644 --- a/skills/lark-base/references/lark-base-record.md +++ b/skills/lark-base/references/lark-base-record.md @@ -8,7 +8,7 @@ record 相关命令索引。 | 文档 | 命令 | 说明 | |------|------|------| -| [lark-base-record-read-sop.md](lark-base-record-read-sop.md) | `+record-get` / `+record-search` / `+record-list` | 记录读取统一选路、筛选排序投影 SOP | +| [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md) | `+record-get` / `+record-search` / `+record-list` / `+data-query` / 视图筛选排序 | 数据查询与分析统一选路、筛选排序投影、聚合后回查明细 SOP | | [lark-base-record-upsert.md](lark-base-record-upsert.md) | `+record-upsert` | 创建或更新记录 | | [lark-base-record-batch-create.md](lark-base-record-batch-create.md) | `+record-batch-create` | 按 `fields/rows` 批量创建记录 | | [lark-base-record-batch-update.md](lark-base-record-batch-update.md) | `+record-batch-update` | 批量更新记录 | @@ -19,7 +19,7 @@ record 相关命令索引。 ## 说明 -- 读取记录前优先阅读 [lark-base-record-read-sop.md](lark-base-record-read-sop.md),它合并了 `+record-get` / `+record-search` / `+record-list` 的选路和 SOP。 +- 读取记录前优先阅读 [lark-base-data-analysis-sop.md](lark-base-data-analysis-sop.md),它合并了 `record / view / data-query` 的选路、分页、投影、聚合后回查明细和 link 关联读取。 - 聚合页只保留目录职责;写入、删除、历史等命令的详细说明请进入对应单命令文档。 - 所有 `+xxx-list` 调用都必须串行执行;若要批量跑多个 list 请求,只能串行执行。 - `+record-list` 支持重复传参 `--field-id` 做字段筛选。