docs(lark-base): add known API pitfalls to skill references

[flyinghanger]

Summary

Three production-verified gotchas that were not documented in the skill references:

• +base-create: A newly created Base contains empty records in its default table. These should be cleaned up with +record-delete before writing data to avoid dirty rows.
• +field-update: (1) Updating the primary field (is_primary: true) requires an explicit type in the JSON payload, otherwise the API returns 99992402 field validation failed. (2) select/multiselect options are fully overwritten on PUT — if you only intend to update the description, you must include the existing options array or all option values will be lost.
• +field-create: A link field is bound to one fixed table per column. Different rows in the same column cannot point to different tables. Use a naming convention (e.g. a text field storing the target table name) instead.

Test plan

• Read through the three updated reference docs for clarity

Summary by CodeRabbit

• Documentation
  • Added a "Pitfalls" note to Base creation docs: Bases auto-create a default table with an empty record; users must remove that empty record before writing data to avoid dirty entries.
  • Clarified link-field constraint: a link field can reference only one fixed target table; use alternative text+naming approaches for multi-table links.
  • Warned that select/multiselect updates are full replacements — omitting options clears them; retrieve and include existing options when updating.

[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: b240f4a6-d014-4edf-9c10-c5b29fb44e8a

📥 Commits

Reviewing files that changed from the base of the PR and between 8432a8c and 7b4122e.

📒 Files selected for processing (1)

• skills/lark-base/references/lark-base-field-update.md

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

• skills/lark-base/references/lark-base-field-update.md

---

📝 Walkthrough

Walkthrough

Documentation updates to three Lark Base reference pages: Base creation warns that creating a Base auto-generates default empty records and explains how to remove them; field-creation clarifies link must reference a single fixed link_table; field-update documents that select/multiselect updates fully replace options and omitting them clears existing options.

Changes

Cohort / File(s)

Summary

Base & Field reference updates skills/lark-base/references/lark-base-base-create.md, skills/lark-base/references/lark-base-field-create.md, skills/lark-base/references/lark-base-field-update.md

Added operational warnings: Base creation auto-generates default empty records (advise using +record-list to find record_id and +record-delete --yes to remove); link fields are fixed to a single link_table and cannot mix target tables; select/multiselect updates use full-replacement semantics — omitting options clears them, so callers must include complete options when updating non-options attributes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hop through notes and tidy signs,
Found empty rows in freshly made lines,
Links must point to one true door,
Keep options whole — or they’re no more,
I nibble errors, then bounce off with a grin.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding documentation for known API pitfalls to Lark Base skill reference guides.
Description check	✅ Passed	The description covers the summary and changes sections well, but the test plan section is incomplete: it only lists a checkbox for reading docs without describing actual verification steps.
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 adds three production-verified API pitfalls to lark-base skill references: empty default-table records on Base creation, the link-field fixed-table constraint, and select/multiselect full-overwrite behavior on PUT. The documented content is accurate, but the is_primary + type pitfall explicitly described in the PR summary — updating a primary field without type causes API error 99992402 — is absent from the actual diff and is not documented anywhere in the codebase.

Confidence Score: 4/5

Safe to merge after adding the missing is_primary pitfall that is described in the PR description but absent from the diff.

Two of the three claimed +field-update pitfalls are correctly documented. The third — primary-field update requiring explicit type — is entirely missing from the changes, leaving a gap between what the PR claims to document and what it actually documents.

skills/lark-base/references/lark-base-field-update.md is missing one of the three pitfalls described in the PR.

Important Files Changed

Filename	Overview
skills/lark-base/references/lark-base-base-create.md	Adds '坑点' section warning about empty default-table records after Base creation; advice is accurate.
skills/lark-base/references/lark-base-field-create.md	Adds link-field fixed-table constraint to both the JSON spec bullet and the pitfalls section; content is correct.
skills/lark-base/references/lark-base-field-update.md	Documents select/multiselect full-overwrite pitfall correctly, but omits the is_primary+type pitfall claimed in the PR description.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[+base-create] --> B[Auto-generated default table\nwith empty records]
    B --> C{Need to write data?}
    C -->|Yes| D[+record-list to find empty rows\n+record-delete --yes to clean up]
    C -->|No| E[Proceed normally]

    F[+field-create: link type] --> G[Fixed to one target table per column\nRows cannot point to different tables]
    G --> H[Workaround: text field\n+ naming convention]

    I[+field-update] --> J{Field type / property?}
    J -->|select / multiselect| K[PUT is full overwrite\nMissing options = all options cleared]
    K --> L[+field-get first, then\ninclude full options array]
    J -->|is_primary: true field| M[Must include explicit 'type'\nor API returns 99992402]
    M --> N[⚠️ NOT yet documented\nin this PR]

Loading

_{Reviews (3): Last reviewed commit: "docs(lark-base): remove redundant is_pri..." | Re-trigger Greptile}

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@8432a8c44ce01a3b158a260531535cc19a3e35d2

🧩 Skill update

npx skills add flyinghanger/cli#fix/lark-base-pitfalls -y -g

[kongenpei]

Thank you for the contribution.

1. On record cleanup, we are documenting this pitfall for now while we look for a better solution.
2. For +field-update, type is required for all fields, and this is already documented in the skill markdown.
3. For the link field, could you share the exact bad case you hit (trigger condition, actual behavior, expected behavior)? We can add a concrete example based on it.

[flyinghanger]

Thanks for the review! Replies inline:

1. Empty record cleanup — Acknowledged, looking forward to a built-in solution.

2. type requirement on +field-update — You're right, it's already covered by the existing 值规范 line ("至少显式包含 name、type"). I've removed the redundant is_primary-specific bullet in 7b4122e.

3. link field bad case:

   • Trigger: Main table where each record represents a "tool"; each tool has its own dedicated child table (e.g. ToolA_runs, ToolB_runs, …). I wanted a single link column on the main table where row 1 (ToolA) links to records in ToolA_runs, row 2 (ToolB) links to records in ToolB_runs, etc.
   • Actual: link_table is a property of the field itself, fixed at +field-create time. All rows in that column must reference the same single table — there is no row-level link_table override.
   • Expected (from a user coming from relational DBs): hoped that a link field could behave like a polymorphic foreign key, or at least allow per-row target table.
   • Workaround I used: dropped the link field entirely; stored the target table name as a plain text field via a naming convention, and resolved the link client-side.

   Happy to fold this into a concrete example in the doc if you'd like — just let me know whether you prefer it under +field-create 坑点 or as a separate "field design notes" doc.