use-dingding

# DingTalk Workspace Skill Use the `dws` CLI to interact with DingTalk enterprise workspace. This skill covers all 12 products: contact, chat, bot, calendar, todo, oa (approval), attendance, ding, report, aitable, workbench, and devdoc. ## ⚠️ Security & Safety Notes **Read before installing:** 1. **Credentials Required**: This skill requires OAuth credentials (DWS_CLIENT_ID, DWS_CLIENT_SECRET) from a DingTalk Open Platform app. Enterprise admin approval may be needed. 2. **Install Safely**: The `dws` CLI installer fetches from GitHub. **Review the installer script before running**: - Installer: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/blob/main/scripts/install.sh - Releases: https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases 3. **Autonomous Execution Risk**: This skill can perform destructive actions (approve workflows, send messages, delete records). **Always use `--dry-run` first** and restrict autonomous invocation unless you trust the agent. 4. **Least Privilege**: Use scoped OAuth credentials with minimum permissions. Test in a sandbox enterprise first. ## Prerequisites ### Installation **Option 1: Install from release (recommended)** Download pre-built binary from https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases **Option 2: Build from source (safer)** ```bash git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git cd dingtalk-workspace-cli go build -o dws ./cmd cp dws ~/.local/bin/ ``` **Option 3: Install script (review first!)** ```bash # macOS / Linux - REVIEW SCRIPT BEFORE RUNNING curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh # Windows (PowerShell) - REVIEW SCRIPT BEFORE RUNNING irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex ``` ### Authentication **Recommended: Interactive Login (secure keychain storage)** ```bash dws auth login --client-id <your-app-key> --client-secret <your-app-secret> # Tokens stored encrypted in system Keychain (macOS/Windows) or libsecret (Linux) ``` **Alternative: Environment Variables (use with caution)** ```bash export DWS_CLIENT_ID=<your-app-key> export DWS_CLIENT_SECRET=<your-app-secret> dws auth login ``` ⚠️ **Security note**: Environment variables may be exposed in process listings and logs. Prefer interactive login for production use. ## Safe Execution Guidelines ### For Agents - **`--dry-run`**: **ALWAYS use first** for mutations to preview API calls - **`--yes`**: Skip confirmation prompts (use only after verifying with --dry-run) - **`--jq`**: Extract specific fields to reduce token consumption - **`--fields`**: Return only needed fields ### Recommended Workflow ```bash # 1. Preview the operation dws todo task create --title "Test" --executors "user123" --dry-run # 2. Verify the output looks correct # 3. Execute (only if preview was correct) dws todo task create --title "Test" --executors "user123" --yes ``` ### Auto-Correction `dws` automatically corrects common AI mistakes: - `--baseId` → `--base-id` (camelCase to kebab-case) - `--timeout30` → `--timeout 30` (sticky argument splitting) - `--tabel-id` → `--table-id` (fuzzy matching) - `"yes"` → `true`, `"2024/03/29"` → `"2024-03-29"` (value normalization) ## Discovery & Introspection Before making calls, discover available capabilities: ```bash # List all products and tool counts dws schema --jq '.products[] | {id, tool_count: (.tools | length)}' # Inspect a specific tool's parameter schema dws schema aitable.query_records --jq '.tool.parameters' # View required fields dws schema aitable.query_records --jq '.tool.required' # List all product IDs dws schema --jq '.products[].id' ``` ## Quick Reference by Product ### Contact ```bash # Search users by keyword dws contact user search --keyword "engineering" # Get current user profile dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName}' # Search department by name dws contact dept search --keyword "Engineering" # List department members dws contact dept members --dept-id <dept-id> ``` ### Chat ```bash # Send message as bot dws chat message send-by-bot --robot-code <BOT_CODE> --group <GROUP_ID> --title "Weekly Report" --text @report.md # List groups dws chat group list # Get group info dws chat group get --group-id <GROUP_ID> ``` ### Calendar ```bash # List calendar events dws calendar event list # Create event dws calendar event create --title "Team Meeting" --start "2024-03-29T14:00:00Z" --end "2024-03-29T15:00:00Z" # Find free slots dws calendar participant busy --user-ids <user-id-1>,<user-id-2> --start "2024-03-29" --end "2024-03-30" # Search meeting rooms dws calendar room search --keyword "Meeting Room" ``` ### Todo ```bash # Create todo dws todo task create --title "Review PR" --executors "<your-userId>" --yes # List todos dws todo task list # Mark as done dws todo task done --task-id <task-id> ``` ### Approval (OA) ```bash # List pending approvals dws oa approval list --status pending # Approve instance dws oa approval approve --instance-id <instance-id> --comment "Approved" # Reject instance dws oa approval reject --instance-id <instance-id> --comment "Needs revision" ``` ### Attendance ```bash # View my attendance records dws attendance record list --user-id <your-userId> # View team shift schedule dws attendance shift list --dept-id <dept-id> ``` ### Report ```bash # View today's received reports dws report list --type received --start-date "2024-03-29" --end-date "2024-03-29" # Create report dws report create --template-id <template-id> --content @report.md ``` ### AITable ```bash # Query records dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> --limit 10 # Create record dws aitable record create --base-id <BASE_ID> --table-id <TABLE_ID> --fields '{"name": "Task 1", "status": "open"}' # List bases dws aitable base list # List tables in a base dws aitable table list --base-id <BASE_ID> ``` ## Output Control ### jq Filtering ```bash # Extract specific fields dws contact user search --keyword "engineering" --jq '.result[] | {name: .orgUserName, userId: .userId}' # Count results dws todo task list --jq '.result | length' ``` ### Field Selection ```bash # Return only specific fields dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> --fields invocation,response ``` ### File Input ```bash # Read from file dws chat message send-by-bot --robot-code <BOT_CODE> --group <GROUP_ID> --text @message.md # Pipe from stdin cat message.md | dws chat message send-by-bot --robot-code <BOT_CODE> --group <GROUP_ID> ``` ## Common Workflows See bundled scripts in `scripts/` for batch operations: **Safety First:** All mutation scripts default to `--dry-run` mode. You must explicitly pass `--execute` to perform actual changes. | Script | Description | |--------|-------------| | `calendar_schedule_meeting.py` | Create event + add participants + book meeting room (use `--execute` to book) | | `calendar_free_slot_finder.py` | Find common free slots across multiple people (read-only) | | `todo_batch_create.py` | Batch create todos from JSON (use `--execute` to create) | | `contact_dept_members.py` | Search department and list all members (read-only) | | `report_inbox_today.py` | View today's received reports (read-only) | | `import_records.py` | Import CSV records into AITable (use `--execute` to import) | **Example:** ```bash # Preview first (default behavior) python scripts/todo_batch_create.py tasks.json # Execute after verifying preview python scripts/todo_batch_create.py tasks.json --execute ``` ## Error Handling ### Common Error Codes - `INVALID_TOKEN`: Re-authenticate with `dws auth login` - `PERMISSION_DENIED`: Check app permissions in DingTalk Open Platform - `RESOURCE_NOT_FOUND`: Verify IDs with `dws schema` introspection ### Recovery When encountering `RECOVERY_EVENT_ID`, use: ```bash dws --recovery <RECOVERY_EVENT_ID> ``` ## Security Notes - Credentials are stored encrypted in system Keychain (never in config files) - All requests use HTTPS to `*.dingtalk.com` only - Use `--dry-run` before any mutation to preview the API call - Token refresh is automatic; no manual intervention needed ## Reference Files - **Product commands**: See `references/products/*.md` for detailed command reference per product - **Intent guide**: See `references/intent-guide.md` for disambiguation (e.g., report vs todo) - **Error codes**: See `references/error-codes.md` for debugging workflows - **Global reference**: See `references/global-reference.md` for auth, output formats, global flags