Download Now

User Manual

Complete user manual with detailed introduction to all ZAgent features

Table of Contents

  1. App Overview
  2. Installation and Running
  3. Interface Introduction
  4. Basic Operations
  5. Session Management
  6. Model Configuration
  7. Skill System
  8. Task Scheduling
  9. Feishu Integration
  10. Troubleshooting
  11. Wiki Knowledge Base
  12. High-Speed Code Analyzer
  13. Memory System
  14. Personalized Settings
  15. Open Source Licenses

1. App Overview

1.1 What is ZAgent

ZAgent is a desktop AI assistant application. Its purpose is to lower the barrier for users to use AI assistants and provide a powerful AI Agent application.

Figure 1.1: ZAgent Main Interface

Main Features:

1.2 System Requirements

Item Minimum Recommended
Operating System Windows 10+ / Windows 11 / Mac OS / Linux coming soon
Memory 4 GB 8 GB+
Disk Space 200 MB 500 MB

2. Installation and Running

2.1 Download and Install

After downloading the installer, click to install. The program will be installed to the specified directory.

2.2 First Run Configuration

After first launch, you need to configure the following:

  1. Model Configuration: The model's API Key can be set directly in the model dialog or via a system environment variable. You can either paste the API key directly or add the system variable name representing the API key in settings.
  2. Proxy Settings (optional): Browser proxy

For detailed model configuration, see Section 6.

3. Interface Introduction

3.1 Overall Layout

ZAgent uses a classic three-section layout: menu bar, workspace, and status bar. The workspace is divided into 2 parts. The right side is the chat window, and the left side is the function area, including embedded terminal, browser, editor, skills, and tasks.

Figure 3.1: Application Layout

3.2 Menu Bar

The menu bar is at the top and contains the following menu items:

Menu Functions
File Exit
Session New, Load, Restore, Tree, Compress, Export, Info
Skill Skill List, New Skill
Task Task List, New Task
Settings Select Model, New Model, Proxy, Feishu
Mode Plan/Build, Theme, Language, Auto/Manual Compress, Feishu
Help Shortcuts, Open Source License, About

File Menu

Session Menu

Settings Menu

Mode Menu

Help Menu

3.3 Right Workspace - Chat Window

The chat tab is the default main interaction area, displaying conversation history: including user messages, assistant messages, tool calls, and tool call result messages.

Figure 3.2: Chat Interface

Interface Elements:

3.4 Left Workspace - Function Tabs

The left workspace has multiple switchable tabs:

Tab Icon Function
Skills 🛠→/td> Skill management and execution
Tasks 📋 Scheduled task management
Browser 🌐 Browser automation
Editor 📝 Code editor
Terminal 💻 Terminal emulator

Skills Tab

Displays the list of loaded skills, including:

Each skill displays:

Figure 3.3: Skills Tab

Tasks Tab

Displays configured scheduled tasks:

Figure 3.4: Tasks Tab

Browser Tab

Integrated browser supporting web automation:

Figure 3.5: Browser Tab

Editor Tab

Integrated code editor:

Figure 3.6: Editor Tab

Terminal Tab

Integrated terminal with Windows Console support:

Figure 3.7: Terminal Tab

3.5 Status Bar

The status bar is at the bottom and displays current status:

[Ready] [Plan] [Model: deepseek-chat] [Context: 45%] [Idle]

Status Descriptions:

Status Meaning
Ready/Active/Error/Stopped Current Agent status
Plan/Build Current tool mode
Model name Currently used AI model
Context Context usage percentage
Idle/Outputting/Processing Current operation status

4. Basic Operations

4.1 Send Messages

  1. Enter your message in the bottom input box
  2. Press Enter to send
  3. Shift+Enter for new line

4.2 Switch Theme

Click menu Mode →Dark Theme or Light Theme

4.3 Switch Language

  1. Click menu Mode →Language
  2. Select English or 中文

Figure 4.2: Switch Language

4.4 Switch Tool Mode

Mode Description Permissions
Plan Read-only mode AI cannot execute any operations, only conversation
Build Full access mode AI can execute various operations

Switch method: Click menu Mode →Select Plan (Read-only) or Build (Full Access)

5. Session Management

5.1 Concept Explanation

Session is the core concept in ZAgent, used for managing conversation context.

Session Tree displays the historical structure of sessions:

Root
├── User msg 1 (Node 1)
├── Assistant msg 2 (Node 2)
→  └── Branch A
→      ├── User msg 3 (Node 3)
→      └── Assistant msg 4 (Node 4)
└── Current (Node 5)

Node Types:

Icon Type Description
👤 User User message
🤖 Assistant Assistant message
🔧 Tool Tool call
📦 Compaction Compression point (context compression)
📄 Branch Summary Branch summary

5.2 Create New Session

Click Session →New

Note: Creating a new session will clear the current chat window but does not affect saved sessions.

5.3 Export Session

  1. Click Session →Export Session to HTML
  2. Choose save location
  3. Confirm export

Figure 5.1: Export Session

5.4 Load Session

  1. Click Session →Load...
  2. Search for sessions in the popup dialog
  3. Double-click to load after selecting session

5.5 Restore Recent

  1. Click Session →Restore Recent
  2. System automatically restores the last session

5.6 Session Tree Operations

Click Session →Tree to open the session tree dialog:

Figure 5.3: Session Tree Dialog

Function Descriptions:

Function Description
Navigate Jump to historical node to continue conversation
Fork Here Create new branch from selected node
New Session Create a completely new blank session

Navigate Two Modes:

  1. With Summary: Generate summary of skipped parts, preserving key information
  2. Without Summary: Direct jump, discarding subsequent nodes

Example:

Currently at node 5, choose to jump to node 2:

5.7 Branch Session

Method 1: Menu Branch

Click Session →Branch: Create new branch from current position

Method 2: Session Tree Branch

In the session tree, select any historical node, click Fork Here

Differences:

Operation Branch Point
Menu Fork Branch from current position
Tree Fork Here Branch from selected historical node

5.8 Compress Context

Auto Compress: Automatically triggered when context usage exceeds threshold (default 80%)

Manual Compress:

  1. Click Session →Compress
  2. Confirm compression operation

Compression will:

6. Model Configuration

6.1 Supported Model Interfaces

ZAgent supports models compatible with OpenAI Completion and Anthropic Messages interfaces. For example, mainstream domestic models supported by Alibaba's Bailian Cloud Coding Plan can be used. DeepSeek, MiniMax, Kimi, and GLM related models can all be used.

6.2 Configure New Model

  1. Click Settings →New Model...
  2. Fill in model information:

Figure 6.1: New Model Dialog

Required Fields:

Field Description Example
Provider Model provider deepseek, openai
Model ID Model identifier deepseek-chat
Display Name Friendly name DeepSeek Chat
API Key or Env Variable Environment variable name for API key, or paste the API key directly DEEPSEEK_API_KEY
Base URL API endpoint https://api.deepseek.com
API Type API protocol type deepseek
Context Window Context token count 128000
Max Tokens Max tokens per response 8192

Optional Fields:

6.3 Select Model

  1. Click Settings →Select Model...
  2. Select from model list
  3. Double-click or press Enter to confirm

Figure 6.2: Select Model Dialog

6.4 Model Information Display

After model selection, the status bar shows current model information:

[Model: deepseek-chat] [Context: 45%]

6.5 Environment Variable Configuration

API keys need to be set in system environment variables or application configuration:

Model Environment Variable How to Get
DeepSeek DEEPSEEK_API_KEY DeepSeek Open Platform
OpenAI OPENAI_API_KEY OpenAI Platform
Anthropic ANTHROPIC_API_KEY Anthropic Console
Qwen DASHSCOPE_API_KEY Alibaba Cloud DashScope

6.6 Proxy Settings

If you need a proxy to access external APIs:

  1. Click Settings →Set Proxy...
  2. Enable proxy
  3. Fill in proxy information:

Figure 6.3: Proxy Settings

Field Description
Enable Proxy Turn proxy on/off
Proxy Type http, https, socks5
Host Proxy server address
Port Proxy server port
Username Authentication username (optional)
Password Authentication password (optional)

7. Skill System

7.1 Concept Explanation

Skill is the tool extension system of ZAgent. Each skill defines a set of available tools and capabilities.

Skill File Structure:

---
name: Skill Name
description: Skill description
read_when:
  - Condition 1
  - Condition 2
metadata: {}
allowed-tools: ToolName(tools:*)
auto_inject: true/false
---

# Skill Content
## Instructions...

7.2 Skill Storage Locations

Skills are stored in two locations:

Location Path Description
Project Skills .zeta/skills/ Project-level skills
User Skills ~/.zeta/agent/skills/ User-level skills

7.3 View Skills

  1. Switch to the Skills tab in the right panel
  2. View the skill list

Figure 7.1: Skills List

Each skill displays:

7.4 Create New Skill

  1. Switch to the Skills tab
  2. Click New Skill
  3. Fill in skill information:

Figure 7.2: New Skill Dialog

Field Description
Skill Name Unique identifier for the skill
Description Detailed description of the skill
Read Conditions When to load this skill
Allowed Tools Tools the skill can use

7.5 Execute Skill

Manual Execution:

  1. Click on skill name in the skill list
  2. View skill details
  3. Click Execute button
  4. Enter request content
  5. Press Enter to execute

Figure 7.3: Execute Skill

Auto Trigger:

When auto_inject: true and the skill is added to the skills array in settings.json, the skill will be automatically injected into the system prompt and available when related use cases are detected.

7.6 Built-in Skills

ZAgent comes with several pre-built skills:

Skill Description
Agent Browser Browser automation for web page interaction, data extraction, and form submission
Ask LLM So Bored Creative conversations and brainstorming for relaxation
Competitive Landscape Market competition analysis and competitive intelligence
News Update Gather and summarize latest news on specified topics
QQMail Manager QQ Mail operations including reading, organizing, and drafting
Wiki Ingest Article Ingest articles and documents into the Wiki knowledge base
Wiki Maintenance Maintain and organize the Wiki knowledge base structure

Agent Browser Skill Example

Used for browser automation, see documentation for detailed commands:

# Install
npm install -g agent-browser
agent-browser install

# Basic Usage
agent-browser open <url>           # Open page
agent-browser snapshot -i           # Get interactive elements
agent-browser click @e1            # Click element
agent-browser fill @e2 "text"      # Fill form
agent-browser close                 # Close browser

8. Task Scheduling

8.1 Concept Explanation

Task is an automated operation that executes on a schedule and can:

8.2 Create Task

  1. Switch to the Tasks tab in the right panel
  2. Click New Task
  3. Fill in task information:

Figure 8.1: New Task Dialog

Required Fields:

Field Description
Task Name Unique identifier for the task
Cron Expression Execution time schedule
Operation Type Run Skill or Send Message
Skill Name Skill to execute
Skill Parameters Skill parameters (JSON)

Operation Types:

Type Description
Run Skill Execute the specified skill
Send Message Send message to main session

8.3 Cron Expressions

Common Templates:

Expression Meaning
* * * * * Every minute
0 * * * * Every hour
0 0 * * * Daily at 0:00
0 9 * * * Daily at 9:00
0 9 * * 1 Every Monday at 9:00
0 0 1 * * First day of month at 0:00

Quick Template Buttons:

8.4 Manage Tasks

Operation Description
Execute Now Execute task immediately (skip schedule)
Edit Modify task configuration
Delete Delete task
Enable/Disable Toggle task status

8.5 Task Status Display

Task list displays:

9. Feishu Integration

9.1 Feature Description

Feishu integration allows:

9.2 Configuration Steps

Step 1: Create Feishu App

  1. Open Feishu Open Platform
  2. Create a self-built app
  3. Enable WebSocket long connection

Step 2: Get Credentials

Get the app's:

Step 3: Configure App

  1. Click Settings →Feishu Settings...
  2. Fill in configuration information:

Figure 9.1: Feishu Settings Dialog

Field Description
Enable Feishu Turn Feishu integration on/off
Domain Feishu (feishu.cn) or Lark (international version)
App ID Feishu app ID
App Secret Feishu app secret

Step 4: Add Bot

Add bot to Feishu group chat:

9.3 Using Feishu

Connection Status:

Status bar shows Feishu connection status:

Status Description
Feishu Connected Connection successful
Feishu Disconnected Not connected or connection lost

Message Flow:

Feishu Message →App →User Message →AI Processing →App →Feishu Reply

Toggle Feishu:

9.4 Message Queue

Feishu messages enter the message queue and are processed in order:

10. Troubleshooting

10.1 Common Questions

Q: Application fails to start

A: Check the following:

  1. Confirm Visual C++ Redistributable is installed (Windows)
  2. Confirm port 1420 is not occupied
  3. Check error information in logs

Q: Model cannot connect

A:

  1. Check if API key is correctly set (either directly entered or via environment variable)
  2. Check network connection
  3. Try configuring proxy
  4. Check if model configuration is correct

Q: Skills cannot load

A:

  1. Check if skill file path is correct
  2. Check if skill file format is correct YAML
  3. Check error information in logs

Q: Feishu cannot connect

A:

  1. Confirm App ID and Secret are correct
  2. Confirm app has WebSocket enabled
  3. Confirm bot has been added to group chat

10.2 Reset Configuration

If you need to reset all configurations:

  1. Close the application
  2. Delete configuration folder:
    • Windows: %USERPROFILE%\.zagent\
  3. Restart the application

11. Wiki Knowledge Base

11.1 Feature Description

ZAgent has a built-in Roam-style, Markdown-backed personal Wiki knowledge base. It stores your notes as local Markdown files, indexes pages and blocks in SQLite, and lets both you and the AI Agent read, search, organize, review, and maintain your knowledge.

Core Features:

11.2 First-Run Initialization

On first launch, ZAgent checks whether the Wiki root exists. If it does not exist, the app creates the required directory structure and initializes the SQLite database schema automatically.

~/.zagent/
└── wiki/                 # Wiki root directory
    ├── pages/            # General pages
    ├── concepts/         # Concept pages extracted or maintained by users/AI
    ├── sources/          # Source material pages
    ├── daily/            # Daily notes
    ├── raw/              # Raw imported files and extracted Markdown
    └── .index/
        └── wiki.db       # SQLite index and workflow metadata

11.3 File Format

Wiki uses Markdown with Roam-style page links, stable block anchors, block references, properties, and provenance metadata:

# Page Title

This is the main content.

## A Stable Block ^b-abc1234

Reference this block from another page: ((b-abc1234))

Link to another page: [[concepts/attention]]

Properties:
source_doc:: sources/attention-paper.md
source_locator:: page 3
confidence:: 0.82

11.4 Usage Methods

Create Note:

  1. Switch to the Wiki tab in the left panel
  2. Click the new page button
  3. Enter a page path such as pages/project-notes.md. If no directory is provided, the page is created under pages/.
  4. Write content in the block editor and save

Search Knowledge:

  1. Use the Wiki search box or graph search
  2. Enter page, block, tag, concept, or source keywords
  3. Open matching pages, inspect block results, or focus graph nodes

Import File:

  1. Click the import button
  2. Select a Markdown, text, PDF, or supported office document
  3. ZAgent stores the original material under raw/ and creates or updates a Markdown page
  4. The imported page is indexed so it can be searched, linked, reviewed, and used by AI workflows

AI Organize:

  1. Open the Wiki tab and expand AI Organize
  2. Use Smart Import to create a persistent ingest workflow for a source document
  3. Review the generated plan, then apply it when the proposed operations are appropriate
  4. Use Smart Maintenance to create a persistent maintenance workflow for anchors, duplicate IDs, broken links, and structure repairs

11.5 AI Integration

AI can access and maintain the knowledge base through the wiki tool:

12. High-Speed Code Analyzer

12.1 Feature Description

ZAgent has a Rust-implemented high-speed code analysis engine that can parse code structure at millisecond level, allowing AI to understand your code in seconds.

Performance Advantages:

12.2 Analysis Capabilities

Analysis Type Description Supported Languages
File Structure Directory tree, file list All
Function Definition Function name, parameters, location Rust, TypeScript, Go, etc.
Class Structure Class name, methods, inheritance Object-oriented languages
Call Relationship Callers, callees All
Import Relationship import/export analysis All
Statistics Code line count, language distribution All

12.3 Usage Method

AI automatically analyzes code base through code analyzer tool:

{
  "action": "analyze",       // analyze, structure, definitions, calls, imports, stats
  "path": "/path/to/code",  // Code path to analyze
  "languages": ["rust", "typescript"],  // Filter languages
  "max_functions": 200,
  "max_calls": 500
}

12.4 Output Examples

Structure Analysis:

src/
├── main.rs
├── lib.rs
└── components/
    ├── ChatTab.tsx
    └── BrowserTab.tsx

Function Definitions:

src-tauri/src/commands/shell.rs:21
  shell_execute(input: ShellInput) -> Result

src-tauri/src/commands/wiki.rs:9
  wiki_read(path: String) -> WikiContent

Call Relationships:

agent_loop →run_loop →execute_tool
                     →get_steering
                     →create_skip_message

13. Memory System

13.1 Feature Description

ZAgent has powerful long-term memory capabilities, able to remember your preferences, habits, and important information, making every conversation build on understanding.

Core Features:

13.2 Memory Types

Type Description Lifespan
Short-term Memory Current session context During session
Long-term Memory Persisted important information Permanent
Project Memory Project-specific context During project

13.3 Usage Methods

View Memory:

  1. Click menu Settings → Memory Management...
  2. View current memory content

Manage Memory:

13.4 Memory Workflow

Conversation →AI identifies important info →Write to long-term memory
                    →
New conversation →Retrieve related memories →Integrate into context

13.5 Memory Events

The system triggers memory-related events:

Event Trigger Condition Description
MemoryFlushRequest Context exceeds threshold Request to flush memory
MemorySaved Memory saved successfully Confirm save complete
CompactComplete Context compression complete Show saved tokens

14. Personalized Settings

14.1 Theme Settings

ZAgent supports light and dark theme modes.

Switch Method:

Figure 14.1: Theme Settings

14.2 Language Settings

ZAgent supports Chinese and English interface switching.

Switch Method:

  1. Click menu Mode →Language
  2. Select English or 中文

Supported Languages:

Language Code Status
Chinese zh Fully supported
English en Fully supported

14.3 Context Compression Settings

Controls context auto-compression behavior.

Mode Options:

Mode Description
Auto Compress Automatically compress when context reaches threshold
Manual Compress Requires manual trigger for compression

Switch Method:

14.4 Feishu Connection Settings

Controls Feishu integration connection status.

Connect/Disconnect:

14.5 Configuration Persistence

All settings are automatically saved:

Configuration File Location:

%USERPROFILE%\.zagent\settings.json

15. Open Source Licenses

15.1 Feature Description

ZAgent is built on top of many excellent open-source projects. We believe in transparency and giving credit where it's due. The application includes a built-in Open Source Licenses dialog that lists all packages used.

Key Libraries:

15.2 Viewing Licenses

To view the complete list of open-source licenses:

  1. Click menu Help → Open Source Licenses
  2. The dialog displays all 60+ packages with their names and license types
  3. Licenses include MIT, Apache-2.0, BSD-3-Clause, ISC, and other permissive licenses

15.3 License Summary

Category Key Packages License
Frontend Framework React, React DOM MIT
Build Tool Vite MIT
Styling Tailwind CSS MIT
Editor Monaco Editor MIT
Icons Lucide React ISC
Markdown Marked, Highlight.js, DOMPurify MIT / BSD-3-Clause / Apache-2.0
State Management Zustand MIT
Desktop Framework Tauri MIT / Apache-2.0
Rust Runtime Tokio MIT
Rust Serialization Serde MIT / Apache-2.0