---
name: xrk-http-api
description: 当你需要开发或排查 HTTP API（core/*/http/*.js）、理解 HttpApi 基类、HttpApiLoader、业务层约定时使用。
---

## 文档与代码

- 文档：`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`。

| 第二参 `data` | 实际 JSON |
|---|---|
| 普通对象（非数组） | `{ success: true, message, ...data }`（**拍平**，无外层 `data`） |
| 数组 / 标量 | `{ success: true, message, data: <值> }` |
| `null` / 省略 | `{ success: true, message }` |

```javascript
// 服务端
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`）。

| 场景 | 做法 |
|------|------|
| `/xrk` | `import { unwrapSuccess } from './web-compat.js'` |
| 其它产品 www | **内联**同语义（见 skill **`xrk-www-compat`**） |
| 或 | 直接读顶层：`json.assessments`、`json.configs` |

```javascript
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` 超时。