# write_blog_agent

**Repository Path**: tujiaw/write_blog_agent

## Basic Information

- **Project Name**: write_blog_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-01-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Blog Writing and Publishing Agent

基于 LangChain 和 DeepSeek 的自动博客写作和发布 Agent，能够生成符合 MDX 格式的技术博客文章并发布到 GitHub 仓库。

## 功能特性

- 🤖 **AI 驱动**: 使用 DeepSeek LLM 生成高质量技术文章
- 📝 **MDX 格式**: 完全兼容 MDX 语法，包含 frontmatter
- ✅ **格式验证**: 自动验证文章格式和语法
- 🏷️ **智能标签**: AI 自动生成相关标签
- 📊 **摘要生成**: 自动生成文章摘要
- 🚀 **GitHub 发布**: 支持 GitHub MCP 发布到仓库

## 项目结构

```
write_blog_agent/
├── .env                    # 环境变量配置
├── .env.example           # 环境变量模板
├── requirements.txt       # Python 依赖
├── agent.py              # 主程序入口
├── tools.py              # LangChain 工具定义
├── prompts.py            # 文章生成提示词
├── utils.py              # 工具函数
└── README.md             # 本文档
```

## 安装步骤

### 1. 安装 Python 3.12

```bash
# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev

# 验证安装
python3.12 --version
```

### 2. 创建虚拟环境

```bash
# 使用 Python 3.12 创建虚拟环境
python3.12 -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows
```

### 3. 安装依赖

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

### 4. 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API Keys
nano .env  # 或使用你喜欢的编辑器
```

必需的环境变量：

```env
# DeepSeek API
DEEPSEEK_API_KEY=your_deepseek_api_key_here
DEEPSEEK_BASE_URL=https://api.deepseek.com

# GitHub
GITHUB_TOKEN=your_github_token_here
GITHUB_REPO=tujiaw/nextjs-blog-deploy
GITHUB_BRANCH=main

# GitHub MCP Server（使用远程服务器，推荐）
GITHUB_MCP_URL=https://api.githubcopilot.com/mcp/
GITHUB_MCP_TRANSPORT=streamable_http
```

**注意：** `GITHUB_MCP_URL` 如果设置为非 HTTP URL（如 Docker 镜像名），会自动使用默认的远程服务器 `https://api.githubcopilot.com/mcp/`。

## 使用方法

### 基本用法

```bash
# 基本用法 - 提供文章主题
python agent.py --prompt "如何使用LangChain构建AI应用"

# 提供详细信息 - 主题、背景、要求
python agent.py --prompt "写一篇关于Python异步编程的文章。
  目标读者：Python中级开发者
  要求：包含asyncio实际代码示例，解释异步编程的优势
  参考：https://docs.python.org/3/library/asyncio.html"

# 提供参考资料
python agent.py --prompt "根据这篇文章 https://example.com/article 
  写一篇关于微服务架构的总结，加入自己的见解"
```

## 命令行参数

| 参数 | 简写 | 说明 |
|------|------|------|
| `--prompt` | `-p` | 文章生成提示，可以包含主题、参考资料、背景信息、写作要求等任何相关信息 |

## 文章格式

生成的文章符合 MDX 格式规范：

```mdx
---
title: "文章标题"
date: 2026-01-22
tags: ["AI", "Python", "LangChain"]
summary: "文章摘要，1-2句话概括核心内容"
draft: false
---

文章正文内容...

## 一级标题

内容...
```

## 发布到 GitHub

Agent 使用 `publish_to_github` 工具自动将文章发布到 GitHub 仓库。工具会：

1. 解析文章内容，提取元数据（标题、日期等）
2. 生成文件路径：`data/blog/{year}/{date}-{slug}.mdx`
3. 生成提交消息：`Add new blog post: {title}`
4. 将内容编码为 base64
5. 通过 GitHub MCP Server 直接发布到仓库

**发布配置：**
- 使用远程 GitHub MCP Server：`https://api.githubcopilot.com/mcp/`
- 通过 `Authorization: Bearer {GITHUB_TOKEN}` header 进行认证
- 自动调用 `create_or_update_file` 工具完成发布

**发布结果：**
- 文件会创建在指定的 GitHub 仓库中
- 提交信息包含文章标题
- 返回 GitHub API 响应，包含文件 URL 和 commit SHA

## Agent 工作流程

1. **接收提示** - 从命令行获取用户提示（可包含主题、参考资料、背景信息等）
2. **生成文章** - 使用 `write_article` 工具调用 DeepSeek LLM 生成 MDX 格式文章
3. **验证格式** - 自动检查 frontmatter 和内容格式
4. **保存本地** - 自动保存到 `articles/` 目录
5. **发布到 GitHub** - 使用 `publish_article` 工具通过 GitHub MCP Server 直接发布到仓库

## 开发

### 项目依赖

- **langchain**: LLM 应用框架
- **langchain-openai**: OpenAI 兼容 API（用于 DeepSeek）
- **python-dotenv**: 环境变量管理
- **python-frontmatter**: Frontmatter 解析
- **mcp**: MCP 服务器集成

### 代码结构

- `agent.py`: 主程序，Agent 执行器和 CLI
- `tools.py`: LangChain 工具定义（`write_article`, `publish_article`）
- `prompts.py`: 提示词模板
- `utils.py`: 辅助函数（验证、格式化等）

## 故障排除

### 环境变量未设置

```
错误: 缺少必需的环境变量: DEEPSEEK_API_KEY
```

**解决**: 创建 `.env` 文件并设置所有必需的环境变量。

### Python 版本不匹配

```
错误: 需要Python 3.10+
```

**解决**: 使用 Python 3.12 创建虚拟环境。

### MDX 格式验证失败

```
错误: Missing required frontmatter fields: tags
```

**解决**: 检查生成的文章，确保 frontmatter 包含所有必需字段。

## 示例

### 示例 1: 简单主题

```bash
python agent.py --prompt "Claude 3.5 Sonnet 最新特性介绍"
```

### 示例 2: 包含要求和参考资料

```bash
python agent.py --prompt "写一篇关于 Claude 3.5 Sonnet 的文章。

主题：Claude 3.5 Sonnet 最新特性介绍
要求：
- 包含 API 使用的代码示例
- 重点介绍多模态能力
- 对比与前代模型的差异
- 适合开发者阅读

参考资料：
- https://www.anthropic.com/news/claude-3-5-sonnet
- https://docs.anthropic.com/claude/docs/intro-to-claude"
```

输出：

```
============================================================
开始生成文章...
用户提示: 写一篇关于 Claude 3.5 Sonnet 的文章...
============================================================

> Entering new AgentExecutor chain...
...
✓ 文章已生成并保存到: articles/2026-01-22-claude-35-sonnet-latest-features.mdx
✓ 文章已成功发布到GitHub
============================================================
任务完成！
============================================================
```

## License

MIT

## 贡献

欢迎提交 Issue 和 Pull Request！