dsh-skill-mcp-market 0.3.0 → 0.3.2

package/README.md

@@ -1,10 +1,144 @@
 # dsh-skill-mcp-market
 
-DSH 的**技能市场**与 **MCP 连接器市场**：装完即刻生效，安装路径由用户决定，无需重启 DSH。
+DSH 的**技能市场**与 **MCP 连接器市场**：浏览实时技能源、装 SKILL.md 技能、装 MCP 连接器，装完立刻能用，安装路径由你自己定，全程不用重启 DSH。
 
 - 提供的工具：12 个 `market_* / skill_market_* / mcp_market_*`（见下表）
-- 安装位置：`~/.dsh/market/settings.json`（可用 `market_set_paths` 改）
+- 设置文件：`~/.dsh/market/settings.json`（可用 `market_set_paths` 改）
 - 默认技能目录：`~/.dsh/market/skills`；默认 MCP 目录：`~/.dsh/market/mcp`
+- 左侧面板：**「SKILL技能&MCP连接器」**
+
+## 截图
+
+真机截图（DSH 桌面版，左侧菜单「SKILL技能&MCP连接器」）。
+
+### 技能市场
+
+顶部按来源切换（`skills.sh` / `clawhub` / `skillsmp` / `trusttools` / `browse.sh` / `lobehub-agent` / `skillhub`），卡片上直接「预览 / 安装」：
+
+![技能市场：来源筛选与卡片](docs/screenshots/panel-skills.png)
+
+> 「MCP 连接器」「已安装」「路径」三个页签的截图待补。
+
+## 安装
+
+已发布到 npm：**`dsh-skill-mcp-market`**（MIT，公共包，无需登录）。
+
+### 前置条件
+
+- 桌面版 DSH：本插件复用的是 `app.asar` 里官方技能/MCP 插件，纯 Node 环境跑不了。
+- profile 目录：`~/.dsh/profiles/<profile>`，桌面版一般是 `~/.dsh/profiles/desktop`；
+  Windows 下是 `C:\Users\<你>\.dsh\profiles\desktop`。
+
+### 方式一：`dsh` CLI 安装（推荐）
+
+DSH 桌面版自带 CLI，profile 的依赖由它**内置的 pnpm** 管理（profile 目录里有 `pnpm-lock.yaml`、`pnpm-workspace.yaml`，`nodeLinker: hoisted`）：
+
+```bash
+dsh plugin --profile desktop add dsh-skill-mcp-market
+```
+
+它等价于在 `~/.dsh/profiles/desktop` 里跑 `pnpm add`，多做了三件事：用安装目录里那份 pnpm（不依赖你本机的 pnpm）、对 profile 的 `package.json` 加文件锁（避免与正在跑的 DSH 抢写）、检查插件与当前 DSH 版本是否兼容。
+
+`dsh` 不在 PATH 时用绝对路径：
+
+```bat
+"D:\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-skill-mcp-market
+```
+
+装完依赖还差一步——**让 DSH 加载它**：把包名加进该 profile `package.json` 的 `dsh.profile.bundles`：
+
+```json
+{
+  "dependencies": {
+    "dsh-skill-mcp-market": "^0.3.0"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "@deepseek-ai/dsh-base",
+        "@deepseek-ai/dsh-web-app",
+        "dsh-skill-mcp-market"
+      ]
+    }
+  }
+}
+```
+
+包自带 `dsh.bundle.patch`（指向 `cordis.patch.yml`），进了 `bundles` 就会自动插入插件行，**不用手写 `cordis.patch.yml`**。
+
+改完 `bundles` 需要**重启一次 DSH** 让插件被加载；此后装技能、装 MCP 都不再需要重启。
+
+不想动 `bundles` 的话，也可以在 profile 的 `cordis.patch.yml` 末尾手写一行：
+
+```yaml
+- insert:
+    - id: dsh-skill-mcp-market
+      name: dsh-skill-mcp-market
+      config:
+        skillDirs: []
+        mcpDirs: []
+        shippedRoot: ""
+```
+
+清掉再装：`dsh plugin --profile desktop remove dsh-skill-mcp-market`（同时从 `bundles` 里删掉包名）。
+
+### 方式二：应用内安装（plugin_manager / 插件面板）
+
+- `plugin_manager`：`action: install_bundle`，`target` 填 `dsh-skill-mcp-market` 会「装依赖 + 加进 bundles」；`action: set_bundle` 只切换已安装包的启用状态。
+- 设置 → 插件 里也能看到并启用它。
+- 这条路径会执行包内代码，需要 Full access 或审批。
+
+### 方式三：npm（不推荐）
+
+profile 的 `node_modules` 是 pnpm 管的：`npm i` 会额外写 `package-lock.json`、打乱 `node_modules` 布局，下一次 `pnpm install` 可能把它清掉。只有在没有 `dsh` CLI 的机器上才这样装：
+
+```bash
+cd ~/.dsh/profiles/desktop
+npm i dsh-skill-mcp-market      # 之后仍需把包名加入 dsh.profile.bundles
+```
+
+### 方式四：固定版本 / 多 profile / 本地开发
+
+```bash
+dsh plugin --profile desktop add dsh-skill-mcp-market@0.3.0            # 固定版本
+dsh plugin --profile desktop why dsh-skill-mcp-market                  # 看装的哪个版本、谁引入的
+dsh plugin --profile desktop add link:/path/to/dsh-market                       # 本地开发（换成你的仓库路径）
+```
+
+`link:` 情况下 `bundles` 里仍写包名；改完源码用 `plugin_manager set_plugin` 把 `include:dsh-skill-mcp-market` 关一次再开一次即可重挂（见「开发」）。同一个包可以装进多个 profile，各自独立配置。
+
+
+### 安装后确认
+
+1. 左侧菜单出现 **「SKILL技能&MCP连接器」**；
+2. 「技能市场」「MCP 连接器」两个页签都能出卡片，顶部来源筛选可用：`skills.sh` / `clawhub` / `skillsmp` / `trusttools` / `browse.sh` / `lobehub-agent` / `skillhub`；
+3. 让模型调 `market_get_settings`，应返回两个目录、provider 挂载状态、官方包解析结果、可用来源；
+4. 12 个 `market_*` / `skill_market_*` / `mcp_market_*` 工具都在。
+
+### 首次使用：决定装到哪里
+
+默认装在 `~/.dsh/market/` 下。想换位置（例如并入 DSH 自带技能目录，让别的 profile 也能看到）：
+
+```
+market_set_paths({ skillDirs: ["C:/Users/你/.dsh/skills"], mcpDirs: ["C:/Users/你/.dsh/market/mcp"] })
+```
+
+支持 `~`、`$DSH_HOME`、`%ENV%` 和相对 profile 的路径；改完 provider 与 MCP 立即重挂。
+
+需要密钥的 MCP 用 `${ENV_VAR}` 占位，值放环境变量：
+
+```json
+{ "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } }
+```
+
+### 升级与卸载
+
+```bash
+dsh plugin --profile desktop add dsh-skill-mcp-market@latest   # 升级，重启 DSH 生效
+dsh plugin --profile desktop remove dsh-skill-mcp-market       # 卸载；再把这个包名从 dsh.profile.bundles 里删掉
+```
+
+卸载插件不会删掉已装好的技能与 MCP 定义（它们在 `~/.dsh/market/` 下，是独立数据）；要清理请用 `skill_market_uninstall` / `mcp_market_uninstall`。
 
 ## 为什么能"不重启就生效"
 
@@ -34,25 +168,39 @@ DSH 本来就有技能运行时和 MCP 运行时，缺的只是市场这一层
 | `mcp_market_probe` | 等 MCP 发布工具并回报 |
 | `mcp_market_uninstall` | 卸载（定义移入 `.trash/`） |
 
+## 数据源
+
+| 源 | 说明 |
+|---|---|
+| **MCP 官方注册表** | `registry.modelcontextprotocol.io`，免费、实时的 MCP 目录，自带真实启动方式（npm / streamable-http） |
+| `skills.sh` | 技能索引，支持页面 URL 与裸 `owner/repo`；搜索接口要求 ≥2 字符，空搜索回退到首页推荐 |
+| `skillsmp` | 带反爬（Cloudflare），走 python→curl→fetch 三级取数 |
+| `browse.sh` | 启动预热 + 内存缓存，冷启动超时不缓存空结果 |
+| `trusttools` | `ai.trusttools.cn/api/skills/search`（POST）；该站会丢弃本进程的 TLS 握手，走 python → curl → fetch 三级通道 |
+| `clawhub` / `lobehub-agent` / `skillhub` | 其余实时技能源 |
+| `github` | 直接给仓库或 `@ref`；jsDelivr 列树失败时回退 GitHub contents API 与 codeload tarball |
+
 ## 目录结构
 
 ```
 dsh-skill-mcp-market/
 ├─ package.json          # dsh.bundle.patch 指向 cordis.patch.yml
-├─ cordis.patch.yml      # 插入一行 dsh-market 插件
+├─ cordis.patch.yml      # 插入一行 dsh-skill-mcp-market 插件
 ├─ index.js              # 插件入口：挂载 provider + 注册 12 个工具
+├─ client.js             # Web 面板「SKILL技能&MCP连接器」
 ├─ src/
 │  ├─ home.js            # 路径解析与 settings.json 读写
 │  ├─ shipped.js         # 从 app.asar 解析并 import 官方插件包
+│  ├─ http.js            # python→curl→fetch 三级取数（绕 TLS 指纹 / 系统代理）
 │  ├─ frontmatter.js     # SKILL.md frontmatter 解析（无依赖）
-│  ├─ github.js          # jsDelivr 列树 + raw/CDN 取文件（绕开被墙的 GitHub API）
+│  ├─ github.js          # jsDelivr 列树 + raw/CDN 取文件，失败回退 contents API / tarball
+│  ├─ extra-sources.js   # skillsmp 等额外源
+│  ├─ mcp-registry.js    # MCP 官方注册表适配 + 内置兜底条目
 │  ├─ skillhub.js        # SkillHub 公共 API 适配
 │  ├─ skills.js          # 搜索聚合 / 安装 / 列出 / 卸载
+│  ├─ sources.js         # 各源适配与缓存
 │  ├─ mcp.js             # MCP 定义扫描、动态挂载、启停、探活
 │  └─ ...
-├─ catalog/
-│  ├─ skills.json        # 17 条精选技能（从 anthropics/skills 生成）
-│  └─ mcp.json           # 8 条标准 MCP 定义
 ├─ locale/{en,zh}.json   # 插件管理器里的标题与描述
 └─ icon.svg
 ```
@@ -61,11 +209,16 @@ dsh-skill-mcp-market/
 
 - DSH 的 `dsh-mcp-client` 只有 `stdio` 与 `streamable-http`，**没有 SSE**；上游只给 SSE 地址的 MCP 装不上。
 - 技能发现是**一层深**：只认 `<root>/<name>/SKILL.md` 和 `<root>/<name>.md`。
-- 精选 MCP 定义是标准写法，能否真跑由安装时的探活结果决定，不预先保证。
+- MCP 定义是标准写法，能否真跑由安装时的探活结果决定，不预先保证；注册表里标记为必填的环境变量会在安装时提示。
 - 市场不伪造下载量/热度：上游没给就显示 0。
+- LobeHub 页面会间歇返回 `402 payment_required`，所以它只作为次要源；MCP 目录不可达时按「上次缓存 → 内置条目」降级，并在面板上提示可直接按名称安装。
 
 ## 开发
 
-改完代码后，`plugin_manager` 无法原地替换模块。用 `plugin_manager set_plugin` 把 `include:dsh-skill-mcp-market` 关一次再开一次，新代码即生效（本机已验证）。
+改完代码后，`plugin_manager` 无法原地替换模块。用 `plugin_manager set_plugin` 把 `include:dsh-skill-mcp-market` 关一次再开一次，新代码即生效（已在本机验证）。
+
+冒烟脚本在 `../tools/`：`smoke-market.mjs`（技能安装/卸载、MCP 配置映射）、`smoke-market-fixes.mjs`（注册表搜索、裸 `owner/repo`、skillsmp）、`smoke-sources.mjs`（各源 provider 行为）、`smoke-demo-mcp.mjs`（MCP 协议自检）。
+
+## 许可
 
-冒烟脚本在 `../tools/`：`smoke-market.mjs`（技能安装/卸载、MCP 配置映射）、`smoke-demo-mcp.mjs`（MCP 协议自检）。
+MIT

package/client.js

@@ -172,14 +172,19 @@ window.__ModuleLoader__.load({
             pageSize: (options && options.size) || 24,
           });
           setSkills(d.items || []);
+          const hints = (d.hints || []).filter(Boolean);
           if (!(d.items || []).length) {
-            // An empty market is either "no match" or "upstream refused us"; say which.
+            // An empty market is either "no match", "needs a keyword" or "upstream refused us".
             const reasons = (d.sourceErrors || []).length
               ? d.sourceErrors
-              : (d.degraded || []).length
-                ? [`部分来源不可用：${d.degraded.map((x) => x.source).join(', ')}`]
-                : ['没有找到匹配的技能。'];
+              : hints.length
+                ? hints
+                : (d.degraded || []).length
+                  ? [`部分来源不可用：${d.degraded.map((x) => x.source).join(', ')}`]
+                  : ['没有找到匹配的技能。'];
             setNotice(reasons.join('；'));
+          } else if (hints.length) {
+            setNotice(hints.join('；'));
           } else if ((d.degraded || []).length) {
             setNotice(`部分来源不可用：${d.degraded.map((x) => x.source).join(', ')}`);
           } else {

package/index.js

@@ -233,8 +233,8 @@ export async function apply(ctx, config = {}) {
   const marketCache = makeCache(join(dirname(settingsPath()), "cache"));
 
   // ---------------------------------------------------------------- skill provider
-  // We own the provider so `disabledSkills` (Hermes' config.yaml `skills.disabled`
-  // equivalent) is a real configuration item instead of a directory trick.
+  // We own the provider so `disabledSkills` (a `skills.disabled: [name]` list, as used by
+  // several agent runtimes) is a real configuration item instead of a directory trick.
   let disposeProvider = null;
   let invalidateSkills = null;
   let skillProviderError = "";
@@ -301,8 +301,8 @@ export async function apply(ctx, config = {}) {
     }
   }, "dsh-market.lifecycle");
 
-  /** Enable/disable a skill by writing settings.disabledSkills, mirroring Hermes'
-   *  config.yaml `skills.disabled` + prompt-cache invalidation. */
+  /** Enable/disable a skill by writing settings.disabledSkills: the name stays on disk but
+   *  leaves the catalog, then the prompt cache is invalidated. */
   async function setSkillEnabled(slug, enabled) {
     const key = String(slug || "").trim().toLowerCase();
     if (!key) throw new Error("slug 不能为空");

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-skill-mcp-market",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
-  "description": "SKILL skill market and MCP connector market for DeepSeek Harness: browse live catalogues, install SKILL.md skills and MCP servers, and use them without restarting DSH.",
+  "description": "DSH 技能市场与 MCP 连接器市场：浏览实时技能源，一键安装 SKILL.md 技能与 MCP 连接器，装完即刻可用、无需重启。SKILL & MCP marketplace for DeepSeek Harness — browse live sources, install skills and MCP connectors, effective immediately.",
   "license": "MIT",
   "keywords": [
     "dsh",

package/src/extra-sources.js

@@ -5,7 +5,7 @@
 //   skillsmp  — skillsmp.com/api/skills (paged search; Cloudflare-fronted, needs the curl
 //               transport because this process's own TLS fingerprint is refused)
 // modelscope (api/v1/dolphin/skills → 404) is intentionally absent: the endpoint is gone.
-import { getJsonEscalating } from "./http.js";
+import { getJsonEscalating, postJsonEscalating } from "./http.js";
 
 const UA = { "User-Agent": "dsh-skill-mcp-market/0.4", accept: "application/json" };
 
@@ -60,11 +60,13 @@ export async function searchClawHub({ query = "", pageSize = 24 }) {
 
 // ---------------------------------------------------------------- trusttools
 export async function searchTrustTools({ query = "", pageSize = 24 }) {
-  const data = await postJson("https://ai.trusttools.cn/api/skills/search", {
-    q: query,
-    page: 1,
-    pageSize,
-  });
+  // ai.trusttools.cn drops this process's TLS handshake (same class of failure as
+  // skillsmp), so the POST goes through python → curl → fetch instead of plain fetch.
+  const data = await postJsonEscalating(
+    "https://ai.trusttools.cn/api/skills/search",
+    { q: query, page: 1, pageSize },
+    { timeoutMs: 25000 },
+  );
   const rows = Array.isArray(data.data) ? data.data : [];
   const items = rows.map((raw) => {
     const repo = String(raw.repo_url || "").replace(/^https?:\/\/github\.com\//i, "").replace(/\.git$/i, "");

package/src/home.js

@@ -39,8 +39,8 @@ export function defaultSettings() {
     skillDirs: [join(home, "market", "skills")],
     // Where MCP server definitions (<serverName>.json) live.
     mcpDirs: [join(home, "market", "mcp")],
-    // DSH equivalent of Hermes' config.yaml `skills.disabled`: names that stay on disk but
-    // are hidden from the catalog. Absent from this list means enabled.
+    // The `skills.disabled` idea as a DSH config item: names that stay on disk but are
+    // hidden from the catalog. Absent from this list means enabled.
     disabledSkills: [],
     // Extra root that holds the shipped dsh packages (app.asar). Empty means auto-detect.
     shippedRoot: "",

package/src/http.js

@@ -107,6 +107,14 @@ const PY_FETCH = [
   "    sys.stdout.write(response.read().decode('utf-8', 'replace'))",
 ].join("\n");
 
+const PY_POST = [
+  "import sys, json, urllib.request",
+  "url, body, headers, timeout = sys.argv[1], sys.argv[2], json.loads(sys.argv[3]), float(sys.argv[4])",
+  "request = urllib.request.Request(url, data=body.encode('utf-8'), headers=headers, method='POST')",
+  "with urllib.request.urlopen(request, timeout=timeout) as response:",
+  "    sys.stdout.write(response.read().decode('utf-8', 'replace'))",
+].join("\n");
+
 async function isPython(binary) {
   // A relocatable CPython can be present but unusable (its stdlib may be pinned to the
   // build machine, e.g. "AssertionError: SRE module mismatch"), so the probe imports what
@@ -230,3 +238,84 @@ export async function getJsonEscalating(url, { headers = {}, timeoutMs = 20000 }
   }
   throw new Error(errors[0] || "所有传输方式都失败");
 }
+
+/** POST a JSON body through curl (some hosts only answer a non-Node TLS client). */
+export async function curlPostText(url, body, { headers = {}, timeoutMs = 15000 } = {}) {
+  const merged = { ...BROWSER_HEADERS, "content-type": "application/json", ...headers };
+  const payload = JSON.stringify(body ?? {});
+  const args = [
+    "-s", "-S", "--compressed",
+    "--max-time", String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+    "-X", "POST",
+    "--data-binary", "@-",
+  ];
+  for (const [name, value] of Object.entries(merged)) args.push("-H", `${name}: ${value}`);
+  args.push(url);
+  return new Promise((resolve, reject) => {
+    const child = execFile("curl.exe", args, { maxBuffer: 16 * 1024 * 1024, timeout: timeoutMs + 5000, windowsHide: true },
+      (error, stdout) => (error ? reject(error) : resolve(String(stdout || ""))));
+    if (child.stdin) {
+      child.stdin.end(payload);
+    }
+  });
+}
+
+/** POST a JSON body through the Python transport. */
+export async function pythonPostText(url, body, { headers = {}, timeoutMs = 20000 } = {}) {
+  const python = await findPython();
+  if (!python) throw new Error("没有可用的 Python 解释器，无法通过该传输取数");
+  return new Promise((resolve, reject) => {
+    execFile(
+      python,
+      ["-c", PY_POST, url, JSON.stringify(body ?? {}), JSON.stringify({ ...BROWSER_HEADERS, "content-type": "application/json", ...headers }), String(timeoutMs / 1000)],
+      {
+        timeout: timeoutMs + 5000,
+        windowsHide: true,
+        maxBuffer: 16 * 1024 * 1024,
+        env: { ...process.env, PYTHONIOENCODING: "utf-8", PYTHONUTF8: "1" },
+      },
+      (error, stdout, stderr) => {
+        if (error) reject(new Error(`python POST 失败：${String(stderr || error.message).slice(0, 200)}`));
+        else resolve(String(stdout));
+      },
+    );
+  });
+}
+
+/**
+ * POST escalation for hosts whose edge drops this process's TLS handshake: python → curl →
+ * Node fetch, first JSON response wins.
+ */
+export async function postJsonEscalating(url, body, { headers = {}, timeoutMs = 20000 } = {}) {
+  const parse = (text) => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new Error(`上游返回的不是 JSON：${String(text).slice(0, 80).replace(/\s+/g, " ")}`);
+    }
+  };
+  const attempts = [
+    async () => parse(await pythonPostText(url, body, { headers, timeoutMs })),
+    async () => parse(await curlPostText(url, body, { headers, timeoutMs })),
+    async () => {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { ...BROWSER_HEADERS, "content-type": "application/json", ...headers },
+        body: JSON.stringify(body ?? {}),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!response.ok) throw new Error(`HTTP ${response.status} for ${url}`);
+      return response.json();
+    },
+  ];
+  const errors = [];
+  for (const attempt of attempts) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      return await attempt();
+    } catch (error) {
+      errors.push(String((error && error.message) || error).slice(0, 120));
+    }
+  }
+  throw new Error(errors[0] || "所有传输方式都失败");
+}

package/src/provider.js

@@ -1,8 +1,8 @@
 // Own skill provider: scans user-configured directories, honours the disabled list,
 // and invalidates the catalog whenever the directories or the settings change.
 //
-// This replaces the shipped filesystem provider so that `disabledSkills` (the DSH
-// equivalent of Hermes' config.yaml `skills.disabled`) is a real configuration item.
+// This replaces the shipped filesystem provider so that `disabledSkills` becomes a real
+// configuration item rather than a directory trick.
 import { readFile, readdir, stat } from "node:fs/promises";
 import { existsSync, watch } from "node:fs";
 import { join } from "node:path";

package/src/sources.js

@@ -54,11 +54,58 @@ export function makeCache(dir) {
 }
 
 // ------------------------------------------------------------------ skills.sh
+/**
+ * skills.sh has no listing API, but its home page links the skills it is featuring right
+ * now. Scrape those links so an empty search box still shows a real catalogue instead of
+ * a blank market.
+ */
+export async function browseSkillsSh({ pageSize = 24, cache } = {}) {
+  let rows = cache ? await cache.get("skills_sh_home", 30 * 60 * 1000) : null;
+  if (!Array.isArray(rows) || rows.length === 0) {
+    const html = await fetchText("https://www.skills.sh/", 25000);
+    const seen = new Set();
+    rows = [];
+    for (const match of html.matchAll(/\/([A-Za-z0-9_.-]+)\/skills\/([A-Za-z0-9_.-]+)/g)) {
+      const key = `${match[1]}/${match[2]}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      rows.push({ owner: `${match[1]}/skills`, slug: match[2] });
+    }
+    if (rows.length > 0 && cache) await cache.put("skills_sh_home", rows);
+  }
+  const items = rows.slice(0, pageSize).map(({ owner, slug }) => ({
+    id: `skills.sh:${owner}/${slug}`,
+    slug,
+    name: slug,
+    description: "",
+    source: "skills.sh",
+    sourceLabel: "skills.sh",
+    owner,
+    homepage: `https://www.skills.sh/${owner}/${slug}`,
+    upstreamUrl: owner,
+    skillDir: "",
+    installs: 0,
+    installable: true,
+  }));
+  return { source: "skills.sh", items, total: rows.length };
+}
+
 /** skills.sh exposes a real JSON search API (Algolia-backed). */
 export async function searchSkillsSh({ query = "", pageSize = 24, cache }) {
-  // The upstream API rejects queries shorter than 2 characters; browsing with an empty
-  // box is a legitimate state, so return an empty page with a hint instead of failing.
+  // The upstream search API rejects queries shorter than 2 characters. Browsing with an
+  // empty box is a legitimate state, so fall back to the home-page highlights and say so.
   if (query.trim().length < 2) {
+    try {
+      const browse = await browseSkillsSh({ pageSize, cache });
+      if (browse.items.length > 0) {
+        return {
+          ...browse,
+          hint: "未输入关键词：以下是 skills.sh 首页当前推荐的技能，输入至少 2 个字符可精确搜索",
+        };
+      }
+    } catch {
+      // fall through to the plain hint below
+    }
     return { source: "skills.sh", items: [], total: 0, hint: "skills.sh 需要至少 2 个字符的关键词" };
   }
   const url = `https://www.skills.sh/api/search?q=${encodeURIComponent(query)}&limit=${pageSize}`;
@@ -244,10 +291,12 @@ export async function searchSkills({ query, source = "all", pageSize = 24, cache
   const wanted = source === "all" ? ALL_SOURCES : [source];
   const items = [];
   const degraded = [];
+  const hints = [];
   for (const name of wanted) {
     try {
       if (name === "skills.sh") {
         const result = await searchSkillsSh({ query, pageSize, cache });
+        if (result.hint) hints.push(`skills.sh：${result.hint}`);
         items.push(...result.items);
       } else if (name === "clawhub") {
         const result = await searchClawHub({ query, pageSize });
@@ -287,8 +336,10 @@ export async function searchSkills({ query, source = "all", pageSize = 24, cache
       ? []
       : degraded.length
         ? degraded.map((entry) => `${entry.source} 不可达：${entry.error}`.slice(0, 200))
-        : ["所选市场暂时没有取到数据，可能是上游不可达或响应超时，请稍后重试"];
-  return { items, degraded, sourceErrors, total: items.length };
+        : hints.length
+          ? hints
+          : ["所选市场暂时没有取到数据，可能是上游不可达或响应超时，请稍后重试"];
+  return { items, degraded, hints, sourceErrors, total: items.length };
 }
 
 /**