yiyan-browser-agent 1.0.0 → 1.0.2

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,145 +1,316 @@
-# doubao-browser-agent
+<div align="center">
 
-NPM package for interacting with Doubao (豆包) web version via Playwright.
+<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 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
+**An autonomous AI coding agent that runs entirely for free — no API key required.**
 
-## Prerequisites
+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.
 
-1. **Chrome browser** installed on your system
-2. **Logged into Doubao** (https://www.doubao.com/chat/) in your Chrome browser at least once
+[Installation](#-installation) · [Quick Start](#-quick-start) · [Usage](#-usage) · [Configuration](#-configuration) · [Tools](#-available-tools) · [Contributing](#-contributing)
 
-The package uses your Chrome profile to maintain login state, so you need to login manually first.
+---
 
-## Installation
+> ⚠️ **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).
+
+</div>
+
+---
+
+## 🧠 How It Works
+
+Most AI coding agents talk to a paid API. This one doesn't.
+
+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.
+
+```
+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
+```
+
+---
+
+## 📦 Installation
 
 ```bash
-npm install doubao-browser-agent
+npm install -g yiyan-browser-agent
 ```
 
-## Node.js API Usage
+> Chromium downloads automatically after install (~150 MB, one time only).
 
-```typescript
-import { DoubaoAgent } from 'doubao-browser-agent';
+**Requirements:** Node.js ≥ 18
 
-// Create agent instance
-const agent = new DoubaoAgent({
-  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);
-}
+## 🚀 Quick Start
+
+**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.
+
+**2. Give it a task:**
+```bash
+yiyan-agent "build a REST API in Express with user authentication"
+```
+
+**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('Profile path:', status.profilePath);
+## 💻 Usage
 
-// Clear saved profile (if needed)
-await agent.reset();
+```
+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 Usage
+### Examples
 
 ```bash
-# Send a question
-doubao-agent ask "What is TypeScript?"
+# Single task — runs and exits
+yiyan-agent "create a Python script that scrapes Hacker News"
+
+# Interactive mode — keeps browser open between tasks
+yiyan-agent --interactive
 
-# With options
-doubao-agent ask "Explain Promise" --timeout 60000 --retry 5
+# Run on a specific project
+ya --dir ~/projects/my-app "refactor all callbacks to async/await"
 
-# Check login status
-doubao-agent status
+# Debug mode (shows what Yiyan is actually outputting)
+ya --debug "build a calculator"
 
-# Clear saved profile
-doubao-agent reset
+# Headless mode (faster — browser runs in background)
+ya --headless "write unit tests for utils.js"
 
-# Show help
-doubao-agent --help
+# In interactive mode, type 'new' to start a fresh chat:
+❯ Task: new
+```
+
+---
+
+## ⚙️ Configuration
+
+### Global config — applies everywhere
+
+Create `~/.yiyan-agent/config.json`:
+
+```json
+{
+  "HEADLESS": true,
+  "MAX_ITERATIONS": 50,
+  "STABLE_DELAY": 3000,
+  "DEBUG": false
+}
 ```
 
-## API Documentation
+### Per-project config — overrides global
 
-### `DoubaoAgent`
+Drop `yiyan-agent.config.json` in your project root:
 
-Main class for interacting with Doubao.
+```json
+{
+  "MAX_ITERATIONS": 60,
+  "MAX_OUTPUT_LENGTH": 12000
+}
+```
 
-#### Constructor
+### 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:
 
-```typescript
-new DoubaoAgent(options?: DoubaoAgentOptions)
+```
+~/.yiyan-agent/
+├── session/        ← Browser cookies (login once, runs forever)
+├── logs/           ← Session logs (only saved with --save-log)
+└── config.json     ← Your global settings
 ```
 
-**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
+---
 
-#### Methods
+## 🔧 Troubleshooting
 
-##### `ask(question: string): Promise<string>`
+### 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"
+```
 
-Send a question to Doubao and return the answer.
+### 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
+```
 
-##### `status(): { loggedIn: boolean; profilePath: string }`
+### Login session expired
+Just run without `--headless` — the browser opens and you log in again:
+```bash
+yiyan-agent --interactive
+```
 
-Check the login status (whether profile exists).
+### Chromium didn't download automatically
+```bash
+npx playwright install chromium
+```
 
-##### `reset(): Promise<void>`
+### Response times out on long tasks
+Increase the timeout in your config:
+```json
+{ "RESPONSE_TIMEOUT": 300000, "STABLE_DELAY": 4000 }
+```
 
-Clear the saved profile copy.
+---
 
-### Error Types
+## 🗂️ Project Structure
 
-The package throws `DoubaoAgentError` with the following error types:
+```
+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
+```
 
-| Type | Description |
-|------|-------------|
-| `BROWSER_LAUNCH` | Failed to launch Chrome browser |
-| `PROFILE_COPY` | Failed to copy Chrome profile |
-| `TIMEOUT` | Timeout while waiting for response |
-| `NETWORK` | Network or connection error |
+---
 
-```typescript
-import { DoubaoAgentError } from 'doubao-browser-agent';
+## 🤝 Contributing
 
-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);
-  }
-}
+Contributions are very welcome — this project is in active development and there's plenty of room to grow.
+
+### Setting up locally
+
+```bash
+git clone https://github.com/YOUR_USERNAME/yiyan-browser-agent
+cd yiyan-browser-agent
+npm install
+npx playwright install chromium
+node src/index.js --interactive
 ```
 
-## How It Works
+### Areas that need work
+
+- 🧪 **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
+
+### How to contribute
+
+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
+
+Please keep PRs focused — one feature or fix per PR makes review much faster.
+
+### 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.
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](./LICENSE) for details.
 
-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
+---
 
-## Supported Platforms
+<div align="center">
 
-- 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`)
+**Built with Playwright · Powered by Yiyan (文心一言) · Free forever**
 
-## License
+If this project helped you, consider giving it a ⭐ on GitHub!
 
-MIT
+</div>

package/package.json

@@ -1,47 +1,45 @@
 {
   "name": "yiyan-browser-agent",
-  "version": "1.0.0",
-  "description": "NPM package for interacting with Yiyan (文心一言) web version via Playwright",
-  "type": "module",
+  "version": "1.0.2",
+  "description": "AI coding agent powered by Yiyan (文心一言) via browser automation — no API key needed",
+  "main": "src/index.js",
   "bin": {
-    "yiyan-agent": "./dist/cli.js"
+    "yiyan-agent": "src/index.js",
+    "ya": "src/index.js"
   },
-  "main": "./dist/index.js",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
+  "scripts": {
+    "start": "node src/index.js",
+    "postinstall": "node src/postinstall.js",
+    "debug": "node src/index.js --debug",
+    "calibrate": "node src/calibrate.js"
   },
   "files": [
-    "dist",
+    "src/",
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build && npm run test"
-  },
   "dependencies": {
-    "playwright-core": "^1.40.0"
+    "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": ["yiyan", "文心一言", "baidu", "playwright", "browser", "agent", "ai", "chatbot"],
+  "keywords": [
+    "ai",
+    "agent",
+    "yiyan",
+    "wenxin",
+    "baidu",
+    "browser-automation",
+    "coding-agent",
+    "cli",
+    "llm"
+  ],
+  "author": "",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/picha/yiyan-browser-agent"
-  },
-  "bugs": {
-    "url": "https://github.com/picha/yiyan-browser-agent/issues"
+    "url": "https://github.com/YOUR_USERNAME/yiyan-browser-agent"
   },
-  "homepage": "https://github.com/picha/yiyan-browser-agent#readme"
+  "homepage": "https://github.com/YOUR_USERNAME/yiyan-browser-agent#readme"
 }