Fix Nacos skill marketplace latest label resolution

[lancefoever]

AgentScope-Java Version

main branch

Description

Background

When using the Builder Nacos marketplace, skill preview/install can fail while loading a skill version detail.

The previous implementation passed the label name LATEST directly as the version argument to getSkillVersionDetail(namespaceId, skillName, version). However, the Nacos skill version detail API expects the actual skill version value, not the label name.

This could produce a request equivalent to:

/nacos/v3/admin/ai/skills/version?skillName=<skillName>&namespaceId=<namespaceId>&version=LATEST

Nacos then returns an error similar to:

Skill version not found: <skillName>@LATEST

Purpose

This PR fixes Nacos-backed Builder marketplace preview/install by resolving the real skill version from the skill metadata labels before loading the skill version detail.

Changes Made

• Load skill metadata through the Nacos maintainer client.
• Resolve the actual skill version from the LATEST label in the skill metadata.
• Use the resolved version value when calling getSkillVersionDetail(...).
• Add validation so a clear error is raised if the LATEST label cannot be resolved.

How to Test

1. Start a Nacos server with Skill Registry support.
2. Create or publish a Nacos skill with a LATEST label pointing to an online skill version.
3. Add the Nacos marketplace in Builder.
4. Preview the Nacos skill from Builder.
5. Install the skill into an agent.

Expected result:

• Builder no longer requests skill details with version=LATEST.
• Builder resolves the actual skill version from Nacos skill metadata.
• Skill preview succeeds.
• Skill installation succeeds.
• The installed skill appears in the agent's skills list.

Local validation:

mvn -q -pl agentscope-examples/agents/agentscope-builder -am spotless:apply
mvn -q -pl agentscope-examples/agents/agentscope-builder -am -DskipTests compile

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[AgentScopeJavaBot]

🤖 AI Review

This PR correctly identifies the root cause — Nacos's getSkillVersionDetail API expects an actual version string, not a label name — and routes the call through getSkillMeta first to resolve a real version from the labels map. The control flow, null/blank guards, and the clear IllegalStateException on unresolvable labels are all reasonable.

However, the fix as written likely will not work end-to-end against Nacos's standard publish flow. In Nacos (com.alibaba.nacos.ai.constant.AiResourceConstants) the canonical label key for the latest published version is "latest" (lowercase), set automatically by SkillOperationServiceImpl#publish(...) when updateLatestLabel=true. The PR reuses the existing LATEST_VERSION = "LATEST" (uppercase) constant as the lookup key into skillMeta.getLabels(), which will miss the canonical label and trip the new IllegalStateException for any skill published the normal way. The test steps in the PR description ("create a skill with a LATEST label") effectively work around the bug by asking the tester to set a non-standard label.

Secondary items: the class Javadoc still describes the old getSkillVersionDetail(..., "LATEST") behavior and should be refreshed; the constant LATEST_VERSION is now semantically a label key, not a version, so renaming it (e.g. to LATEST_LABEL) keeps intent clear.

[AgentScopeJavaBot]

All previously raised review comments have been addressed.