【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除
背景
上篇 blog
【Agent】【OpenCode】bash 工具提示词（路径安全）
继续分析了禁止cd ... && command的原因：规避逻辑陷阱，确保命令执行在正确目录（由 OpenCode 的底层框架在调用系统 API 时切换目录，保证目标目录存并执行命令），防止命令注入，提升安全性（如果允许 AI 自由拼接 cd 命令，当目录路径中包含一些特殊字符时，很容易引发命令注入的漏洞），强制规范化，方便系统记录与调试（明确填写工作目录，这样系统日志非常清晰，出问题时也更容易排查），接下来继续分析了执行命令前的安全提醒：目录核实（如果接下来的命令是要创建新的文件夹或文件，AI 不能直接执行，必须先使用 ls 命令去检查一下父级目录是否存在），以及路径规范（强制 AI 要给带空格的路径加上双引号），在 Linux/Mac 终端里，如果文件路径中间有空格但没加引号，系统就会以为是两个分开的命令，下面继续分析
OpenCode
下面继续看bash工具使用说明
这里补充了四个细节：必选参数，超时设置，描述要求以及输出内容过多时的处理机制，下面详细看下：
- 命令必填：调用
bash工具时，command（要执行的命令）是必填项，不能空着 - 超时设置：AI 可以给命令执行设置一个最长运行时间（单位 ms），如果没设置，默认是 2 分钟（120000 ms），如果时间到了命令还没跑完，系统就会强制把它停掉，防止某个命令卡死导致整个程序一直等下去
- 描述要求：建议 AI 在调用
bash工具时，用 5~10 哥单词简单描述下这个命令是干啥的（比如 Install project dependencies），主要是为了方便用户在查看日志或调试时，能一眼看明白 AI 当时在干什么 - 输出内容过多时的处理机制（重点）：如果命令打印出来的结果太长了，超过了设定的最大行数
${maxLines}或最大字节数${maxBytes}，OpenCode 不会把这些内容全部塞进对话里，会自动把完整的输出内容保存到一个临时文件，并给 AI 展示前面的一小部分，想查看完整内容的话，OpenCode 提供了专门的read工具（后面介绍），配合 offset/limit 等参数可以读取特定段落，或者用grep命令去搜索想要的内容，所以执行命令的时候，不要用head，tail，或者其他命令去限制输出，因为完整的内容会保存在临时文件里
OK，接着继续
这里进一步强调了在日常操作中，AI 要尽量选 OpenCode 提供的专业工具，而不是直接调用 Bash 命令去执行 Linux 的原生命令，下面给出了更安全，更高效的替代方案
| 需求 | 尽量避免使用 Bash 命令 | 优先使用 OpenCode 专用工具 |
|---|---|---|
| 找文件 | find，ls | Glob（文件名模式匹配，速度更快） |
| 搜内容 | grep,rg | Grep（OpenCode 内置的正则搜索工具） |
| 读文件 | cat，head，tail | Read（专门的读取工具，支持行范围等） |
| 改文件 | sed，awk | Edit（精确编辑，保留上下文） |
| 写文件 | echo >，cat << EOF | Write（专门的文件创建，覆盖工具） |
| 输出文字 | echo，printf | 直接输出文本，不用调用命令 |
用这些专用工具替代，有如下考虑
- 安全可控：这些 OpenCode 专用的 Read，Write，Edit 等工具在底层实现时做了大量的权限检查和路径校验，防止 AI 误删文件或越权操作
- 提高效率：像 Glob 和 Grep 这种专用工具，底层往往经过了高度优化，比在 Bash 里直接跑原生命令效率更高，消耗的上下文 Tokens 更少
- 节省资源：如果
echo或printf只是想单纯输出一句话，完全没必要去启动一个 Shell 进程来执行，直接让 OpenCode 输出文本就像，既快又省事
所以最后总结下，这里就是给 AI 定了个规则：除非用户明确要求使用某个 Bash 命令，或者确实没有专用工具能够完成任务，那么就优先使用 OpenCode 内置的这些专用工具，而不是在 Bash 里执行各种 Linux 原生命令
OK，本篇先到这里，如有疑问，欢迎评论区留言讨论，祝各位功力大涨，技术更上一层楼！！！更多内容见下篇 blog
【Agent】【OpenCode】bash 工具提示词（git 提交规则）
)
