yuque-cookie-plugin 0.1.0 → 0.1.2

package/README.md

@@ -6,19 +6,19 @@
 
 这不是一个 OpenAPI wrapper，而是一个本地 CLI 操作面：AI 可以用它读取、整理、下载、快照、对比、格式化并安全写入语雀文档，尽量接近语雀编辑器原生 Lake 结构。
 
-## 当前 MVP 能力
-
-- Cookie 登录和登录态检测：`login`、`auth-status`
-- 读取语雀信息：`inspect`
-- 文档快照和结构对比：`snapshot`、`diff-lake`
-- Lake 和 Markdown 辅助转换：`lake-to-markdown`、`editor-serialize`
-- 安全写入：`apply-lake`、`update-lake`
-- 创建知识库和文档：`create-book`、`create-doc`
+## 当前能力
+
+- Cookie 登录、清理和登录态检测：`auth login`、`auth logout`、`auth status`
+- 读取语雀信息：`book inspect`、`doc inspect`
+- 文档快照和结构对比：`doc snapshot`、`lake diff`
+- Lake 和 Markdown 辅助转换：`lake to-markdown`、`lake serialize`
+- 安全写入：`doc apply-lake`、`doc update-lake`
+- 创建知识库和文档：`book create`、`doc create`
 - 标题原生编号：`--number-headings`
-- 整库/单篇下载：`download-book`、`download-doc`
+- 整库/单篇下载：`book download`、`doc download`
 - 下载资源清单、warning、retry 报告
 - 本地 VitePress 预览：`serve-book`
-- 上传并插入图片、PDF 附件：`upload-attach`、`insert-image`、`insert-attachment`
+- 上传并插入图片、PDF 附件：`doc upload`、`doc insert-image`、`doc insert-attachment`
 
 ## 安装
 
@@ -28,15 +28,16 @@
 npm install -g yuque-cookie-plugin
 ```
 
-如果 npm 版本还没有发布，也可以临时从 GitHub 安装：
+当前 npm 最新版本：
 
 ```bash
-npm install -g https://codeload.github.com/c-sunc6/yuque-cookie-plugin/tar.gz/refs/heads/main
+npm view yuque-cookie-plugin version
 ```
 
 安装后可直接运行：
 
 ```bash
+yuque-local --version
 yuque-local --help
 yuque-local auth login
 yuque-local doctor --json
@@ -51,14 +52,12 @@ cd yuque-cookie-plugin
 npm install
 ```
 
-本项目建议作为“项目内本地 CLI”使用：
+开发者也可以在源码目录中作为“项目内本地 CLI”使用：
 
 ```bash
 npm run yuque-local -- --help
 ```
 
-MVP 阶段不建议使用 `npm install -g`、`npm link` 或修改全局 npm 配置，避免影响电脑上的其他开发环境。
-
 ## 登录
 
 ```bash
@@ -99,6 +98,12 @@ npm run yuque-local -- auth status https://www.yuque.com/<your-login>/<your-book
 yuque-local auth login --manual
 ```
 
+清理本机保存的 Cookie：
+
+```bash
+yuque-local auth logout
+```
+
 也可以一次性传入参数，适合本地受控脚本：
 
 ```bash
@@ -217,12 +222,11 @@ npm test
 npm run yuque-local -- --help
 ```
 
-发布前本地打包验证：
+发布检查：
 
 ```bash
-npm pack
-npm install -g ./yuque-cookie-plugin-0.1.0.tgz
-yuque-local --help
+npm run release:check
+npm run release:smoke
 ```
 
 真实语雀验收不会进入默认 `npm test`。需要手动运行：
@@ -248,6 +252,7 @@ npm run real:acceptance -- \
 
 - 不要把真实 `_yuque_session` 或 `yuque_ctoken` 写入项目文件。
 - 不要提交 `~/.config/yuque-cookie-plugin/config.json`。
+- 需要清理本机凭据时运行 `yuque-local auth logout`。
 - `reports/`、`backups/`、`node_modules/` 已被 `.gitignore` 忽略。
 - 批量写入前先对单篇文档做真实实验。
 - 不确定 Lake 语义时，先 snapshot，再 diff，再实现。

package/dist/auth.js

@@ -1,6 +1,6 @@
 import { createServer } from 'node:http';
 import { existsSync, readFileSync } from 'node:fs';
-import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, rm, writeFile } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import os from 'node:os';
@@ -11,6 +11,14 @@ const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 export function getConfigFilePath() {
     return CONFIG_FILE;
 }
+export async function clearSavedCredentials() {
+    const existed = existsSync(CONFIG_FILE);
+    await rm(CONFIG_FILE, { force: true });
+    return {
+        config_file: CONFIG_FILE,
+        removed: existed
+    };
+}
 export function getCredentials(flags = {}) {
     const envSession = process.env[String(flags.sessionEnv || 'YUQUE_SESSION')];
     const envCtoken = process.env[String(flags.ctokenEnv || 'YUQUE_CTOKEN')];
@@ -28,7 +36,7 @@ export function getCredentials(flags = {}) {
     if (saved?.session && saved?.ctoken) {
         return { ...saved, extraCookies: { ...(saved.extraCookies || {}), ...extraCookies }, source: CONFIG_FILE };
     }
-    throw new Error('Missing Yuque credentials. Run "yuque-local login" to configure them in your browser.');
+    throw new Error('Missing Yuque credentials. Run "yuque-local auth login" to configure them in your browser.');
 }
 export function getCredentialStatus(flags = {}) {
     const envSession = process.env[String(flags.sessionEnv || 'YUQUE_SESSION')];

package/dist/cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import process from 'node:process';
 import path from 'node:path';
-import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { YuqueCookieClient } from "./client-cookie.js";
 import { diffLakeSnapshots } from "./lake-diff.js";
 import { writeJson } from "./fs-utils.js";
-import { getConfigFilePath, getCredentialStatus, getCredentials, loginWithBrowser, recordCredentialValidation } from "./auth.js";
+import { clearSavedCredentials, getConfigFilePath, getCredentialStatus, getCredentials, loginWithBrowser, recordCredentialValidation } from "./auth.js";
 import { serializeHtmlToLake } from "./editor-bridge.js";
 import { snapshotToMarkdown } from "./lake-markdown.js";
 import { downloadBook, downloadDocs } from "./downloader.js";
@@ -20,10 +20,12 @@ function help() {
     console.log(`yuque-local
 
 Usage:
+  yuque-local --version
   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 skill install|status [--json]
+  yuque-local skill install|status|uninstall [--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]
@@ -88,6 +90,7 @@ Options:
   --force                Recreate VitePress config
   --config-only          Generate serve-book VitePress config and exit
   -h, --help             Show help
+  -v, --version          Show version
 `);
 }
 function parseArgs(argv) {
@@ -129,6 +132,7 @@ function normalizeInvocation(argv) {
     const grouped = {
         auth: {
             login: 'login',
+            logout: 'logout',
             status: 'auth-status'
         },
         book: {
@@ -162,6 +166,14 @@ function normalizeInvocation(argv) {
 function toCamel(value) {
     return value.replace(/-([a-z])/g, (_match, char) => char.toUpperCase());
 }
+async function readPackageInfo() {
+    const packageJsonPath = path.join(PACKAGE_ROOT, 'package.json');
+    const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+    return {
+        name: packageJson.name || 'yuque-cookie-plugin',
+        version: packageJson.version || '0.0.0'
+    };
+}
 async function createClient(flags) {
     let credentials;
     try {
@@ -226,14 +238,13 @@ function printError(error) {
     console.error(`yuque-local error: ${message}`);
 }
 async function commandDoctor(flags) {
-    const packageJsonPath = path.join(PACKAGE_ROOT, 'package.json');
-    const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+    const packageInfo = await readPackageInfo();
     const status = getCredentialStatus(flags);
     const skillSource = path.join(PACKAGE_ROOT, 'skills', 'yuque-cookie-plugin');
     const data = {
         package: {
-            name: packageJson.name || 'yuque-cookie-plugin',
-            version: packageJson.version || '0.0.0',
+            name: packageInfo.name,
+            version: packageInfo.version,
             root: PACKAGE_ROOT
         },
         runtime: {
@@ -277,9 +288,24 @@ async function commandSkill(action, flags) {
             console.log(JSON.stringify(data, null, 2));
         return;
     }
+    const source = path.join(PACKAGE_ROOT, 'skills', 'yuque-cookie-plugin');
+    if (action === 'uninstall') {
+        const targets = skillTargets();
+        const removed = [];
+        for (const target of targets) {
+            const existed = existsSync(path.join(target, 'SKILL.md'));
+            await rm(target, { recursive: true, force: true });
+            removed.push({ path: target, removed: existed });
+        }
+        const data = { removed };
+        if (flags.json)
+            printJsonResult(jsonResult('success', 'skill uninstalled', data));
+        else
+            console.log(JSON.stringify(data, null, 2));
+        return;
+    }
     if (action !== 'install')
         throw new Error(`Unknown skill action: ${action}`);
-    const source = path.join(PACKAGE_ROOT, 'skills', 'yuque-cookie-plugin');
     if (!existsSync(path.join(source, 'SKILL.md')))
         throw new Error(`Skill source is missing: ${source}`);
     const installed = [];
@@ -311,6 +337,14 @@ async function main() {
         help();
         return;
     }
+    if (command === 'version' || command === '--version' || command === '-v') {
+        const packageInfo = await readPackageInfo();
+        if (flags.json)
+            printJsonResult(jsonResult('success', 'version loaded', packageInfo));
+        else
+            console.log(`${packageInfo.name}@${packageInfo.version}`);
+        return;
+    }
     if (command === 'diff-lake') {
         const [beforePath, afterPath] = positional;
         if (!beforePath || !afterPath)
@@ -354,6 +388,17 @@ async function main() {
         await loginWithBrowser(flags);
         return;
     }
+    if (command === 'logout') {
+        const result = await clearSavedCredentials();
+        printCommandResult({
+            ok: true,
+            ...result,
+            note: process.env.YUQUE_SESSION || process.env.YUQUE_CTOKEN
+                ? 'Environment credentials are still set in the current shell.'
+                : undefined
+        }, flags, 'auth credentials cleared');
+        return;
+    }
     if (command === 'doctor') {
         await commandDoctor(flags);
         return;

package/docs/npm-release.md

@@ -27,6 +27,16 @@ npm run release:check
 
 这个命令会执行类型检查、测试、构建、敏感信息扫描、npm 包名检查、`npm pack` 和临时 prefix 安装验证。
 
+## 发布后检查
+
+发布完成后运行：
+
+```bash
+npm run release:smoke
+```
+
+这个命令会从 npm registry 安装 `yuque-cookie-plugin@latest` 到临时 prefix，并验证 `yuque-local --help` 与 `yuque-local doctor --json`。
+
 确认 tarball 至少包含：
 
 - `bin/yuque-local.mjs`

package/docs/usage-zh.md

@@ -19,7 +19,15 @@
 
 ## 2. 安装和准备
 
-进入项目目录：
+普通用户推荐从 npm 安装：
+
+```bash
+npm install -g yuque-cookie-plugin
+yuque-local --version
+yuque-local --help
+```
+
+开发者进入项目目录：
 
 ```bash
 cd /home/mi/文档/yuque-cookie-plugin
@@ -34,6 +42,7 @@ npm install
 检查工具是否可运行：
 
 ```bash
+npm run yuque-local -- --version
 npm run yuque-local -- --help
 ```
 
@@ -88,6 +97,12 @@ Docker、SSH、远程服务器等无头环境中，推荐使用手动模式，
 yuque-local auth login --manual
 ```
 
+清理本机保存的 Cookie：
+
+```bash
+yuque-local auth logout
+```
+
 正常执行 `inspect`、`snapshot`、`download-book`、`download-doc` 等真实语雀命令成功后，也会刷新 `last_validated_at`。如果检测到 401、403、页面无法解析等登录态问题，CLI 会提示重新登录。
 
 ### 额外 Cookie

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuque-cookie-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -48,6 +48,7 @@
     "yuque-local": "tsx ./src/cli.ts",
     "real:acceptance": "tsx ./scripts/real-acceptance.ts",
     "release:check": "tsx ./scripts/prepublish-check.ts",
+    "release:smoke": "tsx ./scripts/registry-smoke.ts",
     "typecheck": "tsc --noEmit",
     "test": "npm run typecheck && vitest run && npm run yuque-local -- --help",
     "test:unit": "vitest run",

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

@@ -33,6 +33,7 @@ Legacy flat commands such as `yuque-local snapshot` and `yuque-local download-bo
 ```bash
 yuque-local auth login
 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 download <book-url> --dist-dir download --incremental --quiet --json
@@ -42,6 +43,7 @@ yuque-local doc snapshot <doc-url> --out /tmp/doc.snapshot.json --json
 yuque-local doc apply-lake <doc-url> --lake-file body_asl.html --dry-run --json
 yuque-local doc insert-image <doc-url> --file image.png --after-text "位置" --json
 yuque-local doc insert-attachment <doc-url> --file file.pdf --after-text "附件" --json
+yuque-local skill uninstall --json
 ```
 
 ## Workflow

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

@@ -14,6 +14,13 @@ auth.status:
   example: "yuque-local auth status https://www.yuque.com/user/book --json"
   reference: "reference/agent-spec.md"
 
+auth.logout:
+  cli: "yuque-local auth logout"
+  description: "Remove saved local Yuque cookies from the user config file"
+  optional: ["--json"]
+  example: "yuque-local auth logout --json"
+  reference: "reference/agent-spec.md"
+
 doctor:
   cli: "yuque-local doctor"
   description: "Inspect CLI version, runtime, auth config path, and skill install status"
@@ -28,6 +35,13 @@ skill.install:
   example: "yuque-local skill install --json"
   reference: "reference/agent-spec.md"
 
+skill.uninstall:
+  cli: "yuque-local skill uninstall"
+  description: "Remove the installed yuque-cookie-plugin AI skill from local supported agent skill directories"
+  optional: ["--json"]
+  example: "yuque-local skill uninstall --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

@@ -38,6 +38,12 @@ For Docker, SSH, or headless terminals:
 yuque-local auth login --manual
 ```
 
+To clear saved local cookies:
+
+```bash
+yuque-local auth logout --json
+```
+
 Never request raw cookie values in the conversation.
 
 ## Safe Write Flow