XRK-AGT / rules

---
description: core 目录下业务代码（插件/HTTP/工作流）的编写约定；须遵守 Node 26 运行时（见 xrk-node-runtime）
globs: core/**/*.js
alwaysApply: false
---

# Core 业务代码约定

## 底层与基类（Core 开发者边界）

- **Core 不改 Runtime**：在 `core/` 写业务时，**不得**修改 `src/infrastructure/`、`src/utils/`、`src/factory/` 等 Runtime 代码；缺能力应提 issue 或请框架开发者扩展基类/工具。
- **框架开发者**：维护 `src/` 与 Loader/工厂/基类时**可以且应当**改 `src/`，并通过 `docs/` 与 commonconfig 暴露给 Core。
- **充分利用底层**：继承基类并按文档实现接口；commonconfig 用足 ConfigBase；插件/HTTP/工作流用足各自基类能力，不重复造轮、不在 Core 内复制 `src/` 逻辑。

## 放码位置

- 插件：`core/*/plugin/*.js`；HTTP API：`core/*/http/*.js`；工作流：`core/*/workflow/*.js`。各自继承对应基类，行为符合 `docs/` 中对应文档。
- 基类路径（无 package.json 时用 `#`）：插件 `#infrastructure/plugins/plugin-base.js`，HTTP `#infrastructure/http/http.js`，工作流 `#infrastructure/ai-workflow/ai-workflow.js`。有 package.json 时改为相对路径至 `src/`（如 `../../../src/infrastructure/...`）。

## 导入约定

- **无** package.json 的 core：使用根包 `#` 别名（`#infrastructure/*`、`#utils/*`）。
- **有** package.json 的 core：**禁止使用 `#`**（子包无法解析根包别名），须用**相对路径**引用项目根下 `src/`（如从 `core/X/commonconfig/` 用 `../../../src/infrastructure/...`）。写业务 core 时若该 core 目录下存在 package.json，一律不得使用 `#` 路径。

## 编码约定

- constructor 内不定义缓存/状态容器，用类字段或 `init()` 初始化。
- 插件/事件/Tasker：使用全局 `AgentRuntime`、`msgSegment`（不要 import AgentRuntime 或 msgSegment）。
- HTTP handler：使用 `HttpResponse`（`#utils/http-utils.js`）与注入的 `req.agentRuntime`。详见 `xrk-dev-requirements.mdc`。

## Node 26 运行时（Core 必守）

> 完整清单：skill `xrk-node-runtime`、`docs/node-26-runtime.md`

- **fetch**：全局 `fetch` + `AbortSignal.timeout`；LLM 代理用 `buildFetchOptionsWithProxy`。**禁止** `node-fetch`。
- **exec**：`import { exec } from '#utils/exec-async.js'`（或相对路径至 `src/utils/exec-async.js`）。**禁止** `promisify(exec)`、`child_process/promises`。
- **错误**：`Error.isError(err)`、`normalizeError(err)`（`#utils/normalize-error.js`）。**禁止** `instanceof Error` 判错。
- **二进制**：`toBase64()` / `toHex()` / `Uint8Array.fromBase64()`。**禁止** `toString('base64'|'hex')`。
- **勿写** polyfill、特性检测回退（`globalThis.URLPattern ? ... : 手写`）。