Eidos开发实践：从零开始构建个人数据管理应用-优快云博客

Eidos开发实践：从零开始构建个人数据管理应用

【免费下载链接】eidos Offline alternative to Notion. Eidos is an extensible framework for managing your personal data throughout your lifetime in one place. 项目地址: https://gitcode.com/GitHub_Trending/ei/eidos

本文详细介绍了Eidos框架的开发实践，从环境搭建到扩展开发的完整流程。首先讲解了如何使用pnpm workspace配置现代化的monorepo架构，包括环境要求、项目初始化、依赖管理和多包架构解析。然后深入探讨了Eidos的核心包结构和模块依赖关系，包括核心数据管理、工具库和AI功能集成。最后通过实战案例展示了自定义扩展开发，包括数据清洗脚本、日历视图和AI摘要工具等多种扩展类型。

开发环境搭建与pnpm workspace配置

Eidos作为一个现代化的个人数据管理框架，采用了pnpm workspace来管理其复杂的多包架构。这种架构设计使得项目能够高效地组织桌面应用、Web应用、文档站点以及多个核心功能包。本文将详细介绍如何从零开始搭建Eidos的开发环境，并深入理解其pnpm workspace配置。

环境要求与前置准备

在开始之前，请确保您的系统满足以下基本要求：

组件	版本要求	说明
Node.js	≥ 18.0.0	推荐使用LTS版本
pnpm	≥ 8.5.0	必须使用pnpm包管理器
Git	最新版本	用于代码版本控制

安装pnpm（如果尚未安装）：

# 使用npm安装pnpm
npm install -g pnpm

# 或者使用其他包管理器
# corepack enable pnpm

项目克隆与初始化

首先克隆Eidos项目到本地：

git clone https://gitcode.com/GitHub_Trending/ei/eidos.git
cd eidos

项目采用monorepo结构，使用pnpm workspace进行管理。查看项目根目录的pnpm-workspace.yaml配置文件：

packages:
  # all packages in direct subdirs of packages/
  - "packages/*"
  - "apps/*"
  # exclude packages that are inside test directories
  - "!**/test/**"

这个配置定义了workspace的范围，包含了packages/和apps/目录下的所有子包，同时排除了测试目录。

依赖安装与workspace解析

运行pnpm install安装所有依赖：

pnpm install

pnpm workspace的工作原理如下：

mermaid

安装完成后，pnpm会创建一个符号链接结构，使得各个包能够相互引用。您可以通过以下命令查看workspace的状态：

# 查看workspace包列表
pnpm list --depth -1

# 查看特定包的依赖关系
pnpm why <package-name>

多包架构解析

Eidos的workspace包含多个功能模块：

包类型	目录	功能描述
桌面应用	`apps/desktop`	Electron桌面客户端
Web应用	`apps/web-app`	PWA网页应用
文档站点	`apps/docs`	项目文档网站
核心库	`packages/core`	数据管理和SQLite操作
工具库	`packages/lib`	通用工具函数和组件
AI功能	`packages/ai`	AI集成和向量搜索

开发脚本与工作流

根目录的package.json定义了丰富的脚本命令：

{
  "scripts": {
    "dev": "pnpm run --filter web-app dev",
    "dev:desktop": "pnpm run --filter eidos dev",
    "dev:docs": "pnpm run --filter docs dev",
    "build": "pnpm run --filter web-app build",
    "build:desktop": "pnpm run --filter eidos build"
  }
}

使用--filter参数可以针对特定workspace包执行命令，例如：

# 启动Web应用开发服务器
pnpm dev

# 启动桌面应用开发
pnpm dev:desktop

# 仅构建core包
pnpm --filter core build

桌面应用特殊配置

桌面应用需要额外的本地依赖配置。首次开发时需要运行：

cd apps/desktop
node scripts/download-libsimple.cjs

这个脚本会下载必要的本地库文件。桌面应用的package.json包含了Electron特定的依赖：

{
  "dependencies": {
    "@eidos.space/better-sqlite3": "^11.9.3",
    "electron": "^32.3.3",
    "sqlite-vec": "0.1.7-alpha.2"
  },
  "devDependencies": {
    "electron-builder": "^24.13.3",
    "vite-plugin-electron": "^0.28.7"
  }
}

开发环境验证

完成安装后，运行以下命令验证环境配置：

# 检查TypeScript配置
pnpm typecheck

# 运行代码格式化检查
pnpm format:check

# 启动开发服务器测试
pnpm dev:desktop

如果一切正常，您应该能够看到Electron应用启动，或者开发服务器成功运行。

常见问题与解决方案

依赖冲突处理：

# 解决依赖冲突
pnpm update --latest

# 清理node_modules重新安装
pnpm store prune
pnpm install

Workspace包链接问题：

# 重新链接所有workspace包
pnpm install --force

平台特定问题：

Windows用户可能需要安装Python和Visual Studio Build Tools
macOS用户可能需要安装Xcode Command Line Tools

通过以上步骤，您已经成功搭建了Eidos的开发环境并理解了其pnpm workspace配置。这种架构设计使得大型项目的依赖管理和开发协作变得更加高效和可控。

核心包结构与模块依赖关系

Eidos采用现代化的monorepo架构设计，通过清晰的包结构划分和模块依赖关系，构建了一个高度可扩展的个人数据管理框架。整个项目的核心包结构体现了模块化、可复用性和可扩展性的设计理念。

包结构概览

Eidos的核心代码主要组织在packages目录下，包含以下主要包：

包名称	主要功能	关键依赖
`@eidos.space/core`	核心数据管理逻辑	csv-parse, lodash, pgsql-ast-parser
`lib`	通用工具库	zustand, clsx, idb-keyval
`ai`	AI功能集成	@ai-sdk/*, openai, ai
`code-editor`	代码编辑器组件	-
`shared`	共享类型和工具	-
`locales`	国际化支持	-
`worker`	Web Worker相关	-
`sandbox`	脚本沙箱环境	-
`v3`	版本3相关功能	-
`sync`	数据同步功能	-

核心模块依赖关系

mermaid

核心包详细解析

@eidos.space/core 包

作为整个框架的核心，@eidos.space/core包提供了数据管理的核心功能：

// 核心类结构示例
class DataSpace {
  private tables: Map<string, TableManager>;
  private fields: FieldsManager;
  private sqlite: LocalSqlite;
  
  async initialize(databasePath: string): Promise<void> {
    // 初始化数据库连接
    await this.sqlite.connect(databasePath);
    await this.loadTables();
    await this.loadFields();
  }
  
  getTable(tableName: string): TableManager {
    return this.tables.get(tableName);
  }
}

该包包含的主要模块：

DataSpace类：数据空间的核心管理类，负责协调所有数据操作
TableManager系列：各种数据表的管理器（文档、文件、扩展等）
FieldService系列：字段类型服务（文本、链接、公式等）
SQLite集成：本地数据库操作封装
数据导入导出：CSV、Markdown等格式支持

lib 工具包

lib包提供了跨平台的通用工具函数：

// 状态管理示例
import { create } from 'zustand';

interface AppState {
  currentTable: string | null;
  setCurrentTable: (table: string) => void;
}

export const useAppStore = create<AppState>((set) => ({
  currentTable: null,
  setCurrentTable: (table) => set({ currentTable: table }),
}));

主要功能模块：

状态管理：基于zustand的状态管理
文件操作：IDB键值存储和文件压缩
工具函数：类型检查、数据处理等实用函数

ai 人工智能包

ai包集成了多种大语言模型供应商：

// AI功能集成示例
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

export async function generateSummary(content: string) {
  const { text } = await generateText({
    model: openai('gpt-4'),
    prompt: `Summarize the following content: ${content}`,
  });
  return text;
}

支持的AI供应商包括：

OpenAI、Anthropic、Google、Mistral等主流模型
本地模型和开源替代方案
向量搜索和语义检索功能

模块间协作机制

Eidos采用清晰的依赖注入模式，各模块通过接口进行通信：

mermaid

扩展性设计

Eidos的包结构设计支持灵活的扩展机制：

插件系统：通过ExtensionTable管理扩展
字段类型扩展：可自定义新的字段类型
AI工具扩展：支持自定义AI功能集成
数据格式扩展：可添加新的数据导入导出格式

这种模块化的架构设计使得Eidos能够适应不同的使用场景，从简单的个人数据管理到复杂的企业级应用都能很好地支持。

自定义扩展开发实战案例

Eidos的扩展系统是其最强大的特性之一，允许开发者创建各种类型的自定义功能来增强个人数据管理体验。本节将通过几个实战案例，深入探讨如何开发不同类型的扩展。

扩展类型概览

Eidos支持多种扩展类型，每种类型都有特定的用途和实现方式：

扩展类型	用途	开发语言	运行环境
Script扩展	数据处理、自动化任务	TypeScript/JavaScript	沙盒环境
Block扩展	UI组件、自定义视图	React + TypeScript	主应用环境
Tool扩展	AI工具、外部服务集成	TypeScript	沙盒环境
TableAction扩展	表格操作、批量处理	TypeScript	沙盒环境
UDF扩展	自定义SQL函数	TypeScript	SQLite环境

实战案例一：数据清洗脚本扩展

让我们创建一个实用的数据清洗脚本扩展，用于自动清理和格式化表格数据。

// 数据清洗工具脚本
interface DataCleaningTool {
  name: "data-cleaning-tool"
  description: "自动清洗和格式化表格数据"
  inputJSONSchema: {
    type: "object"
    properties: {
      tableId: { type: "string" }
      columnName: { type: "string" }
      operation: { 
        type: "string" 
        enum: ["trim", "lowercase", "uppercase", "remove-duplicates", "format-date"]
      }
    }
    required: ["tableId", "columnName", "operation"]
  }
}

// 脚本实现
async function dataCleaningTool(input: {
  tableId: string
  columnName: string
  operation: string
}): Promise<{ success: boolean; processedRows: number }> {
  
  // 获取表格数据
  const tableData = await eidos.db.exec(`
    SELECT id, ${input.columnName} 
    FROM ${input.tableId} 
    WHERE ${input.columnName} IS NOT NULL
  `)
  
  let processedCount = 0
  
  for (const row of tableData) {
    let newValue = row[input.columnName]
    
    switch (input.operation) {
      case "trim":
        newValue = newValue.trim()
        break
      case "lowercase":
        newValue = newValue.toLowerCase()
        break
      case "uppercase":
        newValue = newValue.toUpperCase()
        break
      case "remove-duplicates":
        // 去重逻辑
        break
      case "format-date":
        newValue = formatDate(newValue)
        break
    }
    
    // 更新数据
    await eidos.db.exec(
      `UPDATE ${input.tableId} SET ${input.columnName} = ? WHERE id = ?`,
      [newValue, row.id]
    )
    
    processedCount++
  }
  
  return { success: true, processedRows: processedCount }
}

// 注册工具
eidos.registerTool(dataCleaningTool)

实战案例二：自定义表格视图扩展

创建自定义的日历视图扩展，用于按日期查看任务和事件。

// 日历视图Block扩展
interface CalendarViewMeta {
  type: "tableView"
  componentName: "CalendarView"
  tableView: {
    title: "日历视图"
    type: "calendar"
    description: "按日期查看任务的日历视图"
  }
}

// React组件实现
import React from 'react'
import { useTableData } from '@eidos/sdk'

const CalendarView: React.FC<{ tableId: string; viewId: string }> = ({
  tableId,
  viewId
}) => {
  const { data, loading } = useTableData(tableId)
  
  const events = data?.rows.map(row => ({
    id: row.id,
    title: row.title || '未命名事件',
    start: new Date(row.start_date),
    end: new Date(row.end_date),
    allDay: row.all_day || false
  })) || []

  if (loading) return <div>加载中...</div>

  return (
    <div className="calendar-container">
      <h2>日历视图</h2>
      <div className="calendar-grid">
        {events.map(event => (
          <div key={event.id} className="calendar-event">
            <h4>{event.title}</h4>
            <p>{event.start.toLocaleDateString()}</p>
            {!event.allDay && (
              <p>{event.start.toLocaleTimeString()} - {event.end.toLocaleTimeString()}</p>
            )}
          </div>
        ))}
      </div>
    </div>
  )
}

// 注册组件
eidos.registerBlockExtension(CalendarView, {
  type: "tableView",
  componentName: "CalendarView",
  tableView: {
    title: "日历视图",
    type: "calendar",
    description: "按日期查看任务的日历视图"
  }
})

实战案例三：AI增强的摘要生成工具

集成AI能力，创建自动生成内容摘要的工具扩展。

// AI摘要工具
interface AISummaryTool {
  name: "ai-summary-tool"
  description: "使用AI生成内容摘要"
  inputJSONSchema: {
    type: "object"
    properties: {
      content: { type: "string" }
      maxLength: { type: "number", default: 200 }
      language: { type: "string", default: "zh" }
    }
    required: ["content"]
  }
}

async function aiSummaryTool(input: {
  content: string
  maxLength?: number
  language?: string
}): Promise<{ summary: string }> {
  
  const prompt = `
请为以下内容生成一个简洁的摘要，长度不超过${input.maxLength || 200}字，
使用${input.language || '中文'}：

${input.content}
  `.trim()

  try {
    // 调用Eidos内置的AI服务
    const response = await eidos.ai.generateText({
      model: "gpt-3.5-turbo",
      prompt: prompt,
      maxTokens: input.maxLength || 200
    })

    return { summary: response.text }
  } catch (error) {
    throw new Error(`AI摘要生成失败: ${error.message}`)
  }
}

// 注册AI工具
eidos.registerTool(aiSummaryTool)

扩展开发工作流程

Eidos扩展开发遵循标准化的工作流程：

mermaid

扩展调试与测试

Eidos提供了完善的调试工具来测试扩展：

// 扩展调试示例
async function testExtension() {
  // 1. 本地测试脚本
  const testResult = await eidos.debug.runScript({
    code: `function test() { return "Hello World" }`,
    context: { tableId: "test-table" }
  })
  
  // 2. 性能分析
  const profile = await eidos.debug.profileExtension({
    extensionId: "my-extension",
    iterations: 100
  })
  
  // 3. 错误追踪
  eidos.debug.enableErrorTracking({
    onError: (error, context) => {
      console.error("扩展错误:", error, context)
      // 发送错误报告到监控系统
    }
  })
}

扩展安全性考虑

开发扩展时需要特别注意安全性：

// 安全最佳实践
class SecureExtension {
  // 1. 输入验证
  validateInput(input: any) {
    if (typeof input !== 'object') {
      throw new Error('输入必须是对象')
    }
    // 更多的验证逻辑...
  }
  
  // 2. 资源限制
  async withResourceLimits<T>(
    operation: () => Promise<T>,
    limits = { timeout: 5000, memory: 50 }
  ): Promise<T> {
    return Promise.race([
      operation(),
      new Promise((_, reject) => 
        setTimeout(() => reject(new Error('操作超时')), limits.timeout)
      )
    ])
  }
  
  // 3. 沙盒环境执行
  async executeInSandbox(code: string, context: object) {
    return eidos.sandbox.execute(code, {
      context,
      allowedAPIs: ['db.query', 'utils.format'],
      deniedAPIs: ['fs.write', 'network.request']
    })
  }
}

扩展发布与分发

完成扩展开发后，可以通过多种方式分发：

// 扩展发布配置
const extensionManifest = {
  id: "my-data-cleaner",
  name: "数据清洗大师",
  version: "1.0.0",
  description: "专业的数据清洗和格式化工具",
  author: "开发者名称",
  homepage: "https://example.com",
  repository: "https://github.com/username/repo",
  keywords: ["data", "cleaning", "format"],
  categories: ["productivity", "tools"],
  
  // 权限声明
  permissions: {
    database: ["read", "write"],
    ai: ["generate"],
    network: []
  },
  
  // 兼容性
  compatibility: {
    eidos: ">=1.2.0",
    platform: ["desktop", "web"]
  }
}

// 发布到市场
async function publishToMarketplace() {
  const result = await eidos.marketplace.publish({
    manifest: extensionManifest,
    code: extensionCode,
    readme: "扩展的详细说明文档...",
    screenshots: ["screenshot1.png", "screenshot2.png"]
  })
  
  return result.packageId
}

通过这些实战案例，我们可以看到Eidos扩展系统的强大功能和灵活性。无论是简单的数据处理脚本还是复杂的AI集成工具，都可以通过统一的扩展框架来实现。开发者可以根据具体需求选择合适的扩展类型，利用Eidos提供的丰富API和工具来创建高效、安全的自定义功能。

构建打包与发布流程详解

Eidos作为一个现代化的个人数据管理框架，采用了多平台构建策略，支持桌面端（Electron）和Web端（PWA）两种部署方式。其构建系统基于Vite、Electron Builder和pnpm workspace，实现了高效的开发体验和可靠的发布流程。

构建架构概览

Eidos采用monorepo架构，使用pnpm workspace管理多个子包，构建系统通过统一的配置文件和脚本实现跨平台打包：

mermaid

构建配置详解

Vite配置架构

Eidos使用Vite作为构建工具，针对不同平台采用定制化配置：

// 共享基础配置
const sharedConfig: UserConfig = {
  // 公共配置项
  resolve: {
    alias: sharedAlias,
  },
  plugins: [
    // 公共插件
  ]
}

// 桌面端特定配置
const desktopConfig = mergeConfig(sharedConfig, {
  plugins: [
    electron({
      main: {
        entry: ['electron/main.ts', 'electron/worker.ts'],
        vite: {
          build: {
            rollupOptions: {
              external: [
                '@eidos.space/better-sqlite3',
                'oxc-parser',
                'oxc-transform'
              ]
            }
          }
        }
      },
      preload: {
        input: 'electron/preload.ts',
        vite: {
          build: {
            rollupOptions: {
              output: {
                format: 'es',
                inlineDynamicImports: true
              }
            }
          }
        }
      }
    })
  ]
})

Electron Builder配置

桌面应用的打包配置支持多平台发布：

{
  "appId": "space.eidos.desktop",
  "productName": "Eidos",
  "files": [
    "dist/**/*",
    "dist-electron/**/*",
    "dist-sqlite-ext/**/*",
    "package.json",
    "!**/node_modules/**/*",
    "**/node_modules/better-sqlite3/**/*"
  ],
  "extraResources": [
    {
      "from": "dist-sqlite-ext",
      "to": "dist-sqlite-ext",
      "filter": ["**/*"]
    }
  ],
  "win": {
    "target": ["nsis", "zip"],
    "icon": "dist/logo.png"
  },
  "mac": {
    "target": [
      {"target": "dmg", "arch": ["x64", "arm64"]},
      {"target": "zip", "arch": ["x64", "arm64"]}
    ],
    "icon": "dist/logo.icns",
    "hardenedRuntime": true
  },
  "linux": {
    "target": ["AppImage", "zip"]
  }
}

构建流程步骤

1. 依赖安装与准备

# 安装所有依赖
pnpm install

# 下载原生库（首次运行）
cd apps/desktop && node scripts/download-libsimple.cjs

# SQLite扩展构建
node scripts/postinstall-sqlite-ext.cjs

2. 开发环境构建

# Web应用开发
pnpm dev

# 桌面应用开发
pnpm dev:desktop

# 文档开发
pnpm dev:docs

3. 生产环境构建

# Web应用构建
pnpm build

# 桌面应用构建
pnpm build:desktop

# 文档构建
pnpm build:docs

4. 打包发布

# 桌面应用打包（生产环境）
pnpm pkg:desktop

# 桌面应用打包（开发环境）
pnpm pkg:desktop:dev

版本管理机制

Eidos采用自动化的版本管理流程，通过统一的版本控制脚本确保所有包的版本一致性：

mermaid

版本更新脚本支持三种更新模式：

更新类型	命令	说明
补丁更新	`pnpm patch`	修复bug，向后兼容
次要更新	`pnpm minor`	新增功能，向后兼容
主要更新	`pnpm major`	破坏性变更，不向后兼容

构建优化策略

代码分割与Tree Shaking

Eidos利用Vite的现代构建能力实现高效的代码分割：

// Rollup配置优化
rollupOptions: {
  external: [
    '@eidos.space/better-sqlite3',
    'oxc-parser',
    'oxc-transform'
  ],
  output: {
    format: 'es',
    inlineDynamicImports: true,
    entryFileNames: '[name].mjs',
    chunkFileNames: '[name].mjs'
  }
}

原生模块处理

对于SQLite等原生模块，采用特殊的构建策略：

// postinstall脚本处理SQLite扩展
const { execSync } = require('child_process')

// 构建SQLite扩展
execSync('npm run rebuild', {
  cwd: 'node_modules/@eidos.space/better-sqlite3',
  stdio: 'inherit'
})

PWA特性集成

Web应用通过Vite PWA插件实现渐进式Web应用特性：

VitePWA({
  strategies: "injectManifest",
  manifest: {
    name: "Eidos",
    short_name: "Eidos",
    theme_color: "#ffffff",
    display: "standalone",
  },
  workbox: {
    clientsClaim: true,
    skipWaiting: true,
  }
})

多平台发布支持

Eidos支持三种主流操作系统的发布格式：

平台	发布格式	特性
Windows	NSIS安装包 + ZIP	自动更新支持，系统集成
macOS	DMG镜像 + ZIP	公证支持，ARM64原生
Linux	AppImage + ZIP	便携式运行，依赖包含

构建环境变量

构建过程中使用的重要环境变量：

变量名	用途	默认值
`EIDOS_SERVICE_MODE`	服务模式标识	`desktop`
`BUILD_MODE`	构建模式标识	`1`（生产）
`NODE_OPTIONS`	Node.js选项	`--max-old-space-size=8192`

质量保证措施

构建流程中包含多项质量保证措施：

类型检查：pnpm typecheck 执行TypeScript类型检查
代码格式化：pnpm format:check 验证代码格式
lint检查：pnpm lint 使用oxlint进行代码质量检查
测试运行：pnpm test 执行单元测试

通过这套完善的构建打包流程，Eidos能够确保跨平台应用的一致性和可靠性，为开发者提供顺畅的发布体验。

总结

Eidos作为一个现代化的个人数据管理框架，通过精心设计的monorepo架构和pnpm workspace管理，提供了高效的开发体验和可靠的构建发布流程。本文全面介绍了从环境搭建、核心结构解析到扩展开发实战的完整开发周期，展示了Eidos在模块化设计、跨平台支持和AI集成方面的强大能力。无论是简单的数据处理脚本还是复杂的自定义扩展，开发者都可以利用Eidos的统一框架来创建高效、安全的应用功能，为个人数据管理提供了灵活可靠的解决方案。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考