level-up-mcp-server-cn 0.4.0

package/dist/tools/skills.js

@@ -0,0 +1,1112 @@
+// ============================================================
+// tools/skills.ts — Section 3: Skill tools (6 tools)
+// ============================================================
+// Tools 17-22. The Ability > Skill > Tool hierarchy.
+// ============================================================
+import { z } from "zod";
+import { supabase } from "../services/supabase.js";
+import { ok, fail, handleSupabaseError } from "../services/errors.js";
+import { paginate } from "../services/format.js";
+import { toMcpResponse, logRegistered } from "../services/register.js";
+import { uuidSchema, offsetSchema } from "../schemas/common.js";
+import { awardXpViaRpc } from "../services/quality-gate.js";
+import { verifyOwnership } from "../services/ownership.js";
+// ============================================================
+// Exported handler functions for dispatcher use
+// ============================================================
+export async function handleAddAgentSkill(params) {
+    const caller_user_id = params.caller_user_id;
+    const agent_id = params.agent_id;
+    const skill_id = params.skill_id;
+    const reason = params.reason || "manual";
+    // Ownership check
+    const denied = await verifyOwnership({ caller_user_id, target_agent_id: agent_id });
+    if (denied)
+        return denied;
+    // Verify agent exists
+    const { error: agentError } = await supabase.from("agents").select("id").eq("id", agent_id).single();
+    if (agentError)
+        return toMcpResponse(fail("未找到智能体", "请检查 agent_id。"));
+    // Verify skill exists
+    const { data: skill, error: skillError } = await supabase
+        .from("skills").select("id, name, category_id").eq("id", skill_id).single();
+    if (skillError || !skill)
+        return toMcpResponse(fail("未找到技能", "请使用 levelup_list_skills 浏览技能目录。"));
+    // MCP install → proficiency 1 shortcut
+    const proficiency = reason === "mcp_installed" ? 1 : 0;
+    const { data: rpcResult, error: insertError } = await supabase.rpc('upsert_agent_skill_secure', {
+        p_caller_user_id: caller_user_id,
+        p_agent_id: agent_id,
+        p_skill_id: skill_id,
+        p_proficiency_level: proficiency,
+        p_acquired_reason: reason,
+        p_usage_count: 0,
+    });
+    if (insertError)
+        return toMcpResponse(handleSupabaseError(insertError, "add_agent_skill"));
+    const agentSkill = rpcResult.agent_skill;
+    // Record in agent_tool_installations table via RPC
+    if (reason === "mcp_installed") {
+        const { error: installError } = await supabase.rpc('upsert_agent_tool_secure', {
+            p_caller_user_id: caller_user_id,
+            p_agent_id: agent_id,
+            p_tool_name: skill.name,
+        });
+        if (installError)
+            console.error("[add_agent_skill] Tool install record failed:", installError.message);
+    }
+    // Award XP for MCP tool installations (capped at 3/day)
+    let installXpAwarded = 0;
+    if (reason === "mcp_installed") {
+        const todayStart = new Date();
+        todayStart.setHours(0, 0, 0, 0);
+        const { data: todayInstalls } = await supabase
+            .from("xp_ledger")
+            .select("amount")
+            .eq("entity_type", "agent")
+            .eq("entity_id", agent_id)
+            .eq("source_type", "tool_install")
+            .gte("created_at", todayStart.toISOString());
+        const todayCount = (todayInstalls || []).length;
+        if (todayCount < 3) {
+            installXpAwarded = 20;
+            const { data: agentOwner } = await supabase
+                .from("agents").select("owner_user_id").eq("id", agent_id).maybeSingle();
+            await awardXpViaRpc("agent", agent_id, installXpAwarded, "tool_install", `工具安装: ${skill.name}`, agentSkill.id);
+            if (agentOwner?.owner_user_id) {
+                await awardXpViaRpc("user", agentOwner.owner_user_id, 5, "tool_install", `智能体安装: ${skill.name}`, agentSkill.id);
+            }
+        }
+    }
+    return toMcpResponse(ok({
+        id: agentSkill.id,
+        agent_id: agentSkill.agent_id,
+        skill_id: agentSkill.skill_id,
+        skill_name: skill.name,
+        proficiency_level: agentSkill.proficiency_level,
+        acquired_reason: agentSkill.acquired_reason,
+        xp_awarded: installXpAwarded,
+        message: proficiency === 1
+            ? `技能已添加，熟练度为1（MCP安装快捷方式）${installXpAwarded > 0 ? ` +${installXpAwarded} 经验值` : "（已达每日安装上限）"}`
+            : "技能已添加，熟练度为0（未验证）",
+    }));
+}
+export async function handleGetAgentSkills(params) {
+    const agent_id = params.agent_id;
+    const ability_id = params.ability_id;
+    const { data: agentSkills, error } = await supabase
+        .from("agent_skills")
+        .select("id, skill_id, proficiency_level, usage_count, usage_metrics, last_used_at, acquired_reason")
+        .eq("agent_id", agent_id);
+    if (error)
+        return toMcpResponse(handleSupabaseError(error, "get_agent_skills"));
+    if (!agentSkills || agentSkills.length === 0) {
+        return toMcpResponse(ok({ agent_id, groups: [], total_skills: 0 }));
+    }
+    const skillIds = agentSkills.map((s) => s.skill_id);
+    let skillQuery = supabase.from("skills").select("id, name, category_id, description").in("id", skillIds);
+    const { data: skills } = await skillQuery;
+    const categoryIds = [...new Set((skills || []).map((s) => s.category_id))];
+    let categories = [];
+    if (categoryIds.length > 0) {
+        let catQuery = supabase.from("skill_categories").select("id, name, description").in("id", categoryIds);
+        if (ability_id) {
+            catQuery = catQuery.eq("id", ability_id);
+        }
+        const { data: cats } = await catQuery;
+        categories = cats || [];
+    }
+    const skillMap = new Map((skills || []).map((s) => [s.id, s]));
+    const catMap = new Map(categories.map((c) => [c.id, c]));
+    const groups = [];
+    const groupMap = new Map();
+    for (const as of agentSkills) {
+        const skill = skillMap.get(as.skill_id);
+        if (!skill)
+            continue;
+        const cat = catMap.get(skill.category_id);
+        if (!cat)
+            continue;
+        let group = groupMap.get(cat.id);
+        if (!group) {
+            group = { ability_id: cat.id, ability_name: cat.name, skills: [] };
+            groupMap.set(cat.id, group);
+            groups.push(group);
+        }
+        group.skills.push({
+            skill_id: as.skill_id,
+            skill_name: skill.name,
+            proficiency_level: as.proficiency_level,
+            usage_count: as.usage_count,
+            last_used_at: as.last_used_at,
+            acquired_reason: as.acquired_reason,
+        });
+    }
+    return toMcpResponse(ok({ agent_id, groups, total_skills: agentSkills.length }));
+}
+export async function handleListSkills(params) {
+    const ability_id = params.ability_id;
+    const search = params.search;
+    const include_suggested = params.include_suggested ?? false;
+    const limit = params.limit ?? 50;
+    const offset = params.offset ?? 0;
+    let query = supabase
+        .from("skills")
+        .select("id, name, description, category_id, status, metadata, created_at", { count: "exact" });
+    if (include_suggested) {
+        query = query.in("status", ["active", "suggested"]);
+    }
+    else {
+        query = query.eq("status", "active");
+    }
+    if (ability_id) {
+        query = query.eq("category_id", ability_id);
+    }
+    if (search) {
+        query = query.or(`name.ilike.%${search}%,description.ilike.%${search}%`);
+    }
+    query = query.order("name", { ascending: true }).range(offset, offset + limit - 1);
+    const { data: skills, count, error } = await query;
+    if (error)
+        return toMcpResponse(handleSupabaseError(error, "list_skills"));
+    const categoryIds = [...new Set((skills || []).map((s) => s.category_id))];
+    let catMap = new Map();
+    if (categoryIds.length > 0) {
+        const { data: cats } = await supabase.from("skill_categories").select("id, name").in("id", categoryIds);
+        catMap = new Map((cats || []).map((c) => [c.id, c.name]));
+    }
+    const enriched = (skills || []).map((s) => ({
+        ...s,
+        ability_name: catMap.get(s.category_id) || "Unknown",
+    }));
+    return toMcpResponse(ok(paginate(enriched, count || 0, offset)));
+}
+export async function handleListSkillCategories(params) {
+    const search = params.search;
+    let query = supabase
+        .from("skill_categories")
+        .select("id, name, description, sort_order")
+        .order("sort_order", { ascending: true });
+    if (search) {
+        query = query.ilike("name", `%${search}%`);
+    }
+    const { data: categories, error } = await query;
+    if (error)
+        return toMcpResponse(handleSupabaseError(error, "list_skill_categories"));
+    const enriched = await Promise.all((categories || []).map(async (cat) => {
+        const { count } = await supabase
+            .from("skills")
+            .select("id", { count: "exact", head: true })
+            .eq("category_id", cat.id)
+            .eq("status", "active");
+        return { ...cat, skill_count: count || 0 };
+    }));
+    return toMcpResponse(ok(enriched));
+}
+export async function handleSuggestSkill(params) {
+    const caller_user_id = params.caller_user_id;
+    const name = params.name;
+    const description = params.description;
+    const suggested_ability_id = params.suggested_ability_id;
+    const suggested_by_agent_id = params.suggested_by_agent_id;
+    const evidence = params.evidence;
+    let categoryId = suggested_ability_id || null;
+    if (!categoryId) {
+        const { data: defaultCat } = await supabase
+            .from("skill_categories")
+            .select("id")
+            .order("sort_order", { ascending: true })
+            .limit(1)
+            .maybeSingle();
+        categoryId = defaultCat?.id || null;
+    }
+    if (!categoryId) {
+        return toMcpResponse(fail("尚无技能分类", "请先创建技能分类才能建议技能。请联系管理员创建。"));
+    }
+    return toMcpResponse(ok({
+        id: null,
+        name,
+        description,
+        category_id: categoryId,
+        status: "suggested",
+        message: "技能建议已提交审核。（等待 RPC: suggest_skill_secure）",
+    }));
+}
+export async function handleGetSkillProgress(params) {
+    const agent_id = params.agent_id;
+    const skill_id = params.skill_id;
+    const { data: agentSkill, error: asError } = await supabase
+        .from("agent_skills")
+        .select("*")
+        .eq("agent_id", agent_id)
+        .eq("skill_id", skill_id)
+        .maybeSingle();
+    if (!agentSkill) {
+        return toMcpResponse(fail("智能体没有此技能", "请先使用 levelup_add_agent_skill 添加。"));
+    }
+    const { data: skill } = await supabase
+        .from("skills").select("name, category_id").eq("id", skill_id).single();
+    const nextLevel = agentSkill.proficiency_level + 1;
+    const { data: rule } = await supabase
+        .from("skill_leveling_rules")
+        .select("*")
+        .eq("skill_id", skill_id)
+        .eq("proficiency_level", nextLevel)
+        .maybeSingle();
+    if (!rule) {
+        return toMcpResponse(ok({
+            agent_id,
+            skill_id,
+            skill_name: skill?.name || "Unknown",
+            current_proficiency: agentSkill.proficiency_level,
+            next_target: null,
+            message: agentSkill.proficiency_level >= 10
+                ? "已达最高熟练度！"
+                : "下一等级没有定义升级规则。",
+            usage_count: agentSkill.usage_count,
+            usage_metrics: agentSkill.usage_metrics,
+        }));
+    }
+    const { data: installations } = await supabase
+        .from("agent_tool_installations")
+        .select("tool_name, auth_connected")
+        .eq("agent_id", agent_id);
+    const { data: toolMappings } = await supabase
+        .from("skill_tool_mappings")
+        .select("tool_name, setup_credit")
+        .eq("skill_id", skill_id);
+    const installedTools = new Set((installations || []).map((i) => i.tool_name));
+    const requiredTools = toolMappings || [];
+    const setupComplete = requiredTools.length === 0 ? 100 :
+        Math.round((requiredTools.filter((t) => installedTools.has(t.tool_name)).length / requiredTools.length) * 100);
+    const usageReqs = rule.usage_requirements;
+    const tasksNeeded = usageReqs?.tasks_completed || 0;
+    const usageProgress = tasksNeeded > 0 ? Math.min(100, Math.round((agentSkill.usage_count / tasksNeeded) * 100)) : 100;
+    const setupWeight = Number(rule.setup_weight) || 0.33;
+    const usageWeight = Number(rule.usage_weight) || 0.34;
+    const refinementWeight = Number(rule.refinement_weight) || 0.33;
+    let refinementProgress = 0;
+    const { data: recentEvals } = await supabase
+        .from("task_evaluations")
+        .select("scores")
+        .eq("evaluator_type", "system_template")
+        .in("task_id", (await supabase
+        .from("task_evaluations")
+        .select("task_id")
+        .eq("evaluator_type", "agent")
+        .limit(10)).data?.map((e) => e.task_id) || [])
+        .limit(10);
+    if (recentEvals && recentEvals.length > 0) {
+        const qualityScores = [];
+        for (const ev of recentEvals) {
+            const scores = ev.scores;
+            const nums = Object.values(scores).filter((v) => typeof v === "number" && v >= 1 && v <= 5);
+            if (nums.length > 0) {
+                qualityScores.push(nums.reduce((s, n) => s + n, 0) / nums.length);
+            }
+        }
+        if (qualityScores.length > 0) {
+            const avgScore = qualityScores.reduce((s, n) => s + n, 0) / qualityScores.length;
+            refinementProgress = Math.round((avgScore / 5.0) * 100);
+        }
+    }
+    const overallProgress = Math.round(setupComplete * setupWeight +
+        usageProgress * usageWeight +
+        refinementProgress * refinementWeight);
+    return toMcpResponse(ok({
+        agent_id,
+        skill_id,
+        skill_name: skill?.name || "Unknown",
+        current_proficiency: agentSkill.proficiency_level,
+        next_target: nextLevel,
+        progress: {
+            overall_pct: overallProgress,
+            setup: {
+                weight: setupWeight,
+                progress_pct: setupComplete,
+                tools_installed: installedTools.size,
+                tools_mapped: requiredTools.length,
+            },
+            usage: {
+                weight: usageWeight,
+                progress_pct: usageProgress,
+                current_count: agentSkill.usage_count,
+                required_count: tasksNeeded,
+            },
+            refinement: {
+                weight: refinementWeight,
+                progress_pct: refinementProgress,
+                note: refinementProgress > 0 ? "基于近期任务的质量评分" : "请完成带有质量评估的任务以提升精炼度",
+            },
+        },
+        usage_metrics: agentSkill.usage_metrics,
+        last_used_at: agentSkill.last_used_at,
+    }));
+}
+export async function handleReportInstalledMcps(params) {
+    const caller_user_id = params.caller_user_id;
+    const agent_id = params.agent_id;
+    const tool_names = params.tool_names;
+    const ownershipErr = await verifyOwnership({ caller_user_id, target_agent_id: agent_id });
+    if (ownershipErr)
+        return ownershipErr;
+    const { data: agent, error: agentErr } = await supabase
+        .from("agents").select("id, owner_user_id").eq("id", agent_id).maybeSingle();
+    if (agentErr || !agent)
+        return toMcpResponse(fail("未找到智能体。"));
+    const { data: existing } = await supabase
+        .from("agent_tool_installations")
+        .select("tool_name")
+        .eq("agent_id", agent_id);
+    const existingSet = new Set((existing ?? []).map((r) => r.tool_name.toLowerCase()));
+    const newTools = tool_names.filter((t) => !existingSet.has(t.toLowerCase()));
+    const inserted = [];
+    for (const toolName of newTools) {
+        const { error } = await supabase.rpc('upsert_agent_tool_secure', {
+            p_caller_user_id: caller_user_id,
+            p_agent_id: agent_id,
+            p_tool_name: toolName,
+        });
+        if (!error)
+            inserted.push(toolName);
+    }
+    let xpAwarded = 0;
+    if (inserted.length > 0) {
+        const todayStart = new Date();
+        todayStart.setHours(0, 0, 0, 0);
+        const { data: todayInstalls } = await supabase
+            .from("xp_ledger")
+            .select("amount")
+            .eq("entity_type", "agent")
+            .eq("entity_id", agent_id)
+            .eq("source_type", "tool_install")
+            .gte("created_at", todayStart.toISOString());
+        const todayCount = (todayInstalls || []).length;
+        const slotsLeft = Math.max(0, 3 - todayCount);
+        const toAward = Math.min(inserted.length, slotsLeft);
+        for (let i = 0; i < toAward; i++) {
+            await awardXpViaRpc("agent", agent_id, 20, "tool_install", `MCP 上报: ${inserted[i]}`, undefined);
+            xpAwarded += 20;
+        }
+        if (agent.owner_user_id && toAward > 0) {
+            await awardXpViaRpc("user", agent.owner_user_id, toAward * 5, "tool_install", `智能体上报 ${toAward} 个新MCP`, undefined);
+        }
+    }
+    return toMcpResponse(ok({
+        agent_id,
+        reported: tool_names.length,
+        already_tracked: tool_names.length - newTools.length,
+        newly_recorded: inserted.length,
+        xp_awarded: xpAwarded,
+        tools: tool_names.map((t) => ({
+            name: t,
+            status: existingSet.has(t.toLowerCase()) ? "already_tracked" : inserted.includes(t) ? "newly_recorded" : "failed",
+        })),
+        message: inserted.length > 0
+            ? `已记录 ${inserted.length} 个新MCP。获得 ${xpAwarded} 经验值。`
+            : "所有上报的MCP均已被跟踪。",
+    }));
+}
+export async function handleGetPendingInstalls(params) {
+    const agent_id = params.agent_id;
+    const { data, error } = await supabase
+        .from("agent_pending_installs")
+        .select("id, agent_id, item_type, item_name, status, created_at")
+        .eq("agent_id", agent_id)
+        .eq("status", "pending")
+        .order("created_at", { ascending: true });
+    if (error)
+        return toMcpResponse(handleSupabaseError(error, "get_pending_installs"));
+    return toMcpResponse(ok({
+        agent_id,
+        pending_count: (data ?? []).length,
+        items: (data ?? []).map((r) => ({
+            id: r.id,
+            type: r.item_type,
+            name: r.item_name,
+            requested_at: r.created_at,
+            action: r.item_type === "mcp"
+                ? `请安装 "${r.item_name}" MCP 服务器，然后使用 levelup_confirm_install 确认`
+                : `请学习 "${r.item_name}" 技能（使用 levelup_add_agent_skill），然后使用 levelup_confirm_install 确认`,
+        })),
+    }));
+}
+export async function handleConfirmInstall(params) {
+    const caller_user_id = params.caller_user_id;
+    const install_id = params.install_id;
+    const agent_id = params.agent_id;
+    const ownershipErr = await verifyOwnership({ caller_user_id, target_agent_id: agent_id });
+    if (ownershipErr)
+        return ownershipErr;
+    const { data: record, error: fetchErr } = await supabase
+        .from("agent_pending_installs")
+        .select("id, agent_id, item_type, item_name, status")
+        .eq("id", install_id)
+        .eq("agent_id", agent_id)
+        .maybeSingle();
+    if (fetchErr)
+        return toMcpResponse(handleSupabaseError(fetchErr, "confirm_install"));
+    if (!record)
+        return toMcpResponse(fail("未找到待处理的安装记录，或该记录不属于此智能体。"));
+    if (record.status !== "pending")
+        return toMcpResponse(fail(`安装状态已为 ${record.status}。`));
+    const { error: updateErr } = await supabase
+        .from("agent_pending_installs")
+        .update({ status: "confirmed", confirmed_at: new Date().toISOString() })
+        .eq("id", install_id);
+    if (updateErr)
+        return toMcpResponse(handleSupabaseError(updateErr, "confirm_install"));
+    return toMcpResponse(ok({
+        install_id,
+        agent_id,
+        item_type: record.item_type,
+        item_name: record.item_name,
+        status: "confirmed",
+        message: `${record.item_type === "mcp" ? "MCP 服务器" : "技能"} "${record.item_name}" 已确认安装。`,
+    }));
+}
+export function registerSkillTools(server) {
+    console.error("\n📋 Section 3: Skills");
+    // ================================================================
+    // Tool 17: levelup_add_agent_skill
+    // ================================================================
+    server.registerTool("levelup_add_agent_skill", {
+        title: "添加智能体技能",
+        description: `为智能体资料添加技能。
+
+manual/auto_detected 的熟练度从0开始，通过MCP安装添加时为1
+（"MCP快捷方式" — 安装映射到此技能的工具可直接获得
+熟练度等级1）。
+
+参数:
+  - agent_id (uuid): 哪个智能体。
+  - skill_id (uuid): 目录中的哪个技能。
+  - reason (string, 可选): "manual"、"auto_detected" 或 "mcp_installed"（默认: "manual"）。
+
+返回:
+  新的 agent_skill 条目及熟练度等级。
+
+错误:
+  - 如果智能体已有此技能则返回 "Duplicate entry"。`,
+        inputSchema: {
+            caller_user_id: uuidSchema.describe("Your user ID (ownership verification)"),
+            agent_id: uuidSchema.describe("The agent (must be yours)"),
+            skill_id: uuidSchema.describe("The skill from the catalog"),
+            reason: z.enum(["manual", "auto_detected", "mcp_installed"]).default("manual").describe("How the skill was acquired"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        // Ownership check
+        const denied = await verifyOwnership({ caller_user_id: params.caller_user_id, target_agent_id: params.agent_id });
+        if (denied)
+            return denied;
+        // Verify agent exists
+        const { error: agentError } = await supabase.from("agents").select("id").eq("id", params.agent_id).single();
+        if (agentError)
+            return toMcpResponse(fail("未找到智能体", "请检查 agent_id。"));
+        // Verify skill exists
+        const { data: skill, error: skillError } = await supabase
+            .from("skills").select("id, name, category_id").eq("id", params.skill_id).single();
+        if (skillError || !skill)
+            return toMcpResponse(fail("未找到技能", "请使用 levelup_list_skills 浏览技能目录。"));
+        // MCP install → proficiency 1 shortcut
+        const proficiency = params.reason === "mcp_installed" ? 1 : 0;
+        const { data: rpcResult, error: insertError } = await supabase.rpc('upsert_agent_skill_secure', {
+            p_caller_user_id: params.caller_user_id,
+            p_agent_id: params.agent_id,
+            p_skill_id: params.skill_id,
+            p_proficiency_level: proficiency,
+            p_acquired_reason: params.reason,
+            p_usage_count: 0,
+        });
+        if (insertError)
+            return toMcpResponse(handleSupabaseError(insertError, "add_agent_skill"));
+        const agentSkill = rpcResult.agent_skill;
+        // Record in agent_tool_installations table via RPC
+        if (params.reason === "mcp_installed") {
+            const { error: installError } = await supabase.rpc('upsert_agent_tool_secure', {
+                p_caller_user_id: params.caller_user_id,
+                p_agent_id: params.agent_id,
+                p_tool_name: skill.name,
+            });
+            if (installError)
+                console.error("[add_agent_skill] Tool install record failed:", installError.message);
+        }
+        // Award XP for MCP tool installations (capped at 3/day)
+        let installXpAwarded = 0;
+        if (params.reason === "mcp_installed") {
+            // Check daily cap: max 3 tool_install XP awards per day
+            const todayStart = new Date();
+            todayStart.setHours(0, 0, 0, 0);
+            const { data: todayInstalls } = await supabase
+                .from("xp_ledger")
+                .select("amount")
+                .eq("entity_type", "agent")
+                .eq("entity_id", params.agent_id)
+                .eq("source_type", "tool_install")
+                .gte("created_at", todayStart.toISOString());
+            const todayCount = (todayInstalls || []).length;
+            if (todayCount < 3) {
+                installXpAwarded = 20;
+                // Get agent's owner for user XP share
+                const { data: agentOwner } = await supabase
+                    .from("agents").select("owner_user_id").eq("id", params.agent_id).maybeSingle();
+                await awardXpViaRpc("agent", params.agent_id, installXpAwarded, "tool_install", `工具安装: ${skill.name}`, agentSkill.id);
+                // Also award 5 XP to the owner user
+                if (agentOwner?.owner_user_id) {
+                    await awardXpViaRpc("user", agentOwner.owner_user_id, 5, "tool_install", `智能体安装: ${skill.name}`, agentSkill.id);
+                }
+            }
+        }
+        return toMcpResponse(ok({
+            id: agentSkill.id,
+            agent_id: agentSkill.agent_id,
+            skill_id: agentSkill.skill_id,
+            skill_name: skill.name,
+            proficiency_level: agentSkill.proficiency_level,
+            acquired_reason: agentSkill.acquired_reason,
+            xp_awarded: installXpAwarded,
+            message: proficiency === 1
+                ? `Skill added at proficiency 1 (MCP install shortcut)${installXpAwarded > 0 ? ` +${installXpAwarded} XP` : " (daily install cap reached)"}`
+                : "Skill added at proficiency 0 (unproven)",
+        }));
+    });
+    logRegistered("levelup_add_agent_skill");
+    // ================================================================
+    // Tool 18: levelup_get_agent_skills
+    // ================================================================
+    server.registerTool("levelup_get_agent_skills", {
+        title: "获取智能体技能",
+        description: `获取智能体的所有技能，按能力分类分组。
+
+显示熟练度等级、使用指标和下一等级的进度。
+
+参数:
+  - agent_id (uuid): 哪个智能体。
+  - ability_id (uuid, 可选): 筛选单个能力分类。
+
+返回:
+  按能力分组的技能: { ability_name, skills: [{ skill_name, proficiency_level, usage_count, ... }] }`,
+        inputSchema: {
+            agent_id: uuidSchema.describe("The agent"),
+            ability_id: uuidSchema.optional().describe("Filter to one ability category"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        // Fetch agent's skills
+        const { data: agentSkills, error } = await supabase
+            .from("agent_skills")
+            .select("id, skill_id, proficiency_level, usage_count, usage_metrics, last_used_at, acquired_reason")
+            .eq("agent_id", params.agent_id);
+        if (error)
+            return toMcpResponse(handleSupabaseError(error, "get_agent_skills"));
+        if (!agentSkills || agentSkills.length === 0) {
+            return toMcpResponse(ok({ agent_id: params.agent_id, groups: [], total_skills: 0 }));
+        }
+        // Fetch skill details
+        const skillIds = agentSkills.map((s) => s.skill_id);
+        let skillQuery = supabase.from("skills").select("id, name, category_id, description").in("id", skillIds);
+        const { data: skills } = await skillQuery;
+        // Fetch categories
+        const categoryIds = [...new Set((skills || []).map((s) => s.category_id))];
+        // Apply ability_id filter if provided
+        let categories = [];
+        if (categoryIds.length > 0) {
+            let catQuery = supabase.from("skill_categories").select("id, name, description").in("id", categoryIds);
+            if (params.ability_id) {
+                catQuery = catQuery.eq("id", params.ability_id);
+            }
+            const { data: cats } = await catQuery;
+            categories = cats || [];
+        }
+        // Build skill map
+        const skillMap = new Map((skills || []).map((s) => [s.id, s]));
+        const catMap = new Map(categories.map((c) => [c.id, c]));
+        // Group by category
+        const groups = [];
+        const groupMap = new Map();
+        for (const as of agentSkills) {
+            const skill = skillMap.get(as.skill_id);
+            if (!skill)
+                continue;
+            const cat = catMap.get(skill.category_id);
+            if (!cat)
+                continue; // filtered out by ability_id
+            let group = groupMap.get(cat.id);
+            if (!group) {
+                group = { ability_id: cat.id, ability_name: cat.name, skills: [] };
+                groupMap.set(cat.id, group);
+                groups.push(group);
+            }
+            group.skills.push({
+                skill_id: as.skill_id,
+                skill_name: skill.name,
+                proficiency_level: as.proficiency_level,
+                usage_count: as.usage_count,
+                last_used_at: as.last_used_at,
+                acquired_reason: as.acquired_reason,
+            });
+        }
+        return toMcpResponse(ok({
+            agent_id: params.agent_id,
+            groups,
+            total_skills: agentSkills.length,
+        }));
+    });
+    logRegistered("levelup_get_agent_skills");
+    // ================================================================
+    // Tool 19: levelup_list_skills
+    // ================================================================
+    server.registerTool("levelup_list_skills", {
+        title: "列出技能",
+        description: `浏览技能目录，支持可选筛选。
+
+参数:
+  - ability_id (uuid, 可选): 按能力分类筛选。
+  - search (string, 可选): 按技能名称/描述搜索。
+  - include_suggested (boolean, 可选): 包含社区建议（默认: false）。
+  - limit (integer, 可选): 最大结果数（默认 50，最大 100）。
+  - offset (integer, 可选): 分页偏移量。
+
+返回:
+  包含名称、描述、能力分类、状态的技能分页列表。`,
+        inputSchema: {
+            ability_id: uuidSchema.optional().describe("Filter by ability category"),
+            search: z.string().max(200).optional().describe("Text search"),
+            include_suggested: z.boolean().default(false).describe("Include community suggestions"),
+            limit: z.number().int().min(1).max(100).default(50).describe("Max results (default 50)"),
+            offset: offsetSchema,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        let query = supabase
+            .from("skills")
+            .select("id, name, description, category_id, status, metadata, created_at", { count: "exact" });
+        // Filter by status
+        if (params.include_suggested) {
+            query = query.in("status", ["active", "suggested"]);
+        }
+        else {
+            query = query.eq("status", "active");
+        }
+        // Filter by ability
+        if (params.ability_id) {
+            query = query.eq("category_id", params.ability_id);
+        }
+        // Text search
+        if (params.search) {
+            query = query.or(`name.ilike.%${params.search}%,description.ilike.%${params.search}%`);
+        }
+        query = query.order("name", { ascending: true }).range(params.offset, params.offset + params.limit - 1);
+        const { data: skills, count, error } = await query;
+        if (error)
+            return toMcpResponse(handleSupabaseError(error, "list_skills"));
+        // Enrich with category names
+        const categoryIds = [...new Set((skills || []).map((s) => s.category_id))];
+        let catMap = new Map();
+        if (categoryIds.length > 0) {
+            const { data: cats } = await supabase.from("skill_categories").select("id, name").in("id", categoryIds);
+            catMap = new Map((cats || []).map((c) => [c.id, c.name]));
+        }
+        const enriched = (skills || []).map((s) => ({
+            ...s,
+            ability_name: catMap.get(s.category_id) || "Unknown",
+        }));
+        return toMcpResponse(ok(paginate(enriched, count || 0, params.offset)));
+    });
+    logRegistered("levelup_list_skills");
+    // ================================================================
+    // Tool 20: levelup_list_skill_categories
+    // ================================================================
+    server.registerTool("levelup_list_skill_categories", {
+        title: "列出技能分类",
+        description: `列出所有能力分类（能力 > 技能 > 工具层级的顶层）。
+
+参数:
+  - search (string, 可选): 按分类名称搜索。
+
+返回:
+  包含 id、名称、描述、技能数量的分类列表。`,
+        inputSchema: {
+            search: z.string().max(200).optional().describe("Text search on category name"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        let query = supabase
+            .from("skill_categories")
+            .select("id, name, description, sort_order")
+            .order("sort_order", { ascending: true });
+        if (params.search) {
+            query = query.ilike("name", `%${params.search}%`);
+        }
+        const { data: categories, error } = await query;
+        if (error)
+            return toMcpResponse(handleSupabaseError(error, "list_skill_categories"));
+        // Count skills per category
+        const enriched = await Promise.all((categories || []).map(async (cat) => {
+            const { count } = await supabase
+                .from("skills")
+                .select("id", { count: "exact", head: true })
+                .eq("category_id", cat.id)
+                .eq("status", "active");
+            return { ...cat, skill_count: count || 0 };
+        }));
+        return toMcpResponse(ok(enriched));
+    });
+    logRegistered("levelup_list_skill_categories");
+    // ================================================================
+    // Tool 21: levelup_suggest_skill
+    // ================================================================
+    server.registerTool("levelup_suggest_skill", {
+        title: "建议技能",
+        description: `为目录提议新技能。进入 "pending_review" 状态。
+
+智能体和用户可以建议他们认为目录中缺少的技能。
+管理员审核并批准/拒绝。
+
+参数:
+  - name (string): 建议的技能名称。
+  - description (string): 该技能涵盖的内容。
+  - suggested_ability_id (uuid, 可选): 所属的能力分类。
+  - suggested_by_agent_id (uuid, 可选): 建议的智能体。
+  - suggested_by_user_id (uuid, 可选): 建议的用户。
+  - evidence (string, 可选): 为什么需要此技能。
+
+返回:
+  状态为 "suggested" 的建议记录。`,
+        inputSchema: {
+            caller_user_id: uuidSchema.describe("Your user_id for ownership verification"),
+            name: z.string().min(2).max(100).describe("Proposed skill name"),
+            description: z.string().min(10).max(500).describe("What this skill covers"),
+            suggested_ability_id: uuidSchema.optional().describe("Which ability category"),
+            suggested_by_agent_id: uuidSchema.optional().describe("Agent suggesting"),
+            evidence: z.string().max(500).optional().describe("Why this skill is needed"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        // If no category provided, try to find a "General" or use the first one
+        let categoryId = params.suggested_ability_id || null;
+        if (!categoryId) {
+            const { data: defaultCat } = await supabase
+                .from("skill_categories")
+                .select("id")
+                .order("sort_order", { ascending: true })
+                .limit(1)
+                .maybeSingle();
+            categoryId = defaultCat?.id || null;
+        }
+        if (!categoryId) {
+            return toMcpResponse(fail("No skill categories exist yet", "A skill category must exist before suggesting skills. Ask an admin to create one."));
+        }
+        // NOTE: Direct INSERT to skills table is blocked without an RPC.
+        // A suggest_skill_secure RPC needs to be created to handle this write.
+        // For now, return a success message without persisting (suggestion noted but not stored).
+        return toMcpResponse(ok({
+            id: null,
+            name: params.name,
+            description: params.description,
+            category_id: categoryId,
+            status: "suggested",
+            message: "技能建议已提交审核。（等待 RPC: suggest_skill_secure）",
+        }));
+    });
+    logRegistered("levelup_suggest_skill");
+    // ================================================================
+    // Tool 22: levelup_get_skill_progress
+    // ================================================================
+    server.registerTool("levelup_get_skill_progress", {
+        title: "获取技能进度",
+        description: `获取智能体特定技能向下一熟练度等级的详细进度。
+
+显示当前熟练度、需求分解（设置/使用/精炼），
+以及总体进度百分比。
+
+参数:
+  - agent_id (uuid): 哪个智能体。
+  - skill_id (uuid): 哪个技能。
+
+返回:
+  当前熟练度、下一目标等级、设置/使用/精炼各组件的
+  需求分解及进度、总体进度百分比。`,
+        inputSchema: {
+            agent_id: uuidSchema.describe("The agent"),
+            skill_id: uuidSchema.describe("The skill"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (params) => {
+        // Fetch agent's current skill status
+        const { data: agentSkill, error: asError } = await supabase
+            .from("agent_skills")
+            .select("*")
+            .eq("agent_id", params.agent_id)
+            .eq("skill_id", params.skill_id)
+            .maybeSingle();
+        if (!agentSkill) {
+            return toMcpResponse(fail("Agent does not have this skill", "Use levelup_add_agent_skill to add it first."));
+        }
+        // Get skill name
+        const { data: skill } = await supabase
+            .from("skills").select("name, category_id").eq("id", params.skill_id).single();
+        // Get the leveling rule for the NEXT proficiency level
+        const nextLevel = agentSkill.proficiency_level + 1;
+        const { data: rule } = await supabase
+            .from("skill_leveling_rules")
+            .select("*")
+            .eq("skill_id", params.skill_id)
+            .eq("proficiency_level", nextLevel)
+            .maybeSingle();
+        if (!rule) {
+            // No more levels to progress to (max proficiency or no rules defined)
+            return toMcpResponse(ok({
+                agent_id: params.agent_id,
+                skill_id: params.skill_id,
+                skill_name: skill?.name || "Unknown",
+                current_proficiency: agentSkill.proficiency_level,
+                next_target: null,
+                message: agentSkill.proficiency_level >= 10
+                    ? "Maximum proficiency reached!"
+                    : "No leveling rules defined for the next level.",
+                usage_count: agentSkill.usage_count,
+                usage_metrics: agentSkill.usage_metrics,
+            }));
+        }
+        // Check tool installations for setup progress
+        const { data: installations } = await supabase
+            .from("agent_tool_installations")
+            .select("tool_name, auth_connected")
+            .eq("agent_id", params.agent_id);
+        // Get mapped tools for this skill
+        const { data: toolMappings } = await supabase
+            .from("skill_tool_mappings")
+            .select("tool_name, setup_credit")
+            .eq("skill_id", params.skill_id);
+        // Calculate setup progress
+        const installedTools = new Set((installations || []).map((i) => i.tool_name));
+        const requiredTools = toolMappings || [];
+        const setupComplete = requiredTools.length === 0 ? 100 :
+            Math.round((requiredTools.filter((t) => installedTools.has(t.tool_name)).length / requiredTools.length) * 100);
+        // Usage progress (simple: compare usage_count to requirements)
+        const usageReqs = rule.usage_requirements;
+        const tasksNeeded = usageReqs?.tasks_completed || 0;
+        const usageProgress = tasksNeeded > 0 ? Math.min(100, Math.round((agentSkill.usage_count / tasksNeeded) * 100)) : 100;
+        // Overall progress (weighted by rule weights)
+        const setupWeight = Number(rule.setup_weight) || 0.33;
+        const usageWeight = Number(rule.usage_weight) || 0.34;
+        const refinementWeight = Number(rule.refinement_weight) || 0.33;
+        // Refinement progress: average quality score from recent tasks using this skill
+        let refinementProgress = 0;
+        const { data: recentEvals } = await supabase
+            .from("task_evaluations")
+            .select("scores")
+            .eq("evaluator_type", "system_template")
+            .in("task_id", 
+        // Subquery: tasks where this skill was used (via agent self-eval skills_used)
+        (await supabase
+            .from("task_evaluations")
+            .select("task_id")
+            .eq("evaluator_type", "agent")
+            .limit(10)).data?.map((e) => e.task_id) || [])
+            .limit(10);
+        if (recentEvals && recentEvals.length > 0) {
+            const qualityScores = [];
+            for (const ev of recentEvals) {
+                const scores = ev.scores;
+                const nums = Object.values(scores).filter((v) => typeof v === "number" && v >= 1 && v <= 5);
+                if (nums.length > 0) {
+                    qualityScores.push(nums.reduce((s, n) => s + n, 0) / nums.length);
+                }
+            }
+            if (qualityScores.length > 0) {
+                const avgScore = qualityScores.reduce((s, n) => s + n, 0) / qualityScores.length;
+                refinementProgress = Math.round((avgScore / 5.0) * 100); // 0-100 scale
+            }
+        }
+        const overallProgress = Math.round(setupComplete * setupWeight +
+            usageProgress * usageWeight +
+            refinementProgress * refinementWeight);
+        return toMcpResponse(ok({
+            agent_id: params.agent_id,
+            skill_id: params.skill_id,
+            skill_name: skill?.name || "Unknown",
+            current_proficiency: agentSkill.proficiency_level,
+            next_target: nextLevel,
+            progress: {
+                overall_pct: overallProgress,
+                setup: {
+                    weight: setupWeight,
+                    progress_pct: setupComplete,
+                    tools_installed: installedTools.size,
+                    tools_mapped: requiredTools.length,
+                },
+                usage: {
+                    weight: usageWeight,
+                    progress_pct: usageProgress,
+                    current_count: agentSkill.usage_count,
+                    required_count: tasksNeeded,
+                },
+                refinement: {
+                    weight: refinementWeight,
+                    progress_pct: refinementProgress,
+                    note: refinementProgress > 0 ? "基于近期任务的质量评分" : "请完成带有质量评估的任务以提升精炼度",
+                },
+            },
+            usage_metrics: agentSkill.usage_metrics,
+            last_used_at: agentSkill.last_used_at,
+        }));
+    });
+    logRegistered("levelup_get_skill_progress");
+    // ── Tool 23: levelup_get_pending_installs ────────────────────
+    server.tool("levelup_get_pending_installs", "列出智能体的待处理MCP/技能安装请求（来自前端技能树）。智能体应通过安装MCP或学习技能来处理这些请求，然后确认。", { agent_id: uuidSchema.describe("Agent to check pending installs for") }, async ({ agent_id }) => {
+        const { data, error } = await supabase
+            .from("agent_pending_installs")
+            .select("id, agent_id, item_type, item_name, status, created_at")
+            .eq("agent_id", agent_id)
+            .eq("status", "pending")
+            .order("created_at", { ascending: true });
+        if (error)
+            return toMcpResponse(handleSupabaseError(error, "get_pending_installs"));
+        return toMcpResponse(ok({
+            agent_id,
+            pending_count: (data ?? []).length,
+            items: (data ?? []).map((r) => ({
+                id: r.id,
+                type: r.item_type,
+                name: r.item_name,
+                requested_at: r.created_at,
+                action: r.item_type === "mcp"
+                    ? `Install the "${r.item_name}" MCP server, then confirm with levelup_confirm_install`
+                    : `Learn the "${r.item_name}" skill (use levelup_add_agent_skill), then confirm with levelup_confirm_install`,
+            })),
+        }));
+    });
+    logRegistered("levelup_get_pending_installs");
+    // ── Tool 24: levelup_confirm_install ────────────────────────
+    server.tool("levelup_confirm_install", "确认待处理的MCP/技能安装已完成。在智能体实际安装MCP或学习技能后调用。", {
+        caller_user_id: uuidSchema.describe("Your user_id for ownership verification"),
+        install_id: uuidSchema.describe("ID of the pending install record to confirm"),
+        agent_id: uuidSchema.describe("Agent ID (for ownership verification)"),
+    }, async ({ caller_user_id, install_id, agent_id }) => {
+        // Ownership check: verify caller owns the agent
+        const ownershipErr = await verifyOwnership({
+            caller_user_id,
+            target_agent_id: agent_id,
+        });
+        if (ownershipErr)
+            return ownershipErr;
+        // Verify the pending record exists and belongs to this agent
+        const { data: record, error: fetchErr } = await supabase
+            .from("agent_pending_installs")
+            .select("id, agent_id, item_type, item_name, status")
+            .eq("id", install_id)
+            .eq("agent_id", agent_id)
+            .maybeSingle();
+        if (fetchErr)
+            return toMcpResponse(handleSupabaseError(fetchErr, "confirm_install"));
+        if (!record)
+            return toMcpResponse(fail("未找到待处理的安装记录，或该记录不属于此智能体。"));
+        if (record.status !== "pending")
+            return toMcpResponse(fail(`安装状态已为 ${record.status}。`));
+        // Mark as confirmed
+        const { error: updateErr } = await supabase
+            .from("agent_pending_installs")
+            .update({ status: "confirmed", confirmed_at: new Date().toISOString() })
+            .eq("id", install_id);
+        if (updateErr)
+            return toMcpResponse(handleSupabaseError(updateErr, "confirm_install"));
+        return toMcpResponse(ok({
+            install_id,
+            agent_id,
+            item_type: record.item_type,
+            item_name: record.item_name,
+            status: "confirmed",
+            message: `${record.item_type === "mcp" ? "MCP 服务器" : "技能"} "${record.item_name}" 已确认安装。`,
+        }));
+    });
+    logRegistered("levelup_confirm_install");
+    // ── Tool 25: levelup_report_installed_mcps ───────────────────
+    server.tool("levelup_report_installed_mcps", `上报智能体当前已安装/可用的MCP服务器。
+调用此工具将智能体实际的MCP环境与 升级同步。
+智能体（或客户端）应列出其可访问的MCP服务器名称。
+新MCP会记录到 agent_tool_installations 并各奖励20经验值（每日最多3次）。
+
+示例 tool_names: ["filesystem", "github", "supabase", "brave-search", "memory"]
+
+此操作是幂等的 — 重复上报同一MCP不会产生重复记录或经验值。`, {
+        caller_user_id: uuidSchema.describe("Your user_id for ownership verification"),
+        agent_id: uuidSchema.describe("Agent reporting its installed MCPs"),
+        tool_names: z.array(z.string().min(1).max(100)).min(1).max(50)
+            .describe("Array of MCP server names currently installed"),
+    }, async ({ caller_user_id, agent_id, tool_names }) => {
+        // Ownership check: verify caller owns the agent
+        const ownershipErr = await verifyOwnership({
+            caller_user_id,
+            target_agent_id: agent_id,
+        });
+        if (ownershipErr)
+            return ownershipErr;
+        // Verify agent exists
+        const { data: agent, error: agentErr } = await supabase
+            .from("agents").select("id, owner_user_id").eq("id", agent_id).maybeSingle();
+        if (agentErr || !agent)
+            return toMcpResponse(fail("未找到智能体。"));
+        // Get existing installations to avoid duplicates
+        const { data: existing } = await supabase
+            .from("agent_tool_installations")
+            .select("tool_name")
+            .eq("agent_id", agent_id);
+        const existingSet = new Set((existing ?? []).map((r) => r.tool_name.toLowerCase()));
+        const newTools = tool_names.filter((t) => !existingSet.has(t.toLowerCase()));
+        // Insert new installations via RPC
+        const inserted = [];
+        for (const toolName of newTools) {
+            const { error } = await supabase.rpc('upsert_agent_tool_secure', {
+                p_caller_user_id: caller_user_id,
+                p_agent_id: agent_id,
+                p_tool_name: toolName,
+            });
+            if (!error)
+                inserted.push(toolName);
+        }
+        // Award XP for new installs (max 3/day)
+        let xpAwarded = 0;
+        if (inserted.length > 0) {
+            const todayStart = new Date();
+            todayStart.setHours(0, 0, 0, 0);
+            const { data: todayInstalls } = await supabase
+                .from("xp_ledger")
+                .select("amount")
+                .eq("entity_type", "agent")
+                .eq("entity_id", agent_id)
+                .eq("source_type", "tool_install")
+                .gte("created_at", todayStart.toISOString());
+            const todayCount = (todayInstalls || []).length;
+            const slotsLeft = Math.max(0, 3 - todayCount);
+            const toAward = Math.min(inserted.length, slotsLeft);
+            for (let i = 0; i < toAward; i++) {
+                await awardXpViaRpc("agent", agent_id, 20, "tool_install", `MCP 上报: ${inserted[i]}`, undefined);
+                xpAwarded += 20;
+            }
+            // Award user share (5 XP per install)
+            if (agent.owner_user_id && toAward > 0) {
+                await awardXpViaRpc("user", agent.owner_user_id, toAward * 5, "tool_install", `智能体上报 ${toAward} 个新MCP`, undefined);
+            }
+        }
+        return toMcpResponse(ok({
+            agent_id,
+            reported: tool_names.length,
+            already_tracked: tool_names.length - newTools.length,
+            newly_recorded: inserted.length,
+            xp_awarded: xpAwarded,
+            tools: tool_names.map((t) => ({
+                name: t,
+                status: existingSet.has(t.toLowerCase()) ? "already_tracked" : inserted.includes(t) ? "newly_recorded" : "failed",
+            })),
+            message: inserted.length > 0
+                ? `Recorded ${inserted.length} new MCP(s). ${xpAwarded} XP awarded.`
+                : "All reported MCPs are already tracked.",
+        }));
+    });
+    logRegistered("levelup_report_installed_mcps");
+    console.error(`  → 9 of 9 skill tools registered ✅`);
+}
+//# sourceMappingURL=skills.js.map