@adgine/geo-cli 1.2.8

package/skills/adgine-geo-dashboard/scripts/get_overview.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Fetch the project dashboard overview snapshot.
+
+Returns the aggregate dashboard metrics for a project (visibility, prompts,
+topics, test counts, etc.) for the requested period.
+
+Usage:
+  python3 scripts/get_overview.py [--project-id <id>] [--period 30d] [--json]
+"""
+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, extract_data, print_json, fmt_change,
+    pad,
+)
+
+
+def _scalar(obj, key, default=None):
+    """Extract a scalar that may be wrapped in {value, change} or returned plain."""
+    if not isinstance(obj, dict):
+        return default
+    v = obj.get(key)
+    if isinstance(v, dict) and "value" in v:
+        return v.get("value", default)
+    return v if v is not None else default
+
+
+def _delta(obj, key):
+    """Extract the change delta from a {value, change} wrapper, or return None."""
+    if not isinstance(obj, dict):
+        return None
+    v = obj.get(key)
+    if isinstance(v, dict):
+        return v.get("change")
+    return None
+
+
+def _fmt_num(n):
+    if n is None:
+        return "--"
+    try:
+        f = float(n)
+    except (TypeError, ValueError):
+        return str(n)
+    if f == int(f):
+        return f"{int(f):,}"
+    return f"{f:,.1f}"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fetch GEO project dashboard overview")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--period", default="30d", choices=["7d", "14d", "30d", "90d"],
+                        help="Time period (default: 30d)")
+    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)
+
+    result = api_get(
+        f"/api/projects/{pid}/dashboard/overview",
+        key, base,
+        params={"period": args.period},
+    )
+    data = extract_data(result) or {}
+
+    if args.json:
+        print_json(data)
+        return
+
+    period = data.get("period", args.period)
+    dr = data.get("date_range") or {}
+    start = dr.get("start", "--")
+    end = dr.get("end", "--")
+
+    print(f"Dashboard Overview  —  {start} to {end}  ({period})")
+    print(f"Project: {pid}")
+    print()
+
+    # ── Snapshot metrics ──────────────────────────────────────────────────
+    # The dashboard/overview payload aggregates several top-level metric
+    # groups. We render whichever ones are present, with graceful fallback.
+    metric_keys = [
+        ("visibility_score", "Visibility Score"),
+        ("prompts_total",    "Prompts (total)"),
+        ("prompts_tested",   "Prompts tested"),
+        ("topics_total",     "Topics"),
+        ("tests_total",      "Tests run"),
+        ("citations_total",  "Citations"),
+        ("articles_total",   "Articles"),
+        ("ai_referrals",     "AI referrals"),
+    ]
+    rows = []
+    for k, label in metric_keys:
+        if k in data:
+            rows.append((label, _scalar(data, k), _delta(data, k)))
+
+    if rows:
+        print("Snapshot")
+        print("```")
+        print("┌────────────────────────┬──────────┬──────────┐")
+        print("│ Metric                 │    Value │ vs Prev  │")
+        print("├────────────────────────┼──────────┼──────────┤")
+        for label, val, change in rows:
+            print(f"│ {pad(label, 22)} │ {_fmt_num(val):>8} │ {fmt_change(change):>8} │")
+        print("└────────────────────────┴──────────┴──────────┘")
+        print("```")
+        print()
+
+    # ── Top lists (if present) ────────────────────────────────────────────
+    for list_key, title, name_field, value_field, value_label in [
+        ("top_topics",   "Top Topics",       "name",    "score",     "Score"),
+        ("top_prompts",  "Top Prompts",      "text",    "score",     "Score"),
+        ("recent_tests", "Recent Tests",     "prompt",  "platform",  "Platform"),
+    ]:
+        items = data.get(list_key) or []
+        if not items:
+            continue
+        print(f"{title}")
+        print("```")
+        print("┌────┬────────────────────────────────────────┬──────────┐")
+        print(f"│  # │ {pad('Name', 38)} │ {pad(value_label, 8)} │")
+        print("├────┼────────────────────────────────────────┼──────────┤")
+        for idx, item in enumerate(items[:5], 1):
+            name = str(item.get(name_field, ""))
+            value = str(item.get(value_field, ""))
+            if len(name) > 38:
+                name = name[:37] + "…"
+            print(f"│ {idx:>2} │ {pad(name, 38)} │ {pad(value, 8)} │")
+        print("└────┴────────────────────────────────────────┴──────────┘")
+        print("```")
+        print()
+
+    # ── Fallback: dump unknown top-level keys ─────────────────────────────
+    if not rows:
+        print("Raw snapshot keys:")
+        for k, v in data.items():
+            if k in ("period", "date_range"):
+                continue
+            if isinstance(v, (str, int, float, bool)) or v is None:
+                print(f"  {k}: {v}")
+            elif isinstance(v, list):
+                print(f"  {k}: list[{len(v)}]")
+            elif isinstance(v, dict):
+                print(f"  {k}: dict({', '.join(v.keys())})")
+        print()
+        print("Tip: rerun with --json to see the full payload.")
+
+
+if __name__ == "__main__":
+    main()

package/skills/adgine-geo-dashboard/scripts/get_visibility_overview.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Fetch the lightweight 7-day brand visibility snapshot.
+
+Returns current visibility score, 7-day daily trend and period-over-period change.
+
+Usage:
+  python3 scripts/get_visibility_overview.py [--project-id <id>] \\
+      [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--json]
+"""
+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, extract_data, print_json, fmt_change,
+    pad,
+)
+
+
+def _fmt_score(n):
+    if n is None:
+        return "--"
+    try:
+        return f"{float(n):.1f}"
+    except (TypeError, ValueError):
+        return str(n)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fetch GEO visibility overview")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--start-date", help="Start date YYYY-MM-DD")
+    parser.add_argument("--end-date", help="End date YYYY-MM-DD")
+    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)
+
+    params = {}
+    if args.start_date:
+        params["start_date"] = args.start_date
+    if args.end_date:
+        params["end_date"] = args.end_date
+
+    result = api_get(
+        f"/api/projects/{pid}/dashboard/visibility",
+        key, base,
+        params=params or None,
+    )
+    data = extract_data(result) or {}
+
+    if args.json:
+        print_json(data)
+        return
+
+    current = data.get("current_score")
+    change = data.get("change") or data.get("score_change")
+    trend = data.get("daily_scores") or data.get("trend") or []
+
+    print(f"Visibility Overview")
+    print(f"Project: {pid}")
+    print()
+
+    print("```")
+    print("┌────────────────────────┬──────────┐")
+    print("│ Metric                 │    Value │")
+    print("├────────────────────────┼──────────┤")
+    print(f"│ Current Score          │ {_fmt_score(current):>8} │")
+    print(f"│ Change vs Prev         │ {fmt_change(change):>8} │")
+    print("└────────────────────────┴──────────┘")
+    print("```")
+    print()
+
+    if trend:
+        print("7-Day Trend")
+        print("```")
+        print("┌────────────┬──────────┐")
+        print("│ Date       │    Score │")
+        print("├────────────┼──────────┤")
+        for point in trend[:14]:
+            date = str(point.get("date", "--"))[:10]
+            score = _fmt_score(point.get("score"))
+            print(f"│ {pad(date, 10)} │ {score:>8} │")
+        print("└────────────┴──────────┘")
+        print("```")
+    else:
+        print("No daily trend data available for the requested range.")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,60 @@
+---
+name: adgine/geo-docs
+description: Provides the Adgine platform user manual (使用手册). Use when the user asks how to use Adgine, needs help documentation, asks for the user guide, or mentions 使用手册, 帮助文档, 产品说明, user manual, documentation, help guide, how to use, 怎么用, 操作指南, 教程. This skill points to the official Adgine user manual hosted online (PDF). No API key required.
+---
+
+# GEO Docs — Adgine 使用手册
+
+This skill provides access to the official Adgine platform user manual, hosted online.
+
+## No authentication required
+
+This skill needs no `GEO_API_KEY`. The manual is hosted at a public URL — the agent
+simply outputs the link (and may fetch the URL when answering specific content questions).
+
+## Manual location
+
+**Online manual (PDF):** https://docs.adgine.ai/files/Adgine使用手册-v20260531.pdf
+
+**Current version:** v20260531 (2025-05-31)
+
+## Usage
+
+### When the user asks to view or download the user manual (查看手册 / 下载手册 / 我要手册)
+
+**必须输出 PDF 的 Markdown 链接，让用户看到可点击的下载/预览按钮：**
+
+> ⚠️ **CRITICAL — 必须输出可点击的链接：**
+> 当用户说 "查看使用手册", "下载手册", "给我手册", "我要用户手册", "view manual", "download manual", "打开手册" 时：
+> 1. **必须** 输出 Markdown 格式的链接，让用户可以直接点击下载或预览
+> 2. **禁止** 仅输出纯文本 URL 让用户复制粘贴
+>
+> 正确做法 — 输出指向在线手册的 Markdown 链接：
+> ```markdown
+> [📄 Adgine使用手册-v20260531.pdf](https://docs.adgine.ai/files/Adgine使用手册-v20260531.pdf)
+> ```
+
+### When the user asks a specific question about how to use Adgine
+
+1. **Fetch** the online manual at `https://docs.adgine.ai/files/Adgine使用手册-v20260531.pdf` to find relevant content.
+2. **Answer** the user's question based on the manual content.
+3. **Reference** the PDF link so the user can view the full formatted manual.
+
+## Output Format
+
+### For view/download requests
+
+**直接输出以下内容（Markdown 链接 + 说明）：**
+
+> 📄 **Adgine 使用手册 (v20260531)**
+>
+> [点击下载/预览 PDF](https://docs.adgine.ai/files/Adgine使用手册-v20260531.pdf)
+>
+> 这是 Adgine 平台的完整使用手册，包含所有功能的详细操作指南。
+
+### For content questions
+
+- Provide a clear, concise answer based on the manual content
+- Quote relevant sections when helpful
+- Mention that this comes from the official Adgine 使用手册 (v20260531)
+- If the user wants more detail, suggest they review the full PDF manual at the link above

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

@@ -0,0 +1,223 @@
+---
+name: adgine/geo-domains
+description: Search available domains by keyword, list registered domains, and view domain registration details. Use when the user asks about domain availability, domain registration, domain search, 域名搜索, 域名注册, 查询域名, 我的域名, 域名状态. Read-only — does not register domains directly (direct users to the web UI for registration).
+---
+
+# GEO Domains
+
+Read-only access to domain search and your registered domains. Use this skill when the
+user asks "search domains for my brand" / "is example.com available?" / "show my
+domains" / "域名搜索" / "查询域名" / "我的域名" / "这个域名能注册吗".
+
+**Domain registration itself is done via the web UI** — after finding an available
+domain, this skill provides a clickable registration link.
+
+## 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 *"show details of #3"* resolve to the right entity.
+   - Index numbers restart from 1 in each new list — they are not stable across calls.
+
+2. **Single-item operations — prefer a human name over an ID.**
+   - ✅ *"Domain **example.com** — status: Active"*
+   - ❌ *"Domain `a4305b57-...` — status: Active"*
+
+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 (e.g.
+   `get_domain.py <domain_id>`). 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.
+
+---
+
+## Scripts
+
+### Search available domains by keyword
+
+```bash
+python3 scripts/search_domains.py <keyword> [--limit 20] [--json]
+```
+
+Searches for candidate domains matching the keyword. Returns availability status
+(`available` / `taken` / `unsupported`), pricing (registration + renewal, including
+service fees), and tier information.
+
+**For available domains**, the script outputs a `## 马上注册` section at the end with
+plain-text registration URLs in the format:
+`https://platform.adgine.ai/domains/contact?domain={domain_name}`
+
+> ⚠️ **YOU MUST include the full `## 马上注册` section verbatim in your reply.**
+> Do NOT omit, summarise, or reformat this section. The user needs these URLs to
+> register a domain. Simply copy-paste the entire section from the script output.
+
+Already-registered or unsupported domains do not show a registration link.
+
+### List my registered domains
+
+```bash
+python3 scripts/list_domains.py [--json]
+```
+
+Returns all domains registered by the current user, with status, expiration date,
+auto-renew setting, and DNS status.
+
+### Get domain registration details
+
+```bash
+python3 scripts/get_domain.py <domain_id> [--json]
+```
+
+Returns full details for a specific domain registration: Cloudflare state, Zone ID,
+pricing, DNS configuration status, and any error messages.
+
+---
+
+## Agent Output Format
+
+Run `search_domains.py <keyword>` (no `--json`). The script output uses a structured
+plain-text format with labelled fields — parse it and render the results as described
+below.
+
+### Script output format
+
+```
+DOMAIN_SEARCH_RESULTS keyword=<kw>
+
+TAKEN_DOMAINS count=N
+  TAKEN <name>
+  ...
+
+AVAILABLE_DOMAINS count=N
+  AVAILABLE name=<name> price=<price> renewal=<renewal> register_url=<url>
+  ...
+
+UNSUPPORTED_DOMAINS count=N
+  UNSUPPORTED <name>
+  ...
+```
+
+### How to render the results
+
+**⚠️ MANDATORY RULE: every `AVAILABLE` domain MUST be rendered with a clickable
+"[马上注册](register_url)" link. No exceptions. If a domain is available and you do
+not show its registration link, the user cannot register it.**
+
+Use this exact structure:
+
+---
+
+**❌ 已注册域名**
+
+| 域名 | 状态 |
+|------|------|
+| mybrand.com | ❌ 已注册 |
+
+---
+
+**🏆 推荐首选** — pick the `.com` from the AVAILABLE list (or the first available if no `.com`)
+
+| 域名 | 年费 | 续费 | |
+|------|------|------|---|
+| **mybrand.com** | $11.51 | $11.51/yr | [马上注册](https://platform.adgine.ai/domains/contact?domain=mybrand.com) |
+
+---
+
+**📋 其他可注册域名**
+
+| # | 域名 | 年费 | 续费 | |
+|---|------|------|------|---|
+| 2 | mybrand.net | $13.05 | $13.05/yr | [马上注册](https://platform.adgine.ai/domains/contact?domain=mybrand.net) |
+| 3 | mybrand.org | $9.35 | $12.32/yr | [马上注册](https://platform.adgine.ai/domains/contact?domain=mybrand.org) |
+
+---
+
+**💡 建议**
+
+推荐优先注册 `.com`。所有可注册域名：
+
+- [马上注册 mybrand.com](https://platform.adgine.ai/domains/contact?domain=mybrand.com)
+- [马上注册 mybrand.net](https://platform.adgine.ai/domains/contact?domain=mybrand.net)
+- [马上注册 mybrand.org](https://platform.adgine.ai/domains/contact?domain=mybrand.org)
+
+---
+
+The `register_url` value from the script output is the exact URL to use in the
+`[马上注册](URL)` links. Do not construct it yourself — copy it directly from the
+`register_url=` field in the script output.
+
+> 🌐 **我的域名**
+
+```
+┌────┬──────────────────────┬──────────┬──────────────────────┬──────────┬──────────┐
+│ #  │ Domain               │ Status   │ Expires              │ Renew    │ DNS      │
+├────┼──────────────────────┼──────────┼──────────────────────┼──────────┼──────────┤
+│ 1  │ mybrand.com          │ Active   │ 2027-06-16           │ Auto     │ OK       │
+│ 2  │ another-site.io      │ Pending  │ --                   │ Auto     │ Pending  │
+└────┴──────────────────────┴──────────┴──────────────────────┴──────────┴──────────┘
+```
+
+### get_domain.py
+
+> 🌐 **Domain: mybrand.com**
+
+```
+┌────────────────────┬──────────────────────────────────┐
+│ Field              │ Value                            │
+├────────────────────┼──────────────────────────────────┤
+│ Status             │ Active                           │
+│ Cloudflare State   │ registered                       │
+│ Zone ID            │ abc123...                        │
+│ Price              │ $12.99 USD                       │
+│ Expires            │ 2027-06-16                       │
+│ Auto Renew         │ Yes                              │
+│ DNS Status         │ configured                       │
+│ Created            │ 2026-06-16T10:00:00Z             │
+└────────────────────┴──────────────────────────────────┘
+```
+
+---
+
+## Registration Flow
+
+When the user has identified a domain they want to register, **do not attempt to
+register via API**. Instead, present the clickable registration link:
+
+```
+[注册 {domain_name}](https://platform.adgine.ai/domains/contact?domain={domain_name})
+```
+
+The user will complete the registration form (contact info, Stripe payment) on the web.
+
+---
+
+## Related endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/domains/search` | 按关键词搜索候选域名 |
+| GET | `/api/domains` | 当前用户的域名注册记录列表 |
+| GET | `/api/domains/{domain_id}` | 单条域名注册记录详情 |