@sunr/dsh-reminder 0.0.0-stage → 0.14.1

package/src/export.js

@@ -0,0 +1,111 @@
+/**
+ * 导出：JSON（备份）、Markdown（给人看）、ICS（喂给系统日历）。
+ * 导入只接受本插件导出的 JSON 结构，逐条校验后合并。
+ */
+
+import { validateItem, nextOccurrence } from './repeat.js'
+import { solarToLunar, formatLunar } from './lunar.js'
+
+const pad = (value) => String(value).padStart(2, '0')
+
+function compactDate(iso) {
+  return iso.replaceAll('-', '')
+}
+
+function icsEscape(text) {
+  return String(text).replaceAll('\\', '\\\\').replaceAll(';', '\\;').replaceAll(',', '\\,').replaceAll('\n', '\\n')
+}
+
+/** RRULE 只覆盖本插件支持的规则；单次事件不写 RRULE */
+function rruleOf(item) {
+  switch (item.repeat) {
+    case 'daily': return 'FREQ=DAILY'
+    case 'weekly': return 'FREQ=WEEKLY'
+    case 'monthly': return 'FREQ=MONTHLY'
+    case 'yearly': return 'FREQ=YEARLY'
+    case 'biweeklyOdd':
+    case 'biweeklyEven': return 'FREQ=WEEKLY;INTERVAL=2'
+    case 'customDays': return `FREQ=DAILY;INTERVAL=${Math.max(2, Number(item.every) || 2)}`
+    default: return null
+  }
+}
+
+export function toJSON(items, { today } = {}) {
+  return JSON.stringify({ version: 1, exportedAt: new Date().toISOString(), today, items }, null, 2)
+}
+
+export function toMarkdown(items, { today, timeZone = 'Asia/Shanghai' } = {}) {
+  const lines = ['# 记日 · 导出', '', `导出日期：${today}`, '', '| 日期 | 事项 | 农历 | 类型 | 重复 | 标签 |', '| --- | --- | --- | --- | --- | --- |']
+  const rows = items
+    .map((item) => ({ item, next: nextOccurrence(item, today) ?? item.date }))
+    .sort((left, right) => (left.next === right.next ? 0 : left.next < right.next ? -1 : 1))
+
+  for (const { item, next } of rows) {
+    let lunar = ''
+    if (item.calendar === 'lunar') {
+      try { lunar = formatLunar(solarToLunar(next, timeZone)) } catch { lunar = '' }
+    }
+    lines.push(`| ${next} | ${item.title} | ${lunar || '—'} | ${item.kind ?? 'todo'} | ${item.repeat ?? 'none'} | ${(item.tags ?? []).join('、') || '—'} |`)
+  }
+  return `${lines.join('\n')}\n`
+}
+
+export function toICS(items, { today, timeZone = 'Asia/Shanghai' } = {}) {
+  const stamp = new Date().toISOString().replaceAll('-', '').replaceAll(':', '').slice(0, 15) + 'Z'
+  const lines = [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'PRODID:-//dsh-reminder//记日//CN',
+    'CALSCALE:GREGORIAN',
+  ]
+
+  for (const item of items) {
+    const date = nextOccurrence(item, today) ?? item.date
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) continue
+    const next = new Date(Date.parse(date + 'T00:00:00Z') + 86_400_000).toISOString().slice(0, 10)
+    const rule = rruleOf(item)
+    lines.push('BEGIN:VEVENT')
+    lines.push(`UID:${item.id}@dsh-reminder`)
+    lines.push(`DTSTAMP:${stamp}`)
+    lines.push(`DTSTART;VALUE=DATE:${compactDate(date)}`)
+    lines.push(`DTEND;VALUE=DATE:${compactDate(next)}`)
+    lines.push(`SUMMARY:${icsEscape(item.title)}`)
+    if (item.note) lines.push(`DESCRIPTION:${icsEscape(item.note)}`)
+    if (rule) lines.push(`RRULE:${rule}`)
+    lines.push('END:VEVENT')
+  }
+
+  lines.push('END:VCALENDAR')
+  return `${lines.join('\r\n')}\r\n`
+}
+
+/** 导入：接受 { items } 或裸数组；返回 { added, skipped, errors } */
+export function parseImport(text) {
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new Error('不是合法 JSON')
+  }
+  const items = Array.isArray(parsed) ? parsed : parsed?.items
+  if (!Array.isArray(items)) throw new Error('找不到 items 数组')
+
+  const accepted = []
+  const errors = []
+  items.forEach((raw, index) => {
+    const item = {
+      ...raw,
+      id: typeof raw?.id === 'string' ? raw.id : undefined,
+      tags: Array.isArray(raw?.tags) ? raw.tags : [],
+      done: Array.isArray(raw?.done) ? raw.done : [],
+      skipped: Array.isArray(raw?.skipped) ? raw.skipped : [],
+    }
+    const problems = validateItem(item)
+    if (problems.length) errors.push(`第 ${index + 1} 条：${problems.join('；')}`)
+    else accepted.push(item)
+  })
+  return { items: accepted, errors }
+}
+
+export const EXPORT_FORMATS = { json: 'application/json', markdown: 'text/markdown', ics: 'text/calendar' }
+export { pad }

package/src/index.js

@@ -0,0 +1,296 @@
+/**
+ * 插件入口。
+ *
+ * Node 面：
+ *   · 8 个工具（含 jiri_brief 简报与 jiri_export 导出）
+ *   · 页面读写路由（list / month / add / update / delete / done / export / import / remind）
+ *   · 每日提醒（借助宿主的 schedule 服务，投递到新会话）
+ * 浏览器面：src/client.js
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { existsSync, readFileSync, renameSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { buildTools } from './tools.js'
+import { createStore, defaultStorePath, newId } from './store.js'
+import { buildRows, buildMonth } from './view.js'
+import { addItem, updateItem, removeItem, markDone, undoDone } from './service.js'
+import { toJSON, toMarkdown, toICS, parseImport, EXPORT_FORMATS } from './export.js'
+import { LUNAR_DEFAULT_TIME_ZONE, toISODate } from './lunar.js'
+import { normalizeTime, collectTimes } from './remind.js'
+
+export const name = 'dsh-reminder'
+export const inject = ['tools']
+export const ITEMS_ROUTE = '/api/dsh-reminder/items'
+
+const REMINDER_TITLE = '记日 · 每日简报'
+const reminderPrompt = (time) => `调用 jiri_reminders，time 传 "${time}"。若 hasReminders 为 false，只回复「今天没有提醒」，不要展开；否则按返回的清单原样汇报，不要额外补充建议。`
+
+
+export function apply(ctx, config = {}) {
+  const file = config.file ?? defaultStorePath()
+
+  // 包名从 dsh-jiri 改成 @sunr/dsh-reminder：数据目录跟着改，首次加载自动迁移
+  const currentDir = dirname(file)
+  const legacyDir = join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'storages', 'dsh-jiri')
+  if (!existsSync(currentDir) && existsSync(legacyDir)) {
+    try { renameSync(legacyDir, currentDir) } catch { /* 迁移失败就沿用空目录 */ }
+  }
+  const reminderFile = join(dirname(file), 'reminder.json')
+  const settingsFile = join(dirname(file), 'settings.json')
+  const store = createStore(file)
+
+  const settings = { timeZone: config.timeZone ?? LUNAR_DEFAULT_TIME_ZONE, reminderTime: '09:00' }
+  try {
+    const saved = JSON.parse(readFileSync(settingsFile, 'utf8'))
+    if (typeof saved?.timeZone === 'string') settings.timeZone = saved.timeZone
+    if (/^([01]\d|2[0-3]):[0-5]\d$/.test(saved?.reminderTime ?? '')) settings.reminderTime = saved.reminderTime
+  } catch { /* 没有设置文件就用默认 */ }
+  const timeZone = () => settings.timeZone
+
+  for (const tool of buildTools({ defineTool, store, timeZone, reminderTime: () => settings.reminderTime })) ctx.tools.register(tool)
+
+  const today = () => toISODate(new Date(), timeZone())
+
+  async function readReminder() {
+    try { return JSON.parse(await readFile(reminderFile, 'utf8')) } catch { return null }
+  }
+
+  async function writeReminder(value) {
+    await mkdir(dirname(reminderFile), { recursive: true })
+    await writeFile(reminderFile, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+  }
+
+  async function clearReminder() {
+    try { await unlink(reminderFile) } catch { /* 没有就算了 */ }
+  }
+
+  // 宿主可能没装 schedule（headless 等），拿不到就降级
+  let schedule = null
+  ctx.inject(['schedule'], (scope) => { schedule = scope.get('schedule') })
+
+  /** 某条任务用的 RRULE：每天在该时刻触发 */
+  function ruleFor(time) {
+    const [hour, minute] = time.split(':')
+    return `DTSTART;TZID=${settings.timeZone}:${today().replaceAll('-', '')}T${hour}${minute}00\nRRULE:FREQ=DAILY`
+  }
+
+  async function createSchedule(time) {
+    const created = await schedule.create({
+      title: REMINDER_TITLE,
+      prompt: reminderPrompt(time),
+      timing: { kind: 'rrule', rrule: ruleFor(time) },
+      target: { kind: 'new_once' },
+    })
+    const id = created?.id ?? created?.task?.id ?? created?.value?.id ?? await findReminderId(time)
+    if (!id) throw new Error(`任务创建成功但拿不到 id（${time}）`)
+    return id
+  }
+
+  async function findReminderId(time) {
+    try {
+      const listed = await schedule.list({ active: true })
+      const rows = Array.isArray(listed) ? listed : (listed?.items ?? listed?.tasks ?? [])
+      const hit = rows.find((row) => row?.title === REMINDER_TITLE && (time === undefined || String(row?.prompt ?? '').includes(`"${time}"`)))
+      return hit?.id ?? null
+    } catch { return null }
+  }
+
+  /** 旧版只存 { id }，迁移成 { times: { 'HH:mm': id } } */
+  function reminderRecord(raw) {
+    if (!raw?.id && !raw?.times) return null
+    if (raw.times) return raw
+    return { times: { [normalizeTime(raw.time) ?? settings.reminderTime]: raw.id }, createdAt: raw.createdAt }
+  }
+
+  /**
+   * 让「已启用的时间点」与实际任务对齐：缺的建、多的删。
+   * 记录增删改、全局时间变更后都要调一次。
+   */
+  async function syncSchedules() {
+    const record = reminderRecord(await readReminder())
+    if (!record || !schedule) return record
+
+    const items = await store.list()
+    const desired = collectTimes(items, settings.reminderTime)
+    const times = { ...record.times }
+
+    for (const time of Object.keys(times)) {
+      if (desired.includes(time)) continue
+      try { await schedule.edit({ id: times[time], action: 'delete' }) } catch { /* 可能已被手工删除 */ }
+      delete times[time]
+    }
+    for (const time of desired) {
+      if (times[time]) continue
+      times[time] = await createSchedule(time)
+    }
+
+    const next = { times, createdAt: record.createdAt ?? new Date().toISOString(), timeZone: settings.timeZone }
+    await writeReminder(next)
+    return next
+  }
+
+  ctx.inject(['connection'], (scope) => {
+    const register = scope.get('connection')?.fetch?.register
+    if (typeof register !== 'function') return
+
+    const json = (value, status = 200) => Response.json(value, {
+      status,
+      headers: { 'cache-control': 'no-store' },
+    })
+
+    scope.effect(() => register({
+      path: ITEMS_ROUTE,
+      methods: ['POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        let body = {}
+        try {
+          body = await request.json()
+        } catch {
+          return json({ ok: false, error: { code: 'bad-request', message: 'body 不是 JSON' } }, 400)
+        }
+
+        const action = typeof body?.action === 'string' ? body.action : 'list'
+        // 必须声明在 try 外：最终 return 在 catch 之后
+        let extra = {}
+        try {
+          if (action === 'month') {
+            const year = Number(body.year)
+            const month = Number(body.month)
+            if (!(year >= 1900 && year <= 2200) || !(month >= 1 && month <= 12)) {
+              return json({ ok: false, error: { code: 'bad-month', message: 'year/month 不合法' } }, 400)
+            }
+            const items = await store.list()
+            return json({ ok: true, today: today(), month: buildMonth(items, year, month, today()) })
+          }
+
+          switch (action) {
+            case 'list':
+              break
+            case 'add':
+              await addItem(store, body.item ?? {}, { timeZone: timeZone(), today: today() })
+              break
+            case 'update':
+              await updateItem(store, String(body.id ?? ''), body.fields ?? {})
+              break
+            case 'delete':
+              extra = { removed: await removeItem(store, String(body.id ?? '')) }
+              break
+            case 'undone':
+              await undoDone(store, String(body.id ?? ''), String(body.occurrence ?? ''))
+              break
+            case 'restore': {
+              const item = body.item
+              if (!item || typeof item.id !== 'string') {
+                return json({ ok: false, error: { code: 'bad-item', message: '缺少要恢复的记录' } }, 400)
+              }
+              if (!(await store.get(item.id))) await store.insert(item)
+              break
+            }
+            case 'done':
+              await markDone(store, String(body.id ?? ''), body.occurrence, today())
+              break
+            case 'export': {
+              const format = ['json', 'markdown', 'ics'].includes(body.format) ? body.format : 'json'
+              const items = await store.list()
+              const text = format === 'markdown'
+                ? toMarkdown(items, { today: today(), timeZone: timeZone() })
+                : format === 'ics'
+                  ? toICS(items, { today: today(), timeZone: timeZone() })
+                  : toJSON(items, { today: today() })
+              const extension = format === 'ics' ? 'ics' : format === 'markdown' ? 'md' : 'json'
+              return json({
+                ok: true,
+                filename: `jiri-${today()}.${extension}`,
+                mime: EXPORT_FORMATS[format] ?? 'text/plain',
+                data: text,
+              })
+            }
+            case 'import': {
+              const parsed = parseImport(String(body.data ?? ''))
+              const existing = new Set((await store.list()).map((item) => item.id))
+              let added = 0
+              let skipped = 0
+              for (const item of parsed.items) {
+                if (item.id && existing.has(item.id)) { skipped += 1; continue }
+                await store.insert({
+                  ...item,
+                  id: item.id ?? newId(),
+                  createdAt: item.createdAt ?? new Date().toISOString(),
+                  updatedAt: new Date().toISOString(),
+                })
+                added += 1
+              }
+              await syncSchedules()
+              return json({ ok: true, added, skipped, errors: parsed.errors, rows: buildRows(await store.list(), today()) })
+            }
+            case 'settings.get':
+              return json({ ok: true, ...settings, today: today() })
+            case 'settings.set': {
+              const nextZone = body.timeZone === undefined ? settings.timeZone : String(body.timeZone)
+              const nextTime = body.reminderTime === undefined ? settings.reminderTime : String(body.reminderTime)
+              try {
+                new Intl.DateTimeFormat('en-US', { timeZone: nextZone })
+              } catch {
+                return json({ ok: false, error: { code: 'bad-zone', message: `无效时区：${nextZone}` } }, 400)
+              }
+              if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(nextTime)) {
+                return json({ ok: false, error: { code: 'bad-time', message: `时间格式应为 HH:mm：${nextTime}` } }, 400)
+              }
+
+              const changedTime = nextTime !== settings.reminderTime || nextZone !== settings.timeZone
+              settings.timeZone = nextZone
+              settings.reminderTime = nextTime
+              await mkdir(dirname(settingsFile), { recursive: true })
+              await writeFile(settingsFile, `${JSON.stringify({ ...settings }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+
+              // 时间或时区变了：让任务跟着对齐（会重建 RRULE）
+              let reminder = await readReminder()
+              if (changedTime) reminder = await syncSchedules()
+
+              return json({ ok: true, ...settings, today: today(), reminder })
+            }
+            case 'remind.status': {
+              const reminder = reminderRecord(await readReminder())
+              return json({ ok: true, reminder, supported: Boolean(schedule) })
+            }
+            case 'remind.on': {
+              if (!schedule) {
+                return json({ ok: false, error: { code: 'no-schedule', message: '当前 profile 没有 schedule 服务' } }, 400)
+              }
+              const existing = reminderRecord(await readReminder())
+              if (existing) return json({ ok: true, reminder: existing })
+
+              await writeReminder({ times: {}, createdAt: new Date().toISOString() })
+              const record = await syncSchedules()
+              return json({ ok: true, reminder: record })
+            }
+            case 'remind.off': {
+              const existing = reminderRecord(await readReminder())
+              if (existing && schedule) {
+                for (const id of Object.values(existing.times)) {
+                  try { await schedule.edit({ id, action: 'delete' }) } catch { /* 可能已被手工删除 */ }
+                }
+              }
+              await clearReminder()
+              return json({ ok: true, reminder: null })
+            }
+            default:
+              return json({ ok: false, error: { code: 'bad-action', message: `未知动作：${action}` } }, 400)
+          }
+        } catch (error) {
+          return json({ ok: false, error: { code: 'dsh-reminder', message: String(error?.message ?? error) } }, 400)
+        }
+
+        if (['add', 'update', 'delete', 'done', 'undone', 'restore'].includes(action)) {
+          await syncSchedules()
+        }
+        return json({ ok: true, today: today(), rows: buildRows(await store.list(), today()), ...extra })
+      },
+    }, 'dsh-reminder: items'), 'dsh-reminder: items route')
+  })
+}

package/src/lunar.js

@@ -0,0 +1,180 @@
+/**
+ * 农历换算：基于 Node 内置 Intl 的中国历，零依赖。
+ *
+ * 只做记日真正需要的事：
+ *   1. 公历 → 农历（月 / 日 / 是否闰月）
+ *   2. 农历月日 → 未来最近一次对应的公历日期（Intl 没有反向 API，只能逐日扫描）
+ *   3. 人类可读的「农历九月廿九」格式化
+ *
+ * 三个已知边界，与 iOS 端 Shared/Core/LunarCalendar.swift 的结论一致：
+ *   · Intl 只给「公历 → 农历」，反查必须扫描；
+ *   · 闰月以「闰」前缀出现（en 下是 "bis"），必须单独建模；
+ *   · 农历腊月可能只有廿九，没有三十 —— 扫描不到时由调用方决定降级策略。
+ */
+
+const DEFAULT_TIME_ZONE = 'Asia/Shanghai'
+
+/** 一月最多 30 天，覆盖一个农历年的最长扫描范围 */
+const MAX_SCAN_DAYS = 400
+
+const CN_DIGITS = { 一: 1, 二: 2, 三: 3, 四: 4, 五: 5, 六: 6, 七: 7, 八: 8, 九: 9, 十: 10 }
+
+const MONTH_NAMES = new Map([
+  ['正月', 1], ['一月', 1],
+  ['二月', 2], ['三月', 3], ['四月', 4], ['五月', 5], ['六月', 6],
+  ['七月', 7], ['八月', 8], ['九月', 9], ['十月', 10],
+  ['冬月', 11], ['十一月', 11],
+  ['腊月', 12], ['十二月', 12],
+])
+
+const DAY_NAMES = ['初一', '初二', '初三', '初四', '初五', '初六', '初七', '初八', '初九', '初十',
+  '十一', '十二', '十三', '十四', '十五', '十六', '十七', '十八', '十九', '二十',
+  '廿一', '廿二', '廿三', '廿四', '廿五', '廿六', '廿七', '廿八', '廿九', '三十']
+
+const formatters = new Map()
+
+function formatterFor(timeZone) {
+  let formatter = formatters.get(timeZone)
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat('zh-CN-u-ca-chinese', {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+      timeZone,
+    })
+    formatters.set(timeZone, formatter)
+  }
+  return formatter
+}
+
+/** 解析 YYYY-MM-DD；也接受 Date。统一取当天 12:00 UTC，避开时区把日期推前/推后一天。 */
+export function toDate(value) {
+  if (value instanceof Date) return value
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(value ?? '').trim())
+  if (!match) throw new Error(`日期格式应为 YYYY-MM-DD，收到：${value}`)
+  const [, y, m, d] = match
+  const date = new Date(Date.UTC(Number(y), Number(m) - 1, Number(d), 12))
+  if (Number.isNaN(date.getTime())) throw new Error(`无效日期：${value}`)
+  return date
+}
+
+/** Date → YYYY-MM-DD（按指定时区取「那一天」） */
+export function toISODate(value, timeZone = DEFAULT_TIME_ZONE) {
+  const date = value instanceof Date ? value : toDate(value)
+  const parts = new Intl.DateTimeFormat('en-CA', {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    timeZone,
+  }).formatToParts(date)
+  const pick = (type) => parts.find((part) => part.type === type)?.value
+  return `${pick('year')}-${pick('month')}-${pick('day')}`
+}
+
+/** 今天（指定时区）的 YYYY-MM-DD */
+export function today(timeZone = DEFAULT_TIME_ZONE) {
+  return toISODate(new Date(), timeZone)
+}
+
+function parseDay(raw) {
+  if (/^\d+$/.test(raw)) return Number(raw)
+  if (raw === '二十') return 20
+  if (raw === '三十') return 30
+  if (raw.startsWith('廿')) return 20 + (CN_DIGITS[raw[1]] ?? NaN)
+  if (raw.startsWith('初')) return CN_DIGITS[raw[1]] ?? NaN
+  if (raw === '十') return 10
+  if (raw.startsWith('十')) return 10 + (CN_DIGITS[raw[1]] ?? NaN)
+  return NaN
+}
+
+/**
+ * 公历 → 农历。
+ * @returns {{ year: number, month: number, day: number, leap: boolean,
+ *             monthName: string, ganzhi: string }}
+ *   year 是农历年所属的公历年（Intl 的 relatedYear），不是 60 年一轮的序号。
+ */
+export function solarToLunar(value, timeZone = DEFAULT_TIME_ZONE) {
+  const parts = formatterFor(timeZone).formatToParts(toDate(value))
+  const pick = (type) => parts.find((part) => part.type === type)?.value
+
+  const monthRaw = pick('month') ?? ''
+  const leap = monthRaw.startsWith('闰')
+  const monthName = leap ? monthRaw.slice(1) : monthRaw
+  const month = MONTH_NAMES.get(monthName)
+  const day = parseDay(pick('day') ?? '')
+
+  if (!month || !Number.isFinite(day)) {
+    throw new Error(`无法解析农历：${JSON.stringify(parts.map((p) => [p.type, p.value]))}`)
+  }
+
+  return {
+    year: Number(pick('relatedYear')),
+    month,
+    day,
+    leap,
+    monthName,
+    ganzhi: pick('yearName') ?? '',
+  }
+}
+
+/** 1 → 初一，21 → 廿一……30 → 三十 */
+export function dayName(day) {
+  return DAY_NAMES[day - 1] ?? String(day)
+}
+
+/** { month: 9, day: 29, leap: false } → "农历九月廿九" */
+export function formatLunar(lunar, { withYear = false } = {}) {
+  const prefix = lunar.leap ? '闰' : ''
+  const month = lunar.monthName ?? `${lunar.month}月`
+  const body = `${prefix}${month}${dayName(lunar.day)}`
+  return withYear && lunar.year ? `${lunar.year}年${body}` : `农历${body}`
+}
+
+/**
+ * 从 from 起（含当天）向后扫描，找最近一次指定农历月/日。
+ * 找不到（例如要求「腊月三十」而那年只有廿九）返回 null，由调用方降级。
+ */
+export function nextLunarOccurrence(
+  { month, day, leap = false },
+  from,
+  { timeZone = DEFAULT_TIME_ZONE, maxDays = MAX_SCAN_DAYS } = {},
+) {
+  const start = toDate(from)
+  for (let offset = 0; offset <= maxDays; offset += 1) {
+    const cursor = new Date(start.getTime() + offset * 86_400_000)
+    const lunar = solarToLunar(cursor, timeZone)
+    if (lunar.month === month && lunar.day === day && lunar.leap === leap) {
+      return { date: toISODate(cursor, timeZone), lunar }
+    }
+  }
+  return null
+}
+
+/** 某个农历月在该农历年里的天数（30 / 29），用于「腊月三十」这类边界降级 */
+export function lunarMonthLength({ year, month, leap = false }, timeZone = DEFAULT_TIME_ZONE) {
+  // 春节落在 1/21–2/20 之间：先从 1/1 找到该农历年的正月初一，避免把上一年的腊月算进来
+  const scanStart = toDate(`${year}-01-01`)
+  let newYear = null
+  for (let offset = 0; offset <= 60; offset += 1) {
+    const date = new Date(scanStart.getTime() + offset * 86_400_000)
+    const lunar = solarToLunar(date, timeZone)
+    if (lunar.year === year && lunar.month === 1 && lunar.day === 1 && !lunar.leap) {
+      newYear = date
+      break
+    }
+  }
+  if (!newYear) return null
+
+  let best = 0
+  // 农历平年 354 天、闰年 384 天，必须扫满 400 天才能覆盖到腊月
+  for (let offset = 0; offset <= MAX_SCAN_DAYS; offset += 1) {
+    const date = new Date(newYear.getTime() + offset * 86_400_000)
+    const lunar = solarToLunar(date, timeZone)
+    if (lunar.year === year && lunar.month === month && lunar.leap === leap) {
+      best = Math.max(best, lunar.day)
+    }
+  }
+  return best || null
+}
+
+export const LUNAR_DEFAULT_TIME_ZONE = DEFAULT_TIME_ZONE

package/src/remind.js

@@ -0,0 +1,40 @@
+/**
+ * 提醒时间的纯逻辑：每条记录可以有自己的 HH:mm，缺省跟随全局设置。
+ *
+ * 投递机制：每个不同的时间点对应一条 schedule 任务，任务里把 time 传给
+ * jiri_reminders，工具再按「这条记录实际归属的时间」过滤。
+ */
+
+const TIME_PATTERN = /^([01]\d|2[0-3]):[0-5]\d$/
+
+/** '9:00' / '09:00' / 空 → 'HH:mm' 或 null */
+export function normalizeTime(value) {
+  if (value === undefined || value === null) return null
+  const text = String(value).trim()
+  if (!text) return null
+  const match = /^(\d{1,2}):(\d{2})$/.exec(text)
+  if (!match) return null
+  const hour = Number(match[1])
+  const minute = Number(match[2])
+  if (hour > 23 || minute > 59) return null
+  return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`
+}
+
+/** 这条记录实际用哪个时间：自己的优先，否则全局 */
+export function effectiveTime(item, globalTime = '09:00') {
+  return normalizeTime(item?.remindAt) ?? normalizeTime(globalTime) ?? '09:00'
+}
+
+/**
+ * 需要哪些时间点的定时任务：只算「设了提前提醒」的记录。
+ * @returns {string[]} 升序去重的 HH:mm
+ */
+export function collectTimes(items, globalTime = '09:00') {
+  const times = new Set([normalizeTime(globalTime) ?? '09:00'])
+  for (const item of items) {
+    const points = Array.isArray(item?.advance) ? item.advance : []
+    if (!points.length) continue
+    times.add(effectiveTime(item, globalTime))
+  }
+  return [...times].sort()
+}