Merge branch 'main' into refactor/ui

# Conflicts:
#	src-tauri/src/services/skill.rs
#	src/components/skills/SkillsPage.tsx

src/components/skills/SkillsPage.tsx

@@ -6,6 +6,7 @@ import { toast } from "sonner";
 import { SkillCard } from "./SkillCard";
 import { RepoManagerPanel } from "./RepoManagerPanel";
 import { skillsApi, type Skill, type SkillRepo } from "@/lib/api/skills";
+import { formatSkillError } from "@/lib/errors/skillErrorParser";
 
 interface SkillsPageProps {
   onClose?: () => void;
@@ -33,10 +34,22 @@ export const SkillsPage = forwardRef<SkillsPageHandle, SkillsPageProps>(
           afterLoad(data);
         }
       } catch (error) {
-        toast.error(t("skills.loadFailed"), {
-          description:
-            error instanceof Error ? error.message : t("common.error"),
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+
+        // 传入 "skills.loadFailed" 作为标题
+        const { title, description } = formatSkillError(
+          errorMessage,
+          t,
+          "skills.loadFailed",
+        );
+
+        toast.error(title, {
+          description,
+          duration: 8000,
         });
+
+        console.error("Load skills failed:", error);
       } finally {
         setLoading(false);
       }
@@ -66,9 +79,25 @@ export const SkillsPage = forwardRef<SkillsPageHandle, SkillsPageProps>(
         toast.success(t("skills.installSuccess", { name: directory }));
         await loadSkills();
       } catch (error) {
-        toast.error(t("skills.installFailed"), {
-          description:
-            error instanceof Error ? error.message : t("common.error"),
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+
+        // 使用错误解析器格式化错误，传入 "skills.installFailed"
+        const { title, description } = formatSkillError(
+          errorMessage,
+          t,
+          "skills.installFailed",
+        );
+
+        toast.error(title, {
+          description,
+          duration: 10000, // 延长显示时间让用户看清
+        });
+
+        console.error("Install skill failed:", {
+          directory,
+          error,
+          message: errorMessage,
         });
       }
     };
@@ -79,9 +108,25 @@ export const SkillsPage = forwardRef<SkillsPageHandle, SkillsPageProps>(
         toast.success(t("skills.uninstallSuccess", { name: directory }));
         await loadSkills();
       } catch (error) {
-        toast.error(t("skills.uninstallFailed"), {
-          description:
-            error instanceof Error ? error.message : t("common.error"),
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+
+        // 使用错误解析器格式化错误，传入 "skills.uninstallFailed"
+        const { title, description } = formatSkillError(
+          errorMessage,
+          t,
+          "skills.uninstallFailed",
+        );
+
+        toast.error(title, {
+          description,
+          duration: 10000,
+        });
+
+        console.error("Uninstall skill failed:", {
+          directory,
+          error,
+          message: errorMessage,
         });
       }
     };

src/i18n/locales/en.json

@@ -689,6 +689,34 @@
     "installFailed": "Failed to install",
     "uninstallSuccess": "Skill {{name}} uninstalled",
     "uninstallFailed": "Failed to uninstall",
+    "error": {
+      "skillNotFound": "Skill not found: {{directory}}",
+      "missingRepoInfo": "Missing repository info (owner or name)",
+      "downloadTimeout": "Download repository {{owner}}/{{name}} timeout ({{timeout}}s)",
+      "downloadTimeoutHint": "Please check network connection or retry later",
+      "skillPathNotFound": "Skill path '{{path}}' not found in repository {{owner}}/{{name}}",
+      "skillDirNotFound": "Skill directory not found: {{path}}",
+      "emptyArchive": "Downloaded archive is empty",
+      "downloadFailed": "Download failed: HTTP {{status}}",
+      "allBranchesFailed": "All branches failed, tried: {{branches}}",
+      "httpError": "HTTP error {{status}}",
+      "http403": "GitHub access restricted, possibly rate limited",
+      "http404": "Repository or branch not found, please check URL",
+      "http429": "Too many requests, please wait and retry",
+      "parseMetadataFailed": "Failed to parse skill metadata",
+      "getHomeDirFailed": "Unable to get user home directory",
+      "networkError": "Network error",
+      "fsError": "File system error",
+      "unknownError": "Unknown error",
+      "suggestion": {
+        "checkNetwork": "Please check network connection",
+        "checkProxy": "Consider configuring HTTP proxy",
+        "retryLater": "Please retry later",
+        "checkRepoUrl": "Please check repository URL and branch name",
+        "checkDiskSpace": "Please check disk space",
+        "checkPermission": "Please check directory permissions"
+      }
+    },
     "repo": {
       "title": "Manage Skill Repositories",
       "description": "Add or remove GitHub skill repository sources",

src/i18n/locales/zh.json

@@ -689,6 +689,34 @@
     "installFailed": "安装失败",
     "uninstallSuccess": "技能 {{name}} 已卸载",
     "uninstallFailed": "卸载失败",
+    "error": {
+      "skillNotFound": "技能不存在：{{directory}}",
+      "missingRepoInfo": "缺少仓库信息（owner 或 name）",
+      "downloadTimeout": "下载仓库 {{owner}}/{{name}} 超时（{{timeout}}秒）",
+      "downloadTimeoutHint": "请检查网络连接或稍后重试",
+      "skillPathNotFound": "仓库 {{owner}}/{{name}} 中未找到技能路径 '{{path}}'",
+      "skillDirNotFound": "技能目录不存在：{{path}}",
+      "emptyArchive": "下载的压缩包为空",
+      "downloadFailed": "下载失败：HTTP {{status}}",
+      "allBranchesFailed": "所有分支下载失败，尝试了：{{branches}}",
+      "httpError": "HTTP 错误 {{status}}",
+      "http403": "GitHub 访问受限，可能是请求频率过高",
+      "http404": "仓库或分支不存在，请检查地址",
+      "http429": "请求过于频繁，请等待后重试",
+      "parseMetadataFailed": "解析技能元数据失败",
+      "getHomeDirFailed": "无法获取用户主目录",
+      "networkError": "网络错误",
+      "fsError": "文件系统错误",
+      "unknownError": "未知错误",
+      "suggestion": {
+        "checkNetwork": "请检查网络连接",
+        "checkProxy": "建议配置 HTTP 代理",
+        "retryLater": "请稍后重试",
+        "checkRepoUrl": "请检查仓库地址和分支名称",
+        "checkDiskSpace": "请检查磁盘空间",
+        "checkPermission": "请检查目录权限"
+      }
+    },
     "repo": {
       "title": "管理技能仓库",
       "description": "添加或删除 GitHub 技能仓库源",

src/lib/errors/skillErrorParser.ts

@@ -0,0 +1,104 @@
+import { TFunction } from "i18next";
+
+/**
+ * 结构化错误对象
+ */
+export interface SkillError {
+  code: string;
+  context: Record<string, string>;
+  suggestion?: string;
+}
+
+/**
+ * 尝试解析后端返回的错误字符串
+ * 如果是 JSON 格式，返回结构化错误；否则返回 null
+ */
+export function parseSkillError(errorString: string): SkillError | null {
+  try {
+    const parsed = JSON.parse(errorString);
+    if (parsed.code && parsed.context) {
+      return parsed as SkillError;
+    }
+  } catch {
+    // 不是 JSON 格式，返回 null
+  }
+  return null;
+}
+
+/**
+ * 将错误码映射到 i18n key
+ */
+function getErrorI18nKey(code: string): string {
+  const mapping: Record<string, string> = {
+    SKILL_NOT_FOUND: "skills.error.skillNotFound",
+    MISSING_REPO_INFO: "skills.error.missingRepoInfo",
+    DOWNLOAD_TIMEOUT: "skills.error.downloadTimeout",
+    DOWNLOAD_FAILED: "skills.error.downloadFailed",
+    SKILL_DIR_NOT_FOUND: "skills.error.skillDirNotFound",
+    EMPTY_ARCHIVE: "skills.error.emptyArchive",
+    GET_HOME_DIR_FAILED: "skills.error.getHomeDirFailed",
+  };
+
+  return mapping[code] || "skills.error.unknownError";
+}
+
+/**
+ * 将建议码映射到 i18n key
+ */
+function getSuggestionI18nKey(suggestion: string): string {
+  const mapping: Record<string, string> = {
+    checkNetwork: "skills.error.suggestion.checkNetwork",
+    checkProxy: "skills.error.suggestion.checkProxy",
+    retryLater: "skills.error.suggestion.retryLater",
+    checkRepoUrl: "skills.error.suggestion.checkRepoUrl",
+    checkPermission: "skills.error.suggestion.checkPermission",
+    http403: "skills.error.http403",
+    http404: "skills.error.http404",
+    http429: "skills.error.http429",
+  };
+
+  return mapping[suggestion] || suggestion;
+}
+
+/**
+ * 格式化技能错误为用户友好的消息
+ * @param errorString 后端返回的错误字符串
+ * @param t i18next 翻译函数
+ * @param defaultTitle 默认标题的 i18n key（如 "skills.installFailed"）
+ * @returns 包含标题和描述的对象
+ */
+export function formatSkillError(
+  errorString: string,
+  t: TFunction,
+  defaultTitle: string = "skills.installFailed"
+): { title: string; description: string } {
+  const parsedError = parseSkillError(errorString);
+
+  if (!parsedError) {
+    // 如果不是结构化错误，返回原始错误字符串
+    return {
+      title: t(defaultTitle),
+      description: errorString || t("common.error"),
+    };
+  }
+
+  const { code, context, suggestion } = parsedError;
+
+  // 获取错误消息的 i18n key
+  const errorKey = getErrorI18nKey(code);
+
+  // 构建描述（错误消息 + 建议）
+  let description = t(errorKey, context);
+
+  // 如果有建议，追加到描述中
+  if (suggestion) {
+    const suggestionKey = getSuggestionI18nKey(suggestion);
+    const suggestionText = t(suggestionKey);
+    description += `\n\n${suggestionText}`;
+  }
+
+  return {
+    title: t(defaultTitle),
+    description,
+  };
+}