# APP 技术原理

## 定位与边界
这是一个 pnpm workspace 的 monorepo：以 **桌面应用** 为核心，配套 **开发者文档站**、**共享工具包** 与 **插件示例**。核心运行时由 Electron（主进程）+ Vue 3（渲染进程）构成，插件系统以 Manifest/Prelude/Surface 三层结构扩展功能。

## 运行时架构
- **进程模型**：主进程（Electron）负责窗口、模块与系统能力；渲染进程（Vue 3）负责 UI 与交互；Preload 负责安全桥接。
- **模块体系**：主进程通过 `ModuleManager` 管理模块生命周期，模块遵循 `BaseModule` 的 `created/onInit/start/stop/onDestroy` 规范。
- **核心入口**：CoreBox 是应用搜索与执行的主入口，负责搜索聚合、推荐与结果渲染。

## 通信与事件
- **Channel 系统**：抽象 IPC 通信（`ChannelType.MAIN` / `ChannelType.PLUGIN`），支持主进程、渲染进程与插件进程间调用。
- **事件总线**：`TouchEventBus` 分发应用级事件（如 `APP_READY`、`ALL_MODULES_LOADED`、`PLUGIN_STORAGE_UPDATED`）。
- **插件隔离**：插件通道使用隔离密钥，避免跨插件干扰。

## 数据与存储
- **应用配置**：主进程 `StorageModule` 持久化至 `config/`，支持多窗口同步更新。
- **插件配置**：插件独立存储（10MB 限制）并做安全文件名清理。
- **结构化数据**：`database/` 模块基于 Drizzle ORM + LibSQL。

## 搜索与 CoreBox
- **搜索入口**：输入 → Provider 过滤 → 结果评分 → 合并展示。
- **平台差异**：Windows 使用 Everything Provider；macOS/Linux 使用 File Provider。
- **UI 行为**：CoreBox 由渲染侧结果驱动窗口高度，主进程做统一调度与动画。

## 构建与发布
- **构建链路**：Electron-Vite + Vite + TypeScript。
- **发布配置**：`electron-builder.yml` 与 `dev-app-update.yml` 负责构建与更新策略。
- **脚本**：`scripts/` 提供版本同步、权限修复与调试命令。

## 工程目录结构（根目录）
- `apps/`：应用与站点子项目。
- `packages/`：共享工具包与组件库。
- `plugins/`：插件示例与可独立运行的插件项目。
- `docs/`：工程与产品文档、PRD、分析报告。
- `scripts/`：CI/工具脚本与工程维护脚本。
- `build/`：构建配置产物（少量文件）。
- `.github/`、`.husky/`、`.vscode/` 等：协作与工具链配置。工程约束位于 `docs/engineering/specs/`；`docs/comet/` 只读保留退出前的需求、规格和验收记录。
- 关键文件：`package.json`、`pnpm-workspace.yaml`、`pnpm-lock.yaml`、`eslint.config.js`、`commitlint.config.cts`、`README.md`、`README.zh-CN.md`、`AGENTS.md`、`CLAUDE.md`。

## 子项目结构详解

### apps/core-app（Electron 主应用）
- **源码目录**
  - `src/main/`：主进程（core/modules/channel/db/service 等）。
  - `src/renderer/`：渲染进程（Vue 3），含 `src/components`、`src/views`、`src/stores`、`src/modules`、`src/styles`。
  - `src/preload/`：预加载脚本与桥接定义。
  - `src/shared/`：跨进程共享类型。
- **资源与配置**
  - `resources/`：应用资源与图标。
  - `public/`：渲染层静态资源。
  - `scripts/`：构建/调试脚本。
  - 关键文件：`electron.vite.config.ts`、`electron-builder.yml`、`dev-app-update.yml`、`drizzle.config.ts`、`tsconfig*.json`、`package.json`。

### apps/nexus（文档站 / 开发者中心）
- **内容与页面**
  - `content/`：文档内容（`docs/`、`app/`）。
  - `app/`：Nuxt App 目录与页面。
  - `server/`：服务端 API 与中间层。
  - `public/`：公共静态资源。
  - `i18n/`：多语言资源与配置。
  - `types/`：类型定义。
- **关键配置**
  - `nuxt.config.ts`、`content.config.ts`、`i18n.config.ts`、`uno.config.ts`、`sentry.*.config.ts`、`package.json`、`SETUP.md`、`README.md`。

### packages/utils（共享工具包）
- **能力分层**
  - `base/`、`common/`：基础类型与通用工具。
  - `channel/`、`transport/`：通信与传输封装。
  - `plugin/`、`core-box/`、`renderer/`：插件与 UI 侧 SDK。
  - `i18n/`、`eventbus/`、`account/`、`permission/`、`analytics/`：跨模块能力。
- **测试与入口**
  - `__tests__/`、`index.ts`、`vitest.config.ts`、`package.json`。

### packages/tuffex（UI 组件库）
- **组件与工具**
  - `packages/components/`：组件实现（含 TuffIcon）。
  - `packages/utils/`、`packages/script/`：内部工具与脚本。
  - `docs/`：组件文档。
- **配置**
  - `components.json`、`tsconfig.json`、`vitest.config.ts`、`package.json`、`CHANGELOG.md`。

### packages/tuff-intelligence（智能能力）
- `src/`：`index.ts`、`graph.ts`、`storage.ts`、`types.ts`、`langchain-bridge.ts`。
- `package.json`、`tsconfig.json`、`eslint.config.js`。

### packages/unplugin-export-plugin（打包/导出插件）
- `src/`：构建工具适配器（`vite.ts`、`rollup.ts`、`esbuild.ts`、`webpack.ts`、`nuxt.ts`）、共享集成运行时（`index.ts`、`prelude.ts`、`types.ts`）与集成测试。CLI、插件包构建与发布逻辑仅保留在 `packages/tuff-cli` 和 `packages/tuff-cli-core`。
- `tsup.config.ts`、`package.json`、`README.md`。

### packages/help（工程辅助）
- `tree-generator.ts`：目录/结构生成脚本。

### packages/test（测试与验证）
- `src/`：`core-box/`、`download/`、`aisdk/`、`common/`。
- `vitest.config.ts`、`tsconfig.json`、`package.json`。

### plugins/touch-translation（翻译插件）
- `manifest.json`、`index.js`：插件入口与清单。
- `src/`：`pages/`、`components/`、`providers/`、`router/`、`styles/`。
- `widgets/`、`shared/`：插件扩展与共享资源。

### plugins/touch-music（音乐插件）
- `init.json`、`preload.js`：初始化与预加载。
- `src/`：`components/`、`modules/`、`styles/`、`assets/`。

### plugins/touch-image（图片插件）
- `src/`：`App.vue`、`main.ts`、`assets/`。
- `public/`：静态资源与图片。

### examples（示例与演示）
- `basic-usage.js`、`complete-example.js`、`message-system-example.js` 等对接样例。
- `util-pkg/`、`division-box/` 子示例工程。

## 排除项（生成/缓存目录）
为避免噪声，以下目录默认不展开：`node_modules/`、`.git/`、`.pnpm-store/`、`.venv/`、`.nuxt/`、`dist/`、`out/`、`.data/`、`.eslintcache`、`.DS_Store` 等缓存/产物目录。