@daweifu/capability-menu 0.1.2 → 0.1.3

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,24 @@ 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:
 
-- **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`.
+- **Tools / Skills tabs**: the top tab bar shows `Tools` and `Skills`, with per-tier counts, Refresh and Register capability on its right; the read-only Policy & catalog entry sits on the header's description row. The Tools tab groups by server and folds: MCP tools under their own server, harness-native tools together under the built-in group. Click a row for the tool's model-facing definition.
+- **Skills tab**: split into "Global skills" / "Project skills" sub-tabs, with the counts following the active one. Click a skill row to expand its directory tree; click a file to preview it.
+- **Three-state dot**: filled = Resident, half-filled ring = On-demand, ring with a slash (a no-entry sign) = Disabled. Click a dot or a tier count to cycle — native and MCP tools are equally manageable; if a higher-priority rule (a wildcard, say) overrides it, the UI reports that the classification did not apply.
+- **Policy &amp; catalog**: the button on the header's description row opens a read-only modal with two files — the effective policy in a semantic view, and the materialized On-demand catalog (`catalogFile`, On-demand capabilities only). Rules are changed by clicking on the page; a change is written back to this plugin's entry `config` (`patchFile`, the home layer's `~/.dsh/cordis.patch.yml` by default — see "Configuration").
+- **Register capability**: the top-right button opens a form with "MCP server" / "Skill directory" sub-tabs, defaulting to the tab you are on. The modal holds the form only — registered entries are in the list, each with its own Edit.
+  - **MCP server**: registering one writes an `@deepseek-ai/dsh-mcp-client` row into the patch file, **mounted natively by dsh** (this plugin never manages the connection) — the same file and the same table as hand-written entries, no restart needed. Fields: `serverName`, transport (the form picks `streamable-http` by default), stdio's command / args / cwd / env, http's URL / headers, and a timeout in seconds; the form explains what each field takes.
+    > **Headers** carry the credentials: one `Key: Value` per line, `Authorization: Bearer …` and the like. They are stored in **plain text** in `~/.dsh/cordis.patch.yml`, exactly as with hand-written entries.
+  - **Skill directory**: two locations — **Global** (`~/.dsh/skills/`, visible to every session) or **Project** (`<projectRoot>/.dsh/skills/`, visible only to sessions whose cwd sits inside that project). For a project you only supply any existing path inside it; the project root is derived the way dsh derives it, and the panel reports the path actually written. Either way it is a symlink, exactly matching dsh's own skill discovery. Registration validates the `SKILL.md` the way dsh's loader does and reports failures, so a directory can no longer register here and then be silently skipped by dsh. The skill's name is the one declared in `SKILL.md`; the directory name only names the symlink.
+- **Edit**: every MCP server group header in the Tools tab and every skill row with a manageable entry (project skills included) carries an Edit button that opens the current configuration prefilled, to change, save or remove. `serverName` is read-only when editing (it forms the `mcp__<serverName>__<tool>` prefix), and a skill's location cannot be changed — moving between roots is remove + register.
+- **Remove**: removal asks for confirmation first and states what this particular removal costs — an MCP server loses its patch row, while a skill's cost depends on whether the entry is a symlink or a real directory (the latter is deleted recursively and cannot be recovered). The built-in group has no Edit button, because it is not a real MCP server.
+- **Adopt**: for skills in user-level roots such as `~/.agents/skills` / `customSkillDirs`, the row offers Adopt; the confirmation names the directory the skill currently lives in, and confirming links it into `~/.dsh/skills/` (**content untouched**). Rows that cannot be adopted show their source instead — a specific directory, or a category such as "custom skill dirs" / "bundled with dsh"; the action and the source never both appear.
+- **Refresh**: the Refresh button rebuilds the capability catalog and re-pulls the list. Registering a source refreshes once automatically; the manual button is for when you changed a source outside dsh (edited the patch file by hand, linked a skill directory yourself).
 
 ## Quick Install
 
@@ -129,11 +137,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 +174,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 +198,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,31 @@ 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（位于「模型」与「插件」之间），用于可视化查看和调整暴露策略，改动即时生效、无需重启：
-
-- **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`。
+安装后，「设置 / 通用设置」下出现「能力菜单」tab（位于「模型」与「插件」之间），用于可视化查看和调整暴露策略，改动即时生效、无需重启。
+
+- **Tools / Skills 页签**：顶部 Tab 栏为 `Tools` 与 `Skills`，右侧是各档数量统计、「刷新」与「注册能力」，只读的「策略与目录」入口在页头说明行右侧。Tools 页按 server 分组、可折叠：MCP 工具挂在各自 server 下，内置原生工具统一在「系统内置」组。点击某行查看模型侧的工具定义。
+- **Skills 页签**：内部分「全局技能 / 项目技能」两个子页签，数量统计跟随当前页签。点击技能行展开目录树，点文件预览正文。
+- **三态圆点**：实心 = 常驻、上半实心圆环 = 按需、圆环 + 斜杠（禁行标志）= 禁用。点圆点或分类计数即可循环切换，内置原生工具与 MCP 工具同等可管；被更高优先级规则（如通配）覆盖时，界面会提示「分类未生效」。
+- **策略与目录**：页头说明行右侧的按钮弹出只读弹层，含**生效策略的语义化视图**与**按需能力目录**（`catalogFile`，仅含按需能力）两份文件。改规则的入口是页面上点选，改动会在停手后自动写回本插件 entry 的 `config`（`patchFile`，默认 home 层的 `~/.dsh/cordis.patch.yml`，见「配置文件」）。
+- **注册能力**：右上角「注册能力」按钮弹出表单，内含「MCP 服务器 / Skill 目录」两个子页签，默认停在你当前所在的页签。弹窗里只放表单——已注册项在列表里，各带「编辑」。
+  - **MCP 服务器**：注册即写入 patch 文件里的 `@deepseek-ai/dsh-mcp-client` 条目，**由 dsh 原生挂载**（插件不自己管连接），与手写声明式条目同文件、同一张表，无需重启。字段含 `serverName`、传输方式（表单代为选定默认 `streamable-http`）、stdio 的命令 / 参数 / 工作目录 / 环境变量、http 的 URL / 请求头、超时（秒）；各字段的取用方式表单里有说明。
+    > **请求头**用于认证：每行 `Key: Value`，`Authorization: Bearer …` 等凭据填在这里。**明文**存入 `~/.dsh/cordis.patch.yml`（与手写条目一致）。
+  - **Skill 目录**：可选**全局**（`~/.dsh/skills/`，所有会话可见）或**项目**（`<项目根>/.dsh/skills/`，只对 cwd 落在该项目内的会话可见）。选项目时只需填项目内任意一个已存在的路径，项目根按 dsh 的规则确定，面板会回报实际写入的路径。两种情况都是建软链，与 dsh 原生的 skill 发现机制一致。注册前按 dsh 加载器的口径校验 `SKILL.md`，不合格直接报错，不会出现「注册成功但 dsh 静默不加载」。技能名以 `SKILL.md` 里声明的为准，目录名只决定软链名。
+- **编辑**：Tools 页的 MCP server 分组头、Skills 页上已有可管理条目的技能行（含项目技能）都有「编辑」，点开预填当前配置，可改、可存、可移除。`serverName` 编辑时只读（它构成 `mcp__<serverName>__<tool>` 前缀）；技能的位置不可改——换根等于「移除 + 重新注册」。
+- **移除**：移除前先确认，并说明这次移除的实际后果：MCP 是删除其 patch 行；Skill 视软链 / 真实目录而不同，后者连同文件递归删除、不可恢复。「系统内置」组没有「编辑」，因为它不是真实 MCP 服务器。
+- **纳入管理**：`~/.agents/skills`、`customSkillDirs` 这类用户级根里的技能，行上给「纳入管理」；确认框会写明它当前所在的目录，确认后在 `~/.dsh/skills/` 下建一条指向它的软链，**内容不动**。不能纳管的行改为显示来源——某个具体目录，或「自定义技能目录」「随 dsh 预置」这类归类；动作与来源只出现其一。
+- **刷新**：点「刷新」重建能力目录并重新拉取列表。注册来源后会自动刷新一次，手动刷新只用于你在 dsh 之外改动过来源（手改 patch 文件、手动软链 skill 目录）之后。
 
 ## 快速安装
 
@@ -72,7 +80,7 @@ Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 c
 
 ### 从 npm 安装（推荐）
 
-单包同时提供服务端插件与前端「能力管理」tab，装完即可在「设置 / 通用设置」下看到：
+单包同时提供服务端插件与前端「能力菜单」tab，装完即可在「设置 / 通用设置」下看到：
 
 ```sh
 dsh plugin --profile web add @daweifu/capability-menu
@@ -129,11 +137,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 +174,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 +192,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'