BK Project Manager

项目各归其位，开始更轻松。
_{Your projects. One workspace.}

简体中文 · English

项目管理页 · 编辑器页 · 下载安装 · 源码运行 · 功能一览 · 配色主题 · 操作与快捷键 · 更多界面 · 扫描规则 · 开发与构建

面向 macOS 与 Windows 11 的本地项目管理器。把分散的项目归集到一个工作空间，按分类浏览、收藏和最近打开查找；需要深入查看时，再进入项目的编辑器页面，浏览代码并使用终端。

🗂️ 项目管理页 · 所有项目，一目了然

自动扫描工作空间，用分类、收藏和最近打开找到手头的项目。卡片与列表两种视图，支持在软件内打开项目，也可以直接交给 VS Code、Cursor 或其他编辑器。

☀️ 亮色项目管理页 · 🌙 暗色项目管理页

💻 编辑器页 · 打开项目，继续工作

在 v0.2.1 中，点击灰色 启动项目，即可在独立窗口打开三栏工作台：左侧浏览目录，中间只读查看代码，右侧直接运行终端命令。毛玻璃导航、Material 文件图标和细分界线，让项目内容保持清晰。代码区与终端共用主题底色，左侧目录保留同色系层次，切换主题时三栏保持协调。

☀️ 亮色编辑器页 · 🌙 暗色编辑器页
_{两组截图均使用示例项目与中性衬底，并随 GitHub 的亮暗外观自动切换。}

v0.2.1 新增独立项目窗口、启动 / 运行状态、GitHub 仓库入口和按区域比例调节的毛玻璃。 可下载安装包或从源码启动。当前源码还支持 Markdown 阅读与编辑，尚未包含在 v0.2.1 安装包中。

✨ 功能一览

🧩 工作台使用说明

在软件内打开项目即可进入三栏工作台，v0.2.1 安装包与源码均支持。

• 左侧： 当前源码顶栏显示项目名、GitHub 与默认打开软件的图标，移除返回按钮；初始宽度从 320px 起，按完整项目名和按钮占用自动加宽。空间不足时名称换行，手动调整后的宽度会在当前窗口中保留。顶栏与侧栏共用毛玻璃材质，目录在其下方独立滚动。文件和目录使用离线打包的 Material Icon Theme 图标，支持展开/收起及亮暗主题。
• 中间： 代码区上下延伸至窗口边缘，一次显示一个文件，支持行号、VS Code Light+ / Dark+ 代码高亮和常见图片；不显示文件标签。普通代码只读，当前源码额外支持 Markdown 阅读与编辑。
• 右侧： 上下延伸至窗口边缘的交互终端，启动在项目目录，支持滚动、Ctrl+C 中断、清空和重启；清空和重启操作位于系统菜单「终端」。macOS 使用登录 Shell，Windows 11 使用 PowerShell。
• 简洁布局： 代码与终端上下直达窗口边缘，左右仅保留 1px 分界线，拖动范围保持宽于可见线条，方便调整面板。切换到项目列表窗口时保留工作台与终端；关闭项目窗口时结束该项目终端。
• 滚动与外观： 所有区域隐藏滚动条，保留滚轮、触控板和横向滚动；设置通过系统菜单访问，当前源码还提供主页侧栏设置按钮，支持亮色、暗色和跟随系统。

预览支持 2 MiB 以内的 UTF-8、UTF-16 文本与常见图片；超过 20 万字符的文本使用纯文本预览。二进制或不支持的文件会显示说明。文件浏览限定在当前项目中，文件树不展开符号链接。

Markdown 阅读与编辑（当前源码）

打开 .md / .markdown 文件默认进入只读排版预览，支持标题、表格、任务列表、引用和代码块高亮。点击右下角悬浮「编辑」按钮进入源码编辑，支持行号、语法高亮和撤销；点击「保存」或按 ⌘S / Ctrl+S 保存并返回阅读模式。切换文件、关闭窗口或退出软件时，未保存的修改会提示保存、放弃或取消。

保存保留 UTF-8 / UTF-16 编码、BOM 和原换行格式；检测到其他程序修改时会保留草稿并阻止覆盖。支持项目内相对路径图片、以项目为根的 / 路径图片、HTTP / HTTPS 网络图片，以及 README 常用的 <img> / <picture> 写法和亮暗图片切换。图片保留宽高设置并自适应内容区，加载失败时显示提示。项目内文档链接可直接浏览，外部链接交给系统浏览器；内嵌 HTML 经过白名单过滤，不执行脚本或事件处理代码。

🎛️ 操作与快捷键

设置、刷新目录和终端操作位于原生菜单栏，工作台内不再放置额外工具栏。

点击顶部软件图标，按设置中的默认方式打开当前项目；悬停可查看软件名称。终端执行 exit 后，可通过菜单重新启动。关闭项目窗口或重启终端会结束当前终端进程；切换到项目列表窗口会保留终端。

毛玻璃效果（v0.2.1）

设置中可选择 关闭 / 中等 / 完整：关闭会禁用全部毛玻璃；中等只保留顶栏和悬浮工具栏；完整会为各面板开启原生材质，并保留弹窗背景模糊。默认完整，切换立即保存并同步到所有窗口，项目终端保持运行。完整模式下，主页左侧栏按滑块的 100%、右侧项目区按 60% 应用透明度；工作台左右侧栏（目录与终端）按 100%、中间代码区按 60% 应用。滑块为 80% 时，对应区域为 80% / 48% / 80%。代码高亮与终端 ANSI 颜色保持不变，中等和关闭模式恢复实色内容区。macOS 使用系统侧栏材质，Windows 11 22H2 及以上使用 Mica；不支持原生材质时，侧栏保留实色。

毛玻璃透明度滑块支持 0–100%，数值越高越通透，默认 60%。拖动实时预览，松开或键盘调节结束后保存，并同步到其他窗口。关闭毛玻璃会禁用滑块，但保留透明度设置。侧栏滚动内容与玻璃底层分开合成，减少滚动时的残影。

独立项目窗口（v0.2.1）

每个项目拥有独立的文件预览和终端，可同时打开多个项目。同一项目只创建一个窗口；单击运行中的卡片或状态按钮可切回该窗口，最小化时会恢复显示。收藏、GitHub、文件夹、VS Code、终端及移除按钮各自执行操作。关闭管理列表不会结束已打开项目；当前源码可通过原生菜单打开设置来显示或重新打开管理列表，项目继续运行。

GitHub 仓库入口（v0.2.1）

项目卡片、列表及工作台顶部会为 GitHub 项目显示 GitHub 图标，点击即可通过系统默认浏览器打开仓库首页。HTTPS、SSH 地址均可识别，也支持 Git worktree 和子模块的 Git 元数据。识别只读取本地 Git 配置，不依赖 Git 命令或 Token，地址中的凭证不会传入界面或浏览器。

只有一个仓库时直接打开；多个仓库时通过原生菜单选择，origin 优先，并合并重复的仓库地址。普通本地项目及非 GitHub 远程仓库不显示入口。调整远程地址后可重新扫描；点击时也会重新核对本地配置。

📦 下载安装

最新版：v0.2.1。 包含独立项目工作台与运行状态、GitHub 仓库快捷入口、三档毛玻璃及透明度滑块；同时保留分类管理、真实终端和七款内置配色。可从 最新 Release 下载：

完整变化与升级说明见 v0.2.1 更新记录。

macOS 打开 DMG 后将应用拖入 Applications；Windows 运行 EXE 安装，或解压 ZIP 后启动应用。首次启动时选择工作空间即可。

v0.2.1 未配置开发者代码签名和 macOS 公证，系统可能显示信任提示。Release 附带 SHA256SUMS.txt，可用于核对下载文件。

🚀 从源码启动

需要 Node.js 22.12+ 和 npm，建议使用 Node.js 24 LTS。

git clone https://github.com/binbinku/BKProjectManager.git
cd BKProjectManager
npm ci
npm run dev

1. 首次启动，选择工作空间，例如 ~/Workspace 或 D:\Workspace。
2. 应用读取目录结构，自动生成分类和项目列表。
3. 点击灰色 启动项目，在独立窗口打开工作台：左侧展开目录，中间查看文件，右侧输入终端命令。卡片变为绿色 运行中，单击已启动卡片即可切回对应窗口；关闭窗口后恢复 启动项目。
4. 通过系统菜单打开 设置…，选择亮色、暗色或跟随系统，再选一款配色主题和默认编辑器；顶部软件图标用于外部打开项目。

新增或移动项目后，点击 重新扫描。更换工作空间可在系统菜单的 设置… 中完成（macOS：应用菜单，⌘,；Windows：文件菜单，Ctrl+,）。

当前源码的主页侧栏顶端是窗口控制区，下方一行排列应用图标、名称与设置按钮。macOS 使用原生红黄绿按钮，Windows 使用沉浸式无边框标题栏与自定义窗口按钮；工作空间管理在设置中完成。工作台保留项目名称与外部打开入口，不额外放置设置按钮。

🎨 内置配色主题

通过系统菜单打开 设置… → 配色主题，点击预览卡片即可切换并保存到本机。也可使用 ⌘,（macOS）或 Ctrl+,（Windows）打开设置。配色与亮暗模式独立，七款配色均适配亮色、暗色和跟随系统：

GitHub 配色参考 Primer，MacBook Neo 配色以 Citrus 青柠黄色为灵感，采用适合长时间使用的柔和色值。

主题只改变配色，不改变尺寸、间距、面板比例或悬浮按钮位置。代码区、行号区与终端使用同一主题底色，左侧目录保留同色系层次；代码高亮继续使用 VS Code Light+ / Dark+，程序的 ANSI 与真彩色输出保持正常。

新增分类与项目

• 点击左侧「项目分类」旁的 ＋，输入名称并选择颜色、图标。应用创建 工作空间/分类名称/Projects/。
• 选中分类后，通过右下角悬浮区的 … → 修改分类外观 调整颜色和图标，侧栏与项目卡片同步显示。
• 点击 新建项目，选择分类并输入名称，只创建一个空文件夹。已有 Projects 收纳目录时创建在其中，否则直接创建在分类下；创建后自动刷新列表。
• 已识别为工程根目录的分类不可用于新建子项目；重复名称、无效路径与系统保留名称会明确提示，不覆盖已有内容。

分类外观保存在本机设置中，不会向已有项目写入配置文件。

全部项目、我的收藏、最近打开与分类页统一直接展示项目，不显示顶栏、统计栏、搜索和额外标题行。右下角半透明毛玻璃悬浮区叠在内容上，不为工具条单独预留右侧空间，提供 显示方式、排序、重新扫描、新建项目，卡片与列表视图均可使用；分类页额外提供 … 菜单，保留分类外观和移除操作。最近打开默认按打开时间倒序，也可以在排序菜单中切换为名称或目录修改时间。

移除、恢复与手动删除

点击项目卡片上的垃圾桶图标，或选中分类后通过右下角 … → 移除分类，会打开操作弹窗：

• 从列表移除：仅在当前工作空间中隐藏；移除分类会连同其中的项目一起隐藏，重新扫描和重启仍然有效，磁盘文件保持原样。
• 在 Finder / 资源管理器中显示，手动删除：立即从列表隐藏，再定位并选中文件夹，由你在系统中自行删除。应用不会执行删除；即使暂时没有删除文件，重新扫描和重启后也会保持隐藏，可在设置中恢复。
• 恢复：通过系统菜单打开 设置… → 已移除的内容，逐项或全部恢复。恢复分类时，之前单独移除的项目仍会隐藏，可再单独恢复。收藏与最近打开记录保留。

恢复只清除隐藏记录；已经被手动删除或移动的文件夹不会重新创建。

验证范围：v0.2.1 打包应用在 macOS Apple Silicon 及 Rosetta 2 下的 Intel 版本完成运行验证；Windows x64 安装包由 macOS 交叉构建，尚待 Windows 11 实机验证。安装依赖时需要联网下载 npm 包及 Electron 运行时，图标随应用打包，运行时不需要联网加载。

🖼️ 更多界面

上方已完整展示项目管理页与编辑器页。下面补充列表视图、设置、移除弹窗和首次启动页面。

列表视图 · 更紧凑地浏览项目

分类页面 · 专注项目，右下角悬浮操作

首次启动 · 从一个工作空间开始

🗂️ 熟悉的目录，清晰的分类

无需重新组织磁盘文件。下面这样的目录，可以直接作为工作空间：

Workspace/
├── WebDev/                   → 分类：WebDev
│   └── Projects/             → 展示时收纳这一层
│       ├── AtlasWeb/         → 项目
│       └── DesignSystem/     → 项目
├── GameDev/                  → 分类：GameDev
│   ├── Engine/               → 有 Projects 时，不扫描这个同级目录
│   └── Projects/
│       └── OrbitGame/        → 项目
└── TestDev/                  → 分类：TestDev
    └── DevTools/             → 没有 Projects 时，直接识别子目录

扫描顺序：识别一级目录自身是否为工程 → 查找分类下的 Projects → 扫描容器的直接子目录。Projects 自身已是工程时，也会作为一个完整项目收纳。

例如 AndroidDev/Projects 中含有 settings.gradle.kts，会将整个目录识别为 Android 项目，避免把 app、build、gradle 分别列为项目。

🛠️ 开发与构建

Electron · React · TypeScript · Vite

桌面交互测试和截图生成需要可用的桌面会话。它们使用临时工作空间和独立配置，不覆盖你的使用偏好；文档截图不会读取你的项目目录。

VS Code F5 调试

各配置的区别、使用场景、任务菜单和后续维护规则见调试与构建配置说明。

在 VS Code 中打开项目根目录，首次执行 npm install，然后按 F5 启动 开发：启动应用（F5）。启动前会自动准备终端原生模块、文件图标与 Vite 服务，主进程可直接在 electron/*.cjs 中设置断点。

「运行和调试」还提供以下配置，无需安装额外调试扩展：

• 开发：完整调试（主进程 + 界面）：同时调试 Electron 和 React / TypeScript 界面。
• 开发：选择窗口（含工作台）：在开发调试已启动后选择目标窗口；打开独立项目后，可选择地址含 #project 的工作台。
• 运行：构建版：先执行构建，再使用本地构建文件启动，方便检查接近安装版的行为。
• 构建：前端 / 打包：当前平台（安装包） / 清理：全部构建产物：也可直接从 F5 下拉菜单运行构建、打包或清理命令。

构建、打包和清理的 F5 会话会随命令进程退出自动结束；终端保留执行日志，方便检查结果。

配置同时适配 macOS 和 Windows。F5 调试设置独立保存在 .vscode/.user-data/，不会改动安装版设置；该目录不提交到 Git。Vite 使用 5173 端口，界面调试使用本机 9222 端口。停止调试后保留 Vite 后台任务供下次复用；要彻底结束开发服务，可在 VS Code「终端 → 终止任务」中选择「开发：Vite」。启动 F5 前请先关闭同一项目已运行的 npm run dev，避免端口占用。

本地打包

按 ⇧⌘B（macOS）或 Ctrl+Shift+B（Windows）可运行默认的「打包：当前平台（安装包）」。在「终端 → 运行任务」中还可选择应用目录打包、macOS 双架构、Windows x64，以及「清理并打包」。

npm run pack       # 当前平台的应用目录
npm run dist       # 当前系统与架构的安装包
npm run dist:mac   # macOS：DMG + ZIP
npm run dist:win   # Windows：NSIS 安装包 + ZIP
npm run clean      # 清理 dist/ 和 release/

清理仅删除 dist/ 与 release/，保留源码、build/ 应用图标、依赖、文档截图和 VS Code 调试设置。请先结束正在运行的构建或打包任务，再执行清理。

产物位于 release/。所有打包均在本地完成，不使用 GitHub Actions。建议在目标系统上构建；应用、Dock 与安装器使用项目自己的标志；图标由 docs/assets/logo.svg 生成，运行 npm run icons:generate 可重新生成 PNG、macOS ICNS 和 Windows ICO（支持在两种系统上执行）。分发包尚未配置代码签名与 macOS 公证。暂未接入自动更新。

文件树图标

npm run dev 和 npm run build 会从固定版本的官方 npm 包自动生成 Material Icon Theme 的 SVG 资源与匹配表，无需安装 VS Code 扩展。生成资源不提交到 Git；正式构建会将图标及许可一同打包。来源和许可见第三方声明。

代码结构

完整目录树、模块职责、生成文件及功能定位指南见项目目录说明。

electron/     # 原生菜单、受限 IPC、扫描、文件访问与 PTY 终端
src/          # 项目列表、文件树、代码预览与主题
scripts/      # 开发启动、图标生成、桌面测试与截图
tests/        # 扫描、持久化、文件访问与会话测试
docs/assets/  # 文档 SVG 与演示截图
licenses/     # 随应用分发的第三方许可

设置保存在 Electron 的 userData/settings.json。可使用 BKPM_USER_DATA 指定独立配置目录；渲染进程关闭 Node 集成，启用 context isolation 与 sandbox，系统操作通过项目 ID 调用受限 IPC。

🤝 一起完善

欢迎提交 Issue 或 Pull Request。

• 反馈问题：请附上操作系统、复现步骤，以及脱敏后的目录结构。
• 提交改进：说明改动目的，运行 npm test、npm run build 和 npm run format:check；涉及界面时补充截图。
• 改进文档：请同步更新中文版与英文版，保持说明一致。

📄 开源许可证

采用 MIT License 开源。你可以使用、修改和分发本项目，请保留版权与许可声明。

文件树图标来自 Material Icon Theme（MIT），详见第三方声明。

_{Copyright © 2026 binbinku}