内容
# LibraNia
LibraNia 是一个本地优先的 AI 知识工作空间，适用于 Markdown 笔记、图书馆搜索、图形导航、AI 聊天、协作黑板代理、自定义工具和从外部代理客户端访问 MCP。
核心规则很简单：本地图书馆是真相的源头。AI 聊天和代理可以进行研究或推理，但持久的知识应该成为 Markdown 笔记、标签和 `[[精确笔记标题]]` 维基链接，以便未来的工作可以重用它。
## 当前应用表面
LibraNia 作为一个 React/Vite UI 运行，背后是一个 Express API 和 Socket.IO。应用路由如下：
- 首页仪表盘：`/`
- 图书馆：`/library`
- 聊天：`/chat`
- 黑板：`/blackboard`
- 图形：`/graph`
- 设置：`/settings`
## 功能
### 首页仪表盘
- 可定制的仪表盘小部件存储在 `localStorage` 中
- 聊天、黑板、图书馆和图形的快速操作
- 笔记、图形链接、标签和对话的工作空间指标
- 最近的笔记、图形健康状况、最近的研究线程和标签词汇
- 舒适或紧凑的仪表盘密度
### 图书馆
- Markdown 笔记编辑
- 带有快速导航的笔记列表
- 通过笔记 API 支持笔记创建、编辑、软删除、恢复和回收站
- 笔记和标签管理视图上的标签
- `[[维基链接]]` 、反向链接和相关笔记面板
- AI 自动链接，追加新链接而不是删除现有链接
- 图书管理员询问面板，用于笔记范围的问题
- 所选笔记的内容上传/列表/删除
- 将可读内容导入为笔记
- 通过导出对话框导出笔记
### 聊天
- 对话列表和消息历史
- 提供商和模型选择
- 支持研究模式的 AI 聊天端点
- 用于实时应用行为的 Socket.IO 连接
- 后端基于图书馆的研究工具
### 图形
- 2D/3D 力导向图形视图
- 来自笔记的图形节点
- 来自维基链接和相关笔记关系的边
- 搜索、选择、邻居高亮、缩略图和侧面板导航
### 黑板
- 协作的多代理任务会话
- 会话列表，支持重命名和删除
- 可折叠和可调整大小的会话轨道
- 聊天室样式的代理/用户对话视图
- 可折叠和可调整大小的黑板工作区检查器
- 现有黑板会话中的用户消息
- `@代理` 提及流程由黑板服务处理
- 代理响应详细信息，用于调试提示、工具调用和中间输出
- 代理管理，适用于代理名称、描述、系统、工具访问、自定义工具指令和响应预算
- 静态工具和 HTTP 工具的工具生成器
- 工具生成器中内置的工具参考
- 用于内置和自定义工具测试的工具游乐场
- 通过内置工具 `export_blackboard` 支持导出代理
### 设置
- Claude、OpenAI、DeepSeek 和自定义提供商的 AI 提供商配置
- 删除存储的提供商密钥
- 具有多个 API 密钥的自定义提供商
- 自定义基准 URL 和自定义标头
- 用于网络搜索支持的 Tavily API 密钥配置
设置不再在 UI 中公开应用程序模式选择器。
## 提供商和环境配置
提供商密钥存储在 `data/.env` 中，而不是项目根目录的 `.env` 中。
后端从以下位置加载提供商配置：
```text
data/.env
```
实现位于：
- `backend/server.ts`：启动时加载 `data/.env`
- `backend/store/env.store.ts`：读取和写入提供商密钥、自定义标头、模型和 Tavily 密钥
存储在那里常见的密钥包括：
```text
CLAUDE_API_KEY="..."
CLAUDE_MODEL="..."
OPENAI_API_KEY="..."
OPENAI_MODEL="..."
DEEPSEEK_API_KEY="..."
DEEPSEEK_MODEL="..."
CUSTOM_API_KEY="..."
CUSTOM_API_KEYS="[\"key1\",\"key2\"]"
CUSTOM_MODEL="..."
CUSTOM_BASE_URL="..."
CUSTOM_CUSTOM_HEADERS="[{\"name\":\"Header\",\"value\":\"value\"}]"
TAVILY_API_KEY="..."
```
运行时路径覆盖仍然可以通过进程环境变量传递：
- `LIBRANIA_DATA_DIR`：数据目录，默认为 `./data`
- `LIBRANIA_DB_PATH`：显式 SQLite 数据库路径
- `LIBRANIA_MODELS_DIR`：嵌入/模型缓存目录
- `LIBRANIA_UPLOAD_DIR`：上传目录
- `PORT`：`start.js` 使用的服务器端口，默认为 `3001`
- `LIBRANIA_PORT`：`backend/server.ts` 接受的默认端口
- `LIBRANIA_API_BASE_URL`：黑板 HTTP 工具用于相对 `/api` 调用的基准 URL
## 架构
主要层：
- 带有 Vite 的 React 19 UI
- 共享布局壳下的 HashRouter 路由
- `/api` 下的 Express REST API
- Socket.IO 服务器和前端套接字上下文
- 通过 Drizzle 和 `better-sqlite3` 的 SQLite 数据库
- Markdown 笔记和本地内容存储
- Claude、OpenAI、DeepSeek 和自定义提供商的 AI 提供商适配器
- 研究工具和网络搜索服务
- 黑板服务、代理管理、工具执行和会话导出
- `mcp-server/` 中的 MCP stdio 服务器
## REST API 区域
后端注册了这些 API 区域：
- `/api/notes`
- `/api/content`
- `/api/search`
- `/api/tags`
- `/api/export`
- `/api/config`
- `/api/app`
- `/api/ai`
- `/api/graph`
- `/api/providers`
- `/api/conversations`
- `/api/chat`
- `/api/library/ask`
- `/api/blackboard/*`
黑板特定端点包括：
- `GET /api/blackboard/agents`
- `POST /api/blackboard/agents`
- `PUT /api/blackboard/agents/:id`
- `DELETE /api/blackboard/agents/:id`
- `GET /api/blackboard/tools`
- `POST /api/blackboard/tools`
- `PUT /api/blackboard/tools/:id`
- `DELETE /api/blackboard/tools/:id`
- `POST /api/blackboard/tools/:id/execute`
- `GET /api/blackboard/sessions`
- `GET /api/blackboard/sessions/:id`
- `PATCH /api/blackboard/sessions/:id`
- `DELETE /api/blackboard/sessions/:id`
- `POST /api/blackboard/sessions/:id/messages`
- `POST /api/blackboard/assign`
## MCP 集成
MCP 服务器位于 `mcp-server/`，通过 stdio 为外部代理客户端公开 LibraNia。
可用的 MCP 工具：
- `search_notes`
- `get_note`
- `create_note`
- `update_note`
- `add_tags`
- `list_tags`
设置：
```bash
cd mcp-server
npm install
npm run build
npm run setup-codex
npm run setup-cli
```
验证：
```bash
codex mcp get librania
claude mcp get librania
```
MCP 设置脚本传递 `LIBRANIA_DATA_DIR`，以便外部客户端读取 `data/` 下的相同本地数据库。
## 研究协议
适用于 Codex、Claude Code 和其他代理客户端：
1. 首先搜索 LibraNia。
2. 在进行外部研究之前，先阅读相关笔记。
3. 仅在库缺失、不完整、过时或用户要求当前信息时，才使用网络搜索。
4. 在将网络发现用作最终知识之前，将有用的持久性网络发现写回 LibraNia。
5. 添加标签并使用 `[[精确笔记标题]]` 链接连接笔记。
支持策略文件：
- `AGENTS.md`
- `CLAUDE.md`
- `mcp-server/README.md`
## 安装
要求：
- Node.js 18+
- npm 7+
- `better-sqlite3` 和 `sharp` 的原生构建支持
安装主应用：
```bash
npm install
```
安装 MCP 依赖项：
```bash
cd mcp-server
npm install
cd ..
```
## 构建
```bash
npm run build:frontend
npm run build:backend
npm run build:package
```
构建 MCP 服务器：
```bash
cd mcp-server
npm run build
cd ..
```
## 运行
构建并启动生产服务器：
```bash
npm run build:package
npm start
```
`npm start` 运行 `start.js`，在 `http://localhost:3001` 上提供构建的应用和 API，除非设置了 `PORT`。
Windows 帮助程序：
```bat
start.bat
```
`start.bat` 构建软件包，修复 ESM 导入，构建 MCP 服务器，然后启动 `scripts/start-supervisor.js`。
前端开发服务器：
```bash
npm run dev
```
## 本地数据
本地运行时数据不会被故意提交。
重要路径：
```text
data/librania.db SQLite 数据库
data/.env 提供商密钥、模型、自定义标头、Tavily 密钥
data/notes/ 使用文件支持存储时，本地笔记文件
data/uploads/ 上传的文件
data/blackboard-exports/ 黑板 Markdown 导出
data/models/ 使用时，本地模型/缓存目录
content/ 导入或附加的内容文件
```
## 项目布局
```text
backend/ Express API 路由、服务、数据库、AI、黑板、工具
src/ React UI、路由、钩子、API 客户端、组件、样式
mcp-server/ Stdio MCP 服务器和设置脚本
scripts/ 启动、构建、原生模块和同步帮助程序
bin/ CLI 启动器
docs/images/ 文档图表
data/ 本地运行时数据，gitignored
content/ 本地上传/导入的文件，gitignored
```
## 有用的文件
- `src/routes/Home.tsx`：仪表盘
- `src/routes/Library.tsx`：图书馆工作区
- `src/routes/Chat.tsx`：聊天路由
- `src/routes/Blackboard.tsx`：黑板 UI、代理、工具、游乐场
- `src/routes/Settings.tsx`：设置页面
- `src/components/Settings/AIProviderSettings.tsx`：提供商和 Tavily 设置
- `backend/api/routes.ts`：主 API 路由器
- `backend/api/blackboard.routes.ts`：黑板 API
- `backend/services/blackboard.service.ts`：黑板代理、会话、工具、导出
- `backend/store/env.store.ts`：`data/.env` 提供商存储
- `backend/server.ts`：服务器启动和 `data/.env` 加载
- `mcp-server/src/index.ts`：MCP 工具服务器
参见 [workflow.md](workflow.md) 获取系统工作流程和基础设施图表。
