dsh-vscode-mode 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 DSH 0.1.5+ 官方右侧 Sidebar 与对话同屏）+ 命令栏（Ctrl+Shift+P）与可扩展指令系统 + VS Code 兼容代码片段（.code-snippets 全局/项目，IntelliSense 展开）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车",
   "keywords": [
     "dsh",
@@ -35,6 +35,7 @@
   "files": [
     "lib",
     "assets",
+    "skills",
     "src",
     "unity",
     "cordis.patch.yml"

package/skills/dsh-vscodemode-mcp/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: dsh-vscodemode-mcp
+description: 配置、新增、启用或排查 dsh-vscode-mode 插件（VSCodeMode 设置页）的 MCP 服务——全局「我的 MCP」与项目级 `.mcp.json` 两种作用域、stdio / streamable-http 传输写法、`mcp.*` RPC 方法、serverName 命名与冲突规则、项目 MCP 的工作区隔离边界，以及连接失败/工具数为 0 等故障的定位路径。当用户提到「加个 MCP」「配置 MCP」「MCP 连不上」「项目 MCP」「.mcp.json」「VSCodeMode 的 MCP 管理」时加载本技能。
+whenToUse: 用户要求新增/修改/启停/排查 dsh-vscode-mode 的 MCP 服务配置时；或需要判断某个 MCP 工具为何在对话中不可见/被拒绝时。
+---
+
+# dsh-vscodemode-mcp — dsh-vscode-mode 的 MCP 配置与使用
+
+本技能覆盖 **dsh-vscode-mode 插件**（DSH 上的类 VSCode 编码体验）提供的 MCP 可视化管理能力。
+它管理的是 `@deepseek-ai/dsh-mcp-client` 的 loader 条目，连接由 DSH Host 维护，**不在浏览器侧连接 MCP**。
+
+## 1. 两种作用域（先判断用户要哪一种）
+
+| | 全局「我的 MCP」 | 项目 MCP |
+|---|---|---|
+| 配置位置 | profile 的 loader 树（`~/.dsh/profiles/<profile>/cordis.yml`） | 项目根 `.mcp.json` 的 `mcpServers` |
+| 生效范围 | 该 profile 下所有工作区 | 仅该 workspace（+ 其子路径可匹配到的工作区） |
+| 随仓库共享 | 否 | 是（`.mcp.json` 入库即团队共享） |
+| 持久真相 | loader 条目 | `.mcp.json` 文件（重启后由插件 reconcile 恢复激活） |
+| 受工作区隔离约束 | 否 | **是**（见 §5） |
+
+判断规则：
+- 用户说「全局都能用」「所有项目都要」→ 全局。
+- 用户说「这个项目需要」「跟仓库一起提交」→ 项目级。
+- 不确定且该 MCP 只在某个仓库有意义 → 默认项目级。
+
+## 2. UI 路径
+
+设置 → **VSCodeMode** → **「MCP 管理」** Tab，其下三个子页签：
+
+- **我的 MCP** — 全局服务列表（可查看状态/工具、添加、刷新 ⟳、启用/禁用、删除 ⌫）。
+- **项目 MCP** — 先选项目（带路径与 MCP 计数），再管理该项目的服务。
+- **MCP 市场** — 占位，暂未接入。
+
+「+ 添加全局 MCP」按钮在子页签栏右侧；项目 MCP 的新增入口在所选项目的分组内。
+表单字段：名称 / 传输方式 / （stdio）命令·参数·工作目录 / （streamable-http）URL·请求头。
+按钮文案为「保存并连接」——**保存后会立刻尝试连接**。
+
+## 3. 配置写法
+
+### 3.1 项目级 `.mcp.json`
+
+对齐 Claude Code / Cursor 格式，存于项目根：
+
+```json
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "codegraph",
+      "args": ["serve", "--mcp", "--path", "D:/Work/MyProject"]
+    },
+    "remote-tools": {
+      "url": "http://localhost:3000/mcp",
+      "headers": { "Authorization": "Bearer <token>" },
+      "toolCallTimeoutMs": 60000
+    }
+  }
+}
+```
+
+规则（`src/mcpProject.ts` 的 `configFromDef`）：
+- **有 `url` → `streamable-http`；无 `url` → `stdio`**。传输方式由字段形态自动判定，不写 `transport`。
+- stdio 字段：`command`（必填）、`args`（数组）、`cwd`、`env`（键值对象）。
+- http 字段：`url`（必填，须 `http(s)://`）、`headers`（键值对象）。
+- 可选：`toolCallTimeoutMs`（数字）。
+- `disabled: true` = 停用（由启停开关维护；**保存时不会写这个键，保存恒为启用**）。
+- 顶层可有其他字段，写回时保留；`mcpServers` 之外的未知字段不丢。
+
+### 3.2 全局（等价配置形）
+
+全局条目等价于 profile loader 里的一行 `@deepseek-ai/dsh-mcp-client`：
+
+```yaml
+- id: <条目 id>
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: codegraph
+    transport: stdio
+    command: codegraph
+    args: ['serve', '--mcp']
+```
+
+但 **优先用设置页 UI 或 `mcp.save` RPC**，不要手改 profile 的 `cordis.yml`：UI/RPC 会同步触发 loader 热更新与冲突校验，手改容易产生重复条目。
+
+### 3.3 两个最小可用示例
+
+stdio（本地命令行 MCP，如 CodeGraph）：
+```
+名称: codegraph
+传输方式: stdio
+命令: codegraph
+参数: serve --mcp --path D:/Work/MyProject
+```
+
+streamable-http（远端/已启动的 HTTP MCP）：
+```
+名称: remote-tools
+传输方式: streamable-http
+URL: http://localhost:3000/mcp
+请求头: Authorization=Bearer <token>
+```
+
+## 4. RPC 方法表（UI 之外的程序化入口）
+
+路由：`POST /edrv/rpc`，报文体 `{ "method": "...", "args": { ... } }`，返回 `{ ok: true, ... }` 或 `{ ok: false, error }`。
+
+| 方法 | 入参 | 返回 |
+|---|---|---|
+| `mcp.list` | `{}` | `{ servers: MpcServer[] }` |
+| `mcp.save` | `{ config: MpcConfig }` | `{ server: MpcServer }` |
+| `mcp.remove` | `{ id }` | `{}` |
+| `mcp.toggle` | `{ id, enabled }` | `{ server: MpcServer }` |
+| `mcp.refresh` | `{ id }` | `{ server: MpcServer }` |
+| `mcp.projects` | `{}` | `{ projects: MpcProject[] }` |
+| `mcp.projectSave` | `{ workspacePath, serverName, config }` | `{ project: MpcProject }` |
+| `mcp.projectRemove` | `{ workspacePath, serverName }` | `{ project: MpcProject }` |
+| `mcp.projectToggle` | `{ workspacePath, serverName, enabled }` | `{ project: MpcProject }` |
+| `mcp.projectRefresh` | `{ workspacePath, serverName }` | `{ project: MpcProject }` |
+
+`MpcServer` 关键字段：`id`、`serverName`、`enabled`、`transport`、`config`、`status`、`toolCount`、`tools[]`。
+`MpcProject` 关键字段：`workspacePath`、`title`、`servers[]`、`source: 'project'`，异常时带 `missingDir` 或 `fileError`。
+
+## 5. 命名规则与冲突（最容易踩的坑）
+
+- **`serverName` 规则**：`/^[A-Za-z0-9_-]{1,32}$/` —— 字母、数字、**下划线**、连字符，最多 32 位。
+  ⚠️ 注意与技能名的区别：**MCP 的 `serverName` 允许下划线**，而 DSH 技能名不允许（技能名须 kebab-case）。
+- **唯一性**：同一个 `serverName` 在**全局与所有项目之间**全局唯一。重复时保存直接失败：
+  `serverName "xxx" 已被另一个 MCP 使用（全局或其他项目），请换一个名称`。
+- **模型侧工具名**：`mcp__<serverName>__<原始工具名>`。这段前缀是隔离与可见性机制的判定依据，不要手工改 `serverName` 来"重命名工具"——那会生成一整套新工具名。
+- **项目条目 id**：`vsm-mcp.<workspaceHash>.<serverName>`（旧版残留为 `vsm-mcp:<hash>:<name>`，插件识别但不显示为全局 MCP）。
+- 项目 MCP 只接受**已注册为 DSH workspace** 的路径，否则报 `项目未注册为 DSH workspace，不能管理项目 MCP`。
+
+## 6. 作用域隔离（项目 MCP 的边界）
+
+项目 MCP 的连接由 Host 维护，但**每个 agent 只继承当前工作区的项目工具**：
+
+- 机制：`tools.restrict({ deny })` 控制模型可见性 + `tools.guard()` 在执行层兜底拒绝。
+- 当前对话工作区 ≠ 条目所属工作区时，调用被拒，返回：
+  `已拒绝：当前对话工作区不能使用其他项目的 MCP`
+- 会话没有落在任何已注册工作区时：
+  `项目 MCP 需要在已注册工作区的对话中使用`
+- **全局 MCP 不受此限制**，在任何会话都可用。
+- 工作区匹配按**最长父路径**：在子目录会话里也能用到父级工作区的项目 MCP。
+
+排查「工具有但没有出现在模型面前」时，先看当前会话 cwd 是否落在目标 workspace 内。
+
+## 7. 故障排查
+
+| 症状 | 原因与处理 |
+|---|---|
+| 卡片状态 `错误`，提示 `MCP 插件未正常运行` | loader 条目 fiber 未进入 ACTIVE。看 Host 启动日志中该条目的报错；多半是 `command` 不存在或启动即退出 |
+| 状态 `连接中` 一直不变 | 服务端未响应 MCP 握手。核对 stdio 的 `command`/`args`/`cwd`，或 HTTP 的 URL 可达性 |
+| 已连接但 `toolCount` 为 0 | 服务端 `tools/list` 返回空，或工具同步失败。先用该 MCP 的 CLI 自行验证能列出工具 |
+| `stdio MCP 必须填写 command` | 表单「命令」为空 |
+| `HTTP MCP 必须填写 http(s) URL` | 「URL」为空或不是 `http(s)://` 开头 |
+| `serverName 只能包含字母、数字、下划线和连字符（最多 32 位）` | 名称含空格/点/中文或超长 |
+| `serverName "x" 已被另一个 MCP 使用…` | 见 §5 唯一性 |
+| 设置页里 `env` / `headers` 的值显示成 `••••••` | **这是脱敏掩码**（`publicConfig`）。读回的是掩码而非真实值，**不要把它原样回写保存**，否则会用掩码覆盖真实凭据 |
+| `.mcp.json 解析失败：…` | 文件不是合法 JSON；插件只报错、**不覆盖**该文件，修好 JSON 后刷新 |
+| `.mcp.json 的 mcpServers 必须是对象` | `mcpServers` 写成了数组/标量 |
+| 项目显示「目录缺失」 | workspace 路径已不存在（项目被移动/删除） |
+
+## 8. 边界与注意事项
+
+- **删除/启停走设置页或 RPC**，不要手删 profile 树里的条目——插件按条目 id（`vsm-mcp.*`）识别项目 MCP，手工改名会让它被当成全局条目。
+- **项目 MCP 的持久真相是 `.mcp.json`**：重启后插件按文件内容 reconcile 该项目的激活状态（文件里有的激活、文件里没有的停用）。
+- 项目 MCP 的写操作固定写入 `<workspacePath>/.mcp.json`，不会写到别处。
+- 全局 MCP 由 loader 落盘到 profile 树，重启自动恢复。
+- MCP 条目本身是 loader 条目，**HMR/热更新会重建连接**；调试连接问题时可先 `mcp.refresh`（等价于用当前 config 重新 `loader.update`）。
+- 本技能只覆盖 dsh-vscode-mode 的 MCP 管理面。若问题出在 MCP 服务端自身（协议实现、鉴权、工具 schema），那不是本插件的问题，应转向该服务端的调试手段。
+
+## 9. 关键源码位置
+
+需要在插件仓库里核对行为时（按需读取，不要一次全开）：
+
+- `src/mcp.ts` — 全局 MCP 的 list/save/remove/toggle/refresh，`validateConfig`，`publicConfig` 脱敏，`toolsOf` 工具前缀。
+- `src/mcpProject.ts` — 项目 `.mcp.json` 读写、`configFromDef`、reconcile、条目 id 生成。
+- `src/mcpIsolation.ts` — 工作区隔离（restrict + guard）与两条拒绝文案。
+- `src/shared/mcp.ts` — 共享契约（`MpcConfig` / `MpcServer` / `MpcProject`）。
+- `src/shared/rpc.ts` — `mcp.*` 方法的入参与返回形状。
+- `src/client/ui/McpSettings.ts` — 设置页 UI（三个子页签与表单字段映射）。

package/src/client/styles/editor.css

@@ -29,6 +29,8 @@
 [data-edrv-view] .edrv-search-pop { position: absolute; top: calc(100% + 4px); right: 8px; width: min(460px, calc(100vw - 24px)); max-height: 300px; overflow: auto; background: var(--dsw-alias-bg-overlay, #1c1c1c); border: 1px solid var(--dsw-alias-border-l2, #555); border-radius: 10px; box-shadow: 0 6px 20px rgba(0,0,0,.4); z-index: 60; padding: 4px; }
 [data-edrv-view] .edrv-search-item { display: flex; flex-direction: column; gap: 1px; padding: 5px 8px; border-radius: 6px; cursor: pointer; }
 [data-edrv-view] .edrv-search-item:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.07)); }
+/* 键盘高亮项（↑↓ 选择）：与 hover 同特异性但声明在后，故选中态稳定可辨 @author ddj 2026年09月11号 */
+[data-edrv-view] .edrv-search-item.edrv-search-sel { background: var(--dsw-alias-interactive-bg-hover, rgba(255,255,255,.14)); }
 [data-edrv-view] .edrv-search-item .n { color: var(--dsw-alias-label-primary, #eee); font-size: 12px; word-break: break-all; }
 [data-edrv-view] .edrv-search-item .d { color: var(--dsw-alias-label-tertiary, #888); font-size: 11px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 [data-edrv-view] .edrv-search-empty { padding: 8px; font-size: 12px; color: var(--dsw-alias-label-tertiary, #888); }

package/src/client/ui/QuickOpen.ts

@@ -2,16 +2,19 @@
 /**
  * dsh-vscode-mode client — QuickOpen：顶部搜索框（Ctrl+P 打开文件）。
  * 快捷键随配置（edrv.quickOpen），占位文案同步当前键位。
+ * 候选浮窗支持鼠标点击与键盘导航（↑↓ 切换高亮、Enter 打开高亮项、Esc 关闭）；
+ * 输入法组词中不消费按键（中文候选词确认优先）。
  * 迁移自原 src/client/index.ts 的 QuickOpen，语义不改。
- * 作者 ddj 2026-08-20 / 2026-08-26
+ * 作者 ddj 2026-08-20 / 2026-08-26 / 2026年09月11号
  */
 import React from 'react'
 import { rpc } from '../rpc.js'
 import { bindingsOf, chordOf, matchEvent, useKeybindingsVersion } from '../keybindings.js'
+import { stepIndex } from './searchNav.js'
 
 /**
  * 快速打开搜索框：Ctrl+P 聚焦，输入 ≥2 字符经 edrv.searchFiles 搜索，
- * 结果列表点击/回车打开文件。
+ * 结果列表点击 / ↑↓ 选择 + 回车打开高亮项。
  * @param props.sessionId 会话 id
  * @param props.onOpen 打开回调(path)
  */
@@ -21,11 +24,19 @@ export function QuickOpen(props) {
   const [q, setQ] = React.useState('')
   const [results, setResults] = React.useState(null)
   const [open, setOpen] = React.useState(false)
+  const [active, setActive] = React.useState(0)
   const inputRef = React.useRef(null)
+  const popRef = React.useRef(null)
+  const listId = React.useId()
   const seq = React.useRef(0)
   const timer = React.useRef(null)
   useKeybindingsVersion() // 键位变化时刷新占位文案
 
+  const list = Array.isArray(results) ? results : []
+  const showPop = open && Array.isArray(results) && q.trim().length >= 2
+  // 高亮下标：候选集变化（含异步结果变短）时按当前长度收敛，不再单独改状态
+  const activeIdx = list.length ? Math.min(active, list.length - 1) : 0
+
   const search = (query) => {
     const s = ++seq.current
     const clean = String(query || '').trim()
@@ -37,14 +48,14 @@ export function QuickOpen(props) {
   }
 
   const onChange = (v) => {
-    setQ(v); setOpen(true)
+    setQ(v); setActive(0); setOpen(true)
     if (timer.current) clearTimeout(timer.current)
     timer.current = setTimeout(() => search(v), 180)
   }
 
   const pick = (p) => {
     onOpen(p)
-    setQ(''); setResults(null); setOpen(false)
+    setQ(''); setResults(null); setActive(0); setOpen(false)
     inputRef.current?.blur?.()
   }
 
@@ -70,20 +81,56 @@ export function QuickOpen(props) {
     }
   }, [])
 
+  // 高亮项滚入浮窗可视区（候选集或高亮变化时；nearest 避免整页跳动）
+  React.useEffect(() => {
+    if (!showPop) return
+    const node = popRef.current?.querySelector?.('.edrv-search-item.edrv-search-sel')
+    if (typeof node?.scrollIntoView === 'function') node.scrollIntoView({ block: 'nearest' })
+  }, [showPop, activeIdx, list.length])
+
   const dirText = (p) => {
     const base = String(p).split(/[\\/]/).pop() || String(p)
     return String(p).slice(0, Math.max(0, String(p).length - base.length)).replace(/[\\/]+$/, '') || String(p)
   }
 
+  /**
+   * 输入框按键：浮窗有候选时消费 ↑↓/Enter，其余情况放行（保留原生光标行为）。
+   * 输入法组词中一律放行——中文候选词的 Enter 确认不得被当成「打开文件」。
+   * @author ddj 2026年09月11号
+   * @param e 输入框键盘事件
+   */
+  const onInputKey = (e) => {
+    if (e.nativeEvent?.isComposing) return
+    if (e.key === 'Escape') { setOpen(false); return }
+    if (!showPop || !list.length) return
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+      e.preventDefault()
+      setActive((v) => stepIndex(v, e.key === 'ArrowDown' ? 1 : -1, list.length))
+      return
+    }
+    if (e.key === 'Enter') {
+      e.preventDefault()
+      pick(list[activeIdx])
+    }
+  }
+
   let pop = null
-  if (open && Array.isArray(results) && q.trim().length >= 2) {
-    if (results.length) {
-      const items = results.map((p) => React.createElement('div', { key: p, className: 'edrv-search-item', onClick: () => pick(p) },
+  if (showPop) {
+    if (list.length) {
+      const items = list.map((p, i) => React.createElement('div', {
+        key: p,
+        id: listId + '-' + i,
+        role: 'option',
+        'aria-selected': i === activeIdx,
+        className: 'edrv-search-item' + (i === activeIdx ? ' edrv-search-sel' : ''),
+        onMouseEnter: () => setActive(i),
+        onClick: () => pick(p),
+      },
         React.createElement('span', { className: 'n' }, String(p).split(/[\\/]/).pop() || p),
         React.createElement('span', { className: 'd' }, dirText(p))))
-      pop = React.createElement('div', { className: 'edrv-search-pop' }, ...items)
+      pop = React.createElement('div', { ref: popRef, id: listId + '-list', className: 'edrv-search-pop', role: 'listbox' }, ...items)
     } else {
-      pop = React.createElement('div', { className: 'edrv-search-pop' }, React.createElement('div', { className: 'edrv-search-empty' }, '无匹配文件'))
+      pop = React.createElement('div', { ref: popRef, className: 'edrv-search-pop' }, React.createElement('div', { className: 'edrv-search-empty' }, '无匹配文件'))
     }
   }
 
@@ -91,12 +138,13 @@ export function QuickOpen(props) {
     React.createElement('input', {
       ref: inputRef, className: 'edrv-search', placeholder: '搜索文件 (' + (chordOf('edrv.quickOpen') ?? 'Ctrl+P') + ')',
       value: q,
+      role: 'combobox',
+      'aria-expanded': showPop && list.length > 0,
+      'aria-controls': showPop && list.length ? listId + '-list' : undefined,
+      'aria-activedescendant': showPop && list.length ? listId + '-' + activeIdx : undefined,
       onChange: (e) => onChange(e.target.value),
       onFocus: () => { if (q.trim().length >= 2 && !results) setOpen(true) },
-      onKeyDown: (e) => {
-        if (e.key === 'Enter' && Array.isArray(results) && results.length) pick(results[0])
-        if (e.key === 'Escape') setOpen(false)
-      },
+      onKeyDown: onInputKey,
     }),
     pop)
 }

package/src/client/ui/searchNav.ts

@@ -0,0 +1,24 @@
+/**
+ * dsh-vscode-mode client — 候选列表键盘导航纯函数。
+ * 从搜索浮窗（QuickOpen）的按键处理中拆出，便于单测；不依赖 React 与 DOM。
+ * 导航语义：步进越界**循环**（末位 ↓ 回首位、首位 ↑ 到末位），与命令栏
+ * （CommandPalette 的 (min+step) % len）保持一致。
+ * 作者 ddj 2026年09月11号
+ */
+
+/**
+ * 计算候选列表的下一选中下标（循环；任何非法输入都收敛到合法下标）。
+ * 入参与返回值恒在 `[0, length - 1]`（`length <= 0` 时返回 0）。
+ * 作者 ddj 2026年09月11号
+ * @param current 当前选中下标（越界/非有限值按首位处理）
+ * @param delta 步进（+1 下一项 / -1 上一项）
+ * @param length 候选总数
+ * @returns 步进后的选中下标；无候选时返回 0
+ */
+export function stepIndex(current: number, delta: number, length: number): number {
+  if (!Number.isFinite(length) || length <= 0) return 0
+  const size = Math.floor(length)
+  const from = Math.min(Math.max(Number.isFinite(current) ? Math.floor(current) : 0, 0), size - 1)
+  const move = Number.isFinite(delta) ? Math.trunc(delta) : 0
+  return ((from + move) % size + size) % size
+}

package/src/compat.ts

@@ -13,6 +13,7 @@ import { entriesOf } from './mcp.js'
 import { loadSettingsDeps, settingsInstallNote, settingsInstallStrategy } from './fileOpenSettings.js'
 import { readDevForm } from './devForm.js'
 import { compareDshVersions, detectDshVersion, familyLabel, parseDshVersion } from './dshVersion.js'
+import { SKILL_PREFIXES, skillGroupState } from './skills.js'
 import type { CompatAdapter, CompatReport } from './shared/compat.js'
 import type { Ctx } from './store.js'
 import { ROUTE_PREFIX } from './paths.js'
@@ -55,11 +56,14 @@ export function detectExternal(ctx: Ctx, depsAvailable: boolean): CompatAdapter[
   const settings = ctx.get('settings') as { describe?: unknown; update?: unknown } | undefined
   const hasSettings = Boolean(settings?.describe || settings?.update)
   const sub = ctx.get('subprocess') as { spawn?: unknown } | undefined
+  const skills = skillGroupState()
   return [
     { name: MCP_PACKAGE, active: mcpCount > 0, note: mcpCount > 0 ? mcpCount + ' 个 MCP 服务条目' : '未检测到 MCP 条目（MCP 管理页显示为空）' },
     { name: '设置持久化（@deepseek-ai/dsh-settings）', active: depsAvailable, note: depsAvailable ? '设置 section 已安装' : '未安装：fileOpenTool 持久化降级为配置值' },
     { name: 'settings 服务', active: hasSettings, note: hasSettings ? '可读写设置' : '不可用（设置读写走配置回退）' },
     { name: '文件浏览器打开（subprocess 服务）', active: typeof sub?.spawn === 'function', note: typeof sub?.spawn === 'function' ? '可定位/打开 OS 文件浏览器' : '不可用（右键「在文件浏览器中打开」将提示失败）' },
+    // 新增项一律追加在末尾：既有下标被 tests/compat.test.ts 断言，不得前插。
+    { name: '插件技能组（' + SKILL_PREFIXES[0] + '*）', active: skills.mounted, note: skills.note + (skills.mounted && skills.dir ? '（' + skills.dir + '）' : '') },
   ]
 }
 

package/src/index.ts

@@ -26,6 +26,7 @@ import { createLspRpc } from './lsp/rpc.js'
 import { disposeAllServers } from './lsp/transport.js'
 import { createAiRpc } from './ai/rpc.js'
 import { installRulesSection } from './rules.js'
+import { installSkillGroup } from './skills.js'
 import type { RpcHandlerMap } from './shared/rpc.js'
 import type { Registry } from './registry.js'
 import type { Ctx } from './store.js'
@@ -55,6 +56,9 @@ export function apply(ctx: Ctx, config?: unknown): void {
   /** 规则注入 section（~/.dsh/rules 与 <工作区>/.dsh/rules；旧版 DSH 无 systemPrompt 时静默降级）。 */
   const rulesInstalled = installRulesSection(ctx)
   if (!rulesInstalled) log.warn('未检测到 systemPrompt 服务，规则仅可管理不注入')
+  /** 插件自带技能组（<包根>/skills，惰性获取 skills 服务；返回值仅表示"已调度"，实际结果见 skillGroupState）。 */
+  const skillsDispatched = installSkillGroup(ctx)
+  if (!skillsDispatched) log.warn('技能组未调度，插件技能组不可用')
   /** LSP RPC 与会话清理（一次性创建，tracker 状态跨请求保留）。 */
   const lspRpc = createLspRpc({ ctx, pluginConfig: config, manager: lspManager })
   const lspHandlers: Partial<RpcHandlerMap> = lspRpc.handlers
@@ -92,7 +96,7 @@ export function apply(ctx: Ctx, config?: unknown): void {
     disposeAllServers()
   })
 
-  log.info('编辑差异审查已装配（/edrv/rpc 路由就绪，项目 MCP 隔离已启用，语言服务器 LSP 已接入，规则注入' + (rulesInstalled ? '已接入' : '未接入') + '）')
+  log.info('编辑差异审查已装配（/edrv/rpc 路由就绪，项目 MCP 隔离已启用，语言服务器 LSP 已接入，规则注入' + (rulesInstalled ? '已接入' : '未接入') + '，技能组' + (skillsDispatched ? '装配中' : '未装配') + '）')
 }
 
 /**

package/src/paths.ts

@@ -173,6 +173,17 @@ export function vendorDirOf(moduleUrl: string): string {
   return join(assetsDirOf(moduleUrl), 'vendor')
 }
 
+/**
+ * 插件自带技能组根目录（包根 skills/，与 assets/ 同级；随包发布）。
+ * 布局：<根>/<技能名>/SKILL.md（目录式）或 <根>/<技能名>.md（扁平式）。
+ * @author ddj 2026年09月11号
+ * @param moduleUrl 模块 URL（缺省 import.meta.url；测试注入）
+ * @returns 技能组根目录绝对路径
+ */
+export function skillsDirOf(moduleUrl: string): string {
+  return join(dirname(fileURLToPath(moduleUrl)), '..', 'skills')
+}
+
 /** 图标目录：config.imageDir 覆盖优先，否则插件包 assets/。 */
 export function imageDirOf(config: unknown, moduleUrl: string): string {
   const cfg = config as { imageDir?: unknown } | undefined