first commit

.agents/skills/dingtalk-misc/references/dev/recipes.md

@@ -0,0 +1,58 @@
+# 端到端链路（recipes）
+
+dev 的端到端任务都是「定ä½�应用，改容器æŸ�节点，按审批需è¦�走版本生效，最å�Žå›žè¯»éªŒè¯�ã€�。æ¯�步先 `--dry-run` 确认å†� `--yes`，å�‚数用对应命令的 `--help` 查询，¼Œç»†èŠ‚进对应 reference。
+
+## 建一个钉钉里打开的网页应用
+
+1. `dev app create --name <�>` 建应用，拿 unifiedAppId
+2. `dev app webapp config` �移动端/PC 首页（� webapp.md）
+3. `dev app version create` 建版本
+4. `dev app version check-approval` 预检是�需审批
+5. `dev app version publish` �布（需审批时让用户选审批人）
+6. 回读 `dev app version status` 到 `RELEASE` �算生效
+
+## ��从申请到生效
+
+1. `dev app permission list` 选 `scopeValue`（选择顺�� permission.md）
+2. `dev app permission add --scope-values <值>` 申请
+3. 若是 `requiredApproval` 的��，走版本：`version create`，� `check-approval`，� `publish --approver-user-id <用户选的>`，最� `version status`
+4. �审��直接开通，�必�版本
+
+## �一个答疑机器人并接到本地调试
+
+1. `dev app create --name <�>` 创建应用，拿明确 `unifiedAppId`
+2. `dev app robot config --unified-app-id <unifiedAppId>` �置机器人能力；需��用时� `robot enable`
+3. 线上使用闭环：`version create` → `check-approval` → `publish` → `version status`；`SELECT_APPROVER` 时必须等用户选择审批人，�默认�第一个
+4. 本地调试/值守：`dev connect --unified-app-id <unifiedAppId>` 把机器人接到本地 agent（� connect.md）；注�订阅事件��先建�长连（� event.md）
+5. 若走无绑定的 `robot submit/result`，�有结果返回明确 `unifiedAppId` �能继续版本�布
+6. 完��与缺 `unifiedAppId`�`SELECT_APPROVER` 等门�判定� [devapp.md](../devapp.md)「核心规则�：建��功 + 版本进入 `RELEASE`/`AUDIT`/`UNDER_REVIEW` �算完�
+
+## ��守护进程连接器（�存密钥）
+
+守护进程被 stop / kill / 崩溃�，通过�久化的 `unifiedAppId` �新拉�密钥并��，无需本地�存 AppSecret。
+
+1. `dev connect --daemon --unified-app-id <id> --channel <channel>` 首次�动（`unifiedAppId` 和 `channel` 会写入 `~/.dws/connect/<key>/daemon.pid`）
+2. `dev connect restart --unified-app-id <id>` ��：自动 stop 旧进程 → 从 dev 平�拉� AppKey/Secret → �新建�
+3. `dev connect status --unified-app-id <id>` 确认�� `healthy`
+4. 若 daemon.pid 未�久化 `unifiedAppId`（如用 `--robot-client-id` 直接�动的），restart 会�示改用 `--unified-app-id` �动
+
+注�：密钥��盘，�次 restart 动�从开�者平�获�；`daemon.pid` �存 `unifiedAppId`�`channel`�`clientId`（公开值）。
+
+## 上传图片拿 mediaId（应用图标 / 机器人图标）
+
+应用图标�机器人图标都� mediaId 指定，但 dev 命令集��上传——mediaId �调钉钉 OpenAPI 拿到：
+
+1. 拿凭�：`dev app credentials get --unified-app-id <id>` � `appKey/appSecret`（secret 按�感处�，�写进回答）
+2. � access_token：`GET https://oapi.dingtalk.com/gettoken?appkey=<appKey>&appsecret=<appSecret>`，�返回的 `access_token`（有效期约 7200 秒�gettoken 有频控，缓存�用别�次上传都�）
+3. 上传图片：`POST https://oapi.dingtalk.com/media/upload?access_token=<token>&type=image`，multipart 表�字段� `media`，返回 `media_id`（形如 `@lA...`）。图标用方形图（如 256×256 的 jpg/png）
+
+   ```
+   curl -F "media=@/path/to/img.png;type=image/png" \
+     "https://oapi.dingtalk.com/media/upload?access_token=<token>&type=image"
+   ```
+4. 用 mediaId 更新：机器人图标 `dev app robot config --unified-app-id <id> --icon-media-id <media_id>`；应用图标 `dev app update --unified-app-id <id> --icon-media-id <media_id>`。写�作先 `--dry-run` � `--yes`
+5. 回读：`dev app robot get` 看 `iconMediaId` �为新值（应用图标看 `app get` 的 `icon`）
+
+## 查「为什么没生效 / 机器人��到 / ��加了还报错�
+
+先 `dev app version status`——改�置�等于生效，未�到 `RELEASE` 就�生效。