# article_writer_agent

**Repository Path**: scedm/article_writer_agent

## Basic Information

- **Project Name**: article_writer_agent
- **Description**: 基于 OpenAI 兼容 API 的单篇幅中文文章自动写作 CLI 工具。输入主题和参考链接，自动完成资料采集、大纲生成、确认交互、全文写作，最终输出 Markdown 文件。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Research Agent

基于 OpenAI 兼容 API 的单篇幅中文文章自动写作 CLI 工具。输入主题和参考链接，自动完成资料采集、大纲生成、确认交互、全文写作，最终输出 Markdown 文件。

## 功能特性

- **多参考链接** — 支持输入多个 URL，自动抓取正文内容作为写作素材
- **网络搜索补充** — 基于主题自动搜索补充背景资料（DuckDuckGo / Tavily / Serper）
- **大纲生成 + 确认** — LLM 生成结构化大纲，用户可确认、编辑、或重新生成
- **流式写作** — 逐小节流式输出，实时查看写作进度
- **小节连贯性** — 每节写完后生成摘要传入下一节，保持全文连贯
- **可选润色** — 写作完成后可一键调用 LLM 润色优化
- **多模型支持** — 通过 OpenAI 兼容接口接入 GPT、Claude、Ollama 等任意后端

## 工作流程

```
用户输入 (主题 + 多个参考链接)
       ↓
  1. 资料采集
     ├─ 抓取所有参考链接正文 (readability-lxml 提取)
     ├─ 基于主题搜索补充资料 (DuckDuckGo)
     └─ LLM 综合为结构化研究摘要
       ↓
  2. 生成大纲
     └─ LLM 生成标题 + 小节 + 关键点 + 预估字数
       ↓
  3. 大纲确认 (交互循环)
     ├─ [A] 确认 → 开始写作
     ├─ [E] 编辑器修改 ($EDITOR)
     ├─ [I] 交互式逐项编辑
     ├─ [R] 重新生成
     └─ [Q] 退出
       ↓
  4. 逐小节写作 (流式输出)
     └─ 每节传入研究摘要 + 前文摘要，保持连贯
       ↓
  5. 输出 Markdown 文件 (带 YAML front matter)
```

## 安装

**环境要求**: Python 3.10+

建议使用虚拟环境隔离依赖，避免与系统或其他项目的 Python 包产生冲突。

```bash
git clone https://gitee.com/scedm/article_writer_agent.git article_writer_agent
cd article_writer_agent

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS / Linux:
source venv/bin/activate
# Windows:
# venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt
```

后续每次使用前，先激活虚拟环境：

```bash
source venv/bin/activate   # macOS / Linux
# venv\Scripts\activate    # Windows
```

## 快速开始

### 1. 设置 API Key

```bash
export OPENAI_API_KEY="sk-your-api-key"
```

### 2. 运行

```bash
# 交互式（逐步输入主题、链接、风格、字数）
python main.py

# 仅用参考链接（不搜索）
python main.py -t "Ollama + Gemma4 实现本地大模型安装" -s "技术实战教程" \
  -u https://docs.ollama.com/ https://docs.ollama.com/integrations/claude-code

# 无链接，自动搜索
python main.py -t "AI Agent 架构设计" -s "深度分析" -l 5000

# 参考链接 + 强制搜索
python main.py -t "AI Agent 架构设计" -u https://example.com/1 --search -s "深度分析" -l 5000
```

### 3. 命令行参数

| 参数          | 缩写 | 说明                                   |
| ------------- | ---- | -------------------------------------- |
| `--topic`     | `-t` | 文章主题                               |
| `--urls`      | `-u` | 参考链接 URL，支持多个（空格分隔）     |
| `--style`     | `-s` | 写作风格，默认"深度分析"               |
| `--length`    | `-l` | 目标字数，默认 4000                    |
| `--output`    | `-o` | 输出文件路径                           |
| `--config`    | `-c` | 自定义配置文件路径                     |
| `--verbose`   | `-v` | 显示详细日志                           |
| `--no-search` |      | 跳过网络搜索，仅使用参考链接           |
| `--search`    |      | 强制启用网络搜索（即使提供了参考链接） |

### 搜索策略

| 场景              | 命令                    | 行为                |
| ----------------- | ----------------------- | ------------------- |
| 提供链接          | `-u url1 url2`          | 仅抓取链接，不搜索  |
| 提供链接+强制搜索 | `-u url1 url2 --search` | 链接 + 网络搜索补充 |
| 无链接            | `-t "主题"`             | 网络搜索补充资料    |
| 无链接+不搜索     | `-t "主题" --no-search` | 纯 LLM 基于主题生成 |

## 切换 LLM 后端

通过环境变量 `OPENAI_BASE_URL` 和 `OPENAI_MODEL` 切换不同的模型后端：

**OpenAI GPT-4o（默认）**

```bash
export OPENAI_API_KEY="sk-xxx"
python main.py -t "主题"
```

**Claude（通过 OpenRouter）**

```bash
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="or-xxx"
export OPENAI_MODEL="anthropic/claude-sonnet-4-20250514"
python main.py -t "主题"
```

**本地 Ollama**

```bash
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_API_KEY="ollama"
export OPENAI_MODEL="llama3"
python main.py -t "主题"
```

**Claude（通过官方代理）**

```bash
export OPENAI_BASE_URL="https://your-proxy.com/v1"
export OPENAI_API_KEY="your-key"
export OPENAI_MODEL="claude-sonnet-4-20250514"
python main.py -t "主题"
```

## 配置说明

配置文件位于 `config/settings.yml`，支持以下配置项：

### LLM 配置

```yaml
llm:
  api_key_env: "OPENAI_API_KEY" # API Key 环境变量名
  base_url_env: "OPENAI_BASE_URL" # Base URL 环境变量名
  default_base_url: "https://api.openai.com/v1"
  model: "gpt-4o" # 默认模型
  temperature: 0.7 # 默认温度
  max_tokens: 4096 # 默认最大 token
  timeout: 180 # 请求超时（秒）
  max_retries: 3 # 最大重试次数

  # 步骤级配置（覆盖默认值）
  steps:
    research_synthesis: { temperature: 0.5, max_tokens: 4096 }
    outline_generation: { temperature: 0.6, max_tokens: 4096 }
    section_writing: { temperature: 0.7, max_tokens: 8192 }
    article_polish: { temperature: 0.3, max_tokens: 4096 }
```

### 搜索配置

```yaml
search:
  provider: "duckduckgo" # 搜索引擎: duckduckgo / tavily / serper
  max_results: 8 # 搜索结果数量
  fetch_top_n: 5 # 抓取前 N 个结果的全文
  language: "zh-CN"
```

### 文章默认配置

```yaml
article:
  language: "zh"
  default_target_length: 4000 # 默认字数
  min_target_length: 1500
  max_target_length: 10000
  default_style: "深度分析" # 默认风格
```

### 上下文截断

```yaml
context:
  max_research_chars: 60000 # 研究资料最大字符数
  max_url_content_chars: 8000 # 单个 URL 内容截断
  section_context_chars: 2000 # 前文摘要最大字符数
```

## 环境变量

| 变量                    | 必需 | 说明                            |
| ----------------------- | ---- | ------------------------------- |
| `OPENAI_API_KEY`        | 是   | LLM API 密钥                    |
| `OPENAI_BASE_URL`       | 否   | 自定义 API 地址（切换模型后端） |
| `OPENAI_MODEL`          | 否   | 运行时覆盖默认模型              |
| `RESEARCH_AGENT_CONFIG` | 否   | 自定义配置文件路径              |
| `TAVILY_API_KEY`        | 否   | Tavily 搜索 API Key             |
| `SERPER_API_KEY`        | 否   | Serper 搜索 API Key             |
| `BRAVE_SEARCH_API_KEY`  | 否   | Brave 搜索 API Key              |

## 项目结构

```
article_writer_agent/
├── main.py                          # CLI 入口
├── requirements.txt                 # Python 依赖
├── CLAUDE.md                        # Claude Code 项目指引
├── config/
│   ├── settings.yml                 # 全局配置
│   └── prompts/                     # Prompt 模板
│       ├── research_synthesis.txt   #   研究资料综合
│       ├── outline_generation.txt   #   大纲生成
│       ├── section_writing.txt      #   小节写作
│       └── article_polish.txt       #   文章润色
├── src/                             # 核心源码
│   ├── __init__.py
│   ├── config_loader.py             #   配置加载（YAML + 环境变量）
│   ├── llm_client.py                #   OpenAI 兼容 LLM 客户端
│   ├── web_fetcher.py               #   网页抓取 + 多搜索引擎
│   ├── pipeline.py                  #   文章写作流水线
│   ├── outline_parser.py            #   大纲 Markdown ↔ 结构化解析
│   └── prompts.py                   #   Prompt 模板管理
├── cli/                             # CLI 交互模块
│   ├── __init__.py
│   ├── app.py                       #   主应用（交互流程控制）
│   ├── display.py                   #   rich 终端渲染
│   └── editor.py                    #   大纲编辑器
└── output/                          # 文章输出目录
```

## 输出示例

生成的 Markdown 文件包含 YAML front matter：

```markdown
---
title: "AI Agent 架构设计"
date: "2026-05-08"
word_count: 4235
sections: 5
model: "gpt-4o"
---

# AI Agent 架构设计

## 引言

...
```

## 自定义 Prompt 模板

所有 Prompt 模板位于 `config/prompts/` 目录，可直接编辑：

- `research_synthesis.txt` — 研究资料综合提示词
- `outline_generation.txt` — 大纲生成提示词
- `section_writing.txt` — 小节写作提示词
- `article_polish.txt` — 文章润色提示词

## License

MIT



claude --dangerously-skip-permissions -p "/ralph-loop:ralph-loop '实现Agent编写文章的功能。

需求：
- 严格按照 2026-05-08-react-agent-design.md 文件执行

成功标准：
- 所有需求已实现
- 测试通过，覆盖率 >80%
- 无代码检查错误
- 文档已更新
完成后输出 <promise>COMPLETE</promise>。' --max-iterations 30"