结构化输出引擎
> 下游程序最怕的：Agent 说"给你 JSON"。
> 这个引擎保证：输出过了校验才交付——解析失败率从 ~15% 降到接近 0。
Use when（什么时候用我）
- Agent 输出要对接下游程序（入库/调 API/喂给另一个 Agent）
- 需要严格格式保证（JSON/CSV/固定 schema）
- 输出频繁解析失败（"看着像 JSON 但不是"）
- 需要字段完整性保证（不丢字段）
- 批量任务需要输出一致性（同任务 100 次输出格式相同）
Triggers include
「结构化输出」「JSON」「Schema」「格式校验」「输出规范」「解析失败」「字段对齐」「数据入库」「枚举约束」「修复输出」
三大顽疾与对策
顽疾1：几乎-JSON（almost-JSON）
症状：输出带 markdown 代码块标记、中文引号、尾逗号、注释
对策：
① 输出前声明："只输出 JSON，无任何其他文字"
② 输出后清洗：剥 ```json 包裹、统一引号、去尾逗号
③ 校验器验证：json.loads() 必须成功
④ 失败→自动重试（附错误位置），最多2次
顽疾2：字段缺失/多余
症状：有时少字段、有时多字段、字段名大小写漂移
对策：
① 契约先行：先输出 schema（字段名+类型+必填）
② 逐字段检查：missing = required - output.keys()
③ 大小写归一：field_name.casefold() 匹配
④ 失败→按缺失清单补齐重试
顽疾3：格式漂移（同任务不同次输出）
症状：今天输出数组，明天输出对象；枚举值时不时冒出新的
对策：
① 枚举白名单：所有取值预定义，输出必须命中
② 模板锁定：few-shot 给 2 个正确样例
③ 漂移检测：连续 3 次输出的字段集合必须一致
自修复回路（核心机制）
生成 → 校验 → 失败？
├─ 是 → 修复模式匹配（清洗/补字段/枚举纠正）
│ → 重试（≤2次）→ 仍失败 → 输出错误报告（不静默）
└─ 否 → 交付
铁律：永不静默交付未校验的输出。校验失败就报告失败，不"差不多就行"。
输出模板库
JSON 交付协议
{
"_validate": {"schema_ver": "1.0", "generated_at": "..."},
"data": {...}
}
表格化输出（CSV/TSV）
- 首行表头固定
- 值内逗号转义（引号包裹）
- 空值用 null 而非空字符串
与普通"提示词"的区别
| 能力 | 普通提示词 | 本引擎 |
|---|---|---|
| 校验 | 靠模型自觉 | ✅ 强制过校验器 |
| 修复 | 重生成碰运气 | ✅ 模式化修复回路 |
| 字段保证 | 无 | ✅ 契约+逐字段检查 |
| 漂移控制 | 无 | ✅ 枚举白名单+漂移检测 |
| 失败行为 | 静默交付 | ✅ 报错不装死 |
安全红线
- 不静默降级——校验失败必须报错
- 修复不篡改语义——只修格式不编内容
- 输出含用户数据时提醒脱敏
文件结构
structured-output-engine/
├── SKILL.md # 本文件
├── references/
│ └── repair-patterns.md # 修复模式库（12 种常见破损模式）
└── scripts/
└── validate_output.py # 输出校验器（JSON+字段+枚举）
版本历史
- v1.0.0（2026-10-15）：首发。三大顽疾+自修复回路+校验器。
```
