# X/订阅源管理的 API readiness、费用、权限与限速恢复链路 ## Before / After | 环节 | Before | After | | --- | --- | --- | | 前置检查 | 脚本运行后才发现 `X_CLIENT_ID` 缺失、`client-not-enrolled` 或 `CreditsDepleted` | 先跑 `x-api-readiness`，按 credentials、credits、scope、permission、rate-limit 给出阻塞项 | | OAuth 权限 | 遇到读/写失败后临时重新 Authorize app | 工具明确提示缺哪个 scope、是否需要升级 App 写权限、是否需要重新授权 | | 批量取关 | 306 个批量任务中途 429，第一版未写最终审计，真实完成数需要人工追 | 每个账号即时审计，失败时保留错误和剩余名单，可从 `remaining.csv` 续跑 | | 恢复策略 | 依赖人工记忆“已经取关约 100 个，剩余 206” | `audit.jsonl` 是事实源，`rate_limit_state.json` 记录限速桶和建议恢复时间 | ## 升级后的诊断流程样例 ```bash cd ~/Documents/info-bu python .agents/skills/subscribe-hub/scripts/x_api_readiness.py \ --operation write_unfollow \ --target-count 306 \ --config .agents/skills/subscribe-hub/config.json \ --out out/x_api_readiness_$(date +%F).json ``` 预期输出： ```json { "operation": "write_unfollow", "ready": false, "checks": { "credentials": {"status": "ok"}, "credits": {"status": "ok", "remaining_hint": "sufficient_for_smoke_unknown_for_bulk"}, "oauth_scope": {"status": "fail", "missing": ["users.write"]}, "app_permission": {"status": "fail", "reason": "write_permission_missing"}, "rate_limit": {"status": "ok", "reset_at": null} }, "next_actions": [ "Upgrade X app permission to Read and write", "Re-authorize app with users.write scope", "Re-run readiness before batch unfollow" ] } ``` 批量脚本只在 `ready=true` 时执行；若执行中收到 429，立即停止当前批次，写入失败账号、限速 reset 时间和剩余名单。下一次执行： ```bash python .agents/skills/subscribe-hub/scripts/x_unfollow_batch.py \ --input out/x_unfollow/remaining.csv \ --audit out/x_unfollow/audit.jsonl \ --resume ``` 成功标准：审计文件中 `unfollowed + skipped + failed + remaining` 数量等于原始输入数量，且没有账号只存在于内存进度里。