授权与账号管理
本文档承接 SKILL.md 中的未授权处理、登录、取消授权、卸载、用户信息和自更新流程。
未授权处理
所有命令都可能输出未授权错误。当 stdout 输出的 NDJSON 中 code 为非零负数且 msg 包含"未授权"、"认证"、"token"等关键词时,表示用户当前未授权或授权已过期。
未授权时的 NDJSON 输出示例:
{"code":-1408,"msg":"未完成授权认证","action":"not_authenticated","type":"result","data":{}}agent 须知:
- 检测到未授权输出后,agent 必须先将 CLI 返回的
msg字段内容展示给用户(如示例中的"未完成授权认证"),明确告知用户当前未授权或授权已过期,禁止在未做任何说明的情况下直接调用login。- 展示
msg后,自动调用login命令引导用户完成登录授权,登录成功后再重新执行原命令。- agent 禁止重复尝试执行原命令。
登录命令
通过 login 命令完成授权登录。
浏览器 OAuth 登录
login 命令会启动本地授权服务器,自动打开浏览器完成 OAuth 授权,命令会阻塞等待直到授权完成或超时。
# 浏览器 OAuth 登录(阻塞等待授权完成)
node scripts/quark-drive.cjs login
# 授权码登录(非交互式)
node scripts/quark-drive.cjs login --token <agent_auth_code>| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
--token <token> |
string | 选填 | 直接提供授权码,跳过浏览器授权流程 |
agent 调用流程:
- 调用
node scripts/quark-drive.cjs login,命令会自动打开浏览器并等待用户授权。- 授权完成后命令自动返回登录结果。
- 登录成功后,执行后续命令。
已授权账号重复登录
普通 login 会先校验当前授权;当返回 code: -118 时,表示当前夸克网盘账号授权仍然有效。agent 必须:
- 原样展示 CLI 返回的
msg,其中账号名称是服务端返回的真实昵称; - 立即停止本次登录流程,不得再次调用
login; - 不得展示登录成功欢迎文案,也不得进入手动授权码引导;
- 用户确实想切换账号时,先按本文档的“取消授权命令”执行
unauthorize。
当用户已在授权页完成操作并提供 agent_auth_code 时,使用 login --token <agent_auth_code>。该模式代表明确的重新授权意图,会跳过上述重复授权校验,直接执行现有授权码登录流程;无效或过期的授权码仍由服务端按现有逻辑拒绝。
登录成功后的引导规则
当 login 返回 code: 0 时,agent 必须按以下优先级处理:
- 如果本次
login是某个原命令执行过程中的自动重试(即 login 紧跟在原命令之后、为完成该操作而触发),无论data.status是什么,登录成功后都应直接继续执行原命令,不得展示任何授权成功引导。 - 如果本次不是自动重试,且
data.status为"install_confirmed",agent 必须原样展示data.msg:
授权完成,当前网盘文件授权范围为全部文件,你可在【夸克网盘App-我的-登录授权管理-其他AI助手授权】中,修改授权范围。展示上述授权范围引导后,不得再展示下方“授权登录成功我能做这些事”能力介绍。
- 如果本次不是自动重试,且
data.status为其他成功状态,agent 再检查以下任一条件是否满足(不依赖 agent 自行判断"是否有未完成任务",而用确定性标志触发):
- 本次是用户主动触发的登录(用户说「授权」「登录」「绑定」「清空记忆重新授权」等)
- 本地
config.json中accounts为空(首次授权,或清空记忆后的重新授权) - 本次
login没有紧跟在原命令之后(即 login 不是某个操作的自动重试)
满足任一条件时,agent 必须原样输出以下欢迎文案:
授权登录成功我能做这些事:
💾 你在 AI 里的对话和重要文件,直接存网盘
● 「规划的国庆三亚 5 日游行程,存到网盘里」
● 「每天定时生成美股分析,总结好后存进网盘」
🔍 你网盘里的文件,随时能找出来用
● 「找到我和妈妈在西湖边的合照,帮我做成母亲节贺卡」
● 「找出我存的装修报价单,和最新这份做成对比表」
📚 公开资料随手存,AI 搭好知识库随时问
● 「帮我找几篇 AI 产品经理面经存到网盘」
● 「根据网盘里的基金入门书,月入 1 万怎么分配定投?」
📷 网盘照片随心整理,AI 帮你挑
● 「网盘里所有带猫的照片整理到一起」
● 「去年日本旅行的照片,按东京大阪京都整理一下」
注:智能搜索、相册整理、知识库问答为 AI 高级功能,当前仅开放 5000 体验名额,先到先得!不满足上述展示条件时,不输出授权成功引导。
自动登录失败 / 授权超时处理
浏览器 OAuth 自动登录并不总能成功(如超时、浏览器未弹出、授权回调未被本地服务捕获等)。一旦 login 未能自动完成登录,agent 绝对禁止只贴一个授权链接就结束,必须完整、清晰地引导用户走「手动复制授权码 → 粘贴到对话框」的流程:
- 将 CLI 输出的授权链接 URL 以可点击形式提供给用户。
- 明确告知用户:在浏览器中打开链接并完成授权后,从浏览器跳转后的 URL 中复制
code参数的值(即授权码)。 - 重点强调:请用户将复制到的授权码直接粘贴回当前对话框发送给 agent。
- agent 收到用户粘贴的授权码后,使用
node scripts/quark-drive.cjs login --token <授权码>完成登录。 - 登录成功后,自动重新执行用户最近未完成的原命令。
展示失败原因:在自动登录失败(超时、授权未完成、返回非
code: 0等)时,agent 必须先将 CLI 返回的msg字段内容展示给用户,告知用户失败的具体原因,再进入下方手动授权引导流程。话术要求:在自动登录失败时,agent 必须用明确、引导性的语言告诉用户「把授权码粘贴到对话框发给我」,禁止使用让用户自行在终端执行
node scripts/quark-drive.cjs login --token的表述。禁止自动重试
login:当login失败(超时、授权未完成、返回非code: 0等)时,agent 绝对禁止自动再次执行login命令。必须停下来等待用户主动提供授权码或明确要求重新登录。
取消授权命令
当用户要求取消授权 / 解除授权 / 退出登录 / 解绑设备时,调用 unauthorize 命令。
node scripts/quark-drive.cjs unauthorize该命令不会直接解除授权,而是返回一个解除授权地址(H5 页面)。用户需在「夸克网盘」独立端 App 中打开该地址,在页面上完成解除授权操作。
二维码展示规则:
- 优先呈现
data.qrImagePath指向的 PNG 图片二维码。- 若无法读取/展示该图片,必须根据
data.revokeUrl自行构建二维码,或退而呈现 CLI 在终端输出的块字符二维码。- 若确实无法以任何二维码形式呈现,才以可点击链接形式展示
revokeUrl作为最后兜底。- 必须明确告知用户:需使用「夸克网盘独立端 App」扫码或打开该地址,不要在普通浏览器中打开。
- 展示文案直接使用
data.msg字段内容即可,禁止暴露deviceId、revokeUrl、qrImagePath字段名等技术细节。- 必须同时附上 App 内手动解绑路径,原样输出:
若无法扫码,打开夸克网盘 App → 我的 → 登录授权管理 → 网盘 Skill 授权,进入后即可解除绑定。 ⚠️ 解绑后该设备上的网盘授权都将失效,需重新授权才能恢复
unauthorize 与 logout 的区别
CLI 提供两条「撤销授权」路径,用途完全不同,agent 必须区分调用:
| 命令 | 适用场景 | 行为 | 是否清除本地环境 |
|---|---|---|---|
unauthorize |
用户主动要求取消授权 / 解除授权 / 解绑设备(但仍保留 CLI) | 返回解绑 H5 地址 / 二维码,由用户在「夸克网盘」独立端 App 上确认完成 | 否 |
logout |
仅卸载时由 uninstall.sh 内部调用 |
通过 access_token 直接、静默地撤销本机授权,随后删除当前 agent 的配置目录 | 是 |
调用规则:
- 用户主动说「取消授权 / 解除授权 / 退出登录 / 解绑设备」且没有要卸载 → 调用
unauthorize,绝不要调用logout。logout不是面向用户的命令,agent 不要单独调用它;它只在uninstall.sh卸载本地环境时被自动调用。
卸载 / 删除 Skill(清除本地环境)
当用户要求卸载 / 删除 Skill、清除本地环境、清空所有数据并重置时(无论用户说的是「删除」还是「卸载」,均走同一套逻辑),需完成以下两步:
Step 1:执行 uninstall.sh(撤销授权 + 清除当前 agent 配置)
uninstall.sh 会调用 logout 在服务端撤销本设备授权,并删除当前 agent 的配置目录(含登录态 / access_token / 账号信息)。
bash uninstall.sh⚠️
uninstall.sh仅删除当前 agent 的配置目录,不会删除 skill 目录中的 CLI 脚本和文档文件。
禁止跳过
uninstall.sh直接用rm -rf删除,否则服务端授权记录不会被撤销。
Step 2:删除 skill 目录(移除 agent skill 文件)
uninstall.sh 只撤销当前 agent 授权并清除其配置目录,不会删除 agent skill 目录中的 skill 文件(SKILL.md、references/、scripts/ 等)。uninstall.sh 执行成功后,agent 还需删除本 skill 所在目录,将 skill 从 agent 环境中完全移除。
二次确认(必须执行,不可跳过):卸载会撤销授权并清除本地信息,属于不可逆操作。agent 在执行上述步骤之前,必须先用自然语言明确告知用户即将发生什么、会清除哪些信息,并取得用户的二次确认后才能调用。
告知话术按以下文案输出(用自然语言表达,不要暴露文件路径等技术细节):
确认卸载夸克网盘 Skill? 卸载将执行以下操作:解除网盘账号对当前设备的授权 • 清除本地配置与缓存 • 移除 Skill 文件。 你的网盘文件不会受到影响。如需再次使用,重新安装 Skill 并完成授权即可。
仅当用户明确回复「确认 / 是 / 继续卸载 / 继续删除」等肯定意图后,才依次执行上述两步。若用户只是想取消授权但保留 CLI,应改用
unauthorize,不要卸载。
查看用户信息命令
当用户想查看自己的账号 / 会员信息时(如"我的网盘账号是谁""我是不是会员""查看我的会员状态""我的网盘容量还剩多少""我登录的是哪个账号"),调用 get-user-info 命令。
node scripts/quark-drive.cjs get-user-info该命令会依次调用会员信息和用户信息两个接口,两者都成功才算整体成功;任一失败都会返回对应错误并终止。可用于确认当前授权账号、会员等级与网盘容量,也常用于授权后的探活 / 自检。
结果展示规则:
- agent 以自然语言概括用户的账号信息,至少包含昵称与会员类型;如返回了容量信息,可一并换算为可读单位(如
1.2 TB / 6 TB)告知。- 会员类型需转为用户易懂的表述(如
NORMAL→ "普通用户"、SVIP→ "超级会员"),禁止直接输出英文枚举值或原始时间戳。- 遵守全局约束:禁止向用户暴露字段名与技术细节。
- 接口失败时,直接使用返回的
msg文案告知用户,并按「未授权处理」判断是否需要引导用户重新login。
自更新命令
当用户要求升级、更新 CLI / Skill 版本时,直接执行 install.sh 即可:
bash install.sh重要:升级/更新时不需要对比本地与远端内容,也不需要检查差异,直接重新执行
install.sh。install.sh会从服务端拉取并安装最新版本的 skill 包,完成自更新。