Metadata-Version: 2.4
Name: geo-seo-optimizer
Version: 0.1.0
Summary: 结合 SEO 与 GEO 技术的内容优化工具
Project-URL: Homepage, https://github.com/geo-seo/optimizer
Project-URL: Documentation, https://docs.geo-seo.dev
Project-URL: Repository, https://github.com/geo-seo/optimizer.git
Project-URL: Issues, https://github.com/geo-seo/optimizer/issues
Author-email: GEO-SEO Team <team@geo-seo.dev>
License: MIT License
        
        Copyright (c) 2026 GEO-SEO Optimizer
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ai,content,geo,optimization,seo
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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>
