# 需求分析：目录文件大小统计工具 (dirsize-tool)

## 1. 原始需求

统计指定目录下所有文件的总大小，支持人类可读单位和结构化输出。

## 2. 使用场景

### 场景 A：临时统计（轻量）
- 用户想快速知道某个目录多大
- 预期方案：`du -sh <path>` 即可满足

### 场景 B：开发/测试工具（结构化）
- 用于 @mention 修复测试的验证工具
- 需要可预测的结构化输出供自动化断言
- 需要低副作用（纯读）、快速执行
- 需要作为 Hermes 生态内可调用的工具

## 3. 三种方案对比

| 方案 | 复杂度 | 可读性 | 可扩展性 | 适用场景 |
|------|--------|--------|---------|---------|
| A. `du -sh` | 0（系统自带） | 差（每次敲一串） | 无 | 临时统计 |
| B. Python 脚本 | 低（~30-40行） | 好（规整 CLI） | 高（可加过滤/排序） | 开发/测试工具 |
| C. Hermes MCP 工具 | 中（需注册配置） | 好（通过工具链调用） | 高 | 深度集成 |

**推荐方案：B（Python 脚本）** —— 平衡轻量和可扩展，定位在 `scripts/dirsize.py`

## 4. 边界情况与风险

| 场景 | 影响 | 处理方式 |
|------|------|---------|
| 权限不足的目录/文件 | 统计不完整，抛异常 | 加 `--ignore-permission-denied` 跳过 |
| 符号链接 | 循环链接导致无限遍历 | `follow_symlinks=False`（默认不跟随） |
| 超大目录（百万文件） | `os.walk` 慢但可行 | `os.scandir` 替代可提速；加 `--max-depth` |
| 稀疏文件/空洞文件 | `getsize` 报告 apparent size | 区分 `--apparent-size`(默认) vs `--disk-usage` |
| 命名管道/设备文件 | `getsize` 返回 0 | 只统计 `isfile()` |

## 5. 结论

- 如果是临时需求：`du -sh` 即可，无需开发
- 如果是测试工具：Python 脚本方案最佳，30-40行，配合 `--json` 输出满足自动化断言
- 归属路径待 Carlo 确认（全局 Hermes 工具箱 vs 项目 `scripts/`）