share-home 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# Share Home (局域网协作平台)
+
+**Share Home** 是一款专为局域网（Lan）办公打造的**去中心化、私密极速、零配置**的高端协作办公平台。平台融合了极速点对点大文件收发、类飞书云文档知识库协作、以及动态持久化配置等功能，并采用前沿大厂极简 Zinc 中性冷灰视觉规范重塑，为团队局域网协作带来极致高效、安全的轻量化体验。
+
+---
+
+## ✨ 核心特性
+
+### 1. 📂 极速文件流 (File Transfer Hub)
+- **免压极速**：支持局域网内任意大小大文件、文本文件的极速无损传输，不经过外网服务器，速度受限仅取决于局域网物理带宽。
+- **自发现雷达**：基于 mDNS (多播 DNS) 协议，开启即自动捕获同一局域网内所有在线的协作节点，无需手动配置 IP。
+- **断点续传**：基于流式写和 Range 请求，完美支持网络瞬断后的续传保护。
+- **动态路径**：传输文件物理落盘路径支持在系统配置中动态修改。
+
+### 2. 📝 去中心化“飞书云文档”知识库 (Knowledge Base)
+- **混合编写**：打破富文本与代码的壁垒，支持在一个编辑器内自由书写段落，并插入多语种标准 Markdown 代码块。
+- **物理落盘**：文档在服务器端均以标准的 `.md` 格式文件物理存储（包含 Front Matter 元数据头部），对第三方工具（如 Obsidian、VS Code）完全透明且兼容。
+- **防抖自动保存**：内置 `1000ms` 无感防抖自动落盘逻辑，打字即存，免去手动保存烦恼。
+- **多端秒级同步**：采用 WebSocket + 局域网广播机制，本端编辑完成落盘后自动投递至所有在线 Peer 节点。对端接收后不仅刷新浏览器视图，还直接在各自的本地存储路径下物理落盘，实现去中心化的完美分布式备份。
+
+### 3. ⚙️ 动态参数持久化配置 (System Configuration)
+- **零重启应用**：支持在页面中实时更改默认的文件和文档存储目录（默认相对路径为 `./storage`）。
+- **写权限预检**：后端在保存配置时会自动对目标目录执行物理写权限预检测试（通过测试写入并销毁 `.write_test` 文件），校验通过方可应用，防错防灾。
+- **硬核参数展示**：一站式展示本端设备 IP 地址、信道端口、以及系统各底层微服务运行状态。
+
+### 4. 🎨 科技大厂极简视觉 (Premium UI/UX)
+- **Zinc 奢华灰度**：基于大厂高端 Zinc/Slate 冷灰色调进行全面重构，配合精致的毛玻璃材质（Backdrop Filter）与极细微光边框，信息层级清晰、视感大气耐看。
+- **Sidebar 交互规范**：采用 `Sidebar（左侧边栏） + Workspace（右主工作区）` 的专业后台交互体系，配合贝塞尔曲线平滑淡入动效，让每一次切换都纵享丝滑。
+
+---
+
+## 🛠️ 技术栈
+
+- **前端核心**：React 19, Next.js 16, TypeScript
+- **视觉层**：Vanilla CSS (CSS Variables), Lucide Icons
+- **通信/发现**：WebSocket (ws), mDNS (bonjour-service)
+- **渲染与高亮**：Prism.js (Tomorrow Dark Theme)
+- **底层存贮**：Node.js fs, path 流式文件系统
+
+---
+
+## 🚀 快速启动
+
+在开始之前，请确保本地已安装 [Node.js](https://nodejs.org/) 以及包管理器 [pnpm](https://pnpm.io/)。
+
+### 1. 克隆并安装依赖
+```bash
+# 复制项目并进入目录
+git clone https://github.com/18755120710/Share-Home.git
+cd Share-Home
+
+# 使用 pnpm 安装依赖
+pnpm install
+```
+
+### 2. 启动开发服务器
+```bash
+pnpm dev
+```
+启动后，控制台将输出本端设备在局域网中的监听端口及 Web 访问地址。打开浏览器访问对应的 `http://localhost:3000` 或本地 IP 即可进入平台。
+
+### 3. 系统持久化配置
+项目根目录下会生成一个 `config-settings.json` 隐藏参数配置文件：
+```json
+{
+  "storagePath": "./storage"
+}
+```
+- **相对路径**：以 `./` 开头，将自动创建于项目根目录下。
+- **绝对路径**：可以直接填写您本机的绝对物理目录路径（如 `D:/MySharedDocuments`）。
+
+---
+
+## 🌐 局域网协同要点
+
+为了让多台设备相互发现并进行极速协同，请确保：
+1. 所有协作设备均接入**同一局域网**（或连接同一 Wi-Fi）。
+2. 本机防火墙已为 Node.js / Next.js 放行相应的 TCP **网络端口端口**。
+3. 如果在协同编辑文档或收发大文件时遇到握手失败，建议手动重启一下各端开发服务。
+
+---
+
+## 📄 开源许可证
+
+本项目基于 MIT License 协议开源。

package/bin/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const { fork } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+console.log('\x1b[36m%s\x1b[0m', '🚀 正在启动 Share Home 局域网协作平台...');
+
+const projectRoot = path.join(__dirname, '..');
+
+// 1. 确保在用户当前运行命令的目录下（或宿主临时目录）创建存储空间，实现免侵入、免污染运行
+const userStorageDir = path.join(process.cwd(), 'share-home-storage');
+if (!fs.existsSync(userStorageDir)) {
+  try {
+    fs.mkdirSync(userStorageDir, { recursive: true });
+    fs.mkdirSync(path.join(userStorageDir, 'shared'), { recursive: true });
+    console.log(`[CLI] 已在当前目录下初始化物理存储舱: ${userStorageDir}`);
+  } catch (err) {
+    console.error(`[CLI] 创建本地存储目录失败: ${err.message}`);
+  }
+}
+
+// 2. 注入环境变量，使 Next.js 服务能够动态读取该路径
+process.env.PORT = '8301';
+process.env.HOSTNAME = '0.0.0.0';
+process.env.NEXT_SHARP_PATH = 'none'; // 避免 sharp 依赖报错
+
+// 3. 编程式寻找 Next.js 核心执行文件
+const nextBin = path.join(projectRoot, 'node_modules', 'next', 'dist', 'bin', 'next');
+
+if (!fs.existsSync(nextBin)) {
+  console.error('\x1b[31m%s\x1b[0m', '❌ 错误: 未能在包中找到 Next.js 核心执行文件，请确保已经完成 pnpm install！');
+  process.exit(1);
+}
+
+console.log(`[CLI] 正在极速拉起 Web 协同服务与信道，请稍候...`);
+
+// 启动 Next.js 生产服务
+const nextStart = fork(nextBin, ['start', '-p', '8301', '-H', '0.0.0.0'], {
+  cwd: projectRoot,
+  env: {
+    ...process.env,
+    // 强制指定项目的物理存储目录，解决宿主物理存储隔离问题
+    CUSTOM_STORAGE_PATH: userStorageDir
+  }
+});
+
+nextStart.on('exit', (code) => {
+  console.log(`[CLI] Next.js 服务进程已退出，代码: ${code}`);
+  process.exit(code || 0);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "share-home",
+  "version": "1.0.0",
+  "description": "安全、无压缩的局域网零阻碍点对点极速传输与公共落盘共享空间",
+  "bin": {
+    "share-home": "bin/cli.js"
+  },
+  "preferGlobal": true,
+  "files": [
+    "bin/",
+    ".next/",
+    "public/",
+    "package.json",
+    "README.md",
+    "src/services/",
+    "tsconfig.json"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "next dev --webpack -H 0.0.0.0 -p 8301",
+    "build": "next build --webpack",
+    "start": "next start -p 8301",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@tiptap/core": "^3.23.6",
+    "@tiptap/extension-placeholder": "^3.23.6",
+    "@tiptap/pm": "^3.23.6",
+    "@tiptap/react": "^3.23.6",
+    "@tiptap/starter-kit": "^3.23.6",
+    "bonjour-service": "^1.4.0",
+    "lucide-react": "^1.16.0",
+    "next": "16.2.6",
+    "prismjs": "^1.30.0",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tiptap-markdown": "^0.9.0",
+    "ws": "^8.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/prismjs": "^1.26.6",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@types/ws": "^8.18.1",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.6",
+    "typescript": "^5"
+  }
+}

package/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/src/services/configService.ts

@@ -0,0 +1,144 @@
+import fs from 'fs';
+import path from 'path';
+
+interface AppConfig {
+  storagePath: string;
+}
+
+export class ConfigService {
+  private configFilePath: string;
+  private currentConfig: AppConfig;
+
+  private constructor() {
+    this.configFilePath = path.join(process.cwd(), 'config-settings.json');
+    this.currentConfig = this.loadConfig();
+  }
+
+  public static getInstance(): ConfigService {
+    const globalSymbols = global as any;
+    if (!globalSymbols.__config_service_instance__) {
+      globalSymbols.__config_service_instance__ = new ConfigService();
+    }
+    return globalSymbols.__config_service_instance__;
+  }
+
+  /**
+   * 从文件载入配置，若无则初始化默认配置
+   */
+  private loadConfig(): AppConfig {
+    const defaultConfig: AppConfig = {
+      storagePath: './storage',
+    };
+
+    try {
+      if (fs.existsSync(this.configFilePath)) {
+        const fileContent = fs.readFileSync(this.configFilePath, 'utf-8');
+        const parsed = JSON.parse(fileContent);
+        return {
+          ...defaultConfig,
+          ...parsed,
+        };
+      }
+    } catch (err) {
+      console.error('[ConfigService] 载入配置文件失败，将使用默认配置:', err);
+    }
+
+    // 若无配置文件，创建默认的配置文件
+    this.saveConfig(defaultConfig);
+    return defaultConfig;
+  }
+
+  /**
+   * 保存配置到 config-settings.json 文件
+   */
+  private saveConfig(config: AppConfig): void {
+    try {
+      fs.writeFileSync(this.configFilePath, JSON.stringify(config, null, 2), 'utf-8');
+    } catch (err) {
+      console.error('[ConfigService] 持久化保存配置文件失败:', err);
+    }
+  }
+
+  /**
+   * 获取当前配置
+   */
+  public getConfig(): AppConfig {
+    return { ...this.currentConfig };
+  }
+
+  /**
+   * 获取当前已解析的绝对存储路径，若目录不存在则自动创建
+   */
+  public getStoragePath(): string {
+    // 优先读取 CLI 或环境变量中强制指定的存储目录，解决全局发布环境下的宿主文件隔离
+    if (process.env.CUSTOM_STORAGE_PATH) {
+      const cliPath = process.env.CUSTOM_STORAGE_PATH;
+      try {
+        if (!fs.existsSync(cliPath)) {
+          fs.mkdirSync(cliPath, { recursive: true });
+          console.log(`[ConfigService] 已根据环境变量创建存储目录: ${cliPath}`);
+        }
+      } catch (err) {
+        console.error(`[ConfigService] 物理环境变量目录创建失败: ${cliPath}`, err);
+      }
+      return cliPath;
+    }
+
+    const rawPath = this.currentConfig.storagePath;
+    let resolvedPath = '';
+
+    if (path.isAbsolute(rawPath)) {
+      resolvedPath = rawPath;
+    } else {
+      resolvedPath = path.resolve(process.cwd(), rawPath);
+    }
+
+    // 确保物理目录存在
+    try {
+      if (!fs.existsSync(resolvedPath)) {
+        fs.mkdirSync(resolvedPath, { recursive: true });
+        console.log(`[ConfigService] 成功创建存储目录: ${resolvedPath}`);
+      }
+    } catch (err) {
+      console.error(`[ConfigService] 物理目录创建失败: ${resolvedPath}`, err);
+    }
+
+    return resolvedPath;
+  }
+
+  /**
+   * 动态更新存储路径配置
+   */
+  public updateStoragePath(newPath: string): boolean {
+    if (!newPath || !newPath.trim()) return false;
+    
+    const sanitizedPath = newPath.trim();
+    
+    // 预检该路径是否能够成功创建或写入
+    let testPath = '';
+    if (path.isAbsolute(sanitizedPath)) {
+      testPath = sanitizedPath;
+    } else {
+      testPath = path.resolve(process.cwd(), sanitizedPath);
+    }
+
+    try {
+      if (!fs.existsSync(testPath)) {
+        fs.mkdirSync(testPath, { recursive: true });
+      }
+      // 成功写入测试文件来验证写权限
+      const testFile = path.join(testPath, '.write_test');
+      fs.writeFileSync(testFile, 'test');
+      fs.unlinkSync(testFile);
+    } catch (err) {
+      console.error(`[ConfigService] 无法使用此存储路径（无写权限或路径无效）: ${sanitizedPath}`, err);
+      return false;
+    }
+
+    // 更新内存及文件
+    this.currentConfig.storagePath = sanitizedPath;
+    this.saveConfig(this.currentConfig);
+    console.log(`[ConfigService] 存储路径成功修改为: ${sanitizedPath}`);
+    return true;
+  }
+}

package/src/services/documentService.ts

@@ -0,0 +1,210 @@
+import fs from 'fs';
+import path from 'path';
+import { KBDocument } from '@/types/document';
+import { ConfigService } from './configService';
+
+export class DocumentService {
+  private constructor() {}
+
+  public static getInstance(): DocumentService {
+    const globalSymbols = global as any;
+    if (!globalSymbols.__document_service_instance__) {
+      globalSymbols.__document_service_instance__ = new DocumentService();
+    }
+    return globalSymbols.__document_service_instance__;
+  }
+
+  /**
+   * 获取文档保存的 docs 子物理路径
+   */
+  private getDocsDir(): string {
+    const storagePath = ConfigService.getInstance().getStoragePath();
+    const docsDir = path.join(storagePath, 'docs');
+    if (!fs.existsSync(docsDir)) {
+      fs.mkdirSync(docsDir, { recursive: true });
+    }
+    return docsDir;
+  }
+
+  /**
+   * 将文档对象序列化为带 Front Matter 的标准 Markdown 字符串
+   */
+  private serialize(doc: KBDocument): string {
+    // 过滤掉内容里的 yaml 分割符，确保 Front Matter 解析稳健
+    return [
+      '---',
+      `id: ${doc.id}`,
+      `title: ${doc.title.replace(/:/g, ' ')}`,
+      `senderId: ${doc.senderId}`,
+      `senderName: ${doc.senderName}`,
+      `senderAvatar: ${doc.senderAvatar}`,
+      `updatedAt: ${doc.updatedAt}`,
+      `createdAt: ${doc.createdAt}`,
+      `type: ${doc.type || 'file'}`,
+      `parentId: ${doc.parentId || ''}`,
+      '---',
+      doc.content
+    ].join('\n');
+  }
+
+  /**
+   * 从带 Front Matter 的 Markdown 文本中解析出 KBDocument
+   */
+  private deserialize(fileContent: string): KBDocument | null {
+    try {
+      const lines = fileContent.split(/\r?\n/);
+      if (lines[0]?.trim() !== '---') return null;
+
+      let endIdx = -1;
+      for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trim() === '---') {
+          endIdx = i;
+          break;
+        }
+      }
+
+      if (endIdx === -1) return null;
+
+      const metaLines = lines.slice(1, endIdx);
+      const content = lines.slice(endIdx + 1).join('\n');
+      
+      const meta: any = {};
+      metaLines.forEach(line => {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex !== -1) {
+          const key = line.substring(0, colonIndex).trim();
+          const value = line.substring(colonIndex + 1).trim();
+          meta[key] = value;
+        }
+      });
+
+      return {
+        id: meta.id || '',
+        title: meta.title || '无标题文档',
+        senderId: meta.senderId || 'unknown',
+        senderName: meta.senderName || '匿名',
+        senderAvatar: meta.senderAvatar || 'avatar-1',
+        updatedAt: parseInt(meta.updatedAt || '0', 10) || Date.now(),
+        createdAt: parseInt(meta.createdAt || '0', 10) || Date.now(),
+        type: (meta.type as 'file' | 'folder') || 'file',
+        parentId: meta.parentId || null,
+        content: content
+      };
+    } catch (err) {
+      console.error('[DocumentService] 反序列化 Markdown 失败:', err);
+      return null;
+    }
+  }
+
+  /**
+   * 获取本地所有的文档列表（不包含大体量的 content）
+   */
+  public getDocuments(): KBDocument[] {
+    const docsDir = this.getDocsDir();
+    const docs: KBDocument[] = [];
+
+    try {
+      const files = fs.readdirSync(docsDir);
+      files.forEach(fileName => {
+        if (fileName.endsWith('.md')) {
+          const filePath = path.join(docsDir, fileName);
+          const fileContent = fs.readFileSync(filePath, 'utf-8');
+          const doc = this.deserialize(fileContent);
+          if (doc) {
+            docs.push(doc);
+          }
+        }
+      });
+    } catch (err) {
+      console.error('[DocumentService] 读取文档列表异常:', err);
+    }
+
+    // 按最近更新时间倒序排列
+    return docs.sort((a, b) => b.updatedAt - a.updatedAt);
+  }
+
+  /**
+   * 读取单篇文档的详情
+   */
+  public getDocumentById(id: string): KBDocument | null {
+    const docsDir = this.getDocsDir();
+    try {
+      const files = fs.readdirSync(docsDir);
+      for (const fileName of files) {
+        if (fileName.endsWith('.md')) {
+          const filePath = path.join(docsDir, fileName);
+          const fileContent = fs.readFileSync(filePath, 'utf-8');
+          const doc = this.deserialize(fileContent);
+          if (doc && doc.id === id) {
+            return doc;
+          }
+        }
+      }
+    } catch (err) {
+      console.error(`[DocumentService] 获取文档详情失败 id: ${id}`, err);
+    }
+    return null;
+  }
+
+  /**
+   * 保存或更新文档落盘
+   */
+  public saveDocument(doc: KBDocument): boolean {
+    const docsDir = this.getDocsDir();
+    try {
+      // 安全的文件名规范：文档ID_标题.md
+      const safeTitle = doc.title.replace(/[\\/:*?"<>|]/g, '_');
+      
+      // 在写入新文件前，若有旧标题同 ID 的 md，先予删除，防止产生垃圾冗余文件
+      const files = fs.readdirSync(docsDir);
+      for (const fileName of files) {
+        if (fileName.endsWith('.md')) {
+          const filePath = path.join(docsDir, fileName);
+          const fileContent = fs.readFileSync(filePath, 'utf-8');
+          const oldDoc = this.deserialize(fileContent);
+          if (oldDoc && oldDoc.id === doc.id) {
+            fs.unlinkSync(filePath);
+            break;
+          }
+        }
+      }
+
+      // 写入新文件
+      const finalFileName = `${doc.id}_${safeTitle}.md`;
+      const finalPath = path.join(docsDir, finalFileName);
+      const serialized = this.serialize(doc);
+      
+      fs.writeFileSync(finalPath, serialized, 'utf-8');
+      console.log(`[DocumentService] 文档成功写入物理落盘: ${finalPath}`);
+      return true;
+    } catch (err) {
+      console.error(`[DocumentService] 文档落盘失败: ${doc.title}`, err);
+      return false;
+    }
+  }
+
+  /**
+   * 删除本地文档
+   */
+  public deleteDocument(id: string): boolean {
+    const docsDir = this.getDocsDir();
+    try {
+      const files = fs.readdirSync(docsDir);
+      for (const fileName of files) {
+        if (fileName.endsWith('.md')) {
+          const filePath = path.join(docsDir, fileName);
+          const fileContent = fs.readFileSync(filePath, 'utf-8');
+          const doc = this.deserialize(fileContent);
+          if (doc && doc.id === id) {
+            fs.unlinkSync(filePath);
+            console.log(`[DocumentService] 文档物理文件已删除: ${filePath}`);
+            return true;
+          }
+        }
+      }
+    } catch (err) {
+      console.error(`[DocumentService] 删除文档失败: ${id}`, err);
+    }
+    return false;
+  }
+}