侧栏时钟月历 XZT1118/dsh-plugin-calendar-clock

dsh-plugin-calendar-clock

一个 DeepSeek Harness Web GUI 插件：在侧边栏底部、设置按钮旁加一个时钟按钮，点开是实时数字时钟 + 模拟表盘 + 月历。

侧边栏底部位置

预览图只是布局示意，不是运行中应用的截图。实际视觉效果还需要在真实页面上人工确认——见验证。

功能

- 实时数字时钟——HH:MM:SS，每秒重绘一次，对齐到秒边界，所以永远不会走偏。
- 模拟表盘——时针、分针、秒针，精确到秒；遵循 prefers-reduced-motion。
- 月历——固定的 6×7 网格，周一开头，今天用 aria-current="date" 高亮，带上一月 / 下一月 / 回到今天控件。
- 两种侧边栏宽度都适配——在 56px 窄栏里，座位传入 wide: false，按钮退化成纯图标控件，同时保留无障碍名称。
- 双语——中文和英文字典注册在插件自己的 locale 命名空间下；切换应用语言，卡片立即重绘。
- 静默失败——占位组件包在错误边界里，渲染出错时退化成纯时间字符串，不会把整个侧边栏拖垮。

安装

从 GitHub 作为配置档 bundle 安装：

dsh plugin --profile web add 'github:XZT1118/dsh-plugin-calendar-clock'

也可以在 GUI 里打开 Settings → Plugins 管理器，输入同一个仓库 spec。

安装新 bundle 后需要重启，它才会加入启动组合。之后，对本插件 lib/client.js 的修改会热重载。

如果你想自己改配置档，手动等价做法——把下面两项都加进 $DSH_HOME/profiles/<profile>/package.json，然后在配置档目录里跑 pnpm install：

{
"dsh": { "profile": { "bundles": [
// ... existing bundles, official ones first ...
"@dsh-external/dsh-calendar-clock"
] } },
"dependencies": {
"@dsh-external/dsh-calendar-clock": "github:XZT1118/dsh-plugin-calendar-clock"
}
}

bundle 列表的顺序就是补丁层顺序；官方 bundle 要排在第三方前面。

用法

1. 在侧边栏底部、设置按钮旁找到时钟按钮。侧边栏收起时它只有图标；展开侧边栏，图标旁边会显示当前时间。
2. 点它（或聚焦后按 Enter）打开卡片。
3. ‹ / • / › 分别跳到上一月、回到今天、跳到下一月。
4. 按 Esc、点击卡片外部，或再点一次按钮，都能关闭卡片。
卡片用 position: fixed 坐标把自己锚定在按钮上方，坐标从触发元素自身的边界框量出，因此能跳出侧边栏的滚动容器和任何裁剪。窗口缩放、祖先元素滚动时都会重新测量，所以侧边栏拖宽时它依然紧贴按钮。

包结构

| 路径 | 作用 |
| package.json | 清单：dsh.bundle.patch 插入宿主行，dsh.client 声明浏览器端 |
| cordis.patch.yml | 插入本插件的唯一一行；不替换 Harness 自带的任何内容 |
| lib/index.js | 宿主端：刻意留空 —— 所有值都来自浏览器时钟 |
| lib/client.js | 浏览器端：懒加载的 __ModuleLoader__ 包（UI 加日历运算） |
| locale/en.json、locale/zh.json | 插件管理卡片显示的标题和描述 |
| icon.svg | 插件图标 |
| test/calendar.test.mjs | 日历运算的单元测试 |
| test/bundle.mjs | 按页面的方式加载包：当作经典脚本 |
| tools/check.mjs | 清单、字典、补丁、注册契约检查 |
| tools/identity-check.mjs | 一次性校验包身份和脚本类型 |
| tools/rollback.mjs | 从配置档离线紧急回滚 |

没有运行时依赖：包只 require('react')，来自客户端冻结的平台模块表。没有安装期脚本。

工作原理

- 座位 —— sidebar.footer.action，侧边栏属主在底部声明的可叠加列表槽位。条目以 id: 'calendar-clock' 和 order: 20 注册；新 id 会加在自带条目旁边，而不是替换掉某个。
- 属主 prop —— 座位只传一个 prop，wide。false 表示 56px 窄栏。
- 计时 —— 自校正的 setTimeout 链在 1000 - (Date.now() % 1000) 处重新挂起，让 tick 落在整秒边界上。只在卡片打开时运行。
- 格式化 —— 用 Intl.DateTimeFormat 加浏览器解析出的区域设置，所以 12/24 小时制和日期写法跟随区域设置，不需要单独开关。
- 本地化 —— 字典放在 plugin.calendar-clock 命名空间。组件通过 useSyncExternalStore 订阅 locale，所以切换语言（或字典注册较晚）会重绘已挂载的文本，而不是冻结在第一份字典上。
- 隔离 —— 座位占用者包在 React 错误边界里。

验证

node --check lib/client.js # the browser half must parse as a classic script
node tools/identity-check.mjs # bundle identity and script kind
node --test test/calendar.test.mjs # 9 calendar-math tests
node tools/check.mjs # 6 manifest / contract tests
运行中的 GUI 没法从这里驱动，所以自动化覆盖只能停在日历运算、注册契约和脚本类型守卫上。想确认渲染出来的样子和浮层几何，还是得有人在真实页面上看：

1. 时钟按钮出现在侧边栏底部，紧挨着 Settings。
2. 点开后会显示一个走动的数字时钟、一个指针跟着走的表盘，以及月历网格里高亮的今天。
3. 月份切换和回到今天都能用；Esc 和点击外部可以关闭。
4. 切换应用语言会更新卡片上的文字。

有一项模块级检查不需要截图：宿主 Loader 那一行读作 include:calendar-clock，fiberPhase: active，并且 sidebar.footer.action 槽位列出了占用者 id: "calendar-clock"。

故障排查

安装后应用报「could not start」/ 启动失败。 读最新的崩溃日志：

%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-web-boot.log

如果出现类似 1 entry did not activate 并点名了这个包，同时还有 Uncaught SyntaxError: Unexpected token 'export'，说明浏览器那一半里含了 ES 模块语法。见经典脚本规则。GUI 用不了时，可以这样恢复：

node tools/rollback.mjs # strips the bundle and dependency from the profile
then run pnpm install in the profile directory and restart

tools/rollback.mjs 只改配置档清单。加 --profile <dir> 可以指定 $DSH_PROFILE_DIR 之外的配置档。

经典脚本规则

lib/client.js 会被拼进插件组合，当作普通 执行 —— 它不是 ES 模块。任何顶层 import 或 export 都会抛出 Uncaught SyntaxError: Unexpected token 'export'，而组合是一整段拼接脚本，所以这个失败会拖垮整个 web 启动，不只是这个插件。

这个插件的第一版就是这么干的：为了单元测试加了 export { build as buildFactory }。import() 抓不到它，因为 Node 接受被导入文件里的 ESM 语法。现在有两道防线防止重演：

- 打包产物结尾完全没有 export，工厂通过 globalThis.__dshCalendarClockBuild__ 发布（在浏览器里是惰性的），纯辅助函数则通过一个 internal 属性暴露给测试，Loader 从不读它；
- test/bundle.mjs 用 node:vm 以经典脚本语义加载打包产物，tools/identity-check.mjs 断言不存在模块语法。

卸载

从配置档 package.json 的 dsh.profile.bundles 和 dependencies 里都删掉 @dsh-external/dsh-calendar-clock，在配置档目录里跑 pnpm install，然后重启。或者用插件管理器的卸载操作。

只想禁用、不想卸载，就往配置档的 cordis.patch.yml 里加一行：

- id: calendar-clock
disabled: true

这个文件是热重载的，所以禁用本身不需要重启。

限制

- 使用浏览器本地时间和时区；没有时区或 UTC 切换开关。
- 月历网格不显示农历日期或节气。
- 不做持久化：浏览的月份、展开/收起状态都只在当前会话内有效。
- 兼容性声明针对 DeepSeek Harness 0.2.0-rc.2，这是它构建和验证时所用的版本。没有声明 peerDependencies 范围，所以安装器不会因为其他 DSH 版本而拦截它——但其他版本未经验证。

开发

这个包直接发布手写的源码两半；lib/ 是源码，不是构建产物，是特意提交进仓库的。没有构建步骤，也没有打包器。

git clone https://github.com/XZT1118/dsh-plugin-calendar-clock
cd dsh-plugin-calendar-clock
node --test test/calendar.test.mjs
node tools/check.mjs
node tools/identity-check.mjs

想针对实际配置档开发，就用 link: 把配置档指向这份检出，而不是 GitHub 上的版本，然后在配置档目录里重新跑一遍 pnpm install。

许可证

MIT