sync update from LAN repo (source dhk-1 @ 3e87be55)

This commit is contained in:
gozeros committed 2026-10-21 15:06:08 +08:00
1 parent ab6068a7c1
commit 42f2a26fa8
1482 files changed
+227759 -9584

No files matched your search

@@ -0,0 +1,161 @@
# 智能体回答评价与用户反馈评分规范
## 1. 定位
本功能采集用户对**单条智能体回答**的直接评价,并聚合为智能体的“用户评价分”。
它回答的是:
> 用户是否认可这个智能体已经给出的回答,以及负面体验主要集中在哪些方面?
它不等同于完整的智能体能力评测。工具选择、Skill 增益、执行轨迹、事实基准、成本、稳定性和多智能体协作仍需独立的离线评测或运行指标,不能用本分数替代。
## 2. 单条回答的评价入口
每条可评价的最终 AI 回答提供两种选择:
- `回答优秀`:记为正向评价 `rating = 1`。
- `回答不佳`:记为负向评价 `rating = -1`,且必须至少选择一个原因。
负向原因采用固定枚举:
| 枚举 | 展示文案 | 统计归属 |
|---|---|---|
| `incorrect_or_incomplete` | 不正确或不完整 | 正确性、完整性、证据支撑 |
| `unmet_expectations` | 与期望不符 | 相关性、可执行性 |
| `slow_or_problematic` | 速度慢或存在问题 | 性能/可靠性问题分布 |
| `style_or_tone` | 风格或语气 | 表达体验问题分布 |
| `safety_or_legal` | 安全或法律疑虑 | 安全合规问题分布 |
| `other` | 其他 | 其他问题分布 |
用户可以补充自由文本详情。正向评价不携带负向原因;同一用户对同一条回答重复提交时更新原评价,不重复计数。
回答所属智能体必须由服务端根据 `run`、线程和消息记录确定,不能接受前端自行指定的归属。
## 3. 汇总指标
设:
- `P`:正向评价数;
- `Q`:负向评价数;
- `N = P + Q`:有效评价样本数;
- 贝叶斯先验:`alpha = 8`、`beta = 2`,即 10 个等效样本、80 分的中性偏正先验。
### 3.1 原始任务成功率
当 `N > 0` 时:
```text
task_success_rate = 100 × P / N
```
这是没有平滑的真实好评率,必须与样本数一起展示。
### 3.2 用户评价分
当 `N > 0` 时:
```text
score = 100 × (P + alpha) / (N + alpha + beta)
= 100 × (P + 8) / (N + 10)
```
该分数使用贝叶斯平滑,避免只有一两条反馈时直接出现 0 分或 100 分。`N = 0` 时返回 `null`,界面展示“暂无评价”,不得把先验 80 分当作真实成绩。
### 3.3 置信度
```text
confidence = N / (N + 10)
```
置信度只表示样本量相对先验的充分程度,不表示回答事实正确的概率。
### 3.4 分数档位
| 分数 | 档位 | 含义 |
|---:|---|---|
| `>= 90` | `excellent` | 优秀 |
| `>= 80` | `good` | 良好 |
| `>= 70` | `needs_attention` | 需要关注 |
| `< 70` | `poor` | 较差 |
| 无样本 | `insufficient_data` | 数据不足 |
## 4. 回答质量五维诊断
回答质量采用以下权重:
| 维度 | 权重 |
|---|---:|
| 正确性 `correctness` | 30% |
| 完整性 `completeness` | 20% |
| 证据支撑 `evidence_grounding` | 20% |
| 相关性 `relevance` | 15% |
| 可执行性 `actionability` | 15% |
对任一维度 `d`:
- 每条正向评价都是该维度的一条正向证据,记为 `S_d = P`;
- 只有映射到该维度的负向原因才构成该维度的负向证据,记为 `F_d`;
- `E_d = S_d + F_d` 为该维度证据数。
当 `E_d > 0` 时:
```text
dimension_score_d = 100 × (S_d + 8) / (E_d + 10)
```
没有证据时维度分返回 `null`。不能因为用户选择了“风格或语气”,就虚构一次“正确性”失败。
五维任务质量分按有证据的维度加权,并对可用权重重新归一化:
```text
task_score = Σ(weight_d × dimension_score_d) / Σ(weight_d for available dimensions)
```
性能、表达、安全和“其他”原因保持为独立问题分布,不混入五维任务质量分,但仍会影响总的用户评价分。
## 5. 展示要求
智能体详情至少同时展示:
- 用户评价分和档位;
- 有效样本数;
- 原始好评率;
- 置信度或明确的低样本提示;
- 五维质量诊断;
- 各类负向原因数量。
禁止只展示一个没有样本数和解释的总分。前端文案必须使用“用户评价分”或“回答评价”,不得命名为“智能体综合能力分”。
## 6. API 约定
消息级接口:
```text
GET /api/threads/{thread_id}/messages/{message_id}/feedback-context
PUT /api/threads/{thread_id}/messages/{message_id}/feedback
DELETE /api/threads/{thread_id}/messages/{message_id}/feedback
```
智能体聚合接口:
```text
GET /api/agents/{agent_id}/feedback-score
```
该聚合接口仅允许 `system_role=admin` 的管理员访问;正常鉴权模式下未登录返回 401、普通用户返回 403,关闭鉴权的部署沿用项目统一放行语义。消息级评价接口仍按线程所有权和当前用户隔离。
原有运行级反馈接口继续兼容,但新界面应优先使用消息级接口,避免前端猜测 `run_id`。
## 7. 后续完整评测体系
用户评价分适合生产环境的持续反馈闭环。上线准入和版本对比还应逐步补充:
- 规则校验与 Ground Truth;
- 正确性、引用和幻觉率测试集;
- Skill/Tool 选择准确率与调用成功率;
- 轨迹效率、异常恢复率和无效步骤率;
- Sub-agent 委派、信息保留和交接质量;
- Token、延迟、成本、稳定性与回归通过率。
完整评测应按任务类型和智能体版本保存测试集、运行轨迹及评分,不应把在线赞踩直接解释为上述工程指标。
@@ -0,0 +1,82 @@
# b5-1 任务分析深链接接入
`goPath=b5-1` 是「任务分析」单智能体问答入口。接入方先把任务详情写入 DeerFlow,再让用户登录并跳转;页面不会再调用接入方的任务详情接口。
## 前置配置
在「业务链条管理」页面新增的 **任务分析**(业务码 `b5-1`)行中选择要使用的单智能体。没有配置智能体时,深链接不会进入问答页。
服务端为接入写入端配置环境变量:
```text
DEERFLOW_TASK_DEEPLINK_INGEST_KEY=<随机且足够长的共享密钥>
```
该密钥只用于下面的 `PUT`;浏览器读取详情仍需正常登录态。
## 写入或更新任务详情
```http
PUT /api/task-deeplink-details/b5-1/{id}
Content-Type: application/json
X-Integration-Key: <DEERFLOW_TASK_DEEPLINK_INGEST_KEY>
```
```json
{
"taskName": "重点活动舆情研判",
"taskContent": "围绕活动期间的舆情风险、重点对象和处置建议开展分析。",
"overview": "活动前后七天的综合研判任务",
"extra": {
"sourceSystem": "B5",
"priority": "high",
"regionCodes": ["110000", "120000"],
"customField": {
"owner": "张三"
}
}
}
```
- `id` 与深链接中的 `taskId` 必须完全一致;存储键为 `(type, id)`,此处 `type` 固定为 `b5-1`。
- `taskName`、`taskContent` 必填;`overview`、`extra` 可选。
- `extra` 必须是 JSON 对象,最大 64 KiB;用于接入方的扩展字段。
- 这是幂等接口,接入方不需要预先查询「是否已存」。每次直接 `PUT` 完整快照即可:
- 首次写入:创建记录;
- 任务名称、详情、简介或 `extra` 有任一变化:整体更新并递增 `version`;
- 内容完全相同:只按主键读取并返回现有记录,不更新数据库、不递增 `version` 或 `updatedAt`。
成功响应示例:
```json
{
"data": {
"type": "b5-1",
"id": "task-20261020-001",
"taskName": "重点活动舆情研判",
"taskContent": "围绕活动期间的舆情风险、重点对象和处置建议开展分析。",
"overview": "活动前后七天的综合研判任务",
"extra": {
"sourceSystem": "B5",
"priority": "high"
},
"version": 1,
"updatedAt": "2026-10-20T10:00:00+08:00"
},
"created": true,
"changed": true
}
```
`created` 表示本次是否首次创建;`changed` 表示本次是否实际写入。对同样内容的重试,响应为 `created: false`、`changed: false`。
## 用户跳转
写入成功后,引导用户访问登录页(认证参数按既有接入方式附带):
```text
/#/login?taskId=task-20261020-001&goPath=b5-1
```
登录后前端读取本系统详情接口,将任务名称和任务详情展示在左上角,标题固定为「任务分析」;`taskName`、`taskContent`、`overview` 与完整 `extra` 会作为每轮问答的隐藏任务上下文提供给配置的智能体。聊天记录按 `(taskId, b5-1)` 独立保存,不会混入其它任务深链接或通用聊天。
@@ -0,0 +1,92 @@
# 商业情报监测接口、技能与业务链说明
## 组成
本功能全部使用项目级自定义资源:
- 自定义任务详情技能:`fs-task-detail-info`
- 自定义接口技能:`fs-timeline-info`、`fs-insight-info`、`fs-target-info`、`fs-connection-info`
- 当前判断独立接口技能:`fs-current-judgment-info`
- 自定义摘要技能:`fs-brief-info`
- 自定义编排技能:`fs-collect`
- 自定义业务链:`biz-intel-chain`
- 自定义页面助理:`biz-detail-assistant`,显示名“商业QB助理”
这些资源不写入内置技能或内置智能体目录。接口技能脚本第一行均为对应生产接口地址。
## 本地模拟接口
```powershell
cd F:\react01\deeflow-code\deerflow-server\offline-backend-20260512\backend
./devtools/mock_monitor_api/start-mock.ps1
```
新开一个 PowerShell,设置:
```powershell
$env:MONITOR_API_BASE_URL = "http://127.0.0.1:18080/consumer"
$env:MONITOR_AUTHORIZATION = "admin"
```
若要让定时业务链也访问模拟接口,需要在**启动 DeerFlow Gateway 的同一环境**中设置以上
两个环境变量,并保持模拟服务运行;只在另一个终端设置不会改变已经启动的 Gateway 进程。
模拟接口校验 `Authorization: admin`,提供任务详情、时间节点、热点/威胁/战机、实体及
打击/塑势衔接任务。任务名作为严格关键词时先返回空数组,用来验证技能会逐步扩大时间、
移除关键词并最终命中。
## 采集命令
只采集和转换,不写入:
```powershell
python skills/custom/fs-collect/scripts/fs_collect.py `
--group source --task-id 3 --dry-run
```
采集并原子合并到态势详情:
```powershell
python skills/custom/fs-collect/scripts/fs_collect.py `
--group source --task-id 003
```
当前判断写入后生成情报摘要:
```powershell
python skills/custom/fs-collect/scripts/fs_collect.py `
--group judgment --task-id 003
python skills/custom/fs-collect/scripts/fs_collect.py `
--group summary --task-id 003
```
脚本逐次输出接口方法、地址、Authorization 状态、查询参数或请求体、原始返回和放宽原因;
最后一行输出机器可读 JSON。
## 关键字段
- 时间节点:页面字段外保留 `recUuid` 和全部原始时间字段。
- 三类事件:保留接口 `id`,并复制为 `eventId` 供实体查询和追溯。
- 当前判断:独立调用 `eventMonitorByTime`,固定 `discriminant=威胁`,保留 `id/eventId`。
- 重要目标:保留 `eid/etype/text/imagePath/num/label/reason/score`。
- 衔接任务:标识字段是 `taskId`,不生成 `id`;类型只有 `打击/塑势`。
- 情报摘要:`sourceRefs` 保留所依据的事件 id、eid、recUuid、taskId 和判断 id。
## 自定义智能体与业务链注册
Gateway 启动后执行:
```powershell
python scripts/setup_force_situation_chain.py
python scripts/setup_biz_detail_assistant.py
```
业务链安装脚本默认只更新配置,不立即触发真实接口。需要立即执行时显式追加
`--trigger`。链路阶段为:接口数据采集 → 当前判断威胁接口采集 → 情报摘要与校验。
## 测试
```powershell
python -m pytest tests/test_force_situation_monitor_skills.py -q
```
@@ -123,6 +123,27 @@ models:
If your OpenRouter key lives in a different environment variable name, point `api_key` at that variable explicitly (for example `api_key: $OPENROUTER_API_KEY`).
**vLLM (per-model, do not change other entries)**:
`use` is per model. SiliconFlow / DeepSeek entries should stay on `langchain_openai:ChatOpenAI`. For a self-hosted vLLM reasoning model (thinking may arrive as `reasoning` on newer vLLM, or `reasoning_content` on older builds), set only that one entry to `VllmChatModel`:
```yaml
models:
- name: qwen3.6
display_name: qwen3.6
use: deerflow.models.vllm_provider:VllmChatModel
model: qwen3.6
api_key: $VLLM_API_KEY
base_url: http://127.0.0.1:8001/v1
supports_thinking: true
when_thinking_enabled:
extra_body:
chat_template_kwargs:
enable_thinking: true
```
The default `langchain_openai:ChatOpenAI` path also maps both thinking field names onto the UI's `reasoning_content`. Use `VllmChatModel` when follow-up turns must echo vLLM's original `reasoning` field.
**Thinking Models**:
Some models support "thinking" mode for complex reasoning:
@@ -270,21 +291,21 @@ skills:
# Host path (optional, default: ../skills)
path: /custom/path/to/skills
# Container mount path (default: /mnt/skills)
container_path: /mnt/skills
# Optional system-prompt routing rule for the es_query skill
es_query_routing:
enabled: true
prompt: |
当用户的问题需要基于 Elasticsearch Query DSL 灵活构造、调整或执行查询时,优先使用 `es_query` 技能。
执行前先读取该技能的 SKILL.md,并严格遵循其中的流程和参数。
```
`skills.es_query_routing.enabled` controls whether the routing rule is injected
into the overall agent system prompt. Edit `prompt` to tune the matching boundary
or invocation requirements. When disabled (the schema default), the block is not
injected. Custom agents receive it only when their explicit skill allowlist
contains `es_query`.
# Container mount path (default: /mnt/skills)
container_path: /mnt/skills
# Optional system-prompt routing rule for the es_query skill
es_query_routing:
enabled: true
prompt: |
当用户的问题需要基于 Elasticsearch Query DSL 灵活构造、调整或执行查询时,优先使用 `es_query` 技能。
执行前先读取该技能的 SKILL.md,并严格遵循其中的流程和参数。
```
`skills.es_query_routing.enabled` controls whether the routing rule is injected
into the overall agent system prompt. Edit `prompt` to tune the matching boundary
or invocation requirements. When disabled (the schema default), the block is not
injected. Custom agents receive it only when their explicit skill allowlist
contains `es_query`.
**How Skills Work**:
- Skills are stored in `deer-flow/skills/{public,custom}/`
@@ -6,11 +6,14 @@ DeerFlow 后端提供了完整的文件上传功能,支持多文件上传,
## 功能特性
- ✅ 支持多文件同时上传
- ✅ 可选地转换文档为 Markdown(PDF、PPT、Excel、Word)
- ✅ 文件存储在线程隔离的目录中
- ✅ Agent 自动感知已上传的文件
- ✅ 支持文件列表查询和删除
- ✅ 支持多文件同时上传,默认单条消息最多 20 个
- ✅ 上传策略持久化到数据库,管理员可在「设置 → 上传设置」实时调整
- ✅ 按文件类别设置格式与单文件上限,并校验扩展名和文件真实签名
- ✅ 可选地转换文档为 Markdown(PDF、PPT、Excel、Word)
- ✅ 文件存储在线程隔离的目录中
- ✅ Agent 自动感知已上传的文件
- ✅ 大文件采用流式统计和头部/中段/尾部采样,不把全文直接塞入模型上下文
- ✅ 支持文件列表查询和删除
## API 端点
@@ -22,7 +25,15 @@ POST /api/threads/{thread_id}/uploads
**请求体:** `multipart/form-data`
- `files`: 一个或多个文件
网关会在应用层限制上传规模,默认最多 10 个文件、单文件 50 MiB、单次请求总计 100 MiB。可通过 `config.yaml` 的 `uploads.max_files`、`uploads.max_file_size`、`uploads.max_total_size` 调整;前端会读取同一组限制并在选择文件时提示,超过限制时后端返回 `413 Payload Too Large`。
网关每次上传都会读取数据库中的全局上传策略;前端也读取同一策略并在选择文件时预校验。内置默认值如下:
| 类别 | 默认格式 | 默认单文件上限 |
|---|---|---:|
| 文档/文本 | `.txt`、`.md`、`.doc`、`.docx`、`.ppt`、`.pptx`、`.pdf` | 10 MiB |
| 图片 | `.jpg`、`.jpeg`、`.png` | 10 MiB |
| 表格 | `.xls`、`.xlsx`、`.csv` | 5 MiB |
单条消息默认最多 20 个文件、附件合计默认不超过 100 MiB。管理员可在「设置 → 上传设置」调整数量、总量、各类别格式和大小,以及大文件采样阈值与输出字符预算。服务端始终执行最终校验;超过限制返回 `413 Payload Too Large`,不支持或内容签名不匹配返回 `415 Unsupported Media Type`。整批文件先写入暂存目录并全部验证,任一文件失败时不会留下半批结果。
**响应:**
```json
@@ -35,10 +46,10 @@ POST /api/threads/{thread_id}/uploads
"path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf",
"virtual_path": "/mnt/user-data/uploads/document.pdf",
"artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf",
"markdown_file": "document.md",
"markdown_path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.md",
"markdown_virtual_path": "/mnt/user-data/uploads/document.md",
"markdown_artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.md"
"markdown_file": "document.pdf.md",
"markdown_path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf.md",
"markdown_virtual_path": "/mnt/user-data/uploads/document.pdf.md",
"markdown_artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf.md"
}
],
"message": "Successfully uploaded 1 file(s)"
@@ -50,23 +61,62 @@ POST /api/threads/{thread_id}/uploads
- `virtual_path`: Agent 在沙箱中使用的虚拟路径
- `artifact_url`: 前端通过 HTTP 访问文件的 URL
### 2. 查询上传限制
```
GET /api/threads/{thread_id}/uploads/limits
```
返回网关当前生效的上传限制,供前端在用户选择文件前提示和拦截。
### 2. 查询和管理上传策略
所有已登录用户都可读取当前策略:
```
GET /api/upload-policy
```
管理员原子替换或恢复默认策略:
```
PUT /api/upload-policy
POST /api/upload-policy/reset
```
策略首次启动时会将内置默认值写入数据库表 `upload_policy`,后续修改带递增 `revision` 和更新人/更新时间审计信息。各 Gateway worker 在读取或修改策略时同步刷新 harness 运行时副本。
兼容旧前端的线程级限制查询仍保留:
```
GET /api/threads/{thread_id}/uploads/limits
```
返回网关当前生效的分类限制、总量限制、大文件策略和策略版本。
**响应:**
```json
{
"max_files": 10,
"max_file_size": 52428800,
"max_total_size": 104857600
}
```
### 3. 列出已上传文件
"max_files": 20,
"max_file_size": 10485760,
"max_total_size": 104857600,
"max_files_per_message": 20,
"max_total_bytes": 104857600,
"groups": {
"document": {"max_bytes": 10485760, "extensions": [".txt", ".md", ".doc", ".docx", ".ppt", ".pptx", ".pdf"]},
"image": {"max_bytes": 10485760, "extensions": [".jpg", ".jpeg", ".png"]},
"spreadsheet": {"max_bytes": 5242880, "extensions": [".xls", ".xlsx", ".csv"]}
},
"large_file": {
"threshold_bytes": 1048576,
"max_result_chars": 12000,
"hard_max_result_chars": 32000
},
"revision": 1
}
```
### 3. 有界文本预览
```
GET /api/threads/{thread_id}/artifact-preview?path=/mnt/user-data/uploads/example.txt&max_chars=12000
```
小文件返回有界完整文本;大文件返回流式统计、开头/中段/结尾的确定性分块采样、截断标记和警告。浏览器预览不会调用无界的 `response.text()`。
### 4. 列出已上传文件
```
GET /api/threads/{thread_id}/uploads/list
```
@@ -89,7 +139,7 @@ GET /api/threads/{thread_id}/uploads/list
}
```
### 4. 删除文件
### 5. 删除文件
```
DELETE /api/threads/{thread_id}/uploads/{filename}
```
@@ -111,7 +161,7 @@ DELETE /api/threads/{thread_id}/uploads/{filename}
- Word (`.doc`, `.docx`)
- OpenDocument (`.odt`, `.ods`, `.odp`)
转换后的 Markdown 文件会保存在同一目录下,文件名为原文件名 + `.md` 扩展名。
转换后的 Markdown 文件会保存在同一目录下,文件名为完整原文件名再追加 `.md`,例如 `report.docx.md`。这样 `report.docx` 和 `report.pdf` 不会同时覆盖同一个 `report.md`。前端预览仍兼容升级前的旧侧车名称。
通用部署可以关闭自动转换,以避免在网关主机上对不受信任的 Office/PDF 上传执行解析。本仓库当前 `config.yaml` 和纯 DeerFlow 离线部署包默认设置为 `uploads.auto_convert_documents: true`,用于受信任的内网部署。
@@ -121,19 +171,13 @@ DELETE /api/threads/{thread_id}/uploads/{filename}
Agent 在每次请求时会自动收到已上传文件的列表,格式如下:
```xml
<uploaded_files>
The following files have been uploaded and are available for use:
- document.pdf (1.2 MB)
Path: /mnt/user-data/uploads/document.pdf
- document.md (45.3 KB)
Path: /mnt/user-data/uploads/document.md
You can read these files using the `read_file` tool with the paths shown above.
</uploaded_files>
```
```text
<uploaded_files>
{经过 JSON 转义和字符预算裁剪的文件元数据、统计与采样摘要}
</uploaded_files>
```
当前轮文件可附带短摘要;历史轮次只注入元数据;自动生成的 Markdown 侧车不会作为第二个独立附件重复注入。整个 `<uploaded_files>` 块受数据库策略中的常规/硬字符预算约束。
### 使用上传的文件
@@ -144,8 +188,10 @@ Agent 在沙箱中运行,使用虚拟路径访问文件。Agent 可以直接
read_file(path="/mnt/user-data/uploads/document.pdf")
# 读取转换后的 Markdown(推荐)
read_file(path="/mnt/user-data/uploads/document.md")
```
read_file(path="/mnt/user-data/uploads/document.pdf.md")
```
当文本达到大文件阈值时,`read_file` 不会一次性返回全文,而会逐块读取并产生:总字节数/行数、空行和乱码统计、最长行、内容哈希,以及开头/中段/结尾样本。需要进一步核实时应使用明确的行区间或有界 `grep`。超长单行也按固定大小片段处理,内存占用不会随单行长度无限增长。
**路径映射关系:**
- Agent 使用:`/mnt/user-data/uploads/document.pdf`(虚拟路径)
@@ -217,18 +263,20 @@ backend/.deer-flow/threads/
└── user-data/
└── uploads/
├── document.pdf # 原始文件
├── document.md # 转换后的 Markdown
├── presentation.pptx
├── presentation.md
├── document.pdf.md # 转换后的 Markdown
├── presentation.pptx
├── presentation.pptx.md
└── ...
```
## 限制
- 最大文件大小:100MB(可在 nginx.conf 中配置 `client_max_body_size`)
- 文件名安全性:系统会自动验证文件路径,防止目录遍历攻击
- 线程隔离:每个线程的上传文件相互隔离,无法跨线程访问
- 自动文档转换默认关闭;如需启用,需在 `config.yaml` 中显式设置 `uploads.auto_convert_documents: true`
- 数据库策略可配置范围带服务端硬上限:文件数最多 100、单文件最多 100 MiB、单次总量最多 200 MiB;反向代理的 `client_max_body_size` 还必须不低于所需请求大小
- 文件名安全性:系统会自动验证文件路径,防止目录遍历攻击
- 文件真实性:PDF、JPG、PNG、OLE 与 OOXML 会校验签名/容器结构,OOXML 同时限制条目数、解压总量和压缩比
- 线程隔离:每个线程的上传文件相互隔离,无法跨线程访问
- 自动文档转换由 `uploads.auto_convert_documents` 控制;转换在事件循环外执行、限制并发,提取的 Markdown 还有固定字符上限
- 模型安全硬边界:单次文件摘要/读取结果最多 32,000 字符,图片还会校验像素数并生成受限尺寸派生图
## 技术实现
@@ -314,9 +362,7 @@ async function listFiles(threadId: string) {
### 扩展功能建议
1. **文件预览**:添加预览端点,支持在浏览器中直接查看文件
2. **批量删除**:支持一次删除多个文件
3. **文件搜索**:支持按文件名或类型搜索
4. **版本控制**:保留文件的多个版本
5. **压缩包支持**:自动解压 zip 文件
6. **图片 OCR**:对上传的图片进行 OCR 识别
1. **批量删除**:支持一次删除多个文件
2. **文件搜索**:支持按文件名或类型搜索
3. **版本控制**:保留文件的多个版本
4. **图片 OCR**:对上传的图片进行 OCR 识别
@@ -0,0 +1,502 @@
# 知识空间优先检索、Wiki 扩展检索与全库摘要实现方案
> 状态:P0/P1 与普通 Wiki 的 P2 主链路已落地;助手关系图扩展和 P3 待实施
> 适用范围:普通 WeKnora/LLMWiki 知识库、助手知识库、通用问答与智能体问答
> 更新日期:2026-09-16
## 1. 结论
本次改造不应只是“向量搜不到时再补一个 LIKE”。需要同时修复检索范围、索引可用性判断、召回策略和全库认知四个层面:
1. **勾选任一知识空间后,本轮进入严格知识空间模式**:只允许检索已选普通/助手知识空间,不调用 `web_search`、`web_fetch`、图片搜索、外部检索技能或检索型 MCP;非检索工具仍可使用。知识空间没有结果时必须明确报告原因,不能偷偷转向互联网。
2. **把普通知识库和助手知识库统一成一个检索入口**:预检索和智能体二次检索必须覆盖同一批已选空间,使用同一套权限、诊断、引用和排序协议。
3. **保留最后一次成功索引继续服务**:一次增量同步失败或取消,不能让已经完整生成的向量立刻整体失效。
4. **默认采用混合召回**:向量、关键词/全文、标题/别名精确命中并行执行,经 RRF 融合;向量不可用或低置信时关键词结果仍可回答,但响应必须附带 `fallback_reason`,以便继续修复向量根因。
5. **利用 Wiki 图做有界扩展**:在首批命中页面上沿 `InLinks`、`OutLinks`、实体关系和目录父子关系扩展 1 跳,确有多跳意图或首轮低置信时再扩展第 2 跳,然后统一重排,而不是把整张图塞进上下文。
6. **为每个知识空间维护“全库摘要”**:系统持续生成草稿,用户拥有可编辑的发布版本;系统更新不能覆盖人工修改。回答“这个库是干什么的/都讲了什么”时优先读取该摘要,并附代表性页面引用。
优先落地顺序是:**P0 可观测性与索引保活 → P1 严格范围与混合召回 → P2 Wiki 图扩展 → P3 全库摘要维护 → P4 重排与质量评测**。
## 2. 已确认的现状与问题
### 2.1 当前请求链路
当前前端已经把两类选择写入线程 metadata 和运行 context:
- `llmwiki_knowledge_base_ids`
- `assistant_knowledge_base_ids`
Gateway 的 `app/gateway/llmwiki_rag.py::build_llmwiki_rag_context` 会在模型调用前做一次检索,并把最多 8 条资料放进隐藏提示和引用列表。普通知识库走 `WikiRetrievalService`,助手知识库走 `AssistantKnowledgeRepository.search_pages`。
但现有实现存在四个断层:
| 断层 | 当前行为 | 影响 |
|---|---|---|
| 工具范围 | `services.py` 只在未选择普通知识库时排除 `llmwiki_search`,选择知识空间时没有排除 Web/外部检索 | 模型仍可能越过已选空间调用互联网或其他检索 |
| 二次检索 | `llmwiki_search_tool.py` 只读取 `llmwiki_knowledge_base_ids` | 助手知识库只参与一次预检索,智能体无法围绕它继续分解查询 |
| 普通 Wiki 召回 | 完整索引只做向量;远端回退按用户原句查询 Wiki 页面列表 | 同义表达、宽泛问题、精确专名都可能漏召回 |
| Wiki 图 | 本地镜像只保存 `parent_slug`,`normalize.py` 没有保留 `InLinks` / `OutLinks` | 数据虽然 Wiki 化,检索仍是孤立页面向量,没有利用页面关系扩展 |
### 2.2 已确认的向量漏检机制
普通 Wiki 只有同时满足以下条件才会进入本地向量检索:
```text
sync state == idle
AND last_success_at 非空
AND stored embedding_fingerprint == 当前编码器 fingerprint
AND ready_page_count == local_page_count
AND failed_page_count == 0
AND(空库 OR vector_count > 0)
```
对应代码是 `local_index/retrieval.py::is_fully_vectorized`。这个判断把“最新同步是否成功”和“最后一个成功索引是否仍可服务”混成了一个状态。
2026-09-11 本地 SQLite 快照及 2026-09-07 后端日志已经出现以下实际情况:
| 库状态样例 | 页面/向量 | 当前结果 |
|---|---:|---|
| `对话沉淀` | 124 页 / 281 向量 | 最新状态 `failed: Sync cancelled`,已有向量被整体排除,退回 Wiki API |
| `111` | 13 页 / 36 向量 | 同样因同步取消不使用已有向量 |
| `admin的知识库` | 0 页 / 0 向量 | 远端知识库映射持续返回 404,确实不可检索 |
| 两个空/源库 | 0 页 / 0 向量 | Wiki 页面和向量都不存在,属于真实空结果 |
| 三个验收/图片库 | 19 页 / 101 向量 | `idle` 且指纹一致,可走本地向量 |
这证明目前至少存在三类“搜不到”,必须分别呈现:
1. **数据真空**:没有可检索正文页或向量;
2. **索引存在但被状态门禁禁用**:最后一次增量同步失败,旧成功快照也不能服务;
3. **映射失效**:DeerFlow 本地记录指向已删除或无权访问的 WeKnora 库。
还存在一个独立的召回截断:`LocalWikiIndexConfig.min_similarity` 默认是 `0.35`,`search.py` 在此阈值之前直接丢弃候选。`keyword_boost_enabled` 默认关闭;即使开启,它也只给已超过向量阈值的候选加分,并不是关键词兜底。因此,只要所有向量分数低于 0.35,结果就是 0。
助手知识库已有关键词回退,但只有当前编码器指纹、维度和来源的 `last_import_job_id` 同时匹配时才会走向量。当前快照中也存在 active 来源为 0 条向量的情况。现有返回协议没有说明某个来源究竟是“无向量、指纹不符、最新导入不匹配”还是“向量低于阈值”。
### 2.3 “Wiki 已生成”不等于“可向量检索”
完整链路实际是:
```text
原始文件存在
→ WeKnora Wiki 异步生成完成
→ DeerFlow 成功拉取所有 Wiki 正文页
→ 正文成功切段
→ 使用当前编码器生成向量
→ 指纹/维度与查询编码器一致
→ 最后成功索引快照被激活
→ 查询分数超过阈值
```
任一步失败都可能出现“页面在 Wiki 管理里看得到,但聊天搜不到”。后续 UI 和接口必须展示每一层的数量与状态,不能只显示一个模糊的“已 Wiki 化”。
## 3. 外部开源方案调研与选型
### 3.1 可借鉴的项目
1. **腾讯 WeKnora(优先复用)**
当前上游已经把 Wiki 页面组织成有向图,页面包含 `InLinks` / `OutLinks`,并提供 `/wiki/graph`、`/wiki/search`、页面编辑、版本历史和回滚接口。上游说明还明确区分 `summary`、`entity`、`concept`、`index` 等页面类型。参考:[WeKnora Wiki 官方文档](https://github.com/Tencent/WeKnora/blob/main/website-docs/03-features/14-wiki.md)、[WeKnora 官方仓库](https://github.com/Tencent/WeKnora)。
2. **HippoRAG / HippoRAG 2(Wiki 扩展检索算法参考)**
HippoRAG 将稠密召回、知识图和 Personalized PageRank 组合起来,目标就是跨文档关联与多跳检索。这与“先命中 Wiki 页面,再沿关联页面扩展”的需求最接近。参考:[HippoRAG 官方仓库](https://github.com/OSU-NLP-Group/HippoRAG)、[NeurIPS 2024 论文](https://proceedings.neurips.cc/paper_files/paper/2024/file/6ddc001d07ca4f319af96a3024f6dbd1-Paper-Conference.pdf)。
3. **Microsoft GraphRAG(全库摘要参考)**
GraphRAG 的知识模型包含实体、关系、层级社区和 Community Report;Global Search 基于社区报告做全局问题汇总。这适合借鉴到“这个知识库整体讲什么”,但完整 GraphRAG 索引成本较高,不建议当前直接替换现有 WeKnora/本地向量链路。参考:[官方索引数据流](https://github.com/microsoft/graphrag/blob/main/docs/index/default_dataflow.md)、[官方 Global Search 示例](https://microsoft.github.io/graphrag/examples_notebooks/global_search/)。
4. **LightRAG(备选实现参考)**
LightRAG 使用图结构与向量的双层检索,并强调增量更新。它可作为独立图检索服务的备选,但当前系统已经有 WeKnora Wiki 图和助手库实体关系,再引入一套完整存储会造成双份索引、权限和一致性成本。参考:[LightRAG 官方仓库](https://github.com/HKUDS/LightRAG)。
### 3.2 选型结论
第一阶段**不整体引入 GraphRAG、HippoRAG 或 LightRAG 运行时**,而是:
- 复用 WeKnora 已生成的 Wiki 页面、链接图和现有 DeerFlow 助手知识图;
- 采用 HippoRAG 的“检索种子 + PPR/图扩散”思想实现轻量有界扩展;
- 采用 GraphRAG 的“分层摘要/全局摘要”思想维护全库摘要;
- 保留一个实验适配器,后续用离线评测决定是否接入完整框架。
这样能避免重复抽取同一批实体关系,也符合当前离线部署和 Harness/App 分层约束。
## 4. 目标行为
### 4.1 严格知识空间模式
只要本轮 `llmwiki_knowledge_base_ids` 或 `assistant_knowledge_base_ids` 至少有一个有效 ID,就设置:
```json
{
"retrieval_scope": "selected_knowledge_spaces",
"external_retrieval_allowed": false
}
```
必须保证:
- 允许:统一知识空间检索、读取命中 Wiki 全文、文件读写、计算、制图等非外部检索能力;
- 禁止:`web_search`、`web_fetch`、`image_search`、其他公网/内网检索工具、外部检索技能、检索型 MCP;
- 子智能体继承同一限制;
- 即使 0 命中也不能自动 Web fallback;
- 用户需要联网时,应先取消知识空间选择,或未来显式切换“知识空间 + 联网”模式,不能由模型自行决定。
只靠提示词不能作为保证。短期在 Gateway 合并 `excluded_tools`;中期给工具、技能和 MCP 增加 `retrieval_channel` 能力标签,在工具装配层统一 fail-closed 过滤,并在调用网关再次校验。
### 4.2 统一检索工具
用 `knowledge_space_search` 替代仅支持普通库的 `llmwiki_search`:
```json
{
"query": "聚焦后的检索问题",
"intent": "fact | overview | multi_hop | compare",
"selected_spaces": [
{"kind": "llmwiki", "id": "..."},
{"kind": "assistant", "id": "..."}
],
"top_k": 8,
"expand_wiki": "auto"
}
```
工具内部从 runtime context 获取白名单,模型不能通过参数扩大范围。预检索也调用同一个服务,避免两套算法和返回结构再次漂移。
统一结果至少包含:
```json
{
"results": [],
"mode": "hybrid_graph",
"diagnostics": {
"vector_candidates": 0,
"lexical_candidates": 7,
"graph_candidates": 11,
"vector_status": "threshold_filtered",
"top_raw_vector_score": 0.31,
"threshold": 0.35,
"fallback_reason": "VECTOR_BELOW_THRESHOLD"
}
}
```
## 5. 混合检索与 Wiki 扩展算法
### 5.1 查询路由
先做轻量意图识别,不调用外部检索:
- `overview`:“这个知识库做什么”“全部讲了什么”“有哪些主题”;
- `fact`:单事实、定义、专名、编号;
- `multi_hop`:关系链、原因链、跨页面综合;
- `compare`:多个对象/方案比较。
同时生成 1~4 个聚焦查询,包括原句、去停用词版本、实体/别名版本。保留原句用于引用追踪。
### 5.2 第一阶段召回
在每个已选空间内并行执行:
1. **向量召回**:页面正文 section 的 BGE-M3 向量;先取 raw top-N,再判断低置信,不能先丢掉诊断信息;
2. **关键词/全文召回**:标题、别名、heading、正文、实体名;中文使用分词或 CJK 2/3-gram,支持精确短语;
3. **结构命中**:slug、目录路径、实体 ID、来源文档名精确匹配;
4. **概览命中**:直接读取已发布的全库摘要,不把“知识库干什么”送去做普通相似度查询。
推荐默认并行混合,而不是只有 0 条时才执行关键词。向量擅长同义表达,关键词擅长专名、编号和缩写;两者用 Reciprocal Rank Fusion 合并,避免直接比较不可校准的原始分数:
```text
score_rrf(d) = Σ 1 / (k + rank_channel(d))
```
标题/别名精确命中可作为独立 rank channel,不直接覆盖正文相关性。
### 5.3 Wiki 图扩展
同步时把 WeKnora `GET /wiki/graph` 或页面 `InLinks` / `OutLinks` 落到本地边表。助手库复用现有 `assistant_knowledge_entities`、`assistant_knowledge_relations` 及包内双向链接。
建议的节点与边:
| 节点 | 边 | 默认权重方向 |
|---|---|---:|
| Wiki 页面 | 显式 `[[wiki-link]]` / InLinks / OutLinks | 1.0 |
| 页面 ↔ 实体 | 页面提及或实体贡献 | 0.9 |
| 实体 ↔ 实体 | 已抽取关系 | 0.8 |
| 页面 ↔ 来源文档 | `source_refs` / `chunk_refs` | 0.7 |
| 页面 ↔ 目录父子 | `parent_slug` / folder | 0.4 |
在线流程:
1. 取混合召回 top 10~20 作为个性化种子;
2. `fact` 默认扩 1 跳,`multi_hop` 或低置信再扩 2 跳;
3. 每个种子的邻居上限、总节点上限和每库配额必须固定;
4. 用有界 PPR 或衰减传播得到图分;
5. 将向量 rank、关键词 rank、图 rank 用 RRF 融合;
6. 可选本地 reranker 对 top 30 重排;
7. 用 MMR/去重限制同一页面和同一主题占满上下文;
8. 最终只返回有正文且能追溯到原始页面/文档的 6~10 条证据。
图扩展只扩大候选池,不直接把关联页面当作事实证据。最终引用必须对应真实正文片段。
### 5.4 索引快照保活
同步状态拆成两组:
- `serving_snapshot_*`:当前对查询可见的最后成功版本;
- `sync_attempt_*`:最新一次同步任务的状态、错误和进度。
新同步在 staging revision 中完成,只有页面、向量、指纹和维度校验全部通过后才原子切换 serving revision。同步失败时继续使用旧 revision,同时返回 `index_stale=true` 和失败原因。只有从未成功生成过 serving snapshot 时才退回 Wiki API/关键词。
## 6. 全库摘要的持续维护与人工编辑
### 6.1 产品语义
每个知识空间维护两份摘要:
- **系统草稿**:随 Wiki 页面变化持续重算;
- **人工发布版**:用户可编辑,是聊天回答和知识库详情默认展示的摘要。
如果从未人工编辑,发布版自动跟随系统草稿;一旦人工编辑,后续系统更新只产生“待合并草稿”和差异提示,不能覆盖用户文字。用户可以逐段接受、全部替换、恢复历史版本。
### 6.2 摘要结构
摘要不是一段无来源的模型结论,建议存储结构化字段:
```json
{
"purpose": "这个知识空间解决什么问题",
"scope": ["覆盖范围"],
"key_topics": [{"name": "主题", "page_slugs": ["..."]}],
"key_entities": [{"name": "实体", "page_slugs": ["..."]}],
"time_coverage": "资料时间范围或未知",
"source_coverage": {"documents": 12, "wiki_pages": 63, "eligible_pages": 58},
"limitations": ["缺口、失败页面、过期风险"],
"summary_markdown": "面向用户的可编辑摘要"
}
```
`source_coverage` 和 `limitations` 由系统生成且不可由摘要模型伪造。
### 6.3 生成策略
借鉴 GraphRAG 的分层摘要,但复用现有 Wiki 分类:
```text
页面摘要(增量复用)
→ 按目录 / 实体社区 / 来源文档聚类
→ 主题摘要
→ 全库摘要草稿
→ 事实覆盖与引用校验
```
触发条件:文件导入完成、Wiki 页面创建/编辑/删除、索引 serving revision 切换。采用 30~120 秒 debounce,同一知识库合并任务;只重算受影响主题,最后合并全库草稿。
### 6.4 数据模型
新增:
```text
knowledge_space_profiles
kind, space_id, serving_revision
generated_json, generated_markdown, generated_at
published_markdown, published_version, edited_by, edited_at
source_revision, status, last_error
knowledge_space_profile_revisions
profile_id, version, source(system|user|merge|revert)
content_markdown, content_json, created_by, created_at
```
唯一键为 `(kind, space_id)`;更新使用 `published_version` 乐观锁。
### 6.5 API 与界面
建议统一接口:
- `GET /api/knowledge-spaces/{kind}/{id}/profile`
- `PATCH /api/knowledge-spaces/{kind}/{id}/profile`:人工编辑;
- `POST /api/knowledge-spaces/{kind}/{id}/profile/regenerate`:重算系统草稿;
- `POST /api/knowledge-spaces/{kind}/{id}/profile/accept-generated`:接受系统草稿;
- `GET /api/knowledge-spaces/{kind}/{id}/profile/revisions`
- `POST /api/knowledge-spaces/{kind}/{id}/profile/revert/{version}`
普通/助手知识库详情增加“知识库摘要”页签:显示覆盖数量、生成时间、是否落后于当前 Wiki、编辑、差异、重算和历史。问答遇到 `overview` 意图时读取发布摘要,再补充 3~5 个代表性正文引用。
## 7. 检索健康诊断
### 7.1 健康接口
新增:
```text
GET /api/knowledge-spaces/{kind}/{id}/retrieval-health
POST /api/knowledge-spaces/{kind}/{id}/retrieval-health/reindex
POST /api/knowledge-spaces/{kind}/{id}/retrieval-health/resync
```
返回至少包括:
- 远端文档数、Wiki 页面数、正文可检索页面数;
- active/draft/archived、summary/index/body 页面分布;
- 已切段页数、向量数、失败数;
- serving revision 与最新 sync attempt;
- 当前/已存 embedding model、fingerprint、dimensions;
- 空正文数、失效映射/权限状态、最后错误;
- 最后成功同步/向量化/摘要更新时间;
- 关键词索引和 Wiki 图边数量。
### 7.2 每次查询追踪
每次检索生成 `retrieval_trace_id`,记录:
```text
选中空间 → 权限通过数 → 查询变体 → 每通道候选数
→ 向量 top raw score / threshold → 图扩展数 → rerank 数
→ 最终引用数 → 实际模式 / fallback_reason → 各阶段耗时
```
0 结果必须归类为稳定错误码,例如:
- `SPACE_EMPTY`
- `REMOTE_MAPPING_NOT_FOUND`
- `WIKI_NOT_FINALIZED`
- `NO_SERVING_VECTOR_SNAPSHOT`
- `EMBEDDING_FINGERPRINT_MISMATCH`
- `EMBEDDING_DIMENSION_MISMATCH`
- `VECTOR_BELOW_THRESHOLD`
- `NO_ELIGIBLE_BODY_PAGE`
- `KEYWORD_NO_MATCH`
- `RETRIEVAL_PROVIDER_UNAVAILABLE`
前端不得把 `UNAVAILABLE` 显示成“库内没有相关资料”。管理员可以展开诊断并直接触发重同步/重建索引。
## 8. 后端改造位置
| 模块 | 改造 |
|---|---|
| `app/gateway/services.py` | 识别严格知识空间模式;统一过滤外部检索能力;策略传给子智能体 |
| `app/gateway/llmwiki_rag.py` | 改为调用统一 `KnowledgeSpaceRetrievalService`;附诊断和 trace id |
| `tools/builtins/llmwiki_search_tool.py` | 迁移为同时支持普通/助手库的 `knowledge_space_search`,保留兼容别名 |
| `local_index/retrieval.py` | serving snapshot 保活、普通库关键词召回、模式与 fallback 原因 |
| `local_index/search.py` | 返回 raw top score;阈值校准;向量与关键词并行融合 |
| `local_index/normalize.py` | 保留 `in_links`、`out_links`、folder/关系字段 |
| `persistence/llmwiki_index/*` | serving/staging revision、Wiki 图节点边、全文索引 |
| `persistence/assistant_knowledge/*` | 统一诊断协议;复用助手实体关系做图扩展 |
| 新 `knowledge_space_retrieval/` | 查询路由、hybrid/RRF、图扩展、上下文组装、trace |
| 新 `knowledge_space_profiles/` | 全库摘要任务、版本、人工编辑与 diff |
Harness 不导入 `app.*`;Gateway 负责用户和权限解析,把授权后的空间描述传给 Harness 服务。
## 9. 前端改造
1. 选择知识空间后,在选择器旁明确显示“仅检索已选知识空间,不联网”;
2. 检索过程显示“向量 / 关键词 / Wiki 关联扩展 / 重排”阶段及耗时;
3. 0 命中时展示具体状态和修复入口,不只显示空卡片;
4. 引用卡片标注 `向量命中`、`关键词命中`、`Wiki 关联扩展`,但不能暴露内部敏感路径;
5. 普通/助手知识库共用“知识库摘要”编辑、差异和历史组件;
6. 管理页面增加“检索健康”抽屉,普通用户看到简化状态,管理员看到完整诊断。
## 10. 性能设计
- 空间列表继续只读 metadata/聚合统计,不扫描 Wiki 正文和向量;
- 多空间权限校验改成批量查询,不按 ID 串行;
- 本地向量矩阵按 `(space_id, serving_revision, fingerprint)` 缓存;
- 查询向量按 `(fingerprint, normalized_query)` 短 TTL 缓存;
- 关键词索引增量维护,禁止在线全表 `%LIKE%` 扫描大库;SQLite 可用 FTS5/CJK n-gram 辅助表,PostgreSQL/高斯/MySQL 通过统一适配层接各自全文索引;
- Wiki 图常驻压缩邻接表,在线只取有界邻居;
- 页面全文和引用详情批量加载,避免 N+1 远端请求;
- reranker 只处理融合后的 top 20~30,超时则降级到 RRF,不阻断回答;
- 摘要生成完全后台化,聊天只读 serving profile。
建议验收预算(需用生产规模压测校准):热缓存本地检索 p95 ≤ 2 秒,图扩展自身 p95 ≤ 200 ms;远端回退必须有独立超时,不能拖住整个模型首 token。
## 11. 分阶段实施
### 当前落地状态(2026-09-16)
- 已落地 P0/P1 主链路:失败/取消同步保留最后成功向量快照、向量 raw-score 诊断、普通 Wiki
关键词并行召回 + RRF、低分回退原因、普通/助手二次检索统一、选库后的 Web/MCP/技能/子智能体
硬隔离,以及选库后的 4 个推荐问题。
- 已落地逐次查询追踪与同链路预览:`POST /api/llmwiki/retrieval-debug` 复用问答预检索,知识空间
「检索调试」页展示最终证据、通道候选数、阈值、降级和零结果原因;正常问答在 SSE `metadata`
与 `/api/threads/{thread_id}/reference-batches.retrieval_traces` 暴露相同 trace,F12 可直接核对。
后续轮次省略选库字段时沿用线程选择,显式空列表仍清空范围。
- 编码器已按部署配置切换为 SiliconFlow `BAAI/bge-m3`(1024 维),密钥只从环境变量读取;
供应商切换产生新 fingerprint,旧库将重建,期间由关键词/Wiki API 保底。
- 已落地 P2 普通知识库与助手知识库图扩展:普通库同步库内入链/出链、正文 wikilink 与 provider
graph;助手库沿导入实体关系并通过 `entity.wiki_page_id` 回到 Wiki 正文。两者都以混合召回页为
种子,默认 1 跳,显式多跳意图或低置信时最多 2 跳,并执行候选/种子/每库/最终上下文硬上限、
衰减传播排序、真实正文校验、授权二次过滤和可审计路径 trace。P3 可编辑全库摘要仍未实施,
不能把当前 overview 代表页聚合误称为“持续维护摘要”。
### P0:诊断与正确性保底
- 建 retrieval health/trace;
- 拆分 serving snapshot 与 sync attempt;
- 修复失效远端映射和同步取消导致的整库失效;
- 记录 raw top score、阈值和每库候选数。
验收:现有 124 页/281 向量的库即使新同步失败,仍从上一次成功 snapshot 返回结果,并标记 stale。
### P1:严格范围与混合召回
- 勾选知识空间后禁止所有外部检索通道;
- 合并普通/助手知识工具;
- 向量、关键词、标题/别名召回 + RRF;
- 0 结果返回明确 fallback reason。
验收:测试 spy 证明选中空间的整轮运行中 Web/外部检索调用次数为 0;向量低于阈值时关键词能召回精确专名。
### P2:Wiki 图扩展
- 已同步 WeKnora InLinks/OutLinks、正文 wikilink 和 provider graph;
- 已实现普通 Wiki 1~2 跳有界扩展、衰减传播、稳定融合、去重、每库配额与 trace;
- 已接入助手实体关系:只沿所选助手库内 active 的关系、两端实体和页面扩展,并阻断跨库追边;
- 后续继续以多跳评测集校准传播权重和配额。
验收:准备只能通过关联页找到答案的 1 跳/2 跳数据集;结果必须命中且引用真实正文。
### P3:全库摘要与编辑
- profile 表、后台生成、事件触发;
- 人工发布版、diff、历史、回滚;
- overview 查询优先走 profile。
验收:新增/编辑/删除 Wiki 后系统草稿更新;人工摘要不被覆盖;“知识库干什么”稳定返回摘要和代表性引用。
### P4:重排与质量评测
- 可选 BGE reranker;
- 建中文问答集、专名集、概览集、多跳集和负样本;
- 评估 Recall@K、MRR、nDCG、citation precision、0 命中率和 p95。
只有离线评测显著优于 RRF 基线,才默认开启 reranker 或引入完整外部 GraphRAG/HippoRAG 服务。
## 12. 必测用例
1. 普通库、助手库、二者混选时都严格限定到所选 ID;
2. 选择知识空间后直接/技能/MCP/子智能体均不能调用外部检索;
3. 同步取消但存在 serving snapshot 时继续向量检索;
4. 指纹或维度不匹配时返回关键词结果和明确诊断;
5. 所有向量低于阈值时返回 raw top score,不误报为空库;
6. 中文专名、英文缩写、编号、标题别名可被关键词召回;
7. summary/index 页面不作为普通事实的唯一证据;
8. Wiki 1 跳/2 跳扩展不越出已选知识空间;
9. 多知识空间有每库配额,单个大库不会吞掉全部 top-K;
10. 空库仍可进入管理页、编辑摘要说明和上传文件;
11. overview 问题不依赖与问句的向量相似度;
12. 人工编辑摘要后自动更新只生成待合并草稿;
13. 远端 404、超时、权限错误与真实 0 命中分别显示;
14. 引用可打开对应 Wiki 页面或源文档,且正文与答案事实一致。
## 13. 完成定义
以下条件全部满足才算完成,而不是“接口能返回 200”:
- 勾选知识空间后,外部检索调用为 0;
- 普通和助手知识空间共享一套检索语义;
- 每个 0 结果都有可解释原因;
- 旧成功索引不因新同步失败而下线;
- 向量、关键词和 Wiki 图扩展均有独立指标;
- “这个知识库干什么”读取可持续维护、可人工编辑的全库摘要;
- 摘要、混合检索和图扩展都有可追溯引用;
- 离线质量集和性能压测达到约定门槛后再发布。
@@ -11,11 +11,12 @@ This directory contains detailed documentation for the DeerFlow backend.
| [CONFIGURATION.md](CONFIGURATION.md) | Configuration options |
| [SETUP.md](SETUP.md) | Quick setup guide |
## Feature Documentation
| Document | Description |
|----------|-------------|
| [STREAMING.md](STREAMING.md) | Token-level streaming design: Gateway vs DeerFlowClient paths, `stream_mode` semantics, per-id dedup |
## Feature Documentation
| Document | Description |
|----------|-------------|
| [KNOWLEDGE_SPACE_RETRIEVAL_AND_WIKI_EXPANSION_ZH.md](KNOWLEDGE_SPACE_RETRIEVAL_AND_WIKI_EXPANSION_ZH.md) | 知识空间严格优先检索、混合召回、Wiki 图扩展与可编辑全库摘要实现方案 |
| [STREAMING.md](STREAMING.md) | Token-level streaming design: Gateway vs DeerFlowClient paths, `stream_mode` semantics, per-id dedup |
| [FILE_UPLOAD.md](FILE_UPLOAD.md) | File upload functionality |
| [PATH_EXAMPLES.md](PATH_EXAMPLES.md) | Path types and usage examples |
| [summarization.md](summarization.md) | Context summarization feature |
@@ -143,6 +143,12 @@ sequenceDiagram
**`StreamBridge` 的存在价值**:当生产者(`run_agent` 任务)和消费者(HTTP 连接)在不同的 asyncio task 里运行时,需要一个可以跨 task 传递事件的中介。Queue 同时还承担断连重连的 buffer 和多订阅者的 fan-out。
### Gateway 多进程约束
当前 `MemoryStreamBridge` 和 `RunManager` 都只保存当前 Python 进程内的实时状态。首次 `POST /runs/stream` 会在同一个 uvicorn worker 中创建后台 run 并消费事件,因此首连可以正常工作;但响应里的 `Location`、显式 `/join` 和携带 `Last-Event-ID` 的恢复请求都是新的 HTTP 请求。多个 uvicorn worker 会独立调度这些请求,恢复请求一旦落到另一个 worker,该进程看不到原 worker 的 live run 和事件缓冲,只能把持久化 run 记录当作没有可恢复流并提前返回 `end`。持久化 checkpointer/RunStore 不能替代实时事件桥。
因此,使用内存 bridge 时 Gateway 必须运行 **1 个 worker**。两个生产离线启动脚本 `scripts/start_backend-online.sh` 与 `offline-backend-20260512/start_backend.sh` 都默认并校验 `GATEWAY_WORKERS=1`;显式配置更大值会拒绝启动,除非同时设置 `DEERFLOW_ALLOW_UNSAFE_MULTIWORKER=1` 确认接受丢失重连流的风险。真正支持多 worker 需要共享的 StreamBridge 与 live-run 控制面(发布、订阅、结束、取消和活跃 run 查询),不能只依赖负载均衡粘性或数据库中的最终状态。
---
## DeerFlowClient 路径:sync + in-process
@@ -0,0 +1,429 @@
# 任务分析定时 · 对外接口对接文档
> 面向外部任务系统(下称「对方系统」)的开发者。覆盖任务接入、时间线详情拉取、
> 总控问答、**定时数据交付**(任务 6 块 JSON)四组接口。智能体编排配置
> (选业务链 / 执行频率)在 DeerFlow 任务分析页操作,对方系统无需开发。
>
> 相关实现:`app/gateway/routers/task_analysis.py`(任务/绑定/运行记录)、
> `app/gateway/routers/task_analysis_qa.py`(问答)。
## 0. 通用约定
- **Base URL**:DeerFlow Gateway 地址(如 `http://<host>:8001`)。
- **鉴权**:所有接口需带 `Authorization: Bearer <token>` 请求头(token 获取方式见登录对接,本文不重复)。
- **Content-Type**:`application/json`(SSE 接口除外,响应为 `text/event-stream`)。
- **时间格式**:ISO 8601 字符串(含时区,如 `2026-09-10T10:14:55+08:00`)。
- **两类任务标识**:
- `source_task_id`:对方系统的任务号(创建时由你们传入);
- `task_id`:DeerFlow 内部任务 id(**创建接口的响应里返回**,问答接口使用它)。
创建任务后请保存响应中的 `task_id`;也可随时通过时间线详情接口重新取到。
## 1. 任务接入
### 1.1 创建任务
对方系统创建任务完成后调用,DeerFlow 落一条任务记录(初始未绑定分析方案)。
```
POST /api/task-analysis/external/tasks
```
请求体:
```json
{
"source_task_id": "TS-2026-0147",
"name": "东南亚舆论环境监测",
"description": "持续跟踪东南亚重点渠道舆论动向,输出结构化分析详情。"
}
```
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| source_task_id | string(≤128) | 是 | 对方任务号,全局唯一 |
| name | string(≤512) | 是 | 任务名称 |
| description | string(≤8192) | 否 | 任务简介。**定时执行时注入各智能体的任务上下文以此为准**(存量快照,执行时不会回拉) |
响应 `200`:
```json
{
"task_id": "ta-TS-2026-0147",
"default_chain_id": "ta-demo-chain"
}
```
- `task_id`:DeerFlow 内部任务 id,**问答接口需要它**,请保存。
- `default_chain_id`:DeerFlow 侧最近一次绑定使用的业务链 id,可作为你们界面上绑定流程的默认选项;无绑定为 `null`。
错误:`409` —— `source_task_id` 已存在。
### 1.2 删除任务
对方系统删除任务时同步调用,**彻底删除**:任务、绑定、全部执行记录、过程消息与时间线版本一并清除(不可恢复)。
```
DELETE /api/task-analysis/external/tasks/{source_task_id}
```
响应 `200`:`{"deleted": true, "task_id": "..."}`。错误:`404` —— 任务不存在。
## 2. 任务详情(时间线)
对方系统详情页的数据源。每次定时执行成功会落一期**时间线版本**(含各智能体产出),按时间倒序返回。
```
GET /api/task-analysis/external/tasks/{source_task_id}/detail?limit=20&offset=0
```
响应 `200`:
```json
{
"task": {
"task_id": "ta-TS-2026-0147",
"source_task_id": "TS-2026-0147",
"name": "东南亚舆论环境监测"
},
"binding": {
"chain_id": "ta-demo-chain",
"cron_expr": "0 9 * * *",
"schedule_type": "cron",
"enabled": true
},
"timeline": [
{
"id": "…",
"external_task_id": "ta-TS-2026-0147",
"run_id": "tar-…",
"blocks": {
"eightbf-roundtable-intent": {
"name": "8BF 任务理解",
"seat_agent_id": "eightbf-roundtable-intent",
"content": "(该智能体本次产出的 Markdown 正文)",
"format": "markdown"
},
"c0a8799da8724e179e086ea9ca723967": { "name": "策略分析师", "…": "…" }
},
"created_at": "2026-09-10T10:15:13+08:00"
}
]
}
```
- `binding`:当前绑定信息(未绑定为 `null`,此时 `timeline` 不会有新版本)。
`schedule_type` 为执行方式:`cron` = 按 `cron_expr` 频率定时执行;
`once` = 只执行一次(创建后立即执行,之后不再自动执行,`cron_expr` 不生效)。
- `timeline[].blocks`:**每个参与执行的智能体一块**,key 为该智能体的 agent_id,
`name` 为执行时的名称快照,`content` 为其交付正文(Markdown)。
按你们的详情分区规则渲染即可(如按 block 顺序分栏)。
- 分页:`limit`(默认 20)/ `offset`,按 `created_at` 倒序。
## 3. 总控问答(详情页对话)
详情页的对话入口:用户提问 → DeerFlow 总控按任务绑定的编排给对应智能体派活 →
智能体执行 → 总控汇总结论。一次问答会话记为一条「手动执行」记录,过程消息可查。
### 3.1 发起问答会话(init)
```
POST /api/task-analysis/tasks/{task_id}/qa/init
```
> 注意:此处 `{task_id}` 为 **DeerFlow 内部任务 id**(创建接口响应里的 `task_id`)。
请求体:空(无需参数)。
响应 `200`:
```json
{
"run_id": "tar-0743654e-…",
"coordinator": "roundtable-coordinator",
"thread_ids": {
"eightbf-roundtable-intent": "ta-seat-…-…",
"c0a8799da8724e179e086ea9ca723967": "ta-seat-…-…",
"roundtable-coordinator": "ta-seat-…-…"
},
"seats": [
{ "agent_id": "eightbf-roundtable-intent", "name": "8BF 任务理解" },
{ "agent_id": "c0a8799da8724e179e086ea9ca723967", "name": "策略分析师" }
]
}
```
- `run_id`:本次问答会话的运行记录 id(查历史 / 应用方向都用它)。
- `thread_ids`:**会话线程映射,请保存并在后续每轮 stream 原样传回**(会话不跨请求保存在服务端)。
- init 时已自动把任务上下文(名称/简介/编排/历次方向备注)注入总控,之后每轮消息传用户原话即可。
错误:`400` —— 任务未绑定分析方案 / 绑定链没有可调度席位。
### 3.2 发送消息(stream,SSE)
```
POST /api/task-analysis/tasks/{task_id}/qa/stream
Content-Type: application/json
Accept: text/event-stream
```
请求体:
```json
{
"run_id": "tar-0743654e-…",
"message": "请让两个席位各自分析当前的主要风险点,然后给我综合结论。",
"thread_ids": { "…init 返回的映射原样传回…" }
}
```
响应为 SSE 流,每帧 `data: {JSON}\n\n`。**帧类型**:
| 帧 | 触发时机 | 关键字段 |
|---|---|---|
| LangGraph 上游事件(无 `event` 字段的多种帧) | 总控正在生成(token 流) | 透传自运行时,可用于打字机效果 |
| `{"event": "leader", "status": [[seat_id, task], …], …}` | 总控一轮结束 | `status` 为派活表(二维数组)时表示已派活 |
| `{"event": "leader", "status": "clarification", …}` | 总控需要澄清 | `question` / `options`,前端展示追问,等用户补充后发下一轮 |
| `{"event": "leader", "status": [], "content": …}` | 总控给出结论(共识) | `content` 为结论正文 |
| `{"event": "seat", "agent": id, "name": …, "content": …}` | 某智能体执行完成 | `content` 为该智能体交付正文 |
| `{"event": "round_done", "consensus": true/false}` | 本轮结束 | `consensus=true` 会话已收口(run 置 succeeded);`false`(如澄清)可继续发下一轮 |
一轮完整时序:`leader(派活)→ 若干 seat(交付)→ leader(综合结论)→ round_done`。
约定:
- 澄清(`consensus=false, kind=clarification`):继续对**同一 run_id** 发下一轮 stream;
- 共识(`consensus=true`):run 已自动收口,如需再问请新开一次 `qa/init`;
- 客户端中断流不影响服务端继续执行(消息仍会落库,可从历史接口补读)。
错误:`404` 会话不存在;`409` 会话已收口(需重新 init)或 `thread_ids` 缺失(重新 init)。
### 3.3 应用调整方向(可选)
问答结束后,若用户确认「把本次调整应用到后续执行」,调用本接口把结论沉淀为
**执行方向备注**——该备注会注入此任务后续**每次定时执行**各智能体的任务上下文。
```
POST /api/task-analysis/qa/{run_id}/apply-direction
```
请求体:`{"note": "后续执行请重点关注台湾海峡北段动态,风险输出按高/中/低分级。"}`
响应 `200`:`{"applied": true, "direction_notes": ["…", "…"]}`(全部累计备注)。
### 3.4 对话历史查询
按运行记录查询完整过程消息(总控 + 各智能体),供会话回放或补读。
```
GET /api/task-analysis/external/runs/{run_id}/messages?seat=&limit=500
```
- `seat` 可选:传智能体 agent_id 只看该席位;传 `__coordinator__` 只看总控;不传看全部。
- 响应:`{"run": {"id", "trigger", "status", "started_at", "finished_at"}, "messages": […]}`
- 消息字段:`seq`(顺序)、`seat_agent_id`、`stage_index`、`event_type`
(`input` 输入 / `llm.ai` 智能体输出 / `artifact` 产物备注)、`content`。
## 4. 定时数据交付(任务 6 块数据)
按任务展示 **6 块结构化数据**(相当于 6 个页面分区,每块含多个部分),每块一个
JSON 对象。DeerFlow 只负责数据管道与调度:智能体在定时执行过程中把成果提交进
数据块,归配智能体 / 业务链的配置由管理方维护。
**口径要点**:
- 块 key 定死 `block_1`~`block_6`,标题默认「数据块一~六」,可经 4.4 修改;
存量 5 块任务在读接口 / 首次提交时懒补 `block_6`,已改过的标题不覆盖;
- payload 不做 schema 校验(结构会变),只要求是 **JSON 对象**;
- 不定席位↔块映射:多个智能体可各写一个块的不同部分,一个智能体也可写多个块;
- 同一块多次提交按「**顶层 key 合并、同 key 后写覆盖**」合并——某个部分一提交,
立刻体现在任务的当前数据里(实时更新);
- **不挂时间轴**:一个任务的数据只有一份「当前状态」,所有提交(定时轮次、
手动触发、对话修复)都合并进它,越提交越新;
- 调度不管上一轮跑没跑完:到期照常触发,**同任务允许多轮并行**,不跳过不顺延;
多轮提交按流水顺序收敛到同一份数据;
- 首次提交时若任务还没有数据承载记录,自动创建一条(`trigger=external`),
保证写入永远成功。
### 4.1 数据块定义列表
```
GET /api/task-analysis/external/tasks/{source_task_id}/blocks
```
响应 `200`:
```json
{
"task": {"task_id": "ta-TS-2026-0147", "source_task_id": "TS-2026-0147", "name": "东南亚舆论环境监测"},
"blocks": [
{"block_key": "block_1", "title": "数据块一", "sort_order": 1},
{"block_key": "block_2", "title": "数据块二", "sort_order": 2},
{"block_key": "block_3", "title": "舆情热点", "sort_order": 3},
{"block_key": "block_4", "title": "数据块四", "sort_order": 4},
{"block_key": "block_5", "title": "数据块五", "sort_order": 5},
{"block_key": "block_6", "title": "数据块六", "sort_order": 6}
]
}
```
固定 6 条,按 `sort_order` 升序返回;`title` 为修改后的标题(见 4.4)。
### 4.2 当前数据状态(兼容旧路径 periods)
```
GET /api/task-analysis/external/tasks/{source_task_id}/periods
```
时间轴已去掉:任务的数据只有一份当前状态,本接口固定返回**唯一一条**当前数据
承载记录(`periods` 数组长度恒为 1,`is_current` 恒为 `true`),供消费方感知
数据更新时间。响应 `200`:
```json
{
"task": {"task_id": "…", "source_task_id": "…", "name": "…"},
"current_period_index": 3,
"total": 1,
"periods": [
{
"period_index": 3,
"opened_at": "2026-09-14T15:00:00+08:00",
"trigger": "cron",
"run_id": "tar-…",
"is_current": true,
"blocks": {
"block_1": {"updated_at": "2026-09-14T15:03:12+08:00"},
"block_2": {"updated_at": null},
"block_3": {"updated_at": null},
"block_4": {"updated_at": null},
"block_5": {"updated_at": null},
"block_6": {"updated_at": null}
}
}
]
}
```
- 各块 `updated_at` 为 `null` 表示该块尚无数据;
- 首条承载记录由首次数据提交自动创建(`trigger=external`);存量任务沿用
历史期号(`period_index` 数值仅作标识,无时间轴含义)。
### 4.3 单期数据详情
```
GET /api/task-analysis/external/tasks/{source_task_id}/periods/{period}
```
`{period}` 传期号数字(如 `2`)或 `latest`(当前最新一期)。响应 `200`:
```json
{
"task": {"task_id": "…", "source_task_id": "…", "name": "…"},
"period": {
"period_index": 2,
"opened_at": "2026-09-14T12:00:00+08:00",
"trigger": "cron",
"run_id": "tar-…",
"is_current": false
},
"blocks": [
{
"block_key": "block_1",
"title": "数据块一",
"sort_order": 1,
"payload": {"热点列表": ["…"], "统计": {"提及量": 128}},
"updated_at": "2026-09-14T12:04:55+08:00"
},
{"block_key": "block_2", "title": "数据块二", "sort_order": 2, "payload": null, "updated_at": null}
]
}
```
- `blocks` 固定 6 条、按 `sort_order` 升序;尚未提交的块 `payload` / `updated_at`
为 `null`;
- `payload` 即该块的**合并结果**(多次提交按顶层 key 合并、同 key 后写覆盖),
结构由智能体产出决定,请按 JSON 对象渲染;
- `{period}` 推荐传 `latest`(当前数据);传数字期号可访问存量任务的历史
遗留数据(时间轴去掉前的旧期,仅供排查)。
错误:`404` —— 期不存在;`400` —— `period` 既不是数字也不是 `latest`。
### 4.4 修改块标题 / 排序(管理端)
块标题支持后续修改(页面 + API)。`{task_id}` 为 **DeerFlow 内部任务 id**(创建
接口响应里保存的那个)。
```
PUT /api/task-analysis/tasks/{task_id}/blocks
```
请求体(只传要改的块;块集合固定 6 条,不能增删):
```json
{
"blocks": [
{"block_key": "block_3", "title": "舆情热点"},
{"block_key": "block_1", "sort_order": 9}
]
}
```
响应 `200`:`{"blocks": […]}`(修改后的完整定义列表,形状同 4.1)。
错误:`400` —— `block_key` 不在 `block_1`~`block_6` 内。
### 4.5 演示数据(已预存)
开发环境已预存一个演示任务,可直接用于联调:
- 任务号 `source_task_id = BUSINESS-OVERVIEW-DEMO`;`block_1` 标题「商业态势总览」;
- 预存时按 13 期小时刻度写入(时间轴去掉前的演示口径);当前对外仅暴露最新一期
的 `block_1` payload = 页面整卡数据(`pageTitle` / `briefs` / `objectives` /
`events` / `businessNarratives` / `insights` / `chart` / `snapshotName` 等,
与页面 mock 快照同构);`block_2`~`block_6` 暂无数据;
- 预存脚本:`scripts/seed_business_overview_demo.py`(可重复运行,幂等重建)。
### 4.6 智能体数据提交(内部,供参考)
智能体侧由内置技能 `task-data-submit`(`skills/public/task-data-submit/`)调以下
接口完成入库,**对方系统无需调用**,此处仅供联调排查参考:
```
POST /api/task-analysis/data/submit
```
请求体:`{"task_id": "<source_task_id>", "block_key": "block_2", "data": {…JSON 对象…}}`。
响应 `200`:`{"source_task_id", "task_id", "block_key", "period_index", "updated_at", "keys"}`。
错误:`400` —— 块 key 非法 / payload 不是对象;`404` —— 任务不存在;`422` ——
请求体不是合法 JSON 对象。
## 5. 典型对接流程
```
对方系统创建任务
└─ POST /external/tasks ──► 保存 task_id(+ default_chain_id)
│
│ (DeerFlow 管理页配置:选业务链 + 执行频率 —— 无需开发)
▼
按 cron 自动执行(多轮并行,产出时间线版本)
├─ 详情页定期/手动 GET /external/tasks/{source_task_id}/detail ──► 渲染 blocks
└─ 数据交付(任务 6 块 JSON,见第 4 章)
├─ GET /external/tasks/{source_task_id}/periods ──► 当前数据状态(兼容路径)
└─ GET /external/tasks/{source_task_id}/periods/latest ──► 6 块完整 JSON
│
▼
详情页问答(可选)
├─ POST /tasks/{task_id}/qa/init ──► 保存 run_id + thread_ids
├─ POST /tasks/{task_id}/qa/stream(每轮,SSE 渲染对话与席位交付)
├─ (可选)POST /qa/{run_id}/apply-direction ──► 调整注入后续执行
└─ GET /external/runs/{run_id}/messages ──► 历史回放
对方系统删除任务
└─ DELETE /external/tasks/{source_task_id} ──► DeerFlow 侧级联清除
```
## 6. 错误码汇总
| 状态 | 场景 |
|---|---|
| 400 | 任务未绑定分析方案 / 链无席位 / 请求参数非法 / 数据块 key 非法 |
| 401 | 未带 token 或 token 失效 |
| 404 | 任务 / 会话 / 运行记录 / 期不存在 |
| 409 | `source_task_id` 重复创建;会话已收口或线程映射缺失;执行被跳过(业务链已删除/停用) |
@@ -0,0 +1,143 @@
# 上下文超限自动恢复与压测记录
验证日期:2026-09-11。
## 行为
- 模型管理的 `max_input_tokens` 保持可空,不增加 32000 或任何默认模型窗口。明确配置或已有模型 profile 时做预裁剪;两者均无时,首个请求保持原样。
- 主代理、子代理的最终 `ContextWindowGuardMiddleware` 在模型明确返回超限时,对实际发送的请求副本缩短后重试,不重新执行外层摘要、RAG 或记忆注入。原始会话历史不改写。
- 最多首次调用加四次恢复调用。恢复预算来自失败请求的估算值,每次降到约 35%;最后尝试最小请求。30 秒用于限制继续发起恢复尝试,单次调用的超时仍由模型配置控制。
- 不盲目缩减已较小的输出额度,避免推理模型耗尽额度却没有正文。恢复后仍只有思考内容或空白时,普通问答返回自然澄清。
- 不发送空消息列表;不静默删除结构化输出格式和强制工具约束。必要约束无法满足时保留内部失败标记,供业务调用方识别,不能伪造成功 JSON 或已执行的操作。
- 摘要限制针对最终渲染的请求(包括 XML 和摘要提示词)。使用已有摘要裁剪配置与摘要模型上限中较小者,不新增默认模型窗口;`trim_tokens_to_summarize: null` 现在会正确传递。
- 摘要超限也缩短重试;摘要失败时保留可用旧摘要、最近消息和真实用户问题,不缓存失败文案、不阻断主问答。内部摘要调用隔离父级流式回调,避免摘要文字混入回答。
- 上下文错误识别兼容实测 MiniMax 的 `invalid params, context window exceeds limit (2013)`。普通鉴权、额度、网络等错误仍由原错误处理流程负责。
## 自动回归
以下命令从 backend 目录运行:
```powershell
.venv/Scripts/python.exe -m pytest tests/test_context_recovery.py tests/test_context_recovery_transport.py tests/test_llm_error_handling_middleware.py tests/test_summarization_human_message.py tests/test_summarization_multiturn.py tests/test_model_management.py tests/test_writing_mode_report_middleware.py tests/test_roundtable_role_boundary.py -q -p no:cacheprovider
```
首轮结果:135 passed;补充多轮问答后的最终结果:**168 passed**。
覆盖内容:
- 未填写输入上限时不擅自预裁剪,显式上限和绑定模型 profile 生效。
- 中英文、表情、单条超长输入;持续超限;输出预算;极小无效预算。
- 50 组固定随机种子的历史消息、工具调用/结果、隐藏上下文和系统提示组合,验证长度、工具配对与原始历史不变。
- 同步/异步恢复、取消、LangGraph 中断、重试时限、熔断半开探针释放。
- 摘要输入超限、摘要不可用、失败不污染缓存、摘要消息流不泄漏。
- 真实 `PatchedChatOpenAI` 客户端 + 模拟 HTTP 400/SSE + LangGraph 的端到端请求链,验证只返回一次正文、不重复上下文注入、不泄漏超限异常。
Python 改动与新增测试、探针脚本通过 Ruff 检查。
## 真实模型联调
使用当前配置中的 MiniMax-M2.7,仅发送自动生成的合成材料,不使用用户会话或业务文档。40000 行输入的本地估算从 **1,840,102** 降到 **644,001**;这些是保守估算值,不是供应商统计的实际 token 数。
| 模式 | 首次调用 | 第二次调用 | 可见正文 | 耗时 |
| --- | --- | --- | --- | --- |
| 普通调用 | 真实上下文超限 2013 | 自动缩短后成功 | 验证通过 | 18.83 秒 |
| SSE 流式 | 真实上下文超限 2013 | 自动缩短后成功 | 验证通过 | 21.26 秒 |
可重复运行的脚本(真实请求会消耗已配置模型额度):
```powershell
.venv/Scripts/python.exe scripts/probe_context_recovery.py --live --model MiniMax-M2.7 --rows 40000
.venv/Scripts/python.exe scripts/probe_context_recovery.py --live --model MiniMax-M2.7 --rows 40000 --stream
```
探针只在进程内设置 90 秒请求超时与 1024 输出预算,不修改配置文件。初期以较小输出预算测试时发现只有思考、没有正文的问题;30 秒网络超时测试也曾超时,扩大探针超时后完成上述验证。生产调用仍使用自身超时配置。
## 多轮问答追加验证
当前配置的主动摘要开关为 `summarization.enabled: false`,前端默认 `contextCompressionEnabled: false`。前端开启“上下文压缩”后,通过 `summarization_enabled` 传到后端。触发条件为 **120000 token 或 160 条消息**,保留目标为 40000 token。未开启主动摘要时,不会因为对话轮次增加而调用摘要模型;上下文超限后的裁剪重试仍可独立工作。本次没有修改这些开关或生产阈值。
多轮测试发现并修复:
1. 消息数达到阈值但历史尚未达到 token 保留目标时,提前返回导致不触发摘要。现在先执行保留窗口调整,再判断是否有历史可摘要。
2. 反复从全量旧历史重新摘要,旧事实可能被摘要输入截断删除。现在使用“上次摘要 + 新增历史”增量合并,并保留完整原始消息。
3. 摘要提示词与历史拼接后整体截断,可能保留提示词却删除历史开头。现在先计算提示词与已有摘要开销,再给历史分配预算。
4. 历史回复的思考文本、历史 token 用量缩放、摘要输出的思考文本可能干扰事实提取。现在清理这些信息的临时副本,存储的原始聊天记录不改写。
5. 摘要模型可能执行历史中的“只回复已记住”。现在明确区分摘要任务和历史数据,过滤纯确认回复;摘要失败时保留尚未成功摘要的事实,由最终 guard 按实际需要裁剪,不把确认文案当记忆。
6. 补齐 fraction 阈值、复合条件和绑定模型 profile 的多轮处理。
| 测试 | 真正生成摘要的轮次 | 结果 |
| --- | --- | --- |
| 当前阈值的 105 轮模拟,逐轮重建 agent | 81、101 | 210 条消息完整,早期事实可回忆 |
| 小摘要预算的 24 轮模拟 | 5、8、11、14、17、20、23 | 多次合并后仍保留首轮事实 |
| 12 轮工具问答,同步/异步分别运行 | 多次触发 | 每轮工具恰好执行一次,48 条消息完整,调用与结果不拆散 |
| 真实 MiniMax 12 轮,第一次最终复测 | 5、8、11 | 正确回忆代号、更新后的预算和期限;59.02 秒 |
| 真实 MiniMax 12 轮,第二次独立复测 | 5、8、11 | 再次通过相同事实检查;68.16 秒 |
真实测试为加快验证,仅在探针进程内把摘要触发调为 8 条消息、保留 2 条消息,并使用 2048 输出预算;**未设置默认输入上限,也未修改配置文件**。第 9 轮清空进程摘要缓存,检查能否从会话检查点恢复。第 6、7、9、10、12 轮复用摘要,不额外调用摘要模型。每次真正摘要均检查 checkpoint 中的摘要覆盖范围确实更新,而不只检查触发事件。
首轮提供代号 `ORBIT-42`、预算 35 万元和期限 `2026-12-20`,第 6 轮把预算改为 48 万元,第 8 轮把期限改为 `2026-12-28`。两次最终复测第 12 轮均正确返回:
```json
{"code":"ORBIT-42","budget":48,"deadline":"2026-12-28"}
```
复测过程中曾出现“摘要更新了,但答案事实错误”的失败,未计为通过;上述两次成功记录均来自清理历史思考及用量缩放后的版本。逐轮输入场景、正文、摘要正文和缓存更新记录保存在:
- [第一次最终复测](multiturn-probe-20260911.json)
- [第二次独立复测](multiturn-probe-20260911-repeat.json)
复现命令(使用合成材料,会调用已配置模型):
```powershell
.venv/Scripts/python.exe scripts/probe_multiturn_compression.py --live --output docs/multiturn-probe-20260911.json
```
## 前端及验证边界
- 模型管理页已注明输入上限可留空;该 TSX 文件单独转换通过。
- `pnpm typecheck` **未通过**:未改动的 `message-list-item.tsx`、`core/blog`(缺少 nextra)、`GeneralQA.tsx` 等存在类型或依赖错误。本次不把前端全量检查记为通过。
- 真实供应商测试覆盖 MiniMax-M2.7,不能等同于所有供应商均已实测。主代理/子代理和摘要调用以外的独立模型调用不因该中间件自动获得保护;标题生成原本已有本地标题降级。
- 极端情况下会丢失部分材料并请求用户补充;恢复机制不保证缺失信息时仍能完成原任务,也不掩盖鉴权失败、额度不足或服务不可用。
## 部署版本兼容修复(2026-09-11)
前面的本机测试使用 LangChain 1.3.15,未覆盖部署的 1.2.15,这是此前验证的遗漏。
已在真实 1.2.15 包上复现 `_trigger_clauses` AttributeError:旧基类只提供 `_trigger_conditions`。
现在应用自行保存和计算触发条件,不再读取这两个版本相关的私有属性;字典条件的 AND、条件列表的 OR 和旧参数映射保持一致。
此前新增的 `internal_call_transformer` 依赖已移除。没有要求升级部署依赖,没有引入默认输入上限。
本次将用户提供的全部 20 个包安装到隔离目录,以 PYTHONPATH 优先加载,未替换本机虚拟环境。
其余未提供版本的依赖沿用本机,测试主机为 Windows;不把该结果宣称为生产服务器完整环境的启动验证。
- 用户版本组合(LangChain 1.2.15、Core 1.3.2、LangGraph 1.1.9 等):177 项通过,26.26 秒。
- 本机新版组合:同样 177 项通过,24.64 秒。
- 覆盖 Gateway / 主代理导入、105 轮问答、重复压缩、缓存恢复、同步/异步工具和消息流隔离。
- 新增删除基类两个私有触发属性后仍能正常判断阈值的回归测试,涵盖 tuple、OR、AND、混合和未启用情况。
- 用户版本组合下真实 MiniMax-M2.7 12 轮问答:第 5、8、11 轮摘要,第 9 轮清空进程缓存后正常恢复;最终准确返回代号 ORBIT-42、更新预算 48、更新期限 2026-12-28。54.53 秒,无属性错误。
- 所有被调用的摘要中间件方法均已检查能在 1.2.15 下解析;Ruff 通过。
[用户版本组合的真实多轮记录及 20 个版本号](multiturn-probe-langchain-1.2.15.json)。
## 隐藏压缩提示与连续问答复测
后台仅记录真实摘要日志,不再向 custom 流发送 `context_compacting` 通知;前端也忽略旧后台的同名事件,不弹 toast。摘要开关和压缩功能保留。
新增模型每轮上报 150000 输入 token 的 12 轮测试,使用 2000 token 摘要触发阈值:同步和异步均仅在第 2 轮摘要,后续复用;历史用量数据未修改。该测试在用户的 1.2.15 依赖组合和本机新版均通过。部署组合相关回归共 118 项通过(22.28 秒)。
尚未拿到用户连续弹提示时的后台 cache / counted_tokens / msgs 日志,未复现该会话的每轮重复摘要,不能把隐藏提示当作已修复重复摘要根因。
## 修复压缩后每轮重新摘要
已用过长摘要复现另一条真实缺陷路径:摘要加保留内容在生成当时就超过阈值,旧逻辑之后每轮都会把同一个超阈值基础内容再次送摘要模型。12 轮测试中第 2~12 轮均调用摘要。此前的简短摘要测试没有覆盖此边界;尚无生产会话日志,不能据此断言这是用户会话唯一原因。
修复:缓存可用且上次压缩结果本身就超阈值时,要求**压缩后新增内容**累计达到原触发阈值的 25% 才再摘要。正常压缩后低于阈值的路径保持原判定。这个比例用于避免无效重复摘要,不是模型输入上限;最终 ContextWindowGuard 的裁剪及超限重试继续工作。子集计数移除原请求 usage_metadata 的缩放影响,只修改临时副本。日志新增 waiting_for_growth,并区分 unusable 与 stale 缓存。
用户提供的 1.2.15 等 20 个包组合最终回归 **187 passed,26.59 秒**:
- 12 轮过长摘要 + 短追问:仅第 2 轮摘要,修复前为第 2~12 轮;同步/异步均通过。
- 36 轮持续增加材料:第 2、19、36 轮摘要;每轮清空进程缓存,仍可由 checkpoint 恢复,不是直接禁用后续摘要。
- 超长摘要 + 严格 800 token 测试模型 + 连续 8 轮:分别验证配置上限(预裁剪,无拒绝)和不配置(真实抛出 context_length_exceeded 后缩短重试),同步/异步四种组合均正常回答最新问题;原会话消息数完整。这里使用可控测试模型,未宣称所有供应商均实测。
- 既有 105 轮、工具执行、首次阈值、缓存恢复、旧版导入及摘要流隔离回归继续通过。Ruff 通过。
@@ -0,0 +1,133 @@
{
"model": "MiniMax-M2.7",
"trigger_messages": 8,
"keep_messages": 2,
"rows": [
{
"turn": 1,
"compression": "passthrough",
"history_messages": 2,
"has_cache": false,
"visible": "已记住。",
"elapsed_seconds": 6.34,
"summary_updated": false
},
{
"turn": 2,
"compression": "passthrough",
"history_messages": 4,
"has_cache": false,
"visible": "已记住。",
"elapsed_seconds": 2.16,
"summary_updated": false
},
{
"turn": 3,
"compression": "passthrough",
"history_messages": 6,
"has_cache": false,
"visible": "已记住。",
"elapsed_seconds": 1.45,
"summary_updated": false
},
{
"turn": 4,
"compression": "passthrough",
"history_messages": 8,
"has_cache": false,
"visible": "已记住。",
"elapsed_seconds": 2.77,
"summary_updated": false
},
{
"turn": 5,
"compression": "summarize",
"history_messages": 10,
"has_cache": true,
"visible": "项目代号为ORBIT-42,预算为35万元,截止日期为2026年12月20日。",
"elapsed_seconds": 18.06,
"summary_updated": true,
"summary_text": "## SESSION INTENT\nThe user is establishing project parameters for a knowledge base/Q&A system with report export capabilities. The AI is being used as a memory keeper to retain key project constraints and requirements for future reference.\n\n## SUMMARY\nProject ORBIT-42 is defined with the following parameters:\n- **Budget**: 35万元 (350,000 yuan)\n- **Deadline**: 2026-12-20\n- **Scope**: System must support document retrieval, question answering, and report export\n- **Data Constraint**: Real customer data cannot be uploaded; only synthetic test materials are permitted\n- **Acceptance Criteria**: Must verify citation sources, output format compliance, and interface stability\n\nNo implementation work has begun. This session consists entirely of requirements gathering and acknowledgment.\n\n## ARTIFACTS\nNone. No files, code, or resources have been created or modified during this session.\n\n## NEXT STEPS\n- Begin system architecture design and implementation planning\n- Create synthetic test data materials for development and testing\n- Implement core functionalities: document retrieval, Q&A engine, and report export module\n- Establish validation framework for citation checking, format compliance, and interface stability testing"
},
{
"turn": 6,
"compression": "reuse",
"history_messages": 12,
"has_cache": true,
"visible": "已更新。",
"elapsed_seconds": 2.14,
"summary_updated": false
},
{
"turn": 7,
"compression": "reuse",
"history_messages": 14,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 3.05,
"summary_updated": false
},
{
"turn": 8,
"compression": "summarize",
"history_messages": 16,
"has_cache": true,
"visible": "已更新。",
"elapsed_seconds": 14.64,
"summary_updated": true,
"summary_text": "## SESSION INTENT\n\n用户正在建立知识库/问答系统的项目参数,需要AI作为记忆 keeper 保留关键项目约束和需求供后续参考。\n\n## SUMMARY\n\n项目 ORBIT-42 的参数如下:\n\n- **项目代号**:ORBIT-42\n- **预算**:48万元(已从35万元更新)\n- **截止日期**:2026年12月20日\n- **项目范围**:系统需支持文档检索、问答、报告导出三大功能\n- **数据约束**:不得使用真实客户数据,仅可使用合成测试材料\n- **报告格式约束**:报告必须用中文撰写,且先写结论再写依据\n- **验收标准**:验证引用来源、输出格式合规、接口稳定性\n\n## ARTIFACTS\n\n无。暂无文件或代码被创建或修改。\n\n## NEXT STEPS\n\n- 开始系统架构设计与实现规划\n- 创建合成测试数据材料用于开发和测试\n- 实现核心功能:文档检索、问答引擎、报告导出模块\n- 建立验证框架用于引用检查、格式合规和接口稳定性测试"
},
{
"turn": 9,
"compression": "reuse",
"history_messages": 18,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 3.31,
"summary_updated": false
},
{
"turn": 10,
"compression": "reuse",
"history_messages": 20,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 2.72,
"summary_updated": false
},
{
"turn": 11,
"compression": "summarize",
"history_messages": 22,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 9.44,
"summary_updated": true,
"summary_text": "## SESSION INTENT\n\n用户正在建立知识库/问答系统的项目参数,需要AI作为记忆 keeper 保留关键项目约束和需求供后续参考。\n\n## SUMMARY\n\n项目 ORBIT-42 的参数如下:\n\n- **项目代号**:ORBIT-42\n- **预算**:48万元\n- **截止日期**:2026年12月28日(已更新)\n- **项目范围**:系统需支持文档检索、问答、报告导出三大功能\n- **数据约束**:不得使用真实客户数据,仅可使用合成测试材料\n- **报告格式约束**:报告必须用中文撰写,且先写结论再写依据\n- **验收标准**:\n - 验证引用来源、输出格式合规、接口稳定性\n - 必须覆盖多轮问答和长材料(新增)\n- **数据留存要求**:测试报告必须留存,不得删除已有聊天记录(新增)\n\n## ARTIFACTS\n\n无。暂无文件或代码被创建或修改。\n\n## NEXT STEPS\n\n- 开始系统架构设计与实现规划\n- 创建合成测试数据材料用于开发和测试\n- 实现核心功能:文档检索、问答引擎、报告导出模块\n- 建立验证框架用于引用检查、格式合规和接口稳定性测试\n- 设计聊天记录和测试报告的持久化存储方案"
},
{
"turn": 12,
"compression": "reuse",
"history_messages": 24,
"has_cache": true,
"visible": "```json\n{\n \"code\": \"ORBIT-42\",\n \"budget\": 48,\n \"deadline\": \"2026-12-28\"\n}\n```",
"elapsed_seconds": 2.02,
"summary_updated": false
}
],
"fact_check": true,
"summary_rounds": [
5,
8,
11
],
"reuse_rounds": [
6,
7,
9,
10,
12
],
"outcome": "passed",
"elapsed_seconds": 68.16
}
@@ -0,0 +1,133 @@
{
"model": "MiniMax-M2.7",
"trigger_messages": 8,
"keep_messages": 2,
"rows": [
{
"turn": 1,
"compression": "passthrough",
"history_messages": 2,
"has_cache": false,
"visible": "已记住",
"elapsed_seconds": 9.39,
"summary_updated": false
},
{
"turn": 2,
"compression": "passthrough",
"history_messages": 4,
"has_cache": false,
"visible": "已记住",
"elapsed_seconds": 2.08,
"summary_updated": false
},
{
"turn": 3,
"compression": "passthrough",
"history_messages": 6,
"has_cache": false,
"visible": "已记住",
"elapsed_seconds": 1.62,
"summary_updated": false
},
{
"turn": 4,
"compression": "passthrough",
"history_messages": 8,
"has_cache": false,
"visible": "已记住",
"elapsed_seconds": 3.27,
"summary_updated": false
},
{
"turn": 5,
"compression": "summarize",
"history_messages": 10,
"has_cache": true,
"visible": "项目代号为ORBIT-42,预算35万元,截止日期为2026年12月20日。",
"elapsed_seconds": 12.16,
"summary_updated": true,
"summary_text": "## SESSION INTENT\nEstablish and remember project ORBIT-42 parameters for an upcoming project session, including budget, deadline, scope, constraints, and acceptance criteria.\n\n## SUMMARY\n- Project Code: ORBIT-42\n- Budget: 35万元 (350,000 RMB)\n- Deadline: 2026-12-20\n- Scope: System must support document retrieval, Q&A functionality, and report export capabilities\n- Constraint: Real customer data cannot be uploaded; only synthetic test materials may be used\n- Acceptance Criteria: Must verify citation sources, output format compliance, and API stability\n\n## ARTIFACTS\nNone created or modified.\n\n## NEXT STEPS\nReady to begin project ORBIT-42 implementation. Next steps will involve setting up the system architecture, creating synthetic test datasets, and implementing the three core features (document retrieval, Q&A, report export) within the budget and timeline constraints."
},
{
"turn": 6,
"compression": "reuse",
"history_messages": 12,
"has_cache": true,
"visible": "已更新。",
"elapsed_seconds": 2.12,
"summary_updated": false
},
{
"turn": 7,
"compression": "reuse",
"history_messages": 14,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 2.84,
"summary_updated": false
},
{
"turn": 8,
"compression": "summarize",
"history_messages": 16,
"has_cache": true,
"visible": "已更新。",
"elapsed_seconds": 8.55,
"summary_updated": true,
"summary_text": "## SESSION INTENT\nEstablish and remember project ORBIT-42 parameters for an upcoming project session, including budget, deadline, scope, constraints, and acceptance criteria.\n\n## SUMMARY\n- Project Code: ORBIT-42\n- Budget: 48万元 (480,000 RMB)\n- Deadline: 2026-12-20\n- Scope: System must support document retrieval, Q&A functionality, and report export capabilities\n- Constraint: Real customer data cannot be uploaded; only synthetic test materials may be used\n- Additional Constraint: Reports must be in Chinese, with conclusions written first followed by supporting evidence/reasoning\n- Acceptance Criteria: Must verify citation sources, output format compliance, and API stability\n\n## ARTIFACTS\nNone created or modified.\n\n## NEXT STEPS\nReady to begin project ORBIT-42 implementation. Next steps will involve setting up the system architecture, creating synthetic test datasets, and implementing the three core features (document retrieval, Q&A, report export) within the budget and timeline constraints."
},
{
"turn": 9,
"compression": "reuse",
"history_messages": 18,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 1.51,
"summary_updated": false
},
{
"turn": 10,
"compression": "reuse",
"history_messages": 20,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 1.74,
"summary_updated": false
},
{
"turn": 11,
"compression": "summarize",
"history_messages": 22,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 10.69,
"summary_updated": true,
"summary_text": "## SESSION INTENT\nEstablish and remember project ORBIT-42 parameters for an upcoming project session, including budget, deadline, scope, constraints, and acceptance criteria.\n\n## SUMMARY\n- Project Code: ORBIT-42\n- Budget: 48万元 (480,000 RMB)\n- Deadline: 2026-12-28 (updated from 2026-12-20)\n- Scope: System must support document retrieval, Q&A functionality, and report export capabilities\n- Constraint: Real customer data cannot be uploaded; only synthetic test materials may be used\n- Additional Constraint: Reports must be in Chinese, with conclusions written first followed by supporting evidence/reasoning\n- Acceptance Criteria: Must verify citation sources, output format compliance, and API stability\n- Updated Acceptance Criteria: Must cover multi-turn Q&A and long materials testing\n- Data Retention Requirement: Must retain test reports; cannot delete existing chat records\n\n## ARTIFACTS\nNone created or modified.\n\n## NEXT STEPS\nReady to begin project ORBIT-42 implementation. Next steps will involve setting up the system architecture, creating synthetic test datasets, and implementing the three core features (document retrieval, Q&A, report export) within the budget and timeline constraints."
},
{
"turn": 12,
"compression": "reuse",
"history_messages": 24,
"has_cache": true,
"visible": "```json\n{\n \"code\": \"ORBIT-42\",\n \"budget\": 48,\n \"deadline\": \"2026-12-28\"\n}\n```",
"elapsed_seconds": 3.02,
"summary_updated": false
}
],
"fact_check": true,
"summary_rounds": [
5,
8,
11
],
"reuse_rounds": [
6,
7,
9,
10,
12
],
"outcome": "passed",
"elapsed_seconds": 59.02
}
@@ -0,0 +1,155 @@
{
"model": "MiniMax-M2.7",
"trigger_messages": 8,
"keep_messages": 2,
"rows": [
{
"turn": 1,
"compression": "passthrough",
"history_messages": 2,
"has_cache": false,
"visible": "已记住",
"elapsed_seconds": 4.78,
"summary_updated": false
},
{
"turn": 2,
"compression": "passthrough",
"history_messages": 4,
"has_cache": false,
"visible": "已记住。",
"elapsed_seconds": 3.19,
"summary_updated": false
},
{
"turn": 3,
"compression": "passthrough",
"history_messages": 6,
"has_cache": false,
"visible": "已记住。",
"elapsed_seconds": 1.91,
"summary_updated": false
},
{
"turn": 4,
"compression": "passthrough",
"history_messages": 8,
"has_cache": false,
"visible": "已记住。",
"elapsed_seconds": 1.39,
"summary_updated": false
},
{
"turn": 5,
"compression": "summarize",
"history_messages": 10,
"has_cache": true,
"visible": "项目代号为ORBIT-42,预算为35万元,截止日期为2026年12月20日。",
"elapsed_seconds": 13.5,
"summary_updated": true,
"summary_text": "## SESSION INTENT\nSet up and remember project ORBIT-42 parameters for future reference in this session.\n\n## SUMMARY\n- Project Code: ORBIT-42\n- Budget: 35万元 (350,000 RMB)\n- Deadline: 2026-12-20\n- Scope: System must support information retrieval, Q&A functionality, and report export\n- Constraint: Real customer data cannot be uploaded; only synthetic test materials may be used\n- Acceptance Criteria: Must verify reference sources, output format compliance, and interface stability\n\n## ARTIFACTS\nNone created or modified.\n\n## NEXT STEPS\nProject parameters are stored. Awaiting further instructions on ORBIT-42 project implementation."
},
{
"turn": 6,
"compression": "reuse",
"history_messages": 12,
"has_cache": true,
"visible": "已更新。",
"elapsed_seconds": 1.62,
"summary_updated": false
},
{
"turn": 7,
"compression": "reuse",
"history_messages": 14,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 1.31,
"summary_updated": false
},
{
"turn": 8,
"compression": "summarize",
"history_messages": 16,
"has_cache": true,
"visible": "已更新。",
"elapsed_seconds": 9.2,
"summary_updated": true,
"summary_text": "## SESSION INTENT\nSet up and remember project ORBIT-42 parameters for future reference in this session.\n\n## SUMMARY\n- Project Code: ORBIT-42\n- Budget: 48万元 (updated from 35万元)\n- Deadline: 2026-12-20\n- Scope: System must support information retrieval, Q&A functionality, and report export\n- Constraint: Real customer data cannot be uploaded; only synthetic test materials may be used\n- NEW Constraint: Reports must be in Chinese, conclusions first then basis\n- Acceptance Criteria: Must verify reference sources, output format compliance, and interface stability\n\n## ARTIFACTS\nNone created or modified.\n\n## NEXT STEPS\nProject parameters are stored. Awaiting further instructions on ORBIT-42 project implementation."
},
{
"turn": 9,
"compression": "reuse",
"history_messages": 18,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 2.24,
"summary_updated": false
},
{
"turn": 10,
"compression": "reuse",
"history_messages": 20,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 1.67,
"summary_updated": false
},
{
"turn": 11,
"compression": "summarize",
"history_messages": 22,
"has_cache": true,
"visible": "已记住。",
"elapsed_seconds": 10.02,
"summary_updated": true,
"summary_text": "## SESSION INTENT\nSet up and remember project ORBIT-42 parameters for future reference in this session.\n\n## SUMMARY\n- Project Code: ORBIT-42\n- Budget: 48万元\n- Deadline: 2026-12-28 (updated from 2026-12-20)\n- Scope: System must support information retrieval, Q&A functionality, and report export\n- Constraint: Real customer data cannot be uploaded; only synthetic test materials may be used\n- Constraint: Reports must be in Chinese, conclusions first then basis\n- Acceptance Criteria:\n - Must verify reference sources\n - Output format compliance\n - Interface stability\n - Must cover multi-turn Q&A and long documents\n - Must retain test reports, cannot delete existing chat records\n\n## ARTIFACTS\nNone created or modified.\n\n## NEXT STEPS\nProject parameters are stored. Awaiting further instructions on ORBIT-42 project implementation."
},
{
"turn": 12,
"compression": "reuse",
"history_messages": 24,
"has_cache": true,
"visible": "```json\n{\n \"code\": \"ORBIT-42\",\n \"budget\": 48,\n \"deadline\": \"2026-12-28\"\n}\n```",
"elapsed_seconds": 3.62,
"summary_updated": false
}
],
"fact_check": true,
"summary_rounds": [
5,
8,
11
],
"reuse_rounds": [
6,
7,
9,
10,
12
],
"outcome": "passed",
"elapsed_seconds": 54.53,
"tested_dependency_versions": {
"langchain": "1.2.15",
"langchain-anthropic": "1.4.1",
"langchain-core": "1.3.2",
"langchain-deepseek": "1.0.1",
"langchain-google-genai": "4.2.2",
"langchain-mcp-adapters": "0.2.2",
"langchain-openai": "1.2.1",
"langchain-protocol": "0.0.12",
"langfuse": "4.5.1",
"langgraph": "1.1.9",
"langgraph-api": "0.8.1",
"langgraph-checkpoint": "4.0.2",
"langgraph-checkpoint-postgres": "3.0.5",
"langgraph-checkpoint-sqlite": "3.0.3",
"langgraph-cli": "0.4.24",
"langgraph-prebuilt": "1.0.11",
"langgraph-runtime-inmem": "0.28.0",
"langgraph-sdk": "0.3.13",
"langsmith": "0.7.36",
"lark-oapi": "1.5.5"
}
}
@@ -1,6 +1,40 @@
# Conversation Summarization
DeerFlow includes automatic conversation summarization to handle long conversations that approach model token limits. When enabled, the system automatically condenses older messages while preserving recent context.
DeerFlow includes automatic conversation summarization to handle long conversations that approach model token limits. When enabled, the system automatically condenses older messages while preserving recent context.
## Hard input limit (always-on safety net)
Summarization is a quality feature and may be disabled by the user. A model can
also exceed its real window because the final request contains more than chat
history: the system prompt, tool schemas, hidden memory/RAG context, and
historical reasoning are all sent to the provider. For that reason DeerFlow
also supports a model-specific, always-on hard limit:
```yaml
models:
- name: qwen-local
use: langchain_openai:ChatOpenAI
model: Qwen3.8-27B
# This is the safe INPUT ceiling, not the model's advertised total window.
# For a 200k deployment, 160k leaves room for output and tokenizer variance.
max_input_tokens: 160000
max_tokens: 8192
```
`max_tokens` limits generated output. `max_input_tokens` limits the complete
input request and is consumed only by DeerFlow; it is never sent to the
OpenAI-compatible endpoint. The final model middleware conservatively counts
the system message, ordinary and hidden messages, tool schemas, response
format, tool calls/results, and historical reasoning. If the request is over
budget it transiently removes the oldest complete turns, drops expendable
hidden context, and truncates oversized tool/message bodies as a last resort.
The checkpoint and the conversation displayed in the UI are unchanged.
For LangChain-compatible configuration, the same limit may be expressed as
`profile.max_input_tokens`. A top-level `max_input_tokens` is preferred in this
project because it is visible alongside `max_tokens` in model configuration.
Do not set `max_tokens: 200000`: that asks the provider to generate up to 200k
tokens and does not protect the input context.
## Overview
@@ -19,7 +53,7 @@ The summarization feature uses DeerFlow's `DeerFlowSummarizationMiddleware` (a s
LangChain's stock `SummarizationMiddleware` runs in `before_model` and persists a `RemoveMessage(REMOVE_ALL_MESSAGES)` to the checkpoint — which permanently deletes the original Q&A from both the model context *and* the conversation the frontend renders. DeerFlow overrides this:
- `before_model` / `abefore_model` are **no-ops** (the destructive path is disabled).
- Compression runs in `wrap_model_call` / `awrap_model_call`: for a single model call, the message list is replaced with `[summary, *recent]` via `request.override(messages=...)`. **Nothing is written back to state.**
- Compression runs in `wrap_model_call` / `awrap_model_call`: for a single model call, the hidden summary is merged into LangChain's dedicated `ModelRequest.system_message` slot and the ordinary message list is replaced with the recent tail. This guarantees exactly one leading system message even for strict Qwen-style or generic `langchain_chat` adapters. **Nothing is written back to state.**
- The full original messages stay in the checkpoint, so the frontend keeps showing the user's real conversation. The summary message is named `summary` and flagged `hide_from_ui`, and because it only ever lives in the transient request it never reaches the frontend at all.
- The generated summary is cached **per-thread** so we don't pay an extra LLM call on every model invocation. The cached summary is reused (no LLM call) until enough *new* messages accumulate to push the compressed context back over the trigger threshold (a sticky boundary mirroring the stock middleware's post-compaction behavior). The cache is bounded (oldest threads evicted first).
- **Threshold-first**: while the full current conversation is still under the trigger, the request is passed through untouched — no cache lookup, no summary substitution. Compression only ever engages once the real context crosses the configured trigger.
@@ -185,7 +219,7 @@ The default LangChain prompt instructs the model to:
- Messages to summarize (older messages beyond the `keep` threshold)
- Messages to preserve (recent messages within the `keep` threshold)
4. **Summary Generation**: The model generates a concise summary of the older messages
5. **Context Replacement (transient)**: The message list **handed to the model for this call** is rebuilt as `[summary, *recent]`. The persisted state is left untouched — old messages are **not** removed, so the frontend still renders the full original conversation.
5. **Context Replacement (transient)**: The request **handed to the model for this call** is rebuilt with one system message (agent prompt + hidden summary) and the recent non-system tail. The persisted state is left untouched — old messages are **not** removed, so the frontend still renders the full original conversation.
6. **AI/Tool Pair Protection**: The system ensures AI messages and their corresponding tool messages stay together
7. **Skill Rescue**: Before the summary is generated, the most recently loaded skill files (tool results whose tool name is in `skill_file_read_tool_names` and whose target path is under `skills.container_path`) are lifted out of the summarization set and prepended to the preserved tail. Selection walks newest-first under three budgets: `preserve_recent_skill_count`, `preserve_recent_skill_tokens`, and `preserve_recent_skill_tokens_per_skill`. The triggering AIMessage and all of its paired ToolMessages move together so tool_call ↔ tool_result pairing stays intact.
@@ -202,12 +236,14 @@ The middleware intelligently preserves message context:
- **Recent Messages**: Always kept intact based on `keep` configuration
- **AI/Tool Pairs**: Never split - if a cutoff point falls within tool messages, the system adjusts to keep the entire AI + Tool message sequence together
- **Summary Format**: Summary is injected as a HumanMessage with the format:
```
Here is a summary of the conversation to date:
[Generated summary text]
```
- **Summary Format**: Summary is merged into the leading SystemMessage with the format:
```
Internal conversation summary for continuity only...
<internal_context_summary>
[generated summary text]
</internal_context_summary>
```
## Best Practices
@@ -329,7 +365,8 @@ Summarization runs after ThreadData and Sandbox initialization but before Title
- Configuration is loaded once at startup
- Summarization is **non-destructive**: the summary replaces older messages only in the transient model request (`wrap_model_call`), never in persisted state. The checkpointer therefore keeps the full original conversation
- The per-thread summary cache lives in a **process-wide, thread-safe LRU** (`_GLOBAL_SUMMARY_CACHE`, bounded), **not** on the middleware instance. `make_lead_agent` rebuilds a fresh middleware every run, so an instance cache would be cold each turn and re-run a blocking summary LLM call on every turn of a long conversation; the module-level cache keyed by `thread_id` lets a summary survive across turns. It is a cost optimization only — a cold/stale cache simply re-summarizes, which is always correct
- The per-thread summary cache lives in a **process-wide, thread-safe LRU** (`_GLOBAL_SUMMARY_CACHE`, bounded), **not** on the middleware instance. `make_lead_agent` rebuilds a fresh middleware every run, so an instance cache would be cold each turn and re-run a blocking summary LLM call on every turn of a long conversation; the module-level cache keyed by `thread_id` lets a summary survive across turns. It is a cost optimization only — a cold/stale cache simply re-summarizes, which is always correct.
- Compression normalizes LangChain's split request representation before invoking the next middleware/model: the dedicated `system_message` contains all system context exactly once, while `messages` contains no `SystemMessage`. This makes the fix independent of the configured provider adapter.
## Example Configurations