@seasonkoh/webaz 0.1.7 → 0.1.8

package/dist/layer1-agent/L1-1-mcp-server/server.js

@@ -23,6 +23,10 @@ import { initSkillSchema, publishSkill, listSkills, getMySkills, subscribeSkill,
 import { initReputationSchema, recordOrderReputation, recordDisputeReputation, getReputation, getSearchBoost, getStakeDiscount, } from '../../layer4-economics/L4-3-reputation/reputation-engine.js';
 import { generateManifest, getManifestSummary, MANIFEST_URI, } from '../../layer0-foundation/L0-5-manifest/manifest.js';
 import { requireAuth } from './auth.js';
+import { createHash } from 'node:crypto';
+const SERVER_VERSION = '0.1.8';
+const TELEMETRY_URL = process.env.WEBAZ_TELEMETRY_URL ?? 'https://webaz.xyz/api/mcp-telemetry';
+const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'on').toLowerCase() !== 'off';
 // ─── 初始化 ──────────────────────────────────────────────────
 const db = initDatabase();
 initSystemUser(db);
@@ -30,6 +34,52 @@ initDisputeSchema(db);
 initNotificationSchema(db);
 initSkillSchema(db);
 initReputationSchema(db);
+// 结构化商品字段迁移（幂等）
+const MCP_PRODUCT_COLS = [
+    'ALTER TABLE products ADD COLUMN specs TEXT',
+    'ALTER TABLE products ADD COLUMN brand TEXT',
+    'ALTER TABLE products ADD COLUMN model TEXT',
+    'ALTER TABLE products ADD COLUMN source_url TEXT',
+    'ALTER TABLE products ADD COLUMN source_price REAL',
+    'ALTER TABLE products ADD COLUMN ship_regions TEXT DEFAULT "全国"',
+    'ALTER TABLE products ADD COLUMN handling_hours INTEGER DEFAULT 24',
+    'ALTER TABLE products ADD COLUMN estimated_days TEXT',
+    'ALTER TABLE products ADD COLUMN fragile INTEGER DEFAULT 0',
+    'ALTER TABLE products ADD COLUMN return_days INTEGER DEFAULT 7',
+    'ALTER TABLE products ADD COLUMN return_condition TEXT',
+    'ALTER TABLE products ADD COLUMN warranty_days INTEGER DEFAULT 0',
+];
+for (const sql of MCP_PRODUCT_COLS) {
+    try {
+        db.exec(sql);
+    }
+    catch { }
+}
+db.exec(`
+  CREATE TABLE IF NOT EXISTS price_sessions (
+    token      TEXT PRIMARY KEY,
+    product_id TEXT NOT NULL,
+    user_id    TEXT NOT NULL,
+    price      REAL NOT NULL,
+    quantity   INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL,
+    used_at    TEXT
+  )
+`);
+db.exec(`
+  CREATE TABLE IF NOT EXISTS mcp_tool_calls (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    tool_name  TEXT NOT NULL,
+    user_id    TEXT,
+    ts         TEXT NOT NULL DEFAULT (datetime('now')),
+    outcome    TEXT NOT NULL,
+    latency_ms INTEGER NOT NULL,
+    error_msg  TEXT
+  )
+`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_mcp_tool_calls_ts   ON mcp_tool_calls(ts)`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_mcp_tool_calls_tool ON mcp_tool_calls(tool_name, ts)`);
 // ─── 工具定义（Agent 读这些来理解如何使用协议）────────────────
 const TOOLS = [
     {
@@ -76,23 +126,45 @@ const TOOLS = [
         name: 'webaz_search',
         description: `搜索 WebAZ中的在售商品。
 无需登录即可搜索，买家或 Agent 可以自由浏览。
-返回匹配的商品列表，包含价格、卖家信息、库存数量。`,
+返回匹配的商品列表，包含价格、结构化规格（specs）、物流信息、售后政策、agent_summary。
+agent_summary 是一句话决策摘要，Agent 可直接用于比价决策。`,
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: '搜索关键词（商品名称或描述）' },
                 category: { type: 'string', description: '商品分类过滤（可选）' },
                 max_price: { type: 'number', description: '最高价格过滤（可选）' },
+                min_return_days: { type: 'number', description: '最少退货天数（可选，如 7 表示只看支持7天退货的商品）' },
+                max_handling_hours: { type: 'number', description: '最长发货时效小时数（可选，如 24 表示只看24h内发货的）' },
                 limit: { type: 'number', description: '返回数量上限，默认 10' },
             },
         },
     },
+    {
+        name: 'webaz_verify_price',
+        description: `在下单前锁定商品价格，获取 session_token。
+Agent 代理用户下单时，应先调用此工具验证并锁定价格，再调用 webaz_place_order 传入 session_token。
+这样可以：1）确保下单时价格与展示价格一致；2）若价格已变动，会提前告知用户；3）平台只对 T0 时刻价格负责。
+session_token 有效期 10 分钟，使用一次后失效。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: '买家的 api_key' },
+                product_id: { type: 'string', description: '商品 ID（从 webaz_search 获得）' },
+                quantity: { type: 'number', description: '购买数量，默认 1' },
+            },
+            required: ['api_key', 'product_id'],
+        },
+    },
     {
         name: 'webaz_list_product',
         description: `卖家上架新商品到 WebAZ。
 需要卖家角色的 api_key。
 上架时系统会自动计算建议质押金额（商品价格的 15%），用于保障买家权益。
-商品上架后买家可以搜索到并下单。`,
+商品上架后买家可以搜索到并下单。
+
+填得越完整，agent_summary 越能帮买家 Agent 做比价决策（品牌/型号/退货/发货时效/质保等）。
+注意：如需价格对标外部链接（独家价/补贴模式），请通过 PWA Web 端上架——链接认领需要走众包验证流程。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -102,6 +174,26 @@ const TOOLS = [
                 price: { type: 'number', description: '商品价格（WAZ）' },
                 stock: { type: 'number', description: '库存数量，默认 1' },
                 category: { type: 'string', description: '商品分类（可选）' },
+                specs: {
+                    type: 'object',
+                    description: '结构化规格键值对，如 {"颜色":"黑色","内存":"16GB","存储":"512GB"}（可选）',
+                },
+                brand: { type: 'string', description: '品牌（可选）' },
+                model: { type: 'string', description: '型号（可选）' },
+                source_price: {
+                    type: 'number',
+                    description: '同款商品的外部参考价（可选，仅作展示，不参与独家价认证——需通过 PWA 完成链接认领）',
+                },
+                ship_regions: { type: 'string', description: '发货地区，默认"全国"' },
+                handling_hours: { type: 'number', description: '发货时效（小时），默认 24' },
+                estimated_days: {
+                    type: 'object',
+                    description: '预计送达天数：数字（如 4）或区域映射（如 {"江浙沪":2,"全国":4}）',
+                },
+                fragile: { type: 'boolean', description: '是否易碎品，默认 false' },
+                return_days: { type: 'number', description: '支持退货天数，默认 7（填 0 表示不支持退货）' },
+                return_condition: { type: 'string', description: '退货条件说明（可选）' },
+                warranty_days: { type: 'number', description: '质保天数，默认 0' },
             },
             required: ['api_key', 'title', 'description', 'price'],
         },
@@ -120,6 +212,10 @@ const TOOLS = [
                 quantity: { type: 'number', description: '购买数量，默认 1' },
                 shipping_address: { type: 'string', description: '收货地址' },
                 notes: { type: 'string', description: '给卖家的备注（可选）' },
+                session_token: {
+                    type: 'string',
+                    description: '价格锁定 token（推荐）：由 webaz_verify_price 返回，确保下单价格与展示价格一致',
+                },
                 promoter_api_key: {
                     type: 'string',
                     description: '推荐人的 api_key（可选，如果是通过推荐链接来的）',
@@ -363,7 +459,8 @@ function handleInfo() {
         },
         quick_start: {
             seller: '1. webaz_register(role=seller) → 2. webaz_list_product() → 3. 等通知 webaz_update_order(accept/ship)',
-            buyer: '1. webaz_register(role=buyer) → 2. webaz_search() → 3. webaz_place_order() → 4. webaz_update_order(confirm)',
+            buyer: '1. webaz_register(role=buyer) → 2. webaz_search() → 3. webaz_verify_price() → 4. webaz_place_order(session_token) → 5. webaz_update_order(confirm)',
+            agent_buying: '用户提供链接 → 1. webaz_search(query) 找到更优方案 → 2. webaz_verify_price(product_id) 锁定价格 → 3. webaz_place_order(session_token) 下单 → 返回成交理由',
             logistics: '1. webaz_register(role=logistics) → 2. webaz_update_order(pickup) → webaz_update_order(deliver)',
         },
         available_tools: TOOLS.map((t) => ({ name: t.name, description: t.description.split('\n')[0] })),
@@ -397,10 +494,52 @@ function handleRegister(args) {
                 : '等待订单分配给你',
     };
 }
+function buildAgentSummary(p) {
+    const parts = [];
+    if (p.brand)
+        parts.push(String(p.brand));
+    if (p.model)
+        parts.push(String(p.model));
+    const returnDays = p.return_days != null ? Number(p.return_days) : null;
+    if (returnDays != null && returnDays > 0)
+        parts.push(`${returnDays}天退货`);
+    else if (returnDays === 0)
+        parts.push('不支持退货');
+    const warranty = p.warranty_days != null ? Number(p.warranty_days) : null;
+    if (warranty && warranty > 0)
+        parts.push(`${warranty}天质保`);
+    const handling = p.handling_hours != null ? Number(p.handling_hours) : null;
+    if (handling != null)
+        parts.push(`${handling}h发货`);
+    if (p.fragile)
+        parts.push('易碎品');
+    return parts.join('，') || '暂无物流信息';
+}
+function parseProductForAgent(p) {
+    let specs = null;
+    if (p.specs) {
+        try {
+            specs = JSON.parse(p.specs);
+        }
+        catch { }
+    }
+    let estimated_days = null;
+    if (p.estimated_days) {
+        try {
+            estimated_days = JSON.parse(p.estimated_days);
+        }
+        catch {
+            estimated_days = null;
+        }
+    }
+    return { ...p, specs, estimated_days, agent_summary: buildAgentSummary(p) };
+}
 function handleSearch(args) {
     const query = args.query ?? '';
     const category = args.category;
     const maxPrice = args.max_price;
+    const minReturnDays = args.min_return_days;
+    const maxHandlingHours = args.max_handling_hours;
     const limit = args.limit ?? 10;
     let sql = `
     SELECT p.*, u.name as seller_name
@@ -421,6 +560,14 @@ function handleSearch(args) {
         sql += ` AND p.price <= ?`;
         params.push(maxPrice);
     }
+    if (minReturnDays !== undefined) {
+        sql += ` AND p.return_days >= ?`;
+        params.push(minReturnDays);
+    }
+    if (maxHandlingHours !== undefined) {
+        sql += ` AND p.handling_hours <= ?`;
+        params.push(maxHandlingHours);
+    }
     sql += ` ORDER BY p.created_at DESC LIMIT ?`;
     params.push(limit);
     const products = db.prepare(sql).all(...params);
@@ -439,20 +586,79 @@ function handleSearch(args) {
         products: sorted.map((p) => {
             const levelMeta = { new: '', trusted: '⭐', quality: '🌟', star: '💫', legend: '🔥' };
             const badge = levelMeta[p._rep_level] ?? '';
+            const parsed = parseProductForAgent(p);
             return {
                 id: p.id,
                 title: p.title,
-                description: p.description,
-                price: `${p.price} WAZ`,
+                price: p.price,
+                price_display: `${p.price} WAZ`,
                 stock: p.stock,
                 category: p.category,
+                specs: parsed.specs,
+                agent_summary: parsed.agent_summary,
+                logistics: {
+                    handling_hours: p.handling_hours ?? 24,
+                    estimated_days: parsed.estimated_days,
+                    ship_regions: p.ship_regions ?? '全国',
+                    fragile: !!p.fragile,
+                },
+                after_sales: {
+                    return_days: p.return_days ?? 7,
+                    return_condition: p.return_condition ?? '',
+                    warranty_days: p.warranty_days ?? 0,
+                },
                 seller: badge ? `${badge} ${p.seller_name}` : p.seller_name,
                 seller_id: p.seller_id,
-                seller_reputation: p._rep_level !== 'new' ? `${badge} ${['', '可信', '优质', '明星', '传奇'][['new', 'trusted', 'quality', 'star', 'legend'].indexOf(p._rep_level)]}（${p._rep_points}分）` : undefined,
+                seller_reputation: p._rep_level !== 'new'
+                    ? `${badge} ${['', '可信', '优质', '明星', '传奇'][['new', 'trusted', 'quality', 'star', 'legend'].indexOf(p._rep_level)]}（${p._rep_points}分）`
+                    : undefined,
             };
         }),
     };
 }
+function handleVerifyPrice(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const productId = args.product_id;
+    const qty = Number(args.quantity ?? 1);
+    if (!productId)
+        return { error: '请提供 product_id' };
+    const product = db.prepare(`
+    SELECT p.*, u.name as seller_name FROM products p
+    JOIN users u ON p.seller_id = u.id
+    WHERE p.id = ? AND p.status = 'active'
+  `).get(productId);
+    if (!product)
+        return { error: `商品不存在或已下架：${productId}` };
+    if (product.stock < qty) {
+        return { error: `库存不足：当前库存 ${product.stock}，请求数量 ${qty}` };
+    }
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + 10 * 60_000);
+    const token = `pst_${now.getTime().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+    db.prepare(`
+    INSERT INTO price_sessions (token, product_id, user_id, price, quantity, created_at, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).run(token, productId, user.id, product.price, qty, now.toISOString(), expiresAt.toISOString());
+    const parsed = parseProductForAgent(product);
+    return {
+        session_token: token,
+        verified_price: product.price,
+        quantity: qty,
+        total: product.price * qty,
+        product: {
+            id: product.id,
+            title: product.title,
+            agent_summary: parsed.agent_summary,
+            specs: parsed.specs,
+        },
+        expires_at: expiresAt.toISOString(),
+        expires_in_seconds: 600,
+        next: `调用 webaz_place_order 时传入 session_token="${token}" 确保以此价格成交`,
+    };
+}
 function handleListProduct(args) {
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
@@ -475,10 +681,20 @@ function handleListProduct(args) {
         };
     }
     const id = generateId('prd');
+    const specsJson = args.specs != null
+        ? (typeof args.specs === 'string' ? args.specs : JSON.stringify(args.specs))
+        : null;
+    const estJson = args.estimated_days != null
+        ? (typeof args.estimated_days === 'string' ? args.estimated_days : JSON.stringify(args.estimated_days))
+        : null;
     db.prepare(`
-    INSERT INTO products (id, seller_id, title, description, price, stock, category, stake_amount)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(id, user.id, args.title, args.description, price, args.stock ?? 1, args.category ?? null, stakeAmount);
+    INSERT INTO products (
+      id, seller_id, title, description, price, stock, category, stake_amount,
+      specs, brand, model, source_price,
+      ship_regions, handling_hours, estimated_days, fragile,
+      return_days, return_condition, warranty_days
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?, ?,  ?, ?, ?)
+  `).run(id, user.id, args.title, args.description, price, args.stock ?? 1, args.category ?? null, stakeAmount, specsJson, args.brand ?? null, args.model ?? null, args.source_price != null ? Number(args.source_price) : null, args.ship_regions ?? '全国', args.handling_hours != null ? Number(args.handling_hours) : 24, estJson, args.fragile ? 1 : 0, args.return_days != null ? Number(args.return_days) : 7, args.return_condition ?? '', args.warranty_days != null ? Number(args.warranty_days) : 0);
     // 扣除质押金额
     db.prepare(`
     UPDATE wallets SET balance = balance - ?, staked = staked + ? WHERE user_id = ?
@@ -513,6 +729,28 @@ function handlePlaceOrder(args) {
     if (product.stock < quantity) {
         return { error: `库存不足：当前库存 ${product.stock}，你要购买 ${quantity}` };
     }
+    // 验证 session_token（如果提供）
+    if (args.session_token) {
+        const session = db.prepare(`
+      SELECT * FROM price_sessions WHERE token = ? AND product_id = ? AND user_id = ?
+    `).get(args.session_token, args.product_id, user.id);
+        if (!session)
+            return { error: 'session_token 无效，请重新调用 webaz_verify_price' };
+        if (session.used_at)
+            return { error: 'session_token 已使用，请重新调用 webaz_verify_price' };
+        if (new Date(session.expires_at) < new Date()) {
+            return { error: 'session_token 已过期（10分钟有效），请重新调用 webaz_verify_price' };
+        }
+        if (session.price !== product.price) {
+            return {
+                error: 'price_changed',
+                message: `商品价格已变动：验证时 ${session.price} WAZ，当前 ${product.price} WAZ`,
+                new_price: product.price,
+                hint: '请重新调用 webaz_verify_price 获取新价格后再下单',
+            };
+        }
+        db.prepare(`UPDATE price_sessions SET used_at = datetime('now') WHERE token = ?`).run(args.session_token);
+    }
     const totalAmount = product.price * quantity;
     const wallet = db
         .prepare('SELECT * FROM wallets WHERE user_id = ?')
@@ -1098,6 +1336,7 @@ export async function startMCPServer() {
     });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args = {} } = request.params;
+        const t0 = Date.now();
         let result;
         try {
             switch (name) {
@@ -1110,6 +1349,9 @@ export async function startMCPServer() {
                 case 'webaz_search':
                     result = handleSearch(args);
                     break;
+                case 'webaz_verify_price':
+                    result = handleVerifyPrice(args);
+                    break;
                 case 'webaz_list_product':
                     result = handleListProduct(args);
                     break;
@@ -1146,6 +1388,7 @@ export async function startMCPServer() {
         catch (err) {
             result = { error: `执行出错：${err.message}` };
         }
+        recordToolCall(name, args, result, Date.now() - t0);
         return {
             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         };
@@ -1158,3 +1401,46 @@ export async function startMCPServer() {
 function addHours(date, hours) {
     return new Date(date.getTime() + hours * 3_600_000).toISOString();
 }
+function recordToolCall(tool, args, result, latencyMs) {
+    let userId = null;
+    try {
+        const apiKey = args.api_key;
+        if (apiKey) {
+            const row = db.prepare('SELECT id FROM users WHERE api_key = ?').get(apiKey);
+            if (row)
+                userId = row.id;
+        }
+        const isError = !!result && typeof result === 'object' && 'error' in result;
+        const errorMsg = isError
+            ? String(result.error).slice(0, 200)
+            : null;
+        db.prepare(`INSERT INTO mcp_tool_calls (tool_name, user_id, outcome, latency_ms, error_msg)
+       VALUES (?, ?, ?, ?, ?)`).run(tool, userId, isError ? 'error' : 'success', latencyMs, errorMsg);
+        sendTelemetry({
+            tool_name: tool,
+            outcome: isError ? 'error' : 'success',
+            latency_ms: latencyMs,
+            user_id_hash: userId ? createHash('sha256').update(userId).digest('hex').slice(0, 16) : null,
+        });
+    }
+    catch (e) {
+        console.error('[telemetry-write-failed]', e.message);
+    }
+}
+function sendTelemetry(payload) {
+    if (!TELEMETRY_ENABLED)
+        return;
+    try {
+        void fetch(TELEMETRY_URL, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                ...payload,
+                server_version: SERVER_VERSION,
+                ts: new Date().toISOString(),
+            }),
+            signal: AbortSignal.timeout(2000),
+        }).catch(() => { });
+    }
+    catch { /* never block the tool call */ }
+}