核心功能与用法
DeepRead Agent Setup是一个专为AI代理（headless agent）设计的OAuth 2.0设备授权流认证工具，遵循RFC 8628标准。它解决了无浏览器环境下的API密钥获取难题：代理向api.deepread.tech请求设备码，生成短码（如WDJB-MJHT）并展示给用户，用户在浏览器中打开验证页面完成授权后，代理轮询获取API密钥并设置为DEEPREAD_API_KEY环境变量。
完整流程：请求设备码 → 展示用户码和验证URL → 用户浏览器授权 → 代理轮询获取密钥 → 设置环境变量。整个流程仅接触api.deepread.tech和www.deepread.tech/activate两个域名。
显著优点
1. 人机分离安全认证：代理无需浏览器即可获取用户授权，完美适配服务器、CLI工具、自动化脚本等无头环境
2. 遵循RFC 8628标准：使用业界标准的OAuth 2.0设备授权流，协议成熟可靠
3. 密钥一次性交付：api_key仅返回一次，后续轮询立即失效，降低密钥泄露窗口
4. 用户完全可控：用户明确知晓授权对象（显示agent_name），需主动在浏览器中完成授权操作
5. 灵活的持久化策略：仅设置当前会话环境变量，持久化由用户自主选择（密钥管理器/Shell配置），避免自动写入敏感信息
6. 明确的错误状态：authorization_pending、access_denied、expired_token等状态码清晰可辨
潜在局限性与风险
1. 依赖外部服务可用性：认证流程完全依赖DeepRead API在线状态
2. 15分钟超时限制：用户必须在900秒内完成授权，否则需重新发起流程
3. 轮询效率问题：默认5秒轮询间隔，用户未及时操作时存在网络资源消耗
4. 密钥传输风险：虽然使用HTTPS，但密钥在JSON响应中明文传输，需确保curl/jq等工具环境安全
5. 持久化责任转移：技能本身不处理长期存储，用户若选择Shell配置文件方式，存在明文存储风险
6. 单点密钥管理：获取的是单一API密钥，无自动轮换机制
适合人群
- 开发DeepRead OCR集成工具的开发者
- 需要在服务器/CI环境调用DeepRead API的DevOps工程师
- 构建AI agent工作流需要OCR能力的技术团队
- 熟悉OAuth流程、能接受手动授权步骤的高级用户
常规风险提示
- 密钥泄露风险：
DEEPREAD_API_KEY具备生产环境权限，泄露后可能导致API滥用和费用损失 - 会话隔离问题：仅设置当前shell会话变量，子进程或新终端窗口无法继承
- 误操作风险：用户可能在非预期设备上完成授权，或误点Deny导致流程中断
- 供应链风险：依赖
deepread.tech服务持续运营，API变更可能导致认证失败