XRK-AGT：面向多平台、多工作流的 Node.js 智能体基座 | 单片机设备ws适配 | AIStream 工作流 | 可插拔插件 & HTTP/API | 独立基类渲染器 | 开发者配置体系
项目背景：从单体机器人到多场景“智能体工厂”
sunflowermm/XRK-AGT: 这是向日葵工作室基于多语言所搭建的基于web，工作流，新型算法组件的智能体
- 动机：传统机器人往往限定单一平台、单一任务，难以满足真实业务的多通道、多流程诉求。定位为「多适配器 + 多工作流 + 工厂化基类」的智能体运行平台。
- 致敬 Yunzai：插件开发体验向 Yunzai 风格致敬——规则匹配、权限、节流、上下文与指令式编写习惯延续；在此基础上补足多适配器、AI 工作流、HTTP/API、渲染、配置体系等“生产级”能力。
- 目标：让 QQ/微信/自定义协议/MCU 设备都能共享同一套插件与 AI 工作流，同时具备 Web 控制台、HTTP/API、渲染截图、配置热更新和运维工具链。
核心功能：多通道、多角色、一套内核
- 多平台消息接入：OneBotv11、ComWeChat、自定义适配器，事件统一进入 Bot.em。
- 插件工作流：PluginsLoader 统一规则匹配、权限/节流/上下文，兼容 Yunzai 风格；示例插件演示加法、状态、定时任务、远程指令等。
- AIStream 工作流：抽象大模型调用、Embedding 检索、Function Calling；档位/模型路由（generic/OpenAI 协议、火山引擎等），失败自动降级 lightweight。
- Web & HTTP/API：Express 统一 HTTP/HTTPS/WS，ApiLoader 动态挂载 core/http 模块；跨域、认证、限流、请求日志开箱即用。
- 渲染与截图：Renderer 基类 + Puppeteer/Playwright 双引擎，生成报表、卡片、长图，适合社群播报与可视化。
- 配置体系：Cfg（端口级 YAML 拆分与缓存）+ ConfigBase（字段级校验/合并/结构导出），前端可自动生成表单，支持热更新与备份。
- 运维与安全：反向代理（多域名+SNI+HTTP/2）、Helmet/CORS/限流、API-Key+白名单+Cookie 多重认证；定期清理 trash/ 目录，降低长期运行风险。
技术栈与基类流/工厂流
- 运行内核：Node.js + Express + WebSocket，事件总线 Bot.em 统筹多入口。
- 基类流：
- Bot 基类：HTTP/HTTPS/WS、认证、反向代理、静态资源、安全头、限流。
- plugin 基类：规则匹配、权限/节流、上下文管理、任务/handler、统一回复。
- HttpApi 基类：REST/WS 路由定义与自动装载。
- Renderer 基类：模板 + 截图流水线。
- AIStream 基类：LLM 调用、Embedding、Function Calling、上下文增强。
- 工厂流：
- AdapterLoader：扫描 core/adapter，一处接入，多处复用。
- ApiLoader：扫描 core/http，热重载路由与 WS。
- StreamLoader：加载 AI 工作流，统一档位与提供商。
- LLMFactory / TTSFactory / ASRFactory：面向多模型、多语音/识别提供商的抽象工厂
- 存储与缓存：Redis 作为上下文、Embedding、状态与会话的缓存层。
MCU/物联网设备连接：让“消息总线”触达硬件
- 设备事件通道：core/events/device.js + Bot.em 将设备上报映射为标准事件，可被插件与 HTTP/API 复用。
- AI 边缘协作：AIStream 可结合设备消息做函数调用，触发控制指令（如继电器开关、传感器读数回传）。
- 配置拆分：config/default_config/device.yaml + data/server_bots/{port}/device.yaml，便于多端口/多设备场景分别管理。
- 工厂化扩展：在 core/adapter 实现自定义 MCU/IoT 适配器（串口/UDP/MQTT/HTTP 均可），统一进 Bot.em → PluginsLoader → 插件逻辑；同一插件可同时服务 QQ 群、微信与 MCU 设备，形成“消息即接口”的多路复用。
实现难点与巧思
- 统一事件模型：多适配器、多设备上报转译为统一结构，插件与 API 无需关心来源。
- AI 档位与提供商路由：profile/modelKey/llm 前置解析 + apiConfig 覆盖；Embedding 失败自动降级，保证可用性。
- Function Calling 安全：函数注册含权限/解析器/描述，执行前统一校验，避免任意调用被滥用。
- 配置双层设计：Cfg 管端口级拆分与缓存，ConfigBase 管字段级校验/合并/结构导出，前端可动态表单化。
- 渲染流水线：Renderer 抽象 + Puppeteer/Playwright 双引擎，适配报告/播报/告警卡片。
- 运维与安全：多域名 SNI/HTTP2 代理、安全头、限流、目录防穿越；Bot 内置 trash 清理任务保障长期运行。
成果展示与多场景落地
- 社群助手：QQ/微信群播报、任务提醒、AI 问答、卡片渲染。
- 运维与可视化：HTTP/API + Web 控制台调试，结合渲染生成日报/周报。
- 行业垂直（如农业）：多工作流 + MCU 设备上报（温湿度/灌溉阀门），AI 策略 + Function Calling 触发硬件动作。
- 插件示例：core/plugin/example（加法、状态、定时、远程指令）展示规则与上下文；可扩展为“设备控制”“数据采集”“告警推送”类插件。
- API 示例：在 core/http 新增对象即自动注册，可暴露配置读写、设备控制、渲染服务、模型列表等。
开发者快速路径
- 快速上手：阅读 PROJECT_OVERVIEW.md + docs/README.md；app.js 引导检查环境/依赖 → start.js 创建 Bot。
- 写插件：看 docs/plugin-base.md + core/plugin/example，按规则/上下文/权限编写。
- 写 API：看 docs/http-api.md + docs/api-loader.md，在 core/http 新建文件导出对象即可。
- 接入新适配器/MCU：参考 core/adapter/OneBotv11.js，实现设备协议→标准事件→Bot.em；插件/AI/渲染链路无需改动。
- 前端协作：www/xrk 控制台 + /api 列表；ConfigBase.getStructure() 生成动态表单。
下一步计划
- 丰富官方插件与 AIStream 示例：面向客服、运维、IoT/MCU、知识库问答的模版化工厂。
- 更完善的 Web 控制台：可视化配置、任务编排、实时观测（Prometheus/Grafana 集成）。
- 适配器生态扩展：更多 IM/企业协议/IoT 通道，继续强化“消息即接口”。
- 多模态与边缘智能：图片/音频/视频识别与生成链路，与设备控制联动的自动化场景。
- 性能与观测：慢请求分析、插件性能画像、告警与自愈机制。
