@acedatacloud/skills 2026.628.4 → 2026.628.5

package/AGENTS.md

@@ -31,7 +31,7 @@ Skills are located in the `skills/` directory (also mirrored to `.agents/skills/
 - **face-transform** — Face analysis, beautification, age/gender transform, swap, cartoon
 - **short-url** — Create and manage short URLs
 - **onepage-pdf** — Convert an HTML page into one tall single-page PDF (local; no API token; needs Python + pymupdf + Chrome/Edge)
-- **acedatacloud-api** — API usage guide — authentication, SDKs, error handling
+- **acedatacloud** — Manage your AceDataCloud account — balance, usage/spend, API keys, services, orders, announcements
 
 ## Authentication
 

package/README.md

@@ -50,7 +50,7 @@ Compatible with **30+ AI coding agents** via the [agentskills.io](https://agents
 | [face-transform](skills/face-transform/) | Face analysis, beautification, age/gender transform, swap, cartoon |
 | [short-url](skills/short-url/) | Create and manage short URLs |
 | [onepage-pdf](skills/onepage-pdf/) | Convert an HTML page into one tall single-page PDF — no pagination breaks (local, no token) |
-| [acedatacloud-api](skills/acedatacloud-api/) | API usage guide — authentication, SDKs, error handling |
+| [acedatacloud](skills/acedatacloud/) | Manage your AceDataCloud account — balance, usage/spend, API keys, services, orders, announcements |
 
 ### Connectors
 
@@ -207,6 +207,7 @@ Skills provide **knowledge** (when to use, parameters, gotchas). MCP servers pro
 | nano-banana-image | [mcp-nano-banana](https://pypi.org/project/mcp-nano-banana/) | `pip install mcp-nano-banana` | `https://nano-banana.mcp.acedata.cloud/mcp` |
 | short-url | [mcp-shorturl](https://pypi.org/project/mcp-shorturl/) | `pip install mcp-shorturl` | `https://short-url.mcp.acedata.cloud/mcp` |
 | wan-video | [mcp-wan](https://pypi.org/project/mcp-wan/) | `pip install mcp-wan` | `https://wan.mcp.acedata.cloud/mcp` |
+| acedatacloud | [mcp-acedatacloud](https://pypi.org/project/mcp-acedatacloud/) | `pip install mcp-acedatacloud` | `https://acedatacloud.mcp.acedata.cloud/mcp` |
 
 **Using hosted MCP endpoints** (no local install needed):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.628.4",
+  "version": "2026.628.5",
   "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/_shared/mcp-servers.md

@@ -18,6 +18,7 @@ Each AceDataCloud service has a corresponding MCP server that provides tool-use
 | nano-banana-image | `pip install mcp-nano-banana` | `https://nano-banana.mcp.acedata.cloud/mcp` |
 | short-url | `pip install mcp-shorturl` | `https://short-url.mcp.acedata.cloud/mcp` |
 | wan-video | `pip install mcp-wan` | `https://wan.mcp.acedata.cloud/mcp` |
+| acedatacloud | `pip install mcp-acedatacloud` | `https://acedatacloud.mcp.acedata.cloud/mcp` |
 
 ## Configuration Example
 

package/skills/acedatacloud/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: acedatacloud
+description: |
+  Manage your AceDataCloud account through the management API
+  (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
+  from the data-generation APIs (image/video/music/search).
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+connections: [acedatacloud]
+compatibility: Requires ACEDATACLOUD_PLATFORM_TOKEN (a platform or user token). Auto-injected when the AceDataCloud connector is installed; otherwise set it in .env. Optionally pair with mcp-acedatacloud for tool-use.
+---
+
+# AceDataCloud Platform Management
+
+Programmatically manage your AceDataCloud account: balances, usage records, API
+keys, services, orders, platform tokens, models, and announcements.
+
+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
+data-generation API at `api.acedata.cloud` (image / video / music / search generation).
+
+## Setup — use a PLATFORM token, not a service token
+
+The management API is authenticated with a **platform token** (or a logged-in
+user token), **not** the per-service API token used for `api.acedata.cloud`.
+
+1. Create one at [platform.acedata.cloud/console/platform-tokens](https://platform.acedata.cloud/console/platform-tokens)
+   (or `POST /api/v1/platform-tokens/`). It starts with `platform-` and never expires.
+2. Provide it one of two ways:
+   - **Connector (recommended in studio / chat):** install the **AceDataCloud**
+     connector at [auth.acedata.cloud/user/connections](https://auth.acedata.cloud/user/connections)
+     and paste the token once — the runtime injects `ACEDATACLOUD_PLATFORM_TOKEN`
+     into the sandbox automatically (this skill declares `connections: [acedatacloud]`).
+   - **Local `.env`:**
+
+```bash
+ACEDATACLOUD_PLATFORM_TOKEN=platform-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+```bash
+curl -H "authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
+  https://platform.acedata.cloud/api/v1/applications/
+```
+
+> A normal token only ever sees **its own** account data. A superuser token sees
+> every user's data and is required for admin operations (announcements).
+
+## CLI (preferred)
+
+The skill ships [`scripts/acedatacloud.py`](scripts/acedatacloud.py) — a self-contained
+CLI (stdlib only) for the most common operations.
+
+```bash
+ADC=$SKILL_DIR/scripts/acedatacloud.py
+
+# Read
+python3 $ADC balance                         # remaining credits per subscription
+python3 $ADC services --search suno          # list/search subscribed services
+python3 $ADC usage --days 7                   # recent API call records
+python3 $ADC usage-summary --days 30          # spend aggregated by day + API
+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
+
+# Safe write (require --yes to actually execute)
+python3 $ADC create-key  --application <app-id> --name "ci" --yes
+python3 $ADC delete-key  --id <credential-id> --yes
+python3 $ADC create-order --application <app-id> --package <package-id> --yes
+python3 $ADC pay-order   --id <order-id> --pay-way Stripe --yes
+python3 $ADC create-token --yes
+python3 $ADC delete-token --id <token-id> --yes
+
+# Admin (superuser token only)
+python3 $ADC send-announcement --title "..." --content "..." --yes
+```
+
+Every command accepts `--json` for machine-readable output and `--token` to
+override the env token. Without `--yes`, write commands print a dry-run preview
+and exit without calling the API.
+
+## Pagination
+
+List endpoints return `{ "count": <total>, "items": [ ... ] }` and accept
+`?limit=` and `?offset=`. (Note: some older docs say `results`; the live field
+is **`items`**.)
+
+## Endpoints reference
+
+### Balance / subscriptions — `GET /applications/`
+
+An *Application* is your subscription to one Service; its `remaining_amount` is
+your balance (in **Credits**) for that service.
+
+```bash
+curl -H "authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN" \
+  "https://platform.acedata.cloud/api/v1/applications/?limit=1"
+```
+
+```json
+{
+  "count": 3,
+  "items": [
+    {
+      "id": "e9f625f2-cbd5-4254-8264-cfadbd180428",
+      "service_id": "f2b646d8-3cfd-46ef-969a-1ea9eebde329",
+      "remaining_amount": 100.9,
+      "used_amount": 1.1,
+      "paid": false,
+      "scope": "Global",
+      "allow_consume_global": true,
+      "expired_at": null,
+      "type": "Usage"
+    }
+  ]
+}
+```
+
+Filters: `service_id`, `scope` (`Individual`/`Global`), `user_id` (superuser only).
+
+### Usage records — `GET /usage/apis/`
+
+Per-request call records (status code, latency, credits deducted).
+
+Filters: `api_id`, `application_id`, `status_code`, `created_at_from`,
+`created_at_to`, `user_id` (superuser only).
+
+```json
+{
+  "count": 128,
+  "items": [
+    {
+      "id": "c124684b-7188-4c3e-ad53-3fba5150b944",
+      "api": { "title": "Suno Audios Generation API" },
+      "status_code": 200,
+      "original_amount": 0.55,
+      "deducted_amount": 0.55,
+      "trace_id": "…",
+      "elapsed": 12.3,
+      "created_at": "2026-06-28T09:15:44Z"
+    }
+  ]
+}
+```
+
+- **Spend aggregate** — `GET /usage/apis/aggregate/?created_at_from=&created_at_to=`
+  → `{ "items": [{ "date", "api_id", "amount" }], "total": <credits>, "apis": { "<id>": { "title" } } }`
+- **Status-code filter values** — `GET /usage/apis/status-codes/` → `{ "items": [200, 400, 502] }`
+- **CSV export** — `GET /usage/apis/export/?created_at_from=&created_at_to=` (downloads `usages.csv`)
+
+### Services — `GET /services/`
+
+```json
+{ "count": 215, "items": [ { "id": "…", "alias": "suno", "title": "Suno 音乐生成",
+  "unit": "Credit", "free_amount": 0.0, "applied_count": 121733,
+  "packages": [ { "id": "…", "type": "Usage", "price": 13.0, "amount": 100.0 } ] } ] }
+```
+
+### API keys / credentials — `GET /credentials/`
+
+```json
+{ "count": 2, "items": [ { "id": "dae4899f-…", "name": "ci", "type": "Token",
+  "token": "<secret>", "limited_amount": null, "used_amount": 1.1,
+  "host": null, "created_at": "2026-06-28T09:15:44Z" } ] }
+```
+
+- **Create** — `POST /credentials/` `{ "application_id": "<app>", "name": "ci", "limited_amount": 100, "expired_at": "2026-12-31T00:00:00Z" }` → returns the credential incl. the new `token`. Save it; it is shown in full only at creation.
+- **Delete** — `DELETE /credentials/{id}` → `204 No Content`
+- Filters: `application_id`, `host`, `granted` (`true`/`false`), `user_id` (superuser).
+- To "rotate" a key, delete it and create a new one.
+
+### Orders (recharge) — `GET /orders/`
+
+```json
+{ "count": 12, "items": [ { "id": "17c10c9d-…", "application_id": "…",
+  "package_id": "…", "description": "100 Credits", "price": 13.0,
+  "state": "Finished", "pay_way": "Stripe", "pay_url": "<url>",
+  "created_at": "2026-06-28T09:17:25Z" } ] }
+```
+
+- `state` ∈ `Pending` `Paid` `Finished` `Expired` `Failed` `Refunded`
+- `pay_way` ∈ `WechatPay` `AliPay` `Stripe` `X402` `PayPal` `Reward`
+- **Create** — `POST /orders/` `{ "application_id": "<app>", "package_id": "<package>" }`
+- **Pay** — `POST /orders/{id}/pay/` `{ "pay_way": "Stripe" }` → returns the order with a `pay_url` to open
+- **Refresh status** — `POST /orders/{id}/refresh/` (re-checks the PSP and updates `state`)
+- Filters: `state`, `pay_way`, `created_at_from`, `created_at_to`, `user_id` (superuser).
+
+### Platform tokens — `GET /platform-tokens/`
+
+```json
+{ "count": 2, "items": [ { "id": "efdccba4-…", "token": "<secret>",
+  "expiration": null, "used_at": null, "created_at": "2026-06-28T06:29:02Z" } ] }
+```
+
+- **Create** — `POST /platform-tokens/` → returns the new token (starts with `platform-`)
+- **Delete** — `DELETE /platform-tokens/{id}/` → `204 No Content`
+
+### Models — `GET /models/`
+
+OpenAI-style (no pagination): `{ "object": "list", "data": [ { "id": "gpt-4.1",
+"label": "GPT-4.1", "owned_by": "openai", "type": "chat", "capabilities": ["vision"] } ] }`
+
+### Announcements — `GET /announcements/`
+
+Public read: `{ "count": 20, "items": [ { "id", "title", "content",
+"translation_key", "published", "publish_at", "rank", "tags", "is_read" } ] }`
+
+**Admin only (superuser token):**
+
+- **Publish** — `POST /announcements/admin/` `{ "title": "...", "content": "...", "rank": 5, "tags": ["product"], "published": true }`
+  (`content` is Markdown; a zh-cn Translation row is created and other locales are auto-translated by a CronJob)
+- **Edit / delete** — `PUT` / `DELETE /announcements/admin/{id}`
+- **AI polish** — `POST /announcements/admin/polish/` `{ "title", "content" }`
+- **AI translate** — `POST /announcements/admin/translate/` `{ "translation_key" }`
+
+## Write-operation safety
+
+Creating/deleting keys, creating/paying orders, deleting platform tokens, and
+publishing announcements are **irreversible or money-related**. Always:
+
+1. Confirm the exact target (`application_id`, `order_id`, `credential_id`) with
+   the user before executing.
+2. With the CLI, writes are dry-run unless `--yes` is passed.
+3. Never print a full `token` value into shared logs — it grants account access.
+
+## Gotchas
+
+- Use the **platform token** (`ACEDATACLOUD_PLATFORM_TOKEN`), not the
+  `api.acedata.cloud` service token — the latter returns 401 here.
+- `remaining_amount` / `used_amount` / `amount` are in **Credits**, not USD.
+  Convert with a service's package: `USD = Credits × (package.price / package.amount)`.
+- Newly created credential/platform tokens are returned in full **only once** —
+  store them immediately.
+- Credential "rotate" is delete + recreate; there is no in-place rotate endpoint.
+- 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.

package/skills/acedatacloud/scripts/acedatacloud.py

@@ -0,0 +1,467 @@
+#!/usr/bin/env python3
+"""AceDataCloud platform management CLI (self-contained, stdlib only).
+
+Talks to the management API at https://platform.acedata.cloud/api/v1 using a
+platform token (ACEDATACLOUD_PLATFORM_TOKEN). Read commands are always safe;
+write commands are dry-run unless --yes is passed.
+
+Examples:
+    python3 platform.py balance
+    python3 platform.py usage-summary --days 30
+    python3 platform.py keys
+    python3 platform.py create-key --application <app-id> --name ci --yes
+    python3 platform.py send-announcement --title T --content C --yes
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_BASE_URL = os.environ.get("PLATFORM_API_BASE_URL", "https://platform.acedata.cloud")
+SECRET_KEYS = {"token", "password", "pay_url", "pay_id"}
+
+
+def _die(msg: str, code: int = 1) -> None:
+    print(f"error: {msg}", file=sys.stderr)
+    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]:
+    base = args.base_url.rstrip("/")
+    url = f"{base}/api/v1{path}"
+    if params:
+        clean = {k: v for k, v in params.items() if v is not None}
+        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",
+    })
+    try:
+        with urllib.request.urlopen(req, timeout=args.timeout) as resp:
+            raw = resp.read().decode("utf-8")
+            return resp.status, (json.loads(raw) if raw.strip() else None)
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", "replace")
+        try:
+            return e.code, json.loads(raw)
+        except Exception:
+            return e.code, raw
+    except urllib.error.URLError as e:
+        _die(f"network error: {e.reason}")
+    return 0, None  # unreachable
+
+
+def _get_all(args: argparse.Namespace, path: str, params: dict | None = None,
+             page: int = 200, cap: int = 2000) -> tuple[int, list]:
+    """Fetch every page of a {count, items} list endpoint (capped)."""
+    base = dict(params or {})
+    out: list = []
+    offset = 0
+    total = 0
+    while len(out) < cap:
+        base.update({"limit": page, "offset": offset})
+        status, payload = _request(args, "GET", path, base)
+        _check_ok(status, payload)
+        items = payload.get("items", []) if isinstance(payload, dict) else []
+        total = payload.get("count", 0) if isinstance(payload, dict) else 0
+        out.extend(items)
+        offset += page
+        if not items or offset >= total:
+            break
+    return total, out
+
+
+def _mask(obj: object, reveal: bool) -> object:
+    if reveal:
+        return obj
+    if isinstance(obj, dict):
+        out = {}
+        for k, v in obj.items():
+            if k in SECRET_KEYS and isinstance(v, str) and v:
+                out[k] = v[:10] + "…" + f"({len(v)} chars)" if len(v) > 10 else "***"
+            else:
+                out[k] = _mask(v, reveal)
+        return out
+    if isinstance(obj, list):
+        return [_mask(x, reveal) for x in obj]
+    return obj
+
+
+def _emit(args: argparse.Namespace, payload: object, rows: list[tuple] | None = None,
+          headers: tuple | None = None, force_reveal: bool = False) -> None:
+    reveal = force_reveal or getattr(args, "reveal", False)
+    if args.json:
+        print(json.dumps(_mask(payload, reveal), ensure_ascii=False, indent=2))
+        return
+    if rows is not None and headers is not None:
+        widths = [len(h) for h in headers]
+        for r in rows:
+            for i, cell in enumerate(r):
+                widths[i] = max(widths[i], len(str(cell)))
+        line = "  ".join(str(h).ljust(widths[i]) for i, h in enumerate(headers))
+        print(line)
+        print("  ".join("-" * widths[i] for i in range(len(headers))))
+        for r in rows:
+            print("  ".join(str(c).ljust(widths[i]) for i, c in enumerate(r)))
+    else:
+        print(json.dumps(_mask(payload, reveal), ensure_ascii=False, indent=2))
+
+
+def _check_ok(status: int, payload: object) -> None:
+    if status >= 400:
+        msg = payload
+        if isinstance(payload, dict):
+            err = payload.get("error")
+            msg = (err.get("message") if isinstance(err, dict) else err) or payload.get("detail") or payload
+        _die(f"HTTP {status}: {msg}", code=2)
+
+
+def _since(days: int | None) -> str | None:
+    if not days:
+        return None
+    return (dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=days)).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+# ---- read commands -------------------------------------------------------
+
+def cmd_balance(args):
+    status, payload = _request(args, "GET", "/applications/", {"limit": args.limit})
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(
+        it.get("service_id", "")[:8],
+        it.get("remaining_amount"),
+        it.get("used_amount"),
+        it.get("scope"),
+        it.get("id", "")[:8],
+    ) for it in items]
+    _emit(args, payload, rows, ("service", "remaining", "used", "scope", "app_id"))
+
+
+def cmd_services(args):
+    if args.search:
+        total, items = _get_all(args, "/services/")
+        s = args.search.lower()
+        items = [it for it in items if s in (it.get("alias") or "").lower() or s in (it.get("title") or "").lower()]
+        payload = {"count": len(items), "items": items}
+        if not args.json:
+            print(f"# {len(items)} match '{args.search}' / {total} total services\n")
+    else:
+        status, payload = _request(args, "GET", "/services/", {"limit": args.limit})
+        _check_ok(status, payload)
+        items = payload.get("items", []) if isinstance(payload, dict) else []
+        if not args.json:
+            print(f"# {len(items)} shown / {payload.get('count')} total services\n")
+    rows = [(it.get("alias"), (it.get("title") or "")[:28], it.get("unit"), it.get("applied_count"), it.get("id", "")[:8]) for it in items]
+    _emit(args, payload, rows, ("alias", "title", "unit", "applied", "id"))
+
+
+def cmd_usage(args):
+    params = {"limit": args.limit, "status_code": args.status_code,
+              "api_id": args.api, "created_at_from": _since(args.days)}
+    status, payload = _request(args, "GET", "/usage/apis/", params)
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(
+        ((it.get("api") or {}).get("title") or "")[:30],
+        it.get("status_code"),
+        it.get("deducted_amount"),
+        it.get("elapsed"),
+        (it.get("created_at") or "")[:19],
+    ) for it in items]
+    _emit(args, payload, rows, ("api", "status", "credits", "elapsed", "created_at"))
+
+
+def cmd_usage_summary(args):
+    params = {"created_at_from": _since(args.days or 30), "api_id": args.api}
+    status, payload = _request(args, "GET", "/usage/apis/aggregate/", params)
+    _check_ok(status, payload)
+    apis = payload.get("apis", {}) if isinstance(payload, dict) else {}
+    by_api: dict[str, float] = {}
+    for it in (payload.get("items", []) if isinstance(payload, dict) else []):
+        by_api[it.get("api_id")] = by_api.get(it.get("api_id"), 0.0) + (it.get("amount") or 0.0)
+    rows = sorted(((apis.get(k, {}).get("title", k or "?")[:36], round(v, 4)) for k, v in by_api.items()),
+                  key=lambda r: -r[1])
+    if not args.json:
+        print(f"# total spend: {payload.get('total')} Credits over last {args.days or 30} days\n")
+    _emit(args, payload, rows, ("api", "credits"))
+
+
+def cmd_keys(args):
+    status, payload = _request(args, "GET", "/credentials/", {"limit": args.limit, "application_id": args.application})
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(
+        it.get("id", "")[:8],
+        it.get("name") or "-",
+        it.get("type"),
+        it.get("limited_amount"),
+        it.get("used_amount"),
+        (it.get("created_at") or "")[:10],
+    ) for it in items]
+    _emit(args, payload, rows, ("id", "name", "type", "limit", "used", "created"))
+
+
+def cmd_orders(args):
+    status, payload = _request(args, "GET", "/orders/", {"limit": args.limit, "state": args.state, "pay_way": args.pay_way})
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(
+        it.get("id", "")[:8],
+        (it.get("description") or "")[:26],
+        it.get("price"),
+        it.get("state"),
+        it.get("pay_way"),
+        (it.get("created_at") or "")[:10],
+    ) for it in items]
+    _emit(args, payload, rows, ("id", "description", "price", "state", "pay_way", "created"))
+
+
+def cmd_tokens(args):
+    status, payload = _request(args, "GET", "/platform-tokens/", {"limit": args.limit})
+    _check_ok(status, payload)
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    rows = [(it.get("id", "")[:8], (it.get("used_at") or "never")[:19], (it.get("created_at") or "")[:19]) for it in items]
+    _emit(args, payload, rows, ("id", "last_used", "created"))
+
+
+def cmd_models(args):
+    status, payload = _request(args, "GET", "/models/")
+    _check_ok(status, payload)
+    data = payload.get("data", []) if isinstance(payload, dict) else []
+    rows = [(m.get("id"), (m.get("label") or "")[:24], m.get("owned_by"), m.get("type"), ",".join(m.get("capabilities") or [])) for m in data]
+    _emit(args, payload, rows, ("id", "label", "owned_by", "type", "capabilities"))
+
+
+def cmd_announcements(args):
+    status, payload = _request(args, "GET", "/announcements/", {"limit": args.limit})
+    _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("rank"), (it.get("publish_at") or "")[:10]) for it in items]
+    _emit(args, payload, rows, ("id", "title", "rank", "publish_at"))
+
+
+# ---- write commands (gated by --yes) -------------------------------------
+
+def _guard(args, action: str, detail: dict) -> bool:
+    if args.yes:
+        return True
+    print("DRY RUN — pass --yes to execute.")
+    print(f"action: {action}")
+    print(f"target: {json.dumps(detail, ensure_ascii=False)}")
+    return False
+
+
+def cmd_create_key(args):
+    body = {"application_id": args.application}
+    if args.name:
+        body["name"] = args.name
+    if args.limited_amount is not None:
+        body["limited_amount"] = args.limited_amount
+    if args.expired_at:
+        body["expired_at"] = args.expired_at
+    if not _guard(args, "POST /credentials/", body):
+        return
+    status, payload = _request(args, "POST", "/credentials/", body=body)
+    _check_ok(status, payload)
+    print("# new key created — store the token now, it is shown in full only once")
+    _emit(args, payload, force_reveal=True)
+
+
+def cmd_delete_key(args):
+    if not _guard(args, f"DELETE /credentials/{args.id}", {"id": args.id}):
+        return
+    status, payload = _request(args, "DELETE", f"/credentials/{args.id}")
+    _check_ok(status, payload)
+    print(f"deleted credential {args.id} (HTTP {status})")
+
+
+def cmd_create_order(args):
+    body = {"application_id": args.application, "package_id": args.package}
+    if not _guard(args, "POST /orders/", body):
+        return
+    status, payload = _request(args, "POST", "/orders/", body=body)
+    _check_ok(status, payload)
+    _emit(args, payload)
+
+
+def cmd_pay_order(args):
+    body = {"pay_way": args.pay_way}
+    if not _guard(args, f"POST /orders/{args.id}/pay/", body):
+        return
+    status, payload = _request(args, "POST", f"/orders/{args.id}/pay/", body=body)
+    _check_ok(status, payload)
+    if isinstance(payload, dict) and payload.get("pay_url"):
+        print(f"pay_url: {payload['pay_url']}")
+    _emit(args, payload)
+
+
+def cmd_create_token(args):
+    if not _guard(args, "POST /platform-tokens/", {}):
+        return
+    status, payload = _request(args, "POST", "/platform-tokens/", body={})
+    _check_ok(status, payload)
+    print("# new platform token — store it now, it is shown in full only once")
+    _emit(args, payload, force_reveal=True)
+
+
+def cmd_delete_token(args):
+    if not _guard(args, f"DELETE /platform-tokens/{args.id}/", {"id": args.id}):
+        return
+    status, payload = _request(args, "DELETE", f"/platform-tokens/{args.id}/")
+    _check_ok(status, payload)
+    print(f"deleted platform token {args.id} (HTTP {status})")
+
+
+def cmd_send_announcement(args):
+    body = {"title": args.title, "content": args.content, "published": not args.draft}
+    if args.rank is not None:
+        body["rank"] = args.rank
+    if args.tags:
+        body["tags"] = args.tags.split(",")
+    if not _guard(args, "POST /announcements/admin/ (superuser only)", body):
+        return
+    status, payload = _request(args, "POST", "/announcements/admin/", body=body)
+    _check_ok(status, payload)
+    _emit(args, payload)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # Global options use SUPPRESS defaults so a value parsed BEFORE the
+    # subcommand is not clobbered by the subparser re-injecting its own
+    # default. Without SUPPRESS, argparse overwrites `--json foo` back to
+    # False. Real defaults are applied in main() via _GLOBAL_DEFAULTS, so the
+    # options work in both positions (e.g. `--json keys` and `keys --json`).
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--token", default=argparse.SUPPRESS,
+                        help="platform token (default: $ACEDATACLOUD_PLATFORM_TOKEN)")
+    common.add_argument("--base-url", default=argparse.SUPPRESS, help="API base URL")
+    common.add_argument("--timeout", type=float, default=argparse.SUPPRESS,
+                        help="request timeout in seconds (default: 30)")
+    common.add_argument("--json", action="store_true", default=argparse.SUPPRESS,
+                        help="raw JSON output")
+    common.add_argument("--reveal", action="store_true", default=argparse.SUPPRESS,
+                        help="do not mask secrets in output")
+
+    p = argparse.ArgumentParser(description="AceDataCloud platform management CLI", parents=[common])
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def add(name, fn, help_):
+        sp = sub.add_parser(name, help=help_, parents=[common])
+        sp.set_defaults(func=fn)
+        return sp
+
+    sp = add("balance", cmd_balance, "remaining credits per subscription")
+    sp.add_argument("--limit", type=int, default=50)
+
+    sp = add("services", cmd_services, "list/search subscribed services")
+    sp.add_argument("--limit", type=int, default=100)
+    sp.add_argument("--search", help="filter by alias/title substring")
+
+    sp = add("usage", cmd_usage, "recent API call records")
+    sp.add_argument("--limit", type=int, default=20)
+    sp.add_argument("--days", type=int, help="only records newer than N days")
+    sp.add_argument("--status-code", type=int)
+    sp.add_argument("--api", help="filter by api_id")
+
+    sp = add("usage-summary", cmd_usage_summary, "spend aggregated by API")
+    sp.add_argument("--days", type=int, default=30)
+    sp.add_argument("--api", help="filter by api_id")
+
+    sp = add("keys", cmd_keys, "list API keys (credentials)")
+    sp.add_argument("--limit", type=int, default=50)
+    sp.add_argument("--application", help="filter by application_id")
+
+    sp = add("orders", cmd_orders, "list recharge orders")
+    sp.add_argument("--limit", type=int, default=20)
+    sp.add_argument("--state")
+    sp.add_argument("--pay-way", dest="pay_way")
+
+    sp = add("tokens", cmd_tokens, "list platform tokens")
+    sp.add_argument("--limit", type=int, default=50)
+
+    add("models", cmd_models, "list available chat models")
+
+    sp = add("announcements", cmd_announcements, "list announcements")
+    sp.add_argument("--limit", type=int, default=20)
+
+    sp = add("create-key", cmd_create_key, "create an API key (needs --yes)")
+    sp.add_argument("--application", required=True)
+    sp.add_argument("--name")
+    sp.add_argument("--limited-amount", dest="limited_amount", type=float)
+    sp.add_argument("--expired-at", dest="expired_at")
+    sp.add_argument("--yes", action="store_true")
+
+    sp = add("delete-key", cmd_delete_key, "delete an API key (needs --yes)")
+    sp.add_argument("--id", required=True)
+    sp.add_argument("--yes", action="store_true")
+
+    sp = add("create-order", cmd_create_order, "create a recharge order (needs --yes)")
+    sp.add_argument("--application", required=True)
+    sp.add_argument("--package", required=True)
+    sp.add_argument("--yes", action="store_true")
+
+    sp = add("pay-order", cmd_pay_order, "create a pay link for an order (needs --yes)")
+    sp.add_argument("--id", required=True)
+    sp.add_argument("--pay-way", dest="pay_way", default="Stripe")
+    sp.add_argument("--yes", action="store_true")
+
+    sp = add("create-token", cmd_create_token, "create a platform token (needs --yes)")
+    sp.add_argument("--yes", action="store_true")
+
+    sp = add("delete-token", cmd_delete_token, "delete a platform token (needs --yes)")
+    sp.add_argument("--id", required=True)
+    sp.add_argument("--yes", action="store_true")
+
+    sp = add("send-announcement", cmd_send_announcement, "publish an announcement (superuser; needs --yes)")
+    sp.add_argument("--title", required=True)
+    sp.add_argument("--content", required=True)
+    sp.add_argument("--rank", type=int)
+    sp.add_argument("--tags", help="comma-separated")
+    sp.add_argument("--draft", action="store_true", help="create unpublished")
+    sp.add_argument("--yes", action="store_true")
+
+    return p
+
+
+_GLOBAL_DEFAULTS = {
+    "token": None,
+    "base_url": DEFAULT_BASE_URL,
+    "timeout": 30.0,
+    "json": False,
+    "reveal": False,
+}
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    # Apply defaults for any global option not supplied in either position
+    # (they use argparse.SUPPRESS so unset attrs are simply absent).
+    for attr, default in _GLOBAL_DEFAULTS.items():
+        if not hasattr(args, attr):
+            setattr(args, attr, default)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

package/skills/acedatacloud-api/SKILL.md

@@ -1,130 +0,0 @@
----
-name: acedatacloud-api
-description: Guide for using AceDataCloud APIs. Use when authenticating, making API calls, managing credentials, understanding billing, or integrating AceDataCloud services into applications. Covers setup, authentication, request patterns, error handling, and SDK integration.
-license: Apache-2.0
-metadata:
-  author: acedatacloud
-  version: "1.0"
-compatibility: Requires an AceDataCloud account at platform.acedata.cloud.
----
-
-# AceDataCloud API Usage Guide
-
-Complete guide for using AceDataCloud's AI-powered data services API.
-
-## Getting Started
-
-### 1. Create an Account
-
-Register at [platform.acedata.cloud](https://platform.acedata.cloud).
-
-### 2. Subscribe to a Service
-
-Browse available services and click **Get** to subscribe. Most services include free quota.
-
-### 3. Create API Credentials
-
-Go to your service's **Credentials** page and create an API Token.
-
-> **Full details:** See [authentication](../_shared/authentication.md) for token types and usage.
-
-## SDK Integration (OpenAI-Compatible)
-
-For chat completion services, use the standard OpenAI SDK:
-
-```python
-from openai import OpenAI
-
-client = OpenAI(
-    api_key="YOUR_API_TOKEN",
-    base_url="https://api.acedata.cloud/v1"
-)
-
-response = client.chat.completions.create(
-    model="claude-sonnet-4-20250514",
-    messages=[{"role": "user", "content": "Hello!"}]
-)
-```
-
-```javascript
-import OpenAI from "openai";
-
-const client = new OpenAI({
-  apiKey: "YOUR_API_TOKEN",
-  baseURL: "https://api.acedata.cloud/v1"
-});
-
-const response = await client.chat.completions.create({
-  model: "gpt-4.1",
-  messages: [{ role: "user", content: "Hello!" }]
-});
-```
-
-## Request Patterns
-
-### Synchronous APIs
-
-Some APIs return results immediately (e.g., face transform, search):
-
-```bash
-curl -X POST https://api.acedata.cloud/face/analyze \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"image_url": "https://example.com/photo.jpg"}'
-```
-
-### Async Task APIs
-
-Most generation APIs (images, video, music) are asynchronous.
-
-> **Full details:** See [async task polling](../_shared/async-tasks.md) for the submit-and-poll pattern.
-
-## Error Handling
-
-| HTTP Code | Meaning | Action |
-|-----------|---------|--------|
-| 400 | Bad request | Check request parameters |
-| 401 | Unauthorized | Check API token |
-| 403 | Forbidden | Content filtered or insufficient permissions |
-| 429 | Rate limited | Wait and retry with backoff |
-| 500 | Server error | Retry or contact support |
-
-Error response format:
-
-```json
-{
-  "error": {
-    "code": "token_mismatched",
-    "message": "Invalid or expired token"
-  }
-}
-```
-
-## Billing
-
-- Each API call deducts from your **subscription balance** (remaining_amount)
-- Cost varies by service, model, and usage (tokens, requests, data size)
-- Check balance at [platform.acedata.cloud](https://platform.acedata.cloud)
-- Most services offer free trial quota
-
-## Service Categories
-
-| Category | Services | Base Path |
-|----------|----------|-----------|
-| **AI Chat** | GPT, Claude, Gemini, Kimi, Grok | `/v1/chat/completions` |
-| **Image Gen** | Flux, Seedream, NanoBanana | `/flux/*`, `/seedream/*`, etc. |
-| **Video Gen** | Luma, Sora, Veo, Kling, Hailuo, Seedance, Wan | `/luma/*`, `/sora/*`, etc. |
-| **Music Gen** | Suno, Producer, Fish Audio | `/suno/*`, `/producer/*`, `/fish/*` |
-| **Search** | Google Search (web/images/news/maps) | `/serp/*` |
-| **Face** | Analyze, beautify, swap, cartoon, age | `/face/*` |
-| **Utility** | Short URL, QR Art, Headshots | `/short-url`, `/qrart/*`, `/headshots/*` |
-
-## Gotchas
-
-- Tokens are **service-scoped** by default — create a global token if you need cross-service access
-- Async APIs return a `task_id` — always use `callback_url` to get the task_id immediately, then poll for results
-- Avoid `wait: true` — it blocks for the full generation duration and will time out for video/music tasks
-- Rate limits vary by service tier — upgrade your plan if hitting limits
-- All timestamps are in UTC
-
-> **MCP:** See [MCP servers](../_shared/mcp-servers.md) for tool-use integration with AI agents.