Mole 贡献者实战指南：Bash 3.2 兼容规范、安全删除封装与 Go TUI 构建全流程

本文以 Mole 仓库的 CONTRIBUTING.md 为骨架，系统梳理向该项目贡献代码的完整工程流程：开发环境搭建、check.sh/test.sh 质量门禁的内部机制、Bash 3.2 兼容代码风格与 set -euo pipefail 安全写法、lib/core/file_ops.sh 中安全删除封装的设计意图，以及 Go 编写的 mo analyze / mo status TUI 组件的构建与验证方法。读完后，你可以按照仓库约定完成一次能通过 CI 的 Shell 或 Go 代码提交。

环境搭建：三行命令建立受约束的开发环境

Mole 的 CONTRIBUTING.md 给出的 Setup 流程极其精简，全部贡献者工具都通过 Homebrew 与 Go 生态安装：

# Install development tools
brew install shfmt shellcheck bats-core golangci-lint

# Install goimports for better Go formatting
go install golang.org/x/tools/cmd/goimports@latest

# Install pre-commit hook (runs format/lint checks on every commit)
git config core.hooksPath .githooks

这三步在仓库中都有对应的实体文件支撑：

• shfmt、shellcheck、golangci-lint 分别被 scripts/check.sh 的三个检查阶段消费：shfmt -i 4 -ci -sr 负责 Shell 格式化（4 空格缩进、紧凑 if、简化冗余逻辑），shellcheck 按 .shellcheckrc 配置检查 mole、install.sh、bin/*.sh、lib/*/*.sh、scripts/*.sh，golangci-lint run ./... 负责 Go 静态检查。
• .shellcheckrc 是一份值得注意的配置：它禁用了 SC2155（声明与赋值分离）、SC2034（未使用变量）、SC2059（printf 格式串变量）、SC1091（不追踪 source 文件）、SC2038（要求 find -print0 | xargs -0 写法）。贡献代码时，理解这些被豁免的警告意味着项目在这些维度上有自己的约定，不应被 lint 噪音干扰。
• .editorconfig 从编辑器层面固化了代码风格：Shell 文件 indent_style = space、indent_size = 4、UTF-8、LF 换行、结尾保留换行、修剪行尾空白——这正是 CONTRIBUTING.md 中 "4 spaces indent" 规则的机器化表达。
• .githooks 目录在仓库中真实存在，内含可执行的 pre-commit 钩子。git config core.hooksPath .githooks 让每次 commit 自动运行格式化与 lint 检查，相当于把 scripts/check.sh 的纪律前置到了提交环节。

质量门禁脚本的内部机制

CONTRIBUTING.md 要求提交前运行：

./scripts/check.sh    # 质量检查（自动格式化代码）
./scripts/test.sh     # 运行测试

阅读 scripts/check.sh 源码可以确认它并非简单包装，而是一条六段式流水线（--format 模式只做格式化，--no-format 只做检查）：

1. 格式化阶段：shfmt -i 4 -ci -sr -w 处理所有 *.sh 与入口脚本 mole；Go 侧优先使用 goimports -w -local github.com/tw93/mole ./cmd ./internal（按模块名分组导入），未安装 goimports 时回退 gofmt -w。
2. Go lint：先 golangci-lint config verify 验证配置合法性，再 golangci-lint run ./...；若未安装 golangci-lint，降级为 go vet ./...。脚本还内置了排障提示：当 lint 报错指向已删除的临时 worktree 或不存在的路径时，提示执行 golangci-lint cache clean。
3. ShellCheck：按 .shellcheckrc 检查核心 Shell 文件集合。
4. 语法检查：对 mole、install.sh、bin/*.sh、scripts/*.sh 及 lib 下所有 .sh 逐一执行 bash -n。
5. 函数重复审计：调用 scripts/audit_function_duplication.py 对归一化后的 Shell 函数体做哈希分组，拦截"改名不改体"的复制粘贴代码（--list 可查看全部分组）。这一步以 python3 为硬依赖——check.sh 明确注释了原因：测试套件中已有六个 Bats 文件依赖它。
6. 诊断指引安全门禁：用 awk 扫描 AGENTS.md、README 等文档，禁止出现"下载诊断脚本后直接管道进 shell"的引导写法。

scripts/test.sh 则是测试编排器，其工程细节直接体现了 Mole "安全优先"的项目性格：

• 脚本开头 export MOLE_TEST_NO_AUTH=1，并在临时目录生成 sudo/osascript/launchctl 的阻断桩——任何测试若试图触发真实提权或 AppleScript 都会被拦截报错，保证验证流程绝不阻塞在系统授权弹窗上。
• Bats 用例支持跨文件并行（--jobs，默认上限 6 个 job），且 --no-parallelize-within-files 保证单个测试文件内串行，因为同一文件共享 setup_file 设置的 $HOME；含墙钟断言的 core_performance.bats、regression.bats 会被拆出到并行批次之后顺序执行，避免 CPU 争用干扰计时。
• 非 macOS 平台会跳过安装测试；CI 环境下还强制要求存在 timeout/gtimeout 二进制。

Makefile 对上述脚本提供了目标封装：make build（本地架构构建 TUI 二进制到 bin/）、make check（= check.sh --no-format）、make format、make test（= MOLE_TEST_NO_AUTH=1 ./scripts/test.sh）、make test-go、make verify（check + Go 测试）。其中 release-amd64/release-arm64 目标刻意保持纯 Go 交叉编译（CGO_ENABLED=0），注释说明原因：避免发布机器的 macOS SDK 通过 cgo 抬高 Mach-O 最低系统版本。

Bash 代码风格：为 macOS 默认 Bash 3.2 写的规范

CONTRIBUTING.md 的 Basic Rules 是整个 Shell 代码库的风格契约，逐条继承如下：

规则	说明
Bash 3.2+ 兼容	必须兼容 macOS 自带的 Bash 3.2，不能使用更新的 Bash 特性
4 空格缩进	与 .editorconfig 中 [*.{sh,bash}] 配置一致，由 shfmt -i 4 强制执行
全部脚本使用 set -euo pipefail	出错即退出、未定义变量报错、管道中任一段失败即失败
所有变量加引号	"$variable"，防止词法拆分与 glob 展开
测试用 [[ ]] 不用 [ ]	复合条件测试使用 [[ ]]
函数变量用 local，常量用 readonly	约束作用域与可变性
函数名 snake_case	统一命名风格
使用 BSD 命令而非 GNU	例如 stat -f%z 而非 stat --format

其中两条规则的动机可以直接从仓库现状得到印证。"Bash 3.2 兼容"不是纸面要求：tests/uninstall_scan_bash32.bats 专门存在用于验证扫描逻辑在 Bash 3.2 语义下的行为；"BSD 命令"则源于运行环境——Mole 的目标平台是 macOS，stat、find 等工具都是 BSD 版本。

安全文件操作：为什么禁止直接 rm -rf

CONTRIBUTING.md 强调：必须使用安全封装，永远不直接 rm -rf，并给出三个示例：

# Single file/directory
safe_remove "/path/to/file"

# Purge files older than 7 days
safe_find_delete "$dir" "*.log" 7 "f"

# With sudo
safe_sudo_remove "/Library/Caches/com.example"

这些封装全部实现在 lib/core/file_ops.sh 中，从源码位置看各自承担不同职责：safe_remove 处理常规删除，safe_sudo_remove 处理特权删除，safe_find_delete 处理按模式与天龄的批量清理，而 mole_delete 是统一的"删除漏斗"——用户可见的清理动作应优先走它，因为回收站路由（Trash routing）、操作日志、dry-run 行为和路径保护都在同一个地方保持一致。这正是 Mole 作为清理工具的核心纪律：删除路径只有一条，保护逻辑不会被旁路。

配套约束在 AGENTS.md 的安全规则中进一步收紧：裸的 rm -rf / find -delete 仅允许出现在带 # SAFE: <一句话理由> 同行注释的位置，这是 docs/SECURITY_DESIGN.md 定义的路径校验/应用保护契约。贡献者在写任何删除逻辑前，应先查看 should_protect_path() 与应用保护辅助函数，确认目标路径不在 /System、/Library/Apple、com.apple.* 等受保护范围内。

Pipefail 安全：set -euo pipefail 下的三个惯用法

在 set -e -o pipefail 环境中，很多"看起来无害"的写法会直接中止脚本。CONTRIBUTING.md 给出的三个正确姿势值得原样保留：

# Correct: handle failure
find /nonexistent -name "*.cache" 2>/dev/null || true

# Correct: check array before use
if [[ ${#array[@]} -gt 0 ]]; then
    for item in "${array[@]}"; do
        process "$item"
    done
fi

# Correct: arithmetic operations
((count++)) || true

三条规则各对应一类经典陷阱：

• || true 兜底"目标不存在"类命令。在 macOS 上清理不存在的缓存目录是常态，find 返回非零不应终止整个清理流程。
• 数组先判空再遍历——这条尤其针对 Bash 3.2：在 set -u 下展开空数组 "${array[@]}" 会报未绑定变量错误，${#array[@]} 预判空是 Bash 3.2 时代的必要写法（对照 scripts/test.sh 中 bats_opts=() 初始化后再判断长度的写法）。
• 算术自增需要 || true：((count++)) 在 count 为 0 时表达式值为 0，即返回退出码 1，set -e 会把"计数成功"误判为"命令失败"而中断脚本。这是 set -e + 算术运算最著名的反直觉点。

错误处理模式：超时与能力探测

CONTRIBUTING.md 还给出两段错误处理范式：

# Network requests with timeout
result=$(curl -fsSL --connect-timeout 2 --max-time 3 "$url" 2>/dev/null || echo "")

# Command existence check
if ! command -v brew >/dev/null 2>&1; then
    log_warning "Homebrew not installed"
    return 0
fi

网络请求要求显式超时且失败时产出空串而非中断；可选依赖（如 Homebrew）则先做 command -v 探测，缺失时告警并优雅返回。这两段代码与 scripts/check.sh 中对每个工具先 command -v 探测再降级（golangci-lint 缺失回退 go vet、goimports 缺失回退 gofmt）的策略如出一辙：Mole 自身对可选能力的一贯态度是"探测—降级—告警"，而非硬失败。

UI 与日志：统一使用 log 函数族

CONTRIBUTING.md 规定的日志四件套：

# Logging
log_info "Starting cleanup"
log_success "Cache cleaned"
log_warning "Some files skipped"
log_error "Operation failed"

# Spinners
with_spinner "Cleaning cache" rm -rf "$cache_dir"

# Or inline
start_inline_spinner "Processing..."
# ... work ...
stop_inline_spinner "Complete"

这四个函数真实定义在 lib/core/log.sh 中：log_info、log_success、log_warning、log_error。贡献新模块时，输出应全部走这套函数族而不是裸 echo，以保证颜色、图标与 scripts/check.sh 中 NO_COLOR 语义（尊重 no-color.org 约定，非空 NO_COLOR 即禁用 ANSI 转义）等细节的一致性。

Debug 模式：--debug 与 MO_DEBUG

CONTRIBUTING.md 说明调试输出的启用方式与模块侧约定：

mo --debug clean
./bin/clean.sh --debug

模块检查内部 MO_DEBUG 变量：

if [[ "${MO_DEBUG:-0}" == "1" ]]; then
    echo "[MODULE] Debug message" >&2
fi

格式为 [MODULE_NAME] message 且一律输出到 stderr。在仓库中可以验证这条链路：bin/clean.sh、bin/purge.sh、bin/optimize.sh、bin/installer.sh 等入口在解析 --debug 后统一 export MO_DEBUG=1；而 bin/clean.sh 中还能看到 MO_DEBUG 与终端渲染的交互——开启 debug 时会暂停扫描反馈动画，保证调试行独占一行输出。这解释了为什么 debug 输出必须走 stderr 且带模块前缀：它要与 spinner、彩色 UI 等前台渲染逻辑安全共存。

运行环境要求

CONTRIBUTING.md 列出的 Requirements 原文如下，全部保留：

• macOS 10.14 或更新版本，支持 Intel 与 Apple Silicon
• macOS 默认 Bash 3.2+，清理任务需要管理员权限
• 通过 xcode-select --install 安装 Command Line Tools，以获得 curl、tar 等基础工具
• 本地构建 mo status 或 mo analyze TUI 二进制需要 Go 1.24+

其中 Go 版本要求可以结合当前仓库状态精确化：CONTRIBUTING.md 给出的下限是 Go 1.24+，而当前 go.mod 声明的是 go 1.25.0——实际本地构建请以 go.mod 的声明版本为准。依赖面很小：go.mod 的直接依赖只有 bubbletea（TUI 框架）、lipgloss（样式）、gopsutil（系统指标采集）、xxhash 与 golang.org/x/sys，make mod-download 内置了三次重试以缓解模块代理的瞬时网络错误。

Go 组件：Bubble Tea TUI 的组织与验证

mo status 与 mo analyze 两个交互式仪表盘用 Go + Bubble Tea 实现，对应 cmd/analyze/ 与 cmd/status/ 两个包。CONTRIBUTING.md 的 Go 章节包含四部分约定：

代码组织。 文档要求"每个模块按职责拆分为聚焦的文件"，并以 cmd/analyze/ 单文件 500 行上限、cmd/status/ 指标按领域拆分（11 个 metrics 文件）为例。对照当前仓库：cmd/status/ 中确实存在 metrics.go、metrics_cpu.go、metrics_memory.go、metrics_disk.go、metrics_network.go、metrics_gpu.go、metrics_battery.go、metrics_bluetooth.go、metrics_hardware.go、metrics_health.go、metrics_process.go 等按领域划分的指标文件，与该描述吻合；而 cmd/analyze/ 目前已进一步细分为 scanner.go、cache.go、heap.go、snapshots.go、insights.go、live_scan.go 等更聚焦的文件，体现了"单一职责、持续拆分"的约定。从源码结构看，main.go 只做引导（参数解析、main()、辅助函数），model.go 承载类型定义与访问器，update.go 持有 Bubble Tea 的 Update 消息链——新按键绑定、消息类型、导航行为应落在 update.go。

开发工作流。 三个标准动作：

gofmt -w ./cmd/...    # 格式化
go vet ./cmd/...      # 静态检查
go build ./...        # 验证全部包可编译

构建二进制。 本地开发：

# Build binaries for current architecture
make build

# Or run directly without building
go run ./cmd/analyze
go run ./cmd/status

make build 实际执行 go build -ldflags="-s -w" -o bin/analyze-go ./cmd/analyze 及 status 对应命令（见 Makefile），-s -w 去除调试符号与 DWARF 信息以缩小产物；发布场景则由 CI 按架构自动构建，本地贡献者无需手工交叉编译。

编码准则。 四条 Go 侧约定：文件保持单一职责；提取常量替代魔法数字；对外部命令使用 context 控制超时；注释解释"为什么"而不只是"做什么"。其中"context 控制超时"与前文 Shell 侧的 curl --connect-timeout --max-time 要求是同一条安全原则在两种语言中的映射——任何可能阻塞的 I/O 都必须有界。

Pull Request 流程与 CI 校验

CONTRIBUTING.md 定义的 PR 流程共五步：

1. Fork 并从 main 创建分支
2. 完成修改
3. 运行检查：./scripts/check.sh
4. 提交并推送
5. 向 main 发起 PR

"CI will verify formatting, linting, and tests" 这句承诺在仓库中有完整对应：.github/workflows/ 下存在 check.yml（格式与 lint）、test.yml（测试，并强制 # SAFE 注释契约）、codeql.yml（安全审计）、bundle_audit.yml（每月 bundle 漂移审计）等流水线。

结合前文的门禁机制，一次合格的 Mole 贡献提交应当满足：Shell 侧通过 shfmt/shellcheck/bash -n/函数重复审计四重检查，删除逻辑全部走 lib/core/file_ops.sh 的安全封装并对特权路径先过保护检查，Go 侧通过 golangci-lint 与 go test ./...，测试验证使用 MOLE_TEST_NO_AUTH=1 且 dry-run（MOLE_DRY_RUN=1）先行。把这条纪律内化后，本地 ./scripts/check.sh 与 ./scripts/test.sh 双绿，即是 CI 通过的可靠前置信号。