# smart-term

**Repository Path**: fgai/smart-term

## Basic Information

- **Project Name**: smart-term
- **Description**: 使用大模型自动决定终端交互输入
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# smart-term

**smart-term** 是一个智能终端包装器。它在 PTY 中运行任意命令，实时监控输出，当程序等待输入时自动调用大模型生成回答——支持文本输入、y/n 确认、数字菜单选择等场景。

## 功能特性

- 透明 PTY 代理：程序的所有输出原样显示，无感知
- 自动检测输入请求：文本提示、[y/n] 问题、编号菜单
- 密码提示保护：检测到密码输入时跳过 LLM，要求手动输入
- 双模式：**确认模式**（默认）预填建议可编辑，**自动模式**直接发送
- 运行时按 `Ctrl+\` 切换两种模式
- 支持任意 OpenAI 兼容接口（OpenAI、Ollama、DeepSeek、SiliconFlow 等）
- 配置优先级：`.env` > 环境变量 > `~/.config/smart-term/config.toml`

## 文件说明

| 文件 | 说明 |
|------|------|
| `smart_term.py` | **单文件脚本**，直接 `python smart_term.py` 运行 |
| `smart_term/` | 包形式（模块拆分版），`pip install -e .` 安装后用 `smart-term` 命令 |
| `.env.example` | 配置模板，复制为 `.env` 后填写 |

## 快速开始（单文件模式，推荐）

```bash
# 安装依赖
pip install ptyprocess pyte openai rich click

# 配置
cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY 等

# 运行
python smart_term.py bash -c "read -p 'Name: ' n; echo Hello \$n"
```

## 安装为命令（包模式）

```bash
pip install ptyprocess pyte openai rich click
pip install -e .
# 之后可直接使用 smart-term 命令
```

## 快速配置

复制示例 `.env` 文件并填入你的 API 信息：

```bash
cp .env.example .env
```

编辑 `.env`：

```env
OPENAI_API_KEY=your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1   # 或其他兼容地址
SMART_TERM_MODEL=gpt-4o-mini
```

`.env` 文件会从**当前目录**自动加载。也可放到 `~/.smart-term.env` 作为全局默认配置。

### 使用 Ollama（本地模型）

```env
OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
SMART_TERM_MODEL=qwen2.5:7b
```

### 生成 TOML 配置文件

```bash
python smart_term.py --init-config
# 写入 ~/.config/smart-term/config.toml
```

## 使用

```bash
# 单文件模式
python smart_term.py [选项] <命令> [参数...]

# 包安装后
smart-term [选项] <命令> [参数...]
```

### 选项

| 选项 | 说明 |
|------|------|
| `--auto` | 自动模式：LLM 建议直接发送，无需确认 |
| `--model MODEL` | 覆盖 LLM 模型 |
| `--base-url URL` | 覆盖 API 地址 |
| `--timeout MS` | 空闲超时（毫秒），默认 300 |
| `--cooldown MS` | 收到输出后的等待时间（毫秒），默认 15000 |
| `--context-lines N` | 发给 LLM 的历史行数，默认 40 |
| `--init-config` | 生成示例配置文件后退出 |

### 示例

```bash
# 文本输入提示
python smart_term.py bash -c "read -p 'Enter name: ' n; echo Hello \$n"

# y/n 确认
python smart_term.py bash -c "read -p 'Continue? [y/n] ' r; echo \$r"

# 数字菜单（如 npm init）
python smart_term.py npm init

# 包安装确认（自动模式）
python smart_term.py --auto pip install requests

# 使用不同模型
python smart_term.py --model gpt-4o python setup.py
```

### 运行时快捷键

| 按键 | 功能 |
|------|------|
| `Ctrl+\` | 切换自动/确认模式 |
| `Ctrl+T` | 重置任务历史，恢复自动化（任务完成后使用） |
| `Ctrl+C` | 终止子进程并退出 |

### 确认模式交互

当检测到输入请求时，会显示：

```
╭─ smart-term ──────────────────────────────────────╮
│ LLM suggests (y/n answer): y                      │
│ Press Enter to accept, or type a replacement:     │
╰────────────────────────────────────────────────────╯
> _           ← 光标在此，已预填 "y"，可直接回车或修改
```

## 配置参考

### .env 文件变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENAI_API_KEY` | API 密钥（必填） | — |
| `OPENAI_BASE_URL` | API 基础地址 | `https://api.openai.com/v1` |
| `SMART_TERM_MODEL` | 模型名称 | `gpt-4o-mini` |
| `SMART_TERM_AUTO` | 自动模式（`true`/`false`） | `false` |
| `SMART_TERM_TIMEOUT` | 空闲超时（毫秒） | `300` |
| `SMART_TERM_COOLDOWN` | 输出冷却时间（毫秒） | `15000` |
| `SMART_TERM_CONTEXT_LINES` | 发给 LLM 的上下文行数 | `40` |

### 配置优先级（从低到高）

```
~/.config/smart-term/config.toml
    ↓
~/.smart-term.env
    ↓
.env（当前目录）
    ↓
环境变量
    ↓
命令行参数（--model、--auto 等）
```

## 架构

```
用户键盘输入
    │
    ▼ (stdin 转发线程)
PtyManager ──写入──► 子进程 (PTY)
    │                    │
    │◄────── 输出 ───────┘
    │
    ├──► TUI.write_passthrough() ──► 用户终端（透传）
    │
    └──► ScreenParser (pyte VT100 解析)
              │
              │ 空闲 300ms
              ▼
         InputDetector
              │
         ┌───┴───────────────┐
         │                   │
       PASSWORD           TEXT / YES_NO / NUMBERED
         │                   │
      提示手动输入        LLMClient.get_answer()
                             │
                    ┌────────┴────────┐
                  自动模式          确认模式
                    │                │
               直接发送         显示建议 → 用户确认
                    │                │
                    └────────┬───────┘
                             ▼
                      PtyManager.write()
```