介绍
# SignalHire skill instructions
此技能向 OpenClaw 代理公开了三项高级功能。每项功能对应于 SignalHire 文档中记录的一个 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】，它会返回个人资料摘要列表以及 `scrollId`。可以使用 scrollId 通过滚动搜索端点（此处未显示）获取其他页面，直到所有结果耗尽。只有在联系 SignalHire 支持部门后才会授予搜索 API 的访问权限，并且该访问受到严格的并发限制，即**同时三个请求**【21055727237259†L110-L116】。代理必须确保任何时刻正在进行的 searchByQuery 调用不超过三个。
执行搜索时，请求正文应包含 `currentTitle`、`location`、`keywords`、`industry` 和文档中描述的其他过滤器等字段【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` 参数；一旦处理完数据，API 会将结果发布到此 URL【821841938681143†L126-L134】。在 callbackUrl 上侦听的有效服务器必须返回 HTTP 状态 200 以确认成功接收。如果无法访问回调端点或未在十秒超时内响应，SignalHire 将重试最多三次【821841938681143†L187-L198】。只有在接收到所有回调负载后，处理才算完成。
回调负载包含一个对象数组，每个对象都有一个 `status` 字段，指示该项的结果：`success`、`failed`、`credits_are_over`、`timeout_exceeded` 或 `duplicate_query`【821841938681143†L239-L249】。当状态为 `success` 时，负载还包括一个 `candidate` 对象，其中包含 `fullName`、`emails`、`phones`、`location` 等字段。这些结果由连接器服务持久化到 CSV 文件中；代理应等待连接器报告作业已准备就绪，然后再使用数据。
Person API 受到速率限制：每分钟最多处理 **600 个元素**【821841938681143†L490-L503】。代理必须实施限流，以确保所有 Person API 调用中的项目总数不超过此限制。超出限制的请求将被拒绝，并返回 HTTP 状态 429 `Too Many Requests`【821841938681143†L500-L503】。为了最大化吞吐量，请将每个请求的项目数最多设为 100，但不要超过全局每分钟配额。
## 代理的一般指导原则
1. **不要硬编码 API 密钥或回调 URL。** 使用由 OpenClaw 注入的环境变量：`SIGNALHIRE_API_KEY` 用于身份验证，`SIGNALHIRE_CALLBACK_URL` 用于 Person API。这些值在运行时提供，不得回显或泄露。
2. **在开始大型丰富作业之前，务必检查剩余额度。** 如果额度不足，则中止或拆分作业。
3. **遵守速率和并发限制。** 搜索 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. **处理回调中的所有状态值。** 对于 `failed`、`credits_are_over`、`timeout_exceeded` 和 `duplicate_query`，将没有候选人数据可用；记录这些情况并继续。
7. **遵守法律和隐私要求。** SignalHire 将 API 使用与其条款、隐私和 GDPR 页面绑定。在存储或使用联系数据时，务必尊重数据主体权利和退出请求【821841938681143†L559-L566】。
通过遵循上述说明，代理可以安全地将 SignalHire 的潜在客户开发和数据丰富功能集成到 OpenClaw 工作流中。