# 智能表格

企业微信里**结构最像数据库**的载体：子表 = 表，字段 = 列，记录 = 行，另外还有视图（筛选/排序/分组/列宽/填色）
和仪表盘图表两层展示配置。建表、查数、加减列、增删改记录、做看板都在这里。
**这是整套能力里方法最多、能做的事最丰富的一域**——也是删除类操作最集中的一域。

**未指明类型的表格需求默认走这里**；只有你明说「在线表格」或给出 `/sheet/` 链接，
才会转 [10 在线表格](10-在线表格.md)。

## 你可以怎么说

> 「帮我建个项目管理表」
> 「加一列『预算』」
> 「加条记录：登录优化，负责人张三，9 月 15 号截止」
> 「把『登录优化』的状态改成已完成」
> 「统计一下各部门各多少条」
> 「做个看板，加个月度销售趋势图」

## 📋 验证状态

| 项 | 状态 |
|---|---|
| 新建智能表格 | ✅ **已实测** |
| 读表基本信息与子表结构 | ✅ **已实测**：返回 1 张子表 / 5 个字段 / 5 条记录 |
| 查字段列表与属性 | ⚠️ **未实测** |
| SQL 查数 / 读记录 | ⚠️ **未实测** |
| 新增 / 修改 / 删除记录 | ⚠️ **未实测** |
| 新增 / 修改 / 删除字段 | ⚠️ **未实测** |
| 新增 / 改名 / 删除子表 | ⚠️ **未实测** |
| 视图与仪表盘图表 | ⚠️ **未实测** |
| 导入 Excel / CSV 建表 | ⚠️ **未实测** |
| 完整链路（你说一句话 → 助手自动建完） | ⚠️ 未实测 |

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

```bash
wecom-cli smartsheet create ...       # ✅ 建出一张智能表格，标识以 s3_ 开头
wecom-cli smartsheet sheets list ...  # ✅ 返回子表结构：1 张子表 / 5 个字段 / 5 条记录
```

这一条同时印证了一个坑：建表时指定名称的参数是 `name` 而不是 `doc_name`——
实测中人工凭常识写成 `doc_name` 直接失败，技能文档写的是对的。

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

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

## 能力清单

> 除「新建」与「读子表结构」外均**未实测**。

| 能做什么 | 命令 | 风险 |
|---|---|---|
| 新建智能表格（可一次建好子表 + 字段） | `wecom-cli smartsheet create` | 低风险写入 |
| 导入 Excel / CSV 建表（或追加到已有表） | `wecom-cli smartsheet import` | 低风险写入 |
| 看表基本信息 + 子表列表 | `wecom-cli smartsheet sheets list` | 读取 |
| 新增子表 / 仪表盘 | `wecom-cli smartsheet sheets add` | 低风险写入 |
| 改子表名 | `wecom-cli smartsheet sheets update` | **高风险写入** |
| 删子表 | `wecom-cli smartsheet sheets delete` | **高风险写入** |
| 查字段列表与属性 | `wecom-cli smartsheet fields list` | 读取 |
| 新增字段 | `wecom-cli smartsheet fields add` | 低风险写入 |
| 改字段（名称 / 属性 / **类型**） | `wecom-cli smartsheet fields update` | 低风险写入（**改类型时升为高风险**） |
| 删字段 | `wecom-cli smartsheet fields delete` | **高风险写入** |
| 用 SQL 查数（支持聚合、TopN） | `wecom-cli smartsheet records query` | 读取 |
| 读记录（权限受限时的读法） | `wecom-cli smartsheet records list` | 读取 |
| 新增记录 | `wecom-cli smartsheet records add` | 低风险写入 |
| 改记录 | `wecom-cli smartsheet records update` | **高风险写入** |
| 删记录 | `wecom-cli smartsheet records delete` | **高风险写入** |
| 查 / 新增 / 修改视图 | `wecom-cli smartsheet views list / add / update` | 读取 / 低风险写入 |
| 删视图 | `wecom-cli smartsheet views delete` | **高风险写入** |
| 查 / 新增 / 修改仪表盘图表 | `wecom-cli smartsheet charts list / add / update` | 读取 / 低风险写入 |
| 删图表 | `wecom-cli smartsheet charts delete` | **高风险写入** |
| 上传图片 / 文件到文档空间 | `wecom-cli smartsheet images / files upload` | 低风险写入 |

**整套能力的 26 个高风险动作里，有 7 个集中在这一域**。删除类操作**没有任何回滚通道**，
客户端也不提供恢复接口。

**搜索表格、改表格文件名不在这里**——那两件事归 [13 文档管理](13-文档管理.md)。
本域的「改子表名」改的是**子表**，不是整个文件的名字。

## 注意事项

**删除类操作最集中，也最不可逆。** 记住这三条：

- **删一列 = 连带删掉这一列的全部数据。** 助手会告诉你「该列已有的全部数据会一并丢失」。
- **删一张子表 = 里面的字段和记录一起没。** 助手会先数一数有多少字段、多少条记录再告诉你。
- **删视图 = 那套筛选、排序、分组、列宽、填色配置没了**，只能手工重建。

**「删全部」「清一下」这种说法它不会动手。** 描述模糊时助手会先问清范围和保留条件——
「删除 2026 年 3 月之前的记录」「只保留状态为已完成的行」这种才算说清楚了。

**一次改超过 100 条记录，即使是普通修改也会先问你一句**，说明影响范围。
另外单次修改**最多影响 2000 行**，超过要分批。

**改字段类型是隐蔽的高风险动作。** 只改列名、改显示属性是可逆的，助手直接做；
但**改字段类型**会让企业微信对已有单元格做转换甚至直接丢弃（比如文本改成数字时，
非数字内容就没了）。所以助手会先读回这个字段当前的类型，跟你要改成的类型比对，
**不一致就按高风险处理**，先告诉你「该列已有的 N 条数据可能被转换或清空」。

**写记录之前它会先读几条现有的。** 目的是对齐用词——避免造出「进行中」和「处理中」两套并存的脏数据。

**统计交给服务端算，不拉全量回来数。** 「统计一下各部门多少条」这类问题，助手会用 SQL 让企业微信
算完再返回。**超过 1000 行的求和、计数、排名它不会自己心算**。

**只做描述性统计，不做因果和预测。**

- ✅ 各部门工单数排名、本月销售额 TopN、按状态分组统计、同比环比的数值计算
- ❌ 「为什么 A 部门工单这么多」「下个月销售额预测」「这数据反映了什么问题」「建议怎么优化」

**「标红 / 高亮 / 加底色」是真的改表，不是在回复里加粗。**
助手会去改视图的条件格式配置，让你在企业微信里打开就能看到颜色。

**能由其他列算出来的值，它会建议用公式列。** 比如「剩余天数」「完成率」——
你没指定类型时它直接用公式列；你指定了别的类型，它说明公式列的好处之后**听你的**。

**建表时它会顺手做两件事**：清掉新建时自带的空记录，以及按内容长度给每列设个合适的宽度。

**有上限**：单张子表最多 20000 条记录、150 个字段。接近上限时助手会提前告诉你。

**这些做不到**（会直接说明，不变通）：

- 历史版本、时间点快照、查看修改历史或操作日志
- 恢复已删除的记录、字段、子表
- 导出为 Excel / CSV
- 删除智能表格**文件**本身
- 插入 AI 字段、写入地理位置字段、写入群字段（引导你在客户端手动做）

**参考别人的表 ≠ 往别人的表里写。** 你说「参考 X 表的格式」时，助手会读 X 的字段结构，
然后**建一张新表**往新表写，不会往 X 里写。

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

1. **只能改它自己建的东西**——**你自己建的那张智能表格，助手改不了**：加不了列、写不进记录。
   它会说明这条边界，并建议「由我新建一张」或者你自己在客户端改。
   实测的建表 + 读结构就是在助手自己建的表上完成的。
2. **能力按品类逐项开通**——智能表格属于文档品类。未开通时助手会把官方开通指引原样转给你，
   然后停下，不重试。另外，你对这张表**没有全部权限**时，SQL 查数会被拒，
   助手会自动降级成按你可见范围读记录，而不是报错了事。
3. **危险动作先问你**——**7 个高风险写入 + 1 个条件升级**，每个执行前都会复述具体影响
   （删哪一列 / 哪张子表 / 多少条记录）并等你明确同意。见 [99 风险与确认](99-风险与确认.md)。

## 相关

- [10 在线表格](10-在线表格.md)——行列网格式的表格（说「单元格」「A1」时用那个）
- [12 智能文档](12-智能文档.md)——智能文档**自带一份内置数据表**，页面上的图表和表单按钮就绑在它上面；
  那份表的字段与记录操作会委托到本域
- [09 在线文档](09-在线文档.md)——Word 类文档的正文读写
- [13 文档管理](13-文档管理.md)——**搜索表格的唯一入口**；**改整个表格文件的名字**也在那边
- [02 通讯录](02-通讯录.md)——人员字段写入失败时，先在这里把人名解析出来
- [99 风险与确认](99-风险与确认.md)——删除类操作的通用闸门