@acedatacloud/skills 2026.726.6 → 2026.726.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.726.6",
+  "version": "2026.726.8",
   "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/bilibili/SKILL.md

@@ -42,6 +42,8 @@ python3 "$BILI" whoami                     # who is logged in (mid, name)
 python3 "$BILI" articles --limit 20        # my 专栏 articles + stats
 python3 "$BILI" article <cvid>             # one article's stats (cv id)
 python3 "$BILI" drafts --limit 50          # list saved drafts (aid + title)
+python3 "$BILI" status --limit 10          # review state of recent submissions
+python3 "$BILI" categories                 # 分类 names accepted by --category
 ```
 
 Stats come straight from Bilibili: `view` (阅读), `like` (点赞), `reply` (评论),
@@ -69,12 +71,41 @@ BILI="$SKILL_DIR/scripts/bilibili.py"; [ -f "$BILI" ] || BILI=$(find /tmp -maxde
 python3 "$BILI" publish --title "标题" --content-file a.html                       # dry-run
 python3 "$BILI" publish --title "标题" --content-file a.html --draft-only --confirm   # save a draft
 python3 "$BILI" publish --title "标题" --content-file a.html --confirm                # save draft + submit (publish)
+python3 "$BILI" publish --title "标题" --content-file a.html --category 数码 --confirm  # pick the 分类
 ```
 
 - `--draft-only` saves a draft (no submit) — safe; finish/publish in the editor.
+  Prefer it when the user has not clearly asked to go public: a submitted
+  article enters a review queue this CLI cannot withdraw it from.
 - The **submit** (go public) step is frequently rate-limited by Bilibili
   risk-control (HTTP 412). When that happens the CLI reports the saved draft +
-  edit URL so the user can publish from the web editor. Default to `--draft-only`.
+  edit URL so the user can publish from the web editor.
+- `--category` picks the 分类 (default **数码**, which suits technical posts).
+  Run `categories` for the accepted names. The result echoes the 分类 actually
+  used as `category` / `category_id` — report it when it wasn't the user's pick.
+
+### Publishing is not instant — it enters a review queue
+
+A successful `submit` returns `state: -2` (**待审核**) and `pending_review: true`.
+The returned `url` **404s for everyone until Bilibili approves it** (usually
+minutes to hours). Tell the user it is pending; do not claim it is live, and do
+not re-submit. Check later with `status`, which is the only view that shows
+pending/rejected articles (the public list omits them):
+
+```sh
+python3 "$BILI" status --limit 5    # state_desc: 待审核 / 已发布 / 未通过 (+ reason)
+```
+
+Other states are **not** pending and will never go live on their own — the CLI
+returns them with `ok: false` and `published: false` (`-1` 未通过 rejected, `-3`
+锁定, `-4` 已删除). Read `state_desc`, tell the user plainly, and check `status`
+for the `reason` rather than re-submitting.
+
+The `id` in the publish result is the **article id** (use `cv<id>`), which is a
+different number from `draft_aid`. Only ever share the `url` field. If Bilibili
+returned no article id, `url` and `id` are `null` and `id_unverified: true` is
+set — there is nothing shareable yet, so find the article with `status` instead
+of constructing a link from `draft_aid`.
 
 ## Managing drafts (the 999-draft cap)
 
@@ -108,8 +139,8 @@ skips this.
 - **This is the user's real Bilibili account.** Confirm before any publish.
 - **submit may 412** (anti-bot) even when the draft saved fine — the draft is the
   reliable result; don't loop-retry submit.
-- A wrong cover layout (`tid`) / category returns `-17`; the CLI auto-retries
-  common `tid` values.
+- A 分类 the account can't post to returns `-17`; without `--category` the CLI
+  auto-retries the fallback list.
 - **Never print `BILIBILI_COOKIES`** — it is full account access.
 - **ToS**: acts only on the user's own account with their own captured cookie.
 
@@ -123,6 +154,14 @@ After you successfully publish and obtain the live result URL, call the built-in
 publish_artifact(kind="article", channel="bilibili", title="<title>", url="<the REAL returned URL>", status="delivered")
 ```
 
-Use the real returned URL — never fabricate one. Call it once per published item,
-only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
+Use the real returned URL — never fabricate one. That is the `url` field of the
+publish result (built from the article `id`, **not** `draft_aid`). Call it once
+per published item, only after delivery is confirmed.
+
+- `state: 0` or `1` (已发布, live) → `status="delivered"`.
+- `pending_review: true` (待审核) → `status="draft"`; the URL is not live yet.
+  Re-record as delivered later if the user asks you to re-check with `status`.
+- rejected/locked states, a 412-blocked submit, `id_unverified: true`, or
+  `state_unknown: true` → `status="failed"` (or skip it).
+
 See `_shared/artifacts.md`.

package/skills/bilibili/scripts/bilibili.py

@@ -277,8 +277,30 @@ def cmd_article(jar, args):
     })
 
 
-# tid = cover layout; a wrong one returns code -17 / "分类". Try common ones.
-_TID_CANDIDATES = ["4", "3", "6", "7", "2", "17", "28", "41"]
+# The article's 分类 (from /x/article/categories). This is the `category` form
+# field — `tid` alone does NOT set it (a hardcoded category=0 always lands in
+# 生活 regardless of tid). Sub-category ids only; a parent id is rejected.
+_CATEGORIES = {
+    "数码": "26", "科技": "26", "tech": "26",
+    "学习": "34", "人文历史": "25", "自然": "33", "汽车": "27",
+    "日常": "15", "生活": "15", "美食": "13", "时尚": "14", "运动": "22", "萌宠": "21",
+    "绘画": "23", "手工": "24", "摄影": "38", "音乐舞蹈": "39", "模型手办": "11",
+    "动漫杂谈": "4", "动漫资讯": "5", "动画技术": "31",
+    "单机游戏": "6", "电子竞技": "7", "手机游戏": "8", "网络游戏": "9", "桌游棋牌": "10",
+    "电影": "12", "电视剧": "35", "纪录片": "36", "综艺": "37",
+    "原创连载": "18", "同人连载": "19", "短篇小说": "32", "小说杂谈": "20",
+}
+# Fallback order when --category is not given: 数码 first (most of our content
+# is technical), then broad ones. A category the account can't post to → -17.
+_TID_CANDIDATES = ["26", "34", "15", "4", "6", "12", "23"]
+
+# A creative article's `state` (what 投稿管理 shows). Only 0/1 are actually live.
+_STATES = {0: "已发布", 1: "已发布", -1: "未通过", -2: "待审核", -3: "锁定", -4: "已删除"}
+
+# id → canonical display name (first alias wins; 数码/科技/tech all map to 26).
+_CATEGORY_NAMES = {}
+for _name, _cid in _CATEGORIES.items():
+    _CATEGORY_NAMES.setdefault(_cid, _name)
 
 
 # ── image upload (Bilibili hotlink-blocks external imgs; re-host via
@@ -545,6 +567,19 @@ def md_to_html(src):
     return "\n".join(out)
 
 
+def _resolve_categories(raw):
+    """--category → the single 分类 id to use, or the fallback list if unset."""
+    if not raw:
+        return _TID_CANDIDATES, None
+    name = raw.strip()
+    cid = _CATEGORIES.get(name)
+    if not cid:
+        if not name.isdigit():
+            die(f"unknown --category {raw!r}; known: " + ", ".join(sorted(_CATEGORIES)))
+        cid = name
+    return [cid], cid  # explicit choice: don't silently fall back to another 分类
+
+
 def cmd_publish(jar, args):
     if not args.title:
         die("--title is required")
@@ -562,14 +597,22 @@ def cmd_publish(jar, args):
     if not csrf:
         die("no bili_jct cookie (CSRF token) — reconnect Bilibili.")
 
+    # Resolve before the dry-run so a typo'd 分类 is caught in the preview,
+    # and before rehost_images so a bad one can't burn uploads then abort.
+    cids, explicit = _resolve_categories(args.category)
+
     if not CONFIRM:
         out({
             "dry_run": True, "command": "publish", "platform": "bilibili",
             "title": args.title, "draft_only": args.draft_only,
+            "category": (_CATEGORY_NAMES.get(explicit, explicit) if explicit
+                         else "(auto: 数码)"),
             "content_bytes": len(content),
             "note": "Bilibili 专栏 content is HTML. Re-run with --confirm as the "
-                    "LAST argument to write. The submit step is often 412-limited; "
-                    "the saved draft is the reliable result.",
+                    "LAST argument to write. Published articles enter Bilibili's "
+                    "review queue (state -2) before going public; the submit step "
+                    "is also often 412-limited, in which case the saved draft is "
+                    "the reliable result.",
         })
         return
 
@@ -585,13 +628,15 @@ def cmd_publish(jar, args):
     ref = "https://member.bilibili.com/"
     base = {
         "title": args.title, "content": content, "csrf": csrf,
-        "category": "0", "list_id": "0", "reprint": "0", "original": "1",
+        "list_id": "0", "reprint": "0", "original": "1",
         "media_id": "0", "spoiler": "0", "save": "0", "pgc_id": "0",
     }
-    # 1. save draft, retrying tid until the category is accepted
-    aid, last = None, None
-    for tid in _TID_CANDIDATES:
-        body = dict(base, tid=tid)
+    # 1. save draft, retrying the 分类 until one is accepted
+    aid, chosen, last = None, None, None
+    for cid in cids:
+        # `category` is what actually sets 分类; `tid` must match or the article
+        # silently lands in 生活.
+        body = dict(base, tid=cid, category=cid)
         status, text = request("POST", f"{API}/x/article/creative/draft/addupdate",
                                jar, referer=ref, form=body)
         try:
@@ -601,21 +646,22 @@ def cmd_publish(jar, args):
             continue
         if r.get("code") == 0:
             aid = (r.get("data") or {}).get("aid")
-            chosen_tid = tid
+            chosen = cid
             break
         last = f"code={r.get('code')} {r.get('message')}"
         if "分类" not in str(r.get("message", "")) and r.get("code") != -17:
-            break  # a non-category error won't be fixed by another tid
+            break  # a non-category error won't be fixed by another one
     if not aid:
         die(f"save-draft failed: {last}")
 
     if args.draft_only:
         out({"ok": True, "draft_only": True, "aid": str(aid),
+             "category_id": chosen, "category": _CATEGORY_NAMES.get(chosen, chosen),
              "edit_url": f"https://member.bilibili.com/article-text/home?aid={aid}"})
         return
 
     # 2. submit (publish) — may be 412 risk-controlled; report draft if so
-    body = dict(base, tid=chosen_tid, aid=aid)
+    body = dict(base, tid=chosen, category=chosen, aid=aid)
     status, text = request("POST", f"{API}/x/article/creative/article/submit",
                            jar, referer=ref, form=body)
     try:
@@ -623,8 +669,64 @@ def cmd_publish(jar, args):
     except json.JSONDecodeError:
         r = None
     if r and r.get("code") == 0:
-        out({"ok": True, "published": True, "aid": str(aid),
-             "url": f"https://www.bilibili.com/read/cv{aid}"})
+        # The published article gets a NEW id — the draft aid is not a cv id, so
+        # cv<draft_aid> 404s. Only trust an id the submit response actually gave.
+        data = r.get("data") or {}
+        try:
+            cvid = int(data.get("aid"))
+        except (TypeError, ValueError):
+            cvid = None
+        if cvid is not None and cvid <= 0:
+            cvid = None  # article ids are positive; 0 means "not returned"
+        res = {"ok": True, "published": True,
+               "id": str(cvid) if cvid is not None else None,
+               "url": (f"https://www.bilibili.com/read/cv{cvid}"
+                       if cvid is not None else None),
+               "draft_aid": str(aid),
+               "category_id": chosen,
+               "category": _CATEGORY_NAMES.get(chosen, chosen)}
+        notes = []
+        if cvid is None:
+            # Never hand back a draft-aid URL dressed up as the published one.
+            res["id_unverified"] = True
+            notes.append("submit succeeded but returned no article id — there is "
+                         f"no shareable URL yet (draft aid {aid} is NOT a cv id). "
+                         "Find the article with `status`.")
+        raw_state = data.get("state")
+        if isinstance(raw_state, bool):
+            state = None
+        else:
+            try:
+                state = int(raw_state)
+            except (TypeError, ValueError):
+                state = None
+        if state is None and raw_state is not None:
+            res["state_unknown"] = True
+            notes.append(f"submit returned an unreadable state ({raw_state!r}); "
+                         "confirm with `status` before reporting this as live.")
+        if state is not None and state not in (0, 1):
+            res["state"] = state
+            res["state_desc"] = _STATES.get(state, str(state))
+            if state == -2:
+                # 待审核: the url 404s for everyone until Bilibili approves it.
+                res["pending_review"] = True
+                notes.append("submitted, now in Bilibili's review queue — the URL "
+                             "goes live once approved (usually minutes to hours). "
+                             "Re-check with `status`; do not re-submit.")
+            elif state < 0:
+                # -1 未通过 / -3 锁定 / -4 已删除 — NOT pending, will never go live.
+                res["ok"] = False
+                res["published"] = False
+                notes.append(f"submit returned state {state} "
+                             f"({_STATES.get(state, 'unknown')}) — the article is "
+                             "not live and is not queued. Check `status` for the "
+                             "reason; do not report this as published.")
+        elif state in (0, 1):
+            res["state"] = state
+            res["state_desc"] = _STATES[state]
+        if notes:
+            res["note"] = " ".join(notes)
+        out(res)
     else:
         out({"ok": False, "published": False, "draft_saved": True, "aid": str(aid),
              "edit_url": f"https://member.bilibili.com/article-text/home?aid={aid}",
@@ -637,6 +739,41 @@ def _drafts_of(d: dict) -> list:
     return al.get("drafts") or []
 
 
+def cmd_categories(jar, args):
+    by_id = {}
+    for name, cid in _CATEGORIES.items():
+        by_id.setdefault(cid, []).append(name)
+    cats = [{"id": cid, "names": names} for cid, names in by_id.items()]
+    out({"count": len(cats), "categories": cats,
+         "note": "pass any of the names (or the raw id) to `publish --category`; "
+                 "the default is 数码."})
+
+
+def cmd_status(jar, args):
+    # The creative list is the ONLY view that shows pending/rejected articles —
+    # the public space list omits anything not yet approved.
+    d = get_json(f"{API}/x/article/creative/article/list?pn=1&ps={args.limit}",
+                 jar, referer="https://member.bilibili.com/")
+    if d.get("code"):
+        die(f"status error (code={d.get('code')}): {d.get('message')} — cookie expired?")
+    al = (d.get("data") or {}).get("artlist") or d.get("artlist") or {}
+    rows = []
+    for a in (al.get("articles") or [])[: args.limit]:
+        st = a.get("state")
+        cvid = a.get("id")
+        rows.append({
+            "id": str(cvid) if cvid else None,
+            "title": a.get("title"),
+            "state": st,
+            "state_desc": _STATES.get(st, str(st)) if isinstance(st, int) else None,
+            "live": isinstance(st, int) and st >= 0,
+            "reason": a.get("reason") or None,
+            "category": (a.get("category") or {}).get("name"),
+            "url": f"https://www.bilibili.com/read/cv{cvid}" if cvid else None,
+        })
+    out({"count": len(rows), "articles": rows})
+
+
 def cmd_drafts(jar, args):
     # 专栏 drafts are capped at 999; this lists them so they can be pruned.
     d = get_json(f"{API}/x/article/creative/draft/list?pn={args.page}&ps={args.limit}",
@@ -686,6 +823,8 @@ COMMANDS = {
     "publish": cmd_publish,
     "drafts": cmd_drafts,
     "delete-draft": cmd_delete_draft,
+    "categories": cmd_categories,
+    "status": cmd_status,
 }
 
 
@@ -702,8 +841,13 @@ def main() -> None:
     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="save a draft; do NOT submit")
+    sp.add_argument("--category", help="分类 name (e.g. 数码, 学习, 日常) or a raw tid; "
+                                       "default tries 数码 first")
     sp.add_argument("--no-rehost-images", action="store_true",
                     help="keep external image URLs as-is (skip Bilibili CDN re-host)")
+    sp = sub.add_parser("categories", help="list the 分类 names accepted by --category")
+    sp = sub.add_parser("status", help="review state of the user's recent submissions")
+    sp.add_argument("--limit", type=int, default=10)
     sp = sub.add_parser("drafts", help="list 专栏 drafts (id+title); use to prune the 999-draft cap")
     sp.add_argument("--limit", type=int, default=50)
     sp.add_argument("--page", type=int, default=1)

package/skills/toutiao/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: toutiao
+description: Read and publish on 今日头条 / Toutiao (mp.toutiao.com) with the user's own login cookies (BYOC) — list their 头条号 articles with impression/read/comment stats, inspect one article, and publish a new 图文 article or draft. Use when the user mentions 今日头条, 头条号, Toutiao, "我的头条文章", reading their article stats (展现/阅读), or 发头条 / publishing to Toutiao.
+when_to_use: |
+  Trigger for anything on the user's 今日头条号 (mp.toutiao.com) account driven by
+  their own login cookie: show who they are, list their articles with impression /
+  read / 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: [toutiao]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+# toutiao — read & publish on 今日头条 via your own cookies
+
+Drives the user's **real** 头条号 through the same `mp.toutiao.com` creator APIs
+the web console 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:
+
+- `TOUTIAO_COOKIES` — a JSON array of cookies. **Secret — never echo or print
+  it.** The CLI reads it for you.
+
+> Writes echo the `csrftoken` cookie back as the `X-CSRFToken` header (the CLI
+> does this). Reads and writes are otherwise cookie-only — no request signing.
+
+## CLI
+
+The skill ships [`scripts/toutiao.py`](scripts/toutiao.py) — self-contained, stdlib only.
+
+```sh
+# $SKILL_DIR can point at another skill loaded this turn — anchor on our own
+# script, and re-run this at the top of every Bash block (fresh shell each time).
+TT="$SKILL_DIR/scripts/toutiao.py"; [ -f "$TT" ] || TT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/toutiao.py' 2>/dev/null | head -1)
+[ -f "$TT" ] || { echo "toutiao script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
+python3 "$TT" whoami                       # who is logged in (+ total article count)
+python3 "$TT" articles --limit 20          # my articles + stats
+python3 "$TT" articles --status draft      # only drafts
+python3 "$TT" article <pgc-id>             # one article's stats
+```
+
+Stats come straight from 头条: `impression_count` (展现), `read_count` (阅读),
+`comment_count` (评论), `digg_count` (点赞).
+
+`--status` accepts `all` (default) / `draft` / `published` / `reviewing` / `failed`.
+
+## Verify the connection first
+
+```sh
+TT="$SKILL_DIR/scripts/toutiao.py"; [ -f "$TT" ] || TT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/toutiao.py' 2>/dev/null | head -1)
+python3 "$TT" whoami
+# → {"user_id": ..., "name": "...", "articles_total": 273}
+```
+
+On an auth error the cookie is expired — tell the user to reconnect at
+<https://auth.acedata.cloud/user/connections>. Do **not** retry in a loop.
+
+## Publishing — GATED (dry-run unless trailing `--confirm`)
+
+`publish` writes to the user's real 头条号. Content is **Markdown** (converted to
+HTML for 头条's body field). Without a trailing `--confirm` it dry-runs.
+`--confirm` is honored **only as the last argument**. Always show the dry-run,
+get an explicit "yes", then re-run with `--confirm` last.
+
+```sh
+TT="$SKILL_DIR/scripts/toutiao.py"; [ -f "$TT" ] || TT=$(find /tmp -maxdepth 8 -path '*/skills/*/scripts/toutiao.py' 2>/dev/null | head -1)
+python3 "$TT" publish --title "标题" --content-file a.md                          # dry-run
+python3 "$TT" publish --title "标题" --content-file a.md --draft-only --confirm   # private draft
+python3 "$TT" publish --title "标题" --content-file a.md --confirm                # PUBLIC, enters 审核
+```
+
+- `--draft-only` saves a private draft (`save=1`) — safe, nothing public.
+- Without `--draft-only` the article is **submitted publicly** under the user's
+  name and enters 头条's 审核 queue. Default to `--draft-only` unless the user
+  clearly asked to go live.
+- **Titles must be 2–30 characters** — 头条 rejects anything outside that range
+  (the CLI fails early with a clear message).
+
+## Images
+
+头条 rejects the **entire article** (`7115 图片uri非法`) if any `<img>` points at
+a non-头条 URL — so external images cannot simply be left alone. `publish`
+uploads every image in the body to 头条's own CDN first and rewrites the tag with
+the CDN attributes 头条 requires.
+
+If an image fails to upload, `publish` **aborts and posts nothing**, listing the
+offending URLs — it will not silently publish the user's article with images
+missing. Pass `--drop-failed-images` to publish without them instead.
+`--no-rehost-images` skips the whole step (头条 will then reject the article
+unless the body already carries 头条-hosted images).
+
+## Gotchas — surface before the user is surprised
+
+- **This is the user's real 头条号.** Confirm before any publish.
+- **审核**: a published article is not instantly live — 头条 reviews it. The
+  returned URL goes live once it passes; a rejected article shows up under
+  `articles --status failed`.
+- **Daily publish cap**: 头条 caps 图文 posts per day. Hitting it fails the
+  publish with 头条's own message — relay it, don't retry in a loop.
+- **14-day edit window**: 头条 refuses edits to articles published more than 14
+  days ago, so this skill does not offer an edit command.
+- **Cookie expiry**: reconnect at auth.acedata.cloud/user/connections.
+- **Never print `TOUTIAO_COOKIES`** — it is full account access.
+- **ToS**: cookie automation acts only on the user's own account with their own
+  captured cookie; the user owns that risk.
+
+## Record the output
+
+After you successfully publish and obtain the live result URL, call the built-in
+`publish_artifact` tool ONCE so the user can track this deliverable in **My Outputs**:
+
+```
+publish_artifact(kind="article", channel="toutiao", title="<title>", url="<the REAL returned URL>", status="delivered")
+```
+
+Use the real returned URL — never fabricate one. Call it once per published item,
+only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
+See `_shared/artifacts.md`.

package/skills/toutiao/scripts/toutiao.py

@@ -0,0 +1,737 @@
+#!/usr/bin/env python3
+"""
+toutiao — read & publish on 今日头条 (mp.toutiao.com) 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 ``TOUTIAO_COOKIES``
+— a list of ``{name, value, domain, ...}`` dicts captured by the ACE extension.
+
+头条's creator APIs are cookie-only (no request signing); writes additionally
+need the ``csrftoken`` cookie echoed back as the ``X-CSRFToken`` header.
+
+Read commands run directly. ``publish`` is GATED: without a trailing
+``--confirm`` it only dry-runs. ``--confirm`` is honored ONLY as the last
+argument, so a title/content that merely contains "--confirm" can never silently
+go live. ``--draft-only`` stops after saving a private draft.
+
+Examples:
+  python3 toutiao.py whoami
+  python3 toutiao.py articles --limit 20
+  python3 toutiao.py articles --status draft
+  python3 toutiao.py article <pgc-id>
+  python3 toutiao.py publish --title T --content-file a.md --draft-only --confirm
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import html as _html
+import ipaddress
+import json
+import os
+import random
+import re
+import socket
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from html.parser import HTMLParser as _HTMLParser
+
+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"
+)
+PLATFORM = "toutiao"
+MP = "https://mp.toutiao.com"
+
+_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 (shared pattern across the cookie-BYOC skills) ────────
+
+def load_cookies() -> list:
+    env = f"{PLATFORM.upper()}_COOKIES"
+    raw = os.environ.get(env)
+    if not raw:
+        die(f"{env} is not set — connect 今日头条 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:
+    d = domain.lstrip(".").lower()
+    h = host.lower()
+    return not d or h == d or h.endswith("." + d)
+
+
+def cookie_header(jar: list, url: str) -> str:
+    host = urllib.parse.urlsplit(url).hostname or ""
+    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)
+
+
+def cookie_value(jar: list, name: str):
+    for c in jar:
+        if c.get("name") == name:
+            return c.get("value")
+    return None
+
+
+# ── HTTP ────────────────────────────────────────────────────────────
+
+def _headers(jar: list, referer: str) -> dict:
+    return {
+        "User-Agent": UA,
+        "Accept": "application/json, text/plain, */*",
+        "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+        "Referer": referer,
+        "Origin": MP,
+        "sec-ch-ua": '"Chromium";v="124", "Google Chrome";v="124", "Not-A.Brand";v="99"',
+        "sec-ch-ua-mobile": "?0",
+        "sec-ch-ua-platform": '"macOS"',
+        "Sec-Fetch-Dest": "empty",
+        "Sec-Fetch-Mode": "cors",
+        "Sec-Fetch-Site": "same-origin",
+    }
+
+
+def request(method: str, url: str, jar: list, *, referer, headers=None, body=None,
+            nonfatal=False):
+    hdrs = _headers(jar, referer)
+    if headers:
+        hdrs.update(headers)
+    data = body.encode("utf-8") if isinstance(body, str) else body
+    req = urllib.request.Request(url, data=data, headers=hdrs, method=method)
+    # Unredirected → urllib will NOT re-send these if the API 30x-redirects to a
+    # different host (e.g. a login page), so neither the jar nor the CSRF token
+    # (which is itself a cookie value) leaks off-site.
+    req.add_unredirected_header("Cookie", cookie_header(jar, url))
+    # Writes are rejected without the csrftoken cookie echoed as a header.
+    req.add_unredirected_header("X-CSRFToken", str(cookie_value(jar, "csrftoken") or ""))
+    try:
+        with urllib.request.urlopen(req, timeout=60) 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:
+        if nonfatal:
+            raise RuntimeError(f"network error reaching {url}: {e.reason}")
+        die(f"network error reaching {url}: {e.reason}")
+
+
+def api_envelope(method: str, path: str, jar: list, *, referer=None, body=None, headers=None,
+                 nonfatal=False):
+    """Call an mp.toutiao.com endpoint and return the raw {code, message, ...}
+    envelope, dying on a non-zero code. 头条 answers HTTP 200 even for logical
+    failures, so the envelope code is the real status."""
+    url = f"{MP}{path}"
+    ref = referer or f"{MP}/profile_v4/graphic/articles"
+    status, text = request(method, url, jar, referer=ref, body=body, headers=headers,
+                           nonfatal=nonfatal)
+    if status in (401, 403) or "/auth/page/login" in text:
+        msg = (f"auth failed ({status}) on {path} — cookie likely expired. "
+               f"Reconnect 今日头条 at https://auth.acedata.cloud/user/connections.")
+        if nonfatal:
+            raise RuntimeError(msg)
+        die(msg)
+    try:
+        env = json.loads(text)
+    except json.JSONDecodeError:
+        if nonfatal:
+            raise RuntimeError(f"non-JSON response ({status}) from {path}: {text[:200]}")
+        die(f"non-JSON response ({status}) from {path}: {text[:300]}")
+    if not isinstance(env, dict):
+        if nonfatal:
+            raise RuntimeError(f"unexpected response from {path}: {text[:200]}")
+        die(f"unexpected response from {path}: {text[:300]}")
+    # `.get("code", …)` would return a stored None instead of falling back to
+    # err_no, so test explicitly.
+    code = env.get("code")
+    if code is None:
+        code = env.get("err_no")
+    if code not in (0, None):
+        msg = env.get("message") or env.get("reason") or ""
+        if code in (401, 403) or "登录" in str(msg):
+            auth_msg = (f"auth failed (code={code}: {msg}) — cookie likely expired. "
+                        f"Reconnect at https://auth.acedata.cloud/user/connections.")
+            if nonfatal:
+                raise RuntimeError(auth_msg)
+            die(auth_msg)
+        if nonfatal:
+            raise RuntimeError(f"头条 API error on {path} (code={code}): {msg}")
+        die(f"头条 API error on {path} (code={code}): {msg}")
+    return env
+
+
+def api(method: str, path: str, jar: list, **kw):
+    """Same as api_envelope but unwraps the `data` payload."""
+    return api_envelope(method, path, jar, **kw).get("data")
+
+
+# ── commands ────────────────────────────────────────────────────────
+
+def media_info(jar):
+    d = api("GET", "/mp/agw/media/get_media_info/", jar, referer=f"{MP}/profile_v4/index")
+    if not isinstance(d, dict):
+        die("could not read 头条号 profile (cookie expired?)")
+    return d
+
+
+def cmd_whoami(jar, _args):
+    d = media_info(jar)
+    media = d.get("media") or {}
+    user = d.get("user") or {}
+    _, total = _list_page(jar, "all", 1, 1)
+    out({
+        "user_id": user.get("id"),
+        "media_id": media.get("id"),
+        "name": user.get("screen_name") or media.get("display_name"),
+        "url": f"https://www.toutiao.com/c/user/token/{media.get('id')}/"
+               if media.get("id") else None,
+        "articles_total": total,
+        "media_level": media.get("article_media_level"),
+    })
+
+
+# status → 头条's own filter value. `all` also returns drafts (is_draft=1).
+_STATUS = {"all": "all", "draft": "draft", "published": "published",
+           "reviewing": "verifying", "failed": "unpass"}
+
+
+def _list_page(jar, status, page, size, nonfatal=False):
+    q = urllib.parse.urlencode({
+        "status": _STATUS.get(status, "all"), "from_time": 0, "start_time": 0,
+        "end_time": 0, "search_word": "", "page": page, "size": size,
+    })
+    d = api("GET", f"/mp/agw/article/list/?{q}", jar, nonfatal=nonfatal) or {}
+    return d.get("content") or [], d.get("total")
+
+
+def _fmt(a: dict) -> dict:
+    pgc = a.get("pgc_id") or a.get("item_id") or a.get("id")
+    return {
+        "pgc_id": str(pgc) if pgc is not None else None,
+        "title": a.get("title"),
+        "url": a.get("article_url"),
+        "is_draft": bool(a.get("is_draft")),
+        "status_desc": a.get("status_desc"),
+        "impression_count": a.get("impression_count"),
+        # go_detail_count_v2 is the read count; show_go_detail_count is a
+        # display-toggle BOOLEAN, never a fallback for it.
+        "read_count": a.get("go_detail_count_v2"),
+        "comment_count": a.get("comment_count"),
+        "digg_count": a.get("digg_count"),
+        "create_time": a.get("create_time"),
+    }
+
+
+def _iter_articles(jar, status, hard_cap=2000):
+    page, seen = 1, 0
+    while seen < hard_cap:
+        items, total = _list_page(jar, status, page, 50)
+        if not items:
+            return
+        for it in items:
+            yield it
+            seen += 1
+        if total is not None and seen >= total:
+            return
+        page += 1
+
+
+def cmd_articles(jar, args):
+    items = []
+    for it in _iter_articles(jar, args.status):
+        items.append(it)
+        if len(items) >= args.limit:
+            break
+    _, total = _list_page(jar, args.status, 1, 1)
+    out({"total": total, "count": len(items), "status": args.status,
+         "articles": [_fmt(a) for a in items]})
+
+
+def cmd_article(jar, args):
+    # 头条 has no per-article detail endpoint for the creator (article/edit only
+    # works within 14 days of publishing), but the list already carries every
+    # stat, so resolve by scanning it.
+    for it in _iter_articles(jar, "all"):
+        if str(it.get("pgc_id")) == str(args.id) or str(it.get("item_id")) == str(args.id):
+            res = _fmt(it)
+            res["abstract"] = (it.get("abstract") or "")[:200]
+            res["word_count"] = it.get("content_word_cnt")
+            out(res)
+            return
+    die(f"article {args.id} not found among your 头条 articles")
+
+
+# ── image re-host (头条 rejects the whole article if an <img> is external) ──
+
+MAX_IMG_BYTES = 12 * 1024 * 1024
+_IMG_SKIP = ("toutiao.com", "byteimg.com", "pstatp.com", "toutiaoimg.com")
+
+
+class _ImgFinder(_HTMLParser):
+    """Locate <img> tags with the stdlib parser instead of a regex.
+
+    Four regex attempts each traded one unparseable shape for another; the
+    ambiguity is inherent (`title="unclosed>` is indistinguishable from an
+    attribute containing `>`). HTMLParser resolves tag boundaries by the same
+    rules the browser and 头条 use, so what we rewrite is what they render.
+    """
+
+    def __init__(self):
+        # convert_charrefs=False → attribute values stay as authored, matching
+        # what we re-emit into the HTML body.
+        super().__init__(convert_charrefs=False)
+        self.spans = []  # (start_offset, end_offset, attrs)
+
+    def _record(self, tag, attrs):
+        if tag.lower() != "img":
+            return
+        text = self.get_starttag_text() or ""
+        line, col = self.getpos()
+        start = self._line_starts[line - 1] + col
+        self.spans.append((start, start + len(text), attrs))
+
+    handle_starttag = _record
+    handle_startendtag = _record
+
+    def find(self, html):
+        # getpos() is (line, col); precompute line offsets to map to an index.
+        self._line_starts, pos = [0], 0
+        for ln in html.splitlines(keepends=True):
+            pos += len(ln)
+            self._line_starts.append(pos)
+        self.feed(html)
+        self.close()
+        return self.spans
+
+
+def _first_attr(attrs, name):
+    """First occurrence wins, as browsers do with a duplicated attribute."""
+    for k, v in attrs:
+        if k.lower() == name:
+            return v or ""
+    return None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # Refuse redirects on image fetches — a 30x could otherwise reach an internal
+    # host that _assert_public_url() never saw (SSRF).
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        raise RuntimeError(f"image redirect blocked ({code}) -> {newurl[:80]}")
+
+
+_IMG_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+def _assert_public_url(url):
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise RuntimeError(f"unsupported image URL: {url[:80]}")
+    try:
+        addrs = socket.getaddrinfo(parts.hostname, None)
+    except OSError as e:
+        raise RuntimeError(f"cannot resolve {parts.hostname}: {e}")
+    for info in addrs:
+        ip = ipaddress.ip_address(info[4][0])
+        if (ip.is_private or ip.is_loopback or ip.is_link_local
+                or ip.is_reserved or ip.is_multicast or ip.is_unspecified):
+            raise RuntimeError(f"blocked non-public image host: {parts.hostname}")
+
+
+def _download_image(url):
+    _assert_public_url(url)
+    req = urllib.request.Request(url, headers={"User-Agent": UA})
+    with _IMG_OPENER.open(req, timeout=30) as r:
+        data = r.read(MAX_IMG_BYTES + 1)
+    if len(data) > MAX_IMG_BYTES:
+        raise RuntimeError(f"image exceeds {MAX_IMG_BYTES} bytes")
+    return data
+
+
+def _same_or_sub(host, suffix):
+    return host == suffix or host.endswith("." + suffix)
+
+
+def _ext_of(url, default="png"):
+    tail = url.rsplit("/", 1)[-1].split("?")[0]
+    if "." in tail:
+        e = tail.rsplit(".", 1)[-1].lower()
+        if e in ("jpg", "jpeg", "png", "gif", "webp"):
+            return e
+    return default
+
+
+def _multipart(field, filename, blob, ctype):
+    boundary = "----acedata" + "".join(random.choice("0123456789abcdef") for _ in range(20))
+    body = b"".join([
+        (f'--{boundary}\r\nContent-Disposition: form-data; name="{field}";'
+         f' filename="{filename}"\r\nContent-Type: {ctype}\r\n\r\n').encode(),
+        blob,
+        f"\r\n--{boundary}--\r\n".encode(),
+    ])
+    return body, boundary
+
+
+def upload_image(jar, src) -> dict:
+    """Upload one image to 头条's CDN, returning its {url, web_uri, width, ...}."""
+    img = _download_image(src)
+    ext = _ext_of(src)
+    mime = "image/jpeg" if ext in ("jpg", "jpeg") else f"image/{ext}"
+    # The upload form field MUST be `upfile` — `file`/`image` return 1053.
+    body, boundary = _multipart("upfile", f"image.{ext}", img, mime)
+    # This endpoint answers with a FLAT envelope (no `data` wrapper), unlike the
+    # rest of the creator API, so read the fields off the top level.
+    # nonfatal → a per-image failure raises instead of die()ing, so the caller's
+    # failure collector (and --drop-failed-images) actually gets to run.
+    env = api_envelope("POST", "/mp/agw/article_material/photo/upload_picture/?type=json", jar,
+                       referer=f"{MP}/profile_v4/graphic/publish", body=body,
+                       headers={"Content-Type": f"multipart/form-data; boundary={boundary}"},
+                       nonfatal=True)
+    if not env.get("web_url") or not env.get("web_uri"):
+        raise RuntimeError(f"upload returned no image URL: {str(env)[:200]}")
+    return env
+
+
+def _img_tag(info: dict, alt: str) -> str:
+    """头条 needs the CDN attributes it returned, not a bare src — a plain
+    <img src> (or any external URL) makes publish fail with 7115 图片uri非法."""
+    return (
+        f'<img src="{_attr_url(info["web_url"])}"'
+        f' img_width="{int(info.get("width") or 0)}"'
+        f' img_height="{int(info.get("height") or 0)}"'
+        f' image_type="{int(info.get("image_type") or 1)}"'
+        f' mime_type="{_alt(str(info.get("mime_type") or "image/jpeg"))}"'
+        f' web_uri="{_alt(str(info["web_uri"]))}"'
+        f' alt="{_alt(alt)}">'
+    )
+
+
+def rehost_images(jar, html, drop_failed=False):
+    """Rewrite every <img> in the rendered body to a 头条-hosted one.
+
+    An external <img> is not merely blocked — it makes 头条 reject the WHOLE
+    article (7115), so keeping the original is never an option. Default is to
+    abort the publish so the user's article is never silently posted without
+    its images; ``drop_failed`` opts into dropping them instead.
+    """
+    failures = []
+    try:
+        spans = _ImgFinder().find(html)
+    except Exception as e:  # noqa: BLE001 — malformed beyond parsing
+        die(f"could not parse the article HTML to find its images: {e}")
+
+    out, cursor = [], 0
+    for start, end, attrs in spans:
+        out.append(html[cursor:start])
+        cursor = end
+        tag = html[start:end]
+        src = _first_attr(attrs, "src")
+        if not src:
+            # `data-src`-only or valueless src — we cannot fetch it, and 头条
+            # would reject the article, so surface it instead of dropping it.
+            failures.append(f"{tag[:80]} (no usable src attribute)")
+            continue
+        # Attribute values arrive unescaped; re-escape alt on the way back out.
+        alt = _first_attr(attrs, "alt") or ""
+        host = (urllib.parse.urlsplit(src).hostname or "").lower()
+        if any(_same_or_sub(host, s) for s in _IMG_SKIP) and _first_attr(attrs, "web_uri"):
+            out.append(tag)
+            continue
+        try:
+            info = upload_image(jar, src)
+            sys.stderr.write(f"[img] rehosted {src[:60]} -> {info['web_uri']}\n")
+            out.append(_img_tag(info, _html.escape(alt, quote=False)))
+        except Exception as e:  # noqa: BLE001 — collected, then reported below
+            failures.append(f"{src[:80]} ({e})")
+    out.append(html[cursor:])
+    result = "".join(out)
+    if failures and not drop_failed:
+        die("could not upload these images to 头条, and 头条 rejects any article "
+            "with an external image, so nothing was published:\n  - "
+            + "\n  - ".join(failures)
+            + "\nFix the image URLs, or re-run with --drop-failed-images to "
+              "publish without them.")
+    for f in failures:
+        sys.stderr.write(f"[img] DROPPED {f}\n")
+    return result
+
+
+# ── Markdown → HTML (头条's `content` field is rendered HTML, not source) ──
+
+_IMG_RE = re.compile(r"!\[([^\]]{0,500})\]\(([^)\s]{0,2000})\)")
+_LINK_RE = re.compile(r"(?<!!)\[([^\]]{0,500})\]\(([^)\s]{0,2000})\)")
+
+
+def _attr_url(u):
+    # Strip C0 controls/space FIRST, then allow only http/https/mailto — otherwise
+    # `\x01javascript:` would slip past a literal scheme check yet be re-normalised
+    # to javascript: by the browser. Finally neutralise attribute-breaking quotes.
+    u = re.sub(r"[\x00-\x20\x7f]", "", u or "")
+    m = re.match(r"(?i)([a-z][a-z0-9+.\-]*):", u)
+    if m and m.group(1).lower() not in ("http", "https", "mailto"):
+        return "#"
+    return u.replace('"', "%22").replace("'", "%27")
+
+
+def _alt(s):
+    return (s or "").replace('"', "&quot;").replace("'", "&#x27;")
+
+
+def _inline_md(t):
+    t = _html.escape(t, quote=False).replace("\x00", "")
+    # Stash code spans FIRST so emphasis/link/image markup inside `…` stays literal.
+    spans = []
+
+    def _stash(m):
+        spans.append("<code>" + m.group(1) + "</code>")
+        return f"\x00{len(spans) - 1}\x00"
+
+    t = re.sub(r"`([^`]+)`", _stash, t)
+    t = _IMG_RE.sub(lambda m: f'<img src="{_attr_url(m.group(2))}" alt="{_alt(m.group(1))}">', t)
+    t = _LINK_RE.sub(lambda m: f'<a href="{_attr_url(m.group(2))}">{m.group(1)}</a>', t)
+    t = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", t)
+    t = re.sub(r"(?<!\*)\*([^*\n]+)\*(?!\*)", r"<em>\1</em>", t)
+    t = re.sub(r"\x00(\d+)\x00", lambda m: spans[int(m.group(1))], t)
+    return t
+
+
+def _md_block_to_html(b):
+    b = b.strip("\n")
+    if not b.strip():
+        return None
+    f = b.lstrip()
+    m = re.match(r"(#{1,6})\s+(.*)", f)
+    if m:
+        lvl = len(m.group(1))
+        return f"<h{lvl}>{_inline_md(m.group(2).strip())}</h{lvl}>"
+    if f.startswith(">"):
+        inner = re.sub(r"^>\s?", "", b, flags=re.M).replace("\n", " ")
+        return "<blockquote><p>" + _inline_md(inner) + "</p></blockquote>"
+    if re.match(r"[-*+]\s+", f):
+        items = [_inline_md(re.sub(r"^[-*+]\s+", "", ln)) for ln in b.split("\n") if ln.strip()]
+        return "<ul>" + "".join(f"<li>{x}</li>" for x in items) + "</ul>"
+    if re.match(r"\d+\.\s+", f):
+        items = [_inline_md(re.sub(r"^\d+\.\s+", "", ln)) for ln in b.split("\n") if ln.strip()]
+        return "<ol>" + "".join(f"<li>{x}</li>" for x in items) + "</ol>"
+    only = re.fullmatch(r"!\[([^\]]{0,500})\]\(([^)\s]{0,2000})\)", f)
+    if only:
+        return f'<img src="{_attr_url(only.group(2))}" alt="{_alt(_html.escape(only.group(1), quote=False))}">'
+    return "<p>" + _inline_md(b.replace("\n", " ").strip()) + "</p>"
+
+
+def md_to_html(src):
+    """Minimal stdlib Markdown→HTML — 头条's body field is HTML, so raw markdown
+    would publish as literal `##` / `![]()` on one collapsed line."""
+    src = (src or "").strip()
+    res = []
+    # Pull fenced code out FIRST (it may itself contain blank lines) so the
+    # blank-line block splitter below can never tear a ``` … ``` fence apart.
+    for i, part in enumerate(re.split(r"(?ms)^(```.*?(?:\n```[ \t]*$|\Z))", src)):
+        if i % 2 == 1:
+            code = re.sub(r"\A```[^\n]*\n?", "", part)
+            code = re.sub(r"\n?```[ \t]*\Z", "", code)
+            res.append("<pre><code>" + _html.escape(code) + "</code></pre>")
+            continue
+        for b in re.split(r"\n[ \t]*\n", part):
+            block = _md_block_to_html(b)
+            if block:
+                res.append(block)
+    return "\n".join(res)
+
+
+def _looks_like_markdown(s):
+    # Three-way classification (no full parser): block-level HTML ⇒ already an
+    # HTML document → pass through; else markdown markers ⇒ render; else
+    # inline-only HTML ⇒ pass through; else plain text ⇒ render.
+    s = s or ""
+    if re.search(
+        r"</?(?:p|div|h[1-6]|ul|ol|li|table|thead|tbody|tr|td|th|blockquote|"
+        r"pre|figure|figcaption|section|article|header|footer|nav|aside|hr|"
+        r"main|details|summary)\b", s, re.I,
+    ):
+        return False
+    # ^-anchored (re.M) + bounded {0,N} repeats so the scan can't backtrack
+    # across newlines or to EOF (no quadratic scanning).
+    if re.search(
+        r"^#{1,6}\s|!\[[^\]]{0,500}\]\([^)]{0,2000}\)|^[ \t]*[-*+]\s|^[ \t]*\d+\.\s"
+        r"|\[[^\]]{0,500}\]\([^)]{0,2000}\)|`[^`]{1,500}`|\*\*[^*]{1,500}\*\*",
+        s, re.M,
+    ):
+        return True
+    inline_html = re.search(
+        r"</?(?:a|strong|em|b|i|u|s|span|code|br|img|small|mark|sup|sub|"
+        r"video|audio|iframe)\b", s, re.I,
+    )
+    return not inline_html
+
+
+# ── publish ─────────────────────────────────────────────────────────
+
+PUBLISH_PATH = "/mp/agw/article/publish/?source=mp&type=article"
+
+
+def _resolve_url(jar, pgc_id, draft):
+    """Look the freshly-written article up in the list to return its real URL
+    (preview URL for a draft, public /item/ URL once published).
+
+    Runs AFTER the write succeeded, so it must never fail the command — losing
+    the pgc_id would read as a failed publish and invite a duplicate post.
+    """
+    try:
+        items, _ = _list_page(jar, "draft" if draft else "all", 1, 20, nonfatal=True)
+        for it in items:
+            if str(it.get("pgc_id")) == str(pgc_id):
+                return it.get("article_url")
+    except (Exception, SystemExit):  # noqa: BLE001 — URL is a nicety
+        pass
+    if draft:
+        return f"{MP}/preview_article/?pgc_id={pgc_id}"
+    return f"https://www.toutiao.com/item/{pgc_id}/"
+
+
+def cmd_publish(jar, args):
+    if not args.title:
+        die("--title is required")
+    # 头条 rejects out-of-range titles server-side; fail early with a clear message.
+    if not 2 <= len(args.title) <= 30:
+        die(f"头条 titles must be 2–30 characters; got {len(args.title)}")
+    if not args.content_file and args.content is None:
+        die("provide --content-file <path.md> or --content <markdown>")
+    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}")
+    content = content or ""
+
+    if not CONFIRM:
+        out({
+            "dry_run": True, "command": "publish", "platform": "toutiao",
+            "title": args.title, "draft_only": args.draft_only,
+            "content_bytes": len(content),
+            "note": "头条 content is Markdown (converted to HTML for the body). "
+                    "Re-run with --confirm as the LAST argument to actually write. "
+                    "Without --draft-only it publishes a PUBLIC article on the "
+                    "user's real 头条号 and goes through 审核.",
+        })
+        return
+
+    # Writes need the csrftoken cookie echoed as a header; without it 头条 fails
+    # deep in its API with an opaque code instead of "reconnect".
+    if not cookie_value(jar, "csrftoken"):
+        die("the 今日头条 cookie jar has no `csrftoken` — it is incomplete or "
+            "expired. Reconnect at https://auth.acedata.cloud/user/connections.")
+
+    # Render to HTML FIRST, then rewrite <img> tags — 头条 rejects the whole
+    # article (7115) if any image isn't hosted on its own CDN with web_uri.
+    body_html = md_to_html(content) if _looks_like_markdown(content) else content
+    if not args.no_rehost_images:
+        body_html = rehost_images(jar, body_html, drop_failed=args.drop_failed_images)
+
+    form = urllib.parse.urlencode({
+        "title": args.title,
+        "content": body_html,
+        # save=1 → draft; save=0 → submit for 审核 and publish.
+        "save": "1" if args.draft_only else "0",
+        # 0 = no ad. Other values need 广告/自营 permissions most accounts lack.
+        "article_ad_type": "0",
+    })
+    d = api("POST", PUBLISH_PATH, jar, referer=f"{MP}/profile_v4/graphic/publish",
+            body=form, headers={"Content-Type": "application/x-www-form-urlencoded"})
+    pgc_id = (d or {}).get("pgc_id")
+    if not pgc_id:
+        die(f"publish returned no pgc_id: {str(d)[:300]}")
+    out({
+        "ok": True,
+        "draft_only": bool(args.draft_only),
+        "published": not args.draft_only,
+        "pgc_id": str(pgc_id),
+        "url": _resolve_url(jar, pgc_id, args.draft_only),
+        "note": None if args.draft_only else "头条 reviews new articles (审核); "
+                                             "the public URL goes live once it passes.",
+    })
+
+
+COMMANDS = {
+    "whoami": cmd_whoami,
+    "articles": cmd_articles,
+    "article": cmd_article,
+    "publish": cmd_publish,
+}
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="toutiao.py", description="今日头条 cookie CLI")
+    sub = p.add_subparsers(dest="command", required=True)
+    sub.add_parser("whoami", help="show the logged-in 头条号")
+    sp = sub.add_parser("articles", help="list the user's articles + stats")
+    sp.add_argument("--limit", type=int, default=20)
+    sp.add_argument("--status", default="all",
+                    choices=["all", "draft", "published", "reviewing", "failed"])
+    sp = sub.add_parser("article", help="one article's stats")
+    sp.add_argument("id", help="pgc_id / item_id")
+    sp = sub.add_parser("publish", help="create/publish an article (GATED by trailing --confirm)")
+    sp.add_argument("--title", help="2–30 characters")
+    sp.add_argument("--content", help="Markdown content inline")
+    sp.add_argument("--content-file", help="path to a Markdown file")
+    sp.add_argument("--draft-only", action="store_true",
+                    help="save a private draft; do NOT go public")
+    sp.add_argument("--no-rehost-images", action="store_true",
+                    help="keep external image URLs as-is (头条 will reject the article)")
+    sp.add_argument("--drop-failed-images", action="store_true",
+                    help="publish without any image that fails to upload, "
+                         "instead of aborting")
+    args = p.parse_args(ARGV)
+    jar = load_cookies()
+    COMMANDS[args.command](jar, args)
+
+
+if __name__ == "__main__":
+    main()