## 1. Project Overview & Quickstart (agentscope-ai/QwenPaw) ## File: README.md Your personal AI assistant — deploy locally or in the cloud, extend with Skills & Plugins, connect across every channel. | | | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Never forgets** | Three-layer memory — live working context, full verbatim history, and a self-evolving personal knowledge base powered by [ReMe](https://github.com/agentscope-ai/ReMe). Conversations and resources continuously become readable, editable, searchable, and linked Markdown memory. | | **Local or cloud, runs free** | QwenPaw-Flash models (2B / 4B / 9B) trained for agent tasks. Built-in QwenPaw Local runtime — no API key, no cloud dependency. Also works with Ollama, LM Studio, or 14+ cloud providers. | | **Security built in** | Kernel-level Sandbox, Tool Guard, File Guard, Skill Scanner, and Access Policy. Dangerous commands are blocked before they run. | | **Multi-agent & parallel** | Spawn independent agents with their own memory and skills. Sub-agents at runtime. Agent Communication Protocol (ACP) for cross-system orchestration. | | **File workspace** | Unified file navigation, preview, editing, diffs, upload, and download across project and Agent files. | | **Extensible** | Skills for scheduling, documents, browser, news, and more. Plugin architecture with a marketplace. MCP integration for external tools. Combine them into purpose-built workflows. | | **Reachable anywhere** | DingTalk, Lark, WeChat, Discord, Telegram, iMessage, QQ — one instance, all channels. Console, TUI, and desktop app for direct access. | | **Yours, not ours** | Deploy locally — data stays on your machine. No third-party hosting, no data upload. | **What you can do with QwenPaw** - **Automation & scheduling**: Set up recurring tasks — news digests, report generation, multi-channel broadcasting — all on your schedule. - **Code & development**: Read, edit, review, and test code in your projects with the unified file workspace. - **Document processing**: Read, write, and convert PDF, Word, Excel, and PowerPoint files. - **Information gathering**: Search the web, follow subscriptions, summarize videos, and find what you need in your personal knowledge base. - **Multi-channel ops**: Push alerts, summaries, or AI-generated content to DingTalk, Lark, Discord, Telegram, and more — simultaneously or per channel. - **Custom workflows**: Combine built-in capabilities, plugins, and scheduled tasks into workflows tailored to your needs. --- ## News - [2026-08-13] **v2.1.0** | QwenPaw OS Shell, unified Files workspace, QwenPaw Creator, Codex/Qoder Agent integration, Browser-use, Computer-use, workspace checkpoints, and long-running conversation continuity. [v2.1.0 Release Notes →](https://qwenpaw.agentscope.io/release-notes#v2.1.0) - [2026-07-24] **v2.0.1** | PawApp mini-app platform, user-editable Agent Modes, Oh-My-Paw plugins, [ReMe](https://github.com/agentscope-ai/ReMe) memory enhancements, desktop UX improvements, and more. [v2.0.1 Release Notes →](https://qwenpaw.agentscope.io/release-notes#v2.0.1) - [2026-07-10] **v2.0.0 — QwenPaw 2.0 Official Release** 🎉 | An AgentScope 2.0 based ground-up rewrite delivering the Agent OS architecture, Loop Engineering, Scroll Context, [ReMe](https://github.com/agentscope-ai/ReMe) v0.4 Self-evolving Personal Knowledge Base, and a bundled Terminal UI. | Highlight | What's new | |-----------|------------| | **Agent OS — Workspace** | Three pillars per agent: **Resources** (transparent on disk), **Governance** (allow/deny/ask/sandbox), **Sandbox** (macOS / Linux / Windows). | | **Agent OS — Drivers** | Protocol-neutral MCP / A2A / ACP connector layer with encrypted credentials and per-call policy gate. | | **Loop Engineering** | Advanced agent loop templates (Coding Mode, Mission Mode, more to come) with composable approval gates. | | **Scroll Context** | Every turn persisted; evicted turns indexed with on-demand recall — nothing summarized away. | | **[ReMe](https://github.com/agentscope-ai/ReMe) v0.4 Self-evolving Personal Knowledge Base** | Continuously turns conversations and resources into readable, editable, searchable, and linked Markdown memory. | | **Terminal UI (TUI)** | Full-screen terminal chat — same agent, memory, and sessions as Console and channels. | Built on Agent OS, we will be launching out-of-box QwenPaw applications — such as **QwenPaw Creator** and **QwenPaw Insight** — stay tuned. [v2.0.0 Release Notes →](https://qwenpaw.agentscope.io/release-notes#v2.0.0) - [2026-06-17] **v1.1.12 — Models Page Overhaul & Simple Mode** | Redesigned Models page with provider aggregation; new Simple Mode for streamlined navigation. [v1.1.12 Release Notes →](https://qwenpaw.agentscope.io/release-notes#v1.1.12) - [2026-06-11] **AgentScope Platform is live** — Free QwenPaw deployment, plugin sharing, and Skill marketplace. [Try it now →](https://platform.agentscope.io/) - [2026-06-10] **v1.1.11** — Free Model OAuth, Plugin Market, MCP Tool Whitelisting. [v1.1.11 Release Notes →](https://qwenpaw.agentscope.io/release-notes#v1.1.11) [All release notes →](https://qwenpaw.agentscope.io/release-notes) --- ## Table of Contents - [News](#news) - [Quick Start](#quick-start) - [API Key](#api-key) - [Local Models](#local-models) - [Security Features](#security-features) - [Documentation](#documentation) - [FAQ](#faq) - [Roadmap](#roadmap) - [Contributing](#contributing) - [Install From Source](#install-from-source) - [Why QwenPaw?](#why-qwenpaw) - [Built By](#built-by) - [License](#license) --- ## Quick Start ### Option 1: Pip Install If you prefer managing Python yourself (requires Python >= 3.11, < 3.14): ```bash pip install qwenpaw qwenpaw init --defaults qwenpaw app ``` Then open the Console in your browser at **http://127.0.0.1:8088/** to configure your model. To chat in DingTalk, Lark, WeChat, etc., see the [Channel setup](https://qwenpaw.agentscope.io/docs/channels) documentation. --- ### Option 2: Script Install No Python setup required, one command installs everything. The script will automatically download uv (Python package manager), create a virtual environment, and install QwenPaw with all dependencies (including Node.js and frontend assets). Note: May not work in restricted network environments or corporate firewalls. **macOS / Linux:** ```bash curl -fsSL https://qwenpaw.agentscope.io/install.sh | bash ``` **Windows (CMD):** ```CMD curl -fsSL https://qwenpaw.agentscope.io/install.bat -o install.bat && install.bat ``` **Windows (PowerShell):** ```powershell irm https://qwenpaw.agentscope.io/install.ps1 | iex ``` > **Note**: The installer will automatically check the status of uv. If it is not installed, it will attempt to download and configure it automatically. If the automatic installation fails, please follow the on-screen prompts or execute `python -m pip install -U uv`, then rerun the installer. > **⚠️ Special Notice for Windows Enterprise LTSC Users** > > If you are using Windows LTSC or an enterprise environment governed by strict security policies, PowerShell may run in **Constrained Language Mode**, potentially causing the following issue: > 1. **If using CMD (.bat): Script executes successfully but fails to write to `Path`** > > The script completes file installation. Due to **Constrained Language Mode**, it cannot automatically update environment variables. Manually configure as follows: > - **Locate the installation directory**: > - Check if `uv` is available: Enter `uv --version` in CMD. If a version number appears, **only configure the QwenPaw path**. If you receive the prompt `'uv' is not recognized as an internal or external command, operable program or batch file,` configure both paths. > - uv path (choose one based on installation location; use if `uv` fails): Typically `%USERPROFILE%\.local\bin`, `%USERPROFILE%\AppData\Local\uv`, or the `Scripts` folder within your Python installation directory > - QwenPaw path: Typically located at `%USERPROFILE%\.qwenpaw\bin`. > - **Manually add to the system's Path environment variable**: > - Press `Win + R`, type `sysdm.cpl` and press Enter to open System Properties. > - Click “Advanced” -> “Environment Variables”. > - Under “System variables”, locate and select `Path`, then click “Edit”. > - Click “New”, enter both directory paths sequentially, then click OK to save. > 2. **If using PowerShell (.ps1): Script execution interrupted** > > Due to **Constrained Language Mode**, the script may fail to automatically download `uv`. > - **Manually install uv**: Refer to the [GitHub Release](https://github.com/astral-sh/uv/releases) to download `uv.exe` and place it in `%USERPROFILE%\.local\bin` or `%USERPROFILE%\AppData\Local\uv`; or ensure Python is installed and run `python -m pip install -U uv`. > - **Configure `uv` environment variables**: Add the `uv` directory and `%USERPROFILE%\.qwenpaw\bin` to your system's `Path` variable. > - **Re-run the installation**: Open a new terminal and execute the installation script again to complete the `QwenPaw` installation. > - **Configure the `QwenPaw` environment variable**: Add `%USERPROFILE%\.qwenpaw\bin` to your system's `Path` variable. Once installed, open a new terminal and run: ```bash qwenpaw init --defaults # or: qwenpaw init (interactive) qwenpaw app ``` **Install options** **macOS / Linux:** ```bash # Install a specific version curl -fsSL ... | bash -s -- --version 1.1.0 # Install from source (dev/testing) curl -fsSL ... | bash -s -- --from-source # Upgrade — just re-run the installer curl -fsSL ... | bash # Uninstall qwenpaw uninstall # keeps config and data qwenpaw uninstall --purge # removes everything ``` **Windows (PowerShell):** ```powershell # Install a specific version irm ... | iex; .\install.ps1 -Version 1.1.12 # Install from source (dev/testing) .\install.ps1 -FromSource # Upgrade — just re-run the installer irm ... | iex # Uninstall qwenpaw uninstall # keeps config and data qwenpaw uninstall --purge # removes everything ``` --- ### Option 3: Docker Images are on **Docker Hub** (`agentscope/qwenpaw`). Image tags: `latest` (stable); `pre` (PyPI pre-release). ```bash docker pull agentscope/qwenpaw:latest docker run -p 127.0.0.1:8088:8088 \ -v qwenpaw-data:/app/working \ -v qwenpaw-secrets:/app/working.secret \ -v qwenpaw-backups:/app/working.backups \ agentscope/qwenpaw:latest ``` Also available on Alibaba Cloud Container Registry (ACR) for users in China: `agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw` (same tags). Then open **http://127.0.0.1:8088/** for the Console. Config, memory, and skills are stored in the `qwenpaw-data` volume; model provider settings and API keys are in the `qwenpaw-secrets` volume; backup archives are stored in the `qwenpaw-backups` volume. To pass API keys (e.g. `DASHSCOPE_API_KEY`), add `-e VAR=value` or `--env-file .env` to `docker run`. > **Connecting to Ollama or other services on the host machine** > > Inside a Docker container, `localhost` refers to the container itself, not your host machine. If you run Ollama (or other model services) on the host and want QwenPaw in Docker to reach them, use one of these approaches: > > **Option A** — Explicit host binding (all platforms): > ```bash > docker run -p 127.0.0.1:8088:8088 \ > --add-host=host.docker.internal:host-gateway \ > -v qwenpaw-data:/app/working \ > -v qwenpaw-secrets:/app/working.secret \ > -v qwenpaw-backups:/app/working.backups \ > agentscope/qwenpaw:latest > ``` > Then in QwenPaw **Settings → Models**, change the Base URL to `http://host.docker.internal:` — for example, `http://host.docker.internal:11434` for Ollama, or `http://host.docker.internal:1234/v1` for LM Studio. > > **Option B** — Host networking (Linux only): > ```bash > docker run --network=host \ > -v qwenpaw-data:/app/working \ > -v qwenpaw-secrets:/app/working.secret \ > -v qwenpaw-backups:/app/working.backups \ > agentscope/qwenpaw:latest > ``` > No port mapping (`-p`) is needed; the container shares the host network directly. Note that all container ports are exposed on the host, which may cause conflicts if the port is already in use. > The image is built from scratch. To build the image yourself, please refer to the [Build Docker image](scripts/README.md#build-docker-image) section in `scripts/README.md`, and then push to your registry. --- ### Option 4: Deploy on Alibaba Cloud ECS To run QwenPaw on Alibaba Cloud (ECS), use the one-click deployment: open the [QwenPaw on Alibaba Cloud (ECS) deployment link](https://computenest.console.aliyun.com/service/instance/create/cn-hangzhou?type=user&ServiceId=service-1ed84201799f40879884) and follow the prompts. For step-by-step instructions, see [Alibaba Cloud Developer: Deploy your AI assistant in 3 minutes](https://developer.aliyun.com/article/1713682). --- ### Option 5: AgentScope Platform [AgentScope Platform](https://platform.agentscope.io/) provides one-click cloud QwenPaw deployment, plugin sharing, and a Skill marketplace. Free, 7/24 online. --- ### Option 6: Using ModelScope [ModelScope Studio](https://modelscope.cn/studios/fork?target=AgentScope/QwenPaw) also supports cloud QwenPaw deployment. Note: set your Studio to **non-public** so others cannot control your QwenPaw. --- ### Option 7: Desktop Application (Beta) > **Beta Notice**: The desktop application is currently in Beta testing phase with the following known limitations: > - **Incomplete compatibility testing**: Not fully tested across all system versions and hardware configurations > - **Potential performance issues**: Startup time, memory usage, and other performance aspects may need further optimization > - **Features under development**: Some features may be unstable or missing If you're not comfortable with command-line tools, you can download and use QwenPaw's desktop application without manually configuring Python environments or running commands. #### Download Download the desktop app (Tauri build) from [the official download page](https://qwenpaw.agentscope.io/downloads): - **Windows**: `QwenPaw-Tauri--Windows-setup.exe` - **macOS**: `QwenPaw-Tauri--macOS.zip` (Apple Silicon recommended) #### Features - ✅ **Zero configuration**: Download and double-click to run, no need to install Python or configure environment variables - ✅ **Cross-platform**: Supports Windows 10+ and macOS 14+ - ✅ **Visual interface**: Automatically opens the app window, no need to manually enter addresses - ⚠️ **Beta stage**: Features are continuously being improved, feedback welcome #### First Launch **Important**: The first launch may take 10-60 seconds (depending on your system configuration). The application needs to initialize the Python environment and load dependencies. Please wait patiently for the window to open automatically. #### macOS: Bypass System Security Restrictions When you download the QwenPaw macOS app from Releases, macOS may show: *"Apple cannot verify that 'QwenPaw' contains no malicious software"*. This happens because the app is not notarized. You can still open it as follows: - **Right-click to open (recommended)** Right-click (or Control+click) the QwenPaw app → **Open** → in the dialog click **Open** again. This tells Gatekeeper you trust the app; after that you can double-click to launch as usual. - **Allow in System Settings** If it is still blocked, go to **System Settings → Privacy & Security**, scroll to the message like *"QwenPaw was blocked because it is from an unidentified developer"*, and click **Open Anyway** or **Allow**. - **Remove quarantine attribute (not recommended for most users)** In Terminal run: `xattr -cr "/Applications/QwenPaw Desktop.app"` (or use the path to the `.app` after unzipping). This clears the "downloaded from the internet" quarantine flag so the warning usually does not appear, but is less safe and controllable than using **Right-click → Open**. For detailed usage instructions, troubleshooting, and common issues, see the [Desktop Application Guide](https://qwenpaw.agentscope.io/docs/desktop). --- ### What's Next? After installation, configure your model in **Console → Settings → Models**, then explore: - [Add Skills](https://qwenpaw.agentscope.io/docs/skills) to extend capabilities (PDF, Office, browser, news, etc.) - [Set up Channels](https://qwenpaw.agentscope.io/docs/channels) for DingTalk, Lark, Discord, and more - [Configure Cron](https://qwenpaw.agentscope.io/docs/cron) for scheduled tasks and automation - See the full [Quick Start guide](https://qwenpaw.agentscope.io/docs/quickstart) for all options and verification steps --- ## Terminal UI (TUI) Prefer to stay in the terminal? Run `qwenpaw` to open a full-screen chat **TUI** that drives the _same_ agent as the Console and the IM Channels — same memory, skills, MCP tools, and sessions — without leaving your keyboard. ```bash qwenpaw # open a chat with the active agent qwenpaw tui --resume # resume a previous session qwenpaw . # start in the current repo (Coding Mode) ``` It supports streaming replies, slash commands (`/help`, `/resume`, `/theme`, plus the agent's own `/model`, `/clear`, …), pasting files/long text as attachments, and inline tool-permission prompts. See the [Terminal UI guide](https://qwenpaw.agentscope.io/docs/tui) for details. --- ## API Key If you use a **cloud LLM API** (e.g., DashScope / Qwen, OpenAI, Anthropic, Google Gemini, DeepSeek, Kimi, OpenRouter, and more), you must configure an API key before chatting. QwenPaw will not work until a valid key is set. See the [official docs](https://qwenpaw.agentscope.io/docs/models) for details. **How to configure:** 1. **Console (recommended)** — After running `qwenpaw app`, open **http://127.0.0.1:8088/** → **Settings** → **Models**. Choose a provider, enter the **API Key**, and enable that provider and model. 2. **`qwenpaw init`** — When you run `qwenpaw init`, it will guide you through configuring the LLM provider and API key. Follow the prompts to choose a provider and enter your key. 3. **Environment variable** — For DashScope you can set `DASHSCOPE_API_KEY` in your shell or in a `.env` file in the working directory. Tools that need extra keys (e.g. `TAVILY_API_KEY` for web search) can be set in Console **Settings → Environment variables**, see [Config](https://qwenpaw.agentscope.io/docs/config) for details. > **Using local models only?** If you use [Local Models](#local-models) (QwenPaw Local / Ollama / LM Studio), you do **not** need any API key. ## Local Models QwenPaw can run LLMs entirely on your machine — no API keys or cloud services required. See the [official docs](https://qwenpaw.agentscope.io/docs/models) for details. QwenPaw also provides the **QwenPaw-Flash** series — purpose-trained 2B / 4B / 9B models for agent scenarios, with Q4 and Q8 quantizations. Available on [ModelScope](https://www.modelscope.cn/organization/AgentScope?tab=model) and [Hugging Face](https://huggingface.co/agentscope-ai/models). | Backend | Best for | Install | | -------------------- | ---------------------------------------- | -------------------------------------------------------------------- | | **QwenPaw Local** (llama.cpp) | Cross-platform (macOS / Linux / Windows) | Built-in; click "Download" in the web UI. Supports QwenPaw-Flash with hardware-aware recommendations. | | **Ollama** | Cross-platform (requires Ollama service) | Install and start Ollama; set context length ≥ 32k. | | **LM Studio** | Cross-platform (requires LM Studio) | Install and start LM Studio; enable Local Server. | --- ## Security Features QwenPaw includes four core security layers: - **Sandbox** — Kernel-level execution isolation using Seatbelt (macOS), Bubblewrap / Landlock (Linux), and AppContainer (Windows). Shell commands run inside a restricted filesystem view. - **Tool Guard** — YAML rule engine with `ShellEvasionGuardian` inspects every tool call before execution, detecting command injection, path traversal, reverse shells, and obfuscated attacks. Configurable approval levels: STRICT / SMART / AUTO / OFF. - **File Guard** — Independent of Tool Guard; blocks agent access to sensitive files and directories (default-protects `~/.qwenpaw.secret/`, `~/.ssh`, etc.). - **Skill Scanner** — Pre-activation scanning with block / warn / off modes and whitelist support. Detects prompt injection, hardcoded secrets, data exfiltration, and more. See [Security](https://qwenpaw.agentscope.io/docs/security) for details. --- ## Documentation | Topic | Description | | --------------------------------------------------------------------- | ------------------------------------------------ | | [Introduction](https://qwenpaw.agentscope.io/docs/intro) | What QwenPaw is and how to use it | | [Quick start](https://qwenpaw.agentscope.io/docs/quickstart) | Install and run (local or ModelScope Studio) | | [Console](https://qwenpaw.agentscope.io/docs/console) | Web UI: chat and agent configuration | | [Terminal UI (TUI)](https://qwenpaw.agentscope.io/docs/tui) | Full-screen terminal chat, same agent as Console | | [Desktop App](https://qwenpaw.agentscope.io/docs/desktop) | Desktop application installation and usage | | [Models](https://qwenpaw.agentscope.io/docs/models) | Configure cloud, local, and custom providers | | [Channels](https://qwenpaw.agentscope.io/docs/channels) | DingTalk, Lark, QQ, Discord, iMessage, and more | | [Skills](https://qwenpaw.agentscope.io/docs/skills) | Extend and customize capabilities | | [Plugins](https://qwenpaw.agentscope.io/docs/plugins) | Plugin system and Plugin Market | | [MCP](https://qwenpaw.agentscope.io/docs/mcp) | Manage MCP clients | | [Persona](https://qwenpaw.agentscope.io/docs/persona) | Agent personality customization (SOUL / PROFILE) | | [Memory](https://qwenpaw.agentscope.io/docs/memory) | Self-evolving personal knowledge base built on local, editable, searchable, and linked Markdown memory, powered by [ReMe](https://github.com/agentscope-ai/ReMe) | | [ReMe Documentation](https://docs.agentscope.io/reme/latest/en/overview) | Official ReMe overview and documentation | | [Memory-Evolving & Proactive](https://qwenpaw.agentscope.io/docs/memory-evolving-and-proactive) | Agent memory evolution and proactive interaction | | [Context](https://qwenpaw.agentscope.io/docs/context) | Scroll-based context management | | [Magic commands](https://qwenpaw.agentscope.io/docs/commands) | Control conversation state without waiting for the AI | | [Heartbeat](https://qwenpaw.agentscope.io/docs/heartbeat) | Scheduled check-in and digest | | [Cron / Scheduled Tasks](https://qwenpaw.agentscope.io/docs/cron) | Scheduled tasks and automation | | [Multi-Agent](https://qwenpaw.agentscope.io/docs/multi-agent) | Create multiple agents and enable collaboration | | [Security](https://qwenpaw.agentscope.io/docs/security) | Sandbox, tool guard, file guard, skill scanner, access policy | | [Backup & Restore](https://qwenpaw.agentscope.io/docs/backup) | Data backup and recovery | | [Config & working dir](https://qwenpaw.agentscope.io/docs/config) | Working directory and config file | | [REST API](https://qwenpaw.agentscope.io/docs/api-tutorial) | HTTP API for integration and automation | | [ACP Integration](https://qwenpaw.agentscope.io/docs/acp-integration) | Agent Communication Protocol integration | | [CLI](https://qwenpaw.agentscope.io/docs/cli) | Init, cron jobs, skills, clean | | [Agent Team Practice](https://qwenpaw.agentscope.io/docs/practice-agent-team) | Multi-agent team deployment guide | | [FAQ](https://qwenpaw.agentscope.io/docs/faq) | Common questions and troubleshooting | Full documentation: [qwenpaw.agentscope.io/docs](https://qwenpaw.agentscope.io/docs) --- ## FAQ For common questions, troubleshooting tips, and known issues, please visit the **[FAQ page](https://qwenpaw.agentscope.io/docs/faq)**. --- ## Roadmap | Area | Item | Status | | ------------------------------- | ---------------------------------------------------------------------- | -------------------- | | **Horizontal Expansion** | More channels, models, skills, and MCPs | Seeking Contributors | | **Existing Feature Extension** | Display, download, and Windows improvements | Seeking Contributors | | **Models** | Multi-model switching | In Progress | | **Safety & Approval** | Batch preview and approval | In Progress | | **Automation** | Automated tasks | In Progress | | **Agent Interaction** | Agent task handoff | In Progress | | | Running task steering | In Progress | | **Workspaces** | Multiple workspaces | In Progress | | **Context** | System prompt compression | In Progress | | **Tooling** | Multi-location file changes | In Progress | | | Persistent terminals and background tasks | In Progress | | **Computer-use** | On-screen target detection and actions | In Progress | | **Voice Interaction** | Real-time voice tasks | In Progress | | **Context Management & Memory** | Hot-swappable vector models and storage | In Progress | | | Personal knowledge base | In Progress | | **QwenPaw Applications** | QwenPaw Insight | In Progress | | | QwenPaw Mail | In Progress | _Status:_ **In Progress** — actively being worked on; **Seeking Contributors** — we strongly encourage community contributions. --- ## Contributing QwenPaw evolves through open collaboration, and we welcome all forms of contribution! Check the [Roadmap](#roadmap) above (especially items marked **Seeking Contributors**) to find areas that interest you, and read [CONTRIBUTING](https://github.com/agentscope-ai/QwenPaw/blob/main/CONTRIBUTING.md) to get started. We particularly welcome: - **Horizontal expansion** — new channels, model providers, skills, MCPs. - **Existing feature extension & refinement** — display and interaction improvements, download hints, Windows path compatibility, etc. Join [GitHub Discussions](https://github.com/agentscope-ai/QwenPaw/discussions) to discuss ideas or pick up tasks. --- ## Install From Source ```bash git clone https://github.com/agentscope-ai/QwenPaw.git cd QwenPaw # Build console frontend first (required for web UI) cd console && npm ci && npm run build cd .. # Copy console build output to package directory mkdir -p src/qwenpaw/console cp -R console/dist/. src/qwenpaw/console/ # Install Python package pip install -e . ``` - **Dev** (tests, formatting): `pip install -e ".[dev,test,full]"` - **Then**: Run `qwenpaw init --defaults`, then `qwenpaw app`. > **Note for updates:** When updating to a new major version after `git pull`, please also rebuild the frontend, reinstall the package (`pip install -e .`), restart `qwenpaw app`, and clear your browser cache with `Ctrl+Shift+R` (or `Cmd+Shift+R` on macOS). --- ## Why QwenPaw? QwenPaw stands for Qwen Personal Agent Workstation, and also embodies the wisdom of Qwen and the warmth of a Paw. We hope it is not a cold tool, but an intelligent and warm "little paw" always ready to help—a most intuitive partner in your digital life. --- ## Built By [AgentScope team](https://github.com/agentscope-ai) · [AgentScope](https://github.com/agentscope-ai/agentscope) · [AgentScope Runtime](https://github.com/agentscope-ai/agentscope-runtime) · [ReMe](https://github.com/agentscope-ai/ReMe) --- ## Contact Us | [Discord](https://discord.gg/eYMpfnkG8h) | [X (Twitter)](https://x.com/agentscope_ai) | [DingTalk](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) | [RedNote](https://www.xiaohongshu.com/user/profile/691c18db0000000037032be9) | | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | | [](https://discord.gg/eYMpfnkG8h) | [](https://x.com/agentscope_ai) | [](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) | [](https://www.xiaohongshu.com/user/profile/691c18db0000000037032be9) | --- ## Staying Ahead Star QwenPaw on GitHub and be instantly notified of new releases. --- ## Telemetry QwenPaw collects **anonymous** usage data during `qwenpaw init` to help us understand our user base and prioritize improvements. Data is sent **once per version** — when you upgrade QwenPaw, telemetry is re-collected so we can track version adoption. **What we collect:** - QwenPaw version (e.g., 1.1.12) - Install method (pip, Docker, or desktop app) - OS and version (e.g., macOS 14.0, Ubuntu 22.04) - Python version (e.g., 3.13) - CPU architecture (e.g., x86_64, arm64) - GPU availability (yes/no) **What we do NOT collect:** No personal data, no files, no credentials, no IP addresses, no identifiable information. When running `qwenpaw init` interactively, you will be asked whether to opt in. If you choose `--defaults`, telemetry is accepted automatically. The prompt appears once per version and never affects QwenPaw's functionality. --- ## License QwenPaw is released under the [Apache License 2.0](LICENSE). --- ## Contributors All thanks to our contributors: --- ## File: scripts/pack/README.md # QwenPaw Desktop packaging scripts > ⚠️ **Legacy (rollback-only).** These conda-pack based packaging scripts have > been superseded by the **Tauri** desktop build (see `console/src-tauri/` and > `scripts/pack-tauri/`). They are kept only for short-term rollback and are no > longer used by the release pipeline. For the current desktop app, refer to the > [Desktop Application Guide](https://qwenpaw.agentscope.io/docs/desktop). One-click build: each script first builds a **wheel** via `scripts/wheel_build.sh` (includes the console frontend), then uses a **temporary conda environment** and **conda-pack** (no current dev env). Dependencies follow `pyproject.toml`. - **Windows**: wheel → conda-pack → unpack → NSIS installer (`.exe`) - **macOS**: wheel → conda-pack → unpack into `.app` → optional zip ## System Requirements - **Windows**: Windows 10 or later - **macOS**: macOS 14 (Sonoma) or later, Apple Silicon (M1/M2/M3/M4) recommended ## Prerequisites - **conda** (Miniconda/Anaconda) on PATH - **Node.js / npm** (for the console frontend) - (Windows only) **NSIS**: `makensis` on PATH - **Icons**: Pre-generated `icon.ico` (Windows) and `icon.icns` (macOS) are included in `scripts/pack/assets/` ## One-click build From the **repo root**: **macOS** ```bash bash ./scripts/pack/build_macos.sh # Output: dist/QwenPaw.app CREATE_ZIP=1 bash ./scripts/pack/build_macos.sh # also create .zip ``` **Windows (PowerShell)** ```powershell ./scripts/pack/build_win.ps1 # Output: dist/QwenPaw-Setup-.exe # Creates two launchers: # - QwenPaw Desktop.vbs (silent, no console window) # - QwenPaw Desktop (Debug).bat (shows console for troubleshooting) # Note: Pre-compiles all Python files to .pyc for faster startup ``` ## Run from terminal and see logs (macOS) If the .app crashes on double-click, run it from Terminal to see the full error and logs: ```bash # From repo root; force packed env only (no system conda / PYTHONPATH). Adjust path if needed. APP_ENV="$(pwd)/dist/QwenPaw.app/Contents/Resources/env" PYTHONNOUSERSITE=1 PYTHONPATH= PYTHONHOME="$APP_ENV" "$APP_ENV/bin/python" -m qwenpaw desktop ``` The `PYTHONNOUSERSITE=1` prevents Python from loading packages from `~/.local/lib/pythonX.Y/site-packages`, which can conflict with the packaged environment. All stdout/stderr (including Python tracebacks) will appear in the terminal. Use this to debug startup errors or to run with `--log-level debug`. When you **double-click** the .app and nothing appears, the launcher writes stderr/stdout to `~/.qwenpaw/desktop.log`. Inspect that file for errors. On first launch macOS may ask for “Desktop” or “Files and Folders” access: click **Allow** so the app can run properly; if you click Don’t Allow, the window may close. ## macOS: if “Apple cannot verify” / Gatekeeper blocks the app When users download the QwenPaw macOS app (e.g. from Releases) as a `.app` (in a zip), macOS may show: *"Apple cannot verify that 'QwenPaw' contains no malicious software"*. The app is not notarized. They can still open it as follows: - **Right-click to open (recommended)** Right-click (or Control+click) the QwenPaw app → **Open** → in the dialog click **Open** again. Gatekeeper will allow it; after that double-click works as usual. - **Allow in System Settings** If still blocked, go to **System Settings → Privacy & Security**, find the message like *"QwenPaw was blocked because it is from an unidentified developer"*, and click **Open Anyway** or **Allow**. - **Remove quarantine attribute (not recommended for most users)** In Terminal: `xattr -cr /Applications/QwenPaw.app` (or the path to the `.app` after unzipping). This clears the download quarantine flag; less safe than right-click → Open. ## CI `.github/workflows/desktop-release.yml`: - **Triggers**: Release publish or manual workflow_dispatch - **Windows**: Build console → temporary conda env + conda-pack → NSIS → upload artifact - **macOS**: Build console → temporary conda env + conda-pack → .app → zip → upload artifact - **Release**: When triggered by a release, uploads the Windows installer and macOS zip as release assets ## Script reference | File | Description | |------|-------------| | `build_common.py` | Create temporary conda env, install `qwenpaw[full]` from a wheel, conda-pack; produces archive. | | `build_macos.sh` | One-click: build wheel → build_common → unpack into QwenPaw.app; optional zip. | | `build_win.ps1` | One-click: build wheel → build_common → unpack → create VBS/BAT launchers → makensis installer. | | `desktop.nsi` | NSIS script: pack `dist/win-unpacked`, add icons, and create shortcuts. | | `assets/icon.ico` | Pre-generated Windows icon (installer and shortcuts). | | `assets/icon.icns` | Pre-generated macOS icon (app bundle). | --- ## File: scripts/pack/README_zh.md # QwenPaw Desktop 打包脚本 > ⚠️ **旧版（仅用于回滚）。** 这套基于 conda-pack 的打包脚本已被 **Tauri** > 桌面版构建取代（详见 `console/src-tauri/` 与 `scripts/pack-tauri/`），仅作 > 短期回滚保留，发布流程已不再使用。当前桌面应用请参考 > [桌面应用指南](https://qwenpaw.agentscope.io/docs/desktop)。 一键打包：脚本会先运行 `scripts/wheel_build.sh` 构建 **wheel** （包含 console 前端产物），再用 **临时 conda 环境** + **conda-pack** （不依赖当前开发环境）。依赖以 `pyproject.toml` 为准。 - **Windows**: wheel → conda-pack → 解压 → NSIS 安装包 (`.exe`) - **macOS**: wheel → conda-pack → 解压到 `.app` → 可选打 zip ## 系统要求 - **Windows**: Windows 10 或更高版本 - **macOS**: macOS 14 (Sonoma) 或更高版本，推荐 Apple Silicon (M1/M2/M3/M4) ## 前置 - **conda**（Miniconda/Anaconda）在 PATH - **Node.js / npm**（用于构建 console 前端） - （仅 Windows）**NSIS**：`makensis` 在 PATH - **图标**：预生成的 `icon.ico` (Windows) 和 `icon.icns` (macOS) 已包含在 `scripts/pack/assets/` 中 ## 一键打包 在**仓库根目录**执行： **macOS** ```bash bash ./scripts/pack/build_macos.sh # 产出: dist/QwenPaw.app CREATE_ZIP=1 bash ./scripts/pack/build_macos.sh # 同时生成 .zip ``` **Windows (PowerShell)** ```powershell ./scripts/pack/build_win.ps1 # 产出: dist/QwenPaw-Setup-.exe # 创建两个启动器： # - QwenPaw Desktop.vbs (静默启动，无终端窗口) # - QwenPaw Desktop (Debug).bat (显示终端，便于调试) ``` ## 从终端启动并查看日志（macOS） 如果双击 .app 会闪退，可以在终端里运行以查看完整报错和日志： ```bash # 在仓库根目录执行，强制只用打包环境（不用系统 conda / PYTHONPATH）。路径按需改。 APP_ENV="$(pwd)/dist/QwenPaw.app/Contents/Resources/env" PYTHONNOUSERSITE=1 PYTHONPATH= PYTHONHOME="$APP_ENV" "$APP_ENV/bin/python" -m qwenpaw desktop ``` `PYTHONNOUSERSITE=1` 可防止 Python 加载 `~/.local/lib/pythonX.Y/site-packages` 中的包，避免与打包环境冲突。所有标准输出和错误（包括 Python traceback）都会打在终端里；可加 `--log-level debug` 查看更详细日志。 若**双击** .app 没有任何窗口出现，启动器会把 stderr/stdout 写入 `~/.qwenpaw/desktop.log`，可打开该文件查看报错。 首次打开时，macOS 可能弹出「请求访问桌面的文件」：请点**允许**，否则部分功能可能不可用或窗口会关闭。 ## macOS：提示「无法验证开发者」/ Gatekeeper 拦截时怎么打开 用户从 Release 等渠道下载的 QwenPaw macOS 应用（zip 内的 .app）未经过 Apple 公证，可能看到「Apple 无法验证“QwenPaw”是否包含可能危害 Mac 安全或泄漏隐私的恶意软件」。可按以下方式打开： - **右键打开（推荐）** 在 QwenPaw 应用上 **右键（或 Control + 点击）** → 选 **「打开」** → 在弹窗里再点一次 **「打开」**。即表示你确认运行该应用，Gatekeeper 会放行，之后双击即可正常打开。 - **在系统设置里放行** 若仍被拦截，进入 **系统设置 → 隐私与安全性**，往下找到类似「已阻止使用 QwenPaw，因为无法验证开发者」的提示，点 **「仍要打开」** 或 **「允许」** 即可。 - **用终端去掉隔离属性（不推荐普通用户）** 在终端执行：`xattr -cr /Applications/QwenPaw.app`（或解压后 .app 的实际路径）。会去掉「从互联网下载」的隔离标记，一般就不再弹恶意软件提示，但不如「右键 → 打开」安全、可控。 ## CI `.github/workflows/desktop-release.yml`： - **触发**: Release 发布 或 手动 workflow_dispatch - **Windows**: 构建 console → 临时 conda 环境 + conda-pack → NSIS → 上传 artifact - **macOS**: 构建 console → 临时 conda 环境 + conda-pack → .app → zip → 上传 artifact - **Release**: 若由 release 触发，则把 Windows 安装包与 macOS zip 上传到该 Release 的附件 ## 脚本说明 | 文件 | 说明 | |------|------| | `build_common.py` | 创建临时 conda 环境，从 wheel 安装 `qwenpaw[full]`，conda-pack 产出归档 | | `build_macos.sh` | 一键：构建 wheel → build_common → 解压到 QwenPaw.app；可选打 zip | | `build_win.ps1` | 一键：构建 wheel → build_common → 解压 → 创建 VBS/BAT 启动器 → makensis 安装包 | | `desktop.nsi` | NSIS 脚本：打包 `dist/win-unpacked`，添加图标，创建快捷方式 | | `assets/icon.ico` | 预生成的 Windows 图标（安装包和快捷方式使用） | | `assets/icon.icns` | 预生成的 macOS 图标（应用包使用） | --- ## File: scripts/startup_profile/README.md # 🚀 QwenPaw Startup Performance Analyzer One-click analysis of QwenPaw startup performance, identify bottlenecks, and provide optimization suggestions. ## Quick Start ```bash # 1. Generate report python scripts/startup_profile/analyze.py # 2. Start local server to view (recommended) python scripts/startup_profile/serve.py ``` After execution: 1. Collect import time data 2. Collect function execution trace (optional) 3. Generate JSON data 4. View report via HTTP server **Note**: Due to browser security restrictions (CORS), opening HTML directly with `file://` protocol cannot load data. Please use `serve.py` or manually start an HTTP server: ```bash cd /path/to/QwenPaw python -m http.server 8000 # Visit: http://localhost:8000/scripts/startup_profile/output/report.html ``` ## Generated Files ``` output/ ├── importtime.log # Import time raw log ├── execution_trace.json # Function execution trace (if successful) ├── analysis.json # Analysis data (core) └── report.html # Visual report ⭐ ``` ## Report Features - **Import Time Analysis** - QwenPaw modules and third-party library import time ranking - **Function Execution Time** - Top 20 function execution time statistics - **Function Call Tree** - Complete function call hierarchy and timing (limited to 5 levels deep, top 10 calls per level) - **Interactive Charts** - Chart.js horizontal bar chart visualization - **Bilingual Support** - Chinese/English one-click toggle - **Performance Markers** - Auto-mark fast/medium/slow functions based on timing (green/yellow/red) ## How It Works 1. **Data Collection** - Use Python `-X importtime` to collect import time - Use `exec_tracer` to track function calls 2. **Data Analysis** - Parse log files - Categorize statistics (QwenPaw/third-party/stdlib) - Calculate percentages and performance metrics 3. **Visualization** - HTML reads JSON data - Interactive charts and tables - Supports search, sort, filter ## File Description - `analyze.py` - Data collection and analysis script - `viewer.html` - Visualization interface (bilingual) - `README.md` - Chinese documentation - `README_EN.md` - English documentation ## FAQ **Q: Why do results vary each run?** A: Import time is affected by system load. Run multiple times and take average. **Q: How to compare before/after optimization?** A: Save `output/` directory, re-run after optimization and compare. **Q: Function trace fails?** A: Normal, doesn't affect import analysis. Can use `exec_tracer` separately. ## Technical Details - Python 3.8+ - No extra dependencies (except QwenPaw itself) - Pure JSON data output - HTML runs standalone, viewable offline ## Related Tools - `src/qwenpaw/utils/startup_display.py` - Startup banner display --- **Version**: 2.0.0 **Author**: QwenPaw Team **Updated**: 2026-04-17 --- ## File: scripts/startup_profile/README_zh.md # 🚀 QwenPaw 启动性能分析工具 一键分析 QwenPaw 启动性能，识别瓶颈，提供优化建议。 ## 快速开始 ```bash # 1. 生成报告 python scripts/startup_profile/analyze.py # 2. 启动本地服务器查看（推荐） python scripts/startup_profile/serve.py ``` 执行后： 1. 收集 import 时间数据 2. 收集函数执行追踪（可选） 3. 生成 JSON 数据 4. 使用 HTTP 服务器查看报告 **注意**：由于浏览器安全限制（CORS），直接用 `file://` 协议打开 HTML 无法加载数据。 请使用 `serve.py` 或手动启动 HTTP 服务器： ```bash cd /path/to/QwenPaw python -m http.server 8000 # 访问: http://localhost:8000/scripts/startup_profile/output/report.html ``` ## 生成文件 ``` output/ ├── importtime.log # Import 时间原始日志 ├── execution_trace.json # 函数执行追踪（如果成功） ├── analysis.json # 分析数据（核心） └── report.html # 可视化报告 ⭐ ``` ## 报告功能 - **Import 时间分析** - QwenPaw 模块和第三方库导入耗时排名 - **函数执行时间** - Top 20 函数执行时间统计 - **函数调用树** - 完整的函数调用层级关系和耗时（限制深度 5 层，每层最多显示前 10 个调用） - **交互式图表** - Chart.js 横向柱状图可视化 - **双语支持** - 中英文一键切换 - **性能标记** - 根据耗时自动标记快/中/慢函数（绿/黄/红） ## 工作原理 1. **数据收集** - 使用 Python `-X importtime` 收集 import 时间 - 使用 `exec_tracer` 追踪函数调用 2. **数据分析** - 解析日志文件 - 分类统计（QwenPaw/第三方/标准库） - 计算占比和性能指标 3. **可视化展示** - HTML 读取 JSON 数据 - 交互式图表和表格 - 支持搜索、排序、过滤 ## 文件说明 - `analyze.py` - 数据收集和分析脚本 - `viewer.html` - 可视化界面（双语） - `README.md` - 中文文档 - `README_EN.md` - 英文文档 ## 常见问题 **Q: 为什么每次结果不同？** A: Import 时间受系统负载影响，建议多次运行取平均值。 **Q: 如何对比优化前后？** A: 保存 `output/` 目录，优化后重新运行对比。 **Q: 函数追踪失败怎么办？** A: 正常现象，不影响 import 分析。可单独使用 `exec_tracer`。 ## 技术细节 - Python 3.8+ - 无额外依赖（除了 QwenPaw 本身） - 纯 JSON 数据输出 - HTML 独立运行，可离线查看 ## 相关工具 - `src/qwenpaw/utils/startup_display.py` - 启动横幅显示 --- **版本**: 2.0.0 **作者**: QwenPaw Team **更新**: 2026-04-17 --- ## File: scripts/README.md # Scripts Run from **repo root**. ## Build wheel (with latest console) ```bash bash scripts/wheel_build.sh ``` - Builds the console frontend (`console/`), copies `console/dist` to `src/qwenpaw/console/dist`, then builds the wheel. Output: `dist/*.whl`. ## Build website ```bash bash scripts/website_build.sh ``` - Installs dependencies (pnpm or npm) and runs the Vite build. Output: `website/dist/`. ## Build Docker image ```bash bash scripts/docker_build.sh [IMAGE_TAG] [EXTRA_ARGS...] ``` - Default tag: `qwenpaw:latest`. Uses `deploy/Dockerfile` (multi-stage: builds console then Python app). - Example: `bash scripts/docker_build.sh myreg/qwenpaw:v1 --no-cache`. ## Run Test ```bash # Run all tests python scripts/run_tests.py # Run all unit tests python scripts/run_tests.py -u # Run unit tests for a specific module python scripts/run_tests.py -u providers # Run integration tests python scripts/run_tests.py -i # Run all tests and generate a coverage report python scripts/run_tests.py -a -c # Run tests in parallel (requires pytest-xdist) python scripts/run_tests.py -p # Show help python scripts/run_tests.py -h ``` --- ## File: website/public/docs/acp-integration.en.md # ACP Integration QwenPaw supports **ACP (Agent Client Protocol)** in two complementary ways: 1. **QwenPaw using ACP as a Tool**: QwenPaw connects to external ACP runners and uses them as delegated collaborators 2. **QwenPaw as an ACP Server**: external clients connect to QwenPaw over ACP This page explains both modes and the scenarios each one fits best. --- ## QwenPaw using ACP as a Tool In this mode, QwenPaw acts as an **ACP client / orchestrator**, connecting to **configured and enabled external ACP runners** and bringing them into the current session as delegated collaboration capabilities. The actual entry point for this mode is the built-in tool `delegate_external_agent`. It is intended for scenarios where QwenPaw needs to collaborate with other ACP-capable external agent runtimes, such as the built-in examples `opencode`, `qwen_code`, `claude_code`, and `codex`. For more ACP-compatible agents, see the official ACP agent list and integration guide: . In other words, QwenPaw does not directly talk to arbitrary external agents. It talks to runners that have been registered in ACP configuration, and it starts, continues, responds to, and closes delegated collaboration sessions through them. ### What this mode does In this mode, QwenPaw uses the built-in `delegate_external_agent` tool to: - start a session with an external ACP runner - send follow-up messages to that runner - respond to permission requests raised by that runner - close the delegated session when the work is complete Conceptually, this lets QwenPaw treat an external agent as a collaborative, tool-like capability while keeping QwenPaw as the primary orchestrator of the main conversation. ### How to configure external runners Before using an external runner, make sure you have installed an ACP-compatible external agent and completed any required login or API key setup so it can be launched and used normally from the command line. You can refer to the official ACP agent list here: . Once the command-line side is ready, you can configure a custom runner in QwenPaw or collaborate with one of the built-in runners directly. External runners must be configured and enabled on the **Workspace → ACP** page before they can be used by `delegate_external_agent`. The current ACP configuration UI supports these fields for each runner: - `enabled` - `command` - `args` - `env` - `trusted` - `tool_parse_mode` - `stdio_buffer_limit_bytes` Specifically: - `command` and `args` define the command and arguments used to launch the external runner; - `env` passes environment variables; - `tool_parse_mode` and `stdio_buffer_limit_bytes` control ACP output parsing and stdio buffering behavior. In most cases, the default values are fine and do not need to be changed. On Linux/macOS, `command` is usually the command that starts the external agent in ACP mode, such as `opencode` or `qwen`, or the command that launches the corresponding ACP plugin, such as `npx`. Put the remaining flags and arguments in `args`, such as `--acp` or `-y`. Each argument must be entered on its own line. The source code ships with these built-in runner examples: `opencode`, `qwen_code`, `claude_code`, and `codex`. You can also add custom runners on the ACP page as long as they can run via ACP and are configured correctly. On Windows, after confirming the external agent can be launched normally from the command line, set `command` to `cmd` and put `/c` as the first line in `args`, followed by the actual command and its arguments, again one per line. Example: After configuration, enable the `delegate_external_agent` tool in the toolbar. You can then explicitly specify which external agent you want to collaborate with in the conversation. ### Typical workflow A typical delegated ACP workflow looks like this: 1. Configure and enable a runner on the **Workspace → ACP** page. 2. In a conversation, call `delegate_external_agent(action="start", runner="...", message="...")` to start a new delegated session for that runner. 3. If you want to continue the collaboration, call `delegate_external_agent(action="message", runner="...", message="...")` to send follow-up instructions to the existing runner session. 4. If the external runner raises a permission request, first let the user choose from the options shown in the UI, then call `delegate_external_agent(action="respond", runner="...", message="")` to resume execution. Here, `message` must be the **exact option id** returned by that permission request. 5. After the delegated work is complete, call `delegate_external_agent(action="close", runner="...")` to close the runner session. You can pass task prompts such as "analyze the current working directory structure" or "write your self-introduction into a Markdown file" in `start` or `message`, but the underlying flow always maps to the same four actions: `start`, `message`, `respond`, and `close`. ### Supported delegated actions The built-in delegation flow supports these action types: | Action | Purpose | | --------- | ------------------------------------------------------------------ | | `start` | Start a new delegated ACP session | | `message` | Send a follow-up message to an existing delegated session | | `respond` | Reply to a pending permission request using the selected option id | | `close` | Close the delegated ACP session | ### Permission handling When an external ACP runner asks for permission, QwenPaw does **not** decide on the user's behalf. Instead, it: - pauses the delegated flow - shows the permission details and available options - waits for the user to choose how to proceed This keeps delegated ACP execution aligned with the same user-controlled safety model used elsewhere in QwenPaw. ### When to use ACP as a Tool Use this mode when: - you want QwenPaw to collaborate with another agent runtime - you have a specialized ACP-compatible external runner for a certain class of tasks - you want QwenPaw to remain the primary orchestrator while delegating part of the work outward ### ACP Tool vs MCP ACP as a Tool and MCP solve different problems: - **MCP** connects QwenPaw to external services and tool servers - **ACP as a Tool** connects QwenPaw to an external **agent** runtime If you need APIs, databases, filesystems, or service integrations, use **MCP**. If you need agent-to-agent collaboration, use **ACP as a Tool**. --- ## QwenPaw as an ACP Server In this mode, QwenPaw exposes itself as an [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/python-sdk) compliant agent service over stdio JSON-RPC. External clients, such as [Zed](https://zed.dev), [OpenCode](https://github.com/nicholasgasior/opencode), or any ACP-compatible editor, can connect to QwenPaw via the `qwenpaw acp` command and interact with it programmatically. ### Quick Start ```bash # Start QwenPaw as an ACP agent qwenpaw acp # Use a specific agent profile qwenpaw acp --agent mybot # Use a custom workspace directory qwenpaw acp --workspace /path/to/workspace # Enable debug logging to stderr qwenpaw acp --debug ``` The process communicates over stdin/stdout using the ACP JSON-RPC protocol. stderr is used for logging. ### Supported ACP Methods | Method | Description | | ------------------- | ------------------------------------------------------------ | | `initialize` | Handshake that returns agent capabilities and version info | | `new_session` | Create a new conversation session | | `load_session` | Load or attach to an existing session by ID | | `resume_session` | Resume a previously closed session | | `list_sessions` | List active sessions, optionally filtered by `cwd` | | `close_session` | Close and clean up a session | | `prompt` | Send a user message and stream back agent responses | | `set_session_model` | Switch the active LLM model, using `provider_id:model_id` | | `set_config_option` | Toggle session config options, such as the Tool Guard switch | | `cancel` | Cancel an in-progress `prompt` | ### Streaming Updates During a `prompt` call, the agent streams real-time updates back to the client via `session_update` notifications: | Update Type | When | | --------------------- | ------------------------------------------- | | `agent_message_chunk` | Agent text response (streaming) | | `agent_thought_chunk` | Agent internal reasoning or system messages | | `tool_call` | Tool invocation started | | `tool_call_update` | Tool execution completed with output | ### Declared Capabilities The agent declares the following capabilities during `initialize`: ```json { "load_session": true, "session_capabilities": { "close": {}, "list": {}, "resume": {} } } ``` ### Session Config Options When a new session is created, the agent returns config options that the client can change via `set_config_option`: | Config ID | Type | Category | Default | Options | | --------- | ------ | -------- | --------- | ------------------------------------------------------------------------------------------- | | `mode` | select | `mode` | `default` | `default`: normal mode with Tool Guard enabled; `bypassPermissions`: skip tool guard checks | ### Configuration The ACP agent resolves its configuration in the following order: 1. **CLI arguments**: `--agent` and `--workspace` take highest priority 2. **WORKING_DIR config**: read `agents.active_agent` from `config.json` inside `WORKING_DIR` (default `~/.qwenpaw`, or `~/.copaw` for legacy installations; overridable via the `QWENPAW_WORKING_DIR` environment variable) 3. **Defaults**: fall back to agent ID `"default"` and workspace directory `WORKING_DIR/workspaces/default/` --- ## ACP Server vs ACP Tool | Aspect | QwenPaw as an ACP Server | QwenPaw using ACP as a Tool | | -------------------- | --------------------------------------------- | ------------------------------------------------------ | | QwenPaw's role | Server / target agent | Client / orchestrator | | Connection direction | External client connects to QwenPaw | QwenPaw connects to an external runner | | Main purpose | Let editors or external clients drive QwenPaw | Let QwenPaw delegate work to another agent | | Typical entry point | `qwenpaw acp` | Delegation tool + ACP runner configuration | | Best for | Editor integration, programmatic control | Multi-agent collaboration, external specialist runners | --- ## Summary ACP in QwenPaw is not just one feature. It supports both directions: - **Expose QwenPaw outward** as an ACP server - **Reach outward from QwenPaw** to external ACP agents as delegated tools If you are integrating QwenPaw into another client, start with **ACP Server**. If you want QwenPaw to coordinate with another agent runtime, use **ACP as a Tool**. --- ## File: website/public/docs/acp-integration.zh.md # ACP 集成 QwenPaw 对 **ACP（Agent Client Protocol）** 提供两种互补的支持方式： 1. **QwenPaw 将 ACP 作为 Tool 使用**：QwenPaw 连接外部 ACP runner，并将其作为委托协作能力使用 2. **QwenPaw 作为 ACP Server**：外部客户端通过 ACP 连接到 QwenPaw 本页会同时介绍这两种模式，以及各自适合的使用场景。 --- ## QwenPaw 将 ACP 作为 Tool 使用 在这种模式下，QwenPaw 会作为 **ACP client / orchestrator**，连接**已配置并启用的外部 ACP runner**，并将它们接入当前会话，作为委托协作能力使用。 这类能力的实际调用入口是内置工具 `delegate_external_agent`。它适用于你希望 QwenPaw 与其他支持 ACP 的外部 agent runtime 协作的场景，例如源码中默认内置的 `opencode`、`qwen_code`、`claude_code`、`codex`。这些 agent 可参考 ACP 官方的 Agent 列表与接入说明：。换句话说，QwenPaw 不是“直接和任意外部 agent 交互”，而是通过 ACP 配置中已注册的 runner，在会话内发起、继续、响应和关闭一次委托式协作。 ### 这种模式能做什么 在这种模式下，QwenPaw 会通过内置的 `delegate_external_agent` 工具来： - 启动一个外部 ACP runner 会话 - 向该 runner 发送后续消息 - 响应该 runner 发起的权限请求 - 在任务完成后关闭委托会话 从概念上看，这让 QwenPaw 可以把一个外部 agent 当作“可协作的工具能力”来使用，同时仍然由 QwenPaw 负责主会话编排。 ### 如何配置外部 runner 在使用外部 runner 之前，请先安装一个支持 ACP 协议的外部 agent，并完成登录、API Key 等必要配置，确保它可以在命令行中正常启动和使用。可参考 ACP 官方提供的 agent 列表：。 命令行侧准备完成后，你可以在 QwenPaw 中配置自定义 runner，或直接使用内置 runner 与其协作。 外部 runner 需要先在 **Workspace → ACP** 页面中完成配置并启用，之后才能被 `delegate_external_agent` 调用。 当前 ACP 配置页支持为每个 runner 设置以下字段： - `enabled` - `command` - `args` - `env` - `trusted` - `tool_parse_mode` - `stdio_buffer_limit_bytes` 其中： - `command` 与 `args` 用于定义外部 runner 的启动命令及参数； - `env` 用于传递环境变量； - `tool_parse_mode` 与 `stdio_buffer_limit_bytes` 用于控制 ACP 输出解析方式及 stdio 缓冲行为。通常保持默认值即可，一般不需要修改。 对于 Linux/macOS，`command` 一般填写外部 agent 以 ACP 模式启动时使用的命令，例如 `opencode`、`qwen`，或者相应 ACP 插件的启动命令，例如 `npx`；`args` 则填写后续参数，例如 `--acp`、`-y` 等。**注意每个参数都需要单独占一行**。源码中默认内置了这些 runner 示例：`opencode`、`qwen_code`、`claude_code`、`codex`。你也可以在 ACP 页面中添加自定义 runner，只要它能够以 ACP 方式运行并被正确配置即可。 对于 Windows，在确保外部 agent 可以在命令行中正常启动和使用后，`command` 字段填写 `cmd`，`args` 的第一行填写 `/c`，后续再逐行填写真正要执行的命令及参数。**注意每个参数都需要单独占一行**。示例如下： 配置完成后，在工具栏中启用 `delegate_external_agent` 工具。 随后，你就可以在对话中明确指定要与哪个外部 agent 进行协作。 ### 典型工作流 一个典型的委托式 ACP 工作流如下： 1. 在 **Workspace → ACP** 页面中配置并启用一个 runner。 2. 在会话中调用 `delegate_external_agent(action="start", runner="...", message="...")`，为该 runner 启动一条新的委托会话。 3. 如果需要继续协作，调用 `delegate_external_agent(action="message", runner="...", message="...")`，向已开启的 runner 会话发送后续消息。 4. 如果外部 runner 发起权限请求，先由用户从界面展示的选项中做出选择，再调用 `delegate_external_agent(action="respond", runner="...", message="")` 恢复执行。这里的 `message` 必须是权限请求中返回的**精确 option id**。 5. 委托任务完成后，调用 `delegate_external_agent(action="close", runner="...")` 关闭该 runner 会话。 你也可以在 `start` 或 `message` 时传入类似“请分析当前工作目录结构”或“请把你的自我介绍写入一个 Markdown 文件”这样的任务说明，但底层流程始终对应上述四种 action：`start`、`message`、`respond`、`close`。 ### 支持的委托动作 当前委托流程支持以下动作类型： | 动作 | 用途 | | --------- | ----------------------------------------- | | `start` | 启动新的委托 ACP 会话 | | `message` | 向已有委托会话发送后续消息 | | `respond` | 使用选定的 option id 响应待处理的权限请求 | | `close` | 关闭委托 ACP 会话 | ### 权限处理 当外部 ACP runner 请求权限时，QwenPaw **不会替用户做决定**。 相反，它会： - 暂停当前委托流程 - 展示权限详情和可选项 - 等待用户明确选择如何继续 这样可以让委托式 ACP 执行与 QwenPaw 其他能力保持一致的用户可控安全模型。 ### 什么时候使用 ACP as Tool 以下场景适合使用这种模式： - 你希望 QwenPaw 与另一个 agent runtime 协作 - 你有一个专门处理某类任务的 ACP-compatible 外部 runner - 你希望由 QwenPaw 作为主控编排者，把部分工作委托给外部 agent ### ACP Tool 与 MCP 的区别 ACP as Tool 和 MCP 解决的问题并不相同： - **MCP**：让 QwenPaw 连接外部服务和工具服务器 - **ACP as Tool**：让 QwenPaw 连接外部 **agent** runtime 如果你需要接入 API、数据库、文件系统或服务能力，优先使用 **MCP**。 如果你需要 agent 与 agent 之间的协作，优先使用 **ACP as Tool**。 --- ## QwenPaw as ACP Server 在这种模式下，QwenPaw 会通过 stdio JSON-RPC 将自己暴露为一个符合 [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol/python-sdk) 规范的智能体服务。外部客户端，如 [Zed](https://zed.dev)、[OpenCode](https://github.com/nicholasgasior/opencode) 或任何兼容 ACP 的编辑器，都可以通过 `qwenpaw acp` 命令连接到 QwenPaw，并以编程方式与之交互。 ### 快速开始 ```bash # 启动 QwenPaw 作为 ACP 智能体 qwenpaw acp # 使用指定的智能体配置 qwenpaw acp --agent mybot # 使用自定义工作区目录 qwenpaw acp --workspace /path/to/workspace # 启用调试日志（输出到 stderr） qwenpaw acp --debug ``` 进程通过 stdin/stdout 使用 ACP JSON-RPC 协议通信，stderr 用于日志输出。 ### 支持的 ACP 方法 | 方法 | 说明 | | ------------------- | ------------------------------------------------ | | `initialize` | 握手，返回智能体能力和版本信息 | | `new_session` | 创建新的会话 | | `load_session` | 按 ID 加载或接入已有会话 | | `resume_session` | 恢复之前关闭的会话 | | `list_sessions` | 列出活跃会话，可按 `cwd` 过滤 | | `close_session` | 关闭并清理会话 | | `prompt` | 发送用户消息，并流式返回智能体响应 | | `set_session_model` | 切换活跃 LLM 模型，格式为 `provider_id:model_id` | | `set_config_option` | 切换会话配置选项，例如 Tool Guard 开关 | | `cancel` | 取消正在进行的 `prompt` | ### 流式更新 在 `prompt` 调用过程中，智能体会通过 `session_update` 通知向客户端实时推送更新： | 更新类型 | 触发时机 | | --------------------- | ------------------------ | | `agent_message_chunk` | 智能体文本响应（流式） | | `agent_thought_chunk` | 智能体内部推理或系统消息 | | `tool_call` | 工具调用开始 | | `tool_call_update` | 工具执行完成并返回结果 | ### 声明的能力 智能体会在 `initialize` 阶段声明以下能力： ```json { "load_session": true, "session_capabilities": { "close": {}, "list": {}, "resume": {} } } ``` ### 会话配置选项 创建新会话时，智能体会返回可通过 `set_config_option` 切换的配置项： | 配置 ID | 类型 | 类别 | 默认值 | 可选值 | | ------- | ------ | ------ | --------- | --------------------------------------------------------------------------- | | `mode` | select | `mode` | `default` | `default`：正常模式，启用 Tool Guard；`bypassPermissions`：跳过工具安全检查 | ### 配置 ACP 智能体按以下优先级解析配置： 1. **CLI 参数**：`--agent` 和 `--workspace` 优先级最高 2. **WORKING_DIR 配置**：从 `WORKING_DIR` 内的 `config.json` 中读取 `agents.active_agent`（默认 `~/.qwenpaw`，旧版安装为 `~/.copaw`；可通过 `QWENPAW_WORKING_DIR` 环境变量覆盖） 3. **默认值**：回退到智能体 ID `"default"` 和工作区目录 `WORKING_DIR/workspaces/default/` --- ## ACP Server vs ACP Tool | 维度 | QwenPaw as ACP Server | QwenPaw using ACP as Tool | | -------------- | -------------------------------- | ----------------------------------- | | QwenPaw 的角色 | Server / 被连接的智能体 | Client / 编排者 | | 连接方向 | 外部客户端连接 QwenPaw | QwenPaw 连接外部 runner | | 主要目的 | 让编辑器或外部客户端驱动 QwenPaw | 让 QwenPaw 把工作委托给另一个 agent | | 典型入口 | `qwenpaw acp` | delegation tool + ACP runner 配置 | | 适用场景 | 编辑器集成、程序化控制 | 多智能体协作、外部专用 runner | --- ## 总结 ACP 在 QwenPaw 中并不是单一能力，而是支持两个方向： - **向外暴露 QwenPaw**：作为 ACP server - **从 QwenPaw 向外协作**：把外部 ACP agent 当作委托工具使用 如果你是要把 QwenPaw 接入另一个客户端，优先看 **ACP Server**。 如果你是希望 QwenPaw 去协调另一个 agent runtime，优先看 **ACP as Tool**。 --- ## File: website/public/docs/api-tutorial.en.md # RESTful API This document will guide you through using the RESTful API to interact with QwenPaw Agents. > **Protocol Details**: QwenPaw's API is based on an extension of the AgentScope Runtime protocol. For more details, see: > [AgentScope Runtime Protocol Documentation (English)](https://runtime.agentscope.io/en/protocol.html) > ⚠️ **Security Warning**: > If your QwenPaw instance is **exposed to the public internet**, strongly recommend enabling [Web Login Authentication](./security#web-authentication)! > Public instances without authentication pose serious security risks, allowing anyone to access and control your Agents. > See the [Web Authentication Token](#web-authentication-token-optional) section at the end of this document. ## Overview QwenPaw provides a RESTful API interface that allows you to interact with Agents via HTTP requests. Through the API, you can: - Send messages to Agents and receive responses - Manage multiple Agent instances - Integrate with different channels ## API Endpoint The main chat interface is: ``` POST /api/console/chat ``` **Important**: Note the path is `/api/console/chat` not `/console/chat` - all APIs are under the `/api` prefix. ## Authentication ### Agent ID (Required) Specify the Agent to interact with via the `X-Agent-Id` header: ```bash -H "X-Agent-Id: default" ``` **Getting Your Agent ID**: 1. Check the currently selected Agent in the top-left corner of Console 2. The Agent ID is typically displayed in the Agent selector 3. The default Agent ID is `default` ### Localhost Auto-Bypass Authentication ⚠️ **Important Notice**: - **Requests from `localhost` (127.0.0.1 or ::1) automatically bypass Web authentication** - This is designed for local development and CLI tools (`qwenpaw`) convenience - Even if Web authentication is enabled, local requests do **NOT** require an `Authorization` token - If accessing from a **remote machine**, you must provide a valid authentication token **Examples**: ```bash # Local request - No Authorization token needed curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{"input": [...]}' # Remote request - Authorization token required curl -X POST http://your-server.com:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "X-Agent-Id: default" \ -d '{"input": [...]}' ``` > **Tip**: If [Web Login Authentication](./security#web-authentication) is enabled and you're accessing remotely, you'll need to provide an authentication token. See the [Web Authentication Token](#web-authentication-token-optional) section at the end of this document. ## Request Format The API uses a specific message format, similar to OpenAI's message format: ```json { "input": [ { "role": "user", "content": [ { "type": "text", "text": "Your message here" } ] } ], "session_id": "my-session", "user_id": "user-001", "channel": "console" } ``` ### Parameter Explanation - **input** (required): Message array - `role`: Role, typically "user" - `content`: Content array - `type`: Content type, typically "text" - `text`: Actual text content - **session_id** (optional): Session ID for maintaining context continuity - **user_id** (optional): User ID to identify different users - **channel** (recommended): Channel name, recommend setting to "console" ## Making API Calls with cURL ### Basic Example ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [ { "type": "text", "text": "Hello, please introduce yourself" } ] } ], "session_id": "my-session", "user_id": "my-user", "channel": "console" }' \ --no-buffer ``` ### Parameter Explanation - **URL**: `http://localhost:8088/api/console/chat` (modify if deployed elsewhere) - **Headers**: - `Content-Type: application/json`: Specifies JSON format for the request body - `X-Agent-Id: default`: Specifies the Agent ID, defaults to `default` - **--no-buffer**: Disables buffering for real-time streaming response ### Complete Example ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [ { "type": "text", "text": "Please summarize today'\''s tasks for me" } ] } ], "session_id": "my-session-001", "user_id": "user-001", "channel": "console" }' \ --no-buffer ``` ## Response Format The API returns **Server-Sent Events (SSE)** streaming responses, with each event prefixed with `data:`: ``` data: {"sequence_number":0,"object":"response","status":"created",...} data: {"sequence_number":1,"object":"response","status":"in_progress",...} data: {"sequence_number":2,"object":"response","status":"in_progress","output":[{"role":"assistant","content":[{"type":"text","text":"Hello! I'm QwenPaw..."}]}],...} data: {"sequence_number":3,"object":"response","status":"completed",...} ``` ### Response Field Explanation - **sequence_number**: Event sequence number - **object**: Object type, typically "response" - **status**: Status - `created`: Created - `in_progress`: In progress - `completed`: Completed - `failed`: Failed - **output**: Output content (included during processing and completion) - `role`: Role, typically "assistant" - `content`: Content array - `type`: Content type - `text`: Text content - **error**: Error information (included on failure) - **session_id**: Session ID - **usage**: Token usage statistics (included on completion) ## Multi-turn Conversation QwenPaw automatically manages conversation context through `session_id` and `user_id`. Simply use the same `session_id` across different requests, and the system will automatically save and load conversation history: **First turn**: ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [{"type": "text", "text": "My name is Alice"}] } ], "session_id": "my-session-001", "user_id": "user-001", "channel": "console" }' ``` **Second turn** (using the same `session_id`): ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [{"type": "text", "text": "Do you remember my name?"}] } ], "session_id": "my-session-001", "user_id": "user-001", "channel": "console" }' ``` **Important**: - No need to include message history in `input` - the system automatically loads context based on `session_id` - Keep `session_id` and `user_id` consistent to maintain conversation continuity ## Error Handling ### Common Errors #### 405 Method Not Allowed ``` {"detail":"Method Not Allowed"} ``` **Solutions**: - Confirm you're using the `POST` method - Verify the URL path is correct: `/api/console/chat` (note the `/api` prefix) #### 400 Bad Request ```json { "detail": "Validation error" } ``` **Solutions**: - Check the request body format is correct - Ensure the `input` field exists and is properly formatted - Verify JSON format is valid #### 404 Agent Not Found ```json { "detail": "Agent not found" } ``` **Solutions**: - Check the value of the `X-Agent-Id` header - Confirm the Agent has been created in Console #### 503 Channel Not Found ```json { "detail": "Channel Console not found" } ``` **Solutions**: - Confirm the Console channel is enabled - Check channel status in Console → Settings → Channels ## Complete Python Example Using standard library `urllib` and `json` to handle SSE streams: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### Using requests Library (Recommended) If you have the `requests` library installed, you can use this more concise code: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Complete JavaScript Example Using the `fetch` API in Node.js: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## Best Practices 1. **Session Management**: Use consistent `session_id` to maintain conversation context 2. **Error Handling**: Always handle network errors and API error responses 3. **Stream Processing**: Use streaming reads to avoid memory issues 4. **Connection Timeout**: Set reasonable timeout values to avoid long waits 5. **Retry Mechanism**: Implement retry logic with exponential backoff 6. **Logging**: Log API calls for debugging and monitoring ## Advanced Usage ### Multi-Agent Switching Interact with different Agents by changing the `X-Agent-Id` header: ```bash # Chat with Agent 1 curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: agent-1" \ -d '{"input":[{"role":"user","content":[{"type":"text","text":"Hello"}]}],"channel":"console"}' # Chat with Agent 2 curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: agent-2" \ -d '{"input":[{"role":"user","content":[{"type":"text","text":"Hello"}]}],"channel":"console"}' ``` ### Web Authentication Token (Optional) If [Web Login Authentication](./security#web-authentication) is enabled (`QWENPAW_AUTH_ENABLED=true`), all API requests require an authentication token. #### Register Account **First-time setup requires registering an admin account** (QwenPaw uses single-user mode): ```bash curl -X POST http://localhost:8088/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123" }' ``` **Response Example**: ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "username": "admin" } ``` **Register with Custom Token Expiration**: ```bash # Register and get a permanent token curl -X POST http://localhost:8088/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123", "expires_in": 0 }' ``` **Important Notes**: - Registration endpoint can only be called once (single-user mode) - Registration returns a login token immediately - Returns `{"detail":"User already registered"}` error if a user already exists - Supports custom token expiration via `expires_in` parameter (same as login) **If you need to re-register** (e.g., forgot password or want to change account): Method 1: Use CLI to reset password ```bash qwenpaw auth reset-password ``` Method 2: Delete auth file and re-register ```bash # Delete auth file rm ~/.qwenpaw.secret/auth.json # Or use QWENPAW_SECRET_DIR environment variable rm "${QWENPAW_SECRET_DIR}/auth.json" # Restart QwenPaw and re-register qwenpaw app ``` **Docker Deployment**: ```bash # Enter container to delete auth file docker exec -it rm /app/working.secret/auth.json # Or use CLI to reset password docker exec -it qwenpaw auth reset-password ``` **Auto-Registration** (Optional): You can also auto-create an account via environment variables when starting QwenPaw: ```bash export QWENPAW_AUTH_ENABLED=true export QWENPAW_AUTH_USERNAME=admin export QWENPAW_AUTH_PASSWORD=admin123 qwenpaw app ``` This eliminates the need to manually call the registration API. #### Obtaining an Authentication Token **After registration, use the login API to get a token** ```bash curl -X POST http://localhost:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123" }' ``` **Response Example**: ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "username": "admin" } ``` **Customize Token Expiration**: You can specify token expiration time using the `expires_in` parameter (in seconds): ```bash # Request a 30-day token curl -X POST http://localhost:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123", "expires_in": 2592000 }' # Request a permanent token (100-year validity) curl -X POST http://localhost:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123", "expires_in": 0 }' ``` **Common Expiration Values**: - `604800` = 7 days (default) - `2592000` = 30 days - `31536000` = 1 year - `0` or `-1` = permanent token (100 years) **Step 2: Use Token in API Requests** Add the returned `token` to the `Authorization` header: ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [{"type": "text", "text": "Hello"}] } ], "session_id": "my-session", "user_id": "my-user", "channel": "console" }' ``` #### Token Characteristics - **Validity**: - Default: 7 days - Customizable via `expires_in` parameter (supports permanent tokens) - Maximum: 100 years - **Format**: HMAC-SHA256 signed token - **Storage**: Store securely, do not hardcode in code - **Local Bypass**: Requests from `127.0.0.1` or `::1` automatically skip authentication - **Multiple Tokens**: - ⚠️ Each login creates a new token; old tokens are NOT automatically revoked - Multiple tokens can be used simultaneously if they are valid and not expired - If a token is compromised, you need to manually revoke all tokens #### Revoking Tokens If you need to invalidate tokens (e.g., logout, token leak, or security incident): **Method 1: Revoke a Single Token** (Recommended for logout or specific device revocation) ```bash # Revoke current token (logout current session) curl -X POST http://localhost:8088/api/auth/revoke-token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{}' # Revoke a specific token (e.g., leaked token) curl -X POST http://localhost:8088/api/auth/revoke-token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "token": "eyJhbGciOi..." }' ``` **Response Example**: ```json { "message": "Current token has been revoked. Please login again.", "revoked": true, "revoked_current_token": true } ``` **Method 2: Revoke All Tokens** (For security incidents or password reset) ```bash curl -X POST http://localhost:8088/api/auth/revoke-all-tokens \ -H "Authorization: Bearer " ``` **Response Example**: ```json { "message": "All tokens have been revoked. Please login again.", "revoked": true } ``` **Method 3: Change Password** (Also revokes all tokens) Changing your password automatically rotates the JWT secret, invalidating all old tokens: ```bash curl -X POST http://localhost:8088/api/auth/update-profile \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "current_password": "old_password", "new_password": "new_password" }' ``` **Comparison of Revocation Methods**: | Method | Scope | Advantages | Disadvantages | Use Cases | | ------------------- | ------ | --------------------------------------------- | ----------------------------- | --------------------------------- | | Revoke Single Token | Single | Precise control, doesn't affect other devices | Need to know token content | Logout, revoke specific device | | Revoke All Tokens | All | Invalidates all sessions at once | All devices need re-login | Security incidents, password leak | | Change Password | All | Updates password and revokes tokens | Need to remember old password | Regular password updates | | Delete auth file | All | Complete reset (including password) | Requires server access | Full system reset | **Important Notes**: - After revocation, all clients must re-login to get new tokens - Revocation is irreversible - Recommended to revoke immediately when tokens are compromised or devices are lost - If using permanent tokens (`expires_in: 0`), strongly recommend periodic manual revocation and reissuance #### Disabling Authentication If you don't want to use Web authentication, you can disable it: **Method 1: Remove Environment Variable** ```bash # Linux / macOS unset QWENPAW_AUTH_ENABLED qwenpaw app # Windows (CMD) set QWENPAW_AUTH_ENABLED= qwenpaw app # Windows (PowerShell) Remove-Item Env:\QWENPAW_AUTH_ENABLED qwenpaw app ``` **Method 2: Docker Deployment** Remove the `-e QWENPAW_AUTH_ENABLED=true` parameter: ```bash docker run -p 127.0.0.1:8088:8088 \ -v qwenpaw-data:/app/working \ -v qwenpaw-secrets:/app/working.secret \ -v qwenpaw-backups:/app/working.backups \ agentscope/qwenpaw:latest ``` **Important**: - After disabling authentication, all API requests **do not need** the `Authorization` header - If authentication is **not enabled**, no `Authorization` header is needed - Check authentication status: `GET /api/auth/status` ## Troubleshooting ### Cannot Connect to Server Verify QwenPaw service is running: ```bash # Check service status curl http://localhost:8088/api/version ``` ### Response Interrupted If streaming response is interrupted, check: 1. Network connection stability 2. Server is running properly 3. Model configuration is correct ### Model Execution Failed If you see `MODEL_EXECUTION_FAILED` error: 1. Confirm models are properly configured in Console → Settings → Models 2. Check if API Key is valid 3. Verify model name is correct 4. Check the error details file (path provided in error message) ## Related Documentation - [Console Guide](./console) - [Security Settings](./security) - [Multi-Agent](./multi-agent) - [Channels Configuration](./channels) ## Getting Help If you encounter issues using the API: 1. Check the [FAQ](./faq) for common questions 2. Join the [Community](./community) for assistance 3. Submit an [Issue](https://github.com/agentscope-ai/QwenPaw/issues) on GitHub --- ## File: website/public/docs/api-tutorial.zh.md # RESTful API 接口 本文档将指导你如何使用 RESTful API 调用 QwenPaw 的 Agent。 > **协议详情**：QwenPaw 的 API 基于 AgentScope Runtime 协议的拓展。更多详细信息请参考： > [AgentScope Runtime 协议文档（中文）](https://runtime.agentscope.io/zh/protocol.html) > ⚠️ **安全提醒**： > 如果您的 QwenPaw 实例对**公网开放**，强烈建议启用 [Web 登录认证](./security#Web-登录认证)！ > 未启用认证的公网实例存在严重安全风险，任何人都可以访问和控制您的 Agent。 > 详见文档末尾的 [Web 认证令牌](#web-认证令牌可选) 章节。 ## 概述 QwenPaw 提供了 RESTful API 接口，允许你通过 HTTP 请求与 Agent 进行交互。通过 API，你可以： - 发送消息给 Agent 并获取回复 - 管理多个 Agent 实例 - 与不同的频道集成 ## API 端点 主要的聊天接口为： ``` POST /api/console/chat ``` **重要提示**：请注意路径是 `/api/console/chat` 而不是 `/console/chat`，所有 API 都在 `/api` 前缀下。 ## 认证 ### Agent ID（必需） 通过 `X-Agent-Id` 头部指定要交互的 Agent： ```bash -H "X-Agent-Id: default" ``` **获取 Agent ID**： 1. 在 Console 左上角查看当前选中的 Agent 2. Agent ID 通常显示在 Agent 选择器中 3. 默认的 Agent ID 为 `default` ### Localhost 自动免认证 ⚠️ **重要提示**： - **来自 `localhost` (127.0.0.1 或 ::1) 的请求会自动跳过 Web 认证** - 这是为了方便本地开发和 CLI 工具（`qwenpaw`）使用 - 即使启用了 Web 认证，本地请求也**不需要**提供 `Authorization` 令牌 - 如果从**远程机器**访问，则必须提供有效的认证令牌 **示例**： ```bash # 本地请求 - 不需要 Authorization 令牌 curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{"input": [...]}' # 远程请求 - 需要 Authorization 令牌 curl -X POST http://your-server.com:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -H "X-Agent-Id: default" \ -d '{"input": [...]}' ``` > **提示**：如果启用了 [Web 登录认证](./security#Web-登录认证)并从远程访问，需要提供身份验证令牌。详见文档末尾的 [Web 认证令牌](#web-认证令牌可选) 部分。 ## 请求格式 API 使用特定的消息格式，与 OpenAI 的消息格式类似： ```json { "input": [ { "role": "user", "content": [ { "type": "text", "text": "你的消息内容" } ] } ], "session_id": "my-session", "user_id": "user-001", "channel": "console" } ``` ### 参数说明 - **input**（必需）：消息数组 - `role`: 角色，通常为 "user" - `content`: 内容数组 - `type`: 内容类型，通常为 "text" - `text`: 实际的文本内容 - **session_id**（可选）：会话 ID，用于维持上下文连续性 - **user_id**（可选）：用户 ID，用于标识不同的用户 - **channel**（推荐）：频道名称，建议设置为 "console" ## 使用 cURL 调用 API ### 基本示例 ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [ { "type": "text", "text": "你好，请介绍一下自己" } ] } ], "session_id": "my-session", "user_id": "my-user", "channel": "console" }' \ --no-buffer ``` ### 参数说明 - **URL**：`http://localhost:8088/api/console/chat`（如果部署在其他地址，请相应修改） - **Headers**： - `Content-Type: application/json`：指定请求体为 JSON 格式 - `X-Agent-Id: default`：指定 Agent ID，默认为 `default` - **--no-buffer**：禁用缓冲，实时显示流式响应 ### 完整示例 ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [ { "type": "text", "text": "帮我总结一下今天的任务" } ] } ], "session_id": "my-session-001", "user_id": "user-001", "channel": "console" }' \ --no-buffer ``` ## 响应格式 API 返回 **Server-Sent Events (SSE)** 流式响应，每个事件以 `data:` 开头： ``` data: {"sequence_number":0,"object":"response","status":"created",...} data: {"sequence_number":1,"object":"response","status":"in_progress",...} data: {"sequence_number":2,"object":"response","status":"in_progress","output":[{"role":"assistant","content":[{"type":"text","text":"你好！我是 QwenPaw..."}]}],...} data: {"sequence_number":3,"object":"response","status":"completed",...} ``` ### 响应字段说明 - **sequence_number**: 事件序号 - **object**: 对象类型，通常为 "response" - **status**: 状态 - `created`: 已创建 - `in_progress`: 处理中 - `completed`: 已完成 - `failed`: 失败 - **output**: 输出内容（处理中和完成时包含） - `role`: 角色，通常为 "assistant" - `content`: 内容数组 - `type`: 内容类型 - `text`: 文本内容 - **error**: 错误信息（失败时包含） - **session_id**: 会话 ID - **usage**: 令牌使用统计（完成时包含） ## 多轮对话 QwenPaw 通过 `session_id` 和 `user_id` 自动管理对话上下文。只需在不同的请求中使用相同的 `session_id`，系统会自动保存和加载对话历史： **第一轮对话**： ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [{"type": "text", "text": "我的名字是小明"}] } ], "session_id": "my-session-001", "user_id": "user-001", "channel": "console" }' ``` **第二轮对话**（使用相同的 `session_id`）： ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [{"type": "text", "text": "你还记得我的名字吗？"}] } ], "session_id": "my-session-001", "user_id": "user-001", "channel": "console" }' ``` **重要提示**： - 无需在 `input` 中包含历史消息，系统会自动基于 `session_id` 加载上下文 - 保持 `session_id` 和 `user_id` 一致即可维持对话连续性 ## 错误处理 ### 常见错误 #### 405 Method Not Allowed ``` {"detail":"Method Not Allowed"} ``` **解决方法**： - 确认使用的是 `POST` 方法 - 确认 URL 路径正确：`/api/console/chat`（注意 `/api` 前缀） #### 400 Bad Request ```json { "detail": "Validation error" } ``` **解决方法**： - 检查请求体格式是否正确 - 确认 `input` 字段存在且格式正确 - 验证 JSON 格式有效 #### 404 Agent Not Found ```json { "detail": "Agent not found" } ``` **解决方法**： - 检查 `X-Agent-Id` 头部的值 - 确认该 Agent 已在 Console 中创建 #### 503 Channel Not Found ```json { "detail": "Channel Console not found" } ``` **解决方法**： - 确认 Console 频道已启用 - 在 Console → Settings → Channels 中检查频道状态 ## 完整 Python 示例 使用标准库 `urllib` 和 `json` 处理 SSE 流： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 使用 requests 库（推荐） 如果你安装了 `requests` 库，可以使用以下更简洁的代码： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 完整 JavaScript 示例 在 Node.js 中使用 `fetch` API： ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 最佳实践 1. **会话管理**：使用一致的 `session_id` 来维持对话上下文 2. **错误处理**：始终处理网络错误和 API 错误响应 3. **流式处理**：使用流式读取避免内存问题 4. **连接超时**：设置合理的超时时间，避免长时间等待 5. **重试机制**：实现指数退避的重试逻辑 6. **日志记录**：记录 API 调用日志，便于调试和监控 ## 进阶用法 ### 多 Agent 切换 与不同的 Agent 交互只需更改 `X-Agent-Id` 头部： ```bash # 与 Agent 1 对话 curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: agent-1" \ -d '{"input":[{"role":"user","content":[{"type":"text","text":"你好"}]}],"channel":"console"}' # 与 Agent 2 对话 curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "X-Agent-Id: agent-2" \ -d '{"input":[{"role":"user","content":[{"type":"text","text":"你好"}]}],"channel":"console"}' ``` ### Web 认证令牌（可选） 如果启用了 [Web 登录认证](./security#Web-登录认证)（`QWENPAW_AUTH_ENABLED=true`），所有 API 请求都需要提供身份验证令牌。 #### 注册账号 **首次使用需要先注册管理员账号**（QwenPaw 采用单用户模式）： ```bash curl -X POST http://localhost:8088/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123" }' ``` **响应示例**： ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "username": "admin" } ``` **注册时指定令牌有效期**： ```bash # 注册并获取永久令牌 curl -X POST http://localhost:8088/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123", "expires_in": 0 }' ``` **注意事项**： - 注册接口只能调用一次（单用户模式） - 注册成功后会直接返回登录令牌 - 如果已有用户，会返回 `{"detail":"User already registered"}` 错误 - 支持通过 `expires_in` 参数自定义令牌有效期（同登录接口） **如果需要重新注册**（例如忘记密码或想更换账号）： 方法 1：使用 CLI 重置密码 ```bash qwenpaw auth reset-password ``` 方法 2：删除认证文件后重新注册 ```bash # 删除认证文件 rm ~/.qwenpaw.secret/auth.json # 或者使用 QWENPAW_SECRET_DIR 环境变量 rm "${QWENPAW_SECRET_DIR}/auth.json" # 重启 QwenPaw 后重新注册 qwenpaw app ``` **Docker 部署**： ```bash # 进入容器删除认证文件 docker exec -it <容器名> rm /app/working.secret/auth.json # 或者使用 CLI 重置密码 docker exec -it <容器名> qwenpaw auth reset-password ``` **自动注册**（可选）： 你也可以在启动 QwenPaw 时通过环境变量自动创建账号： ```bash export QWENPAW_AUTH_ENABLED=true export QWENPAW_AUTH_USERNAME=admin export QWENPAW_AUTH_PASSWORD=admin123 qwenpaw app ``` 这样就无需手动调用注册 API。 #### 获取认证令牌 **注册后，使用登录 API 获取令牌** ```bash curl -X POST http://localhost:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123" }' ``` **响应示例**： ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "username": "admin" } ``` **自定义令牌有效期**： 你可以通过 `expires_in` 参数指定令牌的有效时长（单位：秒）： ```bash # 申请 30 天有效期的令牌 curl -X POST http://localhost:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123", "expires_in": 2592000 }' # 申请永久令牌（100 年有效期） curl -X POST http://localhost:8088/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "username": "admin", "password": "admin123", "expires_in": 0 }' ``` **常用有效期**： - `604800` = 7 天（默认） - `2592000` = 30 天 - `31536000` = 1 年 - `0` 或 `-1` = 永久令牌（100 年） **步骤 2：在 API 请求中使用令牌** 将返回的 `token` 添加到 `Authorization` 头部： ```bash curl -X POST http://localhost:8088/api/console/chat \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "X-Agent-Id: default" \ -d '{ "input": [ { "role": "user", "content": [{"type": "text", "text": "你好"}] } ], "session_id": "my-session", "user_id": "my-user", "channel": "console" }' ``` #### 令牌特性 - **有效期**： - 默认：7 天 - 可通过 `expires_in` 参数自定义（支持永久令牌） - 最长：100 年 - **格式**：HMAC-SHA256 签名令牌 - **存储**：建议安全存储，不要硬编码在代码中 - **本地免认证**：来自 `127.0.0.1` 或 `::1` 的请求自动跳过认证 - **多令牌共存**： - ⚠️ 每次登录都会创建新令牌，旧令牌不会自动失效 - 只要令牌未过期且签名有效，多个令牌可以同时使用 - 这意味着如果令牌泄露，需要手动撤销 #### 撤销令牌 如果你想使令牌失效（例如令牌泄露、注销登录或安全事件），有以下方法： **方法 1：撤销单个令牌**（推荐用于注销或撤销特定设备） ```bash # 撤销当前令牌（注销当前会话） curl -X POST http://localhost:8088/api/auth/revoke-token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{}' # 撤销指定令牌（例如泄露的令牌） curl -X POST http://localhost:8088/api/auth/revoke-token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "token": "eyJhbGciOi..." }' ``` **响应示例**： ```json { "message": "Current token has been revoked. Please login again.", "revoked": true, "revoked_current_token": true } ``` **方法 2：撤销所有令牌**（用于安全事件或密码重置） ```bash curl -X POST http://localhost:8088/api/auth/revoke-all-tokens \ -H "Authorization: Bearer " ``` **响应示例**： ```json { "message": "All tokens have been revoked. Please login again.", "revoked": true } ``` **方法 3：修改密码**（同时撤销所有令牌） 修改密码时会自动轮换 JWT 密钥，使所有旧令牌失效： ```bash curl -X POST http://localhost:8088/api/auth/update-profile \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "current_password": "old_password", "new_password": "new_password" }' ``` **撤销方法对比**： | 方法 | 作用范围 | 优点 | 缺点 | 使用场景 | | ------------ | -------- | ------------------------ | ------------------ | ---------------------- | | 撤销单个令牌 | 单个 | 精确控制，不影响其他设备 | 需要知道令牌内容 | 注销登录、撤销特定设备 | | 撤销所有令牌 | 全部 | 一次性失效所有会话 | 所有设备需重新登录 | 安全事件、密码泄露 | | 修改密码 | 全部 | 同时更新密码和撤销令牌 | 需要记住旧密码 | 定期密码更新 | | 删除认证文件 | 全部 | 彻底清除（包括密码） | 需要服务器访问权限 | 完全重置系统 | **注意事项**： - 撤销后，所有客户端都需要重新登录获取新令牌 - 撤销操作不可逆 - 建议在令牌泄露或设备丢失时立即撤销 - 如果使用永久令牌（`expires_in: 0`），强烈建议定期手动撤销并重新申请 #### 关闭认证 如果你不想使用 Web 认证，可以关闭它： **方法 1：移除环境变量** ```bash # Linux / macOS unset QWENPAW_AUTH_ENABLED qwenpaw app # Windows (CMD) set QWENPAW_AUTH_ENABLED= qwenpaw app # Windows (PowerShell) Remove-Item Env:\QWENPAW_AUTH_ENABLED qwenpaw app ``` **方法 2：Docker 部署** 移除 `-e QWENPAW_AUTH_ENABLED=true` 参数： ```bash docker run -p 127.0.0.1:8088:8088 \ -v qwenpaw-data:/app/working \ -v qwenpaw-secrets:/app/working.secret \ -v qwenpaw-backups:/app/working.backups \ agentscope/qwenpaw:latest ``` **重要提示**： - 关闭认证后，所有 API 请求**无需** `Authorization` 头部 - 如果**未启用**认证，无需提供 `Authorization` 头部 - 检查认证状态：`GET /api/auth/status` ## 故障排查 ### 无法连接到服务器 确认 QwenPaw 服务正在运行： ```bash # 检查服务状态 curl http://localhost:8088/api/version ``` ### 响应中断 如果流式响应中断，检查： 1. 网络连接是否稳定 2. 服务器是否正常运行 3. 模型配置是否正确 ### 模型执行失败 如果看到 `MODEL_EXECUTION_FAILED` 错误： 1. 确认在 Console → Settings → Models 中正确配置了模型 2. 检查 API Key 是否有效 3. 验证模型名称是否正确 4. 查看错误详情文件（错误消息中会提供路径） ## 相关文档 - [Console 使用指南](./console) - [安全设置](./security) - [多智能体](./multi-agent) - [频道配置](./channels) ## 获取帮助 如果你在使用 API 时遇到问题： 1. 查看 [FAQ](./faq) 了解常见问题 2. 加入 [社区](./community) 寻求帮助 3. 在 GitHub 上提交 [Issue](https://github.com/agentscope-ai/QwenPaw/issues) ## 2. Official Technical Reference & Guides (agentscope-ai/docs) ## File: README.md # AgentScope Documentation This repository is the source for the unified [AgentScope documentation site](https://docs.agentscope.io). It publishes English and Chinese documentation for [AgentScope](https://github.com/agentscope-ai/agentscope) and [ReMe](https://github.com/agentscope-ai/ReMe) with [Mintlify](https://mintlify.com). ## Documentation Sets The two projects share one site but keep separate content and release models: | Project | Documentation scope | Live documentation | Update model | |---|---|---|---| | AgentScope | Building, operating, and deploying agent applications | [AgentScope docs](https://docs.agentscope.io/latest/en/index) | Immutable version directories | | ReMe | File-native agent memory, workflows, integrations, and stable contracts | [ReMe docs](https://docs.agentscope.io/reme/latest/en/overview) | One continuously updated `latest` version | ## ReMe Documentation The ReMe repository [README](https://github.com/agentscope-ai/ReMe#readme) is the concise project entry point. This repository owns the complete public documentation: concepts, verified workflows, integrations, reference material, troubleshooting, and contribution guidance. ReMe documentation should preserve the product principles expressed by its README: - memory files are user-owned source data; - indexes, graphs, and caches are rebuildable derived state; - conversations and resources become correctable, traceable Markdown memory; - Python, AgentScope, MCP, CLI, HTTP, plugins, and Skills are integration boundaries over the same file-native memory model. The current ReMe content is organized by user goal: | Area | Pages | Purpose | |---|---|---| | Get Started | [Overview](reme/latest/en/overview.mdx), [Quick Start](reme/latest/en/quickstart.mdx), [Concepts](reme/latest/en/concepts.mdx) | Explain the product, complete the first memory loop, and establish its principles | | Integration | [Integration overview](reme/latest/en/integration/overview.mdx), [Deployment](reme/latest/en/integration/deployment.mdx), [Python SDK](reme/latest/en/integration/python-sdk.mdx), [Plugins](reme/latest/en/integration/plugins.mdx) | Choose and implement the correct runtime boundary | | Resources | [Reference](reme/latest/en/reference.mdx), [FAQ](reme/latest/en/faq.mdx), [Contribution](reme/latest/en/contribution.mdx) | Find stable contracts, solve common problems, and contribute changes | Chinese pages mirror the same structure under `reme/latest/zh/`. Update both languages together and keep their intent, headings, examples, and links aligned. ## Local Development Use an active Node.js LTS release (Node 20 or 22). Install the [Mintlify CLI](https://www.npmjs.com/package/mint): ```bash npm i mint ``` From the repository root, validate the site or start a preview: ```bash mint validate mint dev ``` The preview is available at `http://localhost:3000` by default. ## Repository Structure ```text . ├── versions/ │ └── /{en,zh}/ # Versioned AgentScope documentation ├── reme/ │ └── latest/{en,zh}/ # Current ReMe documentation ├── images/ # Shared static assets ├── scripts/ # Documentation maintenance scripts ├── docs.json # Mintlify navigation and redirects └── CLAUDE.md # Writing and review guidelines ``` ## Content Boundaries Keep public documentation focused on user goals and stable behavior: - Verify ReMe behavior against current code, public schemas, tests, CLI help, and `reme/config/default.yaml`. - Explain the stable contract and link to authoritative source instead of duplicating implementation details. - Keep concepts focused on product intent; place detailed development mechanics in source code, tests, and repository-local guidance. - Lead with the outcome, use direct language, and introduce every table, image, diagram, and code block. - Start each MDX page with `title` and `description` frontmatter. See [CLAUDE.md](CLAUDE.md) for the complete writing and component guidelines. ## Version Management AgentScope documentation is immutable within each published version directory. For a new AgentScope release: 1. Copy the latest relevant version into a new project version directory. 2. Update every version-specific internal link in the copied pages. 3. Add the version under the matching project tab for both languages in `docs.json`. 4. Point the relevant `latest` or `stable` redirect at the new version. 5. Run `mint validate` before submitting the change. AgentScope versions can be created with `scripts/create-version.sh`. ReMe does not keep historical release directories. Update `reme/latest/{en,zh}/` directly, keep canonical internal links under `/reme/latest/...`, and leave its `docs.json` version label as `latest`. The `/reme/stable/...` alias and obsolete numeric-version URLs redirect to the current pages for compatibility. ## Contribution Workflow When adding or updating documentation: 1. Verify the behavior in the corresponding project source. 2. Update the correct project, version, and language pages. 3. For ReMe, make the equivalent English and Chinese changes in `reme/latest/`. 4. Update `docs.json` when navigation, versions, or compatibility redirects change. 5. Check page links and run `mint validate` before submitting a pull request. Run these checks from the repository root before submitting: ```bash git diff --check mint validate ``` ## Resources - [AgentScope GitHub](https://github.com/agentscope-ai/agentscope) - [ReMe GitHub](https://github.com/agentscope-ai/ReMe) - [ReMe English documentation](https://docs.agentscope.io/reme/latest/en/overview) - [ReMe 中文文档](https://docs.agentscope.io/reme/latest/zh/overview) - [Mintlify Documentation](https://mintlify.com/docs) --- ## File: reme/README.md # ReMe documentation ReMe documentation is part of the unified Mintlify site in this repository. - `latest/` contains the current `en/` and `zh/` MDX pages and is updated in place. - ReMe does not maintain numbered or historical documentation directories. - Shared ReMe media lives in `images/reme/`. - Navigation is defined by the `ReMe` tab for each language in `docs.json`. - Canonical internal links use `/reme/latest/...`; compatibility redirects preserve old URLs. Keep the documentation focused on product philosophy, verified user workflows, and stable contracts. Implementation details belong in the ReMe source, schemas, tests, and runtime help.