# 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` | 列出所有数据库 |

---

## 环境变量配置

```bash
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 |