名称： signalhire
描述： 通过 SignalHire API（搜索、个人资料和额度）寻找和丰富联系人信息
元数据：
openclaw:
# 此技能仅在提供有效的 API 密钥和回调 URL 时加载。主要环境变量用于注入密钥，确保其不会在指令中暴露。回调 URL 应指向通过隧道或反向代理公开暴露的连接器服务。
requires:
env: SIGNALHIRE_API_KEY,SIGNALHIRE_CALLBACK_URL
primaryEnv: SIGNALHIRE_API_KEY

SignalHire 技能使用说明

此技能向 OpenClaw 智能体提供三项高级功能。每项功能对应 SignalHire 文档中的一个 REST 端点。智能体不应直接调用这些端点，而必须调用已定义的技能动作。以下指南总结了 API 的工作原理，包括速率限制、并发限制和异步回调工作流。下文中的所有事实性陈述均以官方 SignalHire API 文档为依据。

1. 查询剩余额度

使用此动作来确认账户剩余多少额度。SignalHire API 提供了一个专用端点 GET /api/v1/credits，该端点会以 JSON 格式返回可用额度数量。请求头中必须包含有效的 API 密钥。成功调用后，响应中会包含一个名为 credits 的字段，表示剩余额度数量。如果账户配置为“仅查询资料（不含联系方式）”，可以调用同一端点并附加查询参数 withoutContacts=true。此外，每次调用个人资料 API 时，响应头 X-Credits-Left 也会返回剩余额度。

在启动大型信息丰富任务之前，智能体必须调用此动作，以避免在操作中途耗尽额度。如果剩余额度数量低于待丰富信息的条目数，应优雅地拆分或中止任务。

2. 搜索个人资料

使用此动作在 SignalHire 数据库中寻找潜在候选人，此操作不消耗联系人额度。搜索 API 端点是 POST /api/v1/candidate/searchByQuery，它返回一个包含个人资料摘要列表和一个 scrollId 的响应。scrollId 可用于通过滚动搜索端点（此处未展示）获取更多结果页，直到所有结果遍历完毕。访问搜索 API 需要联系 SignalHire 支持人员开通，并且受到严格的并发限制：最多同时处理三个请求。智能体必须确保在任何时候，正在进行的 searchByQuery 调用不超过三个。

执行搜索时，请求体应包含诸如 currentTitle、location、keywords、industry 等字段以及其他文档中描述的筛选条件。size 参数控制每页返回的个人资料数量（默认 10，最大 100）。获取第一页结果后，智能体应在 15 秒内立即跟进滚动请求，以避免 scrollId 过期。搜索响应是同步的，会立即返回，无需回调。

3. 丰富联系人信息（个人资料 API）

此动作用于获取最多 100 个条目（每个请求）的完整联系人信息（电子邮件、电话和社交资料）。端点是 POST /api/v1/candidate/search。每个条目可以是 LinkedIn 个人资料 URL、电子邮件地址、电话号码或 SignalHire 个人资料 UID。请求体必须包含一个 callbackUrl 参数；一旦数据处理完成，API 会将结果发送到此 URL。在 callbackUrl 上监听的服务器必须返回 HTTP 状态码 200 以确认接收成功。如果回调端点无法访问或在十秒超时内未响应，SignalHire 会重试最多三次。只有在收到所有回调负载后，处理才算完成。

回调负载包含一个对象数组，每个对象都有一个 status 字段，指示该条目的处理结果：success、failed、credits_are_over、timeout_exceeded 或 duplicate_query。当状态为 success 时，负载还会包含一个 candidate 对象，其字段包括 fullName、emails、phones、location 等。这些结果由连接器服务持久化到 CSV 文件中；智能体应等待连接器报告任务就绪后再处理数据。

个人资料 API 受速率限制：每分钟最多处理 600 个元素。智能体必须实施节流控制，确保所有个人资料 API 调用中的条目总数不超过此限制。超出限制的请求将被拒绝，并返回 HTTP 状态码 429 Too Many Requests。为最大化吞吐量，每个请求最多批处理 100 个条目，但不要超过全局的每分钟配额。

给智能体的通用指南

1. 不要硬编码 API 密钥或回调 URL。 使用 OpenClaw 注入的环境变量：SIGNALHIRE_API_KEY 用于认证，SIGNALHIRE_CALLBACK_URL 用于个人资料 API。这些值在运行时提供，不得回显或泄露。
2. 在开始大型信息丰富任务前，始终检查剩余额度。 如果额度不足，则中止或拆分任务。
3. 遵守速率和并发限制。 搜索 API 并发请求不超过三个。个人资料 API 每分钟处理不超过 600 个条目。对 HTTP 429 响应实施指数退避重试。
4. 调用个人资料 API 时，始终包含有效的 callbackUrl，并确保连接器服务可访问且响应及时。回调必须在十秒内返回 HTTP 200，否则结果可能被丢弃。
5. 等待任务完成。 提交个人资料 API 请求后，智能体应轮询连接器的任务端点（README 中有描述），直到它指示所有结果都已接收。只有到那时，智能体才应继续处理 CSV 数据。
6. 处理回调中的所有状态值。 对于 failed、credits_are_over、timeout_exceeded 和 duplicate_query，将没有候选人数据可用；记录这些情况并继续处理。
7. 遵守法律和隐私要求。 SignalHire 将 API 使用与其条款、隐私和 GDPR 页面绑定。在存储或使用联系人数据时，始终尊重数据主体的权利和退出请求。

遵循上述说明，智能体可以安全地将 SignalHire 的潜在客户寻找和信息丰富功能集成到 OpenClaw 工作流中。