@tnotesjs/core 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tnotesjs/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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/",
@@ -30,6 +33,7 @@
   ],
   "scripts": {
     "build": "tsup",
+    "prepublishOnly": "pnpm build",
     "build:check": "tsc --noEmit -p tsconfig.build.json",
     "typecheck": "vue-tsc --noEmit -p tsconfig.build.json",
     "dev": "tsup --watch",

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 = []
+  }
+}

package/services/file-watcher/folderChangeHandler.ts

@@ -0,0 +1,325 @@
+/**
+ * services/file-watcher/folderChangeHandler.ts
+ *
+ * 文件夹变更处理：删除、重命名、回退
+ */
+
+import { existsSync, promises as fsPromises } from 'fs'
+import { join } from 'path'
+
+import { safeExecute } from './internal'
+import { REPO_NOTES_URL } from '../../config/constants'
+import { generateNoteTitle } from '../../config/templates'
+
+import type { EventScheduler } from './eventScheduler'
+import type { WatchState } from './watchState'
+import type { NoteIndexCache } from '../../core/NoteIndexCache'
+import type { Logger } from '../../utils'
+import type { NoteService } from '../note/service'
+import type { ReadmeService } from '../readme/service'
+import type { TocService } from '../toc/service'
+
+const RENAME_REVERT_DELAY_MS = 2000
+
+/**
+ * 检测到笔记目录名称变更或者被删除的事件时，需要更新根目录下的 README.md 和 sidebar.json
+ *
+ * 暂定 1s 作为缓冲，1s 过后再恢复监听
+ */
+const DELETE_REINIT_DELAY_MS = 1000
+
+const UPDATE_UNLOCK_DELAY_MS = 500
+
+interface FolderChangeHandlerConfig {
+  /** 笔记目录路径 */
+  notesDir: string
+  /** 监听状态管理器 */
+  watchState: WatchState
+  /** 事件调度器 */
+  scheduler: EventScheduler
+  /** 笔记服务实例 */
+  noteService: NoteService
+  /** README 服务实例 */
+  readmeService: ReadmeService
+  /** TOC 服务实例 */
+  tocService: TocService
+  /** 笔记索引缓存实例 */
+  noteIndexCache: NoteIndexCache
+  /** 日志记录器 */
+  logger: Logger
+  /**
+   * 文件夹重命名成功后回调（可选）。
+   *
+   * 用于在 dev server 中通过 Vite WS 通知前端跳转到新 URL，
+   * 让「文件系统直接改名」与「关于面板保存」体验一致。
+   */
+  onRenameSuccess?: (payload: {
+    oldFolder: string
+    newFolder: string
+    noteIndex: string
+  }) => void
+  /** 笔记结构变更（增删改目录）后触发 dev 搜索索引重建 */
+  onNoteStructureChanged?: (reason: string) => void
+}
+
+export class FolderChangeHandler {
+  /** 活跃的定时器 ID 集合，用于统一清理 */
+  private activeTimers: Set<NodeJS.Timeout> = new Set()
+
+  constructor(private config: FolderChangeHandlerConfig) {}
+
+  /**
+   * 清理所有活跃定时器，释放资源
+   *
+   * 在服务停止时调用，防止定时器在服务销毁后仍然触发回调
+   */
+  clearTimers(): void {
+    for (const timer of this.activeTimers) {
+      clearTimeout(timer)
+    }
+    this.activeTimers.clear()
+  }
+
+  private scheduleTimer(fn: () => void, delay: number): void {
+    const timer = setTimeout(() => {
+      this.activeTimers.delete(timer)
+      fn()
+    }, delay)
+    this.activeTimers.add(timer)
+  }
+
+  async handleFolderDeletion(deletedFolderName: string): Promise<void> {
+    const { scheduler, watchState, noteIndexCache, tocService, logger } =
+      this.config
+
+    if (scheduler.getUpdating()) return
+    scheduler.setUpdating(true)
+
+    try {
+      const noteIndex = this.extractNoteIndexOrWarn(deletedFolderName)
+      if (!noteIndex) return
+
+      logger.info(`正在处理笔记删除: ${noteIndex} (${deletedFolderName})`)
+
+      // 清理缓存
+      watchState.deleteNoteDir(deletedFolderName)
+      watchState.clearNoteCaches(deletedFolderName)
+      noteIndexCache.delete(noteIndex)
+
+      // 更新根 README.md、sidebar.json
+      await safeExecute(
+        `删除笔记 ${noteIndex}`,
+        async () => {
+          await tocService.deleteNoteFromToc(noteIndex)
+          await tocService.regenerateSidebar()
+          this.config.onNoteStructureChanged?.(`watcher:delete:${noteIndex}`)
+        },
+        logger,
+      )
+    } finally {
+      this.scheduleTimer(() => {
+        scheduler.setUpdating(false)
+        watchState.initializeFromDisk()
+      }, DELETE_REINIT_DELAY_MS)
+    }
+  }
+
+  async handleFolderRenameUpdate(
+    oldName: string,
+    newName: string,
+  ): Promise<void> {
+    const { scheduler, watchState, logger } = this.config
+
+    if (scheduler.getUpdating()) return
+    scheduler.setUpdating(true)
+
+    try {
+      const { oldNoteIndex, newNoteIndex } = this.validateRenameIndexes(
+        oldName,
+        newName,
+      )
+      if (!oldNoteIndex || !newNoteIndex) return
+
+      logger.info(`正在处理文件夹重命名: ${oldName} → ${newName}`)
+
+      if (oldNoteIndex === newNoteIndex) {
+        await safeExecute(
+          `标题重命名 ${newNoteIndex}`,
+          () => this.handleTitleOnlyRename(newNoteIndex, newName),
+          logger,
+        )
+      } else {
+        await safeExecute(
+          `索引变更 ${oldNoteIndex}→${newNoteIndex}`,
+          () => this.handleIndexChangedRename(oldNoteIndex, newNoteIndex),
+          logger,
+        )
+      }
+
+      this.config.onRenameSuccess?.({
+        oldFolder: oldName,
+        newFolder: newName,
+        noteIndex: newNoteIndex,
+      })
+    } finally {
+      this.scheduleTimer(() => {
+        scheduler.setUpdating(false)
+        watchState.initializeFromDisk()
+      }, UPDATE_UNLOCK_DELAY_MS)
+    }
+  }
+
+  // #region - 私有实现
+
+  private validateRenameIndexes(
+    oldName: string,
+    newName: string,
+  ): { oldNoteIndex: string | null; newNoteIndex: string | null } {
+    const { noteIndexCache, logger } = this.config
+    const oldNoteIndex = this.extractNoteIndexOrWarn(oldName)
+    const newNoteIndex = this.extractNoteIndexOrWarn(newName)
+
+    if (!oldNoteIndex || !newNoteIndex) {
+      return { oldNoteIndex: null, newNoteIndex: null }
+    }
+
+    if (!/^\d{4}$/.test(newNoteIndex)) {
+      logger.error(`新笔记索引格式非法: ${newNoteIndex}，自动回退`)
+      this.revertFolderRename(oldName, newName)
+      return { oldNoteIndex: null, newNoteIndex: null }
+    }
+
+    if (oldNoteIndex !== newNoteIndex && noteIndexCache.has(newNoteIndex)) {
+      logger.error(`新笔记索引 ${newNoteIndex} 已存在，自动回退`)
+      this.revertFolderRename(oldName, newName)
+      return { oldNoteIndex: null, newNoteIndex: null }
+    }
+
+    return { oldNoteIndex, newNoteIndex }
+  }
+
+  private async handleTitleOnlyRename(
+    noteIndex: string,
+    newName: string,
+  ): Promise<void> {
+    const { noteIndexCache, tocService, logger, notesDir } = this.config
+
+    logger.info(`笔记索引未变 (${noteIndex})，只更新标题`)
+    noteIndexCache.updateFolderName(noteIndex, newName)
+
+    // 同步重写笔记目录内 README.md 的一级标题，与 RenameNoteCommand 行为一致
+    await safeExecute(
+      `更新 README 一级标题 ${noteIndex}`,
+      () => this.rewriteNoteReadmeH1(notesDir, newName, noteIndex),
+      logger,
+    )
+
+    await tocService.renameNoteInToc(noteIndex, newName)
+    await tocService.regenerateSidebar()
+    this.config.onNoteStructureChanged?.(`watcher:rename-title:${noteIndex}`)
+    logger.success(`标题更新完成`)
+  }
+
+  /**
+   * 重写指定笔记目录下 README.md 的一级标题。
+   *
+   * 输入的 `folderName` 形如 `0003. 评论功能的技术实现`，
+   * 据此推导出新标题文本（去掉 `${noteIndex}. ` 前缀）。
+   */
+  private async rewriteNoteReadmeH1(
+    notesDir: string,
+    folderName: string,
+    noteIndex: string,
+  ): Promise<void> {
+    const readmePath = join(notesDir, folderName, 'README.md')
+    if (!existsSync(readmePath)) return
+
+    const newTitle = folderName.replace(/^\d{4}\.\s*/, '').trim()
+    if (!newTitle) return
+
+    const content = await fsPromises.readFile(readmePath, 'utf-8')
+    const lines = content.split('\n')
+
+    let h1Index = -1
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].trim().startsWith('# ')) {
+        h1Index = i
+        break
+      }
+    }
+
+    if (h1Index === -1) {
+      this.config.logger.warn(
+        `未在 ${readmePath} 找到一级标题，跳过 README H1 更新`,
+      )
+      return
+    }
+
+    const newH1 = generateNoteTitle(noteIndex, newTitle, REPO_NOTES_URL)
+    if (lines[h1Index] === newH1) return
+
+    lines[h1Index] = newH1
+    await fsPromises.writeFile(readmePath, lines.join('\n'), 'utf-8')
+  }
+
+  private async handleIndexChangedRename(
+    oldNoteIndex: string,
+    newNoteIndex: string,
+  ): Promise<void> {
+    const { noteService, noteIndexCache, tocService, logger } = this.config
+
+    logger.info(`笔记索引变更: ${oldNoteIndex} → ${newNoteIndex}`)
+
+    await tocService.deleteNoteFromToc(oldNoteIndex)
+
+    const newNote = noteService.getNoteByIndex(newNoteIndex)
+
+    if (newNote) {
+      noteIndexCache.delete(oldNoteIndex)
+      noteIndexCache.add(newNote)
+
+      await tocService.appendNoteToToc(newNoteIndex)
+      await tocService.regenerateSidebar()
+      this.config.onNoteStructureChanged?.(
+        `watcher:rename-index:${oldNoteIndex}->${newNoteIndex}`,
+      )
+      logger.success(`笔记索引变更处理完成`)
+    } else {
+      logger.error(`未找到新笔记: ${newNoteIndex}`)
+    }
+  }
+
+  private async revertFolderRename(
+    oldName: string,
+    newName: string,
+  ): Promise<void> {
+    const { notesDir, scheduler, watchState, logger } = this.config
+
+    try {
+      const oldPath = join(notesDir, oldName)
+      const newPath = join(notesDir, newName)
+
+      if (existsSync(newPath)) {
+        scheduler.setUpdating(true)
+        await fsPromises.rename(newPath, oldPath)
+        logger.warn(`文件夹已回退: ${newName} → ${oldName}`)
+        this.scheduleTimer(() => {
+          scheduler.setUpdating(false)
+          watchState.initializeFromDisk()
+        }, RENAME_REVERT_DELAY_MS)
+      }
+    } catch (error) {
+      logger.error(`回退文件夹重命名失败: ${error}`)
+    }
+  }
+
+  private extractNoteIndexOrWarn(name: string): string | null {
+    const noteIndex = name.match(/^(\d{4})/)?.[1] || null
+    if (!noteIndex) {
+      this.config.logger.warn(`无法从文件夹名称提取笔记索引: ${name}`)
+    }
+    return noteIndex
+  }
+
+  // #endregion - 私有实现
+}