内容
# 文档图谱 DocGraph
English | [中文](README.zh-CN.md)
文档图谱 DocGraph 是一个面向团队、内部知识库和本地 AI 代理的本地优先文档知识图谱。它将本地文档、Git 仓库文档、HTML 网站、Confluence 页面、OpenAPI 规范、SFTP 目录和网络文档索引到本地 SQLite，然后通过嵌入式 Web UI、REST API 和 MCP 工具公开结果。
目标是保持文档搜索、上下文组装和影响分析靠近您的机器或内网，而无需将内部知识同步到外部 SaaS 服务。
## 截图
仪表盘显示本地知识库的来源、文档、章节、节点、边和同步作业计数。
连接器允许您添加、编辑、同步和检查文档来源。
搜索提供跨文档章节和生成的检索配置文件的本地检索。
## 功能
- 单个 Go 二进制文件，带有嵌入式 Web UI。
- 本地 SQLite + FTS5 存储，无需外部数据库。
- 支持 `本地`、`Git`、`静态`、`HTML`、`SFTP`、`Confluence`、`OpenAPI` 和 `Web 文档` 来源的连接器。
- MCP 工具：`文档搜索`、`文档上下文`、`获取节点`、`获取章节`、`相关文档` 和 `影响分析`。
- 基于文档的知识图谱，包含节点、边、来源、同步历史和反馈标记。
- 针对混合中文/英文内部文档的中文检索配置文件生成。
- Web/API/SSE 端点的可选令牌身份验证。
## 工作原理
DocGraph 将现有文档转换为本地的可查询知识层：
1. 连接来源：添加本地目录、Git 仓库、静态 HTML、Confluence 页面、OpenAPI 文件、SFTP 文件夹或网络文档中心。
2. 规范化文档：每个连接器将源内容转换为通用文档和章节模型。
3. 本地索引：文档、章节、检索配置文件、节点、边、别名和同步作业存储在 SQLite 中，支持 FTS5 搜索。
4. 建立关系：DocGraph 派生产品/模块/文档/章节/API 节点，并使用证据支持的边连接它们。
5. 查询证据：用户和代理通过 Web UI、REST API 或 MCP 搜索章节、组装任务上下文、检查相关节点并运行影响分析。
除非您明确公开服务器或移动数据库，否则所有数据都保留在配置的本地数据目录中。
## 快速入门
```bash
go build -buildvcs=false -o bin/docgraph ./cmd/docgraph
./bin/docgraph init --data ./.docgraph
./bin/docgraph serve --data ./.docgraph --host 127.0.0.1 --port 8787
```
打开 `http://127.0.0.1:8787`，然后从 Web UI 添加和同步文档来源。
您还可以通过 CLI 添加本地文档来源：
```bash
./bin/docgraph source add --data ./.docgraph --name "文档" --dsn /path/to/docs
./bin/docgraph source sync --data ./.docgraph --id src_xxx
./bin/docgraph search --data ./.docgraph "身份验证失败"
./bin/docgraph context --data ./.docgraph --max-sections 5 "调试身份验证失败"
```
## 开发
```bash
make test
make build
make build-release
make run
```
`make test` 运行 `go test -buildvcs=false ./...`。Makefile 将 Go 构建缓存保存在 `.gocache/` 和 `.gomodcache/` 中，两者都忽略 Git。
## 发布构建
存储库包含 `.github/workflows/release.yml` 中的 GitHub Actions 工作流。
- 手动 `发布` 工作流运行构建并上传工件。
- 推送 `v*` 标签运行测试、构建二进制文件并创建 GitHub 发布。
- 构建工件涵盖 `amd64/arm64` 上的 `linux/windows/darwin`。
- 发布工件包括平台存档和 SHA-256 校验和文件。
- 要手动重建现有发布版本，请运行 `发布` 工作流并将 `release_tag` 设置为标签名称，例如 `v0.1.0`。
示例：
```bash
git tag v0.1.0
git push origin v0.1.0
```
## MCP
DocGraph 支持标准输入/输出 MCP：
```bash
./bin/docgraph mcp --data ./.docgraph
```
HTTP/SSE MCP 设置在 [docs/mcp-setup.md](docs/mcp-setup.md) 中有文档记录。
## 运行时依赖
DocGraph 本身是一个单独的 Go 二进制文件。一些连接器在运行时需要本地工具：
- Git 来源需要本地 `git` 可执行文件。
- SPA 网络爬取需要 Chrome、Chromium、Edge 或 `ROD_BROWSER_BIN` 指向浏览器可执行文件。
## 文档
- [产品需求](docs/docgraph-prd.md)
- [架构](docs/docgraph-architecture.md)
- [MCP 设置](docs/mcp-setup.md)
- [验收清单](docs/docgraph-acceptance.md)
## 安全说明
- 请勿提交真实令牌、cookie、私钥、内部域名、本地数据库或索引文档数据。
- 对于团队或共享部署，请使用 `auth.mode: token`。
- `.docgraph/`、`.docgraph-test/`、`.gocache/`、`.gomodcache/` 和 `bin/` 被忽略。
## 许可证
DocGraph 在 [Server Side Public License v1.0](LICENSE) 下获得许可。
允许内部公司使用、内部部署和内部修改。如果您将 DocGraph 或修改后的版本作为托管服务提供给第三方，则必须遵守 SSPL 第 13 节的规定，提供相应的服务源代码，或获得单独的商业许可证。
