# 文档与表格

钉钉把「文档类」拆成了五个独立产品，**分不清就会用错命令**。这是助手最重要的边界判断之一。

## 五个产品的分界

| 产品 | 对应什么 | 命令前缀 |
| --- | --- | --- |
| 在线文字文档（adoc） | 正文、块、评论、导入导出、模板、版本 | `dws doc` |
| 在线电子表格（axls） | 单元格读写、工作表、区域、图表 | `dws sheet` |
| AI 表格 / 多维表（able） | Base、数据表、字段、记录、视图、仪表盘 | `dws aitable` |
| 知识库空间与节点 | 空间管理、节点层级、成员权限 | `dws wiki` |
| 钉盘 / 文档空间的**文件管理** | 查找、上传下载、移动、权限、回收站 | `dws drive` |
| 原生 `.md` 文件 | 创建、读取、覆盖、局部修补 | `dws markdown`（归 misc） |

### 怎么判断该走哪个

助手用两层判据：

1. **看 URL 路径模式和 token，不看域名。** 钉钉文档链接的路径段决定类型
2. 没有链接时问自己：**「换个文件类型这个操作还成立吗？」**
   - 成立 → **存储层**（走 `drive`）。移动、复制、改名、删除、权限、回收站对任何文件都成立
   - 不成立 → **内容层**（走 `doc` / `sheet` / `aitable`）。编辑正文、读单元格、加字段只对特定类型成立

## 实际用法

### 找文档

```
帮我找一下标题带「测试」的钉钉文档
```

真机实测助手的三步（用例 d1）：

```bash
dws doc +search --query '测试' --format json
dws schema --cli-path 'doc +search' --compact --format json
dws doc +search --query '测试' --page-all --max-pages 20 --max-items 500 --format json
```

第一次拿到结果后，它查了 schema 确认分页参数，再带上分页上限重查——因为**只有确认分页真的走到底，才能说「全部」**。

### AI 多维表

```
我有哪些 AI 多维表？
```

```bash
dws schema --cli-path "aitable base list" --compact --format json
dws aitable base list --limit 10 --format json
```

组织内没有 Base 时返回：

```json
{ "data": { "bases": [] }, "error": {}, "status": "success", "success": true }
```

⚠️ **注意 `"error": {}` 是空对象**——这是成功响应的正常形态，**不是错误**。判据必须是 `ok === false` 或 `error` 是**非空对象**。用 `grep '"error"'` 判失败会把这条误判成报错（我在写测试脚本时就踩过这个坑）。

### 导出表格

```
把那个在线表格导出成 xlsx
```

```bash
dws sheet export        # 异步任务一站式：提交 → 轮询 → 可选下载
dws sheet export-csv    # 单个工作表导出 CSV，同步，可落盘
```

> **官方文档纠错**：`url-patterns.md` 说 xlsx 导出「暂未暴露」，这是**错的**（或已过时）。实测 `dws sheet --help` 里 `export` 与 `export-csv` 都存在。

## 常见误判

| 你说 | 容易被误判成 | 实际该走 |
| --- | --- | --- |
| 「把文档移到某个文件夹」 | doc | **drive**（移动是存储操作） |
| 「给文档加个协作者」 | drive | **doc**（`+access-grant`，权限属内容层协作） |
| 「在多维表里加一列」 | sheet | **aitable**（多维表 ≠ 电子表格） |
| 「读取表格 A1 单元格」 | aitable | **sheet**（单元格是电子表格概念） |
| 「我最近编辑过哪些文件」 | ❌ 写操作 | **查询**（疑问句里的「编辑过」是筛选条件） |

最后一条是真机测出来的实际缺陷，已写进助手的判断规则。
