yuque-cli 0.1.1__tar.gz → 1.0.0__tar.gz

yuque_cli-1.0.0/.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "EDIT|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if git diff --name-only HEAD 2>/dev/null | grep -q '^src/\\|^pyproject.toml'; then current=$(grep '^version = ' pyproject.toml | head -1 | sed 's/version = \"\\(.*\\)\"/\\1/'); IFS='.' read -r major minor patch <<< \"$current\"; new=\"$major.$minor.$((patch + 1))\"; sed -i '' \"s/^version = \\\".*\\\"/version = \\\"$new\\\"/\" pyproject.toml && echo \"[版本升级] $current → $new (patch)\"; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yuque-cli
-Version: 0.1.1
+Version: 1.0.0
 Summary: 针对语雀的命令行客户端：cookie 认证，驱动内部 web 接口，提供文档与评论的 CRUD
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
@@ -101,12 +101,12 @@ yuque -y doc delete team/handbook/old-draft
 | 命令 | 说明 |
 | --- | --- |
 | `comment list <space>/<repo>/<slug>` | 列出评论 |
-| `comment add <space>/<repo>/<slug> [-b/--body \| -F/--file]` | 添加评论 |
+| `comment create <space>/<repo>/<slug> [-b/--body \| -F/--file]` | 添加评论 |
 | `comment delete <comment_id>` | 删除评论 |
 
 ## 正文输入
 
-`doc create` / `comment add` 正文来源（`--body` 与 `--file` 互斥）：
+`doc create` / `comment create` 正文来源（`--body` 与 `--file` 互斥）：
 
 1. `-b/--body` 内联字符串
 2. `-F/--file` 从文件读（`-F -` 读 stdin）

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/README.md

@@ -91,12 +91,12 @@ yuque -y doc delete team/handbook/old-draft
 | 命令 | 说明 |
 | --- | --- |
 | `comment list <space>/<repo>/<slug>` | 列出评论 |
-| `comment add <space>/<repo>/<slug> [-b/--body \| -F/--file]` | 添加评论 |
+| `comment create <space>/<repo>/<slug> [-b/--body \| -F/--file]` | 添加评论 |
 | `comment delete <comment_id>` | 删除评论 |
 
 ## 正文输入
 
-`doc create` / `comment add` 正文来源（`--body` 与 `--file` 互斥）：
+`doc create` / `comment create` 正文来源（`--body` 与 `--file` 互斥）：
 
 1. `-b/--body` 内联字符串
 2. `-F/--file` 从文件读（`-F -` 读 stdin）

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "yuque-cli"
-version = "0.1.1"
+version = "1.0.0"
 description = "针对语雀的命令行客户端：cookie 认证，驱动内部 web 接口，提供文档与评论的 CRUD"
 readme = "README.md"
 requires-python = ">=3.10"

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/src/yuque_cli/cli.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+import json
+import subprocess
 import sys
+import time
 from contextlib import contextmanager
 from dataclasses import dataclass
 from typing import Annotated, Any, Callable, Optional
@@ -12,7 +15,7 @@ from . import __version__, auth, config, output, session
 from .appdata import AppDataError
 from .appdata import repo_id as appdata_repo_id
 from .appdata import doc_id as appdata_doc_id
-from .client import Client
+from .client import Client, _extract_paragraphs
 from .errors import AuthExpired, YuqueError
 from .inputs import BodyInputError, resolve_body
 from .session import SessionError
@@ -83,7 +86,7 @@ def cli_errors():
         raise typer.Exit(1)
 
 
-def build_client(state: AppState) -> Client:
+def build_client(state: AppState, host_hint: str | None = None) -> Client:
     sess = session.load(config.session_file())
     hooks: dict[str, list[Callable[..., Any]]] = {}
     if state.verbose:
@@ -96,11 +99,20 @@ def build_client(state: AppState) -> Client:
     # 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(state.host))
+    # --host 显式指定优先；否则从 URL 提取的 host 作为 fallback
+    return Client(http, sess, base_url=config.base_url(state.host or host_hint))
+
+
+def _pager(text: str) -> None:
+    """当 stdout 是终端时通过 less 分页显示，否则直接输出。"""
+    if sys.stdout.isatty():
+        subprocess.run(["less", "-FRX"], input=text, text=True)
+    else:
+        typer.echo(text)
 
 
 def _emit(state: AppState, data, human: str) -> None:
-    typer.echo(output.dumps(data) if state.json else human)
+    _pager(output.dumps(data) if state.json else human)
 
 
 def _confirm(state: AppState, message: str) -> None:
@@ -125,8 +137,10 @@ def _resolve_repo_ref(
     if not has_url and not has_opts:
         raise YuqueError("请提供 URL 或指定 --space 和 --repo")
     if has_url:
+        assert url is not None
         return parse_repo_ref(url)
-    return RepoRef(space=space, repo=repo)  # type: ignore[arg-type]
+    assert space is not None and repo is not None
+    return RepoRef(space=space, repo=repo)
 
 
 def _resolve_doc_ref(
@@ -164,40 +178,100 @@ def _prompt_cookie() -> str:
     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 完成登录。"
-)
+_CDP_URL = "chrome://inspect/#remote-debugging"
+
+
+def _open_cdp_hint() -> None:
+    """在 Chrome 中打开远程调试说明页面。"""
+    import platform
+    if platform.system() == "Darwin":
+        subprocess.run(["open", "-a", "Google Chrome", _CDP_URL], check=False)
+    elif platform.system() == "Windows":
+        subprocess.run(["start", "", _CDP_URL], shell=True, check=False)
+    else:
+        subprocess.run(["google-chrome", _CDP_URL], check=False)
+
+
+_CDP_DONE_MSG = "建议及时关闭 Chrome 远程调试端口，避免安全风险"
+
+
+def _try_cdp_login(base: str, state: AppState) -> dict:
+    """尝试 CDP 获取 cookie；失败后打开浏览器并持续轮询直至成功。"""
+    # 首次尝试：可能已经开启
+    ws_url = auth.cdp_websocket_url(verbose=state.verbose)
+    if ws_url:
+        try:
+            cookies = auth.cookies_via_cdp(base, ws_url)
+        except auth.CdpUnavailable:
+            pass
+        else:
+            host = state.host or config.host()
+            typer.secho(f"已通过 CDP 从浏览器获取 {host} 登录态", fg="green", err=True)
+            typer.secho(_CDP_DONE_MSG, fg="yellow", err=True)
+            return cookies
+
+    # 打开浏览器引导开启远程调试
+    _open_cdp_hint()
+    typer.secho(
+        f"等待 Chrome 远程调试开启（{_CDP_URL}），Ctrl+C 可中断...",
+        fg="yellow", err=True,
+    )
+
+    # 轮询直至成功
+    spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+    tick = 0
+    try:
+        while True:
+            # 用 spinner 替代 sleep，视觉上不卡死
+            for _ in range(10):
+                char = spinner[tick % len(spinner)]
+                sys.stderr.write(f"\r  {char} 等待 Chrome 远程调试...")
+                sys.stderr.flush()
+                time.sleep(0.2)
+                tick += 1
+            ws_url = auth.cdp_websocket_url(verbose=state.verbose)
+            if ws_url is None:
+                continue
+            try:
+                cookies = auth.cookies_via_cdp(base, ws_url)
+                sys.stderr.write("\r" + " " * 40 + "\r")
+                sys.stderr.flush()
+                host = state.host or config.host()
+                typer.secho(f"已通过 CDP 从浏览器获取 {host} 登录态", fg="green", err=True)
+                typer.secho(_CDP_DONE_MSG, fg="yellow", err=True)
+                return cookies
+            except auth.CdpUnavailable:
+                continue
+    except KeyboardInterrupt:
+        sys.stderr.write("\r" + " " * 40 + "\r")
+        sys.stderr.flush()
+        raise
 
 
 @auth_app.command("login")
 def auth_login(
     ctx: typer.Context,
     manual: Annotated[
-        bool, typer.Option("--manual", help="跳过 CDP，直接手动粘贴 cookie")
+        bool, typer.Option("--manual", help="跳过 CDP，交互式粘贴 cookie")
     ] = False,
+    cookie: Annotated[
+        Optional[str], typer.Option("--cookie", help="直接提供 cookie 串完成登录")
+    ] = None,
 ) -> None:
-    """登录：默认探测本地 CDP 自动获取登录态；未启用或失败时回退手动粘贴。"""
+    """登录：默认探测本地 CDP 自动获取登录态；也可用 --cookie 或 --manual 手动登录。"""
     with cli_errors():
         state: AppState = ctx.obj
         base = config.base_url(state.host)
-        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)
+        if cookie is not None:
+            cookies = auth.cookies_via_manual(lambda: cookie)
+        elif manual:
             cookies = auth.cookies_via_manual(_prompt_cookie)
         else:
             try:
-                cookies = auth.cookies_via_cdp(base, ws_url)
-                typer.secho(
-                    f"已通过 CDP 从浏览器获取 {state.host or 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)
+                cookies = _try_cdp_login(base, state)
+            except KeyboardInterrupt:
+                typer.echo("", err=True)
+                raise typer.Exit(1)
         sess = session.Session(cookies)
         sess.require_session()
         session.save(sess, config.session_file())
@@ -236,6 +310,26 @@ def repo_list(ctx: typer.Context) -> None:
         _emit(state, repos, output.render_repos(repos))
 
 
+@repo_app.command("get")
+def repo_get(
+    ctx: typer.Context,
+    url: UrlArg = None,
+    space: SpaceOpt = None,
+    repo: RepoOpt = None,
+) -> None:
+    """获取指定知识库的信息（GET /api/books/{id}/overview）。"""
+    state: AppState = ctx.obj
+    with cli_errors():
+        ref = _resolve_repo_ref(url, space, repo)
+        client = build_client(state, host_hint=ref.host)
+        repo_id = client.resolve_repo_id(ref.space, ref.repo)
+        data = client.repo_overview(repo_id)
+        docs = client.repo_docs(repo_id)
+        if state.json:
+            data["docs"] = docs
+        _emit(state, data, output.render_repo_overview(data, docs))
+
+
 # -- doc --------------------------------------------------------------------
 
 UrlArg = Annotated[Optional[str], typer.Argument(help="目标 URL 或去 host 的路径形态")]
@@ -256,8 +350,9 @@ def doc_list(ctx: typer.Context, url: UrlArg) -> None:
     """列出知识库下的文档。"""
     state: AppState = ctx.obj
     with cli_errors():
+        assert url is not None
         ref = parse_repo_ref(url)
-        client = build_client(state)
+        client = build_client(state, host_hint=ref.host)
         repo_id = client.resolve_repo_id(ref.space, ref.repo)
         docs = client.repo_docs(repo_id)
         _emit(state, docs, output.render_docs(docs))
@@ -265,15 +360,28 @@ def doc_list(ctx: typer.Context, url: UrlArg) -> None:
 
 @doc_app.command("get")
 def doc_get(ctx: typer.Context, url: UrlArg) -> None:
-    """取文档正文：默认干净 Markdown；--json 出详情（含 Lake）。"""
+    """取文档正文：默认干净 Markdown；--json 出详情（含段落结构）。"""
     state: AppState = ctx.obj
     with cli_errors():
+        assert url is not None
         ref = parse_doc_ref(url)
-        client = build_client(state)
+        client = build_client(state, host_hint=ref.host)
         if state.json:
             app_data = client.doc_page_app_data(ref.space, ref.repo, ref.slug)
             detail = client.doc_detail(ref.slug, appdata_repo_id(app_data))
-            typer.echo(output.dumps(detail))
+            doc_meta = app_data.get("doc", {})
+            book_meta = app_data.get("book", {})
+            lake_body = detail.get("content") or detail.get("body_asl") or detail.get("body", "")
+            combined = {
+                "doc": detail,
+                "doc_version_id": doc_meta.get("doc_version_id"),
+                "book": {
+                    "id": book_meta.get("id") or appdata_repo_id(app_data),
+                    "slug": ref.repo,
+                },
+                "paragraphs": _extract_paragraphs(lake_body) if lake_body else [],
+            }
+            typer.echo(output.dumps(combined))
         else:
             typer.echo(client.doc_markdown(ref.space, ref.repo, ref.slug))
 
@@ -297,13 +405,13 @@ def doc_create(
             raise YuqueError("--title 为必填项")
         ref = _resolve_repo_ref(url, space, repo)
         text = _read_body(body, file)
-        client = build_client(state)
+        client = build_client(state, host_hint=ref.host)
         repo_id = client.resolve_repo_id(ref.space, ref.repo)
         pub = None if public is None else (1 if public else 0)
         created = client.create_doc(
             repo_id=repo_id, title=title, body=text, slug=slug, public=pub
         )
-        url_out = f"{config.base_url(state.host)}/{ref.space}/{ref.repo}/{created.get('slug', '')}"
+        url_out = f"{config.base_url(state.host or ref.host)}/{ref.space}/{ref.repo}/{created.get('slug', '')}"
         _emit(state, created, f"已创建：{url_out}")
 
 
@@ -326,7 +434,7 @@ def doc_update(
                 "没有要更新的字段（至少给 --title / 正文 / --public|--private 之一）"
             )
         ref = _resolve_doc_ref(url, space, repo)
-        client = build_client(state)
+        client = build_client(state, host_hint=ref.host)
         app_data = client.doc_page_app_data(ref.space, ref.repo, ref.slug)
         doc_id = appdata_doc_id(app_data)
         meta = app_data.get("doc", {})
@@ -339,7 +447,7 @@ def doc_update(
         updated = client.update_doc(
             doc_id=doc_id, title=new_title, body=new_body, public=new_public
         )
-        url_out = f"{config.base_url(state.host)}/{ref.space}/{ref.repo}/{ref.slug}"
+        url_out = f"{config.base_url(state.host or ref.host)}/{ref.space}/{ref.repo}/{ref.slug}"
         _emit(state, updated, f"已更新：{url_out}")
 
 
@@ -348,8 +456,9 @@ def doc_delete(ctx: typer.Context, url: UrlArg) -> None:
     """删除文档（软删，可在回收站恢复）。"""
     state: AppState = ctx.obj
     with cli_errors():
+        assert url is not None
         ref = parse_doc_ref(url)
-        client = build_client(state)
+        client = build_client(state, host_hint=ref.host)
         app_data = client.doc_page_app_data(ref.space, ref.repo, ref.slug)
         doc_id = appdata_doc_id(app_data)
         title = app_data.get("doc", {}).get("title", ref.slug)
@@ -366,27 +475,46 @@ def comment_list(ctx: typer.Context, url: UrlArg) -> None:
     """列出文档的评论。"""
     state: AppState = ctx.obj
     with cli_errors():
+        assert url is not None
         ref = parse_doc_ref(url)
-        client = build_client(state)
+        client = build_client(state, host_hint=ref.host)
         _, doc_id = client.resolve_doc_ids(ref.space, ref.repo, 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
+SelectionOpt = Annotated[
+    Optional[str],
+    typer.Option("--selection", "-s", help="划词评论的 selection JSON（如提供则为划词评论）"),
+]
+
+
+@comment_app.command("create")
+def comment_create(
+    ctx: typer.Context,
+    url: UrlArg,
+    body: BodyOpt = None,
+    file: FileOpt = None,
+    selection: SelectionOpt = None,
 ) -> None:
-    """给文档添加评论。"""
+    """给文档添加评论。带 --selection 时为划词评论。"""
     state: AppState = ctx.obj
     with cli_errors():
+        assert url is not None
         ref = parse_doc_ref(url)
         text = _read_body(body, file)
         if not text:
             raise YuqueError("评论正文不能为空（用 --body 或 --file/-）")
-        client = build_client(state)
+        client = build_client(state, host_hint=ref.host)
         _, doc_id = client.resolve_doc_ids(ref.space, ref.repo, ref.slug)
-        created = client.create_comment(doc_id=doc_id, body=text)
+        if selection is not None:
+            try:
+                sel = json.loads(selection)
+            except json.JSONDecodeError as exc:
+                raise YuqueError(f"--selection JSON 解析失败：{exc}") from exc
+            created = client.create_comment(doc_id=doc_id, body=text, selection=sel)
+        else:
+            created = client.create_comment(doc_id=doc_id, body=text)
         _emit(state, created, f"已评论（id={created.get('id', '')}）")
 
 

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/src/yuque_cli/client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import secrets
 from typing import Any
 
 import httpx
@@ -14,6 +15,63 @@ USER_AGENT = (
 )
 
 
+def _random_id() -> str:
+    return "u" + secrets.token_hex(4)
+
+
+def _random_hash() -> str:
+    return secrets.token_hex(32)
+
+
+def _build_body_asl(text: str) -> tuple[str, str, str]:
+    pid = _random_id()
+    sid = _random_id()
+    h = _random_hash()
+    body_asl = (
+        '<!doctype lake>'
+        '<meta name="doc-version" content="1" />'
+        '<meta name="viewport" content="adapt" />'
+        f'<p data-lake-id="{pid}" id="{pid}">'
+        f'<span data-lake-id="{sid}" id="{sid}">{text}</span>'
+        f'</p>'
+        f'<!{h}>'
+    )
+    return body_asl, pid, sid
+
+
+def _build_body(text: str, pid: str, sid: str) -> str:
+    return (
+        '<div class="lake-content" typography="traditional">'
+        f'<p id="{pid}" class="ne-p">'
+        f'<span class="ne-text">{text}</span>'
+        f'</p>'
+        f'</div>'
+    )
+
+
+def _html_to_text(html: str) -> str:
+    import re
+
+    text = re.sub(r"<[^>]+>", "", html or "")
+    text = text.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
+    return text
+
+
+def _extract_paragraphs(html: str) -> list[dict]:
+    import re
+
+    paras: list[dict] = []
+    for pm in re.finditer(r'<p[^>]*\s+id="([^"]*)"[^>]*>(.*?)</p>', html, re.DOTALL):
+        pid = pm.group(1)
+        raw = pm.group(2)
+        text = _html_to_text(raw)
+        spans: list[dict] = []
+        for sm in re.finditer(r'<span[^>]*\s+id="([^"]*)"[^>]*>(.*?)</span>', raw, re.DOTALL):
+            spans.append({"id": sm.group(1), "text": _html_to_text(sm.group(2))})
+        paras.append({"id": pid, "text": text, "spans": spans})
+    return paras
+
+
 class Client:
     """语雀内部 web API 客户端。注入 httpx.Client 与 Session 以便测试。"""
 
@@ -92,11 +150,27 @@ class Client:
         """用户所属的组织/团队列表（GET /api/mine/group_quick_links）。"""
         return self._data(self._request("GET", f"{self.base_url}/api/mine/group_quick_links"))
 
-    def repo_docs(self, repo_id: int) -> list[dict]:
+    def repo_overview(self, repo_id: int) -> dict:
         return self._data(
-            self._request("GET", f"{self.base_url}/api/books/{repo_id}/docs")
+            self._request("GET", f"{self.base_url}/api/books/{repo_id}/overview")
         )
 
+    def repo_docs(self, repo_id: int) -> list[dict]:
+        all_docs: list[dict] = []
+        offset = 0
+        while True:
+            page = self._data(
+                self._request(
+                    "GET", f"{self.base_url}/api/docs",
+                    params={"book_id": repo_id, "offset": offset}
+                )
+            )
+            if not page:
+                break
+            all_docs.extend(page)
+            offset += len(page)
+        return all_docs
+
     # -- 文档 ---------------------------------------------------------------
 
     def doc_markdown(self, space: str, repo: str, slug: str) -> str:
@@ -173,8 +247,19 @@ class Client:
             )
         )
 
-    def create_comment(self, *, doc_id: int, body: str) -> dict:
-        payload = {"commentable_id": doc_id, "commentable_type": "Doc", "body": body}
+    def create_comment(self, *, doc_id: int, body: str, selection: dict | None = None) -> dict:
+        payload: dict[str, Any] = {
+            "commentable_id": doc_id,
+            "commentable_type": "Doc",
+            "body": body,
+        }
+        if selection is not None:
+            body_asl, pid, sid = _build_body_asl(body)
+            payload["type"] = "WORDING_COMMENT"
+            payload["format"] = "lake"
+            payload["body_asl"] = body_asl
+            payload["body"] = _build_body(body, pid, sid)
+            payload["selection"] = selection
         return self._data(
             self._request(
                 "POST", f"{self.base_url}/api/comments", json_body=payload, write=True

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/src/yuque_cli/output.py

@@ -63,16 +63,56 @@ def render_docs(docs: list[dict]) -> str:
     return table(["TITLE", "SLUG", "ID"], rows)
 
 
+def _strip_html(html: str) -> str:
+    """提取 HTML 中的纯文本。"""
+    import re
+
+    text = re.sub(r"<[^>]+>", "", html or "")
+    text = text.replace("&lt;", "<").replace("&gt;", ">").replace("&amp;", "&")
+    return text.strip()
+
+
 def render_comments(comments: list[dict]) -> str:
     rows = [
         [
             str(c.get("id", "")),
             str((c.get("user") or {}).get("name", "")),
-            _first_line(c.get("body", "")),
+            "划词" if c.get("type") == "WORDING_COMMENT" else "正文",
+            _first_line(
+                _strip_html(c.get("body", ""))
+                if c.get("type") == "WORDING_COMMENT"
+                else (c.get("body", "") or "")
+            ),
         ]
         for c in comments
     ]
-    return table(["ID", "AUTHOR", "BODY"], rows)
+    return table(["ID", "AUTHOR", "TYPE", "BODY"], rows)
+
+
+def render_repo_overview(data: dict, docs: list[dict] | None = None) -> str:
+    """通用渲染：按 key 逐行展示，遇到 dict 取其 name/login/id，其它值直接展示。"""
+    _SKIP_KEYS = {"enableCustomBody", "enableCatalog", "order", "layout", "customIndex", "enableUserFeed"}
+    lines: list[str] = []
+    for key, val in data.items():
+        if key in _SKIP_KEYS:
+            continue
+        if isinstance(val, dict):
+            val = val.get("name") or val.get("login") or val.get("id") or json.dumps(val, ensure_ascii=False)
+        elif isinstance(val, list):
+            if val and isinstance(val[0], dict):
+                val = ", ".join(v.get("name") or str(v) for v in val)
+            else:
+                val = ", ".join(str(v) for v in val)
+        elif isinstance(val, bool):
+            val = "yes" if val else "no"
+        elif val is None:
+            val = ""
+        lines.append(f"{key}: {val}")
+    if docs:
+        lines.append("")
+        lines.append(f"文档数量: {len(docs)}")
+        lines.append(render_docs(docs))
+    return "\n".join(lines)
 
 
 def render_spaces(spaces: list[dict]) -> str:

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/src/yuque_cli/urls.py

@@ -12,6 +12,7 @@ class UrlParseError(ValueError):
 class RepoRef:
     space: str
     repo: str
+    host: str | None = None
 
 
 @dataclass(frozen=True)
@@ -19,10 +20,11 @@ class DocRef:
     space: str
     repo: str
     slug: str
+    host: str | None = None
 
     @property
     def repo_ref(self) -> RepoRef:
-        return RepoRef(self.space, self.repo)
+        return RepoRef(self.space, self.repo, host=self.host)
 
 
 def _segments(raw: str) -> list[str]:
@@ -42,14 +44,28 @@ def _segments(raw: str) -> list[str]:
     return [seg for seg in path.split("/") if seg]
 
 
+def extract_host(raw: str) -> str | None:
+    """从完整 URL 或带 host 的路径中提取 host；无法识别时返回 None。"""
+    s = raw.strip()
+    if not s:
+        return None
+    if "://" in s:
+        return urlsplit(s).hostname
+    # 无 scheme：首段含 "." 即视为 host
+    parts = s.split("/")
+    if parts and "." in parts[0]:
+        return parts[0]
+    return None
+
+
 def parse_doc_ref(raw: str) -> DocRef:
     segs = _segments(raw)
-    if len(segs) != 3:
+    if len(segs) < 3:
         raise UrlParseError(
             f"文档地址应形如 {{space}}/{{repo}}/{{slug}}（三段），得到：{raw!r}"
         )
-    space, repo, slug = segs
-    return DocRef(space=space, repo=repo, slug=slug)
+    space, repo, slug = segs[:3]
+    return DocRef(space=space, repo=repo, slug=slug, host=extract_host(raw))
 
 
 def parse_repo_ref(raw: str) -> RepoRef:
@@ -60,4 +76,4 @@ def parse_repo_ref(raw: str) -> RepoRef:
         )
     if len(segs) > 3:
         raise UrlParseError(f"地址段数过多，无法识别为知识库：{raw!r}")
-    return RepoRef(space=segs[0], repo=segs[1])
+    return RepoRef(space=segs[0], repo=segs[1], host=extract_host(raw))

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/test/test_cli.py

@@ -32,14 +32,14 @@ class FakeClient:
         self._rec("groups")
         return [
             {
-                "id": 5969528134,
-                "title": "跨境支付技术中心",
-                "target": {"id": 42434150, "login": "pmw77l", "name": "跨境支付技术中心"},
+                "id": 100001,
+                "title": "Team A",
+                "target": {"id": 200001, "login": "user_a", "name": "Team A"},
             },
             {
-                "id": 5973455253,
-                "title": "PayKKa",
-                "target": {"id": 59898319, "login": "gg87x1", "name": "PayKKa Global"},
+                "id": 100002,
+                "title": "Project B",
+                "target": {"id": 200002, "login": "user_b", "name": "Project B"},
             },
         ]
 
@@ -47,6 +47,10 @@ class FakeClient:
         self._rec("resolve_repo_id", space, repo)
         return 77
 
+    def repo_overview(self, repo_id):
+        self._rec("repo_overview", repo_id)
+        return {"name": "B", "slug": "bk", "id": 77, "description": "desc", "public": 1, "items_count": 2}
+
     def repo_docs(self, repo_id):
         self._rec("repo_docs", repo_id)
         return [{"title": "D", "slug": "d", "id": 88}]
@@ -95,7 +99,7 @@ class FakeClient:
 @pytest.fixture
 def fake(monkeypatch):
     fc = FakeClient()
-    monkeypatch.setattr(cli, "build_client", lambda state: fc)
+    monkeypatch.setattr(cli, "build_client", lambda state, host_hint=None: fc)
     return fc
 
 
@@ -158,29 +162,18 @@ class TestAuth:
         assert "CDP" in result.output
         assert (tmp_path / "session.json").exists()
 
-    def test_login_cdp_disabled_shows_hint_then_manual(self, monkeypatch, tmp_path):
+    def test_login_with_cookie_option(self, monkeypatch, tmp_path):
         monkeypatch.setenv("YUQUE_CONFIG_DIR", str(tmp_path))
-        monkeypatch.setattr(cli.auth, "cdp_websocket_url", lambda **kw: None)
-        monkeypatch.setattr(cli, "_prompt_cookie", lambda: f"{SESSION_COOKIE}=x")
-        result = runner.invoke(cli.app, ["auth", "login"])
-        assert result.exit_code == 0
-        assert "--remote-debugging-port" in result.output
-        assert (tmp_path / "session.json").exists()
 
-    def test_login_cdp_connected_but_fails_falls_back_to_manual(
-        self, monkeypatch, tmp_path
-    ):
-        monkeypatch.setenv("YUQUE_CONFIG_DIR", str(tmp_path))
-        monkeypatch.setattr(cli.auth, "cdp_websocket_url", lambda **kw: "ws://b")
-
-        def boom(base, ws):
-            raise cli.auth.CdpUnavailable("无目标站点登录态")
+        def no_prompt():  # pragma: no cover - must not be called
+            raise AssertionError("should not prompt when --cookie is used")
 
-        monkeypatch.setattr(cli.auth, "cookies_via_cdp", boom)
-        monkeypatch.setattr(cli, "_prompt_cookie", lambda: f"{SESSION_COOKIE}=x")
-        result = runner.invoke(cli.app, ["auth", "login"])
+        monkeypatch.setattr(cli, "_prompt_cookie", no_prompt)
+        result = runner.invoke(
+            cli.app, ["auth", "login", "--cookie", f"{SESSION_COOKIE}=x; ct=t"]
+        )
         assert result.exit_code == 0
-        assert "获取失败" in result.output
+        assert "已登录" in result.output
         assert (tmp_path / "session.json").exists()
 
     def test_logout_removes_session(self, monkeypatch, tmp_path):
@@ -206,6 +199,33 @@ class TestRepo:
         result = runner.invoke(cli.app, ["--json", "repo", "list"])
         assert '"slug": "bk"' in result.output
 
+    def test_get_human(self, fake):
+        result = runner.invoke(cli.app, ["repo", "get", "lg/bk"])
+        assert result.exit_code == 0
+        assert "name: B" in result.output
+        assert "slug: bk" in result.output
+        assert "D" in result.output
+        assert calls(fake, "resolve_repo_id") == [("resolve_repo_id", "lg", "bk")]
+        assert calls(fake, "repo_overview") == [("repo_overview", 77)]
+        assert calls(fake, "repo_docs") == [("repo_docs", 77)]
+
+    def test_get_json(self, fake):
+        result = runner.invoke(cli.app, ["--json", "repo", "get", "lg/bk"])
+        assert result.exit_code == 0
+        assert '"name": "B"' in result.output
+        assert '"slug": "bk"' in result.output
+        assert '"docs"' in result.output
+        assert '"title": "D"' in result.output
+
+    def test_get_with_space_book_opts(self, fake):
+        result = runner.invoke(cli.app, ["repo", "get", "--space", "lg", "--repo", "bk"])
+        assert result.exit_code == 0
+        assert "name: B" in result.output
+        assert "D" in result.output
+        assert calls(fake, "resolve_repo_id") == [("resolve_repo_id", "lg", "bk")]
+        assert calls(fake, "repo_overview") == [("repo_overview", 77)]
+        assert calls(fake, "repo_docs") == [("repo_docs", 77)]
+
 
 class TestDoc:
     def test_list(self, fake):
@@ -222,6 +242,9 @@ class TestDoc:
     def test_get_json_detail(self, fake):
         result = runner.invoke(cli.app, ["--json", "doc", "get", "lg/bk/sl"])
         assert '"body": "<lake>"' in result.output
+        assert '"doc_version_id"' in result.output
+        assert '"book"' in result.output
+        assert '"paragraphs"' in result.output
         assert calls(fake, "doc_detail") == [("doc_detail", "sl", 77)]
 
     def test_create_inline_body(self, fake):
@@ -351,16 +374,43 @@ class TestComment:
 
     def test_add(self, fake):
         result = runner.invoke(
-            cli.app, ["comment", "add", "lg/bk/sl", "--body", "nice"]
+            cli.app, ["comment", "create", "lg/bk/sl", "--body", "nice"]
         )
         assert "已评论" in result.output
         assert calls(fake, "create_comment")[0][1] == {"doc_id": 88, "body": "nice"}
 
     def test_add_empty_body_errors(self, fake):
-        result = runner.invoke(cli.app, ["comment", "add", "lg/bk/sl"])
+        result = runner.invoke(cli.app, ["comment", "create", "lg/bk/sl"])
         assert result.exit_code == 1
         assert "评论正文不能为空" in result.output
 
+    def test_add_with_selection(self, fake):
+        sel = '{"paragraph_id":"u-pid","text":"hello","text_offset":0,"selection_range":{"start":{"id":"u-eid","text":"hello","offset":0,"paragraphId":"u-pid","paragraphOffset":0},"end":{"id":"u-eid","text":"hello","offset":3,"paragraphId":"u-pid","paragraphOffset":3}},"doc_version_id":123}'
+        result = runner.invoke(
+            cli.app, ["comment", "create", "lg/bk/sl", "--body", "nice", "--selection", sel]
+        )
+        assert "已评论" in result.output
+        kw = calls(fake, "create_comment")[0][1]
+        assert kw["doc_id"] == 88
+        assert kw["body"] == "nice"
+        assert kw["selection"] == {
+            "paragraph_id": "u-pid",
+            "text": "hello",
+            "text_offset": 0,
+            "selection_range": {
+                "start": {"id": "u-eid", "text": "hello", "offset": 0, "paragraphId": "u-pid", "paragraphOffset": 0},
+                "end": {"id": "u-eid", "text": "hello", "offset": 3, "paragraphId": "u-pid", "paragraphOffset": 3},
+            },
+            "doc_version_id": 123,
+        }
+
+    def test_add_with_selection_invalid_json_errors(self, fake):
+        result = runner.invoke(
+            cli.app, ["comment", "create", "lg/bk/sl", "--body", "nice", "--selection", "not json"]
+        )
+        assert result.exit_code == 1
+        assert "--selection JSON 解析失败" in result.output
+
     def test_delete_with_yes(self, fake):
         result = runner.invoke(cli.app, ["--yes", "comment", "delete", "5"])
         assert "已删除评论" in result.output
@@ -373,16 +423,16 @@ class TestSpace:
         assert result.exit_code == 0
         assert "Me" in result.output
         assert "me" in result.output
-        assert "跨境支付技术中心" in result.output
-        assert "PayKKa" in result.output
-        assert "pmw77l" in result.output
-        assert "gg87x1" in result.output
+        assert "Team A" in result.output
+        assert "Project B" in result.output
+        assert "user_a" in result.output
+        assert "user_b" in result.output
 
     def test_list_json(self, fake):
         result = runner.invoke(cli.app, ["--json", "space", "list"])
         assert result.exit_code == 0
         assert '"login": "me"' in result.output
-        assert '"login": "pmw77l"' in result.output
-        assert '"login": "gg87x1"' in result.output
+        assert '"login": "user_a"' in result.output
+        assert '"login": "user_b"' in result.output
         assert '"id": 1' in result.output
-        assert '"id": 42434150' in result.output
+        assert '"id": 200001' in result.output

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/test/test_client.py

@@ -6,7 +6,7 @@ from urllib.parse import quote
 import httpx
 import pytest
 
-from yuque_cli.client import USER_AGENT, Client
+from yuque_cli.client import USER_AGENT, Client, _extract_paragraphs
 from yuque_cli.errors import ApiError, AuthExpired
 from yuque_cli.session import CSRF_COOKIE, SESSION_COOKIE, Session
 
@@ -150,6 +150,40 @@ class TestWriteEndpoints:
         make_client(handler).create_comment(doc_id=7, body="nice")
         assert seen["body"] == {"commentable_id": 7, "commentable_type": "Doc", "body": "nice"}
 
+    def test_create_comment_with_selection(self):
+        seen = {}
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            seen["body"] = json.loads(req.content)
+            return httpx.Response(200, json={"data": {"id": 11}})
+
+        sel = {
+            "paragraph_id": "u-pid",
+            "text_offset": 0,
+            "text": "hello",
+            "selection_range": {
+                "start": {"id": "u-eid", "text": "hello", "offset": 0, "paragraphId": "u-pid", "paragraphOffset": 0},
+                "end": {"id": "u-eid", "text": "hello", "offset": 3, "paragraphId": "u-pid", "paragraphOffset": 3},
+            },
+            "doc_version_id": 123,
+        }
+        make_client(handler).create_comment(doc_id=7, body="nice", selection=sel)
+
+        payload = seen["body"]
+        assert payload["commentable_id"] == 7
+        assert payload["commentable_type"] == "Doc"
+        assert payload["type"] == "WORDING_COMMENT"
+        assert payload["format"] == "lake"
+        assert payload["selection"] == sel
+        assert "body_asl" in payload
+        assert "<!doctype lake>" in payload["body_asl"]
+        assert "nice" in payload["body_asl"]
+        assert '<p data-lake-id="' in payload["body_asl"]
+        assert '<span data-lake-id="' in payload["body_asl"]
+        assert payload["body"] != "nice"  # body is HTML not plain text
+        assert '<div class="lake-content"' in payload["body"]
+        assert "nice" in payload["body"]
+
     def test_delete_comment(self):
         def handler(req: httpx.Request) -> httpx.Response:
             assert req.method == "DELETE"
@@ -177,3 +211,36 @@ class TestIdResolution:
             return httpx.Response(200, text=html)
 
         assert make_client(handler).resolve_doc_ids("lg", "bk", "sl") == (77, 88)
+
+
+class TestExtractParagraphs:
+    def test_extracts_ids_and_text(self):
+        html = '<div class="lake-content"><p id="u73ba16c1" class="ne-p"><span class="ne-text">发布时发布后</span></p></div>'
+        paras = _extract_paragraphs(html)
+        assert paras == [{"id": "u73ba16c1", "text": "发布时发布后", "spans": []}]
+
+    def test_extracts_spans_with_ids(self):
+        html = '<p id="p1"><span data-lake-id="s1" id="s1">hello</span></p>'
+        paras = _extract_paragraphs(html)
+        assert paras == [{"id": "p1", "text": "hello", "spans": [{"id": "s1", "text": "hello"}]}]
+
+    def test_skips_spans_without_ids(self):
+        html = '<p id="p1"><span style="color:red">no id span</span></p>'
+        paras = _extract_paragraphs(html)
+        assert paras[0]["spans"] == []
+
+    def test_multiple_paragraphs(self):
+        html = '<p id="a1">第一段<crap/></p>中间文本<p id="b2">二段</p>'
+        paras = _extract_paragraphs(html)
+        assert paras == [
+            {"id": "a1", "text": "第一段", "spans": []},
+            {"id": "b2", "text": "二段", "spans": []},
+        ]
+
+    def test_empty_no_paragraphs(self):
+        assert _extract_paragraphs("<div>no p tags</div>") == []
+
+    def test_strips_tags_and_entities(self):
+        html = '<p id="x">hello &lt;world&gt;</p>'
+        paras = _extract_paragraphs(html)
+        assert paras == [{"id": "x", "text": "hello <world>", "spans": []}]

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/test/test_urls.py

@@ -4,6 +4,7 @@ from yuque_cli.urls import (
     RepoRef,
     DocRef,
     UrlParseError,
+    extract_host,
     parse_repo_ref,
     parse_doc_ref,
 )
@@ -12,15 +13,15 @@ from yuque_cli.urls import (
 class TestParseDocRef:
     def test_full_https_url(self):
         ref = parse_doc_ref("https://www.yuque.com/abc/team-book/my-slug")
-        assert ref == DocRef(space="abc", repo="team-book", slug="my-slug")
+        assert ref == DocRef(space="abc", repo="team-book", slug="my-slug", host="www.yuque.com")
 
     def test_http_scheme(self):
         ref = parse_doc_ref("http://www.yuque.com/abc/book/slug")
-        assert ref == DocRef("abc", "book", "slug")
+        assert ref == DocRef("abc", "book", "slug", host="www.yuque.com")
 
     def test_host_without_scheme(self):
         ref = parse_doc_ref("www.yuque.com/abc/book/slug")
-        assert ref == DocRef("abc", "book", "slug")
+        assert ref == DocRef("abc", "book", "slug", host="www.yuque.com")
 
     def test_path_only(self):
         ref = parse_doc_ref("abc/book/slug")
@@ -34,7 +35,7 @@ class TestParseDocRef:
 
     def test_strips_query_and_fragment(self):
         ref = parse_doc_ref("https://www.yuque.com/abc/book/slug?from=x#h1")
-        assert ref == DocRef("abc", "book", "slug")
+        assert ref == DocRef("abc", "book", "slug", host="www.yuque.com")
 
     def test_strips_surrounding_whitespace(self):
         assert parse_doc_ref("  abc/book/slug  ") == DocRef("abc", "book", "slug")
@@ -51,9 +52,12 @@ class TestParseDocRef:
         with pytest.raises(UrlParseError):
             parse_doc_ref("")
 
-    def test_too_many_segments_rejected(self):
-        with pytest.raises(UrlParseError):
-            parse_doc_ref("abc/book/slug/extra")
+    def test_extra_segments_use_first_three(self):
+        """多余的路径段（如 /edit）会被忽略，只取前三段。"""
+        assert parse_doc_ref("abc/book/slug/edit") == DocRef("abc", "book", "slug")
+        assert parse_doc_ref(
+            "https://www.yuque.com/abc/book/slug/edit"
+        ) == DocRef("abc", "book", "slug", host="www.yuque.com")
 
     def test_repo_ref_property(self):
         ref = parse_doc_ref("abc/book/slug")
@@ -63,7 +67,7 @@ class TestParseDocRef:
 class TestParseRepoRef:
     def test_full_https_url(self):
         assert parse_repo_ref("https://www.yuque.com/abc/team-book") == RepoRef(
-            "abc", "team-book"
+            "abc", "team-book", host="www.yuque.com"
         )
 
     def test_path_only(self):
@@ -73,7 +77,7 @@ class TestParseRepoRef:
         assert parse_repo_ref("abc/team-book/some-slug") == RepoRef("abc", "team-book")
 
     def test_host_stripped_and_trailing_slash(self):
-        assert parse_repo_ref("www.yuque.com/abc/book/") == RepoRef("abc", "book")
+        assert parse_repo_ref("www.yuque.com/abc/book/") == RepoRef("abc", "book", host="www.yuque.com")
 
     def test_space_only_is_rejected(self):
         with pytest.raises(UrlParseError):
@@ -82,3 +86,23 @@ class TestParseRepoRef:
     def test_empty_is_rejected(self):
         with pytest.raises(UrlParseError):
             parse_repo_ref("   ")
+
+
+class TestExtractHost:
+    def test_full_url(self):
+        assert extract_host("https://www.yuque.com/abc/book/slug") == "www.yuque.com"
+
+    def test_custom_domain(self):
+        assert extract_host("https://jlpay.yuque.com/pmw77l/iybc48/doc") == "jlpay.yuque.com"
+
+    def test_no_scheme_with_host(self):
+        assert extract_host("jlpay.yuque.com/abc/book/slug") == "jlpay.yuque.com"
+
+    def test_path_only(self):
+        assert extract_host("abc/book/slug") is None
+
+    def test_empty(self):
+        assert extract_host("") is None
+
+    def test_whitespace(self):
+        assert extract_host("  https://foo.com/a/b  ") == "foo.com"

{yuque_cli-0.1.1 → yuque_cli-1.0.0}/uv.lock

@@ -337,7 +337,7 @@ wheels = [
 
 [[package]]
 name = "yuque-cli"
-version = "0.1.1"
+version = "1.0.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },