AuraBoot
免费开始
English简体中文

AI Plugin 开发

AuraBoot AI Plugin 是普通的 Plugin，它贡献一份 Agent 定义、一组 Tool（Command 与命名查询），以及让它们在 Agent 运行时可用所需的 metadata。本页端到端演示如何构建一个。

概念

AI Plugin 不是独立的 Plugin 类型，而是满足以下条件的 Plugin：

  • 注册一份或多份 Agent 定义。
  • 贡献声明开放给 Agent 和/或 MCP 的 Command。
  • 为每个暴露的 Command 提供 agent_hint metadata。
  • 可选地注册命名查询与系统 Prompt 模板。

Agent 运行时在启动时以与发现普通 Plugin 资源相同的方式发现这些贡献。

何时使用

  • 构建领域专项助手（"供应商入驻助手"、"BOM 审计员"）。
  • 打包一份可由客户安装的可复用 Tool 与 Prompt 集合。
  • 在不分叉平台的前提下为既有产品扩展 AI 能力。

Plugin 目录结构

my-ai-plugin/
  plugin.json
  config/
    models/        # optional, if the plugin owns data models
    commands.json
    bindingRules.json     # required when commands declare handlers
    permissions.json
    agent-definitions.json
    namedQueries/
      bom-coverage.json
    i18n/
      en.json
      zh-CN.json
  backend/
    src/main/java/com/example/aiplugin/
      command/
        BomCoverageQueryHandler.java
      tool/
        BomAuditorAgentDef.java

架构

+--------------------------+      +-----------------------+
|  plugin.json + config    | ---> | Plugin loader (host)  |
+--------------------------+      +-----------+-----------+
                                              |
                              +---------------v---------------+
                              |  Metadata registry            |
                              |  - commands + bindingRules    |
                              |  - permissions                |
                              |  - agent-definitions          |
                              +---------------+---------------+
                                              |
                                              v
                              +---------------+---------------+
                              |  Agent runtime / MCP server   |
                              |  resolves tools at turn time  |
                              +-------------------------------+

步骤 1：注册 Permission

Permission code 必须遵循 {resource_type}.{resource_code}.{action}（所有段小写）并在 permissions.json 中声明。在 commands.json 或 Java 中引用未注册的 code 会导致校验失败。

[
  {
    "code": "bom.coverage.read",
    "name:zh-CN": "BOM 覆盖查看",
    "name:en": "Read BOM coverage stats",
    "description": "Read BOM coverage stats",
    "resourceType": "data",
    "module": "bom"
  },
  {
    "code": "bom.audit.execute",
    "name:zh-CN": "BOM 审计执行",
    "name:en": "Run BOM audit actions",
    "description": "Run BOM audit actions",
    "resourceType": "operation",
    "module": "bom"
  }
]

步骤 2：声明 Command 与 Binding Rule

commands.json 内的 inline bindingRules 会被导入器静默忽略。始终使用注册到 resourceDirs 的独立 bindingRules.json。

// commands.json（节选）
[
  {
    "code": "bom:query_coverage",
    "displayName:zh-CN": "查询 BOM 覆盖率",
    "displayName:en": "Query BOM Coverage",
    "type": "query",
    "modelCode": "bom_project",
    "handler": "bomCoverageQueryHandler",
    "inputFields": ["bom_project_id"],
    "permissions": ["bom.coverage.read"],
    "agent_hint": "Report BOM coverage for a project. Use when the user asks how complete a project's BOM is.",
    "cmd_risk_level": "L1"
  }
]
// bindingRules.json
[
  {
    "commandCode": "bom:query_coverage",
    "ruleType": "handler",
    "handlerClass": "bomCoverageQueryHandler",
    "sequence": 10,
    "enabled": true
  }
]

步骤 3：定义 Agent

// config/agent-definitions.json
[
  {
    "agentCode": "bom_auditor",
    "name": "BOM Auditor",
    "description": "Reports BOM coverage and runs audit actions for projects the calling user owns.",
    "agentType": "reactive",
    "model": "deepseek-chat",
    "systemPrompt": "You are the BOM Auditor. Answer questions about BOM coverage and run audit actions only for projects the calling user owns. Always quote the projectId. Never invent line items.",
    "tools": [
      "cmd:bom:query_coverage",
      "cmd:bom:audit_execute"
    ],
    "skills": [
      "dsl.query",
      "dsl.command"
    ],
    "guardrails": {
      "evidenceFirst": true,
      "writePolicy": "Audit actions require explicit user confirmation."
    },
    "allowedOperations": ["query"],
    "status": "active",
    "visibility": "tenant"
  }
]

在 plugin.json 中以 "agentDefinitions": "config/agent-definitions.json" 注册该文件。Tool 引用用前缀区分：cmd: 指向 Command（如 cmd:bom:query_coverage），nq: 指向命名查询。

步骤 4：编写系统 Prompt

系统 Prompt 直接写入 agent 定义的 systemPrompt 字段（内联字符串），无需独立文件。建议写明 agent 的职责边界、必须引用的字段、以及破坏性操作前需用户确认：

You are the BOM Auditor. You may answer questions about BOM coverage and
run audit actions for projects the calling user owns. Always quote the
projectId you are working on. Never invent line items. If coverage data
is missing, ask the user to confirm before running an audit.

步骤 5：实现 Handler

Handler 的 Bean 名必须与 bindingRules.json 的 handlerClass 一致，并由 getHandlerName() 返回相同的值。命令的权限由 commands.json 的 permissions 数组在管道层统一校验，无需在 Handler 上加权限注解。

@Slf4j
@Component("bomCoverageQueryHandler")
@RequiredArgsConstructor
public class BomCoverageQueryHandler implements CommandHandler {

    private final BomCoverageService service;

    @Override
    public String getHandlerName() {
        return "bomCoverageQueryHandler";
    }

    @Override
    public Map<String, Object> execute(CommandHandlerContext context) {
        String projectId = (String) context.getPayload().get("bom_project_id");
        return service.coverageFor(projectId, context.getTenantId());
    }
}

步骤 6：打包与部署

# 校验 Plugin（捕获未注册 handler、raw label 等问题）
aura plugin validate ./my-ai-plugin

# 构建并打包 Plugin
aura plugin build ./my-ai-plugin

# 导入 Plugin 配置到本地运行的 host
aura plugin import ./my-ai-plugin

# 在 Agent 注册表中验证
aura ops agents show bom_auditor

安装后，该 Agent 即可用于 Copilot 面板、Aura Bot、ACP 与 MCP。Tool 按回合并依据每个调用方的 Permission 解析。

验证清单

  • permissions.json 声明了 Command 与 Java 引用的每个 code。
  • bindingRules.json 为独立文件（commands.json 中无 inline binding rule）。
  • 每个暴露的 Command 都有精确的 agent_hint。
  • 面向用户的字符串使用 $i18n: key，而非中文或英文字面量。
  • aura plugin validate 报告零 blocker。
  • 安装后该 Agent 出现在注册表中，并能在测试用户下解析其 Tool。

相关