Hermes DingTalk 媒体支持

当 Hermes DingTalk 机器人需要发送或接收原生媒体附件（尤其是 MEDIA:/absolute/path 类型响应未能作为独立的 DingTalk 图片/文件送达）时，请使用此技能。

配套脚本文件

该 Hermes 技能包含一个非 Hermes 原生的辅助脚本：

• scripts/fix_dingtalk_media_support.py：验证 Hermes 源码树是否已集成 DingTalk 媒体实现、检查所需 Python 模块是否就绪、执行语法校验，并可重启指定 Hermes profile 的网关服务。
• scripts/send_dingtalk_file.py：利用 Hermes profile 中配置的凭据，通过 DingTalk 机器人媒体 API 发送本地图片/文件，无需修改 Hermes 核心代码。

这些辅助脚本本身不包含任何凭据。可在任意路径下运行校验脚本，并通过 --repo-root 参数传入 Hermes 源码仓库根目录：

python /path/to/hermes-dingtalk-media/scripts/fix_dingtalk_media_support.py --repo-root "$HERMES_REPO"
python /path/to/hermes-dingtalk-media/scripts/fix_dingtalk_media_support.py --repo-root "$HERMES_REPO" --restart-profile 

若环境变量 HERMES_REPO 已指向 Hermes 源码树，则可省略 --repo-root 参数。

如需在不修改 Hermes 源码的前提下验证原生 DingTalk 文件投递能力，可从已配置的 Hermes profile 向目标发送本地文件：

python /path/to/hermes-dingtalk-media/scripts/send_dingtalk_file.py --profile  --target-name "" /tmp/example.txt

如需向单个用户（一对一）发送机器人消息，请传入 DingTalk 员工 ID / 用户 ID：

python /path/to/hermes-dingtalk-media/scripts/send_dingtalk_file.py --profile  --user-id "" /tmp/example.txt

核心流程

1. 确认机器人能正常接收回调事件。

   • 日志中应出现 DingTalk callback received 和 inbound message: platform=dingtalk 等字样。
   • 若未收到回调，请优先排查 Stream Mode 连通性及网络问题。

2. 确认 Hermes 已成功解析媒体标签。

   • 助手响应中应包含形如 MEDIA:/absolute/path/to/file 的标记。
   • 网关日志中应出现 Sending DingTalk media via ... robot API 类似记录。

3. 将本地文件上传至 DingTalk 服务器。

   • 接口地址：POST https://oapi.dingtalk.com/media/upload
   • 参数：access_token；图像类扩展名（如 .png/.jpg）使用 type=image，其余类型使用 type=file。
   • Multipart 字段名：media。
   • 上传成功后使用返回的 media_id 或 mediaId。

4. 使用已上传的 media_id 调用对应机器人发送接口。

   • 群聊场景：POST https://api.dingtalk.com/v1.0/robot/groupMessages/send
   • 一对一机器人对话：POST https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend

关键路由规则

• 切勿对 Hermes 机器人的一对一媒体回复使用 privateChatMessages/send 接口；即使上传成功，该接口也可能返回 resource.not.found 错误。
• 一对一机器人媒体发送必须使用 oToMessages/batchSend，并设置 userIds: [sender_staff_id]。
• 群聊媒体发送必须使用 groupMessages/send，并传入 openConversationId。
• 优先从入站 DingTalk 回调中提取 message.robot_code，而非使用配置文件中预设的 app/client ID；仅当无回调上下文时，才允许回退至配置值。
• 务必保留入站回调上下文中的 chat_id，它可提供 conversation_type、robot_code 和 sender_staff_id 等关键字段。

请求载荷（Payloads）

群聊媒体发送：

payload = {
    "robotCode": robot_code,
    "openConversationId": chat_id,
    "msgKey": msg_key,
    "msgParam": json.dumps(msg_param, ensure_ascii=False),
}

一对一媒体发送：

payload = {
    "robotCode": robot_code,
    "userIds": [sender_staff_id],
    "msgKey": msg_key,
    "msgParam": json.dumps(msg_param, ensure_ascii=False),
}

已知可用的媒体模板示例：

image_candidates = [
    ("sampleImageMsg", {"photoURL": media_id}),
    ("sampleImageMsg", {"mediaId": media_id}),
    ("sampleImage", {"mediaId": media_id}),
]

file_candidates = [
    ("sampleFile", {"mediaId": media_id, "fileName": file_name}),
    ("sampleFileMsg", {"mediaId": media_id, "fileName": file_name}),
]

Hermes 实现检查清单

在 gateway/platforms/dingtalk.py 中：

• 实现 send_image_file、send_document 和 send_video 方法。
• 将入站消息中的 downloadCode 解析为本地缓存路径，用于图像/音频/视频/文档等资源。
• 若因关闭或重连卡死，应改用可取消的 Stream 循环，而非直接调用 dingtalk_stream.DingTalkStreamClient.start()；SDK 可能静默吞掉取消信号。
• 若替换 SDK 的 start() 方法，须在打开 Stream 连接前显式调用 self._stream_client.pre_start()。
• 记录媒体路由信息，但不得泄露敏感凭据，例如： Sending DingTalk media via oto robot API; robot_code_source=callback recipient_source=sender_staff_id。

在 tools/send_message_tool.py 中：

• 支持解析 DingTalk 的 MEDIA: 协议标记。
• 对于无回调上下文的直发场景，一对一媒体发送必须显式传入 DingTalk 用户 ID / 员工 ID；否则默认按群聊方式发送。

在 agent/prompt_builder.py 中：

• 添加 DingTalk 平台提示，说明可通过 MEDIA:/absolute/path/to/file 发送原生媒体。

验证步骤

执行以下命令：

cd "$HERMES_REPO"
python -m py_compile gateway/platforms/dingtalk.py tools/send_message_tool.py agent/prompt_builder.py
python /path/to/hermes-dingtalk-media/scripts/fix_dingtalk_media_support.py --repo-root "$HERMES_REPO"
git diff --check
python /path/to/hermes-dingtalk-media/scripts/fix_dingtalk_media_support.py --repo-root "$HERMES_REPO" --restart-profile 

分别测试图片与文件投递功能：

result = await adapter._send_robot_media(
    chat_id=chat_id,
    file_path="/tmp/example.png",
    media_kind="image",
)

result = await adapter._send_robot_media(
    chat_id=chat_id,
    file_path="/tmp/example.txt",
    media_kind="file",
    file_name="example.txt",
)

预期成功响应结构：

{"success": True, "error": None, "message_id": "..."}

失败信号识别

• resource.not.found 出现在 media/upload 成功之后：说明上传成功，但后续发送接口地址、robotCode 或接收方参数有误。
• robot 不存在：通常由 robotCode 错误导致；请优先使用回调中 message.robot_code 的值。
• 一对一聊天中出现 private HTTP 400 ... resource.not.found：请将 privateChatMessages/send 切换为 oToMessages/batchSend。
• 日志中完全缺失 DingTalk callback received：说明 DingTalk 回调未送达 Hermes；请检查机器人/App 配置、Stream Mode 开启状态、是否存在竞争网关进程，以及 profile 凭据有效性。