跨设备开发方法论，通过显式配置、验证优先和自动回退机制，解决”在我机器上能跑”的便携性问题。
说明：
## 核心定位
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 校验），可能流于形式
会员专属
