核心概述
Portable-tools 是一套源自 OAuth 刷新器调试实战的跨设备开发方法论，核心目标是将"在我机器上能用"转变为"在任何机器上都能用"。
核心用法
三大前置问题：编写代码前必须回答
- "设备间什么会变化？"（路径、账户名、服务名、数据结构、环境）
- "如何证明它有效？"（记录 BEFORE/AFTER 具体值，进行对比验证）
- "出问题时怎么办？"（主动测试错误配置、缺失数据、多条目等异常场景）
四大强制模式：
1. 显式优于隐式：避免模糊匹配，使用明确参数（如指定账户名而非返回首条匹配）
2. 使用前验证：永远不要假设数据结构符合预期
3. 降级链设计：配置值 → 常用默认值 → 错误提示，而非硬编码单一值
4. 有用错误信息：错误消息应包含诊断命令和修复指引
显著优点
- 实战验证：源于真实的 OAuth keychain 调试，非理论推导
- 系统化框架：从发现→实现→测试→文档的完整流程
- 可验证性：强制要求 BEFORE/AFTER 对比，杜绝"应该能用了"的模糊验收
- 防御性编程：主动设计失败路径，而非事后修补
- 快速集成：提供与 sprint-plan、privacy-checklist、skill-creator 的联动方式
潜在局限
- 认知成本：三问题四模式需要刻意练习才能内化为本能
- 初期开发速度：显式配置和验证会增加前期代码量
- 过度工程风险：简单脚本可能不需要完整方法论
- 文档维护：需要持续更新"常见变体"和故障排查指南
- 团队协作依赖：需要团队共同遵守，单人难以在项目中强制执行
适合人群
- 开发将在多台机器或团队中运行的 CLI 工具/脚本
- 处理 keychain、凭证、环境变量等系统配置的场景
- 计划发布到公共仓库（如 ClawdHub）供他人使用的工具开发者
- 厌倦了"在我机器上能跑"调试噩梦的开发人员
常规风险
- 假设盲点：开发者可能低估自己隐含的假设（如"谁会不用 bash？"）
- 测试覆盖不足：容易只测试"正确配置"而忽略降级路径
- 路径硬编码：
/Users/username等绝对路径是常见陷阱 - 静默失败：
|| true等模式会掩盖真正问题 - 多账户歧义：未指定账户时，keychain 等工具返回首条字母序匹配而非正确条目
实际效果对比
OAuth 刷新器修复案例显示：
- 修复前：未指定账户 → 读取错误条目 → 无验证 → 使用空数据
- 修复后：显式账户参数 → 数据验证 → 自动尝试常见账户名 → 诊断式错误消息
结果：从"单设备/易崩溃"升级为"通用/生产就绪"。