dsh-plugin-labels 0.8.0 → 0.9.0

package/README.md

@@ -3,20 +3,23 @@
 [![CI](https://github.com/qyy2005/dsh-plugin-labels/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/qyy2005/dsh-plugin-labels/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-给 DSH（DeepSeek Harness）**已安装插件**配「中文名 + 一句话说明」：官方「插件」页的已安装插件行、插件包卡片与详情页都会**原地显示中文名与中文描述**（由 host 覆盖显示元数据）；新装插件会在启动后自动翻译。**本插件没有任何 UI 入口**（没有 tab、没有设置项），管理通过 loopback HTTP API 或让 AI 代改。
+> 版本更新记录见 [CHANGELOG.md](CHANGELOG.md)，或在 GitHub [Releases](https://github.com/qyy2005/dsh-plugin-labels/releases) 查看。
 
-- 当前版本：**0.8.0**（本仓库即源码目录；通过 `plugin_manager install_bundle` 从 GitHub 或 npm 安装到 DSH profile）
-- 只支持 DSH 桌面版 Web GUI（开发验证版本 0.2.1-rc.2）
+给 DSH（DeepSeek Harness）**已安装插件**配「中文名 + 一句话说明」：官方「插件」页的已安装插件行、插件包卡片与详情页都会**原地显示中文名与中文描述**（由 host 覆盖显示元数据）；新装插件会在启动后自动翻译。同时给 **skills（技能）** 补中文说明：`/` 技能菜单里每条技能显示「英文原描述 ｜中文：<作用>；用法：<怎么用>」。**本插件没有任何 UI 入口**（没有 tab、没有设置项），管理通过 loopback HTTP API 或让 AI 代改。
+
+- 当前版本：**0.9.0**（本仓库即源码目录；通过 `plugin_manager install_bundle` 从 GitHub 或 npm 安装到 DSH profile）
+- 只支持 DSH 桌面版 Web GUI（开发验证版本 0.2.1-rc.2 / rc.3）
 
 ## 功能
 
 - **中文名 + 一句话说明**：每个插件一条中文名（≤10 字）和一句说明（≤80 字）；说明必须写清**怎么用**，不只是“是什么”（见下方「标签格式」）。
 - **官方页原地中文**：官方「插件」页的已安装插件行、点开的详情页，以及插件包卡片（`listBundles`）都会直接显示中文名与中文描述；未翻译的插件回退英文。默认开启。
-- **自动翻译新插件**：host 启动约 4 秒后自动补一次缺失标签（每次最多 20 条，只补空缺、不覆盖手改），不用点任何按钮；可用 `DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0` 关闭。
+- **技能中文翻译**：`/` 技能菜单里每条技能追加「｜中文：作用；用法：怎么用」，看懂技能是做什么、什么时候用（见「技能中文翻译」）。
+- **自动翻译新插件与新技能**：host 启动约 4 秒后自动补一次缺失标签（每次最多 20 条），再补最多 10 条技能说明；只补空缺、不覆盖手改。
 - **手改优先**：手动设置的标签不会被自动翻译覆盖；显式“重翻”才会覆盖。
-- **无 UI 管理入口**：通过 4 个 loopback HTTP API（见「使用」）或让 AI/脚本直接调用它们来翻译、手改、重翻、导入导出。
+- **无 UI 管理入口**：通过 7 个 loopback HTTP API（见「使用」）或让 AI/脚本直接调用它们来翻译、手改、重翻、导入导出。
 - **导出 / 导入 API**：导出带 `source`（`ai` / `manual`）的 JSON，导入时保留来源，只接受已安装插件名（≤64KB）。
-- **缓存 v2**：标签缓存在 `<DSH_HOME>/plugin-labels.json`，UTF-8 无 BOM、原子写，旧 v1 数据可迁移读取。
+- **缓存**：插件标签在 `<DSH_HOME>/plugin-labels.json`（v2），技能说明在 `<DSH_HOME>/plugin-labels-skills.json`（v1）；均 UTF-8 无 BOM、原子写，旧 v1 标签数据可迁移读取。
 
 ### 标签格式
 
@@ -53,12 +56,27 @@ host 启动约 **4 秒**后会自动补一次缺失标签：
 - 与手动翻译共用同一个单飞锁与 120 秒超时；失败只写日志（warn），不抛错、不阻塞启动。
 - 手动补翻译：`POST /api/plugin-labels/translate`（见「使用」）。
 
+## 技能中文翻译
+
+用户的技能大多是英文。本插件会在技能目录的描述末尾追加中文说明，**`/` 技能菜单里每条技能显示**：
+
+```
+<英文原描述> ｜中文：<中文作用>；用法：<怎么用>
+```
+
+- **实现**：host 包装 `skills` 服务的 `snapshot`/`list`，命中缓存才追加，未命中保持原样（`/` 菜单走 `skills.list`，模型侧技能目录走同一份 description）。
+- **缓存**：`<DSH_HOME>/plugin-labels-skills.json`（独立于插件标签缓存，`version: 1`，UTF-8 无 BOM、原子写）；每条 `{zh ≤80 字, usage ≤60 字, source: "ai" | "manual", at}`。
+- **API**（见「使用」）：`GET /api/plugin-labels/skills`、`POST /api/plugin-labels/skills/translate`、`POST /api/plugin-labels/skills/label`。
+- **自动翻译**：启动后约 4 秒的自动任务在补完插件标签后，会再补最多 **10** 条技能说明（`MAX_SKILLS_PER_AUTO`）；只补空缺、不覆盖手改；`DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0` 同时关闭插件与技能自动翻译。
+- **限制**：只翻译/解释技能的目录描述，**技能正文仍是英文**；模型侧技能目录会把 description 截断到 500 字，追加在末尾的中文通常不会明显增加模型上下文；技能服务（`ctx.get("skills")`）不可用时静默跳过，不影响其它功能。
+- **重启**：host 代码在启动时安装，**需要重启 DSH 一次**；`GET /api/plugin-labels/list` 的 `officialMeta.skills` 可确认包装是否已生效。
+
 ## 安装
 
 ### 方式一：npm 包（推荐，`npm publish` 后）
 
 在 DSH 插件页 → 添加插件 → 填包名 `dsh-plugin-labels`；或在创造模式会话里 `plugin_manager` → `install_bundle` → `target: "dsh-plugin-labels"`。发布后 profile 依赖形如
-`"dsh-plugin-labels": "dsh-plugin-labels@^0.8.0"`。
+`"dsh-plugin-labels": "dsh-plugin-labels@^0.9.0"`。
 
 ### 方式二：从 Git 仓库安装
 
@@ -74,7 +92,7 @@ host 启动约 **4 秒**后会自动补一次缺失标签：
 
 ## 使用
 
-v0.7.0 起没有 UI 入口，全部通过 4 个 loopback HTTP API 操作（也可以让 AI/脚本代改）：
+v0.9.0 起没有 UI 入口，全部通过 7 个 loopback HTTP API 操作（也可以让 AI/脚本代改）：
 
 ```powershell
 # 查看已装插件 + 标签 + 诊断字段（officialMeta）
@@ -96,9 +114,21 @@ Invoke-RestMethod -Method Post -ContentType 'application/json' `
 # 导入导出的 JSON（只保留已装插件名，保留 ai/manual 来源）
 Invoke-RestMethod -Method Post -ContentType 'application/json' -InFile labels.json `
   http://127.0.0.1:<端口>/api/plugin-labels/import
+
+# 技能：列出技能 + 已缓存的中文说明
+Invoke-WebRequest -UseBasicParsing http://127.0.0.1:<端口>/api/plugin-labels/skills
+
+# 技能：补翻译缺失的技能说明（每次最多 20 条；可重复调用补剩余）
+Invoke-RestMethod -Method Post -ContentType 'application/json' -Body '{}' `
+  http://127.0.0.1:<端口>/api/plugin-labels/skills/translate
+
+# 技能：手改一条技能说明（source=manual，自动翻译不会覆盖）
+Invoke-RestMethod -Method Post -ContentType 'application/json' `
+  -Body '{"name":"office","zh":"Office 文档处理","usage":"对 AI 说：用 office 技能处理文档"}' `
+  http://127.0.0.1:<端口>/api/plugin-labels/skills/label
 ```
 
-端口就是当前 DSH Web GUI 的端口；这些路由只接受 loopback 请求且必须是 POST（`/list` 为 GET）。自动翻译会替你补空缺，手改过的条目不会被自动覆盖。
+端口就是当前 DSH Web GUI 的端口；这些路由只接受 loopback 请求且必须是 POST（`/list`、`/skills` 为 GET）。自动翻译会替你补空缺，手改过的条目不会被自动覆盖。
 
 ## 插件速查文档
 
@@ -116,9 +146,9 @@ npm run docs                            # 等价于 node scripts/gen-doc.mjs
 
 ## 兼容性
 
-- DSH 桌面版 **0.2.1-rc.2**（Web GUI）；依赖官方 client 基座模块与 host 服务，只 `require("react")`。
-- 本插件不依赖任何 UI slot：显示覆盖包装宿主的 `pluginPackages.metaOf()`（官方页行/详情）与 `pluginManager.listBundles()`（插件包卡片），client 只注册 `locale` 字典。
-- 拿不到这些内部服务时静默回退：不显示中文（回退英文），插件其它功能与 API 仍可用。
+- DSH 桌面版 **0.2.1-rc.2**（Web GUI；技能翻译接口在 **0.2.1-rc.3** 核实）；依赖官方 client 基座模块与 host 服务，只 `require("react")`。
+- 本插件不依赖任何 UI slot：显示覆盖包装宿主的 `pluginPackages.metaOf()`（官方页行/详情）与 `pluginManager.listBundles()`（插件包卡片），技能中文包装 `skills` 服务的 `snapshot`/`list`，client 只注册 `locale` 字典。
+- 拿不到这些内部服务时静默回退：不显示中文（回退英文）、技能说明保持英文，插件其它功能与 API 仍可用。
 
 ## 开发说明
 
@@ -128,10 +158,13 @@ npm run docs                            # 等价于 node scripts/gen-doc.mjs
   - `POST /api/plugin-labels/translate`（无参=补空缺；`{names:[...]}`=显式重翻）
   - `POST /api/plugin-labels/label`（`{name,title,oneLine}` 或 `{name,action:"reset"}`）
   - `POST /api/plugin-labels/import`
-- **自动翻译**：`apply` 里注册一个 4 秒后执行一次的定时器（`unref`），调用 `translatePending` 补空缺；可用 `DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0` 关闭；异常只 warn。
-- **显示覆盖**：`installOfficialMeta` / `installBundleMeta` 用 symbol 标记识别 wrapper，幂等、可 dispose、服务替换后重打、失败静默回退。`DSH_PLUGIN_LABELS_OFFICIAL_META=0` 同时关闭两处覆盖。
-- **安全围栏**：loopback 校验、`sec-fetch-site` 跨站拒绝、POST-only、翻译单飞锁（并发 409）、`AbortSignal.timeout(120s)`、未预期异常统一 500 不泄漏路径。
-- **缓存**：`<DSH_HOME>/plugin-labels.json`，UTF-8 无 BOM，临时文件 + `rename` 原子写；缓存 `version: 2`，旧 v1 数据可迁移读取，单条非法条目丢弃。
+  - `GET  /api/plugin-labels/skills`（技能列表 + 已缓存中文说明）
+  - `POST /api/plugin-labels/skills/translate`（补技能说明，单飞锁，并发 409）
+  - `POST /api/plugin-labels/skills/label`（`{name,zh,usage}` 手改技能说明）
+- **自动翻译**：`apply` 里注册一个 4 秒后执行一次的定时器（`unref`），先 `translatePending` 补插件标签、再 `translateSkillsPending` 补最多 10 条技能说明；可用 `DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0` 关闭；异常只 warn。
+- **显示/技能覆盖**：`installOfficialMeta` / `installBundleMeta` / `installSkillTranslations` 用 symbol 标记识别 wrapper，幂等、可 dispose、服务替换后重打、失败静默回退。`DSH_PLUGIN_LABELS_OFFICIAL_META=0` 关闭前两个显示覆盖（技能翻译不受影响）。
+- **安全围栏**：loopback 校验、`sec-fetch-site` 跨站拒绝、POST-only、翻译单飞锁（插件与技能各一把，并发 409）、`AbortSignal.timeout(120s)`、未预期异常统一 500 不泄漏路径。
+- **缓存**：插件标签 `<DSH_HOME>/plugin-labels.json`（v2，旧 v1 可迁移）、技能说明 `<DSH_HOME>/plugin-labels-skills.json`（v1）；均 UTF-8 无 BOM，临时文件 + `rename` 原子写，单条非法条目丢弃。
 - **验证**：`node --check lib/index.js`、`node --check lib/client.js`；host 可用桩 `ctx` 跑冒烟。
 - 修改 host 后需重启 DSH 生效（本插件已没有需要刷新页面的 UI 改动）。
 
@@ -148,7 +181,7 @@ dsh-plugin-labels/
 ├─ package.json            # manifest（dsh.bundle 组合 patch、dsh.client 平台与 inject）
 ├─ cordis.patch.yml        # bundle 组合 patch
 ├─ lib/
-│  ├─ index.js             # host：HTTP API + 显示覆盖 + 自动翻译 + 标签缓存
+│  ├─ index.js             # host：HTTP API + 显示覆盖 + 技能中文 + 自动翻译 + 缓存
 │  └─ client.js            # client：模块骨架，仅注册 locale（v0.7.0 起无 UI）
 ├─ locale/
 │  ├─ zh.json              # 插件元数据（中文）
@@ -168,10 +201,12 @@ MIT，见 [LICENSE](LICENSE)。Copyright (c) 2026 qyy2005
 
 ## English summary
 
-`dsh-plugin-labels` is a DSH (DeepSeek Harness) plugin that gives every installed plugin a Chinese name and a one-line explanation. The labels are shown **in place** on the official Plugins page: the installed-plugin rows, the detail pages and the plugin package cards (`pluginManager.listBundles`) all display the Chinese name and description, falling back to English for plugins without a label. **The plugin has no UI entry point** (no tab, no settings item): labels are managed through four loopback HTTP routes (or by an AI/script calling them), and results are cached under `<DSH_HOME>/plugin-labels.json` with manual edits never overwritten by automatic translation.
+`dsh-plugin-labels` is a DSH (DeepSeek Harness) plugin that gives every installed plugin a Chinese name and a one-line explanation. The labels are shown **in place** on the official Plugins page: the installed-plugin rows, the detail pages and the plugin package cards (`pluginManager.listBundles`) all display the Chinese name and description, falling back to English for plugins without a label. **The plugin has no UI entry point** (no tab, no settings item): labels are managed through loopback HTTP routes (or by an AI/script calling them), and results are cached under `<DSH_HOME>/plugin-labels.json` with manual edits never overwritten by automatic translation.
+
+It also translates **skills**: each skill description in the `/` skill menu gets a Chinese purpose and usage hint appended (`English description ｜中文：…；用法：…`), cached separately in `<DSH_HOME>/plugin-labels-skills.json` and managed through `GET/POST /api/plugin-labels/skills…`. Only the catalogue description is translated, the skill body stays English; the model-side catalogue truncates descriptions at 500 characters.
 
 Each label is a Chinese name (≤10 characters) plus a one-line explanation (≤80 characters) that must explain **how to use** the plugin: the problem it solves, where in DSH the user enters or operates it, and a concrete first step. When the entry point cannot be inferred, the model is instructed to write 入口以界面为准 instead of inventing menus.
 
-Newly installed plugins are translated automatically: about 4 seconds after host startup one pass fills up to 20 missing labels (set `DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0` and restart DSH to disable it). The display overrides can be disabled together with `DSH_PLUGIN_LABELS_OFFICIAL_META=0`; `GET /api/plugin-labels/list` reports `officialMeta: {enabled, patched, service, bundles}` for diagnostics. Both overrides require one DSH restart after installation.
+Newly installed plugins are translated automatically: about 4 seconds after host startup one pass fills up to 20 missing labels and then up to 10 skill explanations (set `DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0` and restart DSH to disable it). The display overrides can be disabled together with `DSH_PLUGIN_LABELS_OFFICIAL_META=0`; `GET /api/plugin-labels/list` reports `officialMeta: {enabled, patched, service, bundles, skills}` for diagnostics. These hooks require one DSH restart after installation.
 
-The client half is a hand-written `__ModuleLoader__` bundle with no build step that only requires `react` (v0.7.0: locale registration only, no UI); the host half is an ESM plugin exposing four loopback-only HTTP routes plus the display overrides and the startup auto-translate. Verified on DSH desktop 0.2.1-rc.2. MIT licensed.
+The client half is a hand-written `__ModuleLoader__` bundle with no build step that only requires `react` (v0.7.0: locale registration only, no UI); the host half is an ESM plugin exposing seven loopback-only HTTP routes plus the display overrides, the skill translation hook and the startup auto-translate. Verified on DSH desktop 0.2.1-rc.2 / rc.3. MIT licensed.

package/lib/index.js

@@ -1,12 +1,14 @@
 /**
- * dsh-plugin-labels — host half (v0.8.0: labels explain how to use a plugin).
+ * dsh-plugin-labels — host half (v0.9.0: plugin labels + skill translations).
  *
- * Four loopback-only endpoints (kept for scripts/AI even though the client no
- * longer renders a tab):
+ * Loopback-only endpoints:
  *   GET  /api/plugin-labels/list       -> installed profile bundles + cached labels
  *   POST /api/plugin-labels/translate  -> translate the bundles that have no label yet
  *   POST /api/plugin-labels/label      -> set one manual label, or reset one back to AI
  *   POST /api/plugin-labels/import     -> merge an exported labels JSON
+ *   GET  /api/plugin-labels/skills     -> skills with their cached Chinese translations
+ *   POST /api/plugin-labels/skills/translate -> translate missing skill explanations
+ *   POST /api/plugin-labels/skills/label     -> set one manual skill translation
  *
  * Translation uses the live Harness LLM service exactly like the official
  * @deepseek-ai/dsh-experimental-auto-review plugin does:
@@ -21,19 +23,28 @@
  * and a concrete first step when useful. The model is told never to invent
  * menus: when the entry point cannot be inferred it must write 入口以界面为准.
  *
+ * Skill translations (v0.9.0): every skill summary gets a Chinese purpose and a
+ * short usage hint appended to its `description`, so the `/` skill menu shows
+ * "English original ｜中文：…；用法：…". They live in their own cache
+ * <DSH_HOME>/plugin-labels-skills.json. Optional `whenToUse` is sent to the
+ * model, the skill body itself is not translated, and the model-side skill
+ * catalogue truncates descriptions at 500 characters (the appended Chinese
+ * usually falls past that point, so model context barely grows).
+ *
  * Display overrides (all failure-safe; marker-detected because Cordis hands out
  * traceable Proxies whose method references differ on every read):
  *   - `installOfficialMeta` wraps `pluginPackages.metaOf()` so the official
  *     Plugins page rows and detail pages show the Chinese labels in place.
  *   - `installBundleMeta` wraps `pluginManager.listBundles()` so the plugin
  *     package cards (which call `readPluginMeta` directly) show them too.
- * Set DSH_PLUGIN_LABELS_OFFICIAL_META=0 to disable both display overrides.
+ *   - `installSkillTranslations` wraps the `skills` service `snapshot`/`list`.
+ * Set DSH_PLUGIN_LABELS_OFFICIAL_META=0 to disable the first two overrides.
  *
  * Auto translation: shortly after startup one pass fills up to
- * MAX_PENDING_PER_CALL missing labels through the same core, so a newly
- * installed plugin gets a Chinese name without any UI. Set
- * DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0 to disable it. It never throws into or
- * blocks host startup.
+ * MAX_PENDING_PER_CALL missing labels through the same core, then up to
+ * MAX_SKILLS_PER_AUTO skill explanations, so newly installed plugins and skills
+ * get Chinese text without any UI. Set DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0 to
+ * disable it. It never throws into or blocks host startup.
  *
  * Failure policy: every handler catches its own errors and answers with JSON;
  * nothing is allowed to escape as an unhandled rejection (that is fatal to the
@@ -51,6 +62,9 @@ export const LIST_PATH = "/api/plugin-labels/list";
 export const TRANSLATE_PATH = "/api/plugin-labels/translate";
 export const LABEL_PATH = "/api/plugin-labels/label";
 export const IMPORT_PATH = "/api/plugin-labels/import";
+export const SKILLS_PATH = "/api/plugin-labels/skills";
+export const SKILLS_TRANSLATE_PATH = "/api/plugin-labels/skills/translate";
+export const SKILLS_LABEL_PATH = "/api/plugin-labels/skills/label";
 
 const CACHE_VERSION = 2;
 const LEGACY_CACHE_VERSION = 1;
@@ -60,6 +74,12 @@ const MAX_ONE_LINE = 80;
 const MAX_BODY_BYTES = 65536;
 const TRANSLATE_TIMEOUT_MS = 120000;
 
+const SKILL_CACHE_VERSION = 1;
+const MAX_SKILL_ZH = 80;
+const MAX_SKILL_USAGE = 60;
+const MAX_SKILL_DESCRIPTION = 600;
+const MAX_SKILLS_PER_AUTO = 10;
+
 const SYSTEM_PROMPT = [
     "You label DeepSeek Harness (DSH) plugins for a Chinese-speaking user.",
     "For every plugin you receive, produce:",
@@ -73,6 +93,15 @@ const SYSTEM_PROMPT = [
     '{"items":[{"name":"<exact package name>","title":"...","oneLine":"..."}]}',
 ].join("\n");
 
+const SKILL_SYSTEM_PROMPT = [
+    "You translate DeepSeek Harness (DSH) skill descriptions for a Chinese-speaking user who cannot read English.",
+    "For every skill you receive, produce:",
+    "1. zh: a Chinese name plus one-line purpose, at most 80 Chinese characters, concrete (no marketing words, no literal package-name translation).",
+    "2. usage: how and when to use it, at most 60 Chinese characters — for example 对 AI 说\"用 X 技能\" or 输入 /<name>，when the description implies an invocation. Never invent a command that the description does not imply.",
+    "Answer with strict JSON only, no prose, no markdown fences:",
+    '{"items":[{"name":"<exact skill name>","zh":"...","usage":"..."}]}',
+].join("\n");
+
 /**
  * Experimental display-layer override: wrap the host `pluginPackages.metaOf`
  * service so the official Plugins page shows our Chinese labels in place
@@ -101,9 +130,11 @@ function displayOverrideEnabled() {
  */
 const OFFICIAL_META_MARK = Symbol.for("dsh-plugin-labels.official-meta");
 const BUNDLE_META_MARK = Symbol.for("dsh-plugin-labels.bundle-meta");
+const SKILL_TRANSLATIONS_MARK = Symbol.for("dsh-plugin-labels.skill-translations");
 
 const isOfficialMetaWrapper = (value) => Boolean(value && typeof value === "function" && value[OFFICIAL_META_MARK] === true);
 const isBundleMetaWrapper = (value) => Boolean(value && typeof value === "function" && value[BUNDLE_META_MARK] === true);
+const isSkillTranslationWrapper = (value) => Boolean(value && typeof value === "function" && value[SKILL_TRANSLATIONS_MARK] === true);
 
 function markWithSymbol(wrapper, symbol) {
     try {
@@ -127,6 +158,10 @@ function markBundleMetaWrapper(wrapper) {
     return markWithSymbol(wrapper, BUNDLE_META_MARK);
 }
 
+function markSkillTranslationWrapper(wrapper) {
+    return markWithSymbol(wrapper, SKILL_TRANSLATIONS_MARK);
+}
+
 /** Split a configured specifier into its bare package name (`@scope/name/sub` -> `@scope/name`). */
 export function bareNameOf(specifier) {
     if (typeof specifier !== "string") return "";
@@ -439,6 +474,68 @@ function writeCache(home, cache) {
     }
 }
 
+/**
+ * Skill explanation cache: a separate file from the plugin-label cache so the
+ * two features never overwrite each other.
+ */
+function skillCachePath(home) {
+    return path.join(home, "plugin-labels-skills.json");
+}
+
+/** Validate one cached skill translation; invalid entries are dropped. */
+function normalizeSkillEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    const zh = typeof value.zh === "string" ? value.zh.trim() : "";
+    if (zh === "") return null;
+    const usage = typeof value.usage === "string" ? value.usage.trim() : "";
+    const source = value.source === "manual" ? "manual" : "ai";
+    const entry = { zh: zh.slice(0, MAX_SKILL_ZH), usage: usage.slice(0, MAX_SKILL_USAGE), source };
+    if (typeof value.at === "string" && value.at !== "") entry.at = value.at;
+    return entry;
+}
+
+function emptySkillCache() {
+    return { version: SKILL_CACHE_VERSION, entries: {} };
+}
+
+function readSkillCache(home) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(skillCachePath(home), "utf8"));
+    } catch {
+        // Missing or corrupt skill cache: start over, never fail the request.
+        return emptySkillCache();
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return emptySkillCache();
+    if (parsed.version !== SKILL_CACHE_VERSION) return emptySkillCache();
+    if (!parsed.entries || typeof parsed.entries !== "object" || Array.isArray(parsed.entries)) return emptySkillCache();
+    const cache = emptySkillCache();
+    for (const [name, value] of Object.entries(parsed.entries)) {
+        if (typeof name !== "string" || name.trim() === "" || RESERVED_KEYS.has(name)) continue;
+        const entry = normalizeSkillEntry(value);
+        if (entry) cache.entries[name] = entry;
+    }
+    return cache;
+}
+
+function writeSkillCache(home, cache) {
+    const target = skillCachePath(home);
+    const temporary = target + ".tmp-" + process.pid;
+    // UTF-8 without BOM: DSH and Node parse these files as raw JSON text.
+    const body = JSON.stringify({ version: SKILL_CACHE_VERSION, entries: cache.entries || {} }, null, 2);
+    fs.writeFileSync(temporary, body, "utf8");
+    try {
+        fs.renameSync(temporary, target);
+    } catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        } catch {
+            // The temp file is already gone.
+        }
+        throw error;
+    }
+}
+
 /**
  * Install the experimental official-page display override.
  * Wraps `pluginPackages.metaOf(specifier, parentURL)` with our cached labels,
@@ -676,6 +773,282 @@ export function installBundleMeta(ctx, home) {
     return { dispose: restore, tryPatch, status };
 }
 
+/** Read the current skill summaries from the host registry; never throws. */
+async function skillsSnapshot(ctx) {
+    const warn = (message) => {
+        try {
+            ctx.logger?.warn?.("[plugin-labels] " + message);
+        } catch {
+            // A logger failure must not break the host.
+        }
+    };
+    try {
+        const service = ctx.get("skills");
+        if (!service || typeof service.snapshot !== "function") return { available: false, skills: [] };
+        const snapshot = await service.snapshot({});
+        if (!snapshot || !Array.isArray(snapshot.skills)) return { available: false, skills: [] };
+        return { available: true, skills: snapshot.skills };
+    } catch (error) {
+        warn("skills snapshot failed: " + String((error && error.message) || error));
+        return { available: false, skills: [] };
+    }
+}
+
+function truncateChars(value, limit) {
+    const characters = Array.from(value);
+    return characters.length <= limit ? value : characters.slice(0, limit).join("");
+}
+
+function buildSkillsUserText(pending) {
+    return JSON.stringify(
+        {
+            instruction: "Translate and explain every skill below. Reply with the strict JSON object only.",
+            skills: pending.map((skill) => ({
+                name: skill.name,
+                description: truncateChars(typeof skill.description === "string" ? skill.description : "", MAX_SKILL_DESCRIPTION),
+                ...(typeof skill.whenToUse === "string" && skill.whenToUse.trim() !== ""
+                    ? { whenToUse: truncateChars(skill.whenToUse, MAX_SKILL_DESCRIPTION) }
+                    : {}),
+            })),
+        },
+        null,
+        2,
+    );
+}
+
+/** Parse the model's strict-JSON skill answer, keeping only names we asked about. */
+function parseSkillTranslations(text, pending) {
+    let body = text.trim();
+    const fenced = body.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenced) body = fenced[1].trim();
+    const start = body.indexOf("{");
+    const end = body.lastIndexOf("}");
+    if (start < 0 || end <= start) throw new Error("model output contains no JSON object");
+    const parsed = JSON.parse(body.slice(start, end + 1));
+    const items = parsed && Array.isArray(parsed.items) ? parsed.items : [];
+    const wanted = new Set(pending.map((skill) => skill.name));
+    const out = {};
+    for (const item of items) {
+        if (!item || typeof item !== "object") continue;
+        const name = typeof item.name === "string" ? item.name : "";
+        if (!wanted.has(name)) continue;
+        const zh = typeof item.zh === "string" ? item.zh.trim() : "";
+        if (zh === "") continue;
+        const usage = typeof item.usage === "string" ? item.usage.trim() : "";
+        out[name] = {
+            zh: truncateChars(zh, MAX_SKILL_ZH),
+            usage: truncateChars(usage, MAX_SKILL_USAGE),
+        };
+    }
+    return out;
+}
+
+/**
+ * Translate the skill explanations that are still missing. Never throws: HTTP
+ * and the startup auto-run both treat failures as "nothing happened".
+ */
+export async function translateSkillsPending(ctx, home, limit = MAX_PENDING_PER_CALL) {
+    const warn = (message) => {
+        try {
+            ctx.logger?.warn?.("[plugin-labels] " + message);
+        } catch {
+            // A logger failure must not break the host.
+        }
+    };
+    if (skillTranslateInFlight) return { added: 0, remaining: 0, total: 0, available: true, busy: true };
+    skillTranslateInFlight = true;
+    try {
+        const { available, skills } = await skillsSnapshot(ctx);
+        if (!available) return { added: 0, remaining: 0, total: 0, available: false };
+        const cache = readSkillCache(home);
+        const pendingAll = skills.filter((skill) => skill && typeof skill.name === "string" && skill.name !== "" && !cache.entries[skill.name]);
+        const requested = Math.max(1, Number(limit) || MAX_PENDING_PER_CALL);
+        const pending = pendingAll.slice(0, requested);
+        const remaining = Math.max(0, pendingAll.length - pending.length);
+        const total = pendingAll.length;
+        if (pending.length === 0) return { added: 0, remaining, total, available: true };
+        const { provider, model } = modelOf(ctx);
+        const llm = ctx.get("llm");
+        if (!llm || typeof llm.stream !== "function") throw new Error("the llm service is not available in this profile");
+        const stream = llm.stream({
+            provider,
+            model,
+            temperature: 0,
+            system: SKILL_SYSTEM_PROMPT,
+            messages: [{ role: "user", content: [{ type: "text", text: buildSkillsUserText(pending) }] }],
+            signal: AbortSignal.timeout(TRANSLATE_TIMEOUT_MS),
+        });
+        const text = await collectText(stream);
+        const translations = parseSkillTranslations(text, pending);
+        const at = new Date().toISOString();
+        let added = 0;
+        for (const [name, value] of Object.entries(translations)) {
+            // Never overwrite an existing entry (a manual one always wins).
+            if (cache.entries[name]) continue;
+            cache.entries[name] = { zh: value.zh, usage: value.usage, source: "ai", at };
+            added += 1;
+        }
+        if (added > 0) writeSkillCache(home, cache);
+        return { added, remaining, total, available: true };
+    } catch (error) {
+        warn("skill translation failed: " + String((error && error.message) || error));
+        return { added: 0, remaining: 0, total: 0, available: true, error: String((error && error.message) || error) };
+    } finally {
+        skillTranslateInFlight = false;
+    }
+}
+
+/** Append the Chinese purpose/usage to an English skill description. */
+export function skillDescriptionWithChinese(original, entry) {
+    if (typeof original !== "string" || !entry || typeof entry !== "object") return original;
+    const zh = typeof entry.zh === "string" ? entry.zh.trim() : "";
+    if (zh === "") return original;
+    const usage = typeof entry.usage === "string" ? entry.usage.trim() : "";
+    return original + " ｜中文：" + zh + (usage === "" ? "" : "；用法：" + usage);
+}
+
+/** Recover the original English description from an already-injected one. */
+function originalSkillDescription(description, entry) {
+    if (typeof description !== "string") return "";
+    if (!entry || typeof entry !== "object") return description;
+    const zh = typeof entry.zh === "string" ? entry.zh.trim() : "";
+    if (zh === "") return description;
+    const usage = typeof entry.usage === "string" ? entry.usage.trim() : "";
+    const suffix = " ｜中文：" + zh + (usage === "" ? "" : "；用法：" + usage);
+    return description.endsWith(suffix) ? description.slice(0, -suffix.length) : description;
+}
+
+/** Return a shallow copy of one skill summary with the Chinese suffix applied. */
+function skillWithTranslation(skill, entries) {
+    if (!skill || typeof skill !== "object") return skill;
+    const name = typeof skill.name === "string" ? skill.name : "";
+    const entry = name === "" ? undefined : entries[name];
+    const description = skillDescriptionWithChinese(skill.description, entry);
+    if (description === skill.description) return skill;
+    return { ...skill, description };
+}
+
+/** Map a `snapshot`/`list` result through the skill translations. */
+function mapSkillResult(methodName, value, home) {
+    const entries = readSkillCache(home).entries;
+    if (methodName === "list") {
+        if (!Array.isArray(value)) return value;
+        return value.map((skill) => skillWithTranslation(skill, entries));
+    }
+    if (!value || typeof value !== "object" || !Array.isArray(value.skills)) return value;
+    return { ...value, skills: value.skills.map((skill) => skillWithTranslation(skill, entries)) };
+}
+
+/**
+ * Patch the `skills` service so the `/` skill menu shows the Chinese purpose
+ * and usage next to the English description. Marker-based, idempotent,
+ * disposable, re-applied after a service swap; every failure keeps the host's
+ * own data.
+ */
+export function installSkillTranslations(ctx, home) {
+    const warn = (message) => {
+        try {
+            ctx.logger?.warn?.("[plugin-labels] " + message);
+        } catch {
+            // A logger failure must not break the host.
+        }
+    };
+    let installed = null; // { service, methods: [{ name, raw, wrapper }] }
+
+    const currentService = () => {
+        try {
+            return ctx.get("skills");
+        } catch {
+            return undefined;
+        }
+    };
+
+    const restore = () => {
+        const active = installed;
+        installed = null;
+        if (!active) return;
+        for (const method of active.methods) {
+            try {
+                if (!isSkillTranslationWrapper(active.service[method.name])) continue;
+                try {
+                    delete active.service[method.name];
+                } catch {
+                    // Frozen/exotic service object; fall back to the saved method.
+                }
+                if (isSkillTranslationWrapper(active.service[method.name])) active.service[method.name] = method.raw;
+            } catch (error) {
+                warn("failed to restore skills." + method.name + ": " + String((error && error.message) || error));
+            }
+        }
+    };
+
+    const tryPatch = () => {
+        try {
+            const service = currentService();
+            if (!service || (typeof service !== "object" && typeof service !== "function")) return;
+            const alreadyWrapped = ["snapshot", "list"].filter((name) => isSkillTranslationWrapper(service[name]));
+            if (alreadyWrapped.length > 0) {
+                if (!installed) {
+                    installed = {
+                        service,
+                        methods: alreadyWrapped.map((name) => ({ name, raw: service[name], wrapper: service[name] })),
+                    };
+                }
+                return;
+            }
+            if (installed) restore();
+            const methods = [];
+            for (const methodName of ["snapshot", "list"]) {
+                const raw = service[methodName];
+                if (typeof raw !== "function") continue;
+                const wrapper = markSkillTranslationWrapper(function (...args) {
+                    let result;
+                    try {
+                        result = raw.apply(service, args);
+                    } catch (error) {
+                        return Promise.reject(error);
+                    }
+                    // These methods are async today but tolerate a sync result.
+                    return Promise.resolve(result).then(
+                        (value) => {
+                            try {
+                                return mapSkillResult(methodName, value, home);
+                            } catch {
+                                return value;
+                            }
+                        },
+                        (error) => {
+                            throw error;
+                        },
+                    );
+                });
+                try {
+                    service[methodName] = wrapper;
+                } catch (error) {
+                    warn("could not wrap skills." + methodName + ": " + String((error && error.message) || error));
+                    continue;
+                }
+                if (!isSkillTranslationWrapper(service[methodName])) {
+                    warn("could not wrap skills." + methodName + ": the assignment had no effect");
+                    continue;
+                }
+                methods.push({ name: methodName, raw, wrapper });
+            }
+            if (methods.length > 0) installed = { service, methods };
+        } catch (error) {
+            warn("skills translation hook skipped: " + String((error && error.message) || error));
+        }
+    };
+
+    const status = () => ({
+        patched: installed !== null,
+        service: Boolean(currentService()),
+    });
+
+    tryPatch();
+    return { dispose: restore, tryPatch, status };
+}
+
 /** Read the configured default route; fall back to the official DeepSeek route. */
 function modelOf(ctx) {
     try {
@@ -776,7 +1149,7 @@ function handleList(home, req, res, officialMetaStatus) {
         }));
         // Diagnostics for the experimental official-page override; clients ignore
         // unknown fields, so this stays backward compatible.
-        let officialMeta = { enabled: true, patched: false, service: false, bundles: false };
+        let officialMeta = { enabled: true, patched: false, service: false, bundles: false, skills: false };
         if (typeof officialMetaStatus === "function") {
             try {
                 officialMeta = officialMetaStatus();
@@ -897,6 +1270,8 @@ async function handleLabel(home, req, res) {
  * tokens twice and race the atomic cache rename, so refuse it instead.
  */
 let translateInFlight = false;
+/** Separate single-flight lock for skill translations (HTTP 409 on concurrency). */
+let skillTranslateInFlight = false;
 
 /**
  * One startup pass that fills missing labels. Never throws (a failed auto-run
@@ -995,6 +1370,90 @@ async function handleImport(home, req, res) {
     if (applied > 0) writeCache(home, cache);
     json(res, 200, { ok: true, applied, skipped, labels: cache.entries });
 }
+/** GET /skills: skill catalogue with the cached Chinese translations. */
+async function handleSkillsList(ctx, home, req, res) {
+    if (!isLoopback(req)) {
+        json(res, 403, { ok: false, error: "loopback only" });
+        return;
+    }
+    if (!isSameOriginRequest(req) || req.method !== "GET") {
+        json(res, 403, { ok: false, error: "cross-site or non-GET request rejected" });
+        return;
+    }
+    try {
+        const { available, skills } = await skillsSnapshot(ctx);
+        const cache = readSkillCache(home);
+        const items = skills.map((skill) => {
+            const name = typeof skill.name === "string" ? skill.name : "";
+            const entry = name === "" ? null : cache.entries[name] || null;
+            const item = {
+                // The service may already have our suffix injected; report the
+                // original English description here.
+                name,
+                description: originalSkillDescription(skill.description, entry),
+                translation: entry,
+            };
+            if (typeof skill.whenToUse === "string" && skill.whenToUse !== "") item.whenToUse = skill.whenToUse;
+            return item;
+        });
+        json(res, 200, {
+            ok: true,
+            available,
+            count: items.length,
+            translated: items.filter((item) => item.translation !== null).length,
+            pending: items.filter((item) => item.translation === null).length,
+            skills: items,
+        });
+    } catch (error) {
+        respondError(res, error);
+    }
+}
+
+/** POST /skills/translate: fill missing skill explanations (single-flight). */
+async function handleSkillsTranslate(ctx, home, req, res) {
+    if (!isLoopback(req)) {
+        json(res, 403, { ok: false, error: "loopback only" });
+        return;
+    }
+    if (skillTranslateInFlight) {
+        json(res, 409, { ok: false, error: "a skill translation is already running" });
+        return;
+    }
+    const result = await translateSkillsPending(ctx, home, MAX_PENDING_PER_CALL);
+    json(res, 200, {
+        ok: true,
+        available: result.available,
+        added: result.added,
+        remaining: result.remaining,
+        total: result.total,
+    });
+}
+
+/** POST /skills/label: set one manual skill translation (source:"manual"). */
+async function handleSkillsLabel(home, req, res) {
+    if (!isLoopback(req)) {
+        json(res, 403, { ok: false, error: "loopback only" });
+        return;
+    }
+    const payload = await readJsonBody(req);
+    const name = typeof payload.name === "string" ? payload.name.trim() : "";
+    const zh = typeof payload.zh === "string" ? payload.zh.trim() : "";
+    const usage = typeof payload.usage === "string" ? payload.usage.trim() : "";
+    if (name === "") throw badRequest("name is required");
+    if (zh === "") throw badRequest("zh is required");
+    if (Array.from(zh).length > MAX_SKILL_ZH) throw badRequest("zh is too long (max " + MAX_SKILL_ZH + ")");
+    if (Array.from(usage).length > MAX_SKILL_USAGE) throw badRequest("usage is too long (max " + MAX_SKILL_USAGE + ")");
+    const cache = readSkillCache(home);
+    cache.entries[name] = {
+        zh: truncateChars(zh, MAX_SKILL_ZH),
+        usage: truncateChars(usage, MAX_SKILL_USAGE),
+        source: "manual",
+        at: new Date().toISOString(),
+    };
+    writeSkillCache(home, cache);
+    json(res, 200, { ok: true, name });
+}
+
 /** Wrap an async handler so a rejection always becomes a JSON answer. */
 function guarded(res, req, work) {
     if (!isSameOriginRequest(req)) {
@@ -1019,9 +1478,11 @@ export function apply(ctx) {
     // the routes; the service listener re-applies them after a service swap.
     const officialMeta = installOfficialMeta(ctx, home);
     const bundleMeta = installBundleMeta(ctx, home);
+    const skillTranslations = installSkillTranslations(ctx, home);
     ctx.effect(() => () => {
         officialMeta.dispose();
         bundleMeta.dispose();
+        skillTranslations.dispose();
     }, "plugin-labels: restore official plugin metadata wrappers");
     ctx.effect(() => {
         try {
@@ -1029,19 +1490,22 @@ export function apply(ctx) {
             return ctx.on("internal/service", (serviceName) => {
                 if (serviceName === "pluginPackages") officialMeta.tryPatch();
                 if (serviceName === "pluginManager") bundleMeta.tryPatch();
+                if (serviceName === "skills") skillTranslations.tryPatch();
             });
         } catch {
             return () => {};
         }
     }, "plugin-labels: watch the official metadata services");
-    // Auto-translate: one pass a few seconds after startup fills missing labels,
-    // so a newly installed plugin gets a Chinese name without any UI. Never
-    // blocks startup; DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0 turns it off.
+    // Auto-translate: one pass a few seconds after startup fills missing plugin
+    // labels, then missing skill explanations, so a newly installed plugin or
+    // skill gets Chinese text without any UI. Never blocks startup;
+    // DSH_PLUGIN_LABELS_AUTO_TRANSLATE=0 turns it off.
     if (autoTranslateEnabled()) {
         ctx.effect(() => {
             const timer = setTimeout(() => {
                 Promise.resolve()
                     .then(() => runAutoTranslate(ctx, home))
+                    .then(() => translateSkillsPending(ctx, home, MAX_SKILLS_PER_AUTO))
                     .catch(() => {});
             }, AUTO_TRANSLATE_DELAY_MS);
             try {
@@ -1064,6 +1528,7 @@ export function apply(ctx) {
         handler: (req, res) => handleList(home, req, res, () => ({
             ...officialMeta.status(),
             bundles: bundleMeta.status().patched,
+            skills: skillTranslations.status().patched,
         })),
     }), "plugin-labels: installed plugin list route");
     ctx.effect(() => ctx.webServer.register({
@@ -1081,4 +1546,19 @@ export function apply(ctx) {
         path: IMPORT_PATH,
         handler: (req, res) => guarded(res, req, () => handleImport(home, req, res)),
     }), "plugin-labels: import labels route");
+    ctx.effect(() => ctx.webServer.register({
+        kind: "exact",
+        path: SKILLS_PATH,
+        handler: (req, res) => handleSkillsList(ctx, home, req, res),
+    }), "plugin-labels: skill list route");
+    ctx.effect(() => ctx.webServer.register({
+        kind: "exact",
+        path: SKILLS_TRANSLATE_PATH,
+        handler: (req, res) => guarded(res, req, () => handleSkillsTranslate(ctx, home, req, res)),
+    }), "plugin-labels: skill translate route");
+    ctx.effect(() => ctx.webServer.register({
+        kind: "exact",
+        path: SKILLS_LABEL_PATH,
+        handler: (req, res) => guarded(res, req, () => handleSkillsLabel(home, req, res)),
+    }), "plugin-labels: skill manual label route");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-labels",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "description": "Chinese names and one-line explanations for installed DSH plugins; automatic translation and in-place display on the official Plugins page.",