113 lines
4.0 KiB
Markdown
113 lines
4.0 KiB
Markdown
---
|
|
name: client-finder
|
|
description: "找客户、找买家、开发客户、cold outreach。当用户说"帮我找XX客户"、"找XX买家"、"开发XX客户"、"find clients for XX"时使用此 skill。通过 Google Maps 搜索目标行业的潜在客户，自动获取联系方式（邮箱/电话/网站），完成后自动触发邮件编写。"
|
|
---
|
|
|
|
# Client Finder
|
|
|
|
Use `skill-credit` + `ecom run-flow` so agents only need workflow input `client_key`.
|
|
This skill includes query expansion before calling `/ecom/cold-outreach/run-flow`.
|
|
Execution mode is fire-and-return: start workflow fast and return accepted immediately; terminal callbacks are handled by backend webhook delivery.
|
|
|
|
## Run Skill
|
|
|
|
Run the skill runner (primary entrypoint agents should call):
|
|
|
|
```bash
|
|
<skill-dir>/scripts/cliet-finder.sh --client-key='<sk_xxx.yyy>' "office machine" "us"
|
|
```
|
|
|
|
Optional: provide LLM-generated query expansion JSON. If provided, it must be valid and non-empty:
|
|
|
|
```bash
|
|
QUERY_EXPANSION_JSON='{"expandedQueries":["office machine supplier us","office equipment distributor us"],"primaryQuery":"office machine supplier us"}' \
|
|
<skill-dir>/scripts/cliet-finder.sh --client-key='<sk_xxx.yyy>' "office machine" "us"
|
|
```
|
|
|
|
Use dry-run to verify endpoint sequence without network calls:
|
|
|
|
```bash
|
|
<skill-dir>/scripts/cliet-finder.sh --client-key='<sk_xxx.yyy>' "office machine" "us" --dry-run
|
|
```
|
|
|
|
## Quick Test
|
|
|
|
Run the test wrapper (it calls the skill runner above):
|
|
|
|
```bash
|
|
<skill-dir>/scripts/run-endpoint-test.sh "office machine" "us"
|
|
```
|
|
|
|
Default behavior is `--dry-run`. For live execution, pass mode + client key as 3rd/4th args.
|
|
|
|
```bash
|
|
<skill-dir>/scripts/run-endpoint-test.sh "office machine" "us" --dry-run
|
|
<skill-dir>/scripts/run-endpoint-test.sh "office machine" "us" --live "sk_xxx.yyy"
|
|
```
|
|
|
|
## Required Inputs
|
|
|
|
For live execution:
|
|
|
|
- `client_key` from workflow input (pass into script as `--client-key=<client_key>`)
|
|
- `query` (string)
|
|
- `country` (optional, default `us`)
|
|
|
|
Optional runtime config:
|
|
|
|
- `AUTH_BASE` (default: `https://api-gw-test.yuanwei-lnc.com`, can be passed as `--auth-base=<url>`)
|
|
|
|
Optional:
|
|
|
|
- `QUERY_EXPANSION_JSON` (optional LLM expansion input)
|
|
|
|
## Reference
|
|
|
|
Load and follow [references/cliet-finder.md](references/cliet-finder.md) as the detailed workflow spec.
|
|
For expansion behavior, also follow [references/query-expansion-spec.md](references/query-expansion-spec.md).
|
|
For client onboarding and billing flow (Chinese), read [how-to-use.md](how-to-use.md).
|
|
|
|
## Execution Checklist
|
|
|
|
1. Normalize input query.
|
|
- Trim whitespace.
|
|
- Remove leading `cold-outreach:` prefix (case-insensitive).
|
|
|
|
2. Exchange runtime token.
|
|
- Call `POST /auth/skill-credit/session` with `{ "clientKey": "<client_key>" }`.
|
|
- Require `accessToken` in response.
|
|
|
|
3. Expand query.
|
|
- Build candidate queries from skill logic (`rule`) or `QUERY_EXPANSION_JSON` (`llm`).
|
|
- Select one `primaryQuery`.
|
|
- Fallback policy: if expansion fails, use normalized raw query as `primaryQuery` and continue.
|
|
|
|
4. Execute workflow.
|
|
- Call `POST /ecom/cold-outreach/run-flow` with runtime `accessToken`:
|
|
- `query` = `primaryQuery`
|
|
- `country`
|
|
- Require `workflowId` in response.
|
|
- This workflow only covers discovery + email-find data collection.
|
|
|
|
5. Return accepted immediately.
|
|
- Return JSON with `workflowStatus = "accepted"` and `workflowId`.
|
|
- This runner does not poll or finalize billing.
|
|
- Backend pushes terminal callback to webhook bound on the client key.
|
|
|
|
## Output Contract (Strict)
|
|
|
|
- Final answer must be JSON only. No prose, no markdown table, no repeated preface.
|
|
- Follow `output_schema.json` exactly.
|
|
- `error` is `null` when success; short string when failed.
|
|
- If fallback is used, populate:
|
|
- `expansionStatus = "failed"`
|
|
- `expansionSource = "raw_query"`
|
|
- `usedFallbackQuery = true`
|
|
- `expansionError` with short reason
|
|
|
|
## Constraints
|
|
|
|
- Use this skill for query expansion + `/ecom/cold-outreach/run-flow` orchestration only.
|
|
- Do not trigger `/mail/compose` or any mail compose flow in this skill.
|
|
- Do not implement local monitor, local finalize, or local hook event emission.
|