backend-python/docs/structured_output_integration.md

# Agno Structured Output 集成技术文档

本文档记录了对后端生成服务（Generation Services）进行重构，集成 Agno `output_schema`（结构化输出）的技术细节与架构变更。

## 1. 为什么集成 Agno Structured Output?

在重构之前，系统面临以下挑战：

- **模型输出不稳**：不同的大模型（如 GLM, Gemini 等）可能会返回带有 Markdown 标签、Python 代码块或解释性文字的非标准内容。
- **解析代码脆弱**：原先使用正则表达式或简单的 `json.loads` 来提取数据，一旦模型返回格式稍有偏差（例如将字段名 `space_label` 改为 `space`），解析就会失败。
- **缺乏类型安全**：后端逻辑直接操作不确定的字典或字符串，容易引发运行时错误。

**集成 Agno 结构化输出的主要优势：**

- **强类型约束**：通过 Pydantic 模型（Schema）告诉 AI 需要填写的“表格”格式。
- **内建解析**：Agno 在底层自动处理格式校验和重试逻辑。
- **架构一致性**：核心生成逻辑统一走“Schema -> Object”链路。

## 2. 逻辑对比

### 2.1 重构前逻辑 (旧)

1.  **下发 Prompt**：手动在提示词里写“返回 JSON，包含 a, b 字段”。
2.  **获取文本**：从流式响应中累加 `full_content` 字符串。
3.  **手动解析**：用正则表达式尝试从 `full_content` 提取 JSON 或特定字段。
4.  **容错处理**：如果 JSON 报错，尝试一些简单的字符串截取。
5.  **返回结果**：返回一个字段缺失风险较高的字典。

### 2.2 重构后逻辑 (新 - 防御性双轨制)

1.  **定义 Schema**：在 `models/generation.py` 中定义 Pydantic 模型（如 `TitleSpaceResponse`）。
2.  **底层传递**：`StreamChatService` 将 Schema 传给 Agno 处理。
3.  **核心：防御性双轨获取结果**：
    我们**刻意保留并增强**了原有的 `safe_json_parse` 和正则表达式逻辑，形成了所谓的“防御性双轨制”：
    - **第一轨：Agno 结构化提取 (优先)**：直接从响应中提取 Agno 转换好的 Pydantic 对象。这是最理想的情况。
    - **第二轨：手动解析与正则兜底 (核心保险)**：
      - **为什么要保留？**：大模型（尤其是 GLM 等）是非确定性的。即便有 Schema 约束，它们偶尔仍会由于各种原因（如 Context 干扰、模型微调差异）返回纯文本、错误的 JSON 键名或 Python 风格的赋值语句（如 `title='...'`）。
      - **作用**：当 Agno 的内建解析器因为格式极其混乱而报错时，手动逻辑（`safe_json_parse` + 增强正则）会介入。这保证了**即使大模型“发疯”，应用层依然能顽强地从乱码中抠出关键数据**，而不是返回一个冷冰冰的错误或空结果。
4.  **归一化处理**：针对模型输出的细微偏差（如 `space_label` vs `spaceLabel`）或描述溢出进行最终清洗。

## 3. 做的主要变更

### 3.1 模型层 (`src/models/generation.py`)

- 新增了 `TitleResponse`, `TitleSpaceResponse`, `TitleSpaceAgentResponse`, `RelatedQuestionsResponse`, `DailyTipResponse` 五大 Pydantic 模型。
- 集成了 `field_validator` 来自动修复模型常见的表情符号返回格式问题。

### 3.2 基础服务层

- **`stream_chat.py`**: 增加了对 `output_schema` 的流式接收与封装，通过 `DoneEvent` 将结构化对象透传给业务层。
- **`llm_utils.py`**: 更新了 `run_agent_completion` 工具函数，确保它在任务完成时同时返回文本和结构化对象。

### 3.3 业务逻辑层 (`src/services/generation.py`)

- 重构了 5 个核心生成函数，使其完全支持 Agno 的结构化输出。
- 为每个函数增加了**防御性编程**逻辑：结构化解析 -> JSON 安全解析 -> 强力正则匹配 -> 归一化清洗。

## 4. 集成效果

| 功能模块            | 改进点                                                     |
| :------------------ | :--------------------------------------------------------- |
| **标题生成**        | 不再受 Markdown 块干扰，标题长度和表情更精准。             |
| **空间/Agent 识别** | 能够准确剥离描述语，确保返回的 Label 与数据库 100% 匹配。  |
| **相关问题**        | 解决了模型返回纯文本列表而非 JSON 导致按钮显示不出的顽疾。 |
| **每日贴士**        | 确保只返回干货文字，杜绝开场白和结束语。                   |

## 5. 结论

通过此次集成，系统将原本依赖“运气”和“正则”的解析逻辑，进化为一套**由模型驱动、由 Schema 约束、由代码兜底**的稳健传输体系。这不仅大幅提升了后端生成的成功率，也为未来支持更复杂的交互功能打下了坚实的基础。