psyclaw 0.26.3 → 0.27.4

package/dist/src/adapters/pi/extension.js

@@ -1,6 +1,6 @@
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { asProject, bootstrapProject, projectPaths, runOfflineBrief, runInstitutionalFulltext, runLiteratureReview, runExpertReview, runAnalysisDelegation, runWritingReview, runMetaAnalysis, createStageRunner, publishManuscript, recordCitationUse, writeHandoff } from "../../index.js";
+import { asProject, bootstrapProject, exportTraces, projectPaths, runOfflineBrief, runInstitutionalFulltext, runLiteratureReview, runExpertReview, runAnalysisDelegation, runWritingReview, runMetaAnalysis, createStageRunner, publishManuscript, recordCitationUse, writeHandoff } from "../../index.js";
 import { runPlanWithPi } from "../../orchestration/pi-executor.js";
 import { atomicWriteFile } from "../../project/jsonl.js";
 import { RunEventLog } from "../../panel/events.js";
@@ -10,6 +10,8 @@ import { mkdir, readFile } from "node:fs/promises";
 import { PROVIDER_PRESETS } from "../../setup.js";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { coreSkillNames, enabledRecommendedSkillPaths, normalizeRecommendedSkillId, readRecommendationState, readRecommendedCatalog, recommendedSkillTarget, saveRecommendationState, validateModelInstalledRecommendedSkill, } from "../../skills/recommended.js";
+import { SkillManagerComponent } from "../../tui/skill-manager.js";
 const PARADIGMS = new Set([
     "survey-observational",
     "qualitative-thematic",
@@ -44,19 +46,6 @@ async function notifyError(ctx, error) {
 }
 const activeAgentRuns = new Set();
 const CORE_SKILLS = new Set(["research-intake", "evidence-capture", "citation-audit", "research-brief"]);
-async function recommendationState(root) {
-    try {
-        const value = JSON.parse(await readFile(join(root, ".psyclaw", "recommendations.json"), "utf8"));
-        return { schemaVersion: "psyclaw/recommendation-state/v1", skills: Array.isArray(value.skills) ? value.skills.filter((id) => typeof id === "string") : [], mcp: Array.isArray(value.mcp) ? value.mcp.filter((id) => typeof id === "string") : [] };
-    }
-    catch {
-        return { schemaVersion: "psyclaw/recommendation-state/v1", skills: [], mcp: [] };
-    }
-}
-async function saveRecommendationState(root, state) {
-    await mkdir(join(root, ".psyclaw"), { recursive: true });
-    await atomicWriteFile(join(root, ".psyclaw", "recommendations.json"), `${JSON.stringify({ ...state, skills: [...new Set(state.skills)].sort(), mcp: [...new Set(state.mcp)].sort() }, null, 2)}\n`);
-}
 function coreSkillPath(name) {
     return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "skills", "core", name, "SKILL.md");
 }
@@ -147,125 +136,303 @@ async function recommendedItems(kind) {
             const value = JSON.parse(await readFile(path, "utf8"));
             return {
                 items: Array.isArray(value.items) ? value.items.filter((item) => Boolean(item && typeof item === "object")) : [],
+                externalTools: Array.isArray(value.externalTools) ? value.externalTools.filter((item) => Boolean(item && typeof item === "object")) : [],
                 installPrep: Array.isArray(value.installPrep) ? value.installPrep.filter((item) => Boolean(item && typeof item === "object")) : [],
             };
         }
         catch { /* try next candidate */ }
     }
-    return { items: [], installPrep: [] };
+    return { items: [], externalTools: [], installPrep: [] };
 }
-async function showRecommended(kind, args, ctx) {
-    const { items, installPrep } = await recommendedItems(kind);
-    const state = await recommendationState(ctx.cwd);
-    const stateKey = kind === "skills" ? "skill" : "mcp";
-    const stateField = kind === "skills" ? "skills" : "mcp";
-    const action = args.trim().split(/\s+/).filter(Boolean);
-    const verb = action[0];
-    const id = action[1];
-    if (verb && !["status", "enable", "disable", "install", "select"].includes(verb)) {
-        throw new Error(`Usage: /${kind} [status|enable <id>|disable <id>|install <id>]`);
-    }
-    // 1. 无参数或显式 select 时，如果处于交互 TUI 模式，则启动键盘上下键选择器
-    if ((!verb || verb === "select") && ctx.hasUI && typeof ctx.ui.select === "function") {
-        if (!items.length) {
-            ctx.ui.notify(`暂无推荐${kind === "skills" ? " Skill" : " MCP"}`, "info");
-            return;
+function skillScopeLabel(scope) {
+    return scope === "user" ? "系统目录（所有项目）" : "项目目录（仅当前项目）";
+}
+async function skillManagerRows(root, state) {
+    const catalog = await readRecommendedCatalog();
+    return Promise.all(catalog.items.filter((item) => item.kind === "skill").map(async (item) => {
+        const id = normalizeRecommendedSkillId(item.id);
+        const scope = state.skillScopes?.[id] ?? "project";
+        try {
+            await validateModelInstalledRecommendedSkill(root, id, scope);
+            return {
+                id,
+                name: item.name,
+                description: String(item.description ?? ""),
+                ...(item.sourceRef === undefined ? {} : { sourceRef: item.sourceRef }),
+                installed: true,
+                enabled: state.skills.includes(id),
+                scope,
+                blocked: false,
+            };
         }
-        const enabled = new Set(state[stateField]);
-        const optionLabels = items.map((item) => {
-            const isEnabled = enabled.has(String(item.id));
-            const mark = isEnabled ? "● [已启用]" : "○ [未启用]";
-            const stage = item.stage ? ` [${String(item.stage)}]` : "";
-            const desc = item.description ? ` — ${String(item.description)}` : "";
-            return `${mark} ${String(item.name)}${stage}${desc}`;
-        });
-        const CANCEL_LABEL = "↩️ 取消 / 返回";
-        const selected = await ctx.ui.select(`选择推荐 ${kind === "skills" ? "Skill" : "MCP"}（使用键盘 ↑/↓ 移动光标，Enter 确认）:`, [...optionLabels, CANCEL_LABEL]);
-        if (!selected || selected === CANCEL_LABEL)
-            return;
-        const selectedIndex = optionLabels.indexOf(selected);
-        if (selectedIndex < 0 || selectedIndex >= items.length)
-            return;
-        const selectedItem = items[selectedIndex];
-        if (!selectedItem)
-            return;
-        const targetId = String(selectedItem.id);
-        const isCurrentlyEnabled = enabled.has(targetId);
-        const actionChoice = await ctx.ui.select(`管理推荐 ${kind === "skills" ? "Skill" : "MCP"}: ${String(selectedItem.name)} (${targetId})`, [
-            isCurrentlyEnabled ? `🔴 禁用 (Disable ${String(selectedItem.name)})` : `🟢 启用 (Enable ${String(selectedItem.name)})`,
-            `📦 查看安装预检与依赖计划 (Install Plan)`,
-            `🌐 查看来源仓库 (${String(selectedItem.sourceRef ?? "无")})`,
-            `↩️ 取消`,
-        ]);
-        if (!actionChoice || actionChoice === "↩️ 取消")
-            return;
-        if (actionChoice.startsWith("🔴") || actionChoice.startsWith("🟢")) {
-            const nextAction = isCurrentlyEnabled ? "disable" : "enable";
-            if (await ctx.ui.confirm(`${nextAction === "enable" ? "启用" : "禁用"}推荐${stateKey === "skill" ? " Skill" : " MCP"}`, `${String(selectedItem.name)} 的状态将写入当前项目配置。`)) {
-                const current = new Set(state[stateField]);
-                if (nextAction === "enable")
-                    current.add(targetId);
-                else
-                    current.delete(targetId);
-                state[stateField] = [...current];
-                await saveRecommendationState(ctx.cwd, state);
-                ctx.ui.notify(`${nextAction === "enable" ? "已启用" : "已禁用"} ${String(selectedItem.name)}（/reload 后生效；打开 /panel 可可视化管理）`, "info");
-            }
-            return;
+        catch {
+            return {
+                id,
+                name: item.name,
+                description: String(item.description ?? ""),
+                ...(item.sourceRef === undefined ? {} : { sourceRef: item.sourceRef }),
+                installed: false,
+                enabled: false,
+                scope,
+                blocked: typeof item.sourceRef !== "string" || !/^https:\/\//.test(item.sourceRef),
+                reason: typeof item.sourceRef === "string" && /^https:\/\//.test(item.sourceRef)
+                    ? "尚未安装；按 Enter 选择安装范围并交给当前模型处理"
+                    : "没有可交给模型检查的来源网址",
+            };
         }
-        if (actionChoice.startsWith("📦")) {
-            const plan = installPrep.find((candidate) => candidate.id === targetId);
-            ctx.ui.notify(JSON.stringify({
-                schemaVersion: "psyclaw/recommendation-install/v1",
-                kind: stateKey,
-                id: targetId,
-                name: selectedItem.name,
-                sourceRef: selectedItem.sourceRef,
-                plan: plan ?? null,
-                status: plan?.status ?? "review-required",
-                next: "安装预检与启用是两个步骤；打开 /panel 查看完整计划，安装完成后再执行启用。",
-            }, null, 2), "info");
+    }));
+}
+async function mcpManagerRows(state) {
+    const { items, installPrep } = await recommendedItems("mcp");
+    return items.map((item) => {
+        const id = String(item.id ?? "");
+        const plan = installPrep.find((candidate) => candidate.id === id);
+        const blocked = plan?.status === "blocked";
+        const dependencies = Array.isArray(plan?.dependencies)
+            ? plan.dependencies.filter((value) => typeof value === "string")
+            : [];
+        return {
+            id,
+            name: String(item.name ?? id),
+            description: String(item.description ?? ""),
+            ...(typeof item.sourceRef === "string" ? { sourceRef: item.sourceRef } : {}),
+            enabled: state.mcp.includes(id),
+            blocked,
+            ...(typeof plan?.blockedReason === "string" ? { reason: plan.blockedReason } : {}),
+            details: [
+                `传输：${String(item.transport ?? "未声明")} · 风险：${String(item.risk ?? "未声明")}`,
+                `版本：${String(plan?.ref ?? "未固定")} · 许可证：${String(plan?.license ?? "未核验")}`,
+                `依赖：${dependencies.length > 0 ? dependencies.join(", ") : "无已声明依赖"}`,
+            ],
+        };
+    });
+}
+function skillRowLabel(row) {
+    const state = row.blocked ? "× 阻断" : row.enabled ? "● 已启用" : row.installed ? "○ 未启用" : "↓ 未安装";
+    return `${state}  ${row.name}  [${row.id}]`;
+}
+async function setRecommendedSkillEnabled(root, requestedId, enabled, requestedScope) {
+    const id = normalizeRecommendedSkillId(requestedId);
+    const state = await readRecommendationState(root);
+    const scope = requestedScope ?? state.skillScopes?.[id] ?? "project";
+    if (enabled)
+        await validateModelInstalledRecommendedSkill(root, id, scope);
+    const current = new Set(state.skills);
+    if (enabled)
+        current.add(id);
+    else
+        current.delete(id);
+    state.skills = [...current];
+    state.skillScopes = { ...(state.skillScopes ?? {}), [id]: scope };
+    await saveRecommendationState(root, state);
+}
+function skillManagerItems(rows) {
+    return [
+        ...coreSkillNames().map((name) => ({
+            id: `core:${name}`,
+            name,
+            description: "PsyClaw 核心研究流程 Skill。",
+            status: "core",
+            sourceRef: "PsyClaw core",
+        })),
+        ...rows.map((row) => ({
+            id: row.id,
+            name: row.name,
+            description: row.description,
+            status: row.blocked ? "blocked" : row.enabled ? "enabled" : row.installed ? "disabled" : "missing",
+            ...(row.sourceRef === undefined ? {} : { sourceRef: row.sourceRef }),
+            details: [`安装位置：${skillScopeLabel(row.scope)}`],
+            ...(row.reason === undefined ? {} : { reason: row.reason }),
+        })),
+    ];
+}
+async function openSkillManager(ctx, rows) {
+    return ctx.ui.custom((tui, theme, keybindings, done) => (new SkillManagerComponent(skillManagerItems(rows), tui, theme, keybindings, done)));
+}
+function mcpManagerItems(rows) {
+    return rows.map((row) => ({
+        id: row.id,
+        name: row.name,
+        description: row.description,
+        status: row.blocked ? "blocked" : row.enabled ? "enabled" : "disabled",
+        configuredEnabled: row.enabled,
+        ...(row.sourceRef === undefined ? {} : { sourceRef: row.sourceRef }),
+        ...(row.reason === undefined ? {} : { reason: row.reason }),
+        details: row.details,
+    }));
+}
+async function openMcpManager(ctx, rows) {
+    return ctx.ui.custom((tui, theme, keybindings, done) => (new SkillManagerComponent(mcpManagerItems(rows), tui, theme, keybindings, done, {
+        title: "MCP 管理",
+        itemLabel: "MCP",
+        footer: "↑/↓ 移动 · Space 开启/关闭项目配置 · Enter 查看预检 · Esc 关闭",
+        enterAction: "install",
+        enabledText: "项目配置已开启；运行时仍需通过安装、信任和工具策略检查",
+        disabledText: "项目配置已关闭",
+        blockedText: "预检阻断；若配置曾开启，可按 Space 关闭",
+    })));
+}
+async function setRecommendedMcpEnabled(root, id, enabled) {
+    const state = await readRecommendationState(root);
+    const rows = await mcpManagerRows(state);
+    const row = rows.find((candidate) => candidate.id === id);
+    if (!row)
+        throw new Error(`未找到推荐 MCP: ${id}`);
+    if (enabled && row.blocked)
+        throw new Error(row.reason ?? `MCP 预检未通过: ${id}`);
+    const current = new Set(state.mcp);
+    if (enabled)
+        current.add(id);
+    else
+        current.delete(id);
+    state.mcp = [...current];
+    await saveRecommendationState(root, state);
+}
+function mcpInstallPlan(id, items, installPrep) {
+    const item = items.find((candidate) => candidate.id === id);
+    if (!item)
+        throw new Error(`未找到推荐 MCP: ${id}`);
+    const plan = installPrep.find((candidate) => candidate.id === id);
+    return {
+        schemaVersion: "psyclaw/recommendation-install/v1",
+        kind: "mcp",
+        id,
+        name: item.name,
+        sourceRef: item.sourceRef,
+        plan: plan ?? null,
+        status: plan?.status ?? "review-required",
+        next: "这里只展示固定来源、版本、许可证和依赖预检；完成受信任安装与注册后，MCP 才能在运行时调用。",
+    };
+}
+async function showMcpManager(args, ctx) {
+    const [verb, id] = args.trim().split(/\s+/).filter(Boolean);
+    if (verb && !["status", "enable", "disable", "install"].includes(verb)) {
+        throw new Error("Usage: /mcp [status|enable <id>|disable <id>|install <id>]");
+    }
+    if ((verb === "enable" || verb === "disable" || verb === "install") && !id) {
+        throw new Error(`Usage: /mcp ${verb} <id>`);
+    }
+    const catalog = await recommendedItems("mcp");
+    if (verb === "install") {
+        ctx.ui.notify(JSON.stringify(mcpInstallPlan(id, catalog.items, catalog.installPrep), null, 2), "info");
+        return;
+    }
+    if (verb === "enable" || verb === "disable") {
+        await setRecommendedMcpEnabled(ctx.cwd, id, verb === "enable");
+        ctx.ui.notify(`MCP ${id} 的项目配置已${verb === "enable" ? "开启" : "关闭"}；重启后重新检查安装、信任和工具策略`, "info");
+        return;
+    }
+    if (!ctx.hasUI || typeof ctx.ui.custom !== "function" || verb === "status") {
+        const rows = await mcpManagerRows(await readRecommendationState(ctx.cwd));
+        ctx.ui.notify(rows.map((row) => `${row.blocked ? "[!]" : row.enabled ? "[on]" : "[off]"} ${row.id} — ${row.name}${row.reason ? ` — ${row.reason}` : ""}`).join("\n"), "info");
+        return;
+    }
+    while (true) {
+        const rows = await mcpManagerRows(await readRecommendationState(ctx.cwd));
+        const action = await openMcpManager(ctx, rows);
+        if (action.type === "close")
             return;
+        const row = rows.find((candidate) => candidate.id === action.id);
+        if (!row)
+            continue;
+        if (action.type === "install") {
+            ctx.ui.notify(JSON.stringify(mcpInstallPlan(row.id, catalog.items, catalog.installPrep), null, 2), "info");
+            continue;
         }
-        if (actionChoice.startsWith("🌐")) {
-            ctx.ui.notify(`来源仓库: ${String(selectedItem.sourceRef ?? "无")}`, "info");
-            return;
+        if (action.type === "toggle") {
+            await setRecommendedMcpEnabled(ctx.cwd, row.id, action.enabled);
+            ctx.ui.notify(`${row.name} 的项目配置已${action.enabled ? "开启" : "关闭"}；重启后重新检查运行时可用性`, "info");
         }
+    }
+}
+function modelSkillInstallTask(root, row, scope) {
+    const target = recommendedSkillTarget(root, row.id, scope);
+    return [
+        `安装推荐 Skill：${row.name} (${row.id})。`,
+        `来源网址：${row.sourceRef}`,
+        `安装位置：${skillScopeLabel(scope)}。`,
+        `唯一允许的最终目标目录：${target}`,
+        "请使用当前会话的工具检查来源仓库并完成安装。不要写入其他 Skill 目录，不要修改 data/raw、.git 或研究产物。",
+        "目标目录最终必须直接包含有效 SKILL.md（YAML frontmatter 至少包含 name 和 description），不得包含 .git、符号链接、凭据或二进制大文件。",
+        "如果仓库包含多个 Skill，只安装与此推荐项相符的部分；如果它不是 Skill 或无法合理适配，停止并说明原因，不要伪造 SKILL.md。",
+        "安装完成后检查目标目录结构，并提醒用户执行 /skills 启用该项，再执行 /reload。",
+    ].join("\n");
+}
+async function chooseSkillScope(ctx) {
+    const projectLabel = skillScopeLabel("project");
+    const systemLabel = skillScopeLabel("user");
+    const selected = await ctx.ui.select("选择 Skill 安装位置", [projectLabel, systemLabel]);
+    if (selected === projectLabel)
+        return "project";
+    if (selected === systemLabel)
+        return "user";
+    return undefined;
+}
+async function queueModelSkillInstall(pi, ctx, row) {
+    if (!row.sourceRef)
+        throw new Error(`推荐 Skill 没有来源网址: ${row.id}`);
+    const scope = await chooseSkillScope(ctx);
+    if (!scope)
         return;
+    const approved = await ctx.ui.confirm("交给当前模型安装 Skill？", `${row.name}\n来源：${row.sourceRef}\n安装位置：${skillScopeLabel(scope)}\n目标目录：${recommendedSkillTarget(ctx.cwd, row.id, scope)}\n模型将检查仓库并使用文件与命令工具完成安装。`);
+    if (!approved)
+        return;
+    const state = await readRecommendationState(ctx.cwd);
+    state.skillScopes = { ...(state.skillScopes ?? {}), [row.id]: scope };
+    await saveRecommendationState(ctx.cwd, state);
+    pi.sendUserMessage(modelSkillInstallTask(ctx.cwd, row, scope), ctx.isIdle() ? {} : { deliverAs: "followUp" });
+    ctx.ui.notify(`已将 ${row.name} 的安装任务交给当前模型，目标为${skillScopeLabel(scope)}。安装完成后请在 /skills 中启用，再执行 /reload。`, "info");
+}
+async function showSkillManager(pi, args, ctx) {
+    const action = args.trim().split(/\s+/).filter(Boolean);
+    const verb = action[0];
+    const id = action[1];
+    if (verb && !["status", "enable", "disable", "install"].includes(verb)) {
+        throw new Error("Usage: /skills [status|enable <id>|disable <id>|install <id>]");
     }
-    // 2. 命令行显式参数调用
     if ((verb === "enable" || verb === "disable" || verb === "install") && !id) {
-        throw new Error(`Usage: /${kind} ${verb} <id>`);
+        throw new Error(`Usage: /skills ${verb} <id>`);
+    }
+    if (verb === "install") {
+        const row = (await skillManagerRows(ctx.cwd, await readRecommendationState(ctx.cwd))).find((candidate) => candidate.id === normalizeRecommendedSkillId(id));
+        if (!row)
+            throw new Error(`未找到推荐 Skill: ${id}`);
+        await queueModelSkillInstall(pi, ctx, row);
+        return;
     }
     if (verb === "enable" || verb === "disable") {
-        const item = items.find((candidate) => candidate.id === id);
-        if (!item)
-            throw new Error(`未找到推荐${stateKey === "skill" ? " Skill" : " MCP"}: ${id}`);
-        if (!ctx.hasUI || !(await ctx.ui.confirm(`${verb === "enable" ? "启用" : "禁用"}推荐${stateKey === "skill" ? " Skill" : " MCP"}`, `${String(item.name)} 的状态将写入当前项目配置。`)))
-            return;
-        const current = new Set(state[stateField]);
-        if (verb === "enable")
-            current.add(id);
-        else
-            current.delete(id);
-        state[stateField] = [...current];
-        await saveRecommendationState(ctx.cwd, state);
-        ctx.ui.notify(`${verb === "enable" ? "已启用" : "已禁用"} ${String(item.name)}（/reload 后生效；打开 /panel 可可视化管理）`, "info");
+        await setRecommendedSkillEnabled(ctx.cwd, id, verb === "enable");
+        ctx.ui.notify(`${verb === "enable" ? "已启用" : "已停用"} ${normalizeRecommendedSkillId(id)}。请运行 /reload 重新加载。`, "info");
         return;
     }
-    if (verb === "install") {
-        const item = items.find((candidate) => candidate.id === id);
-        const plan = installPrep.find((candidate) => candidate.id === id);
-        if (!item)
-            throw new Error(`未找到推荐${kind === "skills" ? " Skill" : " MCP"}: ${id}`);
-        ctx.ui.notify(JSON.stringify({ schemaVersion: "psyclaw/recommendation-install/v1", kind: stateKey, id, name: item.name, sourceRef: item.sourceRef, plan: plan ?? null, status: plan?.status ?? "review-required", next: "安装预检与启用是两个步骤；打开 /panel 查看完整计划，安装完成后再执行启用。" }, null, 2), "info");
+    if (!ctx.hasUI || typeof ctx.ui.custom !== "function" || verb === "status") {
+        const state = await readRecommendationState(ctx.cwd);
+        const rows = await skillManagerRows(ctx.cwd, state);
+        const lines = [
+            ...coreSkillNames().map((name) => `● 内置  ${name}`),
+            ...rows.map((row) => `${skillRowLabel(row)}${row.reason ? ` — ${row.reason}` : ""}`),
+        ];
+        ctx.ui.notify(lines.join("\n"), "info");
         return;
     }
-    // 3. 非交互模式或 status 命令回退输出
-    const enabled = new Set(state[stateField]);
-    const lines = items.map((item) => `${enabled.has(String(item.id)) ? "[on]" : "[off]"} ${String(item.id)} — ${String(item.name)}  (/${kind} enable|disable ${String(item.id)})`);
-    lines.push("", "可视化管理：打开 /panel（推荐 + 现有 Skill/MCP 的启用/停用）");
-    ctx.ui.notify(lines.length ? lines.join("\n") : `暂无推荐${kind === "skills" ? " Skill" : " MCP"}`, "info");
+    while (true) {
+        const state = await readRecommendationState(ctx.cwd);
+        const rows = await skillManagerRows(ctx.cwd, state);
+        const action = await openSkillManager(ctx, rows);
+        if (action.type === "close")
+            return;
+        const row = rows.find((candidate) => candidate.id === action.id);
+        if (!row)
+            continue;
+        if (action.type === "install") {
+            await queueModelSkillInstall(pi, ctx, row);
+            return;
+        }
+        if (action.type === "toggle") {
+            await setRecommendedSkillEnabled(ctx.cwd, row.id, action.enabled);
+            ctx.ui.notify(`已${action.enabled ? "启用" : "停用"} ${row.name}。请运行 /reload 重新加载。`, "info");
+        }
+    }
 }
 /** Run meta-analysis with the staged progress captured into a buffer (no TTY). */
 async function runMetaAnalysisStaged(root, target, nStudies) {
@@ -365,6 +532,13 @@ const WORKFLOW_RUNNERS = {
 export default function psyclawExtension(pi) {
     const developerCommands = process.env.PSYCLAW_DEVELOPER_COMMANDS === "1";
     const legacyTestApi = typeof pi.registerTool !== "function";
+    if (!legacyTestApi && typeof pi.on === "function")
+        pi.on("resources_discover", async (event, ctx) => {
+            const enabled = await enabledRecommendedSkillPaths(event.cwd);
+            for (const warning of enabled.warnings)
+                ctx.ui.notify(`PsyClaw Skill: ${warning}`, "warning");
+            return { skillPaths: enabled.paths };
+        });
     pi.registerCommand("research", {
         description: "创建可追溯的研究项目",
         handler: async (args, ctx) => {
@@ -417,10 +591,10 @@ export default function psyclawExtension(pi) {
     });
     if (!legacyTestApi)
         pi.registerCommand("skills", {
-            description: "查看并启用/禁用推荐 Skill",
+            description: "打开 Skill 安装与启用管理页",
             handler: async (args, ctx) => {
                 try {
-                    await showRecommended("skills", args, ctx);
+                    await showSkillManager(pi, args, ctx);
                 }
                 catch (error) {
                     await notifyError(ctx, error);
@@ -429,10 +603,10 @@ export default function psyclawExtension(pi) {
         });
     if (!legacyTestApi)
         pi.registerCommand("mcp", {
-            description: "查看并启用/禁用推荐 MCP",
+            description: "打开 MCP 配置与预检管理页",
             handler: async (args, ctx) => {
                 try {
-                    await showRecommended("mcp", args, ctx);
+                    await showMcpManager(args, ctx);
                 }
                 catch (error) {
                     await notifyError(ctx, error);
@@ -449,16 +623,23 @@ export default function psyclawExtension(pi) {
                         const [skills, mcps] = await Promise.all([recommendedItems("skills"), recommendedItems("mcp")]);
                         const skillLines = skills.items.slice(0, 8).map((item) => `Skill: ${String(item.id)} — ${String(item.name)}`);
                         const mcpLines = mcps.items.slice(0, 8).map((item) => `MCP: ${String(item.id)} — ${String(item.name)}`);
-                        ctx.ui.notify(["推荐安装入口", "", ...skillLines, ...mcpLines, "", "安装：/install skill|mcp <id>", "管理：/skills 或 /mcp", "也可以打开 /panel 查看推荐页面"].join("\n"), "info");
+                        const toolLines = skills.externalTools.slice(0, 8).map((item) => `外部工具: ${String(item.name)} — ${String(item.sourceRef ?? "请查看项目文档")}`);
+                        ctx.ui.notify(["推荐安装入口", "", ...skillLines, ...mcpLines, "", ...toolLines, "", "安装：/install skill|mcp <id>", "管理：/skills 或 /mcp", "外部工具不通过 Skill 安装器安装", "也可以打开 /panel 查看推荐页面"].join("\n"), "info");
                         return;
                     }
                     if (kind !== "skill" && kind !== "mcp")
                         throw new Error("Usage: /install skill|mcp <id>");
                     if (!id) {
-                        await showRecommended(kind === "skill" ? "skills" : "mcp", "", ctx);
+                        if (kind === "skill")
+                            await showSkillManager(pi, "", ctx);
+                        else
+                            await showMcpManager("", ctx);
                         return;
                     }
-                    await showRecommended(kind === "skill" ? "skills" : "mcp", `install ${id}`, ctx);
+                    if (kind === "skill")
+                        await showSkillManager(pi, `install ${id}`, ctx);
+                    else
+                        await showMcpManager(`install ${id}`, ctx);
                 }
                 catch (error) {
                     await notifyError(ctx, error);
@@ -529,6 +710,27 @@ export default function psyclawExtension(pi) {
                 ctx.ui.notify(`启动横幅宠物已${action === "on" ? "开启" : "关闭"}，下次启动生效`, "info");
             },
         });
+    const traceCommand = {
+        description: "导出脱敏使用路径，供 Langfuse 或 LangSmith 分析",
+        handler: async (args, ctx) => {
+            try {
+                if (args.trim())
+                    throw new Error("Usage: /trace");
+                const result = await exportTraces({ root: ctx.cwd });
+                ctx.ui.notify([
+                    "使用路径已导出（未上传）",
+                    `文件：${result.output}`,
+                    `轨迹：${result.traces}`,
+                    `步骤：${result.spans}`,
+                    "隐私：不含对话正文、工具参数、原始 ID 或绝对路径",
+                ].join("\n"), "info");
+            }
+            catch (error) {
+                await notifyError(ctx, error);
+            }
+        },
+    };
+    pi.registerCommand("trace", traceCommand);
     if (typeof pi.registerTool === "function") {
         pi.registerTool({
             name: "psyclaw_skill",