dsh-calendar

3. 首次使用（30 秒）

1. 打开 DSH 右侧栏，点「+」里的 日历，或点会话 header 右侧的 日历图标
2. 面板会显示 连接 Obsidian：
   • 点 「自动寻找」：插件在常见位置（Documents、Desktop、各盘根目录等，最多下探两层）找带 .obsidian 的目录， 读出它的 Daily Notes 文件夹（.obsidian/daily-notes.json）并作为建议值填给你
   • 或者手动填你的日记文件夹路径（Obsidian 里存 2026-09-19.md 这类文件的目录）
3. 点 「保存并开始使用」：立刻生效，不用重启

保存后写入 $DSH_HOME/dsh-calendar/config.json（DSH_HOME 默认 ~/.dsh）。想改随时改这个文件，或再进一次向导。

4. 让 AI 帮你自动配置（预留接口）

本插件自带给 AI/命令行的接口，AI 不需要预先知道你的 vault 在哪，就能自己找到并配好。

把下面这段直接发给你在 DSH 里的 AI：

用 dsh-calendar 插件自带的安装接口帮我配好 Obsidian：

1. node /scripts/setup.mjs --detect --json 找出本机 vault；
2. 从候选里选一个（通常用它的 root 字段），执行 node /scripts/setup.mjs --root ""；
3. curl "http://127.0.0.1:3080/dsh-calendar/tasks?refresh=1" 自检，确认 root 与 notes 计数正常；
4. 告诉我结果（配到了哪个文件夹、读到几篇日记）。

命令行接口（scripts/setup.mjs，与面板向导共用同一套实现，不需要 DSH 在运行）：

node scripts/setup.mjs --print                # 打印当前配置（含 DSH 家目录来源）
node scripts/setup.mjs --detect               # 人看的候选列表
node scripts/setup.mjs --detect --json        # AI 解析用的 JSON
node scripts/setup.mjs --root ""        # 配为主数据源
node scripts/setup.mjs --print --dsh-home ""   # 显式指定 DSH 家目录

关于 DSH_HOME：CLI 用它决定配置文件写哪儿（没设就兜底 ~/.dsh，此时会打印一条 ⚠ 提醒）。 如果你的 shell / AI 沙箱里没有这个环境变量，请加 --dsh-home ""； 或者更稳的办法：curl http://127.0.0.1:3080/dsh-calendar/status 看里面的 configPath —— 正在运行的插件给出的路径永远是最准的（它以运行进程的环境为准）。

--detect --json 的返回形状：

{
  "ok": true,
  "count": 1,
  "detected": [
    {
      "name": "Obsidian Vault",
      "vault": "C:\\Users\\me\\Documents\\Obsidian Vault",
      "root": "C:\\Users\\me\\Documents\\Obsidian Vault\\日记",
      "dailyFolder": "日记",
      "hasDailyConfig": true,
      "dateFormat": "YYYY-MM-DD",
      "dayPlanner": { "installed": true, "timelineDateFormat": "YYYY-MM-DD", "startHour": 6 },
      "calendar": { "installed": true, "wordsPerDot": 250 }
    }
  ]
}

HTTP 接口（插件运行中可用；写操作需要 x-dsh-calendar: write 头且来源为本机）：

方法	路径	用途
GET	/dsh-calendar/setup	配置状态；?detect=1 时附候选列表
POST	/dsh-calendar/setup	保存日记文件夹（{ "root": "..." }）
GET	/dsh-calendar/tasks	任务 + 日记 JSON（?refresh=1 强刷）
POST	/dsh-calendar/tasks/toggle	切换完成状态
POST	/dsh-calendar/tasks/update	改任务内容
POST	/dsh-calendar/tasks/schedule	改/清除时间块
POST	/dsh-calendar/tasks/add	新建待办
POST	/dsh-calendar/notes/create	新建某天日记
GET	/dsh-calendar/status	自检：路由、配置、client 模块与真实加载 URL

7. 配置项（$DSH_HOME/dsh-calendar/config.json）

{
  "roots": ["C:\\Users\\me\\Documents\\Obsidian Vault\\日记"],
  "allowAnyRoot": false,
  "autoOpen": true,
  "write": { "enabled": true, "appendDoneDate": true },
  "create": { "enabled": true, "titleTemplate": "# {date} {weekday}" },
  "dayPlanner": { "heading": "Day planner", "headingLevel": 1, "startHour": 6,
                  "defaultDurationMinutes": 30, "minimalDurationMinutes": 10,
                  "snapStepMinutes": 10, "showNow": true, "showNext": true },
  "calendar": { "wordsPerDot": 250, "maxNoteDots": 2 }
}

键	作用
roots	数据源，第一个是主数据源；最多保留 3 个（新加的排最前）
allowAnyRoot	是否允许 ?root= 传任意绝对路径（默认 false：只认 roots 与 DSH 已注册工作区）
autoOpen	进入会话时自动展开日历 tab（默认 true；手动关掉后同一会话不会弹回来）
write.enabled	关掉后完全只读
write.appendDoneDate	标完成时是否追加 ✅ YYYY-MM-DD（关掉则只翻 [ ]↔[x]）
create	是否允许在 DSH 里新建日记 / 待办
dayPlanner.*	与 Obsidian 的 Day Planner 对齐（标题、起始小时、默认时长…）
calendar.wordsPerDot	与 Obsidian 的 Calendar 对齐（每多少字一个点）