@tnotesjs/core 0.2.1 → 0.3.0

package/dist/cli/index.js

@@ -19,7 +19,6 @@ import {
   ROOT_TOC_PATH,
   ReadmeService,
   RenameNoteCommand,
-  TimestampService,
   TocService,
   UpdateNoteConfigCommand,
   VitepressService,
@@ -42,11 +41,12 @@ import {
   runCommand,
   validatePort,
   validateTopic
-} from "../chunk-5QN44ES5.js";
+} from "../chunk-XCWFZLER.js";
 import {
   ConfigManager,
-  getConfigManager
-} from "../chunk-5Y5IYS6C.js";
+  getConfigManager,
+  stripDeprecatedRootItemFields
+} from "../chunk-UJG3UU5X.js";
 
 // commands/update/UpdateCommand.ts
 import { existsSync, readFileSync, writeFileSync } from "fs";
@@ -121,6 +121,9 @@ var UpdateCommand = class extends BaseCommand {
         completed_notes_count: fixed
       };
       delete config.root_item.completed_notes_count_last_month;
+      stripDeprecatedRootItemFields(
+        config.root_item
+      );
       writeFileSync(ROOT_CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
       if (!this.quiet) {
         const filledCount = Object.keys(fixed).length - _countsBeforeFix;
@@ -192,7 +195,6 @@ var PushCommand = class extends BaseCommand {
     super("push");
     this.gitManager = new GitManager(ROOT_DIR_PATH);
     this.gitService = new GitService();
-    this.timestampService = new TimestampService();
   }
   async run() {
     try {
@@ -214,18 +216,6 @@ var PushCommand = class extends BaseCommand {
         const commitMessage = this.gitService.generateCommitMessage();
         await runCommand("git add -A", ROOT_DIR_PATH);
         await runCommand(`git commit -m "${commitMessage}"`, ROOT_DIR_PATH);
-        this.logger.info("\u4FEE\u590D\u7B14\u8BB0\u65F6\u95F4\u6233...");
-        await this.timestampService.fixAllTimestamps(false);
-        const afterFixStatus = await runCommand(
-          "git -c core.quotePath=false status --porcelain",
-          ROOT_DIR_PATH
-        );
-        const hasTimestampChanges = afterFixStatus.split(/\r?\n/).filter(Boolean).some((line) => line.includes(".tnotes.json"));
-        if (hasTimestampChanges) {
-          this.logger.info("\u5C06\u65F6\u95F4\u6233\u53D8\u66F4\u5408\u5E76\u5230 commit...");
-          await runCommand("git add -u", ROOT_DIR_PATH);
-          await runCommand("git commit --amend --no-edit", ROOT_DIR_PATH);
-        }
       } else {
         this.logger.info(`\u68C0\u6D4B\u5230 ${status.ahead} \u4E2A\u672A\u63A8\u9001\u7684\u63D0\u4EA4\uFF0C\u76F4\u63A5\u63A8\u9001...`);
       }
@@ -539,37 +529,6 @@ var InitTocCommand = class extends BaseCommand {
   }
 };
 
-// commands/maintenance/FixTimestampsCommand.ts
-var FixTimestampsCommand = class extends BaseCommand {
-  constructor() {
-    super("fix-timestamps");
-    this.timestampService = new TimestampService();
-  }
-  async run() {
-    this.logger.info("\u5F00\u59CB\u4FEE\u590D\u6240\u6709\u7B14\u8BB0\u7684\u65F6\u95F4\u6233...");
-    this.logger.info("\u{1F4CC} \u6B64\u64CD\u4F5C\u4F1A\u5C06\u6240\u6709\u65F6\u95F4\u6233\u66F4\u65B0\u4E3A git \u771F\u5B9E\u65F6\u95F4");
-    this.logger.info("");
-    const result = await this.timestampService.fixAllTimestamps(true);
-    this.logger.info("");
-    this.logger.info("\u{1F4CA} \u4FEE\u590D\u7EDF\u8BA1:");
-    this.logger.info(
-      `  - \u6839\u914D\u7F6E\u6587\u4EF6: ${result.rootConfigFixed ? "\u5DF2\u4FEE\u590D" : "\u65E0\u9700\u4FEE\u590D"}`
-    );
-    this.logger.info(`  - \u603B\u7B14\u8BB0\u6570: ${result.total}`);
-    this.logger.info(`  - \u5DF2\u4FEE\u590D: ${result.fixed}`);
-    this.logger.info(`  - \u8DF3\u8FC7: ${result.skipped}`);
-    this.logger.info("");
-    if (result.fixed > 0 || result.rootConfigFixed) {
-      this.logger.success(
-        `\u2705 \u6210\u529F\u4FEE\u590D ${result.fixed} \u4E2A\u7B14\u8BB0${result.rootConfigFixed ? " + \u6839\u914D\u7F6E\u6587\u4EF6" : ""}\u7684\u65F6\u95F4\u6233\uFF01`
-      );
-      this.logger.info("\u{1F4A1} \u63D0\u793A: \u8FD0\u884C pnpm tn:push \u63D0\u4EA4\u66F4\u6539");
-    } else {
-      this.logger.success("\u2705 \u6240\u6709\u65F6\u95F4\u6233\u5747\u5DF2\u6B63\u786E\uFF01");
-    }
-  }
-};
-
 // commands/misc/HelpCommand.ts
 var COMMAND_CATEGORIES = {
   \u5F00\u53D1\u548C\u6784\u5EFA: [COMMAND_NAMES.DEV, COMMAND_NAMES.BUILD, COMMAND_NAMES.PREVIEW],
@@ -581,7 +540,7 @@ var COMMAND_CATEGORIES = {
   "Git \u64CD\u4F5C": [COMMAND_NAMES.PUSH, COMMAND_NAMES.PULL],
   "\u8FC1\u79FB\uFF08v0.2.x \u8FC7\u6E21\uFF09": [COMMAND_NAMES.INIT_TOC],
   \u521D\u59CB\u5316: [COMMAND_NAMES.INIT_SUB_REPO],
-  \u5176\u4ED6: [COMMAND_NAMES.FIX_TIMESTAMPS, COMMAND_NAMES.HELP]
+  \u5176\u4ED6: [COMMAND_NAMES.HELP]
 };
 var COMMAND_OPTIONS_INFO = {
   [COMMAND_OPTIONS.QUIET]: {
@@ -783,13 +742,14 @@ var UpdateCompletedCountCommand = class extends BaseCommand {
       const configContent = readFileSync4(ROOT_CONFIG_PATH, "utf-8");
       const config = JSON.parse(configContent);
       this.logger.info("\u5F00\u59CB\u66F4\u65B0\u5B8C\u6210\u7B14\u8BB0\u6570\u91CF\u5386\u53F2\u8BB0\u5F55...");
-      const completedNotesCountHistory = await this.getCompletedNotesCountHistory(
-        config.root_item.created_at ?? Date.now()
-      );
+      const completedNotesCountHistory = await this.getCompletedNotesCountHistory();
       config.root_item = {
         ...config.root_item,
         completed_notes_count: completedNotesCountHistory
       };
+      stripDeprecatedRootItemFields(
+        config.root_item
+      );
       writeFileSync3(ROOT_CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
       const duration = Date.now() - startTime;
       const monthKeys = Object.keys(completedNotesCountHistory);
@@ -812,10 +772,9 @@ var UpdateCompletedCountCommand = class extends BaseCommand {
    * 1. 计算最近12个月的范围（当前月份往前推11个月）
    * 2. 遍历这12个月，从 Git 历史中读取 TOC.md（回退 README.md）
    * 3. 解析获取完成笔记数量
-   * 4. 如果知识库创建时间在这12个月内，之前的月份补0
-   * 5. 返回对象 { '25.01': 0, '25.02': 1, ..., '25.12': 15 }
+   * 4. 返回对象 { '25.01': 0, '25.02': 1, ..., '25.12': 15 }
    */
-  async getCompletedNotesCountHistory(createdAt) {
+  async getCompletedNotesCountHistory() {
     try {
       const now = /* @__PURE__ */ new Date();
       const currentYear = now.getFullYear();
@@ -826,9 +785,6 @@ var UpdateCompletedCountCommand = class extends BaseCommand {
         firstYear = currentYear - 1;
         firstMonth = 12 + firstMonth;
       }
-      const createdDate = new Date(createdAt);
-      const createdYear = createdDate.getFullYear();
-      const createdMonth = createdDate.getMonth();
       const result = {};
       let prevCount = 0;
       for (let i = 0; i < 12; i++) {
@@ -837,25 +793,18 @@ var UpdateCompletedCountCommand = class extends BaseCommand {
         const yearShort = String(targetYear).slice(-2);
         const monthStr = String(targetMonth + 1).padStart(2, "0");
         const key = `${yearShort}.${monthStr}`;
-        const isBeforeCreation = targetYear < createdYear || targetYear === createdYear && targetMonth < createdMonth;
-        if (isBeforeCreation) {
-          result[key] = 0;
-          prevCount = 0;
-          this.logger.info(`\u2713 ${key}: 0 \u7BC7\uFF08\u65E9\u4E8E\u521B\u5EFA\u65F6\u95F4\uFF09`);
-        } else {
-          try {
-            const count = await this.getMonthCompletedCount(
-              targetYear,
-              targetMonth,
-              prevCount
-            );
-            result[key] = count;
-            prevCount = count;
-            this.logger.info(`\u2713 ${key}: ${count} \u7BC7`);
-          } catch (error) {
-            result[key] = prevCount;
-            this.logger.warn(`${key}: \u65E0\u6570\u636E\uFF0C\u4F7F\u7528 ${prevCount}\uFF08\u4E0A\u6708\u503C\uFF09`);
-          }
+        try {
+          const count = await this.getMonthCompletedCount(
+            targetYear,
+            targetMonth,
+            prevCount
+          );
+          result[key] = count;
+          prevCount = count;
+          this.logger.info(`\u2713 ${key}: ${count} \u7BC7`);
+        } catch (error) {
+          result[key] = prevCount;
+          this.logger.warn(`${key}: \u65E0\u6570\u636E\uFF0C\u4F7F\u7528 ${prevCount}\uFF08\u4E0A\u6708\u503C\uFF09`);
         }
       }
       return result;
@@ -919,7 +868,6 @@ var commandFactories = {
   "build": () => new BuildCommand(),
   "create-notes": () => new CreateNoteCommand(),
   "dev": () => new DevCommand(),
-  "fix-timestamps": () => new FixTimestampsCommand(),
   "init-sub-repo": () => new InitSubRepoCommand(),
   "init-toc": () => new InitTocCommand(),
   "help": () => new HelpCommand(),

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   ConfigManager,
   getConfigManager
-} from "./chunk-5Y5IYS6C.js";
+} from "./chunk-UJG3UU5X.js";
 export {
   ConfigManager,
   getConfigManager

package/dist/vitepress/config/index.js

@@ -7,10 +7,10 @@ import {
   UpdateNoteConfigCommand,
   generateAnchor,
   logger
-} from "../../chunk-5QN44ES5.js";
+} from "../../chunk-XCWFZLER.js";
 import {
   ConfigManager
-} from "../../chunk-5Y5IYS6C.js";
+} from "../../chunk-UJG3UU5X.js";
 
 // vitepress/config/index.ts
 import fs3 from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tnotesjs/core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "TNotes 知识库核心框架 —— 基于 VitePress 的笔记管理系统",
   "type": "module",
   "packageManager": "pnpm@10.17.1",
@@ -22,7 +22,10 @@
     "./vitepress/*": "./vitepress/*"
   },
   "files": [
-    "config/defaultConfig.ts",
+    "config/",
+    "core/",
+    "services/",
+    "utils/",
     "dist/",
     "templates/",
     "vitepress/",

package/services/file-watcher/configChangeHandler.ts

@@ -0,0 +1,64 @@
+/**
+ * services/file-watcher/configChangeHandler.ts
+ *
+ * 配置变更处理
+ */
+
+import type { WatchEvent } from './internal'
+import type { WatchState } from './watchState'
+import type { NoteIndexCache } from '../../core/NoteIndexCache'
+import type { Logger } from '../../utils'
+import type { NoteService } from '../note/service'
+
+interface ConfigChangeHandlerConfig {
+  /** 监听状态管理器 */
+  state: WatchState
+  /** 笔记服务实例 */
+  noteService: NoteService
+  /** 笔记索引缓存实例 */
+  noteIndexCache: NoteIndexCache
+  /** 日志记录器 */
+  logger: Logger
+}
+
+export class ConfigChangeHandler {
+  constructor(private config: ConfigChangeHandlerConfig) {}
+
+  async handle(events: WatchEvent[]): Promise<string[]> {
+    if (events.length === 0) return []
+    const changedIndexes: string[] = []
+
+    const { state, noteService, noteIndexCache, logger } = this.config
+
+    for (const change of events) {
+      // 忽略由 API 主动写入的更新，避免重复触发
+      if (noteService.shouldIgnoreConfigChange(change.path)) {
+        logger.debug(`忽略 API 写入的配置文件: ${change.path}`)
+        continue
+      }
+
+      const snapshot = state.readConfigSnapshot(change.path)
+      if (!snapshot) continue
+
+      const cached = state.getConfigSnapshot(change.path)
+      state.setConfigSnapshot(change.path, snapshot)
+      noteIndexCache.updateConfig(change.noteIndex, snapshot)
+
+      if (!cached) continue
+
+      const statusChanged = cached.done !== snapshot.done
+      const otherChanged =
+        cached.enableDiscussions !== snapshot.enableDiscussions ||
+        cached.description !== snapshot.description
+
+      if (statusChanged) {
+        changedIndexes.push(change.noteIndex)
+        logger.info(`检测到配置状态变化: done(${cached.done}→${snapshot.done})`)
+      } else if (otherChanged) {
+        logger.info('检测到配置非状态字段变化，已刷新缓存（无需全局更新）')
+      }
+    }
+
+    return changedIndexes
+  }
+}

package/services/file-watcher/eventScheduler.ts

@@ -0,0 +1,179 @@
+/**
+ * services/file-watcher/eventScheduler.ts
+ *
+ * 事件调度：防抖 + 批量检测 + 队列
+ */
+
+import type { WatchEvent } from './internal'
+
+/** 默认防抖延迟（毫秒） */
+const DEFAULT_DEBOUNCE_MS = 1000
+
+/**
+ * 默认批量更新检测窗口（毫秒）
+ *
+ * - 如果在窗口时间内检测到超过阈值个文件变更，则判定为批量更新
+ * - 暂定是 1s 内 3 个文件变更的阈值，正常编写笔记的情况下，1s 内不会超过 3 个文件同时变更，通常不会误判
+ * - 当批量更新的行为被检测到之后，会暂停监听服务（窗口 + 缓冲时间）后再恢复
+ */
+const DEFAULT_BATCH_WINDOW_MS = 1000
+
+/** 默认批量更新阈值（文件数） */
+const DEFAULT_BATCH_THRESHOLD = 3
+
+/** 默认批量更新安全缓冲（毫秒） */
+const DEFAULT_BATCH_BUFFER_MS = 2000
+
+interface EventSchedulerConfig {
+  /** 防抖延迟（毫秒），默认 1000 */
+  debounceMs?: number
+  /** 批量更新检测窗口（毫秒），默认 1000 */
+  batchWindowMs?: number
+  /** 批量更新阈值（文件数），默认 3 */
+  batchThreshold?: number
+  /** 批量更新安全缓冲（毫秒），默认 2000 */
+  batchBufferMs?: number
+  /** 当事件队列需要刷新处理时的回调函数 */
+  onFlush: (events: WatchEvent[]) => void
+  /** 检测到批量更新时暂停监听服务的回调函数 */
+  onPauseForBatch: () => void
+  /** 批量更新结束后恢复监听服务的回调函数 */
+  onResumeAfterBatch: () => void
+  /** 重新初始化调度器的回调函数 */
+  reinit: () => void
+}
+
+export class EventScheduler {
+  /** 待处理的文件变更事件队列 */
+  private pendingEvents: Map<string, WatchEvent> = new Map()
+
+  /** 防抖定时器 */
+  private updateTimer: NodeJS.Timeout | null = null
+
+  /** 批量更新恢复定时器 */
+  private batchResumeTimer: NodeJS.Timeout | null = null
+
+  /** 记录最近的变更时间戳 */
+  private recentChanges: number[] = []
+
+  /** 标记是否正在更新，避免循环触发 - 类似一把更新行为锁 */
+  private isUpdating = false
+
+  private readonly debounceMs: number
+  private readonly batchWindowMs: number
+  private readonly batchThreshold: number
+  private readonly batchBufferMs: number
+
+  constructor(private config: EventSchedulerConfig) {
+    this.debounceMs = config.debounceMs ?? DEFAULT_DEBOUNCE_MS
+    this.batchWindowMs = config.batchWindowMs ?? DEFAULT_BATCH_WINDOW_MS
+    this.batchThreshold = config.batchThreshold ?? DEFAULT_BATCH_THRESHOLD
+    this.batchBufferMs = config.batchBufferMs ?? DEFAULT_BATCH_BUFFER_MS
+  }
+
+  /**
+   * 设置更新状态锁，用于防止在执行耗时更新操作时被新的文件变更事件打断
+   *
+   * @param flag - true 表示正在更新（锁定），false 表示更新完成（解锁）
+   */
+  setUpdating(flag: boolean) {
+    this.isUpdating = flag
+  }
+
+  /**
+   * 获取当前是否处于更新锁定状态
+   *
+   * @returns true 表示正在执行更新操作（事件处理被暂停），false 表示空闲可处理新事件
+   */
+  getUpdating() {
+    return this.isUpdating
+  }
+
+  /**
+   * 将文件变更事件加入待处理队列，并启动防抖定时器
+   *
+   * - 若同一文件路径的事件已存在，则忽略重复事件（去重）
+   * - 每次新事件都会重置防抖计时器，确保在变更停止后才触发处理
+   *
+   * @param event 文件变更事件
+   */
+  enqueue(event: WatchEvent) {
+    // 事件去重：同一路径的变更只保留一次，降低抖动
+    if (this.pendingEvents.has(event.path)) return
+    this.pendingEvents.set(event.path, event)
+    if (this.updateTimer) clearTimeout(this.updateTimer)
+    this.updateTimer = setTimeout(() => this.flush(), this.debounceMs)
+  }
+
+  /**
+   * 立即触发事件队列的处理（防抖到期或手动调用）
+   *
+   * - 若当前正在更新（isUpdating 为 true），则跳过以避免重复处理
+   * - 清空待处理事件队列，并通过 onFlush 回调交由上层服务处理
+   * - 处理开始后会锁定更新状态，防止处理过程中被新事件打断
+   */
+  flush() {
+    if (this.isUpdating) return
+    if (this.pendingEvents.size === 0) return
+    const events = Array.from(this.pendingEvents.values())
+    this.pendingEvents.clear()
+    this.isUpdating = true
+    this.config.onFlush(events)
+  }
+
+  /**
+   * 记录当前变更时间并检测是否触发批量更新模式
+   *
+   * - 维护一个滑动时间窗口（BATCH_UPDATE_WINDOW_MS）内的变更记录
+   * - 若短时间内（1秒内）变更次数达到阈值（BATCH_UPDATE_THRESHOLD = 3），则判定为批量操作
+   * - 触发批量模式后：
+   *   1. 清空当前待处理事件队列，避免重复处理
+   *   2. 锁定更新状态（isUpdating = true）
+   *   3. 暂停监听服务，并在延迟（窗口 + 缓冲时间）后自动恢复
+   *
+   * @param now 当前时间戳（默认使用 Date.now()）
+   * @returns true 表示已触发批量更新模式，false 表示仍处于普通监听模式
+   */
+  recordChangeAndDetectBatch(now: number = Date.now()): boolean {
+    // 记录近期变更时间戳，用于检测“短时间高频”场景并切换到批量模式
+    this.recentChanges.push(now)
+    this.recentChanges = this.recentChanges.filter(
+      (t) => now - t < this.batchWindowMs,
+    )
+
+    if (this.recentChanges.length < this.batchThreshold) return false
+
+    this.pendingEvents.clear()
+    this.recentChanges = []
+    this.isUpdating = true
+    this.config.onPauseForBatch()
+
+    this.batchResumeTimer = setTimeout(() => {
+      // 批量结束后重建状态并恢复监听
+      this.batchResumeTimer = null
+      this.isUpdating = false
+      this.config.reinit()
+      this.config.onResumeAfterBatch()
+    }, this.batchWindowMs + this.batchBufferMs)
+
+    return true
+  }
+
+  /**
+   * 清理所有定时器，释放资源
+   *
+   * 在服务停止时调用，防止定时器在服务销毁后仍然触发回调
+   */
+  clearTimers(): void {
+    if (this.updateTimer) {
+      clearTimeout(this.updateTimer)
+      this.updateTimer = null
+    }
+    if (this.batchResumeTimer) {
+      clearTimeout(this.batchResumeTimer)
+      this.batchResumeTimer = null
+    }
+    this.pendingEvents.clear()
+    this.recentChanges = []
+  }
+}