yuque-cookie-plugin 0.1.2 → 0.1.3

package/README.md

@@ -9,7 +9,7 @@
 ## 当前能力
 
 - Cookie 登录、清理和登录态检测：`auth login`、`auth logout`、`auth status`
-- 读取语雀信息：`book inspect`、`doc inspect`
+- 读取语雀信息：`book list`、`book inspect`、`doc inspect`
 - 文档快照和结构对比：`doc snapshot`、`lake diff`
 - Lake 和 Markdown 辅助转换：`lake to-markdown`、`lake serialize`
 - 安全写入：`doc apply-lake`、`doc update-lake`
@@ -78,6 +78,15 @@ npm run yuque-local -- auth login
 
 项目目录不会保存真实 Cookie。配置文件会记录保存时间、更新时间、最近成功验证时间和最近失败时间。
 
+如果你在同一台电脑上同时做全局 npm 版真实测试和本地源码开发，可以用独立配置目录隔离 Cookie：
+
+```bash
+YUQUE_COOKIE_PLUGIN_CONFIG_DIR=/tmp/yuque-plugin-real-test yuque-local auth login
+YUQUE_COOKIE_PLUGIN_CONFIG_DIR=/tmp/yuque-plugin-real-test yuque-local auth status --json
+```
+
+这会把配置保存到 `/tmp/yuque-plugin-real-test/config.json`，不会影响默认的 `~/.config/yuque-cookie-plugin/config.json`。
+
 也可以用环境变量覆盖本地配置：
 
 ```bash
@@ -121,6 +130,12 @@ yuque-local auth login --manual \
 npm run yuque-local -- book inspect https://www.yuque.com/<your-login>/<your-book>
 ```
 
+列出当前账号可访问的知识库：
+
+```bash
+yuque-local book list --json
+```
+
 下载整个知识库：
 
 ```bash
@@ -240,6 +255,7 @@ npm run real:acceptance -- \
 ## 文档
 
 - `docs/usage-zh.md`：中文完整使用指南
+- `docs/ai-dialogue-test-cases.md`：用户和 AI 对话测试用例
 - `docs/real-acceptance.md`：真实语雀验收流程
 - `docs/native-lake-capability.md`：原生 Lake 能力矩阵
 - `docs/development-plan.md`：开发计划和迭代日志

package/dist/auth.js

@@ -6,16 +6,20 @@ import { createInterface } from 'node:readline/promises';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-const CONFIG_DIR = path.join(os.homedir(), '.config', 'yuque-cookie-plugin');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+export const CONFIG_DIR_ENV = 'YUQUE_COOKIE_PLUGIN_CONFIG_DIR';
+export function getConfigDirPath() {
+    const override = process.env[CONFIG_DIR_ENV]?.trim();
+    return override ? path.resolve(override) : path.join(os.homedir(), '.config', 'yuque-cookie-plugin');
+}
 export function getConfigFilePath() {
-    return CONFIG_FILE;
+    return path.join(getConfigDirPath(), 'config.json');
 }
 export async function clearSavedCredentials() {
-    const existed = existsSync(CONFIG_FILE);
-    await rm(CONFIG_FILE, { force: true });
+    const configFile = getConfigFilePath();
+    const existed = existsSync(configFile);
+    await rm(configFile, { force: true });
     return {
-        config_file: CONFIG_FILE,
+        config_file: configFile,
         removed: existed
     };
 }
@@ -34,7 +38,7 @@ export function getCredentials(flags = {}) {
     }
     const saved = readSavedCredentials();
     if (saved?.session && saved?.ctoken) {
-        return { ...saved, extraCookies: { ...(saved.extraCookies || {}), ...extraCookies }, source: CONFIG_FILE };
+        return { ...saved, extraCookies: { ...(saved.extraCookies || {}), ...extraCookies }, source: getConfigFilePath() };
     }
     throw new Error('Missing Yuque credentials. Run "yuque-local auth login" to configure them in your browser.');
 }
@@ -56,12 +60,12 @@ export function getCredentialStatus(flags = {}) {
     if (!saved?.session || !saved?.ctoken) {
         return {
             configured: false,
-            source: CONFIG_FILE
+            source: getConfigFilePath()
         };
     }
     return {
         configured: true,
-        source: CONFIG_FILE,
+        source: getConfigFilePath(),
         home_url: saved.homeUrl || null,
         saved_at: saved.saved_at || null,
         updated_at: saved.updated_at || null,
@@ -111,7 +115,7 @@ export async function loginWithBrowser(flags = {}) {
     await openBrowser(result.url);
     const credentials = await result.done;
     await saveCredentials(credentials);
-    console.log(`Saved Yuque credentials to ${CONFIG_FILE}`);
+    console.log(`Saved Yuque credentials to ${getConfigFilePath()}`);
 }
 export async function loginManually(flags = {}) {
     const sessionFromFlag = typeof flags.session === 'string' ? flags.session.trim() : '';
@@ -124,7 +128,7 @@ export async function loginManually(flags = {}) {
             homeUrl: normalizeYuqueHomeUrl(homeUrlFromFlag),
             saved_at: new Date().toISOString()
         });
-        console.log(`Saved Yuque credentials to ${CONFIG_FILE}`);
+        console.log(`Saved Yuque credentials to ${getConfigFilePath()}`);
         return;
     }
     if (!process.stdin.isTTY) {
@@ -145,17 +149,18 @@ export async function loginManually(flags = {}) {
             homeUrl: normalizeYuqueHomeUrl(homeUrlInput.trim()),
             saved_at: new Date().toISOString()
         });
-        console.log(`Saved Yuque credentials to ${CONFIG_FILE}`);
+        console.log(`Saved Yuque credentials to ${getConfigFilePath()}`);
     }
     finally {
         rl.close();
     }
 }
 function readSavedCredentials() {
-    if (!existsSync(CONFIG_FILE))
+    const configFile = getConfigFilePath();
+    if (!existsSync(configFile))
         return null;
     try {
-        return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+        return JSON.parse(readFileSync(configFile, 'utf8'));
     }
     catch {
         return null;
@@ -163,14 +168,16 @@ function readSavedCredentials() {
 }
 async function saveCredentials(credentials) {
     const now = new Date().toISOString();
+    const configDir = getConfigDirPath();
+    const configFile = getConfigFilePath();
     const data = {
         ...credentials,
         saved_at: credentials.saved_at || now,
         updated_at: now
     };
-    await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    await writeFile(CONFIG_FILE, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
-    await chmod(CONFIG_FILE, 0o600);
+    await mkdir(configDir, { recursive: true, mode: 0o700 });
+    await writeFile(configFile, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+    await chmod(configFile, 0o600);
 }
 function ageHours(value) {
     if (!value)
@@ -326,6 +333,7 @@ function sendHtml(res, html, status = 200) {
     res.end(html);
 }
 function loginPage(error = '') {
+    const configFile = getConfigFilePath();
     return `<!doctype html>
 <html lang="zh-CN">
 <head>
@@ -370,7 +378,7 @@ function loginPage(error = '') {
         <p>本地保存语雀网页 Session，让 CLI 使用浏览器同款 Cookie 访问语雀。</p>
       </div>
       <div class="facts">
-        <div class="fact"><strong>保存位置</strong><span>~/.config/yuque-cookie-plugin/config.json</span></div>
+        <div class="fact"><strong>保存位置</strong><span>${escapeHtml(configFile)}</span></div>
         <div class="fact"><strong>安全边界</strong><span>只写入本机配置，不写入项目仓库。</span></div>
         <div class="fact"><strong>失效处理</strong><span>后续可用 auth-status 检测并提示重新登录。</span></div>
       </div>

package/dist/cli.js

@@ -26,6 +26,7 @@ Usage:
   yuque-local auth status [doc-or-book-url] [--json]
   yuque-local doctor [--json]
   yuque-local skill install|status|uninstall [--json]
+  yuque-local book list [--json]
   yuque-local book create --name <name> --slug <slug> [--description <text>] [--public]
   yuque-local book download <book-url> [--dist-dir download] [--incremental]
   yuque-local doc create <book-url> --title <title> --markdown-file <file> [--number-headings]
@@ -136,6 +137,7 @@ function normalizeInvocation(argv) {
             status: 'auth-status'
         },
         book: {
+            list: 'list-books',
             create: 'create-book',
             download: 'download-book',
             inspect: 'inspect'
@@ -463,6 +465,12 @@ async function main() {
             printCommandResult(info, flags, 'inspect completed');
             return;
         }
+        if (command === 'list-books') {
+            const result = await client.listBooks();
+            await recordCredentialValidation(true);
+            printCommandResult(result, flags, 'book list completed');
+            return;
+        }
         if (command === 'snapshot') {
             const [url] = positional;
             if (!url)

package/dist/client-cookie.js

@@ -54,6 +54,17 @@ export class YuqueCookieClient {
         const appData = await this.fetchAppData(url);
         return summarizeAppData(appData);
     }
+    async listBooks() {
+        const result = await this.requestJson('GET', '/api/mine/books?offset=0&limit=100', undefined, `${this.host}/dashboard`);
+        const books = normalizeBookListResponse(result)
+            .map((book) => normalizeBookSummary(book, this.host))
+            .filter((book) => Boolean(book));
+        return {
+            ok: true,
+            count: books.length,
+            books
+        };
+    }
     async getBookInfo(url) {
         const appData = await this.fetchAppData(url);
         if (!appData.book?.id)
@@ -490,6 +501,40 @@ function buildDocUrl(host, appData, book, doc) {
         return `${host}/${bookSlug}/${docSlug}`;
     return `${host}/api/docs/${doc.id || ''}`;
 }
+function normalizeBookListResponse(result) {
+    const data = result.data;
+    if (Array.isArray(data))
+        return data;
+    if (Array.isArray(data?.books))
+        return data.books;
+    if (Array.isArray(data?.repos))
+        return data.repos;
+    if (Array.isArray(result.books))
+        return result.books;
+    if (Array.isArray(result.repos))
+        return result.repos;
+    return [];
+}
+function normalizeBookSummary(book, host) {
+    const slug = typeof book.slug === 'string' ? book.slug : '';
+    const login = typeof book.login === 'string'
+        ? book.login
+        : typeof book.user?.login === 'string'
+            ? book.user.login
+            : undefined;
+    if (!slug)
+        return null;
+    return {
+        id: typeof book.id === 'number' ? book.id : undefined,
+        name: typeof book.name === 'string' ? book.name : slug,
+        slug,
+        login,
+        public: typeof book.public === 'number' || typeof book.public === 'boolean' ? book.public : undefined,
+        items_count: typeof book.items_count === 'number' ? book.items_count : undefined,
+        updated_at: typeof book.updated_at === 'string' ? book.updated_at : undefined,
+        url: login ? `${host}/${login}/${slug}` : `${host}/${slug}`
+    };
+}
 function guessContentType(fileName) {
     const ext = extname(fileName).toLowerCase();
     const types = {

package/docs/usage-zh.md

@@ -17,6 +17,21 @@
 
 项目目录不会保存真实 Cookie。
 
+如果需要把全局 npm 版、源码开发版、Docker 或 AI 真实测试环境隔离开，可以通过 `YUQUE_COOKIE_PLUGIN_CONFIG_DIR` 指定独立配置目录：
+
+```bash
+YUQUE_COOKIE_PLUGIN_CONFIG_DIR=/tmp/yuque-plugin-real-test yuque-local auth login
+YUQUE_COOKIE_PLUGIN_CONFIG_DIR=/tmp/yuque-plugin-real-test yuque-local auth status --json
+```
+
+指定后，Cookie 会保存到：
+
+```bash
+/tmp/yuque-plugin-real-test/config.json
+```
+
+不会影响默认的 `~/.config/yuque-cookie-plugin/config.json`。
+
 ## 2. 安装和准备
 
 普通用户推荐从 npm 安装：
@@ -103,6 +118,12 @@ yuque-local auth login --manual
 yuque-local auth logout
 ```
 
+如果你使用了隔离配置目录，清理时也要带上同一个环境变量：
+
+```bash
+YUQUE_COOKIE_PLUGIN_CONFIG_DIR=/tmp/yuque-plugin-real-test yuque-local auth logout
+```
+
 正常执行 `inspect`、`snapshot`、`download-book`、`download-doc` 等真实语雀命令成功后，也会刷新 `last_validated_at`。如果检测到 401、403、页面无法解析等登录态问题，CLI 会提示重新登录。
 
 ### 额外 Cookie
@@ -129,7 +150,38 @@ export YUQUE_EXTRA_COOKIE_VALUE='<cookie-value>'
 
 额外 Cookie 不会改变本项目的主链路，只用于兼容特殊访问场景。
 
-## 4. 下载整个知识库
+## 4. 列出知识库
+
+查看当前账号可访问的语雀知识库：
+
+```bash
+yuque-local book list --json
+```
+
+这个命令会通过网页 Session 调用语雀列表接口，只输出知识库摘要，不会打印本机配置文件或 Cookie。
+
+输出示例：
+
+```json
+{
+  "status": "success",
+  "message": "book list completed",
+  "data": {
+    "ok": true,
+    "count": 2,
+    "books": [
+      {
+        "name": "工控",
+        "slug": "ydv5i5",
+        "login": "your-login",
+        "url": "https://www.yuque.com/your-login/ydv5i5"
+      }
+    ]
+  }
+}
+```
+
+## 5. 下载整个知识库
 
 推荐先下载到临时目录验证：
 
@@ -234,7 +286,7 @@ AI 或脚本可以用 `retry.args` 只重试失败文档。
 
 `resources.files` 只记录本地相对路径和大小，不保存 Cookie。
 
-## 4.1 创建知识库和文档
+## 6. 创建知识库和文档
 
 创建私密测试知识库：
 
@@ -261,7 +313,7 @@ npm run yuque-local -- create-doc https://www.yuque.com/<your-login>/<your-book>
 - 不默认修改标题文本。
 - 返回 JSON 中 `format` 表示语雀创建接口的初始格式；如果默认 Lake 写回成功，会额外返回 `final_format: "lake"`。
 
-## 4.2 上传和插入附件
+## 7. 上传和插入附件
 
 只上传文件，不写入正文：
 
@@ -333,7 +385,7 @@ npm run yuque-local -- create-doc https://www.yuque.com/<your-login>/<your-book>
 - 语雀会把 Markdown 创建结果自动转换成 Lake 文档，工具随后会默认写回 Lake，后续修改应按 Lake 链路处理。
 - 当前原生写入能力矩阵见 `docs/native-lake-capability.md`。图片、附件、思维导图、画板属于下一阶段真实探索项，不能在未验证前手写 card。
 
-## 4.2 上传图片或附件探索
+## 8. 上传图片或附件探索
 
 只上传本地文件，不写入正文：
 
@@ -392,7 +444,7 @@ npm run yuque-local -- insert-attachment https://www.yuque.com/user/book/doc \
 
 和图片一样，`insert-attachment --dry-run` 会真实上传附件以获得语雀附件 URL，但不会修改文档正文。
 
-## 5. 下载单篇或多篇文档
+## 9. 下载单篇或多篇文档
 
 下载单篇：
 
@@ -409,7 +461,7 @@ npm run yuque-local -- download-doc \
   --dist-dir /tmp/yuque-doc-test
 ```
 
-## 6. 本地预览下载结果
+## 10. 本地预览下载结果
 
 只生成或检查 VitePress 配置，不启动长驻服务：
 
@@ -441,7 +493,7 @@ http://localhost:5173/
 npm run yuque-local -- serve-book /tmp/yuque-download-test/工控 --port 5173 --force
 ```
 
-## 7. 快照和差异比较
+## 11. 快照和差异比较
 
 抓取语雀文档快照：
 
@@ -461,7 +513,7 @@ npm run yuque-local -- diff-lake /tmp/before.json /tmp/after.json
 npm run yuque-local -- lake-to-markdown /tmp/doc.snapshot.json --out /tmp/doc.md
 ```
 
-## 8. HTML 转语雀 Lake
+## 12. HTML 转语雀 Lake
 
 把本地 HTML 交给语雀 Lake editor runtime 序列化：
 
@@ -477,7 +529,7 @@ npm run yuque-local -- editor-serialize --html-file article.html --out article.l
 
 说明使用的是 vendored Lake editor，而不是 fallback。
 
-## 9. 安全写入语雀文档
+## 13. 安全写入语雀文档
 
 强烈建议先 dry-run：
 
@@ -503,7 +555,7 @@ backups/
 reports/
 ```
 
-## 10. 文章格式化流程
+## 14. 文章格式化流程
 
 本地 HTML 到语雀文档的完整流程：
 
@@ -517,7 +569,7 @@ npm run yuque-local -- format-article https://www.yuque.com/user/book/doc --html
 npm run yuque-local -- format-article https://www.yuque.com/user/book/doc --html-file article.html
 ```
 
-## 11. 常用选项
+## 15. 常用选项
 
 忽略图片下载：
 
@@ -565,15 +617,16 @@ npm run yuque-local -- format-article https://www.yuque.com/user/book/doc --html
 
 如果需要严格的 JSON 输出，建议加 `--quiet`。
 
-## 12. 安全规则
+## 16. 安全规则
 
 - 不要把真实 `_yuque_session` 或 `yuque_ctoken` 写入项目文件。
 - 不要提交 `~/.config/yuque-cookie-plugin/config.json`。
+- 真实测试多个版本时，用 `YUQUE_COOKIE_PLUGIN_CONFIG_DIR` 隔离配置目录。
 - 线上写入必须先 dry-run。
 - 批量写入前先对单篇文档做实验。
 - 章节编号不要直接改标题文本硬塞编号，必须先做 snapshot before/after diff。
 
-## 13. 当前已验证场景
+## 17. 当前已验证场景
 
 已真实验证：
 
@@ -584,7 +637,7 @@ npm run yuque-local -- format-article https://www.yuque.com/user/book/doc --html
 - 第二次增量下载全部跳过。
 - 导出文件名保留正常空格。
 
-## 14. 当前未完全覆盖场景
+## 18. 当前未完全覆盖场景
 
 仍需继续补齐：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuque-cookie-plugin",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Cookie-based Yuque CLI for AI agents, without MCP or OpenAPI token limits.",
   "homepage": "https://github.com/c-sunc6/yuque-cookie-plugin#readme",

package/skills/yuque-cookie-plugin/SKILL.md

@@ -2,7 +2,7 @@
 name: yuque-cookie-plugin
 description: Use when an AI agent needs to operate Yuque through the local yuque-local CLI with _yuque_session and yuque_ctoken, including login, auth status, inspect, snapshot, download, create, native Lake update, image/PDF insertion, and safe document formatting. This skill is for CLI orchestration, not MCP or Yuque OpenAPI token usage.
 metadata:
-  version: "0.1.0"
+  version: "0.1.3"
   author: "c-sunc6"
 ---
 
@@ -36,6 +36,7 @@ yuque-local auth login --manual
 yuque-local auth logout --json
 yuque-local auth status <doc-or-book-url> --json
 yuque-local doctor --json
+yuque-local book list --json
 yuque-local book download <book-url> --dist-dir download --incremental --quiet --json
 yuque-local doc download <doc-url> --dist-dir download --quiet --json
 yuque-local doc create <book-url> --title "Title" --markdown-file article.md --number-headings --json
@@ -50,9 +51,10 @@ yuque-local skill uninstall --json
 
 1. Run `yuque-local doctor --json` to inspect local installation and credential state.
 2. If credentials are missing or stale, ask the user to run `yuque-local auth login` or `yuque-local auth login --manual`.
-3. For reads and downloads, call the relevant `book` or `doc` command with `--json`.
-4. For writes, snapshot first, prepare the change, run a dry run when available, then apply after user approval.
-5. Save local reports and paths from the CLI result for later audit.
+3. For book discovery, use `yuque-local book list --json`; do not read or print the local config file.
+4. For reads and downloads, call the relevant `book` or `doc` command with `--json`.
+5. For writes, snapshot first, prepare the change, run a dry run when available, then apply after user approval.
+6. Save local reports and paths from the CLI result for later audit.
 
 ## References
 

package/skills/yuque-cookie-plugin/commands.yaml

@@ -42,6 +42,13 @@ skill.uninstall:
   example: "yuque-local skill uninstall --json"
   reference: "reference/agent-spec.md"
 
+book.list:
+  cli: "yuque-local book list"
+  description: "List Yuque books available to the current cookie-authenticated account without printing local credential files"
+  optional: ["--json"]
+  example: "yuque-local book list --json"
+  reference: "reference/agent-spec.md"
+
 book.download:
   cli: "yuque-local book download"
   description: "Download a Yuque knowledge base with resources and reports"

package/skills/yuque-cookie-plugin/reference/agent-spec.md

@@ -46,6 +46,16 @@ yuque-local auth logout --json
 
 Never request raw cookie values in the conversation.
 
+## Book Discovery
+
+Use the dedicated command:
+
+```bash
+yuque-local book list --json
+```
+
+Do not inspect, print, or copy the local `config.json` file to discover books. The CLI reads credentials internally and returns only book summaries.
+
 ## Safe Write Flow
 
 1. Snapshot the online document.