Dingtalk Workspace

Interact with DingTalk enterprise workspace to search contacts, send messages, manage calendars, todos, approvals, attendance, reports, and AITable data via...

Security Scan

The skill mostly does what it says (wraps a DingTalk CLI) but has several coherence issues and operational risks (metadata mismatch about credentials, scripts that perform mutations without safe dry-run, and installer instructions that pipe remote scripts), so review before installing.

Purpose & Capability

The skill's stated purpose (DingTalk workspace operations) matches the included scripts and docs: they call a 'dws' CLI to manage contacts, chat, calendar, todo, approvals, attendance, reports and AITable. However the registry metadata at the top lists no required environment variables/credentials while the SKILL.md and clawhub.yml repeatedly state this needs OAuth credentials (DWS_CLIENT_ID / DWS_CLIENT_SECRET). That inconsistency (metadata says none required; docs and code require credentials) is noteworthy and unexplained.

Instruction Scope

SKILL.md repeatedly cautions to use --dry-run and least-privilege credentials, but several bundled scripts call the dws CLI programmatically with mutation flags that bypass prompts: import_records.py's run_dws appends '--yes', calendar_schedule_meeting.py's run_dws_action appends '--yes' unless --dry-run is explicitly set, and other scripts can create/update/delete records. That contradicts the 'always preview' guidance and grants the code the ability to perform destructive changes if invoked without care.

Install Mechanism

There is no formal install spec in the registry (instruction-only), which is lower-risk from an automatic-install perspective. The SKILL.md instructs users to download a prebuilt binary or run an installer script pulled from a GitHub repo (raw.githubusercontent.com curl|sh and PowerShell 'iex' links). Pulling and executing remote install scripts is common but higher-risk unless you verify the upstream repository; the URLs point to a third-party GitHub repo (DingTalk-Real-AI) rather than an official vendor site, so verify authenticity before running.

Credentials

Requesting DWS_CLIENT_ID and DWS_CLIENT_SECRET is appropriate for a DingTalk CLI integration and those env vars are documented in the skill's clawhub.yml and SKILL.md. The problem is the manifest/registry metadata in the header reported 'Required env vars: none' and 'Primary credential: none', which contradicts the internal documentation. This metadata mismatch could mislead users or automated install systems into not providing necessary credentials securely. No unrelated credentials are requested by the code.

Persistence & Privilege

The skill is not marked 'always:true' and uses normal autonomous invocation defaults. That is expected. However, because the skill can perform destructive operations (approvals, deletes, create with '--yes'), giving it autonomous invocation increases risk — the combination of autonomous execution and scripts that default to executing mutations (instead of always dry-running) is a practical security concern and should be managed (restrict autonomous use or require explicit confirmation).

What to consider before installing

What to check before installing/using this skill: - Credentials: SKILL.md and clawhub.yml require OAuth credentials (DWS_CLIENT_ID and DWS_CLIENT_SECRET). The registry header incorrectly lists no required env vars — don't rely on that. Use scoped, least-privilege app credentials and prefer interactive/keychain login rather than env vars where possible. - Verify the CLI: SKILL.md points to a third-party GitHub repo (https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli). Manually review the repository and the installer script before running any curl | sh or PowerShell 'iex' commands. Prefer installing from a vetted release or building from source yourself. - Scripts can mutate state: Several bundled scripts call dws with automatic '--yes' (e.g., import_records.py) or will perform mutations unless you pass explicit dry-run flags. If you intend to let the agent run this skill autonomously, restrict that permission or ensure operations are always run with --dry-run by default. - Test in a sandbox: Follow the skill's own advice — test in a non-production/sandbox enterprise and use least-privilege app approvals first. - Operational controls: Disable autonomous invocation for this skill unless you trust the agent; require explicit user confirmation for any mutation; audit activity and token usage; rotate credentials if you stop using the skill. Given the metadata inconsistencies and scripts that can perform destructive actions without safe defaults, treat this skill as 'suspicious' until you confirm the repo authenticity and adjust operational safeguards.

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)

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!)

# 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

# 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

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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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

# Return only specific fields
dws aitable record query --base-id <BASE_ID> --table-id <TABLE_ID> --fields invocation,response

File Input

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

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