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

scope: agent:*

KnowHub 知识管理

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

何时使用

查询知识：

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

保存知识（重要！）：

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

安装配置

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

快速开始

# 搜索知识
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. 查询知识

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. 保存知识

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

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 分：几乎没用

两类经验的区分：

对资源本身的使用经验 — 提交为该资源的知识
- 例如：使用 pymupdf 提取 PDF 表格的经验 → scenario: "pymupdf: PDF 表格提取"
对搜索平台/策略的经验 — 提交为平台或搜索策略的知识
- 对平台本身的评价 → scenario: "Smithery: 搜索 MCP server"
- 关于找工具/找资源的策略、方法论 → scenario: "工具发现策略: 使用 Reddit 搜索"

命令参考

更新知识

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

批量反馈

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

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

feedback.json 格式：

[
  {
    "knowledge_id": "knowledge-xxx",
    "is_effective": true,
    "feedback": "很有用"
  }
]

HTTP API

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

搜索：

curl -G "http://43.106.118.91:9999/api/knowledge/search" \
  --data-urlencode "q=查询" \
  --data-urlencode "top_k=5" \
  --data-urlencode "min_score=3"

保存：

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
    }
  }'

更新：

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

批量反馈：

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 - 资源推荐

示例

保存解决方案

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

保存对比

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

保存搜索策略

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

保存平台评价

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

重要提醒

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

SKILL.md 8.9 KB Kalıcı Bağlantı Geçmiş Ham