# 安装与前置条件

> 本文档回答一个问题：**要让本插件完整跑起来，你必须在钉钉侧和本机侧分别准备什么。**
>
> 结论先行——**三步缺一不可**：① 本机 Node ≥ 16.7.0 → ② 本机装 `dws` → ③ 钉钉侧授权 + 开权限。
> 第 ③ 步第二项（把应用加为 Base 协作者）**极易漏，漏了必 403**。

**标注约定**：本文每条技术结论标明来源档位，与 [CONTEXT.md](../CONTEXT.md) 一致。

| 档位 | 含义 |
|---|---|
| **官方原文** | 直接从 dws 包元数据 / 源码 / 官方错误码文档读到的 |
| **实测** | 在本机（Windows + dws v1.0.61）实际跑通或踩到并确认的 |
| **推测** | 有依据但未经实测确认的 |

---

## 一、总览：三层依赖

```
┌─ 第 1 层  本机运行时 ──────────────────────────────────────┐
│  Node.js ≥ 16.7.0            （官方原文：dws 的 engines）   │
│  DSH ≥ 0.1.2-alpha.4         （本插件 dsh.compatibility）   │
└───────────────────────────────────────────────────────────┘
                          ↓ 必须
┌─ 第 2 层  dws CLI ─────────────────────────────────────────┐
│  npm i -g dingtalk-workspace-cli                           │
│  postinstall 下载平台原生二进制 → vendor/dws(.exe)          │
│  版本须 ≥ 1.0.6（本插件实测基线 v1.0.61）                    │
└───────────────────────────────────────────────────────────┘
                          ↓ 必须
┌─ 第 3 层  钉钉侧授权与权限 ─────────────────────────────────┐
│  ① dws auth login（设备流）或 DWS_CLIENT_ID/SECRET          │
│  ② 开发者后台开通「AI 表格记录读写」权限并发布               │
│  ③ 目标 Base 把应用加为协作者（可编辑）★最易漏              │
│  ④（若被拦）组织主管理员开启「允许成员通过 CLI 访问个人数据」 │
└───────────────────────────────────────────────────────────┘
```

---

## 二、第 1 层：本机运行时

### 2.1 Node.js ≥ 16.7.0

**官方原文**：`dingtalk-workspace-cli` 的 `package.json` 声明 `"engines": { "node": ">=16.7.0" }`。

```sh
node --version     # 需 >= 16.7.0
```

> 本插件自身要求 **Node ≥ 22.19**（`package.json` 的 `engines`）。
> 二者取高——**实际门槛是 22.19**，Node 16.7 只是 dws 自己的下限。

### 2.2 DeepSeek Harness 版本

**官方原文**（本插件 `package.json` 的 `dsh.compatibility`）：

```
0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.3-alpha.1 || 0.1.5-alpha.1
profiles: web
```

超出此范围不保证可用。

---

## 三、第 2 层：安装 dws（**本插件的前置依赖，不装则所有工具报错**）

### 3.1 这是什么

| 项 | 值 | 来源 |
|---|---|---|
| npm 包名 | `dingtalk-workspace-cli` | 官方原文 |
| 可执行名 | `dws` | 官方原文（`bin.dws`） |
| 维护方 | **open-dingtalk**（钉钉官方 GitHub 组织） | 官方原文 |
| 仓库 | <https://github.com/open-dingtalk/dingtalk-workspace-cli> | 官方原文 |
| 许可 | **Apache-2.0** | 官方原文 |
| 当前 latest | **1.0.61**（beta 通道 1.0.62-beta.8） | 官方原文（npm registry） |

> **为什么本插件要包装 dws 而不是直连 REST**：钉钉官方 OpenClaw connector 自己也不直连 REST，
> 而是注入 `DWS_CLIENT_ID/SECRET` 后调用 dws（实测，2026-09-14 直读其仓库确认）。
> 包装官方 CLI 消除了端点不确定性，鉴权 / 分页 / 错误码交由官方维护。

### 3.2 安装命令

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

**⚠️ 这不是一个纯 JS 包**——它有 `postinstall` 钩子（`node install.js`），会在安装时**下载并解压一个平台原生二进制**。因此：

| 要求 | 说明 |
|---|---|
| 网络 | 安装时能访问下载源（npm + 二进制托管） |
| 磁盘 | 解压后约 **25 MB**（npm registry 报 `unpackedSize ≈ 24.9 MB`） |
| 解压工具 | Windows 用 `powershell.exe Expand-Archive`（系统自带）；macOS/Linux 用 `tar -xzf` 或 `unzip` |

**官方原文**——支持的平台矩阵（读自 dws `install.js` 的 `PLATFORM_MAP`）：

| 平台 | 下载的产物 |
|---|---|
| macOS x64 | `dws-darwin-amd64.tar.gz` |
| macOS Apple Silicon | `dws-darwin-arm64.tar.gz` |
| Linux x64 | `dws-linux-amd64.tar.gz` |
| Linux arm64 | `dws-linux-arm64.tar.gz` |
| Windows x64 | `dws-windows-amd64.zip` |
| Windows arm64 | `dws-windows-arm64.zip` |

解压后的二进制落在包的 `vendor/` 目录：Windows 为 `vendor/dws.exe`，其他平台为 `vendor/dws`。

### 3.3 校验安装结果

```sh
dws --version      # 期望输出形如：dws version v1.0.61 (50eb73a0, ...)
```

**实测**：本机输出 `dws version v1.0.61 (50eb73a0, 2026-08-31T14:46:17Z)`。

**版本门槛**：本插件要求 **dws ≥ 1.0.6**。低于此版本命令面不完整，`dws aitable` 子命令可能缺失。

```sh
dws aitable --help     # 应能列出 base / table / field / record 等子命令
```

### 3.4 dws 还会做什么（可能影响你的机器）

**官方原文**（读自 `install.js`）：安装时除了装二进制，dws 还会把一套 Agent Skills 发布到：

```
~/.agents/skills/dws          ← 统一安装位置（canonical）
```

并自动检测本机已安装的 Agent（内置一份 76 项的 Agent 目录表，覆盖 Claude Code、Cursor、Codex、OpenClaw 等），
在各自的 skills 目录下建**符号链接**指回 canonical 位置。

> 影响：它会**写入你的家目录**。若你希望 skills 落到别处，可设环境变量 `DWS_CONFIG_DIR` 覆盖状态目录。
> 旧版本遗留的 skills 副本会被**备份**到 `~/.dws/skill-backups/`（保留最近 5 份，非直接删除）。

### 3.5 手动定位 dws 入口（Windows 强烈建议）

插件配置项 `dwsEntry` 需要 dws 的 **JS 入口**绝对路径：

```sh
npm root -g                                    # 先确认全局前缀
```

按下面形状拼：

```
Windows:      <npm root -g>\dingtalk-workspace-cli\bin\dws.js
macOS/Linux:  <npm root -g>/dingtalk-workspace-cli/bin/dws.js
```

**为什么 Windows 上建议设它**：`.cmd` 必须经 shell 启动，而 shell 会解释参数里的元字符
（引号 / `&` / `|`）。**实测**：设了 `dwsEntry` 后插件用 `node` 直接 spawn，**完全不走 shell**，
记录文本任意字符均安全；不设则有硬校验，含元字符的记录文本会被拒绝（返回 `ARG_UNSAFE`）。

---

## 四、第 3 层：授权与权限（**这一层最容易卡住**）

### 4.1 授权：两种方式二选一

#### 方式 A — 设备流登录（交互式，适合个人）

```sh
dws auth login           # 钉钉 App 扫码授权
dws auth status          # 确认已登录
```

**实测两条必须知道的事实**：

1. **dws 不输出二维码**。它只给一条带 `user_code` 的深链：
   ```
   link: https://login.dingtalk.com/oauth2/device/verify.htm
   authorization code: QMQK-PTMB
   Or open the following link:
     https://login.dingtalk.com/oauth2/device/verify.htm?user_code=QMQK-PTMB
   ```
   本插件的设置面板**自己用本地 `qrcode` 包画二维码**，**绝不调用第三方二维码服务**——认证链接不外发。

2. **本机已登录钉钉时，设备流可能「无需扫码」直接完成**。这不是"系统自动批准"，
   而是本机处于钉钉登录态，设备流可直接选定对应账号与组织。**推论**：在已登录的机器上点「扫码绑定」
   可能不弹码即完成，但它用的是**本机当前选定**的账号/组织，不是让你重新挑一个。

**Token 生命周期**：access token 2 小时自动刷新，refresh token 30 天。

#### 方式 B — 应用凭证（headless / 服务器推荐）

```sh
# Windows
set DWS_CLIENT_ID=<你的 Client ID>
set DWS_CLIENT_SECRET=<你的 Client Secret>
# macOS / Linux
export DWS_CLIENT_ID=<你的 Client ID>
export DWS_CLIENT_SECRET=<你的 Client Secret>

dws auth login
```

**凭证优先级**（官方原文）：`--token` > `DWS_CLIENT_ID/SECRET` > OAuth 加密存储。

> **安全要点**：本插件**只走环境变量**把凭证注入 dws 子进程，**不进命令行参数**
> （避免出现在进程列表里）。`cordis.patch.yml` 中**绝不写 Client Secret**。

### 4.2 ⛔ 组织级拦阻（最常被误判为"技术故障"）

新登录可能走到 Step 4 被拦下：

```
CLI data access is not enabled for this organization
The organization admin has not enabled "Allow members to access their personal data via CLI".
```

**来源**：实测（本插件记录，2026-09-14）。

**处理**：需**组织主管理员**在钉钉开放平台 → 开发者设置 → 开启
「允许成员通过 CLI 访问个人数据」后重新登录。

> **这是组织管理动作，不是技术配置。** 未解决前，"多账号"实际只能绑到 1 个账号。
>
> **实测补充**：现有登录在此开关未开的情况下**仍可用**（`auth status` 有效、数据可读）。
> 新登录被拦而旧会话可用——原因尚未查明（**推测**：旧会话持的是开关开启前签发的长期凭证）。
> 建议由管理员核对该开关的真实状态。

### 4.3 应用权限（钉钉开发者后台）

1. **钉钉开发者后台** → 该应用 → **权限管理** → 开通 **AI 表格（多维表）记录读写** 权限
2. **发布**使权限生效

### 4.4 ★ Base 协作者（**漏了必 403**）

**目标 Base** → 右上角「协作 / 分享」→ 把该应用加为协作者，权限给到 **可编辑**。

> 4.3 与 4.4 **缺一不可**。出现 `permission denied` / 403 时，九成是这两件没做完。
>
> **判定方式**：本插件不解析角色权限模型，而是**跑一次 `base get` 做可读性实测**——
> 成功即可读，失败则记录真实原因。`dingtalk_aitable_scan` 与设置面板都基于此。

### 4.5 受控渠道组织（如阿里巴巴）

**官方原文**（dws `references/channel-login.md`）：若目标组织是阿里巴巴，或登录返回
`CHANNEL_REQUIRED` / `channel_not_allowed` / `enterprise_not_authorized` / "应用暂不受信任"，
则需要 `DWS_CHANNEL` 渠道码：

- `DWS_CHANNEL` = 产品/分发渠道 `channelCode`（CLI 在登录与后续请求中作为 `x-dws-channel` 发送）
- `DINGTALK_DWS_AGENTCODE` = 执行 Agent 身份
- 两者是**独立维度，禁止互相回填或复用**
- 只在与真实宿主/业务场景匹配时使用；**禁止为通过登录随机尝试其他渠道**

---

## 五、一次性核验清单（照这个跑，跑通即环境就绪）

```sh
# ── 第 1 层 ──
node --version                                  # ≥ 22.19

# ── 第 2 层 ──
npm i -g dingtalk-workspace-cli
dws --version                                   # ≥ 1.0.6，期望 v1.0.61
npm root -g                                     # 记下前缀，用于填 dwsEntry

# ── 第 3 层 ──
dws auth status                                 # 或先 dws auth login
dws profile list --format json                  # 应列出至少一个 profile

# ── 端到端冒烟（最小只读命令）──
dws aitable base search --query "测试" --format json
```

最后一步若是 403 / permission denied → 回 4.3 + 4.4。
若是 `CLI data access is not enabled...` → 回 4.2。

**装完插件后**，在 DSH 里跑一次自检工具：

```
dingtalk_aitable_diagnose
```

它会一次性回报 **dws 版本 / 授权状态 / 已注册命令 / RPC 端点是否挂上**，是排障的第一入口。
其中 `rpcEndpoint.registered: true` 才说明设置面板的 RPC 端点可用。

---

## 六、常见安装失败对照

| 症状 | 原因 | 处理 |
|---|---|---|
| `npm i -g` 报 postinstall 失败 | 网络不通 / tar/unzip 缺失 | 检查网络；Windows 确认 `powershell.exe` 可用；macOS/Linux 装 `unzip` |
| `dws: command not found` | npm 全局 bin 不在 PATH | 把 `npm root -g` 对应 bin 目录加入 PATH |
| `dws --version` 低于 1.0.6 | 装到了旧版 | `npm i -g dingtalk-workspace-cli@latest` |
| `dws aitable` 子命令不存在 | 版本过旧 | 同上 |
| `command not found: dws`（插件内） | 插件找不到 dws | 配 `dwsEntry` 指向 `bin/dws.js` 绝对路径 |
| `请先执行 dws login` | 未授权 | `dws auth login` |
| `AUTH_TOKEN_EXPIRED` / `USER_TOKEN_ILLEGAL` | token 过期 | 重新 `dws auth login` |
| `permission denied` / 403 | 权限不足 | 4.3 + 4.4 |
| `CLI data access is not enabled...` | 组织开关未开 | 4.2，需组织主管理员 |
| `CHANNEL_REQUIRED` / `enterprise_not_authorized` | 受控渠道组织 | 4.5，设 `DWS_CHANNEL` |
| `ARG_UNSAFE` | 参数含 shell 元字符 | 配 `dwsEntry` 走无 shell 模式 |

---

## 七、卸载

```sh
dsh plugin --profile web remove @yiyunet/dsh-dingtalk-connector   # 卸插件
npm uninstall -g dingtalk-workspace-cli                           # 卸 dws
dws auth logout                                                   # 清授权（不传 --profile 则退全部账号）
```

> dws 卸载后 `~/.agents/skills/dws` 与 `~/.dws/` 可能残留，按需手动清理。

---

## 附：来源索引

| 来源 | 用途 |
|---|---|
| npm registry `dingtalk-workspace-cli` 元数据 | 包名 / 版本 / License / engines / postinstall |
| dws `package.json`（本地 v1.0.61） | engines 精确值 `>=16.7.0`、bin 路径 |
| dws `install.js` | 平台矩阵 `PLATFORM_MAP`、解压方式、skills 落点 |
| dws `share/skills/mono/references/error-codes.md` | 错误码语义 |
| dws `share/skills/mono/references/channel-login.md` | 受控渠道契约 |
| 本插件实测记录 | 组织拦阻、设备流行为、token 生命周期 |

---

**本插件的实时版本与更新**：见 [CHANGELOG.md](../CHANGELOG.md)。
**术语与禁用说法**：见 [CONTEXT.md](../CONTEXT.md)。