75、【Agent】【OpenCode】用户对话提示词（question 工具）

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

背景

分析了 skills 最后剩下的内容：构建回复内容，将信息整理成一段 AI 容易理解的文本，告诉 AI 什么是技能，并且技能怎么用，通过 Skill.fmt 方法将刚才获取的 list 格式化成人类和 AI 都容易读的字符串，接着开始介绍提示词中的工具内容，首先是第一个用户交互类工具 question，这个工具可以让 AI 在执行任务的过程中，遇到不确定的地方，或者需要用户做决定时，可以停下来询问用户，比如 AI 可能需要收集需求，澄清模糊指令，或者获取决策，这段提示词特别强调了选项的设计逻辑，比如自动包含自定义输入，选项的格式（单选/多选），以及推荐项等，接着介绍了 question 工具的参数定义，下面继续分析

OpenCode

下面接着看第一个属性 questions

再分析 questions 属性之前，可以看到 properties 下面还有个 required 参数，这个参数是个 array 数组类型，不过里面只有一个字段，也就是上面的 questions 属性，这里强调属性中的 questions 字段是必须提供的

下面来看属性中的核心内容 questions（问题列表），这里是 AI 真正需要填写的部分，另外，该属性是个 array 数组类型，意味着 AI 可以一次性向用户提出多个问题，下面来看里面具体的 items 信息

items 项下面有 4 个属性

type：每个问题都会作为一个对象存在
properties：每个问题下的具体属性
required：每个问题必须包含如下三个必填字段：question（完整问题），header（短标签），options（选项列表）
additionalProperties：这个比较重要，在 JSON Schema 中，addtionalProperties 是白名单之外的通行证（所谓白名单，就是指 OpenCode 在 properties 属性中定义的字段），addtionalProperties 决定了数据对象中，除了 OpenCode 明确列出的字段（比如 question，header）之外，是否还允许出现编外人员（也就是未定义的额外字段）

这里的 JSON 配置，可以看出来 OpenCode 使用的是严格模式 ，因为 addtionalProperties 字段控制着对象中，未在 properties 中定义的属性是否合法，下面看两种场景

additionalProperties: false（严格模式）：除了 JOSN 配置中列出来的，其他属性字段一律不准出现，如果 AI 返回的数据中，包含了 JSON 配置里没定义的字段，OpenCode 验证就会报错

比如在 parameters 层级，允许出现的属性只有 questions，而在 questions 层级，允许出现的属性就只有 question，header，option，multiple（非必须）了

而在 options: items 层级，允许出现的属性就只有 label 和 description 了

addtionalProperties: true（宽松模式，默认值）：只要用户定义的核心字段对了，其他的字段 AI 可以随便加，允许出现 JSON 配置中没提到的字段，验证依旧通过

举个例子，比如现在的 options: items 层级定义了属性必须有 label 和 description，并且设置了 additionalProperties: false，此时如果传入了一个 style 字段（JSON 配置里没定义的）

javascript 复制代码

{
  "label": "TypeScript",
  "description": "类型安全",
  "style": "bold"  // <--- 报错！因为 additionalProperties: false 禁止了未定义的字段
}

此时系统会提示类似【Additional property 'style' is not allowed】的错误，正确应该只包含 JSON 里定义的字段，比如

javascript 复制代码

{
  "label": "TypeScript",
  "description": "类型安全"
}

OK，本篇先到这里，如有疑问，欢迎评论区留言讨论，祝各位功力大涨，技术更上一层楼！！！更多内容见下篇 blog
【Agent】【OpenCode】用户对话提示词（addtionalProperties 属性）