yuque-cli 0.1.0__tar.gz

yuque_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__chrome-devtools__new_page",
+      "Bash(uv run *)",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__query-docs",
+      "Bash(uv pip *)",
+      "Bash(uv add *)",
+      "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)"
+    ]
+  }
+}

yuque_cli-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv
+.ruff_cache
+.pytest_cache
+__pycache__/
+dist/

yuque_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

yuque_cli-0.1.0/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "charliermarsh.ruff",
+    "ms-python.python",
+    "astral-sh.ty"
+}

yuque_cli-0.1.0/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnSave": true,
+  },
+  "python.languageServer": "Pylance",
+  "ty.disableLanguageServices": true,
+}

yuque_cli-0.1.0/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS
+
+- TDD

yuque_cli-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

yuque_cli-0.1.0/CONTEXT.md

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

yuque_cli-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,180 @@
+# 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/docs/adr/0001-use-internal-web-api-with-cookie-auth.md

@@ -0,0 +1,14 @@
+# 使用语雀内部 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 + 需要评论 CRUD」的约束下，这是唯一能同时覆盖文档与评论的路径。真实端点可借助 Chrome remote debugging 观察 SPA 流量扒取并固化。
+
+## 后果
+
+- 需要一层 CSRF 处理：读操作仅需 cookie，写操作（POST/PUT/DELETE）须额外带 `x-csrf-token`。
+- cookie 失效（401）需可被识别并提示用户重新登录。
+- 企业版 cookie 名可能与公版不同，认证模块不应硬编码假定唯一的 cookie 键名。

yuque_cli-0.1.0/docs/adr/0002-cookie-acquisition-cdp-with-manual-fallback.md

@@ -0,0 +1,21 @@
+# Cookie 获取：DevToolsActivePort 直连浏览器级 WS（抑制 Origin、绕代理）+ 手动粘贴兜底
+
+在禁用 token（见 [0001](./0001-use-internal-web-api-with-cookie-auth.md)）的前提下，认证依赖浏览器 cookie。`auth login` 默认尝试从**用户当前的 Chrome**（已登录目标站点）抓 cookie，失败再回退手动粘贴。实测在 目标站点 走通的路径如下，三处都踩过坑：
+
+1. **发现端点用 `DevToolsActivePort` 文件，而非 `/json` HTTP**。Chrome 136+ 在**默认 profile** 下禁用了 `/json`、`/json/version` 等 HTTP 调试接口（直连返回空 `404`），但 profile 目录下的 `DevToolsActivePort` 文件仍记录「端口 + 浏览器级 WS 路径」（如 `9222` / `/devtools/browser/<uuid>`）。故以该文件为主、`/json/version` 仅作兜底。
+2. **连 WS 必须抑制 `Origin` 头**。Chrome 111+ 默认拒绝带 `Origin` 的 WS 握手（`403`，提示需 `--remote-allow-origins`）。客户端**不发 Origin 头**即可连上，免去用户重启 Chrome 加该 flag。握手实测约 2s，超时要给足（用 5s）。
+3. **本地回环必须绕开代理**。用户常设 `http_proxy/all_proxy`（如 Clash 的 `127.0.0.1:7897`）；默认信任环境变量会把对 `127.0.0.1:9222` 的请求也走代理而被拦（404、响应头带 `Proxy-Connection`）。故 HTTP 探测用 `trust_env=False`、WS 用 `http_no_proxy`。
+
+连上后调 CDP `Storage.getCookies`，过滤出 目标站点 的全部 cookie（含 httpOnly 的 `_yuque_session` 与 CSRF `yuque_ctoken`），**必须校验确有 `_yuque_session` 才认**。`--manual` 跳过自动直奔手动粘贴。
+
+## 被否决的备选
+
+- **专属调试 profile + 一次性重登 SSO**：可复现，但要在新 profile 重新登录，违背「复用现有登录态」。
+- **直接解密 Chrome cookie DB（macOS Keychain）**：OS 特定、需关 Chrome、弹 Keychain，且加密随版本收紧有长期失效风险。
+- **要求用户加 `--remote-allow-origins=*` 重启 Chrome**：可行但多一步重启；改用抑制 Origin 头规避。
+
+## 后果
+
+- CDP 自动化要求用户的 Chrome 以 `--remote-debugging-port=9222` 启动（默认 profile 即可）并已登录目标站点；对 `uvx` 分发的同事不保证人人如此，故**手动粘贴必须始终可用且文档清晰**。
+- 发现/握手/取 cookie 任一环失败都优雅退回手动；`-v` 可打印真实失败原因。
+- 写操作仍需 CSRF：`yuque_ctoken` cookie 值作为请求头 `x-csrf-token`。

yuque_cli-0.1.0/docs/adr/0003-doc-update-fetch-then-merge.md

@@ -0,0 +1,16 @@
+# doc update 采用「先取后合并」而非整体替换
+
+语雀内部 `PUT /api/docs/{id}` 接收 `{title, body, format, public}`，外观上是整篇替换；但 discovery spike（见 [internal-api.md](../internal-api.md)）只验证了「写得进去」，**未验证省略某字段时该字段会被保留还是被清空**。若实际为整体替换语义，`doc update <doc-url> --title X`（不带正文）就会把正文清空。
+
+因此 `doc update` 先 `GET /api/docs/{slug}?book_id=` 取回现有 `title/body/public`，仅用用户本次命令**显式给出**的字段覆盖，再整体 PUT 回去。
+
+## 权衡
+
+- **代价**：每次更新多一次 GET 往返；且引入「读-改-写」窗口——两端同时改会发生后写覆盖先写。本工具是单人交互式 CLI，此窗口可接受。
+- **为何仍选它**：在 PUT 替换语义未经验证的前提下，这是唯一能安全支持「只改标题 / 只改可见性」而不误清空正文的做法。误清空是不可逆的内容损失（软删只回收文档整体，救不回被覆盖的正文版本），代价远高于一次 GET。
+
+## 后果
+
+- `--title`、正文（`--body`/`--file`）、`--public`/`--private` 均可单独给；未给的字段保持原值（可见性为三态：不给即保持）。
+- 必须至少给一个可改字段，否则报错（无可更新内容），不发空 PUT。
+- 若日后验证内部 PUT 确为「缺字段即保留」的 patch 语义，可移除这次 GET、简化为直接发增量；属可逆优化。

yuque_cli-0.1.0/docs/internal-api.md

@@ -0,0 +1,76 @@
+# 语雀内部 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）。
+> 内部接口未公开、无版本承诺，可能随语雀前端升级而变化。
+
+## 认证与通用请求头
+
+所有请求都带：
+
+| 头 | 值 | 说明 |
+|---|---|---|
+| `Cookie` | 完整 cookie 串 | 须含 `_yuque_session`（登录态）与 `yuque_ctoken`（CSRF） |
+| `User-Agent` | 浏览器 UA | 必需，缺失会被拒 |
+| `Referer` | 相关页面 URL | 内部接口会校验来源 |
+| `x-requested-with` | `XMLHttpRequest` | |
+
+**写操作（POST/PUT/DELETE）额外带**：
+
+| 头 | 值 |
+|---|---|
+| `Content-Type` | `application/json` |
+| `x-csrf-token` | **`yuque_ctoken` cookie 的值**（实测有效） |
+
+## URL → id 解析
+
+写命令大多需要 `book_id`（部分需要数字 `doc_id`），但**没有干净的 REST 路径**可从 `login/book_slug` 反查（`/api/repos/{ns}`、`/api/books/{id}` 均 404）。
+
+通用解法：GET 页面 HTML `https://<host>/{login}/{book}[/{slug}]`，提取其中
+`window.appData = JSON.parse(decodeURIComponent("..."))`，解码后读：
+
+- `appData.book.id` → book_id
+- `appData.doc.id` → doc_id（doc 页面才有）
+
+## 用户 / Auth
+
+| 能力 | 方法 路径 | 响应要点 |
+|---|---|---|
+| 当前用户（auth info） | `GET /api/mine` | `data{ login, name, id, email, organization_login, user_id, ... }` |
+
+## 知识库 / Repo
+
+| 能力 | 方法 路径 | 响应要点 |
+|---|---|---|
+| 我的知识库（repo list） | `GET /api/mine/books` | `[{ id, slug, name, items_count, public, user_id, abilities{create_doc,modify_setting,destroy} }]` |
+
+> `user_id` 为当前用户 id 即个人库，否则为团队/群组库。`abilities.destroy` 仅指「删整个知识库」，不影响删除自建文档。
+
+## 文档 / Doc
+
+| 能力 | 方法 路径 | 备注 |
+|---|---|---|
+| 列出文档 | `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** |
+| 取详情（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}` | |
+| 删除 | `DELETE /api/docs/{id}` | 软删 → 回收站（可恢复）；自建文档可删 |
+
+> `format:"markdown"` 在创建/更新时被直接接受，**无需构造 Lake 格式**。
+
+## 评论 / Comment（文档级）
+
+| 能力 | 方法 路径 | 备注 |
+|---|---|---|
+| 列出 | `GET /api/comments?commentable_id={doc_id}&commentable_type=Doc` | |
+| 创建 | `POST /api/comments` body `{commentable_id, commentable_type:"Doc", body}` | 正文字段是 **`body`**（不是 `content`） |
+| 删除 | `DELETE /api/comments/{comment_id}` | |
+
+> 评论对象含 `selection_id` / `selection_type`：文档级评论为空，行内「划词评论」靠它们锚定。本工具仅做文档级（见对话决策）。
+
+## 已知坑
+
+- `/api/docs/{slug}` **不带 `book_id` 会 404**——demo 旧代码的 `--lake` 路径即栽在这里（从未真正跑通）。
+- 删除是**软删**（进回收站），非物理删除。
+- 数字 id 与 slug 在 `/api/docs/{x}?book_id=` 下均可用；写操作（PUT/DELETE）实测用数字 `id`。

yuque_cli-0.1.0/main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from yuque-cli!")
+
+
+if __name__ == "__main__":
+    main()

yuque_cli-0.1.0/mise.toml

@@ -0,0 +1,29 @@
+[tools]
+uv = "latest"
+
+[tasks.deps]
+run = "uv sync"
+
+[tasks.cli]
+depends = ["deps"]
+run = "uv run yuque"
+
+[tasks.test]
+depends = ["deps"]
+run = "uv run pytest"
+
+[tasks.lint]
+depends = ["deps"]
+run = "ruff check && ruff format"
+
+[tasks.check]
+depends = ["deps"]
+run = "ty check"
+
+[tasks.build]
+depends = ["deps"]
+run = "uv build"
+
+[tasks.publish]
+depends = ["build"]
+run = "uv publish"

yuque_cli-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "yuque-cli"
+version = "0.1.0"
+description = "针对企业语雀实例的命令行客户端：cookie 认证，驱动内部 web 接口，提供文档与评论的 CRUD"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.12",
+    "httpx>=0.27",
+    "websocket-client>=1.9.0",
+]
+
+[project.scripts]
+yuque = "yuque_cli.cli:app"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.15",
+    "ty>=0.0.40",
+    "pytest>=8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yuque_cli"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.pytest.ini_options]
+testpaths = ["test"]
+pythonpath = ["src"]
+addopts = "-q"

yuque_cli-0.1.0/src/yuque_cli/__init__.py

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