From cc8a726b0af65df5aef4a47ba2937b3cd5688b44 Mon Sep 17 00:00:00 2001 From: qinze Date: Thu, 18 Jun 2026 09:09:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(dev):=20dingtalk-dev=20references=20?= =?UTF-8?q?=E4=BA=8C=E6=AC=A1=E7=B2=BE=E7=AE=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - permission/robot/version 删 bash 命令示例堆叠(schema/--help 已覆盖), 保留状态机/枚举语义/链路/gotcha - 去掉所有 reference 的"概念锚点"自造词标签,保留指向概念地图的引语 - SKILL.md 生效模型去"(最重要)";connect 去加粗 Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/multi/dingtalk-dev/SKILL.md | 2 +- skills/multi/dingtalk-dev/references/app.md | 2 +- .../multi/dingtalk-dev/references/connect.md | 2 +- .../dingtalk-dev/references/credentials.md | 2 +- skills/multi/dingtalk-dev/references/event.md | 2 +- .../multi/dingtalk-dev/references/member.md | 2 +- .../dingtalk-dev/references/permission.md | 71 +++---------- skills/multi/dingtalk-dev/references/robot.md | 86 ++++------------ .../multi/dingtalk-dev/references/security.md | 2 +- .../multi/dingtalk-dev/references/version.md | 99 +++++-------------- .../multi/dingtalk-dev/references/webapp.md | 2 +- 11 files changed, 68 insertions(+), 204 deletions(-) diff --git a/skills/multi/dingtalk-dev/SKILL.md b/skills/multi/dingtalk-dev/SKILL.md index 2a824e63..527b3109 100644 --- a/skills/multi/dingtalk-dev/SKILL.md +++ b/skills/multi/dingtalk-dev/SKILL.md @@ -52,7 +52,7 @@ metadata: 应用定位统一只用 `--unified-app-id`（--app-key/--name 仅作 list 过滤，不能定位单应用）。旧的 `--agent-id`/`--app-id`/`--custom-key` 定位 flag 已移除——agentId 只是返回字段，不再是入参定位手段。appKey 与 clientId 是同一标识的新旧两名，无需追问区别。 -### 生效模型（最重要） +### 生效模型 - 改配置不等于线上生效，需审批的变更（如 `requiredApproval=true` 的权限点）先累积在开发态，必须走版本通道才上线： ``` 配置变更（permission add / robot config / webapp config ...） diff --git a/skills/multi/dingtalk-dev/references/app.md b/skills/multi/dingtalk-dev/references/app.md index bf667c7a..b5e25c62 100644 --- a/skills/multi/dingtalk-dev/references/app.md +++ b/skills/multi/dingtalk-dev/references/app.md @@ -1,6 +1,6 @@ # 应用基础操作 -> 概念锚点：操作的是「应用」容器本体（见 SKILL.md 概念地图）；启停/删除改的是应用 appStatus，不是版本 versionStatus。 +> 操作的是「应用」容器本体（见 SKILL.md 概念地图）；启停/删除改的是应用 appStatus，不是版本 versionStatus。 应用列表查询、详情、创建、修改、生命周期启停和删除。参数查 `dws schema dev.app.`（list / get / create / update / delete / disable / enable）。 diff --git a/skills/multi/dingtalk-dev/references/connect.md b/skills/multi/dingtalk-dev/references/connect.md index dfa61cc9..04b51d8f 100644 --- a/skills/multi/dingtalk-dev/references/connect.md +++ b/skills/multi/dingtalk-dev/references/connect.md @@ -1,6 +1,6 @@ # 本地建联（把机器人接到本地 agent） -> 概念锚点：`dws dev connect` 是 dev 顶层命令，把一个**现成机器人**接到当前渠道的本地 agent CLI 做调试/值守——只建联、不建号。缺机器人先走 robot.md 的 `robot submit`/`result` 建号拿 clientId/clientSecret。 +> `dws dev connect` 是 dev 顶层命令，把一个现成机器人接到当前渠道的本地 agent CLI 做调试/值守——只建联、不建号。缺机器人先走 robot.md 的 `robot submit`/`result` 建号拿 clientId/clientSecret。 ## 起连接 diff --git a/skills/multi/dingtalk-dev/references/credentials.md b/skills/multi/dingtalk-dev/references/credentials.md index a1df99e9..b4a740c7 100644 --- a/skills/multi/dingtalk-dev/references/credentials.md +++ b/skills/multi/dingtalk-dev/references/credentials.md @@ -1,6 +1,6 @@ # 应用凭证读取 -> 概念锚点：凭证=应用调 OpenAPI 的身份（appKey=clientId / appSecret=clientSecret）；见 SKILL.md 概念地图。 +> 凭证=应用调 OpenAPI 的身份（appKey=clientId / appSecret=clientSecret）；见 SKILL.md 概念地图。 `dws dev app credentials get --unified-app-id ` 读取应用凭证。参数查 `dws schema dev.app.credentials.get`。 diff --git a/skills/multi/dingtalk-dev/references/event.md b/skills/multi/dingtalk-dev/references/event.md index a8f5a49e..c020d56a 100644 --- a/skills/multi/dingtalk-dev/references/event.md +++ b/skills/multi/dingtalk-dev/references/event.md @@ -1,6 +1,6 @@ # 事件订阅 -> 概念锚点：把应用关心的事件推到回调地址；见 SKILL.md 概念地图。 +> 把应用关心的事件推到回调地址；见 SKILL.md 概念地图。 `dws dev app event list/subscribe/unsubscribe`，按 `--unified-app-id` 定位，订阅/退订用 `--event-codes`（逗号分隔，一次多个）。参数查 `dws schema dev.app.event.`。 diff --git a/skills/multi/dingtalk-dev/references/member.md b/skills/multi/dingtalk-dev/references/member.md index c3113a94..206a70e2 100644 --- a/skills/multi/dingtalk-dev/references/member.md +++ b/skills/multi/dingtalk-dev/references/member.md @@ -1,5 +1,5 @@ # 成员管理 -> 概念锚点：成员=谁能改这个应用（DEVELOPER 等角色）；见 SKILL.md 概念地图。 +> 成员=谁能改这个应用（DEVELOPER 等角色）；见 SKILL.md 概念地图。 `dws dev app member list/add/remove` 管理应用成员。参数查 `dws schema dev.app.member.`（add/remove 需 `--member-user-ids` 列表 + `--member-type`，如 DEVELOPER）。 diff --git a/skills/multi/dingtalk-dev/references/permission.md b/skills/multi/dingtalk-dev/references/permission.md index 84eaf9b2..dba7728e 100644 --- a/skills/multi/dingtalk-dev/references/permission.md +++ b/skills/multi/dingtalk-dev/references/permission.md @@ -1,83 +1,44 @@ # 权限管理 -> 概念锚点：权限点 scopeValue 是授权单元，一个权限点授权一组 OpenAPI；requiredApproval=true 的变更走版本通道生效（见 SKILL.md 生效模型）。 +> 权限点 scopeValue 是授权单元，一个权限点授权一组 OpenAPI；requiredApproval=true 的变更走版本通道生效（见 SKILL.md 生效模型）。 -查询、申请、取消开放平台应用的 APP 应用权限和 SNS 个人权限。 +查询、申请、取消开放平台应用的 APP 应用权限和 SNS 个人权限。参数查 `dws schema dev.app.permission.`。 ## 权限列表 -```bash -dws dev app permission list --unified-app-id ID --format json -dws dev app permission list --unified-app-id ID --keyword "机器人发消息" --auth-status UNAUTHED --format json -dws dev app permission list --unified-app-id ID --scope-type SNS --format json -dws dev app permission list --unified-app-id ID --scope-value qyapi_robot_sendmsg --format json -``` - -参数查 `dws schema dev.app.permission.list`。`--scope-value` 传入即进单权限详情模式；`--scope-type` 取 `APP`/`SNS`，留空返回两者；一个应用可能 150+ 权限点，建议 `--page-size` 不超过 50。 - -**状态判断：** +`--scope-value` 传入即进单权限详情模式；`--scope-type` 取 `APP`/`SNS`，留空返回两者；一个应用可能 150+ 权限点，游标分页续翻、`--page-size` 不超过 50。 `--auth-status` 是查询过滤条件： | authStatus | 含义 | |------------|------| | `ALL` | 不按授权状态过滤 | -| `AUTHED` | 只看已授权/已开通的权限点 | -| `UNAUTHED` | 只看未授权/未开通的权限点 | +| `AUTHED` | 只看已授权/已开通 | +| `UNAUTHED` | 只看未授权/未开通 | 单个权限项返回的 `status` 是内部操作态： | status | 枚举 | 含义 | 下一步 | |--------|------|------|--------| | `0` | `STATUS_OBTAINED` | 权限已获得 | 不要重复申请；如需取消，确认 `canRemove=true` 后走 `permission remove` | -| `1` | `STATUS_APPLYING` | 权限申请中 | 不要重复申请；查看 `authedStatusDesc`，通常等待审批或版本发布 | -| `2` | `STATUS_CAN_APPLY` | 权限可以申请 | 可走 `permission add --dry-run` | -| `3` | `STATUS_CAN_NOT_APPLY` | 权限不可以申请 | 停止申请，展示 `applyDisabledReason/displayMessage` | +| `1` | `STATUS_APPLYING` | 权限申请中 | 不要重复申请；看 `authedStatusDesc`，通常等待审批或版本发布 | +| `2` | `STATUS_CAN_APPLY` | 可以申请 | 走 `permission add` | +| `3` | `STATUS_CAN_NOT_APPLY` | 不可申请 | 停止，展示 `applyDisabledReason/displayMessage` | -`authedStatusDesc` 是给用户看的细分状态：`OPENED`/`APPLIED`/`TO_BE_PUBLISHED` 表示已开通、已申请或待发布；`NOT_OPEN`/`NOT_APPLIED` 表示未开通/未申请；`AUDIT_PROCESSING` 表示审批中；`AUDIT_REFUSE` 表示审批未通过。判断能否操作仍以 `status`、`canEdit`、`canApplyDirectly`、`allowedActions` 为准。 +`authedStatusDesc` 是给用户看的细分状态：`OPENED`/`APPLIED`/`TO_BE_PUBLISHED`=已开通/已申请/待发布；`NOT_OPEN`/`NOT_APPLIED`=未开通/未申请；`AUDIT_PROCESSING`=审批中；`AUDIT_REFUSE`=审批未通过。能否操作仍以 `status`、`canEdit`、`canApplyDirectly`、`allowedActions` 为准。 -**翻页：** +list 默认同时返回 APP 和 SNS 权限；列表模式只返回 `apiPreview`，`--scope-value` 详情模式返回完整 `apiList`。`permission search`/`detail` 是 `list` 的别名。 -权限列表用游标分页（与 app/version list 一致）。一个应用可能有 150+ 个权限点，逐页用 `nextCursor` 续翻： - -```bash -dws dev app permission list --unified-app-id ID --page-size 50 --format json -# → 出参 nextCursor=，续翻： -dws dev app permission list --unified-app-id ID --cursor --page-size 50 --format json -``` - -出参 `nextCursor` 为空（或 `hasMore=false`）时表示已到末尾。 - -**规则：** -- `permission search` 和 `permission detail` 是 `list` 的 CLI 别名。 -- 默认同时返回 APP 和 SNS 权限。 -- 列表模式只返回 `apiPreview`；`--scope-value` 详情模式返回完整 `apiList`。 - -**scopeValue 选择顺序：** - -1. 用户给了 `scopeValue` → 精确匹配 -2. 用户给了 API 名 → `keyword` 搜索，匹配 `apiPreview.name` -3. 用户给了权限名 → 匹配 `scopeName/scopeDesc` -4. 多个候选 → 展示列表让用户选择，不自动取第一条 +scopeValue 选择顺序： +1. 用户给了 `scopeValue`，精确匹配 +2. 给了 API 名，用 `keyword` 搜，匹配 `apiPreview.name` +3. 给了权限名，匹配 `scopeName/scopeDesc` +4. 多个候选，展示列表让用户选，不自动取第一条 ## 申请权限 -```bash -dws dev app permission add --unified-app-id ID --scope-values qyapi_robot_sendmsg --dry-run --format json -dws dev app permission add --unified-app-id ID --scope-values Contact.User.mobile,qyapi_robot_sendmsg --yes --format json -``` - -**规则：** -- `--scope-values` 传 `scopeValue`，多个逗号分隔，必须来自 `permission list` 的返回。 -- 已开通跳过，不可编辑拒绝。 -- `requiredApproval=true` 允许申请——写入版本变更，审批在版本发布时处理。 -- 不在此处选审批人。 +`--scope-values` 传 `scopeValue`，多个逗号分隔，必须来自 `permission list` 返回。已开通跳过、不可编辑拒绝。`requiredApproval=true` 允许申请——写入版本变更，审批在版本发布时处理。不在此处选审批人。 ## 取消权限 -```bash -dws dev app permission remove --unified-app-id ID --scope-values qyapi_robot_sendmsg --dry-run --format json -dws dev app permission remove --unified-app-id ID --scope-values qyapi_robot_sendmsg --yes --format json -``` - `--scope-values` 多个逗号分隔；上游一次只取消一个权限点，多条时 CLI 逐条调用并返回 `results` 聚合数组。未开通返回 `NOT_AUTHED`；不可编辑返回 no-edit 原因。 diff --git a/skills/multi/dingtalk-dev/references/robot.md b/skills/multi/dingtalk-dev/references/robot.md index c7ecf36d..4144a238 100644 --- a/skills/multi/dingtalk-dev/references/robot.md +++ b/skills/multi/dingtalk-dev/references/robot.md @@ -1,92 +1,48 @@ # 机器人能力 -> 概念锚点：机器人是应用的能力扩展之一；建号/配置在此，接到本地 agent 调试用 `dws dev connect`（见 connect.md）。 +> 机器人是应用的能力扩展之一；建号/配置在此，接到本地 agent 调试用 `dws dev connect`（见 connect.md）。 -为开放平台企业内部应用创建和配置机器人。分两类场景： +为开放平台企业内部应用创建和配置机器人。参数查 `dws schema dev.app.robot.`。分两类场景： -1. **新建智能体机器人**：异步创建一个新的 Agent 应用 + 承载机器人（`submit` / `result`）。同步建号（一次性创建应用+机器人）已下线，统一走异步。 -2. **现有应用配置机器人**：在已存在的应用上配置/启用/停用机器人（`get` / `config`(upsert) / `enable` / `disable`），通过 `--unified-app-id` 定位。 +1. 新建智能体机器人：异步创建一个新的 Agent 应用 + 承载机器人（`submit` / `result`）。同步建号已下线，统一走异步。 +2. 现有应用配置机器人：在已存在的应用上配置/启用/停用机器人（`get` / `config`(upsert) / `enable` / `disable`），用 `--unified-app-id` 定位。 > `corpId` / `userId` 由系统上下文自动注入，CLI 不传。所有写操作先 `--dry-run`，确认后再 `--yes`。 ## 一、新建智能体机器人（异步建号） -同步建号已下线，新建智能体一律用异步 `submit` 提交任务 + `result` 轮询。也适合创建耗时较长或需要失败重试的场景。 +`submit` 提交任务拿 `taskId`，`result --task-id ` 轮询。`submit` 返回 `taskId/status/expiresIn/interval/retryCount`，提交成功通常是 `WAITING`。失败重试：把上次 `taskId` 通过 `--task-id` 传回 `submit`，避免重复创建。只有 `result` 返回 `SUCCESS` 才能用返回的 `agentId/robotCode/clientId/clientSecret`。 -```bash -# 提交任务 -dws dev app robot submit --name 我的智能体 --robot-name 小助手 --desc "处理审批问答" --dry-run --format json -dws dev app robot submit --name 我的智能体 --robot-name 小助手 --desc "处理审批问答" --yes --format json -# → 返回 taskId - -# 轮询结果 -dws dev app robot result --task-id --format json -``` - -- `submit` 返回 `taskId / status / expiresIn / interval / retryCount`，提交成功后通常是 `WAITING`。 -- 失败重试：把上次的 `taskId` 通过 `--task-id` 传入 `submit`，避免重复创建。 -- `result` 返回任务状态；只有 `SUCCESS` 时才能使用返回的 `agentId / robotCode / clientId / clientSecret`。 - -异步创建任务状态： +异步任务状态： | status | 含义 | 下一步 | |--------|------|--------| -| `WAITING` | 任务已提交，仍在创建中 | 按 `interval` 轮询 `robot result` | -| `SUCCESS` | 创建完成 | 保存 `robotCode/clientId/clientSecret`，凭据按敏感信息处理 | -| `APPROVAL_REQUIRED` | 创建编排返回需审批 | 不要重复建号；按返回信息或开发者后台审批后再继续 | -| `FAIL` | 创建失败 | 读取 `errorCode/errorMsg/failReason`；可带原 `taskId` 重新 `submit` | -| `EXPIRED` | `taskId` 不存在或超过有效期 | 重新 `submit`，必要时换新 `taskId` | +| `WAITING` | 创建中 | 按 `interval` 轮询 `robot result` | +| `SUCCESS` | 创建完成 | 保存 `robotCode/clientId/clientSecret`，凭据按敏感处理 | +| `APPROVAL_REQUIRED` | 创建编排需审批 | 不要重复建号；按返回信息或后台审批后再继续 | +| `FAIL` | 创建失败 | 读 `errorCode/errorMsg/failReason`；可带原 `taskId` 重新 `submit` | +| `EXPIRED` | `taskId` 不存在或过期 | 重新 `submit` | ## 二、现有应用的机器人配置 -### 查询配置 - -```bash -dws dev app robot get --unified-app-id --format json -``` - -返回机器人基础信息、回调地址、模式、状态和技能列表。应用尚未配置机器人时后端会返回 `robot info is not exist`。 +`robot get` 返回机器人基础信息、回调、模式、状态、技能列表；应用尚未配置机器人时后端返回 `robot info is not exist`。 状态判断： +- `status=1`：OFFLINE，配置存在但停用/下线。 +- `status=2`：ONLINE，配置已生效；`robotCode` 可用于加群、机器人身份发消息或后续建联。 +- `robot get` 返回 `success=true` 且含 `robotCode` = 配置已落库，不是异步等待态。 +- ONLINE 只代表能力已开启。要让机器人自动处理消息，还需配 `--outgoing-url`/`--event-callback-url`，或用 `dev connect` 接本地 Agent（见 connect.md）。 +- 未配置机器人时不返回 `status`，而是业务错误 `robot info is not exist`；这时走 `robot config`，不是 `enable`。 -- `status=1`：OFFLINE，机器人配置存在但处于停用/下线状态。 -- `status=2`：ONLINE，机器人配置已生效；`robotCode` 可用于加群、机器人身份发消息或后续建联。 -- `robot get` 返回 `success=true` 且包含 `robotCode` 时，说明配置已落库，不是异步等待态。 -- ONLINE 只代表开放平台机器人能力已开启。若要让机器人自动处理消息，还需要配置 `--outgoing-url` / `--event-callback-url`，或用 `dev connect` 接到本地 Agent（见 connect.md）。 -- 未配置机器人时不会返回 `status`，而是业务错误 `robot info is not exist`；这时走 `robot config`，不是 `enable`。 - -### 配置（upsert）/ 启用 - -- `config` 是 **upsert**：建或改都用它，配置不存在则建、存在则改，无需区分。需至少一个配置字段。 -- `enable` 是**纯启用**：只开启机器人能力，不带配置字段（只传 `--unified-app-id`）。 -- `config` 成功后必须回读 `robot get`：如果返回 `status=2`，不要再误判为"待生效"；只有 `status=1` 或需要重新上架时才调用 `enable`。 - -```bash -dws dev app robot config --unified-app-id --name 小助手 --brief 审批助手 \ - --desc "处理审批相关问答" --outgoing-url https://example.com/msg \ - --event-callback-url https://example.com/event --mode 2 --skills qa,approval --dry-run --format json - -dws dev app robot enable --unified-app-id --dry-run --format json -``` - -> 旧的独立 `update` 命令已删除（并入 `config`）。 - -参数查 `dws schema dev.app.robot.config`；至少提供一个配置字段，否则 CLI 报错。国际化字段（`--i18n-name` 等）传 JSON，如 `'{"en_US":"Bot"}'`。 - -### 停用 - -```bash -dws dev app robot disable --unified-app-id --dry-run --format json -dws dev app robot disable --unified-app-id --yes --format json -``` +`config` 是 upsert：建或改都用它，不存在则建、存在则改，至少给一个配置字段。国际化字段（`--i18n-name` 等）传 JSON，如 `'{"en_US":"Bot"}'`。`enable` 是纯启用：只开启能力，不带配置字段（只传 `--unified-app-id`）。旧的独立 `update` 已并入 `config`。`config` 成功后回读 `robot get`：返回 `status=2` 就别再误判"待生效"，只有 `status=1` 或要重新上架才调 `enable`。 ## 错误处理 | 情况 | 处理 | |------|------| | `robot info is not exist` | 应用未配置机器人，先用 `robot config` 创建 | -| 应用名重复 | `app-name` 企业内需唯一，换个名字 | +| 应用名重复 | `app-name` 企业内需唯一，换名 | | `ServiceResult.success=false` | 透传 `errorCode/errorMsg` | -| 创建任务 `EXPIRED` | 任务过期，重新 `submit`（可带原 taskId 重试） | +| 创建任务 `EXPIRED` | 任务过期，重新 `submit`（可带原 taskId） | -> 把机器人接到本地 agent 调试/值守（渠道、AI 卡片、会话记忆、依赖预检）见 [connect.md](connect.md)。 +> 把机器人接到本地 agent 调试/值守见 [connect.md](connect.md)。 diff --git a/skills/multi/dingtalk-dev/references/security.md b/skills/multi/dingtalk-dev/references/security.md index 2335b249..a376a933 100644 --- a/skills/multi/dingtalk-dev/references/security.md +++ b/skills/multi/dingtalk-dev/references/security.md @@ -1,6 +1,6 @@ # 安全配置 -> 概念锚点：安全配置=应用的 IP 白名单 / 登录重定向 / 端内免登 URL；见 SKILL.md 概念地图。 +> 安全配置=应用的 IP 白名单 / 登录重定向 / 端内免登 URL；见 SKILL.md 概念地图。 `dws dev app security config` 配 IP 白名单（`--ip-whitelist`）、登录重定向（`--redirect-urls`）、端内免登（`--sso-urls`）。参数查 `dws schema dev.app.security.config`，至少给一个配置字段。 diff --git a/skills/multi/dingtalk-dev/references/version.md b/skills/multi/dingtalk-dev/references/version.md index fae7b227..648c5eae 100644 --- a/skills/multi/dingtalk-dev/references/version.md +++ b/skills/multi/dingtalk-dev/references/version.md @@ -1,117 +1,64 @@ # 版本发布 -> 概念锚点：版本是配置变更生效的唯一通道——改配置 ≠ 上线，发布到 RELEASE 才生效（见 SKILL.md 生效模型）。 +> 版本是配置变更生效的唯一通道——改配置不等于上线，发布到 RELEASE 才生效（见 SKILL.md 生效模型）。 -管理开放平台企业内部应用的版本：基于当前配置创建版本、查看版本列表/详情、预检审批、发布、查状态。 - -> `corpId` / `userId` 由系统上下文自动注入，CLI 不传。所有版本通过 `--unified-app-id` 定位，单个版本再加 `--version-id`。 +管理应用版本：基于当前配置建版本、查列表/详情、预检审批、发布、查状态。参数查 `dws schema dev.app.version.`。版本用 `--unified-app-id` 定位，单个版本再加 `--version-id`；`corpId`/`userId` 系统注入，CLI 不传。 ## 典型流程 ```text permission add（requiredApproval=true 写入版本变更） → version create 创建版本 - → version check-approval 预检是否需要审批 / 审批人 + → version check-approval 预检是否需审批 / 审批人 → version publish 发布（含高敏权限需 --confirmed-sensitive） → version status 轮询发布/审批状态 ``` -## 创建版本 +新应用如果 `version list` 返回空，先 `version create`，用返回的 `versionId` 继续 check-approval/publish；不要因列表空误判无可发布内容。 -```bash -dws dev app version create --unified-app-id --version 1.0.1 --desc "新增机器人能力" --dry-run --format json -dws dev app version create --unified-app-id --version 1.0.1 --desc "新增机器人能力" --yes --format json -``` +## check-approval 与 publish -参数查 `dws schema dev.app.version.create`。 +`check-approval` 只查审批要求和候选审批人，不发布。`publish` 是真实发布；含高敏权限要加 `--confirmed-sensitive`，灰度选人模式用 `--approver-user-id` 指定审批人。 -## 版本列表 - -```bash -dws dev app version list --unified-app-id --page-size 20 --format json -# 续翻：--cursor <上次出参的 nextCursor> -``` - -游标分页：`--cursor`/`--page-size`，出参带 `nextCursor`（空=到底，续翻原样回传）；出参见 SKILL.md「通用出参约定」。 - -新应用如果 `version list` 返回空，先执行 `version create`，用返回的 `versionId` 继续 `check-approval/publish`；不要因为列表为空误判无可发布内容。 - -## 版本详情 - -```bash -dws dev app version get --unified-app-id --version-id --format json -``` - -返回版本状态、描述、能力列表、权限点、敏感权限、审批要求和脱敏详情。 - -## 预检审批（不发布） - -```bash -dws dev app version check-approval --unified-app-id --version-id --format json -``` - -仅返回审批要求和候选审批人，**不会实际发布**。 - -## 发布 - -```bash -dws dev app version publish --unified-app-id --version-id --dry-run --format json -dws dev app version publish --unified-app-id --version-id --yes --format json - -# 含高敏权限时必须确认 -dws dev app version publish --unified-app-id --version-id --confirmed-sensitive --yes --format json - -# 灰度选人模式指定审批人 -dws dev app version publish --unified-app-id --version-id --approver-user-id --yes --format json -``` - -`publish` 是真实发布（区别于 `check-approval` 的预检不发布）。参数查 `dws schema dev.app.version.publish`；含高敏权限要加 `--confirmed-sensitive`，灰度选人模式用 `--approver-user-id` 指定审批人。 - -> 注意：`--dry-run` 是 CLI 层的"预览不执行"开关；服务端的"审批预检"是 `version check-approval`。二者是两个东西：`check-approval` 是只查审批要求不发布，`--dry-run` 是 CLI 要不要真调上游。发布前建议先 `check-approval`。 +区分两个"预检"：`--dry-run` 是 CLI 层的预览不调上游；`check-approval` 是服务端查审批要求不发布。发布前建议先 `check-approval`。 发布响应 `result`： | result | 含义 | 下一步 | |--------|------|--------| -| `NOT_REQUIRED` | 不需要审批；预检时表示可直接发布，真实发布时表示已直接发布上线 | 真实发布后回读 `version status/get` 验证 `RELEASE` | -| `APPROVAL_REQUIRED` | 需要审批，通常出现在 `check-approval` 或未指定审批人时 | 查看 `approvalMode/approvalCandidates`，让用户选择审批人后再 `publish --approver-user-id` | +| `NOT_REQUIRED` | 不需审批；预检=可直接发布，真实发布=已直接上线 | 回读 `version status/get` 验证 `RELEASE` | +| `APPROVAL_REQUIRED` | 需审批，常见于 `check-approval` 或未指定审批人 | 看 `approvalMode/approvalCandidates`，让用户选审批人后再 `publish --approver-user-id` | | `SUBMITTED` | 已提交审批 | 保存 `processId`，轮询 `version status` | 审批模式 `approvalMode`： | approvalMode | 含义 | 下一步 | |--------------|------|--------| -| `SELECT_APPROVER` | 灰度选人模式，需要在候选审批人中选一个 | 展示候选审批人，不自动选第一个 | -| `ENTERPRISE_SELF_BUILT` | 企业自建审核模式 | 不传 `--approver-user-id`，按企业自建审核流程等待 | +| `SELECT_APPROVER` | 灰度选人，需在候选审批人里选一个 | 展示候选，不自动取第一个 | +| `ENTERPRISE_SELF_BUILT` | 企业自建审核 | 不传 `--approver-user-id`，按企业自建流程等待 | ## 版本状态 -```bash -dws dev app version status --unified-app-id --version-id --format json -``` - -返回版本状态、流程实例 ID、审批状态和审批意见。审批详情可能只在钉钉客户端可见。 - -版本状态字段：`version create/list/get/status` 统一返回 `versionStatus`，对齐版本枚举。 +`version create/list/get/status` 统一返回 `versionStatus`： | versionStatus | 含义 | 下一步 | |---------------|------|--------| -| `INIT` | 版本已创建或有待发布变更，尚未发布 | 可 `check-approval` / `publish` | -| `AUDIT` | 发布审核中 | 不要重复发布；即使没有返回 `processStatus`，也按审核中处理 | -| `RELEASE` | 已发布生效 | 发布完成，可继续验证权限、机器人、网页应用等能力 | -| `GRAY` | 灰度状态 | 按灰度流程处理；不要当全量已发布 | +| `INIT` | 已创建或有待发布变更，未发布 | 可 `check-approval`/`publish` | +| `AUDIT` | 发布审核中 | 不要重复发布；即使没返回 `processStatus` 也按审核中处理 | +| `RELEASE` | 已发布生效 | 完成，可验证权限/机器人/网页等能力 | +| `GRAY` | 灰度 | 按灰度流程，不要当全量已发布 | -审批流程状态字段：`version status` 的 `processStatus` 只在存在审批流程且后端透出流程态时有值。`versionStatus=AUDIT` 但没有 `processStatus/processInstanceId` 时，不要判失败，仍表示审核中。 +`version status` 的 `processStatus` 只在存在审批流程且后端透出时有值。`versionStatus=AUDIT` 但没 `processStatus/processInstanceId` 时不要判失败，仍是审核中。 | processStatus | 含义 | 下一步 | |---------------|------|--------| -| `UNDER_REVIEW` | 审批中 | 等待审批，必要时把 `processInstanceId` 给用户去钉钉客户端查看 | -| `PASS` | 审批通过 | 继续回读版本，确认是否进入 `RELEASE` | -| `FAIL` | 审批拒绝 | 展示 `processComment`，修改后重新创建/发布版本 | -| `WITHDRAW` / `CANCEL` | 审批撤回或取消 | 回到发布前状态，重新 `check-approval` / `publish` | -| `PUBLISH_FAILED` | 审批后发布失败 | 展示错误信息，重新检查版本状态和后端错误 | +| `UNDER_REVIEW` | 审批中 | 等待，必要时把 `processInstanceId` 给用户去钉钉客户端看 | +| `PASS` | 审批通过 | 继续回读，确认是否进 `RELEASE` | +| `FAIL` | 审批拒绝 | 展示 `processComment`，改后重新建/发版本 | +| `WITHDRAW` / `CANCEL` | 撤回或取消 | 回到发布前，重新 `check-approval`/`publish` | +| `PUBLISH_FAILED` | 审批后发布失败 | 展示错误，重查版本状态和后端错误 | -遇到未列出的状态值时，不要猜测语义；原样展示状态，并回读 `version get/status` 或查开放平台文档/后台详情。 +遇到未列出的状态值，不要猜语义；原样展示，回读 `version get/status` 或查文档/后台。 ## 错误处理 diff --git a/skills/multi/dingtalk-dev/references/webapp.md b/skills/multi/dingtalk-dev/references/webapp.md index 198bd9ac..d9bf0eb3 100644 --- a/skills/multi/dingtalk-dev/references/webapp.md +++ b/skills/multi/dingtalk-dev/references/webapp.md @@ -1,6 +1,6 @@ # 网页应用配置 -> 概念锚点：网页应用=应用的能力扩展之一，钉钉内打开的 H5；见 SKILL.md 概念地图。 +> 网页应用=应用的能力扩展之一，钉钉内打开的 H5；见 SKILL.md 概念地图。 `dws dev app webapp get` 查配置，`webapp config` 配移动端/PC 首页和管理后台地址。参数查 `dws schema dev.app.webapp.`，config 至少给一个配置字段。