flowchart TB
    subgraph ingestion [文档入库流程]
        A[用户上传文档] --> B[MinIO 对象存储]
        B --> C[Redis / Asynq 异步队列]
        C --> D[解析 → 分片 → 嵌入]
        D --> E[pgvector 向量存储]
    end

    subgraph query [智能问答流程]
        F[用户提问] --> G[意图识别 + 问题改写]
        G --> H[混合检索 — 向量 + 关键词]
        H --> I[Rerank + 分数阈值过滤]
        I --> J[Prompt 组装]
        J --> K[LLM 流式生成]
        K --> L[SSE 返回]
        L --> M[引用快照 / 检索状态持久化]
    end

    E -.->|知识库上下文| H

    style ingestion fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style query fill:#e3f2fd,stroke:#1565c0,stroke-width:2px

上传入口： POST /api/v1/knowledge-bases/:id/files

异步处理（Worker）：

pending → processing → done / failed

Worker 并发从 Redis 拉取任务，执行：

1. 解析（Parser） — PlainParser 处理 .md/.txt，DocxParser 提取 .docx 的 XML 文本
2. 分片（Chunker） — 根据文档结构自动选择切分策略
3. 嵌入（Embedding） — 调用嵌入模型（如 text-embedding-v3）将每个 chunk 转为 1024 维向量
4. 入库（pgvector + PostgreSQL） — chunk 文本写入 PostgreSQL，向量写入 pgvector
5. 完成后 parse_status = "done"，失败则 "failed"

四种策略，由 chunkAuto 自动选择：

chunkAuto 决策顺序：
  有 # 标题 ?  ──→ heading 策略
  有 第X章 / 1. ? ──→ heuristic 策略
  以上都不满足 ──→ recursive 策略（兜底）

• 按 Markdown 标题层级（# ~ ######）拆分文档为节
• 构建面包屑路径作为上下文头（如 # 操作系统 > ## 进程与线程）
• 每节内部递归切分，所有 chunk 携带 ContextHeader 标签

• 在章节标记处切分（第X章、第X节、1.、1、）
• 适用于无 Markdown 标题、但有中文序号结构的纯文本文档

• splitToUnits：按分隔符优先级递归切分
  • \n\n → \n → 。 → ！ → ？ → ; → ；
• mergeUnits：以 512 字符为目标合并 unit，相邻 chunk 保留 80 字符重叠
• 分隔符穷尽后仍无法切分的超长段落，原样保留为单个 chunk

每次用户提问先经过 query.Understand() —— 单次 LLM 调用同时完成改写和意图分类。

6 种意图：

问题改写（Query Rewrite）：

• 载入最近 6 条对话历史
• 让 LLM 将指代词、省略信息补全为自包含的检索查询
• 例如 它和线程有什么区别 → 进程和线程有什么区别

检索控制流程：

用户提问
  → 载入历史（最近 20 条消息）
  → 意图识别 + 问题改写
  → NeedsRetrieval()?
      ├─ false → 跳过检索，纯 LLM 回答
      └─ true  → 进入混合检索

混合召回： 向量检索 + 关键词检索融合

两路分数归一化后加权求和，按融合分数降序排列。

重排序（Rerank）：

召回结果送入 Rerank 模型（如 qwen3-rerank）二次打分，更新每条结果的分数。

分数阈值过滤（filterRAGResults）：

① TopK 截断（默认 5）
     ↓
② ScoreThreshold 过滤（默认 0.45）
     │  └─ 有结果 → 返回
     └─ 无结果 → ③ 阈值降级重试
                    │  └─ 有结果 → 返回
                    └─ 无结果 → ④ FallbackMinScore 单条兜底
                                    │  └─ 满足 → 返回 Top 1
                                    └─ 不满足 → ⑤ 完全拒绝（不走 RAG）

相关环境变量：

Prompt 组装（按顺序拼接）：

系统指令
  +
知识库上下文（[Source N] chunk 正文，来自混合检索结果）
  +
用户长期记忆（来自 memory 表）
  +
对话历史（最近 20 条消息）
  +
当前问题

SSE 流式响应（POST /api/v1/sessions/:id/chat）：

结果溯源：

• Go 1.23+
• Node.js 20+
• Docker

cp .env.example .env    # 如有 .env.example
# 编辑 .env，至少填入 LLM / Embedding / Rerank 的 API Key

本地开发时创建 .env.local 覆盖 Docker 服务地址：

DB_HOST=localhost
REDIS_ADDR=localhost:6379
MINIO_ENDPOINT=localhost:9000

make dev-start

启动 PostgreSQL、Redis、MinIO（Docker 容器）。

make dev-app
# → http://localhost:8081

make dev-frontend
# → http://localhost:5173

docker compose up -d
# 前端 → http://localhost
# API  → http://localhost:8081