xiaozuoassistant 0.2.20 → 0.2.22

package/README.md

@@ -1,119 +1,119 @@
-# 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 环境安装指南](docs/nodejs_install_guide.md))
-- **Python**: v3.0+ (某些依赖可能需要)
-
-## 快速开始（推荐：npm 全局安装）
-
-```bash
-npm install -g xiaozuoassistant --registry=https://registry.npmjs.org
-xiaozuoAssistant start
-```
-
-然后浏览器打开：`http://localhost:3021`
-
-停止服务：
-
-```bash
-xiaozuoAssistant stop
-```
-
-## 常用命令
-
-- 启动服务（后台运行）：`xiaozuoAssistant start`
-- 停止服务：`xiaozuoAssistant stop`
-- 环境自检：`xiaozuoAssistant doctor`
-- 数据导出：`xiaozuoAssistant export`
-- 数据导入：`xiaozuoAssistant import`
-
-更完整的指令说明见：[指令集（CLI）](docs/commands.md)
-
-## 运行模式
-
-### 开发模式（前后端联调）
-
-端口默认为 `3001`。
-
-```bash
-npm install
-npm run dev
-```
-
-### 生产模式（构建后运行）
-
-端口默认为 `3021`。
-
-```bash
-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`）
-
-建议为每套数据创建独立目录，例如：
-
-```bash
-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 环境安装指南](docs/nodejs_install_guide.md)
-- [功能特性详解](docs/features.md)
-- [技术架构](docs/technical_architecture.md)
-- [数据库设计](docs/database_schema.md)
-- [API 参考](docs/api_reference.md)
-- [指令集（CLI）](docs/commands.md)
-- [数据迁移指南](docs/migration_guide.md)
-
-## 许可证
-
-MIT
+# 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 环境安装指南](docs/nodejs_install_guide.md))
+- **Python**: v3.0+ (某些依赖可能需要)
+
+## 快速开始（推荐：npm 全局安装）
+
+```bash
+npm install -g xiaozuoassistant --registry=https://registry.npmjs.org
+xiaozuoAssistant start
+```
+
+然后浏览器打开：`http://localhost:3021`
+
+停止服务：
+
+```bash
+xiaozuoAssistant stop
+```
+
+## 常用命令
+
+- 启动服务（后台运行）：`xiaozuoAssistant start`
+- 停止服务：`xiaozuoAssistant stop`
+- 环境自检：`xiaozuoAssistant doctor`
+- 数据导出：`xiaozuoAssistant export`
+- 数据导入：`xiaozuoAssistant import`
+
+更完整的指令说明见：[指令集（CLI）](docs/commands.md)
+
+## 运行模式
+
+### 开发模式（前后端联调）
+
+端口默认为 `3001`。
+
+```bash
+npm install
+npm run dev
+```
+
+### 生产模式（构建后运行）
+
+端口默认为 `3021`。
+
+```bash
+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`）
+
+建议为每套数据创建独立目录，例如：
+
+```bash
+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 环境安装指南](docs/nodejs_install_guide.md)
+- [功能特性详解](docs/features.md)
+- [技术架构](docs/technical_architecture.md)
+- [数据库设计](docs/database_schema.md)
+- [API 参考](docs/api_reference.md)
+- [指令集（CLI）](docs/commands.md)
+- [数据迁移指南](docs/migration_guide.md)
+
+## 许可证
+
+MIT