@adgine/geo-cli 1.2.8

package/skills/adgine-geo-topics/scripts/generate_prompts.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""AI-powered bulk prompt generation for a GEO topic (async job).
+
+Starts a generate-prompts job, polls until completed (~1–3 min), and prints
+the generated prompts.
+
+Usage:
+  python3 scripts/generate_prompts.py --topic-id <id> [--project-id <id>] \
+    [--count 10] [--language "English (en-US)"] [--region US] \
+    [--platforms "openai,perplexity,google_aio"] \
+    [--instructions "Focus on enterprise buyers"] [--json]
+"""
+import sys
+import os
+import time
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post,
+    extract_data, print_json,
+)
+
+DEFAULT_PLATFORMS = ["openai", "google_aio", "perplexity"]
+
+parser = argparse.ArgumentParser(description="AI-generate prompts for a GEO topic")
+parser.add_argument("--topic-id", required=True, help="Topic ID to generate prompts for")
+parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--count", type=int, default=10,
+                    help="Number of prompts to generate, 1–50 (default: 10)")
+parser.add_argument("--language", default="English (en-US)",
+                    help="Language for generated prompts (default: English (en-US))")
+parser.add_argument("--region", default="US",
+                    help="Target region code (default: US)")
+parser.add_argument("--platforms",
+                    help=f"Comma-separated platform IDs (default: {', '.join(DEFAULT_PLATFORMS)}). "
+                         "Valid values: openai, google_aio, perplexity")
+parser.add_argument("--instructions",
+                    help="Additional instructions to guide prompt generation")
+parser.add_argument("--json", action="store_true", help="Output raw JSON task result")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+platforms = DEFAULT_PLATFORMS
+if args.platforms:
+    platforms = [p.strip() for p in args.platforms.split(",") if p.strip()]
+
+if not (1 <= args.count <= 50):
+    print("ERROR: --count must be between 1 and 50")
+    sys.exit(1)
+
+print(f"Starting AI prompt generation for topic: {args.topic_id}")
+print(f"  Count     : {args.count}")
+print(f"  Language  : {args.language}  |  Region: {args.region}")
+print(f"  Platforms : {', '.join(platforms)}")
+print()
+
+body = {
+    "count":    args.count,
+    "language": args.language,
+    "region":   args.region,
+    "platforms": platforms,
+}
+if args.instructions:
+    body["additional_instructions"] = args.instructions
+
+result = api_post(
+    f"/api/projects/{pid}/topics/{args.topic_id}/generate-prompts",
+    key, base, body
+)
+task_data = extract_data(result)
+task_id = task_data.get("task_id") or task_data.get("id")
+
+if not task_id:
+    print("ERROR: Generate-prompts endpoint did not return a task ID.")
+    print_json(task_data)
+    sys.exit(1)
+
+print(f"Task ID: {task_id}")
+print("Polling for completion (this typically takes 1–3 minutes)...")
+
+# Poll the task status endpoint
+frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+elapsed = 0
+max_wait = 600
+interval = 5
+idx = 0
+final_task = None
+
+while elapsed < max_wait:
+    status_result = api_get(
+        f"/api/projects/{pid}/topics/{args.topic_id}/generate-prompts/{task_id}",
+        key, base
+    )
+    task = extract_data(status_result)
+    status = task.get("status", "")
+    phase  = task.get("current_phase") or status
+    count_so_far = task.get("generated_count", "")
+    label  = f"{phase} ({count_so_far} generated)" if count_so_far else phase
+    print(f"\r  {frames[idx % len(frames)]} {label}...", end="", flush=True)
+    idx += 1
+
+    if status in ("completed", "failed", "done", "success", "error"):
+        print()
+        final_task = task
+        break
+    time.sleep(interval)
+    elapsed += interval
+
+if final_task is None:
+    print()
+    print(f"WARNING: Task still running after {max_wait}s.")
+    print(f"  Check status manually:")
+    print(f"  GET /api/projects/{pid}/topics/{args.topic_id}/generate-prompts/{task_id}")
+    sys.exit(0)
+
+if args.json:
+    print_json(final_task)
+    sys.exit(0)
+
+if final_task.get("status") == "failed":
+    print(f"ERROR: Prompt generation failed — {final_task.get('error', 'unknown error')}")
+    sys.exit(1)
+
+prompts = final_task.get("prompts") or []
+print(f"\nGenerated {len(prompts)} prompts for topic {args.topic_id}:")
+print()
+for i, p in enumerate(prompts, 1):
+    content = p.get("content", "")
+    prompt_id = p.get("id", "")
+    print(f"  {i:>2}. [{prompt_id[:36]}]")
+    print(f"      {content}")
+    print()
+
+print(f"These prompts are ready for:")
+print(f"  - Citation testing : use the geo-citation skill → python3 scripts/create_tests.py --prompt-ids <id1,id2,...>")
+print(f"  - Article outlines : use the geo-content skill  → python3 scripts/generate_outline.py --topic-id {args.topic_id} --prompt-ids <id1,id2,...>")

package/skills/adgine-geo-topics/scripts/manage_prompts.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""List, create, update, or delete prompts within a GEO topic.
+
+Usage:
+  python3 scripts/manage_prompts.py list     --topic-id <tid> [--project-id <id>] [--json]
+  python3 scripts/manage_prompts.py list-all [--project-id <id>] [--json]
+  python3 scripts/manage_prompts.py create   --topic-id <tid> --content "What is...?" \
+                                            [--language "English (en-US)"] [--region US] \
+                                            [--platforms "ChatGPT,Perplexity,Google AI Overviews"]
+  python3 scripts/manage_prompts.py update   --topic-id <tid> --prompt-id <pid> --content "..."
+  python3 scripts/manage_prompts.py delete   --topic-id <tid> --prompt-id <pid>
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post, api_put, api_delete,
+    extract_data, print_json,
+)
+
+parser = argparse.ArgumentParser(description="Manage GEO prompts")
+parser.add_argument("action", choices=["list", "list-all", "get", "create", "update", "delete"])
+parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--topic-id",   help="Topic ID")
+parser.add_argument("--prompt-id",  help="Prompt ID (required for update/delete)")
+parser.add_argument("--content",    help="Prompt text content")
+parser.add_argument("--language",   default="English (en-US)", help="Language (default: English (en-US))")
+parser.add_argument("--region",     default="US", help="Region code (default: US)")
+parser.add_argument("--platforms",  help="Comma-separated platform IDs (e.g. openai,perplexity,google_aio)")
+parser.add_argument("--json", action="store_true", help="Output raw JSON")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+def _fmt_platforms(platforms_list):
+    if not platforms_list:
+        return "—"
+    return ", ".join(platforms_list)[:60]
+
+# ── LIST (by topic) ───────────────────────────────────────────────────────────
+if args.action == "list":
+    if not args.topic_id:
+        print("ERROR: --topic-id is required for list")
+        sys.exit(1)
+    result = api_get(f"/api/projects/{pid}/topics/{args.topic_id}/prompts", key, base)
+    data = extract_data(result)
+    items = data if isinstance(data, list) else data.get("items") or data.get("prompts") or []
+    if args.json:
+        print_json(data)
+        sys.exit(0)
+    print(f"Prompts for topic {args.topic_id}  ({len(items)} found)")
+    print()
+    for p in items:
+        print(f"  ID: {p.get('id', '')[:36]}")
+        content = p.get("content", "")
+        print(f"  {content[:120]}{'...' if len(content) > 120 else ''}")
+        print(f"  Platforms: {_fmt_platforms(p.get('platforms'))}")
+        print()
+
+# ── LIST-ALL (project-wide) ───────────────────────────────────────────────────
+elif args.action == "list-all":
+    result = api_get(f"/api/projects/{pid}/prompts", key, base)
+    data = extract_data(result)
+    items = data if isinstance(data, list) else data.get("items") or data.get("prompts") or []
+    if args.json:
+        print_json(data)
+        sys.exit(0)
+    total = data.get("total", len(items)) if isinstance(data, dict) else len(items)
+    print(f"All prompts in project {pid}  ({total} found)")
+    print()
+    for p in items:
+        content = p.get("content", "")
+        print(f"  [{p.get('id', '')[:36]}]  {content[:100]}{'...' if len(content) > 100 else ''}")
+
+# ── GET (detail) ──────────────────────────────────────────────────────────────
+elif args.action == "get":
+    if not args.topic_id or not args.prompt_id:
+        print("ERROR: --topic-id and --prompt-id are required for get")
+        sys.exit(1)
+    result = api_get(
+        f"/api/projects/{pid}/topics/{args.topic_id}/prompts/{args.prompt_id}",
+        key, base,
+    )
+    prompt = extract_data(result) or {}
+    if args.json:
+        print_json(prompt)
+        sys.exit(0)
+    print(f"Prompt detail: {args.prompt_id}")
+    print()
+    print(f"  Content   : {prompt.get('content', '')}")
+    print(f"  Language  : {prompt.get('language', '--')}")
+    print(f"  Region    : {prompt.get('region', '--')}")
+    print(f"  Platforms : {_fmt_platforms(prompt.get('platforms'))}")
+    print(f"  Created   : {prompt.get('created_at', '--')}")
+
+# ── CREATE ────────────────────────────────────────────────────────────────────
+elif args.action == "create":
+    if not args.topic_id:
+        print("ERROR: --topic-id is required for create")
+        sys.exit(1)
+    if not args.content:
+        print("ERROR: --content is required for create")
+        sys.exit(1)
+    body = {
+        "content":  args.content,
+        "language": args.language,
+        "region":   args.region,
+    }
+    if args.platforms:
+        body["platforms"] = [p.strip() for p in args.platforms.split(",") if p.strip()]
+    result = api_post(f"/api/projects/{pid}/topics/{args.topic_id}/prompts", key, base, body)
+    prompt = extract_data(result)
+    if args.json:
+        print_json(prompt)
+        sys.exit(0)
+    print(f"✓  Created prompt")
+    print(f"   ID      : {prompt.get('id')}")
+    print(f"   Content : {prompt.get('content', '')[:100]}")
+
+# ── UPDATE ────────────────────────────────────────────────────────────────────
+elif args.action == "update":
+    if not args.topic_id or not args.prompt_id:
+        print("ERROR: --topic-id and --prompt-id are required for update")
+        sys.exit(1)
+    if not args.content:
+        print("ERROR: --content is required for update")
+        sys.exit(1)
+    body = {"content": args.content}
+    result = api_put(
+        f"/api/projects/{pid}/topics/{args.topic_id}/prompts/{args.prompt_id}",
+        key, base, body
+    )
+    prompt = extract_data(result)
+    if args.json:
+        print_json(prompt)
+        sys.exit(0)
+    print(f"✓  Updated prompt {args.prompt_id}")
+    print(f"   Content : {prompt.get('content', '')[:100]}")
+
+# ── DELETE ────────────────────────────────────────────────────────────────────
+elif args.action == "delete":
+    if not args.topic_id or not args.prompt_id:
+        print("ERROR: --topic-id and --prompt-id are required for delete")
+        sys.exit(1)
+    api_delete(
+        f"/api/projects/{pid}/topics/{args.topic_id}/prompts/{args.prompt_id}",
+        key, base
+    )
+    print(f"✓  Deleted prompt {args.prompt_id}")

package/skills/adgine-geo-topics/scripts/manage_topics.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""List, create, batch-create, update, or delete GEO topics.
+
+Usage:
+  python3 scripts/manage_topics.py list   [--project-id <id>] [--page 1] [--limit 20] [--json]
+  python3 scripts/manage_topics.py create --name "Product Reviews" [--description "..."]
+  python3 scripts/manage_topics.py batch  --names "Topic A,Topic B,Topic C"
+  python3 scripts/manage_topics.py update --topic-id <id> [--name "..."] [--description "..."]
+  python3 scripts/manage_topics.py delete --topic-id <id>
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post, api_put, api_delete,
+    extract_data, print_json,
+)
+
+parser = argparse.ArgumentParser(description="Manage GEO topics")
+parser.add_argument("action", choices=["list", "get", "create", "batch", "update", "delete"])
+parser.add_argument("--project-id",  help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--topic-id",    help="Topic ID (required for update/delete)")
+parser.add_argument("--name",        help="Topic name")
+parser.add_argument("--description", help="Topic description")
+parser.add_argument("--names",       help="Comma-separated names for batch create")
+parser.add_argument("--page",  type=int, default=1,  help="Page number (list only)")
+parser.add_argument("--limit", type=int, default=20, help="Results per page (list only)")
+parser.add_argument("--json", action="store_true", help="Output raw JSON")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+# ── LIST ─────────────────────────────────────────────────────────────────────
+if args.action == "list":
+    result = api_get(
+        f"/api/projects/{pid}/topics",
+        key, base,
+        params={"page": args.page, "limit": args.limit},
+    )
+    topics = extract_data(result)
+    items = topics if isinstance(topics, list) else topics.get("items") or topics.get("topics") or []
+
+    if args.json:
+        print_json(topics)
+        sys.exit(0)
+
+    total = topics.get("total", len(items)) if isinstance(topics, dict) else len(items)
+    print(f"Topics ({len(items)} of {total})  |  project: {pid}")
+    print()
+    if not items:
+        print("  No topics found. Create one with: python3 scripts/manage_topics.py create --name \"...\"")
+    else:
+        print(f"  {'ID':<38}  {'Name':<30}  {'Prompts':>7}  Description")
+        print(f"  {'-'*38}  {'-'*30}  {'-'*7}  {'-'*30}")
+        for t in items:
+            tid    = t.get("id", "")[:36]
+            name   = (t.get("name") or "")[:30]
+            count  = t.get("prompt_count", 0)
+            desc   = (t.get("description") or "")[:40]
+            print(f"  {tid:<38}  {name:<30}  {count:>7}  {desc}")
+
+# ── GET (detail) ─────────────────────────────────────────────────────────────
+elif args.action == "get":
+    if not args.topic_id:
+        print("ERROR: --topic-id is required for get")
+        sys.exit(1)
+    result = api_get(f"/api/projects/{pid}/topics/{args.topic_id}", key, base)
+    topic = extract_data(result) or {}
+    if args.json:
+        print_json(topic)
+        sys.exit(0)
+    print(f"Topic detail: {args.topic_id}")
+    print()
+    print(f"  Name        : {topic.get('name', '')}")
+    print(f"  Description : {topic.get('description', '') or '--'}")
+    print(f"  Prompts     : {topic.get('prompt_count', 0)}")
+    print(f"  Created     : {topic.get('created_at', '--')}")
+
+# ── CREATE ────────────────────────────────────────────────────────────────────
+elif args.action == "create":
+    if not args.name:
+        print("ERROR: --name is required for create")
+        sys.exit(1)
+    body = {"name": args.name}
+    if args.description:
+        body["description"] = args.description
+    result = api_post(f"/api/projects/{pid}/topics", key, base, body)
+    topic = extract_data(result)
+    if args.json:
+        print_json(topic)
+        sys.exit(0)
+    print(f"✓  Created topic: {topic.get('name')}")
+    print(f"   ID: {topic.get('id')}")
+
+# ── BATCH CREATE ──────────────────────────────────────────────────────────────
+elif args.action == "batch":
+    if not args.names:
+        print("ERROR: --names is required (comma-separated list of topic names)")
+        sys.exit(1)
+    name_list = [n.strip() for n in args.names.split(",") if n.strip()]
+    if not name_list:
+        print("ERROR: --names must contain at least one topic name")
+        sys.exit(1)
+    body = {"topics": [{"name": n} for n in name_list]}
+    result = api_post(f"/api/projects/{pid}/topics/batch", key, base, body)
+    created = extract_data(result)
+    if args.json:
+        print_json(created)
+        sys.exit(0)
+    items = created if isinstance(created, list) else created.get("topics") or created.get("items") or []
+    print(f"✓  Created {len(items)} topics:")
+    for t in items:
+        print(f"   {t.get('id', '')[:36]}  {t.get('name', '')}")
+
+# ── UPDATE ────────────────────────────────────────────────────────────────────
+elif args.action == "update":
+    if not args.topic_id:
+        print("ERROR: --topic-id is required for update")
+        sys.exit(1)
+    body = {}
+    if args.name:
+        body["name"] = args.name
+    if args.description:
+        body["description"] = args.description
+    if not body:
+        print("ERROR: Provide at least one of --name or --description to update")
+        sys.exit(1)
+    result = api_put(f"/api/projects/{pid}/topics/{args.topic_id}", key, base, body)
+    topic = extract_data(result)
+    if args.json:
+        print_json(topic)
+        sys.exit(0)
+    print(f"✓  Updated topic: {topic.get('name')}")
+
+# ── DELETE ────────────────────────────────────────────────────────────────────
+elif args.action == "delete":
+    if not args.topic_id:
+        print("ERROR: --topic-id is required for delete")
+        sys.exit(1)
+    api_delete(f"/api/projects/{pid}/topics/{args.topic_id}", key, base)
+    print(f"✓  Deleted topic {args.topic_id}")

package/skills/adgine-geo-visibility/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: adgine/geo-visibility
+description: Reads and analyzes already-collected AI visibility data for a GEO
+  project — Visibility Score, Share of Voice, Average Position, competitor matrix,
+  historical AI executions, full AI responses, brand mentions, cited URLs.
+  Use when the user wants to READ analytics results: AI visibility / 可见性得分 /
+  Visibility Score / 声量份额 / Share of Voice / 平均排名 / 竞品对比 / 平台矩阵 /
+  AI 回答历史 / prompt 历史测试 / AI 具体怎么回复的 / 品牌提及 / 引用链接.
+  NOT for running new citation tests (向 AI 平台发请求测试是否引用) — use
+  adgine-geo-citation to actively submit prompts and collect new results.
+  NOT for lightweight dashboard summary — use adgine-geo-dashboard instead.
+---
+
+# GEO Visibility (Analytics)
+
+Deep analytics over `/api/projects/{id}/analytics/*` — 11 endpoints covering
+the AI visibility funnel from brand-level single metrics down to individual
+prompt executions.
+
+> Lightweight dashboard summary lives in **adgine-geo-dashboard**.
+> Prompt CRUD / start-analysis actions live in **adgine-geo-topics**.
+
+## 触发条件
+
+当用户说出以下意图时使用本 skill：
+- “可见性得分” / “Visibility Score” / “我的可见度”
+- “声量份额” / “Share of Voice” / “平均排名” / “Average Position”
+- “竞品对比” / “平台矩阵” / “competitor matrix”
+- “AI 回答历史” / “AI 具体怎么回复的” / “prompt 历史测试结果”
+- “品牌提及” / “引用链接”（查看已有数据）
+
+**⛔ 以下意图不属于本 skill：**
+- “跑一次引用测试” / “测试 AI 是否引用”（发起新测试）→ **adgine-geo-citation**
+- “项目总览” / “Dashboard” / “近七天趋势” → **adgine-geo-dashboard**
+- “创建提示词” / “管理主题” → **adgine-geo-topics**
+
+## Output rules — IDs (apply to every reply)
+
+These rules apply to **every list, table, and confirmation message** in this skill. Their goal: keep user-facing output friendly while preserving the IDs the agent needs internally.
+
+1. **Lists & tables — never show raw UUIDs in cells.** Use a 1-based `#` index column instead. Keep a private mental mapping of `#N → actual UUID` so that follow-up commands like *"delete #3"*, *"run citation test on #1 #2"*, *"show details of the 2nd one"* resolve to the right entity.
+   - Index numbers restart from 1 in each new list — they are not stable across calls.
+   - If the user references *"the topic about X"* / *"that Poki vs CrazyGames prompt"*, match by visible content (name / title / domain / prompt text), not by ID.
+
+2. **Single-item operations — prefer a human name over an ID.**
+   - ✅ *"Project **Poki vs Competitors** deleted."*
+   - ✅ *"Topic **Brand mentions in 2024** updated — name → 'Brand mentions 2025'."*
+   - ❌ *"Project `a4305b57-1c79-4cec-a17c-16eb1d959ea6` deleted."*
+   - If the entity has **no human-readable name** (e.g. an anonymous prompt or a job), use a short 8-character prefix: *"Prompt `2a2a8f4f…` deleted."* Never paste the full UUID.
+
+3. **Always exception: `--json` mode.** When the user passes `--json` to a script or explicitly asks for raw JSON / debug output, print the script output verbatim — do not strip IDs.
+
+4. **Internally, the agent still uses full UUIDs** for every API call (`--project-id`, `--topic-id`, `--prompt-id`, etc.). The display rules only affect what is shown back to the user.
+
+---
+
+## Step 1: Make sure GEO_API_KEY is configured
+
+Scripts auto-load `GEO_API_KEY` from `<skills-root>/.env` on import — **no `export` needed, no shell restart needed**. To check the configuration, run any script (it prints the exact `.env` path if the key is missing).
+
+- ✅ Key already in `<skills-root>/.env` → proceed.
+- ❌ Key missing, or user just gave you a new key → go to the **adgine-geo-projects** skill, **Step 0**, which runs `python3 <skills-root>/setup.py <KEY>` to write the key into the correct `.env` file. **Never** write the key to `~/.zshrc`, `~/.bashrc`, Hermes global config, or any user-secrets store.
+
+> ⚠️ **IMPORTANT:** In all shell/exec commands, always reference the key as `$GEO_API_KEY` (the environment variable). Never hardcode the literal value.
+
+## Project selection
+
+```bash
+export GEO_PROJECT_ID=<project-id>
+```
+
+## Scripts
+
+### Brand-level single metrics
+
+```bash
+python3 scripts/get_visibility.py score
+python3 scripts/get_visibility.py share-of-voice
+python3 scripts/get_visibility.py average-position
+# common opts: --platform openai|google_aio|perplexity|gemini --start ... --end ...
+```
+
+### Competitor × platform matrix
+
+```bash
+python3 scripts/get_matrix.py                 # default: visibility metric
+python3 scripts/get_matrix.py --metric sov
+```
+
+### Topic-level metrics
+
+```bash
+python3 scripts/get_topic_metrics.py list                         # full Topic dimension
+python3 scripts/get_topic_metrics.py visibility                   # lightweight picker list
+python3 scripts/get_topic_metrics.py prompts --topic-id <id>      # prompts under topic
+python3 scripts/get_topic_metrics.py prompts-visibility --topic-id <id>
+```
+
+### Per-prompt overview
+
+```bash
+python3 scripts/get_prompt_metrics.py --prompt-id <prompt_id>
+# adds: previous-period delta + per-platform breakdown
+```
+
+### Prompt execution history & detail
+
+```bash
+python3 scripts/get_execution.py list --prompt-id <prompt_id>
+python3 scripts/get_execution.py list --prompt-id <pid> --platform openai
+python3 scripts/get_execution.py get --prompt-id <pid> --execution-id <eid>
+```
+
+## Output Format
+
+ASCII tables only inside fenced code blocks. Numeric formatting: 1 or 2
+decimals depending on metric scale; "%" suffix for percentage metrics;
+"--" for null. Change-from-previous-period is shown with explicit sign
+("+1.5" / "-0.3").
+
+## Metric vocabulary
+
+| Metric            | Unit | Typical range |
+|---|---|---|
+| Visibility Score  | %    | 0–100  |
+| Share of Voice    | %    | 0–100  |
+| Average Position  | rank | 1+ (lower is better) |
+
+## Platform codes
+
+`openai` · `google_aio` · `perplexity` · `gemini`
+
+## Related endpoints
+
+| Method | Path |
+|---|---|
+| GET | `/api/projects/{id}/analytics/visibility/score` |
+| GET | `/api/projects/{id}/analytics/visibility/share-of-voice` |
+| GET | `/api/projects/{id}/analytics/visibility/average-position` |
+| GET | `/api/projects/{id}/analytics/platforms/matrix` |
+| GET | `/api/projects/{id}/analytics/topics` |
+| GET | `/api/projects/{id}/analytics/topics/visibility` |
+| GET | `/api/projects/{id}/analytics/topics/{topic_id}/prompts` |
+| GET | `/api/projects/{id}/analytics/topics/{topic_id}/prompts/visibility` |
+| GET | `/api/projects/{id}/analytics/prompts/{prompt_id}/overview` |
+| GET | `/api/projects/{id}/analytics/prompts/{prompt_id}/executions` |
+| GET | `/api/projects/{id}/analytics/prompts/{prompt_id}/executions/{execution_id}` |
+
+---
+
+## Post-task recommendations
+
+After visibility analysis, suggest actions to improve or act on the results:
+
+| What you saw | → use skill (agent-internal) |
+|---|---|
+| Low Visibility Score | 运行新引用测试，诊断哪些平台未引用 *(→ adgine-geo-citation)*|
+| Low Share of Voice | 针对弱项话题生成更多 GEO 内容 *(→ adgine-geo-content)*|
+| Competitor outperforming | 优化品牌画像，强化差异化定位 *(→ adgine-geo-brand)*|
+| Specific prompt performing well | 基于该 prompt 生成扩展文章 *(→ adgine-geo-content)*|
+| Specific prompt performing poorly | 优化或替换该 prompt *(→ adgine-geo-topics)*|
+| Execution history reviewed | 查看对应页面的 AI 爬虫访问数据 *(→ adgine-geo-aiagent)*|
+
+**⚠️ Output rule:** Do NOT write skill names (e.g. `adgine-geo-xxx`) in user-facing suggestions. Each suggestion must be phrased as a natural-language prompt the user can copy and send directly to the agent.
+
+> 💡 **建议下一步：**
+> 1. **[行动标题]** — *"[可直接发送给 AI 的自然语言提示词]"*
+> 2. **[行动标题]** — *"[可直接发送给 AI 的自然语言提示词]"*