geo-seo-optimizer 0.1.1

结合 SEO 与 GEO 技术的内容优化工具

GEO-SEO Optimizer

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

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

---

目录 Table of Contents

• 简介 Introduction
• 功能特性 Features
• 安装 Installation
• 快速开始 Quick Start
• 使用指南 Usage Guide
• 项目结构 Project Structure
• API 参考 API Reference
• 测试 Testing
• 技术栈 Tech Stack
• 贡献 Contributing
• 许可证 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

# 从源码安装 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:

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

编辑 config/settings.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

# 单个关键词研究 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

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

# 适配现有内容到不同平台 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

# 分析内容的 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

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

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

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

# 运行所有测试 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

# 格式化代码 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 © GEO-SEO Team

---

联系我们 Contact

• GitHub Issues: https://github.com/geo-seo/optimizer/issues
• Documentation: https://docs.geo-seo.dev
• Email: [e-mail]

---

Made with ❤️ for the future of content optimization

为内容优化的未来而创造