docs(base): update location full_address guidance

[zgz2048]

Summary

Update Base skill guidance for location field full_address behavior, covering read/write, filtering, and type conversion semantics.

Changes

• Document that location writes accept only {lng,lat} and full_address is returned after platform resolution.
• Clarify that location filters match full_address text and should prefer contains/intersects over short exact matches.
• Clarify that location -> text conversion keeps full_address, and sync the Base domain template.

Test Plan

• node scripts/skill-format-check/index.js skills
• make unit-test
• Manual local verification: lark-cli base --help

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Clarified geographic location field handling, including recommended write format ({lng,lat}), read-side preferences (full_address), and filtering best practices using address text matching.
  • Updated version to 1.2.1.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR updates skill and reference documentation to standardize location field behavior across the Lark Base platform. Changes clarify that location writes use minimal {lng,lat} format, while reads, filters, and conversions to text operate on the derived full_address field, with recommendations to use contains/intersects matching for address-based queries.

Changes

Location field specification and reference docs

Layer / File(s)	Summary
Field specification and templates skills/lark-base/SKILL.md, skill-template/domains/base.md	Skill version bumped to 1.2.1; location field added to field classification table with write shape {lng,lat} and read preference for full_address; location write guidance added to mental model section; template domain rules document write, read, filter, and conversion behavior.
CellValue write/read guidance skills/lark-base/references/lark-base-cell-value.md, skills/lark-base/references/lark-base-shortcut-field-properties.md	Write format restricted to numeric {lng,lat} object; full_address must not be manually provided as it is platform-derived from coordinates; read/filter/text conversion must prefer full_address; address text without confirmed coordinates must not be used as location CellValue.
Filter and query behavior skills/lark-base/references/lark-base-data-query.md, skills/lark-base/references/lark-base-view-set-filter.md	Location filtering documented to operate on full_address plain text only; text and location filter sections separated with independent examples; intersects/contains matching recommended for city/district lookups; exact == matching discouraged except when filter value matches complete full_address.
Type conversion rules skills/lark-base/references/lark-base-field-update.md	Location-to-text conversion rule tightened to preserve only full_address field.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• larksuite/cli#748: Updates to lark-base-field-update.md in the field-type conversion rules for text target type; this PR further refines location-to-text conversion to preserve only full_address.
• larksuite/cli#636: Previous update to lark-base-cell-value.md location CellValue guidance; this PR extends those rules across reference materials and top-level specs to maintain consistency.

Suggested reviewers

• kongenpei
• zhaoleibd

Poem

🐰 A location field hops into view,
coordinates bloom in {lng, lat} true,
full_address reads and filters anew,
📍 Geography rendered pure through and through! ✨

🚥 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 'docs(base): update location full_address guidance' clearly and specifically describes the main change: updating documentation about location field behavior in the Base skill.
Description check	✅ Passed	The PR description covers all key required sections: Summary explains the change scope, Changes lists the main updates with specific examples, Test Plan documents verification steps executed, and Related Issues is addressed.
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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.76%. Comparing base (5c01a7f) to head (1bdb475).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #754      +/-   ##
==========================================
- Coverage   67.77%   67.76%   -0.02%     
==========================================
  Files         590      590              
  Lines       55194    55194              
==========================================
- Hits        37406    37400       -6     
- Misses      14677    14682       +5     
- Partials     3111     3112       +1     

☔ 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@1bdb4754d46a6a5e6e37f15fdec443009fc728ac

🧩 Skill update

npx skills add zgz2048/cli#codex/base-location-full-address-skill -y -g

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@skill-template/domains/base.md`:
- Line 37: Update the wording under the "**地理位置字段**" section to make `{lng,lat}`
mandatory (not optional); replace language like "推荐写入 `{lng,lat}`" with a clear
requirement such as "必须写入 `{lng,lat}` 且只接受 `{lng,lat}` 格式" and keep the rest
(use `full_address` for read/filter/convert and use contains-match for
filtering) intact so readers know reads/filters still prefer `full_address`
while writes must supply `{lng,lat}`.

In `@skills/lark-base/SKILL.md`:
- Line 219: Change the table row for 地理位置字段 to state that writes accept only the
{lng,lat} format (replace wording like "推荐写入形状是 `{lng,lat}`" with a mandatory
phrase such as "仅接受写入格式 `{lng,lat}`；`full_address` 不能直接写入") and add a brief note
in the explanation column that filtering should prioritize contains-matching
(match the "筛选优先用包含匹配" guidance from base.md) so readers know both the required
write format and the expected filter strategy.

🪄 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: fc769087-d38a-4e8b-8a71-30e848f259a7

📥 Commits

Reviewing files that changed from the base of the PR and between 9ff0d21 and 6007d6a.

📒 Files selected for processing (7)

• skill-template/domains/base.md
• skills/lark-base/SKILL.md
• skills/lark-base/references/lark-base-cell-value.md
• skills/lark-base/references/lark-base-data-query.md
• skills/lark-base/references/lark-base-field-update.md
• skills/lark-base/references/lark-base-shortcut-field-properties.md
• skills/lark-base/references/lark-base-view-set-filter.md

✅ Files skipped from review due to trivial changes (5)

• skills/lark-base/references/lark-base-data-query.md
• skills/lark-base/references/lark-base-shortcut-field-properties.md
• skills/lark-base/references/lark-base-view-set-filter.md
• skills/lark-base/references/lark-base-field-update.md
• skills/lark-base/references/lark-base-cell-value.md