Merge branch 'develop' into xuxiaowei/spring-boot-4

# Conflicts:
#	ai/src/test/java/com/alibaba/nacos/ai/controller/SkillClientControllerTest.java
#	config/src/test/java/com/alibaba/nacos/config/server/controller/v3/ConfigControllerV3Test.java
#	plugin-default-impl/nacos-default-auth-plugin/src/test/java/com/alibaba/nacos/plugin/auth/impl/controller/UserControllerTest.java
#	plugin-default-impl/nacos-default-auth-plugin/src/test/java/com/alibaba/nacos/plugin/auth/impl/controller/v3/UserControllerV3Test.java
#	pom.xml

Author: xuxiaowei-com-cn

.gitignore

@@ -25,3 +25,4 @@ dependency-reduced-pom.xml
 .jqwik-database
 .qoder/
 openspec/
+.codegraph

AGENTS.md

@@ -72,6 +72,20 @@ mvn spotless:apply
 mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests
 ```
 
+### Mandatory Formatting Before Commit
+
+Before committing Java code or tests, AI agents MUST run Spotless for the
+affected module or nearest aggregator:
+
+1. Run `mvn spotless:apply` first.
+2. Run `mvn spotless:check` for the same scope.
+3. Then run the relevant compile/check/test command.
+4. Commit only after Spotless and the relevant validation pass.
+
+Do not rely on `checkstyle:check`, `spotbugs:check`, or `git diff --check` as a
+substitute for Spotless. Spotless uses the project formatter and may accept
+formatting that generic whitespace checks report differently.
+
 ## Code Style
 
 Follows **Alibaba Java Coding Guidelines**.

address/src/main/java/com/alibaba/nacos/address/controller/AddressServerClusterController.java

@@ -16,6 +16,7 @@
 
 package com.alibaba.nacos.address.controller;
 
+import com.alibaba.nacos.api.annotation.Since;
 import com.alibaba.nacos.address.component.AddressServerGeneratorManager;
 import com.alibaba.nacos.address.component.AddressServerManager;
 import com.alibaba.nacos.address.constant.AddressServerConstants;
@@ -83,6 +84,7 @@ public AddressServerClusterController(InstanceOperator instanceOperator,
      * @param ips     will post ip list.
      * @return result of create new cluster
      */
+    @Since("1.1.0")
     @RequestMapping(value = "", method = RequestMethod.POST)
     public ResponseEntity<String> postCluster(@RequestParam(required = false) String product,
         @RequestParam(required = false) String cluster, @RequestParam(name = "ips") String ips) {
@@ -164,6 +166,7 @@ private Result registerCluster(String serviceName, String productName, String cl
      * @param ips     will delete ips.
      * @return delete result (the cluster information is return if success, exception information is return if  fail)
      */
+    @Since("1.1.0")
     @RequestMapping(value = "", method = RequestMethod.DELETE)
     public ResponseEntity<String> deleteCluster(@RequestParam(required = false) String product,
         @RequestParam(required = false) String cluster, @RequestParam String ips) {

address/src/main/java/com/alibaba/nacos/address/controller/ServerListController.java

@@ -16,6 +16,7 @@
 
 package com.alibaba.nacos.address.controller;
 
+import com.alibaba.nacos.api.annotation.Since;
 import com.alibaba.nacos.address.component.AddressServerGeneratorManager;
 import com.alibaba.nacos.api.common.Constants;
 import com.alibaba.nacos.api.naming.pojo.ServiceInfo;
@@ -65,6 +66,7 @@ public ServerListController(AddressServerGeneratorManager addressServerBuilderMa
      * @param cluster will get Ip list of that product cluster to be associated
      * @return result of get
      */
+    @Since("1.1.0")
     @RequestMapping(value = "/{product}/{cluster}", method = RequestMethod.GET)
     public ResponseEntity<String> getCluster(@PathVariable String product,
         @PathVariable String cluster) {

ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/controller/McpRegistryController.java

@@ -16,6 +16,7 @@
 
 package com.alibaba.nacos.airegistry.controller;
 
+import com.alibaba.nacos.api.annotation.Since;
 import com.alibaba.nacos.airegistry.form.GetServerForm;
 import com.alibaba.nacos.airegistry.form.ListServerForm;
 import com.alibaba.nacos.airegistry.form.ListServersNacosForm;
@@ -68,6 +69,7 @@ public McpRegistryController(NacosMcpRegistryService nacosMcpRegistryService) {
      * @return mcp server list {@link McpRegistryServerList}
      * @throws NacosApiException if request parameter is invalid or handle error
      */
+    @Since("3.2.1")
     @GetMapping(value = "/v0/servers")
     public McpRegistryServerList listMcpServers(ListServersNacosForm form)
         throws NacosApiException, NacosException {
@@ -106,6 +108,7 @@ public McpRegistryServerList listMcpServers(ListServersNacosForm form)
      * @return mcp server detail or McpErrorResponse when server not found.
      * @throws NacosApiException if request parameter is invalid or handle error
      */
+    @Since("3.2.1")
     @GetMapping(value = "/v0/servers/{name}/versions")
     public Object getServerVersions(@PathVariable String name, GetServerForm form,
         HttpServletResponse response)
@@ -136,6 +139,7 @@ public Object getServerVersions(@PathVariable String name, GetServerForm form,
      *         found.
      * @throws NacosException if handle error
      */
+    @Since("3.2.1")
     @GetMapping(value = "/v0/servers/{serverName}/versions/{version}")
     public Object getVersionedServer(@PathVariable String serverName, @PathVariable String version,
         GetServerForm form, HttpServletResponse response)

ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/controller/SkillsRegistryController.java

@@ -16,6 +16,7 @@
 
 package com.alibaba.nacos.airegistry.controller;
 
+import com.alibaba.nacos.api.annotation.Since;
 import com.alibaba.nacos.api.annotation.NacosApi;
 import com.alibaba.nacos.api.exception.NacosException;
 import com.alibaba.nacos.common.utils.StringUtils;
@@ -26,6 +27,7 @@
 import com.alibaba.nacos.airegistry.service.NacosSkillsRegistryService;
 import jakarta.servlet.http.HttpServletRequest;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.HttpHeaders;
 import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.util.AntPathMatcher;
@@ -52,6 +54,8 @@ public class SkillsRegistryController {
 
     private static final String WELL_KNOWN_SKILLS = BASE_PATH + "/{namespaceId}/.well-known/skills";
 
+    private static final String APPLICATION_ZIP_VALUE = "application/zip";
+    
     private static final AntPathMatcher PATH_MATCHER = new AntPathMatcher();
 
     private final NacosSkillsRegistryService nacosSkillsRegistryService;
@@ -67,12 +71,27 @@ public SkillsRegistryController(NacosSkillsRegistryService nacosSkillsRegistrySe
      * @return well-known index payload
      * @throws NacosException if query fails
      */
-    @GetMapping(value = {
-        WELL_KNOWN_AGENT_SKILLS + "/index.json",
-        WELL_KNOWN_SKILLS + "/index.json"
-    }, produces = MediaType.APPLICATION_JSON_VALUE)
-    public WellKnownSkillsIndex getIndex(@PathVariable String namespaceId) throws NacosException {
-        return nacosSkillsRegistryService.buildIndex(namespaceId);
+    @Since("3.2.2")
+    @GetMapping(value = WELL_KNOWN_AGENT_SKILLS + "/index.json",
+        produces = MediaType.APPLICATION_JSON_VALUE)
+    public WellKnownSkillsIndex getAgentSkillsIndex(@PathVariable String namespaceId)
+        throws NacosException {
+        return nacosSkillsRegistryService.buildAgentSkillsIndex(namespaceId);
+    }
+    
+    /**
+     * Expose legacy well-known index.json for v0.1-compatible clients.
+     *
+     * @param namespaceId namespace to query
+     * @return legacy well-known index payload
+     * @throws NacosException if query fails
+     */
+    @Since("3.2.2")
+    @GetMapping(value = WELL_KNOWN_SKILLS + "/index.json",
+        produces = MediaType.APPLICATION_JSON_VALUE)
+    public WellKnownSkillsIndex getLegacySkillsIndex(@PathVariable String namespaceId)
+        throws NacosException {
+        return nacosSkillsRegistryService.buildLegacySkillsIndex(namespaceId);
     }
 
     /**
@@ -84,6 +103,7 @@ public WellKnownSkillsIndex getIndex(@PathVariable String namespaceId) throws Na
      * @return search response with CLI-compatible shape
      * @throws NacosException if query fails
      */
+    @Since("3.2.1")
     @GetMapping(value = BASE_PATH + "/{namespaceId}/api/search",
         produces = MediaType.APPLICATION_JSON_VALUE)
     public SkillsSearchResponse search(@PathVariable String namespaceId, SkillsSearchForm form,
@@ -104,6 +124,7 @@ public SkillsSearchResponse search(@PathVariable String namespaceId, SkillsSearc
      * @return skill markdown when the skill is exportable, otherwise 404
      * @throws NacosException if query fails
      */
+    @Since("3.2.1")
     @GetMapping(value = {
         WELL_KNOWN_AGENT_SKILLS + "/{skillName}/SKILL.md",
         WELL_KNOWN_SKILLS + "/{skillName}/SKILL.md"
@@ -122,6 +143,32 @@ public ResponseEntity<String> getSkillMarkdown(@PathVariable String namespaceId,
             : ResponseEntity.ok().contentType(MediaType.TEXT_PLAIN).body(content);
     }
 
+    /**
+     * Return an exported skill archive for v0.2 well-known discovery.
+     *
+     * @param namespaceId namespace to query
+     * @param skillName skill name
+     * @return skill ZIP archive when exportable, otherwise 404
+     * @throws NacosException if query fails
+     */
+    @Since("3.2.2")
+    @GetMapping(value = {
+        WELL_KNOWN_AGENT_SKILLS + "/{skillName}.zip",
+        WELL_KNOWN_SKILLS + "/{skillName}.zip"
+    }, produces = APPLICATION_ZIP_VALUE)
+    public ResponseEntity<byte[]> getSkillArchive(@PathVariable String namespaceId,
+        @PathVariable String skillName)
+        throws NacosException {
+        byte[] content = nacosSkillsRegistryService.getSkillArchiveContent(namespaceId,
+            skillName);
+        return content == null ? ResponseEntity.notFound().build()
+            : ResponseEntity.ok()
+                .header(HttpHeaders.CONTENT_DISPOSITION,
+                    "attachment;filename=" + skillName + ".zip")
+                .contentType(MediaType.parseMediaType(APPLICATION_ZIP_VALUE))
+                .body(content);
+    }
+    
     /**
      * Return an exported text resource for a namespace skill.
      *
@@ -131,6 +178,7 @@ public ResponseEntity<String> getSkillMarkdown(@PathVariable String namespaceId,
      * @return file content when the skill and file are exportable, otherwise 404
      * @throws NacosException if query fails
      */
+    @Since("3.2.1")
     @GetMapping(value = {
         WELL_KNOWN_AGENT_SKILLS + "/{skillName}/**",
         WELL_KNOWN_SKILLS + "/{skillName}/**"

ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/model/skills/WellKnownSkillEntry.java

@@ -16,19 +16,30 @@
 
 package com.alibaba.nacos.airegistry.model.skills;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
+
 import java.util.List;
 
 /**
  * Well-known skill entry for the skills CLI.
  *
  * @author nacos
  */
+@JsonInclude(JsonInclude.Include.NON_NULL)
 public class WellKnownSkillEntry {
 
     private String name;
 
+    private String type;
+    
     private String description;
 
+    private String url;
+    
+    private String digest;
+    
+    private String version;
+    
     private List<String> files;
 
     public String getName() {
@@ -39,6 +50,14 @@ public void setName(String name) {
         this.name = name;
     }
 
+    public String getType() {
+        return type;
+    }
+    
+    public void setType(String type) {
+        this.type = type;
+    }
+    
     public String getDescription() {
         return description;
     }
@@ -47,6 +66,30 @@ public void setDescription(String description) {
         this.description = description;
     }
 
+    public String getUrl() {
+        return url;
+    }
+    
+    public void setUrl(String url) {
+        this.url = url;
+    }
+    
+    public String getDigest() {
+        return digest;
+    }
+    
+    public void setDigest(String digest) {
+        this.digest = digest;
+    }
+    
+    public String getVersion() {
+        return version;
+    }
+    
+    public void setVersion(String version) {
+        this.version = version;
+    }
+    
     public List<String> getFiles() {
         return files;
     }

ai-registry-adaptor/src/main/java/com/alibaba/nacos/airegistry/model/skills/WellKnownSkillsIndex.java

@@ -16,17 +16,32 @@
 
 package com.alibaba.nacos.airegistry.model.skills;
 
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
 import java.util.List;
 
 /**
  * Well-known skills index response for the skills CLI.
  *
  * @author nacos
  */
+@JsonInclude(JsonInclude.Include.NON_NULL)
 public class WellKnownSkillsIndex {
 
+    @JsonProperty("$schema")
+    private String schema;
+    
     private List<WellKnownSkillEntry> skills;
 
+    public String getSchema() {
+        return schema;
+    }
+    
+    public void setSchema(String schema) {
+        this.schema = schema;
+    }
+    
     public List<WellKnownSkillEntry> getSkills() {
         return skills;
     }