# zenbox

**Repository Path**: geek0070/zenbox

## Basic Information

- **Project Name**: zenbox
- **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-10-04
- **Last Updated**: 2026-10-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 禅盒 ZenBox · 用户手册

> 一句话：**禅盒**是一款纯本机、离线的 Windows 专注锁定工具——进入「禅定」后屏蔽分心软件与干扰，帮你把一段时间完整交给手头这件事。

---

## 一、三大核心能力

| 能力 | 说明 | 入口 |
| --- | --- | --- |
| **立即禅定** | 点一下即刻开始，按已保存时长锁定，期间分心软件被挡、全屏遮罩提示 | 主界面「立即禅定」 |
| **定时禅定** | 预设每天/每周的时段，到点自动开始禅定，无需手动 | 主界面「定时禅定」 |
| **桌面提醒** | 到点弹出软件内提醒或系统通知，用于番茄钟、整点提醒、久坐提醒等 | 主界面「提醒」 |

三个能力彼此独立，可单独使用，也可组合（例如：定时到点开始禅定 + 禅定中途弹出休息提醒）。

---

## 二、快速上手（三步）

1. **双击 `ZenBox.exe`**，等待主界面出现（首次冷启动稍慢，见第四节）。
2. 在设置页配置好**禅定时长**与**要屏蔽的分心软件**，勾选「开机自启」。
3. 需要专注时点「**立即禅定**」；想让它自动化就加一条「**定时禅定**」。

> 小贴士：日常可以把禅盒收进系统托盘（`--tray`），需要时再唤回，不占桌面。

---

## 三、运行环境

- **操作系统**：Windows 10 / 11 x64。
- **界面宿主**：WebView2 Runtime（Edge Chromium 内核）。
  - Windows 11 通常**自带**，无需额外安装；
  - 若缺失，程序会**自动回退**到 tkinter 经典界面（等价 `--classic`），功能完整、界面朴素。
- **无需**管理员权限、无需联网、无需任何账号。

---

## 四、首次启动

1. 双击 `ZenBox.exe` 即可，**无需安装**。
2. **冷启动会先解包**：单文件（onefile）程序启动时会把自身解包到系统临时目录，**首次约几秒**属正常现象，之后会快很多。请耐心等待窗口出现。
3. **可能被杀软误报**：单文件打包程序有时会被安全软件误判。
   - 若被拦截，请把 `ZenBox.exe` 加入杀毒软件 / Windows Defender 的**白名单（排除项）**；
   - 本程序不联网、不修改系统文件，仅在本机读写自己的 `data\` 目录，可放心放行。
4. 第一次启动会在 exe 同级自动创建 `data\` 目录并写入默认配置。

---

## 五、开机自启（推荐开启）

在设置页勾选「开机自启」即可，之后每次开机禅盒都会在后台待命。要点如下：

1. **在设置页勾选即可**：无需改脚本、无需任何手工配置，勾选后立即生效（写注册表即生效，不用重启）。
2. **免管理员**：自启项写在当前用户的注册表分支，**不弹 UAC、不需要管理员权限**。
3. **写入 HKCU Run**：位置为 `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run`，值名 `zenbox-autostart`，内容为「本程序路径 + `--tray`」。
4. **exe 移动 / 改名后自动自愈**：自启登记的是绝对路径，若你移动或重命名了 `ZenBox.exe`，**下次启动时程序会自动把登记项改回当前路径**，不会失效。
5. **关闭自启不影响已在跑的调度器**：取消勾选只删除注册表登记项，**不会**打断当前正在运行的定时调度；下次开机才不再自启。
6. **开机后驻留系统托盘**：自启以 `--tray` 方式启动——界面直接收进**系统托盘**，不弹窗打扰，同时后台调度器照常工作，到点即自动禅定。

---

## 六、数据位置

所有数据都在 **`data\`** 目录，位于 **`ZenBox.exe` 同级**：

```
ZenBox.exe
data\
├── config.json        # 设置（时长、屏蔽软件、自启开关、提醒弹窗停留时长与落点等）
├── schedules.json     # 定时禅定计划
├── reminders.json     # 提醒规则
├── session.json       # 当前/未结束的禅定会话
├── stats.json         # 专注统计
├── state.json         # 运行期状态
└── logs\              # 运行日志
```

- **纯本机、离线**：不联网、不上传，数据只在你自己的电脑上。
- **便携**：整个 `ZenBox.exe` + `data\` 可随意拷贝到别的目录或 U 盘，设置与统计随之迁移。
- **不写注册表以外的地方**：除上述 `data\` 目录与自启所需的那一个注册表值外，不在系统其它位置留下任何东西。

---

## 七、命令行入口

| 参数 | 作用 |
| --- | --- |
| `--classic` | 打开 tkinter 经典设置界面（WebView2 缺失时的兜底） |
| `--stats` | 打开统计窗口 |
| `--start` | 按已保存配置**直接开始**禅定 |
| `--tray` | 打开主界面并**直接收起到系统托盘**（开机自启用） |
| `--daemon` | 后台驻留调度器（无窗口） |
| `--selftest` | 数据层自检，打印路径与配置 |

用法示例：

```bat
ZenBox.exe --tray
ZenBox.exe --daemon
ZenBox.exe --selftest
```

---

## 八、从源码运行与打包（开发者）

### 8.1 初始化环境（推荐首次先跑）

双击 **`setup-env.bat`**：它会**幂等地**准备好项目虚拟环境与全部依赖（重复运行安全）。它会：

1. **解析或创建虚拟环境** `.venv\`（查找顺序与 `build.bat` / `start.bat` 完全一致：`ZENBOX_PYTHON` → `.venv\` → `venv\` → 新建；新建时优先 `py -3.14`，要求 ≥ 3.10）；
2. 升级 `pip`；
3. 按 `requirements.txt` 安装运行依赖（`pywebview` / `pystray` / `Pillow`）；
4. 安装构建与测试工具链：**PyInstaller**（打包用）+ **pytest**（跑单测用）；
5. 做一次导入自检并打印后续步骤提示。

> 可选开关：
> - `set ZENBOX_WITH_DEV=1` → 额外安装 `ruff` + `vulture`（静态检查 / 死代码扫描）；
> - `set ZENBOX_PIP_ARGS=--no-index --find-links=<目录>` → 从内网本地 wheel 目录离线安装。

### 8.2 直接运行（开发）

双击 **`start.bat`** 即可：它会自动挑选 Python 解释器并补齐运行依赖（`pywebview` / `pystray` / `Pillow`），然后执行 `python main.py`。

> 解释器查找顺序：环境变量 `ZENBOX_PYTHON` → 项目内的 `.venv\`（若已构建过就存在）→ `venv\` → `py` → `python`。
> 数据目录仍在脚本同级的 `data\`；**点窗口右上角 ✕ 只会收起托盘，不会退出**，退出请用托盘菜单。

### 8.3 打包为单文件 exe

双击 **`build.bat`** 即可（纯 ASCII + CRLF 的批处理，避免中文控制台代码页导致的解析错误）。它会：

1. **准备专用构建环境**：首次运行时用 **Python 3.14** 在项目内创建虚拟环境 **`.venv\`**，并安装 `requirements.txt` 与 PyInstaller；之后每次直接复用该 `.venv`。
   - 解释器选择顺序：环境变量 `ZENBOX_PYTHON`（直接使用，跳过 venv）→ `.venv\` → `venv\`（旧名）→ 都没有则新建 `.venv`；
   - 建 venv 时优先用 `py -3.14`，否则退回 `py` / `python`（要求 ≥ 3.10，否则明确报错）。
2. 重新生成图标；
3. 调用 `pyinstaller build.spec --noconfirm --clean --workpath build --distpath dist`；
4. 校验 `dist\ZenBox.exe` 是否产出，失败会明确报错（无解释器 / 建 venv 失败 / 装依赖失败 / 构建失败 / 未产出）。

也可手动执行（激活 `.venv` 后）：

```bat
.venv\Scripts\activate
pyinstaller build.spec --noconfirm --clean
```

产物位于 **`dist\ZenBox.exe`**（单文件、无控制台黑框）。构建后可自检：

```bat
dist\ZenBox.exe --selftest
```

> 说明：`build.spec` 会把只读资源 `web\` 与图标打进包内，`data\` **绝不进包**（它是 exe 同级的可写运行目录）。
> `build.spec` 用 `SPECPATH` 定位工程根，保证从任意工作目录调用都能正确打包。
> `.venv\` 已在 `.gitignore` 中，不会进版本库。

---

## 九、隐私与安全

禅盒是为「自用」设计的工具，隐私边界清晰：

- **全程离线**：没有任何网络请求，不上传数据、不收集使用信息、不校验账号。
- **数据自持**：所有记录都在你本机的 `data\` 目录里，随时可看、可删、可备份。
- **权限最小**：只申请普通用户权限；唯一的系统写入是开机自启所需的**一个 HKCU 注册表值**，取消自启即删除。
- **无后台偷跑**：退出程序后不残留进程；开机自启的进程也可随时从托盘退出。

---

## 十、常见问题

- **窗口迟迟不出现？** onefile 冷启动需先解包，首次约几秒，稍等即可。
- **点了右上角 ✕，程序退了吗？** 没有——**✕ 只把窗口收进系统托盘**，后台调度器照常工作。要真正退出，请右键**托盘图标 → 退出**。
- **托盘图标会消失吗？** 不会——**程序运行期间托盘图标常驻**（开机自启后也一样）；点 exe 或托盘「打开主界面」都能把控制窗口唤回来。
- **禅定时控制窗口会被全屏锁住吗？** 不会——禅定在**独立窗口**里进行，控制窗口全程保持原样（尺寸、标题栏、层级都不变），禅定结束后控制窗口自动唤回并跳到「数据」页提示本次结果。
- **禅定时顶部还能拖动窗口吗？** 不能——禅定窗口进入后**整体去掉标题栏**并铺满整屏（含任务栏区域，无白边），拖动热区已关闭。
- **提醒弹窗停留多久？** 默认 10 秒后自动关闭，可随时点弹窗右上角 **✕** 或按 **Esc** 手动关；到设置页「提醒弹窗 → 弹窗停留时长（毫秒）」可自定义，填 **0** 表示不自动关闭（只能手动关）。
- **提醒弹窗会不会关不掉？** 不会。弹窗有 **5 条关闭路径**，任意一条都能真的把它从屏幕上收走：**✕ 按钮** / **Esc 键** / **停留时长到点** / **系统关闭请求（Alt+F4、任务栏右键关闭）** / 程序内部直调。其中「系统关闭请求」会被拦成「收起」（窗口只隐藏、不销毁，下一次提醒照常弹出）。预览弹窗（设置页「测试弹窗」）还额外有 **2 分钟兜底寿命**，即使手动关都失效也会自动消失。实现上，收起动作是**先在系统层同步隐藏窗口（当场生效）、再异步同步界面框架状态**，顺序绝不反过来——这正是不再出现「点了 ✕ 却怎么都关不掉」的关键。
- **提醒到点会打扰我正在做的事吗？** 不会——提醒弹出的是**独立的小提醒窗口**，只有它会在「弹窗停留时长」内置顶一会儿，到点自动取消置顶并收起（也可点弹窗右上角 **✕** 或按 **Esc** 立刻关）；**主控制窗口全程不动**（不弹出、不置顶、不改尺寸），你收起在托盘里它就一直在托盘里。
- **提醒弹窗能不能换个位置？** 能——到设置页「提醒弹窗 → 弹窗位置」选择**左上角 / 右上角 / 左下角 / 右下角**（默认右上角），或选「**自定义**」自己填 X / Y 坐标。选自定义时会显示两个参考尺寸：**屏幕可用区域**（不含任务栏的可用范围）与**弹窗基准尺寸**（宽固定 380，高随内容在 80~300 之间自适应）；坐标以**可用区域左上角为原点**，越界会自动夹回，保证整窗可见。点「**测试弹窗**」可立即预览一次（不影响已保存的设置），预览的弹窗还能**按住拖动**，松手自动把坐标填回输入框。改完点「保存设置」**立刻生效**，下一次提醒与测试弹窗就按新位置弹。
- **界面很朴素、不像截图？** 说明本机缺少 WebView2 Runtime，程序已回退到 tkinter 经典界面；安装 WebView2 后即可恢复现代界面。
- **开机没自动启动？** 到设置页确认「开机自启」已勾选；若刚移动过 exe，重启程序一次即可自动修复登记路径。
  - 说明：自启路径的自动修复**只在程序从正式安装位置启动时**进行。若你从临时目录、`build\`/`dist\` 构建目录或源码目录运行，程序会**主动跳过修复**，以免把自启项指向会被清理的位置；`--selftest` 自检则完全不改动系统设置。
- **怎么备份设置和统计？** 直接复制整个 `data\` 目录即可；恢复时把它放回 `ZenBox.exe` 同级即可。
- **禅定中误关了窗口？** 未结束的会话记录在 `session.json`，可用 `ZenBox.exe --resume` 接续（守护进程也会自动拉起）。
- **想彻底卸载？** 取消「开机自启」，删除 `ZenBox.exe` 与 `data\` 目录即可，系统不留残留。

---

## 十一、结语

禅盒的定位很简单：**在你需要专注时，把干扰挡在门外**，其余时候安静地待在托盘里。

- 遇到界面异常，先用 `ZenBox.exe --classic` 打开经典界面确认功能是否正常；
- 遇到数据问题，用 `ZenBox.exe --selftest` 打印路径与配置，便于自查。

祝每一次禅定都专注、从容。