github/dingtalk-workspace-cli
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(dev): dingtalk-dev references 二次精简

Browse Source 
- permission/robot/version 删 bash 命令示例堆叠(schema/--help 已覆盖),
  保留状态机/枚举语义/链路/gotcha
- 去掉所有 reference 的"概念锚点"自造词标签,保留指向概念地图的引语
- SKILL.md 生效模型去"(最重要)";connect 去加粗

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
qinzeandClaude Opus 4.8 committed 2026-06-18 09:09:04 +08:00
1 parent 70d66daa5f
commit cc8a726b0a
11 files changed
+68 -204
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

skills/multi/dingtalk-dev/SKILL.md
+1 -1
View File
@@ -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 ...）
skills/multi/dingtalk-dev/references/app.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 应用基础操作
> 概念锚点：操作的是「应用」容器本体（见 SKILL.md 概念地图）；启停/删除改的是应用 appStatus，不是版本 versionStatus。
> 操作的是「应用」容器本体（见 SKILL.md 概念地图）；启停/删除改的是应用 appStatus，不是版本 versionStatus。
应用列表查询、详情、创建、修改、生命周期启停和删除。参数查 `dws schema dev.app.<method>`（list / get / create / update / delete / disable / enable）。
skills/multi/dingtalk-dev/references/connect.md
+1 -1
View File
@@ -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。
## 起连接
skills/multi/dingtalk-dev/references/credentials.md
+1 -1
View File
@@ -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 <id>` 读取应用凭证。参数查 `dws schema dev.app.credentials.get`。
skills/multi/dingtalk-dev/references/event.md
+1 -1
View File
@@ -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.<method>`。
skills/multi/dingtalk-dev/references/member.md
+1 -1
View File
@@ -1,5 +1,5 @@
# 成员管理
> 概念锚点：成员=谁能改这个应用（DEVELOPER 等角色）；见 SKILL.md 概念地图。
> 成员=谁能改这个应用（DEVELOPER 等角色）；见 SKILL.md 概念地图。
`dws dev app member list/add/remove` 管理应用成员。参数查 `dws schema dev.app.member.<method>`（add/remove 需 `--member-user-ids` 列表 + `--member-type`，如 DEVELOPER）。
skills/multi/dingtalk-dev/references/permission.md
+16 -55
View File
@@ -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.<method>`。
## 权限列表
```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=<token>，续翻：
dws dev app permission list --unified-app-id ID --cursor <token> --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 原因。
skills/multi/dingtalk-dev/references/robot.md
+21 -65
View File
@@ -1,92 +1,48 @@
# 机器人能力
> 概念锚点：机器人是应用的能力扩展之一；建号/配置在此，接到本地 agent 调试用 `dws dev connect`（见 connect.md）。
> 机器人是应用的能力扩展之一；建号/配置在此，接到本地 agent 调试用 `dws dev connect`（见 connect.md）。
为开放平台企业内部应用创建和配置机器人。分两类场景：
为开放平台企业内部应用创建和配置机器人。参数查 `dws schema dev.app.robot.<method>`。分两类场景：
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 <taskId>` 轮询。`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 <taskId> --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 <unifiedAppId> --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 <unifiedAppId> --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 <unifiedAppId> --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 <unifiedAppId> --dry-run --format json
dws dev app robot disable --unified-app-id <unifiedAppId> --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)。
skills/multi/dingtalk-dev/references/security.md
+1 -1
View File
@@ -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`，至少给一个配置字段。
skills/multi/dingtalk-dev/references/version.md
+23 -76
View File
@@ -1,117 +1,64 @@
# 版本发布
> 概念锚点：版本是配置变更生效的唯一通道——改配置 ≠ 上线，发布到 RELEASE 才生效（见 SKILL.md 生效模型）。
> 版本是配置变更生效的唯一通道——改配置不等于上线，发布到 RELEASE 才生效（见 SKILL.md 生效模型）。
管理开放平台企业内部应用的版本：基于当前配置创建版本、查看版本列表/详情、预检审批、发布、查状态。
> `corpId` / `userId` 由系统上下文自动注入，CLI 不传。所有版本通过 `--unified-app-id` 定位，单个版本再加 `--version-id`。
管理应用版本：基于当前配置建版本、查列表/详情、预检审批、发布、查状态。参数查 `dws schema dev.app.version.<method>`。版本用 `--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 <unifiedAppId> --version 1.0.1 --desc "新增机器人能力" --dry-run --format json
dws dev app version create --unified-app-id <unifiedAppId> --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 <unifiedAppId> --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 <unifiedAppId> --version-id <versionId> --format json
```
返回版本状态、描述、能力列表、权限点、敏感权限、审批要求和脱敏详情。
## 预检审批（不发布）
```bash
dws dev app version check-approval --unified-app-id <unifiedAppId> --version-id <versionId> --format json
```
仅返回审批要求和候选审批人，**不会实际发布**。
## 发布
```bash
dws dev app version publish --unified-app-id <unifiedAppId> --version-id <versionId> --dry-run --format json
dws dev app version publish --unified-app-id <unifiedAppId> --version-id <versionId> --yes --format json
# 含高敏权限时必须确认
dws dev app version publish --unified-app-id <unifiedAppId> --version-id <versionId> --confirmed-sensitive --yes --format json
# 灰度选人模式指定审批人
dws dev app version publish --unified-app-id <unifiedAppId> --version-id <versionId> --approver-user-id <userId> --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 <unifiedAppId> --version-id <versionId> --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` 或查文档/后台。
## 错误处理
skills/multi/dingtalk-dev/references/webapp.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 网页应用配置
> 概念锚点：网页应用=应用的能力扩展之一，钉钉内打开的 H5；见 SKILL.md 概念地图。
> 网页应用=应用的能力扩展之一，钉钉内打开的 H5；见 SKILL.md 概念地图。
`dws dev app webapp get` 查配置，`webapp config` 配移动端/PC 首页和管理后台地址。参数查 `dws schema dev.app.webapp.<get|config>`，config 至少给一个配置字段。