base

When to use

Use this skill:

• The user explicitly mentions Base / Bitable, or provides a /base/ link.
• The user wants to build tables, modify tables, manage fields, write records, query records, or configure views within a Base.
• The user wants to perform formula fields, lookup fields, cross-table calculations, derived metrics, filtering/aggregation, TopN, or statistical analysis within a Base.
• The user wants to manage Base forms, dashboards, workflows, advanced permissions, or roles.
• The user wants to migrate old Base aggregate commands or legacy syntax to the current lark-cli base +... shortcut.

Do not use this skill:

• For authentication, initialization, identity switching, scope handling, or permission authorization recovery; redirect to lark-shared.
• To import local Excel / CSV / .base files into Base; redirect to lark-drive +import --type bitable.
• For generalized data analysis, field design, or formula discussions that lack Base/Bitable context.

Usage boundaries

• Base business operations must only use the lark-cli base +... shortcut; do not use legacy aggregate commands like +table / +field / +record / +view / +history / +workspace.
• This Base skill does not depend on lark-cli schema. The SKILL only retains routing, risk management, and complex JSON/DSL; simple commands are handled by the command's own parameters, tips, and error recovery.
• When a user wants to import Excel / CSV / .base into Base, first redirect to lark-cli drive +import --type bitable, and return to Base commands after the import is complete.
• When a user only provides a Base name or keyword, first use lark-cli drive +search --query <keyword> --doc-types bitable to locate the resource.
• Base commands must have a base_token or a resolvable Base URL. If no token is available: if the user wants to create a new one, use +base-create; if the user provides a title/keyword, search using lark-cli drive +search --query "<base title>" --doc-types bitable --only-title --as user; if it still cannot be located, ask the user to specify which Base they mean.
• Authentication, initialization, scope, identity switching, and permission recovery belong to lark-shared; the Base documentation only retains permission rules that affect Base path selection.

Quick routing

Base mental model

• Base was formerly known as Bitable; bitable in returned fields, errors, or legacy documents is for historical compatibility and does not mean you should switch to raw APIs or a different set of commands.
• +base-block-list is the new entry point for viewing a resource directory within a Base: it lists folder/table/docx/dashboard/workflow directly managed by the Base, suitable for determining what is in the Base before deciding to use table, dashboard, workflow, or docx commands.
• base-block is only responsible for resource directory management, including creating resources, moving to folders, renaming, and deleting; specific resource content still uses table/dashboard/workflow commands.
• Names and IDs of tables, fields, views, workflows, and dashboard blocks must come from real returns; do not guess based on user descriptions.
• Storage fields are writable; system fields, formula, and lookup are read-only; attachment fields use dedicated attachment commands.
• For one-time raw record queries, prioritize +record-list / +record-search filter/sort; for aggregate analysis, prioritize +data-query; only add formula / lookup fields when long-term display in the table is required.
• formula is suitable for routine calculations, conditional logic, text/date processing, and long-term derived metrics; lookup is suitable for explicit cross-table lookups, filtered value retrieval, or aggregate references.
• Before writing, analyzing, using formulas, lookups, workflows, or dashboards, read the real structure: table, field, view, linked table, and dashboard block names must be based on command returns.
• Cross-table scenarios must read the target table structure; the associated record_id in link cells is just a connection key; the final answer must look up and display user-readable fields.

Identity and permission degradation

• By default, explicitly use --as user to operate on user resources; only use --as bot when the user explicitly requests application identity.
• If user identity reports scope/authorization insufficiency, or errors contain permission_violations / hint, first redirect to lark-shared for user authorization recovery; do not downgrade to bot directly.
• Only retry once with --as bot if user identity reports resource-level access denial without authorization recovery hints; if bot still fails, stop retrying and handle as a permission error.
• Do not loop identity switching for 91403 or explicit access errors.
• If +base-create / +base-copy is executed with bot identity, pay attention to permission_grant in the return and inform the user whether they can open the new Base.

Query and statistical rules

When involving queries, statistics, or conclusions, first read lark-base-data-analysis-sop.md and comply with:

1. The default page, fixed --limit, and local jq of +record-list only prove facts within the read range; they cannot support global extremes, total counts, Top/Bottom N, anomaly identification, or grouping conclusions.
2. Filtering, sorting, projection, aggregation, grouping, and limits that can be expressed by Base should be executed in Base cloud query capabilities; do not pull raw records to local context for manual filtering/sorting.
3. has_more=true or equivalent pagination signals indicate the current result is not exhaustive; unless the user only wants samples/first N items, do not answer global questions based on that page.
4. Multi-table queries must first confirm relationship fields and connection keys; the record_id in link cells is a relationship key, not a user-readable answer.
5. The final answer must be traceable to the real table, real field, query scope, filter/sort/aggregation conditions, and necessary connection keys.
6. For one-time raw record queries, prioritize +record-list / +record-search filter/sort; for aggregate analysis, prioritize +data-query; only consider adding formula / lookup fields if the result needs to be displayed in the table long-term.
7. +data-query can return aggregate results or dimension field rows, but dimension rows are deduplicated by field combinations and do not return record_id; use +record-list / +record-search / +record-get to look up individual records, record locations, or full row-level fields.

Writing prerequisites

• Read field structure before writing records; only write to storage fields. System fields, attachment fields, formula, and lookup are not written as normal records.
• Attachment upload, download, and deletion use dedicated +record-*-attachment commands.
• Read lark-base-field-json.md before writing fields; for formula / lookup, must read formula-field-guide.md / lookup-field-guide.md.
• Table names, field names, view names, and names in workflow configurations must come from real returns; cross-table scenarios also require reading the target table structure.
• High-risk operations like deletion, role updates, and field updates follow the CLI confirmation gate; use get/list to disambiguate when targets are unclear.
• Batch writes are limited to 200 items per batch; execute serially when writing to the same table, and handle 1254291 by waiting briefly between retries.
• +record-batch-update is for "same-value batch updates": the same patch is applied to all record_id_list; do not use it for row-by-row different value mapping.
• Writing unknown options to select/multiselect may trigger new options on the platform; if not intended, use +field-list or +field-search-options to confirm available values.

Form and view details

• Before +form-submit, must run +form-detail to read questions[].type, required, filter, and the base_token required for attachment scenarios; do not fill in questions hidden by filters.
• Do not write form attachments into fields; place them in --json.attachments; when submitting attachments, must also pass the --base-token of the Base to which the form belongs.
• +view-set-filter is the only retained view reference; for configurations like sort/group/card/timebar/visible-fields, first use the corresponding get command to read the current status, retain unmodified fields, and only replace configurations the user requested to change.
• Views are suitable for persistence, sharing, and UI reuse; for one-time filtering/sorting, use +record-list / +record-search filter/sort to verify results before settling into a persistent view.

Tokens and links

When wiki +node-get returns non-bitable, do not continue using Base commands: redirect docx to document commands, sheet to spreadsheet commands, and other cloud objects to corresponding skills or drive.

Dashboard / Workflow / Role

• The complexity of Dashboards lies in the data_config of blocks, not in list/get/create/delete command parameters. Read dashboard-block-data-config.md before creating or updating blocks; components must be created serially; +dashboard-arrange is server-side intelligent layout, only execute when the user explicitly requests rearrangement/beautification. +dashboard-block-get-data reads the final chart calculation results and does not return block name, type, layout, or data_config; for metadata, use +dashboard-block-get first.
• The complexity of Workflows lies in the steps structure. Read the entry lark-base-workflow-guide.md and steps JSON SSOT lark-base-workflow-schema.md when creating, updating, or explaining a full workflow; enable/disable/list only require confirming workflow ID, current status, and user intent.
• The complexity of Roles lies in the permission JSON. For role operations, first read the entry lark-base-role-guide.md; +role-create only supports custom roles; +role-update is a delta merge; read permission JSON SSOT role-config.md when creating/updating roles or interpreting full configurations. +role-delete only applies to custom roles; system roles cannot be deleted; confirm target and impact before deleting roles or disabling advanced permissions.

Common recovery

Retained References

• lark-base-data-analysis-sop.md: SOP for query/statistics/global conclusions
• lark-base-data-query-guide.md / lark-base-data-query.md: Aggregate query entry fewshot and DSL SSOT
• lark-base-cell-value.md: Record CellValue construction
• lark-base-field-json.md: Field JSON construction
• formula-field-guide.md / lookup-field-guide.md: Formula and lookup fields
• lark-base-field-create.md / lark-base-field-update.md: Field creation/update command-level supplement
• lark-base-record-upsert.md / lark-base-record-batch-create.md / lark-base-record-batch-update.md / lark-base-record-history-list.md: Record write JSON and history return explanation
• lark-base-view-set-filter.md: View filter JSON
• lark-base-form-detail.md / lark-base-form-submit.md / lark-base-form-questions-create.md / lark-base-form-questions-update.md: Form details, submission, and complex JSON
• lark-base-dashboard.md / dashboard-block-data-config.md / lark-base-dashboard-block-get-data.md: Dashboard, component configuration, and chart result protocol
• lark-base-workflow-guide.md / lark-base-workflow-schema.md: Workflow entry and steps JSON SSOT
• lark-base-role-guide.md / role-config.md: Role entry and permission JSON SSOT