内容
<div align="center">
<img src="docs/assets/cortrix-logo.svg" width="100" alt="Cortrix logo">
# Cortrix
面向检索、记忆和 AI 驱动应用的智能存储。
[](https://www.gnu.org/licenses/agpl-3.0)
[](https://github.com/cortrix/cortrix/releases)
[](https://en.cppreference.com/w/cpp/17)
[快速入门](docs/QUICKSTART.md) · [代理访问](docs/agent-access.md) · [兼容性](docs/compatibility.md) · [OpenAPI](api/openapi.yaml)
</div>
Cortrix 提供了一个本地优先的语义存储服务器，具有命名空间、文档、块、混合搜索、内存 API 和面向代理的访问路径。它旨在为需要可编程检索层的应用程序和代理设计，而不是一次性向量数据库包装器。
存储库包括：
- `cortrix-server`：C++ 后端和 HTTP API。
- `api/openapi.yaml`：公共 OpenAPI 契约。
- `cortrix-mcp/`：用于 IDE 和代理客户端的 MCP 服务器。
- `sdk/python/`：Python SDK。
- `cortrix-agent/`：内置的固定流程 RAG 聊天服务。
- `web/`：本地 Web UI。
## 文档地图
从这里开始：
- [快速入门](docs/QUICKSTART.md)：构建、配置、启动和运行第一个健康/API 检查。
- [代理访问](docs/agent-access.md)：在 HTTP/OpenAPI、MCP、Python SDK 和内置代理之间选择。
- [兼容性和已知状态](docs/compatibility.md)：API、MCP、SDK、代理、身份验证、租户/RBAC、内存提取、基准测试和安全强化。
- [OpenAPI 规范](api/openapi.yaml)：端点路径、模式、安全方案和响应契约。
- [MCP README](cortrix-mcp/README.md)：MCP 服务器设置和工具参考。
- [Python SDK README](sdk/python/README.md)：Python 客户端设置和资源模型。
- [内置代理 README](cortrix-agent/README.md)：FastAPI 代理服务和聊天端点。
- [Linux NVIDIA CUDA 操作](docs/operations/cuda-execution-provider.md)：独立镜像、提供者策略、部署、验证和回滚。
- [安全策略](SECURITY.md)：安全报告路径。
- [贡献](CONTRIBUTING.md)：开发工作流程和贡献检查清单。
## 当前状态
Cortrix 处于积极的预发布开发阶段。公共文档使用以下状态标签：
- `已验证`：直接由当前代码/规范证据支持，并在最新的验证范围内进行。
- `需要 RD 审查`：存在于代码、规范或文档中，但尚未确认足够以声称公开就绪。
- `已阻塞`：已知损坏、阻塞或无法在当前运行时证明。
- `路线图`：计划或为后续版本保留。
高信号当前状态：
| 区域 | 状态 | 备注 |
|---|---|---|
| OpenAPI 文件 | `已验证` | `api/openapi.yaml` 存在并声明公共 API 表面。 |
| 本地服务器、健康端点、命名空间、文档、查询 | `需要 RD 审查` | 核心表面存在，但公共就绪性标签仍取决于端到端验证。 |
| MCP 服务器 | `需要 RD 审查` | MCP 工具存在并具有测试覆盖，发布就绪性仍在审查中。 |
| Python SDK | `需要 RD 审查` | SDK 资源和测试存在，兼容性仍与实时 API 契约绑定。 |
| 内置代理聊天 | `需要 RD 审查` | 固定流程聊天模式存在；高级自主执行器是路线图项目。 |
| 身份验证登录 | `已阻塞` | 公共规范定义登录，但最新运行时验证发现契约漂移。 |
| 租户/成员/ACL/配额 | `已阻塞` | 运行时行为和文档契约仍在协调中。 |
| MEM02 内存提取 | `已阻塞` | 最新验证观察到 LLM 传输超时路径。 |
| RBAC 和租户隔离拒绝矩阵 | `已阻塞` | 无法在当前禁用身份验证的本地运行时证明。 |
| 基准测试声明 | `需要 RD 审查` | 在接受测量工件之前，将性能和基准测试数字视为未发布。 |
在进行生产、安全、基准测试或集成声明之前，请参阅 [兼容性和已知状态](docs/compatibility.md)。
## 快速入门
使用源代码优先的快速入门：
```bash
git clone https://github.com/cortrix/cortrix.git
cd cortrix
cp config.yaml.example build/config.yaml
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
./dev.sh
```
然后检查后端：
```bash
curl http://localhost:8420/api/v1/health
curl http://localhost:8420/api/v1/system/health/ready
```
有关完整路径、预期响应、LLM 配置说明和故障排除，请参阅 [快速入门](docs/QUICKSTART.md)。
## API 参考
规范的 API 契约为 [api/openapi.yaml](api/openapi.yaml)。
规范包括：
- 本地和云服务器 URL；
- API 密钥和 Bearer 身份验证方案；
- 命名空间、文档、查询、内存、监视、导入、身份验证、管理员、租户、代理、系统、GC 和维护路径；
- 请求/响应模式和错误模式。
OpenAPI 存在并不等同于运行时验证。如果端点在 [兼容性](docs/compatibility.md) 中列为 `需要 RD 审查` 或 `已阻塞`，请使用该状态作为公共声明边界。
## 代理访问
Cortrix 暴露了四种访问路径：
| 路径 | 最适合 | 入口点 |
|---|---|---|
| HTTP API / OpenAPI | 自定义服务和直接代理调用 | [api/openapi.yaml](api/openapi.yaml) |
| MCP 服务器 | IDE 代理和 MCP 兼容客户端 | [cortrix-mcp/README.md](cortrix-mcp/README.md) |
| Python SDK | Python 应用程序和 RAG 管道 | [sdk/python/README.md](sdk/python/README.md) |
| 内置代理 | 通过 Cortrix 存储的本地固定流程聊天 | [cortrix-agent/README.md](cortrix-agent/README.md) |
有关选择指导和当前支持状态，请参阅 [代理访问](docs/agent-access.md)。
## 核心概念
- **命名空间**：文档、块、内存和查询的逻辑集合边界。
- **文档**：可以解析和索引的上传源材料。
- **块**：从文档或内存记录导出的可搜索单元。
- **查询**：在一个或多个命名空间上的检索请求。
- **内存**：从交互或显式 API 调用捕获的结构化长期信息。
- **代理表面**：允许代理通过 HTTP、MCP、SDK 或内置代理服务使用 Cortrix 的编程路径。
## 配置
默认本地配置模板为 `config.yaml.example`。在第一次运行之前将其复制到 `build/config.yaml`：
```bash
cp config.yaml.example build/config.yaml
```
LLM 支持的功能按角色配置：
- `semantic_llm`：意图分类和重新排序。
- `vision_llm`：OCR 图像增强。
- `agent_llm`：内置代理聊天。
- `doc_summary_llm`：摄入侧摘要。
- `enricher_llm`：摄入增强。
在文档中使用占位符值，在本地忽略配置文件中使用真实提供者密钥。不要提交机密。
## 生产和安全说明
Cortrix 处于预发布状态。在本地开发之外使用它之前，请查看：
- [兼容性和已知状态](docs/compatibility.md)，了解已阻塞和需要审查的区域。
- [安全策略](SECURITY.md)，用于报告。
- `config.yaml.example`，用于身份验证和 API 密钥配置。
- `deploy/`，用于部署模板。
在标记以下区域为 `已验证` 之前，请勿假设身份验证、租户隔离、RBAC、配额强制执行、内存提取或基准测试性能的生产就绪性。
## 路线图
路线图项目不是当前功能。
- 高级自主代理执行器，例如工具使用和计划执行模式。
- 当前记录表面以外其他集成适配器。
- 身份验证、租户隔离、RBAC、配额、日志记录和部署操作的生产就绪强化。
- 方法论和测量结果被接受后，公共基准测试工件。
## 社区和贡献
- [GitHub 问题](https://github.com/cortrix/cortrix/issues)：错误和功能请求。
- [GitHub 讨论](https://github.com/cortrix/cortrix/discussions)：问题讨论。
- [安全策略](SECURITY.md)：安全报告。
- [贡献](CONTRIBUTING.md)：本地开发和拉取请求。
## 许可证
Cortrix 在 [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0) 下获得许可。
