内容
# 文档中心
**一个面向人、应用和智能体的人工智能原生知识工作空间。**
文档中心首先以结构化的 JSON 编辑器模型存储文档。Markdown 是编辑、导入和导出内容的便捷第二格式。自动分段、1024 维嵌入、多语言混合搜索和 GraphRAG 使同一个知识库对人、应用和智能体都很有用，支持网页应用、REST API、TypeScript SDK、CLI 和 MCP 服务器。
[](LICENSE)
[](https://github.com/hiai-gg/docsmint/releases)
[](https://www.npmjs.com/package/@hiai-gg/docsmint)
[](https://hub.docker.com/r/vgalibov/docsmint)
[](https://github.com/hiai-gg/docsmint/stargazers)
[](https://github.com/hiai-gg/docsmint/actions/workflows/ci.yml)
[](https://bun.sh)
[](https://www.typescriptlang.org)
[](https://svelte.dev)
[](https://elysiajs.com)
[](https://tailwindcss.com)
[](https://orm.drizzle.team)
[](CONTRIBUTING.md)
<img width="1920" height="974" alt="文档中心的可安装文档工作空间" src="https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684" />
## 为什么选择文档中心？
- **自然写作**，在丰富的可视化编辑器或原始 Markdown 中写作。
- **查找含义，而不仅仅是关键词**，通过精确的、词汇的、模糊的、向量的、多语言扩展和通过 RRF 融合的图检索。
- **保持检索当前**，通过自动增量分段和文档或元数据更改后的重新嵌入。
- **直接连接智能体**，通过 REST、类型化的 SDK、CLI 或 MCP。
- **控制访问**，使用全局密钥或类别范围内的 `read`、`edit` 和 `write` 权限。
- **拥有整个堆栈**，应用程序数据、向量、图、队列和文件都在您控制的基础设施上运行。
## 0.3.0 版本新增功能？
- **可安装的渐进式 Web 应用（PWA）**，具有清单、服务工作线程、响应式移动外壳、可安装提示、更新安全性和离线备用外壳。
- **离线文档访问**，通过身份分区 IndexedDB/Dexie 快照。离线模式是缓存读取加上显式本地草稿；重新连接时不会静默重放突变。
- **显式本地草稿**，具有本地自动保存、审查/应用、乐观并发（`expectedUpdatedAt`）和可操作冲突处理。
- **可组合的自托管 UI**，具有类型化的仪表板/搜索主机和扩展槽。
- **移动优先的编辑器润色**，包括单个响应式侧栏、安全 PWA 更新、原始 Markdown 自动高度和可访问的窄屏幕控件。
搜索术语：可安装的自托管 PWA 知识库、离线文档阅读、本地草稿、语义多语言搜索、GraphRAG、MCP、TypeScript SDK、CLI 和前端扩展主机。
有关自托管自定义，请参阅 [PWA 主机](docs/PWA_HOSTING.md) 和 [扩展点](docs/EXTENDING.md)。
## 最快的安装方式：给您的智能体这个提示
如果您通过 AI 编码智能体安装 DocsMint，请首先使用此路径。它将设置简化为 Docker 加一个提供者选择，避免不必要的源代码更改。
```text
从 https://github.com/HiAi-gg/docsmint 安装 DocsMint。
验证 Docker 和 Docker Compose v2，克隆存储库，然后运行 `bash scripts/quickstart.sh`。不要打印或提交 .env。要求我仅输入 OpenRouter 密钥或选择 Ollama，然后再次运行 quickstart。验证 http://localhost:50701、http://localhost:50700/api/health 和 `docker compose ps`。不要替换 Bun、重写迁移、禁用 GraphRAG 或删除卷。
```
启动后，打开 **http://localhost:50701** 并创建第一个帐户。
对于手动安装，请使用下面的 Docker 快速入门。
## 快速入门
### 要求
- Docker 引擎或 Docker 桌面版
- Docker Compose v2
- 以下之一：
- [OpenRouter](https://openrouter.ai/) API 密钥；或
- 本地的 [Ollama](https://ollama.com/) 实例
### 使用 Docker 启动
```bash
git clone https://github.com/HiAi-gg/docsmint.git
cd docsmint
bash scripts/quickstart.sh
```
在第一次运行时，该脚本会创建一个被忽略的根 `.env`，生成数据库、身份验证和存储密钥，构建 PostgreSQL 镜像，应用迁移，并启动完整的应用程序。
对于 OpenRouter，请在 `.env` 中添加一个值并再次运行脚本：
```dotenv
OPENROUTER_API_KEY=sk-or-your-key
```
对于 Ollama，请选择本地提供者：
```dotenv
AI_PROVIDER=ollama
OLLAMA_PORT=11434
```
然后确保可用的本地模型：
```bash
ollama pull bge-m3
ollama pull qwen3:8b
bash scripts/quickstart.sh
```
打开 **http://localhost:50701**。API 健康端点是 **http://localhost:50700/api/health**。
### 首次使用
1. 在网页应用中创建您的帐户。
2. 创建一个类别或文件夹，并添加或导入文档。
3. 等待文档管道完成分段和嵌入。
4. 使用精确的短语、相关概念、替代语言或拼写错误进行搜索。
5. 当您想要连接 CLI、MCP 客户端或外部应用程序时，打开 **设置 → API**。
规范的本地端口是：
| 服务 | 端口 |
|---|---:|
| 网页应用 | `50701` |
| REST API | `50700` |
| PostgreSQL | `5437` |
| Redis | `6384` |
| SeaweedFS S3 网关 | `50702` |
| SeaweedFS 文件管理 UI | `50703` |
参阅 [部署](docs/DEPLOYMENT.md)，了解域名、TLS、提供者调优、备份和生产操作。
## 从终端使用 DocsMint
已发布的软件包包括 CLI。它连接到已经运行的 DocsMint 服务器；安装它不会部署服务器。
```bash
npm install @hiai-gg/docsmint
```
```bash
bunx --package @hiai-gg/docsmint docsmint init \
--url http://localhost:50700 \
--key 'your-global-or-category-key'
bunx --package @hiai-gg/docsmint docsmint search "project architecture"
bunx --package @hiai-gg/docsmint docsmint list
bunx --package @hiai-gg/docsmint docsmint read <document-id>
bunx --package @hiai-gg/docsmint docsmint create \
--title "Release notes" --content "# Version 0.2.9"
```
凭证也可以通过 `HIAI_DOCS_URL` 和 `HIAI_DOCS_API_KEY` 提供。有关每个命令和配置优先级，请参阅 [CLI 指南](packages/cli/README.md)。
## 连接 MCP 客户端
DocsMint 将文档搜索、读取、创建、更新、文件夹、快照、历史记录和导出公开为 MCP 工具。
```json
{
"mcpServers": {
"docsmint": {
"command": "bunx",
"args": ["--package", "@hiai-gg/docsmint", "docsmint-mcp"],
"env": {
"HIAI_DOCS_URL": "http://localhost:50700",
"HIAI_DOCS_API_KEY": "your-global-or-category-key"
}
}
}
}
```
直接运行服务器以验证安装：
```bash
bunx --package @hiai-gg/docsmint docsmint-mcp
```
服务器使用标准输入/输出，并与支持标准 MCP 配置的 MCP 客户端（如 Claude Desktop、Cursor 和接受标准 MCP 配置的编码智能体）一起工作。请参阅 [MCP 指南](packages/mcp-server/README.md)，了解其 10 个工具和路由。
## 安装后的智能体技能
MCP 工具是推荐的便携式智能体技能。可以为智能体绑定一个类别范围内的智能体，使其仅接收所需的知识和操作；受信任的个人智能体可以使用全局密钥。智能体不需要数据库或文件系统访问权限。
启动后，在 **设置 → API** 中创建 API 密钥，并将上面的 MCP 模块添加到智能体客户端。对于自定义智能体工作流，请在 CLI、SDK 或 REST API 中使用相同的密钥。
## TypeScript SDK
```bash
bun add @hiai-gg/docsmint
```
```ts
import { DocsClient } from "@hiai-gg/docsmint";
const docs = new DocsClient({
baseUrl: "http://localhost:50700",
apiKey: process.env.HIAI_DOCS_API_KEY,
});
const created = await docs.createDoc({
title: "Meeting notes",
content: "# Agenda",
});
const results = await docs.search("what did we decide?");
console.log(created.id, results.items);
```
SDK 是一个具有重试机制的 `fetch` 客户端，用于处理瞬时故障。请参阅 [SDK 参考](packages/sdk/README.md) 和 [REST API](docs/API.md)。
## API 密钥和集成
在 **设置 → API** 中创建和撤销集成密钥。
| 凭证 | 用途 | 访问权限 |
|---|---|---|
| 全局 API 密钥 | 受信任的全局 CLI、MCP、SDK 或服务 | 所有者内容 |
| 类别密钥 | 最小权限的智能体或产品集成 | 一个类别，具有选定的权限 |
| 操作员密钥 | 管理和重新索引操作 | 仅限 `/api/admin/*` |
类别权限是显式且非分层的：
- `read` 允许列表、读取、搜索和导出；
- `edit` 允许更新现有内容、附件和版本；
- `write` 允许创建、移动、删除、共享和发布操作。
当集成需要多种功能时，请组合权限。API 密钥的生命周期操作需要拥有浏览器会话；API 密钥无法创建或提升另一个密钥。服务器到服务器的集成不受浏览器 CORS 的影响。浏览器集成必须在其确切的源中添加 `CORS_ORIGINS`。
## 包含的内容？
```text
frontend/ SvelteKit 工作区和 TipTap 编辑器
backend/ Elysia REST API、搜索、工作线程和身份验证
packages/db/ Drizzle 模式和迁移
packages/sdk/ 类型化的 API 客户端
packages/cli/ 终端客户端
packages/mcp-server/ MCP 标准输入/输出服务器
postgres/ 带有向量和图扩展的 PostgreSQL 镜像
```
Docker 部署运行：
- **Web** — 文档编辑器、文件夹、类别、共享、设置和搜索；
- **API** — 文档、附件、版本、密钥、搜索和管理；
- **PostgreSQL 18** — 关系数据、pgvector/pgvectorscale 向量和 Apache AGE 图，存储在一个数据库中；
- **Redis 8** — BullMQ 队列、缓存、重试和作业恢复；
- **SeaweedFS** — 兼容 S3 的附件存储。
## 搜索工作原理
每次文档保存都会调度后台工作。内容被分段，变更的段落被嵌入，生成的完整版本被原子化激活。以前的有效版本如果提供者调用失败，仍然可搜索。
搜索结合精确的标题匹配、多语言词汇搜索、容错的模糊匹配、语义向量、自适应查询扩展和 Apache AGE 图邻居。互惠排名融合了各个通道，不允许一个弱提供者的结果主导。授权在检索之前和结果返回之前应用。
GraphRAG 是参考配置中的正常搜索路径。它在嵌入准备好后提取实体，并查找超出直接关键词或向量相似性的相关文档。当外部模型不可用时，它会顺利降级。
有关管道内部和调优，请参阅 [架构](docs/ARCHITECTURE.md) 和 [部署](docs/DEPLOYMENT.md)。
## 技术栈
- Bun、TypeScript、Elysia、Zod 和 Pino
- Svelte 5、SvelteKit、Tailwind CSS 和 TipTap
- Better Auth 和 Drizzle ORM
- PostgreSQL 18、pgvector、pgvectorscale 和 Apache AGE
- Redis 8 和 BullMQ
- 具有 S3 兼容 API 的 SeaweedFS
- 通过 OpenRouter 或本地 Ollama 支持 OpenAI 兼容的提供者
## 比较
DocsMint 与几个优秀的开源知识工具重叠，但其重点是一个紧凑的知识运行时，由人类和智能体平等共享。
| 项目 | 主要优势 | 与 DocsMint 的区别 |
|---|---|---|
| [Outline](https://github.com/outline/outline) | 精致的团队 Wiki 和协作 | DocsMint 强调内置检索、GraphRAG、作用域智能体访问、CLI 和 MCP |
| [Docmost](https://github.com/docmost/docmost) | 协作 Wiki 和实时编辑 | DocsMint 以自动嵌入和面向智能体的集成表面为中心 |
| [AppFlowy](https://github.com/AppFlowy-IO/AppFlowy) | 广泛的本地优先生产力工作区 | DocsMint 更窄：自托管文档和检索服务 |
| [AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) | 聊天导向的 RAG，适用于导入的源 | DocsMint 从可编辑的知识库开始，并向许多客户端公开 |
| [Danswer](https://github.com/danswer-ai/danswer) / Onyx | 跨外部连接器的企业搜索 | DocsMint 拥有和编辑其原生语料库，而不是主要索引其他系统 |
这是产品定位总结，而不是声称每个项目都缺少某个功能。在选择部署时，请查看每个项目的当前文档。
## 文档
- [文档索引](docs/README.md)
- [产品使用](docs/USAGE.md)
- [REST API](docs/API.md) 和 [OpenAPI JSON](docs/openapi.json)
- [架构](docs/ARCHITECTURE.md)
- [部署和操作](docs/DEPLOYMENT.md)
- [扩展点](docs/EXTENDING.md)
- [维护者发布流程](docs/RELEASING.md)
- [安全策略](SECURITY.md)
- [变更日志](CHANGELOG.md)
## 开发
```bash
bun install
bun run lint
bun run typecheck
bun run test
bun run build
```
在打开拉取请求之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。请通过 [SECURITY.md](SECURITY.md) 而不是公共问题报告漏洞。
## 许可证
DocsMint 在 [Apache License 2.0](LICENSE) 下发布。
在 [HiAi](https://github.com/HiAi-gg) 生态系统中构建为独立的开源项目。
