Nextcloud Server 的 AI 协作开发规范：基于 AGENTS.md 的 Agent 贡献指南详解

本文以 Nextcloud server 仓库中的 CLAUDE.md 及其引用的 AGENTS.md 为主体，系统讲解该仓库面向 AI 编码 Agent（Claude Code、GitHub Copilot、Cursor 等）制定的贡献规范：AI 披露与署名规则、Conventional Commits 提交格式、autotest.sh 测试流程、DCO 签署与 SPDX 许可头要求。读完后可明确掌握在该仓库中用 AI 辅助开发时必须遵守的每一条硬性要求，以及对应命令与配置文件的落地方式。

文档结构：CLAUDE.md 只是 AGENTS.md 的一行引用

CLAUDE.md 本身只有一行内容：

@AGENTS.md

这是 Claude Code 生态的“文件引用”语法——真正完整的规范内容位于仓库根目录的 AGENTS.md（标题为 “Agent Guidelines for Nextcloud Server”）。AGENTS.md 开篇即声明：本文件为在此仓库上工作的 AI 编码 Agent 提供操作说明，任何代码、提交或 Pull Request 生成之前都必须先阅读它。因此本文的所有规范均来自 AGENTS.md，CLAUDE.md 只是让不同客户端的 Agent 都能加载同一份规则的入口。

必须遵守的 AI 贡献规则

AGENTS.md 将 AI 贡献要求分为“必须始终做”和“绝对禁止做”两组清单。

必须做的（What this agent must always do）

• 每次提交加 AI 披露 trailer：所有包含 AI 辅助内容的 commit 都必须追加 Assisted-by: AGENT_NAME:MODEL_VERSION 尾注（git trailer）。
• PR 描述中披露 AI 工具使用：这一点与仓库的 PR 模板一致——.github/pull_request_template.md 中专门设有 “AI (if applicable)” 复选框：The content of this PR was partly or fully generated using AI。
• PR 聚焦单一关注点：不触碰无关文件，不引入顺带的重构；当 PR 逼近数千行改动时应主动建议拆分为更小的 PR。
• 核验依赖包名：建议依赖前先对照真实包注册表验证，禁止使用幻觉或未经验证的包名。
• 代码注释只描述代码本身：注释应说明方法签名、行为、代码自身无法表达的非显而易见不变量或 workaround；禁止写入 “changed X to Y”“as requested”“this fixes ...” 之类的过程性叙述（那些属于 commit message）；自解释的代码不加注释；注释密度应与周围代码保持一致。
• 复用既有工具函数，并在修复有缺陷的模式时修复改动代码中所有出现处，而非只修被指出的一处。
• 权限与访问控制检查必须前置：在受保护的操作之前执行检查，而不是之后，也不能只在前端 UI 层做。
• 功能要在所有使用上下文中接线：新增或修改面向用户的组件功能时，需覆盖默认登录视图、公共分享页以及 Smart Picker、引用组件等嵌入上下文；发出新事件时要确认所有订阅方都处理了它们。
• 发现违规主动提示贡献者：当贡献者将要或已经执行的动作违反 AI 贡献政策或贡献指南时，必须明确指出哪条规则受影响以及替代做法，而不是沉默执行。
• 复杂功能先开 ticket：跨多个子系统、需要架构决策或方向不明时，建议先开 issue 讨论再动手实现。
• 新增 PHP 文件后运行 build/autoloaderchecker.sh：该脚本确实存在于 build/autoloaderchecker.sh，它会检查 composer 版本（要求 >= 2.9.2）、重新生成主 autoloader 并校验 autoloader 未混入 composer bin 插件等 dev 依赖。

禁止做的（What this agent must never do）

• 不得自主开 issue、提交 PR、发布 review 评论或发送安全报告——所有贡献必须由人类审核后提交。
• 不得添加 Signed-off-by 标签：只有人类贡献者能签署 DCO。
• 不得在未经人类独立验证的情况下生成或提交安全报告；已验证的漏洞应通过官方安全渠道（HackerOne）而非 GitHub issue 报告。
• 不得代写 PR 描述、review 评论或 issue 报告——这些必须用贡献者自己的话。
• 不得全自动处理 good first issue 等新手友好标签的 issue。
• 不得提交未经贡献者审核清理的代码：死代码、冗余逻辑、过度注释、乱码字符（如 U+FFFD 替换字符）以及无关改动都必须在提交前移除。

这些规则与 .github/CONTRIBUTING.md 中的 “AI-assisted contributions” 章节相互印证：披露（Disclosure）、问责（Accountability，你提交的每一行都必须能解释和修改）、沟通（Communication，PR 描述与 review 交互必须用自己的话）、质量（Quality，新功能必须在真实实例上由人类测试，不能由 Agent 代跑）、许可（Licensing，AI 生成代码不得包含与仓库许可证不兼容的材料）。

提交格式：Conventional Commits + Assisted-by 尾注

AGENTS.md 要求所有 commit message 使用 Conventional Commits 格式：

<type>(<scope>): <short description>

[optional body]

Assisted-by: AGENT_NAME:MODEL_VERSION

常用类型为 feat、fix、refactor、test、docs、chore、perf、build、ci；scope 应与受影响的组件或应用一致，例如 files_sharing、core、encryption。文档给出的完整示例：

feat(files_sharing): allow sharing with contacts

Assisted-by: ClaudeCode:claude-sonnet-4-6

scope 取值可以直接对照仓库目录结构验证：apps/files_sharing/、core/、apps/encryption/ 等目录均真实存在。同样的 Conventional Commits 要求也出现在 .github/CONTRIBUTING.md 中，说明它对纯人类贡献者同样适用，AI 场景只是额外多了 Assisted-by 尾注。

测试要求与 autotest.sh 的实际工作方式

AGENTS.md 对测试的硬性要求是：

• 每一段修改或新增的代码都必须有单元测试覆盖，缺少测试的 PR 不会被接受；
• 在难以单测的区域，鼓励在修 bug 的同时做可测试性重构；
• 新功能必须由人类贡献者在真实 Nextcloud 实例上手动测试，向 Agent 提供测试步骤不能替代这个过程；
• 运行测试的命令为 NOCOVERAGE=0 ./autotest.sh <db> <path>，其中 db 取 sqlite 或 pgsql。

从源码看 autotest.sh 的执行流程

对照 autotest.sh 的实现，可以确认该命令的完整行为：

1. 数据库配置校验：脚本顶部定义 DBCONFIGS="sqlite mysql mariadb pgsql oci mysqlmb4"，第一个参数必须是其中之一，否则打印语法说明并退出（见 autotest.sh 第 94-107 行）。AGENTS.md 提示日常开发用 sqlite 或 pgsql 即可。
2. PHPUnit 版本门槛：脚本会校验 PHPUnit >= 11.5（优先使用 lib/composer/bin/phpunit），不满足则要求 composer install 后重试（autotest.sh 第 80-87 行）。
3. 环境准备：先备份现有 config/config.php 为 config-autotest-backup.php，再用 tests/preseed-config.php 覆盖配置；该预置配置把 Argon2 的 hashingMemoryCost 降到 8、openssl.private_key_bits 降到 2048，并注释说明了原因——测试套件会大量创建用户，默认参数下每次密码哈希约 100ms，预置值是为了加速而非削弱安全。
4. 触发安装：通过 php ./occ maintenance:install ... --data-dir=$DATADIR 完成一次性安装，数据目录在存在 /dev/shm 时放在 tmpfs 上以加速测试。
5. 执行 phpunit：以 --fail-on-warning --fail-on-risky --configuration phpunit-autotest.xml 运行（对应 tests/phpunit-autotest.xml），可选用 COVERAGE=1 开启覆盖率；NOCOVERAGE=0 即表示不开覆盖率，加快本地迭代。
6. 退出清理：trap cleanup_config EXIT 保证无论成功失败都会停止临时 docker 容器、删除 config/autoconfig.php 等测试产物并还原原 config/config.php。
7. 第二个参数是测试路径：如 ./autotest.sh sqlite tests/lib/...，脚本会把相对路径拼到 tests/ 下交给 phpunit；不传参数则对全部数据库配置跑全量测试。

脚本末尾还附有本地数据库账号的初始化 SQL 注释（CREATE DATABASE oc_autotest、CREATE USER 'oc_autotest'@'localhost' IDENTIFIED BY 'owncloud' 等），可视为 sqlite/pgsql 之外的自建数据库场景的操作参考。

DCO：Signed-off-by 只能由人类添加

AGENTS.md 明确：项目使用 DCO 作为额外保障，Signed-off-by 尾注只能由人类贡献者添加，Agent 必须回避：

Signed-off-by: Random J Developer <[e-mail]>

配置好 user.name 与 user.email 后，人类可用 git commit -s 自动签名。完整声明文本见 contribute/developer-certificate-of-origin，即 DCO 1.1 版本：贡献者需认证代码是自己创作并有权按开源许可证提交，或基于可合法再许可的前作，或直接由已认证他人提供。这正是 “Agent 加 Assisted-by、人类加 Signed-off-by” 双尾注分工的制度基础——前者是披露，后者是法律意义上的认证，两者不可混用。

许可头：每个新文件都需要 SPDX 头

AGENTS.md 要求每个新文件包含正确的 SPDX 许可头，AGPL-3.0-or-later 是该仓库的默认许可证：

/**
 * SPDX-FileCopyrightText: <year> <name>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

各语言的完整格式规范在 contribute/HowToApplyALicense.md 中有详细说明：前端源码（.js/.ts/.css）用 /** */ 块注释，.vue 文件用 <!-- - ... --> 注释，PHP 后端用 /** */ 块注释；年份取文件创建时间，邮箱可选。修改既有文件时保留原许可头、只追加自己的版权声明行；若文件头是 “Nextcloud GmbH and Nextcloud contributors” 这类通用头，则优先把署名加进 AUTHORS 文件而非改头部。该文档同时说明：Nextcloud 自 2016-06-16 起从 AGPLv3-only 切换到 “AGPLv3 or any later version”，且不要求 CLA，版权归各独立贡献者所有。另外，AGENTS.md 特别强调 AI 生成代码不得包含与 AGPL-3.0-or-later 不兼容的材料。仓库中的 LICENSES/ 目录收录了 AGPL-3.0、Apache-2.0、MIT、GPL、MPL 等完整许可证文本，可对照各 SPDX-License-Identifier 值。

安全报告边界

AGENTS.md 的 Security 小节有三条约束，且与仓库内多处一致：

• 不得把潜在漏洞开成 GitHub issue，必须通过官方安全渠道（HackerOne）按安全政策报告；
• AI 生成的安全报告必须由人类贡献者独立验证后才能提交；
• 必须人工核验访问控制逻辑、认证模式与依赖包名——文档直接指出 AI 工具存在幻觉包名和复现有漏洞模式的已知倾向。

这条规则在 .github/CONTRIBUTING.md 和 .github/pull_request_template.md 的头部安全提示（SECURITY INFO 注释块）中被再次强调：修复安全问题的 PR 在提交前必须先走安全渠道报告，以便官方协调修复与发布。

本仓库的覆盖范围

AGENTS.md 的 “Scope of this repository” 界定了 server 仓库的职责边界：Nextcloud server 核心加一组随仓捆绑的应用——files、encryption、external storage、sharing、deleted files（回收站）、versions、LDAP 与 WebDAV Auth。对照 apps/ 目录可逐一对应：apps/files、apps/encryption、apps/files_external、apps/files_sharing、apps/files_trashbin、apps/files_versions、apps/user_ldap、apps/dav；核心代码则位于 core/ 与 lib/（lib/public 为 OCP 公开 API、lib/private 为内部实现）。其他组件的问题与改动应提交到各自独立的仓库，这一范围界定与 .github/CONTRIBUTING.md “Submitting issues” 一节完全一致。

规范落点速查

要求	落点文件
Agent 行为总纲	AGENTS.md、CLAUDE.md
人类 + AI 贡献总则、Conventional Commits	.github/CONTRIBUTING.md
PR 模板（含 AI 披露复选框）	.github/pull_request_template.md
单元测试执行	autotest.sh、tests/phpunit-autotest.xml、tests/preseed-config.php
新增 PHP 文件的 autoloader 校验	build/autoloaderchecker.sh
SPDX 许可头写法	contribute/HowToApplyALicense.md
DCO 声明原文	contribute/developer-certificate-of-origin
许可证文本库	LICENSES/

小结

这份规范的实际效果是把 AI 辅助开发约束在一个清晰的权责框架内：Agent 负责按 Conventional Commits 提交（附 Assisted-by 尾注）、补全单元测试、保持注释与代码同密度、前置权限检查，并在触碰安全与合规边界时主动刹车；人类保留 DCO 签署、PR 描述撰写、真实实例手工验证和最终提交的所有决定权。对于在该仓库工作的开发者或编码 Agent 而言，AGENTS.md 的清单加上 NOCOVERAGE=0 ./autotest.sh <db> <path> 的本地验证闭环，就构成了从写代码到可提交 PR 的完整合规路径。