Microservices Engine：AI Registry Skill 快速上手指南

匯入已有 Skill

在 Skill 列表頁點擊 匯入 Skill，系統支援兩種匯入方式：

• 匯入預置 Skill：系統內建了官方預置 Skill 模板，可直接勾選需要的 Skill 一鍵匯入。

• 上傳檔案：將本地 Skill 目錄打包為 ZIP 檔案上傳。

匯入後系統自動產生草稿版本。

建立 Skill

1. 在左側導覽列選擇 AI 資源管理 > Skill，在頁面頂部的工作空間下拉框中選擇目標工作空間。

2. 點擊右上方 + 建立 Skill。

3. 填寫基礎資訊：

   配置項	是否必填	說明
   Skill 名稱	是	最多 64 個字元，僅支援字母、數字、底線和中劃線
   描述	是	最多 1000 個字元，描述 Skill 的功能和用途
   標籤	否	輸入後按斷行符號確認，用於業務分類和檢索

4. 展開 進階選項 可設定可見度：私人（預設，僅自己可見）或 公開（所有人可見）。

5. 在編輯器中編寫 SKILL.md（必填）。SKILL.md 使用 Markdown 格式，左側編輯右側即時預覽。基本結構如下：

   • name（必填）：Skill 名稱，用於標識

   • description（必填）：用途描述，說明 Skill 的功能和適用情境

   • instructions（必填）：核心指令，定義 Agent 如何使用該 Skill

   • 可選欄位：tools（工具列表）、dependencies（依賴項）等

6. 編輯完成後，點擊右上方 立即建立。

選擇整合方式

配置 VPC 私網訪問

如果選擇公網訪問，可跳過本小節，直接使用公網訪問配置指南中的存取點網域名稱作為後續host/ serverAddr。

如果選擇VPC 私網訪問，可在 AI治理中心控制台「接入管理」中一鍵關聯 VPC，系統自動完成 PrivateLink 終端節點配置，無需手動到 VPC 控制台建立終端節點。

前提條件：

• 已在目標地區建立 VPC（參考 建立/刪除專用網路與交換器）

• 已建立用於部署應用的 VPC 和交換器。如尚未建立，請參考建立專用網路和交換器

• 已建立安全性群組。如尚未建立，請參考建立安全性群組

配置步驟：

1. 登入 MSE 控制台，在左側導覽列選擇 AI Registry > 接入管理。

2. 在 VPC 接入 地區點擊右上方 + 關聯 VPC。

3. 在彈窗中按以下參數配置：

   配置項	說明
   選擇 VPC	選擇已建立的目標 VPC
   可用性區域與交換器	選擇 VPC 內的可用性區域及對應交換器，可點擊 + 添加交換器 配置多個；建議至少選擇兩個可用性區域以具備高可用能力
   安全性群組	選擇允許 VPC 內訪問的安全性群組
   描述	可選，便於識別該接入記錄

4. 點擊 確認關聯。系統自動建立 VPC 端點，通常 1～2 分鐘生效，狀態變為 可用 即接入完成。

驗證連通性：

接入完成後，VPC 接入 地區頂部展示當前地區的私網訪問網域名稱。若 VPC 內已有 ECS 執行個體，可在 ECS 上執行以下命令驗證：

# 測試網路連通性（以杭州地區為例）
ping -c 4 airegistry.cn-hangzhou.mse.aliyuncs.com

方式 A：Nacos CLI

憑證配置： 在運行用戶端的裝置上執行以下命令配置登入憑證：

npx @nacos-group/cli profile edit

按提示填寫：

驗證串連：

npx @nacos-group/cli skill-list

若返回 Skill 列表或空列表，說明配置成功。

下載 Skill： 支援 QwenPaw、Qoder、Claude、Codex、Cursor 等多種 AI 編程工具。在控制台 Skill 詳情頁選擇對應工具後，頁面自動產生對應命令，複製執行即可：

# 下載最新版本
npx @nacos-group/cli skill-get <skill-name>

# 下載指定版本
npx @nacos-group/cli skill-get <skill-name> --version 1.0.0 -o ~/my-skills

# 按標籤下載
npx @nacos-group/cli skill-get <skill-name> --label latest

方式 B：Java SDK

添加依賴：

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>${nacos.version}</version>
</dependency>

初始化 AiService：

將 SERVER_ADDR 替換為公網存取點網域名稱或私網網域名稱。

Properties properties = new Properties();
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "airegistry.cn-hangzhou.mse.aliyuncs.com:80");
properties.setProperty(PropertyKeyConst.NAMESPACE, "xxxxxx-xxxx-xxxx-xxxx-xxxxxx");
properties.setProperty(PropertyKeyConst.ACCESS_KEY, "LTAI5tXXXXXXXXXXXXXX");
properties.setProperty(PropertyKeyConst.SECRET_KEY, "XXXXXXXXXXXXXXXXXXXXxx");

AiService aiService = AiFactory.createAiService(properties);

一個 AiService 執行個體對應一個命名空間。訪問多個命名空間時需分別建立執行個體；應用內盡量複用同一執行個體，退出時調用 shutdown() 釋放資源。

下載 Skill ZIP：

SDK 提供按名稱、按版本、按標籤三種下載方式，返回 ZIP 位元組數組（byte[]），包含 SKILL.md 和全部資源檔（二進位資源自動從 Base64 解碼）。

try {
    // 下載最新版本
    byte[] skillZip = aiService.downloadSkillZip("my-first-skill");

    // 下載指定版本
    byte[] skillZipByVer = aiService.downloadSkillZipByVersion("my-first-skill", "1.0.0");

    // 按標籤下載
    byte[] skillZipByLabel = aiService.downloadSkillZipByLabel("my-first-skill", "latest");
} catch (NacosException e) {
    e.printStackTrace();
}

訂閱 Skill 變更：

通過 subscribeSkill 訂閱 Skill 更新，當 ZIP 內容變化時通過監聽器回調。version、label 可選，用於限定訂閱範圍：

try {
    aiService.subscribeSkill("my-first-skill", null, null, new AbstractNacosSkillListener() {
        @Override
        public void onEvent(SkillEvent event) {
            byte[] newZip = event.getSkillZip();
            System.out.println("skill updated, size: " + newZip.length);
        }
    });
} catch (NacosException e) {
    e.printStackTrace();
}

方式 C：AgentScope

通過 agentscope-extensions-nacos-skill 模組在 AgentScope 架構中使用 AI 治理中心的 Skill。

添加依賴：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-nacos-skill</artifactId>
</dependency>

完整樣本（複製即用）：

將 SERVER_ADDR 替換為公網存取點網域名稱或私網網域名稱。

import com.alibaba.nacos.api.PropertyKeyConst;
import com.alibaba.nacos.api.ai.AiFactory;
import com.alibaba.nacos.api.ai.AiService;
import io.agentscope.core.ReActAgent;
import io.agentscope.core.model.DashScopeChatModel;
import io.agentscope.core.message.Msg;
import io.agentscope.core.nacos.skill.NacosSkillRepository;
import io.agentscope.core.skill.AgentSkill;
import io.agentscope.core.skill.SkillBox;
import java.util.Properties;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // 1. 串連 AI Registry
        Properties props = new Properties();
        props.put(PropertyKeyConst.SERVER_ADDR, "airegistry.cn-hangzhou.mse.aliyuncs.com:80");
        props.put(PropertyKeyConst.NAMESPACE, "xxxxxx-xxxx-xxxx-xxxx-xxxxxx");
        props.put(PropertyKeyConst.ACCESS_KEY, "your-access-key");
        props.put(PropertyKeyConst.SECRET_KEY, "your-secret-key");
        AiService aiService = AiFactory.createAiService(props);

        // 2. 載入 Skill
        NacosSkillRepository repo = new NacosSkillRepository(aiService, "public");
        AgentSkill skill = repo.getSkill("my-first-skill");

        // 3. 綁定到 Agent
        SkillBox skillBox = new SkillBox(repo);
        ReActAgent agent = ReActAgent.builder()
                .name("MyAgent")
                .model(DashScopeChatModel.builder()
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .modelName("qwen-max")
                        .build())
                .skillBox(skillBox)
                .build();

        // 4. 對話
        Msg response = agent.call(Msg.of("你好"));
        System.out.println(response.getText());

        aiService.shutdown();
    }
}

支援按版本（AGENTSCOPE_NACOS_SKILL_VERSION）或標籤（AGENTSCOPE_NACOS_SKILL_LABEL）篩選具體版本，倉庫為唯讀。

更多配置選項和進階用法請參考 AgentScope 對接 Nacos AI Registry 使用 Skill。