# MyAgent 配置使用说明

> **版本**: v1.1.0
> **最后更新**: 2025年
> **适用平台**: Windows / macOS / Linux

---

## 目录

1. [项目简介](#1-项目简介)
2. [快速开始](#2-快速开始)
3. [模型API配置](#3-模型api配置)
4. [Agent管理系统](#4-agent管理系统)
5. [配置助手使用指南](#5-配置助手使用指南)
6. [执行引擎](#6-执行引擎)
7. [技能系统](#7-技能系统)
8. [记忆系统](#8-记忆系统)
9. [群聊功能](#9-群聊功能)
10. [Agent间通信](#10-agent间通信)
11. [组织功能](#11-组织功能)
12. [聊天平台接入](#12-聊天平台接入)
13. [自动更新](#13-自动更新)
14. [配置热重载](#14-配置热重载)
15. [常见问题 FAQ](#15-常见问题-faq)
16. [配置文件参考](#16-配置文件参考)
17. [命令行使用](#17-命令行使用)
18. [Web管理后台](#18-web管理后台)

---

## 1. 项目简介

**MyAgent** 是一款面向个人用户的本地桌面端执行型 AI 助手，采用多 Agent 协作架构设计，核心理念是将大语言模型（LLM）的能力直接延伸到用户的本地操作系统环境中。与云端 AI 服务不同，MyAgent 运行在用户的个人电脑上，能够在本地直接执行代码、操作文件、管理系统资源，实现真正的"AI + 本地执行"闭环体验。

项目的核心理念包括三个方面：**多 Agent 架构**——主 Agent、工具 Agent、记忆 Agent 各司其职，通过协调合作完成复杂任务；**本地执行优先**——所有代码和命令在用户本机运行，无需将数据上传到云端，响应速度更快；**隐私优先设计**——用户数据完全存储在本地 `~/.myagent/` 目录中，聊天记录、记忆数据、配置信息均不离开本机。即便接入远程 LLM API，用户的对话历史和本地文件内容也不会被发送到第三方服务。

MyAgent 当前版本为 **v1.1.0**，完整支持 **Windows、macOS、Linux** 三大主流操作系统平台，可通过系统托盘在后台常驻运行，也支持命令行交互模式。同时提供 Web 管理后台和多种聊天平台接入能力，满足不同使用场景的需求。

---

## 2. 快速开始

### 安装方式

MyAgent 提供两种安装方式，用户可根据自己的偏好选择：

**方式一：npm 全局安装（推荐）**

```bash
npm install -g myagent-ai
```

安装完成后，在终端中直接运行 `myagent` 即可启动。

**方式二：Git Clone 源码安装**

```bash
git clone https://github.com/your-org/myagent.git
cd myagent
pip install -r requirements.txt
python main.py
```

### 一键安装命令

各平台的一键安装命令如下：

```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/your-org/myagent/main/install/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/your-org/myagent/main/install/install.ps1 | iex
```

### 首次启动引导

首次运行 MyAgent 时，系统会自动进入配置引导流程：

1. **API Key 配置**：系统会提示你选择 LLM 提供商并输入对应的 API Key。支持 OpenAI、Anthropic (Claude)、Ollama（本地模型）、智谱 GLM 以及自定义兼容接口。如果你已经通过环境变量配置了 API Key，系统会自动检测并跳过此步骤。

2. **配置助手激活**：启动完成后，系统会自动激活内置的「配置助手」Agent。配置助手是一个专门设计用于帮助新用户了解软件功能、完成初始设置的智能引导 Agent。它会自动向你介绍 MyAgent 的核心功能，并逐步引导你完成模型选择、技能探索、Agent 创建等关键配置。

3. **默认配置生成**：首次启动时，系统会在 `~/.myagent/` 目录下自动生成默认配置文件 `config.json`，以及必要的数据目录（`data/`、`logs/`、`workspace/`）和权限配置文件（`permissions.json`）。用户可以随时通过 Web 管理后台或直接编辑配置文件来自定义设置。

---

## 3. 模型API配置

MyAgent 支持多种大语言模型提供商，用户可以根据自己的需求和预算灵活选择。系统支持以下五类模型接口：

### 支持的提供商

| 提供商 | provider 值 | 说明 |
|--------|------------|------|
| OpenAI | `openai` | GPT-4o、GPT-4、GPT-3.5 等 |
| Anthropic | `anthropic` | Claude 3.5 Sonnet、Claude 3 Opus 等 |
| Ollama | `ollama` | 本地运行的开源模型（Llama、Mistral 等） |
| 智谱 GLM | `zhipu` | GLM-4、GLM-5 等国产模型 |
| 自定义接口 | `custom` | 兼容 OpenAI API 格式的任意接口 |

### 配置文件方式

在 `~/.myagent/config.json` 中配置：

```json
{
  "llm": {
    "provider": "openai",
    "api_key": "sk-your-api-key-here",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-4o",
    "temperature": 0.1,
    "max_tokens": 4096,
    "timeout": 120,
    "max_retries": 3
  }
}
```

### ModelScope API 配置方式

ModelScope 是一个优秀的国内模型托管平台，提供多种高质量模型 API。使用 ModelScope 时，provider 设为 `custom`，并指定 ModelScope 的推理接口地址：

```json
{
  "llm": {
    "provider": "custom",
    "api_key": "your-modelscope-api-key",
    "base_url": "https://api-inference.modelscope.cn/v1",
    "model": "stepfun-ai/Step-3.5-Flash"
  }
}
```

**推荐模型列表**：

| 模型名称 | 特点 |
|---------|------|
| `stepfun-ai/Step-3.5-Flash` | 阶跃星辰，高性价比，响应速度快 |
| `ZhipuAI/GLM-5` | 智谱AI，中文能力强，适合复杂任务 |
| `Minimal/MiniMax-M2.5` | MiniMax，均衡性能，多模态支持 |
| `moonshotai/Kimi-K2.5` | Moonshot AI，长上下文，适合文档分析 |

### 环境变量方式

所有 LLM 配置项均可通过环境变量设置，优先级高于配置文件：

```bash
# 基础配置
export MYAGENT_LLM_PROVIDER="openai"
export MYAGENT_LLM_API_KEY="sk-your-key"
export MYAGENT_LLM_BASE_URL="https://api.openai.com/v1"
export MYAGENT_LLM_MODEL="gpt-4o"
export MYAGENT_LLM_TEMPERATURE="0.1"
export MYAGENT_LLM_MAX_TOKENS="4096"

# Anthropic 专用
export MYAGENT_ANTHROPIC_API_KEY="sk-ant-your-key"

# Ollama 本地模型
export MYAGENT_OLLAMA_BASE_URL="http://localhost:11434"
export MYAGENT_OLLAMA_MODEL="llama3"
```

### 模型库功能

MyAgent 支持在配置文件中添加多个模型定义，形成"模型库"。你可以为不同的 Agent 绑定不同的模型，实现精细化的模型分配策略。例如，可以让主 Agent 使用强大的 GPT-4o，而让记忆 Agent 使用性价比更高的 GPT-3.5。

```json
{
  "models_library": [
    {
      "id": "gpt-4o",
      "name": "GPT-4o (主力)",
      "provider": "openai",
      "model": "gpt-4o",
      "max_tokens": 4096,
      "temperature": 0.1,
      "enabled": true
    },
    {
      "id": "step-flash",
      "name": "Step-3.5-Flash (快速)",
      "provider": "custom",
      "base_url": "https://api-inference.modelscope.cn/v1",
      "model": "stepfun-ai/Step-3.5-Flash",
      "api_key": "your-key",
      "max_tokens": 4096,
      "temperature": 0.1,
      "enabled": true
    }
  ]
}
```

### 备用模型链

每个 Agent 可以配置一个主模型和多个备用模型。当主模型请求失败（如超时、API 限流、服务不可用）时，系统会自动切换到备用模型列表中的下一个模型继续执行，确保任务不会因单个模型的故障而中断。这一机制对生产环境和高可靠性需求场景尤为重要。

---

## 4. Agent管理系统

MyAgent 采用多 Agent 架构，允许用户创建和管理多个具备不同能力与角色定位的 Agent。系统内置了三个核心 Agent（MainAgent、ToolAgent、MemoryAgent），同时支持用户自定义创建任意数量的 Agent 来满足特定需求。

### Agent 层级结构

MyAgent 支持父子 Agent 的树形层级结构。父 Agent 可以向子 Agent 委派任务，子 Agent 完成后将结果返回给父 Agent。这种层级结构使得复杂任务可以被自然地分解为多个子任务，由不同专长的 Agent 协作完成。例如，一个"项目管理"Agent 可以将代码编写任务委派给"编程助手"Agent，将文档撰写任务委派给"写作助手"Agent。

### 创建 Agent

用户可以通过以下两种方式创建新 Agent：

- **Web 管理后台**：访问 `http://127.0.0.1:8765/ui/`，在 Agent 管理页面中点击"新建 Agent"，填写名称、描述、系统提示词等信息。
- **聊天界面创建**：直接在对话中告诉配置助手或主 Agent "帮我创建一个新的翻译助手 Agent"，系统会引导你完成配置。

### Agent 配置项

每个 Agent 包含以下可配置的核心属性：

| 配置项 | 说明 |
|--------|------|
| 名称 | Agent 的唯一标识名称 |
| 描述 | Agent 的功能描述，便于理解和搜索 |
| 系统提示词 (soul.md) | 定义 Agent 的核心行为模式和人格 |
| 身份 (identity.md) | 定义 Agent 的角色背景和专业领域 |
| 用户画像 (user.md) | Agent 对用户的理解（偏好、习惯等） |

### 执行模式

MyAgent 支持两种执行模式：

- **本机模式 (local)**：代码和命令直接在用户本机执行，拥有完整的系统权限，响应速度快，适合日常使用。
- **沙盒模式 (sandbox)**：通过 Docker 容器隔离执行代码，具有内存限制（默认 512MB）、CPU 限制（1 核）、进程数限制（64 个），且默认禁止网络访问。适合执行不可信代码或需要额外安全隔离的场景。当 Docker 不可用时，系统会自动回退到本机模式。

### 权限管理

每个 Agent 拥有独立的权限配置，可以精确控制其能力范围：

| 权限项 | 默认值 | 说明 |
|--------|--------|------|
| execution | 开启 | 代码执行（Shell/PowerShell/CMD/Python） |
| file_read | 开启 | 文件读取权限 |
| file_write | 开启 | 文件写入、删除、移动权限 |
| network | 开启 | 联网功能（搜索、HTTP 请求、API 调用） |
| local_comm | 开启 | 本机 Agent 间通信 |
| remote_comm | 关闭 | 跨电脑 Agent 通信（AICQ 中继） |

权限通过 `~/.myagent/data/permissions.json` 文件管理，支持全局默认权限和逐 Agent 覆盖。在 Web 管理后台中也可以直观地查看和修改各 Agent 的权限配置。

### 平台绑定

用户可以将特定 Agent 绑定到某个聊天平台（如 Telegram、Discord 等）。当用户在该平台发送消息时，绑定的 Agent 会自动响应。这允许你在不同平台上部署不同专长的 Agent，例如在 Telegram 上放置一个轻量问答 Agent，在 Discord 上放置一个代码助手 Agent。

### 系统内置 Agent：配置助手

「配置助手」是 MyAgent 的系统内置 Agent，负责新用户引导、配置说明、问题解答等工作。配置助手的核心配置（如系统提示词、权限设置）不可被用户修改，确保其始终能稳定地提供准确的配置指导。它的知识库中包含完整的配置使用说明文档，能够准确回答各种配置相关的问题。

---

## 5. 配置助手使用指南

### 概述

「配置助手」是 MyAgent 系统内置的智能引导 Agent，专为帮助用户快速上手和高效配置而设计。它拥有完整的配置知识库，能够准确回答关于 MyAgent 各项功能和配置的详细问题。与普通 Agent 不同，配置助手的核心配置受到系统保护，不会被用户意外修改，确保其引导功能的可靠性。

### 功能特性

配置助手提供以下核心功能：

1. **功能介绍**：自动或按需向用户介绍 MyAgent 的各项核心功能，包括执行引擎、技能系统、记忆系统、Agent 间通信等模块的能力和使用方法。

2. **配置引导**：在首次启动时自动激活，逐步引导用户完成 API Key 配置、模型选择、执行模式设置、权限管理等关键初始化步骤。对于高级配置项（如沙盒模式、跨电脑通信、组织知识库等），配置助手也会在适当时机向用户介绍和推荐。

3. **Agent 创建辅助**：帮助用户创建新的自定义 Agent，包括编写系统提示词、设置权限、选择模型、绑定聊天平台等。配置助手会根据用户的描述自动生成合适的 Agent 配置。

4. **问题解答**：针对用户在使用过程中遇到的各类问题，配置助手能够基于其内置知识库提供准确的解答。无论是如何更换模型、如何接入聊天平台、还是如何排查执行错误，配置助手都能给出具体的操作指导。

### 知识库

配置助手的知识库包含完整的配置使用说明文档（即本文档），涵盖了 MyAgent 的所有功能模块和配置项。知识库内容与软件版本同步更新，确保用户始终获取到最新、最准确的信息。

### 安全机制

配置助手在帮助用户修改配置时，会自动执行以下安全流程：

- **配置备份**：每次修改配置前，自动备份当前配置文件到 `~/.myagent/data/backups/` 目录，备份文件包含时间戳，便于回滚。
- **配置校验**：修改完成后，自动对配置文件进行格式验证和逻辑校验，确保 JSON 格式正确、必填字段完整、值范围合理。
- **原子写入**：使用"写入临时文件 → 重命名"的方式确保配置文件写入的原子性，避免写入过程中断导致配置损坏。
- **回滚机制**：如果校验失败，自动从最近的备份中恢复配置，确保系统始终处于可用状态。

### 面向 AI 助手的管理 API (Technical Guideline)

为了让配置助手能够自动管理系统，MyAgent 专门提供了一套简洁的 REST API：

- **Agent 管理**:
    - `POST /api/agents`: 创建顶级 Agent。JSON 参数: `{"name": "...", "description": "...", "system_prompt": "..."}`
    - `POST /api/agents/{parent}/children`: 在指定父级下创建子 Agent。
    - `PUT /api/agents/{path}`: 更新 Agent 基本配置。
    - `PUT /api/agents/{path}/soul`: 专门更新系统提示词 (soul.md)。
- **部门管理**:
    - `POST /api/departments`: 创建新部门。参数: `{"name": "...", "parent": "..."}`
    - `PUT /api/departments/{path}/agents`: 为部门分配 Agent 成员。参数: `{"agents": ["agent1", "agent2"]}`
- **配置操作**:
    - `POST /api/config/safe-save`: 安全保存主配置。

**重要准则**：
1. **配置大于代码**：Agent 和部门的创建应始终通过这些 API 或修改 `config.json` 实现。
2. **禁止修改源码**：严禁通过在 `agents/` 目录下编写新的 `.py` 文件来创建 Agent。
3. **隔离性**：新创建的 Agent 的数据应存放在 `data/agents/{name}/` 目录下。

---

## 6. 执行引擎

### 支持的语言

MyAgent 的执行引擎支持四种编程语言/命令行环境，覆盖了日常自动化的绝大多数场景：

| 语言 | 标识 | 适用场景 |
|------|------|---------|
| Python | `python` | 数据处理、文件操作、API 调用、自动化脚本 |
| Shell/Bash | `shell` / `bash` | 系统管理、文件操作、管道处理（Unix/macOS/Linux） |
| PowerShell | `powershell` | Windows 系统管理、Office 自动化、.NET 交互 |
| CMD | `cmd` | Windows 基础命令执行 |

系统还支持 `system` 标识，会根据当前操作系统自动选择合适的 Shell 执行命令。

### 安全特性

执行引擎内置了多层安全防护机制：

- **危险命令拦截**：通过正则表达式（含词边界匹配）和字符串黑名单双重检测，拦截 `rm -rf /`、`format C:`、`dd if=/dev/zero`、Fork Bomb 等危险操作。覆盖 Unix 和 Windows 两大类破坏性命令。
- **超时控制**：每个执行任务都有独立的超时设置（默认 300 秒），超时后进程会被强制终止，防止死循环或无限等待耗尽系统资源。
- **权限检查**：执行前会检查当前 Agent 是否拥有 `execution` 权限，无权限时直接拒绝执行。
- **输出长度限制**：执行输出最大长度默认为 50000 字符，防止大量输出占用内存。

### 自动修复

当代码执行失败时，执行引擎会尝试自动修复常见错误，大幅减少人工干预的需要：

**Python 自动修复（12 种模式）**：ModuleNotFoundError（自动 pip install）、ImportError（建议正确导入路径）、NameError（拼写检查和自动替换）、SyntaxError（自动补全括号）、TypeError（函数签名建议）、FileNotFoundError（路径建议）、PermissionError（权限提示）、ConnectionError（网络诊断）、UnicodeEncodeError（编码修复）、IndentationError（缩进修复）、KeyError（可用 key 建议）、JSONDecodeError（JSON 校验建议）。

**Shell 自动修复（4 种模式）**：command not found（跨平台命令别名建议）、No such file or directory（路径纠正）、Permission denied（chmod 提示）、syntax error near unexpected token（引号匹配修复）。

### 超时诊断

当命令执行超时时，系统会向 LLM 发送包含详细诊断信息的结构化消息，包括已产生的输出、标准错误内容、超时时长等。LLM 会分析可能的超时原因（死循环、数据量过大、网络等待、输入阻塞等），并给出具体的改进建议，如增加超时时间、优化算法、分批处理数据等。

### 沙盒模式

在沙盒模式下，所有代码在 Docker 容器中执行，提供额外的隔离保护。容器默认限制为 512MB 内存、1 个 CPU 核心、最多 64 个进程，且禁止网络访问。工作目录以只读方式挂载到容器内。如果需要网络访问，可通过配置 `sandbox_network: true` 开启。当 Docker 不可用时，系统会自动回退到本机执行模式并记录警告日志。

---

## 7. 技能系统

### 内置技能

MyAgent 内置了丰富的技能集，覆盖文件操作、网络搜索、系统管理、浏览器自动化等常用场景：

- **文件操作技能**：FileRead（文件读取）、FileWrite（文件写入）、FileList（目录列表）、FileDelete（文件删除）、FileSearch（文件搜索）、FileMove（文件移动）
- **网络搜索技能**：WebSearch（网络搜索）、WebRead（网页内容提取）、URLRead（URL 内容读取）
- **系统操作技能**：SystemInfo（系统信息）、ProcessList（进程列表）、CommandRun（命令执行）、EnvironmentGet（环境变量读取）、PathExpand（路径展开）
- **浏览器自动化技能**：BrowserOpen（打开网页）、BrowserClick（点击元素）、BrowserFill（填写表单）

### 外部技能

除了内置技能外，MyAgent 支持从 **OpenClaw 技能市场** 安装外部技能。外部技能可以扩展 MyAgent 的能力边界，例如文档生成（DOCX、PPTX、PDF）、图像处理、金融数据分析、视频理解、语音合成等。每个外部技能都有独立的 SKILL.md 说明文件，定义了技能的输入输出格式和使用方法。

### 技能调度

所有技能的执行由 MainAgent 统一调度。当用户提出需求时，MainAgent 会判断需要调用哪些技能，并将执行指令传递给 ToolAgent。ToolAgent 负责实际调用技能并返回执行结果。如果某个技能执行失败，MainAgent 会根据错误类型决定是重试、换用其他技能，还是向用户报告错误并请求进一步指示。

---

## 8. 记忆系统

### 三层记忆架构

MyAgent 的记忆系统采用三层架构设计，模拟人类记忆的工作方式：

**短期记忆（Short-term Memory）**：对应当前对话上下文，保存最近 N 轮对话（默认 50 轮）的用户消息和助手回复。短期记忆是 Agent 在对话中保持连贯性的基础，当对话轮数超过阈值时，系统会自动对早期对话进行摘要压缩，保留关键信息。

**工作记忆（Working Memory）**：保存当前任务的进度信息、执行步骤、中间结果等动态数据。工作记忆帮助 Agent 在多步骤任务中保持状态一致性，例如在执行一个复杂的数据处理流程时，Agent 需要记住已经完成了哪些步骤、当前正在处理什么、接下来还需要做什么。

**长期记忆（Long-term Memory）**：持久化存储用户偏好、技能使用经验、历史任务总结等重要信息。长期记忆跨越会话边界存在，即使用户关闭 MyAgent 后重新打开，之前积累的经验和偏好仍然可用。长期记忆存储在本地 SQLite 数据库中，默认路径为 `~/.myagent/data/memory.db`。

### 语义搜索

记忆系统内置了基于 TF-IDF 的语义搜索能力，支持中英文文本检索。用户或 Agent 可以通过自然语言描述来搜索历史记忆，系统会返回语义最相关的记忆条目。这使得 Agent 能够在长期记忆中快速找到与当前任务相关的历史经验，避免重复犯错或重复工作。

### 记忆管理

记忆系统具备自动管理能力：

- **自动淘汰**：当记忆条目数量超过上限（工作记忆默认 100 条）时，系统会根据访问频率和时间衰减策略自动淘汰不常用的记忆条目，确保记忆库的高效运行。
- **跨会话检索**：在新的对话会话中，Agent 仍然可以检索和引用历史会话中保存的长期记忆，实现经验积累和知识传承。
- **自动总结**：当对话轮数达到阈值（默认 20 轮）时，系统会自动对对话内容进行总结，将关键信息提取并保存到长期记忆中，防止重要信息在短期记忆滚动时丢失。

---

## 9. 群聊功能

MyAgent 支持创建 Agent 群组，实现多个 Agent 之间的群聊协作。群聊功能让多个 Agent 能够像团队成员一样在一个共享对话空间中交流信息和协同工作。

### 创建群组

用户可以通过 Web 管理后台或直接在对话中创建群组。创建时需要指定群组名称，并可以添加初始成员 Agent。创建后，群主（owner）可以随时添加或移除成员。

### 成员角色

群组中的每个成员拥有以下角色之一：

| 角色 | 权限 |
|------|------|
| owner（群主） | 添加/移除成员、修改群设置、解散群组 |
| admin（管理员） | 添加/移除成员、管理群消息 |
| member（普通成员） | 参与群聊、发送消息 |

### 群消息记录

群组中的所有消息都会被完整记录，包括发送者、时间戳、消息内容等。群消息记录支持历史查看和搜索，方便用户回顾 Agent 之间的协作过程和决策依据。群组数据存储在 `~/.myagent/data/` 目录下。

---

## 10. Agent间通信

MyAgent 实现了基于 **AICQ 协议** 的端对端加密通信系统，支持本机 Agent 间通信和跨电脑 Agent 间通信两种模式。所有通信内容均经过加密处理，确保消息的机密性和完整性。

### 本地通信（LocalChannel）

LocalChannel 用于同一台电脑上运行的 Agent 之间的通信。基于 asyncio.Queue 实现进程内消息传递，消息投递延迟极低（毫秒级别）。每个 Agent 启动时会自动在共享 Broker 中注册消息队列，其他 Agent 可以通过队列 ID 向其发送消息。本地通信默认开启，所有 Agent 均可使用。

### 跨电脑通信（RemoteChannel）

RemoteChannel 通过 AICQ 中继服务器实现跨电脑、跨网络的 Agent 通信。基于 WebSocket 长连接与中继服务器保持连接，支持自动重连和心跳检测。当接收方离线时，消息会被自动缓存到本地 SQLite 离线消息队列中，待接收方上线后自动重发。跨电脑通信默认关闭，需要手动启用并配置。

### 端对端加密

通信系统采用以下加密方案确保安全：

- **身份认证**：Ed25519 签名密钥对作为 Agent 的唯一身份标识，每条消息都附带签名，接收方可验证消息确实来自声称的发送方。
- **密钥交换**：X25519 Diffie-Hellman 密钥交换协议，每次与新的 Agent 通信时自动协商共享密钥。
- **消息加密**：AES-256-GCM 对称加密，确保消息内容在传输过程中的机密性和完整性。

### 通信配置

```json
{
  "communication": {
    "enabled": false,
    "server_url": "wss://aicq.online/ws",
    "agent_id": "",
    "private_key": "",
    "max_friends": 200,
    "auto_accept": false
  }
}
```

首次启用时，系统会自动生成 Ed25519 密钥对。将公钥分享给其他 Agent 即可建立加密通信通道。

---

## 11. 组织功能

MyAgent 支持组织级别的知识管理功能，适合团队或组织内部共享知识和协作使用。

### 组织知识库

组织知识库是面向整个组织的共享知识存储空间，支持上传文档、文本片段等知识内容。知识库中的内容可以被组织内的所有 Agent 检索和引用，为 Agent 提供统一的知识基础。知识库采用 RAG（检索增强生成）技术，在 Agent 回答问题时自动检索相关知识片段，提高回答的准确性和专业性。

### 组织信息

每个组织可以配置一个 `organization.md` 文件，描述组织的基本信息、业务领域、专有术语、协作规范等。Agent 在与组织成员交互时会参考这些信息，确保回复内容符合组织的风格和规范。

### 知识库管理员

组织可以指定一个"知识库管理员"角色（通过 Agent 路径指定，如 `"manager"`）。只有被指定为知识库管理员的 Agent 才有权限修改组织知识库的内容，其他 Agent 只能读取和检索。这一机制防止知识库被不当修改，保证组织知识的可靠性。

### 启用组织功能

```json
{
  "organization": {
    "enabled": true,
    "knowledge_admin": "manager"
  }
}
```

---

## 12. 聊天平台接入

MyAgent 支持将 Agent 接入多种主流聊天平台，使用户可以通过日常使用的通讯工具与 Agent 交互，无需打开专门的应用界面。

### 支持的平台

| 平台 | 标识 | 说明 |
|------|------|------|
| Telegram | `telegram` | 通过 Bot Token 接入 |
| Discord | `discord` | 通过 Bot Token 接入 |
| 飞书 | `feishu` | 通过 App ID + App Secret 接入 |
| QQ | `qq` | 通过 Bot Token 接入 |
| 微信 | `wechat` | 通过 Token 接入 |

### 平台绑定

每个聊天平台可以绑定不同的 Agent。例如，你可以将 Telegram 绑定到一个"日常助手"Agent，将 Discord 绑定到一个"编程助手"Agent，将飞书绑定到一个"工作助手"Agent。不同平台上的消息会被路由到对应的 Agent 进行处理。

### Token 配置方式

**配置文件方式**：

```json
{
  "chat_platforms": [
    {
      "enabled": true,
      "platform": "telegram",
      "token": "your-telegram-bot-token",
      "allowed_users": ["user_id_1", "user_id_2"]
    },
    {
      "enabled": true,
      "platform": "feishu",
      "app_id": "your-feishu-app-id",
      "app_secret": "your-feishu-app-secret",
      "webhook_url": "https://your-domain.com/webhook/feishu"
    }
  ]
}
```

**环境变量方式**：

```bash
export MYAGENT_TELEGRAM_TOKEN="your-telegram-bot-token"
export MYAGENT_DISCORD_TOKEN="your-discord-bot-token"
export MYAGENT_FEISHU_APP_ID="your-feishu-app-id"
export MYAGENT_FEISHU_APP_SECRET="your-feishu-app-secret"
export MYAGENT_QQ_TOKEN="your-qq-bot-token"
export MYAGENT_WECHAT_TOKEN="your-wechat-token"
```

通过环境变量配置的 Token 会自动创建对应的聊天平台配置条目并启用。

### 用户白名单

每个平台支持配置 `allowed_users` 白名单列表。当白名单为空时，所有用户均可与 Agent 交互；当白名单非空时，只有在白名单中的用户才能触发 Agent 响应，其他用户的消息会被忽略。

---

## 13. 自动更新

MyAgent 内置了自动更新机制，确保用户始终使用最新版本的软件。

### 版本检查

系统每小时自动检查一次是否有新版本可用（可通过配置调整检查间隔）。检查时会比对当前版本号与远程最新版本号，如果有新版本且当前没有正在执行的任务，会提示用户进行更新。版本号优先从环境变量 `MYAGENT_VERSION` 读取，其次从 git tag 获取，最后使用基线版本号。

### 热更新机制

MyAgent 支持多种更新类型，从轻量到重量依次为：

| 类型 | 说明 | 是否中断任务 |
|------|------|------------|
| CONFIG | 仅配置热重载 | 否（Agent 暂停后恢复） |
| CODE | 代码模块热重载（importlib.reload） | 否 |
| DEPENDENCY | 依赖包更新（pip install） | 否 |
| FULL | 全量更新（含进程重启） | 是（任务完成后重启） |

### 代码热重载

对于代码级别的更新（CODE 类型），系统使用 Python 的 `importlib.reload` 机制在不中断运行中的 Agent 任务的情况下更新代码模块。更新过程通过 ConfigBroadcaster 广播机制通知所有活跃 Agent 暂停，等待代码更新完成后自动恢复继续执行。这确保了长时间运行的任务不会因为代码更新而丢失进度。

### 更新后自动重启

全量更新（FULL 类型）会在所有任务完成后自动重启 MyAgent 进程。重启时通过环境变量标记（`MYAGENT_UPDATED=true`、`MYAGENT_UPDATED_FROM`、`MYAGENT_UPDATED_TO`）传递更新信息，启动后会自动检测并记录更新日志。

---

## 14. 配置热重载

### ConfigBroadcaster 广播机制

MyAgent 实现了基于 `asyncio.Event` 的配置热重载广播机制（ConfigBroadcaster），支持在不重启服务和中断任务的情况下动态更新配置。

工作流程如下：

1. **任务注册**：Agent 在开始执行任务时，会向 ConfigBroadcaster 注册自己的任务 ID。
2. **暂停检查**：Agent 在每次迭代循环中调用 `check_and_wait()` 方法，检查是否有配置重载请求。
3. **暂停等待**：如果有重载请求，Agent 会保存当前上下文状态（checkpoint）并暂停执行，等待配置更新完成。
4. **重载执行**：系统从配置文件重新加载配置，更新 LLM 客户端、执行引擎等组件的参数。
5. **恢复执行**：配置更新完成后，所有暂停的 Agent 从 checkpoint 恢复继续执行，使用新的配置参数。

整个过程基于异步事件驱动，无需轮询，效率极高。配置版本号（`reload_version`）在每次热重载后递增，Agent 可以根据版本号判断配置是否已更新。

### 确保配置变更不中断任务

配置热重载机制的核心价值在于确保配置变更不会中断正在执行的任务。无论是修改 LLM 参数（如切换模型、调整温度）、更改执行引擎设置（如超时时间、重试次数），还是更新权限配置，所有变更都会在当前迭代完成后安全地应用到下一个迭代中。如果某个任务正在执行代码，系统会等待代码执行完成后再应用配置变更，不会强制中断代码执行。

---

## 15. 常见问题 FAQ

### Q: 如何更换模型？

**A:** 有三种方式可以更换模型：

1. **配置文件**：编辑 `~/.myagent/config.json`，修改 `llm` 部分的 `provider`、`model`、`api_key`、`base_url` 等字段。
2. **环境变量**：设置 `MYAGENT_LLM_PROVIDER`、`MYAGENT_LLM_MODEL`、`MYAGENT_LLM_API_KEY` 等环境变量，重启 MyAgent 后生效。
3. **Web 管理后台**：访问 `http://127.0.0.1:8765/ui/`，在"模型设置"页面中切换模型。

配置支持热重载，修改后无需重启即可生效。如果使用模型库功能，可以为不同 Agent 分配不同模型。

### Q: 如何添加更多 Agent？

**A:** 你可以通过以下方式创建新的 Agent：

1. **Web 管理后台**：在 Agent 管理页面点击"新建 Agent"，填写名称、描述和系统提示词。
2. **对话创建**：直接在聊天中告诉配置助手你的需求，如"帮我创建一个翻译助手"，配置助手会引导你完成创建。
3. **手动配置**：在 `~/.myagent/data/` 目录下创建 Agent 配置文件，包含 `soul.md`（系统提示词）、`identity.md`（身份）和 `user.md`（用户画像）。

创建后可以为新 Agent 设置独立的权限、模型和聊天平台绑定。

### Q: 如何接入聊天平台？

**A:** 在 `~/.myagent/config.json` 的 `chat_platforms` 数组中添加平台配置，或通过环境变量设置 Token。以 Telegram 为例：在 `chat_platforms` 中添加 `{"enabled": true, "platform": "telegram", "token": "your-bot-token"}`，或在终端中执行 `export MYAGENT_TELEGRAM_TOKEN="your-bot-token"`。配置完成后重启 MyAgent，对应的 Bot 即会自动上线。

### Q: 如何导入/导出配置？

**A:** 通过 Web 管理后台的"配置导入/导出"功能，可以一键导出完整配置（支持脱敏处理，隐藏 API Key 等敏感信息），也可以从 JSON 文件导入配置。导入时支持"完全覆盖"和"合并模式"两种策略。合并模式下只覆盖有实际差异的字段，保留已有配置不变。此外，系统在每次修改配置前会自动备份到 `~/.myagent/data/backups/` 目录。

### Q: 执行命令超时怎么办？

**A:** 执行超时通常有以下几种原因和解决方案：

- **死循环或无限等待**：检查代码中是否存在没有退出条件的循环，或是否缺少必要的输入导致程序阻塞。
- **处理数据量过大**：尝试分批处理数据，或增加超时时间（在配置文件中修改 `executor.timeout`）。
- **网络请求超时**：检查网络连接状态，或为网络请求添加合理的超时参数。
- **默认超时时间不足**：通过配置文件将 `executor.timeout` 调大（如从 300 秒调整为 600 秒），或在执行时指定更大的超时值。

当命令超时时，MyAgent 会自动分析超时原因并给出改进建议。

### Q: 如何使用沙盒模式？

**A:** 在配置文件中设置 `executor.execution_mode` 为 `"sandbox"` 即可启用沙盒模式。沙盒模式需要预先安装 Docker。系统会在启动时自动检测 Docker 可用性，如果 Docker 不可用会回退到本机模式并记录警告。沙盒配置项包括：`sandbox_image`（Docker 镜像，默认 `python:3.12-slim`）、`sandbox_network`（是否允许网络，默认关闭）、`sandbox_memory`（内存限制，默认 `512m`）。

---

## 16. 配置文件参考

### 文件路径

| 类型 | 路径 | 说明 |
|------|------|------|
| 配置文件 | `~/.myagent/config.json` | 主配置文件（LLM、执行引擎、记忆系统等） |
| 数据目录 | `~/.myagent/data/` | Agent 数据、记忆数据库、权限配置等 |
| 日志目录 | `~/.myagent/logs/` | 运行日志文件 |
| 工作目录 | `~/.myagent/data/workspace/` | 默认文件操作工作区 |
| 配置备份 | `~/.myagent/data/backups/` | 配置文件自动备份 |

### 完整配置结构

以下是 `config.json` 的完整结构说明（含默认值）：

```json
{
  "llm": {
    "provider": "openai",
    "api_key": "",
    "base_url": "https://api.openai.com/v1",
    "model": "gpt-4",
    "temperature": 0.1,
    "max_tokens": 4096,
    "timeout": 120,
    "max_retries": 3,
    "anthropic_api_key": "",
    "ollama_base_url": "http://localhost:11434",
    "ollama_model": "llama3"
  },
  "memory": {
    "db_path": "",
    "max_short_term": 50,
    "max_working": 100,
    "auto_summarize": true,
    "summarize_threshold": 20
  },
  "executor": {
    "timeout": 300,
    "max_retries": 2,
    "auto_fix": true,
    "max_output_length": 50000,
    "execution_mode": "local",
    "sandbox_image": "python:3.12-slim",
    "sandbox_network": false,
    "sandbox_memory": "512m",
    "allowed_dirs": [],
    "blocked_commands": ["rm -rf /", "format", "del /f /s /q C:\\", "mkfs", "dd if=/dev/zero"]
  },
  "agent": {
    "max_iterations": 30,
    "max_parallel": 3,
    "verbose": true
  },
  "tray": {
    "auto_start": false,
    "show_notifications": true,
    "icon_path": ""
  },
  "organization": {
    "enabled": false,
    "knowledge_admin": ""
  },
  "communication": {
    "enabled": false,
    "server_url": "wss://aicq.online/ws",
    "agent_id": "",
    "private_key": "",
    "max_friends": 200,
    "auto_accept": false
  },
  "chat_platforms": [],
  "models_library": [],
  "log_level": "INFO",
  "data_dir": "",
  "language": "zh-CN"
}
```

---

## 17. 命令行使用

### 启动参数

MyAgent 支持以下命令行启动参数：

| 参数 | 说明 | 示例 |
|------|------|------|
| `--tray` | 以系统托盘模式运行（后台常驻） | `python main.py --tray` |
| `--web` | 启动 Web 管理后台（可指定端口） | `python main.py --web 8765` |
| `--port` | 指定 Web UI 端口（默认 8765） | `python main.py --port 9000` |
| `--autostart` | 设置开机自启 | `python main.py --autostart` |
| `--no-autostart` | 取消开机自启 | `python main.py --no-autostart` |
| `--config` | 指定配置文件路径 | `python main.py --config /path/to/config.json` |
| `--debug` | 启用调试模式（日志级别 DEBUG） | `python main.py --debug` |

### CLI 交互命令

进入 CLI 模式后，支持以下内置命令（直接在输入框中输入）：

| 命令 | 说明 |
|------|------|
| `help` | 显示帮助信息 |
| `status` | 查看系统状态（LLM、执行引擎、记忆、任务队列等） |
| `skills` | 列出所有已注册的技能（来自 aiskills 技能系统） |
| `memory` | 查看记忆系统统计（短期/工作/长期记忆条数） |
| `permissions` | 查看权限配置（全局默认 + Agent 自定义） |
| `sessions` | 查看当前会话信息 |
| `session <id>` | 切换到指定会话 |
| `clear` | 清除当前会话的对话历史 |
| `quit` / `exit` | 退出 MyAgent |

### 会话管理

MyAgent 支持多会话管理。每个会话拥有独立的对话历史和上下文。通过 `session <名称>` 命令可以在不同会话之间切换。不同的聊天平台消息也会被分配到独立的会话 ID 中，确保各平台之间的对话互不干扰。使用 `clear` 命令可以清除当前会话的对话历史（不影响长期记忆）。

---

## 18. Web管理后台

### 访问方式

Web 管理后台默认运行在本地 `http://127.0.0.1:8765/ui/`，可通过以下方式启动：

```bash
# 方式一：启动时指定 --web 参数
python main.py --web

# 方式二：使用 --tray 模式（默认开启管理后台）
python main.py --tray

# 方式三：自定义端口
python main.py --web 9000
```

启动后也可以通过系统托盘菜单中的"打开管理后台"选项快速访问。

### 功能模块

Web 管理后台包含以下功能模块：

| 模块 | 功能 |
|------|------|
| **仪表盘** | 系统运行状态概览（版本、运行时间、活跃任务数、记忆统计等） |
| **Agent 管理** | 创建/编辑/删除 Agent，配置系统提示词、权限、模型绑定 |
| **平台配置** | 管理聊天平台接入（Telegram、Discord、飞书、QQ、微信） |
| **会话管理** | 查看和清理会话记录 |
| **记忆管理** | 浏览搜索记忆条目，手动清理长期记忆 |
| **模型设置** | 配置 LLM 提供商、API Key、模型库管理 |
| **执行引擎** | 执行模式切换（本机/沙盒）、超时设置、安全配置 |
| **技能管理** | 查看已注册技能列表，安装外部技能 |
| **工作目录** | 文件浏览器，查看和管理工作目录中的文件 |
| **日志查看** | 实时查看运行日志，按级别筛选 |
| **配置导入/导出** | 一键导出完整配置（支持脱敏），从文件导入配置 |

### 聊天界面

除了管理后台，MyAgent 还提供了一个独立的聊天界面，访问地址为 `http://127.0.0.1:8765/ui/chat/chat_container.html`。聊天界面提供与 CLI 模式相同的对话功能，但拥有更丰富的界面展示（如 Markdown 渲染、代码高亮、执行结果展示等），适合需要可视化交互的场景。