前言¶
智能体开发者在长时间编码或调试时，常需要明确的时间段来划分专注与休息。手动管理时间容易被打断，缺乏可视化反馈也难以评估投入产出。DSH（DeepSeek Harness）的插件机制允许在运行时扩展功能，但官方并未提供内置的番茄钟组件。
yongfanbeta/dsh-pomodoro 是一个为 DSH 提供番茄钟功能的第三方插件，在插件目录页与 GitHub 仓库中均可获取。它运行在 DSH 进程内，读取当前会话信息进行任务关联，并在本地持久化数据，支持导出为 CSV。
是什么¶
这是一个为 DeepSeek Harness（DSH）设计的番茄钟计时插件，维护者为 yongfanbeta。它提供经典的 25 分钟专注、5 分钟短休息、15 分钟长休息循环，支持将当前会话标题或项目名与计时关联，内置独立统计面板与全年热力图，数据存储在本地并支持导出为 CSV。插件依赖 Node.js 环境运行，无运行时第三方库依赖。
核心功能¶
经典计时循环¶
插件提供三种时长模式：专注 25 分钟、短休息 5 分钟、长休息 15 分钟。循环触发次数可配置，达到一定数量后自动进入长休息。倒计时基于截止时间戳运行，后台节流恢复前台时自动校正，减少漂移。
任务/会话关联¶
打开 DSH 某个会话后，面板会尝试解析当前工作区名或会话标题作为候选任务名。也可以从最近使用过的项目列表中选择，或手动输入任意项目名。关联后，每次完成专注会记录在对应项目下。
三处入口¶
插件在 DSH 界面提供三种访问方式：
- 侧边栏番茄图标：打开整屏面板，包含计时、统计、记录、设置四页
- 可拖动悬浮计时卡：用于快速开始/暂停/停止
- 角落迷你药丸：仅显示跳动时间，适合不打扰的背景计时
全年热力图¶
统计面板展示仿 GitHub 贡献图的全年热力图，覆盖近 365 天，并根据 DSH 的主题深浅调整颜色。图例直接给出今日番茄数、连续活跃天数、累计活跃天数、累计番茄数四个口径。
中断记账与完成率¶
完成、中断、放弃、跳过四类操作分开统计。中断不计入完成数，因此完成率可信。中断操作可选择“继续”，最终仍算一个完成。这种设计避免了因频繁暂停导致完成率虚高的问题。
本地持久化与导出¶
数据以全局 JSON 文件形式存储在 ${DSH_HOME:-~/.dsh}/storages/pomodoro/state.json，采用原子写入与损坏留档机制。支持导出带 BOM 的 CSV 文件，Excel 直接打开时中文不会乱码。无遥测、无统计上报，不联网、不上传任何数据。
安装与启用¶
安装前需要满足两个前置条件：
1. 已安装 DSH 并至少成功运行过一次
2. Node.js 版本为 ^22 或 >=24（Windows 用自带的 pwsh，macOS / Linux 用 bash + node）
插件已发布到 npmjs，可通过官方 CLI 或源码安装。
方式 A：官方 CLI 安装（推荐）¶
桌面端（desktop profile）：
dsh plugin --profile desktop add @yongfanbeta/dsh-pomodoro
Web 端需将 --profile desktop 换成 --profile web，然后执行 dsh web。
方式 B：从源码安装¶
在插件目录中执行对应平台的脚本：
Windows（含桌面端）：
pwsh -File scripts/install.ps1
macOS / Linux：
bash scripts/install.sh
脚本会自动定位当前正在运行的 profile，将插件复制到该 profile 的 node_modules 并登记 bundle 与 dependency。装完后重启 DSH，左侧栏会出现番茄图标。
若需显式指定 profile，可在脚本后追加参数，如 pwsh -File scripts/install.ps1 -Profile desktop。
校验安装¶
装完后可在插件目录执行：
npm run check:install
该脚本会打印实际校验的 profile 名，帮助确认是否装在正确的 profile 下。
典型用法¶
- 重启 DSH，点击左侧栏的番茄图标进入面板“计时”页。
- 若要关联当前任务，先打开对应的会话，回到面板后选择候选项；也可以直接输入项目名。
- 点击“开始专注”，到点后自动记录并切换到休息。
- 在“统计”页查看热力图与汇总数据，在“记录”页导出 CSV。
- 使用悬浮计时卡或角落药丸进行开始/暂停/停止操作。
适用场景与注意¶
适合需要明确专注与休息节奏、希望统计番茄数与项目投入的开发者。插件以当前 DSH 进程的权限运行，因此需要确保 DSH 有权限访问 ${DSH_HOME:-~/.dsh}/storages/pomodoro/state.json 所在目录。
安装前建议查看 GitHub 仓库的源码与许可证（MIT），确认符合自身使用场景。数据为全局一份，不按工作区隔离，如需按项目细粒度统计需自行在会话标题中体现。
限制与已知问题¶
- 提示音依赖浏览器
AudioContext，需要先与页面交互过才能播放；系统通知需授权，未授权时静默跳过。 - 会话标题来自 host 的
sessionTitle服务，不可用时退化为工作区名或目录名。 - 数据为全局一份，不按工作区隔离。
- 导出为 CSV（非多工作表的
.xlsx）。
结语¶
dsh-pomodoro 在 DSH 内部提供了本地化、无依赖的番茄钟与统计功能，适合希望用计时工具辅助开发节奏的开发者。如需设计与实现细节，可查看仓库中的 CONTRIBUTING.md；版本变更记录见 CHANGELOG.md。
- 目录页：https://www.skillhub.cn/plugins/yongfanbeta/dsh-pomodoro
- GitHub：https://github.com/yongfanbeta/dsh-pomodoro
