@wecom/wecom-openclaw-plugin 2026.6.23-beta.0 → 2026.7.2-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "2026.6.23-beta.0",
+  "version": "2026.7.2-beta.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/wecom-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wecom-doc
-description: 企业微信文档管理技能。支持企业微信文档、表格（在线表格）、智能表格和智能文档（原名智能主页）的管理。具体能力：(1) 以 Markdown 格式获取文档/表格/智能表格的完整内容 (2) 新建文档或智能表格 (3) 用 Markdown 覆写文档内容 (4) 创建智能文档，将本地 Markdown 文件发布为智能文档 (5) 导出智能文档内容为 Markdown 文件。用户提及 `https://doc.weixin.qq.com/xxxx` 格式的URL链接时，需要使用此技能。
+description: 企业微信文档（doc）管理技能。提供普通文档的新建、内容读取（Markdown）、内容覆写能力。适用场景：(1) 从零新建空白文档 (2) 以 Markdown 格式读取文档完整内容 (3) 用 Markdown 覆写文档正文。支持通过 docid 或文档 URL 定位文档。当用户提到「企业微信文档」「企微文档」「创建文档」「写个文档」，或链接形如 `https://doc.weixin.qq.com/doc/xxx` 时触发该技能。注意：在线表格（`/sheet/*`）请用 `wecom-sheet`；智能表格（`/smartsheet/*`）请用 `wecom-smartsheet`；智能文档/智能主页（`/smartpage/*`）请用 `wecom-smartpage`。
 ---
 
 # 企业微信文档管理
@@ -9,32 +9,22 @@ description: 企业微信文档管理技能。支持企业微信文档、表格
 
 > ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
 
-管理企业微信文档和智能文档（原名智能主页）的创建、读取和编辑。文档接口支持通过 `docid` 或 `url` 二选一定位文档。
-
-> ⚠️ **重要触发规则**：只有当用户明确提到「**智能文档**」或「**智能主页**」时，才使用智能文档相关接口（`smartpage_*` 系列）。其他所有涉及「文档」的场景（如"创建文档"、"写个文档"、"帮我建个文档"等），一律使用企微文档接口（`create_doc` / `get_doc_content` / `edit_doc_content`）。
+资源型技能，负责普通 doc 文档的新建、内容读取与覆写。文档接口支持通过 `docid` 或 `url` 二选一定位文档。
 
 ## URL 品类识别与接口路由
 
-企业微信文档有四种品类，**URL 格式不同，读取内容所用的接口也不同**，切勿混用。其中**表格（在线表格）与智能表格是两类不同品类**，请通过 URL 严格区分：
+企业微信文档有多种品类，**URL 格式不同，所用的接口/技能也不同**。请通过 URL 严格区分：
 
-| URL 模式 | 品类 | 读取内容接口 |
+| URL 模式 | 品类 | 处理方式 |
 |---|---|---|
-| `https://doc.weixin.qq.com/doc/*` | **文档**（doc_type=3） | `get_doc_content` |
-| `https://doc.weixin.qq.com/sheet/*` | **表格 / 在线表格** | `get_doc_content` |
-| `https://doc.weixin.qq.com/smartsheet/*` | **智能表格**（doc_type=10） | `smartsheet_get_sheet` → `smartsheet_get_records` |
-| `https://doc.weixin.qq.com/smartpage/*` | **智能文档**（原名智能主页） | `smartpage_export_task` → `smartpage_get_export_result` |
-
-**判断规则**：
-- URL 路径以 `/doc/*` 开头 → 文档 → 用 `get_doc_content`
-- URL 路径以 `/sheet/*` 开头 → 表格（在线表格） → 用 `get_doc_content`
-- URL 路径以 `/smartsheet/*` 开头 → 智能表格 → 用 `smartsheet_get_sheet`
-- URL 路径以 `/smartpage/*` 开头 → 智能文档（原名智能主页） → 用 `smartpage_export_task`
-
-> ⚠️ **表格 ≠ 智能表格**：二者是不同品类（`/sheet/` vs `/smartsheet/`）。
+| `https://doc.weixin.qq.com/doc/*` | **文档** | **本 skill** |
+| `https://doc.weixin.qq.com/sheet/*` | **在线表格** | 参阅 `wecom-sheet` skill |
+| `https://doc.weixin.qq.com/smartsheet/*` | **智能表格** | 参阅 `wecom-smartsheet` skill |
+| `https://doc.weixin.qq.com/smartpage/*` | **智能文档**（原名智能主页） | 参阅 `wecom-smartpage` skill |
 
 ## 调用方式
 
-通过 `wecom_mcp` tool 调用，子工具名为 `doc`：
+通过 `wecom_mcp` tool 调用，品类名为 `doc`：
 
 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc <tool_name> '<json_params>'` 调用指定技能
 
@@ -53,117 +43,85 @@ description: 企业微信文档管理技能。支持企业微信文档、表格
 
 | errcode | errmsg | 含义 | 处理方式 |
 |---------|--------|------|----------|
-| `851002` | `incompatible doc type` | 文档品类与所调用的接口不匹配 | 根据文档 URL 重新确认品类（参见上方「URL 品类识别与接口路由」表），然后使用该品类对应的正确接口重试 |
-| `851003` | `no authority` | 无文档权限。在编辑场景，通常是因为机器人不允许编辑由企业成员创建的文档。在**智能表格写入场景**下，若该报错发生在 `smartsheet_add_records` / `smartsheet_update_records`，可引导用户走 Webhook 兜底方案，详见 [webhook-fallback.md](../wecom-smartsheet/references/webhook-fallback.md)；其他接口则按权限问题排查。注意 Webhook 只能更新通过 Webhook 写入的记录，人工创建的记录无法更新 |
-
----
+| `851002` | `incompatible doc type` | 文档品类与所调用的接口不匹配 | 根据文档 URL 重新确认品类（参见上方「URL 品类识别与接口路由」表），然后跳转到该品类对应的 skill |
 
-## 文档
+## 接口详述
 
-适用品类：文档（doc_type=3）、表格（在线表格）和智能表格（doc_type=10）
-适用 URL：`/doc/*`、`/sheet/*`、`/smartsheet/*`
+### create_doc — 新建文档
 
-适用场景：
-1. 以 Markdown 格式导出获取文档 / 表格 / 智能表格完整内容（异步轮询）
-2. 新建文档（doc_type=3）或智能表格（doc_type=10）
-3. 用 Markdown 格式覆写文档内容
+新建一篇空白企微文档（`doc_type` 固定为 3）。创建成功后返回 `docid` 和 `url`。
 
-### get_doc_content
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "项目周报"}'`
 
-获取**文档 / 表格（在线表格） / 智能表格**的完整内容数据，统一以 Markdown 格式返回。采用**异步轮询机制**：首次调用无需传 `task_id`，接口返回 `task_id`；若 `task_done` 为 false，需携带该 `task_id` 再次调用，直到 `task_done` 为 true 时返回完整内容。
-
-> 适用 URL：`/doc/*`、`/sheet/*`、`/smartsheet/*`。`/smartpage/*`（智能文档）不适用，请改用 `smartpage_export_task`。
-
-- 首次调用（不传 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`
-- 轮询（携带上次返回的 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2, "task_id": "xxx"}'`
-- 通过 URL 读取文档：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"url": "https://doc.weixin.qq.com/doc/xxx", "type": 2}'`
-- 通过 URL 读取表格（在线表格）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"url": "https://doc.weixin.qq.com/sheet/xxx", "type": 2}'`
+**参数**
 
-参见 [API 详情](references/get-doc-content.md)。
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `doc_type` | int | 是 | — | 固定传 `3`（文档） |
+| `doc_name` | string | 是 | — | 文档标题，最多 255 个字符，超过会被截断 |
 
-### create_doc
-
-新建文档（doc_type=3）或智能表格（doc_type=10）。创建成功返回 url 和 docid。
-
-- 创建文档：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "项目周报"}'`
-- 创建智能表格：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 10, "doc_name": "任务跟踪表"}'`
-
-**注意**：
-- docid 仅在创建时返回，需妥善保存。创建智能表格时默认包含一个子表
-- 智能表格（doc_type=10）的详细管理功能（子表、字段、数据记录等）已迁移到 `wecom-smartsheet` skill，请使用该 skill 进行高级操作
-- 普通表格（在线表格，URL 含 `/sheet/`）本 skill **仅支持读取**（通过 `get_doc_content`），不支持创建
-
-参见 [API 详情](references/create-doc.md)。
-
-### edit_doc_content
-
-用 Markdown 内容覆写文档正文。`content_type` 固定为 `1`（Markdown）。
-
-使用 `wecom_mcp` tool 调用 `wecom_mcp call doc edit_doc_content '{"docid": "DOCID", "content": "# 标题\n\n正文内容", "content_type": 1}'`
+**返回**
 
-参见 [API 详情](references/edit-doc-content.md)。
-
----
-
-## 智能文档（原名智能主页）
-
-适用品类：智能文档（用户说「智能文档」或「智能主页」时触发）
-适用 URL：`/smartpage/*`
-
-> ⚠️ 只有当用户明确指定「智能文档」或「智能主页」时，才使用以下接口。其他「文档」场景请使用上方的企微文档接口。
-
-适用场景：
-1. 将本地 Markdown 文件创建为智能文档
-2. 异步导出智能文档内容为 Markdown
-
-### smartpage_create
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `docid` | string | 新建文档的 docid，需妥善保存 |
+| `url` | string | 新建文档的访问链接 |
 
-创建智能文档（原名智能主页），支持传入标题和多个子页面。每个子页面可指定标题、内容类型和本地文件路径。响应透传 mcp 回包，返回 docid 和 url。
+**注意事项**
 
-- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_create '{"title": "项目概览", "pages": [{"page_title": "需求文档", "content_type": 1, "page_filepath": "/path/to/requirements.md"}]}'`
+- 本接口仅创建**空白**文档，不携带初始内容；如需写入正文，请在创建后调用 `edit_doc_content`。
 
-**注意**：
-- `content_type` **必须与文件实际内容匹配**：`.md` 文件或包含 Markdown 语法的内容必须传 `1`（Markdown），仅纯文本才传 `0`。绝大多数场景应传 `1`
-- docid 仅在创建时返回，需妥善保存
-- 每个子页面的 Markdown 文件大小不得超过 **10MB**，超过会导致创建失败。如果文件过大，需先拆分为多个子页面再创建
+### get_doc_content — 读取完整内容
 
-参见 [API 详情](references/smartpage-create.md)。
+获取文档的完整内容数据，统一以 Markdown 格式返回。采用**异步轮询机制**：首次调用无需传 `task_id`，接口返回 `task_id`；若 `task_done` 为 `false`，需携带该 `task_id` 再次调用，直到 `task_done` 为 `true` 时返回完整内容。
 
-### smartpage_export_task
+- 首次调用（不传 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`
+- 轮询（携带上次返回的 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2, "task_id": "xxx"}'`
+- 通过 URL 读取：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"url": "https://doc.weixin.qq.com/doc/xxx", "type": 2}'`
 
-发起智能文档内容导出任务（异步）。传入 docid（或 url）和 content_type，返回 task_id。这是异步导出的第一步，需配合 `smartpage_get_export_result` 轮询获取导出结果。
+**参数**
 
-- 通过 docid：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'`
-- 或通过 URL：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"url": "https://doc.weixin.qq.com/smartpage/xxx", "content_type": 1}'`
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 与 `url` 二选一 | — | 文档的 docid |
+| `url` | string | 与 `docid` 二选一 | — | 文档的访问链接 |
+| `type` | int | 是 | — | 内容返回格式，固定传 `2`（Markdown） |
+| `task_id` | string | 否 | — | 任务 ID，首次不传，轮询时填上次返回的 `task_id` |
 
-参见 [API 详情](references/smartpage-export.md)。
+**返回**
 
-### smartpage_get_export_result
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `content` | string | `task_done` 为 `true` 时返回的完整 Markdown 内容 |
+| `task_id` | string | 任务 ID，未完成时用于下次轮询 |
+| `task_done` | bool | 任务是否完成，`false` 时需携带 `task_id` 继续轮询 |
 
-查询智能文档导出任务进度。传入 task_id 进行轮询，当 `task_done` 为 `true` 时返回 `content_filepath`（导出内容的本地文件路径）。
+**使用规则**
 
-- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_get_export_result '{"task_id": "TASK_ID"}'`
+- 首次调用不传 `task_id`；若 `task_done` 为 `false`，记录 `task_id` 后携带其再次调用，直到 `task_done` 为 `true` 取 `content`。
 
-当 `task_done` 为 `true` 时，使用 Read 工具读取 `content_filepath` 指向的文件即可获取导出的 Markdown 内容。
+### edit_doc_content — 覆写文档内容
 
-参见 [API 详情](references/smartpage-export.md)。
+用 Markdown 内容覆写文档正文。此操作为**覆写**，会替换文档全部内容。`content_type` 固定为 `1`（Markdown）。
 
----
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc edit_doc_content '{"docid": "DOCID", "content": "# 标题\n\n正文内容", "content_type": 1}'`
 
-## 典型工作流
+**参数**
 
-> **关键提示**：读取内容前先看 URL 判断品类。`/doc/`、`/sheet/` 或 `/smartsheet/` → `get_doc_content`；`/smartpage/` → `smartpage_export_task`。只有用户明确提到「智能文档」或「智能主页」时才走 smartpage 流程，其他文档场景一律使用企微文档接口。
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 与 `url` 二选一 | — | 文档的 docid |
+| `url` | string | 与 `docid` 二选一 | — | 文档的访问链接 |
+| `content` | string | 是 | — | 覆写的文档内容（Markdown） |
+| `content_type` | int | 是 | — | 内容类型，固定传 `1`（Markdown） |
 
-### 文档 / 表格 / 智能表格读取与文档编辑
+**使用规则**
 
-1. **读取文档 / 表格 / 智能表格**（URL 含 `/doc/`、`/sheet/` 或 `/smartsheet/`） → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`，或通过 URL（`/doc/*`、`/sheet/*`、`/smartsheet/*` 均适用）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"url": "https://doc.weixin.qq.com/sheet/xxx", "type": 2}'`，若 `task_done` 为 false 则携带 `task_id` 继续轮询
-2. **创建新文档** → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 3, "doc_name": "文档名"}'`，保存返回的 docid
-3. **编辑文档** → 先 get_doc_content 了解当前内容，再 edit_doc_content 覆写
+- 此操作为覆写，会替换文档全部内容；建议先用 `get_doc_content` 了解当前内容再编辑。
+- 成功判定：以返回的 `errcode == 0` 为准；非 0 时按「返回格式说明」处理（可重试 1 次）。
 
-### 智能文档操作
+## 跨技能依赖
 
-1. **创建智能文档**（仅当用户明确要求「智能文档」或「智能主页」时） → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_create '{"title": "标题", "pages": [{"page_title": "子页面", "content_type": 1, "page_filepath": "/path/to/file.md"}]}'`，保存返回的 docid
-2. **获取智能文档内容**（URL 含 `/smartpage/`，异步两步）：
-   - **第一步**：发起导出任务 → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_export_task '{"docid": "DOCID", "content_type": 1}'`，获取 `task_id`
-   - **第二步**：轮询导出结果 → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_get_export_result '{"task_id": "TASK_ID"}'`，若 `task_done` 为 `false` 则继续轮询，直到 `task_done` 为 `true`
-   - **第三步**：使用 Read 工具读取 `content_filepath` 指向的本地文件，获取 Markdown 内容
+| 依赖技能 | 典型协作场景 | 数据流向 |
+|---|---|---|
+| `wecom-msg` | 用户要求把文档链接发给某人/某群 | 本 skill 新建后返回 `url` → `wecom-msg` 发送链接 |

package/skills/wecom-sheet/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: wecom-sheet
+description: 企业微信在线表格（sheet）管理技能。提供在线表格的新建、内容读取、内容修改、追加行数据，以及子工作表的增删管理。适用场景：(1) 新建空白在线表格 (2) 读取表格完整内容（Markdown）(3) 读取基础信息与子表列表 (4) 读取子表数据 (5) 修改指定区域内容 (6) 末尾追加一行数据 (7) 添加/删除子工作表。当用户提到「企业微信表格」「企业微信在线表格」「企微 excel 表格」，或链接形如 `https://doc.weixin.qq.com/sheet/xxx` 时触发该技能。注意：智能表格（`/smartsheet/*`）请用 `wecom-smartsheet`；普通文档（`/doc/*`）请用 `wecom-doc`；智能文档/智能主页（`/smartpage/*`）请用 `wecom-smartpage`。
+---
+
+# 企业微信在线表格管理
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+资源型技能，负责**在线表格**（`/sheet/*`）的新建、内容读写以及子工作表管理。
+
+## 调用方式
+
+通过 `wecom_mcp` tool 调用，品类名为 `doc`：
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc <tool_name> '<json_params>'` 调用指定技能
+
+## 返回格式说明
+
+所有接口返回 JSON 对象，包含以下公共字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功，非 `0` 表示失败 |
+| `errmsg` | string | 错误信息，成功时为 `"ok"` |
+
+当 `errcode` 不为 `0` 时，说明接口调用失败，可重试 1 次；若仍失败，将 `errcode` 和 `errmsg` 展示给用户。
+
+### 特殊错误码
+
+| errcode | errmsg | 含义 | 处理方式 |
+|---------|--------|------|----------|
+| `851002` | `incompatible doc type` | 文档品类与所调用的接口不匹配 | 确认目标 URL 为 `/sheet/*`；若不是，请跳转到对应品类的 skill |
+
+## 接口路由表
+
+> **硬规则**：第二列是 `references/xxx.md` 链接的，命中这一行后**先 `read` 对应 references 文件，再构造命令**。写入/读取子表数据前，先用 `sheet_get_info` 拿到目标子表的 `sheet_id`。
+
+| 用户意图 | 参考位置 |
+|---|---|
+| 读取在线表格完整内容（Markdown 概览） | 见下方「读取完整内容」 |
+| 读取在线表格基础信息与子表列表 | 见下方「读取基础信息」 |
+| 从零新建在线表格（空白） | 见下方「新建在线表格」 |
+| 修改在线表格指定区域内容 | [references/sheet-update-range-data.md](references/sheet-update-range-data.md) |
+| 在线表格末尾追加一行数据 | [references/sheet-append-data.md](references/sheet-append-data.md) |
+| 添加在线表格子工作表 | [references/sheet-add-sub.md](references/sheet-add-sub.md) |
+| 删除在线表格子工作表 | [references/sheet-delete-sub.md](references/sheet-delete-sub.md) |
+
+## 接口详述
+
+### create_doc — 新建在线表格
+
+从零新建一篇企微**在线表格**：空白。创建成功后返回 `docid` 和 `url`。
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc create_doc '{"doc_type": 4, "doc_name": "项目数据表"}'`
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|---|---|---|---|---|
+| `doc_type` | int | 是 | — | 固定传 `4`（在线表格） |
+| `doc_name` | string | 是 | — | 表格标题 |
+
+**注意事项**
+
+- 本接口仅创建**空白**在线表格，不支持携带初始内容；如需写入数据，请在创建后先用 `sheet_get_info` 拿到子表 `sheet_id`，再通过 `sheet_update_range_data` / `sheet_append_data` 写入。
+
+### get_doc_content — 读取完整内容
+
+获取**在线表格**的完整内容数据，统一以 Markdown 格式返回。采用**异步轮询机制**：首次调用无需传 `task_id`，接口返回 `task_id`；若 `task_done` 为 `false`，需携带该 `task_id` 再次调用，直到 `task_done` 为 `true` 时返回完整内容。适合快速概览或读取整篇表格内容。
+
+- 首次调用（不传 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2}'`
+- 轮询（携带上次返回的 task_id）：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "type": 2, "task_id": "xxx"}'`
+- 通过 URL：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"url": "https://doc.weixin.qq.com/sheet/xxx", "type": 2}'`
+
+**参数**
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 与 `url` 二选一 | — | 在线表格的 docid |
+| `url` | string | 与 `docid` 二选一 | — | 在线表格的访问链接 |
+| `type` | int | 是 | — | 内容返回格式，固定传 `2`（Markdown） |
+| `task_id` | string | 否 | — | 任务 ID，首次不传，轮询时填上次返回的 `task_id` |
+
+**返回**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `content` | string | `task_done` 为 `true` 时返回的完整 Markdown 内容 |
+| `task_id` | string | 任务 ID，未完成时用于下次轮询 |
+| `task_done` | bool | 任务是否完成，`false` 时需携带 `task_id` 继续轮询 |
+
+**使用规则**
+
+- 首次调用不传 `task_id`；若 `task_done` 为 `false`，记录 `task_id` 后携带其再次调用，直到 `task_done` 为 `true` 取 `content`。
+
+### sheet_get_info — 读取基础信息
+
+读取**在线表格**的基础信息，包括工作表列表、文档名称与访问链接。所有后续需要 `sheet_id` 的接口（`sheet_update_range_data` / `sheet_append_data` / `sheet_delete_sub` 等）的 `sheet_id` 都从本接口返回的 `sheets[]` 中取。
+
+- 通过 docid：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc sheet_get_info '{"docid": "DOCID"}'`
+- 通过 URL：使用 `wecom_mcp` tool 调用 `wecom_mcp call doc sheet_get_info '{"url": "https://doc.weixin.qq.com/sheet/xxx"}'`
+
+**参数**
+
+| 字段 | 类型 | 必填 | 默认值 | 语义 |
+|---|---|---|---|---|
+| `docid` | string | 与 `url` 二选一 | — | 在线表格的 docid |
+| `url` | string | 与 `docid` 二选一 | — | 在线表格的访问链接 |
+
+**返回**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sheets` | array | 工作表列表；每项含 `sheet_id` / `title` / `row_count` / `column_count` / `data_range` 等基础信息 |
+| `url` | string | 文档访问链接 |
+| `name` | string | 文档名称 |
+
+**使用规则**
+
+- `docid` 与 `url` 二选一，至少传其一。
+- **读 → 写 链路**：当需要往具体子表写内容（`sheet_update_range_data` / `sheet_append_data`）时，应先用 `get_doc_content` 读取并识别出各子表的**标题**与**具体数据**，再调用本接口拿到 `sheets[]` 中每个子表的 `sheet_id` 与行列数（`row_count` / `column_count`）；通过**子表标题与 `title` 匹配**确定目标 `sheet_id`，并结合行列数核对写入区域范围，从而打通「读 → 写」的完整链路。
+
+## 跨技能依赖
+
+| 依赖技能 | 典型协作场景 | 数据流向 |
+|---|---|---|
+| `wecom-contact` | 表格里需要写入人员信息时按姓名查 userid | `get_userlist` 查到 userid → 本 skill 写入 |
+| `wecom-msg` | 用户要求把在线表格链接发给某人/某群 | 本 skill 新建后返回 `url` → `wecom-msg` 发送链接 |

package/skills/wecom-sheet/references/sheet-add-sub.md

@@ -0,0 +1,54 @@
+# sheet_add_sub API
+
+向**在线表格**添加一个新的子工作表，返回新增子表信息（含 `sheet_id`）。
+
+## 调用
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc sheet_add_sub '<JSON 参数>'`
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| docid | string | 是 | 在线表格 ID |
+| sheet | object | 是 | 子表信息 |
+| sheet.title | string | 是 | 工作表名称 |
+| sheet.row_count | int | 否 | 表格总行数 |
+| sheet.column_count | int | 否 | 表格总列数 |
+| index | int | 否 | 插入位置：`0` 表示插入到最后，`1` 表示插入到第一个位置 |
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `sheet` | object | 新增的子表信息；含 `sheet_id`（唯一标识）/ `title` / `row_count` / `column_count` / `data_range`（新建时为空） |
+
+## 请求示例
+
+```json
+{
+    "docid": "DOCID",
+    "sheet": {
+        "title": "新子表",
+        "row_count": 100,
+        "column_count": 26
+    },
+    "index": 0
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "sheet": {
+        "sheet_id": "SHEET_ID",
+        "title": "新子表",
+        "row_count": 100,
+        "column_count": 26,
+        "data_range": ""
+    }
+}
+```

package/skills/wecom-sheet/references/sheet-append-data.md

@@ -0,0 +1,64 @@
+# sheet_append_data API
+
+向**在线表格**的指定子工作表末尾自动追加一行数据，无需指定行号——数据将写到最末一行之后。适合逐行写入。
+
+## 调用
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc sheet_append_data '<JSON 参数>'`
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| docid | string | 是 | 在线表格 ID |
+| sheet_id | string | 是 | 工作表 ID，通过 `sheet_get_info` 获取 |
+| row | object | 是 | 追加的一行数据 |
+| row.values | array | 是 | 单元格数组，按列顺序排列 |
+
+`row.values[]` 对象结构：
+
+| 子字段 | 类型 | 说明 |
+|---|---|---|
+| `cell_value` | object | 单元格值，形如 `{"text": "<文本>"}` / `{"link": {"url": "<URL>", "text": "<显示文本>"}}` / `{"formula": "=SUM(A1,A2)"}` |
+| `cell_format` | object | 单元格样式；传空对象 `{}` 表示默认样式 |
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `row` | object | 写入的行数据，结构与入参 `row` 一致 |
+
+## 请求示例
+
+```json
+{
+    "docid": "DOCID",
+    "sheet_id": "SHEET_ID",
+    "row": {
+        "values": [
+            { "cell_value": { "text": "新任务" }, "cell_format": {} },
+            { "cell_value": { "text": "李四" }, "cell_format": {} }
+        ]
+    }
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "row": {
+        "values": [
+            { "cell_value": { "text": "新任务" } },
+            { "cell_value": { "text": "李四" } }
+        ]
+    }
+}
+```
+
+## 使用规则
+
+- **逐行写入场景**：本接口会自动定位到子表最末一行之后追加；批量写不同区域请用 `sheet_update_range_data`。
+- **读 → 写 链路**：写入前先用 `get_doc_content` 识别出目标子表的**标题**与**具体数据**，再用 `sheet_get_info` 拿到 `sheets[]`，按**子表标题匹配 `title`** 确定 `sheet_id`，并参考其 `column_count` 核对每行单元格数量与列对齐。

package/skills/wecom-sheet/references/sheet-delete-sub.md

@@ -0,0 +1,38 @@
+# sheet_delete_sub API
+
+根据 `docid` 与 `sheet_id` 删除**在线表格**的指定子工作表，**操作不可逆**。
+
+## 调用
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc sheet_delete_sub '<JSON 参数>'`
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| docid | string | 是 | 在线表格 ID |
+| sheet_id | string | 是 | 要删除的工作表 ID，通过 `sheet_get_info` 获取 |
+
+## 请求示例
+
+```json
+{
+    "docid": "DOCID",
+    "sheet_id": "SHEET_ID"
+}
+```
+
+## 响应示例
+
+删除成功返回空对象（仅含公共字段）：
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+## 注意事项
+
+- **操作不可逆**，删除前请通过 `sheet_get_info` 确认目标 `sheet_id`。

package/skills/wecom-sheet/references/sheet-update-range-data.md

@@ -0,0 +1,95 @@
+# sheet_update_range_data API
+
+修改**在线表格**指定区域的内容与格式，通过 `grid_data` 指定写入的起始位置与各单元格数据。适合批量写入某个区域。
+
+## 调用
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call doc sheet_update_range_data '<JSON 参数>'`
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| docid | string | 是 | 在线表格 ID |
+| sheet_id | string | 是 | 工作表 ID，通过 `sheet_get_info` 获取 |
+| grid_data | object | 是 | 写入区域的数据 |
+| grid_data.start_row | int | 是 | 起始行号，从 0 起 |
+| grid_data.start_column | int | 是 | 起始列号，从 0 起 |
+| grid_data.rows | array | 是 | 各行数据 |
+
+`grid_data.rows[].values[]` 对象结构：
+
+| 子字段 | 类型 | 说明 |
+|---|---|---|
+| `cell_value` | object | 单元格值，根据内容类型选择对应字段（见下表）|
+| `cell_format` | object | 单元格样式；传空对象 `{}` 表示默认样式 |
+
+`cell_value` 的字段必须按内容类型选择：
+
+| 内容类型 | 必须使用的字段 | 示例 |
+|---|---|---|
+| 普通文本/数字 | `text` | `{"text": "张三"}`、`{"text": "100"}` |
+| 超链接 | `link` | `{"link": {"url": "https://...", "text": "显示文本"}}` |
+| 公式（以 `=` 开头） | `formula` | `{"formula": "=SUM(A1:A2)"}` |
+
+> 公式必须用 `formula` 字段，禁止写成 `{"text": "=SUM(A1:A2)"}`
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `grid_data` | object | 写入的数据，结构与入参 `grid_data` 一致 |
+
+## 请求示例
+
+```json
+{
+    "docid": "DOCID",
+    "sheet_id": "SHEET_ID",
+    "grid_data": {
+        "start_row": 0,
+        "start_column": 0,
+        "rows": [
+            {
+                "values": [
+                    { "cell_value": { "text": "完成需求文档" }, "cell_format": {} },
+                    { "cell_value": { "text": "张三" }, "cell_format": {} }
+                ]
+            },
+            {
+                "values": [
+                    { "cell_value": { "text": "合计" }, "cell_format": {} },
+                    { "cell_value": { "formula": "=SUM(B1:B1)" }, "cell_format": {} }
+                ]
+            }
+        ]
+    }
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "grid_data": {
+        "start_row": 0,
+        "start_column": 0,
+        "rows": [
+            {
+                "values": [
+                    { "cell_value": { "text": "完成需求文档" } },
+                    { "cell_value": { "text": "张三" } }
+                ]
+            }
+        ]
+    }
+}
+```
+
+## 使用规则
+
+- 批量写不同区域用本接口；逐行追加到子表末尾请用 `sheet_append_data`。
+- **公式一律用 `formula` 字段**：任何以 `=` 开头的内容（如 `=SUM(...)`、`=A1+B1`、`=IF(...)`）都必须写成 `{"formula": "=..."}`，不可写成 `{"text": "=..."}`，否则只会被当作文本显示而不计算。
+- **读 → 写 链路**：写入前先用 `get_doc_content` 识别出目标子表的**标题**与**具体数据**，再用 `sheet_get_info` 拿到 `sheets[]`，按**子表标题匹配 `title`** 确定 `sheet_id`，并参考其 `row_count` / `column_count` 核对 `grid_data` 的写入区域是否越界。