00 · 方法与版本口径

先确定证据边界，再讨论架构。这一章说明本文如何从入口、状态与副作用三个方向拆解 Mole。

固定版本，而不是追逐 main

本文分析本地 Mole-main 快照，并将它与上游 tw93/Mole 校验：目录内容与提交 c349e3ae86f6a8711f774ecb954e4c22374971e2 一致，入口脚本版本为 1.48.1。所有源码链接都锁定到这个提交。

项目	口径
上游仓库	tw93/Mole
固定提交	c349e3ae86f6a8711f774ecb954e4c22374971e2
工具版本	1.48.1
主要语言	Bash + Go
运行平台	macOS

每章使用同一套拆解框架

参考 dg-ai-notes 的组织方法，每章都尽量回答：

1. 是什么：模块的产品职责与输入输出。
2. 怎么做：入口、调用链、状态变化、并发与缓存。
3. 为什么：安全边界、兼容性约束和取舍。
4. 在哪里：章末给出固定提交下的关键源码索引。

本文尤其区分三类代码：

• 发现器：扫描候选文件或采集指标，允许保守地漏报。
• 策略层：结合保护表、白名单、运行状态决定能否继续。
• 副作用汇点：真正调用 rm、sudo、Trash、mv 或系统服务的位置，必须再次验证。

一条主线贯穿全书

用户意图
   │
   ▼
`mole` 路由器 ──► `bin/*.sh` / Go 二进制
   │                    │
   │              发现候选、计算大小、交互选择
   │                    │
   └────────────► 策略与保护层
                        │
                        ▼
                `mole_delete` / Go Trash
                        │
                        ▼
                  日志、缓存失效、结果汇总

这条线能避免一种常见误读：看到上层做过路径判断，就以为删除安全。真正重要的是危险动作发生前是否仍然拥有完整上下文并再次检查。

如何阅读

• 想快速理解项目：读 01、02、03、15。
• 做 Shell 安全工具：重点读 04、05、06、07、08。
• 做终端交互与系统监控：重点读 11、12。
• 研究供应链与 CI：读 13、14。
• 准备贡献代码：最后使用 16 的按任务阅读路线。

术语约定

文中的“Trash”表示可恢复的移入废纸篓语义；“永久删除”表示不可恢复的删除。“保护”不是简单黑名单，而是路径结构、应用身份、系统状态、权限归属和用户白名单共同构成的决策。

关键源码索引

• mole：命令总入口与版本声明。
• AGENTS.md：项目结构与安全约束。
• Makefile：Shell 与 Go 产物的构建关系。

下一章先不看实现，先回答：Mole 到底把哪些问题视为自己的产品边界？