wewrite 3.2.0__py3-none-any.whl

wewrite/__init__.py

@@ -0,0 +1,3 @@
+"""WeWrite runtime — 公众号内容管道的确定性工具层（CLI: `wewrite`）。"""
+
+__version__ = "3.2.0"

wewrite/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

wewrite/cli.py

@@ -0,0 +1,82 @@
+"""`wewrite` CLI 调度器 —— 把子命令分发到 commands/ 与 toolkit/ 的既有 main()。
+
+设计约束：各命令模块保持独立 argparse（历史上是独立脚本），调度器只做
+「子命令名 → 模块」映射并透传其余参数，不重复定义参数。
+"""
+
+import importlib
+import sys
+
+from . import __version__
+from .paths import home
+
+# 子命令 → (模块, 一句话说明)。模块须提供 main(argv=None) 或 main()。
+_COMMANDS = {
+    "diagnose": ("wewrite.commands.diagnose", "环境 + 配置自检（降级标记 JSON）"),
+    "score": ("wewrite.commands.humanness_score", "写作质量评分（11 项检测）"),
+    "hotspots": ("wewrite.commands.fetch_hotspots", "多平台热点抓取"),
+    "seo": ("wewrite.commands.seo_keywords", "SEO 关键词分析"),
+    "stats": ("wewrite.commands.fetch_stats", "微信文章数据回填 history"),
+    "learn-edits": ("wewrite.commands.learn_edits", "学习人工修改（diff → lessons）"),
+    "learn-theme": ("wewrite.commands.learn_theme", "从公众号文章 URL 学排版主题"),
+    "exemplar": ("wewrite.commands.extract_exemplar", "范文风格库（导入 / --list）"),
+    "fetch-article": ("wewrite.commands.fetch_article", "公众号文章 URL → Markdown"),
+    "llm-write": ("wewrite.commands.llm_write", "混合路由写作（DeepSeek 等出稿）"),
+    "similarity": ("wewrite.commands.similarity_check", "多平台版本原创度检查"),
+    "build-playbook": ("wewrite.commands.build_playbook", "从历史语料生成 playbook"),
+    "image-gen": ("wewrite.toolkit.image_gen", "AI 图片生成（多 provider fallback）"),
+    "validate": ("wewrite.commands.validate_html", "HTML 微信兼容性校验"),
+}
+
+# toolkit/cli.py 自带子命令（preview/publish/gallery/themes/image-post/learn-theme），
+# 这些名字直接整体透传给它。
+_TOOLKIT_PASSTHROUGH = {"preview", "publish", "gallery", "themes", "image-post"}
+
+
+def _usage() -> str:
+    lines = [f"wewrite {__version__} — 公众号内容管道 CLI（状态目录: {home()}）", "", "用法: wewrite <命令> [参数…]", "", "命令:"]
+    for name, (_, desc) in _COMMANDS.items():
+        lines.append(f"  {name:<16}{desc}")
+    for name in sorted(_TOOLKIT_PASSTHROUGH):
+        lines.append(f"  {name:<16}排版工具链（toolkit）")
+    lines += [
+        "  home            输出状态目录路径",
+        "  migrate         迁移旧版仓库内状态到状态目录",
+        "",
+        "任意命令加 --help 看详细参数。",
+    ]
+    return "\n".join(lines)
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+    if not argv or argv[0] in {"-h", "--help"}:
+        print(_usage())
+        return
+    if argv[0] in {"-V", "--version"}:
+        print(__version__)
+        return
+
+    cmd, rest = argv[0], argv[1:]
+
+    if cmd == "home":
+        print(home())
+        return
+    if cmd == "migrate":
+        from .migrate import main as migrate_main
+        migrate_main(rest)
+        return
+    if cmd in _TOOLKIT_PASSTHROUGH:
+        from .toolkit import cli as toolkit_cli
+        sys.argv = ["wewrite", cmd, *rest]
+        toolkit_cli.main()
+        return
+    if cmd in _COMMANDS:
+        module_name, _ = _COMMANDS[cmd]
+        module = importlib.import_module(module_name)
+        sys.argv = [f"wewrite {cmd}", *rest]
+        module.main()
+        return
+
+    print(f"未知命令: {cmd}\n\n{_usage()}", file=sys.stderr)
+    sys.exit(2)

wewrite/commands/build_playbook.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""
+Build a writing playbook from historical articles.
+
+Reads all .md files in corpus/, analyzes writing patterns
+in batches via LLM, and outputs a structured playbook.md.
+
+Usage:
+    wewrite build-playbook
+    wewrite build-playbook --batch-size 10
+
+Requires: ANTHROPIC_API_KEY or ARK API key in environment/config.
+This script outputs analysis prompts to stdout for the Agent (LLM) to process.
+The Agent reads the output and generates playbook.md.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ..paths import corpus_dir as _corpus_dir
+
+
+def load_corpus() -> list[dict]:
+    """Load all markdown files from corpus directory ($WEWRITE_HOME/corpus)."""
+    corpus_dir = _corpus_dir()
+    if not corpus_dir.exists():
+        print(f"Error: corpus directory not found: {corpus_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    articles = []
+    for md_file in sorted(corpus_dir.glob("*.md")):
+        text = md_file.read_text(encoding="utf-8")
+        if not text.strip():
+            continue
+
+        # Extract title (first H1)
+        title = ""
+        for line in text.split("\n"):
+            if line.strip().startswith("# ") and not line.strip().startswith("## "):
+                title = line.strip()[2:].strip()
+                break
+
+        # Basic stats
+        lines = [l for l in text.split("\n") if l.strip()]
+        paragraphs = text.split("\n\n")
+        h2_count = sum(1 for l in text.split("\n") if l.strip().startswith("## "))
+        char_count = len(text.replace("\n", "").replace(" ", ""))
+
+        articles.append({
+            "filename": md_file.name,
+            "title": title,
+            "char_count": char_count,
+            "paragraph_count": len([p for p in paragraphs if p.strip()]),
+            "h2_count": h2_count,
+            "text": text,
+        })
+
+    return articles
+
+
+def compute_corpus_stats(articles: list[dict]) -> dict:
+    """Compute aggregate statistics from the corpus."""
+    if not articles:
+        return {}
+
+    titles = [a["title"] for a in articles if a["title"]]
+    title_lengths = [len(t) for t in titles]
+    char_counts = [a["char_count"] for a in articles]
+    para_counts = [a["paragraph_count"] for a in articles]
+    h2_counts = [a["h2_count"] for a in articles]
+
+    return {
+        "total_articles": len(articles),
+        "avg_char_count": round(sum(char_counts) / len(char_counts)),
+        "avg_title_length": round(sum(title_lengths) / len(title_lengths), 1) if title_lengths else 0,
+        "title_length_range": f"{min(title_lengths)}-{max(title_lengths)}" if title_lengths else "N/A",
+        "avg_paragraphs": round(sum(para_counts) / len(para_counts), 1),
+        "avg_h2_count": round(sum(h2_counts) / len(h2_counts), 1),
+    }
+
+
+def build_analysis_batches(articles: list[dict], batch_size: int) -> list[list[dict]]:
+    """Split articles into batches for LLM analysis."""
+    batches = []
+    for i in range(0, len(articles), batch_size):
+        batch = articles[i:i + batch_size]
+        batches.append(batch)
+    return batches
+
+
+def output_analysis_prompt(articles: list[dict], stats: dict, batch_idx: int, total_batches: int):
+    """Output a structured analysis prompt for the Agent to process."""
+    print(f"\n{'='*60}")
+    print(f"BATCH {batch_idx + 1}/{total_batches} — {len(articles)} articles")
+    print(f"{'='*60}\n")
+
+    for i, article in enumerate(articles):
+        print(f"--- Article {i+1}: {article['title']} ({article['char_count']}字) ---")
+        # Truncate very long articles to first 2000 chars for analysis
+        text = article["text"]
+        if len(text) > 3000:
+            text = text[:3000] + "\n\n[...truncated...]"
+        print(text)
+        print()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Build writing playbook from corpus")
+    parser.add_argument("--batch-size", type=int, default=10, help="Articles per batch")
+    parser.add_argument("--stats-only", action="store_true", help="Only show corpus stats")
+    args = parser.parse_args()
+
+    # Load corpus
+    articles = load_corpus()
+    if not articles:
+        print("Error: no articles found in corpus/", file=sys.stderr)
+        sys.exit(1)
+
+    # Compute stats
+    stats = compute_corpus_stats(articles)
+
+    print("=" * 60)
+    print("CORPUS ANALYSIS")
+    print("=" * 60)
+    print(json.dumps(stats, ensure_ascii=False, indent=2))
+
+    if args.stats_only:
+        return
+
+    # Build batches
+    batches = build_analysis_batches(articles, args.batch_size)
+
+    print(f"\nTotal: {stats['total_articles']} articles in {len(batches)} batch(es)")
+    print(f"Average: {stats['avg_char_count']} chars, {stats['avg_title_length']} char titles, {stats['avg_h2_count']} H2s")
+
+    # Output analysis instructions
+    print(f"""
+{'='*60}
+ANALYSIS INSTRUCTIONS FOR AGENT
+{'='*60}
+
+Read all articles below, then generate playbook.md with these sections:
+
+## 标题模式
+- 平均字数和范围
+- 常用策略分布（数字/反直觉/痛点/疑问/陈述，给百分比）
+- 标点习惯（逗号断句？问号？感叹号？）
+- 示例：列出 3 个最典型的标题
+
+## 开头模式
+- 最常用的开头方式（场景/数据/反问/新闻引述/个人经历）
+- 第一段平均长度
+- 从不出现的开头方式
+- 示例：列出 3 个典型开头的第一段
+
+## 段落节奏
+- 平均段落长度（字数）
+- 短段（<30字）占比
+- 最长段落上限
+- 长短交替规律
+
+## 用词指纹
+- 高频标志词/口头禅（出现 3 次以上的特征性表达）
+- 禁用词（从未使用的常见 AI 用语）
+- 英文/专业术语使用习惯
+- 语气词偏好
+
+## H2 命名习惯
+- 用问句？短语？数字编号？
+- 平均长度
+- 示例
+
+## 结尾模式
+- 收尾方式（个人观点/开放提问/行动建议/金句）
+- CTA 风格
+- 示例
+
+## 情绪基调
+- 理性 vs 感性的比例
+- 幽默频率
+- 批判性强度
+
+## 配图风格（如果历史文章有配图描述）
+- 色调偏好
+- 风格关键词
+
+请用量化数据（百分比、平均值、范围）支撑每个结论，不要只做定性描述。
+""")
+
+    # Output article batches
+    for i, batch in enumerate(batches):
+        output_analysis_prompt(batch, stats, i, len(batches))
+
+
+if __name__ == "__main__":
+    main()

wewrite/commands/diagnose.py

@@ -0,0 +1,398 @@
+#!/usr/bin/env python3
+"""
+Diagnose which writing-quality (humanness) measures are active in this WeWrite installation.
+
+Checks: Python deps, config.yaml, style.yaml, enhancement files, dimension variance.
+Outputs a human-readable report or structured JSON.
+
+Usage:
+    wewrite diagnose              # text report
+    wewrite diagnose --json       # JSON for agent consumption
+"""
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from pathlib import Path
+
+import yaml
+
+from .. import paths
+
+# 内置写作人格预设（prompt 层数据，随 skill 仓库分发；CLI 只做名字校验）
+BUILTIN_PERSONAS = {
+    "cold-analyst", "humor-storyteller", "industry-observer",
+    "midnight-friend", "sharp-journalist", "tech-coder", "warm-editor",
+}
+
+# Modules to check (import_name, package_name_for_pip)
+REQUIRED_MODULES = [
+    ("markdown", "markdown"),
+    ("bs4", "beautifulsoup4"),
+    ("cssutils", "cssutils"),
+    ("requests", "requests"),
+    ("yaml", "pyyaml"),
+    ("pygments", "Pygments"),
+    ("PIL", "Pillow"),
+]
+
+# Humanness weight per check (0 = no humanness impact, higher = more important)
+# JSON keys keep the legacy anti_ai_* names for compatibility.
+WEIGHTS = {
+    "style_file": 3,
+    "writing_persona": 3,
+    "persona_file": 2,
+    "writing_config": 1,
+    "playbook": 2,
+    "history_articles": 1,
+    "dimension_variance": 1,
+    # These have 0 weight (no humanness impact)
+    "python_packages": 0,
+    "config_file": 0,
+    "wechat_credentials": 0,
+    "image_api_key": 0,
+}
+
+MAX_ANTI_AI_SCORE = sum(v for v in WEIGHTS.values() if v > 0)  # 13
+
+
+def make_check(group, name, status, detail=None, impact=None):
+    """Create a check result dict."""
+    c = {"group": group, "name": name, "status": status}
+    if detail is not None:
+        c["detail"] = detail
+    if impact is not None:
+        c["impact"] = impact
+    return c
+
+
+def check_dependencies():
+    """Group 1: Check Python package imports."""
+    missing = []
+    for mod_name, pip_name in REQUIRED_MODULES:
+        try:
+            importlib.import_module(mod_name)
+        except ImportError:
+            missing.append(pip_name)
+
+    if not missing:
+        return [make_check("dependencies", "python_packages", "pass", "all installed")]
+    return [make_check(
+        "dependencies", "python_packages", "fail",
+        f"missing: {', '.join(missing)}. Reinstall CLI (uv tool install --force wewrite) "
+        f"or: pip install {' '.join(missing)}",
+    )]
+
+
+def _env_set(*names):
+    """True if all named env vars are non-empty (container injects secrets via env)."""
+    return all(os.environ.get(n, "").strip() for n in names)
+
+
+def check_config():
+    """Group 2: Check config.yaml + env-injected secrets.
+
+    线上容器把密钥经环境变量注入（WECHAT_*/WEWRITE_IMAGE_*/WEWRITE_WRITER_*），
+    config.yaml 往往只有非敏感默认值。所以这里 config 与 env **任一**满足即算配置好，
+    避免把已注入的密钥误判成缺失而错误置 skip_*。
+    """
+    checks = []
+    config_path = paths.config_path()
+    cfg = {}
+    if config_path.exists():
+        checks.append(make_check("config", "config_file", "pass", "found"))
+        with open(config_path, "r", encoding="utf-8") as f:
+            cfg = yaml.safe_load(f) or {}
+    else:
+        checks.append(make_check("config", "config_file", "warn",
+                                 "no config.yaml → 仅按环境变量判断"))
+
+    # WeChat credentials: config.yaml 或 env 任一齐全即可
+    wechat = cfg.get("wechat", {}) or {}
+    if (wechat.get("appid") and wechat.get("secret")) or _env_set("WECHAT_APPID", "WECHAT_SECRET"):
+        checks.append(make_check("config", "wechat_credentials", "pass", "configured"))
+    else:
+        checks.append(make_check("config", "wechat_credentials", "warn",
+                                 "missing appid/secret", impact="skip_publish"))
+
+    # Image: config.image.api_key 或 env WEWRITE_IMAGE_API_KEY 任一即可
+    image = cfg.get("image", {}) or {}
+    if image.get("api_key") or _env_set("WEWRITE_IMAGE_API_KEY"):
+        checks.append(make_check("config", "image_api_key", "pass", "configured"))
+    else:
+        checks.append(make_check("config", "image_api_key", "warn",
+                                 "missing → image generation will be skipped", impact="skip_image_gen"))
+
+    return checks
+
+
+def runtime_flags(checks):
+    """管道运行标记，供 SKILL.md Step 1 一次性读取（env 优先，与 check_config 同源）。"""
+    def warned(name):
+        return any(c["name"] == name and c["status"] != "pass" for c in checks)
+    return {
+        # 没有微信凭证 → 跳过发布；没有图片 key → 跳过生图
+        "skip_publish": warned("wechat_credentials"),
+        "skip_image_gen": warned("image_api_key"),
+        # 配了写作模型（混合路由）→ Step 4 走 llm_write.py；否则编排器自写
+        "use_writer_model": _env_set("WEWRITE_WRITER_API_KEY"),
+    }
+
+
+def check_style():
+    """Group 3: Check style.yaml and persona configuration."""
+    checks = []
+    style_path = paths.style_path()
+
+    if not style_path.exists():
+        checks.append(make_check("style", "style_file", "fail", "not found → run onboard first"))
+        return checks
+
+    checks.append(make_check("style", "style_file", "pass", "found"))
+
+    with open(style_path, "r", encoding="utf-8") as f:
+        style = yaml.safe_load(f) or {}
+
+    # writing_persona field
+    persona_name = style.get("writing_persona")
+    if persona_name:
+        checks.append(make_check("style", "writing_persona", "pass", persona_name))
+    else:
+        persona_name = "midnight-friend"
+        checks.append(make_check("style", "writing_persona", "warn", "not set → defaults to midnight-friend"))
+
+    # Persona 存在性：内置预设名单，或 $WEWRITE_HOME/personas/ 下的自定义人格
+    custom = paths.home() / "personas" / f"{persona_name}.yaml"
+    if persona_name in BUILTIN_PERSONAS:
+        checks.append(make_check("style", "persona_file", "pass", f"{persona_name}（内置预设）"))
+    elif custom.exists():
+        checks.append(make_check("style", "persona_file", "pass", f"{custom}（自定义）"))
+    else:
+        checks.append(make_check("style", "persona_file", "fail",
+                                 f"{persona_name} 不是内置人格，且 {custom} 不存在"))
+
+    return checks
+
+
+def check_enhancements():
+    """Group 4: Check writing-config, playbook, history."""
+    checks = []
+
+    # writing-config.yaml
+    if paths.writing_config_path().exists():
+        checks.append(make_check("enhancement", "writing_config", "pass", "found"))
+    else:
+        checks.append(make_check(
+            "enhancement", "writing_config", "warn",
+            "not found → using defaults (say '优化参数' to tune)",
+        ))
+
+    # playbook.md
+    if paths.playbook_path().exists():
+        checks.append(make_check("enhancement", "playbook", "pass", "found"))
+    else:
+        checks.append(make_check(
+            "enhancement", "playbook", "warn",
+            'not found → no learned style (say "学习我的修改" after editing)',
+        ))
+
+    # history.yaml
+    history_path = paths.history_path()
+    if history_path.exists():
+        with open(history_path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        articles = data if isinstance(data, list) else (data or {}).get("articles", [])
+        if articles:
+            checks.append(make_check("enhancement", "history_articles", "pass", f"{len(articles)} articles"))
+        else:
+            checks.append(make_check("enhancement", "history_articles", "warn", "file exists but empty"))
+    else:
+        checks.append(make_check("enhancement", "history_articles", "warn", "not found → no dedup, no dimension tracking"))
+
+    return checks
+
+
+def check_dimensions():
+    """Group 5: Check dimension diversity across recent articles."""
+    history_path = paths.history_path()
+    if not history_path.exists():
+        return [make_check("dimensions", "dimension_variance", "skip", "no history.yaml")]
+
+    with open(history_path, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    articles = data if isinstance(data, list) else (data or {}).get("articles", [])
+    # Get last 3 articles that have dimensions
+    recent = [a for a in articles if a.get("dimensions")][-3:]
+
+    if len(recent) < 3:
+        return [make_check("dimensions", "dimension_variance", "skip", f"only {len(recent)} articles with dimensions (need 3)")]
+
+    # Compare dimension sets — stringify and check uniqueness
+    dim_sets = [tuple(sorted(a["dimensions"])) for a in recent]
+    if len(set(dim_sets)) == len(dim_sets):
+        return [make_check("dimensions", "dimension_variance", "pass", "last 3 articles have distinct dimensions")]
+
+    return [make_check("dimensions", "dimension_variance", "warn", "dimension overlap in recent articles → cross-article fingerprint risk")]
+
+
+def compute_summary(checks):
+    """Compute pass/warn/fail counts, humanness score, and recommendations."""
+    passed = sum(1 for c in checks if c["status"] == "pass")
+    warnings = sum(1 for c in checks if c["status"] == "warn")
+    failures = sum(1 for c in checks if c["status"] == "fail")
+    skipped = sum(1 for c in checks if c["status"] == "skip")
+
+    score = sum(WEIGHTS.get(c["name"], 0) for c in checks if c["status"] == "pass")
+    pct = score / MAX_ANTI_AI_SCORE if MAX_ANTI_AI_SCORE else 0
+    if pct >= 0.76:
+        level = "HIGH"
+    elif pct >= 0.41:
+        level = "MODERATE"
+    else:
+        level = "LOW"
+
+    # Build recommendations ordered by weight (highest first)
+    recs = []
+    non_pass = [c for c in checks if c["status"] in ("warn", "fail") and WEIGHTS.get(c["name"], 0) > 0]
+    non_pass.sort(key=lambda c: WEIGHTS.get(c["name"], 0), reverse=True)
+    for c in non_pass:
+        name = c["name"]
+        if name == "style_file":
+            recs.append('Run the skill once to trigger onboard（重新设置风格）')
+        elif name == "writing_persona":
+            recs.append('Add writing_persona: "midnight-friend" to style.yaml (best humanness rate)')
+        elif name == "persona_file":
+            recs.append(f'Persona file missing — check personas/ directory')
+        elif name == "playbook":
+            recs.append('Edit a generated article, then say "学习我的修改" to build playbook.md')
+        elif name == "writing_config":
+            recs.append('Say "优化参数" to run the optimization loop')
+        elif name == "history_articles":
+            recs.append("Generate your first article to start building history")
+        elif name == "dimension_variance":
+            recs.append("Recent articles reuse same dimensions — the pipeline will auto-fix on next run")
+
+    return {
+        "passed": passed,
+        "warnings": warnings,
+        "failures": failures,
+        "skipped": skipped,
+        "anti_ai_score": score,
+        "anti_ai_max": MAX_ANTI_AI_SCORE,
+        "anti_ai_level": level,
+    }, recs
+
+
+def file_status_map(checks):
+    """Build a quick file-existence map for agent use."""
+    # Extract persona name from checks instead of re-reading style.yaml
+    persona_name = "midnight-friend"
+    for c in checks:
+        if c["name"] == "writing_persona" and c["status"] == "pass" and c.get("detail"):
+            persona_name = c["detail"]
+            break
+
+    exemplars = sorted(paths.exemplars_dir().glob("*.md")) if paths.exemplars_dir().is_dir() else []
+    return {
+        "home": str(paths.home()),
+        "config_yaml": paths.config_path().exists(),
+        "style_yaml": paths.style_path().exists(),
+        "writing_config_yaml": paths.writing_config_path().exists(),
+        "playbook_md": paths.playbook_path().exists(),
+        "history_yaml": paths.history_path().exists(),
+        "persona": persona_name,
+        "exemplars": [f.name for f in exemplars],
+    }
+
+
+def format_text(checks, summary, recs):
+    """Format human-readable text report."""
+    lines = ["WeWrite Writing-Quality Diagnostic", "=" * 33, ""]
+
+    current_group = None
+    group_labels = {
+        "dependencies": "Dependencies",
+        "config": "Config",
+        "style": "Style",
+        "enhancement": "Enhancement",
+        "dimensions": "Dimension Variance",
+    }
+    for c in checks:
+        if c["group"] != current_group:
+            if current_group is not None:
+                lines.append("")
+            current_group = c["group"]
+            lines.append(group_labels.get(current_group, current_group))
+        tag = c["status"].upper()
+        label = c["name"].replace("_", " ").title()
+        detail = f": {c['detail']}" if c.get("detail") else ""
+        lines.append(f"  [{tag:4s}] {label}{detail}")
+    lines.append("")
+
+    p, w, f_ = summary["passed"], summary["warnings"], summary["failures"]
+    sk = summary.get("skipped", 0)
+    skipped_part = f", {sk} skipped" if sk > 0 else ""
+    lines.append(f"Summary: {p} passed, {w} warnings, {f_} failures{skipped_part}")
+
+    score = summary["anti_ai_score"]
+    mx = summary["anti_ai_max"]
+    filled = round(score / mx * 12) if mx else 0
+    bar = "\u2588" * filled + "\u2591" * (12 - filled)
+    lines.append(f"Humanness level: {bar} {summary['anti_ai_level']} ({score}/{mx})")
+
+    if recs:
+        lines.append("")
+        lines.append("Top recommendations:")
+        for i, r in enumerate(recs, 1):
+            lines.append(f"  {i}. {r}")
+
+    return "\n".join(lines)
+
+
+def format_json(checks, summary, recs):
+    """Format JSON output."""
+    return json.dumps({
+        "checks": checks,
+        "summary": summary,
+        "recommendations": recs,
+        "files": file_status_map(checks),
+        "flags": runtime_flags(checks),
+    }, ensure_ascii=False, indent=2)
+
+
+def run_all_checks():
+    """Run all check groups and return combined list."""
+    checks = []
+    checks.extend(check_dependencies())
+    checks.extend(check_config())
+    checks.extend(check_style())
+    checks.extend(check_enhancements())
+    checks.extend(check_dimensions())
+    return checks
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Diagnose which writing-quality (humanness) measures are active in this WeWrite installation.",
+    )
+    parser.add_argument("--json", action="store_true", help="Output structured JSON")
+    args = parser.parse_args()
+
+    paths.ensure_home()  # 首个管道命令，顺手把状态目录立起来
+    checks = run_all_checks()
+    summary, recs = compute_summary(checks)
+
+    if args.json:
+        print(format_json(checks, summary, recs))
+    else:
+        print(format_text(checks, summary, recs))
+
+    # Exit code: 1 if any failures, 0 otherwise
+    sys.exit(1 if summary["failures"] > 0 else 0)
+
+
+if __name__ == "__main__":
+    main()