dingtalk-aicard

DingTalk AI Cards V0.8

根据用户提供的内容或图片创建或编辑 A2UI 文件，仅查询所需的契约，并区分本地验证、交付和客户端渲染。本 Skill 使用基于 A2UI 1.0 的 DingTalk V0.8 软件包：消息 version 为 "v1.0"，发送 API 的 protocolVersion 为 "1.0"。

直接按照用户要求进行查询、文件操作、发送或更新；这些参考资料不是必须按顺序阅读的。遵守命令和协议要求。只有在缺少的事实、交互含义或目标会影响结果时才提问。

按意图选择路径

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

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

使用模式获取组合指导，使用链接的 JSON 查看消息结构。直接阅读已命名的示例；仅在需要选择示例时使用示例索引。

组合模式

内容	参考资料
通知和提醒	通知
对象事实和决策	详情
插图内容和附件	内容
指标和报告	报告
可编辑输入和提交	表单
生成和执行进度更新	进度

对于可编辑输入，还应查阅表单模式，了解绑定和提交，即使卡片由其他模式描述也是如此。 重放执行示例时，请阅读示例和重放，了解其批次边界，即使 JSON 是直接选取的也一样。

执行环境

此版本使用原生 DWS 命令，而非 Python。确认 dws aicard --help 显示 explain、lint 和 preview；复制 Skill 不会安装命令。查询和 lint 均可离线执行，无需 Profile。检查每条命令当前的帮助信息和结构化封套（ok、outcome、data 或 error.details）。如果命令不可用，参考资料可用于指导草稿，但不要声称已通过 DWS 验证。

查询已命名的契约

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

只查询所需名称。精简的 $contractRef 和 definitions 是查询元数据，不是 A2UI 字段。省略 --compact 可查询展开后的字段；source 用于定位省略的详情。

构建和验证

以 references/protocol/ 为契约。编写一个有序的 JSON 消息数组。 在同一张卡片中，保持 surfaceId 相同；创建卡片时，选择适合该卡片的 ID。 完整的新卡片需要创建 Surface、初始化根数据（静态内容也要初始化为 {}），并添加 ID 为 root 的组件。 建议使用以下显式形式：

[
  {"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	初始化其现有 ID，不使用 createSurface；使用 Schema 和资源检查
更新现有卡片	保留 ID，仅发送有意进行的更改；使用 Schema 和资源检查，然后对照已知的当前状态进行检查

从完整文件中移除 createSurface，并不会使其成为安全的增量更新。 不要重放表单默认值或无关的初始数据：这可能覆盖用户输入。仅靠资源检查无法证明更新保留了状态或引用。

编辑时保留无关样式。对于普通的新卡片，优先使用不含背景字段的根 Column。如果需要根 Card，请使用 backgroundColor: "#00FFFFFF"，且不要设置背景令牌。遵循明确指定的 Surface 设计；参见设计指南。

富文本和静态表格优先使用 Markdown；简短标题和标签使用 Text。普通卡片不要设置根 padding。除非收到明确要求，否则不要默认使用 CardHeader；如已要求使用，则予以保留并检查内边距。

保留提供的事实和要求的交互；为演示数据添加标注。交付前替换 REPLACE_* 占位符。不要将未经验证的资源、未连接的操作或模拟状态描述为真实可用。

根据字段契约选择字面值或绑定。使用所需类型初始化绑定数据，并通过 updateDataModel 更新；通过 updateComponents 更改组件字面值。sendDataModel 控制 A2A 消息是否包含完整数据模型，而不影响绑定是否生效。

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 会验证完整软件包。

验证范围

Lint 会检查语法和 Schema 字段。新卡片预检还会检查初始化、根组件、单条消息中的重复 ID、最终组件快照中的静态引用和循环，而不是每个中间流式帧。不可达组件会发出警告。资源预检会检查内联编码；这两种模式都不会评估绑定或验证图像是否加载。--fragment 会检查组件/消息片段；它不能用来绕过新卡片初始化。不要为了通过检查而悄悄改写用户数据、移除用户要求的组件，或降低交互级别。

命名查询成功并不代表完整软件包检查通过。使用所选执行环境支持的自检；本地检查无法证明客户端行为。

交付边界

使用原生 --emit 时，读取 data.a2uiMessages。

仅在收到请求时发送。在发送配置下恰好解析一个目标：对于会话，使用 --conversation-id；对于个人，使用 --open-dingtalk-id。名称不是目标 ID。检查已安装命令的帮助信息，将发出的消息字符串数组编码为 JSON，并作为一个 --content 参数传入，然后调用 dws chat message send-a2ui-card。保留请求、目标、配置和返回的 bizId。结果不确定时，必须先核查，再创建另一个卡片；不要自动重发。

创建后状态为 PROCESSING。使用原始配置，通过 dws chat message update-a2ui-card --biz-id <bizId> --content <message-strings> --flow-status <state> 更新。保持相同的 surfaceId 和组件 ID；只发送预期的 updateDataModel 或 updateComponents 更改，不要再次发送 createSurface 或不相关的默认值。静态卡片需要使用非空且有效的增量，并设置 --flow-status FINISH；发送前先准备好该增量，并保留业务数据。发送完整消息，而不是 JSON 令牌。资源预检只检查增量。如果已知当前状态，则使用增量对其进行验证；符合 Schema 不代表业务安全。

dws aicard preview --file card.a2ui.json 会以 PROCESSING 状态发送自预览；--dry-run 不会发送。要完成静态预览，请使用相同的配置，通过 dws chat message update-a2ui-card --biz-id <data.bizId> --content <message-strings> --flow-status FINISH 完成，并为同一个 Surface 使用非空且保留状态的增量。不要重放表单默认值。使用服务器签发的 data.bizId，绝不要使用请求中的 bizCardId。如果缺少该值，请检查 updateWarning 和回执；不要自动重新创建。openTaskId 不能与 query-send-status 一起使用。

发送后，使用相同配置和目标下可用的回读功能，根据返回的实例/消息标识符识别此特定卡片。通用卡片文本和时间上相近并不足以确认。如果回读不可用或无法得出明确结论，请标记为未验证；仅凭 API 接受请求，不能声称用户已收到卡片或卡片已正确渲染。

收到请求时，报告文件、实际运行的检查以及交付结果。本地验证和请求被接受都不能证明客户端已正确渲染。