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

## When to use

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

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

## 工作流

### 1. 查经验

```bash
curl -s "http://localhost:8000/api/search?q=关键词"
```

**有可用结果**：直接参考。结果包含资源名、URL、评分和具体使用建议。

**需要深入**：结果中如果有 `content_id`，可以获取详细内容：

```bash
curl -s "http://localhost:8000/api/content/{content_id}"
```

返回内容正文 + 导航（children / prev / next），可以继续浏览相关章节。

**无可用结果**：进入步骤 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
curl -s -X POST "http://localhost:8000/api/experience" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "资源名称",
    "url": "来源URL",
    "category": "mcp|skill|library|api|paper|blog|book|course",
    "task": "你在做什么（具体场景）",
    "score": 4,
    "outcome": "结果如何，优缺点",
    "tips": "最关键的一条建议",
    "submitted_by": "'$(git config user.email)'"
  }'
```

**提交时机**：
- ✅ 使用资源完成任务后，有了结果就提交
- ✅ 如果后续获得用户反馈（指出问题、给出建议），视情况再提交一条补充经验

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

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

2. **对搜索平台/策略的经验** — 提交为平台的 experience 或 knowhub 的 experience
   - 对平台本身的评价 → 提交为该平台的经验（`name: "smithery"` / `"pypi"` / `"github-search"`）
   - 关于找工具/找资源的策略、方法论 → 提交为 knowhub 的经验（`name: "knowhub"`）

**搜索策略经验示例**：

```bash
# 对搜索平台的评价
curl -s -X POST "http://localhost:8000/api/experience" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "smithery",
    "url": "https://smithery.ai",
    "category": "search-platform",
    "task": "寻找文件系统操作的 MCP server",
    "score": 4,
    "outcome": "搜索 filesystem 找到 3 个 server，但描述简略，需要进一步查看 GitHub repo",
    "tips": "Smithery 适合找 MCP server，但需要结合 GitHub 文档确认功能",
    "submitted_by": "'$(git config user.email)'"
  }'

# 关于搜索策略的经验
curl -s -X POST "http://localhost:8000/api/experience" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "knowhub",
    "url": "http://localhost:8000",
    "category": "search-platform",
    "task": "寻找 PDF 表格提取的 Python 库",
    "score": 5,
    "outcome": "搜索 pdf extract table python 直接找到 pymupdf 的高分经验，节省了大量调研时间",
    "tips": "关键词要包含具体操作动词（extract/parse）+ 目标对象（table）+ 技术栈（python）",
    "submitted_by": "'$(git config user.email)'"
  }'
```

**字段填写要求**：
- **name** — 资源的通用名称。工具填包名（`pymupdf`），论文填标题（`Attention Is All You Need`），博客填文章标题
- **url** — 资源的规范来源地址（GitHub repo / arXiv / 官方文档）
- **category** — 资源类型，建议用：`mcp | skill | library | api | paper | blog | book | course`
- **task** — 描述具体场景，不要写泛泛的"处理 PDF"
- **tips** — 要具体可操作："双栏论文用 page.get_text(sort=True)"，不要写"挺好用的"
- **submitted_by** — 可选，建议用 `git config user.email`

**多资源协作场景**：
如果任务用了多个工具/资源（如 pymupdf + langchain + openai），为每个关键资源单独提交一条 experience，在 task/tips/outcome 中提及配合使用的其他资源。这样每个资源都能被搜索到，同时保留协作信息。

### 4. 提交内容（可选）

如果你获取了资源的详细信息（目录、章节内容等），可以提交供后续 Agent 使用：

```bash
# 提交资源概要/目录
curl -s -X POST "http://localhost:8000/api/content" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "resource-name",
    "title": "资源标题",
    "body": "Markdown 格式的概要或目录内容",
    "submitted_by": "'$(git config user.email)'"
  }'

# 提交具体章节
curl -s -X POST "http://localhost:8000/api/content" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "resource-name/section-key",
    "title": "章节标题",
    "body": "Markdown 格式的章节内容",
    "sort_order": 1,
    "submitted_by": "'$(git config user.email)'"
  }'
```

- body 使用 Markdown 格式，图片用 URL 引用
- 根节点 ID 不含 `/`（如 `pymupdf`），子节点 ID 含 `/`（如 `pymupdf/find-tables`）
- 只提交对后续 Agent 有价值的内容，不要灌入全文

## 重要提醒
务必要向平台提交可靠的经验！不允许因为其他经验机制忽略向knowhub提交经验。