Skip to content

Latest commit

 

History

History
516 lines (430 loc) · 11 KB

technical-development-guide.md

File metadata and controls

516 lines (430 loc) · 11 KB

技术开发指南

注意: 本文档整合了原有的开发指南和技术文档，提供完整的技术栈说明和开发规范。

1. 项目技术架构

1.1 整体架构

  • Monorepo结构
    • packages/core - 核心功能包
    • packages/web - Web应用
    • packages/extension - Chrome扩展
    • packages/ui - 共享UI组件
  • 包间依赖管理
    • 清晰的依赖关系
    • 版本一致性
    • 最小化重复代码
  • 工程化工具
    • pnpm workspace
    • 多包管理
    • 统一版本控制

1.2 技术栈概览

1.2.1 核心包 (@prompt-optimizer/core)

  • TypeScript 5.3.x
    • 类型系统
    • 接口定义
    • 模块化
  • 原生SDK集成
    • OpenAI SDK ^4.83.0
    • Google Generative AI SDK ^0.21.0
    • 模型管理
    • 提示词处理
    • 流式响应
  • 工具库
    • uuid ^11.0.5
    • zod ^3.22.4
    • 错误处理
    • 类型定义

1.2.2 Web包 (@prompt-optimizer/web)

  • Vue 3.5.x
    • Composition API
    • Script Setup
    • 响应式系统
    • 组件生态
  • Vite 6.0.x
    • 快速开发服务器
    • 优化的构建
    • 插件系统
    • HMR支持

1.2.3 UI框架和样式

  • TailwindCSS 3.4.x
    • 实用优先
    • 响应式设计
    • 深色模式支持
    • 动画系统
  • Vue Transitions
    • 页面过渡动画
    • 组件切换效果
    • 列表动画
  • Element Plus 2.9.x
    • 组件库
    • 主题支持
    • 响应式组件

1.2.4 状态管理

  • Vue Reactivity
    • ref/reactive
    • computed
    • watch
    • watchEffect
  • LocalStorage
    • 配置持久化
    • 历史记录存储
    • 模板管理
    • 加密存储
  • Pinia 2.1.x
    • 状态管理
    • 持久化
    • 插件支持

1.2.5 安全性

  • WebCrypto API
    • API密钥加密
    • 安全存储
    • 密钥轮换
  • XSS防护
    • 输入验证
    • 内容过滤
    • 安全编码
  • CORS配置
    • API访问控制
    • 安全头部
    • CSP策略

1.2.6 开发工具

  • TypeScript 5.3.x
    • 类型检查
    • 代码提示
    • 接口定义
  • ESLint 8.56.x
    • 代码规范
    • 自动修复
    • TypeScript支持
  • Prettier 3.2.x
    • 代码格式化
    • 统一风格
    • 编辑器集成

1.2.7 测试框架

  • Vitest 3.0.x
    • 单元测试
    • 集成测试
    • 快照测试
    • 覆盖率报告
  • Vue Test Utils 2.4.x
    • 组件测试
    • 行为模拟
    • 事件测试
  • Playwright 1.41.x
    • E2E测试
    • 跨浏览器测试
    • 视觉回归测试

1.3 代码组织

  • 模块化设计
    • 按功能划分模块
    • 单一职责原则
    • 关注点分离
  • 统一目录结构
    • src/ - 源代码
    • tests/ - 测试代码
    • types/ - 类型定义
    • config/ - 配置文件

2. 核心包开发规范

2.1 服务实现规范

  • 接口一致性

    • 所有服务必须实现统一接口
    • 方法命名保持一致
    • 错误处理遵循统一模式
    • 返回值类型一致

  • 错误处理

    • 使用统一的错误类型
    • 错误信息应包含上下文
    • 实现错误恢复机制
    • 提供用户友好的错误信息

2.2 SDK集成规范

  • 原生SDK集成

    • 直接使用官方SDK
    • 避免不必要的抽象层
    • 保持版本更新
    • 遵循官方最佳实践

  • 错误映射

    • SDK特定错误映射到统一错误类型
    • 保留原始错误信息
    • 实现重试机制
    • 提供降级方案

2.3 类型定义规范

  • 类型安全性

    • 使用精确的类型定义
    • 避免any类型
    • 使用联合类型表示可能的值
    • 为复杂对象定义接口

  • 类型导出

    • 在index.ts中集中导出类型
    • 按模块组织类型定义
    • 使用命名空间避免冲突
    • 提供类型文档注释

2.4 测试规范

  • 单元测试

    • 测试覆盖率目标>80%
    • 测试边界条件
    • 模拟外部依赖
    • 验证错误处理

  • 集成测试

    • 测试服务间交互
    • 验证端到端流程
    • 测试性能和并发
    • 模拟真实环境

3. 前端开发规范

3.1 项目架构

  • 推荐目录结构

    src/
├── components/    # UI组件
├── composables/   # 组合式函数
├── views/         # 页面组件
├── services/      # 服务
├── stores/        # Pinia状态
├── assets/        # 静态资源
├── utils/         # 工具函数
├── types/         # 类型定义
├── App.vue        # 根组件
└── main.ts        # 入口文件

  • 命名规范

    • 组件文件：PascalCase.vue
    • 工具函数文件：camelCase.ts
    • 类型定义文件：camelCase.types.ts
    • 组合式函数：useXxx.ts

3.2 服务使用规范

  • 核心服务集成

    • 使用统一的服务访问模式
    • 实现服务单例模式
    • 处理服务初始化
    • 管理服务状态

  • 错误处理

    • 使用统一的错误处理机制
    • 提供用户友好的错误提示
    • 实现错误恢复
    • 记录错误日志

3.3 组件开发规范

  • Vue组件模板

    • 使用<script setup>语法
    • 明确定义props和emits
    • 使用TypeScript类型
    • 遵循单一职责原则

  • 组件设计原则

    • 组件应该是可复用的
    • 组件应该是可测试的
    • 组件应该是可维护的
    • 组件应该是可扩展的

3.4 类型系统

  • Vue组件类型

    • 为props定义明确类型
    • 为emits定义事件类型
    • 为ref和reactive定义类型
    • 使用泛型增强类型安全

  • 通用工具类型

    • 创建可复用的工具类型
    • 使用TypeScript内置工具类型
    • 为复杂数据结构定义类型
    • 避免类型断言

3.5 状态管理

  • Pinia存储

    • 按功能模块组织store
    • 使用组合式API风格
    • 实现持久化
    • 处理异步操作

  • 组合式API状态

    • 使用composables封装状态逻辑
    • 实现状态共享
    • 处理生命周期
    • 管理副作用

3.6 性能优化

  • 动态导入

    • 使用路由懒加载
    • 组件按需加载
    • 第三方库按需导入
    • 代码分割

  • 渲染优化

    • 使用虚拟列表
    • 避免不必要的渲染
    • 使用计算属性缓存
    • 优化大型列表

3.7 测试规范

  • 组件测试

    • 测试组件渲染
    • 测试用户交互
    • 测试props和emits
    • 测试边界条件

  • 服务测试

    • 模拟外部依赖
    • 测试异步操作
    • 测试错误处理
    • 验证状态变化

4. 应用流程

4.1 核心服务初始化

  1. 核心服务加载顺序

    • 导入核心服务（modelManager, templateManager, historyManager）
    • 加载模型配置
    • 加载模板配置
    • 加载历史记录

  2. 服务实例创建流程

    • 创建LLM服务实例
    • 创建提示词服务实例
    • 注册事件处理器
    • 初始化服务状态

4.2 Web应用初始化

  1. 应用配置加载

    • 环境变量加载
    • 主题设置初始化
    • Vue应用配置

  2. 服务状态同步

    • 模型状态初始化
    • 模板数据加载
    • 历史记录同步

4.3 提示词优化流程

  1. 用户输入阶段

    • 输入验证流程
    • 错误处理机制
    • 输入清理和预处理

  2. 优化处理阶段

    • 使用原生SDK处理请求
    • 调用LLM服务进行优化
    • 流式响应处理
    • 错误处理与重试

  3. 结果处理阶段

    • 流式响应UI更新
    • 结果存储到历史记录
    • 错误恢复和降级处理

4.4 模型管理流程

  1. 模型配置管理

    • 模型配置更新
    • 连接测试
    • 配置验证
    • 错误处理

  2. API密钥管理

    • 密钥设置与加密
    • 密钥验证
    • 安全存储
    • 错误处理

4.5 模板管理流程

  1. 模板操作流程

    • 模板保存
    • 模板验证
    • 模板分类管理
    • 错误处理

  2. 模板应用流程

    • 模板获取
    • 模板应用
    • 数据验证
    • 错误处理

4.6 历史记录管理

  1. 记录保存流程

    • 添加记录
    • 数据同步
    • 自动清理
    • 错误处理

  2. 记录操作流程

    • 获取记录
    • 过滤记录
    • 删除记录
    • 错误处理

4.7 错误处理流程

  1. API错误处理策略

    • 可重试错误识别
    • 退避重试机制
    • 错误上报
    • 用户通知
    • 降级处理

  2. 验证错误处理

    • 字段验证
    • UI更新
    • 焦点处理
    • 错误提示

  3. 全局错误处理

    • 错误分类
    • 错误恢复
    • 错误上报
    • 用户反馈

5. 代码审查清单

5.1 通用审查项

  • 代码质量
    • 遵循约定的代码风格
    • 没有未使用的变量或导入
    • 适当的注释和文档
    • 避免重复代码
  • 安全性
    • 输入验证
    • 敏感信息保护
    • API密钥安全存储
    • 防止XSS攻击
  • 性能
    • 避免不必要的计算
    • 大型数据集的性能处理
    • 缓存计算结果

5.2 前端审查项

  • 组件设计
    • 组件职责单一
    • 属性和事件定义清晰
    • 状态管理合理
    • 错误处理完善
  • UI/UX
    • 响应式设计
    • 无障碍性支持
    • 良好的错误反馈
    • 加载状态处理

5.3 核心包审查项

  • API设计
    • 接口一致性
    • 错误处理标准化
    • 类型定义完整
    • 文档注释
  • 服务实现
    • 单一职责原则
    • 适当的抽象级别
    • 测试覆盖率
    • 错误恢复机制

6. 开发环境要求

6.1 开发环境

  • Node.js >= 18.0.0
  • pnpm >= 8.15.0
  • VS Code
    • Volar 1.8.x
    • ESLint
    • Prettier
    • Cursor
    • GitLens
    • Tailwind CSS IntelliSense

6.2 浏览器支持

  • Chrome >= 90
  • Firefox >= 90
  • Safari >= 14
  • Edge >= 90
  • 移动端浏览器
    • iOS Safari >= 14
    • Android Chrome >= 90

跨域代理解决方案

为了解决在纯前端应用中调用第三方LLM API时可能遇到的跨域问题，我们实现了一个基于Vercel Edge Runtime的代理解决方案。

代理架构

  1. API代理：用于处理普通请求

    • 路径：/api/proxy
    • 功能：转发普通HTTP请求，处理CORS头

  2. 流式代理：用于处理流式请求

    • 路径：/api/stream
    • 功能：转发流式响应，保持连接直到流结束

工作原理

  1. 在生产环境中（非localhost），系统会自动检测是否需要使用代理
  2. 所有API请求（包括OpenAI）都可以使用代理，通过模型配置中的useVercelProxy选项控制
  3. 代理会保留原始请求的所有头信息和请求体
  4. 代理会添加必要的CORS头，允许浏览器接收响应

代码实现

核心代理逻辑位于：

  • /api/proxy.js：处理普通请求
  • /api/stream.js：处理流式请求

环境检测逻辑位于：

  • packages/core/src/utils/environment.ts

使用方式

对于开发者来说，这个功能是透明的，不需要额外配置。系统会自动检测Vercel环境并在模型配置中提供代理选项。

在模型配置界面中，当检测到Vercel环境时，会显示"使用Vercel代理"的选项。您可以为每个模型单独配置是否启用代理功能。

安全考虑

  1. 代理仅转发请求，不存储任何数据
  2. API密钥仍然由客户端直接发送，不经过中间服务器处理
  3. 所有请求都通过HTTPS加密传输

限制

  1. Vercel Edge Functions有30秒的超时限制
  2. 有每月带宽和请求数量限制
  3. 首次请求可能有冷启动延迟

最后更新：2024-03-02