[Doc] base +record-list: 添加分页读取时 field_id_list 使用说明

[AKAZIK-py]

变更说明

在 skills/lark-base/references/lark-base-record-list.md 中添加了分页读取的最佳实践说明。

问题描述

使用 base +record-list 分页读取多维表格时，API 返回的 field_id_list 顺序在不同分页中可能不同。如果用硬编码索引定位字段，会导致：

• 第二页数据解析错误
• 数据匹配失败，程序误判为"读取完成"
• 数据遗漏但不报错

解决方案

文档中增加了：

1. 坑点说明：分页字段顺序不稳定
2. 分页最佳实践章节
3. 完整的 Python 代码示例
4. 如何获取 field_id 的方法

测试验证

• 本地阅读验证：文档格式正确
• 实际场景验证：解决了分页读取 254 条数据只匹配前 200 条的问题

---

这是实际开发中遇到的问题，希望能帮助其他开发者避免踩坑。

Summary by CodeRabbit

• Documentation
  • Added a warning about unstable field ordering across paginated record-list responses and the risk of mismatched positional data.
  • Added a pagination best-practices section advising re-evaluation of field order per page before extracting values.
  • Provided guidance and a concrete example workflow for retrieving field identifiers and mapping positional values to field IDs reliably across pages.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b55d5cd4-9e50-4191-9a68-842328d0987e

📥 Commits

Reviewing files that changed from the base of the PR and between d2df940 and 0db74d6.

📒 Files selected for processing (1)

• skills/lark-base/references/lark-base-record-list.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/lark-base/references/lark-base-record-list.md

---

📝 Walkthrough

Walkthrough

Added a warning that field_id_list ordering may change across paginated base +record-list responses and a "分页最佳实践" section with a Python example showing per-page retrieval of field_id_list, index validation, remapping rows to {field_id: value}, accumulation by target field, and a lark-cli base +field-list usage snippet.

Changes

Cohort / File(s)	Summary
Pagination Documentation skills/lark-base/references/lark-base-record-list.md	Added note about unstable field_id_list order across pages. Added "分页最佳实践" explaining the data[i][j] ↔ field_id_list[j] mapping risk, a Python example that fetches field_id_list per page, validates target field_id, converts rows to {field_id: value}, accumulates records, and demonstrates lark-cli base +field-list to obtain field_id.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related issues

• [Doc] base +record-list 分页读取时字段顺序不稳定的说明与最佳实践 #189: Documents the same paginated field_id_list ordering instability and recommends per-page field_id_list re-reading and remapping positions to field_id.

Poem

I nibble through pages, hop by hop,
Fields shuffle — then I stop,
Re-read each list, match id to bite,
Collecting values through the night,
Little rabbit, data held tight — 🐰✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description uses a custom format instead of the required template, missing key sections like Changes (as a bulleted list), Test Plan with checkboxes, and Related Issues.	Reformat the description to match the template structure: use '## Changes' with bullet points, add '## Test Plan' with checkboxes, and include a '## Related Issues' section.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: adding documentation about field_id_list usage when paginating with base +record-list.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR enriches lark-base-record-list.md with a well-motivated "分页最佳实践" section that warns developers about unstable field_id_list ordering across pages and provides a complete Python example that builds a {field_id: value} dict per row to sidestep the ordering problem. All four concerns raised in the previous review thread have been addressed. Two minor style issues remain in the snippet:

• id_idx = field_ids.index(ID_FIELD_ID) is computed for its side-effect (validation) but is never used; an explicit in check is cleaner.
• The dict comprehension uses range(len(field_ids)) with positional indexing into record_data, which raises IndexError on a shorter row; dict(zip(field_ids, record_data)) is safer and idiomatic.

Confidence Score: 5/5

Safe to merge — documentation-only change with no runtime impact; all prior P1 issues are resolved and only minor P2 style suggestions remain.

All previously raised P1/P0 concerns (undefined helper, wrong ordering of empty-records guard, unhandled ValueError) are fully addressed in this revision. The two remaining findings are P2 style suggestions (dead variable and fragile indexing) that do not affect the documentation's correctness or developer safety. P2-only PRs default to 5/5 per confidence guidance.

No files require special attention.

Important Files Changed

Filename	Overview
skills/lark-base/references/lark-base-record-list.md	Added pagination best-practices section with a Python code example; all prior P1 concerns (empty-records guard ordering, unhandled ValueError, undefined run_lark_cli) are now resolved; two minor P2 style issues remain: unused id_idx variable and fragile list-index loop that could be replaced with zip.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[load_all_records called] --> B[offset = 0]
    B --> C[run_lark_cli +record-list with offset]
    C --> D{records empty?}
    D -- Yes --> E[break — return all_records]
    D -- No --> F{ID_FIELD_ID in field_ids?}
    F -- No --> G[raise ValueError with helpful message]
    F -- Yes --> H[build record_dict per row using field_ids + record_data]
    H --> I[append to all_records, offset += len records]
    I --> J{has_more?}
    J -- No --> E
    J -- Yes --> C

Loading

_{Reviews (4): Last reviewed commit: "Doc: 添加分页读取时 field_id_list 使用说明" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@skills/lark-base/references/lark-base-record-list.md`:
- Around line 86-91: The snippet assumes ID_FIELD_ID exists in field_ids and
will raise ValueError; update the logic around computing id_idx (where
field_ids.index(ID_FIELD_ID) is used) to first check presence (e.g., if
ID_FIELD_ID not in field_ids) and handle it explicitly—either raise a clear,
human-readable error mentioning the missing field_id or skip/continue the
current page with a logged warning; ensure the repair touches the id_idx lookup
and the loop over records/record_data that uses sample_id and all_records so
paging does not break when the field is absent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0b2ba157-717b-4791-99df-6a7f5ffb83e8

📥 Commits

Reviewing files that changed from the base of the PR and between d4c051d and 698e25a.

📒 Files selected for processing (1)

• skills/lark-base/references/lark-base-record-list.md

[kongenpei]

感谢反馈！技术侧已经定位到问题原因，并且已经开始修复。我们会尽快同步修复进展和后续更新。

Thanks for the report. Our engineering team has identified the root cause and has already started the fix. We’ll share progress and follow-up updates as soon as possible.