deepin UOS AI 助手接入钉钉（DingTalk）配置指南

📌 本文摘要

本指南用于把 deepin UOSAI 助手 接入到 钉钉（DingTalk）。

你只需要照着做：创建钉钉应用 → 添加机器人并选择 Stream 模式 → 创建 AI 消息卡片 → 开通权限 → 发布版本 → 拿到 Client ID/Secret → 在 UOSAI 后台填入 → 验证连接通道 → 测试。

🚀 开始前你需要准备什么

你能登录 钉钉开放平台 ：https://open-dev.dingtalk.com/
你的钉钉账号在企业内具备 开发者权限（没有权限会创建不了应用/开通不了权限）
你本地已经启动了 UOSAI，并能打开应用设置。

💡 1.创建钉钉应用（企业内部应用）

登录钉钉开放平台：https://open-dev.dingtalk.com/

注意：创建钉钉应用前，请确保你的账号具备开发者权限。
在左侧目录树中选择 "企业内部应用" -> "钉钉应用" -> "创建应用"

3.填写应用名称、图标等信息后保存。

💡 2.添加机器人，并设置消息接收模式为 Stream
1. 在应用配置里找到"机器人"相关入口，点击 添加机器人。
1. 点击按钮进入机器人配置。
2. 填写机器人简介、描述、预览图等，点击发布。
3. 非常关键：消息接收模式选择 Stream 模式。
  
  💡 3.创建消息卡片（推荐：AI 卡片）
  
  这一步用于让钉钉侧可以使用 AI 互动卡片能力。按项目当前文档建议，推荐配置。
  1. 登录 钉钉卡片平台 ：https://open-dev.dingtalk.com/fe/card
  2. 左侧选择 "模板管理" -> "新建模板"。
  3. 按下列信息配置模板：
  - 卡片类型：消息卡片
  - 卡片模板场景：AI 卡片
  - 关联应用：选择你刚创建的钉钉应用
  1. 进入卡片模板编辑页面后，无需修改内容 ，点击左上角ID（非必需，流式卡片体验较好），提示复制成功后，依次点击 "保存" 和 "发布"。（保存好id信息，若丢失可回到该页面寻找）
  💡 4.授予应用必要权限
  1. 回到钉钉开放平台，进入："应用开发" -> "钉钉应用"。
  2. 点击你的应用名称进入详情。
  3. 左侧进入 "开发配置" -> "权限管理"。
  4. 搜索并申请以下权限（按文档要求）：
  - 搜索 Card：勾选
    - 互动卡片实例写权限
    - AI卡片流式更新权限
    - 搜索 qyapi_robot_sendmsg：开通
    - 企业内机器人发送消息权限
      
      如果你申请权限时提示需要管理员审批，请按企业流程完成审批，否则机器人可能无法发消息或更新卡片。
      
      💡 5.发布应用版本（不发布通常无法给企业用户使用）
      1. 左侧进入 "应用发布" -> "版本管理与发布"，点击** "创建新版本"**。
      2. 填写版本号、可见范围等，点击 "保存"，再点击** "确认发布"**。
        
        💡 6. 获取凭证信息（Client ID / Client Secret）
        
        左侧进入 "基础信息" -> "凭证与基础信息"。
        
        复制并保存：Client ID 和 Client Secret
        
        💡 7.在 UOSAI 后台完成钉钉配置
        
        确保 UOSAI 已启动。
        
        找到找到IM接入中的 钉钉 / DingTalk 的配置项：
        
        打开"启用/开关"
        
        将第3步的card ID 和第 6 步的 Client ID 和Client Secret 填入对应位置
        
        点击 保存配置 。
        
        💡8.测试是否接入成功
        
        启动 uos-ai。
        
        在钉钉群里与机器人对话（或 @ 机器人）。（进群 - 添加 - 搜索添加正确的机器人 - 完成添加）
        
        如果机器人能正常回复，说明接入成功。
        
        常见问题
        
        Q1：机器人收不到消息？
        
        确认第 2 步选择的是 Stream 模式
        
        确认第 8 步 验证连接通道 已保存
        
        确认权限已申请并通过审批（第 3 步）
        
        Q2：机器人能收消息，但发不出去？
        
        优先检查是否开通了 qyapi_robot_sendmsg（第 3 步）
        
        再检查 UOSAI 后台的Client ID 和 Client Secret 是否填错（第 7 步）
        
        安全提示
        
        Client Secret 属于敏感信息：不要公开分享、不要提交到公开仓库。
        
        建议使用密码管理器保存。