# KnowHub API 参考

KnowHub 是一个 FastAPI 服务，提供知识图谱的存储、检索和管理能力。
基础地址由环境变量 `KNOWHUB_API` 控制，默认 `http://localhost:8000`。

FastAPI 自动生成的交互式文档：`{KNOWHUB_API}/docs`

---

## 数据模型

### Knowledge（知识）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 格式 `knowledge-{date}-{hash}`，自动生成 |
| `task` | string | 任务描述（在什么情景下要完成什么目标） |
| `content` | string | 核心内容 |
| `types` | string[] | 类型标签：`tool` / `strategy` / `case` / `experience` |
| `tags` | object | 业务标签，如 `{"project": "foo", "domain": "ai"}` |
| `scopes` | string[] | 可见范围，默认 `["org:cybertogether"]` |
| `owner` | string | 所有者，默认 `agent:{agent_id}` |
| `source` | object | `{name, category, urls, agent_id, submitted_by, timestamp}` |
| `eval` | object | `{score(1-5), helpful, harmful, confidence}` |
| `capability_ids` | string[] | 关联的能力 ID |
| `tool_ids` | string[] | 关联的工具 ID |
| `resource_ids` | string[] | 关联的资源 ID |
| `status` | string | `pending` / `processing` / `dedup_passed` / `analyzing` / `approved` / `checked` / `rejected` |

### Tool（工具）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 格式 `tools/{category}/{name}`，调用方指定 |
| `name` | string | 工具名称 |
| `version` | string | 版本号（可选） |
| `introduction` | string | 简介 |
| `tutorial` | string | 使用教程 |
| `input` | object/string | 输入格式描述 |
| `output` | object/string | 输出格式描述 |
| `status` | string | 默认 `未接入` |
| `capability_ids` | string[] | 关联的能力 ID |
| `knowledge_ids` | string[] | 关联的知识 ID |
| `provider_ids` | string[] | 关联的提供方 ID |

### Capability（原子能力）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 格式 `CAP-XXX`，调用方指定 |
| `name` | string | 能力名称 |
| `criterion` | string | 判断标准（何时认为该能力被满足） |
| `description` | string | 详细描述 |
| `requirement_ids` | string[] | 关联的需求 ID |
| `tool_ids` | string[] | 实现该能力的工具 ID |
| `implements` | object | `{tool_id: description}` 工具实现描述 |
| `knowledge_ids` | string[] | 关联的知识 ID |

### Requirement（需求）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 格式 `REQ_XXX`，调用方指定 |
| `description` | string | 需求描述 |
| `capability_ids` | string[] | 满足该需求的能力 ID |
| `knowledge_ids` | string[] | 关联的知识 ID |
| `source_nodes` | object[] | 分类树节点 `[{id, score}]` |
| `status` | string | 默认 `未满足` |
| `match_result` | string | 匹配结果说明 |

### Resource（资源）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 路径格式，如 `docs/foo/bar` |
| `title` | string | 标题 |
| `body` | string | 正文内容 |
| `secure_body` | string | 加密内容（AES256-GCM） |
| `content_type` | string | 默认 `text` |
| `metadata` | object | 自定义元数据 |

---

## Knowledge API

### 智能查询（Librarian Agent）

#### `POST /api/knowledge/ask`

同步阻塞。触发 Librarian Agent 跨表检索 + LLM 整合，返回带引用的回答。
同一 `trace_id` 的多次调用复用同一个 Librarian trace，积累上下文。

```json
// 请求
{
  "query": "有没有工具能做角色一致性生成？",
  "trace_id": "trace-abc123"
}

// 响应
{
  "response": "根据知识库，ControlNet 可以...",
  "source_ids": ["knowledge-20260101-abcd"],
  "sources": []
}
```

#### `POST /api/knowledge/upload` → 202

异步。校验后立即返回，后台 Librarian Agent 处理去重、关联、写草稿池。

```json
// 请求
{
  "data": {
    "knowledge": [...],
    "tools": [...],
    "resources": [...]
  },
  "trace_id": "trace-abc123",
  "finalize": false
}

// 响应 202
{
  "message": "已接收 知识: 2 个，Librarian Agent 后台处理中",
  "buffer_file": ".cache/.knowledge/buffer/upload_20260101_120000.json"
}
```

#### `GET /api/knowledge/upload/pending`

列出所有未处理或失败的 upload 任务。

#### `POST /api/knowledge/upload/retry`

重跑所有 `status=failed` 的 upload 任务。

---

### 向量检索

#### `GET /api/knowledge/search`

向量召回 + LLM 精排。

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `q` | string | 必填 | 查询文本 |
| `top_k` | int | 5 | 返回条数（1-20） |
| `min_score` | int | 3 | 最低评分过滤（1-5） |
| `types` | string | - | 逗号分隔，如 `tool,case` |
| `owner` | string | - | 逗号分隔，过滤 owner |

```json
// 响应
{
  "results": [{"id": "...", "task": "...", "content": "...", "score": 0.92, ...}],
  "count": 3
}
```

---

### CRUD

#### `POST /api/knowledge` → 201

创建知识，进入 `pending` 状态，自动触发去重流水线。

```json
{
  "task": "使用 ControlNet 进行姿态控制",
  "content": "...",
  "types": ["tool"],
  "tags": {"project": "image_gen"},
  "source": {"agent_id": "research_agent", "category": "research"},
  "eval": {"score": 4}
}
// 响应: {"status": "pending", "knowledge_id": "knowledge-20260101-abcd"}
```

#### `GET /api/knowledge`

列出知识，支持分页和过滤。

| 参数 | 说明 |
|------|------|
| `page` / `page_size` | 分页，默认 1/20 |
| `types` | 逗号分隔类型过滤 |
| `scopes` | 逗号分隔范围过滤 |
| `owner` | owner 过滤 |
| `tags` | JSON 字符串，如 `{"project":"foo"}` |
| `status` | 状态过滤 |

#### `GET /api/knowledge/{knowledge_id}`

获取单条知识详情。

#### `GET /api/knowledge/status/{knowledge_id}`

查询知识处理状态（`pending` / `approved` 等）。

#### `PUT /api/knowledge/{knowledge_id}`

更新知识评估，支持知识进化（LLM 重写 content）。

```json
{
  "update_score": 5,
  "add_helpful_case": {"context": "...", "result": "success"},
  "add_harmful_case": null,
  "evolve_feedback": "内容需要补充 batch 处理的情况"
}
```

#### `PATCH /api/knowledge/{knowledge_id}`

直接编辑字段（task、content、types、tags、scopes、owner、capability_ids、tool_ids）。

#### `DELETE /api/knowledge/{knowledge_id}`

删除单条知识（级联清理关联表）。

#### `POST /api/knowledge/batch_delete`

批量删除。请求体为 `["knowledge-xxx", "knowledge-yyy"]`。

---

### 审核与验证

#### `POST /api/knowledge/{knowledge_id}/verify`

```json
// approve：approved ↔ checked 切换；reject：→ rejected
{"action": "approve", "verified_by": "howard"}
```

#### `POST /api/knowledge/batch_verify`

```json
{"knowledge_ids": ["knowledge-xxx"], "action": "approve", "verified_by": "howard"}
```

---

### 运维工具

#### `GET /api/knowledge/pending`

查询处理队列（`pending` / `processing` / `dedup_passed` / `analyzing`）。

#### `POST /api/knowledge/process`

手动触发去重处理。`force=true` 时先回滚所有超时锁。

#### `GET /api/knowledge/meta/tags`

获取所有已使用的 tag keys。

#### `POST /api/knowledge/slim`

知识库瘦身：LLM 分析全库，合并语义相似条目。
可选参数 `model`，默认 `google/gemini-2.5-flash-lite`。

#### `POST /api/knowledge/batch_update`

批量反馈知识有效性。

#### `POST /api/extract`

从消息历史中 LLM 提取知识并入库。

```json
{
  "messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}],
  "agent_id": "research_agent",
  "submitted_by": "howard@example.com",
  "session_key": ""
}
```

---

## Tool API

#### `POST /api/tool` → 201

创建或更新工具（id 相同则覆盖，同时全量替换关联表）。

```json
{
  "id": "tools/image/controlnet",
  "name": "ControlNet",
  "introduction": "基于条件控制的图像生成工具",
  "tutorial": "...",
  "status": "已接入",
  "capability_ids": ["CAP-001"],
  "knowledge_ids": ["knowledge-20260101-abcd"]
}
```

#### `GET /api/tool`

列出工具。参数：`status`、`limit`（默认100）、`offset`。

#### `GET /api/tool/search?q=...&top_k=5`

向量检索工具。

#### `GET /api/tool/{tool_id}`

获取单个工具详情（含关联的 capability_ids、knowledge_ids）。

#### `PATCH /api/tool/{tool_id}`

部分更新工具字段。

#### `DELETE /api/tool/{tool_id}`

删除工具（级联清理关联表）。

---

## Capability API

#### `POST /api/capability` → 201

创建或更新原子能力。

```json
{
  "id": "CAP-001",
  "name": "人物姿态控制生成",
  "criterion": "能根据骨骼图生成指定姿态的人物图像",
  "description": "...",
  "tool_ids": ["tools/image/controlnet"],
  "implements": {"tools/image/controlnet": "使用 openpose 模型控制姿态"}
}
```

#### `GET /api/capability`

列出所有能力。参数：`limit`、`offset`。

#### `GET /api/capability/search?q=...&top_k=5`

向量检索能力。

#### `GET /api/capability/{cap_id}`

获取单个能力详情。

#### `PATCH /api/capability/{cap_id}`

部分更新能力字段。

#### `DELETE /api/capability/{cap_id}`

删除能力（级联清理关联表）。

---

## Requirement API

#### `POST /api/requirement` → 201

创建或更新需求。

```json
{
  "id": "REQ_001",
  "description": "需要能生成角色一致的多视角图像",
  "capability_ids": ["CAP-001"],
  "source_nodes": [{"id": "image_generation", "score": 0.9}],
  "status": "已满足"
}
```

#### `GET /api/requirement`

列出需求。参数：`status`、`limit`、`offset`。

#### `GET /api/requirement/search?q=...&top_k=5`

向量检索需求。

#### `GET /api/requirement/{req_id}`

获取单个需求详情。

#### `PATCH /api/requirement/{req_id}`

部分更新需求字段。

#### `DELETE /api/requirement/{req_id}`

删除需求（级联清理关联表）。

---

## Resource API

Resource 存储原始资料文档，通过 `knowledge_resource` 关联表与 Knowledge 关联。

#### `POST /api/resource` → 201

创建或更新资源。

#### `GET /api/resource`

列出资源（树形结构）。

#### `GET /api/resource/{resource_id}`

获取单个资源（含 toc、children、prev/next 导航）。

#### `PATCH /api/resource/{resource_id}`

部分更新资源字段。

#### `DELETE /api/resource/{resource_id}`

删除资源。

---

## 关联表说明

所有实体间的关系通过 junction table 维护，写入时**全量替换**（DELETE + INSERT）：

| 关联表 | 连接 |
|--------|------|
| `capability_tool` | Capability ↔ Tool |
| `capability_knowledge` | Capability ↔ Knowledge |
| `requirement_capability` | Requirement ↔ Capability |
| `requirement_knowledge` | Requirement ↔ Knowledge |
| `tool_knowledge` | Tool ↔ Knowledge |
| `tool_provider` | Tool ↔ Provider |
| `knowledge_resource` | Knowledge ↔ Resource |
| `knowledge_relation` | Knowledge → Knowledge（supplement/duplicate） |

查询任意实体时，关联 ID 通过子查询自动聚合返回（`capability_ids`、`tool_ids` 等字段）。