# LiteKnowledge

**Repository Path**: wuyuancunmin/lite-knowledge

## Basic Information

- **Project Name**: LiteKnowledge
- **Description**: 知识管理平台 — LiteKnowledge
将任意文本文档通过 LLM 转换为结构化知识图谱，支持可视化浏览、智能问答和评测用例生成。知识文档遵循 **OKF（Open Knowledge Format）** 开放格式规范。
理念：不是 RAG，是 LLM Wiki，轻量化，遵循OKF（Open Knowledge Format）规范实现知识标准，车同轨书同文，让知识管理行为标准一致
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识管理平台 — LiteKnowledge

将任意文本文档通过 LLM 转换为结构化知识图谱，支持可视化浏览、智能问答、全文搜索、文档合并和评测用例生成。知识文档遵循 **OKF（Open Knowledge Format）** 开放格式规范。

## 理念：不是 RAG，是 LLM Wiki

传统的 RAG（检索增强生成）模式是 **原文 → 切片 → 向量库 → 检索 → 拼接到 prompt**。问题在于：

- 切片丢失了文档结构和章节间的逻辑关系
- 知识是"碎片"形态，人无法直接阅读、校验和维护
- 每次问答都依赖原始文档的检索质量，不可复现

LiteKnowledge 换个思路：**让 LLM 先把文档"读懂"，写成结构化的 wiki，再基于 wiki 做问答**。

```
传统 RAG：  原始文档 ──→ 切片 ──→ 向量库 ──→ 检索拼凑 ──→ 回答
             （黑箱，碎片化，不可审计）

LiteKnowledge：  原始文档 ──→ [LLM 转换] ──→ OKF wiki ──→ 检索 ──→ 回答
                  （结构化，人可读，可版本管理，可可视化）
```

**本质上是 LLM Wiki 的落地实践**：LLM 充当"知识编辑"，把散落的文档整理成带元信息、带交叉引用、带目录索引的结构化知识库。人可以在任何环节介入——校对 wiki 内容、补充链接、修正错误——知识是透明且可控的。

**相比传统 RAG 的优势：**

| 维度 | 传统 RAG | LiteKnowledge |
|------|---------|---------------|
| 知识形态 | 文本碎片（chunks） | 结构化 wiki 文档 |
| 人类可读 | ❌ 切片不可直接阅读 | ✅ 标准 markdown，任意编辑器打开即读 |
| 可审计 | ❌ 检索结果不可复现 | ✅ wiki 是静态资产，回答附带引用来源 |
| 版本管理 | ❌ 向量库难以 diff | ✅ git diff / git log 追踪每一次知识变更，支持回滚 |
| 知识图谱 | ❌ 无关联 | ✅ 文档间交叉引用 → 力导向图可视化 |
| LLM 角色 | 检索拼凑者 | 知识编辑者（转换 + 关联发现）+ 检索回答者（问答）+ 评测者（自动评分） |
| 人的位置 | 被动使用 | 可随时介入、编辑、校对 |

## 项目组成

```
LiteKnowledge/
├── okf/                        # OKF 核心 Python 库
│   ├── __init__.py             #   公共 API
│   ├── document.py             #   解析 / 序列化 / 校验 OKF markdown
│   ├── paths.py                #   Concept ID ↔ 文件路径 工具
│   ├── indexer.py              #   自动生成目录 index.md（含章节级摘要展开）
│   ├── logger.py               #   变更日志维护 + 文件状态快照扫描
│   ├── merger.py               #   文档相似度检测（Combined Score）与智能合并
│   ├── generator.py            #   遍历 bundle → 生成自包含 viz.html
│   └── viewer/                 #   可视化前端资源
│       ├── templates/viz.html
│       └── static/
│           ├── viz.css
│           └── viz.js
├── server.py                   # Flask Web 服务（平台主入口，~4900 行）
├── eval_db.py                  # 评测 SQLite 数据库模块（~800 行，含 Badcase 表）
├── versioning.py               # Git 版本管理（自动提交 / 历史 / diff / 回滚）
├── demo.py                     # 独立演示：创建 bundle + 可视化
├── save_trace.py               # Claude Code 会话 trace 保存脚本
├── check_config.ps1            # 启动前配置检查脚本（API Key 缺失提醒）
├── config.json                 # 模型与提示词配置（API Key 留空，含多模型 + merge 场景绑定）
├── config.example.json         # 配置模板（含提示词示例）
├── .gitignore                  # Git 排除规则
├── requirements.txt            # Python 依赖清单（文件解析库为必装）
├── run.bat                     # Windows 一键启动脚本
├── templates/
│   ├── index.html              #   Web 控制台界面（~4300 行）
│   └── traces.html             #   Trace 浏览页面
├── bundles/workspace/          # 知识库工作区（自动 git 版本管理）
│   ├── 未分类/                 #   默认文档目录
│   ├── datasets/               #   （数据目录）
│   ├── documents/              #   （文档目录）
│   ├── playbooks/              #   （手册目录）
│   ├── references/             #   （参考目录）
│   ├── tables/                 #   （表目录）
│   └── viz.html                #   交互式知识图谱可视化
├── bundles/originals/          # 原始上传文件归档（与 workspace 镜像目录结构）
├── data/                       # 聊天记录 / 评测数据库持久化
│   ├── chat_history.json       #   对话历史
│   └── eval.db                 #   评测 SQLite 数据库
├── traces/                     # Claude Code 会话 trace 归档
├── SPEC.md                     # OKF v0.1 格式规范
├── LICENSE                     # Apache-2.0
└── README.md                   # 本文件
```

## 快速开始

### 环境要求

- **Python** ≥ 3.11
- **Git**（用于知识库版本管理，可选但推荐）
- 核心依赖：`pip install -r requirements.txt`（pyyaml / flask / waitress / pypdf / python-docx / openpyxl / python-pptx）
- `run.bat` 每次启动自动检查依赖并安装缺失包
- 一个或多个 LLM API Key（DeepSeek / GLM 等，用于文档转换和问答）

### 安装依赖

```bash
# 创建虚拟环境（推荐）
python -m venv .venv
.venv\Scripts\activate

# 一键安装
pip install -r requirements.txt
```

### 配置 API Key

仓库中的 `config.json` 已内置了 DeepSeek / GLM 等模型的默认配置，API Key 字段为空。直接编辑填入你的 Key 即可：

```bash
# 编辑 config.json，在对应模型的 "key" 字段填入 API Key
notepad config.json
```

也可以在 Web UI 的「模型配置」面板中在线配置，Key 会持久化保存。

> `config.json` 和 `config.example.json` 的区别：前者是实际配置文件（含空 Key），后者是纯模板参考。两个文件都会被 git 跟踪。

### 启动 Web 平台

```bash
# 方式一：双击运行
run.bat

# 方式二：命令行
.venv\Scripts\python server.py
```

启动后访问 **http://localhost:5051** 进入操作控制台。服务使用 waitress 生产级 WSGI 服务器运行。

## 核心功能

### 1. 文档转换（Convert）— 流式 SSE

将原始文档通过 LLM 转换为符合 OKF 规范的 markdown 知识文档。

- **多格式上传**：支持 PDF、DOCX、XLSX、PPTX、TXT、MD、HTML、CSV、JSON、XML、YAML、源代码（.py / .js / .ts / .sql 等）
- **拖拽或点击上传**，支持批量文件
- **智能目录推荐**：上传时 LLM 自动分析文档内容，推荐最合适的目标目录，低置信度时建议新建目录
- **流式 SSE 转换**：实时显示 LLM token 输出，每个文件的转换进度可见（通过 F12 Network 可查看结构化事件流）
- **逐文件 trace**：转换过程中显示步骤日志，失败文件不阻断后续处理
- 自动提取元信息（type、title、description、tags、timestamp）
- 生成结构化正文、交叉引用链接和章节级元信息
- 转换结果自动写入知识库并触发 git 提交
- **原始文件归档**：转换后的原始文件自动保存到 `bundles/originals/`，目录结构与 workspace 镜像
- **自动索引更新**：转换完成后自动刷新 index.md 和 log.md
- **自动重叠检测**：转换完成后自动触发内容重叠检测（`/api/convert/similar`），提示新文档与已有文档的相似度，引导合并

### 2. 知识库浏览（Knowledge Base）

以力导向图形式展示知识库中所有概念及其关联关系。

- **节点**：每个 OKF 文档（概念）+ 章节级节点（H1/H2/H3 层级树）
- **边**：文档间的交叉引用链接
- **交互**：点击节点查看渲染后的 markdown 正文
- **焦点模式**：点击侧边栏文件后切换到可视化，自动聚焦到该文件及其所有关联节点
- **显示全部**：一键恢复完整图谱视图
- **目录筛选**：可按目录过滤可视化范围
- 支持搜索、类型筛选、多种布局切换
- 显示 "Cited by" 反向引用

### 3. 智能问答（Chat）— 两步 RAG + 完整 Trace

基于知识库内容的 RAG 式问答，每次对话经过两步 LLM 调用，全过程可追溯。

**管道流程（全部通过 SSE 流式传输）：**

```
用户提问 → 构建知识库索引（FM-index，含 index.md 目录级概览）→ 检索模型选出相关条目（第1次 LLM 调用）
→ 加载文档全文 → 对话模型生成回答（第2次 LLM 调用）→ 返回答案
```

- 每个步骤都在 Trace 面板中实时显示状态、输入输出字符数、耗时
- 可展开查看每次 LLM 调用的完整输入/输出
- 自动去重、自动合并章节级和文档级检索结果
- LLM 基于检索结果生成结构化回答
- 回答末尾附带「📎 引用来源」
- **会话管理**：新建/切换/删除对话，对话历史和 trace 持久化到 `data/chat_history.json`
- **可拖动分隔条**：对话面板、Trace 面板宽度均可鼠标拖动调整

### 4. 全文搜索（Search）

跨知识库的全文检索，支持加权评分和多维筛选。

- **加权评分**：标题（0.95）> 描述（0.8）> 标签（0.7）> 文件名（0.6）> 正文（0.5）
- **多维筛选**：按目录（dir）、文档类型（type）、标签（tag）过滤
- **上下文片段**：搜索结果返回匹配位置周围的正文片段
- **分页支持**：可指定每页条数（1–100）和偏移量
- 搜索结果按评分降序排列

### 5. 目录管理（Directory Management）

知识库支持多级目录组织，提供完整的 CRUD 操作。

- **目录树浏览**：递归展示目录结构，含各目录文档数量和摘要信息
- **创建/重命名/删除**：创建目录自动生成 `index.md`，重命名和删除自动更新所有文档中的交叉引用
- **目录移动**：将目录移到其他父目录下，自动修正交叉引用路径，防止移入自身或子目录
- **文档移动**：单文件在目录间移动，同步更新关联链接
- **深度限制**：最大 6 层嵌套，防止目录结构过度复杂
- **原始文件同步**：所有目录操作同步反映到 `bundles/originals/` 镜像
- **索引自动刷新**：目录操作后自动刷新 index.md 和 log.md
- 默认 `未分类` 目录：旧版扁平文件和新文档默认存放位置

### 6. Git 版本管理（Versioning）

知识库的每一次变更都被 git 自动记录，实现完整的版本控制。

- **自动提交**：文档创建/编辑/删除、批量转换、目录管理、关联添加、章节摘要生成、回滚操作均自动生成 git commit
- **操作标签**：commit message 包含操作类型（create / update / delete / convert / link / enrich / rollback / rename-dir / move 等）
- **文件历史**：在编辑器中选择文件 → 点击「版本历史」，查看该文件的所有历史版本
- **Diff 对比**：选择两个版本对比差异（统一 diff 格式，带语法高亮）
- **一键回滚**：将文件恢复到任意历史版本，回滚操作自身也会被 git 记录
- `.gitignore` 自动维护：`viz.html`、`log.md`、`.okf_state.json`、`index.md` 等生成文件不纳入版本跟踪
- **Index & Log 自动维护**：启动时自动生成缺失的 index.md/log.md；每次文档变更后自动刷新索引和变更日志

### 7. LLM 智能关联发现（Link Discovery）

利用 LLM 自动发现文档间的隐含关联，并建立交叉引用。

- **单文件关联**：分析当前编辑的文档与其他文档的语义关联
- **全局关联**：分析所有文档之间的相互关联
- **失效链接清理**：发现过程中自动清理指向已删除文件的失效链接
- **已有链接跳过**：自动跳过源文档已存在的交叉引用，避免重复建议
- **逐条审查**：每条关联建议标注关联原因，可选择「接受」或「忽略」
- **一键全部接受**：批量应用所有发现的关联
- 接受后自动在源文档末尾追加 `# 关联` 段落，该操作纳入 git 版本记录

### 8. 章节摘要生成（Section Enrichment）

- 扫描知识库中所有无描述的章节标题
- 使用 LLM 为每个章节生成一句简短中文摘要（15 字以内）
- 摘要以 YAML 元信息块写入对应章节标题下方
- 操作纳入 git 版本记录

### 9. 文档相似度检测与智能合并（Merge）

将多篇相似或重复的文档合并为一篇综合文档，完整保留各文档的独特信息。

**相似度算法（Combined Score）：**

- **三重评分模型**：Jaccard（集合重叠） + Cosine（TF 向量余弦，抗文档大小差异） + Containment（小文档被大文档覆盖度）
- **Combined 综合分**：取三者最优值（max(jaccard, cosine×0.95, containment×0.9)），解决单一指标在不同文档大小偏差下的局限
- **中文分词升级**：CJK 文本使用重叠二元组（bigram）分词，相比单字分词显著提升语义区分度
- **段落切分优化**：按 `##`/`###` 标题边界切分，标题与正文保持为同一语义单元

**自动重叠检测（转换后自动触发）：**

- **零操作**：文档转换完成后，自动扫描新文档与知识库中所有已有文档的内容重叠
- **独立 API**：`/api/convert/similar` 纯文本算法检测，快速同步，不依赖 LLM
- **结果表格**：以表格展示重叠对（新文档 | 相似已有文档 | Jaccard/Cosine/Containment/Combined 相似度 | 操作）
- **逐段对比**：点击「对比」弹出左右对照视图，只展示有重叠的章节段落，标题与正文保持一体
- **差异导航**：重叠段落间支持「上一处 / 下一处」逐对跳转（也支持键盘 ←↑→↓）
- **复选框选择**：勾选要合并的文档对，不相关的取消勾选，一键「前往合并」
- **浮动提醒**：关闭弹窗后右下角显示待处理徽章，随时可重新打开
- 章节级 YAML 元信息自动过滤，对比视图只展示实质内容
- 完全相同的段落自动跳过不展示
- 检测阈值 Combined ≥ 0.15（偏灵敏，宁可多报不漏报）

**合并工作流：**

- **扫描分组**：选择范围 → 设定阈值 → 扫描出相似文档组（Combined + 内容哈希双重检测）
- **段落对比**：选择一组文档 → 逐段对照标注 Combined 相似度
- **LLM 智能合并分析**：AI 逐句对比差异，标记 5 种差异类型（整段独有/缺失/部分增删/数据不同/描述矛盾）
- **多文档支持**：支持 3 篇以上文档同时合并，冲突标记中为每个文档列出独立方案（A/B/C/D...）
- **人工确认**：逐处选择方案或手动编辑，支持回撤操作
- **执行合并**：生成合并文档，自动合并标签、记录来源路径（`merged_from`）
- 操作纳入 git 版本记录

### 10. 评测体系（Eval）— 全流程自动化

从案例集上传到多轮评测对比，完整覆盖评测链路。评测数据持久化到 SQLite 数据库（`data/eval.db`）。

**评测流程：**

```
上传案例集 → LLM 解析提取 QA 对 → 人工校对/编辑用例 → 选择评测文档范围
→ 批量执行评测（SSE 实时进度）→ LLM 逐题评分 → 根因分析 + 优化建议
→ 多轮对比分析 → 导出 Excel/JSON 报告
```

- **案例集上传**：支持 PDF/DOCX/XLSX/PPTX/TXT/MD/JSON 等格式，也支持直接粘贴文本
- **LLM 智能解析**：LLM 识别文档中的需求/背景类标题（作为 question）和方案/实施类标题（作为 answer），后端以正则完整提取标题下的原文内容，严格 1:1 对应
- **人工校对**：解析后可增删改每条 QA 对
- **文档范围选择**：可选择全部或部分知识库文档作为评测范围
- **批量评测**：SSE 流式进度，支持**暂停/恢复**，可随时停止
- **LLM Judge 评分**：从事实正确性、完整性、相关性三个维度评分（0-1 分），≥ 通过阈值（可配置）视为通过；LLM 不可用时自动降级为关键词匹配评分
- **根因分析**：LLM 分析未通过用例的共同根因
- **优化建议**：针对根因给出具体的知识库改进建议
- **多轮对比**：选择 2 个以上评测轮次并排对比，逐题展示得分变化（提升/下降/持平），可选 LLM 深度对比分析
- **Excel 导出**：支持三种粒度的导出
  - 测试集导出（含所有 QA 对）
  - 单轮结果导出（含条件着色：通过绿色/未通过红色、冻结表头）
  - 全部轮次导出（多 Sheet 工作簿：汇总表 + 每轮独立 Sheet）
- **JSON 导出**：所有 Excel 导出同时支持 JSON 格式
- **可视化图表**：评测报告包含 Chart.js 绘制得分分布图
- **向后兼容**：保留旧版 `eval_sessions.json` API 端点，自动迁移到 SQLite
- 评测数据持久化到 `data/eval.db`

### 11. Badcase 分析与知识回流（Badcase Analysis & Reflux）

评测完成后，对未通过的用例进行 LLM 智能归因分析，并支持将补充知识一键回流到知识库，形成「评测 → 发现缺口 → 补充知识 → 再评测」的闭环。

**Badcase 分析（归因 + 归类）：**

- **自动归因**：LLM 分析每个失败用例，判定为 `no_answer`（知识缺失，回答为空）或 `wrong_answer`（输出存在但错误/不完整）
- **代码级预判**：先由代码检测回答是否为空，LLM 在此基础上确认并给出详细理由（50-150 字）
- **回流建议**：为每个 badcase 建议最合适的已有文档路径（suggested_doc）、目录（suggested_dir）和补充文档标题（suggested_title）
- **Q&A Markdown 生成**：LLM 为每个 badcase 自动生成 OKF 格式的 Q&A 文档（含 frontmatter + 问题/期望答案/实际回答/归因分析四个章节）
- **LLM 降级**：LLM 分析不可用时自动降级为代码级预判

**知识回流（Badcase → 知识库）：**

- **选择转换**：在多选表格中勾选要回流的 badcase → 一键「回流到知识库」
- **路径策略**：
  - 指定已有文档 → 生成 `{原文档}_badcase补充_{时间戳}.md` 配套文件
  - 指定目录 → 写入建议目录
  - 未指定 → 写入 `未分类/Badcase回流/`
- **用户覆盖**：支持手动修改回流目标路径（user_doc_path），以用户指定为准
- **自动去重**：文件名冲突时自动追加时间戳
- **状态追踪**：每个 badcase 标记 pending / converted 状态，全部转换后分析自动标记为完成
- **Git 记录**：回流操作自动生成 `badcase-reflux` 类型 commit

### 12. 模型与提示词配置（Settings）

通过 Web UI 管理所有模型和提示词配置，全部持久化到 `config.json`。

- **多模型管理**：支持添加/删除/编辑多个 LLM 模型（名称、endpoint、API Key、model、max_tokens、temperature）
- **六场景独立绑定**：每个功能场景独立选择使用哪个模型
  - 转换（convert）
  - 对话（chat）
  - 检索（retrieve）
  - 评测集解析（eval_parse）
  - 用例评测（case_eval）
  - 文档合并（merge）
  - Badcase 分析（case_eval 模型复用）
- **四套提示词独立编辑**：
  - 转换提示词（Convert Prompt）
  - Agent 提示词（Chat Prompt，含 `{kb_context}` 占位符）
  - 评测解析提示词（Eval Prompt，含 `{text}` 占位符）
  - 合并提示词（Merge Prompt，留空则使用内置提示词）
- **API Key 安全处理**：前端仅显示脱敏预览（前 5 字符 + 星号），不回传真实 Key，后端自动识别掩码保持原值
- **旧版配置自动升级**：单模型结构的旧配置自动迁移为多模型格式

### 13. 知识库导入/导出

- **加载示例**：一键加载 demo 文档，快速体验完整功能
- **导出全部 ZIP**：将整个知识库工作区（或指定目录）打包为 `.zip` 文件下载
- **选择性导出**：勾选指定目录或文档，可选是否包含原始文件（originals），可选扁平化目录结构
- **清空知识库**：通过 API 一键清空（保留 .git 目录）

### 14. Trace 浏览（/traces）

独立的 Trace 浏览页面（`http://localhost:5051/traces`），用于回溯 Claude Code 对话记录。

- **自动归档**：`save_trace.py` 配置为 Claude Code Stop hook 后，每次对话结束自动保存 transcript
- **双源合并**：同时展示当前项目 traces 和历史项目归档的 trace
- **对话格式化**：将 JSONL transcript 解析为可读的对话格式（区分 user / assistant / tool 角色）
- 支持查看和删除

### 15. 原始文件管理（Originals）

文档转换后，原始上传文件自动归档到 `bundles/originals/`，目录结构与 workspace 镜像同步。

- **按目录浏览**：可按 workspace 目录结构浏览原始文件列表
- **下载原始文件**：支持直接下载原始上传文件
- **同步维护**：目录创建/重命名/删除/移动、文档删除等操作自动同步到 originals
- **路径安全**：完整的路径遍历防护

## OKF 格式简介

OKF（Open Knowledge Format）是一种开放、人机友好的知识表示格式。核心约定：

- **Bundle**：一个目录树，包含若干 `.md` 文件
- **Concept**：一个 markdown 文件 = 一个知识单元
- **Frontmatter**：YAML 元信息块（`type` 必填，`title`/`description`/`tags`/`resource`/`timestamp` 推荐）
- **Body**：结构化 markdown 正文（支持标题、表格、代码块、交叉引用）
- **Section metadata**：每个 `##`/`###` 标题下方可附带章节级 YAML 元信息（description、tags、resource）
- **index.md**：目录清单，支持渐进式浏览
- **log.md**：更新历史

详细规范见 [SPEC.md](SPEC.md)。

## OKF Python API

```python
from okf import OKFDocument, generate_visualization

# 创建 OKF 文档
doc = OKFDocument(
    frontmatter={
        "type": "BigQuery Table",
        "title": "Orders",
        "description": "One row per completed customer order.",
        "tags": ["sales", "orders"],
        "timestamp": "2026-06-17T10:00:00Z",
    },
    body="# Schema\n\n| Column | Type | Description |\n|---|---|---|",
)
doc.validate()                              # 校验（type 缺失则抛异常）
doc.save("bundle/tables/orders.md")         # 写入文件

# 解析已有文档
text = open("some_file.md").read()
doc = OKFDocument.parse(text)
print(doc.frontmatter)                      # dict
print(doc.body)                             # markdown 正文

# 生成可视化（含文件级和章节级节点）
result = generate_visualization(
    bundle_root="./my_bundle",
    out_path="./my_bundle/viz.html",
    bundle_name="My Knowledge Base",
)
print(result)  # {'concepts': 12, 'edges': 8, 'bytes': 45200}
```

## 配置说明

`config.json` 结构（仓库中已含此文件，Key 字段留空）：

```json
{
  "models": [
    {
      "name": "deepseek-v4-pro",
      "endpoint": "https://api.deepseek.com/chat/completions",
      "key": "",
      "model": "deepseek-v4-pro",
      "max_tokens": 393216,
      "temperature": 0.7
    }
  ],
  "active": {
    "convert": "deepseek-v4-pro",
    "chat": "deepseek-v4-pro",
    "retrieve": "deepseek-v4-pro",
    "eval_parse": "deepseek-v4-pro",
    "case_eval": "deepseek-v4-pro",
    "merge": "deepseek-v4-pro"
  },
  "convert_prompt": "你是一个文档转换助手...",
  "chat_prompt": "你是一个知识管理助手...\n\n{kb_context}",
  "eval_prompt": "你是一个评测用例生成专家...\n\n{text}",
  "merge_prompt": ""
}
```

- `models`：支持配置多个模型（名称、endpoint、API Key、model 标识、max_tokens、temperature）
- `active`：六个功能场景各自独立绑定模型（转换/对话/检索/评测解析/用例评测/文档合并）
- `convert_prompt`：文档转换的系统提示词
- `chat_prompt`：对话 Agent 的系统提示词，`{kb_context}` 在运行时被替换为检索到的知识库内容
- `eval_prompt`：评测用例解析与 Badcase 分析的系统提示词，`{text}` 在运行时被替换为上传的案例集文本
- `merge_prompt`：文档合并的系统提示词（留空则使用内置提示词）
- 旧版配置（单模型结构）会被自动升级为多模型格式

## Git 版本管理详解

平台内置轻量级 git 版本管理，无需额外配置。只要系统安装了 git，所有知识库操作都会自动提交。

**自动提交的操作：**
- 文档转换（convert）
- 文档创建/编辑/删除（create / update / delete）
- 关联发现应用（link）
- 章节摘要生成（enrich）
- 版本回滚（rollback）
- 知识库清空（clear）
- 加载示例（load-demo）
- 目录管理（create-dir / rename-dir / delete-dir / move-dir）
- 文档移动（move）
- 旧版文件迁移（migrate）
- Badcase 回流（badcase-reflux）

**Web UI 功能：**
- 编辑器中点击「版本历史」→ 查看文件的历史版本列表
- 选择版本 → 查看该版本的文件内容
- 选择两个版本 → 查看 diff（统一格式，增删行着色）
- 回滚到指定版本 → 文件恢复到历史状态

## LLM 调用基础设施

所有 LLM 调用均内置以下能力：

- **指数退避重试**：HTTP 错误、连接错误、超时错误最多重试 3 次
- **流式 SSE 解析**：兼容 `data: ` 前缀和裸 JSON 行两种格式
- **Endpoint 自动补齐**：未包含完整路径时自动追加 `/v1/chat/completions`
- **超时设置**：所有 LLM 调用统一 300 秒超时
- **消息数组支持**：对话场景支持传入完整 messages 数组

## Trace 保存

`save_trace.py` 用于保存 Claude Code 对话记录。配置为 Claude Code 的 Stop hook 后，每次对话结束自动将 transcript 归档到 `traces/` 目录，并附带会话摘要文件（`.info.txt`）。

可通过 Web 界面的 `/traces` 路径浏览和查看所有已保存的对话记录。

## 许可

Apache-2.0