fileglide 项目设计

1. 任务定约

这一节把“我想要一个很强大的文件 CLI”翻译成可执行、可验证的工程目标，避免后续实现一开始就因为边界不清而膨胀。

2. 设计原则

3. 能力范围与能力矩阵

用户需求中的 1.x 与 2.x 能力，工程上可以整理成六类能力域。每一类都要有明确的数据输入、范围控制和输出结构。

4. CLI 命令面设计

命令面建议沿用 OpenTrade 的 root command + group + leaf command 组织方式。这样可读、可测试，也便于后续自动生成命令目录与 agent 文档。

4.1 顶层命令树

fileglide
|-- file
|   |-- create
|   |-- delete
|   |-- read
|   |-- lines
|   |-- write
|   |-- append
|   |-- insert
|   |-- patch
|   |-- list
|   |-- search
|   `-- stat
|-- path
|   |-- create
|   |-- delete
|   |-- list
|   |-- search
|   `-- stat
|-- tree
|   |-- scan
|   |-- summary
|   `-- size
|-- text
|   |-- grep
|   |-- extract
|   `-- replace-preview
|-- inspect
|   |-- encoding
|   |-- newline
|   `-- bom
`-- batch
    |-- run-plan
    `-- apply-plan

4.2 顶层设计理由

4.3 统一运行时参数

5. 架构分层

fileglide 的核心不是“命令很多”，而是“层次清楚”。只有分层清楚，后续能力扩展才不会让 CLI、编码探测、文本编辑和搜索逻辑相互污染。

CLI Entry
  -> App Assembly
    -> Command Builders
      -> Executor
        -> Facade
          -> Domain Services
             - TraversalService
             - SearchService
             - EncodingService
             - TextReadService
             - TextEditService
             - StatService
          -> Filesystem Gateway
          -> Renderers

5.7 关键模式落点

6. 核心数据模型

若没有统一的记录模型，遍历、搜索和编辑的结果就无法复用。AI agent 场景下尤其需要结构化对象而非一堆随意拼装的字典。

EntryRecord
- path: str
- kind: file | directory | symlink | other
- name: str
- relative_path: str
- size_bytes: int | null
- exists: bool
- encoding: str | null
- newline: lf | crlf | cr | mixed | null
- bom: utf8-bom | utf16-le | utf16-be | none | unknown
- modified_at: str | null

TextSlice
- path: str
- encoding_used: str
- line_start: int | null
- line_end: int | null
- char_start: int | null
- char_end: int | null
- byte_start: int | null
- byte_end: int | null
- text: str
- newline: str | null

SearchHit
- path: str
- hit_type: filename | pathname | content
- score: float | null
- matcher: exact | regex | levenshtein | contains
- line_number: int | null
- column_start: int | null
- column_end: int | null
- preview: str | null

EditPlan
- operation: overwrite | append | insert | replace-lines | replace-range
- target_path: str
- expected_version: str | null
- backup: bool
- payload: ...

EditResult
- changed: bool
- bytes_before: int
- bytes_after: int
- diff_preview: str | null
- encoding_kept: bool
- newline_kept: bool

7. 编码与文本策略

这是 fileglide 区别于普通文件工具的关键部分。用户明确要求“UTF-8 without BOM 完美适配，以及其他所有常见编码完美适配”。工程上不能写成空话，必须给出明确的解码、保真、写回和失败策略。

7.1 编码处理原则

• 默认写回目标： 新建文本文件默认写为 utf-8 无 BOM。
• 读取优先级： 先显式参数，再 BOM 判断，再已知编码候选，再启发式探测，再保底替换读取。
• 写回优先级： 默认保留原编码、原 BOM、原换行风格；除非用户显式要求规范化。
• 错误策略： 区分“无法探测编码”“可读取但存在替换字符”“写回将丢失字符”。
• 文本与字节双轨： 所有精确编辑命令既要理解文本位置，也要在必要时能报告字节偏移。

7.2 推荐支持的编码层次

7.3 编码服务职责

8. 检索与匹配设计

8.1 文件名 / 路径名检索

文件名与路径名检索分为四种模式：exact、contains、glob、fuzzy。其中 fuzzy 必须基于 vortezwohl.nlp.LevenshteinDistance 实现，这是用户明确要求，不应替换成自定义低质量近似算法。

fuzzy 搜索建议流程
1. 遍历候选文件名或相对路径
2. 先做大小写归一化与 Unicode 规范化
3. 使用 LevenshteinDistance.rank() 进行排序
4. 结合 exact / prefix / contains 结果做分层加权
5. 输出 score、distance、matched_part 和排序原因

8.2 文件内容检索

内容检索建议采用“遍历层 + 文本解码层 + 匹配层”三段式设计。匹配层应支持普通子串、正则表达式、大小写控制、上下文窗口和行号输出。

8.3 大目录搜索性能策略

• 遍历层先过滤文件类型和路径模式，避免无意义打开大量文件。
• 读取层支持采样与大小阈值，避免超大文件拖垮全局搜索。
• 可选引入线程池并发读取，但必须保留输出顺序或显式排序回放。
• 若后续用到并发，可优先复用 vortezwohl.concurrent.ThreadPool，而不是自写松散线程控制。

9. 精确编辑设计

文件编辑是最容易把“工具做强”变成“工具做危险”的部分。设计上要把不同编辑语义拆开，而不是用一个 write 命令包打天下。

9.1 编辑能力拆分

9.2 编辑执行骨架

1. 读取原始字节
2. 探测编码、BOM、换行风格
3. 解码为文本，并记录文本与字节映射
4. 定位目标区间（按行/按字符/按锚点/按正则）
5. 生成变更计划与 diff 预览
6. 校验是否满足预期前置条件
7. 按原编码或目标编码写回
8. 重新读取并做最小验证

9.3 定位方式设计

9.4 并发与防误改控制

• 编辑命令建议支持 --expect-hash 或 --expect-mtime，防止文件被外部修改后误覆盖。
• 高风险编辑默认支持 --backup 与 --dry-run。
• 返回结果要明确说明是否保留原编码、原 BOM、原换行风格。

10. 安全、错误模型与一致性策略

10.1 错误模型

fileglide 不应只输出“失败了”。应建立结构化错误类型，例如：PathNotFound、EncodingDetectFailed、UnsafeDeleteDenied、AnchorNotFound、MultipleAnchorsMatched、TextNotEncodable、BinaryFileSkipped。

10.2 删除类操作原则

• 默认拒绝明显危险的根路径、工作区根路径或过宽范围递归删除，除非显式传入强确认参数。
• 删除前返回命中数量与路径预览，支持 --dry-run。
• 对递归删除建议区分“空目录删除”和“强制删除子树”。

10.3 二进制文件处理

• 默认识别并标记二进制文件，不把二进制误当文本。
• 内容搜索默认跳过二进制，除非用户显式要求按字节搜索。
• 文本编辑命令若发现目标疑似二进制，应直接拒绝并提示原因。

10.4 一致性策略

11. 测试与验证设计

这个项目如果没有系统性的文件测试，很容易在“看起来能用”的阶段埋下大量跨平台与编码坑。测试应被当成主线，不是收尾动作。

11.1 测试分层

11.2 必测样本集

11.3 验收标准建议

• 关键命令具备稳定 JSON 输出结构。
• 核心编码样本的读取和原样写回回归通过。
• Levenshtein 模糊检索排序对固定样本保持确定性。
• 精确编辑在至少三种编码与两种换行风格下通过。

12. 分阶段实施路线

阶段 A：最小闭环

• 搭建 CLI 骨架、命令树、标准输出结构。
• 实现文件/路径创建删除、基础 list、基础 read/write、UTF-8 优先编码处理。
• 完成最小 CLI 测试与编码样本测试。

阶段 B：搜索与尺寸能力

• 实现文件名/路径名搜索。
• 引入 vortezwohl Levenshtein 排序。
• 实现内容正则搜索、目录大小聚合。

阶段 C：精确编辑能力

• 实现按行读取、按行替换、区间读取、区间替换。
• 实现中部插入与锚点型编辑。
• 补齐预演与并发防误写保护。

阶段 D：Agent 强化层

• 批量计划执行、变更预览、结构化 diff 返回。
• 输出摘要与上下文裁剪策略。
• 更丰富的 inspect / diagnostics 命令。

13. 建议目录结构

fileglide/
|-- pyproject.toml
|-- README.md
|-- docs/
|   `-- fileglide-architecture.html
|-- fileglide/
|   |-- __init__.py
|   |-- __main__.py
|   |-- main.py
|   |-- app.py
|   |-- executor.py
|   |-- facade.py
|   |-- models.py
|   |-- errors.py
|   |-- rendering.py
|   |-- commands/
|   |   |-- __init__.py
|   |   |-- root.py
|   |   |-- file_commands.py
|   |   |-- path_commands.py
|   |   |-- tree_commands.py
|   |   |-- text_commands.py
|   |   `-- inspect_commands.py
|   |-- services/
|   |   |-- __init__.py
|   |   |-- traversal_service.py
|   |   |-- search_service.py
|   |   |-- stat_service.py
|   |   |-- text_read_service.py
|   |   |-- text_edit_service.py
|   |   `-- encoding_service.py
|   |-- matchers/
|   |   |-- __init__.py
|   |   |-- name_matcher.py
|   |   `-- regex_matcher.py
|   |-- filesystem/
|   |   |-- __init__.py
|   |   |-- gateway.py
|   |   `-- safety.py
|   `-- util/
|       |-- __init__.py
|       |-- path_utils.py
|       `-- text_utils.py
`-- tests/
    |-- cli/
    |-- services/
    |-- fixtures/
    |   |-- encodings/
    |   `-- trees/
    `-- regression/

14. 未决问题与后续决策点

建议的下一步实现切片

1. 先搭 CLI 基础骨架与目录结构。
2. 实现 file read、file write、path list、file search 的最小闭环。
3. 补充编码探测与保真写回测试。
4. 再进入精确行编辑与模糊匹配排序。