Nacos AGENTS.md 深度解读面向 AI 编程 Agent 的仓库协作与贡献规范实战指南【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacosDynamic Naming and Configuration Service是一个面向云原生与 AI 云原生应用的服务发现、动态配置与 AI Agent 管理平台。随着 Claude Code、Cursor、GitHub Copilot 等 AI 编码工具进入日常开发流程Nacos 仓库根目录下的 AGENTS.md 成为 AI Agent 在仓库中工作的行为契约它规定了 AI 何时可以动手改代码、必须遵守哪些规范流程、如何通过 Maven 构建与测试、如何按 Alibaba Java 编码规范提交代码。本文以 AGENTS.md 为骨架结合仓库源码、pom.xml 插件配置与集成测试文档完整拆解这套面向 AI 协作的工程规范帮助你无论是人还是 Agent在 Nacos 仓库中安全、合规、高质量地完成第一次贡献。为什么一个开源仓库需要 AGENTS.mdAI 编码工具的能力越强就越需要一套可执行、可校验的约束避免AI 生成的代码破坏大型项目的契约与质量。Nacos 的做法是在仓库根目录提供 AGENTS.md面向 AI Agent 明确三层约束协作礼仪不在 issue/PR 上发布 AI 生成的评论讨论只属于人类流程红线实现方向必须先与维护者对齐改动任何行为、API、SDK、插件、存储、运行时流程或领域语义之前必须先阅读 specs/ 下的规范并以规范为唯一实现依据质量门禁提交前必须通过 Spotless 格式化、Checkstyle、SpotBugs、Apache RAT 等一系列检查任何 API/SDK 变更必须同步更新对应的集成测试覆盖注册表。这份文件本身也是人类贡献者的指引入口——它明确说明人类贡献者请参见 CONTRIBUTING.md。AI 贡献准则先讨论后编码AGENTS.md 的第一部分定义了 AI Agent 参与 Nacos 开发的硬性规则核心可以概括为四条准则要求禁止 AI 评论不要在 issue 或 PR 上发布 AI 生成的评论讨论是人类的专属领域先讨论再实现动手前必须在 issue 评论中与维护者就实现方向达成一致Spec-first 强制改动行为、API、SDK、插件、存储、运行时流程或领域语义前必须阅读 specs/ 相关规范并以规范为规则的来源Spec 随设计同步更新任何设计提案若改变或澄清了规范覆盖的行为必须在同一变更集中附带对应的 spec 更新大型或有争议的设计优先先提交纯 spec/design PR再跟进实现 PR此外AGENTS.md 要求当提交中相当一部分内容由 AI 生成时必须在 commit message 中添加 trailerAssisted-by: Claude Code这是业界常见的 AI 使用披露惯例便于维护者审阅时了解代码来源。API 变更测试影响前置Test-First 的变体AGENTS.md 对两类公共契约变更提出了影响分析先行的强制要求HTTP API 变更新增、修改、删除或废弃任何 HTTP API 前必须先分析 test/openapi-test 的覆盖情况并在同一变更集中更新 API IT 场景矩阵、测试用例与覆盖注册表若功能路径无法在独立 IT 中验证至少覆盖边界/错误场景并说明原因Java SDK 公共契约变更新增、修改、删除或废弃任何公共 Java SDK 接口、工厂、模型、监听器行为、生命周期行为或异常映射前必须先分析并更新 test/java-sdk-test 的覆盖包括场景文档。这条规则直接呼应了仓库中JAVA_SDK_IT_COVERAGE.md的维护方式覆盖注册表按场景而非行/分支覆盖率记录例如ConfigServiceJavaSdkITCase记录为Covered验证了工厂创建、发布/查询/CAS/删除生命周期、缺失结果形态、幂等删除、监听器增删、空监听器拒绝等场景而NamingServiceJavaSdkITCase因为仍有场景缺口被标记为Partial。这种场景矩阵 状态标注的机制让 Agent 可以快速定位自己改动的 API 是否已有测试保护。仓库概览从模块布局理解 Nacos 架构AGENTS.md 给出了一份精炼的模块地图当前版本为3.2.1-SNAPSHOT主分支develop服务端要求JDK 17客户端模块 JDK 8构建工具为Maven 3.2.5。核心模块及其职责如下模块/目录职责api / client / client-basic面向客户端的 API、gRPC 定义与 SDKJava 8 兼容common共享工具、HTTP 客户端、通知中心NotifyCenter、执行器config配置管理服务端naming服务发现与注册服务端core核心服务端基础设施集群、分布式共识consistency基于 JRaft 的 CP 协议 自定义 Distro AP 协议auth认证与授权plugin / plugin-default-impl基于 Java SPI 的可扩展插件系统auth、visibility、datasource dialect、config change、encryption、trace、environment、control、AI pipeline、AI storage 等类型console / console-uiWeb UI 后端Spring Boot与前端Reactai / copilot / ai-registry-adaptorAI Agent 支持、Copilot 集成与 AI registry 适配器sys系统环境工具与 JVM 参数管理bootstrap / server服务端启动与聚合persistence数据持久化Derby、MySQL、PostgreSQL 等多数据库支持maintainer-client内部维护客户端lock分布式锁支持通信上Nacos 以gRPC 为主、HTTP/REST 兼容旧协议Protobuf 定义位于 api/src/main/proto/。平台核心能力包括服务发现、动态配置、动态 DNS、服务/元数据管理以及面向 AI 的 AI registryPrompt、MCP、A2A能力。构建与测试命令从零编译到提交检查AGENTS.md 提供了完整的 Maven 命令清单这是任何 Agent 在仓库中工作的第一步# 完整构建跳过测试 mvn -Prelease-nacos,!dev -Dmaven.test.skiptrue clean install -U # 运行全部单元测试 mvn test # 运行 standalone-server 集成测试 mvn -pl test/openapi-test -Pintegration-test -DskipTestsfalse verify mvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTestsfalse verify mvn -pl test/maintainer-sdk-test -Pmaintainer-sdk-integration-test -DskipTestsfalse verify # 提交前格式化代码 mvn spotless:apply # 提交前检查PR 前必须通过 mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests从根 pom.xml 可以看到这些检查工具的版本约定apache-rat-plugin0.12、maven-checkstyle-plugin3.6.0、spotbugs-maven-plugin4.8.6.2其中 SpotBugs 还配置了排除过滤器 style/spotbugs-exclude.xmlCheckstyle 通过checkstyle依赖加载 Nacos 自有的检查规则。这说明质量门禁不是默认配置而是项目定制的严格集合。Spotless 是格式化的唯一标准AGENTS.md 特别强调了一个容易踩坑的点不要把checkstyle:check、spotbugs:check或git diff --check当作 Spotless 的替代品。项目使用 Spotless 与自有 formatter其接受的格式可能与通用的空白检查结果不同。标准流程是先执行mvn spotless:apply对同一范围执行mvn spotless:check校验再运行相关的 compile/check/test 命令只有 Spotless 与相关校验全部通过后才允许提交。代码风格遵循 Alibaba Java 编码规范Nacos 代码风格遵循Alibaba Java Coding Guidelines配置文件包括Checkstyle 配置style/NacosCheckStyle.xmlIDEA 代码风格style/nacos-code-style-for-idea.xmlAGENTS.md 用一张表列出了 Agent 必须遵守的关键规则规则取值缩进4 空格基础缩进与 case 缩进均为 4 空格行长度最长100 字符由 Spotless Checkstyle 强制执行Star imports禁止——必须使用显式导入未使用的导入禁止JavadocAPI 方法必须书写豁免Override、Test、Before、After、BeforeClass、AfterClass、Parameterized、Parameters、Bean大括号所有if/else/for/while/do-while块必须使用大括号即使是单行Switch必须有default分支fall-through 必须注释说明命名方法/变量用camelCase类用PascalCase常量用UPPER_SNAKE_CASE缩写名称中最多 1 个连续大写字母例外VO许可证头每个新文件都必须携带每个新源文件必须包含 Apache License 2.0 头CI 通过apache-rat:check强制执行。标准模板如下/* * Copyright 1999-${year} Alibaba Group Holding Ltd. * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */API 标准v3 API 的设计契约AGENTS.md 明确指出 Nacos v3 API 遵循严格约定Agent 生成 controller 代码时必须遵守。权威的 API 与 SDK 规范位于 specs/提供英文与简体中文双语版本规范层次从顶层设计nacos-design-spec.md、resource-model-spec.md逐级延伸到基础能力、领域能力Config/Naming/AI Registry/Core 运维/Console/分布式锁、接口规范HTTP/gRPC/SDK、扩展模型、安全模型与测试模型。URL 路径模式API 类型基础路径用途示例Open API/v3/client/{module}/...面向客户端的操作/v3/client/ns/instanceAdmin API/v3/admin/{module}/...管理操作/v3/admin/ns/serviceConsole API/v3/console/{module}/...Web 控制台操作/v3/console/cs/configAuth API/v3/auth/{resource}/...插件提供的鉴权操作/v3/auth/user模块缩写模块缩写范围Config Servicecs配置管理Naming Servicens服务发现Corecore集群、命名空间管理AIaiAI 资源管理Pluginplugin插件管理需要注意的是Auth API/v3/auth/user、/v3/auth/role、/v3/auth/permission定义在plugin-default-impl模块中而不是 core 模块。HTTP 方法语义方法用途幂等GET查询 / 检索是POST创建 / 注册否PUT更新 / 修改是DELETE删除 / 注销是响应格式与鉴权所有响应必须包装在com.alibaba.nacos.api.model.v2.ResultT源码见 Result.java中{ code: 0, message: success, data: { } }所有接口必须添加Secured注解定义于 Secured.javaSecured(action ActionTypes.READ, // READ 或 WRITE signType SignType.CONFIG, // CONFIG、NAMING 或 CONSOLE apiType ApiType.ADMIN_API) // OPEN_API、ADMIN_API 或 CONSOLE_APIController 示例AGENTS.md 给出了标准的 v3 Admin API Controller 模板融合了响应包装、鉴权注解与表单校验import com.alibaba.nacos.api.model.v2.Result; import com.alibaba.nacos.auth.annotation.Secured; import com.alibaba.nacos.plugin.auth.constant.ActionTypes; import com.alibaba.nacos.plugin.auth.constant.SignType; import com.alibaba.nacos.api.common.ApiType; RestController RequestMapping(/v3/admin/ns/service) public class ServiceControllerV3 { PostMapping Secured(action ActionTypes.WRITE, apiType ApiType.ADMIN_API) public ResultString create(ServiceForm serviceForm) throws Exception { serviceForm.validate(); // business logic ... return Result.success(ok); } GetMapping(/list) Secured(action ActionTypes.READ, apiType ApiType.ADMIN_API) public ResultPageServiceDetailInfo list(ServiceListForm serviceListForm) throws NacosException { serviceListForm.validate(); // business logic ... return Result.success(result); } }这个模板值得细读serviceForm.validate()把参数校验前移到入口Result.success(...)保证统一的响应结构Secured声明式地接入鉴权体系。从API_TEST_COVERAGE.md的统计看这套约定在测试侧形成了闭环——Client OpenAPI 场景行 11 行、Admin API 38 行、Console API 29 行严格覆盖率分别为 90.91%、81.58%、82.76%有效覆盖率更高每行对应预期能力 / 边界校验 / 异常处理三类场景中的若干种。集成测试的完整处理流程对每个 HTTP API 的新增/修改/删除/废弃AGENTS.md 要求在变更完成前处理 test/openapi-test阅读受影响的 controller、form/request 模型、校验器、service 路径、响应模型、异常处理及匹配的 spec构建或更新场景矩阵覆盖预期能力、边界/校验行为与异常/错误处理为变更的契约新增、更新或删除 API IT 用例目标是API 场景覆盖而非行/分支覆盖更新 test/openapi-test/API_TEST_COVERAGE.md 及对应的*_API_TEST_SCENARIOS.md文档若独立 IT 难以覆盖功能成功路径至少覆盖边界与错误场景并记录未覆盖路径。Java SDK 公共契约变更同样如此且有一条特别约束SDK IT 必须作为外部客户端测试对独立的 Nacos server 运行禁止在测试类内部启动 Spring 或 Nacos。从JAVA_SDK_IT_COVERAGE.md可以看到AiServiceJavaSdkITCase、LockServiceJavaSdkITCase、AiTransportResourceMatrixJavaSdkITCase等测试类如何在真实 standalone server 上验证工厂创建、发布/订阅/轮询、重连重放redo等端到端行为。Java 版本目标服务端与客户端的边界AGENTS.md 明确了 Java 版本的双轨策略服务端模块config、naming、core、console 等Java 17客户端/API/插件模块api、client、pluginJava 8——修改时务必保证向后兼容。这条边界对 Agent 尤其重要在客户端模块引入 Java 9 特性、在服务端模块过度保守都是错误的兼容性约束还进一步体现在 compatibility-deprecation-spec.md 等规范中。PR 约定与提交前检查清单所有 PR 必须面向develop分支标题格式为[ISSUE #14122] Add JVM --add-opens options for JDK 17 compatibility即[ISSUE #编号] 变更描述的结构便于在提交历史上直接追溯到关联 issue。提交前检查清单mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests mvn clean install mvn clean test-compile failsafe:integration-test这条链路的含义是先做静态质量与格式化门禁再确保全量编译与安装通过最后执行 failsafe 集成测试——与 AGENTS.md 开头Pre-submission checks (MUST pass before PR)的定位一致。安全漏洞走专用渠道AGENTS.md 特别规定不要通过 GitHub Issues 报告安全漏洞应使用阿里安全响应中心ASRC渠道。这是大型开源项目处理安全问题的标准做法——漏洞详情在修复前需要保密避免公开讨论造成 0-day 风险。给 AI Agent 的实操 Checklist综合 AGENTS.md 全文一个 AI Agent 在 Nacos 仓库贡献代码的最小合规路径是阅读specs/ 中与改动相关的规范英文/中文双语齐全确认现有契约讨论在 issue 中与维护者确认实现方向若改动涉及规范覆盖的行为先提交 spec/design PR编码遵守 4 空格缩进、100 字符行宽、显式导入、强制大括号、Secured鉴权、ResultT响应包装格式化mvn spotless:apply后执行mvn spotless:check这是格式化的唯一标准测试改动 HTTP API 更新 test/openapi-test改动 Java SDK 更新 test/java-sdk-test同步场景矩阵与覆盖注册表检查执行mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests全套门禁提交为 AI 生成内容添加Assisted-by:trailerPR 面向develop分支标题遵循[ISSUE #xxx]格式。这套流程的本质是把人写代码时靠经验与评审约束的过程转译成 Agent 可以逐条执行、机器可以逐项校验的工程规范。无论你是想为 Nacos 提交第一个修复还是评估如何在自己的开源项目中建立 AI 协作规范AGENTS.md 都是一份可以直接参照的模板。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nacos AGENTS.md 深度解读：面向 AI 编程 Agent 的仓库协作与贡献规范实战指南
Nacos AGENTS.md 深度解读面向 AI 编程 Agent 的仓库协作与贡献规范实战指南【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosNacosDynamic Naming and Configuration Service是一个面向云原生与 AI 云原生应用的服务发现、动态配置与 AI Agent 管理平台。随着 Claude Code、Cursor、GitHub Copilot 等 AI 编码工具进入日常开发流程Nacos 仓库根目录下的 AGENTS.md 成为 AI Agent 在仓库中工作的行为契约它规定了 AI 何时可以动手改代码、必须遵守哪些规范流程、如何通过 Maven 构建与测试、如何按 Alibaba Java 编码规范提交代码。本文以 AGENTS.md 为骨架结合仓库源码、pom.xml 插件配置与集成测试文档完整拆解这套面向 AI 协作的工程规范帮助你无论是人还是 Agent在 Nacos 仓库中安全、合规、高质量地完成第一次贡献。为什么一个开源仓库需要 AGENTS.mdAI 编码工具的能力越强就越需要一套可执行、可校验的约束避免AI 生成的代码破坏大型项目的契约与质量。Nacos 的做法是在仓库根目录提供 AGENTS.md面向 AI Agent 明确三层约束协作礼仪不在 issue/PR 上发布 AI 生成的评论讨论只属于人类流程红线实现方向必须先与维护者对齐改动任何行为、API、SDK、插件、存储、运行时流程或领域语义之前必须先阅读 specs/ 下的规范并以规范为唯一实现依据质量门禁提交前必须通过 Spotless 格式化、Checkstyle、SpotBugs、Apache RAT 等一系列检查任何 API/SDK 变更必须同步更新对应的集成测试覆盖注册表。这份文件本身也是人类贡献者的指引入口——它明确说明人类贡献者请参见 CONTRIBUTING.md。AI 贡献准则先讨论后编码AGENTS.md 的第一部分定义了 AI Agent 参与 Nacos 开发的硬性规则核心可以概括为四条准则要求禁止 AI 评论不要在 issue 或 PR 上发布 AI 生成的评论讨论是人类的专属领域先讨论再实现动手前必须在 issue 评论中与维护者就实现方向达成一致Spec-first 强制改动行为、API、SDK、插件、存储、运行时流程或领域语义前必须阅读 specs/ 相关规范并以规范为规则的来源Spec 随设计同步更新任何设计提案若改变或澄清了规范覆盖的行为必须在同一变更集中附带对应的 spec 更新大型或有争议的设计优先先提交纯 spec/design PR再跟进实现 PR此外AGENTS.md 要求当提交中相当一部分内容由 AI 生成时必须在 commit message 中添加 trailerAssisted-by: Claude Code这是业界常见的 AI 使用披露惯例便于维护者审阅时了解代码来源。API 变更测试影响前置Test-First 的变体AGENTS.md 对两类公共契约变更提出了影响分析先行的强制要求HTTP API 变更新增、修改、删除或废弃任何 HTTP API 前必须先分析 test/openapi-test 的覆盖情况并在同一变更集中更新 API IT 场景矩阵、测试用例与覆盖注册表若功能路径无法在独立 IT 中验证至少覆盖边界/错误场景并说明原因Java SDK 公共契约变更新增、修改、删除或废弃任何公共 Java SDK 接口、工厂、模型、监听器行为、生命周期行为或异常映射前必须先分析并更新 test/java-sdk-test 的覆盖包括场景文档。这条规则直接呼应了仓库中JAVA_SDK_IT_COVERAGE.md的维护方式覆盖注册表按场景而非行/分支覆盖率记录例如ConfigServiceJavaSdkITCase记录为Covered验证了工厂创建、发布/查询/CAS/删除生命周期、缺失结果形态、幂等删除、监听器增删、空监听器拒绝等场景而NamingServiceJavaSdkITCase因为仍有场景缺口被标记为Partial。这种场景矩阵 状态标注的机制让 Agent 可以快速定位自己改动的 API 是否已有测试保护。仓库概览从模块布局理解 Nacos 架构AGENTS.md 给出了一份精炼的模块地图当前版本为3.2.1-SNAPSHOT主分支develop服务端要求JDK 17客户端模块 JDK 8构建工具为Maven 3.2.5。核心模块及其职责如下模块/目录职责api / client / client-basic面向客户端的 API、gRPC 定义与 SDKJava 8 兼容common共享工具、HTTP 客户端、通知中心NotifyCenter、执行器config配置管理服务端naming服务发现与注册服务端core核心服务端基础设施集群、分布式共识consistency基于 JRaft 的 CP 协议 自定义 Distro AP 协议auth认证与授权plugin / plugin-default-impl基于 Java SPI 的可扩展插件系统auth、visibility、datasource dialect、config change、encryption、trace、environment、control、AI pipeline、AI storage 等类型console / console-uiWeb UI 后端Spring Boot与前端Reactai / copilot / ai-registry-adaptorAI Agent 支持、Copilot 集成与 AI registry 适配器sys系统环境工具与 JVM 参数管理bootstrap / server服务端启动与聚合persistence数据持久化Derby、MySQL、PostgreSQL 等多数据库支持maintainer-client内部维护客户端lock分布式锁支持通信上Nacos 以gRPC 为主、HTTP/REST 兼容旧协议Protobuf 定义位于 api/src/main/proto/。平台核心能力包括服务发现、动态配置、动态 DNS、服务/元数据管理以及面向 AI 的 AI registryPrompt、MCP、A2A能力。构建与测试命令从零编译到提交检查AGENTS.md 提供了完整的 Maven 命令清单这是任何 Agent 在仓库中工作的第一步# 完整构建跳过测试 mvn -Prelease-nacos,!dev -Dmaven.test.skiptrue clean install -U # 运行全部单元测试 mvn test # 运行 standalone-server 集成测试 mvn -pl test/openapi-test -Pintegration-test -DskipTestsfalse verify mvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTestsfalse verify mvn -pl test/maintainer-sdk-test -Pmaintainer-sdk-integration-test -DskipTestsfalse verify # 提交前格式化代码 mvn spotless:apply # 提交前检查PR 前必须通过 mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests从根 pom.xml 可以看到这些检查工具的版本约定apache-rat-plugin0.12、maven-checkstyle-plugin3.6.0、spotbugs-maven-plugin4.8.6.2其中 SpotBugs 还配置了排除过滤器 style/spotbugs-exclude.xmlCheckstyle 通过checkstyle依赖加载 Nacos 自有的检查规则。这说明质量门禁不是默认配置而是项目定制的严格集合。Spotless 是格式化的唯一标准AGENTS.md 特别强调了一个容易踩坑的点不要把checkstyle:check、spotbugs:check或git diff --check当作 Spotless 的替代品。项目使用 Spotless 与自有 formatter其接受的格式可能与通用的空白检查结果不同。标准流程是先执行mvn spotless:apply对同一范围执行mvn spotless:check校验再运行相关的 compile/check/test 命令只有 Spotless 与相关校验全部通过后才允许提交。代码风格遵循 Alibaba Java 编码规范Nacos 代码风格遵循Alibaba Java Coding Guidelines配置文件包括Checkstyle 配置style/NacosCheckStyle.xmlIDEA 代码风格style/nacos-code-style-for-idea.xmlAGENTS.md 用一张表列出了 Agent 必须遵守的关键规则规则取值缩进4 空格基础缩进与 case 缩进均为 4 空格行长度最长100 字符由 Spotless Checkstyle 强制执行Star imports禁止——必须使用显式导入未使用的导入禁止JavadocAPI 方法必须书写豁免Override、Test、Before、After、BeforeClass、AfterClass、Parameterized、Parameters、Bean大括号所有if/else/for/while/do-while块必须使用大括号即使是单行Switch必须有default分支fall-through 必须注释说明命名方法/变量用camelCase类用PascalCase常量用UPPER_SNAKE_CASE缩写名称中最多 1 个连续大写字母例外VO许可证头每个新文件都必须携带每个新源文件必须包含 Apache License 2.0 头CI 通过apache-rat:check强制执行。标准模板如下/* * Copyright 1999-${year} Alibaba Group Holding Ltd. * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an AS IS BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */API 标准v3 API 的设计契约AGENTS.md 明确指出 Nacos v3 API 遵循严格约定Agent 生成 controller 代码时必须遵守。权威的 API 与 SDK 规范位于 specs/提供英文与简体中文双语版本规范层次从顶层设计nacos-design-spec.md、resource-model-spec.md逐级延伸到基础能力、领域能力Config/Naming/AI Registry/Core 运维/Console/分布式锁、接口规范HTTP/gRPC/SDK、扩展模型、安全模型与测试模型。URL 路径模式API 类型基础路径用途示例Open API/v3/client/{module}/...面向客户端的操作/v3/client/ns/instanceAdmin API/v3/admin/{module}/...管理操作/v3/admin/ns/serviceConsole API/v3/console/{module}/...Web 控制台操作/v3/console/cs/configAuth API/v3/auth/{resource}/...插件提供的鉴权操作/v3/auth/user模块缩写模块缩写范围Config Servicecs配置管理Naming Servicens服务发现Corecore集群、命名空间管理AIaiAI 资源管理Pluginplugin插件管理需要注意的是Auth API/v3/auth/user、/v3/auth/role、/v3/auth/permission定义在plugin-default-impl模块中而不是 core 模块。HTTP 方法语义方法用途幂等GET查询 / 检索是POST创建 / 注册否PUT更新 / 修改是DELETE删除 / 注销是响应格式与鉴权所有响应必须包装在com.alibaba.nacos.api.model.v2.ResultT源码见 Result.java中{ code: 0, message: success, data: { } }所有接口必须添加Secured注解定义于 Secured.javaSecured(action ActionTypes.READ, // READ 或 WRITE signType SignType.CONFIG, // CONFIG、NAMING 或 CONSOLE apiType ApiType.ADMIN_API) // OPEN_API、ADMIN_API 或 CONSOLE_APIController 示例AGENTS.md 给出了标准的 v3 Admin API Controller 模板融合了响应包装、鉴权注解与表单校验import com.alibaba.nacos.api.model.v2.Result; import com.alibaba.nacos.auth.annotation.Secured; import com.alibaba.nacos.plugin.auth.constant.ActionTypes; import com.alibaba.nacos.plugin.auth.constant.SignType; import com.alibaba.nacos.api.common.ApiType; RestController RequestMapping(/v3/admin/ns/service) public class ServiceControllerV3 { PostMapping Secured(action ActionTypes.WRITE, apiType ApiType.ADMIN_API) public ResultString create(ServiceForm serviceForm) throws Exception { serviceForm.validate(); // business logic ... return Result.success(ok); } GetMapping(/list) Secured(action ActionTypes.READ, apiType ApiType.ADMIN_API) public ResultPageServiceDetailInfo list(ServiceListForm serviceListForm) throws NacosException { serviceListForm.validate(); // business logic ... return Result.success(result); } }这个模板值得细读serviceForm.validate()把参数校验前移到入口Result.success(...)保证统一的响应结构Secured声明式地接入鉴权体系。从API_TEST_COVERAGE.md的统计看这套约定在测试侧形成了闭环——Client OpenAPI 场景行 11 行、Admin API 38 行、Console API 29 行严格覆盖率分别为 90.91%、81.58%、82.76%有效覆盖率更高每行对应预期能力 / 边界校验 / 异常处理三类场景中的若干种。集成测试的完整处理流程对每个 HTTP API 的新增/修改/删除/废弃AGENTS.md 要求在变更完成前处理 test/openapi-test阅读受影响的 controller、form/request 模型、校验器、service 路径、响应模型、异常处理及匹配的 spec构建或更新场景矩阵覆盖预期能力、边界/校验行为与异常/错误处理为变更的契约新增、更新或删除 API IT 用例目标是API 场景覆盖而非行/分支覆盖更新 test/openapi-test/API_TEST_COVERAGE.md 及对应的*_API_TEST_SCENARIOS.md文档若独立 IT 难以覆盖功能成功路径至少覆盖边界与错误场景并记录未覆盖路径。Java SDK 公共契约变更同样如此且有一条特别约束SDK IT 必须作为外部客户端测试对独立的 Nacos server 运行禁止在测试类内部启动 Spring 或 Nacos。从JAVA_SDK_IT_COVERAGE.md可以看到AiServiceJavaSdkITCase、LockServiceJavaSdkITCase、AiTransportResourceMatrixJavaSdkITCase等测试类如何在真实 standalone server 上验证工厂创建、发布/订阅/轮询、重连重放redo等端到端行为。Java 版本目标服务端与客户端的边界AGENTS.md 明确了 Java 版本的双轨策略服务端模块config、naming、core、console 等Java 17客户端/API/插件模块api、client、pluginJava 8——修改时务必保证向后兼容。这条边界对 Agent 尤其重要在客户端模块引入 Java 9 特性、在服务端模块过度保守都是错误的兼容性约束还进一步体现在 compatibility-deprecation-spec.md 等规范中。PR 约定与提交前检查清单所有 PR 必须面向develop分支标题格式为[ISSUE #14122] Add JVM --add-opens options for JDK 17 compatibility即[ISSUE #编号] 变更描述的结构便于在提交历史上直接追溯到关联 issue。提交前检查清单mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests mvn clean install mvn clean test-compile failsafe:integration-test这条链路的含义是先做静态质量与格式化门禁再确保全量编译与安装通过最后执行 failsafe 集成测试——与 AGENTS.md 开头Pre-submission checks (MUST pass before PR)的定位一致。安全漏洞走专用渠道AGENTS.md 特别规定不要通过 GitHub Issues 报告安全漏洞应使用阿里安全响应中心ASRC渠道。这是大型开源项目处理安全问题的标准做法——漏洞详情在修复前需要保密避免公开讨论造成 0-day 风险。给 AI Agent 的实操 Checklist综合 AGENTS.md 全文一个 AI Agent 在 Nacos 仓库贡献代码的最小合规路径是阅读specs/ 中与改动相关的规范英文/中文双语齐全确认现有契约讨论在 issue 中与维护者确认实现方向若改动涉及规范覆盖的行为先提交 spec/design PR编码遵守 4 空格缩进、100 字符行宽、显式导入、强制大括号、Secured鉴权、ResultT响应包装格式化mvn spotless:apply后执行mvn spotless:check这是格式化的唯一标准测试改动 HTTP API 更新 test/openapi-test改动 Java SDK 更新 test/java-sdk-test同步场景矩阵与覆盖注册表检查执行mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests全套门禁提交为 AI 生成内容添加Assisted-by:trailerPR 面向develop分支标题遵循[ISSUE #xxx]格式。这套流程的本质是把人写代码时靠经验与评审约束的过程转译成 Agent 可以逐条执行、机器可以逐项校验的工程规范。无论你是想为 Nacos 提交第一个修复还是评估如何在自己的开源项目中建立 AI 协作规范AGENTS.md 都是一份可以直接参照的模板。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考