pp-contact-goat

Contact Goat - Printing Press 命令行工具

前提条件：安装 CLI

此技能通过 contact-goat-pp-cli 二进制文件运行。**调用此技能中的任何命令前，必须先确认已安装 CLI。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install contact-goat --cli-only
   

2. 验证：contact-goat-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/contact-goat/cmd/contact-goat-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿继续运行技能命令。

何时使用此 CLI

用户需要以下功能时，请使用此 CLI：

• 了解一家公司的覆盖情况（你已经认识该公司的哪些人，以及按关系强度排序的名单）
• 找到联系目标人物的熟人引荐路径（跨来源的共同联系人）
• 寻找潜在客户（扇出搜索并去除跨来源重复结果）
• 整合档案（LinkedIn 个人资料 + Happenstance 调研 + 可选的 Deepline 信息补充）
• 查看随时间变化的关系网络差异（过去 N 天内，你的关系网络中有哪些新增内容）
• 按顺序遍历免费来源，再使用付费来源进行瀑布式信息补充

如果用户的工作流完全在 LinkedIn Sales Navigator 中进行，或只需要抓取原始 LinkedIn 数据而不需要 Happenstance 或 Deepline 的叠加功能，请勿使用此 CLI（在这种情况下，请直接使用 LinkedIn MCP）。

两种身份验证方式

Happenstance 提供两种并行的身份验证方式，CLI 会同时使用：

方式	身份验证	费用	默认方式？
Cookie Web 应用	Chrome 会话 Cookie	每月免费额度	是（自动优先使用）
公共 REST API	HAPPENSTANCE_API_KEY（Bearer）	每次搜索 2 个点数，每次调研 1 个点数	仅作备用

自动路由器会优先使用 Cookie，直到额度用尽，然后改用 Bearer，并在 stderr 上输出明确的“已花费点数”日志。可在 coverage、hp people、prospect 或 warm-intro 上使用 --source api，显式选择 Bearer（例如，为使用更丰富的调研架构或限定范围的群组搜索）。使用 --source hp 可强制使用 Cookie 方式。

api hpn * 子命令始终使用 Bearer 方式，且始终会消耗点数。请在 https://happenstance.ai/settings/api-keys 创建和轮换密钥。

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help -> 运行 contact-goat-pp-cli --help
2. 以 install 开头且以 mcp 结尾 -> 安装 MCP（见下文）
3. 以 install 开头 -> 安装 CLI（见下文）
4. 其他任何内容 -> 直接使用（将请求映射到最合适的命令并运行）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/sales-and-crm/contact-goat/cmd/contact-goat-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add -e DEEPLINE_API_KEY=value -e HAPPENSTANCE_API_KEY=value contact-goat-pp-mcp -- contact-goat-pp-mcp
   

   运行前，向用户询问必需 API 密钥的实际值。
3. 验证：claude mcp list。

MCP 服务会公开 16 个工具。本次发布新增的四个 Bearer API 工具如下：

• api_search - 执行 Happenstance 公共 API 搜索（消耗 2 个点数）
• api_research - 执行深度调研档案检索（完成后消耗 1 个点数）
• api_groups_list - 列出调用者的 Happenstance 群组（免费）
• api_usage - 显示实时点数余额和使用历史（免费）

其他 12 个工具涵盖 Cookie 方式（搜索、好友、动态、通知、档案等）以及 LinkedIn / Deepline 集成。

直接使用

1. 检查是否已安装：which contact-goat-pp-cli。如果未找到，请提供 CLI 安装方式（见上文）。
2. 查看可用命令：contact-goat-pp-cli --help。使用 contact-goat-pp-cli <command> --help 或 contact-goat-pp-cli api hpn <subcommand> --help 查看子命令的帮助信息。
3. 根据用户的查询选择最合适的命令（见下文的“重要命令”）。
4. 使用 --agent 标志执行，以获得结构化且节省令牌的输出：

   contact-goat-pp-cli <command> [args] --agent
   

5. --agent 标志会设置 --json --compact --no-input --no-color --yes。

来源路由（cookie 与 bearer）会自动进行。自动路由优先使用免费的 cookie 接口，仅在 cookie 配额耗尽时才回退到付费的 bearer 接口，并在 stderr 上记录“已产生费用”提示。传入 --source api 可显式选择 bearer（架构更丰富，支持按群组范围搜索），或传入 --source hp 强制使用 cookie。

数据增强前置检查（运行任何数据增强命令前请阅读）

以下命令会消耗 Deepline 额度，且需要 DEEPLINE_API_KEY 或 BYOK 配置：

• waterfall（除非传入 --byok 且已配置 BYOK 提供商）
• dossier --enrich-email
• deepline find-email / enrich-person / email-find / phone-find
• deepline search-people / search-companies / enrich-company

调用任何这些命令前，请先运行 doctor 验证身份验证状态：

contact-goat-pp-cli doctor --agent | grep -i deepline

deepline_env 会显示凭据的来源：

• set (env) — 当前 shell 中已导出 DEEPLINE_API_KEY
• set (flag) — 在命令行中传入了 --deepline-key
• set (file:~/.local/deepline/<host>/.env) — 从官方 Deepline CLI 持久化保存的密钥中自动发现（用户已运行 deepline auth register 或 deepline auth status 进行身份验证；无需在 shell 中导出密钥）
• not set — 以上来源均不存在。向用户索取密钥，或索取 BYOK Hunter/Apollo 密钥

自动发现机制意味着，安装并通过身份验证的 Deepline CLI 用户无需在 shell 中重新导出密钥；contact-goat 会直接读取 ~/.local/deepline/code-deepline-com/.env（权限模式为 0600，由用户拥有）。如果报告 set (file:...)，不要要求用户重新导出密钥。如果同时报告 deepline_discovery_skipped，则表示解析器因安全原因拒绝了这些候选文件（权限模式不正确或缺少前缀）；请告知用户这些文件，以便他们修复根本问题。

按目标类型排列的提供商链（waterfall）：

目标	主要提供商	备用提供商 1	备用提供商 2
LinkedIn URL	apollo_people_match	hunter_people_find	contactout_enrich_person
电子邮件	apollo_people_match	hunter_people_find	-
姓名 + --company	dropleads_email_finder	hunter_email_finder	datagma_find_email

注意：

• 姓名目标必须传入 --company <domain>（或设置 CONTACT_GOAT_COMPANY 环境变量）。
• 如有可用数据，Apollo 会返回 personal_emails[]；请将 email_status: "unavailable" 视为“记录中没有经过验证的工作邮箱”（个人邮箱仍可使用）。
• 对于使用 Google Workspace 的域名，Dropleads 会返回 status: "catch_all"；该电子邮件地址是模式推测，并非经过验证的邮箱。
• 提供商级别的 403 会显示为“提供商未连接”，而不是“检查 DEEPLINE_API_KEY”；这类错误不会中止调用链，系统会自动尝试下一个提供商。

重要命令

命令	功能
coverage <company>	查看你在某家公司的 LinkedIn + Happenstance 人脉，并按关系强度排序
coverage --location <city>	查看你在某座城市的人脉。仅支持 Bearer；Cookie 接口不支持城市搜索，请使用 --source api。
hp people <query>	搜索 Happenstance 图谱中的人物（1 度 / 2 度 / 3 度）。--csv 会输出扁平化 CSV，桥接关系以分号连接。
prospect <query>	在 LinkedIn + Happenstance（以及选择启用的 Deepline）中展开搜索，并去重
warm-intro <target>	查找不同来源中可为你引荐目标对象的共同联系人
waterfall <target> [--company X]	优先使用免费来源进行信息补充，再转到 Deepline 提供商链。需要 DEEPLINE_API_KEY 或 --byok。目标仅提供姓名时，必须指定 --company
dossier <target> [--enrich-email]	汇总 LinkedIn + Happenstance +（可选）Deepline 信息。--enrich-email 需要 DEEPLINE_API_KEY
deepline find-email "<name>" --company <domain>	通过 dropleads_email_finder 单次调用查询工作邮箱
deepline enrich-person <linkedin-url>	通过 apollo_people_match 获取完整人物记录（包括 personal_emails[]）
api hpn search <text>	Bearer API 搜索（消耗 2 个额度，异步执行并轮询）。--first-degree-only 仅保留 1 度匹配；--min-score N 剔除较弱信号（参见 docs/scoring.md）；--all --max-results N 自动翻页。
api hpn research <description>	Bearer API 深度档案查询（完成时消耗 1 个额度）
api hpn usage	实时额度余额、购买记录和近期使用事件（免费）
doctor	检查 CLI 健康状态、两个 Happenstance 接口、LinkedIn 和 Deepline。报告 LinkedIn 上传距今时间对应的 happenstance_graph_status（ok / stale / very_stale）。

运行任意命令时添加 --help，即可查看完整的标志说明。

Agent 模式

为任意命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可通过管道传输 — JSON 输出到 stdout，错误输出到 stderr
• 可筛选 — --select 保留部分字段，支持点分路径（见下文）
• 可预览 — --dry-run 显示请求内容，但不发送
• 可缓存 — GET 响应缓存 5 分钟，可通过 --no-cache 绕过
• 非交互式 — 从不提示输入，所有输入都通过标志指定

筛选输出

--select 接受点分路径以深入访问嵌套响应；数组会逐元素遍历：

contact-goat-pp-cli <command> --agent --select id,name
contact-goat-pp-cli <command> --agent --select items.id,items.owner.name

使用此功能可将超大负载缩小到所需字段，这对深度嵌套的 API 响应尤为重要。

响应封装

数据层命令会将输出封装为 {"meta": {...}, "results": <data>}。解析 .results 获取数据，并查看 .meta.source 以判断数据来自 live 还是本地。只有当 stdout 是 TTY 时，N results (live) 摘要才会输出到 stderr；通过管道接收的内容或 Agent 消费者在 stdout 上只会看到纯 JSON。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题，包括 Bearer 额度不足时的 402）
7	请求受限（Cookie 429 或 Bearer 429；可能会自动回退）