立即下载

详细操作指南

完整的使用手册，详细介绍 Zeta Agent 的所有功能

目录

  1. App概述
  2. 安装和运行
  3. 界面介绍
  4. 基本操作
  5. 会话管理
  6. 模型配置
  7. 技能系统
  8. 任务调度
  9. 飞书集成
  10. 故障排除

1. App概述

1.1 什么是 Zeta Agent

Zeta Agent 是一个桌面 AI 助手应用。它的目的是降低用户使用AI助手的门槛，给用户带来功能强大的一款AI Agent应用。

图 1.1: Zeta Agent 主界面

主要特性：

1.2 系统要求

项目 最低要求 推荐要求
操作系统 Windows 10+ / Windows 11 / Mac OS /linux 待后续推出
内存 4 GB 8 GB+
磁盘空间 200 MB 500 MB

2. 安装和运行

2.1 下载安装

下载安装包后，点击安装即可。程序会安装到指定目录。

2.2 首次运行配置

首次启动后，需要配置以下内容：

  1. 模型配置：模型的API Key需要设置在系统变量里。在设置中添加模型的代表API key的系统变量名。
  2. 代理设置（可选）：浏览器的代理

详细的模型配置请参阅第 6 节。

3. 界面介绍

3.1 整体布局

Zeta Agent 采用经典的三段式布局：菜单栏、工作区和状态栏。其中工作区分为2部分。右边为聊天窗口，左边为功能区，包括内嵌终端、浏览器、编辑器、技能和任务。

图 3.1: 应用布局

3.2 菜单栏

菜单栏位于顶部，包含以下菜单项：

菜单 功能
文件 (File) 退出
会话 (Session) 新建、加载、恢复、树形、压缩、导出、信息
技能 (Skill) 技能列表、新建技能
任务 (Task) 任务列表、新建任务
设置 (Settings) 选择模型、新建模型、代理、飞书
模式 (Mode) 计划/构建、主题、语言、自动/手工压缩、飞书
帮助 (Help) 快捷键、开源许可、关于

文件菜单

会话菜单

设置菜单

模式菜单

帮助菜单

3.3 右侧工作区 - 聊天窗口

聊天标签页是默认的主要交互区域，显示对话历史：包括用户消息、助手消息、工具调用和工具调用结果消息。

图 3.2: 聊天界面

界面元素说明：

3.4 左侧工作区 - 功能标签页

左侧工作区有多个可切换的标签页：

标签 图标 功能
技能 🛠️ 技能管理和执行
任务 📋 定时任务管理
浏览器 🌐 浏览器自动化
编辑器 📝 代码编辑器
终端 💻 终端模拟器

技能标签页

显示已加载的技能列表，包括：

每个技能显示：

图 3.3: 技能标签页

任务标签页

显示已配置的定时任务：

图 3.4: 任务标签页

浏览器标签页

集成浏览器，支持网页自动化：

图 3.5: 浏览器标签页

编辑器标签页

集成代码编辑器：

图 3.6: 编辑器标签页

终端标签页

集成终端，底层Power Shell支持(Windows)：

图 3.7: 终端标签页

3.5 状态栏

状态栏位于底部，显示当前状态：

[就绪] [计划] [模型: deepseek-chat] [上下文: 45%] [空闲]

状态说明：

状态 含义
就绪/活动/错误/已停止 Agent 当前状态
计划/构建 当前工具模式
模型名称 当前使用的 AI 模型
上下文 上下文使用百分比
空闲/输出中/处理中 当前操作状态

4. 基本操作

4.1 发送消息

  1. 在底部输入框中输入消息
  2. 按 Enter 发送
  3. Shift+Enter 换行

4.2 切换主题

点击菜单 模式 → 深色主题 或 浅色主题

4.3 切换语言

  1. 点击菜单 模式 → 语言
  2. 选择 English 或 中文

图 4.2: 切换语言

4.4 切换工具模式

模式 说明 权限
计划 (Plan) 只读模式 AI 无法执行任何操作，只能对话
构建 (Build) 完全访问模式 AI 可以执行各种操作

切换方式：点击菜单 模式 → 选择 计划 (只读) 或 构建 (完全访问)

5. 会话管理

5.1 概念解释

会话 (Session) 是 Zeta Agent 中的核心概念，用于管理对话上下文。

会话树 (Session Tree) 展示会话的历史结构：

Root
├── User msg 1 (节点 1)
├── Assistant msg 2 (节点 2)
│   └── Branch A
│       ├── User msg 3 (节点 3)
│       └── Assistant msg 4 (节点 4)
└── Current (节点 5)

节点类型：

图标 类型 说明
👤 User 用户消息
🤖 Assistant 助手消息
🔧 Tool 工具调用
📦 Compaction 压缩点（上下文压缩）
📄 Branch Summary 分支摘要

5.2 新建会话

点击 会话 → 新建

注意：新建会话会清空当前聊天窗口，但不影响已保存的会话。

5.3 导出会话

  1. 点击 会话 → 导出会话到HTML
  2. 选择保存位置
  3. 确认导出

图 5.1: 导出会话

5.4 加载会话

  1. 点击 会话 → 加载...
  2. 在弹出的对话框中搜索会话
  3. 选择会话后双击加载

5.5 恢复最近

  1. 点击 会话 → 恢复最近
  2. 系统自动恢复上次会话

5.6 会话树操作

点击 会话 → 树形结 打开会话树对话框：

图 5.3: 会话树对话框

功能说明：

功能 说明
Navigate (导航) 跳转到历史节点继续对话
Fork Here (在此分支) 从选中节点创建新分支
New Session (新建会话) 创建全新空白会话

Navigate 两种模式：

  1. 带摘要导航：生成被跳过部分的摘要，保留关键信息
  2. 不带摘要导航：直接跳转，丢弃后续节点

示例：

当前在节点 5，选择跳转到节点 2：

5.6 分支会话

方式一：菜单分支

点击 会话 → 分支：从当前位置创建新分支

方式二：会话树分支

在会话树中选择任意历史节点，点击 Fork Here

二者区别：

操作 分支点
菜单 Fork 从当前位置分支
Tree Fork Here 从选中的任意历史节点分支

5.7 压缩上下文

自动压缩：当上下文使用超过阈值（默认 80%）时自动触发

手动压缩：

  1. 点击 会话 → 压缩
  2. 确认压缩操作

压缩会：

6. 模型配置

6.1 支持的模型接口

Zeta Agent 支持兼容 OpenAI Completion 和 Anthropic Messages 接口的模型都可以使用。比如阿里百炼云 Coding Plan 中支持的国内主流模型都能使用。DeepSeek、MiniMax、Kimi、GLM 相关模型都能使用。

6.2 配置新模型

  1. 点击 设置 → 新建模型...
  2. 填写模型信息：

图 6.1: 新建模型对话框

必填字段：

字段 说明 示例
提供商 (Provider) 模型提供商 deepseek, openai
模型 ID (Model ID) 模型标识符 deepseek-chat
显示名称 友好名称 DeepSeek Chat
API 密钥环境变量 API 密钥的环境变量名 DEEPSEEK_API_KEY
基础 URL API 端点 https://api.deepseek.com
API 类型 API 协议类型 deepseek
上下文窗口 上下文 token 数 128000
最大令牌数 单次回复最大 token 8192

选填字段：

6.3 选择模型

  1. 点击 设置 → 选择模型...
  2. 在模型列表中选择
  3. 双击或按 Enter 确认

图 6.2: 选择模型对话框

6.4 模型信息显示

模型选择后，状态栏显示当前模型信息：

[模型: deepseek-chat] [上下文: 45%]

6.5 环境变量配置

需要在系统环境变量或应用配置中设置 API 密钥：

模型 环境变量 获取方式
DeepSeek DEEPSEEK_API_KEY DeepSeek 开放平台
OpenAI OPENAI_API_KEY OpenAI 平台
Anthropic ANTHROPIC_API_KEY Anthropic 控制台
Qwen DASHSCOPE_API_KEY 阿里云 DashScope

6.6 代理设置

如需代理访问外部 API：

  1. 点击 设置 → 设置代理...
  2. 启用代理
  3. 填写代理信息：

图 6.3: 代理设置

字段 说明
启用代理 开启/关闭代理
代理类型 http, https, socks5
主机 代理服务器地址
端口 代理服务器端口
用户名 认证用户名（可选）
密码 认证密码（可选）

7. 技能系统

7.1 概念解释

技能 (Skill) 是 Zeta Agent 的工具扩展系统，每个技能定义了一组可用的工具和能力。

技能文件结构：

---
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 技能存储位置

技能存储在两个置：

位置 路径 说明
项目技能 .zeta/skills/ 项目级别的技能
用户技能 ~/.zeta/agent/skills/ 用户级别的技能

7.3 查看技能

  1. 切换到右侧面板的 技能 标签页
  2. 查看技能列表

图 7.1: 技能列表

每个技能显示：

7.4 新建技能

  1. 切换到 技能 标签页
  2. 点击 新建技能
  3. 填写技能信息：

图 7.2: 新建技能对话框

字段 说明
技能名称 技能的唯一标识符
描述 技能的详细描述
读取条件 何时加载此技能
允许的工具 技能可使用的工具

7.5 执行技能

手动执行：

  1. 在技能列表中点击技能名称
  2. 查看技能详情
  3. 点击 执行 按钮
  4. 输入请求内容
  5. 按 Enter 执行

图 7.3: 执行技能

自动触发：

当 auto_inject: true，并且在settings.json中的skills数组中加入该skill 时，技能会自动注入到系统提示中，在检测到相关用例时可用。

7.6 内置技能示例

Agent Browser 技能

用于浏览器自动化，详细命令见文档：

# 安装
npm install -g agent-browser
agent-browser install

# 基本使用
agent-browser open <url>           # 打开页面
agent-browser snapshot -i           # 获取可交互元素
agent-browser click @e1            # 点击元素
agent-browser fill @e2 "text"      # 填写表单
agent-browser close                 # 关闭浏览器

8. 任务调度

8.1 概念解释

任务 (Task) 是定时执行的自动化操作，可以：

8.2 创建任务

  1. 切换到右侧面板的 任务 标签页
  2. 点击 新建任务
  3. 填写任务信息：

图 8.1: 新建任务对话框

必填字段：

字段 说明
任务名称 任务的唯一标识符
Cron 表达式 执行时间调度
操作类型 运行技能 或 发送消息
技能名称 要执行的技能
技能参数 技能参数 (JSON)

操作类型：

类型 说明
运行技能 执行指定的技能
发送消息 发送消息到主会话

8.3 Cron 表达式

常用模板：

表达式 含义
* * * * * 每分钟
0 * * * * 每小时
0 0 * * * 每天 0:00
0 9 * * * 每天 9:00
0 9 * * 1 每周一 9:00
0 0 1 * * 每月1号 0:00

快速模板按钮：

8.4 管理任务

操作 说明
立即执行 立即执行任务（跳过调度）
编辑 修改任务配置
删除 删除任务
启用/禁用 切换任务状态

8.5 任务状态显示

任务列表显示：

9. 飞书集成

9.1 功能说明

飞书集成允许：

9.2 配置步骤

第一步：创建飞书应用

  1. 打开 飞书开放平台
  2. 创建自建应用
  3. 启用 WebSocket 长连接

第二步：获取凭证

获取应用的：

第三步：配置应用

  1. 点击 设置 → 飞书设置...
  2. 填写配置信息：

图 9.1: 飞书设置对话框

字段 说明
启用飞书 开启/关闭飞书集成
域名 飞书 (飞书.cn) 或 Lark (国际版)
App ID 飞书应用 ID
App Secret 飞书应用密钥

第四步：添加机器人

在飞书群聊中添加机器人：

9.3 使用飞书

连接状态：

状态栏显示飞书连接状态：

状态 说明
飞书已连接 连接成功
飞书已断开 未连接或连接断开

消息流程：

飞书消息 → 应用 → 用户消息 → AI 处理 → 应用 → 飞书回复

切换飞书：

9.4 消息队列

飞书消息会进入消息队列，按顺序处理：

10. 故障排除

10.1 常见问题

Q: 应用启动失败

A: 检查以下内容：

  1. 确认已安装 Visual C++ Redistributable (Windows)
  2. 确认端口 1420 未被占用
  3. 查看日志中的错误信息

Q: 模型无法连接

A:

  1. 检查 API 密钥是否正确设置
  2. 检查网络连接
  3. 尝试配置代理
  4. 查看模型配置是否正确

Q: 技能无法加载

A:

  1. 检查技能文件路径是否正确
  2. 检查技能文件格式是否正确 YAML
  3. 查看日志中的错误信息

Q: 飞书无法连接

A:

  1. 确认 App ID 和 Secret 正确
  2. 确认应用已启用 WebSocket
  3. 确认机器人已添加到群聊

10.2 重置配置

如需重置所有配置：

  1. 关闭应用
  2. 删除配置文件夹：
    • Windows: %USERPROFILE%\.zetaagent\
  3. 重新启动应用