1744d8e7db
New Features: - Selective field analysis: Choose which fields to analyze (title, meta_description, categories, site) - In-place CSV updates: Update input CSV with new columns (automatic backup created) - Category proposer: Dedicated command for AI-powered category suggestions New Commands: - seo analyze -f title categories: Analyze specific fields only - seo analyze -u: Update input CSV with recommendations - seo category_propose: Propose categories based on content New Scripts: - enhanced_analyzer.py: Enhanced AI analyzer with selective analysis - category_proposer.py: Dedicated category proposal tool CLI Options: - --fields, -f: Specify fields to analyze - --update, -u: Update input CSV (creates backup) - --output, -o: Custom output file path Output Columns: - proposed_title, title_reason (for title analysis) - proposed_meta_description, meta_reason (for meta analysis) - proposed_category, category_reason (for category analysis) - proposed_site, site_reason (for site analysis) - ai_confidence, ai_priority (common to all) Documentation: - ENHANCED_ANALYSIS_GUIDE.md: Complete guide with examples Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
302 lines
7.2 KiB
Markdown
302 lines
7.2 KiB
Markdown
# Enhanced Analysis Guide
|
|
|
|
## Overview
|
|
|
|
The SEO automation tool now provides enhanced analysis capabilities with:
|
|
|
|
1. **Selective Field Analysis** - Choose which fields to analyze (title, meta description, categories, site)
|
|
2. **In-place CSV Updates** - Update input CSV with new columns (with automatic backup)
|
|
3. **Category Proposer** - Dedicated command for AI-powered category suggestions
|
|
|
|
## Commands
|
|
|
|
### 1. Enhanced Analysis (`seo analyze`)
|
|
|
|
Analyze posts with AI and add recommendation columns to your CSV.
|
|
|
|
#### Basic Usage
|
|
```bash
|
|
# Analyze all fields (default behavior)
|
|
./seo analyze
|
|
|
|
# Analyze specific CSV file
|
|
./seo analyze output/all_posts_2026-02-16.csv
|
|
```
|
|
|
|
#### Selective Field Analysis
|
|
```bash
|
|
# Analyze only titles
|
|
./seo analyze -f title
|
|
|
|
# Analyze titles and categories
|
|
./seo analyze -f title categories
|
|
|
|
# Analyze meta descriptions only
|
|
./seo analyze -f meta_description
|
|
|
|
# Analyze all fields
|
|
./seo analyze -f title meta_description categories site
|
|
```
|
|
|
|
#### Update Input CSV (In-place)
|
|
```bash
|
|
# Update input CSV with new columns (creates backup automatically)
|
|
./seo analyze -u
|
|
|
|
# Update with specific fields only
|
|
./seo analyze -u -f title meta_description
|
|
|
|
# Specify custom output file
|
|
./seo analyze -o output/my_analysis.csv
|
|
```
|
|
|
|
#### Output Columns
|
|
|
|
Depending on selected fields, the following columns are added:
|
|
|
|
**Title Analysis:**
|
|
- `proposed_title` - AI-suggested improved title
|
|
- `title_reason` - Explanation for title change
|
|
|
|
**Meta Description Analysis:**
|
|
- `proposed_meta_description` - AI-suggested meta description (120-160 chars)
|
|
- `meta_reason` - Explanation for meta description change
|
|
|
|
**Category Analysis:**
|
|
- `proposed_category` - AI-suggested best category
|
|
- `category_reason` - Explanation for category choice
|
|
|
|
**Site Analysis:**
|
|
- `proposed_site` - AI-suggested best site
|
|
- `site_reason` - Explanation for site recommendation
|
|
|
|
**Common Fields:**
|
|
- `ai_confidence` - AI confidence level (High/Medium/Low)
|
|
- `ai_priority` - Priority level (High/Medium/Low)
|
|
|
|
### 2. Category Proposer (`seo category_propose`)
|
|
|
|
Dedicated command for AI-powered category suggestions based on post content.
|
|
|
|
#### Usage
|
|
```bash
|
|
# Propose categories for latest export
|
|
./seo category_propose
|
|
|
|
# Propose categories for specific CSV
|
|
./seo category_propose output/all_posts_2026-02-16.csv
|
|
|
|
# Save to custom output file
|
|
./seo category_propose -o output/my_category_proposals.csv
|
|
```
|
|
|
|
#### Output Columns
|
|
- `post_id` - Post identifier
|
|
- `title` - Post title
|
|
- `current_categories` - Current categories
|
|
- `proposed_category` - AI-suggested category
|
|
- `alternative_categories` - Alternative category suggestions
|
|
- `category_reason` - Explanation for suggestion
|
|
- `category_confidence` - Confidence level
|
|
|
|
## Examples
|
|
|
|
### Example 1: Analyze Titles Only
|
|
```bash
|
|
# Analyze only titles for SEO optimization
|
|
./seo analyze -f title
|
|
|
|
# Output: analyzed_posts_YYYYMMDD_HHMMSS.csv
|
|
# Contains: original columns + proposed_title + title_reason + ai_confidence
|
|
```
|
|
|
|
### Example 2: Update CSV with Meta Descriptions
|
|
```bash
|
|
# Update input CSV with proposed meta descriptions
|
|
./seo analyze -u -f meta_description
|
|
|
|
# Creates:
|
|
# - all_posts_2026-02-16_backup_YYYYMMDD_HHMMSS.csv (backup)
|
|
# - all_posts_2026-02-16.csv (updated with new columns)
|
|
```
|
|
|
|
### Example 3: Full Category Analysis
|
|
```bash
|
|
# Propose categories for all posts
|
|
./seo category_propose
|
|
|
|
# Review proposals
|
|
open output/category_proposals_*.csv
|
|
|
|
# Apply approved categories manually in WordPress
|
|
```
|
|
|
|
### Example 4: Multi-Field Analysis
|
|
```bash
|
|
# Analyze titles and categories together
|
|
./seo analyze -f title categories
|
|
|
|
# Output includes:
|
|
# - proposed_title, title_reason
|
|
# - proposed_category, category_reason
|
|
# - ai_confidence, ai_priority
|
|
```
|
|
|
|
### Example 5: Targeted Analysis with Output
|
|
```bash
|
|
# Analyze meta descriptions, save to specific file
|
|
./seo analyze -f meta_description -o output/meta_analysis.csv
|
|
```
|
|
|
|
## Workflow Examples
|
|
|
|
### Workflow 1: SEO Title Optimization
|
|
```bash
|
|
# 1. Export posts
|
|
./seo export
|
|
|
|
# 2. Analyze titles only
|
|
./seo analyze -f title
|
|
|
|
# 3. Review proposed titles
|
|
open output/analyzed_posts_*.csv
|
|
|
|
# 4. Manually update best titles in WordPress
|
|
```
|
|
|
|
### Workflow 2: Category Reorganization
|
|
```bash
|
|
# 1. Export posts
|
|
./seo export
|
|
|
|
# 2. Get category proposals
|
|
./seo category_propose
|
|
|
|
# 3. Review proposals
|
|
open output/category_proposals_*.csv
|
|
|
|
# 4. Apply approved category changes
|
|
```
|
|
|
|
### Workflow 3: Complete SEO Audit
|
|
```bash
|
|
# 1. Export posts
|
|
./seo export
|
|
|
|
# 2. Analyze all fields
|
|
./seo analyze -f title meta_description categories site
|
|
|
|
# 3. Review comprehensive analysis
|
|
open output/analyzed_posts_*.csv
|
|
|
|
# 4. Implement changes based on AI recommendations
|
|
```
|
|
|
|
### Workflow 4: Incremental Analysis
|
|
```bash
|
|
# 1. Export posts
|
|
./seo export
|
|
|
|
# 2. Analyze titles (fast, low cost)
|
|
./seo analyze -f title
|
|
|
|
# 3. Later, analyze meta descriptions
|
|
./seo analyze -u -f meta_description
|
|
|
|
# 4. Later, analyze categories
|
|
./seo analyze -u -f categories
|
|
|
|
# Result: CSV progressively enriched with AI recommendations
|
|
```
|
|
|
|
## Cost Optimization
|
|
|
|
### Reduce API Costs
|
|
|
|
```bash
|
|
# Analyze only needed fields (saves tokens)
|
|
./seo analyze -f title # Cheaper than analyzing all fields
|
|
|
|
# Use smaller batch sizes for better control
|
|
# (edit script or use environment variable)
|
|
|
|
# Analyze in stages
|
|
./seo analyze -f title
|
|
./seo analyze -u -f meta_description
|
|
# Total cost similar, but better control over each step
|
|
```
|
|
|
|
### Token Usage by Field
|
|
|
|
Approximate token usage per 100 posts:
|
|
- **title**: ~500 tokens (lowest cost)
|
|
- **meta_description**: ~800 tokens
|
|
- **categories**: ~600 tokens
|
|
- **site**: ~400 tokens (lowest cost)
|
|
- **All fields**: ~2000 tokens (best value)
|
|
|
|
## Best Practices
|
|
|
|
1. **Start Small**: Test with `-f title` first to see AI quality
|
|
2. **Review Before Applying**: Always review AI suggestions before implementing
|
|
3. **Use Backups**: The `-u` flag creates automatic backups
|
|
4. **Batch Analysis**: Analyze related fields together for better context
|
|
5. **Confidence Matters**: Pay attention to `ai_confidence` column
|
|
6. **Iterative Process**: Enrich CSVs incrementally for better control
|
|
|
|
## Troubleshooting
|
|
|
|
### No CSV File Found
|
|
```bash
|
|
# Error: No CSV file found
|
|
# Solution: Run export first or provide file path
|
|
./seo export
|
|
./seo analyze
|
|
|
|
# Or specify file directly
|
|
./seo analyze path/to/your/file.csv
|
|
```
|
|
|
|
### API Key Not Set
|
|
```bash
|
|
# Error: OPENROUTER_API_KEY not set
|
|
# Solution: Add to .env file
|
|
echo "OPENROUTER_API_KEY=your_key_here" >> .env
|
|
```
|
|
|
|
### High API Costs
|
|
```bash
|
|
# Reduce costs by analyzing fewer fields
|
|
./seo analyze -f title # Instead of all fields
|
|
|
|
# Or analyze in batches
|
|
./seo analyze -f title
|
|
./seo analyze -u -f meta_description
|
|
```
|
|
|
|
## File Formats
|
|
|
|
### Input CSV Requirements
|
|
|
|
Must contain at minimum:
|
|
- `post_id` - Unique identifier
|
|
- `title` - Post title (for title analysis)
|
|
- `meta_description` - Current meta (for meta analysis)
|
|
- `categories` - Current categories (for category analysis)
|
|
- `site` - Current site (for site analysis)
|
|
- `content_preview` or `content` - Post content (recommended for all analyses)
|
|
|
|
### Output CSV Format
|
|
|
|
Standard output includes:
|
|
- All original columns
|
|
- New `proposed_*` columns for analyzed fields
|
|
- `*_reason` columns with explanations
|
|
- `ai_confidence` and `ai_priority` columns
|
|
|
|
---
|
|
|
|
**Version**: 1.0.0
|
|
**Last Updated**: 2026-02-16
|
|
**Related**: See ARCHITECTURE.md for system overview
|