@seasonkoh/webaz 0.1.7 → 0.1.9

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

@@ -17,12 +17,16 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initDatabase, generateId } from '../../layer0-foundation/L0-1-database/schema.js';
 import { transition, getOrderStatus, initSystemUser, } from '../../layer0-foundation/L0-2-state-machine/engine.js';
-import { initDisputeSchema, createDispute, respondToDispute, arbitrateDispute, getDisputeDetails, getOrderDispute, getOpenDisputes, } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js';
+import { initDisputeSchema, createDispute, respondToDispute, getDisputeDetails, getOrderDispute, getOpenDisputes, } from '../../layer3-trust/L3-1-dispute-engine/dispute-engine.js';
 import { initNotificationSchema, notifyTransition, getNotifications, getUnreadCount, markRead, } from '../../layer2-business/L2-6-notifications/notification-engine.js';
 import { initSkillSchema, publishSkill, listSkills, getMySkills, subscribeSkill, unsubscribeSkill, getMySubscriptions, formatSkillForAgent, shouldAutoAccept, SKILL_TYPE_META, } from '../../layer4-economics/L4-4-skill-market/skill-engine.js';
-import { initReputationSchema, recordOrderReputation, recordDisputeReputation, getReputation, getSearchBoost, getStakeDiscount, } from '../../layer4-economics/L4-3-reputation/reputation-engine.js';
+import { initReputationSchema, recordOrderReputation, 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, randomBytes } 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,14 +34,129 @@ 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)`);
+// ─── 4 层身份模型 helpers（与 PWA server 同源逻辑）───────────────
+const PERMA_ALPHABET_MCP = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function mcpGeneratePermanentCode() {
+    for (let attempt = 0; attempt < 20; attempt++) {
+        let code = '';
+        for (let i = 0; i < 6; i++)
+            code += PERMA_ALPHABET_MCP[Math.floor(Math.random() * 32)];
+        const exists = db.prepare("SELECT 1 FROM users WHERE permanent_code = ?").get(code);
+        if (!exists)
+            return code;
+    }
+    for (let attempt = 0; attempt < 20; attempt++) {
+        let code = '';
+        for (let i = 0; i < 7; i++)
+            code += PERMA_ALPHABET_MCP[Math.floor(Math.random() * 32)];
+        const exists = db.prepare("SELECT 1 FROM users WHERE permanent_code = ?").get(code);
+        if (!exists)
+            return code;
+    }
+    throw new Error('permanent_code generation exhausted');
+}
+function mcpDeriveHandle(name) {
+    let base = String(name || '').normalize('NFKD').replace(/[̀-ͯ]/g, '');
+    base = base.replace(/[^a-zA-Z0-9._]/g, '').toLowerCase();
+    base = base.replace(/^[._]+|[._]+$/g, '');
+    if (base.length < 3)
+        base = 'user' + Math.random().toString(36).slice(2, 7);
+    if (base.length > 18)
+        base = base.slice(0, 18);
+    if (/^(usr|sys|admin|webaz|anonymous|null)/.test(base))
+        base = 'u_' + base;
+    const requested = base;
+    let candidate = base, i = 1;
+    while (db.prepare("SELECT 1 FROM users WHERE handle = ?").get(candidate)) {
+        candidate = base.slice(0, 16) + i.toString();
+        i++;
+        if (i > 9999)
+            throw new Error('handle generation exhausted');
+    }
+    return { handle: candidate, requested, modified: candidate !== requested };
+}
+// 多形态用户引用解析：usr_xxx / VKSF9P / @handle / handle → 内部 id
+function mcpResolveUserRef(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    const ref = raw.trim();
+    if (!ref)
+        return null;
+    if (/^usr_[A-Za-z0-9_]+$/.test(ref)) {
+        const r = db.prepare("SELECT id FROM users WHERE id = ?").get(ref);
+        return r?.id || null;
+    }
+    if (/^[A-Z0-9]{6,7}$/i.test(ref) && !ref.startsWith('@')) {
+        const r = db.prepare("SELECT id FROM users WHERE permanent_code = ?").get(ref.toUpperCase());
+        if (r)
+            return r.id;
+    }
+    const h = ref.replace(/^@/, '').toLowerCase();
+    if (/^[a-z0-9._]+$/.test(h)) {
+        const r = db.prepare("SELECT id FROM users WHERE handle = ?").get(h);
+        if (r)
+            return r.id;
+    }
+    return null;
+}
 // ─── 工具定义（Agent 读这些来理解如何使用协议）────────────────
 const TOOLS = [
     {
         name: 'webaz_info',
-        description: `获取 WebAZ的说明和使用指南。
-这是新 Agent 接入协议时应该调用的第一个工具。
-返回：协议简介、所有可用工具、每个角色的职责和操作流程。
-无需任何参数，无需身份验证。`,
+        description: `Get WebAZ documentation and usage guide. Call this FIRST when onboarding a new agent.
+Returns: protocol overview, available tools, role responsibilities, operation flows, **network_state (pre-launch disclaimer)**, **commission_model.compliance_notice (MLM-form disclosure)**.
+No auth required, no parameters needed.
+
+⚠️ Important: WebAZ is currently **pre-launch** with ~0 real users on the canonical endpoint. All stats / counts returned by this and other tools come from the **local MCP SQLite DB**, not protocol-wide prod state. Read network_state field BEFORE you treat any number as real-economy data.
+
+──
+中文：获取 WebAZ 说明 — 新 Agent 接入协议时应首先调用，返回协议简介、可用工具、角色职责、**网络状态(pre-launch 披露)** + **佣金结构合规提示(MLM 形态披露)**。⚠️ 协议尚未上线,统计来自本地库,不是真实运营数据。`,
         inputSchema: {
             type: 'object',
             properties: {},
@@ -45,16 +164,29 @@ const TOOLS = [
     },
     {
         name: 'webaz_register',
-        description: `在 WebAZ中注册新账户。
-注册后获得唯一的 api_key，后续所有操作都需要这个 key。
-请将 api_key 安全保存，它代表你在协议中的身份。
-
-角色说明：
-- buyer（买家）：浏览商品、下单、确认收货
-- seller（卖家）：上架商品、接单、发货
-- logistics（物流）：揽收包裹、更新运输状态、确认投递
-- reviewer（测评员）：对商品进行结构化测评
-- arbitrator（仲裁员）：处理争议，做出裁定`,
+        description: `Register a new WebAZ account. Returns:
+- api_key (credential, 36 chars, 128-bit crypto random — store securely)
+- permanent_code (6-char recovery code — use with handle via webaz_mykey to recover lost api_key)
+- handle (URL-safe unique ID derived from name; if requested handle is taken, system auto-appends numeric suffix — check handle_modified flag)
+- created_at (ISO timestamp)
+
+⚠️ Consent required: WebAZ is pre-launch and contains a 3-tier commission + binary PV pairing structure (see webaz_info.commission_model.compliance_notice — may overlap with MLM legal definitions). An agent acting for a human user MUST get the user's explicit, informed consent BEFORE creating an account on their behalf. Do NOT auto-register users just because they asked a generic shopping question.
+
+Roles:
+- buyer:      browse, order, confirm receipt
+- seller:     list products, accept orders, ship
+- logistics:  pickup, transit updates, delivery confirm
+- reviewer:   structured product reviews
+- arbitrator: handle disputes, issue rulings
+
+⚠️ MCP register limitations (by-design anti-bot):
+- Does NOT set placement_id / sponsor_id (binary tree + referral chain not built) — MCP registration does NOT enroll the user into the multi-tier structure
+- To build a referral chain: user must arrive via webaz_share_link ?ref=<uid> URL clicked in browser (PWA flow) — explicit user action required
+- region defaults to 'global' if omitted; valid: singapore, china, usa, malaysia, indonesia, thailand, vietnam, taiwan, hk, global
+
+──
+中文：注册 WebAZ 账户。返回 api_key（128-bit 凭证）+ permanent_code（恢复码）+ handle（唯一标识，冲突自动加后缀，看 handle_modified）+ created_at。可选角色：买家/卖家/物流/测评员/仲裁员。
+注意：MCP register 不建立 placement/sponsor 链（防 bot），需要建链时用 webaz_share_link + PWA 浏览器注册。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -68,50 +200,191 @@ const TOOLS = [
                     type: 'number',
                     description: '初始模拟余额（测试用，默认 1000 WAZ）',
                 },
+                region: {
+                    type: 'string',
+                    enum: ['global', 'singapore', 'china', 'usa', 'malaysia', 'indonesia', 'thailand', 'vietnam', 'taiwan', 'hk'],
+                    description: '账号所在地区（默认 global；影响 referral region cap 与佣金 redirect_region_cap 规则）',
+                },
             },
             required: ['name', 'role'],
         },
     },
     {
         name: 'webaz_search',
-        description: `搜索 WebAZ中的在售商品。
-无需登录即可搜索，买家或 Agent 可以自由浏览。
-返回匹配的商品列表，包含价格、卖家信息、库存数量。`,
+        description: `Search WebAZ marketplace listings. No auth required.
+Returns structured specs + logistics + after-sales + agent_summary (one-line decision hint).
+
+【Keyword search】Pass query / category / max_price / min_return_days / max_handling_hours.
+
+【External-link paste search】When user pastes share text from Taobao/Tmall/JD/Pinduoduo/1688/Douyin/Xiaohongshu
+(e.g. '【淘宝】「Product Name」 https://e.tb.cn/xxx ...'), do:
+1) Prefer your own LLM parsing → pass external_link object with:
+   - platform: 'taobao'|'tmall'|'jd'|'pdd'|'1688'|'douyin'|'xhs'
+   - external_id: canonical product ID (if resolvable from short URL; else omit)
+   - external_title: the title text inside 「」 brackets verbatim
+2) If you can't parse, drop the raw text into paste_text — WebAZ server does light regex parsing (no outbound calls)
+
+Match rules (STRICT, no guessing):
+- Level 1: external_id exact match
+- Level 2: external_title string exact match
+- Neither hit → matched_by: 'none', **NO fuzzy fallback, NO keyword degradation**
+
+IMPORTANT: matched_by='none' is an honest signal — tell the user "no exact match found".
+Do NOT silently fall back to keyword search (that's a separate tool's job).
+Do NOT guess similar products from title impressions.
+WebAZ's trust premise is that match results are TRULY precise, not "looks similar".
+
+Note: paste-link matching hits webaz.xyz production data, not your local webaz.db.
+
+──
+中文：商品搜索（无需登录）。两种模式：关键词搜索 + 粘贴外链精准匹配。外链匹配强制精准（仅 external_id 或 external_title 完全相等命中），不命中返回 matched_by:'none'，不做模糊降级。`,
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: '搜索关键词（商品名称或描述）' },
                 category: { type: 'string', description: '商品分类过滤（可选）' },
                 max_price: { type: 'number', description: '最高价格过滤（可选）' },
-                limit: { type: 'number', description: '返回数量上限，默认 10' },
+                min_return_days: { type: 'number', description: '最少退货天数（可选，如 7 表示只看支持7天退货的商品）' },
+                max_handling_hours: { type: 'number', description: '最长发货时效小时数（可选，如 24 表示只看24h内发货的）' },
+                paste_text: { type: 'string', description: '用户粘贴的分享文本/外链原文（可选，服务端做轻量解析）' },
+                external_link: {
+                    type: 'object',
+                    description: '外链结构化匹配（可选，由 agent 解析得到）',
+                    properties: {
+                        platform: { type: 'string', description: "'taobao'|'tmall'|'jd'|'pdd'|'1688'|'douyin'|'xhs'" },
+                        external_id: { type: 'string', description: '平台商品 canonical ID（可选）' },
+                        external_title: { type: 'string', description: '平台商品标题全文（可选）' },
+                        canonical_url: { type: 'string', description: '规范 URL（可选）' },
+                    },
+                },
+                limit: { type: 'number', description: '返回数量上限，默认 10，agent 模式可调到 200' },
+                sort: { type: 'string', enum: ['trending', 'newest', 'rating', 'price_asc', 'price_desc', 'random'], description: '排序：trending=综合分（默认），newest=最新，rating=信誉，price_asc/price_desc=价格，random=随机探索' },
+                has_sales: { type: 'string', enum: ['true', 'false'], description: 'true=只看已成交，false=只看新品' },
+                ship_to: { type: 'string', description: '配送目的地（省/市），自动过滤不可派送商品' },
+                seller_id: { type: 'string', description: '只看某卖家的商品' },
+                cursor: { type: 'string', description: '分页 cursor（上次返回的 next_cursor）' },
+            },
+        },
+    },
+    {
+        name: 'webaz_verify_price',
+        description: `Lock product price before placing order — returns session_token.
+Recommended flow for agents: call this first to verify & lock price, then call webaz_place_order with session_token.
+Benefits: (1) order price matches displayed; (2) caller is alerted if price changed; (3) platform only liable for T0 price.
+session_token: 10-minute TTL, single-use.
+
+──
+中文：下单前锁价 — 10 分钟一次性 session_token；agent 应先调此再调 place_order。`,
+        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%），用于保障买家权益。
-商品上架后买家可以搜索到并下单。`,
+        description: `Seller product catalog management (create / update / shelf / archive / query own listings).
+Requires seller-role api_key. On create, system auto-suggests stake (~15% of price) to secure buyer protection.
+
+Fill fields completely — better agent_summary helps buyer agents make comparison decisions (brand / return / handling / warranty).
+Note: for "exclusive price vs external link" listing, use PWA Web only — link claim needs crowd-verification.
+
+Actions:
+- create  list a new product (default; needs title/description/price)
+- mine    list all my products (no product_id needed)
+- update  modify fields (needs product_id; only changed fields)
+- delist  move to warehouse (status: warehouse; needs product_id)
+- relist  re-shelve from warehouse (status: active; needs product_id)
+- trash   move to trash (status: deleted; needs product_id)
+- delete  permanent delete (only trash items with no active orders; needs product_id)
+
+──
+中文：卖家商品目录管理（上架/更新/下架/回收/删除/查询）。Actions: create / mine / update / delist / relist / trash / delete。上架时系统自动建议 15% 价格的质押金。`,
         inputSchema: {
             type: 'object',
             properties: {
                 api_key: { type: 'string', description: '卖家的 api_key' },
-                title: { type: 'string', description: '商品名称' },
-                description: { type: 'string', description: '商品详细描述' },
-                price: { type: 'number', description: '商品价格（WAZ）' },
+                action: {
+                    type: 'string',
+                    enum: ['create', 'mine', 'update', 'delist', 'relist', 'trash', 'delete'],
+                    description: '要执行的操作（缺省 = create）',
+                },
+                product_id: { type: 'string', description: '商品 ID（update / delist / relist / trash / delete 时必填）' },
+                title: { type: 'string', description: '商品名称（create 必填；update 可选）' },
+                description: { type: 'string', description: '商品详细描述（create 必填；update 可选）' },
+                price: { type: 'number', description: '商品价格 WAZ（create 必填；update 可选）' },
                 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' },
+                // S2 库存预警
+                low_stock_threshold: {
+                    type: 'number',
+                    description: '【S2】库存预警阈值（≤ 此数时通知卖家；填 0 = 关闭预警）',
+                },
+                auto_delist_on_zero: {
+                    type: 'boolean',
+                    description: '【S2】库存归零时自动下架到仓库（防超卖）',
+                },
+                // S3 跨境上架多语言
+                i18n_titles: {
+                    type: 'object',
+                    description: '【S3】多语言标题，key 是语言码（en/ja/ko/fr/de/es/pt/ru/ar），value 是该语言标题（≤500 字）。zh 用 title 字段，无需填这里。例: {"en":"Wireless Earbuds","ja":"ワイヤレスイヤホン"}',
+                },
+                i18n_descs: {
+                    type: 'object',
+                    description: '【S3】多语言描述，结构同 i18n_titles',
+                },
+                // S4 商品溯源（origin_claims）— 协议级可挑战
+                origin_claims: {
+                    type: 'object',
+                    description: '【S4】商品溯源声明（可挑战）。例: {"made_in":"日本京都","material":"100% 棉 GOTS 认证","certs":[{"name":"GOTS","sha256":"<64 位 hex>"}]}。整体 JSON ≤ 4KB；任一证书 sha256 必须是 64 位 hex。任何买家可发起 claim 验证。',
+                },
             },
-            required: ['api_key', 'title', 'description', 'price'],
+            required: ['api_key'],
         },
     },
     {
         name: 'webaz_place_order',
-        description: `买家下单购买商品。
-需要买家角色的 api_key。
-下单后资金自动进入协议托管，卖家需在 24 小时内接单。
-如卖家超时不接单，协议自动退款并记录违约。`,
+        description: `Buyer places an order. Requires buyer-role api_key.
+
+On order, funds auto-enter protocol escrow. Order deadlines (all stored as absolute ISO timestamps in the response):
+- accept_deadline:   T+48h  (i.e., seller has 24h after the buyer's payment which is itself T+24h)
+- ship_deadline:     T+120h (72h after accept)
+- pickup_deadline:   T+168h (48h after ship)
+- delivery_deadline: T+336h (7d after pickup)
+- confirm_deadline:  T+408h (72h after delivery)
+
+Missing any deadline auto-judges fault against the responsible party and triggers compensation per protocol economics.
+
+【B1 Cross-border tax】For cross-border orders, server auto-estimates import duty (seller's est_import_duty_pct × price) and returns it in the response.
+【B2 Privacy mode】Pass anonymous_recipient=true → system generates a PR-XXXXX alias instead of real name on shipping label.
+【B5 Donation】Optional donation_pct (0 / 0.5% / 1% / 2% / 5%) — sends that fraction of order amount to charity_fund.
+
+──
+中文：买家下单 — 资金进托管。订单 6 个 deadline 都是绝对时间戳，每个相对前一步的允许时长：accept 24h→ship 72h→pickup 48h→deliver 7d→confirm 72h。任何一个超时由对应责任方违约。可选：跨境关税估算 / 匿名收件 / 慈善捐赠。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -120,9 +393,24 @@ 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（可选，如果是通过推荐链接来的）',
+                    description: '推荐人的 api_key（可选）。⚠️ 仅记 L1（直接推荐人，70% commission）；L2/L3 无法经 MCP 推断，会按 region 规则 redirect（singapore 等高 max_levels → charity chain_gap；global max_levels=1 → global_fund region cap）。完整 7:2:1 三级链需买家经 webaz_share_link 生成的 ?ref= URL 浏览器点击（建 product_share_attribution）。',
+                },
+                // B2 隐私购物
+                anonymous_recipient: {
+                    type: 'boolean',
+                    description: '【B2】匿名收件：系统生成 PR-XXXXX 代号代替真实姓名（卖家面单只见代号 + 地址）',
+                },
+                // B5 公益捐赠（按订单总额百分比，定额选项防机器人滥用）
+                donation_pct: {
+                    type: 'number',
+                    enum: [0, 0.005, 0.01, 0.02, 0.05],
+                    description: '【B5】随单捐赠占订单金额的比例（0 / 0.5% / 1% / 2% / 5%）。捐赠金额另行计算并入 charity_fund，订单完成后落账。',
                 },
             },
             required: ['api_key', 'product_id', 'shipping_address'],
@@ -130,22 +418,25 @@ const TOOLS = [
     },
     {
         name: 'webaz_update_order',
-        description: `更新订单状态（每个角色只能执行自己的操作）。
+        description: `Update order status (each role can only perform their own actions).
+
+Seller actions:
+- accept:  accept order (within 24h of payment)
+- ship:    confirm dispatch (needs tracking number, within promised handling time)
 
-卖家可执行的 action：
-- accept：接受订单（付款后 24h 内必须执行）
-- ship：确认发货（需要物流单号，接单后按承诺时间内执行）
+Logistics actions:
+- pickup:  confirm parcel pickup (within 48h of ship)
+- transit: update to in-transit
+- deliver: confirm delivery (needs delivery proof description)
 
-物流方可执行的 action：
-- pickup：确认揽收包裹（发货后 48h 内）
-- transit：更新为运输中
-- deliver：确认投递完成（需要投递证明描述）
+Buyer actions:
+- confirm: confirm receipt → triggers fund settlement
+- dispute: raise dispute (needs reason; freezes funds pending arbitration)
 
-买家可执行的 action：
-- confirm：确认收货，触发资金结算
-- dispute：发起争议（需要说明原因，会冻结资金等待仲裁）
+If a deadline is missed, protocol auto-marks that party as in default.
 
-超过截止时间未操作，协议会自动判定该方违约。`,
+──
+中文：更新订单状态 — 角色专属 action（卖家 accept/ship · 物流 pickup/transit/deliver · 买家 confirm/dispute）。截止超时自动判违约。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -167,9 +458,12 @@ const TOOLS = [
     },
     {
         name: 'webaz_get_status',
-        description: `查询订单的当前状态、完整历史记录和当前责任方。
-需要参与该订单的 api_key（买家、卖家或物流方均可查询）。
-返回：当前状态、状态历史（谁在什么时候做了什么）、当前应该由谁操作、截止时间。`,
+        description: `Query order status, full history, and current responsible party.
+Requires api_key of an order participant (buyer / seller / logistics may all query).
+Returns: current status, status history (who did what when), next responsible actor, deadline.
+
+──
+中文：查订单状态 + 历史 + 当前责任方 + 截止时间。任一参与方可查。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -181,21 +475,40 @@ const TOOLS = [
     },
     {
         name: 'webaz_wallet',
-        description: `查看自己的钱包余额和收益统计。
-返回：可用余额、质押中金额、托管中金额、累计总收益。`,
+        description: `Wallet query (balance + earnings stats + deposit/withdrawal/income history).
+
+Actions:
+- view         available balance + staked + in-escrow + total earnings + reputation tier (default)
+- deposits     last 10 on-chain deposit records (tx_hash / amount / block_number)
+- withdrawals  last 10 withdrawal requests (with status / tx_hash)
+- income       income breakdown: referral L1/L2/L3 + binary PV matching + sales net
+
+NOTE: actual withdrawals / deposits / whitelist management require Passkey + email OTP via PWA Web only.
+This is a security boundary — agents CANNOT bypass it. Use this tool for read-only queries only.
+
+──
+中文：钱包查询（余额/收益/充提历史）。仅查询用，实际充提需 PWA Web + Passkey + 邮件 OTP，agent 不可绕过。`,
         inputSchema: {
             type: 'object',
             properties: {
                 api_key: { type: 'string', description: '你的 api_key' },
+                action: {
+                    type: 'string',
+                    enum: ['view', 'deposits', 'withdrawals', 'income'],
+                    description: '操作类型（缺省 = view）',
+                },
             },
             required: ['api_key'],
         },
     },
     {
         name: 'webaz_notifications',
-        description: `查询当前用户的通知消息（L2-6 通知系统）。
-Agent 应定期调用此工具检查是否有待处理的订单事件。
-每次有状态变更（新订单/发货/争议等），相关参与方都会收到通知。`,
+        description: `Query user notifications (L2-6 notification system).
+Agents should poll this periodically to check for pending order events.
+Every status change (new order / ship / dispute / etc.) notifies relevant participants.
+
+──
+中文：查通知 — agent 定期调用检查待处理事件（新订单/发货/争议等会通知所有相关方）。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -208,72 +521,168 @@ Agent 应定期调用此工具检查是否有待处理的订单事件。
     },
     {
         name: 'webaz_dispute',
-        description: `管理争议流程（L3 争议系统）。
-
-当买家认为货不对版、货损、卖家欺诈时，可通过 webaz_update_order action=dispute 发起争议，
-然后用本工具进行后续操作。
-
-协议保障机制（无需人工干预）：
-- 被诉方有 48 小时提交反驳证据，否则协议自动判发起方胜诉
-- 仲裁员有 120 小时做出裁定，否则协议默认退款给买家
-- 裁定一旦执行，资金立即自动分配，无法撤销
-
-action 说明：
-- view：查看争议详情（任何参与方可调用）
-- list_open：查看所有待处理争议（仅仲裁员）
-- respond：被诉方提交反驳证据（必须在 48h 截止时间前）
-- arbitrate：仲裁员做出裁定并执行资金处置
-
-ruling 裁定选项（arbitrate 时使用）：
-- refund_buyer：全额退款给买家，扣押卖家部分保证金
-- release_seller：资金释放给卖家（卖家胜诉）
-- partial_refund：部分退款（需指定 refund_amount）；若责任在第三方（如物流），同时指定 liable_party（责任方 user_id），此时卖家全额结算，赔偿金从责任方扣除`,
+        description: `Manage dispute lifecycle (L3 dispute system).
+
+When buyer claims item-not-as-described / damaged / seller fraud, first raise dispute via webaz_update_order action=dispute,
+then use this tool for follow-ups.
+
+Protocol guarantees (no human intervention):
+- Respondent has 48h to submit rebuttal evidence, else protocol auto-judges in initiator's favor
+- Arbitrator has 120h to issue ruling, else protocol defaults to refund-buyer
+- Once executed, ruling fund movement is instant and irreversible
+
+Actions:
+- view:         view dispute details (any participant)
+- list_open:    list all pending disputes (arbitrators only)
+- respond:      respondent submits rebuttal evidence (before 48h deadline)
+- add_evidence: any participant (incl. logistics) submits supplementary evidence (Wave 3)
+- arbitrate:    arbitrator issues ruling + executes fund disposition (must be assigned arbitrator)
+
+Ruling options (when arbitrate):
+- refund_buyer:    full refund to buyer + partial stake forfeit from seller
+- release_seller:  release funds to seller (seller wins)
+- partial_refund:  partial refund (needs refund_amount); if third-party fault, set liable_party (user_id) → seller settled full, compensation deducted from liable party
+- liability_split: distributed liability (Wave 3) — needs liability_parties: [{user_id, amount}] for proportional stake deductions
+
+─────────────────────
+⚠️ Iron-Rule boundary (spec §4): arbitrate is a protocol iron-rule node requiring arbitrator to complete Passkey re-confirmation via PWA Web UI.
+Direct agent calls return 412 HUMAN_PRESENCE_REQUIRED — DO NOT retry; instead, guide the user to the browser.
+view / list_open / respond / add_evidence can be agent-proxied; only arbitrate needs human.
+
+──
+中文：管理争议（L3）。Actions: view / list_open / respond / add_evidence (agent 可代) · arbitrate (需 PWA + Passkey 人工)。被诉方 48h 反驳，仲裁员 120h 裁定，超时自动判。`,
         inputSchema: {
             type: 'object',
             properties: {
                 api_key: { type: 'string', description: '操作者的 api_key' },
                 action: {
                     type: 'string',
-                    enum: ['view', 'list_open', 'respond', 'arbitrate'],
+                    enum: ['view', 'list_open', 'respond', 'add_evidence', 'arbitrate'],
                     description: '要执行的操作',
                 },
-                dispute_id: { type: 'string', description: '争议 ID（respond/arbitrate 时必填，view 时与 order_id 二选一）' },
+                dispute_id: { type: 'string', description: '争议 ID（respond/add_evidence/arbitrate 时必填，view 时与 order_id 二选一）' },
                 order_id: { type: 'string', description: '订单 ID（view 时可替代 dispute_id）' },
                 notes: { type: 'string', description: '回应说明 / 反驳理由（respond 时填写）' },
-                evidence_description: { type: 'string', description: '证据描述（respond 时建议填写）' },
+                evidence_description: { type: 'string', description: '证据描述（respond/add_evidence 时填写）' },
                 ruling: {
                     type: 'string',
-                    enum: ['refund_buyer', 'release_seller', 'partial_refund'],
+                    enum: ['refund_buyer', 'release_seller', 'partial_refund', 'liability_split'],
                     description: '裁定结果（arbitrate 时必填）',
                 },
                 refund_amount: { type: 'number', description: '部分退款金额，仅 ruling=partial_refund 时使用' },
                 liable_party: { type: 'string', description: '第三方责任方 user_id（partial_refund 时可选）：指定后赔偿金从该方扣除，卖家全额结算' },
+                liability_parties: {
+                    type: 'array',
+                    description: '责任分配数组（liability_split 时必填），每项 { user_id: string, amount: number }',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            user_id: { type: 'string', description: '责任方 user_id' },
+                            amount: { type: 'number', description: '该责任方需承担的金额（WAZ）' },
+                        },
+                        required: ['user_id', 'amount'],
+                    },
+                },
                 ruling_reason: { type: 'string', description: '裁定理由（arbitrate 时必填，将永久记录在链上）' },
             },
             required: ['api_key', 'action'],
         },
     },
+    {
+        name: 'webaz_claim_verify',
+        description: `Crowd-sourced claim verification — no central arbitrator, 3 eligible verifiers reach consensus by vote.
+
+When to use:
+- Buyer:   suspects a seller's product claim (e.g. "brand new sealed", "ships within 24h") → wants decentralized verification
+- Seller:  defends against an opened verification by submitting counter-evidence → extends task by 24h
+- Verifier: browses open tasks, votes on eligible ones (pass/fail/no_fault/abstain), settles on 3rd vote
+
+Actions:
+[Buyer]
+- create   open a verification on your own order's claim (locks 10 WAZ stake; order must be paid/delivered, NOT completed; settles when 3 votes collected)
+- view     task details (visible to participants + voters + eligible verifiers)
+- mine     all my tasks (buyer + seller + verifier perspectives)
+
+[Seller]
+- submit_seller_evidence  submit rebuttal → +24h extension, task stays open
+
+[Verifier — gated by 7-condition eligibility, NOT just read-only]
+- available             list open tasks I can take (REQUIRES eligibility: age≥60d / email verified / ≥20 completed orders / 0 arbitration losses / never suspended / wallet ≥200 WAZ / reputation ≥110)
+- vote                  vote on a task (pass / fail / no_fault / abstain)
+                        pass     = seller's claim is true / product OK
+                        fail     = seller's claim is false / product mismatch
+                        no_fault = neither party clearly at fault (dispute has merit but inconclusive)
+                        abstain  = "not my expertise, skipping" — not counted in 3-vote consensus, doesn't affect accuracy (V3 right-to-decline)
+
+[Become Verifier]
+- eligibility           check my qualification status (reputation signals)
+- verifier_status       my quota / tier / stake
+- apply                 apply to verifier whitelist (needs reputation + stake lock)
+- withdraw_application  withdraw application, refund stake
+- appeal                appeal a suspension (only when suspended)
+
+─────────────────────
+⚠️ Iron-Rule boundary (spec §4): vote is a protocol iron-rule node requiring verifier to complete Passkey re-confirmation via PWA Web UI.
+Direct agent calls to vote return 412 HUMAN_PRESENCE_REQUIRED — DO NOT retry; instead, guide the user to the browser.
+Other actions (create / view / mine / available / eligibility / apply / appeal etc.) can be agent-proxied; only vote needs human.
+
+──
+中文：众包索赔验证 — 3 verifier 共识投票判定。买家创建、卖家反证、verifier 投票。仅 vote 需 PWA + Passkey 人工，其他 actions agent 可代。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: '你的 api_key' },
+                action: {
+                    type: 'string',
+                    enum: ['create', 'view', 'mine', 'submit_seller_evidence', 'available', 'vote', 'eligibility', 'verifier_status', 'apply', 'withdraw_application', 'appeal'],
+                    description: '要执行的操作',
+                },
+                // create
+                order_id: { type: 'string', description: '订单 ID（create 时必填）。订单状态须在 paid/delivered（completed 终态不可发起）' },
+                claim_target: {
+                    type: 'string',
+                    enum: ['price', 'commission', 'protection', 'return', 'warranty', 'handling', 'other'],
+                    description: '声明对象（create 时必填）。7 类: price（价格争议）/ commission（佣金）/ protection（买家保护）/ return（退货）/ warranty（保修）/ handling（履约时效）/ other',
+                },
+                claim_text: { type: 'string', description: '声明文本 6-500 字（create 时必填）。create 会锁定 10 WAZ 防 spam（无责败诉退回）' },
+                evidence_uri: { type: 'string', description: '证据 URI（create/vote/submit_seller_evidence 可选；buyer 自带 / verifier 附证据 / seller 反驳证据）' },
+                // view / vote / submit_seller_evidence
+                task_id: { type: 'string', description: '任务 ID（view / vote / submit_seller_evidence 时必填）' },
+                // vote
+                vote: { type: 'string', enum: ['pass', 'fail', 'no_fault', 'abstain'], description: 'vote 时必填；abstain = 不熟悉弃投（V3）' },
+                note: { type: 'string', description: '投票说明（vote 可选，≤500 字）' },
+                // appeal
+                reason: { type: 'string', description: '申诉理由（appeal 时必填，≤500 字）' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
     {
         name: 'webaz_skill',
-        description: `L4-4 Skill 市场——让卖家发布可复用的 Agent 能力插件，买家 Agent 一键订阅。
-
-Skill 是解决冷启动的核心机制：现有 Amazon/Shopify 卖家零成本接入 WebAZ，
-买家 Agent 订阅后可自动发现、优先呈现这些卖家的商品，成交后 Skill 发布者获得推荐佣金。
-
-Skill 类型（skill_type）：
-- catalog_sync      目录同步：将外部店铺（Amazon/Shopify/自定义）接入 WebAZ 搜索，买家订阅后优先看到
-- auto_accept       自动接单：买家下单后立即接受，无需等待（config: min_amount, max_amount, max_daily_orders）
-- price_negotiation 价格协商：允许 Agent 在限定范围内议价（config: max_discount_pct, min_quantity）
-- quality_guarantee 质量承诺：额外质押保证金，问题可额外赔偿（config: guarantee_amount, coverage_days）
-- instant_ship      极速发货：承诺 24h 内发货（config: ship_within_hours）
-
-action 说明：
-- list        浏览 Skill 市场（无需登录）
-- publish     发布新 Skill（仅卖家）
-- subscribe   订阅 Skill（买家订阅后可获得额外好处）
-- unsubscribe 取消订阅
-- my_skills   查看自己发布的 Skill（卖家）
-- my_subs     查看自己订阅的 Skill（买家）`,
+        description: `L4-4 Skill marketplace — sellers publish reusable seller-side behaviour configs; buyer Agents subscribe with one click.
+
+⚠️ Important — Skill is NOT executable code distribution. There are exactly 5 typed Skill kinds (below), each accepts only **structured config parameters** (numbers / enums / amounts). There is NO path for an Agent to download and run arbitrary third-party code via this marketplace. Subscribing = setting a flag + data binding, not installing a plugin. (Common Web2 "plugin marketplace" risk model does NOT apply here.)
+
+Skill is WebAZ's cold-start mechanism: existing Amazon/Shopify sellers integrate with zero cost,
+buyer agents subscribe and auto-discover those sellers' products with priority; on sale, the Skill publisher earns referral commission.
+
+Skill types (typed, NOT free-form code):
+- catalog_sync      sync external store (Amazon/Shopify/custom) into WebAZ search → subscribers see priority
+- auto_accept       auto-accept incoming orders, no wait (config: min_amount, max_amount, max_daily_orders)
+- price_negotiation allow Agent-side haggling within limits (config: max_discount_pct, min_quantity)
+- quality_guarantee extra stake for issue compensation (config: guarantee_amount, coverage_days)
+- instant_ship      guarantee 24h dispatch (config: ship_within_hours)
+
+Actions:
+- list        browse Skill marketplace (no auth)
+- publish     publish new Skill (sellers only)
+- subscribe   subscribe to a Skill (buyer perks)
+- unsubscribe cancel subscription
+- my_skills   my published Skills (seller view)
+- my_subs     my subscribed Skills (buyer view)
+
+──
+中文：Skill 市场 — 卖家发布 agent 能力插件（catalog_sync / auto_accept / price_negotiation / quality_guarantee / instant_ship），买家 agent 订阅。Actions: list / publish / subscribe / unsubscribe / my_skills / my_subs。`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -306,731 +715,3146 @@ action 说明：
     },
     {
         name: 'webaz_mykey',
-        description: 'Recover your api_key by name, or view your profile and roles. Use this if you forgot your api_key.',
+        description: `Confirm account existence by handle + permanent_code. Returns redacted api_key hint only — full api_key disclosure requires PWA + Passkey verification (Iron-Rule).
+
+Rate-limited: 5 attempts per handle per hour. Excessive failures lock the handle for 1 hour.
+
+Returns:
+- found: boolean
+- api_key_hint (e.g. "key_7d3d***faa7b") — confirms which account, never the full key
+- full_api_key_recovery — instructions to use PWA for the real recovery
+
+──
+中文：handle + permanent_code 双因素确认账户存在，仅返回 redact 过的 api_key_hint。完整 api_key 必须经 PWA + Passkey 二次验证（Iron-Rule）。同 handle 每小时最多 5 次。`,
         inputSchema: {
             type: 'object',
             properties: {
-                name: { type: 'string', description: 'The name you registered with' },
+                handle: { type: 'string', description: 'Unique handle assigned at registration (check handle_modified flag if name was taken)' },
+                permanent_code: { type: 'string', description: '6-char recovery code from registration response (uppercase)' },
             },
-            required: ['name'],
+            required: ['handle', 'permanent_code'],
         },
     },
     {
         name: 'webaz_profile',
-        description: 'View your profile, manage roles (add a new role or switch active role). One account can hold multiple roles.',
+        description: `View your own profile / manage roles, AND view any user's public profile + content streams (个人主页内容流).
+
+Self actions (need api_key):
+- view        show your profile & wallet & api_key hint
+- add_role    add a new role
+- switch_role switch active role (one account can hold multiple roles)
+
+Public-profile actions:
+- view_user   another user's public profile (user_id = usr_xxx / permanent_code / @handle; needs api_key)
+- feed        a user's content stream (user_id + feed). feed options:
+              secondhand | auctions | reviews | products | shares | reputation | pv | liked
+              (secondhand/auctions/reviews/products/shares/reputation are public;
+               pv needs api_key; liked is owner-only and needs your own api_key)
+
+──
+中文：看自己资料/管角色，也能看他人公开主页 + 内容流（二手/拍卖/测评/商品/笔记/信誉/PV/点赞）。Actions: view / add_role / switch_role / view_user / feed。`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key（view/add_role/switch_role/view_user 必填；公开 feed 可省略）' },
                 action: {
                     type: 'string',
-                    enum: ['view', 'add_role', 'switch_role'],
-                    description: 'view: show profile & api_key | add_role: add a new role | switch_role: switch active role',
+                    enum: ['view', 'add_role', 'switch_role', 'view_user', 'feed'],
+                    description: 'view/add_role/switch_role = 自己；view_user/feed = 看他人主页/内容流',
                 },
                 role: {
                     type: 'string',
                     enum: ['buyer', 'seller', 'logistics', 'arbitrator'],
                     description: 'Role to add or switch to (required for add_role / switch_role)',
                 },
+                user_id: { type: 'string', description: '目标用户：usr_xxx / 永久码 / @handle（view_user / feed 时必填）' },
+                feed: {
+                    type: 'string',
+                    enum: ['secondhand', 'auctions', 'reviews', 'products', 'shares', 'reputation', 'pv', 'liked'],
+                    description: '内容流类型（feed 时必填）',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'webaz_revoke_key',
+        description: `Initiate api_key revocation. Iron-Rule: actual revocation requires PWA + Passkey confirmation — MCP only registers the intent and returns the PWA URL where you finish the action.
+
+Use when:
+- Your api_key was leaked or you suspect unauthorized access
+- You are decommissioning an agent / device
+
+After PWA confirmation, the old api_key returns 401 on all tools. Plan ahead: have a new key (via webaz_rotate_key) before revoking, or you lose access.
+
+──
+中文：发起 api_key 吊销。Iron-Rule：真正吊销必须 PWA + Passkey 二次确认（agent 不能单方面执行不可逆操作）。MCP 仅登记意图，返回 PWA 确认 URL。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your current api_key (the one to revoke)' },
+                reason: { type: 'string', description: 'Optional: leaked / lost_device / rotation / unspecified' },
+            },
+            required: ['api_key'],
+        },
+    },
+    {
+        name: 'webaz_rotate_key',
+        description: `Initiate api_key rotation (invalidate old key + issue new one). Iron-Rule: requires PWA + Passkey confirmation. After PWA confirms, old key returns 401 and new key is shown once — store immediately.
+
+Safer than webaz_revoke_key because issuance is atomic with invalidation — no access gap.
+
+──
+中文：发起 api_key 轮换（旧 key 失效 + 新 key 同时签发）。比 revoke 安全，原子操作无访问中断。需 PWA + Passkey。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your current api_key (will be invalidated after PWA confirm)' },
+                reason: { type: 'string', description: 'Optional: rotation / leaked / scheduled' },
+            },
+            required: ['api_key'],
+        },
+    },
+    {
+        name: 'webaz_referral',
+        description: `View your full referral status: 3-tier commission (推土机) team + earnings + invite links + binary PV matching (原子能) tree + tier progress + L1 share permission gate. Use this to know how to promote and what you have earned.
+
+⚠️ Commission structure involves multi-tier referral + binary pairing tree which may overlap with MLM legal definitions in many jurisdictions (see webaz_info.commission_model.compliance_notice). Agents acting on behalf of a human user MUST get the user's explicit consent before generating referral links or promoting on their behalf. Do NOT auto-recruit.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your api_key' },
+            },
+            required: ['api_key'],
+        },
+    },
+    {
+        name: 'webaz_share_link',
+        description: `Generate a product share link with your referral attached. Open this in any social platform (TikTok / WeChat / Telegram). Whoever clicks and registers/buys will count toward your 3-tier commission (if you are verified buyer) and PV tree.
+
+⚠️ This tool builds the referral chain. Generating a link is taking an active promotion step in a multi-tier commission + binary pairing structure (see webaz_info.commission_model.compliance_notice — may overlap with MLM legal definitions). Agents acting for a human user MUST get explicit consent before calling this on their behalf. Do NOT auto-generate.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your api_key' },
+                product_id: { type: 'string', description: 'Product to promote (from webaz_search)' },
+                side: {
+                    type: 'string',
+                    enum: ['left', 'right', 'auto'],
+                    description: 'Which side of your binary tree the new user lands. auto = weaker leg (default)',
+                },
+            },
+            required: ['api_key', 'product_id'],
+        },
+    },
+    {
+        name: 'webaz_blocklist',
+        description: `Manage your blocklist of sellers/users. Blocked users' products are auto-hidden from your searches.
+
+Scope (元规则 #5 不偏袒 design):
+- ✓ Hides blocked user's products from YOUR search results
+- ✓ Prevents YOU from following them (webaz_follows respects this)
+- ✗ Does NOT prevent placing orders on their products (商品发布即承诺销售 — public listing = sales commitment)
+- ✗ Does NOT silence existing chat conversations (business context overrides)
+- ✗ Does NOT prevent NEW chat starts on shared order/rfq context
+- For active rejection: delist products, don't bid on RFQs, or cancel the order.
+
+Returns the action result.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your api_key' },
+                action: { type: 'string', enum: ['list', 'block', 'unblock'], description: 'list: my blocked users | block: add | unblock: remove' },
+                user_id: { type: 'string', description: 'Target user id (required for block/unblock)' },
+                reason: { type: 'string', description: 'Optional reason for block (e.g. "fake product", "abuse")' },
             },
             required: ['api_key', 'action'],
         },
     },
-];
-// ─── 工具处理函数 ─────────────────────────────────────────────
-function handleInfo() {
-    const summary = getManifestSummary();
-    const stats = (() => {
-        try {
-            const users = db.prepare("SELECT COUNT(*) as n FROM users WHERE id != 'sys_protocol'").get().n;
-            const products = db.prepare("SELECT COUNT(*) as n FROM products WHERE status='active'").get().n;
-            const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE status='completed'").get().n;
-            return { participants: users, active_products: products, completed_orders: completed };
-        }
-        catch {
-            return null;
-        }
-    })();
-    return {
-        ...summary,
-        description: 'WebAZ 是一个去中心化商业协议。每笔交易通过状态机流转，每个状态转移都需要对应责任方的操作证明。任何超时未操作，协议自动判定该方违约并执行处置。',
-        live_stats: stats,
-        roles: {
-            buyer: '下单、付款、确认收货或发起争议',
-            seller: '上架商品、接单、按时发货（质押保证金确保履约）',
-            logistics: '揽收包裹、更新运输状态、确认投递（获得 5% 物流费）',
-            arbitrator: '处理争议，做出裁定（120h 内必须裁定，否则系统自动退款买家）',
+    {
+        name: 'webaz_follows',
+        description: 'Follow/unfollow users for the social feed. Or list your followers / following. Helps agents build the user\'s social graph.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your api_key' },
+                action: { type: 'string', enum: ['list', 'follow', 'unfollow', 'status'], description: 'list: my follows + followers | follow/unfollow: change relation | status: check if I follow a user' },
+                user_id: { type: 'string', description: 'Target user (required for follow/unfollow/status)' },
+            },
+            required: ['api_key', 'action'],
         },
-        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)',
-            logistics: '1. webaz_register(role=logistics) → 2. webaz_update_order(pickup) → webaz_update_order(deliver)',
+    },
+    {
+        name: 'webaz_nearby',
+        description: 'Query anonymized nearby (~11km cell) purchase aggregation. k-anonymity ≥ 3 privacy guard. Or set/clear your coarse geo location (0.1° = 11km precision, never stores exact GPS).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your api_key' },
+                action: { type: 'string', enum: ['query', 'set_location', 'clear_location'], description: 'query: get aggregated nearby activity | set_location: set your geo cell | clear_location: remove' },
+                lat: { type: 'number', description: 'Latitude -90..90 (for set_location, auto-truncated to 0.1°)' },
+                lng: { type: 'number', description: 'Longitude -180..180 (for set_location, auto-truncated to 0.1°)' },
+            },
+            required: ['api_key', 'action'],
         },
-        available_tools: TOOLS.map((t) => ({ name: t.name, description: t.description.split('\n')[0] })),
-        full_manifest: `读取 MCP Resource "${MANIFEST_URI}" 获取完整协议规范（状态机/经济模型/争议系统/Skill 市场/声誉系统）`,
-    };
-}
-function handleRegister(args) {
-    const name = args.name;
-    const role = args.role;
-    const initialBalance = args.initial_balance ?? 1000;
-    const validRoles = ['buyer', 'seller', 'logistics', 'reviewer', 'arbitrator'];
-    if (!validRoles.includes(role)) {
-        return { error: `无效角色：${role}。可选：${validRoles.join(', ')}` };
-    }
-    const id = generateId('usr');
-    const apiKey = generateId('key');
-    db.prepare('INSERT INTO users (id, name, role, roles, api_key) VALUES (?, ?, ?, ?, ?)').run(id, name, role, JSON.stringify([role]), apiKey);
-    db.prepare('INSERT INTO wallets (user_id, balance) VALUES (?, ?)').run(id, initialBalance);
-    return {
-        success: true,
-        message: `注册成功！请妥善保管你的 api_key，这是你在协议中的唯一身份凭证。`,
-        user_id: id,
-        name,
-        role,
-        api_key: apiKey,
-        initial_balance: initialBalance,
-        next_step: role === 'seller'
-            ? '现在可以用 webaz_list_product 上架你的第一件商品'
-            : role === 'buyer'
-                ? '现在可以用 webaz_search 搜索商品'
-                : '等待订单分配给你',
-    };
-}
-function handleSearch(args) {
-    const query = args.query ?? '';
-    const category = args.category;
-    const maxPrice = args.max_price;
-    const limit = args.limit ?? 10;
-    let sql = `
-    SELECT p.*, u.name as seller_name
-    FROM products p
-    JOIN users u ON p.seller_id = u.id
-    WHERE p.status = 'active' AND p.stock > 0
-  `;
-    const params = [];
-    if (query) {
-        sql += ` AND (p.title LIKE ? OR p.description LIKE ?)`;
-        params.push(`%${query}%`, `%${query}%`);
-    }
-    if (category) {
-        sql += ` AND p.category = ?`;
-        params.push(category);
-    }
-    if (maxPrice !== undefined) {
-        sql += ` AND p.price <= ?`;
+    },
+    {
+        name: 'webaz_default_address',
+        description: `Read or set your default shipping address. Used to auto-filter unshippable products in search + fallback when webaz_rfq/place_order omits shipping_address.
+
+⚠️ set 仅接受 2 个字段：text（自由格式地址字符串）+ region（可选；用于 unshippable 过滤）。
+不接受 structured 字段（recipient/line1/city/country/phone 等）— 跟传统电商地址 API 不同，agent 必须自己拼接。
+
+──
+中文：读取/设置默认收货地址。set 需要 text 必填 + region 可选；不收 structured 字段。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your api_key' },
+                action: { type: 'string', enum: ['read', 'set'], description: 'read: get current default | set: update' },
+                text: { type: 'string', description: 'Full address as free-text string (e.g. "John Doe / 1 Test St / Singapore SG / +65 12345678"). Required for set. ≤ 200 chars.' },
+                region: { type: 'string', description: 'Region tag for shipping match (e.g. "global", "china", "SG"). Optional for set. ≤ 40 chars.' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
+    {
+        name: 'webaz_shareables',
+        description: 'Manage your external content "shareables" (YouTube / TikTok / 小红书 / B 站 / IG / Twitter links bound to a product or anchor). WebAZ indexes only the URL, never the content bytes. Or query by product_id / anchor.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: 'Your api_key' },
+                action: { type: 'string', enum: ['list_mine', 'add', 'delete', 'by_product', 'by_anchor'], description: 'list_mine | add (need external_url + product/anchor) | delete | by_product | by_anchor' },
+                external_url: { type: 'string', description: 'For action=add' },
+                title: { type: 'string', description: 'For action=add (optional)' },
+                description: { type: 'string', description: 'For action=add (optional)' },
+                related_product_id: { type: 'string', description: 'For action=add or by_product' },
+                related_anchor: { type: 'string', description: 'For action=add or by_anchor' },
+                shareable_id: { type: 'string', description: 'For action=delete' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
+    // ── P3 RFQ / bid / chat / auto_bid（MCP 通过 HTTP 调 PWA，复用所有校验+状态机）────
+    {
+        name: 'webaz_rfq',
+        description: `RFQ (Request-for-Quotation) — buyer posts demand, sellers bid within a time window.
+
+Actions:
+- create (buyer):  publish RFQ; needs title/qty/max_price/category/urgency/award_mode
+- mine (buyer):    my RFQ list
+- browse (seller): board view (filter by region/category/urgency/unbidded)
+- detail:          full detail (buyer sees all bids; seller sees only own)
+- award (buyer):   pick winner (pass bid_id for manual; omit for auto-lowest)
+- cancel (buyer):  cancel (only if no bid awarded; 30% deposit forfeited)
+
+Economics:
+- Buyer deposit = clamp(0.1, 1) of (max_price × qty × 0.01)  — i.e. 1% capped at 1 WAZ (anti-spam, NOT anti-fraud; real anti-fraud is 30% cancel penalty)
+- No-max-price RFQ deposit = 0.1 WAZ flat
+- Seller bid stake = max(0.5, price × qty × 0.05)  — 5% with floor 0.5 WAZ
+- Cancel before award: 30% deposit forfeit to charity_fund
+- Award winner → standard order lifecycle, BUT with snapshot_commission_rate = 0 (RFQ orders 0% commission — direct deal between buyer/seller, no promoter chain to compensate). Seller gets price minus protocol_fee (2%) and fund_base (1%); no L1/L2/L3 dilution.
+- Seller bid stake (4.5+ WAZ) becomes bid_stake_held on the order; released to seller balance on successful complete; 50/50 split to buyer+sys_protocol on fault_seller (settleFault).
+- Window defaults: now=15min / today=60min / flex=1440min(24h)
+
+Shipping address: if omitted, falls back to webaz_default_address (set via that tool first).
+
+──
+中文：求购单 RFQ。买家押金 1%（封顶 1 WAZ，仅防 spam）；卖家 bid stake 5%（最少 0.5 WAZ）；撤单扣 30% 入慈善池。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: '你的 api_key' },
+                action: { type: 'string', enum: ['create', 'mine', 'browse', 'detail', 'award', 'cancel'] },
+                // create
+                title: { type: 'string' },
+                qty: { type: 'number' },
+                max_price: { type: 'number', description: 'WAZ 预算上限（可选；不填时 buyer 押金为 1 WAZ）' },
+                category: { type: 'string', enum: ['standard', 'general', 'highvalue', 'restricted'] },
+                urgency: { type: 'string', enum: ['now', 'today', 'flex'] },
+                award_mode: { type: 'string', enum: ['manual', 'first_match', 'time_window'] },
+                award_window_min: { type: 'number' },
+                notes: { type: 'string' },
+                shipping_address: { type: 'string', description: '可选；缺省取 buyer 默认地址' },
+                // browse filters
+                region: { type: 'string' },
+                unbidded: { type: 'boolean' },
+                // detail/award/cancel
+                rfq_id: { type: 'string' },
+                bid_id: { type: 'string', description: 'award 时可选 — 不传则自动选当前最低价' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
+    {
+        name: 'webaz_bid',
+        description: `Bid on RFQs (seller-side).
+Actions:
+- submit:    new bid; needs rfq_id + price + qty_offered + fulfillment_type; optional eta_hours/note
+- patch:     edit price/ETA/fulfillment/note (only active; stake delta auto-settled)
+- cancel:    withdraw (only active; deposit released immediately)
+- list_mine: full bid history
+
+──
+中文：对 RFQ 报价（卖家）。Actions: submit / patch / cancel / list_mine。改价时 stake 自动结算差额。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: '卖家 api_key' },
+                action: { type: 'string', enum: ['submit', 'patch', 'cancel', 'list_mine'] },
+                rfq_id: { type: 'string' },
+                bid_id: { type: 'string' },
+                price: { type: 'number' },
+                qty_offered: { type: 'number' },
+                eta_hours: { type: 'number' },
+                fulfillment_type: { type: 'string', enum: ['instant_pickup', 'same_day', 'next_day', 'standard'] },
+                note: { type: 'string' },
+                offer_id: { type: 'string', description: '可选；引用已有 offer 商品' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
+    {
+        name: 'webaz_chat',
+        description: `Context-bound DM (no open DM — only order / rfq / listing_qa contexts allowed).
+Actions:
+- start:     open conversation — needs kind + context_id (for rfq, also recipient_id)
+- list:      my conversation list
+- read:      read messages (last 50; flag_reasons is array)
+- send:      send message (anti-scam regex; matches get flagged=true but still delivered; flag_reasons is array)
+- mark_read: mark as read
+- block:     block this specific conversation (sets conv.status=blocked; ≠ webaz_blocklist which hides from search)
+
+Anti-scam regex names (returned in flag_reasons array):
+phone_cn (CN mobile 11-digit), wechat (微信/vx/wechat/weixin), alipay (支付宝/alipay),
+qq (qq:digits), bank_card (16-19 consecutive digits), telegram (@handle/t.me/telegram),
+external_url (any http(s) URL except localhost/webaz.app/webaz.io).
+
+Rate limits (PWA-enforced):
+- Short-term: 60 messages / minute / user
+- AGENT_DAILY_CAP (reset at UTC midnight): new=30, trusted=100, quality=300, legend=1000
+  (returns 429 + error_code=AGENT_DAILY_CAP + cap + used + level fields)
+  3 overruns/day → auto agent warning strike.
+
+Behavior note: webaz_blocklist hides target from your search; per-conversation block (this tool's "block")
+silences the specific conv. Existing conversations are NOT auto-silenced by webaz_blocklist
+(business context overrides — block prevents future ad-hoc contact but keeps active deal channels open).
+
+──
+中文：上下文私聊 — 仅 order/rfq/listing_qa 三种场景可发起，无自由 DM。Actions: start / list / read / send / mark_read / block。
+反诈 regex 7 类 + 60/min rate limit。blocklist 不影响已建立 conversation（商业上下文优先）。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string' },
+                action: { type: 'string', enum: ['start', 'list', 'read', 'send', 'mark_read', 'block'] },
+                kind: { type: 'string', enum: ['order', 'rfq', 'listing_qa'] },
+                context_id: { type: 'string' },
+                recipient_id: { type: 'string' },
+                conversation_id: { type: 'string' },
+                body: { type: 'string', description: 'send action 的消息正文 (≤ 2000 字)' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
+    {
+        name: 'webaz_price_history',
+        description: `Product historical sale price + volume distribution — helps agents avoid bottom-price dumping bait.
+Returns:
+- windows: { d30, d90, lifetime } each {sales, volume, avg, median, p25, p75}
+- price_buckets: distribution array [{price, count, qty, pct}]
+- daily_avg: 30-day daily avg price trend [{date, sales, avg}]
+- category_avg_30d: same-category 30-day average
+- anomaly_flags: ('current_below_70pct_median' / 'far_below_category_avg' / 'far_above_category_avg')
+Returns insufficient_data:true when data sparse.
+
+──
+中文：商品历史成交价 + 量分布 — 防底价倾销。返回多时窗统计 + 价位分布 + 同类均价 + 异常预警。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product_id: { type: 'string', description: '商品 ID' },
+            },
+            required: ['product_id'],
+        },
+    },
+    {
+        name: 'webaz_charity',
+        description: `Charity wish pool + repayment + community fund — double-anonymous + dual-signed anchoring + isolated prestige.
+Actions:
+- list:        browse public wishes (filter by category/target_kind; anonymous accessible)
+- detail:      single wish details (commit_hash + fulfillment + repayments)
+- create:      (auth) publish a wish
+- claim:       (auth) fulfiller claims (1:1 exclusive; 30-day self-claim lock; auto-release if no proof in 48h)
+- proof:       (auth) submit completion evidence
+- confirm:     (auth) wisher confirms → fulfiller +10 prestige
+- disclose:    (auth) apply for public disclosure (both parties must agree)
+- cancel:      (auth) wisher cancels (only open wishes)
+- me:          (auth) my charity profile (prestige breakdown + pending repayment queue)
+- stories / leaderboard: public
+- repay:       (auth) wisher initiates repayment (≥ 0.1 WAZ; auto-accepted if no response in 7d)
+- repay_respond:(auth) fulfiller responds (accept | decline_to_fund) — decline → funds go to community fund, wisher +8 / fulfiller +2 grace
+- donate:      (auth) donate to community fund (≥ 0.1 WAZ; daily 50 WAZ matched 1:1 → donation_honor)
+- fund:        fund balance + ledger + philanthropist leaderboard (public)
+
+──
+中文：慈善许愿池 + 还愿 + 慈善基金。双匿名 + 双签锚定 + 隔离 prestige。Actions: list/detail/create/claim/proof/confirm/disclose/cancel/me/stories/leaderboard/repay/repay_respond/donate/fund。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string' },
+                action: { type: 'string', enum: ['list', 'detail', 'create', 'claim', 'proof', 'confirm', 'disclose', 'cancel', 'me', 'stories', 'leaderboard', 'repay', 'repay_respond', 'donate', 'fund'] },
+                wish_id: { type: 'string' },
+                fulfillment_id: { type: 'string' },
+                repay_id: { type: 'string' },
+                choice: { type: 'string', enum: ['accept', 'decline_to_fund'] },
+                category: { type: 'string', enum: ['medical', 'education', 'daily', 'elderly', 'disaster', 'tech', 'other'] },
+                target_kind: { type: 'string', enum: ['item', 'service', 'cash'] },
+                target_waz: { type: 'number', description: 'cash 模式必填，≤ 500' },
+                escrow_self: { type: 'number', description: '1=自我托管锁仓全额，0=纯协调' },
+                title: { type: 'string' }, content: { type: 'string' },
+                window_hours: { type: 'number', description: '24-720 小时' },
+                allow_public: { type: 'number' },
+                proof_hash: { type: 'string', description: 'sha256 hex of proof_text' },
+                proof_note: { type: 'string' },
+                amount: { type: 'number', description: 'repay / donate 金额（WAZ）' },
+                note: { type: 'string' },
+                limit: { type: 'number' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'webaz_p2p_product',
+        description: `P2P native store — product detail lives on seller's node; WebAZ only anchors hash + key fields.
+Actions:
+- create (seller): publish anchor — needs title/price/stock + content_hash (sha256) + content_signature (HMAC-SHA256(api_key, hash|signed_at))
+- list:            browse public P2P products (incl. hash + peer_endpoint)
+- detail:          single product (incl. hash + endpoint; agent should self-fetch peer_endpoint and verify sha256)
+- patch (seller):  edit (price/stock/title direct; detail JSON change → must re-sign hash + signature)
+
+Verification flow (agent implements):
+1. GET peer_endpoint/<product_id> → raw JSON
+2. canonicalize (sort keys, drop nulls) → JSON.stringify
+3. sha256(canonical) === product.content_hash ? accept : reject trade
+
+──
+中文：P2P 原生商店 — 商品详情存卖家节点，WebAZ 只锚定 hash + 关键字段。Actions: create / list / detail / patch。Agent 须自行 GET peer_endpoint 校验 sha256。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string' },
+                action: { type: 'string', enum: ['create', 'list', 'detail', 'patch'] },
+                product_id: { type: 'string' },
+                title: { type: 'string' }, price: { type: 'number' }, stock: { type: 'number' },
+                content_hash: { type: 'string', description: 'sha256 hex' },
+                content_signature: { type: 'string', description: 'HMAC-SHA256(api_key, hash|signed_at)' },
+                content_signed_at: { type: 'string', description: '"YYYY-MM-DD HH:MM:SS"' },
+                peer_endpoint: { type: 'string' },
+                thumbnail_uri: { type: 'string', description: 'data:image/* base64, ≤16KB' },
+                category: { type: 'string' }, region: { type: 'string' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'webaz_like',
+        description: `Like a shareable (others' shared content) to boost product ranking.
+Actions:
+- toggle: like or unlike (same endpoint; second call auto-unlikes)
+- status: my like status on a shareable + total count
+Threshold: must have ≥1 completed order (anti-Sybil). One vote per person, can't like own.
+
+──
+中文：对 shareable 点赞 — 提升商品 ranking。Actions: toggle / status。门槛：≥1 完成订单，不能给自己点。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string' },
+                action: { type: 'string', enum: ['toggle', 'status'] },
+                shareable_id: { type: 'string' },
+            },
+            required: ['api_key', 'action', 'shareable_id'],
+        },
+    },
+    {
+        name: 'webaz_leaderboard',
+        description: `WebAZ leaderboards — no centralized traffic distribution, pure real-signal ranking. Privacy-first: GMV / revenue amounts are NEVER exposed.
+Kinds:
+- products       trending products (rank_score = sales×0.5 + referrals×2.0 + likes×1.0)
+- value_products value-certified (💎 cheapest 20% per category · daily batch)
+- creators       creator board (by total likes received)
+- sellers        seller board (by rating × log(reviews+1); GMV hidden)
+- buyers         buyer activity (by completed order count; GMV hidden)
+- verifiers      verifier board (correct count / accuracy)
+- arbitrators    arbitrator reputation (fairness_score)
+- agents         agent eval (trust_score + 30d call count)
+
+──
+中文：排行榜（无中心流量分发，纯真实信号）。8 类：products / value_products / creators / sellers / buyers / verifiers / arbitrators / agents。隐私第一不露 GMV。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: {
+                    type: 'string',
+                    enum: ['products', 'value_products', 'creators', 'sellers', 'buyers', 'verifiers', 'arbitrators', 'agents'],
+                    description: '榜单类型',
+                },
+                limit: { type: 'number', description: '默认 20，最多 50' },
+            },
+            required: ['kind'],
+        },
+    },
+    {
+        name: 'webaz_auction',
+        description: `English forward auction — seller posts → buyers raise bids → anti-sniping extension → highest bid wins.
+Actions:
+- create (seller): start auction; needs title/qty/category/starting_price, optional min_increment/reserve_price/window_min/sniper_extend_min
+- browse:          public board
+- mine:            my created (seller) + my participated (buyer)
+- detail:          full detail incl. bid history (buyer_id redacted for non-seller / non-bidder viewers)
+- bid (buyer):     place bid; needs auction_id + price (first ≥ starting; subsequent ≥ current + increment)
+- cancel (seller): cancel (only before any bid placed)
+
+──
+中文：加价拍卖（English forward）— 反狙击延时 + 最高价中标。Actions: create / browse / mine / detail / bid / cancel。仅未出价时可取消。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string' },
+                action: { type: 'string', enum: ['create', 'browse', 'mine', 'detail', 'bid', 'cancel'] },
+                title: { type: 'string' },
+                qty: { type: 'number' },
+                category: { type: 'string', enum: ['standard', 'general', 'highvalue', 'restricted'] },
+                starting_price: { type: 'number' },
+                min_increment: { type: 'number' },
+                reserve_price: { type: 'number' },
+                window_min: { type: 'number' },
+                sniper_extend_min: { type: 'number' },
+                notes: { type: 'string' },
+                auction_id: { type: 'string' },
+                price: { type: 'number' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
+    {
+        name: 'webaz_auto_bid',
+        description: `Seller auto_bid Skill config — auto-quote on RFQ creation instantly.
+Actions:
+- get:     read current Skill config
+- set:     create/update Skill (needs categories[] / regions[] / max_eta_h / bid_strategy etc.)
+- disable: one-click disable (keeps config)
+
+──
+中文：卖家 auto_bid Skill — RFQ 创建瞬间自动报价。Actions: get / set / disable。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string' },
+                action: { type: 'string', enum: ['get', 'set', 'disable'] },
+                categories: { type: 'array', items: { type: 'string' } },
+                regions: { type: 'array', items: { type: 'string' } },
+                max_eta_h: { type: 'number' },
+                fulfillment_type: { type: 'string', enum: ['instant_pickup', 'same_day', 'next_day', 'standard'] },
+                bid_strategy: { type: 'string', enum: ['cheapest_undercut', 'match_budget'] },
+                undercut_pct: { type: 'number', description: '0–0.5；折价幅度' },
+                max_price_cap: { type: 'number' },
+                daily_cap: { type: 'number' },
+                cooldown_min: { type: 'number' },
+                enabled: { type: 'boolean' },
+            },
+            required: ['api_key', 'action'],
+        },
+    },
+    {
+        name: 'webaz_skill_market',
+        description: `Knowledge-skill marketplace — anyone publishes reusable content skills (templates / prompts / guides / checklists); others pay to unlock. DISTINCT from webaz_skill (that one is seller behaviour-automation plugins).
+
+Lifecycle: publish → WebAZ content review (human admin, not via MCP) → listed → buyers unlock.
+Billing modes: free / one_time (buy once, permanent) / per_use (charged each read).
+Revenue is an independent flow (author net → wallet, 5% protocol fee → sys_protocol); it does NOT enter PV / referral commission engines.
+
+Actions:
+- list       browse listed skills (filters: kind / billing / query; no auth needed)
+- detail     one skill's public detail (skill_id; content is NOT included)
+- publish    publish a new skill (title + content + billing_mode required) → enters review queue
+- update     edit own skill (editing an approved one re-enters review)
+- delist     take own skill offline
+- resubmit   resubmit a rejected/delisted skill for review
+- purchase   unlock free / one_time skill (cannot buy your own)
+- read       read the unlocked content; per_use charges price each call
+- my_skills  my published skills (all statuses)
+- library    my unlocked / used skills
+
+──
+中文：知识技能市场 — 人人发布内容型技能（模板/提示词/指南/清单），他人付费解锁。与 webaz_skill（卖家自动化插件）是两套。计费 free/one_time/per_use；收入独立流转，不进 PV/佣金。审计是人工 admin 节点，不经 MCP。Actions: list / detail / publish / update / delist / resubmit / purchase / read / my_skills / library。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: '你的 api_key（list / detail 时可省略）' },
+                action: {
+                    type: 'string',
+                    enum: ['list', 'detail', 'publish', 'update', 'delist', 'resubmit', 'purchase', 'read', 'my_skills', 'library'],
+                    description: '要执行的操作',
+                },
+                skill_id: { type: 'string', description: '技能 ID（detail/update/delist/resubmit/purchase/read 时必填）' },
+                // publish / update
+                title: { type: 'string', description: '标题（publish 必填）' },
+                content: { type: 'string', description: '技能正文，购买后才可见（publish 必填）' },
+                summary: { type: 'string', description: '一句话简介（可选）' },
+                preview: { type: 'string', description: '公开试读，未购可见（可选）' },
+                skill_kind: { type: 'string', enum: ['template', 'prompt', 'guide', 'checklist'], description: '技能类型（默认 template）' },
+                billing_mode: { type: 'string', enum: ['free', 'one_time', 'per_use'], description: '计费模式（publish 必填）' },
+                price: { type: 'number', description: 'WAZ 价格；free 必须为 0，付费必须 >0，上限 100000' },
+                category: { type: 'string', description: '分类（可选）' },
+                // list filters
+                kind: { type: 'string', enum: ['template', 'prompt', 'guide', 'checklist'], description: '过滤类型（list 时可选）' },
+                billing: { type: 'string', enum: ['free', 'one_time', 'per_use'], description: '过滤计费模式（list 时可选）' },
+                query: { type: 'string', description: '关键词搜索（list 时可选）' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'webaz_secondhand',
+        description: `Secondhand market (个人闲置二手) — peer-to-peer pre-owned goods, 1% protocol fee, escrow-protected. Supports shipping and in-person handoff.
+
+Actions:
+- browse   list available items (filters: category / condition / region / min_price / max_price / query / sort; no auth needed; excludes your own when api_key given)
+- detail   one item's detail + seller's other listings (item_id; no auth needed)
+- publish  list an item (title + category + condition + price + images[] required; ≥1 image)
+- update   edit own item (item_id + fields; can set status available/reserved/closed)
+- mine     my listings + stats (available/sold/earned)
+- buy      place an order on an item (item_id + fulfillment_mode; shipping needs shipping_address)
+
+category: phone / computer / appliance / furniture / clothing / book / toy / sports / other
+condition: brand_new / like_new / lightly_used / well_used / heavily_used
+fulfillment: shipping / in_person / both
+
+──
+中文：二手集市 — 个人闲置 P2P，协议费 1%，escrow 保护，支持快递/面交。Actions: browse / detail / publish / update / mine / buy。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: '你的 api_key（browse / detail 时可省略）' },
+                action: { type: 'string', enum: ['browse', 'detail', 'publish', 'update', 'mine', 'buy'], description: '要执行的操作' },
+                item_id: { type: 'string', description: '物品 ID（detail/update/buy 时必填）' },
+                // publish / update
+                title: { type: 'string', description: '标题 2-60 字（publish 必填）' },
+                description: { type: 'string', description: '详细描述（≤1000 字，可选）' },
+                category: { type: 'string', enum: ['phone', 'computer', 'appliance', 'furniture', 'clothing', 'book', 'toy', 'sports', 'other'], description: '类目（publish 必填）' },
+                condition_grade: { type: 'string', enum: ['brand_new', 'like_new', 'lightly_used', 'well_used', 'heavily_used'], description: '成色（publish 必填）' },
+                price: { type: 'number', description: 'WAZ 价格 0-100000（publish 必填）' },
+                negotiable: { type: 'boolean', description: '是否可议价（可选）' },
+                images: { type: 'array', items: { type: 'string' }, description: '图片 dataURL/URL 数组，≥1 张，最多 9 张（publish 必填）' },
+                region: { type: 'string', description: '地点（≤40 字，可选）' },
+                fulfillment: { type: 'string', enum: ['shipping', 'in_person', 'both'], description: '履约方式（默认 both）' },
+                status: { type: 'string', enum: ['available', 'reserved', 'closed'], description: '改状态（update 时可选）' },
+                // buy
+                fulfillment_mode: { type: 'string', enum: ['shipping', 'in_person'], description: '本单履约方式（buy 必填，默认 shipping）' },
+                shipping_address: { type: 'string', description: '收货地址（buy 且 shipping 时必填）' },
+                notes: { type: 'string', description: '订单备注（buy 可选，可写还价）' },
+                // browse filters
+                condition: { type: 'string', description: '过滤成色，逗号分隔多选（browse 可选）' },
+                min_price: { type: 'number' },
+                max_price: { type: 'number' },
+                query: { type: 'string', description: '关键词（browse 可选）' },
+                sort: { type: 'string', enum: ['newest', 'price_asc', 'price_desc', 'popular'], description: '排序（browse 可选）' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'webaz_trial',
+        description: `Trial-for-review (测评免单) — sellers offer order refunds to buyers who post a qualifying review note; when the review reaches a target view threshold the order is auto-refunded.
+
+Anti-abuse is enforced server-side (buyer≠seller, must have a confirmed/completed order, account ≥3 days old, IP/UA rate limits, config snapshot at claim time) — MCP just passes through.
+
+Buyer actions:
+- get_campaign    read a product's active trial campaign (product_id; no auth)
+- apply           claim a trial slot for a product you've bought (product_id)
+- link_note       attach your review note to a claim (claim_id + note_id)
+- my_claims       my trial claims + statuses
+Seller actions:
+- create_campaign open/update a campaign on your product (product_id + quota_total + reach_threshold + min_chars + min_days_live)
+- cancel_campaign close your product's campaign (product_id)
+- my_campaigns    my seller-side campaigns
+- campaign_claims claims under a campaign (campaign_id)
+
+──
+中文：测评免单 — 卖家给"发合格测评笔记且达到浏览阈值"的买家退款。反作弊后端强制（买≠卖/须完成订单/账号≥3天/IP频控/配置快照）。买家: get_campaign / apply / link_note / my_claims；卖家: create_campaign / cancel_campaign / my_campaigns / campaign_claims。`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string', description: '你的 api_key（get_campaign 可省略）' },
+                action: { type: 'string', enum: ['get_campaign', 'apply', 'link_note', 'my_claims', 'create_campaign', 'cancel_campaign', 'my_campaigns', 'campaign_claims'], description: '要执行的操作' },
+                product_id: { type: 'string', description: '商品 ID（get_campaign/apply/create_campaign/cancel_campaign 时必填）' },
+                claim_id: { type: 'string', description: '申请 ID（link_note 时必填）' },
+                campaign_id: { type: 'string', description: '活动 ID（campaign_claims 时必填）' },
+                note_id: { type: 'string', description: '测评笔记 ID（link_note 时必填；须 type=note + 绑定该商品 + active）' },
+                // create_campaign config
+                quota_total: { type: 'number', description: '名额数 1-200（create_campaign 必填）' },
+                reach_threshold: { type: 'number', description: '浏览阈值 10-10000（默认 50）' },
+                min_chars: { type: 'number', description: '笔记最少字数 20-5000（默认 50）' },
+                min_days_live: { type: 'number', description: '笔记最少存活天数 1-90（默认 7）' },
+            },
+            required: ['action'],
+        },
+    },
+];
+// ─── 工具处理函数 ─────────────────────────────────────────────
+function handleInfo() {
+    const summary = getManifestSummary();
+    // QA 轮 3 抓到：live_stats 不是 hardcoded、不是 remote — 就是本地 SQLite count。这里加 source 字段澄清。
+    const stats = (() => {
+        try {
+            const users = db.prepare("SELECT COUNT(*) as n FROM users WHERE id != 'sys_protocol'").get().n;
+            const products = db.prepare("SELECT COUNT(*) as n FROM products WHERE status='active'").get().n;
+            const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE status='completed'").get().n;
+            return {
+                participants: users,
+                active_products: products,
+                completed_orders: completed,
+                source: 'local SQLite (~/.webaz/webaz.db) — counts reflect *this* MCP server\'s DB, not protocol-wide prod state',
+            };
+        }
+        catch {
+            return null;
+        }
+    })();
+    // QA 轮 3 FAIL：webaz_info 没暴露经济参数。从 protocol_params 表读 fee 类参数 + charity_fund 当前余额。
+    const economics = (() => {
+        try {
+            const feeParams = db.prepare("SELECT key, value, description FROM protocol_params WHERE category='fee' ORDER BY key").all();
+            const fund = db.prepare("SELECT balance, total_donated, total_disbursed, total_redirected FROM charity_fund WHERE id='main'").get();
+            return {
+                protocol_params: feeParams.map(p => ({ key: p.key, value: Number(p.value), note: p.description })),
+                charity_fund: fund || { balance: 0, total_donated: 0, total_disbursed: 0, total_redirected: 0 },
+                note: 'Numeric values reflect current DB state, queried fresh on each call.',
+            };
+        }
+        catch {
+            return null;
+        }
+    })();
+    return {
+        ...summary,
+        // 诚实化披露 — 排在 stats / quick_start 之前,让 agent 先建立正确预期。
+        // 第三方尽调 agent 抓到过的破绽:live_stats 是本地库数字、引导词推 agent 拉新、佣金结构有 MLM 形态。
+        // 此处主动披露,不抗辩;agent 自己判断如何处理。
+        network_state: {
+            phase: 'pre_launch',
+            real_users_on_canonical: 0,
+            canonical_endpoint: 'https://webaz.xyz',
+            economic_flow: 'simulated WAZ (test currency, 1 WAZ ≈ 1 USDC peg is a模拟基准, not a real exchange rate). No fiat/crypto settles yet.',
+            disclaimer: '本协议尚未公开上线,prod 真实用户≈0,无真实经济流转。下方 live_stats / 工具示例所有计数均来自**本机 MCP 服务器的本地 SQLite**(~/.webaz/webaz.db),仅供 dev / demo,不代表协议全网真实状态。请勿据此评估市场规模、做投资决策、或替终端用户承诺任何经济关系。',
+        },
+        description: 'WebAZ 是一个去中心化商业协议。每笔交易通过状态机流转，每个状态转移都需要对应责任方的操作证明。任何超时未操作，协议自动判定该方违约并执行处置。',
+        live_stats: stats,
+        economics,
+        // QA 轮 14.c P1：显式归因机制（与传统 MLM 自动吃下线的根本区别）
+        commission_model: {
+            split: '7:2:1 — L1 70% / L2 20% / L3 10% of commission_pool',
+            attribution: 'EXPLICIT per-order — commission goes to the promoter attributed at purchase time, NOT auto-derived from the buyer\'s sponsor chain. 防 MLM 寡头化（上线不会自动吃下线每一单）。',
+            how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records direct promoter. Full L2/L3 chain requires buyer to arrive via webaz_share_link ?ref= URL clicked in browser (builds product_share_attribution).',
+            redirect_rules: 'chain_gap (无 L / sponsor 无效) → charity_fund; region cap (level > region max_levels) → global_fund. global region max_levels=1 (仅 L1)；singapore 等 max_levels=3.',
+            l1_gate: 'promoter 必须是 verified buyer（≥1 笔完成订单）才能领 commission，否则该份 redirect。',
+            // 主动披露,不要让外部尽调 agent 自己读出来再写差评
+            compliance_notice: '⚠️ 本协议含三级佣金(L1/L2/L3 7:2:1) + 二元配对树(binary PV matching) + 邀请链结构。这类形态在多数司法辖区可能与**多层级营销(MLM)的法律定义重叠**。本协议通过显式 per-order 归因(非自动吃下线)规避了 MLM 寡头化的核心病灶,但形态层面仍带 MLM 特征,我们诚实告知。**代理 AI 不应默认替终端用户生成推广链接或拉新**——这需要用户的显式授权,且用户自身要先评估当地合规性。',
+        },
+        // QA 轮 3 FAIL：roles 漏 reviewer。register 工具支持 5 个角色，info 必须列全。
+        roles: {
+            buyer: '下单、付款、确认收货或发起争议',
+            seller: '上架商品、接单、按时发货（质押保证金确保履约）',
+            logistics: '揽收包裹、更新运输状态、确认投递（获得 5% 物流费）',
+            reviewer: '结构化商品测评（trial campaign 申请试用 + 真实购买后写评）',
+            arbitrator: '处理争议，做出裁定（120h 内必须裁定，否则系统自动退款买家）',
+        },
+        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_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)',
+            reviewer: '1. webaz_register(role=reviewer) → 2. webaz_claim_verify(action=apply) 申请测评免单 → 3. 收货后写真实评价',
+            arbitrator: '1. webaz_register(role=arbitrator) → 2. webaz_dispute(action=list_open) 看待裁案件 → 3. webaz_dispute(action=arbitrate) — ⚠️ 需 PWA + Passkey（Iron-Rule）',
+        },
+        available_tools: TOOLS.map((t) => ({ name: t.name, description: t.description.split('\n')[0] })),
+        full_manifest: `读取 MCP Resource "${MANIFEST_URI}" 获取完整协议规范（状态机/经济模型/争议系统/Skill 市场/声誉系统）`,
+    };
+}
+function handleRegister(args) {
+    const name = args.name;
+    const role = args.role;
+    const initialBalance = args.initial_balance ?? 1000;
+    // QA 轮 14.a P1：MCP register 之前不接受 region → 默认 global（PWA register 强制选）
+    // 协议级 by-design：MCP register 不设 placement_id（防 bot 刷链）
+    // 但 region 是 sales / commission 字段，应允许显式传入
+    const VALID_REGIONS = new Set(['global', 'singapore', 'china', 'usa', 'malaysia', 'indonesia', 'thailand', 'vietnam', 'taiwan', 'hk']);
+    const regionInput = String(args.region || 'global').toLowerCase();
+    const region = VALID_REGIONS.has(regionInput) ? regionInput : 'global';
+    const validRoles = ['buyer', 'seller', 'logistics', 'reviewer', 'arbitrator'];
+    if (!validRoles.includes(role)) {
+        return { error: `无效角色：${role}。可选：${validRoles.join(', ')}` };
+    }
+    const id = generateId('usr');
+    const apiKey = generateId('key');
+    const permaCode = mcpGeneratePermanentCode();
+    const { handle, requested: handleRequested, modified: handleModified } = mcpDeriveHandle(name);
+    const createdAt = new Date().toISOString();
+    db.prepare('INSERT INTO users (id, name, role, roles, api_key, permanent_code, handle, region, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)').run(id, name, role, JSON.stringify([role]), apiKey, permaCode, handle, region, createdAt);
+    db.prepare('INSERT INTO wallets (user_id, balance) VALUES (?, ?)').run(id, initialBalance);
+    const baseNext = role === 'seller' ? '现在可以用 webaz_list_product 上架你的第一件商品'
+        : role === 'buyer' ? '现在可以用 webaz_search 搜索商品'
+            : '等待订单分配给你';
+    return {
+        success: true,
+        message: '注册成功！妥善保管 api_key（身份凭证）+ permanent_code（恢复码，丢失 api_key 用它配 handle 找回）',
+        user_id: id,
+        api_key: apiKey,
+        permanent_code: permaCode,
+        permanent_code_purpose: 'Recovery code. Use webaz_mykey with handle + permanent_code to recover lost api_key. Save it somewhere safe — without it, lost api_key is lost forever.',
+        handle,
+        handle_requested: handleRequested,
+        handle_modified: handleModified,
+        ...(handleModified && {
+            handle_modification_note: `Requested handle "${handleRequested}" already taken; auto-appended numeric suffix for uniqueness. Tell users your actual handle is "${handle}".`,
+        }),
+        name,
+        role,
+        initial_balance: initialBalance,
+        created_at: createdAt,
+        next_step: handleModified
+            ? `${baseNext}。⚠️ 你请求的 handle "${handleRequested}" 已被占用，实际分配 "${handle}" — 分享/被找时用后者。`
+            : baseNext,
+    };
+}
+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) };
+}
+async function handleSearch(args) {
+    // 外链/粘贴文本模式 → relay 到 webaz.xyz/api/search-by-link（生产数据有索引）
+    if (args.paste_text || args.external_link) {
+        const apiUrl = process.env.WEBAZ_API_URL ?? 'https://webaz.xyz';
+        const body = {};
+        if (args.paste_text)
+            body.text = args.paste_text;
+        if (args.external_link)
+            body.external_link = args.external_link;
+        try {
+            const resp = await fetch(`${apiUrl}/api/search-by-link`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!resp.ok)
+                return { error: `链接搜索失败：HTTP ${resp.status}` };
+            const data = (await resp.json());
+            if (data.error)
+                return data;
+            return {
+                ...data,
+                hint: data.products?.length
+                    ? `通过 ${data.matched_by} 匹配到 ${data.products.length} 件商品。下单前用 webaz_verify_price 锁价。`
+                    : '未找到关联商品。可改用 query 参数做关键词搜索。',
+            };
+        }
+        catch (e) {
+            return { error: `链接搜索网络错误：${e.message}` };
+        }
+    }
+    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 hasSales = args.has_sales;
+    const sellerId = args.seller_id;
+    let limit = Number(args.limit ?? 10);
+    if (!Number.isFinite(limit) || limit < 1)
+        limit = 10;
+    if (limit > 200)
+        limit = 200;
+    const sortMode = args.sort ?? 'trending';
+    let sql = `
+    SELECT p.*, u.name as seller_name,
+      COALESCE((SELECT total_points FROM reputation_scores WHERE user_id = p.seller_id), 0) as rep_points,
+      COALESCE((SELECT level FROM reputation_scores WHERE user_id = p.seller_id), 'new') as rep_level
+    FROM products p
+    JOIN users u ON p.seller_id = u.id
+    WHERE p.status = 'active' AND p.stock > 0
+  `;
+    const params = [];
+    // M7.2 协议级精准匹配（与 PWA server 一致的 alias 引擎）：
+    // query 命中条件 = (1) 完全等于 product.title OR
+    //                 (2) 完全等于 任一 external_title OR
+    //                 (3) 用户文本 包含 任一卖家声明的 alias_value (≥ 6 字符 且 active)
+    if (query) {
+        const aliasRows = db.prepare(`
+      SELECT product_id, alias_value FROM product_aliases
+      WHERE status = 'active' AND length(alias_value) >= 6 AND length(alias_value) <= ?
+    `).all(query.length);
+        const aliasIds = new Set();
+        for (const a of aliasRows) {
+            if (query.includes(a.alias_value))
+                aliasIds.add(a.product_id);
+        }
+        if (aliasIds.size === 0) {
+            sql += ` AND (
+        p.title = ?
+        OR EXISTS (SELECT 1 FROM product_external_links pel WHERE pel.product_id = p.id AND pel.external_title = ?)
+      )`;
+            params.push(query, query);
+        }
+        else {
+            sql += ` AND (
+        p.id IN (${[...aliasIds].map(() => '?').join(',')})
+        OR p.title = ?
+        OR EXISTS (SELECT 1 FROM product_external_links pel WHERE pel.product_id = p.id AND pel.external_title = ?)
+      )`;
+            params.push(...aliasIds, query, query);
+        }
+    }
+    if (category) {
+        sql += ` AND p.category = ?`;
+        params.push(category);
+    }
+    if (maxPrice !== undefined) {
+        sql += ` AND p.price <= ?`;
         params.push(maxPrice);
     }
-    sql += ` ORDER BY p.created_at DESC LIMIT ?`;
-    params.push(limit);
-    const products = db.prepare(sql).all(...params);
-    if (products.length === 0) {
-        return { found: 0, message: '没有找到匹配的商品', products: [] };
+    if (minReturnDays !== undefined) {
+        sql += ` AND p.return_days >= ?`;
+        params.push(minReturnDays);
+    }
+    if (maxHandlingHours !== undefined) {
+        sql += ` AND p.handling_hours <= ?`;
+        params.push(maxHandlingHours);
+    }
+    if (sellerId) {
+        sql += ` AND p.seller_id = ?`;
+        params.push(sellerId);
+    }
+    if (hasSales === 'true') {
+        sql += ` AND EXISTS (SELECT 1 FROM orders WHERE product_id = p.id AND status = 'completed')`;
+    }
+    else if (hasSales === 'false') {
+        sql += ` AND NOT EXISTS (SELECT 1 FROM orders WHERE product_id = p.id AND status = 'completed')`;
+    }
+    if (sortMode === 'newest')
+        sql += ` ORDER BY p.created_at DESC`;
+    else if (sortMode === 'rating')
+        sql += ` ORDER BY rep_points DESC, p.created_at DESC`;
+    else if (sortMode === 'price_asc')
+        sql += ` ORDER BY p.price ASC`;
+    else if (sortMode === 'price_desc')
+        sql += ` ORDER BY p.price DESC`;
+    else if (sortMode === 'random')
+        sql += ` ORDER BY RANDOM()`;
+    // 'trending' 默认：先取候选，下面 JS 再算分排序（兼容旧 db 没有 metric 列的场景）
+    else
+        sql += ` ORDER BY p.created_at DESC`;
+    sql += ` LIMIT ?`;
+    params.push(Math.min(limit * 3, 500)); // 取更多候选，便于 trending 排序
+    const products = db.prepare(sql).all(...params);
+    if (products.length === 0) {
+        return { found: 0, message: '没有找到匹配的商品', products: [] };
+    }
+    const enriched = products.map((p) => {
+        const boost = getSearchBoost(db, p.seller_id);
+        const rep_level = p.rep_level || 'new';
+        const rep_points = Number(p.rep_points) || 0;
+        const completion = Number(p.completion_count) || 0;
+        const dispute = Number(p.dispute_loss_count) || 0;
+        const sharer = Number(p.unique_sharer_count) || 0;
+        // 与 PWA 端 TRENDING_SCORE_EXPR 阶梯曲线保持一致
+        const lastSold = p.last_sold_at;
+        let freshness = 0;
+        if (lastSold) {
+            const days = (Date.now() - new Date(lastSold.replace(' ', 'T') + 'Z').getTime()) / 86400_000;
+            if (days < 30)
+                freshness = 10;
+            else if (days < 90)
+                freshness = 10 * (1 - (days - 30) / 60);
+            else if (days < 180)
+                freshness = -5;
+            else
+                freshness = -15;
+        }
+        // 14 天首单 boost
+        const firstSold = p.first_sold_at;
+        const firstSaleBoost = firstSold && (Date.now() - new Date(firstSold.replace(' ', 'T') + 'Z').getTime()) < 14 * 86400_000 ? 5 : 0;
+        const score = completion * 0.5 + rep_points * 0.1 + sharer * 2.0 + freshness + firstSaleBoost - dispute * 5.0;
+        return { ...p, _boost: boost, _rep_level: rep_level, _rep_points: rep_points, _score: score, _freshness: freshness, _first_sale_boost: firstSaleBoost };
+    });
+    const sorted = sortMode === 'trending'
+        ? enriched.sort((a, b) => b._score - a._score || b._boost - a._boost).slice(0, limit)
+        : enriched.slice(0, limit);
+    return {
+        found: sorted.length,
+        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,
+                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,
+                // Tier 7 + 里程碑 5：agent-friendly 排序指标
+                metrics: {
+                    completion_count: Number(p.completion_count) || 0,
+                    dispute_loss_count: Number(p.dispute_loss_count) || 0,
+                    unique_sharer_count: Number(p.unique_sharer_count) || 0,
+                    last_sold_at: p.last_sold_at || null,
+                    first_sold_at: p.first_sold_at || null,
+                    rep_points: p._rep_points,
+                    rep_level: p._rep_level,
+                },
+                score: Math.round(p._score * 100) / 100,
+                score_breakdown: {
+                    freshness: Math.round(p._freshness * 100) / 100,
+                    first_sale_boost: p._first_sale_boost,
+                },
+            };
+        }),
+        sort: sortMode,
+        limit,
+        hint: 'agent 模式：products 已附带 metrics + score（含阶梯新鲜度 + 14d 首单 boost），可基于自身策略二次排序',
+    };
+}
+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);
+    // 与 P0 #1 (commit 07f9e49 generateId) 一致：用 crypto.randomBytes，128-bit 熵
+    const token = `pst_${randomBytes(16).toString('hex')}`;
+    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}" 确保以此价格成交`,
+    };
+}
+async function handleListProduct(args) {
+    // Wave 3 audit P0: 加 action 分发 — agent 卖家能完整管理目录（不止 create）
+    const action = args.action || 'create';
+    const apiKey = args.api_key;
+    if (!apiKey)
+        return { error: 'api_key required' };
+    if (action !== 'create') {
+        const auth0 = requireAuth(db, apiKey);
+        if ('error' in auth0)
+            return auth0;
+        const { user: u0 } = auth0;
+        if (action === 'mine') {
+            // QA 轮 7 P1：旧版走 PWA HTTP，本地 dev 没起 PWA 就挂；改直读 SQLite
+            const rows = db.prepare(`SELECT id, title, price, stock, status, stake_amount, category, created_at, updated_at
+         FROM products
+         WHERE seller_id = ?
+         ORDER BY created_at DESC
+         LIMIT 100`).all(u0.id);
+            const summary = rows.reduce((acc, p) => {
+                const s = p.status || 'active';
+                acc[s] = (acc[s] || 0) + 1;
+                return acc;
+            }, {});
+            return {
+                found: rows.length,
+                products: rows,
+                summary_by_status: summary,
+                seller_id: u0.id,
+                note: 'Direct SQLite query — no PWA dependency.',
+            };
+        }
+        const productId = args.product_id;
+        if (!productId)
+            return { error: `product_id required for action=${action}` };
+        if (action === 'update') {
+            const body = {};
+            const updatable = [
+                'title', 'description', 'price', 'stock', 'specs', 'brand', 'model', 'handling_hours', 'ship_regions', 'estimated_days', 'fragile', 'return_days', 'return_condition', 'warranty_days',
+                // S2 库存预警 / S3 多语言 / S4 商品溯源
+                'low_stock_threshold', 'auto_delist_on_zero', 'i18n_titles', 'i18n_descs', 'origin_claims',
+            ];
+            for (const k of updatable) {
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            }
+            return await pwaApi('PUT', `/products/${productId}`, apiKey, body);
+        }
+        if (action === 'delist')
+            return await pwaApi('PATCH', `/products/${productId}/status`, apiKey, { status: 'warehouse' });
+        if (action === 'relist')
+            return await pwaApi('PATCH', `/products/${productId}/status`, apiKey, { status: 'active' });
+        if (action === 'trash')
+            return await pwaApi('PATCH', `/products/${productId}/status`, apiKey, { status: 'deleted' });
+        if (action === 'delete')
+            return await pwaApi('DELETE', `/products/${productId}`, apiKey);
+        return { error: `unknown action: ${action}. Valid actions: create | mine | update | delist | relist | trash | delete` };
+    }
+    // ─── action === 'create' (默认) — 沿用旧逻辑 ────────────────────
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    if (user.role !== 'seller') {
+        return { error: `只有 seller 角色可以上架商品，你的角色是：${user.role}` };
+    }
+    const price = args.price;
+    // Per-order stake 模型（QA 轮 7 P0 修复）：list_product 不再预扣 stake。
+    // stake 在 place_order 那一刻按"该订单总额 × stake_rate"现锁，订单结算时退该笔，违约时扣该笔。
+    // 这样每个 active 订单都有独立 stake 担保，多 stock 商品也不会被空头薅。
+    // product.stake_amount 字段保留为"indicative rate × price"（前端展示用），不强制 lock。
+    const stakeDiscount = getStakeDiscount(db, user.id);
+    const stakeRate = Math.max(0.05, 0.15 - stakeDiscount); // 最低 5%，声誉越高折扣越大
+    const stakeAmount = Math.round(price * stakeRate * 100) / 100; // indicative only; actual lock per-order
+    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,
+      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);
+    // 注：per-order stake 模型不在此 lock — 移到 place_order 时按订单总额锁
+    // S2/S3/S4 新字段：通过 HTTP PUT 走标准校验路径（i18n 语言白名单 / origin_claims 4KB+sha256 / 库存阈值）
+    const hasExtra = ['i18n_titles', 'i18n_descs', 'origin_claims', 'low_stock_threshold', 'auto_delist_on_zero']
+        .some(k => args[k] !== undefined);
+    let extraResult = null;
+    if (hasExtra) {
+        const body = {};
+        for (const k of ['i18n_titles', 'i18n_descs', 'origin_claims', 'low_stock_threshold', 'auto_delist_on_zero']) {
+            if (args[k] !== undefined)
+                body[k] = args[k];
+        }
+        extraResult = await pwaApi('PUT', `/products/${id}`, apiKey, body);
+    }
+    const rep = getReputation(db, user.id);
+    return {
+        success: true,
+        product_id: id,
+        title: args.title,
+        price: `${price} WAZ`,
+        // QA 轮 7 P2：旧文案 "stake_locked: 15 WAZ（质押保证金，交易完成后返还）" 误导
+        //   实际 per-order 模型不在 list 时锁；改成 stake_per_order_estimate + 明示策略
+        stake_per_order_estimate: `${stakeAmount} WAZ（按当前 price × ${(stakeRate * 100).toFixed(0)}% 估算；实际每笔订单按订单总额×rate 在 place_order 时从 seller balance 锁）`,
+        stake_strategy: 'per_order',
+        stake_rate: stakeDiscount > 0 ? `${(stakeRate * 100).toFixed(0)}%（声誉折扣 -${(stakeDiscount * 100).toFixed(0)}%，原 15%）` : '15%',
+        stake_locked_now: 0, // list 不再 lock；明示给 agent
+        reputation_level: rep.level.label,
+        status: 'active（买家现在可以搜索到这件商品）',
+        ...(extraResult ? { extra_fields_applied: !('error' in extraResult), extra_result: extraResult } : {}),
+    };
+}
+function handlePlaceOrder(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    if (user.role !== 'buyer') {
+        return { error: `只有 buyer 角色可以下单，你的角色是：${user.role}` };
+    }
+    const product = db
+        .prepare("SELECT p.*, u.name as seller_name, u.id as seller_uid FROM products p JOIN users u ON p.seller_id = u.id WHERE p.id = ? AND p.status = 'active'")
+        .get(args.product_id);
+    if (!product) {
+        return { error: `商品不存在或已下架：${args.product_id}` };
+    }
+    const quantity = args.quantity ?? 1;
+    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 = ?')
+        .get(user.id);
+    if (wallet.balance < totalAmount) {
+        return {
+            error: `余额不足：订单金额 ${totalAmount} WAZ，你的余额 ${wallet.balance} WAZ`,
+        };
+    }
+    // B5 公益捐赠：donation_pct 必须是固定档位之一（同后端 DONATION_VALID_PCTS）
+    const DONATION_VALID_PCTS = new Set([0, 0.005, 0.01, 0.02, 0.05]);
+    const donationPctNum = Number(args.donation_pct || 0);
+    if (!DONATION_VALID_PCTS.has(donationPctNum)) {
+        return { error: 'donation_pct 必须是 0 / 0.005 / 0.01 / 0.02 / 0.05 之一' };
+    }
+    const donationAmount = donationPctNum > 0 ? Math.round(totalAmount * donationPctNum * 100) / 100 : 0;
+    // B2 匿名收件：服务端生成 PR-XXXXX 代号（同后端 generateRecipientCode 逻辑）
+    const anonymousFlag = args.anonymous_recipient ? 1 : 0;
+    let recipientCode = null;
+    if (anonymousFlag === 1) {
+        const ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+        const buf = randomBytes(8);
+        let s = '';
+        for (let i = 0; i < 5; i++)
+            s += ALPHABET[buf[i] % ALPHABET.length];
+        recipientCode = 'PR-' + s;
+    }
+    const now = new Date();
+    const orderId = generateId('ord');
+    // 找推荐人
+    let promoterId = null;
+    if (args.promoter_api_key) {
+        const promoter = db
+            .prepare('SELECT id FROM users WHERE api_key = ?')
+            .get(args.promoter_api_key);
+        if (promoter)
+            promoterId = promoter.id;
+    }
+    db.prepare(`
+    INSERT INTO orders (
+      id, product_id, buyer_id, seller_id, promoter_id,
+      quantity, unit_price, total_amount, escrow_amount,
+      status, shipping_address, notes,
+      pay_deadline, accept_deadline, ship_deadline,
+      pickup_deadline, delivery_deadline, confirm_deadline,
+      anonymous_recipient, recipient_code, donation_amount
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'created', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(orderId, product.id, user.id, product.seller_uid, promoterId, quantity, product.price, totalAmount, totalAmount, args.shipping_address, args.notes ?? null, addHours(now, 24), // 买家 24h 内必须付款
+    addHours(now, 48), // 卖家 24h 内接单
+    addHours(now, 120), // 卖家 72h 内发货
+    addHours(now, 168), // 物流 48h 内揽收
+    addHours(now, 336), // 物流 7 天内投递
+    addHours(now, 408), // 买家 72h 内确认
+    anonymousFlag, recipientCode, donationAmount);
+    // QA 轮 9.4 P0 修复（2026-05-27）：MCP 之前没填 settleCommission 真正读的 l1_uid + snapshot_commission_rate
+    // 后果：promoter 永远拿不到 commission（PWA 看 l1_uid=NULL → chain_gap → 14 WAZ 进 charity）
+    //       并因 settleOrder default 0 vs settleCommission default 0.10 还印 20 WAZ from thin air
+    // 修：place_order 时同步 PWA 的写法 — l1_uid = promoter（如有），snapshot_commission_rate 从 product 拷贝
+    // 注：promoter_api_key 路径下 L2/L3 不可推断（需走 share_link 点击的 product_share_attribution 链）→ 保持 NULL
+    //      L2/L3 NULL 在 global region (max_levels=1) 走 region 截断 → global_fund，不进 charity
+    //      L2/L3 NULL 在更高 max_levels region 走 chain_gap → charity
+    const snapshotCommissionRate = Number(product.commission_rate ?? 0.10);
+    db.prepare('UPDATE orders SET l1_uid = ?, snapshot_commission_rate = ? WHERE id = ?')
+        .run(promoterId, snapshotCommissionRate, orderId);
+    // 扣除库存
+    db.prepare('UPDATE products SET stock = stock - ? WHERE id = ?').run(quantity, product.id);
+    // 模拟"付款"：锁定买家余额
+    db.prepare(`
+    UPDATE wallets SET balance = balance - ?, escrowed = escrowed + ? WHERE user_id = ?
+  `).run(totalAmount, totalAmount, user.id);
+    // QA 轮 7 P0 修复：per-order 卖家 stake — 下单瞬间从 seller.balance 锁 15% 到 staked
+    // 该 stake 在 settleOrder 退还 / fault_seller 时扣给 buyer 50% + sys_protocol 50%
+    // 多 stock 商品每笔都独立 lock，不再被空头薅
+    const sellerStakeRate = 0.15; // TODO: protocol_params 化（default_commission_rate 现是 0.10 不同义）
+    const sellerStake = Math.round(totalAmount * sellerStakeRate * 100) / 100;
+    const sellerWalletNow = db.prepare('SELECT balance FROM wallets WHERE user_id = ?').get(product.seller_uid);
+    if (!sellerWalletNow || sellerWalletNow.balance < sellerStake) {
+        // rollback buyer escrow + stock (因为 stake 不够无法担保订单)
+        db.prepare('UPDATE wallets SET balance = balance + ?, escrowed = escrowed - ? WHERE user_id = ?').run(totalAmount, totalAmount, user.id);
+        db.prepare('UPDATE products SET stock = stock + ? WHERE id = ?').run(quantity, product.id);
+        return {
+            error: 'seller_insufficient_stake_balance',
+            error_code: 'SELLER_INSUFFICIENT_BALANCE',
+            message: `卖家余额不足以锁定订单 stake（需要 ${sellerStake} WAZ，卖家余 ${sellerWalletNow?.balance ?? 0}）。卖家先充值才能继续接单。`,
+            seller_stake_required: sellerStake,
+            seller_balance: sellerWalletNow?.balance ?? 0,
+            next_step: '换其他卖家的同类商品，或建议该卖家充值后重试。',
+        };
+    }
+    db.prepare('UPDATE wallets SET balance = balance - ?, staked = staked + ? WHERE user_id = ?').run(sellerStake, sellerStake, product.seller_uid);
+    // 直接进入 paid 状态（Phase 0 模拟支付）
+    transition(db, orderId, 'paid', user.id, [], '模拟支付完成，资金已托管');
+    notifyTransition(db, orderId, 'created', 'paid');
+    // 检查卖家是否开启了 auto_accept Skill，若是则自动接单
+    let autoAccepted = false;
+    if (shouldAutoAccept(db, orderId)) {
+        const sysUser = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
+        const acceptResult = transition(db, orderId, 'accepted', sysUser.id, [], '⚡ auto_accept Skill 自动接单');
+        if (acceptResult.success) {
+            notifyTransition(db, orderId, 'paid', 'accepted');
+            autoAccepted = true;
+        }
+    }
+    return {
+        success: true,
+        order_id: orderId,
+        product: product.title,
+        seller: product.seller_name,
+        quantity,
+        total_amount: `${totalAmount} WAZ（已托管，等待交易完成后自动结算）`,
+        status: autoAccepted ? 'accepted' : 'paid',
+        auto_accepted: autoAccepted || undefined,
+        next: autoAccepted
+            ? '⚡ 卖家已开启自动接单，订单已立即接受！等待卖家发货。'
+            : '卖家须在 accept_deadline 前接单（付款后 24h 内，即下单后 ~48h）。超时未接单系统自动退款。详见 deadline 字段。',
+        track: `用 webaz_get_status 查看订单进展`,
+    };
+}
+async function handleUpdateOrder(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const orderId = args.order_id;
+    const action = args.action;
+    const notes = args.notes ?? '';
+    const evidenceDesc = args.evidence_description ?? '';
+    // QA 轮 9.4 P0 修复（2026-05-27）：MCP confirm 转发 PWA endpoint，单一真相源。
+    // 旧 MCP settleOrder 写死 3% promoter 单 L1，跟 PWA settleCommission 的
+    // commission_rate × 7:2:1 + chain_gap → charity 完全不同。
+    // agent-native 协议要求"哪个接口进结果一致"。MCP confirm 不再自己结算，
+    // 走 PWA /api/orders/:id/action 的 settleOrder + settleCommission（authoritative）。
+    if (action === 'confirm') {
+        const apiKey = args.api_key;
+        const result = await pwaApi('POST', `/orders/${encodeURIComponent(orderId)}/action`, apiKey, {
+            action: 'confirm',
+            notes,
+        });
+        // 透传 PWA 响应；其中包含真实 settlement 结果。
+        // 若 PWA 不可达（本地 dev 没起 PWA），返回明确错误而非 fallback 到旧 MCP 路径
+        return result;
+    }
+    // 验证订单存在且该用户是参与方
+    let order = db
+        .prepare('SELECT * FROM orders WHERE id = ?')
+        .get(orderId);
+    if (!order)
+        return { error: `订单不存在：${orderId}` };
+    // 物流首次操作：先绑定再做参与方检查
+    if ((action === 'pickup' || action === 'transit') &&
+        !order.logistics_id &&
+        user.role === 'logistics') {
+        db.prepare('UPDATE orders SET logistics_id = ? WHERE id = ?').run(user.id, orderId);
+        order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
+    }
+    const isParticipant = order.buyer_id === user.id ||
+        order.seller_id === user.id ||
+        order.logistics_id === user.id;
+    if (!isParticipant && user.role !== 'arbitrator') {
+        return { error: '你不是这笔订单的参与方，无法操作' };
+    }
+    // action → 状态映射
+    const actionMap = {
+        accept: 'accepted',
+        ship: 'shipped',
+        pickup: 'picked_up',
+        transit: 'in_transit',
+        deliver: 'delivered',
+        confirm: 'confirmed',
+        dispute: 'disputed',
+    };
+    const toStatus = actionMap[action];
+    if (!toStatus)
+        return { error: `未知操作：${action}` };
+    // 如果有证据描述，先创建证据记录
+    const evidenceIds = [];
+    if (evidenceDesc) {
+        const evidenceId = generateId('evt');
+        db.prepare(`
+      INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
+      VALUES (?, ?, ?, 'description', ?, ?)
+    `).run(evidenceId, orderId, user.id, evidenceDesc, `hash_${Date.now()}`);
+        evidenceIds.push(evidenceId);
+    }
+    const result = transition(db, orderId, toStatus, user.id, evidenceIds, notes);
+    if (!result.success) {
+        return { error: result.error };
     }
-    const sorted = products
-        .map((p) => {
-        const boost = getSearchBoost(db, p.seller_id);
-        const rep = db.prepare('SELECT total_points, level FROM reputation_scores WHERE user_id = ?').get(p.seller_id);
-        return { ...p, _boost: boost, _rep_level: rep?.level ?? 'new', _rep_points: rep?.total_points ?? 0 };
-    })
-        .sort((a, b) => b._boost - a._boost);
-    return {
-        found: sorted.length,
-        products: sorted.map((p) => {
-            const levelMeta = { new: '', trusted: '⭐', quality: '🌟', star: '💫', legend: '🔥' };
-            const badge = levelMeta[p._rep_level] ?? '';
+    // 通知相关参与方（L2-6）
+    notifyTransition(db, orderId, order.status, toStatus);
+    // 如果是 dispute，写入 disputes 表（L3-1）
+    if (toStatus === 'disputed') {
+        const disputeResult = createDispute(db, orderId, user.id, notes || evidenceDesc || '买家发起争议', evidenceIds);
+        if (disputeResult.success) {
             return {
-                id: p.id,
-                title: p.title,
-                description: p.description,
-                price: `${p.price} WAZ`,
-                stock: p.stock,
-                category: p.category,
-                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,
+                success: true,
+                new_status: 'disputed',
+                dispute_id: disputeResult.disputeId,
+                message: disputeResult.message,
+                respond_deadline: disputeResult.respondDeadline,
+                next: `用 webaz_dispute action=view dispute_id=${disputeResult.disputeId} 查看争议详情`,
             };
-        }),
+        }
+        // 争议记录写入失败不影响状态，仍返回成功
+        return { success: true, new_status: 'disputed', message: '争议已发起，资金已冻结', warning: disputeResult.error };
+    }
+    // 如果是 confirmed，自动触发结算
+    if (toStatus === 'confirmed') {
+        const sysUser = db
+            .prepare("SELECT id FROM users WHERE id = 'sys_protocol'")
+            .get();
+        transition(db, orderId, 'completed', sysUser.id, [], '系统自动结算');
+        const breakdown = settleOrder(db, orderId);
+        return {
+            success: true,
+            new_status: 'completed',
+            message: '确认收货成功！资金已自动分配给各参与方。',
+            settlement_breakdown: breakdown, // QA P1 transparency: 详列每分钱去哪
+            detail: `用 webaz_wallet 查看你的收益`,
+        };
+    }
+    const statusMessages = {
+        accepted: '接单成功！请在承诺时间内发货，超时将自动判违约。',
+        shipped: '发货成功！物流方 48 小时内需要完成揽收。',
+        picked_up: '揽收确认！请尽快安排运输。',
+        in_transit: '运输状态已更新。',
+        delivered: '投递确认！买家 72 小时内确认收货，超时自动确认。',
+        disputed: '争议已发起，资金冻结，等待仲裁员介入。',
+    };
+    return {
+        success: true,
+        new_status: result.newStatus,
+        message: statusMessages[toStatus] ?? '状态已更新',
+        history_record: result.historyId,
     };
 }
-function handleListProduct(args) {
+function handleGetStatus(args) {
     const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const statusInfo = getOrderStatus(db, args.order_id);
+    if (!statusInfo)
+        return { error: `订单不存在：${args.order_id}` };
+    const { order, history, currentResponsible, activeDeadline, isOverdue } = statusInfo;
+    return {
+        order_id: order.id,
+        current_status: order.status,
+        current_responsible: currentResponsible
+            ? `${currentResponsible}（当前应由此角色操作）`
+            : '无（等待系统处理）',
+        deadline: activeDeadline
+            ? {
+                field: activeDeadline.field,
+                time: activeDeadline.deadline,
+                overdue: isOverdue ? '⚠️ 已超时！协议将自动判责' : '未超时',
+            }
+            : null,
+        history: history.map((h) => ({
+            from: h.from_status,
+            to: h.to_status,
+            by: `${h.actor_name}（${h.actor_role_name}）`,
+            at: h.created_at,
+            evidence_count: JSON.parse(h.evidence_ids || '[]').length,
+            notes: h.notes,
+        })),
+    };
+}
+async function handleWallet(args) {
+    // Wave 3 audit P0: 加 action 分发 — agent 能查充值/提现/收入历史（写操作仍 UI-only 走 2FA）
+    const action = args.action || 'view';
+    const apiKey = args.api_key;
+    if (!apiKey)
+        return { error: 'api_key required' };
+    if (action === 'deposits')
+        return await pwaApi('GET', '/wallet/deposits', apiKey);
+    if (action === 'withdrawals')
+        return await pwaApi('GET', '/wallet/withdrawals', apiKey);
+    if (action === 'income')
+        return await pwaApi('GET', '/wallet/income', apiKey);
+    if (action !== 'view') {
+        return { error: `unknown action: ${action}. Valid: view | deposits | withdrawals | income. 注意：提现/充值/白名单管理需 Passkey + 邮件 OTP，仅 PWA Web 端可用` };
+    }
+    // ─── action === 'view' (默认) — 沿用旧逻辑 ─────────────────────
+    const auth = requireAuth(db, apiKey);
     if ('error' in auth)
         return auth;
     const { user } = auth;
-    if (user.role !== 'seller') {
-        return { error: `只有 seller 角色可以上架商品，你的角色是：${user.role}` };
+    const wallet = db
+        .prepare('SELECT * FROM wallets WHERE user_id = ?')
+        .get(user.id);
+    if (!wallet)
+        return { error: '钱包不存在' };
+    // QA 轮 9.4-retry-v3 P1：旧版用 SUM(payouts.amount) 算 earned
+    //   但 PWA settleOrder 只更 wallets.earned 列不写 payouts 表 → MCP 视图 stale
+    //   PWA confirm 后真实 earned 在 wallets.earned；payouts 仅 MCP legacy settleOrder 写
+    //   改用 wallet.earned 列作单一真相源
+    const totalEarned = Number(wallet.earned ?? 0);
+    const rep = getReputation(db, user.id);
+    const nextLevel = ['new', 'trusted', 'quality', 'star', 'legend'];
+    const nextIdx = nextLevel.indexOf(rep.level.key) + 1;
+    const nextLevelDef = nextIdx < nextLevel.length ? { trusted: 200, quality: 800, star: 2000, legend: 5000 }[nextLevel[nextIdx]] : null;
+    return {
+        user: user.name,
+        role: user.role,
+        balance: `${wallet.balance} WAZ（可用）`,
+        staked: `${wallet.staked} WAZ（质押中，不可用）`,
+        escrowed: `${wallet.escrowed} WAZ（托管中，交易完成后结算）`,
+        total_earned: `${totalEarned} WAZ（历史累计收益）`,
+        reputation: {
+            level: `${rep.level.icon} ${rep.level.label}`,
+            total_points: rep.total_points,
+            transactions_done: rep.transactions_done,
+            disputes_won: rep.disputes_won,
+            disputes_lost: rep.disputes_lost,
+            violations: rep.violations,
+            stake_discount: rep.level.stakeDiscount > 0 ? `-${(rep.level.stakeDiscount * 100).toFixed(0)}% 质押优惠` : '暂无（升级后享优惠）',
+            next_level: nextLevelDef ? `距下一等级还需 ${nextLevelDef - rep.total_points} 分` : '已达最高等级！',
+            recent_events: rep.recent_events.slice(0, 5).map(e => `${e.points > 0 ? '+' : ''}${e.points} ${e.reason}`),
+        },
+    };
+}
+// ─── 通知处理 ─────────────────────────────────────────────────
+function handleNotifications(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const onlyUnread = args.unread === true;
+    const notifs = getNotifications(db, user.id, onlyUnread, 30);
+    const unread = getUnreadCount(db, user.id);
+    if (args.mark_read) {
+        markRead(db, user.id);
+    }
+    return {
+        unread_count: unread,
+        notifications: notifs.map(n => ({
+            id: n.id,
+            title: n.title,
+            body: n.body,
+            order_id: n.order_id,
+            read: n.read === 1,
+            time: n.created_at,
+        })),
+    };
+}
+// ─── 争议处理 ─────────────────────────────────────────────────
+async function handleDispute(args) {
+    const apiKey = args.api_key;
+    if (!apiKey)
+        return { error: 'api_key required' };
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const action = args.action;
+    // ── 查看争议详情 ────────────────────────────────────────────
+    if (action === 'view') {
+        let dispute = args.dispute_id
+            ? getDisputeDetails(db, args.dispute_id)
+            : args.order_id
+                ? getOrderDispute(db, args.order_id)
+                : null;
+        if (!dispute)
+            return { error: '找不到争议记录，请提供 dispute_id 或 order_id' };
+        const evidenceList = (orderId, uploaderRole) => db.prepare(`
+        SELECT e.description, e.type, e.file_hash, e.created_at, u.name as uploader
+        FROM evidence e JOIN users u ON e.uploader_id = u.id
+        WHERE e.order_id = ? AND u.role = ?
+        ORDER BY e.created_at ASC
+      `).all(orderId, uploaderRole);
+        return {
+            dispute_id: dispute.id,
+            order_id: dispute.order_id,
+            status: dispute.status,
+            initiator: `${dispute.initiator_name}（${dispute.initiator_role}）`,
+            defendant: `${dispute.defendant_name}（${dispute.defendant_role}）`,
+            reason: dispute.reason,
+            respond_deadline: dispute.respond_deadline,
+            arbitrate_deadline: dispute.arbitrate_deadline,
+            plaintiff_evidence: evidenceList(dispute.order_id, dispute.initiator_role),
+            defendant_notes: dispute.defendant_notes ?? '（被诉方尚未提交回应）',
+            defendant_evidence: JSON.parse(dispute.defendant_evidence_ids || '[]'),
+            ruling: dispute.ruling_type
+                ? { type: dispute.ruling_type, refund_amount: dispute.refund_amount, reason: dispute.verdict_reason }
+                : null,
+            // QA 轮 15 P1：未裁定时暴露可选 ruling 列表（与 PWA disputes-write.ts validRulings 对齐）
+            ruling_options: dispute.ruling_type ? undefined : [
+                { type: 'refund_buyer', desc: '全额退款给买家（卖家败诉）' },
+                { type: 'release_seller', desc: '放款给卖家（买家败诉）' },
+                { type: 'partial_refund', desc: '部分退款（需传 refund_amount）' },
+                { type: 'liability_split', desc: '按责任分配（需传 liability_parties 数组）' },
+            ],
+            resolved_at: dispute.resolved_at,
+        };
+    }
+    // ── 仲裁员查看所有待处理争议 ───────────────────────────────
+    if (action === 'list_open') {
+        if (user.role !== 'arbitrator') {
+            return { error: '只有仲裁员可以查看所有待处理争议' };
+        }
+        const disputes = getOpenDisputes(db);
+        return {
+            open_count: disputes.length,
+            disputes: disputes.map(d => ({
+                dispute_id: d.id,
+                order_id: d.order_id,
+                status: d.status,
+                initiator: `${d.initiator_name}（${d.initiator_role}）`,
+                defendant: `${d.defendant_name}（${d.defendant_role}）`,
+                reason: d.reason,
+                amount: `${d.total_amount} WAZ`,
+                respond_deadline: d.respond_deadline,
+                arbitrate_deadline: d.arbitrate_deadline,
+                created_at: d.created_at,
+            }))
+        };
+    }
+    // ── 被诉方提交反驳 ──────────────────────────────────────────
+    if (action === 'respond') {
+        if (!args.dispute_id)
+            return { error: '请提供 dispute_id' };
+        // 如有证据描述，先创建证据记录
+        const evidenceIds = [];
+        if (args.evidence_description) {
+            const dispute = getDisputeDetails(db, args.dispute_id);
+            if (dispute) {
+                const eid = generateId('evt');
+                db.prepare(`
+          INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
+          VALUES (?, ?, ?, 'description', ?, ?)
+        `).run(eid, dispute.order_id, user.id, args.evidence_description, `hash_${Date.now()}`);
+                evidenceIds.push(eid);
+            }
+        }
+        return respondToDispute(db, args.dispute_id, user.id, args.notes ?? '', evidenceIds);
+    }
+    // ── 争议参与方补充证据 (Wave 3 新增) ────────────────────────
+    if (action === 'add_evidence') {
+        if (!args.dispute_id)
+            return { error: '请提供 dispute_id' };
+        if (!args.evidence_description)
+            return { error: '请提供 evidence_description（证据描述）' };
+        // QA 轮 15 P1：PWA add-evidence 路由收 `description` 字段，MCP 之前发 `evidence_description` → 不匹配证据写不进
+        return await pwaApi('POST', `/disputes/${args.dispute_id}/add-evidence`, apiKey, {
+            description: args.evidence_description,
+            evidence_type: 'text',
+        });
+    }
+    // ── 仲裁员裁定（Iron-Rule：MCP 仅登记意图，真正裁定需 PWA + Passkey 二次确认）─
+    // QA 轮 7 P1 修复：旧版直接调 PWA HTTP /api/disputes/:id/arbitrate，
+    //   1) 违反 Iron-Rule 模型（应该跟 revoke_key/rotate_key 同模式 — agent 不能单方面执行不可逆操作）
+    //   2) 本地 dev 没起 PWA 就挂
+    if (action === 'arbitrate') {
+        if (!args.dispute_id)
+            return { error: '请提供 dispute_id' };
+        if (!args.ruling)
+            return { error: '请提供 ruling（refund_buyer / release_seller / partial_refund / liability_split）' };
+        if (!args.ruling_reason)
+            return { error: '请提供 ruling_reason（裁定理由将永久记录）' };
+        if (args.ruling === 'partial_refund' && !args.refund_amount && !args.liable_party) {
+            return { error: 'partial_refund 需要提供 refund_amount，或 liable_party（第三方责任方）' };
+        }
+        if (args.ruling === 'liability_split' && (!Array.isArray(args.liability_parties) || args.liability_parties.length === 0)) {
+            return { error: 'liability_split 需要提供 liability_parties 数组，每项 { user_id, amount }' };
+        }
+        return {
+            success: false,
+            requires_human_action: true,
+            iron_rule: 'Arbitration ruling is irreversible, affects multiple parties, and locks fund distribution permanently. Agent cannot execute unilaterally. Same Iron-Rule gating as webaz_revoke_key / claim_verify vote.',
+            action: 'arbitrate_dispute',
+            dispute_id: args.dispute_id,
+            proposed_ruling: {
+                ruling: args.ruling,
+                reason: args.ruling_reason,
+                ...(args.refund_amount !== undefined ? { refund_amount: args.refund_amount } : {}),
+                ...(args.liable_party ? { liable_party: args.liable_party } : {}),
+                ...(args.liability_parties ? { liability_parties: args.liability_parties } : {}),
+            },
+            next_step: {
+                via: 'PWA + Passkey (arbitrator role)',
+                url: `https://webaz.xyz/arbitrate?dispute=${encodeURIComponent(args.dispute_id)}`,
+                instructions: '1) Open URL in browser  2) Sign in as arbitrator  3) Review evidence  4) Confirm with Passkey  5) Submit final ruling. Action is irreversible after confirmation.',
+            },
+        };
+    }
+    return { error: `未知 action：${action}。Valid: view | list_open | respond | add_evidence | arbitrate` };
+}
+// ─── 索赔验证（claim-verification）处理 — Wave 6 新增 ────────────
+async function handleClaimVerify(args) {
+    const apiKey = args.api_key;
+    if (!apiKey)
+        return { error: 'api_key required' };
+    const action = String(args.action || '');
+    // 【买家】发起验证
+    if (action === 'create') {
+        if (!args.order_id)
+            return { error: '请提供 order_id（待验证的订单）' };
+        if (!args.claim_target)
+            return { error: '请提供 claim_target（声明对象，如 title / description / condition / shipping_time 等）' };
+        if (!args.claim_text)
+            return { error: '请提供 claim_text（声明文本，6-500 字）' };
+        return await pwaApi('POST', `/orders/${args.order_id}/claim-verification`, apiKey, {
+            claim_target: args.claim_target,
+            claim_text: args.claim_text,
+            evidence_uri: args.evidence_uri,
+        });
+    }
+    // 【任意参与方】查详情
+    if (action === 'view') {
+        if (!args.task_id)
+            return { error: '请提供 task_id' };
+        return await pwaApi('GET', `/claim-tasks/${args.task_id}`, apiKey);
+    }
+    // 【我相关】三类视角
+    if (action === 'mine') {
+        return await pwaApi('GET', '/claim-tasks/mine', apiKey);
+    }
+    // 【卖家】提交反驳证据（延期 24h）
+    if (action === 'submit_seller_evidence') {
+        if (!args.task_id)
+            return { error: '请提供 task_id' };
+        if (!args.evidence_uri)
+            return { error: '请提供 evidence_uri（证据链接，4-500 字符）' };
+        return await pwaApi('POST', `/claim-tasks/${args.task_id}/seller-evidence`, apiKey, {
+            evidence_uri: args.evidence_uri,
+        });
+    }
+    // 【Verifier】可接任务
+    if (action === 'available') {
+        return await pwaApi('GET', '/claim-tasks/available', apiKey);
+    }
+    // 【Verifier】投票
+    if (action === 'vote') {
+        if (!args.task_id)
+            return { error: '请提供 task_id' };
+        const VALID_VOTES = ['pass', 'fail', 'no_fault', 'abstain'];
+        if (!args.vote || !VALID_VOTES.includes(String(args.vote))) {
+            return { error: `vote 必须是 ${VALID_VOTES.join(' / ')}`, error_code: 'VOTE_INVALID' };
+        }
+        return await pwaApi('POST', `/claim-tasks/${args.task_id}/vote`, apiKey, {
+            vote: args.vote,
+            evidence_uri: args.evidence_uri,
+            note: args.note,
+        });
     }
-    const price = args.price;
-    const stakeDiscount = getStakeDiscount(db, user.id);
-    const stakeRate = Math.max(0.05, 0.15 - stakeDiscount); // 最低 5%，声誉越高折扣越大
-    const stakeAmount = Math.round(price * stakeRate * 100) / 100;
-    // 检查卖家是否有足够余额质押
-    const wallet = db
-        .prepare('SELECT * FROM wallets WHERE user_id = ?')
-        .get(user.id);
-    if (wallet.balance < stakeAmount) {
+    // 【Verifier 申请】资格查询
+    if (action === 'eligibility') {
+        return await pwaApi('GET', '/verifier/eligibility', apiKey);
+    }
+    // 【Verifier 状态】tier/quota/stake
+    if (action === 'verifier_status') {
+        return await pwaApi('GET', '/verifier/status', apiKey);
+    }
+    // 【Verifier 申请】提交
+    if (action === 'apply') {
+        return await pwaApi('POST', '/verifier/apply', apiKey);
+    }
+    // 【Verifier 申请】撤回
+    if (action === 'withdraw_application') {
+        return await pwaApi('POST', '/verifier/withdraw-application', apiKey);
+    }
+    // 【Verifier】被暂停后申诉
+    if (action === 'appeal') {
+        if (!args.reason)
+            return { error: '请提供 reason（申诉理由，≤500 字）' };
+        return await pwaApi('POST', '/verifier/appeal', apiKey, {
+            reason: args.reason,
+            task_id: args.task_id,
+        });
+    }
+    return { error: `未知 action：${action}。Valid: create | view | mine | submit_seller_evidence | available | vote | eligibility | verifier_status | apply | withdraw_application | appeal` };
+}
+// ─── Skill 市场处理 ────────────────────────────────────────────
+function handleSkill(args) {
+    const action = args.action;
+    // ── 浏览 Skill 市场 ────────────────────────────────────────
+    if (action === 'list') {
+        let userId;
+        if (args.api_key) {
+            const a = requireAuth(db, args.api_key);
+            if (!('error' in a))
+                userId = a.user.id;
+        }
+        const skills = listSkills(db, {
+            skillType: args.skill_type,
+            query: args.query,
+            subscriberId: userId,
+            limit: 20,
+        });
         return {
-            error: `余额不足：上架此商品需要质押 ${stakeAmount} WAZ，你的余额为 ${wallet.balance} WAZ`,
+            total: skills.length,
+            skill_types: Object.entries(SKILL_TYPE_META).map(([k, v]) => ({ type: k, label: v.label, icon: v.icon, description: v.description })),
+            skills: skills.map(formatSkillForAgent),
         };
     }
-    const id = generateId('prd');
-    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);
-    // 扣除质押金额
-    db.prepare(`
-    UPDATE wallets SET balance = balance - ?, staked = staked + ? WHERE user_id = ?
-  `).run(stakeAmount, stakeAmount, user.id);
-    const rep = getReputation(db, user.id);
-    return {
-        success: true,
-        product_id: id,
-        title: args.title,
-        price: `${price} WAZ`,
-        stake_locked: `${stakeAmount} WAZ（质押保证金，交易完成后返还）`,
-        stake_rate: stakeDiscount > 0 ? `${(stakeRate * 100).toFixed(0)}%（声誉折扣 -${(stakeDiscount * 100).toFixed(0)}%，原 15%）` : '15%',
-        reputation_level: rep.level.label,
-        status: 'active（买家现在可以搜索到这件商品）',
-    };
-}
-function handlePlaceOrder(args) {
+    // 以下操作需要身份验证
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
     const { user } = auth;
-    if (user.role !== 'buyer') {
-        return { error: `只有 buyer 角色可以下单，你的角色是：${user.role}` };
+    // ── 发布 Skill ────────────────────────────────────────────
+    if (action === 'publish') {
+        if (!args.name)
+            return { error: '请填写 Skill 名称（name）' };
+        if (!args.description)
+            return { error: '请填写 Skill 描述（description）' };
+        if (!args.skill_type)
+            return { error: '请选择 Skill 类型（skill_type）' };
+        const skill = publishSkill(db, {
+            sellerId: user.id,
+            name: args.name,
+            description: args.description,
+            category: args.category,
+            skillType: args.skill_type,
+            config: args.config,
+        });
+        const meta = SKILL_TYPE_META[skill.skill_type];
+        return {
+            success: true,
+            skill_id: skill.id,
+            message: `✅ Skill 「${skill.name}」已发布到 WebAZ Skill 市场！买家 Agent 现在可以订阅它。`,
+            type: `${meta.icon} ${meta.label}`,
+            tip: 'auto_accept Skill 发布后，买家新订单将自动被接受（无需手动操作）',
+        };
     }
-    const product = db
-        .prepare("SELECT p.*, u.name as seller_name, u.id as seller_uid FROM products p JOIN users u ON p.seller_id = u.id WHERE p.id = ? AND p.status = 'active'")
-        .get(args.product_id);
-    if (!product) {
-        return { error: `商品不存在或已下架：${args.product_id}` };
+    // ── 订阅 Skill ────────────────────────────────────────────
+    if (action === 'subscribe') {
+        if (!args.skill_id)
+            return { error: '请提供 skill_id' };
+        const result = subscribeSkill(db, user.id, args.skill_id, args.config);
+        return { ...result, skill_id: args.skill_id };
     }
-    const quantity = args.quantity ?? 1;
-    if (product.stock < quantity) {
-        return { error: `库存不足：当前库存 ${product.stock}，你要购买 ${quantity}` };
+    // ── 取消订阅 ──────────────────────────────────────────────
+    if (action === 'unsubscribe') {
+        if (!args.skill_id)
+            return { error: '请提供 skill_id' };
+        unsubscribeSkill(db, user.id, args.skill_id);
+        return { success: true, message: '已取消订阅' };
     }
-    const totalAmount = product.price * quantity;
-    const wallet = db
-        .prepare('SELECT * FROM wallets WHERE user_id = ?')
-        .get(user.id);
-    if (wallet.balance < totalAmount) {
+    // ── 我发布的 Skill ────────────────────────────────────────
+    if (action === 'my_skills') {
+        const skills = getMySkills(db, user.id);
         return {
-            error: `余额不足：订单金额 ${totalAmount} WAZ，你的余额 ${wallet.balance} WAZ`,
+            total: skills.length,
+            skills: skills.map(formatSkillForAgent),
+            tip: skills.length === 0 ? '还没有发布任何 Skill。用 webaz_skill action=publish 发布你的第一个 Skill。' : undefined,
         };
     }
-    const now = new Date();
-    const orderId = generateId('ord');
-    // 找推荐人
-    let promoterId = null;
-    if (args.promoter_api_key) {
-        const promoter = db
-            .prepare('SELECT id FROM users WHERE api_key = ?')
-            .get(args.promoter_api_key);
-        if (promoter)
-            promoterId = promoter.id;
-    }
-    db.prepare(`
-    INSERT INTO orders (
-      id, product_id, buyer_id, seller_id, promoter_id,
-      quantity, unit_price, total_amount, escrow_amount,
-      status, shipping_address, notes,
-      pay_deadline, accept_deadline, ship_deadline,
-      pickup_deadline, delivery_deadline, confirm_deadline
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'created', ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(orderId, product.id, user.id, product.seller_uid, promoterId, quantity, product.price, totalAmount, totalAmount, args.shipping_address, args.notes ?? null, addHours(now, 24), // 买家 24h 内必须付款
-    addHours(now, 48), // 卖家 24h 内接单
-    addHours(now, 120), // 卖家 72h 内发货
-    addHours(now, 168), // 物流 48h 内揽收
-    addHours(now, 336), // 物流 7 天内投递
-    addHours(now, 408));
-    // 扣除库存
-    db.prepare('UPDATE products SET stock = stock - ? WHERE id = ?').run(quantity, product.id);
-    // 模拟"付款"：锁定买家余额
-    db.prepare(`
-    UPDATE wallets SET balance = balance - ?, escrowed = escrowed + ? WHERE user_id = ?
-  `).run(totalAmount, totalAmount, user.id);
-    // 直接进入 paid 状态（Phase 0 模拟支付）
-    transition(db, orderId, 'paid', user.id, [], '模拟支付完成，资金已托管');
-    notifyTransition(db, orderId, 'created', 'paid');
-    // 检查卖家是否开启了 auto_accept Skill，若是则自动接单
-    let autoAccepted = false;
-    if (shouldAutoAccept(db, orderId)) {
-        const sysUser = db.prepare("SELECT id FROM users WHERE id = 'sys_protocol'").get();
-        const acceptResult = transition(db, orderId, 'accepted', sysUser.id, [], '⚡ auto_accept Skill 自动接单');
-        if (acceptResult.success) {
-            notifyTransition(db, orderId, 'paid', 'accepted');
-            autoAccepted = true;
-        }
+    // ── 我订阅的 Skill ────────────────────────────────────────
+    if (action === 'my_subs') {
+        const skills = getMySubscriptions(db, user.id);
+        return {
+            total: skills.length,
+            subscriptions: skills.map(formatSkillForAgent),
+            tip: skills.length === 0 ? '还没有订阅任何 Skill。用 webaz_skill action=list 浏览市场。' : undefined,
+        };
     }
-    return {
-        success: true,
-        order_id: orderId,
-        product: product.title,
-        seller: product.seller_name,
-        quantity,
-        total_amount: `${totalAmount} WAZ（已托管，等待交易完成后自动结算）`,
-        status: autoAccepted ? 'accepted' : 'paid',
-        auto_accepted: autoAccepted || undefined,
-        next: autoAccepted
-            ? '⚡ 卖家已开启自动接单，订单已立即接受！等待卖家发货。'
-            : '等待卖家 24 小时内接单。卖家超时不接单将自动退款。',
-        track: `用 webaz_get_status 查看订单进展`,
-    };
+    return { error: `未知 action：${action}。可选：list, publish, subscribe, unsubscribe, my_skills, my_subs` };
 }
-function handleUpdateOrder(args) {
-    const auth = requireAuth(db, args.api_key);
-    if ('error' in auth)
-        return auth;
-    const { user } = auth;
-    const orderId = args.order_id;
-    const action = args.action;
-    const notes = args.notes ?? '';
-    const evidenceDesc = args.evidence_description ?? '';
-    // 验证订单存在且该用户是参与方
-    let order = db
-        .prepare('SELECT * FROM orders WHERE id = ?')
-        .get(orderId);
-    if (!order)
-        return { error: `订单不存在：${orderId}` };
-    // 物流首次操作：先绑定再做参与方检查
-    if ((action === 'pickup' || action === 'transit') &&
-        !order.logistics_id &&
-        user.role === 'logistics') {
-        db.prepare('UPDATE orders SET logistics_id = ? WHERE id = ?').run(user.id, orderId);
-        order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
+// P0-1 修复（QA 轮 5 抓到）：旧版只要 name → 直接吐所有匹配账户 api_key 明文，且无 rate limit。
+// 新版：handle + permanent_code 双因素 + redact + in-memory rate limit (5/hr per handle)。
+// 完整 api_key 不在 MCP 暴露 — 走 PWA + Passkey 才给（Iron-Rule，跟 claim_verify / arbitrate 同模型）。
+const MYKEY_RATE_LIMIT = new Map();
+const MYKEY_MAX_PER_HOUR = 5;
+function redactKey(key) {
+    if (!key || key.length < 12)
+        return '***';
+    return `${key.slice(0, 8)}***${key.slice(-4)}`;
+}
+function handleMyKey(args) {
+    const handle = args.handle?.trim();
+    const permaCode = args.permanent_code?.trim()?.toUpperCase();
+    if (!handle || !permaCode) {
+        return {
+            error: 'invalid_request',
+            error_code: 'MISSING_PARAMS',
+            message: 'Both handle and permanent_code required. Check the registration response — handle may have been auto-suffixed if requested name was taken (look for handle_modified=true).',
+        };
     }
-    const isParticipant = order.buyer_id === user.id ||
-        order.seller_id === user.id ||
-        order.logistics_id === user.id;
-    if (!isParticipant && user.role !== 'arbitrator') {
-        return { error: '你不是这笔订单的参与方，无法操作' };
+    const now = Date.now();
+    const entry = MYKEY_RATE_LIMIT.get(handle) || { count: 0, resetAt: now + 3600_000 };
+    if (now > entry.resetAt) {
+        entry.count = 0;
+        entry.resetAt = now + 3600_000;
     }
-    // action → 状态映射
-    const actionMap = {
-        accept: 'accepted',
-        ship: 'shipped',
-        pickup: 'picked_up',
-        transit: 'in_transit',
-        deliver: 'delivered',
-        confirm: 'confirmed',
-        dispute: 'disputed',
-    };
-    const toStatus = actionMap[action];
-    if (!toStatus)
-        return { error: `未知操作：${action}` };
-    // 如果有证据描述，先创建证据记录
-    const evidenceIds = [];
-    if (evidenceDesc) {
-        const evidenceId = generateId('evt');
-        db.prepare(`
-      INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
-      VALUES (?, ?, ?, 'description', ?, ?)
-    `).run(evidenceId, orderId, user.id, evidenceDesc, `hash_${Date.now()}`);
-        evidenceIds.push(evidenceId);
+    if (entry.count >= MYKEY_MAX_PER_HOUR) {
+        return {
+            error: 'rate_limit_exceeded',
+            error_code: 'RATE_LIMIT',
+            message: `Too many recovery attempts for this handle. Try again in ${Math.ceil((entry.resetAt - now) / 60_000)} minutes.`,
+            retry_after_seconds: Math.ceil((entry.resetAt - now) / 1000),
+        };
     }
-    const result = transition(db, orderId, toStatus, user.id, evidenceIds, notes);
-    if (!result.success) {
-        return { error: result.error };
+    entry.count++;
+    MYKEY_RATE_LIMIT.set(handle, entry);
+    const user = db.prepare(`SELECT id, name, handle, role, roles, api_key FROM users WHERE handle = ? AND permanent_code = ? AND id != 'sys_protocol'`).get(handle, permaCode);
+    if (!user) {
+        return {
+            error: 'invalid_credentials',
+            error_code: 'AUTH_FAILED',
+            message: 'No account matches handle + permanent_code. Handle is case-sensitive; permanent_code is uppercase.',
+            attempts_remaining: MYKEY_MAX_PER_HOUR - entry.count,
+        };
     }
-    // 通知相关参与方（L2-6）
-    notifyTransition(db, orderId, order.status, toStatus);
-    // 如果是 dispute，写入 disputes 表（L3-1）
-    if (toStatus === 'disputed') {
-        const disputeResult = createDispute(db, orderId, user.id, notes || evidenceDesc || '买家发起争议', evidenceIds);
-        if (disputeResult.success) {
-            return {
-                success: true,
-                new_status: 'disputed',
-                dispute_id: disputeResult.disputeId,
-                message: disputeResult.message,
-                respond_deadline: disputeResult.respondDeadline,
-                next: `用 webaz_dispute action=view dispute_id=${disputeResult.disputeId} 查看争议详情`,
-            };
-        }
-        // 争议记录写入失败不影响状态，仍返回成功
-        return { success: true, new_status: 'disputed', message: '争议已发起，资金已冻结', warning: disputeResult.error };
+    return {
+        found: true,
+        user_id: user.id,
+        name: user.name,
+        handle: user.handle,
+        active_role: user.role,
+        roles: JSON.parse(user.roles || JSON.stringify([user.role])),
+        api_key_hint: redactKey(user.api_key),
+        full_api_key_recovery: {
+            via: 'PWA + Passkey',
+            url: 'https://webaz.xyz/recover',
+            note: 'For security, full api_key disclosure requires Passkey verification on PWA (Iron-Rule). This MCP response only confirms the account exists and shows a redacted hint to help you identify which account.',
+        },
+        next_step: 'If you cannot access PWA, use webaz_rotate_key to invalidate the lost key and get a new one (also Passkey-gated).',
+    };
+}
+async function handleProfile(args) {
+    const action = args.action;
+    const apiKey = String(args.api_key || '');
+    // 看他人公开主页 / 内容流
+    if (action === 'view_user') {
+        if (!args.user_id)
+            return { error: 'user_id required' };
+        if (!apiKey)
+            return { error: 'api_key required（公开主页端点需鉴权）' };
+        return await pwaApi('GET', '/users/' + encodeURIComponent(String(args.user_id)), apiKey);
     }
-    // 如果是 confirmed，自动触发结算
-    if (toStatus === 'confirmed') {
-        const sysUser = db
-            .prepare("SELECT id FROM users WHERE id = 'sys_protocol'")
-            .get();
-        transition(db, orderId, 'completed', sysUser.id, [], '系统自动结算');
-        settleOrder(db, orderId);
+    if (action === 'feed') {
+        if (!args.user_id || !args.feed)
+            return { error: 'user_id + feed required' };
+        const FEED_PATH = {
+            secondhand: 'secondhand', auctions: 'auctions', reviews: 'reviews', products: 'products',
+            shares: 'shareables', reputation: 'reputation', pv: 'pv-summary', liked: 'liked-shareables',
+        };
+        const seg = FEED_PATH[String(args.feed)];
+        if (!seg)
+            return { error: `unknown feed: ${args.feed}. options: ${Object.keys(FEED_PATH).join(', ')}` };
+        // liked = owner-only，需自己的 api_key；其余公开（无 key 也可）
+        return await pwaApi('GET', '/users/' + encodeURIComponent(String(args.user_id)) + '/' + seg, apiKey);
+    }
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const roles = JSON.parse(user.roles || JSON.stringify([user.role]));
+    if (action === 'view') {
+        const wallet = db.prepare('SELECT balance, staked, escrowed, earned FROM wallets WHERE user_id = ?').get(user.id);
+        // P0-2 修复（QA 轮 5）：旧版直接回显完整 api_key 明文。Agent 上下文 / 日志 / 截屏一旦留痕等同于凭据泄漏。
+        // 改返 redact 过的 hint，足够 agent 确认"我是哪个账户"，不再让完整 key 进 conversation transcript。
         return {
-            success: true,
-            new_status: 'completed',
-            message: '确认收货成功！资金已自动分配给各参与方。',
-            detail: `用 webaz_wallet 查看你的收益`,
+            id: user.id,
+            name: user.name,
+            handle: user.handle,
+            active_role: user.role,
+            roles,
+            api_key_hint: redactKey(user.api_key),
+            wallet,
+            tip: 'Use add_role to add a new role, switch_role to change your active role. api_key is no longer returned in plaintext — use webaz_rotate_key if you need a new key.',
         };
     }
-    const statusMessages = {
-        accepted: '接单成功！请在承诺时间内发货，超时将自动判违约。',
-        shipped: '发货成功！物流方 48 小时内需要完成揽收。',
-        picked_up: '揽收确认！请尽快安排运输。',
-        in_transit: '运输状态已更新。',
-        delivered: '投递确认！买家 72 小时内确认收货，超时自动确认。',
-        disputed: '争议已发起，资金冻结，等待仲裁员介入。',
-    };
+    const validRoles = ['buyer', 'seller', 'logistics', 'arbitrator'];
+    const role = args.role;
+    if (action === 'add_role') {
+        if (!validRoles.includes(role))
+            return { error: `Invalid role. Options: ${validRoles.join(', ')}` };
+        if (roles.includes(role))
+            return { error: `You already have the "${role}" role` };
+        roles.push(role);
+        db.prepare("UPDATE users SET roles = ?, updated_at = datetime('now') WHERE id = ?").run(JSON.stringify(roles), user.id);
+        return { success: true, active_role: user.role, roles, message: `Role "${role}" added. Use switch_role to activate it.` };
+    }
+    if (action === 'switch_role') {
+        if (!validRoles.includes(role))
+            return { error: `Invalid role. Options: ${validRoles.join(', ')}` };
+        if (!roles.includes(role))
+            return { error: `You don't have the "${role}" role yet. Use add_role first.` };
+        db.prepare("UPDATE users SET role = ?, updated_at = datetime('now') WHERE id = ?").run(role, user.id);
+        return { success: true, active_role: role, roles, message: `Switched to "${role}" mode.` };
+    }
+    return { error: `Unknown action: ${action}. Options: view, add_role, switch_role, view_user, feed` };
+}
+// ─── api_key 生命周期（Iron-Rule: 真正吊销/轮换走 PWA + Passkey） ─────
+// QA 轮 5 抓到 P0：旧版没任何 logout/revoke/rotate 工具，api_key 一旦泄漏永久接管。
+// 这里给 agent 两个"声明意图"工具：MCP 验 api_key 合法 → 返回 PWA URL 让用户 Passkey 二次确认。
+// 真正改 DB 的动作放 PWA endpoint，跟 claim_verify / arbitrate 同模型。
+function handleRevokeKey(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const reason = (args.reason || 'unspecified').trim().slice(0, 100);
     return {
-        success: true,
-        new_status: result.newStatus,
-        message: statusMessages[toStatus] ?? '状态已更新',
-        history_record: result.historyId,
+        success: false,
+        requires_human_action: true,
+        iron_rule: 'API key revocation is a destructive, irreversible operation. Agent cannot execute unilaterally. Same gating as claim_verify and arbitrate.',
+        action: 'revoke_api_key',
+        user_id: user.id,
+        api_key_hint: redactKey(user.api_key),
+        reason_logged: reason,
+        next_step: {
+            via: 'PWA + Passkey',
+            url: `https://webaz.xyz/revoke?user=${encodeURIComponent(user.id)}`,
+            instructions: '1) Open URL in browser  2) Sign in  3) Confirm with Passkey  4) Click "Revoke". After confirm the old api_key returns 401 on all tools.',
+            warning: 'After revoke you cannot call any auth\'d tool until you have a new api_key. Use webaz_rotate_key instead for atomic invalidate + re-issue.',
+        },
     };
 }
-function handleGetStatus(args) {
+function handleRotateKey(args) {
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
-    const statusInfo = getOrderStatus(db, args.order_id);
-    if (!statusInfo)
-        return { error: `订单不存在：${args.order_id}` };
-    const { order, history, currentResponsible, activeDeadline, isOverdue } = statusInfo;
+    const { user } = auth;
+    const reason = (args.reason || 'rotation').trim().slice(0, 100);
     return {
-        order_id: order.id,
-        current_status: order.status,
-        current_responsible: currentResponsible
-            ? `${currentResponsible}（当前应由此角色操作）`
-            : '无（等待系统处理）',
-        deadline: activeDeadline
-            ? {
-                field: activeDeadline.field,
-                time: activeDeadline.deadline,
-                overdue: isOverdue ? '⚠️ 已超时！协议将自动判责' : '未超时',
-            }
-            : null,
-        history: history.map((h) => ({
-            from: h.from_status,
-            to: h.to_status,
-            by: `${h.actor_name}（${h.actor_role_name}）`,
-            at: h.created_at,
-            evidence_count: JSON.parse(h.evidence_ids || '[]').length,
-            notes: h.notes,
-        })),
+        success: false,
+        requires_human_action: true,
+        iron_rule: 'API key rotation requires Passkey verification (Iron-Rule). MCP registers intent only.',
+        action: 'rotate_api_key',
+        user_id: user.id,
+        old_api_key_hint: redactKey(user.api_key),
+        reason_logged: reason,
+        next_step: {
+            via: 'PWA + Passkey',
+            url: `https://webaz.xyz/rotate?user=${encodeURIComponent(user.id)}`,
+            instructions: '1) Open URL  2) Sign in  3) Confirm with Passkey  4) PWA returns new api_key — copy immediately, shown once. Old key invalidated atomically with new key issuance.',
+        },
     };
 }
-function handleWallet(args) {
+// ─── 推广 / 双轨 (Tokenomics) ───────────────────────────────────
+function handleReferral(args) {
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
     const { user } = auth;
-    const wallet = db
-        .prepare('SELECT * FROM wallets WHERE user_id = ?')
-        .get(user.id);
-    if (!wallet)
-        return { error: '钱包不存在' };
-    const payouts = db
-        .prepare('SELECT SUM(amount) as total FROM payouts WHERE recipient_id = ?')
-        .get(user.id);
-    const rep = getReputation(db, user.id);
-    const nextLevel = ['new', 'trusted', 'quality', 'star', 'legend'];
-    const nextIdx = nextLevel.indexOf(rep.level.key) + 1;
-    const nextLevelDef = nextIdx < nextLevel.length ? { trusted: 200, quality: 800, star: 2000, legend: 5000 }[nextLevel[nextIdx]] : null;
+    const userId = user.id;
+    // 团队 L1/L2/L3
+    const l1 = db.prepare("SELECT COUNT(*) as n FROM users WHERE sponsor_id = ?").get(userId).n;
+    const l2 = db.prepare(`SELECT COUNT(*) as n FROM users WHERE sponsor_id IN (SELECT id FROM users WHERE sponsor_id = ?)`).get(userId).n;
+    const l3 = db.prepare(`SELECT COUNT(*) as n FROM users WHERE sponsor_id IN (SELECT id FROM users WHERE sponsor_id IN (SELECT id FROM users WHERE sponsor_id = ?))`).get(userId).n;
+    // 累计佣金（按 level 聚合）
+    const earnings = db.prepare(`SELECT level, COUNT(*) as orders, COALESCE(SUM(amount),0) as total FROM commission_records WHERE beneficiary_id = ? GROUP BY level`).all(userId);
+    const byLevel = { 1: { orders: 0, total: 0 }, 2: { orders: 0, total: 0 }, 3: { orders: 0, total: 0 } };
+    for (const r of earnings)
+        byLevel[r.level] = { orders: r.orders, total: r.total };
+    // 推土机 L1 资格判定
+    const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
+    const override = db.prepare("SELECT l1_share_override FROM users WHERE id = ?").get(userId)?.l1_share_override ?? 0;
+    const canL1 = override === 1 || (override === 0 && completed > 0);
+    // 原子能双轨
+    const me = db.prepare("SELECT total_left_pv, total_right_pv, left_child_id, right_child_id, placement_id, placement_side FROM users WHERE id = ?").get(userId);
+    const score = db.prepare(`
+    SELECT COALESCE(SUM(CASE WHEN settled_at IS NULL THEN score ELSE 0 END),0) as pending,
+           COALESCE(SUM(CASE WHEN settled_at IS NOT NULL THEN waz_amount ELSE 0 END),0) as settled_waz
+    FROM binary_score_records WHERE user_id = ?
+  `).get(userId);
+    const tiers = db.prepare("SELECT tier, pv_threshold, score_per_hit FROM binary_tier_config WHERE active=1 ORDER BY tier ASC").all();
+    const pair = Math.min(Number(me?.total_left_pv ?? 0), Number(me?.total_right_pv ?? 0));
+    const nextTier = tiers.find(t => t.pv_threshold > pair);
     return {
-        user: user.name,
-        role: user.role,
-        balance: `${wallet.balance} WAZ（可用）`,
-        staked: `${wallet.staked} WAZ（质押中，不可用）`,
-        escrowed: `${wallet.escrowed} WAZ（托管中，交易完成后结算）`,
-        total_earned: `${payouts.total ?? 0} WAZ（历史累计收益）`,
-        reputation: {
-            level: `${rep.level.icon} ${rep.level.label}`,
-            total_points: rep.total_points,
-            transactions_done: rep.transactions_done,
-            disputes_won: rep.disputes_won,
-            disputes_lost: rep.disputes_lost,
-            violations: rep.violations,
-            stake_discount: rep.level.stakeDiscount > 0 ? `-${(rep.level.stakeDiscount * 100).toFixed(0)}% 质押优惠` : '暂无（升级后享优惠）',
-            next_level: nextLevelDef ? `距下一等级还需 ${nextLevelDef - rep.total_points} 分` : '已达最高等级！',
-            recent_events: rep.recent_events.slice(0, 5).map(e => `${e.points > 0 ? '+' : ''}${e.points} ${e.reason}`),
+        user_id: userId,
+        name: user.name,
+        base_referral_link: `/?ref=${userId}`, // 仅推土机
+        region: user.region ?? 'global',
+        permissions: {
+            can_earn_l1_commission: canL1,
+            completed_orders: completed,
+            reason: canL1
+                ? (override === 1 ? 'admin_grant' : 'verified_buyer')
+                : 'need_completed_order — share PV-only link until verified',
+        },
+        team: { l1, l2, l3, total: l1 + l2 + l3 },
+        earnings: {
+            l1: byLevel[1], l2: byLevel[2], l3: byLevel[3],
+            grand_total: byLevel[1].total + byLevel[2].total + byLevel[3].total,
+        },
+        binary: {
+            left_invite_link: `/?ref=${userId}&side=left`,
+            right_invite_link: `/?ref=${userId}&side=right`,
+            platform_left: `/?placement=${userId}&side=left`, // 仅 PV 条线
+            platform_right: `/?placement=${userId}&side=right`,
+            total_left_pv: Number(me?.total_left_pv ?? 0),
+            total_right_pv: Number(me?.total_right_pv ?? 0),
+            pair_volume: pair,
+            next_tier: nextTier ? { tier: nextTier.tier, pv_threshold: nextTier.pv_threshold, score_per_hit: nextTier.score_per_hit, pv_needed: nextTier.pv_threshold - pair } : null,
+            score_pending: score.pending,
+            waz_total_earned: score.settled_waz,
         },
+        tip: canL1
+            ? 'Use webaz_share_link(product_id) to generate a product share link. Both 3-tier commission and PV tree will apply.'
+            : 'Complete 1 purchase first, then your share link will earn 3-tier commission. Until then, your share builds PV tree only.',
     };
 }
-// ─── 通知处理 ─────────────────────────────────────────────────
-function handleNotifications(args) {
+function handleShareLink(args) {
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
     const { user } = auth;
-    const onlyUnread = args.unread === true;
-    const notifs = getNotifications(db, user.id, onlyUnread, 30);
-    const unread = getUnreadCount(db, user.id);
-    if (args.mark_read) {
-        markRead(db, user.id);
+    const userId = user.id;
+    const productId = args.product_id;
+    const sideArg = args.side || 'auto';
+    const product = db.prepare("SELECT id, title, price, commission_rate FROM products WHERE id = ? AND status='active'").get(productId);
+    if (!product)
+        return { error: '商品不存在或已下架' };
+    let side = 'right';
+    if (sideArg === 'left' || sideArg === 'right') {
+        side = sideArg;
+    }
+    else {
+        // auto = 与 PWA pickPreferredSide 对齐：尊重 placement_pref(team_count | pv_count)
+        // 老版只看 total_left_pv vs total_right_pv，team_count 用户被错算
+        const u = db.prepare("SELECT placement_pref, total_left_pv, total_right_pv, left_child_id, right_child_id FROM users WHERE id = ?")
+            .get(userId);
+        const pref = u?.placement_pref || 'team_count';
+        if (pref === 'pv_count') {
+            const since = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000).toISOString().slice(0, 19).replace('T', ' ');
+            const w = db.prepare(`SELECT COALESCE(SUM(consumed_left_pv),0) AS l, COALESCE(SUM(consumed_right_pv),0) AS r
+                            FROM binary_score_records WHERE user_id = ? AND created_at >= ?`)
+                .get(userId, since);
+            const leftPv = Number(u?.total_left_pv ?? 0) + Number(w.l);
+            const rightPv = Number(u?.total_right_pv ?? 0) + Number(w.r);
+            side = leftPv <= rightPv ? 'left' : 'right';
+        }
+        else {
+            // team_count: 沿子链数下线人数（与 server.ts countSubtreeUsers 一致）
+            const countLeg = (rootId, childField) => {
+                let count = 0, current = rootId, safety = 10_000;
+                while (safety-- > 0) {
+                    const row = db.prepare(`SELECT ${childField} FROM users WHERE id = ?`).get(current);
+                    const next = row?.[childField] || null;
+                    if (!next)
+                        break;
+                    count++;
+                    current = next;
+                }
+                return count;
+            };
+            const lCount = countLeg(userId, 'left_child_id');
+            const rCount = countLeg(userId, 'right_child_id');
+            side = lCount <= rCount ? 'left' : 'right';
+        }
     }
+    const completed = db.prepare("SELECT COUNT(*) as n FROM orders WHERE buyer_id = ? AND status = 'completed'").get(userId).n;
+    const override = db.prepare("SELECT l1_share_override FROM users WHERE id = ?").get(userId)?.l1_share_override ?? 0;
+    const canL1 = override === 1 || (override === 0 && completed > 0);
+    const rate = Number(product.commission_rate ?? 0);
+    const link = `/?ref=${userId}&side=${side}#order-product/${productId}`;
     return {
-        unread_count: unread,
-        notifications: notifs.map(n => ({
-            id: n.id,
-            title: n.title,
-            body: n.body,
-            order_id: n.order_id,
-            read: n.read === 1,
-            time: n.created_at,
-        })),
+        product: { id: product.id, title: product.title, price: product.price, commission_rate: rate },
+        share_link: link,
+        full_url_hint: 'Prepend webaz.xyz (production) or http://localhost:3000 (local) to get the absolute URL',
+        side,
+        binary_explanation: `New user via this link → placed in your ${side === 'left' ? '🔵 left' : '🟢 right'} subtree (tail anchor)`,
+        commission_eligibility: canL1
+            ? `You will earn 3-tier commission: L1=${(rate * 0.70 * 100).toFixed(1)}% L2=${(rate * 0.20 * 100).toFixed(1)}% L3=${(rate * 0.10 * 100).toFixed(1)}% of sale price`
+            : 'You are NOT verified yet (need 1 completed purchase). 3-tier commission will be skipped, but PV tree still builds.',
+        next_steps: 'Share on TikTok / WeChat / Telegram. New user clicks → 30-day attribution window starts.',
     };
 }
-// ─── 争议处理 ─────────────────────────────────────────────────
-function handleDispute(args) {
+// ─── 黑名单 / 关注 / 雷达 / 默认地址 / shareables ─────────
+function handleBlocklist(args) {
     const auth = requireAuth(db, args.api_key);
     if ('error' in auth)
         return auth;
     const { user } = auth;
-    const action = args.action;
-    // ── 查看争议详情 ────────────────────────────────────────────
-    if (action === 'view') {
-        let dispute = args.dispute_id
-            ? getDisputeDetails(db, args.dispute_id)
-            : args.order_id
-                ? getOrderDispute(db, args.order_id)
-                : null;
-        if (!dispute)
-            return { error: '找不到争议记录，请提供 dispute_id 或 order_id' };
-        const evidenceList = (orderId, uploaderRole) => db.prepare(`
-        SELECT e.description, e.type, e.file_hash, e.created_at, u.name as uploader
-        FROM evidence e JOIN users u ON e.uploader_id = u.id
-        WHERE e.order_id = ? AND u.role = ?
-        ORDER BY e.created_at ASC
-      `).all(orderId, uploaderRole);
+    const action = String(args.action || '');
+    // 多形态识别：usr_xxx / VKSF9P / @handle
+    const targetId = args.user_id ? mcpResolveUserRef(String(args.user_id)) : undefined;
+    if (action === 'list') {
+        const rows = db.prepare(`
+      SELECT b.blocked_id, b.reason, b.created_at, u.name as blocked_name, u.role as blocked_role
+      FROM user_blocklist b LEFT JOIN users u ON u.id = b.blocked_id
+      WHERE b.blocker_id = ? ORDER BY b.created_at DESC
+    `).all(user.id);
+        return { blocked: rows };
+    }
+    if (!targetId)
+        return { error: 'user_id required for block/unblock' };
+    if (targetId === user.id)
+        return { error: 'cannot block yourself' };
+    if (targetId === 'sys_protocol')
+        return { error: 'cannot block system account' };
+    if (action === 'block') {
+        const exists = db.prepare("SELECT 1 FROM users WHERE id = ?").get(targetId);
+        if (!exists)
+            return { error: 'target user not found' };
+        const reason = (args.reason || '').slice(0, 200);
+        db.prepare("INSERT OR IGNORE INTO user_blocklist (blocker_id, blocked_id, reason) VALUES (?, ?, ?)")
+            .run(user.id, targetId, reason || null);
+        return { ok: true, blocked: targetId };
+    }
+    if (action === 'unblock') {
+        db.prepare("DELETE FROM user_blocklist WHERE blocker_id = ? AND blocked_id = ?").run(user.id, targetId);
+        return { ok: true, unblocked: targetId };
+    }
+    return { error: `unknown action: ${action}` };
+}
+function handleFollows(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const action = String(args.action || '');
+    // 多形态识别：usr_xxx / VKSF9P / @handle
+    const targetId = args.user_id ? mcpResolveUserRef(String(args.user_id)) : undefined;
+    if (action === 'list') {
+        const followers = db.prepare(`
+      SELECT u.id, u.name, u.role, f.created_at FROM follows f JOIN users u ON u.id = f.follower_id
+      WHERE f.followee_id = ? ORDER BY f.created_at DESC LIMIT 100
+    `).all(user.id);
+        const following = db.prepare(`
+      SELECT u.id, u.name, u.role, f.created_at FROM follows f JOIN users u ON u.id = f.followee_id
+      WHERE f.follower_id = ? ORDER BY f.created_at DESC LIMIT 100
+    `).all(user.id);
+        return { followers, following };
+    }
+    if (!targetId)
+        return { error: 'user_id required' };
+    if (targetId === user.id)
+        return { error: 'cannot self-follow' };
+    if (action === 'follow') {
+        const target = db.prepare("SELECT id FROM users WHERE id=?").get(targetId);
+        if (!target)
+            return { error: 'target not found' };
+        // 尊重 blocklist：若 target 已 block 自己 → 拒绝（防绕过私聊封锁）
+        const blockedByTarget = db.prepare("SELECT 1 FROM user_blocklist WHERE blocker_id = ? AND blocked_id = ? LIMIT 1").get(targetId, user.id);
+        if (blockedByTarget)
+            return { error: 'target has blocked you', error_code: 'BLOCKED_BY_TARGET' };
+        db.prepare("INSERT OR IGNORE INTO follows (follower_id, followee_id) VALUES (?, ?)").run(user.id, targetId);
+        return { ok: true, following: true };
+    }
+    if (action === 'unfollow') {
+        db.prepare("DELETE FROM follows WHERE follower_id=? AND followee_id=?").run(user.id, targetId);
+        return { ok: true, following: false };
+    }
+    if (action === 'status') {
+        const isFollowing = !!db.prepare("SELECT 1 FROM follows WHERE follower_id=? AND followee_id=?").get(user.id, targetId);
+        const followers = db.prepare("SELECT COUNT(*) as n FROM follows WHERE followee_id=?").get(targetId).n;
+        const followingCount = db.prepare("SELECT COUNT(*) as n FROM follows WHERE follower_id=?").get(targetId).n;
+        return { following: isFollowing, target_followers: followers, target_following_count: followingCount };
+    }
+    return { error: `unknown action: ${action}` };
+}
+function handleNearby(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const action = String(args.action || '');
+    if (action === 'set_location') {
+        const lat = Number(args.lat), lng = Number(args.lng);
+        if (!Number.isFinite(lat) || !Number.isFinite(lng))
+            return { error: 'lat/lng required and numeric' };
+        if (lat < -90 || lat > 90 || lng < -180 || lng > 180)
+            return { error: 'lat/lng out of bounds' };
+        const truncLat = Math.round(lat * 10) / 10;
+        const truncLng = Math.round(lng * 10) / 10;
+        db.prepare("UPDATE users SET geo_lat = ?, geo_lng = ?, geo_updated_at = datetime('now') WHERE id = ?")
+            .run(truncLat, truncLng, user.id);
+        return { ok: true, lat: truncLat, lng: truncLng, precision_deg: 0.1, approx_km: 11 };
+    }
+    if (action === 'clear_location') {
+        db.prepare("UPDATE users SET geo_lat = NULL, geo_lng = NULL, geo_updated_at = NULL WHERE id = ?").run(user.id);
+        return { ok: true };
+    }
+    if (action === 'query') {
+        const u = db.prepare("SELECT geo_lat, geo_lng FROM users WHERE id = ?").get(user.id);
+        if (u?.geo_lat == null || u?.geo_lng == null)
+            return { has_location: false, hint: 'call set_location first' };
+        const lat = u.geo_lat, lng = u.geo_lng;
+        const K = 3;
+        // 防指纹：count < K 时返回 null（不暴露具体小数字），与 topProducts 一致
+        const rawActive24 = db.prepare(`SELECT COUNT(DISTINCT o.buyer_id) as n FROM orders o JOIN users u ON u.id = o.buyer_id WHERE u.geo_lat = ? AND u.geo_lng = ? AND o.status = 'completed' AND o.updated_at > datetime('now', '-1 day')`).get(lat, lng).n;
+        const rawActive7 = db.prepare(`SELECT COUNT(DISTINCT o.buyer_id) as n FROM orders o JOIN users u ON u.id = o.buyer_id WHERE u.geo_lat = ? AND u.geo_lng = ? AND o.status = 'completed' AND o.updated_at > datetime('now', '-7 day')`).get(lat, lng).n;
+        const active24 = rawActive24 >= K ? rawActive24 : null;
+        const active7 = rawActive7 >= K ? rawActive7 : null;
+        const topProducts = db.prepare(`
+      SELECT p.id, p.title, p.price, COUNT(DISTINCT o.buyer_id) as buyers
+      FROM orders o JOIN users u ON u.id = o.buyer_id JOIN products p ON p.id = o.product_id
+      WHERE u.geo_lat = ? AND u.geo_lng = ? AND o.status = 'completed' AND o.updated_at > datetime('now', '-1 day')
+      GROUP BY p.id HAVING buyers >= ? ORDER BY buyers DESC LIMIT 10
+    `).all(lat, lng, K);
         return {
-            dispute_id: dispute.id,
-            order_id: dispute.order_id,
-            status: dispute.status,
-            initiator: `${dispute.initiator_name}（${dispute.initiator_role}）`,
-            defendant: `${dispute.defendant_name}（${dispute.defendant_role}）`,
-            reason: dispute.reason,
-            respond_deadline: dispute.respond_deadline,
-            arbitrate_deadline: dispute.arbitrate_deadline,
-            plaintiff_evidence: evidenceList(dispute.order_id, dispute.initiator_role),
-            defendant_notes: dispute.defendant_notes ?? '（被诉方尚未提交回应）',
-            defendant_evidence: JSON.parse(dispute.defendant_evidence_ids || '[]'),
-            ruling: dispute.ruling_type
-                ? { type: dispute.ruling_type, refund_amount: dispute.refund_amount, reason: dispute.verdict_reason }
-                : null,
-            resolved_at: dispute.resolved_at,
+            has_location: true,
+            cell: { lat, lng, precision_deg: 0.1, approx_km: 11 },
+            k_threshold: K,
+            active_users_24h: active24,
+            active_users_7d: active7,
+            top_products_24h: topProducts,
         };
     }
-    // ── 仲裁员查看所有待处理争议 ───────────────────────────────
-    if (action === 'list_open') {
-        if (user.role !== 'arbitrator') {
-            return { error: '只有仲裁员可以查看所有待处理争议' };
+    return { error: `unknown action: ${action}` };
+}
+function handleDefaultAddress(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const action = String(args.action || '');
+    if (action === 'read') {
+        const u = db.prepare("SELECT default_address_text, default_address_region FROM users WHERE id = ?").get(user.id);
+        return {
+            address_text: u?.default_address_text || null,
+            address_region: u?.default_address_region || null,
+            hint: u?.default_address_text ? null : 'No default set. Setting it auto-filters unshippable products in search.',
+        };
+    }
+    if (action === 'set') {
+        // QA 轮 10.2-B P1 修复：旧版无校验，传不对的字段（recipient/line1/city 等）silently 写 NULL，
+        // 返回 ok: true 但 text/region 都是 null —— 元规则 #4 不撒谎被违反。
+        // 修：text 必填校验；返回里加 success/stored 字段更明确。
+        const text = (args.text || '').trim().slice(0, 200);
+        const region = (args.region || '').trim().slice(0, 40);
+        if (!text) {
+            return {
+                error: 'missing_text',
+                error_code: 'TEXT_REQUIRED',
+                message: 'webaz_default_address action=set 需要 "text" 字段（自由格式地址字符串，≤200 字符）。不接受 structured 字段如 recipient/line1/city。如要 region 联动过滤 unshippable，请同时传 "region" 字段（如 "global" / "china" / "SG"）。',
+                valid_params: { text: 'required', region: 'optional' },
+            };
         }
-        const disputes = getOpenDisputes(db);
+        db.prepare("UPDATE users SET default_address_text = ?, default_address_region = ?, updated_at = datetime('now') WHERE id = ?")
+            .run(text, region || null, user.id);
         return {
-            open_count: disputes.length,
-            disputes: disputes.map(d => ({
-                dispute_id: d.id,
-                order_id: d.order_id,
-                status: d.status,
-                initiator: `${d.initiator_name}（${d.initiator_role}）`,
-                defendant: `${d.defendant_name}（${d.defendant_role}）`,
-                reason: d.reason,
-                amount: `${d.total_amount} WAZ`,
-                respond_deadline: d.respond_deadline,
-                arbitrate_deadline: d.arbitrate_deadline,
-                created_at: d.created_at,
-            }))
+            success: true,
+            stored: { text, region: region || null },
+            hint: 'webaz_search 现在会自动按 region 过滤 unshippable 商品；webaz_rfq create 不传 shipping_address 时会 fallback 到此地址',
+        };
+    }
+    return { error: `unknown action: ${action}` };
+}
+function handleShareables(args) {
+    const auth = requireAuth(db, args.api_key);
+    if ('error' in auth)
+        return auth;
+    const { user } = auth;
+    const action = String(args.action || '');
+    if (action === 'list_mine') {
+        const rows = db.prepare(`
+      SELECT s.*, p.title as product_title FROM shareables s
+      LEFT JOIN products p ON p.id = s.related_product_id
+      WHERE s.owner_id = ? AND s.status != 'removed' ORDER BY s.created_at DESC LIMIT 100
+    `).all(user.id);
+        return { shareables: rows };
+    }
+    if (action === 'by_product') {
+        const pid = args.related_product_id;
+        if (!pid)
+            return { error: 'related_product_id required' };
+        const rows = db.prepare(`
+      SELECT s.*, u.name as owner_name FROM shareables s LEFT JOIN users u ON u.id = s.owner_id
+      WHERE s.related_product_id = ? AND s.status = 'active'
+      ORDER BY s.click_count DESC, s.created_at DESC LIMIT 20
+    `).all(pid);
+        return { shareables: rows };
+    }
+    if (action === 'by_anchor') {
+        const anchor = args.related_anchor;
+        if (!anchor)
+            return { error: 'related_anchor required' };
+        const rows = db.prepare(`
+      SELECT s.*, u.name as owner_name FROM shareables s LEFT JOIN users u ON u.id = s.owner_id
+      WHERE s.related_anchor = ? AND s.status = 'active' ORDER BY s.created_at DESC LIMIT 50
+    `).all(anchor);
+        return { shareables: rows };
+    }
+    if (action === 'add') {
+        const url = (args.external_url || '').trim();
+        const product_id = args.related_product_id;
+        const anchor = args.related_anchor;
+        if (!url)
+            return { error: 'external_url required' };
+        if (!product_id && !anchor)
+            return { error: 'related_product_id or related_anchor required' };
+        if (url.length > 500)
+            return { error: 'external_url too long (max 500)', error_code: 'URL_TOO_LONG' };
+        if (!/^https?:\/\//i.test(url))
+            return { error: 'external_url must be http(s)://', error_code: 'URL_SCHEME_INVALID' };
+        const todayCount = db.prepare(`SELECT COUNT(*) as n FROM shareables WHERE owner_id = ? AND created_at > datetime('now', '-1 day')`).get(user.id).n;
+        if (todayCount >= 10)
+            return { error: 'daily limit 10 reached' };
+        // 全局唯一：同 URL 已被任何用户认领 → 归因模糊，拒绝（首认领者拿）
+        const globalDup = db.prepare(`SELECT id, owner_id FROM shareables WHERE external_url = ? AND status != 'removed' LIMIT 1`).get(url);
+        if (globalDup) {
+            if (globalDup.owner_id === user.id)
+                return { error: 'duplicate URL exists', existing_id: globalDup.id, error_code: 'DUP_OWN' };
+            return { error: 'URL already claimed by another user (attribution conflict)', error_code: 'URL_CLAIMED' };
+        }
+        let type = 'external_url', platform = 'unknown';
+        if (/youtube\.com|youtu\.be/i.test(url)) {
+            type = 'external_youtube';
+            platform = 'youtube';
+        }
+        else if (/tiktok\.com/i.test(url)) {
+            type = 'external_tiktok';
+            platform = 'tiktok';
+        }
+        else if (/xiaohongshu|xhslink/i.test(url)) {
+            type = 'external_xhs';
+            platform = 'xiaohongshu';
+        }
+        else if (/bilibili\.com/i.test(url)) {
+            type = 'external_bilibili';
+            platform = 'bilibili';
+        }
+        else if (/instagram\.com/i.test(url)) {
+            type = 'external_ig';
+            platform = 'instagram';
+        }
+        else if (/twitter\.com|x\.com/i.test(url)) {
+            type = 'external_twitter';
+            platform = 'twitter';
+        }
+        const id = generateId('shr');
+        const title = (args.title || '').slice(0, 100) || null;
+        const description = (args.description || '').slice(0, 200) || null;
+        db.prepare(`INSERT INTO shareables (id, owner_id, type, external_url, external_platform, title, description, related_product_id, related_anchor) VALUES (?,?,?,?,?,?,?,?,?)`)
+            .run(id, user.id, type, url, platform, title, description, product_id || null, anchor || null);
+        return { ok: true, id, type, platform };
+    }
+    if (action === 'delete') {
+        const id = args.shareable_id;
+        if (!id)
+            return { error: 'shareable_id required' };
+        const row = db.prepare("SELECT owner_id FROM shareables WHERE id = ?").get(id);
+        if (!row || row.owner_id !== user.id)
+            return { error: 'not owner or not found' };
+        db.prepare(`UPDATE shareables SET status = 'removed', updated_at = datetime('now') WHERE id = ?`).run(id);
+        return { ok: true, deleted: id };
+    }
+    return { error: `unknown action: ${action}` };
+}
+// ─── P3 RFQ / bid / chat / auto_bid（HTTP 转发到 PWA，复用所有校验+状态机）────
+const PWA_API_BASE = process.env.WEBAZ_PWA_API_BASE || 'http://localhost:3000/api';
+async function pwaApi(method, path, apiKey, body) {
+    const opts = {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        },
+    };
+    if (body !== undefined)
+        opts.body = JSON.stringify(body);
+    const url = PWA_API_BASE + path;
+    try {
+        const r = await fetch(url, opts);
+        // QA 轮 13 P1：检测 PWA 返回 HTML (SPA 兜底 fallback 404 时)
+        // 之前直接 r.json() 抛 SyntaxError → agent 收到 "Unexpected token <" 无法 structurally 处理
+        const ct = r.headers.get('content-type') || '';
+        if (!ct.includes('application/json')) {
+            const text = await r.text();
+            return {
+                error: `PWA upstream returned non-JSON (likely 404 SPA fallback or routing error)`,
+                error_code: 'PWA_UPSTREAM_NOT_JSON',
+                status: r.status,
+                url: path,
+                body_preview: text.slice(0, 200),
+            };
+        }
+        return await r.json();
+    }
+    catch (e) {
+        return {
+            error: `PWA API unreachable: ${e.message}`,
+            error_code: 'PWA_UNREACHABLE',
+            url: path,
         };
     }
-    // ── 被诉方提交反驳 ──────────────────────────────────────────
-    if (action === 'respond') {
-        if (!args.dispute_id)
-            return { error: '请提供 dispute_id' };
-        // 如有证据描述，先创建证据记录
-        const evidenceIds = [];
-        if (args.evidence_description) {
-            const dispute = getDisputeDetails(db, args.dispute_id);
-            if (dispute) {
-                const eid = generateId('evt');
-                db.prepare(`
-          INSERT INTO evidence (id, order_id, uploader_id, type, description, file_hash)
-          VALUES (?, ?, ?, 'description', ?, ?)
-        `).run(eid, dispute.order_id, user.id, args.evidence_description, `hash_${Date.now()}`);
-                evidenceIds.push(eid);
+}
+async function handleSecondhand(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    const isPublic = action === 'browse' || action === 'detail';
+    if (!isPublic) {
+        if (!apiKey)
+            return { error: 'api_key required' };
+        const auth = requireAuth(db, apiKey);
+        if ('error' in auth)
+            return auth;
+    }
+    const iid = () => encodeURIComponent(String(args.item_id || ''));
+    switch (action) {
+        case 'browse': {
+            const qs = new URLSearchParams();
+            if (args.category)
+                qs.set('category', String(args.category));
+            if (args.condition)
+                qs.set('condition', String(args.condition));
+            if (args.region)
+                qs.set('region', String(args.region));
+            if (args.min_price != null)
+                qs.set('min_price', String(args.min_price));
+            if (args.max_price != null)
+                qs.set('max_price', String(args.max_price));
+            if (args.query)
+                qs.set('q', String(args.query));
+            if (args.sort)
+                qs.set('sort', String(args.sort));
+            return await pwaApi('GET', '/secondhand?' + qs.toString(), apiKey);
+        }
+        case 'detail': {
+            if (!args.item_id)
+                return { error: 'item_id required' };
+            return await pwaApi('GET', '/secondhand/' + iid(), apiKey);
+        }
+        case 'publish': {
+            if (!args.title || !args.category || !args.condition_grade || args.price == null || !Array.isArray(args.images)) {
+                return { error: 'title + category + condition_grade + price + images[] required' };
+            }
+            return await pwaApi('POST', '/secondhand', apiKey, {
+                title: args.title, description: args.description, category: args.category,
+                condition_grade: args.condition_grade, price: args.price, negotiable: args.negotiable,
+                images: args.images, region: args.region, fulfillment: args.fulfillment,
+            });
+        }
+        case 'update': {
+            if (!args.item_id)
+                return { error: 'item_id required' };
+            const body = {};
+            for (const k of ['title', 'description', 'category', 'condition_grade', 'price', 'negotiable', 'region', 'fulfillment', 'status']) {
+                if (args[k] !== undefined)
+                    body[k] = args[k];
+            }
+            return await pwaApi('PATCH', '/secondhand/' + iid(), apiKey, body);
+        }
+        case 'mine': return await pwaApi('GET', '/secondhand/mine', apiKey);
+        case 'buy': {
+            if (!args.item_id)
+                return { error: 'item_id required' };
+            return await pwaApi('POST', '/secondhand/' + iid() + '/order', apiKey, {
+                fulfillment_mode: args.fulfillment_mode ?? 'shipping',
+                shipping_address: args.shipping_address, notes: args.notes,
+            });
+        }
+        default: return { error: `unknown action: ${action}` };
+    }
+}
+async function handleTrial(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    const isPublic = action === 'get_campaign';
+    if (!isPublic) {
+        if (!apiKey)
+            return { error: 'api_key required' };
+        const auth = requireAuth(db, apiKey);
+        if ('error' in auth)
+            return auth;
+    }
+    const pid = () => encodeURIComponent(String(args.product_id || ''));
+    switch (action) {
+        case 'get_campaign': {
+            if (!args.product_id)
+                return { error: 'product_id required' };
+            return await pwaApi('GET', '/products/' + pid() + '/trial-campaign', apiKey);
+        }
+        case 'apply': {
+            if (!args.product_id)
+                return { error: 'product_id required' };
+            return await pwaApi('POST', '/products/' + pid() + '/trial-claim', apiKey, {});
+        }
+        case 'link_note': {
+            if (!args.claim_id || !args.note_id)
+                return { error: 'claim_id + note_id required' };
+            return await pwaApi('POST', '/trial-claims/' + encodeURIComponent(String(args.claim_id)) + '/link-note', apiKey, { note_id: args.note_id });
+        }
+        case 'my_claims': return await pwaApi('GET', '/me/trial-claims', apiKey);
+        case 'create_campaign': {
+            if (!args.product_id || args.quota_total == null)
+                return { error: 'product_id + quota_total required' };
+            return await pwaApi('POST', '/products/' + pid() + '/trial-campaign', apiKey, {
+                quota_total: args.quota_total, reach_threshold: args.reach_threshold,
+                min_chars: args.min_chars, min_days_live: args.min_days_live,
+            });
+        }
+        case 'cancel_campaign': {
+            if (!args.product_id)
+                return { error: 'product_id required' };
+            return await pwaApi('DELETE', '/products/' + pid() + '/trial-campaign', apiKey);
+        }
+        case 'my_campaigns': return await pwaApi('GET', '/me/seller/trial-campaigns', apiKey);
+        case 'campaign_claims': {
+            if (!args.campaign_id)
+                return { error: 'campaign_id required' };
+            return await pwaApi('GET', '/trial-campaigns/' + encodeURIComponent(String(args.campaign_id)) + '/claims', apiKey);
+        }
+        default: return { error: `unknown action: ${action}` };
+    }
+}
+async function handleSkillMarket(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    const isPublic = action === 'list' || action === 'detail';
+    if (!isPublic) {
+        if (!apiKey)
+            return { error: 'api_key required' };
+        const auth = requireAuth(db, apiKey);
+        if ('error' in auth)
+            return auth;
+    }
+    const sid = () => encodeURIComponent(String(args.skill_id || ''));
+    switch (action) {
+        case 'list': {
+            const qs = new URLSearchParams();
+            if (args.kind)
+                qs.set('kind', String(args.kind));
+            if (args.billing)
+                qs.set('billing', String(args.billing));
+            if (args.query)
+                qs.set('q', String(args.query));
+            return await pwaApi('GET', '/skill-market?' + qs.toString(), apiKey);
+        }
+        case 'detail': {
+            if (!args.skill_id)
+                return { error: 'skill_id required' };
+            return await pwaApi('GET', '/skill-market/' + sid(), apiKey);
+        }
+        case 'publish': {
+            if (!args.title || !args.content || !args.billing_mode)
+                return { error: 'title + content + billing_mode required' };
+            return await pwaApi('POST', '/skill-market', apiKey, {
+                title: args.title, content: args.content, summary: args.summary, preview: args.preview,
+                skill_kind: args.skill_kind, billing_mode: args.billing_mode, price: args.price, category: args.category,
+            });
+        }
+        case 'update': {
+            if (!args.skill_id)
+                return { error: 'skill_id required' };
+            const body = {};
+            for (const k of ['title', 'content', 'summary', 'preview', 'skill_kind', 'billing_mode', 'price', 'category']) {
+                if (args[k] !== undefined)
+                    body[k] = args[k];
             }
+            return await pwaApi('PATCH', '/skill-market/' + sid(), apiKey, body);
         }
-        return respondToDispute(db, args.dispute_id, user.id, args.notes ?? '', evidenceIds);
+        case 'delist': {
+            if (!args.skill_id)
+                return { error: 'skill_id required' };
+            return await pwaApi('POST', '/skill-market/' + sid() + '/delist', apiKey, {});
+        }
+        case 'resubmit': {
+            if (!args.skill_id)
+                return { error: 'skill_id required' };
+            return await pwaApi('POST', '/skill-market/' + sid() + '/resubmit', apiKey, {});
+        }
+        case 'purchase': {
+            if (!args.skill_id)
+                return { error: 'skill_id required' };
+            return await pwaApi('POST', '/skill-market/' + sid() + '/purchase', apiKey, {});
+        }
+        case 'read': {
+            if (!args.skill_id)
+                return { error: 'skill_id required' };
+            return await pwaApi('POST', '/skill-market/' + sid() + '/read', apiKey, {});
+        }
+        case 'my_skills': return await pwaApi('GET', '/skill-market/mine', apiKey);
+        case 'library': return await pwaApi('GET', '/skill-market/library', apiKey);
+        default: return { error: `unknown action: ${action}` };
     }
-    // ── 仲裁员裁定 ─────────────────────────────────────────────
-    if (action === 'arbitrate') {
-        if (!args.dispute_id)
-            return { error: '请提供 dispute_id' };
-        if (!args.ruling)
-            return { error: '请提供 ruling（refund_buyer / release_seller / partial_refund）' };
-        if (!args.ruling_reason)
-            return { error: '请提供 ruling_reason（裁定理由将永久记录）' };
-        if (args.ruling === 'partial_refund' && !args.refund_amount) {
-            return { error: 'partial_refund 需要提供 refund_amount' };
+}
+async function handleRfq(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    if (!apiKey)
+        return { error: 'api_key required' };
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    switch (action) {
+        case 'create': return await pwaApi('POST', '/rfqs', apiKey, {
+            title: args.title, qty: args.qty, max_price: args.max_price,
+            category: args.category, urgency: args.urgency,
+            award_mode: args.award_mode, award_window_min: args.award_window_min,
+            notes: args.notes, shipping_address: args.shipping_address,
+        });
+        case 'mine': return await pwaApi('GET', '/rfqs/mine', apiKey);
+        case 'browse': {
+            const qs = new URLSearchParams();
+            if (args.region)
+                qs.set('region', String(args.region));
+            if (args.category)
+                qs.set('category', String(args.category));
+            if (args.urgency)
+                qs.set('urgency', String(args.urgency));
+            if (args.unbidded)
+                qs.set('unbidded', '1');
+            return await pwaApi('GET', '/rfqs?' + qs.toString(), apiKey);
         }
-        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);
-            if (dispute?.order_id) {
-                const ruling = args.ruling;
-                // refund_buyer → 原告(买家)胜，被告(卖家)败；release_seller → 反之
-                const initiatorId = dispute.initiator_id;
-                const defendantId = dispute.defendant_id;
-                const winnerId = ruling === 'refund_buyer' ? initiatorId : defendantId;
-                const loserId = ruling === 'refund_buyer' ? defendantId : initiatorId;
-                recordDisputeReputation(db, dispute.order_id, winnerId, loserId);
+        case 'detail': {
+            if (!args.rfq_id)
+                return { error: 'rfq_id required' };
+            return await pwaApi('GET', '/rfqs/' + encodeURIComponent(String(args.rfq_id)), apiKey);
+        }
+        case 'award': {
+            if (!args.rfq_id)
+                return { error: 'rfq_id required' };
+            const body = args.bid_id ? { bid_id: args.bid_id } : {};
+            return await pwaApi('POST', '/rfqs/' + encodeURIComponent(String(args.rfq_id)) + '/award', apiKey, body);
+        }
+        case 'cancel': {
+            if (!args.rfq_id)
+                return { error: 'rfq_id required' };
+            return await pwaApi('DELETE', '/rfqs/' + encodeURIComponent(String(args.rfq_id)), apiKey);
+        }
+        default: return { error: `unknown action: ${action}` };
+    }
+}
+async function handleBid(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    if (!apiKey)
+        return { error: 'api_key required' };
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    switch (action) {
+        case 'submit': {
+            if (!args.rfq_id || !args.price)
+                return { error: 'rfq_id + price required' };
+            return await pwaApi('POST', '/rfqs/' + encodeURIComponent(String(args.rfq_id)) + '/bids', apiKey, {
+                price: args.price, qty_offered: args.qty_offered,
+                eta_hours: args.eta_hours, fulfillment_type: args.fulfillment_type ?? 'standard',
+                note: args.note, offer_id: args.offer_id,
+            });
+        }
+        case 'patch': {
+            if (!args.bid_id)
+                return { error: 'bid_id required' };
+            const body = {};
+            for (const k of ['price', 'qty_offered', 'eta_hours', 'fulfillment_type', 'note']) {
+                if (args[k] !== undefined)
+                    body[k] = args[k];
             }
+            return await pwaApi('PATCH', '/bids/' + encodeURIComponent(String(args.bid_id)), apiKey, body);
         }
-        return result;
+        case 'cancel': {
+            if (!args.bid_id)
+                return { error: 'bid_id required' };
+            return await pwaApi('DELETE', '/bids/' + encodeURIComponent(String(args.bid_id)), apiKey);
+        }
+        case 'list_mine': {
+            const rows = db.prepare(`
+        SELECT b.*, r.title as rfq_title, r.buyer_id, r.status as rfq_status
+        FROM bids b JOIN rfqs r ON r.id = b.rfq_id
+        WHERE b.seller_id = ? ORDER BY b.submitted_at DESC LIMIT 100
+      `).all(auth.user.id);
+            return { items: rows };
+        }
+        default: return { error: `unknown action: ${action}` };
     }
-    return { error: `未知 action：${action}` };
 }
-// ─── Skill 市场处理 ────────────────────────────────────────────
-function handleSkill(args) {
-    const action = args.action;
-    // ── 浏览 Skill 市场 ────────────────────────────────────────
-    if (action === 'list') {
-        let userId;
-        if (args.api_key) {
-            const a = requireAuth(db, args.api_key);
-            if (!('error' in a))
-                userId = a.user.id;
+async function handleChat(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    if (!apiKey)
+        return { error: 'api_key required' };
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    switch (action) {
+        case 'start': {
+            if (!args.kind || !args.context_id)
+                return { error: 'kind + context_id required' };
+            return await pwaApi('POST', '/conversations/start', apiKey, {
+                kind: args.kind, context_id: args.context_id, recipient_id: args.recipient_id,
+            });
         }
-        const skills = listSkills(db, {
-            skillType: args.skill_type,
-            query: args.query,
-            subscriberId: userId,
-            limit: 20,
-        });
-        return {
-            total: skills.length,
-            skill_types: Object.entries(SKILL_TYPE_META).map(([k, v]) => ({ type: k, label: v.label, icon: v.icon, description: v.description })),
-            skills: skills.map(formatSkillForAgent),
-        };
+        case 'list': return await pwaApi('GET', '/conversations', apiKey);
+        case 'read': {
+            if (!args.conversation_id)
+                return { error: 'conversation_id required' };
+            return await pwaApi('GET', '/conversations/' + encodeURIComponent(String(args.conversation_id)), apiKey);
+        }
+        case 'send': {
+            if (!args.conversation_id || !args.body)
+                return { error: 'conversation_id + body required' };
+            return await pwaApi('POST', '/conversations/' + encodeURIComponent(String(args.conversation_id)) + '/messages', apiKey, { body: args.body });
+        }
+        case 'mark_read': {
+            if (!args.conversation_id)
+                return { error: 'conversation_id required' };
+            return await pwaApi('POST', '/conversations/' + encodeURIComponent(String(args.conversation_id)) + '/read', apiKey);
+        }
+        case 'block': {
+            if (!args.conversation_id)
+                return { error: 'conversation_id required' };
+            return await pwaApi('POST', '/conversations/' + encodeURIComponent(String(args.conversation_id)) + '/block', apiKey);
+        }
+        default: return { error: `unknown action: ${action}` };
     }
-    // 以下操作需要身份验证
-    const auth = requireAuth(db, args.api_key);
+}
+async function handleAutoBidSkill(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    if (!apiKey)
+        return { error: 'api_key required' };
+    const auth = requireAuth(db, apiKey);
     if ('error' in auth)
         return auth;
-    const { user } = auth;
-    // ── 发布 Skill ────────────────────────────────────────────
-    if (action === 'publish') {
-        if (!args.name)
-            return { error: '请填写 Skill 名称（name）' };
-        if (!args.description)
-            return { error: '请填写 Skill 描述（description）' };
-        if (!args.skill_type)
-            return { error: '请选择 Skill 类型（skill_type）' };
-        const skill = publishSkill(db, {
-            sellerId: user.id,
-            name: args.name,
-            description: args.description,
-            category: args.category,
-            skillType: args.skill_type,
-            config: args.config,
-        });
-        const meta = SKILL_TYPE_META[skill.skill_type];
-        return {
-            success: true,
-            skill_id: skill.id,
-            message: `✅ Skill 「${skill.name}」已发布到 WebAZ Skill 市场！买家 Agent 现在可以订阅它。`,
-            type: `${meta.icon} ${meta.label}`,
-            tip: 'auto_accept Skill 发布后，买家新订单将自动被接受（无需手动操作）',
+    if (auth.user.role !== 'seller')
+        return { error: 'only seller can use auto_bid' };
+    const existing = db.prepare(`SELECT id, config, active FROM skills WHERE seller_id = ? AND skill_type = 'auto_bid' ORDER BY created_at DESC LIMIT 1`).get(auth.user.id);
+    if (action === 'get') {
+        if (!existing)
+            return { exists: false };
+        let cfg = {};
+        try {
+            cfg = JSON.parse(existing.config || '{}');
+        }
+        catch { }
+        return { exists: true, id: existing.id, active: existing.active, config: cfg };
+    }
+    if (action === 'set') {
+        const config = {
+            enabled: args.enabled !== false,
+            categories: Array.isArray(args.categories) ? args.categories : ['standard'],
+            regions: Array.isArray(args.regions) ? args.regions : [],
+            max_eta_h: Number(args.max_eta_h ?? 24),
+            fulfillment_type: String(args.fulfillment_type ?? 'standard'),
+            bid_strategy: String(args.bid_strategy ?? 'cheapest_undercut'),
+            undercut_pct: Math.max(0, Math.min(0.5, Number(args.undercut_pct ?? 0.05))),
+            max_price_cap: args.max_price_cap ?? null,
+            daily_cap: Number(args.daily_cap ?? 20),
+            cooldown_min: Number(args.cooldown_min ?? 60),
         };
+        if (existing) {
+            return await pwaApi('PATCH', '/skills/' + encodeURIComponent(existing.id), apiKey, { config, active: config.enabled ? 1 : 0 });
+        }
+        return await pwaApi('POST', '/skills', apiKey, {
+            name: '我的自动报价 (MCP)', description: 'auto_bid via MCP', category: 'rfq', skill_type: 'auto_bid', config,
+        });
     }
-    // ── 订阅 Skill ────────────────────────────────────────────
-    if (action === 'subscribe') {
-        if (!args.skill_id)
-            return { error: '请提供 skill_id' };
-        const result = subscribeSkill(db, user.id, args.skill_id, args.config);
-        return { ...result, skill_id: args.skill_id };
+    if (action === 'disable') {
+        if (!existing)
+            return { error: '尚未创建 auto_bid Skill' };
+        return await pwaApi('POST', '/skills/' + encodeURIComponent(existing.id) + '/disable', apiKey);
     }
-    // ── 取消订阅 ──────────────────────────────────────────────
-    if (action === 'unsubscribe') {
-        if (!args.skill_id)
-            return { error: '请提供 skill_id' };
-        unsubscribeSkill(db, user.id, args.skill_id);
-        return { success: true, message: '已取消订阅' };
+    return { error: `unknown action: ${action}` };
+}
+async function handlePriceHistory(args) {
+    const pid = String(args.product_id || '');
+    if (!pid)
+        return { error: 'product_id required' };
+    try {
+        const r = await fetch(PWA_API_BASE + '/products/' + encodeURIComponent(pid) + '/price-history');
+        return await r.json();
     }
-    // ── 我发布的 Skill ────────────────────────────────────────
-    if (action === 'my_skills') {
-        const skills = getMySkills(db, user.id);
-        return {
-            total: skills.length,
-            skills: skills.map(formatSkillForAgent),
-            tip: skills.length === 0 ? '还没有发布任何 Skill。用 webaz_skill action=publish 发布你的第一个 Skill。' : undefined,
-        };
+    catch (e) {
+        return { error: String(e.message) };
     }
-    // ── 我订阅的 Skill ────────────────────────────────────────
-    if (action === 'my_subs') {
-        const skills = getMySubscriptions(db, user.id);
-        return {
-            total: skills.length,
-            subscriptions: skills.map(formatSkillForAgent),
-            tip: skills.length === 0 ? '还没有订阅任何 Skill。用 webaz_skill action=list 浏览市场。' : undefined,
-        };
+}
+async function handleCharity(args) {
+    const action = String(args.action || '');
+    if (action === 'list') {
+        const qs = new URLSearchParams();
+        if (args.category)
+            qs.set('category', String(args.category));
+        if (args.target_kind)
+            qs.set('target_kind', String(args.target_kind));
+        if (args.limit)
+            qs.set('limit', String(args.limit));
+        try {
+            const r = await fetch(PWA_API_BASE + '/wishes' + (qs.toString() ? '?' + qs : ''));
+            return await r.json();
+        }
+        catch (e) {
+            return { error: String(e.message) };
+        }
     }
-    return { error: `未知 action：${action}。可选：list, publish, subscribe, unsubscribe, my_skills, my_subs` };
+    if (action === 'detail') {
+        if (!args.wish_id)
+            return { error: 'wish_id required' };
+        try {
+            const r = await fetch(PWA_API_BASE + '/wishes/' + encodeURIComponent(String(args.wish_id)));
+            return await r.json();
+        }
+        catch (e) {
+            return { error: String(e.message) };
+        }
+    }
+    if (action === 'stories') {
+        try {
+            const r = await fetch(PWA_API_BASE + '/charity/stories');
+            return await r.json();
+        }
+        catch (e) {
+            return { error: String(e.message) };
+        }
+    }
+    if (action === 'leaderboard') {
+        try {
+            const r = await fetch(PWA_API_BASE + '/charity/leaderboard');
+            return await r.json();
+        }
+        catch (e) {
+            return { error: String(e.message) };
+        }
+    }
+    if (action === 'fund') {
+        try {
+            const r = await fetch(PWA_API_BASE + '/charity/fund');
+            return await r.json();
+        }
+        catch (e) {
+            return { error: String(e.message) };
+        }
+    }
+    const apiKey = String(args.api_key || '');
+    if (!apiKey)
+        return { error: 'api_key required for this action' };
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    if (action === 'create') {
+        return await pwaApi('POST', '/wishes', apiKey, {
+            title: args.title, content: args.content, category: args.category,
+            target_kind: args.target_kind, target_waz: args.target_waz, escrow_self: args.escrow_self,
+            window_hours: args.window_hours, allow_public: args.allow_public,
+        });
+    }
+    if (action === 'me')
+        return await pwaApi('GET', '/charity/me', apiKey);
+    if (action === 'donate')
+        return await pwaApi('POST', '/charity/fund/donate', apiKey, { amount: args.amount, note: args.note });
+    if (!args.wish_id)
+        return { error: 'wish_id required' };
+    const id = encodeURIComponent(String(args.wish_id));
+    if (action === 'claim')
+        return await pwaApi('POST', '/wishes/' + id + '/fulfill', apiKey);
+    if (action === 'proof')
+        return await pwaApi('POST', '/wishes/' + id + '/proof', apiKey, { proof_hash: args.proof_hash, proof_note: args.proof_note });
+    if (action === 'confirm')
+        return await pwaApi('POST', '/wishes/' + id + '/confirm', apiKey, { fulfillment_id: args.fulfillment_id });
+    if (action === 'disclose')
+        return await pwaApi('POST', '/wishes/' + id + '/disclose', apiKey);
+    if (action === 'cancel')
+        return await pwaApi('POST', '/wishes/' + id + '/cancel', apiKey);
+    if (action === 'repay')
+        return await pwaApi('POST', '/wishes/' + id + '/repay', apiKey, { fulfillment_id: args.fulfillment_id, amount: args.amount, note: args.note });
+    if (action === 'repay_respond') {
+        if (!args.repay_id)
+            return { error: 'repay_id required' };
+        return await pwaApi('POST', '/wishes/' + id + '/repay/' + encodeURIComponent(String(args.repay_id)) + '/respond', apiKey, { choice: args.choice });
+    }
+    return { error: `unknown action: ${action}` };
 }
-function handleMyKey(args) {
-    const name = args.name?.trim();
-    if (!name)
-        return { error: 'name is required' };
-    const users = db.prepare(`SELECT name, role, roles, api_key FROM users WHERE name = ? AND id != 'sys_protocol'`).all(name);
-    if (users.length === 0)
-        return { error: `No account found with name "${name}"` };
-    return {
-        found: users.length,
-        accounts: users.map(u => ({
-            name: u.name,
-            role: u.role,
-            roles: JSON.parse(u.roles || JSON.stringify([u.role])),
-            api_key: u.api_key,
-        })),
-        tip: 'Keep your api_key safe — it is your identity on the protocol.',
-    };
+async function handleP2pProduct(args) {
+    const action = String(args.action || '');
+    if (action === 'list') {
+        try {
+            const r = await fetch(PWA_API_BASE + '/p2p-products');
+            return await r.json();
+        }
+        catch (e) {
+            return { error: String(e.message) };
+        }
+    }
+    if (action === 'detail') {
+        if (!args.product_id)
+            return { error: 'product_id required' };
+        try {
+            const r = await fetch(PWA_API_BASE + '/p2p-products/' + encodeURIComponent(String(args.product_id)));
+            return await r.json();
+        }
+        catch (e) {
+            return { error: String(e.message) };
+        }
+    }
+    const apiKey = String(args.api_key || '');
+    if (!apiKey)
+        return { error: 'api_key required for create/patch' };
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    if (action === 'create') {
+        return await pwaApi('POST', '/p2p-products', apiKey, {
+            title: args.title, price: args.price, stock: args.stock,
+            content_hash: args.content_hash, content_signature: args.content_signature, content_signed_at: args.content_signed_at,
+            peer_endpoint: args.peer_endpoint, thumbnail_uri: args.thumbnail_uri,
+            category: args.category, region: args.region,
+        });
+    }
+    if (action === 'patch') {
+        if (!args.product_id)
+            return { error: 'product_id required' };
+        const body = {};
+        for (const k of ['title', 'price', 'stock', 'content_hash', 'content_signature', 'content_signed_at', 'peer_endpoint']) {
+            if (args[k] !== undefined)
+                body[k] = args[k];
+        }
+        return await pwaApi('PATCH', '/p2p-products/' + encodeURIComponent(String(args.product_id)), apiKey, body);
+    }
+    return { error: `unknown action: ${action}` };
 }
-function handleProfile(args) {
-    const auth = requireAuth(db, args.api_key);
+async function handleLike(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    const sid = String(args.shareable_id || '');
+    if (!apiKey || !sid)
+        return { error: 'api_key + shareable_id required' };
+    const auth = requireAuth(db, apiKey);
     if ('error' in auth)
         return auth;
-    const { user } = auth;
-    const action = args.action;
-    const roles = JSON.parse(user.roles || JSON.stringify([user.role]));
-    if (action === 'view') {
-        const wallet = db.prepare('SELECT balance, staked, escrowed, earned FROM wallets WHERE user_id = ?').get(user.id);
-        return {
-            id: user.id,
-            name: user.name,
-            active_role: user.role,
-            roles,
-            api_key: user.api_key,
-            wallet,
-            tip: 'Use add_role to add a new role, switch_role to change your active role.',
-        };
+    if (action === 'toggle')
+        return await pwaApi('POST', '/shareables/' + encodeURIComponent(sid) + '/like', apiKey);
+    if (action === 'status')
+        return await pwaApi('GET', '/shareables/' + encodeURIComponent(sid) + '/like-status', apiKey);
+    return { error: `unknown action: ${action}` };
+}
+async function handleLeaderboard(args) {
+    const kind = String(args.kind || 'products');
+    const limit = Number(args.limit || 20);
+    const VALID_KINDS = ['products', 'creators', 'buyers', 'sellers', 'value_products', 'agents', 'arbitrators', 'verifiers'];
+    if (!VALID_KINDS.includes(kind))
+        return { error: `kind 必须是 ${VALID_KINDS.join(' / ')}` };
+    // 排行榜公开（不需 api_key）；但 pwaApi 需要 — 用空 key 调（PWA 端 leaderboard 路由没 auth）
+    // 简化：直接调 fetch
+    try {
+        const r = await fetch(PWA_API_BASE + '/leaderboard?kind=' + kind + '&limit=' + limit);
+        return await r.json();
     }
-    const validRoles = ['buyer', 'seller', 'logistics', 'arbitrator'];
-    const role = args.role;
-    if (action === 'add_role') {
-        if (!validRoles.includes(role))
-            return { error: `Invalid role. Options: ${validRoles.join(', ')}` };
-        if (roles.includes(role))
-            return { error: `You already have the "${role}" role` };
-        roles.push(role);
-        db.prepare("UPDATE users SET roles = ?, updated_at = datetime('now') WHERE id = ?").run(JSON.stringify(roles), user.id);
-        return { success: true, active_role: user.role, roles, message: `Role "${role}" added. Use switch_role to activate it.` };
+    catch (e) {
+        return { error: `PWA API unreachable: ${e.message}` };
     }
-    if (action === 'switch_role') {
-        if (!validRoles.includes(role))
-            return { error: `Invalid role. Options: ${validRoles.join(', ')}` };
-        if (!roles.includes(role))
-            return { error: `You don't have the "${role}" role yet. Use add_role first.` };
-        db.prepare("UPDATE users SET role = ?, updated_at = datetime('now') WHERE id = ?").run(role, user.id);
-        return { success: true, active_role: role, roles, message: `Switched to "${role}" mode.` };
+}
+async function handleAuction(args) {
+    const apiKey = String(args.api_key || '');
+    const action = String(args.action || '');
+    if (!apiKey)
+        return { error: 'api_key required' };
+    const auth = requireAuth(db, apiKey);
+    if ('error' in auth)
+        return auth;
+    switch (action) {
+        case 'create': return await pwaApi('POST', '/auctions', apiKey, {
+            title: args.title, qty: args.qty, category: args.category,
+            starting_price: args.starting_price, min_increment: args.min_increment,
+            reserve_price: args.reserve_price, window_min: args.window_min,
+            sniper_extend_min: args.sniper_extend_min, notes: args.notes,
+        });
+        case 'browse': {
+            const qs = new URLSearchParams();
+            if (args.category)
+                qs.set('category', String(args.category));
+            return await pwaApi('GET', '/auctions?' + qs.toString(), apiKey);
+        }
+        case 'mine': return await pwaApi('GET', '/auctions/mine', apiKey);
+        case 'detail': {
+            if (!args.auction_id)
+                return { error: 'auction_id required' };
+            return await pwaApi('GET', '/auctions/' + encodeURIComponent(String(args.auction_id)), apiKey);
+        }
+        case 'bid': {
+            if (!args.auction_id || !args.price)
+                return { error: 'auction_id + price required' };
+            return await pwaApi('POST', '/auctions/' + encodeURIComponent(String(args.auction_id)) + '/bids', apiKey, { price: args.price });
+        }
+        case 'cancel': {
+            if (!args.auction_id)
+                return { error: 'auction_id required' };
+            return await pwaApi('DELETE', '/auctions/' + encodeURIComponent(String(args.auction_id)), apiKey);
+        }
+        default: return { error: `unknown action: ${action}` };
     }
-    return { error: `Unknown action: ${action}. Options: view, add_role, switch_role` };
 }
 // ─── 结算逻辑（买家确认后自动执行）──────────────────────────────
+// QA P1（轮 6j）：旧版 2% protocolFee 从 buyer escrow 扣下来但不 payout 给任何账户 → 钱凭空消失。
+// 修：路由到 sys_protocol；返回 settlement_breakdown 显式列出每分钱去向 + sum_check 验证恒等。
 function settleOrder(db, orderId) {
     const order = db.prepare('SELECT * FROM orders WHERE id = ?').get(orderId);
     const totalAmount = order.total_amount;
@@ -1038,11 +3862,15 @@ function settleOrder(db, orderId) {
     const buyerId = order.buyer_id;
     const logisticsId = order.logistics_id;
     const promoterId = order.promoter_id;
-    // 分成比例（协议参数，未来可治理调整）
-    const protocolFee = Math.round(totalAmount * 0.02 * 100) / 100; // 2% 协议费
-    const logisticsFee = Math.round(totalAmount * 0.05 * 100) / 100; // 5% 物流
-    const promoterFee = promoterId ? Math.round(totalAmount * 0.03 * 100) / 100 : 0; // 3% 推荐
-    const sellerAmount = totalAmount - protocolFee - logisticsFee - promoterFee;
+    const donationAmount = order.donation_amount || 0;
+    // 分成比例（协议参数，未来可治理调整 — 注意：这里写死的比率跟 protocol_params 表里的 0.05/0.10 不一致，QA 也抓到，单独 follow-up）
+    const round2 = (n) => Math.round(n * 100) / 100;
+    const isSelfFulfill = !logisticsId; // Phase 1: 无 logistics_id 即 seller 自负物流
+    const protocolFee = round2(totalAmount * 0.02);
+    // self-fulfill 时 seller 已承担 logistics 责任，不再扣 5% — 否则违反"无责方零成本 / 责任方应得回报"原则
+    const logisticsFee = isSelfFulfill ? 0 : round2(totalAmount * 0.05);
+    const promoterFee = promoterId ? round2(totalAmount * 0.03) : 0;
+    const sellerAmount = round2(totalAmount - protocolFee - logisticsFee - promoterFee - donationAmount);
     const payout = (recipientId, role, amount, reason) => {
         if (amount <= 0)
             return;
@@ -1059,12 +3887,41 @@ function settleOrder(db, orderId) {
         payout(logisticsId, 'logistics', logisticsFee, 'logistics_fee');
     if (promoterId)
         payout(promoterId, 'promoter', promoterFee, 'promoter_fee');
-    // 归还卖家质押
-    const product = db.prepare('SELECT stake_amount FROM products WHERE id = ?').get(order.product_id);
-    db.prepare(`UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?`)
-        .run(product.stake_amount, product.stake_amount, sellerId);
-    // L4-3 声誉积分：交易完成后自动更新各方声誉
+    // P1 修复：protocolFee 实际收款方 — 之前没人收
+    if (protocolFee > 0)
+        payout('sys_protocol', 'protocol_fund', protocolFee, 'protocol_fee_2pct');
+    // 捐赠（如有）→ 进 charity_fund 池子
+    if (donationAmount > 0) {
+        db.prepare(`UPDATE charity_fund SET balance = balance + ?, total_donated = total_donated + ?, updated_at = datetime('now') WHERE id = 'main'`).run(donationAmount, donationAmount);
+    }
+    // QA 轮 7 P0 修复 — 改 per-order stake 释放
+    // 不再读 product.stake_amount（旧 per-product 模型残留），改按本订单总额的 stake_rate 计算
+    // 跟 handlePlaceOrder 锁的值一一对应，保证守恒
+    const sellerStakeRate = 0.15;
+    const stakeReturned = Math.round(totalAmount * sellerStakeRate * 100) / 100;
+    if (stakeReturned > 0) {
+        db.prepare(`UPDATE wallets SET staked = staked - ?, balance = balance + ? WHERE user_id = ?`)
+            .run(stakeReturned, stakeReturned, sellerId);
+    }
+    // L4-3 声誉积分
     recordOrderReputation(db, orderId);
+    // P1 修复：显式 breakdown 让 caller 把每分钱去向暴给 agent
+    const sumCheck = round2(sellerAmount + logisticsFee + promoterFee + protocolFee + donationAmount);
+    return {
+        order_amount: totalAmount,
+        distribution: {
+            seller_net: { amount: sellerAmount, to: sellerId, rate: isSelfFulfill ? '~98% (含 logistics work)' : '~93%' },
+            logistics_fee: { amount: logisticsFee, to: logisticsId, rate: isSelfFulfill ? 'N/A (self-fulfill: seller 承担)' : '5%' },
+            promoter_fee: { amount: promoterFee, to: promoterId, rate: promoterId ? '3%' : 'N/A' },
+            protocol_fund: { amount: protocolFee, to: 'sys_protocol', rate: '2%' },
+            charity_donation: { amount: donationAmount, to: 'charity_fund', rate: donationAmount > 0 ? 'buyer-chosen' : 'N/A' },
+        },
+        fulfillment_mode: isSelfFulfill ? 'self' : 'market',
+        sum_check: sumCheck,
+        sum_check_ok: Math.abs(sumCheck - totalAmount) < 0.01,
+        seller_stake_returned: stakeReturned,
+        note: 'sum_check_ok=true 说明 buyer 付的金额完全等于所有分配之和，无遗漏。',
+    };
 }
 // ─── MCP Server 主体 ──────────────────────────────────────────
 export async function startMCPServer() {
@@ -1098,6 +3955,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) {
@@ -1108,25 +3966,31 @@ export async function startMCPServer() {
                     result = handleRegister(args);
                     break;
                 case 'webaz_search':
-                    result = handleSearch(args);
+                    result = await handleSearch(args);
+                    break;
+                case 'webaz_verify_price':
+                    result = handleVerifyPrice(args);
                     break;
                 case 'webaz_list_product':
-                    result = handleListProduct(args);
+                    result = await handleListProduct(args);
                     break;
                 case 'webaz_place_order':
                     result = handlePlaceOrder(args);
                     break;
                 case 'webaz_update_order':
-                    result = handleUpdateOrder(args);
+                    result = await handleUpdateOrder(args);
                     break;
                 case 'webaz_get_status':
                     result = handleGetStatus(args);
                     break;
                 case 'webaz_wallet':
-                    result = handleWallet(args);
+                    result = await handleWallet(args);
                     break;
                 case 'webaz_dispute':
-                    result = handleDispute(args);
+                    result = await handleDispute(args);
+                    break;
+                case 'webaz_claim_verify':
+                    result = await handleClaimVerify(args);
                     break;
                 case 'webaz_notifications':
                     result = handleNotifications(args);
@@ -1134,11 +3998,77 @@ export async function startMCPServer() {
                 case 'webaz_skill':
                     result = handleSkill(args);
                     break;
+                case 'webaz_skill_market':
+                    result = await handleSkillMarket(args);
+                    break;
+                case 'webaz_secondhand':
+                    result = await handleSecondhand(args);
+                    break;
+                case 'webaz_trial':
+                    result = await handleTrial(args);
+                    break;
                 case 'webaz_mykey':
                     result = handleMyKey(args);
                     break;
                 case 'webaz_profile':
-                    result = handleProfile(args);
+                    result = await handleProfile(args);
+                    break;
+                case 'webaz_revoke_key':
+                    result = handleRevokeKey(args);
+                    break;
+                case 'webaz_rotate_key':
+                    result = handleRotateKey(args);
+                    break;
+                case 'webaz_referral':
+                    result = handleReferral(args);
+                    break;
+                case 'webaz_share_link':
+                    result = handleShareLink(args);
+                    break;
+                case 'webaz_blocklist':
+                    result = handleBlocklist(args);
+                    break;
+                case 'webaz_follows':
+                    result = handleFollows(args);
+                    break;
+                case 'webaz_nearby':
+                    result = handleNearby(args);
+                    break;
+                case 'webaz_default_address':
+                    result = handleDefaultAddress(args);
+                    break;
+                case 'webaz_shareables':
+                    result = handleShareables(args);
+                    break;
+                case 'webaz_rfq':
+                    result = await handleRfq(args);
+                    break;
+                case 'webaz_bid':
+                    result = await handleBid(args);
+                    break;
+                case 'webaz_chat':
+                    result = await handleChat(args);
+                    break;
+                case 'webaz_auto_bid':
+                    result = await handleAutoBidSkill(args);
+                    break;
+                case 'webaz_auction':
+                    result = await handleAuction(args);
+                    break;
+                case 'webaz_like':
+                    result = await handleLike(args);
+                    break;
+                case 'webaz_p2p_product':
+                    result = await handleP2pProduct(args);
+                    break;
+                case 'webaz_charity':
+                    result = await handleCharity(args);
+                    break;
+                case 'webaz_price_history':
+                    result = await handlePriceHistory(args);
+                    break;
+                case 'webaz_leaderboard':
+                    result = await handleLeaderboard(args);
                     break;
                 default: result = { error: `未知工具：${name}` };
             }
@@ -1146,6 +4076,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 +4089,49 @@ 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;
+        // #1017 fix: mcp_tool_calls schema 是 user_id_hash 不是 user_id；无 error_msg 列
+        // errorMsg 单独走 sendTelemetry → 服务端聚合，DB 只留汇总指标
+        const userIdHash = userId ? createHash('sha256').update(userId).digest('hex').slice(0, 16) : null;
+        db.prepare(`INSERT INTO mcp_tool_calls (tool_name, user_id_hash, outcome, latency_ms)
+       VALUES (?, ?, ?, ?)`).run(tool, userIdHash, isError ? 'error' : 'success', latencyMs);
+        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 */ }
+}