XRK-AGT / rules

---
description: XRK-AGT 开发需求与编码约定（constructor/全局对象/HttpResponse）
alwaysApply: true
---

# 开发需求与约定

> 完整写法与性能规范：**`docs/coding-style.md`** · skill **`xrk-coding-style`**

## Constructor 内不要定义易变状态

- **禁止**在 `constructor` 里定义会被反复创建、或作为“缓存/状态容器”的变量（如 `this.cache = new Map()`、`this.xxx = {}`）。
- **原因**：热加载或多次实例化时 constructor 会重复执行，导致引用错乱或“无限刷新”感。
- **正确做法**：需要实例级缓存/状态时，用**类字段**在声明处初始化（如 `cache = new Map()`），或放在只调用一次的 `init()` 里；constructor 内只做 `super()` 与固定配置（如 `name`、`event`）。

## 全局标识符：裸名，勿写 `global.`

运行时挂在 **`globalThis`**；Node ESM 下业务模块可直接写裸名（详见 `docs/runtime-surface.md`）。

| 对象 | 业务写法（`core/`） |
|------|---------------------|
| AgentRuntime | 裸名 `AgentRuntime`、`AgentRuntime.em()`、`AgentRuntime[self_id]`；**勿** `import AgentRuntime`、`new AgentRuntime()`、`global.AgentRuntime` |
| msgSegment | 裸名 `msgSegment.image(url)`；**勿** `global.msgSegment` |
| PluginBase | `import PluginBase from '#infrastructure/plugins/plugin-base.js'` |
| runtimeConfig | `import runtimeConfig from '#infrastructure/config/config.js'`（与全局同一单例） |
| HTTP | `req.agentRuntime` 或 handler 第三参 `AgentRuntime` |

- **`src/` 挂载**统一用 `setRuntimeGlobal(name, value)`（`#utils/runtime-globals.js`），勿手写 `global.x` 与 `globalThis.x` 双份。
- 配置在 `AgentRuntime.run` 完成 `CommonConfigRegistry.load()` 之前不可用。

## HttpResponse（src/utils/http-utils.js）

- **导入**：`import { HttpResponse } from '#utils/http-utils.js'`（文件名是 http-utils，不是 http-response）。
- **用途**：统一 HTTP 响应格式与错误处理；`core/*/http/*.js` 的 handler 应优先使用。
- **`success` 响应形状（底层定义，前端必遵）**：
  - `HttpResponse.success(res, data, message)` → 始终含 `success: true` 与 `message`。
  - **普通对象**（非数组）：字段 **拍平到顶层**（`Object.assign`），**没有**统一的 `data` 包裹。  
    例：`success(res, { assessments, webVersion })` → `{ success, message, assessments, webVersion }`。
  - **数组 / 标量 / null**：放在 `data` 字段。  
    例：`success(res, list)` → `{ success, message, data: list }`；`success(res, null, 'ok')` → 仅 `success`+`message`。
  - 若业务就要一个叫 `data` 的字段：显式 `success(res, { data: payload })`，拍平后顶层仍有 `data`。
  - **前端禁止**默认 `return json.data` 再读字段。有 `json.data` 用它，否则去掉 `success`/`message` 后的剩余字段，或读顶层。解包语义见 `unwrapSuccess`（`web-compat.js` / skill **`xrk-www-compat`**）；产品页内联同语义。
- **常用静态方法**：
  - `HttpResponse.success(res, data, message)`：成功（形状见上）；
  - `HttpResponse.error(res, error, statusCode, context)`：统一错误与日志；
  - `HttpResponse.validationError(res, message, code)`：400；
  - `HttpResponse.notFound(res, message)`、`HttpResponse.unauthorized(res, message)`、`HttpResponse.forbidden(res, message)`；
  - `HttpResponse.asyncHandler(handler, context)`：包装异步 handler，自动 try/catch 并调 `HttpResponse.error`；
  - `HttpResponse.json(res, body)`：原样 JSON（兼容端点，不包 success 外壳）；
  - 流式/SSE：`HttpResponse.streamResponse(res, streamHandler, context)`；MCP：`jsonRpcError` / `jsonRpcSuccess` / `validateJsonRpcRequest`。
- **约定**：handler 内用 `return HttpResponse.xxx(...)` 提前返回，不要与裸 `res.json()` 混用；兼容端点（如 stdin 原样 JSON）用 `HttpResponse.json(res, body)`。

## Core www（浏览器兼容层）

> skill **`xrk-www-compat`** · `core/system-Core/www/xrk/modules/web-compat.js`

- **勿**裸用 `crypto.randomUUID`、`AbortSignal.timeout`、无降级 `structuredClone`。
- 控制台：`./web-compat.js`（经 `utils.js` 再导出）。产品 Core：**只内联**同语义（禁止依赖 `/shared` 或跨应用 `/xrk/...`）。
- 根目录名 `shared` 为保留段（见 `RESERVED_ROOT_SEGMENTS`）；产品用自有名（如 `lsy-shared`）。
- 新能力先扩 `web-compat.js`，再同步内联份。

## Node 26 运行时（服务端全局）

> skill `xrk-node-runtime` · `docs/node-26-runtime.md`

- **fetch / 超时**（**仅 Node**）：`fetch(url, { signal: AbortSignal.timeout(ms) })`；禁止 `node-fetch`、`AbortController`+`setTimeout`。浏览器 Core www 用 `abortTimeout`（见上节）。
- **exec**：仅通过 `#utils/exec-async.js`；禁止在 constructor/插件/HTTP 内 `util.promisify(exec)`。
- **错误**：`Error.isError` + `normalizeError`；禁止基础设施式 `instanceof Error`。
- **二进制**：`Buffer#toBase64()` / `Uint8Array.fromBase64`；禁止 `toString('base64')` 新代码。