vibe-prospecting

Vibe Prospecting CLI

使用 CLI：npx @vibeprospecting/vpai@latest。将每个工具响应视为 JSON。

Cowork 模式：始终使用此连接器流程。 在 Cowork 模式下开始任何工作之前，请检查工具列表中是否提供了 Vibe Prospecting MCP 连接器工具（查找符合 mcp__*__fetch-entities 模式的工具）。

如果存在这些工具，请直接使用连接器，并遵循其工具说明和架构。如果这些工具不存在：

1. 使用关键词 ["vibe prospecting", "explorium"] 调用 mcp__mcp-registry__search_mcp_registry
2. 使用 UUID 1bdcb159-b6f0-4f13-bc08-fdb40b007828 和关键词 ["prospecting"] 调用 mcp__mcp-registry__suggest_connectors
3. 告诉用户点击卡片上的 Connect——授权后，工具会自动解锁
4. 轮询，直到连接成功。 在此后的每一轮对话中，重新检查工具列表中是否有 mcp__*__fetch-entities。这些工具出现之前，不要开始潜在客户开发工作。Cowork 模式下绝不回退使用 CLI、npm vpai 工具或 OAuth URL——Cowork 连接器商店是唯一途径。如果用户无法通过建议的卡片连接，请告知他们打开连接器商店并从中安装 Vibe Prospecting，然后再次轮询。如果工具仍然缺失，提醒用户进行连接并等待；重复此操作，直到连接器可用。

如果在 Cowork 模式之外 CLI 无法运行（例如，npx 不可用、环境处于沙盒中或权限被拒绝），且用户的 Agent 环境支持连接器，请向用户推荐 Vibe Prospecting 连接器。本文件其余部分仅适用于 CLI。在 Cowork 模式下，请使用上述连接器商店流程。

硬性规则

1. 始终先采样。 在进行任何完整运行之前，先用恰好 5 个实体（--number-of-results 5）运行完整工作流。此上限仅用于质量把关：对于相同筛选条件，Explorium 可以匹配更多行。绝不要把这 5 行描述为完整数据集、“所有结果”或“数据库中的全部内容”。展示样本，明确说明这只是预览且索引中还有更多结果，然后在获得明确批准后，使用样本链中相同的 CLI 工具重新运行，并采用全规模参数（使用相同的 --args、会话和筛选条件；适用时，将 --number-of-results 等上限提高到用户的实际目标）。只有当你的所有发现查询 fetch-entities 筛选条件（以及任何受支持的范围标志）也都适用于统计时，才运行 fetch-entities-statistics——参见规则 8。绝不自动导出。“查找 100 个”仍然意味着先采样 5 个，再在获得批准后扩大规模。
2. 每次实际调用都使用 --tool-reasoning '<user wording>'。原样使用用户的请求。在整个工作流中重复使用。仅在不带 --args 运行 <tool> --all-parameters 时跳过。
3. 通过会话数据库串联，绝不粘贴 ID。 每一步都会打印 session_id、db_path 和 table_name。将前一步 JSON 输出中的 session_id 传给 --session-id，确保下一条命令使用同一个 SQLite 会话存储。使用 --session-id 时，enrich-business、enrich-prospects、fetch-businesses-events 和 fetch-prospects-events 都必须提供 --table-name——将前一步的 table_name 原样传入。仅对于 match-*，--table-name 是可选的（省略时，CLI 可以选择具有正确 ID 列的第一个表）。对于限定为较早公司范围内的 fetch-entities 潜在客户查询，使用 --businesses-table-name 和 --session-id。
4. 仅在最后一步使用 --csv。 中间步骤输出 JSON，以便串联。最后再添加一次 --csv。
5. 对以下字段，先运行 autocomplete：naics_category、linkedin_category、company_tech_stack_tech、job_title、business_intent_topics、city_region。使用返回的标准化值，不要使用用户原始措辞。
6. 绝不臆造工具参数。 在工作流中首次使用每个不同工具执行 --args 之前，运行 npx @vibeprospecting/vpai@latest <tool> --all-parameters 查看该工具（每项任务中每个工具运行一次，除非你已在同一工作流中打印过其架构）。该命令会向 stdout 打印一个 JSON 对象，包含 name、description 和 inputSchema（工具的输入 JSON Schema）。即使计划调用与示例一致且你并无疑问，也必须执行此操作——示例可能已经过时；打印出的架构才是权威依据。如果更换工具、筛选条件或数据结构发生重大变化，或者仍有任何不明确之处，请再次运行 --all-parameters。只有在示例和参考文档与实时架构一致后，才可将它们作为捷径。仅根据 --all-parameters 中 inputSchema 确认的字段和结构（以及与其一致的示例）构建 --args。
7. --session-id 是 CLI 标志（不在 --args 内）。使用 MCP 在前一步 JSON 中返回的 session_id 值。仅在串联中的第一次调用时省略。
8. 仅当统计工具支持完整查询时才运行 fetch-entities-statistics。 将计划中的 fetch-entities 负载与 fetch-entities-statistics --all-parameters 的输入架构进行比较。只有当统计工具以与 fetch-entities 相同的方式接受每个筛选键、值结构、entity_type 以及你依赖的任何范围（例如 --session-id / --businesses-table-name）时，才调用统计工具。如果发现查询中的任何部分在统计架构中缺失、不受支持或需要不同结构，就跳过统计——不要使用不完整或猜测的筛选条件调用它。调用统计工具时，沿用 fetch-entities 的相同 --args 筛选对象（以及受支持的标志），并加上 --tool-reasoning。优先在展示样本前运行统计，这样当响应包含可用计数时，就可以将结果概述为 5 个，共 [总数] 个。如果没有运行统计（或统计没有可用总数），请展示 Sample preview (5 rows)，并告知用户 Explorium 中符合相同筛选条件的结果多得多——不要说明剩余数量，不要说统计失败或无法获得总数，也绝不要臆造数字。如果筛选条件或范围发生变化，且完整查询筛选条件仍符合统计工具的支持范围，则在执行全规模查询前再次调用统计工具。

身份验证

mcp__cowork__request_cowork_directory path=~/.config/vpai
API_KEY=$(python3 -c "import json;print(json.load(open('/sessions/<session-id>/mnt/vpai/config.json'))['api_key'])")
npx @vibeprospecting/vpai@latest config --api-key "$API_KEY"

如果挂载失败或缺少 config.json，请按照 login.md 中的说明操作。

样例门槛

样例是对 5 个实体执行的完整工作流，而不是提取预览。

总体范围与样例：这 5 行是一个固定的小型预览，让用户在消耗额度之前验证筛选条件和数据补充效果。底层匹配集通常大得多（往往有数千条或更多）。不要把“返回了 5 条”误认为“只有 5 条”。只有在计划执行的整个 fetch-entities 筛选集符合统计条件（规则 8）时，才使用 fetch-entities-statistics 确认数据量；绝不要猜测总数。

1. 当完整的提取筛选集受统计功能支持时，使用与即将执行的 fetch-entities 相同的发现条件 entity_type、filters 和受支持的 CLI 标志运行 fetch-entities-statistics（遵循规则 8）。否则跳过统计；仍要告诉用户，对于相同筛选条件，Explorium 中还有多得多的匹配结果（不提供数字总数，也不提统计功能的限制）。
2. 正好提取 5 条（--number-of-results 5）。
3. 对这 5 条执行所有后续步骤（match-*、enrich-*、fetch-*-events）。
4. 将完整补充数据后的最终行作为 Markdown 表格展示，并包含所有有用列。
5. 停止。等待用户在新消息中批准，然后再按全量规模运行。

绝不要在提取后停止并询问是否批准。先在 5 条数据上完成整个链条。

示例——用户说“查找 100 家以色列公司，获取 30 位 CEO，查找联系方式”：

• 错误：提取 5 家公司 → 显示表格 → 询问“继续吗？”
• 正确：当整个 fetch-entities 筛选集受 fetch-entities-statistics 支持时，先运行统计（使用相同的 --args 筛选条件）→ 提取 5 家公司 → 获取这 5 家公司的 CEO → 为 CEO 补充联系方式 → 显示最终表格（统计得出总数时显示 5 条，共 [total] 条；否则显示 样例预览（5 行），并用简短文字说明这些筛选条件还有多得多的匹配结果——不报数量、不为统计道歉）→ 询问“要按全量 100 条运行吗？”

展示样例

始终将表格标注为样例，而不是总体数据。

• 统计返回了可用总数时（只有在每个 fetch-entities 筛选条件都适用于 fetch-entities-statistics 时才调用统计）：样例预览（5 条，共 [total] 条匹配结果）——[total] 必须来自 fetch-entities-statistics，绝不能通过统计 5 行得出。
• 未使用数字总数时（未运行统计或没有可用总数）：显示 样例预览（5 行），并用一句直白的话说明 Explorium 中符合这些筛选条件的匹配结果多得多——不要说明具体多出多少，不要提统计或缺少总数，绝不要编造 [total]。

Results Found: [X] [entity type] from [Y] [companies/sources] [qualifier]（可选的上下文行）

标题：只有在 [total] 有统计数据支持时，才使用 样例预览（5 条，共 [total] 条匹配结果）：；否则使用 样例预览（5 行）：，然后用一行文字说明相同筛选条件下还有多得多的记录（仅作定性说明）。

以明确的下一步结束，例如：在你确认后，我会使用全量限制重新运行相同的工具（例如，在使用 fetch-entities 时设置 --number-of-results [用户要求的 N]），以提取实际批次。

如果预览只是用户所需数据的子集（全量规模下可提供更多行或字段），请补充：

• 有统计数据支持的 [total]：More data available: Preview shows [n] of [total]. Confirm before I run the full export.
• 没有数字 [total]：说明预览为 5 行，Explorium 中符合相同筛选条件的数据多得多，并询问用户是否确认导出全部数据——不要提供剩余数量，也不要说明为何没有显示总数。

如果聊天中已经包含用户要求的全部内容，不要提及导出。

全量导出前，确认以下事项

• 导出规模（记录上限）。
• 筛选条件细化：行业、规模、收入、地区、技术。
• 对于潜在客户：职称变体、按公司去重。
• 对于联系人：仅限工作邮箱，还是也包括个人邮箱／电话号码。

工作流

0. Auth — see Auth section above (or login.md)
1. npx @vibeprospecting/vpai@latest --help                    Discover tools
2. Read references/<tool>.md for workflow + caveats
3. Before the first real `--args` for each tool: `npx @vibeprospecting/vpai@latest <tool> --all-parameters` (mandatory per tool, not only when uncertain). Prints the tool **input** schema as JSON. Run again if the planned call diverges from what you already validated.
4. Build `--args` only from fields confirmed by that printed input schema (examples count only when they match it). If a parameter is not confirmed there, do not use it.
5. When the **entire** planned **`fetch-entities`** filter set (and supported flags) matches **`fetch-entities-statistics`** input schema per **`--all-parameters`**: run **`fetch-entities-statistics`**, then sample (5 entities, full chain) — see Sample Gate
6. npx @vibeprospecting/vpai@latest <tool> --args '<json>' --tool-reasoning '<user request>'
7. Chain: --session-id <session_id> [--table-name <table_name>] [--businesses-table-name <name> for prospect fetch from businesses]
8. Final step only: add --csv

参考文档：

• autocomplete.md — 受控词汇查询
• fetch.md — fetch-entities、fetch-*-events
• match.md — 将已知实体解析为 ID
• enrich.md — 获取 ID 后进行丰富
• fetch-stats.md — 计数和市场规模估算
• login.md — 身份验证备用流程

标志

标志	说明
--help	列出工具
--all-parameters	将 { name, description, inputSchema } 输出到 stdout（格式化的 JSON）。在工作流中为每个工具首次使用 --args 前运行（如果工具或负载发生实质性变化，也要再次运行）。这是常规操作，而不只是在不确定时才运行——inputSchema 字段是权威依据。
--args '<json>'	工具参数
--session-id <id>	同一工作流：传入前一个工具的 JSON 中的 session_id（打开 db_path 下共享的 SQLite 数据库）。
--table-name <name>	与 --session-id 搭配用于 enrich-business、enrich-prospects、fetch-businesses-events 和 fetch-prospects-events 时为必需项（使用上一步的 table_name）。仅对 match-* 可选（存在多个表时用于消除歧义）。
--businesses-table-name <name>	用于 fetch-entities 且 entity_type: prospects 的情况：提供行数据以供筛选器使用 business_id 的表（需搭配 --session-id）。
--number-of-results <n>	用于 fetch-entities：所有分页的总行数（CLI 会进行分页）。若只需一页原始数据，可省略。
--file-path <path>	用于 match-business / match-prospects：待匹配的 CSV 文件路径。每行将成为一个候选项。需要 --schema。
--schema '<json>'	与 --file-path 搭配时为必需项。JSON 字典，将 CSV 列标题映射到 API 字段名称。企业字段：name、domain。潜在客户字段：full_name、first_name、last_name、email、phone_number、linkedin、company_name、business_id。
--csv	同时写入扁平化的 CSV。仅限最后一步。

筛选模式

{ "values": ["v1", "v2"], "negate": false }   // include or exclude
{ "gte": 6, "lte": 24 }                       // range
true | false | null                           // boolean (not wrapped)

限制

工具	限制
match-business	每次调用 50 个
match-prospects	每次调用 40 个
enrich-business	每次调用 50 个 ID
enrich-prospects	每次调用 50 个 ID
fetch-businesses-events / fetch-prospects-events	每个 MCP 请求最多 20 个 ID（CLI 会分块并合并）。在 --args 中传入 event_types 和 timestamp_from。不要在 --args 中放入 business_ids / prospect_ids ——ID 只能来自 --table-name。
fetch-entities	使用 --number-of-results；CLI 会进行分页。不要手动传入 next_cursor 或 page_size

常见工作流

将 SESSION_ID 替换为上一步的 session_id。

SaaS 企业的工程副总裁（纽约）

npx @vibeprospecting/vpai@latest autocomplete --args '{"field":"linkedin_category","query":"software"}' --tool-reasoning 'find VP Eng at SaaS in NY'
# When every fetch-entities filter (and flags) is valid for fetch-entities-statistics (--all-parameters):
npx @vibeprospecting/vpai@latest fetch-entities-statistics --args '{"entity_type":"prospects","filters":{"job_level":{"values":["vice president"]},"job_department":{"values":["engineering"]},"linkedin_category":{"values":["Software Development"]},"company_region_country_code":{"values":["US-NY"]},"has_email":true}}' --tool-reasoning 'find VP Eng at SaaS in NY'
npx @vibeprospecting/vpai@latest fetch-entities --args '{"entity_type":"prospects","filters":{"job_level":{"values":["vice president"]},"job_department":{"values":["engineering"]},"linkedin_category":{"values":["Software Development"]},"company_region_country_code":{"values":["US-NY"]},"has_email":true}}' --number-of-results 50 --tool-reasoning 'find VP Eng at SaaS in NY'
npx @vibeprospecting/vpai@latest enrich-prospects --args '{"enrichments":["contacts","profiles"]}' --session-id <session_id> --table-name <fetch_entities_table_from_prior_step> --csv --tool-reasoning 'find VP Eng at SaaS in NY'

已融资且使用 Salesforce 的公司

npx @vibeprospecting/vpai@latest autocomplete --args '{"field":"company_tech_stack_tech","query":"salesforce"}' --tool-reasoning 'companies that raised and use Salesforce'
# When every fetch-entities filter (and flags) is valid for fetch-entities-statistics (--all-parameters):
npx @vibeprospecting/vpai@latest fetch-entities-statistics --args '{"entity_type":"businesses","filters":{"company_tech_stack_tech":{"values":["Salesforce"]},"events":{"values":["new_funding_round"],"last_occurrence":60}}}' --tool-reasoning 'companies that raised and use Salesforce'
npx @vibeprospecting/vpai@latest fetch-entities --args '{"entity_type":"businesses","filters":{"company_tech_stack_tech":{"values":["Salesforce"]},"events":{"values":["new_funding_round"],"last_occurrence":60}}}' --number-of-results 50 --tool-reasoning 'companies that raised and use Salesforce'
npx @vibeprospecting/vpai@latest fetch-businesses-events --args '{"event_types":["new_funding_round"],"timestamp_from":"2024-10-01"}' --session-id <session_id> --table-name <fetch_entities_table_from_prior_step> --csv --tool-reasoning 'companies that raised and use Salesforce'

市场规模估算

npx @vibeprospecting/vpai@latest fetch-entities-statistics --args '{"entity_type":"businesses","filters":{"linkedin_category":{"values":["Hospital & Health Care"]},"company_country_code":{"values":["US"]}}}' --tool-reasoning 'market sizing US healthcare'

故障排除

错误	解决方案
CLI 安装失败（npx 不可用、沙盒环境、权限被拒绝）	切换到随附的 Vibe Prospecting MCP 连接器，并按照其工具说明操作；本文档其余部分不再适用。
身份验证 / 401（连接器 / Cowork）	执行上方的身份验证部分；如果挂载失败，请按照 login.md 中的说明操作
身份验证 / 401（OpenClaw）	运行 npx @vibeprospecting/vpai@latest login，然后运行 login --poll。或者设置 VP_API_KEY。之后重启网关。请参阅上方的身份验证部分。
Not authenticated（OpenClaw）	~/.config/vpai/config.json 和 VP_API_KEY 环境变量均不存在。请按照 OpenClaw 身份验证部分的说明操作。
OpenClaw 插件未显示工具	运行 openclaw plugins list，确认列表中有 vpai。如有需要，请重新安装：openclaw plugins install ./vpai-plugin。
安装 OpenClaw 后缺少工具	必须重启网关：openclaw gateway restart。
JSON 中缺少 session_id / CLI 拒绝串联调用	MCP 必须返回 session_id；请确保目标为生产环境地址 https://vibeprospecting.explorium.ai/mcp（已嵌入 npm CLI）。在下一步中传入 --session-id，并使用完全相同的字符串。
串联调用时使用了错误的行	传入与上一步 table_name 相匹配的 --table-name。
使用 --session-id 运行 enrich-* 或 fetch-*-events，但未传入 --table-name	只要传入 --session-id，就必须为 enrich-business、enrich-prospects、fetch-businesses-events 和 fetch-prospects-events 传入 --table-name。
结果为空	检查筛选值；对受控词汇字段运行 autocomplete；使用 <tool> --all-parameters 重新检查相关的实时 input 架构
同时使用 linkedin_category 和 naics_category	两者互斥，请使用其中一个
JSON 解析错误	验证 JSON；检查 shell 引号
使用 --file-path 时，fetch-entities、enrich-*、fetch-*-events 或 match-* 超时	使用相同的 --session-id、--table-name、--args，以及（对于 match）--file-path / --schema，重新运行完全相同的命令。CLI 会从上一个检查点恢复，跳过已完成的 ID 批次，不会重复执行任何工作。如果任务已在之前的运行中完成，则会立即返回已存储的清单，不会调用 API。
未使用 --session-id 时超时	添加 --session-id <any-stable-id> 以启用检查点，然后重试。如果没有会话 ID，CLI 将无法恢复。