Metadata-Version: 2.4
Name: rag-assistant-ldxs
Version: 1.7.0
Summary: rag-assistant — AI Agent
Home-page: https://github.com/Ldxs001/workbuddy-skills
Author: Ldxs (wUwproject)
Author-email: wuwofc@yeah.net
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain>=0.1
Requires-Dist: langchain-community>=0.3
Requires-Dist: langchain-huggingface>=0.1
Requires-Dist: langchain-chroma>=0.1
Requires-Dist: langchain-text-splitters>=0.3
Requires-Dist: chromadb>=0.5
Requires-Dist: sentence-transformers>=3.0
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: modelscope>=1.15
Requires-Dist: openai>=1.0
Requires-Dist: torch>=2.0
Requires-Dist: transformers>=4.30
Requires-Dist: numpy>=1.24
Requires-Dist: easyocr>=1.7
Requires-Dist: requests>=2.28
Requires-Dist: duckduckgo_search>=4.0
Requires-Dist: jieba>=0.42
Requires-Dist: sentencepiece>=0.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# RAG Assistant

> 本地知识库问答智能体 — LLM 驱动的组合式语义检索与多库路由。
> 版本：1.7.0 | 作者：wUwproject | 许可证：Apache 2.0

基于 local-rag-builder 技能构建的独立 RAG 智能体，支持 LM Studio / Ollama 双后端。

---

## 快速开始

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动（需要 LM Studio 或 Ollama 运行中）
python main.py

# 3. 打开浏览器访问 http://localhost:8765

# 同时启动外部 API（可选）
python main.py --api-port 8767
```

---

## 核心特性

| 特性 | 说明 |
|------|------|
| **组合式查询** | LLM 自动做 entities/attrs 分词，穷举组合后独立检索，SM3 去重合并，LLM 综合回答 |
| **多库路由** | 硬编码关键词 + 嵌入模型×KB签名语义回退两级路由 |
| **三层推理流水线** | 检索 → Reranker 精排 → NLI 三向分类（entailment/neutral/contradiction） |
| **自修正决策** | LLM 格式错误时自动反馈重试（最多 5 次），重试耗尽时清上下文重来 |
| **功能运行态切换** | 路由/重排序/NLI/搜索开关无需改配置重启 |
| **联网搜索** | 5 种后端：DuckDuckGo/Tavily/Google/Bing/自定义 |

---

## 文件结构

```
rag-assistant/
├── main.py                           # 入口（CLI/Web/Batch/External API 四模式）
├── setup.bat                         # Windows 一键启动
├── requirements.txt                  # 依赖清单
├── CHANGELOG.md                      # 版本更新日志
│
├── rag_assistant/                    # 智能体核心
│   ├── agent.py                      # LLM 决策循环
│   ├── web_ui.py                     # Web 界面（port 8765）
│   ├── external_api.py               # 外部接入 API（port 8767）← 新增
│   ├── llm_client.py                 # LLM 统一客户端（LM Studio / Ollama）
│   ├── rag_wrapper.py                # 技能封装层
│   ├── search.py                     # 联网搜索（5 种后端）
│   ├── memory.py                     # 三层记忆系统
│   └── _fix_rag.py                   # 破损数据修复工具
│
├── engine/                           # 技能引擎（独立副本）
│   ├── rag_core.py                   # 检索/路由/rerank/NLI 编排
│   ├── router.py                     # 两级路由 + KB 签名生成
│   ├── reranker.py                   # 重排序（model/rule/hybrid）
│   ├── nli_classifier.py             # NLI 三向分类器
│   ├── knowledge_base_manager.py     # KB CRUD + 备份/恢复/移动
│   ├── text_splitter.py              # 5 种切分策略 + 5 种守卫
│   ├── prompt_manager.py             # 提示词管理（模板/插槽/预设）
│   └── ...
│
├── vendor/                           # 内嵌第三方库（bs4/pypdf/markdownify）
└── data/                             # 运行时数据
    ├── config/rag_config.json        # 全量配置
    ├── kb/                           # ChromaDB 知识库
    ├── models/                       # 嵌入/reranker/NLI 模型
    ├── sessions/                     # 会话历史
    ├── memory/                       # 压缩摘要/知识缺口/习惯
    └── prompts/                      # 自定义模板/预设
```

---

## 启动模式

```bash
python main.py                              # Web UI（port 8765）
python main.py --api-port 8767              # Web UI + 外部 API
python main.py --no-web --api-port 8767     # 仅外部 API
python main.py --no-web                     # CLI 交互模式
python main.py --batch --input q.json --output r.json   # 批量处理
cat queries.jsonl | python main.py --jsonl              # 管道模式
python main.py migrate                      # 从 local-rag-builder 迁移
```

---

## 架构概览

```
用户输入
  → [LLM 决策层]
       ├─ 闲聊 → 直接回答
       └─ 知识库查询 → entities/attrs 分词
           → [组合展开器] 穷举 entities × attrs
           → [多切片检索] 每片独立走完整 RAG 流程
              1. 路由（嵌入模型 × KB签名/关键词）
              2. 检索（Chroma 相似度）
              3. (可选) 重排序（reranker）
              4. (可选) NLI 三向分类（entailment/neutral/contradiction）
           → [SM3 去重合并]（保留 NLI 标签）
           → [LLM 综合回答]（带 NLI 标签辅助判断）
```

---

## 文档导航

| 文档 | 用途 |
|------|------|
| `PROTOCOL.md` | Web UI API 契约（port 8765）— 聊天/配置/文件交互 |
| `EXTERNAL_API.md` | 外部接入 API 契约（port 8767）— 功能开关/模型调用/KB管理/提示词/切分 |
| `rag_assistant/engine/rag-assistant-architecture.md` | 内部架构设计文档 |
| `CHANGELOG.md` | 完整版本更新日志 |
| `llms.txt` | AI 可读项目描述（llmstxt.org 规范） |

---

## 三端口架构

| 端口 | 模块 | 定位 | 文档 |
|------|------|------|------|
| 8765 | `web_ui.py` | 人机交互（聊天+配置面板） | `PROTOCOL.md` |
| 8766 | `rag_web_ui.py`（subprocess） | KB/模型配置 GUI | 架构文档 |
| 8767 | `external_api.py` | 系统间集成（组件级调用） | `EXTERNAL_API.md` |

---

## 技术栈

- **LLM 后端**：LM Studio（OpenAI 兼容） / Ollama
- **向量存储**：ChromaDB（langchain-chroma）
- **嵌入模型**：BCE-embedding-base_v1（本地加载）
- **Reranker**：BAAI/bge-reranker-base（本地加载）
- **NLI 分类**：MoritzLaurer/mDeBERTa-v3-base-mnli-xnli（本地加载）
- **文本切分**：5 种策略 + GuardStack 守卫栈
- **哈希去重**：SM3 国密哈希

## 依赖

- LM Studio 或 Ollama（本地 LLM 推理服务）
- Python 3.9+
- 嵌入模型（推荐 maidalun1020/bce-embedding-base_v1）
- ChromaDB（向量存储，自动安装）

## 协议

Apache 2.0


---

## 更新说明

## [1.7.0] - 2026-07-21
### 新增
- **外部接入 API（port 8767）**：`rag_assistant/external_api.py` 独立服务，6 个能力域 27 个 REST 端点，与 Web UI 完全隔离
- **功能开关运行态切换**：`POST /api/feature/toggle` + `GET /api/feature/status`，运行态切换 router/reranker/nli/web_search/auto_classify/geek_mode，持久化到 config.json，免重启
- **模型直接调用**：`POST /api/model/embed` 嵌入、`/api/model/rerank` 重排序、`/api/model/nli` 三向分类，绕过完整 RAG 流程独立调模型
- **KB 管理 API**：`POST /api/kb/create` / `/delete` / `/move` + `GET /api/kb/list` / `/sources` / `/backups` + `POST /api/kb/backup` / `/restore`
- **KB 签名管理**：`GET /api/kb/signatures` + `POST /api/kb/signature/build` + `POST /api/kb/signature/rebuild-all`
- **提示词管理 API**：模板读写/重置（`/api/prompt/template`）、插槽读写（`/api/prompt/slots`）、预设 CRUD+应用（`/api/prompt/presets` / `preset` / `preset/delete` / `preset/apply`）、系统前缀（`/api/prompt/system-prefix`）
- **输入管理 API**：文本切分（`POST /api/input/split`，透传 5 种切分策略 + 5 种守卫）、问题组合切片展开（`POST /api/input/query-slices`，entities×attrs 穷举）、策略列表（`GET /api/input/strategies`）
- **CLI 参数**：`--api-port` 指定端口启动外部 API（默认不启动，兼容旧用法）

### 修复
- **`llms.txt` 全面过时**：版本从 v0.1.0→v1.7.0，修复自修正重试次数（2→5）、压缩阈值（40行→token-based）、API端点数（13→30+）、路由模型角色混淆、文件名引用错误等全部过时信息
- **`PROTOCOL.md` 版本滞后**：v0.1→v1.0，补充外部 API 交叉引用
- **`rag-assistant-architecture.md` 多处过时**：版本 v0.9.0→v1.7.0b1→v1.7.0，修复 `RAG_PROTOCOL.md`→`PROTOCOL.md` 文件名错误、端点列表从 16 个补全到 32 个、新增 5.2b 外部 API 节、压缩阈值描述修正（行数→token比例）、搜索引擎列表从 2 种补全到 5 种

### 变更
- 版本从 `1.7.0b1` 升级为 `1.7.0`（正式版，去掉 beta 标记）
- README.md 全面更新：文件结构对齐当前架构、新增外部 API 说明、新增协议文档导航
- `main.py` +`--api-port` 参数，daemon 线程启动外部 API
### 重大变更
- **KB 签名生成机制重构**：四分法采样后 4 象限各算独立质心 → 各取近 20 个 chunk → 各象限独立 jieba + 停用词 + BCE 排序 → 四段拼接（每象限前 20 直接拼），签名上限 12→80 词。`router.py` `build_kb_signature()` 重写
- **多向量路由**：`kb_signatures.json` 新增 `signatures` 字段存储各象限签名，`route_query()` 区分多向量（逐个 cosine 取最高分）与单向量（fallback），数据驱动不再硬编码
- **反哺策略改为四象限均分**：`(30 - count(originals)) // 4` 每象限配额，取代全局 top-30 竞争，`router.py:343-377`

### 新增
- **签名重建控制**：`config.py` 新增 `signature_auto_rebuild: False` 配置项，`knowledge_base_manager.py:658-667` 入库时根据开关决定全量/增量更新
- **Web UI 签名管理**：KB 签名区新增"入库全量重建"开关 toggle，KB 列表每行新增"重建签名"按钮，JS 添加 `rebuildOneSig()` + `toggleAutoRebuild()` API
- **单 KB 重建 API**：`rag_web_ui.py` 新增 `POST /api/router/rebuild-one` 和 `POST /api/router/toggle-auto-rebuild`
- **查询类型参考修复**：`web_ui.py` 补上 `setTimeout(loadQueryTypes, 500)` 页面初始化调用，4 个内置类型正常显示
- **停用词扩展**：`router.py:167` 新增 `接上、转下页、上一页、下一页、上页、下页、翻页、第几页` 8 个 PDF 分页残留词

### 修复
- **`_originals` 持久化缺陷**：`_save_rules()` 入口自动补齐 `_originals`（`knowledge_base_manager.py:72-77`），不再依赖反哺阶段的条件保存
- **`rag_core.py` 死代码**：删除第 505-513 行引用不存在的 `update_kb_signature` 的多余代码
- **`update_kb_signature` 缺失导入**：`rag_web_ui.py:23` 补上 `build_kb_signature` 导入
- **签名预览截断**：Web UI 签名行显示从 `[:80]` → `[:120]`，鼠标悬停看全文
- **签名重建无反馈**：按钮重建过程禁用 + loading 态，完成后立即执行 `location.reload()`
- **查询切片缺失 entity 单独层**：`agent.py` 补上 `_slices.add(e)`，对齐三层策略
- **多实体 rel 切片缺失宽匹配**：`agent.py` 多实体时同时生成 `e1 e2 rel` 和 `e1 e2 attr rel` 两种
- **空 evidence 值绕过校验**：`agent.py:510` 增加 `not v.strip()` 检查，空值不再因 Python 的 `"" in src` 特性放行
- **LLM entities 拆碎修饰域**：system prompt 第 184 行加"不要将修饰域拆为独立 entity"，第 185 行 attrs 允许复合短语，第 190 行加"凝缩而非泛化"规则

### 变更
- 路由截断 `[:200]` → `[:512]`（适配长签名）
- 清理死常量 `SIGNATURE_MAX_WORDS = 12`
- 保留 `idf: dict = None` 参数兼容（TF-IDF 恢复待后续）

---
### 重大变更
- **多会话管理**：替换"重置对话"为"新建会话"，侧边栏列出所有历史会话，支持切换/归档/恢复。`agent.py` 新增 `new_session()`、`list_sessions()`、`archive_session()`、`delete_session()`、`_generate_session_id()`
- **压缩阈值改为 token 比例**：删除硬编码 100 行阈值，改为 `max_tokens × compress_ratio`（默认 4096×0.7=2867 token）。`memory.py` 新增 `estimate_token_count()`，可配置压缩触发比例和移出比例

### 新增
- **聊天侧边栏**：左栏 260px 宽，列出所有会话（含最近消息预览）。每个会话右侧 📦 归档按钮，归档会话灰显，点击 `↩` 可恢复。底部显示归档数量展开按钮
- **会话归档系统**：归档将会话文件移入 `data/archives/sessions/`，压缩记忆移入 `data/archives/memory/`，不删除数据。`max_sessions` 配置（默认 20）控制非活跃会话上限，超出自动归档最旧的
- **配置折叠**：配置 tab 的 LLM/记忆/搜索卡片可点击 `▾` 折叠，状态存入 localStorage
- **`memory.compress_ratio`/`compress_remove_ratio`/`max_sessions` 配置**：在 8765 配置行中与 LLM 设置同排显示，支持实时修改
- **KaTeX 字体文件**：复制 60 个字体文件到 `static/fonts/` + NOTICE.md 许可证声明
- **PCR/CT值 路由到生物医疗**：`auto_classify_rules.json` 中生物医疗 `_originals` 新增 PCR、聚合酶链式反应、CT值、核酸、基因检测等 10 个关键词

### 修复
- **Tab 切换 8766 泄漏**：消除 `.tab-content.active { display: block }` 与 `#chat-content.active { display: flex }` 的 CSS 冲突，改 JS 直接设置 `style.display`（block/none/flex），不再依赖 CSS class 控制显隐。CSS 中 `#config-content.tab-content { display: block }` 只作默认值，JS inline style 优先级更高，切换时绝对覆盖
- **`web_ui.py` 重建**：因 git checkout 误操作丢弃未提交改动，据 CHANGELOG + agent.py/memory.py API 重构 web_ui.py。侧边栏/会话管理/配置折叠/压缩比例全部恢复
- **双滚动条**：chat-messages 与 chat-content 高度溢出导致 body 额外滚动，`#chat-panel` 加 `overflow: hidden` + flex 子项最小高度 0 修复
- **`kb-status` / `llm-config` Null 报错**：删除 status-bar 后残留 JS 引用加 null 守卫
- **Enter 键未绑定**：从 `addEventListener`（注册时机问题）改为 textarea `onkeydown` 内联属性
- **setup.bat 杀不掉旧进程**：`netstat|find|tokens=5` 因 Windows 版本列偏移失效。改为 PowerShell `Get-CimInstance Win32_Process` 按命令行查杀 + `Get-NetTCPConnection` 按端口兜底
- **MiniCPM 语义判断方向错误**：原为 value 在 sources 中搜索，改为 key vs value 语义一致性判断

### 变更
- `agent.py` 所有 Memory 方法从固定 `"default"` session_id 改为动态生成
- 配置 tab 从原水平带状改为两张独立卡片（LLM + 记忆），统一 grid 布局 + border-radius:10px
- 删除 `status-bar`（kb-status、llm-config、压缩/清除/重置按钮）
- `memory.py` 删除 `COMPRESS_THRESHOLD`、`COMPRESS_REMOVE` 硬编码，新增 `COMPRESS_REMOVE_RATIO`
- `pop_oldest_lines()` 参数从 `n=int` 改为 `ratio=float`

### 移除
- 重置对话按钮、清除上下文按钮（由新建会话 + 归档替代）
- `status-bar` 相关元素及 JS 引用
