Chaos Cypher

Chaos Cypher 知识引擎

将文档转化为知识图谱，让你可以检查、搜索、对话并随身携带——所有操作都在自己的设备上运行。

Chaos Cypher 是一个本地优先的 GraphRAG 平台——让你能够看见、信任并拥有自己的知识。将来源（文档、音频、视频、图像、粘贴的文本、网页——支持 30 多种格式，可自动检测）交给它，它便会提取实体和关系，构建成真正可见、可探索的知识图谱，而不是黑盒式的向量数据块。你可以搜索、对话、完善图谱，并将结果导出为便携的 Lexicon 知识包（.ccx），以便备份、分享或加载到其他实例中。

为什么选择 Chaos Cypher

• 本地优先的 GraphRAG — 来源 → 提取 → 图谱 → 搜索与对话；嵌入在自己的系统上生成。你可以使用自己的 LLM，也可以通过 Ollama 完全离线运行。
• 可检查的知识图谱 — 每个实体和关系都清晰可见，并可追溯至来源。你可以修正提取结果，而不是只能盲目信任。
• 便携的知识包 — 将图谱导入和导出为独立完整的知识包。你的知识由你掌控，可以迁移、管理版本并长期保存。
• 内置 MCP 服务 — 将 Claude Desktop、Cursor 或任何 MCP 客户端直接连接到你的图谱：提供 44 个工具，用于搜索、遍历和构建图谱。
• 可自托管，掌控一切 — 由你决定数据存放位置以及哪些模型可以访问数据。一体化容器可在你掌控的硬件上运行完整技术栈。

功能亮点

核心智能

• 知识图谱画布 — 支持类型区分、筛选和缩放，可从语料库概览深入查看单个实体及其来源
• GraphRAG 搜索 — 将图谱遍历与向量搜索融合（个性化 PageRank + 倒数排名融合），并支持关键词、语义和混合模式
• 带引用的 AI 对话 — 答案以你的内容为依据，并可追溯至生成答案的来源

数据基础

• 质量分析 — 按 0–100 分评估图谱丰富度，并提供明细以标出薄弱来源
• 30 多种来源格式 — PDF、DOCX、Markdown、HTML、EPUB、音频（MP3/WAV/FLAC）、视频（MP4/MKV/MOV）、图像、ZIP 压缩包等
• 自由组合 LLM — Ollama、OpenAI、Anthropic 或 Gemini，可针对不同操作分别配置

自动化与集成

• 自动化 — 可视化工作流构建器，支持触发器和条件逻辑
• MCP 服务 — 提供 44 个工具，适用于 Claude Desktop、Cursor、ChatGPT 和其他 MCP 客户端
• 插件系统 — 可直接使用的 Python 文档加载器、提取领域和工作流工具

哪些数据会离开你的设备？

默认情况下，除了你配置的大模型调用外，没有任何数据会离开你的设备。 嵌入向量在本地计算；你的文档、图谱和导出内容都保存在你拥有的 Docker 卷中。 如果你让 Chaos Cypher 使用托管的大模型提供商（OpenAI、Anthropic、Gemini）， 用于提取和聊天的文本会发送给该提供商——选择 Ollama 这样的本地模型，即可将所有数据保留在设备上。

阅读自托管威胁模型，了解 Chaos Cypher 具体防御哪些威胁、出于设计考量接受哪些风险，以及如何加固局域网或面向互联网的部署。

---

📸 实际效果一览

快速了解整个流程——从添加文档，到提问，再到追溯答案在源文档中对应的高亮句子：

▶️ 在 chaoscypher.com 观看完整演示（配有无音频的旁白字幕）。

仪表板——一览知识库概况：实体和关系数量、质量与密度评分，以及实时图谱预览。

知识图谱——每个来源都会生成可探索的彩色图谱。 平移、缩放、搜索和筛选，即可准确查看提取的内容。

实体——检查任意已提取实体：按重要性排序的有类型和方向的关系，以及统计数据和可追溯到源文档的来源信息。

来源——每份文档都有透明的处理流程视图：加载 → 清理 → 分块 → 提取 → 建立索引，并显示每个来源的实体分布。

聊天——用自然语言提问，获取 GraphRAG 答案，并通过可点击的实体引用跳转至图谱。

---

🚀 快速开始

**前置条件：**Docker（含 Compose）。终端用户只需这些条件——嵌入向量在本地通过 CPU 计算。你还需要一个大模型提供商；Ollama 可将所有数据保留在设备上。

运行已发布的容器（推荐）

推荐的安装方式是使用发布到 GitHub Container Registry 的一体化镜像：

docker run -d --name chaoscypher \
  -p 80:80 \
  -p 443:443 \
  -v chaoscypher-data:/data \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/chaoscypherinc/chaoscypher:latest

# Then open http://localhost  (443 is published so HTTPS works if you enable TLS)

更喜欢使用 Compose？将以下内容保存为 docker-compose.yml，然后运行 docker compose up -d：

name: chaoscypher
services:
  chaoscypher:
    image: ghcr.io/chaoscypherinc/chaoscypher:latest
    container_name: chaoscypher
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - chaoscypher-data:/data
    extra_hosts:
      # Lets the container reach an Ollama running on the host (Linux engines
      # don't resolve host.docker.internal without this)
      - "host.docker.internal:host-gateway"
    restart: unless-stopped
volumes:
  chaoscypher-data:

每次发布 vX.Y.Z 版本时，都会通过 .github/workflows/publish-ghcr.yml 构建并推送镜像。

从 PyPI 安装 CLI

更喜欢以终端为主？可以通过 pipx（或普通 pip）安装独立 CLI：

pipx install chaoscypher-cli
chaoscypher setup                 # wizard: pick an LLM provider
chaoscypher source add paper.pdf

所有四个 Python 包（chaoscypher-core、-cortex、-neuron、 -cli）都会在每次发布时发布到 PyPI——chaoscypher-core 可作为可嵌入库，提供相同的提取和搜索引擎。详见 开发者快速入门。

从源代码构建（替代方案／开发）

克隆代码并在本地构建一体化镜像——无需使用已发布的镜像：

git clone https://github.com/chaoscypherinc/chaoscypher.git
cd chaoscypher
make docker-up      # builds + starts the all-in-one container
# Open http://localhost

约 5 分钟即可试用

快速入门 详细介绍了这些内容——导入和搜索可在约 5 分钟内使用； 配置好 LLM 提供商后，即可使用提取和聊天功能（对于 Ollama， 需要先下载一次模型）。

1. 启动应用：使用上述任一方式启动，然后打开 http://localhost。
2. 创建单用户登录账号：在首次运行设置页面进行创建。
3. 选择 LLM 提供商：在 Settings 中选择——指定本地 Ollama 模型即可完全离线使用，或添加 OpenAI / Anthropic / Gemini 的 API 密钥。
4. 添加来源：上传文档或粘贴文本。Chaos Cypher 会在后台提取 实体和关系（可在 Queue Monitor 中查看进度）。
5. 探索图谱：打开知识图谱视图，查看提取的内容、搜索其中的信息，并与来源内容聊天。
6. 导出知识包：对结果满意后，即可导出，以便备份或在其他地方加载。

开发环境设置（支持热重载）

适用于需要逐个服务进行热重载的贡献者（需要 Python 3.14+、 Node.js 24+ 和 uv 0.11+——uv 可替代 pip，并读取已提交的 uv.lock）：

make install      # First-time setup (packages + hooks + Docker test image)
export QUEUE_PASSWORD="$(openssl rand -base64 32)"  # required by the dev stack
make docker-dev   # Start multi-container dev environment
# Frontend: http://localhost:3000
# Cortex API: http://localhost:8080

---

📦 Monorepo 结构

chaoscypher/
├── packages/
│   ├── core/      # 🧠 Core (Brain) - Business logic & domain models
│   ├── cortex/    # 🎛️ Cortex (Processing Center) - Full backend API
│   ├── neuron/    # ⚡ Neuron (Worker Cells) - Background task processing
│   ├── interface/ # 💻 Interface (Interaction Layer) - Web UI
│   ├── cli/       # 🔧 CLI - Command-line tools
│   ├── docker/    # 🐳 Docker - Orchestration
│   └── docs/      # 📚 Docs - Docusaurus documentation site
├── e2e/           # Public end-to-end test suite
├── scripts/       # Public build/test helper scripts
└── tools/         # Public lint/license tooling

---

🛠️ 常用命令

Docker

make docker-up       # Start all-in-one container (http://localhost)
make docker-rebuild  # Rebuild and restart all-in-one
make docker-dev      # Start multi-container dev environment (hot-reload)
make docker-prod     # Start multi-container production (export QUEUE_PASSWORD first)
make docker-down     # Stop all Docker services

查看日志

# All-in-one
docker logs -f chaoscypher

# Multi-container (the compose file requires QUEUE_PASSWORD for every subcommand)
docker logs -f chaoscypher-cortex

测试

make docker-test     # Run tests in Docker (isolated)
make lint            # Python + frontend lint (make ci runs the full linter suite)
make ci              # Full CI pipeline

单个软件包

cc-cortex start              # Backend API
cc-neuron                    # Unified worker
cd packages/interface && npm run dev  # Frontend UI
chaoscypher --help           # CLI

---

📖 文档

• 已发布的文档站点 - 完整的用户和开发者文档
• 贡献者指南 - 贡献工作流、PR 检查清单和评审要求
• AI 贡献者指南 - 面向 AI 编码助手的公开指南
• 核心架构 - 深入了解六边形架构
• 文档源文件 - Docusaurus 文档站点源文件
• 架构决策 - 公开的 ADR
• 自托管威胁模型 - 哪些数据保留在本地，以及如何加强安全防护

文档站点（Docusaurus）

cd packages/docs && npm run build    # Build static site
cd packages/docs && npm start        # Dev server (http://localhost:3000)

---

🏗️ 架构亮点

Chaos Cypher 采用仿脑隐喻组织结构，每个软件包 都映射到一种专门的角色：

┌─────────────────────────────────────────────────────────────┐
│                      Interface (UI)                          │
│                  React + TypeScript + Vite                   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                 ┌────────▼────────┐
                 │  Cortex (API)   │
                 │  FastAPI + VSA  │
                 └────────┬────────┘
                          │
                 ┌────────▼────────┐
                 │   Core (Brain)  │
                 │    Hexagonal    │
                 └────────┬────────┘
                          │
           ┌──────────────┼──────────────┐
  ┌────────▼────────┐    │    ┌────────▼────────┐
  │ Neuron LLM      │    │    │ Neuron Ops      │
  │ (1 concurrent)  │    │    │ (8 concurrent)  │
  └─────────────────┘    │    └─────────────────┘
                         │
                ┌────────▼────────┐
                │ Storage Adapters│
                │ SQLite / Files  │
                └─────────────────┘

• 🧠 Core (packages/core/) — 与框架无关的业务逻辑（六边形架构）
• 🎛️ Cortex (packages/cortex/) — 采用垂直切片架构的 FastAPI 后端
• ⚡ Neuron (packages/neuron/) — 用于 LLM 和操作处理的后台工作进程
• 💻 Interface (packages/interface/) — React + TypeScript 网页 UI
• 🔧 CLI (packages/cli/) — 独立的命令行界面
• 🐳 Docker (packages/docker/) — 编排配置（docker-compose 文件）

通俗地说： UI 与一个 API 通信，API 将所有实际工作委托给一个与框架无关的 核心，耗时的任务（提取、导出）则由后台工作进程处理，让应用保持响应。

垂直切片架构（Cortex 后端）

功能采用自包含的垂直切片实现，包含从 API → Service → Repository → Database 的完整功能。

packages/cortex/src/chaoscypher_cortex/features/{feature}/
├── __init__.py        # Barrel exports
├── models.py          # Pydantic DTOs (Request/Response)
├── repository.py      # Data access (SQLModel entities) — only where the slice owns tables; most delegate to Core
├── service.py         # Business logic
└── api.py             # REST endpoints + factory DI

六边形架构（Core 库）

packages/core/ 库采用六边形架构，以实现最大的灵活性和可复用性。

• 端口： 协议定义（契约）
• 适配器： 存储实现（SQLite、文件、LLM、Web）
• 服务： 业务逻辑（与框架无关）
• 仓储： 使用存储适配器的领域仓储

队列系统

一个统一的 Neuron 工作进程会处理两个队列：

• LLM 队列（默认并发数为 1，每个已启用的 Ollama 实例各一个）- 聊天、嵌入、实体提取、工具 LLM 调用
• 操作队列（并发数为 8）- 来源处理、导出、工作流

监控地址：http://localhost/queues（全合一；开发环境地址：http://localhost:3000/queues）

---

🔄 开发工作流

# Make changes in any package
cd packages/cortex
# Edit code...

# Changes are immediately available (editable install)
# If using Docker, hot-reload will restart services

# Run tests
uv run pytest packages/*/tests --import-mode=importlib   # or: make test

# Commit changes (Conventional Commits — see CONTRIBUTING.md)
git add .
git commit -m "feat(cortex): add new feature"
git push

---

🤝 贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 修改代码并添加测试
4. 确保所有测试通过
5. 按照 Conventional Commits 规范提交更改（git commit -m 'feat(scope): add amazing feature'）
6. 推送到该分支（git push origin feature/amazing-feature）
7. 发起 Pull Request

---

💬 社区与支持

• 问题、想法和成果展示 → GitHub Discussions
• Bug 和功能请求 → 问题跟踪器
• 最新动态 → 博客 · 更新日志 · 路线图

如果 Chaos Cypher 对你有帮助，在仓库上点一个 ⭐，确实能帮助其他可自托管用户找到它。

---

📄 许可证

Chaos Cypher 仅依据 GNU Affero General Public License v3.0 only (AGPL-3.0-only) 授权——请参阅根目录中的 LICENSE 文件。另提供独立的专有企业版；外部贡献需遵循项目的 CLA。

---

🔗 链接

• 已发布的文档网站
• 博客
• 文档源文件
• GitHub Discussions
• 问题跟踪器
• 贡献者指南
• AI 贡献者指南