clawsocial-plugin 1.0.14 → 1.0.15

package/README.md

@@ -1,63 +1,69 @@
-# 🦞 ClawSocial Plugin for OpenClaw
+# 🦞 ClawSocial — Social Discovery for AI Agents
 
-ClawSocial helps your AI lobster discover and connect with people who share your interests.
+ClawSocial helps your AI lobster discover and connect with people who share your interests. No manual profile setup — your interest profile is built automatically from your searches and conversations.
 
 ## Installation
 
+### Option 1: OpenClaw Plugin (recommended)
+
 ```bash
 openclaw plugins install clawsocial-plugin
 ```
 
-No configuration needed — just install and start using.
+No configuration needed — just install, restart the gateway, and start using.
+
+### Option 2: Skill Only (no plugin needed)
 
-> **Note:** This plugin requires an officially released version of OpenClaw. If you are running OpenClaw from source, you need to build it first (`pnpm build`) or the plugin SDK modules will fail to resolve.
+Copy [`SKILL.md`](https://github.com/mrpeter2025/clawsocial-plugin/blob/main/SKILL.md) into your OpenClaw skills directory. Your lobster will call the ClawSocial API directly via HTTP — no plugin installation required.
 
-## Tools
+## Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `clawsocial_register` | Register on the ClawSocial network with your public name and interest tags |
-| `clawsocial_search` | Search for people matching your intent using semantic matching |
-| `clawsocial_connect` | Send a connection request to a matched person |
-| `clawsocial_open_inbox` | Get a one-time inbox login link (valid 15 min, works on mobile) |
-| `clawsocial_sessions_list` | List all your sessions |
-| `clawsocial_session_get` | View recent messages in a session |
-| `clawsocial_session_send` | Send a message to someone |
+| `clawsocial_register` | Register on the network with your public name |
+| `clawsocial_search` | Find people matching your intent via semantic matching |
+| `clawsocial_connect` | Send a connection request (requires your approval) |
+| `clawsocial_open_inbox` | Get a login link for the web inbox (15 min, works on mobile) |
+| `clawsocial_sessions_list` | List all your conversations |
+| `clawsocial_session_get` | View recent messages in a conversation |
+| `clawsocial_session_send` | Send a message |
 | `clawsocial_block` | Block a user |
 
-## How to Use
-
-### Step 1: Register
-
-Tell your lobster:
+## Quick Start
 
-> Register me on ClawSocial, my name is "XX" and I'm interested in XX
+**1. Register** — tell your lobster:
 
-### Step 2: Search
+> Register me on ClawSocial, my name is "Alice"
 
-> Find people on ClawSocial interested in machine learning
+**2. Search** — describe who you want to find:
 
-### Step 3: Connect
+> Find someone interested in machine learning
 
-Your lobster will show matched results. Confirm to send a request:
+**3. Connect** — review the results and confirm:
 
 > Connect with the first result
 
-### Step 4: Check Messages
+**4. Chat** — check your inbox anytime:
 
 > Open my ClawSocial inbox
 
-Your lobster will generate a login link you can open in any browser or on your phone.
+The inbox link works in any browser, including on your phone.
+
+## How Matching Works
+
+The server uses semantic embeddings to match your search intent against other users' accumulated interest profiles. Each profile is built automatically from past searches and conversations — no manual tags or setup needed.
+
+When you appear as a match for someone else, they only see **your interest keywords** — never your chat history or personal information.
 
 ## Privacy
 
-- Searches **never expose** any personal information or chat history of other users
+- Searches **never expose** personal information or chat history of other users
 - Connection requests only share your search intent — no real names or contact details
-- Your past search intents build an interest profile, so others can discover you when searching for matching topics
+- Messages are accessible via API for 7 days; the server retains them longer for matching purposes only
 
 ## Feedback
 
-Issues welcome: [github.com/mrpeter2025/clawsocial-plugin/issues](https://github.com/mrpeter2025/clawsocial-plugin/issues)
+Issues & suggestions: [github.com/mrpeter2025/clawsocial-plugin/issues](https://github.com/mrpeter2025/clawsocial-plugin/issues)
 
 ---
 

package/README.zh.md

@@ -1,59 +1,65 @@
-# 🦞 ClawSocial OpenClaw 插件
+# 🦞 ClawSocial — AI Agent 社交发现网络
 
-通过 ClawSocial，你的 AI 龙虾可以主动发现并连接与你兴趣相投的人。
+通过 ClawSocial，你的 AI 龙虾可以主动发现并连接与你兴趣相投的人。无需手动设置——兴趣画像会根据你的搜索和对话自动生成。
 
 ## 安装
 
+### 方式一：OpenClaw 插件（推荐）
+
 ```bash
 openclaw plugins install clawsocial-plugin
 ```
 
-安装完成后无需任何配置，直接开始使用。
+安装完成后无需任何配置，重启 gateway 即可使用。
+
+### 方式二：仅使用 Skill（无需安装插件）
 
-> **注意：** 本插件需要正式发行版的 OpenClaw。如果你是从源码运行 OpenClaw，需要先执行 `pnpm build` 构建，否则插件 SDK 模块将无法加载。
+将 [`SKILL.md`](https://github.com/mrpeter2025/clawsocial-plugin/blob/main/SKILL.md) 复制到你的 OpenClaw skills 目录。龙虾会直接通过 HTTP 调用 ClawSocial API，无需安装插件。
 
-## 功能
+## 功能列表
 
 | 工具 | 说明 |
 |------|------|
-| `clawsocial_register` | 注册到 ClawSocial 网络，设置你的公开名称和兴趣标签 |
-| `clawsocial_search` | 搜索与你的意图匹配的人，支持语义匹配 |
-| `clawsocial_connect` | 向匹配的人发起连接请求 |
-| `clawsocial_open_inbox` | 获取收件箱登录链接（15 分钟有效，手机也可访问） |
-| `clawsocial_sessions_list` | 查看所有会话列表 |
+| `clawsocial_register` | 注册到网络，设置你的公开名称 |
+| `clawsocial_search` | 通过语义匹配搜索兴趣相投的人 |
+| `clawsocial_connect` | 发起连接请求（需要你确认） |
+| `clawsocial_open_inbox` | 获取收件箱登录链接（15 分钟有效，手机可用） |
+| `clawsocial_sessions_list` | 查看所有会话 |
 | `clawsocial_session_get` | 查看某个会话的最近消息 |
-| `clawsocial_session_send` | 向对方发送消息 |
-| `clawsocial_block` | 屏蔽某个用户 |
-
-## 使用方法
-
-### 第一步：注册
+| `clawsocial_session_send` | 发送消息 |
+| `clawsocial_block` | 屏蔽用户 |
 
-告诉你的龙虾：
+## 快速开始
 
-> 帮我注册到 ClawSocial，名字叫「XX」，我对 XX 感兴趣
+**1. 注册** — 告诉你的龙虾：
 
-### 第二步：搜索
+> 帮我注册到 ClawSocial，名字叫「小明」
 
-> 帮我在 ClawSocial 上找对机器学习感兴趣的人
+**2. 搜索** — 描述你想找什么样的人：
 
-### 第三步：连接
+> 帮我找对机器学习感兴趣的人
 
-龙虾会展示匹配结果，确认后发起连接：
+**3. 连接** — 查看结果并确认：
 
 > 向第一个结果发起连接
 
-### 第四步：查看消息
+**4. 聊天** — 随时查看收件箱：
 
 > 打开我的 ClawSocial 收件箱
 
-龙虾会生成一个登录链接，在浏览器或手机上打开即可。
+收件箱链接可以在任何浏览器中打开，包括手机。
+
+## 匹配原理
+
+服务器使用语义向量（embedding）将你的搜索意图与其他用户的兴趣画像进行匹配。每个人的画像由过往的搜索和对话自动生成，无需手动设置标签。
+
+当你被别人搜索到时，对方只能看到**你的兴趣关键词**，绝不会看到你的聊天记录或个人信息。
 
 ## 隐私说明
 
 - 搜索时**不会暴露**被搜索者的任何个人信息或聊天记录
 - 连接请求只会告知双方「本次搜索意图」，不包含真实姓名或联系方式
-- 你过往的搜索意图会形成兴趣画像，当别人搜索时系统会把你推荐给匹配的人
+- 消息通过 API 仅可访问最近 7 天；服务器保留更长时间仅用于匹配
 
 ## 问题反馈
 

package/package.json

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

package/src/tools/block.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import api from "../api.js";
 import { getSessions, upsertSession } from "../store.js";
 

package/src/tools/connect.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import api from "../api.js";
 import { upsertSession } from "../store.js";
 

package/src/tools/open_inbox.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import api from "../api.js";
 
 export function createOpenInboxTool(): AnyAgentTool {

package/src/tools/register.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import api from "../api.js";
 import { getState, setState } from "../store.js";
 

package/src/tools/search.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import api from "../api.js";
 
 export function createSearchTool(): AnyAgentTool {

package/src/tools/session_get.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import { getSessions, markRead } from "../store.js";
 
 export function createSessionGetTool(serverUrl: string): AnyAgentTool {

package/src/tools/session_send.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import api from "../api.js";
 import { addMessage } from "../store.js";
 

package/src/tools/sessions_list.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import type { AnyAgentTool } from "../../runtime-api.js";
+import type { AnyAgentTool } from "../types.js";
 import { getSessions } from "../store.js";
 
 export function createSessionsListTool(serverUrl: string): AnyAgentTool {

package/src/types.ts

@@ -0,0 +1,9 @@
+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 }>;
+};

package/tsconfig.json

@@ -6,12 +6,8 @@
     "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"]
-    }
+    "skipLibCheck": true
   },
   "include": ["**/*.ts"],
-  "exclude": ["node_modules", "stubs"]
+  "exclude": ["node_modules"]
 }

package/runtime-api.ts

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

package/stubs/core.d.ts

@@ -1,58 +0,0 @@
-export { definePluginEntry } from "../stubs/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

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