【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除

背景

上篇 blog
【Agent】【OpenCode】bash 工具提示词（HEREDOC）
分析了最后剩下的 bash 工具提示词：分析所有改动，起草 PR 摘要，这里特意用三个感叹号强调，不能只看最新的那次提交，而是要看从主分支分叉出来以后得每次提交，并行执行，提升效率，然后分析了 HEREDOC（提示词特意要求用 HEREDOC 的格式来传递 PR 内容），这是个原封不动的多行文字包裹功能，从指定 EOF 开始，到指定的结束标记 EOF 出现之前，中间所有的内容都当成纯文本，原封不动保留下来，不进行内容解析，然后分析了内容打包的过程，接着提到了 PR 创建完成后，把生成的 PR URL 发给用户，方便用户直接点开查看检视，最后提示了 AI 可以用 gh api 命令去查看 PR 下的评论，下面继续分析

OpenCode

下面继续来看 bash 工具的参数说明

这里规定了 AI 在调用 bash 工具时，必须遵守的数据格式规范，是 AI 与 OpenCode 执行环境之间沟通的约定，下面来详细看下

首先是上面最外层的定义

"type": "object",
"additionalProperties": false

这里要求 AI 生成的参数，必须是一个 JSON 对象，并且 addtionalProperties: false 之前分析了，是 JSON 标准官方关键字，要求 AI 除了 properties 里面定义的属性之外，不能额外传入未定义的属性进来，否则 OpenCode 客户端会直接报错，拒绝执行

接着这个 Shcema 定义了 4 个核心字段，其中两个是必填，两个是选填

下面来详细看下

• command（核心指令）：这里是工具的灵魂，AI 必须在这里填入一条标准的 Linux Bash 命令，注意，这必须是字符串，而不能是数组，比如，不能写 ["git"，"status"]，而应该写 git status，这里的命令直接决定终端里跑什么代码
  
• description（人类可读的摘要）：这是给人看的，而不是给机器看的，提示词里给出了非常具体的例子，比如 ls：Lists files in current directory，强制要求 AI 必须用动词开头的短句，字数控制在 5 ~ 10 个词，需要 AI 进行高度概括，保证 UI 界面显示的整洁性，注意，这个也是必填项，意味着 AI 不能只写命令，而不写解释
  
• workdir（工作目录，环境上下文）：用来解决路径依赖问题，这里的默认路径是 opencode 命令运行的目录，这里也是之前提示词反复强调的，AI 可以通过 workdir 参数设定命令执行目录，而不能在 bash 工具里使用 cd 命令来随意改变工作目录，可选项，如果用户不需要在其他地方执行命令，就用默认路径执行
  
• timeout（安全熔断机制）：可选的，因为大多数比如 Git 命令（status，add，commit）等执行极快，而对于可能卡死的命令，比如网络请求，死循环脚本等，这个属性就很关键了，单位是毫秒，意味着 AI 需要判断任务的轻重缓急来设定超时时间，防止任务无限期挂起
  

从参数定义可以看到，OpenCode 这里将操作意图和操作动作分离了，传统模式下，AI 可能只输出命令（Action），而人类需要自己去猜为什么跑这个命令，而这里的参数中 description 承载了命令意图，command 则承载了具体的执行，这种设计让整个自动化流程变得可审计，可追踪，可解释，用户看到的也不仅仅是一串冰冷的代码，而是一个带有自然语言解释的操作日志

OK，本篇先到这里，如有疑问，欢迎评论区留言讨论，祝各位功力大涨，技术更上一层楼！！！更多内容见下篇 blog