dsh-pomodoro

dsh plugin --profile web add dsh-pomodoro

<div align="center">

<h1>🍅 dsh-pomodoro</h1>

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

<p>

<a href="./README.md">English</a> ·

<strong>简体中文</strong>

</p>

<p>

<a href="https://www.npmjs.com/package/dsh-pomodoro"><img alt="npm 版本" src="https://img.shields.io/npm/v/dsh-pomodoro.svg?logo=npm"></a>

<a href="https://www.npmjs.com/package/dsh-pomodoro"><img alt="npm 月下载量" src="https://img.shields.io/npm/d18m/dsh-pomodoro.svg"></a>

<a href="https://www.npmjs.com/package/dsh-pomodoro"><img alt="Node.js 版本" src="https://img.shields.io/node/v/dsh-pomodoro.svg?logo=node.js"></a>

<a href="https://github.com/deepseek-ai/deepseek-harness"><img alt="DSH rc 版本" src="https://img.shields.io/badge/DSH-rc%20releases-4B8BF5"></a>

<a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img alt="Awesome DSH Plugin" src="https://awesome-dsh-plugin.com/badge.svg"></a>

<a href="https://github.com/causebefore/dsh-pomodoro/blob/main/LICENSE"><img alt="MIT 许可证" src="https://img.shields.io/npm/l/dsh-pomodoro.svg"></a>

</p>

<p>

<img src="https://raw.githubusercontent.com/causebefore/dsh-pomodoro/main/docs/images/pomodoro-demo.gif" alt="演示：专注阶段倒计时走动，阶段结束提醒出现并自动进入休息，随后自动开始下一轮专注，最后面板收起为迷你模式" width="560">

</p>

<p>

<a href="#界面预览">界面预览</a> ·

<a href="#功能亮点">功能亮点</a> ·

<a href="#快速安装">快速安装</a> ·

<a href="#基本使用">基本使用</a> ·

<a href="#设置与提醒">设置与提醒</a> ·

<a href="#故障排查">故障排查</a>

</p>

</div>

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

界面预览

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

<table>

<tr>

<th align="center">浅色主题</th>

<th align="center">深色主题</th>

</tr>

<tr>

<td align="center"><img src="https://raw.githubusercontent.com/causebefore/dsh-pomodoro/main/docs/images/pomodoro-light.png" alt="浅色主题下的番茄钟浮动面板" width="250"></td>

<td align="center"><img src="https://raw.githubusercontent.com/causebefore/dsh-pomodoro/main/docs/images/pomodoro-dark.png" alt="深色主题下的番茄钟浮动面板" width="250"></td>

</tr>

</table>

迷你模式

<p align="center">

<img src="https://raw.githubusercontent.com/causebefore/dsh-pomodoro/main/docs/images/pomodoro-mini.png" alt="只显示阶段、倒计时和主要控制的迷你番茄钟" width="186">

</p>

设置页面

<p align="center">

<img src="https://raw.githubusercontent.com/causebefore/dsh-pomodoro/main/docs/images/pomodoro-settings-light-zh.jpg" alt="DSH 插件详情页中的番茄钟设置，浅色主题" width="800">

</p>

<details>

<summary>深色主题设置页面</summary>

<p align="center">

<img src="https://raw.githubusercontent.com/causebefore/dsh-pomodoro/main/docs/images/pomodoro-settings-dark-zh.jpg" alt="深色主题下的番茄钟插件设置" width="800">

</p>

</details>

功能亮点

• 融入 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：

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：从侧栏进入“插件 → 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 内提醒仍然有效。

更新与移除

# 更新插件
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 <pid> /F 结束后重启

侧栏没有 🍅 按钮 · 确认使用 web profile 且已执行 dsh plugin --profile web add dsh-pomodoro，然后重启 dsh web

找不到旧设置入口 · 新版入口为侧栏“插件 → dsh-pomodoro”；旧版仍在“设置 → 插件 → 插件配置”

升级后旧设置未导入 · 检查宿主日志中的 dsh-pomodoro 迁

…(truncated)