SignalHire 技能使用说明

此技能向 OpenClaw 智能体公开了三种高级能力。每种能力对应 SignalHire API 文档中记载的一个 REST 端点。智能体绝不应直接调用这些端点；相反，它必须调用已定义的技能动作之一。以下指导总结了该 API 的工作原理，包括速率限制、并发限制和异步回调工作流。下文中的所有事实性陈述均以 SignalHire 官方 API 文档为依据。

1. 检查剩余点数

使用此操作来确定账户上剩余多少点数。SignalHire API 公开了一个专用端点GET /api/v1/credits该端点以 JSON 负载形式返回可用点数。请求头中必须包含有效的 API 密钥。调用成功后，响应中包含一个名为credits的字段，其值为剩余点数【821841938681143†L505-L529】。如果账户配置为“无联系人资料”，则可以调用同一端点并附带withoutContacts=true查询参数【821841938681143†L559-L566】。点数也会在每次对 Person API 的调用中，通过X-Credits-Left响应头返回【821841938681143†L559-L566】。

代理必须调用此操作在启动大规模数据丰富任务之前，以避免在操作过程中耗尽点数。如果剩余点数低于待丰富数据的条目数，则应优雅地拆分或中止任务。

2. 搜索档案

使用此操作可在SignalHire数据库中查找潜在候选人，而无需消耗联系人点数。搜索API端点是POST /api/v1/candidate/searchByQuery【21055727237259†L100-L109】，并返回档案摘要列表以及一个滚动标识符。该滚动标识符可用于通过滚动搜索端点（此处未显示）获取更多页面，直到所有结果都获取完毕。只有在联系SignalHire支持团队后，才能获得搜索API的访问权限，并且受到严格的并发限制，即三个 同时请求【21055727237259†L110-L116】。代理必须确保在任何时候，正在进行的searchByQuery调用不超过三个。

执行搜索时，请求正文应包含以下字段，例如当前职位、所在地,关键词,行业以及其他筛选条件，如文档【21055727237259†L120-L177】所述。`size` 参数控制每页返回多少个档案（默认10，最大100）。获取第一页后，代理应在15秒内立即跟进一个滚动请求，以避免 `scrollId` 过期。搜索的响应是同步的，会立即返回；不需要回调。3. 丰富联系人信息（Person API）此操作可检索最多100个项目的完整联系信息（电子邮件、电话和社交档案）。端点是 `POST /api/v1/candidate/search`【821841938681143†L126-L134】。每个项目可以是LinkedIn个人资料URL、电子邮件地址、电话号码或SignalHire档案UID【821841938681143†L120-L124】。请求体必须包含一个 `callbackUrl`。scrollId. The response from search is synchronous and will return immediately; no callback is needed.

3. Enrich contacts (Person API)

This action retrieves full contact information (emails, phones and social profiles) for up to 100 items per request. The endpoint isPOST /api/v1/candidate/search【821841938681143†L126-L134】. Each item may be a LinkedIn profile URL, an email address, a phone number or a SignalHire profile UID【821841938681143†L120-L124】. The request bodymustinclude acallbackUrl参数；一旦数据处理完毕，API会将结果发布到该URL【821841938681143†L126-L134】。一个有效的服务器在callbackUrl上监听，必须返回HTTP状态码200以确认成功接收。如果回调端点无法访问或在十秒超时内未响应，SignalHire将最多重试三次【821841938681143†L187-L198】。只有当所有回调负载都被接收后，处理才算完成。

回调负载包含一个对象数组，每个对象都有一个状态字段，指示该条目的结果：成功、失败、积分已用完、超时或重复查询【821841938681143†L239-L249】。当状态为成功时，负载还会包含一个候选人对象，其中包含诸如全名电子邮件,电话号码,位置等。这些结果由连接器服务持久化存储到CSV文件中；代理应等待连接器报告任务准备就绪后，再开始消费数据。Person API 受速率限制：每分钟最多处理

600个元素【821841938681143†L490-L503】。代理必须实施节流控制，以确保所有Person API调用中的项目总数不超过此限制。超出限制的请求将被拒绝，并返回HTTP状态码429请求过多【821841938681143†L500-L503】。为了最大化吞吐量，每个请求最多批处理100个项目，但不要超过全局的每分钟配额。代理通用指南

不要硬编码API密钥或回调URL。

1. 使用OpenClaw注入的环境变量：SIGNALHIRE_API_KEY用于认证，以及SIGNALHIRE_CALLBACK_URLSIGNALHIRE_CALLBACK_URLPerson API 使用的值。这些值在运行时提供，不得回显或泄露。

2. 始终检查剩余信用额度在开始大型数据丰富作业之前。如果信用额度不足，则中止或拆分作业。

3. 遵守速率和并发限制。Search API 并发请求不得超过三个【21055727237259†L110-L116】。每分钟通过 Person API 发送的项目不得超过 600 个【821841938681143†L490-L503】。对 HTTP 429 响应实施指数退避。

4. 调用 Person API 时始终包含有效的 callbackUrl并确保连接器服务可达且响应迅速。回调必须在十秒内返回 HTTP 200，否则结果可能被丢弃【821841938681143†L187-L198】。

5. 等待作业完成。提交 Person API 请求后，代理应轮询连接器的作业端点（在 README 中描述），直到其指示已收到所有结果。只有这样，代理才应继续处理 CSV 数据。

6. 处理来自回调的所有状态值。对于失败的、credits_are_over（信用额度已用完）,超时和重复查询的情况下，将无法获得候选数据；请记录这些情况并继续处理。

7. 遵守法律和隐私要求。SignalHire 将其 API 的使用与其条款、隐私和 GDPR 页面相关联。在存储或使用联系人数据时，请始终尊重数据主体的权利和退出请求【821841938681143†L559-L566】。

遵循上述指引，代理可以安全地将 SignalHire 的潜在客户挖掘和数据丰富功能集成到 OpenClaw 工作流程中。