446 lines
18 KiB
Markdown
446 lines
18 KiB
Markdown
# 目录树生成脚本 — 技术方案设计（Windows 平台）
|
||
|
||
> 任务 ID: T023 | 项目 ID: PROJ-20260509011
|
||
> 功能清单: F013-F020（8 个功能，全部审批通过）
|
||
> 运行平台: Windows
|
||
> 设计日期: 2026-05-16
|
||
> 设计者: 脚本架构师
|
||
|
||
---
|
||
|
||
## 1. 技术选型评估
|
||
|
||
### 1.1 功能级可行性分析（BAT vs Python）
|
||
|
||
| 功能编号 | 功能名称 | BAT 可行性 | Python 可行性 | 关键问题 |
|
||
|---------|---------|-----------|--------------|---------|
|
||
| F013 | 接收路径输入 | ✅ 完全可行 | ✅ 完全可行 | BAT: `%~1` 即可；Python: `argparse` |
|
||
| F014 | 加载忽略配置 | ⚠️ 勉强可行 | ✅ 完全可行 | BAT 读取配置文件需逐行 `for /f`，无结构化解析能力 |
|
||
| F015 | 递归遍历目录 | ⚠️ 勉强可行 | ✅ 完全可行 | BAT `for /r` 可递归但无法灵活控制跳过逻辑 |
|
||
| F016 | 生成目录树（├── 字符） | ❌ **不可行** | ✅ 完全可行 | Windows CMD 默认代码页 936 (GBK) 无法正确显示 `├` `─` 等 Unicode 制表符；需 `chcp 65001` 且仍有渲染问题。BAT 字符串拼接缩进极其困难 |
|
||
| F017 | 生成文件树 | ⚠️ 勉强可行 | ✅ 完全可行 | BAT `dir /s/b` 可列出文件，但格式化输出困难 |
|
||
| F018 | 终端输出 | ⚠️ 有条件可行 | ✅ 完全可行 | BAT 需处理 `chcp 65001` 编码切换，输出重定向时易乱码 |
|
||
| F019 | Markdown 保存 | ⚠️ 勉强可行 | ✅ 完全可行 | BAT 可 `echo > file.md`，但 Markdown 结构化内容拼接繁琐 |
|
||
| F020 | 统计信息（目录数/文件数/总大小） | ❌ **困难** | ✅ 完全可行 | BAT 无原生文件大小累加能力，`%%~zI` 在 `for` 循环中可用但累加大文件时易溢出（BAT 整数仅支持 32 位） |
|
||
|
||
### 1.2 BAT 核心缺陷总结
|
||
|
||
1. **Unicode 制表符渲染**：F016 要求输出 `├──` `└──` `│` 等字符，Windows CMD 默认代码页下这些字符会显示为乱码。虽然 `chcp 65001` 可以切换 UTF-8，但在 Windows 10 之前的系统上存在严重兼容性问题，且输出重定向到文件时编码转换不可靠。
|
||
2. **字符串处理**：BAT 的字符串拼接、缩进管理极其笨拙，无法优雅实现树形缩进逻辑。
|
||
3. **大文件统计**：BAT 的整数运算限制在 32 位有符号范围（约 ±21 亿），总大小超过 2GB 时会溢出。
|
||
4. **错误处理**：BAT 缺乏结构化异常处理机制（try/catch），错误恢复困难。
|
||
5. **配置解析**：BAT 无法优雅解析结构化配置文件（JSON/INI），只能逐行文本处理。
|
||
|
||
### 1.3 评估结论
|
||
|
||
**BAT 无法胜任 F016（目录树 Unicode 渲染）和 F020（大文件统计），其余功能也均存在明显缺陷。**
|
||
|
||
---
|
||
|
||
## 2. 技术选型结论
|
||
|
||
### 最终选择：Python 3.8+（标准库，无第三方依赖）
|
||
|
||
**理由：**
|
||
|
||
| 维度 | 说明 |
|
||
|-----|------|
|
||
| 功能覆盖 | 8 个功能全部可完美实现，无妥协 |
|
||
| Unicode 支持 | Python 原生 UTF-8 支持，`├──` 等字符渲染无问题 |
|
||
| 标准库 | `pathlib`、`os`、`argparse`、`datetime` 覆盖所有需求 |
|
||
| 文件大小 | Python 整数自动扩展，无溢出问题 |
|
||
| 跨版本兼容 | Python 3.8+ 覆盖 Windows 7 SP1 及以上所有版本 |
|
||
| 可维护性 | 代码结构清晰，模块化设计，易于扩展 |
|
||
| 部署 | 单文件 `.py`，用户只需安装 Python（Windows 10/11 可通过 Microsoft Store 一键安装） |
|
||
|
||
---
|
||
|
||
## 3. 项目结构
|
||
|
||
```
|
||
tree_generator/
|
||
├── tree_gen.py # 主程序（单文件，包含所有模块）
|
||
├── .treeignore # 忽略配置文件（可选，放在目标目录下）
|
||
├── tree_output.md # 默认输出文件（运行后生成）
|
||
└── README.md # 使用文档（由 Web 文档生成 Agent 创建）
|
||
```
|
||
|
||
**设计原则：**
|
||
- 主程序 `tree_gen.py` 为单文件，不拆分为多模块，便于分发和使用
|
||
- 忽略配置文件 `.treeignore` 放在目标目录下，遵循 `.gitignore` 惯例
|
||
- 输出文件默认在当前工作目录生成
|
||
|
||
---
|
||
|
||
## 4. 模块说明表
|
||
|
||
| 模块名 | 负责功能 | 输入 | 输出 | 依赖 |
|
||
|-------|---------|------|------|------|
|
||
| `ArgParser` | F013 路径输入 | 命令行参数 `sys.argv` | 解析后的配置对象（目标路径、输出路径、深度限制等） | `argparse` 标准库 |
|
||
| `IgnoreLoader` | F014 忽略配置 | 配置文件路径（`.treeignore`） | 忽略目录名称集合 `set[str]` | `pathlib` 标准库 |
|
||
| `DirectoryScanner` | F015 递归遍历 | 目标路径 + 忽略集合 | 目录树结构（嵌套字典） | `pathlib`、`os` 标准库 |
|
||
| `TreeFormatter` | F016 目录树 + F017 文件树 | 目录树结构 | 格式化字符串（含 `├──` 缩进） | 无额外依赖 |
|
||
| `TerminalOutput` | F018 终端输出 | 格式化字符串 | 终端显示（stdout） | `sys` 标准库（编码设置） |
|
||
| `MarkdownWriter` | F019 Markdown 保存 | 格式化字符串 + 输出路径 | `.md` 文件 | `pathlib` 标准库 |
|
||
| `StatisticsCollector` | F020 统计信息 | 目录树结构 | 统计信息字典（目录数、文件数、总大小） | `os` 标准库 |
|
||
|
||
---
|
||
|
||
## 5. 技术选型结论总结
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 最终技术选型：Python 3.8+ 标准库 │
|
||
│ │
|
||
│ 核心文件：tree_gen.py（单文件，约 300-400 行） │
|
||
│ 配置文件：.treeignore（可选） │
|
||
│ 输出文件：tree_output.md（默认） │
|
||
│ │
|
||
│ 选择理由： │
|
||
│ 1. BAT 无法正确处理 Unicode 制表符（F016） │
|
||
│ 2. BAT 整数溢出问题（F020 大文件统计） │
|
||
│ 3. Python 标准库完全覆盖所有 8 个功能 │
|
||
│ 4. 单文件部署，零第三方依赖 │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 错误处理策略
|
||
|
||
### 6.1 异常分类与处理
|
||
|
||
| 异常类型 | 触发条件 | 处理策略 | 用户提示 |
|
||
|---------|---------|---------|---------|
|
||
| `PathNotFoundError` | 目标路径不存在 | 捕获 `FileNotFoundError`，退出并提示 | `错误: 路径 "xxx" 不存在，请检查输入` |
|
||
| `PermissionError` | 无权限访问目录 | 跳过该目录，记录警告，继续遍历 | `警告: 无权限访问 "xxx"，已跳过` |
|
||
| `SymlinkLoopError` | 符号链接循环 | 使用 `pathlib.Path.resolve()` 检测，跳过已访问路径 | `警告: 检测到符号链接循环，已跳过` |
|
||
| `EncodingError` | 文件名含特殊字符 | 使用 `errors='replace'` 容错 | 静默替换，不中断 |
|
||
| `OutputWriteError` | 无法写入输出文件 | 捕获 `IOError`/`PermissionError`，回退到仅终端输出 | `警告: 无法写入文件，仅显示到终端` |
|
||
| `InvalidConfigError` | 忽略配置文件格式错误 | 使用默认忽略列表，记录警告 | `警告: 配置文件格式错误，使用默认配置` |
|
||
|
||
### 6.2 退出码规范
|
||
|
||
| 退出码 | 含义 |
|
||
|-------|------|
|
||
| 0 | 成功完成 |
|
||
| 1 | 参数错误（路径不存在、格式错误） |
|
||
| 2 | 运行时错误（写入失败等） |
|
||
| 3 | 中断（Ctrl+C） |
|
||
|
||
---
|
||
|
||
## 7. 接口定义
|
||
|
||
### 7.1 数据流图
|
||
|
||
```
|
||
┌──────────┐ ┌──────────────┐ ┌─────────────────┐
|
||
│ 命令行参数 │────▶│ ArgParser │────▶│ Config 对象 │
|
||
│ sys.argv │ │ (F013) │ │ {path, output, │
|
||
└──────────┘ └──────────────┘ │ ignore, depth} │
|
||
└────────┬────────┘
|
||
│
|
||
┌───────────────────────────┼───────────────────────────┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│IgnoreLoader │ │Directory │ │Statistics │
|
||
│(F014) │ │Scanner │ │Collector │
|
||
│ │ │(F015) │ │(F020) │
|
||
│.treeignore │ │ │ │ │
|
||
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
||
│ │ │
|
||
▼ ▼ │
|
||
ignore_set tree_dict │
|
||
(set[str]) (嵌套字典) │
|
||
│ │
|
||
▼ │
|
||
┌──────────────────┐ │
|
||
│ TreeFormatter │◀────────────────────┘
|
||
│ (F016/F017) │
|
||
│ │
|
||
│ tree_str │
|
||
│ file_list_str │
|
||
└────────┬────────┘
|
||
│
|
||
┌───────────────────┼───────────────────┐
|
||
▼ ▼ ▼
|
||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||
│ Terminal │ │ Markdown │ │ 统计信息 │
|
||
│ Output │ │ Writer │ │ 输出 │
|
||
│ (F018) │ │ (F019) │ │ │
|
||
│ │ │ │ │ │
|
||
│ stdout │ │ tree_output │ │ 目录/文件/ │
|
||
│ │ │ .md │ │ 总大小 │
|
||
└──────────────┘ └──────────────┘ └──────────────┘
|
||
```
|
||
|
||
### 7.2 核心数据结构
|
||
|
||
```python
|
||
# Config 对象（ArgParser 输出）
|
||
Config = {
|
||
"target_path": Path, # 目标目录路径
|
||
"output_path": Path, # Markdown 输出路径（默认 tree_output.md）
|
||
"ignore_dirs": set[str], # 忽略目录名称集合
|
||
"max_depth": int | None, # 最大递归深度（None = 无限制）
|
||
"files_only": bool, # 仅显示文件模式
|
||
"dirs_only": bool, # 仅显示目录模式
|
||
}
|
||
|
||
# 目录树结构（DirectoryScanner 输出）
|
||
TreeDict = {
|
||
"name": str, # 目录/文件名
|
||
"path": Path, # 完整路径
|
||
"is_dir": bool, # 是否为目录
|
||
"children": list[TreeDict], # 子节点列表（目录时有效）
|
||
"size": int, # 文件大小（文件时有效）
|
||
}
|
||
|
||
# 统计信息（StatisticsCollector 输出）
|
||
Statistics = {
|
||
"dir_count": int, # 目录数量
|
||
"file_count": int, # 文件数量
|
||
"total_size": int, # 总大小（字节）
|
||
"total_size_human": str, # 人类可读大小（如 "1.23 GB"）
|
||
}
|
||
```
|
||
|
||
### 7.3 模块间接口
|
||
|
||
| 调用方 | 被调用方 | 接口方法 | 参数 | 返回值 |
|
||
|-------|---------|---------|------|--------|
|
||
| `main()` | `ArgParser` | `parse_args()` | `sys.argv[1:]` | `Config` |
|
||
| `main()` | `IgnoreLoader` | `load_ignores(config)` | `Config` | `set[str]` |
|
||
| `main()` | `DirectoryScanner` | `scan(path, ignore_set, max_depth)` | `Path, set[str], int\|None` | `TreeDict` |
|
||
| `main()` | `TreeFormatter` | `format_tree(tree, style)` | `TreeDict, str` | `str` |
|
||
| `main()` | `TreeFormatter` | `format_files(tree)` | `TreeDict` | `str` |
|
||
| `main()` | `TerminalOutput` | `output(text)` | `str` | `None` |
|
||
| `main()` | `MarkdownWriter` | `write(text, path)` | `str, Path` | `None` |
|
||
| `main()` | `StatisticsCollector` | `collect(tree)` | `TreeDict` | `Statistics` |
|
||
|
||
---
|
||
|
||
## 8. 忽略配置方案（F014）
|
||
|
||
### 8.1 配置文件格式
|
||
|
||
文件名：`.treeignore`（放在目标目录下）
|
||
|
||
```
|
||
# 忽略配置示例
|
||
# 每行一个目录名，支持 # 注释
|
||
|
||
.git
|
||
.gitignore
|
||
node_modules
|
||
__pycache__
|
||
*.pyc
|
||
.DS_Store
|
||
Thumbs.db
|
||
venv
|
||
.env
|
||
.idea
|
||
.vscode
|
||
dist
|
||
build
|
||
*.egg-info
|
||
```
|
||
|
||
### 8.2 内置默认忽略列表
|
||
|
||
当 `.treeignore` 不存在时，使用以下默认列表：
|
||
|
||
```python
|
||
DEFAULT_IGNORE = {
|
||
".git", ".svn", ".hg", # 版本控制
|
||
"node_modules", "bower_components", # Node.js
|
||
"__pycache__", "*.pyc", ".pytest_cache", # Python
|
||
".idea", ".vscode", # IDE
|
||
"dist", "build", "target", # 构建产物
|
||
".DS_Store", "Thumbs.db", # 系统文件
|
||
"venv", ".venv", "env", # 虚拟环境
|
||
}
|
||
```
|
||
|
||
### 8.3 匹配规则
|
||
|
||
- 目录名精确匹配（不区分大小写，Windows 特性）
|
||
- 支持 `*` 通配符（如 `*.pyc`）
|
||
- 忽略配置仅作用于目录级别，不递归检查文件内容
|
||
|
||
---
|
||
|
||
## 9. 树形输出格式规范（F016/F017）
|
||
|
||
### 9.1 目录树格式
|
||
|
||
```
|
||
项目根目录/
|
||
├── src/
|
||
│ ├── main.py
|
||
│ ├── utils/
|
||
│ │ ├── helper.py
|
||
│ │ └── config.py
|
||
│ └── models/
|
||
│ └── user.py
|
||
├── tests/
|
||
│ ├── test_main.py
|
||
│ └── test_utils.py
|
||
├── config.json
|
||
└── README.md
|
||
```
|
||
|
||
**规则：**
|
||
- 目录名后加 `/` 后缀
|
||
- 分支符：`├── `（有后续兄弟节点）/ `└── `（最后一个节点）
|
||
- 缩进线：`│ `（有后续兄弟节点）/ ` `（无后续兄弟节点）
|
||
- 缩进单位：4 个字符（`│` + 3 空格 或 4 空格）
|
||
|
||
### 9.2 文件树格式
|
||
|
||
```
|
||
文件列表:
|
||
C:\project\src\main.py
|
||
C:\project\src\utils\helper.py
|
||
C:\project\src\utils\config.py
|
||
C:\project\src\models\user.py
|
||
C:\project\tests\test_main.py
|
||
C:\project\tests\test_utils.py
|
||
C:\project\config.json
|
||
C:\project\README.md
|
||
```
|
||
|
||
**规则：**
|
||
- 每个文件一行，带完整绝对路径
|
||
- 使用 Windows 风格路径分隔符 `\`
|
||
- 按字母顺序排序
|
||
|
||
### 9.3 统计信息格式
|
||
|
||
```
|
||
统计信息:
|
||
目录数: 5
|
||
文件数: 8
|
||
总大小: 24.5 KB (25,088 字节)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Markdown 保存方案（F019）
|
||
|
||
### 10.1 输出文件格式
|
||
|
||
```markdown
|
||
# 目录树 — 项目根目录
|
||
|
||
> 生成时间: 2026-05-16 16:00:00
|
||
> 目标路径: C:\project
|
||
> 扫描深度: 无限制
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
项目根目录/
|
||
├── src/
|
||
│ ├── main.py
|
||
│ └── utils/
|
||
│ └── helper.py
|
||
├── config.json
|
||
└── README.md
|
||
```
|
||
|
||
## 文件列表
|
||
|
||
| # | 文件路径 |
|
||
|---|---------|
|
||
| 1 | `C:\project\src\main.py` |
|
||
| 2 | `C:\project\src\utils\helper.py` |
|
||
| 3 | `C:\project\config.json` |
|
||
| 4 | `C:\project\README.md` |
|
||
|
||
## 统计信息
|
||
|
||
- **目录数:** 3
|
||
- **文件数:** 4
|
||
- **总大小:** 1.2 KB (1,234 字节)
|
||
```
|
||
|
||
### 10.2 保存策略
|
||
|
||
- 默认文件名：`tree_output.md`（当前工作目录）
|
||
- 可通过 `-o` / `--output` 参数指定自定义路径
|
||
- 文件已存在时覆盖写入（不追加）
|
||
- 编码：UTF-8 with BOM（Windows 记事本兼容）
|
||
|
||
---
|
||
|
||
## 11. 命令行接口设计
|
||
|
||
```
|
||
usage: tree_gen.py [-h] [-o OUTPUT] [-d DEPTH] [-f] [-D] [-i IGNORE_FILE] [path]
|
||
|
||
目录树生成脚本 - Windows 平台
|
||
|
||
positional arguments:
|
||
path 目标目录路径（默认: 当前目录）
|
||
|
||
options:
|
||
-h, --help 显示帮助信息
|
||
-o OUTPUT, --output OUTPUT
|
||
Markdown 输出文件路径（默认: tree_output.md）
|
||
-d DEPTH, --depth DEPTH
|
||
最大递归深度（默认: 无限制）
|
||
-f, --files-only 仅显示文件树
|
||
-D, --dirs-only 仅显示目录树
|
||
-i IGNORE_FILE, --ignore IGNORE_FILE
|
||
忽略配置文件路径（默认: 目标目录下的 .treeignore）
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
```bash
|
||
# 扫描当前目录
|
||
python tree_gen.py
|
||
|
||
# 扫描指定目录
|
||
python tree_gen.py C:\Users\test\project
|
||
|
||
# 指定输出文件和深度
|
||
python tree_gen.py C:\project -o output.md -d 3
|
||
|
||
# 仅显示文件
|
||
python tree_gen.py C:\project -f
|
||
|
||
# 自定义忽略配置
|
||
python tree_gen.py C:\project -i my_ignore.txt
|
||
```
|
||
|
||
---
|
||
|
||
## 12. 编码规范
|
||
|
||
| 项目 | 规范 |
|
||
|-----|------|
|
||
| 文件编码 | UTF-8（Python 源文件） |
|
||
| 输出编码 | UTF-8 with BOM（Markdown 文件） |
|
||
| 终端编码 | UTF-8（通过 `sys.stdout.reconfigure(encoding='utf-8')` 设置） |
|
||
| 行尾符 | LF（Python 标准） |
|
||
| 缩进 | 4 空格 |
|
||
| Python 版本 | 3.8+ |
|
||
|
||
---
|
||
|
||
## 13. 后续任务
|
||
|
||
| 任务 | 负责 Agent | 状态 |
|
||
|-----|-----------|------|
|
||
| T021: Python 代码实现 | BAT 编码 Agent（实际应为 Python 编码 Agent） | 待激活 |
|
||
| T022: 功能测试验证 | 测试验证 Agent | 待激活 |
|
||
| T024: 使用文档编写 | Web 文档生成 Agent | 待激活 |
|
||
|
||
---
|
||
|
||
*文档结束。等待审批后进入编码阶段。*
|