Dingtalk Aicard

DingTalk AI Cards V0.8

Create or edit an A2UI file from the user's content or image, look up only the contracts needed, and distinguish local validation from delivery and client rendering. This Skill uses the DingTalk V0.8 package based on A2UI 1.0: message version is "v1.0" and send API protocolVersion is "1.0".

Follow the user's requested lookup, file, send or update directly; the references are not a mandatory sequence. Obey command and protocol requirements. Ask only when missing facts, interaction meaning or the target affect the outcome.

Route by intent

Read only the relevant reference. Do not preload the complete protocol, every pattern, or the whole guide.

Use patterns for composition guidance and linked JSON for message shapes. Read a named example directly; use the example index only to choose one.

Composition patterns

For editable inputs, also consult the form pattern for bindings and submission, even when another pattern describes the card. When replaying an execution example, read Examples and replay for its batch boundaries, even if the JSON was selected directly.

Execution environment

This edition uses native DWS commands, not Python. Confirm dws aicard --help exposes explain, lint, and preview; copying the Skill does not install commands. Lookup and lint are offline and need no Profile. Check each command's current help and structured envelope (ok, outcome, data, or error.details). If unavailable, references can guide a draft, but do not claim DWS validation.

Query a named contract

dws aicard explain Tabs --format json
dws aicard explain Text Row Column --compact --format json

Query only needed names. Compact $contractRef and definitions are lookup metadata, not A2UI fields. Query without --compact for expanded fields; source locates omitted details.

Construct and validate

Use references/protocol/ as the contract. Write an ordered JSON message array. Within one card, keep the same surfaceId; choose an ID suitable for that card when creating it. A complete new card requires Surface creation, root data initialization (even {} for static content), and a component with ID root. The recommended explicit form is:

[
  {"version":"v1.0","createSurface":{"surfaceId":"example-surface","catalogId":"https://dingtalk.com/card/a2ui/catalogs/public/catalog.json"}},
  {"version":"v1.0","updateDataModel":{"surfaceId":"example-surface","path":"/","value":{}}},
  {"version":"v1.0","updateComponents":{"surfaceId":"example-surface","components":[{"id":"root","component":"Text","text":"Example"}]}}
]

This is a structural example, not a business card to send. Protocol-valid inline initialization in createSurface.dataModel and createSurface.components is also accepted; three separate messages are not the only valid representation.

Removing createSurface from a complete file does not make it a safe delta. Do not replay form defaults or unrelated initial data: that can overwrite user input. Resource checks alone cannot prove an update preserves state or references.

Preserve unrelated styling when editing. For ordinary new cards, prefer a root Column without background fields. If a root Card is needed, use backgroundColor: "#00FFFFFF" and no background token. Honor explicit surface designs; see design guidance.

Prefer Markdown for rich text and static tables; Text for short titles and labels. Omit root padding for ordinary cards. Do not default to CardHeader; preserve it when requested and check insets.

Preserve supplied facts and requested interactions; label demonstration data. Replace REPLACE_* placeholders before delivery. Do not present unverified resources, unconnected actions, or simulated states as real and working.

Choose literals or bindings as the field contract permits. Initialize bound data with the required types and update it through updateDataModel; change component literals through updateComponents. sendDataModel controls whether A2A messages include the full data model, not whether bindings work.

dws aicard lint --file card.a2ui.json --format json

Choose --preflight new-card or --preflight resources for the selected scenario, and use --emit only when serialized message strings are needed; it cannot be combined with --fragment. Check exit status and data.valid plus data.preflight.valid when selected. dws aicard lint --self-check --format json verifies the full package.