Agent/knowhub/knowhub_db

knowhub/knowhub_db 数据库设计文档

概述

knowhub_db 是 KnowHub 系统的 PostgreSQL 数据库访问层，使用远程 PostgreSQL + fastann/pgvector 扩展同时支持向量检索和关系型查询。

系统围绕四张核心表构建，以 原子能力（atomic_capability） 为中心，连接知识、工具和需求：

                     knowledge（知识表）
                    ╱         ╲
        support_capability    tools
               ╱                ╲
  atomic_capability  ←────→  tool_table
    （原子能力表）              （工具表）
         |                       |
    requirements            capabilities
         ↓                       ↓
  requirement_table ←──────→ atomic_capability
     （需求表）

---

数据库表结构

1. atomic_capability — 原子能力表（新增）

原子能力是系统的核心概念，从知识中提炼而来，连接工具实现与需求匹配。

索引：atomic_capability_pkey (id)

字段	类型	说明	示例值
id	VARCHAR	主键	"ac-image-gen-001"
name	VARCHAR	能力名称	"文生图"
criterion	TEXT	评估标准，用于判断该能力是否达成	"能根据文本提示生成符合描述的图像"
description	TEXT	能力描述	"通过自然语言描述生成对应视觉内容的能力"
requirements	JSONB	关联的需求 ID 列表	["req-001", "req-002"]
implements	JSONB	工具实现映射，key 为 tool_name，value 为描述（使用方式、效果、局限）	{"Midjourney": "通过 /imagine 命令生成图像，效果优秀但不支持中文提示词"}
tools	JSONB	关联的工具 ID 列表	["tools/image_gen/midjourney"]
source_knowledge	JSONB	该能力提炼自哪些知识条目	["knowledge-20260330-030758-8611"]
embedding	float4[]	1536 维向量，对 name + description 做 embedding	—

关联关系：

• tools → tool_table.id
• implements 的 key 为 tool_table.name
• requirements → requirement_table.id
• source_knowledge → knowledge.id

---

2. tool_table — 工具表（变更）

相对原表的变更：新增 capabilities 字段；知识关联字段重命名为 tool_knowledge、case_knowledge、process_knowledge。

索引：tool_table_pkey (id)

字段	类型	说明	示例值
id	VARCHAR	主键，路径格式	"tools/image_gen/midjourney"
name	VARCHAR	工具名称	"Midjourney"
version	VARCHAR	版本号	"v5.2"
introduction	TEXT	功能介绍	"AI 图像生成工具，支持文生图、图生图"
tutorial	TEXT	使用指南	"通过 Discord 输入 /imagine 命令..."
input	JSONB	输入规格	"文本提示、参数配置"
output	JSONB	输出规格	"生成图像"
updated_time	BIGINT	更新时间戳（秒）	1774570091
status	VARCHAR	接入状态	"未接入" / "可用" / "异常"
capabilities	JSONB	关联的原子能力 ID 列表	["ac-image-gen-001", "ac-image-edit-002"]
tool_knowledge	JSONB	关联的工具知识 ID 列表	["knowledge-20260327-150915-44a4"]
case_knowledge	JSONB	关联的用例知识 ID 列表	[]
process_knowledge	JSONB	关联的工序知识 ID 列表	[]
embedding	float4[]	1536 维向量，对 name + introduction 做 embedding	—

关联关系：

• capabilities → atomic_capability.id
• tool_knowledge / case_knowledge / process_knowledge → knowledge.id

相对原表变更说明：

• 新增 capabilities 字段（JSONB 数组）
• 新增 embedding 字段（float4[]，对 name + introduction 做 embedding）
• 原 knowledge 字段重命名为 tool_knowledge

---

3. knowledge — 知识表（变更）

相对原表的变更：新增 support_capability、tools 字段；原 embedding 拆分为 task_embedding + content_embedding 双向量；types 扩展为六种分类。其余原有字段全部保留。

索引：knowledge_pkey (id)、idx_knowledge_owner、idx_knowledge_status

字段	类型	说明	示例值
id	VARCHAR	主键	"knowledge-20260330-030758-8611"
task_embedding	float4[]	1536 维向量，对 task 做 embedding	—
content_embedding	float4[]	1536 维向量，对 content 做 embedding	—
message_id	VARCHAR	来源的 agent 任务消息 ID	""
task	VARCHAR	完成什么任务	"调研 AI 图像生成工具的功能特性"
content	TEXT	知识正文	"当调研新兴 AI 工具时..."
types	ARRAY	知识类型（多选）：工序、用例、工具、经验、定义、User Profile	['工具', '经验']
tags	JSONB	标签键值对	{"intent": "信息调研", "project": "feature_extract"}
tag_keys	ARRAY	tags 中的键列表（用于过滤）	['intent', 'state', 'project']
scopes	ARRAY	作用域（组织/用户）	['org:cybertogether']
owner	VARCHAR	所有者	"srt_feature_extract_1"
resource_ids	ARRAY	关联的 resource ID 列表	['tools/image_gen/midjourney']
source	JSONB	来源信息	{"agent_id": "research_agent", "category": "exp"}
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-..."}]
support_capability	JSONB	支撑的原子能力 ID 列表（可多个）	["ac-image-gen-001", "ac-style-transfer-003"]
tools	JSONB	关联的工具 ID 列表	["tools/image_gen/midjourney"]

关联关系：

• support_capability → atomic_capability.id
• tools → tool_table.id

相对原表变更说明：

• 新增字段：support_capability（JSONB）、tools（JSONB）
• 原 embedding（float4[]）拆分为 task_embedding + content_embedding 两个向量字段
• types 可选值更新为：工序、用例、工具、经验、定义、User Profile
• 所有原有字段保留不变

---

4. requirement_table — 需求表（变更）

相对原表的变更：大幅简化，以原子能力 pattern 为核心，替代原来的 source_items/tools/trace/embedding 等字段。

索引：requirement_table_pkey (id)

字段	类型	说明	示例值
id	VARCHAR	主键	"req-001"
description	TEXT	需求描述	"能够根据用户文本描述生成高质量图像"
atomics	JSONB	关联的原子能力 ID 列表	["ac-image-gen-001", "ac-style-transfer-003"]
source_nodes	JSONB	来源于内容树的节点，对象数组	[{"node_name": "image_gen", "posts": ["post-001", "post-002"]}]
status	VARCHAR	满足状态	"已满足" / "未满足"
match_result	TEXT	满足时描述如何满足；不足时描述缺什么，提供调研方向	"通过 Midjourney + ComfyUI 组合可满足，但中文提示词支持不足，需调研替代方案"
embedding	float4[]	1536 维向量，对 description 做 embedding	—

关联关系：

• atomics → atomic_capability.id

相对原表变更说明：

• 删除字段：task、type、source_type、source_itemset_id、source_items、tools、knowledge、case_knowledge、process_knowledge、trace、body、embedding
• 新增字段：description（TEXT）、atomics（JSONB）、source_nodes（JSONB）、status（VARCHAR）、match_result（TEXT）

---

5. resources — 文档资源表（未变更）

索引：resources_pkey (id)

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

---

表间关联关系总览

所有关联均为 应用层软关联（JSONB 字段存储 ID 列表/映射），不使用数据库外键约束。

atomic_capability.tools[]             ──→  tool_table.id
atomic_capability.implements{key}     ──→  tool_table.name
atomic_capability.requirements[]      ──→  requirement_table.id
atomic_capability.source_knowledge[]  ──→  knowledge.id

tool_table.capabilities[]          ──→  atomic_capability.id
tool_table.tool_knowledge[]        ──→  knowledge.id
tool_table.case_knowledge[]        ──→  knowledge.id
tool_table.process_knowledge[]     ──→  knowledge.id

knowledge.support_capability[]     ──→  atomic_capability.id
knowledge.tools[]                  ──→  tool_table.id

requirement_table.atomics[]        ──→  atomic_capability.id

双向关联说明：

• atomic_capability ↔ tool_table：能力的 implements 和工具的 capabilities 互为反向索引
• atomic_capability ↔ knowledge：能力的 source_knowledge 和知识的 support_capability 互为反向索引
• atomic_capability ↔ requirement_table：能力的 requirements 和需求的 atomics 互为反向索引

---

核心封装类

PostgreSQLStore (pg_store.py)

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

方法	功能
insert(knowledge)	插入单条知识
insert_batch(list)	批量插入
search(embedding, filters, limit)	向量相似度检索
query(filters, limit)	纯标量过滤查询
get_by_id(id)	按 ID 查询
update(id, updates)	更新字段
delete(id)	删除
count()	统计总数

PostgreSQLResourceStore (pg_resource_store.py)

资源文档的 CRUD + 导航：

方法	功能
insert_or_update(resource)	插入或更新
get_by_id(id)	按 ID 查询
list_resources(prefix, content_type, limit, offset)	列表查询
update(id, updates)	更新
delete(id)	删除
get_siblings(id)	获取前后同级节点

PostgreSQLRequirementStore (pg_requirement_store.py)

需求的 CRUD + 向量检索：

方法	功能
insert_or_update(requirement)	插入或更新
get_by_id(id)	按 ID 查询
search(embedding, limit)	向量检索
list_all(limit)	列出所有需求
count()	统计总数

---

运维脚本

脚本	功能
create_tables.py	创建/变更数据库表结构
migrate_resources.py	从 SQLite 迁移资源到 PostgreSQL
migrate_tools.py	从 SQLite 迁移工具数据
clean_invalid_knowledge_refs.py	清理失效的 knowledge ID 引用
clean_resource_knowledge_refs.py	清理 resources 中失效的引用
test_pg_connection.py	测试数据库连接
check_extensions.py	查看向量扩展
check_fastann.py	查看 fastann 函数和操作符
list_databases.py	列出所有数据库

---

环境变量配置

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

---

架构特点

1. 原子能力为核心：atomic_capability 作为知识、工具、需求三者之间的桥梁，实现能力的提炼、实现映射和需求匹配。
2. 全表向量检索：四张核心表均支持 1536 维 embedding，其中 knowledge 表有双向量（task_embedding + content_embedding）分别支持任务语义和内容语义检索。
3. 应用层软关联：所有表间关系通过 JSONB 字段存储 ID 列表/映射，保持灵活性，需应用层维护一致性。
4. 双向索引：核心关联关系均有正反两个方向的索引，方便从任意一端查询关联数据。
5. 三类工具知识：工具关联的知识分为工具知识（tool_knowledge）、工序知识（process_knowledge）、用例知识（case_knowledge）三类，形成细粒度的知识图谱。
6. 资源路径 ID：resources.id 和 tool_table.id 均支持 / 分隔路径格式，便于层级组织和导航。

Embedding 策略

表	向量字段	Embedding 内容
atomic_capability	embedding	name + description
tool_table	embedding	name + introduction
knowledge	task_embedding	task
knowledge	content_embedding	content
requirement_table	embedding	description