wewrite/docs/superpowers/specs/2026-03-30-anti-ai-diagnose-design.md

Anti-AI Diagnostic Command Design

Problem

Users (e.g., issue #2) configure writing_persona: "midnight-friend" but still fail AI detection. They have no way to know which anti-AI measures are actually in effect and which silently degraded. A one-command diagnostic tells them exactly what's working, what's missing, and what to fix first.

Solution

Two entry points, one data flow:

1. scripts/diagnose.py — standalone Python script, programmatic checks, text/JSON output
2. SKILL.md auxiliary function — calls the script, adds LLM-powered cross-analysis

Part 1: scripts/diagnose.py

Location: scripts/diagnose.py (same level as fetch_hotspots.py — it checks the whole skill, not just the toolkit)

Invocation:

python3 scripts/diagnose.py              # human-readable text
python3 scripts/diagnose.py --json       # structured JSON for agent consumption

Path resolution: The script resolves the skill root as its own parent directory (Path(__file__).parent.parent), same convention as other scripts.

Check groups (5 groups, each item yields pass / warn / fail):

Group 1: Dependencies

• Import each module from requirements.txt (markdown, bs4, cssutils, requests, yaml, pygments, PIL)
• Missing module = fail with install hint

Group 2: Config (config.yaml)

• File exists → pass; missing → warn (skip_publish + skip_image_gen)
• wechat.appid + wechat.secret present → pass; missing → warn (skip_publish)
• image.api_key present → pass; missing → warn (skip_image_gen)

Group 3: Style (style.yaml)

• File exists → check fields; missing → fail
• writing_persona field present → pass; missing → warn (defaults to midnight-friend)
• Corresponding persona file in personas/ exists → pass; missing → fail

Group 4: Enhancement files

• writing-config.yaml exists → pass; missing → warn (using defaults, suggest optimize_loop.py)
• playbook.md exists → pass; missing → warn (no learned style, suggest "学习我的修改")
• history.yaml exists and has articles → pass; missing/empty → warn (no dedup, no dimension tracking)

Group 5: Dimension variance

• Read history.yaml, extract dimensions from last 3 articles
• All 3 have distinct dimension sets → pass; duplicates → warn
• Fewer than 3 articles → skip (not enough data)

Anti-AI level scoring:

Each check has a weight reflecting its impact on AI detection:

Check	Weight	Rationale
style.yaml exists	3	No style = no persona, no tone control
writing_persona configured	3	Persona is the primary anti-AI lever
persona file exists	2	Without it, persona degrades to default
writing-config.yaml exists	1	Fine-tuning parameters, moderate impact
playbook.md exists	2	Learned style significantly improves human-ness
history.yaml has articles	1	Enables dimension dedup
dimension variance OK	1	Cross-article fingerprint diversity
config.yaml with wechat creds	0	Publish capability, no anti-AI impact
config.yaml with image key	0	Image gen, no anti-AI impact
Python dependencies	0	Prerequisite, not anti-AI specific

Sum of weights for pass items / total possible (13) → percentage → level:

• 0-40% → LOW
• 41-75% → MODERATE
• 76-100% → HIGH

Text output format:

WeWrite Anti-AI Diagnostic
==========================

Dependencies
  [PASS] Python packages: all installed

Config
  [PASS] config.yaml: found
  [PASS] WeChat credentials: configured
  [WARN] Image API key: missing → image generation will be skipped

Style
  [PASS] style.yaml: found
  [PASS] writing_persona: midnight-friend
  [PASS] personas/midnight-friend.yaml: exists

Enhancement
  [WARN] writing-config.yaml: not found → using defaults (run optimize_loop.py to tune)
  [WARN] playbook.md: not found → no learned style (say "学习我的修改" after editing)
  [PASS] history.yaml: 12 articles

Dimension Variance
  [PASS] Last 3 articles have distinct dimensions

Summary: 7 passed, 3 warnings, 0 failures
Anti-AI level: ██████████░░ MODERATE (8/13)

Top recommendations:
  1. Run optimize_loop.py to generate writing-config.yaml
  2. Edit a generated article, then say "学习我的修改" to build playbook.md

JSON output (--json):

{
  "checks": [
    {"group": "dependencies", "name": "python_packages", "status": "pass", "detail": "all installed"},
    {"group": "config", "name": "config_file", "status": "pass", "detail": "found"},
    {"group": "config", "name": "wechat_credentials", "status": "pass"},
    {"group": "config", "name": "image_api_key", "status": "warn", "detail": "missing", "impact": "skip_image_gen"},
    ...
  ],
  "summary": {
    "passed": 7,
    "warnings": 3,
    "failures": 0,
    "anti_ai_score": 8,
    "anti_ai_max": 13,
    "anti_ai_level": "MODERATE"
  },
  "recommendations": [
    "Run optimize_loop.py to generate writing-config.yaml",
    "Edit a generated article, then say \"学习我的修改\" to build playbook.md"
  ],
  "files": {
    "config_yaml": true,
    "style_yaml": true,
    "writing_config_yaml": false,
    "playbook_md": false,
    "history_yaml": true,
    "persona_file": "personas/midnight-friend.yaml"
  }
}

The recommendations list is ordered by impact (highest weight missing items first). The files map gives the agent quick access to which files exist without re-checking.

Part 2: SKILL.md Auxiliary Function

Trigger: User says "诊断反 AI 配置" / "检查配置" / "为什么 AI 检测没过"

Agent flow:

1. Run python3 {skill_dir}/scripts/diagnose.py --json
2. If any fail items → report them, suggest fixes, stop here
3. If all pass or only warn → proceed to LLM deep analysis:
   • Read style.yaml: extract tone, voice, writing_persona
   • Read the active persona YAML file
   • Read writing-config.yaml (if exists)
   • Read history.yaml last 5 entries (if exists)
4. LLM cross-analysis checks:

Check	What to look for	Example issue
tone ↔ persona consistency	tone/voice keywords vs persona's voice_density, emotional_arc, avoid list	tone="严谨客观" with midnight-friend (极度口语化)
writing-config danger params	Values that produce AI-like output	emotional_arc: flat, paragraph_rhythm: structured, closing_style: summary
history persona usage	Whether persona is actually being used in recent articles	history entries with no writing_persona field
WebSearch degradation	Recent articles' topic_source showing LLM fallback	All recent articles lack real material anchoring

5. Output natural language report with prioritized action items

What it does NOT do:

• Does not run humanness_score.py (requires an existing article)
• Does not modify any config files (diagnose + recommend only)
• Does not re-run the full pipeline

SKILL.md Changes

Add to the "辅助功能" section after existing entries:

- 用户说"诊断配置"/"检查反AI" → 运行 diagnose.py --json，结合 LLM 分析输出报告

Add to Step 8c "后续操作" table:

| 诊断配置 / 检查反AI | 运行 diagnose.py + LLM 交叉分析 |

Files Changed

File	Change
scripts/diagnose.py	New file — diagnostic script
SKILL.md	Add auxiliary function entry + Step 8c row
README.md	Add diagnose command to "Toolkit 独立使用" section