番茄专注钟 skillre/dsh-plugin-pomodoro

@skillre/dsh-plugin-pomodoro

状态：experimental

在 DSH Web UI 里的番茄时钟：输入框下方常驻的专注计时器，带每日番茄数与本地偏好设置。

它做什么

- 在输入框（composer）下方显示一枚常驻胶囊：当前阶段、倒计时、本轮进度和三个按钮（开始/暂停、重来、跳到下一阶段）。
- 阶段按经典番茄工作法循环：专注 → 短休息 → … → 第 N 轮后进入长休息 → 回到专注。
- 记录当天完成的专注轮数与专注时长；跨过本地零点自动归零。
- 在 设置 里提供独立一页，调整各阶段时长、循环轮数和两个自动开始开关。

非目标

- 不做系统通知、声音提示或浏览器 Notification 授权（需要额外权限，首版不引入）。
- 不写入 Session 日志、不注册模型可见的 Tool：番茄钟是纯 UI 状态，模型不需要看到它。
- 不做跨设备的云同步。
- 不在 DSH 退出后继续走时（见「已知限制」）。

安装

发布后：

dsh plugin --profile add @skillre/dsh-plugin-pomodoro

本地开发内环（必须走打包 tarball）：

npm install
npm run check
npm pack
dsh plugin --profile add ./skillre-dsh-plugin-pomodoro-.tgz
dsh --profile --dump-config
dsh --profile

不要用 dsh plugin ... add .：把源码目录交给包管理器会建立源码链接安装，插件因此解析到自己的 node_modules 而不是宿主的，本地一切正常、打包安装却在启动时炸掉整个 profile。file: 才是受支持的形态。

更新与回滚见 UNINSTALL.md。

配置与默认值

插件行没有配置项：cordis.patch.yml 只插入一行，不带 config。所有可调项属于用户偏好，存在浏览器本地（见下），因此在设置页里改，而不是在 cordis.patch.yml 里改。

| 偏好 | 默认值 | 范围 | 含义 |
| 专注时长 | 25 分钟 | 1–180 | 一轮专注的长度 |
| 短休息 | 5 分钟 | 1–180 | 普通专注轮次之后的休息 |
| 长休息 | 15 分钟 | 1–180 | 完成一个循环后的休息 |
| 长休息前的专注轮数 | 4 | 1–12 | 一个循环包含几轮专注 |
| 自动开始休息 | 开 | 开/关 | 专注结束后直接进入休息 |
| 自动开始专注 | 关 | 开/关 | 休息结束后直接进入下一轮专注 |

越界的输入会被收敛到范围内，而不是报错：损坏或来自旧版本的数据也会退化成一个可用的配置。

显示元数据

DSH 读取插件卡片信息时不激活插件，所以这些资源随包发布：

- locale/en.json（必需）与 locale/zh.json：{"meta": {"title": ..., "description": ...}}。
它经 Node ESM resolver 解析，因此 exports 必须声明 "./locale/.json"；缺这一条会抛 ERR_PACKAGE_PATH_NOT_EXPORTED，而 DSH 会静默吞掉该错误，卡片退化成裸包名。
- icon：顶层字段 ./icon.svg，包内相对路径、小于 256 KiB、被 files 覆盖。

| locale | title | description |
| en | Pomodoro | A focus clock beside the composer, with daily rounds and local preferences. |
| zh | 番茄时钟 | 输入框旁的专注计时器：工作/休息循环、每日番茄数与本地偏好。 |

界面文案不在这里，而在客户端通过 Client locale 服务注册的 skillre-pomodoro 命名空间（src/client/text.ts，含 en 与 zh 两套词典）。

权限与副作用

- 网络：无。
- 凭据 / 密钥：无。
- 文件系统：无。Host 半边是空入口，不做任何 I/O。
- 浏览器存储：写入 localStorage，键为 skillre-pomodoro/state，内容只有计时状态、当天计数与偏好（payload 带 version，当前为 2），全部是插件自己的 JSON，不含 Session 内容、提示词或路径。存储不可用或写满时静默降级为纯内存运行，计时器不受影响。旧版本写入的记录会被丢弃并重新以暂停状态开始，而不是用当前配置去猜测它原本的长度。
- UI 占用：两个 slot 注册（conversation.composer.dock 与 settings.section），使用插件自己的类名前缀 skp-pomodoro- 和主题变量 --dsw-alias-，不读写产品 DOM，不替换宿主结构。
- 定时器：运行中每秒一次刷新；空闲时睡到下一个本地零点（最早的显示变化时刻）。两者都挂在插件 Fiber 上，卸载即清理。

生成的与模型可见的行为

没有。插件不注册 Tool、不注入 prompt、不写 Session 事件，模型看不到番茄钟。

兼容性

| DSH 版本 | 已完成的验证 | 日期 |
| 0.2.0-rc.2 | 打包 tarball 装入 desktop profile（application: applied）；客户端模块在真实页面加载并把两个 slot 注册为 active occupant；产物按宿主模块信封契约在测试中加载通过 | 2026-09-30 |

尚未完成（因此 compatibility.json#verified 保持为空，release:prepare 会按设计失败）：

- dump-config 与 bounded-startup：未在隔离 profile 中执行。
- browser：没有做真实浏览器视觉验证。当前环境的浏览器控制不可用（CDP 无法读取工作区沙箱之外的 Chrome 调试端口），因此渲染外观、明暗主题与交互均未被观察过。

按技能要求，无浏览器控制时只做语法、manifest 与 live Client slot 三项验证，不构造预览图或模拟渲染来替代。已完成的证据与待办记录在 compatibility.json#observations。Peer range 不是兼容性证据。

已知限制

- 计时依赖浏览器：关闭整个页面期间不推进播放，重开页面时按绝对时间戳结算到期的阶段（因此不会补记睡眠期间的多轮番茄）。
- conversation.composer.dock 的 scope 是 session，所以胶囊随笔输入框出现；没有活动 Session 的空白首页不显示它。设置页（root scope）不受影响。
- 「今天」按浏览器本地时区划分；跨零点时正在进行的阶段不中断，完成时才计入新的一天。
- 一次 settle 只结算一个到期阶段；长时间休眠后不会一次性补记多轮。
- 每个标签页各自持有一份计时状态，通过 localStorage 收敛，但没有跨标签页的实时广播：在 A 标签页开始，B 标签页要等下一次刷新才看到。
- 没有通知与声音提示。

开发

npm run typecheck # Host + tests，以及 Client 半边（DOM lib）
npm test # 先构建 lib/client.js，再跑单测与产物集成测试
npm run check # typecheck + test + pack:check

Client 半边用 esbuild 打包成一个 CommonJS 文件（src/client/index.ts → lib/client.js），只有 baseline react 是 external；原因是模块信封里的 require 只能解析浏览器模块表，相对 require('./store.js') 在运行时无法解析。tests/client-bundle.spec.ts 会按宿主的方式加载产物，一旦多出第二个依赖就失败。

契约查询记录（2026-09-30，DSH 0.2.0-rc.2）：

- Slots.listSubTree：conversation.composer.dock（list，session scope，注册参数 id/order/label）、settings.section（list，root scope，ownerProps { close }）。
- Client Service：slots（inject/register）、locale（register(ns, locale, dict)/bind(ns)/getLocale/subscribe）。
- Builtin：ctx（受限 Context，ctx.effect）、React；模块信封为 window.__ModuleLoader__.load({ id, factory })。
- Theme：仅使用 --dsw-alias-*。

License

MIT