# 公共接口与常见工作流

本文件包含两部分内容：
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，无需再调用其他创建文档工具
```