@voko/lite 0.3.1

package/src/context.js

@@ -0,0 +1,164 @@
+/**
+ * Lite MCP context 工厂
+ *
+ * 填实所有 stub，与 Desktop 共用同一套 core 模块。
+ * 本文件在 Step 3 切换为 @voko/core 包引用。
+ */
+
+const { searchCapabilitiesByDid, searchCapabilitiesByHmac } = require('./core/search-capabilities');
+const { updateAgentProfile } = require('./core/update-agent-profile');
+const { setAgentStatus } = require('./core/set-agent-status');
+const { publishAgent, unpublishAgent } = require('./core/publish-agent');
+const { toggleWhitelistMode: coreToggleWhitelistMode } = require('./core/access-control');
+const { registerCapabilitiesForAgent } = require('./core/register-capabilities');
+const { generateOSSSignature } = require('./server/oss');
+const { createSendMessageToWorker } = require('./core/send-message');
+
+const pkg = require('../package.json');
+
+function createContext({ db, databaseAPI, agentRegistration, agentManager }) {
+  // 创建 sendMessage 函数（写 DB + worker 发送，无 UI 通知）
+  const sendMessage = createSendMessageToWorker({
+    db,
+    agentWorkers: agentManager?.workers || new Map(),
+    mainWindow: null,
+  });
+
+  return {
+    db,
+    query: (sql, params) => {
+      try {
+        const stmt = db.prepare(sql);
+        return params ? stmt.all(...params) : stmt.all();
+      } catch (e) {
+        console.error('[Lite:query]', e.message);
+        return [];
+      }
+    },
+    exec: (sql, params) => {
+      try {
+        const stmt = db.prepare(sql);
+        return params ? stmt.run(...params) : stmt.run();
+      } catch (e) {
+        console.error('[Lite:exec]', e.message);
+        return { changes: 0 };
+      }
+    },
+    databaseAPI,
+
+    // ── 消息 ──
+    sendMessage: (agentId, toUid, content, fromUid, messageType) => {
+      return sendMessage(agentId, toUid, content, fromUid, messageType);
+    },
+
+    // ── Worker 管理 ──
+    startAgentWorker: (agentId, config, appPaths) => {
+      if (!agentManager) {
+        console.error('[Lite] agentManager 未初始化');
+        return;
+      }
+      agentManager.start(agentId, config, appPaths);
+    },
+
+    stopAgentWorker: async (agentId) => {
+      if (!agentManager) return;
+      await agentManager.stop(agentId);
+    },
+
+    getAgentStatus: (agentId) => {
+      if (!agentManager) return { imConnected: false, imStatus: 'unknown', backendConnected: false };
+      const status = agentManager.getStatus(agentId);
+      return {
+        imConnected: status.connected,
+        imStatus: status.status || 'unknown',
+        backendConnected: false,
+        uid: status.uid,
+      };
+    },
+
+    // ── 能力注册 ──
+    registerCapabilities: async (agentId, options) => {
+      try {
+        return await registerCapabilitiesForAgent({ db, agentId, options });
+      } catch (e) {
+        console.error('[Lite] registerCapabilities 失败:', e.message);
+        return { success: false, error: e.message };
+      }
+    },
+
+    // ── Agent 资料 ──
+    updateAgentProfile: (params) => updateAgentProfile({ db, ...params }),
+    setAgentStatus: (params) => setAgentStatus({ db, ...params }),
+
+    // ── 访问控制 ──
+    toggleWhitelistMode: async ({ agentId, enabled }) => coreToggleWhitelistMode({
+      db, agentId, enabled,
+      registerCapabilities: (aid, opts) => registerCapabilitiesForAgent({ db, agentId: aid, options: opts }),
+      setAgentStatus: (params) => setAgentStatus({ db, ...params }),
+    }),
+
+    // ── 发布/下架 ──
+    publishAgent: (params) => publishAgent({
+      db, ...params,
+      registerCapabilities: (aid, opts) => registerCapabilitiesForAgent({ db, agentId: aid, options: opts }),
+      updateAgentProfile: (p) => updateAgentProfile({ db, ...p }),
+      setAgentStatus: (p) => setAgentStatus({ db, ...p }),
+      startAgentWorker: (aid, cfg) => agentManager?.start(aid, cfg),
+      stopAgentWorker: (aid) => agentManager?.stop(aid),
+    }),
+
+    unpublishAgent: (params) => unpublishAgent({
+      db, ...params,
+      registerCapabilities: (aid, opts) => registerCapabilitiesForAgent({ db, agentId: aid, options: opts }),
+      setAgentStatus: (p) => setAgentStatus({ db, ...p }),
+      stopAgentWorker: (aid) => agentManager?.stop(aid),
+    }),
+
+    // ── 能力搜索 ──
+    searchCapabilities: async (params) => {
+      try {
+        const { agent_id, keyword, page, limit } = params || {};
+        const searchOpts = { db, agentId: agent_id, keyword, page, limit };
+        try { return await searchCapabilitiesByDid(searchOpts); } catch (_) {}
+        return await searchCapabilitiesByHmac({ keyword, page, limit });
+      } catch (e) {
+        return { success: false, error: e.message };
+      }
+    },
+
+    // ── OSS ──
+    generateOSSSignature: (filename, dir, contentType, maxSize) => {
+      try {
+        return generateOSSSignature(filename, contentType, maxSize);
+      } catch (e) {
+        console.error('[Lite] OSS 签名失败:', e.message);
+        return { uploadUrl: null, fileUrl: null, error: e.message };
+      }
+    },
+
+    // ── 注册 ──
+    agentRegistration,
+
+    // ── 支付 ──
+    getPaymentAuth: (agentId) => {
+      try { return databaseAPI.getPaymentAuth(agentId); } catch (_) { return null; }
+    },
+    getAgentImUid: (agentId) => {
+      try { return databaseAPI.getAgentImUid(agentId); } catch (_) { return ''; }
+    },
+    savePaymentOrder: (order) => {
+      try { return databaseAPI.savePaymentOrder(order); } catch (_) {}
+    },
+
+    // ── WuKongIM ──
+    wukongim: {
+      getCurrentUid: (agentId) => {
+        try { return databaseAPI.getAgentImUid(agentId); } catch (_) { return 'voko'; }
+      },
+    },
+
+    version: pkg.version,
+  };
+}
+
+module.exports = { createContext };

package/src/core/access-control-api.js

@@ -0,0 +1,150 @@
+/**
+ * 访问控制（黑白名单）API 模块
+ *
+ * 纯函数，无 Electron / IPC 依赖。
+ * 所有函数第一个参数为 db（better-sqlite3 实例），依赖显式传入。
+ */
+
+/**
+ * 查询黑白名单列表
+ */
+function getList(db, { agentId, listType }) {
+  try {
+    const rows = db.prepare(
+      `SELECT id, visitor_id, reason, created_at FROM agent_access_lists WHERE agent_id = ? AND list_type = ? ORDER BY created_at DESC`
+    ).all(agentId, listType);
+    return { success: true, data: rows };
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * 添加黑白名单条目
+ * 如果 listType='whitelist' 且传了 onWhitelistAdded，添加成功后自动回调通知
+ *
+ * @param {Function} [onWhitelistAdded] - (agentId, visitorId) => void
+ */
+function addEntry(db, { agentId, listType, visitorId, reason }, { onWhitelistAdded } = {}) {
+  try {
+    const id = `acl-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    const now = Date.now();
+    db.prepare(
+      `INSERT INTO agent_access_lists (id, agent_id, list_type, visitor_id, reason, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, agentId, listType, visitorId, reason || null, now, now);
+    // 白名单添加成功后自动通知访客
+    if (listType === 'whitelist' && onWhitelistAdded) {
+      try { onWhitelistAdded(agentId, visitorId); } catch (_) {}
+    }
+    return { success: true, id };
+  } catch (e) {
+    if (e.message && e.message.includes('UNIQUE')) {
+      return { success: false, error: '该访客已在此名单中' };
+    }
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * 删除黑白名单条目（按条件）
+ */
+function removeEntryByVisitor(db, agentId, visitorId, listType) {
+  try {
+    db.prepare(`DELETE FROM agent_access_lists WHERE agent_id=? AND visitor_id=? AND list_type=?`).run(agentId, visitorId, listType);
+    return { success: true };
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * 删除黑白名单条目
+ */
+function removeEntry(db, id) {
+  try {
+    db.prepare(`DELETE FROM agent_access_lists WHERE id = ?`).run(id);
+    return { success: true };
+  } catch (e) {
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * 检查访客是否在黑名单中
+ */
+function isBlacklisted(db, agentId, visitorId) {
+  return !!db.prepare(
+    `SELECT 1 FROM agent_access_lists WHERE agent_id = ? AND list_type = 'blacklist' AND visitor_id = ?`
+  ).get(agentId, visitorId);
+}
+
+/**
+ * 检查访客是否在白名单中
+ */
+function isWhitelisted(db, agentId, visitorId) {
+  return !!db.prepare(
+    `SELECT 1 FROM agent_access_lists WHERE agent_id = ? AND list_type = 'whitelist' AND visitor_id = ?`
+  ).get(agentId, visitorId);
+}
+
+/**
+ * 检查主人回复是否是同意好友申请，是则自动加入白名单并通知访客
+ * 干预记录 id 以 private_req_ 开头表示好友申请类型
+ *
+ * @param {Object} db - better-sqlite3 实例
+ * @param {Function} sendSystemMessage - (agentId, visitorId, content, timestamp) => void
+ * @param {Object} intervention - 干预记录
+ * @param {string} ownerReply - 主人回复内容
+ * @returns {boolean} 是否已处理
+ */
+function autoApproveIfFriendRequest(db, sendSystemMessage, intervention, ownerReply) {
+  if (!intervention || !intervention.id || !intervention.id.startsWith('private_req_')) return false;
+  if (!ownerReply || typeof ownerReply !== 'string') return false;
+  const trimmed = ownerReply.trim();
+  const isApproved = /同意|通过|好的|ok/i.test(trimmed);
+  if (!isApproved) return false;
+
+  const { agentId, visitorId } = intervention;
+  if (!agentId || !visitorId) return false;
+
+  // 检查是否已在白名单中
+  if (isWhitelisted(db, agentId, visitorId)) {
+    console.log(`[好友申请] 访客 ${visitorId} 已在白名单中，跳过`);
+    return true;
+  }
+
+  const systemMsg = '【系统消息】好友申请已通过，可以继续交流。';
+  const result = addEntry(db, { agentId, listType: 'whitelist', visitorId, reason: '好友申请已通过' }, {
+    onWhitelistAdded: (aid, vid) => {
+      sendSystemMessage(aid, vid, systemMsg, Math.floor(Date.now() / 1000));
+    }
+  });
+  if (result.success) {
+    console.log(`[好友申请] 访客 ${visitorId} 已自动加入 Agent ${agentId} 的白名单`);
+  } else {
+    console.error('[好友申请] 自动加入白名单失败:', result.error);
+  }
+  return true;
+}
+
+/**
+ * 通知服务端 Agent 状态变更（HTTP POST）
+ */
+function postAgentStatus(apiBase, agentId, data) {
+  fetch(`${apiBase}/api/agent-status`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ agentId, ...data })
+  }).catch(err => console.warn('[AgentStatus] 通知服务端失败:', err.message));
+}
+
+module.exports = {
+  getList,
+  addEntry,
+  removeEntry,
+  removeEntryByVisitor,
+  isBlacklisted,
+  isWhitelisted,
+  autoApproveIfFriendRequest,
+  postAgentStatus,
+};

package/src/core/access-control.js

@@ -0,0 +1,56 @@
+/**
+ * 访问控制（黑白名单 / 白名单模式）核心逻辑
+ *
+ * 供主进程 IPC 和 MCP 工具共享。
+ * 注意：UI 通知等 Electron 相关副作用由调用方处理。
+ */
+
+/**
+ * 切换白名单模式（public ↔ private，不影响 publish_status）
+ * @param {Object} opts
+ * @param {Object} opts.db - better-sqlite3 Database 实例
+ * @param {string} opts.agentId
+ * @param {boolean} opts.enabled - true=private, false=public
+ * @param {Function} opts.registerCapabilities - (agentId, options?) => Promise
+ * @param {Function} opts.setAgentStatus - (params) => Promise
+ * @returns {Promise<{success: boolean, accessMode?: string, error?: string}>}
+ */
+async function toggleWhitelistMode(opts) {
+  const { db, agentId, enabled, registerCapabilities, setAgentStatus } = opts || {};
+
+  if (!db) return { success: false, error: 'db is required' };
+  if (!agentId) return { success: false, error: 'agentId is required' };
+
+  try {
+    const newMode = enabled ? 'private' : 'public';
+    const now = Date.now();
+    db.prepare(`UPDATE agents SET access_mode = ?, updated_at = ? WHERE agent_id = ?`).run(newMode, now, agentId);
+
+    // 重新注册能力（更新 discoverable 标志）
+    if (registerCapabilities) {
+      try { await registerCapabilities(agentId, { discoverable: !enabled }); }
+      catch (e) { console.warn(`[toggleWhitelistMode] Agent ${agentId} 更新能力发现状态失败:`, e.message); }
+    }
+
+    // 同步公开/私有状态到服务端（保持当前上架状态）
+    if (setAgentStatus) {
+      const pubRow = db.prepare(`SELECT publish_status FROM agents WHERE agent_id = ?`).get(agentId);
+      const pubStatus = pubRow?.publish_status === 'published' ? 1 : 0;
+      try {
+        const syncResult = await setAgentStatus({ agentId, status: pubStatus, visibility: enabled ? 0 : 1 });
+        if (!syncResult?.success) {
+          console.warn(`[toggleWhitelistMode] Agent ${agentId} 同步服务端失败:`, syncResult?.error || '未知错误');
+        }
+      } catch (e) {
+        console.warn(`[toggleWhitelistMode] Agent ${agentId} 同步服务端异常:`, e.message);
+      }
+    }
+
+    return { success: true, accessMode: newMode };
+  } catch (e) {
+    console.error('[toggleWhitelistMode] error:', e);
+    return { success: false, error: e.message };
+  }
+}
+
+module.exports = { toggleWhitelistMode };

package/src/core/agent-registration.js

@@ -0,0 +1,319 @@
+/**
+ * VOKO Agent 注册/验证共享逻辑
+ *
+ * 供桌面端 IPC handler 和 MCP 工具共同调用：
+ * - 发送邮箱验证码
+ * - 验证验证码并获取 DID/IM 账号/密钥
+ * - 用本地 userAccessToken 静默创建 Agent
+ * - 写入/更新本地 SQLite agents 表
+ *
+ * 注意：本模块只做“注册（unpublished）”，不启动 worker。
+ */
+
+const { VOKO_API_URL, VOKO_API_KEY, generateApiSignature } = require('./api-signature');
+const ENDPOINTS = require('../endpoints.json');
+
+const USER_ACCESS_TOKEN_CONFIG_TYPE = 'user_access_token';
+const DEFAULT_IM_SERVER_URL = ENDPOINTS.im.wsUrl;
+
+function normalizeUserEmail(email) {
+  return String(email || '').trim().toLowerCase();
+}
+
+function createAgentRegistration({ db }) {
+  if (!db) throw new Error('AgentRegistration requires db');
+
+  // ─── userAccessToken 读写 ───
+  function loadUserAccessTokenConfig() {
+    try {
+      const row = db.prepare('SELECT data FROM config WHERE type = ?').get(USER_ACCESS_TOKEN_CONFIG_TYPE);
+      if (!row?.data) return {};
+      const parsed = JSON.parse(row.data);
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    } catch (e) {
+      console.warn('[AgentRegistration] loadUserAccessTokenConfig error:', e.message);
+      return {};
+    }
+  }
+
+  function saveUserAccessTokenConfig(map) {
+    db.prepare('INSERT OR REPLACE INTO config (type, data, updated_at) VALUES (?, ?, ?)')
+      .run(USER_ACCESS_TOKEN_CONFIG_TYPE, JSON.stringify(map), Date.now());
+  }
+
+  function saveUserAccessToken(email, token) {
+    const normalized = normalizeUserEmail(email);
+    if (!normalized || !token) return;
+    saveUserAccessTokenConfig({ [normalized]: { user_access_token: token, updated_at: Date.now() } });
+  }
+
+  function getUserAccessToken() {
+    try {
+      const map = loadUserAccessTokenConfig();
+      const entries = Object.entries(map);
+      if (entries.length === 0) return { success: true, data: null };
+      entries.sort((a, b) => (b[1]?.updated_at || 0) - (a[1]?.updated_at || 0));
+      const [email, val] = entries[0];
+      if (val?.user_access_token) {
+        return { success: true, data: { email, token: val.user_access_token } };
+      }
+      return { success: true, data: null };
+    } catch (e) {
+      console.error('[AgentRegistration] getUserAccessToken error:', e.message);
+      return { success: false, error: e.message };
+    }
+  }
+
+  function saveUserAccessTokenFromVerify(email, verifyJson) {
+    const normalizedEmail = normalizeUserEmail(verifyJson.email || email);
+    if (!normalizedEmail || !verifyJson.userAccessToken) return null;
+    saveUserAccessToken(normalizedEmail, verifyJson.userAccessToken);
+    console.log('[AgentRegistration] saved userAccessToken for', normalizedEmail);
+    return verifyJson.userAccessToken;
+  }
+
+  // ─── 后端 API：发送验证码 ───
+  async function sendCode({ email, agentName }) {
+    try {
+      const path = '/api/external/v1/send-code';
+      const body = { email };
+      if (agentName) body.agentName = agentName;
+      const { timestamp, signature } = generateApiSignature(path, body);
+
+      console.log('[AgentRegistration] sendCode:', `${VOKO_API_URL}${path}`, 'email:', email);
+
+      const res = await fetch(`${VOKO_API_URL}${path}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': VOKO_API_KEY,
+          'X-Timestamp': timestamp,
+          'X-Signature': signature,
+        },
+        body: JSON.stringify(body),
+      });
+
+      const text = await res.text();
+      console.log('[AgentRegistration] sendCode response:', res.status, text);
+      let json;
+      try { json = JSON.parse(text); } catch { json = { raw: text }; }
+      return { success: res.ok, status: res.status, data: json };
+    } catch (e) {
+      console.error('[AgentRegistration] sendCode error:', e);
+      return { success: false, error: e.message };
+    }
+  }
+
+  // ─── 后端 API：验证码预览（只验码不消费，返回 Agent 列表） ───
+  async function verifyCodePreview({ email, code }) {
+    try {
+      const path = '/api/external/v1/verify-code-preview';
+      const body = { email, code };
+      const { timestamp, signature } = generateApiSignature(path, body);
+
+      const res = await fetch(`${VOKO_API_URL}${path}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': VOKO_API_KEY,
+          'X-Timestamp': timestamp,
+          'X-Signature': signature,
+        },
+        body: JSON.stringify(body),
+      });
+
+      const json = await res.json();
+      if (!res.ok || !json.success) {
+        return { success: false, error: json.message || '验证失败' };
+      }
+      return { success: true, agents: json.agents || [], userExists: !!json.userExists };
+    } catch (e) {
+      console.error('[AgentRegistration] verifyCodePreview error:', e);
+      return { success: false, error: e.message };
+    }
+  }
+
+  // ─── 后端 API：验证验证码 ───
+  async function verifyCode({ email, code, agentName, agentCategory, agentId }) {
+    try {
+      const path = '/api/external/v1/verify-code';
+      const body = { email, code };
+      if (agentName) body.agentName = agentName;
+      if (agentId) body.agentId = agentId;
+      if (agentCategory) body.agentCategory = agentCategory;
+      const { timestamp, signature } = generateApiSignature(path, body);
+
+      console.log('[AgentRegistration] verifyCode:', `${VOKO_API_URL}${path}`, 'email:', email);
+
+      const res = await fetch(`${VOKO_API_URL}${path}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': VOKO_API_KEY,
+          'X-Timestamp': timestamp,
+          'X-Signature': signature,
+        },
+        body: JSON.stringify(body),
+      });
+
+      const text = await res.text();
+      console.log('[AgentRegistration] verifyCode response:', res.status, text);
+      let json;
+      try { json = JSON.parse(text); } catch { json = { raw: text }; }
+
+      if (res.ok && json.did) {
+        const savedToken = saveUserAccessTokenFromVerify(email, json);
+        return { success: true, data: json, userAccessTokenSaved: !!savedToken };
+      }
+      return { success: false, status: res.status, data: json };
+    } catch (e) {
+      console.error('[AgentRegistration] verifyCode error:', e);
+      return { success: false, error: e.message };
+    }
+  }
+
+  // ─── 后端 API：用本地 token 静默创建 Agent ───
+  async function createAgentByToken({ agentId }) {
+    try {
+      if (!agentId) return { success: false, error: '缺少 agentId' };
+
+      const tokenRes = getUserAccessToken();
+      if (!tokenRes.success) return { success: false, error: tokenRes.error };
+      if (!tokenRes.data?.token) return { success: false, error: '未找到 token', noToken: true };
+      const token = tokenRes.data.token;
+
+      const path = '/api/external/v1/agent/create';
+      const body = { name: agentId };
+
+      console.log('[AgentRegistration] createAgentByToken:', agentId);
+
+      const res = await fetch(`${VOKO_API_URL}${path}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token}`,
+        },
+        body: JSON.stringify(body),
+      });
+
+      const json = await res.json();
+      if (!res.ok || !json.success) {
+        const noToken = res.status === 401;
+        return { success: false, error: json.message || '创建失败', noToken, status: res.status };
+      }
+      return { success: true, data: json.data };
+    } catch (e) {
+      console.error('[AgentRegistration] createAgentByToken error:', e.message);
+      return { success: false, error: e.message };
+    }
+  }
+
+  // ─── 本地 SQLite：写入 agents 表（注册，unpublished） ───
+  function registerAgentInDb({
+    agentId,
+    uid,
+    token,
+    serverUrl,
+    ownerEmail,
+    backendType,
+    agentName,
+    category,
+    categoryLabel,
+    did,
+    publicKey,
+    privateKey,
+    loginToken,
+    paymentFeeRate,
+    agentUsageFeeRate,
+  }) {
+    try {
+      const now = Date.now();
+      const backend = backendType || 'others';
+      const imServerUrl = serverUrl || DEFAULT_IM_SERVER_URL;
+      const payRate = paymentFeeRate != null ? paymentFeeRate : 0.006;
+      const usageRate = agentUsageFeeRate != null ? agentUsageFeeRate : 0.1;
+
+      db.prepare(`
+        INSERT INTO agents (id, agent_id, imUid, imToken, im_server_url, owner_email,
+          agent_name, category, category_label, did, public_key, private_key, login_token,
+          payment_fee_rate, agent_usage_fee_rate,
+          publish_status, access_mode, backend_type, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'published', 'private', ?, ?, ?)
+        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,
+          agent_name = excluded.agent_name, category = excluded.category,
+          category_label = excluded.category_label, did = excluded.did,
+          public_key = excluded.public_key, private_key = excluded.private_key,
+          login_token = excluded.login_token,
+          payment_fee_rate = excluded.payment_fee_rate,
+          agent_usage_fee_rate = excluded.agent_usage_fee_rate,
+          backend_type = excluded.backend_type, updated_at = excluded.updated_at
+      `).run(
+        `agent-${agentId}`, agentId, uid, token, imServerUrl, ownerEmail || null,
+        agentName || null, category || null, categoryLabel || null,
+        did || null, publicKey || null, privateKey || null, loginToken || null,
+        payRate, usageRate,
+        backend, now, now
+      );
+
+      console.log('[AgentRegistration] registerAgentInDb success:', agentId);
+      return { success: true };
+    } catch (e) {
+      console.error('[AgentRegistration] registerAgentInDb failed:', agentId, e.message);
+      return { success: false, error: e.message };
+    }
+  }
+
+  // ─── 本地 SQLite：更新 agents 绑定字段 ───
+  function updateAgentBinding({ agentId, updates }) {
+    try {
+      const sets = [];
+      const values = [];
+      if (updates.owner_email !== undefined) { sets.push('owner_email = ?'); values.push(updates.owner_email); }
+      if (updates.chatroom_url !== undefined) { sets.push('chatroom_url = ?'); values.push(updates.chatroom_url); }
+      if (updates.payment_url !== undefined) { sets.push('payment_url = ?'); values.push(updates.payment_url); }
+      if (updates.did !== undefined) { sets.push('did = ?'); values.push(updates.did); }
+      if (updates.public_key !== undefined) { sets.push('public_key = ?'); values.push(updates.public_key); }
+      if (updates.private_key !== undefined) { sets.push('private_key = ?'); values.push(updates.private_key); }
+      if (updates.login_token !== undefined) { sets.push('login_token = ?'); values.push(updates.login_token); }
+      if (updates.imUid !== undefined) { sets.push('imUid = ?'); values.push(updates.imUid); }
+      if (updates.imToken !== undefined) { sets.push('imToken = ?'); values.push(updates.imToken); }
+      if (updates.im_server_url !== undefined) { sets.push('im_server_url = ?'); values.push(updates.im_server_url); }
+      if (updates.imUid !== undefined) { sets.push('chatroom_url = ?'); values.push(ENDPOINTS.im.baseUrl + '/#/chat?peer=' + updates.imUid); }
+      if (updates.ability !== undefined) { sets.push('ability = ?'); values.push(updates.ability); }
+      if (updates.publish_status !== undefined) { sets.push('publish_status = ?'); values.push(updates.publish_status); }
+      if (updates.access_mode !== undefined) { sets.push('access_mode = ?'); values.push(updates.access_mode); }
+      if (updates.short_link_url !== undefined) { sets.push('short_link_url = ?'); values.push(updates.short_link_url); }
+      if (updates.qr_code_url !== undefined) { sets.push('qr_code_url = ?'); values.push(updates.qr_code_url); }
+      if (updates.icon_url !== undefined) { sets.push('icon_url = ?'); values.push(updates.icon_url); }
+
+      if (sets.length === 0) return { success: true };
+      sets.push('updated_at = ?');
+      values.push(Date.now());
+      values.push(agentId);
+
+      const sql = `UPDATE agents SET ${sets.join(', ')} WHERE agent_id = ?`;
+      db.prepare(sql).run(...values);
+      console.log('[AgentRegistration] updateAgentBinding success:', agentId, Object.keys(updates || {}));
+      return { success: true };
+    } catch (e) {
+      console.error('[AgentRegistration] updateAgentBinding error:', e);
+      return { success: false, error: e.message };
+    }
+  }
+
+  return {
+    sendCode,
+    verifyCode,
+    verifyCodePreview,
+    createAgentByToken,
+    getUserAccessToken,
+    saveUserAccessToken,
+    saveUserAccessTokenFromVerify,
+    registerAgentInDb,
+    updateAgentBinding,
+  };
+}
+
+module.exports = { createAgentRegistration };