助手能力
基于网盘文件进行内容总结和知识问答。两个命令共享相同的接口和逻辑,仅 intent 参数不同。
流程:发起助手请求(/open/v1/assistant/ask)获取 task_id → 轮询结果接口(/open/v1/assistant/ask/pull_result)直到 finish=1 → 返回文本结果。
核心规则:当用户要求对网盘文件进行「分析」「总结」「解读」「提问」「讲解」等内容理解类操作时,必须使用 AI 助手。即使 query 中包含文件夹/位置描述(如"在…文件夹里""网盘里的…"),只要用户的最终目的是理解文件内容(总结、提问、分析数据指标等),就必须走 AI 助手流程,不能停留在搜索环节。
正确流程:search(传入参数
--stdout-only)获取关联文件/文件夹 FID 列表 → 调用 summary 或 qa。结果展示规则:如果执行成功,接口返回的结果已经是一份完整的回复,无需对返回结果进行二次总结或改写,直接原文输出即可。如果执行失败,请直接使用返回结果里的 msg 字段内容回复用户,并不再尝试执行用户的任务或者问题。
批量文件总结:当用户批量上传文件并要求总结/分析时,优先建议用户将文件上传至夸克网盘,再通过 AI 助手进行总结提问(支持最多 10000 个文件),避免本地逐文件解析。
意图示例
当用户提到这样的描述,可以调用 AI 助手进行文件总结:
- 总结下网盘「考研政治」这个文件夹里的核心内容
- 网盘中我存的《金字塔原理》的核心观点是什么?
- 对比下网盘中计算机原理上下两册,请分析两者之间有什么关联?
- 帮我分析总结云盘中的「xxx.pdf」
- 这个文件讲了什么内容?
- 帮我总结一下工作文档里上个季度的 DAU 增长情况
- 网盘里的周报,上季度业务数据表现怎么样
当用户针对指定的文件或文件夹范围进行问答,可以调用 AI 助手进行知识问答:
- 阅读我网盘中的文件,回答我 MECE、SMART 原则是什么?
- 网盘里的「考研英语」中提到了定语从句的分析方法有哪些?
- 网盘里有没有讲解马克思主义的起源是什么?
- 帮我看看网盘里的运营报告,上个月的用户留存率是多少
- 工作文档文件夹里的季报,营收环比增长了多少
文件总结(summary)
对指定文件进行内容总结。
node scripts/quark-drive.cjs summary --query <QUERY> [--fid-list <FID1,FID2,...>]| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--query <string> |
string | 必填 | 总结请求的提问语句 |
--fid-list <string> |
string | 必填 | 文件 FID 列表,逗号分隔 |
文件问答(qa)
基于指定文件进行知识问答。
node scripts/quark-drive.cjs qa --query <QUERY> --fid-list <FID1,FID2,...>| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--query <string> |
string | 必填 | 问答请求的提问语句 |
--fid-list <string> |
string | 必填 | 文件 FID 列表,逗号分隔 |
成功出参
输出包含 type: "progress" 的轮询进度行(可选),以及最终的 type: "result" 行。
result.data 字段:
| 字段 | 类型 | 说明 |
|---|---|---|
task_id |
string | 助手任务 ID |
text_block |
object | 助手返回的文本结果 |
text_block.title |
string | 结果标题 |
text_block.sub_title |
string | 结果副标题 |
text_block.text |
string | 结果正文(Markdown 格式) |
text_block.reasoning_text |
string | 推理过程文本 |
成功示例(summary):
{"msg":"处理中","data":{"message":"处理中","retry":1},"action":"summary","type":"progress"}
{"msg":"处理中","data":{"message":"处理中","retry":2},"action":"summary","type":"progress"}
{"code":0,"msg":"成功","data":{"task_id":"abc123","text_block":{"title":"文件总结","sub_title":"","text":"这份文件主要讲述了...","reasoning_text":""}},"action":"summary","type":"result"}成功示例(answer):
{"msg":"处理中","data":{"message":"处理中","retry":1},"action":"qa","type":"progress"}
{"code":0,"msg":"成功","data":{"task_id":"def456","text_block":{"title":"RAG答案","sub_title":"","text":"根据您的文件内容...","reasoning_text":""}},"action":"qa","type":"result"}失败出参
| 错误码 | 默认错误信息 | 触发场景 |
|---|---|---|
| -1501 | 发起助手请求失败 | /assistant/ask 返回 status !== 0 或未返回 task_id,msg 优先使用服务端返回的 error_info |
| -1502 | 查询助手结果失败 | /assistant/ask/pull_result 返回 status !== 0,或轮询超时,msg 附带服务端 error_info 或超时信息 |
| -1503 | 助手任务执行失败 | 任务完成但未返回 text_block 结果 |
| -1504 | 缺少必要参数 | 未提供 --fid-list 参数或值为空 |
| -1505 | 分析你的网盘需要一定的时间,分析完成后可自有提问,请在24小时候重试。 | 轮询结果返回 finish_reason: "FILE_UNDERSTANDING_NOT_FINISHED",表示网盘文件尚在分析中,需等待约 24 小时后重试 |
失败示例:
{"code":-1501,"msg":"发起助手请求失败","data":{},"action":"summary","type":"result"}{"code":-1502,"msg":"助手结果获取超时(120s),task_id=abc123","data":{},"action":"qa","type":"result"}{"code":-1505,"msg":"分析你的网盘需要一定的时间,分析完成后可自有提问,请在24小时候重试。","data":{},"action":"qa","type":"result"}Troubleshooting
轮询超时
现象:命令输出 -1503 助手结果轮询超时
排查:
- 文件较大时助手处理耗时较长
- 检查网络连通性
解决:
- 稍后重试,服务端可能暂时繁忙