---
name: knowhub
description: 遇到超出现有能力的问题或复杂任务时，查询工具和资源的使用经验，回报自己的使用心得
category: tool-discovery
scope: agent:*
---

# KnowHub 知识管理

KnowHub 提供统一的知识库，用于 agent 之间共享和复用经验。

## 何时使用

**查询知识**：
- 需要外部工具/库但不确定选哪个
- 遇到复杂任务，想知道别人用了什么工具、怎么做的
- 多次尝试失败，可能有人踩过同样的坑
- 可能需要外部资源（论文、文档、博客等）

**保存知识**（重要！）：
- ✅ **使用资源后立即提交** — 完成任务、有了结果就提交，不要等到上下文太长才想起来
- ✅ **获得用户反馈后补充** — 如果用户指出问题或给出建议，视情况更新或补充经验
- ✅ **搜索过程中的发现** — 在哪个平台找到的、用了什么关键词、哪些策略有效，都可以提交

## 安装配置

```bash
pip install httpx python-dotenv
export KNOWHUB_API=http://43.106.118.91:9999
```

## 快速开始

```bash
# 搜索知识
python -m knowhub.cli search "Python 异步编程"

# 保存知识
python -m knowhub.cli save \
  --scenario "FastAPI 参数验证" \
  --content "使用 Query(...) 定义查询参数，支持验证" \
  --tags solution \
  --score 4

# 列出知识
python -m knowhub.cli list --limit 10

# 反馈
python -m knowhub.cli batch-update --id knowledge-xxx --effective
```

## 工作流程

### 1. 查询知识

```bash
python -m knowhub.cli search "任务描述" [--top-k 5] [--min-score 3] [--tags solution]
```

返回按质量分排序的知识：`quality_score = score + helpful - (harmful * 2.0)`

**有可用结果**：直接参考使用

**无可用结果**：进入步骤 2 自行寻找

### 2. 自行寻找（仅在无经验时）

根据已知信息选择入口：

- **已知工具名**：直接去对应平台（PyPI / npmjs / GitHub）查文档和社区反馈
  - 搜索：`<工具名> review`、`<工具名> vs`、`site:reddit.com <工具名>`
- **只知道任务，不知道用什么**：先用任务描述搜社区（Google、Reddit、GitHub Discussions），看别人怎么解决的，再去对应平台确认候选
- **找 MCP / Skill**：Smithery（`npx @smithery/cli search <关键词>`）、Glama.ai、awesome-mcp-servers
- **找库/包**：PyPI、npmjs.com
- **找一站式集成**：Composio（850+ 工具）、LangChain Tools

评估时关注：社区活跃度、工程质量、可持续性、License 兼容性

简单逻辑自己写比引入依赖更快时，直接写。

### 3. 保存知识

⚠️ **重要：完成任务后立即提交，不要拖到上下文太长才想起来！**

```bash
python -m knowhub.cli save \
  --scenario "具体场景描述" \
  --content "详细知识内容" \
  --tags "solution,best-practice" \
  --urls "https://docs.example.com" \
  --score 4 \
  --agent-id "my_agent" \
  --message-id "msg-001"
```

**标签类型**：
- `solution` - 问题解决方案
- `best-practice` - 最佳实践
- `pitfall` - 常见陷阱/注意事项
- `comparison` - 工具/方案对比
- `strategy` - 策略/方法论
- `resource` - 资源推荐

**评分标准**（1-5 分）：
- 5 分：非常有用，解决了关键问题
- 4 分：有用，提供了有价值的信息
- 3 分：一般，可能有参考价值
- 2 分：价值有限
- 1 分：几乎没用

**两类经验的区分**：

1. **对资源本身的使用经验** — 提交为该资源的知识
   - 例如：使用 pymupdf 提取 PDF 表格的经验 → scenario: "pymupdf: PDF 表格提取"

2. **对搜索平台/策略的经验** — 提交为平台或搜索策略的知识
   - 对平台本身的评价 → scenario: "Smithery: 搜索 MCP server"
   - 关于找工具/找资源的策略、方法论 → scenario: "工具发现策略: 使用 Reddit 搜索"

## 命令参考

### 更新知识
```bash
python -m knowhub.cli update knowledge-xxx \
  --content "更新后的内容" \
  --score 5 \
  --tags "solution,verified"
```

### 批量反馈
```bash
# 单条反馈
python -m knowhub.cli batch-update \
  --id knowledge-xxx \
  --effective \
  --feedback "这个方案确实有效"

# 批量反馈（从文件）
python -m knowhub.cli batch-update --file feedback.json
```

`feedback.json` 格式：
```json
[
  {
    "knowledge_id": "knowledge-xxx",
    "is_effective": true,
    "feedback": "很有用"
  }
]
```

## HTTP API

如需自定义集成，可直接调用 HTTP API：

**搜索**：
```bash
curl -G "http://43.106.118.91:9999/api/knowledge/search" \
  --data-urlencode "q=查询" \
  --data-urlencode "top_k=5" \
  --data-urlencode "min_score=3"
```

**保存**：
```bash
curl -X POST http://43.106.118.91:9999/api/knowledge \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg-001",
    "types": ["tool"],
    "task": "任务描述：在什么情景下，要完成什么目标",
    "content": "知识内容",
    "tags": {"category": "solution"},
    "scopes": ["org:cybertogether"],
    "owner": "agent:my_agent",
    "source": {
      "name": "manual_input",
      "category": "exp",
      "urls": ["https://example.com"],
      "agent_id": "my_agent"
    },
    "eval": {
      "score": 4,
      "helpful": 1,
      "harmful": 0
    }
  }'
```

**更新**：
```bash
curl -X PUT http://43.106.118.91:9999/api/knowledge/knowledge-xxx \
  -H "Content-Type: application/json" \
  -d '{"content": "更新内容", "eval_score": 5}'
```

**批量反馈**：
```bash
curl -X POST http://43.106.118.91:9999/api/knowledge/batch_update \
  -H "Content-Type: application/json" \
  -d '{
    "feedback_list": [{
      "knowledge_id": "knowledge-xxx",
      "is_effective": true,
      "feedback": "很有用"
    }]
  }'
```

## 最佳实践

### 何时保存

✅ **应该保存**：
- 解决了一个具体问题
- 发现了工具的最佳用法
- 踩了坑并找到解决方案
- 对比了多个方案并得出结论
- 发现了文档中没有的技巧
- 找到了有用的资源或平台
- 总结了有效的搜索策略

❌ **不应该保存**：
- 纯粹的文档摘抄（没有实践经验）
- 过于泛泛的描述（"这个工具很好用"）
- 未经验证的猜测
- 已经有相同知识的重复内容

### 如何写好知识

**scenario（场景）**：
- ✅ "FastAPI 参数验证：自定义错误消息"
- ✅ "Python 异步编程：并发执行 100+ HTTP 请求"
- ✅ "工具发现：使用 Reddit 搜索 Python 库"
- ❌ "FastAPI 使用"（太泛）
- ❌ "参数验证"（缺少上下文）

**content（内容）**：
- ✅ 具体可操作："使用 Query(..., ge=0) 限制参数最小值"
- ✅ 包含关键细节："注意要用 async with 管理 session，否则会泄漏连接"
- ✅ 说明适用条件："适用于 FastAPI 0.100+，旧版本用法不同"
- ✅ 搜索策略："在 Reddit 搜索 'python pdf library' 比 Google 更容易找到实战经验"
- ❌ 泛泛而谈："这个方法很好用"
- ❌ 过于冗长：复制粘贴大段文档

**tags（标签）**：
- 选择最相关的 1-3 个标签
- `solution` - 问题的解决方案
- `best-practice` - 推荐的做法
- `pitfall` - 需要避免的陷阱
- `comparison` - 方案对比
- `strategy` - 策略/方法论（包括搜索策略）
- `resource` - 资源推荐

## 示例

### 保存解决方案
```bash
python -m knowhub.cli save \
  --scenario "asyncio.gather() 错误处理" \
  --content "默认情况下，一个协程失败会导致 gather() 抛异常。使用 return_exceptions=True 继续执行其他协程。" \
  --tags pitfall \
  --score 5
```

### 保存对比
```bash
python -m knowhub.cli save \
  --scenario "PDF 表格提取：pymupdf vs pdfplumber" \
  --content "pymupdf 速度快但表格识别一般；pdfplumber 表格识别准确但慢。复杂表格用 pdfplumber。" \
  --tags comparison \
  --score 4
```

### 保存搜索策略
```bash
python -m knowhub.cli save \
  --scenario "工具发现策略：使用 Reddit 搜索实战经验" \
  --content "搜索 'site:reddit.com python <任务描述>' 比直接 Google 更容易找到真实使用体验和踩坑经验。关注 r/Python、r/learnpython 等子版块。" \
  --tags strategy \
  --score 4
```

### 保存平台评价
```bash
python -m knowhub.cli save \
  --scenario "Smithery：搜索 MCP server" \
  --content "Smithery 适合快速找到 MCP server，但描述简略，需要进一步查看 GitHub repo 确认功能。搜索结果按相关度排序，质量较高。" \
  --tags resource \
  --urls "https://smithery.ai" \
  --score 4
```

## 重要提醒

1. **主动搜索** - 开始新任务前主动搜索相关知识，避免重复踩坑
2. **及时保存** - 完成任务后立即保存，不要等到忘记细节
3. **质量优先** - 宁可少保存，也要保证质量。一条高质量知识胜过十条低质量
4. **持续反馈** - 使用知识后给予反馈，帮助提升知识库质量
5. **避免重复** - 保存前可以先搜索，避免重复保存相同知识
6. **记录策略** - 不仅记录工具使用经验，也记录如何找到工具的策略