核心用法
Portable Tools 是一套从 OAuth 刷新器调试经验提炼的跨设备开发方法论，核心目标是让工具在任意设备上无需修改即可运行。
三大前置问题：
1. "设备间什么会变化？" — 路径、账户名、服务名、数据结构、环境变量等
2. "如何证明它有效？" — 要求具体的 BEFORE/AFTER 状态对比，拒绝模糊断言
3. "出问题时怎么办？" — 主动测试错误配置、缺失数据、多入口歧义等失败场景
四大强制模式：
| 模式 | 反例 | 正例 |
|------|------|------|
| 显式优先于隐式 | `security find-generic-password -s Service -w` | 增加 `-a account` 明确指定 |
| 使用前验证 | `USE_VALUE="$DATA"` | `validate_structure "$DATA"` 后再使用 |
| 回退链 | `ACCOUNT="claude"` | 尝试配置值 → 常用值 → 报错并列出已尝试选项 |
| 有用的错误 | `error "No token"` | 包含检查位置、字段路径、验证命令的完整诊断信息 |
显著优点
1. 从单点故障到弹性系统：通过回退链和自动发现，消除硬编码假设导致的单点失效
2. 可调试性优先：错误信息本身就是诊断工具，用户无需询问开发者即可定位问题
3. 经验驱动：源自真实 OAuth 调试场景，每个模式都对应实际踩过的坑
4. 可组合性强：提供与 sprint-plan、隐私检查清单、skill-creator 的集成模板
局限性与风险
1. 实施成本：小型脚本可能显得过度工程，需要权衡便携性收益与开发成本
2. 回退链复杂性：多层回退可能隐藏配置错误，用户意识不到使用了非预期值
3. 验证函数维护：数据结构变化时需同步更新验证逻辑，否则出现假阴性
4. 安全考量：回退链遍历敏感账户名时，可能暴露系统上存在的其他账户信息
适合人群
- 需要发布到公共仓库（如 ClawdHub）供他人使用的工具开发者
- 管理多设备（本地/远程/CI/CD）配置的团队
- 处理密钥链、OAuth、环境变量等系统级集成的脚本编写者
- 厌倦了 "在我机器上能跑" 问题的开发者
常规风险提示
- 隐私泄露：调试输出中的 "有用错误" 可能意外包含敏感路径或账户名，需审查输出内容
- 回退顺序敏感：账户名回退顺序可能影响安全性（如先尝试 "default" 可能匹配到错误的生产凭证）
- 验证绕过：
jq -e等轻量验证可能不足以检测所有结构变异，关键场景需 schema 验证