# 🌀 echobot - 轻量级 AI 助手

一个轻量级的个人 AI 助手框架，支持多 LLM 提供商、多渠道接入、定时任务和多 Agent 协作。

## 特性

- 超轻量：核心代码量小，易读易改
- 快速启动：默认命令即可运行
- 多 LLM 支持：OpenRouter、Anthropic、OpenAI、MiniMax 等
- 多渠道：Telegram、DingTalk
- 工具调用：文件、命令、Web 等能力
- 安全边界：文件与命令默认限制在工作区
- 定时任务：内置 Cron 任务管理
- 多实例隔离：配置、会话、任务按实例隔离
- 多 Agent 协作：支持路由、绑定与 Agent 间调用

---

## 快速开始

### 1. 安装

```bash
git clone <your-repo-url>
cd echobot

# 方式1：安装脚本
chmod +x install.sh
./install.sh

# 方式2：开发模式安装
uv pip install -e .
```

### 2. 初始化配置

```bash
# 默认实例（~/.echobot/config.json）
echobot onboard

# 或指定实例（~/.echobot/instances/orchestrator/config.json）
echobot onboard --instance orchestrator
```

### 3. 启动网关

```bash
# 默认后台运行（daemon）
echobot gateway

# 前台运行（调试推荐）
echobot gateway --foreground --verbose
```

### 4. 本地直连 Agent（不走渠道）

```bash
# 单条消息
echobot agent -m "你好"

# 交互模式
echobot agent
```

---

## 命令总览

`echobot` 当前顶级命令：

- `gateway`：启动/停止/重启网关
- `agent`：直接与 Agent 对话
- `roles`：列出角色
- `onboard`：交互式初始化与配置
- `status`：查看状态
- `channels`：渠道管理入口（预留）
- `cron`：定时任务管理
- `instance`：实例管理
- `agents`：多 Agent 配置管理

常用全局选项：

- `echobot --version`：查看版本

---

## 命令详解

### `echobot gateway`

用途：启动网关（单 Agent 或多 Agent），支持后台守护与实例隔离。

常用参数：

- `--multi`：多 Agent 模式（读取 `agents.json`）
- `--instance/-i <name>`：使用指定实例
- `--daemon/--foreground`：后台/前台运行（默认后台）
- `--verbose/-v`：详细日志
- `--agents-config <path>`：指定 `agents.json` 路径
- `--stop`：停止后台进程
- `--restart`：重启后台进程
- `--daemon-log <path>`：自定义后台日志文件
- `--daemon-pid <path>`：自定义 PID 文件

示例：

```bash
# 默认实例后台启动
echobot gateway

# 前台调试
echobot gateway --foreground --verbose

# 多 Agent + 实例 + 后台
echobot gateway --multi --instance orchestrator --daemon

# 重启指定实例
echobot gateway --restart --instance orchestrator

# 停止指定实例
echobot gateway --stop --instance orchestrator
```

说明：后台启动后会输出 `PID`、`Port`、`Log`、`PID file`。

---

### `echobot agent`

用途：直接调用 Agent，常用于本地调试。

参数：

- `--message/-m <text>`：单条消息模式
- `--session/-s <id>`：会话 ID（默认 `cli:default`）
- `--role/-r <role>`：指定角色
- `--instance/-i <name>`：指定实例

示例：

```bash
# 默认会话发送消息
echobot agent -m "给我写一个 Python 函数"

# 指定角色和会话
echobot agent -m "审查这段代码" --role reviewer --session cli:review

# 进入交互模式
echobot agent
```

---

### `echobot roles`

用途：列出当前可用角色。

```bash
echobot roles
```

---

### `echobot onboard`

用途：交互式向导，完成初始化和配置。

参数：

- `--instance/-i <name>`：操作指定实例
- `--force/-f`：强制重新初始化

示例：

```bash
echobot onboard
echobot onboard --instance orchestrator
echobot onboard --instance orchestrator --force
```

---

### `echobot status`

用途：查看当前配置和基础状态。

```bash
echobot status
```

---

### `echobot cron`

用途：管理定时任务。

子命令：

- `cron list`：列任务
- `cron add`：加任务
- `cron remove`：删任务
- `cron enable`：启用/禁用任务
- `cron run`：手动执行任务

### `cron list`

参数：

- `--all/-a`：包含禁用任务
- `--instance/-i <name>`：指定实例

```bash
echobot cron list
echobot cron list --instance orchestrator --all
```

### `cron add`

参数：

- `--name/-n`：任务名（必填）
- `--message/-m`：发送给 Agent 的消息（必填）
- 调度方式三选一：
- `--every/-e <seconds>`：每 N 秒
- `--cron/-c "<expr>"`：Cron 表达式
- `--at "<ISO时间>"`：一次性任务
- `--deliver/-d`：执行后回投消息
- `--to <chat_id>`：回投目标
- `--channel <name>`：回投渠道
- `--instance/-i <name>`：指定实例

```bash
# 每10分钟执行
echobot cron add --name ping --message "状态检查" --every 600 --instance orchestrator

# 每天9点执行
echobot cron add --name morning --message "早报" --cron "0 9 * * *"

# 一次性执行
echobot cron add --name once --message "提醒" --at "2026-02-26T10:00:00"
```

### `cron remove`

```bash
echobot cron remove <job_id>
echobot cron remove <job_id> --instance orchestrator
```

### `cron enable`

```bash
# 启用
echobot cron enable <job_id>

# 禁用
echobot cron enable <job_id> --disable
```

### `cron run`

```bash
echobot cron run <job_id>
echobot cron run <job_id> --force --instance orchestrator
```

---

### `echobot instance`

用途：管理实例（实例隔离目录）。

子命令：

- `instance create <name>`：创建实例
- `instance list`：列实例
- `instance delete <name>`：删实例
- `instance copy <source> <target>`：复制实例

示例：

```bash
echobot instance create orchestrator
echobot instance list
echobot instance copy orchestrator orchestrator-backup
echobot instance delete orchestrator-backup --force
```

---

### `echobot agents`

用途：管理多 Agent 配置（`~/.echobot/agents.json`）。

子命令：

- `agents init`：交互式生成配置
- `agents list`：列出 Agent
- `agents add`：新增 Agent
- `agents bind`：新增路由绑定
- `agents enable` / `agents disable`：启停 Agent
- `agents remove`：删除 Agent
- `agents collaboration`：协作策略

### `agents init`

```bash
echobot agents init
echobot agents init --force
```

### `agents add`

参数：

- `--id/-i`：Agent ID（必填）
- `--name/-n`：展示名
- `--token/-t`：Telegram Token（Telegram 渠道需要）
- `--role/-r`：角色（默认 `default`）
- `--workspace/-w`：工作区
- `--channel/-c`：默认绑定渠道（`telegram` / `dingtalk`）

```bash
echobot agents add --id coder --name Coder --role coder --token "BOT_TOKEN"
```

### `agents bind`

参数：

- `AGENT_ID`：目标 Agent（必填）
- `--channel`：`telegram` / `dingtalk`
- `--chat-type/-c`：`private` / `group`
- `--mention/-m`：群聊 mention 关键字
- `--chat-id`：精确群/会话 ID（钉钉 `conversationId` 等）

```bash
# Telegram 群里 @coder 路由
echobot agents bind coder --channel telegram --chat-type group --mention coder

# DingTalk 私聊路由
echobot agents bind coder --channel dingtalk --chat-type private

# DingTalk 按 CID 精确路由（无需 @）
echobot agents bind coder --channel dingtalk --chat-type group --chat-id "cid_xxx"
```

### `agents list / enable / disable / remove`

```bash
# 列出所有 Agent
echobot agents list

# 启用/禁用
echobot agents enable coder
echobot agents disable coder

# 删除 Agent（会同时移除其 bindings）
echobot agents remove coder
```

### `agents collaboration`

参数：

- `--enable/--disable`：开启或关闭协作
- `--add "a,b"`：加入可调用白名单
- `--remove "a,b"`：移除白名单

```bash
echobot agents collaboration --enable --add coder,reviewer
echobot agents collaboration --remove reviewer
```

---

### `echobot channels`

当前为渠道管理入口，暂无可用子命令（预留扩展位）。

---

## 配置与目录

### 默认实例

- 配置：`~/.echobot/config.json`
- 工作区：`~/.echobot/workspace`
- Cron：`~/.echobot/cron/jobs.json`

### 命名实例（`--instance <name>`）

- 配置：`~/.echobot/instances/<name>/config.json`
- 工作区：`~/.echobot/instances/<name>/workspace`
- Cron：`~/.echobot/instances/<name>/cron/jobs.json`

### 多 Agent 配置

- 文件：`~/.echobot/agents.json`
- 说明：当前是全局文件，不按 instance 自动隔离
- 可选：通过 `echobot gateway --multi --agents-config <path>` 指定独立配置

### 后台日志与 PID

`gateway --daemon` 默认输出到实例数据目录，例如：

- 日志：`~/.echobot/instances/orchestrator/logs/gateway-multi-orchestrator_YYYY_MM_DD.log`
- PID：`~/.echobot/instances/orchestrator/gateway-multi-orchestrator.pid`

---

## DingTalk CID 直查

在钉钉会话中发送以下任一命令，机器人会直接回复当前会话 `cid` 和可复制的绑定命令：

- `查询cid`
- `查cid`
- `查看cid`
- `cid`
- `/cid`

推荐流程：

1. 在目标群发送 `查询cid`
2. 复制返回的 `echobot agents bind ... --chat-id "cid_xxx"`
3. 执行后重启网关生效（如需要）

---

## 多 Agent 推荐配置示例

`~/.echobot/agents.json`：

```json
{
  "agents": [
    {
      "id": "orchestrator",
      "name": "总控",
      "token": "YOUR_BOT_TOKEN",
      "role": "orchestrator",
      "workspace": "~/.echobot/agents/orchestrator",
      "enabled": true
    },
    {
      "id": "coder",
      "name": "Coder",
      "token": "YOUR_BOT_TOKEN",
      "role": "coder",
      "workspace": "~/.echobot/agents/coder",
      "enabled": true
    },
    {
      "id": "reviewer",
      "name": "Reviewer",
      "token": "YOUR_BOT_TOKEN",
      "role": "default",
      "workspace": "~/.echobot/agents/reviewer",
      "enabled": true
    }
  ],
  "collaboration": {
    "enabled": true,
    "allowCalls": ["coder", "reviewer"]
  },
  "bindings": [
    {
      "agentId": "orchestrator",
      "match": {
        "channel": "telegram",
        "chatType": "private"
      }
    },
    {
      "agentId": "coder",
      "match": {
        "channel": "telegram",
        "chatType": "group",
        "mention": "coder"
      }
    },
    {
      "agentId": "reviewer",
      "match": {
        "channel": "telegram",
        "chatType": "group",
        "mention": "reviewer"
      }
    }
  ]
}
```

---

## 角色系统

角色目录加载顺序：

- 项目内置：`<repo>/roles/`
- 用户目录：`~/.echobot/roles/`（同名覆盖内置）

常用命令：

```bash
# 列出角色
echobot roles

# 指定角色调用
echobot agent -m "帮我写代码" --role coder
```

---

## License

MIT
