Dingtalk Workspace

SKILL.md

---
name: dingtalk-workspace
description: Interact with DingTalk enterprise workspace using the `dws` CLI. Use for: (1) searching contacts and departments, (2) sending chat messages, (3) managing calendar events and meeting rooms, (4) creating and managing todos, (5) approval workflows, (6) attendance records, (7) AITable CRUD operations, (8) report management. Requires dws CLI installed and authenticated via OAuth.
---

# 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

```bash
# First-time login (credentials saved to system Keychain)
dws auth login --client-id <your-app-key> --client-secret <your-app-secret>

# Or via environment variables
export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
dws auth login
```

## 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:

| Script | Description |
|--------|-------------|
| `calendar_schedule_meeting.py` | Create event + add participants + book meeting room |
| `calendar_free_slot_finder.py` | Find common free slots across multiple people |
| `todo_batch_create.py` | Batch create todos from JSON |
| `contact_dept_members.py` | Search department and list all members |
| `report_inbox_today.py` | View today's received reports |

## 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