tinychat-builtin-tools 0.1.9

Built-in tools for TinyChat: file I/O, shell execution, search, and workflow

tinychat-builtin-tools

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

安装

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 中定义：

[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