dingtalk-aicard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

"v1.0"

and send API

protocolVersion

"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.

根据用户提供的内容或图片创建或编辑 A2UI 文件，仅查询所需契约，并区分本地验证、实际投递与客户端渲染。本 Skill 使用基于 A2UI 1.0 的 DingTalk V0.8 套件：消息的

version

为

"v1.0"

，发送 API 的

protocolVersion

为

"1.0"

。

直接按照用户请求执行查询、文件操作、发送或更新；参考资料并非必须按固定顺序阅读。遵守命令和协议要求。仅当缺失的事实、交互含义或目标对象会影响结果时才询问。

Route by intent

按意图选择路径

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

Intent	First reference	Optional follow-up
Set up lookup and validation	Execution environment	Installed command help
Create or redesign from content or images	Visual focus and layout	One relevant pattern or example
Query a known name	Query a named contract	The result's source pointer
Find an unknown name	Component, function, or Token index	Query only the selected names
Construct or repair a card	Construct and validate	Diagnostic pointer and named contract
Send, preview, or update	Delivery boundary	Installed command help

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

仅阅读相关参考资料。不要预加载完整协议、所有模式或整份指南。

意图	首选参考	可选后续
设置查询与验证	执行环境	已安装命令的帮助信息
根据内容或图片创建或重新设计	视觉焦点与布局	一个相关的模式或示例
查询已知名称	查询指定契约	结果中的 source 指针
查找未知名称	Component、function 或 Token 索引	仅查询选定的名称
构建或修复卡片	构建与验证	诊断指针和指定契约
发送、预览或更新	投递边界	已安装命令的帮助信息

使用各模式获取组合指导，并使用关联的 JSON 了解消息结构。直接阅读指定名称的示例；仅使用示例索引来选择一个示例。

Composition patterns

组合模式

Content	Reference
Notifications and reminders	Notification
Object facts and decisions	Detail
Illustrated content and attachments	Content
Metrics and reports	Report
Editable inputs and submission	Form
Generation and execution updates	Progress

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.

内容	参考资料
通知与提醒	Notification
对象信息与决策	Detail
图文内容与附件	Content
指标与报告	Report
可编辑输入与提交	Form
生成与执行更新	Progress

对于可编辑输入，即使卡片已由另一种模式描述，也应同时查阅 Form 模式，以了解 bindings 和提交机制。回放执行示例时，即使已直接选择 JSON，也要阅读示例与回放以了解其批次边界。

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.

本版本使用原生 DWS 命令，而不是 Python。确认

dws aicard --help

提供了

explain

、

lint

和

preview

；仅复制 Skill 并不会安装这些命令。查询和 lint 均可离线执行，无需 Profile。检查每个命令当前的帮助信息和结构化封装（

ok

、

outcome

、

data

或

error.details

）。如果命令不可用，参考资料可以指导起草，但不要声称已完成 DWS 验证。

Query a named contract

查询指定契约

bash

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.

bash

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

仅查询所需名称。紧凑形式的

$contractRef

和

definitions

是查询元数据，不是 A2UI 字段。需要展开字段时，不要使用

--compact

；

source

可用于定位被省略的详细信息。

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:

json

[
  {"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.

Scenario	Messages and checks
Complete new card	Create and initialize as above; use `--preflight new-card`
Host-created empty Surface	Initialize its existing ID without `createSurface` ; use Schema and resource checks
Existing card update	Keep IDs and send only intentional changes; use Schema and resource checks, then check against known current state

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.

bash

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

Choose

--preflight new-card

--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.

以

references/protocol/

为契约。编写有序的 JSON 消息数组。

在同一张卡片内，保持相同的

surfaceId

；创建卡片时，应选择适合该卡片的 ID。完整的新卡片需要创建 Surface、初始化根数据（静态内容也需要初始化，即使是

{}

），并包含 ID 为

root

的 Component。推荐的显式形式如下：

json

[
  {"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"}]}}
]

这是用于展示结构的示例，不是用于发送的业务卡片。协议也接受在

createSurface.dataModel

和

createSurface.components

中进行有效的内联初始化；三条独立消息并非唯一有效的表示形式。

场景	消息与检查
完整的新卡片	如上创建并初始化；使用 `--preflight new-card`
宿主创建的空 Surface	不包含 `createSurface` ，但要初始化其现有 ID；使用 Schema 和资源检查
更新已有卡片	保留 ID，并且只发送有意进行的变更；使用 Schema 和资源检查，然后结合已知的当前状态进行检查

从完整文件中移除

createSurface

并不会使其成为安全的增量。不要重放 Form 默认值或无关的初始数据：这可能覆盖用户输入。仅进行资源检查无法证明更新保留了状态或引用。

编辑时保留无关的样式。对于普通的新卡片，优先使用不含背景字段的根

Column

。如果需要根

Card

，请使用

backgroundColor: "#00FFFFFF"

，且不要使用 background token。遵循明确指定的 Surface 设计；参见设计指导。

富文本和静态表格优先使用

Markdown

；简短标题和标签使用

Text

。普通卡片省略根级

padding

。不要默认使用

CardHeader

；按要求保留它，并检查 insets。

保留提供的事实和所请求的交互；为演示数据添加标签。投递前替换

REPLACE_*

占位符。不要将未经验证的资源、未连接的操作或模拟状态呈现为真实可用。

根据字段契约允许的情况选择 literals 或 bindings。使用所需类型初始化绑定数据，并通过

updateDataModel

更新它；通过

updateComponents

更改 Component literals。

sendDataModel

控制 A2A 消息是否包含完整数据模型，而不是控制 bindings 是否生效。

bash

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

根据所选场景选择

--preflight new-card

或

--preflight resources

；仅在需要序列化后的消息字符串时使用

--emit

；它不能与

--fragment

组合使用。检查退出状态，以及

data.valid

和所选预检对应的

data.preflight.valid

。

dws aicard lint --self-check --format json

验证整个套件。

Validation scope

验证范围

Lint checks syntax and Schema fields. New-card preflight additionally checks initialization, root, duplicate IDs within a message, static references and cycles in the final component snapshot, not every intermediate streaming frame. Unreachable components are warnings. Resource preflight checks inline encoding; neither mode evaluates bindings or proves image loading.

--fragment

checks component/message fragments; it is not a way to bypass new-card initialization. Do not silently rewrite user data, remove requested components, or downgrade interactions to pass a check.

A successful named lookup is not a full package check. Use the self-check supported by the selected execution environment; local checks do not establish client behavior.

Lint 检查语法和 Schema 字段。新卡片预检还会检查初始化、root、单条消息内的重复 ID，以及最终 Component 快照中的静态引用和循环引用，但不会检查每一个中间流式帧。不可达 Component 会产生警告。资源预检检查内联编码；两种模式都不会评估 bindings，也不能证明图片能够加载。

--fragment

检查 Component/消息片段；它不是绕过新卡片初始化的方式。不要为了通过检查而悄悄重写用户数据、移除用户要求的 Component 或降级交互。

指定名称查询成功并不等于完成了整个套件检查。使用所选执行环境支持的自检；本地检查无法证明客户端行为。

Delivery boundary

投递边界

With native

--emit

, read

data.a2uiMessages

Send only when requested. Resolve exactly one target under the sending profile:

--conversation-id

for a conversation or

--open-dingtalk-id

for a person. Names are not target IDs. Inspect installed command help, JSON-encode the emitted message-string array as one

--content

argument, and call

dws chat message send-a2ui-card

. Preserve the request, target, profile and returned

bizId

. An uncertain result must be checked before another create; do not resend automatically.

Creation starts in PROCESSING. Update with

dws chat message update-a2ui-card --biz-id <bizId> --content <message-strings> --flow-status <state>

under the original profile. Keep the same

surfaceId

and component IDs; send only intended

updateDataModel

updateComponents

changes, not another

createSurface

or unrelated defaults. Static cards require

--flow-status FINISH

with a nonempty valid delta; prepare it before sending and preserve business data. Stream complete messages, not JSON tokens. Resource preflight checks only the delta. If current state is known, validate it with the delta; Schema validity does not prove business safety.

dws aicard preview --file card.a2ui.json

sends a self-preview in PROCESSING;

--dry-run

does not send. For a completed static preview, finish it under the same profile with

dws chat message update-a2ui-card --biz-id <data.bizId> --content <message-strings> --flow-status FINISH

, using a nonempty state-preserving delta for the same Surface. Do not replay form defaults. Use server-issued

data.bizId

, never request-side

bizCardId

. If absent, inspect

updateWarning

and the receipt; do not recreate automatically.

openTaskId

cannot be used with

query-send-status

After sending, use the available readback capability under the same profile and target to identify this exact card from returned instance/message identifiers. Generic card text and a nearby timestamp are not sufficient. Report request acceptance, same-target readback, client rendering and interaction separately. If readback is unavailable or inconclusive, mark it unverified; do not claim the user received or correctly rendered the card from API acceptance alone.

Report the file, checks actually run, and delivery result when requested. Local validation and request acceptance do not prove client rendering.

使用原生

--emit

时，读取

data.a2uiMessages

。

仅在用户请求时发送。在发送 Profile 下解析且仅解析一个目标：会话使用

--conversation-id

，个人使用

--open-dingtalk-id

。名称不是目标 ID。检查已安装命令的帮助信息，将 emit 输出的消息字符串数组 JSON 编码为单个

--content

参数，然后调用

dws chat message send-a2ui-card

。保留请求、目标、Profile 以及返回的

bizId

。结果不确定时，必须先检查，再执行另一次 create；不要自动重新发送。

创建操作以 PROCESSING 状态开始。在原 Profile 下使用

dws chat message update-a2ui-card --biz-id <bizId> --content <message-strings> --flow-status <state>

进行更新。保持相同的

surfaceId

和 Component ID；只发送有意进行的

updateDataModel

或

updateComponents

变更，不要再次发送

createSurface

或无关的默认值。静态卡片要求使用

--flow-status FINISH

，并提供非空的有效增量；发送前应准备好该增量，并保留业务数据。以完整消息流式发送，而不是 JSON token。资源预检只检查增量。如果已知当前状态，请结合增量对其进行验证；Schema 有效性不能证明业务安全性。

dws aicard preview --file card.a2ui.json

以 PROCESSING 状态发送自预览；

--dry-run

不会发送。对于已完成的静态预览，在同一 Profile 下使用

dws chat message update-a2ui-card --biz-id <data.bizId> --content <message-strings> --flow-status FINISH

将其完成，并对同一 Surface 使用非空且保留状态的增量。不要重放 Form 默认值。使用服务器签发的

data.bizId

，绝不要使用请求侧的

bizCardId

。如果

data.bizId

缺失，请检查

updateWarning

和回执；不要自动重新创建。

openTaskId

不能与

query-send-status

一起使用。

发送后，在同一 Profile 和目标下使用可用的回读能力，根据返回的实例/消息标识符识别这张确切卡片。通用卡片文本和附近的时间戳不足以完成识别。分别报告请求受理、同目标回读、客户端渲染和交互情况。如果回读不可用或结果不确定，请将其标记为未验证；不要仅凭 API 受理就声称用户已收到卡片或卡片已正确渲染。

按要求报告文件、实际运行的检查以及投递结果。本地验证和请求受理不能证明客户端已正确渲染。