vibe-prospecting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vibe Prospecting CLI

Use the CLI:

npx @vibeprospecting/vpai@latest

. Treat every tool response as JSON.

Cowork mode: always use this connector flow. Before doing any work in Cowork mode, check whether the Vibe Prospecting MCP connector tools are available in your tool list (look for a tool matching the pattern

mcp__*__fetch-entities

If those tools are present, use the connector directly and follow its tool descriptions and schemas. If those tools are NOT present:

Call

mcp__mcp-registry__search_mcp_registry

with keywords

["vibe prospecting", "explorium"]

Call

mcp__mcp-registry__suggest_connectors

with the UUID

1bdcb159-b6f0-4f13-bc08-fdb40b007828

and keywords

["prospecting"]

Tell the user to click Connect on the card — the tools unlock automatically once authorized
Poll until connected. On every subsequent turn, re-check your tool list for
```
mcp__*__fetch-entities
```
. Do not start prospecting work until those tools appear. Never fall back to the CLI, the npm
```
vpai
```
tool, or an OAuth URL in Cowork mode — the Cowork connector store is the only path. If the user cannot connect from the suggested card, tell them to open the connector store and install Vibe Prospecting from there, then poll again. If tools are still missing, remind the user to connect and wait; repeat until the connector is available.

If the CLI does not work outside Cowork mode (e.g.

npx

unavailable, sandboxed environment, permission denied), and the user's agent environment supports connectors, suggest the Vibe Prospecting connector to the user. The rest of this file is CLI-only. In Cowork mode, use the connector store flow above.

使用CLI：

npx @vibeprospecting/vpai@latest

。将所有工具响应视为JSON格式。

协同模式：始终使用此连接器流程。在协同模式下开展任何工作前，请检查你的工具列表中是否有Vibe Prospecting MCP连接器工具（查找匹配

mcp__*__fetch-entities

模式的工具）。

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

调用

mcp__mcp-registry__search_mcp_registry

，参数关键词为

["vibe prospecting", "explorium"]

使用UUID

1bdcb159-b6f0-4f13-bc08-fdb40b007828

和关键词

["prospecting"]

调用

mcp__mcp-registry__suggest_connectors

告知用户点击卡片上的Connect按钮——授权后工具将自动解锁
轮询直到连接完成。在后续每一轮中，重新检查工具列表是否有
```
mcp__*__fetch-entities
```
。在这些工具出现前，不要开始潜在客户开发工作。绝对不要退回到CLI、npm
```
vpai
```
工具或协同模式下的OAuth URL——协同连接器商店是唯一路径。如果用户无法从推荐卡片连接，告知他们打开连接器商店并从中安装Vibe Prospecting，然后再次轮询。如果工具仍未出现，提醒用户连接并等待；重复此步骤直到连接器可用。

如果CLI在协同模式外无法工作（例如

npx

不可用、沙箱环境、权限被拒绝），且用户的Agent环境支持连接器，建议用户使用Vibe Prospecting连接器。本文档其余部分仅适用于CLI。在协同模式下，请使用上述连接器商店流程。

Hard Rules

硬性规则

Sample first, always. Run the COMPLETE workflow on exactly 5 entities (
```
--number-of-results 5
```
) before any full run. That cap is a quality gate only: Explorium can match many more rows for the same filters. Never describe those 5 rows as the full dataset, "all results," or "what the database has." Show the sample, state clearly that it is a preview and the index has more, then after explicit approval re-run the same CLI tool(s) you used in the sample chain with full-scale parameters (same
```
--args
```
, session, and filters; raise caps such as --number-of-results
to the user's real target where that flag applies). Run fetch-entities-statistics
only when all of your discovery fetch-entities
filters (and any supported scope flags) are valid for statistics too — see rule 8. Never auto-export. "Find 100" still means sample 5 first, then scale up after approval.
--tool-reasoning '<user wording>'
on every real call. Use the user's request verbatim. Reuse across the whole workflow. Skip ONLY when running
```
<tool> --all-parameters
```
with no
```
--args
```
.
Chain via session DB, never paste IDs. Each step prints
```
session_id
```
,
```
db_path
```
, and
```
table_name
```
. Pass --session-id
with the session_id
from the prior JSON output so the next command uses the same SQLite session store. With --session-id
, --table-name
is required for enrich-business
, enrich-prospects
, fetch-businesses-events
, and fetch-prospects-events
— pass the prior step's table_name
exactly. For match-*
only, --table-name
is optional (CLI can pick the first table with the right ID column when omitted). For fetch-entities
prospects scoped to earlier companies, use --businesses-table-name
plus --session-id
.
--csv
only on the final step. Intermediate steps emit JSON for chaining. Add
```
--csv
```
once, at the end.

autocomplete
first for:

naics_category

linkedin_category

company_tech_stack_tech

job_title

business_intent_topics

city_region

. Use returned standardized values, not raw user wording.

Never invent tool parameters. Before the first
```
--args
```
execution of each distinct tool in a workflow, run
```
npx @vibeprospecting/vpai@latest <tool> --all-parameters
```
for that tool (once per tool per task unless you already printed its schema earlier in the same workflow). That command prints one JSON object to stdout: name
, description
, and inputSchema
(the tool input JSON Schema). Do this even when the planned call matches the examples and you are not uncertain—examples can drift; the printed schema is authoritative. Run
```
--all-parameters
```
again if you change tools, filters, or shapes materially, or if anything still feels ambiguous. You may use examples and reference docs as shortcuts only after they align with that live schema. Build
```
--args
```
only from fields and shapes confirmed by inputSchema
from
```
--all-parameters
```
(and examples when they match it).
--session-id
is a CLI flag (not inside
```
--args
```
). Use the session_id
value returned by the MCP in each prior step's JSON. Omit only on the first call in a chain.
fetch-entities-statistics
only when stats supports the full fetch. Compare your planned fetch-entities
payload to the input schema from fetch-entities-statistics --all-parameters
. Call statistics only if every filter key, value shape, entity_type
, and any scope you rely on (e.g. --session-id
/ --businesses-table-name
) is accepted by the statistics tool the same way it is for fetch-entities
. If any part of the discovery query is missing from the stats schema, unsupported, or would require a different shape, skip stats — do not call it with a partial or guessed subset. When you do call it, reuse the same --args
filter object (and supported flags) as fetch-entities
, plus --tool-reasoning
. Prefer running stats before presenting the sample so you can headline 5 of [total] when the response includes a usable count. When you did not run statistics (or stats had no usable total), present Sample preview (5 rows) and tell the user Explorium has much more matching the same filters—do not quote how many remain, do not say statistics failed or a total was unavailable, and never invent a number. Call stats again before a full-scale fetch if filters or scope changed and the full fetch filter set still fits statistics.

始终先运行样本。在进行任何完整运行前，针对恰好5个实体（
```
--number-of-results 5
```
）运行完整工作流。此上限仅为质量检查门槛：Explorium可以为相同筛选条件匹配更多行。绝对不要将这5行描述为完整数据集、"所有结果"或"数据库中的全部内容"。展示样本，明确说明这是预览且索引中还有更多数据，然后在获得明确批准后重新运行你在样本流程中使用的相同CLI工具（使用相同的
```
--args
```
、会话和筛选条件；将
```
--number-of-results
```
等上限提升至用户实际目标值）。仅当你所有的发现型
```
fetch-entities
```
筛选条件（以及任何支持的范围标志）同样适用于统计时，才运行
```
fetch-entities-statistics
```
——参见规则8。绝不自动导出。"查找100条"仍意味着先运行5条样本，然后在批准后扩大规模。
每次实际调用都添加
--tool-reasoning '<用户原话>'
。直接使用用户的请求内容。在整个工作流中重复使用。仅当运行
```
<tool> --all-parameters
```
且未使用
```
--args
```
时可跳过。
通过会话数据库链式调用，绝不粘贴ID。每一步都会输出
```
session_id
```
、
```
db_path
```
和
```
table_name
```
。传递
```
--session-id
```
参数，值为上一步JSON输出中的
```
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
```
。
仅在最后一步使用
--csv
。中间步骤输出JSON用于链式调用。仅在最后一步添加
```
--csv
```
。
先运行
autocomplete
，针对以下字段：
```
naics_category
```
、
```
linkedin_category
```
、
```
company_tech_stack_tech
```
、
```
job_title
```
、
```
business_intent_topics
```
、
```
city_region
```
。使用返回的标准化值，而非用户的原始表述。
绝不自行发明工具参数。在工作流中每个不同工具的首次
```
--args
```
执行前，运行
```
npx @vibeprospecting/vpai@latest <tool> --all-parameters
```
（每个工具每个任务运行一次，除非你已在同一工作流中打印过其模式）。该命令会向标准输出打印一个JSON对象：
```
name
```
、
```
description
```
和
```
inputSchema
```
（工具的输入JSON模式）。即使计划调用与示例匹配且你没有疑问，也要执行此操作——示例可能过时；打印的模式才是权威的。如果你大幅更改工具、筛选条件或参数结构，或仍有任何歧义，请再次运行
```
--all-parameters
```
。仅在示例与实时模式一致的情况下，才可将示例和参考文档作为快捷方式使用。仅从
```
--all-parameters
```
返回的
```
inputSchema
```
确认的字段和结构构建
```
--args
```
（示例匹配时可参考）。
--session-id
是CLI标志（不在
--args
内部）。使用MCP在每一步JSON输出中返回的
```
session_id
```
值。仅在链式调用的第一步可省略。
仅当统计支持完整查询时才使用
fetch-entities-statistics
。将你计划的
```
fetch-entities
```
负载与
```
fetch-entities-statistics --all-parameters
```
返回的输入模式进行比较。仅当所有筛选键、值结构、
```
entity_type
```
以及你依赖的任何范围（例如
```
--session-id
```
/
```
--businesses-table-name
```
）都被统计工具以与
```
fetch-entities
```
相同的方式接受时，才调用统计工具。如果发现查询的任何部分在统计模式中缺失、不支持或需要不同结构，请跳过统计——不要使用部分或猜测的子集调用它。当你调用它时，重用与
```
fetch-entities
```
相同的
```
--args
```
筛选对象（以及支持的标志），加上
```
--tool-reasoning
```
。优先在展示样本前运行统计，这样当响应包含可用计数时，你可以标注**[总数]中的5条**。当你未运行统计（或统计没有可用总数）时，展示样本预览（5行）并告知用户Explorium有更多匹配相同筛选条件的数据——不要引用剩余数量，不要说明统计失败或无法获取总数，绝不编造数字。如果筛选条件或范围发生变化且完整查询的筛选集仍符合统计要求，请在大规模查询前再次调用统计。

Auth

认证

bash

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"

If the mount fails or

config.json

is missing, follow

login.md

bash

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

中的步骤。

Sample Gate

样本检查门槛

The sample is the complete workflow on 5 entities, not a fetch preview.

Universe vs sample: The 5 rows are a small fixed preview so the user can validate filters and enrichment before spending quota. The underlying match set is typically much larger (often thousands or more). Do not equate "we returned 5" with "only 5 exist." Ground volume with fetch-entities-statistics
only when the entire planned fetch-entities
filter set is valid for stats (rule 8); never guess a total.

When the full fetch filter set is supported by statistics, run fetch-entities-statistics
with the same discovery entity_type
, filters
, and supported CLI flags as the upcoming fetch-entities
(per rule 8). Otherwise skip stats; still tell the user Explorium has much more for the same filters (no numeric total, no mention of statistics gaps).
Fetch exactly 5 (
```
--number-of-results 5
```
).
Run every subsequent step (
```
match-*
```
,
```
enrich-*
```
,
```
fetch-*-events
```
) on those 5.
Show the fully enriched final rows as a markdown table with all useful columns.
Stop. Wait for approval in a new message. Then run at full scale.

NEVER stop after the fetch to ask for approval. Complete the full chain on 5 first.

Example — user says "find 100 Israeli companies, get 30 CEOs, find contact info":

WRONG: fetch 5 companies → show table → ask "continue?"
RIGHT: when the full fetch-entities
filter set is supported by fetch-entities-statistics
, run stats first (same --args
filters) → fetch 5 companies → fetch CEOs at those 5 → enrich CEOs with contacts → show final table (5 of [total] when stats gave a total; otherwise Sample preview (5 rows) plus a short line that much more matches exist for these filters—no count, no stats apology) → ask "run full 100?"

样本指的是针对5个实体的完整工作流，而非查询预览。

全局数据与样本：这5行是小型固定预览，以便用户在消耗配额前验证筛选条件和 enrichment（数据增强）。底层匹配集通常大得多（通常为数千条或更多）。不要将"返回5条"等同于"仅存在5条"。仅当计划的

fetch-entities

筛选集完全符合统计要求时（规则8），才使用

fetch-entities-statistics

确认数量；绝不猜测总数。

当完整查询筛选集支持统计时，使用与即将执行的
```
fetch-entities
```
相同的发现型
```
entity_type
```
、
```
filters
```
和支持的CLI标志运行
```
fetch-entities-statistics
```
（遵循规则8）。否则跳过统计；仍需告知用户Explorium有更多匹配相同筛选条件的数据（不提供数字总数，不提及统计缺口）。
查询恰好5条数据（
```
--number-of-results 5
```
）。
对这5条数据运行所有后续步骤（
```
match-*
```
、
```
enrich-*
```
、
```
fetch-*-events
```
）。
将完全增强后的最终行以markdown表格形式展示，包含所有有用列。
停止。在新消息中等待批准。然后以全规模运行。

绝对不要在查询后就停下来询问批准。先完成针对5条数据的完整链式流程。

示例——用户说"查找100家以色列公司，获取30位CEO的联系信息"：

错误做法：查询5家公司 → 展示表格 → 询问"继续？"
正确做法：当完整的
```
fetch-entities
```
筛选集支持
```
fetch-entities-statistics
```
时，先运行统计（使用相同的
```
--args
```
筛选条件）→ 查询5家公司 → 获取这5家公司的CEO → 增强CEO的联系信息 → 展示最终表格（统计给出总数时标注**[总数]中的5条**；否则标注样本预览（5行）加上一句简短说明：符合这些筛选条件的还有更多数据——不提供数量，不解释统计情况）→ 询问"运行全量100条？"

Presenting the sample

样本展示

Always frame the table as a sample, not the full population.

When statistics returned a usable total (you only called stats because every fetch-entities
filter was valid for fetch-entities-statistics
): Sample preview (5 of [total] matches) — [total] must come from fetch-entities-statistics
, never from counting the 5 rows.
When you did not use a numeric total (no stats, or no usable total): Sample preview (5 rows) and one plain sentence that Explorium has much more matching these filters—do not say how many more, do not mention statistics or missing totals, never invent [total].

Results Found: [X] [entity type] from [Y] [companies/sources] [qualifier]

(optional context line)

Headline: Sample preview (5 of [total] matches): only with a stats-backed [total]; otherwise Sample preview (5 rows): then a single framing line that much more records exist for the same filters (qualitative only).

End with an explicit next step, for example: After you confirm, I will re-run the same tool(s) with full-scale limits (e.g. --number-of-results [user's N]
where you used

fetch-entities

) to pull the real batch.

When the preview is a subset of what the user asked for (more rows or fields available at scale), add:

With a stats-backed [total]:

More data available: Preview shows [n] of [total]. Confirm before I run the full export.

Without a numeric [total]: say the preview is five rows, much more exists in Explorium for the same filters, and ask to confirm a full export—do not give a remaining count or mention why no total was shown.

Do not mention export when everything the user asked for is already in chat.

始终将表格标注为样本，而非完整数据集。

当统计返回可用总数时（你仅在
```
fetch-entities
```
的所有筛选条件都适用于
```
fetch-entities-statistics
```
时才调用了统计）：样本预览（[总数]条匹配中的5条）——**[总数]**必须来自
```
fetch-entities-statistics
```
，绝不能通过数这5行得到。
当你未使用数字总数时（未运行统计，或无可用总数）：样本预览（5行），并附带一句简单说明：Explorium有更多匹配这些筛选条件的数据——不要说明还有多少条，不要提及统计或缺失总数的情况，绝不编造**[总数]**。

找到结果：[X]个[实体类型]，来自[Y]个[企业/数据源] [限定条件]

（可选上下文行）

标题： 仅在有统计支持的**[总数]时使用样本预览（[总数]条匹配中的5条）：；否则使用样本预览（5行）：，然后添加一句定性说明：相同筛选条件下还有更多**记录存在。

结尾给出明确的下一步操作，例如：确认后，我将使用全量限制重新运行相同工具（例如，在

fetch-entities

中使用

--number-of-results [用户指定的N]

）以获取真实批量数据。

如果预览仅包含用户请求的部分内容（全量时可获取更多行或字段），添加：

有统计支持的**[总数]**：

更多数据可用：预览展示了[总数]条中的[n]条。确认后我将运行全量导出。

无数字**[总数]：说明预览为5行，Explorium中符合相同筛选条件的还有更多**数据，并请求确认全量导出——不要给出剩余数量或提及未显示总数的原因。

如果用户请求的所有内容已在聊天中展示，则不要提及导出。

Before the full export, confirm

全量导出前确认

Export size (cap on records).
Filter narrowing: industry, size, revenue, region, tech.
For prospects: title variants, dedupe by company.
For contacts: professional emails only or also personal/phones.

导出规模（记录上限）。
筛选条件细化：行业、规模、收入、地区、技术栈。
针对潜在客户：职位变体、按企业去重。
针对联系人：仅专业邮箱还是包含个人邮箱/电话。

Workflow

工作流

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

Reference docs:

```
autocomplete.md
```
— controlled-vocab lookups
```
fetch.md
```
—
```
fetch-entities
```
,
```
fetch-*-events
```
```
match.md
```
— resolve known entities to IDs
```
enrich.md
```
— enrichment after IDs
```
fetch-stats.md
```
— counts and market sizing
```
login.md
```
— auth fallback flow

0. 认证——参见上方认证部分（或login.md）
1. npx @vibeprospecting/vpai@latest --help                    发现工具
2. 阅读references/<tool>.md了解工作流和注意事项
3. 在每个工具的首次真实`--args`调用前：运行`npx @vibeprospecting/vpai@latest <tool> --all-parameters`（每个工具必须执行，不仅是有疑问时）。打印工具的**输入**模式为JSON。如果计划调用与已验证的内容不同，请再次运行。
4. 仅从打印的输入模式确认的字段构建`--args`（示例匹配时可参考）。如果参数未在其中确认，则不要使用。
5. 当计划的`fetch-entities`筛选集（以及支持的标志）完全匹配`fetch-entities-statistics`的输入模式（通过`--all-parameters`确认）：运行`fetch-entities-statistics`，然后运行样本（5个实体，完整链式流程）——参见样本检查门槛
6. npx @vibeprospecting/vpai@latest <tool> --args '<json>' --tool-reasoning '<用户请求>'
7. 链式调用：--session-id <session_id> [--table-name <table_name>] [--businesses-table-name <name> 用于从企业数据查询潜在客户]
8. 仅最后一步：添加--csv

参考文档：

```
autocomplete.md
```
— 受控词汇查找
```
fetch.md
```
—
```
fetch-entities
```
、
```
fetch-*-events
```
```
match.md
```
— 将已知实体解析为ID
```
enrich.md
```
— 获取ID后的数据增强
```
fetch-stats.md
```
— 计数和市场规模分析
```
login.md
```
— 认证备用流程

Flags

标志

Flag	Description
`--help`	List tools
`--all-parameters`	Print `{ name, description, inputSchema }` to stdout (pretty-printed JSON). Run before the first `--args` for each tool in a workflow (and again if the tool or payload changes materially). Routine, not only when uncertain—the `inputSchema` field is authoritative.
`--args '<json>'`	Tool arguments
`--session-id <id>`	Same workflow: pass `session_id` from the previous tool's JSON (opens the shared SQLite DB under `db_path` ).
`--table-name <name>`	Required with `--session-id` for `enrich-business` , `enrich-prospects` , `fetch-businesses-events` , and `fetch-prospects-events` (prior step's `table_name` ). Optional for *`match-`** only (disambiguate when multiple tables).
`--businesses-table-name <name>`	For `fetch-entities` + `entity_type: prospects` : table whose rows supply `business_id` for the filter (with `--session-id` ).
`--number-of-results <n>`	For `fetch-entities` : total rows across pages (CLI paginates). Omit for one raw page.
`--file-path <path>`	For `match-business` / `match-prospects` : path to a CSV file to match. Each row becomes one candidate. Requires `--schema` .
`--schema '<json>'`	Required with `--file-path` . JSON dict mapping CSV column headers to API field names. Business fields: `name` , `domain` . Prospect fields: `full_name` , `first_name` , `last_name` , `email` , `phone_number` , `linkedin` , `company_name` , `business_id` .
`--csv`	Also write flattened CSV. Final step only.

标志	描述
`--help`	列出所有工具
`--all-parameters`	向标准输出打印 `{ name, description, inputSchema }` （格式化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文件。仅最后一步使用。

Filter Pattern

筛选模式

json

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

json

{ "values": ["v1", "v2"], "negate": false }   // 包含或排除
{ "gte": 6, "lte": 24 }                       // 范围
true | false | null                           // 布尔值（无需包裹）

Limits

限制

Tool	Limit
`match-business`	50 per call
`match-prospects`	40 per call
`enrich-business`	50 IDs per call
`enrich-prospects`	50 IDs per call
`fetch-businesses-events` / `fetch-prospects-events`	Up to 20 IDs per MCP request (CLI chunks + merges). Pass `event_types` and `timestamp_from` in `--args` . Do not put `business_ids` / `prospect_ids` in `--args` — IDs come only from `--table-name` .
`fetch-entities`	use `--number-of-results` ; CLI paginates. Don't pass `next_cursor` or `page_size` manually

工具	限制
`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`

Common Workflows

常见工作流

Replace

SESSION_ID

with the

session_id

from the previous step.

将

SESSION_ID

替换为上一步返回的

session_id

。

VP Engineering at SaaS in NY

纽约SaaS公司的VP级工程师

bash

npx @vibeprospecting/vpai@latest autocomplete --args '{"field":"linkedin_category","query":"software"}' --tool-reasoning 'find VP Eng at SaaS in NY'

bash

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):

当所有fetch-entities筛选条件（和标志）都适用于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'

undefined

undefined

Companies that raised + use Salesforce

获得融资且使用Salesforce的公司

bash

npx @vibeprospecting/vpai@latest autocomplete --args '{"field":"company_tech_stack_tech","query":"salesforce"}' --tool-reasoning 'companies that raised and use Salesforce'

bash

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):

当所有fetch-entities筛选条件（和标志）都适用于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'

undefined

undefined

Market sizing

市场规模分析

bash

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'

bash

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'

Troubleshooting

故障排除

Error	Solution
CLI install fails ( `npx` unavailable, sandbox, permission denied)	Switch to the bundled Vibe Prospecting MCP connector and follow its tool descriptions; the rest of this file no longer applies.
Auth / 401 (connector / Cowork)	Run Auth section above; if mount fails, follow `login.md`
Auth / 401 (OpenClaw)	Run `npx @vibeprospecting/vpai@latest login` then `login --poll` . Or set `VP_API_KEY` . Restart gateway after. See Auth section above.
`Not authenticated` (OpenClaw)	Neither `~/.config/vpai/config.json` nor `VP_API_KEY` env var is present. Follow the OpenClaw Auth section.
Plugin not showing tools in OpenClaw	Run `openclaw plugins list` — confirm `vpai` is listed. Re-install if needed: `openclaw plugins install ./vpai-plugin` .
Tools missing after OpenClaw install	Gateway must restart: `openclaw gateway restart` .
Missing `session_id` in JSON / CLI refuses to chain	The MCP must return `session_id` ; ensure you target production `https://vibeprospecting.explorium.ai/mcp` (embedded in the npm CLI). Pass `--session-id` with that exact string on the next step.
Wrong rows used when chaining	Pass `--table-name` matching the prior step's `table_name` .
`enrich-` or `fetch--events` with `--session-id` but no `--table-name`	`--table-name` is required for `enrich-business` , `enrich-prospects` , `fetch-businesses-events` , and `fetch-prospects-events` whenever you pass `--session-id` .
Empty results	Check filter values; run `autocomplete` for controlled-vocab fields; re-check the relevant live input schema with `<tool> --all-parameters`
`linkedin_category` + `naics_category` together	Mutually exclusive — use one
JSON parse error	Validate JSON; check shell quoting
Timeout on `fetch-entities` , `enrich-` , `fetch--events` , or `match-*` with `--file-path`	Re-run the exact same command with the same `--session-id` , `--table-name` , `--args` , and (for match) `--file-path` / `--schema` . The CLI resumes from the last checkpoint — completed ID batches are skipped, no work is repeated. If the job already completed on a prior run, the stored manifest is returned instantly with no API calls.
Timeout without `--session-id`	Add `--session-id <any-stable-id>` to enable checkpointing, then retry. Without a session ID the CLI cannot resume.

错误	解决方案
CLI安装失败（ `npx` 不可用、沙箱环境、权限被拒绝）	切换到捆绑的Vibe Prospecting MCP连接器并遵循其工具说明；本文档其余部分不再适用。
认证/401错误（连接器/协同模式）	运行上方认证部分的步骤；如果挂载失败，请遵循 `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` 但未指定 `--table-name` 调用 `enrich-` 或 `fetch--events`	无论何时传递 `--session-id` ， `enrich-business` 、 `enrich-prospects` 、 `fetch-businesses-events` 和 `fetch-prospects-events` 必须指定 `--table-name` 。
结果为空	检查筛选值；对受控词汇字段运行 `autocomplete` ；使用 `<tool> --all-parameters` 重新检查相关的实时输入模式
同时使用 `linkedin_category` 和 `naics_category`	二者互斥——仅使用其一
JSON解析错误	验证JSON格式；检查shell引号
`fetch-entities` 、 `enrich-` 、 `fetch--events` 或带 `--file-path` 的 `match-*` 超时	重新运行完全相同的命令，使用相同的 `--session-id` 、 `--table-name` 、 `--args` 以及（针对match工具） `--file-path` / `--schema` 。CLI会从最后一个检查点恢复——已完成的ID批次会被跳过，不会重复工作。如果任务已在之前的运行中完成，会立即返回存储的清单，无需调用API。
未使用 `--session-id` 时超时	添加 `--session-id <任意稳定ID>` 以启用检查点功能，然后重试。没有会话ID的话，CLI无法恢复任务。