From c0257564bf7cf791417da576caf5e17f0e304d42 Mon Sep 17 00:00:00 2001 From: kongenpei Date: Wed, 1 Apr 2026 16:45:23 +0800 Subject: [PATCH 1/2] docs(lark-base): add has_more paging guidance for record-list --- skills/lark-base/SKILL.md | 2 +- .../references/lark-base-record-list.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index fc710842..cd0cf32d 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -155,7 +155,7 @@ metadata: - **Base token 口径统一**：统一使用 `--base-token` - **`+xxx-list` 调用纪律**：`+table-list / +field-list / +record-list / +view-list / +record-history-list / +role-list / +dashboard-list / +dashboard-block-list / +workflow-list` 禁止并发调用；批量执行时只能串行 -- **`+record-list` limit 上限**：`--limit` 最大 `200`。需要更多数据时必须用分页（`offset` 递增）分批拉取，禁止单次传超过 `200` +- **`+record-list` 分页规则**：`--limit` 最大 `200`。先拉首批并检查返回 `has_more`；仅当 `has_more=true` 且用户明确需要更多数据（如“全部导出/全量明细/继续下一页”）时再继续翻页。用户只要样例或前 N 条时，不要继续拉全量 - **字段可写性先判断**：存储字段才可写；公式 / lookup / 系统字段默认只读，写记录时应跳过 - **公式能力要主动想到**：用户说“算一下”“生成标签”“判断是否异常”“跨表汇总”“按日期差预警”时，要先判断是否应该建公式字段，而不是只返回手工分析方案 - **lookup 不是默认首选**：lookup 只在用户明确要求或确实更适合固定查找模型时使用；常规计算、跨表聚合和条件判断优先 formula diff --git a/skills/lark-base/references/lark-base-record-list.md b/skills/lark-base/references/lark-base-record-list.md index 308fd759..64c7ac8f 100644 --- a/skills/lark-base/references/lark-base-record-list.md +++ b/skills/lark-base/references/lark-base-record-list.md @@ -4,6 +4,24 @@ 分页列出一张表里的记录；可按视图过滤。 +## 返回关键字段 + +| 字段 | 类型 | 说明 | +|------|------|------| +| `items` | array | 当前页记录列表 | +| `total` | number | 满足条件的记录总数 | +| `has_more` | boolean | 是否还有下一页数据；`true` 表示可继续翻页，`false` 表示已到末页 | + +## 分页执行规则（给智能体） + +1. 先执行一次 `+record-list` 获取首批结果。 +2. 检查返回的 `has_more`。 +3. 仅当同时满足以下条件时才继续翻页： + - `has_more = true` + - 用户问题需要更多数据（例如“全部导出”“统计全量明细”“继续加载下一页”） +4. 若用户只要部分结果（例如“先看前 20 条”“先给示例数据”），即使 `has_more = true` 也不继续翻页。 +5. 继续翻页时，`offset` 按已读取数量递增，直到满足用户需求或 `has_more = false`。 + ## 推荐命令 ```bash @@ -46,6 +64,7 @@ GET /open-apis/base/v3/bases/:base_token/tables/:table_id/records - ⚠️ `+record-list` 禁止并发调用；批量拉多个视图或多张表时必须串行。 - ⚠️ `--limit` 最大 `200`，不要传超过 `200` 的值。 +- ⚠️ 分页时优先根据返回的 `has_more` 判断是否继续请求，不要盲目预拉全量数据。 - ⚠️ 复杂筛选优先落到视图里，再用 `--view-id` 读取。 ## 参考 From a63815bddfd272996fdf349de191cb87758c6a3c Mon Sep 17 00:00:00 2001 From: kongenpei Date: Wed, 1 Apr 2026 16:50:55 +0800 Subject: [PATCH 2/2] docs(lark-base): refine record-list key field and paging title --- skills/lark-base/references/lark-base-record-list.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/skills/lark-base/references/lark-base-record-list.md b/skills/lark-base/references/lark-base-record-list.md index 64c7ac8f..faaca74f 100644 --- a/skills/lark-base/references/lark-base-record-list.md +++ b/skills/lark-base/references/lark-base-record-list.md @@ -8,11 +8,9 @@ | 字段 | 类型 | 说明 | |------|------|------| -| `items` | array | 当前页记录列表 | -| `total` | number | 满足条件的记录总数 | | `has_more` | boolean | 是否还有下一页数据；`true` 表示可继续翻页，`false` 表示已到末页 | -## 分页执行规则（给智能体） +## 按需翻页规则 1. 先执行一次 `+record-list` 获取首批结果。 2. 检查返回的 `has_more`。