SuperAPI AI 工具集

xrk-http-api

编程与开发

查看项目

更新于 11-05 16:20

技能介绍

用途:本技能面向 XRK-AGT 的 HTTP/API 层,用于开发或排查 HTTP API(core//http/.js),帮助理解 HttpApi 基类、ApiLoader 与业务层约定,回答接口新增、鉴权位置、路由实现位置等问题。

主要能力:提供该子系统的实现路径与配置入口,给出代码路径、配置路径与关键字段,并补充风险点、验证步骤与回归范围;适用于需要快速定位改动落点与兼容性注意事项的场景。不用于替代其他子系统的实现说明,也不在缺少证据时臆造路径或字段。

关键约定与入口:权威文档为 docs/http-api.md、docs/api-loader.md、docs/http-business-layer.md;基类为 src/infrastructure/http/http.js;加载器为 src/infrastructure/http/loader.js。API 模块放在 core//http/.js,导出对象或继承 HttpApi;路由数组 routes 中声明 method/path/handler/middleware。鉴权策略由各模块自行决定,system-Core HTTP 推荐在模块内通过 Bot.checkApiAuthorization(req) 统一使用系统级 API Key,其他 Core 可自定义或选择接入该能力(详见 xrk-auth skill)。

响应工具:HttpResponse(src/utils/http-utils.js)导入方式为 import { HttpResponse } from '#utils/http-utils.js'(文件名是 http-utils,不是 http-response),用于统一成功/错误响应格式与错误处理;handler 应优先使用 HttpResponse,避免手写 res.json() 导致格式不一致。常用方法包括 success、error、validationError(400)、notFound、unauthorized、forbidden、asyncHandler(自动 try/catch 并调用 error)、streamResponse(SSE 流式),以及 MCP 的 jsonRpcError、jsonRpcSuccess、validateJsonRpcRequest。约定 handler 内用 return HttpResponse.xxx(...) 提前返回,不要与 res.json() 混用。

使用方式:先确认需求属于该技能职责边界,再给出代码路径、配置路径与关键字段,最后补充风险点、验证步骤与回归范围。

适用场景与限制:适用于定位该子系统实现路径与配置入口、快速给出改动落点与兼容性注意事项;不替代其他子系统实现说明,不在缺少证据时臆造路径或字段。常见陷阱包括只给概念不给具体文件路径、文档与代码冲突时未标注以代码为准、忽略配置与 Schema 及消费代码的一致性。项目概览入口为 PROJECT_OVERVIEW.md,代码入口为 src/ 与 core/ 对应子目录,相关主题文档在 docs/ 下。