Ubuntu
240 lines
6.6 KiB
Markdown
240 lines
6.6 KiB
Markdown
# 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. 支持更多编程语言 |