@seasonkoh/webaz 0.1.24 → 0.1.26

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

@@ -22,6 +22,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, // #B.1 a — MCP 三大原语之 Prompts
 GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { initDatabase, generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+import { setSeamDb } from '../../layer0-foundation/L0-1-database/db.js'; // RFC-016 异步 DB seam(本进程注入)
 import { transition, getOrderStatus, initSystemUser, } from '../../layer0-foundation/L0-2-state-machine/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';
@@ -42,6 +43,15 @@ const TELEMETRY_ENABLED = (process.env.WEBAZ_TELEMETRY ?? 'off').toLowerCase() =
 // P0 不迁移任何工具(NETWORK_TOOLS 为空)→ 一切仍走本地 = 零行为变化;P1/P2 逐个把工具名加入集合切到网络。
 const WEBAZ_API_URL = (process.env.WEBAZ_API_URL ?? 'https://webaz.xyz').replace(/\/+$/, '');
 const WEBAZ_API_KEY = process.env.WEBAZ_API_KEY ?? '';
+// F6 (dogfood R2): keyed MCP handlers resolve api_key as  explicit args.api_key  >  env WEBAZ_API_KEY  >
+// '' (→ the existing typed API_KEY_REQUIRED guards). Explicit ALWAYS wins; env never overrides an explicit
+// key. Keyless actions (list/discover/detail/suggest/browse/get_campaign…) gate their public branches
+// separately and never call this, so a configured env key does NOT change the public read boundary.
+// The key is never printed/returned/logged.
+export function resolveMcpApiKey(args, envKey = WEBAZ_API_KEY) {
+    const explicit = typeof args?.api_key === 'string' ? args.api_key.trim() : '';
+    return explicit || envKey;
+}
 const WEBAZ_MODE_ENV = (process.env.WEBAZ_MODE ?? '').toLowerCase();
 // 模式:显式 WEBAZ_MODE 优先;否则有 api_key → network,无 key → network_readonly(装完即见真网络)。
 // network_readonly(L1 onboarding,2026-06-08):无 key 默认。公共读匿名打 webaz.xyz(真 catalog/协议),
@@ -184,6 +194,7 @@ function modeBanner() {
 }
 // ─── 初始化 ──────────────────────────────────────────────────
 const db = initDatabase();
+setSeamDb(db); // RFC-016 Phase 1:注入异步 DB seam(本进程)—— 共享引擎迁 seam 后 MCP 进程也能用,否则 dbOne/dbAll 抛"未初始化"
 initSystemUser(db);
 initDisputeSchema(db);
 initNotificationSchema(db);
@@ -323,7 +334,7 @@ No auth required, no parameters needed.
 
 Roles: buyer (browse/order/confirm) | seller (list/accept/ship) | logistics (pickup/transit/deliver) | reviewer (reviews) | arbitrator (disputes/rulings).
 
-⚠️ **MCP register limitations (anti-bot, by design)**: does NOT set placement_id/sponsor_id — referral/PV chain NOT built via MCP. To build chain: user must arrive via webaz_share_link \`?ref=<uid>\` URL clicked in browser (PWA flow). region defaults 'global'; valid: singapore/china/usa/malaysia/indonesia/thailand/vietnam/taiwan/hk/global.`,
+⚠️ **MCP register limitations (anti-bot, by design)**: does NOT set placement_id/sponsor_id — referral/PV chain NOT built via MCP. To build chain: user must arrive via webaz_share_link \`/i/<permanent_code>\` (or \`?ref=<permanent_code>\`) URL clicked in browser (PWA flow). region defaults 'global'; valid: singapore/china/usa/malaysia/indonesia/thailand/vietnam/taiwan/hk/global.`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -401,11 +412,11 @@ Skipping is allowed but agent then carries price/stock-race risk itself.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Buyer's api_key" },
+                api_key: { type: 'string', description: "Buyer's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 product_id: { type: 'string', description: 'Product ID (from webaz_search)' },
                 quantity: { type: 'number', description: 'Quantity, default 1' },
             },
-            required: ['api_key', 'product_id'],
+            required: ['product_id'],
         },
     },
     {
@@ -421,7 +432,7 @@ Actions: create (title/description/price) | mine | update (product_id + changed
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Seller's api_key" },
+                api_key: { type: 'string', description: "Seller's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 action: {
                     type: 'string',
                     enum: ['create', 'mine', 'update', 'delist', 'relist', 'trash', 'delete'],
@@ -477,7 +488,7 @@ Actions: create (title/description/price) | mine | update (product_id + changed
                     description: '[S4] Product-origin claims (challengeable). E.g. {"made_in":"Kyoto JP","material":"100% cotton GOTS-cert","certs":[{"name":"GOTS","sha256":"<64-hex>"}]}. Total JSON ≤4KB; any cert sha256 must be 64-hex. Any buyer can challenge.',
                 },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -499,7 +510,7 @@ Options:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Buyer's api_key" },
+                api_key: { type: 'string', description: "Buyer's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 product_id: { type: 'string', description: 'Product ID to buy (from webaz_search)' },
                 quantity: { type: 'number', description: 'Quantity, default 1' },
                 shipping_address: { type: 'string', description: 'Shipping address' },
@@ -524,7 +535,7 @@ Options:
                     description: '[B5] Per-order donation pct (0 / 0.5 / 1 / 2 / 5). Computed separately + into charity_fund, posted on order complete.',
                 },
             },
-            required: ['api_key', 'product_id', 'shipping_address'],
+            required: ['product_id', 'shipping_address'],
         },
     },
     {
@@ -532,15 +543,15 @@ Options:
         // was ~927 chars, now ~430 chars
         description: `STATUS TRANSITIONS on an order — NOT for editing order content (price/qty/address immutable after creation). Each role can only perform their own actions.
 
-- **Seller**: accept (24h after payment) | ship (needs tracking, within handling time)
-- **Logistics**: pickup (48h after ship) | transit | deliver (needs proof description)
+- **Seller**: accept (24h after payment) | ship (needs tracking/notes, within handling time) | pickup/transit/deliver ONLY when order.logistics_id is empty (Phase-1 self-fulfill; seller carries logistics responsibility) | decline (actively refuse a PAID order instead of silent timeout; requires decline_reason_code — objective codes [stock_consumed_concurrent/stale_price_snapshot/force_majeure] go to a PROVISIONAL fault you must then contest within the window, NOT auto-cleared; subjective codes [price_regret/cherry_pick/other] settle immediately as seller-fault + buyer refund) | contest_decline (open human arbitration on an objective-claimed provisional fault, within the contest window, to be cleared to no-fault; pass evidence_description — window expiry finalizes as fault)
+- **Logistics**: pickup (48h after ship) | transit | deliver (needs proof description) when assigned or claiming an unassigned shipped order
 - **Buyer**: confirm (→ fund settlement) | dispute (needs reason; freezes funds → arbitration)
 
 Missing deadline → protocol auto-marks party in default.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Operator's api_key" },
+                api_key: { type: 'string', description: "Operator's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 order_id: { type: 'string', description: 'Order ID' },
                 action: {
                     type: 'string',
@@ -558,7 +569,7 @@ Missing deadline → protocol auto-marks party in default.`,
                     description: 'Evidence description (recommended for ship/pickup/deliver; required for dispute)',
                 },
             },
-            required: ['api_key', 'order_id', 'action'],
+            required: ['order_id', 'action'],
         },
     },
     {
@@ -568,10 +579,10 @@ Missing deadline → protocol auto-marks party in default.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Querier's api_key" },
+                api_key: { type: 'string', description: "Querier's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 order_id: { type: 'string', description: 'Order ID' },
             },
-            required: ['api_key', 'order_id'],
+            required: ['order_id'],
         },
     },
     {
@@ -589,14 +600,14 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['view', 'deposits', 'withdrawals', 'income'],
                     description: 'Action type (default: view)',
                 },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -608,11 +619,11 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 unread: { type: 'boolean', description: 'Return only unread (default false)' },
                 mark_read: { type: 'boolean', description: 'Auto-mark read after call (default false)' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -635,7 +646,7 @@ Protocol auto-judges (no human): respondent silent 48h → favor initiator; arbi
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: "Operator's api_key" },
+                api_key: { type: 'string', description: "Operator's api_key (or omit and set the WEBAZ_API_KEY env var)" },
                 action: {
                     type: 'string',
                     enum: ['view', 'list_open', 'respond', 'add_evidence', 'arbitrate'],
@@ -666,7 +677,7 @@ Protocol auto-judges (no human): respondent silent 48h → favor initiator; arbi
                 },
                 ruling_reason: { type: 'string', description: 'Ruling reason (required for arbitrate; permanently recorded on-chain)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -693,7 +704,7 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['create', 'view', 'mine', 'submit_seller_evidence', 'available', 'vote', 'eligibility', 'verifier_status', 'apply', 'withdraw_application', 'appeal'],
@@ -716,7 +727,7 @@ Actions:
                 // appeal
                 reason: { type: 'string', description: 'Appeal reason (required for appeal, ≤500 chars)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -741,7 +752,7 @@ Actions: list (no auth) | publish (seller) | subscribe / unsubscribe (buyer) | m
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for list)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for list) (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['list', 'publish', 'subscribe', 'unsubscribe', 'my_skills', 'my_subs'],
@@ -805,7 +816,7 @@ Public-profile actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (required for view/add_role/switch_role/view_user; optional for public feed)' },
+                api_key: { type: 'string', description: 'Your api_key (required for view/add_role/switch_role/view_user; optional for public feed) (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['view', 'add_role', 'switch_role', 'view_user', 'feed'],
@@ -839,10 +850,10 @@ Use revoke when: PERMANENT decommission of agent/device, OR want access death NO
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your current api_key (the one to revoke)' },
+                api_key: { type: 'string', description: 'Your current api_key (the one to revoke) (or set the WEBAZ_API_KEY env var)' },
                 reason: { type: 'string', description: 'Optional: leaked / lost_device / rotation / unspecified' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
@@ -854,46 +865,46 @@ Safer than \`webaz_revoke_key\` — atomic swap, no access gap.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your current api_key (will be invalidated after PWA confirm)' },
+                api_key: { type: 'string', description: 'Your current api_key (will be invalidated after PWA confirm) (or set the WEBAZ_API_KEY env var)' },
                 reason: { type: 'string', description: 'Optional: rotation / leaked / scheduled' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
         name: 'webaz_referral',
         description: `View your referral status: 3-tier commission team + earnings + invite links + points-matching tier progress + L1 share permission gate + **rewards_status (RFC-002 §3.5 opt-in state + pending escrow)**.
 
-⚠️ **Opt-in required (RFC-002)**: rewards default = off. \`rewards_status\` field returns 4-state {opted_in | never_activated | auto_downgraded | deactivated} + pending_escrow tally. Opted-out users still see attribution + tree, but commission held in escrow until activation via PWA #me.
+⚠️ **Opt-in required (RFC-002)**: rewards default = off. \`rewards_status\` field returns 4-state {opted_in | never_activated | auto_downgraded | deactivated} + pending_escrow tally. Opted-out users still see attribution + tree. Commission destination differs by state: **never_activated / auto_downgraded** → held in pending_commission_escrow, recoverable by (re-)activating within the window via PWA #me; **deactivated** (active opt-out) → future L1/L2/L3 commission goes to commission_reserve / protocol reserve, NOT escrow and NOT recoverable (re-applying only affects future commission).
 
 ⚠️ **Consent required**: generating referral links / promoting on a human user's behalf needs the user's explicit authorization. Agent **MUST get explicit consent** before generating referral links / promoting. Do NOT auto-recruit.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
         name: 'webaz_share_link',
         description: `Generate product share link with your referral attached. Open in any social platform (TikTok/WeChat/Telegram). Clicker registers/buys → counts toward your 3-tier commission (if verified buyer) + points-matching.
 
-⚠️ **Opt-in required (RFC-002 §3.5)**: this is a valuation-layer action. Caller must have \`rewards_opted_in=1\` (builder-identity opt-in). Opted-out users get \`{error: 'rewards_opt_in_required', missing_requirements, next_steps}\` — direct user to PWA #me to apply.
+⚠️ **Opt-in required (RFC-002 §3.5)**: this is a valuation-layer (rewards) action, not a contribution gate. Caller must have \`rewards_opted_in=1\` (rewards / share-commission opt-in). Opted-out users get \`{error: 'rewards_opt_in_required', missing_requirements, next_steps}\` — direct user to PWA #me to apply.
 
 ⚠️ **Consent required**: this builds a referral chain on the user's behalf. Agent acting for a human user **MUST get explicit consent**. Do NOT auto-generate. See webaz_info.commission_model.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 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)',
+                    enum: ['auto'],
+                    description: 'Deprecated / no-op — placement is always automatic (system-decided). Left/right选择已下线。',
                 },
             },
-            required: ['api_key', 'product_id'],
+            required: ['product_id'],
         },
     },
     {
@@ -907,12 +918,12 @@ Actions: list | block | unblock.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 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'],
+            required: ['action'],
         },
     },
     {
@@ -921,11 +932,11 @@ Actions: list | block | unblock.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 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'],
+            required: ['action'],
         },
     },
     {
@@ -939,12 +950,12 @@ USE THIS for "what's popular near me / 我附近 / 同城" — geo-aggregated, n
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 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'],
+            required: ['action'],
         },
     },
     {
@@ -956,12 +967,12 @@ USE THIS for "what's popular near me / 我附近 / 同城" — geo-aggregated, n
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 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'],
+            required: ['action'],
         },
     },
     {
@@ -977,7 +988,7 @@ Actions: list_mine | add (external_url + product/anchor) | delete | by_product |
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 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)' },
@@ -986,7 +997,7 @@ Actions: list_mine | add (external_url + product/anchor) | delete | 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'],
+            required: ['action'],
         },
     },
     // ── P3 RFQ / bid / chat / auto_bid（MCP 通过 HTTP 调 PWA，复用所有校验+状态机）────
@@ -1015,7 +1026,7 @@ Shipping address falls back to webaz_default_address if omitted.`,
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['create', 'mine', 'browse', 'detail', 'award', 'cancel'] },
                 // create
                 title: { type: 'string' },
@@ -1034,7 +1045,7 @@ Shipping address falls back to webaz_default_address if omitted.`,
                 rfq_id: { type: 'string' },
                 bid_id: { type: 'string', description: 'Optional for award — if omitted, auto-pick current lowest bid' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1048,7 +1059,7 @@ Actions: submit (rfq_id + price + qty_offered + fulfillment_type; optional eta/n
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Seller api_key' },
+                api_key: { type: 'string', description: 'Seller api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['submit', 'patch', 'cancel', 'list_mine'] },
                 rfq_id: { type: 'string' },
                 bid_id: { type: 'string' },
@@ -1059,7 +1070,7 @@ Actions: submit (rfq_id + price + qty_offered + fulfillment_type; optional eta/n
                 note: { type: 'string' },
                 offer_id: { type: 'string', description: 'Optional; reference existing offer' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1079,7 +1090,7 @@ webaz_blocklist hides from search but does NOT auto-silence existing convs (busi
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['start', 'list', 'read', 'send', 'mark_read', 'block'] },
                 kind: { type: 'string', enum: ['order', 'rfq', 'listing_qa'] },
                 context_id: { type: 'string' },
@@ -1087,7 +1098,7 @@ webaz_blocklist hides from search but does NOT auto-silence existing convs (busi
                 conversation_id: { type: 'string' },
                 body: { type: 'string', description: 'Message body for send action (≤2000 chars)' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1127,7 +1138,7 @@ Actions (15):
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 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' },
@@ -1163,7 +1174,7 @@ Actions: create (seller, needs title/price/stock + content_hash sha256 + content
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['create', 'list', 'detail', 'patch'] },
                 product_id: { type: 'string' },
                 title: { type: 'string' }, price: { type: 'number' }, stock: { type: 'number' },
@@ -1188,11 +1199,11 @@ Actions: toggle (same endpoint; 2nd call auto-unlikes) | status (my like status
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['toggle', 'status'] },
                 shareable_id: { type: 'string' },
             },
-            required: ['api_key', 'action', 'shareable_id'],
+            required: ['action', 'shareable_id'],
         },
     },
     {
@@ -1237,7 +1248,7 @@ Actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['create', 'browse', 'mine', 'detail', 'bid', 'cancel'] },
                 title: { type: 'string' },
                 qty: { type: 'number' },
@@ -1251,7 +1262,7 @@ Actions:
                 auction_id: { type: 'string' },
                 price: { type: 'number' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1265,7 +1276,7 @@ Actions: get | set (categories[] / regions[] / max_eta_h / bid_strategy) | disab
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string' },
+                api_key: { type: 'string', description: 'Your api_key (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['get', 'set', 'disable'] },
                 categories: { type: 'array', items: { type: 'string' } },
                 regions: { type: 'array', items: { type: 'string' } },
@@ -1278,7 +1289,7 @@ Actions: get | set (categories[] / regions[] / max_eta_h / bid_strategy) | disab
                 cooldown_min: { type: 'number' },
                 enabled: { type: 'boolean' },
             },
-            required: ['api_key', 'action'],
+            required: ['action'],
         },
     },
     {
@@ -1298,7 +1309,7 @@ Actions: list (no auth, filters: kind/billing/query) | detail (public, no conten
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for list/detail)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for list/detail) (or set the WEBAZ_API_KEY env var)' },
                 action: {
                     type: 'string',
                     enum: ['list', 'detail', 'publish', 'update', 'delist', 'resubmit', 'purchase', 'read', 'my_skills', 'library'],
@@ -1335,7 +1346,7 @@ Enums: **category** phone/computer/appliance/furniture/clothing/book/toy/sports/
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for browse/detail)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for browse/detail) (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['browse', 'detail', 'publish', 'update', 'mine', 'buy'], description: 'Action to execute' },
                 item_id: { type: 'string', description: 'Item ID (required for detail/update/buy)' },
                 // publish / update
@@ -1384,7 +1395,7 @@ Seller actions:
         inputSchema: {
             type: 'object',
             properties: {
-                api_key: { type: 'string', description: 'Your api_key (omit for get_campaign)' },
+                api_key: { type: 'string', description: 'Your api_key (omit for get_campaign) (or set the WEBAZ_API_KEY env var)' },
                 action: { type: 'string', enum: ['get_campaign', 'apply', 'link_note', 'my_claims', 'create_campaign', 'cancel_campaign', 'my_campaigns', 'campaign_claims'], description: 'Action to execute' },
                 product_id: { type: 'string', description: 'Product ID (required for get_campaign/apply/create_campaign/cancel_campaign)' },
                 claim_id: { type: 'string', description: 'Claim ID (required for link_note)' },
@@ -1413,7 +1424,7 @@ Gate by type: ux_issue/bug (reporting = using) → login only, NO Passkey, anyon
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['submit', 'my', 'get'], description: 'submit (default) | my | get' },
-                api_key: { type: 'string', description: "User's api_key (real person required)" },
+                api_key: { type: 'string', description: "User's api_key (real person required; or set the WEBAZ_API_KEY env var)" },
                 type: { type: 'string', enum: ['ux_issue', 'bug', 'proposal'], description: 'submit: kind of feedback' },
                 area: { type: 'string', description: 'submit: which feature, e.g. search / order / dispute' },
                 severity: { type: 'string', enum: ['low', 'annoying', 'blocking'], description: 'submit: for ux_issue/bug' },
@@ -1421,33 +1432,49 @@ Gate by type: ux_issue/bug (reporting = using) → login only, NO Passkey, anyon
                 text: { type: 'string', description: 'submit: the feedback / idea (≥5 chars)' },
                 feedback_id: { type: 'string', description: 'get: the feedback id' },
             },
-            required: ['api_key'],
+            required: [],
         },
     },
     {
         name: 'webaz_contribute',
-        description: `Coordinate building WebAZ itself (RFC-006) — a claim board so contributors don't collide. Check BEFORE starting work on an area. Day-to-day small changes; large ones go via RFC. 协调"谁在做什么"防撞车.
+        description: `Coordinate building WebAZ itself (RFC-006 / RFC-017) — a public task board so contributors don't collide. Check BEFORE starting work on an area. 协调"谁在做什么"防撞车.
+
+Discovery + suggesting need NO api_key (anyone / any agent can browse and propose). Claiming + submitting need an api_key (a real, accountable identity).
 
 Actions:
-- list_open (default): open tasks (opt. area filter)
-- claim: take an open task; provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted. Returns a **handoff** (repo + AGENTS.md + PR flow) — point a coding agent at it to actually do the work; the human needn't know git.
-- submit: mark in_review with pr_ref
-- status: tasks you hold (claimed/in_review)
-- profile: your build dashboard — KPI/tier/restrictions+appeal, self-view (private, no public leaderboard)
+- list_open (default): open public tasks (opt. filters: area / risk_level / auto_claimable / required_capabilities / agent_capabilities / max_duration_minutes / estimated_context_size / estimated_agent_budget — estimated_agent_budget is a resource/effort estimate, NOT a payment). Each task carries its execution boundary + the trusted canonical contribution target. NO api_key needed.
+- detail: one task's full execution boundary (allowed/forbidden paths, prohibited actions, acceptance criteria, verification commands, deliverables, definition_of_done) + the canonical repo to PR to + a copy-ready agent_handoff. NO api_key needed.
+- suggest: propose a NEW task (title + summary/reason; opt. area/expected_outcome/source_ref/github_login). It enters the maintainer inbox — it is a suggestion, NOT a contribution fact / reward / participation, and never auto-becomes a task. NO api_key needed.
+- claim: take an open task (api_key); provenance=human|ai_assisted|ai_authored (self-declared, not detected); auto-expires ~7d if not submitted. Returns a handoff — point a coding agent at it; the human needn't know git but stays accountable (Passkey).
+- submit: mark in_review with pr_ref + verification_summary (api_key). The PR's base repo MUST be the canonical WebAZ repo, and a verification_summary (what you ran/verified) is REQUIRED — both server-enforced. A human maintainer reviews next; done ≠ merge.
+- status: tasks you hold (api_key).
+- profile: your build dashboard — KPI/tier/restrictions+appeal, private self-view (api_key).
 
-Coordinates + records only — NO merge/reward; acceptance (done) = human maintainer. build_reputation is a SEPARATE pool, never gates verifier/arbitrator. Login required; NETWORK only.`,
+Coordinates + records only — NO merge/reward; acceptance (done) = human maintainer. Contribution value is uncommitted (RFC-017 I-12). build_reputation is a SEPARATE pool, never gates verifier/arbitrator. NETWORK only (contribution is a real-network act; sandbox has nothing to coordinate with).`,
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['list_open', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | claim | submit | status | profile' },
-                api_key: { type: 'string', description: "User's api_key (accountable identity)" },
-                task_id: { type: 'string', description: 'claim / submit: the task id' },
-                area: { type: 'string', description: 'list_open: optional area filter (e.g. search / docs / mcp)' },
+                action: { type: 'string', enum: ['list_open', 'detail', 'suggest', 'claim', 'submit', 'status', 'profile'], description: 'list_open (default) | detail | suggest | claim | submit | status | profile' },
+                api_key: { type: 'string', description: 'claim/submit/status/profile: your api_key (accountable identity). NOT needed for list_open/detail/suggest. (or set the WEBAZ_API_KEY env var)' },
+                task_id: { type: 'string', description: 'detail / claim / submit: the task id' },
+                area: { type: 'string', description: 'list_open: area filter / suggest: suggested area (e.g. search / docs / mcp)' },
+                risk_level: { type: 'string', enum: ['low', 'medium', 'high', 'critical'], description: 'list_open: optional risk filter' },
+                auto_claimable: { type: 'boolean', description: 'list_open: optional filter — only auto-claimable (true) or manual-claim (false) tasks' },
+                required_capabilities: { type: 'string', description: 'list_open: optional filter — comma-separated; matches tasks that REQUIRE ALL of the listed capabilities (superset/AND match on the task requirement). For "tasks my agent can do", use agent_capabilities instead.' },
+                agent_capabilities: { type: 'string', description: 'list_open: optional filter — capabilities your agent HAS (comma-separated); matches tasks whose required_capabilities are a SUBSET of these, i.e. tasks your agent can actually do' },
+                max_duration_minutes: { type: 'number', description: 'list_open: optional filter — only tasks whose estimated max duration fits within this many minutes (your idle time)' },
+                estimated_context_size: { type: 'string', enum: ['small', 'medium', 'large'], description: 'list_open: optional filter — task estimated context size' },
+                estimated_agent_budget: { type: 'string', enum: ['minimal', 'small', 'moderate', 'large', 'xlarge'], description: 'list_open: optional filter — task estimated agent budget (resource/effort estimate, not a payment)' },
                 provenance: { type: 'string', enum: ['human', 'ai_assisted', 'ai_authored'], description: 'claim: self-declared authorship (default human)' },
-                pr_ref: { type: 'string', description: 'submit: your PR link or number' },
+                pr_ref: { type: 'string', description: 'submit: your PR link or number (must target the canonical repo)' },
+                verification_summary: { type: 'string', description: 'submit (REQUIRED): summarize what you ran/verified — the task verification_commands you ran and their results' },
                 note: { type: 'string', description: 'submit: optional note' },
+                title: { type: 'string', description: 'suggest: task title (≥3 chars)' },
+                summary: { type: 'string', description: 'suggest: why it is worth doing / what it solves (the reason)' },
+                expected_outcome: { type: 'string', description: 'suggest: optional — what should be true when done' },
+                source_ref: { type: 'string', description: 'suggest: optional reference link (reference only; does NOT set the target repo)' },
+                proposer_github_login: { type: 'string', description: 'suggest: optional — your GitHub login' },
             },
-            required: ['api_key'],
         },
     },
 ];
@@ -1455,7 +1482,7 @@ Coordinates + records only — NO merge/reward; acceptance (done) = human mainta
 // RFC-004: webaz_feedback — agent-native "use → build" 反馈(双模;仅 NETWORK 能送达)
 async function handleFeedback(args) {
     const action = args.action || 'submit';
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     if (toolBackend('webaz_feedback') !== 'network') {
@@ -1489,19 +1516,100 @@ async function handleFeedback(args) {
         },
     });
 }
-// RFC-006 Gap 1: webaz_contribute — 协调"谁在做什么"(双模;仅 NETWORK)
-async function handleContribute(args) {
+// RFC-006 断点1(b)交接:从【可信】canonical 目标(API 响应里,绝不硬编码/不取自 task metadata)构造"怎么真正
+// 动手"。人的编码 agent 做 git/PR;Passkey 真人担责。sandbox 运行 / 本地草稿不算正式参与。
+function buildContributeHandoff(cct, taskId) {
+    const c = (cct ?? {});
+    const repoUrl = c.canonical_github_url || 'https://github.com/seasonsagents-art/webaz';
+    const baseRepo = c.expected_pr_base_repo || c.canonical_repository_full_name || 'seasonsagents-art/webaz';
+    const baseBranch = c.base_branch || 'main';
+    return {
+        canonical_repo: baseRepo,
+        repo: repoUrl,
+        base_branch: baseBranch,
+        start_here: 'Read AGENTS.md (project map + before-you-code + PR flow), then CONTRIBUTING.md.',
+        do_the_work: 'Point a coding agent (e.g. Claude Code) at the repo on a single-topic branch. The buyer/shopping agent is not the coding agent — hand off to one.',
+        submit_pr: `Open a PR whose BASE repo is ${baseRepo} (${repoUrl}), base branch ${baseBranch}. If any target repo differs from this canonical repo, STOP and ask the human — never contribute to a non-canonical repository.`,
+        pr_flow: 'Commit with DCO sign-off (git commit -s). If AI-authored, mark the PR per the meta-rule. Humans merge — no auto-merge.',
+        then: `When the PR is open, report it back: webaz_contribute action=submit task_id=${taskId} pr_ref=#<N> verification_summary="<the verification_commands you ran + their results>". Both pr_ref and verification_summary are required.`,
+        not_participation: 'A sandbox run or a local-only draft is NOT participation and is NOT a contribution; only a merged PR (or recognized issue/task/RFC) on the canonical repo enters the contribution record.',
+        human_note: "You don't need to know git — your coding agent does it; you (the Passkey-bound human) stay accountable.",
+    };
+}
+// RFC-006/RFC-017: webaz_contribute — 协调"谁在做什么"。NETWORK only. Discovery + suggest 无需 key(打公开
+// 端口 #329/#331);claim/submit/status/profile 需 key(真实可问责身份,走受 #330 守卫的 member 端口)。
+export async function handleContribute(args) {
     const action = args.action || 'list_open';
-    const apiKey = args.api_key;
-    if (!apiKey)
-        return { error: 'api_key required' };
+    const apiKey = resolveMcpApiKey(args);
     if (toolBackend('webaz_contribute') !== 'network') {
         return {
             _mode: 'sandbox',
-            error: 'SANDBOX 模式无协调对象 —— 协调要在真实项目上才有意义。请设 WEBAZ_API_KEY 切到 NETWORK 模式。 / Coordination needs NETWORK mode; set WEBAZ_API_KEY.',
+            error: 'SANDBOX 模式无协调对象 —— 协调要在真实项目上才有意义。请设 WEBAZ_API_KEY 切到 NETWORK 模式(或不设 key 默认 network_readonly 也可浏览/建议)。 / Coordination needs the live network; sandbox has nothing to coordinate with.',
             error_code: 'CONTRIBUTE_NEEDS_NETWORK',
         };
     }
+    // ── keyless discovery + suggest (public surface; same trusted canonical target as the PWA) ──
+    if (action === 'list_open') {
+        // public endpoint already restricts to audience=public + status=open; only pass the optional filters.
+        const qs = new URLSearchParams();
+        if (args.area)
+            qs.set('area', String(args.area));
+        if (args.risk_level)
+            qs.set('risk_level', String(args.risk_level));
+        if (args.auto_claimable !== undefined)
+            qs.set('auto_claimable', String(Boolean(args.auto_claimable)));
+        if (args.required_capabilities)
+            qs.set('required_capabilities', String(args.required_capabilities));
+        if (args.agent_capabilities !== undefined)
+            qs.set('agent_capabilities', String(args.agent_capabilities)); // forward even '' so the route fail-closes (typed 400), never silently returns the full list
+        if (args.max_duration_minutes !== undefined)
+            qs.set('max_duration_minutes', String(args.max_duration_minutes));
+        if (args.estimated_context_size)
+            qs.set('estimated_context_size', String(args.estimated_context_size));
+        if (args.estimated_agent_budget)
+            qs.set('estimated_agent_budget', String(args.estimated_agent_budget));
+        const q = qs.toString();
+        const r = await apiCall('/api/public/build-tasks' + (q ? '?' + q : ''));
+        if (!r.error)
+            r._next = 'Pick a task, then: webaz_contribute action=detail task_id=<id> for its full execution boundary + the canonical repo to PR to; then action=claim task_id=<id> api_key=<key> to take it (claiming needs an account).';
+        return r;
+    }
+    if (action === 'detail') {
+        const tid = args.task_id;
+        if (!tid)
+            return { error: 'task_id required for action=detail' };
+        const r = await apiCall('/api/public/build-tasks/' + encodeURIComponent(tid));
+        if (!r.error && r.task)
+            r.agent_handoff = buildContributeHandoff(r.canonical_contribution_target, tid);
+        return r;
+    }
+    if (action === 'suggest') {
+        const title = (args.title ?? '').trim();
+        const summary = (args.summary ?? args.note ?? '').trim();
+        if (title.length < 3)
+            return { error: 'title required (≥3 chars) for action=suggest' };
+        if (summary.length < 1)
+            return { error: 'summary (the reason) required for action=suggest' };
+        const r = await apiCall('/api/public/task-proposals', {
+            method: 'POST',
+            body: {
+                title, summary,
+                suggested_area: args.area ?? args.suggested_area,
+                expected_outcome: args.expected_outcome,
+                source_ref: args.source_ref,
+                proposer_github_login: args.proposer_github_login,
+            },
+        });
+        // typed errors (RATE_LIMITED / DUPLICATE_PROPOSAL / validation) are already mapped by apiCall; the
+        // success response already carries the route-level `proposal_notice` (suggestion ≠ contribution/reward).
+        return r;
+    }
+    // ── participation: a real, accountable identity is required ──
+    if (!apiKey)
+        return {
+            error: `api_key required for action=${action} — set WEBAZ_API_KEY (request an invite at ${WEBAZ_API_URL}/#welcome). Discovery (list_open / detail) and suggest work WITHOUT a key.`,
+            error_code: 'API_KEY_REQUIRED',
+        };
     if (action === 'status')
         return apiCall('/api/build-tasks?mine=1', { apiKey });
     if (action === 'profile')
@@ -1513,31 +1621,25 @@ async function handleContribute(args) {
         const r = await apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/claim', {
             method: 'POST', apiKey, body: { provenance: args.provenance },
         });
-        // RFC-006 断点1(b)交接:认领成功后直接下发"怎么真正动手",让贡献者的【编码 agent】接手 git/PR。
-        //   关键:人不必会 git——人的编码 agent(如 Claude Code)做;人(Passkey 真人)担责。
-        if (!r.error) {
-            r.handoff = {
-                repo: 'https://github.com/seasonsagents-art/webaz',
-                start_here: 'Read AGENTS.md (project map + before-you-code + PR flow), then CONTRIBUTING.md.',
-                do_the_work: 'Point a coding agent (e.g. Claude Code) at the repo; work on a single-topic branch. The buyer/shopping agent is not the coding agent — hand off to one.',
-                pr_flow: 'Commit with DCO sign-off (git commit -s). If AI-authored, add 🤖🤖🤖 to the PR title + a meta-rule trace. Humans merge — no auto-merge.',
-                then: `When the PR is open, report it back: webaz_contribute action=submit task_id=${tid} pr_ref=#<N>.`,
-                human_note: "You don't need to know git — your coding agent does it; you (the Passkey-bound human) stay accountable.",
-            };
-        }
+        if (!r.error)
+            r.handoff = buildContributeHandoff(r.canonical_contribution_target, tid);
         return r;
     }
     if (action === 'submit') {
         const tid = args.task_id;
         if (!tid)
             return { error: 'task_id required for action=submit' };
-        return apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/submit', {
-            method: 'POST', apiKey, body: { pr_ref: args.pr_ref, note: args.note },
+        const vs = (args.verification_summary ?? '').trim();
+        if (vs.length < 1)
+            return { error: 'verification_summary required for action=submit — summarize what you ran/verified (the task verification_commands and their results)', error_code: 'VERIFICATION_SUMMARY_REQUIRED' };
+        const r = await apiCall('/api/build-tasks/' + encodeURIComponent(tid) + '/submit', {
+            method: 'POST', apiKey, body: { pr_ref: args.pr_ref, note: args.note, verification_summary: vs },
         });
+        if (!r.error)
+            r._next = 'A human maintainer reviews next — acceptance (done) is manual and done ≠ merge. Track it with webaz_contribute action=status.';
+        return r;
     }
-    // list_open(默认)
-    const q = args.area ? '?status=open&area=' + encodeURIComponent(String(args.area)) : '?status=open';
-    return apiCall('/api/build-tasks' + q, { apiKey });
+    return { error: 'unknown action: ' + action };
 }
 async function handleInfo() {
     const summary = getManifestSummary();
@@ -1641,10 +1743,10 @@ async function handleInfo() {
             split: '7:2:1 — L1 70% / L2 20% / L3 10% of an order\'s commission_pool',
             jurisdiction_tiers: 'Tiers are graded by the order region\'s max_levels — NOT a uniform 3 tiers everywhere. e.g. global region max_levels=1 → L1 only; singapore (etc.) max_levels=3 → up to L3. A region may also be 0 (no commission tiers; pool → community fund).',
             attribution: 'EXPLICIT per-order — commission goes to the promoter attributed at purchase time, not derived from the buyer\'s sponsor chain.',
-            how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records the direct promoter. Full L2/L3 chain requires the buyer to arrive via a webaz_share_link ?ref= URL clicked in a browser (builds product_share_attribution).',
+            how_to_attribute: 'L1: webaz_place_order(promoter_api_key) records the direct promoter. Full L2/L3 chain requires the buyer to arrive via a webaz_share_link /i/<permanent_code> (?ref=<permanent_code>) URL clicked in a browser (builds product_share_attribution).',
             redirect_rules: 'chain_gap (no L / invalid sponsor) → charity_fund; level beyond the region cap → global_fund.',
             l1_gate: 'the promoter must be a verified buyer (≥1 completed order) to receive commission, otherwise that share redirects.',
-            opt_in: 'Participation is opt-in (RFC-002): default = off. A user applies (Passkey + ≥1 completed order); attribution is always recorded, but commission settlement is gated until opt-in (pending held in pending_commission_escrow, 30d grace). See docs/rfcs/RFC-002-rewards-opt-in.md.',
+            opt_in: 'Participation is opt-in (RFC-002): default = off. A user applies (Passkey + ≥1 completed order); attribution is always recorded. Commission destination is state-dependent: never_activated / auto_downgraded → held in pending_commission_escrow (30d grace), recoverable by (re-)activating within the window, else swept to commission_reserve; deactivated (active opt-out) → future commission goes directly to commission_reserve, NOT escrow and NOT recoverable. Never to charity_fund. See docs/rfcs/RFC-002-rewards-opt-in.md.',
         },
         // QA 轮 3 FAIL：roles 漏 reviewer。register 工具支持 5 个角色，info 必须列全。
         roles: {
@@ -1957,8 +2059,8 @@ async function handleSearch(args) {
             : '没有找到匹配的商品';
         return { found: 0, message: hint, products: [], matched_by: 'strict_no_match' };
     }
-    const enriched = products.map((p) => {
-        const boost = getSearchBoost(db, p.seller_id);
+    const enriched = await Promise.all(products.map(async (p) => {
+        const boost = await 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;
@@ -1983,7 +2085,7 @@ async function handleSearch(args) {
         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);
@@ -2045,11 +2147,11 @@ async function handleVerifyPrice(args) {
     if (toolBackend('webaz_verify_price') === 'network') {
         return apiCall('/api/verify-price', {
             method: 'POST',
-            apiKey: args.api_key,
+            apiKey: resolveMcpApiKey(args),
             body: { product_id: args.product_id, quantity: Number(args.quantity ?? 1) },
         });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -2095,7 +2197,7 @@ async function handleVerifyPrice(args) {
 async function handleListProduct(args) {
     // Wave 3 audit P0: 加 action 分发 — agent 卖家能完整管理目录（不止 create）
     const action = args.action || 'create';
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     // RFC-003 P2b: NETWORK 模式 — 卖家目录管理全部转发生产端点（单一真相源）
@@ -2212,7 +2314,7 @@ async function handleListProduct(args) {
     // stake 在 place_order 那一刻按"该订单总额 × stake_rate"现锁，订单结算时退该笔，违约时扣该笔。
     // 这样每个 active 订单都有独立 stake 担保，多 stock 商品也不会被空头薅。
     // product.stake_amount 字段保留为"indicative rate × price"（前端展示用），不强制 lock。
-    const stakeDiscount = getStakeDiscount(db, user.id);
+    const stakeDiscount = await 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');
@@ -2273,9 +2375,9 @@ async function handlePlaceOrder(args) {
             body.shipping_address = args.shipping_address;
         if (args.donation_pct != null)
             body.donation_pct = args.donation_pct;
-        return apiCall('/api/orders', { method: 'POST', apiKey: args.api_key, body });
+        return apiCall('/api/orders', { method: 'POST', apiKey: resolveMcpApiKey(args), body });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -2442,7 +2544,7 @@ async function handleUpdateOrder(args) {
             return { error: 'order_id and action required' };
         return apiCall(`/api/orders/${encodeURIComponent(orderId)}/action`, {
             method: 'POST',
-            apiKey: args.api_key,
+            apiKey: resolveMcpApiKey(args),
             body: {
                 action,
                 notes: args.notes ?? '',
@@ -2452,7 +2554,7 @@ async function handleUpdateOrder(args) {
             },
         });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -2466,7 +2568,7 @@ async function handleUpdateOrder(args) {
     // agent-native 协议要求"哪个接口进结果一致"。MCP confirm 不再自己结算，
     // 走 PWA /api/orders/:id/action 的 settleOrder + settleCommission（authoritative）。
     if (action === 'confirm') {
-        const apiKey = args.api_key;
+        const apiKey = resolveMcpApiKey(args);
         const result = await pwaApi('POST', `/orders/${encodeURIComponent(orderId)}/action`, apiKey, {
             action: 'confirm',
             notes,
@@ -2575,9 +2677,9 @@ async function handleGetStatus(args) {
         const orderId = args.order_id;
         if (!orderId)
             return { error: 'order_id required' };
-        return apiCall(`/api/orders/${encodeURIComponent(orderId)}`, { apiKey: args.api_key });
+        return apiCall(`/api/orders/${encodeURIComponent(orderId)}`, { apiKey: resolveMcpApiKey(args) });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const statusInfo = getOrderStatus(db, args.order_id);
@@ -2614,7 +2716,7 @@ async function handleGetStatus(args) {
 async function handleWallet(args) {
     // Wave 3 audit P0: 加 action 分发 — agent 能查充值/提现/收入历史（写操作仍 UI-only 走 2FA）
     const action = args.action || 'view';
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     // RFC-003 Batch 4:NETWORK 模式 → webaz.xyz 真网络【只读】(Bearer api_key)。
@@ -2682,20 +2784,20 @@ async function handleWallet(args) {
 async function handleNotifications(args) {
     // RFC-003 Batch 1:NETWORK 模式 → 调 webaz.xyz 真网络通知端点(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_notifications') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (args.mark_read)
             await apiCall('/api/notifications/read', { method: 'POST', apiKey });
         return await apiCall('/api/notifications' + (args.unread === true ? '?unread=1' : ''), { apiKey });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     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);
+    const notifs = await getNotifications(db, user.id, onlyUnread, 30);
+    const unread = await getUnreadCount(db, user.id);
     if (args.mark_read) {
         markRead(db, user.id);
     }
@@ -2713,7 +2815,7 @@ async function handleNotifications(args) {
 }
 // ─── 争议处理 ─────────────────────────────────────────────────
 async function handleDispute(args) {
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     const action = args.action;
@@ -2782,9 +2884,9 @@ async function handleDispute(args) {
     // ── 查看争议详情 ────────────────────────────────────────────
     if (action === 'view') {
         let dispute = args.dispute_id
-            ? getDisputeDetails(db, args.dispute_id)
+            ? await getDisputeDetails(db, args.dispute_id)
             : args.order_id
-                ? getOrderDispute(db, args.order_id)
+                ? await getOrderDispute(db, args.order_id)
                 : null;
         if (!dispute)
             return { error: '找不到争议记录，请提供 dispute_id 或 order_id' };
@@ -2824,7 +2926,7 @@ async function handleDispute(args) {
         if (user.role !== 'arbitrator') {
             return { error: '只有仲裁员可以查看所有待处理争议' };
         }
-        const disputes = getOpenDisputes(db);
+        const disputes = await getOpenDisputes(db);
         return {
             open_count: disputes.length,
             disputes: disputes.map(d => ({
@@ -2848,7 +2950,7 @@ async function handleDispute(args) {
         // 如有证据描述，先创建证据记录
         const evidenceIds = [];
         if (args.evidence_description) {
-            const dispute = getDisputeDetails(db, args.dispute_id);
+            const dispute = await getDisputeDetails(db, args.dispute_id);
             if (dispute) {
                 const eid = generateId('evt');
                 db.prepare(`
@@ -2876,7 +2978,7 @@ async function handleDispute(args) {
 }
 // ─── 索赔验证（claim-verification）处理 — Wave 6 新增 ────────────
 async function handleClaimVerify(args) {
-    const apiKey = args.api_key;
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required' };
     const action = String(args.action || '');
@@ -2964,7 +3066,7 @@ async function handleSkill(args) {
     const action = args.action;
     // RFC-003 Batch 3:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地引擎。
     if (toolBackend('webaz_skill') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (action === 'list') {
             const qs = new URLSearchParams();
             if (args.skill_type)
@@ -3001,12 +3103,12 @@ async function handleSkill(args) {
     // ── 浏览 Skill 市场 ────────────────────────────────────────
     if (action === 'list') {
         let userId;
-        if (args.api_key) {
-            const a = requireAuth(db, args.api_key);
+        if (resolveMcpApiKey(args)) {
+            const a = requireAuth(db, resolveMcpApiKey(args));
             if (!('error' in a))
                 userId = a.user.id;
         }
-        const skills = listSkills(db, {
+        const skills = await listSkills(db, {
             skillType: args.skill_type,
             query: args.query,
             subscriberId: userId,
@@ -3019,7 +3121,7 @@ async function handleSkill(args) {
         };
     }
     // 以下操作需要身份验证
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3064,7 +3166,7 @@ async function handleSkill(args) {
     }
     // ── 我发布的 Skill ────────────────────────────────────────
     if (action === 'my_skills') {
-        const skills = getMySkills(db, user.id);
+        const skills = await getMySkills(db, user.id);
         return {
             total: skills.length,
             skills: skills.map(formatSkillForAgent),
@@ -3073,7 +3175,7 @@ async function handleSkill(args) {
     }
     // ── 我订阅的 Skill ────────────────────────────────────────
     if (action === 'my_subs') {
-        const skills = getMySubscriptions(db, user.id);
+        const skills = await getMySubscriptions(db, user.id);
         return {
             total: skills.length,
             subscriptions: skills.map(formatSkillForAgent),
@@ -3160,7 +3262,7 @@ function handleMyKey(args) {
 }
 async function handleProfile(args) {
     const action = args.action;
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     // RFC-003 Batch 1:NETWORK 模式 → 全部 action 调 webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_profile') === 'network') {
         if (action === 'view_user') {
@@ -3257,7 +3359,7 @@ async function handleProfile(args) {
 function handleRevokeKey(args) {
     // RFC-003 Batch 5:NETWORK 模式 → 不本地校验 key(PWA 会鉴权),直接返回 Passkey 撤销指引。
     if (toolBackend('webaz_revoke_key') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         const reason = (args.reason || 'unspecified').trim().slice(0, 100);
         return {
             _mode: 'network',
@@ -3275,7 +3377,7 @@ function handleRevokeKey(args) {
             },
         };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3299,7 +3401,7 @@ function handleRevokeKey(args) {
 function handleRotateKey(args) {
     // RFC-003 Batch 5:NETWORK 模式 → 不本地校验 key(PWA 会鉴权),直接返回 Passkey 轮换指引。
     if (toolBackend('webaz_rotate_key') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         const reason = (args.reason || 'rotation').trim().slice(0, 100);
         return {
             _mode: 'network',
@@ -3316,7 +3418,7 @@ function handleRotateKey(args) {
             },
         };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3340,12 +3442,12 @@ function handleRotateKey(args) {
 async function handleReferral(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络聚合(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_referral') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         return await apiCall('/api/referral/me', { apiKey });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3373,10 +3475,14 @@ async function handleReferral(args) {
     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);
+    // invite / share links use permanent_code ONLY — never usr_xxx. (sandbox users have one from register.)
+    const permaCode = db.prepare("SELECT permanent_code FROM users WHERE id = ?").get(userId)?.permanent_code || null;
     return {
         user_id: userId,
         name: user.name,
-        base_referral_link: `/?ref=${userId}`, // 仅推土机
+        invite_code: permaCode,
+        invite_unavailable_reason: permaCode ? null : 'permanent_code_missing — re-register or contact support',
+        base_referral_link: permaCode ? `/i/${permaCode}` : null, // 仅推土机
         region: user.region ?? 'global',
         permissions: {
             can_earn_l1_commission: canL1,
@@ -3391,10 +3497,8 @@ async function handleReferral(args) {
             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`,
+            // pre-public 去左右码:只暴露唯一的推荐码;放置侧别由系统自动决定(无 left/right 选择)
+            referral_link: permaCode ? `/i/${permaCode}` : null,
             total_left_pv: Number(me?.total_left_pv ?? 0),
             total_right_pv: Number(me?.total_right_pv ?? 0),
             pair_volume: pair,
@@ -3414,7 +3518,7 @@ async function handleReferral(args) {
             }
             else if (lastAction === 'deactivate') {
                 state = 'deactivated';
-                note = 'You actively deactivated rewards. Future commissions redirect directly to charity_fund (no escrow). You can re-apply via PWA #me.';
+                note = 'You actively deactivated rewards. Future L1/L2/L3 commissions go to commission_reserve / protocol reserve, not charity_fund and not pending escrow. Re-applying only affects future commissions.';
             }
             else if (lastAction === 'auto_downgrade') {
                 state = 'auto_downgraded';
@@ -3432,7 +3536,7 @@ async function handleReferral(args) {
                 note,
                 pending_escrow: { count: pending.n, total_amount: pending.total },
                 expired_to_charity: { count: expired.n, total_amount: expired.total },
-                spec: 'RFC-002 §3.5 — rewards opt-in / 共建身份申请制',
+                spec: 'RFC-002 §3.5 — rewards / share-commission opt-in (RFC-002)',
             };
         })(),
         tip: canL1
@@ -3443,23 +3547,21 @@ async function handleReferral(args) {
 async function handleShareLink(args) {
     // RFC-003 #1122:NETWORK 模式 → 调 webaz.xyz 的 /api/share-link(服务端同款计算);SANDBOX 走本地。
     if (toolBackend('webaz_share_link') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (!args.product_id)
             return { error: 'product_id required' };
+        // pre-public 去左右码:不再向 /api/share-link 转发 side(放置永远自动)
         const qs = new URLSearchParams({ product_id: String(args.product_id) });
-        if (args.side)
-            qs.set('side', String(args.side));
         return await apiCall('/api/share-link?' + qs.toString(), { apiKey });
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
     const userId = user.id;
     const productId = args.product_id;
-    const sideArg = args.side || 'auto';
     // RFC-002 §3.5 valuation-layer gate — share_link generation requires opt-in
     const optIn = db.prepare("SELECT rewards_opted_in FROM users WHERE id = ?").get(userId)?.rewards_opted_in ?? 0;
     if (optIn !== 1) {
@@ -3480,10 +3582,10 @@ async function handleShareLink(args) {
             missing.push('application_not_submitted');
         return {
             error: 'rewards_opt_in_required',
-            message: 'Share-link generation is a valuation-layer action — requires builder-identity opt-in (RFC-002 §3.5)',
+            message: 'Share-link generation is a valuation-layer (rewards / share-link) action, NOT a contribution gate — requires rewards / share-commission opt-in (RFC-002 §3.5)',
             missing_requirements: missing,
             next_steps: [
-                'Open PWA #me → tap "申请共建身份 / Apply for builder identity"',
+                'Open PWA #me → tap "申请分享分润 / Enable share-commission opt-in"',
                 'Read the 8-second disclosure (cannot skip)',
                 'Submit application — pre-checks run server-side',
             ],
@@ -3492,43 +3594,21 @@ async function handleShareLink(args) {
     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_count, right_count 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: 整棵子树人数（增量维护的 left_count/right_count，与 PWA pickPreferredSide 对齐）。
-            // 2026-06-04 修：旧版沿单条脊链数(countLeg)名实不符 → 选边失真。分享链接的 side 会被注册时
-            // 当 placement_side 显式采用，必须与 PWA joinPowerLeg 用同一指标，否则两路径不一致。
-            side = (Number(u?.left_count ?? 0) <= Number(u?.right_count ?? 0)) ? 'left' : 'right';
-        }
-    }
+    // pre-public 去左右码:分享链接不再携带 side(放置侧别由注册时系统自动决定)
     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}`;
+    // share ref uses permanent_code ONLY — never usr_xxx
+    const permaCode = db.prepare("SELECT permanent_code FROM users WHERE id = ?").get(userId)?.permanent_code || null;
+    if (!permaCode)
+        return { error: 'permanent_code_missing — cannot build a share link; re-register or contact support', error_code: 'PERMANENT_CODE_MISSING' };
+    const link = `/?ref=${permaCode}#order-product/${productId}`;
     return {
         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)`,
+        placement_note: 'New user via this link → placement is recorded automatically by the system (no left/right choice).',
         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 points-matching still builds.',
@@ -3539,7 +3619,7 @@ async function handleShareLink(args) {
 async function handleBlocklist(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_blocklist') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         const act = String(args.action || '');
@@ -3554,7 +3634,7 @@ async function handleBlocklist(args) {
             return await apiCall('/api/blocklist/' + uid, { method: 'DELETE', apiKey });
         return { error: `unknown action: ${act}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3593,7 +3673,7 @@ async function handleBlocklist(args) {
 async function handleFollows(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_follows') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         const act = String(args.action || '');
@@ -3610,7 +3690,7 @@ async function handleFollows(args) {
             return await apiCall('/api/follows/' + uid + '/status', { apiKey });
         return { error: `unknown action: ${act}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3659,7 +3739,7 @@ async function handleNearby(args) {
     const action = String(args.action || '');
     // RFC-003 Batch 1:NETWORK 模式 → 调 webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_nearby') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (action === 'set_location')
@@ -3677,7 +3757,7 @@ async function handleNearby(args) {
         }
         return { error: `unknown action: ${action}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3728,7 +3808,7 @@ async function handleNearby(args) {
 async function handleDefaultAddress(args) {
     // RFC-003 Batch 2:NETWORK 模式 → webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_default_address') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         const act = String(args.action || '');
@@ -3747,7 +3827,7 @@ async function handleDefaultAddress(args) {
         }
         return { error: `unknown action: ${act}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3788,7 +3868,7 @@ async function handleShareables(args) {
     const action = String(args.action || '');
     // RFC-003 Batch 1:NETWORK 模式 → 调 webaz.xyz 真网络(Bearer api_key);SANDBOX 走本地。
     if (toolBackend('webaz_shareables') === 'network') {
-        const apiKey = String(args.api_key || '');
+        const apiKey = resolveMcpApiKey(args);
         if (!apiKey)
             return { error: 'api_key required' };
         if (action === 'list_mine')
@@ -3816,7 +3896,7 @@ async function handleShareables(args) {
         }
         return { error: `unknown action: ${action}` };
     }
-    const auth = requireAuth(db, args.api_key);
+    const auth = requireAuth(db, resolveMcpApiKey(args));
     if ('error' in auth)
         return auth;
     const { user } = auth;
@@ -3972,7 +4052,7 @@ async function pwaApi(method, path, apiKey, body) {
     }
 }
 async function handleSecondhand(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const isPublic = action === 'browse' || action === 'detail';
     if (!isPublic) {
@@ -4043,7 +4123,7 @@ async function handleSecondhand(args) {
     }
 }
 async function handleTrial(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const isPublic = action === 'get_campaign';
     if (!isPublic) {
@@ -4096,7 +4176,7 @@ async function handleTrial(args) {
     }
 }
 async function handleSkillMarket(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const isPublic = action === 'list' || action === 'detail';
     if (!isPublic) {
@@ -4169,7 +4249,7 @@ async function handleSkillMarket(args) {
     }
 }
 async function handleRfq(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4218,7 +4298,7 @@ async function handleRfq(args) {
     }
 }
 async function handleBid(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4292,7 +4372,7 @@ async function handleBid(args) {
     }
 }
 async function handleChat(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4334,7 +4414,7 @@ async function handleChat(args) {
     }
 }
 async function handleAutoBidSkill(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4457,7 +4537,7 @@ async function handleCharity(args) {
         return readEndpoint('webaz_charity', '/charity/leaderboard');
     if (action === 'fund')
         return readEndpoint('webaz_charity', '/charity/fund');
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required for this action' };
     if (toolBackend('webaz_charity') !== 'network') {
@@ -4520,7 +4600,7 @@ async function handleP2pProduct(args) {
             return { error: String(e.message) };
         }
     }
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     if (!apiKey)
         return { error: 'api_key required for create/patch' };
     const auth = requireAuth(db, apiKey);
@@ -4547,7 +4627,7 @@ async function handleP2pProduct(args) {
     return { error: `unknown action: ${action}` };
 }
 async function handleLike(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     const sid = String(args.shareable_id || '');
     if (!apiKey || !sid)
@@ -4573,7 +4653,7 @@ async function handleLeaderboard(args) {
     return readEndpoint('webaz_leaderboard', '/leaderboard?kind=' + kind + '&limit=' + limit);
 }
 async function handleAuction(args) {
-    const apiKey = String(args.api_key || '');
+    const apiKey = resolveMcpApiKey(args);
     const action = String(args.action || '');
     if (!apiKey)
         return { error: 'api_key required' };
@@ -4706,7 +4786,7 @@ export async function startMCPServer() {
         if (request.params.uri !== MANIFEST_URI) {
             throw new Error(`未知资源：${request.params.uri}`);
         }
-        const manifest = generateManifest(db);
+        const manifest = await generateManifest(db);
         return {
             contents: [
                 {
@@ -5031,7 +5111,7 @@ function addHours(date, hours) {
 function recordToolCall(tool, args, result, latencyMs) {
     let userId = null;
     try {
-        const apiKey = args.api_key;
+        const apiKey = resolveMcpApiKey(args);
         if (apiKey) {
             const row = db.prepare('SELECT id FROM users WHERE api_key = ?').get(apiKey);
             if (row)