rclone AGENTS.md 精读：AI 编码代理协作开发规范、构建测试流程与核心架构约定

rclone 仓库根目录下的 AGENTS.md 是专门写给 AI 编码代理（Claude Code、Codex、Cursor、Gemini CLI 等）看的开发协作指南：它规定了改动 rclone 代码时必须遵守的兼容性底线、最小的构建与测试命令集、后端/命令的架构约定，以及提交信息与注释风格。读懂这份文档并对照其引用的源码（fs/ 核心接口、backend/all/all.go 注册机制、Makefile 测试目标、.golangci.yml lint 配置），你就能掌握一套在多后端存储同步工具上做安全、可合并贡献的完整工作流。

这份文档是什么：AI 代理协作指南的定位

AGENTS.md 开篇即声明它的读者是 AI 编码代理，并强调了一条核心责任边界：

Rclone 欢迎 AI 辅助的贡献，但前提是作为人类提交者的你必须理解你所提议的每一行代码，并且这些代码是针对真实的 rclone 代码编译、测试过的——而不仅仅是被生成出来的。在发起 Pull Request 之前，请先阅读 CONTRIBUTING.md 的 "AI-assisted contributions" 部分。

也就是说，这份文件既是对机器（代理）的操作手册，也是对人（提交者）的问责声明：生成代码可以，但对代码正确性的最终理解与验证责任在人。仓库中另外存在一份 CLAUDE.md，其内容仅一行导入语句（@AGENTS.md），表明 Claude Code 通过它读取同一份共享指南——所有 AI 代理共用一份权威规范，避免各工具各自为政。

文档给出的项目概览同样简洁而准确：rclone 是一个用 Go 编写的命令行程序，用于在本地与云存储之间同步文件和目录，支持 70 余个后端（backend），常被类比为"面向云存储的 rsync"。

通用原则：兼容性优先、改动最小化

文档的 "General Notes" 部分提出了四条贯穿整个项目的工程原则，每一条都直接对应仓库中的可验证事实：

1. 向后兼容性被高度重视。不应在没有充分理由的情况下改变现有命令、flag 或 rc API 的可观察行为。rclone 不追求稳定的 Go API（不保证库接口不变），但也不应无故变动它。
2. 多后端兼容是 lifeline。由于 rclone 运行在大量不同后端上，后端集成测试是保证兼容性的手段。任何改动都必须同时考虑已知与未知的后端，注意不要破坏现有安装的功能。
3. 核心层禁止后端特判。fs 和 vfs 下的核心部分必须对所有后端工作，"针对特定后端的 hack 不会被合并"。修复应放在相应的后端实现里；如果确实需要新行为，应通过新增 Feature flag 来表达。这一点在 fs/features.go 中有直接对应：Features 结构体正是后端声明可选能力的标准机制。
4. 改动保持最小。尽力做出最优雅、最小的改动；除非必要，不要重构或重排代码，那会增加评审难度。应复用现有的测试脚手架与 lib 下的库例程。文档同时要求：新增的测试必须真正测试你所写的代码并测试改动的意图；修复问题时，先写能复现问题的测试，再着手修复。

构建与测试命令全集

文档给出了一套可直接复制运行的命令清单，覆盖了从构建、单元测试、单测过滤、竞态检测、lint 到后端集成测试的全部场景。下面完整继承这些命令，并结合 Makefile 的实际实现补充细节：

# Build rclone (simple)
go build

# Build with version info (preferred)
make

# Run all unit tests (no cloud credentials needed)
make quicktest
# or equivalently:
RCLONE_CONFIG="/notfound" go test ./...

# Run tests for a specific package
cd backend/memory && go test -v
# or from root:
go test -v ./backend/memory/

# Run a single test
go test -v -run TestIntegration/FsCheckWrap ./backend/memory/

# Run tests with race detector
make racequicktest

# Lint (requires golangci-lint)
golangci-lint run ./...

# Run backend integration tests (requires configured TestRemote remote)
cd backend/drive && go test -v
# Run sync/operations integration tests against a remote
cd fs/sync && go test -v -remote TestDrive:
cd fs/operations && go test -v -remote TestDrive:

# Run integration tests via test framework
go run ./fstest/test_all -backends drive

几个值得注意的实现细节（均可在 Makefile 中核对）：

• make quicktest 的实际定义是 RCLONE_CONFIG="/notfound" go test $(LDFLAGS) $(BUILDTAGS) -timeout 20m ./...。把 RCLONE_CONFIG 指向一个不存在的目录，是为了让测试不读取开发者本地的真实 rclone 配置，从而保证"无需任何云凭证即可运行全部单元测试"；超时上限从 Go 默认的 10 分钟提高到 20 分钟，注释说明原因是 cmd/gitannex 的端到端测试在慢速 CI 上可能超过 10 分钟。
• make racequicktest 则在同样隔离配置的基础上追加了 -cpu=2 -race，用于带竞态检测器的测试。
• 单包测试示例选取 backend/memory 是有代表性的：它是一个纯内存后端，不需要任何外部服务。
• 集成测试通过 -remote TestDrive: 这类参数指定要使用的远端（remote 名为 TestDrive），或通过 go run ./fstest/test_all -backends drive 使用测试框架批量运行指定后端的通用测试套件。这套框架位于 fstest/，其中 fstest/fstests/ 存放通用的后端测试集。

架构：入口、注册与核心抽象

入口点与插件注册模式

rclone.go 是主入口。它通过空导入（blank import）引入 backend/all 和 cmd/all，利用 Go 的 init() 机制在启动时完成所有后端与命令的注册；每个后端在自己的包初始化时调用 fs.Register() 并传入一个 fs.RegInfo 结构体。仓库根目录的 rclone.go 印证了这一点，其全部逻辑只有三处导入加一个 main()：

package main

import (
	_ "github.com/rclone/rclone/backend/all" // import all backends
	"github.com/rclone/rclone/cmd"
	_ "github.com/rclone/rclone/cmd/all"    // import all commands
	_ "github.com/rclone/rclone/lib/plugin" // import plugins
)

func main() {
	cmd.Main()
}

对应的 backend/all/all.go 是一个纯粹的"聚合包"，对 alias、azureblob、b2、crypt、drive、s3、webdav 等 60 余个后端逐一空导入；cmd/all/all.go 以同样方式聚合所有命令包。新增一个后端或命令时，就是在对应包中实现并在此处加一行导入。

核心接口（fs/ 包）

fs 包定义了所有后端必须面对的核心抽象，文档列出的四个关键类型都能在源码中精确定位：

• fs.Fs（fs/types.go）：每个后端必须实现的"文件系统"接口。它内嵌只读的 Info 接口（Name/Root/String/Precision/Hashes/Features），并定义五个核心操作：List（列目录）、NewObject（按路径查找对象）、Put（上传）、Mkdir（建目录，已存在时不应报错）、Rmdir（删空目录，不存在或非空时返回错误）。接口的 godoc 注释本身就把契约写得非常细，例如 Put 注释明确了未知大小（src.Size() == -1）输入时的处理义务。
• fs.Object（fs/types.go）：文件/对象接口，包含 Open（打开读）、Update（上传更新）、Remove（删除）、SetModTime（设置修改时间），并内嵌 ObjectInfo 提供 Hash、Storable 等只读元信息。
• fs.Features（fs/features.go）：后端可声明的可选能力结构体（Purge、Copy、Move、DirMove 等）。后端对支持的操作设置函数指针，nil 表示不支持。这正是前述"核心层不做后端特判"原则的配套机制——核心代码统一面向 Features 探测能力，而不是 if backend == "drive" 式的判断。
• fs.RegInfo（fs/registry.go）：后端注册元数据，字段包括 Name、Description、命令行 flag 前缀 Prefix、NewFs 构造函数、交互式配置函数 Config、配置选项 Options、命令帮助 CommandHelp、别名 Aliases 等。全局注册表就是 var Registry []*RegInfo。

后端组织约定（backend/）

每个后端是 backend/ 下的一个独立 Go 包（如 backend/s3/、backend/drive/）。文档给出了明确的结构约定：

• 主实现放在单个文件中（如 s3.go），不要拆成 fs.go/object.go 这样的多文件布局——这与仓库现状一致，如 backend/s3/s3.go、backend/drive/drive.go。
• API 类型放在独立的 api/types.go（各后端的 api/ 子包）。
• 测试文件（如 s3_test.go）使用 fstest/fstests 的 fstests.Run() 执行标准化的集成测试。
• 在 backend/all/all.go 中通过空导入完成注册。
• HTTP 类后端应使用 lib/rest 发起 HTTP 调用、使用 fs/fshttp 创建 HTTP 客户端；基于目录 ID 的远端用 lib/dircache 缓存目录映射，OAuth 授权用 lib/oauthutil，限流用 lib/pacer。

命令组织与关键子系统

每个命令是 cmd/ 下的一个包（如 cmd/ls/ls.go），通过 cmd/all/all.go 空导入注册，统一经由 cmd.Main()（cobra）分发。

文档列出的关键子系统及其职责：

子系统	路径	职责
核心文件操作	fs/operations/	Copy、Move、Delete 等操作
目录同步	fs/sync/	sync 的目录比对逻辑
并行目录树遍历	fs/march/	sync 使用的并行 walker
包含/排除过滤	fs/filter/	include/exclude 规则
传输统计与带宽限制	fs/accounting/	统计与限速
配置文件管理	fs/config/	rclone.conf 的读写
虚拟文件系统层	vfs/	mount、serve 的基础
C 兼容库接口	librclone/	以库形式嵌入 rclone
集成测试框架	fstest/	通用后端测试套件在 fstest/fstests/

提交信息约定：写给用户看的 changelog

文档对 commit message 有两条硬性要求：

1. 前缀格式：以"被改动目录 + 冒号"开头，例如 drive: add team drive support - fixes #885；跨切面改动使用更宽的前缀，如 fs 或 operations。
2. 首行面向用户：第一行必须是普通用户（而非开发者）愿意读到的改动摘要。因此应写 drive: fix server side copy of big files，而不是 drive: no longer set the MimeType in Move or Copy。文档解释了原因：这些行会直接进入用户阅读的 changelog。

代码注释风格：写给"不知道这次改动"的未来读者

文档的注释规范可以概括为五条规则，核心思想是注释描述代码当前的样子，而不是描述本次改动：

• 每个导出的类型、函数、字段、常量都要有 godoc 注释，以名称开头、以现在时陈述句描述它"是什么/做什么"（示例：// Mkdir makes the directory (container, bucket)——这正是 fs/types.go 中 Mkdir 的实际注释）。
• 记录调用方需要的契约：前置条件、返回值、何时返回哪些哨兵错误、以及"已存在时不应报错"之类的注意事项，而不是实现细节。
• 保持简洁：多数情况一行足矣；只有真正的微妙之处才用空 // 行分隔出额外段落。
• 函数体内的行内注释解释"为什么"：不明显的 API 怪癖、变通方案、陷阱或顺序约束；当外部引用（论坛帖子、厂商文档、RFC）正是让行为变得不显然的原因时可以引用；对代码明摆着在做的事的复述性注释要跳过。
• 已知缺陷使用 FIXME 与 TODO 标记；禁止叙述改动本身——不写 "now we also handle..."、"changed to..."、"previously this returned..."，也不在源码中引用 bug/PR 编号；这些上下文属于 commit message，而不属于会比改动活得久的源码。

Lint 配置：golangci-lint v2 的显式白名单

项目使用 golangci-lint v2，配置位于 .golangci.yml。从配置内容看，其策略是"忽略隐式默认集、显式枚举所有要用的 linter"（default: none），当前启用的是：

• 默认组：errcheck、govet、ineffassign、staticcheck、unused
• 附加组：gocritic、misspell、revive、unconvert
• 格式化器：goimports

配置中还有若干精细调优，例如 govet 开启全部检查但关掉 fieldalignment 与 shadow；staticcheck 关闭了 ST1003 等命名类检查与 SA4023（注释解释了原因：数据流分析使大型包的 lint 慢 10 倍以上导致 CI 超时，且在 operations.Delete 等位置产生误报）；gocritic 显式启用了约 30 项检查并加载自定义 ruleguard 规则（bin/rules.go）；revive 显式启用 20 余项规则并对两条 var-naming 规则做了豁免。运行 lint 的命令即文档中的 golangci-lint run ./...（Makefile 的 check 目标还会额外跑 bin/markdown-lint 校验 Markdown）。

文档生成约定：文档来自源码，不是手写

文档最后几条 Documentation 规则揭示了 rclone 的文档生成管线，对贡献者尤其重要：

• 后端选项文档来自 Go 源码 Options 结构体中的 Help: 字段，而不是手写 Markdown。
• 命令文档位于命令源码中（例如 Long:/Short: 字段在 cmd/ls/ls.go 一类的文件里）。
• 不要提交 make backenddocs 或 make commanddocs 自动生成的文档变更（这两个目标在 Makefile 中定义，均依赖先构建出 rclone 二进制）。
• 网站文档位于 docs/content/ 目录下的 Markdown 文件，使用 Hugo 构建，make serve 可本地预览。

小结：从 AGENTS.md 学到的 rclone 贡献方法论

把整份文档串起来看，rclone 对（AI 辅助的）贡献提出了一个清晰闭环：先理解兼容性与最小改动原则 → 用 make/go build 构建、用 make quicktest（RCLONE_CONFIG="/notfound" 隔离配置）跑通无需凭证的单元测试、必要时用 -remote 或 fstest/test_all 做集成验证 → 遵循"单文件主实现 + api 子包 + fstests.Run() 测试 + all.go 注册"的后端结构和面向用户的 commit 首行、面向未来读者的契约式注释 → 通过 .golangci.yml 定义的 lint 白名单 → 文档改动回归到源码注释（Help: 字段）而非手写页面。对任何希望在多后端、强兼容性约束的 Go 大型项目上工作的开发者或 AI 代理来说，这套"原则 + 命令 + 结构 + 风格"的组合本身就是一份可复用的协作范本。