AI Agent 接入

受众：开发者 摘要：AI Agent 接入指南：OpenAPI 元数据 / Open Platform 调用 / 工具调用约定 / 客户端样板。

本文档说明项目如何面向 AI Agent、MCP Tool Calling、SDK 生成和第三方服务端调用提供稳定接口。

核心原则：

• 对内优先使用 facade / manager，例如 Knowledge、AiTask、Web3。
• 对外统一走 Open Platform，例如 /api/v1/open/**。
• API 元数据统一来自 OpenAPI，例如 /v3/api-docs。
• 工具调用依赖稳定 operationId、版本化路由、统一 Result<T> 和清晰 scope。

接入方式

场景	推荐入口	说明
AI Agent 读取接口元数据	API 文档	使用 OpenAPI 3.1、稳定 operationId 和 x-* AI 元数据
第三方服务端调用能力	Open Platform	使用 AK/SK、签名、防重放、scope、限流和调用日志
项目内调用知识库	知识库	使用 Knowledge.search(...) 或 Knowledge.ask(...)
项目内组织 AI 任务	AI 任务	使用 AiTask.run(...)，按需组合 Queue、Scheduler、Pipeline
开发者工具调用模型	AI 模型网关	OpenAI Compatible 兼容 /api/v1/ai/gateway 和 /api/v1/ai/gateway/v1，Claude Code 使用 /api/v1/ai/gateway/claude/v1，Codex / Responses API 兼容 /api/v1/ai/gateway/codex 和 /api/v1/ai/gateway/codex/v1
第三方接入说明	开放平台	复制 Java 17 签名规则，不依赖 Spring

OpenAPI 元数据

默认入口：

GET /v3/api-docs
GET /v3/api-docs/core
GET /swagger-ui.html

AI Agent 和 SDK 生成优先读取 OpenAPI JSON，不要解析页面 HTML。

约定：

• operationId 必须稳定、唯一、可读，统一 模块__动作 格式（双下划线分隔模块与动作，详见 openapi.md）。
• 普通 JSON 接口统一返回 Result<T>。
• Controller 返回 ResponseEntity<?>，OpenAPI schema 通过 @ApiResult 或 @ApiPageResult 标注。
• 文件、SSE、WebSocket 不强行套 Result<T>，按协议独立描述。
• 后续生成 MCP tool metadata 时，优先以 operationId 作为 tool 名称基础。

示例：

@Operation(operationId = "config__page", summary = "分页查询配置项")
@ApiPageResult(ConfigVO.class)
public ResponseEntity<?> page(...) {
    ...
}

Open Platform 工具调用

外部 Agent 或第三方服务端调用项目能力时，不应直接使用后台管理接口，而应使用 Open Platform。

统一路由：

/api/v1/open/**

统一请求头：

X-Open-App-Key: app_xxx
X-Open-Timestamp: 1779379200000
X-Open-Nonce: random-string
X-Open-Signature: signature
X-Open-Signature-Method: HMAC-SHA256
X-Open-Idempotency-Key: optional-business-idempotency-key

调用前需要：

1. 后台创建开放平台应用。
2. 生成并保存 AppSecret。
3. 授权 scope，例如 open:web3:balance:read。
4. 第三方服务端按签名规则生成请求头。
5. 调用 /api/v1/open/**。
6. 通过调用日志和统计接口查看结果。

不要把 AppSecret 放在浏览器、小程序、移动端或公开仓库中。需要前端调用时，应由自己的后端代理签名。

Scope 命名

开放能力使用：

open:<capability>:<resource>:<action>

示例：

Scope	说明
open:web3:network:read	读取链信息
open:web3:balance:read	查询余额
open:web3:token:read	查询 Token 和授权
open:web3:transaction:read	查询交易、回执和确认数
open:web3:transaction:write	签名或广播写交易
open:payment:order:create	创建支付订单

新增开放接口时必须同步：

• route -> scope 映射。
• OpenAPI 注解。
• Open Platform 文档。
• 调用样板或示例。
• 调用日志和限流边界。

Agent 友好返回

普通响应：

{
  "code": "200",
  "message": "Success",
  "data": {}
}

约定：

• HTTP 状态只表达传输层结果。
• 业务成功或失败看 Result.code。
• 失败时保留可读 message，并通过日志记录 traceId。
• 列表、分页和详情接口字段应保持 VO 稳定，不直接暴露 Entity。

调用接入

Open Platform Java 17 调用示例维护在 开放平台 章节。它覆盖 canonical string 生成、SHA-256(AppSecret) 签名 key、HMAC-SHA256 hex 签名、X-Open-* 请求头生成和 Java 17 HttpClient GET / POST JSON 请求。

第三方服务端可直接复制签名规则，根据自己的 HTTP 客户端、日志、重试、密钥管理和 SDK 发布规范封装。

Web3 开放能力

当前 Open Platform Web3 v1 已暴露：

• 链信息。
• 原生币和 ERC-20 余额。
• Token 信息和授权额度。
• Gas Price、Nonce 和 Gas 预估。
• 交易、回执和确认数。
• 交易 input 解码。
• 事件日志查询。
• Token 价格查询。
• 钱包签名校验。
• 批量转账计划和真实签名。
• 资金归集计划和真实签名。

资金类接口默认不广播，只返回签名结果；显式 broadcast=true 才广播。生产环境建议使用独立应用、独立 scope、IP 白名单、更低限流和审计流程。

Knowledge 和 AI Task

项目内 AI 能力推荐这样组合：

Knowledge.search / Knowledge.ask
-> Pipeline 组装上下文
-> AiTask.run
-> Queue / Scheduler 按需异步或定时
-> Notification / Open Platform 返回结果

第一阶段不把 Knowledge 做成外部公开 API，也不把 AI Task 做成工作流引擎。需要开放给第三方时，应先通过 Open Platform 建立 scope、限流、调用日志和计量边界。

后续方向

后续增强优先级：

1. Agent Friendly API 能力索引接口。
2. OpenAPI -> MCP tool metadata 生成。
3. Open Platform usage event、配额、套餐和账单。
4. Knowledge 向量检索和可控 Ask API。
5. AI Task 任务记录、重试、取消和后台运维。