Octolens API 技能

何时使用此技能

当用户需要时使用此技能：

• 从社交媒体和其他平台获取品牌提及信息
• 按来源筛选提及（Twitter、Reddit、GitHub、LinkedIn、YouTube、HackerNews、DevTO、StackOverflow、Bluesky、新闻通讯、播客）
• 分析情感（积极、中性、消极）
• 按作者粉丝数或互动量筛选
• 搜索特定关键词或标签
• 按日期范围查询提及
• 列出可用的关键词或已保存的视图
• 使用 AND/OR 条件应用复杂筛选逻辑

API 身份验证

Octolens API 需要使用 Bearer 令牌进行身份验证。用户应提供其 API 密钥，您需要将其用于授权请求头：

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（对象）：筛选条件（参见筛选部分）

示例响应：

{
  "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

列出为该组织配置的所有关键词。

示例响应：

{
  "data": [
    {
      "id": 1,
      "keyword": "YourProduct",
      "platforms": ["twitter", "reddit", "github"],
      "color": "#6366f1",
      "paused": false,
      "context": "Our main product name"
    }
  ]
}

3. GET /views

列出所有保存的视图（预配置的筛选器）。

示例响应：

{
  "data": [
    {
      "id": 1,
      "name": "High Priority",
      "icon": "star",
      "filters": {
        "sentiment": ["positive", "negative"],
        "source": ["twitter"]
      },
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

筛选提及

该/mentions端点支持两种模式下的强大筛选功能：

简单模式（隐式AND）

将字段直接放入筛选器中。所有条件以AND方式组合。

{
  "filters": {
    "source": ["twitter", "linkedin"],
    "sentiment": ["positive"],
    "minXFollowers": 1000
  }
}

→来源 IN (twitter, linkedin) AND 情感 = 正面 AND 关注者 ≥ 1000

排除

在任何数组字段前添加 ! 以排除特定值：

{
  "filters": {
    "source": ["twitter"],
    "!keyword": [5, 6]
  }
}

→来源 = twitter AND 关键词 NOT IN (5, 6)

高级模式（AND/OR分组）

使用运算符和用于复杂逻辑的分组：→

{
  "filters": {
    "operator": "AND",
    "groups": [
      {
        "operator": "OR",
        "conditions": [
          { "source": ["twitter"] },
          { "source": ["linkedin"] }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "sentiment": ["positive"] },
          { "!tag": ["spam"] }
        ]
      }
    ]
  }
}

(来源 = twitter 或 来源 = linkedin) 且 (情感 = 正面 且 标签 ≠ 垃圾信息)可用筛选字段

字段

使用捆绑脚本

此技能包含用于常见操作的辅助脚本。使用它们可以快速与API交互：

获取提及

node scripts/fetch-mentions.js YOUR_API_KEY [limit] [includeAll]

列出关键词

node scripts/list-keywords.js YOUR_API_KEY

列表视图

node scripts/list-views.js YOUR_API_KEY

自定义筛选查询

node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"]}' [limit]

高级查询

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提及

{
  "limit": 20,
  "filters": {
    "source": ["twitter"],
    "sentiment": ["positive"],
    "minXFollowers": 1000
  }
}

排除垃圾信息并获取Reddit和GitHub提及

{
  "limit": 50,
  "filters": {
    "source": ["reddit", "github"],
    "!tag": ["spam", "irrelevant"]
  }
}

复杂查询：(Twitter 或 LinkedIn) 且情绪积极，最近7天

{
  "limit": 30,
  "filters": {
    "operator": "AND",
    "groups": [
      {
        "operator": "OR",
        "conditions": [
          { "source": ["twitter"] },
          { "source": ["linkedin"] }
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          { "sentiment": ["positive"] },
          { "startDate": "2024-01-20T00:00:00Z" }
        ]
      }
    ]
  }
}

错误处理

分步工作流程

当用户请求查询 Octolens 数据时：

1. 请求API密钥如果尚未提供
2. 理解请求：他们在寻找什么？
3. 确定所需的过滤器：来源、情感、日期范围等
4. 检查是否有适用的视图：如果用户提到保存的过滤器，首先列出视图
5. 构建查询：首先使用简单模式，复杂逻辑使用高级模式
6. 执行请求：使用捆绑的 Node.js 脚本或直接调用 fetch API
7. 解析结果：提取关键信息（作者、正文、情感、来源）
8. 处理分页：如需更多结果，使用响应中的游标
9. 呈现发现结果：总结见解，突出模式

示例

示例1：简单查询

用户：“显示过去7天内Twitter上的正面提及”

操作（使用捆绑脚本）：

node scripts/query-mentions.js YOUR_API_KEY '{"source": ["twitter"], "sentiment": ["positive"], "startDate": "2024-01-20T00:00:00Z"}'

替代方案（直接使用fetch API）：

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的提及，排除垃圾邮件标签，且情绪为正面或中性”

操作（使用捆绑脚本）：

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）：

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. 首先，列出关键词：

node scripts/list-keywords.js YOUR_API_KEY

2. 然后，使用关键词ID查询提及：

node scripts/query-mentions.js YOUR_API_KEY '{"keyword": [1]}'

给代理的提示

• 使用捆绑脚本: Node.js脚本会自动处理JSON解析
• 缓存关键词: 获取关键词一次后，请在会话中记住它们
• 解释过滤器: 使用复杂过滤器时，向用户解释逻辑
• 展示示例: 当用户不确定时，展示过滤器结构示例
• 明智地分页: 在获取下一页之前，询问用户是否需要更多结果
• 总结洞察: 不要仅仅转储数据，要提供分析（如情感趋势、顶级作者、平台分布）