# Context Hub (chub) - API文档获取技能

## 概述

Context Hub（chub）是一个为AI编码助手设计的上下文文档管理系统，由Andrew Ng（吴恩达）团队开发。这个技能允许nanobot通过chub CLI获取准确、最新的API文档，减少AI幻觉，提高编码准确性。

## 安装要求

chub已经安装在系统中：
```bash
# 检查安装
which chub

# 基本命令可用
chub search openai --json
```

## 使用场景

当用户需要以下帮助时使用此技能：
1. 编写使用第三方库、SDK或API的代码
2. 需要当前API参考文档
3. 需要特定语言的SDK文档
4. 需要验证API接口的正确性

例如：
- "使用OpenAI API"
- "调用Stripe API"
- "使用Anthropic SDK"
- "查询Pinecone"
- 任何需要编写针对外部服务的代码的情况

## 使用步骤

### 步骤1 — 查找正确的文档ID

```bash
chub search "<库名称>" --json
```

从结果中选择最匹配的`id`（例如`openai/chat`、`anthropic/sdk`、`stripe/api`）。如果没有匹配项，尝试更广泛的术语。

### 步骤2 — 获取文档

```bash
chub get <id> --lang py    # 或 --lang js, --lang ts
```

如果文档只有一个语言变体，可以省略`--lang`参数。

### 步骤3 — 使用文档

读取获取的内容，并使用它来编写准确的代码或回答问题。不要依赖记忆的API形状 — 使用文档所说的内容。

### 步骤4 — 注解学习内容（可选）

完成任务后，如果发现了文档中没有的内容 — 例如陷阱、变通方法、版本特性或项目特定细节 — 保存它以便未来的会话更智能：

```bash
chub annotate <id> "Webhook验证需要原始body — 在验证前不要解析"
```

注解是本地保存的，跨会话持久化，并在未来的`chub get`调用中自动显示。保持注解简洁且可操作。不要重复文档中已有的内容。

### 步骤5 — 提供反馈（可选）

对文档进行评分，以便作者可以改进它。在发送前询问用户。

```bash
chub feedback <id> up                        # 文档工作良好
chub feedback <id> down --label outdated     # 文档需要更新
```

可用标签：`outdated`、`inaccurate`、`incomplete`、`wrong-examples`、`wrong-version`、`poorly-structured`、`accurate`、`well-structured`、`helpful`、`good-examples`。

## 快速参考

| 目标 | 命令 |
|------|---------|
| 列出所有内容 | `chub search` |
| 查找文档 | `chub search "stripe"` |
| 精确ID详情 | `chub search stripe/api` |
| 获取Python文档 | `chub get stripe/api --lang py` |
| 获取JS文档 | `chub get openai/chat --lang js` |
| 保存到文件 | `chub get anthropic/sdk --lang py -o docs.md` |
| 获取多个文档 | `chub get openai/chat stripe/api --lang py` |
| 保存注解 | `chub annotate stripe/api "需要原始body"` |
| 列出注解 | `chub annotate --list` |
| 评分文档 | `chub feedback stripe/api up` |

## 注意事项

- `chub search`不带查询参数会列出所有可用内容
- ID格式为`<作者>/<名称>` — 在获取前从搜索结果确认ID
- 如果存在多种语言且未传递`--lang`参数，chub会告诉你哪些语言可用
- 文档是增量获取的，只下载需要的文件，节省token

## 示例用例

### 用例1：获取OpenAI聊天API文档
```bash
# 搜索OpenAI相关文档
chub search openai --json

# 获取Python版本的OpenAI聊天API文档
chub get openai/chat --lang py
```

### 用例2：获取Stripe API文档
```bash
# 搜索Stripe相关文档
chub search stripe --json

# 获取JavaScript版本的Stripe API文档
chub get stripe/api --lang js
```

### 用例3：添加本地注解
```bash
# 为OpenAI聊天API添加注解
chub annotate openai/chat "在streaming模式下，需要处理partial responses"
```

## Python包装器

为了更方便地集成到nanobot，我们创建了一个Python包装器`chub_wrapper.py`：

```python
from skills.context_hub.chub_wrapper import ChubWrapper

# 初始化
wrapper = ChubWrapper()

# 搜索文档
results = wrapper.search("openai")

# 获取文档
content = wrapper.get_doc("openai/chat", language="py")

# 搜索并获取（一步完成）
result = wrapper.search_and_get("fastapi", language="py")
```

## 集成到nanobot

这个技能可以通过以下方式集成：

### 方式1：直接使用exec工具
```bash
# 搜索文档
exec chub search "openai" --json

# 获取文档
exec chub get openai/chat --lang py
```

### 方式2：使用Python包装器
```python
# 在nanobot技能中导入包装器
from skills.context_hub.chub_wrapper import ChubWrapper

wrapper = ChubWrapper()
results = wrapper.search("用户查询的库名")
```

### 建议的集成流程：
1. **检测需求**：当用户需要API文档时触发
2. **搜索阶段**：使用`chub search`查找相关文档
3. **获取阶段**：使用`chub get`获取具体文档
4. **处理阶段**：解析文档内容并用于回答
5. **学习阶段**：可选地使用`chub annotate`保存学习内容

## 优势

1. **减少幻觉**：提供准确的API文档，减少AI错误
2. **最新信息**：获取当前可用的API版本
3. **语言特定**：Python/JavaScript等特定文档
4. **效率提升**：增量获取减少上下文长度
5. **学习能力**：通过注解保留学习成果

## 限制

1. **内容覆盖**：可能缺少特定API文档
2. **社区驱动**：内容质量参差不齐
3. **语言限制**：主要支持主流编程语言
4. **更新延迟**：依赖社区维护更新

## 测试验证

技能已通过以下测试验证：
- ✅ chub CLI已安装并可用
- ✅ 搜索功能正常工作
- ✅ 文档获取功能正常
- ✅ JSON输出格式正确
- ✅ 注解功能正常工作
- ✅ Python包装器功能完整
- ✅ 集成示例运行成功

### 详细测试结果

1. **chub安装验证**：
   ```bash
   which chub  # 返回: /usr/bin/chub
   ```

2. **搜索功能测试**：
   ```bash
   chub search "openai" --json  # 成功返回14个结果
   ```

3. **文档获取测试**：
   ```bash
   chub get fastapi/package --lang py  # 成功获取10,441字符文档
   ```

4. **注解功能测试**：
   ```bash
   chub annotate fastapi/package "测试注解"  # 成功保存
   chub annotate --list  # 成功列出注解
   ```

5. **Python包装器测试**：
   ```python
   from chub_wrapper import ChubWrapper
   wrapper = ChubWrapper()
   results = wrapper.search("openai")  # 成功返回14个结果
   content = wrapper.get_doc("fastapi/package", "py")  # 成功获取文档
   ```

6. **使用示例测试**：
   ```bash
   python3 usage_example.py  # 所有功能正常
   ```

## 未来改进

1. 创建专门的Python包装器
2. 添加缓存机制
3. 集成到nanobot的自动技能调用
4. 支持更多编程语言