XiaoYu（小雨）— 伴随成长的个人工作知识库 Agent

把"每天一个工作文件夹"变成持续生长的个人知识库：本地索引 → 向量检索 → LLM 问答，回答建立在"认识你"的前提上。

XiaoYu 是一个本地优先的个人 RAG Agent。它扫描你的工作区（个人/、小组/、文档/ 等数据源），解析 Excel / Markdown / 纯文本 / Word / PDF 文件，切块后向量化存入本地 SQLite，之后你可以通过 CLI 提问，由 LLM 结合个人画像与检索到的资料生成带引用的回答。

核心链路全部手写（不用 LangChain 等重框架），通用 OpenAI 兼容 API（chat 与 embedding 可来自不同服务商），除调用 API 外数据不出本机。

功能特性

• 全格式解析：Excel（xlsx/xls，行分组合块）、Markdown（按二级标题）、纯文本 / OCR 日报、Word（段落+表格）、PDF（文本层）
• 增量索引：内容哈希判重，已入库文件秒级跳过，只处理新增/变更文件；删除的文件自动清理
• 向量检索：numpy 余弦 top-k + 来源多样性（每文件上限）+ 日期范围过滤（SQL 层）
• 查询理解：自动解析"上周 / 本月"等时间词为日期范围
• 带引用回答：上下文预算保护、结构化引用列表（不依赖 LLM 输出格式）
• 记忆层：profile.md 个人画像（角色/目标/薄弱项）注入 system prompt，回答结合个人情况组织
• 安全三道防线：解析时凭据脱敏 → 敏感文件整文件跳过 → 输出后置扫描
• 换模型防护：库记录 embedding 模型名，更换模型时阻止误用旧向量
• 断点续传：chunk 先写占位行，向量化失败标记 failed，重跑只补失败部分

架构

kb/                         （包名，映射到项目根目录）
├── config.py               配置加载（config.toml + 环境变量 + 校验）
├── models.py               数据模型（Document / Chunk / FileRecord）
├── utils.py                日期提取、SHA256、凭据脱敏、时间词解析、日志
├── llm.py                  OpenAI 兼容 chat/embed 封装（重试/退避/错误分类）
├── QA/                     入库链路：扫描 → 解析 → 切块 → 向量化 → 存储
│   ├── scanner.py          目录递归、增量判重、已删除检测
│   ├── parsers/            excel / markdown / text / docx / pdf 解析器注册表
│   ├── chunker.py          结构化切块 + 滑动窗口回退（带重叠）
│   ├── embedder.py         批量向量化、L2 归一化、断点续传
│   └── store.py            SQLite 存储（WAL、哈希判重、查询过滤、meta 表）
├── Transformer/            问答链路：检索 → 生成 → CLI
│   ├── retriever.py        时间词解析、余弦 top-k、来源多样性
│   ├── generator.py        Prompt 组装、上下文预算、引用、输出脱敏
│   └── cli.py              kb 命令行（click）
├── Menmory/                profile.md 个人画像加载与注入
├── profile.md              个人画像（角色/目标/薄弱项/风格）
├── config.toml             用户可调参数
└── data/kb.sqlite3         向量库（运行时生成）

安装

要求 Python ≥ 3.10。

# 1. 克隆项目后创建虚拟环境并安装
python3 -m venv .venv
.venv/bin/pip install -e .

# 2. 配置 API 密钥
cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY / OPENAI_BASE_URL，以及模型名

.env 关键配置：

OPENAI_BASE_URL=https://api.siliconflow.cn/v1
OPENAI_API_KEY=sk-xxxx
KB_CHAT_MODEL=deepseek-ai/DeepSeek-V3
KB_EMBED_MODEL=BAAI/bge-m3

环境变量以 KB_ 前缀开头，优先级高于 config.toml。Embedding 可单独指定 KB_EMBED_BASE_URL 走不同服务商。

数据源目录

在项目根目录创建数据源目录（可配置，见 config.toml 的 [data].sources），把日常工作文件放进去即可：

项目根/
├── 个人/2026-7-15/日报.md          # 目录名带日期会被提取为文件日期
├── 小组/周报2026-07-20/周报.txt
├── 文档/清单2026-07-21/对账清单.xlsx
└── VDMS在线办公平台/...

支持的文件类型：md、txt、xlsx、xls、docx、pdf（默认超过 50MB 跳过）。

使用

# 查看生效配置（隐藏 key 中间段）
kb config

# 扫描统计（--dry-run 仅统计不入库；--source 只扫指定源）
kb scan --dry-run

# 全链路建库：扫描 → 解析 → 切块 → 向量化 → 入库（--source / --force）
kb index

# 库统计：文件数 / 块数 / 按类型与状态分布
kb stats

# 问答（交互循环；也可直接带问题一次问答）
kb ask
kb ask 上周拼房场景的对账问题是什么

# 清理已删除文件的残留记录
kb prune

# 清空向量库（重建用；--yes 跳过确认）
kb reset --yes

kb ask 交互命令：

你：本月测试用例覆盖情况
  /help   帮助
  /quit   退出（Ctrl+D 亦可）

配置项（config.toml）

段	关键项	默认	说明
[data]	sources	个人/小组/文档/VDMS在线办公平台	数据源目录名
	exclude_dirs / exclude_exts	见文件	黑名单目录 / 扩展名
[chunk]	size / overlap_ratio	600 / 0.1	切块窗口与重叠比
[retrieval]	top_k / max_per_file	5 / 2	检索条数与来源多样性
	max_context_chars	6000	生成上下文预算
	enable_bm25	false	BM25 混合检索（预留）
[vector]	dim	1024	embedding 维度，与模型一致（如 bge-m3 为 1024）
[security]	skip_sensitive_files	true	命中凭据的文件整文件跳过

测试

.venv/bin/python -m pytest

覆盖：日期提取与归一化、切块规则、Excel 行分组合块、凭据脱敏、检索（top-k/日期过滤/来源多样性）、存储判重与级联删除。

设计文档

详细设计见 小雨Agent设计-r1.md（16 章：架构、数据模型、解析/切块/向量化/检索/生成设计、安全、测试与演进路线）。

项目规划

• v0.1（当前）：工作区索引 + CLI 问答 + profile 记忆层
• v0.2+（远期）：文件监听自动入库、滚动摘要、定时回顾、缺陷模式主动推送、Web 界面