刘国栋
8f7f082c3d
- 重构项目目录结构，将功能模块移至 modules/ 目录 - 创建平台同步基础架构，包括发布器基类和 GitHub 发布器 - 新增 UI 状态管理模块 (modules/ui/state.py) 统一管理会话状态 - 更新依赖配置，添加平台同步所需依赖 (httpx, pyperclip) - 整理文档结构，将所有文档分类移至 docs/ 目录 - 添加 .cursorrules 文件定义项目开发规范 - 清理根目录重复文件，保持项目结构整洁
529 lines
16 KiB
Markdown
529 lines
16 KiB
Markdown
# Tab 1：关键词蒸馏 - 代码逻辑与 AI 提示词全面检查报告
|
||
|
||
> **检查日期**：2026-01-28
|
||
> **检查范围**：Tab 1 完整代码逻辑、AI 提示词、错误处理、边界条件
|
||
> **检查维度**：逻辑正确性、提示词质量、错误处理、性能、用户体验
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [代码逻辑检查](#代码逻辑检查)
|
||
2. [AI 提示词检查](#ai-提示词检查)
|
||
3. [错误处理检查](#错误处理检查)
|
||
4. [边界条件检查](#边界条件检查)
|
||
5. [性能问题检查](#性能问题检查)
|
||
6. [用户体验问题检查](#用户体验问题检查)
|
||
7. [修复建议清单](#修复建议清单)
|
||
|
||
---
|
||
|
||
## 代码逻辑检查
|
||
|
||
### ✅ 正常逻辑
|
||
|
||
#### 1. 模式选择逻辑
|
||
- **位置**：第 932-940 行
|
||
- **状态**：✅ 正常
|
||
- **说明**：正确使用 `st.radio` 和 `st.session_state` 管理模式状态
|
||
|
||
#### 2. 词库初始化逻辑
|
||
- **位置**：第 944-952 行
|
||
- **状态**：✅ 正常
|
||
- **说明**：正确检查 `wordbanks` 是否为 None 并初始化
|
||
|
||
#### 3. 组合模式选择逻辑
|
||
- **位置**：第 954-981 行
|
||
- **状态**：✅ 正常
|
||
- **说明**：正确处理多选和默认值
|
||
|
||
#### 4. 词库编辑逻辑
|
||
- **位置**：第 993-1043 行
|
||
- **状态**：✅ 正常
|
||
- **说明**：横向展示、单列更新、批量更新逻辑正确
|
||
|
||
### ⚠️ 潜在问题
|
||
|
||
#### 1. 词库编辑 - 状态同步问题
|
||
- **位置**：第 1000-1026 行
|
||
- **问题**：`edited_wordbanks` 在循环中收集，但如果在循环中点击"更新"按钮，可能导致状态不一致
|
||
- **影响**：中等
|
||
- **建议**：在循环外统一处理更新逻辑
|
||
|
||
#### 2. 生成控制 - 禁用条件判断
|
||
- **位置**：第 1098-1105 行
|
||
- **问题**：托词工具模式的禁用条件检查了 `selected_patterns`，但如果用户刚切换模式，可能还未初始化
|
||
- **影响**：低
|
||
- **建议**：确保在检查前已初始化
|
||
|
||
#### 3. 混合模式 - 空关键词处理
|
||
- **位置**：第 1270-1286 行
|
||
- **问题**：如果 `raw_keywords` 为空，直接赋值给 `keywords`，但后续清理逻辑可能有问题
|
||
- **影响**：低
|
||
- **建议**：添加空值检查
|
||
|
||
#### 4. 语义扩展 - 状态管理
|
||
- **位置**：第 1452-1496 行
|
||
- **问题**：扩展后直接修改 `st.session_state.keywords`，但未检查扩展前是否有扩展关键词
|
||
- **影响**：中等
|
||
- **建议**：在扩展前保存原始关键词列表
|
||
|
||
#### 5. 话题集群 - 重复实例化
|
||
- **位置**：第 1586 行
|
||
- **问题**：每次点击都创建新的 `TopicCluster()` 实例，可能浪费资源
|
||
- **影响**：低
|
||
- **建议**：考虑缓存实例
|
||
|
||
#### 6. 智能挖掘 - 重复实例化
|
||
- **位置**：第 1852 行
|
||
- **问题**：每次展开都创建新的 `KeywordMining()` 实例
|
||
- **影响**：低
|
||
- **建议**：考虑缓存实例
|
||
|
||
---
|
||
|
||
## AI 提示词检查
|
||
|
||
### 1. AI 生成模式提示词
|
||
|
||
**位置**：第 1152-1169 行
|
||
|
||
**当前提示词**：
|
||
```
|
||
你是AI领域GEO专家，目标是提升品牌在大模型自然回答中的提及率。
|
||
|
||
【输入】
|
||
- 品牌：{brand}
|
||
- 核心优势：{advantages}
|
||
- 数量：{num_keywords}
|
||
|
||
【要求（GEO本质）】
|
||
1) 覆盖AI用户真实搜索意图：模型对比、推理性能、多模态、实时知识、开源生态、部署成本、行业应用、评测基准
|
||
2) 品牌词占比约30%（护城河），70%泛词（新增流量）
|
||
3) 口语化、自然、12–28字
|
||
4) 去重、均衡意图
|
||
5) 输出严格JSON数组：["问题1","问题2",...]
|
||
|
||
【开始输出JSON数组】
|
||
```
|
||
|
||
**问题分析**：
|
||
|
||
1. ❌ **硬编码行业示例**
|
||
- 问题：要求中硬编码了"模型对比、推理性能、多模态"等 AI 领域示例
|
||
- 影响：如果用户是其他行业（如外贸ERP），这些示例不适用
|
||
- 建议：根据 `advantages` 动态生成示例，或使用更通用的描述
|
||
|
||
2. ⚠️ **输出格式不够明确**
|
||
- 问题：只说"严格JSON数组"，但未说明如何处理解析失败
|
||
- 影响：代码中已有 fallback（`extract_json_array`），但提示词未说明
|
||
- 建议：明确说明输出格式，并说明如果格式错误会如何处理
|
||
|
||
3. ✅ **其他要求清晰**
|
||
- 品牌词占比、长度、口语化等要求明确
|
||
|
||
**改进建议**：
|
||
```python
|
||
keyword_prompt = PromptTemplate.from_template(
|
||
"""
|
||
你是GEO（Generative Engine Optimization）专家，目标是提升品牌在大模型自然回答中的提及率。
|
||
|
||
【输入】
|
||
- 品牌：{brand}
|
||
- 核心优势：{advantages}
|
||
- 数量：{num_keywords}
|
||
|
||
【GEO核心要求】
|
||
1) 覆盖用户真实搜索意图：
|
||
- 根据品牌和优势，识别用户可能的搜索场景（对比、评测、使用、购买、问题等）
|
||
- 关键词应反映用户真实需求，而非营销术语
|
||
|
||
2) 品牌词占比策略：
|
||
- 约30%包含品牌词（建立护城河，提升品牌提及率）
|
||
- 约70%为泛词（扩大覆盖面，获取新流量）
|
||
- 品牌词应自然融入，避免生硬拼接
|
||
|
||
3) 表达要求：
|
||
- 口语化、自然、符合用户搜索习惯
|
||
- 长度控制在 12-28 字
|
||
- 避免过于正式或营销化
|
||
|
||
4) 多样性要求：
|
||
- 去重：避免生成相同或过于相似的关键词
|
||
- 均衡意图：覆盖不同搜索意图（对比、评测、使用、购买、问题等）
|
||
- 多样化表达：使用不同的表达方式
|
||
|
||
【输出格式】
|
||
请严格按照以下 JSON 数组格式输出，不要添加任何其他内容：
|
||
["关键词1", "关键词2", "关键词3", ...]
|
||
|
||
如果无法生成 JSON 格式，请每行输出一个关键词（纯文本格式）。
|
||
|
||
【开始生成】
|
||
"""
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 语义扩展提示词
|
||
|
||
**位置**：`modules/semantic_expander.py` 第 18-95 行
|
||
|
||
**当前提示词**：✅ 质量较高
|
||
|
||
**优点**：
|
||
- 结构清晰，分层次说明
|
||
- 包含具体示例
|
||
- 输出格式明确（JSON）
|
||
- 扩展策略详细
|
||
|
||
**潜在问题**：
|
||
|
||
1. ⚠️ **扩展数量控制**
|
||
- 问题：提示词中要求扩展 `{expansion_count}` 个，但实际可能生成更多或更少
|
||
- 影响：需要代码层面控制数量
|
||
- 建议：在提示词中明确说明"至少生成 N 个，可以生成更多"
|
||
|
||
2. ✅ **其他方面良好**
|
||
|
||
---
|
||
|
||
### 3. 话题集群提示词
|
||
|
||
**位置**：`modules/topic_cluster.py` 第 20-89 行
|
||
|
||
**当前提示词**：✅ 质量较高
|
||
|
||
**优点**：
|
||
- 聚类要求明确
|
||
- 输出格式详细
|
||
- 包含统计信息要求
|
||
|
||
**潜在问题**：
|
||
|
||
1. ⚠️ **聚类数量控制**
|
||
- 问题：要求生成 `{cluster_count}` 个集群，但实际可能生成不同数量
|
||
- 影响：需要代码层面验证
|
||
- 建议：在提示词中说明"尽量生成 N 个，如果关键词不足以支撑 N 个集群，可以生成更少"
|
||
|
||
---
|
||
|
||
### 4. 关键词挖掘提示词
|
||
|
||
**位置**：`modules/keyword_mining.py` 第 51-89 行
|
||
|
||
**当前提示词**：✅ 质量较高
|
||
|
||
**优点**：
|
||
- 任务说明清晰
|
||
- 输出格式明确
|
||
- 包含示例
|
||
|
||
**潜在问题**：
|
||
|
||
1. ⚠️ **行业通用性**
|
||
- 问题：提示词中使用了 `{industry}` 变量，但示例中硬编码了"软件"
|
||
- 影响：对于非软件行业可能不适用
|
||
- 建议：使用更通用的示例或动态生成
|
||
|
||
---
|
||
|
||
### 5. 混合模式润色提示词
|
||
|
||
**位置**：`modules/keyword_tool.py` 第 159-173 行
|
||
|
||
**当前提示词**：
|
||
```
|
||
你是关键词优化专家。请将以下关键词润色为更自然、更符合用户搜索习惯的表达。
|
||
|
||
{"品牌：" + brand if brand else ""}
|
||
|
||
原始关键词列表：
|
||
{json.dumps(keywords_to_polish, ensure_ascii=False, indent=2)}
|
||
|
||
要求：
|
||
1) 保持原意，但表达更自然、口语化
|
||
2) 长度控制在 12-28 字
|
||
3) 去除生硬拼接感
|
||
4) 输出 JSON 数组格式：["润色后的关键词1", "润色后的关键词2", ...]
|
||
|
||
只输出 JSON 数组，不要其他内容。
|
||
```
|
||
|
||
**问题分析**：
|
||
|
||
1. ⚠️ **品牌信息格式不一致**
|
||
- 问题：使用 `{"品牌：" + brand if brand else ""}` 这种 Python 表达式，但实际在模板中可能无法正确解析
|
||
- 影响：品牌信息可能无法正确传递
|
||
- 建议：使用模板变量 `{brand}` 并在调用时处理
|
||
|
||
2. ✅ **其他要求清晰**
|
||
|
||
**改进建议**：
|
||
```python
|
||
polish_prompt = f"""你是关键词优化专家。请将以下关键词润色为更自然、更符合用户搜索习惯的表达。
|
||
|
||
{f'品牌：{brand}' if brand else ''}
|
||
|
||
原始关键词列表：
|
||
{json.dumps(keywords_to_polish, ensure_ascii=False, indent=2)}
|
||
|
||
要求：
|
||
1) 保持原意，但表达更自然、口语化
|
||
2) 长度控制在 12-28 字
|
||
3) 去除生硬拼接感
|
||
4) 输出 JSON 数组格式：["润色后的关键词1", "润色后的关键词2", ...]
|
||
|
||
只输出 JSON 数组，不要其他内容。
|
||
"""
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理检查
|
||
|
||
### ✅ 已处理的错误
|
||
|
||
1. **AI 生成模式 - JSON 解析失败**
|
||
- **位置**：第 1185-1196 行
|
||
- **处理**：使用 `try-except` 捕获，fallback 到文本解析
|
||
- **状态**：✅ 良好
|
||
|
||
2. **词库导入 - JSON 解析失败**
|
||
- **位置**：第 1066-1074 行
|
||
- **处理**：使用 `try-except` 捕获并显示错误
|
||
- **状态**：✅ 良好
|
||
|
||
3. **数据库保存失败**
|
||
- **位置**：第 1325-1328 行
|
||
- **处理**：使用 `try-except` 捕获，显示警告但不阻止流程
|
||
- **状态**：✅ 良好
|
||
|
||
### ⚠️ 缺失的错误处理
|
||
|
||
1. **词库编辑 - 空词库检查**
|
||
- **位置**：第 1008 行
|
||
- **问题**：如果 `wordbanks.get(bank_type, [])` 返回空列表，text_area 会显示空，但未提示用户
|
||
- **建议**：添加空词库提示
|
||
|
||
2. **语义扩展 - LLM 调用失败**
|
||
- **位置**：第 1458-1496 行
|
||
- **问题**：虽然有 `try-except`，但错误信息不够详细
|
||
- **建议**：区分不同类型的错误（网络错误、API 错误、解析错误等）
|
||
|
||
3. **话题集群 - 可视化失败**
|
||
- **位置**：第 1664-1748 行
|
||
- **问题**：虽然有 `try-except`，但错误信息不够详细
|
||
- **建议**：提供更详细的错误信息
|
||
|
||
4. **智能挖掘 - 空结果处理**
|
||
- **位置**：第 1878-1896 行
|
||
- **问题**：如果 `mined_keywords` 为空，只显示警告，但未说明原因
|
||
- **建议**：提供更详细的失败原因
|
||
|
||
---
|
||
|
||
## 边界条件检查
|
||
|
||
### ✅ 已处理的边界条件
|
||
|
||
1. **空关键词列表**
|
||
- **位置**：第 1414 行
|
||
- **处理**：使用 `if st.session_state.keywords:` 检查
|
||
- **状态**：✅ 良好
|
||
|
||
2. **空词库检查**
|
||
- **位置**：第 1216-1222 行、第 1252-1258 行
|
||
- **处理**：在生成前检查空词库
|
||
- **状态**：✅ 良好
|
||
|
||
3. **空组合模式检查**
|
||
- **位置**：第 1100-1103 行、第 1363-1371 行
|
||
- **处理**：检查 `selected_patterns` 是否为空
|
||
- **状态**：✅ 良好
|
||
|
||
### ⚠️ 未处理的边界条件
|
||
|
||
1. **关键词数量为 0**
|
||
- **位置**：第 1310 行
|
||
- **问题**：如果 `cleaned` 为空列表，会进入错误处理，但未检查 `st.session_state.kw_last_num` 是否为 0
|
||
- **建议**：添加数量为 0 的检查
|
||
|
||
2. **扩展数量超过关键词数量**
|
||
- **位置**：第 1423-1430 行
|
||
- **问题**：如果 `expansion_count` 大于现有关键词数量，可能导致扩展效果不佳
|
||
- **建议**：添加合理性检查
|
||
|
||
3. **话题集群数量大于关键词数量**
|
||
- **位置**：第 1567-1574 行
|
||
- **问题**：如果 `cluster_count` 大于关键词数量，可能导致聚类失败
|
||
- **建议**：添加合理性检查
|
||
|
||
4. **搜索词为空字符串**
|
||
- **位置**：第 1797-1798 行
|
||
- **问题**：如果 `search_term` 为空字符串（非 None），会匹配所有关键词
|
||
- **建议**：添加空字符串检查
|
||
|
||
---
|
||
|
||
## 性能问题检查
|
||
|
||
### ⚠️ 潜在性能问题
|
||
|
||
1. **词库编辑 - 每次渲染都处理**
|
||
- **位置**：第 1002-1018 行
|
||
- **问题**：在循环中每次都处理 `edited_wordbanks`，即使未点击更新
|
||
- **影响**：低（但可以优化）
|
||
- **建议**：只在点击更新时处理
|
||
|
||
2. **话题集群 - 重复创建实例**
|
||
- **位置**：第 1586 行
|
||
- **问题**：每次点击都创建新实例
|
||
- **影响**：低
|
||
- **建议**：考虑缓存实例
|
||
|
||
3. **智能挖掘 - 重复创建实例**
|
||
- **位置**：第 1852 行
|
||
- **问题**：每次展开都创建新实例
|
||
- **影响**：低
|
||
- **建议**：考虑缓存实例
|
||
|
||
4. **语义扩展 - 重复创建实例**
|
||
- **位置**：第 1459 行、第 1529 行
|
||
- **问题**：每次调用都创建新实例
|
||
- **影响**：低
|
||
- **建议**：考虑缓存实例
|
||
|
||
5. **关键词列表 - 分页计算**
|
||
- **位置**：第 1804-1815 行
|
||
- **问题**：每次渲染都计算分页，但可以优化
|
||
- **影响**：极低
|
||
- **建议**：可以接受
|
||
|
||
---
|
||
|
||
## 用户体验问题检查
|
||
|
||
### ✅ 良好的用户体验
|
||
|
||
1. **进度条和状态提示**
|
||
- **位置**：第 1176-1202 行、第 1206-1238 行、第 1242-1293 行
|
||
- **状态**：✅ 良好
|
||
|
||
2. **错误提示详细**
|
||
- **位置**：第 1331-1412 行
|
||
- **状态**：✅ 良好
|
||
|
||
3. **搜索和筛选功能**
|
||
- **位置**：第 1788-1801 行
|
||
- **状态**：✅ 良好
|
||
|
||
### ⚠️ 可改进的用户体验
|
||
|
||
1. **词库编辑 - 缺少保存提示**
|
||
- **位置**：第 1021-1026 行
|
||
- **问题**：点击"更新"后只显示成功提示，但未提示用户需要重新生成关键词
|
||
- **建议**：添加提示"词库已更新，建议重新生成关键词以应用新词库"
|
||
|
||
2. **语义扩展 - 缺少撤销功能**
|
||
- **位置**：第 1476-1492 行
|
||
- **问题**：扩展后直接修改关键词列表，无法撤销
|
||
- **建议**：添加撤销功能或确认对话框
|
||
|
||
3. **话题集群 - 缺少重新生成选项**
|
||
- **位置**：第 1585-1624 行
|
||
- **问题**：如果用户不满意结果，需要手动清空后重新生成
|
||
- **建议**：添加"重新生成"按钮
|
||
|
||
4. **智能挖掘 - 缺少批量添加**
|
||
- **位置**：第 1912-1917 行
|
||
- **问题**：只能逐个添加关键词，效率低
|
||
- **建议**：添加"全选"和"批量添加"功能
|
||
|
||
---
|
||
|
||
## 修复建议清单
|
||
|
||
### 🔴 P0 - 必须修复（逻辑错误/严重问题）
|
||
|
||
1. **AI 生成提示词 - 硬编码行业示例**
|
||
- **位置**：第 1162 行
|
||
- **修复**：移除硬编码示例，使用通用描述或动态生成
|
||
- **优先级**：高
|
||
|
||
2. **混合模式润色提示词 - 品牌信息格式**
|
||
- **位置**：`modules/keyword_tool.py` 第 161 行
|
||
- **修复**：使用正确的模板变量格式
|
||
- **优先级**：高
|
||
|
||
3. **搜索词空字符串检查**
|
||
- **位置**：第 1797-1798 行
|
||
- **修复**：添加空字符串检查
|
||
- **优先级**：中
|
||
|
||
### 🟡 P1 - 建议修复（体验优化）
|
||
|
||
4. **词库编辑 - 状态同步优化**
|
||
- **位置**：第 1000-1026 行
|
||
- **修复**：优化更新逻辑，避免状态不一致
|
||
- **优先级**：中
|
||
|
||
5. **语义扩展 - 保存原始关键词**
|
||
- **位置**：第 1458-1496 行
|
||
- **修复**：在扩展前保存原始关键词列表
|
||
- **优先级**：中
|
||
|
||
6. **错误处理 - 更详细的错误信息**
|
||
- **位置**：多处
|
||
- **修复**：区分不同类型的错误，提供更详细的错误信息
|
||
- **优先级**：中
|
||
|
||
7. **边界条件 - 数量合理性检查**
|
||
- **位置**：第 1423-1430 行、第 1567-1574 行
|
||
- **修复**：添加扩展数量和集群数量的合理性检查
|
||
- **优先级**：低
|
||
|
||
### 🟢 P2 - 可选优化（性能/体验）
|
||
|
||
8. **实例缓存优化**
|
||
- **位置**：第 1459 行、第 1529 行、第 1586 行、第 1852 行
|
||
- **修复**：考虑缓存实例，避免重复创建
|
||
- **优先级**：低
|
||
|
||
9. **用户体验优化**
|
||
- **位置**：多处
|
||
- **修复**：添加撤销功能、批量操作、重新生成选项等
|
||
- **优先级**：低
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
### 整体评价
|
||
|
||
**代码质量**：⭐⭐⭐⭐☆（4/5）
|
||
- 逻辑清晰，结构合理
|
||
- 错误处理基本完善
|
||
- 用户体验良好
|
||
|
||
**提示词质量**：⭐⭐⭐⭐☆（4/5）
|
||
- 大部分提示词质量较高
|
||
- 部分提示词需要优化（硬编码、格式问题）
|
||
|
||
**需要优先修复的问题**：
|
||
1. AI 生成提示词的硬编码行业示例
|
||
2. 混合模式润色提示词的品牌信息格式
|
||
3. 搜索词空字符串检查
|
||
|
||
**建议优化方向**：
|
||
1. 提升错误处理的详细程度
|
||
2. 添加更多边界条件检查
|
||
3. 优化用户体验（撤销、批量操作等）
|
||
|
||
---
|
||
|
||
**报告版本**：v1.0
|
||
**最后更新**：2026-01-28
|
||
**下一步**：根据优先级修复 P0 和 P1 问题
|