名称： octolens
描述： 从 Octolens API 查询和分析品牌提及。当用户需要获取提及、追踪关键词、按来源平台（Twitter、Reddit、GitHub、LinkedIn 等）筛选、进行情感分析或分析社交媒体互动时使用。支持使用 AND/OR 逻辑、日期范围、粉丝数和书签进行复杂筛选。
许可证： MIT
元数据：
author: octolens
version: "1.0"
compatibility: 需要 Node.js 18+（用于 fetch API）和互联网访问权限
允许工具： Node Read

Octolens API 技能

何时使用此技能

当用户需要执行以下操作时，请使用此技能：
- 从社交媒体和其他平台获取品牌提及
- 按来源筛选提及（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（对象）：筛选条件（参见筛选部分）

响应示例：

{
  "data": [
    {
      "id": "abc123",
      "url": "https://twitter.com/user/status/123",
      "body": "刚刚发现了 @YourProduct - 这正是我需要的！",
      "source": "twitter",
      "timestamp": "2024-01-15T10:30:00Z",
      "author": "user123",
      "authorName": "张三",
      "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": "我们的主要产品名称"
    }
  ]
}

3. GET /views

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

响应示例：

{
  "data": [
    {
      "id": 1,
      "name": "高优先级",
      "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

排除筛选

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

{
  "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. 尽可能使用视图，以利用预配置的筛选器
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 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. 检查是否有适用的视图：如果用户提到已保存的筛选器，先列出视图
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 解析
• 缓存关键词：获取关键词一次后，在当前会话中记住它们
• 解释筛选器：使用复杂筛选器时，向用户解释其逻辑
• 展示示例：当用户不确定时，展示筛选器结构示例
• 明智地分页：在获取下一页之前，询问用户是否需要更多结果
• 总结洞察：不要仅仅转储数据，要提供分析（情感趋势、主要作者、平台分布）