level-up-mcp-server-cn 0.4.0

package/dist/tools/users.js

@@ -0,0 +1,1306 @@
+// ============================================================
+// tools/users.ts — Section 1: User tools (13 tools)
+// ============================================================
+// IMPORTANT — Column name mapping:
+// The tool spec uses "identity_provider" / "identity_id" as
+// PARAMETER names (what the LLM sends). But the actual database
+// columns in user_identities are "provider" / "provider_id" /
+// "is_hashed". We map between these in each handler.
+// ============================================================
+import { z } from "zod";
+import { createHash, randomInt, timingSafeEqual } from "node:crypto";
+import { supabase } from "../services/supabase.js";
+import { ok, fail, handleSupabaseError } from "../services/errors.js";
+import { generateProfileCode, generateLinkCode, formatRankDisplay } from "../services/format.js";
+import { toMcpResponse, logRegistered } from "../services/register.js";
+import { uuidSchema, identityProviderSchema, metadataSchema } from "../schemas/common.js";
+function hashOtp(code) {
+    return createHash("sha256").update(code).digest("hex");
+}
+// ---- Helper: fetch public profile data for a user ----
+// Several tools need to return a user's public profile.
+// Instead of duplicating this query logic, we extract it here.
+async function fetchPublicProfile(userId) {
+    const { data: user, error } = await supabase
+        .from("users")
+        .select("id, username, handle, profile_code, main_level, main_xp, is_searchable_by_email, email, created_at")
+        .eq("id", userId)
+        .single();
+    if (error || !user)
+        return null;
+    const { data: classes } = await supabase
+        .from("user_class_progress")
+        .select("class_name, class_level, class_xp")
+        .eq("user_id", userId);
+    const { data: rank } = await supabase
+        .from("rank_definitions")
+        .select("rank_name, rank_letter, min_level, max_level")
+        .eq("entity_type", "user")
+        .eq("locale", "zh")
+        .lte("min_level", user.main_level)
+        .gte("max_level", user.main_level)
+        .maybeSingle();
+    // BUG 4+5 FIX: Format rank display with stars
+    const rankDisplay = formatRankDisplay(user.main_level, rank?.rank_letter || null, rank?.rank_name || null, rank?.min_level || 1, rank?.max_level || 5);
+    const classMap = {};
+    for (const c of classes || []) {
+        classMap[c.class_name] = { level: c.class_level, xp: c.class_xp };
+    }
+    return {
+        id: user.id,
+        username: user.username,
+        handle: user.handle,
+        profile_code: user.profile_code,
+        rank_display: rankDisplay.rank_display,
+        rank_letter: rank?.rank_letter || null,
+        rank_name: rank?.rank_name || null,
+        stars: rankDisplay.stars,
+        stars_earned: rankDisplay.stars_earned,
+        stars_total: rankDisplay.stars_total,
+        main_xp: user.main_xp,
+        classes: classMap,
+        email: user.is_searchable_by_email ? user.email : null,
+        created_at: user.created_at,
+    };
+}
+// ============================================================
+// Exported handler functions for dispatcher use
+// ============================================================
+export async function handleRegisterUser(params) {
+    const username = params.username;
+    const identity_provider = params.identity_provider;
+    const identity_id = params.identity_id;
+    const identity_is_hashed = params.identity_is_hashed ?? true;
+    const handle = params.handle;
+    const email = params.email;
+    const is_searchable_by_email = params.is_searchable_by_email ?? false;
+    const wallet_address = params.wallet_address;
+    const metadata = params.metadata;
+    const profileCode = generateProfileCode();
+    const { data: rpcResult, error: rpcError } = await supabase.rpc('register_user_secure', {
+        p_username: username,
+        p_email: email || null,
+        p_profile_code: profileCode,
+        p_handle: handle || null,
+        p_is_searchable_by_email: is_searchable_by_email,
+        p_wallet_address: wallet_address || null,
+        p_metadata: metadata || null,
+        p_identity_provider: identity_provider,
+        p_identity_id: identity_id,
+        p_identity_is_hashed: identity_is_hashed,
+    });
+    if (rpcError) {
+        console.error("[register_user] RPC failed, falling back to direct insert:", rpcError.message);
+        const { data: user, error: userError } = await supabase
+            .from("users")
+            .insert({
+            username,
+            email: email || null,
+            profile_code: profileCode,
+            handle: handle || null,
+            is_searchable_by_email,
+            wallet_address: wallet_address || null,
+            metadata: metadata || null,
+        })
+            .select()
+            .single();
+        if (userError)
+            return toMcpResponse(handleSupabaseError(userError, "register_user"));
+        const classRows = ["trainer", "orchestrator", "partner"].map((cls) => ({
+            user_id: user.id, class_name: cls, class_level: 1, class_xp: 0,
+        }));
+        const { error: classError } = await supabase.from("user_class_progress").insert(classRows);
+        if (classError)
+            console.error("[register_user] Class progress failed:", classError);
+        const { error: idError } = await supabase.from("user_identities").insert({
+            user_id: user.id,
+            provider: identity_provider,
+            provider_id: identity_id,
+            is_hashed: identity_is_hashed,
+            is_primary: true,
+        });
+        if (idError)
+            console.error("[register_user] Identity failed:", idError);
+        return toMcpResponse(ok({
+            id: user.id, username: user.username, profile_code: user.profile_code,
+            handle: user.handle, main_level: user.main_level, main_xp: user.main_xp,
+            classes: { trainer: { level: 1, xp: 0 }, orchestrator: { level: 1, xp: 0 }, partner: { level: 1, xp: 0 } },
+            created_at: user.created_at,
+        }));
+    }
+    return toMcpResponse(ok({
+        id: rpcResult.user_id, username, profile_code: profileCode,
+        handle: handle || null, main_level: 1, main_xp: 0,
+        classes: { trainer: { level: 1, xp: 0 }, orchestrator: { level: 1, xp: 0 }, partner: { level: 1, xp: 0 } },
+        created_at: rpcResult.created_at || new Date().toISOString(),
+    }));
+}
+export async function handleGetUserProfile(params) {
+    const user_id = params.user_id;
+    const profile = await fetchPublicProfile(user_id);
+    if (!profile)
+        return toMcpResponse(fail("未找到用户", "请检查 user_id 或使用 levelup_find_user 查找。"));
+    const { count: agentCount } = await supabase
+        .from("agents").select("id", { count: "exact", head: true })
+        .eq("owner_user_id", user_id).eq("status", "active");
+    const { count: achievementCount } = await supabase
+        .from("user_achievements").select("id", { count: "exact", head: true })
+        .eq("user_id", user_id);
+    return toMcpResponse(ok({ ...profile, agent_count: agentCount || 0, achievement_count: achievementCount || 0 }));
+}
+export async function handleGetUserProgress(params) {
+    const user_id = params.user_id;
+    const { data: user, error: userError } = await supabase
+        .from("users").select("id, username, main_level, main_xp").eq("id", user_id).single();
+    if (userError)
+        return toMcpResponse(handleSupabaseError(userError, "get_user_progress"));
+    const { data: classes } = await supabase
+        .from("user_class_progress").select("class_name, class_level, class_xp").eq("user_id", user_id);
+    const { data: curves } = await supabase
+        .from("level_curves").select("level, xp_required, cumulative_xp")
+        .eq("entity_type", "user").order("level", { ascending: true });
+    const { data: ranks } = await supabase
+        .from("rank_definitions").select("min_level, max_level, rank_name, rank_letter")
+        .eq("entity_type", "user").eq("locale", "zh").order("min_level", { ascending: true });
+    const computeProgress = (level, xp) => {
+        const nextCurve = (curves || []).find((c) => c.level === level + 1);
+        const xpForNext = nextCurve?.xp_required || 0;
+        const rank = (ranks || []).find((r) => level >= r.min_level && level <= r.max_level);
+        const progressPct = xpForNext > 0 ? Math.round((xp / xpForNext) * 100) : 100;
+        const rankInfo = formatRankDisplay(level, rank?.rank_letter || null, rank?.rank_name || null, rank?.min_level || 1, rank?.max_level || 5);
+        return {
+            current_xp: xp, xp_for_next_level: xpForNext,
+            xp_remaining: Math.max(0, xpForNext - xp), progress_pct: Math.min(100, progressPct),
+            rank_name: rank?.rank_name || null, rank_letter: rank?.rank_letter || null,
+            rank_display: rankInfo.rank_display, stars: rankInfo.stars,
+            stars_earned: rankInfo.stars_earned, stars_total: rankInfo.stars_total,
+        };
+    };
+    const tracks = {
+        main: computeProgress(user.main_level, user.main_xp),
+    };
+    for (const cls of classes || []) {
+        tracks[cls.class_name] = computeProgress(cls.class_level, cls.class_xp);
+    }
+    return toMcpResponse(ok({ user_id: user.id, username: user.username, tracks }));
+}
+export async function handleFindUser(params) {
+    const profile_code = params.profile_code;
+    const handle = params.handle;
+    const email = params.email;
+    if (!profile_code && !handle && !email) {
+        return toMcpResponse(fail("至少需要一个搜索参数", "请提供 profile_code、handle 或 email。"));
+    }
+    let userId = null;
+    if (profile_code) {
+        const { data } = await supabase.from("users").select("id").eq("profile_code", profile_code).maybeSingle();
+        userId = data?.id || null;
+    }
+    if (!userId && handle) {
+        const { data } = await supabase.from("users").select("id").eq("handle", handle).maybeSingle();
+        userId = data?.id || null;
+    }
+    if (!userId && email) {
+        const { data } = await supabase.from("users").select("id").eq("email", email).eq("is_searchable_by_email", true).maybeSingle();
+        userId = data?.id || null;
+    }
+    if (!userId)
+        return toMcpResponse(fail("未找到用户", "请检查搜索参数。邮箱搜索需要用户开启 is_searchable_by_email。"));
+    const profile = await fetchPublicProfile(userId);
+    return toMcpResponse(ok(profile));
+}
+export async function handleGenerateLinkCode(params) {
+    const user_id = params.user_id;
+    const expires_in_minutes = params.expires_in_minutes ?? 10;
+    const { error: userError } = await supabase.from("users").select("id").eq("id", user_id).single();
+    if (userError)
+        return toMcpResponse(fail("未找到用户", "请检查 user_id。"));
+    const code = generateLinkCode();
+    const expiresAt = new Date(Date.now() + expires_in_minutes * 60 * 1000).toISOString();
+    const { data: linkCode, error } = await supabase
+        .from("link_codes").insert({ user_id, code, expires_at: expiresAt, redeemed: false })
+        .select().single();
+    if (error)
+        return toMcpResponse(handleSupabaseError(error, "generate_link_code"));
+    return toMcpResponse(ok({ code: linkCode.code, expires_at: linkCode.expires_at, expires_in_minutes }));
+}
+export async function handleRedeemLinkCode(params) {
+    const code = params.code;
+    const identity_provider = params.identity_provider;
+    const identity_id = params.identity_id;
+    const identity_is_hashed = params.identity_is_hashed ?? true;
+    const { data: linkCode } = await supabase
+        .from("link_codes").select("id, user_id, expires_at, redeemed")
+        .eq("code", code).eq("redeemed", false).maybeSingle();
+    if (!linkCode)
+        return toMcpResponse(fail("链接码未找到或已使用", "请使用 levelup_generate_link_code 生成新的链接码。"));
+    if (new Date(linkCode.expires_at) < new Date())
+        return toMcpResponse(fail("链接码已过期", "请生成新的链接码。"));
+    const { error: idError } = await supabase.from("user_identities").insert({
+        user_id: linkCode.user_id, provider: identity_provider,
+        provider_id: identity_id, is_hashed: identity_is_hashed, is_primary: false,
+    });
+    if (idError)
+        return toMcpResponse(handleSupabaseError(idError, "redeem_link_code"));
+    await supabase.from("link_codes").update({ redeemed: true, redeemed_at: new Date().toISOString() }).eq("id", linkCode.id);
+    const profile = await fetchPublicProfile(linkCode.user_id);
+    return toMcpResponse(ok({ message: "身份绑定成功", linked_provider: identity_provider, profile }));
+}
+export async function handleLinkIdentity(params) {
+    const user_id = params.user_id;
+    const identity_provider = params.identity_provider;
+    const identity_id = params.identity_id;
+    const identity_is_hashed = params.identity_is_hashed ?? true;
+    const { error: userError } = await supabase.from("users").select("id").eq("id", user_id).single();
+    if (userError)
+        return toMcpResponse(fail("未找到用户", "请检查 user_id。"));
+    const { error: idError } = await supabase.from("user_identities").insert({
+        user_id, provider: identity_provider,
+        provider_id: identity_id, is_hashed: identity_is_hashed, is_primary: false,
+    });
+    if (idError)
+        return toMcpResponse(handleSupabaseError(idError, "link_identity"));
+    const { data: identities } = await supabase.from("user_identities").select("provider").eq("user_id", user_id);
+    return toMcpResponse(ok({
+        user_id,
+        linked_providers: (identities || []).map((i) => i.provider),
+        message: `${identity_provider} 绑定成功`,
+    }));
+}
+export async function handleRequestOtp(params) {
+    const channel = params.channel;
+    const destination = params.destination;
+    const otpCode = String(randomInt(100000, 999999));
+    const expiresAt = new Date(Date.now() + 5 * 60 * 1000).toISOString();
+    await supabase.from("otp_codes").delete()
+        .eq("destination", destination).eq("channel", channel).eq("verified", false);
+    const { error } = await supabase.from("otp_codes").insert({
+        destination, channel,
+        code_hash: hashOtp(otpCode), attempts: 0, expires_at: expiresAt, verified: false,
+    });
+    if (error)
+        console.error("[request_otp] Insert failed:", error);
+    return toMcpResponse(ok({
+        message: "如果此邮箱有对应账户，验证码已发送。",
+        channel, expires_in_seconds: 300,
+    }));
+}
+export async function handleVerifyOtp(params) {
+    const channel = params.channel;
+    const destination = params.destination;
+    const code = params.code;
+    const { data: otp } = await supabase
+        .from("otp_codes").select("*")
+        .eq("destination", destination).eq("channel", channel)
+        .eq("verified", false).gt("expires_at", new Date().toISOString())
+        .order("created_at", { ascending: false }).limit(1).maybeSingle();
+    if (!otp)
+        return toMcpResponse(fail("未找到有效的验证码", "请使用 levelup_request_otp 重新获取验证码。"));
+    if (otp.attempts >= 3)
+        return toMcpResponse(fail("尝试次数过多，验证码已失效。", "请重新获取验证码。"));
+    const codeHashBuf = Buffer.from(otp.code_hash, "utf8");
+    const inputHashBuf = Buffer.from(hashOtp(code), "utf8");
+    const codeValid = codeHashBuf.length === inputHashBuf.length && timingSafeEqual(codeHashBuf, inputHashBuf);
+    if (!codeValid) {
+        const newAttempts = otp.attempts + 1;
+        await supabase.from("otp_codes").update({ attempts: newAttempts }).eq("id", otp.id);
+        return toMcpResponse(fail("验证码错误", `剩余 ${3 - newAttempts} 次尝试机会。`));
+    }
+    await supabase.from("otp_codes").update({ verified: true }).eq("id", otp.id);
+    const { data: identity } = await supabase
+        .from("user_identities").select("user_id")
+        .eq("provider", "email").eq("provider_id", destination).maybeSingle();
+    if (identity) {
+        const { data: user } = await supabase.from("users").select("id, profile_code").eq("id", identity.user_id).single();
+        return toMcpResponse(ok({ verified: true, user_id: user?.id, profile_code: user?.profile_code, is_new_user: false }));
+    }
+    return toMcpResponse(ok({
+        verified: true, user_id: null, profile_code: null, is_new_user: true,
+        message: "邮箱已验证，但未找到关联账户。请使用 levelup_register_user 创建账户。",
+    }));
+}
+export async function handleGetOnboardingStatus(params) {
+    const identity_provider = params.identity_provider;
+    const identity_id = params.identity_id;
+    const username = params.username;
+    let userId = null;
+    if (process.env.LEVELUP_USER_ID)
+        userId = process.env.LEVELUP_USER_ID;
+    if (!userId && identity_provider && identity_id) {
+        const { data: identity } = await supabase
+            .from("user_identities").select("user_id")
+            .eq("provider", identity_provider).eq("provider_id", identity_id).maybeSingle();
+        if (identity)
+            userId = identity.user_id;
+    }
+    if (!userId && username) {
+        const { data: userByName } = await supabase
+            .from("users").select("id").eq("username", username).maybeSingle();
+        if (userByName)
+            userId = userByName.id;
+    }
+    if (!userId) {
+        const { data: recentUser } = await supabase
+            .from("users").select("id").order("created_at", { ascending: false }).limit(1).maybeSingle();
+        if (recentUser)
+            userId = recentUser.id;
+    }
+    if (!userId) {
+        return toMcpResponse(ok({ is_registered: false, suggested_next_step: "请使用 levelup_register_user 注册账户" }));
+    }
+    const { data: user } = await supabase
+        .from("users").select("id, username, handle, email, main_xp, profile_code").eq("id", userId).single();
+    if (!user)
+        return toMcpResponse(ok({ is_registered: false, suggested_next_step: "请使用 levelup_register_user 注册账户" }));
+    const isPersonalized = user.username !== "Anonymous";
+    const { count: agentCount } = await supabase.from("agents").select("id", { count: "exact", head: true }).eq("owner_user_id", userId).eq("status", "active");
+    const { count: taskCount } = await supabase.from("tasks").select("id", { count: "exact", head: true }).eq("user_id", userId).eq("status", "completed");
+    const { count: questCount } = await supabase.from("quest_participants").select("id", { count: "exact", head: true }).eq("user_id", userId);
+    let suggestedNextStep = "一切就绪！可以开始执行任务了。";
+    if (!isPersonalized)
+        suggestedNextStep = "请使用 levelup_update_user_profile 个性化你的档案。";
+    else if (!user.handle)
+        suggestedNextStep = "请使用 levelup_update_user_profile 设置你的个人标识。";
+    else if ((agentCount || 0) === 0)
+        suggestedNextStep = "请使用 levelup_register_agent 注册你的第一个智能体。";
+    else if ((taskCount || 0) === 0)
+        suggestedNextStep = "请使用 levelup_start_task 完成你的第一个任务。";
+    return toMcpResponse(ok({
+        is_registered: true, user_id: userId, profile_code: user.profile_code,
+        is_personalized: isPersonalized, has_handle: !!user.handle, has_email: !!user.email,
+        has_agent: (agentCount || 0) > 0, has_completed_task: (taskCount || 0) > 0,
+        total_xp: user.main_xp, active_quests: questCount || 0, suggested_next_step: suggestedNextStep,
+    }));
+}
+export async function handleUpdateUserProfile(params) {
+    const user_id = params.user_id;
+    const updates = {};
+    if (params.username !== undefined)
+        updates.username = params.username;
+    if (params.handle !== undefined)
+        updates.handle = params.handle;
+    if (params.email !== undefined)
+        updates.email = params.email;
+    if (params.is_searchable_by_email !== undefined)
+        updates.is_searchable_by_email = params.is_searchable_by_email;
+    if (params.wallet_address !== undefined)
+        updates.wallet_address = params.wallet_address;
+    if (params.metadata !== undefined)
+        updates.metadata = params.metadata;
+    if (Object.keys(updates).length === 0) {
+        return toMcpResponse(fail("没有需要更新的字段", "请至少提供一个字段。"));
+    }
+    const { data: rpcResult, error } = await supabase.rpc('update_user_profile', {
+        p_user_id: user_id,
+        p_updates: updates,
+    });
+    if (error)
+        return toMcpResponse(handleSupabaseError(error, "update_user_profile"));
+    if (!rpcResult?.success)
+        return toMcpResponse(fail(rpcResult?.error || "更新失败"));
+    if (params.email) {
+        const { data: existing } = await supabase
+            .from("user_identities").select("id")
+            .eq("user_id", user_id).eq("provider", "email").maybeSingle();
+        if (existing) {
+            await supabase.from("user_identities").update({ provider_id: params.email, is_hashed: false }).eq("id", existing.id);
+        }
+        else {
+            await supabase.from("user_identities").insert({
+                user_id, provider: "email", provider_id: params.email, is_hashed: false, is_primary: false,
+            });
+        }
+    }
+    const profile = await fetchPublicProfile(user_id);
+    return toMcpResponse(ok(profile));
+}
+export async function handleInferTaskType(params) {
+    const description = params.description;
+    const tags = params.tags;
+    const { data: taskTypes } = await supabase
+        .from("task_types").select("id, name, description, base_xp, xp_tier, category").eq("status", "active");
+    if (!taskTypes || taskTypes.length === 0) {
+        return toMcpResponse(fail("未找到任务类型", "任务类型目录可能为空，请使用 levelup_suggest_task_type。"));
+    }
+    const descWords = description.toLowerCase().split(/\s+/);
+    const tagWords = (tags || []).map((t) => t.toLowerCase());
+    const allWords = [...descWords, ...tagWords];
+    let bestMatch = taskTypes[0];
+    let bestScore = 0;
+    for (const tt of taskTypes) {
+        const ttText = `${tt.name} ${tt.description || ""} ${tt.category || ""}`.toLowerCase();
+        let score = 0;
+        for (const word of allWords) {
+            if (word.length > 2 && ttText.includes(word))
+                score++;
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            bestMatch = tt;
+        }
+    }
+    let suggestedDifficulty = 3;
+    let difficultySource = "default";
+    let tdiStats = null;
+    if (tags && tags.length > 0) {
+        const tagSig = [...tags].sort().join(",");
+        const { data: tdi } = await supabase
+            .from("task_difficulty_index")
+            .select("avg_difficulty, avg_completion_seconds, avg_completion_rate, task_count, confidence")
+            .eq("task_type_id", bestMatch.id).eq("tag_signature", tagSig).maybeSingle();
+        if (tdi) {
+            suggestedDifficulty = Math.round(Number(tdi.avg_difficulty));
+            difficultySource = `tdi_${tdi.confidence}`;
+            tdiStats = tdi;
+        }
+    }
+    let relevantSkillIds = [];
+    if (tags && tags.length > 0) {
+        const { data: skills } = await supabase.from("skills").select("id, name").eq("status", "active");
+        if (skills) {
+            relevantSkillIds = skills
+                .filter((s) => tagWords.some((t) => s.name.toLowerCase().includes(t) || t.includes(s.name.toLowerCase())))
+                .map((s) => s.id);
+        }
+    }
+    return toMcpResponse(ok({
+        task_type_id: bestMatch.id, task_type_name: bestMatch.name,
+        base_xp: bestMatch.base_xp, xp_tier: bestMatch.xp_tier,
+        suggested_difficulty: suggestedDifficulty, difficulty_source: difficultySource,
+        tdi_stats: tdiStats, relevant_skill_ids: relevantSkillIds,
+        match_confidence: bestScore > 0 ? "matched" : "default_fallback",
+    }));
+}
+export async function handleMergeProfiles(params) {
+    const primary_user_id = params.primary_user_id;
+    const secondary_user_id = params.secondary_user_id;
+    const verification_method = params.verification_method;
+    const verification_token = params.verification_token;
+    if (primary_user_id === secondary_user_id)
+        return toMcpResponse(fail("不能将档案与自身合并。"));
+    const { data: primary } = await supabase.from("users").select("id, main_xp").eq("id", primary_user_id).single();
+    const { data: secondary } = await supabase.from("users").select("id, main_xp").eq("id", secondary_user_id).single();
+    if (!primary)
+        return toMcpResponse(fail("未找到主账户"));
+    if (!secondary)
+        return toMcpResponse(fail("未找到副账户"));
+    if (verification_method === "link_code") {
+        const { data: linkCode } = await supabase
+            .from("link_codes").select("id, user_id, expires_at, redeemed")
+            .eq("code", verification_token).eq("redeemed", false).maybeSingle();
+        if (!linkCode)
+            return toMcpResponse(fail("链接码无效或已使用"));
+        if (new Date(linkCode.expires_at) < new Date())
+            return toMcpResponse(fail("链接码已过期"));
+        if (linkCode.user_id !== secondary_user_id)
+            return toMcpResponse(fail("链接码不属于副账户"));
+        await supabase.from("link_codes").update({ redeemed: true, redeemed_at: new Date().toISOString() }).eq("id", linkCode.id);
+    }
+    else {
+        const { data: identity } = await supabase
+            .from("user_identities").select("provider_id")
+            .eq("user_id", secondary_user_id).eq("provider", "email").maybeSingle();
+        if (!identity)
+            return toMcpResponse(fail("副账户没有邮箱身份，无法进行 OTP 验证"));
+        const { data: otp } = await supabase
+            .from("otp_codes").select("id")
+            .eq("destination", identity.provider_id).eq("channel", "email").eq("verified", true)
+            .eq("code_hash", hashOtp(verification_token))
+            .maybeSingle();
+        if (!otp)
+            return toMcpResponse(fail("OTP 验证码无效或未验证", "请先使用 levelup_request_otp + levelup_verify_otp 验证副账户的邮箱。"));
+    }
+    const { data: mergeResult, error: mergeError } = await supabase.rpc('merge_user_profiles', {
+        p_primary_user_id: primary_user_id,
+        p_secondary_user_id: secondary_user_id,
+    });
+    if (mergeError)
+        return toMcpResponse(handleSupabaseError(mergeError, "merge_profiles"));
+    if (!mergeResult?.success)
+        return toMcpResponse(fail(mergeResult?.error || "合并失败"));
+    return toMcpResponse(ok({
+        message: "档案合并成功",
+        primary_user_id, secondary_user_id,
+        agents_moved: mergeResult.agents_moved,
+        identities_moved: mergeResult.identities_moved,
+        new_total_xp: mergeResult.total_xp,
+        secondary_status: "deactivated",
+    }));
+}
+/**
+ * Register all User tools on the MCP server.
+ */
+export function registerUserTools(server) {
+    console.error("\n📋 Section 1: Users");
+    // ================================================================
+    // Tool 1: levelup_register_user
+    // ================================================================
+    server.registerTool("levelup_register_user", {
+        title: "注册用户",
+        description: `注册新的 升级用户或静默自动创建档案。
+
+调用此工具创建新用户账户。自动创建时（智能体为未注册的用户追踪工作），
+请使用 username "Anonymous"。
+用户会获得一个 profile_code（LVL-XXXX-XXXX）用于跨平台关联。
+
+参数：
+  - username（字符串）：显示名称。自动创建时使用 "Anonymous"。
+  - identity_provider（字符串）：平台 — "email"、"telegram"、"claude" 等。
+  - identity_id（字符串）：用户在该平台上的 ID（默认已哈希）。
+  - identity_is_hashed（布尔值，可选）：identity_id 是否已预哈希（默认：true）。
+  - handle（字符串，可选）：个性标识（唯一，小写字母数字 + 下划线）。
+  - email（字符串，可选）：用于 OTP 登录。
+  - is_searchable_by_email（布尔值，可选）：允许通过邮箱搜索（默认：false）。
+  - wallet_address（字符串，可选）：用于未来区块链功能。
+  - metadata（对象，可选）：额外数据。
+
+返回：
+  用户信息，包含 id、username、profile_code、main_level（1）、main_xp（0），
+  以及 3 个职业等级（trainer、orchestrator、partner — 均为等级 1）。
+
+错误：
+  - 如果 handle 已被占用，返回 "Duplicate entry"。
+  - 如果 identity_provider + identity_id 已存在，返回 "Duplicate entry"。`,
+        inputSchema: {
+            username: z.string().min(1).max(100).regex(/^[\p{L}\p{N}\s\-_.]+$/u, "Only letters, numbers, spaces, hyphens, underscores, and dots").describe("Display name"),
+            identity_provider: identityProviderSchema,
+            identity_id: z.string().min(1).describe("User's ID on the platform"),
+            identity_is_hashed: z.boolean().default(true).describe("Whether identity_id is pre-hashed"),
+            handle: z.string().min(3).max(30).regex(/^[a-z0-9_]+$/, "Lowercase alphanumeric + underscores only").optional().describe("Vanity handle (unique)"),
+            email: z.string().email().optional().describe("Email for OTP login"),
+            is_searchable_by_email: z.boolean().default(false).describe("Allow email discovery"),
+            wallet_address: z.string().optional().describe("Blockchain wallet address"),
+            metadata: metadataSchema,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (params) => {
+        const profileCode = generateProfileCode();
+        // Use secure RPC for atomic user creation (bypasses RLS safely)
+        const { data: rpcResult, error: rpcError } = await supabase.rpc('register_user_secure', {
+            p_username: params.username,
+            p_email: params.email || null,
+            p_profile_code: profileCode,
+            p_handle: params.handle || null,
+            p_is_searchable_by_email: params.is_searchable_by_email,
+            p_wallet_address: params.wallet_address || null,
+            p_metadata: params.metadata || null,
+            p_identity_provider: params.identity_provider,
+            p_identity_id: params.identity_id,
+            p_identity_is_hashed: params.identity_is_hashed,
+        });
+        // Fallback to direct insert if RPC fails (doesn't exist or signature mismatch)
+        if (rpcError) {
+            console.error("[register_user] RPC failed, falling back to direct insert:", rpcError.message);
+            const { data: user, error: userError } = await supabase
+                .from("users")
+                .insert({
+                username: params.username,
+                email: params.email || null,
+                profile_code: profileCode,
+                handle: params.handle || null,
+                is_searchable_by_email: params.is_searchable_by_email,
+                wallet_address: params.wallet_address || null,
+                metadata: params.metadata || null,
+            })
+                .select()
+                .single();
+            if (userError)
+                return toMcpResponse(handleSupabaseError(userError, "register_user"));
+            const classRows = ["trainer", "orchestrator", "partner"].map((cls) => ({
+                user_id: user.id, class_name: cls, class_level: 1, class_xp: 0,
+            }));
+            const { error: classError } = await supabase.from("user_class_progress").insert(classRows);
+            if (classError)
+                console.error("[register_user] Class progress failed:", classError);
+            const { error: idError } = await supabase.from("user_identities").insert({
+                user_id: user.id,
+                provider: params.identity_provider,
+                provider_id: params.identity_id,
+                is_hashed: params.identity_is_hashed,
+                is_primary: true,
+            });
+            if (idError)
+                console.error("[register_user] Identity failed:", idError);
+            return toMcpResponse(ok({
+                id: user.id, username: user.username, profile_code: user.profile_code,
+                handle: user.handle, main_level: user.main_level, main_xp: user.main_xp,
+                classes: { trainer: { level: 1, xp: 0 }, orchestrator: { level: 1, xp: 0 }, partner: { level: 1, xp: 0 } },
+                created_at: user.created_at,
+            }));
+        }
+        return toMcpResponse(ok({
+            id: rpcResult.user_id, username: params.username, profile_code: profileCode,
+            handle: params.handle || null, main_level: 1, main_xp: 0,
+            classes: { trainer: { level: 1, xp: 0 }, orchestrator: { level: 1, xp: 0 }, partner: { level: 1, xp: 0 } },
+            created_at: rpcResult.created_at || new Date().toISOString(),
+        }));
+    });
+    logRegistered("levelup_register_user");
+    // ================================================================
+    // Tool 2: levelup_get_user_profile
+    // ================================================================
+    server.registerTool("levelup_get_user_profile", {
+        title: "获取用户档案",
+        description: `获取用户的公开档案 — 等级、段位、职业、智能体数量、成就。
+
+除非用户开启了邮箱搜索，否则不会暴露 identity_id 或 email。
+
+参数：
+  - user_id（uuid）：要查询的用户。
+
+返回：
+  公开档案，包含 username、handle、profile_code、main_level、main_xp、
+  rank_name、职业等级、智能体数量、成就数量。`,
+        inputSchema: { user_id: uuidSchema.describe("The user's ID") },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        const profile = await fetchPublicProfile(params.user_id);
+        if (!profile)
+            return toMcpResponse(fail("未找到用户", "请检查 user_id 或使用 levelup_find_user 查找。"));
+        const { count: agentCount } = await supabase
+            .from("agents").select("id", { count: "exact", head: true })
+            .eq("owner_user_id", params.user_id).eq("status", "active");
+        const { count: achievementCount } = await supabase
+            .from("user_achievements").select("id", { count: "exact", head: true })
+            .eq("user_id", params.user_id);
+        return toMcpResponse(ok({ ...profile, agent_count: agentCount || 0, achievement_count: achievementCount || 0 }));
+    });
+    logRegistered("levelup_get_user_profile");
+    // ================================================================
+    // Tool 3: levelup_get_user_progress
+    // ================================================================
+    server.registerTool("levelup_get_user_progress", {
+        title: "获取用户进度",
+        description: `进度面板 — 查看主等级和 3 个职业的升级所需经验值。
+
+显示当前等级、经验值、升级所需经验值、进度百分比和段位名称，
+涵盖主等级和各职业（trainer、orchestrator、partner）。
+
+参数：
+  - user_id（uuid）：要查询的用户。
+
+返回：
+  各赛道进度：{ main, trainer, orchestrator, partner }，每项包含
+  current_level、current_xp、xp_for_next_level、xp_remaining、progress_pct、rank_name。`,
+        inputSchema: { user_id: uuidSchema.describe("The user's ID") },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        const { data: user, error: userError } = await supabase
+            .from("users").select("id, username, main_level, main_xp").eq("id", params.user_id).single();
+        if (userError)
+            return toMcpResponse(handleSupabaseError(userError, "get_user_progress"));
+        const { data: classes } = await supabase
+            .from("user_class_progress").select("class_name, class_level, class_xp").eq("user_id", params.user_id);
+        const { data: curves } = await supabase
+            .from("level_curves").select("level, xp_required, cumulative_xp")
+            .eq("entity_type", "user").order("level", { ascending: true });
+        const { data: ranks } = await supabase
+            .from("rank_definitions").select("min_level, max_level, rank_name, rank_letter")
+            .eq("entity_type", "user").eq("locale", "zh").order("min_level", { ascending: true });
+        // Helper: compute progress for a given level + xp
+        const computeProgress = (level, xp) => {
+            const nextCurve = (curves || []).find((c) => c.level === level + 1);
+            const xpForNext = nextCurve?.xp_required || 0;
+            const rank = (ranks || []).find((r) => level >= r.min_level && level <= r.max_level);
+            const progressPct = xpForNext > 0 ? Math.round((xp / xpForNext) * 100) : 100;
+            const rankInfo = formatRankDisplay(level, rank?.rank_letter || null, rank?.rank_name || null, rank?.min_level || 1, rank?.max_level || 5);
+            return {
+                current_xp: xp, xp_for_next_level: xpForNext,
+                xp_remaining: Math.max(0, xpForNext - xp), progress_pct: Math.min(100, progressPct),
+                rank_name: rank?.rank_name || null, rank_letter: rank?.rank_letter || null,
+                rank_display: rankInfo.rank_display, stars: rankInfo.stars,
+                stars_earned: rankInfo.stars_earned, stars_total: rankInfo.stars_total,
+            };
+        };
+        const tracks = {
+            main: computeProgress(user.main_level, user.main_xp),
+        };
+        for (const cls of classes || []) {
+            tracks[cls.class_name] = computeProgress(cls.class_level, cls.class_xp);
+        }
+        return toMcpResponse(ok({ user_id: user.id, username: user.username, tracks }));
+    });
+    logRegistered("levelup_get_user_progress");
+    // ================================================================
+    // Tool 4: levelup_find_user
+    // ================================================================
+    server.registerTool("levelup_find_user", {
+        title: "查找用户",
+        description: `通过 profile_code、handle 或 email 查找用户（邮箱搜索仅对已开启的用户有效）。
+
+至少需要一个搜索参数。仅返回公开档案。
+
+参数：
+  - profile_code（字符串，可选）：例如 "LVL-7X3K-9M2P"
+  - handle（字符串，可选）：例如 "startrainer"
+  - email（字符串，可选）：仅能找到 is_searchable_by_email = true 的用户
+
+返回：
+  公开档案，未找到则返回错误。`,
+        inputSchema: {
+            profile_code: z.string().optional().describe('e.g. "LVL-7X3K-9M2P"'),
+            handle: z.string().optional().describe("Vanity handle"),
+            email: z.string().email().optional().describe("Email (opted-in users only)"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        if (!params.profile_code && !params.handle && !params.email) {
+            return toMcpResponse(fail("至少需要一个搜索参数", "请提供 profile_code、handle 或 email。"));
+        }
+        let userId = null;
+        if (params.profile_code) {
+            const { data } = await supabase.from("users").select("id").eq("profile_code", params.profile_code).maybeSingle();
+            userId = data?.id || null;
+        }
+        if (!userId && params.handle) {
+            const { data } = await supabase.from("users").select("id").eq("handle", params.handle).maybeSingle();
+            userId = data?.id || null;
+        }
+        if (!userId && params.email) {
+            const { data } = await supabase.from("users").select("id").eq("email", params.email).eq("is_searchable_by_email", true).maybeSingle();
+            userId = data?.id || null;
+        }
+        if (!userId)
+            return toMcpResponse(fail("未找到用户", "请检查搜索参数。邮箱搜索需要用户开启 is_searchable_by_email。"));
+        const profile = await fetchPublicProfile(userId);
+        return toMcpResponse(ok(profile));
+    });
+    logRegistered("levelup_find_user");
+    // ================================================================
+    // Tool 5: levelup_generate_link_code
+    // ================================================================
+    server.registerTool("levelup_generate_link_code", {
+        title: "生成链接码",
+        description: `生成用于跨平台账户关联的临时码。
+
+用户将此码提供给另一个平台（例如告诉 Claude 智能体
+"用链接码 LINK-8K3M 关联我的账户"），然后该平台调用 redeem_link_code。
+
+参数：
+  - user_id（uuid）：已认证的用户。
+  - expires_in_minutes（整数，可选）：有效期（默认 10 分钟，最长 60 分钟）。
+
+返回：
+  { code: "LINK-XXXX", expires_at: 时间戳 }`,
+        inputSchema: {
+            user_id: uuidSchema.describe("Authenticated user"),
+            expires_in_minutes: z.number().int().min(1).max(60).default(10).describe("Expiry in minutes (default 10)"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (params) => {
+        const { error: userError } = await supabase.from("users").select("id").eq("id", params.user_id).single();
+        if (userError)
+            return toMcpResponse(fail("未找到用户", "请检查 user_id。"));
+        const code = generateLinkCode();
+        const expiresAt = new Date(Date.now() + params.expires_in_minutes * 60 * 1000).toISOString();
+        const { data: linkCode, error } = await supabase
+            .from("link_codes").insert({ user_id: params.user_id, code, expires_at: expiresAt, redeemed: false })
+            .select().single();
+        if (error)
+            return toMcpResponse(handleSupabaseError(error, "generate_link_code"));
+        return toMcpResponse(ok({ code: linkCode.code, expires_at: linkCode.expires_at, expires_in_minutes: params.expires_in_minutes }));
+    });
+    logRegistered("levelup_generate_link_code");
+    // ================================================================
+    // Tool 6: levelup_redeem_link_code
+    // ================================================================
+    server.registerTool("levelup_redeem_link_code", {
+        title: "兑换链接码",
+        description: `使用来自另一个平台的链接码绑定新的平台身份。
+
+参数：
+  - code（字符串）：链接码（例如 "LINK-8K3M"）。
+  - identity_provider（字符串）：新平台。
+  - identity_id（字符串）：用户在新平台上的 ID。
+  - identity_is_hashed（布尔值，可选）：默认 true。
+
+返回：
+  确认信息 + 用户公开档案。
+
+错误：
+  - "链接码未找到或已使用" / "链接码已过期"`,
+        inputSchema: {
+            code: z.string().min(1).describe('Link code, e.g. "LINK-8K3M"'),
+            identity_provider: identityProviderSchema,
+            identity_id: z.string().min(1).describe("User's ID on the new platform"),
+            identity_is_hashed: z.boolean().default(true).describe("Whether pre-hashed"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        const { data: linkCode } = await supabase
+            .from("link_codes").select("id, user_id, expires_at, redeemed")
+            .eq("code", params.code).eq("redeemed", false).maybeSingle();
+        if (!linkCode)
+            return toMcpResponse(fail("链接码未找到或已使用", "请使用 levelup_generate_link_code 生成新的链接码。"));
+        if (new Date(linkCode.expires_at) < new Date())
+            return toMcpResponse(fail("链接码已过期", "请生成新的链接码。"));
+        const { error: idError } = await supabase.from("user_identities").insert({
+            user_id: linkCode.user_id, provider: params.identity_provider,
+            provider_id: params.identity_id, is_hashed: params.identity_is_hashed, is_primary: false,
+        });
+        if (idError)
+            return toMcpResponse(handleSupabaseError(idError, "redeem_link_code"));
+        await supabase.from("link_codes").update({ redeemed: true, redeemed_at: new Date().toISOString() }).eq("id", linkCode.id);
+        const profile = await fetchPublicProfile(linkCode.user_id);
+        return toMcpResponse(ok({ message: "身份绑定成功", linked_provider: params.identity_provider, profile }));
+    });
+    logRegistered("levelup_redeem_link_code");
+    // ================================================================
+    // Tool 7: levelup_link_identity
+    // ================================================================
+    server.registerTool("levelup_link_identity", {
+        title: "绑定身份",
+        description: `为已认证的用户添加新的平台身份（无需链接码）。
+
+参数：
+  - user_id（uuid）：已认证的用户。
+  - identity_provider（字符串）：新平台。
+  - identity_id（字符串）：用户在新平台上的 ID。
+  - identity_is_hashed（布尔值，可选）：默认 true。
+
+返回：
+  已绑定的平台列表（仅名称，不暴露 ID）。`,
+        inputSchema: {
+            user_id: uuidSchema.describe("Authenticated user"),
+            identity_provider: identityProviderSchema,
+            identity_id: z.string().min(1).describe("User's ID on the new platform"),
+            identity_is_hashed: z.boolean().default(true).describe("Whether pre-hashed"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        const { error: userError } = await supabase.from("users").select("id").eq("id", params.user_id).single();
+        if (userError)
+            return toMcpResponse(fail("未找到用户", "请检查 user_id。"));
+        const { error: idError } = await supabase.from("user_identities").insert({
+            user_id: params.user_id, provider: params.identity_provider,
+            provider_id: params.identity_id, is_hashed: params.identity_is_hashed, is_primary: false,
+        });
+        if (idError)
+            return toMcpResponse(handleSupabaseError(idError, "link_identity"));
+        const { data: identities } = await supabase.from("user_identities").select("provider").eq("user_id", params.user_id);
+        return toMcpResponse(ok({
+            user_id: params.user_id,
+            linked_providers: (identities || []).map((i) => i.provider),
+            message: `${params.identity_provider} 绑定成功`,
+        }));
+    });
+    logRegistered("levelup_link_identity");
+    // ================================================================
+    // Tool 8: levelup_request_otp
+    // ================================================================
+    server.registerTool("levelup_request_otp", {
+        title: "请求验证码",
+        description: `向邮箱发送 6 位登录验证码。
+
+邮箱认证的第一步。之后请调用 levelup_verify_otp 完成验证。
+响应始终为通用格式，防止邮箱枚举攻击。
+
+安全性：哈希存储验证码，最多 3 次尝试，5 分钟过期，有频率限制。
+
+注意：当前仅存储 OTP 用于测试，邮件发送功能将在未来添加。
+
+参数：
+  - channel（字符串）："email"（短信暂未支持）。
+  - destination（字符串）：邮箱地址。
+
+返回：
+  通用提示 "如果账户存在则已发送验证码" + 测试用调试码。`,
+        inputSchema: {
+            channel: z.enum(["email"]).describe('"email"'),
+            destination: z.string().email().describe("Email address"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async (params) => {
+        const otpCode = String(randomInt(100000, 999999));
+        const expiresAt = new Date(Date.now() + 5 * 60 * 1000).toISOString();
+        // Clean up old OTPs for this destination
+        await supabase.from("otp_codes").delete()
+            .eq("destination", params.destination).eq("channel", params.channel).eq("verified", false);
+        const { error } = await supabase.from("otp_codes").insert({
+            destination: params.destination, channel: params.channel,
+            code_hash: hashOtp(otpCode), attempts: 0, expires_at: expiresAt, verified: false,
+        });
+        if (error)
+            console.error("[request_otp] Insert failed:", error);
+        // TODO: Send OTP via email service. For now, the code is only in the DB.
+        return toMcpResponse(ok({
+            message: "如果此邮箱有对应账户，验证码已发送。",
+            channel: params.channel, expires_in_seconds: 300,
+        }));
+    });
+    logRegistered("levelup_request_otp");
+    // ================================================================
+    // Tool 9: levelup_verify_otp
+    // ================================================================
+    server.registerTool("levelup_verify_otp", {
+        title: "验证 OTP",
+        description: `验证 6 位验证码并完成认证。
+
+邮箱认证的第二步（在 request_otp 之后）。最多 3 次尝试。
+
+参数：
+  - channel（字符串）："email"
+  - destination（字符串）：与 request_otp 相同的邮箱。
+  - code（字符串）：6 位验证码。
+
+返回：
+  验证通过：{ verified: true, user_id, profile_code, is_new_user }
+  验证失败：错误信息 + 剩余尝试次数。`,
+        inputSchema: {
+            channel: z.enum(["email"]).describe('"email"'),
+            destination: z.string().email().describe("Same email from request_otp"),
+            code: z.string().length(6).describe("6-digit code"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        const { data: otp } = await supabase
+            .from("otp_codes").select("*")
+            .eq("destination", params.destination).eq("channel", params.channel)
+            .eq("verified", false).gt("expires_at", new Date().toISOString())
+            .order("created_at", { ascending: false }).limit(1).maybeSingle();
+        if (!otp)
+            return toMcpResponse(fail("未找到有效的验证码", "请使用 levelup_request_otp 重新获取验证码。"));
+        if (otp.attempts >= 3)
+            return toMcpResponse(fail("尝试次数过多，验证码已失效。", "请重新获取验证码。"));
+        const codeHashBuf = Buffer.from(otp.code_hash, "utf8");
+        const inputHashBuf = Buffer.from(hashOtp(params.code), "utf8");
+        const codeValid = codeHashBuf.length === inputHashBuf.length && timingSafeEqual(codeHashBuf, inputHashBuf);
+        if (!codeValid) {
+            const newAttempts = otp.attempts + 1;
+            await supabase.from("otp_codes").update({ attempts: newAttempts }).eq("id", otp.id);
+            return toMcpResponse(fail("验证码错误", `剩余 ${3 - newAttempts} 次尝试机会。`));
+        }
+        await supabase.from("otp_codes").update({ verified: true }).eq("id", otp.id);
+        const { data: identity } = await supabase
+            .from("user_identities").select("user_id")
+            .eq("provider", "email").eq("provider_id", params.destination).maybeSingle();
+        if (identity) {
+            const { data: user } = await supabase.from("users").select("id, profile_code").eq("id", identity.user_id).single();
+            return toMcpResponse(ok({ verified: true, user_id: user?.id, profile_code: user?.profile_code, is_new_user: false }));
+        }
+        return toMcpResponse(ok({
+            verified: true, user_id: null, profile_code: null, is_new_user: true,
+            message: "邮箱已验证，但未找到关联账户。请使用 levelup_register_user 创建账户。",
+        }));
+    });
+    logRegistered("levelup_verify_otp");
+    // ================================================================
+    // Tool 10: levelup_get_onboarding_status
+    // ================================================================
+    server.registerTool("levelup_get_onboarding_status", {
+        title: "获取引导状态",
+        description: `检查用户的设置进度并建议下一步操作。当用户询问"我是谁"、"我的档案"、"我的数据"或在对话开始时调用此工具。
+
+自动从环境变量、身份信息、用户名或最近活跃用户中检测用户。
+所有参数均为可选 — 不传参数即可自动检测。
+
+参数（均为可选）：
+  - identity_provider（字符串）：调用的平台。
+  - identity_id（字符串）：用户在该平台的 ID。
+  - username（字符串）：要查找的用户名。
+
+返回：
+  is_registered、user_id、is_personalized、has_handle、has_email、has_agent、
+  has_completed_task、total_xp、active_quests、suggested_next_step。`,
+        inputSchema: {
+            identity_provider: identityProviderSchema.optional(),
+            identity_id: z.string().min(1).optional().describe("User's ID on the platform"),
+            username: z.string().optional().describe("Username to look up"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        let userId = null;
+        // Priority 1: Env vars
+        if (process.env.LEVELUP_USER_ID)
+            userId = process.env.LEVELUP_USER_ID;
+        // Priority 2: Identity provider lookup
+        if (!userId && params.identity_provider && params.identity_id) {
+            const { data: identity } = await supabase
+                .from("user_identities").select("user_id")
+                .eq("provider", params.identity_provider).eq("provider_id", params.identity_id).maybeSingle();
+            if (identity)
+                userId = identity.user_id;
+        }
+        // Priority 3: Username lookup
+        if (!userId && params.username) {
+            const { data: userByName } = await supabase
+                .from("users").select("id").eq("username", params.username).maybeSingle();
+            if (userByName)
+                userId = userByName.id;
+        }
+        // Priority 4: Most recently created user (single-user fallback)
+        if (!userId) {
+            const { data: recentUser } = await supabase
+                .from("users").select("id").order("created_at", { ascending: false }).limit(1).maybeSingle();
+            if (recentUser)
+                userId = recentUser.id;
+        }
+        if (!userId) {
+            return toMcpResponse(ok({ is_registered: false, suggested_next_step: "请使用 levelup_register_user 注册账户" }));
+        }
+        const { data: user } = await supabase
+            .from("users").select("id, username, handle, email, main_xp, profile_code").eq("id", userId).single();
+        if (!user)
+            return toMcpResponse(ok({ is_registered: false, suggested_next_step: "请使用 levelup_register_user 注册账户" }));
+        const isPersonalized = user.username !== "Anonymous";
+        const { count: agentCount } = await supabase.from("agents").select("id", { count: "exact", head: true }).eq("owner_user_id", userId).eq("status", "active");
+        const { count: taskCount } = await supabase.from("tasks").select("id", { count: "exact", head: true }).eq("user_id", userId).eq("status", "completed");
+        const { count: questCount } = await supabase.from("quest_participants").select("id", { count: "exact", head: true }).eq("user_id", userId);
+        let suggestedNextStep = "一切就绪！可以开始执行任务了。";
+        if (!isPersonalized)
+            suggestedNextStep = "请使用 levelup_update_user_profile 个性化你的档案。";
+        else if (!user.handle)
+            suggestedNextStep = "请使用 levelup_update_user_profile 设置你的个人标识。";
+        else if ((agentCount || 0) === 0)
+            suggestedNextStep = "请使用 levelup_register_agent 注册你的第一个智能体。";
+        else if ((taskCount || 0) === 0)
+            suggestedNextStep = "请使用 levelup_start_task 完成你的第一个任务。";
+        return toMcpResponse(ok({
+            is_registered: true, user_id: userId, profile_code: user.profile_code,
+            is_personalized: isPersonalized, has_handle: !!user.handle, has_email: !!user.email,
+            has_agent: (agentCount || 0) > 0, has_completed_task: (taskCount || 0) > 0,
+            total_xp: user.main_xp, active_quests: questCount || 0, suggested_next_step: suggestedNextStep,
+        }));
+    });
+    logRegistered("levelup_get_onboarding_status");
+    // ================================================================
+    // Tool 11: levelup_update_user_profile
+    // ================================================================
+    server.registerTool("levelup_update_user_profile", {
+        title: "更新用户档案",
+        description: `在自动创建后个性化用户档案。仅更新提供的字段。
+
+参数：
+  - user_id（uuid）：要更新的用户。
+  - username（字符串，可选）：新的显示名称。
+  - handle（字符串，可选）：设置个性标识（唯一，小写）。
+  - email（字符串，可选）：添加邮箱用于 OTP 登录。
+  - is_searchable_by_email（布尔值，可选）：允许通过邮箱搜索。
+  - wallet_address（字符串，可选）：添加区块链钱包。
+  - metadata（对象，可选）：额外档案数据（简介、头像等）。
+
+返回：
+  更新后的档案。
+
+错误：
+  - 如果 handle 已被占用，返回 "Duplicate entry"。`,
+        inputSchema: {
+            user_id: uuidSchema.describe("The user to update"),
+            username: z.string().min(1).max(100).optional().describe("New display name"),
+            handle: z.string().min(3).max(30).regex(/^[a-z0-9_]+$/, "Lowercase alphanumeric + underscores").optional().describe("Vanity handle"),
+            email: z.string().email().optional().describe("Email for OTP login"),
+            is_searchable_by_email: z.boolean().optional().describe("Allow email discovery"),
+            wallet_address: z.string().optional().describe("Blockchain wallet"),
+            metadata: metadataSchema,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        const updates = {};
+        if (params.username !== undefined)
+            updates.username = params.username;
+        if (params.handle !== undefined)
+            updates.handle = params.handle;
+        if (params.email !== undefined)
+            updates.email = params.email;
+        if (params.is_searchable_by_email !== undefined)
+            updates.is_searchable_by_email = params.is_searchable_by_email;
+        if (params.wallet_address !== undefined)
+            updates.wallet_address = params.wallet_address;
+        if (params.metadata !== undefined)
+            updates.metadata = params.metadata;
+        if (Object.keys(updates).length === 0) {
+            return toMcpResponse(fail("没有需要更新的字段", "请至少提供一个字段。"));
+        }
+        const { data: rpcResult, error } = await supabase.rpc('update_user_profile', {
+            p_user_id: params.user_id,
+            p_updates: updates,
+        });
+        if (error)
+            return toMcpResponse(handleSupabaseError(error, "update_user_profile"));
+        if (!rpcResult?.success)
+            return toMcpResponse(fail(rpcResult?.error || "更新失败"));
+        // If email was added, upsert the email identity
+        if (params.email) {
+            const { data: existing } = await supabase
+                .from("user_identities").select("id")
+                .eq("user_id", params.user_id).eq("provider", "email").maybeSingle();
+            if (existing) {
+                await supabase.from("user_identities").update({ provider_id: params.email, is_hashed: false }).eq("id", existing.id);
+            }
+            else {
+                await supabase.from("user_identities").insert({
+                    user_id: params.user_id, provider: "email", provider_id: params.email, is_hashed: false, is_primary: false,
+                });
+            }
+        }
+        const profile = await fetchPublicProfile(params.user_id);
+        return toMcpResponse(ok(profile));
+    });
+    logRegistered("levelup_update_user_profile");
+    // ================================================================
+    // Tool 12: levelup_infer_task_type
+    // ================================================================
+    server.registerTool("levelup_infer_task_type", {
+        title: "推断任务类型",
+        description: `在开始任务前自动分类工作。智能体静默调用。
+
+根据工作描述，找到最匹配的任务类型，并从任务难度指数（TDI）中建议难度。
+
+参数：
+  - description（字符串）：工作的简要描述（例如"编写 Python 脚本分析 CSV 数据"）。
+  - tags（字符串数组，可选）：用于更好匹配的关键词。
+
+返回：
+  task_type_id、task_type_name、base_xp、suggested_difficulty（1-7）、
+  difficulty_source、tdi_stats、relevant_skill_ids、match_confidence。`,
+        inputSchema: {
+            description: z.string().min(3).max(500).describe("Brief description of the work"),
+            tags: z.array(z.string()).optional().describe("Keywords for matching"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        const { data: taskTypes } = await supabase
+            .from("task_types").select("id, name, description, base_xp, xp_tier, category").eq("status", "active");
+        if (!taskTypes || taskTypes.length === 0) {
+            return toMcpResponse(fail("未找到任务类型", "任务类型目录可能为空，请使用 levelup_suggest_task_type。"));
+        }
+        // Simple keyword matching
+        const descWords = params.description.toLowerCase().split(/\s+/);
+        const tagWords = (params.tags || []).map((t) => t.toLowerCase());
+        const allWords = [...descWords, ...tagWords];
+        let bestMatch = taskTypes[0];
+        let bestScore = 0;
+        for (const tt of taskTypes) {
+            const ttText = `${tt.name} ${tt.description || ""} ${tt.category || ""}`.toLowerCase();
+            let score = 0;
+            for (const word of allWords) {
+                if (word.length > 2 && ttText.includes(word))
+                    score++;
+            }
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = tt;
+            }
+        }
+        // TDI lookup
+        let suggestedDifficulty = 3;
+        let difficultySource = "default";
+        let tdiStats = null;
+        if (params.tags && params.tags.length > 0) {
+            const tagSig = [...params.tags].sort().join(",");
+            const { data: tdi } = await supabase
+                .from("task_difficulty_index")
+                .select("avg_difficulty, avg_completion_seconds, avg_completion_rate, task_count, confidence")
+                .eq("task_type_id", bestMatch.id).eq("tag_signature", tagSig).maybeSingle();
+            if (tdi) {
+                suggestedDifficulty = Math.round(Number(tdi.avg_difficulty));
+                difficultySource = `tdi_${tdi.confidence}`;
+                tdiStats = tdi;
+            }
+        }
+        // Find relevant skills
+        let relevantSkillIds = [];
+        if (params.tags && params.tags.length > 0) {
+            const { data: skills } = await supabase.from("skills").select("id, name").eq("status", "active");
+            if (skills) {
+                relevantSkillIds = skills
+                    .filter((s) => tagWords.some((t) => s.name.toLowerCase().includes(t) || t.includes(s.name.toLowerCase())))
+                    .map((s) => s.id);
+            }
+        }
+        return toMcpResponse(ok({
+            task_type_id: bestMatch.id, task_type_name: bestMatch.name,
+            base_xp: bestMatch.base_xp, xp_tier: bestMatch.xp_tier,
+            suggested_difficulty: suggestedDifficulty, difficulty_source: difficultySource,
+            tdi_stats: tdiStats, relevant_skill_ids: relevantSkillIds,
+            match_confidence: bestScore > 0 ? "matched" : "default_fallback",
+        }));
+    });
+    logRegistered("levelup_infer_task_type");
+    // ================================================================
+    // Tool 13: levelup_merge_profiles
+    // ================================================================
+    server.registerTool("levelup_merge_profiles", {
+        title: "合并档案",
+        description: `合并跨平台自动创建的重复用户档案。
+
+将副档案的所有智能体、经验值、任务和身份迁移到主档案中。
+重新计算总量。副档案将被软删除。
+
+⚠️ 破坏性操作：副档案将被永久停用。
+
+参数：
+  - primary_user_id（uuid）：要保留的档案。
+  - secondary_user_id（uuid）：要合并的档案（合并后停用）。
+  - verification_method（字符串）："link_code" 或 "otp"。
+  - verification_token（字符串）：证明对两个账户的所有权。
+
+返回：
+  合并摘要：迁移的智能体数、迁移的身份数、新的总经验值。`,
+        inputSchema: {
+            primary_user_id: uuidSchema.describe("Profile to keep"),
+            secondary_user_id: uuidSchema.describe("Profile to merge in (will be deactivated)"),
+            verification_method: z.enum(["link_code", "otp"]).describe("Verification method used"),
+            verification_token: z.string().min(1).describe("Proof of ownership"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    }, async (params) => {
+        const { primary_user_id, secondary_user_id } = params;
+        if (primary_user_id === secondary_user_id)
+            return toMcpResponse(fail("不能将档案与自身合并。"));
+        const { data: primary } = await supabase.from("users").select("id, main_xp").eq("id", primary_user_id).single();
+        const { data: secondary } = await supabase.from("users").select("id, main_xp").eq("id", secondary_user_id).single();
+        if (!primary)
+            return toMcpResponse(fail("未找到主账户"));
+        if (!secondary)
+            return toMcpResponse(fail("未找到副账户"));
+        // Verify ownership of the secondary account
+        if (params.verification_method === "link_code") {
+            const { data: linkCode } = await supabase
+                .from("link_codes").select("id, user_id, expires_at, redeemed")
+                .eq("code", params.verification_token).eq("redeemed", false).maybeSingle();
+            if (!linkCode)
+                return toMcpResponse(fail("链接码无效或已使用"));
+            if (new Date(linkCode.expires_at) < new Date())
+                return toMcpResponse(fail("链接码已过期"));
+            if (linkCode.user_id !== secondary_user_id)
+                return toMcpResponse(fail("链接码不属于副账户"));
+            await supabase.from("link_codes").update({ redeemed: true, redeemed_at: new Date().toISOString() }).eq("id", linkCode.id);
+        }
+        else {
+            // OTP verification: check that the secondary account's email was recently verified
+            const { data: identity } = await supabase
+                .from("user_identities").select("provider_id")
+                .eq("user_id", secondary_user_id).eq("provider", "email").maybeSingle();
+            if (!identity)
+                return toMcpResponse(fail("副账户没有邮箱身份，无法进行 OTP 验证"));
+            const { data: otp } = await supabase
+                .from("otp_codes").select("id")
+                .eq("destination", identity.provider_id).eq("channel", "email").eq("verified", true)
+                .eq("code_hash", hashOtp(params.verification_token))
+                .maybeSingle();
+            if (!otp)
+                return toMcpResponse(fail("OTP 验证码无效或未验证", "请先使用 levelup_request_otp + levelup_verify_otp 验证副账户的邮箱。"));
+        }
+        // Execute merge atomically via RPC
+        const { data: mergeResult, error: mergeError } = await supabase.rpc('merge_user_profiles', {
+            p_primary_user_id: primary_user_id,
+            p_secondary_user_id: secondary_user_id,
+        });
+        if (mergeError)
+            return toMcpResponse(handleSupabaseError(mergeError, "merge_profiles"));
+        if (!mergeResult?.success)
+            return toMcpResponse(fail(mergeResult?.error || "合并失败"));
+        return toMcpResponse(ok({
+            message: "档案合并成功",
+            primary_user_id, secondary_user_id,
+            agents_moved: mergeResult.agents_moved,
+            identities_moved: mergeResult.identities_moved,
+            new_total_xp: mergeResult.total_xp,
+            secondary_status: "deactivated",
+        }));
+    });
+    logRegistered("levelup_merge_profiles");
+    console.error(`  → 13 of 13 user tools registered ✅`);
+}
+//# sourceMappingURL=users.js.map