介绍
# Octolens API Skill
## 何时使用此技能
当用户需要以下功能时使用此技能： - 从社交媒体和其他平台获取品牌提及 - 按来源过滤提及（Twitter、Reddit、GitHub、LinkedIn、YouTube、HackerNews、DevTO、StackOverflow、Bluesky、新闻通讯、播客） - 分析情感（正面、中性、负面） - 按作者粉丝数或参与度过滤 - 搜索特定关键词或标签 - 按日期范围查询提及 - 列出可用的关键词或保存的视图 - 使用 AND/OR 条件应用复杂的过滤逻辑
## API 身份验证
Octolens API 需要 Bearer 令牌进行身份验证。用户应提供其 API 密钥，您将在 `Authorization` 标头中使用该密钥：
``` Authorization: Bearer YOUR_API_KEY ```
**重要**：在进行任何 API 调用之前，请务必询问用户的 API 密钥。将其存储在变量中以便后续请求使用。
## 基础 URL
所有 API 端点均使用基础 URL：`https://app.octolens.com/api/v1`
## 速率限制
- **限制**：每小时 500 次请求 - **检查标头**：`X-RateLimit-*` 标头指示当前使用情况
## 可用端点
### 1. POST /mentions
获取匹配关键词的提及，支持可选过滤。返回按时间戳排序的帖子（最新的在前）。
**关键参数：** - `limit`（数字，1-100）：返回的最大结果数（默认：20） - `cursor`（字符串）：来自上一个响应的分页游标 - `includeAll`（布尔值）：包含低相关性帖子（默认：false） - `view`（数字）：用于过滤的视图 ID - `filters`（对象）：过滤条件（请参阅过滤部分）
**响应示例：** ```json { "data": [ { "id": "abc123", "url": "https://twitter.com/user/status/123", "body": "Just discovered @YourProduct - this is exactly what I needed!", "source": "twitter", "timestamp": "2024-01-15T10:30:00Z", "author": "user123", "authorName": "John Doe", "authorFollowers": 5420, "relevance": "relevant", "sentiment": "positive", "language": "en", "tags": ["feature-request"], "keywords": [{ "id": 1, "keyword": "YourProduct" }], "bookmarked": false, "engaged": false } ], "cursor": "eyJsYXN0SWQiOiAiYWJjMTIzIn0=" } ```
### 2. GET /keywords
列出为组织配置的所有关键词。
**响应示例：** ```json { "data": [ { "id": 1, "keyword": "YourProduct", "platforms": ["twitter", "reddit", "github"], "color": "#6366f1", "paused": false, "context": "Our main product name" } ] } ```
### 3. GET /views
列出所有保存的视图（预配置的过滤器）。
**响应示例：** ```json { "data": [ { "id": 1, "name": "High Priority", "icon": "star", "filters": { "sentiment": ["positive", "negative"], "source": ["twitter"] }, "createdAt": "2024-01-01T00:00:00Z" } ] } ```
## 过滤提及
`/mentions` 端点支持强大的过滤功能，有两种模式：
### 简单模式（隐式 AND）
将字段直接放入过滤器中。所有条件以 AND 组合。
```json { "filters": { "source": ["twitter", "linkedin"], "sentiment": ["positive"], "minXFollowers": 1000 } } ``` → `source IN (twitter, linkedin) AND sentiment = positive AND followers ≥ 1000`
### 排除
在任何数组字段前加 ! 以排除特定值：
```json { "filters": { "source": ["twitter"], "!keyword": [5, 6] } } ``` → `source = twitter AND keyword NOT IN (5, 6)`
### 高级模式（AND/OR 组）
使用 `operator` 和 `groups` 进行复杂逻辑判断：
```json { "filters": { "operator": "AND", "groups": [ { "operator": "OR", "conditions": [ { "source": ["twitter"] }, { "source": ["linkedin"] } ] }, { "operator": "AND", "conditions": [ { "sentiment": ["positive"] }, { "!tag": ["spam"] } ] } ] } } ``` → `(source = twitter OR source = linkedin) AND (sentiment = positive AND tag ≠ spam)`
### 可用过滤字段
| 字段 | 类型 | 描述 | |-------|------|-------------| | `source` | string[] | 平台：twitter, reddit, github, linkedin, youtube, hackernews, devto, stackoverflow, bluesky, newsletter, podcast | | `sentiment` | string[] | 值：positive, neutral, negative | | `keyword` | string[] | 关键词 ID（从 /keywords 端点获取）| | `language` | string[] | ISO 639-1 代码：en, es, fr, de, pt, it, nl, ja, ko, zh | | `tag` | string[] | 标签名称 | | `bookmarked` | boolean | 过滤已加书签的帖子或未加书签的帖子 | | `engaged` | boolean | 过滤已参与的帖子或未参与的帖子 | | `minXFollowers` | number | 最小 Twitter 粉丝数 | | `maxXFollowers` | number | 最大 Twitter 粉丝数 | | `startDate` | string | ISO 8601 格式（例如，"2024-01-15T00:00:00Z"）| | `endDate` | string | ISO 8601 格式 |
## 使用捆绑脚本
此技能包含用于常见操作的辅助脚本。使用它们可以快速与 API 交互：
### 获取提及 ```bash node scripts/fetch-mentions.js YOUR_API_KEY [limit] [includeAll] ```
### 列出关键词 ```bash node scripts/list-keywords.js YOUR_API_KEY ```
### 列出视图 ```bash node scripts/list-views.js YOUR_API_KEY ```
### 自定义过滤查询 ```bash node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"]}' [limit] ```
### 高级查询 ```bash node scripts/advanced-query.js YOUR_API_KEY [limit] ```
## 最佳实践
1. **请务必询问 API 密钥**，然后再发出请求 2. **尽可能使用视图**以利用预配置的过滤器 3. **从简单的过滤器开始**，并根据需要增加复杂性 4. **检查响应标头中的速率限制**（`X-RateLimit-*`） 5. **使用游标进行分页**以处理大型结果集 6. **日期必须为 ISO 8601** 格式（例如，"2024-01-15T00:00:00Z"） 7. **按关键词过滤前先从 `/keywords` 端点获取关键词 ID** 8. **使用排除符 (!)** 过滤掉不需要的内容 9. **结合使用 includeAll=false** 和相关性过滤以获得高质量结果
## 常见用例
### 查找粉丝数较多的正面 Twitter 提及 ```json { "limit": 20, "filters": { "source": ["twitter"], "sentiment": ["positive"], "minXFollowers": 1000 } } ```
### 排除垃圾邮件并获取 Reddit + GitHub 提及 ```json { "limit": 50, "filters": { "source": ["reddit", "github"], "!tag": ["spam", "irrelevant"] } } ```
### 复杂查询：(Twitter OR LinkedIn) AND 正面情感，过去 7 天 ```json { "limit": 30, "filters": { "operator": "AND", "groups": [ { "operator": "OR", "conditions": [ { "source": ["twitter"] }, { "source": ["linkedin"] } ] }, { "operator": "AND", "conditions": [ { "sentiment": ["positive"] }, { "startDate": "2024-01-20T00:00:00Z" } ] } ] } } ```
## 错误处理
| 状态 | 错误 | 描述 | |--------|-------|-------------| | 401 | unauthorized | 缺少或无效的 API 密钥 | | 403 | forbidden | 密钥有效但没有权限 | | 404 | not_found | 未找到资源（例如，视图 ID）| | 429 | rate_limit_exceeded | 请求过多 | | 400 | invalid_request | 请求正文格式错误 | | 500 | internal_error | 服务器错误，请稍后重试 |
## 分步工作流程
当用户要求查询 Octolens 数据时：
1. **询问 API 密钥**（如果尚未提供） 2. **理解请求**：他们在寻找什么？ 3. **确定所需的过滤器**：来源、情感、日期范围等。 4. **检查是否有适用的视图**：如果用户提到保存的过滤器，请先列出视图 5. **构建查询**：首先使用简单模式，对于复杂逻辑使用高级模式 6. **执行请求**：使用捆绑的 Node.js 脚本或直接使用 fetch API 7. **解析结果**：提取关键信息（作者、正文、情感、来源） 8. **处理分页**：如果需要更多结果，请使用响应中的游标 9. **展示发现**：总结见解，突出模式
## 示例
### 示例 1：简单查询 **用户**：“向我展示过去 7 天来自 Twitter 的正面提及”
**操作**（使用捆绑脚本）： ```bash node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"], "startDate": "2024-01-20T00:00:00Z"}' ```
**备选方案**（直接使用 fetch API）： ```javascript const response = await fetch('https://app.octolens.com/api/v1/mentions', { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ limit: 20, filters: { source: ['twitter'], sentiment: ['positive'], startDate: '2024-01-20T00:00:00Z', }, }), }); const data = await response.json(); ```
### 示例 2：高级查询 **用户**：“查找来自 Reddit 或 GitHub 的提及，排除垃圾邮件标签，且情感为正面或中性”
**操作**（使用捆绑脚本）： ```bash node scripts/query-mentions.js YOUR_API_KEY '{"operator": "AND", "groups": [{"operator": "OR", "conditions": [{"source": ["reddit"]}, {"source": ["github"]}]}, {"operator": "OR", "conditions": [{"sentiment": ["positive"]}, {"sentiment": ["neutral"]}]}, {"operator": "AND", "conditions": [{"!tag": ["spam"]}]}]}' ```
**备选方案**（直接使用 fetch API）： ```javascript const response = await fetch('https://app.octolens.com/api/v1/mentions', { method: 'POST', headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ limit: 30, filters: { operator: 'AND', groups: [ { operator: 'OR', conditions: [ { source: ['reddit'] }, { source: ['github'] }, ], }, { operator: 'OR', conditions: [ { sentiment: ['positive'] }, { sentiment: ['neutral'] }, ], }, { operator: 'AND', conditions: [ { '!tag': ['spam'] }, ], }, ], }, }), }); const data = await response.json(); ```
### 示例 3：先获取关键词 **用户**：“显示我们主要产品关键词的提及”
**操作**： 1. 首先，列出关键词： ```bash node scripts/list-keywords.js YOUR_API_KEY ```
2. 然后使用关键词 ID 查询提及： ```bash node scripts/query-mentions.js YOUR_API_KEY '{"keyword": [1]}' ```
## 给代理的提示
- **使用捆绑脚本**：Node.js 脚本会自动处理 JSON 解析 - **缓存关键词**：获取一次关键词后，请在会话期间记住它们 - **解释过滤器**：使用复杂过滤器时，请向用户解释逻辑 - **展示示例**：当用户不确定时，展示示例过滤器结构 - **明智地分页**：在获取下一页之前询问用户是否需要更多结果 - **总结见解**：不要只是堆砌数据，要提供分析（情感趋势、热门作者、平台分布）