DingTalk-Real-AI · PeterGuy326 · Jun 5, 2026 · Jun 7, 2026
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 <p align="center"><code>dws</code> — DingTalk Workspace on the command line, built for humans and AI agents.</p>
 
 <p align="center">
-  <img src="https://img.alicdn.com/imgextra/i1/O1CN01oKAc2r28jOyyspcQt_!!6000000007968-2-tps-4096-1701.png" alt="DWS Product Overview" width="100%">
+  <img src="./docs/assets/dws-demo.gif" alt="dws in action: an AI agent operating DingTalk via the CLI" width="100%">
 </p>
 
 <p align="center">
@@ -12,16 +12,25 @@
   <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases"><img src="https://img.shields.io/github/v/release/DingTalk-Real-AI/dingtalk-workspace-cli?color=red&label=release" alt="Latest Release"></a>
   <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/actions/workflows/ci.yml"><img src="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src=".github/badges/coverage.svg" alt="Coverage">
+  <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/stargazers"><img src="https://img.shields.io/github/stars/DingTalk-Real-AI/dingtalk-workspace-cli?label=stars&color=yellow" alt="GitHub stars"></a>
 </p>
 
 <p align="center">
   <a href="./README_zh.md">中文版</a> · <a href="./README.md">English</a> · <a href="./docs/reference.md">Reference</a> · <a href="./CHANGELOG.md">Changelog</a>
 </p>
 
-> [!IMPORTANT]
-> **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.
->
-> <img src="https://img.alicdn.com/imgextra/i1/O1CN01WJyAsJ1prD2ovQACM_!!6000000005413-2-tps-718-720.png" alt="dws Open Source Community DingTalk Group QR Code" width="150">
+<p align="center"><strong>One CLI gives your AI agent — or you — control over all of DingTalk.</strong><br>
+Send messages, manage calendars, search docs, drive AI Sheets, run approvals — <strong>330 commands across 18 products</strong>, returned as structured JSON an agent can act on. Zero-trust by design: <strong>not a single byte bypasses auth and audit.</strong></p>
+
+```bash
+# Install (macOS / Linux)
+curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh
+
+# Your agent (or you) can now do things like:
+dws contact user search --query "Wei Zhang"        # resolve a person
+dws calendar event list                            # what's on the calendar
+dws aisearch person --query "who owns payments"    # find who owns an area
+```
 
 <details>
 <summary><strong>Table of Contents</strong></summary>
@@ -152,6 +161,11 @@ A backup of the current version is automatically created before each upgrade. Us
 
 ## Getting Started
 
+> [!IMPORTANT]
+> **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.
+>
+> <img src="https://img.alicdn.com/imgextra/i1/O1CN01WJyAsJ1prD2ovQACM_!!6000000005413-2-tps-718-720.png" alt="dws Open Source Community DingTalk Group QR Code" width="150">
+
 ```bash
 dws auth login            # browser opens automatically
 dws auth login --device   # for headless environments (Docker, SSH, CI)

diff --git a/README_zh.md b/README_zh.md
@@ -3,7 +3,7 @@
 <p align="center"><code>dws</code> — 钉钉工作台命令行工具，为人类和 AI Agent 而生。</p>
 
 <p align="center">
-  <img src="https://img.alicdn.com/imgextra/i1/O1CN01oKAc2r28jOyyspcQt_!!6000000007968-2-tps-4096-1701.png" alt="DWS Product Overview" width="100%">
+  <img src="./docs/assets/dws-demo.gif" alt="dws 实战：AI Agent 通过命令行操作钉钉" width="100%">
 </p>
 
 <p align="center">
@@ -12,16 +12,25 @@
   <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases"><img src="https://img.shields.io/github/v/release/DingTalk-Real-AI/dingtalk-workspace-cli?color=red&label=release" alt="Latest Release"></a>
   <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/actions/workflows/ci.yml"><img src="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <img src=".github/badges/coverage.svg" alt="Coverage">
+  <a href="https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/stargazers"><img src="https://img.shields.io/github/stars/DingTalk-Real-AI/dingtalk-workspace-cli?label=stars&color=yellow" alt="GitHub stars"></a>
 </p>
 
 <p align="center">
   <a href="./README_zh.md">中文版</a> · <a href="./README.md">English</a> · <a href="./docs/reference.md">参考手册</a> · <a href="./CHANGELOG.md">更新日志</a>
 </p>
 
-> [!IMPORTANT]
-> **共创阶段**：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。欢迎加入钉钉 DWS 共创群获取支持与最新动态。详见下方 [开始使用](#开始使用)。
->
-> <img src="https://img.alicdn.com/imgextra/i1/O1CN01WJyAsJ1prD2ovQACM_!!6000000005413-2-tps-718-720.png" alt="dws 开源沟通群二维码" width="150">
+<p align="center"><strong>一个 CLI，让你的 AI Agent（或你自己）掌控整个钉钉。</strong><br>
+收发消息、管理日程、搜索文档、操作 AI 表格、跑审批 —— <strong>18 个产品、330 条命令</strong>，全部返回 Agent 可直接处理的结构化 JSON。零信任设计：<strong>没有一个字节能绕过鉴权和审计。</strong></p>
+
+```bash
+# 安装（macOS / Linux）
+curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh
+
+# 你的 Agent（或你自己）现在就能这样用：
+dws contact user search --query "张伟"              # 找到一个人
+dws calendar event list                            # 看日程安排
+dws aisearch person --query "谁负责支付系统"        # 按职责找负责人
+```
 
 <details>
 <summary><strong>目录</strong></summary>
@@ -152,6 +161,11 @@ dws upgrade -y                 # 跳过确认直接升级
 
 ## 开始使用
 
+> [!IMPORTANT]
+> **共创阶段**：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。欢迎加入钉钉 DWS 共创群获取支持与最新动态。
+>
+> <img src="https://img.alicdn.com/imgextra/i1/O1CN01WJyAsJ1prD2ovQACM_!!6000000005413-2-tps-718-720.png" alt="dws 开源沟通群二维码" width="150">
+
 ```bash
 dws auth login            # 自动唤起浏览器
 dws auth login --device   # 无浏览器环境（Docker、SSH、CI）

diff --git a/docs/assets/dws-demo.gif b/docs/assets/dws-demo.gif
diff --git a/docs/assets/dws-demo.tape b/docs/assets/dws-demo.tape
@@ -0,0 +1,53 @@
+# dws demo GIF — reproducible via VHS (https://github.com/charmbracelet/vhs)
+#   vhs docs/assets/dws-demo.tape
+# No PII / no side effects: only --dry-run, which previews the request without executing.
+
+Output docs/assets/dws-demo.gif
+
+Set Shell bash
+Set FontSize 20
+Set Width 1280
+Set Height 460
+Set Padding 25
+Set Margin 16
+Set MarginFill "#0d0e14"
+Set BorderRadius 10
+Set WindowBar Colorful
+Set Theme "TokyoNight"
+Set TypingSpeed 32ms
+
+# Themed prompt, set off-camera
+Hide
+Type "export PS1='\[\e[32m\]dws \[\e[36m\]❯\[\e[0m\] '"
+Enter
+Type "clear"
+Enter
+Show
+
+Sleep 400ms
+
+# 1) Resolve a person — the exact tool call is shown transparently, nothing executed
+Type "dws contact user search --query 'Wei Zhang' --dry-run --jq '{tool:.invocation.tool, args:.invocation.params}'"
+Sleep 500ms
+Enter
+Sleep 1700ms
+
+Type "clear"
+Enter
+Sleep 400ms
+
+# 2) Find who owns an area
+Type "dws aisearch person --query 'who owns payments' --dry-run --jq '{tool:.invocation.tool, args:.invocation.params}'"
+Sleep 500ms
+Enter
+Sleep 1700ms
+
+Type "clear"
+Enter
+Sleep 400ms
+
+# 3) The pitch — numbers match the README
+Type "echo '18 products · 330 commands · structured JSON for AI agents · zero-trust'"
+Sleep 500ms
+Enter
+Sleep 2300ms