xiaozuoAssistant（小左助理）

xiaozuoAssistant 是一个**本地优先（Local-first）**的个人 AI 助手：提供 Web UI、可扩展的技能/插件体系、以及多通道接入能力，面向办公自动化场景。

亮点能力

• Web UI + 实时通信：浏览器访问 http://localhost:3021（生产环境）或 http://localhost:3001（开发环境），Socket.IO 实时收发消息。
• 多通道（Channels）：内置 Web/Terminal，并可按配置启用 Telegram/飞书/钉钉/微信等。
• 技能（Skills）+ 工具调用：模型可触发工具调用（OpenAI tools 兼容格式），技能注册表可扩展。
• 增强型记忆系统（Enhanced Memory）：
  • 短期记忆：基于会话的上下文管理。
  • 长期记忆（向量）：基于 LanceDB 的语义检索，支持自动汇总和维护。
  • 结构化记忆（SQLite）：存储用户画像、项目信息和结构化事实。
  • 自动归档：每 3 分钟自动扫描活跃会话，提炼项目信息和通用知识；支持手动触发。
• 项目与笔记管理：
  • 项目空间：管理项目元数据（描述、成员、目录等），为 AI 提供项目上下文（支持多项目关联）。
  • 智能笔记本：记录笔记和待办事项（Todo），支持关键字自动归档。
• 插件体系 (Plugins)：
  • Plugins 管理中心：可视化管理所有 AI 能力，支持动态启用/禁用。
  • 第三方插件市场：支持接入 WPS Office、飞书文档等第三方服务（基于 OAuth 2.0 授权）。
  • 动态加载机制：根据会话上下文和用户意图，动态加载所需的工具集。
• 定时任务 (Scheduler)：
  • 可视化调度：在设置面板查看和管理系统定时任务（如记忆归档、数据维护）。
  • 手动触发：支持立即执行维护任务，无需等待定时周期。
• 更易接入新模型：统一 LLM(OpenAI 兼容) client 工厂与 provider→baseURL 解析，便于新增 provider。
• CLI 管理：支持 start/stop/doctor/export/import，完美支持 Windows/macOS/Linux 跨平台运行。

系统要求

• 操作系统: macOS, Linux, Windows (WSL 或 PowerShell/CMD)
• Node.js: v18.0.0 或更高版本 (参见 Node.js 环境安装指南)
• Python: v3.0+ (某些依赖可能需要)

快速开始（推荐：npm 全局安装）

npm install -g xiaozuoassistant --registry=https://registry.npmjs.org
xiaozuoAssistant start

然后浏览器打开：http://localhost:3021

停止服务：

xiaozuoAssistant stop

常用命令

• 启动服务（后台运行）：xiaozuoAssistant start
• 停止服务：xiaozuoAssistant stop
• 环境自检：xiaozuoAssistant doctor
• 数据导出：xiaozuoAssistant export
• 数据导入：xiaozuoAssistant import

更完整的指令说明见：指令集（CLI）

运行模式

开发模式（前后端联调）

端口默认为 3001。

npm install
npm run dev

生产模式（构建后运行）

端口默认为 3021。

npm install
npm run build
node dist/server/index.js

xiaozuoAssistant start 本质上也是启动 dist/server/index.js，并将日志写入你执行命令的当前目录（CWD）下的 logs/。

工作目录（非常重要）

xiaozuoAssistant 将**以你执行命令时所在目录（CWD）**作为工作目录，并在此目录读写：

• config.json：配置文件
• data/sqlite/：结构化数据（项目、笔记本、用户画像）
• data/lancedb/：向量记忆数据
• logs/：运行日志（包含 server.pid）

建议为每套数据创建独立目录，例如：

mkdir -p ~/xiaozuo && cd ~/xiaozuo
xiaozuoAssistant start

配置与模型

• 你可以通过 config.json 或 API (/api/config) 更新 LLM 配置。
• 支持 OpenAI 兼容的多 provider（示例：openai/deepseek/minimax/doubao/qwen/custom），并会自动映射 baseURL。
• 配置项增强：
  • maxHistoryMessages: 控制发送给 LLM 的历史消息数量（默认 20），防止 Context Window 溢出。
  • maxToolIterations: 限制工具调用的最大迭代次数（默认 15），防止死循环。
• 可用环境变量：XIAOZUO_LLM_API_KEY（覆盖 config.json 中的 key）。

文档

• Node.js 环境安装指南
• 功能特性详解
• 技术架构
• 数据库设计
• API 参考
• 指令集（CLI）
• 数据迁移指南

许可证

MIT