terco 🚀

Terco 是一个基于终端的 AI 助手，通过 OpenAI 兼容的 API（如 DeepSeek）驱动，支持函数调用（Function Calling）并内置了多种有用工具。

---

✨ 功能特性

• 🤖 多模型支持 — 兼容任何 OpenAI 格式的 API（DeepSeek、OpenAI、Azure OpenAI 等）
• 🛠️ 8 大内置工具 — 文件操作、Web 搜索、Shell 执行、Python 运行、天气查询等
• 🔒 安全授权机制 — 敏感操作（写文件、执行命令等）需用户确认，防止误操作
• 🎨 彩色终端输出 — 区分用户、助手、系统等不同角色的信息
• 💬 流式输出 — 类 ChatGPT 的逐字输出体验
• 📂 读写文件的路径保护 — 可配置敏感路径模式，读取敏感文件需授权

---

🗂️ 项目结构

terco/
├── main.py              # 主程序入口与核心对话循环
├── client.py            # OpenAI API 客户端配置
├── config.py            # 全局配置（颜色、系统提示词、环境变量）
├── conversation.py      # 对话消息管理
├── utils.py             # 工具函数（颜色化输出、获取时间）
├── .env                 # 环境变量配置文件（API Key 等）
├── .gitignore           # Git 忽略规则
├── tools/
│   ├── __init__.py      # 工具注册表与 OpenAI 工具定义
│   ├── files.py         # 文件读写、替换、搜索工具
│   ├── web.py           # 网页搜索与抓取工具
│   ├── shell.py         # Shell 命令执行工具
│   ├── python.py        # Python 代码执行工具
│   └── weather.py       # 天气查询工具（和风天气 API）
└── README.md

---

🚀 快速开始

1️⃣ 安装依赖

pip install openai python-dotenv

2️⃣ 配置环境变量

创建 .env 文件：

OPENAI_API_KEY=your_api_key_here
BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat
READ_AUTH_PATTERNS=.env,/etc/,~/.ssh/
HEFENG_API_KEY=your_hefeng_key_here   # 可选，用于天气查询

变量	说明	必填
OPENAI_API_KEY	API 密钥	✅
BASE_URL	API 地址（默认 DeepSeek）	✅
MODEL_NAME	模型名称	✅
READ_AUTH_PATTERNS	读取文件需授权的路径模式（逗号分隔）	❌
HEFENG_API_KEY	和风天气 API Key	❌

3️⃣ 启动

python main.py

---

🎮 使用指南

基本操作

启动后进入交互模式：

>> terco <<
Type /exit to quit, /clear to clear screen
--------------------------------------------------

You: 现在是几点？

命令

命令	功能
/exit 或 exit / quit	退出程序
/clear	清屏

用户授权

执行敏感操作（写文件、运行 Shell/Python 等）时，会弹出授权提示：

Authorize write(filepath='test.txt', content='Hello')? [y]es/[n]o/[a]ll: y

• y — 仅本次允许
• n — 拒绝
• a — 允许本次及后续所有操作（当前会话内）

---

🛠️ 内置工具一览

工具	功能	需要授权
get_current_time	获取当前日期时间	❌
search_web	搜索引擎查询（Bing/Baidu/DuckDuckGo）	❌
fetch_web	抓取并提取网页内容	❌
skill_weather	查询实时天气（和风天气）	❌
read	读取文件内容	⚠️ 条件性
grep	在文件中搜索文本	❌
write	写入文件	✅
replace	替换文件中的文本	✅
useshell	执行 Shell 命令	✅
run_python	执行 Python 代码	✅

条件性授权：read 工具仅在读取路径匹配 READ_AUTH_PATTERNS 中的模式时需要授权。

---

⚙️ 配置详情

config.py

• COLORS — 终端输出颜色映射
• SYSTEM_PROMPT — AI 系统提示词（可自定义助手行为）
• OPENAI_API_KEY / BASE_URL / MODEL_NAME — 从 .env 读取
• READ_AUTH_PATTERNS — 读文件授权路径模式
• HEFENG_API_KEY — 天气 API Key

自定义工具

要添加新工具：

1. 在 tools/ 下创建模块文件
2. 编写工具函数
3. 在 tools/__init__.py 中导入并注册到 TOOLS_REGISTRY 和 TOOL_DEFINITIONS
4. 如需授权，将工具名加入 AUTH_TOOLS 或 CONDITIONAL_AUTH_TOOLS

---

🔧 依赖

• Python ≥ 3.8
• openai — OpenAI API 客户端
• python-dotenv — 环境变量加载（可选但推荐）

---

📄 许可证

本项目基于 GPL-3.0-only 许可证开源。

本README由terco生成