Octolens API 技能

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 从社交媒体及其他平台抓取品牌提及（mentions）
• 按来源筛选提及（Twitter、Reddit、GitHub、LinkedIn、YouTube、HackerNews、DevTO、StackOverflow、Bluesky、新闻简报、播客）
• 分析情感倾向（正面、中性、负面）
• 按作者粉丝数或互动量进行筛选
• 搜索特定关键词或标签
• 按日期范围查询提及
• 列出可用的关键词或已保存的视图（saved views）
• 应用包含 AND/OR 条件的复杂筛选逻辑

API 认证

Octolens API 使用 Bearer Token 进行身份验证。用户应提供其 API 密钥，你需将其放入 Authorization 请求头中：

Authorization: Bearer YOUR_API_KEY

重要提示：在发起任何 API 调用前，务必先向用户索取其 API 密钥，并将该密钥存入变量以供后续请求复用。

基础 URL

所有 API 接口均基于以下基础地址：https://app.octolens.com/api/v1

速率限制

• 限制：每小时最多 500 次请求
• 查看方式：响应头中的 X-RateLimit-* 字段可反映当前使用情况

可用接口

1. POST /mentions

根据关键词获取匹配的提及内容，并支持可选的筛选条件。返回结果按时间戳倒序排列（最新优先）。

关键参数：

• limit（数字，取值范围 1–100）：返回结果的最大数量（默认为 20）
• cursor（字符串）：上一次响应中提供的分页游标（pagination 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）

将筛选字段直接置于 filters 对象中，所有条件自动按逻辑与（AND）组合。

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

→ 等价于：source IN (twitter, linkedin) AND sentiment = positive AND followers ≥ 1000

排除项（Exclusions）

对任意数组型字段添加前缀 ! 即可实现排除语义：

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

→ 等价于：source = twitter AND keyword NOT IN (5, 6)

高级模式（AND/OR 分组）

通过 operator 和 groups 字段构建嵌套逻辑表达式：

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

可用筛选字段

使用内置脚本

本技能附带若干辅助脚本，用于快速完成常见操作。可通过它们便捷地调用 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. 尽可能使用视图（views），复用预设的筛选逻辑
3. 从简易筛选起步，再根据需要逐步增加复杂度
4. 检查速率限制：关注响应头中的 X-RateLimit-* 字段
5. 合理使用分页：对大量结果务必借助 cursor 参数进行分页处理
6. 日期格式必须为 ISO 8601（例如 "2024-01-15T00:00:00Z"）
7. 使用关键词前先获取 ID：须先调用 /keywords 接口获得关键词 ID
8. 善用排除语法（!）：过滤掉不相关或低质量内容
9. 结合 includeAll=false 与相关性筛选，提升结果质量

典型使用场景

查找粉丝数高且情感为正面的 Twitter 提及

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

排除含 spam 标签的内容，并获取 Reddit 与 GitHub 提及

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

复杂查询：(Twitter OR LinkedIn) AND 正面情感，近 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. 确认是否适用已有视图：若用户提及“已保存的筛选器”，请优先调用 /views 列出选项
5. 构建查询参数：首选简易模式；复杂逻辑再启用高级模式
6. 执行请求：使用内置 Node.js 脚本，或直接调用 fetch API
7. 解析响应数据：提取关键字段（作者、正文、情感、来源等）
8. 处理分页：若需更多结果，请复用响应中的 cursor 值发起下一页请求
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 的提及，排除带 spam 标签的内容，且情感为正面或中性”

操作（使用内置脚本）：

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]}'

代理（Agent）使用提示

• 优先使用内置脚本：Node.js 脚本已自动处理 JSON 解析与错误输出
• 缓存关键词信息：首次获取关键词后，可在当前会话中复用，避免重复请求
• 解释筛选逻辑：使用复杂筛选时，向用户清晰说明其含义（如 “A 与 B 任一满足，且 C 必须满足”）
• 提供结构示例：当用户不确定如何构造筛选条件时，主动展示标准 JSON 示例
• 审慎分页：在请求下一页前，主动询问用户是否需要更多结果
• 强调洞察而非原始数据：不只是罗列结果，还需提炼分析结论（如情感趋势、高频作者、平台占比等）