# kbase
**Repository Path**: dxdbc/kbase
## Basic Information
- **Project Name**: kbase
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-07
- **Last Updated**: 2026-06-11
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# kbase — LLM-WIKI 实践
基于 OpenCode 的 LLM-WIKI 理念的一次实践。提供语义搜索、知识索引、健康检查等能力,让大模型帮你管理知识。使用者可以根据自己对 LLM-WIKI 的理解不断自行进化——这不正是 AI 带来的快乐吗?
---
## 知识宝库是什么
一个**可持续进化的个人知识系统**。你在日常使用 OpenCode 时遇到的值得保存的文章、报告、技术文档,都可以投入宝库。AI Agent 会自动完成内容分析、结构化整理和语义索引,让这些知识在未来的对话中可以被精准检索和引用。
它有几个特点:
- **语义检索,而非关键词匹配** — 所有 wiki 页面通过 bge-m3 模型做向量化,存入 Qdrant。你可以用自然语言描述需求,Agent 自动找到最相关的知识。
- **从原始资料到结构化知识的完整链路** — 每篇资料都保留 raw/ 原文,再提炼为 wiki/ 结构化页面,wiki 中的每个事实性断言都可以追溯到 raw/ 原文的具体位置。
- **数据工坊:跨域数据洞察** — 从文章中自动提取结构化数据(财务指标、市场行情、行业对比等),统一单位归一化到国标,支持自然语言和 SQL 查询,自动发现数据之间的跨域关联。
- **观星台:多源信息追踪** — 每日从东方财富、新浪、财联社、第一财经等源头并行采集财经资讯,自动交叉验证、因果链分析,识别注意力应分配的方向。
- **实体映射与企业财报分析** — 公司名/代码/实体间的映射查询,一键拉取 A股/港股/美股财报数据,从营收利润、盈利能力、成长性、估值四维度解读公司。
- **知识钩子实现跨项目复用** — 在项目 A 中解决问题的经验,可以留下"钩子"。当项目 B 遇到类似场景时,系统自动找到并提示。
- **定期体检保持宝库健康** — 自动检测矛盾、孤岛、断链、过时、漂移五类问题。
---
## 背后的大模型们
整个宝库在索引构建和语义搜索两个环节中使用 4 个模型:
| 模型 | 提供商 | 用途 | 环节 | 费用 |
|------|--------|------|------|------|
| **bge-m3** | SiliconFlow / 本地 | wiki 页面 + 用户查询向量化(embedding),搜索粗召回 | 索引构建、语义搜索 | API 按量 / 本地免费 |
| **bge-reranker-v2-m3** | SiliconFlow / 本地 | 搜索结果交叉编码精排(Top 10 → Top 3) | 语义搜索 | API 按量 / 本地免费 |
| **DeepSeek V4 Flash** | DeepSeek API | wiki 页面摘要生成(200字提炼) | 索引构建 | 按量付费 |
| **DeepSeek OCR** | SiliconFlow(免费) | 图片文字识别(截图文章处理) | 截图入库 | **免费** |
bge-m3 和 bge-reranker-v2-m3 的运行方式由 `EMBEDDING_MODE` 环境变量统一控制:未设默认走 API(效果最优),设为 `local` 走本地推理(免费,约 1.2GB 模型下载)。安装时由用户选择。
### 搜索流水线
```
用户查询 → bge-m3 向量化 → Qdrant 粗召回 Top 10
→ bge-reranker-v2-m3 精排 → Top 3-5 结果
```
### 你需要做的
**两个 API Key 需要自行配置:**
```bash
export DEEPSEEK_API_KEY=sk-... # DeepSeek API,摘要生成
export SILICONFLOW_API_KEY=sk-... # SiliconFlow API,搜索精排 + OCR + embedding 回退
```
- `DEEPSEEK_API_KEY` — 用于 wiki 摘要生成。在 [platform.deepseek.com](https://platform.deepseek.com) 注册获取。未设置时摘要退化为纯文本截取。
- `SILICONFLOW_API_KEY` — 用于语义搜索(API 模式时的 embedding + reranker)、OCR 文字识别。在 [siliconflow.cn](https://siliconflow.cn) 注册获取。如选择本地模式可跳过。
> ⚠️ **费用提醒**:DeepSeek V4 Flash 按 token 计费;bge-reranker-v2-m3 和 bge-m3(仅 SiliconFlow 回退时)按量计费。bge-m3 本地模型和 DeepSeek OCR 不产生费用。
**bge-m3 本地模型:**
安装时自动从 [HuggingFace](https://huggingface.co/Xenova/bge-m3) 下载约 600MB 的量化模型到 `~/.cache/transformers/`。如果下载失败或被墙,embedding 自动回退到 SiliconFlow。
---
安装过程由 OpenCode Agent 全自动完成。详细步骤见 [install.md](common/deploy/install.md)。
**快速流程:**
```bash
# 1. 创建一个新目录
mkdir my-knowledge-base && cd my-knowledge-base
# 2. 启动 OpenCode
opencode
```
**3. 在 OpenCode 中输入:**
> 请按照 https://gitee.com/dxdbc/kbase/raw/master/common/deploy/install.md 中的指南,为我的知识宝库完成安装。
Agent 会依次执行以下操作:
- 确认安装目录,询问宝库名称
- 检测操作系统,安装 Node.js / Qdrant / bge-m3 模型
- 下载 kbase 源码到 `./tmp/`,编译并发布 MCP Server 到全局
- 将使用规范(AGENTS.md)、索引脚本、项目 Skill 部署到项目目录
- 在 opencode.json 中注册 MCP Server 和全局 Skill
- 清理临时文件
安装完成后,项目目录结构如下:
```
my-knowledge-base/
├── AGENTS.md # 使用规范(安装时自动生成,含宝库名称)
├── raw/ # 原始资料(首次投入资料时创建)
│ └── index.md
├── wiki/ # 整理后的知识页面(首次投入资料时创建)
│ └── index.md
├── thoughts/ # 个人思想宝库
├── db/ # 数据工坊数据库
│ └── observatory.db # SQLite 数据文件(WAL 模式)
├── tmp/ # 临时文件目录
└── .opencode/
├── scripts/ # 语义索引脚本 + 数据工坊数据脚本
│ ├── build-index.js
│ └── observatory/
│ ├── db-init.js
│ ├── db-extract.js
│ ├── db-query.js
│ ├── db-schema.js
│ ├── db-relation.js
│ └── db-check.js
└── skills/
├── knowledge-health-check/ # 健康检查
├── data-analysis/ # 数据工坊数据分析
├── news-scan/ # 观星台多源财经资讯追踪
├── financial-analysis/ # 公司财报四维度深度解读
└── entity-mapping/ # 公司/指数/商品与 tushare/akshare 代码映射
```
---
## 使用指南
宝库的核心使用方式是**对话**——你告诉 OpenCode 你想做什么,Agent 会记住你给宝库起的名字,用自然的称呼与你互动。
### 支持的操作
| 你想做什么 | 对 OpenCode 说(以"智慧阁"为例) | Agent 会自动… |
|------------|------|--------------|
| 保存一篇网页文章 | "把这篇[文章链接]存入智慧阁" | 抓取内容 → 保存 raw/ → 提炼 wiki/ → 更新索引 → 构建语义向量 |
| 保存一个 PDF | "把这个[PDF路径]存入智慧阁" | 提取文字 → 保存 raw/ → 提炼 wiki/ → 更新索引 |
| 保存一篇公众号截图 | "把这篇[公众号链接]存入智慧阁" | 下载图片 → OCR → 保存 raw/ → 提炼 wiki/ → 更新索引 |
| 查找某方面知识 | "智慧阁里有没有关于[主题]的内容?" | 语义搜索 → 返回匹配的 wiki 页面摘要 |
| 查看某个知识页面 | "打开智慧阁中关于[主题]的页面" | 读取 wiki 页面全文 |
| 追溯原始来源 | "这篇 wiki 的原始资料在哪?" | 通过 knowledge_trace 找到 raw/ 中的原文 |
| 检查宝库健康 | "给智慧阁做个体检" | 执行五项检查 → 输出问题清单 |
| 浏览数据资产 | "智慧阁有哪些数据可以用" | 列出域表、数据量、字典 |
| 自然语言查数据 | "2025Q1 腾讯阿里营收对比" | Agent 翻译为 SQL → 执行 → 展示 |
| 直接 SQL 查询 | "SELECT * FROM company_financials" | 执行查询(readonly 安全) |
| 跨域组合分析 | "宁德时代受哪些行业因素影响" | 关联发现 → 多域并行拉取 → 组合结论 |
| 扫描每日资讯 | "扫描资讯""今天有什么新闻" | 4源并行采集 → 交叉验证 → 注视点/波动线/因果链 |
| 分析公司财报 | "分析一下宁德时代" | 查映射 → 拉财报/股价/新闻 → 四维度输出报告 |
| 查公司数据代码 | "宁德时代代码是什么" | 查 entity_map → 返回可在 tushare/akshare 使用的代码 |
| 在项目间共享经验 | "记住这个解法,以后[场景]可以用" | 创建知识钩子 → 下次匹配时自动提示 |
### 使用技巧
**1. 命名你的分类**
当第一篇资料入库时,Agent 会询问分类体系。分类反映你的思维结构,选你直觉上会去搜的名字:
> "把这篇关于 Rust 的文章存入智慧阁"
> Agent: 建议放入「编程语言/Rust」,可以吗?
> 你: 好
**2. 让 AI 承担检索负担**
不需要记住宝库里有什么,直接用自然语言描述:
> "最近在研究 GPU 编程,智慧阁里有没有相关内容?"
**3. 文章和截图自动分流**
Agent 根据内容形态自动选择处理方式——网页文章走文字提炼,PPT 截图走 OCR。你只负责提供链接。
**4. 定期体检,防微杜渐**
知识积累多了难免出现矛盾或断链:
> "给智慧阁做个体检"
建议每周或每新增 10 篇资料后做一次。
---
## 自进化
宝库不是一成不变的。在使用过程中发现现有规则或工具不够用:
### 规则进化
宝库的使用规范保存在项目根目录的 `AGENTS.md`。如果 AI 反复犯同样的错误:
> "把这个规则加到 AGENTS.md 里:以后遇到 PDF 要先检查文字层再决定处理方式"
Agent 会更新 AGENTS.md,后续自动遵循新规则。
### 工具进化
宝库的 Skill 和 MCP Server 在 kbase 仓库维护。有新的想法可以提 PR 或 Issue:
- 仓库:`https://gitee.com/dxdbc/kbase`
- 更新后在新环境重新安装即可获得最新版本
### 分享进化
如果你调整了规则或流程并认为有价值:
1. 提交到 kbase 仓库
2. 更新 `spec/AGENTS.md`(模板)
3. 写清楚提交信息说明"为什么改"
---
## 依赖
| 组件 | 说明 |
|------|------|
| **OpenCode** | AI 编程助手,宝库的操作入口 |
| **Node.js** ≥18 | MCP Server 运行时(安装时自动检测安装) |
| **Qdrant** | 向量数据库,存储语义向量(安装时自动下载) |
| **bge-m3** | 本地 embedding 模型 ~600MB(安装时从 HuggingFace 自动下载) |
| **better-sqlite3** | 数据工坊本地数据库(安装时自动安装) |
| **DEEPSEEK_API_KEY** | DeepSeek API,用于对话、摘要和数据提取(需自行配置,按量付费) |
| **SILICONFLOW_API_KEY** | SiliconFlow API,用于 OCR(免费)和 embedding 回退(按量付费) |
---
## 更多文档
- [v1 文本信息库管理 — 使用说明](codex/docs/v1-文本信息库管理-使用说明.md)
- [v1 文本信息库管理 — 实现设计](codex/docs/v1-文本信息库管理-实现设计.md)
- [v2 跨域数据洞察系统 — 使用说明](observatory/docs/v2-跨域数据洞察-使用说明.md)
- [v2 跨域数据洞察系统 — 实现设计](observatory/docs/v2-跨域数据洞察-实现设计.md)
- [v2 数据模型与关联发现设计](observatory/docs/v2-数据模型与关联发现设计.md)
- [数据工坊脚本说明](observatory/scripts/README.md)
- [KHub — 知识检索与分发](codex/mcp-server/KHub/docs/README.md)
- [MCP Server 使用手册](codex/mcp-server/KHub/docs/使用手册.md)
- [MCP 服务与钩子机制设计](codex/mcp-server/KHub/docs/知识库MCP服务与钩子机制设计.md)
- [语义搜索层设计](codex/mcp-server/KHub/docs/知识库语义搜索层设计.md)