# 在线文档

企业微信的 **Word 类在线文档**：新建、把本地 .docx/.doc/.txt 传上去变成在线文档、读正文、
往末尾追加内容、整篇覆盖。**只管一份文档里的文字**——文档叫什么名字、谁能看，
归 [13 文档管理](13-文档管理.md)。

**注意路由**：你只说「写个文档 / 整理成文档 / 输出到文档」而**没指明类型**时，
默认落到 [12 智能文档](12-智能文档.md)，不是这里。要用这一域，得明确说「Word 文档」「在线文档」「docx」，
或者给出一个 `/doc/` 开头的文档链接。

## 你可以怎么说

> 「给我建个 Word 文档写周报」
> 「新建一个在线文档」
> 「把这份 docx 传到企微上」
> 「这份文档写了什么？」
> 「在这个文档里再加一段：今天完成了联调」
> 「把这个文档整个重写」

## 📋 验证状态

| 项 | 状态 |
|---|---|
| 创建在线文档 | ✅ **已实测** |
| 向文档末尾追加内容 | ✅ **已实测** |
| 读取文档正文 | ✅ **已实测，读回内容与写入完全一致** |
| 导入本地 .docx / .txt | ⚠️ **未实测** |
| 整篇覆盖正文 | ⚠️ **未实测**（高风险写入，未做破坏性验证） |
| 完整链路（你说一句话 → 助手自动写完） | ⚠️ 未实测 |

**实测记录**（命令层，人工在真实账号上执行）：

```
doc create           →  ✅ 建出一份在线文档
doc contents append  →  ✅ 追加成功
doc contents get     →  ✅ 读回内容与追加的内容完全一致
doc names update     →  ✅ 重命名成功（用于清理测试数据）
```

**「写 → 读」闭环成立**，这是这一域最有价值的一条实测结论。

同时印证了一件事：企业微信的四种文档在标识上有**前缀路由**——在线文档是 `w3_`、
在线表格是 `e3_`、智能表格是 `s3_`、智能文档是 `a1_`。助手就是靠这个判断你给的链接是哪种文档，
实测结果与技能里写的规则一致。

**测试数据处置**：命令行没有删除文档的接口，4 份测试文档已全部重命名为
「【可删除】DesireCore验收测试-\*」，需要在企业微信里手动删除。

**关于创建方式的一个说明**：实测确认 `doc create` **直接可用**。
但助手的默认流程走的是另一条路——**先在本地生成一份 .docx，再导入**。
原因见下方「注意事项」。两条路都记在这里，是为了让你知道助手有时候多花的那一步在做什么。

## 能力清单

| 能做什么 | 命令 | 风险 |
|---|---|---|
| 把本地文件导入成在线文档（**助手默认的新建方式**） | `wecom-cli doc import` | 低风险写入 |
| 直接新建在线文档 | `wecom-cli doc create` | 低风险写入 |
| 读取文档正文 | `wecom-cli doc contents get` | 读取 |
| 向文档末尾追加文本 | `wecom-cli doc contents append` | 低风险写入 |
| 整篇覆盖文档正文 | `wecom-cli doc contents overwrite` | **高风险写入（不可逆覆盖）** |

**搜索文档不在这里**——搜索是 [13 文档管理](13-文档管理.md) 的专属能力，四种文档类型都走那边。

## 注意事项

**「新建」有两条路，助手默认走导入那条。**

- **默认路径**：先在本地生成一份 .docx，再导入成在线文档。这样能一次带进**封面标题、多级标题、
  列表、表格、局部加粗与配色**这些排版。
- **另一条路**：直接新建。它也能带初始内容，但只能灌一段**没有结构的纯文字或 markdown**——
  你说「生成一份 Word 周报」时期待的多半不是这个。

所以你会看到助手在建文档时多花一步。内容确实是纯文本、你也没有排版要求时，
它会跳过生成 .docx，直接写个 .txt 导进去。

**文档名由文件名决定。** 导入时的文件名（含后缀）就是最终的文档标题——想让文档叫《项目周报》，
文件名就得是 `项目周报.docx`。

**默认是「追加」不是「覆盖」，判不准也按追加。**
你说「写入 / 记录 / 补充 / 加进去 / 写进去」这类中性说法，助手一律**追加到末尾**。
只有出现「覆盖 / 重写 / 替换 / 清空重写 / 整个换成」这类强语义词，才会整篇覆盖。
理由很直接：**追加错了可以再覆盖修正，覆盖错了原文就没了。**

**覆盖之前它一定会先读一遍。** 整篇覆盖是不可逆的，原文没有备份，也没有回滚接口。
所以助手会**先把现有正文读出来**，在确认里告诉你「这份文档现在有什么」（一两句摘要），
让你知道自己要毁掉的是什么。跳过这一步的覆盖等于蒙眼删除。
含糊的「嗯」「你看着办」不算同意。

**追加和覆盖的容量差两个数量级。** 追加单次上限一万字符，覆盖上限一百万。
内容特别长时助手会自己分段追加。

**追加进去的内容不认 markdown 标记。** 追加只支持纯文本，写 `**加粗**` 是不会被渲染的，
会原样出现在文档里。读取和覆盖则支持 markdown——**这三个动作的格式能力不一致**，
所以你会发现「读出来是带格式的，加进去却是纯文本」，这是接口本身的差异。

**内容很长时读取会走本地文件。** 文档正文超长时接口不直接返回内容，而是落到本地文件。
助手会自动再读一次那个文件，然后告诉你「内容较长，我已读取完」——**它不会把本地路径贴给你**。

**清空文档不是传空。** 想把一份文档清空，传空内容是会被拒的，正确做法是写一个空格。
你不需要知道这个，但如果看到助手在「清空」时留了个空格，那是对的。

**这些类型读不了正文**：`ppt` / `journal` / `collect` / `mind` / `flow` / `pdf`。
整套能力里都没有读它们正文的方法，助手会直接说明并给你文档链接，让你在客户端打开。

**要结构化数据就别用文档。** 你的需求里出现「字段 / 记录 / 筛选 / 排序 / 统计 / 分组」时，
助手**不会**用「文档 + 一张静态 markdown 表格」凑合，而是改用
[11 智能表格](11-智能表格.md) 或 [12 智能文档](12-智能文档.md)。

### 三条通用边界在本域怎么体现

1. **只能改它自己建的东西**——**你自己在企业微信里建的那份文档，助手改不了**：
   追加不进去、更覆盖不了。它会说明这条边界，并建议「由我新建一份」或者你自己在客户端改。
   反过来，助手自己建的文档它可以随便改——实测的「写 → 读」闭环就是在自己建的文档上完成的。
2. **能力按品类逐项开通**——文档是独立品类（实测账号是后来单独补开的）。
   未开通时助手会把官方开通指引原样转给你，然后停下，不重试。
3. **危险动作先问你**——**整篇覆盖是高风险写入**，会先读原文、再复述
   「将把《文档名》的全部现有正文替换为新内容（约 N 字），原内容不可恢复」并等你明确同意。
   创建和追加是低风险，直接执行。见 [99 风险与确认](99-风险与确认.md)。

## 相关

- [12 智能文档](12-智能文档.md)——**没指明类型的「写个文档」默认落这里**
- [10 在线表格](10-在线表格.md)——行列网格式的表格
- [11 智能表格](11-智能表格.md)——字段 / 记录 / 视图式的结构化表
- [13 文档管理](13-文档管理.md)——**搜索文档的唯一入口**；改名、加成员、改权限也在那边
- [14 微盘](14-微盘.md)——文件放在微盘里而不是做成在线文档
- [99 风险与确认](99-风险与确认.md)——覆盖前的确认规则