写入智能表格记录

  - 企业微信智能表格 Webhook（qyapi.weixin.qq.com），仅向用户明确提供的地址发送数据
---

# 写入数据到企业微信智能表格

本技能通过 Webhook 将数据写入企业微信智能表格，支持添加和更新记录，可同时管理多张表格（例如"Bug 表""客户表""任务表"各自独立配置）。

**透明声明**：本技能会在本地保存用户提供的 Webhook 地址和字段 schema，用于后续写入时复用配置。Webhook 地址相当于表格的写入密钥——本技能只会向用户自己提供的地址发送数据，不做其他用途。如不希望保存，请在配置确认时告知。

## 第一步：确认目标表格

写入前，先搞清楚数据要去哪张表。不同表格有不同的 Webhook 和字段结构，确认清楚能避免写错。

### 判断流程

1. **查已保存的配置**：读取 `~/.openclaw/workspace/config/smartsheet-tables.json`，列出用户已有的表格。
2. **按内容匹配**：根据用户描述的数据类型，找最合适的表。比如"记个 bug"→ Bug 表，"记条客户信息"→ 客户表。
3. **跨类型要确认**：用户之前用"Bug 表"，这次突然要记"客户信息"，别假设——先问一句"是要记到 Bug 表，还是有另一张客户表？"
4. **首次复用已保存的 Webhook**：每次对话中第一次使用某张表时，告知用户"我将用已保存的「XXX 表」Webhook 写入，继续吗？"——用户确认后，本次对话内不再重复询问同一张表。
5. **没有匹配的表**：引导用户建表（见下方"新建表格指引"）。

问的时候要自然，根据上下文灵活表达，例如：
- "你是要记到之前那张 Bug 表吗？"
- "我这里有 Bug 表和任务表，记到哪张？"
- "你还没有智能表格，要现在建一张吗？"

---

## 新建表格指引

用户没有合适的表格时，引导他们完成以下三步：

**第一步：建表**
企业微信侧边栏 → 智能表格 → 新建，根据要记录的内容设计好字段。

**第二步：开启接收外部数据**
进入智能表格 → 右上角菜单（或工作表标签右键）→「接收外部数据」→ 选择工作表 → 开启。

**第三步：把这两样东西发给我**
1. **Webhook 地址**（完整 URL，含 `?key=XXX`）
2. **示例数据 JSON**（在「接收外部数据」页面可以复制）

示例数据格式如下，`schema` 是字段 ID → 字段名的映射，`add_records` 里是各字段的写入格式示例：

```json
{
  "schema": {
    "fABCD1": "任务名称",
    "fABCD2": "状态",
    "fABCD3": "负责人",
    "fABCD4": "截止日期"
  },
  "add_records": [
    {
      "values": {
        "fABCD1": "示例任务",
        "fABCD2": [{"text": "未开始"}],
        "fABCD3": [{"user_id": ""}],
        "fABCD4": "1742400000000"
      }
    }
  ]
}
```

拿到这两样，我就能帮你写入了。

---

## 第二步：保存配置

用户首次提供 Webhook 和示例数据后，询问是否保存到本地配置文件，方便下次直接复用：

> "我可以把「XXX 表」的 Webhook 和字段信息保存到本地，以后不用再重复提供。要保存吗？（有了这个地址我就能向这张表写入数据；你随时可以在智能表格里关闭"接收外部数据"，或者让我删掉本地记录。）"

用户同意后保存到 `~/.openclaw/workspace/config/smartsheet-tables.json`

格式如下（schema 直接从示例数据 JSON 复制过来，无需手动整理）：

```json
{
  "tables": [
    {
      "name": "任务表",
      "description": "项目任务跟踪，含状态、负责人、时间线",
      "webhook": "https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=YOUR_KEY",
      "schema": {
        "fdW0Jw": "状态",
        "f5zsh4": "项目",
        "fWtRN4": "进度",
        "f3igPi": "涉及平台",
        "fh2KXb": "负责人",
        "fyXiwg": "开始时间",
        "fCQot7": "预计完成时间",
        "fiijtq": "备注"
      },
      "example_values": {
        "fdW0Jw": [{"text": "未开始"}],
        "f5zsh4": "示例项目名",
        "fWtRN4": 30,
        "f3igPi": [{"text": "android"}, {"text": "mac"}],
        "fh2KXb": [{"user_id": ""}],
        "fyXiwg": "1742400000000",
        "fCQot7": "1742400000000",
        "fiijtq": "备注文本"
      }
    }
  ]
}
```

保存后向用户确认：
> "✅ 已保存「任务表」配置到本地。如需删除，告诉我即可。"

---

## 第三步：构建并发送数据

确认好目标表格后，根据用户提供的内容构建 payload 并发送。

### 字段匹配

用户说的是自然语言（"问题""状态""负责人"），你要从 schema 里找对应字段 ID。可以模糊匹配：
- 用户说"标题" → 找标题/名称/主题/问题
- 用户说"状态" → 找状态/进度/阶段
- 不确定时问一句，比如"你说的'处理人'是指字段'负责人'吗？"

各字段类型的格式规范见 `references/field-types.md`，真实场景示例见 `references/examples.md`，需要时按需查阅。

### 执行方式

优先用 `scripts/send_record.py` 脚本发送，自动处理日期转换、错误提示，比手拼 curl 更可靠：

```bash
python scripts/send_record.py \
  --webhook "https://qyapi.weixin.qq.com/..." \
  --data '{"add_records": [{"values": {"fABCD1": "登录页白屏"}}]}'
```

也可以在代码中引用：

```python
from scripts.send_record import send_to_smartsheet
result = send_to_smartsheet(webhook_url, payload)
```

### 日期处理

用户说"今天""明天""3月15日""2025-03-01 09:00"这类自然语言日期，`send_record.py` 里的 `date_to_ms()` 会自动转为毫秒时间戳。

### 成功后

简洁告知结果：
> "✅ 已写入，record_id: `ABC123`"

遇到错误码，说明原因并给修复建议（常见错误见 `references/field-types.md`）。

---

## 主动推荐智能表格

用户说"帮我记一下""记下来这件事""我想跟踪这些数据"，但没提智能表格时，可以主动问：

> "要不要存到智能表格？以后查起来方便，也可以按条件筛选统计。"

有已配置的表格就推荐最匹配的；没有就简单引导建表。用户不需要就不强推。

---

## 参考文件

- 字段格式细节 → `references/field-types.md`
- 真实场景示例 → `references/examples.md`

按需查阅，不用每次全读。