npm - @daweifu/capability-menu - Versions diffs - 0.1.4 → 0.1.5 - Mend

@daweifu/capability-menu 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/README.en.md +72 -87
package/README.md +74 -89
package/cordis.patch.yml +7 -0
package/lib/client.d.ts +15 -3
package/lib/client.d.ts.map +1 -1
package/lib/client.js +710 -442
package/lib/locations.js +168 -5
package/lib/locations.js.map +1 -1
package/lib/patch-file.js +33 -3
package/lib/patch-file.js.map +1 -1
package/lib/policy.js +3 -0
package/lib/policy.js.map +1 -1
package/lib/registry.js +53 -10
package/lib/registry.js.map +1 -1
package/lib/search.js +4 -4
package/lib/search.js.map +1 -1
package/lib/server/remote.js +7 -0
package/lib/server/remote.js.map +1 -1
package/lib/types/locations.d.ts +2 -0
package/lib/types/locations.d.ts.map +1 -1
package/lib/types/patch-file.d.ts.map +1 -1
package/lib/types/policy.d.ts +2 -0
package/lib/types/policy.d.ts.map +1 -1
package/lib/types/registry.d.ts.map +1 -1
package/lib/types/search.d.ts +2 -2
package/lib/types/server/remote.d.ts +2 -0
package/lib/types/server/remote.d.ts.map +1 -1
package/package.json +37 -21

package/README.en.md CHANGED Viewed

@@ -1,36 +1,45 @@
 <h1 align="center">dsh-capability-menu</h1>
 <p align="center">
-  <strong>One unified capability management surface for DeepSeek Harness: control the exposure level (context footprint) and execution of Tools and Skills</strong>
+  <strong>Manage how Tools and Skills are exposed and invoked in DeepSeek Harness, reducing context use through on-demand discovery</strong>
 </p>
 <p align="center">
-  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/v/@daweifu/capability-menu.svg?style=flat-square&color=0969DA&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
-  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/dt/@daweifu/capability-menu.svg?style=flat-square&color=0969DA&labelColor=161b22" alt="downloads"/></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek%20Harness-0.2.0--rc.1-4D6BFE.svg?style=flat-square&labelColor=161b22&logo=deepseek&logoColor=white" alt="DeepSeek Harness 0.2.0-rc.1"/></a>
+  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/v/@daweifu/capability-menu.svg?style=flat-square&color=CB3837&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
+  <a href="https://github.com/PKUfudawei/dsh-capability-menu/actions"><img src="https://img.shields.io/github/actions/workflow/status/PKUfudawei/dsh-capability-menu/ci.yml?branch=master&label=CI&style=flat-square&labelColor=161b22&logo=github&logoColor=white" alt="CI"/></a>
+  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/d18m/@daweifu/capability-menu.svg?style=flat-square&color=CB3837&labelColor=161b22&logo=npm&logoColor=white" alt="downloads"/></a>
   <a href="https://github.com/PKUfudawei/dsh-capability-menu"><img src="https://img.shields.io/github/stars/PKUfudawei/dsh-capability-menu.svg?style=flat-square&color=dbab09&labelColor=161b22&logo=github&logoColor=white" alt="GitHub stars"/></a>
-  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek%20Harness-0.1.5--rc.2-4D6BFE.svg?style=flat-square&labelColor=161b22&logo=deepseek&logoColor=white" alt="DeepSeek Harness 0.1.5-rc.2"/></a>
   <a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://img.shields.io/badge/featured%20in-awesome--dsh--plugin-8250DF?style=flat-square&labelColor=161b22&logo=github&logoColor=white" alt="featured in awesome-dsh-plugin"/></a>
-  <a href="https://github.com/PKUfudawei/dsh-capability-menu/actions"><img src="https://img.shields.io/github/actions/workflow/status/PKUfudawei/dsh-capability-menu/ci.yml?branch=master&label=CI&style=flat-square&labelColor=161b22&logo=github&logoColor=white" alt="CI"/></a>
 </p>
 <p align="center">
   <a href="./README.md">简体中文</a> · <strong>English</strong>
 </p>
-<br/>
 ## Table of Contents
 - [Capability Overview](#capability-overview)
-- [Quick Install](#quick-install)
+  - [Capability Model](#capability-model)
+  - [Capability Management](#capability-management)
+- [Installation and Uninstallation](#installation-and-uninstallation)
+  - [Install from npm (recommended)](#install-from-npm-recommended)
+  - [Install from source](#install-from-source)
+  - [Verify the install](#verify-the-install)
+  - [Uninstall](#uninstall)
 - [Exposure Policy](#exposure-policy)
+  - [Tools and Skills three-tier exposure and execution](#tools-and-skills-three-tier-exposure-and-execution)
 - [Configuration](#configuration)
+  - [All configuration options](#all-configuration-options)
+  - [On-demand capability catalog (`catalogFile`)](#on-demand-capability-catalog-catalogfile)
 ---
 ## Capability Overview
-dsh-capability-menu is a Cordis plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). It builds a unified capability catalog (`ctx.capability`) over a large number of tools / skills (MCP tools and harness-native built-in tools) and manages their **exposure level and execution** in three tiers — **Resident / On-demand / Disabled** — so you can adjust the agent's capability boundary at any time, keep a flood of tools/skills out of a single request, and save tokens and context. Changes apply immediately without restarting, and the plugin composes into the Harness runtime purely through the Cordis plugin mechanism — no upstream source is modified. **Without this plugin (policy) mounted, everything stays visible as before; mounted with no rules at all, every capability defaults to Resident.**
+- Builds a unified capability catalog (`ctx.capability`) for DeepSeek Harness tools (including MCP and built-in tools) and skills.
+- Provides three policy tiers — **Resident / On-demand / Disabled** — to manage capability exposure and invocation.
+- Supplies on-demand capabilities only when needed, reducing the tool definitions sent with each request and saving tokens and context.
 ### Capability Model
@@ -45,7 +54,7 @@ The model gets two meta tools:
 | tool | role | corresponding entry |
 | --- | --- | --- |
-| `meta_search` | search the capability catalog (Tool / Skill), list/detail dual mode | `@daweifu/capability-menu/search` |
+| `meta_search` | search Tool / Skill candidates; list summaries help choose one, while detail returns its full description and the tool schema or Skill usage guidance | `@daweifu/capability-menu/search` |
 | `meta_invoke` | unified execution surface: really executes Tools (full `ctx.tools` pipeline) + loads Skills | `@daweifu/capability-menu/invoke` |
 ### Capability Management
@@ -54,48 +63,42 @@ The model gets two meta tools:
   <img src="assets/screenshot-tools.png" alt="Tools tab" width="48%"/>
   <img src="assets/screenshot-skills.png" alt="Skills tab" width="48%"/>
 </p>
-<p align="center">
-  <img src="assets/screenshot-policy.png" alt="Policy &amp; catalog · Policy (effective)" width="48%"/>
-  <img src="assets/screenshot-catalog.png" alt="Policy &amp; catalog · On-demand catalog" width="48%"/>
-</p>
+After installation, open **Settings** and select **Capability Management** from the settings navigation to manage Tools and Skills.
-Once installed, a Capability Management tab appears under Settings → General Settings (between "Model" and "Plugins"). It is where you view and adjust a capability's exposure tier; changes apply immediately, no restart needed.
-| What you want to do | Where |
+| Task | How to do it |
 | --- | --- |
-| Change a tier | Click the dot on a capability row, or a tier count at the top to switch the whole group |
-| Register an MCP server / skill directory | Register capability, top right |
-| Edit or remove a registered entry | Edit on an MCP server's group header (Tools) or a skill row (Skills) |
-| See the effective policy and the On-demand catalog | Policy &amp; catalog, on the header's description row |
-| The list is stale (you changed a source outside dsh) | Nothing to do: returning to the tab, a settings change and a carrier reconnect all re-read it, with a ~5s poll as the backstop |
-| Find a capability in a long list | The filter box under the tab bar matches a name **and the group it sits in** (server / source / preset id), case-insensitively, and takes a regex (shared by Tools and Skills) |
-**The tier is that dot**: filled = Resident (the model calls it directly), half-filled ring = On-demand (reached through `meta_search` → `meta_invoke`), ring with a slash (a no-entry sign) = Disabled. If a higher-priority rule (a wildcard, say) overrides it, the UI reports that the classification did not apply.
-**How the page is laid out**: the Tools tab groups by server and folds — MCP tools under their own server, harness-native tools together under the built-in group; the Skills tab splits into "Global skills" / "Project skills" / "Preset skills" — **the third appears only when skills that ship with an agent preset actually exist** (without them the tab bar stays at two), and preset ids are section headings inside that tab rather than another level of tabs. A filter box under the tab bar matches names and the group a row sits in and accepts a regex, which beats folding groups once a list gets long. Click a capability row for its model-facing definition, a skill row to expand its directory tree, and a file to preview it.
-**Three behaviours worth knowing**:
-- **A tier click does not hit disk immediately**: it changes memory first (so it feels instant) and is written back to `patchFile` (the home layer's `~/.dsh/cordis.patch.yml` by default) once you stop for ~1.5s — writing that file makes dsh hot-reload this plugin, so it cannot happen on every click.
-- **Registering writes files**: an MCP server goes into the same patch file (an `@deepseek-ai/dsh-mcp-client` row, mounted natively by dsh — this plugin never manages the connection), and a skill directory becomes a symlink under the skill root. Credentials such as headers are stored there in **plain text**.
-- **Some skill rows offer Adopt rather than Edit**: those are skills in user-level roots such as `~/.agents/skills` / `customSkillDirs`. The confirmation names the directory it currently lives in, and confirming links it into `~/.dsh/skills/` with the **content untouched**; rows that cannot be adopted show their source instead. **Skills that ship with an agent preset are never adoptable**: linking a preset asset into the user skill root would make it apply to every session, the opposite of "visible only to sessions that mount this preset", so those rows just say "From preset X".
+| Change a tier | Click the dot beside a capability. Click a tier count at the top to change the whole group. |
+| Find a capability | Use the filter below the tabs to search by name or group. Regex is supported and matching is case-insensitive. |
+| View details | Click a Tool to see its definition. Click a Skill to expand its files and preview them; content is rendered as Markdown. |
+| Register a capability | Click **Register capability** in the top right to add an MCP server or Skill directory; Skills accept local paths or public GitHub URLs. |
+| Edit or remove | Click **Edit** on a server group in Tools or a Skill row in Skills. |
+| View policies and catalog | Click **Policy &amp; catalog** on the right side of the page header. |
-> **Skill sources and same-name handling**: a row's source label comes from dsh's provider (`project-dsh` / `user-agents` / `custom` / `bundled` …), and a **preset skill and a user-configured `customSkillDirs` entry are both labelled `custom`** — only scope provenance tells them apart, so grouping uses the preset id recorded while scanning, never the source label. Tier rules apply by **bare name**: same-named skills across scopes share one switch, and indexing is **global layer first, then presets in order** (matching the tool side); a name collision does not affect tiers, but only one of the implementations shows up in the list.
+Registering an MCP server writes its patch configuration; a missing file or parent directory is created automatically. MCP credentials such as request headers are stored in the config; keep it secure. Skill registration creates a link or imports a directory into the selected skill root.
-What each form field means, how visible a global versus a project skill is, what a removal actually costs, and how `SKILL.md` is validated are all stated where you act on them — no need to repeat them here.
+GitHub Skill imports accept a default-branch root URL (the root must contain `SKILL.md`), a specific branch root `https://github.com/{owner}/{repo}/tree/{branch}`, or a Skill subdirectory `https://github.com/{owner}/{repo}/tree/{branch}/{skill-directory}`. Local paths are also supported. Only public repositories are supported; Git must be installed on the machine running dsh. The plugin validates `SKILL.md` and copies only the selected directory.
-## Quick Install
+## Installation and Uninstallation
-Prerequisites: Node.js and the dsh CLI installed (`dsh plugin` forwards to pnpm internally).
+Prerequisites: [Node.js](https://nodejs.org/en/download) and the [dsh CLI](https://github.com/deepseek-ai/deepseek-harness). Compatible with DeepSeek Harness `0.1.5-rc.2` and `0.2.0-rc.1` (`dsh plugin` forwards to pnpm internally, so pnpm needs no separate install).
 ### Install from npm (recommended)
-A single package ships both the server-side plugin and the front-end Capability Management tab; once installed it shows up under Settings → General Settings:
+A single package ships both the server-side plugin and the front-end Capability Management page; after installation it appears as its own section in Settings:
 ```sh
+# install
 dsh plugin --profile web add @daweifu/capability-menu
+# upgrade to the version tagged latest on npm (name the version to avoid keeping the installed one)
+dsh plugin --profile web add "@daweifu/capability-menu@$(npm view @daweifu/capability-menu dist-tags.latest)"
+# To install a prerelease tag such as next, use that tag instead:
+# dsh plugin --profile web add "@daweifu/capability-menu@$(npm view @daweifu/capability-menu dist-tags.next)"
 ```
+The upgrade command installs the version pointed to by npm's `latest` tag; use the matching tag or an explicit version for prereleases.
 ### Install from source
 ```sh
@@ -109,21 +112,7 @@ dsh plugin --profile web add ./dsh-capability-menu
 ### Verify the install
 ```sh
-dsh --profile web --dump-config | grep -E 'capability-menu'
-```
-```
-# == @daweifu/capability-menu
-- id: capability-menu-registry
-  name: '@daweifu/capability-menu/registry'
-- id: capability-menu-search
-  name: '@daweifu/capability-menu/search'
-- id: capability-menu-invoke
-  name: '@daweifu/capability-menu/invoke'
-- id: capability-menu-policy
-  name: '@daweifu/capability-menu/policy'
-- id: capability-menu
-  name: '@daweifu/capability-menu'
+cd "${DSH_HOME:-$HOME/.dsh}/profiles/web" && pnpm list @daweifu/capability-menu && dsh --profile web --dump-config | grep -m1 '== @daweifu/capability-menu'
 ```
 ### Uninstall
@@ -136,54 +125,56 @@ dsh plugin --profile web remove @daweifu/capability-menu
 All capabilities (Tool and Skill) fall into three tiers by their **exposure level** (what the model sees in the context) and their **execution mode**:
-### Tools / Skills three-tier exposure and execution
+### Tools and Skills three-tier exposure and execution
-| tier | capability | exposure (model view) | discovery | execution |
+| tier | capability | what the model sees | how to find it | how to use it |
 | --- | --- | --- | --- | --- |
-| **Resident** | tool | full schema in `assembly.tools` → the model's `tools` request payload, visible at every step | none (already resident) | model calls it directly; at runtime it goes through the full `ctx.tools` pipeline |
-| | skill | name + description in the `<available_skills>` catalog (body not in the catalog) | none (already resident) | the `skill` tool loads the body on demand (on-demand loading) |
-| **On-demand** | tool | not in the payload (zero context cost) | `meta_search` list / `grep` the materialized catalog YAML (`catalogFile`) | executed by `meta_invoke` (via `ctx.tools.execute`, full pipeline); or fetch the schema through detail and call it directly |
-| | skill | not in the `<available_skills>` catalog | `meta_search`, or `grep` the materialized catalog YAML (`catalogFile`) | `meta_invoke` loads the SKILL.md body (via `ctx.skills`) |
-| **Disabled** | tool | not in the payload | not returned by `meta_search`, not written to the catalog YAML | refused by `meta_invoke`; hallucinated direct calls are also hard-rejected in `tools/pre-execute` |
-| | skill | not in the `<available_skills>` catalog | not returned by `meta_search`, not written to the catalog YAML | refused by `meta_invoke`; the `skill` tool is hard-rejected in `tools/pre-execute` |
+| **Resident** | tool | Tool definition is included with every request | No search needed | Call directly; it goes through the full `ctx.tools` pipeline |
+| | skill | Name and summary appear in `<available_skills>` | No search needed | The `skill` tool loads the content when needed |
+| **On-demand** | tool | Tool definition is not included with requests | Search candidates with `meta_search` or search the capability catalog YAML (`catalogFile`) | Call with `meta_invoke`, or fetch details and parameters by exact id before calling directly |
+| | skill | Not shown in `<available_skills>` | Search with `meta_search` or search the capability catalog YAML (`catalogFile`) | Load `SKILL.md` with `meta_invoke` |
+| **Disabled** | tool | Tool definition is not included with requests | Hidden from search results and the capability catalog | Calls are rejected |
+| | skill | Not shown in `<available_skills>` | Hidden from search results and the capability catalog | Loads are rejected |
 > **Scope & reserved tools**:
-> - The tool tiers cover both `mcp__` cataloged tools and harness-native built-in tools (native tools are grouped under the reserved `built-in` server and are managed in all three tiers exactly like MCP tools). **Do not name a real MCP server `built-in`.**
-> - `meta_search`/`meta_invoke` are this plugin's control plane: always Resident, cannot be disabled (a rule that disables one fails at startup). `run_code` is the reserved Code Mode transport: it never enters the catalog, does not appear in Capability Management, and should not get tier rules.
-> - **Keep high-frequency core tools Resident**: an On-demand built-in tool leaves the model's resident view and needs a `meta_search` → `meta_invoke` two-hop call.
+> - Tiers apply to MCP and harness-native built-in tools; built-ins use the reserved `built-in` group. **Do not name an MCP server `built-in`.**
+> - `meta_search` and `meta_invoke` are always Resident and cannot be disabled. `run_code` is reserved for Code Mode; it is excluded from the catalog and menu and needs no tier rule.
+> - **Keep high-frequency core tools Resident**: On-demand built-ins require `meta_search` → `meta_invoke` to use.
 ## Configuration
-Rules are declared under the `config` of this plugin's `capability-menu-policy` entry — by default in the home layer's `~/.dsh/cordis.patch.yml` (`$DSH_HOME` wins), and a profile's `cordis.patch.yml` can also amend it with an id-targeted override patch (the outer `- insert:` / `id` / `name` is Cordis patch boilerplate and has nothing to do with the rules):
+Rules live under `config` in this plugin's `capability-menu-policy` entry:
+- The default file is `~/.dsh/cordis.patch.yml`; when `$DSH_HOME` is set, the file is `$DSH_HOME/cordis.patch.yml`.
+- Edit the YAML directly or use Capability Management. UI clicks update memory immediately and write back about 1.5 seconds after input stops, batching writes to avoid repeated hot reloads and catalog rebuilds.
+- A profile can override the rules in its own `cordis.patch.yml`, targeting the entry ID. In examples, `- insert:`, `id`, and `name` are Cordis patch structure, not policy fields.
 ```yaml
 config:
   tools:
-    resident:
+    resident: # Resident
       - execute_cmd
       - get_session_context
       - search_kb
       - 'mcp__gongfeng__*'    # wildcard: everything under this server is resident
-    on-demand:
+    on-demand: # On-demand
       - 'mcp__*'              # wildcard fallback
       - 'server:km:*'         # bulk on-demand by server prefix
-    disabled:
+    disabled: # Disabled
       - 'mcp__secret__*'      # disabled outranks everything, even resident
   skills:
-    resident:
+    resident: # Resident
       - debugging
       - coding
-    on-demand:
+    on-demand: # On-demand
       - legacy_skill          # explicit on-demand (unlisted skills default to resident)
-    disabled:
+    disabled: # Disabled
       - forbidden_skill
   metaTools:
     - meta_search             # always resident; cannot be disabled
     - meta_invoke
 ```
-> Config keys are the tier words themselves: `resident` (常驻) / `on-demand` (按需) / `disabled` (禁用).
 ### All configuration options
 | Option | Entry | Default | Description |
@@ -195,7 +186,9 @@ config:
 | `skillsDir` | `capability-menu-policy` | `~/.dsh/skills` | Skill root used by skill directory registration |
 | `persistDebounceMs` | `capability-menu-policy` | `1500` | Debounce window (ms) before a clicked tier change is written back to the patch file |
-**Rule priority** (first match wins; within one tier, an exact rule beats a wildcard):
+These settings belong to their respective plugin entries and usually live in the same `cordis.patch.yml`; they do not require separate config files. `catalogFile` is the generated catalog for model-side search, while `skillsDir` is a directory for Skills.
+**Rule priority** (evaluated in order: Disabled always wins; between Resident and On-demand, exact rules beat wildcards):
 | priority | rule | example | effect |
 | --- | --- | --- | --- |
@@ -207,21 +200,13 @@ config:
 | 6 | `on-demand` wildcard | `on-demand: ['mcp__*']` | bulk on-demand fallback |
 | default | no rule matched | — | resident |
-Key points:
-- **Exact rules win over wildcards (even across tiers)**: e.g. with `resident: ['mcp__gongfeng__*']` in place, clicking a tool to On-demand in the Capability Management writes an exact `on-demand` rule that takes effect instead of being pushed back by the wildcard (if a higher-priority rule still overrides it, the UI reports that the classification did not apply).
-> **Two kinds of change, both persisted**:
->
-> - **Tier classification** changes memory first (so a click takes effect immediately) and is written back to this plugin's entry `config` (`patchFile`, the home layer's `~/.dsh/cordis.patch.yml` by default) once you stop for ~1.5s — writing that file makes dsh hot-reload this plugin and re-run the capability enumeration, so it cannot happen on every click. To batch-declare rules under version control, edit that same entry; no import/export buttons are needed.
-> - **Registered sources** (MCP servers, skill directories) hit disk as you click: MCP rows go into the same patch file (as `@deepseek-ai/dsh-mcp-client` entries), skill directories are linked into the skill root.
+If a higher-priority rule overrides a selected tier, the UI reports that the classification did not apply.
-### On-demand capability catalog (`catalogFile`, the single materialized catalog, searchable with `grep`)
+### On-demand capability catalog (`catalogFile`)
-On-demand capabilities are materialized into **one auto-generated YAML file** the model can browse:
+The plugin writes On-demand Tools and Skills to the YAML file specified by `catalogFile` so the model can search them. The default is `~/.dsh/capability-catalog.yaml`; set it to an empty string to disable the catalog. The catalog is updated when Tools, Skills, or tiers change. When there are no On-demand capabilities, the model receives no catalog hint.
-- The file location is the `config.catalogFile` of the **registry entry** (`capability-menu-registry`): it defaults to `~/.dsh/capability-catalog.yaml` and an empty string disables emission. The registry rewrites it automatically on any tool/skill or classification change. When nothing is On-demand, the catalog pointer is not injected (saving context).
-- A skill must first be **registered in `ctx.skills`** (a skill provider — e.g. its SKILL.md under a user/project skills root or `customSkillDirs`) to show up automatically; there is **no separate user-maintained input file**.
-- The model browses the file with `grep`/`read` (or calls `meta_search`) to get an entry's id and `kind`, then calls `meta_invoke(id, kind)` to run/load it. Skill ids are the bare name (e.g. `frontend-design`); `kind` distinguishes tools from skills.
+A Skill must be registered in `ctx.skills` to appear in the catalog. The model can search it with `grep` / `read` or call `meta_search`, then use the capability with `meta_invoke`. Each entry has an `id` and `kind`; a Skill's id is its name.
 ```yaml
 # ~/.dsh/capability-catalog.yaml (auto-generated; contains only On-demand
@@ -241,7 +226,7 @@ capabilities:
     whenToUse: Use when working on legacy projects
 ```
-> The catalog file is written under the host's `~/.dsh` by default, so the sandbox of the model-side `bash`/`read` tools must be able to reach that path. If the sandbox isolates the host directory, explicitly configure `catalogFile` to a path the sandbox can see. The default path is shared across multiple dsh instances (last-write-wins); in multi-instance deployments, give each instance its own `catalogFile`.
+If the model-side `bash` / `read` sandbox cannot access the default directory, set `catalogFile` to a path it can reach. Multiple DSH instances share the default file; use a different path for each instance when they need separate catalogs.
 ## License

package/README.md CHANGED Viewed

@@ -1,36 +1,45 @@
 <h1 align="center">dsh-capability-menu</h1>
 <p align="center">
-  <strong>为 DeepSeek Harness 统一管理 Tools 和 Skills 的暴露水平（上下文占用大小）与执行方式</strong>
+  <strong>统一管理 DeepSeek Harness 中 Tools 与 Skills 的暴露策略和调用方式，按需发现与调用，减少上下文占用</strong>
 </p>
 <p align="center">
-  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/v/@daweifu/capability-menu.svg?style=flat-square&color=0969DA&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
-  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/dt/@daweifu/capability-menu.svg?style=flat-square&color=0969DA&labelColor=161b22" alt="downloads"/></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek%20Harness-0.2.0--rc.1-4D6BFE.svg?style=flat-square&labelColor=161b22&logo=deepseek&logoColor=white" alt="DeepSeek Harness 0.2.0-rc.1"/></a>
+  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/v/@daweifu/capability-menu.svg?style=flat-square&color=CB3837&labelColor=161b22&logo=npm&logoColor=white" alt="npm version"/></a>
+  <a href="https://github.com/PKUfudawei/dsh-capability-menu/actions"><img src="https://img.shields.io/github/actions/workflow/status/PKUfudawei/dsh-capability-menu/ci.yml?branch=master&label=CI&style=flat-square&labelColor=161b22&logo=github&logoColor=white" alt="CI"/></a>
+  <a href="https://www.npmjs.com/package/@daweifu/capability-menu"><img src="https://img.shields.io/npm/d18m/@daweifu/capability-menu.svg?style=flat-square&color=CB3837&labelColor=161b22&logo=npm&logoColor=white" alt="downloads"/></a>
   <a href="https://github.com/PKUfudawei/dsh-capability-menu"><img src="https://img.shields.io/github/stars/PKUfudawei/dsh-capability-menu.svg?style=flat-square&color=dbab09&labelColor=161b22&logo=github&logoColor=white" alt="GitHub stars"/></a>
-  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek%20Harness-0.1.5--rc.2-4D6BFE.svg?style=flat-square&labelColor=161b22&logo=deepseek&logoColor=white" alt="DeepSeek Harness 0.1.5-rc.2"/></a>
   <a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://img.shields.io/badge/featured%20in-awesome--dsh--plugin-8250DF?style=flat-square&labelColor=161b22&logo=github&logoColor=white" alt="featured in awesome-dsh-plugin"/></a>
-  <a href="https://github.com/PKUfudawei/dsh-capability-menu/actions"><img src="https://img.shields.io/github/actions/workflow/status/PKUfudawei/dsh-capability-menu/ci.yml?branch=master&label=CI&style=flat-square&labelColor=161b22&logo=github&logoColor=white" alt="CI"/></a>
 </p>
 <p align="center">
   <strong>简体中文</strong> · <a href="./README.en.md">English</a>
 </p>
-<br/>
 ## 目录
 - [能力总览](#能力总览)
-- [快速安装](#快速安装)
+  - [能力模型](#能力模型)
+  - [能力菜单](#能力菜单)
+- [安装与卸载](#安装与卸载)
+  - [从 npm 安装（推荐）](#从-npm-安装推荐)
+  - [从源码安装](#从源码安装)
+  - [验证安装](#验证安装)
+  - [卸载](#卸载)
 - [暴露策略](#暴露策略)
-- [配置文件](#配置文件)
+  - [Tools 和 Skills 三档暴露与执行对照](#tools-和-skills-三档暴露与执行对照)
+- [配置](#配置)
+  - [全部配置项](#全部配置项)
+  - [按需能力目录（`catalogfile`）](#按需能力目录catalogfile)
 ---
 ## 能力总览
-dsh-capability-menu 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的一个 Cordis 插件，为海量 tools / skills（MCP 工具与内置原生工具）建立统一能力目录（`ctx.capability`），并以**常驻 / 按需 / 禁用**三档管理暴露程度和执行方式——随时调整 agent 的能力边界，避免海量 tools/skills 塞满一次请求、节省 token 和上下文。调整即时生效、无需重启，纯插件机制组合进 Harness 运行时，不改上游源码。**不挂载本插件（policy）时一切照旧、全量可见；挂载但未配置任何规则时，所有能力默认常驻。**
+- 为 DeepSeek Harness 的 tools（包括 MCP 工具和内置工具）与 skills 建立统一能力目录：`ctx.capability`。
+- 提供**常驻 / 按需 / 禁用**三档策略，管理能力的暴露与调用。
+- 按需能力只在需要时提供给 Agent，减少单次请求携带的工具定义，节省 token 和上下文。
 ### 能力模型
@@ -45,7 +54,7 @@ Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 c
 | 工具 | 作用 | 对应 entry |
 | --- | --- | --- |
-| `meta_search` | 检索能力目录（Tool / Skill），list/detail 双模式 | `@daweifu/capability-menu/search` |
+| `meta_search` | 搜索 Tool / Skill 候选项；列表摘要用于筛选，详情返回指定能力的完整说明及工具参数 schema / Skill 使用提示 | `@daweifu/capability-menu/search` |
 | `meta_invoke` | 统一执行面：Tool 真执行（走完整 `ctx.tools` 管线）+ Skill 加载 | `@daweifu/capability-menu/invoke` |
 ### 能力菜单
@@ -54,48 +63,42 @@ Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 c
   <img src="assets/screenshot-tools.png" alt="Tools 页" width="48%"/>
   <img src="assets/screenshot-skills.png" alt="Skills 页" width="48%"/>
 </p>
-<p align="center">
-  <img src="assets/screenshot-policy.png" alt="策略与目录 · 三档策略配置" width="48%"/>
-  <img src="assets/screenshot-catalog.png" alt="策略与目录 · 按需能力目录" width="48%"/>
-</p>
+安装后，在「设置」导航中选择「能力菜单」，即可管理 Tools 和 Skills。
-安装后，「设置 / 通用设置」下出现「能力菜单」tab（在「模型」与「插件」之间），用来查看和调整能力的暴露档位，改动即时生效、无需重启。
-| 想做什么 | 在哪 |
+| 操作 | 用法 |
 | --- | --- |
-| 切档位 | 点能力行右侧的圆点；或点顶部的档位计数，整组切 |
-| 在长列表里找能力 | 页签栏下方的过滤框，匹配名字**和所属分组**（server / 来源 / preset id），忽略大小写、可写正则（Tools / Skills 共用） |
-| 注册 MCP 服务器 / Skill 目录 | 右上角「注册能力」 |
-| 编辑、移除已注册项 | Tools 页 server 分组头、Skills 页技能行右侧的「编辑」 |
-| 看当前生效策略与按需能力目录 | 页头说明行右侧的「策略与目录」 |
-| 列表没跟上（你在 dsh 之外改过来源） | 不用管：切回本页、配置变更、carrier 重连都会自动重读，另有约 5s 的兜底轮询 |
-**档位就是那个圆点**：实心 = 常驻（模型直接调用）、上半实心圆环 = 按需（走 `meta_search` → `meta_invoke`）、圆环 + 斜杠（禁行标志）= 禁用。被更高优先级规则（如通配）挡住时，界面会提示「分类未生效」。
-**页面结构**：Tools 页按 server 分组、可折叠，MCP 工具挂在各自 server 下，内置原生工具统一在「系统内置」组；Skills 页分「全局技能 / 项目技能 / 预设技能」子页签——**「预设技能」只在确实存在随 agent preset 分发的技能时出现**（没有就是原来的两个页签），组内以 preset id 作小标题，不再往下分层。页签下方是过滤框：匹配名字与所属分组、支持正则（列表长时比翻分组快）。点能力行看模型侧的工具定义，点技能行展开目录树、点文件预览正文。
-**三点需要知道的行为**：
-- **切档位不立刻落盘**：先改内存（所以响应快），停手约 1.5s 后才写回 `patchFile`（默认 home 层的 `~/.dsh/cordis.patch.yml`）——写这个文件会让 dsh 热重载本插件，所以不能每次点击都写。
-- **注册是写文件**：MCP 服务器写进同一个 patch 文件（`@deepseek-ai/dsh-mcp-client` 条目，由 dsh 原生挂载，插件不自己管连接）；Skill 在技能根下建软链。请求头等凭据**明文**存在那里。
-- **有的技能行给的是「纳入管理」而不是「编辑」**：`~/.agents/skills` / `customSkillDirs` 这类用户级根里的技能，确认框会写明它当前所在的目录，确认后软链进 `~/.dsh/skills/`，**内容不动**；不能纳管的行改为显示来源。**随 agent preset 分发的技能不提供「纳入管理」**：把预设资产软链进用户技能根等于让它对所有会话生效，与该类技能"只对挂载了预设的会话可见"的定位相反，因此这类行只显示「来自预设 X」。
+| 更改档位 | 点击能力旁的圆点；也可以点击顶部档位计数，批量切换该组能力 |
+| 查找能力 | 使用页签下方的过滤框搜索名称或分组；支持正则表达式，不区分大小写 |
+| 查看能力详情 | 点击 Tool 查看定义；点击 Skill 展开文件列表并预览文件，内容按 Markdown 渲染 |
+| 注册能力 | 点击右上角「注册能力」，添加 MCP 服务器或 Skill 目录；Skill 支持本机目录或公开 GitHub 链接 |
+| 编辑或移除 | 在 Tools 的服务器分组或 Skills 的技能项中点击「编辑」 |
+| 查看策略和目录 | 点击页头右侧的「策略与目录」 |
-> **技能来源与同名规则**：技能行上的来源标签来自 dsh 的 provider（`project-dsh` / `user-agents` / `custom` / `bundled` …），而**预设技能和用户自配的 `customSkillDirs` 都是 `custom`**——两者只能靠作用域归属区分，所以分组用的是扫描时记下的 preset id，不是来源标签。档位规则按**裸名字**生效：同名技能跨作用域共享同一个开关，且索引时**全局层优先、预设之间先到先得**（与工具侧一致）；同名冲突不影响档位，但会让另一份实现不出现在列表里。
+注册 MCP 会写入 patch 配置；文件或父目录缺失时会自动创建。MCP 请求头等凭据保存在配置中，请妥善保管。注册 Skill 则会在所选技能根目录创建链接或导入目录。
-字段含义与可见范围（全局 / 项目）、移除的具体后果、注册时的 `SKILL.md` 校验口径，都在你操作的那一刻写着，这里不重复。
+GitHub Skill 支持默认分支根目录链接（需含 `SKILL.md`）、指定分支根目录 `https://github.com/{owner}/{repo}/tree/{branch}`，以及指定分支下的技能目录 `https://github.com/{owner}/{repo}/tree/{branch}/{skill-directory}`。也可输入本机目录。仅支持公开仓库；导入需要运行 dsh 的机器安装 Git，插件会校验 `SKILL.md` 并只复制所选目录。
-## 快速安装
+## 安装与卸载
-前置：已安装 Node.js 与 dsh CLI（`dsh plugin` 内部会转发给 pnpm）。
+前置：[Node.js](https://nodejs.org/en/download) 与 [dsh CLI](https://github.com/deepseek-ai/deepseek-harness)；支持 DeepSeek Harness `0.1.5-rc.2` 和 `0.2.0-rc.1`（`dsh plugin` 内部会转发给 pnpm，不用单独装 pnpm）。
 ### 从 npm 安装（推荐）
-单包同时提供服务端插件与前端「能力菜单」tab，装完即可在「设置 / 通用设置」下看到：
+单包同时提供服务端插件与前端「能力菜单」页面，安装后会作为「设置」中的独立栏目显示：
 ```sh
+# 安装
 dsh plugin --profile web add @daweifu/capability-menu
+# 升级到 npm 的 latest 标签指向的版本（要显式带版本号，避免沿用已安装版本）
+dsh plugin --profile web add "@daweifu/capability-menu@$(npm view @daweifu/capability-menu dist-tags.latest)"
+# 若要安装 next 等预发布标签，请把 latest 换成对应标签名，例如：
+# dsh plugin --profile web add "@daweifu/capability-menu@$(npm view @daweifu/capability-menu dist-tags.next)"
 ```
+升级命令安装 npm `latest` 标签指向的版本；安装预发布版本请使用对应标签或指定版本号。
 ### 从源码安装
 ```sh
@@ -109,21 +112,7 @@ dsh plugin --profile web add ./dsh-capability-menu
 ### 验证安装
 ```sh
-dsh --profile web --dump-config | grep -E 'capability-menu'
-```
-```
-# == @daweifu/capability-menu
-- id: capability-menu-registry
-  name: '@daweifu/capability-menu/registry'
-- id: capability-menu-search
-  name: '@daweifu/capability-menu/search'
-- id: capability-menu-invoke
-  name: '@daweifu/capability-menu/invoke'
-- id: capability-menu-policy
-  name: '@daweifu/capability-menu/policy'
-- id: capability-menu
-  name: '@daweifu/capability-menu'
+cd "${DSH_HOME:-$HOME/.dsh}/profiles/web" && pnpm list @daweifu/capability-menu && dsh --profile web --dump-config | grep -m1 '== @daweifu/capability-menu'
 ```
 ### 卸载
@@ -136,54 +125,56 @@ dsh plugin --profile web remove @daweifu/capability-menu
 所有能力（Tool 与 Skill）按 **暴露程度**（模型在上下文中看到什么）与 **执行方式** 分为三档：
-### Tools / Skills 三档暴露与执行对照
+### Tools 和 Skills 三档暴露与执行对照
-| 档位 | 能力 | 暴露方式（模型视野） | 发现 | 执行方式 |
+| 档位 | 能力 | 模型能看到什么 | 如何找到 | 如何使用 |
 | --- | --- | --- | --- | --- |
-| **常驻** | tool | 完整 schema 进 `assembly.tools` → 模型请求 `tools` payload，每步可见 | 无需发现（已常驻） | 模型直接调用，运行时走完整 `ctx.tools` 管线 |
-| | skill | 名字+描述进 `<available_skills>` 目录（正文不在目录） | 无需发现（已常驻） | `skill` 工具按需加载正文（渐进加载） |
-| **按需** | tool | 不进 payload（零上下文成本） | `meta_search` list / `grep` 检索物化目录 YAML（`catalogFile`） | `meta_invoke` 执行（走 `ctx.tools.execute`，管线完整）；或 detail 拿 schema 后直接调 |
-| | skill | 不进 `<available_skills>` 目录 | `meta_search` 检索 / `grep` 检索物化目录 YAML（`catalogFile`） | `meta_invoke` 加载 SKILL.md 正文（经 `ctx.skills`） |
-| **禁用** | tool | 不进 payload | `meta_search` 不返回、目录 YAML 不写入 | `meta_invoke` 拒绝；模型幻觉直调也在 `tools/pre-execute` 被硬拒绝 |
-| | skill | 不进 `<available_skills>` 目录 | `meta_search` 不返回、目录 YAML 不写入 | `meta_invoke` 拒绝；`skill` 工具在 `tools/pre-execute` 硬拒绝 |
+| **常驻** | tool | 工具定义始终随请求提供 | 无需查找 | 直接调用；运行时经过完整 `ctx.tools` 管线 |
+| | skill | 名称和简介显示在 `<available_skills>` 中 | 无需查找 | `skill` 工具按需加载正文 |
+| **按需** | tool | 不随请求提供工具定义 | 用 `meta_search` 搜索候选项，或搜索能力目录 YAML（`catalogFile`） | 用 `meta_invoke` 调用；也可先按精确 id 查看详情和参数，再直接调用 |
+| | skill | 不显示在 `<available_skills>` 中 | 用 `meta_search` 搜索，或搜索能力目录 YAML（`catalogFile`） | 用 `meta_invoke` 加载 `SKILL.md` |
+| **禁用** | tool | 不随请求提供工具定义 | 搜索结果和能力目录中均不可见 | 调用会被拒绝 |
+| | skill | 不显示在 `<available_skills>` 中 | 搜索结果和能力目录中均不可见 | 加载会被拒绝 |
 > **覆盖与保留**：
-> - `tool` 档同时覆盖 `mcp__` 编目工具与内置原生工具——原生工具统一以保留的 `built-in` server 归组，与 MCP 工具一样三档可管。**请勿把真实 MCP server 命名为 `built-in`。**
-> - `meta_search`/`meta_invoke` 是本插件的控制面：恒常驻、不可被禁用（在规则里禁用它们会在启动时报错）。`run_code` 是 Code Mode 保留传输层：不进目录、不在「能力菜单」出现，请勿为它配置三档规则。
-> - **不建议把高频核心工具设为按需**：按需的内置工具会退出模型常驻视野，使用时需要 `meta_search` → `meta_invoke` 两跳调用。
+> - 三档策略同时覆盖 MCP 与内置原生工具；内置工具归入保留组 `built-in`。**请勿把 MCP server 命名为 `built-in`。**
+> - `meta_search` 和 `meta_invoke` 固定常驻且不可禁用。`run_code` 是 Code Mode 保留工具，不进目录或菜单，也无需配置档位。
+> - **高频核心工具建议设为常驻**：按需内置工具需经 `meta_search` → `meta_invoke` 两步调用。
+## 配置
-## 配置文件
+规则写在本插件 `capability-menu-policy` entry 的 `config` 下：
-规则写在本插件 entry（`capability-menu-policy`）的 `config` 下，默认落在 home 层的 `~/.dsh/cordis.patch.yml`（`$DSH_HOME` 优先），也可以由任一 profile 的 `cordis.patch.yml` 用一条按 id 定位的覆盖补丁改写（外层 `- insert:` / `id` / `name` 是 Cordis patch 的挂载样板，与规则无关）。**手写和「能力菜单」里点选都可以**：点选只改内存（所以响应快），停手约 1.5s 后再自动写回这个 entry——因为写这个文件会让 dsh 热重载本插件并重跑一次能力枚举，所以不能每次点击都写。
+- 默认文件是 `~/.dsh/cordis.patch.yml`；设置了 `$DSH_HOME` 时使用 `$DSH_HOME/cordis.patch.yml`。
+- 可手写 YAML，也可在「能力菜单」里点选。点选立即更新内存，停手约 1.5 秒后统一写回，避免频繁热重载和能力重建。
+- Profile 可在自己的 `cordis.patch.yml` 中按 entry ID 覆盖规则。示例中的 `- insert:`、`id`、`name` 属于 Cordis 补丁结构，不是策略字段。
 ```yaml
 config:
   tools:
-    resident:
+    resident: # 常驻
       - execute_cmd
       - get_session_context
       - search_kb
       - 'mcp__gongfeng__*'    # 通配：该 server 下全部常驻
-    on-demand:
+    on-demand: # 按需
       - 'mcp__*'              # 通配兜底
       - 'server:km:*'         # 按 server 前缀批量按需
-    disabled:
+    disabled: # 禁用
       - 'mcp__secret__*'      # 禁用优先级最高，压过常驻
   skills:
-    resident:
+    resident: # 常驻
       - debugging
       - coding
-    on-demand:
+    on-demand: # 按需
       - legacy_skill          # 显式按需（未列出即默认常驻）
-    disabled:
+    disabled: # 禁用
       - forbidden_skill
   metaTools:
     - meta_search             # 恒常驻，不可被禁用
     - meta_invoke
 ```
-> 配置键即档位英文词：`resident`（常驻）/ `on-demand`（按需）/ `disabled`（禁用）。
 ### 全部配置项
 | 配置项 | 归属 entry | 默认值 | 说明 |
@@ -195,7 +186,9 @@ config:
 | `skillsDir` | `capability-menu-policy` | `~/.dsh/skills` | 注册 Skill 目录的技能根 |
 | `persistDebounceMs` | `capability-menu-policy` | `1500` | 点选改动写回 patch 文件前的防抖窗口（ms）|
-**规则优先级**（从上到下命中即停；同档内精确规则优先于通配）：
+这些配置项分别属于对应的插件 entry，通常都写在同一份 `cordis.patch.yml` 里，不需要为每项单独建配置文件。`catalogFile` 是插件自动生成、供模型检索的目录文件；`skillsDir` 是 Skill 存放目录。
+**规则优先级**（按序匹配：禁用始终优先；在常驻与按需之间，精确规则优先于通配）：
 | 优先级 | 规则 | 示例 | 效果 |
 | --- | --- | --- | --- |
@@ -207,21 +200,13 @@ config:
 | 6 | `on-demand` 通配 | `on-demand: ['mcp__*']` | 兜底批量按需 |
 | 默认 | 未命中任何规则 | — | 常驻 |
-要点：
-- **精确规则优先于通配（跨档也成立）**：例如存在 `resident: ['mcp__gongfeng__*']` 时，在「能力菜单」把某工具点成按需会写入一条精确 `on-demand` 规则并生效，不会被通配压回；若仍被更高优先级规则覆盖，界面提示「分类未生效」。
-> **两类改动，落盘位置不同**：
->
-> - **三档分类**先只改内存（所以点击即时生效），停手约 1.5s 后自动写回本插件 entry 的 `config`（`patchFile`，默认 home 层的 `~/.dsh/cordis.patch.yml`）——写这个文件会让 dsh 热重载本插件并重跑一次能力枚举，所以不能每次点击都写。要在版本管理里批量声明规则，直接编辑同一条 entry 即可，无需额外的导入/导出按钮。
-> - **注册的来源**（MCP 服务器、Skill 目录）在点击当下就落盘：MCP 写进同一个 patch 文件（`@deepseek-ai/dsh-mcp-client` 条目），Skill 在技能根下建软链。
+若更高优先级规则覆盖了所选档位，界面会提示「分类未生效」。
-### 按需能力目录（`catalogFile`，唯一物化目录，grep 可检索）
+### 按需能力目录（`catalogFile`）
-On-demand 能力自动物化成**一个 YAML 文件**给模型检索（改档位只重写这个文件——库存没变，不需要重新枚举工具与各 agent preset 的技能层）：
+插件会把按需 Tool 和 Skill 写入 `catalogFile` 指定的 YAML 文件，供模型检索。默认路径为 `~/.dsh/capability-catalog.yaml`，设为空字符串可关闭；没有按需能力时，模型不会收到目录提示。目录会在 Tool、Skill 或档位变化后自动更新。
-- 文件位置在 **registry entry（`capability-menu-registry`）** 的 `config.catalogFile`，默认 `~/.dsh/capability-catalog.yaml`，置空禁用；工具/技能变更或分类调整后自动重写。没有任何按需能力时不注入目录指引，省上下文。
-- 技能必须**已注册进 `ctx.skills`**（SKILL.md 放用户/项目技能根或挂 `customSkillDirs`）才会自动出现；无独立手写输入清单。
-- 模型用 `grep`/`read` 浏览该文件（或调 `meta_search`）拿到条目的 id 与 `kind`，再调 `meta_invoke(id, kind)` 执行/加载。技能 id 即裸名（`frontend-design`），tool/skill 由 `kind` 区分。
+Skill 需要先注册到 `ctx.skills` 才会出现在目录中。模型可以用 `grep` / `read` 搜索目录，或调用 `meta_search` 查找条目，再通过 `meta_invoke` 使用对应能力。每个条目包含 `id` 和 `kind`，Skill 的 id 使用其名称。
 ```yaml
 # ~/.dsh/capability-catalog.yaml（自动生成；仅含 On-demand 能力，
@@ -239,7 +224,7 @@ capabilities:
     whenToUse: 处理旧工程时使用
 ```
-> 目录文件默认写在宿主 `~/.dsh`，需要模型侧 `bash`/`read` 工具的沙箱能访问该路径；若沙箱隔离宿主目录，请把 `catalogFile` 显式配置到沙箱可见的路径。默认路径在多个 dsh 实例间共享（last-write-wins），多实例部署时请为每个实例配置独立的 `catalogFile`。
+如果模型侧的 `bash` / `read` 沙箱无法访问默认目录，请把 `catalogFile` 改到沙箱可见的位置。多个 DSH 实例默认共用该文件；需要隔离时，为每个实例设置不同路径。
 ## License