@acedatacloud/skills 2026.728.1 → 2026.728.2

package/package.json

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

@@ -1,104 +1,125 @@
 ---
 name: yuque
-description: Read and write Yuque (语雀) documents with the user's own personal access token through the official open API at https://www.yuque.com/api/v2. Use when the user wants to publish Markdown to 语雀, list their knowledge bases (知识库), read or update a 语雀 document, or delete one.
+description: Read and write Yuque (语雀) documents on the user's own account — list knowledge bases (知识库), read a document, publish Markdown, and update or delete one. Works with either the user's browser login (free) or a personal access token. Use when the user wants to publish Markdown to 语雀, list their 语雀 knowledge bases, or read a 语雀 document.
 when_to_use: |
   Trigger for 语雀 / Yuque document management: verify the connected account,
   list knowledge bases or the documents inside one, read a document, create a
-  Markdown document, update an existing one, or delete one. Writes and
-  destructive actions require explicit confirmation.
+  Markdown document, and (token connections only) update or delete one.
+  Writes and destructive actions require explicit confirmation.
 connections: [yuque]
 allowed_tools: [Bash]
 license: Apache-2.0
 metadata:
   author: acedatacloud
-  version: "1.0"
+  version: "2.0"
 ---
 
-Use the bundled standard-library CLI. The connector injects the user's 语雀
-personal access token as `$YUQUE_TOKEN`. Never print it. The CLI uses the
-official open API at `https://www.yuque.com/api/v2` with the documented
-`X-Auth-Token` header.
+# 语雀 — two connection modes
 
-```bash
-python3 "$SKILL_DIR/scripts/yuque.py" whoami
-```
+The connector injects exactly one credential, and the CLI picks its mode from it:
 
-If `$SKILL_DIR` points at a different skill loaded in the same turn, resolve
-this skill's directory explicitly before running the commands below.
+- **`$YUQUE_COOKIES`** — the user's own browser login jar, captured by the ACE
+  extension. **Free.** Drives 语雀's internal web API.
+- **`$YUQUE_TOKEN`** — a 语雀 personal access token for the official open API.
+  **Requires a paid 语雀超级会员.**
 
-If authentication fails, ask the user to create a token at
-`https://www.yuque.com/settings/tokens` and reconnect at
-`https://auth.acedata.cloud/user/connections`. Do not ask for their account
-password or Cookie.
+Both are **secret — never echo, print, log or return them.** Every command
+reports the active mode back as `auth_mode`; read that instead of guessing.
 
-## Read
+| Command | cookie | token |
+|---|---|---|
+| `whoami`, `repos`, `docs`, `doc` | ✅ | ✅ |
+| `create` | ✅ | ✅ |
+| `update`, `delete` | ❌ refused with a clear error | ✅ |
+
+If the user asks to edit or delete on a cookie connection, tell them that needs
+a personal token (created at `https://www.yuque.com/settings/tokens`, 超级会员
+required) and offer to create a new document instead. Do not attempt a
+workaround.
 
-A `repo` is a 语雀 knowledge base, addressed either by its `namespace`
-(`user/book`, as shown in the document URL) or by its numeric id. Always run
-`repos` first — never guess a namespace.
+## Script resolution
 
-```bash
-# Verify the token and see the account.
-python3 "$SKILL_DIR/scripts/yuque.py" whoami
+Bash calls do not share shell variables. Resolve the helper inside **every**
+fenced Bash invocation before using it:
 
-# List knowledge bases, then the documents in one.
-python3 "$SKILL_DIR/scripts/yuque.py" repos
-python3 "$SKILL_DIR/scripts/yuque.py" docs REPO_NAMESPACE --limit 20
-python3 "$SKILL_DIR/scripts/yuque.py" doc REPO_NAMESPACE DOC_ID
+```sh
+Y="${SKILL_DIR:-}/scripts/yuque.py"; [ -f "$Y" ] || Y=$(find /tmp -maxdepth 8 -path '*/skills/*/yuque/scripts/yuque.py' -print -quit 2>/dev/null)
+[ -f "$Y" ] || { echo "yuque script not found (SKILL_DIR=$SKILL_DIR)" >&2; exit 1; }
+python3 "$Y" whoami
 ```
 
-## Create and update
+On an auth error, ask the user to reconnect at
+<https://auth.acedata.cloud/user/connections>. Never ask for their password,
+and never ask them to paste a Cookie into the chat.
 
-Prepare the complete Markdown in a file. 语雀 has no separate draft state — a
-document is either private or public — so the CLI creates **private** documents
-by default and only publishes publicly with an explicit `--public`.
+## Read
+
+A knowledge base (`repo`) is addressed by its `user/book` namespace or its
+numeric id. **Always run `repos` first — never guess a namespace or an id.**
+Pass back exactly the `repo_id` that `repos` printed; on a cookie connection a
+`user/book` namespace is resolved by matching the account's own knowledge
+bases, so it fails for a base the account does not own, and an ambiguous slug
+is refused rather than guessed.
+
+```sh
+Y="${SKILL_DIR:-}/scripts/yuque.py"; [ -f "$Y" ] || Y=$(find /tmp -maxdepth 8 -path '*/skills/*/yuque/scripts/yuque.py' -print -quit 2>/dev/null)
+python3 "$Y" repos
+python3 "$Y" docs REPO_ID --limit 20
+python3 "$Y" doc REPO_ID DOC_ID
+```
 
-```bash
-# First call is always a dry run and does not load credentials or call the API.
-python3 "$SKILL_DIR/scripts/yuque.py" create REPO_NAMESPACE \
-  --title "标题" --content-file /tmp/article.md
+## Create
+
+Prepare the complete Markdown in a file. 语雀 has no draft state — a document is
+either private or public — so the CLI creates **private** documents by default
+and only publishes publicly with an explicit `--public`.
+
+```sh
+Y="${SKILL_DIR:-}/scripts/yuque.py"; [ -f "$Y" ] || Y=$(find /tmp -maxdepth 8 -path '*/skills/*/yuque/scripts/yuque.py' -print -quit 2>/dev/null)
+
+# The first call is always a dry run: it loads no credentials and calls no API.
+python3 "$Y" create REPO_ID --title "标题" --content-file /tmp/article.md
 
 # Create it privately after the user confirms.
-python3 "$SKILL_DIR/scripts/yuque.py" create REPO_NAMESPACE \
-  --title "标题" --content-file /tmp/article.md --confirm
+python3 "$Y" create REPO_ID --title "标题" --content-file /tmp/article.md --confirm
 
 # Public publishing additionally requires --public.
-python3 "$SKILL_DIR/scripts/yuque.py" create REPO_NAMESPACE \
-  --title "标题" --content-file /tmp/article.md --public --confirm
-
-python3 "$SKILL_DIR/scripts/yuque.py" update REPO_NAMESPACE DOC_ID \
-  --title "新标题" --content-file /tmp/article.md --public --confirm
+python3 "$Y" create REPO_ID --title "标题" --content-file /tmp/article.md --public --confirm
 ```
 
-`--confirm` is valid only as the final argument. Always show the target
-knowledge base, title, visibility and full content to the user before a public
-publish. Default to a private document unless the user explicitly asks to
-publish publicly.
-
-Note that `update` rewrites the whole document body. Read the current document
-first if the user only wants part of it changed.
+`--confirm` is honored **only as the final argument**. Before a public publish,
+always show the user the target knowledge base, the title, the visibility and
+the full content. Default to private unless they explicitly ask to publish
+publicly.
 
-## Delete
+## Update and delete (token connections only)
 
-```bash
-python3 "$SKILL_DIR/scripts/yuque.py" delete REPO_NAMESPACE DOC_ID --confirm
+```sh
+python3 "$Y" update REPO_NAMESPACE DOC_ID --title "新标题" --content-file /tmp/a.md --confirm
+python3 "$Y" delete REPO_NAMESPACE DOC_ID --confirm
 ```
 
-Use the real returned `doc_id` and URL. Do not retry a timed-out write
-automatically because its outcome may be unknown; list the documents first so
-you do not create a duplicate.
+`update` rewrites the whole document body — read the current document first if
+the user only wants part of it changed.
 
 ## Gotchas
 
+- Use the real returned `doc_id` and `url`; never invent either. A cookie
+  connection cannot always resolve a public URL, in which case `url` is `null`
+  — report the `doc_id` instead of guessing a link.
+- If a write times out its outcome is **unknown** — run `docs` to check before
+  retrying, or you will create a duplicate.
 - Images referenced by external URL are not re-hosted; 语雀 renders them from
-  the original host. If the source blocks hotlinking, upload the images to 语雀
+  the original host. If that host blocks hotlinking, upload the images in 语雀
   manually first and reference the returned URLs.
-- 语雀's own terms state the open API is for normal reading and writing of 语雀
-  content; abnormal automated behaviour can get the account blocked. Keep the
-  volume human-scale.
+- 语雀's terms allow the API for normal reading and writing of 语雀 content;
+  abnormal automated behaviour can get the account blocked. Keep the volume
+  human-scale and never batch-publish.
 
 ## Record the output
 
-After a confirmed public publish returns a real URL, call `publish_artifact`
-once with `kind="article"`, `channel="yuque"`, the title, returned URL, and
-`status="delivered"`. Do not record private documents or failed/unknown writes.
+After a confirmed **public** publish, if the response carries a non-null `url`,
+call `publish_artifact` once with `kind="article"`, `channel="yuque"`, the
+title, that URL, and `status="delivered"`. If `url` is `null`, **do not invent
+one** — report the `doc_id` to the user and skip `publish_artifact`. Do not
+record private documents or failed/unknown writes.

package/skills/yuque/scripts/yuque.py

@@ -1,9 +1,25 @@
 #!/usr/bin/env python3
-"""Read and write Yuque (语雀) documents through its official open API."""
+"""Read and write Yuque (语雀) documents.
+
+Two authentication modes, picked automatically from the environment:
+
+* ``YUQUE_TOKEN``   — the official open API (``/api/v2`` + ``X-Auth-Token``).
+                      Requires a paid 语雀超级会员.
+* ``YUQUE_COOKIES`` — the user's own browser login jar (BYOC) driving the
+                      internal web API (``/api/*``). Free, no membership.
+
+Standard-library only (urllib), no third-party deps, so it runs in the bare
+sandbox without an image change.
+
+Writes are GATED: without a trailing ``--confirm`` they only dry-run.
+``--confirm`` is honored ONLY as the last argument, so a title or body that
+merely contains "--confirm" can never silently write.
+"""
 
 from __future__ import annotations
 
 import argparse
+import gzip
 import json
 import os
 import pathlib
@@ -13,11 +29,21 @@ import urllib.error
 import urllib.parse
 import urllib.request
 
-API_BASE = "https://www.yuque.com/api/v2"
+ORIGIN = "https://www.yuque.com"
+API_BASE = f"{ORIGIN}/api/v2"
+WEB_API = f"{ORIGIN}/api"
+UA = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+)
 GATED_COMMANDS = {"create", "update", "delete"}
+# Commands the internal web API cannot serve safely; see SKILL.md.
+TOKEN_ONLY_COMMANDS = {"update", "delete"}
 MAX_CONTENT_BYTES = 10 * 1024 * 1024
 MAX_ITEMS = 100
 
+RECONNECT = "https://auth.acedata.cloud/user/connections"
+
 
 def output(value) -> None:
     print(json.dumps(value, ensure_ascii=False, indent=2, default=str))
@@ -34,110 +60,280 @@ def split_confirmation(argv: list[str]) -> tuple[list[str], bool]:
 
 
 class NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Refuse redirects outright.
+
+    ``add_unredirected_header`` protects only the Cookie header — urllib copies
+    every *other* header onto a redirected request, so ``x-csrf-token`` would
+    follow a 30x to an arbitrary host. Refusing redirects closes that leak.
+    """
+
     def redirect_request(self, req, fp, code, msg, headers, newurl):
         return None
 
 
+# ── Cookie jar (shared pattern across the cookie-BYOC skills) ──────────────
+
+
+def load_cookies(raw: str) -> list:
+    try:
+        jar = json.loads(raw)
+    except json.JSONDecodeError as error:
+        die(f"YUQUE_COOKIES is not valid JSON: {error}")
+    if not isinstance(jar, list):
+        die(f"YUQUE_COOKIES 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 csrf_token(jar: list) -> str:
+    """Yuque's internal API takes its CSRF token from the yuque_ctoken cookie."""
+    for c in jar:
+        if c.get("name") == "yuque_ctoken" and c.get("value"):
+            return str(c["value"])
+    die(
+        "The 语雀 cookie jar has no yuque_ctoken cookie, so no write can be "
+        f"signed. Log in at {ORIGIN} and reconnect at {RECONNECT}."
+    )
+    return ""  # unreachable; die() raises
+
+
 class YuqueClient:
-    def __init__(self, token: str, opener=None) -> None:
+    """One client, two modes. ``mode`` drives the base URL and the auth headers."""
+
+    def __init__(self, mode: str, *, token: str = "", cookies: list | None = None, opener=None) -> None:
+        self.mode = mode
         self._token = token
+        self._cookies = cookies or []
+        self._csrf = csrf_token(self._cookies) if mode == "cookie" else ""
+        self._books_cache: list[dict] | None = None
+        self._book_meta: dict[int, dict] = {}
         self._opener = opener or urllib.request.build_opener(NoRedirectHandler())
 
     @classmethod
     def from_environment(cls):
         token = os.environ.get("YUQUE_TOKEN", "").strip()
-        if not token:
-            die(
-                "YUQUE_TOKEN is not set. Reconnect 语雀 at "
-                "https://auth.acedata.cloud/user/connections."
-            )
-        return cls(token)
-
-    def request(self, method: str, path: str, *, body=None, write: bool = False, expect_json: bool = True):
-        encoded = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
-        request = urllib.request.Request(
-            f"{API_BASE}{path}",
-            data=encoded,
-            method=method,
-            headers={
-                "Accept": "application/json",
-                "X-Auth-Token": self._token,
-                "Content-Type": "application/json",
-                "User-Agent": "AceDataCloud-Yuque-Skill/1.0",
-            },
+        if token:
+            if "\r" in token or "\n" in token:
+                die("YUQUE_TOKEN contains invalid characters.")
+            return cls("token", token=token)
+        raw = os.environ.get("YUQUE_COOKIES", "").strip()
+        if raw:
+            return cls("cookie", cookies=load_cookies(raw))
+        die(
+            "No 语雀 credential is available. Connect 语雀 with the browser "
+            f"extension (free) or a personal token at {RECONNECT}."
         )
+
+    # -- transport ---------------------------------------------------------
+
+    def _open(self, request: urllib.request.Request, *, what: str, write: bool):
         try:
             with self._opener.open(request, timeout=30) as response:
                 raw = response.read()
+                if response.headers.get("Content-Encoding") == "gzip":
+                    raw = gzip.decompress(raw)
+                return raw
         except urllib.error.HTTPError as error:
             if error.code in {301, 302, 303, 307, 308}:
-                die(f"Yuque API redirected {method} {path}; credentials were not forwarded.")
-            if error.code in {401, 403}:
                 die(
-                    f"Yuque API HTTP {error.code} for {method} {path}. The token is invalid or "
-                    "lacks scope. Reconnect with a token from https://www.yuque.com/settings/tokens."
+                    f"语雀 redirected {what} — not followed, so no credential left "
+                    f"yuque.com. You are most likely logged out; reconnect at {RECONNECT}."
+                    + (
+                        " This was a WRITE: its outcome is UNKNOWN — list the "
+                        "documents before retrying so you do not create a duplicate."
+                        if write
+                        else ""
+                    )
+                )
+            if error.code in {401, 403}:
+                hint = (
+                    "The token is invalid or lacks scope. Note the 语雀 open API "
+                    "requires a paid 语雀超级会员."
+                    if self.mode == "token"
+                    else "The login session expired or the request was rejected by 语雀's "
+                    "CSRF check."
                 )
+                die(f"语雀 HTTP {error.code} for {what}. {hint} Reconnect at {RECONNECT}.")
             if error.code == 404:
-                die(f"Yuque API 404 for {method} {path}; the repo or document does not exist.")
-            die(f"Yuque API HTTP {error.code} for {method} {path}.")
-        except (urllib.error.URLError, OSError, socket.timeout):
+                die(f"语雀 404 for {what}; the knowledge base or document does not exist.")
+            die(f"语雀 HTTP {error.code} for {what}.")
+        except (urllib.error.URLError, OSError, socket.timeout) as error:
             if write:
                 die(
-                    f"Yuque write {method} {path} did not return a result; outcome is unknown. "
-                    "List the documents before retrying so you do not create a duplicate."
+                    f"语雀 write {what} did not return a result ({error}); the outcome "
+                    "is UNKNOWN. List the documents before retrying so you do not "
+                    "create a duplicate."
                 )
-            die(f"Network error while calling Yuque {method} {path}.")
+            die(f"Network error while calling 语雀 {what}.")
+
+    def request(self, method: str, path: str, *, body=None, write: bool = False, expect_json: bool = True):
+        """Call the API of whichever mode is active and return the ``data`` payload."""
+        what = f"{method} {path}"
+        if self.mode == "token":
+            url = f"{API_BASE}{path}"
+            headers = {
+                "Accept": "application/json",
+                "X-Auth-Token": self._token,
+                "Content-Type": "application/json",
+                "User-Agent": "AceDataCloud-Yuque-Skill/2.0",
+            }
+        else:
+            url = f"{WEB_API}{path}"
+            # Yuque's CSRF layer rejects writes without Origin/Referer — the
+            # upstream WechatSync adapter injects both for every /api/ call.
+            headers = {
+                "Accept": "application/json",
+                "Accept-Language": "zh-CN,zh;q=0.9",
+                "Content-Type": "application/json",
+                "User-Agent": UA,
+                "Origin": ORIGIN,
+                "Referer": f"{ORIGIN}/dashboard",
+                "x-csrf-token": self._csrf,
+                "x-requested-with": "XMLHttpRequest",
+            }
+
+        encoded = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
+        request = urllib.request.Request(url, data=encoded, method=method, headers=headers)
+        if self.mode == "cookie":
+            request.add_unredirected_header("Cookie", cookie_header(self._cookies, url))
+
+        raw = self._open(request, what=what, write=write)
         if not expect_json or not raw:
             return None
         try:
             payload = json.loads(raw)
         except json.JSONDecodeError:
-            die(f"Yuque returned invalid JSON for {method} {path}.")
+            die(f"语雀 returned invalid JSON for {what}.")
         if not isinstance(payload, dict) or "data" not in payload:
-            die(f"Yuque returned an unexpected envelope for {method} {path}.")
+            die(f"语雀 returned an unexpected envelope for {what}.")
         return payload["data"]
 
+    # -- reads -------------------------------------------------------------
+
     def user(self) -> dict:
-        value = self.request("GET", "/user")
+        path = "/user" if self.mode == "token" else "/mine"
+        value = self.request("GET", path)
         if not isinstance(value, dict):
-            die("Yuque returned malformed user data.")
+            die("语雀 returned malformed user data.")
         return value
 
-    def repos(self, login: str) -> list[dict]:
-        quoted = urllib.parse.quote(str(login), safe="")
-        value = self.request("GET", f"/users/{quoted}/repos")
-        if not isinstance(value, list):
-            die("Yuque returned malformed repo data.")
-        return value
+    def repos(self, login: str | None = None) -> list[dict]:
+        if self.mode == "token":
+            quoted = urllib.parse.quote(str(login), safe="")
+            value = self.request("GET", f"/users/{quoted}/repos")
+            if not isinstance(value, list):
+                die("语雀 returned malformed repo data.")
+            return value
+        # Internal API: books are nested under the "common used" payload and
+        # carry the book id as target_id.
+        value = self.request("GET", "/mine/common_used")
+        books = (value or {}).get("books") if isinstance(value, dict) else None
+        if not isinstance(books, list):
+            die("语雀 returned malformed knowledge-base data.")
+        return books
 
     def docs(self, repo: str) -> list[dict]:
-        quoted = urllib.parse.quote(str(repo), safe="")
-        value = self.request("GET", f"/repos/{quoted}/docs")
+        if self.mode == "token":
+            quoted = urllib.parse.quote(str(repo), safe="")
+            value = self.request("GET", f"/repos/{quoted}/docs")
+        else:
+            value = self.request("GET", f"/books/{self._book_id(repo)}/docs")
         if not isinstance(value, list):
-            die("Yuque returned malformed document data.")
+            die("语雀 returned malformed document data.")
         return value
 
-    def doc(self, repo: str, doc_id: str) -> dict:
-        repo_q = urllib.parse.quote(str(repo), safe="")
-        doc_q = urllib.parse.quote(str(doc_id), safe="")
-        value = self.request("GET", f"/repos/{repo_q}/docs/{doc_q}")
+    def doc(self, repo: str, doc_id: str) -> tuple[dict, str | None]:
+        book_id = None
+        if self.mode == "token":
+            repo_q = urllib.parse.quote(str(repo), safe="")
+            doc_q = urllib.parse.quote(str(doc_id), safe="")
+            value = self.request("GET", f"/repos/{repo_q}/docs/{doc_q}")
+        else:
+            book_id = self._book_id(repo)
+            query = urllib.parse.urlencode({"book_id": book_id, "mode": "markdown"})
+            doc_q = urllib.parse.quote(str(doc_id), safe="")
+            value = self.request("GET", f"/docs/{doc_q}?{query}")
         if not isinstance(value, dict):
-            die("Yuque returned malformed document data.")
-        return value
+            die("语雀 returned malformed document data.")
+        return value, self.doc_url(book_id, value)
+
+    # -- writes ------------------------------------------------------------
 
-    def create_doc(self, repo: str, body: dict) -> dict:
-        quoted = urllib.parse.quote(str(repo), safe="")
-        value = self.request("POST", f"/repos/{quoted}/docs", body=body, write=True)
+    def create_doc(self, repo: str, args, content: str) -> tuple[dict, str | None]:
+        book_id = None
+        if self.mode == "token":
+            quoted = urllib.parse.quote(str(repo), safe="")
+            body = {
+                "title": args.title,
+                "body": content,
+                "format": "markdown",
+                "public": 1 if args.public else 0,
+            }
+            if args.slug:
+                body["slug"] = args.slug
+            value = self.request("POST", f"/repos/{quoted}/docs", body=body, write=True)
+        else:
+            # The internal API accepts markdown directly, so we skip the extra
+            # /api/docs/convert round trip, and insert_to_catalog puts the new
+            # doc in the book's 目录 (the plain create leaves it unlisted).
+            book_id = self._book_id(repo)
+            body = {
+                "book_id": book_id,
+                "title": args.title,
+                "format": "markdown",
+                "body": content,
+                "body_draft": content,
+                "public": 1 if args.public else 0,
+                "insert_to_catalog": True,
+                "action": "appendByDocs",
+                "target_uuid": "",
+            }
+            if args.slug:
+                body["slug"] = args.slug
+            value = self.request("POST", "/docs", body=body, write=True)
         if not isinstance(value, dict) or not value.get("id"):
-            die("Yuque did not return a valid created document.")
-        return value
+            die("语雀 did not return a valid created document.")
+        return value, self.doc_url(book_id, value)
 
-    def update_doc(self, repo: str, doc_id: str, body: dict) -> dict:
+    def update_doc(self, repo: str, doc_id: str, args, content: str) -> dict:
         repo_q = urllib.parse.quote(str(repo), safe="")
         doc_q = urllib.parse.quote(str(doc_id), safe="")
+        body = {
+            "title": args.title,
+            "body": content,
+            "format": "markdown",
+            "public": 1 if args.public else 0,
+        }
+        if args.slug:
+            body["slug"] = args.slug
         value = self.request("PUT", f"/repos/{repo_q}/docs/{doc_q}", body=body, write=True)
         if not isinstance(value, dict) or not value.get("id"):
-            die("Yuque did not return a valid updated document.")
+            die("语雀 did not return a valid updated document.")
         return value
 
     def delete_doc(self, repo: str, doc_id: str) -> None:
@@ -145,6 +341,73 @@ class YuqueClient:
         doc_q = urllib.parse.quote(str(doc_id), safe="")
         self.request("DELETE", f"/repos/{repo_q}/docs/{doc_q}", write=True, expect_json=False)
 
+    # -- helpers -----------------------------------------------------------
+
+    def _book_id(self, repo: str) -> int:
+        """Resolve a repo reference to a numeric book id for the internal API.
+
+        The internal endpoints are addressed by numeric book id only, so a
+        ``user/book`` namespace has to be looked up against the account's own
+        knowledge bases first.
+        """
+        text = str(repo).strip()
+        # isdigit() is Unicode-aware but int() is not, and non-ASCII digits
+        # would otherwise either crash or resolve to a different number.
+        if text.isascii() and text.isdigit():
+            return int(text)
+        wanted = text.rsplit("/", 1)[-1].lower()
+        if not wanted:
+            die("Empty knowledge base reference; run `repos` and pass a repo_id.")
+        matches = []
+        for book in self._books():
+            slug = str(book.get("slug") or "").lower()
+            name = str(book.get("name") or "").lower()
+            if wanted in {slug, name}:
+                raw = book.get("target_id") or book.get("id")
+                try:
+                    matches.append((int(raw), book))
+                except (TypeError, ValueError):
+                    continue
+        if len(matches) > 1:
+            die(
+                f"{repo!r} matches {len(matches)} knowledge bases "
+                f"({', '.join(str(m[0]) for m in matches)}). Pass the numeric "
+                "repo_id from `repos` instead — writing to the wrong base is silent."
+            )
+        if matches:
+            self._book_meta[matches[0][0]] = matches[0][1]
+            return matches[0][0]
+        die(
+            f"Could not resolve knowledge base {repo!r} to a book id. Run "
+            "`repos` and pass the numeric repo_id shown there."
+        )
+        return 0  # unreachable; die() raises
+
+    def _books(self) -> list[dict]:
+        """Knowledge bases, fetched once — a doc loop must not re-query per item."""
+        if self._books_cache is None:
+            self._books_cache = self.repos()
+        return self._books_cache
+
+    def doc_url(self, book_id, doc: dict) -> str | None:
+        """Public URL for a doc, using the book namespace when we know it."""
+        slug = doc.get("slug")
+        book = (doc.get("book") or {}) if isinstance(doc.get("book"), dict) else {}
+        namespace = book.get("namespace")
+        if not namespace and self.mode == "cookie":
+            try:
+                meta = self._book_meta.get(int(book_id)) or {}
+            except (TypeError, ValueError):
+                meta = {}
+            user = (meta.get("user") or {}) if isinstance(meta.get("user"), dict) else {}
+            login = user.get("login")
+            book_slug = meta.get("slug")
+            if login and book_slug:
+                namespace = f"{login}/{book_slug}"
+        if namespace and slug:
+            return f"{ORIGIN}/{namespace}/{slug}"
+        return None
+
 
 def read_content(args) -> str:
     if args.content_file:
@@ -163,9 +426,17 @@ def read_content(args) -> str:
 
 
 def format_repo(repo: dict) -> dict:
+    # The internal API nests books under a "common used" record whose own `id`
+    # is NOT the book id — the book id is target_id. Prefer it, or `repos`
+    # would print an id that no other endpoint accepts.
+    repo_id = repo.get("target_id") or repo.get("id")
+    user = repo.get("user") if isinstance(repo.get("user"), dict) else {}
+    namespace = repo.get("namespace")
+    if not namespace and user.get("login") and repo.get("slug"):
+        namespace = f"{user['login']}/{repo['slug']}"
     return {
-        "repo_id": repo.get("id"),
-        "namespace": repo.get("namespace"),
+        "repo_id": repo_id,
+        "namespace": namespace,
         "name": repo.get("name"),
         "slug": repo.get("slug"),
         "type": repo.get("type"),
@@ -174,43 +445,31 @@ def format_repo(repo: dict) -> dict:
     }
 
 
-def format_doc(doc: dict, repo: str | None = None) -> dict:
+def format_doc(doc: dict, repo: str | None = None, url: str | None = None) -> dict:
     namespace = repo or (doc.get("book") or {}).get("namespace")
     slug = doc.get("slug")
+    if url is None and namespace and slug and not str(namespace).isdigit():
+        url = f"{ORIGIN}/{namespace}/{slug}"
     return {
         "doc_id": doc.get("id"),
         "title": doc.get("title"),
         "slug": slug,
         "public": doc.get("public"),
         "status": doc.get("status"),
-        "url": f"https://www.yuque.com/{namespace}/{slug}" if namespace and slug else None,
+        "url": url,
         "word_count": doc.get("word_count"),
         "created_at": doc.get("created_at"),
         "updated_at": doc.get("updated_at"),
     }
 
 
-def build_body(args, content: str) -> dict:
-    # public: 0 = private, 1 = public. Yuque has no separate "draft" state, so a
-    # private doc is the closest equivalent and is the default.
-    body = {
-        "title": args.title,
-        "body": content,
-        "format": "markdown",
-        "public": 1 if args.public else 0,
-    }
-    if args.slug:
-        body["slug"] = args.slug
-    return body
-
-
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="yuque.py", description="Yuque open API CLI")
+    parser = argparse.ArgumentParser(prog="yuque.py", description="Yuque CLI (token or cookie)")
     sub = parser.add_subparsers(dest="command", required=True)
-    sub.add_parser("whoami", help="show the token's account")
+    sub.add_parser("whoami", help="show the connected account and the active auth mode")
 
     repos = sub.add_parser("repos", help="list the account's knowledge bases")
-    repos.add_argument("--login", help="user login; defaults to the token's own account")
+    repos.add_argument("--login", help="user login; token mode only, defaults to the own account")
 
     docs = sub.add_parser("docs", help="list documents in a knowledge base")
     docs.add_argument("repo", help="repo namespace (user/book) or numeric repo id")
@@ -255,7 +514,7 @@ def dry_run(args, content: str | None = None) -> None:
         )
     else:
         value["doc_id"] = args.doc_id
-    value["note"] = "Re-run with --confirm as the final argument to write to Yuque."
+    value["note"] = "Re-run with --confirm as the final argument to write to 语雀."
     output(value)
 
 
@@ -269,42 +528,56 @@ def main(argv: list[str] | None = None) -> None:
         return
 
     client = YuqueClient.from_environment()
+    if client.mode == "cookie" and args.command in TOKEN_ONLY_COMMANDS:
+        die(
+            f"`{args.command}` is only available when 语雀 is connected with a "
+            "personal token (the open API). This connection uses login cookies. "
+            "Create a new document instead, or edit the existing one in 语雀."
+        )
+
+    mode = {"auth_mode": client.mode}
     if args.command == "whoami":
         user = client.user()
+        login = user.get("login")
         output(
             {
+                **mode,
                 "user_id": user.get("id"),
-                "login": user.get("login"),
+                "login": login,
                 "name": user.get("name"),
-                "url": f"https://www.yuque.com/{user.get('login')}" if user.get("login") else None,
+                "url": f"{ORIGIN}/{login}" if login else None,
                 "books_count": user.get("books_count"),
                 "public_books_count": user.get("public_books_count"),
             }
         )
     elif args.command == "repos":
-        login = args.login or client.user().get("login")
-        if not login:
-            die("Could not resolve the account login; pass --login explicitly.")
-        output({"repos": [format_repo(item) for item in client.repos(login)]})
+        if client.mode == "token":
+            login = args.login or client.user().get("login")
+            if not login:
+                die("Could not resolve the account login; pass --login explicitly.")
+            items = client.repos(login)
+        else:
+            items = client.repos()
+        output({**mode, "repos": [format_repo(item) for item in items]})
     elif args.command == "docs":
         if not 1 <= args.limit <= MAX_ITEMS:
             die(f"--limit must be between 1 and {MAX_ITEMS}.")
         items = client.docs(args.repo)[: args.limit]
-        output({"count": len(items), "docs": [format_doc(item, args.repo) for item in items]})
+        output({**mode, "count": len(items), "docs": [format_doc(item, args.repo) for item in items]})
     elif args.command == "doc":
-        doc = client.doc(args.repo, args.doc_id)
-        result = format_doc(doc, args.repo)
+        doc, url = client.doc(args.repo, args.doc_id)
+        result = format_doc(doc, args.repo, url)
         result["body"] = doc.get("body")
-        output(result)
+        output({**mode, **result})
     elif args.command == "create":
-        result = client.create_doc(args.repo, build_body(args, content or ""))
-        output({"ok": True, **format_doc(result, args.repo), "public": bool(args.public)})
+        result, url = client.create_doc(args.repo, args, content or "")
+        output({**mode, "ok": True, **format_doc(result, args.repo, url), "public": bool(args.public)})
     elif args.command == "update":
-        result = client.update_doc(args.repo, args.doc_id, build_body(args, content or ""))
-        output({"ok": True, **format_doc(result, args.repo), "public": bool(args.public)})
+        result = client.update_doc(args.repo, args.doc_id, args, content or "")
+        output({**mode, "ok": True, **format_doc(result, args.repo), "public": bool(args.public)})
     elif args.command == "delete":
         client.delete_doc(args.repo, args.doc_id)
-        output({"ok": True, "repo": args.repo, "doc_id": args.doc_id, "deleted": True})
+        output({**mode, "ok": True, "repo": args.repo, "doc_id": args.doc_id, "deleted": True})
 
 
 if __name__ == "__main__":

package/skills/yuque/tests/test_yuque.py

@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+import unittest
+import unittest.mock
+import urllib.error
+
+SCRIPT = pathlib.Path(__file__).resolve().parents[1] / "scripts" / "yuque.py"
+SPEC = importlib.util.spec_from_file_location("yuque_skill_script", SCRIPT)
+yuque = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+sys.modules[SPEC.name] = yuque
+SPEC.loader.exec_module(yuque)
+
+
+COOKIES = [
+    {"name": "yuque_ctoken", "value": "CTOKEN", "domain": ".yuque.com"},
+    {"name": "_yuque_session", "value": "SESSION", "domain": ".yuque.com"},
+]
+
+
+def run(argv, env):
+    """Run main() with a patched environ and captured stdout."""
+    buffer = io.StringIO()
+    code = 0
+    with unittest.mock.patch.dict(yuque.os.environ, env, clear=True):
+        with contextlib.redirect_stdout(buffer):
+            try:
+                yuque.main(argv)
+            except SystemExit as exc:  # die() path
+                code = exc.code
+    return code, json.loads(buffer.getvalue())
+
+
+class ModeSelection(unittest.TestCase):
+    def test_token_wins_when_both_credentials_are_present(self):
+        with unittest.mock.patch.dict(
+            yuque.os.environ,
+            {"YUQUE_TOKEN": "t", "YUQUE_COOKIES": json.dumps(COOKIES)},
+            clear=True,
+        ):
+            self.assertEqual(yuque.YuqueClient.from_environment().mode, "token")
+
+    def test_cookie_is_the_fallback(self):
+        with unittest.mock.patch.dict(
+            yuque.os.environ, {"YUQUE_COOKIES": json.dumps(COOKIES)}, clear=True
+        ):
+            self.assertEqual(yuque.YuqueClient.from_environment().mode, "cookie")
+
+    def test_no_credential_dies_with_a_reconnect_hint(self):
+        code, payload = run(["whoami"], {})
+        self.assertEqual(code, 1)
+        self.assertIn("connections", payload["error"])
+
+    def test_cookie_jar_without_ctoken_is_rejected(self):
+        jar = [c for c in COOKIES if c["name"] != "yuque_ctoken"]
+        code, payload = run(["whoami"], {"YUQUE_COOKIES": json.dumps(jar)})
+        self.assertEqual(code, 1)
+        self.assertIn("yuque_ctoken", payload["error"])
+
+
+class CookieScoping(unittest.TestCase):
+    def test_jar_is_not_sent_off_domain(self):
+        self.assertEqual(yuque.cookie_header(COOKIES, "https://evil.example/x"), "")
+
+    def test_jar_is_sent_to_yuque(self):
+        header = yuque.cookie_header(COOKIES, "https://www.yuque.com/api/mine")
+        self.assertIn("_yuque_session=SESSION", header)
+
+    def test_domainless_cookie_is_not_leaked_to_an_unrelated_host(self):
+        jar = COOKIES + [{"name": "loose", "value": "L"}]
+        self.assertEqual(yuque.cookie_header(jar, "https://evil.example/x"), "")
+
+    def test_a_lookalike_suffix_host_is_not_matched(self):
+        self.assertEqual(yuque.cookie_header(COOKIES, "https://notyuque.com/api"), "")
+
+
+class WriteGating(unittest.TestCase):
+    def test_create_without_confirm_is_a_dry_run(self):
+        code, payload = run(
+            ["create", "1", "--title", "T", "--content", "body"],
+            {"YUQUE_COOKIES": json.dumps(COOKIES)},
+        )
+        self.assertEqual(code, 0)
+        self.assertTrue(payload["dry_run"])
+
+    def test_confirm_is_only_honored_as_the_last_argument(self):
+        # A real --confirm argv element that is NOT last must not confirm.
+        argv = ["create", "1", "--confirm", "--title", "T", "--content", "b"]
+        self.assertEqual(yuque.split_confirmation(argv), (argv, False))
+
+    def test_confirm_as_the_last_argument_does_confirm(self):
+        clean, confirmed = yuque.split_confirmation(["create", "1", "--confirm"])
+        self.assertTrue(confirmed)
+        self.assertEqual(clean, ["create", "1"])
+
+    def test_a_body_containing_the_flag_is_not_a_confirmation(self):
+        code, payload = run(
+            ["create", "1", "--title", "T", "--content", "please --confirm this"],
+            {"YUQUE_COOKIES": json.dumps(COOKIES)},
+        )
+        self.assertEqual(code, 0)
+        self.assertTrue(payload["dry_run"])
+
+    def test_create_defaults_to_private(self):
+        code, payload = run(
+            ["create", "1", "--title", "T", "--content", "b"],
+            {"YUQUE_COOKIES": json.dumps(COOKIES)},
+        )
+        self.assertEqual(payload["visibility"], "private")
+
+
+class TokenOnlyCommands(unittest.TestCase):
+    def test_update_is_refused_on_a_cookie_connection(self):
+        code, payload = run(
+            ["update", "1", "9", "--title", "T", "--content", "b", "--confirm"],
+            {"YUQUE_COOKIES": json.dumps(COOKIES)},
+        )
+        self.assertEqual(code, 1)
+        self.assertIn("personal token", payload["error"])
+
+    def test_delete_is_refused_on_a_cookie_connection(self):
+        code, payload = run(
+            ["delete", "1", "9", "--confirm"], {"YUQUE_COOKIES": json.dumps(COOKIES)}
+        )
+        self.assertEqual(code, 1)
+        self.assertIn("personal token", payload["error"])
+
+
+class RequestShape(unittest.TestCase):
+    """Capture the outgoing request instead of calling 语雀."""
+
+    def _capture(self, mode_env, method, path, **kwargs):
+        seen = {}
+
+        class Opener:
+            def open(self, request, timeout=None):
+                seen["request"] = request
+                raise urllib.error.HTTPError(
+                    request.full_url, 401, "Unauthorized", {}, None
+                )
+
+        with unittest.mock.patch.dict(yuque.os.environ, mode_env, clear=True):
+            client = yuque.YuqueClient.from_environment()
+        client._opener = Opener()
+        with contextlib.redirect_stdout(io.StringIO()):
+            with self.assertRaises(SystemExit):
+                client.request(method, path, **kwargs)
+        return seen["request"]
+
+    def test_cookie_mode_sends_csrf_origin_and_referer(self):
+        request = self._capture({"YUQUE_COOKIES": json.dumps(COOKIES)}, "GET", "/mine")
+        self.assertEqual(request.full_url, "https://www.yuque.com/api/mine")
+        self.assertEqual(request.get_header("X-csrf-token"), "CTOKEN")
+        # 语雀's CSRF layer rejects writes without these two.
+        self.assertEqual(request.get_header("Origin"), "https://www.yuque.com")
+        self.assertTrue(request.get_header("Referer"))
+
+    def test_cookie_is_unredirected_so_it_is_dropped_on_a_30x(self):
+        request = self._capture({"YUQUE_COOKIES": json.dumps(COOKIES)}, "GET", "/mine")
+        self.assertIn("Cookie", request.unredirected_hdrs)
+        self.assertNotIn("Cookie", request.headers)
+
+    def test_token_mode_uses_the_open_api_and_auth_header(self):
+        request = self._capture({"YUQUE_TOKEN": "TK"}, "GET", "/user")
+        self.assertEqual(request.full_url, "https://www.yuque.com/api/v2/user")
+        self.assertEqual(request.get_header("X-auth-token"), "TK")
+        self.assertIsNone(request.get_header("X-csrf-token"))
+
+    def test_cookie_create_sends_markdown_without_a_convert_round_trip(self):
+        request = self._capture(
+            {"YUQUE_COOKIES": json.dumps(COOKIES)},
+            "POST",
+            "/docs",
+            body={"book_id": 1, "format": "markdown", "body": "# hi"},
+            write=True,
+        )
+        payload = json.loads(request.data)
+        self.assertEqual(payload["format"], "markdown")
+
+
+class RedirectHandling(unittest.TestCase):
+    def test_redirects_are_refused(self):
+        handler = yuque.NoRedirectHandler()
+        self.assertIsNone(
+            handler.redirect_request(None, None, 302, "Found", {}, "https://evil.example")
+        )
+
+    def test_the_no_redirect_handler_is_actually_installed(self):
+        # Cookie is unredirected, but x-csrf-token is NOT — urllib copies every
+        # other header onto a redirected request, so only refusing the redirect
+        # keeps the CSRF token off a foreign host.
+        with unittest.mock.patch.dict(
+            yuque.os.environ, {"YUQUE_COOKIES": json.dumps(COOKIES)}, clear=True
+        ):
+            client = yuque.YuqueClient.from_environment()
+        self.assertTrue(
+            any(isinstance(h, yuque.NoRedirectHandler) for h in client._opener.handlers),
+            "default opener must install NoRedirectHandler",
+        )
+
+    def test_a_30x_on_a_write_reports_an_unknown_outcome(self):
+        class Opener:
+            def open(self, request, timeout=None):
+                raise urllib.error.HTTPError(
+                    request.full_url, 302, "Found", {}, None
+                )
+
+        with unittest.mock.patch.dict(
+            yuque.os.environ, {"YUQUE_COOKIES": json.dumps(COOKIES)}, clear=True
+        ):
+            client = yuque.YuqueClient.from_environment()
+        client._opener = Opener()
+        buffer = io.StringIO()
+        with contextlib.redirect_stdout(buffer):
+            with self.assertRaises(SystemExit):
+                client.request("POST", "/docs", body={}, write=True)
+        error = json.loads(buffer.getvalue())["error"]
+        self.assertIn("UNKNOWN", error)
+
+
+class BookIdResolution(unittest.TestCase):
+    """`_book_id` turns a repo reference into the numeric id the internal API needs."""
+
+    def _client(self, books):
+        with unittest.mock.patch.dict(
+            yuque.os.environ, {"YUQUE_COOKIES": json.dumps(COOKIES)}, clear=True
+        ):
+            client = yuque.YuqueClient.from_environment()
+        client._books_cache = books
+        return client
+
+    def _expect_die(self, fn, *args):
+        buffer = io.StringIO()
+        with contextlib.redirect_stdout(buffer):
+            with self.assertRaises(SystemExit):
+                fn(*args)
+        return json.loads(buffer.getvalue())["error"]
+
+    def test_non_ascii_digits_do_not_crash(self):
+        # str.isdigit() is Unicode-aware but int() is not; a traceback would
+        # break the JSON-only output contract.
+        error = self._expect_die(self._client([])._book_id, "²")
+        self.assertIn("Could not resolve", error)
+
+    def test_a_malformed_book_id_is_skipped_not_fatal(self):
+        client = self._client(
+            [{"slug": "bad", "target_id": "not-a-number"}, {"slug": "blog", "target_id": 42}]
+        )
+        self.assertEqual(client._book_id("alice/blog"), 42)
+
+    def test_an_ambiguous_slug_is_refused_rather_than_guessed(self):
+        # Writing to the wrong knowledge base would be a silent wrong result.
+        client = self._client(
+            [{"slug": "blog", "target_id": 111}, {"slug": "blog", "target_id": 222}]
+        )
+        error = self._expect_die(client._book_id, "alice/blog")
+        self.assertIn("matches 2", error)
+
+    def test_books_are_fetched_once_per_run(self):
+        client = self._client(None)
+        calls = []
+
+        def fake_repos(login=None):
+            calls.append(1)
+            return [{"slug": "blog", "target_id": 7}]
+
+        client.repos = fake_repos
+        client._book_id("a/blog")
+        client._book_id("a/blog")
+        self.assertEqual(len(calls), 1)
+
+
+class OutputShape(unittest.TestCase):
+    def test_repos_reports_target_id_as_the_repo_id(self):
+        # The common-used record's own `id` is not the book id.
+        formatted = yuque.format_repo({"id": 55555555, "target_id": 12345, "slug": "blog"})
+        self.assertEqual(formatted["repo_id"], 12345)
+
+    def test_repos_derives_a_namespace_from_the_owner_login(self):
+        formatted = yuque.format_repo(
+            {"target_id": 1, "slug": "blog", "user": {"login": "alice"}}
+        )
+        self.assertEqual(formatted["namespace"], "alice/blog")
+
+    def test_cookie_mode_create_returns_a_real_url(self):
+        # SKILL.md requires a real URL for publish_artifact; a null would
+        # invite the model to invent one.
+        client = self._cookie_client()
+        client._book_meta[9] = {"slug": "blog", "user": {"login": "alice"}}
+        url = client.doc_url(9, {"id": 1, "slug": "abc123"})
+        self.assertEqual(url, "https://www.yuque.com/alice/blog/abc123")
+
+    def test_doc_url_is_none_rather_than_wrong_when_the_book_is_unknown(self):
+        client = self._cookie_client()
+        self.assertIsNone(client.doc_url(9, {"id": 1, "slug": "abc123"}))
+
+    def _cookie_client(self):
+        with unittest.mock.patch.dict(
+            yuque.os.environ, {"YUQUE_COOKIES": json.dumps(COOKIES)}, clear=True
+        ):
+            return yuque.YuqueClient.from_environment()
+
+
+if __name__ == "__main__":
+    unittest.main()