Metadata-Version: 2.4
Name: tinychat-builtin-tools
Version: 0.1.6
Summary: Built-in tools for TinyChat: file I/O, shell execution, search, and workflow
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: tinychat-ai

# tinychat-builtin-tools

TinyChat 的内置工具插件包，为 LLM 提供文件操作、Shell 执行、文件搜索和工作流管理能力。

## 安装

```bash
pip install -e "./packages/tinychat-builtin-tools"
```

本包依赖 `tinychat-ai`，需先安装主项目。

## 工具列表

### 文件操作

| 工具 | 说明 |
|------|------|
| `read_file` | 读取文本文件，支持 `offset`、`limit`、`tail` 参数 |
| `write_file` | 写入文件，自动创建父目录 |
| `edit_file` | 字符串替换编辑文件，支持 `replace_all` 批量替换 |

### 文件系统

| 工具 | 说明 |
|------|------|
| `list_directory` | 列出目录内容，子目录以 `/` 后缀标识 |

### 搜索

| 工具 | 说明 |
|------|------|
| `glob` | 按文件名模式查找文件（支持递归） |
| `grep` | 按正则表达式搜索文件内容，支持 `include` 文件过滤、`ignore_case`、`context` 上下文行、`max_count` 匹配上限 |

### Shell

| 工具 | 说明 |
|------|------|
| `exec_shell` | 执行 Shell 命令，支持 `timeout` 超时和 `working_directory` 工作目录 |

### 工作流

| 工具 | 说明 |
|------|------|
| `todo_list` | 管理待办事项列表和工作流（创建、执行、暂停、恢复、取消等） |

### 其他

| 工具 | 说明 |
|------|------|
| `no_action` | 显式退出通道，用于 LLM 在无需工具时直接回答 |

## Shell 安全

`exec_shell` 内置多层安全机制：

- **命令白名单**：仅允许预配置的命令执行，危险命令（`sudo`、`rm -rf /`、`mkfs` 等）始终被拦截
- **环境变量清理**：自动过滤敏感环境变量（`PATH`、`HOME` 等保留）
- **超时控制**：默认 30 秒超时，防止长时间运行

白名单配置通过 TOML 文件加载，详见 `shell_security.py` 和 `command_config.py`。

## 插件注册

工具通过 Python entry points 注册，在 `pyproject.toml` 中定义：

```toml
[project.entry-points."tinychat.tools"]
read_file = "tinychat_builtin_tools.files:ReadFileTool"
write_file = "tinychat_builtin_tools.files:WriteFileTool"
# ...
```

TinyChat 主程序启动时自动发现并加载所有已注册的工具。

## 项目结构

```
tinychat_builtin_tools/
├── __init__.py
├── files.py           # read_file, write_file, edit_file
├── fs.py              # list_directory
├── search.py          # glob, grep
├── shell.py           # exec_shell
├── shell_security.py  # 命令验证与环境变量清理
├── shell_defaults.py  # 默认安全命令白名单
├── command_config.py  # TOML 白名单配置加载
├── todos.py           # todo_list（待办事项 + 工作流）
└── no_action.py       # no_action
```

## License

MIT
