# KnowHub

## 文档维护规范

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

---

## 文档索引

### 代码快照（与代码一致）

| 文档 | 内容 |
|------|------|
| [数据模型](docs/schema.md) | 13张表（5实体+8关联）、字段定义、向量策略 |
| [REST API](docs/api.md) | API 端点参考 |
| [Librarian Agent](docs/librarian-agent.md) | 知识管理 Agent 架构和接口 |
| [知识处理流水线](docs/processing-pipeline.md) | 去重、工具关联分析、状态流转 |
| [DB层](knowhub_db/README.md) | 数据库访问层封装类和运维脚本 |

### 方案文档（`*-plan.md`，未实现）

| 文档 | 内容 |
|------|------|
| [Schema 迁移](docs/schema-migration-plan.md) | JSONB 软关联 → 关联表 |
| [Cognition Log](../agent/docs/cognition-log-plan.md) | Agent 侧认知日志事件流（在 agent/docs/ 中） |
| [前端重构](docs/frontend-restructure-plan.md) | 原子能力为中心的前端重构 |
| [Dashboard](docs/dashboard-plan.md) | 知识库可视化 Dashboard |
| [用户反馈](docs/user-feedback-plan.md) | 用户反馈 UI、API、数据模型 |

### 其他

| 文档 | 内容 |
|------|------|
| [决策记录](docs/decisions.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调用指南
```

---

## 环境变量

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

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