用途:当 TOTP 种子存放在需认证的托管方、代理机器从不接触种子时,用本技能取码。若种子在本机(文件、钥匙串、otpauth:// URI),应改用 totp-generate 与 totp-secret-store;向 MCP 客户端供码用 totp-mcp-server;驱动登录用 login-2fa-flow;校验终端用户的 TOTP 码则相反,属于 Twilio Verify 或应用 TOTP 库,不属本技能。
主要能力:支持四种提供方。1Password 用 op item get ITEM --otp、op read "op://v/i/one-time password?attribute=otp",认证为 OP_SERVICE_ACCOUNT_TOKEN;Bitwarden 用 bw get totp ITEM_ID,认证为 bw unlock --raw 得到的 BW_SESSION;HashiCorp Vault 用 GET /v1/totp/code/:name,认证为 X-Vault-Token,是纯 HTTP、无需客户端;2FAuth(自托管)用 GET /api/v1/twofaccounts/{id}/otp,认证为 Bearer PAT。Google Authenticator 不存在服务器 API 或 CLI,只有 otpauth-migration://offline?data=… 导出二维码,属未公开、逆向的 protobuf,需先解码为 otpauth:// URI。
使用方式:脚本 fetch_code.py 先执行 check 检查哪些提供方已安装并已配置凭据,再按提供方取码,例如 python3 "$FETCH" 1password "GitHub" --vault Automation --min-validity 5、bitwarden、vault github --addr …、2fauth 3 --url …。送入表单时用 --min-validity 5;非 30 秒周期用 --period。约定为 stdout 输出一个码并 exit 0,否则非零且无 stdout:3 未找到或有歧义、5 凭据缺失或过期、6 超时、7 提供方错误。
适用场景与限制:适合 CI、无人值守代理。op/bw 缺凭据会退回交互式解锁并挂起,脚本先检查、关闭 stdin、30 秒超时以保证快速失败。凭据需最小化:1Password 用只访问专用保险库的服务账户,且 --vault 在多保险库可见时必填;Vault 策略只授予 totp/code/<name> 的读权限,不要授予 totp/keys/*;2FAuth 用可撤销的 PAT。不要把令牌或取到的码打印到日志,CI 的密钥掩码不覆盖运行时返回值。已知坑包括 op/bw 在 CI 挂起、名称有歧义时应用 item ID、--otp 与 --fields 不能同用、op read 少 ?attribute=otp 会返回种子、Vault 403 多为策略只给了 key 路径、2FAuth 返回 HTML 多为 Base URL 未指向 /api/v1。取码逻辑内置于提供方,不受本机时钟影响,但若本地另有生成则运行器时钟仍相关。