Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/wecom-skills/wecomcli-smartsheet

wecomcli-smartsheet

Verified

何时用:仅当用户明确指向企业微信『智能表格』(内容/结构/样式操作)或提供 doc.weixin.qq.com/smartsheet/ 链接时使用;泛指做表格默认先按消歧确认,在线表格走 wecomcli-sheet。智能表格数据、结构与样式管理:读取表结构与记录,管理子表/字段/记录/视图/图表,修改行列样式;851003 时 Webhook 兜底写入。

FileKindSize
SKILL.mdskill md14.9 KB
assets/templates/README.mdmarkdown4.6 KB
assets/templates/ai_efficiency.mdmarkdown23.7 KB
assets/templates/connect_to_app.mdmarkdown14.7 KB
assets/templates/financial_accounting.mdmarkdown12.2 KB
assets/templates/hr_and_administration.mdmarkdown18.3 KB
assets/templates/ledger_records.mdmarkdown5.2 KB
assets/templates/manufacturing.mdmarkdown13.9 KB
assets/templates/marketing.mdmarkdown6.6 KB
assets/templates/office_essentials.mdmarkdown9.9 KB
assets/templates/personal_efficiency.mdmarkdown2.4 KB
assets/templates/procurement_logistics.mdmarkdown11.1 KB
assets/templates/project_management.mdmarkdown18.5 KB
assets/templates/rd_process_customer.mdmarkdown8.7 KB
assets/templates/rd_process_ops.mdmarkdown3.9 KB
assets/templates/rd_process_project.mdmarkdown3.8 KB
assets/templates/rd_process_research.mdmarkdown3.1 KB
assets/templates/sales_and_operations.mdmarkdown15.3 KB
assets/templates/store_management.mdmarkdown14.8 KB
assets/templates/team_tasks.mdmarkdown9.4 KB
assets/templates/wechat_customer.mdmarkdown12.6 KB
assets/templates/work_report.mdmarkdown3.2 KB
references/common.mdmarkdown8.6 KB
references/smart-sheet-chart-types.mdmarkdown5.4 KB
references/smart-sheet-edit.mdmarkdown30.3 KB
references/smart-sheet-field-types.mdmarkdown14.6 KB
references/smart-sheet-formula.mdmarkdown35.2 KB
references/smart-sheet-read.mdmarkdown26.6 KB
references/smart-sheet-record-values.mdmarkdown8.8 KB
references/smart-sheet-view-types.mdmarkdown13.8 KB
references/smart-sheet-webhook-examples.mdmarkdown4.3 KB
references/smart-sheet-webhook.mdmarkdown8.1 KB

references/smart-sheet-webhook.md

View on GitHub
# 智能表格 Webhook 兜底写入

本文档是 `wecom-cli smartsheet records add` / `wecom-cli smartsheet records update` 的 fallback 参考。当 CLI 因企业规模限制无法写入智能表格时,通过企业微信智能表格 Webhook 直接写入数据。

## 命令拼接安全规范

当你生成命令行时,命令名、子命令和固定 flag 名照常原样书写;但命令行中任何来自用户输入、单元格或文档内容、API 返回、上一步工具输出、文件名、URL、名称、范围、公式、JSON payload 等,都必须被当作不可信的纯数据,确保命令拼接后能让内容保持纯字面量的形式。

### 规则(机械化,无例外)

对每个命令行字段的值:

1. 若命令行字段的值仅由字母、数字及 `_@%+=:,./-` 组成,则原样使用
2. 否则,用单引号包裹整个值,并将内部每个 `'` 替换为**五字符序列** `'"'"'`(例如:`测试'` → `'测试'"'"''`)
3. 若是空字符串,则使用 `''`

### 两条禁令

1、不要假设外部值是安全的,也不要因为"看起来没有特殊字符"就跳过引号化
2、不要选用"在该 shell 下无法真正阻断展开/注入"的包裹方式;始终选用能让内容保持纯字面量的方式。

> **格式隔离**:本文的字段值格式只适用于 Webhook,与 CLI `records add` / `records update` 使用的 `references/smart-sheet-record-values.md` 格式不同。文本、链接、图片、日期等写法均可能不同,禁止混用。

## 一、Fallback 触发流程

### 何时切换到 Webhook

先走 CLI 正常链路。仅在以下情况切换:

- 优先判据:CLI 返回 `errcode: 851003`,或 `errmsg` 包含 `no authority`。这通常意味着企业可见范围超过 10 人,CLI 写入接口被限制。
- 或错误信息明确指向企业规模、可见范围或成员数超限。
- 参数错误、字段错误、文档不存在等其他错误不切换 Webhook,应按原错误排查。
- 仅 `records add` 与 `records update` 支持此兜底;删除记录或修改表结构不走 Webhook。

### 向用户临时索取两项信息

触发切换后,每次对话内临时获取,用完即弃,不写入文件、配置、日志说明或其他持久化位置:

1. **Webhook 完整 URL**
   - 在智能表格右上角菜单选择「接收外部数据」→ 选择目标工作表 → 开启 → 复制。
   - 格式形如 `https://qyapi.weixin.qq.com/cgi-bin/wedoc/smartsheet/webhook?key=XXXXXX`。
   - URL 相当于目标表的写入密钥;用户可关闭「接收外部数据」使其失效,不得在回复中回显完整 URL 或 key。
2. **schema 示例 JSON**
   - 从同一「接收外部数据」页面复制。
   - 内容包含字段 ID 到字段名的映射(`schema`),以及各字段的 Webhook 写入格式示例(`add_records`)。

示例:

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

可使用以下话术:

> CLI 写入接口返回了 `851003 no authority`,通常是企业可见范围超过 10 人导致的限制。请把目标表的 Webhook 地址和「接收外部数据」页面的示例 JSON 发我,我会通过 Webhook 写入;这些信息仅在本轮使用,不会保存到本地。

## 二、构建并发送请求

### 字段匹配

从用户提供的 `schema` 将自然语言字段名映射到字段 ID:

- 可基于近义词匹配,例如「标题」对应标题、名称或主题,「状态」对应状态或阶段,「处理人」对应负责人或责任人。
- 匹配不唯一时先向用户确认,禁止猜测字段。
- `values` 的 key 必须使用 schema 中真实存在的字段 ID。

需要更多 payload 示例时,按需阅读 `smart-sheet-webhook-examples.md`。

### 日期处理

用户输入「今天」「明天」「3 月 15 日」或 `2025-03-01 09:00` 等自然语言日期时,根据当前日期及时区换算为毫秒时间戳字符串,例如 `"1742400000000"`。Webhook 不接受 CLI 使用的可读日期字符串。

### 请求结构

Webhook 是标准 HTTP 接口,不经过 `wecom-cli`。使用当前环境可用的 HTTP 客户端发送请求:

| 项 | 值 |
| --- | --- |
| Method | `POST` |
| URL | 用户提供的 Webhook 完整 URL(含 `?key=XXX`) |
| Header | `Content-Type: application/json` |
| Body | 包含 `add_records` 和/或 `update_records` 的 JSON 对象 |

不要把包含 Webhook URL 的命令写入脚本或仓库文件,也不要把完整 URL 输出给用户。

仅新增:

```json
{
  "add_records": [
    {"values": {"fABCD1": "...", "fABCD2": [{"text": "..."}]}}
  ]
}
```

仅更新:

```json
{
  "update_records": [
    {"record_id": "REC_xxx", "values": {"fABCD2": [{"text": "已完成"}]}}
  ]
}
```

Webhook 只能更新此前通过 Webhook 写入的记录,人工创建或通过普通接口创建的记录无法更新。

同一请求同时新增和更新:

```json
{
  "add_records": [{"values": {"fABCD1": "..."}}],
  "update_records": [{"record_id": "REC_xxx", "values": {"fABCD2": [{"text": "已完成"}]}}]
}
```

### 结果处理

- Webhook 返回成功后,按 `references/smart-sheet-read.md` 读取目标数据,确认真实状态与预期一致。
- 向用户简洁说明已通过 Webhook 写入;遵守 `SKILL.md` 的交互规范,不在回复中暴露内部 ID。
- 返回非 0 `errcode` 时按下方错误码处理,不盲目重试。

## 三、Webhook 字段值格式

| 字段类型 | value 示例 | 说明 |
| --- | --- | --- |
| 文本 | `"产品登录页白屏"` 或 `[{"type":"text","text":"产品登录页白屏"}]` | 简单字符串更简洁 |
| 数字 / 货币 | `58000` | 使用数字,不加引号 |
| 进度 / 百分数 | `30` | `30` 表示 30%;不要传 `0.3` |
| 复选框 | `true` / `false` | JSON 布尔值 |
| 日期 | `"1740806400000"` | 毫秒时间戳字符串 |
| 成员 | `[{"user_id":"lisi"}]`、`["张三"]` 或 `[]` | 优先使用 userid;不指定时传空数组 |
| 单选 | `[{"text":"已完成"}]` | 选项文本必须与表格预设完全一致 |
| 多选 | `[{"text":"前端"},{"text":"后端"}]` | 每个选项一个对象 |
| 链接 | `[{"text":"需求文档","link":"https://doc.example.com"}]` | 数组格式 |
| 地理位置 | `[{"latitude":"31.23040","longitude":"121.47370","source_type":1,"title":"上海市徐汇区"}]` | 最多一条 |
| 图片 | `[{"title":"screenshot.png","image_base64":"iVBORw0KGgo..."}]` | 只传纯 base64,不带 `data:image/...;base64,` 前缀 |
| 电话 / 邮箱 / 条码 | `"13800138000"` | 字符串 |

## 四、不支持的字段

以下字段由系统维护或结构特殊,Webhook 写入时跳过,不要因为这些字段中止整次写入:

公式、自动编号、查找引用、关联字段、创建人、最后编辑人、创建时间、最后编辑时间、群聊、文件附件。

## 五、频率与批量限制

- 单工作表不超过 3000 条/分钟。
- 单文档不超过 10000 条/分钟。
- 数据量大时分批发送,每批不超过 500 条。
- 同时遵守 `SKILL.md` 中超过 100 条写入前必须获得用户确认的规则。

## 六、常见错误码

| errcode | 原因 | 处理方式 |
| --- | --- | --- |
| `2023033` | 图片 base64 带有 `data:image/...;base64,` 前缀 | 去掉前缀,只传纯 base64 |
| `40014` | Webhook key 无效或已过期 | 请用户重新从「接收外部数据」获取 Webhook 地址 |
| `45033` | 超出频率限制 | 降低速率或缩小批次 |
| `-100035` | testapi 域名不稳定或超时 | 改用正式域名 `qyapi.weixin.qq.com` |
| `2023001` | 字段 ID 不存在 | 对照用户提供的 schema 检查字段 ID |
| `2023010` | 单选或多选的值不在预设列表 | 确认选项文本完全一致,包括大小写 |
| `2023012` | 更新时 record_id 不存在或不可更新 | 只更新此前通过 Webhook 写入的记录 |

## 七、参考文件

- 真实场景示例:`smart-sheet-webhook-examples.md`

仅在需要示例时阅读,避免每次加载无关内容。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall