Qwen Code 无头模式如何用 --json-schema 让最终回答输出符合指定 JSON Schema 的结构化结果【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code在脚本、CI/CD 或批处理流水线里跑 Qwen Code 无头模式时常见问题是模型的最终回答是自由文本下游程序没法直接解析。--json-schema参数解决的就是这个问题你提供一个 JSON SchemaQwen Code 会注册一个合成的终端工具内部名为structured_output模型被要求调用该工具并提交参数参数按你的 Schema 校验通过后校验过的载荷payload被输出到 stdout且第一次合法调用就结束本次运行。前提条件已安装 Qwen Code快速开始 中的方式例如npm install -g qwen-code/qwen-codelatest需要 Node.js 22 或更高并完成过一次模型服务商认证无头模式入口qwen -p …、位置参数 prompt或通过 stdin 管道传入 prompt 均可--json-schema与这三种方式都兼容该功能仅适用于无头运行不能与交互式 TUI 组合。一次最简运行直接在命令行内联 Schema结构化输出文档 给出的示例qwen --prompt Summarize the changes in HEAD with risk_level \ --json-schema { type: object, properties: { summary: { type: string }, risk_level: { type: string, enum: [low, medium, high] } }, required: [summary, risk_level], additionalProperties: false }默认--output-format text下stdout 的内容就是JSON.stringify(payload) \n——恰好一行、只含校验后的对象没有事件日志包裹文档示例输出形如{ summary: …, risk_level: low }可以直接管道给jq或其他消费方qwen --prompt Summarize the changes in HEAD with risk_level \ --json-schema ./schemas/summary.json | jq -r .risk_leveltext 模式下 stdout 在成功时只放 JSON 载荷失败时为空错误信息和日志走 stderr。因此下面这种捕获写法是安全的——失败不会污染捕获到的变量RESULT$(qwen --prompt Audit this diff --json-schema ./schemas/audit.json) || exit 1需要提醒text 模式会丢弃模型规划阶段的 incidental 文本如果你希望看到这些过程内容改用--output-format json或stream-json。Schema 怎么写、怎么传两种等价形式# 内联 JSON 字面量 qwen -p … --json-schema {type:object, properties:{…}} # 从文件读取 前缀 qwen -p … --json-schema ./schemas/summary.jsonpath形式会展开~、规范化路径并按utf8编码读取文件。文件在解析期会做以下校验不满足会直接报错校验项说明必须是普通文件不接受 FIFO、字符设备、目录文件大小上限 4 MiB超过基本是路径写错注意 Schema 会随每个模型请求下发大 Schema 按轮次成比例增加输入 token必须是合法 JSONpath输入的解析错误是通用提示content ofpathis not valid JSON不回显文件内容必须通过严格 Ajv 编译propertees这类拼写错误会被指出规范允许的写法如required未列出properties全部键被接受根必须接受 object 类型Gemini、OpenAI、Anthropic 的 function-calling 都要求工具参数是 JSON 对象非对象根会注册出一个不可用的工具关于根$ref解析期检查拒绝根上直接$ref。如果你的 Schema 用$ref复用定义把它包进allOf// 拒绝 { $ref: #/$defs/MyObj, $defs: { MyObj: { type: object, properties: { name: { type: string } } } } } // 接受根通过 allOf 分支接受对象 { allOf: [{ $ref: #/$defs/MyObj }], $defs: { MyObj: { type: object, properties: { name: { type: string } } } } }$ref出现在anyOf/oneOf/allOf内部时会推迟到运行期交给 Ajv所以包裹形式能过根检查。两个使用边界空 Schema{}是合法的stdout 会输出{}模型不带参数调用structured_output归一化路径把它变成空对象载荷。安全边界Schema 里的pattern关键词会被 Ajv 用 ECMAScript 正则引擎编译恶意构造的正则如(a)b配合模型给出的较长匹配值可能因灾难性回溯挂起 CLI。只使用你信任来源的 Schema。不同 --output-format 下如何取出结构化结果--output-formatstdout 内容取载荷的方式text默认JSON.stringify(payload) \n一行即校验后的对象直接解析整行或管道给jqjson一个 JSON 数组完整事件日志最后一个元素是type: result消息同时携带result字符串化和structured_result原始对象读数组最后一个元素取structured_result例如jq .[-1].structured_resultstream-jsonJSONL每事件一行终止的result行同样携带result与structured_result读最后一行type: result在两种 JSON 格式中要拿对象请优先读structured_resultresult是字符串化形式只为那些期望该字段恒为字符串的消费方保留。失败时的退出码与现象运行在第一次合法调用structured_output前结束。在此之前可能出现的分支参数校验失败structured_output返回带 Ajv 错误信息的工具结果模型下一轮看到后可修正参数再调用。注意每次校验失败重试都是一个完整的模型轮次会成倍增加 token 消耗。模型输出了普通文本而不是调用工具退出码1错误信息包含轮次数和模型输出的截断预览方便定位模型实际说了什么。达到--max-session-turns退出码53除标准 Reached max session turns 外还有--json-schema专属提示指向三种常见卡死原因模型从未调用该工具、structured_output被权限规则拒绝、Schema 不可满足。SIGINT / Ctrl-C 中断退出码130结构化结果通常不会输出以退出码为准。在--output-format json和stream-json下失败结果消息会写到stdout数组最后一个元素或 JSONL 流的终止result行。但并非所有失败模式都向 stdout 发 result——max-session-turns退出 53和信号中断退出 130只输出到 stderr。因此脚本应先检查退出码再用 result 对象上的is_error区分确实产生了 result 事件的那部分失败。哪些组合会被拒绝组合行为--json-schema-i/--prompt-interactive解析期拒绝合成工具的会话即刻结束语义在 TUI 循环里没有终结点--json-schema--input-format stream-json解析期拒绝单次终止契约与长驻 stream-json 输入协议不兼容--json-schema--acp/--experimental-acp解析期拒绝ACP 有自己的轮次循环不遵守合成工具终止契约--json-schema但没有 prompt 也没有管道 stdin解析期拒绝无头模式需要 prompt——用-p、位置参数或管道传入--bare--json-schema支持合成工具与 bare 三件套read_file、edit、run_shell_command一起注册在 subagent 内使用--json-schema工具不注册只有主运行/顶层 drain 轮次遵守终止契约权限侧structured_output有意绕过--core-tools白名单没有它就没有终止契约。但显式的permissions.deny规则和--exclude-tools仍然生效——两者都会阻止工具注册模型看不到该工具典型结果是模型用纯文本回答退出 1若模型在其他工具上打转最终撞maxSessionTurns退出 53错误信息里的--json-schema提示会指给你看。注意--bare会忽略大多数 settings 来源的配置含 settings 级permissions.deny与tools.exclude此时要用 argv 级--exclude-tools structured_output。另外如果某个 MCP server 恰好注册了名为structured_output的工具工具注册表冲突检查会把它改名为mcp__server-name__structured_output合成工具保留裸名模型看到的始终是你提供的 Schema。流水线示例用结构化结果做门禁文档给出的完整例子——把 diff 风险评级接到流水线判断上RESULT$(qwen --prompt Audit this diff and rate its risk. \ --json-schema ./schemas/audit.json) || exit 1 risk$(jq -r .risk_level $RESULT) if [ $risk high ]; then echo High-risk diff; pausing pipeline. 2 exit 2 fi运行预算与会话续跑结合无头模式的预算参数详见 Headless Modestructured_output不计入--max-tool-calls包括校验失败的情况它是我完成了的契约而非实际工作。因此卡在错误输出重试循环里的模型不受--max-tool-calls约束需要配合--max-session-turns或--max-wall-time封顶。structured_output计入--max-session-turns。想允许 N 轮实际工作把--max-session-turns设为N1预期会有重试时同样应调大该值。成功的运行有一个封顶约 500 ms 的关闭 holdback等待在途后台 agent 刷完最终通知没有后台任务时提前退出简单运行几乎无感但批量扇出数百次--json-schema调用的流水线要把这个上界算进去。--json-schema是每次运行per-run的 flag不是会话属性每次--continue/--resume都想要终止契约时都要重新传一遍--json-schema沿用原 Schema 是安全默认中途换 Schema 允许但改变了模型被约束的契约。不带该 flag 续跑时恢复的只是普通无头会话structured_output不存在模型用自由文本回答。最后一条内容边界Schema 本身会作为structured_output函数声明的parameters块随每个模型请求下发给服务商其中的字面值enum、const、default、examples、description等对服务商是明文。Schema 应保持描述形状与约束不要在其中写入密钥、客户记录等敏感内容调用参数在本地遥测和磁盘 chat-recording 中会被 redact 占位符替代但PreToolUse/PostToolUse/PostToolUseFailurehooks 看到的是未脱敏的原始参数。完整的参数说明、限制表格与隐私细节见 docs/users/features/structured-output.md无头模式的全部选项输出格式、预算参数、持久重试模式等见 docs/users/features/headless.md。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Qwen Code 无头模式如何用 --json-schema 让最终回答输出符合指定 JSON Schema 的结构化结果？
Qwen Code 无头模式如何用 --json-schema 让最终回答输出符合指定 JSON Schema 的结构化结果【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code在脚本、CI/CD 或批处理流水线里跑 Qwen Code 无头模式时常见问题是模型的最终回答是自由文本下游程序没法直接解析。--json-schema参数解决的就是这个问题你提供一个 JSON SchemaQwen Code 会注册一个合成的终端工具内部名为structured_output模型被要求调用该工具并提交参数参数按你的 Schema 校验通过后校验过的载荷payload被输出到 stdout且第一次合法调用就结束本次运行。前提条件已安装 Qwen Code快速开始 中的方式例如npm install -g qwen-code/qwen-codelatest需要 Node.js 22 或更高并完成过一次模型服务商认证无头模式入口qwen -p …、位置参数 prompt或通过 stdin 管道传入 prompt 均可--json-schema与这三种方式都兼容该功能仅适用于无头运行不能与交互式 TUI 组合。一次最简运行直接在命令行内联 Schema结构化输出文档 给出的示例qwen --prompt Summarize the changes in HEAD with risk_level \ --json-schema { type: object, properties: { summary: { type: string }, risk_level: { type: string, enum: [low, medium, high] } }, required: [summary, risk_level], additionalProperties: false }默认--output-format text下stdout 的内容就是JSON.stringify(payload) \n——恰好一行、只含校验后的对象没有事件日志包裹文档示例输出形如{ summary: …, risk_level: low }可以直接管道给jq或其他消费方qwen --prompt Summarize the changes in HEAD with risk_level \ --json-schema ./schemas/summary.json | jq -r .risk_leveltext 模式下 stdout 在成功时只放 JSON 载荷失败时为空错误信息和日志走 stderr。因此下面这种捕获写法是安全的——失败不会污染捕获到的变量RESULT$(qwen --prompt Audit this diff --json-schema ./schemas/audit.json) || exit 1需要提醒text 模式会丢弃模型规划阶段的 incidental 文本如果你希望看到这些过程内容改用--output-format json或stream-json。Schema 怎么写、怎么传两种等价形式# 内联 JSON 字面量 qwen -p … --json-schema {type:object, properties:{…}} # 从文件读取 前缀 qwen -p … --json-schema ./schemas/summary.jsonpath形式会展开~、规范化路径并按utf8编码读取文件。文件在解析期会做以下校验不满足会直接报错校验项说明必须是普通文件不接受 FIFO、字符设备、目录文件大小上限 4 MiB超过基本是路径写错注意 Schema 会随每个模型请求下发大 Schema 按轮次成比例增加输入 token必须是合法 JSONpath输入的解析错误是通用提示content ofpathis not valid JSON不回显文件内容必须通过严格 Ajv 编译propertees这类拼写错误会被指出规范允许的写法如required未列出properties全部键被接受根必须接受 object 类型Gemini、OpenAI、Anthropic 的 function-calling 都要求工具参数是 JSON 对象非对象根会注册出一个不可用的工具关于根$ref解析期检查拒绝根上直接$ref。如果你的 Schema 用$ref复用定义把它包进allOf// 拒绝 { $ref: #/$defs/MyObj, $defs: { MyObj: { type: object, properties: { name: { type: string } } } } } // 接受根通过 allOf 分支接受对象 { allOf: [{ $ref: #/$defs/MyObj }], $defs: { MyObj: { type: object, properties: { name: { type: string } } } } }$ref出现在anyOf/oneOf/allOf内部时会推迟到运行期交给 Ajv所以包裹形式能过根检查。两个使用边界空 Schema{}是合法的stdout 会输出{}模型不带参数调用structured_output归一化路径把它变成空对象载荷。安全边界Schema 里的pattern关键词会被 Ajv 用 ECMAScript 正则引擎编译恶意构造的正则如(a)b配合模型给出的较长匹配值可能因灾难性回溯挂起 CLI。只使用你信任来源的 Schema。不同 --output-format 下如何取出结构化结果--output-formatstdout 内容取载荷的方式text默认JSON.stringify(payload) \n一行即校验后的对象直接解析整行或管道给jqjson一个 JSON 数组完整事件日志最后一个元素是type: result消息同时携带result字符串化和structured_result原始对象读数组最后一个元素取structured_result例如jq .[-1].structured_resultstream-jsonJSONL每事件一行终止的result行同样携带result与structured_result读最后一行type: result在两种 JSON 格式中要拿对象请优先读structured_resultresult是字符串化形式只为那些期望该字段恒为字符串的消费方保留。失败时的退出码与现象运行在第一次合法调用structured_output前结束。在此之前可能出现的分支参数校验失败structured_output返回带 Ajv 错误信息的工具结果模型下一轮看到后可修正参数再调用。注意每次校验失败重试都是一个完整的模型轮次会成倍增加 token 消耗。模型输出了普通文本而不是调用工具退出码1错误信息包含轮次数和模型输出的截断预览方便定位模型实际说了什么。达到--max-session-turns退出码53除标准 Reached max session turns 外还有--json-schema专属提示指向三种常见卡死原因模型从未调用该工具、structured_output被权限规则拒绝、Schema 不可满足。SIGINT / Ctrl-C 中断退出码130结构化结果通常不会输出以退出码为准。在--output-format json和stream-json下失败结果消息会写到stdout数组最后一个元素或 JSONL 流的终止result行。但并非所有失败模式都向 stdout 发 result——max-session-turns退出 53和信号中断退出 130只输出到 stderr。因此脚本应先检查退出码再用 result 对象上的is_error区分确实产生了 result 事件的那部分失败。哪些组合会被拒绝组合行为--json-schema-i/--prompt-interactive解析期拒绝合成工具的会话即刻结束语义在 TUI 循环里没有终结点--json-schema--input-format stream-json解析期拒绝单次终止契约与长驻 stream-json 输入协议不兼容--json-schema--acp/--experimental-acp解析期拒绝ACP 有自己的轮次循环不遵守合成工具终止契约--json-schema但没有 prompt 也没有管道 stdin解析期拒绝无头模式需要 prompt——用-p、位置参数或管道传入--bare--json-schema支持合成工具与 bare 三件套read_file、edit、run_shell_command一起注册在 subagent 内使用--json-schema工具不注册只有主运行/顶层 drain 轮次遵守终止契约权限侧structured_output有意绕过--core-tools白名单没有它就没有终止契约。但显式的permissions.deny规则和--exclude-tools仍然生效——两者都会阻止工具注册模型看不到该工具典型结果是模型用纯文本回答退出 1若模型在其他工具上打转最终撞maxSessionTurns退出 53错误信息里的--json-schema提示会指给你看。注意--bare会忽略大多数 settings 来源的配置含 settings 级permissions.deny与tools.exclude此时要用 argv 级--exclude-tools structured_output。另外如果某个 MCP server 恰好注册了名为structured_output的工具工具注册表冲突检查会把它改名为mcp__server-name__structured_output合成工具保留裸名模型看到的始终是你提供的 Schema。流水线示例用结构化结果做门禁文档给出的完整例子——把 diff 风险评级接到流水线判断上RESULT$(qwen --prompt Audit this diff and rate its risk. \ --json-schema ./schemas/audit.json) || exit 1 risk$(jq -r .risk_level $RESULT) if [ $risk high ]; then echo High-risk diff; pausing pipeline. 2 exit 2 fi运行预算与会话续跑结合无头模式的预算参数详见 Headless Modestructured_output不计入--max-tool-calls包括校验失败的情况它是我完成了的契约而非实际工作。因此卡在错误输出重试循环里的模型不受--max-tool-calls约束需要配合--max-session-turns或--max-wall-time封顶。structured_output计入--max-session-turns。想允许 N 轮实际工作把--max-session-turns设为N1预期会有重试时同样应调大该值。成功的运行有一个封顶约 500 ms 的关闭 holdback等待在途后台 agent 刷完最终通知没有后台任务时提前退出简单运行几乎无感但批量扇出数百次--json-schema调用的流水线要把这个上界算进去。--json-schema是每次运行per-run的 flag不是会话属性每次--continue/--resume都想要终止契约时都要重新传一遍--json-schema沿用原 Schema 是安全默认中途换 Schema 允许但改变了模型被约束的契约。不带该 flag 续跑时恢复的只是普通无头会话structured_output不存在模型用自由文本回答。最后一条内容边界Schema 本身会作为structured_output函数声明的parameters块随每个模型请求下发给服务商其中的字面值enum、const、default、examples、description等对服务商是明文。Schema 应保持描述形状与约束不要在其中写入密钥、客户记录等敏感内容调用参数在本地遥测和磁盘 chat-recording 中会被 redact 占位符替代但PreToolUse/PostToolUse/PostToolUseFailurehooks 看到的是未脱敏的原始参数。完整的参数说明、限制表格与隐私细节见 docs/users/features/structured-output.md无头模式的全部选项输出格式、预算参数、持久重试模式等见 docs/users/features/headless.md。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
