sunflowermm-xrk-agt-2

目录

• 架构
• 项目展示
• Star 趋势
• 快速开始
• 核心特性
• 文档与开发指南
• 测试与质量
• 常见问题
• 贡献指南
• 致谢
• 许可证
• 联合研制单位
• 联合研制工作室

XRK-AGT 是由向日葵开发、各大学志同道合的学生联合研制的 通用后端运行时：src/ 提供 HTTP/WS、加载器与 AI 工厂，core/*/ 承载插件、API、工作流与智能体业务。支持多平台消息接入与工作流编排：

• 🌐 多平台消息接入：OneBotv11 / QBQBot / GSUIDCORE / stdin / 自定义 Tasker
• 🔌 插件与工作流：指令插件 + AI 工作流 (AIStream)
• 🌐 Web 与 HTTP/API：内置 Web 控制台 + REST API + WebSocket
• ⭐ system-Core：12 HTTP API、7 工作流（80 MCP 工具）、15 插件、4 Tasker、4 events、Web 控制台（/xrk/）
• 🎨 渲染：默认 Playwright；Chromium 经启动菜单或 pnpm run setup:browsers 安装

---

📸 项目展示

以下均为 本机真实运行 录屏/截图（端口 11451，控制台 http://127.0.0.1:11451/xrk/）。

终端启动

node app.js 引导菜单 → 选择端口 → 加载插件 / 工作流 / Tasker → 服务 online。

Web 控制台

系统概览	AI 对话 · MCP 工作流

配置管理	API 调试 · /api/health

更多截图

AI 对话（Event 模式）

API 调试中心（端点列表）

如果你是第一次接触本项目：

• 仅想先跑起来：「快速开始」
• 想懂架构：docs/底层架构设计.md（单一架构图）
• 想看清启动链：docs/startup.md
• 想配 Redis / MongoDB：docs/database.md
• 想看目录该放哪：PROJECT_OVERVIEW.md · docs/README.md
• 想写插件 / Core：docs/runtime-surface.md → docs/coding-style.md → docs/base-classes.md
• 想跑测试 / 发布前审查：docs/框架测试指南.md → docs/代码审查清单.md
• 文档中心：docs/README.md

---

🏗️ 架构

Runtime（src/bot.js）+ 基础设施（加载器、基类、工厂）+ Core 业务层（core/*/：插件、HTTP、工作流、Tasker）。分层图与 AI 链路仅维护于 docs/底层架构设计.md；启动链见 docs/startup.md；目录树见 PROJECT_OVERVIEW.md。

---

⭐ Star 趋势

🚀 快速开始

📥 1. 克隆项目

请使用浅克隆以减小下载体积（--depth=1 仅拉取最新提交）：

# Github
git clone --depth=1 https://github.com/sunflowermm/XRK-AGT.git

# Gitee
git clone --depth=1 https://gitee.com/xrkseek/XRK-AGT.git

# Gitcode
git clone --depth=1 https://gitcode.com/Xrkseek/XRK-AGT.git

cd XRK-AGT

📦 2. 安装依赖

# 需 Node.js >= 26.0.0
pnpm install

Redis / MongoDB：正常运行需要两者至少其一可用（默认两者都连）。Docker 见下文；本机需自行安装或设 XRK_OPTIONAL_DB=1 做无库调试。配置与生命周期见 docs/database.md。

⚙️ 3. 配置环境变量（可选）

创建 .env 文件（可选；勿提交仓库）：

# 主服务端口（默认 8080）
XRK_SERVER_PORT=8080

# 容器出网代理（可选；按本机代理软件端口填写，留空则不走代理）
# HTTP_PROXY=http://host.docker.internal:<端口>
# HTTPS_PROXY=http://host.docker.internal:<端口>
# NO_PROXY=127.0.0.1,localhost

# MongoDB 认证（可选）
MONGO_ROOT_USERNAME=admin
MONGO_ROOT_PASSWORD=password

🚀 4. 启动服务

XRK-AGT 支持多种启动方式，包括本地运行和 Docker 部署。

🐳 Docker 启动（推荐）

提示：Docker Compose 会一并构建可选的 Python 子服务端（FastAPI 扩展框架），主服务 LLM/工作流无需依赖子服务即可运行。

# 启动所有服务（包括主服务端和子服务端）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

服务说明：

• xrk-agt: 主服务端（端口：8080）
• xrk-subserver: Python 子服务端（端口：8000，自动构建）
• redis: Redis 缓存服务（端口：6379）
• mongodb: MongoDB 数据库服务（端口：27017）

详细 Docker 部署指南：参见 docs/docker.md

💻 本地启动（开发环境）

Windows/Linux/macOS:

# 方式1：使用 app.js（推荐，自动检查依赖与环境后启动）
node app.js

# 方式2：使用启动脚本（会先经 app.js 做依赖检查再启动）
# Windows
start.bat

# Linux/macOS
chmod +x start.sh
./start.sh server 8080

# 方式3：node start 会重定向到 app.js，同样会做依赖检查
node start.js server 8080

指定端口：

# 环境变量
XRK_SERVER_PORT=3000 node app.js

# 命令行参数
node start.js server 3000