wehub-resource-sync
231 lines
6.9 KiB
Markdown
231 lines
6.9 KiB
Markdown
# 自动 Title 生成功能实现总结
|
||
|
||
## ✅ 已完成的工作
|
||
|
||
### 1. 核心实现文件
|
||
|
||
#### [`packages/harness/deerflow/agents/thread_state.py`](../packages/harness/deerflow/agents/thread_state.py)
|
||
- ✅ 添加 `title: str | None = None` 字段到 `ThreadState`
|
||
|
||
#### [`packages/harness/deerflow/config/title_config.py`](../packages/harness/deerflow/config/title_config.py) (新建)
|
||
- ✅ 创建 `TitleConfig` 配置类
|
||
- ✅ 支持配置：enabled, max_words, max_chars, model_name, prompt_template
|
||
- ✅ 提供 `get_title_config()` 和 `set_title_config()` 函数
|
||
- ✅ 提供 `load_title_config_from_dict()` 从配置文件加载
|
||
|
||
#### [`packages/harness/deerflow/agents/middlewares/title_middleware.py`](../packages/harness/deerflow/agents/middlewares/title_middleware.py) (新建)
|
||
- ✅ 创建 `TitleMiddleware` 类
|
||
- ✅ 实现 `_should_generate_title()` 检查是否需要生成
|
||
- ✅ 默认使用本地 fallback 生成标题，避免流式回复结束前等待额外 LLM 调用；显式配置 `model_name` 时可使用 LLM 标题
|
||
- ✅ 实现 `after_model()` / `aafter_model()` 钩子，在首次对话后自动触发
|
||
- ✅ 包含 fallback 策略（LLM 未配置或失败时使用用户消息前几个字符）
|
||
|
||
#### [`packages/harness/deerflow/config/app_config.py`](../packages/harness/deerflow/config/app_config.py)
|
||
- ✅ 导入 `load_title_config_from_dict`
|
||
- ✅ 在 `from_file()` 中加载 title 配置
|
||
|
||
#### [`packages/harness/deerflow/agents/lead_agent/agent.py`](../packages/harness/deerflow/agents/lead_agent/agent.py)
|
||
- ✅ 导入 `TitleMiddleware`
|
||
- ✅ 注册到 `middleware` 列表：`[SandboxMiddleware(), TitleMiddleware()]`
|
||
|
||
### 2. 配置文件
|
||
|
||
#### [`config.yaml`](../../config.example.yaml)
|
||
- ✅ 添加 title 配置段：
|
||
```yaml
|
||
title:
|
||
enabled: true
|
||
max_words: 6
|
||
max_chars: 60
|
||
model_name: null # null = 快速本地 fallback；填模型名才启用 LLM 标题
|
||
```
|
||
|
||
### 3. 文档
|
||
|
||
#### [`docs/AUTO_TITLE_GENERATION.md`](../docs/AUTO_TITLE_GENERATION.md) (新建)
|
||
- ✅ 完整的功能说明文档
|
||
- ✅ 实现方式和架构设计
|
||
- ✅ 配置说明
|
||
- ✅ 客户端使用示例（TypeScript）
|
||
- ✅ 工作流程图（Mermaid）
|
||
- ✅ 故障排查指南
|
||
- ✅ State vs Metadata 对比
|
||
|
||
#### [`TODO.md`](TODO.md)
|
||
- ✅ 添加功能完成记录
|
||
|
||
### 4. 测试
|
||
|
||
#### [`tests/test_title_generation.py`](../tests/test_title_generation.py) (新建)
|
||
- ✅ 配置类测试
|
||
- ✅ Middleware 初始化测试
|
||
- ✅ TODO: 集成测试（需要 mock Runtime）
|
||
|
||
---
|
||
|
||
## 🎯 核心设计决策
|
||
|
||
### 为什么使用 State 而非 Metadata？
|
||
|
||
| 方面 | State (✅ 采用) | Metadata (❌ 未采用) |
|
||
|------|----------------|---------------------|
|
||
| **持久化** | 自动（通过 checkpointer） | 取决于实现，不可靠 |
|
||
| **版本控制** | 支持时间旅行 | 不支持 |
|
||
| **类型安全** | TypedDict 定义 | 任意字典 |
|
||
| **标准化** | LangGraph 核心机制 | 扩展功能 |
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
用户发送首条消息
|
||
↓
|
||
Agent 处理并返回回复
|
||
↓
|
||
TitleMiddleware.after_model()/aafter_model() 触发
|
||
↓
|
||
检查：是否首次对话？是否已有 title？
|
||
↓
|
||
默认从首条用户消息生成本地 fallback title
|
||
↓
|
||
如果显式配置 title.model_name，才调用 LLM 生成更精炼的 title
|
||
↓
|
||
返回 {"title": "..."} 更新 state
|
||
↓
|
||
Checkpointer 自动持久化（如果配置了）
|
||
↓
|
||
客户端从 state.values.title 读取
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 使用指南
|
||
|
||
### 后端配置
|
||
|
||
1. **启用/禁用功能**
|
||
```yaml
|
||
# config.yaml
|
||
title:
|
||
enabled: true # 设为 false 禁用
|
||
```
|
||
|
||
2. **自定义配置**
|
||
```yaml
|
||
title:
|
||
enabled: true
|
||
max_words: 8 # 标题最多 8 个词
|
||
max_chars: 80 # 标题最多 80 个字符
|
||
model_name: null # null = 快速本地 fallback；填模型名才启用 LLM 标题
|
||
```
|
||
|
||
3. **配置持久化（可选）**
|
||
|
||
如果需要在本地开发时持久化 title：
|
||
|
||
```python
|
||
# checkpointer.py
|
||
from langgraph.checkpoint.sqlite import SqliteSaver
|
||
|
||
checkpointer = SqliteSaver.from_conn_string("deerflow.db")
|
||
```
|
||
|
||
```json
|
||
// langgraph.json
|
||
{
|
||
"graphs": {
|
||
"lead_agent": "deerflow.agents:lead_agent"
|
||
},
|
||
"checkpointer": "checkpointer:checkpointer"
|
||
}
|
||
```
|
||
|
||
### 客户端使用
|
||
|
||
```typescript
|
||
// 获取 thread title
|
||
const state = await client.threads.getState(threadId);
|
||
const title = state.values.title || "New Conversation";
|
||
|
||
// 显示在对话列表
|
||
<li>{title}</li>
|
||
```
|
||
|
||
**⚠️ 注意**：Title 在 `state.values.title`，而非 `thread.metadata.title`
|
||
|
||
---
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行测试
|
||
pytest tests/test_title_generation.py -v
|
||
|
||
# 运行所有测试
|
||
pytest
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 故障排查
|
||
|
||
### Title 没有生成？
|
||
|
||
1. 检查配置：`title.enabled = true`
|
||
2. 确认是首次对话（1 个用户消息 + 1 个助手回复）
|
||
3. 如果显式配置了 `title.model_name`，检查标题模型是否可用；未配置时会走本地 fallback
|
||
|
||
### Title 生成但看不到？
|
||
|
||
1. 确认读取位置：`state.values.title`（不是 `thread.metadata.title`）
|
||
2. 检查 API 响应是否包含 title
|
||
3. 重新获取 state
|
||
|
||
### Title 重启后丢失？
|
||
|
||
1. 本地开发需要配置 checkpointer
|
||
2. LangGraph Platform 会自动持久化
|
||
3. 检查数据库确认 checkpointer 工作正常
|
||
|
||
### 中断首轮后仍显示默认标题？
|
||
|
||
1. `runtime/runs/worker.py` 会在 interrupted-run cleanup 中保持 run 处于 finalizing 状态，避免同线程新 run 在 fallback title 写入期间覆盖 checkpoint
|
||
2. 如果取消发生在可用 checkpoint 写入前，worker 会使用本次 `graph_input` 中的首条用户消息生成本地 fallback title
|
||
3. fallback title 写入前会重新读取 latest checkpoint；如果同线程状态已经前进，只对最新 snapshot 做 title-only 更新，避免旧消息重新成为 latest
|
||
|
||
---
|
||
|
||
## 📊 性能影响
|
||
|
||
- **默认延迟**：默认 `title.model_name: null` 不会发起额外 LLM 调用，仅从首条用户消息生成本地 fallback title
|
||
- **显式 LLM 标题延迟**：只有配置 `title.model_name` 时，首轮回复后才会等待一次标题模型调用
|
||
- **并发安全**：在 `after_model()` / `aafter_model()` 中更新 state，不需要客户端额外请求
|
||
- **资源消耗**：每个 thread 只生成一次
|
||
|
||
### 优化建议
|
||
|
||
1. 默认保持 `model_name: null`，避免流式回复结束前的额外 LLM 等待
|
||
2. 如需更精炼标题，再显式配置较快的标题模型
|
||
3. 减少 `max_words` 和 `max_chars`，并让 prompt 保持简洁
|
||
|
||
---
|
||
|
||
## 🚀 下一步
|
||
|
||
- [ ] 补充 prompt template 的集成测试
|
||
- [ ] 支持多语言 title 生成
|
||
- [ ] 添加 title 重新生成功能
|
||
- [ ] 监控 title 生成成功率和延迟
|
||
|
||
---
|
||
|
||
## 📚 相关资源
|
||
|
||
- [完整文档](../docs/AUTO_TITLE_GENERATION.md)
|
||
- [LangGraph Middleware](https://langchain-ai.github.io/langgraph/concepts/middleware/)
|
||
- [LangGraph State 管理](https://langchain-ai.github.io/langgraph/concepts/low_level/#state)
|
||
- [LangGraph Checkpointer](https://langchain-ai.github.io/langgraph/concepts/persistence/)
|
||
|
||
---
|
||
|
||
*实现完成时间: 2026-01-14*
|