Skip to content

[ISSUE#14907] feat(ai): support targetVersion parameter for skill upload API #14979

Merged
KomachiSion merged 3 commits into
alibaba:developfrom
LiyunZhang10:fix-skill-upload-version-param
May 7, 2026
Merged

[ISSUE#14907] feat(ai): support targetVersion parameter for skill upload API #14979
KomachiSion merged 3 commits into
alibaba:developfrom
LiyunZhang10:fix-skill-upload-version-param

Conversation

@LiyunZhang10

@LiyunZhang10 LiyunZhang10 commented Apr 23, 2026

Copy link
Copy Markdown
Contributor

What is the purpose of the change

Closes #14907

When uploading a skill via ZIP file, if the ZIP content does not contain version information (neither in SKILL.md YAML front-matter nor meta.json), the version defaults to 0.0.1. This makes it impossible for users to specify a custom version during upload.

This PR adds an optional targetVersion request parameter to the skill upload API, allowing users to explicitly specify a version as a fallback.

Version resolution priority:
SKILL.md YAML front-matter > meta.json in ZIP > user-specified targetVersion > default "0.0.1"

Brief changelog

  • Added optional targetVersion parameter to SkillAdminController.uploadSkill() and ConsoleSkillController.uploadSkill()
  • Extended SkillOperationService interface with new overloaded uploadSkillFromZip methods that accept targetVersion
  • Updated SkillOperationServiceImpl.resolveUploadVersion() to use targetVersion as fallback
  • Updated SkillHandler interface and all implementations (SkillInnerHandler, SkillNoopHandler, SkillRemoteHandler)
  • Updated SkillProxy with new overloaded method
  • Added unit test testUploadSkillFromZipUsesTargetVersionWhenCannotInfer

Verifying this change

This change is already covered by existing tests and a new test case:

  • SkillOperationServiceImplTest#testUploadSkillFromZipUsesTargetVersionWhenCannotInfer — verifies that when ZIP content has no version info, the user-specified targetVersion is used.

Checklist

  • The code follows the project's coding style
  • Unit tests have been added for the new functionality
  • All existing tests pass
  • Backward compatibility is maintained (new parameter is optional, existing overloads delegate with null)

@github-actions

github-actions Bot commented Apr 23, 2026

Copy link
Copy Markdown

Thanks for your this PR. 🙏
Please check again for your PR changes whether contains any usage/api/configuration change such as Add new API , Add new configuration, Change default value of configuration.
If so, please add or update documents(markdown type) in docs/next/ for repository nacos-group/nacos-group.github.io

感谢您提交的PR。 🙏
请再次查看您的PR内容，确认是否包含任何使用方式/API/配置参数的变更，如：新增API、新增配置参数、修改默认配置等操作。
如果是，请确保在提交之前，在仓库nacos-group/nacos-group.github.io中的docs/next/目录下添加或更新文档（markdown格式）。

@LiyunZhang10 LiyunZhang10 mentioned this pull request Apr 23, 2026
Closed
@KomachiSion

KomachiSion commented Apr 24, 2026

Copy link
Copy Markdown
Collaborator

meta.info文件并非skill spec中定义的文件， 而是skillhub的自定义文件， 面向spec标准的话不应该支持。

不过nacos在规划新功能就是设置导入来源， 若是选择直接从skillhub导入的话， 在对应部分代码中是应该支持的。

但是不是通过文件上传导入支持， 文件上传导入还是应该面向标准

KomachiSion
KomachiSion requested changes Apr 24, 2026
View reviewed changes

@KomachiSion KomachiSion left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

如issue表述的， 针对meta.info这种非标准定义中的内容，不应该在文件导入中支持。

通过api和ui导入时指定版本号确实需要， 因此辛苦重新修改一下PR，仅api，ui导入时支持制定版本（可选项）。

顺序为：

frontmatter.metadata.version -> target version -> default version 0.0.1.

@LiyunZhang10

LiyunZhang10 commented Apr 24, 2026

Copy link
Copy Markdown
Contributor Author

okok, please review again

@KomachiSion

KomachiSion commented Apr 28, 2026

Copy link
Copy Markdown
Collaborator

@LiyunZhang10 Sorry for my mistack, I forgot loading meta.json is current supported features, might you rollback to old implementation.

@LiyunZhang10
[ISSUE#14907] feat(ai): support targetVersion parameter for skill upl…
45be3a7 
…oad API

Add optional targetVersion parameter to skill upload API and UI, allowing
users to specify a version when the ZIP content has no version info.

Version resolution priority:
  SKILL.md frontmatter -> meta.json in ZIP -> targetVersion -> default 0.0.1

Changes:
- Add targetVersion parameter to upload API endpoints (SkillAdminController,
  ConsoleSkillController)
- Thread targetVersion through SkillHandler, SkillProxy, SkillOperationService
- Add targetVersion as fallback in resolveUploadVersion after meta.json
- Add test for targetVersion fallback behavior
@LiyunZhang10
LiyunZhang10 force-pushed the fix-skill-upload-version-param branch from f65685f to 45be3a7 Compare April 28, 2026 08:20
@LiyunZhang10

LiyunZhang10 commented Apr 28, 2026

Copy link
Copy Markdown
Contributor Author

ok,please review again

@KomachiSion KomachiSion added kind/feature type/feature area/Skill area/Nacos console Related to Nacos consle labels Apr 29, 2026
@LiyunZhang10
fix(test): update SkillInnerHandlerTest to match 4-param uploadSkillF…
c6ea121 
…romZip signature

The uploadSkillFromZip method in SkillOperationService was updated to accept
a targetVersion parameter (4 params: namespaceId, zipBytes, overwrite, targetVersion).
The SkillInnerHandler delegates to this 4-param method, but the test was still
stubbing and verifying the old 3-param overload, causing a PotentialStubbingProblem
in Mockito strict mode.

Fix: update when() and verify() to use the 4-param signature with isNull() for targetVersion.
@KomachiSion

KomachiSion commented Apr 29, 2026

Copy link
Copy Markdown
Collaborator

Also please update the api document.

@codecov-commenter

codecov-commenter commented Apr 29, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 62.50000% with 6 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
...com/alibaba/nacos/console/proxy/ai/SkillProxy.java 0.00% 3 Missing ⚠️
...nacos/ai/service/skills/SkillOperationService.java 33.33% 2 Missing ⚠️
...nsole/controller/v3/ai/ConsoleSkillController.java 0.00% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@LiyunZhang10 LiyunZhang10 mentioned this pull request Apr 30, 2026
Merged
3 tasks
@LiyunZhang10

LiyunZhang10 commented Apr 30, 2026

Copy link
Copy Markdown
Contributor Author

Docs PR submitted: nacos-group/nacos-group.github.io#1077

@KomachiSion KomachiSion added this to the 3.2.2 milestone May 7, 2026
@KomachiSion
KomachiSion merged commit afba480 into alibaba:develop May 7, 2026
4 checks passed
KomachiSion pushed a commit to nacos-group/nacos-group.github.io that referenced this pull request May 7, 2026
@LiyunZhang10
docs(ai): add targetVersion parameter to skill upload APIs (#1077)
3ae11bc 
The skill upload REST APIs (/nacos/v3/admin/ai/skills/upload and
/v3/console/ai/skills/upload) now accept an optional targetVersion form
field. Version resolution order:
  SKILL.md frontmatter metadata.version
  -> meta.json in ZIP
  -> targetVersion parameter
  -> default 0.0.1

Aligns docs with nacos PR alibaba/nacos#14979.

Co-authored-by: LiyunZhang10 <LiyunZhang10@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@KomachiSion KomachiSion KomachiSion approved these changes

Assignees

No one assigned

Labels

area/Nacos console Related to Nacos consle area/Skill kind/feature type/feature

Projects

None yet

Milestone

3.2.2

Development

Successfully merging this pull request may close these issues.

3.2.1版本，目前不能在上传skill的时候指定版本号

3 participants

@LiyunZhang10 @KomachiSion @codecov-commenter