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

{yuque_cli-0.1.0 → yuque_cli-0.1.1}/.claude/settings.local.json

@@ -10,7 +10,12 @@
       "Bash(ps -p 46455 -o command=)",
       "Bash(curl --noproxy '*' -sS -m 3 -i http://127.0.0.1:9222/)",
       "Bash(curl --noproxy '*' -sS -m 3 http://127.0.0.1:9222/json)",
-      "Bash(curl --noproxy '*' -sS -m 3 http://127.0.0.1:9222/json/list)"
+      "Bash(curl --noproxy '*' -sS -m 3 http://127.0.0.1:9222/json/list)",
+      "Bash(python *)",
+      "mcp__chrome-devtools__take_snapshot",
+      "mcp__chrome-devtools__navigate_page",
+      "mcp__chrome-devtools__list_pages",
+      "WebSearch"
     ]
   }
 }

{yuque_cli-0.1.0 → yuque_cli-0.1.1}/CONTEXT.md

@@ -1,11 +1,11 @@
 # 语雀 CLI (yuque-cli)
 
-针对语雀（含企业版）的通用命令行客户端：以浏览器 cookie 认证、驱动语雀内部 web 接口，提供文档与评论的增删改查。默认连接 `www.yuque.com`，企业实例用环境变量 `YUQUE_HOST` 指定。
+针对语雀的通用命令行客户端：以浏览器 cookie 认证、驱动语雀内部 web 接口，提供文档与评论的增删改查。默认连接 `www.yuque.com`，自建实例用环境变量 `YUQUE_HOST` 指定。
 
 ## Language
 
-**知识库 (Book)**:
-语雀中承载一组文档的容器，对应网页端的「知识库」。内部 API 中称 `book`（本工具采用此英文名）；官方开放 API 中称 `repo`。
+**知识库 (Repo)**:
+语雀中承载一组文档的容器，对应网页端的「知识库」。内部 API 中称 `repo`；官方开放 API 中称 `repo`。
 _Avoid_: Repo, 仓库, 文档库
 
 **文档 (Doc)**:
@@ -16,14 +16,14 @@ _Avoid_: 文章, Article, Page
 挂在某一篇文档上的评论。
 _Avoid_: 回复, Reply
 
-**login**:
-用户或团队的唯一标识，位于 URL 第一段（`<host>/{login}/...`）。可指个人用户，也可指团队，二者在 URL 中形态一致。
-_Avoid_: username, 账号, owner
+**space**:
+用户或团队的唯一标识，位于 URL 第一段（`<host>/{space}/...`）。可指个人用户，也可指团队，二者在 URL 中形态一致。
+_Avoid_: login, username, 账号, owner
 
 **namespace**:
-定位一个知识库的路径，形如 `{login}/{book}`（语雀官方术语），即知识库的浏览器地址（book URL）。用户可直接用此 URL 指定一个知识库；文档地址在其后再加 `/{slug}`（doc URL）。两种 URL 去掉 host 的路径形态与完整 URL 等价；数字 id 不属于用户语汇，仅内部解析时使用。
-_Avoid_: 把单独的 login 误当作 namespace（URL 第一段只是 login，不是完整 namespace）
+定位一个知识库的路径，形如 `{space}/{repo}`（语雀官方术语），即知识库的浏览器地址（book URL）。用户可直接用此 URL 指定一个知识库；文档地址在其后再加 `/{slug}`（doc URL）。两种 URL 去掉 host 的路径形态与完整 URL 等价；数字 id 不属于用户语汇，仅内部解析时使用。
+_Avoid_: 把单独的 space 误当作 namespace（URL 第一段只是 space，不是完整 namespace）
 
 **slug**:
-文档在其知识库内的可读标识，位于 URL 末段。一篇文档的完整地址即 `{login}/{book}/{slug}`，也就是其浏览器 URL。
+文档在其知识库内的可读标识，位于 URL 末段。一篇文档的完整地址即 `{space}/{repo}/{slug}`，也就是其浏览器 URL。
 _Avoid_: 短链, 别名

yuque_cli-0.1.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: yuque-cli
+Version: 0.1.1
+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 接口，提供文档与评论的增删改查。
+
+> 术语（知识库/文档/评论/space/namespace/slug）见 [CONTEXT.md](./CONTEXT.md)；关键设计取舍见 [docs/adr](./docs/adr)。
+
+## 安装
+
+需要 Python ≥ 3.10 与 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+uv sync                 # 安装依赖
+uv run yuque --help     # 项目内运行
+uv tool install .       # 全局安装
+```
+
+## 快速开始
+
+```bash
+yuque auth login                       # 登录（自动 CDP 抓取 cookie，失败回退手动粘贴）
+yuque auth status                      # 查看当前身份
+yuque repo list                        # 列出我的知识库
+yuque doc list  <space>/<repo>         # 列出知识库下的文档
+yuque doc get   <space>/<repo>/<slug>  # 取文档正文（Markdown）
+```
+
+地址可用完整浏览器 URL 或去掉 host 的路径形态，二者等价。
+
+## 认证
+
+`yuque auth login` 默认从 Chrome 远程调试端口（9222）自动抓取 cookie。前提是 Chrome 以此端口启动：
+
+```bash
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+```
+
+未检测到远程调试时，提示手动粘贴 cookie。也可 `yuque auth login --manual` 跳过 CDP。
+
+会话保存在 `~/.config/yuque-cli/session.json`（权限 0600），`yuque auth logout` 清除。
+
+## 全局选项
+
+置于子命令之前：`yuque --json repo list`。
+
+| 选项 | 说明 |
+| --- | --- |
+| `--json` | 输出原始 JSON |
+| `-y`, `--yes` | 跳过确认 |
+| `-v`, `--verbose` | 打印 HTTP 请求到 stderr |
+| `-V`, `--version` | 显示版本 |
+
+## 命令
+
+### auth
+
+| 命令 | 说明 |
+| --- | --- |
+| `auth login [--manual]` | 登录 |
+| `auth status` | 显示当前身份 |
+| `auth logout` | 清除会话 |
+
+### repo
+
+| 命令 | 说明 |
+| --- | --- |
+| `repo list` | 列出我的知识库 |
+
+### doc
+
+| 命令 | 说明 |
+| --- | --- |
+| `doc list <space>/<repo>` | 列出文档 |
+| `doc get <space>/<repo>/<slug>` | 取正文（默认 Markdown，`--json` 出详情） |
+| `doc create <space>/<repo> -t <标题> [选项]` | 创建文档 |
+| `doc update <space>/<repo>/<slug> [选项]` | 更新文档（先取后合并，未给的字段保持原值） |
+| `doc delete <space>/<repo>/<slug>` | 删除文档（软删，可回收站恢复） |
+
+`doc create` 选项：`-t/--title`（必填）、`--slug`、`--public/--private`、`-b/--body`、`-F/--file`。
+
+`doc update` 选项：`-t/--title`、`--public/--private`、`-b/--body`、`-F/--file`；至少给其一。
+
+```bash
+yuque doc create team/handbook -t "上手指南" --body "# 标题\n正文"
+yuque doc create team/handbook -t "周报" -F report.md --private
+yuque doc update team/handbook/getting-started -t "新标题"
+yuque -y doc delete team/handbook/old-draft
+```
+
+### comment
+
+| 命令 | 说明 |
+| --- | --- |
+| `comment list <space>/<repo>/<slug>` | 列出评论 |
+| `comment add <space>/<repo>/<slug> [-b/--body \| -F/--file]` | 添加评论 |
+| `comment delete <comment_id>` | 删除评论 |
+
+## 正文输入
+
+`doc create` / `comment add` 正文来源（`--body` 与 `--file` 互斥）：
+
+1. `-b/--body` 内联字符串
+2. `-F/--file` 从文件读（`-F -` 读 stdin）
+3. 管道 stdin
+
+```bash
+echo "# 正文" | yuque doc create team/handbook -t "标题"
+```
+
+`doc update` 只有显式给 `-b`/`-F` 才会改正文，裸管道不生效。
+
+## 环境变量
+
+| 变量 | 作用 | 默认 |
+| --- | --- | --- |
+| `YUQUE_HOST` | 目标语雀 host | `www.yuque.com` |
+| `YUQUE_CONFIG_DIR` | 配置目录 | `~/.config/yuque-cli` |
+| `NO_COLOR` | 禁用彩色输出 | — |
+
+## 开发
+
+```bash
+mise run deps     # uv sync
+mise run test     # pytest
+mise run lint     # ruff check && ruff format
+mise run check    # pyright
+mise run cli -- --help
+```

yuque_cli-0.1.1/README.md

@@ -0,0 +1,127 @@
+# yuque-cli
+
+语雀通用命令行客户端，以浏览器 cookie 认证，驱动语雀内部 web 接口，提供文档与评论的增删改查。
+
+> 术语（知识库/文档/评论/space/namespace/slug）见 [CONTEXT.md](./CONTEXT.md)；关键设计取舍见 [docs/adr](./docs/adr)。
+
+## 安装
+
+需要 Python ≥ 3.10 与 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+uv sync                 # 安装依赖
+uv run yuque --help     # 项目内运行
+uv tool install .       # 全局安装
+```
+
+## 快速开始
+
+```bash
+yuque auth login                       # 登录（自动 CDP 抓取 cookie，失败回退手动粘贴）
+yuque auth status                      # 查看当前身份
+yuque repo list                        # 列出我的知识库
+yuque doc list  <space>/<repo>         # 列出知识库下的文档
+yuque doc get   <space>/<repo>/<slug>  # 取文档正文（Markdown）
+```
+
+地址可用完整浏览器 URL 或去掉 host 的路径形态，二者等价。
+
+## 认证
+
+`yuque auth login` 默认从 Chrome 远程调试端口（9222）自动抓取 cookie。前提是 Chrome 以此端口启动：
+
+```bash
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
+```
+
+未检测到远程调试时，提示手动粘贴 cookie。也可 `yuque auth login --manual` 跳过 CDP。
+
+会话保存在 `~/.config/yuque-cli/session.json`（权限 0600），`yuque auth logout` 清除。
+
+## 全局选项
+
+置于子命令之前：`yuque --json repo list`。
+
+| 选项 | 说明 |
+| --- | --- |
+| `--json` | 输出原始 JSON |
+| `-y`, `--yes` | 跳过确认 |
+| `-v`, `--verbose` | 打印 HTTP 请求到 stderr |
+| `-V`, `--version` | 显示版本 |
+
+## 命令
+
+### auth
+
+| 命令 | 说明 |
+| --- | --- |
+| `auth login [--manual]` | 登录 |
+| `auth status` | 显示当前身份 |
+| `auth logout` | 清除会话 |
+
+### repo
+
+| 命令 | 说明 |
+| --- | --- |
+| `repo list` | 列出我的知识库 |
+
+### doc
+
+| 命令 | 说明 |
+| --- | --- |
+| `doc list <space>/<repo>` | 列出文档 |
+| `doc get <space>/<repo>/<slug>` | 取正文（默认 Markdown，`--json` 出详情） |
+| `doc create <space>/<repo> -t <标题> [选项]` | 创建文档 |
+| `doc update <space>/<repo>/<slug> [选项]` | 更新文档（先取后合并，未给的字段保持原值） |
+| `doc delete <space>/<repo>/<slug>` | 删除文档（软删，可回收站恢复） |
+
+`doc create` 选项：`-t/--title`（必填）、`--slug`、`--public/--private`、`-b/--body`、`-F/--file`。
+
+`doc update` 选项：`-t/--title`、`--public/--private`、`-b/--body`、`-F/--file`；至少给其一。
+
+```bash
+yuque doc create team/handbook -t "上手指南" --body "# 标题\n正文"
+yuque doc create team/handbook -t "周报" -F report.md --private
+yuque doc update team/handbook/getting-started -t "新标题"
+yuque -y doc delete team/handbook/old-draft
+```
+
+### comment
+
+| 命令 | 说明 |
+| --- | --- |
+| `comment list <space>/<repo>/<slug>` | 列出评论 |
+| `comment add <space>/<repo>/<slug> [-b/--body \| -F/--file]` | 添加评论 |
+| `comment delete <comment_id>` | 删除评论 |
+
+## 正文输入
+
+`doc create` / `comment add` 正文来源（`--body` 与 `--file` 互斥）：
+
+1. `-b/--body` 内联字符串
+2. `-F/--file` 从文件读（`-F -` 读 stdin）
+3. 管道 stdin
+
+```bash
+echo "# 正文" | yuque doc create team/handbook -t "标题"
+```
+
+`doc update` 只有显式给 `-b`/`-F` 才会改正文，裸管道不生效。
+
+## 环境变量
+
+| 变量 | 作用 | 默认 |
+| --- | --- | --- |
+| `YUQUE_HOST` | 目标语雀 host | `www.yuque.com` |
+| `YUQUE_CONFIG_DIR` | 配置目录 | `~/.config/yuque-cli` |
+| `NO_COLOR` | 禁用彩色输出 | — |
+
+## 开发
+
+```bash
+mise run deps     # uv sync
+mise run test     # pytest
+mise run lint     # ruff check && ruff format
+mise run check    # pyright
+mise run cli -- --help
+```

{yuque_cli-0.1.0 → yuque_cli-0.1.1}/docs/adr/0001-use-internal-web-api-with-cookie-auth.md

@@ -1,6 +1,6 @@
 # 使用语雀内部 web API + cookie 认证，而非官方 Open API v2
 
-目标企业语雀实例（企业版）禁用了个人 Token 生成，而官方 Open API v2 以 `X-Auth-Token` 认证，在禁 token 的实例上基本不可用；此外 v2 **完全没有评论接口**（Doc 对象上只有 `commentsCount` 计数）。因此本 CLI 直接驱动语雀网页端 SPA 所用的内部 `/api` 接口，以浏览器会话 cookie（`_yuque_session`）认证，写操作再带 CSRF（cookie 中的 `ctoken` ↔ 请求头 `x-csrf-token`）。
+目标语雀实例禁用了个人 Token 生成，而官方 Open API v2 以 `X-Auth-Token` 认证，在禁 token 的实例上基本不可用；此外 v2 **完全没有评论接口**（Doc 对象上只有 `commentsCount` 计数）。因此本 CLI 直接驱动语雀网页端 SPA 所用的内部 `/api` 接口，以浏览器会话 cookie（`_yuque_session`）认证，写操作再带 CSRF（cookie 中的 `ctoken` ↔ 请求头 `x-csrf-token`）。
 
 ## 权衡
 
@@ -11,4 +11,4 @@
 
 - 需要一层 CSRF 处理：读操作仅需 cookie，写操作（POST/PUT/DELETE）须额外带 `x-csrf-token`。
 - cookie 失效（401）需可被识别并提示用户重新登录。
-- 企业版 cookie 名可能与公版不同，认证模块不应硬编码假定唯一的 cookie 键名。
+- 不同部署的 cookie 名可能不同，认证模块不应硬编码假定唯一的 cookie 键名。

{yuque_cli-0.1.0 → yuque_cli-0.1.1}/docs/internal-api.md

@@ -1,7 +1,7 @@
 # 语雀内部 Web API 参考（实测）
 
 > 本文档记录 `yuque-cli` 所依赖的语雀**内部** web 接口（非官方 Open API v2，原因见 [ADR 0001](./adr/0001-use-internal-web-api-with-cookie-auth.md)）。
-> 全部端点于 **2026-06-01** 针对某企业语雀实例实测通过（discovery + 写链路验证 spike）。
+> 全部端点于 **2026-06-01** 针对某语雀实例实测通过（discovery + 写链路验证 spike）。
 > 内部接口未公开、无版本承诺，可能随语雀前端升级而变化。
 
 ## 认证与通用请求头
@@ -24,9 +24,9 @@
 
 ## URL → id 解析
 
-写命令大多需要 `book_id`（部分需要数字 `doc_id`），但**没有干净的 REST 路径**可从 `login/book_slug` 反查（`/api/repos/{ns}`、`/api/books/{id}` 均 404）。
+写命令大多需要 `book_id`（部分需要数字 `doc_id`），但**没有干净的 REST 路径**可从 `space/book_slug` 反查（`/api/repos/{ns}`、`/api/books/{id}` 均 404）。
 
-通用解法：GET 页面 HTML `https://<host>/{login}/{book}[/{slug}]`，提取其中
+通用解法：GET 页面 HTML `https://<host>/{space}/{book}[/{slug}]`，提取其中
 `window.appData = JSON.parse(decodeURIComponent("..."))`，解码后读：
 
 - `appData.book.id` → book_id
@@ -51,7 +51,7 @@
 | 能力 | 方法 路径 | 备注 |
 |---|---|---|
 | 列出文档 | `GET /api/books/{book_id}/docs` | 返回 `[{id, slug, title, book_id, ...}]` |
-| 取正文（Markdown） | `GET /{login}/{book}/{slug}/markdown?plain=true&linebreak=false&anchor=false` | 干净 Markdown，**不需 book_id、非 /api** |
+| 取正文（Markdown） | `GET /{space}/{book}/{slug}/markdown?plain=true&linebreak=false&anchor=false` | 干净 Markdown，**不需 book_id、非 /api** |
 | 取详情（JSON/Lake） | `GET /api/docs/{slug或id}?book_id={book_id}` | **必须带 `book_id`**，否则 404 |
 | 创建 | `POST /api/docs` body `{book_id, title, slug, format:"markdown", body, public}` | 返回 `data{id, slug, body, body_draft, format, status, ...}` |
 | 更新 | `PUT /api/docs/{id}` body `{title, body, format:"markdown", public}` | |

{yuque_cli-0.1.0 → yuque_cli-0.1.1}/mise.toml

@@ -25,5 +25,8 @@ depends = ["deps"]
 run = "uv build"
 
 [tasks.publish]
-depends = ["build"]
+depends = ["build", "clean"]
 run = "uv publish"
+
+[tasks.clean]
+run = "rm -rf ./dist/"

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

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

yuque_cli-0.1.1/src/yuque_cli/__init__.py

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

{yuque_cli-0.1.0 → yuque_cli-0.1.1}/src/yuque_cli/appdata.py

@@ -25,7 +25,7 @@ def parse_app_data(html: str) -> dict:
         raise AppDataError(f"window.appData 解码失败：{exc}") from exc
 
 
-def book_id(app_data: dict) -> int:
+def repo_id(app_data: dict) -> int:
     try:
         return int(app_data["book"]["id"])
     except (KeyError, TypeError, ValueError) as exc: