XRK-AGT / rules

---
description: XRK-AGT 架构、放码与配置归属（克隆本仓写 Core 必遵）
alwaysApply: true
---

# XRK-AGT 项目规则

克隆本仓开发 Core / 扩展 Runtime 时遵守。开发入口：根 **`AGENTS.md`**；任务→Skill：`.cursor/skills/SKILL_INDEX.md`。

## 上游与提交

- 官方仓库与文档链接默认 owner：**`xrkseek`**（例：`github.com/xrkseek/XRK-AGT`）。
- 提交信息不得含 `Co-authored-by: Cursor` / `cursoragent@cursor.com`；Author 用提交者本人的 git identity。

## 边界

- **业务**：`core/<core名>/` → `plugin` · `http` · `workflow` · `tasker` · `events` · `commonconfig` · `www/<应用名>/`（`www` 必须子目录；根名勿用 `api|core|media|uploads|File|shared`）。
- **Runtime**：`src/infrastructure/` · `src/utils/` · `src/factory/`；启动 `app.js` / `start.js` → `src/agent-runtime.js`。
- **Core 开发者不得改 `src/`**；缺能力提 issue，或由框架扩基类后经文档 / commonconfig 暴露。框架维护者改 `src/` 并文档化。
- 加载：Loader 扫描 `core/*/` 对应子目录；`www/` 由 `mountCoreWwwStatic` 挂到 `/<应用名>`。

## 配置归属

| 位置 | 用途 |
|------|------|
| `config/default_config/` | 仅 AGT 运行时 / LLM·ASR·TTS 工厂 / system-Core |
| `core/<core>/default/` + `commonconfig/` | 独立产品模板与 schema；运行时数据在 `data/<产品>/` |

产品业务配置 **禁止** 写入 `config/default_config/`。改字段须模板 + schema + 消费代码同步。

## 导入

- 无 `package.json`：`#infrastructure/*`、`#utils/*`
- 有 `package.json`：相对路径引用根 `src/`（**禁止 `#`**）

## 栈

Node ≥ 26 · 仅 **pnpm**。服务端 API / 禁止旧写法：`xrk-dev-requirements.mdc` · skill `xrk-node-runtime`；Core www：skill `xrk-www-compat`。

## 主仓入库

主仓通常只白名单 `system-Core`；业务 Core、娱乐插件默认本地运行，**勿**为产品名改根 `.gitignore` 加 `!`。细则：`xrk-third-party-plugins.mdc`。

独立 git 产品 Core 的精工写在**该 Core 仓** `.cursor/rules/`；主仓可用 `globs: core/<名>/**` 薄路由，不 alwaysApply 产品细则。

## 语言

规则与 Skills 用**简体中文**；「在哪改」给到文件 + 函数/字段；与代码冲突以代码为准。