@acedatacloud/skills 2026.621.2 → 2026.621.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.621.2",
+  "version": "2026.621.4",
   "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/cn-blog/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: cn-blog
+description: Read and publish on Chinese content platforms with the user's own login cookies (BYOC) — list their published articles with vote/comment stats, inspect one article, and publish a new article. Use when the user mentions 知乎 / Zhihu, "我的知乎文章", reading their article stats (点赞/评论), or publishing/发文 to Zhihu.
+when_to_use: |
+  Trigger for anything on the user's Zhihu (知乎) account driven by their own
+  login cookie: show who they are, list their published articles with
+  vote-up / comment counts, look at one article's stats, or publish a new
+  article. This acts as the user's real account, so writes are gated behind
+  an explicit confirmation.
+connections: [zhihu]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+# cn-blog — Zhihu via your own cookies
+
+Drives the user's **real** Zhihu account through the same web APIs the site's
+own editor uses, authenticated by the login cookie they captured with the ACE
+extension. No browser, no third-party deps — just `urllib`.
+
+The connector injects the cookie jar as an env var:
+
+- `ZHIHU_COOKIES` — a JSON array of `{name, value, domain, path, ...}` cookies.
+  **Secret — never echo or print it.** The CLI reads it for you.
+
+## CLI
+
+The skill ships [`scripts/blog.py`](scripts/blog.py) — self-contained, stdlib only.
+
+```sh
+BLOG=$SKILL_DIR/scripts/blog.py
+
+# Read (run directly)
+python3 $BLOG whoami                       # who is logged in
+python3 $BLOG articles --limit 20          # my published articles + stats
+python3 $BLOG article <article-id>         # one article's details + stats
+```
+
+## Verify the connection first
+
+```sh
+python3 $BLOG whoami
+# → {"id": "...", "name": "崔庆才丨静觅", "url_token": "cui-qing-cai", ...}
+```
+
+On a `401`/`403` the cookie is expired — tell the user to reconnect at
+<https://auth.acedata.cloud/user/connections> (re-capture with the ACE
+extension). Do **not** retry in a loop.
+
+## Reading recipes
+
+| Goal | Command |
+|---|---|
+| Who am I | `python3 $BLOG whoami` |
+| My latest articles + vote/comment counts | `python3 $BLOG articles --limit 20` |
+| Next page | `python3 $BLOG articles --limit 20 --offset 20` |
+| One article's stats | `python3 $BLOG article <id>` |
+
+Stats come straight from Zhihu: `voteup_count` (赞同), `comment_count` (评论).
+Zhihu does not expose per-article read counts on these endpoints.
+
+## Publishing — GATED (dry-run unless trailing `--confirm`)
+
+`publish` writes to the user's real account. Without a trailing `--confirm` it
+**dry-runs** (prints what it would do, changes nothing). `--confirm` is honored
+**only as the last argument**, so a title/content containing "--confirm" can
+never silently go live. Always show the dry-run to the user, get an explicit
+"yes", then re-run with `--confirm` last.
+
+```sh
+# Content is HTML. For Markdown, convert to HTML first.
+python3 $BLOG publish --title "标题" --content-file article.html               # dry-run
+python3 $BLOG publish --title "标题" --content-file article.html --draft-only --confirm  # save a private draft
+python3 $BLOG publish --title "标题" --content-file article.html --confirm     # PUBLIC, goes live
+```
+
+- `--draft-only` stops after saving a private draft (safe — nothing public).
+- Without `--draft-only`, the article is **published publicly** under the user's
+  name. Default to `--draft-only` unless the user clearly asked to go live.
+- Images: only image URLs already reachable on the public web are kept as-is;
+  this CLI does not re-upload local images to Zhihu's CDN.
+
+## Gotchas — surface before the user is surprised
+
+- **This is the user's real Zhihu account.** Confirm before any publish; reading
+  exposes their own private drafts.
+- **Cookie expiry**: Zhihu cookies are short-lived. A `401`/`403` means
+  reconnect at auth.acedata.cloud/user/connections — never loop-retry.
+- **ToS**: cookie automation is against most platforms' terms. This only ever
+  acts on the user's own account with their own captured cookie; the user owns
+  that risk. Never use it to scrape other people's content at scale.
+- **Never print `ZHIHU_COOKIES`** — it is full account access.
+- **Scope today**: Zhihu only. 掘金 / CSDN connectors exist in the vault and are
+  planned next; this skill will grow a `--platform` switch for them.

package/skills/cn-blog/scripts/blog.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+"""
+cn-blog — read & publish on Chinese content platforms with the user's own
+login cookies (BYOC). Standard-library only (urllib), no third-party deps,
+so it runs in the bare sandbox without an image change.
+
+The connector injects the user's cookie jar as a JSON env var named
+``<PLATFORM>_COOKIES`` (e.g. ``ZHIHU_COOKIES``) — a list of
+``{name, value, domain, path, ...}`` dicts captured by the ACE extension.
+
+Read commands run directly. ``publish`` is GATED: without a trailing
+``--confirm`` it only dry-runs (prints what it would do, changes nothing).
+``--confirm`` is honored ONLY as the last argument, so a title/content that
+merely contains "--confirm" can never silently go live.
+
+Quick examples:
+  python3 $SKILL_DIR/scripts/blog.py whoami
+  python3 $SKILL_DIR/scripts/blog.py articles --limit 20
+  python3 $SKILL_DIR/scripts/blog.py article <article-id>
+  python3 $SKILL_DIR/scripts/blog.py drafts
+  python3 $SKILL_DIR/scripts/blog.py publish --title "T" --content-file a.html --draft-only --confirm
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+UA = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
+)
+
+# --confirm is only honored as the LAST token so a value that merely
+# contains "--confirm" can never silently confirm a write.
+_RAW = sys.argv[1:]
+CONFIRM = bool(_RAW) and _RAW[-1] == "--confirm"
+ARGV = _RAW[:-1] if CONFIRM else list(_RAW)
+
+
+def out(obj) -> None:
+    print(json.dumps(obj, ensure_ascii=False, indent=2, default=str))
+
+
+def die(msg: str, code: int = 1) -> None:
+    out({"error": msg})
+    sys.exit(code)
+
+
+# ── Cookie jar (from env) ───────────────────────────────────────────
+
+def load_cookies(platform: str) -> list[dict]:
+    env = f"{platform.upper()}_COOKIES"
+    raw = os.environ.get(env)
+    if not raw:
+        die(
+            f"{env} is not set — connect the {platform} account at "
+            f"https://auth.acedata.cloud/user/connections, then retry."
+        )
+    try:
+        jar = json.loads(raw)
+    except json.JSONDecodeError as e:
+        die(f"{env} is not valid JSON: {e}")
+    if not isinstance(jar, list):
+        die(f"{env} must be a JSON list of cookies, got {type(jar).__name__}")
+    return jar
+
+
+def _domain_matches(host: str, domain: str) -> bool:
+    # Browser-style domain match: a cookie scoped to ".zhihu.com" / "zhihu.com"
+    # is sent to zhihu.com and any subdomain; a host-only cookie matches exactly.
+    d = domain.lstrip(".").lower()
+    h = host.lower()
+    return not d or h == d or h.endswith("." + d)
+
+
+def cookie_header(jar: list[dict], url: str) -> str:
+    # Only send a cookie to a host inside its domain scope, so a jar is never
+    # replayed outside the platform it was captured for (defense in depth — all
+    # request URLs here are first-party, but this future-proofs multi-platform).
+    host = urllib.parse.urlsplit(url).hostname or ""
+    # A domainless cookie has no scope of its own; only send it to a host the
+    # jar's domain-scoped cookies already cover (i.e. this jar's own platform),
+    # never fail-open to an arbitrary host.
+    host_in_scope = any(
+        c.get("domain") and _domain_matches(host, str(c["domain"])) for c in jar
+    )
+    parts = []
+    for c in jar:
+        name, value = c.get("name"), c.get("value")
+        if not name or value is None:
+            continue
+        domain = c.get("domain")
+        if domain:
+            if not _domain_matches(host, str(domain)):
+                continue
+        elif not host_in_scope:
+            continue
+        parts.append(f"{name}={value}")
+    return "; ".join(parts)
+
+
+# ── HTTP (stdlib urllib) ────────────────────────────────────────────
+
+def request(method: str, url: str, jar: list[dict], *, headers=None, body=None):
+    hdrs = {
+        "User-Agent": UA,
+        "Accept": "application/json, text/plain, */*",
+        "Cookie": cookie_header(jar, url),
+    }
+    if headers:
+        hdrs.update(headers)
+    data = None
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        hdrs.setdefault("Content-Type", "application/json")
+    req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            raw = resp.read()
+            if resp.headers.get("Content-Encoding") == "gzip":
+                raw = gzip.decompress(raw)
+            return resp.status, raw.decode("utf-8", "replace")
+    except urllib.error.HTTPError as e:
+        raw = e.read()
+        try:
+            if e.headers.get("Content-Encoding") == "gzip":
+                raw = gzip.decompress(raw)
+        except Exception:
+            pass
+        return e.code, raw.decode("utf-8", "replace")
+    except urllib.error.URLError as e:
+        die(f"network error reaching {url}: {e.reason}")
+
+
+def get_json(url: str, jar: list[dict], **kw):
+    status, text = request("GET", url, jar, **kw)
+    if status == 401 or status == 403:
+        die(
+            f"auth failed ({status}) on {url} — the cookie is likely expired. "
+            f"Reconnect at https://auth.acedata.cloud/user/connections."
+        )
+    try:
+        return status, json.loads(text)
+    except json.JSONDecodeError:
+        die(f"non-JSON response ({status}) from {url}: {text[:300]}")
+
+
+# ── Zhihu ───────────────────────────────────────────────────────────
+
+ZH = {
+    "me": "https://www.zhihu.com/api/v4/me",
+    "articles": "https://www.zhihu.com/api/v4/members/{token}/articles",
+    "article": "https://www.zhihu.com/api/v4/articles/{id}",
+    "create_draft": "https://zhuanlan.zhihu.com/api/articles/drafts",
+}
+ZH_FETCH = {"x-requested-with": "fetch"}
+
+
+def zh_me(jar):
+    _, data = get_json(ZH["me"], jar, headers=ZH_FETCH)
+    if not data.get("id"):
+        die(f"could not read Zhihu profile (cookie expired?): {str(data)[:300]}")
+    return data
+
+
+def cmd_whoami(jar, _args):
+    me = zh_me(jar)
+    out({
+        "id": str(me.get("id", "")),
+        "name": me.get("name"),
+        "url_token": me.get("url_token"),
+        "headline": me.get("headline"),
+        "articles_count": me.get("articles_count"),
+        "voteup_count": me.get("voteup_count"),
+    })
+
+
+# Zhihu omits stats unless asked via `include`. This pulls the counts the
+# user actually cares about onto each article in the list/detail responses.
+ZH_ARTICLE_INCLUDE = "data[*].comment_count,voteup_count,created,updated,title,url"
+
+
+def _https(url):
+    if isinstance(url, str) and url.startswith("http://"):
+        return "https://" + url[len("http://"):]
+    return url
+
+
+def _fmt_article(a: dict) -> dict:
+    aid = a.get("id")
+    # Prefer the canonical public reader URL built from the id — the API's own
+    # `url` field is inconsistent (zhuanlan in the list, api.zhihu.com in detail).
+    return {
+        "id": str(aid) if aid is not None else None,
+        "title": a.get("title"),
+        "url": (f"https://zhuanlan.zhihu.com/p/{aid}" if aid else _https(a.get("url"))),
+        "voteup_count": a.get("voteup_count"),
+        "comment_count": a.get("comment_count"),
+        "created": a.get("created"),
+        "updated": a.get("updated"),
+    }
+
+
+def cmd_articles(jar, args):
+    me = zh_me(jar)
+    token = me.get("url_token")
+    if not token:
+        die("Zhihu profile has no url_token; cannot list articles.")
+    url = ZH["articles"].format(token=token)
+    q = urllib.parse.urlencode({
+        "include": ZH_ARTICLE_INCLUDE,
+        "limit": args.limit,
+        "offset": args.offset,
+    })
+    _, data = get_json(f"{url}?{q}", jar, headers=ZH_FETCH)
+    items = data.get("data", []) if isinstance(data, dict) else []
+    out({
+        "total": (data.get("paging") or {}).get("totals") if isinstance(data, dict) else None,
+        "count": len(items),
+        "articles": [_fmt_article(a) for a in items],
+    })
+
+
+def cmd_article(jar, args):
+    base = ZH["article"].format(id=args.id)
+    q = urllib.parse.urlencode({"include": "comment_count,voteup_count"})
+    _, a = get_json(f"{base}?{q}", jar, headers=ZH_FETCH)
+    if not isinstance(a, dict) or not a.get("id"):
+        die(f"article {args.id} not found or not accessible: {str(a)[:300]}")
+    res = _fmt_article(a)
+    res["content_excerpt"] = (a.get("excerpt") or "")[:200]
+    out(res)
+
+
+def cmd_publish(jar, args):
+    if not args.title:
+        die("--title is required")
+    if not args.content_file and args.content is None:
+        die("provide --content-file <path> or --content <html>")
+    content = args.content
+    if args.content_file:
+        try:
+            with open(args.content_file, encoding="utf-8") as f:
+                content = f.read()
+        except OSError as e:
+            die(f"cannot read --content-file: {e}")
+
+    if not CONFIRM:
+        out({
+            "dry_run": True,
+            "command": "publish",
+            "platform": "zhihu",
+            "title": args.title,
+            "draft_only": args.draft_only,
+            "content_bytes": len(content or ""),
+            "note": "re-run with --confirm as the LAST argument to actually write. "
+                    "Without --draft-only this publishes a PUBLIC article on the user's real account.",
+        })
+        return
+
+    # 1. create empty draft
+    status, text = request(
+        "POST", ZH["create_draft"], jar, headers=ZH_FETCH,
+        body={"title": args.title, "content": "", "delta_time": 0},
+    )
+    try:
+        created = json.loads(text)
+    except json.JSONDecodeError:
+        die(f"create-draft returned non-JSON ({status}): {text[:300]}")
+    draft_id = created.get("id")
+    if not draft_id:
+        die(f"create-draft failed ({status}): {str(created)[:300]}")
+
+    # 2. set draft content
+    status, text = request(
+        "PATCH", f"https://zhuanlan.zhihu.com/api/articles/{draft_id}/draft", jar,
+        headers=ZH_FETCH, body={"title": args.title, "content": content},
+    )
+    if status >= 400:
+        die(f"update-draft failed ({status}) for {draft_id}: {text[:300]}")
+
+    if args.draft_only:
+        out({
+            "ok": True,
+            "draft_only": True,
+            "draft_id": str(draft_id),
+            "edit_url": f"https://zhuanlan.zhihu.com/write?draftId={draft_id}",
+        })
+        return
+
+    # 3. publish (go live)
+    status, text = request(
+        "PUT", f"https://zhuanlan.zhihu.com/api/articles/{draft_id}/publish", jar,
+        headers=ZH_FETCH, body={},
+    )
+    if status >= 400:
+        die(f"publish failed ({status}) for {draft_id}; it remains a draft: {text[:300]}")
+    out({
+        "ok": True,
+        "published": True,
+        "article_id": str(draft_id),
+        "url": f"https://zhuanlan.zhihu.com/p/{draft_id}",
+    })
+
+
+COMMANDS = {
+    "whoami": cmd_whoami,
+    "articles": cmd_articles,
+    "article": cmd_article,
+    "publish": cmd_publish,
+}
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="blog.py", description="cn-blog cookie CLI")
+    p.add_argument("--platform", default="zhihu", choices=["zhihu"],
+                   help="content platform (only zhihu is implemented today)")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("whoami", help="show the logged-in account")
+
+    sp = sub.add_parser("articles", help="list the user's published articles + stats")
+    sp.add_argument("--limit", type=int, default=20)
+    sp.add_argument("--offset", type=int, default=0)
+
+    sp = sub.add_parser("article", help="one article's details + stats")
+    sp.add_argument("id")
+
+    sp = sub.add_parser("publish", help="create/publish an article (GATED by trailing --confirm)")
+    sp.add_argument("--title")
+    sp.add_argument("--content", help="HTML content inline")
+    sp.add_argument("--content-file", help="path to an HTML file")
+    sp.add_argument("--draft-only", action="store_true",
+                    help="create a draft only; do NOT go public")
+
+    args = p.parse_args(ARGV)
+    jar = load_cookies(args.platform)
+    COMMANDS[args.command](jar, args)
+
+
+if __name__ == "__main__":
+    main()

package/skills/telegram/SKILL.md

@@ -1,118 +1,242 @@
 ---
 name: telegram
-description: Read, search and send personal Telegram messages — list recent chats / contacts / groups, pull a conversation's history, search messages, and send a message — driven by the Telethon MTProto client with the user's own account. Use when the user mentions Telegram, a Telegram chat/group/contact, "我的 Telegram", reading or replying to Telegram messages, or summarizing Telegram conversations.
+description: Full personal Telegram control over MTProto (Telethon) with the user's own account — list/search chats, read & summarize history, see unread, look up contacts & chat info, download media, and send / reply / forward / edit / delete / react / send files / mark read. Use when the user mentions Telegram, a Telegram chat/group/contact, "我的 Telegram", reading/replying/forwarding/summarizing Telegram messages, their unread Telegram, or sending a file/message on Telegram.
 when_to_use: |
-  Trigger when the user wants to do anything with their personal Telegram
-  account: list recent conversations, read / summarize the history of a chat
-  or group, search their messages for a keyword, look up a contact, or send /
-  reply to a message. This drives the user's OWN account over MTProto (not a
-  bot), so it can see everything the user can see.
+  Trigger for anything on the user's personal Telegram account: list recent
+  conversations or just the unread ones, read / summarize a chat or group,
+  search one chat or across all chats, look up a contact or a chat's info,
+  download a photo/file from a message, or take an action — send, reply,
+  forward, edit, delete, react, send a file, or mark a chat read. This drives
+  the user's OWN account over MTProto (not a bot), so it sees everything they see.
 connections: [telegram]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "1.1"
 ---
 
-We drive **personal** Telegram over the MTProto protocol with the
-[Telethon](https://docs.telethon.dev/) Python library — this acts as the user's own
-account (a "userbot"), so unlike the Bot API it can read full chat history, list every
-conversation, and message anyone the user can message.
+We drive **personal** Telegram over MTProto with [Telethon](https://docs.telethon.dev/) —
+this acts as the user's own account (a "userbot"), so unlike the Bot API it can read full
+history, list every conversation, and act on anyone the user can reach.
 
-The user's credentials are injected as environment variables by the connector:
+Credentials are injected as env vars by the connector:
 
-- `TELEGRAM_API_ID` — the app id (from my.telegram.org)
-- `TELEGRAM_API_HASH` — the app hash — **secret, never echo it**
-- `TELEGRAM_SESSION_STRING` — a Telethon `StringSession` = **full account access. Never log,
+- `TELEGRAM_API_ID` — app id
+- `TELEGRAM_API_HASH` — app hash — **secret, never echo**
+- `TELEGRAM_SESSION_STRING` — Telethon `StringSession` = **full account access. Never log,
   echo, or print it.** Treat it like the account password.
 
 ## Setup — write the helper once per session
 
-`telethon` is preinstalled in the sandbox image. The helper is written to `./tg.py` **in the
-current working directory** (the per-session workdir) — not a shared global path like `/tmp` —
-so concurrent sessions never race on or reuse each other's file.
+`telethon` is preinstalled in the sandbox. The helper is written to `./tg.py` **in the current
+working directory** (the per-session workdir) — not a shared global path — so concurrent
+sessions never race.
+
+Every state-changing command (`send`, `reply`, `send-file`, `forward`, `edit`, `delete`,
+`react`, `mark-read`) is **gated**: without a trailing `--confirm` it only DRY-RUNS (prints what
+it would do, changes nothing). Read commands run directly. `--confirm` is honored **only as the
+last argument** so a message/caption that merely contains "--confirm" can never silently confirm.
 
 ```sh
-# telethon is preinstalled; the `|| pip install` is a best-effort fallback only
-# (the sandbox is non-root, so a runtime install may not succeed — rely on the
-# preinstalled package).
 python3 -c "import telethon" 2>/dev/null || pip install --user --quiet telethon 2>/dev/null || true
 
 cat > ./tg.py <<'PY'
 import os, sys, json, asyncio
 from telethon import TelegramClient
 from telethon.sessions import StringSession
+from telethon.tl import functions
+from telethon.tl.types import ReactionEmoji
 
 API_ID = int(os.environ["TELEGRAM_API_ID"])
 API_HASH = os.environ["TELEGRAM_API_HASH"]
 SESSION = os.environ["TELEGRAM_SESSION_STRING"]
 
+_raw = sys.argv[1:]
+# --confirm is only honored as the LAST token, and only one is stripped, so a
+# message/caption that merely contains "--confirm" cannot silently confirm a write.
+CONFIRM = bool(_raw) and _raw[-1] == "--confirm"
+a = _raw[:-1] if CONFIRM else list(_raw)
+cmd = a[0] if a else "help"
+args = a[1:]
+GATED = {"send", "reply", "send-file", "forward", "edit", "delete", "react", "mark-read"}
+
+
+def out(o):
+    print(json.dumps(o, ensure_ascii=False, default=str))
+
 
 async def resolve(client, target):
-    # Accept a numeric id, @username, phone, or an exact chat display name.
+    # 1) try direct resolve; 2) fall back to scanning dialogs by id or exact name
+    #    (StringSession doesn't persist the entity cache, so a numeric id from a
+    #    previous invocation may need the dialog scan to recover its access hash).
+    for attempt in (lambda: client.get_entity(int(target)), lambda: client.get_entity(target)):
+        try:
+            return await attempt()
+        except Exception:
+            pass
+    ti = None
     try:
-        return await client.get_entity(int(target))
+        ti = int(target)
     except (ValueError, TypeError):
         pass
-    try:
-        return await client.get_entity(target)
-    except Exception:
-        async for d in client.iter_dialogs():
-            if d.name == target:
-                return d.entity
-        raise ValueError(f"could not resolve target: {target}")
+    async for d in client.iter_dialogs():
+        if (ti is not None and d.id == ti) or d.name == target:
+            return d.entity
+    raise ValueError(f"could not resolve target: {target}")
 
 
-async def main():
-    cmd = sys.argv[1]
-    async with TelegramClient(StringSession(SESSION), API_ID, API_HASH) as client:
+def msg_row(m):
+    return {"id": m.id, "date": str(m.date), "out": m.out, "sender_id": m.sender_id,
+            "text": m.message, "media": bool(m.media)}
+
+
+def need(n):
+    if len(args) < n:
+        raise ValueError(f"{cmd} needs {n} argument(s), got {len(args)}")
+
+
+async def run():
+    if cmd in GATED and not CONFIRM:
+        out({"dry_run": True, "command": cmd, "args": args,
+             "note": "re-run with --confirm as the LAST argument to actually perform this write"})
+        return
+    async with TelegramClient(StringSession(SESSION), API_ID, API_HASH) as cl:
         if cmd == "whoami":
-            me = await client.get_me()
-            print(json.dumps({"id": me.id, "username": me.username,
-                              "name": ((me.first_name or "") + " " + (me.last_name or "")).strip()},
-                             ensure_ascii=False))
+            me = await cl.get_me()
+            out({"id": me.id, "username": me.username,
+                 "name": ((me.first_name or "") + " " + (me.last_name or "")).strip(), "phone": me.phone})
+
         elif cmd == "list-chats":
-            limit = int(sys.argv[2]) if len(sys.argv) > 2 else 20
-            out = []
-            async for d in client.iter_dialogs(limit=limit):
-                out.append({"name": d.name, "id": d.id, "group": d.is_group,
+            limit = int(args[0]) if args and args[0].lstrip("-").isdigit() else 20
+            unread_only = "unread-only" in args
+            res = []
+            async for d in cl.iter_dialogs(limit=limit):
+                if unread_only and not d.unread_count:
+                    continue
+                res.append({"name": d.name, "id": d.id, "group": d.is_group,
                             "channel": d.is_channel, "user": d.is_user, "unread": d.unread_count})
-            print(json.dumps(out, ensure_ascii=False))
+            out(res)
+
+        elif cmd == "unread":
+            res = []
+            async for d in cl.iter_dialogs():
+                if d.unread_count:
+                    res.append({"name": d.name, "id": d.id, "unread": d.unread_count,
+                                "group": d.is_group, "channel": d.is_channel})
+            out(sorted(res, key=lambda x: -x["unread"]))
+
         elif cmd == "get-messages":
-            target = sys.argv[2]
-            n = int(sys.argv[3]) if len(sys.argv) > 3 else 50
-            ent = await resolve(client, target)
-            out = []
-            async for m in client.iter_messages(ent, limit=n):
-                out.append({"id": m.id, "date": str(m.date), "out": m.out,
-                            "sender_id": m.sender_id, "text": m.message})
-            out.reverse()
-            print(json.dumps(out, ensure_ascii=False))
+            need(1); ent = await resolve(cl, args[0])
+            n = int(args[1]) if len(args) > 1 else 50
+            rows = [msg_row(m) async for m in cl.iter_messages(ent, limit=n)]
+            rows.reverse()
+            out(rows)
+
         elif cmd == "search":
-            target, query = sys.argv[2], sys.argv[3]
-            n = int(sys.argv[4]) if len(sys.argv) > 4 else 30
-            ent = await resolve(client, target)
-            out = []
-            async for m in client.iter_messages(ent, search=query, limit=n):
-                out.append({"id": m.id, "date": str(m.date), "sender_id": m.sender_id, "text": m.message})
-            print(json.dumps(out, ensure_ascii=False))
+            need(2); ent = await resolve(cl, args[0])
+            q = args[1]; n = int(args[2]) if len(args) > 2 else 30
+            out([msg_row(m) async for m in cl.iter_messages(ent, search=q, limit=n)])
+
+        elif cmd == "search-global":
+            need(1); q = args[0]; n = int(args[1]) if len(args) > 1 else 30
+            rows = []
+            async for m in cl.iter_messages(None, search=q, limit=n):
+                r = msg_row(m); r["chat_id"] = m.chat_id
+                rows.append(r)
+            out(rows)
+
+        elif cmd == "contacts":
+            res = await cl(functions.contacts.GetContactsRequest(hash=0))
+            out([{"id": u.id, "username": u.username,
+                  "name": ((u.first_name or "") + " " + (u.last_name or "")).strip(), "phone": u.phone}
+                 for u in res.users])
+
+        elif cmd == "chat-info":
+            need(1); ent = await resolve(cl, args[0])
+            info = {"id": ent.id, "type": type(ent).__name__,
+                    "title": getattr(ent, "title", None),
+                    "name": ((getattr(ent, "first_name", "") or "") + " " + (getattr(ent, "last_name", "") or "")).strip() or None,
+                    "username": getattr(ent, "username", None)}
+            try:
+                info["participants"] = (await cl.get_participants(ent, limit=1)).total
+            except Exception:
+                pass
+            out(info)
+
+        elif cmd == "message-link":
+            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
+            try:
+                r = await cl(functions.channels.ExportMessageLinkRequest(channel=ent, id=mid))
+                out({"link": r.link})
+            except Exception as e:
+                out({"error": f"links only available for channels/supergroups: {e}"})
+
+        elif cmd == "download-media":
+            need(2); ent = await resolve(cl, args[0]); mid = int(args[1])
+            outdir = args[2] if len(args) > 2 else "./tg_downloads"
+            os.makedirs(outdir, exist_ok=True)
+            m = await cl.get_messages(ent, ids=mid)
+            if not m or not m.media:
+                out({"error": "no media on that message"}); return
+            path = await cl.download_media(m, file=outdir)
+            out({"downloaded": path})
+
+        # ---- gated writes (need trailing --confirm) ----
         elif cmd == "send":
-            # Gated: without --confirm this only DRY-RUNS (prints the intended
-            # target + text and sends nothing). Pass --confirm to actually send.
-            target, text = sys.argv[2], sys.argv[3]
-            confirm = "--confirm" in sys.argv[4:]
-            ent = await resolve(client, target)
-            if not confirm:
-                name = getattr(ent, "title", None) or getattr(ent, "first_name", None) or str(target)
-                print(json.dumps({"dry_run": True, "would_send_to": name, "text": text,
-                                  "note": "re-run with --confirm to actually send"}, ensure_ascii=False))
-                return
-            msg = await client.send_message(ent, text)
-            print(json.dumps({"sent": True, "id": msg.id}, ensure_ascii=False))
+            need(2); ent = await resolve(cl, args[0])
+            m = await cl.send_message(ent, args[1])
+            out({"sent": True, "id": m.id})
+
+        elif cmd == "reply":
+            need(3); ent = await resolve(cl, args[0])
+            m = await cl.send_message(ent, args[2], reply_to=int(args[1]))
+            out({"sent": True, "id": m.id, "reply_to": int(args[1])})
+
+        elif cmd == "send-file":
+            need(2); ent = await resolve(cl, args[0])
+            caption = args[2] if len(args) > 2 else None
+            m = await cl.send_file(ent, args[1], caption=caption)
+            out({"sent": True, "id": m.id})
+
+        elif cmd == "forward":
+            need(3); src = await resolve(cl, args[0]); mid = int(args[1]); dst = await resolve(cl, args[2])
+            fwd = await cl.forward_messages(dst, mid, src)
+            out({"forwarded": True, "id": getattr(fwd, "id", None) or [x.id for x in fwd]})
+
+        elif cmd == "edit":
+            need(3); ent = await resolve(cl, args[0])
+            m = await cl.edit_message(ent, int(args[1]), args[2])
+            out({"edited": True, "id": m.id})
+
+        elif cmd == "delete":
+            need(2); ent = await resolve(cl, args[0])
+            await cl.delete_messages(ent, int(args[1]))
+            out({"deleted": True, "id": int(args[1])})
+
+        elif cmd == "react":
+            need(3); ent = await resolve(cl, args[0]); mid = int(args[1]); emoji = args[2]
+            await cl(functions.messages.SendReactionRequest(
+                peer=ent, msg_id=mid, reaction=[ReactionEmoji(emoticon=emoji)]))
+            out({"reacted": True, "id": mid, "emoji": emoji})
+
+        elif cmd == "mark-read":
+            need(1); ent = await resolve(cl, args[0])
+            await cl.send_read_acknowledge(ent)
+            out({"marked_read": True})
+
         else:
-            print(json.dumps({"error": f"unknown command: {cmd}"}))
-            sys.exit(1)
+            out({"error": f"unknown command: {cmd}"}); sys.exit(1)
+
+
+async def main():
+    try:
+        await run()
+    except SystemExit:
+        raise
+    except Exception as e:
+        out({"error": f"{type(e).__name__}: {e}"})
+        sys.exit(1)
 
 
 asyncio.run(main())
@@ -120,76 +244,77 @@ PY
 echo "helper ready"
 ```
 
-## Verify the connection (run this first)
+## Verify the connection first
 
 ```sh
 python3 ./tg.py whoami
-# → {"id": 8367450178, "username": "GermeyAce", "name": "Germey"}
+# → {"id": 8367450178, "username": "GermeyAce", "name": "Germey", "phone": "..."}
 ```
 
-If this errors with an auth/session message, the stored session is dead (revoked or expired) —
-tell the user to reconnect the Telegram connector at https://auth.acedata.cloud/user/connections.
+On an auth/session error the stored session is dead — tell the user to reconnect at
+https://auth.acedata.cloud/user/connections.
 
-## Recipes
+## Read recipes
 
-### List recent conversations
+| Goal | Command |
+|---|---|
+| Recent conversations | `python3 ./tg.py list-chats 20` |
+| Only chats with unread (ranked) | `python3 ./tg.py unread` |
+| A chat's history (oldest→newest) | `python3 ./tg.py get-messages <target> 50` |
+| Search inside one chat | `python3 ./tg.py search <target> "kw" 30` |
+| Search across ALL chats | `python3 ./tg.py search-global "kw" 30` |
+| List contacts | `python3 ./tg.py contacts` |
+| Info about a chat/user | `python3 ./tg.py chat-info <target>` |
+| t.me link to a message | `python3 ./tg.py message-link <target> <msg_id>` |
 
-```sh
-python3 ./tg.py list-chats 20
-# → [{"name":"Ace <> ConduitOS","id":-5287630726,"group":true,...,"unread":0}, ...]
-```
+`<target>` = numeric id (most reliable — from `list-chats`), `@username`, phone, or exact chat
+name. In message rows, `out:true` = sent by the user; `media:true` = has an attachment.
 
-Use the returned `id` (or the exact `name`) as the target for the next calls.
+**Summarize-unread pattern**: `unread` → pick the chats that matter → `get-messages <id> N` on
+each → summarize. Don't dump 20k messages; sample the most-unread / most-relevant.
 
-### Read a conversation's history (oldest→newest)
+## Media
 
 ```sh
-# target = numeric id, @username, phone, or exact chat name; second arg = how many messages
-python3 ./tg.py get-messages -5287630726 50
-python3 ./tg.py get-messages @some_username 30
+# Download an attachment from a message → returns the saved path
+python3 ./tg.py download-media <target> <msg_id> ./tg_downloads
+# Send a local file or a URL (optional caption) — GATED
+python3 ./tg.py send-file <target> /path/or/https-url "caption" --confirm
 ```
 
-`out: true` means the message was sent BY the user; `sender_id` is the author. Summarize from
-the returned JSON.
+To hand a downloaded file back to the user as a link, upload it to the CDN (see the
+`cos-upload` skill) after `download-media`.
 
-### Search inside a conversation
+## Write recipes — all GATED (dry-run unless trailing `--confirm`)
 
-```sh
-python3 ./tg.py search -5287630726 "keyword" 30
-```
-
-(Server-side search is scoped to one chat. To search broadly, list chats first, then search the
-relevant ones.)
-
-### Send / reply to a message — TWO-STEP, confirm first
-
-Sending posts a **real message as the user**, so it is gated:
+Sending/editing/deleting acts as the **real user**. Always run the dry run first, show the user
+exactly what will happen, get an explicit "yes", then re-run with `--confirm` as the **last
+argument**. Never bulk-send.
 
 ```sh
-# Step 1 — DRY RUN (default, sends nothing). Show this preview to the user.
-python3 ./tg.py send -5287630726 "Hi, following up on this."
-# → {"dry_run": true, "would_send_to": "Ace <> ConduitOS", "text": "Hi, following up on this.", ...}
-
-# Step 2 — only after the user explicitly says yes in the conversation, add --confirm:
-python3 ./tg.py send -5287630726 "Hi, following up on this." --confirm
-# → {"sent": true, "id": 4502}
+python3 ./tg.py send    <target> "text"                          # → dry_run; add --confirm to send
+python3 ./tg.py reply   <target> <msg_id> "text" --confirm
+python3 ./tg.py forward <from_target> <msg_id> <to_target> --confirm
+python3 ./tg.py edit    <target> <msg_id> "new text" --confirm   # own messages
+python3 ./tg.py delete  <target> <msg_id> --confirm              # destructive
+python3 ./tg.py react   <target> <msg_id> "👍" --confirm
+python3 ./tg.py mark-read <target> --confirm                     # sends read receipts
 ```
 
-**Always run the dry run first, show the user exactly who + what, and require an explicit "yes"
-before re-running with `--confirm`** — even if the original instruction said "just send it".
-Never bulk-send.
-
-## Gotchas — surface these before the user is surprised
-
-- **This is the user's real account.** Sending posts as them; reading exposes all their private
-  chats. Be conservative.
-- **`FloodWaitError`**: Telegram rate-limits userbots. If a call fails with a flood-wait of N
-  seconds, tell the user to retry after N seconds — do not loop/retry aggressively (it escalates
-  toward an account ban).
-- **Dead session**: a `session_string` can be revoked by the user from Telegram → Settings →
-  Devices. On an `AuthKeyError` / unauthorized error, the fix is reconnecting the connector, not
-  retrying.
-- **Never print `TELEGRAM_SESSION_STRING` or `TELEGRAM_API_HASH`** — they are full-account
-  secrets. The helper never prints them; keep it that way.
-- **Resolving targets**: prefer the numeric `id` from `list-chats` (most reliable). Names work
-  only on an exact match; usernames need the leading `@`.
+The dry run returns `{"dry_run": true, "command": ..., "args": [...]}` — present that to the
+user verbatim as the confirmation prompt.
+
+## Gotchas — surface before the user is surprised
+
+- **This is the user's real account.** Confirm before any write; reading exposes private chats.
+- **`FloodWaitError`**: Telegram rate-limits userbots. On a flood-wait of N seconds, tell the
+  user to retry after N — never loop/retry aggressively (escalates toward a ban).
+- **Dead session**: revoked from Telegram → Settings → Devices, or ~6-month inactivity. On
+  `AuthKeyError`/unauthorized, reconnect the connector (don't retry).
+- **Never print `TELEGRAM_SESSION_STRING` / `TELEGRAM_API_HASH`** — full-account secrets.
+- **Targets**: prefer the numeric `id` from `list-chats` (the helper recovers its access hash by
+  scanning dialogs); names need an exact match, usernames need a leading `@`.
+- **`message-link`** only works for public channels/supergroups; private 1:1 / basic groups
+  return an error (no shareable link exists).
+- **`edit`/`delete`** generally only apply to the user's own messages (admins can delete others
+  in groups they manage).