From 7f8ddde748aba78e97f13ae6c1e9e13bfe65dd07 Mon Sep 17 00:00:00 2001 From: Simon <10131203+gaomeng1900@users.noreply.github.com> Date: Sat, 28 Mar 2026 19:11:54 +0800 Subject: [PATCH 1/2] docs: move setup details to dev-guide; simplify readme and contributing --- CONTRIBUTING.md | 186 +++------------------------------------- README.md | 10 +-- docs/developer-guide.md | 117 +++++++++++++++++++++++++ 3 files changed, 135 insertions(+), 178 deletions(-) create mode 100644 docs/developer-guide.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f303d7..ca044ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,45 +1,14 @@ # Contributing to PageAgent -> **[A note from the maintainer](https://github.com/alibaba/page-agent/issues/349)** — Please read before opening issues or PRs. - ♥️ We welcome contributions from everyone. -## 🚀 Quick Start - -### Development Setup - -1. **Prerequisites** - - `macOS` / `Linux` / `WSL` - - `node.js >= 20` with `npm >= 10` - - An editor that supports `ts/eslint/prettier` - - Make sure `eslint`, `prettier` and `commitlint` work well. Un-linted code won't pass the CI. - -2. **Setup** - - ```bash - npm i - npm start # Start demo and documentation site - npm run build # Build libs and website - ``` - -### Project Structure - -This is a **monorepo** with npm workspaces containing **4 main packages**: - -- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm -- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/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 `@page-agent/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. -> - When bundling `IIFE` and `Website`. Bundle everything together. +For local development workflows, setup, local LLM config, extension development, testing on other websites, and more details, see [docs/developer-guide.md](docs/developer-guide.md). ## 🤝 How to Contribute -### Reporting Issues +> **[Maintainer's Note](https://github.com/alibaba/page-agent/issues/349)** + +### Opening Issues - Use the GitHub issue tracker to report bugs or request features - Search existing issues before creating new ones @@ -48,147 +17,24 @@ This is a **monorepo** with npm workspaces containing **4 main packages**: ### Code Contributions -1. **Fork and Clone** - - ```bash - git clone https://github.com/your-username/page-agent.git - cd page-agent - ``` - -2. **Create Feature Branch** - - ```bash - 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** - - Build and lint everything. - - Test in our demo website - - Test it on other websites if applicable - - `@TODO: test suite` - -5. **Commit and Push** - - ```bash - 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 +1. Follow existing code style and patterns +2. Update documentation as needed +3. Add JSDoc for public APIs +4. Build and lint everything +5. Test in our demo website, and on other websites if applicable +6. Include screenshots for UI changes ### Vibe Coding with AI -> [Vibe coding](https://en.wikipedia.org/wiki/Vibe_coding) - +- Vibe coding is **NOT** allowed for the core lib or the extension!!! - Vibe coding is **RECOMMENDED** when maintaining **the demo, the website, the UI and tests**. - - We have a [website/AGENTS.md](packages/website/AGENTS.md) for that. -- Vibe coding is **NOT** allowed for the core lib!!! -- NEVER try to vibe coding the MV3 extension!!! It is HELL. +- Make sure your AI references `AGENTS.md` and `website/AGENTS.md` for better quality. - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI. -If your AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it: - -- claude-code (`CLAUDE.md`) - - ```markdown - @AGENTS.md - ``` - -- antigravity (`.agent/rules/alias.md`) - - ```markdown - --- - 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 - - ```env - 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): - - ```env - LLM_BASE_URL="http://localhost:11434/v1" - LLM_API_KEY="NA" - LLM_MODEL_NAME="qwen3:14b" - ``` - - > @see https://alibaba.github.io/page-agent/docs/features/models#ollama for configuration - -- **Restart the dev server** to load new env vars -- If not provided, the demo will use the free testing proxy by default. By using it, you agree to its [terms](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md). - -### Extension Development - -```bash -# make sure you ran `npm run build:libs` first -# and every time you changed the core libs -npm run dev -w @page-agent/ext -npm run zip -w @page-agent/ext -``` - -- Update `packages/extension/docs/extension_api.md` for API integration details - -### Testing on Other Websites - -- Start and serve a local `iife` script - - ```bash - npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.demo.js - ``` - -- Add a new bookmark - - ```javascript - javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent 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. Be very careful when you distribute the 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. - ## 🚫 What We Don't Accept - Breaking changes and large PRs without prior discussion - Heavy dependencies to core libs -- Contributions without proper testing -- Code that doesn't follow project conventions - Dependencies or code with licenses incompatible with MIT - Bot or AI-generated pull requests without meaningful human involvement @@ -196,12 +42,6 @@ Ask an AI to help you add documentation to the `website/` package. Follow the ex By contributing to this project, you agree that your contributions will be licensed under the MIT License. -> CLA is optional. - -## 💬 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 PageAgent better! 🎉 diff --git a/README.md b/README.md index 9aa79f6..0edc496 100644 --- a/README.md +++ b/README.md @@ -76,11 +76,11 @@ For more programmatic usage, see [📖 Documentations](https://alibaba.github.io ## 🤝 Contributing -We welcome contributions from the community! Follow our instructions in [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines. +We welcome contributions from the community! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [docs/developer-guide.md](docs/developer-guide.md) for local development workflows. -Please read the [maintainer note](https://github.com/alibaba/page-agent/issues/349) and [Code of Conduct](docs/CODE_OF_CONDUCT.md) before opening issues or PRs. +Please read the [maintainer's note](https://github.com/alibaba/page-agent/issues/349) on principles and current state. -Contributions generated entirely by **bots or agents** without substantial human involvement will **not be accepted**. +Contributions generated entirely by **bots or AI** without substantial human involvement will **not be accepted**. ## ⚖️ License @@ -110,8 +110,8 @@ Built something cool with PageAgent? Add it here! Open a PR to share your projec > These are community projects — not maintained or endorsed by us. Use at your own discretion. -| Project | Description | -| ------- | ----------- | +| Project | Description | +| -------- | ----------------------------------------------------------- | | _Yours?_ | [Open a PR](https://github.com/alibaba/page-agent/pulls) 🙌 | --- diff --git a/docs/developer-guide.md b/docs/developer-guide.md new file mode 100644 index 0000000..8e34ce0 --- /dev/null +++ b/docs/developer-guide.md @@ -0,0 +1,117 @@ +# Developer Guide + +This file is for local development workflows. + +For contribution rules and expectations, see [../CONTRIBUTING.md](../CONTRIBUTING.md). + +## 🚀 Quick Start + +### Development Setup + +1. **Prerequisites** + - `macOS` / `Linux` / `WSL` + - `node.js >= 20` with `npm >= 10` + - An editor that supports `ts/eslint/prettier` + - Make sure `eslint`, `prettier` and `commitlint` work well. Un-linted code won't pass the CI. + +2. **Setup** + + ```bash + npm i + npm start # Start demo and documentation site + npm run build # Build libs and website + ``` + +## 📦 Project Structure + +This is a **monorepo** with npm workspaces containing **4 main packages**: + +- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm +- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/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 `@page-agent/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. +> - When bundling `IIFE` and `Website`. Bundle everything together. + +## 🤖 AGENTS.md Alias + +If your AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it: + +- claude-code (`CLAUDE.md`) + + ```markdown + @AGENTS.md + ``` + +- antigravity (`.agent/rules/alias.md`) + + ```markdown + --- + 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 + + ```env + 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): + + ```env + LLM_BASE_URL="http://localhost:11434/v1" + LLM_API_KEY="NA" + LLM_MODEL_NAME="qwen3:14b" + ``` + + > @see https://alibaba.github.io/page-agent/docs/features/models#ollama for configuration + +- **Restart the dev server** to load new env vars +- If not provided, the demo will use the free testing proxy by default. By using it, you agree to its [terms](./terms-and-privacy.md). + +### Extension Development + +```bash +# make sure you ran `npm run build:libs` first and every time you changed the core libs +npm run dev -w @page-agent/ext +npm run zip -w @page-agent/ext +``` + +- Update `packages/extension/docs/extension_api.md` for API integration details + +### Testing on Other Websites + +- Start and serve a local `iife` script + + ```bash + npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.demo.js + ``` + +- Add a new bookmark + + ```javascript + javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent 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. Be very careful when you distribute the 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. From a7c9999d8365a707e67db3231739e3ccca93a194 Mon Sep 17 00:00:00 2001 From: Simon <10131203+gaomeng1900@users.noreply.github.com> Date: Sat, 28 Mar 2026 19:21:20 +0800 Subject: [PATCH 2/2] chore: mv security file --- SECURITY.md => docs/SECURITY.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename SECURITY.md => docs/SECURITY.md (100%) diff --git a/SECURITY.md b/docs/SECURITY.md similarity index 100% rename from SECURITY.md rename to docs/SECURITY.md