@seasonkoh/webaz 0.1.6 → 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（可选，如果是通过推荐链接来的）',
@@ -227,7 +323,7 @@ action 说明：
 ruling 裁定选项（arbitrate 时使用）：
 - refund_buyer：全额退款给买家，扣押卖家部分保证金
 - release_seller：资金释放给卖家（卖家胜诉）
-- partial_refund：部分退款（需指定 refund_amount）`,
+- partial_refund：部分退款（需指定 refund_amount）；若责任在第三方（如物流），同时指定 liable_party（责任方 user_id），此时卖家全额结算，赔偿金从责任方扣除`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -247,6 +343,7 @@ ruling 裁定选项（arbitrate 时使用）：
                     description: '裁定结果（arbitrate 时必填）',
                 },
                 refund_amount: { type: 'number', description: '部分退款金额，仅 ruling=partial_refund 时使用' },
+                liable_party: { type: 'string', description: '第三方责任方 user_id（partial_refund 时可选）：指定后赔偿金从该方扣除，卖家全额结算' },
                 ruling_reason: { type: 'string', description: '裁定理由（arbitrate 时必填，将永久记录在链上）' },
             },
             required: ['api_key', 'action'],
@@ -362,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] })),
@@ -396,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
@@ -420,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);
@@ -438,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)
@@ -474,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 = ?
@@ -512,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 = ?')
@@ -866,7 +1105,7 @@ function handleDispute(args) {
         if (args.ruling === 'partial_refund' && !args.refund_amount) {
             return { error: 'partial_refund 需要提供 refund_amount' };
         }
-        const result = arbitrateDispute(db, args.dispute_id, user.id, args.ruling, args.ruling_reason, args.refund_amount);
+        const result = arbitrateDispute(db, args.dispute_id, user.id, args.ruling, args.ruling_reason, args.refund_amount, undefined, args.liable_party);
         // L4-3 争议声誉：裁定完成后更新声誉
         if (result.success) {
             const dispute = getDisputeDetails(db, args.dispute_id);
@@ -1097,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) {
@@ -1109,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;
@@ -1145,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) }],
         };
@@ -1157,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 */ }
+}

package/dist/layer3-trust/L3-1-dispute-engine/dispute-engine.js

@@ -143,7 +143,8 @@ export function respondToDispute(db, disputeId, responderId, notes, evidenceIds)
         message: '反驳证据已提交，争议进入仲裁阶段。仲裁员将在 72 小时内做出裁定。',
     };
 }
-export function arbitrateDispute(db, disputeId, arbitratorId, ruling, reason, refundAmount, liabilityParties) {
+export function arbitrateDispute(db, disputeId, arbitratorId, ruling, reason, refundAmount, liabilityParties, liablePartyId // 指定责任方 user_id（用于 partial_refund 第三方责任场景）
+) {
     const dispute = db.prepare('SELECT * FROM disputes WHERE id = ?').get(disputeId);
     if (!dispute)
         return { success: false, error: `争议不存在：${disputeId}` };
@@ -159,10 +160,10 @@ export function arbitrateDispute(db, disputeId, arbitratorId, ruling, reason, re
     // 执行资金处置
     const settlement = ruling === 'liability_split' && liabilityParties
         ? executeLiabilitySplit(db, dispute.order_id, liabilityParties, refundAmount)
-        : executeSettlement(db, dispute.order_id, ruling, refundAmount);
+        : executeSettlement(db, dispute.order_id, ruling, refundAmount, liablePartyId);
     if (!settlement.success)
         return { success: false, error: settlement.error };
-    // 收取仲裁费（败诉方付 1%，最低 1 WAZ）
+    // 收取仲裁费（败诉/责任方付 1%，最低 1 WAZ）
     const order = db.prepare('SELECT total_amount, buyer_id, seller_id FROM orders WHERE id = ?')
         .get(dispute.order_id);
     const sysUser = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
@@ -170,29 +171,35 @@ export function arbitrateDispute(db, disputeId, arbitratorId, ruling, reason, re
     if (order) {
         const amt = order.total_amount;
         if (ruling === 'refund_buyer') {
-            // 卖家败诉
             const f = chargeArbitrationFee(db, order.seller_id, amt, arbitratorId, sysUser.id);
             if (f.fee > 0)
                 arbFees[order.seller_id] = f.fee;
         }
         else if (ruling === 'release_seller') {
-            // 买家败诉
             const f = chargeArbitrationFee(db, order.buyer_id, amt, arbitratorId, sysUser.id);
             if (f.fee > 0)
                 arbFees[order.buyer_id] = f.fee;
         }
         else if (ruling === 'partial_refund') {
-            // 折中：双方各付 0.5%（最低各 0.5 WAZ，实际按 chargeArbitrationFee 的 min 逻辑）
-            const halfAmt = amt * 0.5;
-            const fb = chargeArbitrationFee(db, order.buyer_id, halfAmt, arbitratorId, sysUser.id);
-            const fs = chargeArbitrationFee(db, order.seller_id, halfAmt, arbitratorId, sysUser.id);
-            if (fb.fee > 0)
-                arbFees[order.buyer_id] = fb.fee;
-            if (fs.fee > 0)
-                arbFees[order.seller_id] = fs.fee;
+            // 有指定责任方：仲裁费全由责任方承担
+            // 无责任方：买卖双方各付 0.5%
+            const payerId = liablePartyId ?? null;
+            if (payerId) {
+                const f = chargeArbitrationFee(db, payerId, amt, arbitratorId, sysUser.id);
+                if (f.fee > 0)
+                    arbFees[payerId] = f.fee;
+            }
+            else {
+                const halfAmt = amt * 0.5;
+                const fb = chargeArbitrationFee(db, order.buyer_id, halfAmt, arbitratorId, sysUser.id);
+                const fs = chargeArbitrationFee(db, order.seller_id, halfAmt, arbitratorId, sysUser.id);
+                if (fb.fee > 0)
+                    arbFees[order.buyer_id] = fb.fee;
+                if (fs.fee > 0)
+                    arbFees[order.seller_id] = fs.fee;
+            }
         }
         else if (ruling === 'liability_split' && liabilityParties) {
-            // 各责任方按比例分担
             const totalLiability = liabilityParties.reduce((s, p) => s + p.amount, 0) || amt;
             for (const p of liabilityParties) {
                 const share = (p.amount / totalLiability) * amt;
@@ -378,7 +385,7 @@ function chargeArbitrationFee(db, loserId, orderAmount, arbitratorId, sysUserId)
     }
     return { fee: actualFee, arbitratorShare, protocolShare };
 }
-function executeSettlement(db, orderId, ruling, refundAmount) {
+function executeSettlement(db, orderId, ruling, refundAmount, liablePartyId) {
     const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
     if (!order)
         return { success: false, error: '订单不存在' };
@@ -447,35 +454,88 @@ function executeSettlement(db, orderId, ruling, refundAmount) {
         };
     }
     else if (ruling === 'partial_refund') {
-        // ── 折中处理：部分退款 ────────────────────────────────────────
         const refund = refundAmount ?? Math.round(totalAmount * 0.5 * 100) / 100;
         if (refund > totalAmount)
             return { success: false, error: `退款金额 ${refund} 超出订单总额 ${totalAmount}` };
-        const sellerGet = Math.round((totalAmount - refund) * 100) / 100;
-        const stakeReturn = Math.round(stakeAmount * 0.5 * 100) / 100; // 质押返一半
-        db.transaction(() => {
-            db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, buyerId);
-            if (refund > 0) {
-                db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(refund, buyerId);
-            }
-            if (sellerGet > 0) {
-                db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(sellerGet, sellerId);
-            }
-            if (stakeAmount > 0) {
-                db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
-                    .run(stakeAmount, stakeReturn, sellerId);
-            }
-            transition(db, orderId, 'cancelled', sysUser.id, [], `争议裁定：部分退款 ${refund} WAZ`);
-        })();
-        return {
-            success: true,
-            detail: {
-                ruling: 'partial_refund',
-                buyer_refund: refund,
-                seller_received: sellerGet,
-                seller_stake_returned: stakeReturn,
-            }
-        };
+        if (liablePartyId) {
+            // ── 第三方责任 partial_refund ────────────────────────────────
+            // 卖家全额结算（正常收款），买家赔偿由责任方钱包直接支付
+            const protocolFee = Math.round(totalAmount * 0.02 * 100) / 100;
+            const logisticsFee = order.logistics_id ? Math.round(totalAmount * 0.05 * 100) / 100 : 0;
+            const sellerAmount = totalAmount - protocolFee - logisticsFee;
+            // 检查责任方余额是否足够
+            const liableWallet = db.prepare('SELECT balance, staked FROM wallets WHERE user_id = ?')
+                .get(liablePartyId);
+            const liableAvailable = (liableWallet?.balance ?? 0) + (liableWallet?.staked ?? 0);
+            const actualRefund = Math.min(refund, liableAvailable);
+            db.transaction(() => {
+                // 1. 释放托管 → 正常结算给卖家
+                db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, buyerId);
+                db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(sellerAmount, sellerId);
+                if (order.logistics_id && logisticsFee > 0) {
+                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(logisticsFee, order.logistics_id);
+                }
+                // 2. 返还卖家质押
+                if (stakeAmount > 0) {
+                    db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
+                        .run(stakeAmount, stakeAmount, sellerId);
+                }
+                // 3. 从责任方钱包扣除赔偿（先质押后余额）
+                if (actualRefund > 0) {
+                    const liableStaked = liableWallet?.staked ?? 0;
+                    if (liableStaked >= actualRefund) {
+                        db.prepare('UPDATE wallets SET staked = staked - ? WHERE user_id = ?').run(actualRefund, liablePartyId);
+                    }
+                    else {
+                        const fromBalance = actualRefund - liableStaked;
+                        db.prepare('UPDATE wallets SET staked = 0, balance = balance - ? WHERE user_id = ?').run(fromBalance, liablePartyId);
+                    }
+                    // 4. 赔偿金给买家
+                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(actualRefund, buyerId);
+                }
+                transition(db, orderId, 'completed', sysUser.id, [], `争议裁定：第三方责任赔偿 ${actualRefund} WAZ，卖家全额结算`);
+            })();
+            return {
+                success: true,
+                detail: {
+                    ruling: 'partial_refund',
+                    liable_party: liablePartyId,
+                    buyer_compensation: actualRefund,
+                    seller_received: sellerAmount,
+                    logistics_fee: logisticsFee,
+                    protocol_fee: protocolFee,
+                    seller_stake_returned: stakeAmount,
+                }
+            };
+        }
+        else {
+            // ── 买卖双方协商 partial_refund（原逻辑）───────────────────────
+            const sellerGet = Math.round((totalAmount - refund) * 100) / 100;
+            const stakeReturn = Math.round(stakeAmount * 0.5 * 100) / 100; // 质押返一半
+            db.transaction(() => {
+                db.prepare('UPDATE wallets SET escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, buyerId);
+                if (refund > 0) {
+                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(refund, buyerId);
+                }
+                if (sellerGet > 0) {
+                    db.prepare('UPDATE wallets SET balance = balance + ? WHERE user_id = ?').run(sellerGet, sellerId);
+                }
+                if (stakeAmount > 0) {
+                    db.prepare('UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?')
+                        .run(stakeAmount, stakeReturn, sellerId);
+                }
+                transition(db, orderId, 'cancelled', sysUser.id, [], `争议裁定：部分退款 ${refund} WAZ`);
+            })();
+            return {
+                success: true,
+                detail: {
+                    ruling: 'partial_refund',
+                    buyer_refund: refund,
+                    seller_received: sellerGet,
+                    seller_stake_returned: stakeReturn,
+                }
+            };
+        }
     }
     return { success: false, error: `未知裁定类型：${ruling}` };
 }