Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions skills/lark-base/references/lark-base-data-analysis-sop.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ Base 数据查询与分析任务的执行契约。覆盖记录读取、筛选、
- “最高、最低、最新、最早、Top、Bottom、总数、全部、异常、最大、最小、最多、最少、优先级最高”等全局语义,必须在 Base 云端查询服务中完成筛选、排序或聚合。
- `+record-search` 用于关键词检索字段的展示文本;可搜多类字段,但匹配的是文本表示(如人员命中 name),不要用它替代金额、状态、日期、空值等结构化条件。
- 不要依赖已有视图,除非用户明确指定该视图,或你已读取并验证其 filter/sort/projection 符合当前问题。
- 最终答案必须使用用户可读的展示值;内部 ID、`record_id`、关联记录 ID、open_id、编码字段只能作为连接键,不能替代最终答案,除非用户明确要求输出 ID
- 交付输出必须使用用户可读的真实字段值;内部 ID、`record_id`、关联记录 ID、open_id、编码字段只可作为连接键或定位键,不能替代最终输出,除非用户明确要求输出这些键值
- 每次读取必须做最小投影,并包含后续解释、回查或写入需要的业务 key。

## 1. Intent -> Tool Path
Expand All @@ -24,11 +24,11 @@ Base 数据查询与分析任务的执行契约。覆盖记录读取、筛选、
| --- | --- | --- |
| 看几条、预览、示例 | `+record-list --limit N` | 保持局部语义;不要推广为全局结论 |
| 已知 `record_id` | `+record-get` | 直接读取;不要 search/list 反查 |
| 明确关键词 | `+record-search` | 按字段展示文本命中;使用 `search_fields` 限定匹配范围、`select_fields` 投影降低返回内容 token 量 |
| 明确关键词 | `+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 明细 |
| 聚合后输出实体字段 | `+data-query` 得到业务 key -> record 路径回查明细 | `+data-query` 不返回原始记录或 link 明细;聚合结果中的 key 需要再解析成用户要求字段 |
| 多表 / 多跳关联 | 以候选数最小的事实表为驱动表,沿业务 key 或 link `record_id` 逐跳回查 | 读出 link 单元格里的关联 `record_id` 后,到被关联表批量 `+record-get` 展示字段,并在回答用结果中合并展示 |
| 查询后写入 / 视图化 | 先用本 SOP 得到可复核的目标记录 id 集合 | 再进入记录写入或视图配置;高价值可复用查询优先沉淀为持久视图 |

Expand All @@ -43,46 +43,46 @@ Base 数据查询与分析任务的执行契约。覆盖记录读取、筛选、
3. 设置 filter/sort/visible fields。
4. `+record-list --view-id <view_id> --limit <N>` 读取结果。

不要从未筛选、未排序的全表输出中手动挑选。一次性查询可用临时视图;如果这个筛选/排序结果对用户后续查看有价值,应保留为持久视图,不要删除,并在回答中告知用户视图名称和用途。视图参数细节见 view-set references。
不要从未筛选、未排序的全表输出中手动挑选。一次性查询可用临时视图;如果这个筛选/排序结果对用户后续查看有价值,应保留为持久视图,不要删除,并告知用户视图名称和用途。视图参数细节见 view-set references。

### 2.2 聚合分析与 TopN

使用 `+data-query`:

- 让 Base 云端查询服务完成 filters、dimensions、measures、sort、pagination.limit。
- `pagination.limit` 是 Base 云端查询服务中的聚合结果限制,不是本地分页扫描。
- 需要输出明细或名称时,先拿业务 key,再用 record 路径精确回查。
- 需要输出明细或用户可读字段时,先拿业务 key,再用 record 路径精确回查。
- 字段类型、日期 value、DSL shape 以 [lark-base-data-query.md](lark-base-data-query.md) 为准。

### 2.3 关系查询与回查

- link 单元格通常是关联表 `record_id` 数组,不是用户可读名称
- link 单元格通常是关联表 `record_id` 数组,不是用户可读内容,只是连接键
- 先用 `+field-list` 确认 link 字段的 `link_table`、业务唯一键和展示字段。
- 从驱动表拿到候选记录后,用关联 `record_id` 到关联表 `+record-get` 批量读取展示字段
- 多跳关系逐跳建立 `record_id/key -> 展示字段` 映射;最终输出业务名称或用户要求字段
- 从驱动表拿到候选记录后,用关联 `record_id` 到关联表 `+record-get` 批量读取记录内容
- 多跳关系逐跳建立 `record_id/key -> 用户可读字段` 映射;最终用户可读的信息
Comment thread
zgz2048 marked this conversation as resolved.

禁止:

- 把 link `record_id` 当最终答案
- 把 link `record_id` 当最终输出
- 用 `+record-search` 搜 link `record_id`。
- ID 猜名称、负责人、门店、供应商
- 基于 ID、自增编号、link 值做语义猜测;禁止依赖字段先验、样本记忆补全交付输出

## 3. Range & Pagination Contract

- `+record-list` 默认页、固定 `--limit`、本地 `jq`、shell 管道、手工浏览输出,都只覆盖已读取范围;超过 200 行不要把本地处理当作推荐路径。
- `has_more=true`、存在下一页 offset/page token、或返回行数等于 page size,都表示可能还有未读取数据。
- 对全局问题,只有 Base 云端查询服务已经通过 filter/sort/aggregate 收敛目标范围,或 `data-query` 已在云端完成聚合、排序和限制时,才可以用有限返回作答
- 对全局问题,只有 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 精确回查,最终答案是否来自关联表真实字段
- 最终答案能追溯到表、字段、筛选条件、排序/聚合条件和连接键。
- 如果涉及关系查询,是否按 `record_id` 或业务 key 精确回查,交付输出是否来自关联表真实字段
- 交付输出能追溯到表、字段、筛选条件、排序/聚合条件和连接键。

任一项无法确认时,继续查询或明确说明只能得到局部结论。
Loading