@ilaomianyang/dsh-memory-graph 0.11.0 → 0.12.0

package/src/auto.js

@@ -32,14 +32,30 @@ export function inQuietHours(window, now) {
  * Should this tick run a distillation? Pure, so the rules are readable in one
  * place and testable without a clock.
  *
+ * Three rules, in the order they are asked:
+ *
+ * 1. **catch-up** — a pile bigger than one batch is a queue, not a schedule. It
+ *    runs every `catchUpEveryMinutes` until the pile is smaller than a batch, and
+ *    stops for the day at `maxBatchesPerDay`. This is the rule that lets an
+ *    imported history drain itself overnight without a person pressing anything,
+ *    and the daily cap is what keeps it from spending without a ceiling.
+ * 2. **schedule** — `everyMinutes` since the last run (or since the clock
+ *    started).
+ * 3. **threshold** — `minEpisodes` waiting.
+ *
+ * The gap (`minGapMinutes`) sits between 1 and 2/3: catch-up measures its own
+ * cadence, while the other two answers still respect the gap a person configured.
+ *
  * @param {object} input
  * @param {object} input.auto        the `auto` config group
  * @param {number} input.now         epoch ms
  * @param {number|null} input.lastAttemptAt  epoch ms of the previous attempt
  * @param {number} input.pending     undistilled episodes waiting
+ * @param {number} [input.batchSize] episodes one run distils
+ * @param {number} [input.batchesToday] automatic batches already run today
  * @returns {{due: boolean, rule: string|null, reason: string}}
  */
-export function autoDecision({ auto, now, lastAttemptAt = null, startedAt = null, pending = 0 }) {
+export function autoDecision({ auto, now, lastAttemptAt = null, startedAt = null, pending = 0, batchSize = 40, batchesToday = 0 }) {
   if (auto?.enabled !== true) return { due: false, rule: null, reason: 'auto is off' }
   if (pending <= 0) return { due: false, rule: null, reason: 'nothing to distill' }
   if (inQuietHours(auto.quietHours, now)) return { due: false, rule: null, reason: 'quiet hours' }
@@ -55,6 +71,24 @@ export function autoDecision({ auto, now, lastAttemptAt = null, startedAt = null
   const clock = lastAttemptAt ?? startedAt
   const sinceClock = clock === null ? null : now - clock
 
+  // Catch-up first: its cadence is its own, and it is the only rule that can be
+  // due while the gap configured for the others has not elapsed.
+  if (auto.catchUp === true && pending >= Math.max(1, batchSize)) {
+    const cap = auto.maxBatchesPerDay ?? 0
+    if (cap > 0 && batchesToday >= cap) {
+      return { due: false, rule: null, reason: `今日已跑 ${batchesToday} 批，达到上限 ${cap} · daily batch cap reached` }
+    }
+    const every = Math.max(1, auto.catchUpEveryMinutes ?? 10) * MINUTE
+    if (sinceRun === null || sinceRun >= every) {
+      return {
+        due: true,
+        rule: 'catch-up',
+        reason: `还有 ${pending} 条待蒸馏，今天第 ${batchesToday + 1} 批${cap > 0 ? ` / 上限 ${cap}` : ''}`,
+      }
+    }
+    return { due: false, rule: null, reason: `距上一批不到 ${auto.catchUpEveryMinutes ?? 10} 分钟 · catch-up gap` }
+  }
+
   const gap = (auto.minGapMinutes ?? 0) * MINUTE
   if (gap > 0 && sinceRun !== null && sinceRun < gap) {
     return { due: false, rule: null, reason: 'the gap between runs has not elapsed' }
@@ -85,6 +119,8 @@ export function createAutoDistiller({ cfg, vault, run, log = () => {}, now = ()
   let lastAttemptAt = null
   let startedAt = null
   let lastReport = null
+  let day = null
+  let batchesToday = 0
 
   async function loadState() {
     if (loaded) return
@@ -95,20 +131,34 @@ export function createAutoDistiller({ cfg, vault, run, log = () => {}, now = ()
       const start = Number(state?.startedAt)
       lastAttemptAt = Number.isFinite(attempt) && attempt > 0 ? attempt : null
       startedAt = Number.isFinite(start) && start > 0 ? start : null
+      day = typeof state?.batchDay === 'string' ? state.batchDay : null
+      const count = Number(state?.batchesToday)
+      batchesToday = Number.isFinite(count) && count > 0 ? count : 0
     } catch (error) {
       log('warn', `自动蒸馏：读不了 .auto-state.json · auto: could not read .auto-state.json: ${error?.message ?? error}`)
     }
   }
 
+  /** Today's local date, the key the daily batch cap resets on. */
+  function todayKey(at) {
+    const date = new Date(at)
+    const pad = (value) => String(Math.abs(value)).padStart(2, '0')
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`
+  }
+
   /** One decision, and at most one run. Returns what it decided, for the tests. */
   async function tick() {
     const auto = cfg.auto ?? {}
     await loadState()
     if (auto.enabled !== true) return { due: false, rule: null, reason: 'auto is off', ran: false }
 
+    const batchSize = Math.max(1, cfg.extractor?.maxEpisodesPerRun ?? 40)
     let pending = 0
     try {
-      const batch = await vault.readUndistilled(Math.max(1, auto.minEpisodes ?? 0, cfg.extractor?.maxEpisodesPerRun ?? 40))
+      // Ask for one batch more than a batch: the decision needs to know whether a
+      // *full* batch is waiting (catch-up) and whether the threshold is met, and
+      // one extra row answers both without a second read.
+      const batch = await vault.readUndistilled(Math.max(1, auto.minEpisodes ?? 0, batchSize))
       pending = Array.isArray(batch) ? batch.length : 0
     } catch (error) {
       log('warn', `自动蒸馏：数不了还没蒸馏的情节 · auto: could not count undistilled episodes: ${error?.message ?? error}`)
@@ -130,14 +180,25 @@ export function createAutoDistiller({ cfg, vault, run, log = () => {}, now = ()
       }
     }
 
-    const decision = autoDecision({ auto, now: at, lastAttemptAt, startedAt, pending })
-    if (!decision.due) return { ...decision, pending, ran: false }
+    // The daily cap is per calendar day, and a new day resets it — in memory now
+    // and on disk with the next write, so a restart cannot lose the count either.
+    const today = todayKey(at)
+    if (day !== today) {
+      day = today
+      batchesToday = 0
+    }
+
+    const decision = autoDecision({ auto, now: at, lastAttemptAt, startedAt, pending, batchSize, batchesToday })
+    if (!decision.due) return { ...decision, pending, batchesToday, ran: false }
 
     // Arm the gap before the call: a slow or failing run must not be retried on
     // the next tick.
     lastAttemptAt = at
+    // Counted before the call, like the gap: a run that fails or finds another one
+    // in flight still spent this batch's slot, so the daily cap stays a real cap.
+    if (decision.rule === 'catch-up') batchesToday += 1
     try {
-      await vault.writeAutoState?.({ lastAttemptAt: at })
+      await vault.writeAutoState?.(decision.rule === 'catch-up' ? { lastAttemptAt: at, batchDay: today, batchesToday } : { lastAttemptAt: at })
     } catch (error) {
       log('warn', `自动蒸馏：没能记下这次尝试 · auto: could not record the attempt: ${error?.message ?? error}`)
     }
@@ -158,12 +219,12 @@ export function createAutoDistiller({ cfg, vault, run, log = () => {}, now = ()
         `自动蒸馏 auto (${decision.rule}): ${report?.message ?? report?.reason ?? '没有运行 · did not run'}`,
       )
     }
-    return { ...decision, pending, ran: true, report }
+    return { ...decision, pending, batchesToday, ran: true, report }
   }
 
   /** What the ticker knows, for a diagnostics line or a test. */
   function state() {
-    return { lastAttemptAt, lastReport }
+    return { lastAttemptAt, lastReport, batchesToday, day }
   }
 
   return { tick, state }

package/src/config.js

@@ -114,6 +114,34 @@ const DEFAULTS = {
     quietHours: '',
     /** Project tag for automatic cards; empty uses the newest episode's project. */
     project: '',
+    /**
+     * Catch-up mode: instead of waiting for the schedule, keep running a batch
+     * every `catchUpEveryMinutes` while a full batch is still waiting — and stop
+     * at `maxBatchesPerDay`. This is what turns a backlog (an imported history,
+     * a week of sessions) into something that drains itself without a person
+     * pressing a button, while still capping what it can spend in one day.
+     */
+    catchUp: false,
+    /** Minutes between catch-up batches. */
+    catchUpEveryMinutes: 10,
+    /** Most automatic batches in one calendar day; 0 turns the daily cap off. */
+    maxBatchesPerDay: 6,
+  },
+
+  /**
+   * Update checking. The plugin asks the registry what the newest version is and
+   * compares it with the version it is running; it never installs unless asked
+   * (`autoInstall`) or a person presses the button. One HTTPS GET, no query
+   * string, nothing about the vault or the user in it.
+   */
+  update: {
+    enabled: true,
+    /** Hours a check result stays good for. */
+    checkEveryHours: 12,
+    /** Install a newer version at startup without being asked. */
+    autoInstall: false,
+    /** Registry to ask; empty uses the plugin manager's, then npm's own. */
+    registry: '',
   },
 }
 
@@ -241,6 +269,14 @@ export function resolveConfig(raw) {
   // A malformed window must not disable the rule or, worse, silence it forever:
   // parse what is parseable and fall back to "no quiet hours".
   cfg.auto.quietHours = parseQuietHours(cfg.auto.quietHours) === null ? '' : String(cfg.auto.quietHours).trim()
+  cfg.auto.catchUp = cfg.auto.catchUp === true
+  cfg.auto.catchUpEveryMinutes = int(cfg.auto.catchUpEveryMinutes, 10, 1, 1440)
+  cfg.auto.maxBatchesPerDay = int(cfg.auto.maxBatchesPerDay, 6, 0, 200)
+
+  cfg.update.enabled = cfg.update.enabled !== false
+  cfg.update.checkEveryHours = int(cfg.update.checkEveryHours, 12, 1, 24 * 30)
+  cfg.update.autoInstall = cfg.update.autoInstall === true
+  cfg.update.registry = String(cfg.update.registry || '').trim().replace(/\/+$/, '')
 
   return cfg
 }
@@ -276,5 +312,6 @@ export function paths(vaultDir) {
     audit: path.join(vaultDir, 'audit'),
     distillState: path.join(vaultDir, '.distill-state.json'),
     autoState: path.join(vaultDir, '.auto-state.json'),
+    updateState: path.join(vaultDir, '.update-state.json'),
   }
 }

package/src/history.js

@@ -421,6 +421,32 @@ export async function runBackfill({
     onProgress?.(report)
   }
 
+  // Views last, and only when something changed: `README.md` and `graph.html` are
+  // rendered from the cards, so an import that adds episodes but no cards changes
+  // nothing on either. The *reason* to do it here is that a backfill is the one
+  // operation that can add hundreds of episodes after the last render, and a stale
+  // view is indistinguishable from an empty vault when a person opens the file.
+  let refreshed = false
+  const previous = { readme: true, graph: true }
+  if (!dryRun && imported > 0) {
+    for (const [key, render] of [
+      ['readme', vault.regenerateReadme],
+      ['graph', vault.regenerateGraph],
+    ]) {
+      if (typeof render !== 'function') {
+        previous[key] = false
+        continue
+      }
+      try {
+        await render.call(vault)
+      } catch {
+        // A view that will not render must not lose the episodes that just landed.
+        previous[key] = false
+      }
+    }
+    refreshed = Object.values(previous).some(Boolean)
+  }
+
   return {
     dir,
     dryRun,
@@ -430,6 +456,7 @@ export async function runBackfill({
     imported,
     duplicates,
     exhausted,
+    refreshed,
     malformed: sessions.reduce((n, s) => n + s.malformed, 0),
     failed: sessions.filter((s) => s.failure !== null).length,
     ms: Date.now() - started,

package/src/schema.js

@@ -292,6 +292,60 @@ const auto = z.object({
       .default('')
       .description('自动蒸馏记到哪个项目；空 = 最近情节的项目 · project for automatic cards; empty = the newest episode\'s project'),
   ),
+  catchUp: live(
+    z
+      .boolean()
+      .default(false)
+      .description('追平模式：只要还攒着一整批就按自己的节奏一批批蒸下去 · catch-up: keep distilling batch after batch while a full batch is still waiting'),
+  ),
+  catchUpEveryMinutes: live(
+    z
+      .number()
+      .min(1)
+      .max(1440)
+      .step(1)
+      .default(10)
+      .description('追平模式每批之间隔多少分钟 · minutes between catch-up batches'),
+  ),
+  maxBatchesPerDay: live(
+    z
+      .number()
+      .min(0)
+      .max(200)
+      .step(1)
+      .default(6)
+      .description('一天最多自动蒸几批；0 = 不限 · most automatic batches per day; 0 lifts the cap'),
+  ),
+})
+
+const update = z.object({
+  enabled: live(
+    z
+      .boolean()
+      .default(true)
+      .description('定期检查 npm 上有没有新版本（只查，不装）· check npm for a newer version (checks only, never installs)'),
+  ),
+  checkEveryHours: live(
+    z
+      .number()
+      .min(1)
+      .max(720)
+      .step(1)
+      .default(12)
+      .description('查到的结果保持多久 · hours a check result stays good for'),
+  ),
+  autoInstall: live(
+    z
+      .boolean()
+      .default(false)
+      .description('启动时发现新版本就自动装（link: 本地安装会拒绝）· install a newer version at startup; a link: install is refused'),
+  ),
+  registry: live(
+    z
+      .string()
+      .default('')
+      .description('用哪个 npm 源查版本；空 = 宿主的源，再退到 npmjs · registry to ask; empty = the harness\'s, then npmjs'),
+  ),
 })
 
 export const Config = z.object({
@@ -317,6 +371,7 @@ export const Config = z.object({
   privacy,
   extractor,
   auto,
+  update,
   retrieval,
 })
 

package/src/tools.js

@@ -57,6 +57,27 @@ function formatHits(hits) {
  */
 
 /** One line describing what a distill call would do right now, for memory_stats. */
+/**
+ * The version line for memory_stats.
+ *
+ * Deliberately silent about a newer version when the check has not run yet: "no
+ * news" must not read as "you are up to date", and a check is an outbound request
+ * that a person did not necessarily just make.
+ */
+function describeUpdate(getUpdate) {
+  if (typeof getUpdate !== 'function') return '版本 version: 更新检查不可用 · update check unavailable'
+  let state = null
+  try {
+    state = getUpdate()
+  } catch {
+    return '版本 version: 更新检查不可用 · update check unavailable'
+  }
+  if (state === null || typeof state !== 'object' || state.current === null) return '版本 version: 未知 · unknown'
+  const current = `版本 version: \`${state.current}\``
+  if (state.latest === null) return `${current} · 还没有检查过更新 · no update check yet`
+  if (state.latest === state.current) return `${current} · 已是最新 · latest`
+  return `${current} · 有新版本 \`${state.latest}\`（设置页可更新）· newer version available`
+}
 function describeExtractor(ctx, cfg) {
   if (!cfg.extractor.enabled) return 'extractor: off (nothing calls a model)'
   if (cfg.extractor.transport === 'http') {
@@ -73,7 +94,7 @@ function describeExtractor(ctx, cfg) {
   }
 }
 
-export function registerTools(ctx, { cfg, vault, redactor, runner = null }) {
+export function registerTools(ctx, { cfg, vault, redactor, runner = null, getUpdate = null }) {
   const disposers = []
 
   /**
@@ -525,6 +546,7 @@ export function registerTools(ctx, { cfg, vault, redactor, runner = null }) {
           describeExtractor(ctx, cfg),
           `privacy rules: ${stats.privacy.rules}`,
           `views: README.md and graph.html in the vault root (open the HTML directly, no server needed)`,
+          describeUpdate(getUpdate),
         ].join('\n')
         return { ...stats, text }
       },
@@ -575,6 +597,7 @@ export function registerTools(ctx, { cfg, vault, redactor, runner = null }) {
         }
         if (report.imported > 0 && !dryRun) {
           lines.push('这些情节还没有变成卡片：蒸馏一次（memory_distill 或设置页的「蒸馏一次」）才会进入检索层。')
+          if (report.refreshed === true) lines.push('README.md 和 graph.html 已经按新情节重画过一次。')
         }
         return { ...report, text: lines.join('\n') }
       },