{"owner":"alibaba","repo":"nacos","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when working with the Nacos repository. For human contributors, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## AI Contribution Guidelines\n\n- **Do NOT post AI-generated comments** on issues or PRs. Discussions are for humans only.\n- **Discuss before implementing**: Ensure the implementation direction is agreed upon with maintainers in the issue comments before starting work.\n- **Spec-first coding is mandatory**: Before changing behavior, APIs, SDKs,\n  plugins, storage, runtime flow, or domain semantics, AI agents MUST read the\n  relevant specs under [`specs/`](./specs/README.md) and treat them as the rule\n  source for the implementation.\n- **Discuss spec-impacting changes before coding**: If a change touches behavior\n  covered by an existing spec, or exposes a gap between the code and the spec,\n  AI agents MUST discuss the implementation direction and the required spec\n  update with maintainers before starting the code change.\n- **Update specs with the design**: Any design proposal that changes or\n  clarifies spec-covered behavior MUST include the corresponding spec updates\n  in the same change set. When the design is large or controversial, prefer a\n  spec/design-only PR first, then follow with implementation PRs.\n- **API IT impact comes first**: Before adding, changing, deleting, or\n  deprecating any HTTP API, AI agents MUST analyze the affected\n  `test/openapi-test` coverage and update the API IT scenario matrix, test\n  cases, and coverage registry in the same change set. If the functional path\n  cannot be exercised in standalone IT, cover boundary/error scenarios and\n  document the reason.\n- **Java SDK IT impact comes first**: Before adding, changing, deleting, or\n  deprecating any public Java SDK interface, factory, model, listener behavior,\n  lifecycle behavior, or exception mapping, AI agents MUST analyze and update\n  `test/java-sdk-test` coverage, including scenario documentation. If the\n  end-to-end success path is impractical, cover SDK parameter validation,\n  boundary behavior, and controlled exceptions.\n- **Disclose AI usage**: When a significant part of a commit is AI-generated, add a trailer to your commit message:\n  ```\n  Assisted-by: Claude Code\n  ```\n- **Follow [CONTRIBUTING.md](./CONTRIBUTING.md)** for all contribution processes.\n\n## Repository Overview\n\nNacos (Dynamic Naming and Configuration Service) is an easy-to-use platform designed for dynamic service discovery, configuration management, and AI agent management. It helps you build cloud-native applications and AI Agent applications easily. Key capabilities: service discovery, dynamic configuration, dynamic DNS service, service/metadata management, and AI registry (Prompt, MCP, A2A).\n\n**Current Version**: 3.2.1-SNAPSHOT | **Main Branch**: `develop` | **Java**: JDK 17+ (client modules: JDK 8+) | **Build**: Maven 3.2.5+\n\n## Core Architecture\n\nKey modules and their roles:\n\n- **api / client / client-basic**: Client-facing APIs, gRPC definitions, SDK (Java 8 compatible)\n- **common**: Shared utilities, HTTP client, notify center, executor\n- **config**: Configuration management server\n- **naming**: Service discovery and registration server\n- **core**: Core server infrastructure (cluster, distributed consensus)\n- **consistency**: JRaft-based CP protocol + custom Distro AP protocol\n- **auth**: Authentication and authorization\n- **plugin / plugin-default-impl**: Extensible plugin system (Java SPI). Types: auth, visibility, datasource dialect, config change, encryption, trace, environment, control, AI pipeline, AI storage\n- **console / console-ui**: Web UI backend (Spring Boot) and frontend (React)\n- **ai / copilot / ai-registry-adaptor**: AI Agent support, Copilot integration, and AI registry adaptor\n- **sys**: System environment utilities and JVM parameter management\n- **bootstrap / server**: Server startup and aggregation\n- **persistence**: Data persistence with multi-database support (Derby, MySQL, PostgreSQL)\n- **maintainer-client**: Internal maintenance client\n- **lock**: Distributed lock support\n\nCommunication: **gRPC** (primary) + **HTTP/REST** (legacy compatibility). Protobuf definitions in `api/src/main/proto/`.\n\n## Build & Test Commands\n\n```bash\n# Full build (skip tests)\nmvn '-Prelease-nacos,!dev' -Dmaven.test.skip=true clean install -U\n\n# Run all unit tests\nmvn test\n\n# Run standalone-server integration tests\nmvn -pl test/openapi-test -Pintegration-test -DskipTests=false verify\nmvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTests=false verify\nmvn -pl test/maintainer-sdk-test -Pmaintainer-sdk-integration-test -DskipTests=false verify\n\n# Format code (run before commit)\nmvn spotless:apply\n\n# Pre-submission checks (MUST pass before PR)\nmvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests\n```\n\n### Mandatory Formatting Before Commit\n\nBefore committing Java code or tests, AI agents MUST run Spotless for the\naffected module or nearest aggregator:\n\n1. Run `mvn spotless:apply` first.\n2. Run `mvn spotless:check` for the same scope.\n3. Then run the relevant compile/check/test command.\n4. Commit only after Spotless and the relevant validation pass.\n\nDo not rely on `checkstyle:check`, `spotbugs:check`, or `git diff --check` as a\nsubstitute for Spotless. Spotless uses the project formatter and may accept\nformatting that generic whitespace checks report differently.\n\n## Code Style\n\nFollows **Alibaba Java Coding Guidelines**.\n\n- Checkstyle config: [`style/NacosCheckStyle.xml`](style/NacosCheckStyle.xml)\n- IDEA code style: [`style/nacos-code-style-for-idea.xml`](style/nacos-code-style-for-idea.xml)\n\n### Key Rules for AI Agents\n\n| Rule | Value |\n|------|-------|\n| Indentation | **4 spaces** (basic offset), 4 spaces (case indent) |\n| Line length | **100 characters** max (enforced by Spotless + Checkstyle) |\n| Star imports | **Forbidden** — always use explicit imports |\n| Unused imports | **Forbidden** |\n| Javadoc | Required for API methods (exemptions: `@Override`, `@Test`, `@Before`, `@After`, `@BeforeClass`, `@AfterClass`, `@Parameterized`, `@Parameters`, `@Bean`) |\n| Braces | Required for all `if/else/for/while/do-while` blocks, even single-line |\n| Switch | Must have `default` case; fall-through must be commented |\n| Naming | `camelCase` for methods/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants |\n| Abbreviations | Max 1 consecutive capital letter in names (exception: `VO`) |\n\n### License Header\n\nEvery new source file **must** include the Apache License 2.0 header. CI enforces this via `apache-rat:check`.\n\n```java\n/*\n * Copyright 1999-${year} Alibaba Group Holding Ltd.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *      http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n```\n\n## API Standards\n\nNacos v3 APIs follow strict conventions. AI agents **must** comply with these\nstandards when generating controller code.\n\nAuthoritative API and SDK specs live under [`specs/`](./specs/README.md).\nBefore coding any API, SDK, plugin, storage, runtime, or domain change, AI\nagents **MUST** consult the relevant specs below. If the intended behavior\ndiffers from the existing spec, do not silently implement the code first:\ndiscuss the change with maintainers and update the affected specs as part of\nthe design. For broad or uncertain changes, submit a spec/design PR first so\nthe contract is reviewed before implementation.\n\nEnglish:\n\n- Design foundation:\n  [Nacos Design Spec](./specs/en/design/nacos-design-spec.md),\n  [Resource Model Spec](./specs/en/design/resource-model-spec.md),\n  [Compatibility And Deprecation Spec](./specs/en/design/compatibility-deprecation-spec.md),\n  [Foundation Capabilities Spec](./specs/en/design/foundation-capabilities-spec.md),\n  [Server Lifecycle And Environment Configuration Spec](./specs/en/design/foundation-server-lifecycle-env-spec.md),\n  [Cluster Membership Spec](./specs/en/design/foundation-cluster-membership-spec.md),\n  [Remote Connection Lifecycle Spec](./specs/en/design/foundation-remote-connection-spec.md),\n  [Request Filtering And Runtime Context Spec](./specs/en/design/foundation-request-context-spec.md),\n  [Internal RPC And Cluster Request Spec](./specs/en/design/foundation-internal-rpc-spec.md),\n  [AP Consistency Spec](./specs/en/design/foundation-ap-consistency-spec.md),\n  [CP Consistency Spec](./specs/en/design/foundation-cp-consistency-spec.md),\n  [Persistence And Dump Spec](./specs/en/design/foundation-persistence-dump-spec.md),\n  [Task Execution Spec](./specs/en/design/foundation-task-execution-spec.md),\n  [Event Dispatch And NotifyCenter Spec](./specs/en/design/foundation-event-dispatch-spec.md),\n  [Observability Hooks Spec](./specs/en/design/foundation-observability-hooks-spec.md),\n  [Core Capabilities Spec](./specs/en/design/core-capabilities-spec.md)\n- Interface model:\n  [HTTP API Spec](./specs/en/http-api/api-spec.md),\n  [Authorization Spec](./specs/en/http-api/authorization-spec.md),\n  [Response And Error Spec](./specs/en/http-api/response-error-spec.md),\n  [V3 API Surface](./specs/en/http-api/v3-api-surface.md),\n  [gRPC API Spec](./specs/en/grpc-api/api-spec.md),\n  [SDK Spec](./specs/en/sdk/sdk-spec.md),\n  [Java SDK Implementation Spec](./specs/en/sdk/sdk-java-impl-spec.md),\n  [Client Runtime Spec](./specs/en/client/client-runtime-spec.md),\n  [Client Connection And Failover Spec](./specs/en/client/client-connection-failover-spec.md),\n  [Client Ability Negotiation Spec](./specs/en/client/client-ability-negotiation-spec.md),\n  [Client Local Cache And Redo Spec](./specs/en/client/client-local-cache-redo-spec.md),\n  [Runtime Push And Reconnect Spec](./specs/en/client/runtime-push-reconnect-spec.md)\n- Domain model:\n  [Config Spec](./specs/en/config/config-spec.md),\n  [Config Resource Spec](./specs/en/config/config-resource-spec.md),\n  [Config Publish And Query Spec](./specs/en/config/config-publish-query-spec.md),\n  [Config Listener And Watch Spec](./specs/en/config/config-listener-watch-spec.md),\n  [Config Gray Release Spec](./specs/en/config/config-gray-release-spec.md),\n  [Config Persistence And History Spec](./specs/en/config/config-persistence-history-spec.md),\n  [Config Consistency, Dump, And Visibility Spec](./specs/en/config/config-consistency-dump-visibility-spec.md),\n  [Config Capacity And Ops Spec](./specs/en/config/config-capacity-ops-spec.md),\n  [Naming Spec](./specs/en/naming/naming-spec.md),\n  [Naming Resource Spec](./specs/en/naming/naming-resource-spec.md),\n  [Naming Instance Lifecycle Spec](./specs/en/naming/naming-instance-lifecycle-spec.md),\n  [Naming Discovery And Subscription Spec](./specs/en/naming/naming-discovery-subscription-spec.md),\n  [Naming Health And Protection Spec](./specs/en/naming/naming-health-protection-spec.md),\n  [Naming Metadata And Selector Spec](./specs/en/naming/naming-metadata-selector-spec.md),\n  [Naming Consistency And Client State Spec](./specs/en/naming/naming-consistency-client-spec.md),\n  [Naming Ephemeral Distro Consistency Spec](./specs/en/naming/naming-ephemeral-distro-consistency-spec.md),\n  [Naming Persistent CP Consistency Spec](./specs/en/naming/naming-persistent-cp-consistency-spec.md),\n  [Naming Ops Spec](./specs/en/naming/naming-ops-spec.md),\n  [AI Registry Spec](./specs/en/ai/ai-registry-spec.md),\n  [AI Resource Model Spec](./specs/en/ai/ai-resource-model-spec.md),\n  [AI Resource Lifecycle Spec](./specs/en/ai/ai-resource-lifecycle-spec.md),\n  [AI Registry Adaptor Spec](./specs/en/ai/ai-registry-adaptor-spec.md),\n  [Agent Management Spec](./specs/en/ai/agent-management-spec.md),\n  [Remote Agent Discovery Protocol Spec](./specs/en/ai/rad-protocol-spec.md),\n  [Agent API Spec](./specs/en/ai/agent-api-spec.md),\n  [Agent Storage Spec](./specs/en/ai/agent-storage-spec.md),\n  [MCP Server Spec](./specs/en/ai/mcp-server-spec.md),\n  [A2A Agent Spec](./specs/en/ai/a2a-agent-spec.md),\n  [Prompt Spec](./specs/en/ai/prompt-spec.md),\n  [Skill Spec](./specs/en/ai/skill-spec.md),\n  [AgentSpec Spec](./specs/en/ai/agentspec-spec.md),\n  [Core Operations Spec](./specs/en/core/core-operations-spec.md),\n  [Console Spec](./specs/en/console/console-spec.md),\n  [Distributed Lock Spec](./specs/en/lock/lock-spec.md)\n- Extension model:\n  [Integration And Adapter Spec](./specs/en/integration/integration-adapter-spec.md),\n  [Plugin Specs](./specs/en/plugin/README.md)\n- Security model:\n  [Auth And Permission Spec](./specs/en/auth/auth-permission-spec.md),\n  [Auth Plugin Spec](./specs/en/auth/auth-plugin-spec.md),\n  [RAM Auth Plugin Spec](./specs/en/auth/ram-auth-plugin-spec.md),\n  [OIDC Auth Plugin Spec](./specs/en/auth/oidc-auth-plugin-spec.md),\n  [Visibility Plugin Spec](./specs/en/auth/visibility-plugin-spec.md),\n  [Default Auth Plugin Implementation Spec](./specs/en/auth/default-auth-plugin-spec.md)\n- Testing model:\n  [API Integration Test Spec](./specs/en/testing/api-integration-test-spec.md),\n  [Java SDK Integration Test Spec](./specs/en/testing/java-sdk-integration-test-spec.md)\n- Shared schemas:\n  [JSON Schema Index](./specs/schemas/README.md)\n\nSimplified Chinese:\n\n- 设计基础：\n  [Nacos 设计规范](./specs/zh-cn/design/nacos-design-spec.md)，\n  [资源模型规范](./specs/zh-cn/design/resource-model-spec.md)，\n  [兼容与废弃策略规范](./specs/zh-cn/design/compatibility-deprecation-spec.md)，\n  [基础能力规范](./specs/zh-cn/design/foundation-capabilities-spec.md)，\n  [服务端生命周期与环境配置规范](./specs/zh-cn/design/foundation-server-lifecycle-env-spec.md)，\n  [集群成员规范](./specs/zh-cn/design/foundation-cluster-membership-spec.md)，\n  [远程连接生命周期规范](./specs/zh-cn/design/foundation-remote-connection-spec.md)，\n  [请求过滤与运行时上下文规范](./specs/zh-cn/design/foundation-request-context-spec.md)，\n  [内部 RPC 与集群请求规范](./specs/zh-cn/design/foundation-internal-rpc-spec.md)，\n  [AP 一致性规范](./specs/zh-cn/design/foundation-ap-consistency-spec.md)，\n  [CP 一致性规范](./specs/zh-cn/design/foundation-cp-consistency-spec.md)，\n  [持久化与 Dump 规范](./specs/zh-cn/design/foundation-persistence-dump-spec.md)，\n  [任务执行规范](./specs/zh-cn/design/foundation-task-execution-spec.md)，\n  [事件分发与 NotifyCenter 规范](./specs/zh-cn/design/foundation-event-dispatch-spec.md)，\n  [可观测钩子规范](./specs/zh-cn/design/foundation-observability-hooks-spec.md)，\n  [核心功能规范](./specs/zh-cn/design/core-capabilities-spec.md)\n- 接口模型：\n  [HTTP API 规范](./specs/zh-cn/http-api/api-spec.md)，\n  [鉴权规范](./specs/zh-cn/http-api/authorization-spec.md)，\n  [响应与错误规范](./specs/zh-cn/http-api/response-error-spec.md)，\n  [V3 API 范围](./specs/zh-cn/http-api/v3-api-surface.md)，\n  [gRPC API 规范](./specs/zh-cn/grpc-api/api-spec.md)，\n  [SDK 规范](./specs/zh-cn/sdk/sdk-spec.md)，\n  [Java SDK 实现规范](./specs/zh-cn/sdk/sdk-java-impl-spec.md)，\n  [客户端运行时规范](./specs/zh-cn/client/client-runtime-spec.md)，\n  [客户端连接与故障切换规范](./specs/zh-cn/client/client-connection-failover-spec.md)，\n  [客户端能力协商规范](./specs/zh-cn/client/client-ability-negotiation-spec.md)，\n  [客户端本地缓存与 Redo 规范](./specs/zh-cn/client/client-local-cache-redo-spec.md)，\n  [运行时推送与重连规范](./specs/zh-cn/client/runtime-push-reconnect-spec.md)\n- 领域模型：\n  [Config 规范](./specs/zh-cn/config/config-spec.md)，\n  [Config 资源规范](./specs/zh-cn/config/config-resource-spec.md)，\n  [Config 发布与查询规范](./specs/zh-cn/config/config-publish-query-spec.md)，\n  [Config 监听与 Watch 规范](./specs/zh-cn/config/config-listener-watch-spec.md)，\n  [Config 灰度发布规范](./specs/zh-cn/config/config-gray-release-spec.md)，\n  [Config 持久化与历史规范](./specs/zh-cn/config/config-persistence-history-spec.md)，\n  [Config 一致性、Dump 与可见性规范](./specs/zh-cn/config/config-consistency-dump-visibility-spec.md)，\n  [Config 容量与运维规范](./specs/zh-cn/config/config-capacity-ops-spec.md)，\n  [Naming 规范](./specs/zh-cn/naming/naming-spec.md)，\n  [Naming 资源规范](./specs/zh-cn/naming/naming-resource-spec.md)，\n  [Naming 实例生命周期规范](./specs/zh-cn/naming/naming-instance-lifecycle-spec.md)，\n  [Naming 发现与订阅规范](./specs/zh-cn/naming/naming-discovery-subscription-spec.md)，\n  [Naming 健康检查与保护规范](./specs/zh-cn/naming/naming-health-protection-spec.md)，\n  [Naming 元数据与 Selector 规范](./specs/zh-cn/naming/naming-metadata-selector-spec.md)，\n  [Naming 一致性与客户端状态规范](./specs/zh-cn/naming/naming-consistency-client-spec.md)，\n  [Naming 临时服务 Distro 一致性规范](./specs/zh-cn/naming/naming-ephemeral-distro-consistency-spec.md)，\n  [Naming 持久服务 CP 一致性规范](./specs/zh-cn/naming/naming-persistent-cp-consistency-spec.md)，\n  [Naming 运维规范](./specs/zh-cn/naming/naming-ops-spec.md)，\n  [AI Registry 规范](./specs/zh-cn/ai/ai-registry-spec.md)，\n  [AI 资源模型规范](./specs/zh-cn/ai/ai-resource-model-spec.md)，\n  [AI 资源生命周期规范](./specs/zh-cn/ai/ai-resource-lifecycle-spec.md)，\n  [AI Registry 适配器规范](./specs/zh-cn/ai/ai-registry-adaptor-spec.md)，\n  [Agent 管理规范](./specs/zh-cn/ai/agent-management-spec.md)，\n  [Remote Agent Discovery 协议规范](./specs/zh-cn/ai/rad-protocol-spec.md)，\n  [Agent API 规范](./specs/zh-cn/ai/agent-api-spec.md)，\n  [Agent 存储规范](./specs/zh-cn/ai/agent-storage-spec.md)，\n  [MCP Server 规范](./specs/zh-cn/ai/mcp-server-spec.md)，\n  [A2A Agent 规范](./specs/zh-cn/ai/a2a-agent-spec.md)，\n  [Prompt 规范](./specs/zh-cn/ai/prompt-spec.md)，\n  [Skill 规范](./specs/zh-cn/ai/skill-spec.md)，\n  [AgentSpec 规范](./specs/zh-cn/ai/agentspec-spec.md)，\n  [Core 运维规范](./specs/zh-cn/core/core-operations-spec.md)，\n  [Console 规范](./specs/zh-cn/console/console-spec.md)，\n  [分布式锁规范](./specs/zh-cn/lock/lock-spec.md)\n- 扩展模型：\n  [集成与适配器规范](./specs/zh-cn/integration/integration-adapter-spec.md)，\n  [插件规范](./specs/zh-cn/plugin/README.md)\n- 安全模型：\n  [鉴权与权限规范](./specs/zh-cn/auth/auth-permission-spec.md)，\n  [鉴权插件规范](./specs/zh-cn/auth/auth-plugin-spec.md)，\n  [RAM 鉴权插件规范](./specs/zh-cn/auth/ram-auth-plugin-spec.md)，\n  [OIDC 鉴权插件规范](./specs/zh-cn/auth/oidc-auth-plugin-spec.md)，\n  [可见性插件规范](./specs/zh-cn/auth/visibility-plugin-spec.md)，\n  [默认鉴权插件实现规范](./specs/zh-cn/auth/default-auth-plugin-spec.md)\n- 测试模型：\n  [API 集成测试规范](./specs/zh-cn/testing/api-integration-test-spec.md)，\n  [Java SDK 集成测试规范](./specs/zh-cn/testing/java-sdk-integration-test-spec.md)\n- 共享 Schema：\n  [JSON Schema 索引](./specs/schemas/README.md)\n\nThis section is a quick implementation checklist for agents. If it conflicts\nwith the specs, follow the specs and update this checklist.\n\n### URL Path Patterns\n\n| API Type | Base Path | Purpose | Example |\n|----------|-----------|---------|---------|\n| **Open API** | `/v3/client/{module}/...` | Client-facing operations | `/v3/client/ns/instance` |\n| **Admin API** | `/v3/admin/{module}/...` | Administrative operations | `/v3/admin/ns/service` |\n| **Console API** | `/v3/console/{module}/...` | Web console operations | `/v3/console/cs/config` |\n| **Auth API** | `/v3/auth/{resource}/...` | Plugin-provided auth operations | `/v3/auth/user` |\n\n### Module Names\n\n| Module | Abbreviation | Scope |\n|--------|-------------|-------|\n| Config Service | `cs` | Configuration management |\n| Naming Service | `ns` | Service discovery |\n| Core | `core` | Cluster, namespace management |\n| AI | `ai` | AI resource management |\n| Plugin | `plugin` | Plugin management |\n\n> **Note**: Auth APIs (`/v3/auth/user`, `/v3/auth/role`, `/v3/auth/permission`) are defined in `plugin-default-impl` module, not in core.\n\n### HTTP Method Semantics\n\n| Method | Usage | Idempotent |\n|--------|-------|:----------:|\n| `GET` | Query / Retrieve | Yes |\n| `POST` | Create / Register | No |\n| `PUT` | Update / Modify | Yes |\n| `DELETE` | Remove / Deregister | Yes |\n\n### Response Format\n\n**Always** wrap responses in `com.alibaba.nacos.api.model.v2.Result<T>`:\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"success\",\n  \"data\": { }\n}\n```\n\n### Authentication\n\n**Always** add `@Secured` annotation (`com.alibaba.nacos.auth.annotation.Secured`):\n\n```java\n@Secured(action = ActionTypes.READ,       // READ or WRITE\n         signType = SignType.CONFIG,       // CONFIG, NAMING, or CONSOLE\n         apiType = ApiType.ADMIN_API)      // OPEN_API, ADMIN_API, or CONSOLE_API\n```\n\n### API Integration Tests\n\nFor every HTTP API addition, modification, deletion, or deprecation, handle\n`test/openapi-test` before the API change is considered complete:\n\n1. Read the affected controller, form/request model, validators, service path,\n   response model, exception handling, and matching specs.\n2. Build or update the scenario matrix for expected capability,\n   boundary/validation behavior, and exception/error handling.\n3. Add, update, or remove API IT cases for the changed contract. The goal is API\n   scenario coverage, not line or branch coverage.\n4. Update `test/openapi-test/API_TEST_COVERAGE.md` and the matching\n   `*_API_TEST_SCENARIOS.md` document.\n5. If the functional success path is hard to exercise in standalone IT, at\n   least cover boundary and error scenarios and document the uncovered path.\n\n### Java SDK Integration Tests\n\nFor every Java SDK public contract change, handle `test/java-sdk-test` before\nthe SDK change is considered complete:\n\n1. Read the public interface, implementation, request/response model, listener\n   path, lifecycle code, exception mapping, and matching SDK/client specs.\n2. Build or update the scenario matrix for factory/lifecycle behavior,\n   expected capability, boundary/validation behavior, listener/subscription\n   behavior, and exception handling.\n3. Add, update, or remove Java SDK IT cases for the changed SDK contract. Assert\n   SDK return values, callbacks, remote side effects, and typed exceptions.\n4. Update `test/java-sdk-test/JAVA_SDK_IT_COVERAGE.md`.\n5. Keep SDK ITs as external-client tests against a standalone Nacos server; do\n   not start Spring or Nacos inside the test class.\n\n### Controller Example\n\n```java\nimport com.alibaba.nacos.api.model.v2.Result;\nimport com.alibaba.nacos.auth.annotation.Secured;\nimport com.alibaba.nacos.plugin.auth.constant.ActionTypes;\nimport com.alibaba.nacos.plugin.auth.constant.SignType;\nimport com.alibaba.nacos.api.common.ApiType;\n\n@RestController\n@RequestMapping(\"/v3/admin/ns/service\")\npublic class ServiceControllerV3 {\n\n    @PostMapping\n    @Secured(action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)\n    public Result<String> create(ServiceForm serviceForm) throws Exception {\n        serviceForm.validate();\n        // business logic ...\n        return Result.success(\"ok\");\n    }\n\n    @GetMapping(\"/list\")\n    @Secured(action = ActionTypes.READ, apiType = ApiType.ADMIN_API)\n    public Result<Page<ServiceDetailInfo>> list(ServiceListForm serviceListForm) throws NacosException {\n        serviceListForm.validate();\n        // business logic ...\n        return Result.success(result);\n    }\n}\n```\n\n## Java Version Targeting\n\n- **Server modules** (config, naming, core, console, etc.): Java 17+\n- **Client/API/Plugin modules** (api, client, plugin): Java 8+ — ensure backwards compatibility when modifying\n\n## PR Convention\n\nAll PRs must target the `develop` branch. Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md).\n\n**Title format**: `[ISSUE #14122] Add JVM --add-opens options for JDK 17+ compatibility`\n\n**Pre-submission checklist**:\n```bash\nmvn -B clean package apache-rat:check spotbugs:check -DskipTests\nmvn clean install\nmvn clean test-compile failsafe:integration-test\n```\n\n## Security Vulnerabilities\n\nDo NOT report security vulnerabilities via GitHub Issues. Use [ASRC (Alibaba Security Response Center)](https://security.alibaba.com) instead.\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when working with the Nacos repository. For human contributors, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## AI Contribution Guidelines\n\n- **Do NOT post AI-generated comments** on issues or PRs. Discussions are for humans only.\n- **Discuss before implementing**: Ensure the implementation direction is agreed upon with maintainers in the issue comments before starting work.\n- **Spec-first coding is mandatory**: Before changing behavior, APIs, SDKs,\n  plugins, storage, runtime flow, or domain semantics, AI agents MUST read the\n  relevant specs under [`specs/`](./specs/README.md) and treat them as the rule\n  source for the implementation.\n- **Discuss spec-impacting changes before coding**: If a change touches behavior\n  covered by an existing spec, or exposes a gap between the code and the spec,\n  AI agents MUST discuss the implementation direction and the required spec\n  update with maintainers before starting the code change.\n- **Update specs with the design**: Any design proposal that changes or\n  clarifies spec-covered behavior MUST include the corresponding spec updates\n  in the same change set. When the design is large or controversial, prefer a\n  spec/design-only PR first, then follow with implementation PRs.\n- **API IT impact comes first**: Before adding, changing, deleting, or\n  deprecating any HTTP API, AI agents MUST analyze the affected\n  `test/openapi-test` coverage and update the API IT scenario matrix, test\n  cases, and coverage registry in the same change set. If the functional path\n  cannot be exercised in standalone IT, cover boundary/error scenarios and\n  document the reason.\n- **Java SDK IT impact comes first**: Before adding, changing, deleting, or\n  deprecating any public Java SDK interface, factory, model, listener behavior,\n  lifecycle behavior, or exception mapping, AI agents MUST analyze and update\n  `test/java-sdk-test` coverage, including scenario documentation. If the\n  end-to-end success path is impractical, cover SDK parameter validation,\n  boundary behavior, and controlled exceptions.\n- **Disclose AI usage**: When a significant part of a commit is AI-generated, add a trailer to your commit message:\n  ```\n  Assisted-by: Claude Code\n  ```\n- **Follow [CONTRIBUTING.md](./CONTRIBUTING.md)** for all contribution processes.\n\n## Repository Overview\n\nNacos (Dynamic Naming and Configuration Service) is an easy-to-use platform designed for dynamic service discovery, configuration management, and AI agent management. It helps you build cloud-native applications and AI Agent applications easily. Key capabilities: service discovery, dynamic configuration, dynamic DNS service, service/metadata management, and AI registry (Prompt, MCP, A2A).\n\n**Current Version**: 3.2.1-SNAPSHOT | **Main Branch**: `develop` | **Java**: JDK 17+ (client modules: JDK 8+) | **Build**: Maven 3.2.5+\n\n## Core Architecture\n\nKey modules and their roles:\n\n- **api / client / client-basic**: Client-facing APIs, gRPC definitions, SDK (Java 8 compatible)\n- **common**: Shared utilities, HTTP client, notify center, executor\n- **config**: Configuration management server\n- **naming**: Service discovery and registration server\n- **core**: Core server infrastructure (cluster, distributed consensus)\n- **consistency**: JRaft-based CP protocol + custom Distro AP protocol\n- **auth**: Authentication and authorization\n- **plugin / plugin-default-impl**: Extensible plugin system (Java SPI). Types: auth, visibility, datasource dialect, config change, encryption, trace, environment, control, AI pipeline, AI storage\n- **console / console-ui**: Web UI backend (Spring Boot) and frontend (React)\n- **ai / copilot / ai-registry-adaptor**: AI Agent support, Copilot integration, and AI registry adaptor\n- **sys**: System environment utilities and JVM parameter management\n- **bootstrap / server**: Server startup and aggregation\n- **persistence**: Data persistence with multi-database support (Derby, MySQL, PostgreSQL)\n- **maintainer-client**: Internal maintenance client\n- **lock**: Distributed lock support\n\nCommunication: **gRPC** (primary) + **HTTP/REST** (legacy compatibility). Protobuf definitions in `api/src/main/proto/`.\n\n## Build & Test Commands\n\n```bash\n# Full build (skip tests)\nmvn '-Prelease-nacos,!dev' -Dmaven.test.skip=true clean install -U\n\n# Run all unit tests\nmvn test\n\n# Run standalone-server integration tests\nmvn -pl test/openapi-test -Pintegration-test -DskipTests=false verify\nmvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTests=false verify\nmvn -pl test/maintainer-sdk-test -Pmaintainer-sdk-integration-test -DskipTests=false verify\n\n# Format code (run before commit)\nmvn spotless:apply\n\n# Pre-submission checks (MUST pass before PR)\nmvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests\n```\n\n### Mandatory Formatting Before Commit\n\nBefore committing Java code or tests, AI agents MUST run Spotless for the\naffected module or nearest aggregator:\n\n1. Run `mvn spotless:apply` first.\n2. Run `mvn spotless:check` for the same scope.\n3. Then run the relevant compile/check/test command.\n4. Commit only after Spotless and the relevant validation pass.\n\nDo not rely on `checkstyle:check`, `spotbugs:check`, or `git diff --check` as a\nsubstitute for Spotless. Spotless uses the project formatter and may accept\nformatting that generic whitespace checks report differently.\n\n## Code Style\n\nFollows **Alibaba Java Coding Guidelines**.\n\n- Checkstyle config: [`style/NacosCheckStyle.xml`](style/NacosCheckStyle.xml)\n- IDEA code style: [`style/nacos-code-style-for-idea.xml`](style/nacos-code-style-for-idea.xml)\n\n### Key Rules for AI Agents\n\n| Rule | Value |\n|------|-------|\n| Indentation | **4 spaces** (basic offset), 4 spaces (case indent) |\n| Line length | **100 characters** max (enforced by Spotless + Checkstyle) |\n| Star imports | **Forbidden** — always use explicit imports |\n| Unused imports | **Forbidden** |\n| Javadoc | Required for API methods (exemptions: `@Override`, `@Test`, `@Before`, `@After`, `@BeforeClass`, `@AfterClass`, `@Parameterized`, `@Parameters`, `@Bean`) |\n| Braces | Required for all `if/else/for/while/do-while` blocks, even single-line |\n| Switch | Must have `default` case; fall-through must be commented |\n| Naming | `camelCase` for methods/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants |\n| Abbreviations | Max 1 consecutive capital letter in names (exception: `VO`) |\n\n### License Header\n\nEvery new source file **must** include the Apache License 2.0 header. CI enforces this via `apache-rat:check`.\n\n```java\n/*\n * Copyright 1999-${year} Alibaba Group Holding Ltd.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *      http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n```\n\n## API Standards\n\nNacos v3 APIs follow strict conventions. AI agents **must** comply with these\nstandards when generating controller code.\n\nAuthoritative API and SDK specs live under [`specs/`](./specs/README.md).\nBefore coding any API, SDK, plugin, storage, runtime, or domain change, AI\nagents **MUST** consult the relevant specs below. If the intended behavior\ndiffers from the existing spec, do not silently implement the code first:\ndiscuss the change with maintainers and update the affected specs as part of\nthe design. For broad or uncertain changes, submit a spec/design PR first so\nthe contract is reviewed before implementation.\n\nEnglish:\n\n- Design foundation:\n  [Nacos Design Spec](./specs/en/design/nacos-design-spec.md),\n  [Resource Model Spec](./specs/en/design/resource-model-spec.md),\n  [Compatibility And Deprecation Spec](./specs/en/design/compatibility-deprecation-spec.md),\n  [Foundation Capabilities Spec](./specs/en/design/foundation-capabilities-spec.md),\n  [Server Lifecycle And Environment Configuration Spec](./specs/en/design/foundation-server-lifecycle-env-spec.md),\n  [Cluster Membership Spec](./specs/en/design/foundation-cluster-membership-spec.md),\n  [Remote Connection Lifecycle Spec](./specs/en/design/foundation-remote-connection-spec.md),\n  [Request Filtering And Runtime Context Spec](./specs/en/design/foundation-request-context-spec.md),\n  [Internal RPC And Cluster Request Spec](./specs/en/design/foundation-internal-rpc-spec.md),\n  [AP Consistency Spec](./specs/en/design/foundation-ap-consistency-spec.md),\n  [CP Consistency Spec](./specs/en/design/foundation-cp-consistency-spec.md),\n  [Persistence And Dump Spec](./specs/en/design/foundation-persistence-dump-spec.md),\n  [Task Execution Spec](./specs/en/design/foundation-task-execution-spec.md),\n  [Event Dispatch And NotifyCenter Spec](./specs/en/design/foundation-event-dispatch-spec.md),\n  [Observability Hooks Spec](./specs/en/design/foundation-observability-hooks-spec.md),\n  [Core Capabilities Spec](./specs/en/design/core-capabilities-spec.md)\n- Interface model:\n  [HTTP API Spec](./specs/en/http-api/api-spec.md),\n  [Authorization Spec](./specs/en/http-api/authorization-spec.md),\n  [Response And Error Spec](./specs/en/http-api/response-error-spec.md),\n  [V3 API Surface](./specs/en/http-api/v3-api-surface.md),\n  [gRPC API Spec](./specs/en/grpc-api/api-spec.md),\n  [SDK Spec](./specs/en/sdk/sdk-spec.md),\n  [Java SDK Implementation Spec](./specs/en/sdk/sdk-java-impl-spec.md),\n  [Client Runtime Spec](./specs/en/client/client-runtime-spec.md),\n  [Client Connection And Failover Spec](./specs/en/client/client-connection-failover-spec.md),\n  [Client Ability Negotiation Spec](./specs/en/client/client-ability-negotiation-spec.md),\n  [Client Local Cache And Redo Spec](./specs/en/client/client-local-cache-redo-spec.md),\n  [Runtime Push And Reconnect Spec](./specs/en/client/runtime-push-reconnect-spec.md)\n- Domain model:\n  [Config Spec](./specs/en/config/config-spec.md),\n  [Config Resource Spec](./specs/en/config/config-resource-spec.md),\n  [Config Publish And Query Spec](./specs/en/config/config-publish-query-spec.md),\n  [Config Listener And Watch Spec](./specs/en/config/config-listener-watch-spec.md),\n  [Config Gray Release Spec](./specs/en/config/config-gray-release-spec.md),\n  [Config Persistence And History Spec](./specs/en/config/config-persistence-history-spec.md),\n  [Config Consistency, Dump, And Visibility Spec](./specs/en/config/config-consistency-dump-visibility-spec.md),\n  [Config Capacity And Ops Spec](./specs/en/config/config-capacity-ops-spec.md),\n  [Naming Spec](./specs/en/naming/naming-spec.md),\n  [Naming Resource Spec](./specs/en/naming/naming-resource-spec.md),\n  [Naming Instance Lifecycle Spec](./specs/en/naming/naming-instance-lifecycle-spec.md),\n  [Naming Discovery And Subscription Spec](./specs/en/naming/naming-discovery-subscription-spec.md),\n  [Naming Health And Protection Spec](./specs/en/naming/naming-health-protection-spec.md),\n  [Naming Metadata And Selector Spec](./specs/en/naming/naming-metadata-selector-spec.md),\n  [Naming Consistency And Client State Spec](./specs/en/naming/naming-consistency-client-spec.md),\n  [Naming Ephemeral Distro Consistency Spec](./specs/en/naming/naming-ephemeral-distro-consistency-spec.md),\n  [Naming Persistent CP Consistency Spec](./specs/en/naming/naming-persistent-cp-consistency-spec.md),\n  [Naming Ops Spec](./specs/en/naming/naming-ops-spec.md),\n  [AI Registry Spec](./specs/en/ai/ai-registry-spec.md),\n  [AI Resource Model Spec](./specs/en/ai/ai-resource-model-spec.md),\n  [AI Resource Lifecycle Spec](./specs/en/ai/ai-resource-lifecycle-spec.md),\n  [AI Registry Adaptor Spec](./specs/en/ai/ai-registry-adaptor-spec.md),\n  [Agent Management Spec](./specs/en/ai/agent-management-spec.md),\n  [Remote Agent Discovery Protocol Spec](./specs/en/ai/rad-protocol-spec.md),\n  [Agent API Spec](./specs/en/ai/agent-api-spec.md),\n  [Agent Storage Spec](./specs/en/ai/agent-storage-spec.md),\n  [MCP Server Spec](./specs/en/ai/mcp-server-spec.md),\n  [A2A Agent Spec](./specs/en/ai/a2a-agent-spec.md),\n  [Prompt Spec](./specs/en/ai/prompt-spec.md),\n  [Skill Spec](./specs/en/ai/skill-spec.md),\n  [AgentSpec Spec](./specs/en/ai/agentspec-spec.md),\n  [Core Operations Spec](./specs/en/core/core-operations-spec.md),\n  [Console Spec](./specs/en/console/console-spec.md),\n  [Distributed Lock Spec](./specs/en/lock/lock-spec.md)\n- Extension model:\n  [Integration And Adapter Spec](./specs/en/integration/integration-adapter-spec.md),\n  [Plugin Specs](./specs/en/plugin/README.md)\n- Security model:\n  [Auth And Permission Spec](./specs/en/auth/auth-permission-spec.md),\n  [Auth Plugin Spec](./specs/en/auth/auth-plugin-spec.md),\n  [RAM Auth Plugin Spec](./specs/en/auth/ram-auth-plugin-spec.md),\n  [OIDC Auth Plugin Spec](./specs/en/auth/oidc-auth-plugin-spec.md),\n  [Visibility Plugin Spec](./specs/en/auth/visibility-plugin-spec.md),\n  [Default Auth Plugin Implementation Spec](./specs/en/auth/default-auth-plugin-spec.md)\n- Testing model:\n  [API Integration Test Spec](./specs/en/testing/api-integration-test-spec.md),\n  [Java SDK Integration Test Spec](./specs/en/testing/java-sdk-integration-test-spec.md)\n- Shared schemas:\n  [JSON Schema Index](./specs/schemas/README.md)\n\nSimplified Chinese:\n\n- 设计基础：\n  [Nacos 设计规范](./specs/zh-cn/design/nacos-design-spec.md)，\n  [资源模型规范](./specs/zh-cn/design/resource-model-spec.md)，\n  [兼容与废弃策略规范](./specs/zh-cn/design/compatibility-deprecation-spec.md)，\n  [基础能力规范](./specs/zh-cn/design/foundation-capabilities-spec.md)，\n  [服务端生命周期与环境配置规范](./specs/zh-cn/design/foundation-server-lifecycle-env-spec.md)，\n  [集群成员规范](./specs/zh-cn/design/foundation-cluster-membership-spec.md)，\n  [远程连接生命周期规范](./specs/zh-cn/design/foundation-remote-connection-spec.md)，\n  [请求过滤与运行时上下文规范](./specs/zh-cn/design/foundation-request-context-spec.md)，\n  [内部 RPC 与集群请求规范](./specs/zh-cn/design/foundation-internal-rpc-spec.md)，\n  [AP 一致性规范](./specs/zh-cn/design/foundation-ap-consistency-spec.md)，\n  [CP 一致性规范](./specs/zh-cn/design/foundation-cp-consistency-spec.md)，\n  [持久化与 Dump 规范](./specs/zh-cn/design/foundation-persistence-dump-spec.md)，\n  [任务执行规范](./specs/zh-cn/design/foundation-task-execution-spec.md)，\n  [事件分发与 NotifyCenter 规范](./specs/zh-cn/design/foundation-event-dispatch-spec.md)，\n  [可观测钩子规范](./specs/zh-cn/design/foundation-observability-hooks-spec.md)，\n  [核心功能规范](./specs/zh-cn/design/core-capabilities-spec.md)\n- 接口模型：\n  [HTTP API 规范](./specs/zh-cn/http-api/api-spec.md)，\n  [鉴权规范](./specs/zh-cn/http-api/authorization-spec.md)，\n  [响应与错误规范](./specs/zh-cn/http-api/response-error-spec.md)，\n  [V3 API 范围](./specs/zh-cn/http-api/v3-api-surface.md)，\n  [gRPC API 规范](./specs/zh-cn/grpc-api/api-spec.md)，\n  [SDK 规范](./specs/zh-cn/sdk/sdk-spec.md)，\n  [Java SDK 实现规范](./specs/zh-cn/sdk/sdk-java-impl-spec.md)，\n  [客户端运行时规范](./specs/zh-cn/client/client-runtime-spec.md)，\n  [客户端连接与故障切换规范](./specs/zh-cn/client/client-connection-failover-spec.md)，\n  [客户端能力协商规范](./specs/zh-cn/client/client-ability-negotiation-spec.md)，\n  [客户端本地缓存与 Redo 规范](./specs/zh-cn/client/client-local-cache-redo-spec.md)，\n  [运行时推送与重连规范](./specs/zh-cn/client/runtime-push-reconnect-spec.md)\n- 领域模型：\n  [Config 规范](./specs/zh-cn/config/config-spec.md)，\n  [Config 资源规范](./specs/zh-cn/config/config-resource-spec.md)，\n  [Config 发布与查询规范](./specs/zh-cn/config/config-publish-query-spec.md)，\n  [Config 监听与 Watch 规范](./specs/zh-cn/config/config-listener-watch-spec.md)，\n  [Config 灰度发布规范](./specs/zh-cn/config/config-gray-release-spec.md)，\n  [Config 持久化与历史规范](./specs/zh-cn/config/config-persistence-history-spec.md)，\n  [Config 一致性、Dump 与可见性规范](./specs/zh-cn/config/config-consistency-dump-visibility-spec.md)，\n  [Config 容量与运维规范](./specs/zh-cn/config/config-capacity-ops-spec.md)，\n  [Naming 规范](./specs/zh-cn/naming/naming-spec.md)，\n  [Naming 资源规范](./specs/zh-cn/naming/naming-resource-spec.md)，\n  [Naming 实例生命周期规范](./specs/zh-cn/naming/naming-instance-lifecycle-spec.md)，\n  [Naming 发现与订阅规范](./specs/zh-cn/naming/naming-discovery-subscription-spec.md)，\n  [Naming 健康检查与保护规范](./specs/zh-cn/naming/naming-health-protection-spec.md)，\n  [Naming 元数据与 Selector 规范](./specs/zh-cn/naming/naming-metadata-selector-spec.md)，\n  [Naming 一致性与客户端状态规范](./specs/zh-cn/naming/naming-consistency-client-spec.md)，\n  [Naming 临时服务 Distro 一致性规范](./specs/zh-cn/naming/naming-ephemeral-distro-consistency-spec.md)，\n  [Naming 持久服务 CP 一致性规范](./specs/zh-cn/naming/naming-persistent-cp-consistency-spec.md)，\n  [Naming 运维规范](./specs/zh-cn/naming/naming-ops-spec.md)，\n  [AI Registry 规范](./specs/zh-cn/ai/ai-registry-spec.md)，\n  [AI 资源模型规范](./specs/zh-cn/ai/ai-resource-model-spec.md)，\n  [AI 资源生命周期规范](./specs/zh-cn/ai/ai-resource-lifecycle-spec.md)，\n  [AI Registry 适配器规范](./specs/zh-cn/ai/ai-registry-adaptor-spec.md)，\n  [Agent 管理规范](./specs/zh-cn/ai/agent-management-spec.md)，\n  [Remote Agent Discovery 协议规范](./specs/zh-cn/ai/rad-protocol-spec.md)，\n  [Agent API 规范](./specs/zh-cn/ai/agent-api-spec.md)，\n  [Agent 存储规范](./specs/zh-cn/ai/agent-storage-spec.md)，\n  [MCP Server 规范](./specs/zh-cn/ai/mcp-server-spec.md)，\n  [A2A Agent 规范](./specs/zh-cn/ai/a2a-agent-spec.md)，\n  [Prompt 规范](./specs/zh-cn/ai/prompt-spec.md)，\n  [Skill 规范](./specs/zh-cn/ai/skill-spec.md)，\n  [AgentSpec 规范](./specs/zh-cn/ai/agentspec-spec.md)，\n  [Core 运维规范](./specs/zh-cn/core/core-operations-spec.md)，\n  [Console 规范](./specs/zh-cn/console/console-spec.md)，\n  [分布式锁规范](./specs/zh-cn/lock/lock-spec.md)\n- 扩展模型：\n  [集成与适配器规范](./specs/zh-cn/integration/integration-adapter-spec.md)，\n  [插件规范](./specs/zh-cn/plugin/README.md)\n- 安全模型：\n  [鉴权与权限规范](./specs/zh-cn/auth/auth-permission-spec.md)，\n  [鉴权插件规范](./specs/zh-cn/auth/auth-plugin-spec.md)，\n  [RAM 鉴权插件规范](./specs/zh-cn/auth/ram-auth-plugin-spec.md)，\n  [OIDC 鉴权插件规范](./specs/zh-cn/auth/oidc-auth-plugin-spec.md)，\n  [可见性插件规范](./specs/zh-cn/auth/visibility-plugin-spec.md)，\n  [默认鉴权插件实现规范](./specs/zh-cn/auth/default-auth-plugin-spec.md)\n- 测试模型：\n  [API 集成测试规范](./specs/zh-cn/testing/api-integration-test-spec.md)，\n  [Java SDK 集成测试规范](./specs/zh-cn/testing/java-sdk-integration-test-spec.md)\n- 共享 Schema：\n  [JSON Schema 索引](./specs/schemas/README.md)\n\nThis section is a quick implementation checklist for agents. If it conflicts\nwith the specs, follow the specs and update this checklist.\n\n### URL Path Patterns\n\n| API Type | Base Path | Purpose | Example |\n|----------|-----------|---------|---------|\n| **Open API** | `/v3/client/{module}/...` | Client-facing operations | `/v3/client/ns/instance` |\n| **Admin API** | `/v3/admin/{module}/...` | Administrative operations | `/v3/admin/ns/service` |\n| **Console API** | `/v3/console/{module}/...` | Web console operations | `/v3/console/cs/config` |\n| **Auth API** | `/v3/auth/{resource}/...` | Plugin-provided auth operations | `/v3/auth/user` |\n\n### Module Names\n\n| Module | Abbreviation | Scope |\n|--------|-------------|-------|\n| Config Service | `cs` | Configuration management |\n| Naming Service | `ns` | Service discovery |\n| Core | `core` | Cluster, namespace management |\n| AI | `ai` | AI resource management |\n| Plugin | `plugin` | Plugin management |\n\n> **Note**: Auth APIs (`/v3/auth/user`, `/v3/auth/role`, `/v3/auth/permission`) are defined in `plugin-default-impl` module, not in core.\n\n### HTTP Method Semantics\n\n| Method | Usage | Idempotent |\n|--------|-------|:----------:|\n| `GET` | Query / Retrieve | Yes |\n| `POST` | Create / Register | No |\n| `PUT` | Update / Modify | Yes |\n| `DELETE` | Remove / Deregister | Yes |\n\n### Response Format\n\n**Always** wrap responses in `com.alibaba.nacos.api.model.v2.Result<T>`:\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"success\",\n  \"data\": { }\n}\n```\n\n### Authentication\n\n**Always** add `@Secured` annotation (`com.alibaba.nacos.auth.annotation.Secured`):\n\n```java\n@Secured(action = ActionTypes.READ,       // READ or WRITE\n         signType = SignType.CONFIG,       // CONFIG, NAMING, or CONSOLE\n         apiType = ApiType.ADMIN_API)      // OPEN_API, ADMIN_API, or CONSOLE_API\n```\n\n### API Integration Tests\n\nFor every HTTP API addition, modification, deletion, or deprecation, handle\n`test/openapi-test` before the API change is considered complete:\n\n1. Read the affected controller, form/request model, validators, service path,\n   response model, exception handling, and matching specs.\n2. Build or update the scenario matrix for expected capability,\n   boundary/validation behavior, and exception/error handling.\n3. Add, update, or remove API IT cases for the changed contract. The goal is API\n   scenario coverage, not line or branch coverage.\n4. Update `test/openapi-test/API_TEST_COVERAGE.md` and the matching\n   `*_API_TEST_SCENARIOS.md` document.\n5. If the functional success path is hard to exercise in standalone IT, at\n   least cover boundary and error scenarios and document the uncovered path.\n\n### Java SDK Integration Tests\n\nFor every Java SDK public contract change, handle `test/java-sdk-test` before\nthe SDK change is considered complete:\n\n1. Read the public interface, implementation, request/response model, listener\n   path, lifecycle code, exception mapping, and matching SDK/client specs.\n2. Build or update the scenario matrix for factory/lifecycle behavior,\n   expected capability, boundary/validation behavior, listener/subscription\n   behavior, and exception handling.\n3. Add, update, or remove Java SDK IT cases for the changed SDK contract. Assert\n   SDK return values, callbacks, remote side effects, and typed exceptions.\n4. Update `test/java-sdk-test/JAVA_SDK_IT_COVERAGE.md`.\n5. Keep SDK ITs as external-client tests against a standalone Nacos server; do\n   not start Spring or Nacos inside the test class.\n\n### Controller Example\n\n```java\nimport com.alibaba.nacos.api.model.v2.Result;\nimport com.alibaba.nacos.auth.annotation.Secured;\nimport com.alibaba.nacos.plugin.auth.constant.ActionTypes;\nimport com.alibaba.nacos.plugin.auth.constant.SignType;\nimport com.alibaba.nacos.api.common.ApiType;\n\n@RestController\n@RequestMapping(\"/v3/admin/ns/service\")\npublic class ServiceControllerV3 {\n\n    @PostMapping\n    @Secured(action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)\n    public Result<String> create(ServiceForm serviceForm) throws Exception {\n        serviceForm.validate();\n        // business logic ...\n        return Result.success(\"ok\");\n    }\n\n    @GetMapping(\"/list\")\n    @Secured(action = ActionTypes.READ, apiType = ApiType.ADMIN_API)\n    public Result<Page<ServiceDetailInfo>> list(ServiceListForm serviceListForm) throws NacosException {\n        serviceListForm.validate();\n        // business logic ...\n        return Result.success(result);\n    }\n}\n```\n\n## Java Version Targeting\n\n- **Server modules** (config, naming, core, console, etc.): Java 17+\n- **Client/API/Plugin modules** (api, client, plugin): Java 8+ — ensure backwards compatibility when modifying\n\n## PR Convention\n\nAll PRs must target the `develop` branch. Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md).\n\n**Title format**: `[ISSUE #14122] Add JVM --add-opens options for JDK 17+ compatibility`\n\n**Pre-submission checklist**:\n```bash\nmvn -B clean package apache-rat:check spotbugs:check -DskipTests\nmvn clean install\nmvn clean test-compile failsafe:integration-test\n```\n\n## Security Vulnerabilities\n\nDo NOT report security vulnerabilities via GitHub Issues. Use [ASRC (Alibaba Security Response Center)](https://security.alibaba.com) instead.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to AI coding agents (Claude Code, Cursor, GitHub Copilot, etc.) when working with the Nacos repository. For human contributors, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## AI Contribution Guidelines\n\n- **Do NOT post AI-generated comments** on issues or PRs. Discussions are for humans only.\n- **Discuss before implementing**: Ensure the implementation direction is agreed upon with maintainers in the issue comments before starting work.\n- **Spec-first coding is mandatory**: Before changing behavior, APIs, SDKs,\n  plugins, storage, runtime flow, or domain semantics, AI agents MUST read the\n  relevant specs under [`specs/`](./specs/README.md) and treat them as the rule\n  source for the implementation.\n- **Discuss spec-impacting changes before coding**: If a change touches behavior\n  covered by an existing spec, or exposes a gap between the code and the spec,\n  AI agents MUST discuss the implementation direction and the required spec\n  update with maintainers before starting the code change.\n- **Update specs with the design**: Any design proposal that changes or\n  clarifies spec-covered behavior MUST include the corresponding spec updates\n  in the same change set. When the design is large or controversial, prefer a\n  spec/design-only PR first, then follow with implementation PRs.\n- **API IT impact comes first**: Before adding, changing, deleting, or\n  deprecating any HTTP API, AI agents MUST analyze the affected\n  `test/openapi-test` coverage and update the API IT scenario matrix, test\n  cases, and coverage registry in the same change set. If the functional path\n  cannot be exercised in standalone IT, cover boundary/error scenarios and\n  document the reason.\n- **Java SDK IT impact comes first**: Before adding, changing, deleting, or\n  deprecating any public Java SDK interface, factory, model, listener behavior,\n  lifecycle behavior, or exception mapping, AI agents MUST analyze and update\n  `test/java-sdk-test` coverage, including scenario documentation. If the\n  end-to-end success path is impractical, cover SDK parameter validation,\n  boundary behavior, and controlled exceptions.\n- **Disclose AI usage**: When a significant part of a commit is AI-generated, add a trailer to your commit message:\n  ```\n  Assisted-by: Claude Code\n  ```\n- **Follow [CONTRIBUTING.md](./CONTRIBUTING.md)** for all contribution processes.\n\n## Repository Overview\n\nNacos (Dynamic Naming and Configuration Service) is an easy-to-use platform designed for dynamic service discovery, configuration management, and AI agent management. It helps you build cloud-native applications and AI Agent applications easily. Key capabilities: service discovery, dynamic configuration, dynamic DNS service, service/metadata management, and AI registry (Prompt, MCP, A2A).\n\n**Current Version**: 3.2.1-SNAPSHOT | **Main Branch**: `develop` | **Java**: JDK 17+ (client modules: JDK 8+) | **Build**: Maven 3.2.5+\n\n## Core Architecture\n\nKey modules and their roles:\n\n- **api / client / client-basic**: Client-facing APIs, gRPC definitions, SDK (Java 8 compatible)\n- **common**: Shared utilities, HTTP client, notify center, executor\n- **config**: Configuration management server\n- **naming**: Service discovery and registration server\n- **core**: Core server infrastructure (cluster, distributed consensus)\n- **consistency**: JRaft-based CP protocol + custom Distro AP protocol\n- **auth**: Authentication and authorization\n- **plugin / plugin-default-impl**: Extensible plugin system (Java SPI). Types: auth, visibility, datasource dialect, config change, encryption, trace, environment, control, AI pipeline, AI storage\n- **console / console-ui**: Web UI backend (Spring Boot) and frontend (React)\n- **ai / copilot / ai-registry-adaptor**: AI Agent support, Copilot integration, and AI registry adaptor\n- **sys**: System environment utilities and JVM parameter management\n- **bootstrap / server**: Server startup and aggregation\n- **persistence**: Data persistence with multi-database support (Derby, MySQL, PostgreSQL)\n- **maintainer-client**: Internal maintenance client\n- **lock**: Distributed lock support\n\nCommunication: **gRPC** (primary) + **HTTP/REST** (legacy compatibility). Protobuf definitions in `api/src/main/proto/`.\n\n## Build & Test Commands\n\n```bash\n# Full build (skip tests)\nmvn '-Prelease-nacos,!dev' -Dmaven.test.skip=true clean install -U\n\n# Run all unit tests\nmvn test\n\n# Run standalone-server integration tests\nmvn -pl test/openapi-test -Pintegration-test -DskipTests=false verify\nmvn -pl test/java-sdk-test -Pjava-sdk-integration-test -DskipTests=false verify\nmvn -pl test/maintainer-sdk-test -Pmaintainer-sdk-integration-test -DskipTests=false verify\n\n# Format code (run before commit)\nmvn spotless:apply\n\n# Pre-submission checks (MUST pass before PR)\nmvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests\n```\n\n### Mandatory Formatting Before Commit\n\nBefore committing Java code or tests, AI agents MUST run Spotless for the\naffected module or nearest aggregator:\n\n1. Run `mvn spotless:apply` first.\n2. Run `mvn spotless:check` for the same scope.\n3. Then run the relevant compile/check/test command.\n4. Commit only after Spotless and the relevant validation pass.\n\nDo not rely on `checkstyle:check`, `spotbugs:check`, or `git diff --check` as a\nsubstitute for Spotless. Spotless uses the project formatter and may accept\nformatting that generic whitespace checks report differently.\n\n## Code Style\n\nFollows **Alibaba Java Coding Guidelines**.\n\n- Checkstyle config: [`style/NacosCheckStyle.xml`](style/NacosCheckStyle.xml)\n- IDEA code style: [`style/nacos-code-style-for-idea.xml`](style/nacos-code-style-for-idea.xml)\n\n### Key Rules for AI Agents\n\n| Rule | Value |\n|------|-------|\n| Indentation | **4 spaces** (basic offset), 4 spaces (case indent) |\n| Line length | **100 characters** max (enforced by Spotless + Checkstyle) |\n| Star imports | **Forbidden** — always use explicit imports |\n| Unused imports | **Forbidden** |\n| Javadoc | Required for API methods (exemptions: `@Override`, `@Test`, `@Before`, `@After`, `@BeforeClass`, `@AfterClass`, `@Parameterized`, `@Parameters`, `@Bean`) |\n| Braces | Required for all `if/else/for/while/do-while` blocks, even single-line |\n| Switch | Must have `default` case; fall-through must be commented |\n| Naming | `camelCase` for methods/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants |\n| Abbreviations | Max 1 consecutive capital letter in names (exception: `VO`) |\n\n### License Header\n\nEvery new source file **must** include the Apache License 2.0 header. CI enforces this via `apache-rat:check`.\n\n```java\n/*\n * Copyright 1999-${year} Alibaba Group Holding Ltd.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *      http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n```\n\n## API Standards\n\nNacos v3 APIs follow strict conventions. AI agents **must** comply with these\nstandards when generating controller code.\n\nAuthoritative API and SDK specs live under [`specs/`](./specs/README.md).\nBefore coding any API, SDK, plugin, storage, runtime, or domain change, AI\nagents **MUST** consult the relevant specs below. If the intended behavior\ndiffers from the existing spec, do not silently implement the code first:\ndiscuss the change with maintainers and update the affected specs as part of\nthe design. For broad or uncertain changes, submit a spec/design PR first so\nthe contract is reviewed before implementation.\n\nEnglish:\n\n- Design foundation:\n  [Nacos Design Spec](./specs/en/design/nacos-design-spec.md),\n  [Resource Model Spec](./specs/en/design/resource-model-spec.md),\n  [Compatibility And Deprecation Spec](./specs/en/design/compatibility-deprecation-spec.md),\n  [Foundation Capabilities Spec](./specs/en/design/foundation-capabilities-spec.md),\n  [Server Lifecycle And Environment Configuration Spec](./specs/en/design/foundation-server-lifecycle-env-spec.md),\n  [Cluster Membership Spec](./specs/en/design/foundation-cluster-membership-spec.md),\n  [Remote Connection Lifecycle Spec](./specs/en/design/foundation-remote-connection-spec.md),\n  [Request Filtering And Runtime Context Spec](./specs/en/design/foundation-request-context-spec.md),\n  [Internal RPC And Cluster Request Spec](./specs/en/design/foundation-internal-rpc-spec.md),\n  [AP Consistency Spec](./specs/en/design/foundation-ap-consistency-spec.md),\n  [CP Consistency Spec](./specs/en/design/foundation-cp-consistency-spec.md),\n  [Persistence And Dump Spec](./specs/en/design/foundation-persistence-dump-spec.md),\n  [Task Execution Spec](./specs/en/design/foundation-task-execution-spec.md),\n  [Event Dispatch And NotifyCenter Spec](./specs/en/design/foundation-event-dispatch-spec.md),\n  [Observability Hooks Spec](./specs/en/design/foundation-observability-hooks-spec.md),\n  [Core Capabilities Spec](./specs/en/design/core-capabilities-spec.md)\n- Interface model:\n  [HTTP API Spec](./specs/en/http-api/api-spec.md),\n  [Authorization Spec](./specs/en/http-api/authorization-spec.md),\n  [Response And Error Spec](./specs/en/http-api/response-error-spec.md),\n  [V3 API Surface](./specs/en/http-api/v3-api-surface.md),\n  [gRPC API Spec](./specs/en/grpc-api/api-spec.md),\n  [SDK Spec](./specs/en/sdk/sdk-spec.md),\n  [Java SDK Implementation Spec](./specs/en/sdk/sdk-java-impl-spec.md),\n  [Client Runtime Spec](./specs/en/client/client-runtime-spec.md),\n  [Client Connection And Failover Spec](./specs/en/client/client-connection-failover-spec.md),\n  [Client Ability Negotiation Spec](./specs/en/client/client-ability-negotiation-spec.md),\n  [Client Local Cache And Redo Spec](./specs/en/client/client-local-cache-redo-spec.md),\n  [Runtime Push And Reconnect Spec](./specs/en/client/runtime-push-reconnect-spec.md)\n- Domain model:\n  [Config Spec](./specs/en/config/config-spec.md),\n  [Config Resource Spec](./specs/en/config/config-resource-spec.md),\n  [Config Publish And Query Spec](./specs/en/config/config-publish-query-spec.md),\n  [Config Listener And Watch Spec](./specs/en/config/config-listener-watch-spec.md),\n  [Config Gray Release Spec](./specs/en/config/config-gray-release-spec.md),\n  [Config Persistence And History Spec](./specs/en/config/config-persistence-history-spec.md),\n  [Config Consistency, Dump, And Visibility Spec](./specs/en/config/config-consistency-dump-visibility-spec.md),\n  [Config Capacity And Ops Spec](./specs/en/config/config-capacity-ops-spec.md),\n  [Naming Spec](./specs/en/naming/naming-spec.md),\n  [Naming Resource Spec](./specs/en/naming/naming-resource-spec.md),\n  [Naming Instance Lifecycle Spec](./specs/en/naming/naming-instance-lifecycle-spec.md),\n  [Naming Discovery And Subscription Spec](./specs/en/naming/naming-discovery-subscription-spec.md),\n  [Naming Health And Protection Spec](./specs/en/naming/naming-health-protection-spec.md),\n  [Naming Metadata And Selector Spec](./specs/en/naming/naming-metadata-selector-spec.md),\n  [Naming Consistency And Client State Spec](./specs/en/naming/naming-consistency-client-spec.md),\n  [Naming Ephemeral Distro Consistency Spec](./specs/en/naming/naming-ephemeral-distro-consistency-spec.md),\n  [Naming Persistent CP Consistency Spec](./specs/en/naming/naming-persistent-cp-consistency-spec.md),\n  [Naming Ops Spec](./specs/en/naming/naming-ops-spec.md),\n  [AI Registry Spec](./specs/en/ai/ai-registry-spec.md),\n  [AI Resource Model Spec](./specs/en/ai/ai-resource-model-spec.md),\n  [AI Resource Lifecycle Spec](./specs/en/ai/ai-resource-lifecycle-spec.md),\n  [AI Registry Adaptor Spec](./specs/en/ai/ai-registry-adaptor-spec.md),\n  [Agent Management Spec](./specs/en/ai/agent-management-spec.md),\n  [Remote Agent Discovery Protocol Spec](./specs/en/ai/rad-protocol-spec.md),\n  [Agent API Spec](./specs/en/ai/agent-api-spec.md),\n  [Agent Storage Spec](./specs/en/ai/agent-storage-spec.md),\n  [MCP Server Spec](./specs/en/ai/mcp-server-spec.md),\n  [A2A Agent Spec](./specs/en/ai/a2a-agent-spec.md),\n  [Prompt Spec](./specs/en/ai/prompt-spec.md),\n  [Skill Spec](./specs/en/ai/skill-spec.md),\n  [AgentSpec Spec](./specs/en/ai/agentspec-spec.md),\n  [Core Operations Spec](./specs/en/core/core-operations-spec.md),\n  [Console Spec](./specs/en/console/console-spec.md),\n  [Distributed Lock Spec](./specs/en/lock/lock-spec.md)\n- Extension model:\n  [Integration And Adapter Spec](./specs/en/integration/integration-adapter-spec.md),\n  [Plugin Specs](./specs/en/plugin/README.md)\n- Security model:\n  [Auth And Permission Spec](./specs/en/auth/auth-permission-spec.md),\n  [Auth Plugin Spec](./specs/en/auth/auth-plugin-spec.md),\n  [RAM Auth Plugin Spec](./specs/en/auth/ram-auth-plugin-spec.md),\n  [OIDC Auth Plugin Spec](./specs/en/auth/oidc-auth-plugin-spec.md),\n  [Visibility Plugin Spec](./specs/en/auth/visibility-plugin-spec.md),\n  [Default Auth Plugin Implementation Spec](./specs/en/auth/default-auth-plugin-spec.md)\n- Testing model:\n  [API Integration Test Spec](./specs/en/testing/api-integration-test-spec.md),\n  [Java SDK Integration Test Spec](./specs/en/testing/java-sdk-integration-test-spec.md)\n- Shared schemas:\n  [JSON Schema Index](./specs/schemas/README.md)\n\nSimplified Chinese:\n\n- 设计基础：\n  [Nacos 设计规范](./specs/zh-cn/design/nacos-design-spec.md)，\n  [资源模型规范](./specs/zh-cn/design/resource-model-spec.md)，\n  [兼容与废弃策略规范](./specs/zh-cn/design/compatibility-deprecation-spec.md)，\n  [基础能力规范](./specs/zh-cn/design/foundation-capabilities-spec.md)，\n  [服务端生命周期与环境配置规范](./specs/zh-cn/design/foundation-server-lifecycle-env-spec.md)，\n  [集群成员规范](./specs/zh-cn/design/foundation-cluster-membership-spec.md)，\n  [远程连接生命周期规范](./specs/zh-cn/design/foundation-remote-connection-spec.md)，\n  [请求过滤与运行时上下文规范](./specs/zh-cn/design/foundation-request-context-spec.md)，\n  [内部 RPC 与集群请求规范](./specs/zh-cn/design/foundation-internal-rpc-spec.md)，\n  [AP 一致性规范](./specs/zh-cn/design/foundation-ap-consistency-spec.md)，\n  [CP 一致性规范](./specs/zh-cn/design/foundation-cp-consistency-spec.md)，\n  [持久化与 Dump 规范](./specs/zh-cn/design/foundation-persistence-dump-spec.md)，\n  [任务执行规范](./specs/zh-cn/design/foundation-task-execution-spec.md)，\n  [事件分发与 NotifyCenter 规范](./specs/zh-cn/design/foundation-event-dispatch-spec.md)，\n  [可观测钩子规范](./specs/zh-cn/design/foundation-observability-hooks-spec.md)，\n  [核心功能规范](./specs/zh-cn/design/core-capabilities-spec.md)\n- 接口模型：\n  [HTTP API 规范](./specs/zh-cn/http-api/api-spec.md)，\n  [鉴权规范](./specs/zh-cn/http-api/authorization-spec.md)，\n  [响应与错误规范](./specs/zh-cn/http-api/response-error-spec.md)，\n  [V3 API 范围](./specs/zh-cn/http-api/v3-api-surface.md)，\n  [gRPC API 规范](./specs/zh-cn/grpc-api/api-spec.md)，\n  [SDK 规范](./specs/zh-cn/sdk/sdk-spec.md)，\n  [Java SDK 实现规范](./specs/zh-cn/sdk/sdk-java-impl-spec.md)，\n  [客户端运行时规范](./specs/zh-cn/client/client-runtime-spec.md)，\n  [客户端连接与故障切换规范](./specs/zh-cn/client/client-connection-failover-spec.md)，\n  [客户端能力协商规范](./specs/zh-cn/client/client-ability-negotiation-spec.md)，\n  [客户端本地缓存与 Redo 规范](./specs/zh-cn/client/client-local-cache-redo-spec.md)，\n  [运行时推送与重连规范](./specs/zh-cn/client/runtime-push-reconnect-spec.md)\n- 领域模型：\n  [Config 规范](./specs/zh-cn/config/config-spec.md)，\n  [Config 资源规范](./specs/zh-cn/config/config-resource-spec.md)，\n  [Config 发布与查询规范](./specs/zh-cn/config/config-publish-query-spec.md)，\n  [Config 监听与 Watch 规范](./specs/zh-cn/config/config-listener-watch-spec.md)，\n  [Config 灰度发布规范](./specs/zh-cn/config/config-gray-release-spec.md)，\n  [Config 持久化与历史规范](./specs/zh-cn/config/config-persistence-history-spec.md)，\n  [Config 一致性、Dump 与可见性规范](./specs/zh-cn/config/config-consistency-dump-visibility-spec.md)，\n  [Config 容量与运维规范](./specs/zh-cn/config/config-capacity-ops-spec.md)，\n  [Naming 规范](./specs/zh-cn/naming/naming-spec.md)，\n  [Naming 资源规范](./specs/zh-cn/naming/naming-resource-spec.md)，\n  [Naming 实例生命周期规范](./specs/zh-cn/naming/naming-instance-lifecycle-spec.md)，\n  [Naming 发现与订阅规范](./specs/zh-cn/naming/naming-discovery-subscription-spec.md)，\n  [Naming 健康检查与保护规范](./specs/zh-cn/naming/naming-health-protection-spec.md)，\n  [Naming 元数据与 Selector 规范](./specs/zh-cn/naming/naming-metadata-selector-spec.md)，\n  [Naming 一致性与客户端状态规范](./specs/zh-cn/naming/naming-consistency-client-spec.md)，\n  [Naming 临时服务 Distro 一致性规范](./specs/zh-cn/naming/naming-ephemeral-distro-consistency-spec.md)，\n  [Naming 持久服务 CP 一致性规范](./specs/zh-cn/naming/naming-persistent-cp-consistency-spec.md)，\n  [Naming 运维规范](./specs/zh-cn/naming/naming-ops-spec.md)，\n  [AI Registry 规范](./specs/zh-cn/ai/ai-registry-spec.md)，\n  [AI 资源模型规范](./specs/zh-cn/ai/ai-resource-model-spec.md)，\n  [AI 资源生命周期规范](./specs/zh-cn/ai/ai-resource-lifecycle-spec.md)，\n  [AI Registry 适配器规范](./specs/zh-cn/ai/ai-registry-adaptor-spec.md)，\n  [Agent 管理规范](./specs/zh-cn/ai/agent-management-spec.md)，\n  [Remote Agent Discovery 协议规范](./specs/zh-cn/ai/rad-protocol-spec.md)，\n  [Agent API 规范](./specs/zh-cn/ai/agent-api-spec.md)，\n  [Agent 存储规范](./specs/zh-cn/ai/agent-storage-spec.md)，\n  [MCP Server 规范](./specs/zh-cn/ai/mcp-server-spec.md)，\n  [A2A Agent 规范](./specs/zh-cn/ai/a2a-agent-spec.md)，\n  [Prompt 规范](./specs/zh-cn/ai/prompt-spec.md)，\n  [Skill 规范](./specs/zh-cn/ai/skill-spec.md)，\n  [AgentSpec 规范](./specs/zh-cn/ai/agentspec-spec.md)，\n  [Core 运维规范](./specs/zh-cn/core/core-operations-spec.md)，\n  [Console 规范](./specs/zh-cn/console/console-spec.md)，\n  [分布式锁规范](./specs/zh-cn/lock/lock-spec.md)\n- 扩展模型：\n  [集成与适配器规范](./specs/zh-cn/integration/integration-adapter-spec.md)，\n  [插件规范](./specs/zh-cn/plugin/README.md)\n- 安全模型：\n  [鉴权与权限规范](./specs/zh-cn/auth/auth-permission-spec.md)，\n  [鉴权插件规范](./specs/zh-cn/auth/auth-plugin-spec.md)，\n  [RAM 鉴权插件规范](./specs/zh-cn/auth/ram-auth-plugin-spec.md)，\n  [OIDC 鉴权插件规范](./specs/zh-cn/auth/oidc-auth-plugin-spec.md)，\n  [可见性插件规范](./specs/zh-cn/auth/visibility-plugin-spec.md)，\n  [默认鉴权插件实现规范](./specs/zh-cn/auth/default-auth-plugin-spec.md)\n- 测试模型：\n  [API 集成测试规范](./specs/zh-cn/testing/api-integration-test-spec.md)，\n  [Java SDK 集成测试规范](./specs/zh-cn/testing/java-sdk-integration-test-spec.md)\n- 共享 Schema：\n  [JSON Schema 索引](./specs/schemas/README.md)\n\nThis section is a quick implementation checklist for agents. If it conflicts\nwith the specs, follow the specs and update this checklist.\n\n### URL Path Patterns\n\n| API Type | Base Path | Purpose | Example |\n|----------|-----------|---------|---------|\n| **Open API** | `/v3/client/{module}/...` | Client-facing operations | `/v3/client/ns/instance` |\n| **Admin API** | `/v3/admin/{module}/...` | Administrative operations | `/v3/admin/ns/service` |\n| **Console API** | `/v3/console/{module}/...` | Web console operations | `/v3/console/cs/config` |\n| **Auth API** | `/v3/auth/{resource}/...` | Plugin-provided auth operations | `/v3/auth/user` |\n\n### Module Names\n\n| Module | Abbreviation | Scope |\n|--------|-------------|-------|\n| Config Service | `cs` | Configuration management |\n| Naming Service | `ns` | Service discovery |\n| Core | `core` | Cluster, namespace management |\n| AI | `ai` | AI resource management |\n| Plugin | `plugin` | Plugin management |\n\n> **Note**: Auth APIs (`/v3/auth/user`, `/v3/auth/role`, `/v3/auth/permission`) are defined in `plugin-default-impl` module, not in core.\n\n### HTTP Method Semantics\n\n| Method | Usage | Idempotent |\n|--------|-------|:----------:|\n| `GET` | Query / Retrieve | Yes |\n| `POST` | Create / Register | No |\n| `PUT` | Update / Modify | Yes |\n| `DELETE` | Remove / Deregister | Yes |\n\n### Response Format\n\n**Always** wrap responses in `com.alibaba.nacos.api.model.v2.Result<T>`:\n\n```json\n{\n  \"code\": 0,\n  \"message\": \"success\",\n  \"data\": { }\n}\n```\n\n### Authentication\n\n**Always** add `@Secured` annotation (`com.alibaba.nacos.auth.annotation.Secured`):\n\n```java\n@Secured(action = ActionTypes.READ,       // READ or WRITE\n         signType = SignType.CONFIG,       // CONFIG, NAMING, or CONSOLE\n         apiType = ApiType.ADMIN_API)      // OPEN_API, ADMIN_API, or CONSOLE_API\n```\n\n### API Integration Tests\n\nFor every HTTP API addition, modification, deletion, or deprecation, handle\n`test/openapi-test` before the API change is considered complete:\n\n1. Read the affected controller, form/request model, validators, service path,\n   response model, exception handling, and matching specs.\n2. Build or update the scenario matrix for expected capability,\n   boundary/validation behavior, and exception/error handling.\n3. Add, update, or remove API IT cases for the changed contract. The goal is API\n   scenario coverage, not line or branch coverage.\n4. Update `test/openapi-test/API_TEST_COVERAGE.md` and the matching\n   `*_API_TEST_SCENARIOS.md` document.\n5. If the functional success path is hard to exercise in standalone IT, at\n   least cover boundary and error scenarios and document the uncovered path.\n\n### Java SDK Integration Tests\n\nFor every Java SDK public contract change, handle `test/java-sdk-test` before\nthe SDK change is considered complete:\n\n1. Read the public interface, implementation, request/response model, listener\n   path, lifecycle code, exception mapping, and matching SDK/client specs.\n2. Build or update the scenario matrix for factory/lifecycle behavior,\n   expected capability, boundary/validation behavior, listener/subscription\n   behavior, and exception handling.\n3. Add, update, or remove Java SDK IT cases for the changed SDK contract. Assert\n   SDK return values, callbacks, remote side effects, and typed exceptions.\n4. Update `test/java-sdk-test/JAVA_SDK_IT_COVERAGE.md`.\n5. Keep SDK ITs as external-client tests against a standalone Nacos server; do\n   not start Spring or Nacos inside the test class.\n\n### Controller Example\n\n```java\nimport com.alibaba.nacos.api.model.v2.Result;\nimport com.alibaba.nacos.auth.annotation.Secured;\nimport com.alibaba.nacos.plugin.auth.constant.ActionTypes;\nimport com.alibaba.nacos.plugin.auth.constant.SignType;\nimport com.alibaba.nacos.api.common.ApiType;\n\n@RestController\n@RequestMapping(\"/v3/admin/ns/service\")\npublic class ServiceControllerV3 {\n\n    @PostMapping\n    @Secured(action = ActionTypes.WRITE, apiType = ApiType.ADMIN_API)\n    public Result<String> create(ServiceForm serviceForm) throws Exception {\n        serviceForm.validate();\n        // business logic ...\n        return Result.success(\"ok\");\n    }\n\n    @GetMapping(\"/list\")\n    @Secured(action = ActionTypes.READ, apiType = ApiType.ADMIN_API)\n    public Result<Page<ServiceDetailInfo>> list(ServiceListForm serviceListForm) throws NacosException {\n        serviceListForm.validate();\n        // business logic ...\n        return Result.success(result);\n    }\n}\n```\n\n## Java Version Targeting\n\n- **Server modules** (config, naming, core, console, etc.): Java 17+\n- **Client/API/Plugin modules** (api, client, plugin): Java 8+ — ensure backwards compatibility when modifying\n\n## PR Convention\n\nAll PRs must target the `develop` branch. Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md).\n\n**Title format**: `[ISSUE #14122] Add JVM --add-opens options for JDK 17+ compatibility`\n\n**Pre-submission checklist**:\n```bash\nmvn -B clean package apache-rat:check spotbugs:check -DskipTests\nmvn clean install\nmvn clean test-compile failsafe:integration-test\n```\n\n## Security Vulnerabilities\n\nDo NOT report security vulnerabilities via GitHub Issues. Use [ASRC (Alibaba Security Response Center)](https://security.alibaba.com) instead.\n","category":"root","tokens":5907}]}