@tnotesjs/core 0.2.1 → 0.2.2

package/core/ReadmeGenerator.ts

@@ -0,0 +1,215 @@
+/**
+ * core/ReadmeGenerator.ts
+ *
+ * README 生成器 - 负责生成各种 README 内容
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs'
+
+import { TocGenerator } from './TocGenerator'
+import { ConfigManager } from '../config/ConfigManager'
+import { EOL } from '../config/constants'
+import {
+  logger,
+  parseNoteLine,
+  buildNoteLineMarkdown,
+  processEmptyLines,
+} from '../utils'
+import { createAddNumberToTitle } from '../utils'
+
+import type { NoteInfo } from '../types'
+
+/**
+ * README 生成器类
+ */
+export class ReadmeGenerator {
+  private tocGenerator: TocGenerator
+  private configManager: ConfigManager
+
+  constructor() {
+    this.tocGenerator = new TocGenerator()
+    this.configManager = ConfigManager.getInstance()
+  }
+
+  /**
+   * 更新笔记 README
+   * @param noteInfo - 笔记信息
+   */
+  updateNoteReadme(noteInfo: NoteInfo): void {
+    if (!noteInfo.config) {
+      logger.warn(`笔记 ${noteInfo.dirName} 缺少配置文件`)
+      return
+    }
+
+    const content = readFileSync(noteInfo.readmePath, 'utf-8')
+
+    // 跳过空内容（可能是其他进程写入时的 truncate 中间状态）
+    if (content.length === 0) return
+
+    const lines = content.split(EOL)
+
+    const repoName = this.configManager.get('repoName')
+    this.tocGenerator.updateNoteToc(
+      noteInfo.index,
+      lines,
+      noteInfo.config,
+      repoName,
+    )
+
+    const updatedContent = lines.join(EOL)
+    writeFileSync(noteInfo.readmePath, updatedContent, 'utf-8')
+  }
+
+  /**
+   * 更新首页 README
+   * 更新笔记链接的状态标记（[x] 或 [ ]），同时更新 TOC 区域
+   * @param notes - 笔记信息数组
+   * @param homeReadmePath - 首页 README 路径
+   */
+  updateHomeReadme(notes: NoteInfo[], homeReadmePath: string): void {
+    if (!existsSync(homeReadmePath)) {
+      logger.error(`根目录下的 README.md 文件未找到：${homeReadmePath}`)
+      return
+    }
+
+    const content = readFileSync(homeReadmePath, 'utf-8')
+    const lines = content.split(EOL)
+
+    // 创建笔记配置映射，以笔记索引为键
+    const noteByIndexMap = new Map<string, NoteInfo>()
+    for (const note of notes) {
+      noteByIndexMap.set(note.index, note)
+    }
+
+    // 获取仓库信息
+    const repoOwner = this.configManager.get('author')
+    const repoName = this.configManager.get('repoName')
+
+    // 跟踪已存在的笔记索引和要移除的行
+    const existingNoteIndexes = new Set<string>()
+    const linesToRemove = new Set<number>()
+
+    // 更新笔记链接的状态标记
+    const titles: string[] = []
+    const titlesNotesCount: number[] = []
+    let inTocRegion = false
+    let currentNoteCount = 0
+
+    // 标题编号器（用于自动更新二级和三级标题前边儿的编号）
+    const addNumberToTitle = createAddNumberToTitle()
+    const numberedHeaders = ['## ', '### ']
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+
+      // 跳过 TOC region (后面会重新生成)
+      if (line.includes('<!-- region:toc -->')) {
+        inTocRegion = true
+        continue
+      }
+      if (line.includes('<!-- endregion:toc -->')) {
+        inTocRegion = false
+        continue
+      }
+      if (inTocRegion) {
+        continue
+      }
+
+      // 使用公共方法解析笔记链接
+      const parsed = parseNoteLine(line)
+      if (parsed.isMatch && parsed.noteIndex) {
+        const note = noteByIndexMap.get(parsed.noteIndex)
+
+        if (!note) {
+          // 笔记不存在，标记为移除
+          linesToRemove.add(i)
+          logger.warn(`移除不存在的笔记: ${parsed.noteIndex}`)
+          continue
+        }
+
+        existingNoteIndexes.add(parsed.noteIndex)
+        lines[i] = buildNoteLineMarkdown(note, repoOwner, repoName)
+        currentNoteCount++
+        continue
+      }
+
+      // 匹配标题: ## xxx 或 ### xxx
+      const titleMatch = line.match(/^(#{2,})\s+(.+)$/)
+      if (titleMatch) {
+        // 检查是否是需要编号的标题（2~3 级）
+        const isNumberedHeader = numberedHeaders.some((header) =>
+          line.startsWith(header),
+        )
+
+        if (isNumberedHeader) {
+          // 自动添加编号
+          const [numberedTitle] = addNumberToTitle(line)
+          lines[i] = numberedTitle
+
+          // 保存上一个标题的笔记数量
+          if (titles.length > 0) {
+            titlesNotesCount.push(currentNoteCount)
+          }
+
+          titles.push(numberedTitle)
+          currentNoteCount = 0
+        } else {
+          // 其他级别的标题，不添加编号
+          // 保存上一个标题的笔记数量
+          if (titles.length > 0) {
+            titlesNotesCount.push(currentNoteCount)
+          }
+
+          titles.push(line)
+          currentNoteCount = 0
+        }
+      }
+    }
+
+    // 移除不存在的笔记（从后往前删除，避免索引问题）
+    const sortedLinesToRemove = Array.from(linesToRemove).sort((a, b) => b - a)
+    for (const lineIndex of sortedLinesToRemove) {
+      lines.splice(lineIndex, 1)
+      if (currentNoteCount > 0) {
+        currentNoteCount--
+      }
+    }
+
+    // 查找缺失的笔记（在真实目录中存在但 README 中不存在）
+    const missingNotes: NoteInfo[] = []
+    for (const note of notes) {
+      if (!existingNoteIndexes.has(note.index)) {
+        missingNotes.push(note)
+      }
+    }
+
+    // 将缺失的笔记添加到结尾
+    if (missingNotes.length > 0) {
+      logger.info(`添加 ${missingNotes.length} 篇缺失的笔记到 README`)
+
+      // 按笔记索引排序
+      missingNotes.sort((a, b) => a.index.localeCompare(b.index))
+
+      for (const note of missingNotes) {
+        const noteLine = buildNoteLineMarkdown(note, repoOwner, repoName)
+        lines.push(noteLine)
+        currentNoteCount++
+      }
+    }
+
+    // 保存最后一个标题的笔记数量
+    if (titles.length > 0) {
+      titlesNotesCount.push(currentNoteCount)
+    }
+
+    // 更新 TOC 区域
+    this.tocGenerator.updateHomeToc(lines, titles, titlesNotesCount)
+
+    const processedLines = processEmptyLines(lines)
+
+    const updatedContent = processedLines.join(EOL)
+    writeFileSync(homeReadmePath, updatedContent, 'utf-8')
+
+    logger.info('已更新首页 README')
+  }
+}

package/core/TocGenerator.ts

@@ -0,0 +1,212 @@
+/**
+ * core/TocGenerator.ts
+ *
+ * 目录生成器 - 负责生成各种目录（TOC）
+ */
+
+import { EOL } from '../config/constants'
+import {
+  generateToc as generateTocUtil,
+  createAddNumberToTitle,
+} from '../utils'
+
+import type { NoteConfig } from '../types'
+
+// URL 常量
+const BILIBILI_VIDEO_BASE_URL = 'https://www.bilibili.com/video/'
+const TNOTES_YUQUE_BASE_URL = 'https://www.yuque.com/tdahuyou/tnotes.yuque/'
+
+// 目录开始和结束标记
+const NOTES_TOC_START_TAG = '<!-- region:toc -->'
+const NOTES_TOC_END_TAG = '<!-- endregion:toc -->'
+
+/**
+ * 目录生成器类
+ */
+export class TocGenerator {
+  /**
+   * 更新笔记目录
+   * @param noteIndex - 笔记索引
+   * @param lines - 笔记内容行数组
+   * @param noteConfig - 笔记配置
+   * @param repoName - 仓库名称
+   */
+  updateNoteToc(
+    noteIndex: string,
+    lines: string[],
+    noteConfig: NoteConfig,
+    repoName: string,
+  ): void {
+    let startLineIdx = -1,
+      endLineIdx = -1
+    lines.forEach((line, idx) => {
+      if (line.startsWith(NOTES_TOC_START_TAG)) startLineIdx = idx
+      if (line.startsWith(NOTES_TOC_END_TAG)) endLineIdx = idx
+    })
+    if (startLineIdx === -1 || endLineIdx === -1) return
+
+    const titles: string[] = []
+    const numberedHeaders = ['## ', '### '] // 2~3 级标题需要编号
+    const unnumberedHeaders = ['#### ', '##### ', '###### '] // 4~6 级标题不需要编号
+    const addNumberToTitle = createAddNumberToTitle()
+
+    // 代码块检测状态
+    let inCodeBlock = false
+    let inHtmlComment = false
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+
+      // 检测代码块边界（``` 或 ~~~）
+      if (line.trim().startsWith('```') || line.trim().startsWith('~~~')) {
+        inCodeBlock = !inCodeBlock
+        continue
+      }
+
+      // 检测 HTML 注释边界
+      if (line.trim().startsWith('<!--')) {
+        inHtmlComment = true
+      }
+      if (line.trim().includes('-->')) {
+        inHtmlComment = false
+        continue
+      }
+
+      // 跳过代码块和 HTML 注释内的内容
+      if (inCodeBlock || inHtmlComment) {
+        continue
+      }
+
+      // 检查是否是需要编号的标题（2~3 级）
+      const isNumberedHeader = numberedHeaders.some((header) =>
+        line.startsWith(header),
+      )
+      // 检查是否是不需要编号的标题（4~6 级）
+      const isUnnumberedHeader = unnumberedHeaders.some((header) =>
+        line.startsWith(header),
+      )
+
+      if (isNumberedHeader) {
+        const [numberedTitle] = addNumberToTitle(line)
+        titles.push(numberedTitle)
+        lines[i] = numberedTitle // 更新原行内容（添加编号）
+      } else if (isUnnumberedHeader) {
+        // 移除可能存在的旧编号
+        const match = line.match(/^(#+)\s*(\d+(\.\d+)*\.\s*)?(.*)/)
+        if (match) {
+          const headerSymbol = match[1]
+          const plainTitle = match[4]
+          const cleanTitle = `${headerSymbol} ${plainTitle}`
+          titles.push(cleanTitle)
+          lines[i] = cleanTitle // 更新原行内容（移除编号）
+        } else {
+          titles.push(line)
+        }
+      }
+    }
+
+    const toc = generateTocUtil(titles)
+    const bilibiliTOCItems: string[] = []
+    const tnotesTOCItems: string[] = []
+    const yuqueTOCItems: string[] = []
+
+    if (noteConfig) {
+      if (noteConfig.bilibili.length > 0) {
+        noteConfig.bilibili.forEach((bvid, i) => {
+          bilibiliTOCItems.push(
+            `  - [bilibili.${repoName}.${noteIndex}.${i + 1}](${
+              BILIBILI_VIDEO_BASE_URL + bvid
+            })`,
+          )
+        })
+      }
+      if (noteConfig.tnotes && noteConfig.tnotes.length > 0) {
+        // 生成相关知识库标题和链接列表
+        tnotesTOCItems.push(
+          `- [📒 TNotes（相关知识库）](https://tnotesjs.github.io/TNotes/)`,
+        )
+        noteConfig.tnotes.forEach((repoName) => {
+          tnotesTOCItems.push(
+            `  - [TNotes.${repoName}](https://tnotesjs.github.io/TNotes.${repoName}/)`,
+          )
+        })
+      }
+      if (noteConfig.yuque.length > 0) {
+        noteConfig.yuque.forEach((slug) => {
+          yuqueTOCItems.push(
+            `  - [TNotes.yuque.${repoName.replace(
+              'TNotes.',
+              '',
+            )}.${noteIndex}](${TNOTES_YUQUE_BASE_URL + slug})`,
+          )
+        })
+      }
+    }
+
+    const insertTocItems: string[] = []
+    const hasExternalResources =
+      bilibiliTOCItems.length > 0 ||
+      tnotesTOCItems.length > 0 ||
+      yuqueTOCItems.length > 0
+
+    if (hasExternalResources) {
+      insertTocItems.push('::: details 📚 相关资源', '')
+
+      if (bilibiliTOCItems.length > 0) {
+        insertTocItems.push(
+          `- [📺 bilibili（笔记视频资源）](https://space.bilibili.com/407241004)`,
+          ...bilibiliTOCItems,
+        )
+      }
+
+      if (tnotesTOCItems.length > 0) {
+        insertTocItems.push(...tnotesTOCItems)
+      }
+
+      if (yuqueTOCItems.length > 0) {
+        insertTocItems.push(
+          `- [📂 TNotes.yuque（笔记附件资源）](${TNOTES_YUQUE_BASE_URL})`,
+          ...yuqueTOCItems,
+        )
+      }
+
+      insertTocItems.push('', ':::', '')
+    }
+
+    lines.splice(
+      startLineIdx + 1,
+      endLineIdx - startLineIdx - 1,
+      '',
+      ...insertTocItems,
+      ...toc.replace(new RegExp(`^${EOL}`), '').split(EOL),
+    )
+  }
+
+  /**
+   * 更新首页目录
+   * @param lines - 首页内容行数组
+   * @param titles - 标题数组
+  * @param _titlesNotesCount - 每个标题下的笔记数量
+   */
+  updateHomeToc(
+    lines: string[],
+    titles: string[],
+    _titlesNotesCount: number[],
+  ): void {
+    let startLineIdx = -1,
+      endLineIdx = -1
+    lines.forEach((line, idx) => {
+      if (line.startsWith(NOTES_TOC_START_TAG)) startLineIdx = idx
+      if (line.startsWith(NOTES_TOC_END_TAG)) endLineIdx = idx
+    })
+    if (startLineIdx === -1 || endLineIdx === -1) return
+
+    const toc = generateTocUtil(titles)
+
+    lines.splice(
+      startLineIdx + 1,
+      endLineIdx - startLineIdx - 1,
+      ...toc.split(EOL),
+    )
+  }
+}

package/core/index.ts

@@ -0,0 +1,11 @@
+/**
+ * core/index.ts
+ *
+ * Core 层统一导出
+ */
+
+export { NoteManager } from './NoteManager'
+export { NoteIndexCache } from './NoteIndexCache'
+export { ReadmeGenerator } from './ReadmeGenerator'
+export { GitManager } from './GitManager'
+export { ProcessManager } from './ProcessManager'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tnotesjs/core",
-  "version": "0.2.1",
+  "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/",

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