xrk-http-api

文档与代码

• 文档：docs/http-api.md、docs/runtime-surface.md、docs/api-loader.md
• 基类：src/infrastructure/http/http.js
• 加载器：src/infrastructure/http/loader.js

核心约定

• API 模块放在 core/*/http/*.js，导出对象或继承 HttpApi。
• 路由数组 routes 中声明 method/path/handler/middleware。
• 鉴权策略由各模块自行决定：system-Core HTTP 推荐在模块内通过 AgentRuntime.checkApiAuthorization(req) 统一使用系统级 API Key，其他 Core 可自定义或选择接入该能力（详见 xrk-auth skill）。
• handler 用 req.agentRuntime 或第三参 AgentRuntime，勿 global.AgentRuntime。

HttpResponse

import { HttpResponse } from '#utils/http-utils.js'。handler 用 return HttpResponse.success/error/asyncHandler/...，勿混用 res.json()。

success 响应形状（底层定义）

实现：src/utils/http-utils.js → HttpResponse.success。

// 服务端
HttpResponse.success(res, { assessments, webVersion });
// → { success: true, message: '操作成功', assessments, webVersion }

HttpResponse.success(res, { data: config }); // 刻意要顶层 data 字段
// → { success: true, message: '操作成功', data: config }

HttpResponse.success(res, items); // 数组
// → { success: true, message: '操作成功', data: items }

前端 / Core www 消费约定

禁止默认 const data = json.data 再读业务字段（对象拍平后常为 undefined）。

function unwrapSuccess(json) {
  if (!json?.success) throw new Error(json?.message || '请求失败');
  if (json.data !== undefined) return json.data;
  const { success, message, ...rest } = json;
  return rest;
}

需要「整包在 data 下」时，服务端应写 success(res, { data: payload })（如 kaguya、xiaozhi config）。

详见 docs/http-api.md「响应格式」。

Node 26（Core HTTP）

• 模块内出站请求：fetch + AbortSignal.timeout（仅服务端；浏览器用 abortTimeout，见 xrk-www-compat）。
• catch：Error.isError / normalizeError（见 skill xrk-node-runtime）。
• 禁止 node-fetch、手写 AbortController 超时。