数据模型

文档维护规范

先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
文档分层，链接代码 - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：module/file.py:function_name
简洁快照，日志分离 - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议、决策历史、修改日志、大量代码；决策依据或修改日志若有必要，可在 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 ──── requirement_strategy ──── strategy
            ╱     ╲   ╲                                 ╱  │  ╲
  capability_ids  knowledge_ids  resource_ids   capability │  knowledge / resource
           ╱              ╲         ╲                      compose
     capability          knowledge ← knowledge_resource → resource
         │  ╲              ╱  ╲                            ↑
         │  tool_ids  knowledge_ids  knowledge_relation    │
         │     ╲         ╱            (知识间关系)          │
         │      tool    ...          ← capability_resource ┤
    capability_resource                ← requirement_resource
                                       ← strategy_resource
                     tool_provider (执行层索引)

所有 *_knowledge / knowledge_relation / strategy_capability / strategy_knowledge 边带 relation_type 语义标签：

source — 知识/资料是该实体的构建来源
case — 知识是该实体的应用实例
compose — 组合关系（strategy → capability）
related — 默认/未分类

实体表（6）

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 扁平列表 + {entity}_links 带 relation_type）：

requirement_ids / requirement_links ← requirement_knowledge
capability_ids / capability_links ← capability_knowledge
tool_ids / tool_links ← 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 / knowledge_links ← requirement_knowledge
resource_ids ← requirement_resource
strategy_ids ← requirement_strategy（满足该需求的 strategy）

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 / knowledge_links ← capability_knowledge
resource_ids ← capability_resource

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 / knowledge_links ← tool_knowledge
provider_ids ← tool_provider

strategy — 制作策略表

一组原子 capability 的组合，附带自身的可执行 body（如工作流脚本、流程描述）与 source 知识。strategy 设计用来满足 requirement。

字段	类型	说明
`id`	VARCHAR PK	`"strategy-{...}"`
`name`	VARCHAR	策略名称
`description`	TEXT	策略描述
`body`	TEXT	可执行正文（工作流/脚本/流程步骤）
`status`	VARCHAR	draft / approved / deprecated 等
`created_at`	BIGINT	创建时间戳（秒）
`updated_at`	BIGINT	更新时间戳（秒）
`embedding`	float4[]	name + description 的向量

关联：

requirement_ids ← requirement_strategy（这个 strategy 被设计用来满足哪些 requirement）
capability_ids / capability_links ← strategy_capability（compose 组合）
knowledge_ids / knowledge_links ← strategy_knowledge（source / case 等）
resource_ids ← strategy_resource（直接原始素材）

关联表（14）

实体链（3）

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)

requirement_strategy — 需求由 strategy 满足

字段	类型	说明
`requirement_id`	VARCHAR	→ requirement.id
`strategy_id`	VARCHAR	→ strategy.id

PK: (requirement_id, strategy_id)

知识链（4）

所有 *_knowledge 表及 strategy_knowledge 都带 relation_type VARCHAR(32) 列，值 ∈ {source, case, related}。DEFAULT 'related'（历史数据）。

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

字段	类型	说明
`requirement_id`	VARCHAR	→ requirement.id
`knowledge_id`	VARCHAR	→ knowledge.id
`relation_type`	VARCHAR(32)	source / case / related（默认）

PK: (requirement_id, knowledge_id)

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

字段	类型	说明
`capability_id`	VARCHAR	→ capability.id
`knowledge_id`	VARCHAR	→ knowledge.id
`relation_type`	VARCHAR(32)	source / case / related（默认）

PK: (capability_id, knowledge_id)

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

字段	类型	说明
`tool_id`	VARCHAR	→ tool.id
`knowledge_id`	VARCHAR	→ knowledge.id
`relation_type`	VARCHAR(32)	source / case / related（默认）

PK: (tool_id, knowledge_id)

strategy_knowledge — strategy 的知识来源

字段	类型	说明
`strategy_id`	VARCHAR	→ strategy.id
`knowledge_id`	VARCHAR	→ knowledge.id
`relation_type`	VARCHAR(32)	默认 `source`；可为 `case` 等

PK: (strategy_id, knowledge_id)

组合关系（1）

strategy_capability — strategy 组合哪些原子能力

字段	类型	说明
`strategy_id`	VARCHAR	→ strategy.id
`capability_id`	VARCHAR	→ capability.id
`relation_type`	VARCHAR(32)	默认 `compose`

PK: (strategy_id, capability_id)

来源链（5）

knowledge_resource — 知识的原始来源

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

PK: (knowledge_id, resource_id)

requirement_resource — 需求直接来自的原始素材（绕过 knowledge 整理层）

PK: (requirement_id, resource_id)

capability_resource — capability 直接来自的原始素材

PK: (capability_id, resource_id)

strategy_resource — strategy 直接来自的原始素材

PK: (strategy_id, resource_id)

*_resource 边无 relation_type——存在本身即"source"语义，不需额外标签。

知识间关系（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
strategy	`embedding`	name + description

schema.md 12 KB Histórico Raw