@tikomni/skills 0.1.0

package/skills/creator-analysis/scripts/author_home/analyzers/prompt_first_analyzers.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Prompt-first analyzers for author-home insights."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from typing import Any, Dict, List, Tuple
+
+from scripts.author_home.analyzers.author_analysis_v2_support import (
+    build_author_analysis_input_v1,
+    build_fallback_author_analysis_v2,
+    derive_legacy_summary,
+    prompt_contract_text,
+    validate_author_analysis_v2,
+)
+from scripts.author_home.analyzers.sampled_work_batch_explainer import run_sampled_work_batch_explanations
+
+AUTHOR_ANALYSIS_PROMPT_FILE = "author-analysis-v2.md"
+DEFAULT_ANALYSIS_TIMEOUT_SEC = 45
+DEFAULT_SMALL_SAMPLE_SKIP_THRESHOLD = 5
+PROMPT_TEXT_LIMITS = {
+    "title": 120,
+    "caption_raw": 240,
+    "primary_text": 480,
+    "signature": 160,
+    "top_list": 8,
+    "notes": 6,
+}
+
+
+def _truncate_text(value: Any, limit: int) -> str:
+    text = str(value or "").strip()
+    if limit <= 0 or len(text) <= limit:
+        return text
+    return text[: max(limit - 1, 0)] + "…"
+
+
+
+def _compact_distribution(block: Any, *, item_limit: int) -> Any:
+    if not isinstance(block, dict):
+        return block
+    compacted = dict(block)
+    items = compacted.get("items")
+    if isinstance(items, list):
+        compacted["items"] = items[:item_limit]
+    return compacted
+
+
+
+def _compact_analysis_input_for_prompt(analysis_input: Dict[str, Any]) -> Dict[str, Any]:
+    compacted = json.loads(json.dumps(analysis_input, ensure_ascii=False))
+
+    author_profile = compacted.get("author_profile")
+    if isinstance(author_profile, dict):
+        author_profile["signature"] = _truncate_text(author_profile.get("signature"), PROMPT_TEXT_LIMITS["signature"])
+
+    sampled_works = compacted.get("sampled_works")
+    if isinstance(sampled_works, list):
+        trimmed_works: List[Dict[str, Any]] = []
+        for work in sampled_works:
+            if not isinstance(work, dict):
+                continue
+            row = dict(work)
+            row["title"] = _truncate_text(row.get("title"), PROMPT_TEXT_LIMITS["title"])
+            row["caption_raw"] = _truncate_text(row.get("caption_raw"), PROMPT_TEXT_LIMITS["caption_raw"])
+            row["primary_text"] = _truncate_text(row.get("primary_text"), PROMPT_TEXT_LIMITS["primary_text"])
+            if isinstance(row.get("tags"), list):
+                row["tags"] = row.get("tags")[: PROMPT_TEXT_LIMITS["top_list"]]
+            if isinstance(row.get("style_markers"), list):
+                row["style_markers"] = row.get("style_markers")[: PROMPT_TEXT_LIMITS["top_list"]]
+            trimmed_works.append(row)
+        compacted["sampled_works"] = trimmed_works
+
+    aggregate_stats = compacted.get("aggregate_stats")
+    if isinstance(aggregate_stats, dict):
+        for key in (
+            "global_title_keyword_distribution",
+            "global_caption_keyword_distribution",
+            "global_primary_text_keyword_distribution",
+            "global_hook_type_distribution",
+            "global_structure_type_distribution",
+            "global_cta_type_distribution",
+            "global_content_form_distribution",
+            "global_work_modality_distribution",
+            "global_bucket_distribution",
+        ):
+            aggregate_stats[key] = _compact_distribution(aggregate_stats.get(key), item_limit=PROMPT_TEXT_LIMITS["top_list"])
+        deltas = aggregate_stats.get("global_top_vs_mid_vs_bottom_deltas")
+        if isinstance(deltas, dict):
+            for group in ("top", "mid", "bottom"):
+                block = deltas.get(group)
+                if not isinstance(block, dict):
+                    continue
+                for key in ("title_keywords", "caption_keywords", "primary_text_keywords", "hook_types", "structure_types", "cta_types", "content_forms"):
+                    value = block.get(key)
+                    if isinstance(value, list):
+                        block[key] = value[: PROMPT_TEXT_LIMITS["top_list"]]
+        duration_dist = aggregate_stats.get("global_duration_distribution")
+        if isinstance(duration_dist, dict) and isinstance(duration_dist.get("items"), list):
+            duration_dist["items"] = duration_dist["items"][:3]
+
+    return compacted
+
+
+
+def _build_prompt(analysis_input: Dict[str, Any], sampled_work_explanations: Dict[str, Any]) -> str:
+    contract_prompt = prompt_contract_text()
+    prompt_input = _compact_analysis_input_for_prompt(analysis_input)
+    prompt_payload = {"author_analysis_input_v1": prompt_input}
+    if isinstance(sampled_work_explanations, dict) and sampled_work_explanations.get("sampled_work_explanations"):
+        prompt_payload["sampled_work_explanations"] = sampled_work_explanations["sampled_work_explanations"]
+    return (
+        "请严格根据以下提示词原文输出，结果必须是 JSON 对象，且只输出 JSON。\n"
+        "顶层对象必须是 author_analysis_v2。\n"
+        "不得输出 markdown，不得输出解释。\n\n"
+        "=== 提示词原文开始 ===\n"
+        f"{contract_prompt}\n"
+        "=== 提示词原文结束 ===\n\n"
+        "=== 标准化输入对象名 ===\n"
+        "author_analysis_input_v1\n\n"
+        "=== 输入数据(JSON) ===\n"
+        f"{json.dumps(prompt_payload, ensure_ascii=False)}"
+    )
+
+
+def _extract_json_block(text: str) -> Dict[str, Any]:
+    content = (text or "").strip()
+    if not content:
+        return {}
+    try:
+        return json.loads(content)
+    except Exception:
+        pass
+
+    fenced = re.search(r"```(?:json)?\s*(\{[\s\S]*?\})\s*```", content)
+    if fenced:
+        try:
+            return json.loads(fenced.group(1))
+        except Exception:
+            pass
+
+    match = re.search(r"\{[\s\S]*\}", content)
+    if not match:
+        return {}
+    try:
+        return json.loads(match.group(0))
+    except Exception:
+        return {}
+
+
+def _unwrap_author_analysis(payload: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(payload, dict):
+        return {}
+    if isinstance(payload.get("author_analysis_v2"), dict):
+        return payload["author_analysis_v2"]
+    return payload
+
+
+def run_prompt_first_author_analysis(profile: Dict[str, Any], works: List[Dict[str, Any]]) -> Tuple[Dict[str, Any], List[Dict[str, str]], List[Dict[str, Any]]]:
+    analysis_input, input_errors = build_author_analysis_input_v1(profile=profile, works=works, platform=str(profile.get("platform") or "unknown"))
+    sampled_work_explanations, sampled_explanation_errors, sampled_explanation_trace = run_sampled_work_batch_explanations(analysis_input)
+    sampled_works_count = len(analysis_input.get("sampled_works") or [])
+    total_works = ((analysis_input.get("aggregate_stats") or {}).get("total_works") if isinstance(analysis_input.get("aggregate_stats"), dict) else 0)
+    llm_timeout_sec = max(int(os.getenv("TIKOMNI_AUTHOR_ANALYSIS_TIMEOUT_SEC", str(DEFAULT_ANALYSIS_TIMEOUT_SEC))), 5)
+    small_sample_skip_threshold = max(int(os.getenv("TIKOMNI_AUTHOR_ANALYSIS_SMALL_SAMPLE_SKIP", str(DEFAULT_SMALL_SAMPLE_SKIP_THRESHOLD))), 0)
+    trace: List[Dict[str, Any]] = [
+        {
+            "step": "analysis.input_built",
+            "input_object": "author_analysis_input_v1",
+            "total_works": total_works,
+            "sampled_works_count": sampled_works_count,
+            "prompt_contract": f"prompt-contracts/{AUTHOR_ANALYSIS_PROMPT_FILE}@v1",
+            "llm_timeout_sec": llm_timeout_sec,
+            "small_sample_skip_threshold": small_sample_skip_threshold,
+        }
+    ] + sampled_explanation_trace
+    if input_errors:
+        trace.append({"step": "analysis.input_validation_failed", "error_count": len(input_errors)})
+    if sampled_explanation_errors:
+        trace.append({"step": "analysis.sampled_work_explanations_validation_failed", "error_count": len(sampled_explanation_errors)})
+
+    prompt = _build_prompt(analysis_input, sampled_work_explanations)
+    response_text = ""
+    analysis_v2: Dict[str, Any] = {}
+    llm_ok = False
+    skip_llm = sampled_works_count < small_sample_skip_threshold
+    if skip_llm:
+        trace.append(
+            {
+                "step": "analysis.llm_skipped",
+                "reason": "small_sample_below_threshold",
+                "sampled_works_count": sampled_works_count,
+                "threshold": small_sample_skip_threshold,
+            }
+        )
+    else:
+        try:
+            run = subprocess.run(
+                ["openclaw", "agent", "--agent", "main", "--message", prompt, "--json"],
+                capture_output=True,
+                text=True,
+                timeout=llm_timeout_sec,
+                check=False,
+            )
+            parsed = json.loads(run.stdout or "{}")
+            chunks: List[str] = []
+            for item in parsed.get("result", {}).get("payloads", []):
+                if isinstance(item, dict) and isinstance(item.get("text"), str):
+                    chunks.append(item["text"])
+            response_text = "\n".join(chunks).strip()
+            raw_analysis = _extract_json_block(response_text)
+            analysis_v2 = _unwrap_author_analysis(raw_analysis)
+            llm_ok = bool(analysis_v2)
+            trace.append(
+                {
+                    "step": "analysis.llm_called",
+                    "returncode": run.returncode,
+                    "has_text": bool(response_text),
+                    "parsed": llm_ok,
+                    "stdout_chars": len(run.stdout or ""),
+                    "stderr_chars": len(run.stderr or ""),
+                }
+            )
+        except Exception as error:
+            trace.append({"step": "analysis.llm_error", "error": f"{type(error).__name__}:{error}"})
+
+    validation_errors = validate_author_analysis_v2(analysis_v2, analysis_input=analysis_input) if analysis_v2 else []
+    if not analysis_v2 or validation_errors:
+        fallback = build_fallback_author_analysis_v2(analysis_input)
+        fallback_errors = validate_author_analysis_v2(fallback, analysis_input=analysis_input)
+        trace.append(
+            {
+                "step": "analysis.fallback_used",
+                "reason": "llm_empty_or_validation_failed",
+                "llm_ok": llm_ok,
+                "validation_error_count": len(validation_errors),
+                "fallback_error_count": len(fallback_errors),
+            }
+        )
+        analysis_v2 = fallback
+        validation_errors = input_errors + sampled_explanation_errors + validation_errors + fallback_errors
+    else:
+        validation_errors = input_errors + sampled_explanation_errors + validation_errors
+        trace.append({"step": "analysis.schema_validation_passed"})
+
+    legacy = derive_legacy_summary(analysis_v2, analysis_input=analysis_input, validation_errors=validation_errors)
+    result = {
+        **legacy,
+        "author_analysis_v2": analysis_v2,
+        "author_analysis_input_v1": analysis_input,
+        "sampled_work_explanations": sampled_work_explanations,
+        "validation": {
+            "ok": not bool(validation_errors),
+            "errors": validation_errors,
+        },
+    }
+    return result, validation_errors, trace

package/skills/creator-analysis/scripts/author_home/analyzers/sampled_work_batch_explainer.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Batch explanations for sampled works."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+import jsonschema
+
+
+PROMPT_CONTRACT_PATH = Path(__file__).resolve().parents[2] / "references" / "prompt-contracts" / "sampled-work-batch-explanations.md"
+SCHEMA_PATH = Path(__file__).resolve().parents[2] / "references" / "schemas" / "sampled-work-batch-explanations.schema.json"
+DEFAULT_TIMEOUT_SEC = 45
+TEXT_LIMITS = {
+    "title": 120,
+    "caption_raw": 220,
+    "primary_text": 420,
+    "top_list": 8,
+}
+
+
+def _safe_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value.strip()
+    return str(value).strip()
+
+
+def _truncate_text(value: Any, limit: int) -> str:
+    text = _safe_text(value)
+    if limit <= 0 or len(text) <= limit:
+        return text
+    return text[: max(limit - 1, 0)] + "…"
+
+
+def _load_json(path: Path) -> Dict[str, Any]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _schema_errors(payload: Any) -> List[Dict[str, str]]:
+    schema = _load_json(SCHEMA_PATH)
+    if not schema:
+        return []
+    try:
+        validator = jsonschema.Draft202012Validator(schema)
+        errors: List[Dict[str, str]] = []
+        for error in sorted(validator.iter_errors(payload), key=lambda item: list(item.absolute_path)):
+            field = ".".join(str(part) for part in error.absolute_path) or "$"
+            errors.append({"field": field, "reason": f"schema:{error.message}"})
+        return errors
+    except Exception as error:
+        return [{"field": "$", "reason": f"schema_runtime:{type(error).__name__}:{error}"}]
+
+
+def _prompt_contract_text() -> str:
+    try:
+        return PROMPT_CONTRACT_PATH.read_text(encoding="utf-8").strip()
+    except Exception:
+        return ""
+
+
+def _extract_json_block(text: str) -> Dict[str, Any]:
+    content = (text or "").strip()
+    if not content:
+        return {}
+    try:
+        return json.loads(content)
+    except Exception:
+        pass
+
+    fenced = re.search(r"```(?:json)?\s*(\{[\s\S]*?\})\s*```", content)
+    if fenced:
+        try:
+            return json.loads(fenced.group(1))
+        except Exception:
+            pass
+
+    match = re.search(r"\{[\s\S]*\}", content)
+    if not match:
+        return {}
+    try:
+        return json.loads(match.group(0))
+    except Exception:
+        return {}
+
+
+def _compact_input(analysis_input: Dict[str, Any]) -> Dict[str, Any]:
+    sampled = analysis_input.get("sampled_works") if isinstance(analysis_input.get("sampled_works"), list) else []
+    aggregate = analysis_input.get("aggregate_stats") if isinstance(analysis_input.get("aggregate_stats"), dict) else {}
+    deltas = aggregate.get("global_top_vs_mid_vs_bottom_deltas") if isinstance(aggregate.get("global_top_vs_mid_vs_bottom_deltas"), dict) else {}
+
+    compacted_sampled: List[Dict[str, Any]] = []
+    for item in sampled:
+        if not isinstance(item, dict):
+            continue
+        compacted_sampled.append(
+            {
+                "platform_work_id": _safe_text(item.get("platform_work_id")),
+                "title": _truncate_text(item.get("title"), TEXT_LIMITS["title"]),
+                "caption_raw": _truncate_text(item.get("caption_raw"), TEXT_LIMITS["caption_raw"]),
+                "work_modality": _safe_text(item.get("work_modality")),
+                "primary_text": _truncate_text(item.get("primary_text"), TEXT_LIMITS["primary_text"]),
+                "bucket": _safe_text(item.get("bucket")),
+                "hook_type": _safe_text(item.get("hook_type")),
+                "structure_type": _safe_text(item.get("structure_type")),
+                "cta_type": _safe_text(item.get("cta_type")),
+                "content_form": _safe_text(item.get("content_form")),
+                "style_markers": list(item.get("style_markers") or [])[: TEXT_LIMITS["top_list"]],
+                "digg_count": item.get("digg_count"),
+                "comment_count": item.get("comment_count"),
+                "collect_count": item.get("collect_count"),
+                "share_count": item.get("share_count"),
+                "play_count": item.get("play_count"),
+            }
+        )
+
+    compacted_deltas: Dict[str, Any] = {}
+    for group in ("top", "mid", "bottom"):
+        block = deltas.get(group) if isinstance(deltas, dict) else None
+        if not isinstance(block, dict):
+            continue
+        compacted_deltas[group] = {
+            "title_keywords": list(block.get("title_keywords") or [])[: TEXT_LIMITS["top_list"]],
+            "caption_keywords": list(block.get("caption_keywords") or [])[: TEXT_LIMITS["top_list"]],
+            "primary_text_keywords": list(block.get("primary_text_keywords") or [])[: TEXT_LIMITS["top_list"]],
+            "hook_types": list(block.get("hook_types") or [])[: TEXT_LIMITS["top_list"]],
+            "structure_types": list(block.get("structure_types") or [])[: TEXT_LIMITS["top_list"]],
+            "cta_types": list(block.get("cta_types") or [])[: TEXT_LIMITS["top_list"]],
+            "content_forms": list(block.get("content_forms") or [])[: TEXT_LIMITS["top_list"]],
+        }
+
+    return {
+        "sampled_works": compacted_sampled,
+        "aggregate_deltas": compacted_deltas,
+    }
+
+
+def _build_prompt(analysis_input: Dict[str, Any]) -> str:
+    compacted = _compact_input(analysis_input)
+    return (
+        "请严格根据以下提示词原文输出，结果必须是 JSON 对象，且只输出 JSON。\n"
+        "顶层对象必须是 sampled_work_explanations。\n"
+        "不得输出 markdown，不得输出解释。\n\n"
+        "=== 提示词原文开始 ===\n"
+        f"{_prompt_contract_text()}\n"
+        "=== 提示词原文结束 ===\n\n"
+        "=== 输入数据(JSON) ===\n"
+        f"{json.dumps(compacted, ensure_ascii=False)}"
+    )
+
+
+def _fallback_explanations(analysis_input: Dict[str, Any]) -> Dict[str, Any]:
+    sampled = analysis_input.get("sampled_works") if isinstance(analysis_input.get("sampled_works"), list) else []
+    explanations: Dict[str, Any] = {}
+    for item in sampled:
+        if not isinstance(item, dict):
+            continue
+        work_id = _safe_text(item.get("platform_work_id"))
+        if not work_id:
+            continue
+        explanations[work_id] = {
+            "why_it_worked_or_failed": f"该样本主要依赖 { _safe_text(item.get('hook_type')) or 'hook' }、{ _safe_text(item.get('structure_type')) or 'structure' } 与 { _safe_text(item.get('content_form')) or 'content_form' } 的组合。",
+            "copyable_elements": [value for value in [_safe_text(item.get("hook_type")), _safe_text(item.get("structure_type")), _safe_text(item.get("cta_type"))] if value],
+            "non_copyable_elements": ["具体个人经历或原始案例背书"],
+            "emotional_triggers": [_safe_text(item.get("hook_type")) or "结果预期"],
+            "cognitive_gap": "观众想知道为什么这个结构能成立，以及自己如何快速套用。",
+            "commercial_signal": "从 CTA 与内容结构看，具备基础商业承接意图，但证据仍有限。",
+        }
+    return {"sampled_work_explanations": explanations}
+
+
+def _coverage_errors(payload: Dict[str, Any], analysis_input: Dict[str, Any]) -> List[Dict[str, str]]:
+    sampled = analysis_input.get("sampled_works") if isinstance(analysis_input.get("sampled_works"), list) else []
+    explanations = payload.get("sampled_work_explanations") if isinstance(payload.get("sampled_work_explanations"), dict) else {}
+    errors: List[Dict[str, str]] = []
+    for item in sampled:
+        if not isinstance(item, dict):
+            continue
+        work_id = _safe_text(item.get("platform_work_id"))
+        if not work_id:
+            continue
+        if not isinstance(explanations.get(work_id), dict):
+            errors.append({"field": f"sampled_work_explanations.{work_id}", "reason": "missing_work_explanation"})
+    return errors
+
+
+def run_sampled_work_batch_explanations(analysis_input: Dict[str, Any]) -> Tuple[Dict[str, Any], List[Dict[str, str]], List[Dict[str, Any]]]:
+    sampled = analysis_input.get("sampled_works") if isinstance(analysis_input.get("sampled_works"), list) else []
+    trace: List[Dict[str, Any]] = [
+        {
+            "step": "sampled_work_explanations.input_built",
+            "sampled_works_count": len(sampled),
+            "prompt_contract": "prompt-contracts/sampled-work-batch-explanations.md@v1",
+        }
+    ]
+
+    if not sampled:
+        trace.append({"step": "sampled_work_explanations.skipped", "reason": "empty_sampled_works"})
+        return {"sampled_work_explanations": {}}, [], trace
+
+    llm_timeout_sec = max(int(os.getenv("TIKOMNI_SAMPLED_EXPLANATION_TIMEOUT_SEC", str(DEFAULT_TIMEOUT_SEC))), 5)
+    prompt = _build_prompt(analysis_input)
+    result: Dict[str, Any] = {}
+    errors: List[Dict[str, str]] = []
+
+    try:
+        run = subprocess.run(
+            ["openclaw", "agent", "--agent", "main", "--message", prompt, "--json"],
+            capture_output=True,
+            text=True,
+            timeout=llm_timeout_sec,
+            check=False,
+        )
+        parsed = json.loads(run.stdout or "{}")
+        chunks: List[str] = []
+        for item in parsed.get("result", {}).get("payloads", []):
+            if isinstance(item, dict) and isinstance(item.get("text"), str):
+                chunks.append(item["text"])
+        response_text = "\n".join(chunks).strip()
+        result = _extract_json_block(response_text)
+        trace.append(
+            {
+                "step": "sampled_work_explanations.llm_called",
+                "returncode": run.returncode,
+                "has_text": bool(response_text),
+                "parsed": bool(result),
+                "stdout_chars": len(run.stdout or ""),
+                "stderr_chars": len(run.stderr or ""),
+            }
+        )
+    except Exception as error:
+        trace.append({"step": "sampled_work_explanations.llm_error", "error": f"{type(error).__name__}:{error}"})
+
+    errors = _schema_errors(result) if result else [{"field": "$", "reason": "empty_result"}]
+    if not errors:
+        errors.extend(_coverage_errors(result, analysis_input))
+    if errors:
+        fallback = _fallback_explanations(analysis_input)
+        fallback_errors = _schema_errors(fallback) + _coverage_errors(fallback, analysis_input)
+        trace.append(
+            {
+                "step": "sampled_work_explanations.fallback_used",
+                "reason": "llm_empty_or_validation_failed",
+                "validation_error_count": len(errors),
+                "fallback_error_count": len(fallback_errors),
+            }
+        )
+        return fallback, errors + fallback_errors, trace
+
+    trace.append({"step": "sampled_work_explanations.schema_validation_passed"})
+    return result, [], trace

package/skills/creator-analysis/scripts/author_home/asr/__init__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+
+from .home_asr import enrich_author_home_asr
+
+__all__ = ["enrich_author_home_asr"]