feat: add base record filter and sort json flags

[zgz2048]

Summary

• add --filter-json and --sort-json to Base +record-list and +record-search
• support @file input and view-compatible filter/sort JSON shapes, including sort_config normalization
• update lark-base guidance to prefer record filter/sort for raw record queries and keep +data-query for aggregation

Validation

• go test ./shortcuts/base
• git diff --check
• git diff --cached --check

Summary by CodeRabbit

• New Features

  • Added --filter-json and --sort-json for record listing/search; --json is now optional (escape hatch).
  • Improved search/list request construction to accept flag-based filter/sort and view scoping.

• Bug Fixes / Validation

  • Stricter flag validation (JSON shapes, required keyword/search-field when needed, sort limits, mutual exclusivity).

• Documentation

  • Expanded skill/SOP guidance and examples on when to use record vs data-query commands.

• Tests

  • Expanded unit and integration tests covering filter/sort parsing, request shapes, and dry-run scenarios.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bcdbe06a-22b9-4b6a-954d-da722df90069

📥 Commits

Reviewing files that changed from the base of the PR and between 91186c2 and 60f47b5.

📒 Files selected for processing (1)

• shortcuts/base/record_query_test.go

---

📝 Walkthrough

Walkthrough

Adds --filter-json and --sort-json flags with parsing/normalization and validation, wires them into record-list/search dry-run and execute flows, updates help and validation behavior, adds unit/integration tests, and revises docs to prefer structured queries for record reads.

Changes

Record filtering and sorting via CLI flags

Layer / File(s)	Summary
Record query flag definitions and shared body builders shortcuts/base/record_query.go	New file adding --filter-json/--sort-json parsing, sort normalization (array or wrapped sort_config), marshalling helpers, and functions to apply parsed queries to params, URL values, and request bodies; builds search bodies for both flag-based and --json modes and centralizes validation.
Record-list flag integration and validation shortcuts/base/record_list.go	Adds recordFilterFlag() and recordSortFlag() to BaseRecordList, updates Tips with filter/sort examples, and introduces Validate to run format and query option validation.
Record-search flag updates and validation shortcuts/base/record_search.go	Repositions --json as an escape hatch (removed Required: true), revises Tips to include filter/sort examples and pagination guidance, and switches Validate to validateRecordSearchFlags().
Record operations wiring for query flags shortcuts/base/record_ops.go	Applies query flags in dry-run/execute paths via applyRecordQueryToURLValues() and applyRecordQueryToParams(), and conditionally builds search bodies from recordSearchJSONBody() or recordSearchFlagBody() depending on --json.
Dry-run test coverage for filter and sort shortcuts/base/base_dryrun_ops_test.go	Adds dry-run scenarios exercising record-list with filter-json+sort-json (verifying encoded GET URL fragments) and record-search with keyword/view/filter/sort (verifying POST body serialization).
Execution test coverage for filter, sort, and search variants shortcuts/base/base_execute_test.go	Updates BaseRecordSearch execution test to use richer --json (filter/sort/pagination), adjusts assertions for filter/sort, and adds subtests for flag-based --filter-json+--sort-json and --filter-json @file``.
Help text and validation test expectations shortcuts/base/base_shortcuts_test.go	Updates help/tips expectations and expands TestBaseRecordValidate to require non-nil Validate hooks and assert --filter-json type rules, --sort-json limits, keyword/search-field requirements, and --json exclusivity.
Documentation updates on query tool selection and patterns skills/lark-base/SKILL.md, skills/lark-base/references/lark-base-data-analysis-sop.md, skills/lark-base/references/lark-base-data-query-guide.md, skills/lark-base/references/lark-base-data-query.md	Rewrites guidance to prefer structured query flags for record reads, clarifies +data-query for aggregation and that data-query dimension rows exclude record_id, and adjusts view/pagination/aggregation SOP language.
Unit tests for record query parsing and application shortcuts/base/record_query_test.go	New unit tests cover sort normalization, applying query flags to params and URL values, JSON-body search behavior and overrides, and wrapped sort_config normalization.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#328: Extends initial +record-search JSON passthrough with shared filter/sort query builders and validation wiring in the same dryRunRecordSearch, executeRecordSearch, and related test paths.
• larksuite/cli#458: Tightens JSON input handling and validation that relates to --json parsing and validateRecordJSON behavior used by record commands.

Suggested reviewers

• kongenpei
• zhouyue-bytedance

Poem

🐰 Hopping through filters, I compile each line,
Sorts and queries twirl like ribbons fine,
Tests hum softly, tips align,
Records list and search in time,
A rabbit cheers: the flags behave—how divine!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the primary change: adding filter and sort JSON flags to Base record commands.
Description check	✅ Passed	The description covers the main changes and validation steps, though it lacks a detailed Change list and explicit Test Plan section from the template.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

❌ Patch coverage is 77.27273% with 40 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.22%. Comparing base (6d7f8ba) to head (60f47b5).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
shortcuts/base/record_query.go	78.20%	17 Missing and 17 partials ⚠️
shortcuts/base/record_ops.go	73.33%	2 Missing and 2 partials ⚠️
shortcuts/base/record_list.go	50.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1228      +/-   ##
==========================================
+ Coverage   69.20%   69.22%   +0.02%     
==========================================
  Files         634      635       +1     
  Lines       59517    59687     +170     
==========================================
+ Hits        41188    41320     +132     
- Misses      15014    15033      +19     
- Partials     3315     3334      +19     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@60f47b539f7276b88caf03389dd429840fd86298

🧩 Skill update

npx skills add zgz2048/cli#codex/base-record-filter-sort -y -g