一、背景与设计理念在构建企业级 AI Agent 应用时智能体能力的可复用性、版本化管理与动态分发是工程化落地的核心瓶颈。传统做法往往将 Prompt、工具定义硬编码在业务代码中导致技能无法跨项目复用修改一个 Prompt 需要重新编译部署多人协作缺乏审阅与版本追踪机制AgentScope Java v2 提出的技能仓库Skill Repository机制通过标准化的 AgentSkill 格式与可插拔的存储抽象系统性地解决了上述问题。二、核心抽象2.1 AgentSkillMarkdown as CodeAgentSkill 是 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 RepositoryMySQL 数据库通过控制台/业务系统在线编辑、动态发布管理后台运营、高频调整、事务边界PostgreSQL RepositoryPostgreSQL 数据库已有 PG 基础设施在线编辑、动态发布PG 技术栈团队、Schema 级隔离 生态补充Nacos 也提供了一个 AgentSkillRepository 实现适合已深度集成 Nacos 作为配置中心的团队。四、Git 技能仓库详解4.1 何时使用想用 Git 来管控技能内容的版本与审阅想跨多个项目共享同一份技能集不希望在生产服务里嵌入数据库或配置中心4.2 添加依赖dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-skill-git-repository/artifactIdversion${agentscope.version}/version/dependency底层使用 JGitHTTPS / SSH 都支持。4.3 快速上手importio.agentscope.core.skill.repository.GitSkillRepository;importio.agentscope.core.skill.AgentSkill;// 公开仓库 默认分支使用临时目录GitSkillRepositoryreponewGitSkillRepository(https://github.com/agentscope/skills.git);// 取出全部技能注册到 ToolkitToolkittoolkitnewToolkit();repo.getAllSkills().forEach(toolkit::registerSkill);// 应用退出时清理临时目录Runtime.getRuntime().addShutdownHook(newThread(repo::close));4.4 选定分支 / 自定义本地路径GitSkillRepositoryreponewGitSkillRepository(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 helperosxkeychain、libsecret 等SSH使用 ~/.ssh/ 下的密钥与 ssh-agent// SSH 私有仓库GitSkillRepositoryreponewGitSkillRepository(gitgithub.com:my-org/private-skills.git);⚠️ CI 环境下请确保 runner 用户具备相应凭证或挂载好 SSH agent。4.6 自动同步与手动同步模式行为autoSynctrue默认getSkill / getAllSkills / skillExists 等读操作前会先 ls-remote如远端有更新才执行 pullautoSyncfalse完全不自动 pull要刷新时手动调用 repo.sync()GitSkillRepositoryreponewGitSkillRepository(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 添加依赖dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-skill-mysql-repository/artifactIdversion${agentscope.version}/version/dependency5.3 快速上手importcom.zaxxer.hikari.HikariDataSource;importio.agentscope.core.skill.repository.mysql.MysqlSkillRepository;HikariDataSourcedsnewHikariDataSource();ds.setJdbcUrl(jdbc:mysql://localhost:3306/agentscope);ds.setUsername(root);ds.setPassword(password);// 第二参数 createIfNotExisttrue自动建库建表MysqlSkillRepositoryreponewMysqlSkillRepository(ds,true);ToolkittoolkitnewToolkit();repo.getAllSkills().forEach(toolkit::registerSkill);5.4 表结构createIfNotExisttrue 时自动创建以下两张表CREATETABLEIFNOTEXISTSagentscope_skills(idBIGINTNOTNULLAUTO_INCREMENTPRIMARYKEY,nameVARCHAR(255)NOTNULLUNIQUE,descriptionTEXTNOTNULL,skill_contentLONGTEXTNOTNULL,sourceVARCHAR(255)NOTNULL,metadata_jsonLONGTEXTNULL,created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,updated_atTIMESTAMPDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP)DEFAULTCHARACTERSETutf8mb4COLLATEutf8mb4_unicode_ci;CREATETABLEIFNOTEXISTSagentscope_skill_resources(idBIGINTNOTNULL,resource_pathVARCHAR(500)NOTNULL,resource_contentLONGTEXTNOTNULL,created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,updated_atTIMESTAMPDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP,PRIMARYKEY(id,resource_path),FOREIGNKEY(id)REFERENCESagentscope_skills(id)ONDELETECASCADE)DEFAULTCHARACTERSETutf8mb4COLLATEutf8mb4_unicode_ci;表名用途agentscope_skills技能本身name 唯一skill_content 存 SKILL.md 全文agentscope_skill_resources技能附带的资源文件截图、模板等与 id 级联删除5.5 与已有表兼容旧表如果没有 metadata_json 列仓库会自动降级到只往返 name description的兼容模式不会主动 ALTER TABLE。想升级到完整模式自行执行ALTERTABLEagentscope_skillsADDCOLUMNmetadata_jsonLONGTEXTNULL;5.6 自定义库名 / 表名MysqlSkillRepositoryreponewMysqlSkillRepository(ds,skill_center,// 库名ops_skills,// 技能表ops_skill_resources,// 资源表true// 自动建库建表);5.7 CRUD 操作// 写入save 是 upsertname 已存在则更新AgentSkillskill...;repo.save(List.of(skill),/* overwrite */true);// 读取AgentSkillloadedrepo.getSkill(calculator);ListStringnamesrepo.getAllSkillNames();booleanexistsrepo.skillExists(calculator);// 删除repo.delete(calculator);写入与删除都在事务里执行资源表的 ON DELETE CASCADE 保证不会出现孤儿资源。六、PostgreSQL 技能仓库详解6.1 何时使用通过管理后台在线运营技能希望改完即生效已经有 PostgreSQL 基础设施不想再引入 Git 依赖需要把技能存储和业务数据放在同一事务边界6.2 添加依赖dependencygroupIdio.agentscope/groupIdartifactIdagentscope-extensions-skill-postgresql-repository/artifactIdversion${agentscope.version}/version/dependency6.3 快速上手importjavax.sql.DataSource;importio.agentscope.core.skill.repository.postgresql.PostgresSkillRepository;DataSourceds...;// HikariCP、PgBouncer 等连接池// createIfNotExisttrue自动建 schema 和表writeabletrue允许写入PostgresSkillRepositoryreponewPostgresSkillRepository(ds,true,true);ToolkittoolkitnewToolkit();repo.getAllSkills().forEach(toolkit::registerSkill);6.4 使用 Builder 模式PostgresSkillRepositoryrepoPostgresSkillRepository.builder(ds).schemaName(my_schema).skillsTableName(my_skills).resourcesTableName(my_resources).createIfNotExist(true).writeable(true).build();6.5 表结构createIfNotExisttrue 时自动创建以下两张表在指定 schema 下CREATETABLEIFNOTEXISTSagentscope.agentscope_skills(id BIGSERIALPRIMARYKEY,nameVARCHAR(255)NOTNULLUNIQUE,descriptionTEXTNOTNULL,skill_contentTEXTNOTNULL,sourceVARCHAR(255)NOTNULL,metadata_jsonTEXTNULL,created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,updated_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP);CREATETABLEIFNOTEXISTSagentscope.agentscope_skill_resources(idBIGINTNOTNULL,resource_pathVARCHAR(500)NOTNULL,resource_contentTEXTNOTNULL,created_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,updated_atTIMESTAMPDEFAULTCURRENT_TIMESTAMP,PRIMARYKEY(id,resource_path),FOREIGNKEY(id)REFERENCESagentscope.agentscope_skills(id)ONDELETECASCADE);与 MySQL 版的关键区别PostgreSQL 使用 schema而非 database作为命名空间隔离边界数据库由 JDBC URL 决定。6.6 与已有表兼容旧表如果没有 metadata_json 列仓库会自动降级到只往返 name description的兼容模式不会主动 ALTER TABLE。升级方式ALTERTABLEagentscope.agentscope_skillsADDCOLUMNmetadata_jsonTEXTNULL;6.7 CRUD 操作// 写入save 是 upsertname 已存在则更新AgentSkillskill...;repo.save(List.of(skill),/* overwrite */true);// 读取AgentSkillloadedrepo.getSkill(calculator);ListStringnamesrepo.getAllSkillNames();booleanexistsrepo.skillExists(calculator);// 删除repo.delete(calculator);写入与删除都在事务里执行资源表的 ON DELETE CASCADE 保证不会出现孤儿资源。6.8 Builder 配置参数一览方法说明默认值schemaName(String)Schema 名称agentscopeskillsTableName(String)技能表名agentscope_skillsresourcesTableName(String)资源表名agentscope_skill_resourcescreateIfNotExist(boolean)自动 CREATE SCHEMA CREATE TABLEtruewriteable(boolean)是否允许写操作true七、统一接入范式无论选择哪种后端上层集成代码完全一致AgentSkillRepositoryrepo...;// 任选一种实现ListAgentSkillskillsrepo.getAllSkills();ToolkittoolkitnewToolkit();skills.forEach(toolkit::registerSkill);ReActAgentagentReActAgent.builder().name(Assistant).model(model).toolkit(toolkit).build();多源聚合同一个 Toolkit 可注册来自多个 Repository 的技能// 核心技能从 Git 加载保证稳定性GitSkillRepositorygitReponewGitSkillRepository(https://github.com/org/core-skills.git);// 运营技能从 MySQL 加载保证灵活性MysqlSkillRepositorydbReponewMysqlSkillRepository(ds,true);ToolkittoolkitnewToolkit();gitRepo.getAllSkills().forEach(toolkit::registerSkill);dbRepo.getAllSkills().forEach(toolkit::registerSkill);八、选型决策指南决策维度推荐方案关键理由需要 PR/MR 流程管控、可读可 ReviewGit天然融入软件工程治理体系要在管理后台/配置中心动态修改、立即生效MySQL / PostgreSQL / Nacos修改即时生效支持 CRUD API已有 PostgreSQL 基础设施PostgreSQL复用现有连接池Schema 级隔离需要与业务数据同事务边界MySQL / PostgreSQL数据库原生事务支持多种来源混用组合多个 Repository实现 AgentSkillRepository 自己组合或多个 repo 都注册到 toolkit九、MySQL vs PostgreSQL 实现差异对比对比维度MySQL 实现PostgreSQL 实现命名空间隔离Database库名Schema主键策略AUTO_INCREMENTB大文本类型LONGTEXTTEXT表名自定义构造函数参数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确保生命周期管理多实例部署无需担心锁竞争各自维护本地 clone10.2 DB 模式MySQL / PostgreSQL合理配置连接池推荐 HikariCP避免技能读取成为性能瓶颈对 name 字段建立唯一索引建表已自动包含对接管理后台时建议增加操作日志与回滚机制利用 metadata_json 字段存储标签、分类等元数据支持精细化检索10.3 通用建议单个技能加载失败不应阻断整个 Repository 初始化做好异常隔离在监控系统中对技能加载耗时、失败率设置告警安全合规Git 使用 Deploy Key / PATDB 连接启用 SSL 加密传输考虑实现自定义 AgentSkillRepository 对接内部私有系统仅需实现接口方法十一、总结AgentScope Java 的技能仓库机制通过标准化的 Markdown 描述与可插拔的存储后端将 AI Agent 的能力建设从硬编码推向了“配置化与资产化”Git保障了治理严谨性——版本追踪、Code Review、变更审计MySQL / PostgreSQL赋予了运行时灵活性——改完即生效、事务一致性统一的接口抽象让切换与组合变得零成本对于正在构建复杂多智能体系统的团队而言这是实现能力沉淀、复用与规模化治理的关键基础设施。