cli-auth

name	cli-auth
label	命令行授权
icon	terminal
summary	安全处理阻塞等待扫码或网页授权的 CLI
description	命令行扫码与网页授权等待规程。用于 init/login 等打印授权链接或字符画二维码后持续等待、不会自行退出的 CLI 命令。
user-invocable	false
tools	["mastra_workspace_execute_command","mastra_workspace_get_process_output","mastra_workspace_kill_process","show_qr"]
metadata	{"category":"capability"}

命令行授权

当 CLI 首次使用需要扫码或网页授权时（init/login 类命令，打印授权链接或字符画二维码后停在“等待扫码/授权”不退出），严格执行本规程。

方式选择优先级

在决定接入方式前，必须先运行该 CLI 的 init/login 类命令的 --help（如 cli init --help、cli login --help），摸清它提供的全部接入方式。优先选择自动化程度最高、可由产品承接的扫码、device flow 或非交互方式（如 --noninteractive），由产品渲染二维码卡让用户扫码。

不要主动把用户推去第三方管理后台手动创建应用、复制 AppID/App Secret 等凭证；只有 --help 已确认该 CLI 完全没有任何自动授权方式时，才可引导手动配置，并明确说明为什么只能手动。

标准流程

1. 按帮助启动：运行这类命令前先查看该 CLI 的 --help；若帮助中提供“不自动打开浏览器”之类的选项（如 --no-open），启动命令必须带上，具体参数名以该 CLI 的帮助为准，禁止凭经验硬编码猜测。

2. 后台启动：这类命令绝不能前台跑死等，否则会一直挂到超时，用户什么都看不到。用 background:true 后台启动并拿到 PID。

3. 轮询输出：用 mastra_workspace_get_process_output(pid, tail) 轮询输出，严禁带 wait:true。wait 会阻塞等进程退出，而授权进程在用户扫码前不会退出，会把本轮拖到超时中止，后台授权进程也会被连带终止。

4. 提取候选链接：从输出提取授权 URL，通常紧邻二维码字符画，形如 https://…。

5. 出码前验真：CLI 打印的文字链接常常只是“桌面出码展示页”（打开又是一张二维码，扫了等于套娃，手机客户端还扫不了页面里的图），真正扫码直达的授权 URL 往往只编码在字符画二维码里。必须把候选链接的页面正文拉下来，搜索内嵌授权 URL：

   • Windows：curl -s "候选URL" | findstr /i "auth_url redirect_uri jump_url"
   • 其他平台：把 findstr 换成 grep

   只查 HTTP 状态码（-o NUL -w 之类）不算验真，必须读取正文。搜到 auth_url / redirect_uri / jump_url 之类字段里嵌着 https 链接，就改用页面内嵌的那个 URL 出码；正文里没嵌链接（或链接本身就是授权/登录页）才用原链接。

6. 展示二维码：调用 show_qr，把验真后的 URL 渲染成二维码卡给用户扫，配置 confirmQuery 收尾话术，并记住工具结果返回的 cardId。字符画二维码在聊天里渲染不出来，绝不要把它原样贴进回复，一律转成 show_qr 卡。

7. 立即收尾：发出二维码卡后立刻收尾并结束本轮回复。等用户扫完码点确认，再在下一轮轮询输出确认授权完成。

8. 验证并更新原卡：只有从 CLI/服务输出验证到成功标志后，才调用同一个 show_qr，传 {"completedCardId":"<首次返回的 cardId>","completionMessage":"授权已完成"} 把原卡更新为完成态；未验证成功时禁止更新。

用户回报后的意图边界

• 用户说“我扫完了/已授权/好了/完成了”等完成语义时，只轮询现有进程输出验证，严禁 kill 进程、严禁重新起进程、严禁重新出码。只有验证到成功标志才可报告授权完成；未验证到就如实说“还没检测到完成，可能还没生效/还在等待”，让用户决定下一步。
• 只有用户明确说“过期了/重新生成/重来一个/换一个码”等重来语义时，才用 mastra_workspace_kill_process 结束旧进程并重起。拿不准是哪种语义时，默认只轮询，不做不可逆动作。

等待与轮次边界

• 非交互后台等待：用户明确说“等它结束/跑完告诉我”时，若进程不是在等待扫码、授权或输入等用户交互，应持续用有界 wait 轮询直到进程退出再收尾；一次约 60 秒的有界 wait 返回后继续下一次，不要把球踢回用户。若预计仍需很久，可以先给一次进度反馈再继续等待。扫码/授权等交互等待仍按上文出码后立即收尾，严禁用 wait 死等。
• 轮次抢占边界：持续轮询只服务于本轮用户明确要求的等待；一旦本轮被后续新消息中断，下一轮必须优先处理新的用户文本。除非新文本明确要求继续等待、查询或终止旧后台进程，否则不得因历史里仍有 PID/等待卡而自动续跑旧轮询。新消息抢占只中止 Agent 等待，不代表后台进程已终止；没有进程退出或 kill 结果时必须如实说状态待确认。

show_qr 文案

• 卡片内部固定按“标题 → 二维码 → note”渲染，note 位于二维码下方；因此 note 指代二维码时必须写“上方二维码/上面的二维码”，禁止写“下方二维码/下面的二维码”。这里说的是 note 与二维码的卡内相对位置；卡片整体仍按工具说明位于本条回复下方，两种方位不要混淆。
• completionMessage 必须是“已完成”的终态陈述，不要以半角或全角省略号结尾，也不要写成“正在……”等进行中口吻。