CardNotes - 一款支持 LaTeX 和标签知识图谱的笔记应用

CardNotes 是一款桌面笔记应用程序，旨在为用户提供一个集成了数学公式支持和可视化知识管理的强大工具。用户可以轻松创建和管理笔记，使用 LaTeX 语法无缝插入复杂的数学公式，并通过一个交互式的标签关系图来探索和理解不同知识点之间的联系。

开发说明

实际上，本项目完全通过AI生成！！！！！这里的一切都来自于以下对话，

prompt：我现在想要从头开始开发一个记笔记的软件，这个软件的基本理念是：支持latex（类似markdown），简洁风格，笔记具有标签整理功能，笔记可以按照标签进行关联分类，目前先考虑Windows平台 -- 我是一个完全的小白，只有基本的python知识，我如果想要完成这个任务，我应该怎么开始一步一步实现这个目标

Copilot(Gemini 2.5 Pro): 我们把整个项目分成几个大的阶段来逐步完成：

-环境搭建和基础窗口创建：首先，我们需要搭建好开发环境，并创建一个最简单的应用程序窗口。 -核心编辑器功能：实现一个可以输入和显示文本的编辑器。 -笔记的保存和加载：让你的笔记可以被保存到本地，并且之后可以重新打开。 -LaTeX和Markdown支持：集成相应的库来解析和显示格式化的文本和数学公式。 -标签系统：设计数据结构来存储笔记和标签，并在界面上实现标签的添加和管理。 -笔记关联和检索：根据标签来筛选和查找笔记。 -界面美化和完善：让软件变得更美观、更易用。

在现在的(2025/7/29)的version 0.1版本中，AI已经实现了大部分的内容，界面美化和完善就等待后续啦~ （另外这个README.md也是AI生成的，功能总览是根据对话总结的，但是有些功能在测试中有bug，所以可能下面说的功能不能全信，不过主要功能还是实现了：支持LaTeX，支持添加tag，支持绘制tag间的联系）

核心功能

• 笔记管理：支持创建、重命名、删除和搜索笔记。
• 实时预览：提供一个分屏视图，左侧为 Markdown 和 LaTeX 编辑区，右侧为实时渲染的预览区。
• LaTeX 支持：通过集成 KaTeX 库，实现了对行内公式（$...$）和块级公式（$$...$$）的完美渲染。
• 标签系统：允许用户为每篇笔记添加多个标签，方便分类和检索。
• 可视化标签图：
  • 将所有标签以节点的形式展示在一个可交互的图谱中。
  • 用户可以拖动标签节点，自定义布局，程序会自动保存位置。
  • 新增的标签会自动以螺旋状布局在现有标签集群周围，形成紧凑、美观的视觉效果。
  • 支持在标签节点之间创建带有关联描述的连线，构建知识网络。
• 跨平台部署：通过 PyInstaller 打包，可以生成无需依赖 Python 环境即可在 Windows 上运行的独立 .exe 文件。

技术栈

• 核心语言：Python 3
• 图形用户界面 (GUI)：PyQt6
• LaTeX 渲染：KaTeX (JavaScript 库)
• Web 视图集成：PyQt6.QtWebEngineWidgets
• 打包工具：PyInstaller

代码结构

项目的代码结构清晰，职责分明：

• main.py:

  • 程序主入口：包含 MainWindow 类，是应用的起点和核心。
  • UI 初始化：负责构建主窗口的全部界面元素，如笔记列表、编辑器、预览窗口和所有按钮。
  • 业务逻辑处理：管理所有用户交互，包括笔记的增删改查、标签管理、文件读写等。
  • 数据管理：负责从 notes.json 和 tag_map_data.json 加载和保存数据。
  • 窗口协调：管理和调用 TagMapWindow，并向其传递更新后的标签数据。
  • 打包适配：包含 resource_path 辅助函数，用于处理在开发环境和打包后（EXE）环境中资源文件的路径问题，确保程序的可移植性。

• tag_map_view.py:

  • 标签图谱视图：定义了 TagMapWindow 和 TagMapScene 类，完全封装了标签图的显示和交互逻辑。
  • TagNode: 代表图谱中的一个可拖动、可交互的标签节点。
  • TagConnection: 代表连接两个标签节点的线。
  • 智能布局算法：
    • _find_next_available_pos: 实现了螺旋式布局算法，用于将新标签节点紧凑地排列在现有节点集群周围。
    • populate_scene: 负责整个场景的布局逻辑，它会优先使用 tag_map_data.json 中保存的节点位置，并对新节点或位置冲突的节点应用智能布局。

• notes.json:

  • 笔记数据文件：以 JSON 格式存储所有的笔记。每篇笔记包含其标题、内容（content）和标签列表（tags）。

• tag_map_data.json:

  • 标签图布局文件：以 JSON 格式存储标签图的布局信息。
  • nodes: 记录每个标签节点的位置坐标（x, y）。
  • connections: 记录节点之间的连接关系。

• katex/ (文件夹):

  • 静态资源：存放 KaTeX 库的所有文件，包括 CSS、JavaScript 和字体文件。这些资源在打包时会被完整地包含进最终的 EXE 文件中。

运行与开发

要在开发环境中运行此程序，请按照以下步骤操作：

1. 克隆仓库：

   git clone <repository-url>
   cd CardNotesAPP

2. 安装依赖： 确保您已安装 Python 3。然后通过 pip 安装所需的库。

   pip install PyQt6 PyQt6-WebEngine PyInstaller

3. 运行程序：

   python main.py

打包为可执行文件

使用 PyInstaller 可以将此应用打包成一个独立的 .exe 文件，方便在其他 Windows 电脑上分发和运行，无需对方安装 Python 或任何库。

1. 确保 PyInstaller 已安装：

   pip install pyinstaller

2. 执行打包命令： 在项目根目录下打开终端，运行以下命令：

   pyinstaller --name CardNotes --windowed --onefile --add-data "katex;katex" main.py

   • --name CardNotes: 指定生成的文件名为 CardNotes.exe。
   • --windowed: 在运行时不显示黑色的命令行控制台窗口。
   • --onefile: 将所有依赖和资源打包成一个单独的 .exe 文件。
   • --add-data "katex;katex": 这是最关键的一步，它告诉 PyInstaller 将 katex 文件夹及其所有内容复制到最终打包文件的根目录中，以确保 LaTeX 渲染正常工作。

3. 找到可执行文件： 命令执行完毕后，您会在项目下找到一个 dist 文件夹，CardNotes.exe 就在其中。

4. 分发： 您可以将 CardNotes.exe 文件连同 notes.json 和 tag_map_data.json（如果希望保留现有数据）一起复制到任何其他 Windows 电脑上直接运行。

致谢

本应用的 LaTeX 渲染功能由优秀的开源库 KaTeX 提供支持。