---
name: knowhub
description: 查询和上传知识到 KnowHub 知识库。当用户需要检索已有调研成果、工具知识，或上传新的调研结果时使用。
---

# KnowHub 知识库

自包含单脚本，三种模式覆盖全部典型用法：

| 模式 | 做什么 | 何时用 |
|------|-------|--------|
| `ask`    | 深度回顾 —— 调远端 Librarian Agent 做规划+检索+整合 | 需要一个有引用的自然语言答案 |
| `search` | 快速检索 —— 语义搜索 + LLM 精排 | 只想拿结构化条目列表，快 |
| `save`   | 保存知识 | 把调研结论/工具使用经验写库 |

**自包含：** 本 skill 目录下 `knowhub.py` 是独立脚本，不依赖 `cyber-agent` 安装，只需 `pip install httpx`。

## 环境变量

| 变量 | 作用 | 默认 |
|------|------|------|
| `KNOWHUB_API`   | KnowHub 服务器地址 | `http://43.106.118.91:9999` |
| `KNOWHUB_OWNER` | `save` 的默认所有者；`search` 留空=不过滤，传 `--owner=$KNOWHUB_OWNER` 限定自己的 | `sunlit.howard@gmail.com` |

也可以在 skill 目录下放 `.env` 文件覆盖默认（仅认 `KEY=VALUE` 纯文本，不依赖 python-dotenv）。

## 用法

### ask —— 深度回顾

```bash
# 调 remote_librarian（默认，快，基于已入库知识）
python /Users/sunlit/.claude/skills/knowhub/knowhub.py ask --query="ControlNet 相关的工具"

# 调 remote_research（深，全网调研 + 入库，慢，分钟级）
python /Users/sunlit/.claude/skills/knowhub/knowhub.py ask --query="..." --deep

# 复用上下文（用上次返回的 sub_trace_id）
python /Users/sunlit/.claude/skills/knowhub/knowhub.py ask \
    --query="基于刚才的结果补充..." \
    --continue_from=65298f18-7cc4-4bc0-9fb8-6f2dd048df31
```

返回 `{"mode","agent_type","sub_trace_id","status","summary","stats","error"}`，`summary` 字段是带引用的自然语言回答。

### search —— 快速检索

```bash
python /Users/sunlit/.claude/skills/knowhub/knowhub.py search \
    --query="图片批量生成" \
    --top_k=5 \
    --min_score=3 \
    --types=strategy,tool
```

**按关系过滤**（只看某 capability/tool/requirement 关联的）：

```bash
python /Users/sunlit/.claude/skills/knowhub/knowhub.py search \
    --query="..." --capability_id=CAP-008
```

返回 `{"query","count","results":[...]}`，`results` 每项含 `id / task / content / eval.score / types`。

### save —— 保存知识

```bash
python /Users/sunlit/.claude/skills/knowhub/knowhub.py save \
    --task="在用 flux 生成海报图时, 怎么让文字不错乱" \
    --content="把文字用 [] 显式标出, 并在 prompt 末尾加 'clean typography, legible text'" \
    --types=strategy \
    --score=4 \
    --source_name="flux 实测 2026-04" \
    --source_urls=https://example.com/post-1
```

默认 `owner = $KNOWHUB_OWNER`，`scopes=["org:cybertogether"]`。需要覆盖用 `--owner=...` / `--scopes=...`。

## 注意

- `ask` 是同步阻塞的，timeout 600s；`search` 和 `save` 都在 60s / 30s 内返回
- 所有命令返回标准 JSON，失败时 `error` 字段有值且退出码 1
- `--tags` 接 JSON 字符串（如 `'{"project":"xyz"}'`）；其他逗号分隔的参数接 CSV