Cube Tools

---
name: cube-tools
description: 用 Cue 全能解析助手连接器把公网网页/在线文档解析成 Markdown、可检索分块或带来源定位的 hypertext；含三个工具的用法、参数、示例与错误恢复约定。
---

# Cue 全能解析助手（cube-tools）

把这个连接器的能力接到「读网页 → 产出可用内容」这一步之前：给定一个公网可访问的
`http(s)` 地址，取回结构化内容，再继续用户原本的任务。

- **能解析**：公网可达的网页、在线文档、B 站/YouTube 等视频页面（服务自动做 ASR+OCR 提取）。
- **不能解析**：本地文件、内网地址、需要登录的页面。服务方明确不许把这些内容读出来再内联送进去。

## 工具

### `parse` —— 发起解析

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `source` | string | — | 要解析的公网 `http(s)` 地址（**推荐用这个**） |
| `url` | string | — | 旧参数名，仍被接受；新调用用 `source` |
| `output` | `markdown` \| `hypertext` \| `chunks` | `markdown` | 输出形态，见下 |
| `wait` | boolean | `true` | `true` = 等到终态再返回；`false` = 立刻返回初始处理态 |
| `detail` | string \| null | `null` | `text` 或省略 = 正常；传 `grounded`/`layout` 会**失败关闭**（本出口只产 markdown，不会静默降级） |

返回值是这次解析操作的**结构化状态**（含操作标识与结果），成功与失败都走同一形态 ——
先读状态字段，再决定下一步，不要只看有没有抛异常。

### `get_parse_status` —— 取进度/结果

恢复某个**已存在**操作的权威进度或终态结果。用在 `parse(wait=false)` 之后，
或用在你不确定上一次调用是否完成时。

### `cancel_parse` —— 取消

请求取消一个已存在的解析操作。

## 选哪种 `output`

| 形态 | 拿到什么 | 适合 |
|---|---|---|
| `markdown` | 正文（默认） | 摘要、改写、翻译、纯阅读 |
| `hypertext` | 带来源定位的正文 | 引用、事实核查、需要标出处的回答 |
| `chunks` | 检索用分块 | 喂 RAG / 检索问答 / 长文分段处理 |

## 典型流程

1. **常规**：`parse(source="<url>")` —— `wait` 默认 `true`，多数情况一次就拿到结果。
2. **长文档 / 容易超时**：`parse(source="<url>", wait=false)` 拿到操作标识，
   再用 `get_parse_status` 轮询到终态。
3. **不想要了**：`cancel_parse`。
4. **解析完之后**：回到用户原来的问题继续做（别停在「已经解析好了」）。

## 错误恢复（服务的硬约定，务必遵守）

1. 把用户给的地址**原样**传给 `parse`。**不要**自己先读一遍内容再 base64 或内联送进去。
2. 只有 `http(s)` 才算 URL。普通本地路径会返回一个**明确的 Bridge 要求**，本连接器不支持。
3. **不要**用 `file://`、`localhost`、或公共临时上传网盘作为兜底方案。
4. **不要**要求用户把 API Key 粘贴到对话里 —— 授权走标准 OAuth，凭据由连接器持有。
5. 只有在**结构化状态允许**时才重试；重试前先用 `get_parse_status` **恢复已有操作**，
   不要重复提交同一个地址。
6. **工具级错误不等于 MCP 断连** —— 读返回里的结构化错误再判断，不要贸然重连。
7. 客户端不具备 task 能力时，**不要承诺**「后台跑完会通知你」。
8. 清理动作**未被确认之前**，不要声称已经删除。
9. 如果用户要装本地 Bridge 或扩大可访问目录 —— **先问过用户**再做。

## 授权

标准 MCP OAuth：连接时浏览器跳转授权一次即可，用户无需提供任何密钥。
授权范围由服务端 entitlement 决定（本连接器对应 `omni_reader`）。