# Butler-Shell 使用说明

## 概述

Butler-Shell 是一个通过 IM (Telegram/QQ) 接收指令的持久化 Shell 助手。它维护远程服务器上的 tmux 会话，支持自然语言交互和原始命令执行。

## 交互模式

### 自然语言模式（默认）

直接用自然语言描述你想做的事情，LLM 会理解意图、生成命令、总结输出。

```
用户: 查看当前目录
回复: 当前目录下共有 12 个文件和 3 个子目录...

用户: 看下磁盘空间
回复: 磁盘使用率 65%，根分区还剩 120GB 可用空间...
```

### 原始命令模式（`!` 前缀）

以 `!` 开头的消息直接作为 shell 命令执行，跳过 LLM 理解和总结，返回原始终端输出。

```
用户: !ls -la
回复: (原始 ls -la 输出)

用户: !df -h
回复: (原始 df -h 输出)
```

危险命令检查仍然生效。

## 命令列表

| 命令 | 说明 |
|------|------|
| `!<命令>` | 原始命令模式，直接执行，返回原始输出 |
| `/new` | 新建会话（新 tmux session + 新 LLM 上下文） |
| `/list` | 列出所有会话 |
| `/enter <会话>` | 切换到指定会话（按编号或名称） |
| `/rename <名称>` | 重命名当前会话 |
| `/del <会话>` | 删除指定会话（按编号或名称） |
| `/clear` | 清理当前会话的 LLM 对话历史（保留 shell session） |
| `/help` | 显示使用说明 |

## 会话管理

每个会话由 **tmux session** + **LLM 对话上下文** 绑定组成：

- `/new` — 创建全新的 tmux session 和 LLM 上下文，旧会话保留
- `/list` — 查看所有会话，当前活跃会话标有 `*`
- `/enter 2` 或 `/enter myproject` — 按编号或名称切换到其他会话
- `/rename dev` — 给当前会话取一个好记的名字
- `/del 1` — 删除指定会话（同时销毁对应的 tmux session），不能删除唯一活跃会话
- `/clear` — 清空 LLM 对话历史，shell 环境不变。适用于上下文过长或话题切换时

### 会话管理示例

```
/new              → 已创建新会话: butler_user_2 (#2)
/rename dev       → 已重命名会话为: dev
/list             → 会话列表：
                     #1 butler_user
                     #2 butler_user_2 (dev) *
/enter 1          → 已切换到会话: butler_user
/del 2            → 已删除会话: dev
```

### 交互模式

当检测到 tmux 中运行了交互式程序（vim, top, python 等），自动切换到交互模式：

- 所有输入直接透传到 tmux
- 发送 `C-c`、`C-d` 等特殊按键
- 退出交互程序后自动恢复自然语言模式

## API 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 服务存活检查 |
| `/ready` | GET | 服务就绪检查（tmux + 通道状态） |
| `/api/mock/message` | POST | 模拟消息（测试用），body: `{"user_id": "...", "content": "..."}` |
| `/api/raw-output` | GET | 获取命令原始输出，参数: `user_id`, `limit` |
| `/api/approval` | POST | 处理审批响应，参数: `user_id`, `approved` |

### 响应格式

所有消息处理返回统一结构：

```json
{
  "reply": "自然语言总结或原始输出",
  "mode": "nl|raw|command|interactive|pending_approval|llm_error|unauthorized",
  "command": "实际执行的命令",
  "raw_output": "命令原始输出",
  "session_id": "butler_user123_1"
}
```

## 配置

通过 `.env` 文件或环境变量配置：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `ANTHROPIC_API_KEY` | LLM API 密钥 | 必填 |
| `ANTHROPIC_BASE_URL` | API 代理地址 | https://api.anthropic.com |
| `ANTHROPIC_MODEL` | 使用的模型 | claude-sonnet-4-20250514 |
| `TELEGRAM_BOT_TOKEN` | Telegram Bot Token | 可选 |
| `NAPCAT_WS_URL` | NapCatQQ WebSocket 地址 | 可选 |
| `BUTLER_ENABLED_CHANNELS` | 启用的通道 | `["telegram"]` |
| `BUTLER_ALLOWED_USERS` | 允许的用户 ID | 空=允许所有 |
| `BUTLER_GUARDRAIL_ENABLED` | 危险命令检查 | true |