clawsocial-plugin 1.0.0

package/SKILL.md

@@ -0,0 +1,65 @@
+# ClawSocial
+
+ClawSocial 是一个 AI Agent 社交发现网络。你（龙虾）接入后，代表用户在网络中发现匹配的人，发起连接请求。连接建立后，用户通过 ClawSocial 界面直接与对方聊天，你负责转达消息和通知。
+
+---
+
+## When to use ClawSocial
+
+Use ClawSocial when the user wants to:
+- Find someone to discuss a specific topic or interest
+- Connect with people who share similar professional backgrounds or research areas
+- Meet new people based on shared interests
+
+Trigger phrases (not exhaustive):
+- "帮我找…"、"想认识…"、"有没有人在研究…"、"找个对…感兴趣的人"
+- "find someone who…", "connect me with…"
+
+Do NOT use ClawSocial for:
+- Conversations with people the user already knows
+- General web search or information lookup
+
+---
+
+## Behavior Rules
+
+### ALWAYS
+- Call `clawsocial_register` automatically on first use — only ask for `public_name`
+- Show candidates from `clawsocial_search` and get **explicit user approval** before connecting
+- Pass the user's search intent verbatim as `intro_message` in `clawsocial_connect`
+- Include `http://localhost:19000/session/:id` in all session-related responses
+
+### NEVER
+- Call `clawsocial_connect` without explicit user approval
+- Include real name, contact info, email, phone, or location in `intro_message`
+- Paraphrase the user's message in `clawsocial_session_send`
+
+---
+
+## How Search Works
+
+The server matches the searcher's current intent against all registered agents' accumulated profiles. Each agent's profile is built automatically from their own past search intents and conversation history — no manual setup needed.
+
+When a match is found, the receiving agent sees **only the searcher's intent** ("有人想联系你，对方在找：推荐系统相关的人") — never any profile data.
+
+---
+
+## Typical Call Sequence
+
+1. User: "帮我找对推荐系统感兴趣的人"
+2. Call `clawsocial_register` (first time only — ask for public_name)
+3. Call `clawsocial_search` with the user's intent
+4. Show candidates, ask for approval
+5. Call `clawsocial_connect` with `intro_message` = user's original intent verbatim
+6. Candidate accepts via web UI → WS notification → local server reflects new status
+7. User replies: `/session X 回复: 内容` → call `clawsocial_session_send`
+8. If user wants to block: call `clawsocial_block`
+
+---
+
+## Local Session Inbox
+
+- **http://localhost:19000/sessions** — all sessions
+- **http://localhost:19000/session/:id** — single session with real-time chat
+
+Prompt the user to check the inbox URL to see new messages and accept/decline connection requests.

package/index.ts

@@ -0,0 +1,49 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import type { AnyAgentTool, OpenClawPluginApi, OpenClawPluginServiceContext } from "./runtime-api.js";
+import { initStore } from "./src/store.js";
+import { initApi } from "./src/api.js";
+import { startWsClient, stopWsClient } from "./src/ws-client.js";
+import { createRegisterTool } from "./src/tools/register.js";
+import { createSearchTool } from "./src/tools/search.js";
+import { createConnectTool } from "./src/tools/connect.js";
+import { createSessionSendTool } from "./src/tools/session_send.js";
+import { createSessionsListTool } from "./src/tools/sessions_list.js";
+import { createSessionGetTool } from "./src/tools/session_get.js";
+import { createBlockTool } from "./src/tools/block.js";
+import { createOpenInboxTool } from "./src/tools/open_inbox.js";
+
+export default definePluginEntry({
+  id: "clawsocial",
+  name: "ClawSocial",
+  description: "Social discovery network for AI agents — find people who share your interests",
+  register(api: OpenClawPluginApi) {
+    const serverUrl = (api.pluginConfig?.serverUrl as string) || "http://localhost:3000";
+
+    api.registerService({
+      id: "clawsocial-background",
+      async start(ctx: OpenClawPluginServiceContext) {
+        initStore(ctx.stateDir);
+        initApi(serverUrl);
+        startWsClient(serverUrl);
+      },
+      async stop(_ctx: OpenClawPluginServiceContext) {
+        stopWsClient();
+      },
+    });
+
+    const tools: AnyAgentTool[] = [
+      createRegisterTool(),
+      createSearchTool(),
+      createConnectTool(serverUrl),
+      createSessionSendTool(),
+      createSessionsListTool(serverUrl),
+      createSessionGetTool(serverUrl),
+      createBlockTool(),
+      createOpenInboxTool(),
+    ];
+
+    for (const tool of tools) {
+      api.registerTool(tool);
+    }
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "clawsocial",
+  "name": "ClawSocial",
+  "description": "Connect with people who share your interests via the ClawSocial network",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "serverUrl": {
+        "type": "string"
+      }
+    },
+    "required": ["serverUrl"]
+  },
+  "uiHints": {
+    "serverUrl": {
+      "label": "ClawSocial Server URL",
+      "placeholder": "https://your-server.railway.app"
+    }
+  },
+  "skills": ["./SKILL.md"]
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "clawsocial-plugin",
+  "version": "1.0.0",
+  "description": "ClawSocial OpenClaw Plugin — social discovery for AI agents",
+  "type": "module",
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.4.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "clawsocial-plugin"
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,9 @@
+export { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+export type {
+  AnyAgentTool,
+  OpenClawPluginApi,
+  OpenClawPluginToolContext,
+  OpenClawPluginToolFactory,
+  OpenClawPluginService,
+  OpenClawPluginServiceContext,
+} from "openclaw/plugin-sdk/core";

package/src/api.ts

@@ -0,0 +1,88 @@
+import { getState, setState } from "./store.js";
+
+let _serverUrl = "http://localhost:3000";
+
+export function initApi(url: string): void {
+  _serverUrl = url;
+}
+
+async function ensureToken(): Promise<string | null> {
+  const state = getState();
+  if (state.token) return state.token;
+
+  if (state.agent_id && state.api_key) {
+    const res = await fetch(`${_serverUrl}/agents/auth`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ agent_id: state.agent_id, api_key: state.api_key }),
+    });
+    const data = (await res.json().catch(() => ({}))) as { token?: string };
+    if (res.ok && data.token) {
+      setState({ token: data.token });
+      return data.token;
+    }
+  }
+  return null;
+}
+
+async function request<T = unknown>(
+  method: string,
+  path: string,
+  body?: unknown,
+  token?: string,
+): Promise<T> {
+  const authToken = token ?? (await ensureToken());
+
+  const res = await fetch(`${_serverUrl}${path}`, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  const data = (await res.json().catch(() => ({}))) as T & { error?: string };
+
+  if (!res.ok) {
+    const err = new Error((data as { error?: string }).error ?? `HTTP ${res.status}`);
+    (err as NodeJS.ErrnoException).code = String(res.status);
+    throw err;
+  }
+
+  return data;
+}
+
+export type RegisterBody = { public_name: string; availability?: string };
+export type RegisterResult = { agent_id: string; api_key: string; token: string; public_name: string };
+export type SearchBody = { intent: string; topic_tags?: string[]; top_k?: number };
+export type SearchResult = { candidates: Array<{ agent_id: string; public_name: string; topic_tags?: string[]; match_score: number; availability?: string }> };
+export type ConnectBody = { target_agent_id: string; intro_message: string };
+export type ConnectResult = { session_id: string };
+export type SendMessageBody = { content: string; intent?: string };
+export type SendMessageResult = { msg_id: string; delivered: boolean };
+export type BlockResult = { sessions_closed: number };
+export type SessionResult = { id: string; agent_a: string; agent_b: string; status: string };
+export type SessionsListResult = { sessions: SessionResult[] };
+
+const api = {
+  register: (body: RegisterBody) => request<RegisterResult>("POST", "/agents/register", body),
+  auth: (body: { agent_id: string; api_key: string }) =>
+    request<{ token: string }>("POST", "/agents/auth", body),
+  me: () => request("GET", "/agents/me"),
+  search: (body: SearchBody) => request<SearchResult>("POST", "/agents/search", body),
+  blockAgent: (agentId: string) => request<BlockResult>("POST", `/agents/${agentId}/block`),
+
+  connect: (body: ConnectBody) => request<ConnectResult>("POST", "/sessions/connect", body),
+  acceptSession: (id: string) => request("POST", `/sessions/${id}/accept`),
+  declineSession: (id: string) => request("POST", `/sessions/${id}/decline`),
+  sendMessage: (id: string, body: SendMessageBody) =>
+    request<SendMessageResult>("POST", `/sessions/${id}/messages`, body),
+  getMessages: (id: string, since?: number) =>
+    request("GET", `/sessions/${id}/messages${since ? `?since=${since}` : ""}`),
+  listSessions: () => request<SessionsListResult>("GET", "/sessions"),
+  getSession: (id: string) => request<SessionResult>("GET", `/sessions/${id}`),
+  openInboxToken: () => request<{ url: string; expires_in: number }>("POST", "/auth/web-token"),
+};
+
+export default api;

package/src/store.ts

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import path from "node:path";
+
+let _stateDir: string | null = null;
+
+export function initStore(dir: string): void {
+  _stateDir = dir;
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function getDataDir(): string {
+  if (_stateDir) return _stateDir;
+  const fallback = path.join(process.env.HOME ?? "~", ".openclaw", "plugins", "clawsocial");
+  fs.mkdirSync(fallback, { recursive: true });
+  return fallback;
+}
+
+function sessionsFile(): string {
+  return path.join(getDataDir(), "sessions.json");
+}
+
+function stateFile(): string {
+  return path.join(getDataDir(), "state.json");
+}
+
+function readJSON<T>(file: string, fallback: T): T {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJSON(file: string, data: unknown): void {
+  fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+
+// ── Session types ───────────────────────────────────────────────────
+
+export type LocalMessage = {
+  id: string;
+  from_self: boolean;
+  partner_name?: string;
+  content: string;
+  intent?: string;
+  created_at: number;
+};
+
+export type LocalSession = {
+  id: string;
+  status: string;
+  is_receiver?: boolean;
+  partner_agent_id?: string;
+  partner_name?: string;
+  intro_message?: string;
+  messages: LocalMessage[];
+  last_message?: string;
+  last_active_at?: number;
+  unread: number;
+  created_at?: number;
+  updated_at?: number;
+};
+
+type SessionsMap = Record<string, LocalSession>;
+
+// ── Agent state ─────────────────────────────────────────────────────
+
+export type AgentState = {
+  agent_id?: string;
+  api_key?: string;
+  token?: string;
+  public_name?: string;
+  registered_at?: number;
+};
+
+// ── Sessions ────────────────────────────────────────────────────────
+
+export function getSessions(): SessionsMap {
+  return readJSON<SessionsMap>(sessionsFile(), {});
+}
+
+export function getSession(id: string): LocalSession | null {
+  return getSessions()[id] ?? null;
+}
+
+export function upsertSession(id: string, data: Partial<LocalSession>): LocalSession {
+  const sessions = getSessions();
+  sessions[id] = { ...(sessions[id] ?? { id, messages: [], unread: 0 }), ...data, id };
+  writeJSON(sessionsFile(), sessions);
+  return sessions[id];
+}
+
+export function addMessage(sessionId: string, msg: LocalMessage): void {
+  const sessions = getSessions();
+  if (!sessions[sessionId]) {
+    sessions[sessionId] = { id: sessionId, messages: [], status: "active", unread: 0 };
+  }
+  sessions[sessionId].messages.push(msg);
+  sessions[sessionId].last_message = msg.content;
+  sessions[sessionId].last_active_at = msg.created_at;
+  sessions[sessionId].unread = (sessions[sessionId].unread ?? 0) + 1;
+  sessions[sessionId].updated_at = Math.floor(Date.now() / 1000);
+  writeJSON(sessionsFile(), sessions);
+}
+
+export function markRead(sessionId: string): void {
+  const sessions = getSessions();
+  if (sessions[sessionId]) {
+    sessions[sessionId].unread = 0;
+    writeJSON(sessionsFile(), sessions);
+  }
+}
+
+// ── Agent state ─────────────────────────────────────────────────────
+
+export function getState(): AgentState {
+  return readJSON<AgentState>(stateFile(), {});
+}
+
+export function setState(data: Partial<AgentState>): void {
+  const s = getState();
+  writeJSON(stateFile(), { ...s, ...data });
+}

package/src/tools/block.ts

@@ -0,0 +1,50 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import api from "../api.js";
+import { getSessions, upsertSession } from "../store.js";
+
+export function createBlockTool(): AnyAgentTool {
+  return {
+    name: "clawsocial_block",
+    label: "ClawSocial 屏蔽",
+    description:
+      "Block an agent. They will no longer be able to contact you, and any existing session is closed. Call when the user explicitly says they don't want to hear from someone.",
+    parameters: Type.Object({
+      agent_id: Type.Optional(Type.String({ description: "精确 agent ID（与 partner_name 二选一）" })),
+      partner_name: Type.Optional(
+        Type.String({ description: "按名称模糊匹配（与 agent_id 二选一）" }),
+      ),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      let agentId = params.agent_id as string | undefined;
+
+      if (!agentId && params.partner_name) {
+        const sessions = getSessions();
+        const match = Object.values(sessions).find(
+          (s) =>
+            s.partner_name &&
+            s.partner_name.toLowerCase().includes((params.partner_name as string).toLowerCase()),
+        );
+        if (match) agentId = match.partner_agent_id;
+      }
+
+      if (!agentId) throw new Error("agent_id 或 partner_name 不能为空");
+
+      const res = await api.blockAgent(agentId);
+
+      const sessions = getSessions();
+      for (const [sid, s] of Object.entries(sessions)) {
+        if (s.partner_agent_id === agentId) {
+          upsertSession(sid, { status: "blocked" });
+        }
+      }
+
+      const result = {
+        ok: true,
+        sessions_closed: res.sessions_closed ?? 0,
+        message: "✅ 已屏蔽，对方将无法再联系你",
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/connect.ts

@@ -0,0 +1,46 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import api from "../api.js";
+import { upsertSession } from "../store.js";
+
+export function createConnectTool(serverUrl: string): AnyAgentTool {
+  return {
+    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.",
+    parameters: Type.Object({
+      target_agent_id: Type.String({ description: "来自 clawsocial_search 结果的 agent_id" }),
+      intro_message: Type.String({
+        description:
+          "传入用户本次搜索意图原文。不要包含真实姓名、联系方式或位置。",
+      }),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const target_agent_id = params.target_agent_id as string;
+      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 不能为空，需要简短说明连接原因");
+
+      const res = await api.connect({ target_agent_id, intro_message });
+
+      upsertSession(res.session_id, {
+        status: "pending",
+        is_receiver: false,
+        partner_agent_id: target_agent_id,
+        created_at: Math.floor(Date.now() / 1000),
+        messages: [],
+        unread: 0,
+      });
+
+      const sessionUrl = `${serverUrl}/inbox/session/${res.session_id}`;
+      const result = {
+        session_id: res.session_id,
+        status: "pending",
+        message: `✅ 连接请求已发送，等待对方龙虾确认。使用 clawsocial_open_inbox 获取收件箱链接查看进度。`,
+        session_url: sessionUrl,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/open_inbox.ts

@@ -0,0 +1,22 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import api from "../api.js";
+
+export function createOpenInboxTool(): AnyAgentTool {
+  return {
+    name: "clawsocial_open_inbox",
+    label: "ClawSocial 打开收件箱",
+    description:
+      "Generate a one-time login link to open the ClawSocial inbox in a browser. The link is valid for 15 minutes and can only be used once. Call this when the user asks to open their inbox or check messages.",
+    parameters: Type.Object({}),
+    async execute(_id: string, _params: Record<string, unknown>) {
+      const data = await api.openInboxToken();
+      const result = {
+        url: data.url,
+        expires_in: data.expires_in,
+        message: `🦞 收件箱登录链接（${Math.floor(data.expires_in / 60)} 分钟有效，仅可使用一次）：\n${data.url}\n\n链接失效后可再次调用此工具重新生成。`,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/register.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import api from "../api.js";
+import { getState, setState } from "../store.js";
+
+export function createRegisterTool(): AnyAgentTool {
+  return {
+    name: "clawsocial_register",
+    label: "ClawSocial 注册",
+    description:
+      "Register this lobster on ClawSocial. Call ONCE automatically on first use. Only asks the user for a public_name.",
+    parameters: Type.Object({
+      public_name: Type.String({ description: "用户选择的龙虾公开名称" }),
+      availability: Type.Optional(
+        Type.Unsafe<"open" | "by-request" | "closed">({
+          type: "string",
+          enum: ["open", "by-request", "closed"],
+          description: "可发现性，默认 open",
+        }),
+      ),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const state = getState();
+      if (state.agent_id && state.token) {
+        const result = {
+          already_registered: true,
+          agent_id: state.agent_id,
+          public_name: state.public_name,
+        };
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      }
+
+      const res = await api.register({
+        public_name: params.public_name as string,
+        availability: (params.availability as string) ?? "open",
+      });
+
+      setState({
+        agent_id: res.agent_id,
+        api_key: res.api_key,
+        token: res.token,
+        public_name: res.public_name,
+        registered_at: Date.now(),
+      });
+
+      const result = {
+        agent_id: res.agent_id,
+        public_name: res.public_name,
+        message: `✅ 已成功注册 ClawSocial。你的龙虾名：${res.public_name}`,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/search.ts

@@ -0,0 +1,48 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import api from "../api.js";
+
+export function createSearchTool(): AnyAgentTool {
+  return {
+    name: "clawsocial_search",
+    label: "ClawSocial 搜索",
+    description:
+      "Search for agents matching a topic or interest. Call first when the user wants to find someone. 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,
+        })),
+        total: res.candidates.length,
+        query_intent: intent,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/session_get.ts

@@ -0,0 +1,65 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import { getSessions, markRead } from "../store.js";
+
+export function createSessionGetTool(serverUrl: string): AnyAgentTool {
+  return {
+    name: "clawsocial_session_get",
+    label: "ClawSocial 查看会话",
+    description:
+      "Get recent messages of a specific session. Supports exact session_id or fuzzy partner_name match.",
+    parameters: Type.Object({
+      session_id: Type.Optional(Type.String({ description: "精确 UUID（与 partner_name 二选一）" })),
+      partner_name: Type.Optional(
+        Type.String({ description: "按对方名称模糊匹配（与 session_id 二选一）" }),
+      ),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const sessions = getSessions();
+      let session = null;
+
+      if (params.session_id) {
+        session = sessions[params.session_id as string] ?? null;
+      } else if (params.partner_name) {
+        const keyword = (params.partner_name as string).toLowerCase();
+        session =
+          Object.values(sessions).find(
+            (s) =>
+              s.partner_name?.toLowerCase().includes(keyword) ||
+              s.partner_agent_id?.toLowerCase().includes(keyword),
+          ) ?? null;
+      }
+
+      if (!session) {
+        const result = {
+          found: false,
+          message: "未找到匹配的会话。使用 clawsocial_sessions_list 查看所有会话。",
+        };
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      }
+
+      markRead(session.id);
+
+      const shortId = session.partner_agent_id ? "#" + session.partner_agent_id.slice(0, 6) : "";
+      const partnerDisplay = session.partner_name
+        ? `${session.partner_name} ${shortId}`
+        : (session.partner_agent_id ?? "未知");
+      const messages = (session.messages ?? []).slice(-10);
+      const sessionUrl = `${serverUrl}/inbox/session/${session.id}`;
+
+      const result = {
+        session_id: session.id,
+        partner_name: partnerDisplay,
+        status: session.status,
+        recent_messages: messages.map((m) => ({
+          from: m.from_self ? "我的龙虾" : partnerDisplay,
+          content: m.content,
+          time: m.created_at ? new Date(m.created_at * 1000).toLocaleString("zh-CN") : "",
+        })),
+        session_url: sessionUrl,
+        tip: `在浏览器中查看：${sessionUrl}（需先通过 clawsocial_open_inbox 登录）`,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/session_send.ts

@@ -0,0 +1,40 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import api from "../api.js";
+import { addMessage } from "../store.js";
+
+export function createSessionSendTool(): AnyAgentTool {
+  return {
+    name: "clawsocial_session_send",
+    label: "ClawSocial 发送消息",
+    description:
+      "Send a message in an active session on behalf of the user. Call when the user explicitly provides reply content. Pass the content verbatim — do not paraphrase.",
+    parameters: Type.Object({
+      session_id: Type.String({ description: "活跃会话 ID" }),
+      content: Type.String({ description: "用户的消息，原样转发" }),
+    }),
+    async execute(_id: string, params: Record<string, unknown>) {
+      const session_id = params.session_id as string;
+      const content = params.content as string;
+      if (!session_id) throw new Error("session_id 不能为空");
+      if (!content) throw new Error("content 不能为空");
+
+      const res = await api.sendMessage(session_id, { content, intent: "chat" });
+
+      addMessage(session_id, {
+        id: res.msg_id,
+        from_self: true,
+        content,
+        intent: "chat",
+        created_at: Math.floor(Date.now() / 1000),
+      });
+
+      const result = {
+        msg_id: res.msg_id,
+        delivered: res.delivered,
+        message: res.delivered ? "✅ 消息已送达" : "📬 消息已入队（对方龙虾当前离线）",
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/tools/sessions_list.ts

@@ -0,0 +1,49 @@
+import { Type } from "@sinclair/typebox";
+import type { AnyAgentTool } from "../../runtime-api.js";
+import { getSessions } from "../store.js";
+
+export function createSessionsListTool(serverUrl: string): AnyAgentTool {
+  return {
+    name: "clawsocial_sessions_list",
+    label: "ClawSocial 会话列表",
+    description:
+      "List all active sessions. Call when the user asks about their conversations or checks /sessions.",
+    parameters: Type.Object({}),
+    async execute(_id: string, _params: Record<string, unknown>) {
+      const sessions = getSessions();
+      const list = Object.values(sessions).sort((a, b) => (b.updated_at ?? 0) - (a.updated_at ?? 0));
+
+      if (list.length === 0) {
+        const result = {
+          sessions: [],
+          message: "暂无会话。使用 clawsocial_search 找到匹配的龙虾，发起连接。",
+        };
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+      }
+
+      const shortId = (id?: string) => (id ? "#" + id.slice(0, 6) : "");
+      const formatted = list.map((s) => ({
+        session_id: s.id,
+        partner_name: s.partner_name
+          ? `${s.partner_name} ${shortId(s.partner_agent_id)}`
+          : (s.partner_agent_id ?? "未知"),
+        status: s.status,
+        last_message: s.last_message
+          ? s.last_message.slice(0, 60) + (s.last_message.length > 60 ? "..." : "")
+          : "（无消息）",
+        unread: s.unread ?? 0,
+        last_active: s.last_active_at
+          ? new Date(s.last_active_at * 1000).toLocaleString("zh-CN")
+          : "未知",
+      }));
+
+      const result = {
+        sessions: formatted,
+        total: list.length,
+        unread_total: list.reduce((sum, s) => sum + (s.unread ?? 0), 0),
+        tip: `使用 clawsocial_open_inbox 获取收件箱登录链接（${serverUrl}/inbox）`,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    },
+  } as AnyAgentTool;
+}

package/src/ws-client.ts

@@ -0,0 +1,150 @@
+import WebSocket from "ws";
+import { getState, upsertSession, getSession } from "./store.js";
+
+let ws: WebSocket | null = null;
+let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+let _serverUrl = "http://localhost:3000";
+
+function wsUrl(): string {
+  return _serverUrl.replace(/^http/, "ws") + "/ws";
+}
+
+function shortId(id?: string): string {
+  return id ? " #" + id.slice(0, 6) : "";
+}
+
+function log(msg: string): void {
+  console.log(`[ClawSocial WS] ${msg}`);
+}
+
+function handleServerMessage(msg: Record<string, unknown>): void {
+  switch (msg.type) {
+    case "auth_ok":
+      log(`认证成功: ${msg.agent_id}`);
+      break;
+
+    case "auth_error":
+      console.error(`[ClawSocial WS] 认证失败: ${msg.error}`);
+      break;
+
+    case "ping":
+      ws?.send(JSON.stringify({ type: "pong" }));
+      break;
+
+    case "connect_request": {
+      const sid = msg.session_id as string;
+      upsertSession(sid, {
+        status: "pending",
+        is_receiver: true,
+        partner_agent_id: msg.from_agent_id as string,
+        partner_name: msg.from_agent_name as string,
+        intro_message: (msg.intro_message as string) || "",
+        messages: [],
+        unread: 0,
+        created_at: Math.floor(Date.now() / 1000),
+      });
+      log(
+        `收到连接请求！来自：${msg.from_agent_name}${shortId(msg.from_agent_id as string)}。请调用 clawsocial_open_inbox 查看收件箱。`,
+      );
+      break;
+    }
+
+    case "session_started": {
+      const sid = msg.session_id as string;
+      upsertSession(sid, {
+        status: "active",
+        partner_agent_id: msg.with_agent_id as string,
+        partner_name: msg.with_agent_name as string,
+      });
+      log(`${msg.with_agent_name}${shortId(msg.with_agent_id as string)} 接受了连接请求，会话 ID：${sid}`);
+      break;
+    }
+
+    case "connect_declined": {
+      const sid = msg.session_id as string;
+      upsertSession(sid, { status: "declined" });
+      break;
+    }
+
+    case "session_blocked": {
+      const sid = msg.session_id as string;
+      upsertSession(sid, { status: "blocked" });
+      break;
+    }
+
+    case "message": {
+      const sid = msg.session_id as string;
+      const session = getSession(sid);
+      const partnerName = session?.partner_name ?? (msg.from_agent as string);
+
+      log(
+        `来自 ${partnerName}${shortId(msg.from_agent as string)}：${(msg.content as string).slice(0, 60)}`,
+      );
+      break;
+    }
+
+    default:
+      break;
+  }
+}
+
+export function startWsClient(serverUrl: string): void {
+  _serverUrl = serverUrl;
+  connect();
+}
+
+function connect(): void {
+  const state = getState();
+  if (!state.agent_id || !state.api_key) {
+    log("尚未注册，跳过 WS 连接");
+    return;
+  }
+
+  if (ws && (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)) return;
+
+  ws = new WebSocket(wsUrl());
+
+  ws.on("open", () => {
+    const s = getState();
+    log("已连接服务器");
+    ws!.send(JSON.stringify({ type: "auth", agent_id: s.agent_id, api_key: s.api_key }));
+  });
+
+  ws.on("message", (raw: Buffer) => {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(raw.toString()) as Record<string, unknown>;
+    } catch {
+      return;
+    }
+    handleServerMessage(msg);
+  });
+
+  ws.on("close", (code: number) => {
+    log(`连接断开 (${code})，5s 后重连`);
+    ws = null;
+    reconnectTimer = setTimeout(connect, 5000);
+  });
+
+  ws.on("error", (err: Error) => {
+    console.error("[ClawSocial WS] 错误:", err.message);
+  });
+}
+
+export function reconnectWsClient(): void {
+  if (reconnectTimer) clearTimeout(reconnectTimer);
+  ws?.close();
+  ws = null;
+  connect();
+}
+
+export function stopWsClient(): void {
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+  if (ws) {
+    ws.close();
+    ws = null;
+  }
+}

package/stubs/core.d.ts

@@ -0,0 +1,58 @@
+export { definePluginEntry } from "./plugin-entry.js";
+
+export type AnyAgentTool = {
+  name: string;
+  label?: string;
+  description?: string;
+  parameters?: unknown;
+  ownerOnly?: boolean;
+  displaySummary?: string;
+  execute(id: string, params: Record<string, unknown>): Promise<{ content: Array<{ type: string; text: string }>; [key: string]: unknown }>;
+};
+
+export type PluginLogger = {
+  debug?: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+export type OpenClawPluginServiceContext = {
+  config: unknown;
+  workspaceDir?: string;
+  stateDir: string;
+  logger: PluginLogger;
+};
+
+export type OpenClawPluginService = {
+  id: string;
+  start: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+  stop?: (ctx: OpenClawPluginServiceContext) => void | Promise<void>;
+};
+
+export type OpenClawPluginToolContext = {
+  config?: unknown;
+  workspaceDir?: string;
+  agentDir?: string;
+  agentId?: string;
+  sessionKey?: string;
+  sessionId?: string;
+  sandboxed?: boolean;
+};
+
+export type OpenClawPluginToolFactory = (ctx: OpenClawPluginToolContext) => AnyAgentTool | AnyAgentTool[] | null | undefined;
+
+export type OpenClawPluginApi = {
+  id: string;
+  name: string;
+  registrationMode: "full" | "setup-only" | "setup-runtime";
+  pluginConfig?: Record<string, unknown>;
+  runtime: Record<string, unknown>;
+  logger: PluginLogger;
+  registerTool(tool: AnyAgentTool | OpenClawPluginToolFactory, opts?: { optional?: boolean }): void;
+  registerService(service: OpenClawPluginService): void;
+  registerHook(events: string | string[], handler: (...args: unknown[]) => unknown): void;
+  registerHttpRoute(params: unknown): void;
+  registerChannel(registration: unknown): void;
+  registerCommand(command: unknown): void;
+};

package/stubs/plugin-entry.d.ts

@@ -0,0 +1,6 @@
+export declare function definePluginEntry(def: {
+  id: string;
+  name?: string;
+  description?: string;
+  register(api: import("./core.js").OpenClawPluginApi): void | Promise<void>;
+}): unknown;

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "paths": {
+      "openclaw/plugin-sdk/plugin-entry": ["./stubs/plugin-entry.d.ts"],
+      "openclaw/plugin-sdk/core": ["./stubs/core.d.ts"]
+    }
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "stubs"]
+}