八爪鱼 Connector Skill
本 Skill 指导 AI 在 WorkBuddy 中正确使用「八爪鱼」MCP 连接器。
鉴权方式为 OAuth（浏览器授权）。除非 OAuth 失败且客户端明确要求其它方式，否则不要向用户索要 API Key。
首发工具范围
本连接器仅暴露以下 6 个工具：
| 工具 | 用途 |
|---|---|
search_templates | 发现或精确解析云采集模板 |
execute_task | 创建并启动云采集（单次最多等待约 45 秒） |
get_task_status | 查询标准化状态 / 已采集行数 / 批次号 |
export_data | 读取某一采集批次的一页 JSON 数据 |
search_tasks | 在当前授权账号下查找已有任务 |
start_or_stop_task | 启动或停止已有任务 |
不要编造其它工具名（无优惠券、电商专用、平台内容搜索等工具）。
推荐工作流
- 发现模板：用
search_templates的语义query（写清站点 + 数据类型 + 采集意图）。 - 补全 Schema（需要时）：用精确
id或slug再调search_templates，拿到完整inputSchema/sourceTree。 - 启动任务：
execute_task传入templateName+parameters（JSON 对象字符串）。强烈建议带唯一taskName。 - 若仍在运行：用
taskId调get_task_status轮询至completed或stopped（不要无限卡在一次调用上）。 - 读数据：
export_data传入taskId+lotNo（来自 execute/status），用page/pageSize分页。 - 管理已有任务：先
search_tasks，再start_or_stop_task或export_data。
鉴权说明
- 用户连接本 Connector 时，由 WorkBuddy 自动完成 OAuth。
- 所有工具都需要有效用户会话；未登录会返回 401 及 OAuth 发现信息。
- 若长时间闲置后出现 unauthorized / invalid_token，引导用户重新连接本连接器（refresh_token 可能已过期）。
- 禁止在对话、日志示例中输出 access token。
工具说明
search_templates — 搜索模板
用户要抓取 / 采集 / 抽取网页数据、需要云模板时使用。
每次调用只能选一种选择器：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
query | string | 三选一 | 语义搜索：完整描述站点、数据与采集意图 |
id | number | 三选一 | 按模板 ID 精确查询 |
slug | string | 三选一 | 按模板 slug / 别名精确查询 |
limit | number | 否 | 仅可与 query 同用；1–20，默认 10 |
规则：
- 优先选
score高、且支持云端执行（executionMode）的模板。 - 语义搜索后，若需要完整
inputSchema与sourceTree再执行任务，请用id或slug精确查询。 - 不要传已废弃参数
keyword、page。
示例：
- 语义：
query= 「亚马逊美国站无线耳机搜索结果 商品标题 价格」 - 精确：
id= 12345
execute_task — 启动云采集
创建任务并启动云端运行，最多等待约 45 秒返回进度快照。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
templateName | string | 是 | 来自 search_templates 的模板名 |
parameters | string（JSON 对象） | 否 | key 使用 inputSchema[].field；默认 {} |
taskName | string | 否 | 友好且唯一的任务名；强烈建议填写，便于 search_tasks 找回 |
参数类型约定：
- Input / Dropdown → 字符串
- MultiInput / CheckboxList → 字符串数组（即使只有一个值）
- 依赖 source 的字段 → 传精确查询
sourceTree中选项的key；若仍缺依赖，工具返回input_required与下一层sourceOptions，补全后再次调用（参数未就绪时不会创建任务）
结果要点： taskId、lotNo、collectedRows、status（running / completed / stopped）。
规则：
collectedRows默认可能为 0；需结合status区分「仍在跑暂无数据」与「终态无数据」。- 若担心客户端超时，务必保留
taskId/taskName，后续用get_task_status/search_tasks续查。 - 在
export_data（或大结果 curl 导出）成功前，不要声称数据已全部导出。
get_task_status — 查询任务状态
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
taskId | string | 是 | 来自 execute_task 或 search_tasks |
返回： status（running / completed / stopped）、collectedRows、可用时的 lotNo。
规则：
running时退避轮询，终态停止。- 同一任务优先用本工具续查，不要重复
execute_task。
export_data — 导出一页数据
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
taskId | string | 是 | 八爪鱼任务 ID |
lotNo | string/number | 是 | 精确批次号（来自 execute/status） |
page | number | 否 | 默认 1 |
pageSize | number | 否 | 默认 20，最大 100 |
返回： 当前页 Body（data、分页信息等）；数据量大时可能含 directAccess（签名 URL / curlTemplate）——大结果优先用 curl，避免占满模型上下文。
search_tasks — 搜索已有任务
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | number | 否 | 页码 |
size | number | 否 | 每页条数，默认 10，最大 100 |
keyword | string | 否 | 任务名等关键词 |
status | enum | 否 | Running / Stopped / Completed / Failed |
taskIds | string[] | 否 | 指定任务 ID 列表，最多 100 |
用户提到已有任务但没有 taskId 时，先用本工具再导出或启停。
start_or_stop_task — 启停任务
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
taskId | string | 是 | 已有任务 ID |
action | enum | 是 | start 或 stop |
规则：
- 对未在运行的任务执行
stop，可能返回成功且状态为already_stopped。 start可能因积分、权限、模板不可用、限流失败——直接展示工具返回说明，不要盲目重试。- 可能的情况下先查状态，再决定是否 start。
错误处理
| 情况 | 处理建议 |
|---|---|
| 401 / invalid_token | 请用户重新连接本 Connector（OAuth） |
execute_task 返回 input_required | 按返回补参数 / source 选项后重试 |
| 模板找不到 | 放宽 query 或改用精确 id/slug |
execute 后仍为 running | 轮询 get_task_status，不要编造已完成 |
| 积分不足 / 权限不足 | 展示工具原文；勿盲目重试 |
export_data 为空 | 核对 lotNo、任务状态与页码 |
| 长采集超时 | 用 taskId / taskName 恢复，继续轮询状态 |
回复风格
- 进度更新宜短，突出
taskId、lotNo、行数等关键字段。 - 若已有
directAccess.curlTemplate，不要把超大data数组整段贴进对话。 - 若界面已展示列表，口头摘要即可，不必逐条重复。
相关链接
- 产品站：https://www.bazhuayu.com
- 托管 MCP：https://mcp.bazhuayu.com
