# 设计文档 (Design)

本文档阐述了 `l-tool` 的核心设计原则和决策。

## 设计原则

### 1. 声明式 CLI 定义

我们使用 `clap` 的 Derive 宏来定义命令行接口。这使得代码既是实现也是文档，保证了参数定义与处理逻辑的一致性。

- **优点**: 减少样板代码，自动生成 Help 信息，类型安全。
- **实践**: 所有的参数结构体都定义在各模块的 `commands.rs` 中，并派生 `Args` 或 `Subcommand` trait。

### 2. 模块化与可扩展性

为了防止 `main.rs` 或 `lib.rs` 变得臃肿，每个顶级命令（如 `js`, `image`）都拥有独立的目录空间。

- **添加新命令的流程**:
  1. 在 `src/commands/` 下创建新目录 (如 `new_feature/`)。
  2. 定义 `mod.rs` 和 `commands.rs`。
  3. 实现具体逻辑。
  4. 在 `src/lib.rs` 的 `Commands` 枚举中注册。

这种设计使得多人协作开发不同功能模块时，冲突最小化。

### 3. 结构化错误处理

我们不使用 `String` 传递错误，也不过度使用 `unwrap()`。

- **库错误**: 使用 `thiserror` 定义具体的错误类型（虽然目前项目初期可能混用了一些 `Box<dyn Error>` 或 `anyhow` 风格，但目标是向结构化迁移）。
- **统一返回**: 所有命令执行函数返回 `crate::types::Result<()>`。

### 4. 异步优先

考虑到部分任务（如网络请求、大量文件 I/O）的性质，核心运行时基于 `tokio`。

- 即使是同步逻辑（如简单的计算），也运行在异步上下文中，以保持一致性。
- 对于 CPU 密集型任务（如图片压缩），应注意不要阻塞异步运行时（必要时使用 `tokio::task::spawn_blocking`）。

### 5. 零配置与智能检测

工具应尽可能“开箱即用”。

- **例子**: `js upgrade` 命令会自动检测当前目录是 npm, yarn 还是 pnpm 项目，无需用户手动指定标志。
- **原则**: 优先推断，提供覆盖选项。
