什么是 Happenstance？

Happenstance 使客户能够精准地掌控其专业领域。通过集成 Happenstance API，此技能支持在个人、好友连接以及特定群组中进行异步搜索。它不仅是简单的联系人查找，还提供深入的研究能力，将雇佣历史、教育背景、项目经历和社交动态整合到一份极具参考价值的个人档案中。

对于需要自动化人才挖掘和人脉分析的开发者、招聘人员及销售专业人士而言，此 Openclaw Skills 集成至关重要。它提供了一种结构化的方式来处理专业数据，确保每次搜索都有特质标签、共同好友和社交链接等元数据支撑。

下载入口:https://github.com/openclaw/skills/tree/main/skills/dgoss28/happenstance

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Happenstance 应用场景

• 在扩展的人脉网络中识别特定专家，以进行技术咨询或招聘。
• 针对潜在合作伙伴或候选人生成深度专业背景报告。
• 自动化发现共同联系人，以促进熟人引荐。
• 以编程方式监控 API 额度使用情况并管理人脉群组成员身份。

1. 用户通过 Happenstance API 发起搜索查询或研究请求。
2. 技能处理异步流程，并返回用于轮询的唯一 ID。
3. 通过轮询状态端点检索结果，直到任务达到已完成（COMPLETED）或失败（FAILED）状态。
4. 对于搜索任务，技能会提取结构化数据，包括社交链接、加权特质和共同联系人。
5. 对于研究任务，系统会编译包含工作经历、教育、项目、作品和爱好的完整档案。

Happenstance 配置指南

要在 Openclaw Skills 上开始使用 Happenstance，您必须拥有有效的 API 密钥并安装了 curl 工具。

# 将您的 API 密钥设置为环境变量
export HAPPENSTANCE_API_KEY='your_api_key_here'

您可以在 Happenstance 控制面板购买额度并管理 API 设置。确保您的环境可以访问 HAPPENSTANCE_API_KEY 以便进行持有者令牌（Bearer Token）请求。

Happenstance 数据架构与分类体系

该技能处理并返回为高级专业分析量身定制的结构化数据：

name: happenstance
description: Search your professional network and research people using the Happenstance API.
metadata:
  openclaw:
    requires:
      env:
        - HAPPENSTANCE_API_KEY
      bins:
        - curl
    primaryEnv: HAPPENSTANCE_API_KEY

Happenstance

Search your network and get detailed research profiles on people using the Happenstance API.

Documentation: https://developer.happenstance.ai

Authentication

All requests require the HAPPENSTANCE_API_KEY environment variable. Pass it as a Bearer token:

Authorization: Bearer $HAPPENSTANCE_API_KEY

Base URL: https://api.happenstance.ai

Billing

• Search: 2 credits per search (including find-more)
• Research: 1 credit per completed research
• Check balance with GET /v1/usage
• Purchase credits at https://happenstance.ai/settings/api

Available Operations

1. Search Your Network

Search for people across groups and connections. Searches run asynchronously.

Start a search:

curl -s -X POST https://api.happenstance.ai/v1/search r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{
    "text": "engineers who have worked on AI infrastructure",
    "include_my_connections": true,
    "include_friends_connections": true
  }'

You can also search within specific groups by adding "group_ids": ["uuid1", "uuid2"]. Get group IDs from GET /v1/groups.

At least one search source is required: group_ids, include_my_connections: true, or include_friends_connections: true.

Response:

{"id": "search-uuid", "url": "https://happenstance.ai/search/search-uuid"}

Poll for results (every 5-10 seconds until status is COMPLETED or FAILED):

curl -s https://api.happenstance.ai/v1/search/SEARCH_ID r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

Completed response includes:

• status: RUNNING, COMPLETED, or FAILED
• results: array of people, each with id, name, current_title, current_company, summary, weighted_traits_score, socials (with happenstance_url, linkedin_url, twitter_url), mutuals, and traits
• has_more: boolean indicating if more results are available
• mutuals: top-level array of mutual connections (results reference these by index)
• traits: top-level array of trait definitions (results reference these by index)

2. Find More Results

When has_more is true on a completed search, get additional results that exclude all previously returned people. Costs 2 credits.

curl -s -X POST https://api.happenstance.ai/v1/search/SEARCH_ID/find-more r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

Response:

{"page_id": "page-uuid", "parent_search_id": "search-uuid"}

Then poll with the page_id:

curl -s "https://api.happenstance.ai/v1/search/SEARCH_ID?page_id=PAGE_ID" r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

3. Research a Person

Get a detailed professional profile for a specific person. Runs asynchronously.

Start research:

curl -s -X POST https://api.happenstance.ai/v1/research r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY" r
  -H "Content-Type: application/json" r
  -d '{"description": "Garry Tan, CEO of Y Combinator, @garrytan on Twitter"}'

Include as many details as possible (full name, company, title, location, social handles) for best results.

Response:

{"id": "research-uuid"}

Poll for results (every 5-10 seconds until status is COMPLETED, FAILED, or FAILED_AMBIGUOUS):

curl -s https://api.happenstance.ai/v1/research/RESEARCH_ID r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

Completed response includes a profile object with:

• person_metadata: full_name, alternate_names, profile_urls, current_locations, tagline
• employment: array of jobs with company_name, job_title, start_date, end_date, description
• education: array with university_name, degree, start_date, end_date
• projects: array with title, description, urls
• writings: array of publications with title, description, date, urls
• hobbies: array with description
• summary: overall text summary with supporting urls

4. List Groups

Get the groups you can search within:

curl -s https://api.happenstance.ai/v1/groups r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

Returns {"groups": [{"id": "uuid", "name": "Group Name"}, ...]}.

5. Check Credits and Usage

curl -s https://api.happenstance.ai/v1/usage r
  -H "Authorization: Bearer $HAPPENSTANCE_API_KEY"

Returns balance_credits, has_credits, purchases, usage history, and auto_reload settings.

Error Handling

Errors use RFC 7807 format:

{"type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Description must not be empty", "instance": "/v1/research"}

Key status codes:

• 401: Invalid or missing API key
• 402: Insufficient credits
• 429: Too many concurrent requests (max 10 running searches or research requests)
• 500/503: Server error, retry with backoff

Tips

• Always check credits before starting multiple searches or research requests.
• Search typically completes in 30-60 seconds. Research takes 1-3 minutes.
• Each search returns up to 30 results. Use find-more for additional pages.
• When presenting search results, include the person's name, title, company, summary, and Happenstance profile link.
• When presenting research, summarize the profile and link to sources.
• The more data sources the user connects, the better the search results.