From d66bf8f3cf4a920a5378da04d845a0dfc686f43c Mon Sep 17 00:00:00 2001 From: Simon <10131203+gaomeng1900@users.noreply.github.com> Date: Mon, 9 Mar 2026 17:00:25 +0800 Subject: [PATCH] docs: improve Contributing.md --- CONTRIBUTING.md | 49 +++++++++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 541f424..d267139 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to Page-Agent +# Contributing to PageAgent -Thank you for your interest in contributing to Page-Agent! We welcome contributions from everyone. +Thank you for your interest in contributing to PageAgent! We welcome contributions from everyone. ## 🚀 Quick Start @@ -27,11 +27,11 @@ This is a **monorepo** with npm workspaces containing **4 main packages**: - **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 to leave deps out. -- When bundling `IIFE` and `Website`. Bundle everything including local packages. +> 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 @@ -90,14 +90,17 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference - Keep functions small and focused - Add JSDoc for public APIs -### Vibe coding with AI +### 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!!! +> [Vibe coding](https://en.wikipedia.org/wiki/Vibe_coding) = describe what you want in natural language, let AI write the code, and you review the result. + +- 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. - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI. -- Update the [AI instructions](AGENTS.md) when structure changed. -If your lame AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it: +If your AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it: - claude-code (`CLAUDE.md`) @@ -135,10 +138,10 @@ If your lame AI assistant does not support [AGENTS.md](https://agents.md/). Add 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` + > @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 the free testing proxy by default +- **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). ### Website Development @@ -149,12 +152,13 @@ npm start ### 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 ``` -- 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 +- Update `packages/extension/docs/extension_api.md` for API integration details ### Testing on Other Websites @@ -172,7 +176,7 @@ npm run zip -w @page-agent/ext - Click the bookmark on any page to load Page-Agent -> Warning: AK in your local `.env` will be inlined in the iife script. +> Warning: AK in your local `.env` will be inlined in the iife script. Be very careful when you distribute the script. ### Adding Documentation @@ -193,16 +197,17 @@ We especially welcome contributions in: ## 🚫 What We Don't Accept -- Changes that break existing API compatibility (Discuss first) -- Heavy dependencies to core library +- 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 ## 📄 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. +> You need to sign a github CLA when you create a PR. ## 💬 Questions? @@ -210,4 +215,4 @@ By contributing to this project, you agree that your contributions will be licen - Check existing documentation and issues first - Be respectful and constructive in discussions -Thank you for helping make Page-Agent better! 🎉 +Thank you for helping make PageAgent better! 🎉