heapchat

# Heap Chat **像浏览 Pinterest 一样浏览您的文件。与本地 AI 聊天，它实际上了解文件内容。** Heap Chat 是一个本地优先的知识工作空间：指向您的文件夹，它将它们变成一个可搜索、可聊天的知识库 — 默认情况下由本地 [Ollama](https://ollama.com) 模型提供支持。无需云依赖，无需 API 密钥，无需遥测。所有内容 — 索引、嵌入、视觉、聊天 —都在您的机器上运行，除非您故意选择云模型（管理员可以连接任何 OpenAI 兼容的提供商 — NVIDIA、OpenAI、Groq、本地 vLLM... — 作为额外的可选模型源 — 参见 [配置](#configuration)）。 它既可以作为桌面应用程序（Electron，macOS/Windows），又可以作为自托管的 Web 服务器，您可以在局域网上运行并从手机访问。  --- ## 为什么选择 Heap Chat - **完全本地，完全私有。** 除非您明确启用，否则没有数据离开您的机器（仅到您自己的 Ollama 服务器和 Web/MCP 端点）。 - **不仅仅是搜索 — 代理.** 多步骤、工具使用代理推理您的文件，引用来源，并在您看到它们之前自我验证答案。 - **所有内容，而不仅仅是文档.** 照片、视频、音频、PDF、Word 文档、代码、CSV — 带有面部识别、照片地图和知识图，将所有内容联系起来。 - **随着时间推移变得更智能.** 学习循环赋予它持久的记忆、您喜欢被帮助的个人资料以及从重复任务中自我学习的技能。 - **多用户，真正访问控制.** 管理员/成员角色，带有按文件夹划分的权限，在服务器端强制执行，而不仅仅是在 UI 中隐藏。 - **可扩展。** 连接到任何 MCP 服务器，或将 Heap Chat 自己的知识库暴露为 MCP 服务器给 Claude Desktop/Code。 --- ## Heap Chat 比较 Heap Chat 并不是试图成为一个较小版本的 ChatGPT — 它建立在一个不同的前提上：**AI 与您的文件永久共存，而不是一次访问一个文件上传。** | | ChatGPT / Claude | Open WebUI | Heap Chat | |---|---|---|---| | 完全离线/仅本地运行 | 否 | 是 | **是** | | 反映、衰减并学习您的个人资料的记忆 | 浅层静态事实 | 否 | **是** — 输入式记忆、情景反思、自动构建个人资料 | | 您自己的文件上的知识图 | 否 | 否 | **是** — 人员、地点、标签和文档融合，无需 LLM | | 照片原生（面部识别、地理标签地图、视觉重复检测） | 否 | 否 | **是** | | 与聊天集成的本地图像生成 | 仅托管 API | 否 | **是** — 通过 Draw Things，完全离线 | | 多用户，服务器强制执行，按文件夹访问控制 | 不适用（单用户） | 是 | **是** | | 按计划的后台代理作业 | 否 | 否 | **是** — 摘要到订阅源/备注/通知 | | MCP 客户端 *和* 服务器 | 变化 | 仅客户端 | **两者** | | 可选的云模型作为第二个提供商 | 不适用 | 是（许多） | **是** — 任何 OpenAI 兼容的 API，管理员配置，完整的代理 + 工具调用支持 | Heap Chat 仍在赶上的地方：它尚未具备语音对话、可拆分窗格的可编辑画布或移动优先的布局 — 所有这些都是针对托管应用程序的真正差距，公开跟踪而不是掩盖。 它用一个实际上积累了关于您的文件和您自己的上下文的 AI 进行交易，而不会让任何内容离开您的机器。 --- ## 截图 | | | |---|---| |  |  | | 每个文件都像一个板块一样布局 — 包括照片，自动缩略。 | 任何 OpenAI 兼容的提供商，都可以连接，与 Ollama 一样：URL，密钥，测试，保存。 | *(所有截图都使用为此目的制作的小型虚拟演示数据集 — 见 [`website/demo-fixtures`](website/demo-fixtures) — 从未使用真实数据。)* --- ## 目录 - [Heap Chat 比较](#heap-chat-比较) - [截图](#截图) - [功能](#功能) - [快速入门](#快速入门) - [桌面应用程序](#桌面应用程序) - [配置](#配置) - [帐户和多租户](#帐户和多租户) - [手机 / 局域网访问](#手机--局域网访问) - [安全](#安全) - [工作原理](#工作原理) - [API 参考](#api-参考) - [开发](#开发) --- ## 功能 ### 浏览和组织 - **打开文件夹 _或_ 单个文件** 通过真正的 文件系统选择器。选择文件直接跳转到其预览 + 聊天。 - **砌墙式画廊** — 真实的图像缩略图、视频帧、音频波形和文档卡片。按类型筛选，按最近/名称/类型/大小排序，并 **按名称和内容搜索** （匹配文件文本和图像描述，而不仅仅是文件名）。 - **快速文件夹访问** — 边栏记住您最近浏览的文件夹，以便一键返回，旁边是“打开另一个文件夹”。 - **重复查找器** — 通过感知哈希聚类照片：**确切副本** 预先选中以删除（保留最大文件），**相似** 组（突发、裁剪、编辑）显示供手动审查。 - **多选 + 批量操作** — 选择多个文件并 **添加到知识库**、**标签**、**使其可搜索** 或 **删除**，另外还有三个 AI 批量操作： - **询问 AI** — 聊天范围限定在所选文件内。 - **自动标签** — 为每个文件生成基于内容的标签。 - **智能重命名** — 从每个文件的内容中提出描述性文件名，审查后应用。 - **命令调色板（⌘K / Ctrl-K）** — 通过键盘跳转到任何文件、最近的文件或操作。 ### 聊天和代理 - **聚焦 + 聊天** — 点击任何文件以获取完整预览（图像/视频/音频/PDF）以及一个限定在该文件的 AI 聊天边栏。每个文件可保存多个聊天，存储在服务器端。 - **无处不在的代理聊天.** 多步骤、工具使用代理（原生 Ollama 工具调用）循环直到它可以回答，显示其 **步骤链** 在最终引用答案流出之前。工具包括语义 + 精确搜索、文件列表/读取、CSV 分析、文件比较、图像描述/EXIF、笔记、相关文件发现和文件管理。代理在您的整个知识库、打开的文件夹、单个文件或项目上运行 — 无论您在哪个范围内。 - **深度工作模式** — 在编辑器中切换 **“深度工作 - 代理团队”** 以获取复杂请求的协调多代理团队（计划者 → 研究人员 → 起草者 → 评论者），而不是单个代理循环。 - **接地和信任层.** 接地答案显示 **✓ 接地 · N 个来源** 徽章（可点击的来源）；一般知识答案不显示徽章，永远不会被拒绝。 **自我验证通过** 双重检查特定声明与检索的证据，**值级溯源** 在答案中的每个数字下方加下划线，显示其确切来源。 - **丰富渲染.** 表格/数字工具结果以交互式表格、条形图/折线图/饼图和 KPI 卡片渲染 — 无依赖的 SVG/CSS，在数据实际适合时启用。 - **上下文仪表盘** — 编辑器中的实时甜甜圈仪表盘显示聊天使用了多少模型上下文窗口，单击后展开。 - **聊天人体工程学** — 复制、重新生成、编辑和重新发送、导出任何对话到 Markdown 或 JSON，以及每个聊天的模型选择器。 - **将图像拖入聊天** 进行临时视觉 Q&A，无需先将其添加到文件夹。 ### 知识和记忆 - **知识库** — 将文件（文本/代码、CSV、PDF、Word）上传到个人知识库，自动索引以供检索，并使用 **询问知识库** 与所有内容聊天。 - **询问整个文件夹（RAG）** — 聊天关于文件夹及其子文件夹中的所有内容，带有缓存并增量更新的向量索引，以及可点击的来源引用。 - **长期记忆** — 助手记住您在每次聊天中的持久事实和偏好，自动捕获并严格重复/合并规则，或显式添加（“记住……）。随时管理条目。 - **学习循环** — Heap Chat 越用越好： - **技能** — 可重用的步骤程序，代理在解决可重复任务后保存，通过相似性调用，当类似任务再次出现时。 - **个人资料** — 您是谁以及您喜欢如何被帮助的综合摘要，注入每种对话，并在您的记忆增长时自动重建。 - **反思** — 一个可选的通道，审查完成的聊天并悄悄纠正记忆/技能。 - **调度器** — 背景作业，按节奏（每小时/每 6 小时/每天/每周）运行在您的知识库、文件夹或项目上，将摘要传递到您的订阅源，作为备注或桌面通知。在 **活动** 下管理。 - **可搜索图像（多模态 RAG）** — 照片由视觉模型描述和索引，以便代理可以查找、读取和引用图像实际显示的内容 — 而不仅仅是文件名。 ### 照片和人员 - **照片地图** — 地理标记的照片绘制在交互式地图上（EXIF GPS），带有弹出窗口直接链接到每个照片。 - **人员** — 设备端面部检测和聚类。命名一个集群一次（输入现有名称会合并集群），重新扫描个别照片，并管理 Heap Chat 已经识别的每个人。 - **发现和媒体智能** — EXIF 元数据与地图链接的地理标记快照，以及 **相关文件** 条带：通过内容嵌入相似性查找文档，通过视觉相似性（感知哈希 — 查找突发、裁剪和编辑，而不仅仅是类似的描述）查找图像。 - **灯箱** — 全屏图像查看器，带有单击缩放和键盘导航到文件夹。 ### 知识图 - 一个完全本地、无需 LLM 的实体图，由命名的人员、照片位置、标签和文档实体构建。浏览单个实体及其连接，或切换到一次性 **概览** 整个实体。 ### 项目和自定义代理 - **项目** — 命名的工作空间，具有自定义指令、私有知识库和分组聊天历史记录，用于将客户端、主题或任务与主知识库干净地分开。 - **自定义代理** — 定义您自己的代理，具有完整的系统提示符覆盖、模型和采样覆盖以及每个代理的工具功能切换（文件、网络、内存、连接器）。从编辑器的代理选择器中选择一个，或直接与其聊天。 - **导出和导入** — 将任何代理或聊天作为 JSON 文件下载，并在以后（或在另一台机器上）单击导入。每个聊天卡和代理卡都有导出按钮；两个中心都有导入按钮在标题中。 ### 本地图像生成 - **创建和编辑图像完全离线** 通过本地 [Draw Things](https://drawthings.ai) 服务器 — 不涉及云图像 API。使用聊天中的 `/image-create` 和 `/image-edit` 斜杠命令，或生成的图像或画廊照片上的 **用 AI 编辑** 按钮。 *(实验性 / 测试版。)* ### 集成 - **MCP 客户端.** 将代理指向任何远程 MCP 服务器的 URL（设置 → 连接器） — 它获得两个元工具（`list_connectors`、`use_connector`），因此任意数量的连接器仅添加两个工具到代理的工具箱。会话在重启后持续存在。 - **MCP 服务器.** Heap Chat 还通过 Streamable HTTP 在 `/mcp` 上公开其自己的知识库工具，因此 Claude Desktop、Claude Code 或任何 MCP 客户端可以直接搜索和读取您的知识库。 - **网络搜索（可选，无需密钥）** — DuckDuckGo 支持的搜索工具，无需 API 密钥。返回链接卡和图像网格内联，并带有引用，插入到底层徽章中。 - **粘贴链接，获取阅读** — 在聊天消息中粘贴 URL，代理自动获取并读取页面作为上下文，无需额外步骤（或使用 `/read` 按需执行，而无需模型决定）。 ### 多租户和访问控制 - 管理员/成员帐户，**每个文件夹的权限在服务器端强制执行** — 不仅在 UI 中隐藏。每个用户都有一个完全私有的知识库、聊天历史、长期记忆和 MCP 令牌。 - 通过您的局域网访问手机/PWA，受到与桌面应用程序相同的登录 + 文件夹授予的限制。 --- ## 快速入门 ```bash git clone https://github.com/heaplabshq/heapchat.git cd heapchat cp .env.example .env # 然后编辑 .env — 参见下面的配置 npm install npm start # 或：npm run dev（自动重启更改） ``` 打开 **http://localhost:5174**。在第一次启动时，您将被提示创建管理员帐户。 您需要 [Ollama](https://ollama.com) 在本地运行，至少有一个聊天模型和一个嵌入模型被拉取（例如 `ollama pull llama3.1` 和 `ollama pull nomic-embed-text`）。 ## 桌面应用程序 Heap Chat 也作为原生 Electron 应用程序运行。macOS 预构建版本（Apple Silicon + Intel）位于 [Releases 页面](https://github.com/heaplabshq/heapchat/releases/latest) — 目前为 unsigned，因此第一次启动需要右键单击 → 打开 → 打开以绕过 Gatekeeper。尚无 Windows 版本；请在 Windows 机器上自行构建。 ```bash npm run desktop # 在本地运行桌面外壳 npm run dist:mac # 构建可分发 macOS 应用程序（dist/） npm run dist:win # 构建可分发 Windows 安装程序（dist/） ``` 打包版本通过 GitHub Releases 自动更新。 ## 配置 复制 `.env.example` 到 `.env` 并设置您自己的值： ``` PORT=5174 # Ollama 服务器 OLLAMA_URL=http://localhost:11434 OLLAMA_MODEL=llama3.1:latest OLLAMA_VISION_MODEL=llama3.2-vision:latest OLLAMA_EMBED_MODEL=nomic-embed-text:latest OLLAMA_AGENT_MODEL=llama3.1:latest # 绑定地址：127.0.0.1 = 本机；0.0.0.0 = 您的网络上的手机/设备 HOST=127.0.0.1 ``` **模型可在 UI 中切换** — 编辑器中的模型选择器更改当前对话的模型，设置中有下拉菜单用于默认聊天和代理模型，从您本地安装的模型中填充（`GET /api/models`）。 `.env` 被 git 忽略；永远不会提交。 ### 提供商连接（Ollama + 任何 OpenAI 兼容的 API） 每个模型提供商 — 包括内置的本地 Ollama 连接 — 都以相同的方式管理，完全来自 **设置 → 模型 → 提供商**（仅限管理员编辑；每个已登录的用户看到哪些提供商是有效的）：给它一个 **基本 URL** 和一个 **API 密钥** （如果需要），点击 **测试连接** 以实时探测并拉取其实际的模型列表，选择要启用的模型，然后 **保存连接**。不需要重启服务器。 - **Ollama** 内置且无法删除，但其基本 URL 和可选的 API 密钥（用于安全/代理的 Ollama 兼容端点）与任何其他连接一样可编辑。 - **添加任何 OpenAI 兼容的提供商** — [NVIDIA](https://build.nvidia.com)，OpenAI 本身、Groq、Together、Fireworks、本地 vLLM/LM Studio 服务器，任何说标准 `/v1/chat/completions` + `/v1/models` 线上格式的内容。添加任意多个，每个都有自己的名称、连接和模型允许列表。完整的代理 + 工具调用支持在模型可选择的所有地方，包括深入研究和深度工作多代理团队，而不仅仅是简单的聊天。 密钥存储在服务器端，并在显示时屏蔽 — 从不发送到或从非管理员浏览器会话中读取，并且永远不能在每个请求的基础上由用户覆盖，管理员或非管理员。 如果您想通过 `.env` 种子内置的 Ollama 连接或第一个 NVIDIA 连接（例如首次启动前管理员登录），仍然可以 — 应用程序 UI 具有优先级，一旦在那里保存，`.env` 只是默认值： ``` OLLAMA_URL=http://localhost:11434 NVIDIA_API_KEY=nvapi-... NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1 NVIDIA_MODELS=z-ai/glm-5.2 ``` ## 帐户和多租户 Heap Chat 从第一次启动时就是多用户。创建设置屏幕上的管理员帐户，每个 API 路径都需要登录（HttpOnly cookie，scrypt-hashed 密码）。 - **私有每用户：** 知识库、聊天历史记录、长期记忆、MCP 连接器和 MCP 令牌。 - **磁盘访问基于角色，默认拒绝。** 管理员看到整个机器；成员看到仅限他们的私有知识库，直到管理员授予他们特定的文件夹根目录（设置 → 用户 → 文件夹，包含子文件夹）。授予在每个路径采取的端点上强制执行，并解析符号链接，因此无法逃避授予。 - **管理员面板**（设置 → 账户和用户） — 添加/删除用户、重置密码、编辑文件夹授予和角色。 - **MCP 令牌** `/mcp` 端点需要 `Authorization: Bearer <token>`（从设置 → 账户复制您的令牌）；每个令牌仅限于用户自己的知识库。 ## 手机 / 局域网访问 将 `.env` 设置 `HOST=0.0.0.0`，启动横幅会打印您的网络 URL（例如 `http://192.168.x.x:5174`） — 在您的手机上打开它，登录，然后 **添加到主屏幕** 以安装 Heap Chat 为 PWA。每个请求仍然需要登录，因此 LAN 暴露受帐户和文件夹授予的限制。默认值为 `127.0.0.1`（仅限本机）。 ## 安全 - **默认离线。** 唯一进行外部网络调用的功能是网页搜索、MCP 连接器和粘贴链接自动获取 — 所有这些都是显式的，不需要任何一项。 - **网络出口功能由管理员控制。** 本地图像生成端点的目标地址只能由管理员帐户覆盖；其他用户始终固定在 `localhost`，关闭了任何请求驱动的服务器出口调用的重定向。 - **无遥测。** 每个前端库都是本地提供的；没有任何内容会发送到服务器。 - **密码经过 scrypt 哈希处理**，会话基于 HttpOnly-cookie，文件访问权限在每个请求时在服务器端进行检查，而不是从 UI 假设。 发现安全问题？请私下报告，而不是公开提交问题。 ## 工作原理 一个小型 Express 服务器（`server.js`，由 `src/` 下的专注模块支持）读取文件系统并将聊天代理到 Ollama — 避免浏览器 CORS 并为模型提供实际文件内容。`public/` 中的前端使用 React，通过 esbuild 进行打包。 **完全离线设计：** 每个前端库都在 `public/vendor/` 下本地提供，字体也是自托管的。应用程序除非连接到您自己的 Ollama 服务器（以及您明确启用的内容 — 网页搜索、MCP、图像生成），否则不会进行任何网络请求。`npm install` 只需要在网络上获取服务器依赖项。 ## API 参考 | 端点 | 用途 | |---|---| | `GET /api/config` | UI 的端点/模型/主页 | | `GET /api/browse?path=` | 列出子文件夹（文件夹选择器） | | `GET /api/list?path=` | 列出文件夹的文件 + 元数据 | | `GET /api/file?path=` | 流式传输文件字节（缩略图/预览） | | `POST /api/chat` | 流式聊天 → Ollama（文件 / 文件夹 / 助手 / 通用范围） | | `POST /api/agent` | 多步骤工具调用代理（流式步骤 + 答案） | | `POST /api/kb/upload` | 上传文件到知识库 | | `DELETE /api/kb?path=` | 从知识库中删除文件 | | `POST /api/image/describe` | 视觉模型描述图像以进行搜索 | | `POST /api/image/create` · `/api/image/edit` | 本地图像生成 / 编辑 | | `POST /api/index` · `GET /api/index?path=` | 构建/检查文件夹的向量索引 | | `GET /api/chats` · `/api/chats/:fileId/:sessionId` | 列出 / 加载保存的聊天会话 | | `PUT` · `DELETE /api/chats/:fileId/:sessionId` | 创建/更新 / 删除会话 | | `GET /api/agents` · `POST /api/agents` | 列出 / 创建自定义代理 | | `GET /api/models` | 列出已安装的 Ollama 模型 | | `GET /api/duplicates?path=` | 将文件夹的照片聚类成重复组 | | `POST /api/batch/autotag` · `/api/batch/rename/suggest` | AI 批量操作 | | `POST /mcp` | MCP 服务器（可流式传输的 HTTP）将 KB 工具暴露给任何 MCP 客户端 | ## 开发 ```bash npm run dev # 带有自动重启的服务器 npm run build:ui # 打包前端（esbuild） npm run eval # 运行代理评估套件以对抗固定知识库 ``` `npm run eval` 启动一个临时实例，带有固定知识库，并通过代理运行一组黄金问题（基础事实、精确数字、释义、合并陷阱、通用知识路由），评估答案、基础和引用的来源。在检索、记忆、提示或代理循环的任何更改后运行它。 ## 许可证 Heap Chat 在 [PolyForm Noncommercial License 1.0.0](LICENSE) 下获得许可 — 免费用于任何非商业目的（个人、研究、教育、非营利）。未经作者单独许可，不得用于商业用途，包括销售或作为付费产品或服务的一部分。 --- 为那些想要一个真正了解他们文件的人工智能而构建 — 而无需将文件发送到任何地方。