hexo-ai-summary-pro/README.md

Professional AI summary generator for Hexo - supports multiple AI providers with automatic generation

# hexo-ai-summary-pro

[![npm version](https://badge.fury.io/js/hexo-ai-summary-pro.svg)](https://badge.fury.io/js/hexo-ai-summary-pro)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/hexo-ai-summary-pro.svg)](https://nodejs.org/)

Professional AI summary generator for Hexo - supports multiple AI providers with automatic generation.

专业的Hexo AI摘要生成插件 - 支持多种AI服务商，具备自动生成功能。

## 🔥 v1.0.3 重要更新

**修复了插件在新安装的 Hexo 博客中无法正常工作的问题！**

- ✅ 修复了插件注册机制，现在可以在任何 Hexo 博客中开箱即用
- ✅ 修复了命令行工具无法注册的问题
- ✅ 优化了插件初始化流程
- ✅ 完全兼容 Hexo 7.x 版本

如果你之前遇到插件无法工作的问题，请更新到最新版本！

## 🌟 Features | 特性

- 🤖 **Multiple AI Providers** | **多AI服务商支持**
  - OpenAI (GPT-3.5/GPT-4)
  - Claude (Anthropic)
  - Google Gemini
  - 通义千问 (Qianwen)
  - 文心一言 (Baidu)
  - Custom API | 自定义API

- ⚡ **Automatic Generation** | **自动生成**
  - Auto-generate summaries during `hexo generate`
  - 在 `hexo generate` 时自动生成摘要
  - Smart skip for existing summaries | 智能跳过已有摘要
  - Configurable exclusion rules | 可配置排除规则

- 🛠️ **Flexible Configuration** | **灵活配置**
  - Custom prompts | 自定义提示词
  - Batch processing with delays | 批量处理延迟控制
  - Retry mechanisms | 重试机制
  - Content filtering | 内容过滤

- 🎯 **High Performance** | **高性能**
  - Async processing | 异步处理
  - API rate limiting protection | API限流保护
  - Error handling with fallbacks | 错误处理与降级

## 📦 Installation | 安装

```bash
npm install hexo-ai-summary-pro --save
```

## ⚙️ Configuration | 配置

Add the following configuration to your `_config.yml`:

在你的 `_config.yml` 中添加以下配置：

### Basic Configuration | 基础配置

```yaml
ai_summary_api:
  enable: true                    # Enable AI summary | 启用AI摘要
  auto_generate: true             # Auto-generate during hexo generate | 自动生成
  provider: openai                # AI provider | AI服务商
  api_key: "your-api-key"         # API key | API密钥
  model: "gpt-3.5-turbo"          # Model name | 模型名称
  max_tokens: 150                 # Max tokens | 最大令牌数
  temperature: 0.3                # Generation temperature | 生成温度
```

### Provider-Specific Examples | 各服务商配置示例

#### OpenAI
```yaml
ai_summary_api:
  provider: openai
  api_key: "sk-your-openai-key"
  model: "gpt-3.5-turbo"
```

#### Claude
```yaml
ai_summary_api:
  provider: claude
  api_key: "your-claude-key"
  model: "claude-3-haiku-20240307"
```

#### Google Gemini
```yaml
ai_summary_api:
  provider: gemini
  api_key: "your-gemini-key"
  model: "gemini-pro"
```

#### Custom API | 自定义API
```yaml
ai_summary_api:
  provider: custom
  api_key: "your-api-key"
  api_url: "https://your-api-endpoint.com/v1/chat/completions"
  model: "your-model-name"
```

### Advanced Configuration | 高级配置

```yaml
ai_summary_api:
  enable: true
  auto_generate: true
  provider: openai
  api_key: "your-api-key"
  model: "gpt-3.5-turbo"
  max_tokens: 150
  temperature: 0.3
  timeout: 30000                  # Request timeout (ms) | 请求超时
  retry_count: 3                  # Retry attempts | 重试次数
  retry_delay: 1000               # Retry delay (ms) | 重试延迟
  batch_delay: 500                # Batch processing delay | 批量延迟
  min_content_length: 100         # Min content length | 最小内容长度
  
  # Custom prompt template | 自定义提示词模板
  prompt_template: |
    Please generate a concise summary for the following article in Chinese, within 150 characters:
    
    Title: {title}
    Content: {content}
  
  # Exclusion rules | 排除规则
  exclude_layouts:
    - page
    - about
    - links
  exclude_tags:
    - draft
    - private
  exclude_categories:
    - test
    - temp
  
  # Fallback summary | 默认摘要
  fallback_summary: "This article introduces relevant technical content with detailed implementation methods and practical examples."
```

## 🚀 Usage | 使用方法

### Automatic Generation | 自动生成 (Recommended | 推荐)

With `auto_generate: true`, summaries are automatically generated during site generation:

设置 `auto_generate: true` 后，摘要会在站点生成时自动创建：

```bash
hexo clean
hexo generate    # Summaries auto-generated here | 摘要在此自动生成
hexo server
```

### Manual Generation | 手动生成

```bash
# Generate summaries for all posts | 为所有文章生成摘要
hexo ai-summary

# Force regenerate all summaries | 强制重新生成所有摘要
hexo ai-summary --force

# Test API connection | 测试API连接
hexo ai-summary --test

# Use specific provider | 使用特定服务商
hexo ai-summary --provider openai
```

### Configuration Check | 配置检查

```bash
hexo ai-config
```

## 🎨 Theme Integration | 主题集成

### For Solitude Theme | Solitude主题

Enable AI display in `_config.solitude.yml`:

在 `_config.solitude.yml` 中启用AI显示：

```yaml
post:
  ai:
    enable: true
    modelName: AI Summary Assistant
```

### For Other Themes | 其他主题

Add to your post template:

在文章模板中添加：

```ejs
<% if (page.ai_text) { %>
  <div class="ai-summary">
    <h4>🤖 AI Summary</h4>
    <p><%- page.ai_text %></p>
  </div>
<% } %>
```

### Custom Styling | 自定义样式

```css
.ai-summary {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: 20px;
  border-radius: 10px;
  margin: 20px 0;
  box-shadow: 0 4px 15px rgba(0,0,0,0.1);
}

.ai-summary h4 {
  margin: 0 0 10px 0;
  font-size: 18px;
}

.ai-summary p {
  margin: 0;
  line-height: 1.6;
}
```

## 🔧 API Commands | API命令

| Command | Description | 命令说明 |
|---------|-------------|----------|
| `hexo ai-summary` | Generate summaries | 生成摘要 |
| `hexo ai-summary --test` | Test API connection | 测试API连接 |
| `hexo ai-summary --force` | Force regenerate | 强制重新生成 |
| `hexo ai-config` | Check configuration | 检查配置 |

## 🐛 Troubleshooting | 故障排除

### Common Issues | 常见问题

1. **API Connection Failed | API连接失败**
   ```bash
   hexo ai-summary --test
   ```
   Check API key and network connection | 检查API密钥和网络连接

2. **Summaries Not Generated | 摘要未生成**
   - Ensure `enable: true` and `auto_generate: true`
   - Check exclusion rules | 检查排除规则
   - Verify content length > `min_content_length`

3. **Rate Limiting | 频率限制**
   - Increase `batch_delay` value | 增加批量延迟
   - Reduce concurrent requests | 减少并发请求

### Debug Mode | 调试模式

```bash
DEBUG=hexo:* hexo generate
```

## 📊 Performance Tips | 性能建议

1. **Optimize Delays | 优化延迟**
   - Free APIs: `batch_delay: 1000-2000ms`
   - Paid APIs: `batch_delay: 200-500ms`

2. **Content Filtering | 内容过滤**
   - Set appropriate `min_content_length`
   - Use exclusion rules for drafts | 为草稿设置排除规则

3. **API Selection | API选择**
   - Speed: GPT-3.5-turbo, Claude-3-haiku
   - Quality: GPT-4, Claude-3-opus

## 📄 License | 许可证

MIT License

## 🤝 Contributing | 贡献

Contributions are welcome! Please feel free to submit a Pull Request.

欢迎贡献！请随时提交Pull Request。

## 📞 Support | 支持

- [GitHub Issues](https://github.com/yourusername/hexo-ai-summary-pro/issues)
- [Documentation](https://github.com/yourusername/hexo-ai-summary-pro#readme)

---

**Enjoy intelligent summaries for your Hexo blog! | 享受为你的Hexo博客带来的智能摘要！** 🎉