tinychat-ai 0.1.5

A feature-rich yet lightweight terminal AI chat application designed for low resource consumption

TinyChat

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

特性

多后端支持

• Ollama - 本地 Ollama 服务器
• OpenAI 兼容 - 支持 OpenAI 兼容的 API 服务

现代化终端界面

• 基于 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 安装

pip install tinychat

从源码安装

git clone <repository-url>
cd tinychat

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

# 或使用 uv
uv sync --extra dev

安装内置工具

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

pip install tinychat-builtin-tools

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

---

使用

启动应用

tinychat

或直接运行模块：

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（如不存在会自动创建）。

配置结构

[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 本地服务器：

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

OpenAI 官方 API：

[[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 兼容服务：

[[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 等云服务：

[[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：

[[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 字段区分：

[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/                    # 测试

运行测试

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

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

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

代码检查

ruff check src/ tests/
ruff format src/ tests/

打包发布

# 安装构建工具
pip install build

# 构建
python -m build

# 生成的文件在 dist/ 目录

---

致谢

• Textual - 现代 TUI 框架
• Rich - 富文本渲染
• httpx - HTTP 客户端

许可证

MIT License