Metadata-Version: 2.4
Name: tinychat-ai
Version: 0.1.5
Summary: A feature-rich yet lightweight terminal AI chat application designed for low resource consumption
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: tomli>=2.0.0
Requires-Dist: textual>=8.0.2
Requires-Dist: rich>=14.3.3
Requires-Dist: pyperclip>=1.11.0
Requires-Dist: tomli-w>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: respx>=0.20.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# TinyChat

轻量级终端 AI 聊天应用，支持多后端供应商，中英文双语界面。

## 特性

### 多后端支持
- **Ollama** - 本地 Ollama 服务器
- **OpenAI 兼容** - 支持 OpenAI 兼容的 API 服务

### 现代化终端界面
- 基于 [Textual](https://github.com/Textualize/textual) 框架
- 丰富的 Markdown 渲染和代码高亮
- 响应式布局，自适应终端尺寸
- 原生鼠标支持（点击、滚动）
- 多主题支持（明/暗主题）
- ESC 键停止流式响应
- 输入历史导航（上下方向键）

### 国际化
- 中文/英文双语界面
- 一键切换语言

### 会话管理
- 自动保存聊天历史
- 支持多会话切换
- 自动生成会话标题
- 流式响应实时显示
- 命令面板快速访问会话历史
- 会话列表对话框键盘导航
- 会话重命名和删除确认
- 跳过保存和加载空会话

### 工具系统（插件架构）
- 内置工具：read_file、write_file、exec_shell、edit_file、glob、grep、list_directory、todo_list
- 基于插件架构，支持通过 entry points 扩展
- 智能触发词系统，支持多语言
- 防滥用机制：系统提示规则、no_action 工具、动态过滤
- 工具执行结果实时展示
- Shell 工具命令白名单和环境变量清理
- 工具链式调用提示，支持多步骤工作流
- 全局持久化"始终允许"列表，渐进信任机制
- todo_list 工具集成工作流引擎

### 跨平台
- 支持 Windows、macOS、Linux
- 跨平台剪贴板支持

### 多后端支持增强
- 交互式侧边栏切换多个后端
- DeepSeek DSML 工具调用解析
- 后端切换时优雅处理认证错误

---

## 安装

### 系统要求
- Python 3.9+
- pip 或 uv 包管理器

### 从 PyPI 安装

```bash
pip install tinychat
```

### 从源码安装

```bash
git clone <repository-url>
cd tinychat

# 使用 pip
pip install -e ".[dev]"

# 或使用 uv
uv sync --extra dev
```

### 安装内置工具

内置工具提供文件读写、Shell 执行、搜索和工作流等功能，需单独安装：

```bash
pip install tinychat-builtin-tools
```

> 如从源码安装，可使用：`pip install -e "./packages/tinychat-builtin-tools"`

---

## 使用

### 启动应用

```bash
tinychat
```

或直接运行模块：

```bash
python -m tinychat
```

### 基本操作

1. **选择后端** - 在左侧边栏点击后端名称
2. **选择模型** - 在边栏点击模型名称
3. **发送消息** - 输入内容后按 Enter
4. **换行** - 按 Ctrl+Enter 插入换行
5. **滚动历史** - 使用鼠标滚轮或方向键

### 快捷键

| 按键 | 功能 |
|------|------|
| **Enter** | 发送消息 |
| **Ctrl+Enter** | 输入换行 |
| **Ctrl+L** | 切换语言 |
| **Ctrl+T** | 切换主题 |
| **Ctrl+Q** | 退出应用 |
| **Ctrl+P** | 命令面板 |
| **ESC** | 停止流式响应 |

---

## 配置

配置文件位于 `~/.config/tinychat/config.toml`（如不存在会自动创建）。

### 配置结构

```toml
[settings]
locale = "zh"  # 语言: "en" (英语) 或 "zh" (中文)

[[backends]]  # 可以配置多个后端
name = "backend-name"       # 后端显示名称
type = "backend-type"       # 后端类型
endpoint = "API地址"         # API 端点
default_model = "模型名"     # 默认模型
api_key = "密钥"            # API 密钥（可选）
```

### 后端类型详解

| 类型 | 说明 | API 端点示例 |
|------|------|--------------|
| `ollama` | 本地 Ollama 服务器 | `http://localhost:11434` |
| `openai-compatible` | OpenAI 兼容的 API 服务 | `https://api.example.com/v1` |

### 后端配置参数

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `name` | 字符串 | 是 | 后端显示名称，用于 UI 标识 |
| `type` | 字符串 | 是 | 后端类型：`ollama` 或 `openai-compatible` |
| `endpoint` | 字符串 | 是 | API 地址，需包含完整路径（如 `/v1`） |
| `default_model` | 字符串 | 是 | 默认使用的模型名称 |
| `api_key` | 字符串 | 否 | API 密钥（Ollama 不需要） |

### 配置示例

**Ollama 本地服务器：**

```toml
[[backends]]
name = "ollama-local"
type = "ollama"
endpoint = "http://localhost:11434"
default_model = "llama3.2"
```

**OpenAI 官方 API：**

```toml
[[backends]]
name = "openai"
type = "openai-compatible"
endpoint = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"
```

**vLLM / LM Studio / Text Generation WebUI 等 OpenAI 兼容服务：**

```toml
[[backends]]
name = "vllm-server"
type = "openai-compatible"
endpoint = "http://localhost:8000/v1"
api_key = "not-required"  # 多数本地服务不需要密钥
default_model = "meta-llama/Llama-2-7b-chat-hf"
```

**OpenRouter / Together AI 等云服务：**

```toml
[[backends]]
name = "openrouter"
type = "openai-compatible"
endpoint = "https://openrouter.ai/api/v1"
api_key = "sk-or-..."
default_model = "openai/gpt-3.5-turbo"
```

**Azure OpenAI Service：**

```toml
[[backends]]
name = "azure-openai"
type = "openai-compatible"
endpoint = "https://your-resource.openai.azure.com/openai/deployments/your-deployment"
api_key = "your-azure-api-key"
default_model = "gpt-35-turbo"
```

### 多后端配置

可以同时配置多个后端，通过 `name` 字段区分：

```toml
[settings]
locale = "zh"

[[backends]]
name = "ollama-local"
type = "ollama"
endpoint = "http://localhost:11434"
default_model = "llama3.2"

[[backends]]
name = "openai-cloud"
type = "openai-compatible"
endpoint = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"

[[backends]]
name = "vllm-server"
type = "openai-compatible"
endpoint = "http://localhost:8000/v1"
default_model = "meta-llama/Llama-2-7b-chat-hf"
```

启动后可在左侧边栏点击切换不同后端和模型。

---

## 开发

### 项目结构

```
tinychat/
├── src/tinychat/
│   ├── __main__.py           # 入口
│   ├── app_textual.py        # 主应用
│   ├── backends/             # 后端实现
│   │   ├── base.py          # 抽象基类
│   │   ├── ollama.py        # Ollama 后端
│   │   └── openai.py        # OpenAI 后端
│   ├── components/           # UI 组件
│   │   ├── chat_view_textual.py
│   │   ├── input_area_textual.py
│   │   ├── sidebar_textual.py
│   │   └── status_bar_textual.py
│   ├── models/               # 数据模型
│   ├── utils/                # 工具函数
│   │   ├── event_bus.py     # 事件系统
│   │   ├── i18n.py          # 国际化
│   │   └── theme_manager.py # 主题管理
│   ├── tools/               # 工具系统
│   │   ├── base.py          # 工具基类
│   │   ├── manager.py       # 插件管理器
│   │   ├── executor.py      # 工具执行器
│   │   └── adapter.py       # LLM 工具调用适配器
│   └── locales/              # 翻译文件
│       ├── en/LC_MESSAGES/
│       └── zh/LC_MESSAGES/
└── tests/                    # 测试
```

### 运行测试

```bash
# 运行所有测试
pytest tests/ -v

# 带覆盖率报告
pytest tests/ --cov=src/tinychat --cov-report=html

# 运行单个测试
pytest tests/unit/test_app_textual.py -v
```

### 代码检查

```bash
ruff check src/ tests/
ruff format src/ tests/
```

### 打包发布

```bash
# 安装构建工具
pip install build

# 构建
python -m build

# 生成的文件在 dist/ 目录
```

---

## 致谢

- [Textual](https://github.com/Textualize/textual) - 现代 TUI 框架
- [Rich](https://github.com/Textualize/rich) - 富文本渲染
- [httpx](https://www.python-httpx.org/) - HTTP 客户端

## 许可证

MIT License
