From 50e03f2dd6b45baaa21bf1a4984a6beb5528fa57 Mon Sep 17 00:00:00 2001 From: pomelo-nwu Date: Mon, 22 Dec 2025 21:11:33 +0800 Subject: [PATCH] feat: update docs --- CONTRIBUTING.md | 110 ++++++++++++++++++++++++------------------------ Makefile | 10 ++--- 2 files changed, 61 insertions(+), 59 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a8f053ee..84aa5520 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,27 +2,6 @@ We would love to accept your patches and contributions to this project. -## Before you begin - -### Sign our Contributor License Agreement - -Contributions to this project must be accompanied by a -[Contributor License Agreement](https://cla.developers.google.com/about) (CLA). -You (or your employer) retain the copyright to your contribution; this simply -gives us permission to use and redistribute your contributions as part of the -project. - -If you or your current employer have already signed the Google CLA (even if it -was for a different project), you probably don't need to do it again. - -Visit to see your current agreements or to -sign a new one. - -### Review our Community Guidelines - -This project follows [Google's Open Source Community -Guidelines](https://opensource.google/conduct/). - ## Contribution Process ### Code Reviews @@ -74,12 +53,6 @@ Your PR should have a clear, descriptive title and a detailed description of the In the PR description, explain the "why" behind your changes and link to the relevant issue (e.g., `Fixes #123`). -## Forking - -If you are forking the repository you will be able to run the Build, Test and Integration test workflows. However in order to make the integration tests run you'll need to add a [GitHub Repository Secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) with a value of `GEMINI_API_KEY` and set that to a valid API key that you have available. Your key and secret are private to your repo; no one without access can see your key and you cannot see any secrets related to this repo. - -Additionally you will need to click on the `Actions` tab and enable workflows for your repository, you'll find it's the large blue button in the center of the screen. - ## Development Setup and Workflow This section guides contributors on how to build, modify, and understand the development setup of this project. @@ -98,8 +71,8 @@ This section guides contributors on how to build, modify, and understand the dev To clone the repository: ```bash -git clone https://github.com/google-gemini/gemini-cli.git # Or your fork's URL -cd gemini-cli +git clone https://github.com/QwenLM/qwen-code.git # Or your fork's URL +cd qwen-code ``` To install dependencies defined in `package.json` as well as root dependencies: @@ -118,9 +91,9 @@ This command typically compiles TypeScript to JavaScript, bundles assets, and pr ### Enabling Sandboxing -[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum, setting `GEMINI_SANDBOX=true` in your `~/.env` and ensuring a sandboxing provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See [Sandboxing](#sandboxing) for details. +[Sandboxing](#sandboxing) is highly recommended and requires, at a minimum, setting `QWEN_SANDBOX=true` in your `~/.env` and ensuring a sandboxing provider (e.g. `macOS Seatbelt`, `docker`, or `podman`) is available. See [Sandboxing](#sandboxing) for details. -To build both the `gemini` CLI utility and the sandbox container, run `build:all` from the root directory: +To build both the `qwen-code` CLI utility and the sandbox container, run `build:all` from the root directory: ```bash npm run build:all @@ -130,13 +103,13 @@ To skip building the sandbox container, you can use `npm run build` instead. ### Running -To start the Gemini CLI from the source code (after building), run the following command from the root directory: +To start the Qwen Code application from the source code (after building), run the following command from the root directory: ```bash npm start ``` -If you'd like to run the source build outside of the gemini-cli folder, you can utilize `npm link path/to/gemini-cli/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) or `alias gemini="node path/to/gemini-cli/packages/cli"` to run with `gemini` +If you'd like to run the source build outside of the qwen-code folder, you can utilize `npm link path/to/qwen-code/packages/cli` (see: [docs](https://docs.npmjs.com/cli/v9/commands/npm-link)) to run with `qwen-code` ### Running Tests @@ -154,7 +127,7 @@ This will run tests located in the `packages/core` and `packages/cli` directorie #### Integration Tests -The integration tests are designed to validate the end-to-end functionality of the Gemini CLI. They are not run as part of the default `npm run test` command. +The integration tests are designed to validate the end-to-end functionality of Qwen Code. They are not run as part of the default `npm run test` command. To run the integration tests, use the following command: @@ -209,19 +182,61 @@ npm run lint ### Coding Conventions - Please adhere to the coding style, patterns, and conventions used throughout the existing codebase. -- Consult [QWEN.md](https://github.com/QwenLM/qwen-code/blob/main/QWEN.md) (typically found in the project root) for specific instructions related to AI-assisted development, including conventions for React, comments, and Git usage. - **Imports:** Pay special attention to import paths. The project uses ESLint to enforce restrictions on relative imports between packages. ### Project Structure - `packages/`: Contains the individual sub-packages of the project. - `cli/`: The command-line interface. - - `core/`: The core backend logic for the Gemini CLI. + - `core/`: The core backend logic for Qwen Code. - `docs/`: Contains all project documentation. - `scripts/`: Utility scripts for building, testing, and development tasks. For more detailed architecture, see `docs/architecture.md`. +## Documentation Development + +This section describes how to develop and preview the documentation locally. + +### Prerequisites + +1. Ensure you have Node.js (version 18+) installed +2. Have npm or yarn available + +### Setup Documentation Site Locally + +To work on the documentation and preview changes locally: + +1. Navigate to the `docs-site` directory: + + ```bash + cd docs-site + ``` + +2. Install dependencies: + + ```bash + npm install + ``` + +3. Link the documentation content from the main `docs` directory: + + ```bash + npm run link + ``` + + This creates a symbolic link from `../docs` to `content` in the docs-site project, allowing the documentation content to be served by the Next.js site. + +4. Start the development server: + + ```bash + npm run dev + ``` + +5. Open [http://localhost:3000](http://localhost:3000) in your browser to see the documentation site with live updates as you make changes. + +Any changes made to the documentation files in the main `docs` directory will be reflected immediately in the documentation site. + ## Debugging ### VS Code: @@ -231,7 +246,7 @@ For more detailed architecture, see `docs/architecture.md`. ```bash npm run debug ``` - This command runs `node --inspect-brk dist/gemini.js` within the `packages/cli` directory, pausing execution until a debugger attaches. You can then open `chrome://inspect` in your Chrome browser to connect to the debugger. + This command runs `node --inspect-brk dist/index.js` within the `packages/cli` directory, pausing execution until a debugger attaches. You can then open `chrome://inspect` in your Chrome browser to connect to the debugger. 2. In VS Code, use the "Attach" launch configuration (found in `.vscode/launch.json`). Alternatively, you can use the "Launch Program" configuration in VS Code if you prefer to launch the currently open file directly, but 'F5' is generally recommended. @@ -239,16 +254,16 @@ Alternatively, you can use the "Launch Program" configuration in VS Code if you To hit a breakpoint inside the sandbox container run: ```bash -DEBUG=1 gemini +DEBUG=1 qwen-code ``` -**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect gemini-cli due to automatic exclusion. Use `.gemini/.env` files for gemini-cli specific debug settings. +**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect qwen-code due to automatic exclusion. Use `.qwen-code/.env` files for qwen-code specific debug settings. ### React DevTools To debug the CLI's React-based UI, you can use React DevTools. Ink, the library used for the CLI's interface, is compatible with React DevTools version 4.x. -1. **Start the Gemini CLI in development mode:** +1. **Start the Qwen Code application in development mode:** ```bash DEV=true npm start @@ -270,23 +285,10 @@ To debug the CLI's React-based UI, you can use React DevTools. Ink, the library ``` Your running CLI application should then connect to React DevTools. - ![](/docs/assets/connected_devtools.png) ## Sandboxing -### macOS Seatbelt - -On macOS, `qwen` uses Seatbelt (`sandbox-exec`) under a `permissive-open` profile (see `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) that restricts writes to the project folder but otherwise allows all other operations and outbound network traffic ("open") by default. You can switch to a `restrictive-closed` profile (see `packages/cli/src/utils/sandbox-macos-restrictive-closed.sb`) that declines all operations and outbound network traffic ("closed") by default by setting `SEATBELT_PROFILE=restrictive-closed` in your environment or `.env` file. Available built-in profiles are `{permissive,restrictive}-{open,closed,proxied}` (see below for proxied networking). You can also switch to a custom profile `SEATBELT_PROFILE=` if you also create a file `.qwen/sandbox-macos-.sb` under your project settings directory `.qwen`. - -### Container-based Sandboxing (All Platforms) - -For stronger container-based sandboxing on macOS or other platforms, you can set `GEMINI_SANDBOX=true|docker|podman|` in your environment or `.env` file. The specified command (or if `true` then either `docker` or `podman`) must be installed on the host machine. Once enabled, `npm run build:all` will build a minimal container ("sandbox") image and `npm start` will launch inside a fresh instance of that container. The first build can take 20-30s (mostly due to downloading of the base image) but after that both build and start overhead should be minimal. Default builds (`npm run build`) will not rebuild the sandbox. - -Container-based sandboxing mounts the project directory (and system temp directory) with read-write access and is started/stopped/removed automatically as you start/stop Gemini CLI. Files created within the sandbox should be automatically mapped to your user/group on host machine. You can easily specify additional mounts, ports, or environment variables by setting `SANDBOX_{MOUNTS,PORTS,ENV}` as needed. You can also fully customize the sandbox for your projects by creating the files `.qwen/sandbox.Dockerfile` and/or `.qwen/sandbox.bashrc` under your project settings directory (`.qwen`) and running `qwen` with `BUILD_SANDBOX=1` to trigger building of your custom sandbox. - -#### Proxied Networking - -All sandboxing methods, including macOS Seatbelt using `*-proxied` profiles, support restricting outbound network traffic through a custom proxy server that can be specified as `GEMINI_SANDBOX_PROXY_COMMAND=`, where `` must start a proxy server that listens on `:::8877` for relevant requests. See `docs/examples/proxy-script.md` for a minimal proxy that only allows `HTTPS` connections to `example.com:443` (e.g. `curl https://example.com`) and declines all other requests. The proxy is started and stopped automatically alongside the sandbox. +> TBD ## Manual Publish diff --git a/Makefile b/Makefile index fc540ccc..db8cba23 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,9 @@ -# Makefile for gemini-cli +# Makefile for qwen-code .PHONY: help install build build-sandbox build-all test lint format preflight clean start debug release run-npx create-alias help: - @echo "Makefile for gemini-cli" + @echo "Makefile for qwen-code" @echo "" @echo "Usage:" @echo " make install - Install npm dependencies" @@ -14,11 +14,11 @@ help: @echo " make format - Format the code" @echo " make preflight - Run formatting, linting, and tests" @echo " make clean - Remove generated files" - @echo " make start - Start the Gemini CLI" - @echo " make debug - Start the Gemini CLI in debug mode" + @echo " make start - Start the Qwen Code CLI" + @echo " make debug - Start the Qwen Code CLI in debug mode" @echo "" @echo " make run-npx - Run the CLI using npx (for testing the published package)" - @echo " make create-alias - Create a 'gemini' alias for your shell" + @echo " make create-alias - Create a 'qwen' alias for your shell" install: npm install