# 数据模型

## 文档维护规范

0. **先改文档，再动代码** - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
1. **文档分层，链接代码** - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：`module/file.py:function_name`
2. **简洁快照，日志分离** - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议、决策历史、修改日志、大量代码；决策依据或修改日志若有必要，可在 `knowhub/docs/decisions.md` 另行记录

---

## 存储架构

PostgreSQL + pgvector 扩展。所有向量字段为 float4[]（1536维），使用余弦距离（`<=>`）检索。

Embedding 模型：`google/gemini-2.5-flash-lite`（通过 OpenRouter）。实现：`knowhub/embeddings.py`。

---

## 表间关系

以 atomic_capability 为中心，连接知识、工具和需求：

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

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

---

## knowledge — 知识表

实现：`knowhub_db/pg_store.py:PostgreSQLStore`

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | VARCHAR PK | `"knowledge-{timestamp}-{random}"` |
| `task_embedding` | float4[] | task 的向量 |
| `content_embedding` | float4[] | content 的向量 |
| `message_id` | VARCHAR | 来源 Agent 消息 ID |
| `task` | VARCHAR | 任务场景描述 |
| `content` | TEXT | 知识正文 |
| `types` | ARRAY | 知识类型（多选）：工序/用例/工具/经验/定义/User Profile |
| `tags` | JSONB | 标签键值对 |
| `tag_keys` | ARRAY | tags 中的键列表（用于过滤） |
| `scopes` | ARRAY | 作用域，如 `["org:cybertogether"]` |
| `owner` | VARCHAR | 所有者 |
| `resource_ids` | ARRAY | 关联的 resource ID 列表 |
| `source` | JSONB | 来源信息（agent_id, category, urls, submitted_by, timestamp） |
| `eval` | JSONB | 评估（score, helpful, harmful, confidence, helpful_history, harmful_history） |
| `created_at` | BIGINT | 创建时间戳（秒） |
| `updated_at` | BIGINT | 更新时间戳（秒） |
| `status` | VARCHAR | pending → processing → dedup_passed → analyzing → approved/rejected/checked |
| `relationships` | JSONB | 与其他知识的关系列表 `[{type, target}]` |
| `support_capability` | JSONB | 支撑的原子能力 ID 列表 → `atomic_capability.id` |
| `tools` | JSONB | 关联的工具 ID 列表 → `tool_table.id` |

索引：`knowledge_pkey (id)`、`idx_knowledge_owner`、`idx_knowledge_status`

---

## resources — 资源表

实现：`knowhub_db/pg_resource_store.py:PostgreSQLResourceStore`

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | TEXT PK | 路径格式，如 `"tools/selenium/login"` |
| `title` | TEXT | 标题 |
| `body` | TEXT | 公开内容（Markdown/代码） |
| `secure_body` | TEXT | 敏感内容（AES-256-GCM 加密） |
| `content_type` | TEXT | text / code / credential / cookie |
| `metadata` | JSONB | 附加元数据（language, acquired_at, expires_at） |
| `sort_order` | INTEGER | 同级排序 |
| `submitted_by` | TEXT | 提交者 |
| `created_at` | BIGINT | 创建时间戳 |
| `updated_at` | BIGINT | 更新时间戳 |

路径格式 ID 支持层级导航：根节点（无 `/`）为目录/概要，子节点（含 `/`）为具体内容。API 返回时自动计算 toc/children/prev/next 导航上下文。

加密：`secure_body` 使用 AES-256-GCM，密钥从环境变量 `ORG_KEY_{org}` 读取。加密格式：`encrypted:AES256-GCM:{base64}`。

---

## tool_table — 工具表

实现：`knowhub_db/pg_tool_store.py:PostgreSQLToolStore`

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | VARCHAR PK | 路径格式，如 `"tools/image_gen/midjourney"` |
| `name` | VARCHAR | 工具名称 |
| `version` | VARCHAR | 版本号 |
| `introduction` | TEXT | 功能介绍 |
| `tutorial` | TEXT | 使用指南 |
| `input` | JSONB | 输入规格 |
| `output` | JSONB | 输出规格 |
| `updated_time` | BIGINT | 更新时间戳 |
| `status` | VARCHAR | 未接入 / 可用 / 异常 |
| `capabilities` | JSONB | 关联的原子能力 ID 列表 → `atomic_capability.id` |
| `tool_knowledge` | JSONB | 工具知识 ID 列表 → `knowledge.id` |
| `case_knowledge` | JSONB | 用例知识 ID 列表 → `knowledge.id` |
| `process_knowledge` | JSONB | 工序知识 ID 列表 → `knowledge.id` |
| `embedding` | float4[] | name + introduction 的向量 |
| `implemented_tool_ids` | JSONB | 已实现的工具 ID 列表 |

---

## atomic_capability — 原子能力表

实现：`knowhub_db/pg_capability_store.py:PostgreSQLCapabilityStore`

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

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | VARCHAR PK | `"ac-image-gen-001"` |
| `name` | VARCHAR | 能力名称 |
| `criterion` | TEXT | 评估标准 |
| `description` | TEXT | 能力描述 |
| `requirements` | JSONB | 关联需求 ID 列表 → `requirement_table.id` |
| `implements` | JSONB | 工具实现映射 `{tool_name: 使用方式描述}` |
| `tools` | JSONB | 关联工具 ID 列表 → `tool_table.id` |
| `source_knowledge` | JSONB | 提炼自哪些知识 → `knowledge.id` |
| `embedding` | float4[] | name + description 的向量 |

---

## requirement_table — 需求表

实现：`knowhub_db/pg_requirement_store.py:PostgreSQLRequirementStore`

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | VARCHAR PK | `"req-001"` |
| `description` | TEXT | 需求描述 |
| `atomics` | JSONB | 关联的原子能力 ID 列表 → `atomic_capability.id` |
| `source_nodes` | JSONB | 来源节点 `[{node_name, posts}]` |
| `status` | VARCHAR | 已满足 / 未满足 |
| `match_result` | TEXT | 满足/不足的描述 |
| `embedding` | float4[] | description 的向量 |

---

## Embedding 策略

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