Metadata-Version: 2.4
Name: rag-assistant-ldxs
Version: 1.7.0b1
Summary: rag-assistant — AI Agent
Home-page: https://github.com/Ldxs001/workbuddy-skills
Author: Ldxs (wUwproject)
Author-email: wuwofc@yeah.net
Classifier: Development Status :: 4 - Beta
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 驱动的组合式语义检索与多库路由。
> 作者：wUwproject | 许可证：Apache 2.0

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

---

## 核心特性

| 特性 | 说明 |
|------|------|
| **组合式查询** | LLM 自动对问题做实体/属性分词（entities + attrs），穷举组合后独立检索，SM3 去重合并，LLM 综合回答 |
| **多库路由** | 硬编码关键词 + 语义回退（FallbackRouter）双路由，自动匹配最相关的知识库 |
| **自修正决策** | LLM 输出格式错误时自动反馈重试（最多 5 次），重试耗尽时清上下文重来 |
| **配置持久化** | timeout / max_tokens / backend / model 全部保存到 config.json，刷新页面不丢 |
| **联网搜索** | 可选启用，扩展知识库覆盖范围 |

---

## 文件结构

```
agent/rag-assistant/
├── main.py                           # 入口，CLI + Web 双模式
├── rag_assistant/
│   ├── agent.py                      # Agent 决策循环
│   ├── web_ui.py                     # Web 界面（port 8765）
│   ├── llm_client.py                 # LLM 统一客户端
│   ├── rag_wrapper.py                # 技能封装层
│   ├── search.py                     # 联网搜索
│   └── memory.py                     # 记忆管理
├── scripts/                          # 技能核心模块
├── vendor/                           # 内嵌第三方库
└── data/                             # 运行时数据
    ├── config/rag_config.json        # LLM 与检索配置
    ├── models/                       # 嵌入/路由/rerank 模型
    ├── kb/                           # 知识库（Chroma 向量库）
    └── ...
```

---

## 快速开始

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

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

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

## 架构概览

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

## 依赖

- LM Studio 或 Ollama（本地 LLM 推理服务）
- Python 3.9+
- 嵌入模型（推荐 BAAI/bge-small-zh-v1.5）
- ChromaDB（向量存储，自动安装）

## 协议

Apache 2.0


---

## 更新说明

## [1.7.0b1] - 2026-07-20
### 重大变更
- **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 引用
