基于 Python 与 GitHub,打造个人专属本地化思维导图工具全流程方案(上)

在这里插入图片描述


各位博友,自从踏入修真界,就整天想怎样把代码改造成绝世技能。这不又有新思路,准备用 Python 和 GitHub 这两把 “趁手仙器”,从零开始打造一个专属于自己的本地化思维导图工具。
这工具啥特色?轻量到能揣兜里跑(内存占用低),颜值随你心意改(界面可自定义),还能离线玩得转(数据全存本地)。不管你是想理清楚小说剧情线、课堂笔记,还是规划个小项目,它都能支棱起来。咱不整那些花里胡哨的框架套路,就靠最基础的 HTML/CSS/JS 和 Python,一步步带你打通 “开发任督二脉”:从拆解开源项目优点,到写代码时的 “挖坑填坑”,再到最后打包成能双击运行的 EXE 文件,每一步都给你掰扯得明明白白。
放心,就算你是刚摸到键盘的 “练气期” 萌新,跟着咱的节奏走,也能亲手造出趁手的 “数据法宝”。走,咱们这就开整!


文章目录


第一部分:开发思路——融合开源优势,打造个人专属工具

1.1 核心目标:用最小成本实现「高效本地思维导图」

结合 Blink-Mind 的开源架构(节点管理、连线算法)和 Elixir 的界面美学(简洁线条、柔和配色),去除网络功能,强化 本地化操作易用性,让初学者也能快速上手。

1.2 整合Blink-Mind的核心优势(保留3大核心功能)

  1. 成熟的节点管理系统

    • 直接复用Blink的 节点属性模型(事件、时间、人物、伏笔等),通过Python类封装,支持动态扩展属性(如新增“场景标签”字段)。
    • 继承其 逻辑校验机制(时间格式检查、人物重复提示),但改为本地内存校验,无需网络请求。
  2. 智能连线算法

    • 沿用Blink的 人物关联连线逻辑(相同人物、时间顺序自动连线),简化算法实现,去除复杂的布局引擎,仅保留树形布局。
    • 新增 伏笔虚线连线(Elixir风格的细虚线),通过CSS样式轻松实现,无需额外绘图库。
  3. 跨平台文件存储

    • 使用Blink的 JSON/MD文件格式 作为默认存储,新增 本地自动备份 功能(每次保存生成时间戳文件,如node_20240717_1530.json)。

1.3 借鉴Elixir的界面美学(3大设计改造)

  1. 极简色彩体系

    • 主色调采用Elixir的 柔和蓝色(#2196F3)浅灰(#F5F5F5),节点边框透明度从0.6渐变到0.8,选中时高亮为纯色,避免视觉干扰。
    • 暗黑模式:一键切换,背景改为深灰(#333),文字色为浅灰(#E0E0E0),保护视力。
  2. 轻量化布局

    • 左侧功能区固定240px宽度,按钮图标化(如“新建节点”用📄图标+文字),右侧画布区占满剩余空间,支持鼠标滚轮缩放(100%-200%)。
    • 节点样式:圆角矩形(8px),取消复杂阴影,仅保留鼠标悬停时的轻微投影(2px),提升绘制性能。
  3. 交互反馈优化

    • 按钮点击时添加 Elixir式的涟漪动画(通过CSS transform 实现),拖拽节点时显示半透明辅助线,提示层级关系。

1.4 个性化功能设计

  1. 一键式操作

    • 新建节点:点击左侧按钮 Ctrl+N,弹出简化版输入框(仅必填字段:事件、时间),选填项可后续编辑。
    • 保存文件:自动存储到本地默认路径(如C:\Users\你的用户名\story_tool\data.json),无需手动选择路径。
  2. 可视化引导

    • 首次启动时显示 3步操作指南(新建节点→拖拽连线→保存),通过半透明浮层提示,可随时按 F1 重新查看。
    • 错误提示:用中文弹窗明确告知问题(如“时间格式错误,请用YYYY-MM-DD”),而非技术术语。
  3. 可扩展的自定义空间

    • 允许手动编辑节点JSON文件(用Notepad++打开),新增字段会自动识别显示。
    • 提供 主题CSS文件theme.css),用户可修改颜色、字体,保存后重启生效。

1.5 轻量化实现策略

  1. 技术栈极简

    • 前端:纯HTML/CSS/JavaScript(不用框架),借助浏览器原生API实现拖拽、存储(localStorage)。
    • 后端:Python Flask(仅本地API,处理文件读写),单文件启动(app.py),无需复杂部署。
    • 存储:默认用JSON文件,可选SQLite(通过Python内置库sqlite3,无需额外安装)。
  2. 模块独立化

    • 每个功能模块(节点、连线、存储)一个独立Python/JS文件,代码不超过500行,初学者可逐行理解。
    • 去除Blink的插件系统和Elixir的网络模块,仅保留核心逻辑,代码量减少70%。
  3. AI辅助开发

    • 用AI生成基础代码框架(如节点类、存储函数),再手动优化细节,重点学习核心逻辑而非重复劳动。

第二部分:功能需求拆解与文件架构设计

2.1 详细功能需求(分3大模块)

1. 核心功能(基于Blink-Mind改造)
功能点具体需求整合Blend优势
节点管理- 支持创建/编辑/删除节点,属性包括:事件名、时间(YYYY-MM-DD)、地点、人物(逗号分隔)
- 选填项:伏笔(起/止)、概要、内容
- 逻辑校验:时间格式错误提示、相同时间+相同人物不同地点警告
复用Blink的节点属性模型和校验逻辑,简化为本地内存校验
连线生成- 自动连线:相同人物且时间顺序正确时生成实线,伏笔关联生成虚线
- 手动调整:鼠标拖拽连线端点修改连接关系
- 样式设置:支持修改连线颜色、粗细(Elixir风格默认细线条)
沿用Blink的人物关联算法,新增Elixir的虚线样式(CSS实现)
数据存储- 本地存储:默认JSON格式,存储在C:\Users\用户名\story_tool\data\目录
- 自动备份:每次保存生成带时间戳的副本(如node_20240717_1600.json
- 支持导入/导出:拖拽MD/JSON文件导入,导出为图片(PNG)
采用Blink的文件格式,新增Windows路径适配和备份策略
2. 界面功能(借鉴Elixir美学)
功能点具体需求Elixir风格体现
左侧功能区- 6个核心按钮:新建节点、保存、撤销、显示选项、主题切换、帮助
- 文件列表:按时间排序显示历史节点文件,双击打开
- 设置面板:抽屉式弹出,包含字体大小(12/14/16px)、网格开关
按钮采用圆角矩形,配色为#2196F3和#FFFFFF,图标简洁(如🌓代表主题切换)
右侧画布区- 可拖拽节点,鼠标滚轮缩放(100%-200%),中键平移
- 节点显示:默认仅显示事件名,鼠标悬停显示时间/人物,可通过下拉菜单选择显示字段
- 时间刻度:可选显示垂直灰色线条(年份),ALT+悬停显示具体日期
节点边框为1px浅灰,选中时边框变深,连线为0.5px虚线,避免视觉杂乱
交互反馈- 快捷键:Ctrl+N新建、Ctrl+S保存、Ctrl+Z撤销
- 动画效果:节点创建/删除淡入淡出,连线生成时平滑过渡
- 错误提示:中文弹窗(如“人物名称不能包含特殊字符”)
动画时长统一为0.3s,符合Elixir的简洁反馈机制
3. 本地化专属功能
功能点具体需求初学者友好设计
离线使用- 完全本地运行,无需联网,数据不涉及云端
- 支持Windows 7+,无需安装额外运行时(仅需Python环境)
主程序为单个EXE文件(打包后),双击直接运行
快速入门- 首次启动引导:3步动画教程(新建→连线→保存)
- 帮助文档:内置help.html,F1键打开,图文解释常用操作
引导浮层半透明,可随时关闭,帮助文档本地化存储,无需联网加载
个性化设置- 自定义主题:修改theme.css文件调整颜色/字体,支持用户级样式覆盖
- 快捷键自定义:在config/shortcuts.json中修改,支持中文注释
配置文件位于用户目录,用记事本即可编辑,错误会提示文件路径

2.2 模块拆解(分3层架构)

1. 前端模块(HTML/CSS/JavaScript)
子模块职责核心文件
界面渲染绘制左侧功能区、右侧画布,实现节点拖拽和缩放src/frontend/index.html
src/frontend/styles.css
交互逻辑处理按钮点击、快捷键响应、节点编辑事件(双击输入、右键菜单)src/frontend/script.js
src/frontend/drag.js
模板引擎动态生成节点/连线的HTML结构,支持属性扩展(如伏笔状态显示)src/frontend/templates/node.hbs
src/frontend/templates/connection.hbs
主题系统切换明暗模式,管理CSS变量(如--primary-color, --grid-opacitysrc/frontend/themes/dark.css
src/frontend/themes/light.css
2. 后端模块(Python实现核心逻辑)
子模块职责核心文件
节点管理创建节点对象,执行逻辑校验(时间格式、人物重复),维护节点列表src/backend/node_manager.py
连线生成根据节点属性生成连线(人物关联/伏笔关联),返回连线数据(起点/终点/样式)src/backend/connection_logic.py
数据存储读写JSON文件,实现自动备份和版本管理,支持文件导入/导出src/backend/storage.py
本地API提供前端调用的本地接口(如保存节点、加载文件),基于Flask实现src/backend/app.py
3. 数据层(本地文件系统)
子模块职责存储格式
节点数据以JSON格式存储节点属性,每个节点一个对象,包含唯一ID和扩展字段data/nodes.json
data/backups/目录
配置数据保存用户设置(主题、快捷键、显示选项),存储在config.jsonconfig/config.json
临时数据缓存当前画布状态(节点位置、连线样式),程序关闭后清除temp/cache.json

2.3 文件架构设计(Windows系统适配)

story_tool/
├─ src/                  # 核心代码(分前后端)
│  ├─ frontend/          # 前端代码(初学者重点关注)
│  │  ├─ html/            # 界面HTML
│  │  │  └─ index.html    # 主界面,包含左侧功能区和右侧画布
│  │  ├─ css/             # CSS样式
│  │  │  ├─ styles.css    # 基础样式(布局、节点样式)
│  │  │  └─ themes/       # 主题文件(dark.css/light.css)
│  │  ├─ js/              # JavaScript逻辑
│  │  │  ├─ script.js     # 主逻辑(按钮响应、画布操作)
│  │  │  ├─ drag.js       # 拖拽功能(节点/连线)
│  │  │  └─ template.js   # 模板渲染(Handlebars库)
│  └─ backend/           # 后端Python代码(初学者可先跳过,直接用API)
│     ├─ node_manager.py # 节点核心逻辑(创建/校验/存储)
│     ├─ storage.py      # 文件读写与备份
│     └─ app.py          # Flask本地API(端口5000,默认无需修改)
├─ data/                 # 数据存储(自动创建,用户目录下)
│  ├─ nodes.json         # 当前节点数据
│  └─ backups/           # 时间戳备份文件(如node_20240717_1600.json)
├─ config/               # 配置文件(可手动编辑)
│  └─ config.json        # 用户设置(主题、快捷键、存储路径)
├─ tools/                # 辅助工具(打包/调试脚本)
│  └─ generate_tree.py   # 生成文件树状图(见第五部分)
├─ .gitignore           # Git忽略文件(排除数据/配置目录)
└─ README.md            # 入门指南(包含启动步骤、快捷键列表)

2.4 文件架构的意义(初学者必懂3点)

  1. 模块化降低学习难度

    • 前端代码集中在frontend/,可先用浏览器直接打开index.html调试,无需启动后端,适合新手先掌握界面交互。
    • 后端逻辑在backend/独立存在,暂时不懂Python也可通过API调用(如用Postman测试保存节点),逐步深入。
  2. 本地化路径自动适配

    • Windows用户数据默认存储在C:\Users\你的用户名\story_tool\data\,避免手动指定路径,减少出错概率。
    • 配置文件config.json可通过记事本修改,错误提示会直接显示文件路径(如“找不到config.json,请检查C:\Users\你\config\”)。
  3. 可扩展性预留空间

    • 新增功能只需在对应模块下新建文件(如新增“导出PDF”功能,在frontend/js/export_pdf.js,后端加pdf_export.py),不影响原有结构。
    • 主题系统独立,用户可复制light.css修改,保存后直接生效,无需重启程序(通过JavaScript动态加载样式)。

第三部分:技术栈与开发环境搭建(Windows系统专属)

3.1 核心技术栈(极简组合)

技术/工具版本作用为什么选它
Python3.9+后端逻辑开发、文件处理,自带sqlite3库(无需额外安装)入门简单,Windows兼容性好,库生态丰富
Flask2.3.2搭建本地API,处理前端文件读写请求(如保存节点、加载历史文件)轻量框架,单文件启动,文档友好
HTML/CSS/JavaScript原生语法前端界面开发,利用浏览器原生API实现拖拽、存储、动画无需学习框架,适合初学者掌握基础Web技术
Git2.30+版本控制,管理代码修改历史,方便回滚和协作开源免费,Windows有官方客户端(Git Bash)
VSCode最新稳定版代码编辑器,支持Python/HTML调试,集成Git和插件生态微软出品,开箱即用,对初学者友好

3.2 Python依赖列表(通过pip安装)

# 必需依赖(核心功能)
flask==2.3.2          # 轻量Web框架,处理本地API
jsondiff==2.0.0       # 生成数据备份时对比差异(可选)
python-dotenv==1.0.0  # 管理环境变量(如存储路径,可选)

# 可选依赖(进阶功能)
Pillow==10.0.1        # 导出图片时处理截图(需额外安装Windows依赖)
pywin32==305          # 操作Windows用户目录(自动获取路径)

3.3 版本控制:用Git管理代码(初学者5步上手)

  1. 安装Git

    • 下载Git for Windows,安装时勾选“Use Git from the Windows Command Prompt”。
    • 验证:打开PowerShell,输入git --version,显示版本号(如git version 2.39.2)。
  2. 初始化项目仓库

    # 在项目根目录(story_tool/)执行
    git init
    git add .  # 添加所有文件到暂存区
    git commit -m "初始化项目"  # 提交第一个版本
    
  3. 常用命令(初学者必备)

    命令作用示例
    git status查看文件修改状态git status
    git log查看历史提交记录git log --oneline(简洁模式)
    git checkout -b dev创建并切换到开发分支git checkout -b dev
    git push origin dev推送代码到远程仓库(需先创建GitHub仓库)git push origin dev

3.4 PowerShell与Conda环境搭建(避免依赖冲突)

1. 创建Conda虚拟环境(推荐)
# 步骤1:安装Miniconda(Windows版)
# 下载地址:https://docs.conda.io/en/latest/miniconda.html
# 安装时勾选“Add Anaconda to my PATH environment variable”

# 步骤2:创建虚拟环境
conda create -n story_tool python=3.9  # 命名为story_tool,Python 3.9版本
conda activate story_tool  # 激活环境(PowerShell提示变为(story_tool))

# 步骤3:安装Python依赖
pip install flask jsondiff python-dotenv
2. 手动搭建(不使用Conda)
# 步骤1:检查Python版本(确保3.9+)
python --version  # 如显示Python 3.9.7,则无需升级

# 步骤2:创建项目目录并进入
mkdir story_tool && cd story_tool

# 步骤3:启动Flask开发服务器(自动 reload)
set FLASK_APP=src/backend/app.py  # Windows环境变量设置
set FLASK_DEBUG=1  # 开启调试模式
flask run  # 访问http://127.0.0.1:5000测试

3.5 VSCode设置及必备插件(提升开发效率)

1. 基础配置
  • 安装插件(在VSCode左侧扩展商店搜索):

    • Python(微软官方):支持代码补全、调试、Linting
    • HTML/CSS/JS Formatter(Prettier):自动格式化代码,保持风格统一
    • Git Lens:可视化Git提交历史,方便查看代码修改记录
    • Live Server:右键点击HTML文件,选择“Open with Live Server”,实时预览界面变化
  • 设置Python解释器

    1. Ctrl+Shift+P 打开命令面板,输入“Python: Select Interpreter”
    2. 选择Conda环境路径(如C:\Users\你的用户名\miniconda3\envs\story_tool\python.exe
2. AI辅助工具推荐
  • GitHub Copilot:VSCode插件,自动生成代码片段(如节点类定义、文件读写函数),适合初学者快速上手。
  • Tabnine:轻量级AI补全工具,支持Python/JS,免费版足够入门使用。

3.6 验证环境搭建成功(3个测试点)

  1. Python依赖是否安装

    pip list | findstr "flask jsondiff"  # Windows PowerShell命令
    # 应显示flask 2.3.2和jsondiff 2.0.0
    
  2. Flask本地API是否运行

    • 启动Flask:flask run,浏览器访问http://127.0.0.1:5000,应显示空白页面(前端未部署,属正常)。
    • 测试API:用Postman发送POST请求到http://127.0.0.1:5000/save,Body填{"test": "success"},应返回“保存成功”。
  3. VSCode调试是否正常

    • 打开src/backend/app.py,按F5启动调试,断点应正常触发,控制台显示请求日志。

第四部分:VSCode设置及开发环境深入配置

4.1 VSCode 必备插件及配置

  1. Python 插件
    • 功能:这是微软官方推出的 Python 扩展,能为 Python 开发提供丰富的功能,像代码补全、语法检查、调试支持等。
    • 配置:在 VSCode 的设置里,找到“Python: Default Interpreter Path”,将其设置为之前创建的 Conda 虚拟环境路径,例如 C:\Users\你的用户名\miniconda3\envs\story_tool\python.exe
  2. HTML/CSS/JS Formatter(Prettier)
    • 功能:能按照统一的风格自动格式化 HTML、CSS 和 JavaScript 代码,使代码的可读性和规范性得到提升。
    • 配置:在 VSCode 的设置中,搜索“Editor: Default Formatter”,选择“esbenp.prettier-vscode”。同时,你可以在项目根目录下创建 .prettierrc 文件,对格式化规则进行自定义,例如:
{
    "singleQuote": true,
    "trailingComma": "es5",
    "printWidth": 80
}
  1. GitLens
    • 功能:它能增强 VSCode 的 Git 功能,让你可以直观地查看代码的提交历史、作者信息等,有助于团队协作和代码审查。
    • 配置:一般情况下,安装后即可使用,不过你可以在设置中根据自己的需求对显示信息和颜色等进行调整。
  2. Live Server
    • 功能:在开发前端页面时,它能提供一个实时预览的服务器,只要你保存文件,页面就会自动刷新。
    • 配置:安装完成后,在 HTML 文件中右键选择“Open with Live Server”,就能在浏览器中实时预览页面。

4.2 Conda 虚拟环境使用

  1. 环境管理命令
    • 创建环境conda create -n story_tool python=3.9,这里创建了一个名为 story_tool 的虚拟环境,Python 版本为 3.9。
    • 激活环境conda activate story_tool,激活后 PowerShell 提示符会变为 (story_tool)
    • 查看环境列表conda env list,可以查看所有的 Conda 虚拟环境。
    • 删除环境conda remove -n story_tool --all,用于删除 story_tool 环境。
  2. 依赖管理
    • 安装依赖:在激活的虚拟环境中,使用 pip install 命令来安装所需的 Python 包,例如 pip install flask jsondiff python-dotenv
    • 导出依赖pip freeze > requirements.txt,把当前环境中的所有依赖导出到 requirements.txt 文件,方便在其他环境中重现。
    • 安装依赖列表pip install -r requirements.txt,从 requirements.txt 文件中安装所有依赖。

4.3 AI 辅助工具选择与使用

  1. GitHub Copilot
    • 特点:它是由 OpenAI 和 GitHub 联合开发的 AI 代码助手,能根据上下文自动生成代码建议,涵盖多种编程语言。
    • 使用方法:安装插件后,在编写代码时,Copilot 会在编辑器中实时给出代码建议,你可以按 Tab 键接受建议。例如,当你输入 def calculate_sum( 时,它可能会自动补全函数的参数和返回值。
  2. Tabnine
    • 特点:轻量级的 AI 代码补全工具,支持多种编程语言,免费版功能也能满足初学者的需求。
    • 使用方法:安装后,在编写代码时,它会根据你的输入提供代码补全建议,你可以使用上下箭头选择建议,按 Enter 键接受。

4.4 用 Python 生成项目文件树状图

下面是一个简单的 Python 脚本,用于生成项目的文件树状图:

import os

def generate_tree(path, prefix=''):
    items = os.listdir(path)
    for index, item in enumerate(items):
        is_last = index == len(items) - 1
        new_prefix = prefix + ('└── ' if is_last else '├── ')
        print(new_prefix + item)
        item_path = os.path.join(path, item)
        if os.path.isdir(item_path):
            next_prefix = prefix + ('   ' if is_last else '│   ')
            generate_tree(item_path, next_prefix)

if __name__ == "__main__":
    project_path = '.'  # 当前目录
    generate_tree(project_path)

将上述代码保存为 generate_tree.py,然后在项目根目录下运行 python generate_tree.py,就能在控制台看到项目的文件树状图。


第五部分:GitHub资源包获取与代码解析

5.1 GitHub资源包获取

  1. 注册与登录
    如果你还没有 GitHub 账号,需要先在 GitHub 官网 注册一个账号。注册完成后,使用账号和密码登录到 GitHub。
  2. 搜索资源
    打开 GitHub 首页,在搜索框中输入与 Blink 和 Elixir 相关的关键词,例如 “Blink Mind”、“Elixir framework” 等。筛选搜索结果,选择符合你需求且星标数较多、活跃度较高的项目。
  3. 克隆项目到本地
    在项目页面中,点击绿色的 “Code” 按钮,复制项目的 HTTPS 或 SSH 链接。然后在本地打开 PowerShell 或 Git Bash,使用 git clone 命令克隆项目到本地。例如:
git clone https://github.com/your-repo/blink-mind.git

这会将项目克隆到当前目录下的 blink-mind 文件夹中。

5.2 Blink + Elixir 的文件解析

  1. 了解项目结构
    进入克隆下来的项目目录,使用前面提到的 generate_tree.py 脚本生成文件树状图,了解项目的整体结构。通常,Blink 和 Elixir 项目可能包含以下几个主要部分:
    • 前端文件:如 HTML、CSS、JavaScript 文件,负责界面的展示和交互。
    • 后端文件:Python 或其他语言的代码文件,处理业务逻辑和数据存储。
    • 配置文件:如 config.json.env 等,用于存储项目的配置信息。
  2. 关键文件解析
    • 前端文件:查看 HTML 文件,了解页面的结构和布局;查看 CSS 文件,了解样式的定义和应用;查看 JavaScript 文件,了解交互逻辑的实现。
    • 后端文件:分析 Python 文件中的函数和类,了解其功能和调用关系。例如,在一个基于 Flask 的后端项目中,可能会有路由定义、数据库操作等代码。
    • 配置文件:理解配置文件中各个参数的含义和作用,例如数据库连接信息、API 密钥等。

5.3 利用 Python 生成文件组成树状图并投喂给 AI 解析

  1. 生成树状图
    运行之前编写的 generate_tree.py 脚本,将生成的树状图保存到一个文本文件中,例如 project_tree.txt
  2. 投喂给 AI 解析
    project_tree.txt 文件的内容复制到 AI 工具(如 GitHub Copilot、ChatGPT 等)中,请求 AI 对项目的文件结构进行分析和解释。例如,你可以问:“请根据这个文件树状图分析项目的主要功能模块和文件之间的关系”。

5.4 具体文件代码的解析及 AI 加详细注释

  1. 选择要解析的文件
    从项目中选择一个关键的文件,例如一个 Python 脚本或一个 JavaScript 文件。
  2. 使用 AI 添加注释
    将文件的代码复制到 AI 工具中,请求 AI 为代码添加详细注释。例如,对于以下 Python 代码:
def add_numbers(a, b):
    return a + b

你可以让 AI 为其添加注释,AI 可能会给出如下结果:

# 定义一个名为 add_numbers 的函数,该函数接受两个参数 a 和 b
def add_numbers(a, b):
    # 返回 a 和 b 的和
    return a + b
  1. 理解代码逻辑
    结合 AI 添加的注释,仔细阅读代码,理解其实现的功能和逻辑。如果有不理解的地方,可以进一步向 AI 提问,请求更详细的解释。

基于 Python 与 GitHub,打造个人专属本地化思维导图工具全流程方案(下)将介绍以下五个部分:

  • 第六部分:具体开发步骤
  • 第七部分:模块封装方法与资源包代码提取详解
  • 第八部分:调试技巧
  • 第九部分:浏览器开发人员工具介绍(以 Chrome 中文界面为例)
  • 第十部分:进程阻塞、版本冲突、内存泄露深度解析
Logo

助力广东及东莞地区开发者,代码托管、在线学习与竞赛、技术交流与分享、资源共享、职业发展,成为松山湖开发者首选的工作与学习平台

更多推荐