@sovovs/bycli 2.1.59 → 2.1.60

package/README.zh-CN.md

@@ -22,6 +22,27 @@ bycli <site> <command> --help   # 查看命令的参数和选项
 bycli <site> <command> -f yaml  # 结构化输出(适合 agent)
 ```
 
+### Linux 下载 IMA 知识库 PDF
+
+Linux 不需要安装 IMA 桌面客户端。安装 bycli 后，把 npm 包内的
+`extension/` 目录加载到 Chrome/Chromium 的开发者模式，启动 daemon，并在浏览器中登录
+`ima.qq.com`。Browser Bridge 会复用浏览器会话获取文件地址：
+
+```bash
+bycli daemon start
+bycli ima download "知识库名称" "文件名.pdf" --output ./downloads -f json
+```
+
+全局安装时扩展目录可用 `npm root -g` 定位：
+`$(npm root -g)/@sovovs/bycli/extension`。如果浏览器会话需要跨机器提供，可在受控浏览器端
+导出完整 `x-ima-cookie` 后设置 `BYCLI_IMA_COOKIE`，下载命令会切换到 Node 直连模式，Linux
+主机无需安装 IMA App 或运行 Chrome：
+
+```bash
+export BYCLI_IMA_COOKIE='完整的 x-ima-cookie'
+bycli ima download "知识库名称" "文件名.pdf" --output ./downloads -f json
+```
+
 示例:
 
 ```bash

package/cli-manifest.json

@@ -13549,11 +13549,11 @@
   {
     "site": "ima",
     "name": "download",
-    "description": "下载 ima 知识库中的原始文件",
+    "description": "下载 ima 知识库中的完整原始文件（Linux 无需 IMA App）",
     "access": "read",
     "domain": "ima.qq.com",
     "strategy": "cookie",
-    "browser": true,
+    "browser": "conditional",
     "args": [
       {
         "name": "knowledgeBase",
@@ -13586,7 +13586,7 @@
         "name": "viewerUrl",
         "type": "str",
         "required": false,
-        "help": "已打开的 IMA 查看器 URL（含 originUrl 签名参数）"
+        "help": "已打开的 IMA 查看器 URL（含 originUrl 签名参数；Linux 可省略）"
       }
     ],
     "columns": [

package/clis/ima/ax.js

@@ -163,12 +163,15 @@ func knowledgeWindow(_ app: AXUIElement) -> AXUIElement? {
     return windows(app).first(where: { !pageKnowledgeID($0).isEmpty })
 }
 
-func publicURL(in root: AXUIElement) -> String? {
+func publicURL(in root: AXUIElement, allowViewer: Bool = false) -> String? {
     func acceptable(_ value: String?) -> String? {
-        guard let value, value.hasPrefix("http://") || value.hasPrefix("https://") else { return nil }
+        guard let value else { return nil }
+        if allowViewer && value.hasPrefix("chrome-extension://") && value.contains("originUrl=") { return value }
+        guard value.hasPrefix("http://") || value.hasPrefix("https://") else { return nil }
         return value.contains("ima.qq.com") || value.contains("ima.copilot") ? nil : value
     }
     if let value = acceptable(stringAttribute(root, kAXURLAttribute as CFString)) { return value }
+    if let value = acceptable(stringAttribute(root, kAXDocumentAttribute as CFString)) { return value }
     for element in descendants(root, limit: 4000) {
         let elementRole = role(element)
         let description = stringAttribute(element, kAXDescriptionAttribute as CFString) ?? ""
@@ -176,6 +179,7 @@ func publicURL(in root: AXUIElement) -> String? {
             || (elementRole == (kAXTextFieldRole as String) && description.contains("地址"))
         guard isDocumentLocation else { continue }
         if let value = acceptable(stringAttribute(element, kAXURLAttribute as CFString)) { return value }
+        if let value = acceptable(stringAttribute(element, kAXDocumentAttribute as CFString)) { return value }
         if let value = acceptable(stringAttribute(element, kAXValueAttribute as CFString)) { return value }
     }
     return nil
@@ -197,8 +201,9 @@ func readPublicURL(
     let deadline = Date().addingTimeInterval(expectsURL ? 12 : 2)
     repeat {
         for window in windows(app).reversed()
-            where !known.contains(windowSignature(window)) && pageKnowledgeID(window).isEmpty {
-            if let url = publicURL(in: window) {
+            where (expectsURL || !known.contains(windowSignature(window)))
+                && (expectsURL || pageKnowledgeID(window).isEmpty) {
+            if let url = publicURL(in: window, allowViewer: expectsURL) {
                 return (window, url, CFEqual(window, knowledgeBeforeOpen))
             }
             let title = label(window) ?? ""
@@ -230,10 +235,12 @@ func closeArticlePage(app: AXUIElement, _ window: AXUIElement, reusedKnowledgeWi
 
 func pageKnowledgeID(_ window: AXUIElement) -> String {
     for element in [window] + descendants(window, limit: 4000) {
-        guard let value = stringAttribute(element, kAXURLAttribute as CFString),
-              let range = value.range(of: "knowledgeBaseId=") else { continue }
-        let suffix = value[range.upperBound...]
-        return String(suffix.prefix { $0 != "&" && $0 != "#" })
+        for key in [kAXURLAttribute, kAXDocumentAttribute] {
+            guard let value = stringAttribute(element, key as CFString),
+                  let range = value.range(of: "knowledgeBaseId=") else { continue }
+            let suffix = value[range.upperBound...]
+            return String(suffix.prefix { $0 != "&" && $0 != "#" })
+        }
     }
     return ""
 }
@@ -494,7 +501,7 @@ func scrapeCurrentFolder(
                 throw DriverError(code: "KNOWLEDGE_WINDOW_LOST", message: "Knowledge-base window disappeared")
             }
             var url: String? = nil
-            let expectsURL = contentType == "公众号" || contentType == "网页"
+            let expectsURL = contentType == "公众号" || contentType == "网页" || contentType == "PDF"
             if press(row.element), let opened = readPublicURL(
                 app: app,
                 excluding: before,
@@ -502,7 +509,7 @@ func scrapeCurrentFolder(
                 expectsURL: expectsURL
             ) {
                 url = opened.1
-                if !closeArticlePage(app: app, opened.0, reusedKnowledgeWindow: opened.2) {
+                if !closeArticlePage(app: app, opened.0, reusedKnowledgeWindow: opened.2 && contentType != "PDF") {
                     throw DriverError(code: "TAB_CLOSE_FAILED", message: "Could not close article tab '\(row.title)' safely")
                 }
             }
@@ -653,4 +660,28 @@ export function readKnowledgeBase(query) {
     return envelope;
 }
 
+const CURRENT_VIEWER_SCRIPT = String.raw`
+import Cocoa
+import ApplicationServices
+func attr(_ e: AXUIElement, _ key: CFString) -> AnyObject? { var v: CFTypeRef?; guard AXUIElementCopyAttributeValue(e, key, &v) == .success else { return nil }; return v }
+func children(_ e: AXUIElement) -> [AXUIElement] { attr(e, kAXChildrenAttribute as CFString) as? [AXUIElement] ?? [] }
+func string(_ e: AXUIElement, _ key: CFString) -> String? { if let v = attr(e, key) as? String { return v }; if let v = attr(e, key) as? URL { return v.absoluteString }; return nil }
+func all(_ root: AXUIElement) -> [AXUIElement] { var out = [root], q = [root], seen = Set<CFHashCode>(); while let e = q.popLast() { let h = CFHash(e); if seen.contains(h) { continue }; seen.insert(h); for c in children(e) { out.append(c); q.append(c) } }; return out }
+let apps = NSRunningApplication.runningApplications(withBundleIdentifier: "com.tencent.imamac")
+var urls: [String] = []
+for app in apps where !app.isTerminated { let root = AXUIElementCreateApplication(app.processIdentifier); let windows = attr(root, kAXWindowsAttribute as CFString) as? [AXUIElement] ?? []; for e in windows.flatMap(all) { for key in [kAXURLAttribute, kAXDocumentAttribute, kAXValueAttribute] { if let v = string(e, key as CFString), v.hasPrefix("chrome-extension://"), v.contains("originUrl=") && !urls.contains(v) { urls.append(v) } } } }
+let data = try! JSONSerialization.data(withJSONObject: urls, options: []); print(String(data: data, encoding: .utf8)!)
+`;
+
+export function readCurrentViewerUrl(title = '') {
+    if (process.platform !== 'darwin') return null;
+    try {
+        const output = execFileSync('swift', ['-'], { input: CURRENT_VIEWER_SCRIPT, encoding: 'utf8', timeout: 20_000, maxBuffer: 8 * 1024 * 1024, stdio: ['pipe', 'pipe', 'ignore'] });
+        const urls = String(output).trim().split(/\r?\n/).reverse().reduce((found, line) => {
+            try { const parsed = JSON.parse(line); return Array.isArray(parsed) ? parsed : found; } catch { return found; }
+        }, []);
+        return urls.find((url) => { try { const origin = new URL(url).searchParams.get('originUrl'); return !title || (origin && new URL(origin).searchParams.get('media_title') === title); } catch { return false; } }) || null;
+    } catch { return null; }
+}
+
 export const __test__ = { AX_KNOWLEDGE_SCRIPT, OPEN_KNOWLEDGE_APPLESCRIPT };

package/clis/ima/download.js

@@ -4,6 +4,7 @@ import { httpDownload } from '@sovovs/bycli/download';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { CommandExecutionError, EmptyResultError } from '@sovovs/bycli/errors';
 import { readImaMediaUrl, readKnowledgeBaseFromChrome } from './native-client.js';
+import { readCurrentViewerUrl } from './ax.js';
 import { extractOriginUrl, resolveOutputPath, sha256File } from './download-utils.js';
 
 function countPdfPages(filePath) {
@@ -16,29 +17,75 @@ export async function runDownloadCommand(page, kwargs, deps = {}) {
   const kb = String(kwargs.knowledgeBase ?? '').trim();
   const title = String(kwargs.file ?? '').trim();
   if (!kb || !title) throw new CommandExecutionError('knowledge base and file title are required');
-  const reader = deps.read ?? ((query) => readKnowledgeBaseFromChrome(page, query));
-  const envelope = await reader(kb);
+  const currentViewer = deps.readCurrentViewerUrl?.(title)
+    ?? (process.platform === 'darwin' ? readCurrentViewerUrl(title) : null);
+  const effectivePage = page ?? (process.env.BYCLI_IMA_COOKIE ? {
+    fetchJson: async (url, options = {}) => {
+      const response = await fetch(url, { method: options.method ?? 'GET', headers: options.headers, body: options.body === undefined ? undefined : JSON.stringify(options.body) });
+      const text = await response.text();
+      try { return JSON.parse(text); } catch { throw new Error(`IMA HTTP ${response.status}: invalid JSON response`); }
+    },
+  } : page);
+  const reader = deps.read ?? ((query) => readKnowledgeBaseFromChrome(effectivePage, query));
+  let envelope;
+  if (currentViewer) {
+    const origin = extractOriginUrl(currentViewer);
+    const parsed = new URL(origin);
+    envelope = {
+      knowledgeBase: kb,
+      items: [{ title, contentType: 'PDF', mediaId: parsed.searchParams.get('media_id') || '', url: currentViewer }],
+    };
+  } else {
+    try {
+      envelope = await reader(kb);
+    } catch (error) {
+      if (process.platform !== 'darwin') throw error;
+      const { readKnowledgeBase: readKnowledgeBaseFromDesktop } = await import('./ax.js');
+      envelope = await Promise.resolve(readKnowledgeBaseFromDesktop(kb));
+    }
+  }
   const items = (envelope?.items ?? []).filter((item) => item.title === title
     && (!kwargs.mediaId || item.mediaId === kwargs.mediaId));
   if (items.length === 0) throw new EmptyResultError('ima download', `File "${title}" was not found`);
   if (items.length > 1) throw new CommandExecutionError('Multiple files matched; specify --media-id');
   const item = items[0];
   let originUrl;
-  if (item.url) originUrl = item.url;
+  if (currentViewer) originUrl = extractOriginUrl(currentViewer);
+  if (item.url) {
+    originUrl = String(item.url).startsWith('chrome-extension://')
+      ? extractOriginUrl(item.url)
+      : item.url;
+  }
   if (!originUrl && kwargs.viewerUrl) originUrl = extractOriginUrl(kwargs.viewerUrl);
-  if (!originUrl && page.getCurrentUrl) {
+  if (!originUrl && page?.getCurrentUrl) {
     const currentUrl = await page.getCurrentUrl();
     if (currentUrl?.includes('originUrl=')) originUrl = extractOriginUrl(currentUrl);
   }
-  if (!originUrl && deps.readOriginalUrl) originUrl = await deps.readOriginalUrl(item);
-  if (!originUrl && page.fetchJson) originUrl = await readImaMediaUrl(page, { ...item, knowledgeBaseId: item.knowledgeBaseId || envelope.knowledgeBaseId });
+  let mediaError;
+  if (!originUrl && deps.readOriginalUrl) {
+    try {
+      originUrl = await deps.readOriginalUrl(item);
+    } catch (error) {
+      mediaError = error;
+    }
+  }
+  if (!originUrl && (effectivePage?.requestImaMedia || effectivePage?.fetchJson)) {
+    try {
+      originUrl = await readImaMediaUrl(effectivePage, { ...item, knowledgeBaseId: item.knowledgeBaseId || envelope.knowledgeBaseId });
+    } catch (error) {
+      mediaError = error;
+    }
+  }
   if (!originUrl && process.platform === 'darwin') {
     const { readKnowledgeBase: readKnowledgeBaseFromDesktop } = await import('./ax.js');
     const desktop = await Promise.resolve(readKnowledgeBaseFromDesktop(kb));
     const desktopItem = desktop?.items?.find((entry) => entry.title === title);
     if (desktopItem?.url) originUrl = desktopItem.url;
   }
-  if (!originUrl) throw new CommandExecutionError('IMA original file URL is unavailable; open the file in the IMA client first');
+  if (!originUrl) {
+    const message = mediaError instanceof Error ? mediaError.message : 'IMA original file URL is unavailable; open the file in the IMA client first';
+    throw new CommandExecutionError(message);
+  }
   const outputPath = resolveOutputPath(kwargs.output || '.', item.title);
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   const download = deps.httpDownload ?? httpDownload;
@@ -51,14 +98,14 @@ export async function runDownloadCommand(page, kwargs, deps = {}) {
 }
 
 cli({
-  site: 'ima', name: 'download', access: 'read', description: '下载 ima 知识库中的原始文件',
-  domain: 'ima.qq.com', strategy: Strategy.COOKIE, browser: true, navigateBefore: false,
+  site: 'ima', name: 'download', access: 'read', description: '下载 ima 知识库中的完整原始文件（Linux 无需 IMA App）',
+  domain: 'ima.qq.com', strategy: Strategy.COOKIE, browser: () => !process.env.BYCLI_IMA_COOKIE, navigateBefore: false,
   args: [
     { name: 'knowledgeBase', positional: true, required: true, help: '知识库名称或 ID' },
     { name: 'file', positional: true, required: true, help: '文件标题' },
     { name: 'output', flags: '--output <path>', default: '.', help: '输出文件或目录' },
     { name: 'mediaId', flags: '--media-id <id>', help: 'IMA mediaId，用于精确定位' },
-    { name: 'viewerUrl', flags: '--viewer-url <url>', help: '已打开的 IMA 查看器 URL（含 originUrl 签名参数）' },
+    { name: 'viewerUrl', flags: '--viewer-url <url>', help: '已打开的 IMA 查看器 URL（含 originUrl 签名参数；Linux 可省略）' },
   ],
   columns: ['path', 'title', 'contentType', 'size', 'sha256', 'pages'],
   func: (page, kwargs) => runDownloadCommand(page, kwargs),

package/clis/ima/native-client.js

@@ -2,6 +2,30 @@ import { listKnowledgeBases, readKnowledgeBaseFromApi } from './native-api.js';
 
 const IMA_WIKIS_URL = 'https://ima.qq.com/wikis';
 const IMA_GET_MEDIA_URL = 'https://ima.qq.com/cgi-bin/file_manager/get_media';
+const IMA_READER_URL = 'https://ima.qq.com/cgi-bin/knowledge_tab_reader';
+
+function imaBknFromCookie(cookie) {
+    const token = String(cookie).split(';').map((part) => part.trim())
+        .find((part) => part.startsWith('IMA-TOKEN='))?.slice('IMA-TOKEN='.length);
+    if (!token) return '';
+    let hash = 5381;
+    for (const character of token) hash += (hash << 5) + character.charCodeAt(0);
+    return String(hash & 0x7fffffff);
+}
+
+function directImaRequest(page, dependencies = {}) {
+    const imaCookie = dependencies.imaCookie ?? process.env.BYCLI_IMA_COOKIE;
+    if (!imaCookie || !page || typeof page.fetchJson !== 'function') return null;
+    const headers = {
+        'x-ima-cookie': String(imaCookie),
+        'x-ima-bkn': dependencies.imaBkn ?? imaBknFromCookie(imaCookie),
+        from_browser_ima: '1',
+        extension_version: String(dependencies.extensionVersion ?? process.env.BYCLI_IMA_EXTENSION_VERSION ?? '2.1.23'),
+    };
+    return (path, body) => page.fetchJson(`${IMA_READER_URL}${path}`, {
+        method: 'POST', headers, body,
+    });
+}
 
 function codedError(code, message) {
     return Object.assign(new Error(message), { code });
@@ -66,6 +90,8 @@ async function releaseImaAuth(page, authId) {
 }
 
 export async function readKnowledgeBasesFromChrome(page, dependencies = {}) {
+    const directRequest = directImaRequest(page, dependencies);
+    if (directRequest) return listKnowledgeBases(directRequest);
     const authId = await acquireImaChromeAuth(page, undefined, dependencies);
     try {
         return await listKnowledgeBases((path, body) => page.requestImaReader(authId, path, body));
@@ -75,6 +101,8 @@ export async function readKnowledgeBasesFromChrome(page, dependencies = {}) {
 }
 
 export async function readKnowledgeBaseFromChrome(page, query, dependencies = {}) {
+    const directRequest = directImaRequest(page, dependencies);
+    if (directRequest) return readKnowledgeBaseFromApi(query, directRequest);
     const authId = await acquireImaChromeAuth(page, query, dependencies);
     try {
         return await readKnowledgeBaseFromApi(
@@ -87,15 +115,38 @@ export async function readKnowledgeBaseFromChrome(page, query, dependencies = {}
 }
 
 export async function readImaMediaUrl(page, item, dependencies = {}) {
+    const imaCookie = dependencies.imaCookie ?? process.env.BYCLI_IMA_COOKIE;
+    if (imaCookie && page && typeof page.fetchJson === 'function') {
+        const response = await page.fetchJson(IMA_GET_MEDIA_URL, {
+            method: 'POST',
+            headers: {
+                'x-ima-cookie': String(imaCookie),
+                'x-ima-bkn': dependencies.imaBkn ?? imaBknFromCookie(imaCookie),
+                from_browser_ima: '1',
+                extension_version: String(dependencies.extensionVersion ?? process.env.BYCLI_IMA_EXTENSION_VERSION ?? '2.1.23'),
+            },
+            body: {
+                knowledge_base_id: String(item?.knowledgeBaseId ?? ''),
+                media_id: String(item?.mediaId ?? ''),
+                scene: dependencies.scene ?? 4,
+            },
+        });
+        const data = response && typeof response === 'object' ? response : {};
+        const url = data.jumpUrlInfo?.url ?? data.jump_url_info?.url;
+        if (Number(data.action) !== 1 || typeof url !== 'string' || !url) {
+            throw codedError('IMA_ORIGINAL_URL_UNAVAILABLE', data.toastText || data.toast_text || 'IMA did not return an exportable file URL');
+        }
+        return url;
+    }
     if (typeof page.requestImaMedia === 'function' && typeof page.startImaAuthCapture === 'function') {
         const authId = await acquireImaChromeAuth(page, item?.knowledgeBaseId, dependencies);
         try {
             const response = await page.requestImaMedia(authId, {
-                knowledgeBaseId: String(item?.knowledgeBaseId ?? ''),
-                mediaId: String(item?.mediaId ?? ''),
+                knowledge_base_id: String(item?.knowledgeBaseId ?? ''),
+                media_id: String(item?.mediaId ?? ''),
                 scene: dependencies.scene ?? 4,
-                ...(item?.shareId ? { shareId: String(item.shareId) } : {}),
-                ...(item?.sourceKnowledgeBaseId ? { sourceKnowledgeBaseId: String(item.sourceKnowledgeBaseId) } : {}),
+                ...(item?.shareId ? { share_id: String(item.shareId) } : {}),
+                ...(item?.sourceKnowledgeBaseId ? { source_knowledge_base_id: String(item.sourceKnowledgeBaseId) } : {}),
             });
             const data = response && typeof response === 'object' ? response : {};
             const url = data.jumpUrlInfo?.url ?? data.jump_url_info?.url;

package/dist/src/browser/cdp.js

@@ -232,6 +232,14 @@ class CDPPage extends BasePage {
                 const maxMs = options?.settleMs ?? 1000;
                 await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
             }
+            try {
+                const current = await this.evaluate('window.location.href');
+                if (typeof current === 'string' && current)
+                    this._lastUrl = current;
+            }
+            catch {
+                // Retain the requested URL when the document is still unavailable.
+            }
         }
         finally {
             if (guard)

package/dist/src/browser/page.js

@@ -108,6 +108,16 @@ export class Page extends BasePage {
             this._page = result.page;
         }
         this._lastUrl = url;
+        const refreshUrl = async () => {
+            try {
+                const current = await this.evaluate('window.location.href');
+                if (typeof current === 'string' && current)
+                    this._lastUrl = current;
+            }
+            catch {
+                // Navigation may still be settling; retain the requested URL as fallback.
+            }
+        };
         // Inject stealth + settle in a single round-trip instead of two sequential exec calls.
         // Some security-sensitive editors reject runtime environment patches, so callers can
         // retain the normal DOM-settle behavior while opting out of stealth injection.
@@ -139,6 +149,7 @@ export class Page extends BasePage {
                         throw retryErr;
                 }
             }
+            await refreshUrl();
         }
         else if (useStealth) {
             // Even with waitUntil='none', still inject stealth (best-effort)
@@ -151,6 +162,7 @@ export class Page extends BasePage {
             catch {
                 // Non-fatal: stealth is best-effort
             }
+            await refreshUrl();
         }
     }
     /** Get the active page identity (targetId) */

package/extension/README.md

@@ -0,0 +1,26 @@
+# byCLI Browser Bridge Extension
+
+The extension connects Chrome tabs to the local byCLI daemon. It uses Chrome
+extension APIs only as a transport and browser-control layer for explicit CLI
+commands.
+
+## Permission Notes
+
+- `debugger`: sends CDP commands to byCLI-controlled or bound tabs.
+- `tabs` / `tabGroups`: manages the dedicated byCLI automation container and
+  reports selected tab metadata back to the CLI.
+- `cookies`: reads cookies for browser-backed adapters that need authenticated
+  fetches.
+- `downloads`: surfaces download lifecycle to `bycli browser wait download`.
+  The extension observes started / in-progress / completed / failed downloads so
+  the CLI can wait for a file triggered by an automation command. byCLI
+  filters by the command's filename/URL pattern and timeout, and does not modify,
+  redirect, or persist browser download history.
+
+Suggested Chrome Web Store justification for `downloads`:
+
+> This extension uses `chrome.downloads` to surface download lifecycle
+> (started / in-progress / completed / failed) to the byCLI command-line tool,
+> so agents can wait for downloads triggered during an automation workflow. The
+> command filters by a user-provided filename or URL pattern and timeout. We do
+> not modify, redirect, or persist user download history.