# softwarer-csdn

**Repository Path**: queue001/softwarer-csdn

## Basic Information

- **Project Name**: softwarer-csdn
- **Description**: 基于 Playwright + PyQt6 的 CSDN 自动化助手：批量回访点赞/收藏/评论、回复私信、清未读角标，SQLite 记录已互动文章自动顺延，不重复操作。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CSDN Mutual Engagement Assistant

Automates the "mutual engagement" (互三) routine of CSDN follower groups with a real browser driven by Playwright: open a blogger's home page → like + favorite + comment on an article → reply to their direct message. A SQLite database records every engaged article so nothing is done twice. Ships with a PyQt6 GUI — click buttons and watch the live log — while every feature is also available from the command line.

> 互三 (hù sān) is CSDN community slang: like, favorite and comment on someone's article, and they return the favor.

## Features

- **QR login**: grabs the WeChat QR code from the CSDN login page; after scanning, the session is persisted in a local browser profile (`.csdn-browser-profile/`) so all later runs skip login
- **Batch visit**: reads message-center contacts (uid parsed from avatars, system accounts excluded) → opens the blogger's home page → picks the **first article not yet engaged** → like, favorite (first folder), comment with 《article title》 + text → replies "已学习" (already studied) to the DM; opening the conversation also clears the red unread badge
- **Dedup**: `data/csdn.db` (SQLite) tracks like/favorite/comment state per article; engaged articles are skipped and the next one is picked; only the last 30 days are blocked, so old articles can be revisited later
- **Unread badges**: open each unread conversation (a click alone clears the badge) — by nickname or all at once, optionally with a reply
- **GUI**: function cards + parameters on the left, live subprocess log on the right, progress bar and stop button at the bottom; frameless custom title bar in a muted blue-gray theme

## Requirements

- Python 3.12+ (developed on Windows; the CLI part is cross-platform)
- Chromium (installed via Playwright)

## Installation

```bash
# Option 1: uv (recommended, uv.lock included)
uv sync
uv run playwright install chromium

# Option 2: pip
pip install playwright PyQt6
playwright install chromium
```

## Quick Start

```bash
# 1. First run: scan the QR code (waits 10 minutes, see --minutes)
python -m csdn.login

# 2. Verify the saved session
python -m csdn.check_login

# 3. Run a small batch
python -m csdn.batch --limit 5
```

Or use the GUI:

```bash
python main.py        # same as python -m csdn.gui
```

GUI buttons map 1:1 to the CLI commands: Account (open home / QR login / check login), Message Center (open / clear badges / list contacts), Batch (all unread / first N / reply-only), Engagement records (stats / recent 20 / import history). The "Parameters" card holds the comment/DM text and the include-title toggle.

## Command Reference

| Command | Purpose |
|---|---|
| `python -m csdn.open [--url URL] [--headless]` | Open the CSDN home page or any URL |
| `python -m csdn.login [--minutes 10]` | QR login, saves the session |
| `python -m csdn.check_login` | Check the local session (no login flow) |
| `python -m csdn.messages [--headless]` | Open the message center and list content |
| `python -m csdn.batch --list` | List contacts only, no actions |
| `python -m csdn.batch --limit 5` | Process contacts 1–5 |
| `python -m csdn.batch --start 1 --limit 10` | Process 10 contacts starting at #2 |
| `python -m csdn.batch --all-unread` | Process everyone with unread > 0 |
| `python -m csdn.batch --reply-only` | Reply to DMs / clear badges only, no article actions |
| `python -m csdn.batch --text TEXT [--no-title]` | Custom comment/DM text (default 已学习); comments include the 《title》 by default |
| `python -m csdn.clear_unread --list-only` | List current unread conversations |
| `python -m csdn.clear_unread --all` | Clear all unread badges (no replies) |
| `python -m csdn.clear_unread --nick NAME [--reply TEXT]` | Clear badges for a nickname, optionally replying |
| `python -m csdn.engage <HOME_URL> [--dry-run]` | Engage one blogger (`--dry-run` probes only) |
| `python -m csdn.check_comment <ARTICLE_URL>` | Verify a comment actually got posted |
| `python -m csdn.db --stats` | Engagement statistics |
| `python -m csdn.db --list 20` | Show the 20 most recent records |
| `python -m csdn.db --import` | Import historical `output/*.json` results into the database |
| `python -m csdn.db --reset` | Wipe all records (asks for confirmation) |

Each batch run saves a JSON report to `output/batch_<timestamp>.json` and prints a like/favorite/comment/DM summary.

## Project Layout

```
softwarer-csdn/
├── main.py              # Entry point: launches the GUI
├── csdn/                # Feature package (run as python -m csdn.xxx)
│   ├── __init__.py      #   Project ROOT, the single source of paths
│   ├── browser.py       #   Persistent Playwright context / session / shared paths
│   ├── actions.py       #   Page actions: like / favorite / comment / DM reply
│   ├── login.py         #   QR login
│   ├── check_login.py   #   Session check
│   ├── open.py          #   Open CSDN pages
│   ├── messages.py      #   Open the message center
│   ├── clear_unread.py  #   Clear unread badges
│   ├── engage.py        #   Engage a single blogger
│   ├── batch.py         #   Batch visit (main flow)
│   ├── db.py            #   SQLite engagement records
│   └── gui.py           #   PyQt6 GUI
├── assets/              # Title-bar icons for the GUI
├── probes/              # One-off probes for DOM / anti-bot troubleshooting
├── scripts/             # Archived early scripts (kept for reference only)
├── tests/               # GUI self-checks (offscreen render + simulated clicks)
├── data/                # csdn.db (generated at runtime, not committed)
├── output/              # Batch result JSON (generated, not committed)
└── screenshots/         # Runtime screenshots (generated, not committed)
```

## Dedup Rules

- Articles are normalized to their **numeric ID** (different link spellings of the same article collapse into one)
- Each article keeps `liked / collected / commented` flags; successes only grow, failures never erase them
- Batch runs load article IDs recorded in the last 30 days into memory once — zero queries in the loop; authors with everything engaged are skipped
- The GUI / `db.py --import` can backfill older JSON results in one shot

## Notes

1. **For your own account's daily courtesy visits only**: actions are spaced by a random 12–22 s delay; rapid-fire comments still get rate-limited by CSDN (comment=fail) — that's normal, just wait and rerun
2. **Site redesigns**: when CSDN changes its DOM, selectors may break — use the `probes/` scripts to locate the new structure, then patch `csdn/actions.py`
3. **Session data is sensitive**: `.csdn-browser-profile/` and `.csdn-storage-state.json` contain cookies; both are git-ignored — never commit or share them
4. Comments are typed with real keystrokes (JS value assignment is rejected by the frontend), so keep the browser window in the foreground

## License

MIT License — see [LICENSE](LICENSE).