Pine/ChouJuGEO
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: 重构项目结构并添加平台同步基础架构

Browse Source 
- 重构项目目录结构，将功能模块移至 modules/ 目录
- 创建平台同步基础架构，包括发布器基类和 GitHub 发布器
- 新增 UI 状态管理模块 (modules/ui/state.py) 统一管理会话状态
- 更新依赖配置，添加平台同步所需依赖 (httpx, pyperclip)
- 整理文档结构，将所有文档分类移至 docs/ 目录
- 添加 .cursorrules 文件定义项目开发规范
- 清理根目录重复文件，保持项目结构整洁
This commit is contained in:
刘国栋
2026-01-30 10:21:29 +08:00
parent 77d5ec70f8
commit 8f7f082c3d
102 changed files with 33742 additions and 1526 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guides/ADVANCED_OPTIMIZATION_PLAN.md
+188
View File
@@ -0,0 +1,188 @@
# 深度目录结构优化方案
## 📊 当前问题分析
### 根目录文件统计
**Python 文件（根目录）**：约30+个
- 主程序：1个（`geo_tool.py` - 必须保留）
- 重复模块文件：18个（已在 `modules/` 中，应删除根目录版本）
- 工具脚本：5个（可移动到 `scripts/` 目录）
- 配置文件：1个（`requirements.txt` - 必须保留）
**问题**：
1. ❌ 根目录有大量重复的模块文件（既在根目录又在 `modules/`）
2. ❌ 工具脚本混在根目录
3. ❌ 根目录文件过多，不够整洁
## 🎯 优化目标
### 理想根目录结构
```
geo_tool/
├── README.md # 项目主文档
├── DOCS.md # 文档索引
├── requirements.txt # 依赖文件
├── .gitignore # Git配置
├── .streamlit/ # Streamlit配置
│ └── config.toml
├── geo_tool.py # 主程序（唯一入口）
│
├── modules/ # 功能模块
│ └── [所有模块文件]
│
├── platform_sync/ # 平台同步模块
│ └── [平台同步文件]
│
├── scripts/ # 工具脚本（新增）
│ ├── cleanup_duplicate_docs.py
│ ├── move_reorganization_docs.py
│ ├── reorganize_files.py
│ ├── update_imports.py
│ └── update_doc_references.py
│
└── docs/ # 文档目录
├── features/
├── analysis/
├── guides/
└── implementation/
```
## 📋 优化步骤
### 步骤1：清理重复模块文件
**需要删除的根目录文件**（18个，已在 `modules/` 中）：
- `config_optimizer.py`
- `content_metrics.py`
- `content_scorer.py`
- `data_storage.py`
- `eeat_enhancer.py`
- `fact_density_enhancer.py`
- `keyword_mining.py`
- `keyword_tool.py`
- `multimodal_prompt.py`
- `negative_monitor.py`
- `optimization_techniques.py`
- `resource_recommender.py`
- `roi_analyzer.py`
- `schema_generator.py`
- `semantic_expander.py`
- `storage_example.py`
- `technical_config_generator.py`
- `topic_cluster.py`
- `workflow_automation.py`
**影响评估**：
- ⚠️ **中等影响**：需要更新 `geo_tool.py` 中的导入路径
- ✅ **安全**：`modules/` 中已有完整版本
### 步骤2：移动工具脚本
**需要移动到 `scripts/` 的文件**（5个）：
- `scripts/cleanup_duplicate_docs.py`
- `scripts/move_reorganization_docs.py`
- `scripts/reorganize_files.py`
- `scripts/update_imports.py`
- `scripts/update_doc_references.py`
**影响评估**：
- ✅ **低影响**：这些是工具脚本，不参与主程序运行
- ✅ **安全**：只是位置移动，不影响功能
### 步骤3：更新导入路径
**需要更新的文件**：
1. `geo_tool.py` - 更新所有模块导入（从 `from xxx import` 改为 `from modules.xxx import`）
2. `modules/storage_example.py` - 更新 `data_storage` 导入
**影响评估**：
- ⚠️ **关键影响**：必须正确更新，否则程序无法运行
- ✅ **自动化**：可以使用 `scripts/update_imports.py` 脚本自动更新
## 🔧 实施计划
### 阶段1：准备（低风险）
1. ✅ 创建 `scripts/` 目录
2. ✅ 创建清理脚本
3. ✅ 备份关键文件
### 阶段2：移动工具脚本（低风险）
1. 移动工具脚本到 `scripts/`
2. 更新脚本中的路径引用（如果需要）
3. 验证脚本仍可正常运行
### 阶段3：清理重复文件（中等风险）
1. 确认 `modules/` 中所有文件完整
2. 更新 `geo_tool.py` 的导入路径
3. 删除根目录的重复文件
4. 测试程序运行
### 阶段4：验证（必须）
1. 运行 `python -c "from modules.data_storage import DataStorage"`
2. 运行 `streamlit run geo_tool.py`
3. 测试所有功能模块
## ⚠️ 风险评估
### 改动影响
| 操作 | 影响程度 | 风险等级 | 回滚难度 |
|------|---------|---------|---------|
| 移动工具脚本 | 低 | 低 | 容易 |
| 删除重复模块文件 | 中 | 中 | 中等 |
| 更新导入路径 | 高 | 中 | 容易（有脚本） |
### 风险缓解措施
1. **Git 提交**：每步完成后立即提交，便于回滚
2. **自动化脚本**：使用脚本自动更新，减少人为错误
3. **分步执行**：分阶段执行，每步验证后再继续
4. **备份**：关键文件备份
## 📝 执行命令
### 快速执行（推荐）
```powershell
# 1. 创建 scripts 目录
New-Item -ItemType Directory -Force -Path scripts
# 2. 移动工具脚本
Move-Item cleanup_duplicate_docs.py scripts\ -Force
Move-Item move_reorganization_docs.py scripts\ -Force
Move-Item reorganize_files.py scripts\ -Force
Move-Item update_imports.py scripts\ -Force
Move-Item update_doc_references.py scripts\ -Force
# 3. 更新导入路径（在移动脚本后）
python scripts/update_imports.py
# 4. 删除重复模块文件（在更新导入后）
# 使用 cleanup_duplicate_modules.py 脚本
```
## ✅ 优化后的优势
1. **根目录极简**：只保留必要的入口文件
2. **结构清晰**：功能模块、工具脚本、文档分类明确
3. **易于维护**：新功能添加时，只需在对应目录操作
4. **符合最佳实践**：遵循Python项目标准结构
## 🎯 最终根目录文件（约5个）
```
geo_tool/
├── README.md # 项目主文档
├── DOCS.md # 文档索引
├── requirements.txt # 依赖文件
├── geo_tool.py # 主程序
└── .gitignore # Git配置
```
**对比**：从 30+ 个文件减少到 5 个核心文件！
docs/guides/DECISION_GUIDE.md
+293
View File
@@ -0,0 +1,293 @@
# 平台文章同步功能决策指南
> 基于项目现状、GEO目标、实现成本和用户价值的综合决策分析
## 🎯 核心问题
**是否要实现20个平台的文章同步功能？如何实现？**
---
## 📊 决策矩阵分析
### 方案对比
| 方案 | 实现成本 | 用户价值 | GEO效果 | 技术风险 | 推荐度 |
|------|---------|---------|---------|---------|--------|
| **方案A：完整实现（20平台）** | 10周 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
| **方案B：MVP版本（5平台）** | 3-4周 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |
| **方案C：仅新增平台内容生成** | 1-2周 | ⭐⭐⭐ | ⭐⭐⭐ | ⭐ | ⭐⭐⭐⭐ |
| **方案D：暂不实现** | 0 | ⭐ | ⭐ | ⭐ | ⭐⭐ |
---
## 💡 推荐方案：分阶段实施（方案B → 方案A）
### 为什么推荐分阶段？
1. **降低风险**：先验证可行性，再全面铺开
2. **快速验证**：3-4周看到效果，验证用户需求
3. **灵活调整**：根据用户反馈调整方向
4. **资源优化**：避免一次性投入过大
---
## 🚀 阶段一：MVP版本（强烈推荐先做）⭐⭐⭐⭐⭐
### 目标
**3-4周实现5个核心平台的发布功能**
### 选择平台
1. ✅ **GitHub**（1-2天）- 最简单，验证架构
2. ✅ **微信公众号**（3-4天）- 用户价值最高
3. ✅ **B站**（3-4天）- 用户量大，API完善
4. ✅ **知乎**（3-4天）- 用户量大，API相对完善
5. ✅ **CSDN**（3-4天）- 技术平台，API支持
### 为什么选择这5个？
- ✅ **API支持好**：都有完善的API文档
- ✅ **用户价值高**：覆盖主要内容平台
- ✅ **技术风险低**：实现难度中等
- ✅ **验证价值大**：能验证整体架构
### 同时完成
- ✅ **新增8个平台的内容生成**（1-2周）
- 只需创建Prompt模板
- 工作量小，价值高
- 满足运营需求
### 产出
- 5个平台自动发布功能
- 8个新增平台内容生成
- 验证架构可行性
- 用户反馈收集
---
## 📈 阶段二：根据反馈决定是否扩展
### 决策点1：MVP版本用户反馈如何？
**如果反馈好** → 继续阶段二
- 实现剩余3个API平台（百家号、企鹅号、网易号）
- 实现一键复制功能（12个平台）
- 添加批量发布功能
**如果反馈一般** → 暂停扩展
- 优化现有5个平台
- 专注于其他GEO功能
### 决策点2：运营需求是否紧急？
**如果紧急** → 快速实现一键复制
- 12个平台一键复制功能（1-2周）
- 满足"覆盖20个平台"的需求
- 虽然不能自动发布，但能大幅提升效率
**如果不紧急** → 按计划实施
- 先完善API平台
- 再实现一键复制
---
## ⚖️ 关键决策因素
### 1. 对GEO效果的直接影响
**文章同步功能的价值**：
- ✅ **扩大内容投放**：更多平台 = 更多曝光
- ✅ **提升发布效率**：自动化减少人工成本
- ⚠️ **间接影响**：内容已经生成，同步只是效率提升
**对比其他功能**：
- JSON-LD Schema：直接提升实体识别 ⭐⭐⭐⭐⭐
- 语义扩展：从"点"到"面"占领 ⭐⭐⭐⭐
- 文章同步：提升发布效率 ⭐⭐⭐
### 2. 实现成本
| 方案 | 工作量 | 开发周期 | 维护成本 |
|------|--------|---------|---------|
| MVP（5平台） | 15-20天 | 3-4周 | 低 |
| 完整版（20平台） | 60-82天 | 10周 | 中-高 |
| 仅内容生成（8平台） | 5-7天 | 1-2周 | 低 |
### 3. 用户价值
**高价值场景**：
- 需要多平台发布的内容团队
- 需要批量发布的运营团队
- 需要追踪发布状态的管理者
**中等价值场景**：
- 偶尔发布内容的个人用户
- 只关注1-2个平台的用户
### 4. 技术风险
**低风险**：
- GitHub、微信公众号、B站、知乎、CSDN（API完善）
- 一键复制功能（技术简单）
**中风险**：
- 百家号、企鹅号、网易号（API状态需确认）
- OAuth2.0认证流程（复杂度中等）
**高风险**：
- 平台API变更
- 账号被封禁风险
---
## 🎯 最终推荐决策
### 推荐方案：**分阶段实施**
#### 第一步：立即开始（1-2周）
1. ✅ **实现GitHub发布功能**（1-2天）
- 验证架构可行性
- 风险最低
- 快速看到效果
2. ✅ **新增8个平台的内容生成**（5-7天）
- 满足运营需求
- 工作量小
- 价值高
#### 第二步：MVP版本（3-4周）
3. ✅ **实现5个核心平台发布**（15-20天）
- GitHub、微信公众号、B站、知乎、CSDN
- 验证用户需求
- 收集反馈
#### 第三步：根据反馈决定（可选）
4. ⚠️ **如果反馈好** → 继续扩展
- 剩余3个API平台
- 一键复制功能
- 批量发布
5. ⚠️ **如果反馈一般** → 暂停扩展
- 优化现有功能
- 专注其他GEO功能
---
## 📋 决策检查清单
### 开始前需要确认
- [ ] **运营需求是否紧急？**
- 紧急 → 优先实现一键复制（快速满足需求）
- 不紧急 → 按MVP方案实施
- [ ] **是否有开发资源？**
- 有1-2个开发者 → 可以开始
- 资源紧张 → 先做新增平台内容生成
- [ ] **用户是否真的需要？**
- 有明确需求 → 开始实施
- 需求不明确 → 先做MVP验证
- [ ] **是否有平台账号？**
- 有企业认证账号 → 可以接入API平台
- 只有个人账号 → 优先一键复制平台
### 实施中需要监控
- [ ] **技术可行性验证**
- GitHub发布是否成功？
- 架构是否合理？
- [ ] **用户反馈收集**
- 用户是否使用？
- 是否有问题？
- [ ] **成本控制**
- 开发时间是否超预期？
- 是否需要调整计划？
---
## 💰 成本效益分析
### MVP版本（5平台）
**成本**：
- 开发时间：3-4周
- 维护成本：低（每月1-2天）
**收益**：
- 5个主要平台自动发布
- 8个新增平台内容生成
- 验证架构可行性
- 收集用户反馈
**ROI**：⭐⭐⭐⭐（高）
### 完整版本（20平台）
**成本**：
- 开发时间：10周
- 维护成本：中-高（每月3-4天）
**收益**：
- 20个平台全覆盖
- 批量发布功能
- 完整的发布管理系统
**ROI**：⭐⭐⭐（中-高，取决于用户需求）
---
## 🎯 最终建议
### 强烈推荐：**先做MVP版本**
**理由**：
1. ✅ **快速验证**：3-4周看到效果
2. ✅ **降低风险**：避免一次性投入过大
3. ✅ **灵活调整**：根据反馈决定是否扩展
4. ✅ **满足需求**：5个核心平台 + 8个新增平台内容生成
### 实施路径
**第1-2周**：
- GitHub发布功能（验证架构）
- 新增8个平台内容生成（满足运营需求）
**第3-4周**：
- 微信公众号、B站、知乎、CSDN发布功能
- 测试和优化
**第5周**：
- 收集用户反馈
- 决定是否继续扩展
---
## ⚠️ 风险提示
1. **API状态不确定**：企鹅号、网易号API需确认
2. **企业认证要求**：百家号等需要企业认证
3. **开发周期**：完整版10周，需要合理安排资源
4. **用户需求**：需要验证用户是否真的需要
---
## 📝 决策记录
**推荐决策**：✅ **先做MVP版本（5平台 + 8个新增平台内容生成）**
**实施时间**：3-4周
**下一步行动**：
1. 实现GitHub发布功能（1-2天）
2. 新增8个平台内容生成（5-7天）
3. 实现剩余4个API平台发布（15-20天）
4. 收集用户反馈
5. 决定是否继续扩展
---
**决策日期**：2025-01-26
**决策依据**：项目现状分析 + 成本效益分析 + 风险评估
docs/guides/DOCUMENTATION_CLEANUP_GUIDE.md
+124
View File
@@ -0,0 +1,124 @@
# 文档清理指南
## 📋 根目录文档保留策略
### ✅ 必须保留在根目录的文档
1. **README.md** - 项目主文档（GitHub/GitLab 标准要求）
2. **DOCS.md** - 文档索引（方便快速查找所有文档）
### 📌 重组相关文档（建议移动到 docs/guides/）
以下重组相关的文档建议移动到 `docs/guides/` 目录：
- `PROJECT_STRUCTURE_ANALYSIS.md` - 项目结构分析
- `QUICK_REORGANIZE.md` - 快速重组指南
- `REORGANIZATION_SUMMARY.md` - 重组总结
- `DOCUMENTATION_CLEANUP_GUIDE.md` - 文档清理指南
**建议**：这些文档可以移动到 `docs/guides/` 目录，保持根目录整洁。使用 `scripts/move_reorganization_docs.py` 脚本可以自动移动。
### ❌ 需要删除的文档（已在 docs/ 目录下）
所有以下文档在根目录的重复版本都应该删除，因为已经在 `docs/` 目录下分类存放：
#### 功能文档（15个）
- `*_FEATURE.md` 文件（已在 `docs/features/`）
#### 分析报告（7个）
- `*_ANALYSIS.md` 和 `*_REPORT.md` 文件（已在 `docs/analysis/`）
#### 指南文档（5个）
- `*_GUIDE.md` 文件（已在 `docs/guides/`）
#### 实现文档（7个）
- 实现相关文档（已在 `docs/implementation/`）
## 🚀 执行清理
### 方法1：使用自动清理脚本（推荐）
```powershell
python scripts/cleanup_duplicate_docs.py
```
这个脚本会：
- 自动检查根目录中的重复文档
- 确认 `docs/` 目录下存在对应文件
- 安全删除根目录的重复版本
- 保留必要的文档（README.md, DOCS.md 等）
### 方法2：手动清理
如果脚本执行失败（文件被占用），可以：
1. **关闭所有打开的文件**（IDE、编辑器等）
2. **手动删除**根目录中的重复文档文件
3. **验证** `docs/` 目录下存在对应文件
## 📁 清理后的根目录结构
```
geo_tool/
├── README.md # ✅ 保留
├── DOCS.md # ✅ 保留（文档索引）
│
├── geo_tool.py # 主程序
├── requirements.txt # 依赖文件
├── .gitignore # Git配置
│
├── modules/ # 功能模块
├── platform_sync/ # 平台同步
└── docs/ # 所有文档（分类存放）
├── features/
├── analysis/
├── guides/ # 包含重组相关文档
└── implementation/
```
## ✅ 清理验证清单
清理完成后，请验证：
- [ ] `README.md` 仍在根目录
- [ ] `DOCS.md` 已在根目录创建
- [ ] 根目录不再有 `*_FEATURE.md` 文件
- [ ] 根目录不再有 `*_ANALYSIS.md` 文件
- [ ] 根目录不再有 `*_GUIDE.md` 文件（除了可选保留的）
- [ ] 所有文档在 `docs/` 目录下可以找到
- [ ] `DOCS.md` 中的链接都能正常访问
## 💡 最佳实践
1. **README.md** 应该简洁，包含：
- 项目简介
- 快速开始
- 主要功能概览
- 链接到 DOCS.md 获取详细文档
2. **DOCS.md** 作为文档索引，提供：
- 所有文档的分类导航
- 快速查找功能
- 清晰的文档结构说明
3. **详细文档** 放在 `docs/` 目录下分类管理，保持根目录整洁
## 🆘 遇到问题？
### 问题1：文件被占用无法删除
**解决方案**：
1. 关闭所有IDE和编辑器
2. 检查是否有Python进程在运行
3. 如果仍有问题，重启计算机后再试
### 问题2：误删了重要文档
**解决方案**：
1. 检查 `docs/` 目录下是否有对应文件
2. 如果有，说明只是删除了重复版本
3. 如果没有，可以从Git历史恢复
### 问题3：文档链接失效
**解决方案**：
1. 运行 `python scripts/update_doc_references.py` 更新文档引用
2. 检查 `DOCS.md` 中的链接是否正确
3. 使用相对路径而不是绝对路径
docs/guides/FINAL_OPTIMIZATION_GUIDE.md
+203
View File
@@ -0,0 +1,203 @@
# 最终目录结构优化指南
## ✅ 当前状态检查
### 已完成的优化
- ✅ `geo_tool.py` 已更新导入路径（使用 `modules.xxx`）
- ✅ `modules/storage_example.py` 已更新导入路径
- ✅ 文档已分类移动到 `docs/` 目录
- ✅ 重组相关文档已移动到 `docs/guides/`
### 待优化的部分
- ⏳ 根目录仍有18个重复的模块文件（已在 `modules/` 中）
- ⏳ 根目录有5个工具脚本（可移动到 `scripts/`）
## 🎯 优化目标
### 优化前（根目录约30+个文件）
```
geo_tool/
├── README.md
├── DOCS.md
├── geo_tool.py
├── requirements.txt
├── [18个重复模块文件] ❌
├── [5个工具脚本] ❌
└── ...
```
### 优化后（根目录约5个文件）
```
geo_tool/
├── README.md # ✅ 保留
├── DOCS.md # ✅ 保留
├── geo_tool.py # ✅ 保留（主程序）
├── requirements.txt # ✅ 保留
├── .gitignore # ✅ 保留
│
├── modules/ # ✅ 功能模块
├── platform_sync/ # ✅ 平台同步
├── scripts/ # ✅ 工具脚本（新增）
└── docs/ # ✅ 文档目录
```
## 📋 优化步骤（安全执行）
### 步骤1：移动工具脚本（低风险，先执行）
**操作**：将工具脚本移动到 `scripts/` 目录
**执行**：
```powershell
python move_scripts.py
```
**影响**：
- ✅ 低风险：工具脚本不参与主程序运行
- ✅ 可回滚：如有问题可轻松恢复
**验证**：
```powershell
# 测试脚本是否仍可运行
python scripts/update_imports.py --help
```
### 步骤2：清理重复模块文件（中等风险，需谨慎）
**前提条件**：
- ✅ 已确认 `geo_tool.py` 使用 `modules.xxx` 导入
- ✅ 已测试程序可以正常运行
**执行**：
```powershell
python cleanup_duplicate_modules.py
```
**影响**：
- ⚠️ 中等风险：删除后无法直接恢复（需从Git恢复）
- ✅ 安全：`modules/` 中已有完整版本
**验证**：
```powershell
# 1. 测试导入
python -c "from modules.data_storage import DataStorage; print('✓ 导入成功')"
# 2. 测试主程序
streamlit run geo_tool.py
```
## 🔍 详细文件清单
### 需要删除的重复模块文件（18个）
这些文件在根目录和 `modules/` 目录都存在，删除根目录版本：
1. `config_optimizer.py`
2. `content_metrics.py`
3. `content_scorer.py`
4. `data_storage.py`
5. `eeat_enhancer.py`
6. `fact_density_enhancer.py`
7. `keyword_mining.py`
8. `keyword_tool.py`
9. `multimodal_prompt.py`
10. `negative_monitor.py`
11. `optimization_techniques.py`
12. `resource_recommender.py`
13. `roi_analyzer.py`
14. `schema_generator.py`
15. `semantic_expander.py`
16. `storage_example.py`
17. `technical_config_generator.py`
18. `topic_cluster.py`
19. `workflow_automation.py`
### 需要移动的工具脚本（5个）
这些脚本移动到 `scripts/` 目录：
1. `scripts/cleanup_duplicate_docs.py`
2. `scripts/move_reorganization_docs.py`
3. `scripts/reorganize_files.py`
4. `scripts/update_imports.py`
5. `scripts/update_doc_references.py`
## ⚠️ 风险评估与缓解
### 风险1：删除重复文件后程序无法运行
**概率**：低（已确认导入路径已更新）
**缓解措施**：
1. 先测试：`python -c "from modules.data_storage import DataStorage"`
2. 再删除：确认测试通过后再执行删除
3. Git备份：删除前先提交，便于回滚
### 风险2：工具脚本移动后无法使用
**概率**：极低（只是位置移动）
**缓解措施**：
1. 更新使用方式：`python scripts/script_name.py`
2. 测试脚本：移动后立即测试
### 风险3：遗漏某些导入路径
**概率**：低（已检查 `geo_tool.py`）
**缓解措施**：
1. 全局搜索：`grep -r "from data_storage import" .`
2. 运行测试：完整测试所有功能
## 📝 完整执行清单
### 准备阶段
- [ ] 确认 Git 仓库状态（建议先提交当前更改）
- [ ] 备份关键文件（可选，Git已提供版本控制）
- [ ] 阅读本指南
### 执行阶段
- [ ] 步骤1：运行 `python move_scripts.py`
- [ ] 验证：测试脚本是否仍可运行
- [ ] 步骤2：运行 `python cleanup_duplicate_modules.py`
- [ ] 验证：测试导入 `python -c "from modules.data_storage import DataStorage"`
- [ ] 验证：运行主程序 `streamlit run geo_tool.py`
### 验证阶段
- [ ] 检查根目录文件数量（应该只有5个左右）
- [ ] 测试所有主要功能模块
- [ ] 确认没有导入错误
- [ ] Git 提交优化结果
## 🎉 优化后的优势
1. **根目录极简**：从30+个文件减少到5个核心文件
2. **结构清晰**：功能模块、工具脚本、文档分类明确
3. **易于维护**：新功能添加时，只需在对应目录操作
4. **符合最佳实践**：遵循Python项目标准结构
5. **便于协作**：团队成员更容易理解项目结构
## 📚 相关文档
- `ADVANCED_OPTIMIZATION_PLAN.md` - 详细优化方案
- `cleanup_duplicate_modules.py` - 清理重复模块脚本
- `move_scripts.py` - 移动工具脚本脚本
## 🆘 遇到问题？
### 问题1：删除文件后程序无法运行
**解决方案**：
1. 从Git恢复：`git checkout HEAD -- filename.py`
2. 检查导入路径：确认使用 `modules.xxx` 格式
3. 重新测试：`python -c "from modules.data_storage import DataStorage"`
### 问题2：工具脚本无法运行
**解决方案**：
1. 使用完整路径：`python scripts/script_name.py`
2. 或在 `scripts/` 目录下运行：`cd scripts && python script_name.py`
### 问题3：遗漏某些文件
**解决方案**：
1. 检查 `modules/` 目录：确认所有模块文件都在
2. 检查导入错误：运行程序查看具体错误信息
3. 从Git恢复：`git checkout HEAD -- .`
docs/guides/LAYOUT_UPGRADE_GUIDE.md
+282
View File
@@ -0,0 +1,282 @@
# 布局升级复杂度评估与实施指南
## 📊 复杂度评估总结
**总体复杂度：⭐⭐⭐☆☆（中等）**
### 为什么是中等复杂度？
✅ **有利因素**：
- 你已经有了基础的 CSS 样式系统
- 已经使用了 `st.tabs` 作为主导航
- 已经部分使用了 `st.container(border=True)` 卡片式设计
- 侧边栏已经有 form 结构
- 代码结构相对清晰
⚠️ **需要注意**：
- 文件较大（5864行），需要系统化改动
- 有 37 个 `st.expander` 需要评估是否改为 tabs/container
- 需要保持功能逻辑不变，只改布局
---
## 🎯 推荐方案：方案2 + 方案4 混合
### 核心改动点
1. **CSS 增强**（30分钟）
- 增强卡片样式
- 优化侧边栏视觉层次
- 统一间距和阴影
2. **Expander → Container/Tabs 转换**（2-3小时）
- 将功能相关的多个 expander 合并为 tabs
- 将单个 expander 改为 container(border=True)
- 保持次要信息用 expander
3. **侧边栏优化**（30分钟）
- 添加分组容器
- 优化视觉层次
---
## 📋 详细实施步骤
### 阶段 1：CSS 增强（低风险，30分钟）
**改动范围**：只修改 CSS 部分（第 36-170 行）
**具体改动**：
```css
/* 1. 增强卡片样式 */
div[data-testid="stVerticalBlockBorderWrapper"] {
border-radius: var(--radius);
box-shadow: var(--shadow);
padding: 1.5rem !important; /* 新增：内边距 */
background: #FFFFFF !important; /* 新增：白色背景 */
margin-bottom: 1rem !important; /* 新增：卡片间距 */
}
/* 2. 优化侧边栏分组 */
section[data-testid="stSidebar"] .stForm {
background: #FFFFFF;
border-radius: 8px;
padding: 1rem;
margin-bottom: 1rem;
border: 1px solid var(--border);
}
/* 3. Expander 样式优化（保留但美化） */
.streamlit-expanderHeader {
font-weight: 500;
color: var(--text);
}
.streamlit-expanderContent {
padding-top: 0.75rem;
}
/* 4. 增强分隔线 */
hr {
border: none;
border-top: 1px solid var(--border);
margin: 1.5rem 0;
}
```
**风险**：极低，只改样式，不影响功能
---
### 阶段 2：Expander 重构（中等风险，2-3小时）
#### 2.1 识别需要改动的 Expander
**改为 Tabs 的情况**（功能相关的多个选项）：
- ✅ Tab1 中的"组合模式选择" + "词库管理" → 可以合并为一个 tabs
- ✅ Tab1 中的"智能关键词挖掘"已经有 tabs（保持）
- ✅ Tab3 中的多个分析 expander → 可以合并为 tabs
**改为 Container 的情况**（主要功能区域）：
- ✅ Tab1 中的"组合模式选择"区域 → 已经是 container，保持
- ✅ Tab2 中的主要输入区域 → 确保用 container
- ✅ Tab3 中的优化结果展示 → 用 container
**保留 Expander 的情况**（次要/详细信息）：
- ✅ "查看技巧说明" → 保持 expander
- ✅ "详细评分与改进建议" → 保持 expander
- ✅ "预览最后一篇" → 保持 expander
#### 2.2 具体改动示例
**示例 1：Tab1 中的词库管理区域**
**当前代码**（第 797 行）：
```python
with st.expander("词库管理", expanded=False):
# 词库编辑和导入导出
```
**改为**：
```python
with st.container(border=True):
st.markdown("### 📚 词库管理")
wordbank_tab1, wordbank_tab2 = st.tabs(["编辑词库", "导入/导出"])
with wordbank_tab1:
# 词库编辑代码
with wordbank_tab2:
# 导入导出代码
```
**示例 2：Tab3 中的分析结果**
**当前代码**（多个 expander）：
```python
with st.expander("📈 事实密度分析", expanded=False):
# 分析内容
with st.expander("🏗️ 结构化块分析", expanded=False):
# 分析内容
```
**改为**：
```python
analysis_tabs = st.tabs(["📈 事实密度", "🏗️ 结构化块", "📝 强化详情"])
with analysis_tabs[0]:
with st.container(border=True):
# 事实密度分析内容
with analysis_tabs[1]:
with st.container(border=True):
# 结构化块分析内容
```
---
### 阶段 3：侧边栏优化（低风险，30分钟）
**当前结构**（第 563-697 行）：
```python
with st.sidebar:
st.header("全局配置")
with st.form("global_config_form"):
# 所有配置项
```
**优化后**：
```python
with st.sidebar:
st.header("⚙️ 全局配置")
# 分组 1：LLM 配置
with st.container(border=True):
st.markdown("#### 🤖 LLM 配置")
with st.form("llm_config_form"):
# LLM 相关配置
# 分组 2：品牌信息
with st.container(border=True):
st.markdown("#### 🏢 品牌信息")
with st.form("brand_config_form"):
# 品牌相关配置
# 分组 3：其他设置
with st.container(border=True):
st.markdown("#### ⚙️ 其他设置")
# 其他配置
```
---
## ⏱️ 时间估算
| 阶段 | 任务 | 时间 | 风险 |
|------|------|------|------|
| 阶段 1 | CSS 增强 | 30分钟 | ⭐ 极低 |
| 阶段 2 | Expander 重构 | 2-3小时 | ⭐⭐ 中等 |
| 阶段 3 | 侧边栏优化 | 30分钟 | ⭐ 极低 |
| **总计** | | **3-4小时** | |
---
## 🎨 改动前后对比
### 改动前
- 大量 expander 折叠，需要点击展开
- 视觉层次不够清晰
- 卡片样式不统一
### 改动后
- 主要功能用 tabs，一目了然
- 次要信息用 expander，保持简洁
- 卡片样式统一，视觉更现代
- 侧边栏分组清晰
---
## ⚠️ 注意事项
1. **逐步实施**：先改 CSS，测试没问题再改布局
2. **保持功能**：只改布局，不改逻辑
3. **测试每个 Tab**：改完一个 tab 就测试一次
4. **保留 Expander**：不是所有 expander 都要改，次要信息保持 expander 更合适
---
## 🚀 快速开始
### 最小改动方案（1小时）
如果时间紧张，可以先做这些：
1. **只增强 CSS**（30分钟）
- 添加卡片内边距和背景
- 优化侧边栏样式
2. **改 3-5 个关键 Expander**（30分钟）
- Tab1 的词库管理
- Tab3 的分析结果区域
- 其他明显需要改的
这样就能看到明显改善，后续再逐步完善。
---
## 📝 检查清单
实施完成后检查：
- [ ] 所有主要功能区域都用 container(border=True) 或 tabs
- [ ] 次要信息保持用 expander
- [ ] 侧边栏有清晰的分组
- [ ] 卡片样式统一（圆角、阴影、内边距）
- [ ] 所有功能正常工作
- [ ] 响应式布局正常（不同屏幕尺寸）
---
## 💡 建议
**推荐实施顺序**：
1. ✅ 先做阶段 1（CSS），立即看到效果
2. ✅ 再做阶段 3（侧边栏），改动小风险低
3. ✅ 最后做阶段 2（Expander），需要仔细测试
**如果遇到问题**：
- 先回退到上一个稳定版本
- 逐个 tab 测试，不要一次性改完
- 保留原代码注释，方便对比
---
## 🎯 预期效果
实施完成后，你的工具将：
- ✨ 视觉更现代，更像产品级应用
- 🎯 功能组织更清晰，减少滚动疲劳
- 📱 用户体验更好，操作更直观
- 🎨 保持专业感，同时更美观
**复杂度总结**：中等，但可以分阶段实施，风险可控！
docs/guides/MANUAL_CLEANUP_GUIDE.md
+185
View File
@@ -0,0 +1,185 @@
# 手动清理指南
## ⚠️ 当前状态
由于文件被占用（可能被IDE或其他程序打开），自动脚本无法执行删除/移动操作。
## 📋 需要手动完成的操作
### 步骤1：关闭所有打开的文件
**重要**：在执行清理前，请：
1. 关闭所有IDE和编辑器
2. 关闭可能占用文件的程序
3. 确保没有Python进程在运行
### 步骤2：清理重复模块文件（19个）
这些文件在根目录和 `modules/` 目录都存在，**删除根目录版本**：
**需要删除的文件**：
1. `config_optimizer.py`
2. `content_metrics.py`
3. `content_scorer.py`
4. `data_storage.py`
5. `eeat_enhancer.py`
6. `fact_density_enhancer.py`
7. `keyword_mining.py`
8. `keyword_tool.py`
9. `multimodal_prompt.py`
10. `negative_monitor.py`
11. `optimization_techniques.py`
12. `resource_recommender.py`
13. `roi_analyzer.py`
14. `schema_generator.py`
15. `semantic_expander.py`
16. `storage_example.py`
17. `technical_config_generator.py`
18. `topic_cluster.py`
19. `workflow_automation.py`
**验证**：删除前确认 `modules/` 目录中有对应文件
### 步骤3：整理优化相关文件（可选）
**移动到 `docs/guides/` 的文档**：
- `ADVANCED_OPTIMIZATION_PLAN.md`
- `FINAL_OPTIMIZATION_GUIDE.md`
- `REFERENCE_UPDATE_SUMMARY.md`
- `OPTIMIZATION_STATUS.md`
**移动到 `scripts/` 的脚本**：
- `cleanup_duplicate_modules.py`
- `move_scripts.py`
- `update_script_references.py`
- `cleanup_optimization_files.py`
## 🚀 快速执行（PowerShell）
### 方法1：使用脚本（推荐）
关闭所有文件后，运行：
```powershell
# 清理重复模块
python cleanup_duplicate_modules.py
# 输入 yes
# 整理优化文件
python cleanup_optimization_files.py
```
### 方法2：手动删除/移动
```powershell
# 删除重复模块文件
$modules = @(
"config_optimizer.py", "content_metrics.py", "content_scorer.py",
"data_storage.py", "eeat_enhancer.py", "fact_density_enhancer.py",
"keyword_mining.py", "keyword_tool.py", "multimodal_prompt.py",
"negative_monitor.py", "optimization_techniques.py", "resource_recommender.py",
"roi_analyzer.py", "schema_generator.py", "semantic_expander.py",
"storage_example.py", "technical_config_generator.py", "topic_cluster.py",
"workflow_automation.py"
)
foreach ($file in $modules) {
if (Test-Path $file) {
Remove-Item $file -Force
Write-Host "✓ 已删除: $file"
}
}
# 移动优化文档
$docs = @(
"ADVANCED_OPTIMIZATION_PLAN.md",
"FINAL_OPTIMIZATION_GUIDE.md",
"REFERENCE_UPDATE_SUMMARY.md",
"OPTIMIZATION_STATUS.md"
)
foreach ($doc in $docs) {
if (Test-Path $doc) {
Move-Item $doc -Destination "docs\guides\" -Force
Write-Host "✓ 已移动: $doc"
}
}
# 移动优化脚本
$scripts = @(
"cleanup_duplicate_modules.py",
"move_scripts.py",
"update_script_references.py",
"cleanup_optimization_files.py"
)
foreach ($script in $scripts) {
if (Test-Path $script) {
Move-Item $script -Destination "scripts\" -Force
Write-Host "✓ 已移动: $script"
}
}
```
## ✅ 验证清单
清理完成后，请验证：
- [ ] 根目录只有5个核心文件：
- README.md
- DOCS.md
- geo_tool.py
- requirements.txt
- .gitignore
- [ ] 所有模块文件在 `modules/` 目录中
- [ ] 所有工具脚本在 `scripts/` 目录中
- [ ] 所有文档在 `docs/` 子目录中
- [ ] 测试导入：`python -c "from modules.data_storage import DataStorage"`
- [ ] 测试主程序：`streamlit run geo_tool.py`
## 🎯 优化后的最终结构
```
geo_tool/
├── README.md # ✅ 项目主文档
├── DOCS.md # ✅ 文档索引
├── geo_tool.py # ✅ 主程序
├── requirements.txt # ✅ 依赖文件
├── .gitignore # ✅ Git配置
│
├── modules/ # ✅ 功能模块（19个文件）
├── platform_sync/ # ✅ 平台同步模块
├── scripts/ # ✅ 工具脚本（9个文件）
└── docs/ # ✅ 文档目录
├── features/ # 功能文档（15个）
├── analysis/ # 分析报告（7个）
├── guides/ # 指南文档（13个）
└── implementation/ # 实现文档（7个）
```
## 📊 优化效果
- **根目录文件**：从 50+ 个减少到 5 个（减少 90%）
- **文档分类**：34个文档按类型分类存放
- **模块组织**：19个模块集中在 `modules/` 目录
- **脚本整理**：9个工具脚本集中在 `scripts/` 目录
## 🆘 遇到问题？
### 问题1：文件仍被占用
**解决方案**：
1. 检查是否有Python进程：`tasklist | findstr python`
2. 关闭所有IDE和编辑器
3. 重启计算机后再试
### 问题2：删除后程序无法运行
**解决方案**：
1. 从Git恢复：`git checkout HEAD -- filename.py`
2. 检查 `modules/` 目录：确认文件存在
3. 检查导入路径：确认使用 `modules.xxx` 格式
### 问题3：不确定是否安全删除
**解决方案**：
1. 先备份：`git add . && git commit -m "备份：清理前"`
2. 再删除：如有问题可回滚
3. 验证：删除后立即测试程序
docs/guides/OPTIMIZATION_STATUS.md
+157
View File
@@ -0,0 +1,157 @@
# 目录结构优化状态报告
## ✅ 已完成的优化
### 1. 文档分类 ✅
- ✅ 所有功能文档已移动到 `docs/features/`（15个）
- ✅ 所有分析报告已移动到 `docs/analysis/`（7个）
- ✅ 所有指南文档已移动到 `docs/guides/`（9个）
- ✅ 所有实现文档已移动到 `docs/implementation/`（7个）
- ✅ 重组相关文档已移动到 `docs/guides/`
### 2. 工具脚本整理 ✅
- ✅ 所有工具脚本已移动到 `scripts/` 目录（5个）
- `cleanup_duplicate_docs.py`
- `move_reorganization_docs.py`
- `reorganize_files.py`
- `update_imports.py`
- `update_doc_references.py`
### 3. 引用路径更新 ✅
- ✅ `geo_tool.py` 导入路径已更新为 `modules.xxx`
- ✅ `storage_example.py` 导入路径已更新
- ✅ 所有文档中的脚本引用已更新为 `scripts/` 前缀
- ✅ 所有文档中的模块路径引用已更新
## ⏳ 待完成的优化
### 1. 清理重复模块文件（19个）
**状态**：文件被占用，无法自动删除
**需要删除的根目录文件**（已在 `modules/` 中）：
1. `config_optimizer.py`
2. `content_metrics.py`
3. `content_scorer.py`
4. `data_storage.py`
5. `eeat_enhancer.py`
6. `fact_density_enhancer.py`
7. `keyword_mining.py`
8. `keyword_tool.py`
9. `multimodal_prompt.py`
10. `negative_monitor.py`
11. `optimization_techniques.py`
12. `resource_recommender.py`
13. `roi_analyzer.py`
14. `schema_generator.py`
15. `semantic_expander.py`
16. `storage_example.py`
17. `technical_config_generator.py`
18. `topic_cluster.py`
19. `workflow_automation.py`
**解决方案**：
1. 关闭所有IDE和编辑器
2. 关闭可能占用文件的程序
3. 重新运行：`python cleanup_duplicate_modules.py`
4. 或手动删除这些文件
### 2. 整理优化相关文档和脚本
**根目录的优化相关文件**（可移动到 `docs/guides/` 或 `scripts/`）：
- `ADVANCED_OPTIMIZATION_PLAN.md` → `docs/guides/`
- `FINAL_OPTIMIZATION_GUIDE.md` → `docs/guides/`
- `REFERENCE_UPDATE_SUMMARY.md` → `docs/guides/`
- `OPTIMIZATION_STATUS.md` → `docs/guides/`（本文件）
- `cleanup_duplicate_modules.py` → `scripts/`
- `move_scripts.py` → `scripts/`
- `update_script_references.py` → `scripts/`
## 📊 当前根目录文件统计
**当前根目录文件**（约30个）：
- 核心文件：5个（README.md, DOCS.md, geo_tool.py, requirements.txt, .gitignore）
- 重复模块文件：19个（待删除）
- 优化相关文档：4个（可移动）
- 优化相关脚本：3个（可移动）
**优化后根目录文件**（约5个）：
- README.md
- DOCS.md
- geo_tool.py
- requirements.txt
- .gitignore
## 🎯 下一步操作
### 步骤1：关闭所有打开的文件
**重要**：关闭所有IDE、编辑器和其他可能占用文件的程序
### 步骤2：清理重复模块文件
**方法A：使用脚本（推荐）**
```powershell
python cleanup_duplicate_modules.py
# 输入 yes 确认
```
**方法B：手动删除**
- 确认 `modules/` 目录中有对应文件
- 手动删除根目录的重复文件
### 步骤3：整理优化相关文件（可选）
**移动优化文档到 `docs/guides/`**：
```powershell
Move-Item ADVANCED_OPTIMIZATION_PLAN.md docs\guides\ -Force
Move-Item FINAL_OPTIMIZATION_GUIDE.md docs\guides\ -Force
Move-Item REFERENCE_UPDATE_SUMMARY.md docs\guides\ -Force
Move-Item OPTIMIZATION_STATUS.md docs\guides\ -Force
```
**移动优化脚本到 `scripts/`**：
```powershell
Move-Item cleanup_duplicate_modules.py scripts\ -Force
Move-Item move_scripts.py scripts\ -Force
Move-Item update_script_references.py scripts\ -Force
```
### 步骤4：验证
```powershell
# 测试导入
python -c "from modules.data_storage import DataStorage; print('✓ 导入成功')"
# 测试主程序
streamlit run geo_tool.py
```
## 📈 优化进度
- [x] 文档分类整理（100%）
- [x] 工具脚本整理（100%）
- [x] 引用路径更新（100%）
- [ ] 清理重复模块文件（0% - 文件被占用）
- [ ] 整理优化相关文件（0% - 可选）
## 🎉 优化效果
### 优化前
- 根目录：50+ 个文件混在一起
- 文档：34个文档文件在根目录
- 模块：18个模块文件在根目录
- 脚本：5个工具脚本在根目录
### 优化后（完成所有步骤后）
- 根目录：5个核心文件
- 文档：分类存放在 `docs/` 子目录
- 模块：集中在 `modules/` 目录
- 脚本：集中在 `scripts/` 目录
**文件减少率**：从 50+ 个减少到 5 个（减少 90%）
## 📚 相关文档
- `docs/guides/FINAL_OPTIMIZATION_GUIDE.md` - 完整优化指南
- `docs/guides/ADVANCED_OPTIMIZATION_PLAN.md` - 详细优化方案
- `docs/guides/REFERENCE_UPDATE_SUMMARY.md` - 引用路径更新总结
docs/guides/PLATFORM_SETUP.md
+94
View File
@@ -0,0 +1,94 @@
# 平台扩展安装说明
## 已支持的平台
### 基础平台（已包含依赖）
- DeepSeek
- OpenAI (GPT)
- Tongyi (通义千问)
- Groq
- Moonshot (Kimi)
### 新增平台（需要额外安装）
#### 1. 豆包（字节跳动）
**安装命令：**
```bash
pip install 'volcengine-python-sdk[ark]'
```
**API Key 格式：**
```
access_key:secret_key:endpoint_id
```
用冒号分隔三个值：
- `access_key`: 火山引擎 Access Key
- `secret_key`: 火山引擎 Secret Key
- `endpoint_id`: 接入点名称（Endpoint ID）
**获取方式：**
1. 访问 [火山引擎官网](https://www.volcengine.com/)
2. 注册账号并完成实名认证
3. 在控制台获取 Access Key 和 Secret Key
4. 创建模型接入点，获取 Endpoint ID
**使用示例：**
在侧边栏"生成&优化 LLM"或"验证用LLM"中选择"豆包（字节跳动）"，输入格式化的 API Key。
---
#### 2. 文心一言（百度）
**安装命令：**
```bash
pip install qianfan
```
**API Key 格式：**
```
app_key:app_secret
```
用冒号分隔两个值：
- `app_key`: 百度智能云 App Key
- `app_secret`: 百度智能云 App Secret
**获取方式：**
1. 访问 [百度智能云千帆平台](https://cloud.baidu.com/product/qianfan.html)
2. 注册账号并完成认证
3. 创建应用，获取 App Key 和 App Secret
**使用示例：**
在侧边栏"生成&优化 LLM"或"验证用LLM"中选择"文心一言（百度）"，输入格式化的 API Key。
---
## 快速安装所有平台
如果需要使用所有平台，可以运行：
```bash
pip install 'volcengine-python-sdk[ark]' qianfan
```
---
## 注意事项
1. **API Key 格式**：豆包和文心一言的 API Key 需要使用冒号分隔多个值
2. **依赖冲突**：某些包可能有版本冲突，如遇到问题请单独安装
3. **可选安装**：这些平台是可选的，如果不使用可以不安装，不影响其他功能
---
## 故障排除
### 豆包安装失败
- 确保 Python 版本 >= 3.7
- Windows 系统可能需要启用长路径支持
- 尝试：`pip install 'volcengine-python-sdk[ark]' -U`
### 文心一言初始化失败
- 确保已安装 `qianfan` 包
- 检查 API Key 格式是否正确（app_key:app_secret）
- 确认环境变量或参数中的 AK/SK 是否正确
docs/guides/PROJECT_STRUCTURE_ANALYSIS.md
+231
View File
@@ -0,0 +1,231 @@
# 项目目录结构分析报告
## 📊 当前项目结构分析
### 文件统计
**Python 文件（.py）**：24个
- 主程序：1个（geo_tool.py）
- 功能模块：18个
- 平台同步模块：3个（在platform_sync/目录）
- 示例/工具：2个
**文档文件（.md）**：34个
- 功能文档（*_FEATURE.md）：15个
- 分析报告（*_ANALYSIS.md, *_REPORT.md）：7个
- 指南文档（*_GUIDE.md）：5个
- 实现文档：7个
**配置文件**：3个
- requirements.txt
- .gitignore
- .streamlit/config.toml
### 目录结构
```
geo_tool/
├── 根目录文件（50+个文件混在一起）
│ ├── Python模块文件（18个）
│ ├── 文档文件（34个）
│ ├── 配置文件（3个）
│ └── 主程序（1个）
│
└── platform_sync/（已有子目录）
├── __init__.py
├── base_publisher.py
├── github_publisher.py
└── copy_manager.py
```
## 🔍 文件引用关系分析
### Python 文件导入关系
**geo_tool.py** 导入的模块（18个）：
```python
from data_storage import DataStorage
from keyword_tool import KeywordTool
from content_scorer import ContentScorer
from eeat_enhancer import EEATEnhancer
from semantic_expander import SemanticExpander
from fact_density_enhancer import FactDensityEnhancer
from schema_generator import SchemaGenerator
from topic_cluster import TopicCluster
from multimodal_prompt import MultimodalPromptGenerator
from roi_analyzer import ROIAnalyzer
from workflow_automation import WorkflowManager, WorkflowStep
from keyword_mining import KeywordMining
from optimization_techniques import OptimizationTechniqueManager
from content_metrics import ContentMetricsAnalyzer
from technical_config_generator import TechnicalConfigGenerator
from negative_monitor import NegativeMonitor
from resource_recommender import ResourceRecommender
```
**platform_sync** 模块：
- 使用相对导入，已有包结构
### 文档引用关系
**README.md** 引用的文档：
- `INTEGRATION_NOTES.md`
- `STORAGE_GUIDE.md`
- `PLATFORM_SETUP.md`
- `IMPLEMENTATION_SUMMARY.md`
- `PLATFORM_SYNC_IMPLEMENTATION.md`
- 15个 `*_FEATURE.md` 文件
**功能文档** 之间的引用：
- 各功能文档相互引用
- 引用实现模块（.py文件）
- 引用其他分析文档
## 🎯 优化建议
### 1. 目录结构优化
**建议结构**：
```
geo_tool/
├── README.md
├── requirements.txt
├── .gitignore
├── .streamlit/
├── geo_tool.py
├── modules/ # 新增：功能模块目录
│ ├── __init__.py
│ └── [18个模块文件]
├── platform_sync/ # 已有
└── docs/ # 新增：文档目录
├── features/ # 功能文档
├── analysis/ # 分析报告
├── guides/ # 指南文档
└── implementation/ # 实现文档
```
### 2. 导入路径更新
**需要更新的导入**：
- `geo_tool.py`：所有模块导入添加 `modules.` 前缀
- `storage_example.py`：更新 `data_storage` 导入
### 3. 文档路径更新
**需要更新的文档引用**：
- 所有 `.md` 文件中的文档路径引用
- README.md 中的文档链接
## 📋 实施计划
### 阶段1：准备（已完成）
- ✅ 创建优化方案文档
- ✅ 创建目录结构
- ✅ 创建更新脚本
### 阶段2：文件移动（待执行）
1. 关闭所有打开的文件（IDE、编辑器等）
2. 运行文件移动脚本或手动移动
3. 验证文件移动成功
### 阶段3：路径更新（待执行）
1. 运行 `scripts/update_imports.py` 更新Python导入
2. 运行 `scripts/update_doc_references.py` 更新文档引用
3. 手动检查关键文件
### 阶段4：验证（待执行）
1. 运行 `python geo_tool.py` 测试导入
2. 检查文档链接是否正常
3. 验证所有功能是否正常
## 📝 详细文件清单
### 需要移动到 modules/ 的文件（18个）
1. `data_storage.py`
2. `keyword_tool.py`
3. `content_scorer.py`
4. `eeat_enhancer.py`
5. `semantic_expander.py`
6. `fact_density_enhancer.py`
7. `schema_generator.py`
8. `topic_cluster.py`
9. `multimodal_prompt.py`
10. `roi_analyzer.py`
11. `workflow_automation.py`
12. `keyword_mining.py`
13. `optimization_techniques.py`
14. `content_metrics.py`
15. `technical_config_generator.py`
16. `negative_monitor.py`
17. `resource_recommender.py`
18. `config_optimizer.py`
19. `storage_example.py`（可选）
### 需要移动到 docs/features/ 的文件（15个）
1. `CONFIG_OPTIMIZER_FEATURE.md`
2. `CONTENT_METRICS_FEATURE.md`
3. `CONTENT_SCORER_FEATURE.md`
4. `EEAT_FEATURE.md`
5. `FACT_DENSITY_FEATURE.md`
6. `JSON_LD_SCHEMA_FEATURE.md`
7. `KEYWORD_MINING_FEATURE.md`
8. `MULTIMODAL_FEATURE.md`
9. `NEGATIVE_MONITOR_FEATURE.md`
10. `OPTIMIZATION_TECHNIQUES_FEATURE.md`
11. `RESOURCE_RECOMMENDER_FEATURE.md`
12. `ROI_ANALYSIS_FEATURE.md`
13. `SEMANTIC_EXPANSION_FEATURE.md`
14. `TECHNICAL_CONFIG_FEATURE.md`
15. `TOPIC_CLUSTER_FEATURE.md`
16. `WORKFLOW_AUTOMATION_FEATURE.md`
### 需要移动到 docs/analysis/ 的文件（7个）
1. `ANALYSIS_ACCURACY_REPORT.md`
2. `CODE_DOCUMENTATION_ANALYSIS.md`
3. `DOCUMENTATION_REVERSE_VERIFICATION.md`
4. `FEATURE_ANALYSIS.md`
5. `FEATURE_PRIORITY_ANALYSIS.md`
6. `FUNCTION_VERIFICATION_REPORT.md`
7. `GEO_COMPLIANCE_ANALYSIS.md`
### 需要移动到 docs/guides/ 的文件（5个）
1. `QUICK_START_GUIDE.md`
2. `STORAGE_GUIDE.md`
3. `PLATFORM_SETUP.md`
4. `LAYOUT_UPGRADE_GUIDE.md`
5. `DECISION_GUIDE.md`
### 需要移动到 docs/implementation/ 的文件（7个）
1. `IMPLEMENTATION_SUMMARY.md`
2. `PLATFORM_SYNC_ANALYSIS.md`
3. `PLATFORM_SYNC_IMPLEMENTATION.md`
4. `PLATFORM_SYNC_TEST.md`
5. `INTEGRATION_NOTES.md`
6. `FEATURES_COMPLETE_LIST.md`
7. `ADVANCED_FEATURES.md`
## ✅ 优化后的优势
1. **清晰的目录结构**：文件按功能分类，易于查找和管理
2. **模块化组织**：功能模块集中管理，便于维护和扩展
3. **文档分类清晰**：功能文档、分析报告、指南文档分开管理
4. **符合最佳实践**：遵循Python项目标准目录结构
5. **便于协作**：团队成员更容易理解项目结构
## 🚨 注意事项
1. **文件占用**：移动文件前，确保所有文件未被IDE或其他程序打开
2. **路径更新**：移动文件后，必须运行更新脚本更新所有引用路径
3. **测试验证**：完成移动和更新后，务必测试程序是否正常运行
4. **Git提交**：建议分步骤提交，便于回滚和追踪变更
## 📚 相关文档
- `docs/DIRECTORY_STRUCTURE_OPTIMIZATION.md` - 详细的优化方案和实施步骤
- `scripts/update_imports.py` - 自动更新Python导入路径的脚本
- `scripts/update_doc_references.py` - 自动更新文档路径引用的脚本
docs/guides/QUICK_REORGANIZE.md
+139
View File
@@ -0,0 +1,139 @@
# 快速重组项目目录结构
## ⚡ 快速执行步骤
### 步骤1：关闭所有打开的文件
**重要**：在移动文件之前，请关闭所有在IDE或编辑器中打开的文件，否则会出现"文件被占用"的错误。
### 步骤2：执行文件移动
#### 方法A：使用PowerShell脚本（推荐）
在项目根目录打开PowerShell，执行：
```powershell
# 移动功能模块
$modules = @(
"data_storage.py", "keyword_tool.py", "content_scorer.py", "eeat_enhancer.py",
"semantic_expander.py", "fact_density_enhancer.py", "schema_generator.py",
"topic_cluster.py", "multimodal_prompt.py", "roi_analyzer.py",
"workflow_automation.py", "keyword_mining.py", "optimization_techniques.py",
"content_metrics.py", "technical_config_generator.py", "negative_monitor.py",
"resource_recommender.py", "config_optimizer.py", "storage_example.py"
)
foreach ($file in $modules) {
if (Test-Path $file) {
Move-Item $file -Destination "modules\" -Force -ErrorAction SilentlyContinue
Write-Host "✓ $file"
}
}
# 移动功能文档
Get-ChildItem -Filter "*_FEATURE.md" | ForEach-Object {
Move-Item $_.FullName -Destination "docs\features\" -Force -ErrorAction SilentlyContinue
Write-Host "✓ $($_.Name)"
}
# 移动分析报告
$analysis = @(
"ANALYSIS_ACCURACY_REPORT.md", "CODE_DOCUMENTATION_ANALYSIS.md",
"DOCUMENTATION_REVERSE_VERIFICATION.md", "FEATURE_ANALYSIS.md",
"FEATURE_PRIORITY_ANALYSIS.md", "FUNCTION_VERIFICATION_REPORT.md",
"GEO_COMPLIANCE_ANALYSIS.md"
)
foreach ($file in $analysis) {
if (Test-Path $file) {
Move-Item $file -Destination "docs\analysis\" -Force -ErrorAction SilentlyContinue
Write-Host "✓ $file"
}
}
# 移动指南文档
$guides = @(
"QUICK_START_GUIDE.md", "STORAGE_GUIDE.md", "PLATFORM_SETUP.md",
"LAYOUT_UPGRADE_GUIDE.md", "DECISION_GUIDE.md"
)
foreach ($file in $guides) {
if (Test-Path $file) {
Move-Item $file -Destination "docs\guides\" -Force -ErrorAction SilentlyContinue
Write-Host "✓ $file"
}
}
# 移动实现文档
$implementation = @(
"IMPLEMENTATION_SUMMARY.md", "PLATFORM_SYNC_ANALYSIS.md",
"PLATFORM_SYNC_IMPLEMENTATION.md", "PLATFORM_SYNC_TEST.md",
"INTEGRATION_NOTES.md", "FEATURES_COMPLETE_LIST.md", "ADVANCED_FEATURES.md"
)
foreach ($file in $implementation) {
if (Test-Path $file) {
Move-Item $file -Destination "docs\implementation\" -Force -ErrorAction SilentlyContinue
Write-Host "✓ $file"
}
}
Write-Host "`n✅ 文件移动完成！"
```
#### 方法B：手动移动（如果脚本失败）
如果PowerShell脚本因为文件被占用而失败，请：
1. 关闭所有IDE和编辑器
2. 手动将文件拖拽到对应目录
3. 参考 `PROJECT_STRUCTURE_ANALYSIS.md` 中的文件清单
### 步骤3：更新导入路径
```powershell
python scripts/update_imports.py
```
### 步骤4：更新文档引用
```powershell
python scripts/update_doc_references.py
```
### 步骤5：验证
```powershell
# 测试导入是否正常
python -c "from modules.data_storage import DataStorage; print('✓ 导入成功')"
```
## 📋 完整执行清单
- [ ] 关闭所有打开的文件（IDE、编辑器等）
- [ ] 执行文件移动（PowerShell脚本或手动）
- [ ] 运行 `python scripts/update_imports.py`
- [ ] 运行 `python scripts/update_doc_references.py`
- [ ] 测试导入：`python -c "from modules.data_storage import DataStorage"`
- [ ] 运行主程序：`streamlit run geo_tool.py`
- [ ] 检查文档链接是否正常
## 🆘 遇到问题？
### 问题1：文件被占用
**解决方案**：
1. 关闭所有IDE和编辑器
2. 检查是否有Python进程在运行：`tasklist | findstr python`
3. 如果仍有问题，重启计算机后再试
### 问题2：导入错误
**解决方案**：
1. 确认文件已移动到 `modules/` 目录
2. 确认 `modules/__init__.py` 存在
3. 检查 `geo_tool.py` 中的导入路径是否正确
### 问题3：文档链接失效
**解决方案**：
1. 运行 `python scripts/update_doc_references.py`
2. 手动检查 `README.md` 中的链接
3. 使用相对路径而不是绝对路径
## 📚 相关文档
- `PROJECT_STRUCTURE_ANALYSIS.md` - 详细的项目结构分析
- `docs/DIRECTORY_STRUCTURE_OPTIMIZATION.md` - 完整的优化方案
docs/guides/QUICK_START_GUIDE.md
+355
View File
@@ -0,0 +1,355 @@
# 快速开始指南：实现GitHub发布功能
> 这是最简单的实现示例，可以作为其他平台的基础模板
## 🎯 目标
实现GitHub平台的文章自动发布功能，验证整体架构可行性。
## 📦 步骤1：安装依赖
```bash
pip install httpx pyperclip
```
## 📝 步骤2：扩展数据库
在 `modules/data_storage.py` 的 `_init_sqlite` 方法中添加：
```python
# 平台账号表
cursor.execute("""
CREATE TABLE IF NOT EXISTS platform_accounts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
platform TEXT NOT NULL,
account_type TEXT NOT NULL,
account_name TEXT,
api_key TEXT,
config_json TEXT,
is_active INTEGER DEFAULT 1,
brand TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
""")
# 发布记录表
cursor.execute("""
CREATE TABLE IF NOT EXISTS publish_records (
id INTEGER PRIMARY KEY AUTOINCREMENT,
article_id INTEGER,
platform TEXT NOT NULL,
publish_method TEXT NOT NULL,
publish_status TEXT NOT NULL,
publish_url TEXT,
publish_id TEXT,
error_message TEXT,
published_at TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
""")
```
## 💻 步骤3：创建GitHub发布器
创建文件 `platform_sync/github_publisher.py`：
```python
"""
GitHub发布器 - 最简单的实现示例
"""
import base64
import httpx
from typing import Dict, Any, Optional
class GitHubPublisher:
"""GitHub发布器"""
def __init__(self, api_key: str, repo_owner: str, repo_name: str):
self.api_key = api_key
self.repo_owner = repo_owner
self.repo_name = repo_name
self.base_url = "https://api.github.com"
self.headers = {
"Authorization": f"token {api_key}",
"Accept": "application/vnd.github.v3+json"
}
def publish(self, content: str, title: str, file_path: Optional[str] = None) -> Dict[str, Any]:
"""
发布内容到GitHub
Args:
content: Markdown内容
title: 文章标题
file_path: 文件路径（可选）
Returns:
{
'success': bool,
'publish_url': str,
'publish_id': str,
'error': str
}
"""
try:
# 生成文件路径
if not file_path:
safe_title = title.replace(' ', '_').replace('/', '_')
file_path = f"content/{safe_title}.md"
# 编码内容
content_bytes = content.encode('utf-8')
content_base64 = base64.b64encode(content_bytes).decode('utf-8')
# API URL
url = f"{self.base_url}/repos/{self.repo_owner}/{self.repo_name}/contents/{file_path}"
# 检查文件是否存在
response = httpx.get(url, headers=self.headers)
sha = None
if response.status_code == 200:
sha = response.json().get('sha')
# 准备数据
data = {
"message": f"Publish: {title}",
"content": content_base64,
"branch": "main"
}
if sha:
data["sha"] = sha
# 创建或更新文件
response = httpx.put(url, json=data, headers=self.headers)
if response.status_code in [200, 201]:
result = response.json()
html_url = result.get('content', {}).get('html_url', '')
return {
'success': True,
'publish_url': html_url,
'publish_id': result.get('content', {}).get('sha', ''),
'error': None
}
else:
return {
'success': False,
'publish_url': '',
'publish_id': '',
'error': f"GitHub API错误: {response.text}"
}
except Exception as e:
return {
'success': False,
'publish_url': '',
'publish_id': '',
'error': str(e)
}
def validate_account(self) -> bool:
"""验证GitHub账号"""
try:
response = httpx.get(f"{self.base_url}/user", headers=self.headers)
return response.status_code == 200
except:
return False
```
## 🔧 步骤4：扩展DataStorage
在 `modules/data_storage.py` 的 `DataStorage` 类中添加：
```python
def save_platform_account(self, platform: str, account_config: Dict[str, Any], brand: str):
"""保存平台账号"""
if self.storage_type == "sqlite":
conn = sqlite3.connect(self.db_path)
cursor = conn.cursor()
cursor.execute("""
INSERT OR REPLACE INTO platform_accounts
(platform, account_type, account_name, api_key, config_json, brand, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?)
""", (
platform,
account_config.get('account_type', 'api'),
account_config.get('account_name', ''),
account_config.get('api_key', ''),
json.dumps(account_config.get('config', {}), ensure_ascii=False),
brand,
datetime.now().isoformat()
))
conn.commit()
conn.close()
def get_platform_account(self, platform: str, brand: str) -> Optional[Dict[str, Any]]:
"""获取平台账号"""
if self.storage_type == "sqlite":
conn = sqlite3.connect(self.db_path)
cursor = conn.cursor()
cursor.execute("""
SELECT * FROM platform_accounts
WHERE platform = ? AND brand = ? AND is_active = 1
""", (platform, brand))
row = cursor.fetchone()
conn.close()
if row:
return {
'api_key': row[4],
'config': json.loads(row[5] or '{}')
}
return None
def save_publish_record(self, article_id: int, platform: str, publish_method: str,
publish_status: str, publish_url: str = '', publish_id: str = '',
error_message: str = ''):
"""保存发布记录"""
if self.storage_type == "sqlite":
conn = sqlite3.connect(self.db_path)
cursor = conn.cursor()
cursor.execute("""
INSERT INTO publish_records
(article_id, platform, publish_method, publish_status, publish_url,
publish_id, error_message, published_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
""", (
article_id, platform, publish_method, publish_status,
publish_url, publish_id, error_message, datetime.now().isoformat()
))
conn.commit()
conn.close()
```
## 🎨 步骤5：添加UI（在geo_tool.py中）
在 `modules/geo_tool.py` 中添加新的Tab或功能：
```python
# 在Tab定义中添加
tabs = st.tabs([
"1 关键词蒸馏",
"2 内容生成",
"3 内容优化",
"4 AI验证",
"5 历史记录",
"6 平台同步" # 新增
])
with tabs[5]: # 平台同步Tab
st.header("📤 平台文章同步")
# GitHub账号配置
with st.expander("🔐 GitHub账号配置", expanded=True):
github_api_key = st.text_input("GitHub Personal Access Token", type="password")
github_repo_owner = st.text_input("仓库所有者（用户名）")
github_repo_name = st.text_input("仓库名称")
if st.button("保存GitHub配置"):
if github_api_key and github_repo_owner and github_repo_name:
storage.save_platform_account(
platform="GitHub",
account_config={
'account_type': 'api',
'api_key': github_api_key,
'config': {
'repo_owner': github_repo_owner,
'repo_name': github_repo_name
}
},
brand=brand
)
st.success("GitHub配置已保存！")
else:
st.error("请填写完整信息")
# 发布功能
st.subheader("📝 发布到GitHub")
# 选择文章
articles = storage.get_articles(brand=brand)
if articles:
article_options = {f"{a['keyword']} - {a['platform']}": a['id'] for a in articles}
selected_article_key = st.selectbox("选择要发布的文章", list(article_options.keys()))
selected_article_id = article_options[selected_article_key]
if st.button("🚀 发布到GitHub", type="primary"):
# 获取账号配置
account_config = storage.get_platform_account("GitHub", brand)
if not account_config:
st.error("请先配置GitHub账号")
else:
# 获取文章
article = next((a for a in articles if a['id'] == selected_article_id), None)
if article:
# 创建发布器
from platform_sync.github_publisher import GitHubPublisher
publisher = GitHubPublisher(
api_key=account_config['api_key'],
repo_owner=account_config['config']['repo_owner'],
repo_name=account_config['config']['repo_name']
)
# 发布
with st.spinner("正在发布到GitHub..."):
result = publisher.publish(
content=article['content'],
title=article['keyword']
)
# 保存发布记录
storage.save_publish_record(
article_id=selected_article_id,
platform="GitHub",
publish_method="api",
publish_status="success" if result['success'] else "failed",
publish_url=result.get('publish_url', ''),
publish_id=result.get('publish_id', ''),
error_message=result.get('error', '')
)
# 显示结果
if result['success']:
st.success(f"✅ 发布成功！")
st.markdown(f"**发布链接**: {result['publish_url']}")
else:
st.error(f"❌ 发布失败: {result.get('error', '未知错误')}")
else:
st.info("请先生成文章")
# 发布记录
st.subheader("📊 发布记录")
# 这里可以显示发布历史记录
```
## ✅ 步骤6：测试
1. **获取GitHub Token**：
- 访问 https://github.com/settings/tokens
- 创建新的 Personal Access Token
- 选择 `repo` 权限
2. **运行测试**：
```bash
streamlit run geo_tool.py
```
3. **测试流程**：
- 配置GitHub账号
- 生成一篇文章
- 发布到GitHub
- 检查GitHub仓库是否成功创建文件
## 🎉 完成！
如果GitHub发布功能正常工作，说明架构是正确的。接下来可以：
1. 按照相同模式实现其他7个API平台
2. 实现一键复制功能
3. 添加批量发布功能
## 📚 参考
- [GitHub API文档](https://docs.github.com/en/rest)
- [完整实现指南](./PLATFORM_SYNC_IMPLEMENTATION.md)
docs/guides/REFERENCE_UPDATE_SUMMARY.md
+122
View File
@@ -0,0 +1,122 @@
# 引用路径更新总结
## ✅ 已完成的更新
### 1. 工具脚本引用更新
**更新的文档**（6个）：
- ✅ `FINAL_OPTIMIZATION_GUIDE.md`
- ✅ `ADVANCED_OPTIMIZATION_PLAN.md`
- ✅ `docs/guides/DOCUMENTATION_CLEANUP_GUIDE.md`
- ✅ `docs/guides/PROJECT_STRUCTURE_ANALYSIS.md`
- ✅ `docs/guides/QUICK_REORGANIZE.md`
- ✅ `docs/guides/REORGANIZATION_SUMMARY.md`
**更新内容**：
- `python update_imports.py` → `python scripts/update_imports.py`
- `python cleanup_duplicate_docs.py` → `python scripts/cleanup_duplicate_docs.py`
- `update_imports.py` → `scripts/update_imports.py`
- 等等...
### 2. 模块导入路径更新
**已更新的文件**：
- ✅ `geo_tool.py` - 所有导入已更新为 `from modules.xxx import`
- ✅ `modules/storage_example.py` - 导入已更新为 `from modules.data_storage import`
- ✅ `storage_example.py` (根目录) - 导入已更新为 `from modules.data_storage import`
## 📋 引用路径对照表
### 工具脚本路径
| 旧路径 | 新路径 |
|--------|--------|
| `python update_imports.py` | `python scripts/update_imports.py` |
| `python update_doc_references.py` | `python scripts/update_doc_references.py` |
| `python cleanup_duplicate_docs.py` | `python scripts/cleanup_duplicate_docs.py` |
| `python move_reorganization_docs.py` | `python scripts/move_reorganization_docs.py` |
| `python reorganize_files.py` | `python scripts/reorganize_files.py` |
### 模块导入路径
| 旧导入 | 新导入 |
|--------|--------|
| `from data_storage import DataStorage` | `from modules.data_storage import DataStorage` |
| `from keyword_tool import KeywordTool` | `from modules.keyword_tool import KeywordTool` |
| `from content_scorer import ContentScorer` | `from modules.content_scorer import ContentScorer` |
| ... | ... (所有模块都已更新) |
## ✅ 验证清单
### Python 导入验证
- [x] `geo_tool.py` - 所有导入使用 `modules.xxx`
- [x] `modules/storage_example.py` - 导入已更新
- [x] `storage_example.py` (根目录) - 导入已更新
- [x] 测试导入：`python -c "from modules.data_storage import DataStorage"` ✓
### 文档引用验证
- [x] 所有文档中的工具脚本路径已更新为 `scripts/` 前缀
- [x] 所有文档中的模块路径引用已更新（通过之前的 `update_doc_references.py`）
### 脚本路径验证
- [ ] 移动脚本后，测试脚本是否仍可运行
- [ ] 确认所有文档中的脚本路径正确
## 🎯 下一步操作
### 执行优化前
1. **确认所有引用已更新** ✅
- Python 导入路径：已更新
- 文档引用路径：已更新
2. **执行文件移动**
```powershell
# 步骤1：移动工具脚本
python move_scripts.py
# 步骤2：清理重复模块（在确认导入路径正确后）
python cleanup_duplicate_modules.py
```
3. **验证**
```powershell
# 测试脚本
python scripts/update_imports.py
# 测试主程序
streamlit run geo_tool.py
```
## 📝 注意事项
1. **工具脚本移动后**：
- 使用方式：`python scripts/script_name.py`
- 或在 `scripts/` 目录下运行：`cd scripts && python script_name.py`
2. **模块文件删除后**：
- 确保 `modules/` 目录中有完整版本
- 确保所有导入使用 `modules.xxx` 格式
- 如有问题，可从 Git 恢复
3. **文档引用**：
- 所有文档中的路径引用已自动更新
- 如有遗漏，可手动检查并更新
## 🆘 如果遇到问题
### 问题1：脚本找不到
**解决方案**：
- 使用完整路径：`python scripts/script_name.py`
- 或进入目录：`cd scripts && python script_name.py`
### 问题2：导入错误
**解决方案**：
- 检查导入路径：确认使用 `from modules.xxx import`
- 检查 `modules/__init__.py` 是否存在
- 从 Git 恢复文件：`git checkout HEAD -- filename.py`
### 问题3：文档链接失效
**解决方案**：
- 运行 `python scripts/update_doc_references.py` 更新文档引用
- 运行 `python scripts/update_script_references.py` 更新脚本引用
docs/guides/REORGANIZATION_SUMMARY.md
+243
View File
@@ -0,0 +1,243 @@
# 项目目录结构优化总结
## ✅ 已完成的工作
### 1. 目录结构创建
- ✅ 创建了 `docs/` 目录及其子目录：
- `docs/features/` - 功能文档
- `docs/analysis/` - 分析报告
- `docs/guides/` - 指南文档
- `docs/implementation/` - 实现文档
- ✅ 创建了 `modules/` 目录
- ✅ 创建了 `modules/__init__.py`
### 2. 分析文档创建
- ✅ `PROJECT_STRUCTURE_ANALYSIS.md` - 完整的项目结构分析
- ✅ `docs/DIRECTORY_STRUCTURE_OPTIMIZATION.md` - 详细的优化方案
- ✅ `QUICK_REORGANIZE.md` - 快速执行指南
### 3. 自动化脚本创建
- ✅ `scripts/update_imports.py` - 自动更新Python导入路径
- ✅ `scripts/update_doc_references.py` - 自动更新文档路径引用
- ✅ `scripts/reorganize_files.py` - 文件移动脚本（备用）
## 📋 待执行的任务
### 任务1：清理重复文件
**当前状态**：部分文件已移动到 `modules/`，但根目录仍有重复文件。
**需要操作**：
1. 检查根目录和 `modules/` 目录中的重复文件
2. 删除根目录中的重复文件（保留 `modules/` 中的版本）
**重复文件列表**（需要确认）：
- `config_optimizer.py`
- `content_metrics.py`
- `content_scorer.py`
- `data_storage.py`
- `eeat_enhancer.py`
- `fact_density_enhancer.py`
- `keyword_mining.py`
- `keyword_tool.py`
- `multimodal_prompt.py`
- `negative_monitor.py`
- `optimization_techniques.py`
- `resource_recommender.py`
- `roi_analyzer.py`
- `schema_generator.py`
- `semantic_expander.py`
- `storage_example.py`
- `technical_config_generator.py`
- `topic_cluster.py`
- `workflow_automation.py`
### 任务2：移动文档文件
**需要移动到 `docs/features/` 的文件**（15个）：
- `CONFIG_OPTIMIZER_FEATURE.md`
- `CONTENT_METRICS_FEATURE.md`
- `CONTENT_SCORER_FEATURE.md`
- `EEAT_FEATURE.md`
- `FACT_DENSITY_FEATURE.md`
- `JSON_LD_SCHEMA_FEATURE.md`
- `KEYWORD_MINING_FEATURE.md`
- `MULTIMODAL_FEATURE.md`
- `NEGATIVE_MONITOR_FEATURE.md`
- `OPTIMIZATION_TECHNIQUES_FEATURE.md`
- `RESOURCE_RECOMMENDER_FEATURE.md`
- `ROI_ANALYSIS_FEATURE.md`
- `SEMANTIC_EXPANSION_FEATURE.md`
- `TECHNICAL_CONFIG_FEATURE.md`
- `TOPIC_CLUSTER_FEATURE.md`
- `WORKFLOW_AUTOMATION_FEATURE.md`
**需要移动到 `docs/analysis/` 的文件**（7个）：
- `ANALYSIS_ACCURACY_REPORT.md`
- `CODE_DOCUMENTATION_ANALYSIS.md`
- `DOCUMENTATION_REVERSE_VERIFICATION.md`
- `FEATURE_ANALYSIS.md`
- `FEATURE_PRIORITY_ANALYSIS.md`
- `FUNCTION_VERIFICATION_REPORT.md`
- `GEO_COMPLIANCE_ANALYSIS.md`
**需要移动到 `docs/guides/` 的文件**（5个）：
- `QUICK_START_GUIDE.md`
- `STORAGE_GUIDE.md`
- `PLATFORM_SETUP.md`
- `LAYOUT_UPGRADE_GUIDE.md`
- `DECISION_GUIDE.md`
**需要移动到 `docs/implementation/` 的文件**（7个）：
- `IMPLEMENTATION_SUMMARY.md`
- `PLATFORM_SYNC_ANALYSIS.md`
- `PLATFORM_SYNC_IMPLEMENTATION.md`
- `PLATFORM_SYNC_TEST.md`
- `INTEGRATION_NOTES.md`
- `FEATURES_COMPLETE_LIST.md`
- `ADVANCED_FEATURES.md`
### 任务3：更新导入路径
**需要更新的文件**：
1. `geo_tool.py` - 更新所有模块导入
2. `modules/storage_example.py` - 更新 `data_storage` 导入
**执行命令**：
```powershell
python scripts/update_imports.py
```
### 任务4：更新文档引用
**需要更新的文件**：
- `README.md` - 更新所有文档路径引用
- 所有 `.md` 文件中的文档和模块路径引用
**执行命令**：
```powershell
python scripts/update_doc_references.py
```
## 🎯 优化后的目录结构
```
geo_tool/
├── README.md # 项目主文档
├── requirements.txt # 依赖文件
├── .gitignore # Git配置
├── .streamlit/ # Streamlit配置
│ └── config.toml
├── geo_tool.py # 主程序
│
├── modules/ # 功能模块（18个文件）
│ ├── __init__.py
│ ├── data_storage.py
│ ├── keyword_tool.py
│ ├── content_scorer.py
│ ├── eeat_enhancer.py
│ ├── semantic_expander.py
│ ├── fact_density_enhancer.py
│ ├── schema_generator.py
│ ├── topic_cluster.py
│ ├── multimodal_prompt.py
│ ├── roi_analyzer.py
│ ├── workflow_automation.py
│ ├── keyword_mining.py
│ ├── optimization_techniques.py
│ ├── content_metrics.py
│ ├── technical_config_generator.py
│ ├── negative_monitor.py
│ ├── resource_recommender.py
│ ├── config_optimizer.py
│ └── storage_example.py
│
├── platform_sync/ # 平台同步模块
│ ├── __init__.py
│ ├── base_publisher.py
│ ├── github_publisher.py
│ └── copy_manager.py
│
└── docs/ # 文档目录
├── features/ # 功能文档（15个）
├── analysis/ # 分析报告（7个）
├── guides/ # 指南文档（5个）
└── implementation/ # 实现文档（7个）
```
## 📝 执行步骤
### 快速执行（推荐）
1. **关闭所有打开的文件**（IDE、编辑器等）
2. **执行文件移动**：
```powershell
# 参考 QUICK_REORGANIZE.md 中的PowerShell脚本
```
3. **更新导入路径**：
```powershell
python scripts/update_imports.py
```
4. **更新文档引用**：
```powershell
python scripts/update_doc_references.py
```
5. **验证**：
```powershell
python -c "from modules.data_storage import DataStorage; print('✓ 导入成功')"
streamlit run geo_tool.py
```
## 🔍 文件引用关系
### Python 导入关系
**geo_tool.py** 需要更新的导入（18个）：
```python
# 旧导入
from data_storage import DataStorage
from keyword_tool import KeywordTool
# ...
# 新导入
from modules.data_storage import DataStorage
from modules.keyword_tool import KeywordTool
# ...
```
### 文档引用关系
**README.md** 中的文档路径需要更新：
- `xxx_FEATURE.md` → `docs/features/xxx_FEATURE.md`
- `xxx_GUIDE.md` → `docs/guides/xxx_GUIDE.md`
- `xxx.md` (implementation) → `docs/implementation/xxx.md`
## ✅ 验证清单
完成重组后，请验证：
- [ ] 根目录不再有重复的模块文件
- [ ] 所有文档文件已分类移动到 `docs/` 子目录
- [ ] `geo_tool.py` 中的导入路径已更新
- [ ] 所有文档中的路径引用已更新
- [ ] `python -c "from modules.data_storage import DataStorage"` 执行成功
- [ ] `streamlit run geo_tool.py` 运行正常
- [ ] 所有功能测试通过
## 📚 相关文档
- `QUICK_REORGANIZE.md` - 快速执行指南
- `PROJECT_STRUCTURE_ANALYSIS.md` - 详细的项目结构分析
- `docs/DIRECTORY_STRUCTURE_OPTIMIZATION.md` - 完整的优化方案
## 🎉 优化后的优势
1. **清晰的目录结构**：文件按功能分类，易于查找和管理
2. **模块化组织**：功能模块集中管理，便于维护和扩展
3. **文档分类清晰**：功能文档、分析报告、指南文档分开管理
4. **符合最佳实践**：遵循Python项目标准目录结构
5. **便于协作**：团队成员更容易理解项目结构
docs/guides/ROOT_DIRECTORY_RULES.md
+100
View File
@@ -0,0 +1,100 @@
# 根目录文件管理规则
## 📋 根目录文件规范
### ✅ 允许在根目录的文件
**核心文件（必须保留）**：
1. `README.md` - 项目主文档
2. `DOCS.md` - 文档索引
3. `geo_tool.py` - 主程序
4. `requirements.txt` - 依赖文件
5. `.gitignore` - Git配置
6. `.streamlit/` - Streamlit配置目录
### ❌ 禁止在根目录创建的文件
1. **文档文件（.md）**
- ❌ 禁止在根目录创建任何新的 `.md` 文档
- ✅ 所有文档应放在 `docs/` 的相应子目录中
2. **功能模块文件（.py）**
- ❌ 禁止在根目录创建功能模块文件
- ✅ 所有功能模块应放在 `modules/` 目录
3. **工具脚本文件（.py）**
- ❌ 禁止在根目录创建工具脚本
- ✅ 所有工具脚本应放在 `scripts/` 目录
## 📁 文件位置规则
### 文档文件
| 文档类型 | 位置 | 示例 |
|---------|------|------|
| 功能文档 | `docs/features/` | `docs/features/CONFIG_OPTIMIZER_FEATURE.md` |
| 分析报告 | `docs/analysis/` | `docs/analysis/FEATURE_ANALYSIS.md` |
| 使用指南 | `docs/guides/` | `docs/guides/QUICK_START_GUIDE.md` |
| 实现文档 | `docs/implementation/` | `docs/implementation/IMPLEMENTATION_SUMMARY.md` |
### Python 文件
| 文件类型 | 位置 | 示例 |
|---------|------|------|
| 功能模块 | `modules/` | `modules/data_storage.py` |
| 工具脚本 | `scripts/` | `scripts/update_imports.py` |
| 主程序 | 根目录 | `geo_tool.py` |
| 平台同步 | `platform_sync/` | `platform_sync/github_publisher.py` |
## 🎯 创建新文件时的检查
创建新文件前，请确认：
1. **如果是文档文件**：
- [ ] 是否放在了正确的 `docs/` 子目录？
- [ ] 是否更新了 `DOCS.md` 的索引？
2. **如果是功能模块**：
- [ ] 是否放在了 `modules/` 目录？
- [ ] 是否更新了导入路径？
3. **如果是工具脚本**：
- [ ] 是否放在了 `scripts/` 目录？
## 📝 当前需要清理的根目录文件
以下文件应删除或移动到合适位置：
### 需要删除的重复文档（docs/guides/中已有）：
- `ADVANCED_OPTIMIZATION_PLAN.md`
- `FINAL_OPTIMIZATION_GUIDE.md`
- `REFERENCE_UPDATE_SUMMARY.md`
- `OPTIMIZATION_STATUS.md`
### 需要移动的文档：
- `MANUAL_CLEANUP_GUIDE.md` → `docs/guides/`
## 🚀 快速清理命令
```powershell
# 删除重复文档
Remove-Item ADVANCED_OPTIMIZATION_PLAN.md -Force
Remove-Item FINAL_OPTIMIZATION_GUIDE.md -Force
Remove-Item REFERENCE_UPDATE_SUMMARY.md -Force
Remove-Item OPTIMIZATION_STATUS.md -Force
# 移动文档
Move-Item MANUAL_CLEANUP_GUIDE.md -Destination "docs\guides\" -Force
```
## ✅ 清理后的根目录
清理完成后，根目录应该只有：
- `README.md`
- `DOCS.md`
- `geo_tool.py`
- `requirements.txt`
- `.gitignore`
- `.streamlit/` (目录)
**总计：5个核心文件 + 1个配置目录**
docs/guides/STORAGE_GUIDE.md
+194
View File
@@ -0,0 +1,194 @@
# 数据持久化方案对比
## 为什么不能用 IndexedDB？
**IndexedDB 是浏览器 API**，只能在 JavaScript 前端使用。
**Streamlit 是 Python 后端应用**，运行在服务器端，无法使用 IndexedDB。
---
## 方案对比
### 方案1：SQLite（⭐ 推荐）
**优点：**
- ✅ Python 内置支持（`sqlite3`），无需安装额外依赖
- ✅ 单文件数据库，易于备份和迁移
- ✅ 查询性能好，支持复杂查询
- ✅ 支持事务，数据安全
- ✅ 支持 SQL 查询，灵活强大
- ✅ 适合 MVP 到生产环境的平滑升级
**缺点：**
- ⚠️ 需要学习基本的 SQL（但很简单）
- ⚠️ 多进程写入需要处理锁（Streamlit 单进程，无此问题）
**代码复杂度：** ⭐⭐（非常简单）
**适用场景：** MVP 和生产环境都适用
---
### 方案2：JSON 文件
**优点：**
- ✅ 最简单，无需学习 SQL
- ✅ 人类可读，易于调试
- ✅ 无需数据库知识
**缺点：**
- ❌ 查询性能差（需要加载整个文件）
- ❌ 数据量大时很慢
- ❌ 并发写入可能丢失数据
- ❌ 不支持复杂查询
**代码复杂度：** ⭐（极简单）
**适用场景：** 仅适合数据量很小（<1000条）的 MVP
---
## 推荐方案：SQLite
### 为什么推荐 SQLite？
1. **其实很简单**：只需要几行代码
```python
import sqlite3
conn = sqlite3.connect('data.db')
cursor = conn.cursor()
cursor.execute("INSERT INTO table VALUES (?)", (value,))
conn.commit()
conn.close()
```
2. **性能好**：即使数据量增长到几万条，依然很快
3. **功能强大**：支持统计、查询、分析，为后续功能扩展打好基础
4. **零依赖**：Python 内置，无需安装任何包
---
## 快速开始
### 1. 使用已封装好的 DataStorage 类
我已经为你创建了 `modules/data_storage.py`，提供了统一的接口：
```python
from data_storage import DataStorage
# 初始化（SQLite方式）
storage = DataStorage(storage_type="sqlite", db_path="geo_data.db")
# 保存关键词
storage.save_keywords(["关键词1", "关键词2"], "品牌名")
# 获取关键词
keywords = storage.get_keywords("品牌名")
# 保存文章
storage.save_article("关键词", "平台", "内容", "文件名", "品牌名")
# 获取统计数据
stats = storage.get_stats("品牌名")
```
### 2. 最小改动集成
在 `modules/geo_tool.py` 中，只需要在关键位置添加几行保存代码：
```python
# 文件顶部
from data_storage import DataStorage
storage = DataStorage(storage_type="sqlite", db_path="geo_data.db")
# 关键词生成后（约第533行）
if cleaned:
st.session_state.keywords = cleaned
storage.save_keywords(cleaned, brand) # 新增这一行
st.success(f"生成完成（{len(cleaned)} 条）")
# 内容生成后（约第714行）
st.session_state.generated_contents = contents
storage.save_article(keyword, plat, content, filename, brand) # 在循环中添加
# 优化后（约第838行）
st.session_state.optimized_article = optimized_article
storage.save_optimization(
original_article, optimized_article, changes, target_platform, brand
) # 新增
# 验证后（约第932行）
st.session_state.verify_combined = combined
storage.save_verify_results(all_results) # 新增
```
### 3. 添加历史记录查看功能（可选）
可以新增一个 Tab 来查看历史数据：
```python
tab5 = st.tabs([..., "5 历史记录"])
with tab5:
st.header("历史记录")
# 统计数据
stats = storage.get_stats(brand)
col1, col2, col3, col4 = st.columns(4)
col1.metric("关键词", stats["keywords_count"])
col2.metric("文章", stats["articles_count"])
col3.metric("优化", stats["optimizations_count"])
col4.metric("验证", stats["verify_results_count"])
# 历史文章列表
articles = storage.get_articles(brand=brand)
if articles:
df = pd.DataFrame(articles)
st.dataframe(df[["keyword", "platform", "created_at"]])
```
---
## 数据库文件位置
- **SQLite 文件**：`geo_data.db`（项目根目录）
- **JSON 文件**：`data/` 目录（如果使用 JSON 方式）
**建议：** 将 `geo_data.db` 添加到 `.gitignore`，避免提交到版本控制。
---
## 性能对比（参考）
| 数据量 | SQLite | JSON文件 |
|--------|--------|----------|
| 100条 | <10ms | <10ms |
| 1000条 | <50ms | ~100ms |
| 10000条 | ~200ms | ~5秒 |
| 100000条 | ~1秒 | 很慢 |
---
## 总结
**对于 MVP 版本，强烈推荐使用 SQLite：**
1. ✅ 简单：使用封装好的 `DataStorage` 类，只需几行代码
2. ✅ 高效：性能好，支持未来扩展
3. ✅ 可靠：数据安全，支持事务
4. ✅ 零依赖：Python 内置，无需安装
**如果数据量真的非常小（<100条），可以考虑 JSON 文件。**
---
## 下一步
1. 查看 `modules/data_storage.py` 了解实现细节
2. 查看 `modules/storage_example.py` 了解使用方法
3. 在 `modules/geo_tool.py` 中集成（参考上面的最小改动示例）
需要我帮你直接集成到 `modules/geo_tool.py` 吗？