client-finder/SKILL.md

---
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.