用途：让自动化登录通过 TOTP 两步验证挑战，同时避免浪费尝试次数或锁定账号。它修复常见不稳定问题：本可用已保存会话却仍做验证、验证码临近过期才生成、重复提交被拒验证码、重试到锁定，以及硬碰无法脚本化的推送或 WebAuthn 提示。
授权前提：仅对用户拥有或获授权自动化的账号使用。涉及他人个人凭据时应停止并确认是否为受认可的服务或共享账号。
不适用：生成验证码用 totp-generate；保管种子用 totp-provider-api；种子存放用 totp-secret-store；经 MCP 提供验证码用 totp-mcp-server。也不用于在自己产品中实现 2FA 验证、CAPTCHA 破解或绕过非用户控制的挑战。
验证码来源契约：本技能不生成验证码，而是接收一个 code 命令，要求：stdout 只输出验证码；成功退出 0，失败非 0 且 stdout 为空；返回的验证码至少约 5 秒有效期；幂等，运行两次不消耗任何东西。示例：python3 totp.py --file ~/.config/totp/github.txt --min-validity 5。TOTP 窗口是绝对的，远程获取还有往返延迟，生产者必须等待新窗口。备份码来源不满足幂等规则，preflight.py 会拒绝破坏性命令。shell 管道应设 set -o pipefail。
工作流：1) 能跳过就跳过 2FA，先尝试已保存会话，仅在失效或被拒时完整登录；Playwright 可用 storageState 复用，认证状态文件应 gitignore 并注意过期。2) 在触碰表单前预检验证码来源：python3 "${CLAUDE_SKILL_DIR}/scripts/preflight.py" --code-command '...'。3) 识别挑战类型：6–8 位验证码属本技能；短信/邮件码需 API 或人工；推送、WebAuthn、恢复码、CAPTCHA 应停止。4) 输入前校验来源，按账号固定预期 origin 并与当前页面比对，不匹配则停止。5) 在窗口内提交，提交前才生成验证码，等待导航或错误元素而非固定 sleep。6) 重试规则：绝不重发相同数字，需等下一个时间步再生成并提交一次；最多两次尝试，跨运行按账号累计；第二次前检查时钟漂移。7) 持久化结果，接受“记住此设备”并保存会话状态。
输出规范：登录成功，或带具体原因停止且不再尝试；填写前已验证来源；最多两次提交；会话状态保存到 gitignore 路径；转录、测试输出或 CI 日志中不得出现种子或密码。验证码会经过模型上下文并进入存储转录，但数秒即过期；种子进入转录则是永久泄露。
限制：推送和 WebAuthn 无法程序化完成；数据中心与 CI 出口 IP 常触发额外设备验证；账号锁定恢复需人工。