@acedatacloud/skills 2026.628.6 → 2026.628.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.628.6",
+  "version": "2026.628.7",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/acedatacloud/SKILL.md

@@ -5,8 +5,11 @@ description: |
   (platform.acedata.cloud). Use when the user wants to check their balance /
   remaining credits, look up API call (usage) records and spend, list or create
   or delete API keys (credentials), list subscribed services, list/create/pay
-  recharge orders, manage platform tokens, list available models, or (admins)
-  publish an announcement. This is the self-service "console" API — distinct
+  recharge orders, manage platform tokens, view referral/affiliate earnings, or
+  (admins) publish an announcement. Also covers the PUBLIC catalog & docs (no
+  token needed): service detail & pricing, API list & OpenAPI specs, datasets,
+  integrations, full-text documentation search, and the model catalog with
+  per-model credit pricing. This is the self-service "console" API — distinct
   from the data-generation APIs (image/video/music/search).
 license: Apache-2.0
 metadata:
@@ -19,7 +22,9 @@ compatibility: Requires ACEDATACLOUD_PLATFORM_TOKEN (a platform or user token).
 # AceDataCloud Platform Management
 
 Programmatically manage your AceDataCloud account: balances, usage records, API
-keys, services, orders, platform tokens, models, and announcements.
+keys, services, orders, platform tokens, models, announcements and referral
+earnings — plus browse the public catalog & docs (service pricing, API specs,
+datasets, integrations, documentation search, model catalog) without a token.
 
 This is the **management / console** API at `https://platform.acedata.cloud/api/v1`
 — the same surface the web console uses. It is **different** from the
@@ -68,6 +73,20 @@ python3 $ADC keys                             # list API keys (credentials)
 python3 $ADC orders --state Finished          # recharge orders
 python3 $ADC tokens                           # platform tokens
 python3 $ADC models                           # available chat models
+python3 $ADC distributions                    # referral status + commission history
+
+# Catalog & docs (PUBLIC — work without a token)
+python3 $ADC get-service --service suno       # one service's detail
+python3 $ADC pricing --service suno           # unit, free_amount and cost
+python3 $ADC apis --service suno              # API endpoints for a service
+python3 $ADC spec --path /suno/audios         # one API's OpenAPI definition + cost
+python3 $ADC datasets                         # downloadable datasets
+python3 $ADC integrations                     # third-party integrations
+python3 $ADC docs-search --query "suno lyrics" --lang en   # full-text doc search
+python3 $ADC docs-list                        # browse documentation pages
+python3 $ADC doc --id <document-uuid>         # one doc's full content
+python3 $ADC model-catalog --modality chat    # rich model catalog + credit pricing
+python3 $ADC model --model claude             # look up a model by id/name
 
 # Safe write (require --yes to actually execute)
 python3 $ADC create-key  --application <app-id> --name "ci" --yes
@@ -206,6 +225,22 @@ Filters: `api_id`, `application_id`, `status_code`, `created_at_from`,
 OpenAI-style (no pagination): `{ "object": "list", "data": [ { "id": "gpt-4.1",
 "label": "GPT-4.1", "owned_by": "openai", "type": "chat", "capabilities": ["vision"] } ] }`
 
+### Catalog & docs (PUBLIC — no token required)
+
+These work without auth (send the token if you have one; not required):
+
+- **Service detail / pricing** — `GET /services/?id=<uuid>` → `items[0]` (full: `cost`, `unit`,
+  `free_amount`, `title`). The `services/?alias=` filter is **ignored** server-side, so resolve an
+  alias by paging `services/` and matching `alias` client-side. The `services/{id}/` detail route is broken (500).
+- **APIs** — `GET /apis/?path=<path>` → exactly one item with its OpenAPI `definition` + `cost`.
+  `apis/?service_id=` is **ignored** server-side; filter by `service_id` client-side. `apis/{id}/` is broken (500).
+- **Datasets / integrations** — `GET /datasets/`, `GET /integrations/`.
+- **Doc search** — `GET /search/?query=<text>&lang=<code>` → `{ results: [ { id, alias, title, type, snippet, url } ] }`.
+  The param is **`query`** (not `keyword`).
+- **Doc content** — `GET /documents/?id=<uuid>` → `items[0].content`. `documents/{id}/` (id or slug) is broken (404).
+- **Model catalog** — `GET /models/catalog/` → `{ rates, modalities, count, items:[{ id, name, provider,
+  modality, unit, capabilities, pricing:{ input_credits, output_credits, official_* } }] }`. Filter client-side.
+
 ### Announcements — `GET /announcements/`
 
 Public read: `{ "count": 20, "items": [ { "id", "title", "content",
@@ -241,4 +276,4 @@ publishing announcements are **irreversible or money-related**. Always:
 - Announcement endpoints under `/admin/` require a **superuser** token; a normal
   token gets `403`.
 
-> **MCP:** `pip install mcp-acedatacloud` | See [all MCP servers](../_shared/mcp-servers.md). The MCP exposes these as tools (`platform_get_balance`, `platform_list_usage`, `platform_create_credential`, `platform_create_announcement`, …) with the same write-confirmation guard.
+> **MCP:** `pip install mcp-acedatacloud` | Hosted: `https://mcp.acedata.cloud/mcp` | See [all MCP servers](../_shared/mcp-servers.md). The MCP exposes these as tools (`acedatacloud_get_balance`, `acedatacloud_list_usage`, `acedatacloud_get_pricing`, `acedatacloud_search_docs`, `acedatacloud_get_api_spec`, `acedatacloud_create_credential`, …) with the same write-confirmation guard.

package/skills/acedatacloud/scripts/acedatacloud.py

@@ -18,6 +18,7 @@ import argparse
 import datetime as dt
 import json
 import os
+import re
 import sys
 import urllib.error
 import urllib.parse
@@ -32,18 +33,9 @@ def _die(msg: str, code: int = 1) -> None:
     sys.exit(code)
 
 
-def _token(args: argparse.Namespace) -> str:
-    token = args.token or os.environ.get("ACEDATACLOUD_PLATFORM_TOKEN", "")
-    if not token:
-        _die(
-            "no platform token. Set ACEDATACLOUD_PLATFORM_TOKEN or pass --token.\n"
-            "Create one at https://platform.acedata.cloud/console/platform-tokens"
-        )
-    return token
-
-
 def _request(args: argparse.Namespace, method: str, path: str,
-             params: dict | None = None, body: dict | None = None) -> tuple[int, object]:
+             params: dict | None = None, body: dict | None = None,
+             auth_required: bool = True) -> tuple[int, object]:
     base = args.base_url.rstrip("/")
     url = f"{base}/api/v1{path}"
     if params:
@@ -51,11 +43,16 @@ def _request(args: argparse.Namespace, method: str, path: str,
         if clean:
             url += "?" + urllib.parse.urlencode(clean, doseq=True)
     data = json.dumps(body).encode() if body is not None else None
-    req = urllib.request.Request(url, data=data, method=method, headers={
-        "accept": "application/json",
-        "authorization": f"Bearer {_token(args)}",
-        "content-type": "application/json",
-    })
+    headers = {"accept": "application/json", "content-type": "application/json"}
+    token = args.token or os.environ.get("ACEDATACLOUD_PLATFORM_TOKEN", "")
+    if token:
+        headers["authorization"] = f"Bearer {token}"
+    elif auth_required:
+        _die(
+            "no platform token. Set ACEDATACLOUD_PLATFORM_TOKEN or pass --token.\n"
+            "Create one at https://platform.acedata.cloud/console/platform-tokens"
+        )
+    req = urllib.request.Request(url, data=data, method=method, headers=headers)
     try:
         with urllib.request.urlopen(req, timeout=args.timeout) as resp:
             raw = resp.read().decode("utf-8")
@@ -72,7 +69,7 @@ def _request(args: argparse.Namespace, method: str, path: str,
 
 
 def _get_all(args: argparse.Namespace, path: str, params: dict | None = None,
-             page: int = 200, cap: int = 2000) -> tuple[int, list]:
+             page: int = 200, cap: int = 2000, auth_required: bool = True) -> tuple[int, list]:
     """Fetch every page of a {count, items} list endpoint (capped)."""
     base = dict(params or {})
     out: list = []
@@ -80,7 +77,7 @@ def _get_all(args: argparse.Namespace, path: str, params: dict | None = None,
     total = 0
     while len(out) < cap:
         base.update({"limit": page, "offset": offset})
-        status, payload = _request(args, "GET", path, base)
+        status, payload = _request(args, "GET", path, base, auth_required=auth_required)
         _check_ok(status, payload)
         items = payload.get("items", []) if isinstance(payload, dict) else []
         total = payload.get("count", 0) if isinstance(payload, dict) else 0
@@ -142,6 +139,29 @@ def _since(days: int | None) -> str | None:
     return (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
+_UUID = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
+
+
+def _resolve_service(args, ref: str) -> dict | None:
+    """Resolve a service by UUID (services/?id=) or alias (paginated match).
+
+    The platform's services/?alias= filter is ignored server-side, so alias
+    lookups page through the catalog and match client-side.
+    """
+    ref = ref.strip()
+    if _UUID.match(ref):
+        status, payload = _request(args, "GET", "/services/", {"id": ref}, auth_required=False)
+        _check_ok(status, payload)
+        items = payload.get("items", []) if isinstance(payload, dict) else []
+        return items[0] if items else None
+    target = ref.lower()
+    _, items = _get_all(args, "/services/", page=50, cap=600, auth_required=False)
+    for it in items:
+        if (it.get("alias") or "").lower() == target:
+            return it
+    return None
+
+
 # ---- read commands -------------------------------------------------------
 
 def cmd_balance(args):
@@ -261,6 +281,179 @@ def cmd_announcements(args):
     _emit(args, payload, rows, ("id", "title", "rank", "publish_at"))
 
 
+# ---- catalog & docs commands (public, no token needed) ------------------
+
+def cmd_get_service(args):
+    svc = _resolve_service(args, args.service)
+    if not svc:
+        _die(f"no service matched '{args.service}'", code=2)
+    _emit(args, svc)
+
+
+def cmd_pricing(args):
+    svc = _resolve_service(args, args.service)
+    if not svc:
+        _die(f"no service matched '{args.service}'", code=2)
+    out = {
+        "service_id": svc.get("id"),
+        "alias": svc.get("alias"),
+        "title": svc.get("title"),
+        "type": svc.get("type"),
+        "unit": svc.get("unit"),
+        "free_amount": svc.get("free_amount"),
+        "cost": svc.get("cost"),
+    }
+    _emit(args, out)
+
+
+def cmd_apis(args):
+    sid = None
+    if args.service:
+        svc = _resolve_service(args, args.service)
+        if not svc:
+            _die(f"no service matched '{args.service}'", code=2)
+        sid = svc.get("id")
+    # apis/?service_id= is ignored server-side, so filter client-side.
+    _, items = _get_all(args, "/apis/", page=50, cap=2000, auth_required=False)
+    if sid:
+        items = [it for it in items if it.get("service_id") == sid]
+    items = items[: args.limit]
+    slim = [{k: v for k, v in it.items() if k != "definition"} for it in items]
+    rows = [(
+        (it.get("path") or ""),
+        it.get("method"),
+        it.get("stage"),
+        (it.get("title") or "")[:30],
+    ) for it in items]
+    _emit(args, {"count": len(slim), "items": slim}, rows, ("path", "method", "stage", "title"))
+
+
+def cmd_spec(args):
+    status, payload = _request(args, "GET", "/apis/", {"path": args.path}, auth_required=False)
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    if not items:
+        _die(f"no API matched path '{args.path}'", code=2)
+    api = items[0]
+    _emit(args, {
+        "id": api.get("id"),
+        "service_id": api.get("service_id"),
+        "title": api.get("title"),
+        "path": api.get("path"),
+        "method": api.get("method"),
+        "stage": api.get("stage"),
+        "cost": api.get("cost"),
+        "definition": api.get("definition"),
+    })
+
+
+def cmd_datasets(args):
+    status, payload = _request(args, "GET", "/datasets/", {"limit": args.limit}, auth_required=False)
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(it.get("id", "")[:8], (it.get("title") or "")[:30], it.get("price"), (it.get("part") or "")) for it in items]
+    _emit(args, payload, rows, ("id", "title", "price", "part"))
+
+
+def cmd_integrations(args):
+    status, payload = _request(args, "GET", "/integrations/", {"limit": args.limit}, auth_required=False)
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(it.get("id", "")[:8], (it.get("title") or "")[:34], it.get("stage")) for it in items]
+    _emit(args, payload, rows, ("id", "title", "stage"))
+
+
+def cmd_docs_search(args):
+    status, payload = _request(args, "GET", "/search/", {"query": args.query, "lang": args.lang}, auth_required=False)
+    _check_ok(status, payload)
+    results = payload.get("results", []) if isinstance(payload, dict) else []
+    rows = [((r.get("title") or "")[:44], r.get("type"), r.get("matched_lang"), (r.get("id") or "")[:8]) for r in results]
+    _emit(args, payload, rows, ("title", "type", "lang", "id"))
+
+
+def cmd_docs_list(args):
+    status, payload = _request(args, "GET", "/documents/", {"limit": args.limit, "type": args.type}, auth_required=False)
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(it.get("id", "")[:8], (it.get("title") or "")[:40], it.get("type"), it.get("alias")) for it in items]
+    _emit(args, {"count": payload.get("count") if isinstance(payload, dict) else None, "items": items}, rows,
+          ("id", "title", "type", "alias"))
+
+
+def cmd_doc(args):
+    if not _UUID.match(args.id.strip()):
+        _die("doc id must be a document UUID", code=2)
+    status, payload = _request(args, "GET", "/documents/", {"id": args.id.strip()}, auth_required=False)
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    if not items:
+        _die(f"no document with id '{args.id}'", code=2)
+    _emit(args, items[0])
+
+
+def cmd_model_catalog(args):
+    status, payload = _request(args, "GET", "/models/catalog/", auth_required=False)
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    if args.modality:
+        m = args.modality.lower()
+        items = [it for it in items if (it.get("modality") or "").lower() == m]
+    if args.provider:
+        pv = args.provider.lower()
+        items = [it for it in items if pv in (it.get("provider") or "").lower()]
+    rows = [(
+        it.get("id"),
+        it.get("provider"),
+        it.get("modality"),
+        (it.get("pricing") or {}).get("input_credits"),
+        (it.get("pricing") or {}).get("output_credits"),
+    ) for it in items]
+    out = {"modalities": payload.get("modalities") if isinstance(payload, dict) else None,
+           "count": len(items), "items": items}
+    _emit(args, out, rows, ("id", "provider", "modality", "in_credits", "out_credits"))
+
+
+def cmd_model(args):
+    status, payload = _request(args, "GET", "/models/catalog/", auth_required=False)
+    _check_ok(status, payload)
+    q = args.model.strip().lower()
+    items = [it for it in (payload.get("items", []) if isinstance(payload, dict) else [])
+             if q in (it.get("id") or "").lower() or q in (it.get("name") or "").lower()]
+    if not items:
+        _die(f"no model matched '{args.model}'", code=2)
+    rows = [(
+        it.get("id"),
+        it.get("provider"),
+        it.get("modality"),
+        (it.get("pricing") or {}).get("input_credits"),
+        (it.get("pricing") or {}).get("output_credits"),
+    ) for it in items]
+    _emit(args, {"count": len(items), "items": items}, rows,
+          ("id", "provider", "modality", "in_credits", "out_credits"))
+
+
+def cmd_distributions(args):
+    status, status_payload = _request(args, "GET", "/distribution-statuses/", {"limit": 1})
+    _check_ok(status, status_payload)
+    st_items = status_payload.get("items", []) if isinstance(status_payload, dict) else []
+    hstatus, hist = _request(args, "GET", "/distribution-histories/", {"limit": args.limit})
+    _check_ok(hstatus, hist)
+    hitems = hist.get("items", []) if isinstance(hist, dict) else []
+    out = {
+        "status": st_items[0] if st_items else None,
+        "history_count": hist.get("count") if isinstance(hist, dict) else None,
+        "history": hitems,
+    }
+    rows = [(
+        (it.get("created_at") or "")[:10],
+        it.get("price"),
+        it.get("reward"),
+        it.get("percentage"),
+        "invalid" if it.get("invalid") else "ok",
+    ) for it in hitems]
+    _emit(args, out, rows, ("date", "price", "reward", "pct", "state"))
+
+
 # ---- write commands (gated by --yes) -------------------------------------
 
 def _guard(args, action: str, detail: dict) -> bool:
@@ -405,6 +598,47 @@ def build_parser() -> argparse.ArgumentParser:
     sp = add("announcements", cmd_announcements, "list announcements")
     sp.add_argument("--limit", type=int, default=20)
 
+    sp = add("distributions", cmd_distributions, "referral status + commission history")
+    sp.add_argument("--limit", type=int, default=20)
+
+    # ---- catalog & docs (public, no token needed) ----
+    sp = add("get-service", cmd_get_service, "one service's detail by alias or id")
+    sp.add_argument("--service", required=True, help="service alias or UUID")
+
+    sp = add("pricing", cmd_pricing, "a service's unit, free_amount and cost")
+    sp.add_argument("--service", required=True, help="service alias or UUID")
+
+    sp = add("apis", cmd_apis, "list API endpoints (optionally per service)")
+    sp.add_argument("--service", help="scope to a service alias or UUID")
+    sp.add_argument("--limit", type=int, default=50)
+
+    sp = add("spec", cmd_spec, "one API's OpenAPI definition + cost, by path")
+    sp.add_argument("--path", required=True, help="API path, e.g. /suno/audios")
+
+    sp = add("datasets", cmd_datasets, "list downloadable datasets")
+    sp.add_argument("--limit", type=int, default=50)
+
+    sp = add("integrations", cmd_integrations, "list third-party integrations")
+    sp.add_argument("--limit", type=int, default=50)
+
+    sp = add("docs-search", cmd_docs_search, "full-text search the documentation")
+    sp.add_argument("--query", required=True)
+    sp.add_argument("--lang", help="language code, e.g. en, zh-cn")
+
+    sp = add("docs-list", cmd_docs_list, "browse documentation pages")
+    sp.add_argument("--limit", type=int, default=30)
+    sp.add_argument("--type", help="document type filter, e.g. Text")
+
+    sp = add("doc", cmd_doc, "fetch one doc's full content by UUID")
+    sp.add_argument("--id", required=True, help="document UUID")
+
+    sp = add("model-catalog", cmd_model_catalog, "rich model catalog with credit pricing")
+    sp.add_argument("--modality", help="chat/video/image/music/search/embedding")
+    sp.add_argument("--provider", help="filter by provider substring")
+
+    sp = add("model", cmd_model, "look up a model by id/name")
+    sp.add_argument("--model", required=True)
+
     sp = add("create-key", cmd_create_key, "create an API key (needs --yes)")
     sp.add_argument("--application", required=True)
     sp.add_argument("--name")