前言¶
在 DSH Web 里长时间开着会话时，「今天农历几号」「离春节还有几天」「下一个节气是什么时候」往往要另开日历或搜索。系统日历偏重公历，节令释义和习俗也不在同一块界面里。岁时（Suishi）是维护者 qianniu2009 发布的一枚 DSH Web 侧栏插件：把农历、二十四节气、常见节令和自定义纪念日收进同一面板，并在侧栏用胶囊实时显示距春节的天数。农历与节气数据在构建期由香港天文台 1901–2100 年公众年历生成，运行时不联网请求日历接口。
这是什么¶
岁时 · 中国年 · 全年节日倒计时，仓库名 dsh-suishi，在 SkillHub 目录分类为「联网工具」（插件本体为纯前端 bundle，日历数据离线随包发布）。当前 package.json 版本为 1.0.0，代码以 MIT 发布；农历/节气派生数据遵循香港天文台公开资料的使用条款。
- 目录页：https://www.skillhub.cn/plugins/qianniu2009/dsh-suishi
- 源码：https://github.com/qianniu2009/dsh-suishi
核心功能¶
下面按界面模块说明已文档化的能力。
主面板与筛选¶
从侧栏「岁时」图标或侧栏胶囊进入主面板。界面提供农历副标题，以及「全部 / 节令 / 节气」三档筛选；年轮盘展示未来一年节点、春节倒计时与少数节令标注；另有「下一个」节点卡、「我的纪念日」以及接下来一年的分组列表。
详情弹层¶
点击年轮点或列表行可打开详情：节气侧展示三候、太阳黄经、季节；节令侧展示释义、别名、习俗，以及去年与明年的对应日期。弹层可用 Esc、点击遮罩或关闭按钮退出。
自定义纪念日¶
支持按农历或公历设定、每年重复；保存后立即进入年轮、列表与提醒链路。
侧栏胶囊与设置¶
侧栏胶囊有宽、窄（rail）两态，实时显示距下一个春节的天数。设置页提供：安静提醒开关与提前天数、侧栏胶囊开关、纪念日管理。
安静提醒与跨天刷新¶
重要日子临近时，右下角每天最多出现一张不打扰的提醒卡。页面若停留过夜，会自动把「今天」推进到新的一天。
数据与运行时行为¶
农历与二十四节气离线数据由香港天文台《1901–2100 年公历与农历日期对照表》在构建期生成，数据文件为 src/parts/10-cal-data.js（约 27 KB），随插件发布。单个浏览器模块 client.js（约 187 KB）在运行时无网络请求。数据来源说明见香港天文台页面：https://www.hko.gov.hk/tc/gts/time/conversion.htm。
安装与启用¶
前置条件：本机已安装 DSH，且 dsh 命令可用。
- 将插件目录放到本机（例如从 GitHub 仓库获取后解压，或复制到 DSH 工作区），记下该目录的绝对路径。
- 在 DSH 会话中通过插件管理安装本地 bundle：
plugin_manager(action: "install_bundle", target: "<插件目录的绝对路径>")
- 刷新 DSH Web 页面。侧栏应出现「岁时」图标，侧栏底部出现「距春节 N 天」胶囊，设置面板多出「岁时」分区。
说明：插件通过 link: 方式挂到 profile；若之后移动目录，需要重新安装。仓库内已提交构建产物 client.js，安装时无需再执行 node build.mjs。
典型用法¶
安装并刷新页面后，可按下面路径操作（与 README 中的浏览器实测场景一致）。
- 打开侧栏「岁时」或点击「距春节」胶囊，进入主面板。
- 用「全部 / 节令 / 节气」切换列表与年轮展示范围。
- 在年轮或「接下来」列表中点开节点，查看节气或节令详情。
- 添加自定义纪念日（农历或公历、每年重复），确认其出现在年轮与列表中。
- 在设置中打开安静提醒并设置提前天数；临近日时在右下角查看提醒卡（每天一次）。
- 在设置中切换侧栏胶囊显示；需要窄侧栏时可使用 rail 态。
二次开发或改数据时，可在仓库根目录用 README 中的命令做构建与自检，例如：
node build.mjs # 生成 client.js
node build.mjs --check # 仅语法检查
重新生成日历数据（需先有 tools/hko 脚本环境）：
node tools/hko/fetch.mjs # 下载原始年表到 tools/hko/raw/（已存在则跳过）
node tools/hko/build-calendar.mjs # 解析并生成 src/parts/10-cal-data.js
node tests/test-lunar.mjs # 逐日比对 1901-01-01 ~ 2100-12-31
node tests/test-festivals.mjs # 24 节气 + 25 节令的文案数据校验
更完整的发布与开发流程见仓库内 DEVELOPING.md。
适用场景与注意¶
适合谁：需要在 DSH Web 里常驻查看农历、节气/节令倒计时和个人纪念日，且希望侧栏一眼看到距春节天数的开发者或日常用户。
权限与安全：插件随当前 DSH 进程在浏览器端运行；安装前应浏览源码与 LICENSE，确认接受 MIT 及天文台数据的归属说明。Host 半部分 index.js 为空实现，界面与数据均在客户端加载。
已知限制（来自 README）：年轮盘相对设计稿约有 1–2% 比例差异；卡片宽度随宿主内容区变化；安静提醒固定在右下角，可能与其他插件浮层重叠。
结尾¶
岁时把香港天文台年历衍生的离线农历/节气数据和节令文案收成一枚侧栏年历：主面板、详情、纪念日、胶囊与安静提醒形成一条完整闭环，且运行时不依赖外网拉取日历。查阅目录说明或提交 issue 可分别访问 SkillHub 插件页与 GitHub 仓库。
