github/dingtalk-workspace-cli

Fork 0

Files

T

玉澜 5e4b5e4eda docs(devapp): add one-click install guide

2026-06-11 10:26:17 +08:00

9.0 KiB

Raw Blame History

DevApp 一键安装与 Agent 接入指南

面向希望用 Codex、Claude、Cursor 等开发 Agent 管理钉钉开放平台应用的开发者。

这份指南参考 Notion Developer Platform 的引导方式：先给出一条可复制的安装命令，再用最短路径完成验证、登录、Agent 调用和排障。

一键安装

当前 DevApp 能力在 feat/dws-devapp 预览分支上。要安装这个分支里的最新能力，请使用 DevApp 专用安装脚本：

curl -fsSL https://raw.githubusercontent.com/wxianfeng/dingtalk-workspace-cli/feat/dws-devapp/scripts/install-devapp.sh | sh

这个脚本会：

拉取 wxianfeng/dingtalk-workspace-cli 的 feat/dws-devapp 分支。
使用本地源码构建 dws。
安装 dws 到默认目录 ~/.local/bin。
安装 Agent Skill 到本机已检测到的 Agent 目录。

预览分支安装需要本机已有 git、go 和 make。Go 版本要求以仓库 go.mod 为准。

如果 DevApp 能力已经发布到正式 Release，可以改用正式安装命令：

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

Windows PowerShell 正式安装命令：

irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

安装脚本支持这些环境变量：

变量	说明
`DEVAPP_REPO_URL`	覆盖源码仓库地址，默认 `https://github.com/wxianfeng/dingtalk-workspace-cli.git`
`DEVAPP_BRANCH`	覆盖安装分支，默认 `feat/dws-devapp`
`DEVAPP_SOURCE_DIR`	使用已有源码目录安装，跳过 clone
`DEVAPP_KEEP_SOURCE=1`	保留临时源码目录，便于调试
`DWS_INSTALL_DIR`	传给底层 `scripts/install.sh`，覆盖 `dws` 安装目录
`DWS_SKILL_MODE`	传给底层 `scripts/install.sh`，选择 `mono` 或 `multi`

安装后验证

先确认 dws 可执行：

dws version

确认 DevApp 命令存在：

dws devapp --help --format json

如果能看到 list、get、create、permission、robot、security、version 等能力，说明 DevApp 已安装成功。

确认登录状态：

dws auth status

如果尚未登录：

dws auth login

登录完成后读取应用列表：

dws devapp list --format json

DevApp 是什么

DevApp 是开放平台应用管理能力的 CLI 和 Agent Skill 入口。安装后，开发者和 Agent 可以用统一命令管理企业内部应用，而不需要反复进入开发者后台页面。

它让 Agent 可以完成这些工作：

查询、创建、更新、启用、停用、删除开放平台应用。
查询应用凭证，读取 clientId / appKey，敏感凭证走专用命令。
配置网页应用首页和管理后台地址。
查询、申请、移除权限点。
管理应用成员。
配置安全项，包括 IP 白名单、登录重定向 URL、端内免登地址。
创建、查询、更新、启用、停用机器人。
创建版本、发起发布、查询审批和发布状态。

给 Agent 使用

安装完成后，可以直接让 Agent 操作 DevApp。

示例：

帮我查一下最近创建的开放平台应用。

帮我给 agentId=<agentId> 的应用配置机器人，先 dry-run 给我确认。

帮我查询这个应用缺哪些权限点，并申请 Contact.User.mobile。

帮我发布这个应用版本，先检查发布前置条件。

Agent 写操作必须遵循：

先查询定位应用。
先 dry-run 预览。
明确展示将要修改的应用、字段和值。
用户确认后加 --yes 执行。
执行后回读验证。

第一个写操作

推荐用机器人配置作为 smoke test。先 dry-run：

dws devapp robot config \
  --unified-app-id <unifiedAppId> \
  --name "告警机器人" \
  --brief "告警通知" \
  --description "处理告警通知和事件回调" \
  --dry-run \
  --format json

确认预览无误后执行：

dws devapp robot config \
  --unified-app-id <unifiedAppId> \
  --name "告警机器人" \
  --brief "告警通知" \
  --description "处理告警通知和事件回调" \
  --yes \
  --format json

回读验证：

dws devapp robot get --unified-app-id <unifiedAppId> --format json

常用命令

应用管理

dws devapp list --format json
dws devapp get --agent-id <agentId> --format json
dws devapp create --app-name "考勤应用" --dry-run --format json
dws devapp update --agent-id <agentId> --app-name "新应用名" --dry-run --format json
dws devapp inactive --agent-id <agentId> --dry-run --format json
dws devapp active --agent-id <agentId> --dry-run --format json
dws devapp delete --agent-id <agentId> --dry-run --format json

凭证查询

dws devapp credentials get --agent-id <agentId> --format json

凭证输出可能包含敏感字段，不要把完整结果写入文档、日志或长期记忆。

权限点管理

dws devapp permission list --agent-id <agentId> --format json
dws devapp permission add --agent-id <agentId> --scope-values Contact.User.mobile --dry-run --format json
dws devapp permission remove --agent-id <agentId> --scope-value Contact.User.mobile --dry-run --format json

权限申请和移除只使用 scopeValue，不要传 API 名或权限分组名。

机器人配置

dws devapp robot get --unified-app-id <unifiedAppId> --format json
dws devapp robot config --unified-app-id <unifiedAppId> --name "机器人名称" --dry-run --format json
dws devapp robot update --unified-app-id <unifiedAppId> --brief "新的简介" --dry-run --format json
dws devapp robot enable --unified-app-id <unifiedAppId> --name "机器人名称" --dry-run --format json
dws devapp robot offline --unified-app-id <unifiedAppId> --dry-run --format json

成员与安全

dws devapp member list --agent-id <agentId> --format json
dws devapp member add --agent-id <agentId> --user-ids <userId> --dry-run --format json
dws devapp member remove --agent-id <agentId> --user-ids <userId> --dry-run --format json
dws devapp security config --unified-app-id <unifiedAppId> --redirect-urls <url> --dry-run --format json
dws devapp security config --unified-app-id <unifiedAppId> --ip-white-list <ip> --dry-run --format json

版本发布

dws devapp version list --unified-app-id <unifiedAppId> --format json
dws devapp version create --unified-app-id <unifiedAppId> --dry-run --format json
dws devapp version publish --unified-app-id <unifiedAppId> --version-id <versionId> --dry-run --format json
dws devapp version status --unified-app-id <unifiedAppId> --version-id <versionId> --format json

安全边界

DevApp 的目标不是绕过开发者后台权限，而是让 CLI、MCP 和 Web 后台保持一致。

默认安全策略：

写操作先 dry-run。
删除、停用、发布必须由用户确认。
Agent 不接收用户手动传入的 access token、cookie、clientSecret、appSecret。
应用定位优先使用 agentId、unifiedAppId、appKey。
对权限点申请、成员变更、安全配置、版本发布记录操作结果，便于审计和回滚。

排障

`dws devapp` 不存在

先确认安装的是预览分支源码，而不是正式 Release：

dws version
dws devapp --help --format json

如果正式 Release 尚未包含 DevApp，请重新执行本文的一键源码安装命令。

`dws devapp list` 失败

优先检查登录态：

dws auth status
dws auth login

然后确认当前账号能访问目标企业，并且当前用户在目标企业内。

页面能操作，但 CLI 或 MCP 提示无权限

通常说明 CLI/MCP 后端鉴权和 Web 后台权限没有对齐。

先确认当前用户是否满足以下任一条件：

应用 owner。
应用管理员。
应用开发者。
企业管理员或具备开放平台应用管理权限的角色。

机器人配置失败

先查当前机器人状态：

dws devapp robot get --unified-app-id <unifiedAppId> --format json

如果机器人不存在，使用 robot config 创建或配置。如果机器人已存在，用 robot update 修改配置，或用 robot enable 重新启用。

页面文案建议

用于产品页顶部：

Install DevApp in one command.

Let your coding agents manage DingTalk Open Platform apps from the terminal:
create apps, configure robots, apply permissions, manage security settings,
and publish versions with dry-run safety built in.

中文版本：

一行命令接入 DevApp。

让 Codex、Claude、Cursor 等开发 Agent 直接管理钉钉开放平台应用：
创建应用、配置机器人、申请权限、管理安全配置、发布版本。
所有写操作先预览，再确认执行。

参考

Notion Developer Platform: https://www.notion.com/product/dev
Notion CLI Help: https://www.notion.com/help/use-notion-from-your-terminal-with-notion-cli
Notion Developer Platform Blog: https://www.notion.com/blog/introducing-developer-platform

9.0 KiB Raw Blame History Unescape Escape