# 钉钉 DWS CLI 命令实战总结：已掌握与待探索功能

> 作者: Elaine
> 日期: 2026-04-30
> 标签: 钉钉, CLI

---

<h1>钉钉 DWS CLI 命令实战总结</h1>
        <p class="subtitle">已掌握 12 个命令 · 待探索 8 个功能 · 实战日期：2026-04-30</p>

        <!-- Part 1: 已掌握的命令 -->
        <div class="section">
            <h2>一、已掌握的命令 ✅</h2>

            <h3>1. 通讯录 — contact</h3>
            <div class="cmd-block">
                <div class="cmd">dws contact user get-self --format json</div>
                <div class="desc">获取当前用户信息（userId、所属部门等）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws contact dept search --query "研发" --format json</div>
                <div class="desc">按部门名称关键词搜索部门，返回部门ID</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws contact dept list-members --ids 40182869 --format json</div>
                <div class="desc">查询指定部门的所有成员（姓名 + userId）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws contact user search --query "姓名" --format json</div>
                <div class="desc">按姓名关键词搜索用户，返回 userId 列表</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws contact user search-mobile --mobile 13800138000 --format json</div>
                <div class="desc">通过手机号查 userId</div>
            </div>

            <h3>2. 考勤 — attendance</h3>
            <div class="cmd-block">
                <div class="cmd">dws attendance record get --user &lt;USER_ID&gt; --date 2026-04-30 --format json</div>
                <div class="desc">查询指定用户某日的考勤记录（打卡时间、排班状态等）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws attendance shift list --users userId1,userId2 --start 2026-04-27 --end 2026-05-03 --format json</div>
                <div class="desc">批量查询团队排班（最多50人，间隔不超过7天）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws attendance rules --date 2026-04-30 --format json</div>
                <div class="desc">查看考勤规则（打卡范围、弹性时间等）</div>
            </div>

            <h3>3. 待办 — todo</h3>
            <div class="cmd-block">
                <div class="cmd">dws todo task create --title "任务标题" --executors &lt;USER_ID&gt; --priority 30 --format json</div>
                <div class="desc">创建待办任务（priority: 10低/20普通/30较高/40紧急）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws todo task list --page 1 --size 20 --status false --format json</div>
                <div class="desc">查询未完成（false）或已完成（true）的待办列表</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws todo task done --task-id &lt;ID&gt; --status true --format json</div>
                <div class="desc">标记指定待办为已完成</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws todo task delete --task-id &lt;ID&gt; --yes --format json</div>
                <div class="desc">删除待办（⚠️ 不可逆，需 --yes 确认）</div>
            </div>

            <h3>4. 日历 — calendar</h3>
            <div class="cmd-block">
                <div class="cmd">dws calendar event create --title "标题" --start "2026-05-06T10:00:00+08:00" --end "2026-05-06T10:30:00+08:00" --format json</div>
                <div class="desc">创建日程，自动发送钉钉提醒（默认提前15分钟）</div>
            </div>

            <h3>5. 邮箱 — mail</h3>
            <div class="cmd-block">
                <div class="cmd">dws mail mailbox list --format json</div>
                <div class="desc">查看当前邮箱账号列表</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws mail message search --email &lt;邮箱地址&gt; --query "subject:*" --size 5 --format json</div>
                <div class="desc">搜索邮件（KQL 语法，支持 date:2026-04-30 等条件）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws mail message get --mail-id &lt;ID&gt; --format json</div>
                <div class="desc">查看邮件完整内容</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws mail message send --to "xxx@xxx.com" --subject "标题" --content "正文" --format json</div>
                <div class="desc">发送邮件</div>
            </div>

            <h3>6. 群聊消息 — chat</h3>
            <div class="cmd-block">
                <div class="cmd">dws chat message send --group &lt;群ID&gt; --title "标题" --text "内容" --at-all --format json</div>
                <div class="desc">以当前用户身份发群消息，支持 @所有人</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat message send-by-webhook --token &lt;WEBHOOK_TOKEN&gt; --title "标题" --text "内容" --format json</div>
                <div class="desc">通过自定义机器人 Webhook 发群消息（无需认证，适合告警场景）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat message search --keyword "关键词" --start "2026-04-01T00:00:00+08:00" --end "2026-04-30T23:59:59+08:00" --format json</div>
                <div class="desc">按关键词搜索群聊消息记录</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat message list-mentions --start "2026-04-30T00:00:00+08:00" --end "2026-04-30T23:59:59+08:00" --format json</div>
                <div class="desc">拉取某时间段内 @我的所有消息</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat search --query "群名关键词" --format json</div>
                <div class="desc">搜索群会话列表</div>
            </div>
        </div>

        <!-- Part 2: 尚未使用的功能 -->
        <div class="section">
            <h2>二、待探索功能 🔮</h2>

            <h3>1. OA 审批 — oa</h3>
            <p>已验证可用的命令：</p>
            <div class="cmd-block">
                <div class="cmd">dws oa approval list-pending --format json</div>
                <div class="desc">查看待我审批的单子（processInstanceId）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws oa approval list-forms --cursor 0 --size 20 --format json</div>
                <div class="desc">查看企业可用审批表单模板（processCode）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws oa approval detail --instance-id &lt;ID&gt; --format json</div>
                <div class="desc">查看审批单详情（表单字段、附件、当前状态）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws oa approval approve --instance-id &lt;ID&gt; --task-id &lt;ID&gt; --remark "同意" --format json</div>
                <div class="desc">同意审批（⚠️ 需先获取 taskId）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws oa approval reject --instance-id &lt;ID&gt; --task-id &lt;ID&gt; --remark "拒绝理由" --format json</div>
                <div class="desc">拒绝审批（⚠️ 需先获取 taskId）</div>
            </div>

            <h3>2. AI 表格 — aitable</h3>
            <p>适合运维场景：工单管理、监控数据报表、资产台账。</p>
            <div class="cmd-block">
                <div class="cmd">dws aitable base list --format json</div>
                <div class="desc">列出最近访问的 AI 表格</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws aitable base search --query "关键词" --format json</div>
                <div class="desc">搜索 AI 表格</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws aitable base get --base-id &lt;ID&gt; --format json</div>
                <div class="desc">获取表格详情（tableId、dashboardId 等）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws aitable record list --base-id &lt;ID&gt; --table-id &lt;ID&gt; --format json</div>
                <div class="desc">列出数据表中的所有记录</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws aitable dashboard get --base-id &lt;ID&gt; --dashboard-id &lt;ID&gt; --format json</div>
                <div class="desc">查看图表仪表盘</div>
            </div>

            <h3>3. 钉钉文档 — doc</h3>
            <p>适合运维场景：故障复盘文档、运维手册、知识库。</p>
            <div class="cmd-block">
                <div class="cmd">dws doc search --query "故障复盘" --format json</div>
                <div class="desc">搜索钉钉文档</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws doc node get --node-id &lt;ID&gt; --format json</div>
                <div class="desc">读取文档内容</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws doc node create --title "标题" --folder-id &lt;ID&gt; --format json</div>
                <div class="desc">创建新文档</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws doc block create --node-id &lt;ID&gt; --block-type "text" --content "内容" --format json</div>
                <div class="desc">向文档写入块级内容</div>
            </div>

            <h3>4. 云盘 — drive</h3>
            <p>适合运维场景：日志文件归档、备份包存取、报告下载。</p>
            <div class="cmd-block">
                <div class="cmd">dws drive file list --space-id &lt;ID&gt; --format json</div>
                <div class="desc">列出云盘文件</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws drive upload-info --file-name "xxx.log" --file-size &lt;字节数&gt; --format json</div>
                <div class="desc">获取文件上传信息（上传URL）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws drive commit --file-name "xxx.log" --file-size &lt;字节数&gt; --upload-id &lt;ID&gt; --format json</div>
                <div class="desc">确认上传完成</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws drive download --file-id &lt;ID&gt; --format json</div>
                <div class="desc">下载文件</div>
            </div>

            <h3>5. AI 听记 — minutes</h3>
            <p>适合运维场景：值班交接会议自动生成纪要、提取待办事项。</p>
            <div class="cmd-block">
                <div class="cmd">dws minutes list --format json</div>
                <div class="desc">获取听记列表</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws minutes get --minutes-id &lt;ID&gt; --format json</div>
                <div class="desc">获取听记摘要、转写、待办</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws minutes mindmap --minutes-id &lt;ID&gt; --format json</div>
                <div class="desc">获取思维导图</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws minutes speaker-list --minutes-id &lt;ID&gt; --format json</div>
                <div class="desc">获取发言人列表</div>
            </div>

            <h3>6. 日志/日报 — report</h3>
            <p>适合运维场景：团队日报收集、运维日志汇总统计。</p>
            <div class="cmd-block">
                <div class="cmd">dws report template list --format json</div>
                <div class="desc">查看可用日志模板</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws report create --template-id &lt;ID&gt; --content "日报内容" --format json</div>
                <div class="desc">按模板创建日报</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws report inbox --format json</div>
                <div class="desc">查看收到的日志（收件箱）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws report detail --report-id &lt;ID&gt; --format json</div>
                <div class="desc">查看日志详情</div>
            </div>

            <h3>7. DING 消息 — ding</h3>
            <p>适合运维场景：P0 故障紧急电话/短信通知。</p>
            <div class="cmd-block">
                <div class="cmd">dws ding message send --robot-code &lt;CODE&gt; --users &lt;USER_ID&gt; --type app --content "内容" --format json</div>
                <div class="desc">发送应用内 DING（免费）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws ding message send --robot-code &lt;CODE&gt; --users &lt;USER_ID&gt; --type call --content "紧急内容" --format json</div>
                <div class="desc">发送电话 DING（⚠️ 有通信成本，紧急时使用）</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws ding message send --robot-code &lt;CODE&gt; --users &lt;USER_ID&gt; --type sms --content "内容" --format json</div>
                <div class="desc">发送短信 DING（⚠️ 有通信成本）</div>
            </div>

            <h3>8. 群组管理 — chat group</h3>
            <div class="cmd-block">
                <div class="cmd">dws chat group create --name "群名" --users userId1,userId2 --format json</div>
                <div class="desc">创建内部群</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat group members list --id &lt;群ID&gt; --format json</div>
                <div class="desc">查看群成员列表</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat group members add --id &lt;群ID&gt; --users userId1,userId2 --format json</div>
                <div class="desc">添加群成员</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat group rename --id &lt;群ID&gt; --name "新群名" --format json</div>
                <div class="desc">修改群名称</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws chat group members add-bot --id &lt;群ID&gt; --robot-code &lt;CODE&gt; --format json</div>
                <div class="desc">添加机器人到群</div>
            </div>
        </div>

        <!-- Part 3: 缺失功能 -->
        <div class="section">
            <h2>三、暂不支持的功能 ❌</h2>

            <div class="warning">
                <ul>
                    <li><strong>群公告（Announcement）</strong>：DWS CLI 目前没有群公告专用命令，普通群消息无法置顶，实用性大打折扣</li>
                    <li><strong>部门组织架构全量查询</strong>：根部门 ID=1 返回空，需从已知部门逐步展开，缺少全量树形结构接口</li>
                    <li><strong>通讯录批量导出</strong>：list-members 只能按部门查，无法一次性导出全公司成员</li>
                    <li><strong>Corp Token 应用凭证登录</strong>：DWS 不支持 AppKey/AppSecret 直接登录，只能用 OAuth 设备流，每个新 Scope 首次需扫码授权</li>
                </ul>
            </div>
        </div>

        <!-- Part 4: 授权机制说明 -->
        <div class="section">
            <h2>四、授权机制说明 🔐</h2>
            <p>DWS CLI 使用 OAuth 2.0 个人授权，refresh_token 有效期 <strong>30 天</strong>，每个新 API Scope 首次使用需要扫码授权一次。</p>

            <div class="info">
                <strong>常见报错：</strong>
                <ul style="margin-top:10px">
                    <li><code>PAT_MEDIUM_RISK_NO_PERMISSION</code> → 该 Scope 尚未授权，命令行会返回授权链接，点击扫码即可</li>
                    <li><code>.AUTH_TOKEN_EXPIRED</code> → Token 过期，执行 <code>dws auth login --force</code> 重新登录</li>
                    <li><code>InvalidParameter</code> → 参数错误，检查 flag 名称（kebab-case）和格式</li>
                </ul>
            </div>

            <div class="success">
                <strong>一次性搞定所有授权：</strong>把所有会用到的命令都跑一遍授权，之后 30 天内无需再弹框。
            </div>

            <div class="highlight">
                <strong>技巧：</strong>遇到授权弹框时，命令行会直接输出完整的授权 URL，复制给用户在浏览器打开即可完成授权，无需在服务器端操作。
            </div>
        </div>

        <!-- Part 5: 命令发现 -->
        <div class="section">
            <h2>五、命令发现技巧 🔧</h2>
            <p>遇到不确定的命令时，按以下优先级查阅：</p>
            <ol>
                <li><code>dws &lt;cmd&gt; --help</code> — 人类可读的 Usage、Example、Flags</li>
                <li><code>dws schema &lt;product&gt;.&lt;command&gt;</code> — 机器可读 Schema（参数名、必填、别名）</li>
                <li><code>dws schema</code> — 列出所有产品和命令</li>
            </ol>

            <div class="cmd-block">
                <div class="cmd">dws schema calendar.event create --jq '.tool.flag_overlay'</div>
                <div class="desc">查看 calendar.event create 的所有 flag 别名</div>
            </div>
            <div class="cmd-block">
                <div class="cmd">dws schema calendar.event create --jq '.tool.required'</div>
                <div class="desc">查看 calendar.event create 的必填字段</div>
            </div>
        </div>