AgentScope Java 2.0 技能仓库（Skill Repository）完全实战指南

1.集成生态全景解析：构建企业级智能体系统的集成之道

2.长期记忆集成深度解析：让智能体真正"记住"用户

3.Agent 状态存储（AgentStateStore）深度解析：构建可恢复、可扩展的智能体运行时

4.RAG 知识库集成全攻略：从自建向量库到第三方平台，一篇讲透

5.技能仓库（Skill Repository）完全实战指南

6.协议集成全景解析：A2A、AG-UI、Agent Protocol 三大开放协议实战指南

7.集成 Higress AI 网关：智能体流量治理的生产级实战

8.深度集成 Nacos：智能体注册发现、技能管理与动态治理全实战

9.集成 Scheduler 调度器：让智能体"按时上班"的生产级定时调度实战

10.集成 Chat Completions Web：一行依赖让你的 Agent 变身 OpenAI 兼容服务

11.集成在线训练（Training）：让你的 Agent 越用越聪明

一、背景与设计理念

在构建企业级 AI Agent 应用时，智能体能力的可复用性、版本化管理与动态分发是工程化落地的核心瓶颈。传统做法往往将 Prompt、工具定义硬编码在业务代码中，导致：

技能无法跨项目复用
修改一个 Prompt 需要重新编译部署
多人协作缺乏审阅与版本追踪机制

AgentScope Java v2 提出的 技能仓库（Skill Repository） 机制，通过标准化的 AgentSkill 格式与可插拔的存储抽象，系统性地解决了上述问题。

二、核心抽象

2.1 AgentSkill：Markdown as Code

AgentSkill 是 AgentScope 用 Markdown + 资源文件 来描述一个可复用"技能"的标准格式。一个技能通常包含：

SKILL.md：技能的核心描述文件（System Prompt、Few-shot Examples、工具调用规范等）
资源文件（可选）：截图、模板、JSON Schema 等辅助文件，与技能主文件级联管理

这种设计将提示词工程从代码中彻底解耦，使得非技术人员也能通过编辑 Markdown 参与技能维护，同时保留了版本控制与 Diff 审查的能力。

2.2 AgentSkillRepository：可插拔的存储抽象

AgentSkillRepository 接口负责把技能从外部存储里加载进来，再交给 Toolkit / ReActAgent 使用。其核心方法包括：

方法	说明
getAllSkills()	获取全部技能列表
getSkill(name)	按名称获取单个技能
getAllSkillNames()	获取所有技能名称
skillExists(name)	判断技能是否存在
save(skills, overwrite)	写入/更新技能（upsert 语义）
delete(name)	删除技能

无论底层使用何种存储，上层业务代码保持完全一致，实现了技能定义与业务逻辑的彻底分离。

三、三大官方存储后端对比

agentscope-extensions-* 仓库提供了以下开箱即用的实现：

扩展实现	后端存储	核心优势	适用场景
Git Repository	远程 Git 仓库用	Git 流程管控技能版本，跨团队共享	版本治理、Code Review、跨项目复用
MySQL Repository	MySQL 数据库	通过控制台/业务系统在线编辑、动态发布	管理后台运营、高频调整、事务边界
PostgreSQL Repository	PostgreSQL 数据库	已有 PG 基础设施，在线编辑、动态发布	PG 技术栈团队、Schema 级隔离

💡 生态补充：Nacos 也提供了一个 AgentSkillRepository 实现，适合已深度集成 Nacos 作为配置中心的团队。

四、Git 技能仓库详解

4.1 何时使用

想用 Git 来管控技能内容的版本与审阅
想跨多个项目共享同一份技能集
不希望在生产服务里嵌入数据库或配置中心

4.2 添加依赖

xml 复制代码

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-git-repository</artifactId>
    <version>${agentscope.version}</version>
</dependency>

底层使用 JGit，HTTPS / SSH 都支持。

4.3 快速上手

java 复制代码

import io.agentscope.core.skill.repository.GitSkillRepository;
import io.agentscope.core.skill.AgentSkill;

// 公开仓库 + 默认分支，使用临时目录
GitSkillRepository repo = new GitSkillRepository(
    "https://github.com/agentscope/skills.git"
);

// 取出全部技能注册到 Toolkit
Toolkit toolkit = new Toolkit();
repo.getAllSkills().forEach(toolkit::registerSkill);

// 应用退出时清理临时目录
Runtime.getRuntime().addShutdownHook(new Thread(repo::close));

4.4 选定分支 / 自定义本地路径

java 复制代码

GitSkillRepository repo = new GitSkillRepository(
    "https://github.com/agentscope/skills.git",
    "develop",                   // 分支
    Path.of("/var/skills/repo"), // 本地路径（null = 临时目录）
    "agentscope-public",         // source 标识（在 Toolkit 里能看到）
    true                         // autoSync = true，每次读自动检查并 pull
);

4.5 私有仓库的鉴权

GitSkillRepository 复用系统级 Git 配置，不在 Java 侧管理凭证：

协议	鉴权方式
HTTPS	使用 ~/.gitconfig 里的 credential helper（osxkeychain、libsecret 等）
SSH	使用 ~/.ssh/ 下的密钥与 ssh-agent

java 复制代码

// SSH 私有仓库
GitSkillRepository repo = new GitSkillRepository(
    "git@github.com:my-org/private-skills.git"
);

⚠️ CI 环境下请确保 runner 用户具备相应凭证或挂载好 SSH agent。

4.6 自动同步与手动同步

模式	行为
autoSync=true（默认）	getSkill / getAllSkills / skillExists 等读操作前会先 ls-remote，如远端有更新才执行 pull
autoSync=false	完全不自动 pull，要刷新时手动调用 repo.sync()

java 复制代码

GitSkillRepository repo = new GitSkillRepository(remoteUrl, false);
repo.sync();              // 启动时同步一次
schedule(() -> repo.sync(), 5, TimeUnit.MINUTES);  // 定时同步

4.7 工程实践建议

建议在 Spring Bean 上以单例形式持有仓库，重启时统一 close()
临时目录会注册 JVM Shutdown Hook 自动删除；如果你强制 kill 进程，可能残留，需要外部清理
多实例部署时各自维护一份本地 clone，没有锁竞争

五、MySQL 技能仓库详解

5.1 何时使用

通过管理后台在线运营技能，希望"改完即生效"
已经有 MySQL 基础设施，不想再引入 Git 依赖
需要把技能存储和业务数据放在同一事务边界

5.2 添加依赖

xml 复制代码

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-mysql-repository</artifactId>
    <version>${agentscope.version}</version>
</dependency>

5.3 快速上手

java 复制代码

import com.zaxxer.hikari.HikariDataSource;
import io.agentscope.core.skill.repository.mysql.MysqlSkillRepository;

HikariDataSource ds = new HikariDataSource();
ds.setJdbcUrl("jdbc:mysql://localhost:3306/agentscope");
ds.setUsername("root");
ds.setPassword("password");

// 第二参数 createIfNotExist=true：自动建库建表
MysqlSkillRepository repo = new MysqlSkillRepository(ds, true);

Toolkit toolkit = new Toolkit();
repo.getAllSkills().forEach(toolkit::registerSkill);

5.4 表结构

createIfNotExist=true 时自动创建以下两张表：

sql 复制代码

CREATE TABLE IF NOT EXISTS agentscope_skills (
    id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL UNIQUE,
    description TEXT NOT NULL,
    skill_content LONGTEXT NOT NULL,
    source VARCHAR(255) NOT NULL,
    metadata_json LONGTEXT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE TABLE IF NOT EXISTS agentscope_skill_resources (
    id BIGINT NOT NULL,
    resource_path VARCHAR(500) NOT NULL,
    resource_content LONGTEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id, resource_path),
    FOREIGN KEY (id) REFERENCES agentscope_skills(id) ON DELETE CASCADE
) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

表名	用途
agentscope_skills	技能本身，name 唯一，skill_content 存 SKILL.md 全文
agentscope_skill_resources	技能附带的资源文件（截图、模板等），与 id 级联删除

5.5 与已有表兼容

旧表如果没有 metadata_json 列，仓库会自动降级 到"只往返 name + description"的兼容模式，不会主动 ALTER TABLE。

想升级到完整模式，自行执行：

sql 复制代码

ALTER TABLE agentscope_skills ADD COLUMN metadata_json LONGTEXT NULL;

5.6 自定义库名 / 表名

java 复制代码

MysqlSkillRepository repo = new MysqlSkillRepository(
    ds,
    "skill_center",          // 库名
    "ops_skills",            // 技能表
    "ops_skill_resources",   // 资源表
    true                     // 自动建库建表
);

5.7 CRUD 操作

java 复制代码

// 写入（save 是 upsert：name 已存在则更新）
AgentSkill skill = ...;
repo.save(List.of(skill), /* overwrite */ true);

// 读取
AgentSkill loaded = repo.getSkill("calculator");
List<String> names = repo.getAllSkillNames();
boolean exists = repo.skillExists("calculator");

// 删除
repo.delete("calculator");

写入与删除都在事务里执行，资源表的 ON DELETE CASCADE 保证不会出现孤儿资源。

六、PostgreSQL 技能仓库详解

6.1 何时使用

通过管理后台在线运营技能，希望"改完即生效"
已经有 PostgreSQL 基础设施，不想再引入 Git 依赖
需要把技能存储和业务数据放在同一事务边界

6.2 添加依赖

xml 复制代码

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-postgresql-repository</artifactId>
    <version>${agentscope.version}</version>
</dependency>

6.3 快速上手

java 复制代码

import javax.sql.DataSource;
import io.agentscope.core.skill.repository.postgresql.PostgresSkillRepository;

DataSource ds = ...;  // HikariCP、PgBouncer 等连接池

// createIfNotExist=true：自动建 schema 和表；writeable=true：允许写入
PostgresSkillRepository repo = new PostgresSkillRepository(ds, true, true);

Toolkit toolkit = new Toolkit();
repo.getAllSkills().forEach(toolkit::registerSkill);

6.4 使用 Builder 模式

java 复制代码

PostgresSkillRepository repo = PostgresSkillRepository.builder(ds)
    .schemaName("my_schema")
    .skillsTableName("my_skills")
    .resourcesTableName("my_resources")
    .createIfNotExist(true)
    .writeable(true)
    .build();

6.5 表结构

createIfNotExist=true 时自动创建以下两张表（在指定 schema 下）：

sql 复制代码

CREATE TABLE IF NOT EXISTS "agentscope"."agentscope_skills" (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL UNIQUE,
    description TEXT NOT NULL,
    skill_content TEXT NOT NULL,
    source VARCHAR(255) NOT NULL,
    metadata_json TEXT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE IF NOT EXISTS "agentscope"."agentscope_skill_resources" (
    id BIGINT NOT NULL,
    resource_path VARCHAR(500) NOT NULL,
    resource_content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (id, resource_path),
    FOREIGN KEY (id) REFERENCES "agentscope"."agentscope_skills"(id) ON DELETE CASCADE
);

与 MySQL 版的关键区别：PostgreSQL 使用 schema（而非 database）作为命名空间隔离边界，数据库由 JDBC URL 决定。

6.6 与已有表兼容

旧表如果没有 metadata_json 列，仓库会自动降级到"只往返 name + description"的兼容模式，不会主动 ALTER TABLE。

升级方式：

sql 复制代码

ALTER TABLE "agentscope"."agentscope_skills" ADD COLUMN metadata_json TEXT NULL;

6.7 CRUD 操作

java 复制代码

// 写入（save 是 upsert：name 已存在则更新）
AgentSkill skill = ...;
repo.save(List.of(skill), /* overwrite */ true);

// 读取
AgentSkill loaded = repo.getSkill("calculator");
List<String> names = repo.getAllSkillNames();
boolean exists = repo.skillExists("calculator");

// 删除
repo.delete("calculator");

写入与删除都在事务里执行，资源表的 ON DELETE CASCADE 保证不会出现孤儿资源。

6.8 Builder 配置参数一览

方法	说明	默认值
schemaName(String)	Schema 名称	agentscope
skillsTableName(String)	技能表名	agentscope_skills
resourcesTableName(String)	资源表名	agentscope_skill_resources
createIfNotExist(boolean)	自动 CREATE SCHEMA + CREATE TABLE	true
writeable(boolean)	是否允许写操作	true

七、统一接入范式

无论选择哪种后端，上层集成代码完全一致：

java 复制代码

AgentSkillRepository repo = ...;        // 任选一种实现
List<AgentSkill> skills = repo.getAllSkills();

Toolkit toolkit = new Toolkit();
skills.forEach(toolkit::registerSkill);

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .toolkit(toolkit)
    .build();

多源聚合

同一个 Toolkit 可注册来自多个 Repository 的技能：

java 复制代码

// 核心技能从 Git 加载，保证稳定性
GitSkillRepository gitRepo = new GitSkillRepository(
    "https://github.com/org/core-skills.git"
);

// 运营技能从 MySQL 加载，保证灵活性
MysqlSkillRepository dbRepo = new MysqlSkillRepository(ds, true);

Toolkit toolkit = new Toolkit();
gitRepo.getAllSkills().forEach(toolkit::registerSkill);
dbRepo.getAllSkills().forEach(toolkit::registerSkill);

八、选型决策指南

决策维度	推荐方案	关键理由
需要 PR/MR 流程管控、可读可 Review	Git	天然融入软件工程治理体系
要在管理后台/配置中心动态修改、立即生效	MySQL / PostgreSQL / Nacos	修改即时生效，支持 CRUD API
已有 PostgreSQL 基础设施	PostgreSQL	复用现有连接池，Schema 级隔离
需要与业务数据同事务边界	MySQL / PostgreSQL	数据库原生事务支持
多种来源混用	组合多个 Repository	实现 AgentSkillRepository 自己组合，或多个 repo 都注册到 toolkit

九、MySQL vs PostgreSQL 实现差异对比

对比维度	MySQL 实现	PostgreSQL 实现
命名空间隔离	Database（库名）	Schema
主键策略	AUTO_INCREMENT	B
大文本类型	LONGTEXT	TEXT
表名自定义	构造函数参数	Builder 模式
自动建库/表	支持（createIfNotExist）	支持（CREATE SCHEMA + CREATE TABLE）
写入控制	无额外参数	writeable 参数（可设为只读）
兼容降级	缺 metadata_json 自动降级	缺 metadata_json 自动降级

十、生产环境最佳实践

10.1 Git 模式

使用语义化 Tag（如 v1.2.0）锁定生产版本，避免 main 分支不稳定变更影响线上
在 CI 流水线中加入 Markdown Lint 与 Front Matter Schema 校验
以 Spring 单例 Bean 持有 Repository，确保生命周期管理
多实例部署无需担心锁竞争，各自维护本地 clone

10.2 DB 模式（MySQL / PostgreSQL）

合理配置连接池（推荐 HikariCP），避免技能读取成为性能瓶颈
对 name 字段建立唯一索引（建表已自动包含）
对接管理后台时，建议增加操作日志与回滚机制
利用 metadata_json 字段存储标签、分类等元数据，支持精细化检索

10.3 通用建议

单个技能加载失败不应阻断整个 Repository 初始化，做好异常隔离
在监控系统中对技能加载耗时、失败率设置告警
安全合规：Git 使用 Deploy Key / PAT；DB 连接启用 SSL 加密传输
考虑实现自定义 AgentSkillRepository 对接内部私有系统（仅需实现接口方法）

十一、总结

AgentScope Java 的技能仓库机制，通过标准化的 Markdown 描述与可插拔的存储后端，将 AI Agent 的能力建设从"硬编码"推向了 "配置化"与"资产化"：

Git 保障了治理严谨性------版本追踪、Code Review、变更审计
MySQL / PostgreSQL 赋予了运行时灵活性------改完即生效、事务一致性
统一的接口抽象 让切换与组合变得零成本

对于正在构建复杂多智能体系统的团队而言，这是实现能力沉淀、复用与规模化治理的关键基础设施。