@jackwener/opencli 1.5.9 → 1.6.0

package/dist/clis/xiaohongshu/note.test.js

@@ -112,6 +112,55 @@ describe('xiaohongshu note', () => {
         const page = createPageMock({ loginWall: false, notFound: true });
         await expect(command.func(page, { 'note-id': 'abc123' })).rejects.toThrow('returned no data');
     });
+    it('throws a token hint when the note page renders as an empty shell', async () => {
+        const page = createPageMock({
+            loginWall: false,
+            notFound: false,
+            title: '',
+            desc: '',
+            author: '',
+            likes: '',
+            collects: '',
+            comments: '',
+            tags: [],
+        });
+        try {
+            await command.func(page, { 'note-id': '69ca3927000000001a020fd5' });
+            throw new Error('expected xiaohongshu note to fail on an empty shell page');
+        }
+        catch (error) {
+            expect(error).toMatchObject({
+                code: 'EMPTY_RESULT',
+                hint: expect.stringMatching(/xsec_token|full url|search_result/i),
+            });
+        }
+    });
+    it('keeps the empty-shell hint generic when the user already passed a full URL', async () => {
+        const page = createPageMock({
+            loginWall: false,
+            notFound: false,
+            title: '',
+            desc: '',
+            author: '',
+            likes: '',
+            collects: '',
+            comments: '',
+            tags: [],
+        });
+        try {
+            await command.func(page, {
+                'note-id': 'https://www.xiaohongshu.com/search_result/69ca3927000000001a020fd5?xsec_token=abc',
+            });
+            throw new Error('expected xiaohongshu note to fail on an empty shell page');
+        }
+        catch (error) {
+            expect(error).toMatchObject({
+                code: 'EMPTY_RESULT',
+                hint: expect.stringContaining('loaded without visible content'),
+            });
+            expect(error.hint).not.toContain('bare note ID');
+        }
+    });
     it('normalizes placeholder text to 0 for zero-count metrics', async () => {
         const page = createPageMock({
             loginWall: false, notFound: false,

package/dist/commanderAdapter.js

@@ -212,7 +212,7 @@ async function renderError(err, cmdName, verbose) {
     if (err instanceof SelectorError || err instanceof EmptyResultError) {
         const icon = ERROR_ICONS[err.code] ?? '⚠️';
         console.error(chalk.red(`${icon} ${err.message}`));
-        console.error(chalk.yellow('→ The page structure may have changed — this adapter may be outdated.'));
+        console.error(chalk.yellow(`→ ${err.hint ?? 'The page structure may have changed — this adapter may be outdated.'}`));
         console.error(chalk.dim(`  Debug:  ${cmdName} --verbose`));
         console.error(chalk.dim(`  Report: ${ISSUES_URL}`));
         return;

package/dist/commanderAdapter.test.js

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { Command } from 'commander';
+import { EmptyResultError, SelectorError } from './errors.js';
 const { mockExecuteCommand, mockRenderOutput } = vi.hoisted(() => ({
     mockExecuteCommand: vi.fn(),
     mockRenderOutput: vi.fn(),
@@ -157,3 +158,45 @@ describe('commanderAdapter default formats', () => {
         expect(mockRenderOutput).toHaveBeenCalledWith([{ response: 'hello' }], expect.objectContaining({ fmt: 'json' }));
     });
 });
+describe('commanderAdapter empty result hints', () => {
+    const cmd = {
+        site: 'xiaohongshu',
+        name: 'note',
+        description: 'Read one note',
+        browser: false,
+        args: [
+            { name: 'note-id', positional: true, required: true, help: 'Note ID' },
+        ],
+        func: vi.fn(),
+    };
+    beforeEach(() => {
+        mockExecuteCommand.mockReset();
+        mockRenderOutput.mockReset();
+        delete process.env.OPENCLI_VERBOSE;
+        process.exitCode = undefined;
+    });
+    it('prints the adapter hint instead of the generic outdated-adapter message', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        mockExecuteCommand.mockRejectedValueOnce(new EmptyResultError('xiaohongshu/note', 'Pass the full search_result URL with xsec_token instead of a bare note ID.'));
+        await program.parseAsync(['node', 'opencli', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+        const output = errorSpy.mock.calls.flat().join('\n');
+        expect(output).toContain('xsec_token');
+        expect(output).not.toContain('this adapter may be outdated');
+        errorSpy.mockRestore();
+    });
+    it('prints selector-specific hints too', async () => {
+        const program = new Command();
+        const siteCmd = program.command('xiaohongshu');
+        registerCommandToProgram(siteCmd, cmd);
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        mockExecuteCommand.mockRejectedValueOnce(new SelectorError('.note-title', 'The note title selector no longer matches the current page.'));
+        await program.parseAsync(['node', 'opencli', 'xiaohongshu', 'note', '69ca3927000000001a020fd5']);
+        const output = errorSpy.mock.calls.flat().join('\n');
+        expect(output).toContain('selector no longer matches');
+        expect(output).not.toContain('this adapter may be outdated');
+        errorSpy.mockRestore();
+    });
+});

package/dist/commands/daemon.js

@@ -5,46 +5,7 @@
  *   opencli daemon restart — stop + respawn
  */
 import chalk from 'chalk';
-import { DEFAULT_DAEMON_PORT } from '../constants.js';
-const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
-async function fetchStatus() {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 2000);
-    try {
-        const res = await fetch(`${DAEMON_URL}/status`, {
-            headers: { 'X-OpenCLI': '1' },
-            signal: controller.signal,
-        });
-        if (!res.ok)
-            return null;
-        return await res.json();
-    }
-    catch {
-        return null;
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-async function requestShutdown() {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 5000);
-    try {
-        const res = await fetch(`${DAEMON_URL}/shutdown`, {
-            method: 'POST',
-            headers: { 'X-OpenCLI': '1' },
-            signal: controller.signal,
-        });
-        return res.ok;
-    }
-    catch {
-        return false;
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
+import { fetchDaemonStatus, requestDaemonShutdown } from '../browser/daemon-client.js';
 function formatUptime(seconds) {
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
@@ -65,7 +26,7 @@ function formatTimeSince(timestampMs) {
     return `${h}h ${m % 60}m ago`;
 }
 export async function daemonStatus() {
-    const status = await fetchStatus();
+    const status = await fetchDaemonStatus();
     if (!status) {
         console.log(`Daemon: ${chalk.dim('not running')}`);
         return;
@@ -78,12 +39,12 @@ export async function daemonStatus() {
     console.log(`Port: ${status.port}`);
 }
 export async function daemonStop() {
-    const status = await fetchStatus();
+    const status = await fetchDaemonStatus();
     if (!status) {
         console.log(chalk.dim('Daemon is not running.'));
         return;
     }
-    const ok = await requestShutdown();
+    const ok = await requestDaemonShutdown();
     if (ok) {
         console.log(chalk.green('Daemon stopped.'));
     }
@@ -93,9 +54,9 @@ export async function daemonStop() {
     }
 }
 export async function daemonRestart() {
-    const status = await fetchStatus();
+    const status = await fetchDaemonStatus();
     if (status) {
-        const ok = await requestShutdown();
+        const ok = await requestDaemonShutdown();
         if (!ok) {
             console.error(chalk.red('Failed to stop daemon.'));
             process.exitCode = 1;
@@ -105,7 +66,7 @@ export async function daemonRestart() {
         const deadline = Date.now() + 5000;
         while (Date.now() < deadline) {
             await new Promise(r => setTimeout(r, 200));
-            if (!(await fetchStatus()))
+            if (!(await fetchDaemonStatus()))
                 break;
         }
     }

package/dist/commands/daemon.test.js

@@ -1,4 +1,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+const { fetchDaemonStatusMock, requestDaemonShutdownMock, } = vi.hoisted(() => ({
+    fetchDaemonStatusMock: vi.fn(),
+    requestDaemonShutdownMock: vi.fn(),
+}));
 vi.mock('chalk', () => ({
     default: {
         green: (s) => s,
@@ -13,6 +17,10 @@ vi.mock('../browser/bridge.js', () => ({
         connect = mockConnect;
     },
 }));
+vi.mock('../browser/daemon-client.js', () => ({
+    fetchDaemonStatus: fetchDaemonStatusMock,
+    requestDaemonShutdown: requestDaemonShutdownMock,
+}));
 import { daemonStatus, daemonStop, daemonRestart } from './daemon.js';
 describe('daemon commands', () => {
     let logSpy;
@@ -20,6 +28,8 @@ describe('daemon commands', () => {
     beforeEach(() => {
         logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
         errorSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        fetchDaemonStatusMock.mockReset();
+        requestDaemonShutdownMock.mockReset();
     });
     afterEach(() => {
         vi.restoreAllMocks();
@@ -27,12 +37,12 @@ describe('daemon commands', () => {
     });
     describe('daemonStatus', () => {
         it('shows "not running" when daemon is unreachable', async () => {
-            vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+            fetchDaemonStatusMock.mockResolvedValue(null);
             await daemonStatus();
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
         });
         it('shows "not running" when daemon returns non-ok response', async () => {
-            vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false }));
+            fetchDaemonStatusMock.mockResolvedValue(null);
             await daemonStatus();
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
         });
@@ -47,10 +57,7 @@ describe('daemon commands', () => {
                 memoryMB: 64,
                 port: 19825,
             };
-            vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-                ok: true,
-                json: () => Promise.resolve(status),
-            }));
+            fetchDaemonStatusMock.mockResolvedValue(status);
             await daemonStatus();
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('running'));
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('PID 12345'));
@@ -70,66 +77,45 @@ describe('daemon commands', () => {
                 memoryMB: 32,
                 port: 19825,
             };
-            vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
-                ok: true,
-                json: () => Promise.resolve(status),
-            }));
+            fetchDaemonStatusMock.mockResolvedValue(status);
             await daemonStatus();
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('disconnected'));
         });
     });
     describe('daemonStop', () => {
         it('reports "not running" when daemon is unreachable', async () => {
-            vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+            fetchDaemonStatusMock.mockResolvedValue(null);
             await daemonStop();
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('not running'));
         });
         it('sends shutdown and reports success', async () => {
-            const statusResponse = {
+            fetchDaemonStatusMock.mockResolvedValue({
                 ok: true,
-                json: () => Promise.resolve({
-                    ok: true,
-                    pid: 12345,
-                    uptime: 100,
-                    extensionConnected: true,
-                    pending: 0,
-                    lastCliRequestTime: Date.now(),
-                    memoryMB: 50,
-                    port: 19825,
-                }),
-            };
-            const shutdownResponse = { ok: true };
-            const mockFetch = vi.fn()
-                .mockResolvedValueOnce(statusResponse)
-                .mockResolvedValueOnce(shutdownResponse);
-            vi.stubGlobal('fetch', mockFetch);
+                pid: 12345,
+                uptime: 100,
+                extensionConnected: true,
+                pending: 0,
+                lastCliRequestTime: Date.now(),
+                memoryMB: 50,
+                port: 19825,
+            });
+            requestDaemonShutdownMock.mockResolvedValue(true);
             await daemonStop();
-            // Verify shutdown was called with POST
-            expect(mockFetch).toHaveBeenCalledTimes(2);
-            const shutdownCall = mockFetch.mock.calls[1];
-            expect(shutdownCall[0]).toContain('/shutdown');
-            expect(shutdownCall[1]).toMatchObject({ method: 'POST' });
+            expect(requestDaemonShutdownMock).toHaveBeenCalledTimes(1);
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon stopped'));
         });
         it('reports failure when shutdown request fails', async () => {
-            const statusResponse = {
+            fetchDaemonStatusMock.mockResolvedValue({
                 ok: true,
-                json: () => Promise.resolve({
-                    ok: true,
-                    pid: 12345,
-                    uptime: 100,
-                    extensionConnected: true,
-                    pending: 0,
-                    lastCliRequestTime: Date.now(),
-                    memoryMB: 50,
-                    port: 19825,
-                }),
-            };
-            const shutdownResponse = { ok: false };
-            const mockFetch = vi.fn()
-                .mockResolvedValueOnce(statusResponse)
-                .mockResolvedValueOnce(shutdownResponse);
-            vi.stubGlobal('fetch', mockFetch);
+                pid: 12345,
+                uptime: 100,
+                extensionConnected: true,
+                pending: 0,
+                lastCliRequestTime: Date.now(),
+                memoryMB: 50,
+                port: 19825,
+            });
+            requestDaemonShutdownMock.mockResolvedValue(false);
             await daemonStop();
             expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon'));
         });
@@ -146,37 +132,26 @@ describe('daemon commands', () => {
             port: 19825,
         };
         it('starts daemon directly when not running', async () => {
-            vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
+            fetchDaemonStatusMock.mockResolvedValue(null);
             mockConnect.mockResolvedValue(undefined);
             await daemonRestart();
             expect(mockConnect).toHaveBeenCalledWith({ timeout: 10 });
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon restarted'));
         });
         it('stops then starts when daemon is running', async () => {
-            const mockFetch = vi.fn()
-                // First call: fetchStatus in daemonRestart — daemon is running
-                .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(statusData) })
-                // Second call: requestShutdown — success
-                .mockResolvedValueOnce({ ok: true })
-                // Subsequent calls: polling fetchStatus until unreachable
-                .mockRejectedValue(new Error('ECONNREFUSED'));
-            vi.stubGlobal('fetch', mockFetch);
+            fetchDaemonStatusMock
+                .mockResolvedValueOnce(statusData)
+                .mockResolvedValueOnce(null);
+            requestDaemonShutdownMock.mockResolvedValue(true);
             mockConnect.mockResolvedValue(undefined);
             await daemonRestart();
-            // Verify shutdown was called
-            const shutdownCall = mockFetch.mock.calls[1];
-            expect(shutdownCall[0]).toContain('/shutdown');
-            expect(shutdownCall[1]).toMatchObject({ method: 'POST' });
+            expect(requestDaemonShutdownMock).toHaveBeenCalledTimes(1);
             expect(mockConnect).toHaveBeenCalledWith({ timeout: 10 });
             expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Daemon restarted'));
         });
         it('aborts when shutdown fails', async () => {
-            const mockFetch = vi.fn()
-                // fetchStatus — daemon is running
-                .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(statusData) })
-                // requestShutdown — failure
-                .mockResolvedValueOnce({ ok: false });
-            vi.stubGlobal('fetch', mockFetch);
+            fetchDaemonStatusMock.mockResolvedValue(statusData);
+            requestDaemonShutdownMock.mockResolvedValue(false);
             await daemonRestart();
             expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Failed to stop daemon'));
             expect(mockConnect).not.toHaveBeenCalled();

package/dist/discovery.js

@@ -66,6 +66,33 @@ export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
         writeCompatShimIfNeeded(path.join(baseDir, 'errors.js'), `export * from '${errorsUrl}';\n`),
         writeCompatShimIfNeeded(path.join(baseDir, 'package.json'), `${JSON.stringify({ name: 'opencli-user-runtime', private: true, type: 'module' }, null, 2)}\n`),
     ]);
+    // Create node_modules/@jackwener/opencli symlink so user TS CLIs can import
+    // from '@jackwener/opencli/registry' (the package export).
+    // This is needed because ~/.opencli/clis/ is outside opencli's node_modules tree.
+    const opencliRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    const symlinkDir = path.join(baseDir, 'node_modules', '@jackwener');
+    const symlinkPath = path.join(symlinkDir, 'opencli');
+    try {
+        // Only recreate if symlink is missing or points to wrong target
+        let needsUpdate = true;
+        try {
+            const existing = await fs.promises.readlink(symlinkPath);
+            if (existing === opencliRoot)
+                needsUpdate = false;
+        }
+        catch { /* doesn't exist */ }
+        if (needsUpdate) {
+            await fs.promises.mkdir(symlinkDir, { recursive: true });
+            try {
+                await fs.promises.unlink(symlinkPath);
+            }
+            catch { /* doesn't exist */ }
+            await fs.promises.symlink(opencliRoot, symlinkPath, 'dir');
+        }
+    }
+    catch {
+        // Non-fatal: npm-linked installs or permission issues may prevent this
+    }
 }
 /**
  * Discover and register CLI commands.

package/dist/types.d.ts

@@ -80,4 +80,12 @@ export interface IPage {
     getCurrentUrl?(): Promise<string | null>;
     /** Returns the active tab ID, or undefined if not yet resolved. */
     getActiveTabId?(): number | undefined;
+    /** Send a raw CDP command via chrome.debugger passthrough. */
+    cdp?(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Click at native coordinates via CDP Input.dispatchMouseEvent. */
+    nativeClick?(x: number, y: number): Promise<void>;
+    /** Type text via CDP Input.insertText. */
+    nativeType?(text: string): Promise<void>;
+    /** Press a key via CDP Input.dispatchKeyEvent. */
+    nativeKeyPress?(key: string, modifiers?: string[]): Promise<void>;
 }

package/docs/guide/getting-started.md

@@ -48,6 +48,27 @@ opencli bilibili hot -f csv     # CSV
 opencli bilibili hot -v         # Verbose: show pipeline debug
 ```
 
+### Tab Completion
+
+OpenCLI supports intelligent tab completion to speed up command input:
+
+```bash
+# Add shell completion to your startup config
+echo 'eval "$(opencli completion zsh)"' >> ~/.zshrc              # Zsh
+echo 'eval "$(opencli completion bash)"' >> ~/.bashrc            # Bash
+echo 'opencli completion fish | source' >> ~/.config/fish/config.fish  # Fish
+
+# Restart your shell, then press Tab to complete:
+opencli [Tab]          # Complete site names (bilibili, zhihu, twitter...)
+opencli bilibili [Tab] # Complete commands (hot, search, me, download...)
+```
+
+The completion includes:
+- All available sites and adapters
+- Built-in commands (list, explore, validate...)
+- Command aliases
+- Real-time updates as you add new adapters
+
 ## Next Steps
 
 - [Installation details](/guide/installation)

package/docs/superpowers/specs/2026-04-02-browse-skill-testing-design.md

@@ -0,0 +1,144 @@
+# Browse Skill Testing Design
+
+Two-layer testing framework for `opencli browse` commands and the
+Claude Code skill integration.
+
+## Goal
+
+Verify that `opencli browse` works reliably on real websites and that
+Claude Code can use the skill to complete browser tasks end-to-end.
+
+## Architecture
+
+```
+autoresearch/
+├── browse-tasks.json       ← 59 task definitions with browse command sequences
+├── eval-browse.ts          ← Layer 1: deterministic browse command testing
+├── eval-skill.ts           ← Layer 2: Claude Code skill E2E testing
+├── run-browse.sh           ← Launch Layer 1
+├── run-skill.sh            ← Launch Layer 2
+├── baseline-browse.txt     ← Layer 1 best score
+├── baseline-skill.txt      ← Layer 2 best score
+└── results/                ← Per-run results (gitignored)
+```
+
+## Layer 1: Deterministic Browse Command Testing
+
+Tests `opencli browse` commands directly on real websites. No LLM
+involved — pure command reliability testing.
+
+### How It Works
+
+Each task defines a sequence of browse commands and a judge for the
+last command's output:
+
+```json
+{
+  "name": "hn-top-stories",
+  "steps": [
+    "opencli browse open https://news.ycombinator.com",
+    "opencli browse eval \"JSON.stringify([...document.querySelectorAll('.titleline a')].slice(0,5).map(a=>({title:a.textContent,url:a.href})))\""
+  ],
+  "judge": { "type": "arrayMinLength", "minLength": 5 }
+}
+```
+
+### Execution
+
+```bash
+./autoresearch/run-browse.sh
+```
+
+- Runs all 59 tasks serially
+- Each task: execute steps → judge last step output → pass/fail
+- `opencli browse close` between tasks for clean state
+- Expected: ~2 minutes, $0 cost
+
+### Task Categories
+
+| Category | Count | Example |
+|----------|-------|---------|
+| extract | 9 | Open page, eval JS to extract data |
+| list | 10 | Open page, eval JS to extract array |
+| search | 6 | Open, type query, keys Enter, eval results |
+| nav | 7 | Open, click link, eval new page title |
+| scroll | 5 | Open, scroll, eval footer/hidden content |
+| form | 6 | Open, type into fields, eval field values |
+| complex | 6 | Multi-step: open → click → navigate → extract |
+| bench | 10 | Test set (various) |
+
+## Layer 2: Claude Code Skill E2E Testing
+
+Spawns Claude Code with the opencli-operate skill to complete tasks
+autonomously using browse commands.
+
+### How It Works
+
+```bash
+claude -p \
+  --system-prompt "$(cat skills/opencli-operate/SKILL.md)" \
+  --dangerously-skip-permissions \
+  --allowedTools "Bash(opencli:*)" \
+  --output-format json \
+  "用 opencli browse 完成任务：Extract the top 5 stories from Hacker News with title and score. Start URL: https://news.ycombinator.com"
+```
+
+### Execution
+
+```bash
+./autoresearch/run-skill.sh
+```
+
+- Runs all 59 tasks serially
+- Each task: spawn Claude Code → it uses browse commands autonomously → judge output
+- Expected: ~20 minutes, ~$5-10
+
+### Judge
+
+Both layers use the same judge types:
+
+| Type | Description |
+|------|-------------|
+| `contains` | Output contains a substring |
+| `arrayMinLength` | Output is an array with ≥ N items |
+| `arrayFieldsPresent` | Array items have required fields |
+| `nonEmpty` | Output is non-empty |
+| `matchesPattern` | Output matches a regex |
+
+## Output Format
+
+```
+🔬 Layer 1: Browse Commands — 59 tasks
+
+  [1/59] extract-title-example... ✓ (0.5s)
+  [2/59] hn-top-stories... ✓ (1.2s)
+  ...
+
+  Score: 55/59 (93%)
+  Time: 2min
+  Cost: $0
+
+🔬 Layer 2: Skill E2E — 59 tasks
+
+  [1/59] extract-title-example... ✓ (8s, $0.01)
+  [2/59] hn-top-stories... ✓ (15s, $0.08)
+  ...
+
+  Score: 52/59 (88%)
+  Time: 20min
+  Cost: $6.50
+```
+
+## Constraints
+
+- All 59 tasks run on real websites (no mocks)
+- Layer 1: zero LLM cost, ~2 min
+- Layer 2: ~$5-10 LLM cost, ~20 min
+- Results saved to `autoresearch/results/` (gitignored)
+- Baselines tracked in `baseline-browse.txt` and `baseline-skill.txt`
+
+## Success Criteria
+
+- Layer 1 ≥ 90% (browse commands work on real sites)
+- Layer 2 ≥ 85% (Claude Code can use skill effectively)
+- Both layers cover all 8 task categories

package/docs/zh/guide/getting-started.md

@@ -32,6 +32,27 @@ opencli bilibili hot -f md      # Markdown
 opencli bilibili hot -f csv     # CSV
 ```
 
+## 终端自动补全
+
+OpenCLI 支持智能的 Tab 自动补全，加快命令输入：
+
+```bash
+# 把自动补全加入 shell 启动配置
+echo 'eval "$(opencli completion zsh)"' >> ~/.zshrc              # Zsh
+echo 'eval "$(opencli completion bash)"' >> ~/.bashrc            # Bash
+echo 'opencli completion fish | source' >> ~/.config/fish/config.fish  # Fish
+
+# 重启 shell 后，按 Tab 键补全：
+opencli [Tab]          # 补全站点名称（bilibili、zhihu、twitter...）
+opencli bilibili [Tab] # 补全命令（hot、search、me、download...）
+```
+
+补全功能包含：
+- 所有可用的站点和适配器
+- 内置命令（list、explore、validate...）
+- 命令别名
+- 新增适配器时的实时更新
+
 ## 下一步
 
 - [安装详情](/zh/guide/installation)

package/extension/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "opencli-extension",
-  "version": "1.5.4",
+  "version": "1.5.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "opencli-extension",
-      "version": "1.5.4",
+      "version": "1.5.5",
       "devDependencies": {
         "@types/chrome": "^0.0.287",
         "typescript": "^5.7.0",