Ariand修雨
f7e8106a72
* docs(devapp): add image-upload recipe + "discovering commands" to dingtalk-dev skill The dingtalk-dev skill could set an app/robot icon via --icon-media-id but never documented where a mediaId comes from: the dev command set has no upload command, so a mediaId must be fetched from DingTalk's OpenAPI. Agents had to guess the flow. The per-resource refs also lacked a uniform pointer to self-discover commands and params, so they leaned on memory instead of --help / schema. recipes.md: new "上传图片拿 mediaId" recipe — credentials get -> gettoken -> OpenAPI /media/upload (multipart field `media`, type=image) -> robot config / app update --icon-media-id -> read back. Includes a curl example and notes the token TTL (~7200s, rate-limited) and a square-icon hint. references/*.md: append a Chinese "发现命令" block to each of the 10 product refs (app, credentials, webapp, permission, member, security, robot, version, event, connect). Each block shows that group's own `--help` plus `dws schema dev.app.<group>.<method>` (connect uses `dws schema dev.connect`), mirroring SKILL.md's MUST DO. Verified end-to-end on a real app (unifiedAppId via dws dev): uploaded a PNG through /media/upload, set the robot icon with the returned mediaId, and `robot get` reflected the new iconMediaId with robotStatus=ONLINE. All 10 `--help` targets and the 9 `dws schema dev.app.*` paths + `dws schema dev.connect` resolve. * docs(changelog): note dingtalk-dev mediaId recipe + command discovery (#508) --------- Co-authored-by: 修雨 <47820304+PeterGuy326@users.noreply.github.com>
3.6 KiB
3.6 KiB
事件订阅
把应用关心的事件推到回调地址；见 SKILL.md 概念地图。
dws dev app event list/subscribe/unsubscribe，按 --unified-app-id 定位，订阅/退订用 --event-codes（逗号分隔，一次多个）。参数查 dws schema dev.app.event.<method>。
规则：
- 写操作先
--dry-run预览，确认后--yes。 - 一次可订阅多个事件码，共用同一回调。
- 事件码定位优先用
event list --keyword <关键词>搜索（按事件码或事件名称模糊匹配）；只有用户明确要「全部事件」时才不带--keyword翻全量。 - 可订阅的事件码通过
event list查询：返回events[]列出eventCode/eventName/subscribed，不用查文档。 - 退订前先
event list确认当前订阅，避免退不存在的。 - 翻全量时用
--cursor/--page-size逐页处理；返回events/hasMore/nextCursor/pageSize，翻页继续传nextCursor。 - 批量或全量订阅前，先把候选
eventCode列给用户确认，再--dry-run→--yes。 - 返回看
events[].subscribed和pushType=STREAM（事件走 Stream 长连推送；connect 与事件订阅的关系见下方「Stream 长连」）。 subscribe/unsubscribe的--event-codes必填，返回success/operation/unifiedAppId/eventCodes/needsPublish/versionRequiredAction；失败时补errorCode/errorMsg/reason/retryable/action。- 如果服务端返回
errorCode=STREAM_NOT_CONNECTED、reason=STREAM_NOT_CONNECTED、retryable=false、action=run connect，先执行dev connect建联，再重试订阅。
Stream 长连：connect 与事件订阅的关系
钉钉一个应用就一条 Stream 长连（WebSocket），上面同时承载机器人消息、事件、卡片回调等多种 topic。connect 和 event 在这条长连上分工不同：
dev connect：用应用凭证把这条长连建起来并保活，但只注册了机器人消息处理（收 @机器人 → 转发本地 agent），不消费事件。event subscribe/unsubscribe：只是配置操作（配应用订阅哪些事件码），自己不建长连、不收事件；服务端要求应用的 Stream 长连已在线，否则返回STREAM_NOT_CONNECTED。- 两者唯一关联：先
dev connect把长连建在线，event subscribe才能成功——connect 负责「让长连在线」，subscribe 负责「配置订阅」。 - 当前限制：connect 的长连不处理事件，dws 也没有「收/消费事件」的运行时命令，event 只到「配置订阅」为止。订阅成功后真正的事件推送 dws 暂不消费——要消费得用注册了事件 handler 的 SDK 自接（事件结构走
dev doc search查）。
Stream 长连怎么建的
dev connect 内部用 dingtalk-stream-sdk-go，凭 clientId/clientSecret 建一条 WebSocket 长连并保活——底层网关握手、ticket、加解密都由 SDK 封装，agent 跑 dev connect 即可，不用碰这些。
dws 当前只消费机器人消息、不消费事件。要自己写事件消费程序补这个 gap 时，SDK 用法以官方文档为准（走 dev doc search，或看 github.com/open-dingtalk/dingtalk-stream-sdk-go）——注意事件用 RegisterAllEventHandler、connect 用的机器人是 RegisterChatBotCallbackRouter，两套别混；版本/接口会变，不在这里固化。
发现命令
调用任何方法前先查清楚再敲：
# 浏览命令组下的子命令与 flag
dws dev app event --help
# 查某方法的必填参数、类型、默认值
dws schema dev.app.event.<method>
按 dws schema 输出构造 --flag（flag 名 = schema 参数名）。