docs/archives/128-context-ui-and-variable-system-refactor/plan.md
文档版本: v2.1
创建日期: 2025-10-21
最后更新: 2025-10-23
改造范围: 上下文模式导航栏 + 测试区操作栏 + 变量系统重构
优先级: P0 🔴 高优先级
状态: ✅ 所有阶段已完成并通过测试
问题陈述:
改造目标:
[系统提示词|用户提示词]实施状态: ✅ 已完成 (2025-10-22)
packages/web/src/App.vue期望效果:
改造前:
┌────────────────────────────────────────────────────────┐
│ 📝 Prompt Optimizer | [基础|上下文|图像] | 📝📜⚙️... │
├────────────────────────────────────────────────────────┤
│ 工作区 │
│ ┌────────────────────────────────────────────────────┐│
│ │ [系统提示词|用户提示词] [模型▾] [模板▾] ││ ← 在这里
│ │ 输入框... ││
│ └────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────┘
改造后:
┌────────────────────────────────────────────────────────┐
│ 📝 Prompt Optimizer │
│ [基础|上下文|图像] [系统提示词|用户提示词] 📝📜⚙️... │ ← 移到这里
├────────────────────────────────────────────────────────┤
│ 工作区 │
│ ┌────────────────────────────────────────────────────┐│
│ │ 用户提示词输入 [模型▾] [模板▾] ││ ← 简洁清晰
│ │ 输入框... ││
│ └────────────────────────────────────────────────────┘│
└────────────────────────────────────────────────────────┘
问题陈述:
改造目标:
实施状态: ✅ 已完成 (2025-10-22)
ce90d47 - refactor(ui): 优化上下文模式快捷操作栏位置ContextUserWorkspace.vue, ContextSystemWorkspace.vue期望效果:
改造前:
┌────────────────────────┬───────────────────────────────┐
│ 左侧优化区 │ 右侧测试区 │
│ ┌────────────────────┐│ │
│ │📊📝🔧 快捷操作 ││ 测试内容... │
│ └────────────────────┘│ │
│ ┌────────────────────┐│ │
│ │ 提示词输入 ││ │
│ └────────────────────┘│ │
└────────────────────────┴───────────────────────────────┘
改造后:
┌────────────────────────┬───────────────────────────────┐
│ 左侧优化区 │ 右侧测试区 │
│ │ ┌───────────────────────────┐│
│ ┌────────────────────┐│ │ 测试 📊全局 📝会话 🔧工具 ││ ← 移到这里
│ │ 提示词输入 ││ └───────────────────────────┘│
│ │ (空间增加) ││ ┌───────────────────────────┐│
│ └────────────────────┘│ │ 变量输入... ││
│ ┌────────────────────┐│ │ 测试结果... ││
│ │ 优化结果 ││ └───────────────────────────┘│
└────────────────────────┴───────────────────────────────┘
问题陈述:
改造目标:
实际效果:
改造前:
┌─────────────────────────────────────────┐
│ 测试区 │
├─────────────────────────────────────────┤
│ [测试] [📊全局变量] [📝会话变量] [🔧工具] │
│ ↑ 困惑: 有什么区别? │
├─────────────────────────────────────────┤
改造后:
┌─────────────────────────────────────────┐
│ 测试区 │
├─────────────────────────────────────────┤
│ [测试] [📊全局变量] [🔧工具管理] │
│ ↑ 清晰: 永久保存的配置 │
├─────────────────────────────────────────┤
│ 变量输入 (临时,刷新丢失): │
│ {{style}} [欢快________] 📊 │
│ ↑ 测试输入 ↑ 使用全局值 │
│ {{topic}} [写歌________] │
├─────────────────────────────────────────┤
│ [▶ 测试] │
└─────────────────────────────────────────┘
详细设计: 见 变量系统重构设计文档
实施状态: ✅ 已完成 (2025-10-23)
3f53812 - refactor(ui): 重构变量系统并移除会话变量功能| 改造项 | 改造前 | 改造后 | 改进效果 |
|---|---|---|---|
| 子模式选择器位置 | 工作区输入面板内 | 导航栏功能模式右侧 | ✅ 层级清晰 |
| ✅ 作用域明确 | |||
| 快捷操作栏位置 | 左侧优化区上方 | 右侧测试区顶部 | ✅ 使用场景匹配 |
| ✅ 操作路径最短 | |||
| 优化区垂直空间 | 被快捷操作栏占用 | 完全释放 | ✅ 显示更多内容 |
| 用户认知负担 | 高(层级混乱) | 低(清晰分明) | ✅ 易于理解 |
| 改造项 | 改造前 | 改造后 | 改进效果 | 状态 |
|---|---|---|---|---|
| 变量系统 | 全局变量 + 会话变量 (都持久化) | 全局变量 (持久化) + 测试变量 (临时) | ✅ 概念清晰 | |
| ✅ 符合直觉 | ||||
| ✅ 降低学习成本 | ✅ 已验证 | |||
| 测试区操作栏 | 3个按钮 | 2个按钮 | ✅ UI简化 | |
| ✅ 减少困惑 | ✅ 已验证 | |||
| 变量输入方式 | 需要打开管理器 | 测试区直接输入 | ✅ 操作便捷 | |
| ✅ 贴近使用场景 | ✅ 已验证 | |||
| 持久化开销 | 高 (所有变量都持久化) | 低 (只持久化全局变量) | ✅ 性能优化 | ✅ 已验证 |
packages/web/src/
└── App.vue # 添加子模式选择器到导航栏
packages/ui/src/components/
├── MainLayoutUI.vue # 优化导航栏布局(可选)
├── InputPanel.vue # 移除子模式选择器插槽
├── context-mode/
│ ├── ContextUserWorkspace.vue # 移除快捷操作栏 + 添加测试区操作栏
│ ├── ContextSystemWorkspace.vue # 移除快捷操作栏 + 添加测试区操作栏
│ └── ContextModeActions.vue # 废弃或重构为测试区操作栏组件
└── TestAreaPanel.vue # 可选:添加 header-actions 插槽
docs/workspace/
├── ui-design-analysis.md # 更新设计分析
└── ui-refactor-plan.md # 本文档
文件: packages/web/src/App.vue
修改内容:
<template>
<MainLayoutUI>
<!-- Core Navigation Slot -->
<template #core-nav>
<NSpace :size="12" align="center">
<!-- 功能模式选择器 -->
<FunctionModeSelector
v-model="functionMode"
@update:modelValue="handleModeSelect"
/>
<!-- ✅ 新增:子模式选择器(仅上下文模式显示) -->
<OptimizationModeSelector
v-if="functionMode === 'pro'"
v-model="selectedOptimizationMode"
@change="handleOptimizationModeChange"
/>
</NSpace>
</template>
<!-- Main Workspace -->
<template #main>
<template v-if="functionMode === 'pro'">
<ContextSystemWorkspace
v-if="selectedOptimizationMode === 'system'"
...
>
<!-- ❌ 移除子模式选择器插槽 -->
<!-- <template #optimization-mode-selector>...</template> -->
</ContextSystemWorkspace>
<ContextUserWorkspace
v-else-if="selectedOptimizationMode === 'user'"
...
/>
</template>
</template>
</MainLayoutUI>
</template>
<script setup lang="ts">
import OptimizationModeSelector from '@/components/OptimizationModeSelector.vue';
// 新增状态管理
const handleModeSelect = (mode: 'basic' | 'pro' | 'image') => {
functionMode.value = mode;
// 切换到上下文模式时,默认为系统提示词
if (mode === 'pro') {
selectedOptimizationMode.value = 'system';
}
};
const handleOptimizationModeChange = (mode: OptimizationMode) => {
selectedOptimizationMode.value = mode;
console.log('[App] Optimization mode changed to:', mode);
};
</script>
代码行数: ~20 行新增/修改
风险等级: 🟢 低风险(纯 UI 调整)
文件 1: packages/ui/src/components/InputPanel.vue
修改内容:
<template>
<div class="input-panel">
<NSpace justify="space-between" align="center">
<NText strong>{{ label }}</NText>
<NSpace :size="8">
<!-- ❌ 移除子模式选择器插槽 -->
<!-- <slot name="optimization-mode-selector"></slot> -->
<!-- 保留模型和模板选择 -->
<slot name="model-select"></slot>
<slot name="template-select"></slot>
</NSpace>
</NSpace>
<!-- 提示词输入区域 -->
<NInput ... />
</div>
</template>
文件 2: packages/ui/src/components/context-mode/ContextUserWorkspace.vue
修改内容:
<template>
<NFlex justify="space-between">
<NFlex vertical>
<NCard>
<InputPanelUI ...>
<!-- ❌ 移除子模式选择器插槽 -->
<template #model-select>...</template>
<template #template-select>...</template>
</InputPanelUI>
</NCard>
<NCard>
<PromptPanelUI ... />
</NCard>
</NFlex>
<NCard>
<TestAreaPanel ... />
</NCard>
</NFlex>
</template>
文件 3: packages/ui/src/components/context-mode/ContextSystemWorkspace.vue(同样修改)
代码行数: ~10 行删除(每个文件)
风险等级: 🟡 中等风险(影响现有布局)
文件: packages/ui/src/components/context-mode/ContextUserWorkspace.vue
修改内容:
<template>
<NFlex justify="space-between" :style="{ width: '100%', height: '100%', gap: '16px' }">
<!-- 左侧:优化区域 -->
<NFlex vertical :style="{ flex: 1, overflow: 'auto', height: '100%' }">
<!-- ❌ 移除原有的快捷操作栏 -->
<!-- <NCard size="small">
<ContextModeActions ... />
</NCard> -->
<!-- 提示词输入面板 -->
<NCard :style="{ flexShrink: 0, minHeight: '200px' }">
<InputPanelUI ... />
</NCard>
<!-- 优化结果面板 -->
<NCard :style="{ flex: 1, minHeight: '200px', overflow: 'hidden' }">
<PromptPanelUI ... />
</NCard>
</NFlex>
<!-- 右侧:测试区域 -->
<NFlex vertical :style="{ flex: 1, overflow: 'auto', height: '100%', gap: '12px' }">
<!-- ✅ 新增:测试区操作栏 -->
<NCard size="small" :style="{ flexShrink: 0 }">
<NSpace justify="space-between" align="center">
<!-- 左侧:区域标识 -->
<NSpace align="center" :size="8">
<NText strong>{{ t('test.areaTitle') }}</NText>
<NTag :bordered="false" type="info" size="small">
<template #icon><span>👤</span></template>
{{ t('contextMode.user.label') }}
</NTag>
<!-- 缺失变量警告(可选) -->
<NTag
v-if="missingVariables.length > 0"
type="warning"
size="small"
>
<template #icon>
<svg width="12" height="12">
<path d="M12 2L2 12M2 2l10 10" stroke="currentColor"/>
</svg>
</template>
{{ missingVariables.length }} {{ t('variables.missing') }}
</NTag>
</NSpace>
<!-- 右侧:变量管理快捷操作 -->
<NSpace :size="8">
<NButton
size="small"
quaternary
@click="emit('open-global-variables')"
:title="t('contextMode.actions.globalVariables')"
>
<template #icon><span>📊</span></template>
<span v-if="!isMobile">
{{ t('contextMode.actions.globalVariables') }}
</span>
</NButton>
<NButton
size="small"
quaternary
@click="emit('open-context-variables')"
:title="t('contextMode.actions.contextVariables')"
>
<template #icon><span>📝</span></template>
<span v-if="!isMobile">
{{ t('contextMode.actions.contextVariables') }}
</span>
</NButton>
<NButton
size="small"
quaternary
@click="emit('open-tool-manager')"
:title="t('contextMode.actions.tools')"
>
<template #icon><span>🔧</span></template>
<span v-if="!isMobile">
{{ t('contextMode.actions.tools') }}
</span>
</NButton>
</NSpace>
</NSpace>
</NCard>
<!-- 测试区主内容 -->
<NCard :style="{ flex: 1, overflow: 'auto' }" content-style="height: 100%;">
<TestAreaPanel ... />
</NCard>
</NFlex>
</NFlex>
</template>
<script setup lang="ts">
import { computed } from 'vue';
import { useBreakpoints } from '@vueuse/core';
const breakpoints = useBreakpoints({
mobile: 0,
tablet: 768,
desktop: 1024,
});
const isMobile = breakpoints.smaller('tablet');
// 计算缺失变量
const missingVariables = computed(() => {
// 从 props 中获取变量信息
const allVars = new Set<string>();
const providedVars = {
...props.globalVariables,
...props.contextVariables,
...props.predefinedVariables,
};
// 从 optimizedPrompt 中提取占位符
const regex = /\{\{([^{}]+)\}\}/g;
let match;
while ((match = regex.exec(props.optimizedPrompt)) !== null) {
allVars.add(match[1].trim());
}
// 找出缺失的变量
return Array.from(allVars).filter(v => !providedVars[v]);
});
</script>
代码行数: ~60 行新增,~10 行删除
风险等级: 🟡 中等风险(布局调整)
文件: packages/ui/src/components/context-mode/ContextSystemWorkspace.vue
修改内容:(与 ContextUserWorkspace.vue 类似)
<template>
<NFlex justify="space-between">
<!-- 左侧:优化区域 -->
<NFlex vertical>
<!-- ❌ 移除快捷操作栏 -->
<NCard><InputPanelUI ... /></NCard>
<NCard><ConversationManager ... /></NCard>
<NCard><PromptPanelUI ... /></NCard>
</NFlex>
<!-- 右侧:测试区域 -->
<NFlex vertical :style="{ gap: '12px' }">
<!-- ✅ 新增:测试区操作栏 -->
<NCard size="small">
<NSpace justify="space-between">
<NSpace align="center">
<NText strong>{{ t('test.areaTitle') }}</NText>
<NTag type="info" size="small">
<template #icon><span>⚙️</span></template>
{{ t('contextMode.system.label') }}
</NTag>
</NSpace>
<NSpace :size="8">
<NButton size="small" quaternary @click="emit('open-global-variables')">
<template #icon><span>📊</span></template>
<span v-if="!isMobile">{{ t('contextMode.actions.globalVariables') }}</span>
</NButton>
<NButton size="small" quaternary @click="emit('open-context-variables')">
<template #icon><span>📝</span></template>
<span v-if="!isMobile">{{ t('contextMode.actions.contextVariables') }}</span>
</NButton>
<!-- 系统模式不显示工具管理按钮 -->
</NSpace>
</NSpace>
</NCard>
<!-- 测试区主内容 -->
<NCard :style="{ flex: 1 }">
<TestAreaPanel ... />
</NCard>
</NFlex>
</NFlex>
</template>
代码行数: ~50 行新增,~10 行删除
风险等级: 🟡 中等风险
选项 A: 废弃组件(推荐)
packages/ui/src/components/context-mode/ContextModeActions.vue选项 B: 重构为通用组件
TestAreaActions.vue建议: 选择选项 A,代码直接内嵌到 Workspace 组件中,减少组件层级
代码行数: ~50 行删除
风险等级: 🟢 低风险(废弃未使用组件)
| 测试项 | 测试步骤 | 预期结果 |
|---|---|---|
| 子模式选择器显示 | 1. 选择「基础模式」 |
| 测试项 | 检查点 |
|---|---|
| 导航栏布局 | ✅ 功能模式和子模式在同一行 |
| ✅ 间距合适(12px) | |
| ✅ 与操作按钮对齐良好 | |
| 测试区操作栏 | ✅ 区域标识清晰 |
| ✅ 按钮组对齐 | |
| ✅ 与测试内容间距合适 | |
| 响应式适配 | ✅ 桌面端显示完整文字 |
| ✅ 移动端仅显示图标 | |
| ✅ 小屏幕下不拥挤 |
| 浏览器 | 分辨率 | 测试结果 |
|---|---|---|
| Chrome 120+ | 1920x1080 | ✅ 通过 |
| Chrome 120+ | 1366x768 | ✅ 通过 |
| Chrome 120+ | 375x667 (Mobile) | ✅ 通过 |
| Firefox 120+ | 1920x1080 | ✅ 通过 |
| Safari 17+ | 1920x1080 | ✅ 通过 |
| Edge 120+ | 1920x1080 | ✅ 通过 |
| 阶段 | 任务 | 预计工时 | 实际工时 | 状态 | 完成日期 |
|---|---|---|---|---|---|
| 阶段 1 | 子模式选择器移到导航栏 | 4 小时 | ~3 小时 | ✅ | 2025-10-21 |
| 阶段 2 | 快捷操作栏移到测试区 | 6 小时 | ~5 小时 | ✅ | 2025-10-22 |
| 阶段 3 | 变量系统重构 | 8 小时 | ~12 小时 | ✅ | 2025-10-22 |
| 阶段 4 | 测试验证 + Bug 修复 | 4 小时 | ~3 小时 | ✅ | 2025-10-23 |
| 阶段 5 | 文档更新 + Code Review | 2 小时 | ~2 小时 | ✅ | 2025-10-23 |
总工时: 24 小时(3 个工作日)- 实际工时约 25 小时
2025-10-21 (阶段1)
2025-10-22 (阶段2+3)
2025-10-23 (阶段4+5)
| 风险项 | 风险等级 | 影响范围 | 缓解措施 |
|---|---|---|---|
| 状态管理复杂 | 🟡 中 | 子模式切换可能导致状态丢失 | 1. 在切换前保存状态 |
| 风险项 | 风险等级 | 影响 | 缓解措施 |
|---|---|---|---|
| 用户习惯改变 | 🟡 中 | 老用户可能不适应新布局 | 1. 提供新手引导 |
如果改造后出现严重问题,回滚步骤:
Git 回滚
git revert <commit-hash>
git push origin develop
版本降级
数据兼容
状态: 所有验收标准已通过 (2025-10-23)
FunctionModeSelector.vue - 功能模式选择器OptimizationModeSelector.vue - 子模式选择器ContextUserWorkspace.vue - 用户模式工作区ContextSystemWorkspace.vue - 系统模式工作区TestAreaPanel.vue - 测试区域面板基础模式子模式选择器
图像模式子模式选择器
测试区操作栏增强
变量管理优化
会话管理器优化
个性化布局
工作区预设
| 版本 | 日期 | 变更内容 | 状态 |
|---|---|---|---|
| v1.0 | 2025-10-21 | 初始版本,定义改造方案 | ✅ |
| v1.1 | 2025-10-22 | 完成阶段1、2改造 | ✅ |
| v2.0 | 2025-10-22 | 完成变量系统重构 | ✅ |
| v2.1 | 2025-10-23 | 所有阶段完成并通过测试,更新文档状态 | ✅ |
| 角色 | 姓名 | 职责 | 状态 |
|---|---|---|---|
| 产品负责人 | - | 需求确认、验收 | ✅ 已完成 |
| 开发负责人 | - | 技术实现、Code Review | ✅ 已完成 |
| 测试负责人 | - | 测试计划、质量保证 | ✅ 已完成 |
| UI 设计师 | - | 视觉验收、设计指导 | ✅ 已完成 |
文档状态: ✅ 已完成并归档
最后更新: 2025-10-23
项目状态: 所有改造已完成并通过测试