Agent/knowhub/knowhub_db/README.md

knowhub_db — 数据库访问层

PostgreSQL 数据库的封装层。表结构和数据模型详见 docs/schema.md。

---

封装类

PostgreSQLStore (pg_store.py)

knowledge 表的 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)

resource 表的 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)	获取前后同级节点

PostgreSQLToolStore (pg_tool_store.py)

tool 表的 CRUD + 向量检索。关联表：capability_tool, tool_knowledge。

PostgreSQLCapabilityStore (pg_capability_store.py)

capability 表的 CRUD + 向量检索。关联表：requirement_capability, capability_tool, capability_knowledge。

PostgreSQLRequirementStore (pg_requirement_store.py)

requirement 表的 CRUD + 向量检索。关联表：requirement_capability, requirement_knowledge。

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

---

目录结构

knowhub_db/
├── pg_store.py                # knowledge 表
├── pg_resource_store.py       # resource 表
├── cascade.py                 # 级联删除（应用层，替代 FK ON DELETE CASCADE）
├── pg_tool_store.py           # tool 表
├── pg_capability_store.py     # capability 表
├── pg_requirement_store.py    # requirement 表
├── README.md
├── migrations/                # 一次性迁移脚本（已执行，保留备查）
└── scripts/                   # 诊断和运维脚本
    ├── check_table_structure.py   # 查看表结构和行数
    ├── check_extensions.py        # 查看 PostgreSQL 扩展
    ├── clear_locks.py             # 清理数据库锁
    ├── clean_invalid_knowledge_refs.py  # 清理失效引用
    └── ...

---

环境变量

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