技能介绍

解决的问题

Agent 在调用受保护能力时，常遇到两类实际问题：一是本地 Python 环境路径不统一，Windows 下 python 可能误启 Microsoft Store，导致脚本执行失败；二是授权链路长且状态多，凭证缺失、过期、远程校验失败等情况容易被误判为“致命错误”，要么提前中断流程，要么在未授权时强行产出业务结果，造成结果不可控。

工作方式与关键步骤

技能以 scripts/auth.py 为核心，按固定顺序执行：

前置环境检测：先静默检测 Python 命令，优先复用已有的 PYTHON_CMD；若检测不到但用户提供了路径，直接使用该路径，无需重新检测。
凭证与授权检查：执行 auth.py --ensure，输出 AUTH_OK 则通过；若输出 AUTH_REQUIRED 或 CREDENTIALS_MISSING，说明仅缺少本地缓存凭证，需自动触发绑定，而非中断。
自动绑定流程：主动调用 WorkBuddy 的 connect_cloud_service 获取 JWT，再用 auth.py --bind-jwt 完成绑定，成功后重新 --ensure 确认 AUTH_OK。
受保护内容拉取：仅当 scripts/protected.py 返回 protected instructions 时，才继续执行业务；未拿到则立即停止，不依赖本地提示补全。

适用边界与注意点

勿混淆信号：AUTH_REQUIRED 是首次绑定的正常状态，不是失败，必须自动继续绑定，不能停下打扰用户。
重试上限：凭证失效时重新绑定并 --ensure，最多重试 1 次；两次失败则判定为服务端问题，停止业务推理。
鉴权与业务互斥：只要未拿到 AUTH_OK 或 protected instructions，禁止产出任何业务结果，避免“鉴权失败但硬出结果”的风险。
密钥保护：全程不手动解析 JWT、不拼接 AppKey/AppSecret，也不向用户暴露密钥明文，仅转述脱敏后的错误信息。