docs/developer/technical-development-guide.md
注意: 本文档整合了原有的开发指南和技术文档，提供完整的技术栈说明和开发规范。
接口一致性
错误处理
原生SDK集成
错误映射
类型安全性
类型导出
单元测试
集成测试
推荐目录结构
src/
├── components/ # UI组件
├── composables/ # 组合式函数
├── views/ # 页面组件
├── services/ # 服务层
├── config/ # 配置文件
├── assets/ # 静态资源
├── utils/ # 工具函数
├── types/ # 类型定义
├── App.vue # 根组件
└── main.ts # 入口文件
命名规范
核心服务集成
错误处理
Vue组件模板
组件设计原则
Vue组件类型
通用工具类型
Composables模式
响应式状态管理
项目级tsconfig.json配置
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"moduleResolution": "node",
"strict": true,
"jsx": "preserve",
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
"noEmit": true,
"useDefineForClassFields": true
},
"include": ["src/**/*", "*.vue"],
"exclude": ["node_modules", "dist"]
}
Vue组件类型定义
// 组件Props类型定义
interface ComponentProps {
title: string
items: Array<{ id: string, name: string }>
onSelect?: (item: any) => void
}
// 组件Emits类型定义
const emit = defineEmits<{
select: [item: any]
update: [value: string]
}>()
// 响应式数据类型
const formData = ref<{
username: string
modelConfig: ModelConfig | null
}>({
username: '',
modelConfig: null
})
服务接口类型安全
// 服务依赖注入类型
interface Services {
modelManager: IModelManager
templateManager: ITemplateManager
variableManager: IVariableManager
}
const services = inject<{ value: Services | null }>('services')
if (!services?.value) {
throw new Error('Services not provided')
}
基础ESLint配置
{
"root": true,
"parser": "vue-eslint-parser",
"parserOptions": {
"parser": "@typescript-eslint/parser",
"ecmaVersion": 2022,
"sourceType": "module",
"extraFileExtensions": [".vue"]
},
"plugins": ["@typescript-eslint", "vue"],
"extends": [
"eslint:recommended",
"@vue/eslint-config-typescript/recommended"
],
"rules": {
"@typescript-eslint/no-unused-vars": "warn",
"@typescript-eslint/no-explicit-any": "warn",
"vue/multi-word-component-names": "off",
"vue/no-unused-vars": "error"
}
}
Vue文件特定规则
{
"rules": {
"vue/component-name-in-template-casing": ["error", "PascalCase"],
"vue/prop-name-casing": ["error", "camelCase"],
"vue/attribute-hyphenation": ["error", "always"],
"vue/v-on-event-hyphenation": ["error", "always"],
"vue/no-unused-components": "warn",
"vue/require-default-prop": "off"
}
}
VS Code配置 (.vscode/settings.json)
{
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"eslint.validate": [
"javascript",
"typescript",
"vue"
],
"vetur.validation.template": false,
"vetur.validation.script": false,
"vetur.validation.style": false
}
动态导入
渲染优化
企业级设计
TypeScript支持
主题系统
基础配置
<template>
<NConfigProvider :theme="naiveTheme" :theme-overrides="themeOverrides">
<!-- 应用内容 -->
</NConfigProvider>
</template>
<script setup>
import { useNaiveTheme } from '@prompt-optimizer/ui'
const { naiveTheme, themeOverrides } = useNaiveTheme()
</script>
主题配置
// config/naive-theme.ts
export const themeConfig = {
light: lightTheme,
dark: darkTheme,
blue: createCustomTheme(blueColors),
green: createCustomTheme(greenColors),
purple: createCustomTheme(purpleColors)
}
组件使用
<template>
<NButton type="primary" @click="handleClick">
按钮
</NButton>
<NCard title="卡片标题">
<p>卡片内容</p>
</NCard>
</template>
<script setup>
import { NButton, NCard } from 'naive-ui'
</script>
系统提供5种完整主题配置，每种主题都包含完整的颜色体系和组件样式定制：
1. 日间模式 (light)
2. 夜间模式 (dark)
3. 蓝色模式 (blue)
4. 绿色模式 (green)
5. 暗紫模式 (purple)
1. 表单组件
<template>
<NForm ref="formRef" :model="formModel" :rules="formRules">
<NFormItem label="用户名" path="username">
<NInput v-model:value="formModel.username" placeholder="请输入用户名" />
</NFormItem>
<NFormItem label="模型选择" path="model">
<NSelect
v-model:value="formModel.model"
:options="modelOptions"
placeholder="请选择模型"
/>
</NFormItem>
<NFormItem>
<NButton type="primary" @click="handleSubmit">
提交
</NButton>
</NFormItem>
</NForm>
</template>
2. 布局组件
<template>
<!-- 弹性布局 - 推荐用于现代布局 -->
<NFlex vertical :size="16">
<NFlex justify="space-between" align="center">
<NH3>标题</NH3>
<NButton type="primary">操作</NButton>
</NFlex>
<!-- 卡片容器 -->
<NCard title="内容卡片" hoverable>
<NFlex :size="12">
<NTag type="info">标签1</NTag>
<NTag type="success">标签2</NTag>
</NFlex>
</NCard>
</NFlex>
<!-- 传统间距布局 -->
<NSpace vertical :size="16">
<NSpace justify="space-between" align="center">
<NText strong>列表标题</NText>
<NButton quaternary>更多</NButton>
</NSpace>
</NSpace>
<!-- 网格布局 -->
<NGrid :cols="3" :x-gap="16" :y-gap="16">
<NGridItem v-for="item in items" :key="item.id">
<NCard>{{ item.content }}</NCard>
</NGridItem>
</NGrid>
</template>
3. 反馈组件
<script setup>
import { useMessage, useNotification } from 'naive-ui'
const message = useMessage()
const notification = useNotification()
const showToast = () => {
message.success('操作成功')
}
const showNotification = () => {
notification.info({
title: '通知标题',
content: '通知内容',
duration: 3000
})
}
</script>
4. 变量管理组件使用模式
<script setup>
import { useVariableManager } from '@prompt-optimizer/ui'
const services = inject('services')
const {
isReady,
isAdvancedMode,
customVariables,
allVariables,
setAdvancedMode,
addVariable,
updateVariable,
deleteVariable,
replaceVariables
} = useVariableManager(services, { autoSync: true })
// 使用变量替换
const processedContent = computed(() => {
return replaceVariables(originalContent.value, allVariables.value)
})
</script>
组件测试
服务测试
核心服务加载顺序
服务实例创建流程
应用配置加载
服务状态同步
用户输入阶段
优化处理阶段
结果处理阶段
模型配置管理
llmParams):
ModelConfig 接口包含一个 llmParams?: Record<string, any>; 字段。"llmParams": {
"temperature": 0.7,
"max_tokens": 4096,
"timeout": 60000, // 用于OpenAI客户端的请求超时 (毫秒)
"top_p": 0.9,
"frequency_penalty": 0.5
// ... 其他OpenAI支持的参数
}
"llmParams": {
"temperature": 0.8,
"maxOutputTokens": 2048, // 注意: Gemini使用maxOutputTokens
"topP": 0.95,
"topK": 40
// ... 其他Gemini支持的参数
}
LLMService 如何处理 llmParams:
timeout 值（如果提供）用于配置OpenAI JavaScript SDK客户端实例的超时设置。其余参数（如 temperature, max_tokens, top_p 等）会直接传递给 chat.completions.create() 方法。temperature, maxOutputTokens, topP, topK 等参数会包含在传递给 model.startChat() 的 generationConfig 对象中。timeout for OpenAI, 或非已知Gemini参数）通常会被安全地传递给相应SDK的请求中，如果SDK支持它们。llmParams 字段（如果提供）必须是一个对象。API密钥管理
模板操作流程
模板应用流程
记录保存流程
记录操作流程
API错误处理策略
验证错误处理
全局错误处理
由于安全原因(SSRF漏洞风险，详见 GitHub Issue #169)，我们已在v1.x版本中完全移除了Vercel和Docker内置代理功能。
如遇跨域问题，请使用以下方案：
桌面版应用(推荐)
自建反向代理
docs/archives/122-docker-api-proxy/ 中的历史实现LLM提供商自有代理
早期版本(v0.x)曾提供内置代理端点(/api/proxy, /api/stream)，但因安全审计发现SSRF风险已移除。历史实现可查看 docs/archives/122-docker-api-proxy/implementation.md
最后更新：2025-01-21