215 lines
7.6 KiB
Markdown
215 lines
7.6 KiB
Markdown
# page-agent AI Coding Instructions
|
|
|
|
## Project Overview
|
|
|
|
This project has **TWO SEPARATE PARTS**:
|
|
|
|
1. **Core Library** (`src/`) - Pure JavaScript AI agent library that can be injected into any webpage
|
|
2. **Marketing Website** (`pages/`) - React web app for landing page and documentation
|
|
|
|
## Architecture & Tech Stack
|
|
|
|
### Core Library (`src/`) - Pure JavaScript AI Agent
|
|
|
|
- **Technology**: Vanilla JavaScript/TypeScript (no React dependency)
|
|
- **Purpose**: AI agent with DOM automation capabilities
|
|
- **Output**: UMD/ES modules via `vite.lib.config.ts`
|
|
- **Key Features**: DOM processing, LLM integration, type-safe event bus
|
|
|
|
### Marketing Website (`pages/`) - React Web App
|
|
|
|
- **Technology**: React 19 + TypeScript + Wouter routing + Tailwind CSS v4
|
|
- **Purpose**: Landing page and documentation site
|
|
- **Output**: Static website via `vite.config.ts`
|
|
- **Usage**: Hosted documentation and demos
|
|
|
|
## Critical Development Workflows
|
|
|
|
### Dual Build System - Two Separate Projects
|
|
|
|
```bash
|
|
npm start # React website (pages/) development
|
|
npm run build # Build BOTH library AND website
|
|
npm run build:lib # Pure JS library only (src/ → dist/lib/)
|
|
npm run build:lib:watch # Library development with auto-rebuild
|
|
```
|
|
|
|
### Library Development (Pure JavaScript)
|
|
|
|
**Working on the core AI agent (`src/`):**
|
|
|
|
1. Edit pure JavaScript/TypeScript files in `src/`
|
|
2. Use `npm run build:lib:watch` for development
|
|
3. Test via CDN injection: `<script src="dist/lib/page-agent.umd.js"></script>`
|
|
4. No React dependencies allowed in `src/`
|
|
|
|
### Website Development (React)
|
|
|
|
**Working on marketing/docs (`pages/`):**
|
|
|
|
1. Use `npm start` for React development server
|
|
2. Can import from `src/` via `@/` alias to demo library features
|
|
3. Create test pages in `pages/test-pages/` to validate library integration
|
|
|
|
### DOM Pipeline
|
|
|
|
1. **DOM Extraction**: `src/dom/` converts live DOM to `FlatDomTree`
|
|
2. **Dehydration**: DOM tree → simplified text representation for LLM
|
|
3. **LLM Processing**: Send text to AI model for action planning
|
|
4. **Indexed Operations**: Map LLM responses back to specific DOM elements via indices
|
|
|
|
### Event Bus Communication
|
|
|
|
Use `src/utils/bus.ts` instead of prop drilling for PageAgent ↔ UI communication:
|
|
|
|
```typescript
|
|
// Emit events from PageAgent
|
|
getEventBus().emit('panel:show', undefined)
|
|
getEventBus().emit('panel:update', { status: 'thinking', message: 'Processing...' })
|
|
|
|
// Listen in UI components
|
|
getEventBus().on('panel:show', () => panel.show())
|
|
```
|
|
|
|
## Key Patterns & Conventions
|
|
|
|
### Strict Module Boundaries
|
|
|
|
- **Core library** (`src/`): Never import from `pages/` - must remain pure JavaScript
|
|
- **React website** (`pages/`): Can import from `src/` via `@/` alias to demo features
|
|
- **Entry points**: `src/entry.ts` (CDN/UMD), `pages/main.tsx` (React website)
|
|
|
|
### Manual Route Registration Pattern
|
|
|
|
Routes in `pages/router.tsx` require explicit definition:
|
|
|
|
```tsx
|
|
<Route path="/docs/features/dom-operations">
|
|
<div className="min-h-screen bg-white dark:bg-gray-900">
|
|
<Header />
|
|
<DocsLayout>
|
|
<DomOperations />
|
|
</DocsLayout>
|
|
</div>
|
|
</Route>
|
|
```
|
|
|
|
**Adding new docs pages**: 1) Add route to `router.tsx`, 2) Add nav item to `DocsLayout.tsx`
|
|
|
|
### Hash Routing Requirement
|
|
|
|
Uses wouter with `useHashLocation` for static hosting compatibility:
|
|
|
|
```tsx
|
|
<Router hook={useHashLocation}> // Always hash-based routes
|
|
```
|
|
|
|
### CDN Auto-Injection Pattern
|
|
|
|
Library auto-initializes when injected via script tag:
|
|
|
|
```html
|
|
<script src="page-agent.js?model=gpt-4"></script>
|
|
```
|
|
|
|
Query params configure `PageAgentConfig` automatically.
|
|
|
|
### CSS & Design System
|
|
|
|
- **Prefer Tailwind CSS over custom CSS** - Use utility classes for styling
|
|
- Custom CSS variables in `src/index.css` define theme gradients:
|
|
```css
|
|
--theme-color-1: rgb(88, 192, 252);
|
|
--theme-color-2: rgb(189, 69, 251);
|
|
```
|
|
- Design follows modern SaaS aesthetic with blue/purple gradients
|
|
- **Accessibility**: Ensure proper contrast ratios, semantic HTML, ARIA labels
|
|
- Dark mode support throughout via Tailwind `dark:` classes
|
|
- Responsive grid layouts for features and content sections
|
|
|
|
## File Organization
|
|
|
|
### Core Library (`src/`)
|
|
|
|
- **PageAgent.ts**: Core agent implementation and public API
|
|
- **entry.ts**: Library entry point for CDN/UMD usage
|
|
- **config/**: Configuration constants and settings management
|
|
- **tools/**: Agent tool implementations for web actions and page manipulation
|
|
- **ui/**: User interface components (Panel, SimulatorMask, etc.) for agent visualization
|
|
- **llms/**: LLM integration and communication layer
|
|
- **dom/**: HTML serialization, page analysis utilities, and DOM manipulation helpers
|
|
- **utils/**: Shared utilities including the type-safe event bus system
|
|
- **patches/**: Framework-specific optimizations and compatibility fixes (React, Antd, etc.)
|
|
- **prompts/**: System prompts and LLM instruction templates
|
|
- **i18n/**: Internationalization and language support
|
|
|
|
### Documentation Site (`pages/`)
|
|
|
|
- `main.tsx` - Site entry point with hash routing setup
|
|
- `router.tsx` - Manual route definitions (requires explicit registration)
|
|
- `components/DocsLayout.tsx` - Navigation structure (hardcoded nav items)
|
|
- `docs/[section]/[topic]/page.tsx` - Documentation pages
|
|
- `test-pages/` - Library integration test pages
|
|
|
|
## Development Workflow
|
|
|
|
### Commands
|
|
|
|
- `npm start` - Development server (Vite)
|
|
- `npm run build` - Production build (TypeScript check + Vite build)
|
|
- `npm run lint` - ESLint with strict TypeScript rules
|
|
|
|
### Debugging Routing Issues
|
|
|
|
**Common problem**: Blank pages in docs sections. Debug steps:
|
|
|
|
1. Verify route exists in `pages/router.tsx`
|
|
2. Check component import path
|
|
3. Test with minimal component first
|
|
4. Verify CSS isn't hiding content (check dark mode classes)
|
|
|
|
### TypeScript Configuration
|
|
|
|
- Strict mode enabled with `noUnusedLocals` and `noUnusedParameters`
|
|
- Path alias `@/*` maps to `src/*`
|
|
- ESLint uses strict TypeScript rules but disables some for pragmatism:
|
|
```js
|
|
'@typescript-eslint/no-non-null-assertion': 'off'
|
|
'@typescript-eslint/no-unsafe-assignment': 'off'
|
|
```
|
|
|
|
## Content & Messaging
|
|
|
|
- **Tone**: Technical but approachable, targeting web developers
|
|
- **Core value prop**: "一行 CDN 引入，为任何网站添加智能 UI Agent"
|
|
- **Differentiator**: Page-embedded vs external automation (vs browser-use)
|
|
- Feature categories: DOM operations, security, data masking, knowledge injection, model integration
|
|
|
|
## Code Quality Standards
|
|
|
|
- Use TypeScript strict mode
|
|
- Prefer functional components with hooks
|
|
- **Prefer Tailwind CSS over custom CSS** - Use utility classes for styling
|
|
- Consistent file naming: kebab-case for multi-word files
|
|
- Import organization: React imports first, then components, then styles
|
|
|
|
## Critical Files to Understand
|
|
|
|
- `pages/router.tsx` - Central routing definition
|
|
- `pages/components/DocsLayout.tsx` - Navigation structure
|
|
- `pages/page.tsx` - Homepage showcasing product features
|
|
- `src/PageAgent.ts` - **Core library**: AI agent class with DOM manipulation
|
|
- `src/dom/dom_tree/index.js` - **DOM extraction engine** (ported from Python)
|
|
- `src/utils/bus.ts` - **Type-safe event bus** for decoupled communication
|
|
- `src/entry.ts` - CDN/UMD entry point with auto-initialization
|
|
- `vite.config.ts` and `vite.lib.config.ts` - Dual build configuration
|
|
- `tsconfig.app.json` - TypeScript strictness settings
|
|
|
|
## Core Library Architecture
|
|
|
|
The core library (`src/`) is a standalone AI agent with these key components:
|
|
|
|
- **PageAgent.ts**: Main agent class managing DOM tree updates, element highlighting, and LLM communication
|
|
- **DOM processing pipeline**: Converts complex web pages into LLM-friendly text while preserving interactive element mappings for precise actions
|
|
- **Event bus system**: Type-safe communication between PageAgent and UI components
|