yiyan-browser-agent 1.4.5 → 1.4.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 doubao-browser-agent contributors
+Copyright (c) 2026 Omar Azam
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,228 +1,316 @@
-# yiyan-browser-agent
+<div align="center">
 
-NPM package for interacting with Yiyan (文心一言) web version via Playwright. No API key required.
+<img src="https://img.shields.io/badge/status-in%20development-orange?style=for-the-badge" alt="Status: In Development"/>
+<img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=for-the-badge" alt="Node.js"/>
+<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License"/>
+<img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge" alt="PRs Welcome"/>
 
-## Features
+# 🤖 Yiyan Browser Agent (文心一言)
 
-- 🤖 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
+**An autonomous AI coding agent that runs entirely for free — no API key required.**
 
-## Installation
+It drives a real browser to talk to [Yiyan (文心一言)](https://yiyan.baidu.com), giving you a Claude Code / Cursor-style coding agent powered by Baidu's AI models at zero cost.
 
-```bash
-npm install yiyan-browser-agent
-```
-
-Chromium will be automatically downloaded after installation.
+[Installation](#-installation) · [Quick Start](#-quick-start) · [Usage](#-usage) · [Configuration](#-configuration) · [Tools](#-available-tools) · [Contributing](#-contributing)
 
-### Ubuntu Additional Step
-
-```bash
-npx playwright install-deps chromium
-```
+---
 
-This installs required system libraries for Chromium on Ubuntu.
+> ⚠️ **This project is currently in active development.**
+> Core functionality works, but you may encounter rough edges. Bug reports and contributions are very welcome — see [Contributing](#-contributing).
 
-## Quick Start
+</div>
 
-### CLI Usage
+---
 
-```bash
-# First time: login to Yiyan
-yiyan-browser-agent login
+## 🧠 How It Works
 
-# Ask a question (headless mode)
-yiyan-browser-agent ask "济宁天气情况"
+Most AI coding agents talk to a paid API. This one doesn't.
 
-# With verbose output
-yiyan-browser-agent ask "什么是 TypeScript？" --verbose
+Instead, it uses **Playwright** to control a real Chromium browser, navigates to `yiyan.baidu.com`, sends your task, waits for the response, and parses it to extract tool calls — all automatically. Your local files and terminal are wired up as tools the AI can use, so it can read code, write files, run commands, and and build complete projects step by step.
 
-# Headful mode (visible browser window)
-yiyan-browser-agent ask "解释 Promise" --headful
+```
+Your Terminal
+     │
+     ▼
+ Agent Core          ← orchestrates the loop
+     │
+     ├──► Browser (Playwright)  ← talks to yiyan.baidu.com
+     │         │
+     │    Yiyan AI (文心一言)  ← thinks, decides what tool to use
+     │         │
+     └──► Tool Executor  ← reads/writes files, runs commands
+              │
+         Your Project
+```
 
-# Check login status
-yiyan-browser-agent status
+---
 
-# Clear saved session
-yiyan-browser-agent reset
+## 📦 Installation
 
-# Debug mode (output DOM info for troubleshooting)
-yiyan-browser-agent debug
+```bash
+npm install -g yiyan-browser-agent
 ```
 
-### Node.js API
+> Chromium downloads automatically after install (~150 MB, one time only).
+
+**Requirements:** Node.js ≥ 18
 
-```typescript
-import { YiyanAgent } from 'yiyan-browser-agent';
+---
 
-// Create agent instance
-const agent = new YiyanAgent({
-  timeout: 120000,    // Timeout in milliseconds (default: 120000)
-});
+## 🚀 Quick Start
 
-// Login first time
-await agent.login();
+**1. First run — log in to Yiyan:**
+```bash
+yiyan-agent --interactive
+```
+A browser window opens. Log in to your Yiyan (文心一言) account, then come back to the terminal and press **Enter**. Your session is saved — you only do this once.
 
-// Ask a question
-const answer = await agent.ask('What is TypeScript?');
-console.log('Answer:', answer);
+**2. Give it a task:**
+```bash
+yiyan-agent "build a REST API in Express with user authentication"
+```
 
-// Headful mode (visible browser)
-const answer2 = await agent.ask('Explain Promise', true);
+**3. Use the short alias `ya` from any project folder:**
+```bash
+cd ~/my-project
+ya "add input validation to all my API routes"
+```
 
-// Check login status
-const status = agent.status();
-console.log('Logged in:', status.loggedIn);
-console.log('Session path:', status.sessionPath);
+---
 
-// Clear saved session
-await agent.reset();
+## 💻 Usage
 
-// Debug mode (for troubleshooting selectors)
-await agent.debug();
+```
+yiyan-agent [OPTIONS] [TASK]
+
+  -t, --task <task>    Task to run (or just type it as the last argument)
+  -i, --interactive    Keep browser open, run multiple tasks in a session
+  -d, --dir <path>     Set working directory (default: current directory)
+  --debug              Print raw AI responses to the terminal
+  --headless           Run browser invisibly (requires prior login)
+  --save-log           Save full session log to ~/.yiyan-agent/logs/
+  --calibrate          Auto-detect DOM selectors (run if agent breaks)
+  -h, --help           Show help
+
+Aliases:
+  ya                   Short form of yiyan-agent
 ```
 
-## CLI Commands
+### Examples
 
-| 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 |
+```bash
+# Single task — runs and exits
+yiyan-agent "create a Python script that scrapes Hacker News"
 
-## CLI Options
+# Interactive mode — keeps browser open between tasks
+yiyan-agent --interactive
 
-| Option | Description |
-|--------|-------------|
-| `--timeout <ms>` | Timeout in milliseconds (default: 120000) |
-| `--headful` | Show browser window (for debugging/captcha) |
-| `--verbose` | Show detailed logs |
-| `--help` | Show help message |
+# Run on a specific project
+ya --dir ~/projects/my-app "refactor all callbacks to async/await"
 
-## API Documentation
+# Debug mode (shows what Yiyan is actually outputting)
+ya --debug "build a calculator"
 
-### `YiyanAgent`
+# Headless mode (faster — browser runs in background)
+ya --headless "write unit tests for utils.js"
 
-Main class for interacting with Yiyan.
+# In interactive mode, type 'new' to start a fresh chat:
+❯ Task: new
+```
 
-#### Constructor
+---
 
-```typescript
-new YiyanAgent(options?: YiyanAgentOptions)
-```
+## ⚙️ Configuration
 
-**Options:**
-- `timeout?: number` - Timeout in milliseconds (default: 120000)
-- `profileDir?: string` - Custom session directory
-- `verbose?: boolean` - Enable verbose logging (default: false)
+### Global config — applies everywhere
 
-#### Methods
+Create `~/.yiyan-agent/config.json`:
 
-##### `login(): Promise<void>`
+```json
+{
+  "HEADLESS": true,
+  "MAX_ITERATIONS": 50,
+  "STABLE_DELAY": 3000,
+  "DEBUG": false
+}
+```
 
-Open browser window for manual login. Login state is saved automatically.
+### Per-project config — overrides global
 
-##### `ask(question: string, headful?: boolean): Promise<string>`
+Drop `yiyan-agent.config.json` in your project root:
 
-Send question and return answer.
-- `headful: false` (default) - Headless mode
-- `headful: true` - Visible browser window
+```json
+{
+  "MAX_ITERATIONS": 60,
+  "MAX_OUTPUT_LENGTH": 12000
+}
+```
 
-##### `status(): { loggedIn: boolean; sessionPath: string }`
+### All settings
+
+| Setting | Default | Description |
+|---|---|---|
+| `HEADLESS` | `false` | Hide the browser window |
+| `MAX_ITERATIONS` | `40` | Max agent steps per task before stopping |
+| `RESPONSE_TIMEOUT` | `180000` | Max ms to wait for a response (3 min) |
+| `STABLE_DELAY` | `2500` | Ms of silence that means Yiyan is done |
+| `SEND_DELAY` | `400` | Ms between typing and pressing Enter |
+| `MAX_OUTPUT_LENGTH` | `8000` | Truncate long command outputs sent to AI |
+| `DEBUG` | `false` | Print raw AI responses to terminal |
+| `SESSION_DIR` | `~/.yiyan-agent/session` | Where browser cookies are saved |
+
+---
+
+## 🛠️ Available Tools
+
+The agent can use these tools autonomously to complete your task:
+
+| Tool | Description |
+|---|---|
+| `read_file` | Read a file's contents, optionally by line range |
+| `write_file` | Create or overwrite a file (auto-creates directories) |
+| `append_to_file` | Append text to an existing file |
+| `replace_in_file` | Find and replace text in a file (regex supported) |
+| `delete_file` | Permanently delete a file |
+| `list_directory` | List directory contents, optionally recursive |
+| `create_directory` | Create a directory and all parents |
+| `move_file` | Move or rename a file or directory |
+| `copy_file` | Copy a file to a new location |
+| `get_file_info` | Get file metadata (size, line count, dates) |
+| `run_command` | Execute any shell command |
+| `find_files` | Find files by name pattern (e.g. `*.ts`) |
+| `search_in_files` | Search text inside files (like `grep -r`) |
+| `read_url` | Fetch and read the content of a URL |
+| `write_files` | Write multiple files at once (batch scaffold) |
+
+---
+
+## 📂 Where Data is Stored
+
+Everything lives in `~/.yiyan-agent/` in your home directory:
 
-Check login status.
+```
+~/.yiyan-agent/
+├── session/        ← Browser cookies (login once, runs forever)
+├── logs/           ← Session logs (only saved with --save-log)
+└── config.json     ← Your global settings
+```
 
-##### `reset(): Promise<void>`
+---
 
-Clear saved session.
+## 🔧 Troubleshooting
 
-##### `debug(): Promise<void>`
+### Agent responds but creates no files
+The browser DOM rendered the AI's response in a way the parser didn't catch. Run with `--debug` to see exactly what's being received:
+```bash
+yiyan-agent --debug "build a calculator"
+```
 
-Start browser in debug mode, output DOM information for troubleshooting selectors.
+### Agent stops responding / loops
+Yiyan's UI may have changed. Run the calibration tool — it inspects the live DOM and prints updated selectors:
+```bash
+yiyan-agent --calibrate
+```
 
-### Error Types
+### Login session expired
+Just run without `--headless` — the browser opens and you log in again:
+```bash
+yiyan-agent --interactive
+```
 
-| Type | Description |
-|------|-------------|
-| `BROWSER_LAUNCH` | Failed to launch Chromium |
-| `TIMEOUT` | Timeout while waiting for response |
-| `NETWORK` | Network or connection error |
-| `CAPTCHA` | Captcha detected (use --headful) |
+### Chromium didn't download automatically
+```bash
+npx playwright install chromium
+```
 
-## How It Works
+### Response times out on long tasks
+Increase the timeout in your config:
+```json
+{ "RESPONSE_TIMEOUT": 300000, "STABLE_DELAY": 4000 }
+```
 
-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
+## 🗂️ Project Structure
 
-Session data is stored in:
-- Windows: `C:\Users\<user>\.yiyan-browser-agent\session`
-- Linux/macOS: `~/.yiyan-browser-agent/session`
+```
+yiyan-browser-agent/
+├── src/
+│   ├── index.js          ← CLI entry point and argument parsing
+│   ├── agent.js          ← Core agent loop (send → wait → parse → execute)
+│   ├── browser.js        ← Playwright controller for yiyan.baidu.com
+│   ├── tools.js          ← All 15 filesystem and shell tools
+│   ├── parser.js         ← Extracts tool calls from AI responses (6 strategies)
+│   ├── prompt.js         ← System prompt and conversation history manager
+│   ├── config.js         ← Configuration loader (global + per-project)
+│   ├── logger.js         ← ANSI-colored terminal output
+│   ├── calibrate.js      ← DOM selector inspector / auto-fix tool
+│   └── postinstall.js    ← Auto-downloads Chromium after npm install
+├── LICENSE
+├── README.md
+└── package.json
+```
 
-## Supported Platforms
+---
 
-| Platform | Status | Notes |
-|----------|--------|-------|
-| Windows | ✅ | Direct use |
-| Ubuntu | ✅ | Run `npx playwright install-deps chromium` first |
-| macOS | ✅ | Direct use |
+## 🤝 Contributing
 
-## Troubleshooting
+Contributions are very welcome — this project is in active development and there's plenty of room to grow.
 
-### Ubuntu: Browser doesn't start
+### Setting up locally
 
 ```bash
+git clone https://github.com/YOUR_USERNAME/yiyan-browser-agent
+cd yiyan-browser-agent
+npm install
 npx playwright install chromium
-npx playwright install-deps chromium
-yiyan-browser-agent login --verbose
+node src/index.js --interactive
 ```
 
-### Timeout in headless mode
+### Areas that need work
 
-```bash
-# Use headful mode to see what's happening
-yiyan-browser-agent ask "question" --headful --verbose
-```
+- 🧪 **Tests** — there are currently no automated tests; a test suite would be a great contribution
+- 🎨 **UI selector resilience** — Yiyan updates their UI occasionally; better selector strategies are welcome
+- 🔌 **More tools** — image generation, browser control, database tools, etc.
+- 🌐 **Other AI frontends** — adapting the browser layer to work with other free AI chats
+- 📦 **Windows support** — currently tested on Linux; Windows path handling may need fixes
+- 📝 **Better error messages** — making failures easier to diagnose
 
-### Captcha detected
+### How to contribute
 
-```bash
-# Use headful mode to manually solve captcha
-yiyan-browser-agent ask "question" --headful
-```
+1. Fork the repo
+2. Create a branch: `git checkout -b feature/my-improvement`
+3. Make your changes
+4. Open a Pull Request with a clear description
 
-### Selectors not working
+Please keep PRs focused — one feature or fix per PR makes review much faster.
 
-```bash
-# Use debug mode to see DOM structure
-yiyan-browser-agent debug
-```
+### Reporting bugs
+
+Open an issue on GitHub with:
+- What you ran
+- What you expected
+- What actually happened
+- Output of `yiyan-agent --debug "your task"` if relevant
+
+---
+
+## ⚠️ Disclaimer
+
+This project automates a web browser to interact with yiyan.baidu.com. Automating web UIs may violate the terms of service of the website being automated. Use this tool for **personal and development purposes only**. The authors take no responsibility for account suspensions or other consequences of use.
+
+---
 
-## Comparison with deepseek-browser-agent
+## 📄 License
 
-This package follows similar architecture to [deepseek-browser-agent](https://github.com/Omar-Azam/deepseek-browser-agent):
+MIT — see [LICENSE](./LICENSE) for details.
 
-| Feature | yiyan-browser-agent | deepseek-browser-agent |
-|---------|---------------------|------------------------|
-| Browser | Playwright Chromium | Playwright Chromium |
-| Login | Persistent session | Persistent session |
-| Platform | Win/Ubuntu/macOS | Linux |
+---
 
-## License
+<div align="center">
 
-MIT
+**Built with Playwright · Powered by Yiyan (文心一言) · Free forever**
 
-## Repository
+If this project helped you, consider giving it a ⭐ on GitHub!
 
-https://github.com/picha/yiyan-browser-agent
+</div>

package/package.json

@@ -1,50 +1,45 @@
 {
   "name": "yiyan-browser-agent",
-  "version": "1.4.5",
-  "description": "NPM package for interacting with Yiyan (文心一言) web version via Playwright. No API key required.",
+  "version": "1.4.7",
+  "description": "AI coding agent powered by Yiyan (文心一言) via browser automation — no API key needed",
+  "main": "src/index.js",
   "bin": {
-    "yiyan-browser-agent": "./dist/cli.js"
+    "yiyan-agent": "src/index.js",
+    "ya": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "postinstall": "node src/postinstall.js",
+    "debug": "node src/index.js --debug",
+    "calibrate": "node src/calibrate.js"
   },
-  "main": "./dist/index.js",
   "files": [
-    "dist",
+    "src/",
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "postinstall": "node dist/postinstall.js",
-    "prepublishOnly": "npm run build && npm run test"
-  },
   "dependencies": {
     "playwright": "^1.45.0"
   },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "vitest": "^3.2.4",
-    "tsup": "^8.0.0",
-    "@types/node": "^20.0.0"
+  "engines": {
+    "node": ">=18.0.0"
   },
   "keywords": [
+    "ai",
+    "agent",
     "yiyan",
-    "文心一言",
+    "wenxin",
     "baidu",
-    "playwright",
-    "browser",
-    "agent",
-    "ai",
-    "chatbot"
+    "browser-automation",
+    "coding-agent",
+    "cli",
+    "llm"
   ],
+  "author": "readfor",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/picha/yiyan-browser-agent"
-  },
-  "bugs": {
-    "url": "https://github.com/picha/yiyan-browser-agent/issues"
+    "url": "git+https://github.com/readfor/yiyan-browser-agent.git"
   },
-  "homepage": "https://github.com/picha/yiyan-browser-agent#readme"
-}
+  "homepage": "https://github.com/readfor/yiyan-browser-agent#readme"
+}

package/src/agent.js

@@ -0,0 +1,63 @@
+// src/agent.js — Simple agent, one browser per process
+'use strict';
+
+const config     = require('./config');
+const logger     = require('./logger');
+const YiyanBrowser = require('./browser');
+
+class YiyanAgent {
+  constructor(options = {}) {
+    this.browser = new YiyanBrowser();
+    this.options = options;
+  }
+
+  async init() {
+    await this.browser.launch();
+  }
+
+  async shutdown() {
+    await this.browser.close();
+  }
+
+  async run(task) {
+    const startTime = Date.now();
+
+    logger.info('Sending task to Yiyan...');
+    await this.browser.sendMessage(task);
+
+    logger.info('Waiting for response...');
+    const answer = await this.browser.waitForResponse();
+
+    const duration = Date.now() - startTime;
+
+    return {
+      question: task,
+      answer: answer || 'No response',
+      duration,
+      status: answer ? 'success' : 'error'
+    };
+  }
+
+  async runInteractive() {
+    const readline = require('readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = () => new Promise(resolve => rl.question('', resolve));
+
+    while (true) {
+      const task = (await ask()).trim();
+      if (!task) continue;
+      if (['exit', 'quit', 'q'].includes(task.toLowerCase())) break;
+
+      try {
+        await this.browser.newChat();
+        const result = await this.run(task);
+        console.log(JSON.stringify(result, null, 2));
+      } catch (err) {
+        console.log(JSON.stringify({ question: task, answer: `Error: ${err.message}`, duration: 0, status: 'error' }, null, 2));
+      }
+    }
+    rl.close();
+  }
+}
+
+module.exports = YiyanAgent;