sutong
750f981c7e
资源中心——从多渠道获取资源链接，转存到夸克网盘并整理归档。 - sources/tencent-doc: 腾讯文档读取 - sources/search: 网盘搜索 - storage/quark: 夸克网盘操作 - ref/: 来源 skill 参考归档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
236 lines
8.0 KiB
Markdown
236 lines
8.0 KiB
Markdown
# 公共接口与常见工作流
|
||
|
||
本文件包含两部分内容：
|
||
1. **公共接口**：不归属于任何特定品类的通用工具 API
|
||
2. **常见工作流**：跨品类的典型操作流程
|
||
|
||
---
|
||
|
||
## 公共接口
|
||
|
||
### get_content
|
||
|
||
**功能说明**：获取文档完整内容。支持所有文档类型，是读取文档内容的通用接口。
|
||
|
||
**调用示例**
|
||
```json
|
||
{
|
||
"file_id": "doc_1234567890"
|
||
}
|
||
```
|
||
|
||
**参数说明**
|
||
- `file_id` (string, 必填): 文档唯一标识符
|
||
|
||
**返回值说明**
|
||
```json
|
||
{
|
||
"content": "# 项目文档\n\n这是文档的完整内容...",
|
||
"error": "",
|
||
"trace_id": "trace_1234567890"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### upload_image
|
||
|
||
**功能说明**：上传图片，将图片的 base64 编码上传至腾讯文档，返回有效期为一天的 imageID，可用于智能表格、智能文档等场景的图片字段。
|
||
|
||
> ⚠️ **重要**：`image_base64` 参数必须传入图片文件的实际 base64 编码数据，不要传入文件路径（如 `/path/to/image.png`）或 URL 地址。
|
||
|
||
**调用示例**
|
||
```json
|
||
{
|
||
"image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
|
||
"file_name": "photo.png"
|
||
}
|
||
```
|
||
|
||
**参数说明**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `image_base64` | string | ✅ | 图片的 base64 编码内容，支持 PNG、JPG、GIF、BMP、WEBP 等常见格式，图片大小不超过 10MB。注意：必须传入实际 base64 编码数据（如 `iVBORw0KGgo...`），不要传入文件路径或 URL 地址 |
|
||
| `file_name` | string | ✅ | 图片文件名，用于识别图片类型，例如：`image.png`、`photo.jpg`，支持 `.png/.jpg/.jpeg/.gif/.bmp/.webp/.svg` 后缀 |
|
||
|
||
**返回值说明**
|
||
```json
|
||
{
|
||
"image_id": "img_1234567890",
|
||
"error": "",
|
||
"trace_id": "trace_1234567890"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `image_id` | string | 上传成功后返回的图片 ID，有效期为一天，可用于智能表格、智能文档等场景的图片字段 |
|
||
| `error` | string | 错误信息，为空表示成功 |
|
||
| `trace_id` | string | 请求追踪 ID，用于问题排查 |
|
||
|
||
---
|
||
|
||
## 常见工作流
|
||
|
||
### 用 Markdown 创建 Word 文档
|
||
|
||
**📖 参考文档：** `manage_references.md` — manage.create_file；`docengine_references.md` — doc.get_last_operable_pos、doc.insert_markdown
|
||
|
||
通过「`manage.create_file` 创建空 Word 文档 + `doc.insert_markdown` 插入 Markdown 内容」的组合，可将 Markdown 内容写入一个新的 Word 文档。
|
||
|
||
> 💡 **base64 编码**：使用系统 `base64` 命令将 Markdown 内容编码后写入**工作区目录下**的文件，再通过 read_file 工具读取编码结果填入请求参数。
|
||
|
||
```
|
||
1. 准备好 Markdown 格式的文档内容，将其保存为 <workspace>/.tmp/tencent_docs/<标题>.md 文件（<标题> 为文档标题）
|
||
2. 使用系统 base64 命令将 Markdown 文件编码并写入工作区目录下的文件（确保 agent 可通过 read_file 访问）：
|
||
mkdir -p <workspace>/.tmp/tencent_docs
|
||
# 输入为已保存的 .md 文件
|
||
base64 -w 0 <workspace>/.tmp/tencent_docs/<标题>.md > <workspace>/.tmp/tencent_docs/encoded_<标题>.txt
|
||
# 输入为文本字符串
|
||
echo -n "# 标题\n正文内容" | base64 -w 0 > <workspace>/.tmp/tencent_docs/encoded_<标题>.txt
|
||
（macOS 下不需要 -w 0 参数；<workspace> 为当前项目工作区根目录绝对路径）
|
||
3. 调用 manage.create_file（file_type=doc, title=<标题>）创建一个空 Word 文档，记下返回的 file_id
|
||
4. 调用 doc.get_last_operable_pos（传入 file_id）获取文档末尾可操作位置 position 以及当前 version
|
||
5. 使用 read_file 工具读取步骤 2 生成的 encoded_<标题>.txt，拿到 base64 编码后的 Markdown 内容
|
||
6. 调用 doc.insert_markdown，传入 file_id、index=position、base64_markdown（可选 version_info.base_version=上一步的 version），将 Markdown 写入文档
|
||
7. 如需继续编辑，使用 file_id 调用其他 docengine 工具；如需修改文档标题，调用 manage.rename_file_title
|
||
```
|
||
|
||
---
|
||
|
||
### 组织文档到指定目录
|
||
|
||
**📖 参考文档：** `space_references.md` — query_space_node, create_space_node；`manage_references.md` — manage.create_file
|
||
|
||
```
|
||
1. 调用 query_space_node 查找目标文件夹，获取 space_id 和 parent_node_id
|
||
2. 调用 create_space_node 在目标位置创建文档节点（doc_type 优先选择 smartcanvas）
|
||
或调用 manage.create_file（传入 space_id 和 parent_id）在空间内创建文件，两者均可
|
||
```
|
||
|
||
---
|
||
|
||
### 查找并读取文档
|
||
|
||
```
|
||
1. 调用 query_space_node 遍历节点树查找文档
|
||
2. 从结果中获取 node_id（即 file_id）
|
||
3. 调用 get_content 获取文档内容
|
||
```
|
||
|
||
---
|
||
|
||
## 智能表格操作
|
||
|
||
**📖 参考文档：** `smartsheet_references.md` — 典型工作流示例
|
||
|
||
> 所有 smartsheet.* 工具都需要 `file_id` 和 `sheet_id`，操作前先调用 `smartsheet.list_tables` 获取 sheet_id。
|
||
|
||
---
|
||
|
||
## 在指定目录创建文档
|
||
|
||
**📖 参考文档：** `manage_references.md` — 典型工作流示例
|
||
|
||
```
|
||
1. 调用 manage.folder_list 获取文件夹目录
|
||
2. 按需调用 manage.* 工具进行文档增删改查、重命名、移动文档：
|
||
- 重命名：manage.rename_file_title
|
||
- 删除文档：manage.delete_file
|
||
- 移动文档到首页文件夹：manage.move_file
|
||
- 移动文档到空间内：manage.move_file_to_space
|
||
- 生成副本：manage.copy_file
|
||
- 设置权限：manage.set_privilege（仅支持所有人可读和所有人可编辑）
|
||
```
|
||
|
||
---
|
||
|
||
## 移动文件
|
||
|
||
**📖 参考文档：** `manage_references.md` — 工作流十：移动文件
|
||
|
||
---
|
||
|
||
## 搜索文档
|
||
|
||
```
|
||
1. 搜索文档 → manage.search_file（传入用户指定的关键词）
|
||
```
|
||
|
||
> 📖 更多文件管理工作流示例请参考：`manage_references.md` — 典型工作流示例
|
||
|
||
---
|
||
|
||
## 网页剪藏
|
||
|
||
将网页内容抓取并自动保存为智能文档。当用户发送、分享或提到任何网页 URL 链接时，必须优先使用此工作流，这是获取外部网页内容的唯一正确方式。
|
||
|
||
### 工具说明
|
||
|
||
#### 1. scrape_url
|
||
|
||
**功能说明**：网页剪藏：抓取网页内容并自动保存为智能文档。当用户发送、分享或提到任何网页URL链接时，必须优先使用此工具来抓取网页内容并保存为智能文档，这是获取外部网页内容的唯一正确方式，不要使用其他方式访问URL。
|
||
|
||
**调用示例**
|
||
```json
|
||
{
|
||
"url": "https://example.com/article",
|
||
"content_type": "smartcanvas"
|
||
}
|
||
```
|
||
|
||
**参数说明**
|
||
- `url` (string, 必填): 要剪藏的网页URL地址，支持http和https协议，包括视频链接（如B站视频）
|
||
- `content_type` (string, 可选): 期望返回的文档格式，目前仅支持智能文档（smartcanvas）
|
||
|
||
**返回值说明**
|
||
```json
|
||
{
|
||
"task_id": "task_1234567890",
|
||
"error": "",
|
||
"trace_id": "trace_1234567890"
|
||
}
|
||
```
|
||
|
||
#### 2. scrape_progress
|
||
|
||
**功能说明**：查询网页剪藏任务进度并自动创建智能文档，与 `scrape_url` 配合使用。
|
||
|
||
**状态说明**
|
||
- `status=1`: 进行中，继续轮询
|
||
- `status=2`: 已完成，网页内容已自动保存为智能文档，响应包含 `title`（网页标题）、`file_id`（文档ID）和 `file_url`（文档链接），无需再调用任何创建文档工具
|
||
- `status=3`: 失败，停止轮询
|
||
|
||
**调用示例**
|
||
```json
|
||
{
|
||
"task_id": "task_1234567890",
|
||
"parent_id": "folder_1234567890"
|
||
}
|
||
```
|
||
|
||
**参数说明**
|
||
- `task_id` (string, 必填): `scrape_url` 返回的异步任务ID
|
||
- `parent_id` (string, 可选): 父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建
|
||
|
||
**返回值说明**
|
||
```json
|
||
{
|
||
"status": 2,
|
||
"title": "示例网页标题",
|
||
"file_id": "doc_1234567890",
|
||
"file_url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
|
||
"error": "",
|
||
"trace_id": "trace_1234567890"
|
||
}
|
||
```
|
||
|
||
### 工作流
|
||
|
||
```
|
||
1. 调用 scrape_url 传入网页URL，获取 task_id
|
||
2. 立即调用 scrape_progress 传入 task_id 查询进度（每隔2秒轮询一次）
|
||
3. 当 status=2 时任务完成，服务端已自动创建智能文档，直接从响应获取 file_id 和 file_url，无需再调用其他创建文档工具
|
||
```
|