dingtalk_channel_connect

钉钉渠道自动连接（有头浏览器）

本技能使用有头浏览器自动创建钉钉应用并绑定 QwenPaw 渠道。

强制规则

1. 必须以有头浏览器模式启动：

{"action": "start", "headed": true}

2. 遇到登录关卡时必须暂停：

   • 如果页面显示登录界面（例如登录提示、扫码登录、手机号/密码登录），立即停止自动化操作。
   • 明确提示用户先手动登录，然后等待用户回复“已登录 / 继续”。
   • 在用户确认之前，不要继续执行后续步骤。

3. 任何应用配置变更都只在创建新版本并发布后才会生效：

   • 配置完机器人相关信息后，你必须发布机器人。
   • 无论是新建应用还是修改应用信息（名称、描述、图标、机器人配置等），最后都必须执行“创建新版本 + 发布”。
   • 如果尚未完成发布，不要声称配置已生效。

执行前确认（必须首先执行）

在开始自动点击之前，先与用户进行“配置确认”，明确告知可自定义字段、图片规格和默认值。使用以下结构化确认：

1. 允许用户自定义以下字段：

   • 应用名称
   • 应用描述
   • 机器人图标图片 URL 或本地路径
   • 机器人消息预览图 URL 或本地路径

2. 明确说明图片规格（重点提示）：

   • 机器人图标：仅支持 JPG/PNG，240*240px 或更大，1:1 比例，小于 2MB，无圆角。
   • 机器人消息预览图：格式为 png/jpeg/jpg，不超过 2MB。

3. 明确说明默认值（用户未指定时自动使用）：

   • 应用名称：QwenPaw
   • 应用描述：Your personal assistant
   • 机器人图标：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png
   • 机器人消息预览图：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png

4. 如果用户未提供自定义值，你必须先明确回复：

   • “将全部使用默认设置（QwenPaw / Your personal assistant / 默认图片）。现在开始执行。”

图片上传策略（链接和路径均支持）

1. 如果用户提供本地路径，直接使用该路径上传。
2. 如果用户提供图片链接，先将其下载到本地临时文件，然后再上传。
3. 上传动作顺序必须为：
   • 先点击页面上传入口（以触发选择器）
   • 然后使用本地路径数组（paths_json）调用 file_upload
4. 如果因图片规格不匹配（尺寸、比例、大小、格式）导致上传失败：
   • 立即暂停自动化
   • 明确要求用户手动上传符合要求的图片
   • 在用户确认“已上传 / 继续”后，从当前步骤恢复

实操上传提示

1. file_upload 的 paths_json 必须是“JSON 字符串数组”——注意转义：

{
  "action": "file_upload",
  "paths_json": "[\"xxx.png\"]",
  "frame_selector": "iframe[src*=\"/fe/app?isHideOuterFrame=true\"]"
}

2. 如果页面位于 iframe 中，优先包含 frame_selector；否则可能找不到上传控件或无法触发选择器。

3. 必须先点击上传入口，然后再调用 file_upload；直接调用会得到：

   • No chooser. Click upload then file_upload.

4. 机器人图标区域的常见结构特征，可用于定位元素（示例；这些在钉钉控制台中可能显示为中文 UI 文案）：

   • text: "* 机器人图标"（机器人图标）
   • button: "使用应用图标"（使用应用图标）
   • button: "avatar"（通常内部包含 img "avatar"）

5. 当快照同时显示“使用应用图标”（“Use App Icon”）和“avatar”时，优先点击 avatar 按钮以触发上传，然后调用 file_upload。

自动化流程

第 1 步：打开钉钉开发者后台

1. 以有头模式启动浏览器（headed: true）
2. 访问 https://open-dev.dingtalk.com/
3. 调用 snapshot 检查是否需要登录

如果需要登录，请暂停并提示以下信息：

需要登录钉钉开发者后台。我已暂停自动化操作。请在已打开的浏览器中完成登录。完成后回复“继续”，我将从当前页面恢复操作。

第 2 步：创建企业内部应用

用户确认登录后，继续：

1. 进入创建路径：
   • 应用开发 -> 企业内部应用 -> 钉钉应用 -> 创建应用
2. 填写应用信息（优先使用用户自定义值，否则使用默认值）：
   • 应用名称：默认 QwenPaw
   • 应用描述：默认 Your personal assistant
3. 保存并创建应用

如果页面文本或结构与预期不符，请重新运行 snapshot，并根据可见文本语义重新定位元素。

第 3 步：添加机器人能力并发布

1. 在 应用能力 下点击 添加应用能力，找到 机器人 并添加
2. 将 机器人配置 右侧的开关按钮切换为启用
3. 填写 机器人名称、机器人简介 和 机器人描述
4. 上传 机器人图标（用户自定义或默认图片）：
   • 点击机器人图标标签下方的图片
   • 默认图片 URL：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png
   • 如果是链接，请先下载到本地，再上传
   • 如果图片不符合规格，请暂停并要求用户手动上传符合规格的图片后再继续
5. 上传 机器人消息预览图（用户自定义或默认图片）：
   • 点击机器人消息预览图标签下方的图片
   • 默认图片 URL：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png
   • 如果是链接，请先下载到本地，再上传
   • 如果图片不符合规格，请暂停并要求用户手动上传符合规格的图片后再继续
6. 确认消息接收模式设置为 Stream Mode（中文界面可能显示为 Stream 模式）
7. 选择 发布；会出现进一步的确认对话框 -- 选择发布。注意：进入下一步前 必须先发布机器人

第 4 步：创建版本并发布

1. 进入 应用发布 -> 版本管理与发布
2. 创建新版本（每次配置变更后都必须创建）
3. 填写版本描述；将应用可见范围设置为全部员工
4. 按照页面提示完成发布；会出现新的对话框 -- 选择确认发布
5. 只有在看到发布成功状态后，才能继续后续步骤或告知用户“配置已生效”

第 5 步：获取凭证

1. 进入 基础信息 -> 凭证与基础信息
2. 告知用户 Client ID（AppKey）和 Client Secret（AppSecret）位于此页面。不要主动进行更改；引导用户自行绑定

QwenPaw 绑定方式

获取凭证后，引导用户选择以下方式之一：

1. 控制台前端配置：

   • 在 QwenPaw 控制台中，进入 Control -> Channels -> DingTalk
   • 输入 Client ID 和 Client Secret

2. 配置文件方式：

"dingtalk": {
  "enabled": true,
  "bot_prefix": "[BOT]",
  "client_id": "Your Client ID",
  "client_secret": "Your Client Secret"
}

路径：~/.qwenpaw/config.json，位于 channels.dingtalk 下。

凭据交付要求（强制）

1. Agent 仅负责引导用户前往凭据页面，获取并展示 Client ID 与实际 Client Secret。
2. Agent 不得主动修改 console 配置或 ~/.qwenpaw/config.json。
3. 你必须指导用户使用以下两种方式之一手动填写凭据：
   • 控制台前端：Control -> Channels -> DingTalk
   • 配置文件：编辑 ~/.qwenpaw/config.json 中的 channels.dingtalk 字段

浏览器工具使用模式

默认按以下顺序执行：

1. 使用 start，并设置 headed: true
2. open
3. snapshot
4. 按需执行 click / type / select_option / press_key
5. 页面跳转后频繁执行 snapshot
6. 完成后执行 stop

稳定性与恢复策略

• 优先使用最新 snapshot 中的 ref；仅在必要时使用 selector。
• 每次关键点击或导航后，使用短暂等待（wait_for）并立即重新执行 snapshot。
• 如果会话过期或流程中途需要重新登录，请再次暂停并等待用户登录，然后从当前步骤继续。
• 如果自动化因租户权限或管理员审批而受阻，请清晰描述阻塞原因，并请用户手动完成该步骤后再继续。