# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

WeWrite is a WeChat public account (公众号) content generation AI skill. It automates the full workflow from trending topic discovery to draft box publishing. It works as both a Claude Code skill (via SKILL.md) and an OpenClaw-compatible skill (via `dist/openclaw/`).

The core pipeline is defined in SKILL.md (Steps 1-8): environment check → topic selection → framework + material collection → writing → SEO/anti-AI verification → visual AI → formatting/publishing → wrap-up.

## Commands

```bash
# Install dependencies
pip install -r requirements.txt

# Toolkit CLI
python3 toolkit/cli.py preview article.md --theme sspai       # Preview as HTML
python3 toolkit/cli.py publish article.md --cover cover.png --title "标题"  # Publish to WeChat
python3 toolkit/cli.py gallery                                  # Browse all 16 themes
python3 toolkit/cli.py themes                                   # List theme names
python3 toolkit/cli.py image-post img1.jpg img2.jpg -t "标题"   # Image post (carousel)

# Data collection scripts
python3 scripts/fetch_hotspots.py --limit 20                   # Trending topics
python3 scripts/seo_keywords.py --json "关键词1" "关键词2"      # SEO keyword analysis
python3 scripts/fetch_stats.py <article_id>                     # WeChat article stats
python3 scripts/humanness_score.py article.md --verbose         # AI detection scoring (11 checks)

# Build OpenClaw-compatible skill (also runs in CI on push to main)
python3 scripts/build_openclaw.py
```

No formal test suite exists. CI only rebuilds the OpenClaw version on push to main.

## Architecture

### Dual Nature: Skill + Toolkit

- **As a skill** (SKILL.md): An agent-orchestrated 8-step pipeline. The LLM reads SKILL.md and executes steps, calling Python scripts as tools. Reference docs in `references/` are loaded on-demand by the agent at specific steps.
- **As a standalone toolkit** (`toolkit/cli.py`): A Python CLI for Markdown→WeChat HTML conversion and publishing, usable independently of the skill.

### Key Directories

- `scripts/` — Data collection utilities (hotspots, SEO, stats) and build tools. Called by the agent during pipeline execution.
- `toolkit/` — Markdown→WeChat HTML converter, theme engine, WeChat API client, image generation. The CLI entry point is `toolkit/cli.py`.
- `personas/` — 5 YAML writing personality presets controlling tone, data presentation, emotional arc. Loaded in Step 4b.
- `references/` — Agent-loaded docs (writing rules, frameworks, SEO, topic scoring). These are NOT code — they are instruction sets the LLM reads and follows.
- `toolkit/themes/` — 16 YAML theme definitions. Parsed by `toolkit/theme.py`, applied as inline CSS by `toolkit/converter.py`.

### Formatting Pipeline (toolkit)

`converter.py` is the core: Markdown → HTML with inline styles + WeChat compatibility fixes (CJK spacing, bold punctuation, list→section conversion, external links→footnotes, dark mode attributes). WeChat strips `<style>` tags, so all CSS must be inlined. Themes are YAML files defining colors and base CSS; `theme.py` parses them, `converter.py` applies them.

### OpenClaw Compatibility

`scripts/build_openclaw.py` transforms SKILL.md for OpenClaw: replaces `{skill_dir}` with `{baseDir}`, renames tool references (WebSearch→web_search, etc.), copies referenced files. CI runs this on push to main and commits to `dist/openclaw/`.

### Configuration Files

- `config.yaml` (from `config.example.yaml`) — WeChat API credentials + image API key. Missing → graceful degradation (skip_publish, skip_image_gen).
- `style.yaml` (from `style.example.yaml`) — User's writing profile (name, topics, tone, persona, theme). Auto-created via onboard flow on first run.
- `writing-config.yaml` (from `writing-config.example.yaml`) — Writing parameters (sentence variance, idiom density, etc.). Optimized per-user via the "优化参数" auxiliary function in SKILL.md.

All three are .gitignored — each user generates their own.

### Graceful Degradation

The pipeline never hard-fails. Missing config → skip_publish/skip_image_gen flags. Script failures → WebSearch or LLM fallback. Image gen fails → output prompts only. These flags are set in Step 1 and automatically respected by later steps.

## Language & Conventions

- All code is Python 3.11+. No type checking or linter configured.
- Commit messages are in Chinese, format: `type: description` (e.g., `fix: ...`, `chore: ...`).
- The project language (README, SKILL.md, comments, references) is Chinese.