配置与发布

一句话版：插件配置 = schemastery 定义的 Config schema(patch 层按 id 覆盖)**,外加运行时用户配置 ctx.settings;**发布 = package.json dsh 字段 + 挂载方式,让用户一行装上。

这是插件开发系列的收尾:让你的插件可配置、可分发、可维护。

一、静态配置 schema

import z from '@deepseek-ai/schemastery'
import { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export const Config = z.object({
  greeting: z.string().default('你好'),
  maxItems: z.number().step(1).min(1).default(10),
})

apply(ctx, config) 拿到的就是校验后的配置(plugin.Config 被拷到 runtime 做 ~standard 校验)。

用 @deepseek-ai/schemastery,别用裸名 schemastery(rescope,见 插件解剖)。

二、用户如何覆盖(patch 层)

# profile 的 cordis.patch.yml
- id: my-plugin
  name: '@dsh-external/my-plugin'
  config:
    greeting: 嗨
    maxItems: 5

处理:patch 按 entry id 定位(不要求等于注册名);config 是整行替换非深合并;

完整应用序:profile.bundles → win32 shell → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → --patch 覆盖(见 插件解剖)。

三、运行时用户配置(ctx.settings)

patch 是静态层。要让最终用户在 UI/Settings 里改,用 ctx.settings:

import { settingsNamespace } from '@deepseek-ai/dsh-settings'
import z from '@deepseek-ai/schemastery'
import { Context } from '@deepseek-ai/cordis'

const ns = settingsNamespace('my-plugin')
const schema = z.object({
  greeting: z.string().default('你好'),
  maxItems: z.number().step(1).min(1).default(10),
})

export async function apply(ctx: Context) {
  const scope = ctx.settings.register(ns, schema, { /* base? */ })
  const s = await ctx.settings.get(ns)   // 解析:schema默认 → composition base → 用户层
  // 用户更新: const updated = await scope.update({ greeting: '嗨' })
}

• 文件提供者 dsh-settings-file,默认 $DSH_HOME/settings.yaml,热发布外部编辑
• 乐观并发 revision;settings/document-updated 事件让 UI 和插件同步
• 这是"用户能改我插件什么"的真实通道,与 patch 互补

四、发布到组织

1. 仓库清单(package.json 的 dsh 字段：不存在 dsh.plugin.json)

{
  "name": "@dsh-external/my-plugin",
  "version": "0.1.0",
  "exports": { ".": "./lib/index.js" },
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

2. 提交到 dsh-external 组织

git push origin main
# 在 dsh-external 组织下新建仓库(或提交现有组织)

3. 用户一行安装

dsh plugin --profile web add "github:dsh-external/my-plugin#main"

五、bundle vs repository

	Bundle 插件	repository 插件
载体	git 源一行(github:...#main)	.dsh-plugin 目录(外部 plugin-registry 机制)
生效	重启 dsh web	即改即生效
属于	DSH 标准	第三方 plugin-console + home 层

六、发布检查清单

项	检查
构建产物	lib/ 已入库,或构建脚本可用
依赖完整	注意裸名依赖:必要时把裸名装进插件自身 node_modules
组合正常	dsh web --dump-config 无异常
文档	中英文 README(组织惯例 README.md + README.zh.md)
schema	Config/ctx.settings schema 都声明了默认值

七、验证发布

# 干净环境模拟用户安装
dsh plugin --profile web add "github:dsh-external/my-plugin#main"
dsh web --dump-config | grep my-plugin

课程完结 🎉

到这里,插件开发闭环完成:

插件是什么(解剖)→ 怎么写(hello → tool → service → events)→ 怎么配 → 怎么发

新能力、新行为、新 UI：你都能自己加了。再接再厉:完整的 学习路径 里还有能力要点与进阶。