@volisphere/commercial 0.3.0 → 0.3.1

package/dist/client.d.ts

@@ -228,8 +228,76 @@ export declare class VolisphereClient {
     pauseCampaign(campaignId: string): Promise<void>;
     resumeCampaign(campaignId: string): Promise<void>;
     registerAgent(params: RegisterAgentParams): Promise<RegisterAgentResponse>;
+    claimAgent(claimToken: string): Promise<AgentProfile>;
     heartbeat(agentId: string): Promise<void>;
     setMonetization(agentId: string, enabled: boolean): Promise<AgentProfile>;
+    discoverAgents(params: {
+        query: string;
+        categories?: string[];
+        only_online?: boolean;
+        top_k?: number;
+    }): Promise<{
+        results: Array<{
+            rank: number;
+            agent_slug: string;
+            agent_name: string;
+            skill_name: string;
+            description: string;
+            tags: string[];
+            is_online: boolean;
+            call_count: number;
+            invoke_url: string;
+        }>;
+        total: number;
+    }>;
+    getAgentProfile(slug: string): Promise<{
+        id: string;
+        slug: string;
+        display_name: string;
+        description: string;
+        is_online: boolean;
+        monetization_enabled: boolean;
+        skills: Array<{
+            id: string;
+            skill_name: string;
+            description: string;
+            ads_enabled: boolean;
+            ad_policy: string;
+        }>;
+        capabilities: Array<{
+            id: string;
+            skill_name: string;
+            description: string;
+            category: string;
+            tags: string[];
+            is_online: boolean;
+        }>;
+    }>;
+    registerSkillPublic(claimToken: string, skills: Array<{
+        skill_name: string;
+        description?: string;
+        ads_enabled?: boolean;
+        ad_policy?: string;
+        min_bid_micros?: number;
+        allowed_categories?: string[];
+    }>): Promise<{
+        skills: Array<{
+            id: string;
+            skill_name: string;
+            description: string;
+            ads_enabled: boolean;
+            ad_policy: string;
+        }>;
+    }>;
+    listSkills(): Promise<SkillConfig[]>;
+    updateSkill(skillId: string, patch: {
+        skill_version?: string;
+        description?: string;
+        ads_enabled?: boolean;
+        ad_policy?: string;
+        min_bid_micros?: number;
+        allowed_categories?: string[];
+    }): Promise<SkillConfig>;
     invokeAgent(params: InvokeAgentParams): Promise<InvokeAgentResponse>;
     getSSPStats(days?: number): Promise<StatsResponse>;
     getDSPStats(days?: number): Promise<StatsResponse>;

package/dist/client.js

@@ -117,6 +117,18 @@ export class VolisphereClient {
         }
         return res.json();
     }
+    async claimAgent(claimToken) {
+        const res = await fetch(`${this.baseURL}/api/ssp/v1/agents/claim`, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify({ claim_token: claimToken }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`claimAgent failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
     async heartbeat(agentId) {
         const res = await fetch(`${this.baseURL}/api/ssp/v1/agents/${agentId}/heartbeat`, { method: "POST", headers: this.headers });
         if (!res.ok) {
@@ -136,6 +148,64 @@ export class VolisphereClient {
         }
         return res.json();
     }
+    // ── Discovery (Public) ─────────────────────────────────────────────────
+    async discoverAgents(params) {
+        const res = await fetch(`${this.baseURL}/api/public/v1/discovery/search`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(params),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`discoverAgents failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async getAgentProfile(slug) {
+        const res = await fetch(`${this.baseURL}/api/agents/${encodeURIComponent(slug)}`, {
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`getAgentProfile failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    // ── Skill Management ───────────────────────────────────────────────────
+    async registerSkillPublic(claimToken, skills) {
+        const res = await fetch(`${this.baseURL}/api/public/v1/skills/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ claim_token: claimToken, skills }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`registerSkillPublic failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async listSkills() {
+        const res = await fetch(`${this.baseURL}/api/ssp/v1/skills`, {
+            headers: this.headers,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`listSkills failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    async updateSkill(skillId, patch) {
+        const res = await fetch(`${this.baseURL}/api/ssp/v1/skills/${skillId}`, {
+            method: "PATCH",
+            headers: this.headers,
+            body: JSON.stringify(patch),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`updateSkill failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
     // ── Gateway (Invoke) ────────────────────────────────────────────────────
     async invokeAgent(params) {
         const res = await fetch(`${this.baseURL}/api/gateway/v1/invoke`, {

package/dist/index.js

@@ -57,55 +57,6 @@ function resolveConfig(api) {
 }
 // ─── Tool Definitions ───────────────────────────────────────────────────────
 function registerMonetizationTools(api, client) {
-    // get_recommendations
-    api.registerTool({
-        name: "volisphere_get_recommendations",
-        description: "Get relevant ad recommendations from the Volisphere network based on user intent and context. " +
-            "Do not submit any private conversation content. " +
-            "Call this when the user says: '推荐广告', '拉取广告', 'voli 推荐', 'get ads', 'show me ads'.",
-        parameters: {
-            type: "object",
-            properties: {
-                agent_id: { type: "string", description: "The agent identifier" },
-                skill_name: {
-                    type: "string",
-                    description: "The skill/tool name calling this",
-                },
-                categories: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Ad categories to filter",
-                },
-                scenes: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Usage scenes",
-                },
-                region: { type: "string", description: "Geographic region" },
-                intent_text: {
-                    type: "string",
-                    description: "User intent text for semantic matching",
-                },
-                top_k: {
-                    type: "number",
-                    description: "Number of recommendations (1-20, default 3)",
-                },
-            },
-            required: ["agent_id", "skill_name"],
-        },
-        execute: async (params) => {
-            const result = await client.getRecommendations({
-                agent_id: params.agent_id,
-                skill_name: params.skill_name,
-                categories: params.categories,
-                scenes: params.scenes,
-                region: params.region,
-                intent_text: params.intent_text,
-                top_k: params.top_k ?? 3,
-            });
-            return JSON.stringify(result, null, 2);
-        },
-    });
     // report_action
     api.registerTool({
         name: "volisphere_report_action",
@@ -504,6 +455,230 @@ function registerDashboardTools(api, client) {
         },
     });
 }
+// ─── Discovery Tools ─────────────────────────────────────────────────────────
+function registerDiscoveryTools(api, client) {
+    // volisphere_discover — search for agents on the network
+    api.registerTool({
+        name: "volisphere_discover",
+        description: "Search for agents and their skills on the Volisphere network. " +
+            "Returns a list of agents matching your query, with their capabilities and online status. " +
+            "Call this when the user says: '找 agent', '搜索 agent', '有哪些 agent', '看看网络里有谁', " +
+            "'discover agents', 'find agents', 'search agents', 'who is on the network'.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query describing what kind of agent or skill you're looking for (e.g. 'translation', 'code review', '翻译')",
+                },
+                categories: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Filter by categories (e.g. 'software-development', 'marketing')",
+                },
+                only_online: {
+                    type: "boolean",
+                    description: "Only show currently online agents (default false)",
+                },
+                top_k: {
+                    type: "number",
+                    description: "Number of results to return (default 10)",
+                },
+            },
+            required: ["query"],
+        },
+        execute: async (params) => {
+            const result = await client.discoverAgents({
+                query: params.query,
+                categories: params.categories,
+                only_online: params.only_online,
+                top_k: params.top_k ?? 10,
+            });
+            if (result.results.length === 0) {
+                return JSON.stringify({
+                    total: 0,
+                    results: [],
+                    message: "没有找到匹配的 Agent。试试更宽泛的关键词？",
+                });
+            }
+            const agents = result.results.map((r) => ({
+                slug: r.agent_slug,
+                name: r.agent_name,
+                skill: r.skill_name,
+                description: r.description,
+                tags: r.tags,
+                online: r.is_online,
+                calls: r.call_count,
+            }));
+            return JSON.stringify({
+                total: result.total,
+                results: agents,
+                tip: "用 volisphere_invoke 调用感兴趣的 Agent，例如：volisphere_invoke(target_agent='agent-slug', message='你好')",
+            }, null, 2);
+        },
+    });
+    // volisphere_agent_profile — view a specific agent's details and capabilities
+    api.registerTool({
+        name: "volisphere_agent_profile",
+        description: "View detailed profile and capabilities of a specific agent on the Volisphere network. " +
+            "Shows what skills the agent has, whether it's online, and how to invoke it. " +
+            "Call this when the user says: '看看这个 agent', '查看 agent 详情', " +
+            "'agent profile', 'show agent details', 'what can this agent do'.",
+        parameters: {
+            type: "object",
+            properties: {
+                slug: {
+                    type: "string",
+                    description: "The agent slug to look up (e.g. 'codepilot-pro')",
+                },
+            },
+            required: ["slug"],
+        },
+        execute: async (params) => {
+            const profile = await client.getAgentProfile(params.slug);
+            return JSON.stringify({
+                slug: profile.slug,
+                name: profile.display_name,
+                description: profile.description,
+                online: profile.is_online,
+                skills: (profile.skills ?? []).map((s) => ({
+                    name: s.skill_name,
+                    description: s.description,
+                })),
+                capabilities: (profile.capabilities ?? []).map((c) => ({
+                    skill: c.skill_name,
+                    description: c.description,
+                    category: c.category,
+                    tags: c.tags,
+                    online: c.is_online,
+                })),
+                tip: profile.is_online
+                    ? `这个 Agent 在线！用 volisphere_invoke(target_agent='${profile.slug}', message='...') 调用它`
+                    : "这个 Agent 当前离线",
+            }, null, 2);
+        },
+    });
+}
+// ─── Skill Management Tools ──────────────────────────────────────────────────
+function registerSkillTools(api, client) {
+    // volisphere_register_skill — register skills using claim_token (public endpoint)
+    api.registerTool({
+        name: "volisphere_register_skill",
+        description: "Register one or more skills/capabilities for your agent on the Volisphere network. " +
+            "Other agents will discover and invoke your skills through the network. " +
+            "Call this when the user says: '注册技能', '添加能力', '添加技能', " +
+            "'register skill', 'add skill', 'add capability'.",
+        parameters: {
+            type: "object",
+            properties: {
+                skills: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            skill_name: { type: "string", description: "Skill name (e.g. 'code-review', 'translate')" },
+                            description: { type: "string", description: "What this skill does" },
+                            ads_enabled: { type: "boolean", description: "Whether to show ads when this skill is invoked (default true)" },
+                            ad_policy: { type: "string", description: "Ad policy: 'allow_all', 'category_filter', or 'disabled'" },
+                            min_bid_micros: { type: "number", description: "Minimum bid in micros (default 0)" },
+                            allowed_categories: { type: "array", items: { type: "string" }, description: "Allowed ad categories" },
+                        },
+                        required: ["skill_name"],
+                    },
+                    description: "List of skills to register",
+                },
+            },
+            required: ["skills"],
+        },
+        execute: async (params) => {
+            const saved = loadSavedCredentials();
+            if (!saved?.claim_token) {
+                return JSON.stringify({
+                    error: "No claim_token found. Please enable commercial features first (say '开启商业化' or 'go commercial').",
+                });
+            }
+            const skills = params.skills;
+            const result = await client.registerSkillPublic(saved.claim_token, skills);
+            return JSON.stringify({
+                ...result,
+                message: `成功注册 ${result.skills.length} 个技能！其他 Agent 现在可以发现并调用这些技能了。`,
+            }, null, 2);
+        },
+    });
+    // volisphere_list_skills — list all registered skills
+    api.registerTool({
+        name: "volisphere_list_skills",
+        description: "List all skills registered for your agent on the Volisphere network. " +
+            "Call this when the user says: '我的技能', '看看技能', '技能列表', " +
+            "'list skills', 'my skills', 'show skills'.",
+        parameters: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+        execute: async () => {
+            const skills = await client.listSkills();
+            if (skills.length === 0) {
+                return JSON.stringify({
+                    skills: [],
+                    message: "你还没有注册任何技能。用「注册技能」添加你的第一个技能吧！",
+                });
+            }
+            return JSON.stringify({
+                total: skills.length,
+                skills: skills.map((s) => ({
+                    id: s.id,
+                    skill_name: s.skill_name,
+                    description: s.description,
+                    ads_enabled: s.ads_enabled,
+                    ad_policy: s.ad_policy,
+                    min_bid_micros: s.min_bid_micros,
+                })),
+            }, null, 2);
+        },
+    });
+    // volisphere_update_skill — update a skill's configuration
+    api.registerTool({
+        name: "volisphere_update_skill",
+        description: "Update the configuration of a registered skill (ads policy, description, etc). " +
+            "Call this when the user says: '更新技能', '修改技能', '改技能配置', " +
+            "'update skill', 'modify skill', 'change skill'.",
+        parameters: {
+            type: "object",
+            properties: {
+                skill_id: { type: "string", description: "The skill UUID to update" },
+                description: { type: "string", description: "New description" },
+                ads_enabled: { type: "boolean", description: "Enable/disable ads" },
+                ad_policy: { type: "string", description: "New ad policy" },
+                min_bid_micros: { type: "number", description: "New minimum bid" },
+                allowed_categories: { type: "array", items: { type: "string" }, description: "New allowed categories" },
+                skill_version: { type: "string", description: "New version string" },
+            },
+            required: ["skill_id"],
+        },
+        execute: async (params) => {
+            const skillId = params.skill_id;
+            const patch = {};
+            if (params.description !== undefined)
+                patch.description = params.description;
+            if (params.ads_enabled !== undefined)
+                patch.ads_enabled = params.ads_enabled;
+            if (params.ad_policy !== undefined)
+                patch.ad_policy = params.ad_policy;
+            if (params.min_bid_micros !== undefined)
+                patch.min_bid_micros = params.min_bid_micros;
+            if (params.allowed_categories !== undefined)
+                patch.allowed_categories = params.allowed_categories;
+            if (params.skill_version !== undefined)
+                patch.skill_version = params.skill_version;
+            const result = await client.updateSkill(skillId, patch);
+            return JSON.stringify({
+                ...result,
+                message: `技能 "${result.skill_name}" 已更新。`,
+            }, null, 2);
+        },
+    });
+}
 // ─── Lifecycle Tools (Enable / Disable) ─────────────────────────────────────
 function registerLifecycleTools(api, client, apiURL) {
     // volisphere_enable — register agent + enable monetization + heartbeat
@@ -561,24 +736,33 @@ function registerLifecycleTools(api, client, apiURL) {
                     api_url: apiURL,
                     agent_id: agentId,
                     slug: reg.agent.slug,
+                    claim_token: reg.claim_token,
                 });
                 api.logger.info(`[Volisphere] API key auto-provisioned and saved to ${CREDENTIALS_FILE}`);
             }
-            // Step 3: Enable monetization (now using the provisioned key)
+            // Step 3: Claim agent — triggers welcome call (sim agent invokes within 2-4 min)
+            try {
+                await client.claimAgent(reg.claim_token);
+                api.logger.info("[Volisphere] Agent claimed — welcome call will arrive in 2-4 minutes");
+            }
+            catch (e) {
+                api.logger.warn(`[Volisphere] Claim failed (non-critical): ${e instanceof Error ? e.message : String(e)}`);
+            }
+            // Step 4: Enable monetization (now using the provisioned key)
             try {
                 await client.setMonetization(agentId, true);
             }
             catch {
                 // May fail if no JWT — agent was registered publicly
             }
-            // Step 4: Heartbeat (go online)
+            // Step 5: Heartbeat (go online)
             try {
                 await client.heartbeat(agentId);
             }
             catch {
                 // Non-critical
             }
-            // Step 5: Auto-connect WebSocket so agent can receive invocations
+            // Step 6: Auto-connect WebSocket so agent can receive invocations
             if (reg.api_key) {
                 const wsClient = new GatewayWSClient(apiURL, reg.api_key, {
                     onRequest: async (requestId, from, message) => {
@@ -608,9 +792,19 @@ function registerLifecycleTools(api, client, apiURL) {
                 slug: reg.agent.slug,
                 display_name: reg.agent.display_name,
                 claim_token: reg.claim_token,
-                message: "Agent registered and commercial features enabled. " +
-                    "API key auto-provisioned — no manual configuration needed. " +
-                    "Your agent is now online and can receive ad recommendations and invocations.",
+                guide: {
+                    what_is_this: "你的 Agent 已加入 Volisphere 广告网络！这意味着：" +
+                        "其他 Agent 可以通过网络调用你的技能，调用时会向对方展示相关广告，" +
+                        "广告的展示、点击和转化会为你产生收益（VBucks）。",
+                    whats_next: [
+                        "用「注册技能」或 volisphere_register_skill 注册你擅长的技能，让更多 Agent 找到你",
+                        "用「看看收益」或 volisphere_my_earnings 随时查看你的收入",
+                    ],
+                    how_to_stop: "说「关闭商业化」或 volisphere_disable 即可随时退出网络",
+                },
+                message: "Agent 注册成功，商业化已开启！" +
+                    "当其他 Agent 调用你的技能时，会自动向对方展示广告，广告收入归你。" +
+                    "接下来建议注册你的技能（说「注册技能」），让更多 Agent 发现并调用你。",
             }, null, 2);
         },
     });
@@ -731,11 +925,15 @@ function registerHooks(api, client) {
             appendSystemContext: [
                 "## Volisphere Ad Network",
                 "",
-                'You have the Volisphere commercial plugin installed. When the user mentions "voli" or "volisphere", they are using this plugin.',
+                "You have the Volisphere commercial plugin installed. It lets your Agent join the Volisphere ad network — other Agents can discover and invoke your skills, and ads are shown to callers during invocations. Ad impressions, clicks, and conversions generate VBucks revenue for you.",
+                'When the user mentions "voli" or "volisphere", they are using this plugin.',
                 "",
                 "### Quick Action Map (natural language → tool)",
                 '- "voli 开启" / "开启商业化" / "monetize my agent" / "go commercial" → volisphere_enable',
                 '- "voli 关闭" / "关闭商业化" / "stop monetization" / "go offline" → volisphere_disable',
+                '- "注册技能" / "添加能力" / "register skill" / "add skill" → volisphere_register_skill',
+                '- "我的技能" / "看看技能" / "list skills" / "my skills" → volisphere_list_skills',
+                '- "更新技能" / "修改技能" / "update skill" → volisphere_update_skill',
                 '- "voli 投广告" / "创建广告活动" / "create campaign" → volisphere_create_campaign',
                 '- "voli 创建广告" / "做个广告素材" / "create ad" → volisphere_create_ad',
                 '- "voli 暂停广告" / "暂停投放" / "pause campaign" → volisphere_pause_campaign',
@@ -743,12 +941,14 @@ function registerHooks(api, client) {
                 '- "voli 广告效果" / "看看活动表现" / "campaign stats" → volisphere_campaign_performance',
                 '- "voli 看看收益" / "赚了多少" / "被调用了多少次" / "my earnings" → volisphere_my_earnings',
                 '- "voli 看看花费" / "广告数据" / "投了多少" / "my spending" → volisphere_my_spending',
+                '- "找 agent" / "搜索 agent" / "有哪些 agent" / "discover agents" → volisphere_discover',
+                '- "查看 agent" / "agent 详情" / "agent profile" → volisphere_agent_profile',
                 '- "voli 调用 xxx" / "帮我问问 xxx" / "call agent xxx" → volisphere_invoke (target_agent=xxx)',
-                '- "voli 推荐广告" / "拉取广告" / "get ads" → volisphere_get_recommendations',
                 "",
                 "### Smart Defaults (when user omits parameters)",
                 "- create_campaign: daily_budget=10 VB (10,000,000 micros), total_budget=100 VB, default_bid=0.1 VB, billing=cpi, start_at=now",
                 "- my_earnings / my_spending: days=7",
+                "- discover: top_k=10, only_online=false",
                 "- invoke: extract target agent slug and message from user's natural language",
                 "",
                 "Always clearly label sponsored content. Never submit private user data to ad tools.",
@@ -770,6 +970,8 @@ export default {
         registerCampaignTools(api, client);
         registerGatewayTools(api, client);
         registerDashboardTools(api, client);
+        registerDiscoveryTools(api, client);
+        registerSkillTools(api, client);
         registerLifecycleTools(api, client, apiURL);
         registerCommands(api, client);
         registerHooks(api, client);
@@ -797,6 +999,6 @@ export default {
             });
             wsClient.connect();
         }
-        api.logger.info("Registered 13 tools + 1 command + 1 hook — ready to monetize");
+        api.logger.info("Registered 17 tools + 1 command + 1 hook — ready to monetize");
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volisphere/commercial",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Volisphere commercial plugin for OpenClaw — monetize your agent skills with the agent-native ad network",
   "type": "module",
   "main": "dist/index.js",