XRK-AGT / rules

---
description: 基础设施层（src/）代码约定，仅修改底层时遵守
globs: src/**/*.js
alwaysApply: false
---

# 基础设施层约定

## 职责边界

- 本层只提供基类、加载器、工具、工厂；不包含业务逻辑（业务在 `core/*`）。

## 错误与日志

- 错误处理：使用 `#utils/error-handler.js` 的 `errorHandler.handle()` 与 `ErrorCodes`；HTTP 响应用 `HttpResponse.error()`。
- 归一化：`#utils/normalize-error.js` 的 `normalizeError()`；判错用 `Error.isError()`，禁止 `instanceof Error`。
- 日志：使用 `RuntimeUtil.makeLog`（或注入的 logger），不在业务逻辑处随意 `console.log`。

## Node 26 工具（本层新增/统一出口）

| 模块 | 用途 |
|------|------|
| `normalize-error.js` | 非 Error → Error |
| `exec-async.js` | 唯一 Promise 版 `exec`/`execFile` |
| `db-connect-utils.js` | DB 连接辅助：`execCommandResult`、`maskConnectionUrl`、`detectArm64`、`connectWithRetry` |
| `browser-renderer-base.js` | Puppeteer/Playwright 共用浏览器截图基类 |
| `llm/proxy-utils.js` | `fetch` + Undici `ProxyAgent` |
| `subserver-client.js` | `fetchSubserverToPath`：`fetch` + `Readable.fromWeb` |

禁止在本层以外重复实现上述能力；详见 skill `xrk-node-runtime`。

## 接口稳定

- 修改基类或加载器对外 API 时，须同步更新 `docs/`、skills、rules 与依赖该 API 的 Core；**勿**长期保留兼容别名。破坏性重命名应一次改净标识符与文档。