@tnotesjs/core 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tnotesjs/core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "TNotes 知识库核心框架 —— 基于 VitePress 的笔记管理系统",
   "type": "module",
   "packageManager": "pnpm@10.17.1",

package/services/file-watcher/folderChangeHandler.ts

@@ -5,11 +5,12 @@
  */
 
 import { existsSync, promises as fsPromises } from 'fs'
-import { join } from 'path'
+import { dirname, join } from 'path'
 
 import { safeExecute } from './internal'
 import { REPO_NOTES_URL } from '../../config/constants'
 import { generateNoteTitle } from '../../config/templates'
+import { reconcileTocFromFiles } from '../reconcileToc'
 
 import type { EventScheduler } from './eventScheduler'
 import type { WatchState } from './watchState'
@@ -17,7 +18,6 @@ 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
 
@@ -41,8 +41,6 @@ interface FolderChangeHandlerConfig {
   noteService: NoteService
   /** README 服务实例 */
   readmeService: ReadmeService
-  /** TOC 服务实例 */
-  tocService: TocService
   /** 笔记索引缓存实例 */
   noteIndexCache: NoteIndexCache
   /** 日志记录器 */
@@ -89,7 +87,7 @@ export class FolderChangeHandler {
   }
 
   async handleFolderDeletion(deletedFolderName: string): Promise<void> {
-    const { scheduler, watchState, noteIndexCache, tocService, logger } =
+    const { scheduler, watchState, noteIndexCache, logger, notesDir } =
       this.config
 
     if (scheduler.getUpdating()) return
@@ -106,12 +104,11 @@ export class FolderChangeHandler {
       watchState.clearNoteCaches(deletedFolderName)
       noteIndexCache.delete(noteIndex)
 
-      // 更新根 README.md、sidebar.json
+      // files→TOC 对齐（Workspace）：TOC 行随目录消失而移除
       await safeExecute(
         `删除笔记 ${noteIndex}`,
         async () => {
-          await tocService.deleteNoteFromToc(noteIndex)
-          await tocService.regenerateSidebar()
+          await reconcileTocFromFiles(dirname(notesDir))
           this.config.onNoteStructureChanged?.(`watcher:delete:${noteIndex}`)
         },
         logger,
@@ -202,7 +199,7 @@ export class FolderChangeHandler {
     noteIndex: string,
     newName: string,
   ): Promise<void> {
-    const { noteIndexCache, tocService, logger, notesDir } = this.config
+    const { noteIndexCache, logger, notesDir } = this.config
 
     logger.info(`笔记索引未变 (${noteIndex})，只更新标题`)
     noteIndexCache.updateFolderName(noteIndex, newName)
@@ -214,8 +211,12 @@ export class FolderChangeHandler {
       logger,
     )
 
-    await tocService.renameNoteInToc(noteIndex, newName)
-    await tocService.regenerateSidebar()
+    // files→TOC 对齐（Workspace）：标题以目录名为准，行位置/完成标记保留
+    await safeExecute(
+      `标题重命名同步目录 ${noteIndex}`,
+      () => reconcileTocFromFiles(dirname(notesDir)),
+      logger,
+    )
     this.config.onNoteStructureChanged?.(`watcher:rename-title:${noteIndex}`)
     logger.success(`标题更新完成`)
   }
@@ -266,11 +267,16 @@ export class FolderChangeHandler {
     oldNoteIndex: string,
     newNoteIndex: string,
   ): Promise<void> {
-    const { noteService, noteIndexCache, tocService, logger } = this.config
+    const { noteService, noteIndexCache, logger, notesDir } = this.config
 
     logger.info(`笔记索引变更: ${oldNoteIndex} → ${newNoteIndex}`)
 
-    await tocService.deleteNoteFromToc(oldNoteIndex)
+    // files→TOC 对齐（Workspace）：旧索引行随目录消失移除，新索引行按编号追加
+    await safeExecute(
+      `索引变更同步目录 ${oldNoteIndex}→${newNoteIndex}`,
+      () => reconcileTocFromFiles(dirname(notesDir)),
+      logger,
+    )
 
     const newNote = noteService.getNoteByIndex(newNoteIndex)
 
@@ -278,8 +284,6 @@ export class FolderChangeHandler {
       noteIndexCache.delete(oldNoteIndex)
       noteIndexCache.add(newNote)
 
-      await tocService.appendNoteToToc(newNoteIndex)
-      await tocService.regenerateSidebar()
       this.config.onNoteStructureChanged?.(
         `watcher:rename-index:${oldNoteIndex}->${newNoteIndex}`,
       )

package/services/file-watcher/globalUpdateCoordinator.ts

@@ -1,25 +1,26 @@
 /**
  * services/file-watcher/globalUpdateCoordinator.ts
  *
- * 全局更新协调：应用配置更新、更新 README 列表
+ * 全局更新协调：应用配置更新、更新 README 列表。
+ * TOC/sidebar 的写入统一走 Workspace 的 `toc.reconcileFromFiles()`
+ * （0004 方案 B），不再直接操作 TocService。
  */
 
+import { dirname } from 'path'
+
 import { safeExecute } from './internal'
+import { reconcileTocFromFiles } from '../reconcileToc'
 
 import type { WatchEvent } from './internal'
-import type { NoteIndexCache } from '../../core/NoteIndexCache'
 import type { Logger } from '../../utils'
 import type { ReadmeService } from '../readme/service'
-import type { TocService } from '../toc/service'
 
 
 interface GlobalUpdateCoordinatorConfig {
+  /** 笔记目录路径 */
+  notesDir: string
   /** README 服务实例，用于更新笔记 README */
   readmeService: ReadmeService
-  /** TOC 服务实例，用于更新 TOC.md 与 sidebar */
-  tocService: TocService
-  /** 笔记索引缓存实例 */
-  noteIndexCache: NoteIndexCache
   /** 日志记录器 */
   logger: Logger
 }
@@ -30,26 +31,19 @@ export class GlobalUpdateCoordinator {
   async applyConfigUpdates(changedNoteIndexes: string[]): Promise<void> {
     if (changedNoteIndexes.length === 0) return
 
-    const { tocService, noteIndexCache, logger } = this.config
-
-    logger.info('检测到笔记状态变化，增量更新全局文件...')
-
-    for (const noteIndex of changedNoteIndexes) {
-      await safeExecute(
-        `增量更新 ${noteIndex}`,
-        async () => {
-          const item = noteIndexCache.getByNoteIndex(noteIndex)
-          await tocService.updateNoteInToc(
-            noteIndex,
-            item?.noteConfig || {},
-          )
-          logger.info(`增量更新 TOC.md 中的笔记: ${noteIndex}`)
-        },
-        logger,
-      )
-    }
-
-    await tocService.regenerateSidebar()
+    const { logger, notesDir } = this.config
+
+    logger.info('检测到笔记状态变化，同步全局文件...')
+
+    // files→TOC 对齐（Workspace）：config.done 等以文件为真值，
+    // 同步到 TOC 行标记与 sidebar。
+    await safeExecute(
+      '配置变更同步目录',
+      () => reconcileTocFromFiles(dirname(notesDir)),
+      logger,
+    )
+
+    logger.info(`已同步配置变更的笔记: ${changedNoteIndexes.join(', ')}`)
   }
 
   async updateNoteReadmesOnly(events: WatchEvent[]): Promise<void> {

package/services/file-watcher/service.ts

@@ -24,7 +24,6 @@ import { NoteIndexCache } from '../../core/NoteIndexCache'
 import { logger } from '../../utils'
 import { NoteService } from '../note/service'
 import { ReadmeService } from '../readme/service'
-import { TocService } from '../toc/service'
 
 import type { WatchEvent } from './internal'
 
@@ -49,7 +48,6 @@ export class FileWatcherService {
   private adapter!: FsWatcherAdapter
   private noteService!: NoteService
   private readmeService!: ReadmeService
-  private tocService!: TocService
   private noteIndexCache!: NoteIndexCache
   private unlockTimer: NodeJS.Timeout | null = null
 
@@ -68,7 +66,6 @@ export class FileWatcherService {
   private init(): void {
     this.noteService = NoteService.getInstance()
     this.readmeService = ReadmeService.getInstance()
-    this.tocService = TocService.getInstance()
     this.noteIndexCache = NoteIndexCache.getInstance()
 
     this.watchState = this.initWatchState()
@@ -103,7 +100,6 @@ export class FileWatcherService {
       scheduler: this.scheduler,
       noteService: this.noteService,
       readmeService: this.readmeService,
-      tocService: this.tocService,
       noteIndexCache: this.noteIndexCache,
       logger,
       onRenameSuccess: (payload) => {
@@ -228,9 +224,8 @@ export class FileWatcherService {
 
   private initCoordinator(): GlobalUpdateCoordinator {
     return new GlobalUpdateCoordinator({
+      notesDir: this.notesDir,
       readmeService: this.readmeService,
-      tocService: this.tocService,
-      noteIndexCache: this.noteIndexCache,
       logger,
     })
   }

package/services/index.ts

@@ -8,7 +8,6 @@ export { FileWatcherService } from './file-watcher'
 export { GitService } from './git'
 export { NoteService } from './note'
 export { ReadmeService } from './readme'
-export { TocService } from './toc'
 export { VitepressService } from './vitepress'
 export { InitSubRepoService } from './init-sub-repo'
 export * from './init-sub-repo/initSubRepoLogic'

package/services/note/service.ts

@@ -8,7 +8,7 @@ import { writeFileSync, readFileSync, promises as fsPromises } from 'fs'
 import { join } from 'path'
 import { v4 as uuidv4 } from 'uuid'
 
-import { NOTES_PATH, CONSTANTS, REPO_NOTES_URL } from '../../config/constants'
+import { NOTES_PATH, CONSTANTS, REPO_NOTES_URL, ROOT_DIR_PATH } from '../../config/constants'
 import {
   generateNoteTitle,
   getNewNoteReadmeBody,
@@ -16,7 +16,7 @@ import {
 import { NoteIndexCache } from '../../core/NoteIndexCache'
 import { NoteManager } from '../../core/NoteManager'
 import { ensureDirectory, logger } from '../../utils'
-import { TocService } from '../toc/service'
+import { reconcileTocFromFiles } from '../reconcileToc'
 
 import type { NoteInfo, NoteConfig } from '../../types'
 
@@ -247,10 +247,8 @@ export class NoteService {
       logger.info(`检测到全局字段变更 (${noteIndex})，正在增量更新全局文件...`)
 
       // 使用增量更新
-      const tocService = TocService.getInstance()
-
-      await tocService.updateNoteInToc(noteIndex, updates)
-      await tocService.regenerateSidebar()
+      // files→TOC 对齐（Workspace）：config 已写盘，同步 TOC 行标记与 sidebar
+      await reconcileTocFromFiles(ROOT_DIR_PATH)
 
       logger.info(`全局文件增量更新完成 (${noteIndex})`)
     } else {

package/services/readme/service.ts

@@ -12,7 +12,7 @@ import {
 } from 'fs'
 
 import { ConfigManager } from '../../config/ConfigManager'
-import { ROOT_README_PATH, VP_SIDEBAR_PATH } from '../../config/constants'
+import { ROOT_DIR_PATH, ROOT_README_PATH, VP_SIDEBAR_PATH } from '../../config/constants'
 import { NoteIndexCache } from '../../core/NoteIndexCache'
 import { NoteManager } from '../../core/NoteManager'
 import { ReadmeGenerator } from '../../core/ReadmeGenerator'
@@ -24,7 +24,8 @@ import {
   genHierarchicalSidebar,
   processEmptyLines,
 } from '../../utils'
-import { TocService } from '../toc/service'
+import { reconcileTocFromFiles } from '../reconcileToc'
+
 
 import type { NoteInfo, NoteConfig } from '../../types'
 
@@ -60,14 +61,12 @@ export class ReadmeService {
   private readmeGenerator: ReadmeGenerator
   private configManager: ConfigManager
   private noteIndexCache: NoteIndexCache
-  private tocService: TocService
 
   private constructor() {
     this.noteManager = NoteManager.getInstance()
     this.readmeGenerator = new ReadmeGenerator()
     this.configManager = ConfigManager.getInstance()
     this.noteIndexCache = NoteIndexCache.getInstance()
-    this.tocService = TocService.getInstance()
   }
 
   static getInstance(): ReadmeService {
@@ -121,10 +120,9 @@ export class ReadmeService {
       await this.updateHomeReadme(notes)
     }
 
-    // 规范化 TOC.md 并更新 sidebar.json
+    // files→TOC 对齐（Workspace）：规范化 TOC.md 并重建 sidebar.json
     if (updateSidebar) {
-      await this.tocService.normalizeToc(notes)
-      await this.tocService.regenerateSidebar(notes)
+      await reconcileTocFromFiles(ROOT_DIR_PATH)
     }
 
     logger.info('知识库更新完成！')
@@ -618,23 +616,18 @@ export class ReadmeService {
   /**
    * 更新 TOC.md 和 sidebar，不重写每篇笔记 README
    */
-  async refreshHomeReadmeAndSidebar(notes?: NoteInfo[]): Promise<void> {
-    const allNotes =
-      notes ??
-      (this.noteIndexCache.isInitialized()
-        ? this.noteIndexCache.toNoteInfoList()
-        : this.noteManager.scanNotes())
-
-    await this.tocService.normalizeToc(allNotes)
-    await this.tocService.regenerateSidebar(allNotes)
+  async refreshHomeReadmeAndSidebar(_notes?: NoteInfo[]): Promise<void> {
+    // files→TOC 对齐（Workspace）：TOC.md 规范化 + sidebar 重建
+    await reconcileTocFromFiles(ROOT_DIR_PATH)
   }
 
   /**
    * 重新生成 sidebar.json（基于当前 TOC.md）
    * @param notes - 可选的笔记列表，不传则内部扫描
    */
-  async regenerateSidebar(notes?: NoteInfo[]): Promise<void> {
-    await this.tocService.regenerateSidebar(notes)
+  async regenerateSidebar(_notes?: NoteInfo[]): Promise<void> {
+    // files→TOC 对齐（Workspace）：sidebar 由重建的 TOC 派生
+    await reconcileTocFromFiles(ROOT_DIR_PATH)
     logger.info('重新生成 sidebar.json')
   }
 

package/services/reconcileToc.ts

@@ -0,0 +1,20 @@
+/**
+ * services/reconcileToc.ts
+ *
+ * CLI / 服务侧的「files→TOC 对齐」入口（0004 方案 B）：
+ * 统一的 TOC/sidebar 写入都收敛到 Core Workspace 的
+ * `toc.reconcileFromFiles()`，不再直接操作 TocService。
+ */
+import { createWorkspace, type TNotesWorkspace } from '../workspace'
+
+const workspaces = new Map<string, TNotesWorkspace>()
+
+/** 知识库根目录 → 常驻 Workspace 实例（幂等，可重复调用）。 */
+export async function reconcileTocFromFiles(repoRoot: string): Promise<void> {
+  let workspace = workspaces.get(repoRoot)
+  if (!workspace) {
+    workspace = createWorkspace({ rootPath: repoRoot })
+    workspaces.set(repoRoot, workspace)
+  }
+  await workspace.toc.reconcileFromFiles()
+}

package/utils/index.ts

@@ -52,15 +52,6 @@ export type {
   TocSidebarItem,
   TocLineKind,
 } from './tocHelpers'
-export {
-  migrateReadmeToToc,
-  extractReadmeBodyAfterToc,
-  README_TOC_END_TAG,
-} from './migrateReadmeToToc'
-export type {
-  MigratedTocEntry,
-  MigrateReadmeToTocResult,
-} from './migrateReadmeToToc'
 export { isPortInUse, killPortProcess, waitForPort } from './portUtils'
 export {
   parseNoteLine,

package/{services/toc → utils}/moveTocInside.test.ts

@@ -11,7 +11,7 @@ import {
   getTocEntrySubtreeRange,
   parseTocLine,
   TOC_INDENT_SPACES,
-} from '../../utils/tocHelpers'
+} from './tocHelpers'
 
 function adjustSubtreeIndent(lines: string[], delta: number): string[] {
   if (delta === 0) return lines

package/vitepress/components/constants.ts

@@ -108,11 +108,11 @@ export const TOC_MD: string = TOC + '.md'
  * https://github.com/tnotesjs/en-words/blob/main/{word}.md
  */
 export const EN_WORDS_REPO_BASE_URL: string =
-  'https://github.com/tnotesjs/TNotes.en-words/blob/main/'
+  'https://github.com/tnotesjs/en-words/blob/main/'
 
 /**
  * 英语单词仓库 raw 地址
  * https://raw.githubusercontent.com/tnotesjs/TNotes.en-words/refs/heads/main/{word}.md
  */
 export const EN_WORDS_REPO_BASE_RAW_URL: string =
-  'https://raw.githubusercontent.com/tnotesjs/TNotes.en-words/refs/heads/main/'
+  'https://raw.githubusercontent.com/tnotesjs/en-words/refs/heads/main/'

package/vitepress/components/sidebar.data.ts

@@ -5,15 +5,19 @@
 import fs from 'node:fs'
 import path from 'node:path'
 
-import { TocService } from '../../services/toc/service'
+import { ROOT_DIR_PATH } from '../../config/constants'
+import { createWorkspace } from '../../workspace'
 
-const rootPath = process.cwd()
+const rootPath = ROOT_DIR_PATH
 const sidebarFilePath = path.resolve(rootPath, 'sidebar.json')
 const tocFilePath = path.resolve(rootPath, 'TOC.md')
 
+const workspace = createWorkspace({ rootPath })
+
 /**
  * VitePress Data Loader for Sidebar
- * 以 TOC.md 为唯一数据源，加载前重建 sidebar.json，并监听 TOC/sidebar 变化做 HMR
+ * 以 TOC.md 为唯一数据源，加载前用 Workspace 对齐（files→TOC）重建 sidebar.json，
+ * 并监听 TOC/sidebar 变化做 HMR
  */
 
 interface SidebarItem {
@@ -37,8 +41,7 @@ export default {
 
   async load(): Promise<SidebarConfig> {
     try {
-      const tocService = TocService.getInstance()
-      await tocService.regenerateSidebar()
+      await workspace.toc.reconcileFromFiles()
 
       const fileContent = fs.readFileSync(sidebarFilePath, 'utf-8')
       const sidebarArray = JSON.parse(fileContent) as SidebarGroup[]