Toutiao Publisher

# Toutiao Publisher Skill

Manage Toutiao (Today's Headlines) account, maintain persistent login session, and publish articles.

## When to Use This Skill

Trigger when user:
- Asks to publish to Toutiao/Today's Headlines
- Wants to manage Toutiao login
- Mentions "toutiao" or "头条号"

## Core Workflow

### Step 1: Authentication (One-Time Setup)

The skill requires a one-time login. The session is persisted for subsequent uses.

```bash
# Browser will open for manual login (scan QR code)
python scripts/run.py auth_manager.py setup
```

**Instructions:**
1.  Run the setup command.
2.  A browser window will open loading the Toutiao login page.
3.  Log in manually (e.g., scan QR code).
4.  Once logged in (redirected to dashboard), the script will save the session and close.

### Step 2: Publish Article

```bash
# Opens browser with authenticated session at publish page
python scripts/run.py publisher.py
```

**Instructions:**
1.  Run the publisher command.
2.  Browser opens directly to the "Publish Article" page.
3.  Write and publish the article manually.
4.  Press `Ctrl+C` in the terminal when done.

> **Note:** Toutiao requires titles to be **2-30 characters**. This tool automatically optimizes titles to fit this constraint (truncating if >30, padding if <2).

#### Advanced Usage (Automated)

You can fully automate the publishing process by providing arguments:

```bash
# Publish with title, content file, and cover image
python scripts/run.py publisher.py --title "AI Trends 2025" --content "article.md" --cover "assets/cover.jpg" --headless
```



### Management

```bash
# Check authentication status
python scripts/run.py auth_manager.py status

# Clear authentication data (logout)
python scripts/run.py auth_manager.py clear
```

## Technical Details

- **Persistent Auth**: Uses `patchright` to launch a persistent browser context. Cookies and storage state are saved to `data/browser_state/state.json`.
- **Anti-Detection**: Uses `patchright`'s stealth features to avoid bot detection.
- **Environment**: Automatically manages a virtual environment (`.venv`) with required dependencies.

## Script Reference

- `scripts/auth_manager.py`: Handles login, session validation, and state persistence.
- `scripts/publisher.py`: Launches authenticated browser for publishing.
- `scripts/run.py`: Wrapper ensuring execution in the correct virtual environment.


# Toutiao Publisher Skill 架构与最佳实践指南

## 1. 架构原理 (Architecture)

Toutiao Publisher 是一个基于 **Playwright** 的自动化发布工具，旨在解决头条号及其复杂的富文本编辑器交互问题。其核心设计理念是 **"模拟真实用户行为" (User Simulation)** 而非简单的 API 调用。

### 1.1 核心组件

*   **`publisher.py` (核心执行器)**
    *   作为主入口，负责编排整个发布流程。
    *   **智能填充**：针对 ProseMirror 编辑器，采用多级降级策略（`execCommand` > `ClipboardEvent`）确保内容注入成功。
    *   **封面自动化**：实现了文件上传控件（`input[type=file]`）的精准定位与交互，支持本地图片上传。
    *   **双重发布确认**：模拟“点击发布 -> 等待弹窗 -> 点击确认”的完整链路。
    *   **即时登录 (Login-on-the-fly)**：不再依赖分离的登录脚本，发布时若检测到未登录，自动暂停等待用户扫码，实现无缝衔接。

*   **`auth_manager.py` (凭证管理)**
    *   负责 Cookie 和 LocalStorage 的持久化。
    *   通过 `state.json` 实现免登录复用。
    *   包含自动检测 Cookie 有效性的逻辑。

*   **`browser_utils.py` (环境工厂)**
    *   配置反爬虫策略（Anti-detection）。
    *   管理持久化浏览器上下文（Persistent Context），确保 UserDataDir 的正确复用。

### 1.2 关键技术点

*   **混合输入模式**：对于标题使用标准 `fill`，对于正文使用 JS 注入，对于封面使用 `setInputFiles`。
*   **鲁棒性设计**：
    *   **Autosave 触发器**：注入内容后自动输入空格触发编辑器保存机制。
    *   **动态等待**：从不使用固定 `sleep`，而是基于 `wait_for_selector` 和状态轮询。
*   **调试友好**：关键步骤自动截图（Debug Screenshots），便于排查无头模式下的问题。

---

## 2. 最佳实践 (Best Practices)

### 2.1 自动化发布 (Automated Publishing)

最推荐的使用方式是通过命令行进行全自动发布。

```bash
# 标准发布命令（推荐）
python scripts/run.py publisher.py \
  --title "你的标题（2-30字）" \
  --content "/absolute/path/to/article.md" \
  --cover "/absolute/path/to/cover.png"
```

*   **参数说明**：
    *   `--title`: 必填。脚本会自动截断超长标题。
    *   `--c