@acedatacloud/skills 2026.425.1 → 2026.504.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.425.1",
+  "version": "2026.504.1",
   "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/tencentcloud.md

@@ -0,0 +1,84 @@
+# Tencent Cloud Authentication
+
+All `tencentcloud-*` skills authenticate with the same SecretId / SecretKey pair via the official Tencent Cloud Python SDK.
+
+## Get Your Credentials
+
+1. Sign in to [Tencent Cloud Console](https://console.cloud.tencent.com/cam/capi)
+2. Navigate to **Access Management → API Keys → Create Key**
+3. You'll get a **SecretId** (starts with `AKID...`) and a **SecretKey** that's displayed exactly once — save it before closing the page.
+
+> ⚠️ **Use a sub-account, not your main account.** Create a CAM sub-user with only the policies the skill needs (e.g. `QcloudCOSReadOnlyAccess` for read-only COS, `QcloudCLSReadOnlyAccess` for log queries) and generate the keys for that sub-account. Limits the blast radius if the credentials leak.
+
+## Setup
+
+The Tencent Cloud SDK reads credentials from these environment variables:
+
+| Variable | Description | Example |
+|---|---|---|
+| `TENCENTCLOUD_SECRET_ID` | API SecretId | `AKIDxxxxxxxxxxxx` |
+| `TENCENTCLOUD_SECRET_KEY` | API SecretKey (sensitive) | `xxxxxxxxxxxxxxxx` |
+| `TENCENTCLOUD_REGION` | Default region | `ap-hongkong`, `ap-guangzhou`, ... |
+
+**Local dev — `.env` file**:
+
+```bash
+TENCENTCLOUD_SECRET_ID=AKID...
+TENCENTCLOUD_SECRET_KEY=...
+TENCENTCLOUD_REGION=ap-hongkong
+```
+
+Load it before running any tool:
+
+```bash
+set -a; source .env; set +a
+```
+
+> ⚠️ **Important:** Add `.env` to your `.gitignore` — never commit credentials to git.
+
+**Agent usage** (Claude / Studio / etc.): If you've installed the [腾讯云 connector](https://auth.acedata.cloud/user/connections) on AceDataCloud, your encrypted credentials are auto-injected as the env vars above when the agent runs any `tencentcloud-*` skill — no manual `.env` setup needed.
+
+## Common regions
+
+| Region code | Location |
+|---|---|
+| `ap-hongkong` | Hong Kong, China |
+| `ap-guangzhou` | Guangzhou |
+| `ap-beijing` | Beijing |
+| `ap-shanghai` | Shanghai |
+| `ap-singapore` | Singapore |
+| `ap-tokyo` | Tokyo |
+| `eu-frankfurt` | Frankfurt |
+| `na-siliconvalley` | Silicon Valley |
+| `na-ashburn` | Ashburn (Virginia) |
+
+Full list: [Tencent Cloud regions and AZs](https://www.tencentcloud.com/document/product/213/6091).
+
+## Verifying credentials
+
+A quick sanity check that doesn't cost anything:
+
+```python
+from tencentcloud.common import credential
+from tencentcloud.cam.v20190116 import cam_client, models
+
+cred = credential.EnvironmentVariableCredential().get_credential()
+client = cam_client.CamClient(cred, "ap-guangzhou")
+resp = client.GetUserAppId(models.GetUserAppIdRequest())
+print("OK, AppId =", resp.AppId)
+```
+
+Returns your Tencent Cloud `AppId` (a numeric account identifier). Any 4xx tells you the keys are wrong / expired / lack `QcloudCamReadOnlyAccess`.
+
+## Dependencies
+
+```bash
+pip install tencentcloud-sdk-python
+```
+
+Service-specific add-ons used by individual skills:
+
+```bash
+pip install cos-python-sdk-v5      # tencentcloud-cos
+pip install kubernetes              # tencentcloud-tke (kubeconfig handling)
+```

package/skills/tencentcloud-cls/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: tencentcloud-cls
+description: |
+  Search and analyze Tencent Cloud CLS (Cloud Log Service) logs. Use
+  whenever the user asks to: search logs, debug API errors, trace
+  requests by trace ID, find 5xx errors, run CQL/SQL analytics over
+  log topics, extract structured fields. Backed by the official
+  tencentcloud-sdk-python CLS client.
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+connections: [tencentcloud]
+---
+
+# Tencent Cloud CLS (Log Service) — Search & Analysis
+
+Search and run CQL / SQL analytics over Tencent Cloud CLS log topics.
+
+> **Setup:** See [tencentcloud authentication](../_shared/tencentcloud.md). The SDK reads `TENCENTCLOUD_SECRET_ID` / `TENCENTCLOUD_SECRET_KEY` / `TENCENTCLOUD_REGION` from the environment.
+>
+> **Companion skill:** Use `tencentcloud-cls-alarm` for alarm policy / notice group / shield management. This skill is only about searching log content.
+
+## CLI (preferred)
+
+The skill ships [`scripts/cls.py`](scripts/cls.py) — a self-contained CLI for the most common operations.
+
+```bash
+CLS=$SKILL_DIR/scripts/cls.py
+
+python3 $CLS topics                                              # list topics
+python3 $CLS search --topic <topic-id> --query 'level:ERROR' --time 1h
+python3 $CLS search --topic <topic-id> --trace-id <uuid>
+python3 $CLS search --topic <topic-id> --time 1d \
+    --query '* | SELECT api_name, count(*) AS cnt GROUP BY api_name ORDER BY cnt DESC LIMIT 20' \
+    --format json
+```
+
+`--time` accepts `30m / 1h / 6h / 1d / 7d`. `--query` is CQL by default; pass `--lucene` to switch dialect. Append `| SELECT ... GROUP BY ...` to a query for SQL analytics.
+
+For anything beyond what the CLI exposes (custom field projections, raw paginated walks, `Context`-based tailing) drop down to the SDK calls below.
+
+## When to Use
+
+- Find recent errors / 5xx responses for a service
+- Look up a single request by trace ID across multiple topics
+- Run CQL filters (`status_code:>=500 AND service:"openai"`)
+- Run SQL analytics (`SELECT api_name, COUNT(*) GROUP BY api_name`)
+- Chain trace logs to reconstruct a request lifecycle
+- Extract specific fields for billing / audit reports
+
+## Dependencies
+
+```bash
+pip install tencentcloud-sdk-python
+```
+
+## Quick start
+
+```python
+import os
+import json
+from tencentcloud.common import credential
+from tencentcloud.cls.v20201016 import cls_client, models
+
+cred = credential.EnvironmentVariableCredential().get_credential()
+client = cls_client.ClsClient(cred, os.environ["TENCENTCLOUD_REGION"])
+```
+
+## Workflows
+
+### Discover topics
+
+```python
+req = models.DescribeTopicsRequest()
+resp = client.DescribeTopics(req)
+for t in resp.Topics:
+    print(t.TopicId, t.TopicName, t.LogsetId)
+```
+
+> Tip: ask the user for the topic ID up front. Topic IDs look like `751a7350-dc5d-41c3-a6ca-c178bae05807` and aren't guessable from a service name.
+
+### Search logs (CQL)
+
+```python
+import time
+
+req = models.SearchLogRequest()
+req.TopicId = "<topic-id>"
+req.From = int((time.time() - 3600) * 1000)   # 1 hour ago, ms epoch
+req.To = int(time.time() * 1000)
+req.Query = 'status_code:>=500 AND service:"openai"'
+req.Limit = 100
+req.Sort = "desc"
+req.SyntaxRule = 1                             # 1 = CQL, 0 = Lucene
+
+resp = client.SearchLog(req)
+for line in resp.Results:
+    fields = {f.Key: f.Value for f in line.LogJson and []}  # see below
+    print(line.Time, line.PkgLogId, fields.get("status_code"), fields.get("api_name"))
+```
+
+> CLS hands you `Results` with `LogJson` as a JSON string per record. Decode with `json.loads(line.LogJson)` to get a flat dict of all the indexed fields the topic stores.
+
+### Look up a trace ID across multiple topics
+
+```python
+TRACE_ID = "34341776-0835-422a-956d-ac8d5b404db1"
+TOPICS = {
+    "trace": "<trace-topic-id>",
+    "api-usages": "<api-usages-topic-id>",
+}
+
+for label, topic_id in TOPICS.items():
+    req = models.SearchLogRequest()
+    req.TopicId = topic_id
+    req.From = int((time.time() - 86400) * 1000)
+    req.To = int(time.time() * 1000)
+    req.Query = f'trace_id:"{TRACE_ID}"'
+    req.Limit = 100
+    req.SyntaxRule = 1
+    resp = client.SearchLog(req)
+    print(f"--- {label}: {len(resp.Results)} records ---")
+    for line in resp.Results:
+        print(line.Time, line.LogJson)
+```
+
+### SQL analytics
+
+CLS supports a SQL-on-logs subset for aggregation. Append `| <SQL>` to a CQL filter:
+
+```python
+req.Query = '* | SELECT api_name, count(*) AS cnt GROUP BY api_name ORDER BY cnt DESC LIMIT 20'
+req.SyntaxRule = 1
+resp = client.SearchLog(req)
+# When the query has a `|`, results land in resp.Analysis (rows of column→value)
+for row in resp.AnalysisResults or []:
+    print(row)
+```
+
+### Tail recent logs
+
+```python
+# Poll every 5s for new lines after the last cursor
+last_cursor = None
+while True:
+    req = models.SearchLogRequest()
+    req.TopicId = topic_id
+    req.From = int((time.time() - 30) * 1000)
+    req.To = int(time.time() * 1000)
+    req.Query = 'level:ERROR'
+    req.Limit = 100
+    req.Sort = "asc"
+    req.SyntaxRule = 1
+    if last_cursor:
+        req.Context = last_cursor
+    resp = client.SearchLog(req)
+    for line in resp.Results:
+        print(line.Time, line.LogJson)
+    last_cursor = resp.Context
+    time.sleep(5)
+```
+
+## CQL cheatsheet
+
+| Pattern | Meaning |
+|---|---|
+| `status_code:500` | exact match |
+| `status_code:>=500` | range |
+| `status_code:[500 TO 599]` | range with bounds |
+| `service:"openai"` | quoted phrase (use for values containing spaces) |
+| `NOT level:DEBUG` | negation |
+| `service:openai AND status_code:>=400` | conjunction |
+| `(api:foo OR api:bar)` | grouping |
+| `* | SELECT ... GROUP BY ...` | switch into SQL analytics |
+
+## Pagination
+
+CLS returns up to 1000 records per call. For larger result sets, iterate with `Context`:
+
+```python
+all_records = []
+context = None
+while True:
+    req = models.SearchLogRequest()
+    req.TopicId = topic_id
+    req.From = ...
+    req.To = ...
+    req.Query = '...'
+    req.Limit = 1000
+    req.SyntaxRule = 1
+    if context:
+        req.Context = context
+    resp = client.SearchLog(req)
+    all_records.extend(resp.Results)
+    context = resp.Context
+    if not context or len(resp.Results) < 1000:
+        break
+```
+
+## Error patterns
+
+| Symptom | Likely cause |
+|---|---|
+| `InvalidParameter.QueryError` | Quote phrases that contain `:` or spaces; check `SyntaxRule` matches the query |
+| `LimitExceeded` | Concurrent `SearchLog` calls exceed the 30-QPS quota — back off & retry |
+| `OperationDenied.AccountIsolated` | CLS service is suspended for billing — check the console |
+| Empty `Results` but logs visible in console | Time range is wrong (`From` / `To` are ms epoch, not seconds), or topic has different field names than the query expects |
+
+## Console links
+
+- CLS console: <https://console.cloud.tencent.com/cls/topic>
+- CQL syntax: <https://www.tencentcloud.com/document/product/614/47044>
+- SQL analytics syntax: <https://www.tencentcloud.com/document/product/614/58978>

package/skills/tencentcloud-cls/scripts/cls.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Tencent Cloud CLS (Cloud Log Service) — search & analytics CLI.
+
+Search log topics with CQL filters or run SQL analytics over them.
+
+Quick examples:
+  python3 $SKILL_DIR/scripts/cls.py topics
+  python3 $SKILL_DIR/scripts/cls.py search --topic <topic-id> --query 'level:ERROR' --time 1h
+  python3 $SKILL_DIR/scripts/cls.py search --topic <topic-id> --trace-id <uuid>
+  python3 $SKILL_DIR/scripts/cls.py search --topic <topic-id> \\
+      --query '* | SELECT api_name, count(*) AS cnt GROUP BY api_name ORDER BY cnt DESC LIMIT 20' \\
+      --time 1d
+
+Environment:
+  TENCENTCLOUD_SECRET_ID   — required
+  TENCENTCLOUD_SECRET_KEY  — required
+  TENCENTCLOUD_REGION      — optional, default ap-hongkong
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+
+DEFAULT_REGION = os.environ.get("TENCENTCLOUD_REGION", "ap-hongkong")
+
+
+def get_client(region: str = DEFAULT_REGION):
+    try:
+        from tencentcloud.cls.v20201016 import cls_client
+        from tencentcloud.common import credential
+    except ImportError:
+        print(
+            "ERROR: tencentcloud-sdk-python not installed.\nRun: pip3 install tencentcloud-sdk-python",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    secret_id = os.environ.get("TENCENTCLOUD_SECRET_ID")
+    secret_key = os.environ.get("TENCENTCLOUD_SECRET_KEY")
+    if not secret_id or not secret_key:
+        print(
+            "ERROR: TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY must be set in env",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    cred = credential.Credential(secret_id, secret_key)
+    return cls_client.ClsClient(cred, region)
+
+
+# ---------------------------------------------------------------------------
+# Time parsing — accepts `30m`, `1h`, `6h`, `1d`, `7d`.
+# ---------------------------------------------------------------------------
+
+_TIME_RE = re.compile(r"^(\d+)([smhd])$")
+
+
+def parse_relative(spec: str) -> int:
+    """Return milliseconds for a string like `1h` / `30m` / `7d`."""
+    m = _TIME_RE.match(spec)
+    if not m:
+        raise ValueError(f"bad --time: {spec!r}; use e.g. 30m, 1h, 6h, 1d, 7d")
+    n, unit = int(m.group(1)), m.group(2)
+    return n * {"s": 1000, "m": 60_000, "h": 3_600_000, "d": 86_400_000}[unit]
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+def cmd_topics(args):
+    """List all log topics in the region."""
+    from tencentcloud.cls.v20201016 import models
+
+    client = get_client(args.region)
+    req = models.DescribeTopicsRequest()
+    if args.logset_id:
+        req.Filters = [{"Key": "logsetId", "Values": [args.logset_id]}]
+    resp = client.DescribeTopics(req)
+    if args.format == "json":
+        print(json.dumps([t._serialize() for t in (resp.Topics or [])], indent=2, ensure_ascii=False))
+        return
+    print(f"{'TopicId':40s}  {'TopicName':32s}  {'LogsetId'}")
+    for t in resp.Topics or []:
+        print(f"{t.TopicId:40s}  {(t.TopicName or '')[:32]:32s}  {t.LogsetId}")
+
+
+def cmd_search(args):
+    """Search a topic with a CQL / SQL query."""
+    from tencentcloud.cls.v20201016 import models
+
+    client = get_client(args.region)
+    req = models.SearchLogRequest()
+    req.TopicId = args.topic
+    now_ms = int(time.time() * 1000)
+    req.From = now_ms - parse_relative(args.time)
+    req.To = now_ms
+
+    if args.trace_id:
+        query = f'trace_id:"{args.trace_id}"'
+    else:
+        query = args.query
+    req.Query = query
+    req.Limit = args.limit
+    req.Sort = args.sort
+    req.SyntaxRule = 0 if args.lucene else 1
+
+    resp = client.SearchLog(req)
+
+    # Analytics queries (have a `|`) land in AnalysisResults.
+    if "|" in query and (resp.AnalysisResults or []):
+        rows = []
+        for row in resp.AnalysisResults or []:
+            rows.append({c.Name: c.Value for c in row.Data})
+        if args.format == "json":
+            print(json.dumps(rows, indent=2, ensure_ascii=False))
+        else:
+            for r in rows:
+                print(json.dumps(r, ensure_ascii=False))
+        return
+
+    out = []
+    for line in resp.Results or []:
+        try:
+            fields = json.loads(line.LogJson) if line.LogJson else {}
+        except Exception:
+            fields = {"_raw": line.LogJson}
+        out.append({"time_ms": line.Time, "fields": fields})
+    if args.format == "json":
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        for entry in out:
+            ts = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(entry["time_ms"] / 1000))
+            f = entry["fields"]
+            short = " ".join(f"{k}={v}" for k, v in list(f.items())[:6])
+            print(f"{ts}  {short}")
+    if resp.Context:
+        print(f"\n# more results: --context {resp.Context}", file=sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# Argparse
+# ---------------------------------------------------------------------------
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Search Tencent Cloud CLS log topics.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    parser.add_argument(
+        "--region",
+        default=DEFAULT_REGION,
+        help=f"Tencent Cloud region (default: {DEFAULT_REGION})",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_topics = sub.add_parser("topics", help="List log topics")
+    p_topics.add_argument("--logset-id", help="Filter to one logset")
+    p_topics.add_argument("--format", choices=["text", "json"], default="text")
+    p_topics.set_defaults(func=cmd_topics)
+
+    p_search = sub.add_parser("search", help="Search a topic")
+    p_search.add_argument("--topic", required=True, help="TopicId (UUID)")
+    g = p_search.add_mutually_exclusive_group(required=True)
+    g.add_argument("--query", "-q", help="CQL or SQL query (use `|` for SQL analytics)")
+    g.add_argument("--trace-id", help="Shortcut for trace_id:\"<id>\"")
+    p_search.add_argument("--time", default="1h", help="Time range (30m, 1h, 6h, 1d, 7d). Default 1h.")
+    p_search.add_argument("--limit", type=int, default=100, help="Max results (default 100)")
+    p_search.add_argument("--sort", choices=["asc", "desc"], default="desc")
+    p_search.add_argument("--lucene", action="store_true", help="Treat --query as Lucene (default CQL)")
+    p_search.add_argument("--format", choices=["text", "json"], default="text")
+    p_search.set_defaults(func=cmd_search)
+
+    args = parser.parse_args()
+    return args.func(args) or 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())