yiyan-browser-agent 1.3.3 → 1.4.0

package/README.md

@@ -1,145 +1,228 @@
-# doubao-browser-agent
+# yiyan-browser-agent
 
-NPM package for interacting with Doubao (豆包) web version via Playwright.
+NPM package for interacting with Yiyan (文心一言) web version via Playwright. No API key required.
 
 ## Features
 
-- Automated browser interaction with Doubao web version
-- Automatic Chrome profile management for login persistence
-- Retry mechanism for network failures
-- CLI and Node.js API support
-- TypeScript support with full type definitions
+- 🤖 Automated browser interaction with Yiyan web version
+- 🔐 Login persistence via Playwright session
+- 🌍 Cross-platform: Windows / Ubuntu / macOS
+- 📦 Auto-download Chromium (~150MB)
+- 🛠️ CLI and Node.js API support
+- 📝 TypeScript support with full type definitions
 
-## Prerequisites
+## Installation
 
-1. **Chrome browser** installed on your system
-2. **Logged into Doubao** (https://www.doubao.com/chat/) in your Chrome browser at least once
+```bash
+npm install yiyan-browser-agent
+```
 
-The package uses your Chrome profile to maintain login state, so you need to login manually first.
+Chromium will be automatically downloaded after installation.
 
-## Installation
+### Ubuntu Additional Step
 
 ```bash
-npm install doubao-browser-agent
+npx playwright install-deps chromium
 ```
 
-## Node.js API Usage
+This installs required system libraries for Chromium on Ubuntu.
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# First time: login to Yiyan
+yiyan-browser-agent login
+
+# Ask a question (headless mode)
+yiyan-browser-agent ask "济宁天气情况"
+
+# With verbose output
+yiyan-browser-agent ask "什么是 TypeScript？" --verbose
+
+# Headful mode (visible browser window)
+yiyan-browser-agent ask "解释 Promise" --headful
+
+# Check login status
+yiyan-browser-agent status
+
+# Clear saved session
+yiyan-browser-agent reset
+
+# Debug mode (output DOM info for troubleshooting)
+yiyan-browser-agent debug
+```
+
+### Node.js API
 
 ```typescript
-import { DoubaoAgent } from 'doubao-browser-agent';
+import { YiyanAgent } from 'yiyan-browser-agent';
 
 // Create agent instance
-const agent = new DoubaoAgent({
+const agent = new YiyanAgent({
   timeout: 120000,    // Timeout in milliseconds (default: 120000)
-  retryCount: 3,      // Retry count (default: 3)
 });
 
-// Send a question and get answer
-try {
-  const answer = await agent.ask('What is TypeScript?');
-  console.log('Answer:', answer);
-} catch (error) {
-  console.error('Error:', error.message);
-}
+// Login first time
+await agent.login();
+
+// Ask a question
+const answer = await agent.ask('What is TypeScript?');
+console.log('Answer:', answer);
+
+// Headful mode (visible browser)
+const answer2 = await agent.ask('Explain Promise', true);
 
 // Check login status
 const status = agent.status();
 console.log('Logged in:', status.loggedIn);
-console.log('Profile path:', status.profilePath);
+console.log('Session path:', status.sessionPath);
 
-// Clear saved profile (if needed)
+// Clear saved session
 await agent.reset();
-```
-
-## CLI Usage
 
-```bash
-# Send a question
-doubao-agent ask "What is TypeScript?"
+// Debug mode (for troubleshooting selectors)
+await agent.debug();
+```
 
-# With options
-doubao-agent ask "Explain Promise" --timeout 60000 --retry 5
+## CLI Commands
 
-# Check login status
-doubao-agent status
+| Command | Description |
+|---------|-------------|
+| `login` | Open browser for manual login (required first time) |
+| `ask "question"` | Send question and get answer |
+| `status` | Check login status |
+| `reset` | Clear saved session |
+| `debug` | Debug mode: output DOM info for troubleshooting |
 
-# Clear saved profile
-doubao-agent reset
+## CLI Options
 
-# Show help
-doubao-agent --help
-```
+| Option | Description |
+|--------|-------------|
+| `--timeout <ms>` | Timeout in milliseconds (default: 120000) |
+| `--headful` | Show browser window (for debugging/captcha) |
+| `--verbose` | Show detailed logs |
+| `--help` | Show help message |
 
 ## API Documentation
 
-### `DoubaoAgent`
+### `YiyanAgent`
 
-Main class for interacting with Doubao.
+Main class for interacting with Yiyan.
 
 #### Constructor
 
 ```typescript
-new DoubaoAgent(options?: DoubaoAgentOptions)
+new YiyanAgent(options?: YiyanAgentOptions)
 ```
 
 **Options:**
 - `timeout?: number` - Timeout in milliseconds (default: 120000)
-- `retryCount?: number` - Number of retry attempts (default: 3)
-- `profileDir?: string` - Custom directory for storing Chrome profile copy
-- `chromePath?: string` - Custom Chrome executable path
+- `profileDir?: string` - Custom session directory
+- `verbose?: boolean` - Enable verbose logging (default: false)
 
 #### Methods
 
-##### `ask(question: string): Promise<string>`
+##### `login(): Promise<void>`
+
+Open browser window for manual login. Login state is saved automatically.
 
-Send a question to Doubao and return the answer.
+##### `ask(question: string, headful?: boolean): Promise<string>`
 
-##### `status(): { loggedIn: boolean; profilePath: string }`
+Send question and return answer.
+- `headful: false` (default) - Headless mode
+- `headful: true` - Visible browser window
 
-Check the login status (whether profile exists).
+##### `status(): { loggedIn: boolean; sessionPath: string }`
+
+Check login status.
 
 ##### `reset(): Promise<void>`
 
-Clear the saved profile copy.
+Clear saved session.
 
-### Error Types
+##### `debug(): Promise<void>`
 
-The package throws `DoubaoAgentError` with the following error types:
+Start browser in debug mode, output DOM information for troubleshooting selectors.
+
+### Error Types
 
 | Type | Description |
 |------|-------------|
-| `BROWSER_LAUNCH` | Failed to launch Chrome browser |
-| `PROFILE_COPY` | Failed to copy Chrome profile |
+| `BROWSER_LAUNCH` | Failed to launch Chromium |
 | `TIMEOUT` | Timeout while waiting for response |
 | `NETWORK` | Network or connection error |
-
-```typescript
-import { DoubaoAgentError } from 'doubao-browser-agent';
-
-try {
-  const answer = await agent.ask('Hello');
-} catch (error) {
-  if (error instanceof DoubaoAgentError) {
-    console.log('Error type:', error.type);
-    console.log('Error message:', error.message);
-  }
-}
-```
+| `CAPTCHA` | Captcha detected (use --headful) |
 
 ## How It Works
 
-1. On first run, the package copies your Chrome profile to a temporary directory
-2. Launches Chrome in headless mode with the copied profile
-3. Navigates to Doubao chat page
-4. Sends your question and waits for response
-5. Extracts the response and closes the browser
+1. Uses Playwright's built-in Chromium (auto-download)
+2. Launches browser with persistent session context
+3. Navigates to Yiyan chat page
+4. Sends question and waits for response
+5. Extracts response using multiple strategies
+6. Closes browser (session saved for next use)
+
+## Session Storage
+
+Session data is stored in:
+- Windows: `C:\Users\<user>\.yiyan-browser-agent\session`
+- Linux/macOS: `~/.yiyan-browser-agent/session`
 
 ## Supported Platforms
 
-- Windows (Chrome paths: `C:/Program Files/Google/Chrome/Application/chrome.exe`)
-- macOS (Chrome paths: `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`)
-- Linux (Chrome paths: `/usr/bin/google-chrome`, `/usr/bin/chrome`)
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Windows | ✅ | Direct use |
+| Ubuntu | ✅ | Run `npx playwright install-deps chromium` first |
+| macOS | ✅ | Direct use |
+
+## Troubleshooting
+
+### Ubuntu: Browser doesn't start
+
+```bash
+npx playwright install chromium
+npx playwright install-deps chromium
+yiyan-browser-agent login --verbose
+```
+
+### Timeout in headless mode
+
+```bash
+# Use headful mode to see what's happening
+yiyan-browser-agent ask "question" --headful --verbose
+```
+
+### Captcha detected
+
+```bash
+# Use headful mode to manually solve captcha
+yiyan-browser-agent ask "question" --headful
+```
+
+### Selectors not working
+
+```bash
+# Use debug mode to see DOM structure
+yiyan-browser-agent debug
+```
+
+## Comparison with deepseek-browser-agent
+
+This package follows similar architecture to [deepseek-browser-agent](https://github.com/Omar-Azam/deepseek-browser-agent):
+
+| Feature | yiyan-browser-agent | deepseek-browser-agent |
+|---------|---------------------|------------------------|
+| Browser | Playwright Chromium | Playwright Chromium |
+| Login | Persistent session | Persistent session |
+| Platform | Win/Ubuntu/macOS | Linux |
 
 ## License
 
-MIT
+MIT
+
+## Repository
+
+https://github.com/picha/yiyan-browser-agent

package/dist/cli.d.ts

@@ -4,7 +4,7 @@ import { C as CliOutput } from './types-BhQ78DYf.js';
 declare function printHelp(): void;
 /** 解析后的 CLI 参数 */
 interface ParsedArgs {
-    command: 'ask' | 'status' | 'reset' | 'login' | 'help' | null;
+    command: 'ask' | 'status' | 'reset' | 'login' | 'debug' | 'help' | null;
     question?: string;
     timeout?: number;
     headful?: boolean;