@jackwener/opencli 1.5.5 → 1.5.7

package/dist/serialization.js

@@ -23,6 +23,7 @@ export function serializeCommand(cmd) {
         command: fullName(cmd),
         site: cmd.site,
         name: cmd.name,
+        aliases: cmd.aliases ?? [],
         description: cmd.description,
         strategy: strategyLabel(cmd),
         browser: !!cmd.browser,
@@ -67,6 +68,8 @@ export function formatRegistryHelpText(cmd) {
         meta.push(`Deprecated: ${typeof cmd.deprecated === 'string' ? cmd.deprecated : 'yes'}`);
     if (cmd.replacedBy)
         meta.push(`Use instead: ${cmd.replacedBy}`);
+    if (cmd.aliases?.length)
+        meta.push(`Aliases: ${cmd.aliases.join(', ')}`);
     lines.push(meta.join(' | '));
     if (cmd.columns?.length)
         lines.push(`Output columns: ${cmd.columns.join(', ')}`);

package/dist/serialization.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { Strategy } from './registry.js';
-import { formatRegistryHelpText } from './serialization.js';
+import { formatRegistryHelpText, serializeCommand } from './serialization.js';
 describe('formatRegistryHelpText', () => {
     it('summarizes long choices lists so help text stays readable', () => {
         const cmd = {
@@ -20,4 +20,20 @@ describe('formatRegistryHelpText', () => {
         };
         expect(formatRegistryHelpText(cmd)).toContain('--field: all-fields, topic, title, author, ... (+3 more)');
     });
+    it('includes aliases in structured serialization and help text', () => {
+        const cmd = {
+            site: 'demo',
+            name: 'get',
+            aliases: ['metadata'],
+            description: 'Demo command',
+            strategy: Strategy.COOKIE,
+            browser: true,
+            args: [],
+        };
+        expect(serializeCommand(cmd)).toMatchObject({
+            command: 'demo/get',
+            aliases: ['metadata'],
+        });
+        expect(formatRegistryHelpText(cmd)).toContain('Aliases: metadata');
+    });
 });

package/dist/tui.d.ts

@@ -20,3 +20,10 @@ export declare function checkboxPrompt(items: CheckboxItem[], opts?: {
     title?: string;
     hint?: string;
 }): Promise<string[]>;
+/**
+ * Simple yes/no confirmation prompt.
+ *
+ * In non-TTY environments, returns `defaultYes` (defaults to true) without blocking.
+ * In TTY, waits for a single keypress: y/Enter → true, n/Esc/q → false.
+ */
+export declare function confirmPrompt(message: string, defaultYes?: boolean): Promise<boolean>;

package/dist/tui.js

@@ -138,3 +138,55 @@ export async function checkboxPrompt(items, opts = {}) {
         draw();
     });
 }
+/**
+ * Simple yes/no confirmation prompt.
+ *
+ * In non-TTY environments, returns `defaultYes` (defaults to true) without blocking.
+ * In TTY, waits for a single keypress: y/Enter → true, n/Esc/q → false.
+ */
+export async function confirmPrompt(message, defaultYes = true) {
+    const { stdin, stdout } = process;
+    if (!stdin.isTTY)
+        return defaultYes;
+    const hint = defaultYes ? '[Y/n]' : '[y/N]';
+    stdout.write(`  ${message} ${chalk.dim(hint)} `);
+    return new Promise((resolve) => {
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        function cleanup() {
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            stdin.removeListener('data', onData);
+            stdout.write('\n');
+        }
+        function onData(data) {
+            const key = data.toString();
+            // Ctrl+C
+            if (key === '\x03') {
+                cleanup();
+                process.exit(EXIT_CODES.INTERRUPTED);
+            }
+            // Enter — use default
+            if (key === '\r' || key === '\n') {
+                cleanup();
+                resolve(defaultYes);
+                return;
+            }
+            // y/Y — yes
+            if (key === 'y' || key === 'Y') {
+                cleanup();
+                resolve(true);
+                return;
+            }
+            // n/N/q/Esc — no
+            if (key === 'n' || key === 'N' || key === 'q' || key === '\x1b') {
+                cleanup();
+                resolve(false);
+                return;
+            }
+            // Ignore other keys
+        }
+        stdin.on('data', onData);
+    });
+}

package/dist/tui.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tui.test.js

@@ -0,0 +1,19 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { confirmPrompt } from './tui.js';
+describe('confirmPrompt', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns defaultYes when stdin is not TTY', async () => {
+        const result = await confirmPrompt('Restart?', true);
+        expect(result).toBe(true);
+    });
+    it('returns false when defaultYes is false and non-TTY', async () => {
+        const result = await confirmPrompt('Restart?', false);
+        expect(result).toBe(false);
+    });
+    it('defaults to true when defaultYes is omitted and non-TTY', async () => {
+        const result = await confirmPrompt('Restart?');
+        expect(result).toBe(true);
+    });
+});

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/dist/weixin-download.test.js

@@ -27,4 +27,18 @@ describe('weixin publish time extraction', () => {
         const extractInPage = eval(mod.buildExtractWechatPublishTimeJs());
         expect(extractInPage('2026年3月24日 22:38', 'var create_time = "1711291080";')).toBe('2026年3月24日 22:38');
     });
+    it('detects WeChat verification gate pages', async () => {
+        const mod = await loadModule();
+        expect(mod.detectWechatAccessIssue('环境异常 当前环境异常，完成验证后即可继续访问。 去验证', '<html><body><a id="js_verify">去验证</a></body></html>')).toBe('environment verification required');
+    });
+    it('browser access detector matches the server-side verifier', async () => {
+        const mod = await loadModule();
+        const detectInPage = eval(mod.buildDetectWechatAccessIssueJs());
+        expect(detectInPage('环境异常 当前环境异常，完成验证后即可继续访问。 去验证', '<html>secitptpage/verify.html<a id="js_verify">去验证</a></html>')).toBe('environment verification required');
+    });
+    it('picks the first non-empty WeChat metadata field', async () => {
+        const mod = await loadModule();
+        expect(mod.pickFirstWechatMetaText('', 'Name cleared', '数字生命卡兹克')).toBe('数字生命卡兹克');
+        expect(mod.pickFirstWechatMetaText('', '  聊聊刚刚上线的PixVerse V6视频模型。  ')).toBe('聊聊刚刚上线的PixVerse V6视频模型。');
+    });
 });

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,8 +69,10 @@ 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: 'NotebookLM', link: '/adapters/browser/notebooklm' },
                 { text: 'WeRead', link: '/adapters/browser/weread' },
                 { text: 'Douban', link: '/adapters/browser/douban' },
                 { text: 'Sina Blog', link: '/adapters/browser/sinablog' },
@@ -104,6 +107,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/notebooklm.md

@@ -0,0 +1,69 @@
+# NotebookLM
+
+**Mode**: 🔐 Browser Bridge · **Domain**: `notebooklm.google.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli notebooklm status` | Check whether NotebookLM is reachable in the current Chrome session |
+| `opencli notebooklm list` | List notebooks visible from the NotebookLM home page |
+| `opencli notebooklm current` | Show metadata for the currently opened notebook tab |
+| `opencli notebooklm get` | Get richer metadata for the current notebook |
+| `opencli notebooklm source-list` | List sources in the current notebook |
+| `opencli notebooklm source-get <source>` | Resolve one source in the current notebook by id or title |
+| `opencli notebooklm source-fulltext <source>` | Fetch extracted source fulltext through NotebookLM RPC |
+| `opencli notebooklm source-guide <source>` | Fetch guide summary and keywords for one source |
+| `opencli notebooklm history` | List conversation history threads for the current notebook |
+| `opencli notebooklm note-list` | List Studio notes visible in the current notebook |
+| `opencli notebooklm notes-get <note>` | Read the currently visible Studio note by title |
+| `opencli notebooklm bind-current` | Bind the current active NotebookLM tab into the `site:notebooklm` workspace |
+| `opencli notebooklm summary` | Read the current notebook summary |
+
+## Compatibility Aliases
+
+| Alias | Canonical command |
+|-------|-------------------|
+| `opencli notebooklm metadata` | `opencli notebooklm get` |
+| `opencli notebooklm use` | `opencli notebooklm bind-current` |
+| `opencli notebooklm notes-list` | `opencli notebooklm note-list` |
+
+## Positioning
+
+This adapter reuses the existing OpenCLI Browser Bridge runtime:
+
+- no custom NotebookLM extension
+- no exported cookie replay
+- requests and page state stay in the real Chrome session
+
+The current milestone focuses on a stable NotebookLM read surface in desktop Chrome with an already logged-in Google account.
+
+## Usage Examples
+
+```bash
+opencli notebooklm status
+opencli notebooklm list -f json
+opencli notebooklm current -f json
+opencli notebooklm metadata -f json
+opencli notebooklm source-list -f json
+opencli notebooklm source-get "Quarterly report" -f json
+opencli notebooklm source-guide "Quarterly report" -f json
+opencli notebooklm source-fulltext "Quarterly report" -f json
+opencli notebooklm history -f json
+opencli notebooklm notes-list -f json
+opencli notebooklm notes-get "Draft note" -f json
+opencli notebooklm summary -f json
+opencli notebooklm use -f json
+```
+
+## Prerequisites
+
+- Chrome running and logged into Google / NotebookLM
+- [Browser Bridge extension](/guide/browser-bridge) installed
+- NotebookLM accessible in the current browser session
+
+## Notes
+
+- Notebook-oriented commands assume you already have the target notebook open in Chrome, or that `opencli notebooklm use` can bind an existing notebook tab into `site:notebooklm`.
+- `list`, `get`, `source-list`, `history`, `source-fulltext`, and `source-guide` prefer NotebookLM RPC paths and fall back only when the richer path is unavailable.
+- `notes-get` currently reads note content only from the visible Studio note editor; if the note is listed but not open, open it in NotebookLM first and then retry.

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/xiaohongshu.md

@@ -7,15 +7,18 @@
 | Command | Description |
 |---------|-------------|
 | `opencli xiaohongshu search` | Search notes by keyword (returns title, author, likes, URL) |
-| `opencli xiaohongshu notifications` | |
-| `opencli xiaohongshu feed` | |
-| `opencli xiaohongshu user` | |
-| `opencli xiaohongshu download` | |
-| `opencli xiaohongshu creator-notes` | |
-| `opencli xiaohongshu creator-note-detail` | |
-| `opencli xiaohongshu creator-notes-summary` | |
-| `opencli xiaohongshu creator-profile` | |
-| `opencli xiaohongshu creator-stats` | |
+| `opencli xiaohongshu note` | Read full note content (title, author, description, likes, collects, comments, tags) |
+| `opencli xiaohongshu comments` | Read comments from a note (`--with-replies` for nested 楼中楼 replies) |
+| `opencli xiaohongshu feed` | Home feed recommendations (via Pinia store interception) |
+| `opencli xiaohongshu notifications` | User notifications (mentions, likes, connections) |
+| `opencli xiaohongshu user` | Get public notes from a user profile |
+| `opencli xiaohongshu download` | Download images and videos from a note |
+| `opencli xiaohongshu publish` | Publish image-text notes (creator center UI automation) |
+| `opencli xiaohongshu creator-notes` | Creator's note list with per-note metrics |
+| `opencli xiaohongshu creator-note-detail` | Detailed analytics for a single creator note |
+| `opencli xiaohongshu creator-notes-summary` | Combined note list + detail analytics summary |
+| `opencli xiaohongshu creator-profile` | Creator account info (followers, growth level) |
+| `opencli xiaohongshu creator-stats` | Creator data overview (views, likes, collects, trends) |
 
 ## Usage Examples
 
@@ -23,13 +26,19 @@
 # Search for notes
 opencli xiaohongshu search 美食 --limit 10
 
+# Read a note's full content (pass URL from search results to preserve xsec_token)
+opencli xiaohongshu note "https://www.xiaohongshu.com/search_result/<id>?xsec_token=..."
+
+# Read comments with nested replies (楼中楼)
+opencli xiaohongshu comments "https://www.xiaohongshu.com/search_result/<id>?xsec_token=..." --with-replies --limit 20
+
 # JSON output
 opencli xiaohongshu search 旅行 -f json
 
 # Other commands
 opencli xiaohongshu feed
 opencli xiaohongshu notifications
-opencli xiaohongshu download <url>
+opencli xiaohongshu download <note-id or url>
 ```
 
 ## Prerequisites

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