AI Skill

受众：开发者 / 管理员 摘要：spring-open-starter-ai-skill 与 AI 模块 Skill 控制面提供生产安全的 Skill 声明、发现、版本、启停和运行日志能力。

定位

AI Skill 用于描述“某类任务应如何让 Agent 使用上下文、资源、工具和约束”。它借鉴 Codex Skill / Agent Skill 的使用体验，但在 SpringOpen 中按生产安全边界落地：

• starter 负责 SKILL.md 解析、classpath 发现、激活评分和资源访问策略。
• AI 模块负责数据库态 Skill 导入、版本发布、启停、运行日志和后台管理。
• scripts:、resources: 和 tools: 等清单只作为元数据和后续编排依据，默认不会被 starter 或 AI 模块直接执行。
• 需要真实工具执行时，必须接入受治理的 ToolGateway / ToolRegistry，继续保留 scope、风险确认、幂等、审计和超时边界；starter 只提供适配层，不内置 shell、HTTP 或业务动作执行器。

SKILL.md 格式

---
name: refund-audit
description: 审核退款申请时使用的证据收集和判断说明
version: 1.0.0
risk-level: medium
scopes:
  - ai.skill
  - payment.refund
tags:
  - refund
  - review
resources:
  - references/refund-policy.md
scripts:
  - scripts/check-refund.sh
---

读取退款申请、订单、支付和售后上下文。
先列出证据，再给出建议，不要直接执行退款。

字段说明：

字段	说明
name	Skill 唯一名称，导入数据库后作为定义主键的一部分
description	激活匹配和后台展示说明
version	Skill 文档版本；数据库态导入会形成版本记录
risk-level	low / medium / high / critical，未知值会降级为 low，避免不可信文档直接打断启动
scopes	Skill 适用范围，供激活请求和后续权限治理使用
tags	辅助筛选和后台管理标签
resources	相对资源路径；禁止绝对路径、路径穿越和反斜杠路径
scripts	脚本清单，仅作为元数据；默认不执行

后台管理

后台入口位于 AI 运营页 /ai/platform 的 AI Skills 页签。管理员可以：

• 查看内置 classpath Skill 和数据库态 Skill。
• 导入一份 SKILL.md，可选择是否立即发布。
• 启用或停用数据库态 Skill。
• 查看 Skill 版本列表并发布指定版本。
• 查询 Skill 运行日志，按 Skill、状态和时间筛选。

权限：

权限	能力
ai:skill:view	查看 Skill、版本和运行日志
ai:skill:update	导入、启停和发布 Skill 版本

API

后台控制面：

API	说明
GET /api/v1/admin/ai/platform/skills	查询内置和数据库态 Skill
POST /api/v1/admin/ai/platform/skills	导入 SKILL.md
PUT /api/v1/admin/ai/platform/skills/{skillName}/status	启用或停用 Skill
GET /api/v1/admin/ai/platform/skills/{skillName}/versions	查询 Skill 版本
POST /api/v1/admin/ai/platform/skills/{skillName}/versions/{versionId}/publish	发布指定版本
GET /api/v1/admin/ai/platform/skills/run-logs	查询运行日志

数据模型

AI Skill 数据表归属 spring-open-module-ai：

表	说明
ai_skill_definition	Skill 定义，保存名称、状态、描述、风险等级、scope、tag 和当前发布版本
ai_skill_version	Skill 版本，保存 SKILL.md 原文、instructions、资源 / 脚本清单和 checksum
ai_skill_run_log	Skill 运行日志，记录 runKey、traceId、用户、状态、token、耗时和错误摘要

ToolGateway 适配

spring-open-starter-ai-skill 已提供 SkillToolAdapter、SkillToolExecutor 和 SkillToolRegistryBinder，用于把 Skill 中声明的可执行资源接入 spring-open-starter-ai-model 的受治理 ToolGateway：

• 默认不注册任何可执行工具。必须同时满足 spring.open.ai.skill.script-execution-enabled=true、存在 ToolRegistry，且业务模块显式提供 SkillToolExecutor Bean。
• starter 不提供默认执行器，不直接执行 scripts:、命令、HTTP 请求、MCP 工具或业务动作。
• DefaultSkillToolAdapter 只把 executable=true 的资源映射为 ToolDefinition；普通 resources: 不会暴露为可调用工具。
• 生成的工具默认要求二次确认，调用方必须先拿到 ToolGateway 返回的确认令牌，再携带 confirmed=true 和 confirmationToken 重试。
• 所有执行请求都会带上 Skill 名称、版本、风险等级和资源路径等审计 metadata，业务执行器可以据此落库、告警或做更细权限检查。

最小接入方式：

@Bean
SkillToolExecutor skillToolExecutor() {
    return context -> {
        // 业务模块在这里接入受控执行器，例如只读诊断、沙箱脚本或内部工具。
        // 不要在这里直接放行资金、链上、删除数据等不可逆动作。
        return Map.of("status", "ok", "resource", context.getResource().path());
    };
}

启用后，模型侧仍只能调用 ToolRegistry 中显式注册的工具，并继续经过 scope 校验、二次确认、幂等、超时和审计。真实生产执行器上线前，需要先完成对应业务安全评审和后台确认交互设计。

迁移文件：

spring-open-modules/spring-open-module-ai/src/main/resources/db/changelog/migrations/
├── 0000_00_00_417000_module_ai_create_tables.xml
└── 0000_00_00_417100_module_ai_seed_data.xml

配置

spring:
  open:
    ai:
      skill:
        enabled: true
        locations:
          - classpath*:/skills/*/SKILL.md
        external-file-location-enabled: false
        max-skill-size: 64KB
        max-resource-size: 256KB
        script-execution-enabled: false
        activation-min-score: 1
        max-activation-results: 5

生产建议：

• 优先把内置 Skill 放在 classpath skills/<name>/SKILL.md，随模块版本发布。
• 外部文件系统 Skill 只在受控目录启用，并配合发布审批。
• Skill instructions 不保存敏感凭证；脚本清单不等于脚本执行授权。
• 运行日志不保存完整 Prompt / Completion，必要时另行设计脱敏、授权和保留周期。

验证

AI Skill 改动后至少执行：

./mvnw -pl spring-open-starters/spring-open-starter-ai-skill -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
./mvnw -pl spring-open-modules/spring-open-module-ai -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
pnpm -C views/admin typecheck
./.ai/scripts/check migrations
git diff --check