Wecomcli Smartsheet

# 单元格值格式参考

`smartsheet_add_records`、`+smartsheet_add_records_auto_file` 仅支持**字段标题**作为key。
`smartsheet_update_records`、`+smartsheet_update_records_auto_file` 支持通过 `key_type` 参数指定使用字段标题（`CELL_VALUE_KEY_TYPE_FIELD_TITLE`）或字段 ID（`CELL_VALUE_KEY_TYPE_FIELD_ID`）。

## 各字段类型的值格式

### 1. 文本 (FIELD_TYPE_TEXT)

**必须**使用数组格式，外层方括号不可省略：

```json
"字段标题": [{"type": "text", "text": "内容"}]
```

### 2. 数字 (NUMBER) / 货币 (CURRENCY) / 百分比 (PERCENTAGE) / 进度 (PROGRESS)

直接传数字：

```json
"金额": 100,
"完成率": 0.6,
"进度": 80
```

### 3. 复选框 (CHECKBOX)

直接传布尔值：

```json
"已完成": true
```

### 4. 单选 (SINGLE_SELECT) / 多选 (SELECT)

**必须**使用数组格式，不能直接传字符串：

```json
"优先级": [{"text": "高"}],
"标签": [{"text": "紧急", "style": 17}, {"text": "重要", "style": 12}]
```

已存在的选项应通过 `id` 匹配（`id` 可从 `smartsheet_get_fields` 返回中获取），新增选项时不填 `id`。可附带 `style`（颜色 1-27），对照表如下：

| style | 颜色 |
|-------|------|
| 1 | 浅红1 |
| 2 | 浅橙1 |
| 3 | 浅天蓝1 |
| 4 | 浅绿1 |
| 5 | 浅紫1 |
| 6 | 浅粉红1 |
| 7 | 浅灰1 |
| 8 | 白 |
| 9 | 灰 |
| 10 | 浅蓝1 |
| 11 | 浅蓝2 |
| 12 | 蓝 |
| 13 | 浅天蓝2 |
| 14 | 天蓝 |
| 15 | 浅绿2 |
| 16 | 绿 |
| 17 | 浅红2 |
| 18 | 红 |
| 19 | 浅橙2 |
| 20 | 橙 |
| 21 | 浅黄1 |
| 22 | 浅黄2 |
| 23 | 黄 |
| 24 | 浅紫2 |
| 25 | 紫 |
| 26 | 浅粉红2 |
| 27 | 粉红 |

### 5. 日期时间 (DATE_TIME)

传日期时间字符串，系统自动按东八区转换：

```json
"截止日期": "2026-01-15 14:30:00",
"创建日期": "2026-01-15"
```

支持格式：`YYYY-MM-DD HH:mm:ss`、`YYYY-MM-DD HH:mm`、`YYYY-MM-DD`

### 6. 手机号 (PHONE_NUMBER) / 邮箱 (EMAIL) / 条码 (BARCODE)

直接传字符串：

```json
"电话": "13800138000",
"邮箱": "test@example.com"
```

### 7. 成员 (USER)

数组格式，需传 user_id。**user_id 不是姓名**，必须先通过 `wecomcli-contact` 技能查找目标人员的 `userid`，再填入此处。

具体步骤：先
```bash
wecom-cli contact get_userlist '{}'
```
 获取通讯录成员列表，在返回结果中按姓名/别名筛选出目标人员，取其 `userid` 值填入。

```json
"负责人": [{"user_id": "zhangsan"}]
```

多个成员：

```json
"负责人": [{"user_id": "zhangsan"}, {"user_id": "lisi"}]
```

### 8. 超链接 (URL)

数组格式，目前仅支持一个链接：

```json
"参考链接": [{"type": "url", "text": "官网", "link": "https://example.com"}]
```

### 9. 图片 (IMAGE)

数组格式，支持传入本地路径：

```json
"封面": [{"image_path": "/path/to/img.png"}]
```

### 10. 地理位置 (LOCATION)

数组格式：

```json
"地点": [{"source_type": 1, "id": "地点ID", "latitude": "39.9", "longitude": "116.3", "title": "北京"}]
```

### 11. 文件

数组格式：

```json
"文件": [{"file_path": "/path/to/img.png"}]
```

## 完整添加记录示例

```json
{
    "docid": "DOCID",
    "sheet_id": "SHEETID",
    "records": [{
        "values": {
            "任务名称": [{"type": "text", "text": "完成需求文档"}],
            "优先级": [{"text": "高"}],
            "截止日期": "2026-03-20",
            "完成进度": 30,
            "已完成": false
        }
    }]
}
```



# 智能表格字段类型参考

## 支持的字段类型

| 类型枚举值 | 说明 | 适用场景 |
|---|---|---|
| `FIELD_TYPE_TEXT` | 文本 | 名称、标题、描述、负责人姓名等自由文本 |
| `FIELD_TYPE_NUMBER` | 数字 | 金额、工时、数量等数值 |
| `FIELD_TYPE_CHECKBOX` | 复选框 | 是否完成等布尔值 |
| `FIELD_TYPE_DATE_TIME` | 日期时间 | 截止日期、创建时间等 |
| `FIELD_TYPE_IMAGE` | 图片 | 附件图片 |
| `FIELD_TYPE_USER` | 用户/成员 | 需传入 user_id；仅在明确知道成员 ID 时使用，若只有姓名应用 TEXT |
| `FIELD_TYPE_URL` | 链接 | 超链接 |
| `FIELD_TYPE_SELECT` | 多选 | 标签、分类等可多选的选项 |
| `FIELD_TYPE_PROGRESS` | 进度 | 完成进度（0-100 整数） |
| `FIELD_TYPE_PHONE_NUMBER` | 手机号 | 联系电话 |
| `FIELD_TYPE_EMAIL` | 邮箱 | 电子邮件 |
| `FIELD_TYPE_SINGLE_SELECT` | 单选 | 状态、优先级、严重程度等有固定选项的字段 |
| `FIELD_TYPE_LOCATION` | 位置 | 地理位置 |
| `FIELD_TYPE_CURRENCY` | 货币 | 货币金额 |
| `FIELD_TYPE_PERCENTAGE` | 百分比 | 比率类数值（完成率、转化率） |
| `FIELD_TYPE_BARCODE` | 条码 | 条形码/二维码 |
| `FIELD_TYPE_ATTACHMENT` | 文件 | 文件/附件 |

## 添加字段示例

```json
{
    "docid": "DOCID",
    "sheet_id": "SHEETID",
    "fields": [
        { "field_title": "任务名称", "field_type": "FIELD_TYPE_TEXT" },
        { "field_title": "优先级", "field_type": "FIELD_TYPE_SINGLE_SELECT" },
        { "field_title": "截止日期", "field_type": "FIELD_TYPE_DATE_TIME" },
        { "field_title": "完成进度", "field_type": "FIELD_TYPE_PROGRESS" }
    ]
}
```

## 更新字段注意事项

- `smartsheet_update_fields` **只能更新字段标题**，不能更改字段类型
- `field_type` 必须传字段当前的原始类型
- `field_title` 不能更新为原值（即不能传与当前相同的标题）


# smartsheet_get_records API

查询智能表格中指定子表的记录信息，支持分页读取。支持通过 docid 或文档 URL 定位文档，二者传入其一即可。

## 技能定义

```json
{