# 使用说明

把自然语言意图翻译成钉钉官方 CLI（`dws`）的正确调用，并对结果负责。覆盖通讯录、群聊消息、
日程会议、待办、审批、考勤、日志、文档、表格、AI 多维表、钉盘、知识库、邮件、AI 听记、DING、
实时事件等钉钉产品域。

**它不是钉钉命令的说明书。** 命令目录由钉钉官方技能与 `dws schema` 提供，随二进制升级而更新。
本 Agent 做的是官方技能不覆盖的四件事：

| 增量 | 说明 |
| --- | --- |
| **接入** | 钉钉官方 CLI 的 Agent 分发列表里没有 DesireCore，装到 DesireCore 的路径无人覆盖 |
| **纪律** | 钉钉 CLI 有 339 个「自己不拦」的写操作（占全部写操作 56%），由本 Agent 把关 |
| **编排** | 跨产品工作流；官方 SKILL.md 明写「定时调度由外层工作流负责」 |
| **降级** | 没装 / 没授权 / 没权限 / 没开通时如实停下，绝不编造成功 |

---

## 装之前必须知道

本 Agent 依赖一个**由第三方独立分发**的命令行程序。DesireCore 不打包、不分发、不授权、
不安装、不代付、不运营该程序及其背后的钉钉产品。凭据与费用由你与钉钉之间的服务条款约束。

装完本 Agent 还**不能直接用**，必须自行完成下面 5 步。

---

## 快速开始

### 1. 安装钉钉官方 CLI

```bash
npm i -g dingtalk-workspace-cli
```

⚠️ 这一步会顺带往你机器上**其它 AI 编程工具的技能目录**写入钉钉技能
（`~/.claude/skills/`、`~/.cursor/skills/` 等，共 80+ 个框架）。这是上游 `dws` 的
postinstall 行为，不是 DesireCore 做的。

### 2. 把官方产品技能装进 DesireCore

装完 CLI 后技能已解包在 `~/.dws/skills/multi/`，拷进 DesireCore 全局技能目录：

```bash
DC_ROOT="${DESIRECORE_TEST_ROOT:-${DESIRECORE_HOME:-$HOME/.desirecore}}"
mkdir -p "$DC_ROOT/skills"
cp -R ~/.dws/skills/multi/dingtalk-* "$DC_ROOT/skills/"
```

共 14 个：`aisearch` `aitable` `calendar` `chat` `contact` `doc` `drive` `event`
`mail` `minutes` `misc` `shared` `todo` `wiki`。

> **为什么不走市场安装**：市场里有 `dingtalk-cli` 条目，但钉钉官方仓库未公开（HTTP 404），
> 客户端按 git 源拉不到内容。该条目的作用是让你在市场里发现这个能力并看到装法，不是分发通道。
>
> **代价**：这样装的技能没有 provenance 记录，市场同步视为孤儿——既不自动更新也不自动卸载。
> **每次 `dws upgrade` 后要重跑一次上面的拷贝。**

### 3. 授权

```bash
dws auth login              # 本机有浏览器
dws auth login --device     # 无浏览器 / SSH / 容器，出设备码
```

⚠️ **钉钉不支持账号密码登录**，也不支持手机验证码、纯应用凭证。只有 OAuth 回环、设备流、
`--token`、自有应用 OAuth 四种。

授权成功后 access token 约 2 小时、refresh token 约 30 天自动刷新，之后无需再打扰。

### 4. 把 `dws` 加进命令白名单（强烈建议）

实测每条 `dws` 命令都会被判**高风险**并弹审批卡片——18 个测试用例里 34 次 Bash 调用触发了
**41 次审批**。不加白名单的话你要不停点确认。

点输入框左下角的审批模式胶囊即可切换。六种模式的取舍：

| 模式 | 行为 | 适合 |
| --- | --- | --- |
| **AI 审批**（默认） | 前台保留 30 秒真人抢先窗口，AI 建议到达即收敛 | 日常，但**需要配好审批 chat 模型** |
| 完全 AI 审批 | AI 建议到达立即决策 | 无人值守 |
| 仅 AI 建议 | AI 只提供参考，永不自动决策，无截止时间等待真人 | 高风险场景 |
| 每次确认 | 每次执行命令都要你审批 | 最保守 |
| **白名单** | 仅白名单中的命令可自动执行 | **推荐**：把 `dws` 加进去 |
| 外部工具审批 | 交给外部系统裁决 | 有审批中台时 |

⚠️ **默认的「AI 审批」需要一个可用的审批 chat 模型。** 没配的话所有命令会被 fail-closed
拦掉，报「AI 审批后端不可用，命令未执行」——连本 Agent 自己写计划文件都会被拦。要么去
资源管理面板 → 算力配一个 chat 模型，要么换成「白名单」或「每次确认」。

### 5. 自检

```bash
dws doctor
```

四项：登录状态 / 钥匙串 / 网络连通性 / 版本更新。

---

## 安全边界

本 Agent 继承钉钉官方的执行契约，并补了 DesireCore 侧的一层：

- **只走 `dws`**，不用 curl、不自拼 HTTP
- **不编造标识符**——userId / docId / baseId 一律从命令返回中提取
- **写操作先确认**，判据是 `effect == destructive || risk == high || confirmation == user_required`
  三元组兜底（不能只看 `confirmation` 字段：1256 个工具里有 339 个是 `dws` 自己不拦的 silent-write）
- **单次批量 ≤ 30 条**
- **多候选禁止默认取第一个**；多组织时解析、读取、执行必须用同一个 profile
- **退出码不等于成功**——只有 `data.complete=true` 才能说「全部」，响应里缺少集合不能当空结果
- **禁止轮询**消息历史或审批列表，实时需求走长连接

---

## 已知边界

| 限制 | 说明 |
| --- | --- |
| 视频会议 | **CLI 无入口**。会前（排日程订会议室）与会后（纪要/逐字稿/行动项）可用，会中控制需在钉钉客户端操作 |
| 消息搜索 | 需要**消息搜索权益**，未开通时返回 `SearchRightsDenied`。其余 chat 能力（发消息、群管理、机器人）不受影响 |
| 组织权限 | 能力覆盖取决于 OAuth 授权范围与你所在组织开通的产品，本 Agent 会在受限时如实说明 |

---

## 更详细的功能文档

按产品域的能力覆盖、边界与权益门槛，随 Agent 一起安装在私有技能
`dingtalk-guide` 的 `references/` 目录下（通讯录、群聊、日程、待办审批、文档表格、
钉盘知识库、邮件、AI 听记、考勤日志、实时事件、跨产品工作流、界面与审批、故障排查共 13 篇）。
装好后直接问本 Agent「钉盘同步怎么用」这类问题即可，它会自己去读对应文档再回答。