ylib-wecom-openclaw-plugin 2026.4.29

package/skills/wecom-contact/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: wecom-contact
+description: 通讯录成员查询技能，基于 MCP tool 协议封装的 `get_userlist` 接口，获取当前用户可见范围内的通讯录成员，支持按姓名/别名本地筛选匹配。返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员，非全量成员。
+---
+
+# 通讯录成员查询技能
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+通过 MCP tool 协议封装的 `get_userlist` 接口，获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。
+
+## 操作
+
+### 1. 获取全量通讯录成员
+
+获取当前用户可见范围内的所有企业成员信息：
+
+**调用示例：**
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'`
+
+**返回格式：**
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "userlist": [
+        {
+            "userid": "zhangsan",
+            "name": "张三",
+            "alias": "Sam"
+        },
+        {
+            "userid": "lisi",
+            "name": "李四",
+            "alias": ""
+        }
+    ]
+}
+```
+
+**返回字段说明：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `userlist` | array | 用户列表 |
+| `userlist[].userid` | string | 用户唯一 ID |
+| `userlist[].name` | string | 用户姓名 |
+| `userlist[].alias` | string | 用户别名，可能为空 |
+
+---
+
+### 2. 按姓名/别名搜索人员
+
+`get_userlist` 返回全量成员后，在本地对结果进行筛选匹配：
+
+- **精确匹配**：`name` 或 `alias` 与关键词完全一致，直接使用
+- **模糊匹配**：`name` 或 `alias` 包含关键词，返回所有匹配结果
+- **无结果**：告知用户未找到对应人员
+
+**搜索示例：**
+
+用户问："帮我找一下张三是谁？"
+
+1. 调用 `get_userlist` 获取全量成员
+2. 在 `userlist` 中筛选 `name` 或 `alias` 包含"张三"的成员
+3. 返回匹配结果
+
+---
+
+## 注意事项
+
+- `get_userlist` 返回的是当前用户**可见范围内**的成员，需经过可见性规则过滤，不一定是全公司所有人员；返回字段仅包含 `userid`、`name`（姓名）和 `alias`（别名）
+- ⚠️ **超过 10 人时接口将报错**：若 `userlist` 返回成员数量超过 10 人，视为异常，应立即停止处理并向用户说明：
+
+  > 当前通讯录可见成员数量超过了本技能支持的上限（10 人）。
+  > 本技能仅适用于可见范围较小的场景，无法在大范围通讯录中使用。
+  > 建议缩小可见范围后重试，或通过其他方式查询目标人员。
+
+- `userid` 是用户的唯一标识，在需要传递用户 ID 给其他接口时使用此字段
+- `alias` 字段可能为空字符串，搜索时需做空值判断
+- 若搜索结果有多个同名人员，需将所有候选人展示给用户选择，不得自行决定
+- 若 `errcode` 不为 `0`，说明接口调用失败，需告知用户错误信息（`errmsg`）
+
+---
+
+## 典型工作流
+
+### 工作流 1：查询人员信息
+
+用户问："帮我查一下 Sam 是谁？"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员列表
+
+2. 在结果中筛选 `alias` 为 `Sam` 或 `name` 包含 `Sam` 的成员
+3. 若找到唯一匹配，直接展示结果：
+
+```
+📇 找到成员：
+- 姓名：张三
+- 别名：Sam
+- 用户ID：zhangsan
+```
+
+4. 若找到多个匹配，展示候选列表请用户确认：
+
+```
+🔍 找到多个匹配成员，请确认您要查询的是哪位：
+
+1. 张三（别名：Sam，ID：zhangsan）
+2. 张三丰（别名：Sam2，ID：zhangsan2）
+
+请问您要查询的是哪一位？
+```
+
+---
+
+### 工作流 2：为其他功能提供 userid 转换
+
+用户问："帮我发消息给张三"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员
+
+2. 筛选 `name` 为"张三"的成员，确认 `userid`
+3. 将 `userid` 传递给消息发送接口
+
+---
+
+### 工作流 3：批量查询多个人员
+
+用户问："帮我查一下张三和李四分别是谁？"
+
+1. 使用 `wecom_mcp` tool 调用 `wecom_mcp call contact get_userlist '{}'` 获取全量成员列表
+
+2. 分别筛选"张三"和"李四"的匹配结果
+3. 汇总后一并展示
+
+> 注意：只需调用一次 `get_userlist`，在本地对结果进行多次筛选，避免重复调用接口。
+
+---
+
+## 快速参考
+
+### 接口说明
+
+| 接口 | 用途 | 输入 | 返回 |
+|------|------|------|------|
+| `get_userlist` | 获取可见范围内全量通讯录成员 | 无 | 用户列表（userid、name、alias） |
+
+### 本地筛选策略
+
+| 场景 | 策略 |
+|------|------|
+| 精确匹配（name 或 alias 完全一致） | 直接使用，无需用户确认 |
+| 模糊匹配（name 或 alias 包含关键词），唯一结果 | 直接使用，向用户展示结果 |
+| 模糊匹配，多个结果 | 展示候选列表，请用户选择 |
+| 无匹配结果 | 告知用户未找到对应人员 |

package/skills/wecom-doc/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: wecom-doc
+description: 企业微信文档管理技能。支持企业微信文档、智能表格和智能文档（原名智能主页）的管理。具体能力：(1) 获取文档或智能表格的完整内容，以 Markdown 格式导出 (2) 新建文档或智能表格 (3) 用 Markdown 覆写文档内容 (4) 创建智能文档，将本地 Markdown 文件发布为智能文档 (5) 导出智能文档内容为 Markdown 文件。
+---
+
+# 企业微信文档管理
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+管理企业微信文档和智能文档（原名智能主页）的创建、读取和编辑。文档接口支持通过 `docid` 或 `url` 二选一定位文档。
+
+> ⚠️ **重要触发规则**：只有当用户明确提到「**智能文档**」或「**智能主页**」时，才使用智能文档相关接口（`smartpage_*` 系列）。其他所有涉及「文档」的场景（如"创建文档"、"写个文档"、"帮我建个文档"等），一律使用企微文档接口（`create_doc` / `get_doc_content` / `edit_doc_content`）。
+
+## URL 品类识别与接口路由
+
+企业微信文档有三种品类，**URL 格式不同，读取内容所用的接口也不同**，切勿混用：
+
+| URL 模式 | 品类 | 读取内容接口 |
+|---|---|---|
+| `https://doc.weixin.qq.com/doc/*` | **文档**（doc_type=3） | `get_doc_content` |
+| `https://doc.weixin.qq.com/smartsheet/*` | **智能表格**（doc_type=10） | `get_doc_content` |
+| `https://doc.weixin.qq.com/smartpage/*` | **智能文档**（原名智能主页） | `smartpage_export_task` → `smartpage_get_export_result` |
+
+**判断规则**：
+- URL 路径以 `/doc/*` 开头 → 文档 → 用 `get_doc_content`
+- URL 路径以 `/smartsheet/*` 开头 → 智能表格 → 用 `get_doc_content`
+- URL 路径以 `/smartpage/*` 开头 → 智能文档（原名智能主页） → 用 `smartpage_export_task`
+
+
+## 调用方式
+
+通过 `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 重新确认品类（参见上方「URL 品类识别与接口路由」表），然后使用该品类对应的正确接口重试 |
+| `851003` | `no authority` | 无权限调用该接口，**智能表格写入场景**下通常是企业可见范围 > 10 人的规模限制 | 若发生在需要写入数据的场景，引导用户走 Webhook 兜底方案，详见 [webhook-fallback.md](../wecom-smartsheet/references/webhook-fallback.md)；其他接口则按权限问题排查 |
+
+---
+
+## 文档
+
+适用品类：文档（doc_type=3）和智能表格（doc_type=10）
+适用 URL：`/doc/*`、`/smartsheet/*`
+
+适用场景：
+1. 以 Markdown 格式导出获取文档完整内容（异步轮询）
+2. 新建文档（doc_type=3）或智能表格（doc_type=10）
+3. 用 Markdown 格式覆写文档内容
+
+### 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/doc/xxx", "type": 2}'`
+
+参见 [API 详情](references/get-doc-content.md)。
+
+### 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 进行高级操作
+
+参见 [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
+
+创建智能文档（原名智能主页），支持传入标题和多个子页面。每个子页面可指定标题、内容类型和本地文件路径。响应透传 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"}]}'`
+
+**注意**：
+- `content_type` **必须与文件实际内容匹配**：`.md` 文件或包含 Markdown 语法的内容必须传 `1`（Markdown），仅纯文本才传 `0`。绝大多数场景应传 `1`
+- docid 仅在创建时返回，需妥善保存
+- 每个子页面的 Markdown 文件大小不得超过 **10MB**，超过会导致创建失败。如果文件过大，需先拆分为多个子页面再创建
+
+参见 [API 详情](references/smartpage-create.md)。
+
+### smartpage_export_task
+
+发起智能文档内容导出任务（异步）。传入 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}'`
+
+参见 [API 详情](references/smartpage-export.md)。
+
+### smartpage_get_export_result
+
+查询智能文档导出任务进度。传入 task_id 进行轮询，当 `task_done` 为 `true` 时返回 `content_filepath`（导出内容的本地文件路径）。
+
+- 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc smartpage_get_export_result '{"task_id": "TASK_ID"}'`
+
+当 `task_done` 为 `true` 时，使用 Read 工具读取 `content_filepath` 指向的文件即可获取导出的 Markdown 内容。
+
+参见 [API 详情](references/smartpage-export.md)。
+
+---
+
+## 典型工作流
+
+> **关键提示**：读取内容前先看 URL 判断品类。`/doc/` 或 `/smartsheet/` → `get_doc_content`；`/smartpage/` → `smartpage_export_task`。只有用户明确提到「智能文档」或「智能主页」时才走 smartpage 流程，其他文档场景一律使用企微文档接口。
+
+### 文档操作
+
+1. **读取文档/智能表格内容**（URL 含 `/doc/` 或 `/smartsheet/`） → 使用 `wecom_mcp` tool 调用 `wecom_mcp call doc get_doc_content '{"docid": "DOCID", "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 覆写
+
+### 智能文档操作
+
+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 内容

package/skills/wecom-doc/references/create-doc.md

@@ -0,0 +1,56 @@
+# create_doc API
+
+新建文档、表格或智能表格。创建成功后返回文档访问链接和 docid。
+
+## 技能定义
+
+```json
+{
+    "name": "create_doc",
+    "description": "新建文档、表格或智能表格。支持在指定空间和目录下创建，可设置文档管理员。创建成功后返回文档访问链接和 docid（docid 仅在创建时返回，需妥善保存）。注意：创建智能表格（doc_type=10）时，文档会默认包含一个子表，可通过 smartsheet_get_sheet 查询其 sheet_id，无需额外调用 smartsheet_add_sheet。",
+    "inputSchema": {
+        "properties": {
+            "doc_type": {
+                "description": "文档类型：3-文档，10-智能表格",
+                "enum": [3, 10],
+                "title": "Doc Type",
+                "type": "integer"
+            },
+            "doc_name": {
+                "description": "文档名字，最多 255 个字符，超过会被截断",
+                "title": "Doc Name",
+                "type": "string"
+            }
+        },
+        "required": ["doc_type", "doc_name"],
+        "title": "create_docArguments",
+        "type": "object"
+    }
+}
+```
+
+## 请求示例
+
+```json
+{
+    "doc_type": 3,
+    "doc_name": "项目周报"
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "url": "https://doc.weixin.qq.com/doc/xxx",
+    "docid": "DOCID"
+}
+```
+
+## 注意事项
+
+- `doc_type=3` 创建文档
+- `doc_type=10` 创建智能表格，默认包含一个子表
+- docid 仅在创建时返回，后续无法再获取，务必保存

package/skills/wecom-doc/references/edit-doc-content.md

@@ -0,0 +1,68 @@
+# edit_doc_content API
+
+编辑（覆写）文档内容。
+
+## 技能定义
+
+```json
+{
+    "name": "edit_doc_content",
+    "description": "编辑文档内容",
+    "inputSchema": {
+        "properties": {
+            "docid": {
+                "description": "文档 id，与 url 二选一传入",
+                "title": "Docid",
+                "type": "string"
+            },
+            "url": {
+                "description": "文档的访问链接，与 docid 二选一传入",
+                "title": "URL",
+                "type": "string"
+            },
+            "content": {
+                "description": "覆写的文档内容",
+                "title": "Content",
+                "type": "string"
+            },
+            "content_type": {
+                "description": "内容类型格式。1:markdown",
+                "enum": [1],
+                "title": "Content Type",
+                "type": "integer"
+            }
+        },
+        "oneOf": [
+            { "required": ["docid", "content", "content_type"] },
+            { "required": ["url", "content", "content_type"] }
+        ],
+        "title": "edit_doc_contentArguments",
+        "type": "object"
+    }
+}
+```
+
+## 请求示例
+
+```json
+{
+    "docid": "DOCID",
+    "content": "# 标题\n\n正文内容",
+    "content_type": 1
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok"
+}
+```
+
+## 注意事项
+
+- `content_type` 当前仅支持 `1`（Markdown 格式）
+- 此操作为**覆写**，会替换文档全部内容
+- 建议先调用 `get_doc_content` 了解当前内容再编辑

package/skills/wecom-doc/references/get-doc-content.md

@@ -0,0 +1,88 @@
+# get_doc_content API
+
+获取企业微信文档的完整内容数据，以 Markdown 格式返回。该接口采用异步轮询机制：首次调用无需传 task_id，接口会返回 task_id；若 task_done 为 false，需携带该 task_id 再次调用，直到 task_done 为 true 时返回完整内容。
+
+## 技能定义
+
+```json
+{
+    "name": "get_doc_content",
+    "description": "获取企业微信文档的完整内容数据，以 Markdown 格式返回。该接口采用异步轮询机制：首次调用无需传 task_id，接口会返回 task_id；若 task_done 为 false，需携带该 task_id 再次调用，直到 task_done 为 true 时返回完整内容。",
+    "inputSchema": {
+        "properties": {
+            "docid": {
+                "description": "文档的 docid，与 url 二选一传入",
+                "title": "Doc ID",
+                "type": "string"
+            },
+            "url": {
+                "description": "文档的访问链接，与 docid 二选一传入",
+                "title": "URL",
+                "type": "string"
+            },
+            "type": {
+                "description": "内容返回格式。2: Markdown 格式",
+                "enum": [2],
+                "title": "Type",
+                "type": "integer"
+            },
+            "task_id": {
+                "description": "任务 ID，用于异步轮询。初次调用时不填，后续轮询时填写上次返回的 task_id",
+                "title": "Task ID",
+                "type": "string"
+            }
+        },
+        "oneOf": [
+            { "required": ["docid", "type"] },
+            { "required": ["url", "type"] }
+        ],
+        "title": "get_doc_contentArguments",
+        "type": "object"
+    }
+}
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| docid | string | 与 url 二选一 | 文档的 docid |
+| url | string | 与 docid 二选一 | 文档的访问链接 |
+| type | integer | 是 | 内容返回格式，固定传 `2`（Markdown 格式） |
+| task_id | string | 否 | 任务 ID，初次调用不填，后续轮询时填写上次返回的 task_id |
+
+## 异步轮询机制
+
+1. **首次调用**：传入 `docid`/`url` 和 `type: 2`，不传 `task_id`
+2. **检查响应**：若 `task_done` 为 `false`，记录返回的 `task_id`
+3. **轮询调用**：携带 `task_id` 再次调用，直到 `task_done` 为 `true`
+4. **获取内容**：当 `task_done` 为 `true` 时，`content` 字段包含完整的 Markdown 内容
+
+## 请求示例
+
+```json
+// 首次调用
+{
+    "docid": "DOCID",
+    "type": 2
+}
+
+// 轮询调用
+{
+    "docid": "DOCID",
+    "type": 2,
+    "task_id": "xxx"
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "content": "# 文档标题\n\n文档正文内容...",
+    "task_id": "xxxxx",
+    "task_done": true
+}
+```

package/skills/wecom-doc/references/smartpage-create.md

@@ -0,0 +1,125 @@
+# smartpage_create API
+
+创建智能文档（原智能主页）。支持传入多个子页面，每个子页面可指定标题、内容类型和本地文件路径。创建成功后返回文档访问链接和 docid。
+
+## 技能定义
+
+```json
+{
+    "name": "smartpage_create",
+    "description": "创建智能文档（原智能主页）。支持传入标题和多个子页面配置，每个子页面可指定标题、内容类型（Text/Markdown）和本地文件路径。创建成功后返回 docid 和 url（docid 仅在创建时返回，需妥善保存）。",
+    "inputSchema": {
+        "properties": {
+            "title": {
+                "description": "智能文档标题",
+                "title": "Title",
+                "type": "string"
+            },
+            "pages": {
+                "description": "子页面列表",
+                "title": "Pages",
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "page_title": {
+                            "description": "子页面标题",
+                            "title": "Page Title",
+                            "type": "string"
+                        },
+                        "content_type": {
+                            "description": "内容类型。1: Markdown（包含Markdown语法的内容），0: Text（纯文本，不含任何Markdown语法）",
+                            "enum": [0, 1],
+                            "default": 1,
+                            "title": "Content Type",
+                            "type": "integer"
+                        },
+                        "page_filepath": {
+                            "description": "子页面内容对应的本地文件路径",
+                            "title": "Page Filepath",
+                            "type": "string"
+                        }
+                    }
+                }
+            }
+        },
+        "required": ["pages"],
+        "title": "smartpage_createArguments",
+        "type": "object"
+    }
+}
+```
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| title | string | 否 | 智能文档标题 |
+| pages | array | 是 | 子页面列表 |
+| pages[].page_title | string | 否 | 子页面标题 |
+| pages[].content_type | integer | 否 | 内容类型：1-Markdown，0-Text（纯文本）。**默认应传 1**，仅纯文本内容才传 0 |
+| pages[].page_filepath | string | 否 | 子页面内容对应的本地文件路径，需确保文件存在且可读 |
+
+## ContentType 枚举
+
+| 值 | 含义 | 适用场景 |
+|---|---|---|
+| 1 | Markdown | 文件内容包含 Markdown 语法（标题、列表、链接、代码块等） |
+| 0 | Text（纯文本） | 文件内容为纯文本，不含任何 Markdown 语法 |
+
+除了标准的 markdown 格式以外，智能文档还支持扩展语法以提升表示的丰富性，包括：
+1. 背景块
+```markdown
+<card color="green">
+## 在扩展标签里面可以任意嵌套 markdown 语法
+- 背景块常用于展示重要信息
+- 颜色的使用根据需要表达的语义进行选择，卡片背景由 `color` 指定；支持 `green`, `blue`, `red`, `yellow`, `gray`, `purple`, `orange`, `cyan`, `indigo`，也支持 `dark_green`, `dark_blue`, `dark_red`, `dark_yellow`, `dark_gray`, `dark_purple`, `dark_orange`, `dark_cyan`, `dark_indigo` 等深色系。
+</card>
+```
+背景颜色推荐使用浅色背景，以完成区隔/高亮并且保持低饱和度确保正文内容的良好显示。
+2. 分栏
+使用分栏可以并列显示内容，常用于展示对比或者并列信息
+```markdown
+<grid>
+<area width-ratio="0.5">占据50%的空间</area>
+<area width-ratio="0.5">占据50%的空间</area>
+</grid>
+```
+width-ratio：子容器宽度占比，范围 0.1~1.0，所有的子容器宽度占比之和为 1
+
+## 请求示例
+
+```json
+{
+    "title": "项目概览",
+    "pages": [
+        {
+            "page_title": "需求文档",
+            "content_type": 1,
+            "page_filepath": "/path/to/requirements.md"
+        },
+        {
+            "page_title": "设计说明",
+            "content_type": 1,
+            "page_filepath": "/path/to/design.md"
+        }
+    ]
+}
+```
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "docid": "DOCID",
+    "url": "https://doc.weixin.qq.com/smartpage/a1_xxxxxx"
+}
+```
+## 注意事项
+
+- `docid` 仅在创建时返回，后续无法再获取，务必保存
+- `page_filepath` 指向本地文件，需确保文件存在且可读
+- **`content_type` 必须与文件实际内容格式匹配**：`.md` 文件或包含 Markdown 语法的内容必须传 `1`，不要传 `0`
+- 每个子页面的 Markdown 文件大小不得超过 **10MB**，超过会导致创建失败；如果文件过大，需先拆分为多个子页面