claw-code 源码分析：结构化输出与重试——`structured_output` 一类开关如何改变「可解析性」与失败语义？

涉及源码：src/query_engine.py、src/runtime.py、src/main.py；Rustrust/crates/tools/src/lib.rs（StructuredOutput工具）；对照rust/crates/claw-cli/src/app.rs（OutputFormat，与 Python 开关不同名同源问题）。

1. 术语：仓库里至少有三条「结构化」线

下面分述主角与旁支，避免读源码时混为一谈。

2. Python：structured_output如何改变可解析性

2.1 配置项

# 15:21:src/query_engine.py@dataclass(frozen=True)classQueryEngineConfig:max_turns:int=8max_budget_tokens:int=2000compact_after_turns:int=12structured_output:bool=Falsestructured_retry_limit:int=2

• structured_output=False（默认）：submit_message里summary_lines用'\n'.join(...)拼成多行纯文本。对下游而言是非 JSON：整段 stdout 不能json.loads一次吃干净（除非自行截取）。
• structured_output=True：同一组summary_lines被包进对象{"summary": [...], "session_id": "..."}，再json.dumps(..., indent=2)→单文档合法 JSON 字符串（在序列化成功的前提下）。

# 152:159:src/query_engine.pydef_format_output(self,summary_lines:list[str])->str:ifself.config.structured_output:payload={'summary':summary_lines,'session_id':self.session_id,}returnself._render_structured_output(payload)return'\n'.join(summary_lines)

2.2 流式事件中的位置

stream_submit_message在message_delta里输出的text就是submit_message算出的result.output，因此开关同时改变 delta 载荷的可解析性：

# 120:121:src/query_engine.pyresult=self.submit_message(prompt,matched_commands,matched_tools,denied_tools)yield{'type':'message_delta','text':result.output}

message_stop里的usage/stop_reason仍是结构化 dict（Python 字面量），与structured_output无关。

2.3 CLI 打印形态

turn-loop子命令把result.output原样 print，前面只加 markdown 风格标题；不会再包一层 JSON：

# 153:158:src/main.pyifargs.command=='turn-loop':results=PortRuntime().run_turn_loop(args.prompt,limit=args.limit,max_turns=args.max_turns,structured_output=args.structured_output)foridx,resultinenumerate(results,start=1):print(f'## Turn{idx}')print(result.output)print(f'stop_reason={result.stop_reason}')

因此：

• 开启structured_output时，单轮 body是一段可json.loads的字符串，但整段 stdout仍含## Turn 1、stop_reason=...——整体不是单一 JSON。要做管道解析需按节切片或只解析print(result.output)那一段。
• 关闭时，body 为自然语言行，明确非 JSON。

3. 失败语义与重试：structured_retry_limit

3.1 重试只针对json.dumps

# 161:169:src/query_engine.pydef_render_structured_output(self,payload:dict[str,object])->str:last_error:Exception|None=Nonefor_inrange(self.config.structured_retry_limit):try:returnjson.dumps(payload,indent=2)except(TypeError,ValueError)asexc:# pragma: no cover - defensive branchlast_error=exc payload={'summary':['structured output retry'],'session_id':self.session_id}raiseRuntimeError('structured output rendering failed')fromlast_error

语义要点：

1. 触发条件：当前 payload 无法被json.dumps（例如summary_lines里混入了不可 JSON 化的对象——在正常路径里summary_lines全是str，该分支标注为pragma: no cover，属防御性）。
2. 重试行为：不重试同一 payload；而是替换为极小安全 payload（固定一句'structured output retry'+session_id），再试，最多structured_retry_limit次。
3. 最终失败：抛出RuntimeError('structured output rendering failed')，链上保留最后一次TypeError/ValueError。这是对调用方的硬失败；submit_message没有try/except 包住_format_output，故异常会冒泡，TurnResult不会生成。
4. 与业务stop_reason无关：max_turns/max_budget_reached等仍走正常TurnResult；序列化失败是异常路径，不是stop_reason。

3.2 早退路径与可解析性不一致

在max_turns已达时，output是直接格式化的英文句子，不走_format_output，因此即使structured_output=True，该轮也不会是 JSON：

# 68:77:src/query_engine.pyiflen(self.mutable_messages)>=self.config.max_turns:output=f'Max turns reached before processing prompt:{prompt}'returnTurnResult(prompt=prompt,output=output,...stop_reason='max_turns_reached',)

结论：structured_output只保证「正常摘要路径」下的 body 形态；错误/早退字符串仍可能破坏「每轮皆可json.loads」的假设——企业若要做严格 JSON 流水线，需在下游按stop_reason分支或统一包装 envelope。

4. Rust：StructuredOutput工具（与配置开关无关）

工具定义允许任意额外字段（additionalProperties: true），执行器把输入 map echo 到structured_output字段：

// 496:504:rust/crates/tools/src/lib.rsToolSpec{name:"StructuredOutput",description:"Return structured output in the requested format.",input_schema:json!({"type":"object","additionalProperties":true}),required_permission:PermissionMode::ReadOnly,},

fn execute_structured_output(input: StructuredOutputInput) -> StructuredOutputResult { StructuredOutputResult { data: String::from("Structured output provided successfully"), structured_output: input.0, } }

序列化走to_pretty_json→serde_json失败则Result::Err(String)，没有Python 那种「降级 payload + 多次重试」。失败语义是工具调用失败，由上层 runtime/对话环处理。

这与QueryEngineConfig.structured_output完全独立：前者是agent 工具链的契约，后者是Python port 的演示/测试输出格式。

5. 对照：CLIOutputFormat（Rust）

claw-cli在写出 turn 结果时按OutputFormat选择文本或 JSON 行，例如：

// 270:288:rust/crates/claw-cli/src/app.rsmatchself.config.output_format{OutputFormat::Text=>{writeln!(out,"\nToken usage: {} input / {} output",self.state.last_usage.input_tokens,self.state.last_usage.output_tokens)?;}OutputFormat::Json=>{writeln!(out,"{}",serde_json::json!({"message":summary.assistant_text,"usage":{"input_tokens":self.state.last_usage.input_tokens,"output_tokens":self.state.last_usage.output_tokens,}}))?;}

这里JSON 由代码构造，不依赖对模型输出做json.dumps；失败主要来自 IO，而非「内容不可序列化」。与 Python port 的structured_output+ 重试是不同问题域。

6. 小结表

设计启示：若企业需要稳定、可机器校验的每轮 envelope，仅靠当前structured_output不够（早退、CLI 装饰行、混用测试）。更稳妥的是在边界层（HTTP/SSE、子进程协议）定义固定顶层 JSON，把人类可读段落放进字段，而不是依赖「整段 print 即 JSON」。