@michengai/dsh-skills-manager 1.2.12 → 1.2.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.2.13 - 2026-10-23
+
+- Hide the heading version chip when online updates are disabled alongside the update check action.
+- Disable the bundle config toggle with localized diagnostics when online updates are locked by host configuration (`updater: false` or `onlineUpdate: false`), preventing silent 403 bounces.
+- Clean up sidebar controller listeners and slots on plugin teardown, invalidating late initialization and rollback responses.
+
 ## 1.2.12 - 2026-10-23
 
 - Support opt-out toggle for online updates with a native switch under bundle configuration (Issue #50).

package/CHANGELOG.zh-CN.md

@@ -2,6 +2,12 @@
 
 [English](CHANGELOG.md)
 
+## 1.2.13 - 2026-10-23
+
+- 修复关闭在线更新后标题栏版本号标签仍残留的问题：将门控前置，关闭后同步隐藏版本号与检查更新按钮。
+- 完善宿主配置锁定（`updater: false` / `onlineUpdate: false`）体验：锁定后在配置卡片中明确禁用开关并提示锁定原因，防止点击后静默回弹 403。
+- 修复侧边栏入口控制器的生命周期管理：在插件卸载清理钩子中安全释放监听器与插槽注册，并在销毁时阻断延迟初始化与回滚回调。
+
 ## 1.2.12 - 2026-10-23
 
 - 支持在插件详情配置中提供「在线更新」开关（默认开启），关闭后自动隐藏检查更新入口（#50）。

package/README.md

@@ -19,21 +19,19 @@
 
 > DSH Skills Manager is a community-maintained DeepSeek Harness (DSH) plugin, not an official DeepSeek AI product.
 
-This README describes **1.2.12**. Released changes are in the [changelog](CHANGELOG.md).
+This README describes **1.2.13**. Released changes are in the [changelog](CHANGELOG.md).
 
 ## Features
 
-
 Bring skills from your computer and projects into DSH without switching between Agent folders.
 
-- **Manage in one place**: browse collapsible source groups, search, read, and toggle skills. Categories group skills inside a source and do not move files.
-- **Global and project skills**: select a registered workspace from the project tab dropdown. Its skills use the same source-group layout as global skills. Project copies take priority over global copies.
-- **Reuse existing skills**: supports Codex, Claude Code, Copilot, and other agents without modifying their source files when toggled.
-- **Create and import**: create a skill or import ZIP archives, folders, and `SKILL.md` files into your user directory (default) or a registered workspace. User-level writes can go to DSH skills or Shared Agent.
-- **Skill repositories**: discover public GitHub skills, install without overwriting local files, review updates and restore backups.
-- **Recover deleted skills**: DSH skills go to Trash first, so accidental deletions can be restored.
-
-- **Source tracking and updates**: distinguish local and repository skills, preview file changes, protect local edits, and confirm backup, update or rollback.
+- **Unified multi-view management**: Browse Global Skills, Project Skills, Discover, and Trash in unified tabs with instant search, status filtering, and collapsible source groups.
+- **Broad ecosystem support**: Full coverage for 19+ tools and CLI environments including DSH, Shared Agent, Codex, Claude Code, Copilot, Cursor, Windsurf, Qoder, and Trae without touching third-party files.
+- **Categorization and drag & drop**: Create category folders inside sources, drag skill rows (`⋮⋮`) to organize and order them, batch assign skills, and toggle entire categories with a single switch. Category metadata is saved without moving files.
+- **Public markets & repositories**: Integrated Discover hub to explore trending skills from ClawHub and skills.sh, or subscribe to public GitHub repositories with incremental diff inspection and backups.
+- **Create and flexible import**: Create skills or import ZIP archives, folders, and `SKILL.md` files directly into your global user root or a registered workspace.
+- **Wide reading experience**: 760px responsive detail modal with monospace syntax styling, vertical resizing, and a one-click "Copy body" action.
+- **Trash & safe rollback**: Soft delete protects skills from accidental loss, allowing complete restoration with provenance and update history preserved.
 
 ## Screenshots
 
@@ -45,11 +43,11 @@ Project skills:
 
 ![Project skills management view](assets/screenshots/project-skills.webp)
 
-Skill repositories:
+Skill repositories & discover:
 
 ![Browse and install repository skills](assets/screenshots/skill-repositories.webp)
 
-*Screenshots show the 1.1.18 release featuring global skills, project skills, and skill repositories. Screenshots show only the core feature panels, with background whitespace and unneeded window chrome cropped out, and use lossless WebP.*
+*Screenshots show core feature views for global skills, project skills, and skill discovery. Lossless WebP.*
 
 ## Installation
 
@@ -75,34 +73,87 @@ dsh plugin --profile web add @michengai/dsh-skills-manager@latest --registry=htt
 
 Restart DSH, refresh the page, and open **Settings → Skills**. To update, select **Check for updates** or run the installation command again.
 
-- Plugin `1.2.12` is tested with DeepSeek Harness `0.2.0-rc.1`, `0.2.0-rc.2`, `0.2.1-rc.1`, `0.2.1-rc.2`.
+- Plugin `1.2.13` is tested with DeepSeek Harness `0.2.0-rc.1`, `0.2.0-rc.2`, `0.2.1-rc.1`, `0.2.1-rc.2`.
 - Hosts before `0.2.0` are no longer supported. If you still use a `0.1.x` host, install plugin `1.1.23` instead of `@latest`.
-
-## Usage
-
-| What you want to do | How |
+- **Reverse proxy deployment**: Supports hosting DSH behind prefix-stripping reverse proxies (e.g. `/app/dsh/`). API and update endpoints resolve against the page base URI (`document.baseURI`).
+
+## Plugin Configuration & Toggles
+
+The plugin follows standard DSH bundle configuration conventions. Options are located at:
+> **Sidebar → Plugins → Click `Skills Manager`** (the host's `plugins.bundle.config` slot).
+
+Two native switches are available:
+
+### 1. Sidebar Entry (`sidebarEntry`)
+- **Default**: Disabled (`false`)
+- **Description**: Displays a persistent **Skills** navigation icon directly under **Plugins** in the host's left primary sidebar.
+- **Effect**:
+  - When enabled, clicking the sidebar icon opens the Skills Manager directly in the primary workspace with a **960px centered container** (matching host plugin manager conventions). This eliminates vertical scrolling constraints in narrow settings dialogs;
+  - When disabled, unregisters the sidebar entry cleanly;
+  - The standard **Settings → Skills** view remains active either way, and state is synchronized live across both entry points.
+
+### 2. Online Updates (`onlineUpdate` / `updater`)
+- **Default**: Enabled (`true`)
+- **Description**: Controls whether the plugin checks for and installs updates from npm.
+- **Effect**:
+  - **Dynamic UI Sync**: Disabling the toggle hides the **Check for updates** button in the header immediately without requiring a full page reload;
+  - **Endpoint Guard**: When disabled, the update API route returns `HTTP 403` for all check and install requests, preventing unreviewed updates;
+  - **Host / Platform Lock**: For curated plugin indexes (such as VibeDev) or restricted enterprise environments, this can be locked directly via Cordis configuration (bundle patch) without needing UI interaction:
+    ```yaml
+    updater: false # or onlineUpdate: false
+    ```
+    Once configured, the built-in updater is disabled at startup and the update action stays hidden.
+
+## Usage Guide
+
+| Action | How to do it |
 | --- | --- |
-| Find a skill | Choose Global or Project, expand a source group, or use search and filters. |
-| Read its contents | Select **View details** for the skill body and source information. |
-| Enable or disable | Toggle the skill switch. This affects DSH without editing source files. |
-| Add a skill | Select **Create skill** or **Import skill**, then use the side-by-side dropdowns: choose **User directory** (default) or **Specific workspace** on the left, and a location or registered workspace on the right. Check the destination path below. A workspace copy is written to that project's `.dsh/skills` and may be committed to its repository. |
-| Install from a repository | Open **Repositories → Add repository**, enter a public GitHub URL, scan, click **Install**, use the same side-by-side dropdowns to choose the scope and location or workspace, check the destination path below, and confirm. |
-| Uninstall a repository skill | Click the red **Uninstall** button and confirm. This includes copies in a registered workspace. The installed folder and local edits move to **Trash**, and **Install** becomes available again. |
-| Update repository skills | Select **Refresh & check updates**, then **Review update** to inspect changes and confirm backup and update. |
-| Roll back an update | Select **Restore previous version** for a skill with a backup, preview and confirm. |
-| Recover a deletion | Open **Trash** and restore. |
-
-- **Registered workspaces**: select a registered workspace from the project tab dropdown. Only that workspace is scanned, displayed and searched. Git repositories use the nearest Git root; other folders use the workspace directory, so no `git init` is required. Empty workspaces remain selectable; unavailable directories are disabled.
-- **Independent copies**: disabling a project copy allows another enabled copy to take over, and the panel identifies the active source. Disable all copies to turn the skill off completely.
-- **File management**: User-level DSH and Shared Agent skills can move to Trash and be restored from the general manager without installation records. A top-level directory link in user or project DSH is listed too: it can be viewed and toggled, and it cannot be deleted or overwritten. Project Shared Agent remains read-only. Shared Agent keeps recursive discovery and link reading; linked entries and unsafe paths are not writable. Repository-installed copies in DSH, Shared Agent, or a registered workspace can also be uninstalled from **Repositories**. Codex, Claude and other external skills remain read-only. Creation, file import and repository install can write to DSH skills or Shared Agent in your user directory, or to a registered workspace's `.dsh/skills`. Creation, import and installation never preselect a workspace, and Shared Agent is not available for workspaces. The project tab viewing selection is not a write destination.
-- **Restore**: retired repository provenance belongs to the specific Trash entry and is reactivated only by an explicit restore, including the destination and update/rollback history. A different same-name skill does not inherit repository management. Uninstalling a Shared Agent copy affects every agent using that directory.
-
-### Repository boundaries
-
-- The header **Check for updates** updates the plugin itself. Repository **Refresh & check updates** checks skill contents without installing or replacing them; it shows animation, counts and the current repository.
-- Repository installation writes to user-level DSH skills or Shared Agent (`~/.agents/skills`, overridable with `DSH_AGENTS_HOME`), or to a registered workspace's `<project>/.dsh/skills`. The chooser shows the configured path and disables unsafe paths; a missing directory is created only after confirmation. Codex, Claude and other agent directories cannot be selected. Arbitrary paths, unregistered project destinations and plugin-managed caches are not writable. Missing destinations in legacy records default to DSH; updates and rollback follow the recorded destination. Public GitHub repositories are supported; private credentials and automatic updates are not. Removing a subscription keeps installed skills.
-- Archives are limited to 32 MiB, including when filtering by subdirectory. Failed scans preserve the previous catalog; corrupt caches require refresh.
-- Local edits require explicit confirmation before replacement. Historical backups are not automatically cleaned and consume additional disk space.
+| **Find skills** | Switch between Global Skills and Project Skills tabs, expand/collapse source groups, or use the search bar and status filters. |
+| **Inspect content** | Click **View details** on any skill row to read `SKILL.md` content and diagnostics in a 760px wide resizable dialog, with one-click **Copy body**. |
+| **Toggle invocation** | Toggle the switch on the right side of a skill row to enable or disable it for DSH without editing third-party files. |
+| **Organize categories** | Click **New category** within a source, then drag the grab handle (`⋮⋮`) to reorder or move skills across categories. Toggling a category turns all its member skills on or off. |
+| **Create & import** | Click **Create skill** or **Import skill** in the header. Select destination scope (User directory or a registered workspace project) and path. |
+| **Discover & install** | Open the **Discover** tab to browse trending ClawHub skills or search the skills.sh catalog, or click **Add repository** to subscribe to a public GitHub repo. |
+| **Update repository skills** | Click **Refresh**, inspect file diffs with **Review update**, and confirm to update with an automated backup. |
+| **Roll back updates** | Click **Restore previous version** on skills with backup history, preview changes, and confirm rollback. |
+| **Recover deletions** | Open **Trash** to restore accidentally deleted DSH skills with their original locations preserved. |
+
+### Four Main Tabs
+
+1. **Global Skills**
+   - Manage cross-project skills stored across all detected agent home directories on your machine.
+   - Categorize and toggle skills by source; same-name precedence automatically highlights shadowed copies.
+2. **Project Skills**
+   - Select any registered workspace from the dropdown to manage its project-level skills (`<project>/.dsh/skills`, etc.).
+   - Scans and searches only the selected workspace; project copies take precedence over global counterparts.
+3. **Discover**
+   - **Public Catalogs**: Direct integration with ClawHub and skills.sh to find and install popular community skills;
+   - **GitHub Repositories**: Subscribe to public repositories, scan skill lists, preview diffs, and install copies with local edit protections.
+4. **Trash**
+   - Soft-delete buffer for DSH and Shared Agent skills, preserving provenance and install destinations.
+   - Deleted skills can be restored anytime with a single click.
+
+### Skill Naming & Frontmatter Requirements
+
+The DeepSeek Harness loader enforces strict identifier policies:
+- **Format constraint**: Host loaders require skill names to strictly match lowercase ASCII alphanumeric characters and hyphens (kebab-case, e.g. `my-tool`).
+- **Non-ASCII & Chinese skill folders**: Your skill directory name can remain in Chinese (e.g. `文案排版/`), provided you specify a valid English `name` in `SKILL.md` frontmatter:
+  ```markdown
+  ---
+  name: copy-formatting-helper
+  description: Helper for multi-platform article formatting
+  ---
+
+  # Skill instructions...
+  ```
+- **Diagnostics**: Skills lacking an English name are flagged with clear in-app diagnostics explaining that the host loader cannot invoke them, with options to safely disable or clean up records.
+
+### Repository & Installation Boundaries
+
+- The header **Check for updates** updates the plugin itself; repository **Refresh** checks subscribed skill contents without replacing local files.
+- Repository installation can target user DSH skills, Shared Agent (`~/.agents/skills`, overridable via `DSH_AGENTS_HOME`), or `<project>/.dsh/skills` for registered workspaces. Unsafe paths and external agent roots (Codex, Claude) are locked against writes.
+- 32 MiB archive limit; downloading subdirectories still fetches the full archive.
+- Local edits are detected and require explicit confirmation before overwriting; backup history is preserved for rollback.
 
 ## Supported Agent directories
 

package/README.zh-CN.md

@@ -19,21 +19,19 @@
 
 > DSH Skills Manager 是社区维护的 DeepSeek Harness（DSH）插件，并非 DeepSeek AI 官方产品。
 
-本文描述 **1.2.12**。已发布变更见[更新日志](CHANGELOG.zh-CN.md)。
+本文描述 **1.2.13**。已发布变更见[更新日志](CHANGELOG.zh-CN.md)。
 
 ## 功能概览
 
 把散落在本机和项目中的技能集中到 DSH，无需在多个 Agent 目录间来回查找。
 
-- **统一管理**：按来源分组，搜索技能、查看正文，一键启用或停用。分类记在来源里，不移动文件。
-- **区分全局与项目**：项目页在顶部下拉选择已登记工作区，下方按来源显示该工作区的技能，列表样式与全局技能一致；同名技能优先使用项目副本。
-- **复用已有技能**：支持 Codex、Claude Code、Copilot 等常见 Agent，启停不会修改它们的源文件。
-- **创建与导入**：新建技能，或导入 ZIP、技能文件夹和 `SKILL.md`，保存到用户目录（默认）或已登记工作区。用户目录支持 DSH skills 与 Shared Agent。
-- **回收与恢复**：删除 DSH 技能后先进入回收站，误删可找回。
-- **技能仓库**：添加公开 GitHub 仓库，按来源折叠浏览、搜索、查看详情并逐项安装；同名不覆盖，刷新不自动更新本地。
-
-
-- **来源追踪与更新**：区分本机和仓库安装，预览文件差异，保护本地修改，确认后备份更新并可恢复上一版。
+- **多视图集中管理**：提供「全局技能」、「项目技能」、「发现」与「回收站」四大工作区视图，支持搜索、状态筛选与来源折叠。
+- **生态目录全覆盖**：支持 DSH、公共 Agent（Shared Agent）、Codex、Claude Code、Copilot、Cursor、Windsurf、Qoder、Trae 等 19+ 种常见开发工具与 CLI 生态，启停不修改第三方源文件。
+- **分类整理与拖拽归类**：支持在各来源内创建分类文件夹、拖拽技能卡片归类排序、批量添加技能，并支持分类级一键启停。分类元数据独立保存，不改动物理文件。
+- **公共市场与仓库订阅**：内置「发现」中心，一站式浏览 ClawHub 热门榜单与 skills.sh 技能市场，支持公开 GitHub 仓库订阅、增量更新检测与版本备份回退。
+- **创建与自由导入**：新建技能，或导入 ZIP、文件夹与 `SKILL.md`，可精准写入用户全局目录或指定工作区项目目录。
+- **宽屏阅读与正文复制**：760px 宽屏自适应详情弹窗，等宽字体代码高亮排版，支持垂直自由拉伸与一键复制 Markdown 正文。
+- **回收站与防误删保障**：DSH 技能删除后优先移入回收站，支持完整保留安装身份与更新历史的安全恢复。
 
 ## 界面预览
 
@@ -45,11 +43,11 @@
 
 ![项目技能管理界面](assets/screenshots/project-skills.webp)
 
-技能仓库：
+技能仓库与发现：
 
 ![技能仓库浏览与安装](assets/screenshots/skill-repositories.webp)
 
-*截图展示 1.1.18 版本的全局技能、项目技能与技能仓库。截图仅保留核心功能面板，已裁去背景中的多余留白与无关窗口，采用无损 WebP。*
+*截图展示核心功能面板，包含全局技能、项目技能与技能发现仓库。采用无损 WebP 格式。*
 
 ## 安装
 
@@ -75,34 +73,87 @@ dsh plugin --profile web add @michengai/dsh-skills-manager@latest --registry=htt
 
 安装后重启 DSH 并刷新页面，打开「设置 → 技能」即可使用。更新时可点击「检查更新」，或重新执行安装命令。
 
-- `1.2.12` 已验证兼容 DeepSeek Harness `0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-rc.1`、`0.2.1-rc.2`。
+- `1.2.13` 已验证兼容 DeepSeek Harness `0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-rc.1`、`0.2.1-rc.2`。
 - 不再支持 `0.2.0` 之前的宿主。仍在使用 `0.1.x` 的，请安装插件 `1.1.23`，不要装 `@latest`。
-
-## 使用说明
-
-| 你想做什么 | 如何操作 |
+- **反向代理部署**：支持将 DSH 部署在带路径前缀的反向代理后面（如 `/app/dsh/`），插件 API 统一自动按页面基址（`document.baseURI`）相对解析。
+
+## 插件配置与可选开关
+
+插件遵循 DSH 官方扩展配置规范，配置项位于：
+> **主界面侧边栏「插件」→ 点击 `Skills Manager` 详情页**（对应宿主 `plugins.bundle.config` 槽位）。
+
+此处提供两个原生扁平行开关：
+
+### 1. 侧边栏入口 (`sidebarEntry`)
+- **默认状态**：关闭（`false`）
+- **功能说明**：在宿主左侧主导航栏的「插件」下方增加常驻的 **「技能」** 图标入口。
+- **生效效果**：
+  - 开启后，在侧边栏点击即可直达技能管理中心，并在主工作区以 **960px 居中版心**（对齐官方插件管理与市场规范）展开完整大面板，彻底告别在设置弹窗狭窄视口内滚动的局限；
+  - 关闭后安全注销侧栏槽位；
+  - 无论是否开启侧栏入口，DSH 原有的「设置 → 技能」入口始终保留，两处界面数据与状态 100% 实时同步。
+
+### 2. 在线更新 (`onlineUpdate` / `updater`)
+- **默认状态**：开启（`true`）
+- **功能说明**：控制是否允许在线检查并安装技能管理器的新版本。
+- **生效效果**：
+  - **界面联动**：关闭开关后，技能管理面板顶部的「检查更新」按钮将即时隐藏，无需刷新页面；开启后自动恢复展示；
+  - **接口安全拦截**：关闭后，服务端的更新路由对任何版本检查和安装请求均返回 `HTTP 403` 禁用状态，彻底杜绝在插件内安装未审核版本；
+  - **宿主/平台级锁定**：面向精选插件索引（如 VibeDev）或企业安全合规环境，支持直接在 Cordis 配置文件（bundle patch）中声明，无需进入界面手动配置：
+    ```yaml
+    updater: false # 或 onlineUpdate: false
+    ```
+    配置生效后，更新器在启动时即被完全禁用，且更新入口默认保持隐藏。
+
+## 使用指南
+
+| 核心操作 | 操作方式 |
 | --- | --- |
-| 查找技能 | 选择全局或项目页签，展开来源分组，或使用搜索和筛选。 |
-| 查看内容 | 点击「查看详情」，阅读技能正文及来源信息。 |
-| 控制启停 | 切换技能开关；只影响 DSH，不改动源文件。 |
-| 添加技能 | 点击「创建技能」或「导入技能」，左侧下拉选择「用户目录」（默认）或「指定工作区」，右侧下拉选择位置或已登记工作区，并核对下方路径。工作区副本会写进该项目的 `.dsh/skills`，可能被提交到仓库。 |
-| 从仓库安装 | 打开「技能仓库 → 添加仓库」，填写公开 GitHub 地址，扫描后点击「安装」，使用同一组并排下拉选择范围及位置或工作区，核对下方实际路径并确认。 |
-| 卸载仓库技能 | 点击红色「卸载」并确认。已登记工作区里的副本也同样可以卸载。已安装的文件夹及本地修改移入「回收站」，随后可以重新安装。 |
-| 更新仓库技能 | 点击「刷新并检查更新」，再「查看更新」预览文件差异，确认备份后更新。 |
-| 恢复更新前版本 | 对有备份的技能点击「恢复上一版」，预览并确认。 |
-| 找回误删 | 打开「回收站」恢复。 |
-
-- **按已登记工作区查看**：项目页顶部下拉列出 DSH 里已登记的工作区，选中后只读取并显示这一项的技能，搜索也只针对所选工作区。Git 仓库使用最近的 Git 根目录；普通文件夹使用工作区目录，无需 `git init`。没有技能的工作区也可选择，失效目录不可选。
-- **同名技能独立启停**：停用项目副本后，其他已启用副本仍可接管，页面会提示实际来源。要完全关闭该技能，需停用全部副本。
-- **文件管理范围**：用户级 DSH 和公共 Agent（Shared Agent）来源的普通技能均可从管理页移入回收站并恢复，不要求安装来源记录。用户级和项目 DSH 的顶层目录链接也会列出，可以查看和启停，不能删除或覆盖；项目 Shared Agent 仍只读。公共 Agent 保留递归发现和链接读取，链接条目及不安全路径不允许文件写入；从仓库安装到 DSH、公共 Agent 或已登记工作区的副本也可从「技能仓库」卸载。Codex、Claude 等其他外部技能仍只读。创建、文件导入和仓库安装可以写入用户目录下的 DSH skills 或公共 Agent（Shared Agent），也可以写入某个已登记工作区的 `.dsh/skills`。创建、导入和安装时，工作区不会被预先选中，也不能选 Shared Agent；项目页的只读查看选择不作为写入目标。
-- **恢复**：已卸载副本的仓库来源绑定到具体回收站条目；仅显式恢复后重新启用来源、安装位置和更新/恢复历史。其他同名技能不会继承仓库管理权限。卸载公共 Agent 副本会影响使用该目录的所有 Agent。
-
-### 仓库使用边界
-
-- 标题区「检查更新」更新插件自身；仓库区「刷新并检查更新」检查技能内容，不自动安装或替换。刷新时显示当前仓库、数量和动画。
-- 仓库安装可以写入用户目录下的 DSH skills 或公共 Agent（`~/.agents/skills`，可用 `DSH_AGENTS_HOME` 覆盖），也可以写入已登记工作区的 `<项目根>/.dsh/skills`。选择器显示实际配置路径，并禁用不安全路径；缺少的目录仅在确认安装后创建。不能安装到 Codex、Claude 等其他 Agent 目录，也不允许任意路径、未登记项目目录或插件托管缓存写入。旧安装记录未指定位置时默认使用 DSH；更新与恢复上一版沿用记录的位置。仅支持公开 GitHub，不提供私有凭证或自动更新。移除订阅保留已安装技能。
-- 归档上限 32 MiB，指定子目录也需下载整库。扫描失败保留上次目录；缓存损坏时重新刷新。
-- 更新前检测本地修改，覆盖必须明确确认；历史备份不自动清理，磁盘用量会增加。
+| **检索技能** | 切换「全局技能」或「项目技能」页签，按来源分组折叠/展开，或使用顶部搜索框与状态筛选器。 |
+| **阅读技能** | 点击技能行右侧「查看详情」，在 760px 宽屏弹窗中阅读 `SKILL.md` 正文及诊断信息，支持一键「复制正文」。 |
+| **控制启停** | 点击技能行右侧开关，切换其在 DSH 中的调用状态；仅影响 DSH 智能体执行，绝不改动第三方源文件。 |
+| **分类与拖拽** | 在来源内点击「新建分类」，拖拽左侧把手（`⋮⋮`）直接跨分类移动或同组排序；支持分类一键批量启停与多选添加。 |
+| **创建与导入** | 点击顶栏「创建技能」或「导入技能」，并排选择写入目标（用户目录或已登记工作区项目目录），系统自动核对安全路径。 |
+| **发现与安装** | 切换到「发现」页签，浏览 ClawHub 热榜或搜索 skills.sh 目录，或点击「添加仓库」订阅公开 GitHub 仓库。 |
+| **仓库技能更新** | 点击「刷新」，再点击「查看更新」预览文件 Diff 差异，确认后自动创建本地备份并完成更新。 |
+| **版本回退** | 对存在备份的技能点击「恢复上一版」，预览差异并确认恢复。 |
+| **回收与防误删** | 删除的 DSH 技能自动进入「回收站」，可随时完整恢复或永久删除。 |
+
+### 技能管理四大板块
+
+1. **全局技能（Global Skills）**
+   - 集中展示当前电脑上所有 Agent 目录下的全局技能（跨项目通用）。
+   - 支持按来源启停、按分类组织；当不同来源存在同名技能时，自动遵循优先级遮盖并给出来源提示。
+2. **项目技能（Project Skills）**
+   - 顶部下拉选择当前 DSH 已登记的工作区目录，下方展示该项目所属的 Agent 技能。
+   - 仅扫描并管理所选工作区；项目级同名技能优于全局副本生效。
+3. **发现（Discover）**
+   - **公共市场**：集成 ClawHub 热门下载榜与 skills.sh 全球技能库，输入关键字即可检索全球开源技能，一键完成多副本安装；
+   - **GitHub 仓库订阅**：输入 GitHub 仓库地址，整仓扫描技能清单，支持增量版本比对、本地修改保护与更新备份。
+4. **回收站（Trash）**
+   - 存放从 DSH 或公共 Agent 来源中删除的技能副本，保留原始安装位置与关联信息。
+   - 误删技能可一键恢复回原目录，彻底杜绝意外丢失。
+
+### 技能命名与 Frontmatter 规范
+
+DeepSeek Harness 宿主加载机制对技能标识符遵循规范命名约束：
+- **名称格式**：宿主严格要求技能名称必须为 ASCII 小写字母、数字与连字符构成的 kebab-case 格式（如 `my-custom-skill`）；
+- **中文技能目录自救**：您的技能文件夹名称可以继续使用直观的中文名称（如 `文案排版/`），只需在其 `SKILL.md` 的 YAML frontmatter 中显式声明合法的英文 `name` 即可被宿主正常加载和调用：
+  ```markdown
+  ---
+  name: copy-formatting-helper
+  description: 微信公众号与多平台文案排版辅助工具
+  ---
+
+  # 技能正文内容...
+  ```
+- **界面智能诊断**：若本地存在缺少英文 `name` 的纯中文技能，管理器会在界面明确给出「宿主不支持此技能名称格式，无法启用」的诊断指引，并允许停用清理历史脏记录。
+
+### 仓库与安装边界
+
+- 顶栏「检查更新」用于更新技能管理器插件自身；仓库区「刷新」仅检查技能仓库内容更新，不自动覆盖本地。
+- 仓库安装可以写入用户目录下的 DSH skills 或公共 Agent（`~/.agents/skills`，可用 `DSH_AGENTS_HOME` 覆盖），也可以写入已登记工作区的 `<项目根>/.dsh/skills`。选择器显示实际配置路径，并禁用不安全路径；缺少的目录仅在确认安装后创建。不能安装到 Codex、Claude 等其他 Agent 目录。
+- 归档上限 32 MiB，指定子目录也需下载整库。
+- 更新前检测本地修改，覆盖必须明确确认；历史备份不自动清理，可随时恢复上一版。
 
 ## 支持的 Agent 目录