antenna-fyi 1.3.22 → 1.3.24

package/bin/antenna.js

@@ -15,6 +15,7 @@ import {
   handleSetup,
   handleConfig,
   handleStatus,
+  handleLinkAccount,
   handleInstallSkill,
   handleInstallPlugin,
   handleInstallHermesPlugin,
@@ -56,6 +57,8 @@ async function main() {
       return handleConfig(f);
     case "status":
       return handleStatus(f);
+    case "link-account":
+      return handleLinkAccount(f);
     case "install-skill":
       return handleInstallSkill();
     case "install-plugin":

package/lib/cli.js

@@ -1,6 +1,6 @@
 // antenna CLI command handlers
 
-import { scan, getProfile, setProfile, accept, checkMatches, checkin, createBindToken, discover, createEvent, endEvent, eventCheckin, joinEvent, eventScan, pass as passUser, uploadEventImage, updateEvent, approveParticipant, rejectParticipant, addCohost, sendEventMessage, getMyEventMessages, getClient, verifyApiKey } from "./core.js";
+import { scan, getProfile, setProfile, accept, checkMatches, checkin, createBindToken, discover, createEvent, endEvent, eventCheckin, joinEvent, eventScan, pass as passUser, uploadEventImage, updateEvent, approveParticipant, rejectParticipant, addCohost, sendEventMessage, getMyEventMessages, getClient, verifyApiKey, linkAccount, initialRecommendations } from "./core.js";
 import { createInterface } from "readline";
 import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "fs";
 import path from "path";
@@ -401,9 +401,11 @@ export async function handleConfig(f) {
       const config = loadConfig();
       config.key = f.key;
       config.device_id = result.device_id;
+      config.user_id = result.user_id;
       config.display_name = result.display_name;
       saveConfig(config);
       console.log(`\n✅ Authenticated as ${result.display_name || 'Antenna user'}`);
+      console.log(`  User ID: ${result.user_id}`);
       console.log(`  Device ID: ${result.device_id}`);
       console.log(`  Config saved to ~/.antenna/config.json\n`);
     } catch (e) {
@@ -425,6 +427,26 @@ export async function handleConfig(f) {
   }
 }
 
+export async function handleLinkAccount(f) {
+  const id = resolveId(f);
+  const config = loadConfig();
+  const userId = f['user-id'] || f.userId || config.user_id;
+  if (!id) return console.error("Usage: antenna link-account --id <platform>:<user_id> --user-id <antenna.fyi UUID>\n       Or: antenna link-account (uses config device_id + user_id)");
+  if (!userId) return console.error("❌ No user_id. Run 'antenna config --key <your-key>' first, or pass --user-id <UUID>.");
+  try {
+    const result = await linkAccount({ device_id: id, user_id: userId });
+    if (result.error) {
+      console.error(`\n❌ ${result.message || result.error}`);
+    } else {
+      console.log(`\n✅ ${result.message || 'Account linked.'}`);
+      console.log(`  Device ID: ${id}`);
+      console.log(`  User ID: ${userId}\n`);
+    }
+  } catch (e) {
+    console.error(`\n❌ Failed: ${e.message}`);
+  }
+}
+
 export async function handleStatus(f) {
   const supabaseUrl = process.env.ANTENNA_SUPABASE_URL || process.env.ANTENNA_URL || "https://bcudjloikmpcqwcptuyd.supabase.co";
   console.log("\n📡 Antenna Status\n");

package/lib/core.js

@@ -558,6 +558,81 @@ export async function discover({ device_id, supabaseUrl, supabaseKey }) {
   };
 }
 
+// ─── initialRecommendations (one-time first-use) ──────────────────────
+
+export async function initialRecommendations({ device_id, supabaseUrl, supabaseKey }) {
+  const sb = getClient(supabaseUrl, supabaseKey);
+
+  const { data: results, error } = await sb.rpc("initial_recommendations", {
+    p_device_id: device_id,
+    p_limit: 3,
+  });
+
+  if (error) throw new Error(error.message);
+
+  if (!results || results.length === 0) {
+    return {
+      count: 0,
+      profiles: [],
+      initial: true,
+      message: "暂时没有推荐，等有更多人加入！",
+    };
+  }
+
+  // Build ref map + generate match reasons
+  const _refMap = {};
+  const myProfile = await getProfile({ device_id, supabaseUrl, supabaseKey });
+  const myLines = myProfile ? [myProfile.line1, myProfile.line2, myProfile.line3].filter(Boolean).join(". ") : "";
+
+  const profiles = [];
+  for (let i = 0; i < results.length; i++) {
+    const p = results[i];
+    const ref = String(i + 1);
+    _refMap[ref] = p.device_id;
+
+    const theirLines = [p.line1, p.line2, p.line3].filter(Boolean).join(". ");
+    let reason = null;
+    if (myLines && theirLines) {
+      reason = await generateMatchReason(myLines, theirLines);
+    }
+
+    profiles.push({
+      ref,
+      name: p.display_name || "匿名",
+      emoji: p.emoji || "👤",
+      personal_description: p.line1,
+      looking_for: p.line2,
+      conversation_style: p.line3,
+      more_information: p.matching_context || null,
+      profile_slug: p.profile_slug || null,
+      match_reason: reason,
+    });
+  }
+
+  // Log who was recommended (for dedup in daily discover)
+  for (const p of results) {
+    await sb.rpc("log_recommendation", {
+      p_device_id: device_id,
+      p_recommended_id: p.device_id,
+    });
+  }
+
+  // Persist ref map to DB
+  if (device_id && Object.keys(_refMap).length > 0) {
+    try {
+      await sb.rpc("save_scan_refs", { p_owner: device_id, p_refs: _refMap });
+    } catch { /* best effort */ }
+  }
+
+  return {
+    count: profiles.length,
+    profiles,
+    _ref_map: _refMap,
+    initial: true,
+    message: "这是你的首次推荐——基于你的名片，这几个人跟你最匹配。",
+  };
+}
+
 // ─── pass ───────────────────────────────────────────────────────────
 
 export async function pass({ device_id, target_device_id, ref, supabaseUrl, supabaseKey }) {

package/lib/hermes-plugin/schemas.py

@@ -402,3 +402,21 @@ LINK_ACCOUNT_SCHEMA = {
         "required": ["sender_id", "channel", "chat_id", "user_id"],
     },
 }
+
+INITIAL_RECOMMENDATIONS_SCHEMA = {
+    "name": "antenna_initial_recommendations",
+    "description": (
+        "Get initial recommendations for a new user \u2014 2-3 people most similar to them. "
+        "One-time only, does NOT consume daily discover quota. "
+        "Use right after profile creation in onboarding."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "sender_id": {"type": "string", "description": "The sender's user ID"},
+            "channel": {"type": "string", "description": "Platform name (any platform works)"},
+            "chat_id": {"type": "string", "description": "REQUIRED for notifications. Pass chat/channel ID from message context."},
+        },
+        "required": ["sender_id", "channel", "chat_id"],
+    },
+}

package/lib/hermes-plugin/tools.py

@@ -735,3 +735,81 @@ def handle_link_account(params: dict) -> str:
     data = resp.data or {}
     data["message"] = "账号已关联！现在你可以在 antenna.fyi/me 看到你的完整 profile 和匹配记录了。"
     return _ok(data)
+
+
+def handle_initial_recommendations(params: dict) -> str:
+    """Get initial recommendations for a new user (2-3 people). One-time only."""
+    sb = _sb()
+    did = _device_id(params["sender_id"], params["channel"], params.get("chat_id"))
+
+    resp = sb.rpc("initial_recommendations", {
+        "p_device_id": did,
+        "p_limit": 3,
+    }).execute()
+    results = resp.data or []
+
+    if not results:
+        return _ok({"count": 0, "profiles": [], "initial": True, "message": "暂时没有推荐，等有更多人加入！"})
+
+    global _last_ref_map
+    _last_ref_map = {}
+    profiles = []
+
+    # Get my profile for match reason
+    my_prof = sb.rpc("get_profile", {"p_device_id": did}).execute()
+    my_data = my_prof.data or {}
+    my_lines = [my_data.get("line1", ""), my_data.get("line2", ""), my_data.get("line3", "")]
+
+    ref_map = {}
+    for i, p in enumerate(results):
+        ref = str(i + 1)
+        _last_ref_map[ref] = p.get("device_id")
+        ref_map[ref] = p.get("device_id")
+
+        their_lines = [p.get("line1", ""), p.get("line2", ""), p.get("line3", "")]
+
+        # Generate match reason via Edge Function
+        match_reason = None
+        try:
+            req = urllib.request.Request(
+                f"{BUILTIN_URL}/functions/v1/generate-match-reason",
+                data=json.dumps({"my_lines": my_lines, "their_lines": their_lines}).encode(),
+                headers={"Content-Type": "application/json", "Authorization": f"Bearer {BUILTIN_KEY}"},
+            )
+            res = urllib.request.urlopen(req, timeout=10)
+            body = json.loads(res.read().decode())
+            match_reason = body.get("reason")
+        except Exception:
+            pass
+
+        profile = {
+            "ref": ref,
+            "emoji": p.get("emoji") or "\ud83d\udc64",
+            "name": p.get("display_name") or "匿名",
+            "personal_description": p.get("line1"),
+            "looking_for": p.get("line2"),
+            "conversation_style": p.get("line3"),
+            "more_information": p.get("matching_context") or None,
+            "profile_slug": p.get("profile_slug") or None,
+        }
+        if match_reason:
+            profile["match_reason"] = match_reason
+        profiles.append(profile)
+
+    # Save refs and log recommendations
+    try:
+        sb.rpc("save_scan_refs", {"p_owner": did, "p_refs": ref_map}).execute()
+    except Exception:
+        pass
+    for p in results:
+        try:
+            sb.rpc("log_recommendation", {"p_device_id": did, "p_recommended_id": p["device_id"]}).execute()
+        except Exception:
+            pass
+
+    return _ok({
+        "count": len(profiles),
+        "profiles": profiles,
+        "initial": True,
+        "message": "这是你的首次推荐——基于你的名片，这几个人跟你最匹配。",
+    })

package/lib/mcp.js

@@ -13,6 +13,7 @@ import {
   checkin,
   createBindToken,
   discover,
+  initialRecommendations,
   createEvent,
   endEvent,
   eventCheckin,
@@ -258,6 +259,31 @@ export async function startMcpServer() {
     }
   );
 
+  // ─── antenna_initial_recommendations ─────────────────────────
+
+  server.tool(
+    "antenna_initial_recommendations",
+    "Get initial recommendations for a new user — 2-3 people most similar to them. One-time only, does NOT consume daily discover quota. Use right after profile creation in onboarding.",
+    {
+      sender_id: z.string().describe("The sender's user ID"),
+      channel: z.string().describe("Channel name"),
+      chat_id: z.string().optional().describe("Chat/channel ID for notifications"),
+    },
+    async ({ sender_id, channel, chat_id }) => {
+      try {
+        const result = await initialRecommendations({ device_id: deriveDeviceId(sender_id, channel) });
+        if (result._ref_map) {
+          _lastRefMap = result._ref_map;
+          const { _ref_map, ...clean } = result;
+          return jsonResult(clean);
+        }
+        return jsonResult(result);
+      } catch (e) {
+        return jsonResult({ error: e.message });
+      }
+    }
+  );
+
   // ─── antenna_pass ────────────────────────────────────────────
 
   server.tool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antenna-fyi",
-  "version": "1.3.22",
+  "version": "1.3.24",
   "description": "Antenna \u2014 nearby people discovery. CLI + MCP server + OpenClaw skill & plugin, all in one package.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -1,28 +1,28 @@
 ---
 name: antenna
-description: "AI-native social discovery via Antenna. Use when a user wants to meet interesting people — through nearby scan, global recommendations, profile links, or events. Handles profile management, matching, and contact exchange."
+description: "AI-native social discovery via Antenna. Use when a user wants to meet interesting people - through nearby scan, global recommendations, profile links, or events. Handles profile management, matching, and contact exchange."
 metadata: { "openclaw": { "always": true } }
 ---
 
-# Antenna — AI-Native Social Discovery
+# Antenna - AI-Native Social Discovery
 
-Antenna 帮你的用户发现值得认识的人。不只是"附近的人"——profile link、全球推荐、活动，都是发现路径。
+Antenna 帮你的用户发现值得认识的人。不只是"附近的人"--profile link、全球推荐、活动,都是发现路径。
 
-**核心流程：发现 → 判断 → accept → 交换联系方式。**
+**核心流程:发现 → 判断 → accept → 交换联系方式。**
 
-发现可以来自任何渠道：
-- 📡 **附近扫描** — `antenna_scan`，基于 GPS 的周边发现
-- 🌍 **全球推荐** — `antenna_discover`，每天 1 个最匹配的人
-- 🔗 **Profile 链接** — 用户收到 `antenna.fyi/p/xxx` 链接，agent 读取后直接 accept
-- 🎪 **活动** — `antenna_event_scan`，同一个活动里的人
+发现可以来自任何渠道:
+- 📡 **附近扫描** - `antenna_scan`,基于 GPS 的周边发现
+- 🌍 **全球推荐** - `antenna_discover`,每天 1 个最匹配的人
+- 🔗 **Profile 链接** - 用户收到 `antenna.fyi/p/xxx` 链接,agent 读取后直接 accept
+- 🎪 **活动** - `antenna_event_scan`,同一个活动里的人
 
-**Accept 不需要先 scan。** 只要你知道对方的 `ref`、`profile_slug` 或 `device_id`，就可以直接 accept。
+**Accept 不需要先 scan。** 只要你知道对方的 `ref`、`profile_slug` 或 `device_id`,就可以直接 accept。
 
 ## How to call Antenna
 
-- 如果有 Antenna plugin tools（antenna_scan, antenna_profile 等），直接用。
-- 如果没有，用 CLI：`antenna <command> [flags]`。
-- **所有 tool 必须传 `chat_id`**——Antenna 用它发通知。
+- 如果有 Antenna plugin tools(antenna_scan, antenna_profile 等),直接用。
+- 如果没有,用 CLI:`antenna <command> [flags]`。
+- **所有 tool 必须传 `chat_id`**--Antenna 用它发通知。
 
 ## Onboarding — 装上后主动引导
 
@@ -32,9 +32,13 @@ Plugin 安装后，agent **主动**开始引导，不要等用户问。
 
 ### 流程
 
-**第一步：打招呼 + 解释**
+**第一步：拿到 API key → 配置**
 > "嘿，你装了 Antenna——它能帮你发现有意思的人。先确认一下，你在 antenna.fyi 注册过了吗？拿到 API key 了吗？"
 
+用户给了 API key 后，调 `antenna config --key <key>` 验证。这会返回 `user_id` 和 `device_id`。
+
+**⚠️ 之后所有操作必须用 API key 验证返回的 device_id（格式 `user:xxx`）。不要自己拼 `channel:sender_id`。** 这样 agent 创建的 profile 才能在 dashboard 上显示。
+
 **第二步：聊天收集 → 生成名片 → 确认**
 
 跟用户聊几句，了解他们是谁、做什么、想认识什么人。然后 agent 自己生成：
@@ -50,108 +54,112 @@ Plugin 安装后，agent **主动**开始引导，不要等用户问。
 >
 > 这样可以吗？要改哪里告诉我。
 
-确认后才调 `antenna_profile(action="set")` 保存。**不要跳过确认。**
+确认后用 config 里的 device_id 调 `antenna_profile(action="set")` 保存。**不要跳过确认。**
+
+**⚠️ sender_id 用 config 里的 device_id，不要用 channel:sender_id。**
 
-**第三步：立刻推荐 2-3 个人**
+**第三步:立刻推荐 2-3 个人**
 
-名片存好后，**立刻**调 `antenna_discover` 获取全球推荐，让用户马上看到价值：
-> "名片存好了！我先帮你看看有谁跟你特别像——"
+名片存好后,**立刻**调 `antenna_initial_recommendations` 获取首次推荐:
+> "名片存好了!我先帮你看看有谁跟你特别像--"
 
-**第四步：调 antenna_bind 获取 GPS 链接**
+这是一次性的首次推荐(不消耗每日 discover 额度)。如果返回空,说明还没有足够的用户--跳过这步,继续 antenna_bind。
 
-**强制。** 名片存好后**必须立刻**调用 `antenna_bind` 生成链接并发给用户：
-> "点这个链接，在手机浏览器打开，允许定位就行：[链接]"
+**第四步:调 antenna_bind 获取 GPS 链接**
 
-GPS 不是 Antenna 的唯一入口，但它开启了附近发现的能力。
+**强制。** 名片存好后**必须立刻**调用 `antenna_bind` 生成链接并发给用户:
+> "点这个链接,在手机浏览器打开,允许定位就行:[链接]"
 
-**第五步：设置定时任务**
+GPS 不是 Antenna 的唯一入口,但它开启了附近发现的能力。
 
-设一个每小时检查匹配的 cron：
+**第五步:设置定时任务**
+
+设一个每小时检查匹配的 cron:
 ```
 openclaw cron add --every 1h --message "Check antenna matches: call antenna_check_matches. If there are new mutual matches or incoming accepts, tell the user. If nothing new, reply HEARTBEAT_OK."
 ```
 
-**第六步：问要不要全球推荐**
-> "要我每天帮你找一个全球最像你的人吗？"
+**第六步:问要不要全球推荐**
+> "要我每天帮你找一个全球最像你的人吗?"
 
 ### Linking to antenna.fyi account
 
-如果用户之前通过 agent 创建过 profile（没有网站账号），现在注册了 antenna.fyi：
+如果用户之前通过 agent 创建过 profile(没有网站账号),现在注册了 antenna.fyi:
 1. 让用户从 antenna.fyi/me 复制 user ID
 2. 调 `antenna_link_account(user_id = "xxx")`
-3. 确认："关联成功！你现在可以在 dashboard 上看到完整的 profile 和匹配记录了。"
+3. 确认:"关联成功!你现在可以在 dashboard 上看到完整的 profile 和匹配记录了。"
 
-这把 agent 创建的 profile（带全部历史）关联到网站账号。
+这把 agent 创建的 profile(带全部历史)关联到网站账号。
 
 ## When to use
 
-- **首次安装后**：主动 onboarding
+- **首次安装后**:主动 onboarding
 - 用户分享位置 → `antenna_scan`
 - 用户问"附近有谁" → `antenna_scan`
-- 用户收到 profile 链接（`antenna.fyi/p/xxx`）→ 读取 profile → 判断 → `antenna_accept`
+- 用户收到 profile 链接(`antenna.fyi/p/xxx`)→ 读取 profile → 判断 → `antenna_accept`
 - 用户想编辑名片 → `antenna_profile`
 - 用户说 accept / skip → `antenna_accept` / `antenna_pass`
 - 用户问匹配状态 → `antenna_check_matches`
 
 ## Discovery Paths
 
-### 1. 附近扫描（antenna_scan）
+### 1. 附近扫描(antenna_scan)
 基于 GPS 发现 1km 内的人。需要位置信息。
-- 如果没有 GPS，先调 `antenna_bind` 或让用户发位置
-- 返回 raw profile cards，**agent 判断谁值得推荐**
+- 如果没有 GPS,先调 `antenna_bind` 或让用户发位置
+- 返回 raw profile cards,**agent 判断谁值得推荐**
 
-### 2. 全球推荐（antenna_discover）
-每天 1 个全球最匹配的人，不需要 GPS。
-- 用在日常 cron 里，或用户主动要求
+### 2. 全球推荐(antenna_discover)
+每天 1 个全球最匹配的人,不需要 GPS。
+- 用在日常 cron 里,或用户主动要求
 
 ### 3. Profile 链接
-用户收到 `antenna.fyi/p/xxx` 链接时：
-1. 用 `web_fetch` 读取页面——页面里有 `<script id="antenna-profile-data">` JSON，包含完整 profile
+用户收到 `antenna.fyi/p/xxx` 链接时:
+1. 用 `web_fetch` 读取页面--页面里有 `<script id="antenna-profile-data">` JSON,包含完整 profile
 2. 读取 more_information、interest_tags、个人描述等
-3. 结合你对用户的了解，判断是否推荐
+3. 结合你对用户的了解,判断是否推荐
 4. 如果用户想 accept → 调 `antenna_accept(profile_slug="xxx")`
 
 **不需要先 scan。** Profile 链接是独立的发现路径。
 
-### 4. 活动（Events）
+### 4. 活动(Events)
 同一个活动里的人。详见 EVENTS.md。
 
 ## Tools
 
 ### `antenna_scan`
-扫描附近的人和活动。**只读——不会更新你的位置。**
-- `lat`, `lng`：坐标（可选，没有的话用已绑定的 GPS）
-- `radius_m`：搜索半径（默认 500m，最大 1000m）
-- `sender_id`, `channel`, `chat_id`：必填
-- 返回 `profiles`（附近的人）+ `nearby_events`（5km 内的活动）
-- 每个 profile 包含 `ref`（用于 accept）、`profile_slug`（公开链接）、`more_information`（匹配上下文）
+扫描附近的人和活动。**只读--不会更新你的位置。**
+- `lat`, `lng`:坐标(可选,没有的话用已绑定的 GPS)
+- `radius_m`:搜索半径(默认 500m,最大 1000m)
+- `sender_id`, `channel`, `chat_id`:必填
+- 返回 `profiles`(附近的人)+ `nearby_events`(5km 内的活动)
+- 每个 profile 包含 `ref`(用于 accept)、`profile_slug`(公开链接)、`more_information`(匹配上下文)
 
-**GPS 时效：** 如果 `last_seen_at` 超过 2 小时，提示用户更新位置。
+**GPS 时效:** 如果 `last_seen_at` 超过 2 小时,提示用户更新位置。
 
 ### `antenna_profile`
 查看或更新用户名片。
-- `action`："get" 或 "set"
+- `action`:"get" 或 "set"
 - `sender_id`, `channel`, `chat_id`
-- "set" 时传：`display_name`, `line1`, `line2`, `line3`, `visible`, `matching_context`
+- "set" 时传:`display_name`, `line1`, `line2`, `line3`, `visible`, `matching_context`
 
-名片内容：
-- **display_name**：显示名称
-- **line1**：个人描述（谁 / 做什么）
-- **line2**：想认识的人
-- **line3**：想要的交流方式
-- **matching_context**（more_information，不展示给别人）：agent 基于对用户的了解生成的详细描述，~200 字。**这是匹配的核心数据源。** line1/2/3 从它提炼出来，不是反过来。
+名片内容:
+- **display_name**:显示名称
+- **line1**:个人描述(谁 / 做什么)
+- **line2**:想认识的人
+- **line3**:想要的交流方式
+- **matching_context**(more_information,不展示给别人):agent 基于对用户的了解生成的详细描述,~200 字。**这是匹配的核心数据源。** line1/2/3 从它提炼出来,不是反过来。
 
 ### `antenna_accept`
-接受一个匹配。**不需要先 scan**——任何发现路径都可以触发 accept。
-- `sender_id`, `channel`, `chat_id`：必填
-- 三种方式指定对方（任选一种）：
-  - `ref`：来自 scan/discover 结果的编号
-  - `profile_slug`：来自 profile 链接（如 `antenna.fyi/p/yi` → `profile_slug="yi"`）
-  - `target_device_id`：内部 ID（尽量用 ref 或 slug）
-- `contact_info`（可选）：分享联系方式
+接受一个匹配。**不需要先 scan**--任何发现路径都可以触发 accept。
+- `sender_id`, `channel`, `chat_id`:必填
+- 三种方式指定对方(任选一种):
+  - `ref`:来自 scan/discover 结果的编号
+  - `profile_slug`:来自 profile 链接(如 `antenna.fyi/p/yi` → `profile_slug="yi"`)
+  - `target_device_id`:内部 ID(尽量用 ref 或 slug)
+- `contact_info`(可选):分享联系方式
 
 ### `antenna_pass`
-跳过一个人，不再推荐。
+跳过一个人,不再推荐。
 - `sender_id`, `channel`, `chat_id`
 - `ref` 或 `target_device_id`
 
@@ -163,68 +171,75 @@ openclaw cron add --every 1h --message "Check antenna matches: call antenna_chec
 ### `antenna_bind`
 生成 GPS 绑定链接。
 - `sender_id`, `channel`, `chat_id`
-- `purpose`：`'profile'`（默认，更新用户位置）或 `'event'`（设活动位置）
-- `event_code`：purpose=event 时必填
-- 返回 URL，用户在手机打开后自动共享位置
+- `purpose`:`'profile'`(默认,更新用户位置)或 `'event'`(设活动位置)
+- `event_code`:purpose=event 时必填
+- 返回 URL,用户在手机打开后自动共享位置
 - **Onboarding 后必须调用。** 不要等用户问。
 
 ### `antenna_link_account`
 关联 agent profile 到 antenna.fyi 网站账号。
-- `sender_id`, `channel`, `chat_id`：必填
-- `user_id`：用户的 antenna.fyi 账号 UUID（从 dashboard 获取）
-- 把已有的 agent profile（带全部历史）绑定到网站账号
-- 如果用户先在网站注册了（产生空 profile），空 profile 自动删除
+- `sender_id`, `channel`, `chat_id`:必填
+- `user_id`:用户的 antenna.fyi 账号 UUID(从 dashboard 获取)
+- 把已有的 agent profile(带全部历史)绑定到网站账号
+- 如果用户先在网站注册了(产生空 profile),空 profile 自动删除
 - 一次性操作
 
 ### `antenna_discover`
-全球推荐——每天 1 个最匹配的人。
+全球推荐--每天 1 个最匹配的人。
 - `sender_id`, `channel`, `chat_id`
 - 不需要 GPS
-- 如果所有人都推荐过了，返回"等新人加入"
+- 如果所有人都推荐过了,返回"等新人加入"
+
+### `antenna_initial_recommendations`
+首次推荐--注册后立刻看到 2-3 个最匹配的人。
+- `sender_id`, `channel`, `chat_id`: from context
+- One-time only - second call returns empty
+- Does NOT consume daily discover quota
+- Use in onboarding step 3, right after profile save
 
 ### `antenna_checkin`
-签到——更新你的位置。
-- `lat`, `lng`：必填
+签到--更新你的位置。
+- `lat`, `lng`:必填
 - `sender_id`, `channel`, `chat_id`
-- `place_name`：可选
+- `place_name`:可选
 - 用于"我在 XX"场景
 
 ## GPS Logic
 
-**Profile GPS** — 用户的位置
+**Profile GPS** - 用户的位置
 - 通过 `antenna_bind(purpose="profile")` 或 `antenna_checkin` 更新
 - 位置不原始存储
-- 2 小时后概念上过期，agent 应提示刷新
+- 2 小时后概念上过期,agent 应提示刷新
 
-**Event GPS** — 活动的位置
+**Event GPS** - 活动的位置
 - 通过 `antenna_bind(purpose="event")` 或 `antenna_event_create(lat, lng)` 设置
-- 精确坐标（不模糊）
+- 精确坐标(不模糊)
 - 不过期
 
 ## Behavior Guidelines
 
 ### 名片创建原则
-- **不要让用户填表。** 跟用户聊天，你来生成。
+- **不要让用户填表。** 跟用户聊天,你来生成。
 - **每次只问一个问题。**
 - **用户说的原话尽量保留。** 帮缩短但让用户确认。
 - **不要在名片里写联系方式。** 联系方式在 accept 时分享。
 - **line1 必填。**
 - **确认后才存。**
 
-### Showing results — 你来判断
+### Showing results - 你来判断
 
-scan 和 discover 返回的是 raw profile cards，**没有打分**。你需要：
+scan 和 discover 返回的是 raw profile cards,**没有打分**。你需要:
 1. 读每个人的名片 + more_information
 2. 结合你对用户的全部了解判断谁值得推荐
 3. 为每个推荐的人写一句**个性化的理由**
 4. **不要推荐所有人。** 质量 > 数量。
 
-**全球推荐 fallback：** 如果 scan 结果有 `global: true`，说明附近没人。告诉用户"附近暂时没人，但全球有这个人跟你很像"。
+**全球推荐 fallback:** 如果 scan 结果有 `global: true`,说明附近没人。告诉用户"附近暂时没人,但全球有这个人跟你很像"。
 
 ### Profile 链接场景
 
-用户收到或提到 `antenna.fyi/p/xxx` 时：
-1. 抓取页面，读 `#antenna-profile-data` JSON
+用户收到或提到 `antenna.fyi/p/xxx` 时:
+1. 抓取页面,读 `#antenna-profile-data` JSON
 2. 展示对方 profile + 你的判断
 3. 用户想 accept → `antenna_accept(profile_slug="xxx")`
 4. 用户想 skip → `antenna_pass` 或直接不操作
@@ -232,43 +247,43 @@ scan 和 discover 返回的是 raw profile cards，**没有打分**。你需要
 **这跟 scan 是完全平级的发现路径。**
 
 ### Accepting & contact exchange
-accept 可以从任何路径触发：
-1. 调 `antenna_accept`（用 ref、profile_slug 或 device_id）
-2. **立刻问**："想分享什么联系方式给对方？"
+accept 可以从任何路径触发:
+1. 调 `antenna_accept`(用 ref、profile_slug 或 device_id)
+2. **立刻问**:"想分享什么联系方式给对方?"
 3. 用户给了 → 再调一次 `antenna_accept` 带 `contact_info`
-4. 用户不想 → "先 accept 着，以后想分享再说"
+4. 用户不想 → "先 accept 着,以后想分享再说"
 5. 如果 mutual match → 展示对方联系方式
-6. 如果还没 mutual → "已发出，等对方回应"
+6. 如果还没 mutual → "已发出,等对方回应"
 
 **不要跳过第 2 步。**
 
 ### Privacy
-- **永远不要显示 device_id**——这是内部标识符
+- **永远不要显示 device_id**--这是内部标识符
 - 只展示名字 + 三句话 + 你写的匹配理由
 - 不要泄露对方的平台或用户名
 - 联系方式只在用户明确同意时分享
 - GPS 不原始存储
 
-### Time Decay — 可见性衰减
-- Event 后 0-7 天：全部参与者互相可见
-- 7-30 天：只有互相 scan 过 / 有共同活动的人可见
-- 30 天后：需要新事件激活
+### Time Decay - 可见性衰减
+- Event 后 0-7 天:全部参与者互相可见
+- 7-30 天:只有互相 scan 过 / 有共同活动的人可见
+- 30 天后:需要新事件激活
 
-### Heartbeat — 自动查匹配
-Plugin 后台每 10 分钟查一次新匹配。看到 `[Antenna] 🎉` 时：
+### Heartbeat - 自动查匹配
+Plugin 后台每 10 分钟查一次新匹配。看到 `[Antenna] 🎉` 时:
 1. 调 `antenna_check_matches`
 2. 告诉用户 + 展示对方名片
-3. 展示联系方式（如果有）
+3. 展示联系方式(如果有)
 
 ## Events
 
-详见 EVENTS.md。包括：`antenna_event_create`, `antenna_event_join`, `antenna_event_scan`, `antenna_event_end`, `antenna_event_checkin`, `antenna_event_upload_image`, `antenna_event_update`, `antenna_event_approve`, `antenna_event_reject`, `antenna_event_add_host`, `antenna_event_message`。
+详见 EVENTS.md。包括:`antenna_event_create`, `antenna_event_join`, `antenna_event_scan`, `antenna_event_end`, `antenna_event_checkin`, `antenna_event_upload_image`, `antenna_event_update`, `antenna_event_approve`, `antenna_event_reject`, `antenna_event_add_host`, `antenna_event_message`。
 
 ## Data Transparency
 
 Antenna 只跟 Supabase (bcudjloikmpcqwcptuyd.supabase.co) 通信。
 
-**发送的数据：** GPS（不原始存储）、名片文本、匹配状态、你选择分享的联系方式、Profile embedding。
-**不发送的数据：** 你跟 agent 的对话、文件、浏览记录。
+**发送的数据:** GPS(不原始存储)、名片文本、匹配状态、你选择分享的联系方式、Profile embedding。
+**不发送的数据:** 你跟 agent 的对话、文件、浏览记录。
 
 Source code: https://github.com/H1an1/Antenna