# MyFlow

**Repository Path**: amadeus113/my-flow

## Basic Information

- **Project Name**: MyFlow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-19
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MyFlow 文档管理

简易的 Git 仓库文档管理系统：可视化浏览文件、Typora 式所见即所得编辑 Markdown、图片直接预览，一键同步到远程仓库。支持 Gitee / GitCode / GitHub / GitLab 等任意支持 HTTPS + Token 认证的 Git 托管平台。

## 目录
- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [从源码运行](#从源码运行)
- [配置说明](#配置说明)
- [使用流程](#使用流程)
- [快捷键](#快捷键)
- [打包为 exe](#打包为-exe)
- [项目结构](#项目结构)
- [技术栈](#技术栈)
- [常见问题](#常见问题)
- [安全说明](#安全说明)

## 功能特性
- 一键拉取 / 克隆远程仓库
- 文件树可视化浏览，**可拖拽调节**文件栏宽度（自动记忆）
- **可视化新建**：悬停任意文件夹（含仓库根）显示「新建文件 / 新建文件夹」按钮，输入名称即在对应目录创建
- **可视化删除**：悬停任意文件 / 文件夹显示删除按钮，确认后删除（文件夹递归删除，`.git` 与仓库根受保护）
- **可视化重命名**：悬停任意文件 / 文件夹显示重命名按钮，输入新名称即同级改名（`.git` 与仓库根受保护）
- **拖拽上传**：从系统资源管理器直接拖拽本地文件 / 文件夹到左侧任意目录（含仓库根），自动保留文件夹结构；同名文件弹窗询问覆盖或跳过
- **所见即所得** Markdown 编辑（Vditor WYSIWYG 模式，输入语法即时渲染，无需分屏预览）
- **代码文件高亮**：打开 .py/.json/.js 等非 Markdown 文本时切换为代码视图，highlight.js 语法高亮预览 + 一键切换编辑模式，保留原始缩进
- **图片直接预览**：点击 png/jpg/gif/svg/webp 等图片文件在右侧居中显示，不再出乱码
- Markdown 中的相对路径图片自动通过本地代理加载，编辑保存不污染原始路径
- 一键提交并推送到远程仓库（新建 / 删除 / 修改统一通过同步推送同步到远程）
- 白天 / 夜间模式切换（自动记忆）
- 跨平台：不限定代码托管服务商，改配置即可切换 Gitee / GitHub 等

## 快速开始

最快的方式是使用已打包的 exe：

1. 确保本机已安装 `git` 命令行工具。
2. 在项目根目录编辑 `config.json`，填入平台用户名和访问令牌（见 [配置说明](#配置说明)）。
3. 双击 `build_output\dist\MyFlow.exe`（或把 exe 拷到任意位置双击）。
4. 浏览器会自动打开 http://127.0.0.1:3000 ，即可开始使用。

> exe 启动时会从自身所在目录**逐级向上**查找已填入 token 的 `config.json`，找到即用该目录作为工作目录（同时复用其下的 `repos\`）。因此把 exe 放在项目根目录（与 `config.json` 同级）最直接；放在子目录也能自动向上找到根目录配置。若均未配置，则在 exe 同级目录生成默认 `config.json`，编辑填入 token 后重启生效。

## 从源码运行

1. 安装依赖：
   ```
   pip install -r requirements.txt
   ```
2. 确保本机已安装 `git` 命令行工具。
3. 配置凭证：编辑 `config.json`（见 [配置说明](#配置说明)）。
4. 启动：
   ```
   python app.py
   ```
5. 浏览器访问 http://127.0.0.1:3000

## 配置说明

编辑 `config.json`，填入平台用户名和访问令牌：

| 字段 | 说明 |
| --- | --- |
| `repo_url` | 仓库地址（如 `https://gitee.com/user/repo.git`） |
| `username` | 平台用户名 |
| `token` | 访问令牌 |
| `email` | 提交时使用的邮箱（可随意） |
| `local_path` | 本地克隆目录（相对项目根 / exe 同级目录） |

各平台令牌获取与权限要求：
- **Gitee**：[私人访问令牌](https://gitee.com/profile/personal_access_tokens)，勾选仓库读写权限
- **GitHub**：[Personal Access Token](https://github.com/settings/tokens)（须用令牌，密码认证已停用），勾选 `repo` 权限
- **GitCode / GitLab 等**：在对应设置页生成带仓库写权限的令牌

> 切换仓库时，修改 `repo_url` 与 `local_path` 后重启即可。

## 使用流程
1. 点击「⬇ 同步拉取」克隆 / 拉取仓库
2. 在左侧文件树操作文件：
   - 点击文件：Markdown 进入所见即所得编辑，图片直接预览
   - 悬停文件夹：点「📄＋」新建文件、「📁＋」新建文件夹
   - 悬停文件 / 文件夹：点「✎」重命名（同级改名）、点「🗑」删除
   - 拖拽本地文件 / 文件夹到任意目录：自动上传，保留目录结构；同名弹窗询问覆盖或跳过
3. 编辑后点击「💾 保存」（或 Ctrl+S）写入本地
4. 点击「⬆ 同步推送」将新建 / 删除 / 修改统一提交并推送到远程仓库
5. 右上角 ☀️/🌙 切换主题；拖动文件栏与编辑栏之间的分隔条调节宽度

> 新建、删除、保存均为本地操作，需点击「⬆ 同步推送」才会同步到远程仓库。

## 快捷键
| 快捷键 | 功能 |
| --- | --- |
| `Ctrl+S` / `Cmd+S` | 保存当前文件 |
| `Ctrl+Z` / `Cmd+Z` | 代码文件撤销编辑（自定义历史栈，支持回退误删） |
| `Ctrl+Y` / `Cmd+Y` / `Ctrl+Shift+Z` | 代码文件重做 |
| `Tab` | 代码文件插入 4 空格缩进（可撤销） |

## 打包为 exe

运行 `build.bat`（或手动执行下方命令）即可生成单文件可执行程序：
```
pip install pyinstaller flask
pyinstaller --noconfirm --onefile --name MyFlow --distpath build_output\dist --workpath build_output\build --specpath build_output --add-data "%CD%\static;static" --exclude-module pygame app.py
```
> 需在项目根目录执行（cmd）；PowerShell 中将 `%CD%` 换成 `$PWD`。`--add-data` 必须用绝对路径，否则 spec 位于 `build_output` 时会找不到 `static`。

生成物：`build_output\dist\MyFlow.exe`。所有打包中间文件（`build/`、`*.spec`）均集中在 `build_output/` 下，不污染项目根目录。

## 项目结构
```
MyFlow/
├── app.py              # Flask 后端（git 同步、文件树、文件读写/新建/删除/上传、资源代理）
├── config.json         # 凭证配置（自行填入）
├── config.example.json # 配置模板
├── requirements.txt    # 依赖
├── build.bat           # 一键打包为 exe
├── repos/              # 克隆的仓库（自动生成）
├── build_output/       # 打包产物（dist\MyFlow.exe + 中间文件，自动生成）
└── static/
    ├── index.html      # 页面
    ├── style.css       # 样式（白天/夜间主题）
    └── app.js          # 前端逻辑
```

## 技术栈
- **后端**：Python 3 + Flask，通过 `subprocess` 调用本机 `git` 完成克隆 / 拉取 / 提交 / 推送
- **前端**：原生 HTML / CSS / JavaScript，[Vditor](https://github.com/Vanessa219/vditor) 提供 WYSIWYG Markdown 编辑，[highlight.js](https://highlightjs.org/) 提供代码文件语法高亮（CDN 加载）
- **打包**：PyInstaller 打包为单文件 exe

## 常见问题

**Q：双击 exe 后提示输入 token？**
A：exe 未找到已配置的 `config.json`。请确保 exe 上层某级目录存在已填入真实 token 的 `config.json`（最稳妥是放在项目根目录与 exe 同级，或把 exe 放到项目根目录）。

**Q：启动时提示端口 3000 被占用？**
A：关闭占用 3000 端口的程序，或修改 `app.py` 末尾 `app.run(..., port=3000)` 的端口号（同时改前端访问地址）。

**Q：同步拉取 / 推送失败，提示要求输入密码或 Unauthorized？**
A：检查 `config.json` 中的 `token` 是否正确、是否已过期、是否具备仓库读写权限。GitHub 必须使用 Personal Access Token 而非登录密码。

**Q：图片预览或 Markdown 内图片不显示？**
A：先点击「同步拉取」确保仓库已克隆到本地；图片通过后端 `/api/raw/` 代理访问，需本地服务运行中。网络图片需联网。

**Q：编辑器或工具栏加载不出来？**
A：前端 Vditor 通过 CDN 加载，首次使用需联网。离线环境需自行替换为本地 Vditor 资源。

**Q：如何切换管理的仓库？**
A：修改 `config.json` 的 `repo_url` 与 `local_path`，重启服务 / exe 即可。

## 安全说明
- 凭证以明文形式写入仓库 `.git/config` 的 remote URL，仅供本地使用，请勿在公共环境运行。
- `config.json` 含敏感令牌，请妥善保管，切勿提交到公开仓库。
- 仓库默认克隆到 `repos/your-repo`（可在 `config.json` 的 `local_path` 修改）。
- 图片预览与 Markdown 内相对路径图片通过后端 `/api/raw/` 代理访问，仅在本地服务运行时可用。