@rezti/dsh-rez-suite 0.1.50 → 0.1.52

package/templates/shared/wecomcli-smartsheet/references/smart-sheet-read.md

@@ -0,0 +1,391 @@
+# 智能表格取数接口参考
+
+本文件是子表、记录、字段、视图和图表五类资源的唯一取数入口。凡需读取这些资源，必须先完整阅读本文件；需要解析具体字段、视图或图表结构时，再完整阅读对应类型 reference。
+
+## 目录
+
+- [读取前强制规范](#读取前强制规范)
+- [命令调用格式](#命令调用格式)
+- [文档与资源标识](#文档与资源标识)
+- [取数与验证规范](#取数与验证规范)
+- [读取操作](#读取操作)
+
+## 读取前强制规范
+
+1. 先完成 `SKILL.md` 的安全边界复查；未通过时禁止调用任何工具。
+2. 完整阅读本文件，并按场景补充阅读类型 reference：
+   - 字段：`references/smart-sheet-field-types.md`
+   - 记录写入值：`references/smart-sheet-record-values.md`
+   - 视图、过滤与排序：`references/smart-sheet-view-types.md`
+   - 图表：`references/smart-sheet-chart-types.md`
+3. 确认接口名称、参数、枚举和返回结构均有明确文本依据后再调用；禁止凭记忆猜测、根据名称推断或试探性调用。
+4. **访问子表失败时禁止重试**——尝试访问某个子表失败时，禁止直接重试，应先调用 `wecom-cli smartsheet sheets list` 检查子表是否存在。若子表确实存在但仍无法访问，需立即停止执行任务，并告知用户可能为权限问题。
+
+## 命令调用格式
+
+五类读取接口中，记录 SQL 查询使用 `--docid` 与一个或多个 `--sql`；其余接口统一使用 `--json`。
+
+**`docid` 传参规则**：除 `records query` 外，禁止把 `docid` 直接作为 smartsheet 顶层参数传入（必须作为 `--json` 参数的一个字段传入）；`records query` 必须使用 `--docid '<docid>'`。
+
+```bash
+wecom-cli smartsheet sheets list --json '{"docid": "<docid>"}'
+wecom-cli smartsheet records query --docid '<docid>' --sql '<SELECT ...>' [--sql '<SELECT ...>']
+wecom-cli smartsheet records list --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "limit": 100}'
+wecom-cli smartsheet fields list --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "limit": 100}'
+wecom-cli smartsheet views list --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "limit": 100}'
+wecom-cli smartsheet charts list --json '{"docid": "<docid>", "sheet_title": "<仪表盘子表名称>", "limit": 100}'
+```
+
+- `--json`：JSON 参数用单引号包裹，`docid` 是 JSON 内部字段，不得作为顶层 shell 参数。
+- `--docid`：仅记录 SQL 查询使用，用单引号包裹。
+- `--sql`：仅允许只读 `SELECT`；可重复传入。SQL 外层用单引号，字段名、子表名和别名用反引号，字符串字面量用双引号。
+
+## 文档与资源标识
+
+所有读取接口都需要文档 ID。合法来源和模糊指代限制以 `SKILL.md` 的“如何获取文档 ID”和“执行前置协议”为准。
+
+| ID 类型 | 获取方式 |
+| --- | --- |
+| docid | 用户当前消息直接提供，或从当前消息中的智能表格 URL 提取；用户明确要求搜索时可通过文档管理技能获取 |
+| sheet_id | 读取子表列表后，从返回的子表对象中获取 |
+| field_id | 读取字段列表后，从返回的字段对象中获取 |
+| sheet_title | 用户提供的子表名称，或读取子表列表后获取 |
+| field_title | 用户提供的字段名称，或读取子表/字段列表后获取 |
+| record_id | 记录 SQL 查询显式选择特殊记录标识列后，从返回行中获取 |
+| view_id | 读取视图列表后，从返回的视图对象中获取 |
+| chart_id | 读取图表列表后，从返回的图表对象中获取 |
+
+## 取数与验证规范
+
+1. **服务端过滤**——当用户有筛选条件时，必须在 `wecom-cli smartsheet records query` 的 SQL 中用 `WHERE` / `HAVING` / `LIMIT` 等条件约束结果规模，严禁拉取全量或部分后本地筛选。
+2. **时间查询用 SQL 表达**——涉及"今天/本周/本月"等相对时间，必须在 SQL 中表达查询范围；日期时间字段在 SQL 中按 Excel 序列号存储，非 Unix 毫秒，默认使用 `DATE_FORMAT` 直接格式化。
+3. **人员字段查询口径**——`FIELD_TYPE_USER` / 短枚举 `user` 在 `records query` 中返回对象数组。按人名筛选时可直接对人员字段 `LIKE`；按人员 `id` 或 `corp_name` 筛选时，使用 JSON 子键语法（shell 调用中写成 `` `负责人`->>"id" LIKE "%woxxx%" ``）。人员字段本质是数组，相关筛选优先使用 `LIKE`，不要用 `=` 做精确匹配。读取时直接 `SELECT` 人员字段，解析 `rows` 后从对象数组中取 `name` 展示。写入时优先传 `{"userName": "<姓名>"}` 让系统自动匹配，报错时再用 `wecomcli-contact` 查 `userid` 重试。
+4. **聚合遵循维度建模语义**——执行聚合前先确认事实表粒度（grain）和度量可加性（additivity），识别可加、半可加、不可加及去重计数度量；字段名不能替代口径确认。详见下方“聚合语义”。
+5. **超1000行的数值汇总不支持**——严禁在 reasoning 或回复中口算超过1000条记录的加总；凡涉及超过1000条记录的求和、计数、排名、分组汇总，提示大数据不支持，并推荐用户新增公式字段进行运算。
+6. **大结果优先收敛查询**——返回临时文件路径时，优先补充过滤、分页、聚合和字段投影后重新查询；确需读取文件时仅提取必要片段，禁止整文件载入上下文。
+7. **读取即验证**——写操作完成后，根据资源类型读取子表、字段、记录、视图或图表，核对用户要求的最终状态；接口返回成功也不能替代最终验证。
+
+## 读取操作
+
+需要修改表结构、记录、视图或图表时，另行完整阅读 `references/smart-sheet-edit.md`。
+
+### 一、查询子表列表（smartsheet sheets list）
+
+查询智能表格的子表列表，获取子表名称、类型、字段数、记录数等信息。
+
+```bash
+wecom-cli smartsheet sheets list --json '{"docid": "<docid>"}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+
+**返回值：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `url` | string | 智能表格访问链接 |
+| `name` | string | 智能表格文档名称 |
+| `sheets` | array | 子表列表，包含智能表格子表和仪表盘两种类型 |
+| `sheets[].sheet_id` | string | 子表 ID |
+| `sheets[].title` | string | 子表标题 |
+| `sheets[].type` | string | 子表类型：`smartsheet` 为智能表格子表，`dashboard` 为仪表盘 |
+| `sheets[].field_count` | int | 列数量（仅 `smartsheet` 类型） |
+| `sheets[].record_count` | int | 行数量（仅 `smartsheet` 类型） |
+| `sheets[].chart_count` | int | 图表数量（仅 dashboard 类型） |
+| `sheets[].fields` | array | 可选的轻量列预览（仅 `smartsheet` 类型可能返回）。当前每项仅包含 `field_title`、`field_type`；`field_type` 为读取返回短枚举，对应 `references/smart-sheet-field-types.md` 的“短枚举值”列；大表响应体积较大时可能不返回本字段 |
+
+> **大数据响应处理（返回文件路径时）**：
+>
+> 当子表数量较多时，接口返回内容可能过长，系统会将完整结果写入一个**临时文件**，并在响应中返回该文件的**绝对路径**，而非直接输出 JSON 内容。
+>
+> 遇到此情况时，**禁止**直接读取整个文件，应按以下策略处理：
+>
+> 1. 优先回到接口层补充过滤条件（如 `limit`、`cursor`），重新调用，避免本地全量解析。
+> 2. 如需快速预览，可使用局部读取（`read 工具`）查看结构。
+> 3. 如需提取关键字段，使用 `grep 工具`（指 Harness 内置工具，非 `exec grep` 命令）进行提取。
+
+> **字段详情获取规则**：`sheets list` 返回的字段预览不能替代 `fields list`。涉及新增/修改记录、视图筛选、图表筛选、字段属性判断、单选/多选 option ID、人员字段属性等场景时，先用 `sheets list` 定位子表，再对目标子表调用 `wecom-cli smartsheet fields list`。
+
+---
+
+### 二、读取智能表格数据（smartsheet records query）
+
+使用 SQL 读取智能表格子表数据。适用于简单取数、字段探查、分组统计、TopN、趋势统计、跨表关联等只读场景。
+
+```bash
+wecom-cli smartsheet records query --docid '<docid>' --sql 'SELECT RECORD_ID, `<field_title1>`, `<field_title2>` FROM `<sheet_title>` LIMIT 100'
+```
+
+**请求参数（shell 参数传入）：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `--docid` | string | 是 | 文档 ID |
+| `--sql` | string[] | 是 | 一条只读 `SELECT` 语句；可重复传多个 `--sql` 表示 SQL 数组，每个 `--sql` 对应一条 SQL |
+
+> **SQL shell 转义规则**：整条 SQL 用单引号包裹；字段名、子表名、别名用反引号包裹；字符串字面量用双引号包裹，避免反引号在 shell 中被命令替换。
+
+**返回值：**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `errcode` | int | `0` 表示查询成功 |
+| `values` | string[] | 每个元素对应请求中的一条 SQL；元素内容是 JSON 字符串，解析后读取其中的 `rows` |
+
+`values[i]` 与请求中的第 `i + 1` 条 SQL 一一对应。每个 `values[i]` 解析后的结构如下：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `rows` | object[] | 返回行数据；每行是 `{字段名: 值}` 映射，按 SQL 中的 `field_title` 返回 |
+
+
+```json
+{
+  "errcode": 0,
+  "values": [
+    "{\"rows\":[{\"文本\":\"这是一个纯文本\",\"数字\":111,\"单选\":\"选项A\",\"多选\":[\"标签2\",\"标签1\"],\"复选框\":true,\"自动编号\":\"1\",\"创建人\":\"zhangsan(张三)\",\"创建时间\":46205,\"RECORD_ID\":\"r2gG1i\"},{\"文本\":null,\"数字\":null,\"单选\":null,\"多选\":null,\"复选框\":false,\"自动编号\":\"2\",\"创建人\":\"zhangsan(张三)\",\"创建时间\":46205,\"RECORD_ID\":\"rNbGbU\"}]}"
+  ]
+}
+```
+
+> **重要**：`records query` 的 SQL 入参和 `rows` 返回 key 默认都以字段名称（`field_title`）为准；除 `RECORD_ID` 这种特殊列外，不要在 SQL 中使用 `field_id`，也不要把字段 ID 当作返回 key 来解析。
+
+> **大数据响应处理（返回 JSON 文件路径时）**：
+>
+> 当查询结果过大时，工具可能不会直接返回完整 `values` 内容，而是将完整 JSON 结果写入临时文件，并在响应中返回该 JSON 文件的绝对路径。
+>
+> 遇到此情况时，优先回到 SQL 层补充 `WHERE`、`LIMIT`、聚合、字段投影等约束后重新查询，避免本地全量解析。确需使用文件结果时，只读取必要片段或用结构化方式提取目标字段，禁止把整个大文件一次性读入上下文再做筛选、统计或汇总。
+
+**各字段类型在 `rows` 中的常见值形态：**
+
+| 字段类型短枚举值 | `rows` 中的值形态 | 示例 | 说明 |
+| --- | --- | --- | --- |
+| `text` / `phone_number` / `email` / `url` / `barcode` / `autonumber` | string 或 null | `"这是一个纯文本"`、`"17620067816"`、`"1"` | 未填通常返回 `null`；`autonumber` 是系统生成值，空行业务字段未填时也会按显示文本返回 |
+| `number` / `currency` / `percentage` / `progress` | number 或 null | `111`、`20`、`0.18018018018018`、`37` | 未填返回 `null`；`percentage` 返回小数（如 `0.2` 表示 20%）；`progress` 返回显示数值 |
+| `formula` | 取决于公式结果类型，或 null | `0.18018018018018`、`"已完成"`、`true`、`["标签1"]` | 公式可能返回数字、文本、布尔、日期序列号、数组或空值；不要默认当作 number 处理 |
+| `date_time` | number 或 null | `46205`、`null` | 默认按 Excel 序列号返回；需要可读日期时在 SQL 中使用 `DATE_FORMAT` |
+| `created_time` / `modified_time` | number | `46205` | 系统字段，记录存在即通常有值；按 Excel 序列号返回 |
+| `checkbox` | boolean | `true`、`false` | 勾选返回 `true`；未勾选或未填返回 `false`，不要当作缺失值 |
+| `single_select` | string 或 null | `"选项A"` | 直接返回选项文本 |
+| `select` | string[] 或 null | `["标签2","标签1"]` | 直接返回选项文本数组，顺序以服务端返回为准 |
+| `user` | object[] 或 null | `[{"corp_name":"腾讯","id":"14433133094329758785","name":"zhangsan(张三)"}]` | 始终按数组返回；单人/多人由字段属性区分；对象内通常包含 `id`、`name`、`corp_name`；展示给用户用 `name`，不要暴露 `id` |
+| `created_user` / `modified_user` | string | `"zhangsan(张三)"` | 系统字段，返回姓名字符串，不是数组或对象 |
+| `image` / `attachment` | string[] 或 null | `["意图对比.jpg"]`、`["Python3内置SQLite库说明.pdf"]` | 查询结果只给图片名/文件名数组，不是媒体下载 URL |
+| `wwgroup` | string 或 null | `"未命名群聊"` | 查询结果返回群聊名称字符串；未填返回 `null` |
+| `location` | string 或 null | `"广东省广州市番禺区沙溪大道330号"` | 查询结果返回地址文本；未填返回 `null` |
+| `lookup` | 被引用字段的查询值数组或 null | `["这是一个纯文本"]` | 查找引用会展开为引用字段值的数组；数组元素类型跟源字段在 `records query` 中的查询值形态一致；无引用值返回 `null` |
+| `two_way_link_records` | 被关联字段的查询值数组或 null | `["这是一个纯文本"]` | 双向关联会展开为关联记录的显示值数组；数组元素类型跟关联显示字段在 `records query` 中的查询值形态一致；无关联值返回 `null` |
+
+未填业务字段通常返回 `null`；例外是 `checkbox` 未填返回 `false`，`autonumber` / `created_user` / `created_time` / `modified_user` / `modified_time` 等系统字段通常仍有值。
+
+#### SQL 编写规则
+
+1. **只读查询**——仅允许 `SELECT`；禁止写入、更新、删除、建表、临时表等操作
+2. **数据源限定**——`FROM` 只能使用当前智能表格内真实存在的子表名称（`sheet_title`），例如 ``FROM `任务列表` ``
+3. **特殊列 `RECORD_ID`**——`RECORD_ID` 是 records query 暴露的行记录 ID 特殊列，不是普通字段，不需要来自字段列表；需要后续 `records update` / `records delete` 定位记录时，在 `SELECT` 中显式带上 `RECORD_ID`
+4. **字段限定**——除 `RECORD_ID` 外，SQL 中所有列引用必须使用字段名称（`field_title`），禁止使用字段 ID（`field_id`）。`SELECT`、`WHERE`、`HAVING`、`GROUP BY`、`ORDER BY`、`JOIN ON` 和函数参数中的列引用均适用；字段名称必须来自 `wecom-cli smartsheet sheets list` 或 `wecom-cli smartsheet fields list` 返回结果，禁止臆造字段
+5. **反引号包裹**——子表名称（`sheet_title`）、字段名称（`field_title`）和 SQL 别名默认使用反引号包裹；名称即使包含中文、空格或特殊字符，也使用反引号包裹。`RECORD_ID` 按示例直接书写，不加反引号
+6. **日期字段**——日期时间字段在 SQL 中按 Excel 序列号存储，非 Unix 毫秒；默认使用 `DATE_FORMAT` 直接格式化
+7. **结论来源**——计数、合计、占比、峰值、TopN、趋势等结论必须来自 SQL 返回结果，不得根据字段名或表名推断
+
+#### 聚合语义
+
+SQL 聚合前遵循维度建模的 **grain-first** 原则：先用业务主键、时间/批次字段和少量样例确认一行事实的粒度，再确定度量的可加性。
+
+聚合前必须确认指标的业务定义及其与字段的映射关系。字段存在、值为空或 SQL 能返回结果，只能证明数据层事实，不能自动证明业务状态；映射关系无法从用户说明或表结构中唯一确定时，不得自行假设，应说明该指标无法可靠计算并追问口径。
+
+例如：
+- “发货日期为空”只表示日期未填写，不一定代表未发货；
+- “金额为空”不等于金额为 0。
+
+- **Additive measure**：仅可沿与事实粒度兼容的维度 `SUM`。
+- **Semi-additive measure**：余额、库存、累计值等通常不可沿时间维度求和；对 periodic/accumulating snapshot fact，应先按业务主键选定目标快照。`MAX` 不等于“最新”。
+- **Non-additive measure**：比例、人均、均价、转化率等应从同口径的基础分子、分母重新计算，不能直接求和或平均。
+- **Distinct-count measure**：人数、客户数、设备数等须基于稳定主体标识 `COUNT(DISTINCT ...)`；没有主体标识时不得宣称已去重。
+
+跨组比较还须满足相同 grain、统计周期、过滤范围和去重规则。任一关键语义无法从用户说明、表结构或探查结果确认时，先追问或改用可信汇总表；不得先输出数字再用免责声明补救。
+
+#### SQL 能力边界
+
+支持：
+
+- `JOIN`
+- `GROUP BY` / `HAVING`
+- `COUNT`、`COUNT(*)`、`COUNT(DISTINCT col)`
+- `SUM`、`AVG`、`MIN`、`MAX`
+- `DATE_FORMAT`、`NOW()`
+- `CASE WHEN`、`NULLIF`
+- `IN`、`EXISTS`
+- `LIKE`、字符串函数、数学函数
+
+不支持：
+
+- `FULL JOIN`
+- 窗口函数
+- `COALESCE` / `IFNULL`
+- `UNION` / CTE / `PIVOT`
+- 子查询
+- `CAST`
+- `STDDEV`
+- `COUNT(*) FILTER`
+- `GROUP_CONCAT` / `ARRAY_AGG`
+- SQL 内把多选列拆成多行
+
+#### SQL 示例
+
+**日期按月分组：统计每月总数、满意度平均分和未完成得分：**
+
+日期时间字段按 Excel 序列号存储，展示和按月分组时优先使用日期格式化函数；人员字段可用 JSON 子键语法按人员 `id` 查询。
+
+```bash
+wecom-cli smartsheet records query --docid '<docid>' --sql 'SELECT DATE_FORMAT(`提交时间`, "%Y-%m") AS `月份`, COUNT(*) AS `总数`, AVG(`满意度评分`) AS `满意度平均分`, SUM(CASE WHEN `是否已完成` = false THEN 10 ELSE 0 END) AS `未完成得分` FROM `<sheet_title>` WHERE `负责人`->>"id" LIKE "%woxxx%" GROUP BY DATE_FORMAT(`提交时间`, "%Y-%m") ORDER BY `月份` ASC LIMIT 100'
+```
+
+**聚合后筛选：按单选分组，筛选条件包含多选值和创建人，对数值字段求和并按复选框算分：**
+
+多选字段可用模糊匹配判断是否包含某个选项，但 SQL 内不支持把多选拆成多行统计；`created_user` 返回字符串，可直接按显示姓名筛选；自动编号返回字符串，不能用 `CAST` 转为数值参与求和；需要求和时应选择数字、货币、百分比等数值字段。复选框字段可配合条件聚合做计数或算分；需要对聚合结果筛选时，直接使用 `HAVING`，不要套子查询。
+
+```bash
+wecom-cli smartsheet records query --docid '<docid>' --sql 'SELECT `状态`, COUNT(*) AS `总数`, SUM(`工时`) AS `工时合计`, SUM(CASE WHEN `是否已完成` = false THEN 1 ELSE 0 END) AS `未完成数` FROM `<sheet_title>` WHERE `标签` LIKE "%标签1%" AND `创建人` = "zhangsan(张三)" GROUP BY `状态` HAVING `未完成数` > 0 ORDER BY `未完成数` DESC, `总数` DESC LIMIT 100'
+```
+
+**跨子表关联：统计项目数和平均每项目工时：**
+
+跨子表关联适合两张子表有稳定业务键可关联的场景，例如任务表和项目表都包含 `项目编号`。关联条件中的字段仍使用字段名称，数据源使用子表 ID；需要去重统计时使用去重计数，计算比例时用除零保护。
+
+```bash
+wecom-cli smartsheet records query --docid '<docid>' --sql 'SELECT COUNT(DISTINCT `项目表`.`项目编号`) AS `项目数`, SUM(`任务表`.`工时`) * 1.0 / NULLIF(COUNT(DISTINCT `项目表`.`项目编号`), 0) AS `平均每项目工时` FROM `<sheet_title1>` AS `任务表` JOIN `<sheet_title2>` AS `项目表` ON `任务表`.`项目编号` = `项目表`.`项目编号`' --sql 'SELECT `状态`, COUNT(*) AS `总数`, SUM(`工时`) AS `工时合计`, SUM(CASE WHEN `是否已完成` = false THEN 1 ELSE 0 END) AS `未完成数` FROM `<sheet_title>` WHERE `标签` LIKE "%标签1%" AND `创建人` = "zhangsan(张三)" GROUP BY `状态` HAVING `未完成数` > 0 ORDER BY `未完成数` DESC, `总数` DESC LIMIT 100'
+```
+
+#### records query 的权限适用范围与 records list 降级读取
+
+`wecom-cli smartsheet records query` 要求当前用户拥有智能表的全部权限；如果用户没有，接口会返回：
+
+```text
+errcode=538005 errmsg="没有该智能表的全部权限，请降级使用wecom-cli smartsheet records list"
+```
+
+遇到该错误时，停止使用 `records query` 查询该子表，改用 `wecom-cli smartsheet records list` 读取用户可见范围内的行记录，注意返回值的结构与records query不同。`records list` 是权限降级读取接口，适合简单读取、字段投影、基础筛选、排序和分页；复杂统计、JOIN、聚合、TopN 等仍优先使用 `records query`，但前提是用户具备智能表的全部权限。
+
+```bash
+wecom-cli smartsheet records list --json '{"docid": "<docid>", "sheet_title": "<子表名称>", "limit": 100}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 子表名称，用于定位目标子表 |
+| `cursor` | string | 否 | 分批拉取游标，不传则从头开始；上一次响应的 `next_cursor` 值，下次传入此字段继续拉取 |
+| `limit` | uint32 | 否 | 分页条数（0～1000）；同时必须保证 `limit * 返回列数 < 10000`。返回列数按 `field_titles` 数量计算；未传 `field_titles` 时，先获取目标子表字段数量。超过限制时，减少 `limit` 或通过 `field_titles` 只取必要字段 |
+| `field_titles` | string[] | 否 | 按字段名称过滤要返回的列，不传返回全部列 |
+| `sort` | Sort[] | 否 | 排序设置 |
+| `filter_spec` | FilterSpec | 否 | 过滤设置。单选/多选支持直接传选项文本，不要求一定传 `options[].id`。结构定义见 `references/smart-sheet-view-types.md` |
+
+**Sort（排序项，`sort` 为 Sort 数组）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `field_title` | string | 是 | 排序字段名称 |
+| `desc` | bool | 否 | 是否降序：`true` 降序，`false` 升序 |
+
+**FilterSpec / Condition：**
+
+使用 `filter_spec` 前必须查阅 `references/smart-sheet-view-types.md` 和 `references/smart-sheet-field-types.md`，确认 `conjunction`、`field_type`、`operator` 以及对应值字段。单条 `Condition` 中 `field_title`、`field_type`、`operator` 必填，值字段按字段类型选择其一：文本/单选/多选等使用 `string_value`，数字/货币/百分比等使用 `number_value`，复选框使用 `bool_value`，成员/创建人/编辑人使用 `user_value`，日期/创建时间/编辑时间使用 `date_time_value`。禁止传空的 `filter_spec` 或空 `conditions`。
+
+**请求示例：**
+
+```json
+{
+  "docid": "s3_xxx",
+  "sheet_title": "任务列表",
+  "field_titles": ["状态", "负责人"],
+  "filter_spec": {
+    "conjunction": "and",
+    "conditions": [
+      {
+        "field_title": "状态",
+        "field_type": "single_select",
+        "operator": "is",
+        "string_value": {
+          "value": ["进行中"]
+        }
+      }
+    ]
+  },
+  "limit": 20
+}
+```
+
+> 解析返回值前查阅 `references/smart-sheet-record-values.md`。`errcode == 0` 但无 `records` 字段表示成功且结果为空，应向用户说明当前条件下未命中数据。返回数据过大时，工具可能将结果写入临时文件并返回路径；此时优先补充过滤条件重新调用，避免本地全量解析。
+
+### 三、查询字段列表（smartsheet fields list）
+
+查询指定子表的字段（列）信息。
+
+> **使用场景分工**：
+> - `wecom-cli smartsheet sheets list`：首次了解文档结构，需要获取**子表列表**概览（子表名称、类型、行列数等）；其 `fields` 仅为轻量预览，且大表可能不返回
+> - `wecom-cli smartsheet fields list`（本接口）：已知目标子表，需要**分页或过滤**查询字段详情，或需要字段属性、选项、完整字段信息时
+
+```bash
+wecom-cli smartsheet fields list --json '{"docid": "<docid>", "sheet_title": "<子表名称>"}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 子表名称，用于定位目标子表 |
+| `limit` | uint32 | 是 | 分页条数（0～1000） |
+| `cursor` | string | 否 | 分批拉取游标 |
+| `field_titles` | string[] | 否 | 按字段名称过滤要返回的列 |
+
+> 解析返回值前查阅 `references/smart-sheet-field-types.md`
+
+---
+
+### 四、查询视图列表（smartsheet views list）
+
+查询指定子表的视图列表。
+
+```bash
+wecom-cli smartsheet views list --json '{"docid": "<docid>", "sheet_title": "<子表名称>"}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 子表名称，用于定位目标子表 |
+| `limit` | uint32 | 是 | 分页条数（0～1000） |
+| `cursor` | string | 否 | 分批拉取游标 |
+
+> 解析返回值前查阅 `references/smart-sheet-view-types.md`
+
+---
+
+### 五、查询图表列表（smartsheet charts list）
+
+查询指定仪表盘子表的图表列表。
+
+```bash
+wecom-cli smartsheet charts list --json '{"docid": "<docid>", "sheet_title": "<仪表盘子表名称>"}'
+```
+
+**请求参数 (JSON 格式传入)：**
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `docid` | string | 是 | 文档 ID |
+| `sheet_title` | string | 是 | 仪表盘子表名称 |
+| `limit` | uint32 | 是 | 分页条数（0～1000） |
+| `cursor` | string | 否 | 分批拉取游标 |
+
+> 解析返回值前查阅 `references/smart-sheet-chart-types.md`

package/templates/shared/wecomcli-smartsheet/references/smart-sheet-record-values.md

@@ -0,0 +1,201 @@
+# 记录值（Record Value）类型参考
+
+本文件主要说明 `wecom-cli smartsheet records add/update/delete` 中记录值的写入格式。记录的 `fields` / `values` 是一个 key-value 映射，key 为字段名，value 的格式取决于字段类型。
+
+> **与 `records query` 返回值区分**：`wecom-cli smartsheet records query` 是 SQL 查询接口，命令返回体外层为 `errcode` + `values string[]`；每个 `values[i]` 解析后读取其中的 `rows`。SQL 中用字段名查询，解析后的 `rows` key 默认也是字段名；解析查询结果时以 `references/smart-sheet-read.md` 的记录读取章节为准，不要把下表的写入格式原样套用到 SQL 查询返回。
+
+| 字段类型短枚举值 | value 格式 | 示例 |
+| --- | --- | --- |
+| `text` | string | `"文本字符串"` |
+| `number` | double 数值 | `123.45` |
+| `checkbox` | bool 布尔值 | `true` |
+| `date_time` | string | 必须严格按照 `"YYYY-MM-DD HH:mm:ss"` 标准时间格式 |
+| `image` | CellImageValue 数组 | `[{"id": "xxx", "title": "图片", "imageUrl": "https://..."}]` |
+| `attachment` | CellAttachmentValue 数组 | `[{"id": "xxx", "title": "文件名", "fileUrl": "https://..."}]` |
+| `user` | CellUserValue 数组 | 读取时返回 `[{"userId": "<userid>", "userName": "<姓名>"}]`；写入时优先传 `userName` 写入（若报错则改传 `userId`，通过 `wecomcli-contact` 技能获取） |
+| `url` | CellUrlValue 数组 | `[{"text": "链接名", "link": "https://..."}]` |
+| `select` | Option 数组 | `[{"id": "服务端返回的选项ID", "text": "选项A"}]` |
+| `progress` | double（0~100） | `75.5` |
+| `phone_number` | string | `"<phone_number>"` |
+| `email` | string | `"<email>"` |
+| `single_select` | Option 数组 | `[{"id": "服务端返回的选项ID", "text": "选项A"}]` |
+| `reference` | CellReferenceValue 数组 | `[{"record_id": "rec_xxx"}]`（关联的记录 ID） |
+| `location` | CellLocationValue 数组 | `[{"id": "<腾讯地图给的UID>", "source_type": 1, "title": "<地点名称>", "latitude": "<纬度>", "longitude": "<经度>", "address": "<详细地址>"}]` |
+| `autonumber` | 只读 | 系统自动生成，不可写入 |
+| `currency` | double | `99.99` |
+| `wwgroup` | CellGroupValue 数组 | `[{"chat_id": "<chat_id>"}]` |
+| `percentage` | double（0~1） | `0.85`（显示为 85%） |
+| `barcode` | string | `"<barcode_text>"` |
+
+---
+
+## 上传附件到文档空间
+
+根据文件类型选择上传命令，并获取文件对应的 URL：
+
+- 图片使用 `wecom-cli smartsheet images upload`。
+- PDF、Office 文件、`.zip` 压缩包等非图片文件使用 `wecom-cli smartsheet files upload`。
+
+写入智能表格的图片字段（`CellImageValue.imageUrl`）或文件字段（`CellAttachmentValue.fileUrl`）时，必须先通过对应命令将文件上传到目标智能表格所在文档空间，再把返回的 `url` 写入记录字段。两个命令的参数完全相同：
+
+```bash
+# 图片
+wecom-cli smartsheet images upload --json '{"media_id": "<media_id>", "docid": "<文档ID>"}'
+
+# 非图片文件
+wecom-cli smartsheet files upload --json '{"media_id": "<media_id>", "docid": "<文档ID>"}'
+```
+
+**入参：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `media_id` | string | 是 | 媒体文件 ID，用户的消息中主动提供，或通过 `wecomcli-media` 的 `media upload` 获取 |
+| `docid` | string | 是 | 目标智能表格的文档 ID |
+
+**出参：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | string | 上传后的文件访问 URL。图片返回直接图片资源 URL，通常形如 `https://w...qpic.cn/...`；非图片文件返回文件分享链接，通常形如 `https://d...qq.com/...?k=...` |
+
+**调用示例：**
+
+```bash
+# 上传图片
+wecom-cli smartsheet images upload --json '{"media_id": "mcabc123...", "docid": "a1_xxx"}'
+
+# 上传非图片文件
+wecom-cli smartsheet files upload --json '{"media_id": "mcabc123...", "docid": "a1_xxx"}'
+```
+
+---
+
+## 各类型 CellValue 详细结构
+
+### CellUserValue（人员）
+
+```json
+[{ "userId": "<userid>", "userName": "<姓名>" }]
+```
+
+> **读取与写入规范**：
+> - **读取**：始终返回 `userId` 和 `userName`。
+> - **写入**：优先支持直接传 `userName` 写入（如 `[{"userName": "张三"}]`）。如果传 `userName` 报错（例如姓名错误或存在同名人员），则**必须**使用 `wecomcli-contact` 技能搜索该人员的 `userid`，再通过 `userId` 进行重试写入（如 `[{"userId": "xxx"}]`）。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `userId` | string | userid。读取时必返；写入时，若按 `userName` 写入失败，则必须通过 `wecomcli-contact` 获取 `userid` 并传入此字段 |
+| `userName` | string | 姓名。读取时必返；写入时，优先直接传入此字段进行写入 |
+
+### CellUrlValue（超链接）
+
+```json
+[{ "text": "<链接名>", "link": "<url>" }]
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `text` | string | 链接显示文本 |
+| `link` | string | 链接地址 |
+
+### CellImageValue（图片）
+
+```json
+[{ "title": "图片名", "imageUrl": "https://..." }]
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | string | 图片标题 |
+| `imageUrl` | string | 图片 URL。通过 `wecom-cli smartsheet images upload` 上传图片后，取返回的 `url` 写入。详见“上传附件到文档空间” |
+
+### CellAttachmentValue（文件）
+
+```json
+[{ "title": "文件名.pdf", "fileUrl": "https://..." }]
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `title` | string | 文件名（读取返回字段，写入可不传） |
+| `fileUrl` | string | 文件 URL。通过 `wecom-cli smartsheet files upload` 上传非图片文件后，取返回的 `url` 写入。详见“上传附件到文档空间” |
+
+### CellLocationValue（地理位置）
+
+```json
+[{
+  "id": "<腾讯地图的UID>", // 必填，由腾讯地图提供，不可捏造
+  "source_type": 1, // 来自腾讯地图
+  "title": "<地点名称>",
+  "latitude": "<纬度>",
+  "longitude": "<经度>",
+  "address": "<详细地址>"
+}]
+```
+
+> 目前没有接口获取腾讯地图位置信息，故目前无法插入地图信息。若用到相关功能，请提醒用户手动插入。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | string | **必填且不能为空**。|
+| `source_type` | int | **必填**。目前只支持填入1，表示来自腾讯地图 |
+| `title` | string | 位置名称 |
+| `latitude` | string | 纬度 |
+| `longitude` | string | 经度 |
+| `address` | string | 详细地址 |
+
+### CellReferenceValue（关联）
+
+```json
+[{ "record_id": "rec_001" }]
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `record_id` | string | 关联的记录 ID |
+
+### CellGroupValue（群）
+
+```json
+[{ "chat_id": "<chat_id>" }]
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `chat_id` | string | 群聊 ID |
+
+### 条码（barcode）
+
+```json
+"<barcode_text>"
+```
+
+条码字段直接传入条码内容字符串，例如：`"BARCODE-TEST-001"`
+
+### 电话（phone_number）
+
+电话字段直接传字符串：
+
+```json
+"13800138000"
+```
+
+或：
+
+```json
+"0755-12345678"
+```
+
+禁止写成数组，禁止写成 `CellTextValue`。只允许数字和合法分隔符，禁止写入 `x`、`*`、`#`、中文占位符或脱敏号码。如果用户提供`138xxxx0001`、`138****0001` 等脱敏号码，需要用简洁自然语言询问用户选择：转换为文本字段，或统一转为纯数字占位号码（如 `13800000001`、`13800000002`，同一批内保持唯一）；不得自行猜测。
+
+### Option（单选/多选）
+
+```json
+[{ "id": "选项ID", "text": "选项文本" }]
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | string | 选项 ID（必须使用服务端返回的真实 ID） |
+| `text` | string | 选项文本 |