Skip to content
dsh marketplace

dsh-pomodoro-overlay

Verified

dsh-pomodoro-overlay · v0.1.0 · MIT · Web UI

Automatic focus/break Pomodoro cycles with a chat-sized translucent countdown for DeepSeek Harness Web.

Install

dsh plugin add dsh-pomodoro-overlay

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Readme

dsh-pomodoro-overlay

为 DeepSeek Harness Web 设计的自动循环番茄钟。启动后无需点击，自动进行「专注 → 休息 → 专注」循环；一个尽量铺满聊天消息区的半透明大倒计时，不覆盖侧栏和底部输入框。

功能

  • 自动循环：默认专注 25 分钟、休息 5 分钟；原生配置读取完成后自动开始。
  • 聊天区大倒计时：按消息区实际宽高和文字宽度自适应，保持数字比例，不裁切。
  • 可配置阶段外观：默认专注浅灰 #9ca3af / 10% 不透明度，休息红 #ef4444 / 30% 不透明度；颜色和不透明度均可调整。
  • 可配置时钟字体：专注与休息共用，默认等线（DengXian）；可输入本机已安装字体，未安装时回退到本机无衬线字体，不下载字体。
  • DSH 原生设置页：在 DSH 设置窗口的「番茄钟」页修改字体及两种阶段的时长、颜色和不透明度；七个字段一次原子保存，revision 防止并发覆盖。
  • 纯展示聊天层：聊天区只有阶段标签和大倒计时，没有暂停、跳过、重置等控制按钮。
  • 刷新恢复：运行状态保存绝对截止时间，刷新、切标签页、休眠或重开页面后按原时间线恢复，不通过 interval 递减计时。
  • 低干扰：数字层鼠标穿透；没有声音、系统通知、网络请求、模型工具或额外后台服务。

安装

在本目录执行：

npm run build
dsh plugin --profile web add "$(pwd)"

按 dsh plugin 返回的应用结果操作：若 Host schema 变更要求重启，请在外部 Terminal 重载现有 DSH Web 服务并刷新原 GUI，不要从 DSH 会话内部终止自己的宿主；若支持客户端 HMR，则确认浏览器已收到新 bundle 后再刷新。不要把“Host 已应用”直接当作浏览器已加载成功。

安装会修改 ~/.dsh/profiles/web，请通过正常的 DSH 安装命令完成，不要手改 profile 的 package/patch 文件。

设置与使用

  1. 打开 DSH 左下角的「设置」窗口。
  2. 在设置导航中选择 番茄钟。
  3. 在「时钟字体」中保留默认等线，或输入其他本机已安装字体；也可从常用候选中选择。
  4. 分别调整专注和休息：
    • 时长：整数 1–240 分钟，默认 25 / 5。
    • 数字颜色：原生颜色选择器，使用 #RRGGBB。
    • 数字不透明度：0–100%，默认 10% / 30%。
  5. 查看使用所选字体的草稿预览，点击「保存设置」；如需还原未保存草稿，点击「放弃修改」。

配置生效规则：不打断当前计时。 字体、颜色和不透明度保存后立即应用；当前阶段的时长与截止时间不变，新时长从下一阶段开始生效。聊天区不提供控制按钮，计时会按配置自动循环。

恢复与多标签语义

  • 页面关闭时没有浏览器计时器或通知在运行；但绝对时间线仍有效，重开后会落到当前应有阶段。
  • 长时间离线按完整周期做算术跳跃，不逐分钟循环，也不补发历史提醒。
  • localStorage 不可用时自动退化为当前页面内存计时，阶段切换仍继续；刷新后可能重置。
  • 多个同源标签页通过 storage 事件尽力同步。没有 Web Locks，不承诺并发操作下的严格 exactly-once；本插件也不发送完成通知，因此不存在通知风暴。
  • 原生周期与外观配置保存在 DSH profile；运行状态保存在当前浏览器同源 localStorage，二者用途不同。

兼容性边界

已在 DSH 0.2.1-rc.2 的真实 Web GUI 中验证；本次环境的既有插件冲突及隔离方式见 验证记录。

当前 DSH 没有公开的“聊天消息区 additive overlay”slot，因此插件使用公开的 shell.overlay，再只读测量以下 Conversation DOM 标记，将实际覆盖范围限制在消息区：

  • [data-conversation-content][data-conversation-region="chat"]
  • [data-composer-seat]
  • [data-chat-flow]

这些标记是内部 DOM，不是稳定 API。找不到活动消息流、切到其他视图、区域异常或过小时，插件会隐藏而不是全屏遮挡。升级 DSH 后必须重跑布局验证。

开发

运行时没有 npm React 依赖，React 由 DSH 宿主提供；@deepseek-ai/schemastery 用于 Host 配置。esbuild 仅是开发依赖。

npm install --legacy-peer-deps
npm run verify

在文件写入沙箱中，如全局 npm 缓存不可写，可使用项目缓存：

npm install --legacy-peer-deps --cache .npm-cache

单独执行：

npm run build       # src/ → client/client.js（DSH ModuleLoader 格式）
npm run check       # 语法、manifest、patch、schema 声明与 bundle 静态检查
npm test            # node:test
node tools/build.mjs --check  # 检查构建产物是否过时

测试覆盖：自动循环、精确边界、跨多个离线周期、旧/新配置语义、颜色、不透明度与字体校验、字体栈、外观即时更新、暂停继续、跳过/重置、损坏快照、存储失败、多标签旧事件、dispose、聊天区几何、Host schema、原生设置 slot，以及构建后客户端的加载/启动/清理冒烟。

验证结果

  • npm run verify 通过，38/38 自动化测试通过；独立审查及 896 组状态机对拍未发现算术跳周期错误。
  • 真实 DSH GUI 已验证自动启动、1/1 分钟自动双向循环、刷新恢复、灰/红半透明配色、原生设置保存与当前截止时间不变。
  • 桌面与 380px 窄窗口均精确匹配聊天消息区并扣除输入框；数字无裁切，聊天区无控制按钮，非聊天视图隐藏。
  • 测试用的 1/1 配置已恢复为 25/5。
  • 完整结果与既有 file-tree / 内置 sidebar-files 冲突说明见 docs/verification.md。该冲突不是番茄钟引起的，本次未擅自修改其他插件。

文件

  • lib/index.js：Host 配置 schema 与自定义设置策略。
  • src/timer-core.js：纯计时状态机。
  • src/browser-store.js：运行持久化、跨标签同步与订阅。
  • src/chat-geometry.js：聊天区识别及 composer 扣除。
  • src/font.js：本机字体候选与安全 CSS 字体栈。
  • src/client.js：React overlay、slots 注册与生命周期。
  • src/settings.js：DSH 设置窗口中的七字段表单与草稿预览。
  • src/styles.js：主题令牌、响应式与 reduced-motion 样式。
  • client/client.js：构建产物，请勿直接编辑。
  • docs/design.md：交互和视觉验收标准。
  • docs/architecture.md：接口证据与实现决策。
  • docs/verification.md：自动化与真实 GUI 验证结果、环境限制。

License

MIT