Agent/knowhub/docs/schema.md

数据模型

文档维护规范

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

---

存储架构

PostgreSQL (阿里云 AnalyticDB for PostgreSQL)。所有向量字段为 float4[]（1536维），使用余弦距离（<=>）检索。

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

数据库名：knowhub

---

设计原则

• knowledge 是基础层，其余实体是组织/提炼知识的维度
• 每个维度的目标是收敛到最优知识，不是关联尽可能多的知识
• 实体字段（description、criterion、match_result）是提炼结果，知识链是提炼来源——两者都需要
• 所有实体间关系通过关联表存储，不使用 JSONB 数组软关联
• 工具库和知识库共用同一套工具 ID，不做 ID 映射
• Provider（运行环境）不作为知识库实体，由执行 Agent（Craftsman）内部管理；tool_provider 仅提供工具可用性索引

---

表间关系

           requirement
          ╱           ╲
 capability_ids    knowledge_ids
        ╱                 ╲
  capability            knowledge ← knowledge_resource → resource
        ╲                 ╱  ╲
     tool_ids      knowledge_ids  knowledge_relation
        ╲            ╱              (知识间关系)
         tool
          |
    tool_provider (执行层索引)

---

实体表（5）

knowledge — 知识表

基础层。用例、方法、经验、评论都是 knowledge。

字段	类型	说明
id	VARCHAR PK	"knowledge-{timestamp}-{random}"
task_embedding	float4[]	task 的向量
content_embedding	float4[]	content 的向量
message_id	VARCHAR	来源 Agent 消息 ID
task	VARCHAR	任务场景描述
content	TEXT	知识正文
types	TEXT[]	知识类型：tool / strategy / case / experience / definition
tags	JSONB	标签键值对
tag_keys	TEXT[]	tags 中的键列表（用于过滤）
scopes	TEXT[]	作用域，如 ["org:cybertogether"]
owner	VARCHAR	所有者
source	JSONB	来源信息（agent_id, category, urls, submitted_by, timestamp）
eval	JSONB	评估（score, helpful, harmful, confidence）
created_at	BIGINT	创建时间戳（秒）
updated_at	BIGINT	更新时间戳（秒）
status	VARCHAR	pending → approved / rejected / checked

关联（通过关联表，API 返回时聚合为 {entity}_ids）：

• requirement_ids ← requirement_knowledge
• capability_ids ← capability_knowledge
• tool_ids ← tool_knowledge
• resource_ids ← knowledge_resource
• relations ← knowledge_relation

resource — 资源表

知识的原始来源。文档、代码、凭证等。

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

requirement — 需求表

业务目标。分解为能力的组合，以保持稳定性。

字段	类型	说明
id	VARCHAR PK	"REQ_XXX"
description	TEXT	需求描述
source_nodes	JSONB	来源节点 [{node_name, posts}]
status	VARCHAR	已满足 / 未满足
match_result	TEXT	满足方案描述（提炼结果）
embedding	float4[]	description 的向量

关联：

• capability_ids ← requirement_capability
• knowledge_ids ← requirement_knowledge

capability — 原子能力表

需求的稳定分解锚点。从知识中提炼，连接需求与工具。

字段	类型	说明
id	VARCHAR PK	"CAP-XXX"
name	VARCHAR	能力名称
criterion	TEXT	评估标准（提炼结果）
description	TEXT	能力描述（提炼结果）
embedding	float4[]	name + description 的向量

关联：

• requirement_ids ← requirement_capability
• tool_ids ← capability_tool
• knowledge_ids ← capability_knowledge

tool — 工具表

具体的技术/模型/软件。工具库和知识库共用同一套 ID。

字段	类型	说明
id	VARCHAR PK	路径格式，如 "tools/image_gen/controlnet_openpose"
name	VARCHAR	工具名称
version	VARCHAR	版本号
introduction	TEXT	功能介绍
tutorial	TEXT	使用指南
input	JSONB	输入规格
output	JSONB	输出规格
updated_time	BIGINT	更新时间戳
status	VARCHAR	未接入 / 可用 / 异常
embedding	float4[]	name + introduction 的向量

关联：

• capability_ids ← capability_tool
• knowledge_ids ← tool_knowledge
• provider_ids ← tool_provider

---

关联表（8）

实体链（2）

requirement_capability — 需求分解为能力

字段	类型	说明
requirement_id	VARCHAR	→ requirement.id
capability_id	VARCHAR	→ capability.id

PK: (requirement_id, capability_id)

capability_tool — 能力由工具实现

字段	类型	说明
capability_id	VARCHAR	→ capability.id
tool_id	VARCHAR	→ tool.id
description	TEXT	该工具如何实现此能力

PK: (capability_id, tool_id)

知识链（3）

requirement_knowledge — 需求的方案策略、完成方法

字段	类型	说明
requirement_id	VARCHAR	→ requirement.id
knowledge_id	VARCHAR	→ knowledge.id

PK: (requirement_id, knowledge_id)

capability_knowledge — 能力的原理依据、评判来源

字段	类型	说明
capability_id	VARCHAR	→ capability.id
knowledge_id	VARCHAR	→ knowledge.id

PK: (capability_id, knowledge_id)

tool_knowledge — 工具的用法、案例、经验

字段	类型	说明
tool_id	VARCHAR	→ tool.id
knowledge_id	VARCHAR	→ knowledge.id

PK: (tool_id, knowledge_id)

来源链（1）

knowledge_resource — 知识的原始来源

字段	类型	说明
knowledge_id	VARCHAR	→ knowledge.id
resource_id	VARCHAR	→ resource.id

PK: (knowledge_id, resource_id)

知识间关系（1）

knowledge_relation — 知识之间的关系（替代、扩展、矛盾等）

字段	类型	说明
source_id	VARCHAR	→ knowledge.id
target_id	VARCHAR	→ knowledge.id
relation_type	VARCHAR	supersedes / extends / contradicts / ...

PK: (source_id, target_id, relation_type)

执行层索引（1）

tool_provider — 工具在哪些运行环境可用（供 Craftsman 查询）

字段	类型	说明
tool_id	VARCHAR	→ tool.id
provider_id	VARCHAR	运行环境标识（如 "comfyui"、"liblib"）

PK: (tool_id, provider_id)

---

Embedding 策略

表	向量字段	Embedding 内容
knowledge	task_embedding	task
knowledge	content_embedding	content
tool	embedding	name + introduction
capability	embedding	name + description
requirement	embedding	description