prompt-optimizer/docs/experience.md

项目核心经验总结

📋 核心知识点

• 架构设计 - API集成、模块化结构
• 错误处理 - 常见问题与解决方案
• 测试规范 - 关键测试要点
• 开发实践 - Vue、工具配置、最佳实践
• 重要Bug修复 - 安全漏洞与性能问题

---

架构设计

API集成核心原则

// 统一OpenAI兼容格式
export default {
  baseURL: "https://api.openai.com/v1", 
  models: ["gpt-4", "gpt-3.5"],
  apiKey: import.meta.env.VITE_API_KEY // Vite项目必须使用import.meta.env
}

模块化结构

src/
├─ api/        # API封装层
├─ services/   # 业务逻辑  
├─ config/     # 配置管理
├─ components/ # UI组件
└─ prompts/    # 提示模板

LLM服务设计要点

• 接口标准化: 统一使用OpenAI格式
• 多服务商兼容: Provider标识区分
• 敏感信息管理: 环境变量+本地加密存储
• 用户自管理API密钥: 避免后端开销，保持应用简单性
• 参数透明化: 只使用用户明确配置的参数，不设置默认值避免误解

---

错误处理

核心处理策略

// 统一错误处理模板
try {
  await apiCall();
} catch (err) {
  console.error("[API Error]", err.context);
  throw new Error("友好的错误提示");
}

常见问题速查表

问题	解决方案	日期
模板ID与模型Key混淆	明确功能ID与API Key分离	2024-03-22
状态同步异常	增加状态同步处理函数	2024-03-22
全局Provider污染	显式传递模型参数	2024-03-22

---

测试规范

关键要点

1. 环境变量: Vite项目使用 import.meta.env.VITE_*
2. 测试隔离: 使用动态唯一标识符避免冲突
3. 错误场景: 覆盖网络错误、无效Token等异常
4. 状态管理: 独立测试数据库、正确清理状态
5. 参数测试: 为每个LLM参数创建独立测试用例，确保参数兼容性

测试模板

describe("功能测试", () => {
  beforeEach(() => {
    // 使用唯一标识符
    testId = `test-${Date.now()}`;
  });
  
  it("应正确处理异常", async () => {
    await expect(func()).rejects.toThrow("预期错误");
  });
});

// LLM参数测试最佳实践
describe("Individual Parameter Tests", () => {
  // 为每个advancedParameterDefinitions中的参数创建独立测试
  it("should accept valid temperature", async () => {
    await modelManager.updateModel(configKey, {
      // ... 基础配置
      llmParams: { temperature: 0.3 } // 只测试一个参数
    });
    
    const response = await llmService.sendMessage(messages, configKey);
    expect(response).toBeDefined();
  });
  
  // 组合参数测试
  it("should handle multiple parameters together", async () => {
    await modelManager.updateModel(configKey, {
      // ... 基础配置  
      llmParams: {
        temperature: 0.6,
        max_tokens: 150,
        top_p: 0.9
      }
    });
  });
});

---

开发实践

Vue开发规范

// ✅ 正确: 组件顶层调用Composable
const { data } = useFetch();

// ❌ 错误: 生命周期内调用
onMounted(() => {
  const { data } = useFetch(); // 禁止
});

工具配置

# 常用NPM命令
npm outdated          # 检查更新
ncu -u "eslint*"      # 安全更新指定包
npm run test          # 每次修改后必须执行

流式处理最佳实践

// 统一流式处理器
const handlers = {
  onToken: (token) => result.value += token,
  onComplete: () => isLoading.value = false,
  onError: (error) => toast.error(error.message)
};

---

重要Bug修复

安全漏洞修复 (2024-12-20)

Bug类型	风险等级	修复状态
UI配置导入验证不充分	中	✅ 已修复
数据迁移竞态条件	中	✅ 已修复
测试覆盖缺失	高	✅ 已修复
LLM参数默认值误导用户	中	✅ 已修复

关键修复示例

// UI配置导入安全验证
for (const [key, value] of Object.entries(typedData.userSettings)) {
  // 白名单验证
  if (!UI_SETTINGS_KEYS.includes(key as any)) {
    console.warn(`跳过未知的UI配置键: ${key}`);
    continue;
  }
  // 类型验证
  if (typeof value !== 'string') {
    console.warn(`跳过无效类型 ${key}: ${typeof value}`);
    continue;
  }
  await this.storage.setItem(key, value);
}

// LLM参数透明化处理 (2024-12-20)
// ❌ 旧版本：自动设置默认值
if (completionConfig.temperature === undefined) {
  completionConfig.temperature = 0.7; // 可能误导用户
}

// ✅ 新版本：只使用用户明确配置的参数
const completionConfig: any = {
  model: modelConfig.defaultModel,
  messages: formattedMessages,
  ...restLlmParams // 只传递用户配置的参数
};
// 不设置任何默认值，让API服务商使用其默认配置

---

核心经验要点

配置管理

• 业务逻辑与API配置解耦
• 支持动态配置更新
• 环境变量使用Vite规范

错误处理

• 开发环境保留完整堆栈
• 生产环境友好提示+日志
• 统一错误处理机制

测试策略

• 测试用例隔离
• 覆盖边界条件
• Mock最小必要依赖

安全考虑

• 输入验证白名单
• 防止原型污染
• 数据迁移原子性

性能优化

• 流式处理提升体验
• 组件懒加载
• 合理状态管理