From dbfd785af3aaf45d866a50ed495cbb132fdec27c Mon Sep 17 00:00:00 2001 From: audanye-sudo Date: Sun, 29 Mar 2026 16:48:21 +0800 Subject: [PATCH] docs: add Chinese README (README_zh.md) --- README_zh.md | 367 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 367 insertions(+) create mode 100644 README_zh.md diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 00000000..a02982a8 --- /dev/null +++ b/README_zh.md @@ -0,0 +1,367 @@ +

DingTalk Workspace CLI (dws)

+ +

dws — 钉钉工作台命令行工具，为人类和 AI Agent 而生。

+ +

+ DWS Product Overview +

+ +

+ Go 1.25+ + License Apache-2.0 + v1.1.0 + CI + Coverage +

+ +

+ 中文版 · English · 参考手册 · 更新日志 +

+ +> [!IMPORTANT] +> **共创阶段**：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。当前为灰度共创阶段，请加入钉钉 DWS 共创群完成白名单配置。详见下方 [开始使用](#开始使用)。 +> +> DingTalk Group QR Code + +
+目录 + +- [为什么选择 dws？](#why-dws) +- [安装](#安装) +- [开始使用](#开始使用) +- [快速开始](#快速开始) +- [在 Agent 中使用](#在-agent-中使用) +- [新功能](#新功能) +- [核心服务](#核心服务) +- [安全设计](#安全设计) +- [AI Agent Skills](#ai-agent-skills) +- [参考与文档](#参考与文档) +- [贡献指南](#贡献指南) + +
+ +--- + +

为什么选择 dws？

+ +- **为人类而设计** — `--help` 查看用法，`--dry-run` 预览请求，`-f table/json/raw` 切换格式。 +- **为 AI Agent 而设计** — 结构化 JSON 响应 + 内置 Agent Skills，开箱即用。 +- **为企业管理员而设计** — 零信任架构：OAuth 设备流认证 + 域名白名单 + 权限最小化。**没有一个字节能绕过安全鉴权和审计。** + +## 安装 + +**macOS / Linux：** + +```bash +curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh +``` + +**Windows（PowerShell）：** + +```powershell +irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex +``` + +
+其他安装方式 + +**预编译二进制文件**：从 [GitHub Releases](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases) 下载。 + +**从源码构建**： + +```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/ # 安装到 PATH +``` + +> 需要 Go 1.25+。也可以用 `make package` 构建所有平台产物（macOS / Linux / Windows × amd64 / arm64）。 + +
+ +## 开始使用 + +### 步骤 1：创建钉钉应用 + +进入 [开放平台应用开发后台](https://open-dev.dingtalk.com/fe/app?hash=%23%2Fcorp%2Fapp#/corp/app)，在「企业内部应用 - 钉钉应用」点击**创建应用**。 + +
+查看截图 +

+ 创建应用 +

+
+ +### 步骤 2：配置重定向 URL + +进入应用 → **安全设置**，在「重定向 URL」中添加以下地址并保存： + +``` +http://127.0.0.1 +https://login.dingtalk.com +``` + +> `http://127.0.0.1` 用于本地浏览器登录；`https://login.dingtalk.com` 用于 `--device` 设备流登录（Docker 容器、远程服务器等无浏览器环境）。建议两个都配置。 + +
+查看截图 +

+ 配置重定向URL +

+
+ +### 步骤 3：发布应用 + +点击「应用发布 - 版本管理与发布」，发布版本使应用上线。 + +
+查看截图 +

+ 发布应用 +

+
+ +### 步骤 4：申请白名单 + +加入钉钉 DWS 共创群，提供 **Client ID** 和**管理员确认凭证**完成白名单配置。 + +### 步骤 5：登录认证 + +```bash +dws auth login --client-id --client-secret +``` + +或通过环境变量： + +```bash +export DWS_CLIENT_ID= +export DWS_CLIENT_SECRET= +dws auth login +``` + +> CLI 参数优先于环境变量。凭证用于钉钉 OAuth 设备流认证。 + +## 快速开始 + +```bash +dws contact user search --keyword "悟空" # 搜索联系人 +dws calendar event list # 查看日历日程 +dws todo task create --title "季度汇报" --executors "" # 创建待办 +dws todo task list --dry-run # 预览操作但不执行 +``` + +## 在 Agent 中使用 + +dws 是为 AI Agent 设计的 CLI 工具。以下是接入指南。 + +### 1. 环境配置 + +```bash +# 安装 dws +curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh + +# 通过环境变量配置认证（Agent 推荐方式，无需交互式登录） +export DWS_CLIENT_ID= +export DWS_CLIENT_SECRET= +dws auth login +``` + +### 2. Agent 调用模式 + +```bash +# 使用 --yes 跳过确认提示（Agent 必须） +dws todo task create --title "Review PR" --yes + +# 使用 --dry-run 预览操作（安全执行） +dws contact user search --keyword "test" --dry-run + +# 使用 --jq 精确提取（节省 token） +dws contact user search --keyword "test" --jq '.response.content' + +# 使用 --fields 只返回需要的字段 +dws calendar event list --fields response +``` + +### 3. Schema 发现（Agent 自主探索） + +Agent 无需预置所有命令知识，通过 `dws schema` 动态发现可用能力： + +```bash +# 第一步：发现所有可用产品 +dws schema --jq '.products[] | {id, tool_count: (.tools | length)}' + +# 第二步：查看目标工具的参数结构 +dws schema aitable.query_records --jq '.tool.input_schema' + +# 第三步：构造正确的调用 +dws aitable record query --base-id "xxx" --table-id "yyy" --limit 10 +``` + +### 4. 错误容忍 + +dws 的智能纠错引擎对 Agent 生成的常见错误有高容忍度： + +| Agent 输出 | dws 自动纠正为 | +|-----------|--------------| +| `--userId` | `--user-id` | +| `--limit100` | `--limit 100` | +| `--tabel-id` | `--table-id` | +| `--USER-ID` | `--user-id` | +| `--user_name` | `--user-name` | + +### 5. Agent Skill 集成 + +安装 Agent Skills 后，Claude Code / Cursor 等工具可直接使用钉钉能力： + +```bash +# 安装 skills 到当前项目 +curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh +``` + +> 详见 [AI Agent Skills](#ai-agent-skills) 章节。 + +## 新功能 + +### 智能输入纠错 + +dws 内置 Pipeline 纠错引擎，自动修正 AI 模型常见的参数错误，无需人工干预： + +```bash +# 命名风格自动转换 (camelCase / snake_case / UPPER → kebab-case) +dws aitable record query --baseId x --tableId y # 自动纠正为 --base-id --table-id + +# 粘连参数自动拆分 +dws contact user search --keyword "test" --timeout30 # 自动拆分为 --timeout 30 + +# 拼写错误模糊匹配 +dws aitable record query --base-id x --tabel-id y # --tabel-id → --table-id + +# 参数值归一化 (布尔 / 数字 / 日期 / 枚举) +# "yes" → true, "1,000" → 1000, "2024/03/29" → "2024-03-29", "ACTIVE" → "active" +``` + +### JSON 字段筛选 & jq 过滤 + +精确控制输出内容，减少 token 消耗： + +```bash +# 只返回指定字段 +dws aitable record query --base-id x --table-id y --fields invocation,response + +# 内置 jq 表达式 +dws aitable record query --base-id x --table-id y --jq '.invocation.params' +dws schema --jq '.products[] | {id, tools: (.tools | length)}' +``` + +### Schema 自省 + +Agent 可以在调用前查询任何工具的参数结构： + +```bash +dws schema # 列出所有产品和工具 +dws schema aitable.query_records # 查看参数 Schema +dws schema aitable.query_records --jq '.tool.input_schema.required' # 查看必填字段 +dws schema --jq '.products[].id' # 提取所有产品 ID +``` + +## 核心服务 + +| 服务 | 命令 | 描述 | +|---------|---------|-------------| +| 通讯录 | `contact` | 用户 / 部门 | +| 群聊 | `chat` | 群管理 / 群成员 / 机器人消息 / Webhook | +| 日历 | `calendar` | 日程 / 会议室 / 闲忙 | +| 待办 | `todo` | 任务管理 | +| 审批 | `approval` | 流程 / 表单 / 实例 | +| 考勤 | `attendance` | 打卡 / 排班 / 统计 | +| DING | `ding` | DING 消息 / 发送 / 撤回 | +| 日志 | `report` | 日志 / 模版 / 统计 | +| 智能表格 | `aitable` | AI 表格操作 | +| 工作台 | `workbench` | 应用查询 | +| 开发者文档 | `devdoc` | 开放平台文档搜索 | + +运行 `dws --help` 查看完整列表，或 `dws --help` 查看子命令。 + +
+即将推出 + +`doc`（文档）· `mail`（邮箱）· `minutes`（AI 听记）· `drive`（钉盘）· `conference`（视频会议）· `tb`（Teambition）· `aiapp`（AI 应用）· `live`（直播）· `skill`（技能市场） + +
+ +## 安全设计 + +`dws` 从架构层面将安全作为一等公民，而非事后补丁。**凭证不落盘、Token 不出域、权限不越界、操作不脱审** — 每一次 API 调用都必须经过钉钉开放平台的鉴权和审计链路，无例外。 + +
+开发者安全机制 + +| 机制 | 说明 | +|------|------| +| **Token 加密存储** | **PBKDF2（600,000 次迭代 + SHA-256）+ AES-256-GCM** 加密，密钥绑定设备物理 MAC 地址；macOS 集成系统 Keychain、Windows 集成 DPAPI 提供额外保护，跨设备无法解密 | +| **输入安全防护** | 路径遍历防护（符号链接解析 + 工作目录约束）、CRLF 注入拦截、Unicode 视觉欺骗字符过滤，防止 AI Agent 被恶意指令诱导 | +| **域名白名单** | `DWS_TRUSTED_DOMAINS` 默认仅信任 `*.dingtalk.com`，Bearer Token 不会发送到非白名单域 | +| **并发安全** | 双层锁机制（进程内 + 跨进程文件锁）保障 Token 刷新原子性，适配高并发 MCP Server 场景 | +| **数据完整性** | 所有配置写入采用原子操作（temp + fsync + rename），确保进程中断时数据不损坏 | +| **HTTPS 强制** | 除 loopback 开发调试外，所有请求强制 TLS | +| **Dry-run 预览** | `--dry-run` 展示调用参数但不执行，防止误操作生产数据 | +| **凭证零落盘** | Client ID / Secret 仅在内存中使用，不写入配置文件或日志 | + +
+ +
+企业管理员安全机制 + +| 机制 | 说明 | +|------|------| +| **OAuth 设备流认证** | 用户必须通过管理员授权的钉钉应用认证，未授权应用无法获取 Token | +| **权限最小化** | CLI 仅能调用管理员授予该应用的 API 权限范围，无法越权 | +| **白名单准入** | 共创阶段需管理员主动确认开通，后续支持自助审批 | +| **操作全链路审计** | 每一次数据读写都经过钉钉开放平台 API，企业管理员可在管理后台实时追溯完整调用日志，任何异常操作无处隐藏 | + +
+ +
+ISV / 企业服务商安全机制 + +| 机制 | 说明 | +|------|------| +| **租户数据隔离** | 以已授权应用身份调用 API，不同租户数据严格隔离 | +| **Skill 沙箱** | Agent Skills 是 Markdown 文档（`SKILL.md`），仅提供 prompt 描述，不执行任意代码 | +| **集成链路零盲区** | ISV Skill 与 dws Skill 联调时，每一次 API 调用都强制经过钉钉开放平台鉴权，完整调用链路可追溯，不存在绕过审计的旁路 | + +
+ +> 发现安全漏洞？请通过 [GitHub Security Advisories](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/security/advisories/new) 报告，详见 [SECURITY.md](./SECURITY.md)。 + +## AI Agent Skills + +仓库为每个钉钉产品提供 Agent Skill（`SKILL.md`），安装脚本会自动部署到 `~/.agents/skills/dws`。 + +```bash +# 仅安装 skills 到当前项目 +curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh +``` + +> `install.sh` 安装到 `$HOME/.agents/skills/dws`（全局）；`install-skills.sh` 安装到 `./.agents/skills/dws`（当前项目）。 + +### ISV Skill 联调 + +编写您自己的 Agent Skill，与 dws 内置 skill 搭配构建跨产品工作流：**ISV Skill → dws Skill → 钉钉开放平台 API（强制鉴权 + 全链路审计）**。 + +**示例**：CRM Skill 调用日历 Skill 为客户创建会议，再通过待办 Skill 分配跟进任务 — AI Agent 在一次对话中完成跨系统协作。 + +## 参考与文档 + +- [参考手册](./docs/reference.md) — 环境变量、退出码、输出格式、Shell 补全 +- [架构设计](./docs/architecture.md) — 发现驱动管道、IR、Transport 层 +- [更新日志](./CHANGELOG.md) — 版本历史与迁移说明 + +## 贡献指南 + +参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解构建、测试和开发工作流。 + +## 许可证 + +Apache-2.0