heyreach-master

用途

HeyReach Master 是 HeyReach 集成的内部资源库，用于集中存放被各 HeyReach 技能共享的资源。它解决的问题是：多个 HeyReach 技能之间会产生重复内容（设置说明、API 文档、认证流程、错误处理）。其解决方案是把共享内容抽取到 heyreach-master/references/ 与 heyreach-master/scripts/ 中，再由各技能引用，从而实现单一事实来源，并减少每个技能占用的上下文。

主要能力

资源库包含 API 客户端（heyreach_client.py）、配置检查器（check_heyreach_config.py）、全部操作脚本以及参考文档。

参考文档（references/）：

setup-guide.md：完整设置向导，包括从 HeyReach 获取 API 密钥、环境配置、验证连接。
api-reference.md：HeyReach API 模式，包括基础 URL 与认证、全部端点文档、请求/响应示例、分页模式。
error-handling.md：故障排除，包括常见错误与解决方案、HTTP 错误码、速率限制、调试提示。

脚本（scripts/）：

check_heyreach_config.py：预检校验。命令为 python check_heyreach_config.py [--json]，参数 --json 非必填、默认 False，用于输出供 AI 使用的结构化 JSON。退出码：0=已配置，1=部分配置，2=未配置。建议在任何 HeyReach 操作之前首先运行，用于验证 API 密钥是否已配置、诊断认证问题或检查是否需要设置。
heyreach_client.py：共享 API 客户端。示例用法：

from heyreach_client import get_client, HeyReachError
client = get_client()
result = client.post("/v2/campaigns/All", {"offset": 0, "limit": 100})

其特性包括：自动重试与指数退避、速率限制处理（300 req/min）、一致的错误响应、从 .env 管理 API 密钥。

使用方式

智能错误检测流程：当某个 HeyReach 技能因缺少配置而失败时，AI 应：

运行带 JSON 输出的配置检查：python 00-system/skills/heyreach/heyreach-master/scripts/check_heyreach_config.py --json
解析 ai_action 字段，按以下映射处理：proceed_with_operation（配置正常，继续原操作）；prompt_for_api_key（询问用户提供 API 密钥）；create_env_file（创建 .env 文件并询问用户凭据）；verify_api_key（密钥存在但连接失败，验证是否正确）；retry_later（API 超时，稍后重试）；check_network（连接错误，检查网络）。
帮助用户修复问题。若 ai_action 为 prompt_for_api_key：告知用户集成需要设置并索要 API 密钥，提示其从 HeyReach 的 Settings → API 获取，请其粘贴密钥，收到后直接写入 .env：HEYREACH_API_KEY=their-key-here，然后重新运行配置检查进行验证。

环境变量：.env 中需要 HEYREACH_API_KEY=your-api-key-here。

API 基础 URL：所有 API 请求发送至 https://api.heyreach.io/api/public；认证头为 X-API-KEY: {api_key}；速率限制为 300 请求/分钟。

脚本使用示例：

列出活动：

from heyreach_client import get_client
client = get_client()
result = client.post("/v2/campaigns/All", {"offset": 0, "limit": 100})
campaigns = result.get("items", [])

获取活动详情：

result = client.get(f"/v2/campaigns/{campaign_id}")

添加潜在客户：

leads = [
    {"linkedInUrl": "https://linkedin.com/in/user1"},
    {"linkedInUrl": "https://linkedin.com/in/user2"}
]
result = client.post(f"/v2/campaigns/{campaign_id}/leads", {"leads": leads})

错误处理示例：

from heyreach_client import get_client, HeyReachError

try:
    client = get_client()
    result = client.get("/v2/campaigns/123")
except HeyReachError as e:
    print(f"Error {e.status_code}: {e.message}")
except ValueError as e:
    print(f"Config error: {e}")

适用场景

需要通过脚本或 AI 技能与 HeyReach API 交互、并希望在多个技能之间共享认证配置、API 文档与错误处理逻辑的场景。所有 HeyReach 技能都以渐进式披露方式引用这些共享资源。

限制

资料未提供关于费用、平台支持范围、具体效果等方面的信息，暂未提供。版本为 1.0，创建时间 2025-12-19，状态为 Production Ready。

技能介绍

用途

主要能力

使用方式

适用场景

限制