causebefore/dsh-pomodoro

🍅 dsh-pomodoro

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

English ·
简体中文

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

兼容性提示： DeepSeek Harness 目前迭代迅速，本插件仅跟进 rc 版本：开发与验证均以 rc 基线为准，不承诺支持 alpha 等中间预发布。每个发布版本适配的 DSH 版本都在 Releases 说明中注明；升级 DSH 后，请先对照 Release 说明确认插件兼容性。

界面预览

支持明暗主题、迷你模式和 DSH 插件配置。

浅色主题
深色主题

迷你模式

设置页面

功能亮点

- 融入 DSH： 从侧栏打开番茄钟，在插件配置页面统一管理设置。
- 完整计时控制： 支持开始、暂停、重置、跳过、环形进度、阶段提示和已完成专注计数。
- 跨会话恢复： 刷新页面，或关闭标签页、重启浏览器后重新打开 DSH，都会按原截止时间恢复；离开期间已到期时只结算当前阶段一次。
- 低干扰迷你模式： 收起后只保留阶段、倒计时和开始/暂停，仍可拖动、展开或关闭。
- 可配置循环： 专注与休息时长可调，并可分别控制是否自动开始休息或下一轮专注。
- 阶段结束提醒： 无论面板是否打开都会显示 DSH 内提醒，还可选择提示音和后台系统通知。
- DSH 语言支持： 跟随 DSH 全局语言提供中文和英文；切换语言会立即更新已打开的插件界面，不会重置计时或未保存的设置草稿。
- 界面适配： 自动适配 DSH 明暗主题、键盘操作和“减少动态效果”偏好。

环境要求

| 组件 | 要求 |
|---|---|
| DeepSeek Harness | 已验证 0.1.1-rc.2、0.1.2-rc.1 |
| Node.js | ^22.19.0 或 >=24.0.0 |
| DSH profile | web；headless profile 不提供界面 |
| pnpm | 可从命令行使用 |

快速安装

将插件安装到 web profile：

dsh plugin --profile web add dsh-pomodoro

安装后启动或重启 DSH Web：

dsh web

侧栏底部出现 🍅 按钮即表示插件已加载。

在 DSH 界面内安装

不想离开 Web 界面？两个社区伴侣插件都可以代劳：

- dsh-market：先执行 dsh plugin --profile web add dshmarket 并重启 dsh web，然后打开“设置 → 插件市场”，搜索 dsh-pomodoro 一键安装，刷新页面即可使用。
- dsh-find-plugin：先执行 dsh plugin --profile web add dsh-find-plugin 并重启 dsh web，然后直接对话“帮我安装 dsh-pomodoro 插件到 dsh”，agent 会搜索并完成安装，结束后刷新浏览器即可。

基本使用

点击侧栏 🍅 按钮打开或关闭面板，拖动标题栏可以调整面板位置。标题栏中的“迷你”会收起次要信息，“展开”可恢复完整面板。

| 控件 | 行为 |
|---|---|
| 开始 / 暂停 | 启动或暂停当前阶段 |
| 重置 | 将当前阶段恢复到完整时长并暂停 |
| 跳过 | 切换到下一阶段并保持暂停 |
| 迷你 / 展开 | 在低遮挡布局与完整控制之间切换 |

设置与提醒

在 DSH 的“设置 → 插件 → 插件配置 → 番茄钟”中展开卡片即可修改：

| 设置 | 默认值 | 作用 |
|---|---:|---|
| 专注时长 | 25 分钟 | 每轮专注阶段的完整时长，可设置为 1–240 分钟的整数 |
| 休息时长 | 5 分钟 | 每轮休息阶段的完整时长，可设置为 1–240 分钟的整数 |
| 自动开始休息 | 开启 | 专注自然结束后自动启动休息 |
| 自动开始下一轮专注 | 关闭 | 休息自然结束后自动启动下一轮 |
| 阶段结束时播放提示音 | 关闭 | 阶段自然结束时播放三次提示音，可直接试听 |
| 后台时发送系统通知 | 关闭 | DSH 页面位于后台时发送浏览器通知 |

当前阶段尚未开始时，新时长会立即生效；计时已经开始后，从下一阶段生效。

完成提醒

- DSH 内提醒： 始终开启。专注或休息自然结束时会显示，即使番茄钟面板已经关闭也能看到；若下一阶段自动开始，提醒中会一并说明。
- 提示音： 默认关闭。开启并保存后，每次阶段自然结束会播放三次提示音；“试听”无需先保存。
- 系统通知： 默认关闭。首次开启时请按浏览器提示允许通知，然后点击“保存”。通知只在 DSH 页面位于后台或失去焦点时发送。

所有 DSH 页面都关闭时，浏览器不会在截止时刻播放提示音或发送通知；下次打开 DSH 时会恢复状态，并对已到期的当前阶段结算和提醒一次。

系统通知需要通过 localhost、127.0.0.1 或 HTTPS 访问，并保持 DSH 页面打开。提示音或系统通知不可用时，DSH 内提醒仍然有效。

更新与移除

更新插件
dsh plugin --profile web update dsh-pomodoro

移除插件
dsh plugin --profile web remove dsh-pomodoro

执行后重启 dsh web。

故障排查

| 症状 | 处理 |
|---|---|
| 安装或更新时报 '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 页面打开，详见完成提醒 |

相关链接

- npm 包
- 版本发布
- 问题反馈
- DeepSeek Harness

License

MIT。React/ReactDOM 与 CC0 完成提示音等第三方素材的许可信息见 THIRD_PARTY_NOTICES.md。

开发与维护

展开本地开发、项目结构与发布流程

本地开发

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 入口、官方设置分节与只读 loopback 配置降级 RPC |
| 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 发布。