Agent/knowhub

KnowHub

文档维护规范

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

---

定位

Agent 集体记忆平台。收集和检索 Agent 的真实使用经验，覆盖工具、知识资源等各类资源。

核心原则：

1. 汇总不同 Agent 的真实使用经验（Agent 版大众点评）
2. 端侧 Agent 负责搜索、评估、总结、提取内容；Server 做存取、去重和简单聚合

---

架构

Agent（端侧）
├── ask_knowledge 工具     →  POST /api/knowledge/ask（设计中，未实现）
├── upload_knowledge 工具  →  POST /api/knowledge/upload（设计中，未实现）
├── knowledge_search 工具  →  GET /api/knowledge/search（当前实现）
├── knowledge_save 工具    →  POST /api/knowledge（当前实现）
├── goal focus 自动注入    →  GET /api/knowledge/search（当前实现）
└── resource 资源引用       →  GET /api/resource/{id}
                                    │
                              KnowHub Server（FastAPI）
                              ├── REST API（36个端点）
                              ├── 知识处理流水线（去重 + 工具关联分析）
                              └── Librarian Agent（知识管理Agent，当前通过IM独立运行）
                                    │
                              PostgreSQL + pgvector
                              ├── knowledge（知识表，双向量）
                              ├── resources（资源表，加密存储）
                              ├── tool_table（工具表）
                              ├── atomic_capability（原子能力表）
                              └── requirement_table（需求表）

---

文档索引

核心设计

文档	内容
数据模型	5张表结构、字段定义、表间关联、向量策略
REST API	36个API端点的完整参考
Librarian Agent	知识管理Agent：当前IM架构 + 未来HTTP ask/upload设计

处理机制

文档	内容
知识处理流水线	去重、工具关联分析、状态流转、LLM关系判断
Cognition Log	Agent侧的认知日志：查询/评估/提取/反思事件流（在 agent/docs/ 中）

前端与用户交互

文档	内容
用户反馈设计	用户反馈UI、API、数据模型
Dashboard设计	知识库可视化Dashboard

其他

文档	内容
决策记录	设计决策的依据和权衡
DB层README	数据库访问层的封装类和运维脚本

---

项目结构

knowhub/
├── server.py              # FastAPI Server（API + 知识处理流水线）
├── embeddings.py          # Embedding 生成（OpenRouter）
├── kb_manage_prompts.py   # LLM Prompt（去重判断、工具分析）
├── agents/                # Librarian Agent（独立进程）
├── knowhub_db/            # PostgreSQL 数据库访问层
│   ├── pg_store.py        # knowledge 表
│   ├── pg_resource_store.py
│   ├── pg_tool_store.py
│   ├── pg_capability_store.py
│   ├── pg_requirement_store.py
│   └── *.py               # 迁移和运维脚本
├── frontend/              # 管理前端
├── docs/                  # 设计文档
└── skill/                 # Agent调用指南

---

环境变量

# 数据库
KNOWHUB_DB          # PostgreSQL 主机
KNOWHUB_PORT        # 端口（默认 5432）
KNOWHUB_USER        # 用户名
KNOWHUB_PASSWORD    # 密码
KNOWHUB_DB_NAME     # 数据库名

# Embedding
OPENROUTER_API_KEY  # OpenRouter API Key（用于生成 embedding）