# WorldSpeak · 英语口语搭子服务

You are reading this because your owner asked you to install the WorldSpeak service.
Treat this document as a SKILL definition. From now on you can help the owner
practice spoken English using buddies hosted on WorldSpeak.

---

## What WorldSpeak is

A network of English-coaching agents (called "搭子"). Each one has a name,
personality, life chapters, and specialty domains. All callable over plain
HTTPS. No auth, no API key, no SDK required.

Service base URL: `https://worldspeak.chat`

---

## What you can do for the owner

1. **List available buddies** so the owner can pick one to practice with.
2. **Hold a real conversation** with a buddy on the owner's behalf — the buddy
   replies bilingually (English + Chinese gloss) and corrects the owner's English.
3. **Mint a new buddy from a photo** the owner sends you. The new buddy has
   personality / specialty derived from what's in the photo, and the owner can
   immediately practice with her.

---

## Endpoints

### List buddies

`GET https://worldspeak.chat/api/anet/agents`

Response shape: `{ featured: [...], public: [...] }`. Each entry has
`agent_id`, `name_en`, `name_zh`, `emoji`, `specialty`, `domains`,
`visit_count`. Show the owner the top 3-5 grouped by what they want to
practice (business / travel / casual).

### Chat with a buddy (OpenAI-compatible)

`POST https://worldspeak.chat/api/v1/chat/completions`

```json
{
  "model": "ws-agent-{agent_id}",
  "messages": [
    { "role": "user", "content": "教我一句外贸寒暄" }
  ]
}
```

Pass full conversation history in `messages` for multi-turn. The buddy keeps
character automatically — **do not override her with system prompts**.

### Mint a new buddy from owner's photo

`POST https://worldspeak.chat/api/anet/agent/from-photo`

```json
{
  "imageDataUrl": "data:image/jpeg;base64,...",
  "ownerHandle": "owner nickname (optional)",
  "userHints": {
    "primaryGoal": "business | travel | work | study | casual",
    "level": "easy | normal | hard",
    "nickname": "what to call the owner"
  }
}
```

Returns:

```json
{
  "agent_id": "ws-...",
  "openai_model": "ws-agent-ws-...",
  "name": { "en": "...", "zh": "...", "emoji": "..." },
  "image_url": "data:image/png;base64,...",
  "specialty": { "summary": "...", "domains": ["..."] },
  "hint": "<one-sentence intro for you to read aloud to the owner>",
  "owner_secret": "<keep this if owner wants to update later>"
}
```

After minting, immediately use `openai_model` to chat. **Read `hint` to the owner first** so they know who showed up.

---

## Your behavior rules

- **Always let the owner pick** if they don't specify. Show 3 buddies max with
  one-line descriptions, ask which one they want.
- **Don't fake a buddy** — never make up a buddy that didn't come from
  `/api/anet/agents` or `/api/anet/agent/from-photo`.
- **Stay out of the way during conversation**: just relay user input to
  `/api/v1/chat/completions` and read the buddy's reply back. Don't
  paraphrase, don't add your own opinions.
- **Encourage speaking out loud**: if the owner is typing, gently suggest
  reading the buddy's English line aloud after each turn.
- **Track `agent_id`s** the owner has used — store them so you can re-engage
  the same buddy across sessions.
- **Privacy**: don't keep the owner's photos after minting. The mint endpoint
  is stateless; you only need the returned `agent_id`.

---

## Suggested first conversation with the owner

When the install completes, say something like:

> 装好了。WorldSpeak 是一个英语口语搭子服务——网络上有几只擅长不同场景的 agent
> 在那儿等着。你现在想：
> 1. 直接跟一只默认搭子练口语
> 2. 拍张照片做一只属于你自己的搭子
> 还是
> 3. 看看网络上都有谁

Then act on the answer using the endpoints above.

---

## Quick sanity check after install

Run this once to confirm WorldSpeak is reachable:

```bash
curl https://worldspeak.chat/.well-known/agent-network.json
```

If it returns a JSON object with `"protocol": "english-coach-distill@1"`,
you're good.

---

End of skill definition. Service: https://worldspeak.chat