Files

T

Ariand修雨 f7e8106a72 docs(devapp): add image-upload recipe + "discovering commands" to dingtalk-dev skill (#508 )

* 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>

2026-06-25 23:46:48 +08:00

2.0 KiB

Raw Permalink Blame History

应用基础操作

操作的是「应用」容器本体（见 SKILL.md 概念地图）；启停/删除改的是应用 appStatus，不是版本 versionStatus。

应用列表查询、详情、创建、修改、生命周期启停和删除。参数查 dws schema dev.app.<method>（list / get / create / update / delete / disable / enable）。

应用定位

所有单应用命令统一只用 --unified-app-id（全树主键）定位。--app-key/--name 只在 dev app list 里作列表过滤，不能定位单应用。拿到 appKey/agentId 时，只能做只读候选排查；写操作必须由用户或上游结果提供明确 unifiedAppId。

应用状态 appStatus

app get 的 appStatus 是字符串，取值如 normal、published。app list 不回这个字段（恒 null），看应用状态以 app get 为准。应用状态 appStatus 和版本状态 versionStatus 是两套，别混。遇到没见过的 appStatus 值原样展示。

app create、app update 不返回状态字段；版本状态由 version create 返回的 status（值如 INIT）表达，见 version.md。

要点

get 主要用于定位核验；若返回里带 appSecret，脱敏处理，不复制到回答；主动读凭证走 credentials get。
disable/enable 成功返回 {disabled:true} / {enabled:true} + message，不回 appStatus；以这个布尔判操作成败。要确认最终生效态再 get 看 appStatus 字符串值。
delete 前必须展示应用摘要；删除是异步，成功后延迟从列表消失。

错误处理

情况	处理
多应用命中	展示候选，停止写操作
`ServiceResult.success=false`	透传 `errorCode/errorMsg`

发现命令

调用任何方法前先查清楚再敲：

# 浏览命令组下的子命令与 flag
dws dev app --help

# 查某方法的必填参数、类型、默认值
dws schema dev.app.<method>

按 dws schema 输出构造 --flag（flag 名 = schema 参数名）。

2.0 KiB Raw Permalink Blame History Unescape Escape