工具与审批

Hunea 在对话过程中，模型可以调用一组内置工具来完成读文件、改文件、执行命令、搜索代码、查看图片等工作，并在多轮调用后继续生成回复。

这一页说明用户侧会接触到的内容：有哪些工具、哪些需要审批、路径范围如何限制，以及审批面板如何操作。

工具相关的使用说明（tool guidelines）会参与 /prompt 的提示词组装；上下文占用也可以在 /context 中看到 Tool definitions 一项。本页补充的是运行时能力本身。

工作区边界

只读类工具（read / list_dir / view_image / grep / find）既能访问工作区内的路径，也能访问工作区之外已存在的路径。路径可以是相对工作区的路径，也可以是绝对路径；写类工具之外、工作区中不存在的路径会失败。

写类工具（write / edit）以及 bash 仍严格限定在当前工作区内：bash 默认在工作区中执行，可以指定 workdir，但仍要求落在工作区范围内。

因此建议在真正需要操作的项目目录中启动 Hunea，而不是在无关的上层目录中启动。

工具	作用	是否需要审批
`bash`	在工作区执行 shell 命令；合并 stdout 与 stderr；输出过长时会截断，完整内容可能写入临时文件	需要（Ask）
`read`	读取 UTF-8 文本；可用 `offset` / `limit` 分段读取；输出带行号	否（Always）
`write`	创建文件或整文件重写	需要（Ask），并提供 diff 预览
`edit`	按 `old_string` / `new_string` 做定点替换（可一次多处，但不可重叠）	需要（Ask），并提供 diff 预览
`list_dir`	列出目录下的直接子项（遵循 gitignore，包含点文件）	否
`view_image`	将本地图片（png / jpeg / gif / webp）作为多模态内容提供给模型（模型本身也要支持多模态）	否
`grep`	按内容搜索（优先使用 managed 或 `PATH` 中的 `rg`，否则使用内置 Rust backend）	否
`find`	按 glob 查找路径（使用内置 Rust backend，不依赖外部 `fd`）	否

使用上需要注意：

能用专用工具完成的事，优先使用 grep / find / list_dir / read，而不是一律改用 bash。专用工具有明确的路径边界和输出截断策略；bash 更适合管道、环境变量，以及专用工具无法覆盖的命令。
对已有文件使用 write / edit 前，通常需要先完整 read 过该文件。这是为了降低在未读取完整内容时直接改写的风险。
图片文件请使用 view_image，而不是 read（并且使用的模型本身也需要支持多模态，不然会报错）。
bash 输出有上限（大约最后 2000 行或 50KB）。截断时会尽量将完整输出保存到临时文件。
grep 优先使用系统 PATH 或 managed 的 rg，两者都不可用时退回内置 Rust backend；find 始终使用内置 Rust backend，无需额外安装 fd。建议系统安装 rg 以获得更快的 grep 搜索，参见快速开始。

权限策略大致分为两类：

Ask 工具弹出时，常见选项为：

操作方式：

需要注意：审批面板位于文档尾部区域。如果视口滚到上方查看历史消息，面板可能暂时不在可见范围内。

当视口不在底部时，左侧会显示常驻提示条，告知下方有未查看内容，避免在看不到选项时误操作：

两种提示条都可以鼠标左键直接点击，一键回到底部：点击后会先关闭遮挡的非审批类全屏层，再将视口跳回底部（恢复贴底跟随）并清除对应提示条；点击审批待办提示条时，回到底部后内联审批面板会重新可见并获得输入焦点。更多说明见非贴底保留视口与左侧提示。

调试用的 /tool-debug（需 debug.enabled = true）可以预览审批面板界面，但不属于常规使用路径；后续也可能移除或继续完善。

一次用户请求中，Agent 可以连续进行多轮工具调用。如果需要限制轮次，可配置：

[runtime]
# 默认不限制；设置为正整数后，超过该轮次会终止本次请求
tool_max_turns = 32

请求重试、idle timeout 等说明见config.toml中的 [runtime] 部分。

当前启用了哪些工具、对应 guidelines 的内容：见 /prompt 的 Tools 页签。该页签的 On 列可逐工具启用/禁用（禁用后不会出现在发送给模型的工具列表中），Guide 列控制是否注入该工具的使用指南；启停状态会持久化，主要面向下一次新会话。详见工具级启用/禁用。
工具定义占用的上下文：见 /context。
工具结果会进入会话树，因此 /tree 中可以看到 tool 节点；但 /copy 默认只列出用户消息与助手回复，不会把 tool / reasoning 一并列入拷贝列表。