核心定位
Portable-tools 是一套源于实际调试经验（OAuth 令牌刷新器故障排查，2026-01-23）的跨设备开发方法论，目标是将工具从"单设备可用"提升至"任意环境即插即用"。
核心用法
方法论围绕"三问法则"展开，强制开发者在编码前回答：
1. "什么会在设备间变化？" —— 路径、账户名、服务名、数据结构、环境差异
2. "如何证明它有效？" —— 必须展示 BEFORE/AFTER 的精确数据对比
3. "坏了会怎样？" —— 主动测试错误配置、缺失数据、多条目歧义等场景
四大强制模式需贯穿实现：
- 显式优于隐式：避免模糊匹配（如
security find-generic-password必须指定-a account） - 使用前验证：数据流入必须先校验结构，拒绝"假设有效"
- 回退链机制：配置值 → 常见默认值 → 报错并提示验证命令
- 有用错误：错误消息须包含检查路径、预期格式、验证命令
显著优点
- 实战根源：非理论推导，而是从 OAuth 调试的真实故障（错读 keychain 条目、空值未校验、账户名硬编码）中提炼
- 可度量标准：明确定义"便携"的五条验收标准（跨设备零修改、自动发现差异、优雅失败、自诊断、文档完备）
- 完整工具链：提供预发布检查清单、调试方法论（Patrick 三步法）、反模式速查、多技能集成指南
- 语言无关：虽以 Bash 示例为主，但原则适用于 Python、JS 等任何配置读取场景
潜在局限
- 学习成本：对快速原型开发而言，验证和回退链代码显得冗余
- 未覆盖场景：主要聚焦本地配置/凭证读取，对网络服务差异、容器化环境的处理仅点到为止
- 示例偏向 macOS：
security命令、keychain 等示例对 Linux/Windows 开发者需自行映射 - 无自动化检查：依赖人工执行检查清单，未提供静态分析工具自动识别硬编码
适合人群
- 构建 ClawdHub 技能、开源 CLI 工具的开发者（他人环境不可控）
- 团队内维护共享脚本的 DevOps/SRE（减少"环境差异"工单）
- 从个人脚本向生产级工具升级的场景
常规风险
- 过度工程：简单一次性脚本套用全部模式反而增加维护负担
- 回退链陷阱：默认值过多可能导致静默使用错误账户（如误用 "default" 而非用户指定的 "work"）
- 验证盲区：示例中的
validate_data函数若实现不当（如过于宽松的 JSON 校验），可能流于形式