update knowhub_db readme

knowhub/knowhub_db/README.md

@@ -0,0 +1,186 @@
+# 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 子句 |
+
+**过滤语法转换示例：**
+```python
+# 输入（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` | 列出主机上所有数据库 |
+
+---
+
+## 环境变量配置
+
+```bash
+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` 利用字典序实现层级导航。