feat: 初始化黄小瓜AI助手记忆仓库

- 核心配置: IDENTITY, USER, SOUL, AGENTS, TOOLS, HEARTBEAT, MEMORY - memory/: 每日总结和临时记录 - skills/: 所有已安装技能 - notes/: 语音配置笔记
2026-04-04 02:42:48 +08:00
parent 2d24fe9b50
commit 691b8cdd0c
115 changed files with 18198 additions and 0 deletions
--- a/skills/tencent-docs/references/smartsheet_references.md
+++ b/skills/tencent-docs/references/smartsheet_references.md
@@ -0,0 +1,1052 @@
+# 智能表格（SmartSheet）工具完整参考文档
+
+腾讯文档智能表格（SmartSheet）提供了一套完整的表格操作 API，支持对工作表、视图、字段、记录进行增删改查操作。
+
+---
+
+## 目录
+
+- [概念说明](#概念说明)
+- [工作表（SubSheet）操作](#工作表subsheet操作)
+  - [smartsheet.list_tables - 列出工作表](#smartsheetlist_tables)
+  - [smartsheet.add_table - 新增工作表](#smartsheetadd_table)
+  - [smartsheet.delete_table - 删除工作表](#smartsheetdelete_table)
+- [视图（View）操作](#视图view操作)
+  - [smartsheet.list_views - 列出视图](#smartsheetlist_views)
+  - [smartsheet.add_view - 新增视图](#smartsheetadd_view)
+  - [smartsheet.delete_view - 删除视图](#smartsheetdelete_view)
+- [字段（Field）操作](#字段field操作)
+  - [smartsheet.list_fields - 列出字段](#smartsheetlist_fields)
+  - [smartsheet.add_fields - 新增字段](#smartsheetadd_fields)
+  - [smartsheet.update_fields - 更新字段](#smartsheetupdate_fields)
+  - [smartsheet.delete_fields - 删除字段](#smartsheetdelete_fields)
+- [记录（Record）操作](#记录record操作)
+  - [smartsheet.list_records - 列出记录](#smartsheetlist_records)
+  - [smartsheet.add_records - 新增记录](#smartsheetadd_records)
+  - [smartsheet.update_records - 更新记录](#smartsheetupdate_records)
+  - [smartsheet.delete_records - 删除记录](#smartsheetdelete_records)
+- [枚举值参考](#枚举值参考)
+- [字段值格式参考](#字段值格式参考)
+- [典型工作流示例](#典型工作流示例)
+
+---
+
+## 概念说明
+
+| 概念 | 说明 |
+|------|------|
+| `file_id` | 智能表格文档的唯一标识符，每个文档有唯一的 file_id |
+| `sheet_id` | 工作表 ID，一个智能表格文档可包含多个工作表 |
+| `view_id` | 视图 ID，每个工作表可有多个视图（网格视图、看板视图等） |
+| `field_id` | 字段 ID，对应表格的列 |
+| `record_id` | 记录 ID，对应表格的行 |
+
+**层级关系**：`file_id（文档）` → `sheet_id（工作表）` → `view_id（视图）` / `field_id（字段）` / `record_id（记录）`
+
+---
+
+## 工作表（SubSheet）操作
+
+### smartsheet.list_tables
+
+**功能**：列出文档下的所有工作表，返回工作表基本信息列表。
+
+**使用场景**：
+- 查看一个智能表格文档中有哪些工作表
+- 获取 sheet_id 以便后续操作字段、记录、视图
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+
+**返回字段**：
+
+| 字段                    | 类型 | 说明 |
+|-----------------------|------|------|
+| `sheets`              | array | 工作表列表 |
+| `sheets[].sheet_id`   | string | 工作表唯一标识符 |
+| `sheets[].title`      | string | 工作表名称 |
+| `sheets[].is_visible` | bool | 工作表可见性 |
+| `error`               | string | 错误信息，操作失败时返回 |
+| `trace_id`            | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id"
+}
+```
+
+**返回示例**：
+
+```json
+{
+  "sheets": [
+    {
+      "sheet_id": "sheet_abc123",
+      "title": "任务列表",
+      "is_visible": true
+    },
+    {
+      "sheet_id": "sheet_def456",
+      "title": "已归档",
+      "is_visible": false
+    }
+  ],
+  "error": "",
+  "trace_id": "trace_xyz"
+}
+```
+
+---
+
+### smartsheet.add_table
+
+**功能**：在文档中新增工作表，支持设置工作表名称和初始配置。
+
+**使用场景**：
+- 在已有智能表格文档中添加新的工作表（如新增"2024年Q2"工作表）
+- 按业务模块拆分数据到不同工作表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `properties` | object | ✅ | 工作表属性配置 |
+| `properties.sheet_id` | string | ✅ | 工作表名称（注意：此字段实际含义为工作表名称） |
+| `properties.title` | string | | 工作表标题 |
+| `properties.index` | uint32 | | 工作表下标（位置） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `properties` | object | 新创建工作表的属性信息 |
+| `properties.sheet_id` | string | 工作表名称 |
+| `properties.title` | string | 工作表标题 |
+| `properties.index` | uint32 | 工作表下标 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "properties": {
+    "sheet_id": "新工作表",
+    "title": "2024年Q2数据",
+    "index": 1
+  }
+}
+```
+
+---
+
+### smartsheet.delete_table
+
+**功能**：删除指定的工作表。
+
+**使用场景**：
+- 删除不再需要的工作表
+- 清理测试数据工作表
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 要删除的工作表 ID |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息，操作失败时返回 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123"
+}
+```
+
+---
+
+## 视图（View）操作
+
+### smartsheet.list_views
+
+**功能**：列出工作表下的所有视图，返回视图基本信息和配置。
+
+**使用场景**：
+- 查看工作表有哪些视图（网格视图、看板视图）
+- 获取 view_id 以便按视图筛选记录或字段
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_ids` | []string | | 需要查询的视图 ID 数组，不填则返回全部 |
+| `offset` | uint32 | | 分页查询偏移量，默认 0 |
+| `limit` | uint32 | | 分页大小，最大 100 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `views` | array | 视图列表 |
+| `views[].view_id` | string | 视图唯一标识符 |
+| `views[].view_name` | string | 视图名称 |
+| `views[].view_type` | uint32 | 视图类型，枚举值见下方 |
+| `total` | uint32 | 符合条件的视图总数 |
+| `hasMore` | bool | 是否还有更多项 |
+| `next` | uint32 | 下一页偏移量 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**视图类型枚举值**：
+
+| 值 | 说明 |
+|----|------|
+| `1` | 网格视图（grid） |
+| `2` | 看板视图（kanban） |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "offset": 0,
+  "limit": 20
+}
+```
+
+---
+
+### smartsheet.add_view
+
+**功能**：在工作表中新增视图，支持自定义视图名称和类型。
+
+**使用场景**：
+- 为工作表创建看板视图，按状态分组展示任务
+- 创建多个网格视图，分别展示不同筛选条件的数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_title` | string | ✅ | 视图标题 |
+| `view_type` | uint32 | | 视图类型：1-网格视图，2-看板视图 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `view_id` | string | 新创建的视图 ID |
+| `view_title` | string | 视图标题 |
+| `view_type` | uint32 | 视图类型 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "view_title": "按状态分组",
+  "view_type": 2
+}
+```
+
+---
+
+### smartsheet.delete_view
+
+**功能**：删除指定的视图，支持批量删除多个视图。
+
+**使用场景**：
+- 删除不再使用的视图
+- 批量清理多余视图
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_ids` | []string | ✅ | 要删除的视图 ID 列表 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "view_ids": ["view_id1", "view_id2"]
+}
+```
+
+---
+
+## 字段（Field）操作
+
+### smartsheet.list_fields
+
+**功能**：列出工作表的所有字段，返回字段基本信息和类型配置。
+
+**使用场景**：
+- 查看工作表有哪些列（字段）及其类型
+- 获取 field_id 以便后续更新或删除字段
+- 在写入记录前，先了解字段结构和类型
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_id` | string | | 视图 ID，按视图筛选字段 |
+| `field_ids` | []string | | 指定字段 ID 数组 |
+| `field_titles` | []string | | 指定字段标题数组 |
+| `offset` | uint32 | | 偏移量，初始值为 0 |
+| `limit` | uint32 | | 分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | uint32 | 符合条件的字段总数 |
+| `has_more` | bool | 是否还有更多项 |
+| `next` | uint32 | 下一页偏移量 |
+| `fields` | array | 字段列表，详见 FieldInfo 结构 |
+
+**FieldInfo 结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `field_id` | string | 字段唯一 ID |
+| `field_title` | string | 字段标题（列名） |
+| `field_type` | uint32 | 字段类型，枚举值见下方 |
+| `property_*` | object | 字段属性，根据 field_type 不同而不同 |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123"
+}
+```
+
+---
+
+### smartsheet.add_fields
+
+**功能**：批量新增字段（列），支持同时添加多个不同类型的字段。
+
+**使用场景**：
+- 为工作表添加新列，如"优先级"（单选）、"截止日期"（日期）、"负责人"（用户）
+- 初始化工作表结构
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `fields` | []FieldInfo | ✅ | 要添加的字段列表 |
+
+**FieldInfo 参数说明**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field_title` | string | ✅ | 字段标题（列名） |
+| `field_type` | uint32 | ✅ | 字段类型，枚举值见下方 |
+| `property_text` | object | | 文本类型属性（无需额外配置） |
+| `property_number` | object | | 数字类型属性 |
+| `property_checkbox` | object | | 复选框类型属性 |
+| `property_date_time` | object | | 日期时间类型属性 |
+| `property_url` | object | | 超链接类型属性 |
+| `property_select` | object | | 多选类型属性 |
+| `property_single_select` | object | | 单选类型属性 |
+| `property_progress` | object | | 进度类型属性 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `fields` | array | 添加成功的字段列表（含 field_id） |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例（添加多种类型字段）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "fields": [
+      {
+        "field_title": "任务名称",
+        "field_type": 1,
+        "property_text": {}
+      },
+      {
+        "field_title": "优先级",
+        "field_type": 17,
+        "property_single_select": {
+          "options": [
+            { "text": "高", "style": 1 },
+            { "text": "中", "style": 3 },
+            { "text": "低", "style": 4 }
+          ]
+        }
+      },
+      {
+        "field_title": "截止日期",
+        "field_type": 4,
+        "property_date_time": {
+          "format": "yyyy-mm-dd",
+          "auto_fill": false
+        }
+      },
+      {
+        "field_title": "完成进度",
+        "field_type": 14,
+        "property_progress": {
+          "decimal_places": 0
+        }
+      },
+      {
+        "field_title": "是否完成",
+        "field_type": 3,
+        "property_checkbox": {
+          "checked": false
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.update_fields
+
+**功能**：批量更新字段属性，支持修改字段名称和配置信息。
+
+**使用场景**：
+- 修改字段标题（列名）
+- 更新单选/多选字段的选项列表
+- 修改数字字段的精度配置
+
+> ⚠️ **注意**：`field_type`（字段类型）不允许被更新，但更新时必须传入原字段类型值。
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `fields` | []FieldInfo | ✅ | 要更新的字段列表，必须包含 field_id |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `fields` | array | 更新成功的字段列表 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例（修改字段标题和选项）**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "fields": [
+      {
+        "field_id": "field_id_001",
+        "field_title": "任务状态",
+        "field_type": 17,
+        "property_single_select": {
+          "options": [
+            { "text": "待处理", "style": 7 },
+            { "text": "进行中", "style": 3 },
+            { "text": "已完成", "style": 4 },
+            { "text": "已取消", "style": 1 }
+          ]
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.delete_fields
+
+**功能**：批量删除字段（列），支持同时删除多个字段。
+
+**使用场景**：
+- 删除不再需要的列
+- 清理冗余字段
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `field_ids` | []string | ✅ | 要删除的字段 ID 数组 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "field_ids": ["field_id_001", "field_id_002"]
+}
+```
+
+---
+
+## 记录（Record）操作
+
+### smartsheet.list_records
+
+**功能**：分页列出工作表记录（行），支持排序和按字段筛选。
+
+**使用场景**：
+- 读取工作表中的数据
+- 按特定字段排序查看数据
+- 分页获取大量数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `view_id` | string | | 视图 ID，按视图筛选记录 |
+| `record_ids` | []string | | 指定记录 ID 数组，精确查询 |
+| `field_titles` | []string | | 只返回指定字段标题的值，不填则返回全部字段 |
+| `sort` | []Sort | | 排序配置 |
+| `offset` | uint32 | | 偏移量，初始值为 0 |
+| `limit` | uint32 | | 分页大小，最大 100；不填或为 0 时，总数 >100 返回 100 条，否则返回全部 |
+
+**Sort 排序配置**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field_title` | string | ✅ | 需要排序的字段标题 |
+| `desc` | bool | | 是否降序，默认 false（升序） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total` | uint32 | 符合条件的记录总数 |
+| `has_more` | bool | 是否还有更多项 |
+| `next` | uint32 | 下一页偏移量 |
+| `records` | array | 记录列表，详见 RecordInfo 结构 |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**RecordInfo 结构**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `record_id` | string | 记录唯一 ID |
+| `field_values` | map | 字段值映射，key 为字段标题，value 为字段值 |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "field_titles": ["任务名称", "优先级", "截止日期"],
+  "sort": [
+    { "field_title": "截止日期", "desc": false }
+  ],
+  "offset": 0,
+  "limit": 50
+}
+```
+
+---
+
+### smartsheet.add_records
+
+**功能**：批量添加记录（行），支持同时添加多条记录数据。
+
+**使用场景**：
+- 批量导入数据到工作表
+- 添加新任务、新条目
+- 从其他数据源同步数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `records` | []AddRecord | ✅ | 要添加的记录列表 |
+
+**AddRecord 结构**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `field_values` | map | ✅ | 字段值映射，key 为字段标题，value 为字段值（格式见下方） |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `records` | array | 添加成功的记录列表（含 record_id） |
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "records": [
+      {
+        "field_values": {
+          "任务名称": [{"text": "完成需求文档", "type": "text"}],
+          "优先级": [{"text": "高"}],
+          "截止日期": "1720000000000",
+          "完成进度": 30,
+          "是否完成": false
+        }
+      },
+      {
+        "field_values": {
+          "任务名称": [{"text": "代码评审", "type": "text"}],
+          "优先级": [{"text": "中"}],
+          "截止日期": "1720086400000",
+          "完成进度": 0,
+          "是否完成": false
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.update_records
+
+**功能**：批量更新记录，支持修改多条记录的字段值。
+
+**使用场景**：
+- 更新任务状态、进度
+- 修改记录中的某些字段值
+- 批量修改多条数据
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `records` | []RecordInfo | ✅ | 要更新的记录列表，必须包含 record_id |
+
+**RecordInfo 参数说明**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `record_id` | string | ✅ | 记录 ID，标识要更新哪条记录 |
+| `field_values` | map | ✅ | 要更新的字段值映射 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "records": [
+      {
+        "record_id": "record_id_001",
+        "field_values": {
+          "完成进度": 100,
+          "是否完成": true,
+          "优先级": [{"text": "高"}]
+        }
+      }
+    ]
+}
+```
+
+---
+
+### smartsheet.delete_records
+
+**功能**：批量删除记录（行），支持同时删除多条指定的记录。
+
+**使用场景**：
+- 删除已完成或过期的任务记录
+- 清理测试数据
+- 批量删除多条记录
+
+**请求参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `file_id` | string | ✅ | 智能表格文档的唯一标识符 |
+| `sheet_id` | string | ✅ | 工作表 ID |
+| `record_ids` | []string | ✅ | 要删除的记录 ID 列表 |
+
+**返回字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | string | 错误信息 |
+| `trace_id` | string | 调用链追踪 ID |
+
+**调用示例**：
+
+```json
+{
+  "file_id": "your_file_id",
+  "sheet_id": "sheet_abc123",
+  "record_ids": ["record_id_001", "record_id_002", "record_id_003"]
+}
+```
+
+---
+
+## 枚举值参考
+
+### 字段类型（field_type）
+
+| 枚举值 | 类型名称 | 对应 property 字段 | 说明 |
+|--------|---------|-------------------|------|
+| `1` | 文本 | `property_text` | 普通文本，无需额外配置 |
+| `2` | 数字 | `property_number` | 整数或浮点数 |
+| `3` | 复选框 | `property_checkbox` | 布尔值 true/false |
+| `4` | 日期 | `property_date_time` | 毫秒时间戳字符串 |
+| `5` | 图片 | `property_image` | 图片 ID 数组 |
+| `8` | 超链接 | `property_url` | URL 数组 |
+| `9` | 多选 | `property_select` | 选项数组（可多选） |
+| `10` | 创建人 | `property_user` | 系统自动填充，无需配置 |
+| `11` | 最后编辑人 | `property_modified_user` | 系统自动填充，无需配置 |
+| `12` | 创建时间 | `property_created_time` | 系统自动填充，无需配置 |
+| `13` | 最后编辑时间 | `property_modified_time` | 系统自动填充，无需配置 |
+| `14` | 进度 | `property_progress` | 整数或浮点数（百分比） |
+| `15` | 电话 | `property_phone_number` | 字符串，无需额外配置 |
+| `16` | 邮件 | `property_email` | 字符串，无需额外配置 |
+| `17` | 单选 | `property_single_select` | 选项数组（只能单选） |
+| `18` | 关联 | - | 关联其他记录，值为 record_id 字符串数组 |
+| `25` | 自动编号 | - | 系统自动生成编号，无需手动配置 |
+| `26` | 货币 | - | 浮点数，表示货币金额 |
+| `28` | 百分比 | - | 浮点数，如 0.75 表示 75% |
+
+### 视图类型（view_type）
+
+| 枚举值 | 说明 |
+|--------|------|
+| `1` | 网格视图（grid）- 传统表格形式 |
+| `2` | 看板视图（kanban）- 按列分组展示 |
+
+### 选项颜色（style）
+
+| 枚举值 | 颜色 |
+|--------|------|
+| `1` | 红色 |
+| `2` | 橘黄色 |
+| `3` | 蓝色 |
+| `4` | 绿色 |
+| `5` | 紫色 |
+| `6` | 粉色 |
+| `7` | 灰色 |
+| `8` | 白色 |
+
+### 超链接展示样式（UrlFieldProperty.type）
+
+| 枚举值 | 说明 |
+|--------|------|
+| `0` | 未知 |
+| `1` | 文字 |
+| `2` | 图标文字 |
+
+---
+
+## 字段值格式参考
+
+在 `add_records` 和 `update_records` 中，`field_values` 的 value 格式因字段类型而异：
+
+| 字段类型 | 值格式 | 示例                                                         |
+|---------|--------|------------------------------------------------------------|
+| 文本（1） | JSON Array of TextValue | `[{"text": "内容", "type": "text"}]`                         |
+| 数字（2） | number | `42` 或 `3.14`                                              |
+| 复选框（3） | bool | `true` 或 `false`                                           |
+| 日期（4） | string（毫秒时间戳） | `"1720000000000"`                                          |
+| 图片（5） | JSON Array of ImageIDValue | `[{"image_id": "图片id"}]`                                   |
+| 超链接（8） | JSON Array of UrlValue | `[{"text": "链接文字", "type": "url", "link": "https://..."}]` |
+| 多选（9） | JSON Array of OptionValue | `[{"text": "选项1"}, {"text": "选项2"}]`                       |
+| 进度（14） | number | `75` 或 `75.5`                                              |
+| 电话（15） | string | `"13800138000"`                                            |
+| 邮件（16） | string | `"user@example.com"`                                       |
+| 单选（17） | JSON Array of OptionValue（单个） | `[{"text": "选项文字"}]`                                       |
+| 关联（18） | array string | `["record_id_1", "record_id_2"]`                           |
+| 自动编号（25） | JSON(AutoNumberValue) | `{"seq": "1", "text": "编号内容"}`                             |
+| 货币（26） | double | `99.99`                                                    |
+| 百分比（28） | double | `0.75`（表示 75%）                                             |
+
+### TextValue 结构
+
+```json
+{
+  "text": "文本内容",
+  "type": "text"
+}
+```
+
+### UrlValue 结构
+
+```json
+{
+  "text": "链接显示文字",
+  "type": "url",
+  "link": "https://example.com"
+}
+```
+
+### OptionValue 结构
+
+```json
+{
+  "id": "选项ID（可选）",
+  "text": "选项文字",
+  "style": 3
+}
+```
+
+> ⚠️ **注意**：写入记录时，单选/多选字段的 `text` 必须与字段属性中已定义的选项文字完全匹配，否则可能写入失败。
+
+---
+
+## 字段属性（Property）详细说明
+
+### NumberFieldProperty（数字字段属性）
+
+```json
+{
+  "decimal_places": 2,
+  "use_separate": true
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `decimal_places` | uint32 | 小数点位数（精度） |
+| `use_separate` | bool | 是否使用千位符（如 1,000） |
+
+### CheckboxFieldProperty（复选框字段属性）
+
+```json
+{
+  "checked": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `checked` | bool | 新增记录时是否默认勾选 |
+
+### DateTimeFieldProperty（日期时间字段属性）
+
+```json
+{
+  "format": "yyyy-mm-dd",
+  "auto_fill": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `format` | string | 日期格式，支持格式见下方 |
+| `auto_fill` | bool | 新建记录时是否自动填充当前时间 |
+
+**支持的日期格式**：
+
+| 格式字符串 | 示例 |
+|-----------|------|
+| `yyyy"年"m"月"d"日"` | 2018 年 4 月 20 日 |
+| `yyyy-mm-dd` | 2018-04-20 |
+| `yyyy/m/d` | 2018/4/20 |
+| `m"月"d"日"` | 4 月 20 日 |
+| `[$-804]yyyy"年"m"月"d"日" dddd` | 2018 年 4 月 20 日 星期五 |
+| `yyyy"年"m"月"d"日" hh:mm` | 2018 年 4 月 20 日 14:00 |
+| `yyyy-mm-dd hh:mm` | 2018-04-20 14:00 |
+| `m/d/yyyy` | 4/20/2018 |
+| `d/m/yyyy` | 20/4/2018 |
+
+### UrlFieldProperty（超链接字段属性）
+
+```json
+{
+  "type": 1
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | uint32 | 展示样式：0-未知，1-文字，2-图标文字 |
+
+### SelectFieldProperty（多选字段属性）
+
+```json
+{
+  "options": [
+    { "id": "opt_001", "text": "选项A", "style": 3 },
+    { "id": "opt_002", "text": "选项B", "style": 4 }
+  ],
+  "is_multiple": true,
+  "is_quick_add": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `options` | []Option | 选项列表 |
+| `is_multiple` | bool | 是否多选（系统参数，用户无需设置） |
+| `is_quick_add` | bool | 是否允许填写时新增选项（系统参数，用户无需设置） |
+
+### SingleSelectFieldProperty（单选字段属性）
+
+结构与 `SelectFieldProperty` 相同，但只允许单选。
+
+### ProgressFieldProperty（进度字段属性）
+
+```json
+{
+  "decimal_places": 0
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `decimal_places` | uint32 | 小数位数 |
+
+---
+
+## 典型工作流示例
+
+### 工作流一：从零创建表
+
+```
+步骤 1：获取文档的工作表列表
+  → smartsheet.list_tables（获取 sheet_id）
+
+步骤 2：为工作表添加字段
+  → smartsheet.add_fields（添加：任务名称、优先级、负责人、截止日期、状态、进度）
+
+步骤 3：批量添加任务记录
+  → smartsheet.add_records（写入多条任务数据）
+
+步骤 4：删除默认空行和默认列
+  → smartsheet.list_records（获取建表时自动生成的空行 record_id 列表）
+  → smartsheet.delete_records（传入空行 record_ids，批量删除默认空行）
+  → smartsheet.list_fields（获取建表时自动生成的默认列 field_id 列表）
+  → smartsheet.delete_fields（传入默认列 field_ids，批量删除默认列）
+
+步骤 5：（可选）创建看板视图
+  → smartsheet.add_view（view_type=2，按状态分组）
+```
+
+### 工作流二：查询并更新任务状态
+
+```
+步骤 1：列出工作表
+  → smartsheet.list_tables（获取 sheet_id）
+
+步骤 2：查询记录
+  → smartsheet.list_records（获取 record_id 和当前字段值）
+
+步骤 3：更新指定记录
+  → smartsheet.update_records（传入 record_id 和新的字段值）
+```
+
+### 工作流三：读取数据并分析
+
+```
+步骤 1：列出工作表
+  → smartsheet.list_tables
+
+步骤 2：了解字段结构
+  → smartsheet.list_fields（了解有哪些列及其类型）
+
+步骤 3：分页读取所有记录
+  → smartsheet.list_records（offset=0, limit=100）
+  → 若 has_more=true，继续请求下一页（offset=100）
+
+步骤 4：处理数据
+  → 根据 field_values 中的数据进行统计分析
+```
+
+### 工作流四：清理过期数据
+
+```
+步骤 1：列出工作表
+  → smartsheet.list_tables
+
+步骤 2：查询需要删除的记录
+  → smartsheet.list_records（获取目标 record_id 列表）
+
+步骤 3：批量删除记录
+  → smartsheet.delete_records（传入 record_ids 数组）
+```
+
+---
+
+> 📌 **提示**：所有操作都需要先获取 `file_id`（智能表格文档 ID）和 `sheet_id`（工作表 ID）。
+> 可通过 `manage.search_file` 搜索文档获取 `file_id`，再通过 `smartsheet.list_tables` 获取 `sheet_id`。
+
+
+## 注意事项
+
+- **前置条件**：所有 smartsheet.* 工具都需要 `file_id` 和 `sheet_id`，操作前先调用 `smartsheet.list_tables` 获取 sheet_id
+- **图片字段写入**：向图片类型字段（field_type=5）写入数据时，需先调用 `upload_image` 工具上传图片获取 `image_id`，再以 `[{"image_id": "xxx"}]` 格式填入字段值
+- **字段类型不可变**：`update_fields` 时 `field_type` 不能修改，但必须传入原值；支持的字段类型详见字段类型枚举表
+- **记录字段值格式**：不同字段类型的值格式不同，详见上方"字段值格式参考"章节