diff --git a/README.md b/README.md index 06d0371d..135d4ce6 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@

> [!IMPORTANT] -> **Co-creation Phase**: This project accesses DingTalk enterprise data and requires enterprise admin authorization. Please join the DingTalk DWS co-creation group to complete whitelist configuration. See [Getting Started](#getting-started) below. +> **Co-creation Phase**: This project accesses DingTalk enterprise data and requires enterprise admin authorization. Join the DingTalk DWS co-creation group for support and updates. See [Getting Started](#getting-started) below. > > DingTalk Group QR Code @@ -87,78 +87,57 @@ cp dws ~/.local/bin/ # install to PATH ## Getting Started -### Step 1: Create a DingTalk Application - -Go to the [Open Platform Console](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app). Under "Internal Enterprise Apps - DingTalk Apps", click **Create App**. - -
-View screenshot -

- Create Application -

-
- -### Step 2: Configure Redirect URL - -Go to app settings → **Security Settings**. Add the following redirect URLs and save: - -``` -http://127.0.0.1,https://login.dingtalk.com +```bash +dws auth login ``` -> `http://127.0.0.1` is for local browser login; `https://login.dingtalk.com` is for `--device` device-flow login (Docker containers, remote servers, and other headless environments). We recommend configuring both. +The browser opens automatically — select your organization and authorize. That's it. + +

+ Authorization Successful +

+ +> If your organization hasn't enabled CLI access, you'll be prompted to send an access request to your admin. Once approved, re-run `dws auth login`.
-View screenshot +Organization hasn't enabled CLI access? + +1. After selecting your organization, click "Apply Now" to notify the admin +2. The admin receives a request card and can approve with one click +3. Once approved, re-run `dws auth login` +

- Configure Redirect URL + Apply for Access

+
-### Step 3: Publish the Application - -Click "App Release - Version Management & Release" to publish and go live. -
-View screenshot +Admin: Enable CLI access for your organization + +Go to [Developer Platform](https://open-dev.dingtalk.com) → "CLI Access Management" → Enable. +

- Publish Application + CLI Access Management

+
-### Step 4: Request Whitelist Access +
+Custom App mode (CI/CD, ISV integration) -Join the DingTalk DWS co-creation group and provide your **Client ID** and **admin confirmation** to complete whitelist setup. +For enterprise-managed scenarios, create your own DingTalk app: -### Step 5: Authenticate +1. [Open Platform Console](https://open-dev.dingtalk.com/fe/app#/corp/app) → Create App +2. Security Settings → Add redirect URLs: `http://127.0.0.1,https://login.dingtalk.com` +3. Publish the app +4. Login: ```bash dws auth login --client-id --client-secret ``` -Or via environment variables: - -```bash -export DWS_CLIENT_ID= -export DWS_CLIENT_SECRET= -dws auth login -``` - -
-Credential Configuration Priority - -`client-id` and `client-secret` support multiple configuration methods with the following priority (highest to lowest): - -| Priority | Method | Description | -|----------|--------|-------------| -| 1 | CLI flags / Persisted config | `--client-id` / `--client-secret` command-line arguments; auto-saved after first successful login with `client-secret` stored in system Keychain | -| 2 | Environment variables | `DWS_CLIENT_ID` / `DWS_CLIENT_SECRET` | -| 3 | Default values | Hardcoded defaults (for development only) | - -**Recommended usage**: -- **First login**: Use `--client-id` and `--client-secret` flags; credentials are securely persisted after successful login -- **Subsequent use**: Run `dws` commands directly; token refresh automatically reads saved credentials from Keychain -- **CI/CD environments**: Use environment variables +Credentials are securely persisted after first login (Keychain). Subsequent runs auto-refresh tokens.
@@ -175,13 +154,6 @@ dws todo task list --dry-run # preview without executing dws is designed as an AI-native CLI. Complete [Installation](#installation) and [Getting Started](#getting-started) first, then configure your agent: -```bash -# Configure auth via environment variables (recommended for agents, no interactive login) -export DWS_CLIENT_ID= -export DWS_CLIENT_SECRET= -dws auth login -``` - ### Agent Invocation Patterns ```bash @@ -334,22 +306,22 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \ ## Key Services -| Service | Command | Tools | Subcommands | Description | -|---------|---------|:-----:|-------------|-------------| -| Contact | `contact` | 8 | `user` `dept` | Search users by name/mobile, batch query, departments, current user profile | -| Chat | `chat` | 14 | `message` `group` `bot` `search` | Group CRUD, member management, topic replies, send as user | -| Bot | `chat bot` | 9 | — | Robot creation, group/single messaging, webhook, message recall | +| Service | Command | Commands | Subcommands | Description | +|---------|---------|:--------:|-------------|-------------| +| Contact | `contact` | 6 | `user` `dept` | Search users by name/mobile, batch query, departments, current user profile | +| Chat | `chat` | 10 | `message` `group` `search` | Group CRUD, member management, bot messaging, webhook | +| Bot | `chat bot` | 6 | `bot` `group` `message` `search` | Robot creation/search, group/single messaging, webhook, message recall | | Calendar | `calendar` | 13 | `event` `room` `participant` `busy` | Events CRUD, meeting room booking, free-busy query, participant management | | Todo | `todo` | 6 | `task` | Create, list, update, done, get detail, delete | | Approval | `oa` | 9 | `approval` | Approve/reject/revoke, pending tasks, initiated instances, process list | | Attendance | `attendance` | 4 | `record` `shift` `summary` `rules` | Clock-in records, shift schedules, attendance summary, group rules | -| Ding | `ding` | 3 | `message` | Send/recall DING messages | +| Ding | `ding` | 2 | `message` | Send/recall DING messages | | Report | `report` | 7 | `create` `list` `detail` `template` `stats` `sent` | Create reports, sent/received list, templates, statistics | -| AITable | `aitable` | 27 | `base` `table` `record` `field` `attachment` `template` | Full CRUD for bases/tables/records/fields, views, import/export, templates | +| AITable | `aitable` | 20 | `base` `table` `record` `field` `attachment` `template` | Full CRUD for bases/tables/records/fields, templates | | Workbench | `workbench` | 2 | `app` | Batch query app details | -| DevDoc | `devdoc` | 2 | `article` | Search platform docs and error codes | +| DevDoc | `devdoc` | 1 | `article` | Search platform docs and error codes | -> 104 tools across 12 products. Run `dws --help` for the full list, or `dws --help` for subcommands. +> 86 commands across 12 products. Run `dws --help` for the full list, or `dws --help` for subcommands.
Coming soon diff --git a/README_zh.md b/README_zh.md index 9b9c9b3a..7b4bba24 100644 --- a/README_zh.md +++ b/README_zh.md @@ -19,7 +19,7 @@

> [!IMPORTANT] -> **共创阶段**：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。当前为灰度共创阶段，请加入钉钉 DWS 共创群完成白名单配置。详见下方 [开始使用](#开始使用)。 +> **共创阶段**：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。欢迎加入钉钉 DWS 共创群获取支持与最新动态。详见下方 [开始使用](#开始使用)。 > > DingTalk Group QR Code @@ -87,78 +87,57 @@ cp dws ~/.local/bin/ # 安装到 PATH ## 开始使用 -### 步骤 1：创建钉钉应用 - -进入 [开放平台应用开发后台](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app)，在「企业内部应用 - 钉钉应用」点击**创建应用**。 - -
-查看截图 -

- 创建应用 -

-
- -### 步骤 2：配置重定向 URL - -进入应用 → **安全设置**，在「重定向 URL」中添加以下地址并保存： - -``` -http://127.0.0.1,https://login.dingtalk.com +```bash +dws auth login ``` -> `http://127.0.0.1` 用于本地浏览器登录；`https://login.dingtalk.com` 用于 `--device` 设备流登录（Docker 容器、远程服务器等无浏览器环境）。建议两个都配置。 +浏览器自动打开 — 选择组织并授权即可。 + +

+ 授权成功 +

+ +> 如果组织尚未开启 CLI 访问权限，系统会引导你向管理员发送申请。审批通过后重新执行 `dws auth login` 即可。
-查看截图 +组织未开启 CLI 访问权限？ + +1. 选择组织后，点击「立即申请」通知管理员 +2. 管理员收到申请卡片，一键审批 +3. 审批通过后，重新执行 `dws auth login` +

- 配置重定向URL + 申请权限

+
-### 步骤 3：发布应用 - -点击「应用发布 - 版本管理与发布」，发布版本使应用上线。 -
-查看截图 +管理员：为组织开启 CLI 访问权限 + +进入 [开发者平台](https://open-dev.dingtalk.com) →「CLI 访问管理」→ 开启。 +

- 发布应用 + CLI访问管理

+
-### 步骤 4：申请白名单 +
+自建应用模式（CI/CD、ISV 集成） -加入钉钉 DWS 共创群，提供 **Client ID** 和**管理员确认凭证**完成白名单配置。 +企业自主管控场景，可创建自有钉钉应用： -### 步骤 5：登录认证 +1. [开放平台应用开发后台](https://open-dev.dingtalk.com/fe/app#/corp/app) → 创建应用 +2. 安全设置 → 添加重定向 URL：`http://127.0.0.1,https://login.dingtalk.com` +3. 发布应用 +4. 登录： ```bash dws auth login --client-id --client-secret ``` -或通过环境变量： - -```bash -export DWS_CLIENT_ID= -export DWS_CLIENT_SECRET= -dws auth login -``` - -
-凭证配置优先级 - -`client-id` 和 `client-secret` 支持多种配置方式，按以下优先级生效（从高到低）： - -| 优先级 | 配置方式 | 说明 | -|------|----------|------| -| 1 | CLI 参数 / 持久化配置 | `--client-id` / `--client-secret` 命令行参数；首次登录成功后自动保存，`client-secret` 存储在系统 Keychain 中 | -| 2 | 环境变量 | `DWS_CLIENT_ID` / `DWS_CLIENT_SECRET` | -| 3 | 默认值 | 代码中的预设值（仅开发时使用） | - -**推荐用法**： -- **首次登录**：使用 `--client-id` 和 `--client-secret` 参数，登录成功后凭证会自动安全存储 -- **后续使用**：直接运行 `dws` 命令，Token 自动刷新时会从 Keychain 读取已保存的凭证 -- **CI/CD 环境**：建议使用环境变量配置 +首次登录后凭证安全存储（Keychain），后续自动刷新 Token。
@@ -175,13 +154,6 @@ dws todo task list --dry-run # 预览操作但不执行 dws 是为 AI Agent 设计的 CLI 工具。请先完成[安装](#安装)和[开始使用](#开始使用)，然后配置 Agent 环境： -```bash -# 通过环境变量配置认证（Agent 推荐方式，无需交互式登录） -export DWS_CLIENT_ID= -export DWS_CLIENT_SECRET= -dws auth login -``` - ### Agent 调用模式 ```bash @@ -334,22 +306,22 @@ dws chat message send-by-bot --robot-code BOT_CODE --group GROUP_ID \ ## 核心服务 -| 服务 | 命令 | 工具数 | 子命令 | 描述 | +| 服务 | 命令 | 命令数 | 子命令 | 描述 | |------|------|:------:|--------|------| -| 通讯录 | `contact` | 8 | `user` `dept` | 按姓名/手机号搜索、批量查询、部门树、当前用户信息 | -| 群聊 | `chat` | 14 | `message` `group` `bot` `search` | 群增删改查、成员管理、话题回复、以用户身份发消息 | -| 机器人 | `chat bot` | 9 | — | 机器人创建、群聊/单聊消息、Webhook、消息撤回 | +| 通讯录 | `contact` | 6 | `user` `dept` | 按姓名/手机号搜索、批量查询、部门树、当前用户信息 | +| 群聊 | `chat` | 10 | `message` `group` `search` | 群增删改查、成员管理、机器人消息、Webhook | +| 机器人 | `chat bot` | 6 | `bot` `group` `message` `search` | 机器人创建/搜索、群聊/单聊消息、Webhook、消息撤回 | | 日历 | `calendar` | 13 | `event` `room` `participant` `busy` | 日程增删改查、会议室预订、闲忙查询、参与者管理 | | 待办 | `todo` | 6 | `task` | 创建、列表、修改、完成、详情、删除 | | 审批 | `oa` | 9 | `approval` | 同意/拒绝/撤销、待我审批、我发起的、流程列表 | | 考勤 | `attendance` | 4 | `record` `shift` `summary` `rules` | 打卡记录、排班查询、考勤摘要、考勤组规则 | -| DING | `ding` | 3 | `message` | 发送/撤回 DING 消息 | +| DING | `ding` | 2 | `message` | 发送/撤回 DING 消息 | | 日志 | `report` | 7 | `create` `list` `detail` `template` `stats` `sent` | 创建日志、收发列表、模版、统计 | -| 智能表格 | `aitable` | 27 | `base` `table` `record` `field` `attachment` `template` | 多维表/数据表/记录/字段全量 CRUD、视图、导入导出、模板 | +| 智能表格 | `aitable` | 20 | `base` `table` `record` `field` `attachment` `template` | 多维表/数据表/记录/字段全量 CRUD、模板 | | 工作台 | `workbench` | 2 | `app` | 批量查询应用详情 | -| 开发者文档 | `devdoc` | 2 | `article` | 搜索开放平台文档与错误码 | +| 开发者文档 | `devdoc` | 1 | `article` | 搜索开放平台文档与错误码 | -> 12 个产品，104 个工具。运行 `dws --help` 查看完整列表，或 `dws --help` 查看子命令。 +> 12 个产品，86 个命令。运行 `dws --help` 查看完整列表，或 `dws --help` 查看子命令。
即将推出