# Butler-Shell 实施计划

> **Status:** ✅ Completed

**Goal:** 构建基于 Inngest 与 tmux 的持久化 Shell 助手，通过 QQ 接收指令并维护持久化会话

**Architecture:** 分层单体架构 - QQ Gateway → Inngest Workflows → Session Manager (TmuxWrapper) → tmux sessions

**Tech Stack:** Python 3.11+, Inngest (Python SDK), tmux, NapCatQQ (WebSocket), Pydantic, SQLite, FastAPI

**Spec:** `docs/superpowers/specs/2026-04-07-butler-shell-design.md`

**Detailed Plan:** `docs/superpowers/plans/2026-04-07-butler-shell-implementation.md`

---

## 实施阶段概要

### Phase 1: 核心会话层 (Chunk 1-3) ✅
- 项目基础设施
- 配置管理模块
- 核心数据模型
- 安全模块（认证、危险命令检测、敏感信息过滤）
- TmuxWrapper 核心类

### Phase 2: Skill 扩展系统 (Chunk 4) ✅
- Skill 基类和注册表
- LogSkill 实现
- SystemSkill 实现

### Phase 3: Inngest 工作流 (Chunk 5) ✅
- handle_message 工作流
- command_guardrail 审批流程

### Phase 4: QQ Gateway (Chunk 6) ✅
- NapCatQQ WebSocket 集成
- 消息转换

### Phase 5: 主入口和部署 (Chunk 7) ✅
- FastAPI 主入口
- Docker 部署配置
- Mock 测试脚本

---

## 关键文件清单

```
src/butler/
├── __init__.py
├── main.py                     # FastAPI 入口
├── config.py                   # 配置管理
├── session/
│   ├── state.py               # 数据模型
│   └── wrapper.py             # TmuxWrapper
├── security/
│   ├── auth.py                # 认证授权
│   ├── guardrail.py           # 危险命令检测
│   └── sanitizer.py           # 敏感信息过滤
├── skills/
│   ├── base.py                # Skill 基类
│   ├── log_skill.py           # 日志 Skill
│   └── system_skill.py        # 系统信息 Skill
├── workflows/
│   ├── handle_message.py      # 消息处理工作流
│   └── guardrail.py           # 审批工作流
└── gateway/
    └── napcat.py              # QQ Gateway
```

---

## 验证结果

| 检查项 | 状态 |
|--------|------|
| 测试 | ✅ 50 passed |
| Ruff | ✅ All checks passed |
| MyPy | ⚠️ 10 non-critical (type stubs) |
| 导入 | ✅ 成功 |

---

## 启动方式

```bash
# 启动服务
python -m butler.main

# 健康检查
curl http://localhost:8000/health

# Mock 测试
python scripts/mock_test.py normal "ls -la"
```