mirror of
https://github.com/linshenkx/prompt-optimizer.git
synced 2026-06-08 01:58:56 +08:00
366 lines
9.9 KiB
Markdown
366 lines
9.9 KiB
Markdown
# 开发经验总结
|
||
|
||
## 🎯 核心经验
|
||
|
||
### 1. 向后兼容策略设计模式
|
||
**核心原则**: 使用可选字段扩展而非重写接口
|
||
```typescript
|
||
// ✅ 正确的扩展方式
|
||
interface OptimizationRequest {
|
||
// 现有字段保持不变
|
||
optimizationMode: OptimizationMode;
|
||
targetPrompt: string;
|
||
|
||
// 新功能作为可选字段
|
||
advancedContext?: {
|
||
variables?: Record<string, string>;
|
||
messages?: ConversationMessage[];
|
||
};
|
||
}
|
||
|
||
// ❌ 错误的方式：创建新接口
|
||
interface AdvancedOptimizationRequest extends OptimizationRequest {
|
||
// 这会破坏现有代码
|
||
}
|
||
```
|
||
**适用场景**: 任何需要扩展现有功能的情况
|
||
**关键价值**: 确保现有用户无感升级，新用户可选择使用高级功能
|
||
|
||
### 2. 渐进式UI功能发现模式
|
||
**设计思想**: 通过导航菜单实现功能的渐进式暴露
|
||
```vue
|
||
<!-- 高级模式按钮 - 始终可见，引导用户发现 -->
|
||
<ActionButtonUI
|
||
icon="🚀"
|
||
:text="$t('nav.advancedMode')"
|
||
@click="toggleAdvancedMode"
|
||
:class="{ 'active-button': advancedModeEnabled }"
|
||
/>
|
||
|
||
<!-- 变量管理按钮 - 仅在高级模式下显示 -->
|
||
<ActionButtonUI
|
||
v-if="advancedModeEnabled"
|
||
icon="📊"
|
||
:text="$t('nav.variableManager')"
|
||
@click="showVariableManager = true"
|
||
/>
|
||
```
|
||
**核心价值**: 既保持简洁性，又提供高级功能的可发现性
|
||
|
||
### 3. 多LLM提供商统一接口模式
|
||
**架构策略**: 抽象统一接口，各提供商适配转换
|
||
```typescript
|
||
// 统一的工具调用结果格式
|
||
export interface ToolCall {
|
||
id: string;
|
||
type: 'function';
|
||
function: {
|
||
name: string;
|
||
arguments: string;
|
||
};
|
||
}
|
||
|
||
// OpenAI直接映射
|
||
const openaiToolCall = chunk.choices[0]?.delta?.tool_calls?.[0];
|
||
|
||
// Gemini需要转换
|
||
const geminiToolCall: ToolCall = {
|
||
id: `call_${Date.now()}`,
|
||
type: 'function' as const,
|
||
function: {
|
||
name: functionCall.name,
|
||
arguments: JSON.stringify(functionCall.args)
|
||
}
|
||
};
|
||
```
|
||
**关键优势**: 新增LLM提供商时只需实现转换逻辑，业务代码无需修改
|
||
|
||
## 🛠️ 技术实现经验
|
||
|
||
### 1. Vue 3响应式状态管理最佳实践
|
||
**模式**: 组合式API + 服务注入
|
||
```typescript
|
||
// ✅ 推荐的状态管理方式
|
||
export function useVariableManager() {
|
||
const customVariables = ref<Record<string, string>>({});
|
||
|
||
// 响应式计算属性
|
||
const allVariables = computed(() => {
|
||
return { ...predefinedVariables.value, ...customVariables.value };
|
||
});
|
||
|
||
// 方法封装
|
||
const setVariable = (name: string, value: string) => {
|
||
customVariables.value[name] = value;
|
||
saveToStorage(); // 自动持久化
|
||
};
|
||
|
||
return { allVariables, setVariable };
|
||
}
|
||
```
|
||
**避坑指南**: 不要在computed中进行副作用操作，保持纯函数特性
|
||
|
||
### 2. TypeScript类型安全实践
|
||
**关键技巧**: 使用字面量类型和断言确保类型安全
|
||
```typescript
|
||
// 问题：string类型不能赋值给字面量类型
|
||
const toolCall = {
|
||
type: 'function' // TypeScript推断为string
|
||
};
|
||
|
||
// 解决方案1：使用as const断言
|
||
const toolCall = {
|
||
type: 'function' as const // 推断为'function'
|
||
};
|
||
|
||
// 解决方案2：显式类型声明
|
||
const toolCall: ToolCall = {
|
||
type: 'function' // 符合ToolCall类型定义
|
||
};
|
||
```
|
||
|
||
### 3. 组件状态同步策略
|
||
**问题**: 多个组件实例导致状态不一致
|
||
**解决方案**: 统一实例管理
|
||
```typescript
|
||
// App.vue 创建统一实例
|
||
const variableManager = new VariableManager();
|
||
|
||
// 子组件优先使用传入实例
|
||
const activeVariableManager = computed(() => {
|
||
return props.variableManager || localVariableManager;
|
||
});
|
||
```
|
||
**关键原则**: 单一数据源，避免状态分散
|
||
|
||
### 4. 主题CSS集成模式
|
||
**策略**: 使用语义化CSS类而非硬编码样式
|
||
```vue
|
||
<!-- ❌ 硬编码样式 -->
|
||
<div class="bg-white dark:bg-gray-800 border rounded-lg p-4">
|
||
|
||
<!-- ✅ 使用主题系统 -->
|
||
<div class="theme-manager-card theme-manager-padding">
|
||
```
|
||
**优势**: 自动适配主题切换，减少维护成本
|
||
|
||
## 🚫 避坑指南
|
||
|
||
### 1. 接口扩展的时机选择
|
||
**错误做法**: 过早创建新接口
|
||
```typescript
|
||
// ❌ 不要过早抽象
|
||
interface BasicRequest { /* ... */ }
|
||
interface AdvancedRequest { /* ... */ }
|
||
interface SuperAdvancedRequest { /* ... */ }
|
||
```
|
||
**正确做法**: 基于可选字段渐进式扩展
|
||
```typescript
|
||
// ✅ 渐进式扩展
|
||
interface Request {
|
||
// 核心字段
|
||
basic: string;
|
||
// 第一次扩展
|
||
advanced?: AdvancedOptions;
|
||
// 第二次扩展
|
||
superAdvanced?: SuperAdvancedOptions;
|
||
}
|
||
```
|
||
|
||
### 2. 组件通信复杂度控制
|
||
**反模式**: 深层props传递
|
||
```vue
|
||
<!-- ❌ 避免深层传递 -->
|
||
<GrandParent>
|
||
<Parent :data="data">
|
||
<Child :data="data">
|
||
<GrandChild :data="data" />
|
||
</Child>
|
||
</Parent>
|
||
</GrandParent>
|
||
```
|
||
**推荐模式**: 服务层解耦
|
||
```typescript
|
||
// ✅ 通过服务层通信
|
||
const variableService = inject('variableService');
|
||
// 任何组件都可以直接使用服务
|
||
```
|
||
|
||
### 3. 性能优化的时机
|
||
**错误时机**: 功能未完成就开始优化
|
||
**正确时机**: 功能完整后针对性优化
|
||
```typescript
|
||
// 功能完成后的性能优化
|
||
const debouncedSave = debounce(saveVariables, 300);
|
||
const virtualizedList = useVirtualList(largeVariableList);
|
||
```
|
||
|
||
### 4. 测试用例的设计误区
|
||
**错误方式**: 只测试正常流程
|
||
**正确方式**: 重点测试边界情况
|
||
```typescript
|
||
describe('VariableManager', () => {
|
||
it('should handle invalid variable names', () => {
|
||
// 测试特殊字符、空字符串、保留字等
|
||
});
|
||
|
||
it('should recover from storage corruption', () => {
|
||
// 测试存储数据损坏的恢复机制
|
||
});
|
||
});
|
||
```
|
||
|
||
## 🔄 架构设计经验
|
||
|
||
### 1. 服务层职责划分原则
|
||
**UI层职责**: 用户交互、状态展示、本地状态管理
|
||
```typescript
|
||
// UI层：变量管理UI逻辑
|
||
export class VariableManagerUI {
|
||
private customVariables = ref({});
|
||
|
||
// UI相关方法：验证、格式化、本地存储
|
||
validateAndSave(name: string, value: string) { /* ... */ }
|
||
}
|
||
```
|
||
|
||
**Core层职责**: 业务逻辑、数据处理、API调用
|
||
```typescript
|
||
// Core层：模板处理逻辑
|
||
export class TemplateProcessor {
|
||
// 纯业务逻辑：变量替换、模板渲染
|
||
replaceVariables(template: string, variables: Record<string, string>) { /* ... */ }
|
||
}
|
||
```
|
||
|
||
### 2. 扩展点设计模式
|
||
**策略**: 预留扩展接口，支持插件化
|
||
```typescript
|
||
export interface IVariableProvider {
|
||
getVariables(): Record<string, string>;
|
||
}
|
||
|
||
export class VariableManager {
|
||
private providers: IVariableProvider[] = [];
|
||
|
||
// 支持插件注册
|
||
addProvider(provider: IVariableProvider) {
|
||
this.providers.push(provider);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 错误处理层次化策略
|
||
```typescript
|
||
// 层次1：业务逻辑错误
|
||
class VariableValidationError extends Error {
|
||
constructor(variableName: string) {
|
||
super(`Invalid variable name: ${variableName}`);
|
||
}
|
||
}
|
||
|
||
// 层次2：系统级错误
|
||
class StorageError extends Error {
|
||
constructor(operation: string) {
|
||
super(`Storage ${operation} failed`);
|
||
}
|
||
}
|
||
|
||
// 层次3：用户友好提示
|
||
const handleError = (error: Error) => {
|
||
if (error instanceof VariableValidationError) {
|
||
toast.warning('变量名格式不正确');
|
||
} else {
|
||
toast.error('操作失败，请重试');
|
||
}
|
||
};
|
||
```
|
||
|
||
## 💡 创新解决方案
|
||
|
||
### 1. 智能会话模板配置系统
|
||
**创新点**: 根据优化模式自动生成合适的测试环境
|
||
```typescript
|
||
// 传统方式：用户手动配置测试环境
|
||
// 创新方式：智能模板生成
|
||
if (optimizationMode === 'system') {
|
||
// 系统提示词：创建系统+用户消息对
|
||
conversationMessages = [
|
||
{ role: 'system', content: '{{currentPrompt}}' },
|
||
{ role: 'user', content: '请展示你的能力并与我互动' }
|
||
];
|
||
} else {
|
||
// 用户提示词：创建用户消息
|
||
conversationMessages = [
|
||
{ role: 'user', content: '{{currentPrompt}}' }
|
||
];
|
||
}
|
||
```
|
||
|
||
### 2. 变量工具分离设计
|
||
**设计决策**: 变量系统和工具系统完全分离
|
||
**理由**: 避免概念混淆，简化用户理解
|
||
```typescript
|
||
// 变量：用于内容模板化
|
||
const variables = { userName: 'Alice', task: 'coding' };
|
||
const template = 'Hello {{userName}}, let\'s start {{task}}';
|
||
|
||
// 工具：用于LLM功能调用
|
||
const tools = [{
|
||
function: { name: 'get_weather', parameters: { ... } }
|
||
}];
|
||
```
|
||
|
||
### 3. 渐进式功能暴露机制
|
||
**创新**: 通过UI状态控制功能可见性
|
||
```typescript
|
||
const featureVisibility = computed(() => ({
|
||
basicMode: true,
|
||
advancedMode: advancedModeEnabled.value,
|
||
variableManager: advancedModeEnabled.value,
|
||
toolManager: advancedModeEnabled.value && hasTools.value
|
||
}));
|
||
```
|
||
|
||
## 📚 可复用模式库
|
||
|
||
### 1. 可选功能扩展模式
|
||
适用于任何需要向后兼容的功能增强场景：
|
||
1. 定义可选字段的接口扩展
|
||
2. 实现新功能的独立组件
|
||
3. 通过配置控制功能启用
|
||
4. 保持默认行为不变
|
||
|
||
### 2. 服务注入 + 组合式API模式
|
||
适用于复杂状态管理场景：
|
||
1. 创建服务类封装业务逻辑
|
||
2. 使用组合式API封装响应式状态
|
||
3. 通过依赖注入实现组件解耦
|
||
4. 支持单元测试和模拟
|
||
|
||
### 3. 多提供商适配模式
|
||
适用于需要集成多个第三方服务的场景：
|
||
1. 定义统一的接口抽象
|
||
2. 为每个提供商实现适配器
|
||
3. 使用工厂模式选择具体实现
|
||
4. 保持业务代码与提供商无关
|
||
|
||
## 🔮 后续演进建议
|
||
|
||
### 短期优化 (1个月内)
|
||
1. **性能监控**: 添加变量解析和工具调用的性能指标
|
||
2. **用户体验**: 更多智能默认值和快捷操作
|
||
3. **错误处理**: 改进边缘情况的错误提示
|
||
|
||
### 中期扩展 (3个月内)
|
||
1. **模板市场**: 支持预设的变量和工具模板分享
|
||
2. **使用分析**: 记录功能使用情况，指导优化方向
|
||
3. **协作功能**: 支持团队共享变量和工具定义
|
||
|
||
### 长期愿景 (6个月以上)
|
||
1. **AI增强**: 智能推荐变量、自动生成测试用例
|
||
2. **可视化编辑**: 拖拽式会话流程设计器
|
||
3. **企业级功能**: 权限管理、审计日志、批量操作
|
||
|
||
这些经验和模式可以应用到任何大型功能迭代过程中，特别是需要保持向后兼容性和用户体验平滑升级的场景。
|