diff --git a/docs/devapp-agent-install-guide.md b/docs/devapp-agent-install-guide.md index 80d940bb..bac9f19a 100644 --- a/docs/devapp-agent-install-guide.md +++ b/docs/devapp-agent-install-guide.md @@ -104,7 +104,7 @@ DevApp 是开放平台应用管理能力的 CLI 和 Agent Skill 入口。安装 ``` ```text -帮我给 agentId= 的应用配置机器人，先 dry-run 给我确认。 +帮我给 unifiedAppId= 的应用配置机器人，先 dry-run 给我确认。 ``` ```text @@ -192,7 +192,6 @@ dws devapp permission remove --agent-id --scope-value Contact.User.mob ```bash dws devapp robot get --unified-app-id --format json dws devapp robot config --unified-app-id --name "机器人名称" --dry-run --format json -dws devapp robot update --unified-app-id --brief "新的简介" --dry-run --format json dws devapp robot enable --unified-app-id --name "机器人名称" --dry-run --format json dws devapp robot offline --unified-app-id --dry-run --format json ``` @@ -211,6 +210,7 @@ dws devapp security config --unified-app-id --ip-white-list ```bash dws devapp version list --unified-app-id --format json +dws devapp version list --unified-app-id --cursor --format json dws devapp version create --unified-app-id --dry-run --format json dws devapp version publish --unified-app-id --version-id --dry-run --format json dws devapp version status --unified-app-id --version-id --format json @@ -272,7 +272,7 @@ dws devapp robot get --unified-app-id --format json ``` 如果机器人不存在，使用 `robot config` 创建或配置。 -如果机器人已存在，用 `robot update` 修改配置，或用 `robot enable` 重新启用。 +如果机器人已存在，继续用 `robot config` 修改配置，或用 `robot enable` 重新启用。 ## 页面文案建议 diff --git a/docs/devapp-yulan-command-routing.md b/docs/devapp-yulan-command-routing.md index 3455b635..4f95c984 100644 --- a/docs/devapp-yulan-command-routing.md +++ b/docs/devapp-yulan-command-routing.md @@ -93,12 +93,11 @@ dws devapp robot submit Submit async robot-create task (supports retry by taskId) robot result Query async robot-create task result robot get Get robot config of an existing app - robot config Create robot config on an existing app - robot update Update robot config + robot config Create or update robot config on an existing app robot enable Enable / re-enable robot capability robot offline Offline robot capability version create Save app version - version list List app versions (paged) + version list List app versions (cursor paged) version get Get one version detail version check-approval Precheck publish approval requirements (no publish) version publish Submit publish, possibly creating approval @@ -141,7 +140,7 @@ Do not send confirmation fields such as `confirmCreate`, `confirmUpdate`, `confi | Permission remove | `devapp permission remove` | `remove_open_dev_app_permission` | `OpenInnerAppPermissionFacade.remove` | Implemented | Hardcoded helper | | Events | `devapp event list/subscribe/unsubscribe` | `list_open_dev_app_events`, `subscribe/unsubscribe_open_dev_app_event` | Implemented | Hardcoded helper | | Robot create | `devapp robot create/submit/result` | `create_dingtalk_robot`/`submit_robot_create_task`/`query_robot_create_result` | Implemented | Hardcoded helper | -| Robot config | `devapp robot get/config/update/enable/offline` | `get/create/update_open_dev_app_robot_config`, `enable/offline_open_dev_app_robot` | Implemented | Hardcoded helper | +| Robot config | `devapp robot get/config/enable/offline` | `get/set_open_dev_app_robot_config`, `enable/offline_open_dev_app_robot` | Implemented | Hardcoded helper | | Version | `devapp version create/list/get/check-approval/publish/status` | `create/list_open_dev_app_versions`, `get_open_dev_app_version_detail/status`, `publish_open_dev_app_version` | Implemented | Hardcoded helper | P0 for yulan is app CRUD, permissions, credentials, and web app config. Robot, @@ -1023,13 +1022,13 @@ Implemented version tools (verified against the `op-app` MCP `tools/list`): | CLI | MCP tool | Notes | | --- | --- | --- | | `devapp version create` | `create_open_dev_app_version` | Save a new version from current config (`version`, `description`). | -| `devapp version list` | `list_open_dev_app_versions` | Paged list (`currentPage`, `pageSize`). | +| `devapp version list` | `list_open_dev_app_versions` | Cursor-paged list (`cursor`, `pageSize`; response `items/nextCursor/hasMore`). | | `devapp version get` | `get_open_dev_app_version_detail` | One version detail by `versionId`. | -| `devapp version check-approval` | `publish_open_dev_app_version` (`dryRun=true`) | Precheck approval requirement / approvers; does not publish. | -| `devapp version publish` | `publish_open_dev_app_version` (`dryRun=false`) | Publish; `confirmedSensitive` for high-sensitivity scopes, optional `approverUserId`. | +| `devapp version check-approval` | `publish_open_dev_app_version` (`precheckOnly=true`) | Precheck approval requirement / approvers; does not publish. | +| `devapp version publish` | `publish_open_dev_app_version` (`precheckOnly=false`) | Publish; `confirmedSensitive` for high-sensitivity scopes, optional `approverUserId`. | | `devapp version status` | `get_open_dev_app_version_status` | Poll publish and approval state. | -Note: the MCP `dryRun` field is the server-side approval precheck and maps to +Note: the MCP `precheckOnly` field is the server-side approval precheck and maps to `version check-approval`. It is distinct from the CLI global `--dry-run` (preview without execution). `check-approval` is read-only (no write guard); `publish` uses the standard `--dry-run`/`--yes` write guard. @@ -1042,12 +1041,11 @@ Implemented robot tools: | `devapp robot submit` | `submit_robot_create_task` | Async submit; supports retry via original `taskId`. | | `devapp robot result` | `query_robot_create_result` | Poll async task by `taskId`. | | `devapp robot get` | `get_open_dev_app_robot_config` | Read robot config of an existing app. | -| `devapp robot config` | `create_open_dev_app_robot_config` | Create robot config on an existing app. | -| `devapp robot update` | `update_open_dev_app_robot_config` | Update robot config. | +| `devapp robot config` | `set_open_dev_app_robot_config` | Create or update robot config on an existing app. | | `devapp robot enable` | `enable_open_dev_app_robot` | Enable / re-enable robot capability. | | `devapp robot offline` | `offline_open_dev_app_robot` | Offline robot capability. | -Robot create/submit and config/update/enable/offline are write operations and +Robot create/submit and config/enable/offline are write operations and use the `--dry-run`/`--yes` guard; `get` and `result` are reads. Stitching rule: diff --git a/internal/helpers/devapp.go b/internal/helpers/devapp.go index a4c33f42..27ffeb67 100644 --- a/internal/helpers/devapp.go +++ b/internal/helpers/devapp.go @@ -34,14 +34,13 @@ const ( devAppSecurityConfigTool = "update_app_security_config" // 机器人能力（op-app MCP 工具，硬编码不走服务发现）。 - devAppRobotCreateTool = "create_dingtalk_robot" - devAppRobotSubmitTool = "submit_robot_create_task" - devAppRobotResultTool = "query_robot_create_result" - devAppRobotConfigGetTool = "get_open_dev_app_robot_config" - devAppRobotConfigCreateTool = "create_open_dev_app_robot_config" - devAppRobotConfigUpdateTool = "update_open_dev_app_robot_config" - devAppRobotEnableTool = "enable_open_dev_app_robot" - devAppRobotOfflineTool = "offline_open_dev_app_robot" + devAppRobotCreateTool = "create_dingtalk_robot" + devAppRobotSubmitTool = "submit_robot_create_task" + devAppRobotResultTool = "query_robot_create_result" + devAppRobotConfigGetTool = "get_open_dev_app_robot_config" + devAppRobotConfigSetTool = "set_open_dev_app_robot_config" + devAppRobotEnableTool = "enable_open_dev_app_robot" + devAppRobotOfflineTool = "offline_open_dev_app_robot" // 版本发布能力（op-app MCP 工具，硬编码不走服务发现）。 devAppVersionCreateTool = "create_open_dev_app_version" @@ -172,8 +171,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command { newDevAppRobotSubmitCommand(runner), newDevAppRobotResultCommand(runner), newDevAppRobotConfigGetCommand(runner), - newDevAppRobotConfigCommand(runner, "config", "为现有应用创建机器人配置", devAppRobotConfigCreateTool), - newDevAppRobotConfigCommand(runner, "update", "更新现有应用机器人配置", devAppRobotConfigUpdateTool), + newDevAppRobotConfigCommand(runner, "config", "创建或更新现有应用机器人配置", devAppRobotConfigSetTool), newDevAppRobotConfigCommand(runner, "enable", "启用现有应用机器人能力", devAppRobotEnableTool), newDevAppRobotOfflineCommand(runner), newDevAppRobotConnectCommand(runner), @@ -966,8 +964,8 @@ func newDevAppVersionCreateCommand(runner executor.Runner) *cobra.Command { func newDevAppVersionListCommand(runner executor.Runner) *cobra.Command { cmd := &cobra.Command{ Use: "list", - Short: "分页查询应用版本列表", - Example: " dws devapp version list --unified-app-id UNIFIED_APP_ID --page 1 --page-size 20 --format json", + Short: "按 cursor 查询应用版本列表", + Example: " dws devapp version list --unified-app-id UNIFIED_APP_ID --page-size 20 --format json\n dws devapp version list --unified-app-id UNIFIED_APP_ID --cursor NEXT_CURSOR --page-size 20 --format json", Args: cobra.NoArgs, DisableAutoGenTag: true, RunE: func(cmd *cobra.Command, args []string) error { @@ -977,14 +975,14 @@ func newDevAppVersionListCommand(runner executor.Runner) *cobra.Command { } params := map[string]any{ "unifiedAppId": appID, - "currentPage": devAppIntFlag(cmd, "page"), "pageSize": devAppIntFlag(cmd, "page-size"), } + devAppPutString(params, "cursor", devAppStringFlag(cmd, "cursor")) return runDevAppTool(runner, cmd, devAppVersionListTool, params) }, } addDevAppUnifiedIDFlag(cmd) - cmd.Flags().Int("page", 1, "分页页码，从 1 开始") + cmd.Flags().String("cursor", "", "服务端返回的不透明分页游标；首次查询留空") cmd.Flags().Int("page-size", 20, "分页大小") preferLegacyLeaf(cmd) return cmd @@ -1022,8 +1020,8 @@ func newDevAppVersionCheckApprovalCommand(runner executor.Runner) *cobra.Command if err != nil { return err } - // 复用 publish 工具的服务端预检模式：dryRun=true 只返回审批要求，不发布。 - params["dryRun"] = true + // 复用 publish 工具的服务端预检模式：precheckOnly=true 只返回审批要求，不发布。 + params["precheckOnly"] = true return runDevAppTool(runner, cmd, devAppVersionPublishTool, params) }, } @@ -1047,7 +1045,7 @@ func newDevAppVersionPublishCommand(runner executor.Runner) *cobra.Command { if err != nil { return err } - params["dryRun"] = false + params["precheckOnly"] = false if cmd.Flags().Changed("confirm-sensitive") { value, _ := cmd.Flags().GetBool("confirm-sensitive") params["confirmedSensitive"] = value @@ -1102,12 +1100,10 @@ func devAppVersionLocator(cmd *cobra.Command) (map[string]any, error) { func addDevAppUnifiedIDFlag(cmd *cobra.Command) { cmd.Flags().String("unified-app-id", "", "统一应用 ID (必填)") - cmd.Flags().String("app-id", "", "--unified-app-id 的兼容别名") - _ = cmd.Flags().MarkHidden("app-id") } func requiredDevAppUnifiedID(cmd *cobra.Command) (string, error) { - appID := devAppFlagOrFallback(cmd, "unified-app-id", "app-id") + appID := devAppStringFlag(cmd, "unified-app-id") if appID == "" { return "", apperrors.NewValidation("--unified-app-id is required") } diff --git a/internal/helpers/devapp_test.go b/internal/helpers/devapp_test.go index f027ca4c..7f0567b6 100644 --- a/internal/helpers/devapp_test.go +++ b/internal/helpers/devapp_test.go @@ -119,6 +119,15 @@ func TestDevAppCommandHasAppAliasAndCoreCommands(t *testing.T) { t.Fatalf("missing command %q: %v", name, err) } } + robotCmd, _, err := root.Find([]string{"robot"}) + if err != nil { + t.Fatalf("missing robot command: %v", err) + } + for _, cmd := range robotCmd.Commands() { + if cmd.Name() == "update" { + t.Fatal("robot update command exists, want removed public command") + } + } } func TestDevAppRobotCommandsBuildToolParams(t *testing.T) { @@ -166,7 +175,7 @@ func TestDevAppRobotCommandsBuildToolParams(t *testing.T) { { name: "config create with skills and mode", args: []string{"robot", "config", "--unified-app-id", "u-1", "--name", "小助手", "--brief", "审批助手", "--mode", "2", "--skills", "qa,approval", "--add-scope", "--yes"}, - wantTool: "create_open_dev_app_robot_config", + wantTool: "set_open_dev_app_robot_config", wantParams: map[string]any{ "unifiedAppId": "u-1", "name": "小助手", @@ -228,11 +237,11 @@ func TestDevAppVersionCommandsBuildToolParams(t *testing.T) { }, { name: "list", - args: []string{"version", "list", "--unified-app-id", "u-1", "--page", "2", "--page-size", "5"}, + args: []string{"version", "list", "--unified-app-id", "u-1", "--cursor", "cursor-1", "--page-size", "5"}, wantTool: "list_open_dev_app_versions", wantParams: map[string]any{ "unifiedAppId": "u-1", - "currentPage": 2, + "cursor": "cursor-1", "pageSize": 5, }, }, @@ -243,19 +252,19 @@ func TestDevAppVersionCommandsBuildToolParams(t *testing.T) { wantParams: map[string]any{"unifiedAppId": "u-1", "versionId": "v-1"}, }, { - name: "check-approval forces dryRun", + name: "check-approval prechecks only", args: []string{"version", "check-approval", "--unified-app-id", "u-1", "--version-id", "v-1"}, wantTool: "publish_open_dev_app_version", - wantParams: map[string]any{"unifiedAppId": "u-1", "versionId": "v-1", "dryRun": true}, + wantParams: map[string]any{"unifiedAppId": "u-1", "versionId": "v-1", "precheckOnly": true}, }, { - name: "publish sets dryRun false and sensitive", + name: "publish disables precheck and sets sensitive", args: []string{"version", "publish", "--unified-app-id", "u-1", "--version-id", "v-1", "--confirm-sensitive", "--approver", "user-1", "--yes"}, wantTool: "publish_open_dev_app_version", wantParams: map[string]any{ "unifiedAppId": "u-1", "versionId": "v-1", - "dryRun": false, + "precheckOnly": false, "confirmedSensitive": true, "approverUserId": "user-1", }, @@ -359,6 +368,79 @@ func TestDevAppEventSubscribeRequiresEventCode(t *testing.T) { } } +func TestDevAppScopedCommandsRejectLegacyLocators(t *testing.T) { + cases := []struct { + name string + args []string + }{ + {name: "version create", args: []string{"devapp", "version", "create", "--app-id", "u-1", "--version", "1.0.1", "--yes"}}, + {name: "version list", args: []string{"devapp", "version", "list", "--app-id", "u-1"}}, + {name: "version get", args: []string{"devapp", "version", "get", "--app-id", "u-1", "--version-id", "v-1"}}, + {name: "version check approval", args: []string{"devapp", "version", "check-approval", "--app-id", "u-1", "--version-id", "v-1"}}, + {name: "version publish", args: []string{"devapp", "version", "publish", "--app-id", "u-1", "--version-id", "v-1", "--yes"}}, + {name: "version status", args: []string{"devapp", "version", "status", "--app-id", "u-1", "--version-id", "v-1"}}, + {name: "robot get", args: []string{"devapp", "robot", "get", "--app-id", "u-1"}}, + {name: "robot config", args: []string{"devapp", "robot", "config", "--app-id", "u-1", "--name", "小助手", "--yes"}}, + {name: "robot enable", args: []string{"devapp", "robot", "enable", "--app-id", "u-1", "--name", "小助手", "--yes"}}, + {name: "robot offline", args: []string{"devapp", "robot", "offline", "--app-id", "u-1", "--yes"}}, + {name: "event list", args: []string{"devapp", "event", "list", "--app-id", "u-1"}}, + {name: "event subscribe", args: []string{"devapp", "event", "subscribe", "--app-id", "u-1", "--event-code", "user_add_org", "--yes"}}, + {name: "event unsubscribe", args: []string{"devapp", "event", "unsubscribe", "--app-id", "u-1", "--event-code", "user_add_org", "--yes"}}, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + runner := &captureRunner{} + root := newDevAppTestRoot(runner) + var out bytes.Buffer + root.SetOut(&out) + root.SetErr(&out) + root.SetArgs(tc.args) + + err := root.Execute() + if err == nil { + t.Fatal("Execute() error = nil, want unknown --app-id flag") + } + if !strings.Contains(err.Error(), "unknown flag: --app-id") { + t.Fatalf("error = %q, want unknown --app-id flag", err.Error()) + } + if runner.last.Tool != "" { + t.Fatalf("tool = %q, want no invocation", runner.last.Tool) + } + }) + } +} + +func TestDevAppScopedCommandsRejectAgentAndCustomKeyLocators(t *testing.T) { + for _, flag := range []string{"--agent-id", "--custom-key"} { + for _, args := range [][]string{ + {"devapp", "version", "list", flag, "u-1"}, + {"devapp", "robot", "get", flag, "u-1"}, + {"devapp", "event", "list", flag, "u-1"}, + } { + t.Run(strings.Join(args[1:3], " ")+" "+flag, func(t *testing.T) { + runner := &captureRunner{} + root := newDevAppTestRoot(runner) + var out bytes.Buffer + root.SetOut(&out) + root.SetErr(&out) + root.SetArgs(args) + + err := root.Execute() + if err == nil { + t.Fatalf("Execute() error = nil, want unknown %s flag", flag) + } + if !strings.Contains(err.Error(), "unknown flag: "+flag) { + t.Fatalf("error = %q, want unknown %s flag", err.Error(), flag) + } + if runner.last.Tool != "" { + t.Fatalf("tool = %q, want no invocation", runner.last.Tool) + } + }) + } + } +} + func TestDevAppRobotAndVersionWritesRequireGuard(t *testing.T) { cases := []struct { name string diff --git a/skills/dingtalk-devapp/references/event.md b/skills/dingtalk-devapp/references/event.md index 166dbc61..cecdb196 100644 --- a/skills/dingtalk-devapp/references/event.md +++ b/skills/dingtalk-devapp/references/event.md @@ -42,7 +42,7 @@ MCP tool: `unsubscribe_open_dev_app_event`（入参 `unifiedAppId` + `eventCode` | CLI | MCP | 必填 | 说明 | |-----|-----|------|------| -| `--unified-app-id` | `unifiedAppId` | 是 | 统一应用 ID（兼容隐藏别名 `--app-id`） | +| `--unified-app-id` | `unifiedAppId` | 是 | 统一应用 ID | | `--event-code` | `eventCode` | subscribe/unsubscribe 必填 | 事件码，取自 `event list` | ## 灰度应用需发布版本生效（重要） diff --git a/skills/dingtalk-devapp/references/robot.md b/skills/dingtalk-devapp/references/robot.md index 11b51755..834d9d98 100644 --- a/skills/dingtalk-devapp/references/robot.md +++ b/skills/dingtalk-devapp/references/robot.md @@ -3,7 +3,7 @@ 为开放平台企业内部应用创建和配置机器人。分两类场景： 1. **新建智能体机器人**：一次性创建一个新的 Agent 应用 + 承载机器人（`create` / `submit` / `result`）。 -2. **现有应用配置机器人**：在已存在的应用上开启/配置/停用机器人（`get` / `config` / `update` / `enable` / `offline`），通过 `--unified-app-id` 定位。 +2. **现有应用配置机器人**：在已存在的应用上开启/配置/停用机器人（`get` / `config` / `enable` / `offline`），通过 `--unified-app-id` 定位。 > `corpId` / `userId` 由 MCP 系统上下文注入，CLI 不传。所有写操作先 `--dry-run`，确认后再 `--yes`。 @@ -74,9 +74,9 @@ MCP tool: `get_open_dev_app_robot_config`。返回机器人基础信息、回调 - ONLINE 只代表开放平台机器人能力已开启。若要让机器人自动处理消息，还需要配置 `--outgoing-url` / `--event-url`，或用 `robot connect` 接到本地 Agent。 - 未配置机器人时不会返回 `status`，而是业务错误 `robot info is not exist`；这时走 `robot config`，不是 `enable`。 -### 创建 / 更新 / 启用配置 +### 创建或更新 / 启用配置 -三者字段一致，区别在语义：`config`=首次创建、`update`=修改、`enable`=启用/重新启用。 +`config` 是 upsert：未配置机器人时创建，已存在时更新；`enable` 用于启用/重新启用。 首次 `config` 成功后必须回读 `robot get`：如果返回 `status=2`，不要再误判为“待生效”；只有 `status=1` 或需要重新上架时才调用 `enable`。 @@ -85,12 +85,10 @@ dws devapp robot config --unified-app-id --name 小助手 --brief --description "处理审批相关问答" --outgoing-url https://example.com/msg \ --event-url https://example.com/event --mode 2 --skills qa,approval --dry-run --format json -dws devapp robot update --unified-app-id --brief "新的简介" --dry-run --format json - dws devapp robot enable --unified-app-id --name 小助手 --dry-run --format json ``` -MCP tools: `create_open_dev_app_robot_config` / `update_open_dev_app_robot_config` / `enable_open_dev_app_robot` +MCP tools: `set_open_dev_app_robot_config` / `enable_open_dev_app_robot` | CLI | MCP | 说明 | |-----|-----|------| diff --git a/skills/dingtalk-devapp/references/version.md b/skills/dingtalk-devapp/references/version.md index 0998ec67..bea2ae75 100644 --- a/skills/dingtalk-devapp/references/version.md +++ b/skills/dingtalk-devapp/references/version.md @@ -31,10 +31,11 @@ MCP tool: `create_open_dev_app_version` ## 版本列表 ```bash -dws devapp version list --unified-app-id --page 1 --page-size 20 --format json +dws devapp version list --unified-app-id --page-size 20 --format json +dws devapp version list --unified-app-id --cursor --page-size 20 --format json ``` -MCP tool: `list_open_dev_app_versions`（`--page`→`currentPage`，`--page-size`→`pageSize`） +MCP tool: `list_open_dev_app_versions`（`--cursor`→`cursor`，`--page-size`→`pageSize`）。响应使用 `items` / `nextCursor` / `hasMore`。 新应用如果 `version list` 返回空，先执行 `version create`，用返回的 `versionId` 继续 `check-approval/publish`；不要因为列表为空误判无可发布内容。 @@ -52,7 +53,7 @@ MCP tool: `get_open_dev_app_version_detail`。返回版本状态、描述、能 dws devapp version check-approval --unified-app-id --version-id --format json ``` -MCP tool: `publish_open_dev_app_version`，CLI 强制 `dryRun=true`，仅返回审批要求和候选审批人，**不会实际发布**。 +MCP tool: `publish_open_dev_app_version`，CLI 强制 `precheckOnly=true`，仅返回审批要求和候选审批人，**不会实际发布**。 ## 发布 @@ -67,14 +68,14 @@ dws devapp version publish --unified-app-id --version-id --version-id --approver --yes --format json ``` -MCP tool: `publish_open_dev_app_version`，CLI 设 `dryRun=false`。 +MCP tool: `publish_open_dev_app_version`，CLI 设 `precheckOnly=false`。 | CLI | MCP | 说明 | |-----|-----|------| | `--confirm-sensitive` | `confirmedSensitive` | 版本含高敏权限时必须确认 | | `--approver` | `approverUserId` | 灰度选人模式指定审批人 userId | -> 注意：`--dry-run` 是 CLI 层的"预览不执行"开关；服务端的"审批预检"是 `version check-approval`（对应 `dryRun=true`）。二者不同，发布前建议先 `check-approval`。 +> 注意：`--dry-run` 是 CLI 层的"预览不执行"开关；服务端的"审批预检"是 `version check-approval`（对应 `precheckOnly=true`）。二者不同，发布前建议先 `check-approval`。 发布响应 `result`： diff --git a/skills/dingtalk-devapp/references/workflows.md b/skills/dingtalk-devapp/references/workflows.md index 9347fbee..bed457c6 100644 --- a/skills/dingtalk-devapp/references/workflows.md +++ b/skills/dingtalk-devapp/references/workflows.md @@ -148,7 +148,7 @@ 2. 审批预检：获取审批要求和候选审批人列表 dws devapp version check-approval --unified-app-id --version-id --format json - → 服务端 dryRun 预检，不实际发布 + → 服务端 precheckOnly 预检，不实际发布 → 返回中包含是否需要审批、候选审批人（userId + 姓名） 3. 把候选审批人列表展示给用户，让用户选择 diff --git a/skills/mono/references/products/devapp.md b/skills/mono/references/products/devapp.md index cfde383f..570549c2 100644 --- a/skills/mono/references/products/devapp.md +++ b/skills/mono/references/products/devapp.md @@ -220,12 +220,11 @@ MCP tools: `create_dingtalk_robot` / `submit_robot_create_task` / `query_robot_c ```bash dws devapp robot get --unified-app-id ID --format json dws devapp robot config --unified-app-id ID --name 小助手 --brief 审批助手 --outgoing-url URL --mode 2 --skills qa,approval --dry-run --format json -dws devapp robot update --unified-app-id ID --brief "新简介" --dry-run --format json dws devapp robot enable --unified-app-id ID --name 小助手 --dry-run --format json dws devapp robot offline --unified-app-id ID --dry-run --format json ``` -MCP tools: `get_open_dev_app_robot_config` / `create_open_dev_app_robot_config` / `update_open_dev_app_robot_config` / `enable_open_dev_app_robot` / `offline_open_dev_app_robot`。 +MCP tools: `get_open_dev_app_robot_config` / `set_open_dev_app_robot_config` / `enable_open_dev_app_robot` / `offline_open_dev_app_robot`。 配置字段：`--name/--brief/--description/--icon/--outgoing-url(outgoingUrl)/--event-url(chatBotEventUrl)/--mode/--skills(skillList)/--add-scope/--disable-ssl-verify/--i18n-name/--i18n-brief/--i18n-description`。应用未配机器人时 `get` 返回 `robot info is not exist`。 @@ -278,7 +277,8 @@ dws devapp robot connect --robot-client-id CLIENT_ID --robot-client-secret CLIEN ```bash dws devapp version create --unified-app-id ID --version 1.0.1 --desc "新增机器人能力" --dry-run --format json -dws devapp version list --unified-app-id ID --page 1 --page-size 20 --format json +dws devapp version list --unified-app-id ID --page-size 20 --format json +dws devapp version list --unified-app-id ID --cursor NEXT_CURSOR --page-size 20 --format json dws devapp version get --unified-app-id ID --version-id VERSION_ID --format json dws devapp version check-approval --unified-app-id ID --version-id VERSION_ID --format json dws devapp version publish --unified-app-id ID --version-id VERSION_ID --confirm-sensitive --dry-run --format json @@ -287,8 +287,9 @@ dws devapp version status --unified-app-id ID --version-id VERSION_ID --format j MCP tools: `create_open_dev_app_version` / `list_open_dev_app_versions` / `get_open_dev_app_version_detail` / `publish_open_dev_app_version` / `get_open_dev_app_version_status`。 -- `check-approval` = `publish_open_dev_app_version` 的 `dryRun=true` 预检模式，不实际发布。 -- `publish` 设 `dryRun=false`；含高敏权限需 `--confirm-sensitive`，灰度选人模式用 `--approver USER_ID`。 +- `version list` 使用 `cursor/pageSize`；首次不传 cursor，后续传响应里的 `nextCursor`。 +- `check-approval` = `publish_open_dev_app_version` 的 `precheckOnly=true` 预检模式，不实际发布。 +- `publish` 设 `precheckOnly=false`；含高敏权限需 `--confirm-sensitive`，灰度选人模式用 `--approver USER_ID`。 - 流程：`permission add`（requiredApproval 写入版本变更）→ `version create` → `check-approval` → `publish` → `status`。 - 新应用如果 `version list` 返回空，先执行 `version create`，用返回的 `versionId` 继续 `check-approval/publish`；不要因为列表为空误判无可发布内容。 - **审批人选择**：`check-approval` 返回候选审批人列表（userId+姓名）→ **展示给用户让其选择（不要自行挑选或默认第一个）** → `publish --approver <选中的userId>` 自动向该审批人发起审批 → `version status` 跟踪。机器人等能力需审批通过、应用发布后才可被搜索/加群/路由消息。 diff --git a/skills/multi/dingtalk-devapp/references/event.md b/skills/multi/dingtalk-devapp/references/event.md index 166dbc61..cecdb196 100644 --- a/skills/multi/dingtalk-devapp/references/event.md +++ b/skills/multi/dingtalk-devapp/references/event.md @@ -42,7 +42,7 @@ MCP tool: `unsubscribe_open_dev_app_event`（入参 `unifiedAppId` + `eventCode` | CLI | MCP | 必填 | 说明 | |-----|-----|------|------| -| `--unified-app-id` | `unifiedAppId` | 是 | 统一应用 ID（兼容隐藏别名 `--app-id`） | +| `--unified-app-id` | `unifiedAppId` | 是 | 统一应用 ID | | `--event-code` | `eventCode` | subscribe/unsubscribe 必填 | 事件码，取自 `event list` | ## 灰度应用需发布版本生效（重要） diff --git a/skills/multi/dingtalk-devapp/references/robot.md b/skills/multi/dingtalk-devapp/references/robot.md index 11b51755..834d9d98 100644 --- a/skills/multi/dingtalk-devapp/references/robot.md +++ b/skills/multi/dingtalk-devapp/references/robot.md @@ -3,7 +3,7 @@ 为开放平台企业内部应用创建和配置机器人。分两类场景： 1. **新建智能体机器人**：一次性创建一个新的 Agent 应用 + 承载机器人（`create` / `submit` / `result`）。 -2. **现有应用配置机器人**：在已存在的应用上开启/配置/停用机器人（`get` / `config` / `update` / `enable` / `offline`），通过 `--unified-app-id` 定位。 +2. **现有应用配置机器人**：在已存在的应用上开启/配置/停用机器人（`get` / `config` / `enable` / `offline`），通过 `--unified-app-id` 定位。 > `corpId` / `userId` 由 MCP 系统上下文注入，CLI 不传。所有写操作先 `--dry-run`，确认后再 `--yes`。 @@ -74,9 +74,9 @@ MCP tool: `get_open_dev_app_robot_config`。返回机器人基础信息、回调 - ONLINE 只代表开放平台机器人能力已开启。若要让机器人自动处理消息，还需要配置 `--outgoing-url` / `--event-url`，或用 `robot connect` 接到本地 Agent。 - 未配置机器人时不会返回 `status`，而是业务错误 `robot info is not exist`；这时走 `robot config`，不是 `enable`。 -### 创建 / 更新 / 启用配置 +### 创建或更新 / 启用配置 -三者字段一致，区别在语义：`config`=首次创建、`update`=修改、`enable`=启用/重新启用。 +`config` 是 upsert：未配置机器人时创建，已存在时更新；`enable` 用于启用/重新启用。 首次 `config` 成功后必须回读 `robot get`：如果返回 `status=2`，不要再误判为“待生效”；只有 `status=1` 或需要重新上架时才调用 `enable`。 @@ -85,12 +85,10 @@ dws devapp robot config --unified-app-id --name 小助手 --brief --description "处理审批相关问答" --outgoing-url https://example.com/msg \ --event-url https://example.com/event --mode 2 --skills qa,approval --dry-run --format json -dws devapp robot update --unified-app-id --brief "新的简介" --dry-run --format json - dws devapp robot enable --unified-app-id --name 小助手 --dry-run --format json ``` -MCP tools: `create_open_dev_app_robot_config` / `update_open_dev_app_robot_config` / `enable_open_dev_app_robot` +MCP tools: `set_open_dev_app_robot_config` / `enable_open_dev_app_robot` | CLI | MCP | 说明 | |-----|-----|------| diff --git a/skills/multi/dingtalk-devapp/references/version.md b/skills/multi/dingtalk-devapp/references/version.md index 0998ec67..bea2ae75 100644 --- a/skills/multi/dingtalk-devapp/references/version.md +++ b/skills/multi/dingtalk-devapp/references/version.md @@ -31,10 +31,11 @@ MCP tool: `create_open_dev_app_version` ## 版本列表 ```bash -dws devapp version list --unified-app-id --page 1 --page-size 20 --format json +dws devapp version list --unified-app-id --page-size 20 --format json +dws devapp version list --unified-app-id --cursor --page-size 20 --format json ``` -MCP tool: `list_open_dev_app_versions`（`--page`→`currentPage`，`--page-size`→`pageSize`） +MCP tool: `list_open_dev_app_versions`（`--cursor`→`cursor`，`--page-size`→`pageSize`）。响应使用 `items` / `nextCursor` / `hasMore`。 新应用如果 `version list` 返回空，先执行 `version create`，用返回的 `versionId` 继续 `check-approval/publish`；不要因为列表为空误判无可发布内容。 @@ -52,7 +53,7 @@ MCP tool: `get_open_dev_app_version_detail`。返回版本状态、描述、能 dws devapp version check-approval --unified-app-id --version-id --format json ``` -MCP tool: `publish_open_dev_app_version`，CLI 强制 `dryRun=true`，仅返回审批要求和候选审批人，**不会实际发布**。 +MCP tool: `publish_open_dev_app_version`，CLI 强制 `precheckOnly=true`，仅返回审批要求和候选审批人，**不会实际发布**。 ## 发布 @@ -67,14 +68,14 @@ dws devapp version publish --unified-app-id --version-id --version-id --approver --yes --format json ``` -MCP tool: `publish_open_dev_app_version`，CLI 设 `dryRun=false`。 +MCP tool: `publish_open_dev_app_version`，CLI 设 `precheckOnly=false`。 | CLI | MCP | 说明 | |-----|-----|------| | `--confirm-sensitive` | `confirmedSensitive` | 版本含高敏权限时必须确认 | | `--approver` | `approverUserId` | 灰度选人模式指定审批人 userId | -> 注意：`--dry-run` 是 CLI 层的"预览不执行"开关；服务端的"审批预检"是 `version check-approval`（对应 `dryRun=true`）。二者不同，发布前建议先 `check-approval`。 +> 注意：`--dry-run` 是 CLI 层的"预览不执行"开关；服务端的"审批预检"是 `version check-approval`（对应 `precheckOnly=true`）。二者不同，发布前建议先 `check-approval`。 发布响应 `result`： diff --git a/skills/multi/dingtalk-devapp/references/workflows.md b/skills/multi/dingtalk-devapp/references/workflows.md index 9347fbee..bed457c6 100644 --- a/skills/multi/dingtalk-devapp/references/workflows.md +++ b/skills/multi/dingtalk-devapp/references/workflows.md @@ -148,7 +148,7 @@ 2. 审批预检：获取审批要求和候选审批人列表 dws devapp version check-approval --unified-app-id --version-id --format json - → 服务端 dryRun 预检，不实际发布 + → 服务端 precheckOnly 预检，不实际发布 → 返回中包含是否需要审批、候选审批人（userId + 姓名） 3. 把候选审批人列表展示给用户，让用户选择