KnowHub
文档维护规范
- 先改文档，再动代码 - 新功能或重大修改需先完成文档更新、并完成审阅后，再进行代码实现；除非改动较小、不被文档涵盖
- 文档分层，链接代码 - 重要或复杂设计可以另有详细文档；关键实现需标注代码文件路径；格式：
module/file.py:function_name
- 简洁快照，日志分离 - 只记录最重要的、与代码准确对应的或者明确的已完成的设计的信息，避免推测、建议、决策历史、修改日志、大量代码；决策依据或修改日志若有必要，可在
docs/decisions.md 另行记录
定位
Agent 集体记忆平台。收集和检索 Agent 的真实使用经验，覆盖工具、知识资源等各类资源。
核心原则：
- 汇总不同 Agent 的真实使用经验（Agent 版大众点评）
- 端侧 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, resource, tool, capability, requirement（5 实体表）
└── 8 张关联表（详见 schema.md）
文档索引
代码快照（与代码一致）
方案文档（*-plan.md，未实现）
其他
项目结构
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）
