@voko/lite 0.3.1

package/src/core/offline-sync.js

@@ -0,0 +1,150 @@
+/**
+ * offline-sync.js — 离线消息同步
+ *
+ * 从 WuKongIM 服务端拉取遗漏的离线消息，逐条入库后按组分批转发给 agent。
+ * 纯 Node.js，无 Electron 依赖。
+ *
+ * @module
+ */
+
+const { enqueueDbWrite, waitForDbQueue } = require('./database');
+
+/**
+ * 拉取离线消息并转发
+ *
+ * @param {object} db - better-sqlite3 实例
+ * @param {object} messageHandler - MessageHandler 实例（需有 handleAgentMessage / forwardToAgent）
+ * @param {string} [agentIdFilter] - 可选，仅同步指定 agent
+ * @returns {Promise<number>} 同步的消息总数
+ */
+async function syncOfflineMessages(db, messageHandler, agentIdFilter) {
+  console.log(`[离线同步] 开始拉取离线消息...` + (agentIdFilter ? ` (仅 agent=${agentIdFilter})` : ''));
+  try {
+    const agents = db.prepare(`SELECT agent_id, imUid, imToken, im_server_url FROM agents WHERE publish_status = 'published'`).all();
+    const pendingMessages = [];
+
+    for (const agent of agents) {
+      if (agentIdFilter && agent.agent_id !== agentIdFilter) {
+        console.log(`[离线同步] 跳过 agent=${agent.agent_id}`);
+        continue;
+      }
+      // WukongIM WS → HTTP API 端口映射（默认 WS:5200 → API:5001）
+      const httpBase = agent.im_server_url
+        .replace(/^ws:/, 'http:').replace(/^wss:/, 'https:')
+        .replace(/:5200(?=\/|$)/, ':5001');
+      const convs = db.prepare(`SELECT DISTINCT channel_id FROM conversations WHERE agent_id = ?`).all(agent.agent_id);
+
+      for (const conv of convs) {
+        const maxRow = db.prepare(`SELECT MAX(message_seq) as m FROM messages WHERE channel_id = ? AND agent_id = ?`).get(conv.channel_id, agent.agent_id);
+        const startSeq = (maxRow?.m || 0) + 1;
+        if (startSeq <= 1) continue;
+
+        try {
+          const resp = await fetch(`${httpBase}/channel/messagesync`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              login_uid: agent.imUid,
+              channel_id: conv.channel_id,
+              channel_type: 1,
+              start_message_seq: startSeq,
+              end_message_seq: 0,
+              limit: 100,
+              pull_mode: 1
+            })
+          });
+          if (!resp.ok) {
+            console.warn(`[离线同步] agent=${agent.agent_id} channel=${conv.channel_id} HTTP ${resp.status}`);
+            continue;
+          }
+          const data = await resp.json();
+          const msgs = data.messages || [];
+          console.log(`[离线同步] agent=${agent.agent_id} channel=${conv.channel_id} 拉取到 ${msgs.length} 条`);
+
+          for (const msg of msgs) {
+            const msgId = msg.message_id || msg.messageID;
+            if (!msgId) continue;
+            let content = msg.content || '';
+            let contentType = msg.content_type || 1;
+            if (msg.payload && !content) {
+              try {
+                const decoded = JSON.parse(Buffer.from(msg.payload, 'base64').toString());
+                content = decoded.content || '';
+                contentType = decoded.type || 1;
+              } catch (_) {}
+            }
+            const toUid = msg.from_uid === agent.imUid ? conv.channel_id : agent.imUid;
+            pendingMessages.push({
+              agentId: agent.agent_id,
+              data: {
+                fromUid: msg.from_uid || '',
+                toUid,
+                channelId: conv.channel_id,
+                channelType: 1,
+                content,
+                contentType,
+                messageId: msgId,
+                timestamp: msg.timestamp || 0,
+                messageSeq: msg.message_seq,
+                clientMsgNo: msg.client_msg_no,
+                noPersist: msg.header?.no_persist ? 1 : 0,
+                redDot: msg.header?.red_dot ? 1 : 0,
+                syncOnce: msg.header?.sync_once ? 1 : 0
+              }
+            });
+          }
+        } catch (e) {
+          console.error(`[离线同步] agent=${agent.agent_id} channel=${conv.channel_id} 请求失败:`, e.message);
+        }
+      }
+    }
+
+    console.log(`[离线同步] 共收集 ${pendingMessages.length} 条离线消息，开始分组转发...`);
+
+    // 第一步：逐条入库（skipForward=true，不转发到 agent 后端）
+    await new Promise(resolve => {
+      enqueueDbWrite(() => {
+        for (const p of pendingMessages) {
+          messageHandler.handleAgentMessage(p.agentId, p.data, true);
+        }
+      });
+      waitForDbQueue().then(() => setImmediate(resolve));
+    });
+
+    // 第二步：按 agent + 会话分组，合并转发
+    const sessions = new Map();
+    for (const p of pendingMessages) {
+      const key = `${p.agentId}:${p.data.fromUid}`;
+      if (!sessions.has(key)) {
+        sessions.set(key, {
+          agentId: p.agentId, fromUid: p.data.fromUid, toUid: p.data.toUid,
+          channelId: p.data.channelId, list: []
+        });
+      }
+      sessions.get(key).list.push(p.data);
+    }
+    console.log(`[离线同步] 分组 ${sessions.size} 组，合并转发`);
+    for (const [key, session] of sessions) {
+      if (session.list.length === 1) {
+        enqueueDbWrite(() => messageHandler.handleAgentMessage(session.agentId, session.list[0]));
+      } else {
+        const lines = [`访客共发送了 ${session.list.length} 条离线消息，请合并回复：\n`];
+        for (let i = 0; i < session.list.length; i++) {
+          const msg = session.list[i];
+          const time = msg.timestamp ? new Date(msg.timestamp * 1000).toLocaleString('zh-CN') : '';
+          lines.push(`--- 消息 ${i + 1} (${time}) ---`);
+          lines.push(msg.content);
+          lines.push('');
+        }
+        messageHandler.forwardToAgent(session.agentId, session.fromUid, lines.join('\n'), session.channelId, null, null, null, null);
+      }
+    }
+    console.log(`[离线同步] 完成`);
+    return pendingMessages.length;
+  } catch (e) {
+    console.error('[离线同步] 失败:', e.message);
+    return 0;
+  }
+}
+
+module.exports = { syncOfflineMessages };

package/src/core/payment.js

@@ -0,0 +1,285 @@
+/**
+ * payment.js — 支付处理逻辑
+ *
+ * 包括支付订单处理、二维码生成、消息发送等核心逻辑。
+ * 纯 Node.js，无 Electron 依赖。UI 通知通过 callback 注入。
+ *
+ * @module
+ */
+
+const QRCode = require('qrcode');
+const { uploadBase64ToOSS } = require('../server/oss');
+const { signDidRequest } = require('./did-auth');
+
+/**
+ * 处理支付订单
+ *
+ * @param {object} order - 订单对象 { id, agent_id, visitor_id, from_uid, amount, description }
+ * @param {object} deps
+ * @param {object} deps.db - better-sqlite3 实例
+ * @param {object} deps.databaseAPI - 数据库 API
+ * @param {object} deps.agentWorkers - Map<agentId, {worker}> IM worker 进程映射
+ * @param {object} deps.endpoints - { payment: { baseUrl } }
+ * @param {Function} deps.notifyUI - (type, data) => {} 可选 UI 通知回调
+ * @param {Function} deps.payLog - (data) => {} 可选支付日志回调
+ */
+async function processPendingPaymentOrder(order, deps) {
+  const { db, databaseAPI, agentWorkers, endpoints, notifyUI, payLog } = deps;
+  const _log = payLog || (() => {});
+  const _notify = notifyUI || (() => {});
+
+  try {
+    // 原子领取：只有当前仍是 pending 才能成功
+    const claimed = db.prepare(`UPDATE payment_orders SET status = 'processing' WHERE id = ? AND status = 'pending'`).run(order.id);
+    if (claimed.changes === 0) {
+      console.log('[Payment] 跳过，订单已被处理, id:', order.id);
+      return;
+    }
+
+    // 获取 Agent DID 和私钥
+    const agentDid = databaseAPI.getAgentDid(order.agent_id);
+    const agentKeyRow = db.prepare(`SELECT private_key FROM agents WHERE agent_id = ? AND private_key IS NOT NULL`).get(order.agent_id);
+    if (!agentDid || !agentKeyRow) {
+      databaseAPI.updatePaymentOrder(order.id, { status: 'failed', result: 'Agent 未注册 DID 或未配置私钥' });
+      console.error('[Payment] Agent ' + order.agent_id + ' 未注册 DID 或未配置私钥');
+      return;
+    }
+
+    const bizFields = {
+      agentDid,
+      amount: order.amount,
+      description: order.description || '支付收款',
+      imUid: order.visitor_id || undefined
+    };
+    const authFields = await signDidRequest(agentDid, agentKeyRow.private_key, bizFields);
+    const body = { ...authFields, ...bizFields };
+
+    const initResp = await fetch(endpoints.payment.baseUrl + '/payment/create-order', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body)
+    });
+    const initResult = await initResp.json();
+
+    if (!initResult.success) {
+      databaseAPI.updatePaymentOrder(order.id, { status: 'failed', result: initResult.message || '创建支付失败' });
+      return;
+    }
+
+    const payUrl = initResult.data?.payUrl;
+    const orderNo = initResult.data?.orderNo;
+    const queryToken = initResult.data?.queryToken || '';
+    if (!payUrl) {
+      databaseAPI.updatePaymentOrder(order.id, { status: 'failed', result: '未获取到支付链接' });
+      return;
+    }
+
+    if (queryToken) {
+      db.prepare(`UPDATE payment_orders SET query_token = ? WHERE id = ?`).run(queryToken, order.id);
+    }
+
+    // 二维码
+    let qrImageUrl = '';
+    try {
+      const qrDataUrl = await QRCode.toDataURL(payUrl, { width: 256, margin: 2 });
+      qrImageUrl = await uploadBase64ToOSS(qrDataUrl, `chat/pay/qr_${Date.now()}.png`);
+    } catch (e) {
+      _log({ event: 'qr_fail', orderId: order.id, error: e.message });
+      console.error('[Payment] 二维码生成/上传失败:', e.message);
+    }
+
+    // 发送给访客
+    const entry = agentWorkers?.get(order.agent_id);
+    let fromUid = order.from_uid || '';
+    if (!fromUid) {
+      try {
+        const row = db.prepare(`SELECT imUid FROM agents WHERE agent_id = ?`).get(order.agent_id);
+        fromUid = row?.imUid || 'voko';
+      } catch (_) { fromUid = 'voko'; }
+    }
+
+    const textMsg = `请支付 ¥${order.amount.toFixed(2)}，支付链接：${payUrl}`;
+    const textMsgId = `pay_msg_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+    const timestamp = Math.floor(Date.now() / 1000);
+
+    db.prepare(`INSERT INTO messages (id, from_uid, to_uid, content, channel_id, channel_type, agent_id, timestamp, is_me, status, message_seq, client_msg_no, no_persist, red_dot, sync_once, content_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(textMsgId, fromUid, order.visitor_id, textMsg, order.visitor_id, 1, order.agent_id, timestamp, 1, 'sent', null, null, 0, 0, 0, 1);
+
+    db.prepare(`INSERT OR IGNORE INTO conversations (user_uid, channel_id, channel_type, name, last_message, last_timestamp, unread_count, agent_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(fromUid, order.visitor_id, 1, order.visitor_id, textMsg, timestamp, 0, order.agent_id);
+    db.prepare(`UPDATE conversations SET last_message = ?, last_timestamp = ? WHERE user_uid = ? AND channel_id = ?`)
+      .run(textMsg, timestamp, fromUid, order.visitor_id);
+
+    if (entry) {
+      entry.worker.send({ type: 'send', channelId: order.visitor_id, content: textMsg, messageType: 'text', localMsgId: textMsgId });
+    }
+
+    if (qrImageUrl) {
+      const imgMsgId = `pay_msg_img_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`;
+      db.prepare(`INSERT INTO messages (id, from_uid, to_uid, content, channel_id, channel_type, agent_id, timestamp, is_me, status, message_seq, client_msg_no, no_persist, red_dot, sync_once, content_type) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(imgMsgId, fromUid, order.visitor_id, qrImageUrl, order.visitor_id, 1, order.agent_id, timestamp + 1, 1, 'sent', null, null, 0, 0, 0, 2);
+
+      if (entry) {
+        entry.worker.send({ type: 'send', channelId: order.visitor_id, content: qrImageUrl, messageType: 'image', localMsgId: imgMsgId });
+      }
+    }
+
+    // UI 通知（通过回调）
+    _notify('agent-wukongim:message', {
+      agentId: order.agent_id, fromUid, toUid: order.visitor_id,
+      channelId: order.visitor_id, content: textMsg, timestamp
+    });
+    if (qrImageUrl) {
+      _notify('agent-wukongim:message', {
+        agentId: order.agent_id, fromUid, toUid: order.visitor_id,
+        channelId: order.visitor_id, content: qrImageUrl, contentType: 2, timestamp: timestamp + 1
+      });
+    }
+
+    databaseAPI.updatePaymentOrder(order.id, { status: 'created', order_no: orderNo, pay_url: payUrl });
+    _log({ event: 'order_created', orderId: order.id, orderNo });
+    console.log('[Payment] 订单已创建并通知访客:', order.id, orderNo);
+  } catch (e) {
+    _log({ event: 'pending_fail', orderId: order.id, error: e.message });
+    console.error('[Payment] 处理 pending 订单失败:', order.id, e.message);
+    databaseAPI.updatePaymentOrder(order.id, { status: 'failed', result: e.message });
+  }
+}
+
+/**
+ * 启动支付轮询
+ *
+ * 每 5 秒检查 created 订单：超 30 分钟 → expired，成功支付 → paid 并通知各方。
+ *
+ * @param {object} deps
+ * @param {object} deps.db
+ * @param {object} deps.databaseAPI
+ * @param {object} deps.agentWorkers - Map<agentId, {worker}>
+ * @param {object} deps.endpoints - { payment: { baseUrl } }
+ * @param {object} deps.hermesHandler
+ * @param {object} deps.openclawHandler
+ * @param {Function} deps.sendSystemMessage - (agentId, visitorId, content) => {}
+ * @param {Function} deps.payLog - (data) => {}
+ * @param {object} deps.ownerInterventionNotifier - 可选
+ */
+function startPaymentPolling(deps) {
+  const { db, databaseAPI, agentWorkers, endpoints, hermesHandler, openclawHandler, sendSystemMessage, payLog, ownerInterventionNotifier } = deps;
+  const _log = payLog || (() => {});
+  const _sendMsg = sendSystemMessage || (() => {});
+
+  let pollInterval = 5000;
+  let pollTimer = null;
+
+  const scheduleNext = () => {
+    pollTimer = setTimeout(doPoll, pollInterval);
+  };
+
+  const doPoll = async () => {
+    try {
+      const createdOrders = databaseAPI.getPaymentOrdersByStatus('created');
+      const now = Date.now();
+      for (const order of createdOrders) {
+        try {
+          // 超 30 分钟未支付 → expired
+          if (now - order.updated_at > 30 * 60 * 1000) {
+            databaseAPI.updatePaymentOrder(order.id, { status: 'expired' });
+            try {
+              const expWorker = agentWorkers?.get(order.agent_id);
+              if (expWorker) {
+                const isTimed = order.type === 'timed';
+                const expireMsg = isTimed
+                  ? '【系统消息】支付超时，订单已过期。如需继续使用请回复"购买"。'
+                  : '【系统消息】支付超时！订单号：' + (order.order_no || '-') + '，项目：' + (order.description || '无') + '，金额：¥' + order.amount.toFixed(2) + '。支付链接已过期，如需重新购买请联系 Agent。';
+                const uid = db.prepare(`SELECT imUid FROM agents WHERE agent_id = ?`).get(order.agent_id)?.imUid;
+                if (uid) _sendMsg(order.agent_id, order.visitor_id, expireMsg);
+              }
+            } catch (e) { console.error('[Payment] 通知访客超时失败:', e.message); }
+            continue;
+          }
+
+          const qt = db.prepare(`SELECT query_token FROM payment_orders WHERE id = ?`).get(order.id);
+          const queryToken = qt?.query_token || '';
+          const queryResp = await fetch(endpoints.payment.baseUrl + '/payment/order/' + order.order_no + '?token=' + queryToken, { method: 'GET' });
+          const queryResult = await queryResp.json();
+
+          if (queryResult.success && queryResult.data?.status === 1) {
+            const paidData = queryResult.data;
+            paidData.transaction_no = paidData.transactionNo || paidData.tradeNo || paidData.thirdTradeNo || '';
+            databaseAPI.updatePaymentOrder(order.id, { status: 'paid', result: JSON.stringify(paidData) });
+
+            // 激活会话
+            try {
+              if (order.type === 'timed') {
+                const pa = db.prepare('SELECT duration_minutes FROM agent_pricing WHERE agent_id = ? AND enabled = 1').get(order.agent_id);
+                if (pa && pa.duration_minutes) {
+                  const conv = db.prepare('SELECT session_status, session_expire_at FROM conversations WHERE user_uid = ? AND channel_id = ?').get(order.from_uid, order.visitor_id);
+                  const n2 = Date.now();
+                  const dur = pa.duration_minutes * 60 * 1000;
+                  const expireAt = (conv && conv.session_status === 'active' && conv.session_expire_at > n2) ? conv.session_expire_at + dur : n2 + dur;
+                  if (conv) {
+                    db.prepare('UPDATE conversations SET session_status=?, session_expire_at=? WHERE user_uid=? AND channel_id=?').run('active', expireAt, order.from_uid, order.visitor_id);
+                  } else {
+                    db.prepare(`INSERT INTO conversations (user_uid, channel_id, channel_type, name, last_message, last_timestamp, session_status, session_expire_at, agent_id) VALUES (?, ?, 1, ?, '', ?, 'active', ?, ?)`).run(order.from_uid, order.visitor_id, order.visitor_id, n2, expireAt, order.agent_id);
+                  }
+                }
+              }
+            } catch (e) { console.error('[计费] 激活会话失败:', e.message); }
+
+            // 通知访客
+            try {
+              const payWorker = agentWorkers?.get(order.agent_id);
+              if (payWorker) {
+                const isTimed = order.type === 'timed';
+                const payMsg = isTimed
+                  ? '【系统消息】支付成功！已开通使用时长，请继续与 Agent 对话。'
+                  : '【系统消息】支付成功！金额：¥' + order.amount.toFixed(2) + '，项目：' + (order.description || '无') + '，订单号：' + (order.order_no || '-') + '。已通知 Agent 准备后续服务。';
+                _sendMsg(order.agent_id, order.visitor_id, payMsg);
+              }
+            } catch (e) { console.error('[Payment] 通知访客支付结果失败:', e.message); }
+
+            // 通知 agent
+            try {
+              const payAgent = db.prepare(`SELECT backend_type FROM agents WHERE agent_id = ?`).get(order.agent_id);
+              const payBackend = payAgent?.backend_type || 'openclaw';
+              const payMsg2 = `[Payment Notification]\n访客: ${order.visitor_id}\n金额: ¥${order.amount.toFixed(2)}\n描述: ${order.description || '无'}\n订单号: ${order.order_no || '-'}\n交易流水号: ${paidData.transactionNo || ''}`;
+              if (payBackend === 'hermes' && hermesHandler?.connected) {
+                hermesHandler.steer(`hermes:${order.agent_id}:${order.visitor_id}`, payMsg2);
+              } else if (openclawHandler?.connected) {
+                openclawHandler.sendToSession(`agent:${order.agent_id}:${order.visitor_id}`, payMsg2);
+              }
+            } catch (e) { console.error('[Payment] 通知 agent 失败:', e.message); }
+
+            // 通知主人
+            try {
+              const now2 = Date.now();
+              const oiId = 'pay_' + now2 + '_' + Math.random().toString(36).substr(2, 6);
+              const ownerMsg = '💰 支付成功通知\nAgent: ' + order.agent_id + '\n访客: ' + order.visitor_id + '\n金额: ¥' + order.amount.toFixed(2);
+              const payPrefix = (db.prepare(`SELECT backend_type FROM agents WHERE agent_id = ?`).get(order.agent_id)?.backend_type) === 'hermes' ? 'hermes' : 'agent';
+              databaseAPI.saveOwnerIntervention({
+                id: oiId, visitorId: order.visitor_id, sessionKey: payPrefix + ':' + order.agent_id + ':' + order.visitor_id,
+                problem: ownerMsg, agentSuggestion: '支付成功通知，无需回复', askTime: now2,
+                status: 'pending', channelType: 'voko', createdAt: now2, updatedAt: now2, agentId: order.agent_id,
+              });
+              if (ownerInterventionNotifier) ownerInterventionNotifier.enqueue({ id: oiId, visitorId: order.visitor_id, agentId: order.agent_id, sessionKey: payPrefix + ':' + order.agent_id + ':' + order.visitor_id, problem: ownerMsg, agentSuggestion: '支付成功通知，无需回复', askTime: now2, skipReply: 1 });
+            } catch (e) { console.error('[Payment] 通知主人失败:', e.message); }
+          }
+        } catch (e) {
+          _log({ event: 'query_fail', orderId: order.id, error: e.message });
+          console.error('[Payment] 查询订单状态失败:', order.id, e.message);
+        }
+      }
+    } catch (err) {
+      _log({ event: 'poll_error', error: err.message });
+      console.error('[Payment] 支付轮询错误:', err.message);
+    }
+    scheduleNext();
+  };
+
+  scheduleNext();
+  console.log('[Payment] 启动支付轮询，初始间隔 5s');
+
+  // 返回停止函数
+  return () => { if (pollTimer) clearTimeout(pollTimer); };
+}
+
+module.exports = { processPendingPaymentOrder, startPaymentPolling };

package/src/core/publish-agent.js

@@ -0,0 +1,166 @@
+/**
+ * Agent 发布/下架核心逻辑
+ *
+ * 把原来 main.js 中 agent-wukongim:connect / disconnect 的业务逻辑抽取出来，
+ * 供主进程 IPC 和 MCP 工具共享。
+ *
+ * 注意：本模块零 Electron 依赖，所有副作用（启动/停止 worker、能力注册、通知 UI 等）
+ * 都通过 opts 注入。
+ */
+
+/**
+ * 发布 Agent：启动 Worker、连接 IM、注册能力、同步资料、同步服务端状态
+ * @param {Object} opts
+ * @param {Object} opts.db - better-sqlite3 Database 实例
+ * @param {string} opts.agentId
+ * @param {Function} opts.startAgentWorker - (agentId, config) => void
+ * @param {Function} opts.stopAgentWorker - (agentId) => Promise|void
+ * @param {Function} opts.registerCapabilities - (agentId, options?) => Promise
+ * @param {Function} opts.updateAgentProfile - (params) => Promise
+ * @param {Function} opts.setAgentStatus - (params) => Promise
+ * @param {Object} [opts.endpoints] - 端点配置，用于 chatroom_url
+ * @returns {Promise<{success: boolean, error?: string}>}
+ */
+async function publishAgent(opts) {
+  const { db, agentId, startAgentWorker, stopAgentWorker, registerCapabilities, updateAgentProfile, setAgentStatus, endpoints } = opts || {};
+
+  if (!db) return { success: false, error: 'db is required' };
+  if (!agentId) return { success: false, error: 'agentId is required' };
+
+  try {
+    const row = db.prepare(`SELECT * FROM agents WHERE agent_id = ?`).get(agentId);
+    if (!row) return { success: false, error: 'Agent not found' };
+    if (!row.imUid || !row.imToken || !row.im_server_url) {
+      return { success: false, error: 'Agent 缺少 IM 绑定信息' };
+    }
+
+    const { imUid: uid, imToken: token, im_server_url: serverUrl } = row;
+
+    // 如果该 uid 已绑定其他 agent，先解除其绑定
+    const existingStmt = db.prepare(`SELECT agent_id FROM agents WHERE imUid = ? AND agent_id != ?`);
+    const existing = existingStmt.get(uid, agentId);
+    if (existing) {
+      db.prepare(`UPDATE agents SET publish_status = 'unpublished' WHERE agent_id = ?`).run(existing.agent_id);
+      if (stopAgentWorker) {
+        try { await stopAgentWorker(existing.agent_id); } catch (_) {}
+      }
+      console.log(`[${existing.agent_id}] WuKongIM 账号已被其他 agent 占用，已自动下架`);
+    }
+
+    // 启动 Worker 进程
+    if (startAgentWorker) {
+      startAgentWorker(agentId, { uid, token, serverUrl });
+    }
+
+    const now = Date.now();
+    const imBaseUrl = endpoints?.im?.baseUrl || '';
+    const chatroomUrl = uid && imBaseUrl ? imBaseUrl + '/#/chat?peer=' + uid : '';
+    const backend = row.backend_type || 'openclaw';
+    // 上架不影响 access_mode，由 voko_set_private_mode 专门控制
+    const accessMode = row.access_mode || 'public';
+    const visibility = accessMode === 'private' ? 0 : 1;
+
+    db.prepare(`
+      INSERT INTO agents (id, agent_id, imUid, imToken, im_server_url, owner_email, chatroom_url, agent_name, category, category_label, publish_status, access_mode, backend_type, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'published', ?, ?, ?, ?)
+      ON CONFLICT(agent_id) DO UPDATE SET
+        imUid = excluded.imUid,
+        imToken = excluded.imToken,
+        im_server_url = excluded.im_server_url,
+        owner_email = excluded.owner_email,
+        chatroom_url = excluded.chatroom_url,
+        agent_name = excluded.agent_name,
+        category = excluded.category,
+        category_label = excluded.category_label,
+        publish_status = 'published',
+        backend_type = excluded.backend_type,
+        updated_at = excluded.updated_at
+    `).run(`agent-${agentId}`, agentId, uid, token, serverUrl, row.owner_email || null, chatroomUrl, row.agent_name || null, row.category || null, row.category_label || null, accessMode, backend, now, now);
+
+    // 注册能力到服务端
+    if (registerCapabilities) {
+      try { await registerCapabilities(agentId); } catch (e) {
+        console.warn(`[publishAgent] Agent ${agentId} 注册能力失败:`, e.message);
+      }
+    }
+
+    // 同步本地已有资料字段到服务端
+    if (updateAgentProfile) {
+      try {
+        const fresh = db.prepare(`SELECT * FROM agents WHERE agent_id = ?`).get(agentId);
+        const fields = {};
+        if (fresh?.description) fields.description = fresh.description;
+        if (fresh?.short_description) fields.short_description = fresh.short_description;
+        if (fresh?.address) fields.address = fresh.address;
+        if (fresh?.contact_phone) fields.contact_phone = fresh.contact_phone;
+        if (fresh?.tags) fields.tags = fresh.tags;
+        if (fresh?.category) fields.category = fresh.category;
+        if (fresh?.icon_url) fields.icon_url = fresh.icon_url;
+        if (Object.keys(fields).length) {
+          await updateAgentProfile({ agentId, ...fields });
+        }
+      } catch (e) {
+        console.warn(`[publishAgent] Agent ${agentId} 同步资料失败:`, e.message);
+      }
+    }
+
+    // 同步上下架状态到服务端（保持当前 access_mode 对应的 visibility）
+    if (setAgentStatus) {
+      setAgentStatus({ agentId, status: 1, visibility }).catch(() => {});
+    }
+
+    return { success: true, publishStatus: 'published', accessMode };
+  } catch (e) {
+    console.error(`[publishAgent] Agent ${agentId} error:`, e);
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * 下架 Agent：能力设为不可发现、停止 Worker、更新本地状态、同步服务端状态
+ * @param {Object} opts
+ * @param {Object} opts.db - better-sqlite3 Database 实例
+ * @param {string} opts.agentId
+ * @param {Function} opts.stopAgentWorker - (agentId) => Promise|void
+ * @param {Function} opts.registerCapabilities - (agentId, options?) => Promise
+ * @param {Function} opts.setAgentStatus - (params) => Promise
+ * @returns {Promise<{success: boolean, error?: string}>}
+ */
+async function unpublishAgent(opts) {
+  const { db, agentId, stopAgentWorker, registerCapabilities, setAgentStatus } = opts || {};
+
+  if (!db) return { success: false, error: 'db is required' };
+  if (!agentId) return { success: false, error: 'agentId is required' };
+
+  try {
+    // 读取当前可见性，下架时保持其不变
+    const currentRow = db.prepare(`SELECT access_mode FROM agents WHERE agent_id = ?`).get(agentId);
+    const currentAccessMode = currentRow?.access_mode || 'public';
+    const visibility = currentAccessMode === 'private' ? 0 : 1;
+
+    // 通知服务端该 agent 不再可发现
+    if (registerCapabilities) {
+      try { await registerCapabilities(agentId, { discoverable: false }); } catch (_) {}
+    }
+
+    // 同步上下架状态到服务端（保持原有 visibility）
+    if (setAgentStatus) {
+      setAgentStatus({ agentId, status: 0, visibility }).catch(() => {});
+    }
+
+    // 停止 Worker
+    if (stopAgentWorker) {
+      try { await stopAgentWorker(agentId); } catch (_) {}
+    }
+
+    // 更新本地 DB（只改 publish_status，保留 access_mode）
+    db.prepare(`UPDATE agents SET publish_status = 'unpublished', updated_at = ? WHERE agent_id = ?`).run(Date.now(), agentId);
+
+    return { success: true, publishStatus: 'unpublished' };
+  } catch (e) {
+    console.error(`[unpublishAgent] Agent ${agentId} error:`, e);
+    return { success: false, error: e.message };
+  }
+}
+
+module.exports = { publishAgent, unpublishAgent };