DingTalk AI Table Skill

First Distinguish Operations, Usage, and Contract Review

When the user only asks to review return values or recovery plans, do not execute business operations, and do not expand to upstream write commands based on the business task. The discovery target is based on the user's original message; parameters summarized or passed by the Agent into the Skill are not new requests; do not rewrite "verify this reconciliation command" into "compare the reconciliation with the original creation command". Preserve the full atomic path or

Shortcut name that the user is verifying; do not make synonym substitutions. The original creation command mentioned in the background is not an additional discovery target.

When reviewing only one command, first obtain the compact Schema for that entry point once, then answer based on this result; do not query background commands in parallel or sequentially, and do not append synonymous entry points, full Schema, or Help. If

result

is not published, state that the structure is not public; do not infer fields from repeated queries or examples. Only when the user explicitly asks to compare multiple commands do you query each contract separately. Help/Schema is a local offline query; "do not execute online business" does not prohibit it; when the user explicitly prohibits any command, do not query and state that the contract has not been verified.

When during the review the user asks for the next read-only command, the answer should first provide the complete command that is based on the current contract and uses the original ID/verification key, and state that it has not been executed; then immediately give the key judgment and prohibited actions, followed by a brief explanation. Do not first expand tool procedures, Schema field tables, or long citations; do not bury the next step at the end of the analysis; when the read-only entry point or parameters cannot be determined, state the gap; do not guess. When no command is requested, first answer all of the user's security questions with a brief conclusion: whether replaying writes is allowed, which results should be retained or discarded, what prerequisites read-only recovery has, then explain as needed; do not leave key prohibited actions to sectioned explanations or a final summary. Clearly distinguish local offline contract verification, user-provided receipts, and still-unverified online status: the local Schema can only prove the command contract; it cannot prove that the business has been executed or that the remote state has been verified.

When only reviewing invalid cursor recovery, read the "Review Invalid Cursor Recovery Only" section at the beginning of record-query, focusing on the three boundaries: discarding old results, the UNAVAILABLE wait prerequisite, and the prohibition on replaying writes; do not proceed to the actual query flow later in that Reference, and do not infer permission to supplement writes from differences between old and new results.

The following intent routing takes priority over the general Schema navigation below. Usage inquiries and return value reviews for form sharing cannot share the same discovery path:

Request intent	The only contract query this time
Review return value, recovery plan, fault, or dry-run sample	Put the full entry being verified as-is into `dws schema --cli-path "aitable <original entry>" --compact --format json` ; keep `+` , do not switch to Help, and do not switch between atomic/Shortcut
Only ask about atomic `form share update` syntax	Only execute `dws aitable form share update --help` (do not query Schema instead)
Only ask about Shortcut syntax	Only query the compact Schema of that Shortcut

Minimal DWS Execution Contract

DingTalk business operations go only through the
```
dws
```
CLI; scripts explicitly published by this Skill can orchestrate
```
dws
```
and complete presigned file uploads. Structured reads use
```
--format json
```
; judge results based on actual returns.
Known leaves execute directly. Only when parameters or security semantics are uncertain, read at most once
```
dws schema --cli-path "aitable <leaf>" --compact --format json
```
; only when that compact leaf Schema is inconsistent with actual Cobra behavior, read
```
dws aitable <leaf> --help
```
for the same leaf. It is forbidden to explore commands through parent Help, product Help, or the full Catalog.
Do not guess commands, flags, fields, IDs, accounts, or times. Subsequent IDs must come from real returns; stop and disambiguate when there are zero hits, multiple candidates, or unclear types.
Parsing targets, reading context, and final execution must use the same profile; do not reuse userId, openDingTalkId, or openConversationId across organizations. Multi-account organizations use only the explicit default account with
```
isOrgCurrent=true
```
; when there is no default account, ask the user to specify; do not select the first item, most recently logged-in, or most recently used account.
Do not output or log credentials such as token, refresh token, appSecret, or webhook token; do not ask for credentials when the host has already injected authentication.
Write operations must conform to the user's explicit intent. Whether confirmation is needed is determined by the final Runtime gate and Schema; when the user has explicitly requested execution in this turn and the target and impact of a non-destructive write operation are unambiguous, that explicit instruction is the confirmation for this turn; the first call carries the
```
--yes
```
required by Runtime directly, without first creating
```
confirmation_required
```
. File import is a non-idempotent operation and still triggers the Runtime confirmation gate per the Golden Route; append
```
--yes
```
only after confirmation. Destructive or high-risk actions such as deletion or disabling automations must first explain the object, action, and impact and obtain independent confirmation.
After writing, verify according to the task result contract; do not claim success based solely on the exit code. Partial results, unknown delivery statuses, and failed items must be faithfully retained.
Runtime Schema is the authoritative source for current capabilities and security semantics; within the same leaf task, read it once and reuse. Read leaf Help only when the Schema is missing fields, unclear, or conflicts with actual execution; invalidate the cache immediately when versions, profiles change, or contract errors appear.
Mutation returns, HTTP 200, and exit code 0 are only call receipts, not the final object state. After writing, clear affected read caches and initiate an independent read-back using the real ID/unique key returned; do not reuse pre-write results.
Writes to the same Base are serial by default; controlled concurrent writes are allowed only when they target different Bases, have no data/ID/order dependencies, and failures can be read back independently. Independent read-only calls default to a maximum of 4-way concurrency.
When a write call times out, the connection is interrupted, or the returned result is unknown, do not automatically replay it as-is; first check the real state. Read-only calls may retry transient errors with a cap.
Structured results may use a unified
```
ok/outcome
```
, legacy
```
status
```
, or boolean
```
success
```
envelope; do not assume a fixed
```
data
```
layer.
```
partial_failure
```
may appear in stdout and return exit code 7; parse the envelope first before judging the execution result.
The
```
uploadUrl
```
, token, authorization, signature, etc., returned by file upload are credentials; do not output or log them; recursively redact structured errors as well.
When timestamps are shown to users, convert them to readable time with timezone; default to the current session timezone, and retain the original value when necessary.
When encountering authentication, permission, profile, confirmation, or unknown errors, only load the corresponding reference in
```
dingtalk-shared
```
; do not keep guessing alternative commands.

Form Share Usage Answer Contract

After receiving a request that only asks about usage, the first step is to immediately actually execute and only execute the corresponding command below; even if the user mentions "help/schema", choose according to the entry point and do not substitute on your own:

form share update

dws aitable form share update --help

+form-share-update

dws schema --cli-path "aitable +form-share-update" --compact --format json

The leading

in a Shortcut name is an indispensable part of the command name; do not rewrite it, try other spellings, or switch to

--help

-h

Discovery gate: even if the Skill or reference documentation already provides complete examples, you must actually execute the safe help/schema query for the target leaf once and only once before answering; you must not answer solely based on the Skill or reference documentation. This rule takes precedence over the reference navigation below: when hit, do not read any reference and do not execute other commands.

When the user only asks about usage, the final answer must first give the complete command; when required IDs are missing, give a complete command template with clear placeholders; guessing is forbidden. Then explicitly state that "share configurations not passed in retain their original values"; do not execute the target write operation or claim it has been executed. The read-only query above is the only allowed command.

After the query succeeds, the final answer may contain only two lines of plain text: no Markdown code fences, headings, tables, read-back commands, or other content. The first line holds the complete command for the entry point the user asked about; existing required values must be used as-is, and missing values must remain as clear placeholders such as

<BASE_ID>

<TABLE_ID>

<VIEW_ID>

. The second line first lists the placeholders that need replacement (omit the replacement note if there are none), then gives the fixed not-executed statement, and immediately ends:

text

dws aitable form share update --base-id <BASE_ID> --table-id <TABLE_ID> --view-id <VIEW_ID> --enabled true
请将 <BASE_ID>、<TABLE_ID>、<VIEW_ID> 替换为真实值；未传入的分享配置保持原值。本次仅查询 help/schema，未执行写操作。

Known IDs and placeholders must be handled differently: short IDs explicitly given by the user are also used as-is and are not required to be replaced because of their length or because they look like examples. When all IDs are known, the second line must be exactly "未传入的分享配置保持原值。本次仅查询 help/schema，未执行写操作。"; only add the corresponding replacement note when the command actually uses placeholders. The Shortcut command line must keep

--format json

;

help/schema

in the fixed statement is not rewritten just because this time only schema was queried.

Both entry points must fully preserve the configuration values specified by the user, especially

--form-name

corresponding to the form name; do not leave only the ID and

--enabled

because of the two-line simplification. Below is an example Shortcut usage answer with known IDs (replace the title according to user input; do not omit it):

text

dws aitable +form-share-update --base-id base-123 --table-id table-456 --view-id view-789 --enabled true --form-name "报名表" --format json
未传入的分享配置保持原值。本次仅查询 help/schema，未执行写操作。

Dedicated Queries for Return Value Review (Not Applicable to Command Usage Inquiries)

Before answering, you must have the actual target compact Schema query result executed this time; simply loading the Skill or seeing a synthetic sample does not satisfy this condition. First execute the commands in the table below, then explain; you cannot answer directly based on the Skill.

Help/Schema is an offline contract query; it does not call online business or read/write the user's forms. Therefore, "only analyze synthetic returns, do not execute online business commands" still allows and requires the local queries in the table below; do not misjudge them as online reads and skip them; only when the user explicitly prohibits any command or local query do you not execute, and state that the local contract has not been verified.

When only reviewing return values/fault results (rather than asking about syntax), do not apply the two-line command template, and the "Shortcut priority" rule does not apply. The atomic/Shortcut entry points specified by the user must be preserved as-is; even if they share the Result contract, they cannot be interchanged; strictly query once per the table below, then explain the sample; do not search source code/references, and do not execute business reads/writes.

User-specified entry point	The only contract query
`form share get`	`dws schema --cli-path "aitable form share get" --compact --format json`
`form share update`	`dws schema --cli-path "aitable form share update" --compact --format json`
`+form-share-get`	`dws schema --cli-path "aitable +form-share-get" --compact --format json`
`+form-share-update`	`dws schema --cli-path "aitable +form-share-update" --compact --format json`

Do not use source code or reference searches in place of local contract queries. get only diagnoses share configuration and does not return

cpSynced

; do not suggest "confirm the loop by reading back cpSynced via get". Unverified CP should continue to be marked as unconfirmed and left to server-side diagnostics; do not treat the success of get or a non-empty UUID as proof of recovery.

First select the actual result branch of the Schema: the dry-run preview with

data.executed=false

contains only

tool/arguments/executed

(Shortcut also contains

dry_run=true

); server state or

cpSynced

is not needed, and

ok=true

only indicates preview success. Do not apply required fields from the real execution success branch to the preview. Whether a field is required is read only from the

required

of the selected branch; whether extra fields are allowed is read only from

additionalProperties

of that object; do not infer the parent object from the

arguments

sub-object.

Real execution result judgment: the share switch is based on

enabled

; retaining a UUID does not mean it is enabled; if UUID/cover is empty, report as-is; do not speculate on a single cause or assemble a cover URL. The success of get does not prove CP sync. update succeeds only when required fields are complete and types correct and

cpSynced=true

; missing/false/type anomalies cannot confirm the loop. A unified partial failure has no top-level error: the original response is in

data.succeeded[0].response

, which only indicates receipt at that stage; failure reasons are in

data.failed[0].error

, including

execution_started=true

. Do not replay writes or compensate CP on your own. If a synthetic sample does not match this structure, point out the mismatch; do not fill in Schema fields as facts that the sample already has.

Interpretation boundaries: when

status

has not published enum meanings, retain the raw value; do not translate 0/1 into unpublished/published yourself.

cpSynced=false

only supports "CP final state unconfirmed"; it does not prove external users necessarily cannot access. Empty UUID/cover values cannot prove that nothing was created before; a short ID cannot be judged as a placeholder solely because of its length.

Even if the outer layer remains ok=true or the returned structure does not conform to the contract, do not execute or recommend resending form share update / +form-share-update (including later passing the same configuration) to re-verify CP; diagnosis must not add writes; keep only the receipt and leave troubleshooting to the server.

After actually executing

form share update

+form-share-update

, the success result must check

shareFormUuid

status

formCover

, and

cpSynced

; only when

cpSynced=true

can you confirm to the user that the sharing loop is complete. Partial failure or

cpSynced=false

must not be described as success. DWS does not call a second View update command to compensate CP.

formCover

may be empty during the old server release window; state this as-is; DWS must not assemble the cover URL.

Command reference: aitable.md; PostgreSQL read-only queries: aitable-psql.md; complex commands load
references/aitable/*.md
as needed; playbook: 06-data-analytics.md.

Shortcut Discovery (On Demand)

aitable

currently has 126 public shortcuts; the full list is kept in the Runtime Catalog and Schema and is not repeated in the high-frequency product root Skill. Known leaves execute directly. For parameters, only query

dws schema --cli-path "aitable <leaf>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json

; only when

result

is needed and published, query outcomes/pagination, and for field-level details, query

data_schema

; do not infer missing items from Help or examples. Read a known leaf Help once only if Schema is unavailable; correct

unknown flag

once with the same leaf Help.

unknown command

prohibits Help: wrong suggestion → use the loaded Skill/reference explicit entry; if neither exists, report drift. Full Catalog/root/parent/product Help is prohibited; low-frequency references do not default to Help; read only one Reference in the same task.

Only when the root route, exact task reference, and the low-frequency atomic index in

references/aitable.md

all fail to locate a capability, execute

dws shortcut list --service aitable --format json

as a final fallback; do not load the full Shortcut Catalog or product-level Schema for known intents.

Golden Route (High-Frequency Composite Tasks)

IDs already returned by the current AITable call with confirmed types are used directly; names are first uniquely resolved to stable IDs. For user-supplied

/i/nodes/

URLs or unverified nodeId, first execute

dws drive info

; if it is

extension=dlink

, save the returned

result.fileId

as the shortcut entry ID, pass it to

dws doc info

, then read the target

linkSourceInfo

hop by hop; after confirming

extension=able

, use the target

linkSourceInfo.nodeId

as the baseId. Stop when parsing fails, fields are missing, IDs are duplicated, or the final type is not able; keep the initial

result.fileId

and switch to Drive only when explicitly moving, renaming, or deleting the shortcut entry itself. Also stop on zero hits or multiple candidates; do not default to the first item.

For data analysis, as well as PostgreSQL/SQL/SELECT/JOIN or cross-table related queries, first read aitable-psql.md. Use

record query

for raw record filtering, sorting, and Top N; use

record stats

record group-stats

for single-table direct scalar, grouped, or deduplication statistics; use

psql

only for complex analysis such as same-Base JOIN, arithmetic between fields, CASE, post-aggregation derivation, Top N or ranking of aggregate results, and window calculations. When using

psql

, keep the same DWS entry, first use

dws aitable psql -d <baseId> -l

to discover logical tables, then use

-t <tableId>

to view column types, execute a minimal

LIMIT 3

query using the returned

Name

, and only after success execute the formal read-only query with

-c <SQL>

;

psql

outputs PostgreSQL table text and does not add

--format json

. After psql fails, re-judge only from the original intent: resend

record query

if it is entirely single-table raw records, resend

record stats

record group-stats

if it is entirely single-table direct statistics; unfinished psql results must be discarded and the switch reason explained; complex analysis, result merging, and local equivalent computation are all prohibited from downgrading.

User intent	Only recommended entry	Key boundaries
Resolve stable ID from a confirmed AITable URL	`dws aitable +url-resolve --url <URL>`	Only resolve baseId/tableId/viewId/recordId already in the URL; do not resolve dlink remotely; the original `/i/nodes/` URL must first be normalized as above, and the dlink target nodeId is used directly as baseId
Uniquely locate and operate Base/Table by name	`dws aitable +resolve-base --name <name>` → `dws aitable +resolve-table --base <ID> --name <table name>`	Exact match by default; add `--fuzzy` only when the user explicitly accepts fuzzy matching
Search Base candidates or check existence	`dws aitable +base-search --query <keyword>`	When the user says "search / look for / candidates / create if not exists", go directly to this entry; do not call `+resolve-base` first; returns `hasMore/nextCursor` ; page only when `hasMore=true` ; AITable Base names must not be routed to `dws aisearch person`
Browse tables under a Base	`dws aitable +list-tables --base <ID>`	Returns only tableId/tableName; does not load fields
Create a Base with a full set of table fields	`dws aitable +base-bootstrap --name <name> --tables '[{"name":"<table name>","fields":[{"fieldName":"<field name>","type":"text"}]}]'`	The table object key must be `name` , not `tableName` ; fields use `fieldName/type/config` , optional `description` ; execute directly when parameters are sufficient
Copy a Base	`dws aitable +base-copy --base-id <B_OR_URL> [--target-folder-id <FOLDER_ID_OR_URL>] [--only-struct] [--new-name <name>]`	`base-id` accepts a Base ID or standard node URL; `target-folder-id` accepts dentryUuid, standard node URL, or Drive folder URL; when omitted, copy to the workspace root where the source Base resides; parameter parsing and target validation are handled by AITable MCP
Create a table and fields in an existing Base	`dws aitable +table-bootstrap --base-id <ID> --name <table name> --fields '<JSON array>'`	Fields use `fieldName/type/config` , optional `description` ; automatically shards by 15 fields and reads back for verification
Read field catalog or full config	`dws aitable field list --base-id <B> --table-id <T>` / `dws aitable +field-get --base-id <B> --table-id <T>`	Use `field list` for fieldId/name/type only; use `+field-get` when config is needed; `+field-list` or `+list-fields` do not exist
Resolve person, department, or group entities by name	`dws aitable entity search --entity-type PERSON\|DEPARTMENT\|GROUP --keyword <name>`	Returns candidates and stable identities usable for filtering; stop on zero hits, duplicate names, fuzzy hits, or incomplete pagination; do not default to the first item
Query raw records, record filtering/sorting, raw record Top N, or field projection	`dws aitable +record-query --base-id <ID> --table-id <ID> [--record-ids <IDs>] [--field-ids <IDs>] [--filters <JSON>] [--sort <JSON>] [--query <keyword>]`	When the user asks to "return/view only" specified fields, pass the corresponding `--field-ids` ; do not just remove columns in the final text; single-table direct scalar, grouped, or deduplication statistics switch to `record stats` / `record group-stats` ; complex server-side analysis switches to psql. Non-analytical full row-by-row details with explicit user permission may use atomic `record query --all --page-limit <N>` directly, without needing or triggering the psql downgrade gate.
Create single or batch records	`dws aitable record create --base-id <ID> --table-id <ID> --records <JSON>`	Currently no `+record-create` ; get field definitions before writing; read back by new ID after writing
Verify record results by original write token	`dws aitable +record-write-result --base-id <B> --table-id <T> --client-token <original UUID>`	When unknown or IDs are incomplete, stop subsequent writes; the next step still calls this command read-only for reconciliation using the original Base/Table/token, not a full-table query; the applied ID set does not guarantee the whole batch is complete or in input order; records without returned IDs remain unverified; do not supplement by count difference or input position; after the full ID set is confirmed, verify actual values ID by ID; a query failure is not a terminal write state that can be rebuilt
Update a known recordId	`dws aitable +record-update --base-id <ID> --table-id <ID> --records <JSON>`	Automatically shards and reads back; pass only fields to modify
Query change history of a record	`dws aitable +record-history-list --base-id <ID> --table-id <ID> --record-id <ID>`	When recordId is known, execute directly; do not probe Help, Catalog, or full Schema
Manage comments on a record	Query with `dws aitable comment list --base-id <B> --table-id <T> --record-id <R>` ; create, reply, update, and delete use the same leaf group as needed	First read comment; topicId/commentKey are only reused from the same record's real returns; empty comment pages still read `meta.pagination` ; stop only when `meta.pagination.endpoint_exhausted=true` ; otherwise pass `meta.pagination.next_token` as-is to the next `--cursor` ; for unknown write states, reconcile with list first
Sync by business key or batch modify by condition	Use `dws aitable +record-upsert-by-key ...` for unique keys; use `dws aitable +record-bulk-patch ... --max-matches <N>` for bounded batch modification	upsert allows only 0 creates and 1 update; batch modification must have query/filters/record-ids boundaries. Normal update/upsert executes directly; read record-ops only for history, sharing, delete recovery, empty rows, or special field values; read filter-sort only for explicit AND/OR, date, or comparison operators
Generate record share links and send to a contact	`dws aitable +record-share-links --base <B> --table <T> --record-ids <IDs>` → `dws chat +dm --to <name> --text <full link text>`	AITable only generates links; when the user asks to "send", you must actually complete the send; do not stop at contact resolution
Create or duplicate a view	Create with `dws aitable view create --base-id <B> --table-id <T> --view-type <Grid\|FormDesigner\|Gantt\|Calendar\|Kanban\|Gallery> [--name <name>]` ; duplicate with `dws aitable +view-duplicate --base-id <B> --table-id <T> --view-id <V> [--new-name <name>]`	Create and duplicate execute directly; when configuration is needed, choose one View Reference under "On-Demand Loading" below
Create and verify a Dashboard, create Chart as needed	`dws aitable dashboard create --base-id <B> --name <name>` → `dws aitable +dashboard-get --base-id <B> --dashboard-id <D>` ; when a Chart is needed, handle per "On-Demand Loading" below	Use only the real dashboardId returned by creation; on failure, do not guess synonymous commands or change dashboardId
Manage AI table app mode	`dws aitable app get --base-id <B>` → `dws aitable app page list --base-id <B>` → as needed `app page create/update/move/delete` or `app widget create/get/list/update/delete`	A Base has only one user-facing App; a page's `pageId` is also the corresponding Dashboard ID. Widget `config` / `layout` are complete objects; read back before updating; do not automatically replay when a create operation is in an unknown state
Create a Section in a Base and move nodes	`dws aitable +section-create --base-id <B> --name <name>` → `dws aitable +section-move-node --base-id <B> --node-id <N> --new-parent-section-id <S>` → `dws aitable +section-list-nodes --base-id <B>`	Table, Dashboard, and Section are all nsheet nodes of AITable; do not switch to Wiki/Drive folders or move commands
Import local CSV/XLSX/XLS into a new table	`dws aitable +import-file --base-id <BASE_ID> --file <FILE_PATH>`	The stored example does not preset `--yes` ; the first call triggers the Runtime confirmation gate; after explicit confirmation, the executor appends it. DWS completes credential application, empty Content-Type PUT, and `import data` in-process without exposing the signed URL; do not guess `+import-csv` or pass `--file` to `import upload`
Connect external data sources (approval, etc.)	`dws aitable +datasource-list-sources --base-id <ID> --datasource-type OA` → parse result to construct sourceConfig → `dws aitable +datasource-create --base-id <ID> --datasource-type OA --source-config '<JSON>'`	Currently only OA approval is supported; processCode/name/iconUrl/url are transparently passed from list-sources; after creation, use `+datasource-sync-status` to check sync results

Simple Leaves

Except for

aitable psql

, structured commands use

--format json

and extract stable IDs from real returns;

aitable psql

outputs PostgreSQL table text and does not support

--format json

; follow

aitable-psql.md

Use directly when the intent is clear; read the leaf Schema only when parameters are uncertain:

User intent	Entry point
View / rename / delete Base	`+base-get` / `+base-update` / `+base-delete`
Search templates	`+template-search`
View / copy across Base / rename / delete Table	`+table-get` / `+table-copy` / `+table-update` / `+table-delete`
Create / update / delete normal fields	`field create` / `field update` / `field delete`
View / delete View	`+view-get` / `+view-delete`
View / rename / delete Dashboard	`+dashboard-get` / `+dashboard-update` / `+dashboard-delete`
View / modify App in app mode	`app get` / `app update`
Manage app pages	`app page create/get/list/update/move/delete`
Manage page Widgets	`app widget create/get/list/update/delete`

Commands are appended after

dws aitable

; resource IDs use

--base-id/--table-id/--field-id/--view-id/--dashboard-id/--page-id/--widget-id

, and renaming uses

--name

. All app mode commands require

--base-id

;

app widget create

also requires

--config

containing

chartType

and

--layout

containing

x/y/w/h

+table-copy

has irregular parameters; read only its leaf Schema before execution. Do not read operation References, Help, or the product Catalog.

For data sources, use

+datasource-list-sources

to view sources,

+datasource-get-fields

to get fields, and

+datasource-create

+datasource-update

+datasource-sync

+datasource-sync-status

+datasource-get-config

to create, update, sync, check status, and view config.

Execution Constraints

Use existing IDs directly; resolve URLs only once; use

+resolve-base

+resolve-table

for "uniquely locate and operate", and

+base-search

directly for "search candidates/existence check". When people, departments, or groups only have display names, use

entity search

to obtain stable identities; do not probe these paths serially. Read the field catalog only when filters/sort are missing fieldId.

When the Golden Route already provides accurate commands and parameters, execute directly; do not pre-read or default to reading the general

references/aitable.md

. Only when operation parameters, JSON structures, or recovery semantics are truly missing, read one precise operation Reference below.

When a Shortcut already includes sharding or verification, do not split steps again; to create a complete table structure in an existing Base, use

+table-bootstrap

directly.

Single-product linear tasks execute directly without creating TodoWrite; create a plan only for long tasks spanning multiple products or with multiple independent branches, and update it only at phase transitions, not after every CLI.

When the user requires resource names to include the current timestamp, take it once and reuse the same value across Base, Table, Dashboard, and other names; do not take the time separately for each resource.

When JSON already returns the needed fields, reuse them immediately; do not switch to

--verbose

raw

, or

pretty

and repeat requests to find the same field.

Read the field catalog only when record filter/sort is missing fieldId.
The protocols and References for record filter/sort and view filter/sort/group are mutually exclusive. Regular record query/create/update/upsert go direct; only history, sharing, delete recovery, empty rows, or special field values read
```
record-ops
```
.

Normal field types use

text/number/date/singleSelect/currency

; the config for

singleSelect

{"options":[{"name":"<option>"}]}

, and RMB

currency

{"currencyType":"CNY","formatter":"FLOAT_2"}

Use TodoWrite only when the task contains 4 or more independent business steps or the user explicitly requests it; do not split steps by individual CLI, update only at phase transitions.
When multiple resource names require the same timestamp, take it once and reuse.
Reuse fields already returned in JSON; do not repeat requests with
```
--verbose/raw/pretty
```
.
Before creating a data source, you must first use
```
+datasource-list-sources
```
to obtain passthrough fields such as processCode; do not construct sourceConfig from memory.

Record Stability Constraints

When record pagination reports
```
INVALID_CURSOR
```
,
```
CURSOR_SNAPSHOT_CHANGED
```
, or
```
CURSOR_SNAPSHOT_UNAVAILABLE
```
, discard all accumulated results and the old cursor; there is no new resumable cursor, and you cannot keep the first page and deduplicate/splice it. For the first two, after checking conditions, re-query read-only from the first page without
```
--cursor
```
; UNAVAILABLE requires waiting for server repair first. Do not re-run an entire command that includes writes. Resume only for normal recoverable errors with an actual valid checkpoint; see record-query for details.
Before querying, writing, filtering, or sorting, first use
```
field get
```
to obtain the target field's
```
fieldId
```
,
```
type
```
, and
```
config
```
; the key in
```
cells
```
must use
```
fieldId
```
, not the Chinese name of the field.
For select/multipleSelect writes, pass option names; when filtering, first uniquely resolve the option ID. For multipleSelect or other array-type fields, the second operand must be an array of option IDs/stable IDs; do not pass a bare string.
Resolve people, departments, groups, related records, and similar conditions into stable structured IDs first; stop on zero hits, multiple hits, or type mismatches; do not pass display names or raw values directly.
Non-analytical full row-by-row details with explicit user permission can use
```
record query --all --page-limit 0
```
directly, without needing or triggering the psql downgrade gate; do not use it to replace psql complex analysis or do calculations in local tools such as Agent context, Python, jq, JavaScript, or spreadsheets. Model-written loops are prohibited for automatic paging; manual paging must pass the real
```
data.nextCursor
```
through, with query conditions unchanged. A successful empty continuation page with
```
records=[]
```
and empty
```
nextCursor
```
is a normal last page; do not report an error, retry, or judge it as a missed query.
For create or update, read back only with the ID actually returned; when the write effect is unknown, read back and do not replay successful batches.
For full queries check
```
hasMore
```
; for batch writes check the final state; do not claim full completion when pagination has not ended or on
```
partial_success
```
.
Record
```
cells
```
use the current fieldId; write values according to the real field type; read-only fields cannot be written.
For create or update, read back only with the ID actually returned; when the write effect is unknown, read back and do not replay successful batches.
For full queries check
```
hasMore
```
; for batch writes check the final state; do not claim full completion when pagination has not ended or on
```
partial_success
```
.

Security Boundaries

Deletion is irreversible; verify the real target according to Runtime confirmation;
```
base list
```
only shows recent access. Stop when fields have zero/multiple candidates or unclear types; for multi-batch writes, retain completed batches and the resume position.
Comment create/reply are non-idempotent; when a comment write operation is in an unknown state, first reconcile with
```
comment list
```
; do not replay automatically; delete only removes the user's own comments and is irreversible; handling of associated replies is not guaranteed.
```
app get
```
/
```
app page list
```
will initialize a default App when the App does not exist; this is an idempotent conditional write;
```
app page/widget create
```
is non-idempotent and does not automatically retry. Deleting a Page cascades to delete all Widgets; deleting a Widget synchronously cleans up layouts; both require independent confirmation.
Data source
```
+datasource-create
```
/
```
+datasource-update
```
triggers real data synchronization; confirm the target Base and sourceConfig before execution.
```
+datasource-sync
```
handles at most 5 tables per run.

On-Demand Loading (Complex JSON and Recovery Semantics)

Do not read References when Golden/secondary direct paths cover the case; otherwise, read one precise Reference according to the final specific capability. After reading, execute directly and do not read other AITable References.

Trigger condition	Reference
Record filters/sort/date/AND/OR/comparison operators for `+record-query` , upsert, bulk patch	filter-sort
Record history, sharing, delete recovery, empty rows, or special field values	record-ops
Record pagination errors, invalid cursors, or snapshot recovery	record-query
Record statistics, grouped aggregation, or deduplication rate	record-stats
Record comment query, create, reply, update, or delete	comment
Query a record's primary document, or create a primary document for a record	Read primary-doc before first table creation; not for normal Base/Table/field/record creation and import
AI fields, related fields, lookup/filterUp, or other complex config	field
Formula fields or formula syntax	formula-guide
Import/export task recovery	export-import
View column order, move/place/pin to far left, filter, sort, group (do not switch to record `filter-sort` )	view-config
Kanban/Gallery cards, Gantt timebar, Grid aggregate	view-types
View locking, freezing first N columns, row height, or color fill	view-extras
Section/node movement or cleanup within a Base	section
Config needed for Chart creation/update, or full Dashboard config/arrange; normal Dashboard CRUD uses the direct paths above	dashboard-chart
Form creation, questions, or sharing	form
Attachment upload or removal	attachment
Automation workflows	workflow
Normal roles or advanced permissions	advperm
Data source integration, sync management, sourceConfig construction, or approval data sync	datasource
SQL, PostgreSQL, SELECT, or same-Base multi-table JOIN	psql
Unclear product boundary	intent-guide
Low-frequency atomic capabilities still not locatable by the References above	The corresponding section in aitable.md

Do not pre-load these References.

Error Shortest Path

Zero/multiple candidates, field ambiguity, or incomplete pagination: stop and return evidence; only a valid pagination session can pass through the real
```
nextCursor
```
. For invalid cursors, first execute the "Record Stability Constraints" above; do not apply ordinary checkpoint resumption.
For type errors, only re-check the target field; do not delete fields or lose input; resume
```
partial_success
```
from the checkpoint; for unknown writes, read back first.
When the error provides
```
actions
```
/
```
available_flags
```
, correct once only according to the
```
next_command
```
in it; stop when
```
retryable=false
```
or the target ID type does not match.
Data source sync
```
errorCode=4014
```
indicates duplicate triggering while a sync is running; you can retry later; before triggering sync on a non-data-source table, first use
```
+base-get
```
to confirm
```
sync=true
```
.

Cross-Product Boundaries

Excel-style cell, range, and formula operations → Sheet in
```
dingtalk-misc
```
.
Moving a Base as a whole between ordinary folders or doing outer storage renaming → Drive; copying/deleting Base structures, and creating, copying, moving, renaming, deleting Table, Dashboard, Section within a Base → AITable.
Record primary document content → switch to
```
dingtalk-doc
```
after obtaining the real nodeId.

dingtalk-aitable

NPX Install

Tags

SKILL.md Content (Chinese)