@daweifu/capability-menu 0.1.1 → 0.1.2

package/README.en.md

@@ -0,0 +1,217 @@
+<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>
+</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="./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/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)
+- [Exposure Policy](#exposure-policy)
+- [Configuration](#configuration)
+
+---
+
+## 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.**
+
+### Capability Model
+
+*Capability* is the umbrella concept introduced by this plugin: a Tool and a Skill are different *kinds* of capability.
+
+| kind | provides to the agent | action | notes |
+| --- | --- | --- | --- |
+| `tool` | executes an action (an MCP tool or a harness-native built-in tool) | `execute` | indexed by `ctx.tools` |
+| `skill` | the method / flow / knowledge for a class of tasks | `load` | indexed by `ctx.skills` |
+
+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_invoke` | unified execution surface: really executes Tools (full `ctx.tools` pipeline) + loads Skills | `@daweifu/capability-menu/invoke` |
+
+### Capability Management
+
+<p align="center">
+  <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="View capability catalog · Policy (effective)" width="48%"/>
+  <img src="assets/screenshot-catalog.png" alt="View capability 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`.
+
+## Quick Install
+
+Prerequisites: Node.js and the dsh CLI installed (`dsh plugin` forwards to pnpm internally).
+
+### 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:
+
+```sh
+dsh plugin --profile web add @daweifu/capability-menu
+```
+
+### Install from source
+
+```sh
+git clone https://github.com/PKUfudawei/dsh-capability-menu.git
+cd dsh-capability-menu
+pnpm install                   # the prepare script builds lib/ (server) and lib/client.js (front-end)
+
+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'
+```
+
+### Uninstall
+
+```sh
+dsh plugin --profile web remove @daweifu/capability-menu
+```
+
+## Exposure Policy
+
+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
+
+| tier | capability | exposure (model view) | discovery | execution |
+| --- | --- | --- | --- | --- |
+| **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` |
+
+> 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.
+
+## 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):
+
+```yaml
+config:
+  tools:
+    resident:
+      - execute_cmd
+      - get_session_context
+      - search_kb
+      - 'mcp__gongfeng__*'    # wildcard: everything under this server is resident
+    on-demand:
+      - 'mcp__*'              # wildcard fallback
+      - 'server:km:*'         # bulk on-demand by server prefix
+    disabled:
+      - 'mcp__secret__*'      # disabled outranks everything, even resident
+  skills:
+    resident:
+      - debugging
+      - coding
+    on-demand:
+      - legacy_skill          # explicit on-demand (unlisted skills default to resident)
+    disabled:
+      - forbidden_skill
+  metaTools:
+    - meta_search             # always resident; cannot be disabled
+    - meta_invoke
+```
+
+> Config keys are the tier words themselves: `resident` (常驻) / `on-demand` (按需) / `disabled` (禁用).
+
+**Rule priority** (first match wins; within one tier, an exact rule beats a wildcard):
+
+| priority | rule | example | effect |
+| --- | --- | --- | --- |
+| 1 | `disabled` exact | `disabled: [forbidden_skill]` | hardest deny, overrides everything |
+| 2 | `disabled` wildcard | `disabled: ['mcp__secret__*']` | block a whole group |
+| 3 | `resident` exact | `resident: [bash]` | keep one capability resident |
+| 4 | `on-demand` exact | `on-demand: [legacy_skill]` | one capability on-demand (what a Capability Management click writes) |
+| 5 | `resident` wildcard | `resident: ['mcp__gongfeng__*']` | keep a whole group resident |
+| 6 | `on-demand` wildcard | `on-demand: ['mcp__*']` | bulk on-demand fallback |
+| 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.
+
+### 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.
+
+```yaml
+# ~/.dsh/capability-catalog.yaml (auto-generated; contains only On-demand
+# capabilities — Resident ones are already resident and Disabled ones must not
+# be discoverable, so neither is written. Lists are emitted as `-` block
+# sequences, one item per line.)
+capabilities:
+  - id: mcp__km__search
+    kind: tool
+    name: mcp__km__search
+    description: Search the knowledge base
+    server: km
+  - id: legacy_skill
+    kind: skill
+    name: legacy_skill
+    description: A low-frequency skill for working on legacy code
+    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`.
+
+## License
+
+This project is licensed under the [Apache License 2.0](LICENSE).

package/README.md

@@ -1,50 +1,70 @@
 <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="./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/cordiverse/cordis"><img src="https://img.shields.io/badge/stack-Cordis%20bundle-7FBDF1.svg?style=flat-square&labelColor=161b22&logo=cardano&logoColor=white" alt="Cordis bundle"/></a>
-  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek%20Harness-0.1.1--rc.1-4D6BFE.svg?style=flat-square&labelColor=161b22&logo=deepseek&logoColor=white" alt="DeepSeek Harness 0.1.1-rc.1"/></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/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/>
 
 ## 目录
 
-- [能力菜单](#能力菜单)
+- [能力总览](#能力总览)
 - [快速安装](#快速安装)
-- [能力模型](#能力模型)
 - [暴露策略](#暴露策略)
 - [配置文件](#配置文件)
 
 ---
 
-dsh-capability-menu 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的一个 Cordis 插件，为海量 MCP tools / skills 建立统一能力目录（`ctx.capability`），并以**常驻 / 按需 / 禁用**三档管理暴露程度和执行方式——随时调整 agent 的能力边界，避免海量 tools/skills 塞满一次请求、节省 token 和上下文：
+## 能力总览
+
+dsh-capability-menu 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的一个 Cordis 插件，为海量 tools / skills（MCP 工具与内置原生工具）建立统一能力目录（`ctx.capability`），并以**常驻 / 按需 / 禁用**三档管理暴露程度和执行方式——随时调整 agent 的能力边界，避免海量 tools/skills 塞满一次请求、节省 token 和上下文。调整即时生效、无需重启，纯插件机制组合进 Harness 运行时，不改上游源码。**不挂载本插件（policy）时一切照旧、全量可见；挂载但未配置任何规则时，所有能力默认常驻。**
+
+### 能力模型
+
+Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 capability。
+
+| kind | 对 Agent 提供 | action | 备注 |
+| --- | --- | --- | --- |
+| `tool` | 执行一个动作（MCP 工具或内置原生工具） | `execute` | 由 `ctx.tools` 索引 |
+| `skill` | 某类任务的方法/流程/知识 | `load` | 由 `ctx.skills` 索引 |
+
+模型获得两个元工具：
 
-- **统一能力目录**：编目所有 MCP 工具与 Skill，模型经 `meta_search` 检索、`meta_invoke` 执行。
-- **三档能力策略**：常驻 = 高频能力随叫随到；按需 = 低频能力归档进目录、用到才翻出来；禁用 = 明确禁止。这是你配置的驻留策略，不是按使用次数自动统计的标签。
-- **可视化配置**：「能力菜单」设置 tab（MCP tools / Skills 两栏，分类可点击循环切换），调整即时生效。
-- **零侵入**：不改上游源码，经 Cordis 插件机制与 Harness 组合进同一运行时。
+| 工具 | 作用 | 对应 entry |
+| --- | --- | --- |
+| `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-mcp-tools.png" alt="MCP tools tab" width="45%"/>
-  <img src="assets/screenshot-skills.png" alt="Skills tab" width="45%"/>
+  <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>
 
-安装后，「设置 / 通用设置」下出现「能力菜单」tab（位于「模型」与「插件」之间），用于可视化查看和调整暴露策略，改动即时生效、无需重启：
+安装后，「设置 / 通用设置」下出现「能力管理」tab（位于「模型」与「插件」之间），用于可视化查看和调整暴露策略，改动即时生效、无需重启：
 
-- **两栏**：MCP 工具（按 server 分组、可折叠）与 Skills。
-- **三态圆点 + 统计**：每个能力带一个分类圆点（实心 = 常驻、半实心 = 按需、空心 = 禁用），栏顶部显示各档数量统计。
-- **点击循环切换**：点击能力旁的圆点或分类计数即可循环切换分类；MCP 工具还可以点击整行查看模型侧工具定义（name / description / parameters）。
-- **Skills 目录浏览**：展开某个 skill 可浏览其文件目录，点击文件预览 SKILL.md 等正文内容。
+- **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`。
 
 ## 快速安装
 
@@ -52,7 +72,7 @@ dsh-capability-menu 是 [DeepSeek Harness](https://github.com/deepseek-ai/deepse
 
 ### 从 npm 安装（推荐）
 
-单包同时提供服务端插件与前端「能力菜单」tab，装完即可在「设置 / 通用设置」下看到：
+单包同时提供服务端插件与前端「能力管理」tab，装完即可在「设置 / 通用设置」下看到：
 
 ```sh
 dsh plugin --profile web add @daweifu/capability-menu
@@ -94,22 +114,6 @@ dsh --profile web --dump-config | grep -E 'capability-menu'
 dsh plugin --profile web remove @daweifu/capability-menu
 ```
 
-## 能力模型
-
-Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 capability。
-
-| kind | 对 Agent 提供 | action | 备注 |
-| --- | --- | --- | --- |
-| `tool` | 执行一个动作（MCP 工具） | `execute` | 由 `ctx.tools` 索引 |
-| `skill` | 某类任务的方法/流程/知识 | `load` | 由 `ctx.skills` 索引 |
-
-模型获得两个元工具：
-
-| 工具 | 作用 | 对应 entry |
-| --- | --- | --- |
-| `meta_search` | 检索能力目录（Tool / Skill），list/detail 双模式 | `@daweifu/capability-menu/search` |
-| `meta_invoke` | 统一执行面：Tool 真执行（走完整 `ctx.tools` 管线）+ Skill 加载 | `@daweifu/capability-menu/invoke` |
-
 ## 暴露策略
 
 所有能力（Tool 与 Skill）按 **暴露程度**（模型在上下文中看到什么）与 **执行方式** 分为三档：
@@ -120,12 +124,12 @@ Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 c
 | --- | --- | --- | --- | --- |
 | **常驻** | tool | 完整 schema 进 `assembly.tools` → 模型请求 `tools` payload，每步可见 | 无需发现（已常驻） | 模型直接调用，运行时走完整 `ctx.tools` 管线 |
 | | skill | 名字+描述进 `<available_skills>` 目录（正文不在目录） | 无需发现（已常驻） | `skill` 工具按需加载正文（渐进加载） |
-| **按需** | tool | 不进 payload（零上下文成本） | `meta_search` list 返回 name+summary | `meta_invoke` 执行（走 `ctx.tools.execute`，管线完整）；或 detail 拿 schema 后直接调 |
-| | skill | 不进 `<available_skills>` 目录 | `meta_search` 检索（`progressiveSkillCatalog` 条目） | `meta_invoke` 按 `path` 加载 SKILL.md 正文 |
-| **禁用** | tool | 不进 payload | `meta_search` 不返回 | `meta_invoke` 拒绝，直接调用被投影排除 |
-| | skill | 不进目录 | `meta_search` 不返回 | `meta_invoke` 拒绝 |
+| **按需** | 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 档位均指 `mcp__` 编目工具；原生工具不参与三档管理，只能以 `tools.exposed` 保活可见性（见下方配置文件示例）。
+> tool 档位同时覆盖 `mcp__` 编目工具与内置原生工具（原生工具统一以 `built-in` 为 server 归组、同样三档可管）。**On-demand 的内置工具会退出模型常驻视野**，需要时经 `meta_search` 发现、`meta_invoke` 派发（两跳调用）——因此不建议把高频核心工具设为按需。`meta_search`/`meta_invoke` 自身与 Code Mode 保留传输层 `run_code` 不进能力目录，恒常驻、不可在「能力管理」切换。
 
 ## 配置文件
 
@@ -134,38 +138,77 @@ Capability 是本插件引入的上位概念：Tool / Skill 是不同类型的 c
 ```yaml
 config:
   tools:
-    exposed: [execute_cmd, get_session_context, search_kb, 'mcp__gongfeng__*']   # 通配：该 server 下全部常驻
-    progressive: ['mcp__*', 'server:km:*']                                        # 通配兜底 + 按 server 前缀批量按需
-    blocked: ['mcp__secret__*']                                                   # 禁用优先级最高，压过常驻
+    resident:
+      - execute_cmd
+      - get_session_context
+      - search_kb
+      - 'mcp__gongfeng__*'    # 通配：该 server 下全部常驻
+    on-demand:
+      - 'mcp__*'              # 通配兜底
+      - 'server:km:*'         # 按 server 前缀批量按需
+    disabled:
+      - 'mcp__secret__*'      # 禁用优先级最高，压过常驻
   skills:
-    exposed: [debugging, coding]
-    progressive: [legacy_skill]          # 显式按需（未列出即默认常驻）
-    blocked: [forbidden_skill]
-  metaTools: [meta_search, meta_invoke]  # 恒常驻，不可被禁用
-  progressiveSkillCatalog: ~/.dsh/progressive-skills.yaml
+    resident:
+      - debugging
+      - coding
+    on-demand:
+      - legacy_skill          # 显式按需（未列出即默认常驻）
+    disabled:
+      - forbidden_skill
+  metaTools:
+    - meta_search             # 恒常驻，不可被禁用
+    - meta_invoke
 ```
 
-**规则优先级**（命中即停，同级内精确匹配先于通配）：`blocked` > `exposed` > `progressive`，未命中任何规则默认 Exposed；`blocked` 是最硬的控制（压过 `exposed`），meta 工具（`meta_search`/`meta_invoke`）恒为 Exposed 且不可被 blocked。`tools.exposed` 里列原生工具名（`execute_cmd` 等）是**保活**：原生工具不进能力编目、只受投影链裁剪可见性，列在这里保持模型可见可调——一旦被 progressive/blocked 覆盖，模型就看不到也调不到。
+> 配置键即档位英文词：`resident`（常驻）/ `on-demand`（按需）/ `disabled`（禁用）。
+
+**规则优先级**（从上到下命中即停；同档内精确规则优先于通配）：
+
+| 优先级 | 规则 | 示例 | 效果 |
+| --- | --- | --- | --- |
+| 1 | `disabled` 精确 | `disabled: [forbidden_skill]` | 最硬禁用，压过一切 |
+| 2 | `disabled` 通配 | `disabled: ['mcp__secret__*']` | 整组禁用 |
+| 3 | `resident` 精确 | `resident: [bash]` | 单个能力显式常驻 |
+| 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`。**
+
+> 「能力管理」tab 的改动只写入运行时内存、不落盘；要持久化（随 profile 生效、可版本管理/批量声明），编辑 profile 的 `cordis.patch.yml` 即可——这就是持久化入口，无需额外的导入/导出按钮。
 
-> 「能力菜单」tab 的改动只写入运行时内存、不落盘；要持久化（随 profile 生效、可版本管理/批量声明），编辑 profile 的 `cordis.patch.yml` 即可——这就是持久化入口，无需额外的导入/导出按钮。
+### 按需能力目录（`catalogFile`，唯一物化目录，grep 可检索）
 
-### 渐进技能目录（`progressiveSkillCatalog`）
+On-demand 能力自动物化成**一个 YAML 文件**给模型检索，链路：
 
-按需（Progressive）技能不进固定上下文，也可能根本没注册进 `ctx.skills`。为了让它们仍可被发现，用一份独立 YAML 存 name + description + path，由 registry 索引、`meta_search` 检索；完整 SKILL.md 由 `meta_invoke` 按需加载（`ctx.skills` 未注册时按 YAML 的 `path` 读取）：
+**工具/技能变更或分类调整 → registry 自动重写 `catalogFile` → 模型 `grep`/`read`（或 `meta_search`）找到 id 与 kind → `meta_invoke(id, kind)` 执行/加载**
+
+- 默认 `~/.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`。
 
 ```yaml
-# ~/.dsh/progressive-skills.yaml
-skills:
-  - name: legacy_skill            # 对应 skills.progressive 里的规则名
-    description: 旧版迁移技能，低频使用
+# ~/.dsh/capability-catalog.yaml（自动生成；仅含 On-demand 能力，
+# Resident 已常驻、Disabled 不可发现，均不写入；列表以 `-` 每项一行的 block 序列写出）
+capabilities:
+  - id: mcp__km__search
+    kind: tool
+    name: mcp__km__search
+    description: 搜索知识库
+    server: km
+  - id: legacy_skill
+    kind: skill
+    name: legacy_skill
+    description: 处理旧工程的低频技能
     whenToUse: 处理旧工程时使用
-    path: /path/to/legacy_skill   # 含 SKILL.md 的目录
 ```
 
-### 默认（不配置 policy）
-
-- 不挂 `capability-menu-policy` → 全部工具/技能照旧可见（不投影）。
-- 挂了 policy 但没有任何规则 → 全部能力默认 Exposed（`classify` 兜底），不投影、不隐藏。需要把低频能力归档进目录时，显式配置 `progressive`（或 `blocked`）规则把它们从模型视野中移出。
+> 目录文件默认写在宿主 `~/.dsh`，需要模型侧 `bash`/`read` 工具的沙箱能访问该路径；若沙箱隔离宿主目录，请把 `catalogFile` 显式配置到沙箱可见的路径。默认路径在多个 dsh 实例间共享（last-write-wins），多实例部署时请为每个实例配置独立的 `catalogFile`。
 
 ## License
 

package/cordis.patch.yml

@@ -17,50 +17,49 @@
 #     name: '@daweifu/capability-menu/policy'
 #       config:
 #         tools:
-#           exposed:
+#           resident:
 #             - execute_cmd
 #             - get_session_context
 #             - search_kb
 #             - 'mcp__gongfeng__*'
-#           progressive:
+#           on-demand:
 #             - 'mcp__*'
 #             - 'server:km:*'
-#           blocked: []
+#           disabled: []
 #         skills:
-#           exposed:
+#           resident:
 #             - debugging
 #             - coding
 #         metaTools:
 #           - meta_search
 #           - meta_invoke
-#         progressiveSkillCatalog: ~/.dsh/progressive-skills.yaml
 #
 # - `capability-menu-registry` (P0): builds/indexes the capability catalog and
 #   exposes the `ctx.capability` service (search/get/getDetail/refresh). It registers
-#   no model-facing tool itself. Indexes the GLOBAL registry (no visibility
-#   filter) and additionally indexes Progressive skills from
-#   `progressiveSkillCatalog` (§7.2).
+#   no model-facing tool itself. Indexes every visible tool — MCP tools by their
+#   server and harness-native tools (bash/read/write/…) under the reserved
+#   `built-in` pseudo-server — plus skills from the global layer and every
+#   mountable preset's standing scope. The single on-demand catalog is emitted to
+#   `catalogFile` (default `~/.dsh/capability-catalog.yaml`) for grep/read.
 # - `capability-menu-search` (P1): registers the `meta_search` tool (list + detail).
 # - `capability-menu-invoke` (P2): registers the `meta_invoke` tool (unified
-#   execution of MCP tools and skill loading). Executes on the GLOBAL view
-#   (no agent) so Progressive tools stay runnable; dedups already-loaded skills.
-#   Rejects Blocked capabilities.
-# - `capability-menu-policy` (P3): Exposed/Progressive/Blocked projection
-#   strategy + 能力管理 surface. Reads explicit exposed/progressive/blocked
+#   execution of tools — MCP or native — and skill loading). Executes on the GLOBAL
+#   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
 #   rules (exact name + glob + server:<name>:*) and filters `assembly.tools` at
-#   `system-prompt/assemble` to Exposed + meta tools only. The execution chain
-#   (`ctx.tools.execute`) is untouched, so Progressive tools remain executable
+#   `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
-#   (Exposed/Progressive/Blocked rules + click-to-cycle classification +
+#   `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.
 #
-# Default (policy present but no config): every capability is Exposed — the
-# `classify` fallback, nothing is hidden. Add explicit `progressive`/`blocked`
-# rules to pull capabilities out of the model surface. This bundle ships the
-# harness-native coding tools under `tools.exposed` so the model keeps direct
-# bash/file access.
+# Default (policy present but no config): every capability is Resident — the
+# `classify` fallback, nothing is hidden. Add explicit `on-demand`/`disabled`
+# rules to pull capabilities out of the model surface.
 - insert:
     - id: capability-menu-registry
       name: '@daweifu/capability-menu/registry'
@@ -71,15 +70,16 @@
     - id: capability-menu-policy
       name: '@daweifu/capability-menu/policy'
       config:
-        # Harness-native coding tools stay context-resident (Exposed) so the
-        # model can call them directly. meta_invoke only dispatches MCP `mcp__*`
-        # tools, so native tools (bash/read/write/edit/glob/grep) MUST stay
-        # Exposed — listing them Progressive/Blocked would make them neither
-        # visible nor invocable. The default (unlisted) class is Exposed; add
-        # explicit `progressive`/`blocked` rules to pull MCP servers and skills
-        # out of the model surface.
+        # Native coding tools are cataloged under the reserved `built-in`
+        # pseudo-server and are fully manageable like MCP tools. Unlisted
+        # capabilities default to Resident; list them under `on-demand`/
+        # `disabled` to pull MCP servers, native tools, or skills out of the
+        # model surface. On-demand native tools stay invocable through
+        # `meta_search` → `meta_invoke`. The `meta_search`/`meta_invoke`
+        # control-plane tools and the reserved `run_code` transport never enter
+        # the catalog. Do not name a real MCP server `built-in`.
         tools:
-          exposed:
+          resident:
             - bash
             - read
             - write
@@ -90,6 +90,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'