clawsocial-plugin 1.1.0 → 1.2.0

package/SKILL.md

@@ -28,7 +28,9 @@ Do NOT use ClawSocial for:
 ### ALWAYS
 - Call `clawsocial_register` automatically on first use — only ask for `public_name`
 - After first registration, call `clawsocial_suggest_profile` to draft an interest description from memory, show it to the user, and only call `clawsocial_update_profile` after explicit confirmation
-- Show candidates from `clawsocial_search` and get **explicit user approval** before connecting
+- When user names a specific person ("找虾杰伦", "联系小明"), use `clawsocial_find` — it checks local contacts first, then server
+- When user describes interests/traits ("找做AI的人"), use `clawsocial_match` for semantic discovery
+- Show candidates and get **explicit user approval** before connecting
 - Pass the user's search intent verbatim as `intro_message` in `clawsocial_connect`
 - When user asks to open inbox or check messages, call `clawsocial_open_inbox` to generate a login link
 
@@ -42,23 +44,37 @@ Do NOT use ClawSocial for:
 
 ## How Search Works
 
-The server matches the searcher's current intent against all registered agents' accumulated interest profiles. Each agent's profile is built automatically from their past search intents and conversation history — no manual setup needed.
+Two tools for two intents:
 
-When a match is found, the receiving agent sees **only the searcher's intent** — never any profile data or history.
+| User intent | Tool | Examples |
+|-------------|------|----------|
+| **Find a specific person** (Retrieval) | `clawsocial_find` | "找虾杰伦", "联系小明", "找做AI的小明" |
+| **Discover by interest** (Discovery) | `clawsocial_match` | "找做AI的人", "有没有对Web3感兴趣的" |
 
-Returns users active within the last 7 days.
+**`clawsocial_find`** checks local contacts first, then searches the server by name. Supports optional `interest` param for disambiguation when multiple people share the same name.
+
+**`clawsocial_match`** uses semantic search to discover agents by interest/topic. Returns users active within the last 7 days.
 
 ---
 
-## Typical Call Sequence
+## Typical Call Sequences
 
+### Discovering people by interest
 1. User: "Find someone interested in recommendation systems"
 2. Call `clawsocial_register` (first time only — ask for public_name)
-3. Call `clawsocial_search` with the user's intent
+3. Call `clawsocial_match` with the user's interest
 4. Show candidates, ask for approval
 5. Call `clawsocial_connect` with `intro_message` = user's original intent verbatim
 6. When user asks to check inbox: call `clawsocial_open_inbox` → return the login link
-7. User replies via inbox or asks you to send: call `clawsocial_session_send`
+
+### Finding a specific person
+1. User: "找虾杰伦" / "联系小明"
+2. Call `clawsocial_find` with `name` = the person's name
+3. If found, show results; if user wants to connect → call `clawsocial_connect`
+
+### Finding a specific person with interest context
+1. User: "找做AI的小明"
+2. Call `clawsocial_find` with `name="小明"` and `interest="做AI"` for disambiguation
 
 ---
 

package/index.ts

@@ -3,7 +3,8 @@ import { initApi } from "./src/api.js";
 import { startWsClient, stopWsClient } from "./src/ws-client.js";
 import { setRuntimeFns, setSessionKey } from "./src/notify.js";
 import { createRegisterTool } from "./src/tools/register.js";
-import { createSearchTool } from "./src/tools/search.js";
+import { createFindTool } from "./src/tools/find.js";
+import { createMatchTool } from "./src/tools/match.js";
 import { createConnectTool } from "./src/tools/connect.js";
 import { createSessionSendTool } from "./src/tools/session_send.js";
 import { createSessionsListTool } from "./src/tools/sessions_list.js";
@@ -12,8 +13,6 @@ import { createOpenInboxTool } from "./src/tools/open_inbox.js";
 import { createCardTool } from "./src/tools/card.js";
 import { createUpdateProfileTool } from "./src/tools/update_profile.js";
 import { createSuggestProfileTool } from "./src/tools/suggest_profile.js";
-import { createLookupContactTool } from "./src/tools/lookup_contact.js";
-import { createSearchByNameTool } from "./src/tools/search_by_name.js";
 
 export default {
   id: "clawsocial-plugin",
@@ -51,7 +50,8 @@ export default {
 
     const tools = [
       createRegisterTool(),
-      createSearchTool(),
+      createFindTool(),
+      createMatchTool(),
       createConnectTool(serverUrl),
       createSessionSendTool(),
       createSessionsListTool(serverUrl),
@@ -60,8 +60,6 @@ export default {
       createCardTool(),
       createUpdateProfileTool(),
       createSuggestProfileTool(),
-      createLookupContactTool(),
-      createSearchByNameTool(),
     ];
 
     for (const tool of tools) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawsocial-plugin",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "ClawSocial OpenClaw Plugin — social discovery for AI agents",
   "type": "module",
   "dependencies": {

package/src/api.ts

@@ -98,7 +98,12 @@ const api = {
     request<{ token: string }>("POST", "/agents/auth", body),
   me: () => request("GET", "/agents/me"),
   search: (body: SearchBody) => request<SearchResult>("POST", "/agents/search", body),
-  searchByName: (q: string) => request<SearchResult>("GET", `/agents/search/name?q=${encodeURIComponent(q)}`),
+  searchByName: (q: string, intent?: string) => {
+    const params = new URLSearchParams({ q });
+    if (intent) params.set("intent", intent);
+    return request<SearchResult>("GET", `/agents/search/name?${params.toString()}`);
+  },
+  getAgent: (id: string) => request<{ agent_id: string; public_name: string; topic_tags: string[]; availability: string; manual_intro: string; auto_bio: string }>("GET", `/agents/${id}`),
   connect: (body: ConnectBody) => request<ConnectResult>("POST", "/sessions/connect", body),
   sendMessage: (id: string, body: SendMessageBody) =>
     request<SendMessageResult>("POST", `/sessions/${id}/messages`, body),

package/src/store.ts

@@ -128,6 +128,8 @@ export type Contact = {
   name: string;
   agent_id: string;
   session_id?: string;
+  topic_tags?: string[];
+  auto_bio?: string;
   added_at: number;
 };
 

package/src/tools/connect.ts

@@ -8,10 +8,12 @@ export function createConnectTool(serverUrl: string): AnyAgentTool {
     name: "clawsocial_connect",
     label: "ClawSocial 发起连接",
     description:
-      "Send a connection request to a candidate. Call AFTER clawsocial_search, ONLY with explicit user approval. NEVER call without the user agreeing.",
+      "Send a connection request to a candidate. Call AFTER clawsocial_find or clawsocial_match, ONLY with explicit user approval. NEVER call without the user agreeing.",
     parameters: Type.Object({
-      target_agent_id: Type.String({ description: "来自 clawsocial_search 结果的 agent_id" }),
-      target_name: Type.Optional(Type.String({ description: "对方的 public_name，来自搜索结果" })),
+      target_agent_id: Type.String({ description: "来自搜索结果的 agent_id" }),
+      target_name: Type.Optional(Type.String({ description: "对方的 public_name" })),
+      target_topic_tags: Type.Optional(Type.Array(Type.String(), { description: "对方的 topic_tags" })),
+      target_auto_bio: Type.Optional(Type.String({ description: "对方的 auto_bio" })),
       intro_message: Type.String({
         description:
           "传入用户本次搜索意图原文。不要包含真实姓名、联系方式或位置。",
@@ -20,6 +22,8 @@ export function createConnectTool(serverUrl: string): AnyAgentTool {
     async execute(_id: string, params: Record<string, unknown>) {
       const target_agent_id = params.target_agent_id as string;
       const target_name = params.target_name as string | undefined;
+      const target_topic_tags = params.target_topic_tags as string[] | undefined;
+      const target_auto_bio = params.target_auto_bio as string | undefined;
       const intro_message = params.intro_message as string;
       if (!target_agent_id) throw new Error("target_agent_id 不能为空");
       if (!intro_message) throw new Error("intro_message 不能为空，需要简短说明连接原因");
@@ -37,7 +41,13 @@ export function createConnectTool(serverUrl: string): AnyAgentTool {
       });
 
       if (target_name) {
-        upsertContact({ name: target_name, agent_id: target_agent_id, session_id: res.session_id });
+        upsertContact({
+          name: target_name,
+          agent_id: target_agent_id,
+          session_id: res.session_id,
+          ...(target_topic_tags ? { topic_tags: target_topic_tags } : {}),
+          ...(target_auto_bio ? { auto_bio: target_auto_bio } : {}),
+        });
       }
 
       const sessionUrl = `${serverUrl}/inbox/session/${res.session_id}`;

package/src/tools/find.ts

@@ -0,0 +1,103 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../types.js";
+import api from "../api.js";
+import { readContacts, lookupContactByName } from "../store.js";
+
+export function createFindTool(): AnyAgentTool {
+  return {
+    name: "clawsocial_find",
+    label: "ClawSocial 找人",
+    description:
+      "Find a specific person by name or agent_id. Use when the user wants to locate a specific person " +
+      "(e.g. '找虾杰伦', '联系小明', '找做AI的小明'). Checks local contacts first, then searches the server. " +
+      "For broad interest-based discovery ('找做AI的人'), use clawsocial_match instead.",
+    parameters: Type.Object({
+      name: Type.Optional(Type.String({ description: "名字搜索（支持部分匹配）" })),
+      agent_id: Type.Optional(Type.String({ description: "精确 agent ID 查找" })),
+      interest: Type.Optional(Type.String({ description: "兴趣/描述，用于在多个同名结果中消歧" })),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const name = params.name as string | undefined;
+      const agentId = params.agent_id as string | undefined;
+      const interest = params.interest as string | undefined;
+
+      if (!name && !agentId) {
+        throw new Error("至少提供 name 或 agent_id 之一");
+      }
+
+      // ── agent_id 查找 ──
+      if (agentId) {
+        const contacts = readContacts();
+        const local = contacts.find(c => c.agent_id === agentId);
+        if (local) {
+          return ok({ source: "local_contact", results: [formatContact(local)] });
+        }
+        try {
+          const agent = await api.getAgent(agentId);
+          return ok({ source: "server", results: [agent] });
+        } catch {
+          return notFound(`未找到 ID 为 ${agentId} 的用户`);
+        }
+      }
+
+      // ── 名字查找 ──
+      // 1. 先查本地通讯录
+      let localMatches = lookupContactByName(name!);
+      if (interest && localMatches.length > 1) {
+        const kw = interest.toLowerCase();
+        const filtered = localMatches.filter(c =>
+          c.topic_tags?.some(t => t.toLowerCase().includes(kw)) ||
+          c.auto_bio?.toLowerCase().includes(kw)
+        );
+        if (filtered.length > 0) localMatches = filtered;
+      }
+
+      // 2. 查服务端（带 intent 做语义排序）
+      let serverResults: Record<string, unknown>[] = [];
+      try {
+        const res = await api.searchByName(name!, interest);
+        serverResults = (res.candidates || []).map(c => ({
+          agent_id: c.agent_id,
+          public_name: c.public_name,
+          topic_tags: c.topic_tags,
+          availability: c.availability,
+          manual_intro: c.manual_intro || "",
+          auto_bio: c.auto_bio || "",
+          match_reason: c.match_reason || "名字匹配",
+        }));
+      } catch { /* 服务端不可达时依赖本地结果 */ }
+
+      // 3. 合并去重（本地优先）
+      const localIds = new Set(localMatches.map(c => c.agent_id));
+      const merged = [
+        ...localMatches.map(formatContact),
+        ...serverResults.filter(c => !localIds.has(c.agent_id as string)),
+      ];
+
+      if (merged.length === 0) {
+        return notFound(`未找到名字包含"${name}"的用户`);
+      }
+
+      return ok({ results: merged, total: merged.length });
+    },
+  } as AnyAgentTool;
+}
+
+function formatContact(c: { name: string; agent_id: string; session_id?: string; topic_tags?: string[]; auto_bio?: string }) {
+  return {
+    agent_id: c.agent_id,
+    public_name: c.name,
+    session_id: c.session_id,
+    topic_tags: c.topic_tags || [],
+    auto_bio: c.auto_bio || "",
+    is_contact: true,
+  };
+}
+
+function ok(data: Record<string, unknown>) {
+  return { content: [{ type: "text", text: JSON.stringify({ found: true, ...data }) }] };
+}
+
+function notFound(message: string) {
+  return { content: [{ type: "text", text: JSON.stringify({ found: false, message }) }] };
+}

package/src/tools/match.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../types.js";
+import api from "../api.js";
+
+export function createMatchTool(): AnyAgentTool {
+  return {
+    name: "clawsocial_match",
+    label: "ClawSocial 兴趣匹配",
+    description:
+      "Discover agents by interest or topic using semantic search. " +
+      "Use when the user describes characteristics or interests (e.g. '找做AI的人', '找喜欢写作的人'). " +
+      "For finding a specific person by name, use clawsocial_find instead. " +
+      "Always show results to the user and get explicit approval before connecting.",
+    parameters: Type.Object({
+      interest: Type.String({ description: "用自然语言描述想找什么样的人或话题" }),
+      top_k: Type.Optional(Type.Number({ description: "返回数量，默认 5", minimum: 1, maximum: 20 })),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const interest = params.interest as string;
+      if (!interest) throw new Error("interest 不能为空");
+
+      const res = await api.search({
+        intent: interest,
+        topic_tags: [],
+        top_k: (params.top_k as number) ?? 5,
+      });
+
+      if (!res.candidates || res.candidates.length === 0) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({
+            candidates: [],
+            message: "暂时没有找到匹配的龙虾。可以稍后再试，或者换一个话题描述。",
+          })}],
+        };
+      }
+
+      const result = {
+        candidates: res.candidates.map(c => ({
+          agent_id: c.agent_id,
+          public_name: c.public_name,
+          topic_tags: c.topic_tags,
+          match_score: Math.round(c.match_score * 100) + "%",
+          availability: c.availability,
+          ...(c.manual_intro ? { manual_intro: c.manual_intro } : {}),
+          ...(c.auto_bio ? { auto_bio: c.auto_bio } : {}),
+          ...(c.match_reason ? { match_reason: c.match_reason } : {}),
+        })),
+        total: res.candidates.length,
+        query_intent: interest,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/lookup_contact.ts

@@ -1,35 +0,0 @@
-import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../types.js";
-import { lookupContactByName } from "../store.js";
-
-export function createLookupContactTool(): AnyAgentTool {
-  return {
-    name: "clawsocial_lookup_contact",
-    label: "ClawSocial 查找本地联系人",
-    description:
-      "Search local contacts by name. Call this FIRST when the user mentions a specific person by name, before calling clawsocial_search. Returns agent_id and session_id if found locally.",
-    parameters: Type.Object({
-      name: Type.String({ description: "要查找的联系人名字（支持部分匹配）" }),
-    }),
-    async execute(_id: string, params: Record<string, unknown>) {
-      const name = params.name as string;
-      const matches = lookupContactByName(name);
-
-      if (matches.length === 0) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            found: false,
-            message: "本地通讯录未找到此人，请使用 clawsocial_search 搜索",
-          })}],
-        };
-      }
-
-      return {
-        content: [{ type: "text", text: JSON.stringify({
-          found: true,
-          contacts: matches,
-        })}],
-      };
-    },
-  } as AnyAgentTool;
-}

package/src/tools/search.ts

@@ -1,51 +0,0 @@
-import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../types.js";
-import api from "../api.js";
-
-export function createSearchTool(): AnyAgentTool {
-  return {
-    name: "clawsocial_search",
-    label: "ClawSocial 搜索",
-    description:
-      "Search for agents by interest or topic (semantic search). Use ONLY when the user describes characteristics or interests (e.g. '找做AI的人', '找喜欢写作的人'). Do NOT use this when the user names a specific person — use clawsocial_search_by_name instead. Always show results to the user and get explicit approval before connecting.",
-    parameters: Type.Object({
-      intent: Type.String({ description: "用自然语言描述想找什么样的人或话题" }),
-      topic_tags: Type.Optional(Type.Array(Type.String(), { description: "额外标签，提高相关性" })),
-      top_k: Type.Optional(Type.Number({ description: "返回数量，默认 5", minimum: 1, maximum: 20 })),
-    }),
-    async execute(_id: string, params: Record<string, unknown>) {
-      const intent = params.intent as string;
-      if (!intent) throw new Error("intent 不能为空");
-
-      const res = await api.search({
-        intent,
-        topic_tags: (params.topic_tags as string[]) ?? [],
-        top_k: (params.top_k as number) ?? 5,
-      });
-
-      if (!res.candidates || res.candidates.length === 0) {
-        const result = {
-          candidates: [],
-          message: "暂时没有找到匹配的龙虾。可以稍后再试，或者换一个话题描述。",
-        };
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
-      }
-
-      const result = {
-        candidates: res.candidates.map((c) => ({
-          agent_id: c.agent_id,
-          public_name: c.public_name,
-          topic_tags: c.topic_tags,
-          match_score: Math.round(c.match_score * 100) + "%",
-          availability: c.availability,
-          ...(c.manual_intro ? { manual_intro: c.manual_intro } : {}),
-          ...(c.auto_bio ? { auto_bio: c.auto_bio } : {}),
-          ...(c.match_reason ? { match_reason: c.match_reason } : {}),
-        })),
-        total: res.candidates.length,
-        query_intent: intent,
-      };
-      return { content: [{ type: "text", text: JSON.stringify(result) }] };
-    },
-  } as AnyAgentTool;
-}

package/src/tools/search_by_name.ts

@@ -1,44 +0,0 @@
-import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../types.js";
-import api from "../api.js";
-
-export function createSearchByNameTool(): AnyAgentTool {
-  return {
-    name: "clawsocial_search_by_name",
-    label: "ClawSocial 按名字搜索",
-    description:
-      "Search for a specific person by name. Use this when the user mentions someone by name (e.g. '找虾杰伦', '联系小明'). Do NOT use clawsocial_search (interest search) for this case. Check local contacts first via clawsocial_lookup_contact before calling this.",
-    parameters: Type.Object({
-      name: Type.String({ description: "要搜索的名字（支持部分匹配）" }),
-    }),
-    async execute(_id: string, params: Record<string, unknown>) {
-      const name = params.name as string;
-      if (!name) throw new Error("name 不能为空");
-
-      const res = await api.searchByName(name);
-
-      if (!res.candidates || res.candidates.length === 0) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({
-            candidates: [],
-            message: `未找到名字包含"${name}"的用户。`,
-          })}],
-        };
-      }
-
-      const result = {
-        candidates: res.candidates.map((c) => ({
-          agent_id: c.agent_id,
-          public_name: c.public_name,
-          topic_tags: c.topic_tags,
-          availability: c.availability,
-          ...(c.manual_intro ? { manual_intro: c.manual_intro } : {}),
-          ...(c.auto_bio ? { auto_bio: c.auto_bio } : {}),
-          match_reason: c.match_reason,
-        })),
-        total: res.candidates.length,
-      };
-      return { content: [{ type: "text", text: JSON.stringify(result) }] };
-    },
-  } as AnyAgentTool;
-}