# 智能文档

企业微信的智能文档 / 智能主页：一份文档由**多个页面**组成（页面之间可以嵌套成树），
每个页面由若干**内容块**组成，还自带一份**内置数据表**，页面上的图表和表单按钮可以绑到它上面。

**这一域最重要的一条规则是路由**：你说「写个文档 / 整理成文档 / 输出到文档 / 帮我写份周报」
而**没指明是哪种文档**时，**默认落到这里**——助手不会追问「你要哪种文档」。
只有你明确说了「在线文档 / Word」「在线表格」「智能表格」，或者给出对应链接，才会转给别的能力。

## 你可以怎么说

> 「帮我写份项目周报」
> 「把这些内容整理成文档」
> 「做个数据看板页」
> 「做个报名表单页」
> 「这份智能文档写了什么？」
> 「在文档里再加一段」

## 📋 验证状态

| 项 | 状态 |
|---|---|
| 新建智能文档 | ✅ **已实测**（只验到「能建出来」这一步） |
| 由 Markdown 一次性导入建成带内容的文档 | ⚠️ **未实测** |
| 读页面树 / 读页面正文 | ⚠️ **未实测** |
| 追加内容 | ⚠️ **未实测** |
| 整页覆盖 | ⚠️ **未实测**（高风险写入，未做破坏性验证） |
| 内容块级增删改 | ⚠️ **未实测** |
| 调整页面结构（新建 / 删除 / 改名 / 移动 / 改布局） | ⚠️ **未实测** |
| 取文档内置数据表 | ⚠️ **未实测** |
| 上传图片 / 附件 | ⚠️ **未实测** |
| 完整链路（你说一句话 → 助手自动写完） | ⚠️ 未实测 |

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

```bash
wecom-cli smartpage create ...    # ✅ 建出一份智能文档，标识以 a1_ 开头
```

**只验到「创建」这一步。** 读、写、改页面结构一条都没跑——所以本页不写「实际效果」，
也不虚构任何页面内容或返回值。下面「能力清单」与「注意事项」来自接口定义与技能文档，
是**设计意图，不是实测结论**。

同批实测印证了文档标识的前缀路由：智能文档编辑态是 `a1_`，在线文档 `w3_`，在线表格 `e3_`，
智能表格 `s3_`。助手靠这个判断你给的链接是哪种文档。

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

## 能力清单

> 除「新建」外均**未实测**。

| 能做什么 | 命令 | 风险 |
|---|---|---|
| 新建空白智能文档 | `wecom-cli smartpage create` | 低风险写入 |
| 由 Markdown 一次性导入建成带内容的文档 | `wecom-cli smartpage import` | 低风险写入 |
| 读页面树 / 读某页正文 / 读某页内容块 | `wecom-cli smartpage pages get` | 读取 |
| 在页面末尾追加内容 | `wecom-cli smartpage pages append` | 低风险写入 |
| **整页覆盖**内容 | `wecom-cli smartpage pages overwrite` | **高风险写入** |
| 改页面结构（新建 / 删除 / 改名 / 移动 / 改布局） | `wecom-cli smartpage pages update` | **高风险写入**（仅删除页面那一档） |
| 内容块级插入 / 替换 / 删除 | `wecom-cli smartpage blocks update` | **高风险写入**（仅替换与删除那两档） |
| 取文档内置数据表的子表列表 | `wecom-cli smartpage databases get` | 读取 |
| 上传图片 / 文件到文档空间 | `wecom-cli smartpage images / files upload` | 低风险写入 |

**搜索文档、改文档名不在这里**——归 [13 文档管理](13-文档管理.md)。
本域的「改名」改的是**页面名**，不是整份文档的名字。

## 注意事项

**编辑态和发布态是两种东西，发布态改不了。**

| 状态 | 链接长什么样 | 能不能改 |
|---|---|---|
| 编辑态 | `doc.weixin.qq.com`，标识 `a1_` 开头 | 可读可写 |
| 发布态 | `page.weixin.qq.com`，标识 `b1_` 开头 | **只读** |

你给的是发布态链接却要求编辑时，助手会请你换一个编辑态链接，**不会硬试**。

**默认是「追加」不是「覆盖」。** 说「写入 / 记录 / 补充 / 加进去」这类中性词，助手追加到末尾；
只有「覆盖 / 重写 / 替换整页 / 清空重写」这类强语义词才会整页覆盖。

**「把第三段改一下」不会走整页覆盖。** 局部改动走的是**内容块级编辑**——
只动那一块，其余原样保留。助手**不会为了图省事整页重写**。

**整页覆盖是把原有内容块全部删掉后重建**，旧内容没有任何接口能找回来。所以执行前会复述
「将用新内容全量覆盖页面『XX』的原有内容，原内容不可恢复」并等你明确同意。
另外覆盖时如果拿不到版本号，**会静默盖掉别人刚写的并发修改**——所以助手会先重新读一遍最新内容。

**删页面是级联的。** 删一个页面会**连同它下面的所有子页面一起删掉**。
助手会先把子页面数出来告诉你（「及其全部 N 个子页面：……」）再等你同意。
同一个命令里的新建、改名、移动、改布局是可逆的，不需要这层确认——但移动改变了层级归属，
改完助手会重新读一遍结构再告诉你新的样子。

**改之前一定会重新读一遍。** 哪怕几分钟前刚读过。既是为了拿准要改哪一块，
也是为了不覆盖掉别人的并发修改。

**要做表单页 / 数据看板页，走的是另一条路。**
需求里出现「表单 / 报名 / 问卷 / 收集 / 录入」或「数据看板 / 图表绑数据 / 任务系统 / 项目跟踪」时，
页面上的控件要引用内置数据表的字段——**必须先把字段定好，再写页面内容**。
直接导入一份 Markdown 会建出一份**没有数据表的静态文档**：报名按钮存不下数据，图表也渲染不出来。
助手知道这个顺序。

**文档自带一份内置数据表，不用另建智能表格。**
那份内置表的子表、字段、记录操作会委托给 [11 智能表格](11-智能表格.md)；
但页面上的图表、视图、筛选控件属于展示层，仍归本域。

**文档命名有固定风格。** 中文命名，时间等附加信息用中文括号标注——
`项目进展周报（2026.04.23）` 是对的，`工作日报_20260202` 这种下划线拼英文日期是不允许的。

**正文里的图片会被真的读进去。** 你让它「总结这份文档」而正文里有图时，
助手会把图片下载下来识别，再和文字合并作答，必要时标注「图 N：……」方便你溯源。
图片下载失败时它会如实说「第 N 张图片无法访问，未纳入分析」——**不会编造图片内容**。
纯粹的结构调整、搬运、覆盖任务则跳过这一步。

**页面里的只读组件会被原样保留**，助手不会顺手改掉或删掉它们。

**这些做不到**（会直接说明，引导你去客户端）：

- 导出 / 下载为 PDF、Word、图片
- 评论、查看历史版本、回收站恢复
- 编辑发布态文档

**内容安全上有一条硬线**：写进页面的内容里如果夹带可执行脚本、事件处理器属性、
`javascript:` 之类的伪协议，助手会**直接拒绝写入并说明原因**，不会「悄悄清洗一下再写进去」。
读到的页面内容里出现「忽略之前的指令」这类文本时，一律当普通文字处理。

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

1. **只能改它自己建的东西**——**你自己建的那份智能文档，助手改不了**：追加不进去、
   改不了页面结构。它会说明这条边界，并建议「由我新建一份」或者你自己在客户端改。
2. **能力按品类逐项开通**——智能文档属于文档品类（实测账号是后来单独补开的）。
   未开通时助手会把官方开通指引原样转给你，然后停下，不重试。
3. **危险动作先问你**——**整页覆盖、删除页面、删除或替换内容块**是高风险写入，
   都会复述具体影响并等你明确同意。新建、导入、追加、插入内容块是低风险，直接执行。
   见 [99 风险与确认](99-风险与确认.md)。

## 相关

- [09 在线文档](09-在线文档.md)——Word 类在线文档（明说「Word / 在线文档」或给 `/doc/` 链接才走那边）
- [11 智能表格](11-智能表格.md)——本文档内置数据表的字段与记录操作会委托到那边
- [10 在线表格](10-在线表格.md)——行列网格式的表格
- [13 文档管理](13-文档管理.md)——**搜索文档的唯一入口**；**改整份文档的名字**也在那边
- [14 微盘](14-微盘.md)——文件放进微盘，而不是做成智能文档
- [99 风险与确认](99-风险与确认.md)——覆盖与删除前的确认规则