@daweifu/capability-menu 0.1.2 → 0.1.4

package/README.en.md

@@ -7,9 +7,9 @@
 <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="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-2EA44F?style=flat-square&labelColor=161b22" alt="license"/></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.2--rc.1-4D6BFE.svg?style=flat-square&labelColor=161b22&logo=deepseek&logoColor=white" alt="DeepSeek Harness 0.1.2-rc.1"/></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>
 
@@ -55,16 +55,34 @@ The model gets two meta tools:
   <img src="assets/screenshot-skills.png" alt="Skills tab" width="48%"/>
 </p>
 <p align="center">
-  <img src="assets/screenshot-policy.png" alt="View capability catalog · Policy (effective)" width="48%"/>
-  <img src="assets/screenshot-catalog.png" alt="View capability catalog · On-demand catalog" width="48%"/>
+  <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>
 
-Once installed, a Capability Management tab appears under Settings → General Settings (between "Model" and "Plugins"). It lets you visualize and adjust the exposure policy; changes apply immediately, no restart needed:
+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.
 
-- **Tools / Skills tabs**: the top tab bar shows `Tools` and `Skills`; its right side holds the per-class counts and the "View capability catalog" button. The Tools tab groups every tool by server (collapsible). MCP tools hang under their own server (`gongfeng`/`km`…); harness-native tools from the agent presets (`bash`/`read`/`write`/`glob`/`grep`…) hang under the reserved "System built-in" group (server key `built-in`). Click a row to view the model-facing tool definition — name / description / parameters.
-- **Skills tab**: split into "Global skills" / "Project skills" sub-tabs (both always visible; the empty side shows an empty-state hint), and the per-class counts at the top follow the active sub-tab. Click a skill row to expand its directory tree; click a file to preview its content (e.g. the SKILL.md).
-- **Three-state dot & click-to-cycle**: every capability carries a classification dot — solid = Resident, top-half-filled ring = On-demand, ring with a slash (no-entry sign) = Disabled — with per-class counts at the top of the pane; click a capability's dot or a class count to cycle its classification (built-in tools are manageable exactly like MCP tools), and if a higher-priority rule (e.g. a wildcard) overrides it, the UI reports that the classification did not apply.
-- **View capability catalog**: the top-right button opens a read-only modal with the effective policy in a semantic view — every capability defaults to Resident, so `tools.resident` lists each server as `'*'`, exceptions appear only under `on-demand`/`disabled` grouped by server → tool name (skills have no server dimension, so `skills.resident` is just `'*'`) — plus the materialized On-demand catalog file (`catalogFile`) path and content. Persistence remains via the profile's `cordis.patch.yml`.
+| What you want to do | Where |
+| --- | --- |
+| 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".
+
+> **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.
+
+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.
 
 ## Quick Install
 
@@ -129,11 +147,14 @@ All capabilities (Tool and Skill) fall into three tiers by their **exposure leve
 | **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` |
 
-> The tool tiers in the table above 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 just like MCP tools). **An On-demand built-in tool leaves the model's resident view**: the model reaches it via `meta_search` and executes it with `meta_invoke` (a two-hop call) — so keep high-frequency core tools Resident. The `meta_search`/`meta_invoke` tools themselves and the reserved Code Mode transport `run_code` never enter the capability catalog; they are always Resident and cannot be cycled in the Capability Management.
+> **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.
 
 ## Configuration
 
-Rules are declared under the `config` of the `capability-menu-policy` plugin entry in the profile's `cordis.patch.yml` (the outer `- insert:` / `id` / `name` is Cordis patch boilerplate and has nothing to do with the rules):
+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):
 
 ```yaml
 config:
@@ -163,6 +184,17 @@ config:
 
 > Config keys are the tier words themselves: `resident` (常驻) / `on-demand` (按需) / `disabled` (禁用).
 
+### All configuration options
+
+| Option | Entry | Default | Description |
+| --- | --- | --- | --- |
+| `tools` / `skills` / `metaTools` | `capability-menu-policy` | see above | Tier rules; UI changes are written back to this entry's `config` after the debounce |
+| `catalogFile` | `capability-menu-registry` | `~/.dsh/capability-catalog.yaml` | Materialized on-demand catalog path; empty disables it |
+| `refreshDebounceMs` | `capability-menu-registry` | `200` | Debounce window (ms) for change-event rebuilds; `0` disables debouncing |
+| `patchFile` | `capability-menu-policy` | `~/.dsh/cordis.patch.yml` (`$DSH_HOME` wins) | Patch file that MCP server registration writes to |
+| `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):
 
 | priority | rule | example | effect |
@@ -176,21 +208,20 @@ config:
 | default | no rule matched | — | resident |
 
 Key points:
-- `meta_search`/`meta_invoke` are always resident and cannot be disabled.
 - **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).
-- Native tools are cataloged exactly like MCP tools (under the `built-in` server); unlisted native tools default to Resident. Once overridden by `on-demand`/`disabled` a native tool leaves the model's resident view — when On-demand it stays reachable via `meta_search` → `meta_invoke`. **Do not name a real MCP server `built-in`.**
 
-> Changes made in the Capability Management tab only write to in-memory runtime state and are not persisted. To persist them (apply with the profile, version-controllable / batch-declarable), edit the profile's `cordis.patch.yml` — that is the persistence entry point; no extra import/export buttons are needed.
+> **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.
 
 ### On-demand capability catalog (`catalogFile`, the single materialized catalog, searchable with `grep`)
 
 On-demand capabilities are materialized into **one auto-generated YAML file** the model can browse:
 
-**tools/skills change or classification change → the registry rewrites `catalogFile` → the model `grep`s/`read`s it (or calls `meta_search`) for an id + kind → `meta_invoke(id, kind)` runs/loads it**
-
-- Defaults to `~/.dsh/capability-catalog.yaml` (`catalogFile` configurable; empty string disables). 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`) and then switched to On-demand; there is **no separate user-maintained input file**.
-- Two discovery paths for the model: `grep` the catalog file / `meta_search` (structured schema); then call `meta_invoke` with the **`kind` reported by the same entry** to load/run it. Skill ids are the bare name (e.g. `frontend-design`) and `kind` distinguishes tools from skills. Bodies load via `ctx.skills` for skills and `ctx.tools.execute` for tools.
+- 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.
 
 ```yaml
 # ~/.dsh/capability-catalog.yaml (auto-generated; contains only On-demand

package/README.md

@@ -7,9 +7,9 @@
 <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="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-2EA44F?style=flat-square&labelColor=161b22" alt="license"/></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.2--rc.1-4D6BFE.svg?style=flat-square&labelColor=161b22&logo=deepseek&logoColor=white" alt="DeepSeek Harness 0.1.2-rc.1"/></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>
 
@@ -48,23 +48,41 @@ Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 c
 | `meta_search` | 检索能力目录（Tool / Skill），list/detail 双模式 | `@daweifu/capability-menu/search` |
 | `meta_invoke` | 统一执行面：Tool 真执行（走完整 `ctx.tools` 管线）+ Skill 加载 | `@daweifu/capability-menu/invoke` |
 
-### 能力管理
+### 能力菜单
 
 <p align="center">
   <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%"/>
+  <img src="assets/screenshot-policy.png" alt="策略与目录 · 三档策略配置" width="48%"/>
+  <img src="assets/screenshot-catalog.png" alt="策略与目录 · 按需能力目录" width="48%"/>
 </p>
 
-安装后，「设置 / 通用设置」下出现「能力管理」tab（位于「模型」与「插件」之间），用于可视化查看和调整暴露策略，改动即时生效、无需重启：
+安装后，「设置 / 通用设置」下出现「能力菜单」tab（在「模型」与「插件」之间），用来查看和调整能力的暴露档位，改动即时生效、无需重启。
 
-- **Tools / Skills 页签**：顶部 Tab 栏为 `Tools` 与 `Skills`，右侧是各档数量统计和「查看能力目录」按钮。Tools 页按 server 分组、可折叠：MCP 工具挂在各自 server（`gongfeng`/`km`…）下；内置原生工具（来自 agent preset 的 `bash`/`read`/`write`/`glob`/`grep`…）统一挂在保留的「系统内置」组（server 键 `built-in`）。点击某行查看模型侧工具定义 name / description / parameters。
-- **Skills 页签**：内部再分「全局技能 / 项目技能」两个子页签（始终显示，空的一侧显示空态提示），顶部数量统计跟随当前子页签。点击技能行展开目录树，点文件预览 SKILL.md 等正文。
-- **三态圆点与循环切换**：每个能力带一个分类圆点——实心 = 常驻、上半实心圆环 = 按需、圆环 + 斜杠（禁行标志）= 禁用；点击能力旁圆点或分类计数即可循环切换（内置原生工具与 MCP 工具同等可管），若被更高优先级规则（如通配）覆盖，界面会提示「分类未生效」。
-- **查看能力目录**：点右上角按钮弹出只读弹层，含两份文件——「三档策略配置」是**生效策略的语义化视图**（默认全部能力常驻：`tools.resident` 每个 server 显示 `*`，例外只在 `on-demand`/`disabled` 里按 server → 工具名 分级列出；skills 无 server 维度，`skills.resident` 恒为 `*`），以及「按需能力目录」物化文件（`catalogFile`）的路径与内容；持久化入口仍是 profile 的 `cordis.patch.yml`。
+| 想做什么 | 在哪 |
+| --- | --- |
+| 切档位 | 点能力行右侧的圆点；或点顶部的档位计数，整组切 |
+| 在长列表里找能力 | 页签栏下方的过滤框，匹配名字**和所属分组**（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」。
+
+> **技能来源与同名规则**：技能行上的来源标签来自 dsh 的 provider（`project-dsh` / `user-agents` / `custom` / `bundled` …），而**预设技能和用户自配的 `customSkillDirs` 都是 `custom`**——两者只能靠作用域归属区分，所以分组用的是扫描时记下的 preset id，不是来源标签。档位规则按**裸名字**生效：同名技能跨作用域共享同一个开关，且索引时**全局层优先、预设之间先到先得**（与工具侧一致）；同名冲突不影响档位，但会让另一份实现不出现在列表里。
+
+字段含义与可见范围（全局 / 项目）、移除的具体后果、注册时的 `SKILL.md` 校验口径，都在你操作的那一刻写着，这里不重复。
 
 ## 快速安装
 
@@ -72,7 +90,7 @@ Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 c
 
 ### 从 npm 安装（推荐）
 
-单包同时提供服务端插件与前端「能力管理」tab，装完即可在「设置 / 通用设置」下看到：
+单包同时提供服务端插件与前端「能力菜单」tab，装完即可在「设置 / 通用设置」下看到：
 
 ```sh
 dsh plugin --profile web add @daweifu/capability-menu
@@ -129,11 +147,14 @@ dsh plugin --profile web remove @daweifu/capability-menu
 | **禁用** | tool | 不进 payload | `meta_search` 不返回、目录 YAML 不写入 | `meta_invoke` 拒绝；模型幻觉直调也在 `tools/pre-execute` 被硬拒绝 |
 | | skill | 不进 `<available_skills>` 目录 | `meta_search` 不返回、目录 YAML 不写入 | `meta_invoke` 拒绝；`skill` 工具在 `tools/pre-execute` 硬拒绝 |
 
-> tool 档位同时覆盖 `mcp__` 编目工具与内置原生工具（原生工具统一以 `built-in` 为 server 归组、同样三档可管）。**On-demand 的内置工具会退出模型常驻视野**，需要时经 `meta_search` 发现、`meta_invoke` 派发（两跳调用）——因此不建议把高频核心工具设为按需。`meta_search`/`meta_invoke` 自身与 Code Mode 保留传输层 `run_code` 不进能力目录，恒常驻、不可在「能力管理」切换。
+> **覆盖与保留**：
+> - `tool` 档同时覆盖 `mcp__` 编目工具与内置原生工具——原生工具统一以保留的 `built-in` server 归组，与 MCP 工具一样三档可管。**请勿把真实 MCP server 命名为 `built-in`。**
+> - `meta_search`/`meta_invoke` 是本插件的控制面：恒常驻、不可被禁用（在规则里禁用它们会在启动时报错）。`run_code` 是 Code Mode 保留传输层：不进目录、不在「能力菜单」出现，请勿为它配置三档规则。
+> - **不建议把高频核心工具设为按需**：按需的内置工具会退出模型常驻视野，使用时需要 `meta_search` → `meta_invoke` 两跳调用。
 
 ## 配置文件
 
-规则写在 profile 的 `cordis.patch.yml` 里 `capability-menu-policy` 插件 entry 的 `config` 下（外层 `- insert:` / `id` / `name` 是 Cordis patch 的挂载样板，与规则无关）：
+规则写在本插件 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 热重载本插件并重跑一次能力枚举，所以不能每次点击都写。
 
 ```yaml
 config:
@@ -163,6 +184,17 @@ config:
 
 > 配置键即档位英文词：`resident`（常驻）/ `on-demand`（按需）/ `disabled`（禁用）。
 
+### 全部配置项
+
+| 配置项 | 归属 entry | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `tools` / `skills` / `metaTools` | `capability-menu-policy` | 见上 | 三档分类规则；能力菜单的改动会（防抖后）自动写回本 entry 的 `config` |
+| `catalogFile` | `capability-menu-registry` | `~/.dsh/capability-catalog.yaml` | 按需能力目录物化路径，置空禁用 |
+| `refreshDebounceMs` | `capability-menu-registry` | `200` | 变更事件的重建防抖窗口（ms）；`0` 关闭防抖 |
+| `patchFile` | `capability-menu-policy` | `~/.dsh/cordis.patch.yml`（`$DSH_HOME` 优先） | 注册 MCP 服务器写入的 patch 文件 |
+| `skillsDir` | `capability-menu-policy` | `~/.dsh/skills` | 注册 Skill 目录的技能根 |
+| `persistDebounceMs` | `capability-menu-policy` | `1500` | 点选改动写回 patch 文件前的防抖窗口（ms）|
+
 **规则优先级**（从上到下命中即停；同档内精确规则优先于通配）：
 
 | 优先级 | 规则 | 示例 | 效果 |
@@ -170,27 +202,26 @@ config:
 | 1 | `disabled` 精确 | `disabled: [forbidden_skill]` | 最硬禁用，压过一切 |
 | 2 | `disabled` 通配 | `disabled: ['mcp__secret__*']` | 整组禁用 |
 | 3 | `resident` 精确 | `resident: [bash]` | 单个能力显式常驻 |
-| 4 | `on-demand` 精确 | `on-demand: [legacy_skill]` | 单个能力显式按需（能力管理点击写入的就是这类） |
+| 4 | `on-demand` 精确 | `on-demand: [legacy_skill]` | 单个能力显式按需（能力菜单点击写入的就是这类） |
 | 5 | `resident` 通配 | `resident: ['mcp__gongfeng__*']` | 整组常驻 |
 | 6 | `on-demand` 通配 | `on-demand: ['mcp__*']` | 兜底批量按需 |
 | 默认 | 未命中任何规则 | — | 常驻 |
 
 要点：
-- `meta_search`/`meta_invoke` 恒常驻，不可被禁用（Disabled）。
-- **精确规则优先于通配（跨档也成立）**：例如存在 `resident: ['mcp__gongfeng__*']` 时，在「能力管理」把某工具点成按需会写入精确 `on-demand` 规则并生效，不会被通配压回；若仍被更高优先级覆盖，界面提示「分类未生效」。
-- 原生工具与 MCP 工具一样进编目（归 `built-in` server），未列出默认常驻；被 `on-demand`/`disabled` 覆盖后退出常驻视野，按需时仍可 `meta_search` → `meta_invoke` 两跳调用。**勿把真实 MCP server 命名为 `built-in`。**
+- **精确规则优先于通配（跨档也成立）**：例如存在 `resident: ['mcp__gongfeng__*']` 时，在「能力菜单」把某工具点成按需会写入一条精确 `on-demand` 规则并生效，不会被通配压回；若仍被更高优先级规则覆盖，界面提示「分类未生效」。
 
-> 「能力管理」tab 的改动只写入运行时内存、不落盘；要持久化（随 profile 生效、可版本管理/批量声明），编辑 profile 的 `cordis.patch.yml` 即可——这就是持久化入口，无需额外的导入/导出按钮。
+> **两类改动，落盘位置不同**：
+>
+> - **三档分类**先只改内存（所以点击即时生效），停手约 1.5s 后自动写回本插件 entry 的 `config`（`patchFile`，默认 home 层的 `~/.dsh/cordis.patch.yml`）——写这个文件会让 dsh 热重载本插件并重跑一次能力枚举，所以不能每次点击都写。要在版本管理里批量声明规则，直接编辑同一条 entry 即可，无需额外的导入/导出按钮。
+> - **注册的来源**（MCP 服务器、Skill 目录）在点击当下就落盘：MCP 写进同一个 patch 文件（`@deepseek-ai/dsh-mcp-client` 条目），Skill 在技能根下建软链。
 
 ### 按需能力目录（`catalogFile`，唯一物化目录，grep 可检索）
 
-On-demand 能力自动物化成**一个 YAML 文件**给模型检索，链路：
-
-**工具/技能变更或分类调整 → registry 自动重写 `catalogFile` → 模型 `grep`/`read`（或 `meta_search`）找到 id 与 kind → `meta_invoke(id, kind)` 执行/加载**
+On-demand 能力自动物化成**一个 YAML 文件**给模型检索（改档位只重写这个文件——库存没变，不需要重新枚举工具与各 agent preset 的技能层）：
 
-- 默认 `~/.dsh/capability-catalog.yaml`（`catalogFile` 可改，置空禁用）；没有任何按需能力时不注入目录指引，省上下文。
-- 技能必须**已注册进 `ctx.skills`**（SKILL.md 放用户/项目技能根或挂 `customSkillDirs`）再切按需，即自动出现；无独立手写输入清单。
-- 模型侧两路发现：`grep` 目录文件 / `meta_search`（结构化 schema）；再以**同一条目返回的 `kind`** 调 `meta_invoke` 加载/执行。技能 id 即裸名（`frontend-design`），tool/skill 由 `kind` 区分；工具经 `ctx.tools.execute`，技能经 `ctx.skills`。
+- 文件位置在 **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` 区分。
 
 ```yaml
 # ~/.dsh/capability-catalog.yaml（自动生成；仅含 On-demand 能力，

package/cordis.patch.yml

@@ -16,23 +16,10 @@
 #   - id: capability-menu-policy
 #     name: '@daweifu/capability-menu/policy'
 #       config:
-#         tools:
-#           resident:
-#             - execute_cmd
-#             - get_session_context
-#             - search_kb
-#             - 'mcp__gongfeng__*'
-#           on-demand:
-#             - 'mcp__*'
-#             - 'server:km:*'
-#           disabled: []
-#         skills:
-#           resident:
-#             - debugging
-#             - coding
-#         metaTools:
-#           - meta_search
-#           - meta_invoke
+#         # Rule syntax — tier keys `resident` / `on-demand` / `disabled`
+#         # (exact names, `*` globs, or `server:<name>:*`), plus `metaTools` —
+#         # and the priority order are documented in the README「配置文件」
+#         # section; the shipped defaults live in the insert block below.
 #
 # - `capability-menu-registry` (P0): builds/indexes the capability catalog and
 #   exposes the `ctx.capability` service (search/get/getDetail/refresh). It registers
@@ -47,15 +34,19 @@
 #   view (no agent) so On-demand tools stay runnable; dedups already-loaded skills.
 #   Rejects Disabled capabilities.
 # - `capability-menu-policy` (P3): Resident/On-demand/Disabled projection
-#   strategy + 能力管理 surface. Reads explicit resident/on-demand/disabled
+#   strategy + 能力菜单 surface. Reads explicit resident/on-demand/disabled
 #   rules (exact name + glob + server:<name>:*) and filters `assembly.tools` at
 #   `system-prompt/assemble` to Resident + meta tools only. The execution chain
 #   (`ctx.tools.execute`) is untouched, so On-demand capabilities remain executable
-#   via `meta_invoke`. Exposes `ctx.capabilityPolicy` with
-#   `classifyAll`/`getConfig`/`updateConfig` for the frontend 能力管理 tab
-#   (Resident/On-demand/Disabled rules + click-to-cycle classification +
-#   read-only list), plus skill file browsing (`getDetail`/`listSkillDir`/
-#   `readSkillFile`) via the Typert gateway.
+#   via `meta_invoke`. Exposes `ctx.capabilityPolicy` to the 能力菜单 tab through
+#   the Typert gateway: the tier surface (`classifyAll`/`getConfig`/
+#   `updateConfig`), the registered-location surface (`listLocations`/`addLocation`/
+#   `updateLocation`/`removeLocation` and `listSkillLocations`/`addSkillLocation`/
+#   `updateSkillLocation`/`removeSkillLocation`/`adoptSkillLocation`), the
+#   read-only catalog docs (`getCatalogDocs`), a rebuild trigger (`refresh`), and
+#   skill browsing (`getDetail`/`listSkillDir`/`readSkillFile`). Tier clicks land
+#   in this entry's own `config` after `persistDebounceMs`; registered MCP servers
+#   land in `patchFile` and skill directories as links under `skillsDir`.
 #
 # Default (policy present but no config): every capability is Resident — the
 # `classify` fallback, nothing is hidden. Add explicit `on-demand`/`disabled`
@@ -90,6 +81,6 @@
     # Root entry: loads the package main, which mounts the Typert gateway that
     # exposes ctx.capabilityPolicy to the browser. Makes this package a loader
     # entry itself so @deepseek-ai/dsh-client-modules discovers its `dsh.client`
-    # declaration and serves the 能力管理 browser bundle (`./client`).
+    # declaration and serves the 能力菜单 browser bundle (`./client`).
     - id: capability-menu
       name: '@daweifu/capability-menu'