日历日记 liwangzimo/dsh-calendar-diary

dsh-calendar-diary（日历日记）

一个纯记事本式的 DSH 插件：一天一条，写在你自己的一个 .xlsx 里。侧栏一个月历面板（一次显示 10 周）。

没有提醒、没有通知、没有标签、没有搜索、没有云同步，也不联动官方「自动化任务」。除了你指定的那个 .xlsx 和插件自己的配置目录，它不写别的地方，也不联网。

功能

- 侧栏「日历日记」：月历网格一次显示 10 周（10 行 × 7 天，周一开头），格子里直接显示当天内容（超出一格的部分裁切，鼠标悬停看全文）；有记录的日子带标记；可左右切月、回到今天；点某天打开编辑框写 / 改 / 删（保存、Ctrl+Enter、删除本条）。
- 数据文件一栏：显示当前数据文件路径，「更改…」可换（只换指向，不搬数据）。
- 导入：选 .xlsx / .xls → 先预览（来源、行数、日期范围、新增 / 冲突 / 未变 / 跳过，冲突逐条列出）→ 选冲突策略（默认保留现有）→ 确认后才写盘，写前自动备份。
- 导出：范围「全部 / 某年 / 某月」→ 写出同构的 .xlsx，只写新文件、绝不动数据文件；目标若就是当前数据文件本身会被拒绝（导出不备份，覆盖等于把范围外的天数一次删光）。

安装

需要 DSH（桌面版或网页版均可；本插件同时有宿主半与客户端半）。dsh plugin 会把剩余参数原样转发给 profile 目录里的 pnpm，所以 --profile 是它自己的选项，必须写在 add 之前（写成 plugin add … --profile desktop 会报 required option '--profile <name>' not specified）。

方式一：从 GitHub

& '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd' plugin --profile <profile> add "github:liwangzimo/dsh-calendar-diary" --config.minimumReleaseAge=0

方式二：克隆到本地后按目录安装（改代码即生效，但要重启）

git clone https://github.com/liwangzimo/dsh-calendar-diary.git
& '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd' plugin --profile <profile> add "link:<克隆下来的目录>" --config.minimumReleaseAge=0

--config.minimumReleaseAge=0 只放宽这一次命令的供应链策略（DSH 的 profile 默认拒绝"太新"的包）。不加可能因 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION 失败。

装完必须再做一步：注册 bundle

dsh plugin add 只加依赖。还要在 profile 的 package.json 里把插件登记进 dsh.profile.bundles，即在这个数组里加一行字符串：

"dsh": {
"profile": {
"bundles": [
"…", "dsh-calendar-diary" ] } }

只装依赖不登记 bundle 是不会加载的。 两处都改完后，完全退出并重开 DSH——本插件不支持热更新（刷新页面、关窗重开都无效，客户端代码是在启动时打包进图的）。

重启后确认生效：侧栏出现「日历日记」面板，或打开 http://<DSH 地址>/dsh-calendar-diary/state 看到 JSON。

回滚

& '<DSH 安装目录>\resources\runtime\cli\bin\dsh.cmd' plugin --profile <profile> remove dsh-calendar-diary

再把 dsh.profile.bundles 里那行删掉，重启。

数据格式

数据文件是一个 .xlsx，默认位置是你用户目录下的 .dsh/dsh-calendar-diary/diary.xlsx（第一次运行时创建；面板里可改）：

| 项 | 值 |
| 工作表 | DesktopCal |
| A 列 | 整数 Excel 日期序列号（1900 系统），单元格格式固定 m/d/yy（显示成 11/25/26） |
| B 列 | 自由文本，可多行（\r\n），时间直接写在文本里 |
| 行序 | 日期降序；一天最多一行 |

这个形状与桌面日历软件 DesktopCal 导出的两列表一致，所以老数据可以直接导入。

为什么数据文件只写 .xlsx 而不是 .xls：把上千行写回 .xls 会静默截断长度超过 255 字符的单元格，不报错、不提示。写 .xlsx 实测 0 处值差异、0 处格式差异、0 处文本差异。所以导入收 .xls，但数据文件只写 .xlsx。

HTTP 路由（宿主半注册，客户端同源 fetch）

客户端不依赖任何会话或命令通道，只用相对路径 fetch(..., { cache: 'no-store' }) 调这些路由：

| 方法 | 路径 | 说明 |
| GET | /dsh-calendar-diary/state | 数据文件路径、是否存在 / 可写、总行数、有记录的月份（降序）、今天 |
| GET | /dsh-calendar-diary/entries?month=YYYY-MM | 该月条目 [{ date, serial, text }] |
| POST | /dsh-calendar-diary/entries | { date, text } 写入 / 覆盖一天；text:'' 置空但保留行 |
| POST | /dsh-calendar-diary/entries/remove | { date } 删掉该行 |
| POST | /dsh-calendar-diary/path | { dataPath } 换数据文件（校验是可用日记、拒绝 .xls） |
| POST | /dsh-calendar-diary/pick-dir | 原生文件夹对话框（不可用时返回 {ok:false,error}，界面回退到手输） |
| POST | /dsh-calendar-diary/list-files | { dir } 列出候选 .xlsx / .xls |
| POST | /dsh-calendar-diary/import/scan | 只读预览导入，不写盘 |
| POST | /dsh-calendar-diary/import/apply | { sourcePath, policy } 执行导入（先备份再原子写） |
| POST | /dsh-calendar-diary/export | { scope, value, outPath } 导出新 .xlsx |

错误一律返回 JSON：{ ok:false, error:'' } + 4xx/5xx。方法不匹配返回 405，并在 JSON 里给出 allow。

文件

| 文件 | 作用 |
| index.js | 宿主半：注册上面 10 条路由，持有全部文件读写 |
| diary-io.js | I/O 层：读 / 原子写 / 备份 / 导入 / 导出（只用 node:fs + xlsx，不碰 ctx，所以能在纯 Node 里验证） |
| diary-store.js | 纯数据层：序列号↔日期、解析、排序、upsert / remove、导入合并策略（无 I/O、无时钟） |
| client.js | 浏览器半：月历面板 + 日编辑框 + 导入导出 |
| locale/zh.json、locale/en.json | 界面文案（键集合两边完全一致） |
| cordis.patch.yml | loader 补丁：一行把宿主半挂上（package.json 的 dsh.bundle.patch 指向它） |
| tests/diary-store.test.mjs | 数据层单测（含用真实 DesktopCal 导出测出的序列号锚点） |
| tools/migrate.mjs | 从 .xls 迁移到 .xlsx 并做 0 差异校验的一次性工具 |

开发与自测

node --test tests/diary-store.test.mjs # 数据层单测（纯函数，无 I/O）
node tools/migrate.mjs --help # 迁移工具用法

宿主半的路由可以用假 req/res 在纯 Node 里驱动，不需要启动 DSH。

已知边界（都是有意的，不是待办）

- 一天只保留一行。如果数据文件里同一天被人手工塞了两行，读取时按「首行优先」取一行；下一次任何写入都会按这个结果重写整个文件，也就是那一行会从正式文件里消失。它仍在那一次写入生成的 .bak-<时间戳> 里，所以可恢复。本插件自己不会产生重复行。
- 「必须先预览再导入」是客户端门槛。宿主半按设计无状态：/import/apply 单独调用也会执行（但不支持按天逐个决策）。这条防线在 UI 上，不在协议上。
- 相对路径按插件主目录（~/.dsh/dsh-calendar-diary）解析，不按宿主进程的工作目录——否则同一个相对路径会随启动方式指向不同地方。
- 写入失败不会留下垃圾：临时文件在失败时被清掉，数据文件本身只在最后一步 rename 时才会被替换，所以「写失败」永远不等于「文件损坏」。失败时仍可能已经生成了一份 .bak-。
- 两位数年份的文本日期（如 11/25/26）一律按 20xx 解释，与 Excel 在这段日期范围内的行为一致。
- 每个进程首次写入前做一次备份（diary.xlsx.bak-<yyyyMMdd-HHmmss>），同一次运行内不重复备份。
- 10 周视图下格子会偏小：面板越窄（尤其编辑框并排时）每格越窄，「格子里显示内容」只是提示，全文以悬停提示或点开编辑框为准。

许可

MIT