Agent/knowhub/knowhub_db

knowhub/knowhub_db 模块总结

概述

knowhub_db 是 KnowHub 系统的 PostgreSQL 数据库访问层，从早期的 Milvus（向量数据库）迁移而来，现使用远程 PostgreSQL + fastann/pgvector 扩展同时支持向量检索和关系型查询。

---

数据库表结构

当前数据量：knowledge 387 条，resources 70 条，tool_table 163 条，skill_table / requirement_table 暂无数据。

1. knowledge — 核心知识条目表（387 rows）

索引：knowledge_pkey (id)、idx_knowledge_owner、idx_knowledge_status

字段	类型	说明	示例值
id	VARCHAR	主键，格式 knowledge-{日期}-{时间}-{hash}	knowledge-20260330-030758-8611
embedding	ARRAY (float4[])	1536 维向量，用于语义检索	—
message_id	VARCHAR	来源消息 ID	""
task	VARCHAR	产生该知识时的任务描述	"在调研 AI 工具功能特性时..."
content	TEXT	知识正文	"当调研新兴 AI 工具时，应采用多渠道策略..."
types	ARRAY	知识类型标签	['strategy']、['tool', 'strategy']
tags	JSONB	标签键值对	{"tool": true, "intent": "信息调研", "project": "feature_extract"}
tag_keys	ARRAY	tags 中的键列表（用于过滤）	['intent', 'state', 'project']
scopes	ARRAY	作用域（组织/用户）	['org:cybertogether']
owner	VARCHAR	所有者（agent_id 或 email）	"srt_feature_extract_1"
resource_ids	ARRAY	关联的 resource ID 列表	['tools/image_gen/midjourney']
source	JSONB	来源信息	{"agent_id": "research_agent", "category": "exp", "timestamp": "..."}
eval	JSONB	评估信息	{"score": 5, "harmful": 0, "helpful": 1, "confidence": 0.5}
created_at	BIGINT	创建时间戳（秒）	1774811278
updated_at	BIGINT	更新时间戳（秒）	1774943256
status	VARCHAR	状态	"approved"
relationships	JSONB	关联关系列表	[{"type": "complement", "target": "knowledge-..."}]

2. resources — 文档资源表（70 rows）

索引：resources_pkey (id)

字段	类型	说明	示例值
id	TEXT	主键，/ 分隔路径格式	"references/python_type_hints"、"code/web-crawler/baidu_hot_search"
title	TEXT	标题	"Python Type Hints 权威资源列表"
body	TEXT	公开内容（Markdown 或代码）	"Python 类型提示调研的三个核心权威资源..."
secure_body	TEXT	私有/加密内容	""
content_type	TEXT	内容类型	"text"
metadata	JSONB	附加元数据，含 knowledge_ids 引用	{"topic": "type_hints", "category": "python", "verified_at": "2026-03-24"}
sort_order	INTEGER	排序权重	0
submitted_by	TEXT	提交者	""
created_at	BIGINT	创建时间戳（秒）	1774259301
updated_at	BIGINT	更新时间戳（秒）	1774259301

3. tool_table — 工具表（163 rows）

索引：tool_table_pkey (id)

字段	类型	说明	示例值
id	VARCHAR	主键，路径格式	"tools/image_gen/webui"、"tools/plugin/ksampler"
name	VARCHAR	工具名称	"WebUI"、"KSampler"
version	VARCHAR	版本号	null
introduction	TEXT	简介	"传统的 Stable Diffusion 网页用户界面"
tutorial	TEXT	使用教程	"通过表单参数配置进行图像生成"
input	JSONB	输入规格	"文本提示、参数配置"
output	JSONB	输出规格	"生成图像"
updated_time	BIGINT	更新时间戳（秒）	1774570091
status	VARCHAR	接入状态	"未接入" / "可用" / "异常"
knowledge	JSONB	关联通用知识 ID 列表	["knowledge-20260327-150915-44a4"]
case_knowledge	JSONB	关联用例知识 ID 列表	[]
process_knowledge	JSONB	关联工序知识 ID 列表	[]

4. skill_table — 技能表（0 rows）

索引：skill_table_pkey (id)

字段	类型	说明
id	VARCHAR	主键
name	VARCHAR	技能名称
version	VARCHAR	版本号
introduction	TEXT	简介
input	JSONB	输入规格
output	JSONB	输出规格
updated_time	BIGINT	更新时间戳
resource_id	VARCHAR	关联的 tool_table.id
knowledge	JSONB	关联通用知识 ID 列表
case_knowledge	JSONB	关联用例知识 ID 列表
process_knowledge	JSONB	关联工序知识 ID 列表
status	VARCHAR	状态："未验证" / "可用" / "异常"

5. requirement_table — 需求表（0 rows）

索引：requirement_table_pkey (id)、idx_requirement_embedding（fastann ANN，dim=1536，hnsw_m=16）

字段	类型	说明
id	VARCHAR	主键
task	TEXT	任务需求描述
type	VARCHAR	需求类型（如 "制作"）
source_type	VARCHAR	来源类型（如 "itemset"）
source_itemset_id	VARCHAR	关联 pattern 的 ID
source_items	JSONB	包含的特征/分类列表
tools	JSONB	关联工具 ID 与简介
knowledge	JSONB	关联通用知识 ID 列表
case_knowledge	JSONB	关联用例知识 ID 列表
process_knowledge	JSONB	关联工序知识 ID 列表
trace	JSONB	关联的任务执行 log
body	TEXT	需求正文（str/json）
embedding	ARRAY (float4[])	1536 维向量，用 fastann ANN 索引检索

---

核心封装类

PostgreSQLStore (pg_store.py)

知识条目的 CRUD + 向量检索：

方法	功能
insert(knowledge)	插入单条知识
insert_batch(list)	批量插入（用 execute_batch）
search(embedding, filters, limit)	向量相似度检索（<=> 余弦距离）
query(filters, limit)	纯标量过滤查询
get_by_id(id, include_embedding)	按 ID 查询（默认不返回向量以提升性能）
update(id, updates)	更新字段
delete(id)	删除
count()	统计总数
_build_where_clause(filters)	将 Milvus 风格过滤语法转换为 PostgreSQL WHERE 子句

过滤语法转换示例：

# 输入（Milvus 风格）
'array_contains(types, "insight") and eval["score"] == 5'
# 转换后（PostgreSQL）
"WHERE types @> ARRAY['insight'] AND (eval->>'score')::int = 5"

PostgreSQLResourceStore (pg_resource_store.py)

资源文档的 CRUD + 导航：

方法	功能
insert_or_update(resource)	插入或更新（ON CONFLICT DO UPDATE）
get_by_id(id)	按 ID 查询
list_resources(prefix, content_type, limit, offset)	列表查询，支持路径前缀过滤
update(id, updates)	更新
delete(id)	删除
get_siblings(id)	获取前后同级节点（用于文档导航）

---

运维脚本

脚本	功能
create_tables.py	创建 tool_table、skill_table、requirement_table 三张表及 fastann 索引
migrate_resources.py	从 SQLite 迁移 text 类型资源到 PostgreSQL
migrate_tools.py	从 SQLite 迁移 tool 类型数据到 tool_table
clean_invalid_knowledge_refs.py	清理 tool_table.knowledge 中失效的 knowledge ID 引用
clean_resource_knowledge_refs.py	清理 resources.metadata.knowledge_ids 中失效的引用
test_pg_connection.py	测试数据库连接，检查版本、pgvector 扩展及表列表
check_extensions.py	查看 PostgreSQL 可用及已安装的向量扩展
check_fastann.py	查看 fastann 相关函数和操作符
list_databases.py	列出主机上所有数据库

---

环境变量配置

KNOWHUB_DB        # 数据库主机
KNOWHUB_PORT      # 端口（默认 5432）
KNOWHUB_USER      # 用户名
KNOWHUB_PASSWORD  # 密码
KNOWHUB_DB_NAME   # 数据库名

---

架构特点

1. 向量检索：knowledge 和 requirement_table 均有 float4[] 向量字段，前者用 <=> 运算符（pgvector），后者用 fastann ANN 索引，支持 HNSW 算法（hnsw_m=16）。
2. 兼容层：_build_where_clause 保留了 Milvus 过滤语法兼容，方便旧代码平滑迁移。
3. 三层知识关联：工具/技能/需求均挂载 knowledge（通用）、case_knowledge（用例）、process_knowledge（工序）三类引用，形成细粒度的知识图谱。
4. 资源路径 ID：resources.id 支持 / 分隔路径（如 tools/search/api），get_siblings 利用字典序实现层级导航。