sunflowermm 文档与代码
- 文档：
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-authskill）。 - 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 } |
// 服务端
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 |
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（见 skillxrk-node-runtime）。 - 禁止
node-fetch、手写AbortController超时。