@jackwener/opencli 1.7.20 → 1.7.22

package/clis/weibo/utils.js

@@ -1,10 +1,39 @@
 /**
  * Shared Weibo utilities — uid extraction.
  */
-import { AuthRequiredError } from '@jackwener/opencli/errors';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+/**
+ * `page.evaluate` may return either the raw IIFE value or a
+ * `{ session, data }` envelope depending on the browser-bridge version.
+ * Adapter code that inspected the payload directly (e.g. `Array.isArray`,
+ * truthiness checks on uid strings) silently received the envelope wrapper
+ * instead of the inner value. This helper normalizes both shapes so callers
+ * can keep their existing checks unchanged.
+ */
+export function unwrapEvaluateResult(payload) {
+    if (payload && !Array.isArray(payload) && typeof payload === 'object' && 'session' in payload && 'data' in payload) {
+        return payload.data;
+    }
+    return payload;
+}
+export function requireArrayEvaluateResult(payload, label) {
+    if (!Array.isArray(payload)) {
+        if (payload && typeof payload === 'object' && 'error' in payload) {
+            throw new CommandExecutionError(`${label}: ${String(payload.error)}`);
+        }
+        throw new CommandExecutionError(`${label} returned malformed extraction payload`);
+    }
+    return payload;
+}
+export function requireObjectEvaluateResult(payload, label) {
+    if (!payload || Array.isArray(payload) || typeof payload !== 'object') {
+        throw new CommandExecutionError(`${label} returned malformed extraction payload`);
+    }
+    return payload;
+}
 /** Get the currently logged-in user's uid from Vue store or config API. */
 export async function getSelfUid(page) {
-    const uid = await page.evaluate(`
+    const uid = unwrapEvaluateResult(await page.evaluate(`
     (() => {
       const app = document.querySelector('#app')?.__vue_app__;
       const store = app?.config?.globalProperties?.$store;
@@ -12,18 +41,18 @@ export async function getSelfUid(page) {
       if (uid) return String(uid);
       return null;
     })()
-  `);
+  `));
     if (uid)
         return uid;
     // Fallback: config API
-    const config = await page.evaluate(`
+    const config = unwrapEvaluateResult(await page.evaluate(`
     (async () => {
       const resp = await fetch('/ajax/config/get_config', {credentials: 'include'});
       if (!resp.ok) return null;
       const data = await resp.json();
       return data.ok && data.data?.uid ? String(data.data.uid) : null;
     })()
-  `);
+  `));
     if (config)
         return config;
     throw new AuthRequiredError('weibo.com');

package/clis/weibo/utils.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { requireArrayEvaluateResult, requireObjectEvaluateResult, unwrapEvaluateResult } from './utils.js';
+
+describe('unwrapEvaluateResult (browser-bridge envelope normalization)', () => {
+    it('returns the raw array unchanged when payload is already an array', () => {
+        const arr = [{ id: '1' }, { id: '2' }];
+        expect(unwrapEvaluateResult(arr)).toBe(arr);
+    });
+    it('unwraps { session, data: [...] } envelope to the inner array', () => {
+        const arr = [{ id: '1' }];
+        const env = { session: 'site:weibo:abc', data: arr };
+        expect(unwrapEvaluateResult(env)).toBe(arr);
+    });
+    it('unwraps primitive data (e.g. uid string) from Browser Bridge envelopes', () => {
+        expect(unwrapEvaluateResult({ session: 'site:weibo:abc', data: '1234567890' })).toBe('1234567890');
+    });
+    it('unwraps null payload data so getSelfUid fallback can trigger', () => {
+        expect(unwrapEvaluateResult({ session: 'site:weibo:abc', data: null })).toBe(null);
+    });
+    it('passes non-envelope objects through unchanged (e.g. profile result)', () => {
+        const obj = { screen_name: 'alice', uid: '42' };
+        expect(unwrapEvaluateResult(obj)).toBe(obj);
+    });
+    it('handles null and undefined safely', () => {
+        expect(unwrapEvaluateResult(null)).toBe(null);
+        expect(unwrapEvaluateResult(undefined)).toBe(undefined);
+    });
+    it('keeps malformed array/object payloads as typed command failures after unwrap', () => {
+        expect(requireArrayEvaluateResult([{ id: '1' }], 'weibo feed')).toEqual([{ id: '1' }]);
+        expect(() => requireArrayEvaluateResult({ error: 'API error' }, 'weibo feed')).toThrow(CommandExecutionError);
+        expect(() => requireArrayEvaluateResult({ error: 'API error' }, 'weibo feed')).toThrow('weibo feed: API error');
+        expect(requireObjectEvaluateResult({ uid: '42' }, 'weibo me')).toEqual({ uid: '42' });
+        expect(() => requireObjectEvaluateResult([{ uid: '42' }], 'weibo me')).toThrow(CommandExecutionError);
+    });
+});

package/clis/xiaohongshu/search.js

@@ -6,7 +6,7 @@
  * Ref: https://github.com/jackwener/opencli/issues/10
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { ArgumentError, AuthRequiredError } from '@jackwener/opencli/errors';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 /**
  * Wait for search results or login wall using MutationObserver (max 5s).
  * Returns 'content' if note items appeared, 'login_wall' if login gate
@@ -60,6 +60,26 @@ export function stripXhsAuthorDateSuffix(value) {
     const stripped = text.replace(/\s*(?:\d{1,2}天前|\d+小时前|\d+分钟前|\d+秒前|刚刚|昨天|前天|\d+周前|\d+个月前|\d{1,2}-\d{1,2}|\d{4}-\d{1,2}-\d{1,2})$/u, '').trim();
     return stripped || text;
 }
+/**
+ * `page.evaluate` may return either the raw IIFE value or a
+ * `{ session, data }` envelope depending on the browser-bridge version.
+ * Adapter code that called `Array.isArray(payload)` directly on the
+ * envelope silently received [] for every search. This helper normalizes
+ * both shapes so callers can keep their Array.isArray checks unchanged.
+ */
+export function unwrapEvaluateResult(payload) {
+    if (payload && !Array.isArray(payload) && typeof payload === 'object' && 'session' in payload && 'data' in payload) {
+        return payload.data;
+    }
+    return payload;
+}
+function requireSearchRows(payload, phase) {
+    const rows = unwrapEvaluateResult(payload);
+    if (!Array.isArray(rows)) {
+        throw new CommandExecutionError(`Unexpected Xiaohongshu search ${phase} payload shape; expected an array of rows.`);
+    }
+    return rows;
+}
 export function parseLimit(raw) {
     const parsed = Number(raw ?? 20);
     if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) {
@@ -267,7 +287,7 @@ export const command = cli({
         // Wait for search results to render (or login wall to appear).
         // Uses MutationObserver to resolve as soon as content appears,
         // instead of a fixed delay + blind retry.
-        const waitResult = await page.evaluate(WAIT_FOR_CONTENT_JS);
+        const waitResult = unwrapEvaluateResult(await page.evaluate(WAIT_FOR_CONTENT_JS));
         if (waitResult === 'login_wall') {
             throw new AuthRequiredError('www.xiaohongshu.com', 'Xiaohongshu search results are blocked behind a login wall');
         }
@@ -275,25 +295,23 @@ export const command = cli({
         // layout, so scrolling to the bottom can evict the initially visible
         // note cards from the DOM and make extraction return [] even though the
         // browser rendered results correctly.
-        const initialPayload = await page.evaluate(buildSearchExtractJs('www.xiaohongshu.com'));
-        let payload = Array.isArray(initialPayload) ? initialPayload : [];
+        const initialPayload = requireSearchRows(await page.evaluate(buildSearchExtractJs('www.xiaohongshu.com')), 'initial extraction');
+        const payload = [...initialPayload];
         if (payload.length < limit) {
             // Scroll until enough rows are rendered or the lazy-load plateaus.
             // Replaces the previous fixed `autoScroll({ times: 2 })` which capped
             // extraction at ~13 notes regardless of `--limit` (#1471).
             await page.evaluate(buildScrollUntilJs(limit));
-            const scrolledPayload = await page.evaluate(buildSearchExtractJs('www.xiaohongshu.com'));
-            if (Array.isArray(scrolledPayload)) {
-                const seen = new Set(payload.map((item) => item.url).filter(Boolean));
-                for (const item of scrolledPayload) {
-                    if (item?.url && seen.has(item.url))
-                        continue;
-                    if (item?.url)
-                        seen.add(item.url);
-                    payload.push(item);
-                    if (payload.length >= limit)
-                        break;
-                }
+            const scrolledPayload = requireSearchRows(await page.evaluate(buildSearchExtractJs('www.xiaohongshu.com')), 'post-scroll extraction');
+            const seen = new Set(payload.map((item) => item.url).filter(Boolean));
+            for (const item of scrolledPayload) {
+                if (item?.url && seen.has(item.url))
+                    continue;
+                if (item?.url)
+                    seen.add(item.url);
+                payload.push(item);
+                if (payload.length >= limit)
+                    break;
             }
         }
         const data = payload;

package/clis/xiaohongshu/search.test.js

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
 import { JSDOM } from 'jsdom';
-import { __test__, buildScrollUntilJs, noteIdToDate } from './search.js';
+import { __test__, buildScrollUntilJs, noteIdToDate, unwrapEvaluateResult } from './search.js';
 
 function markVisible(el) {
     el.getBoundingClientRect = () => ({ width: 100, height: 100 });
@@ -57,24 +57,37 @@ describe('xiaohongshu search', () => {
         expect(page.evaluate).toHaveBeenCalledTimes(1);
         expect(page.autoScroll).not.toHaveBeenCalled();
     });
+    it('unwraps a browser-bridge envelope before handling login-wall wait result', async () => {
+        const cmd = getRegistry().get('xiaohongshu/search');
+        const page = createPageMock([
+            { session: 'site:xiaohongshu', data: 'login_wall' },
+        ]);
+
+        await expect(cmd.func(page, { query: '特斯拉', limit: 5 })).rejects.toMatchObject({
+            code: 'AUTH_REQUIRED',
+            message: expect.stringContaining('blocked behind a login wall'),
+        });
+        expect(page.evaluate).toHaveBeenCalledTimes(1);
+    });
     it('returns ranked results with search_result url and author_url preserved', async () => {
         const cmd = getRegistry().get('xiaohongshu/search');
         expect(cmd?.func).toBeTypeOf('function');
         const detailUrl = 'https://www.xiaohongshu.com/search_result/68e90be80000000004022e66?xsec_token=test-token&xsec_source=';
         const authorUrl = 'https://www.xiaohongshu.com/user/profile/635a9c720000000018028b40?xsec_token=user-token&xsec_source=pc_search';
+        const rows = [
+            {
+                title: '某鱼买FSD被坑了4万',
+                author: '随风',
+                likes: '261',
+                url: detailUrl,
+                author_url: authorUrl,
+            },
+        ];
         const page = createPageMock([
             // First evaluate: MutationObserver wait (content appeared)
             'content',
-            // Second evaluate: initial DOM extraction (already enough results)
-            [
-                {
-                    title: '某鱼买FSD被坑了4万',
-                    author: '随风',
-                    likes: '261',
-                    url: detailUrl,
-                    author_url: authorUrl,
-                },
-            ],
+            // Second evaluate: initial DOM extraction (already enough results) through Browser Bridge envelope.
+            { session: 'site:xiaohongshu', data: rows },
         ]);
         const result = await cmd.func(page, { query: '特斯拉', limit: 1 });
         // Should only do one goto (the search page itself), no per-note detail navigation
@@ -91,6 +104,18 @@ describe('xiaohongshu search', () => {
             },
         ]);
     });
+    it('fails typed instead of silently returning [] for malformed extraction payloads', async () => {
+        const cmd = getRegistry().get('xiaohongshu/search');
+        const page = createPageMock([
+            'content',
+            { session: 'site:xiaohongshu', data: { rows: [] } },
+        ]);
+
+        await expect(cmd.func(page, { query: '测试', limit: 1 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('payload shape'),
+        });
+    });
     it('filters out results with no title and respects the limit', async () => {
         const cmd = getRegistry().get('xiaohongshu/search');
         expect(cmd?.func).toBeTypeOf('function');
@@ -135,6 +160,10 @@ describe('xiaohongshu search', () => {
             'content',
             // Second evaluate: initial extraction (no rows rendered)
             [],
+            // Third evaluate: scroll-until row count
+            0,
+            // Fourth evaluate: post-scroll extraction (still no rows)
+            [],
         ]);
         const result = (await cmd.func(page, { query: '测试等待', limit: 5 }));
         expect(result).toHaveLength(0);
@@ -268,3 +297,29 @@ describe('noteIdToDate (ObjectID timestamp parsing)', () => {
         expect(noteIdToDate('https://www.xiaohongshu.com/search_result/000000000000000000000000')).toBe('');
     });
 });
+describe('unwrapEvaluateResult (browser-bridge envelope normalization)', () => {
+    it('returns the raw array unchanged when payload is already an array', () => {
+        const arr = [{ title: 'a' }, { title: 'b' }];
+        expect(unwrapEvaluateResult(arr)).toBe(arr);
+    });
+    it('unwraps { session, data: [...] } envelope to the inner array', () => {
+        const arr = [{ title: 'a' }];
+        const env = { session: 'site:xiaohongshu:abc', data: arr };
+        expect(unwrapEvaluateResult(env)).toBe(arr);
+    });
+    it('unwraps primitive data from Browser Bridge envelopes', () => {
+        expect(unwrapEvaluateResult({ session: 'site:xiaohongshu:abc', data: 'login_wall' })).toBe('login_wall');
+    });
+    it('passes non-envelope objects through unchanged', () => {
+        const obj = { results: [], loginWall: true };
+        expect(unwrapEvaluateResult(obj)).toBe(obj);
+    });
+    it('handles null and undefined safely', () => {
+        expect(unwrapEvaluateResult(null)).toBe(null);
+        expect(unwrapEvaluateResult(undefined)).toBe(undefined);
+    });
+    it('unwraps non-array envelope data so callers can validate the payload shape', () => {
+        const env = { session: 'x', data: { not: 'an array' } };
+        expect(unwrapEvaluateResult(env)).toEqual({ not: 'an array' });
+    });
+});

package/clis/yahoo/search.js

@@ -0,0 +1,92 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+  emptySearchResults,
+  requireBoundedInteger,
+  requireRows,
+  requireSearchQuery,
+  runBrowserStep,
+  toHttpsUrl,
+} from '../_shared/search-adapter.js';
+
+function decodeYahooUrl(href) {
+  if (!href) return '';
+  if (href.indexOf('RU=') !== -1 && href.indexOf('/RK=') !== -1) {
+    var match = href.match(/RU=([^/]+)\/RK=/);
+    if (match && match[1]) {
+      try {
+        return toHttpsUrl(decodeURIComponent(match[1]), 'https://search.yahoo.com');
+      } catch {
+        return toHttpsUrl(href, 'https://search.yahoo.com');
+      }
+    }
+  }
+  return toHttpsUrl(href, 'https://search.yahoo.com');
+}
+
+function buildExtractorJs(limit) {
+  return `
+(function() {
+  var results = [];
+  var seen = {};
+  var items = document.querySelectorAll('.algo');
+  for (var i = 0; i < items.length; i++) {
+    if (results.length >= ${limit}) break;
+    var el = items[i];
+    var h3 = el.querySelector('h3');
+    var linkEl = el.querySelector('.compTitle a');
+    var snippetEl = el.querySelector('.compText');
+    if (!h3 || !linkEl) continue;
+    var title = h3.textContent.trim();
+    var href = linkEl.getAttribute('href') || '';
+    var snippet = snippetEl ? snippetEl.textContent.trim() : '';
+    if (!title || !href || seen[href]) continue;
+    seen[href] = true;
+    results.push([title, href, snippet]);
+  }
+  return results;
+})()`;
+}
+
+const command = cli({
+  site: 'yahoo',
+  name: 'search',
+  access: 'read',
+  description: 'Search Yahoo (powered by Bing)',
+  domain: 'search.yahoo.com',
+  strategy: Strategy.PUBLIC,
+  browser: true,
+  args: [
+    { name: 'keyword', positional: true, required: true, help: 'Search query' },
+    { name: 'limit', type: 'int', default: 7, help: 'Number of results per page (max 7)' },
+    { name: 'page', type: 'int', default: 1, help: 'Page number (1, 2, 3...). Yahoo returns ~7 results per page' },
+  ],
+  columns: ['rank', 'title', 'url', 'snippet'],
+  func: async (page, kwargs) => {
+    const limit = requireBoundedInteger(kwargs.limit, 7, 1, 7, '--limit');
+    const query = requireSearchQuery(kwargs.keyword);
+    const keyword = encodeURIComponent(query);
+    const pageNum = requireBoundedInteger(kwargs.page, 1, 1, 100, '--page');
+    var url = `https://search.yahoo.com/search?p=${keyword}`;
+    if (pageNum > 1) url += `&b=${(pageNum - 1) * 7 + 1}`;
+    await runBrowserStep('yahoo search navigation', () => page.goto(url));
+    try {
+      await page.wait({ selector: '.algo', timeout: 10 });
+    } catch {
+      await page.wait(3).catch(function() {});
+    }
+    const raw = await runBrowserStep('yahoo search extraction', () => page.evaluate(buildExtractorJs(limit)));
+    const results = requireRows(raw, 'yahoo search');
+    if (results.length === 0) {
+      throw emptySearchResults('Yahoo', query);
+    }
+    const rows = results
+      .map(function(r, index) {
+        return { rank: index + 1 + (pageNum - 1) * 7, title: r[0], url: decodeYahooUrl(r[1]), snippet: r[2] };
+      })
+      .filter((row) => row.url);
+    if (rows.length === 0) throw emptySearchResults('Yahoo', query);
+    return rows;
+  },
+});
+
+export const __test__ = { command };

package/clis/yahoo/search.test.js

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi } from 'vitest';
+
+const { __test__ } = await import('./search.js');
+const command = __test__.command;
+
+function createPageMock(evaluateResult = []) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(evaluateResult),
+  };
+}
+
+describe('yahoo search', () => {
+  it('should register as a valid command', () => {
+    expect(command).toBeDefined();
+    expect(command.site).toBe('yahoo');
+    expect(command.name).toBe('search');
+    expect(command.access).toBe('read');
+    expect(command.browser).toBe(true);
+    expect(command.strategy).toBe('public');
+    expect(command.domain).toBe('search.yahoo.com');
+  });
+
+  it('should define keyword positional arg', () => {
+    const kwArg = command.args.find(a => a.name === 'keyword');
+    expect(kwArg).toBeDefined();
+    expect(kwArg.positional).toBe(true);
+    expect(kwArg.required).toBe(true);
+  });
+
+  it('should define limit arg with default 7', () => {
+    const limitArg = command.args.find(a => a.name === 'limit');
+    expect(limitArg).toBeDefined();
+    expect(limitArg.type).toBe('int');
+    expect(limitArg.default).toBe(7);
+  });
+
+  it('should define output columns', () => {
+    expect(command.columns).toContain('rank');
+    expect(command.columns).toContain('title');
+    expect(command.columns).toContain('url');
+    expect(command.columns).toContain('snippet');
+  });
+
+  it('rejects empty query, invalid limit, and invalid page before navigation', async () => {
+    const page = createPageMock();
+    await expect(command.func(page, { keyword: ' ', limit: 5 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    await expect(command.func(page, { keyword: 'opencli', limit: 8 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    await expect(command.func(page, { keyword: 'opencli', limit: 5, page: 0 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it('decodes Yahoo redirect URLs and assigns listing rank', async () => {
+    const page = createPageMock({
+      session: 'site:yahoo',
+      data: [[
+        'OpenCLI',
+        'https://r.search.yahoo.com/_ylt=x/RU=https%3A%2F%2Fgithub.com%2Fjackwener%2FOpenCLI/RK=2/RS=x',
+        'CLI browser tooling',
+      ]],
+    });
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 1, page: 2 })).resolves.toEqual([{
+      rank: 8,
+      title: 'OpenCLI',
+      url: 'https://github.com/jackwener/OpenCLI',
+      snippet: 'CLI browser tooling',
+    }]);
+  });
+
+  it('drops decoded Yahoo redirect targets that are not http(s) URLs', async () => {
+    const page = createPageMock([
+      [
+        'Bad redirect',
+        'https://r.search.yahoo.com/_ylt=x/RU=javascript%3Aalert(1)/RK=2/RS=x',
+        'should not be emitted',
+      ],
+    ]);
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 1 })).rejects.toMatchObject({
+      code: 'EMPTY_RESULT',
+    });
+  });
+
+  it('fails typed instead of silently returning [] for malformed extraction payloads', async () => {
+    const page = createPageMock({ rows: [] });
+
+    await expect(command.func(page, { keyword: 'opencli', limit: 1 })).rejects.toMatchObject({
+      code: 'COMMAND_EXEC',
+      message: expect.stringContaining('payload shape'),
+    });
+  });
+});

package/dist/src/cli.js

@@ -545,7 +545,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             for (const ext of externalClis) {
                 const isInstalled = isBinaryInstalled(ext.binary);
                 const tag = isInstalled ? '[installed]' : '[auto-install]';
-                console.log(`    ${ext.name} ${tag}${ext.description ? ` — ${ext.description}` : ''}`);
+                console.log(`    ${formatExternalCliLabel(ext)} ${tag}${ext.description ? ` — ${ext.description}` : ''}`);
             }
             console.log();
         }

package/dist/src/external-clis.yaml

@@ -16,6 +16,7 @@
 
 - name: ntn
   binary: ntn
+  package: notion
   description: "Notion CLI — official Notion API CLI for pages, databases, blocks, search, comments"
   homepage: "https://ntn.dev"
   tags: [notion, notes, knowledge, productivity]
@@ -36,8 +37,18 @@
   install:
     default: "npm install -g @larksuite/cli"
 
+- name: longbridge
+  binary: longbridge
+  description: "Longbridge CLI — AI-native market data, account management and trading commands for Longbridge OpenAPI"
+  homepage: "https://open.longbridge.com/zh-CN/docs/cli/"
+  tags: [longbridge, finance, trading, market-data, openapi, ai-agent]
+  install:
+    mac: "brew install --cask longbridge/tap/longbridge-terminal"
+    windows: "scoop install https://open.longbridge.com/longbridge/longbridge-terminal/longbridge.json"
+
 - name: dws
   binary: dws
+  package: DingTalk Workspace
   description: "DingTalk Workspace CLI — messages, docs, calendar, contacts and more for humans and AI agents"
   homepage: "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
   tags: [dingtalk, collaboration, productivity, ai-agent]
@@ -47,6 +58,7 @@
 
 - name: wecom-cli
   binary: wecom-cli
+  package: 企业微信
   description: "WeCom/企业微信 CLI — contacts, todos, meetings, messages, calendar, docs and smart sheets for AI agents"
   homepage: "https://github.com/WecomTeam/wecom-cli"
   tags: [wecom, wechat-work, collaboration, productivity, ai-agent]

package/dist/src/external.d.ts

@@ -8,7 +8,12 @@ export interface ExternalCliConfig {
     /** User-facing OpenCLI subcommand and, by default, the executable name. */
     name: string;
     binary: string;
-    /** Distribution/project name when it differs from the executable name. */
+    /**
+     * Display alias rendered alongside `name` in help/listing as `name(package)`.
+     * Use either the upstream distribution/project name (e.g. `tg-cli`, `discord-cli`)
+     * or a human-readable brand label (e.g. `notion`, `企业微信`) when the bare
+     * executable name is ambiguous.
+     */
     package?: string;
     description?: string;
     homepage?: string;

package/dist/src/external.test.js

@@ -44,6 +44,21 @@ describe('parseCommand', () => {
             }
         }
     });
+    it('registers Longbridge with safe package-manager installers only', () => {
+        const raw = fs.readFileSync(path.join(__dirname, 'external-clis.yaml'), 'utf8');
+        const entries = (yaml.load(raw) || []);
+        const longbridge = entries.find((entry) => entry.name === 'longbridge');
+        expect(longbridge).toMatchObject({
+            binary: 'longbridge',
+            homepage: 'https://open.longbridge.com/zh-CN/docs/cli/',
+            install: {
+                mac: 'brew install --cask longbridge/tap/longbridge-terminal',
+                windows: 'scoop install https://open.longbridge.com/longbridge/longbridge-terminal/longbridge.json',
+            },
+        });
+        expect(longbridge?.install?.linux).toBeUndefined();
+        expect(longbridge?.install?.default).toBeUndefined();
+    });
 });
 describe('formatExternalCliLabel', () => {
     it('shows the package name when the executable name differs', () => {
@@ -52,6 +67,10 @@ describe('formatExternalCliLabel', () => {
     it('keeps the label compact when package and name match', () => {
         expect(formatExternalCliLabel({ name: 'docker', binary: 'docker', package: 'docker' })).toBe('docker');
     });
+    it('renders a human-readable brand alias for ambiguous executable names', () => {
+        expect(formatExternalCliLabel({ name: 'ntn', binary: 'ntn', package: 'notion' })).toBe('ntn(notion)');
+        expect(formatExternalCliLabel({ name: 'wecom-cli', binary: 'wecom-cli', package: '企业微信' })).toBe('wecom-cli(企业微信)');
+    });
 });
 describe('installExternalCli', () => {
     const cli = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.20",
+  "version": "1.7.22",
   "publishConfig": {
     "access": "public"
   },