Hetu

# 河图 > AI 增强的个人知识管理 — 以笔记和聊天为双引擎，本地优先设计。 [简体中文](./README.zh-CN.md) | <a href="https://github.com/hetu-io/hetu">GitHub</a> 河图（Hetu）是一个本地优先的知识工作空间，它将 Markdown 笔记系统与 AI 聊天工作空间融合在一起，并通过知识图谱、智能代理和工具层连接它们。笔记、对话和 AI 操作共同演化成一个活的知识库。 --- ## ✨ 功能 ### 📝 笔记与笔记本 - 所见即所得的 Markdown 编辑（Milkdown），支持编辑、预览和分屏模式。 - **内联 AI**，通过文本选择触发（润色 / 翻译 / 压缩 / 扩展 / 解释 / 自定义）— 替换选择或插入结果到笔记中。 - **AI 助手面板**，用于整个笔记的操作，支持每次调用独立的模型选择。 - 无限嵌套的笔记本，带有树状侧边栏（创建 / 重命名 / 删除 / 上下文菜单），包括一个默认的“未分类”分组。 - 支持颜色选择、重命名、合并和筛选的标签。 - **3 秒自动保存**，并有明确的保存 / 脏 / 已保存指示器。 - **版本历史**，在更新时自动快照，支持预览、差异比较和一键恢复。 - **分享链接**，每个笔记都有永久 / 24 小时 / 3 天的分享链接，带有访问计数器和一键禁用；公共查看器位于 `/share/:code`。 - 每个笔记的 **知识库索引** 状态（块计数、重新索引按钮）和 **一键图谱提取**，报告新的实体 / 关系。 - **回收站**，支持软删除和 30 天清理。 ### 💬 聊天工作空间 - 会话 **分组** 和 **主题**，每个主题都有自己的模型、系统提示、上下文窗口和消息历史。 - **SSE 流式传输**，带有丰富的事件类型 — `delta`、`thinking`、网络搜索结果、知识库命中、记忆命中、工具调用 / 结果、交互式问题和实时待办计划。 - **深度思考**，可切换推理努力程度（低 / 中 / 高），并有可折叠的思考轨迹。 - **工具栏**，在输入框旁边：网络搜索、知识库、记忆、工具调用（带有批准模式：自动 / 询问 / 绕过）、模型选择、智能代理选择、推理努力程度。 - **斜杠菜单**（`/`），用于调用技能或智能代理。 - 消息 **复制 / 编辑 / 删除**，主题 **分叉** 用于分支探索。 - **提炼到笔记** — 将主题转换为 4 种样式的 Markdown 笔记（摘要 / 详细 / 问答 / 自定义提示），带有流式预览和笔记本选择器。 - **文件附件** 在输入框中，以及跨消息的全文 **搜索**。 ### 🤖 智能代理、技能与提示 - **智能代理页面** — 管理系统提示预设（“智能代理”），带有类别、搜索、每个智能代理的 **工具白名单** 和 **每个工具的批准策略**（静默 / 自动 / 询问），以及所有智能代理的 JSON **导入 / 导出**。 - 可用的工具包括：`search_notes`、`read_note`、`search_web`、`search_memory`、`search_graph`、`create_note`、`update_note`、`create_memory`、`ask_question`、`todo`、`run_command`。 - **技能页面** — 两个选项卡： - **数据库技能**：内置（翻译 / 总结 / 解释 / 润色）+ 自定义技能，带有可编辑的提示模板和系统提示；可以直接从页面调用以预览输出。 - **本地技能**：从磁盘上的可配置目录加载 Markdown / JSON 技能文件，带有目录管理界面。 - 技能可以通过聊天窗口的 `/skill-name` 调用，也可以通过提示预设库调用。 ### 🧠 知识库 - 三个选项卡：**概览**、**索引管理** 和 **搜索测试**。 - 索引任意组合的 **笔记、上传的文件和 URL** — 支持 Notes / Files / URLs / All 的类型筛选。 - 带有自动轮询的实时索引状态，项目未索引时；每个项目的块计数和重新索引操作。 - 内置 **语义搜索 playground**，可通过调整 Top-K 和高亮块预览来验证检索。 ### 🕸️ 知识图谱 - 力导向的图谱可视化，支持缩放、平移、搜索和重置布局。 - **实体类型**，带有不同的颜色和图标：概念、人、组织、技术、项目、自定义。 - **关系类型**：属于、相关、依赖、包含、比较、自定义。 - **AI 提取**，从选定的笔记中提取实体和关系，带有合并 / 去重操作。 - 点击实体，查看链接的笔记，并跳回编辑器。 ### 🔌 MCP 服务器 - 从设置 → MCP 服务器管理 **模型上下文协议** 服务器。 - **stdio** 传输完全支持（进程生成 + JSON-RPC 2.0）；SSE 传输可配置。 - **自动工具发现**（`tools/list`）和工具调用（`tools/call`）；发现的工具可以从聊天窗口调用。 ### 🧬 记忆 - 长期 **AI 记忆存储** — 内容、可选类别（偏好 / 身份 / 工作 / 习惯 / 知识 / ...）和 **重要性** 分数（显示为 1-5 星）。 - 创建、编辑、删除、搜索和筛选记忆；通过 **记忆** 切换和 `search_memory` 工具将记忆呈现给聊天窗口。 ### 🗂️ 任务（后台作业） - 两个选项卡：**后台任务** 和 **计划任务**。 - 作业的实时状态：排队 / 运行中 / 已完成 / 失败，支持类型筛选（例如 * 生成嵌入*、* 图谱提取*）。 - 每 5 秒自动刷新，以及“清除已完成”和每个任务的删除。 ### 🔎 全局搜索 - 跨 **笔记 / 聊天 / 标签** 的统一搜索，带有选项卡和 `⌘/Ctrl + K` 焦点快捷键。 - 两种模式：**关键词搜索** 和 **语义（嵌入）搜索**；结果高亮匹配片段，并在原位打开完整笔记。 ### 🤝 分享与导出 - 每个笔记的 **分享链接**，带有过期时间和访问计数器；公共查看器路由以渲染的 Markdown 显示，无需登录。 - 设置 → **数据和备份**：导出所有笔记为 Markdown ZIP，备份 / 恢复 SQLite 数据库文件。 ### ⚙️ 设置 - **应用程序**：显示名称、主题（系统 / 亮色 / 暗色）和图谱选项。 - **AI 模型**：提供商（OpenAI 兼容 / Anthropic）、每个用途的模型（`chat` / `embedding` / `completion`）、每个用途的默认模型、加密的 API 密钥。 - **MCP 服务器** 管理。 - **数据库**：在 SQLite 和 PostgreSQL 之间切换，运行连接测试。 - **回收站** 快捷方式。 ### 🔐 隐私与存储 - 100% 本地执行 — 无需云账户。 - API 密钥通过 ASP.NET DataProtection（Windows 上的 DPAPI）静态加密。 - 向量存储在本地，使用 `sqlite-vec`，或在 PostgreSQL 中，使用 `pgvector`。 --- ## 🧱 技术栈 | 层级 | 技术栈 | | -------- | ------------------------------------------------------------------ | | 后端 | ASP.NET Core 10、EF Core 10、Serilog | | 存储 | SQLite（默认，带 `sqlite-vec`）/ PostgreSQL（带 `pgvector`） | | 前端 | React 19、TypeScript ~6、Vite 8、Tailwind CSS 4 | | 状态 | Zustand（客户端）+ TanStack Query（服务器） | | 编辑器 | Milkdown（所见即所得）+ react-markdown 渲染器 + DOMPurify | | AI | OpenAI 兼容协议、Anthropic 协议、嵌入、SSE 流式传输 | | 协议 | RESTful API、JSON-RPC 2.0（用于 MCP） | ## 📂 项目结构 ``` Hetu/ ├── src/ │ ├── Hetu.Api/ # Web API 主机 │ ├── Hetu.Core/ # 领域实体、服务、接口 │ ├── Hetu.Infrastructure/ # EF Core、AI 提供商、MCP、sqlite-vec │ ├── Hetu.Infrastructure.PostgresMigrations/ # PostgreSQL 迁移 │ └── Hetu.Shared/ # DTO 和共享模型 ├── frontend/ # React + Vite 应用（见下页） ├── shell/ │ └── hetu-desktop/ # Tauri 2 桌面壳（可选） ├── scripts/ # start.sh / start.ps1 / 测试脚本 ├── docs/ # PRD 和设计笔记 ├── design/ # HTML 原型 └── AGENTS.md # 实现约定 ``` 前端页面映射（位于 [`frontend/src/App.tsx`](frontend/src/App.tsx) 中的路由）： | 路由 | 页面 | 目的 | | -------------------------------- | --------------- | ------------------------------------------- | | `/` | 笔记 | 笔记本树 + 笔记列表 + Markdown 编辑器 | | `/tags` | 标签 | 标签 CRUD、合并、重命名 | | `/chat` | 聊天 | 分组 + 主题 + 流式消息区域 | | `/agents` | 智能代理 | 系统提示预设 + 工具策略 | | `/skills` | 技能 | 数据库技能 + 本地技能 | | `/knowledge-base` | 知识库 | 索引和语义搜索 playground | | `/graph` | 知识图谱 | 力导向的实体 / 关系图 | | `/tasks` | 任务 | 后台和计划任务监视器 | | `/memories` | 记忆 | 长期 AI 记忆存储 | | `/search` | 搜索 | 跨内容的关键词 + 语义搜索 | | `/trash` | 回收站 | 软删除的笔记 | | `/settings` | 设置 | 应用程序 / AI / MCP / 数据库 / 回收站 | | `/share/:code` | 分享的笔记 | 公共只读查看器 | | `/models`、`/work`、`/workflows` | 占位符 | 为即将到来的功能预留 | ## 🚀 快速开始 ### 要求 - .NET SDK **10.0+** - Node.js **20+** - （可选）PostgreSQL **16+**，带有 `pgvector` 扩展 ### 一键启动 ```bash # Linux / macOS / Git Bash ./scripts/start.sh # PowerShell .\scripts\start.ps1 ``` ### 手动运行 ```bash # 后端（默认为 http://localhost:5000） dotnet run --project src/Hetu.Api --urls "http://localhost:5000" # 前端（默认为 http://localhost:5174） cd frontend npm install npm run dev ``` 然后打开 <http://localhost:5174>。API 在 <http://localhost:5000/api> 提供服务。 ### 桌面壳（Tauri 2，可选） 在 `shell/hetu-desktop/` 下提供了一个原生桌面包装器。它将后端作为一个附属进程启动，并在 WebView 中加载前端。 ```bash # 开发 pwsh ./scripts/desktop-dev.ps1 # 构建（SelfContained ≈120 MB，或 FrameworkDependent 精简版） pwsh ./scripts/publish-backend.ps1 cd shell/hetu-desktop && npm run tauri:build ``` 后端通过 `HETU_DATA_DIR` 接收 OS 用户数据目录，其中存储 SQLite 数据库和日志。 ## ⚙️ 配置 AI 提供商 1. 打开应用程序并进入 **设置 → AI 模型**。 2. 添加一个 **提供商**：选择一个协议（OpenAI / Anthropic），输入基本 URL 和 API 密钥。 3. 在该提供商下添加 **模型**： - `用途`：`chat`、`embedding` 或 `completion`。 - 将一个模型标记为每个用途的默认模型。 4. 保存 — 聊天流式传输回复，笔记可以嵌入以进行语义搜索，图谱提取可以运行。 > API 密钥使用 ASP.NET DataProtection 静态加密。 ## 🗄️ 切换到 PostgreSQL SQLite 是默认的，不需要设置。要使用 PostgreSQL + `pgvector`： ```bash export DatabaseProvider=Postgresql export ConnectionStrings__DefaultConnection="Host=localhost;Database=hetu;Username=postgres;Password=postgres" # 应用迁移（仅在模式更改时需要） dotnet ef database update \ --project src/Hetu.Infrastructure.PostgresMigrations \ --startup-project src/Hetu.Api ``` 向量列维度由 `Embedding:Dimensions`（默认为 `1536`）控制，必须与您的嵌入模型匹配。 ## 🧪 构建与测试 ```bash # 后端构建（整个解决方案） dotnet build Hetu.slnx # 前端类型检查 + 生产构建 cd frontend npm run build # API 烟雾测试（后端必须运行） ./scripts/test-api.sh ``` ## ⚠️ 已知限制 - Anthropic 目前不提供公共嵌入 API — 为 `embedding` 选择 Anthropic 会引发明确的错误。 - MCP **SSE** 传输可配置，但仅 **stdio** 已连接用于工具执行。 - `/models`、`/work`、`/workflows` 页面是即将推出的功能的占位符。 - 笔记的全文搜索使用 `LIKE`；计划升级到 FTS5 / `tsvector`。 ## 🤝 贡献 欢迎提出问题和 PR。请在提交更改前阅读 [`AGENTS.md`](./AGENTS.md)，了解分层、命名、提交格式和测试约定。 约定提交格式： ``` <type>(<scope>): <subject> # type: feat | fix | docs | style | refactor | test | chore # scope: api | ui | db | ai | config ``` ## 📜 许可证 根据 [Apache License 2.0](./LICENSE) 授权。 ``` Copyright 2026 Hetu Contributors Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 ```