开发环境搭建指南

本指南帮助开发者快速搭建爱生活的开发环境，涵盖环境配置、项目启动、多平台调试和常见问题。

1. 环境要求

工具	版本要求	用途
Node.js	>= 18	运行环境、包管理
npm	>= 9	包管理器
HBuilderX	最新版	App 打包（仅 Android/iOS 构建需要）
Android Studio	最新稳定版	Android 模拟器 / 真机调试
Xcode	15+	iOS 模拟器 / 真机调试（仅 macOS）
Git	>= 2.30	版本控制

推荐 IDE：VS Code + Volar 插件（Vue 3 + TypeScript 支持），或直接使用 HBuilderX。

可选工具：

工具	用途
微信开发者工具	微信小程序调试
Charles / Proxyman	网络请求抓包
React Native Debugger	H5 端状态调试（Pinia DevTools）

2. 项目初始化

2.1 克隆与安装

bash

# 克隆项目
git clone <repo-url> ai-life-os
cd ai-life-os

# 安装依赖
npm install

2.2 安装完成后验证

bash

# 类型检查（确保 TypeScript 编译通过）
npm run type-check

# 启动 H5 开发服务器
npm run dev:h5

浏览器打开 http://localhost:5173，看到爱生活首页即表示环境配置成功。

3. 项目结构速览

ai-life-os/
├── src/
│   ├── main.ts                 # 应用入口
│   ├── App.vue                 # 根组件（启动安全流程）
│   ├── manifest.json           # uni-app 原生配置
│   ├── pages.json              # 页面路由（120+ 页面）
│   ├── uni.scss                # 全局样式入口
│   │
│   ├── ai/                     # AI 子系统
│   │   ├── actions.ts          # 40+ Agent Action 定义
│   │   ├── agent-prompt.ts     # Agent System Prompt
│   │   ├── edge-stream.ts      # 端侧流式引擎
│   │   ├── model-manager.ts    # 8 模型管理
│   │   └── pipeline.ts         # H5 推理管线
│   │
│   ├── assets/styles/          # SCSS 全局变量与样式
│   ├── components/             # 通用组件
│   │   ├── common/             # BioAuthOverlay, LifeButton 等
│   │   ├── home/               # 首页组件
│   │   └── Layout/             # BottomBar, Layout, StatusBar
│   │
│   ├── data/                   # 静态配置数据
│   ├── database/               # 数据库层
│   │   ├── engines/            # SQLite / Dexie / Encrypted 三引擎
│   │   ├── schema.ts           # 80+ 表定义
│   │   ├── base-repository.ts  # Repository 基类
│   │   └── migration.ts        # 数据库版本迁移
│   │
│   ├── hooks/                  # useSafeArea, useTimePhase
│   ├── modules/                # 12 个业务模块
│   ├── pages/                  # 80+ 功能页面
│   ├── services/               # AI Agent, Insight, Event 等服务
│   ├── stores/                 # Pinia Store（7 个）
│   ├── sync/                   # 同步引擎
│   │   ├── sync-manager.ts     # SyncManager 单例
│   │   ├── providers/          # 同步 Provider 实现
│   │   └── types.ts            # 同步类型定义
│   ├── types/                  # 全局类型
│   └── uni_modules/            # 原生插件
│       ├── biometric-auth2/    # 生物认证
│       └── llama-ai3/          # Llama.cpp AI 引擎
│
├── docs/                       # VitePress 文档站点
│   └── .vitepress/config.mts   # 文档配置
├── scripts/                    # 种子数据脚本
├── package.json
├── tsconfig.json
└── vite.config.ts              # 构建配置（含 4 个自定义代理插件）

4. 各平台运行命令

4.1 开发模式

命令	平台	说明
`npm run dev:h5`	H5 (浏览器)	默认端口 5173
`npm run dev:app`	App 通用	需连接真机或模拟器
`npm run dev:app-android`	Android	直接指定平台
`npm run dev:app-ios`	iOS	仅 macOS

4.2 构建模式

命令	平台	产物位置
`npm run build:h5`	H5	`dist/build/h5/`
`npm run build:app`	App 通用	`dist/build/app/`
`npm run build:app-android`	Android	`dist/build/app/`
`npm run build:app-ios`	iOS	`dist/build/app/`

所有命令自动设置 SASS_SILENCE_DEPRECATION=1 以消除 SCSS Modern API 迁移的弃用警告。

4.3 类型检查

bash

npm run type-check

调用 vue-tsc --noEmit 执行全项目类型检查。建议在提交前运行。

4.4 文档站点

bash

# 启动文档热更新开发服务器
npm run docs:dev

# 构建文档
npm run docs:build

# 预览构建产物
npm run docs:preview

文档站点基于 VitePress，配置在 docs/.vitepress/config.mts。通过 vite: { configFile: false } 禁用了根目录 vite.config.ts 的继承，避免 uni-app 构建配置干扰。

5. 开发工作流

5.1 典型开发流程

① npm run dev:h5                   启动 H5 开发服务器
② 修改代码 → 浏览器热更新 (HMR)
③ 在 DevTools 中调试 Vue/网络/存储
④ 功能完成后运行 npm run type-check
⑤ 切换真机验证（需要时）
⑥ 提交代码

5.2 热更新说明

uni-app 支持以下文件变更的热更新：

文件类型	表现
`.vue` 模板/样式	浏览器即时更新（保留状态）
`.ts` / `.js` 逻辑	浏览器即时更新
`pages.json` 路由	需手动刷新
`manifest.json`	需重启开发服务器

5.3 Vite 自定义代理插件

vite.config.ts 注册了 4 个开发服务器专用插件：

插件	端口/路由	用途
`davProxyPlugin`	`localhost:9399`	WebDAV 同步代理（处理 CORS）
`copyOrtWasmPlugin`	`/ort/`	ONNX Runtime WASM 文件服务（含 COOP/COEP 头）
`packageProxyPlugin`	`/api/package`	快递查询 API 代理
`aiProxyPlugin`	`/api/ai/proxy`	AI API 通用代理

这些插件的配置在 vite.config.ts 中，修改时需要重启开发服务器。

6. 多平台开发注意事项

6.1 条件编译

uni-app 支持使用注释标记进行条件编译：

vue

<!-- #ifdef H5 -->
只会在 H5 平台编译的代码
<!-- #endif -->

<!-- #ifdef APP-PLUS -->
只会在 App 平台编译的代码
<!-- #endif -->

平台标识	说明
`H5`	浏览器环境
`APP-PLUS`	App（含 Android + iOS）
`APP-PLUS-ANDROID`	仅 Android
`APP-PLUS-IOS`	仅 iOS
`MP-WEIXIN`	微信小程序

6.2 平台差异

特性	H5	App
数据库引擎	Dexie (IndexedDB)	SQLite (原生)
AI 推理	Transformers.js (WASM)	Llama.cpp (Native)
生物认证	不支持	Face ID / Touch ID / 指纹
截图保护	不支持	iOS `isSecureTextEntry`
后台锁屏	页面可见性 API	原生 `pause` 事件
安全存储	无	Keychain / Keystore
WASM 要求	COOP/COEP 跨域隔离	不需要

6.3 页面路由

路由配置位于 src/pages.json，关键约定：

所有页面使用 navigationStyle: "custom"（自定义导航栏）
敏感页面（锁屏、密码管理）配置 disableScreenshot: true
通过 easycom 自动注册 13 个通用组件，无需手动 import
TabBar 固定 5 个主 tab：首页、任务、功能、日程、我的

7. 核心架构速览

7.1 数据层调用链

页面 (Vue Component)
    ↓ 调用
Pinia Store (stores/)
    ↓ 调用
Repository (modules/*/repository.ts)
    ↓ 继承 BaseRepository
IStore (database/engines/)
    ↓ 透明加密
EncryptedStore → SQLite / Dexie

7.2 创建数据实体的标准流程

typescript

// 1. 在 modules/<name>/types.ts 中定义实体接口
interface Task extends BaseEntity {
  content: string
  priority: 'high' | 'medium' | 'low'
  // ...
}

// 2. 在 modules/<name>/repository.ts 中创建 Repository
class TaskRepository extends BaseRepository&#60;Task&#62; {
  constructor() {
    super('task')
  }
}

// 3. 在 stores/<name>.store.ts 中创建 Pinia Store
export const useTaskStore = defineStore('task', () => {
  const repo = new TaskRepository()

  async function createTask(data) {
    const task = await repo.create({
      ...data,
      syncStatus: 'LOCAL_ONLY',
      version: 0,
    })
    syncManager.markForSync('task', task.id, 'create', task, 'task')
    return task
  }
})

7.3 相关文档

子系统	设计文档
数据库设计	数据库 Schema 设计
AI 子系统	AI 子系统设计
安全与加密	安全与隐私设计
同步机制	同步机制设计
架构总览	架构设计

8. 新增功能模块指南

以下以新增"喝水记录"功能为例。

8.1 创建页面

在 src/pages/water/ 下创建 index.vue：

vue

<template>
  <view class="page">
    <text>喝水记录</text>
  </view>
</template>

<script setup lang="ts">
import { useWaterStore } from '@/stores/water.store'
</script>

8.2 注册路由

在 src/pages.json 的 pages 数组中添加：

json

{
  "path": "pages/water/index",
  "style": {
    "navigationStyle": "custom",
    "navigationBarTitleText": "喝水"
  }
}

8.3 定义实体类型

在 src/modules/health/types.ts 中添加（或新建模块类型文件）：

typescript

interface WaterRecord extends BaseEntity {
  amount: number       // 毫升
  recordedAt: number
}

8.4 创建 Repository

typescript

// src/modules/health/water-repository.ts
import { BaseRepository } from '@/database/base-repository'

class WaterRepository extends BaseRepository&#60;WaterRecord&#62; {
  constructor() {
    super('waterRecord')
  }

  async getTodayTotal(): Promise&#60;number&#62; {
    const today = dayjs().format('YYYY-MM-DD')
    const records = await this.store.toArray()
    return records
      .filter(r => dayjs(r.recordedAt).format('YYYY-MM-DD') === today)
      .reduce((sum, r) => sum + r.amount, 0)
  }
}

8.5 创建 Pinia Store

typescript

// src/stores/water.store.ts
export const useWaterStore = defineStore('water', () => {
  const repo = new WaterRepository()

  async function record(amount: number) {
    const record = await repo.create({
      amount,
      recordedAt: Date.now(),
      syncStatus: 'LOCAL_ONLY',
      version: 0,
    })
    syncManager.markForSync('waterRecord', record.id, 'create', record, 'health')
    return record
  }

  return { record }
})

8.6 （可选）注册 AI Action

在 src/ai/actions.ts 中添加：

typescript

{
  name: 'record_water',
  description: '记录一次饮水量',
  schema: z.object({
    amount: z.number().describe('饮水量（毫升）'),
  }),
  execute: async (params) => {
    const store = useWaterStore()
    await store.record(params.amount)
    return { success: true, message: `已记录饮水 ${params.amount}ml` }
  }
}

9. 调试方法

9.1 H5 端调试

浏览器 DevTools：

Vue 组件树：安装 Vue DevTools 浏览器扩展
网络请求：Network 面板查看 API 代理请求
IndexedDB：Application > IndexedDB > LifeOSDatabase_v2
控制台：查看 AI 推理日志、同步状态

Pinia 调试：在 main.ts 中可启用 Pinia DevTools 集成。

9.2 App 端调试

HBuilderX 调试：

连接真机 / 启动模拟器
运行 → 运行到手机或模拟器
使用 HBuilderX 内置的 WebView 调试器

Android 调试：

bash

# 查看日志
adb logcat | grep -i "lifeos"

# 查看数据库文件
adb shell run-as <package-name> ls /data/data/<package-name>/databases/

iOS 调试：Xcode → Window → Devices and Simulators → 选择设备 → 查看日志。

9.3 类型检查

bash

# 全量类型检查
npm run type-check

# 检查单个文件
npx vue-tsc --noEmit src/stores/task.store.ts

建议在 VS Code 中安装 Volar 插件，获得实时类型提示和错误检查。

9.4 数据库调试

typescript

// 在浏览器控制台中查看所有表数据
import { db } from '@/database'
const data = await db.task.toArray()
console.log(data)

H5 端可直接在 DevTools > Application > IndexedDB 中浏览所有表（数据为 AES-256-GCM 加密密文）。

10. 代码规范

10.1 TypeScript

项目启用 strict: true 严格模式。所有新代码必须：

使用完整的 TypeScript 类型注解
避免 any，优先使用 unknown 或具体接口
为 Props、Emits、Store 导出类型接口

10.2 命名约定

类型	约定	示例
Vue 组件	PascalCase	`BioAuthOverlay.vue`
页面文件	kebab-case	`data-management/index.vue`
Store	`useXxxStore`	`useTaskStore`
Repository	`XxxRepository`	`TaskRepository`
类型/接口	PascalCase	`Task`, `SyncConfig`
工具函数	camelCase	`deriveKey`, `markForSync`
常量	UPPER_SNAKE_CASE	`PBKDF2_ITERATIONS`

10.3 提交规范

建议遵循 Conventional Commits：

feat: 添加喝水记录模块
fix: 修复加密配置双写失败
docs: 更新开发指南
refactor: 重构同步队列查询

11. 常见问题

11.1 SCSS 弃用警告

若看到大量 SCSS Legacy JS API 警告，这是正常的。项目已通过 SASS_SILENCE_DEPRECATION=1 环境变量屏蔽，构建配置中也指定了 api: 'modern'。

11.2 H5 端 ONNX Runtime 白屏

H5 端 AI 推理需要 SharedArrayBuffer，要求跨域隔离头：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: credentialless

vite.config.ts 已自动配置，确保使用 npm run dev:h5 启动的开发服务器。

11.3 TypeScript 报 "找不到模块 @/..."

检查 tsconfig.json 中是否包含正确的 paths 配置：

json

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

11.4 App 端构建失败

常见原因：

Android：检查 Android SDK 和 NDK 是否正确安装。参考 Android 开发者文档。
iOS：确保 Xcode 版本 >= 15，CocoaPods 已安装。
权限缺失：检查 manifest.json 中是否声明了相应原生模块。

11.5 VitePress 文档构建失败

文档站点使用 vite: { configFile: false } 避免继承根目录 vite.config.ts。如果失败，检查：

docs/.vitepress/config.mts 是否被修改
文档 Markdown 中是否有未转义的 < > 字符（Vue 解析错误）
运行 npm run docs:build 查看详细错误

11.6 加密相关错误

"ActiveKey not found"：用户尚未解锁。确保先通过锁屏/加密验证。
"Decrypt failed"：密文可能损坏，或密钥不匹配。如果是从备份恢复的数据，确认使用的是正确的密码。

开发环境搭建指南 ​

1. 环境要求 ​

2. 项目初始化 ​

2.1 克隆与安装 ​

2.2 安装完成后验证 ​

3. 项目结构速览 ​

4. 各平台运行命令 ​

4.1 开发模式 ​

4.2 构建模式 ​

4.3 类型检查 ​

4.4 文档站点 ​

5. 开发工作流 ​

5.1 典型开发流程 ​

5.2 热更新说明 ​

5.3 Vite 自定义代理插件 ​

6. 多平台开发注意事项 ​

6.1 条件编译 ​

6.2 平台差异 ​

6.3 页面路由 ​

7. 核心架构速览 ​

7.1 数据层调用链 ​

7.2 创建数据实体的标准流程 ​

7.3 相关文档 ​

8. 新增功能模块指南 ​

8.1 创建页面 ​

8.2 注册路由 ​

8.3 定义实体类型 ​

8.4 创建 Repository ​

8.5 创建 Pinia Store ​

8.6 （可选）注册 AI Action ​

9. 调试方法 ​

9.1 H5 端调试 ​

9.2 App 端调试 ​

9.3 类型检查 ​

9.4 数据库调试 ​

10. 代码规范 ​

10.1 TypeScript ​

10.2 命名约定 ​

10.3 提交规范 ​

11. 常见问题 ​

11.1 SCSS 弃用警告 ​

11.2 H5 端 ONNX Runtime 白屏 ​

11.3 TypeScript 报 "找不到模块 @/..." ​

11.4 App 端构建失败 ​

11.5 VitePress 文档构建失败 ​

11.6 加密相关错误 ​

开发环境搭建指南

1. 环境要求

2. 项目初始化

2.1 克隆与安装

2.2 安装完成后验证

3. 项目结构速览

4. 各平台运行命令

4.1 开发模式

4.2 构建模式

4.3 类型检查

4.4 文档站点

5. 开发工作流

5.1 典型开发流程

5.2 热更新说明

5.3 Vite 自定义代理插件

6. 多平台开发注意事项

6.1 条件编译

6.2 平台差异

6.3 页面路由

7. 核心架构速览

7.1 数据层调用链

7.2 创建数据实体的标准流程

7.3 相关文档

8. 新增功能模块指南

8.1 创建页面

8.2 注册路由

8.3 定义实体类型

8.4 创建 Repository

8.5 创建 Pinia Store

8.6 （可选）注册 AI Action

9. 调试方法

9.1 H5 端调试

9.2 App 端调试

9.3 类型检查

9.4 数据库调试

10. 代码规范

10.1 TypeScript

10.2 命名约定

10.3 提交规范

11. 常见问题

11.1 SCSS 弃用警告

11.2 H5 端 ONNX Runtime 白屏

11.3 TypeScript 报 "找不到模块 @/..."

11.4 App 端构建失败

11.5 VitePress 文档构建失败

11.6 加密相关错误