Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
213 lines (144 loc) · 5.99 KB

CONTRIBUTING.md

File metadata and controls

213 lines (144 loc) · 5.99 KB
Raw

Contributing to Page-Agent

Thank you for your interest in contributing to Page-Agent! We welcome contributions from everyone.

🚀 Quick Start

Development Setup

  1. Prerequisites

    • node.js >= 20 with npm >= 10
    • An editor that supports ts/eslint/prettier
    • Make sure eslint, prettier and commitlint work well

  2. Setup

    npm ci
npm start          # Start demo and documentation site

Project Structure

This is a monorepo with npm workspaces containing 4 main packages:

  • IXR Agent (packages/ixr-agent/) - Main entry with built-in UI Panel, published as ixr-agent on npm
  • Core (packages/core/) - Core agent logic without UI (npm: @ixr/core)
  • Extension (packages/extension/) - Chrome extension for multi-page tasks and browser-level automation
  • Website (packages/website/) - React documentation and landing page. Also as demo and test page for the core lib. private package @ixr/website

We use a simplified monorepo solution with native npm-workspace + ts reference + vite alias. No fancy tooling. Hoisting is required.

  • When developing. Use alias so that we don't have to pre-build.
  • When bundling. Use external and disable ts paths alias to leave deps out.
  • When bundling IIFE and Website. Bundle everything including local packages.

🤝 How to Contribute

Reporting Issues

  • Use the GitHub issue tracker to report bugs or request features
  • Search existing issues before creating new ones
  • Provide clear reproduction steps for bugs
  • Include browser version and environment details

Code Contributions

  1. Fork and Clone

    git clone https://github.com/your-username/ixr-agent.git
cd ixr-agent

  2. Create Feature Branch

    git checkout -b feat/your-feature-name

  3. Make Changes

    • Follow existing code style and patterns
    • Add tests for new functionality
    • Update documentation as needed

  4. Test Your Changes

    • Test in our demo website
    • Test it on other websites if applicable
    • @TODO: test suite

  5. Commit and Push

    git add .
git commit -m "feat: add awesome feature"
git push origin feat/your-feature-name

  6. Create Pull Request

    • Provide clear description of changes
    • Link related issues
    • Include screenshots for UI changes

📝 Code Style

General Guidelines

  • Use TypeScript for type safety
  • Follow existing naming conventions
  • Write meaningful commit messages
  • Keep functions small and focused
  • Add JSDoc for public APIs

Vibe coding with AI

  • It's recommended to heavily rely on AI (aka "vibe coding") when maintaining demo pages and tests.
  • Be very careful if AI ever touched the core lib!!!
  • Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI.
  • Update the AI instructions when structure changed.

If your lame AI assistant does not support AGENTS.md. Add an alias for it:

  • claude-code (CLAUDE.md)

    @AGENTS.md

  • antigravity (.agent/rules/alias.md)

    ---
trigger: always_on
---

@../../AGENTS.md

🔧 Development Workflows

Test With Your Own LLM API

  • Create a .env file in the repo root with your LLM API config

    LLM_MODEL_NAME=gpt-5.2
LLM_API_KEY=your-api-key
LLM_BASE_URL=https://api.your-llm-provider.com/v1

  • Ollama example (tested on 0.15 + qwen3:14b, RTX3090 24GB):

    LLM_BASE_URL="http://localhost:11434/v1"
LLM_API_KEY="NA"
LLM_MODEL_NAME="qwen3:14b"

    ⚠️ Add * to OLLAMA_ORIGINS (403). Models < 10B unlikely strong enough. Requires tool_call support. Set context length > 15k (default 4k will NOT work): $env:OLLAMA_CONTEXT_LENGTH=64000; ollama serve

  • Restart the dev server to load new env vars

  • If not provided, the demo will the free testing proxy by default

Website Development

npm start

Extension Development

npm run dev -w @ixr/ext
npm run zip -w @ixr/ext
  • Load extension in Chrome via chrome://extensions -> Load unpacked
  • Use packages/extension/docs/extension_api.md (EN) or packages/extension/docs/extension_api_zh.md (ZH) for API integration details

Testing on Other Websites

  • Start and serve a local iife script

    npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/ixr-agent.demo.js

  • Add a new bookmark

    javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/ixr-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log(%27IXRAgent ready!%27);document.head.appendChild(s);})();

  • Click the bookmark on any page to load Page-Agent

Warning: AK in your local .env will be inlined in the iife script.

Adding Documentation

Ask an AI to help you add documentation to the website/ package. Follow the existing style.

Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.

🎯 Contribution Areas

We especially welcome contributions in:

  • Browser compatibility improvements
  • Performance optimizations for DOM processing
  • Documentation and examples
  • Testing and quality assurance
  • Accessibility features
  • Internationalization support

🚫 What We Don't Accept

  • Changes that break existing API compatibility (Discuss first)
  • Heavy dependencies to core library
  • Contributions without proper testing
  • Code that doesn't follow project conventions

📄 Legal

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

You may need to sign a github CLA before you create a PR.

💬 Questions?

  • Open a GitHub issue for technical questions
  • Check existing documentation and issues first
  • Be respectful and constructive in discussions

Thank you for helping make Page-Agent better! 🎉