• 网络安全
• 应用安全
• 密码学
• CLI

本文是 HackBrowserData 开源仓库的官方贡献指南解读与实践手册，核心围绕CONTRIBUTING.md展开，并结合仓库中的 CI 流水线、构建脚本与源码实现，系统讲解"如何安全地参与 HackBrowserData 的贡献"。读完本文，你将掌握该项目的分支与 Issue 协作规范、Go 版本兼容红线（Go 1.20 + Windows 7）、完整的本地开发验证命令链（构建/测试/静态检查/格式化/拼写检查）、Pull Request 与提交信息规范，以及平台相关代码的 build tag 组织方式，可以直接上手提交第一个高质量 PR。

一、贡献流程总览：从main分支到 Issue-First 协作

HackBrowserData 是一个用 Go 编写的浏览器数据解密导出工具，支持 Chromium 系浏览器与 Firefox，并可在 macOS、Windows、Linux 上运行。参与贡献前，请先阅读仓库根目录的README.md了解项目全貌，而CONTRIBUTING.md则是贡献者必须遵守的行为准则。

贡献流程有两条硬性要求：

1. 始终基于main分支开展开发。所有功能分支、修复分支都应从main检出，保证你的工作基于最新的主干代码，避免合并冲突与历史分叉。
2. Pull Request 必须对应 Issue。在创建 PR 之前，请先确认你的改动是否已有关联 Issue；如果没有，请先创建一个 Issue 说明问题或需求，再围绕它开展编码。这一"先讨论、后编码"的流程能避免重复劳动，也让维护者与社区能够提前对齐方向。

从仓库的 CI 配置看，main分支同时承载着测试与发布两条流水线（详见.github/workflows/test.yml与.github/workflows/release.yml），因此任何未经讨论就向main提交的改动都会直接触发全平台验证与潜在发布流程，Issue-First 的必要性由此体现。

二、Go 版本约束：Go 1.20 红线与 Windows 7 兼容

这是本项目贡献规范中最重要的一条技术红线：

项目必须使用 Go 1.20 构建，以维持对 Windows 7 的支持。该约束由 CI 强制执行。

具体而言，贡献者需要注意以下三点：

1. 禁用 Go 1.21+ 的新特性：例如log/slog、slices、maps、cmp等标准库包，一律不得使用。
2. 不得提升go.mod中的go指令版本：即go.mod中的go指令必须保持go 1.20，不得升级。
3. 依赖版本锁定：modernc.org/sqlite被固定锁定在v1.31.1，因为v1.32+版本开始要求 Go 1.21。这是一个纯 Go 的 SQLite 实现，被项目用于读取浏览器数据库文件（如历史记录、Cookie 存储），它的升级必须与 Go 版本约束同步评估。

这些约束在仓库中都有明确证据。查看go.mod可确认go 1.20指令与modernc.org/sqlite v1.31.1的锁定版本。更关键的是，CI 流水线对该约束进行了硬性校验：在.github/workflows/lint.yml中，CI 会直接解析go.mod中的go指令并与1.20比对，不一致即报错并退出：

GO_VERSION=$(grep '^go ' go.mod | awk '{print $2}') if [ "$GO_VERSION" != "1.20" ]; then echo "::error::go.mod directive must remain 'go 1.20' (Windows 7 support requirement)" exit 1 fi

同样，.golangci.yml 中run.go: "1.20"的设置也明确标注"Compatible with Go 1.20"，并附带了原因说明：copyloopvar、intrange、modernize、perfsprint等检查器依赖 Go 1.22+，需在版本约束解除后才能启用。这意味着：

• 你的代码不应使用任何需要 Go 1.21+ 才能编译或通过检查的语法与 API；
• 本地开发时建议直接使用 Go 1.20 工具链进行验证，避免"本地能过、CI 必挂"的尴尬；
• 若确有引入新依赖的需求，务必检查该依赖及其传递依赖对 Go 版本的最低要求，modernc.org/sqlite正是这样一个先例。

这一约束背后的业务动机是 Windows 7 兼容性：HackBrowserData 作为跨平台工具，Windows 构建路径（见Makefile中的build-windows目标）必须覆盖仍在使用 Windows 7 的用户场景，而 Go 1.21 起官方不再支持 Windows 7 作为目标系统。理解了这一层因果，你在审查依赖与语法时就会更有判断力。

三、本地开发命令链：构建、测试、静态检查、格式化与拼写检查

CONTRIBUTING.md 给出了完整的本地开发命令集，下面逐条结合仓库实现进行解读，保证你可以直接复制运行。

3.1 构建

go build ./cmd/hack-browser-data/

入口位于 cmd/hack-browser-data/main.go，基于 cobra 命令框架组织。构建产物为hack-browser-data可执行文件，默认（无子命令）即执行dump行为。除了这条命令，仓库还提供了更便捷的构建入口：在仓库根目录执行make build即可等价构建（见Makefile）。

针对 Windows，还提供了一键交叉构建脚本：

make build-windows

该目标会设置GOOS=windows、GOARCH=amd64、CGO_ENABLED=0，并以-tags abe_embed、-trimpath、-ldflags="-s -w"参数产出.exe文件（见Makefile）。其中abe_embed标签与 Windows 平台的数据解密能力（AES 相关系统调用注入）有关，对应 crypto/windows/payload/embed_windows.go 等文件。如果你修改了 Windows 相关代码，请务必用此命令验证构建通过。

3.2 测试

go test ./...

该命令运行全仓库测试。从 CI 配置（.github/workflows/test.yml）看，测试会在ubuntu-latest、macos-latest、windows-latest三个平台矩阵上分别执行，且非 Windows 平台会额外生成覆盖率报告并上传：

go test -v -coverprofile=coverage.out ./...

因此本地至少应保证go test ./...全绿。仓库的测试非常完整：例如 browser/chromium/decrypt_test.go 覆盖 Chromium 数据解密，browser/firefox/extract_cookie_test.go 覆盖 Firefox Cookie 提取，browser/archive_test.go 覆盖归档导出。新增功能时参考这些测试文件编写对应的单元测试即可。

3.3 静态检查（Lint）

golangci-lint run

注意：该命令要求 golangci-lint v2。仓库在 .golangci.yml 中声明了version: "2"，并启用了多达数十个检查器，大致可分为几类：

• 默认必备：errcheck、govet、staticcheck、ineffassign、unused；
• Bug 检测：errorlint、gosec、sqlclosecheck、nilerr、bodyclose、durationcheck、errchkjson、exhaustive、forcetypeassert；
• 代码质量：depguard、dupl、goconst、gocritic、misspell、revive、unparam、whitespace等；
• 复杂度控制：gocognit（最小复杂度 30）、nestif（最小复杂度 5）。

其中depguard明确禁用了github.com/pkg/errors、io/ioutil等包；gosec针对本项目的特殊性做了大量豁免（如 SHA1/DES 弱加密用于浏览器数据解密、exec.Command用于 macOSsecurity命令等），详见配置文件中的excludes段。CI 使用 golangci-lint v2.10（见.github/workflows/lint.yml），建议本地安装同版本以保证结果一致。

3.4 格式化

gofumpt -l -w . goimports -w -local github.com/moond4rk/hackbrowserdata .

两条命令分工明确：

• gofumpt是比go fmt更严格的格式化工具，仓库在.golangci.yml中将其作为 formatter 启用并开启了extra-rules；
• goimports负责整理 import 分组，-local参数把项目自身的包（github.com/moond4rk/hackbrowserdata）与第三方包分区排列。.golangci.yml的formatters.settings.goimports.local-prefixes与之对应。

3.5 拼写检查

typos

项目使用typos工具做拼写检查，配置在.typos.toml中，对部分技术性词汇（如Readed、Sie、Encrypter等）做了白名单豁免，并排除了go.mod、go.sum。CI 中该检查仅在 ubuntu 平台执行（见.github/workflows/lint.yml）。

四、CI 流水线：三平台矩阵与版本约束如何落地

理解了本地命令后，再看 CI 如何把这些命令串成自动化防线，这能帮你预判 PR 会经历哪些检查。

.github/workflows/test.yml 定义了测试流水线：

• 触发时机：对main分支的 push、所有 PR、手动触发（workflow_dispatch）；
• 三平台矩阵：ubuntu-latest、macos-latest、windows-latest，覆盖项目宣称支持的全部操作系统；
• 使用go-version-file: go.mod自动读取 Go 版本——这再次印证了go.mod中go 1.20指令的地位，它直接决定 CI 使用的工具链版本；
• Windows 平台只跑测试，非 Windows 平台额外产出覆盖率并上传 codecov。

.github/workflows/lint.yml 定义了静态检查流水线：

• 同样三平台跑 golangci-lint v2.10；
• 在 ubuntu 平台额外执行go.mod版本硬校验（第二节所述）与typos拼写检查。

也就是说，一个 PR 至少会经过：Go 版本约束校验 → 拼写检查 → 三平台 lint → 三平台单元测试。任何一环不过，都无法合并。本地尽量把第三节的命令全部跑一遍，能大幅缩短 CI 反馈周期。

五、Pull Request 规范：如何写出可被高效评审的 PR

当代码完成、本地验证通过后，创建 PR 时请遵循以下指南（来自CONTRIBUTING.md）：

1. 关联 Issue：在 PR 描述中链接对应的 Issue，让评审者快速了解背景与动机；
2. 提供上下文：PR 描述中说明改动的背景与原因，帮助评审者理解"为什么这么改"；
3. 附上前后对比示例：如果改动涉及输出、行为或界面变化，尽量给出before/after示例；
4. 说明功能测试步骤或复现步骤：让评审者可以按步骤验证功能正确性；
5. 新功能必须包含单元测试：这是硬性要求，也是项目代码质量的重要保障。

从仓库测试布局（如 browser/chromium/extract_password_test.go、browser/chromium/extract_cookie_test.go 等）可以看出，几乎每个提取模块都有配套测试，新增功能遵循同样的"实现 + 测试"结对模式是默认期望。

六、Commit Message 规范：Conventional Commits 格式

项目要求提交信息遵循Conventional Commits（约定式提交）格式，CONTRIBUTING.md 给出的示例：

feat: add support for new browser fix: resolve cookie decryption on Windows chore: update dependencies docs: improve RFC documentation refactor: simplify profile discovery logic test: add extraction tests for Firefox

对应的类型语义如下：

这种统一格式让git log清晰可读，也为自动生成 changelog、触发 CI 类型化检查提供了基础。注意示例中 "docs: improve RFC documentation" 对应的是仓库中真实的 rfcs/ 目录——HackBrowserData 用 RFC 文档沉淀架构决策（详见第八节），涉及架构性改动时应同步更新对应 RFC。

七、代码风格：build tag 平台隔离与命名规范

CONTRIBUTING.md 的代码风格要求中，平台代码必须使用 build tag（如_darwin.go、_windows.go、_linux.go后缀文件），这在源码中得到了充分体现：

• 浏览器列表按平台隔离：browser/browser_darwin.go（//go:build darwin）、browser/browser_linux.go、browser/browser_windows.go；
• 解密逻辑按平台隔离：crypto/crypto_darwin.go、crypto/crypto_linux.go、crypto/crypto_windows.go；
• 主程序入口按平台隔离：cmd/hack-browser-data/main_others.go 与 cmd/hack-browser-data/main_windows.go，后者承载 Windows 特有的双击模式配置（configureDoubleClickMode）；
• 文件复制逻辑按平台隔离：filemanager/copy_other.go 与 filemanager/copy_windows.go。

因此，当你贡献涉及平台差异的功能（例如新增某平台专用的密钥提取机制）时，应当遵循同样的模式：新建带_darwin.go/_windows.go/_linux.go后缀的文件并在文件头部写//go:build指令，而不是在单个文件里堆叠runtime.GOOS分支。

其余风格要求还包括：

• 命名遵循 Go 官方约定（驼峰、导出标识符首字母大写、包名小写等）；
• 架构性改动参考rfcs/设计文档（见下节）。

八、错误处理与测试规范

8.1 错误处理：必须使用%w包装

错误处理规范的核心是：

使用fmt.Errorf("context: %w", err)包装错误；除非是刻意的尽力而为式清理（如Close/Remove），否则不得忽略错误。

这与 .golangci.yml 中启用的errorlint、errcheck检查器相互呼应：errcheck会拦截被忽略的错误返回值（.golangci.yml中已对os.Remove、(*database/sql.DB).Close等"清理类"调用做了豁免），errorlint则检查错误包装是否符合%w规范。此外depguard禁止了github.com/pkg/errors，要求统一使用标准库fmt.Errorf或errors。

8.2 测试规范：使用t.TempDir()

文件系统相关测试必须使用t.TempDir()，它由 Go 标准库自动创建临时目录并在测试结束时清理。仓库测试中随处可见这一实践：

• browser/archive_test.go：用t.TempDir()构造归档源目录、目标 zip 路径与解压目录；
• browser/browser_test.go：用t.TempDir()构造浏览器配置目录树。

此外，测试文件命名遵循_test.go约定，.golangci.yml对测试文件做了专项豁免（如dupl、funlen、gosec、errcheck等），说明测试代码可以适当放宽部分严格检查，但功能正确性依然是第一位的。

九、架构设计文档：RFC 体系

CONTRIBUTING.md 指出"架构设计参见rfcs/"。仓库的 rfcs/ 目录是项目的设计中枢，共包含 13 篇 RFC 文档，与贡献工作直接相关：

• 001-project-architecture.md：项目整体架构；
• 002-chromium-data-storage.md、003-chromium-encryption.md：Chromium 系浏览器的数据存储与加密方案；
• 004-firefox-data-storage.md、005-firefox-encryption.md：Firefox 的数据存储与加密方案；
• 006-key-retrieval-mechanisms.md：密钥提取机制；
• 007-cli-and-output-design.md：CLI 与输出设计；
• 008-file-acquisition-and-platform-quirks.md：文件获取与平台差异；
• 009-windows-locked-file-bypass.md：Windows 锁定文件绕过；
• 010-chrome-abe-integration.md：Windows 下 Chrome 数据解密集成；
• 011-safari-data-storage.md：Safari 数据存储；
• 012-yandex-decryption.md：Yandex 解密；
• 013-cli-redesign-cross-host.md：跨主机 CLI 重设计。

在提交涉及架构、新浏览器支持或平台机制的 PR 之前，阅读相关 RFC 能让你快速理解设计约束；如果改动改变了既有设计，应同步更新或补充 RFC 文档（对应提交类型docs）。

十、遇到问题怎么办：提问渠道与最终建议

如果对贡献流程、代码约束有任何疑问，可以在 Issue 或 PR 中直接提问，也可以联系维护者（CONTRIBUTING.md 中提供的维护者邮箱me@moond4rk.com）。

最后，把整个贡献流程压缩成一份自检清单，供你提交 PR 前逐项核对：

1. 功能分支是否基于最新的main检出？
2. 是否已有对应 Issue，PR 是否已链接它？
3. 是否使用了 Go 1.21+ 特性？go.mod的go指令是否仍是1.20？
4. 新增依赖是否兼容 Go 1.20（特别注意 SQLite 等底层库的版本）？
5. go build ./cmd/hack-browser-data/、go test ./...、golangci-lint run、gofumpt -l -w .、goimports -w -local github.com/moond4rk/hackbrowserdata .、typos是否全部通过？
6. 平台相关代码是否使用了正确的 build tag 后缀文件？
7. 错误是否用fmt.Errorf("context: %w", err)包装？清理类错误是否按规范豁免处理？
8. 文件系统测试是否使用了t.TempDir()？
9. 新功能是否附带单元测试？
10. Commit message 是否符合 Conventional Commits 格式？

逐项通过这份清单，你的贡献将同时满足社区协作规范与 CI 的技术约束，为 HackBrowserData 的跨平台能力持续添砖加瓦。

• 网络安全
• 应用安全
• 密码学
• CLI