Metadata-Version: 2.4
Name: blog-pro-max
Version: 1.0.9
Summary: 自動化 SEO 內容創作與部落格文章生成工具
License: MIT
Project-URL: Homepage, https://github.com/max32002/blog-pro-max
Project-URL: Repository, https://github.com/max32002/blog-pro-max
Project-URL: Bug-Tracker, https://github.com/max32002/blog-pro-max/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: Markdown>=3.5.0
Requires-Dist: Pygments>=2.17.0
Dynamic: license-file

# blog-pro-max

自動化 SEO 內容創作與部落格文章生成工具。支援一鍵將寫作 Skill 注入到 18 種 AI 編輯器與 Assistant。

## 功能亮點

- **AI 驅動寫作**：根據關鍵字自動進行內容研究並生成 SEO 最佳化的部落格文章。
- **品牌風格一致性**：自動套用品牌寫作風格規範（`writing-style.md`）。
- **內建風格檢查器**：自動驗證產出內容是否符合排版與語氣規範。
- **多樣化模板**：支援多種寫作風格（SEO 專業 / Max 個人風格 / FB 貼文 / LINE 訊息）。
- **三維度審稿專家**：邏輯與事實、深度與結構、讀者視角三位專家自動審查，附問題點與修改前後對比。
- **時事趨勢專家**：分析文章與當前時事的關聯，提供切入角度、高流量關鍵字/Hashtag、內容改寫示範。
- **標題專家**：自動產出 4 個風格不同的標題建議（含英文 WordPress permalink），附加到輸出檔案供人工選擇。
- **封面提示詞專家**：自動產出 3 組 AI 繪圖提示詞（Midjourney / DALL-E / Stable Diffusion），附加到輸出檔案。
- **AI Skill 注入**：一鍵將 Prompt 與工具鏈注入到 Claude Code, Cursor, GitHub Copilot 等 18 種平台。
- **自動格式轉換**：內建 Markdown 轉 HTML 引擎，支援代碼高亮與 SEO 優化排版。

---

## 快速開始（5 分鐘上手）

### Step 1：安裝

**從 PyPI 安裝（推薦使用者）**

```bash
pip install blog-pro-max
```

安裝後您將獲得 `blogpro` 全域指令。

**從 GitHub 安裝（開發者）**

```bash
git clone https://github.com/max32002/blog-pro-max.git
cd blog-pro-max
pip install -e .
```

### Step 2：設定 API 金鑰（僅 Script Mode 需要）

> **💡 如果你只使用 Skill Mode（透過 AI Assistant 生成文章），可跳過此步驟。**
> AI Assistant 使用自己內建的 LLM 能力，不需要額外的 API 金鑰。
>
> 只有在直接執行 Python 腳本（Script Mode）時，才需要設定 API 金鑰。

在您的工作目錄建立 `.env` 檔案：

```bash
# 推薦：GitHub PAT（免費，不需 OpenAI 帳號）
GITHUB_TOKEN=ghp_your-token-here

# 或：OpenAI API Key
OPENAI_API_KEY=sk-your-key-here
```

### Step 3：注入 Skill 到您的 AI Assistant

```bash
blogpro init --ai claude      # 針對 Claude Code
blogpro init --ai copilot     # 針對 GitHub Copilot
blogpro init --ai cursor      # 針對 Cursor
blogpro init --ai all         # 注入到所有支援的平台
```

### Step 4：開始創作

在已注入 Skill 的 AI Assistant 中直接輸入：

```
/blog-pro-max 寫一篇[AI 寫作工具]文章,受眾[內容行銷人員],以專業SEO風格
```

---

## AI Assistant 整合支援

`blog-pro-max` 支援將寫作能力無縫整合進 **18 個** AI 助手平台：

| 分類 | 平台 | `--ai` 參數 |
|------|------|-------------|
| **專業開發工具** | Claude Code | `claude` |
| | Cursor | `cursor` |
| | Windsurf | `windsurf` |
| | Trae | `trae` |
| | Roo Code | `roo` |
| **擴充套件** | GitHub Copilot | `copilot` |
| | Continue | `continue` |
| | CodeBuddy | `codebuddy` |
| | OpenCode | `opencode` |
| | Augment | `augment` |
| **終端機 / CLI** | Gemini CLI | `gemini` |
| | Codex CLI | `codex` |
| | Warp | `warp` |
| **新興 Agent** | Antigravity | `antigravity` |
| | Kiro | `kiro` |
| | Qoder | `qoder` |
| | Droid (Factory) | `droid` |
| | KiloCode | `kilocode` |

### 全域安裝（適用於電腦上所有專案）

```bash
blogpro init --ai all --global
```

---

## 使用方式

> **API 金鑰需求一覽：**
>
> | 模式 | 需要 API 金鑰？ | 說明 |
> |------|----------------|------|
> | Skill Mode | ❌ 不需要 | AI Assistant 用自己的 LLM 生成 |
> | Workflow Mode | ❌ 不需要 | 同上 |
> | Script Mode | ✅ 需要 | Python 腳本直接呼叫 OpenAI / GitHub Models |

### Skill Mode（自動啟動）

**支援平台：** Claude Code, Cursor, Windsurf, Antigravity, Codex CLI, Continue, Gemini CLI, OpenCode, Qoder, CodeBuddy, Droid (Factory), KiloCode, Warp, Augment

安裝 Skill 後，AI Assistant 會**自動讀取** SKILL.md，您只需用自然語言下達指令：

```
幫我寫一篇關於「遠端工作生產力」的 SEO 文章，目標讀者是科技業上班族
```

或是先貼上參考資料，再要求 AI 根據這些資料生成文章：

```
以下是我收集的資料：
[貼上你的資料]

請根據以上資料，用標準模板寫一篇文章，受眾是一般讀者。
```

```
用 Max 的風格寫一篇「失去才懂珍惜」的心情筆記
```

```
幫我寫一篇「時間管理」的 Facebook 貼文，受眾是上班族
```

```
用 LINE 訊息風格分享一篇「讀書心得」，讓朋友看得輕鬆
```

```
檢查 output/my-article.md 的寫作風格
```

#### Skill Mode 輸出行為

依 AI 平台能力分兩種模式：

| AI 類型 | 範例平台 | 輸出方式 |
|---------|----------|----------|
| **可執行腳本** | Claude Code, Cursor, Windsurf | 執行 Python 腳本，自動產出 `.md` + `.html` 檔案 |
| **純 LLM 生成** | Gemini CLI, 一般聊天模式 | 直接生成文字輸出，詢問是否存檔為 `.md` |

兩種模式都會完整輸出：
- 文章本文（依選定模板格式）
- `## 📝 推薦標題選項`（4 個標題 + WordPress permalink）
- `## 🎨 推薦封面提示詞`（3 組 AI 繪圖 prompt）

### Workflow Mode（斜線命令）

**支援平台：** Kiro, GitHub Copilot, Roo Code, KiloCode

使用斜線命令精確控制生成參數：

```
/blog-pro-max 寫一篇[遠端工作生產力]文章,受眾[科技業上班族],以專業SEO風格
```

```
/blog-pro-max 寫一篇[失去才懂珍惜]文章,受眾[一般讀者],以作家Max風格
```

```
/blog-pro-max 寫一篇[時間管理心得]文章,受眾[上班族],以FB風格
```

```
/blog-pro-max 寫一篇[讀書心得分享]文章,受眾[大學生],以LINE風格
```

```
/blog-pro-max 寫一篇[Python 入門指南]文章,受眾[程式初學者],字數[2000]
```

#### 斜線命令解析規則

| 語法 | 對應參數 | 範例 |
|------|----------|------|
| `[關鍵字]`（第一個方括號） | `--keyword` | `[遠端工作生產力]` |
| `受眾[值]` | `--audience` | `受眾[科技業上班族]` |
| `字數[N]` | `--word-count` | `字數[2000]` |
| `作家Max風格` / `心情筆記` | `--template max-personal-style` | |
| `SEO風格` / `專業風格` / `部落格風格` | `--template blog-skill-content` | |
| `FB風格` / `Facebook風格` / `臉書風格` | `--template fb-post-style` | |
| `LINE風格` / `LINE訊息` / `賴風格` | `--template line-message-style` | |
| `幫我取標題 <路徑>` | 呼叫標題專家 | `幫我取標題 output/article.md` |
| `幫我生成封面 <路徑>` | 呼叫封面提示詞專家 | `幫我生成封面 output/article.md` |
| `全科檢查 <路徑>` | 三位專家全面審查 | `全科檢查 output/article.md` |
| `檢查邏輯 <路徑>` | 邏輯與事實專家 | `檢查邏輯 output/article.md` |
| `檢查結構 <路徑>` | 深度與結構專家 | `檢查結構 output/article.md` |
| `檢查讀者 <路徑>` | 讀者視角專家 | `檢查讀者 output/article.md` |
| `分析趨勢 <路徑>` | 時事趨勢專家 | `分析趨勢 output/article.md` |
| `檢查風格 <路徑>` | 執行 style_checker | `檢查風格 output/article.md` |
| `列出模板` | 列出可用模板 | |
| `專案狀態` | 顯示專案狀態報告 | |

### Script Mode（直接執行）

不透過 AI Assistant，直接在終端機執行：

```bash
# 生成文章
python -m blog_pro_max.content_research --keyword "Python 基礎教學" --template blog-skill-content

# 關鍵字太長？從檔案讀取（兩種方式皆可）
python -m blog_pro_max.content_research --keyword @topic.txt
python -m blog_pro_max.content_research --keyword-file topic.txt

# 只看 prompt（不呼叫 API）
python -m blog_pro_max.content_research --keyword "Python 基礎教學" --dry-run

# 檢查現有 Markdown 檔案風格
python -m blog_pro_max.content_research --keyword "Python" --check-only output/my-article.md
```

---

## CLI 指令參考

### 初始化與管理
- `blogpro init`: 偵測環境並注入 Skill 檔案。
- `blogpro uninstall`: 移除已注入的 Skill。
- `blogpro versions`: 檢查版本與已安裝的平台狀態。
- `blogpro update`: 同步更新所有平台的 Skill 檔案至最新版。

---

## 生成 Pipeline

文章生成時會自動執行完整 pipeline：

```
文章生成 → 風格檢查 → 三維度審稿(邏輯/結構/讀者) → 時事趨勢分析 → 標題建議(4個+permalink) → 封面提示詞(3組) → MD→HTML
```

每個步驟的失敗不會阻擋後續步驟。最終輸出的 `.md` 和 `.html` 包含：
- 文章本文
- 三維度審稿報告（含問題點、修改建議、修改前後對比）
- 時事趨勢報告（趨勢關聯、切入角度、關鍵字/Hashtag、改寫示範）
- 推薦標題選項（含英文 WordPress permalink）
- 推薦封面 AI 繪圖提示詞

### 內部角色

| 角色 | 觸發方式 | 說明 |
|------|----------|------|
| **🔬 邏輯與事實專家** | 自動 / `檢查邏輯` / `全科檢查` | 數據正確性、邏輯一致性、錯別字、AI 幻覺偵測 |
| **📐 深度與結構專家** | 自動 / `檢查結構` / `全科檢查` | 遺漏面向、段落轉折、論述深度、結構平衡 |
| **👁️ 讀者視角專家** | 自動 / `檢查讀者` / `全科檢查` | 口吻適配、易讀性、注意力留存、情感共鳴 |
| **📰 時事趨勢專家** | 自動 / `分析趨勢` | 趨勢關聯分析、切入角度、關鍵字/Hashtag、改寫示範 |
| **📝 部落格標題專家** | 自動 / `幫我取標題` | 產出 4 個風格標題（直述、提問、數字、情感）+ 英文 permalink slug |
| **🎨 封面提示詞專家** | 自動 / `幫我生成封面` | 產出 3 組 AI 繪圖 prompt（寫實攝影、插畫、極簡設計） |

---

## 參數說明

| 參數 | 說明 | 預設值 |
|---|---|---|
| `--keyword` | 核心關鍵字，或 `@檔案路徑` 從檔案讀取 | — |
| `--keyword-file` | 從指定檔案讀取關鍵字（替代 `--keyword`） | — |
| `--audience` | 目標讀者（如：初學者、資深工程師） | 30-45 歲知識工作者 |
| `--word-count` | 目標字數 | 1200 |
| `--template` | 寫作風格模板 (`blog-skill-content` / `max-personal-style` / `fb-post-style` / `line-message-style`) | blog-skill-content |
| `--check-only` | 僅對指定檔案執行風格檢查 | — |
| `--dry-run` | 顯示 prompt 但不呼叫 API | — |
| `--model` | OpenAI 模型名稱 | gpt-4o |
| `--output` | 自訂輸出路徑 | `output/{keyword}.md` |

> **💡 提示**：`--keyword` 和 `--keyword-file` 二擇一，至少提供一個。當關鍵字很長（如完整的文章主題描述），建議寫入檔案後使用 `@` 語法讀取。

---

## 授權
本專案採用 [MIT License](LICENSE) 授權。
歡迎提交 Issue 或 Pull Request 參與貢獻！

---

## 📚 延伸文件

| 文件 | 說明 |
|------|------|
| [docs/architecture.md](docs/architecture.md) | **系統架構說明**：模組職責分工、目錄結構、完整生成 Pipeline 流程圖、函式參考表，適合想深入了解工具內部運作的開發者閱讀 |
| [docs/scripts-reference.md](docs/scripts-reference.md) | **腳本完整參考手冊**：6 個腳本的所有函式簽名、參數說明、回傳格式範例、獨立使用情境與範例指令，以及 Skill Mode 斜線命令速查表 |
| [docs/faq.md](docs/faq.md) | **常見問題 FAQ**：25+ 個 Q&A，涵蓋安裝設定、API 金鑰選擇、Skill 注入、各專家功能說明、輸出格式、疑難排解等 |
