白龙马：一个持续运转的数字意识框架

图1：白龙马项目 Logo

想象一下，你打开一个桌面程序，它不只是一问一答的聊天窗口，而是一个有"记忆"、有"感知"、会主动思考的数字助手——你发消息它响应，你不在时它也在运行，会自动整理记忆、规划任务、感知环境变化。这就是白龙马（Bailongma）想要做的事。

白龙马是一个由 Node.js + Electron 驱动的持续运行桌面 AI Agent 框架，版本号已达 2.1.435。它不是传统意义上的聊天机器人，而是一个以主循环（Main Loop）为驱动的数字意识系统：在用户交互时处理消息，空闲时自动整理记忆、刷新上下文、检查任务状态，并把运行状态实时推送到前端 Brain UI。整个项目由中文开发者"xiaoyuanda666-ship-it"维护，采用 MIT 许可证开源。

一、为什么需要"持续运行"的 AI Agent？

大多数 AI 对话产品（包括 ChatGPT、Claude Web）都是按需启动、问答即结束的"会话型"产品。它们有几个共同局限：

第一，无法积累真正的长期记忆。 每次对话结束后，模型的记忆随之清零，下次重新开始无法主动调用前几次讨论的上下文。即便有对话历史功能，也只是机械地把历史记录塞入上下文窗口，无法真正理解哪些信息重要、哪些需要保留、哪些可以遗忘。

第二，无法感知环境变化。 传统对话式 AI 不知道你的电脑在运行什么、桌面上有什么文件、系统当前状态如何。白龙马在启动时会主动扫描本地资源：已安装软件、Git 仓库、SSH 配置、地理天气、当前热点话题，并把这些信息注入 AI 的上下文，让它能"看见"用户的真实环境。

第三，无法主动行动。 传统 AI 只在用户发送消息后被动响应，无法主动发起行动。白龙马的主循环支持定时心跳、任务队列、提醒系统和预取机制，在没有用户输入时也会按节奏执行后台任务——比如整理记忆图谱、检查任务进度、刷新热点信息。

白龙马正是针对这三个痛点构建的：它是一个有记忆感知、能主动思考、可持续运行的桌面 AI 助手。

二、架构解析：七层模块如何协同

白龙马的架构设计清晰，可分为七个核心层：

1. Electron 桌面壳层（electron/）

Electron 提供跨平台桌面窗口、托盘图标、自动更新和单实例运行能力。预加载脚本（preload.cjs）负责安全桥接，让前端 Brain UI 能访问必要的系统能力而不过度暴露 Node.js 运行时。桌面窗口还提供焦点横幅（Focus Banner）功能，在任务执行期间在屏幕边缘显示运行状态。

2. 本地 HTTP 服务层（src/api.js）

内置 HTTP 服务器监听默认端口 3721（被占用时自动寻找可用端口），对外暴露 RESTful API 和 SSE 事件流。常用接口包括：POST /message 发送用户消息、GET /events 订阅实时事件流、GET /status 查询运行状态、GET /quota 查看 API 限流信息、GET /memories 查询记忆、POST /activate 激活 Provider 配置等。

3. LLM 调用层（src/llm.js）

统一封装 OpenAI 兼容接口，支持 DeepSeek、MiniMax、OpenAI、Qwen、Moonshot、Zhipu、MiMo 等多模型。通过 src/config.js 配置 Provider 和模型参数，每轮对话根据消息内容、任务状态和可用能力动态注入工具 schema。LLM 调用支持流式输出（Server-Sent Events），思考过程和工具调用结果实时推送。

4. 记忆系统层（src/memory/）

这是白龙马最具特色的子系统。基于本地 SQLite 数据库（better-sqlite3）持久化存储：对话记录、记忆节点、记忆关系、行动日志、提醒、预取缓存、媒体历史、线程状态等。记忆系统支持全文检索（FTS5）、语义补充、记忆去重与合并、可见性控制和焦点线程管理。每次对话前后，记忆注入器（src/context/）根据相关性自动选择要注入的记忆片段、近期对话和用户画像。

5. 工具执行层（src/capabilities/）

工具系统采用 schema 驱动架构，工具定义位于 src/capabilities/schemas/，运行时由 src/capabilities/schemas.js 汇总选择。每次主循环根据当前消息、任务状态、最近行动和可用 Provider 能力，动态选择本轮要暴露的工具集，避免每轮注入全部工具。内置工具覆盖：通信（Discord/微信/邮件）、文件系统（读写删列）、Shell 执行、网页抓取、搜索、记忆管理、提醒设置、ACUI 卡片渲染、语音合成、音乐/视频生成、本地 Agent 委托等。此外还支持自定义工具市场安装。

6. 语音系统层（src/voice/）

支持云端 ASR（自动语音识别）和多种 TTS 服务，可在 Brain UI 设置面板中配置语音输入/输出开关、音色选择和 API 凭证。通过 POST /tts/stream 接口支持流式语音生成。

7. 前端 UI 层（src/ui/brain-ui/）

Brain UI 是项目的主操作界面，通过 HTTP + SSE + WebSocket 与后端通信。提供多渠道聊天、实时思考流、记忆图谱可视化、焦点线程面板、热点信息面板、文档知识面板、人物卡片、语音控制面板、设置页面和 ACUI 卡片渲染（天气、自检、唤醒等场景化组件）。前端还包含 ACUI（Agent-Centered User Interface）设计理念文档和 Phase 1 设计稿，体现作者对 Agent 原生交互范式的思考。

三、Brain UI 界面一览

图2：Brain UI 主界面

Brain UI 不是普通的聊天界面，它更像一个 Agent 的"控制台"。左侧是传统聊天面板，但每条消息下方还会实时展示 AI 的思考过程（思考流），让用户能看见 Agent 内部推理的中间步骤。右侧面板可根据需要切换显示：记忆图谱（节点和关系可视化）、焦点线程（当前任务状态）、热点信息（实时抓取的新闻）、文档知识库、人物卡片（用户画像）和系统状态。UI 本身基于原生 HTML/CSS/JS 实现，没有引入 React/Vue 等框架，保持了轻量和可控性。

四、多模型接入：灵活切换 AI 大脑

白龙马通过统一的 LLM 调用层支持多 Provider 接入，包括：

Provider	备注
OpenAI	GPT-4o、GPT-4o-mini 等
DeepSeek	性价比高
MiniMax	国内可用
Qwen（通义千问）	阿里云
Moonshot（月之暗面）	Kimi 底层
Zhipu（智谱）	清华智谱
MiMo	小米
自定义	任何 OpenAI 兼容接口，支持私有部署

用户只需在激活页（/activation）或 .env 文件中填写 API Key，即可在 Brain UI 设置面板中随时切换模型。所有配置持久化到本地 SQLite，不会在每次启动时重复配置。

五、部署体验：门槛有多低？

白龙马的部署非常简单：

git clone https://github.com/xiaoyuanda666-ship-it/BaiLongma
cd BaiLongma
npm install
npm start

首次启动会打开激活页，填写任意已支持 Provider 的 API Key 即可。配置完成后进入 Brain UI 主界面。项目没有提供 Dockerfile 或 docker-compose.yml，这与其 Electron 桌面应用的定位有关——Electron 应用天然需要访问本地系统资源（文件系统、托盘、系统通知等），容器化并不能带来实质收益，反而会增加复杂度。因此"快速部署"标注为 partially_supported（部分支持）：有完整的 Web UI 和文档，但不支持 Docker 一键启动。

硬件要求方面，由于 LLM 推理本身由云端 API 完成，本地只需承担 Electron 界面和 SQLite 存储的开销，推荐 4GB 以上内存、500MB 以上磁盘空间，不强制要求 GPU。

六、社交连接与外部集成

白龙马支持与 Discord 和微信的桥接。外部消息通过社交连接器（src/social/）进入同一个主循环，AI 的回复会根据消息来源渠道路由到对应的平台。这意味着用户可以在一个界面里同时管理多渠道对话——既有本地 Brain UI 聊天，也有 Discord 群聊和微信消息。微信桥接通过 wechat-clawbot 实现，登录后可获取微信二维码状态并支持登出操作。Discord 连接器则通过 Bot Token 接入频道，支持频道消息的接收和回复。

七、安全设计：本地优先，访问可控

作为一款有文件系统访问能力的本地 Agent，安全设计尤为重要：

• 网络访问控制：本地 HTTP 服务默认只允许本机访问（127.0.0.1），敏感接口（激活、设置、管理、记忆修改）不对外暴露。通过环境变量可开启局域网访问，但需要配合 API Token 认证。
• Electron 隔离：前端通过预加载脚本访问 Node.js 能力，避免直接暴露完整的 Node.js 运行时。启用上下文隔离（contextIsolation）。
• 工具执行管控：所有文件操作和 Shell 命令经过执行器统一路由，危险操作会触发确认流程或策略检查。
• API 限流：内置配额管理（src/quota.js），防止 API 滥用。

八、局限与思考

白龙马也有一些值得注意的局限：

1. 依赖外部 API，不适合完全离线场景。 所有 LLM 推理都需要调用云端 API，没有本地模型支持。对于网络受限或对数据隐私要求极高的场景，这是一个硬性限制。

2. Electron 桌面应用的重量感。 Electron 以"内存占用大"著称，尽管白龙马本体逻辑不重，但 Electron 框架本身会带来一定的资源开销。在低配置机器上可能体验不佳。

3. 记忆质量依赖注入策略。 记忆系统的效果很大程度上取决于 src/context/ 的注入选择逻辑。项目内置了多种测试（rule-context、relevance、section-gate 等）来验证注入质量，但随着记忆量增长，召回和筛选策略可能面临挑战。

4. 社交桥接的维护成本。 Discord 和微信桥接依赖第三方工具（wechat-clawbot），这些工具本身可能面临平台政策风险，需要持续维护。

九、总结与行业意义

白龙马代表了一种本地优先、持续运转、记忆驱动的 AI Agent 范式。它不是简单地把 LLM API 套了个壳，而是围绕"数字意识"这个主题，构建了一套完整的感知-记忆-行动闭环：从环境扫描、本地资源感知，到 SQLite 记忆持久化，再到动态上下文注入和工具执行，最后通过 Brain UI 可视化呈现——每一个环节都有对应的代码模块支撑。

396 star 和 123 forks 的社区规模说明它不是热门的"流量项目"，但其代码质量、架构完整性和文档丰富度都相当扎实。对于希望深入理解 AI Agent 工程实现、或需要一个可定制本地 AI 助手的开发者来说，白龙马是一个值得研究的参考实现。

---

项目地址：https://github.com/xiaoyuanda666-ship-it/BaiLongma | 主语言：JavaScript/Node.js | 许可证：MIT