知识库2

好，我用最清晰的方式，把整个知识库架构从头到尾讲一遍，配合 Mermaid 图，让你一次看懂全貌。

---

一、整体架构全景图

```mermaid

flowchart TB

subgraph User["👤 用户层"]

U[用户提问]

end

subgraph OpenCode["🤖 OpenCode 层"]

OA[OpenCode Agent 理解意图/决策]

SK[Skill 技能 定义检索流程]

MCP[MCP Server 工具注册与调用]

end

subgraph Knowledge["📚 知识库核心层"]

direction TB

Parser[Parser 解析器 解析各类文件]

DB[(PostgreSQL 主存储 + 索引)]

FS[文件系统 原始文件存储]

Cache[缓存文件 加速启动]

end

subgraph Sources["📁 数据源层"]

Bug[🐛 Bug 报告 MD + 图片]

Spec[📄 Spec 文档 PDF + 图片]

Firm[⚙️ 固件代码 源码 + 二进制]

Other[➕ 其他数据源 日志/测试用例]

end

U --> OA

OA --> SK

SK --> MCP

MCP --> DB

MCP --> Cache

DB --> FS

Parser --> FS

Parser --> DB

FS --> Bug

FS --> Spec

FS --> Firm

FS --> Other

```

---

二、分层详解

第一层：数据源层（原始材料）

```mermaid

flowchart LR

subgraph S1["🐛 Bug 源"]

B1[report.md 标题/根因/方案]

B2[images/ VT图/截图]

end

subgraph S2["📄 Spec 源"]

S1_pdf[auth-spec.pdf 规范文档]

S2_pdf[payment-spec.pdf 接口规范]

end

subgraph S3["⚙️ 固件源"]

F1[token.c 源码文件]

F2[firmware.bin 二进制固件]

end

subgraph S4["📂 其他源"]

O1[日志文件]

O2[测试用例]

end

```

作用：存放所有原始知识材料，是知识库的“原材料仓库”。

关键点：

· Bug 报告是 Markdown 格式，包含 Frontmatter 元数据和正文

· Spec 是 PDF 格式，包含规范条文和图表

· 固件包括源码（.c/.h）和二进制（.bin/.elf）

· 每种数据源都有自己的目录结构

---

第二层：解析器层（翻译官）

```mermaid

flowchart TB

subgraph P["解析器工厂"]

BP[Bug Parser 解析 MD]

SP[Spec Parser 解析 PDF]

FP[Firmware Parser 解析源码/二进制]

OP[其他 Parser 扩展用]

end

subgraph O["统一输出格式"]

O1[source_type: bug/spec/firmware]

O2[title, content, summary]

O3[module, version, severity]

O4[error_codes, keywords, log_pattern]

O5[root_cause, solution]

O6[metadata JSONB]

O7[attachments]

end

BP --> O

SP --> O

FP --> O

OP --> O

```

作用：把各种格式的原始文件，翻译成统一的结构化数据。

关键点：

· 每种数据源有独立的 Parser

· 所有 Parser 输出相同的格式（统一知识条目）

· Bug Parser 提取 Frontmatter + 正文章节

· Spec Parser 提取 PDF 全文 + 图片

· Firmware Parser 提取函数、调用关系、错误字符串

---

第三层：存储层（PostgreSQL + 文件系统 + 缓存）

```mermaid

flowchart TB

subgraph FS["💾 文件系统"]

F1[bugs/ 原始 MD + 图片]

F2[specs/ 原始 PDF]

F3[firmware/ 源码 + 二进制]

F4[.skills/ Skill 定义]

F5[.metadata/ 缓存文件]

F6[cache/ PDF 解析缓存]

end

subgraph DB["🗄️ PostgreSQL"]

D1[(knowledge_entries 主表：所有条目元数据)]

D2[(knowledge_embeddings 向量表：语义指纹)]

D3[(knowledge_attachments 附件表：图片元数据)]

D4[(knowledge_relations 关联表：知识图谱)]

D5[(data_sources 配置表：数据源管理)]

end

F1 -.->|解析后写入| D1

F2 -.->|解析后写入| D1

F3 -.->|解析后写入| D1

D1 -->|生成向量| D2

D1 -->|关联图片| D3

D1 -->|建立关系| D4

D5 -->|配置 Parser| D1

D1 -.->|导出快照| F5

```

作用：持久化存储所有知识和索引，是知识库的“记忆中枢”。

PostgreSQL 五张表详解：

表名存储内容作用

knowledge_entries 所有条目的元数据（标题、内容、根因、方案）主表，所有查询的入口

knowledge_embeddings 768维向量（语义指纹）语义检索的核心

knowledge_attachments 图片路径 + OCR 文字 + 描述让 AI 能“看懂”图片

knowledge_relations 条目间的关联关系知识图谱，跨源关联

data_sources 数据源配置（Parser 模块名）系统启动时加载

文件系统目录：

目录内容作用

bugs/ MD + 图片人可读的 Bug 报告

specs/ PDF 文件原始规范文档

firmware/ 源码 + 二进制固件代码

.skills/ SKILL.md 告诉 OpenCode 怎么处理

.metadata/ index.json + embeddings.npy 加速 MCP Server 启动

cache/ PDF 解析缓存避免重复解析 PDF

---

第四层：检索层（粗索引体系）

```mermaid

flowchart TB

subgraph Index["🔍 粗索引体系"]

direction TB

K[关键词索引 GIN 索引]

E[错误码索引 GIN 索引]

F[全文检索索引 GIN 索引]

V[向量索引 IVFFlat 索引]

C[缓存文件 JSON + NumPy]

end

subgraph Query["📝 查询方式"]

Q1["错误码精确匹配 WHERE 'ETIMEDOUT' = ANY(error_codes)"]

Q2["关键词模糊匹配 WHERE keywords && ARRAY['timeout']"]

Q3["全文搜索 WHERE search_document @@ 'timeout'"]

Q4["语义相似度 ORDER BY embedding <=> query_vec"]

Q5["内存计算 从缓存加载后直接算"]

end

K --> Q2

E --> Q1

F --> Q3

V --> Q4

C --> Q5

```

作用：提供多种快速检索入口，让查询在毫秒级完成。

粗索引的五种实现：

索引类型存储位置技术查询场景

关键词索引 PostgreSQL GIN 用户输入 "timeout redis"

错误码索引 PostgreSQL GIN 日志包含 "ETIMEDOUT"

全文索引 PostgreSQL GIN 用户输入 "连接超时"

向量索引 PostgreSQL IVFFlat "语义上相似的内容"

缓存文件 .metadata/ JSON + NumPy MCP Server 启动加速

---

第五层：OpenCode 接入层（Skill + MCP）

```mermaid

flowchart TB

subgraph OC["OpenCode 调用链路"]

U[用户提问]

A[Agent 理解意图]

S[选择 Skill]

T[调用 MCP Tool]

R[返回结果]

end

subgraph Skill["Skill 定义"]

S1[bug-analyzer 处理 Bug 报告]

S2[spec-analyzer 处理 Spec 文档]

S3[firmware-analyzer 处理固件代码]

S4[universal-search 跨源检索]

end

subgraph MCP["MCP Server 工具"]

M1[search_knowledge 统一检索入口]

M2[get_detail 获取完整详情]

M3[关联查询 知识图谱]

end

U --> A

A --> S

S --> T

T --> M1

M1 --> DB

M1 --> Cache

DB --> R

R --> U

```

作用：让 OpenCode 能够调用知识库，实现“提问→检索→回答”的闭环。

调用关系：

组件作用调用方式

Skill 定义检索流程和顺序 Agent 根据用户意图自动选择

MCP Tool 暴露具体检索能力 Skill 内部调用 search_knowledge

MCP Server 连接 PostgreSQL 和缓存执行 SQL 查询，返回结构化结果

OpenCode Agent 理解用户意图，调度 Skill 用户提问触发

---

三、完整数据流（从写入到检索）

```mermaid

flowchart LR

subgraph Write["📝 写入流程"]

W1[新文件 MD/PDF/源码]

W2[Parser 解析 提取结构化数据]

W3[写入 PostgreSQL 主表 + 向量表]

W4[导出缓存 .metadata/]

end

subgraph Read["🔍 检索流程"]

R1[用户提问 "连接超时"]

R2[OpenCode Agent 理解意图]

R3[选择 Skill bug-analyzer]

R4[调用 MCP Tool search_knowledge]

R5[查询 PostgreSQL 向量 + 关键词]

R6[返回匹配结果 BUG-001 根因+方案]

end

W1 --> W2 --> W3 --> W4

R1 --> R2 --> R3 --> R4 --> R5 --> R6

```

---

四、各组件调用关系总结

```mermaid

flowchart TB

subgraph Legend["调用关系说明"]

L1["──▶ 数据流"]

L2["─ ─▶ 配置/导出"]

L3["◀──▶ 双向交互"]

end

subgraph Main["核心组件"]

U[用户]

OC[OpenCode Agent]

SK[Skill]

MC[MCP Server]

DB[(PostgreSQL)]

FS[文件系统]

CA[缓存文件]

PA[Parser 解析器]

SRC[数据源文件]

end

U -->|提问| OC

OC -->|加载| SK

SK -->|调用工具| MC

MC -->|SQL查询| DB

MC -->|读取| CA

DB <-->|读写| FS

PA -->|写入| DB

PA -->|读取| SRC

PA -->|生成| CA

DB -.->|导出| CA

SRC -->|存储| FS

```

---

五、架构的核心设计原则

原则说明

读/写分离写入走 Parser → PostgreSQL，读取走 MCP → PostgreSQL/缓存

统一模型所有数据源存入同一张表，通过 source_type 区分

分层索引关键词索引 + 全文索引 + 向量索引 + 缓存文件，多路召回

解耦设计文件系统存原始文件，PostgreSQL 存元数据，互不依赖

可扩展性新增数据源只需写新 Parser + 新 Skill，核心架构不变

加速策略热数据（向量）存 PostgreSQL，热启动（缓存）存 .metadata/

---

六、一句话总结整个架构

文件系统存原始材料，Parser 翻译成统一格式，PostgreSQL 建立多层索引（关键词+全文+向量），缓存文件加速启动，MCP Server 暴露检索工具，OpenCode 通过 Skill 调用并返回结果。

这样整个知识库就形成了 “原始文件 → 解析 → 索引 → 检索 → 回答” 的完整闭环。😊

posted @ 2026-06-29 14:29 朵朵奇fa 阅读(7) 评论(0) 收藏举报

刷新页面返回顶部

朵朵奇fa

知识库2

公告