@civilization/deepseek-harness-skill-mcp 0.1.7 → 0.1.9

package/README.md

@@ -114,7 +114,11 @@ MCP 工具是提供给模型的工具 schema，不是用户 `/` 命令，因此
 
 MCP 对端离线、命令启动失败或首次工具发现失败不会阻止 DSH 启动。stdio 与 Streamable HTTP 使用 Harness MCP client 的后台重连策略；旧版 SSE 当前依赖连接自身，在断线后可通过刷新配置重新加载。设置页在连接恢复并发现工具后更新状态。插件加载时也会把旧版本写入的严格启动配置迁移为非致命启动策略。
 
-## Agent 工具
+## Agent 工具与 Skill
+
+插件向 DSH 注册了 `extension-management` Skill 以及 7 个模型专属管理工具：
+
+- **`extension-management` Skill**：引导模型掌握受管 Skill 路径与 stdio / streamable-http / sse 模式 MCP 服务器的标准配置结构与安全规约。
 
 | 工具 | 作用 |
 |---|---|
@@ -153,9 +157,9 @@ pnpm run web
 
 ## 验证
 
-自动测试覆盖配置持久化、Skill 多路径、编辑和删除、单技能内容编辑与删除、用户分组、并发 revision、Skill 创建与调用权限、MCP 工具发现和卸载、轮询状态以及中英文词典一致性。测试不需要模型 API key。
+自动测试覆盖配置持久化、Skill 多路径、编辑和删除、单技能内容编辑与删除、用户分组、并发 revision、Skill 创建与调用权限、MCP 工具发现和卸载、轮询状态、中英文词典一致性，以及 DSH `webServer` 前缀路由、OPTIONS 预检和 RPC 信封协议桥接。测试不需要模型 API key。
 
-浏览器端 `/` 候选缓存失效兼容逻辑会使用公开的 `connection/reset` 客户端事件；自动测试验证 Host/RPC 和浏览器 bundle 构建，但没有在本仓库内启动完整 Harness Web 做端到端菜单点击验证。外部文件改动仍依赖 filesystem provider 先完成 watcher 失效，必要时可在变更后点击管理页“刷新”。
+浏览器端 `/` 候选缓存失效兼容逻辑会使用公开的 `connection/reset` 客户端事件；服务端通过注入 `webServer` 与 `connection` 双重挂载 `/extensions` 路由并由 Cordis effect 托管生命周期，防止动态请求掉入前端静态资源的 405 fallback。自动测试验证 Host/RPC、HTTP 桥接和浏览器 bundle 构建，但没有在本仓库内启动完整 Harness Web 做端到端菜单点击验证。外部文件改动仍依赖 filesystem provider 先完成 watcher 失效，必要时可在变更后点击管理页“刷新”。
 
 ## 发布
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civilization/deepseek-harness-skill-mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Skill path and MCP server management for DeepSeek Harness Web",
   "license": "Apache-2.0",
   "repository": {
@@ -24,6 +24,7 @@
   "files": [
     "src",
     "lib",
+    "skills",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"

package/skills/extension-management/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: extension-management
+description: Manage custom Skill directories and Model Context Protocol (MCP) server configurations (stdio, streamable-http, sse) in DeepSeek Harness.
+---
+
+# Extension management (Skills & MCP)
+
+The `dsh-skill-mcp` plugin manages custom Skill directories and external Model Context Protocol (MCP) servers in DeepSeek Harness (DSH).
+
+When the user asks how to configure MCP servers or add custom Skill roots, describe the available tools and configuration schemas directly without probing the workspace.
+
+## Core Management Tools
+
+1. **`extensions_list`**:
+   - Lists all managed Skill sources and MCP configurations along with their enabled/disabled state and transport type.
+   - Note: An enabled state indicates authorization in configuration, not necessarily active connection health.
+
+2. **`extensions_inspect`**:
+   - Inspects the actual Skill catalog currently snapshot for the caller and all visible MCP tools (`mcp__*`).
+   - Requires `cwd`. Zero discovered tools does not automatically mean connection failure (servers may still be discovering or starting).
+
+3. **`extensions_add_skill`**:
+   - Adds an existing directory containing skill folders (each containing a `SKILL.md`).
+   - Parameters: `id` (unique internal identifier) and `directory` (absolute local path).
+   - Added sources are created disabled by default; call `extensions_set_enabled` to activate.
+
+4. **`extensions_add_mcp`**:
+   - Adds a new MCP server configuration (created disabled by default).
+   - Parameters: `id` and `configuration` (JSON string).
+   - Supported transport configurations:
+     - **`stdio`**:
+       ```json
+       {
+         "transport": "stdio",
+         "command": "node",
+         "args": ["D:/path/to/server.js"],
+         "cwd": "D:/path/to"
+       }
+       ```
+     - **`streamable-http`**:
+       ```json
+       {
+         "transport": "streamable-http",
+         "url": "http://127.0.0.1:9000/mcp"
+       }
+       ```
+     - **`sse`** (legacy SSE transport):
+       ```json
+       {
+         "transport": "sse",
+         "url": "http://127.0.0.1:9000/sse"
+       }
+       ```
+   - **Security rules**:
+     - Never supply plain-text API secrets, passwords, or authentication tokens in parameters or URLs.
+     - URLs with user credentials or access tokens are strictly rejected.
+
+5. **`extensions_set_enabled`**:
+   - Toggles an extension (`id` and `enabled: true|false`).
+   - Enabling a stdio server authorizes its executable to run when the DSH profile reloads.
+
+6. **`extensions_update_skill`** & **`extensions_update_mcp`**:
+   - Modifies existing Skill directory paths or updates MCP connection configurations while preserving the existing ID and enabled status.
+
+7. **`extensions_remove`**:
+   - Removes a managed configuration. Removing a Skill source removes its registration in DSH; it does NOT delete any files from the disk.
+
+## Recommended Workflows
+
+- **Adding a new MCP server**:
+  1. Call `extensions_list` to check existing IDs and prevent duplicate names.
+  2. Call `extensions_add_mcp` with a descriptive ID and valid JSON configuration.
+  3. Call `extensions_set_enabled` with `enabled: true`.
+  4. Inform the user that the configuration has been saved to the profile patch and tools will become available upon reload.
+- **Mounting custom skills**:
+  1. Verify the target directory contains valid Skill folders with `SKILL.md`.
+  2. Call `extensions_add_skill` with an explicit ID.
+  3. Call `extensions_set_enabled` to activate.

package/src/index.js

@@ -2,9 +2,10 @@
 import Schema from '@deepseek-ai/schemastery'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { readFile } from 'node:fs/promises'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { ExtensionStore } from './store.js'
-import { createWebHandler } from './web.js'
+import { createWebHandler, createWebHttpHandler } from './web.js'
 
 export const name = 'extension-manager'
 export const inject = ['tools', 'skills']
@@ -18,11 +19,35 @@ const output = {
 
 /** Register management operations. MCP processes are started only by the profile loader. */
 export async function apply(ctx, config) {
+  try {
+    const skillPath = new URL('../skills/extension-management/SKILL.md', import.meta.url)
+    const skillText = await readFile(skillPath, 'utf8')
+    const content = skillText.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trim()
+    ctx.effect(() => ctx.skills?.register({
+      name: 'extension-management',
+      description: 'Manage custom Skill directories and Model Context Protocol (MCP) server configurations.',
+      whenToUse: 'Use when configuring, inspecting, adding, or modifying external skills and MCP servers.',
+      source: 'bundled',
+      content,
+    }))
+  } catch {}
+
   const home = process.env.DSH_HOME || join(homedir(), '.dsh')
   const store = new ExtensionStore(config.patchPath || join(home, 'profiles', 'web', 'cordis.patch.yml'))
   await store.ensureNonFatalMcpStartup()
+
+  const webHandler = createWebHandler(store, ctx)
+  const httpHandler = createWebHttpHandler(store, ctx)
+
   ctx.inject(['connection'], web => {
-    web.connection.rpc.handle('/extensions', createWebHandler(store, ctx))
+    web.connection.rpc.handle('/extensions', webHandler)
+  })
+  ctx.inject(['webServer'], hostCtx => {
+    hostCtx.effect(() => hostCtx.webServer.register({
+      kind: 'prefix',
+      path: '/extensions',
+      handler: httpHandler,
+    }), 'extension-manager: /extensions route')
   })
   const register = (name, description, parameters, execute) => ctx.tools.register(defineTool({ name, description, parameters, output, execute }))
 

package/src/web.js

@@ -61,7 +61,7 @@ export function createWebHandler(store, ctx) {
     try {
       if (!Object.hasOwn(schemas, endpoint)) throw new Error('Unknown operation.')
       const args = schemas[endpoint](payload)
-      signal.throwIfAborted()
+      signal?.throwIfAborted()
       if (endpoint === 'add-skill') await store.addSkillPath(args.directory, signal, args.revision)
       if (endpoint === 'add-mcp') {
         const input = JSON.parse(args.configuration)
@@ -97,3 +97,68 @@ export function createWebHandler(store, ctx) {
     }
   }
 }
+
+/** HTTP server route handler that satisfies DSH WebServer and RPC envelope protocols. */
+export function createWebHttpHandler(store, ctx) {
+  const handler = createWebHandler(store, ctx)
+  return async (req, res) => {
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'access-control-allow-origin': '*',
+        'access-control-allow-methods': 'POST, OPTIONS',
+        'access-control-allow-headers': 'content-type, *',
+      })
+      res.end()
+      return
+    }
+    if (req.method !== 'POST') {
+      res.writeHead(405, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, error: { message: 'Method Not Allowed' } }))
+      return
+    }
+    const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+    const endpoint = pathname.startsWith('/extensions/') ? pathname.slice('/extensions/'.length)
+      : pathname === '/extensions' ? 'list' : undefined
+    if (!endpoint) {
+      res.writeHead(404, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, error: { message: 'Not Found' } }))
+      return
+    }
+
+    let raw = ''
+    try {
+      for await (const chunk of req) raw += chunk.toString('utf8')
+    } catch {
+      res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, error: { message: 'Failed to read request body.' } }))
+      return
+    }
+
+    let body = {}
+    if (raw.trim()) {
+      try { body = JSON.parse(raw) }
+      catch {
+        res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify({ ok: false, error: { message: 'Invalid JSON body.' } }))
+        return
+      }
+    }
+
+    const isRpcEnvelope = body && body.type === 'client-request' && typeof body.rpcId === 'string'
+    const actualEndpoint = isRpcEnvelope ? (body.method || endpoint) : endpoint
+    const payload = isRpcEnvelope ? (body.payload ?? {}) : body
+
+    const result = await handler(actualEndpoint, payload, req.signal)
+
+    const responseBody = isRpcEnvelope
+      ? { type: 'server-response', rpcId: body.rpcId, result }
+      : result
+
+    const data = JSON.stringify(responseBody)
+    res.writeHead(200, {
+      'content-type': 'application/json; charset=utf-8',
+      'content-length': Buffer.byteLength(data),
+    })
+    res.end(data)
+  }
+}