@jackwener/opencli 1.5.5 → 1.5.6

package/dist/clis/zsxq/utils.js

@@ -0,0 +1,230 @@
+import { ArgumentError, AuthRequiredError, CliError } from '../../errors.js';
+const SITE_DOMAIN = 'wx.zsxq.com';
+const SITE_URL = 'https://wx.zsxq.com';
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function pickArray(...values) {
+    for (const value of values) {
+        if (Array.isArray(value)) {
+            return value;
+        }
+    }
+    return [];
+}
+export async function ensureZsxqPage(page) {
+    await page.goto(SITE_URL);
+}
+export async function ensureZsxqAuth(page) {
+    // zsxq uses httpOnly cookies that may be on different subdomains.
+    // Verify auth by attempting a lightweight API call instead of checking cookies.
+    try {
+        const result = await page.evaluate(`
+      (async () => {
+        try {
+          const r = await new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open('GET', 'https://api.zsxq.com/v2/groups', true);
+            xhr.withCredentials = true;
+            xhr.setRequestHeader('accept', 'application/json');
+            xhr.onload = () => {
+              if (xhr.status >= 200 && xhr.status < 300) {
+                try { resolve(JSON.parse(xhr.responseText)); }
+                catch { resolve(null); }
+              } else { resolve(null); }
+            };
+            xhr.onerror = () => resolve(null);
+            xhr.send();
+          });
+          return r !== null;
+        } catch { return false; }
+      })()
+    `);
+        if (!result) {
+            throw new AuthRequiredError('zsxq.com');
+        }
+    }
+    catch (err) {
+        if (err instanceof AuthRequiredError)
+            throw err;
+        throw new AuthRequiredError('zsxq.com');
+    }
+}
+export async function getCookieValue(page, name) {
+    const cookies = await page.getCookies({ domain: SITE_DOMAIN });
+    return cookies.find(cookie => cookie.name === name)?.value;
+}
+export async function getActiveGroupId(page) {
+    const groupId = await page.evaluate(`
+    (() => {
+      const target = localStorage.getItem('target_group');
+      if (target) {
+        try {
+          const parsed = JSON.parse(target);
+          if (parsed.group_id) return String(parsed.group_id);
+        } catch {}
+      }
+      return null;
+    })()
+  `);
+    if (groupId)
+        return groupId;
+    throw new ArgumentError('Cannot determine active group_id', 'Pass --group_id <id> or open the target 知识星球 page in Chrome first');
+}
+export async function browserJsonRequest(page, path) {
+    return await page.evaluate(`
+    (async () => {
+      const path = ${JSON.stringify(path)};
+
+      try {
+        return await new Promise((resolve) => {
+          const xhr = new XMLHttpRequest();
+          xhr.open('GET', path, true);
+          xhr.withCredentials = true;
+          xhr.setRequestHeader('accept', 'application/json, text/plain, */*');
+          xhr.onload = () => {
+            let parsed = null;
+            if (xhr.responseText) {
+              try { parsed = JSON.parse(xhr.responseText); }
+              catch {}
+            }
+
+            resolve({
+              ok: xhr.status >= 200 && xhr.status < 300,
+              url: path,
+              status: xhr.status,
+              data: parsed,
+              error: xhr.status >= 200 && xhr.status < 300 ? undefined : 'HTTP ' + xhr.status,
+            });
+          };
+          xhr.onerror = () => resolve({
+            ok: false,
+            url: path,
+            error: 'Network error',
+          });
+          xhr.send();
+        });
+      } catch (error) {
+        return {
+          ok: false,
+          url: path,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })()
+  `);
+}
+export async function fetchFirstJson(page, paths) {
+    let lastFailure = null;
+    for (const path of paths) {
+        const result = await browserJsonRequest(page, path);
+        if (result.ok) {
+            return result;
+        }
+        lastFailure = result;
+    }
+    if (!lastFailure) {
+        throw new CliError('FETCH_ERROR', 'No candidate endpoint returned JSON', `Checked endpoints: ${paths.join(', ')}`);
+    }
+    throw new CliError('FETCH_ERROR', lastFailure.error || 'Failed to fetch ZSXQ API', `Checked endpoints: ${paths.join(', ')}`);
+}
+export function unwrapRespData(payload) {
+    const record = asRecord(payload);
+    if (!record) {
+        throw new CliError('PARSE_ERROR', 'Invalid ZSXQ API response');
+    }
+    if (record.succeeded === false) {
+        const code = typeof record.code === 'number' ? String(record.code) : 'API_ERROR';
+        const message = typeof record.info === 'string'
+            ? record.info
+            : typeof record.error === 'string'
+                ? record.error
+                : 'ZSXQ API returned an error';
+        throw new CliError(code, message);
+    }
+    return (record.resp_data ?? record.data ?? payload);
+}
+export function getTopicsFromResponse(payload) {
+    const data = unwrapRespData(payload);
+    if (Array.isArray(data))
+        return data;
+    return pickArray(data.topics, data.list, data.records, data.items, data.search_result);
+}
+export function getCommentsFromResponse(payload) {
+    const data = unwrapRespData(payload);
+    if (Array.isArray(data))
+        return data;
+    return pickArray(data.comments, data.list, data.items);
+}
+export function getGroupsFromResponse(payload) {
+    const data = unwrapRespData(payload);
+    if (Array.isArray(data))
+        return data;
+    return pickArray(data.groups, data.list, data.items);
+}
+export function getTopicFromResponse(payload) {
+    const data = unwrapRespData(payload);
+    if (Array.isArray(data))
+        return data[0] ?? null;
+    if (typeof data.topic_id === 'number')
+        return data;
+    const record = asRecord(data);
+    if (!record)
+        return null;
+    const topic = record.topic;
+    return topic && typeof topic === 'object' ? topic : null;
+}
+export function getTopicAuthor(topic) {
+    return (topic.owner?.name ||
+        topic.talk?.owner?.name ||
+        topic.question?.owner?.name ||
+        topic.answer?.owner?.name ||
+        topic.task?.owner?.name ||
+        topic.solution?.owner?.name ||
+        '');
+}
+export function getTopicText(topic) {
+    const primary = [
+        topic.title,
+        topic.talk?.text,
+        topic.question?.text,
+        topic.answer?.text,
+        topic.task?.text,
+        topic.solution?.text,
+    ].find(value => typeof value === 'string' && value.trim());
+    return (primary || '').replace(/\s+/g, ' ').trim();
+}
+export function getTopicUrl(topicId) {
+    return topicId ? `${SITE_URL}/topic/${topicId}` : SITE_URL;
+}
+export function summarizeComments(comments, limit = 3) {
+    return comments
+        .slice(0, limit)
+        .map((comment) => {
+        const author = comment.owner?.name || '匿名';
+        const target = comment.repliee?.name ? ` -> ${comment.repliee.name}` : '';
+        const text = (comment.text || '').replace(/\s+/g, ' ').trim();
+        return `${author}${target}: ${text}`;
+    })
+        .join(' | ');
+}
+export function toTopicRow(topic) {
+    const topicId = topic.topic_id ?? '';
+    const comments = pickArray(topic.show_comments, topic.comments);
+    return {
+        topic_id: topicId,
+        type: topic.type || '',
+        group: topic.group?.name || '',
+        author: getTopicAuthor(topic),
+        title: getTopicText(topic).slice(0, 120),
+        content: getTopicText(topic),
+        comments: topic.comments_count ?? comments.length ?? 0,
+        likes: topic.likes_count ?? 0,
+        readers: topic.readers_count ?? topic.reading_count ?? 0,
+        time: topic.create_time || '',
+        comment_preview: summarizeComments(comments),
+        url: getTopicUrl(topicId),
+    };
+}

package/dist/commanderAdapter.js

@@ -17,7 +17,7 @@ import { executeCommand } from './execution.js';
 import { CliError, EXIT_CODES, ERROR_ICONS, getErrorMessage, BrowserConnectError, AuthRequiredError, TimeoutError, SelectorError, EmptyResultError, ArgumentError, AdapterLoadError, CommandExecutionError, } from './errors.js';
 import { checkDaemonStatus } from './browser/discover.js';
 export function normalizeArgValue(argType, value, name) {
-    if (argType !== 'bool')
+    if (argType !== 'bool' && argType !== 'boolean')
         return value;
     if (typeof value === 'boolean')
         return value;

package/dist/commanderAdapter.test.js

@@ -60,3 +60,42 @@ describe('commanderAdapter arg passing', () => {
         expect(mockExecuteCommand).not.toHaveBeenCalled();
     });
 });
+describe('commanderAdapter boolean alias support', () => {
+    const cmd = {
+        site: 'reddit',
+        name: 'save',
+        description: 'Save a post',
+        browser: false,
+        args: [
+            { name: 'post-id', positional: true, required: true, help: 'Post ID' },
+            { name: 'undo', type: 'boolean', default: false, help: 'Unsave instead of save' },
+        ],
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockExecuteCommand.mockResolvedValue([]);
+        mockRenderOutput.mockReset();
+        delete process.env.OPENCLI_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('coerces default false for boolean args to a real boolean', async () => {
+        const program = new Command();
+        const siteCmd = program.command('reddit');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'opencli', 'reddit', 'save', 't3_abc123']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs['post-id']).toBe('t3_abc123');
+        expect(kwargs.undo).toBe(false);
+    });
+    it('coerces explicit false for boolean args to a real boolean', async () => {
+        const program = new Command();
+        const siteCmd = program.command('reddit');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'opencli', 'reddit', 'save', 't3_abc123', '--undo', 'false']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        const kwargs = mockExecuteCommand.mock.calls[0][1];
+        expect(kwargs.undo).toBe(false);
+    });
+});

package/dist/external-clis.yaml

@@ -30,6 +30,23 @@
   install:
     default: "npm install -g @larksuite/cli"
 
+- name: dws
+  binary: dws
+  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]
+  install:
+    mac: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+    linux: "curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh"
+
+- name: wecom-cli
+  binary: wecom-cli
+  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]
+  install:
+    default: "npm install -g @wecom/cli"
+
 - name: vercel
   binary: vercel
   description: "Vercel CLI — deploy projects, manage domains, env vars, logs and serverless functions"

package/dist/types.d.ts

@@ -70,6 +70,11 @@ export interface IPage {
     getInterceptedRequests(): Promise<any[]>;
     waitForCapture(timeout?: number): Promise<void>;
     screenshot(options?: ScreenshotOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    setFileInput?(files: string[], selector?: string): Promise<void>;
     closeWindow?(): Promise<void>;
     /** Returns the current page URL, or null if unavailable. */
     getCurrentUrl?(): Promise<string | null>;

package/docs/.vitepress/config.mts

@@ -50,6 +50,7 @@ export default defineConfig({
               items: [
                 { text: 'Twitter / X', link: '/adapters/browser/twitter' },
                 { text: 'Reddit', link: '/adapters/browser/reddit' },
+                { text: 'Tieba', link: '/adapters/browser/tieba' },
                 { text: 'Bilibili', link: '/adapters/browser/bilibili' },
                 { text: 'Zhihu', link: '/adapters/browser/zhihu' },
                 { text: 'Xiaohongshu', link: '/adapters/browser/xiaohongshu' },
@@ -68,6 +69,7 @@ export default defineConfig({
                 { text: 'Jimeng', link: '/adapters/browser/jimeng' },
                 { text: 'Yollomi', link: '/adapters/browser/yollomi' },
                 { text: 'LINUX DO', link: '/adapters/browser/linux-do' },
+                { text: 'Band', link: '/adapters/browser/band' },
                 { text: 'Chaoxing', link: '/adapters/browser/chaoxing' },
                 { text: 'Grok', link: '/adapters/browser/grok' },
                 { text: 'WeRead', link: '/adapters/browser/weread' },
@@ -104,6 +106,7 @@ export default defineConfig({
                 { text: 'Barchart', link: '/adapters/browser/barchart' },
                 { text: 'Hugging Face', link: '/adapters/browser/hf' },
                 { text: 'Sina Finance', link: '/adapters/browser/sinafinance' },
+                { text: 'Spotify', link: '/adapters/browser/spotify' },
                 { text: 'Stack Overflow', link: '/adapters/browser/stackoverflow' },
                 { text: 'Wikipedia', link: '/adapters/browser/wikipedia' },
                 { text: 'Lobsters', link: '/adapters/browser/lobsters' },

package/docs/adapters/browser/band.md

@@ -0,0 +1,63 @@
+# Band
+
+**Mode**: 🔐 Browser · **Domain**: `www.band.us`
+
+Read posts, comments, and notifications from [Band](https://www.band.us), a private community platform. Authentication uses your logged-in Chrome session (cookie-based).
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli band bands` | List all Bands you belong to |
+| `opencli band posts <band_no>` | List posts from a Band |
+| `opencli band post <band_no> <post_no>` | Export full post content including nested comments |
+| `opencli band mentions` | Show notifications where you were @mentioned |
+
+## Usage Examples
+
+```bash
+# List all your bands (get band_no from here)
+opencli band bands
+
+# List recent posts in a band
+opencli band posts 12345678 --limit 10
+
+# Export a post with comments
+opencli band post 12345678 987654321
+
+# Export post body only (skip comments)
+opencli band post 12345678 987654321 --comments false
+
+# Export post and download attached photos
+opencli band post 12345678 987654321 --output ./band-photos
+
+# Show recent @mention notifications
+opencli band mentions --limit 20
+
+# Show only unread mentions
+opencli band mentions --unread true
+
+# Show all notification types
+opencli band mentions --filter all
+```
+
+### `band mentions` filter options
+
+| Filter | Description |
+|--------|-------------|
+| `mentioned` | Only notifications where you were @mentioned (default) |
+| `all` | All notifications |
+| `post` | Post-related notifications |
+| `comment` | Comment-related notifications |
+
+## Prerequisites
+
+- Chrome running and **logged into** [band.us](https://www.band.us)
+- [Browser Bridge extension](/guide/browser-bridge) installed
+
+## Notes
+
+- `band_no` is the numeric ID in the Band URL: `band.us/band/{band_no}/post`
+- `band bands` lists all your bands with their `band_no` values
+- `band post` output rows: `type=post` (the post itself), `type=comment` (top-level comment), `type=reply` (nested reply)
+- Photo downloads use the full-resolution URL (thumbnail query params are stripped automatically)

package/docs/adapters/browser/ones.md

@@ -0,0 +1,59 @@
+# ONES
+
+**Mode**: 🔐 Browser Bridge · **Domain**: `ones.cn` (self-hosted via `ONES_BASE_URL`)
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli ones login` | Login via Project API (`auth/login`) |
+| `opencli ones me` | Current user profile (`users/me`) |
+| `opencli ones token-info` | Token/user/team summary (`auth/token_info`) |
+| `opencli ones tasks` | Team task list with status/project labels and hours |
+| `opencli ones my-tasks` | My tasks (`assign`/`field004`/`owner`/`both`) |
+| `opencli ones task` | Task detail by UUID (`team/:team/task/:id/info`) |
+| `opencli ones worklog` | Log/backfill hours (GraphQL `addManhour` first, then REST fallbacks) |
+| `opencli ones logout` | Logout (`auth/logout`) |
+
+## Usage Examples
+
+```bash
+# Required: your ONES base URL
+export ONES_BASE_URL=https://your-instance.example.com
+
+# Optional if your deployment requires auth headers
+# export ONES_USER_ID=...
+# export ONES_AUTH_TOKEN=...
+
+# Login/profile
+opencli ones login --email you@company.com --password 'your-password'
+opencli ones me
+opencli ones token-info
+
+# Task lists
+opencli ones tasks <teamUUID> --limit 20
+opencli ones tasks <teamUUID> --project <projectUUID> --assign <userUUID>
+opencli ones my-tasks <teamUUID> --limit 100
+opencli ones my-tasks <teamUUID> --mode both
+
+# Task detail
+opencli ones task <taskUUID> --team <teamUUID>
+
+# Worklog: today / backfill
+opencli ones worklog <taskUUID> 2 --team <teamUUID>
+opencli ones worklog <taskUUID> 1.5 --team <teamUUID> --date 2026-03-23 --note "integration"
+
+opencli ones logout
+```
+
+## Prerequisites
+
+- Chrome running and logged into your ONES instance
+- [Browser Bridge extension](/guide/browser-bridge) installed
+- `ONES_BASE_URL` set to the same origin opened in Chrome
+
+## Notes
+
+- This adapter targets legacy ONES Project API deployments.
+- `ONES_TEAM_UUID` can be set to omit `--team` in `tasks` / `my-tasks` / `task`.
+- Hours display and input use `ONES_MANHOUR_SCALE` (default `100000`).

package/docs/adapters/browser/spotify.md

@@ -0,0 +1,62 @@
+# Spotify
+
+**Mode**: 🔑 OAuth API · **Domains**: `accounts.spotify.com`, `api.spotify.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli spotify auth` | Authenticate with Spotify and store tokens locally |
+| `opencli spotify status` | Show current playback status |
+| `opencli spotify play [query]` | Resume playback or search-and-play a track |
+| `opencli spotify pause` | Pause playback |
+| `opencli spotify next` | Skip to the next track |
+| `opencli spotify prev` | Skip to the previous track |
+| `opencli spotify volume <0-100>` | Set playback volume |
+| `opencli spotify search <query>` | Search Spotify tracks |
+| `opencli spotify queue <query>` | Add a track to the playback queue |
+| `opencli spotify shuffle <on|off>` | Toggle shuffle |
+| `opencli spotify repeat <off|track|context>` | Set repeat mode |
+
+## Usage Examples
+
+```bash
+# First-time setup
+opencli spotify auth
+
+# What is playing right now?
+opencli spotify status
+
+# Resume playback
+opencli spotify play
+
+# Search and immediately play a track
+opencli spotify play "Numb Linkin Park"
+
+# Search without playing
+opencli spotify search "Daft Punk" --limit 5 -f json
+
+# Queue a track
+opencli spotify queue "Get Lucky"
+
+# Playback controls
+opencli spotify pause
+opencli spotify next
+opencli spotify prev
+opencli spotify volume 35
+opencli spotify shuffle on
+opencli spotify repeat track
+```
+
+## Setup
+
+1. Create a Spotify app at <https://developer.spotify.com/dashboard>
+2. Add `http://127.0.0.1:8888/callback` to the app's Redirect URIs
+3. Fill in `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` in `~/.opencli/spotify.env`
+4. Run `opencli spotify auth`
+
+## Notes
+
+- Browser Bridge is not required.
+- Tokens are stored locally at `~/.opencli/spotify-tokens.json`.
+- Playback commands work best when you already have an active Spotify device/session.

package/docs/adapters/browser/tieba.md

@@ -0,0 +1,45 @@
+# Tieba
+
+**Mode**: 🔐 Browser · **Domain**: `tieba.baidu.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli tieba hot` | Read Tieba trending topics |
+| `opencli tieba posts <forum>` | List threads in one forum |
+| `opencli tieba search <keyword>` | Search threads across Tieba |
+| `opencli tieba read <thread-id>` | Read one thread page |
+
+## Usage Examples
+
+```bash
+# Trending topics
+opencli tieba hot --limit 5
+
+# List forum threads
+opencli tieba posts 李毅 --limit 10
+
+# Search Tieba
+opencli tieba search 编程 --limit 10
+
+# Read one thread
+opencli tieba read 10163164720 --limit 10
+
+# Read page 2 of a thread
+opencli tieba read 10163164720 --page 2 --limit 10
+
+# JSON output
+opencli tieba hot -f json
+```
+
+## Notes
+
+- `tieba search` currently supports only `--page 1`
+- `tieba read --limit` counts reply rows; page 1 may also include the main post
+
+## Prerequisites
+
+- Chrome running and able to open `tieba.baidu.com`
+- [Browser Bridge extension](/guide/browser-bridge) installed
+- For `posts`, `search`, and `read`, a valid Tieba login session in Chrome is recommended

package/docs/adapters/browser/xueqiu.md

@@ -12,6 +12,7 @@
 | `opencli xueqiu hot` | 获取雪球热门动态 |
 | `opencli xueqiu search` | 搜索雪球股票（代码或名称） |
 | `opencli xueqiu stock` | 获取雪球股票实时行情 |
+| `opencli xueqiu comments` | 获取单只股票的讨论动态（按时间排序） |
 | `opencli xueqiu watchlist` | 获取雪球自选股列表 |
 | `opencli xueqiu fund-holdings` | 获取蛋卷基金持仓明细（可用 `--account` 按子账户过滤） |
 | `opencli xueqiu fund-snapshot` | 获取蛋卷基金快照（总资产、子账户、持仓，推荐 `-f json`） |
@@ -28,6 +29,9 @@ opencli xueqiu search 茅台
 # View one stock
 opencli xueqiu stock SH600519
 
+# View recent discussions for one stock
+opencli xueqiu comments SH600519 --limit 5
+
 # Upcoming earnings dates
 opencli xueqiu earnings-date SH600519 --next
 
@@ -57,4 +61,5 @@ opencli xueqiu feed -v
 
 - `fund-holdings` exposes both market value and share fields (`volume`, `usableRemainShare`)
 - `fund-snapshot -f json` is the easiest way to persist a full account snapshot for later analysis or diffing
+- `comments` returns stock-scoped discussion posts from the symbol page, not reply threads under one parent post
 - If the commands return empty data, first confirm the logged-in browser can directly see the Danjuan asset page

package/docs/adapters/browser/zsxq.md

@@ -0,0 +1,49 @@
+# 知识星球 (ZSXQ)
+
+**Mode**: 🔐 Browser · **Domain**: `wx.zsxq.com`
+
+Read groups, topics, search results, dynamics, and single-topic details from [知识星球](https://wx.zsxq.com) using your logged-in Chrome session.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli zsxq groups` | List the groups your account has joined |
+| `opencli zsxq topics` | List topics in the active group |
+| `opencli zsxq topic <id>` | Fetch a single topic with comments |
+| `opencli zsxq search <keyword>` | Search topics inside a group |
+| `opencli zsxq dynamics` | List recent dynamics across groups |
+
+## Usage Examples
+
+```bash
+# List your groups
+opencli zsxq groups
+
+# List topics from the active group in Chrome
+opencli zsxq topics --limit 20
+
+# Search inside the active group
+opencli zsxq search "opencli"
+
+# Search inside a specific group explicitly
+opencli zsxq search "opencli" --group_id 123456789
+
+# Export a single topic with comments
+opencli zsxq topic 987654321 --comment_limit 20
+
+# Read recent dynamics across all joined groups
+opencli zsxq dynamics --limit 20
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** [wx.zsxq.com](https://wx.zsxq.com)
+- [Browser Bridge extension](/guide/browser-bridge) installed
+
+## Notes
+
+- `zsxq topics` and `zsxq search` use the current active group context from Chrome by default
+- If there is no active group context, pass `--group_id <id>` or open the target group in Chrome first
+- `zsxq groups` returns `group_id`, which you can reuse with `--group_id`
+- `zsxq topic` surfaces a missing topic as `NOT_FOUND` instead of a generic fetch error