yuque-cli 0.1.0__py3-none-any.whl

yuque_cli/__init__.py

@@ -0,0 +1,3 @@
+"""yuque-cli: 企业语雀命令行客户端。"""
+
+__version__ = "0.1.0"

yuque_cli/__main__.py

@@ -0,0 +1,4 @@
+from .cli import app
+
+if __name__ == "__main__":
+    app()

yuque_cli/appdata.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+import re
+from urllib.parse import unquote
+
+# 匹配 window.appData = JSON.parse(decodeURIComponent("...")) 中被 percent-encode 的串。
+# 编码后的内容不含裸引号（" 会变成 %22），故 [^"]* 足以圈定整段。
+_APP_DATA_RE = re.compile(
+    r'window\.appData\s*=\s*JSON\.parse\(\s*decodeURIComponent\(\s*"([^"]*)"\s*\)\s*\)'
+)
+
+
+class AppDataError(ValueError):
+    """页面 HTML 中找不到或无法解析 window.appData。"""
+
+
+def parse_app_data(html: str) -> dict:
+    m = _APP_DATA_RE.search(html)
+    if not m:
+        raise AppDataError("页面中未找到 window.appData（可能未登录或页面结构变化）")
+    try:
+        return json.loads(unquote(m.group(1)))
+    except (ValueError, json.JSONDecodeError) as exc:
+        raise AppDataError(f"window.appData 解码失败：{exc}") from exc
+
+
+def book_id(app_data: dict) -> int:
+    try:
+        return int(app_data["book"]["id"])
+    except (KeyError, TypeError, ValueError) as exc:
+        raise AppDataError("appData 中缺少 book.id") from exc
+
+
+def doc_id(app_data: dict) -> int:
+    try:
+        return int(app_data["doc"]["id"])
+    except (KeyError, TypeError, ValueError) as exc:
+        raise AppDataError("appData 中缺少 doc.id（该页面可能不是文档页）") from exc

yuque_cli/auth.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Callable, Optional
+from urllib.parse import urlsplit
+
+import httpx
+
+from .session import SESSION_COOKIE, parse_cookie_string
+
+CDP_PORT = 9222
+# 本地回环不应走代理；这些 host 在 CDP 连接时强制直连。
+_NO_PROXY_HOSTS = ["127.0.0.1", "localhost", "::1"]
+_WS_TIMEOUT = 5.0
+
+
+class CdpUnavailable(Exception):
+    """无法通过 Chrome 远程调试（CDP）抓到目标域名的会话 cookie。"""
+
+
+# -- 浏览器级 WebSocket 端点发现 -------------------------------------------
+
+
+def default_devtools_port_files() -> list[Path]:
+    home = Path.home()
+    candidates = [
+        home / "Library/Application Support/Google/Chrome/DevToolsActivePort",
+        home / "Library/Application Support/Chromium/DevToolsActivePort",
+        home / ".config/google-chrome/DevToolsActivePort",
+        home / ".config/chromium/DevToolsActivePort",
+    ]
+    local_appdata = os.environ.get("LOCALAPPDATA")
+    if local_appdata:
+        candidates.append(
+            Path(local_appdata) / "Google/Chrome/User Data/DevToolsActivePort"
+        )
+    return candidates
+
+
+def parse_devtools_active_port(text: str) -> tuple[int, str]:
+    lines = text.splitlines()
+    if not lines or not lines[0].strip().isdigit():
+        raise CdpUnavailable("DevToolsActivePort 内容异常（缺少端口号）")
+    port = int(lines[0].strip())
+    ws_path = lines[1].strip() if len(lines) > 1 else ""
+    return port, ws_path
+
+
+def _ws_url_from_devtools_file(*, verbose: bool = False) -> Optional[str]:
+    """从 Chrome 的 DevToolsActivePort 文件取浏览器级 WS 地址。
+
+    Chrome 136+ 在默认 profile 下禁用了 /json HTTP 接口（返回 404），但该文件仍记录
+    端口与浏览器级 WS 路径，故这是最可靠的发现方式。
+    """
+    for path in default_devtools_port_files():
+        try:
+            if not path.is_file():
+                continue
+            port, ws_path = parse_devtools_active_port(path.read_text())
+            if ws_path:
+                return f"ws://127.0.0.1:{port}{ws_path}"
+        except Exception as exc:
+            if verbose:
+                print(f"读取 {path} 失败：{exc!r}", file=sys.stderr)
+    return None
+
+
+def _ws_url_from_http(port: int, *, verbose: bool = False) -> Optional[str]:
+    """退而求其次：经 /json/version 取 WS 地址（部分配置可用）。
+
+    用 trust_env=False 绕开 *_proxy 环境变量——本地回环不该走代理。
+    """
+    url = f"http://127.0.0.1:{port}/json/version"
+    try:
+        resp = httpx.get(url, timeout=1.0, trust_env=False)
+        resp.raise_for_status()
+        return resp.json().get("webSocketDebuggerUrl")
+    except Exception as exc:
+        if verbose:
+            print(f"CDP HTTP 探测失败（{url}）：{exc!r}", file=sys.stderr)
+        return None
+
+
+def cdp_websocket_url(port: int = CDP_PORT, *, verbose: bool = False) -> Optional[str]:
+    """发现本地 Chrome 的浏览器级 WebSocket 调试地址；未启用远程调试则 None。"""
+    return _ws_url_from_devtools_file(verbose=verbose) or _ws_url_from_http(
+        port, verbose=verbose
+    )
+
+
+# -- cookie 过滤 ------------------------------------------------------------
+
+
+def _domain_matches(cookie_domain: str, host: str) -> bool:
+    d = cookie_domain.lstrip(".")
+    return host == d or host.endswith("." + d)
+
+
+def cookies_for_host(cdp_cookies: list[dict], host: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for cookie in cdp_cookies:
+        if _domain_matches(str(cookie.get("domain", "")), host):
+            out[cookie["name"]] = cookie["value"]
+    return out
+
+
+# -- WebSocket 取 cookie ----------------------------------------------------
+
+
+def _storage_get_cookies(ws_url: str) -> list[dict]:
+    from websocket import create_connection
+
+    # suppress_origin：Chrome 111+ 默认拒绝带 Origin 的 WS（除非 --remote-allow-origins）；
+    # 不发 Origin 头即可连上，免去用户重启 Chrome 加该 flag。
+    ws = create_connection(
+        ws_url,
+        timeout=_WS_TIMEOUT,
+        http_no_proxy=_NO_PROXY_HOSTS,
+        suppress_origin=True,
+    )
+    try:
+        ws.send(json.dumps({"id": 1, "method": "Storage.getCookies"}))
+        for _ in range(50):
+            data = json.loads(ws.recv())
+            if data.get("id") == 1:
+                return data.get("result", {}).get("cookies", [])
+        raise CdpUnavailable("CDP 未在预期内返回 cookie")
+    finally:
+        ws.close()
+
+
+def cookies_via_cdp(base_url: str, ws_url: str) -> dict[str, str]:
+    """经浏览器级 WS 调 Storage.getCookies，过滤出目标域名 cookie 并校验登录态。"""
+    host = urlsplit(base_url).hostname or base_url
+    try:
+        raw = _storage_get_cookies(ws_url)
+    except CdpUnavailable:
+        raise
+    except Exception as exc:  # WS 连接/收发失败、端口已死等
+        raise CdpUnavailable(f"CDP 抓取失败：{exc}") from exc
+    cookies = cookies_for_host(raw, host)
+    if SESSION_COOKIE not in cookies:
+        raise CdpUnavailable(
+            f"CDP 未取到 {host} 的 {SESSION_COOKIE}（请确认已在该 Chrome 登录该域名）"
+        )
+    return cookies
+
+
+def cookies_via_manual(prompt_fn: Callable[[], str]) -> dict[str, str]:
+    return parse_cookie_string(prompt_fn())

yuque_cli/cli.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+import sys
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Annotated, Any, Callable, Optional
+
+import httpx
+import typer
+
+from . import __version__, auth, config, output, session
+from .appdata import AppDataError
+from .appdata import book_id as appdata_book_id
+from .appdata import doc_id as appdata_doc_id
+from .client import Client
+from .errors import AuthExpired, YuqueError
+from .inputs import BodyInputError, resolve_body
+from .session import SessionError
+from .urls import UrlParseError, parse_book_ref, parse_doc_ref
+
+
+@dataclass
+class AppState:
+    json: bool = False
+    yes: bool = False
+    verbose: bool = False
+
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="企业语雀命令行客户端")
+auth_app = typer.Typer(no_args_is_help=True, help="登录态管理")
+book_app = typer.Typer(no_args_is_help=True, help="知识库（book）")
+doc_app = typer.Typer(no_args_is_help=True, help="文档（doc）")
+comment_app = typer.Typer(no_args_is_help=True, help="评论（comment）")
+app.add_typer(auth_app, name="auth")
+app.add_typer(book_app, name="book")
+app.add_typer(doc_app, name="doc")
+app.add_typer(comment_app, name="comment")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_out: Annotated[bool, typer.Option("--json", help="输出原始 JSON")] = False,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="跳过所有确认")] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="打印内部 HTTP 请求")
+    ] = False,
+    version: Annotated[
+        Optional[bool],
+        typer.Option(
+            "--version", "-V", callback=_version_callback, is_eager=True, help="显示版本"
+        ),
+    ] = None,
+) -> None:
+    ctx.obj = AppState(json=json_out, yes=yes, verbose=verbose)
+
+
+# -- 公共辅助 ---------------------------------------------------------------
+
+
+@contextmanager
+def cli_errors():
+    try:
+        yield
+    except AuthExpired as exc:
+        typer.secho(str(exc), fg="red", err=True)
+        raise typer.Exit(2)
+    except (YuqueError, SessionError, UrlParseError, AppDataError, BodyInputError) as exc:
+        typer.secho(str(exc), fg="red", err=True)
+        raise typer.Exit(1)
+
+
+def build_client(state: AppState) -> Client:
+    sess = session.load(config.session_file())
+    hooks: dict[str, list[Callable[..., Any]]] = {}
+    if state.verbose:
+
+        def _log(request: httpx.Request) -> None:
+            typer.secho(f"→ {request.method} {request.url}", fg="bright_black", err=True)
+
+        hook: Callable[..., Any] = _log
+        hooks["request"] = [hook]
+    # trust_env=False：默认直连，绕开 *_proxy 环境变量（如本地 Clash 的 socks5 代理）——
+    # 避免请求被本地代理拦截，也免去 SOCKS 需 socksio 的崩溃。如需经代理访问，移除此参数并装 httpx[socks]。
+    http = httpx.Client(timeout=30.0, event_hooks=hooks, trust_env=False)
+    return Client(http, sess, base_url=config.base_url())
+
+
+def _emit(state: AppState, data, human: str) -> None:
+    typer.echo(output.dumps(data) if state.json else human)
+
+
+def _confirm(state: AppState, message: str) -> None:
+    if state.yes:
+        return
+    if not sys.stdin.isatty():
+        raise YuqueError("需要确认但当前为非交互环境；如确定请加 --yes")
+    if not typer.confirm(message):
+        raise typer.Abort()
+
+
+def _read_body(body: Optional[str], file: Optional[str]) -> Optional[str]:
+    return resolve_body(
+        body, file, stdin=sys.stdin, stdin_isatty=sys.stdin.isatty()
+    )
+
+
+# -- auth -------------------------------------------------------------------
+
+
+def _prompt_cookie() -> str:
+    typer.echo(
+        "请粘贴目标域名的完整 cookie 串"
+        "（浏览器 DevTools → Application → Cookies，或 document.cookie）：",
+        err=True,
+    )
+    return typer.prompt("cookie")
+
+
+_CDP_HINT = (
+    f"未检测到 Chrome 远程调试（DevToolsActivePort / 127.0.0.1:{auth.CDP_PORT}）。\n"
+    "如需自动化登录：完全退出 Chrome，再带远程调试启动并登录目标语雀站点，例如 macOS：\n"
+    f'  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" '
+    f"--remote-debugging-port={auth.CDP_PORT}\n"
+    "随后重试 yuque auth login。现在可手动粘贴 cookie 完成登录。"
+)
+
+
+@auth_app.command("login")
+def auth_login(
+    ctx: typer.Context,
+    manual: Annotated[
+        bool, typer.Option("--manual", help="跳过 CDP，直接手动粘贴 cookie")
+    ] = False,
+) -> None:
+    """登录：默认探测本地 CDP 自动获取登录态；未启用或失败时回退手动粘贴。"""
+    with cli_errors():
+        state: AppState = ctx.obj
+        base = config.base_url()
+        ws_url = None if manual else auth.cdp_websocket_url(verbose=state.verbose)
+        if ws_url is None:
+            if not manual:
+                typer.secho(_CDP_HINT, fg="yellow", err=True)
+            cookies = auth.cookies_via_manual(_prompt_cookie)
+        else:
+            try:
+                cookies = auth.cookies_via_cdp(base, ws_url)
+                typer.secho(
+                    f"已通过 CDP 从浏览器获取 {config.host()} 登录态", fg="green", err=True
+                )
+            except auth.CdpUnavailable as exc:
+                typer.secho(f"CDP 已连接但获取失败：{exc}", fg="yellow", err=True)
+                cookies = auth.cookies_via_manual(_prompt_cookie)
+        sess = session.Session(cookies)
+        sess.require_session()
+        session.save(sess, config.session_file())
+    typer.echo(f"已登录，会话保存在 {config.session_file()}")
+
+
+@auth_app.command("status")
+def auth_status(ctx: typer.Context) -> None:
+    """显示当前登录身份（GET /api/mine）。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        user = build_client(state).mine()
+        _emit(state, user, output.render_user(user))
+
+
+@auth_app.command("logout")
+def auth_logout(ctx: typer.Context) -> None:
+    """清除本地保存的会话。"""
+    path = config.session_file()
+    if path.exists():
+        path.unlink()
+        typer.echo("已退出登录（已清除本地会话）")
+    else:
+        typer.echo("当前未登录")
+
+
+# -- book -------------------------------------------------------------------
+
+
+@book_app.command("list")
+def book_list(ctx: typer.Context) -> None:
+    """列出我的知识库（GET /api/mine/books）。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        books = build_client(state).mine_books()
+        _emit(state, books, output.render_books(books))
+
+
+# -- doc --------------------------------------------------------------------
+
+UrlArg = Annotated[str, typer.Argument(help="目标 URL 或去 host 的路径形态")]
+BodyOpt = Annotated[Optional[str], typer.Option("--body", "-b", help="内联正文")]
+FileOpt = Annotated[
+    Optional[str], typer.Option("--file", "-F", help="从文件读正文（- 表示 stdin）")
+]
+PublicOpt = Annotated[
+    Optional[bool],
+    typer.Option("--public/--private", help="可见性；不给则继承知识库默认/保持原值"),
+]
+
+
+@doc_app.command("list")
+def doc_list(ctx: typer.Context, url: UrlArg) -> None:
+    """列出知识库下的文档。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        ref = parse_book_ref(url)
+        client = build_client(state)
+        book_id = client.resolve_book_id(ref.login, ref.book)
+        docs = client.book_docs(book_id)
+        _emit(state, docs, output.render_docs(docs))
+
+
+@doc_app.command("get")
+def doc_get(ctx: typer.Context, url: UrlArg) -> None:
+    """取文档正文：默认干净 Markdown；--json 出详情（含 Lake）。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        ref = parse_doc_ref(url)
+        client = build_client(state)
+        if state.json:
+            app_data = client.doc_page_app_data(ref.login, ref.book, ref.slug)
+            detail = client.doc_detail(ref.slug, appdata_book_id(app_data))
+            typer.echo(output.dumps(detail))
+        else:
+            typer.echo(client.doc_markdown(ref.login, ref.book, ref.slug))
+
+
+@doc_app.command("create")
+def doc_create(
+    ctx: typer.Context,
+    url: UrlArg,
+    title: Annotated[str, typer.Option("--title", "-t", help="文档标题")],
+    slug: Annotated[Optional[str], typer.Option("--slug", help="文档 slug（省略则自动生成）")] = None,
+    public: PublicOpt = None,
+    body: BodyOpt = None,
+    file: FileOpt = None,
+) -> None:
+    """在知识库中创建文档。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        ref = parse_book_ref(url)
+        text = _read_body(body, file)
+        client = build_client(state)
+        book_id = client.resolve_book_id(ref.login, ref.book)
+        pub = None if public is None else (1 if public else 0)
+        created = client.create_doc(
+            book_id=book_id, title=title, body=text, slug=slug, public=pub
+        )
+        url_out = f"{config.base_url()}/{ref.login}/{ref.book}/{created.get('slug', '')}"
+        _emit(state, created, f"已创建：{url_out}")
+
+
+@doc_app.command("update")
+def doc_update(
+    ctx: typer.Context,
+    url: UrlArg,
+    title: Annotated[Optional[str], typer.Option("--title", "-t", help="新标题")] = None,
+    public: PublicOpt = None,
+    body: BodyOpt = None,
+    file: FileOpt = None,
+) -> None:
+    """更新文档（先取后合并：未给的字段保持原值）。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        if title is None and public is None and body is None and file is None:
+            raise YuqueError(
+                "没有要更新的字段（至少给 --title / 正文 / --public|--private 之一）"
+            )
+        ref = parse_doc_ref(url)
+        client = build_client(state)
+        app_data = client.doc_page_app_data(ref.login, ref.book, ref.slug)
+        doc_id = appdata_doc_id(app_data)
+        meta = app_data.get("doc", {})
+        new_title = title if title is not None else meta.get("title", "")
+        if body is not None or file is not None:
+            new_body = _read_body(body, file) or ""
+        else:
+            new_body = client.doc_markdown(ref.login, ref.book, ref.slug)
+        new_public = (1 if public else 0) if public is not None else meta.get("public")
+        updated = client.update_doc(
+            doc_id=doc_id, title=new_title, body=new_body, public=new_public
+        )
+        url_out = f"{config.base_url()}/{ref.login}/{ref.book}/{ref.slug}"
+        _emit(state, updated, f"已更新：{url_out}")
+
+
+@doc_app.command("delete")
+def doc_delete(ctx: typer.Context, url: UrlArg) -> None:
+    """删除文档（软删，可在回收站恢复）。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        ref = parse_doc_ref(url)
+        client = build_client(state)
+        app_data = client.doc_page_app_data(ref.login, ref.book, ref.slug)
+        doc_id = appdata_doc_id(app_data)
+        title = app_data.get("doc", {}).get("title", ref.slug)
+        _confirm(state, f"确认删除文档「{title}」？（软删，可在回收站恢复）")
+        result = client.delete_doc(doc_id)
+        _emit(state, result, "已删除（可在回收站恢复）")
+
+
+# -- comment ----------------------------------------------------------------
+
+
+@comment_app.command("list")
+def comment_list(ctx: typer.Context, url: UrlArg) -> None:
+    """列出文档的评论。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        ref = parse_doc_ref(url)
+        client = build_client(state)
+        _, doc_id = client.resolve_doc_ids(ref.login, ref.book, ref.slug)
+        items = client.comments(doc_id)
+        _emit(state, items, output.render_comments(items))
+
+
+@comment_app.command("add")
+def comment_add(
+    ctx: typer.Context, url: UrlArg, body: BodyOpt = None, file: FileOpt = None
+) -> None:
+    """给文档添加评论。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        ref = parse_doc_ref(url)
+        text = _read_body(body, file)
+        if not text:
+            raise YuqueError("评论正文不能为空（用 --body 或 --file/-）")
+        client = build_client(state)
+        _, doc_id = client.resolve_doc_ids(ref.login, ref.book, ref.slug)
+        created = client.create_comment(doc_id=doc_id, body=text)
+        _emit(state, created, f"已评论（id={created.get('id', '')}）")
+
+
+@comment_app.command("delete")
+def comment_delete(
+    ctx: typer.Context,
+    comment_id: Annotated[int, typer.Argument(help="评论 id（从 comment list 获取）")],
+) -> None:
+    """删除一条评论。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        client = build_client(state)
+        _confirm(state, f"确认删除评论 {comment_id}？")
+        result = client.delete_comment(comment_id)
+        _emit(state, result, "已删除评论")

yuque_cli/client.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import appdata
+from .errors import ApiError, AuthExpired
+from .session import Session
+
+USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36"
+)
+
+
+class Client:
+    """语雀内部 web API 客户端。注入 httpx.Client 与 Session 以便测试。"""
+
+    def __init__(
+        self,
+        http: httpx.Client,
+        session: Session,
+        *,
+        base_url: str,
+        user_agent: str = USER_AGENT,
+    ) -> None:
+        self.http = http
+        self.session = session
+        self.base_url = base_url.rstrip("/")
+        self.user_agent = user_agent
+
+    # -- 底层请求 -----------------------------------------------------------
+
+    def _headers(self, *, write: bool, referer: str | None) -> dict[str, str]:
+        headers = {
+            "Cookie": self.session.cookie_header,
+            "User-Agent": self.user_agent,
+            "Referer": referer or f"{self.base_url}/",
+            "x-requested-with": "XMLHttpRequest",
+        }
+        if write:
+            token = self.session.csrf_token
+            if not token:
+                raise ApiError("写操作缺少 CSRF token（yuque_ctoken）；请重新登录")
+            headers["Content-Type"] = "application/json"
+            headers["x-csrf-token"] = token
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        write: bool = False,
+        referer: str | None = None,
+    ) -> httpx.Response:
+        resp = self.http.request(
+            method,
+            url,
+            params=params,
+            json=json_body,
+            headers=self._headers(write=write, referer=referer),
+        )
+        if resp.status_code == 401:
+            raise AuthExpired("登录态已失效（401）；请重新运行 yuque auth login")
+        if resp.status_code >= 400:
+            raise ApiError(
+                f"请求失败 {resp.status_code} {method} {url}：{resp.text[:200]}",
+                status_code=resp.status_code,
+            )
+        return resp
+
+    @staticmethod
+    def _data(resp: httpx.Response) -> Any:
+        payload = resp.json()
+        if isinstance(payload, dict) and "data" in payload:
+            return payload["data"]
+        return payload
+
+    # -- 用户 / 知识库 ------------------------------------------------------
+
+    def mine(self) -> dict:
+        return self._data(self._request("GET", f"{self.base_url}/api/mine"))
+
+    def mine_books(self) -> list[dict]:
+        return self._data(self._request("GET", f"{self.base_url}/api/mine/books"))
+
+    def book_docs(self, book_id: int) -> list[dict]:
+        return self._data(
+            self._request("GET", f"{self.base_url}/api/books/{book_id}/docs")
+        )
+
+    # -- 文档 ---------------------------------------------------------------
+
+    def doc_markdown(self, login: str, book: str, slug: str) -> str:
+        url = f"{self.base_url}/{login}/{book}/{slug}/markdown"
+        return self._request(
+            "GET",
+            url,
+            params={"plain": "true", "linebreak": "false", "anchor": "false"},
+            referer=f"{self.base_url}/{login}/{book}/{slug}",
+        ).text
+
+    def doc_detail(self, slug_or_id: str | int, book_id: int) -> dict:
+        return self._data(
+            self._request(
+                "GET",
+                f"{self.base_url}/api/docs/{slug_or_id}",
+                params={"book_id": book_id},
+            )
+        )
+
+    def create_doc(
+        self,
+        *,
+        book_id: int,
+        title: str,
+        body: str | None,
+        slug: str | None = None,
+        public: int | None = None,
+    ) -> dict:
+        payload: dict[str, Any] = {
+            "book_id": book_id,
+            "title": title,
+            "format": "markdown",
+            "body": body or "",
+        }
+        if slug is not None:
+            payload["slug"] = slug
+        if public is not None:
+            payload["public"] = public
+        return self._data(
+            self._request("POST", f"{self.base_url}/api/docs", json_body=payload, write=True)
+        )
+
+    def update_doc(
+        self,
+        *,
+        doc_id: int,
+        title: str,
+        body: str,
+        public: int | None = None,
+    ) -> dict:
+        payload: dict[str, Any] = {"title": title, "body": body, "format": "markdown"}
+        if public is not None:
+            payload["public"] = public
+        return self._data(
+            self._request(
+                "PUT", f"{self.base_url}/api/docs/{doc_id}", json_body=payload, write=True
+            )
+        )
+
+    def delete_doc(self, doc_id: int) -> dict:
+        return self._data(
+            self._request("DELETE", f"{self.base_url}/api/docs/{doc_id}", write=True)
+        )
+
+    # -- 评论 ---------------------------------------------------------------
+
+    def comments(self, doc_id: int) -> list[dict]:
+        return self._data(
+            self._request(
+                "GET",
+                f"{self.base_url}/api/comments",
+                params={"commentable_id": doc_id, "commentable_type": "Doc"},
+            )
+        )
+
+    def create_comment(self, *, doc_id: int, body: str) -> dict:
+        payload = {"commentable_id": doc_id, "commentable_type": "Doc", "body": body}
+        return self._data(
+            self._request(
+                "POST", f"{self.base_url}/api/comments", json_body=payload, write=True
+            )
+        )
+
+    def delete_comment(self, comment_id: int) -> dict:
+        return self._data(
+            self._request(
+                "DELETE", f"{self.base_url}/api/comments/{comment_id}", write=True
+            )
+        )
+
+    # -- URL → id 解析（抓 appData） ----------------------------------------
+
+    def doc_page_app_data(self, login: str, book: str, slug: str) -> dict:
+        html = self._request("GET", f"{self.base_url}/{login}/{book}/{slug}").text
+        return appdata.parse_app_data(html)
+
+    def resolve_book_id(self, login: str, book: str) -> int:
+        html = self._request("GET", f"{self.base_url}/{login}/{book}").text
+        return appdata.book_id(appdata.parse_app_data(html))
+
+    def resolve_doc_ids(self, login: str, book: str, slug: str) -> tuple[int, int]:
+        data = self.doc_page_app_data(login, book, slug)
+        return appdata.book_id(data), appdata.doc_id(data)

yuque_cli/config.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+DEFAULT_HOST = "www.yuque.com"
+
+
+def host() -> str:
+    return os.environ.get("YUQUE_HOST") or DEFAULT_HOST
+
+
+def base_url() -> str:
+    return f"https://{host()}"
+
+
+def config_dir() -> Path:
+    override = os.environ.get("YUQUE_CONFIG_DIR")
+    if override:
+        return Path(override)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "yuque-cli"
+
+
+def session_file() -> Path:
+    return config_dir() / "session.json"
+
+
+def no_color() -> bool:
+    return bool(os.environ.get("NO_COLOR"))

yuque_cli/errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+class YuqueError(Exception):
+    """yuque-cli 的运行期错误基类。"""
+
+
+class AuthExpired(YuqueError):
+    """登录态失效（HTTP 401）。"""
+
+
+class ApiError(YuqueError):
+    """内部接口返回非预期状态码。"""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code

yuque_cli/inputs.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TextIO
+
+
+class BodyInputError(ValueError):
+    """正文输入来源无效（互斥冲突或文件不可读）。"""
+
+
+def resolve_body(
+    body: str | None,
+    file: str | None,
+    *,
+    stdin: TextIO,
+    stdin_isatty: bool,
+) -> str | None:
+    """按 --body > --file(-=stdin) > 管道 stdin 的优先级解析正文。
+
+    在 TTY 下且未给任何来源时返回 None（由调用方决定是否必填）。
+    """
+    if body is not None and file is not None:
+        raise BodyInputError("--body 与 --file 互斥，只能给其一")
+    if body is not None:
+        return body
+    if file is not None:
+        if file == "-":
+            return stdin.read()
+        try:
+            return Path(file).read_text(encoding="utf-8")
+        except OSError as exc:
+            raise BodyInputError(f"无法读取文件 {file}：{exc}") from exc
+    if not stdin_isatty:
+        return stdin.read()
+    return None

yuque_cli/output.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def dumps(data: Any) -> str:
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def table(headers: list[str], rows: list[list[str]]) -> str:
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+    lines = ["  ".join(h.ljust(widths[i]) for i, h in enumerate(headers)).rstrip()]
+    for row in rows:
+        lines.append("  ".join(row[i].ljust(widths[i]) for i in range(len(headers))).rstrip())
+    return "\n".join(lines)
+
+
+def _first_line(text: str, limit: int = 60) -> str:
+    line = (text or "").splitlines()[0] if text else ""
+    return line if len(line) <= limit else line[: limit - 1] + "…"
+
+
+def render_user(u: dict) -> str:
+    fields = ["login", "name", "id", "email", "organization_login"]
+    return "\n".join(f"{k}: {u[k]}" for k in fields if k in u)
+
+
+def render_books(books: list[dict]) -> str:
+    rows = [
+        [
+            str(b.get("name", "")),
+            str(b.get("slug", "")),
+            str(b.get("items_count", "")),
+            "yes" if b.get("public") else "no",
+            str(b.get("id", "")),
+        ]
+        for b in books
+    ]
+    return table(["NAME", "SLUG", "DOCS", "PUBLIC", "ID"], rows)
+
+
+def render_docs(docs: list[dict]) -> str:
+    rows = [
+        [str(d.get("title", "")), str(d.get("slug", "")), str(d.get("id", ""))]
+        for d in docs
+    ]
+    return table(["TITLE", "SLUG", "ID"], rows)
+
+
+def render_comments(comments: list[dict]) -> str:
+    rows = [
+        [
+            str(c.get("id", "")),
+            str((c.get("user") or {}).get("name", "")),
+            _first_line(c.get("body", "")),
+        ]
+        for c in comments
+    ]
+    return table(["ID", "AUTHOR", "BODY"], rows)

yuque_cli/session.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+SESSION_COOKIE = "_yuque_session"
+CSRF_COOKIE = "yuque_ctoken"
+
+
+class SessionError(ValueError):
+    """会话缺失或无效（未登录、cookie 不含登录态等）。"""
+
+
+def parse_cookie_string(raw: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for part in raw.split(";"):
+        part = part.strip()
+        if not part or "=" not in part:
+            continue
+        key, value = part.split("=", 1)
+        key = key.strip()
+        if key:
+            out[key] = value.strip()
+    return out
+
+
+@dataclass(frozen=True)
+class Session:
+    cookies: dict[str, str]
+
+    @property
+    def cookie_header(self) -> str:
+        return "; ".join(f"{k}={v}" for k, v in self.cookies.items())
+
+    @property
+    def csrf_token(self) -> str | None:
+        return self.cookies.get(CSRF_COOKIE)
+
+    def require_session(self) -> None:
+        if SESSION_COOKIE not in self.cookies:
+            raise SessionError(
+                f"cookie 中缺少 {SESSION_COOKIE}（登录态）；请重新运行 yuque auth login"
+            )
+
+
+def from_cookie_string(raw: str) -> Session:
+    session = Session(parse_cookie_string(raw))
+    session.require_session()
+    return session
+
+
+def save(session: Session, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({"cookies": session.cookies}, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    path.chmod(0o600)
+
+
+def load(path: Path) -> Session:
+    if not path.exists():
+        raise SessionError("尚未登录；请先运行 yuque auth login")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return Session(dict(data["cookies"]))
+    except (ValueError, KeyError, TypeError) as exc:
+        raise SessionError(f"会话文件损坏：{path}（{exc}）") from exc

yuque_cli/urls.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+
+class UrlParseError(ValueError):
+    """输入无法解析成知识库（book）或文档（doc）地址。"""
+
+
+@dataclass(frozen=True)
+class BookRef:
+    login: str
+    book: str
+
+
+@dataclass(frozen=True)
+class DocRef:
+    login: str
+    book: str
+    slug: str
+
+    @property
+    def book_ref(self) -> BookRef:
+        return BookRef(self.login, self.book)
+
+
+def _segments(raw: str) -> list[str]:
+    s = raw.strip()
+    if not s:
+        return []
+    s = s.split("#", 1)[0].split("?", 1)[0]
+    if "://" in s:
+        path = urlsplit(s).path
+    else:
+        # 无 scheme 时可能是 "host/seg/..." 也可能是纯 "seg/seg..."。
+        # 语雀 login 不含点，故首段含 "." 即视为 host 并剥掉。
+        parts = s.split("/")
+        if "." in parts[0]:
+            parts = parts[1:]
+        path = "/".join(parts)
+    return [seg for seg in path.split("/") if seg]
+
+
+def parse_doc_ref(raw: str) -> DocRef:
+    segs = _segments(raw)
+    if len(segs) != 3:
+        raise UrlParseError(
+            f"文档地址应形如 {{login}}/{{book}}/{{slug}}（三段），得到：{raw!r}"
+        )
+    login, book, slug = segs
+    return DocRef(login=login, book=book, slug=slug)
+
+
+def parse_book_ref(raw: str) -> BookRef:
+    segs = _segments(raw)
+    if len(segs) < 2:
+        raise UrlParseError(
+            f"知识库地址应形如 {{login}}/{{book}}（两段），得到：{raw!r}"
+        )
+    if len(segs) > 3:
+        raise UrlParseError(f"地址段数过多，无法识别为知识库：{raw!r}")
+    return BookRef(login=segs[0], book=segs[1])

yuque_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: yuque-cli
+Version: 0.1.0
+Summary: 针对企业语雀实例的命令行客户端：cookie 认证，驱动内部 web 接口，提供文档与评论的 CRUD
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Requires-Dist: websocket-client>=1.9.0
+Description-Content-Type: text/markdown
+
+# yuque-cli
+
+面向语雀(含企业版)的通用命令行客户端:以浏览器 cookie 认证,驱动语雀内部 web 接口,提供文档(doc)与评论(comment)的增删改查。默认连接 `www.yuque.com`,企业实例用环境变量 `YUQUE_HOST` 指定。
+
+> 术语(知识库/文档/评论/login/namespace/slug)见 [CONTEXT.md](./CONTEXT.md);关键设计取舍见 [docs/adr](./docs/adr)。
+
+## 特性
+
+- **复用浏览器登录态**:默认探测本地 Chrome 远程调试(CDP)自动抓取 cookie,无需手动复制;失败可回退手动粘贴。
+- **干净的 Markdown 输出**:`doc get` 默认输出纯 Markdown,便于管道与落盘;`--json` 输出含 Lake 正文的完整详情。
+- **先取后合并的更新**:`doc update` 只改你指定的字段,其余保持原值。
+- **脚本友好**:全局 `--json` 输出原始 JSON,`-y` 跳过确认,正文支持 `--body`/`--file`/管道 stdin。
+
+## 安装
+
+需要 Python ≥ 3.10 与 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+uv sync                 # 安装依赖
+uv run yuque --help     # 在项目内运行
+```
+
+或作为工具安装,得到全局 `yuque` 命令:
+
+```bash
+uv tool install .
+yuque --help
+```
+
+## 快速开始
+
+```bash
+yuque auth login                       # 登录(自动 CDP,失败回退手动粘贴)
+yuque auth status                      # 查看当前身份
+yuque book list                        # 列出我的知识库
+yuque doc list  <login>/<book>         # 列出知识库下的文档
+yuque doc get   <login>/<book>/<slug>  # 取文档正文(Markdown)
+```
+
+`<login>/<book>/<slug>` 既可写成去掉 host 的路径形态,也可直接粘贴完整浏览器 URL(见 [URL 形态](#url-形态))。
+
+## 认证
+
+### 自动(CDP)
+
+`yuque auth login` 默认尝试从**你当前的 Chrome**(已登录目标语雀站点)直接抓取 cookie。前提是 Chrome 以远程调试端口启动:
+
+```bash
+# 完全退出 Chrome 后,带远程调试重新启动(默认 profile 即可),再登录你的语雀站点
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+```
+
+随后 `yuque auth login` 会自动连接、抓取目标站点的全部 cookie(含 `_yuque_session` 与 CSRF `yuque_ctoken`)并保存会话。
+
+### 手动
+
+未检测到远程调试、或自动抓取失败时,会提示粘贴 cookie;也可直接 `yuque auth login --manual` 跳过 CDP。cookie 取自浏览器 DevTools → Application → Cookies,或控制台 `document.cookie`。
+
+### 会话与退出
+
+- 会话保存在 `~/.config/yuque-cli/session.json`(权限 `0600`)。
+- `yuque auth logout` 清除本地会话。
+
+### 代理说明
+
+对语雀的 API 请求**默认直连,不读取 `*_proxy` 环境变量**(`trust_env=False`),避免请求被本地代理(如 Clash)拦截,也免去 SOCKS 代理触发 `socksio` 缺失的报错。如果你的网络必须经代理才能访问目标实例,需要移除该参数并引入 `httpx[socks]` 依赖。
+
+## 命令参考
+
+### 全局选项
+
+置于子命令之前,如 `yuque --json book list`。
+
+| 选项 | 说明 |
+| --- | --- |
+| `--json` | 输出原始 JSON(便于脚本解析) |
+| `-y`, `--yes` | 跳过所有确认(删除等危险操作) |
+| `-v`, `--verbose` | 打印内部 HTTP 请求到 stderr |
+| `-V`, `--version` | 显示版本 |
+
+### auth — 登录态管理
+
+| 命令 | 说明 |
+| --- | --- |
+| `auth login [--manual]` | 登录;默认探测 CDP 自动获取,`--manual` 直接手动粘贴 |
+| `auth status` | 显示当前登录身份(`GET /api/mine`) |
+| `auth logout` | 清除本地会话 |
+
+### book — 知识库
+
+| 命令 | 说明 |
+| --- | --- |
+| `book list` | 列出我的知识库(`GET /api/mine/books`) |
+
+### doc — 文档
+
+| 命令 | 说明 |
+| --- | --- |
+| `doc list <login>/<book>` | 列出知识库下的文档 |
+| `doc get <login>/<book>/<slug>` | 取正文;默认干净 Markdown,`--json` 出详情(含 Lake) |
+| `doc create <login>/<book> -t <标题> [选项]` | 在知识库中创建文档 |
+| `doc update <login>/<book>/<slug> [选项]` | 更新文档(先取后合并,未给的字段保持原值) |
+| `doc delete <login>/<book>/<slug>` | 删除文档(软删,可在回收站恢复) |
+
+`doc create` 选项:`-t/--title`(必填)、`--slug`(省略则自动生成)、`--public/--private`、`-b/--body`、`-F/--file`。
+
+`doc update` 选项:`-t/--title`、`--public/--private`、`-b/--body`、`-F/--file`;至少给其一,否则报错。
+
+可见性 `--public/--private`:不给则创建时继承知识库默认、更新时保持原值。
+
+```bash
+# 创建(内联正文)
+yuque doc create your-team/handbook -t "上手指南" --body "# 标题\n正文"
+
+# 从文件创建,并设为私有
+yuque doc create your-team/handbook -t "周报" -F report.md --private
+
+# 仅改标题(正文与可见性保持不变)
+yuque doc update your-team/handbook/getting-started -t "新标题"
+
+# 删除(非交互环境需 -y)
+yuque -y doc delete your-team/handbook/old-draft
+```
+
+### comment — 评论
+
+| 命令 | 说明 |
+| --- | --- |
+| `comment list <login>/<book>/<slug>` | 列出文档评论 |
+| `comment add <login>/<book>/<slug> [-b/--body \| -F/--file]` | 添加评论(正文不能为空) |
+| `comment delete <comment_id>` | 删除一条评论(id 取自 `comment list`) |
+
+## URL 形态
+
+凡接受文档/知识库地址的命令,既可用**完整浏览器 URL**,也可用**去掉 host 的路径形态**,二者等价:
+
+```
+https://<host>/<login>/<book>/<slug>   ←→   <login>/<book>/<slug>   (文档)
+https://<host>/<login>/<book>          ←→   <login>/<book>          (知识库)
+```
+
+数字 id 不属于用户语汇,仅内部解析时使用。
+
+## 正文输入
+
+`doc create` / `comment add` 的正文按以下优先级取值(`--body` 与 `--file` 互斥):
+
+1. `-b/--body`(内联字符串)
+2. `-F/--file`(从文件读;`-F -` 表示读 stdin)
+3. 管道 stdin(直接 `... | yuque doc create ...`)
+
+```bash
+echo "# 来自管道的正文" | yuque doc create your-team/handbook -t "标题"
+```
+
+`doc update` 略有不同:只有显式给 `-b/--body` 或 `-F/--file`(含 `-F -` 读 stdin)才会改正文;**裸管道不会被读取**——不给正文来源即表示保持原正文不变。
+
+## 环境变量
+
+| 变量 | 作用 | 默认 |
+| --- | --- | --- |
+| `YUQUE_HOST` | 目标语雀 host | `www.yuque.com` |
+| `YUQUE_CONFIG_DIR` | 配置/会话目录 | `$XDG_CONFIG_HOME/yuque-cli` 或 `~/.config/yuque-cli` |
+| `XDG_CONFIG_HOME` | 配置根目录 | `~/.config` |
+| `NO_COLOR` | 设置后禁用彩色输出 | — |
+
+## 开发
+
+本项目遵循 TDD,并用 [mise](https://mise.jdx.dev/) 管理工具链(锁定 uv)与常用任务。
+
+```bash
+mise run deps     # 安装依赖(uv sync)
+mise run test     # 运行测试(pytest)
+mise run lint     # ruff check && ruff format
+mise run check    # ty 类型检查
+mise run cli -- --help   # 运行 CLI(-- 之后为 yuque 的参数)
+```
+
+- 源码:`src/yuque_cli/`;测试:`test/`。
+- 设计文档:术语表 [CONTEXT.md](./CONTEXT.md)、决策记录 [docs/adr](./docs/adr)、内部接口速查 [docs/internal-api.md](./docs/internal-api.md)。

yuque_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+yuque_cli/__init__.py,sha256=E7Y2P7b8OYtteFYpw4lSixsqfYPPORhyw3S2sV0O7fA,74
+yuque_cli/__main__.py,sha256=Qd-f8z2Q2vpiEP2x6PBFsJrpACWDVxFKQk820MhFmHo,59
+yuque_cli/appdata.py,sha256=OCpcFbn1_tpLa8xP9knKx724tWu93BedIijqaGBOJM4,1328
+yuque_cli/auth.py,sha256=PGp_y_M-fmATK447w3NyJ2HL6jOkkcUxsdQLXJ-wKjw,5393
+yuque_cli/cli.py,sha256=Y5QGMY2sEGZ00DhUKUaVSUcw0Svp8R_UNrGhvA_tdkc,13007
+yuque_cli/client.py,sha256=LSvSUAtcThzlZ_YSrHjIe5PUQt9ndj5tAGLKYSO5gk0,6534
+yuque_cli/config.py,sha256=yoeFuC26KjaxGwDr3TrTCQvtqimIZ9NRXvhNmJm0yj0,633
+yuque_cli/errors.py,sha256=P0PJ6ZrdxQUStDVEE9drygFzTGm76CoTlI7rYJptoU0,425
+yuque_cli/inputs.py,sha256=YhyRxZLuVZ17v1ZIYruBSh9-1ayY35brdpfdH0a5Aro,1004
+yuque_cli/output.py,sha256=rsPjt_JGZMONcSFEysSE8tFdqBiAD-q26ti31RLps30,1828
+yuque_cli/session.py,sha256=Aw2Xgbs6Oh3a4zvRb1PMzDONor1-CA3LtOayMk64qgo,1921
+yuque_cli/urls.py,sha256=iiMW2nI_k4ycJxOt_DlV0_Q7XHx94nZfnY1ParjH9UM,1678
+yuque_cli-0.1.0.dist-info/METADATA,sha256=1Kt63WVNkneeJF2TYIx4SXzgC7Fu317Qqm88870wUs0,7340
+yuque_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+yuque_cli-0.1.0.dist-info/entry_points.txt,sha256=wAmlUjwsHdCdBpdv0baZSO1v_vVbpe4940swfNb7zIM,44
+yuque_cli-0.1.0.dist-info/RECORD,,

yuque_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

yuque_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yuque = yuque_cli.cli:app