钉钉 AI 机器人接入攻略：真实截图完成权限、卡片导入与发布

Sparkles 接入的是钉钉企业内部应用机器人。需要启用机器人能力，并使用 Stream 模式接收消息；群里的自定义 Webhook 机器人不能替代应用机器人。真实站点中，消息、图片和文件仍按 Sparkles 的会话权限、模型权限与 Credits 规则处理。

同一个应用只连接一个管理员和一个环境。先在测试环境完成绑定和验收，再把同样的配置带到正式环境。

打开钉钉开发者后台的“权限管理”，搜索并确认以下能力已开通：企业内机器人发消息权限、互动卡片实例写权限、AI 卡片实例写权限，以及 AI 卡片流式更新权限。真实截图里，前三项卡片/机器人能力都能看到“已开通”状态；其他未使用的待办或群管理权限不必为了这条链路一起申请。

如果你要使用卡片按钮回调，还要按当前开放平台的说明配置对应的互动卡片回调能力。权限改动后必须创建版本并发布，单看权限页的修改状态不能代表线上应用已经生效。

1. 在卡片平台新建一个 AI 卡片模板，使用新的草稿承载导入，避免覆盖已有版本。
2. 进入卡片搭建器，点击右上方“更多”，选择“导入卡片模板”。真实截图显示导入入口位于复制和导出菜单的同一组操作中。
3. 选择 Sparkles 提供的 v1.1 JSON 文件并确认。导入会替换当前草稿，导入完成后先检查画布，再保存。
4. 回到模板列表，确认名称、创建人、更新时间和模板 ID 都属于你当前企业。不要直接复用别的企业发布的模板 ID。

模板文件下载入口：钉钉卡片模板 v1.1。

导入后打开左侧“变量”面板，确认字段没有被改名或删除。必须保留 content（AI 流式富文本）、status、openUrl、choiceCount，以及 choiceId0 到 choiceId5、choiceLabel0 到 choiceLabel5。空的选择文案会在投递时隐藏对应按钮。

变量只描述卡片如何显示；会话、任务、发起者和权限由 Sparkles 服务端保存，不能通过卡片变量替换成其他用户或会话。

点击“预览模式”，先检查正文宽度、长文本换行、中文按钮和“查看作品与对话”入口。然后依次切换“处理中”“输出中”“完成”“失败”四种状态：处理中应有处理提示，输出中允许继续更新正文，完成状态不应停留在转圈，失败状态应隐藏无效选项并保留网页入口。

这些是平台搭建器的真实预览，不等于机器人已经收到一条消息。真正联调还要使用已发布应用发送一次短消息，并检查原卡片是否持续更新。

卡片搭建器中的“发布”会生成当前企业可使用的卡片模板 ID；应用的“版本管理与发布”则让机器人能力、权限和事件配置对企业成员生效。两者缺一不可。

真实版本页显示应用版本 1.0.1 和 1.0.0 已上线。发布后复制你自己的模板 ID，回到 Sparkles 账户页的钉钉机器人设置中填写。修改模板时复制成新版本，排空旧消息后再切换，不要让同一条历史消息使用新旧字段混合的模板。

在测试站账户页打开“钉钉机器人”，按页面提示填写 Client ID / AppKey、Client Secret / AppSecret、Robot Code 和卡片模板 ID。密钥只在专用表单里提交，页面提交后会清空，不要放进截图、普通聊天、Git 或攻略正文。

连接成功后，管理员在机器人私聊中完成一次性绑定，再先发送 /status。确认状态正常后，才测试一条简短对话或一张低成本图片。群聊默认关闭，需要先把机器人加入群并 @ 一次，再在 Sparkles 中启用该群。

1. 权限页确认四项能力已开通。
2. 卡片变量和四种状态预览无误。
3. 卡片模板已经发布，并记录自己的模板 ID。
4. 应用版本已经发布，机器人保持 Stream 模式。
5. 私聊 /status、短文本、按钮回调和图片附件各验收一次。
6. 再启用目标群，并从“仅 @ + 仅管理员”开始逐步扩大成员范围。

如果出现权限错误、卡片更新失败或附件状态未知，先回网页查看原任务和投递记录，不要盲目重复提交会计费的创作请求。