feat: init
This commit is contained in:
Simon
214
.github/copilot-instructions.md
vendored
Normal file
214
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,214 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user