# 文档索引

本目录承载**决策留痕、实测记录、专题手册**。根目录的 README 讲"怎么用"，这里讲"为什么这样做、当时验证了什么"。

---

## 目录结构

```
docs/
├── 安装与前置条件.md          ★ 最先读这篇：Node / dws / 钉钉侧授权三层依赖
├── 发布与版本管理.md           怎么传上 GitHub / 加功能后怎么升版本发布
├── adr/                        架构决策记录（ADR）—— 为什么这样设计
│   └── 0001-从手搓REST改为包装dws.md
├── 实测/                       逐次真机验证留痕 —— 当时到底测出了什么
│   └── 2026-09-14-钉钉AI表格实测记录.md
└── images/                     截图与示意图
    └── README.md               ⚠️ 待补截图清单
```

---

## 按问题找文档

| 你想知道 | 去看 |
|---|---|
| 装了插件但工具报错 / 403 / 查不到表 | [安装与前置条件.md](./安装与前置条件.md) |
| 怎么把插件传上 GitHub？加功能后怎么升版本、怎么发布？ | [发布与版本管理.md](./发布与版本管理.md) |
| 什么改动该升 major，什么该升 minor？ | [发布与版本管理.md](./发布与版本管理.md) 2.1 |
| 为什么这插件要包装 `dws` 而不是直连 REST？ | [adr/0001](./adr/0001-从手搓REST改为包装dws.md) |
| 为什么记录写入的 `cells` key 必须是 `fieldId`？ | [adr/0001](./adr/0001-从手搓REST改为包装dws.md) |
| 为什么定时任务在 DSH 关着时不跑？ | [实测记录](./实测/2026-09-14-钉钉AI表格实测记录.md) 5.3 |
| 为什么"列出全部 Base"做不到？ | [实测记录](./实测/2026-09-14-钉钉AI表格实测记录.md) 4.5 |
| 扫码绑定时为什么不弹二维码？ | [实测记录](./实测/2026-09-14-钉钉AI表格实测记录.md) 4.2 |
| 术语该怎么叫、哪些说法禁用？ | [../CONTEXT.md](../CONTEXT.md) |
| 每个版本改了什么？ | [../CHANGELOG.md](../CHANGELOG.md) |

---

## 写作约定

本仓库文档遵守三条约定，与 [CONTEXT.md](../CONTEXT.md) 的术语表一致：

1. **每条技术结论标明来源档位**：**官方原文** / **实测** / **推测**。推测可以写，但必须显式标注。
2. **禁用模糊措辞**："一般来说""应该是""我记得" 一律不用。
3. **已知限制明示，不掩饰**。例如定时器的进程内语义、`base search` 的 `hasMore` 误报，
   都在文档里直接写明，而不是等使用者踩坑。

> 为什么这么较真：本插件有几个概念**用一个词就会被误解**（例如"定时任务"其实不是云端定时），
> 误解会直接导致使用者按错误预期排故障。措辞精度在这里是功能，不是文风。