# GEO-SEO Optimizer

<div align="center">

[![Python](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/Tests-125%20passing-success.svg)](tests/)
[![Coverage](https://img.shields.io/badge/Coverage-95%25-brightgreen.svg)](coverage_html/)
[![Code Style](https://img.shields.io/badge/Code%20Style-Black-black.svg)](https://github.com/psf/black)

**结合 SEO 与 GEO（生成式引擎优化）技术的内容优化工具**

**Content optimization tool combining SEO with GEO (Generative Engine Optimization)**

</div>

---

## 目录 Table of Contents

- [简介 Introduction](#简介-introduction)
- [功能特性 Features](#功能特性-features)
- [安装 Installation](#安装-installation)
- [快速开始 Quick Start](#快速开始-quick-start)
- [使用指南 Usage Guide](#使用指南-usage-guide)
- [项目结构 Project Structure](#项目结构-project-structure)
- [API 参考 API Reference](#api-参考-api-reference)
- [测试 Testing](#测试-testing)
- [技术栈 Tech Stack](#技术栈-tech-stack)
- [贡献 Contributing](#贡献-contributing)
- [许可证 License](#许可证-license)

---

## 简介 Introduction

### 中文

GEO-SEO Optimizer 是下一代内容优化工具，它不仅仅是传统的 SEO 工具，更专注于 **GEO（Generative Engine Optimization）** —— 让内容更容易被 AI 引擎（如 ChatGPT、Claude、Perplexity 等）引用和理解。

**核心差异化优势：**
- SEO 只是表层优化，真正的差距在于 GEO
- 让内容被 AI 引擎引用，获得未来搜索流量
- 结合传统搜索引擎和生成式引擎的双重优化

### English

GEO-SEO Optimizer is a next-generation content optimization tool that goes beyond traditional SEO to focus on **GEO (Generative Engine Optimization)** — making content more likely to be cited and understood by AI engines (ChatGPT, Claude, Perplexity, etc.).

**Key Differentiators:**
- SEO is just the surface; the real advantage is GEO
- Get your content cited by AI engines for future search traffic
- Dual optimization for traditional search and generative engines

---

## 功能特性 Features

| 模块 Module | 中文 | English |
|------------|------|---------|
| **关键词研究** Keyword Research | Google Keyword Planner API 封装、竞争度分析、批量异步处理 | Google Keyword Planner API wrapper, competition analysis, batch async processing |
| **内容生成** Content Generation | SEO 优化、GEO 优化、Schema.org 结构化数据生成 | SEO optimization, GEO optimization, Schema.org structured data |
| **平台适配** Platform Adaptation | Quora、Medium、Reddit、LinkedIn、Twitter 多平台格式适配 | Multi-platform format adaptation for Quora, Medium, Reddit, LinkedIn, Twitter |
| **数据分析** Analytics | Google Search Console 集成、GEO 表现分析、HTML/JSON 报告生成 | Google Search Console integration, GEO performance analysis, HTML/JSON reporting |

### 高级特性 Advanced Features

- **异步架构** Async Architecture - 基于 asyncio 的高性能异步处理
- **限流保护** Rate Limiting - 令牌桶算法保护 API 调用
- **CJK 支持** CJK Support - 完整支持中文、日文、韩文内容优化
- **行业对标** Industry Benchmarks - 与 Yoast SEO、SEMrush 标准对齐

---

## 安装 Installation

### 系统要求 Requirements

- Python 3.11+
- pip 或 uv

### 安装方式 Installation Methods

```bash
# 从源码安装 Install from source
git clone https://github.com/geo-seo/optimizer.git
cd optimizer
pip install -e ".[dev]"

# 或使用 uv Using uv
uv pip install -e ".[dev]"
```

### 配置 Configuration

创建配置文件 Create config file:

```bash
mkdir -p config
cp config/settings.yaml.example config/settings.yaml
```

编辑 `config/settings.yaml`:

```yaml
# Google Ads API 配置
api:
  developer_token: "your_developer_token"
  client_id: "your_client_id"
  client_secret: "your_client_secret"
  refresh_token: "your_refresh_token"
  login_customer_id: "your_customer_id"

# 限流配置
rate_limiter:
  requests_per_minute: 100
  window_seconds: 60

# 平台限制配置
platforms:
  twitter:
    max_length: 280
    cjk_max_length: 140
```

---

## 快速开始 Quick Start

### 1. 关键词研究 Keyword Research

```bash
# 单个关键词研究 Single keyword research
geo-seo keywords research "digital marketing" --output ./data/keywords/

# 批量关键词研究 Batch keyword research
geo-seo keywords research-file ./keywords.txt --output ./data/ --max-concurrent 10
```

### 2. 内容生成 Content Generation

```bash
# 生成 SEO + GEO 优化内容 Generate SEO + GEO optimized content
geo-seo content generate "best ai tools" --platform medium --geo --seo

# 仅 GEO 优化 GEO only
geo-seo content generate "machine learning guide" --platform quora --geo

# 保存到文件 Save to file
geo-seo content generate "content marketing" --platform medium --output ./article.md
```

### 3. 平台适配 Platform Adaptation

```bash
# 适配现有内容到不同平台 Adapt existing content to different platforms
geo-seo content adapt ./article.md --platform twitter
geo-seo content adapt ./article.md --platform linkedin
geo-seo content adapt ./article.md --platform reddit
```

### 4. GEO 分析 GEO Analysis

```bash
# 分析内容的 GEO 评分 Analyze GEO score
geo-seo analytics geo ./content.md

# 生成完整报告 Generate full report
geo-seo analytics report --days 30 --format html --output ./report.html
```

---

## 使用指南 Usage Guide

### 关键词研究模块 Keyword Research Module

```python
from src.keyword_research.google_planner import GoogleKeywordPlanner
from src.keyword_research.batch_processor import BatchProcessor

async def research_keywords():
    # 初始化规划器
    planner = GoogleKeywordPlanner()

    # 单个关键词查询
    data = await planner.get_keyword_data("seo tools")
    print(f"月搜索量: {data.avg_monthly_searches}")

    # 批量处理
    processor = BatchProcessor(planner, max_concurrent=10)
    keywords = ["seo", "content marketing", "ai tools", "..."]
    results = await processor.process(keywords)
```

### 内容生成模块 Content Generation Module

```python
from src.content_generator.seo_optimizer import SEOOptimizer
from src.content_generator.geo_optimizer import GEOOptimizer

# SEO 优化
seo_opt = SEOOptimizer()
result = seo_opt.optimize(
    content="Your content here...",
    keyword="target keyword",
    title="Article Title"
)
print(f"SEO 评分: {result.score}")

# GEO 优化
geo_opt = GEOOptimizer()
geo_result = geo_opt.optimize(content)
print(f"GEO 评分: {geo_result.score}")
print(f"实体: {geo_result.entities}")
```

### 平台适配器 Platform Adapters

```python
from src.platform_adapter import TwitterAdapter, MediumAdapter, LinkedInAdapter

# Twitter 适配 - 支持 CJK 字符
adapter = TwitterAdapter()
content = adapter.format_content(
    "Your long article content...",
    extract_hashtags=True
)
print(f"字数: {len(content.body)}")  # 自动限制在 280/140

# Medium 适配
medium = MediumAdapter()
result = medium.format_content(content, add_toc=True)

# LinkedIn 适配
linkedin = LinkedInAdapter()
result = linkedin.format_content(content, professional_tone=True)
```

---

## 项目结构 Project Structure

```
geo-seo-optimizer/
├── src/                          # 源代码 Source code
│   ├── keyword_research/         # 关键词研究 Keyword research
│   │   ├── google_planner.py     # Google Ads API 封装
│   │   ├── analyzer.py           # 竞争度分析
│   │   └── batch_processor.py    # 异步批量处理
│   ├── content_generator/        # 内容生成 Content generation
│   │   ├── seo_optimizer.py      # SEO 优化逻辑
│   │   ├── geo_optimizer.py      # GEO 优化逻辑
│   │   ├── schema_builder.py     # Schema.org 结构化数据
│   │   └── template_engine.py    # Jinja2 模板引擎
│   ├── platform_adapter/         # 平台适配 Platform adapters
│   │   ├── base_adapter.py       # 抽象基类
│   │   ├── twitter_adapter.py    # Twitter 线程支持
│   │   ├── medium_adapter.py     # Medium 文章格式
│   │   ├── quora_adapter.py      # Quora 问答格式
│   │   ├── reddit_adapter.py     # Reddit 帖子格式
│   │   └── linkedin_adapter.py   # LinkedIn 专业格式
│   ├── analytics/                # 数据分析 Analytics
│   │   ├── gsc_connector.py      # Google Search Console API
│   │   ├── metrics_tracker.py    # SQLite 指标追踪
│   │   ├── geo_analyzer.py       # GEO 表现分析
│   │   └── reporter.py           # 报告生成
│   ├── utils/                    # 工具模块 Utilities
│   │   ├── config.py             # Pydantic 配置管理
│   │   ├── rate_limiter.py       # 异步令牌桶限流
│   │   ├── validators.py         # 输入验证
│   │   └── logger.py             # Rich 日志
│   └── cli.py                    # 统一 CLI 入口
├── tests/                        # 测试 Tests
│   ├── unit/                     # 单元测试
│   ├── integration/              # 集成测试
│   ├── e2e/                      # 端到端测试
│   ├── performance/              # 性能测试
│   ├── security/                 # 安全测试
│   ├── platform/                 # 平台适配测试
│   └── algorithm/                # 算法准确性测试
├── config/                       # 配置文件
│   ├── settings.yaml             # 主配置
│   └── platforms.yaml            # 平台限制配置
├── coverage_html/                # 覆盖率报告
├── pyproject.toml               # 项目配置
├── README.md                    # 项目文档
└── LICENSE                      # 许可证
```

---

## API 参考 API Reference

### SEOOptimizer

| 方法 Method | 描述 Description | 参数 Parameters |
|------------|-----------------|----------------|
| `optimize(content, keyword, title)` | 优化内容并评分 | `content: str`, `keyword: str`, `title: str` |
| `calculate_keyword_density(content, keyword)` | 计算关键词密度 | `content: str`, `keyword: str` |
| `calculate_readability(content)` | 计算 Flesch-Kincaid 可读性评分 | `content: str` |
| `optimize_title(title, keyword)` | 优化标题 | `title: str`, `keyword: str` |

### GEOOptimizer

| 方法 Method | 描述 Description | 参数 Parameters |
|------------|-----------------|----------------|
| `optimize(content)` | GEO 优化内容 | `content: str` |
| `extract_entities(content)` | 提取命名实体 | `content: str` |
| `calculate_semantic_completeness(content)` | 计算语义完整性 | `content: str` |

### BatchProcessor

| 方法 Method | 描述 Description | 参数 Parameters |
|------------|-----------------|----------------|
| `process(keywords)` | 批量处理关键词 | `keywords: list[str]` |
| `process_with_progress(keywords)` | 带进度回调的批量处理 | `keywords: list[str]` |

---

## 测试 Testing

### 运行测试 Run Tests

```bash
# 运行所有测试 Run all tests
python -m pytest tests/ -v

# 运行特定测试类别 Run specific test categories
python -m pytest tests/unit/ -v                    # 单元测试
python -m pytest tests/integration/ -v             # 集成测试
python -m pytest tests/performance/ -v             # 性能测试
python -m pytest tests/security/ -v                # 安全测试
python -m pytest tests/algorithm/ -v               # 算法测试

# 带覆盖率报告 With coverage report
python -m pytest tests/ --cov=src --cov-report=html

# 打开覆盖率报告 Open coverage report
open coverage_html/index.html
```

### 测试覆盖 Test Coverage

- **总覆盖率 Total Coverage**: 95%
- **单元测试 Unit Tests**: 125+ tests
- **测试目标 Target**: > 80% (已达成 achieved)

### 性能基准 Performance Benchmarks

| 测试项 Test | 目标 Target | 状态 Status |
|------------|------------|------------|
| 100 关键词批量处理 | < 10s | ✅ Pass |
| 1000 关键词批量处理 | < 60s | ✅ Pass |
| 内存使用 | < 500MB | ✅ Pass |
| 缓存命中率 | > 80% | ✅ Pass |

---

## 技术栈 Tech Stack

| 组件 Component | 用途 Purpose | 版本 Version |
|---------------|-------------|-------------|
| **Python** | 编程语言 | 3.11+ |
| **Pydantic v2** | 数据验证与配置 | >=2.0.0 |
| **Typer** | CLI 框架 | >=0.9.0 |
| **Rich** | 终端美化与日志 | >=13.0.0 |
| **Jinja2** | 模板引擎 | >=3.1.0 |
| **aiosqlite** | 异步 SQLite | >=0.19.0 |
| **aiohttp** | 异步 HTTP 客户端 | >=3.8.0 |
| **pytest** | 测试框架 | >=7.0.0 |
| **pytest-asyncio** | 异步测试 | >=0.21.0 |
| **black** | 代码格式化 | >=23.0.0 |
| **ruff** | 代码检查 | >=0.1.0 |
| **mypy** | 类型检查 | >=1.5.0 |

---

## 贡献 Contributing

### 开发流程 Development Workflow

1. Fork 项目并创建分支 Fork the project and create a branch
2. 安装开发依赖 Install dev dependencies
3. 编写代码并添加测试 Write code and add tests
4. 确保测试通过 Ensure tests pass
5. 提交 Pull Request Submit Pull Request

### 代码规范 Code Standards

```bash
# 格式化代码 Format code
python -m black src/ tests/

# 代码检查 Linting
python -m ruff check src/ tests/

# 类型检查 Type checking
python -m mypy src/ --ignore-missing-imports

# 运行测试 Run tests
python -m pytest tests/ --cov=src --cov-fail-under=80
```

### Git 提交规范 Commit Convention

```
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建/工具相关
```

---

## 许可证 License

[MIT License](LICENSE) © GEO-SEO Team

---

## 联系我们 Contact

- **GitHub Issues**: [https://github.com/geo-seo/optimizer/issues](https://github.com/geo-seo/optimizer/issues)
- **Documentation**: [https://docs.geo-seo.dev](https://docs.geo-seo.dev)
- **Email**: team@geo-seo.dev

---

<div align="center">

**Made with ❤️ for the future of content optimization**

**为内容优化的未来而创造**

</div>
