@sovovs/bycli 2.1.38 → 2.1.39

package/cli-manifest.json

@@ -13546,6 +13546,38 @@
     "sourceFile": "hupu/unlike.js",
     "navigateBefore": false
   },
+  {
+    "site": "ima",
+    "name": "knowledge",
+    "description": "按名称或 ID 获取 ima 知识库中的文章标题、URL 与文件夹路径",
+    "access": "read",
+    "domain": "ima.qq.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "knowledgeBase",
+        "type": "string",
+        "required": true,
+        "positional": true,
+        "help": "知识库的完整名称或 ima 页面中的 knowledgeBaseId"
+      }
+    ],
+    "columns": [
+      "knowledgeBaseId",
+      "knowledgeBase",
+      "folderPath",
+      "title",
+      "url",
+      "contentType",
+      "addedDate"
+    ],
+    "defaultFormat": "json",
+    "type": "js",
+    "modulePath": "ima/knowledge.js",
+    "sourceFile": "ima/knowledge.js",
+    "navigateBefore": false
+  },
   {
     "site": "imdb",
     "name": "person",

package/clis/ima/ax.js

@@ -0,0 +1,656 @@
+import { execFileSync } from 'node:child_process';
+
+import { normalizeArticleUrl } from './utils.js';
+
+const OPEN_KNOWLEDGE_APPLESCRIPT = [
+    'tell application "System Events" to tell process "ima.copilot"',
+    'set frontmost to true',
+    'if exists front window then',
+    'repeat with itemRef in (entire contents of front window)',
+    'try',
+    'if description of itemRef is "知识库" then click itemRef',
+    'end try',
+    'end repeat',
+    'end if',
+    'end tell',
+    'delay 1',
+];
+
+const AX_KNOWLEDGE_SCRIPT = String.raw`
+import Cocoa
+import ApplicationServices
+
+struct DriverError: Error {
+    let code: String
+    let message: String
+}
+
+struct Candidate {
+    let name: String
+    let id: String
+    let element: AXUIElement
+}
+
+let query = CommandLine.arguments.dropFirst().first ?? ""
+let bundleID = "com.tencent.imamac"
+
+func attribute(_ element: AXUIElement, _ name: CFString) -> AnyObject? {
+    var value: CFTypeRef?
+    guard AXUIElementCopyAttributeValue(element, name, &value) == .success else { return nil }
+    return value
+}
+
+func stringAttribute(_ element: AXUIElement, _ name: CFString) -> String? {
+    if let value = attribute(element, name) as? String { return value }
+    if let value = attribute(element, name) as? URL { return value.absoluteString }
+    return nil
+}
+
+func elementAttribute(_ element: AXUIElement, _ name: CFString) -> AXUIElement? {
+    guard let value = attribute(element, name) else { return nil }
+    return (value as! AXUIElement)
+}
+
+func children(_ element: AXUIElement) -> [AXUIElement] {
+    return attribute(element, kAXChildrenAttribute as CFString) as? [AXUIElement] ?? []
+}
+
+func role(_ element: AXUIElement) -> String {
+    return stringAttribute(element, kAXRoleAttribute as CFString) ?? ""
+}
+
+func label(_ element: AXUIElement) -> String? {
+    for key in [kAXTitleAttribute, kAXDescriptionAttribute, kAXValueAttribute, kAXHelpAttribute] {
+        if let value = stringAttribute(element, key as CFString), !value.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+            return value.trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+    }
+    return nil
+}
+
+func descendants(_ root: AXUIElement, limit: Int = 12000) -> [AXUIElement] {
+    var result: [AXUIElement] = []
+    var queue = children(root)
+    var seen = Set<CFHashCode>()
+    while !queue.isEmpty && result.count < limit {
+        let item = queue.removeFirst()
+        let hash = CFHash(item)
+        if seen.contains(hash) { continue }
+        seen.insert(hash)
+        result.append(item)
+        queue.append(contentsOf: children(item))
+    }
+    return result
+}
+
+func actions(_ element: AXUIElement) -> [String] {
+    var names: CFArray?
+    guard AXUIElementCopyActionNames(element, &names) == .success else { return [] }
+    return names as? [String] ?? []
+}
+
+func pause(_ seconds: TimeInterval) {
+    RunLoop.current.run(until: Date().addingTimeInterval(seconds))
+}
+
+func clickCenter(_ element: AXUIElement) -> Bool {
+    guard let positionValue = attribute(element, kAXPositionAttribute as CFString),
+          let sizeValue = attribute(element, kAXSizeAttribute as CFString) else { return false }
+    let rawPosition = positionValue as! AXValue
+    let rawSize = sizeValue as! AXValue
+    var position = CGPoint.zero
+    var size = CGSize.zero
+    guard AXValueGetValue(rawPosition, .cgPoint, &position),
+          AXValueGetValue(rawSize, .cgSize, &size), size.width > 1, size.height > 1 else { return false }
+    let point = CGPoint(x: position.x + size.width / 2, y: position.y + size.height / 2)
+    guard let down = CGEvent(mouseEventSource: nil, mouseType: .leftMouseDown, mouseCursorPosition: point, mouseButton: .left),
+          let up = CGEvent(mouseEventSource: nil, mouseType: .leftMouseUp, mouseCursorPosition: point, mouseButton: .left) else { return false }
+    down.post(tap: CGEventTapLocation.cghidEventTap)
+    up.post(tap: CGEventTapLocation.cghidEventTap)
+    return true
+}
+
+func frame(_ element: AXUIElement) -> CGRect? {
+    guard let positionValue = attribute(element, kAXPositionAttribute as CFString),
+          let sizeValue = attribute(element, kAXSizeAttribute as CFString) else { return nil }
+    var position = CGPoint.zero
+    var size = CGSize.zero
+    guard AXValueGetValue(positionValue as! AXValue, .cgPoint, &position),
+          AXValueGetValue(sizeValue as! AXValue, .cgSize, &size) else { return nil }
+    return CGRect(origin: position, size: size)
+}
+
+func actionable(_ element: AXUIElement) -> AXUIElement? {
+    var current: AXUIElement? = element
+    for _ in 0..<7 {
+        guard let item = current else { return nil }
+        if actions(item).contains(kAXPressAction as String) { return item }
+        current = elementAttribute(item, kAXParentAttribute as CFString)
+    }
+    return nil
+}
+
+@discardableResult
+func press(_ element: AXUIElement) -> Bool {
+    if let target = actionable(element), AXUIElementPerformAction(target, kAXPressAction as CFString) == .success {
+        return true
+    }
+    var current: AXUIElement? = element
+    for _ in 0..<5 {
+        guard let item = current else { return false }
+        if role(item) == (kAXGroupRole as String), clickCenter(item) { return true }
+        current = elementAttribute(item, kAXParentAttribute as CFString)
+    }
+    return clickCenter(element)
+}
+
+func waitUntil(_ timeout: TimeInterval, _ condition: () -> Bool) -> Bool {
+    let deadline = Date().addingTimeInterval(timeout)
+    repeat {
+        if condition() { return true }
+        RunLoop.current.run(until: Date().addingTimeInterval(0.15))
+    } while Date() < deadline
+    return false
+}
+
+func windows(_ app: AXUIElement) -> [AXUIElement] {
+    let all = attribute(app, kAXWindowsAttribute as CFString) as? [AXUIElement] ?? []
+    return all.filter { !children($0).isEmpty }
+        .sorted { descendants($0, limit: 300).count > descendants($1, limit: 300).count }
+}
+
+func knowledgeWindow(_ app: AXUIElement) -> AXUIElement? {
+    return windows(app).first(where: { !pageKnowledgeID($0).isEmpty })
+}
+
+func publicURL(in root: AXUIElement) -> String? {
+    func acceptable(_ value: String?) -> String? {
+        guard let value, 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 }
+    for element in descendants(root, limit: 4000) {
+        let elementRole = role(element)
+        let description = stringAttribute(element, kAXDescriptionAttribute as CFString) ?? ""
+        let isDocumentLocation = elementRole == "AXWebArea"
+            || (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, kAXValueAttribute as CFString)) { return value }
+    }
+    return nil
+}
+
+func windowSignature(_ window: AXUIElement) -> String {
+    let title = label(window) ?? ""
+    let document = stringAttribute(window, kAXDocumentAttribute as CFString) ?? ""
+    return "\(title)|\(document)"
+}
+
+func readPublicURL(
+    app: AXUIElement,
+    excluding known: Set<String>,
+    knowledgeBeforeOpen: AXUIElement,
+    expectsURL: Bool
+) -> (AXUIElement, String?, Bool)? {
+    var fallback: (AXUIElement, String?, Bool)? = nil
+    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) {
+                return (window, url, CFEqual(window, knowledgeBeforeOpen))
+            }
+            let title = label(window) ?? ""
+            if !title.isEmpty { fallback = (window, nil, CFEqual(window, knowledgeBeforeOpen)) }
+        }
+        pause(0.15)
+    } while Date() < deadline
+    return fallback
+}
+
+func closeArticlePage(app: AXUIElement, _ window: AXUIElement, reusedKnowledgeWindow: Bool) -> Bool {
+    let openedSignature = windowSignature(window)
+    _ = AXUIElementPerformAction(window, kAXRaiseAction as CFString)
+    if let owner = elementAttribute(window, kAXParentAttribute as CFString) {
+        _ = AXUIElementSetAttributeValue(owner, kAXFocusedWindowAttribute as CFString, window)
+    }
+    pause(0.2)
+    let keyCode: CGKeyCode = reusedKnowledgeWindow ? 33 : 13 // Command-[ goes back; Command-W closes a new tab/window.
+    guard let down = CGEvent(keyboardEventSource: nil, virtualKey: keyCode, keyDown: true),
+          let up = CGEvent(keyboardEventSource: nil, virtualKey: keyCode, keyDown: false) else { return false }
+    down.flags = .maskCommand
+    up.flags = .maskCommand
+    down.post(tap: .cghidEventTap)
+    up.post(tap: .cghidEventTap)
+    return waitUntil(6) {
+        knowledgeWindow(app) != nil && !windows(app).contains(where: { windowSignature($0) == openedSignature })
+    }
+}
+
+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 != "#" })
+    }
+    return ""
+}
+
+func pageKnowledgeName(_ window: AXUIElement) -> String {
+    for element in descendants(window, limit: 4000) {
+        guard let value = stringAttribute(element, kAXURLAttribute as CFString),
+              value.contains("knowledgeBaseId="), let name = label(element) else { continue }
+        return name
+    }
+    return ""
+}
+
+func exactElements(_ root: AXUIElement, _ text: String) -> [AXUIElement] {
+    return descendants(root).filter { label($0) == text }
+}
+
+func sidebarTextElements(_ window: AXUIElement) -> [AXUIElement] {
+    let windowFrame = frame(window) ?? .zero
+    return descendants(window).filter { element in
+        guard role(element) == (kAXStaticTextRole as String),
+              let text = label(element), text.count > 0, text.count < 100,
+              let itemFrame = frame(element) else { return false }
+        let inSidebar = itemFrame.midX < windowFrame.minX + min(430, windowFrame.width * 0.35)
+        return inSidebar && !["个人知识库", "共享知识库", "订阅知识库"].contains(text)
+    }
+}
+
+func navigateToKnowledge(app: AXUIElement) throws -> AXUIElement {
+    if let existing = knowledgeWindow(app) { return existing }
+    guard !windows(app).isEmpty else {
+        throw DriverError(code: "IMA_NOT_RUNNING", message: "ima is running but has no visible window")
+    }
+    var knowledgeTab: AXUIElement? = nil
+    var navigationWindow: AXUIElement? = nil
+    _ = waitUntil(10) {
+        for window in windows(app) {
+            if let tab = exactElements(window, "知识库").first {
+                knowledgeTab = tab
+                navigationWindow = window
+                return true
+            }
+        }
+        return false
+    }
+    if let tab = knowledgeTab {
+        if let window = navigationWindow {
+            _ = AXUIElementPerformAction(window, kAXRaiseAction as CFString)
+            _ = AXUIElementSetAttributeValue(app, kAXFocusedWindowAttribute as CFString, window)
+            pause(0.2)
+        }
+        _ = clickCenter(tab)
+        _ = waitUntil(6) { knowledgeWindow(app) != nil }
+    }
+    if let selected = knowledgeWindow(app) { return selected }
+    throw DriverError(code: "KNOWLEDGE_NOT_FOUND", message: "ima did not open its knowledge-base page")
+}
+
+func selectKnowledge(app: AXUIElement, window: AXUIElement) throws -> Candidate {
+    let currentID = pageKnowledgeID(window)
+    let currentName = pageKnowledgeName(window)
+    if query == currentID {
+        return Candidate(name: currentName, id: currentID, element: window)
+    }
+    // Exact visible-name lookup is restricted to knowledge-base rows.
+    let exactMatches = sidebarTextElements(window).filter { label($0) == query }
+    if exactMatches.count > 1 {
+        throw DriverError(code: "AMBIGUOUS_KNOWLEDGE", message: "Multiple knowledge bases are named '\(query)'; use an ID")
+    }
+    if query == currentName {
+        return Candidate(name: currentName, id: currentID, element: window)
+    }
+    if let element = exactMatches.first, press(element) {
+        _ = waitUntil(4) {
+            guard let current = knowledgeWindow(app) else { return false }
+            return pageKnowledgeName(current) == query
+        }
+        let current = knowledgeWindow(app) ?? window
+        let candidate = Candidate(name: pageKnowledgeName(current), id: pageKnowledgeID(current), element: element)
+        if query == candidate.name { return candidate }
+    }
+
+    // ID lookup: visit sidebar rows and compare the ID exposed by ima's page URL.
+    let visible = sidebarTextElements(window)
+    var checked = Set<String>()
+    for element in visible {
+        guard let name = label(element) else { continue }
+        let nodeID = (attribute(element, "ChromeAXNodeId" as CFString) as? NSNumber)?.stringValue
+        let identity = nodeID ?? "\(CFHash(element)):\(name)"
+        guard !checked.contains(identity), press(element) else { continue }
+        checked.insert(identity)
+        pause(0.8)
+        let current = knowledgeWindow(app) ?? window
+        let candidate = Candidate(name: pageKnowledgeName(current), id: pageKnowledgeID(current), element: element)
+        if query == candidate.name || query == candidate.id { return candidate }
+    }
+    throw DriverError(code: "KNOWLEDGE_NOT_FOUND", message: "No knowledge base exactly matches '\(query)'")
+}
+
+let datePattern = try! NSRegularExpression(pattern: #"(?:\d{4}[-/.])?\d{1,2}[-/.]\d{1,2}|\d{1,2}/\d{1,2}"#)
+let folderPattern = try! NSRegularExpression(pattern: #"^\d+\s*项(?:\s|$)"#)
+let knownTypes = ["公众号", "网页", "PDF", "文档", "文件", "笔记", "视频", "音频", "图片"]
+
+func firstMatch(_ regex: NSRegularExpression, _ value: String) -> Bool {
+    return regex.firstMatch(in: value, range: NSRange(value.startIndex..., in: value)) != nil
+}
+
+func textValues(_ element: AXUIElement) -> [String] {
+    var values: [String] = []
+    for item in [element] + descendants(element, limit: 100) {
+        if let value = label(item), !values.contains(value) { values.append(value) }
+    }
+    return values
+}
+
+struct Row {
+    let element: AXUIElement
+    let identity: String
+    let bounds: CGRect
+    let title: String
+    let metadata: String
+    let isFolder: Bool
+}
+
+struct FolderTarget {
+    let title: String
+    let identity: String
+    let ordinal: Int
+}
+
+func rows(in window: AXUIElement) -> [Row] {
+    var result: [Row] = []
+    let groups = descendants(window)
+        .filter { role($0) == (kAXGroupRole as String) }
+        .sorted { descendants($0, limit: 100).count < descendants($1, limit: 100).count }
+    for element in groups {
+        let values = textValues(element).filter { $0.count < 240 }
+        guard values.count >= 2 && values.count <= 7 else { continue }
+        let folderMetadata = values.first(where: { firstMatch(folderPattern, $0) })
+        let rowType = values.first(where: { value in knownTypes.contains(where: { value.hasPrefix($0) }) })
+        let rowDate = values.first(where: { firstMatch(datePattern, $0) })
+        let metadata: String
+        let isFolder: Bool
+        if let folderMetadata {
+            metadata = folderMetadata
+            isFolder = true
+        } else if let rowType, let rowDate {
+            metadata = "\(rowType) \(rowDate)"
+            isFolder = false
+        } else {
+            continue
+        }
+        guard let title = values.first(where: {
+            $0 != metadata && !knownTypes.contains($0) && !firstMatch(datePattern, $0)
+                && !$0.hasPrefix("/") && $0 != "没有更多内容了"
+        }) else { continue }
+        let bounds = frame(element) ?? .zero
+        let overlapsAcceptedRow = result.contains { accepted in
+            guard accepted.title == title && accepted.metadata == metadata,
+                  !accepted.bounds.isEmpty && !bounds.isEmpty else { return false }
+            return accepted.bounds.contains(CGPoint(x: bounds.midX, y: bounds.midY))
+                || bounds.contains(CGPoint(x: accepted.bounds.midX, y: accepted.bounds.midY))
+        }
+        if overlapsAcceptedRow { continue }
+        let nodeID = (attribute(element, "ChromeAXNodeId" as CFString) as? NSNumber)?.stringValue
+        let identity = nodeID ?? "\(CFHash(element)):\(title):\(metadata)"
+        result.append(Row(
+            element: element,
+            identity: identity,
+            bounds: bounds,
+            title: title,
+            metadata: metadata,
+            isFolder: isFolder
+        ))
+    }
+    return result
+}
+
+func scrollPage(_ window: AXUIElement) -> Bool {
+    for element in descendants(window).reversed() where role(element) == (kAXScrollAreaRole as String) {
+        let action = "AXScrollDownByPage" as CFString
+        if actions(element).contains(action as String), AXUIElementPerformAction(element, action) == .success { return true }
+        if let bar = elementAttribute(element, kAXVerticalScrollBarAttribute as CFString),
+           let current = attribute(bar, kAXValueAttribute as CFString) as? NSNumber {
+            let next = min(1, current.doubleValue + 0.72)
+            if next > current.doubleValue + 0.001 {
+                return AXUIElementSetAttributeValue(bar, kAXValueAttribute as CFString, NSNumber(value: next)) == .success
+            }
+        }
+    }
+    return false
+}
+
+func scrollToTop(_ window: AXUIElement) {
+    for element in descendants(window) where role(element) == (kAXScrollAreaRole as String) {
+        if let bar = elementAttribute(element, kAXVerticalScrollBarAttribute as CFString) {
+            _ = AXUIElementSetAttributeValue(bar, kAXValueAttribute as CFString, NSNumber(value: 0))
+        }
+    }
+    pause(0.5)
+}
+
+func findFolderRow(app: AXUIElement, target: FolderTarget) -> Row? {
+    guard let initial = knowledgeWindow(app) else { return nil }
+    scrollToTop(initial)
+    var visitedPages = Set<String>()
+    var fallbackSeen = Set<String>()
+    var matchingTitleSeen = 0
+    while let window = knowledgeWindow(app) {
+        let folders = rows(in: window).filter { $0.isFolder }
+        let pageIdentity = rows(in: window).map(\.identity).sorted().joined(separator: "|")
+        if visitedPages.contains(pageIdentity) { return nil }
+        visitedPages.insert(pageIdentity)
+        if let match = folders.first(where: { $0.identity == target.identity }) { return match }
+        let newTitleMatches = folders.filter {
+            $0.title == target.title && !fallbackSeen.contains($0.identity)
+        }
+        if target.ordinal >= matchingTitleSeen
+            && target.ordinal < matchingTitleSeen + newTitleMatches.count {
+            return newTitleMatches[target.ordinal - matchingTitleSeen]
+        }
+        for match in newTitleMatches { fallbackSeen.insert(match.identity) }
+        matchingTitleSeen += newTitleMatches.count
+        if !scrollPage(window) { return nil }
+        pause(0.8)
+    }
+    return nil
+}
+
+func scrapeCurrentFolder(
+    app: AXUIElement,
+    knowledge: Candidate,
+    folderPath: [String],
+    folderTargets: inout [FolderTarget]
+) throws -> [[String: Any]] {
+    var output: [[String: Any]] = []
+    var seen = Set<String>()
+    var idleRounds = 0
+    while idleRounds < 2 {
+        guard let window = knowledgeWindow(app) else { break }
+        let pageRows = rows(in: window)
+        var foldersAdded = 0
+        for folder in pageRows where folder.isFolder
+            && !folderTargets.contains(where: { $0.identity == folder.identity }) {
+            let ordinal = folderTargets.filter { $0.title == folder.title }.count
+            folderTargets.append(FolderTarget(title: folder.title, identity: folder.identity, ordinal: ordinal))
+            foldersAdded += 1
+        }
+        var added = 0
+        for row in pageRows where !row.isFolder && !seen.contains(row.identity) {
+            seen.insert(row.identity)
+            added += 1
+            let parts = row.metadata.split(separator: " ").map(String.init)
+            let contentType = parts.first ?? ""
+            let addedDate = parts.first(where: { firstMatch(datePattern, $0) }) ?? ""
+            let before = Set(windows(app).map(windowSignature))
+            guard let knowledgeBeforeOpen = knowledgeWindow(app) else {
+                throw DriverError(code: "KNOWLEDGE_WINDOW_LOST", message: "Knowledge-base window disappeared")
+            }
+            var url: String? = nil
+            let expectsURL = contentType == "公众号" || contentType == "网页"
+            if press(row.element), let opened = readPublicURL(
+                app: app,
+                excluding: before,
+                knowledgeBeforeOpen: knowledgeBeforeOpen,
+                expectsURL: expectsURL
+            ) {
+                url = opened.1
+                if !closeArticlePage(app: app, opened.0, reusedKnowledgeWindow: opened.2) {
+                    throw DriverError(code: "TAB_CLOSE_FAILED", message: "Could not close article tab '\(row.title)' safely")
+                }
+            }
+            output.append([
+                "knowledgeBaseId": knowledge.id,
+                "knowledgeBase": knowledge.name,
+                "folderPath": folderPath,
+                "title": row.title,
+                "url": url ?? NSNull(),
+                "contentType": contentType,
+                "addedDate": addedDate
+            ])
+        }
+        if added == 0 && foldersAdded == 0 { idleRounds += 1 } else { idleRounds = 0 }
+        guard let current = knowledgeWindow(app), scrollPage(current) else { break }
+        pause(0.8)
+    }
+    return output
+}
+
+func scrapeFolderRecursive(app: AXUIElement, knowledge: Candidate, folderPath: [String], depth: Int = 0) throws -> [[String: Any]] {
+    guard depth < 20, knowledgeWindow(app) != nil else { return [] }
+    var folderTargets: [FolderTarget] = []
+    var output = try scrapeCurrentFolder(
+        app: app,
+        knowledge: knowledge,
+        folderPath: folderPath,
+        folderTargets: &folderTargets
+    )
+    for folderTarget in folderTargets {
+        guard let folder = findFolderRow(app: app, target: folderTarget), press(folder.element) else {
+            throw DriverError(code: "FOLDER_NAVIGATION_FAILED", message: "Could not open folder '\(folderTarget.title)'")
+        }
+        pause(1)
+        output.append(contentsOf: try scrapeFolderRecursive(
+            app: app,
+            knowledge: knowledge,
+            folderPath: folderPath + [folderTarget.title],
+            depth: depth + 1
+        ))
+        let parentName = folderPath.last ?? knowledge.name
+        guard let childWindow = knowledgeWindow(app),
+              let parentCrumb = exactElements(childWindow, parentName).last,
+              press(parentCrumb) else {
+            throw DriverError(code: "FOLDER_NAVIGATION_FAILED", message: "Could not return to folder '\(parentName)'")
+        }
+        pause(1)
+    }
+    return output
+}
+
+func scrapeKnowledge(app: AXUIElement, knowledge: Candidate) throws -> [[String: Any]] {
+    return try scrapeFolderRecursive(app: app, knowledge: knowledge, folderPath: [])
+}
+
+func emit(_ value: [String: Any]) {
+    let data = try! JSONSerialization.data(withJSONObject: value, options: [])
+    print(String(data: data, encoding: .utf8)!)
+}
+
+do {
+    guard !query.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+        throw DriverError(code: "EMPTY_QUERY", message: "Knowledge-base name or ID is required")
+    }
+    guard AXIsProcessTrusted() else {
+        throw DriverError(code: "ACCESSIBILITY_PERMISSION_REQUIRED", message: "Enable Accessibility access for the terminal running bycli")
+    }
+    let runningApps = NSRunningApplication.runningApplications(withBundleIdentifier: bundleID)
+    guard !runningApps.isEmpty else {
+        throw DriverError(code: "IMA_NOT_RUNNING", message: "Open ima before running this command")
+    }
+    var selected: (NSRunningApplication, AXUIElement)? = nil
+    for running in runningApps where !running.isTerminated {
+        let candidate = AXUIElementCreateApplication(running.processIdentifier)
+        if !windows(candidate).isEmpty { selected = (running, candidate); break }
+    }
+    guard let (running, app) = selected else {
+        throw DriverError(code: "IMA_NOT_RUNNING", message: "ima is running but has no visible window")
+    }
+    running.activate()
+    let window = try navigateToKnowledge(app: app)
+    let knowledge = try selectKnowledge(app: app, window: window)
+    guard let contentWindow = knowledgeWindow(app),
+          descendants(contentWindow).contains(where: { role($0) == "AXWebArea" }) else {
+        throw DriverError(
+            code: "ACCESSIBILITY_CONTENT_UNAVAILABLE",
+            message: "ima's article list is not exposed to macOS Accessibility; quit ima and reopen it with --force-renderer-accessibility"
+        )
+    }
+    let items = try scrapeKnowledge(app: app, knowledge: knowledge)
+    emit(["ok": true, "knowledgeBaseId": knowledge.id, "knowledgeBase": knowledge.name, "items": items])
+} catch let error as DriverError {
+    emit(["ok": false, "code": error.code, "message": error.message])
+} catch {
+    emit(["ok": false, "code": "AX_DRIVER_FAILED", "message": String(describing: error)])
+}
+`;
+
+export function parseDriverEnvelope(output) {
+    const lines = String(output).trim().split(/\r?\n/).reverse();
+    let envelope;
+    for (const line of lines) {
+        try {
+            envelope = JSON.parse(line);
+            break;
+        } catch {
+            // Swift may print compiler diagnostics around the single JSON result.
+        }
+    }
+    if (!envelope || typeof envelope !== 'object') throw new Error('ima driver returned invalid JSON');
+    if (typeof envelope.ok !== 'boolean') throw new Error('ima driver response is missing ok flag');
+    return envelope;
+}
+
+export function readKnowledgeBase(query) {
+    if (process.platform !== 'darwin') {
+        return { ok: false, code: 'UNSUPPORTED_PLATFORM', message: 'The ima adapter currently requires macOS' };
+    }
+    try {
+        execFileSync('pgrep', ['-x', 'ima.copilot'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch {
+        execFileSync('open', ['-a', 'ima.copilot', '--args', '--force-renderer-accessibility'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        execFileSync('osascript', ['-e', 'delay 2'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    try {
+        execFileSync('osascript', OPEN_KNOWLEDGE_APPLESCRIPT.flatMap((line) => ['-e', line]), {
+            encoding: 'utf8',
+            timeout: 15_000,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    } catch {
+        // The Swift driver below returns the actionable typed error.
+    }
+    const output = execFileSync('swift', ['-', String(query)], {
+        input: AX_KNOWLEDGE_SCRIPT,
+        encoding: 'utf8',
+        timeout: 30 * 60 * 1000,
+        maxBuffer: 50 * 1024 * 1024,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const envelope = parseDriverEnvelope(output);
+    if (Array.isArray(envelope.items)) {
+        envelope.items = envelope.items.map((item) => ({ ...item, url: normalizeArticleUrl(item.url) }));
+    }
+    return envelope;
+}
+
+export const __test__ = { AX_KNOWLEDGE_SCRIPT, OPEN_KNOWLEDGE_APPLESCRIPT };

package/clis/ima/knowledge.js

@@ -0,0 +1,95 @@
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import {
+    ArgumentError,
+    CommandExecutionError,
+    ConfigError,
+    EmptyResultError,
+} from '@sovovs/bycli/errors';
+
+import { readKnowledgeBaseFromChrome } from './native-client.js';
+import { toKnowledgeRow } from './utils.js';
+
+const COMMAND = 'ima knowledge';
+
+function throwDriverError(envelope) {
+    const message = envelope?.message || 'ima reader failed';
+    switch (envelope?.code) {
+        case 'EMPTY_QUERY':
+        case 'AMBIGUOUS_KNOWLEDGE':
+            throw new ArgumentError(message);
+        case 'KNOWLEDGE_NOT_FOUND':
+            throw new EmptyResultError(COMMAND, message);
+        case 'IMA_CHROME_AUTH_REQUIRED':
+            throw new ConfigError(
+                message,
+                'Open https://ima.qq.com/wikis in Chrome, sign in, then retry with the latest bycli Browser Bridge extension.',
+            );
+        default:
+            throw new CommandExecutionError(message);
+    }
+}
+
+export async function runKnowledgeCommand(kwargs, read) {
+    const query = String(kwargs?.knowledgeBase ?? '').trim();
+    if (!query) {
+        throw new ArgumentError('knowledge-base name or ID is required');
+    }
+
+    let envelope;
+    try {
+        envelope = await read(query);
+    } catch (error) {
+        if (error instanceof ArgumentError || error instanceof ConfigError
+            || error instanceof EmptyResultError || error instanceof CommandExecutionError) {
+            throw error;
+        }
+        if (error && typeof error === 'object' && typeof error.code === 'string') {
+            throwDriverError({ code: error.code, message: error.message });
+        }
+        throw new CommandExecutionError(
+            `ima knowledge reader failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    }
+    if (!envelope?.ok) throwDriverError(envelope);
+    if (!Array.isArray(envelope.items)) {
+        throw new CommandExecutionError('ima knowledge reader returned malformed items');
+    }
+    if (envelope.items.length === 0) {
+        throw new EmptyResultError(COMMAND, `Knowledge base "${query}" contains no readable articles.`);
+    }
+    return envelope.items.map(toKnowledgeRow);
+}
+
+export const knowledgeCommand = cli({
+    site: 'ima',
+    name: 'knowledge',
+    access: 'read',
+    description: '按名称或 ID 获取 ima 知识库中的文章标题、URL 与文件夹路径',
+    domain: 'ima.qq.com',
+    defaultFormat: 'json',
+    args: [
+        {
+            name: 'knowledgeBase',
+            type: 'string',
+            required: true,
+            positional: true,
+            help: '知识库的完整名称或 ima 页面中的 knowledgeBaseId',
+        },
+    ],
+    columns: [
+        'knowledgeBaseId',
+        'knowledgeBase',
+        'folderPath',
+        'title',
+        'url',
+        'contentType',
+        'addedDate',
+    ],
+    strategy: Strategy.COOKIE,
+    browser: true,
+    navigateBefore: false,
+    func: async (page, kwargs) => runKnowledgeCommand(
+        kwargs,
+        (query) => readKnowledgeBaseFromChrome(page, query),
+    ),
+});

package/clis/ima/native-api.js

@@ -0,0 +1,169 @@
+const MEDIA_TYPE_NAMES = new Map([
+    [0, '未知'], [1, 'PDF'], [2, '网址'], [3, 'WORD'], [4, 'PPT'],
+    [5, 'EXCEL'], [6, '公众号'], [7, 'MD'], [9, '图片'], [11, '笔记'],
+    [12, '问答'], [13, 'TXT'], [14, 'XMIND'], [15, '音频'], [16, '视频网站'],
+    [19, '播客'], [20, 'HTML'], [21, 'EPUB'], [98, '源代码'], [99, '文件夹'],
+]);
+function field(value, camelName, snakeName) {
+    return value?.[camelName] ?? value?.[snakeName];
+}
+
+function codedError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+
+function knowledgeBaseFromRaw(raw) {
+    const basicInfo = field(raw, 'basicInfo', 'basic_info') || {};
+    return {
+        id: String(field(raw, 'id', 'id') || ''),
+        name: String(field(basicInfo, 'name', 'name') || ''),
+    };
+}
+
+function basesFromGroups(response) {
+    const groups = field(response, 'results', 'results');
+    if (!Array.isArray(groups)) throw new Error('ima API returned malformed knowledge-base groups');
+    return groups.flatMap((group) => {
+        const list = field(group, 'knowledgeBaseList', 'knowledge_base_list');
+        return Array.isArray(list) ? list.map(knowledgeBaseFromRaw) : [];
+    });
+}
+
+export async function findKnowledgeBase(query, request) {
+    const initialGroups = [
+        { type: 1001, limit: 20 },
+        { type: 1002, limit: 20 },
+        { type: 1004, limit: 20 },
+        { type: 1005, limit: 50 },
+    ];
+    let response = await request('/get_knowledge_base_list', {
+        params: initialGroups.map(({ type, limit }) => ({ type, cursor: '', limit })),
+    });
+    const all = [];
+    const pendingPages = [];
+    const queuedPages = new Set();
+
+    for (;;) {
+        if (Number(response?.code) !== 0) {
+            throw new Error(response?.msg || `ima API error ${response?.code ?? 'unknown'}`);
+        }
+        all.push(...basesFromGroups(response));
+        const groups = field(response, 'results', 'results');
+        for (const group of groups) {
+            const cursor = field(group, 'nextCursor', 'next_cursor');
+            if (field(group, 'isEnd', 'is_end') === false) {
+                const type = Number(field(group, 'type', 'type'));
+                if (!cursor) {
+                    throw new Error(`ima API returned a missing cursor for knowledge-base group ${type}`);
+                }
+                const pageKey = `${type}:${cursor}`;
+                if (queuedPages.has(pageKey)) {
+                    throw new Error(`ima API returned a repeated cursor for knowledge-base group ${type}`);
+                }
+                queuedPages.add(pageKey);
+                pendingPages.push({
+                    type,
+                    cursor: String(cursor),
+                    limit: 10,
+                });
+            }
+        }
+        const next = pendingPages.shift();
+        if (!next) break;
+        response = await request('/get_knowledge_base_list', {
+            params: [next],
+        });
+    }
+
+    const matches = all.filter((base) => base.id === query || base.name === query);
+    if (matches.length === 0) {
+        throw codedError('KNOWLEDGE_NOT_FOUND', `Knowledge base "${query}" was not found`);
+    }
+    const unique = [...new Map(matches.map((base) => [base.id, base])).values()];
+    if (unique.length > 1) {
+        throw codedError('AMBIGUOUS_KNOWLEDGE', `Knowledge base name "${query}" is ambiguous`);
+    }
+    return unique[0];
+}
+
+function articleFromRaw(raw, knowledgeBaseId, knowledgeBaseName, folderPath) {
+    const mediaType = Number(field(raw, 'mediaType', 'media_type') ?? 0);
+    const jumpUrl = field(raw, 'jumpUrl', 'jump_url');
+    const sourcePath = field(raw, 'sourcePath', 'source_path');
+    return {
+        knowledgeBaseId,
+        knowledgeBase: knowledgeBaseName,
+        folderPath,
+        title: field(raw, 'title', 'title') || '',
+        url: jumpUrl || (/^https?:\/\//i.test(sourcePath || '') ? sourcePath : null),
+        contentType: MEDIA_TYPE_NAMES.get(mediaType) ?? String(mediaType),
+        addedDate: field(raw, 'timeWording', 'time_wording')
+            || field(raw, 'createTime', 'create_time')
+            || null,
+    };
+}
+
+export async function collectKnowledgeTree({ knowledgeBaseId, knowledgeBaseName, request }) {
+    const articles = [];
+    const pendingFolders = [{ id: '', path: [] }];
+    const visitedFolders = new Set();
+
+    while (pendingFolders.length > 0) {
+        const folder = pendingFolders.shift();
+        if (visitedFolders.has(folder.id)) continue;
+        visitedFolders.add(folder.id);
+        let cursor = '';
+        const visitedCursors = new Set();
+
+        do {
+            if (visitedCursors.has(cursor)) {
+                throw new Error(`ima API returned a repeated cursor for folder ${folder.id || 'root'}`);
+            }
+            visitedCursors.add(cursor);
+            const response = await request('/get_knowledge_list', {
+                cursor,
+                limit: 20,
+                knowledge_base_id: knowledgeBaseId,
+                need_default_cover: true,
+                ...(folder.id ? { folder_id: folder.id } : {}),
+                ext_info: { share_id: '' },
+            });
+            if (Number(response?.code) !== 0) {
+                throw new Error(response?.msg || `ima API error ${response?.code ?? 'unknown'}`);
+            }
+
+            const items = field(response, 'knowledgeList', 'knowledge_list');
+            if (!Array.isArray(items)) throw new Error('ima API returned malformed knowledge_list');
+            for (const item of items) {
+                const mediaType = Number(field(item, 'mediaType', 'media_type') ?? 0);
+                if (mediaType === 99) {
+                    const info = field(item, 'folderInfo', 'folder_info') || {};
+                    const id = field(info, 'folderId', 'folder_id');
+                    const name = field(info, 'name', 'name');
+                    if (id && name) pendingFolders.push({ id, path: [...folder.path, name] });
+                    continue;
+                }
+                articles.push(articleFromRaw(item, knowledgeBaseId, knowledgeBaseName, folder.path));
+            }
+
+            const isEnd = field(response, 'isEnd', 'is_end') !== false;
+            cursor = String(field(response, 'nextCursor', 'next_cursor') || '');
+            if (!isEnd && !cursor) {
+                throw new Error(`ima API returned a missing cursor for folder ${folder.id || 'root'}`);
+            }
+            if (isEnd) cursor = '';
+        } while (cursor);
+    }
+
+    return articles;
+}
+
+export async function readKnowledgeBaseFromApi(query, request) {
+    const knowledgeBase = await findKnowledgeBase(query, request);
+    const items = await collectKnowledgeTree({
+        knowledgeBaseId: knowledgeBase.id,
+        knowledgeBaseName: knowledgeBase.name,
+        request,
+    });
+    return { ok: true, items };
+}

package/clis/ima/native-client.js

@@ -0,0 +1,70 @@
+import { readKnowledgeBaseFromApi } from './native-api.js';
+
+const IMA_WIKIS_URL = 'https://ima.qq.com/wikis';
+
+function codedError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function waitForImaAuth(page, timeoutMs, sleep) {
+    const deadline = Date.now() + timeoutMs;
+    do {
+        const auth = await page.readImaAuth();
+        if (auth?.authId) return auth.authId;
+        if (Date.now() >= deadline) break;
+        await sleep(Math.min(250, Math.max(1, deadline - Date.now())));
+    } while (true);
+    throw codedError(
+        'IMA_CHROME_AUTH_REQUIRED',
+        'ima reader authentication was not observed in the Chrome session',
+    );
+}
+
+async function triggerImaAuthRequest(page, query) {
+    await page.evaluate((knowledgeBase) => {
+        const candidates = [...document.querySelectorAll('._knowledgeListItem_xfmpc_1')];
+        const target = candidates.find((element) => element.innerText?.trim() === knowledgeBase)
+            ?? candidates[0];
+        if (!target) return false;
+        target.click();
+        return true;
+    }, query);
+}
+
+export async function readKnowledgeBaseFromChrome(page, query, dependencies = {}) {
+    if (!page || typeof page.startImaAuthCapture !== 'function'
+        || typeof page.readImaAuth !== 'function' || typeof page.requestImaReader !== 'function'
+        || typeof page.evaluate !== 'function') {
+        throw codedError(
+            'IMA_CHROME_AUTH_REQUIRED',
+            'The installed bycli Browser Bridge does not support private ima reader authentication',
+        );
+    }
+    const timeoutMs = dependencies.timeoutMs ?? 30_000;
+    const sleep = dependencies.sleep ?? wait;
+    let authId;
+    try {
+        await page.startImaAuthCapture();
+        await page.goto(IMA_WIKIS_URL);
+        await triggerImaAuthRequest(page, query);
+        authId = await waitForImaAuth(page, timeoutMs, sleep);
+    } catch (error) {
+        if (error?.code === 'IMA_CHROME_AUTH_REQUIRED') throw error;
+        throw codedError(
+            'IMA_CHROME_AUTH_REQUIRED',
+            `Chrome Browser Bridge could not acquire ima reader authentication: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    }
+    try {
+        return await readKnowledgeBaseFromApi(
+            query,
+            (path, body) => page.requestImaReader(authId, path, body),
+        );
+    } finally {
+        if (typeof page.releaseImaAuth === 'function') {
+            await page.releaseImaAuth(authId).catch(() => {});
+        }
+    }
+}

package/clis/ima/utils.js

@@ -0,0 +1,48 @@
+const VOLATILE_QUERY_KEYS = new Set([
+    'sessionid',
+    'pass_ticket',
+    'exportkey',
+    'scene',
+    'ascene',
+    'devicetype',
+    'version',
+    'nettype',
+    'abtest_cookie',
+    'lang',
+    'countrycode',
+    'fontscale',
+    'wx_header',
+]);
+
+export function normalizeArticleUrl(value) {
+    if (typeof value !== 'string' || !value.trim()) return null;
+
+    try {
+        const raw = value.trim();
+        const parsed = new URL(raw.includes('://') ? raw : `https://${raw}`);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+
+        parsed.hash = '';
+        for (const key of [...parsed.searchParams.keys()]) {
+            const normalizedKey = key.toLowerCase();
+            if (VOLATILE_QUERY_KEYS.has(normalizedKey) || normalizedKey.startsWith('utm_')) {
+                parsed.searchParams.delete(key);
+            }
+        }
+        return parsed.toString();
+    } catch {
+        return null;
+    }
+}
+
+export function toKnowledgeRow(item) {
+    return {
+        knowledgeBaseId: item.knowledgeBaseId || null,
+        knowledgeBase: item.knowledgeBase,
+        folderPath: Array.isArray(item.folderPath) ? item.folderPath : [],
+        title: item.title,
+        url: normalizeArticleUrl(item.url),
+        contentType: item.contentType || null,
+        addedDate: item.addedDate || null,
+    };
+}

package/dist/src/browser/daemon-client.d.ts

@@ -5,7 +5,7 @@
  */
 export interface DaemonCommand {
     id: string;
-    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'wait-download' | 'cdp' | 'frames';
+    action: 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'ima-auth-start' | 'ima-auth-read' | 'ima-reader-request' | 'ima-auth-release' | 'wait-download' | 'cdp' | 'frames';
     /** Target page identity (targetId). Cross-layer contract with the extension. */
     page?: string;
     code?: string;
@@ -32,6 +32,9 @@ export interface DaemonCommand {
     text?: string;
     /** URL substring filter pattern for network capture */
     pattern?: string;
+    authId?: string;
+    readerPath?: string;
+    readerBody?: Record<string, unknown>;
     /** Download wait timeout in milliseconds */
     timeoutMs?: number;
     cdpMethod?: string;

package/dist/src/browser/page.d.ts

@@ -58,6 +58,12 @@ export declare class Page extends BasePage {
     screenshot(options?: ScreenshotOptions): Promise<string>;
     startNetworkCapture(pattern?: string): Promise<boolean>;
     readNetworkCapture(): Promise<unknown[]>;
+    startImaAuthCapture(): Promise<void>;
+    readImaAuth(): Promise<{
+        authId: string;
+    } | null>;
+    requestImaReader(authId: string, path: string, body: Record<string, unknown>): Promise<unknown>;
+    releaseImaAuth(authId: string): Promise<void>;
     waitForDownload(pattern?: string, timeoutMs?: number, options?: BrowserDownloadWaitOptions): Promise<BrowserDownloadWaitResult>;
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.

package/dist/src/browser/page.js

@@ -305,6 +305,26 @@ export class Page extends BasePage {
             return [];
         }
     }
+    async startImaAuthCapture() {
+        await sendCommand('ima-auth-start', this._cmdOpts());
+    }
+    async readImaAuth() {
+        const result = await sendCommand('ima-auth-read', this._cmdOpts());
+        if (!result || typeof result !== 'object' || typeof result.authId !== 'string')
+            return null;
+        return { authId: result.authId };
+    }
+    async requestImaReader(authId, path, body) {
+        return sendCommand('ima-reader-request', {
+            authId,
+            readerPath: path,
+            readerBody: body,
+            ...this._cmdOpts(),
+        });
+    }
+    async releaseImaAuth(authId) {
+        await sendCommand('ima-auth-release', { authId, ...this._cmdOpts() });
+    }
     async waitForDownload(pattern = '', timeoutMs = 30_000, options) {
         const result = await sendCommand('wait-download', {
             pattern,

package/dist/src/types.d.ts

@@ -203,6 +203,12 @@ export interface IPage {
     annotatedScreenshot?(options?: ScreenshotOptions): Promise<string>;
     startNetworkCapture?(pattern?: string): Promise<boolean>;
     readNetworkCapture?(): Promise<unknown[]>;
+    startImaAuthCapture?(): Promise<void>;
+    readImaAuth?(): Promise<{
+        authId: string;
+    } | null>;
+    requestImaReader?(authId: string, path: string, body: Record<string, unknown>): Promise<unknown>;
+    releaseImaAuth?(authId: string): Promise<void>;
     /**
      * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
      * Chrome reads the files directly — no base64 encoding or payload size limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovovs/bycli",
-  "version": "2.1.38",
+  "version": "2.1.39",
   "publishConfig": {
     "access": "public"
   },