Agent/knowhub/docs/schema.md

数据模型

文档维护规范

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