Metadata-Version: 2.4
Name: yanzhiti
Version: 2.3.2
Summary: 衍智体 is a **personal assistant** that runs in your own environment. It talks to you over multiple channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.) and runs scheduled tasks according to your configuration. **What it can do is driven by Skills — the possibilities are open-ended.** Built-in skills include cron, PDF/Office handling, news digest, file reading, and more; you can add custom skills. All data and tasks run on your machine; no third-party hosting.
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentscope==1.0.20
Requires-Dist: agentscope-runtime==1.1.6
Requires-Dist: httpx>=0.27.0
Requires-Dist: packaging>=24.0
Requires-Dist: discord-py>=2.3
Requires-Dist: dingtalk-stream>=0.24.3
Requires-Dist: alibabacloud-dingtalk>=2.2.42
Requires-Dist: alibabacloud-tea-openapi>=0.4.4
Requires-Dist: alibabacloud-credentials>=0.3.0
Requires-Dist: alibabacloud-tea-util>=0.3.0
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: apscheduler<4,>=3.11.2
Requires-Dist: playwright>=1.49.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: mss>=9.0.0
Requires-Dist: reme-ai==0.3.1.10
Requires-Dist: transformers>=4.30.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-socks>=2.5.3
Requires-Dist: onnxruntime<1.24
Requires-Dist: lark-oapi>=1.5.3
Requires-Dist: python-telegram-bot>=20.0
Requires-Dist: twilio>=9.10.2
Requires-Dist: pywebview>=4.0
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: paho-mqtt>=2.0.0
Requires-Dist: wecom-aibot-python-sdk==1.0.2
Requires-Dist: matrix-nio>=0.24.0
Requires-Dist: shortuuid>=1.0.0
Requires-Dist: google-genai>=1.67.0
Requires-Dist: tzdata>=2024.1
Requires-Dist: cryptography>=43.0.0
Requires-Dist: keyring>=25.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: json-repair>=0.30.0
Requires-Dist: segno>=1.6.6
Requires-Dist: modelscope>=1.35.0
Requires-Dist: huggingface_hub>=0.20.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: agent-client-protocol>=0.9.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: openai<=2.33.0,>=2.0.0
Requires-Dist: anyio<4.13.0,>=4.0.0
Requires-Dist: watchfiles>=0.22
Requires-Dist: orjson>=3.9
Requires-Dist: python-lsp-server[all]>=1.10
Requires-Dist: ast-grep-cli>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Provides-Extra: local
Requires-Dist: huggingface_hub>=0.20.0; extra == "local"
Provides-Extra: adbpg
Requires-Dist: psycopg2-binary==2.9.10; extra == "adbpg"
Provides-Extra: whisper
Requires-Dist: openai-whisper>=20231117; extra == "whisper"
Provides-Extra: full
Requires-Dist: yanzhiti[local,whisper]; extra == "full"
Provides-Extra: sip
Requires-Dist: pyVoIP>=1.6.0; extra == "sip"
Requires-Dist: dashscope>=1.0.0; extra == "sip"
Requires-Dist: dashscope-realtime>=0.1.0; extra == "sip"
Requires-Dist: audioop-lts; python_version >= "3.13" and extra == "sip"
Provides-Extra: sip-livekit
Requires-Dist: yanzhiti[sip]; extra == "sip-livekit"
Requires-Dist: livekit>=1.0.0; extra == "sip-livekit"
Requires-Dist: livekit-api>=0.6.0; extra == "sip-livekit"
Dynamic: license-file

<div align="center">

# 衍智体

[![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-black.svg?logo=github)](https://github.com/agentscope-ai/衍智体)
[![PyPI](https://img.shields.io/pypi/v/yanzhiti?color=3775A9&label=PyPI&logo=pypi)](https://pypi.org/project/yanzhiti/)
[![Documentation](https://img.shields.io/badge/Docs-Website-green.svg?logo=readthedocs&label=Docs)](https://yanzhiti.agentscope.io/)
[![Python Version](https://img.shields.io/badge/python-3.10%20~%20%3C3.14-blue.svg?logo=python&label=Python)](https://www.python.org/downloads/)
[![Last Commit](https://img.shields.io/github/last-commit/agentscope-ai/衍智体)](https://github.com/agentscope-ai/衍智体)
[![License](https://img.shields.io/badge/license-Apache%202.0-red.svg?logo=apache&label=License)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-black.svg?logo=python&label=CodeStyle)](https://github.com/psf/black)
[![GitHub Stars](https://img.shields.io/github/stars/agentscope-ai/衍智体?style=flat&logo=github&color=yellow&label=Stars)](https://github.com/agentscope-ai/衍智体/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/agentscope-ai/衍智体?style=flat&logo=github&color=purple&label=Forks)](https://github.com/agentscope-ai/衍智体/network)
[![DeepWiki](https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/agentscope-ai/衍智体)
[![Discord](https://img.shields.io/badge/Discord-Join_Us-blueviolet.svg?logo=discord)](https://discord.gg/eYMpfnkG8h)
[![X](https://img.shields.io/badge/X-Follow_Us-black.svg?logo=x)](https://x.com/agentscope_ai)
[![DingTalk](https://img.shields.io/badge/DingTalk-Join_Us-orange.svg)](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11)

[[Documentation](https://yanzhiti.agentscope.io/)] [[中文](README_zh.md)] [[日本語](README_ja.md)] [[Русский](README_ru.md)]

<p align="center">
  <img src="https://gw.alicdn.com/imgextra/i1/O1CN01sens5C1TuwioeGexL_!!6000000002443-55-tps-771-132.svg" alt="衍智体 Logo" width="120">
</p>

<p align="center"><b>Works for you, grows with you.</b></p>

</div>

Your personal AI assistant — easy to install, deploy locally or in the cloud, connect across channels, extend with ease.

> **Core capabilities:**
>
> **Under your control** — Memory and personalization fully under your control. Deploy locally (data stays on your machine) or in the cloud (your chosen server). No third-party hosting, no data upload.
>
> **Skills extension** — Built-in scheduling, PDF/Office processing, news digest, and more; custom skills auto-loaded, no lock-in. Skills determine what 衍智体 can do.
>
> **Multi-agent collaboration** — Create multiple independent agents, each with their own role; enable collaboration skills for inter-agent communication to tackle complex tasks together.
>
> **Multi-layer security** — Tool guard, file access control, skill security scanning to ensure safe operation.
>
> **Every channel** — DingTalk, Feishu, WeChat, Discord, Telegram, and more. One 衍智体, connect as needed.
>
> **Memory-evolving & proactive** — Agent learns from interactions, reflects on experience, and proactively serves you. Gets smarter the more you use it.
>
> <details>
> <summary><b>What you can do with 衍智体</b></summary>
>
> <br>
>
> - **Social media**: Daily hot post digests (Xiaohongshu, Zhihu, Reddit), Bilibili/YouTube video summaries.
> - **Productivity**: Email & newsletter highlights pushed to DingTalk/Feishu/QQ; email & calendar contact organization.
> - **Creative & building**: Describe your goal before sleep, auto-execute, wake up to a prototype; full workflow from topic selection to final video.
> - **Research & learning**: Track tech & AI news, personal knowledge base search and reuse.
> - **Desktop & files**: Organize and search local files, read & summarize documents, request files in chat.
> - **Explore more**: Combine Skills with scheduled tasks into your own agentic app.
>
> </details>

---

## News

- [2026-06-01] **v1.1.10 — Spawn Subagent & More Channels** | Agents can now spawn sub-agents; Tencent Yuanbao joins the channel family.

  | Highlight | What's new |
  |-----------|------------|
  | **Spawn Subagent** | New `spawn_subagent` tool for ephemeral in-workspace sub-agent execution. |
  | **Open Directory** | Coding mode gains an "Open Directory" tab to reference local projects without copying. |
  | **Feishu Thread Reply** | Agents can now reply within Feishu message threads. |
  | **Tencent Yuanbao Channel** | New channel integration for Tencent Yuanbao bot. |
  | **Dynamic Upload Limit** | Upload size limit is now configurable across console and channels. |

  Also: OpenRouter attribution headers, bundled desktop CLI, skill update stability fixes. [v1.1.10 Release Notes →](https://yanzhiti.agentscope.io/release-notes#v1.1.10)

- [2026-05-27] **v1.1.9** — Coding Mode (three-panel Web IDE), Tauri desktop app, unified access control. [v1.1.9 Release Notes →](https://yanzhiti.agentscope.io/release-notes#v1.1.9)

- [2026-05-19] **v1.1.8** — Official plugin distribution, 衍智体 Pet, streaming cards for DingTalk / Feishu / Telegram. [v1.1.8 Release Notes →](https://yanzhiti.agentscope.io/release-notes#v1.1.8)

- [2026-05-14] **v1.1.7** — Browser batch actions, OAuth 2.1 MCP, Cron calendar view, multiple file attachments. [v1.1.7 Release Notes →](https://yanzhiti.agentscope.io/release-notes#v1.1.7)

- [2026-05-09] **v1.1.6** — Whisper voice input, GPT Image 2 plugin, Volcano Engine provider, Mermaid diagrams. [v1.1.6 Release Notes →](https://yanzhiti.agentscope.io/release-notes#v1.1.6)

- [2026-04-12] **CoPaw rebrands to 衍智体** — deeper Qwen ecosystem integration, same open-source mission. [v1.0.0 Release Notes →](https://yanzhiti.agentscope.io/release-notes#v1.0.0)

---

## Table of Contents

> **Recommended reading:**
>
> - **🚀 I'm new and want to try quickly**: [Quick Start](#quick-start) → three commands to run → [Configure model](#api-key) → chat in Console
> - **💬 I want to use in DingTalk/Feishu/WeChat**: Complete Quick Start → [Configure model](#api-key) → [Channel setup](https://yanzhiti.agentscope.io/docs/channels)
> - **🐍 I don't want to install Python**: [Desktop app](#option-6-desktop-application-beta) or [Script install](#option-2-script-install) or [ModelScope Studio](https://modelscope.cn/studios/fork?target=AgentScope/衍智体)
> - **💻 I want to use local models (no API key needed)**: [Local Models](#local-models) → download model → start using
> - **🛠️ I want to contribute code or develop new features**: [Install from source](#install-from-source) → [Contributing](#contributing)
- [News](#news)
- [Quick Start](#quick-start)
- [API Key](#api-key)
- [Local Models](#local-models)
- [Documentation](#documentation)
- [Security Features](#security-features)
- [FAQ](#faq)
- [Staying ahead](#staying-ahead)
- [Roadmap](#roadmap)
- [Install from source](#install-from-source)
- [Contributing](#contributing)
- [Why 衍智体?](#why-yanzhiti)
- [Built by](#built-by)
- [License](#license)

---

## Quick Start

### Option 1: pip install

If you prefer managing Python yourself:

```bash
pip install yanzhiti
yanzhiti init --defaults
yanzhiti app
```

Then open the Console in your browser at **http://127.0.0.1:8088/** to configure your model. To chat in DingTalk, Feishu, WeChat, etc., see the [Channel setup](https://yanzhiti.agentscope.io/docs/channels) documentation.

![Console](https://img.alicdn.com/imgextra/i2/O1CN01EP1ra01iOAcBvF0TC_!!6000000004402-2-tps-3822-2070.png)

---

### 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 衍智体 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://yanzhiti.agentscope.io/install.sh | bash
```

**Windows (CMD):**

```CMD
curl -fsSL https://yanzhiti.agentscope.io/install.bat -o install.bat && install.bat
```

**Windows (PowerShell):**

```powershell
irm https://yanzhiti.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 衍智体 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
>      - 衍智体 path: Typically located at `%USERPROFILE%\.yanzhiti\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%\.yanzhiti\bin` to your system's `Path` variable.
>   - **Re-run the installation**: Open a new terminal and execute the installation script again to complete the `衍智体` installation.
>   - **Configure the `衍智体` environment variable**: Add `%USERPROFILE%\.yanzhiti\bin` to your system's `Path` variable.

Once installed, open a new terminal and run:

```bash
yanzhiti init --defaults   # or: yanzhiti init (interactive)
yanzhiti app
```

<details>
<summary><b>Install options</b></summary>

**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
yanzhiti uninstall          # keeps config and data
yanzhiti uninstall --purge  # removes everything
```

**Windows (PowerShell):**

```powershell
# Install a specific version
irm ... | iex; .\install.ps1 -Version 0.0.2

# Install from source (dev/testing)
.\install.ps1 -FromSource

# Upgrade — just re-run the installer
irm ... | iex

# Uninstall
yanzhiti uninstall          # keeps config and data
yanzhiti uninstall --purge  # removes everything
```

</details>


---

### Option 3: Docker

Images are on **Docker Hub** (`agentscope/yanzhiti`). Image tags: `latest` (stable); `pre` (PyPI pre-release).

```bash
docker pull agentscope/yanzhiti:latest
docker run -p 127.0.0.1:8088:8088 \
  -v yanzhiti-data:/app/working \
  -v yanzhiti-secrets:/app/working.secret \
  -v yanzhiti-backups:/app/working.backups \
  agentscope/yanzhiti:latest
```

Also available on Alibaba Cloud Container Registry (ACR) for users in China: `agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/yanzhiti` (same tags).

Then open **http://127.0.0.1:8088/** for the Console. Config, memory, and skills are stored in the `yanzhiti-data` volume; model provider settings and API keys are in the `yanzhiti-secrets` volume; backup archives are stored in the `yanzhiti-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 衍智体 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 yanzhiti-data:/app/working \
>   -v yanzhiti-secrets:/app/working.secret \
>   -v yanzhiti-backups:/app/working.backups \
>   agentscope/yanzhiti:latest
> ```
> Then in 衍智体 **Settings → Models**, change the Base URL to `http://host.docker.internal:<port>` — 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 yanzhiti-data:/app/working \
>   -v yanzhiti-secrets:/app/working.secret \
>   -v yanzhiti-backups:/app/working.backups \
>   agentscope/yanzhiti: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 衍智体 on Alibaba Cloud (ECS), use the one-click deployment: open the [衍智体 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: Using ModelScope

**No local install?** [ModelScope Studio](https://modelscope.cn/studios/fork?target=AgentScope/衍智体) one-click cloud setup. Set your Studio to **non-public** so others cannot control your 衍智体.

---

### Option 6: 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 衍智体's desktop application without manually configuring Python environments or running commands.

#### Download

Download the desktop app from [GitHub Releases](https://github.com/agentscope-ai/衍智体/releases):
- **Windows**: `衍智体-Setup-<version>.exe`
- **macOS**: `衍智体-<version>-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 browser interface, 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 browser window to open automatically.

#### macOS: Bypass System Security Restrictions

When you download the 衍智体 macOS app from Releases, macOS may show: *"Apple cannot verify that '衍智体' 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 衍智体 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 *"衍智体 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/衍智体.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://yanzhiti.agentscope.io/docs/desktop).

---

## API Key

If you use a **cloud LLM API** (e.g., Qianwen, Gemini, OpenAI), you must configure an API key before chatting. 衍智体 will not work until a valid key is set. See the [official docs](https://yanzhiti.agentscope.io/docs/models) for details.

**How to configure:**

1. **Console (recommended)** — After running `yanzhiti app`, open **http://127.0.0.1:8088/** → **Settings** → **Models**. Choose a provider, enter the **API Key**, and enable that provider and model.
2. **`yanzhiti init`** — When you run `yanzhiti 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://yanzhiti.agentscope.io/docs/config) for details.

> **Using local models only?** If you use [Local Models](#local-models) (llama.cpp / Ollama / LM Studio), you do **not** need any API key.

## Local Models

衍智体 can run LLMs entirely on your machine — no API keys or cloud services required. See the [official docs](https://yanzhiti.agentscope.io/docs/models) for details.

| Backend       | Best for                                 | Install                                                              |
| ------------- | ---------------------------------------- | -------------------------------------------------------------------- |
| **llama.cpp** | Cross-platform (macOS / Linux / Windows) | No extra installation required; click "Download Llama.cpp" in the web UI. |
| **Ollama**    | Cross-platform (requires Ollama service) | Install and start the Ollama app in advance. |
| **LM Studio** | Cross-platform (requires LM Studio service) | Install and start the LM Studio app in advance. |

---

## Documentation

| Topic                                                                 | Description                                      |
| --------------------------------------------------------------------- | ------------------------------------------------ |
| [Introduction](https://yanzhiti.agentscope.io/docs/intro)                | What 衍智体 is and how to use it                  |
| [Quick start](https://yanzhiti.agentscope.io/docs/quickstart)            | Install and run (local or ModelScope Studio)    |
| [Console](https://yanzhiti.agentscope.io/docs/console)                   | Web UI: chat and agent configuration            |
| [Models](https://yanzhiti.agentscope.io/docs/models)                     | Configure cloud, local, and custom providers    |
| [Channels](https://yanzhiti.agentscope.io/docs/channels)                  | DingTalk, Feishu, QQ, Discord, iMessage, and more |
| [Skills](https://yanzhiti.agentscope.io/docs/skills)                      | Extend and customize capabilities               |
| [Plugins](https://yanzhiti.agentscope.io/docs/plugins)                    | Plugin system                                    |
| [MCP](https://yanzhiti.agentscope.io/docs/mcp)                            | Manage MCP clients                               |
| [Memory](https://yanzhiti.agentscope.io/docs/memory)                     | Long-term memory                     |
| [Memory-Evolving & Proactive](https://yanzhiti.agentscope.io/docs/memory-evolving-and-proactive) | Agent memory evolution and proactive interaction |
| [Context](https://yanzhiti.agentscope.io/docs/context)                   | Context management mechanism                     |
| [Magic commands](https://yanzhiti.agentscope.io/docs/commands)           | Control conversation state without waiting for the AI |
| [Heartbeat](https://yanzhiti.agentscope.io/docs/heartbeat)                | Scheduled check-in and digest                    |
| [Multi-Agent](https://yanzhiti.agentscope.io/docs/multi-agent)           | Create multiple agents and enable collaboration  |
| [Config & working dir](https://yanzhiti.agentscope.io/docs/config) | Working directory and config file                |
| [CLI](https://yanzhiti.agentscope.io/docs/cli)                            | Init, cron jobs, skills, clean                   |
| [FAQ](https://yanzhiti.agentscope.io/docs/faq)                           | Common questions and troubleshooting             |

Full docs in this repo: [website/public/docs/](website/public/docs/).

---

## Security Features

衍智体 includes multi-layer security mechanisms to protect your data and system:

- **Tool guard** — Automatically intercepts dangerous shell commands (e.g., `rm -rf /`, fork bombs, reverse shells, etc.)
- **File access guard** — Restricts agent access to sensitive paths (e.g., `~/.ssh`, key files, system directories, etc.)
- **Skill security scanning** — Automatically scans before installing skills, detecting risks like prompt injection, command injection, hardcoded keys, data exfiltration, etc.
- **Local deployment** — All data and memory stored locally, no third-party upload (when using cloud LLM APIs, conversation content is sent to the corresponding API provider)
- **Web Authentication** — Optional login protection for the Console. Disabled by default; set `YANZHITI_AUTH_ENABLED=true` to enable. See [Web Authentication](https://yanzhiti.agentscope.io/docs/security#Web-Authentication) for details.

See [Security documentation](https://yanzhiti.agentscope.io/docs/security) for details.

---

## FAQ

For common questions, troubleshooting tips, and known issues, please visit the **[FAQ page](https://yanzhiti.agentscope.io/docs/faq)**.

---

## Staying ahead

<a href="https://github.com/agentscope-ai/衍智体">
  <img src="https://img.alicdn.com/imgextra/i1/O1CN01V8HYv61By0HYcIDaq_!!6000000000013-1-tps-1698-954.gif" width="600" alt="Star 衍智体" />
</a>

Star 衍智体 on GitHub and be instantly notified of new releases.

---

## Roadmap

| Area                     | Item                                                                                         | Status               |
| ------------------------ | -------------------------------------------------------------------------------------------- | -------------------- |
| **Horizontal Expansion** | More channels, models, skills, MCPs — **community contributions welcome**                  | Seeking Contributors |
| **Existing Feature Extension** | Display optimization, download hints, Windows path compatibility, etc. — **community contributions welcome** | Seeking Contributors |
| **Client Experience**    | Install, update, and packaging improvements                                                  | In Progress          |
| **Models**               | Multi-model switching                                                                         | In Progress          |
|                          | OAuth                                                                                        | Planned              |
|                          | Response API                                                                                 | Planned              |
| **Workspace**            | File access control with Sandbox integration                                                 | In Progress          |
|                          | Subfolder layout (config, production files, etc.)                                            | Planned              |
| **Coding**               | LSP, dedicated prompts, workspace versioning, runtime, and supporting infra                  | In Progress              |
|                          | Lightweight native APIs                                                                      | Planned              |
|                          | Tool self-evolution                                                                          | Planned              |
|                          | Compatibility with existing agents (e.g. Claude Code)                                        | Planned              |
| **Multi-agent**          | Group chat                                                                                   | Planned              |
|                          | Subagent Visualization                                                                                 | Planned              |
|                          | HiClaw enterprise capabilities                                                               | Planned              |
| **Context Management**   | Personal Knowledge Base                                                             | In Progress          |
|                          | User-selectable compression (fine-grained control)                                           | Planned              |
| **衍智体 Application**   | 衍智体 Creator                                                             | In Progress          |
|                          | 衍智体 Insight                                           | In Progress              |
_Status:_ **In Progress** — actively being worked on; **Planned** — queued or under design, also welcome contributions; **Seeking Contributors** — we strongly encourage community contributions.

## Install from source

```bash
git clone https://github.com/agentscope-ai/衍智体.git
cd 衍智体

# 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/yanzhiti/console
cp -R console/dist/. src/yanzhiti/console/

# Install Python package
pip install -e .
```

- **Dev** (tests, formatting): `pip install -e ".[dev,full]"`
- **Then**: Run `yanzhiti init --defaults`, then `yanzhiti 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 `yanzhiti app`, and clear your browser cache with `Ctrl+Shift+R` (or `Cmd+Shift+R` on macOS).

---

## Contributing

衍智体 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/衍智体/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/衍智体/discussions) to discuss ideas or pick up tasks.

---

## Why 衍智体?

衍智体 (Yǎn Zhì Tǐ) means "Evolving Intelligence Body" — a self-evolving AI agent that grows with you. It represents the continuous derivation (衍) of intelligence (智) into a living system (体).
We hope it is not a cold tool, but a continuously evolving intelligent partner always ready to help—the most intuitive companion 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) |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| [<img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="80" height="80" alt="Discord">](https://discord.gg/eYMpfnkG8h) | [<img src="https://img.shields.io/badge/X-black.svg?logo=x&logoColor=white" width="80" height="80" alt="X">](https://x.com/agentscope_ai) | [<img src="https://img.alicdn.com/imgextra/i2/O1CN01vCWI8a1skHtLGXEMQ_!!6000000005804-2-tps-458-460.png" width="80" height="80" alt="DingTalk">](https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11) | [<img src="https://img.alicdn.com/imgextra/i3/O1CN016BoEPS1l33CE9mHb9_!!6000000004762-0-tps-160-160.jpg" width="80" height="80" alt="RedNote">](https://www.xiaohongshu.com/user/profile/691c18db0000000037032be9) |

---

## Telemetry

衍智体 collects **anonymous** usage data during `yanzhiti init` to help us understand our user base and prioritize improvements. Data is sent **once per version** — when you upgrade 衍智体, telemetry is re-collected so we can track version adoption.

**What we collect:**

- 衍智体 version (e.g., 0.0.7)
- 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 `yanzhiti 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 衍智体's functionality.

---

## License

衍智体 is released under the [Apache License 2.0](LICENSE).

---

## Contributors

All thanks to our contributors:

<a href="https://github.com/agentscope-ai/衍智体/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=agentscope-ai/衍智体" alt="Contributors" />
</a>
