┌─────────────────────────── dsh 桌面版 / 网页版 ───────────────────────────┐│                                                                           ││  【Host 半边】Node.js 主进程（lib/index.js）          【浏览器半边】（lib/client.js）││   · 注册 N 个 skill 给模型        ◄── postMessage ──►  · 侧栏入口图标            ││   · 注册 2 个工具（数据读写）                            · 主区域 iframe 加载插件页面      ││   · Web 路由：页面 + catalog API + 文件服务                              ││   · 明暗主题转发给 iframe                                                 ││                                                                           ││  【数据目录】$DSH_HOME/<你的插件名>/                                        ││   你的 JSON 库 · 你的档案 · 你的缩略图                                     │└───────────────────────────────────────────────────────────────────────────┘

my-plugin/├── package.json          ① 声明：入口、客户端入口、版本门槛├── cordis.patch.yml      ① bundle 补丁（两行，照抄改个名）├── lib/                  ②③④ Host 半边（Node 主进程里跑）│   ├── index.js          ② skill 提供方 + 工具注册 + Web 路由│   ├── skills.js         ② 读 SKILL.md、适配插件环境│   ├── tools.js          ③ 给模型的工具│   ├── library.js        ⑦ 数据读写（Host 与 CLI 共用）│   └── thumbs.js         ③ 缩略图这类「工具的执行细节」├── client.js             ⑤ 浏览器半边（页面里跑）├── gallery/              ⑤ 插件页面本体（纯 HTML/CSS/JS）│   ├── index.html│   ├── app.js│   └── scheme.js         ⑤ 明暗主题跟随├── scripts/              ⑦ 命令行入口（给人在终端用）├── skills/               ⑨ 外部 skill 快照 + manifest.json└── test/                 ⑧ 测试

{  ”name”: ”my-dsh-plugin”,  ”version”: ”0.1.0”,  ”type”: ”module”,  ”main”: ”lib/index.js”,                    // Host 半边入口  ”exports”: {    ”.”: ”./lib/index.js”,    ”./client”: ”./client.js”                // 浏览器半边入口（固定约定路径）  },  ”engines”: {    ”node”: ”^22.19.0 || >=24.0.0”,    ”dsh”: ”>=0.2.1-rc.2 <0.3.0”             // 兼容的 dsh 版本区间  },  ”dsh”: {    ”bundle”: { ”patch”: ”./cordis.patch.yml” },    ”client”: { ”platform”: ”web”, ”inject”: [] }  }}

# Host 半边（skill 提供方、工具、页面和接口）。浏览器半边由 package.json 的 dsh.client 声明加载。- insert:    - id: my-plugin      name: 'my-dsh-plugin'

// lib/index.js —— Host 半边最小骨架export const name = 'my-plugin'// 声明依赖的服务，宿主会等它们就绪再调用 applyexport const inject = ['skills', 'tools', 'webServer']export function apply(ctx) {  // 所有注册都包进 ctx.effect()：插件被卸载/重载时自动撤销，不留脏东西  ctx.effect(() => console.log('my-plugin loaded'))}

---name: my-skilldescription: 一句话说清楚这个 skill 干什么、什么时候用。模型靠这段话决定要不要自主调用它，务必具体。---# 我的技能（写给 AI 的操作步骤……）

import { existsSync, readFileSync, readdirSync } from 'node:fs'import { join } from 'node:path'function parse(file) {  const text = readFileSync(file, 'utf8')  const m = text.match(/^---\n([\s\S]*?)\n---\n?/)  if (!m) return null  const field = (k) => (m[1].match(new RegExp(`^${k}:\\s*(.+)$`, 'm')) || [])[1]?.trim().replace(/^([”'])(.*)\1$/, '$2')  const name = field('name'), description = field('description')  return name && description ? { name, description, body: text.slice(m[0].length) } : null}export function readSkills(dirs) {  return [].concat(dirs).flatMap((dir) =>    !existsSync(dir) ? [] :    readdirSync(dir, { withFileTypes: true })      .filter((d) => d.isDirectory() && existsSync(join(dir, d.name, 'SKILL.md')))      .map((d) => ({ dir: join(dir, d.name), file: join(dir, d.name, 'SKILL.md'), ...parse(join(dir, d.name, 'SKILL.md')) }))      .filter((s) => s.name))}export function createSkillProvider(dirs) {  const candidate = (s) => ({    name: s.name,    description: s.description,    path: s.file,    invocation: { modelInvocable: true, userInvocable: true },   // 模型可自主调用 + 用户可 /命令 调用    source: 'bundled',    provider: 'my-plugin',    rank: 600,                                                    // 用户提供方排前面：同名时让位    locator: s.dir,                                               // get() 时靠它找回这份 skill    resourceBase: { kind: 'directory', path: s.dir },             // 告诉 dsh skill 的附属资源在哪  })  return {    name: 'my-plugin',    async list() { return readSkills(dirs).map(candidate) },    async get(c) {      const s = readSkills(dirs).find((x) => x.dir === c.locator && x.name === c.name)      if (!s) return undefined      const content = s.body.replaceAll('', s.dir)   // 正文里的占位符换成真实目录      const { rank, locator, ...summary } = candidate(s)      return { ...summary, content }    },  }}

const SKILL_DIRS = [join(ROOT, 'skills')]   // ROOT = 插件安装目录ctx.effect(() => ctx.skills.registerProvider(() => createSkillProvider(SKILL_DIRS)))

// ① 替换表：每条规则必须命中原文（测试会断言，上游改版就报警，不悄悄失效）const REWRITES = {  'my-skill': [    [/### Step 0 · 检查更新[^\n]*\n[\s\S]*?(?=\n### Step 1)/,     '### Step 0 · 检查更新\n\n在插件里跳过这一步：skill 随插件版本更新，不是 git 仓库，不要运行 git 命令，也不用向用户提起。\n'],  ],}// ② 附注：把独立仓库的用法换成插件环境的用法function addendum(skill) {  return `---## 在 ${'插件名'} 插件（DSH）里使用- 本 skill 的目录是 \`${skill.dir}\`，上文的 scripts/、assets/ 都相对这个目录。- 依赖已随插件安装，跳过 npm install。- 交付以后调用 \`my_plugin_save\` 工具登记结果……`}

// lib/tools.jsconst str = (description, extra = {}) => ({ type: 'string', description, ...extra })const PARAMS = {  type: 'object',  additionalProperties: false,          // 必须显式写！dsh 会校验  required: ['path', 'title'],  properties: {    path: str('交付物的绝对路径'),    title: str('标题'),  },}export const saveTool = {  name: 'my_plugin_save',               // 小写字母开头，[a-z][a-z0-9_]*  description: '把结果登记进我的插件，用户就能在侧栏页面看到它。同一个文件重复登记只会更新。',  parameters: PARAMS,  timeoutMs: 60_000,  output: {    schema: { type: 'object', additionalProperties: false, required: ['id'], properties: { id: { type: 'string' } } },    // render 把执行结果翻译成给模型看的自然语言——模型据此向用户汇报    render: (_args, v) => [{ type: 'text', text: `已登记（${v.id}）。用户可以在侧栏看到它。` }],  },  async execute(args) {    // 注册的是原始 JSON Schema，没有帮手校验，自己挡住缺字段和类型错    if (!args?.path) throw new Error('缺少 path')    if (!isAbsolute(args.path)) throw new Error('path 要用绝对路径')    const id = addWork(args.path, { title: args.title })    return { id }  },}export const TOOLS = [saveTool]

for (const tool of TOOLS) ctx.tools.register(tool)

// lib/index.jsconst BASE = '/guizang-design'ctx.effect(() =>  ctx.webServer.register({    kind: 'prefix',    path: BASE,    async handler(req, res) {          // 原生 Node http.req / http.res      const url = new URL(req.url || '/', 'http://x')      const rest = decodeURIComponent(url.pathname.slice(BASE.length)) || '/'      if (rest === '/api/catalog') return sendJson(res, 200, catalog())   // 页面数据接口      if (rest === '/api/works/remove') { /* 读 JSON body、处理 */ }      if (req.method !== 'GET' && req.method !== 'HEAD') return notFound(res)      // 文件服务：/examples/*、/works//*、/thumbs/*、其余按静态文件处理      const f = safeFile(join(ROOT, 'gallery'), rest === '/' ? 'index.html' : rest.slice(1))      return f ? serveFile(req, res, f) : notFound(res)    },  }),)

import { createReadStream, existsSync, realpathSync, statSync } from 'node:fs'import { extname, join, normalize, sep } from 'node:path'// 只在 dir 里面找文件：拒绝点文件段、目录外的符号链接function safeFile(dir, rel) {  if (!dir || rel.split('/').some((p) => p.startsWith('.'))) return null  let base  try { base = realpathSync(dir) } catch { return null }  const file = normalize(join(base, rel))  if (!file.startsWith(base + sep) || !existsSync(file)) return null  const real = realpathSync(file)  return real.startsWith(base + sep) && statSync(real).isFile() ? real : null}const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', /* … */ }function serveFile(req, res, file) {  res.writeHead(200, { 'content-type': MIME[extname(file).toLowerCase()] || 'application/octet-stream',                       'content-length': statSync(file).size, 'cache-control': 'no-cache' })  if (req.method === 'HEAD') return res.end()  createReadStream(file).pipe(res)}// POST 接口的 JSON 读取：限 Content-Type、校验同源、限 16KBfunction readJson(req, max = 16 * 1024) {  return new Promise((resolve, reject) => {    const origin = req.headers.origin    if (req.method !== 'POST') return reject(Object.assign(new Error('method'), { status: 405 }))    if (!/^application\/json\b/.test(req.headers['content-type'] || '')) return reject(Object.assign(new Error('type'), { status: 415 }))    if (origin && origin.replace(/^https?:\/\//, '') !== req.headers.host) return reject(Object.assign(new Error('origin'), { status: 403 }))    // …按 max 限量收 chunk，end 时 JSON.parse  })}

// gallery/app.js（节选）function start(prompt) {  if (window.parent !== window)    return window.parent.postMessage({ type: 'my-plugin:start', prompt }, location.origin)  // 嵌在 dsh 里：交给父页面  navigator.clipboard?.writeText(prompt)   // 单独打开页面：降级为复制草稿}

// client.js —— 浏览器半边window.__ModuleLoader__.load({  id: 'my-dsh-plugin',  factory: (require) => {    const React = require('react')    const h = React.createElement    // 侧栏图标：一个 24×24 线条 SVG 组件    function MyIcon(props) {      const s = (props && props.size) || 18      return h('svg', { width: s, height: s, viewBox: '0 0 24 24', fill: 'none',                        stroke: 'currentColor', strokeWidth: 1.5 },        h('path', { d: '…你的图标路径…' }))    }    function MyPanel() {      const ref = React.useRef(null)      React.useEffect(() => {        function onMessage(e) {          const frame = ref.current          if (!frame || e.source !== frame.contentWindow || e.origin !== location.origin) return          const m = e.data          if (!m || m.type !== 'my-plugin:start' || typeof m.prompt !== 'string') return          try {            // 开一个新对话并把草稿填进输入框（不直接发送！）            ctx.uiWorkspace.startSession(undefined, { prompt: m.prompt, whenDraftExists: 'replace' })          } catch (err) {            frame.contentWindow.postMessage({ type: 'my-plugin:start-failed', message: String(err) }, location.origin)          }        }        addEventListener('message', onMessage)        return () => removeEventListener('message', onMessage)      }, [])      return h('iframe', { ref, src: '/my-plugin/', title: '我的插件', allow: 'fullscreen',                           style: { width: '100%', height: '100%', border: 0 } })    }    function apply(ctx) {      // ① 侧栏列表里注册入口（order 决定排位）      ctx.slots.inject('sidebar.panellist', () =>        ctx.slots.register({ name: 'sidebar.panellist', id: 'my-plugin', order: 6, label: () => '我的插件' }, MyIcon))      // ② 主区域注册面板（点侧栏入口时渲染）      ctx.slots.inject('main', () => ctx.slots.register({ name: 'main', key: 'my-plugin' }, MyPanel))    }    const exports = { isPlugin: true, inject: ['slots', 'uiWorkspace'], apply }    return exports  },})

页面按钮 click → postMessage({type:'my-plugin:start', prompt:草稿})             → client.js 收到（校验 e.source / e.origin / e.data.type）             → ctx.uiWorkspace.startSession(undefined, { prompt, whenDraftExists:'replace' })             → dsh 开新会话，草稿进输入框，用户补完内容自己发送

// client.js 里的 apply（节选）ctx.inject(['theme'], (c) => {  const push = (snap) => frames.forEach((f) => f.contentWindow?.postMessage(    { type: 'my-plugin:scheme', scheme: snap.active.colorScheme }, location.origin))  push(c.theme.getTheme())  c.on('theme/change', push)})

// gallery/scheme.js —— 放在  顶部同步执行(() => {  const root = document.documentElement  const set = (dark) => { root.dataset.scheme = dark ? 'dark' : 'light' }  let host = null  try { if (parent !== window) host = parent.document.body } catch {}  if (host) set(host.hasAttribute('data-ds-dark-theme'))          // 嵌在 dsh 里：读宿主  else {    const media = matchMedia('(prefers-color-scheme: dark)')       // 单独打开：跟随系统    set(media.matches); media.addEventListener('change', (e) => set(e.matches))  }  addEventListener('message', (e) => {    if (e.source !== parent || e.origin !== location.origin) return    if (e.data?.type === 'my-plugin:scheme') set(e.data.scheme === 'dark')  })})()

// lib/library.jsimport { homedir } from 'node:os'import { join } from 'node:path'export const dataDir = () => join(process.env.DSH_HOME || join(homedir(), '.dsh'), 'my-plugin')

function writeLibrary(works) {  mkdirSync(dataDir(), { recursive: true })  const tmp = libraryFile() + '.' + process.pid  writeFileSync(tmp, JSON.stringify({ works }, null, 2) + '\n')  renameSync(tmp, libraryFile())}

#!/usr/bin/env node// scripts/library.mjs —— 终端手动处理用；模型在 dsh 里走工具，不走这里import { join } from 'node:path'import { addWork, listWorks, removeWork } from '../lib/library.js'const args = process.argv.slice(2)const [cmd, target] = argsconst opt = (k) => (args.includes(`--${k}`) ? args[args.indexOf(`--${k}`) + 1] : '')if (cmd === 'add' && target) {  const w = addWork(target, { skill: opt('skill'), title: opt('title') })  console.log(`已登记：${w.title}（${w.id}）`)} else if (cmd === 'list') {  for (const w of listWorks()) console.log(`${w.id}  ${w.title}`)} else if (cmd === 'remove' && target) {  console.log(removeWork(target) ? '已移除' : '没有这个 id')}

// test/plugin.test.mjsimport assert from 'node:assert/strict'import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'import { join } from 'node:path'import { test } from 'node:test'const home = mkdtempSync(join(tmpdir(), 'my-plugin-'))process.env.DSH_HOME = home                       // 必须在 import 库代码之前设置const { createSkillProvider, readSkills, REWRITES } = await import('../lib/skills.js')const { TOOLS } = await import('../lib/tools.js')test('skill 都注册了，名字合法、描述够长', async () => {  const provider = createSkillProvider([join(ROOT, 'skills')])  const names = (await provider.list({})).map((c) => c.name)  for (const c of await provider.list({})) {    assert.match(c.name, /^[a-z0-9]+(-[a-z0-9]+)*$/)    assert.ok(c.description.length > 20)  }})test('每条 rewrite 都命中原文（上游改版时这里失败，而不是替换悄悄失效）', () => {  for (const [name, rules] of Object.entries(REWRITES)) {    const s = readSkills([join(ROOT, 'skills')]).find((x) => x.name === name)    for (const [from] of rules) assert.match(s.body, from, `${name}：上游改了这一段，更新 REWRITES`)  }})test('工具定义符合 dsh 注册表要求', () => {  const walk = (n, at) => {    if (n.type === 'object') {      assert.equal(typeof n.additionalProperties, 'boolean', `${at}.additionalProperties 要写明`)      for (const k of n.required || []) assert.ok(n.properties[k], `${at}.required ${k}`)      for (const [k, p] of Object.entries(n.properties)) walk(p, `${at}.${k}`)    }  }  for (const t of TOOLS) {    assert.match(t.name, /^[a-z][a-z0-9_]*$/)    assert.equal(typeof t.output.render, 'function')    walk(t.parameters, `${t.name}.parameters`)  }})

#!/usr/bin/env nodeimport { execFileSync } from 'node:child_process'import { cpSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'import { dirname, join } from 'node:path'import { fileURLToPath } from 'node:url'const ROOT = fileURLToPath(new URL('..', import.meta.url))const SOURCES = [  { name: 'my-skill', repo: 'https://github.com/you/my-skill.git' },]const SKIP = [/^README[^/]*$/i, /^docs?\//, /^tests?\//, /^\.github\//, /^package(-lock)?\.json$/]const git = (cwd, ...a) => execFileSync('git', a, { cwd, encoding: 'utf8' }).trim()rmSync(join(ROOT, 'skills'), { recursive: true, force: true })const manifest = { skills: [] }for (const s of SOURCES) {  const src = join(ROOT, '.vendor-cache', s.name)  execFileSync('git', ['clone', '-q', '--depth', '1', s.repo, src])  const commit = git(src, 'rev-parse', 'HEAD')  const files = git(src, 'ls-files').split('\n').filter((f) => f && !SKIP.some((re) => re.test(f)))  const dest = join(ROOT, 'skills', s.name)  for (const f of files) { mkdirSync(dirname(join(dest, f)), { recursive: true }); cpSync(join(src, f), join(dest, f)) }  manifest.skills.push({ name: s.name, repo: s.repo, commit, files: files.length })  console.log(`${s.name}  ${commit.slice(0, 7)}  ${files.length} 个文件`)}writeFileSync(join(ROOT, 'skills', 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')

”files”: [ ”lib”, ”client.js”, ”gallery”, ”skills”, ”scripts”, ”cordis.patch.yml” ],