Agent/knowhub/docs/schema-migration-plan.md

Schema 迁移方案：新库 knowhub

背景

旧库 knowledge_hub 使用 JSONB 数组存储实体间关系，存在一致性、索引、命名问题。迁移目标：在新库 knowhub 中建立干净的关联表结构。

为什么新建库而不是原地改

阿里云 AnalyticDB for PostgreSQL 的 DDL 限制（已验证）：

操作	是否安全	说明
CREATE TABLE	✅ 安全	包括 IF NOT EXISTS
DROP TABLE	✅ 安全	已验证可用
INSERT / SELECT	✅ 安全	包括 ON CONFLICT DO NOTHING
ALTER TABLE RENAME	❌ 致命	导致表损坏，需重启实例恢复
ALTER TABLE DROP COLUMN	❌ 致命	同上
FK / ON DELETE CASCADE	❌ 不支持	底层依赖 trigger，而 trigger 不被支持
事务内 DDL	❌ 不可靠	DDL 回滚不完整，部分操作会持久化

改表结构的安全方式：CREATE TABLE 新表 → INSERT 数据 → DROP TABLE 旧表。

原地迁移多次失败后，决定新建库 knowhub，用 CREATE TABLE + INSERT 完成迁移。旧库保留作为备份。

目标结构

见 schema.md。5 实体表 + 8 关联表 = 13 张表。

旧库现状（2026-04-08）

旧表	状态	说明
knowledge (766 rows)	可用	仍含 support_capability、tools、resource_ids、relationships 旧字段
tool (305 rows)	可用	原 tool_table，被 RENAME；JSONB 关联列已丢失
capability / atomic_capability (21 rows)	可用	两个名字同时可访问
requirement / requirement_table (99 rows)	可用	两个名字同时可访问
resources (73 rows)	可用	无变化
requirement_capability (214 rows)	可用	旧迁移已填充
capability_tool (67 rows)	可用	旧迁移已填充（仅 capability 侧）
capability_knowledge (0 rows)	可用	源数据为空
tool_knowledge (846 rows)	可用	旧迁移已填充

新库迁移步骤

Step 1：在 knowhub 库建 13 张表

只用 CREATE TABLE IF NOT EXISTS，不用 ALTER/RENAME/DROP。

Step 2：迁移实体数据

从 knowledge_hub 读 → 写入 knowhub。每张表只选需要的列：

新表	源表	选取列（排除的旧字段）
knowledge	knowledge	排除 support_capability, tools, resource_ids, relationships
resource	resources	全部
requirement	requirement	排除 atomics
capability	capability	排除 requirements, implements, tools, source_knowledge
tool	tool	排除 implemented_tool_ids（已无 JSONB 关联列）

Step 3：迁移关联数据

从旧关联表直接复制（已有正确数据）：

• requirement_capability (214 rows)
• capability_tool (67 rows)
• tool_knowledge (846 rows)

从旧 JSONB 字段提取（新增的关联表）：

• requirement_knowledge — 从 requirement 和 knowledge 的关联提取（如有）
• knowledge_resource — 从 knowledge.resource_ids 数组提取
• knowledge_relation — 从 knowledge.relationships JSONB 提取
• tool_provider — 需手动或从工具库数据填充

无数据需迁移：

• capability_knowledge — 源数据为空

Step 4：验证

对比新旧库行数，确认数据完整。

Step 5：切换

更新 .env 中 KNOWHUB_DB_NAME=knowhub，重启服务。

代码改动范围

• knowhub_db/pg_*.py：所有 store 适配新表结构
• knowhub_db/cascade.py：更新关联表注册
• knowhub/server.py：Pydantic 模型和 API handler
• knowhub/agents/librarian_agent.prompt：schema 描述
• .env：KNOWHUB_DB_NAME

迁移脚本

knowhub/knowhub_db/migrations/migrate_to_new_db.py