dsh-claude-compat 0.8.3 → 0.9.0

package/README.md

@@ -8,7 +8,7 @@
   <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/🌐_简体中文-点我阅读中文-red?style=for-the-badge" alt="简体中文"></a>
   <img src="https://img.shields.io/npm/dm/dsh-claude-compat?style=flat-square&label=downloads/month&color=brightgreen" alt="npm downloads/month">
   <img src="https://img.shields.io/npm/dt/dsh-claude-compat?style=flat-square&label=total%20downloads&color=blue" alt="npm total downloads">
-  <img src="https://img.shields.io/badge/version-0.8.1-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/version-0.9.0-blue?style=flat-square" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
 </p>
 
@@ -120,6 +120,8 @@ Restart DSH (`dsh web`). Done — skills show up in `/`, rules are injected into
 | `enableHooks` | `true` | Run `.claude/settings.json` hooks (Pre/PostToolUse, UserPromptSubmit) |
 | `hooksTimeoutMs` | `60000` | Per-hook run timeout (UserPromptSubmit capped at 10s regardless) |
 | `enableAgents` | `true` | Surface `.claude/agents/*.md` as delegation-shim skills |
+| `skillAliases` | `{}` | Non-kebab (e.g. Chinese) name → ASCII slug map, e.g. `{ "三脑": "san-nao" }`. See “Non-ASCII skill names” below |
+| `aliasDescriptionPrefix` | `true` | When an alias is used, put the original name in front of the description: `san-nao: 三脑 — …` |
 | `rulesMaxBytes` | `65536` | Hard cap on total injected project rules text |
 | `userRulesMaxBytes` | `65536` | Hard cap on total injected `~/.claude/rules` text |
 | `projectRootMarkers` | `[".git"]` | Ancestor markers for project-root discovery |
@@ -145,6 +147,23 @@ Restart DSH (`dsh web`). Done — skills show up in `/`, rules are injected into
 - **Rules content**: rules are injected verbatim as instructions to the model. Only commit rules you want the model to follow — same trust level as `CLAUDE.md`.
 - **Catalog snapshot timing**: the skill catalog is snapshotted when a session is created. Skills installed or edited mid-session surface after `/reload-cc-plugins` (hot reload) or in the next session.
 
+### Non-ASCII skill names
+
+DSH's skill-name grammar is fixed to kebab-case (`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`, defined in `@deepseek-ai/dsh-skill` and enforced by the registry before a candidate is read), so **a Chinese name can never reach the registry, no matter what this plugin emits** — emitting it anyway only moves the failure one layer down (`get()` returns `void 0`).
+
+The plugin's answer is an explicit map from the original name to a legal slug, keeping the original name at the front of the description:
+
+```yaml
+skillAliases:
+  三脑: tri-brain
+  读知乎: read-zhihu
+```
+
+- The `name` becomes the slug (`/tri-brain` in the slash menu); the `description` becomes `三脑 — 三脑复核（…）`.
+- **A legal name always beats an alias** — a skill DSH can already load is never renamed.
+- Aliased entries keep their provider's rank, so a collision with a DSH-native or `~/.agents` skill is deduped exactly like any other duplicate (a `~/.claude` alias loses to an `~/.agents` skill of the same name rather than shadowing it). Lower `userSkillRank` below 500 to make `~/.claude` win.
+- Un-mapped non-kebab names no longer vanish silently: one warning per file per process, with a paste-ready mapping example.
+
 ## Troubleshooting
 
 ### Known limitation: `/cc-resume` via the skill tool

package/README.zh-CN.md

@@ -8,7 +8,7 @@
   <a href="README.md"><img src="https://img.shields.io/badge/🌐_English-Click_me-red?style=for-the-badge" alt="English"></a>
   <img src="https://img.shields.io/npm/dm/dsh-claude-compat?style=flat-square&label=downloads/month&color=brightgreen" alt="npm downloads/month">
   <img src="https://img.shields.io/npm/dt/dsh-claude-compat?style=flat-square&label=total%20downloads&color=blue" alt="npm total downloads">
-  <img src="https://img.shields.io/badge/version-0.8.1-blue?style=flat-square" alt="Version">
+  <img src="https://img.shields.io/badge/version-0.9.0-blue?style=flat-square" alt="Version">
   <img src="https://img.shields.io/badge/license-MIT-orange?style=flat-square" alt="License">
 </p>
 
@@ -120,6 +120,8 @@ dsh plugin --profile web add github:biedongbin/dsh-claude-compat
 | `enableHooks` | `true` | 运行 `.claude/settings.json` hooks（Pre/PostToolUse、UserPromptSubmit） |
 | `hooksTimeoutMs` | `60000` | 单个 hook 运行超时（UserPromptSubmit 无论如何上限 10s） |
 | `enableAgents` | `true` | 把 `.claude/agents/*.md` 暴露为委派 shim skill |
+| `skillAliases` | `{}` | 非 kebab 名（中文等）→ ASCII slug 的映射，如 `{ "三脑": "san-nao" }`。见下方「中文 / 非 ASCII 技能名」 |
+| `aliasDescriptionPrefix` | `true` | 用了 alias 时把原名放在描述最前：`san-nao: 三脑 — …` |
 | `rulesMaxBytes` | `65536` | 注入项目 rules 总量硬上限 |
 | `userRulesMaxBytes` | `65536` | 注入 `~/.claude/rules` 总量硬上限 |
 | `projectRootMarkers` | `[".git"]` | 项目根发现的祖先标记 |
@@ -145,6 +147,23 @@ dsh plugin --profile web add github:biedongbin/dsh-claude-compat
 - **Rules 内容**：rules 原文注入为模型指令。只提交你想让模型遵循的 rule —— 信任级别同 `CLAUDE.md`。
 - **Catalog 快照时机**：skill catalog 在会话创建时快照。会话中途安装/修改的 skill 通过 `/reload-cc-plugins` 热生效，或下一会话生效。
 
+### 中文 / 非 ASCII 技能名
+
+DSH 的技能名文法写死为 kebab-case（`/^[a-z0-9]+(?:-[a-z0-9]+)*$/`，定义在 `@deepseek-ai/dsh-skill`，registry 取用前先校验），所以**中文名无论插件怎么发都进不了 registry** —— 插件层放行也没用，下一层立刻 `return void 0`。
+
+本插件的做法：把中文名显式映射成一个合法 slug，原名保留在描述最前，目录里读起来仍是中文：
+
+```yaml
+skillAliases:
+  三脑: tri-brain
+  读知乎: read-zhihu
+```
+
+- 映射后 `name` 用 slug（斜杠菜单里是 `/tri-brain`），`description` 变成 `三脑 — 三脑复核（…）`。
+- **合法名永远压过映射**：本来就能加载的技能不会被 alias 改名。
+- 别名条目沿用原 provider 的 rank，所以与 DSH 原生或 `~/.agents` 同名时，按原有优先级去重（`~/.claude` 的 alias 输给 `~/.agents` 同名项，不会顶掉它）。想让 `~/.claude` 赢就把 `userSkillRank` 调到 500 以下。
+- 没配映射的非 kebab 名不再静默消失：每个文件每进程告警一次，并直接给出可粘贴的映射示例。
+
 ## 故障排查
 
 ### 已知限制：通过 skill 工具调用 `/cc-resume`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-claude-compat",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "DeepSeek Harness plugin: bridge Claude Code's .claude/ directories (project and ~/.claude: skills, commands, rules) into DSH native skill registry and message-stream rules injection.",
   "type": "module",
   "main": "src/index.js",
@@ -56,7 +56,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "check": "node --check src/index.js && node --check src/lib.js && node --check src/mcp.js && node --check src/hooks.js && node --check src/agents.js && node --check src/plugins.js && node --test test/self-check.test.js test/v040.test.js test/v050.test.js"
+    "check": "node --check src/index.js && node --check src/lib.js && node --check src/mcp.js && node --check src/hooks.js && node --check src/agents.js && node --check src/plugins.js && node --check src/aliases.js && node --test test/self-check.test.js test/v040.test.js test/v050.test.js test/v060.test.js test/v070.test.js test/v080.test.js test/v090.test.js"
   },
   "bin": {
     "dsh-claude-compat-restart": "scripts/dsh-restart.sh"

package/scripts/deploy-local.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Deploy this checkout into the local DSH profile.
+#
+# Editing ~/src/dsh-claude-compat does NOT change what DSH runs: DSH imports the
+# copy under the profile's node_modules, and only at process start. This script
+# copies the source over that copy and reminds you to restart.
+#
+#   bash scripts/deploy-local.sh                 # default profile: desktop
+#   bash scripts/deploy-local.sh --profile web
+#   bash scripts/deploy-local.sh --no-backup
+#
+# Environment: DSH_HOME (default ~/.dsh), DSH_PROFILE (default desktop).
+set -euo pipefail
+
+SRC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+PROFILE="${DSH_PROFILE:-desktop}"
+BACKUP=1
+
+usage() {
+  sed -n '2,12p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --profile)   PROFILE="${2:?--profile 需要参数}"; shift 2 ;;
+    --no-backup) BACKUP=0; shift ;;
+    -h|--help)   usage; exit 0 ;;
+    *) echo "未知参数: $1（用 --help 看用法）" >&2; exit 1 ;;
+  esac
+done
+
+TARGET="$DSH_HOME/profiles/$PROFILE/node_modules/dsh-claude-compat"
+if [[ ! -d "$TARGET" ]]; then
+  cat >&2 <<EOF
+找不到已安装的插件：
+  $TARGET
+
+先把它装进 profile：
+  "/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \\
+    plugin --profile $PROFILE add dsh-claude-compat@latest
+EOF
+  exit 1
+fi
+
+# A deployed copy older than the checkout is the exact failure this script
+# exists to prevent; say what is being overwritten so it is recoverable.
+if [[ $BACKUP -eq 1 ]]; then
+  BK="$DSH_HOME/backups/dsh-claude-compat-$(date +%Y%m%d-%H%M%S)"
+  mkdir -p "$BK"
+  cp -a "$TARGET"/. "$BK"/
+  echo "备份 → $BK"
+fi
+
+# --delete keeps the deployed src an exact mirror (stale modules would otherwise
+# linger and get imported).
+rsync -a --delete "$SRC_DIR/src/" "$TARGET/src/"
+for f in README.md README.zh-CN.md CHANGELOG.md CHANGELOG.zh-CN.md; do
+  [[ -f "$SRC_DIR/$f" ]] && cp -a "$SRC_DIR/$f" "$TARGET/"
+done
+
+if diff -r "$SRC_DIR/src" "$TARGET/src" >/dev/null; then
+  echo "✓ src 已同步 → $TARGET"
+else
+  echo "✗ 复制后校验不一致，请检查权限" >&2
+  exit 1
+fi
+
+echo
+echo "⚠ 插件在 DSH 启动时 import，改完必须重启 DSH 进程才生效（不是刷新窗口）。"
+echo "  配置项（cordis.patch.yml）同理。"

package/src/agents.js

@@ -7,20 +7,20 @@
 // the provider's rank (50 < 700) plus the shared dedupe flow.
 
 import { join } from 'node:path';
-import { isSkillName } from '@deepseek-ai/dsh-skill';
 import {
   readTextSafe,
   stringField,
   parseFrontmatter,
   pathExists,
 } from './lib.js';
+import { resolveCandidateName, warnUnmapped, withOriginalName } from './aliases.js';
 
 const AGENT_HEADER = 'Agent delegation: use the subagent/background-agent capability with this persona and instructions.';
 
 // Discover agent candidates from one agents dir (flat: *.md). Returns DSH skill
 // candidates in the same shape as discoverSkills/discoverCommands so the
 // registry's dedupe treats them uniformly.
-export async function discoverAgents(rootDir, providerName, source, rank) {
+export async function discoverAgents(rootDir, providerName, source, rank, aliasOptions) {
   const out = [];
   if (!(await pathExists(rootDir))) return out;
   let entries;
@@ -36,14 +36,22 @@ export async function discoverAgents(rootDir, providerName, source, rank) {
     const parsed = parseFrontmatter(raw);
     const data = parsed?.data ?? {};
     const stem = entry.name.slice(0, -3);
-    let name = stringField(data, 'name');
-    if (name === undefined || !isSkillName(name)) name = stem;
-    if (!isSkillName(name)) continue; // non-kebab names rejected by registry anyway
-    const description = stringField(data, 'description')
+    // Frontmatter name first, then the filename stem — a non-kebab name falls
+    // back to a skillAliases slug (see src/aliases.js).
+    const fmName = stringField(data, 'name');
+    const resolved = resolveCandidateName([fmName, stem], aliasOptions?.aliases);
+    if (resolved === undefined) {
+      warnUnmapped('agent', fmName ?? stem, path);
+      continue;
+    }
+    const baseDescription = stringField(data, 'description')
       ?? firstLine(parsed?.body ?? raw, 100);
+    const description = aliasOptions?.tagOriginal === false
+      ? baseDescription
+      : withOriginalName(baseDescription, resolved.original);
     const tools = stringField(data, 'tools');
     out.push({
-      name,
+      name: resolved.name,
       description,
       whenToUse: description,
       invocation: { modelInvocable: true, userInvocable: true },

package/src/aliases.js

@@ -0,0 +1,99 @@
+// dsh-claude-compat: non-ASCII (Chinese) skill names.
+//
+// DSH's registry only accepts kebab-case names. The grammar lives in
+// `@deepseek-ai/dsh-skill`:
+//
+//   const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+//   // registry.get(name): if (!isSkillName(name)) return void 0;
+//
+// so a skill whose frontmatter name or directory is written in Chinese can
+// never be reached under that name, no matter what this plugin emits. The
+// only thing the plugin can do is stop dropping it silently: map it to an
+// explicit ASCII slug through the `skillAliases` config and keep the original
+// name visible at the front of the description, so the catalog still reads
+// "san-nao: 三脑 — …".
+//
+// Aliased entries keep the provider's own rank, so the existing dedupe ladder
+// still applies: an alias that collides with a higher-priority skill (a DSH
+// native name, or ~/.agents) loses exactly like any other duplicate instead of
+// shadowing it.
+
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Whether `name` satisfies DSH's public skill-name grammar. */
+export function isKebabName(name) {
+  return typeof name === 'string' && SKILL_NAME.test(name);
+}
+
+/**
+ * Keep only usable `skillAliases` entries: plain string → string where the
+ * target is itself a legal skill name. Bad targets are dropped rather than
+ * emitted and rejected later by the registry.
+ */
+export function normalizeAliases(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [from, to] of Object.entries(raw)) {
+    if (typeof from !== 'string' || from === '') continue;
+    if (typeof to !== 'string' || !isKebabName(to)) continue;
+    out[from] = to;
+  }
+  return out;
+}
+
+/**
+ * Pick the DSH skill name for one candidate.
+ *
+ * @param candidates names to try, in priority order (frontmatter `name`, then
+ *   the flattened directory name / filename stem).
+ * @param aliases normalized alias map.
+ * @returns `{ name, original }` — `original` is the non-kebab name an alias
+ *   replaced, or `undefined` when the natural name already works. `undefined`
+ *   when nothing usable was found (the caller should skip and warn).
+ */
+export function resolveCandidateName(candidates, aliases) {
+  const list = (candidates ?? []).filter((n) => typeof n === 'string' && n !== '');
+  // A legal name always beats an alias — an alias must never rename a skill
+  // that DSH can already load under its own name.
+  for (const candidate of list) {
+    if (isKebabName(candidate)) return { name: candidate, original: undefined };
+  }
+  for (const candidate of list) {
+    const mapped = aliases?.[candidate];
+    if (mapped !== undefined) return { name: mapped, original: candidate };
+  }
+  return undefined;
+}
+
+/**
+ * Put the original (Chinese) name back in front of the description so it shows
+ * up in the skill catalog and the slash menu: "三脑 — 三脑复核流程…".
+ * Idempotent, so a caller that resolves twice cannot double-prefix.
+ */
+export function withOriginalName(description, original) {
+  if (original === undefined) return description;
+  if (typeof description !== 'string' || description === '') return description;
+  const prefix = `${original} — `;
+  return description.startsWith(prefix) ? description : `${prefix}${description}`;
+}
+
+// One warning per skipped file per process: discovery runs on every catalog
+// collect, and an un-mapped Chinese skill must not flood the log.
+const warned = new Set();
+
+/** Warn once that `name` cannot be surfaced, and how to fix it. */
+export function warnUnmapped(kind, name, path) {
+  const key = `${kind}\u0000${path}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(
+    `dsh-claude-compat: ${kind} "${name}" (${path}) is not a kebab-case name and has no `
+    + `skillAliases mapping, so DSH cannot load it. Add one to the plugin config, e.g. `
+    + `skillAliases: { "${name}": "your-slug" }`,
+  );
+}
+
+/** Test seam: forget which paths have already warned. */
+export function resetWarnings() {
+  warned.clear();
+}

package/src/hooks.js

@@ -13,6 +13,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import {
+  CLAUDE_COMPAT_SOURCE_KIND,
   findProjectRootSync,
   resolveUserClaudeDir,
 } from './lib.js';
@@ -108,7 +109,7 @@ export function mapPostHookOutput(exitCode, stdout, { warn = console.warn } = {}
       kind: 'accept',
       additionalContexts: [createUserMessage({
         content: [{ type: 'text', text: additional }],
-        source: { kind: 'plugin', plugin: 'dsh-claude-compat', form: 'hook-context' },
+        source: { kind: CLAUDE_COMPAT_SOURCE_KIND, form: 'hook-context' },
       })],
     };
   }
@@ -339,7 +340,7 @@ async function runPromptHooks(hooks, agent, config) {
     if (text === '') continue;
     extra.push(createUserMessage({
       content: [{ type: 'text', text }],
-      source: { kind: 'plugin', plugin: 'dsh-claude-compat', form: 'hook-context' },
+      source: { kind: CLAUDE_COMPAT_SOURCE_KIND, form: 'hook-context' },
     }));
   }
   return extra.length > 0 ? extra : undefined;

package/src/index.js

@@ -47,13 +47,19 @@ import { readFileSync } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { isSkillName } from '@deepseek-ai/dsh-skill';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { discoverAgents, renderAgentContent } from './agents.js';
+import {
+  normalizeAliases,
+  resolveCandidateName,
+  warnUnmapped,
+  withOriginalName,
+} from './aliases.js';
 import { registerHooks } from './hooks.js';
 import { mountMcpServers, mountMcpConfigs } from './mcp.js';
 import { discoverPluginContent, readInstalledClaudePlugins, translatePluginMcp } from './plugins.js';
 import {
+  CLAUDE_COMPAT_SOURCE_KIND,
   findProjectRoot,
   findProjectRootSync,
   listMdFilesSync,
@@ -86,6 +92,15 @@ export const Config = z.object({
   enableHooks: z.boolean().default(true),
   hooksTimeoutMs: z.number().default(60000),
   enableAgents: z.boolean().default(true),
+  // Non-ASCII (e.g. Chinese) skill/command/agent names can never satisfy DSH's
+  // kebab-case grammar, so they are dropped by the registry. `skillAliases`
+  // maps the original name to an ASCII slug the registry accepts —
+  // { "三脑": "san-nao" } — and the original name is kept at the front of the
+  // description so the catalog still reads "san-nao: 三脑 — …". Aliased entries
+  // keep their provider rank, so dedupe against DSH-native and ~/.agents names
+  // behaves exactly like any other collision.
+  skillAliases: z.dict(z.string()).default({}),
+  aliasDescriptionPrefix: z.boolean().default(true),
   // Claude Code plugin-marketplace installs (~/.claude/plugins). Skills,
   // commands and agents surface at pluginSkillRank (750: the long tail —
   // everything else wins collisions). Plugin MCP servers are opt-in via
@@ -168,6 +183,11 @@ class ClaudeCompatSkillProvider {
     this.userSkillRank = config.userSkillRank ?? 700;
     this.userSkillSource = config.userSkillSource ?? 'user-claude';
     this.userClaudeDir = resolveUserClaudeDir(config.userClaudeDir);
+    this.aliases = normalizeAliases(config.skillAliases);
+    this.aliasOptions = {
+      aliases: this.aliases,
+      tagOriginal: config.aliasDescriptionPrefix !== false,
+    };
     this.control = control;
     control.signal.addEventListener('abort', () => {}, { once: true });
   }
@@ -206,7 +226,8 @@ class ClaudeCompatSkillProvider {
     if (this.config.enablePlugins !== false) {
       const pluginCandidates = await discoverPluginContent(
         this.config.pluginsRoot, this.name, this.config.pluginSkillSource ?? 'claude-plugin',
-        this.config.pluginSkillRank ?? 750, { enableAgents: this.config.enableAgents });
+        this.config.pluginSkillRank ?? 750,
+        { enableAgents: this.config.enableAgents, ...this.aliasOptions });
       candidates.push(...pluginCandidates);
     }
     return candidates;
@@ -259,13 +280,13 @@ Notes:
 
   async addRootCandidates(candidates, claudeDir, source, rank) {
     const provider = this.name;
-    const tasks = [discoverSkills(join(claudeDir, 'skills'), provider, source, rank)];
+    const tasks = [discoverSkills(join(claudeDir, 'skills'), provider, source, rank, this.aliasOptions)];
     for (const [dir, fn] of [
       ['commands', discoverCommands],
       ['agents', discoverAgents],
     ]) {
       if (dir === 'agents' && this.config.enableAgents === false) continue;
-      tasks.push(fn(join(claudeDir, dir), provider, source, rank));
+      tasks.push(fn(join(claudeDir, dir), provider, source, rank, this.aliasOptions));
     }
     const batches = await Promise.all(tasks);
     for (const batch of batches) candidates.push(...batch);
@@ -299,7 +320,7 @@ Notes:
 
 // ─── discovery: <root>/.claude/skills (recursive, ≤3 levels) ─────────────────
 
-export async function discoverSkills(rootDir, providerName, source, rank) {
+export async function discoverSkills(rootDir, providerName, source, rank, aliasOptions) {
   const { readdir } = await import('node:fs/promises');
   const out = [];
   if (!(await pathExistsSafe(rootDir))) return out;
@@ -313,7 +334,8 @@ export async function discoverSkills(rootDir, providerName, source, rank) {
     } catch { return; }
     if (entries.some(e => e.isFile() && e.name === 'SKILL.md')) {
       const skillPath = join(dir, 'SKILL.md');
-      const c = await parseSkillCandidateFile(skillPath, providerName, source, rank, prefix || undefined);
+      const c = await parseSkillCandidateFile(
+        skillPath, providerName, source, rank, prefix || undefined, aliasOptions);
       if (c !== undefined) out.push(c);
       return; // bundle — don't descend
     }
@@ -329,7 +351,7 @@ export async function discoverSkills(rootDir, providerName, source, rank) {
 
 // ─── discovery: <root>/.claude/commands (flat) ───────────────────────────────
 
-export async function discoverCommands(rootDir, providerName, source, rank) {
+export async function discoverCommands(rootDir, providerName, source, rank, aliasOptions) {
   const { readdir } = await import('node:fs/promises');
   const out = [];
   if (!(await pathExistsSafe(rootDir))) return out;
@@ -341,14 +363,20 @@ export async function discoverCommands(rootDir, providerName, source, rank) {
     if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
     const path = join(rootDir, entry.name);
     const stem = entry.name.slice(0, -3);
-    if (!isSkillName(stem)) continue; // non-kebab names rejected by registry anyway
+    const resolved = resolveCandidateName([stem], aliasOptions?.aliases);
+    if (resolved === undefined) {
+      warnUnmapped('command', stem, path);
+      continue;
+    }
     const raw = await readTextSafe(path);
     if (raw === undefined) continue;
     const parsed = parseFrontmatter(raw);
-    const description = parsed === undefined ? stem : (stringField(parsed.data, 'description') ?? stem);
+    const baseDescription = parsed === undefined ? stem : (stringField(parsed.data, 'description') ?? stem);
     out.push({
-      name: stem,
-      description,
+      name: resolved.name,
+      description: aliasOptions?.tagOriginal === false
+        ? baseDescription
+        : withOriginalName(baseDescription, resolved.original),
       invocation: { modelInvocable: true, userInvocable: true },
       provider: providerName,
       source,
@@ -361,7 +389,7 @@ export async function discoverCommands(rootDir, providerName, source, rank) {
   return out;
 }
 
-async function parseSkillCandidateFile(path, providerName, source, rank, flatName) {
+async function parseSkillCandidateFile(path, providerName, source, rank, flatName, aliasOptions) {
   const raw = await readTextSafe(path);
   if (raw === undefined) return undefined;
   const parsed = parseFrontmatter(raw);
@@ -372,18 +400,23 @@ async function parseSkillCandidateFile(path, providerName, source, rank, flatNam
   // Prefer frontmatter name when it is a valid kebab-case skill name. Some Claude
   // skills use names with ':' or other chars DSH rejects (e.g.
   // "salus:ai-robot-coding-env-check"); for those, fall back to the flattened
-  // directory name, which is virtually always kebab-case.
-  let name;
-  if (fmName !== undefined && isSkillName(fmName)) name = fmName;
-  else if (flatName !== undefined && isSkillName(flatName)) name = flatName;
-  if (name === undefined) return undefined;
+  // directory name, which is virtually always kebab-case. Names that are not
+  // kebab-case at all (e.g. Chinese) can still be surfaced through an explicit
+  // `skillAliases` mapping — see src/aliases.js.
+  const resolved = resolveCandidateName([fmName, flatName], aliasOptions?.aliases);
+  if (resolved === undefined) {
+    warnUnmapped('skill', fmName ?? flatName ?? path, path);
+    return undefined;
+  }
   let invocation;
   try { invocation = parseInvocationPolicy(parsed.data); }
   catch { invocation = { modelInvocable: true, userInvocable: true }; }
   const whenToUse = stringField(parsed.data, 'whenToUse');
   return {
-    name,
-    description,
+    name: resolved.name,
+    description: aliasOptions?.tagOriginal === false
+      ? description
+      : withOriginalName(description, resolved.original),
     ...(whenToUse !== undefined ? { whenToUse } : {}),
     invocation,
     provider: providerName,
@@ -405,7 +438,7 @@ function registerRulesSection(ctx, config) {
   ctx.on('agent/pre-step', async ({ agent, messages }, next) => {
     const decision = await next();
     if (decision.kind !== 'enter') return decision;
-    const present = (list) => list.some((m) => m?.source?.kind === 'plugin' && m.source.plugin === 'dsh-claude-compat');
+    const present = (list) => list.some((m) => m?.source?.kind === CLAUDE_COMPAT_SOURCE_KIND);
     // dsh 0.1.2 made the event log private — exact lookup is eventAt(seq),
     // the same API dsh core uses for its own surface scans. Legacy dsh
     // exposed a plain session.events array; keep an optional fallback.
@@ -414,8 +447,7 @@ function registerRulesSection(ctx, config) {
       || agent.session.surface.nodes.some((seq) => {
         const event = agent.session.eventAt?.(seq) ?? agent.session.events?.[seq];
         return event?.type === 'user/message'
-          && event.data?.source?.kind === 'plugin'
-          && event.data.source.plugin === 'dsh-claude-compat';
+          && event.data?.source?.kind === CLAUDE_COMPAT_SOURCE_KIND;
       });
     if (alreadyInjected) return decision;
     // Session cwd, NOT process.cwd() — the DSH process may be launched from
@@ -430,7 +462,7 @@ function registerRulesSection(ctx, config) {
       // of the message array. Not in system prompt.
       cache.set(cwd, createUserMessage({
         content: [{ type: 'text', text }],
-        source: { kind: 'plugin', plugin: 'dsh-claude-compat', form: 'rules' },
+        source: { kind: CLAUDE_COMPAT_SOURCE_KIND, form: 'rules' },
       }));
     }
     return {

package/src/lib.js

@@ -8,6 +8,15 @@ import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { parse } from 'yaml';
 
+// Producer-owned source kind for every message this plugin injects. dsh's
+// session format v4 admission (session-format-v3-to-v4/src/message-sources.ts)
+// rejects the retired V3 `kind: 'plugin'` wrapper: a third-party producer must
+// emit its own kind. dsh derives exactly this string for us — `producerKind()`
+// falls through RENAMED_PRODUCERS and RELEASED_SAME_NAME_PRODUCERS to
+// `plugin:${plugin}` — so a V3 log migrated by dsh and a message we emit today
+// carry the identical kind. Emission and dedup must both use this constant.
+export const CLAUDE_COMPAT_SOURCE_KIND = 'plugin:dsh-claude-compat';
+
 export function resolveUserClaudeDir(dir) {
   if (dir === undefined || dir === null || dir === '') return join(homedir(), '.claude');
   if (dir === '~') return homedir();

package/src/plugins.js

@@ -21,6 +21,7 @@ import {
   stringField,
 } from './lib.js';
 import { translateMcpServers } from './mcp.js';
+import { resolveCandidateName, warnUnmapped } from './aliases.js';
 
 // Parse installed_plugins.json → [{ key, name, marketplace, installPath,
 // version }] for scope==='user' entries. Dedupe per key, keeping the last
@@ -60,16 +61,17 @@ function claReadSync(p) { return rfs(p, 'utf8'); }
 // Claude Code's discoverCommands drops commands whose only description is the
 // empty string; plugin marketplaces ship many such stubs, so this wrapper
 // re-surfaces them with the filename stem as the description.
-export async function discoverPluginContent(pluginsRoot, providerName, source, rank, { enableAgents } = {}) {
+export async function discoverPluginContent(pluginsRoot, providerName, source, rank, { enableAgents, aliases, tagOriginal } = {}) {
   const out = [];
   const plugins = readInstalledClaudePlugins(pluginsRoot);
   const { discoverSkills, discoverCommands } = await import('./index.js');
   const { discoverAgents } = await import('./agents.js');
+  const aliasOptions = { aliases, tagOriginal };
   const patchedCommands = async (dir) => {
-    const batch = await discoverCommands(dir, providerName, source, rank);
+    const batch = await discoverCommands(dir, providerName, source, rank, aliasOptions);
     if (batch.length > 0) return batch;
     const kept = new Set(batch.map((c) => c.path));
-    const extra = await discoverCommandsAllowEmpty(dir, providerName, source, rank);
+    const extra = await discoverCommandsAllowEmpty(dir, providerName, source, rank, aliasOptions);
     return [...batch, ...extra.filter((c) => !kept.has(c.path))];
   };
   for (const plugin of plugins) {
@@ -89,33 +91,37 @@ export async function discoverPluginContent(pluginsRoot, providerName, source, r
     };
     if (manifest !== undefined) {
       const skillDirs = manifestDirs(manifest, 'skills', installPath);
-      for (const dir of skillDirs) push('skills')(await discoverSkills(dir, providerName, source, rank));
+      for (const dir of skillDirs) push('skills')(await discoverSkills(dir, providerName, source, rank, aliasOptions));
       const commandsDir = typeof manifest.commands === 'string' ? resolve(installPath, manifest.commands) : undefined;
       if (commandsDir !== undefined) push('commands')(await patchedCommands(commandsDir));
     } else {
-      push('skills')(await discoverSkills(join(installPath, 'skills'), providerName, source, rank));
+      push('skills')(await discoverSkills(join(installPath, 'skills'), providerName, source, rank, aliasOptions));
       push('commands')(await patchedCommands(join(installPath, 'commands')));
     }
     if (enableAgents !== false) {
       const agentsDir = join(installPath, 'agents');
-      if (await pathExists(agentsDir)) push('agents')(await discoverAgents(agentsDir, providerName, source, rank));
+      if (await pathExists(agentsDir)) push('agents')(await discoverAgents(agentsDir, providerName, source, rank, aliasOptions));
     }
   }
   return out;
 }
 
 // Like discoverCommands but keeps empty-description stubs (stem as description).
-async function discoverCommandsAllowEmpty(rootDir, providerName, source, rank) {
+async function discoverCommandsAllowEmpty(rootDir, providerName, source, rank, aliasOptions) {
   const { readdir } = await import('node:fs/promises');
-  const { isSkillName } = await import('@deepseek-ai/dsh-skill');
-  const out = [];  if (!(await pathExists(rootDir))) return out;
+  const out = [];
+  if (!(await pathExists(rootDir))) return out;
   let entries;
   try { entries = await readdir(rootDir, { withFileTypes: true, encoding: 'utf8' }); }
   catch { return out; }
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
     const stem = entry.name.slice(0, -3);
-    if (!isSkillName(stem)) continue;
+    const resolved = resolveCandidateName([stem], aliasOptions?.aliases);
+    if (resolved === undefined) {
+      warnUnmapped('command', stem, join(rootDir, entry.name));
+      continue;
+    }
     const raw = await readTextSafe(join(rootDir, entry.name));
     if (raw === undefined) continue;
     const parsed = parseFrontmatter(raw);
@@ -123,8 +129,10 @@ async function discoverCommandsAllowEmpty(rootDir, providerName, source, rank) {
     const description = stringField(parsed.data, 'description');
     if (description !== undefined) continue; // non-empty handled by index.js variant
     out.push({
-      name: stem,
-      description: stem,
+      name: resolved.name,
+      // The stub description IS the name; when an alias was used the original
+      // (Chinese) name is the useful label, not the slug.
+      description: resolved.original ?? stem,
       invocation: { modelInvocable: true, userInvocable: true },
       provider: providerName,
       source,