🍅 dsh-pomodoro

为 DeepSeek Harness Web UI 提供专注与休息循环的番茄钟插件。

English · 简体中文

npm 版本 npm 月下载量 Node.js 版本 DSH rc 版本 Awesome DSH Plugin MIT 许可证

演示：专注阶段倒计时走动，阶段结束提醒出现并自动进入休息，随后自动开始下一轮专注，最后面板收起为迷你模式

界面预览 · 功能亮点 · 快速安装 · 基本使用 · 设置与提醒 · 故障排查

> **兼容性提示：** DeepSeek Harness 目前迭代迅速，本插件仅跟进 rc 版本：开发与验证均以 rc 基线为准，不承诺支持 alpha 等中间预发布。每个发布版本适配的 DSH 版本都在 [Releases](https://github.com/causebefore/dsh-pomodoro/releases) 说明中注明；升级 DSH 后，请先对照 Release 说明确认插件兼容性。 ## 界面预览 支持明暗主题、迷你模式和 DSH 插件配置。
浅色主题 深色主题
浅色主题下的番茄钟浮动面板 深色主题下的番茄钟浮动面板
### 迷你模式

只显示阶段、倒计时和主要控制的迷你番茄钟

### 设置页面

DSH 插件详情页中的番茄钟设置，浅色主题

深色主题设置页面

深色主题下的番茄钟插件设置

## 功能亮点 - **融入 DSH：** 从侧栏打开番茄钟，在插件配置页面统一管理设置。 - **完整计时控制：** 支持开始、暂停、重置、跳过、环形进度、阶段提示和已完成专注计数。 - **跨会话恢复：** 刷新页面，或关闭标签页、重启浏览器后重新打开 DSH，都会按原截止时间恢复；离开期间已到期时只结算当前阶段一次。 - **低干扰迷你模式：** 收起后只保留阶段、倒计时和开始/暂停，仍可拖动、展开或关闭。 - **可配置循环：** 专注与休息时长可调，并可分别控制是否自动开始休息或下一轮专注。 - **阶段结束提醒：** 无论面板是否打开都会显示 DSH 内提醒，还可选择提示音和后台系统通知。 - **DSH 语言支持：** 跟随 DSH 全局语言提供中文和英文；切换语言会立即更新已打开的插件界面，不会重置计时或未保存的设置草稿。 - **界面适配：** 自动适配 DSH 明暗主题、键盘操作和“减少动态效果”偏好。 ## 环境要求 | 组件 | 要求 | |---|---| | DeepSeek Harness | 已验证版本见各插件 Release 说明 | | Node.js | `^22.19.0` 或 `>=24.0.0` | | DSH profile | `web`；headless profile 不提供界面 | | pnpm | 可从命令行使用 | ## 快速安装 将插件安装到 `web` profile： ```powershell dsh plugin --profile web add dsh-pomodoro ``` 安装后启动或重启 DSH Web： ```powershell dsh web ``` 侧栏底部出现 🍅 按钮即表示插件已加载。 ### 在 DSH 界面内安装 不想离开 Web 界面？两个社区伴侣插件都可以代劳： - **[dsh-market](https://github.com/dsh-market/dsh-market)**：先执行 `dsh plugin --profile web add dshmarket` 并重启 `dsh web`，然后打开“设置 → 插件市场”，搜索 `dsh-pomodoro` 一键安装，刷新页面即可使用。 - **[dsh-find-plugin](https://github.com/awesome-dsh-plugin/dsh-find-plugin)**：先执行 `dsh plugin --profile web add dsh-find-plugin` 并重启 `dsh web`，然后直接对话“帮我安装 dsh-pomodoro 插件到 dsh”，agent 会搜索并完成安装，结束后刷新浏览器即可。 ## 基本使用 点击侧栏 🍅 按钮打开或关闭面板，拖动标题栏可以调整面板位置。标题栏中的“迷你”会收起次要信息，“展开”可恢复完整面板。 | 控件 | 行为 | |---|---| | 开始 / 暂停 | 启动或暂停当前阶段 | | 重置 | 将当前阶段恢复到完整时长并暂停 | | 跳过 | 切换到下一阶段并保持暂停 | | 迷你 / 展开 | 在低遮挡布局与完整控制之间切换 | ## 设置与提醒 新版 DSH：从侧栏进入“插件 → dsh-pomodoro”，展开“番茄钟”卡片。旧版 DSH：进入“设置 → 插件 → 插件配置 → 番茄钟”。可修改以下六项设置： | 设置 | 默认值 | 作用 | |---|---:|---| | 专注时长 | 25 分钟 | 每轮专注阶段的完整时长，可设置为 1–240 分钟的整数 | | 休息时长 | 5 分钟 | 每轮休息阶段的完整时长，可设置为 1–240 分钟的整数 | | 自动开始休息 | 开启 | 专注自然结束后自动启动休息 | | 自动开始下一轮专注 | 关闭 | 休息自然结束后自动启动下一轮 | | 阶段结束时播放提示音 | 关闭 | 阶段自然结束时播放三次提示音，可直接试听 | | 后台时发送系统通知 | 关闭 | DSH 页面位于后台时发送浏览器通知 | 当前阶段尚未开始时，新时长会立即生效；计时已经开始后，从下一阶段生效。 支持远程设置持久化的新版 DSH 中，已认证的远程浏览器也可保存和清除设置。首次打开页面时，番茄钟会等待宿主设置返回，再执行开始操作或结算离线期间已到期的阶段，避免误用默认时长与自动开始选项。旧宿主不提供远程设置时仍按默认配置运行。 ### 旧设置迁移 升级到新版设置宿主后，插件会自动读取 `$DSH_HOME/settings.yaml`（不存在时读取 `settings.yaml.imported`）中的 `dsh-pomodoro` 分节。只迁移上表六个有效字段，并且只补充新版配置中尚未明确设置的字段；原文件保持不变，无效字段会跳过并在宿主日志中提示。 迁移结果和内部完成标记由宿主一次写入。点击“清除自定义设置”会恢复继承的配置，不会在重启后再次导入旧值。迁移读取或写入失败时，现有配置保持不变；修复旧文件的格式或权限后重启重试，也可以在插件详情页重新设置。 新版保存与清除均一次提交六项变更。若发生并发修改或写入失败，界面会显示错误并保留草稿，请核对最新设置后重试。 ### 完成提醒 - **DSH 内提醒：** 始终开启。专注或休息自然结束时会显示，即使番茄钟面板已经关闭也能看到；若下一阶段自动开始，提醒中会一并说明。 - **提示音：** 默认关闭。开启并保存后，每次阶段自然结束会播放三次提示音；“试听”无需先保存。 - **系统通知：** 默认关闭。首次开启时请按浏览器提示允许通知，然后点击“保存”。通知只在 DSH 页面位于后台或失去焦点时发送。 所有 DSH 页面都关闭时，浏览器不会在截止时刻播放提示音或发送通知；下次打开 DSH 时会恢复状态，并对已到期的当前阶段结算和提醒一次。 系统通知需要通过 `localhost`、`127.0.0.1` 或 HTTPS 访问，并保持 DSH 页面打开。提示音或系统通知不可用时，DSH 内提醒仍然有效。 ## 更新与移除 ```powershell # 更新插件 dsh plugin --profile web update dsh-pomodoro # 移除插件 dsh plugin --profile web remove dsh-pomodoro ``` 执行后重启 `dsh web`。 插件通过 `engines.dsh` 向新版宿主声明兼容范围，并保留旧宿主使用的 peer 依赖声明。实际完成验证的 rc 版本及验证范围以每次 Release 说明为准。 ## 故障排查 | 症状 | 处理 | |---|---| | 安装或更新时报 `'pnpm' 不是内部或外部命令` | `dsh plugin` 依赖 PATH 上的 pnpm：执行 `npm install -g pnpm` 后重试 | | `dsh web` 启动失败，提示端口 3080 被占用 | 上一个实例仍在运行或已残留：用 `netstat -ano \| findstr :3080` 找到 PID，`taskkill /PID /F` 结束后重启 | | 侧栏没有 🍅 按钮 | 确认使用 `web` profile 且已执行 `dsh plugin --profile web add dsh-pomodoro`，然后重启 `dsh web` | | 找不到旧设置入口 | 新版入口为侧栏“插件 → dsh-pomodoro”；旧版仍在“设置 → 插件 → 插件配置” | | 升级后旧设置未导入 | 检查宿主日志中的 `dsh-pomodoro` 迁移诊断；修复旧文件格式或权限后重启，或在插件页重新设置 | | 系统通知不出现 | 检查浏览器站点通知权限并保持 DSH 页面打开，详见[完成提醒](#完成提醒) | ## 相关链接 - [npm 包](https://www.npmjs.com/package/dsh-pomodoro) - [版本发布](https://github.com/causebefore/dsh-pomodoro/releases) - [问题反馈](https://github.com/causebefore/dsh-pomodoro/issues) - [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) ## License [MIT](LICENSE)。React/ReactDOM 与 CC0 完成提示音等第三方素材的许可信息见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 ## 开发与维护
展开本地开发、项目结构与发布流程 ### 本地开发 ```powershell git clone https://github.com/causebefore/dsh-pomodoro.git Set-Location dsh-pomodoro dsh plugin --profile web add . npm run check npm pack --dry-run ``` 项目没有生成步骤，`lib/client.js` 就是直接发布的浏览器 bundle。日常开发在 `dev` 分支进行，`main` 只接收已经完成发布检查的版本。 ### 项目结构 | 路径 | 职责 | |---|---| | `lib/index.js` | Node/Cordis 入口、官方设置分节与只读配置降级通道（新宿主 GET 路由 / 老宿主 loopback RPC） | | `lib/migrate-settings.js` | 旧设置的受限读取、字段校验及一次性迁移 | | `lib/client.js` | 浏览器计时引擎、React UI、slot 注册、locale 文案和设置同步 | | `assets/sounds/deep-ding.mp3` | CC0 低沉提示音源文件；运行时字节嵌入客户端 bundle | | `docs/images/` | 中英文 README 截图与 GitHub Social Preview 图片 | | `cordis.patch.yml` | 向 DSH Web 组合插入插件服务 | | `package.json` | exports、peer 范围、bundle 声明和 npm 发布清单 | | `.github/workflows/publish.yml` | GitHub Release 到 npm 的可信发布流程 | ### 发布流程 1. 在 `dev` 完成开发和验证，并更新 `package.json` 版本。 2. 通过发布 PR 将 `dev` 合入 `main`。 3. 从对应的 `main` 提交创建名称匹配 `vX.Y.Z` 的稳定 GitHub Release。 4. 发布工作流会验证版本、tag 和 `main` 归属，运行语法与打包检查，再通过 npm Trusted Publishing 发布。