从 0 到 1 开发 dsh 插件实战课
以「查天气 + 动效卡片」插件为完整案例，带你走完一个真实 dsh 插件的全部开发流程：需求 → 环境 → 骨架 → 实现（工具/技能/系统提示/浏览器端）→ 双端构建 → 安装测试 → 界面验收 → 发布维护。
写在前面
这门课教什么
DeepSeek Harness（简称 dsh）是一个"万物皆插件"的智能体框架。给 dsh 增加任何新能力——让模型会查天气、会调用你的系统、会画出好看的界面——本质上都是写一个插件。
这门课以一个真实的天气插件（我们已经在 dsh 网页里跑通、显示过天气卡片的项目）为蓝本，手把手带你从零写出、构建、安装并测试一个插件。你最终会得到：
- 输入"北京今天天气怎么样"，模型自动调用
weather 工具；
- 工具调用 Open-Meteo 天气 API 拿到真实数据（不是编的）；
- 模型按
weather-briefing 技能规范播报："北京今天晴天 ☀️ 29°C 东风 6km/h……"；
- 在 dsh 网页界面里，渲染出一张会动的天气卡片（☀️ 旋转光芒、🌧 下落雨线、❄️ 飘落雪花……）。
这门课适合谁
- 完全没接触过 dsh，但会一点前端/Node 的开发者；
- 想给自己的智能体（Agent）增加自定义工具和界面的产品/技术人员；
- 想理解"插件化智能体框架"到底怎么回事的人。
怎么学效果最好
- 跟着做：每一章的代码和命令都自己敲一遍，别只看。
- 看真实报错：这门课记录了我们开发时真实踩过的坑和报错原文，遇到类似问题直接查附录 C。
- 遇到卡点先自查：先看是不是 Node 版本、junction 顺序、产物没同步这类"高频三坑"。
第 1 部分 · 认识 dsh
第 1 章 dsh 是什么：一个「万物皆插件」的智能体框架
1.1 传统智能体 vs dsh
传统做法：模型、工具、对话循环、网页界面……全部"焊死"在一个程序里。想加一个能力，就得改源码、重新编译、重新发布。这对第三方开发者非常不友好。
dsh 换了一种哲学——everything-is-a-plugin（万物皆插件）：
- dsh 的核心几乎是一个"空壳"（无特权内核）；
- 几乎所有能力——模型适配器、工具注册表、Agent 循环、网页界面——本身都是插件；
- 所有插件挂在一个叫 Cordis 的容器框架上，按需组合、替换、扩展。
一句话：dsh = 一台"所有零件都能换"的智能体机器。写插件 = 造一个零件装上去。不需要 fork 源码。
1.2 你的插件挂在哪里
当你写一个天气插件时，你实际上是在往这台机器上加三样东西：
| 东西 | 类比 | 作用 |
|---|
| 工具（Tool） | 给模型"手" | 模型可以调用的动作：查天气、查数据、算东西 |
| 技能（Skill） | 给模型"说明书" | 教模型"按什么规范产出"：天气怎么播报、文案怎么写 |
| 系统提示 | 给模型"入职培训" | 教模型"什么时候该用哪个工具" |
三样配合，模型才能"会查 → 会播报 → 播得好"。
1.3 一个插件通常写"两端"
dsh 网页端的插件往往是双端的：
- Node 端（后端进程，可信环境）：负责"干活"——注册工具、调 API、算数据；
- 浏览器端（前端沙箱 iframe，受限环境）：负责"画画"——把工具结果渲染成卡片、图表、动效。
两端通过 meta 数据衔接：Node 端算好结构化数据放进 meta，浏览器端读取并渲染。
这正是我们天气插件的设计：Node 端调 Open-Meteo 拿温度风力，浏览器端用这些数据画一张会动的天气卡片。
第 2 章 一个 dsh 插件的生命周期（全景图）
写一个插件不是只写代码，而是一条完整流水线。全程共 7 步，本课程后续章节逐一展开：
① 选型 → ② 环境 → ③ 骨架 → ④ 实现 → ⑤ 构建 → ⑥ 安装 → ⑦ 测试
第 ① 步 选型：这是哪一类插件？
动手前先回答："用户要加的新能力属于哪一类？" dsh 插件分四种（详见第 15 章）：
| 类型 | 解决什么 | 什么时候用 |
|---|
| Tool Plugin | 让模型拥有新动作 | 90% 的需求，比如查天气、查数据库、调 API |
| Skill 插件 | 教模型按规范产出 | 想让输出风格统一、结构固定 |
| Service Provider | 换底层驱动 | 换模型网关、换文件沙箱 |
| Event Interceptor | 关键路径加料 | 审批、审计、限流 |
| Agent Loop | 重写核心循环 | 高难定制，一般用不到 |
选型口诀：Provider 是"换驱动"，Tool 是"装软件"，Interceptor 是"加关卡"，AgentLoop 是"换引擎"。
我们的天气插件 = Tool Plugin（工具）+ Skill 插件（技能）+ 系统提示 + 浏览器端渲染，是 dsh 插件最典型的组合。
第 ② 步 环境准备
- Node.js 必须 22+（dsh 0.1.x 用到
Promise.withResolvers、node:zlib zstd、node:module stripTypeScriptTypes，Node 20 必崩）；
- 能运行
dsh 命令；
- 定位到 dsh 发布包缓存（构建时要用它里面的宿主依赖，见第 11 章）。
第 ③~④ 步 骨架与实现
用脚手架一键生成项目骨架，然后填充四块核心代码：工具、技能、系统提示、浏览器端。
第 ⑤ 步 双端构建
用 tsdown 一次构建出两个产物：lib/index.js（Node 端）+ lib/client.js（浏览器端单文件）。
第 ⑥ 步 安装进 profile
dsh 用 profile（配置档案）管理插件集合。dsh plugin --profile 名字 add file:路径 即可把插件装进去。
第 ⑦ 步 测试与验收
- headless 冒烟：命令行问一句，验证"识别意图 → 调工具 → 播报"全链路；
- web 界面验收（最终标准）：浏览器里看到工具调用 + 动效卡片渲染。
重要提醒：命令行跑通 不算完成。用户真正看到的是网页界面。所以最终验收必须在浏览器里做。这也是本课程贯穿始终的标准。
第 2 部分 · 环境与骨架
第 3 章 环境准备：Node 22 是硬门槛
3.1 我们真实踩到的坑
开发天气插件时，第一次启动 dsh 直接崩了，报错类似：
TypeError: Promise.withResolvers is not a function
TypeError: zlib.createZstdDecompress is not a function
TypeError: module.stripTypeScriptTypes is not a function
原因：dsh 0.1.x 必须在 Node 22+ 上运行，而我们系统里的 node 是 v20.20.2。Node 20 缺少这些 API。
3.2 dsh 到底用了哪些 Node 22 新能力
| Node 22 新能力 | dsh 用来干什么 |
|---|
Promise.withResolvers | 标准库新增的 Promise 构造方式，dsh 内部异步逻辑用到 |
node:zlib 的 createZstdDecompress | 解压 zstd 压缩的数据 |
node:module 的 stripTypeScriptTypes | 让 dsh 能直接加载/剥离 TS 类型 |
这些在 Node 20 里都不存在，所以不是配置问题，是版本问题。
3.3 怎么解决
方法一（推荐）：升级 Node 到 22+。官网下载 LTS 版（22.x）安装即可。
方法二（本机多版本）：如果你系统里同时有多个 node，直接用 Node 22 的 node.exe 跑 dsh，不污染全局：
# 找到 node22 的 node.exe，直接调 dsh 的入口文件
C:\Users\49707\node22\node-v22.23.2-win-x64\node.exe C:\Users\49707\AppData\Local\npm-cache\_npx\<hash>\node_modules\@deepseek-ai\dsh\lib\bin.js --profile web
方法三：把 node22 目录放到 PATH 的最前面，这样 dsh、node、npx 都优先用 Node 22。
验证：node -v 必须输出 v22.x 及以上。
连带坑：构建工具 tsdown 0.22+ 也要求 Node 22。如果只能在 Node 20 环境构建，请用 tsdown@^0.19.0（我们就是这么降级的）。
3.4 一键脚本的完整流程
环境确认后，构建脚本按这个顺序工作（见 scripts/build.ps1）：
# ① 安装构建工具（tsdown/typescript）
npm install --legacy-peer-deps
# ② 链宿主依赖（junction，必须放在 npm install 之后！）
python scripts/link_deps.py
# ③ 双端打包
npx tsdown
# ④ 自检产物
# 检查 lib/index.js 与 lib/client.js 是否生成
为什么 link_deps 必须放在 npm install 之后？ 因为 npm install 会把 node_modules 里的链接清掉重新装，如果在它之前建链接，会被冲掉。这是开发时反复踩的坑（详见第 11 章）。
第 4 章 认识插件骨架：每个文件是干什么的
4.1 用脚手架一键生成
不用手动搭文件，用 skill 自带的脚手架脚本：
python scripts/scaffold_plugin.py D:/dev/weather-plugin --name @me/weather-plugin --desc "查天气 + 动效卡片"
它会自动复制模板、替换包名和描述占位符，生成一个结构完整、可直接开始改代码的项目。
4.2 项目结构逐文件解读（真实 API 版）
weather-plugin/
├─ package.json # 插件"身份证"：入口/依赖/清单字段
├─ cordis.patch.yml # 挂载声明：把插件插进 profile 的 layer 栈
├─ tsdown.config.ts # 双端打包配置
├─ tsconfig.json # Node 端 TS 配置
├─ tsconfig.client.json # 浏览器端 TS 配置（lib: DOM）
├─ scripts/
│ ├─ build.ps1 # 一键构建（Windows）
│ ├─ link_deps.py # junction 链宿主依赖
│ └─ sync_profile.py # 构建后同步产物到已安装的 profile
└─ src/
├─ index.ts # 插件入口 apply + 配置 Config
├─ tool.ts # 工具定义（defineTool）
├─ skill.ts # 技能定义（SkillProvider）
├─ fragment.ts # 共享契约纯函数（双端共用）
└─ client/
└─ index.tsx # 浏览器端 Toolview 组件
4.3 package.json 里的关键字段（容易看懵）
dsh 插件不用 dsh.plugin.json（那是旧版资料的说法），而是在 package.json 里声明：
{
"name": "@me/weather-plugin",
"type": "module",
"main": "lib/index.js",
"exports": {
".": "./lib/index.js",
"./client": "./lib/client.js",
"./cordis.patch.yml": "./cordis.patch.yml"
},
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": { "inject": ["@deepseek-ai/dsh-client-runtime"], "platform": "web" }
},
"dshx": {
"contributes": { "tools": ["weather"], "skills": ["weather-briefing"] }
},
"peerDependencies": {
"@deepseek-ai/cordis": "^4.0.1-rc.1",
"@deepseek-ai/dsh-tools": "*",
"@deepseek-ai/dsh-skill": "*",
"@deepseek-ai/dsh-system-prompt": "*",
"@deepseek-ai/schemastery": "^3.18.1-rc.1",
"react": "^18.2.0"
}
}
| 字段 | 干什么 |
|---|
dsh.bundle.patch | 指向 cordis.patch.yml，告诉 dsh 怎么挂载插件 |
dsh.client.inject / dsh.client.platform | 浏览器端注入声明（web 平台） |
dshx.contributes.tools/skills | 插件提供的工具/技能清单（发现用） |
peerDependencies | 声明依赖的宿主包（不打包，运行时由 dsh 提供） |
4.4 挂载声明 cordis.patch.yml
- insert:
- id: weather-plugin # 插件实例 id
name: '@me/weather-plugin' # npm 包名
这个文件让 dsh 启动时知道"要加载一个叫 weather-plugin 的插件"，并把它挂进当前 profile 的 layer 栈。
第 3 部分 · 开发核心
第 5 章 插件入口 apply 与配置 Config
5.1 一切的起点：index.ts
每个插件都有一个入口文件 src/index.ts，导出 name、inject、Config 和 apply 函数。dsh 启动时加载插件，调用 apply(ctx, config)，把容器上下文 ctx 传给你。
import type { Context as CordisContext } from '@deepseek-ai/cordis'
import type SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import type SkillService from '@deepseek-ai/dsh-skill'
import type ToolRegistry from '@deepseek-ai/dsh-tools'
import z from '@deepseek-ai/schemastery'
import { weatherTool } from './tool.js'
import { weatherSkillProvider } from './skill.js'
import type { WeatherClientConfig } from './client.js'
// 声明"这个插件要用哪些服务"，并给出合并后的 ctx 类型
type Context = CordisContext & {
tools: ToolRegistry
systemPrompt: SystemPrompt
skills: SkillService
}
export const name = 'weather-plugin' // 插件唯一 id
export const inject = ['tools', 'systemPrompt', 'skills'] // 依赖的服务
export interface Config extends WeatherClientConfig {}
export const Config: z<Config> = z.object({
baseUrl: z.string().default('https://api.open-meteo.com/v1/forecast')
.description('Open-Meteo 天气 API 基地址；可指向自建镜像做离线开发。'),
geocodingUrl: z.string().default('https://geocoding-api.open-meteo.com/v1/search')
.description('Open-Meteo 地理编码 API 基地址。'),
timeoutMs: z.number().step(1).min(1_000).default(10_000)
.description('单次天气请求超时（毫秒）。'),
})
export function apply(ctx: Context, config: Config): void {
// 把配置收敛成一个运行时对象（带默认值兜底）
const resolved: WeatherClientConfig = {
baseUrl: config.baseUrl ?? 'https://api.open-meteo.com/v1/forecast',
geocodingUrl: config.geocodingUrl ?? 'https://geocoding-api.open-meteo.com/v1/search',
timeoutMs: config.timeoutMs ?? 10_000,
}
// 三件套都包在 ctx.effect 里注册：插件被移除时自动清理
ctx.effect(() => ctx.tools.register(weatherTool(resolved)), 'weather-plugin.tool')
ctx.effect(() => ctx.skills.registerProvider(() => weatherSkillProvider), 'weather-plugin.skill')
ctx.effect(() => ctx.systemPrompt.section({
name: 'tool:weather',
order: 117,
text: PROMPT_TEXT,
}), 'weather-plugin.prompt')
}
5.2 逐块拆解
| 部分 | 说明 |
|---|
export const name | 插件唯一 id，必须和 cordis.patch.yml 的 id 一致 |
export const inject | 声明依赖的服务。ctx 就能访问 .tools / .skills / .systemPrompt |
export const Config | 用 schemastery 定义配置 schema，带默认值 + 中文说明。用户可在 profile/补丁层覆盖，不用改代码 |
export function apply | 真正干活的地方：注册工具、注册技能、注入系统提示 |
ctx.effect(fn, key) | 把注册动作挂到插件生命周期，卸载自动清理（"插头的保险丝"） |
为什么用 ctx.effect？ 如果插件被移除/停用，effect 会自动注销它注册的工具、技能、系统提示，不会留下"幽灵注册"污染容器。这是 dsh 插件规范写法。
第 6 章 写工具：让模型「会查天气」（defineTool）
6.1 工具的本质
工具 = 给模型看的"可执行函数签名" + 你写的 execute 实现。
- 模型看到的是
description 和 parameters（决定它会不会调、怎么调）；
- 模型调用后，你的
execute 去干活（这里就是查天气 API）；
- 你返回的数据，一部分给模型看（短文本），一部分给浏览器渲染（结构化数据）。
6.2 天气数据源：Open-Meteo（免 key）
我们用的天气 API 是 Open-Meteo，完全免费、无需注册 API key：
- 地理编码：把城市名转成经纬度
GET https://geocoding-api.open-meteo.com/v1/search?name=北京&count=1&language=zh
- 实时天气：按经纬度拿天气
GET https://api.open-meteo.com/v1/forecast?latitude=..&longitude=..¤t_weather=true&daily=..&timezone=auto&forecast_days=1
6.3 defineTool 四要素
真实 API 用 defineTool(...) 产出工具定义，再 ctx.tools.register(...) 注册：
import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
import { normalizeItems, summarize, myMetaFrom } from './fragment.js'
export function weatherTool(config: WeatherClientConfig, fetchImpl?: typeof fetch): ToolDefinition {
return defineTool({
name: 'weather',
description: '查询指定城市的实时天气。当用户询问天气、温度、雨雪、风力时使用。',
parameters: {
city: { type: 'string', required: true, description: '城市名，例如：北京、上海、London' },
unit: { type: 'string', enum: ['celsius', 'fahrenheit'], description: '温度单位，默认摄氏度' },
},
output: {
schema: { /* ... */ },
render: (_args, value) => [{ type: 'text', text: value.text }],
presentationMeta: (_args, value) => ({ kind: 'weather', ...value.weather }),
},
isConcurrencySafe: () => true,
async execute(args) { /* 查天气，返回 { text, weather } */ },
presentCall: () => ({ card: 'generic', title: '查天气', kind: 'other' }),
presentResult() { /* 结果卡片标题 */ },
})
}
四要素详解：
| 要素 | 作用 | 写作要点 |
|---|
name | 工具名 | 蛇形命名，唯一 |
description | 说明 | 模型决定调不调它全靠这句。写清"做什么 + 何时用 + 注意" |
parameters | 参数 Schema | 手写 JSON Schema；每个参数带 description，否则模型不知道传什么 |
output | 返回说明 | render 定模型看到的文本；presentationMeta 定浏览器渲染的数据 |
6.4 execute 里做了什么（核心逻辑）
async execute(args) {
const city = typeof args.city === 'string' ? args.city.trim() : ''
if (city === '') throw new Error('weather: city 是必填参数')
// ① 地理编码：城市名 → 经纬度
const geo = await fetchImpl_(`${config.geocodingUrl}/search?name=${encodeURIComponent(city)}&count=1&language=zh`)
const geoData = await geo.json()
const hit = geoData.results?.[0]
if (!hit) throw new Error(`weather: 找不到城市「${city}」，请换英文名试试`)
// ② 实时天气：经纬度 → 天气数据
const unit = args.unit === 'fahrenheit' ? 'fahrenheit' : 'celsius'
const forecast = await fetchImpl_(`${config.baseUrl}?latitude=${hit.latitude}&longitude=${hit.longitude}¤t_weather=true&daily=temperature_2m_max,temperature_2m_min&timezone=auto&forecast_days=1`)
const data = await forecast.json()
// ③ 用共享契约把原始数据规整成 WeatherInfo
const info = parseWeather(hit.name, data, unit)
// ④ 返回：text 给模型看（短），weather 结构化数据进 meta 给浏览器
return { text: summarize(info), weather: info }
}
6.5 output 与 presentationMeta 分离（核心套路）
这是 dsh 插件最重要的设计套路：
output: {
schema: {
type: 'object', additionalProperties: false,
properties: {
text: { type: 'string', required: true }, // 给模型的一句话
weather: { type: 'object', additionalProperties: true, required: true }, // 结构化数据
},
},
render: (_args, value) => [{ type: 'text', text: value.text }],
presentationMeta: (_args, value) => ({ kind: 'weather', ...value.weather }),
}
text（模型看到的）：要短。模型还要把它写进自己的回复，太长挤占上下文。例：北京当前晴天，29°C，20~29°C，6km/h 东风。presentationMeta（浏览器用的）：可序列化的结构化数据（城市、天气类型、温度、风力、温度范围……），dsh 把它写进持久化 meta，不占模型上下文；浏览器端从 block.meta 读回渲染卡片，回放也一致。
结果：用户看到的是"模型一句话播报 + 浏览器一张精美动效卡片"，而模型上下文里只有一句话，省 token、渲染富、两端职责分离。
6.6 错误处理
两种失败要区别对待：
// 参数错误 → 直接 throw（让模型知道这次调用无效，自行修正）
if (city === '') throw new Error('weather: city 是必填参数')
// 业务失败（找不到城市、外部服务报错）→ 抛出带信息的错误，让模型读得懂并调整策略
if (!hit) throw new Error(`weather: 找不到城市「${city}」，请换英文名试试`)
原则：参数/调用错误抛异常，业务失败返回结构化结果。别把"外部服务挂了"当成"工具坏了"抛给模型。
第 7 章 共享契约 fragment：双端一致的秘密
7.1 问题：同一份数据，两端各算一套？
Node 端把天气数据写进 meta，浏览器端要读它渲染。如果两端各写各的解析逻辑，很容易不一致：Node 端说 WMO 天气码 0 是"晴"，浏览器端以为是"阴"，卡片就画错了。
解法：把"数据怎么算/怎么解析"抽成纯函数契约模块 src/fragment.ts，Node 端、浏览器端、测试三方 import 同一个函数。
7.2 fragment.ts 里有什么
// 双端共用的纯函数：不 import 任何 @deepseek-ai 包，Node/浏览器都能打包
/** WMO 天气码 → 动效类型 + 中文描述 */
export function weatherTypeFromCode(code: number): { type: WeatherType; zh: string } {
if (code === 0) return { type: 'sunny', zh: '晴' }
if (code >= 1 && code <= 3) return { type: 'partly', zh: '多云' }
if (code >= 45 && code <= 48) return { type: 'fog', zh: '雾' }
if (code >= 51 && code <= 67) return { type: 'rain', zh: '降雨' }
if (code >= 71 && code <= 77) return { type: 'snow', zh: '降雪' }
if (code >= 95) return { type: 'storm', zh: '雷暴' }
return { type: 'cloudy', zh: '阴' }
}
/** 把 Open-Meteo 原始数据规整成渲染/展示用的 WeatherInfo */
export function parseWeather(city: string, data: unknown, unit: string): WeatherInfo { /* ... */ }
/** 给模型看的一句话摘要 */
export function summarize(info: WeatherInfo): string {
return `${info.city}当前${info.zh}，${info.temp}°${unitChar}，${info.low}~${info.high}°${unitChar}，${info.windSpeed}km/h ${info.windDir}。`
}
/** 从持久化 tool/result meta 还原结构化数据（Node 写入、浏览器读回） */
export function weatherMetaFrom(meta: unknown): WeatherInfo | undefined { /* ... */ }
7.3 为什么这设计很值
- 一致性：同一份映射、同一份解析，双端必然一致；
- 可测试：纯函数不碰网络、不碰 DOM，是最便宜、最该多写的测试层；
- 省 token：规则说明（如天气码映射）还能被模型直接引用，省得重复写。
经验：把"所有会算数据的逻辑"都往 fragment 里放，是 dsh 插件的最佳实践。
第 8 章 写技能：教模型「怎么播报天气」（SkillProvider）
8.1 技能是什么
技能 = 给 AI 的"写作规范手册"。 工具给 AI"手"（动作），技能给 AI"说明书"（怎么做、按什么规范产出）。
我们的天气技能 weather-briefing 就干一件事：教模型拿到天气数据后，按什么结构、什么语气播报。
8.2 真实 API：SkillProvider（list + get）
当前版本的技能是 SkillProvider { name, list(), get() } 两级加载（旧资料里的 fetchCandidates/load 已经变了）：
import {
BUNDLED_SKILL_RANK,
type SkillCandidate, type SkillDefinition, type SkillProvider,
} from '@deepseek-ai/dsh-skill'
const PROVIDER_NAME = 'weather-plugin'
const INVOCATION = { modelInvocable: true, userInvocable: true } as const
const CANDIDATES: SkillCandidate[] = [{
name: 'weather-briefing',
description: '向用户播报天气时使用：固定结构、语气自然、附一条实用建议。'
+ '在调用 weather 工具拿到实时数据后，按此规范组织播报。',
invocation: INVOCATION,
provider: PROVIDER_NAME,
source: 'bundled',
rank: BUNDLED_SKILL_RANK,
locator: 'weather-briefing',
}]
const BODY = `# 天气播报规范
1. 先报城市与天气类型（如：北京当前晴天）。
2. 再报温度与体感，单位与用户要求一致（摄氏度/华氏度）。
3. 补充风力（风速+风向）。
4. 有高低温时附上今日范围。
5. 结合天气给一句实用建议（雨天带伞、降温加衣、雪天慢行），不超过 10 字。
6. 只依据 weather 工具返回的实时数据，不编造预报。`
export const weatherSkillProvider: SkillProvider = {
name: PROVIDER_NAME,
list: () => Promise.resolve(CANDIDATES), // 候选清单：轻量，常驻
async get(candidate): Promise<SkillDefinition> {
return {
name: candidate.name,
description: candidate.description,
invocation: candidate.invocation,
provider: PROVIDER_NAME,
source: 'bundled',
rank: candidate.rank,
content: BODY, // 完整规范：重，触发才加载
}
},
}
8.3 两级加载的设计用意
| 层 | 内容 | 何时进上下文 |
|---|
list() 候选 | name + description（轻） | 常驻，模型据此判断是否触发 |
get() 正文 | 完整 content（重） | 仅当模型决定使用该技能时 |
为什么要这样？ 模型上下文是稀缺资源。如果把所有技能的完整规范都常驻，上下文立刻爆炸。所以：候选精炼常驻、正文按需加载。
8.4 技能正文就是"创作契约"
写技能正文 = 写清楚产出物的结构、必含要素、格式、语气、边界。要点：
- 结构契约：固定顺序（先城市 → 温度 → 风力 → 范围 → 建议）；
- 必含要素：列出缺一不可的（单位一致、高低温范围）；
- 格式契约：字数、语言；
- 边界：明确"不做什么"——我们写了"只依据工具实时数据，不编造预报"，这是防止模型幻觉的关键。
在 apply 里注册：ctx.effect(() => ctx.skills.registerProvider(() => weatherSkillProvider), 'weather-plugin.skill')
第 9 章 系统提示：引导模型「何时用工具」
9.1 为什么需要系统提示
工具 description 通常写得较长，模型在长对话里不一定记得用它。系统提示是常驻的，加一小段就能持续引导："遇到天气问题 → 调用 weather 工具 → 按技能播报"。
9.2 真实 API：ctx.systemPrompt.section
注意签名是传一个对象 { name, order, text }（不是三个参数）：
const PROMPT_TEXT = `## Query weather (weather)
Use the \`weather\` tool when the user asks about the weather, temperature,
rain/snow, or wind for any city (for example "北京天气怎么样" or
"will it rain in London tomorrow morning?"). Pass the city name in \`city\`.
The tool returns real-time conditions as an animated weather card; report it
following the weather-briefing skill. Only pass \`unit\` when the user asks
for Fahrenheit.`
ctx.effect(() => ctx.systemPrompt.section({
name: 'tool:weather', // 段落唯一 id
order: 117, // 排序：小的靠前
text: PROMPT_TEXT, // 段落正文
}), 'weather-plugin.prompt')
9.3 order 的作用
系统提示由多个插件各自追加，顺序有讲究：通用规则在前、具体约定在后。order 小的靠前，约定类段落给较大 order 放后面（我们用 117），避免干扰模型对通用指令的理解。
9.4 写好工具/系统提示的"三件套"
模型只通过文字理解工具。 写 description 的黄金模板：
- 做什么：
查询指定城市的实时天气。
- 何时用：
当用户询问天气、温度、雨雪、风力时使用。
- 何时不用/注意：
仅当用户要求华氏度时才传 unit 参数。
实战验证：weather 的系统提示 + description 按"三件套"写，浏览器实测模型一次就准确调用了 weather 工具。
9.5 系统提示 vs 技能：怎么分
| 维度 | 系统提示 | 技能 |
|---|
| 加载 | 常驻（始终在上下文） | 按需触发加载 |
| 体量 | 宜短 | 可长 |
| 用途 | 引导"何时用工具/遵守约定" | 提供"怎么写/怎么组织"的完整规范 |
原则：全局的、简短的 → 系统提示；局部的、详细的 → 技能。别把长规范塞进系统提示。
第 10 章 浏览器端：把数据画成动效卡片
10.1 浏览器端在架构里的位置
Node 端负责"干活"（调 API、算数据），浏览器端负责"画画"（渲染界面）。两端通过持久化 meta 衔接：
工具 presentationMeta ──► block.meta（持久化）──► 浏览器端 Toolview ──► 用户看到的动效卡片
浏览器端代码最终被打包成 lib/client.js，由 dsh 以 /plugins/weather-plugin/client.js 提供，在沙箱 iframe 里运行。
10.2 注册方式：slots 注入 keyed Toolview
真实 API 是 ctx.slots.inject('tool.call.toolview', ...) + ctx.slots.register({name, key}, Component)（旧资料的 registerView 已经变了）：
import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
import type { ToolCallViewProps } from '@deepseek-ai/dsh-client-ui-tool/client'
import { weatherMetaFrom } from '../fragment'
export const name = 'weather-plugin'
export const inject = ['slots']
function WeatherCardView({ callId, block }: ToolCallViewProps) {
// ① 运行中：block 还没有 kind，显示 loading
if (!('kind' in block)) {
return <div className="wea-load">加载天气中…</div>
}
// ② 失败
if (block.isError) {
return <div>天气查询失败</div>
}
// ③ 成功：从持久化 meta 还原数据，渲染动效卡片
const info = weatherMetaFrom(block.meta)
if (info === undefined) return <div>无天气数据</div>
return <WeatherCard info={info} />
}
export function apply(ctx: ClientContext): void {
ctx.slots.inject('tool.call.toolview', () => ctx.slots.register(
{ name: 'tool.call.toolview', key: 'weather' }, // key = 工具名
WeatherCardView,
))
}
10.3 三种状态判断（重要）
组件拿到的 block 有三种形态：
| 形态 | 判断方式 | 渲染什么 |
|---|
| 运行中（pending） | !('kind' in block) | loading 动画 |
| 失败 | block.isError | 错误文本 |
| 成功 | 有 kind，从 block.meta 还原 | 结果卡片 |
别漏掉：运行中的 block 没有 kind 字段，直接读 block.meta 会拿不到数据。
10.4 动效卡片：纯 CSS，零外部依赖
天气卡片用纯 CSS keyframes 实现 6 种天气动画，不引任何 CDN（沙箱 CSP 也禁止外部脚本）：
| 天气 | 动效 |
|---|
| ☀️ 晴 | 太阳核心 + 旋转的虚线光芒 |
| ⛅ 多云 | 漂浮移动的云朵 |
| 🌫 雾 | 平移的雾带 |
| 🌧 降雨 | 周期性下落、淡出的雨线 |
| ❄️ 降雪 | 飘落 + 旋转的雪花 |
| ⛈ 雷暴 | 闪烁的闪电 |
卡片还显示：城市、温度、体感、风向风速、今日温度范围、"白天/夜间"、更新时间。
硬约束：浏览器产物必须单文件、无动态 import、无多 chunk，不能 import Node 内置模块。这些由构建自检把关（见第 11 章）。
第 4 部分 · 构建与测试
第 11 章 双端构建：tsdown + junction + ModuleLoader
11.1 构建的目标
一次构建产出两个文件：
lib/index.js —— Node 端（工具/技能/系统提示），ESM + 类型声明；lib/client.js —— 浏览器端（Toolview），CJS 单文件，带 ModuleLoader 包装。
11.2 junction：宿主依赖从哪来
插件要 import @deepseek-ai/* 宿主包，但不打包它们（运行时由 dsh 提供）。这些包在 dsh 发布包的 node_modules 里就有。
用 junction（Windows 目录联接） 把它们链进插件的 node_modules，保证和运行的 dsh 完全同版本：
# scripts/link_deps.py（节选）
NODE_DEPS = ["cordis", "cosmokit", "schemastery",
"dsh-tools", "dsh-skill", "dsh-system-prompt", ...]
CLIENT_DEPS = ["dsh-client-runtime", "dsh-client-ui-tool", "dsh-client-ui-slots", ...]
# 用 cmd 的 mklink /J 建目录联接（不需要管理员权限）
subprocess.run(["cmd", "/c", "mklink", "/J", dst, src], check=True)
为什么不用 npm install 装一份？ 会装到 registry 上的另一个版本，和运行的 dsh 不一致，类型和运行时都可能错位。junction 直连 dsh 自带的包最稳。
高频坑：npm install 会把 node_modules 里的链接清掉重装，所以 link_deps.py 必须放在 npm install 之后跑（build.ps1 已按此编排）。
11.3 tsdown 双端配置
// tsdown.config.ts（要点）
export default [
{
entry: { index: 'src/index.ts' },
outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
dts: true, clean: true,
deps: { neverBundle: ['@deepseek-ai/schemastery', '@deepseek-ai/cordis'] },
},
{
entry: { client: 'src/client/index.tsx' },
outDir: 'lib', format: 'cjs', platform: 'browser',
outputOptions: {
entryFileNames: 'client.js',
inlineDynamicImports: true, // 强制单文件
banner: `window.__ModuleLoader__.load({ id: "weather-plugin", factory: (require) => {`,
footer: `return module.exports; } });`,
intro: 'var module = { exports: {} }; var exports = module.exports;',
},
},
]
关键点：
- neverBundle：schemastery 和 cordis 不打包，因为 dsh 的 Loader 要校验你的
Config schema，必须看到它自己的实例；
- 浏览器端 format: 'cjs' + inlineDynamicImports：产出一个 CJS 文件；
- banner/footer：把产物包进
window.__ModuleLoader__.load({ id, factory })，这是 dsh 网页端加载插件浏览器端的方式。
从旧 API 迁移最易漏的一环：忘写 ModuleLoader 包装，前端会报 __ModuleLoader__ is not a function。
11.4 产物自检（三大硬约束）
构建后自检 lib/client.js：
- require 白名单：只允许 import
react、@deepseek-ai/dsh-client-* 等平台模块；
- 无动态 import：不允许
import(；
- 无多 chunk：必须是单文件。
任一不满足即报错，保证浏览器产物能在 CSP 沙箱安全加载。
11.5 build.ps1 全流程
# ① 装构建工具
npm install --legacy-peer-deps
# ② 链宿主依赖（junction，必须在 install 之后）
python scripts/link_deps.py
# ③ 双端打包
npx tsdown
# ④ 自检
# 检查 lib/index.js 与 lib/client.js 是否生成
第 12 章 安装进 profile 与 headless 冒烟测试
12.1 安装：三行命令
dsh 用 profile（配置档案）管理插件。我们装进两个 profile：web（网页端）和 headless（命令行端）。
dsh plugin --profile web add file:D:/dsh-openmaic-main/weather-plugin
dsh plugin --profile headless add file:D:/dsh-openmaic-main/weather-plugin
这条命令会自动把插件（含 cordis.patch.yml 的 insert）写进 profile 的 package.json → dsh.profile.bundles，dsh 启动该 profile 时按 layer 顺序加载。
12.2 headless 冒烟（最快验证全链路）
不需要浏览器，命令行直接问：
dsh --profile headless "北京今天天气怎么样"
我们真实得到的输出：
北京今天晴天 ☀️
气温：当前 29°C，体感较热，全天在 20~29°C 之间
风力：东风，风速约 6 km/h，风很小
白天太阳很足、午后偏热，出门记得防晒补水；早晚 20°C 左右稍凉，可以带件薄外套。
再测一个城市：
dsh --profile headless "上海今天天气怎么样"
# → 上海当前阴天 ☁️ 29°C 东风 11km/h
这证明了什么：
- 模型识别了"查天气"的意图 → 调用了 weather 工具；
- 工具真的调了 Open-Meteo 拿到实时数据；
- 模型加载了
weather-briefing 技能，按规范播报（结构、语气、实用建议都对）。
12.3 数据真实性校验
为了确认不是模型编的，我们写了一个独立脚本直接调 Open-Meteo，与插件返回逐项比对一致：
Open-Meteo 北京实时：晴天 29°C 6km/h 东风 20~29°C
weather 工具返回： 北京当前晴天 29°C 20~29°C 6km/h 东风
数据一致 → 全链路真实可靠。
说明：weather 工具调用的是 Open-Meteo 免费 API，无需任何 API key。如果你开发的插件需要调用付费服务，key 应放在 ~/.dsh/.credentials.yaml 或 profile 配置里，绝不写进代码。
第 13 章 web 界面验收：在浏览器里看到天气卡片
13.1 为什么这步是"最终验收"
用户真正看到的是网页界面。命令行跑通只能证明"逻辑对"，界面验收才能证明"用户看得见、用得上"。
13.2 启动 web 并实测
dsh --profile web
# 浏览器打开 http://127.0.0.1:3080
我们真实实测的过程：
- 浏览器打开
http://127.0.0.1:3080，标题显示 DeepSeek Harness，模型已配置为 DeepSeek-V4-Flash；
- 输入框输入"北京今天天气怎么样"，点击发送；
- 会话标题自动变成 "北京今日天气查询"；
- 界面消息流里依次出现：
- 模型按技能规范完整播报 + 实用建议；
- 统计信息：1 轮 · 2 步 | LLM 4.5s · 工具调用 3.6s | 首 token 平均 1.1s · 156 tok/s | 缓存命中 50% | 输入 31.4K tok · 输出 358 tok。
13.3 这次验收证明了什么
- 天气工具被真实调用并返回数据；
weather-briefing 技能被加载并指导播报；- 浏览器端动效卡片成功渲染（前端读取持久化 meta → 画出生动的天气卡）；
- 前端卡片数据与 headless 完全一致 → 回放一致性的体现。
13.4 如果卡片没显示怎么办
排查顺序：
http://127.0.0.1:3080/plugins/weather-plugin/client.js 是否返回 200（浏览器端产物是否被 serve）；block.meta 是否有数据（Node 端 presentationMeta 是否正确投影）；ctx.slots.register 的 key 是否与工具名 weather 一致；- client.js 是否单文件、无动态 import（构建自检）。
第 5 部分 · 交付与进阶
第 14 章 发布与维护：改代码后的正确姿势
14.1 一个容易忽略的坑：file: 依赖是复制
用 file: 方式安装插件，dsh 是把它复制进 profile 的 node_modules，而不是软链。所以：
- 第一次安装后，你再改插件代码、重新构建，profile 里还是旧产物；
- 必须手动把新产物同步过去。
正确姿势（改代码后三步）：
# ① 重新构建
powershell -ExecutionPolicy Bypass -File scripts/build.ps1
# ② 同步产物到已安装的 profile
python scripts/sync_profile.py
# ③ 重启 dsh 生效
sync_profile.py 会把 lib/、cordis.patch.yml、package.json 拷到 profile 里的插件目录。
14.2 本次开发真实踩过的坑（高频）
| # | 坑 | 现象 | 解法 |
|---|
| 1 | Node 版本太旧 | dsh 启动报 Promise.withResolvers 等 | 升级 Node 22+，或用 node22 的 node.exe 跑 |
| 2 | junction 被 npm install 清掉 | 构建找不到 @deepseek-ai/* | link_deps 放 npm install 之后 |
| 3 | 改了代码没生效 | 行为还是旧的 | file: 是复制，跑 sync_profile.py |
| 4 | 浏览器端没渲染 | 前端报 __ModuleLoader__ 错误 | client.js 缺 ModuleLoader 包装 |
| 5 | 中文城市查不到 | "纽约" geocode 无结果 | API 语言问题，换英文名或北京/上海 |
| 6 | tsdown 版本 | Node 20 下 tsdown 0.22 报 Promise.withResolvers | 用 tsdown@^0.19.0 |
| 7 | PowerShell 中文乱码 | build.ps1 输出乱码 | 脚本输出用纯英文 |
| 8 | npm peer 冲突 | npm install 报 peerDependencies | 加 --legacy-peer-deps |
14.3 发布清单
对外发布前逐项确认：
第 15 章 进阶：四种插件类型，选型与实现
15.1 四类插件总览
| 类型 | 一句话 | 实现手段 | 典型场景 |
|---|
| Tool Plugin | 给模型加可执行动作 | defineTool + ctx.tools.register | 查天气、查库、调 API |
| Skill 插件 | 教模型按规范产出 | SkillProvider {list,get} | 统一写作风格、播报规范 |
| Service Provider | 换底层驱动 | 实现服务接口 + ctx.super('key') | 换模型网关、换文件沙箱 |
| Event Interceptor | 关键路径加料 | waterfall 事件 + next() 委托/短路 | 审批、审计、限流 |
| Agent Loop | 重写核心循环 | 实现 Agent 接口 + AgentFactory | Plan-and-Execute、多智能体 |
15.2 选型决策
用户想"加新能力" →
├─ 想让模型多一个"能干的动作"？ → Tool Plugin（首选）
├─ 想教模型"怎么写/怎么组织"？ → Skill 插件
├─ 想换掉底层驱动（模型/文件/沙箱）？ → Service Provider
├─ 想在关键路径插审批/审计/限流？ → Event Interceptor
└─ 想重写整个思考-行动循环？ → Agent Loop
选型口诀：Provider 是"换驱动"，Tool 是"装软件"，Interceptor 是"加关卡"，AgentLoop 是"换引擎"。
建议：多数需求用 Tool + Skill + 系统提示 + 浏览器端 组合即可解决。先做最小可用的 Tool，再补技能/系统提示/前端，不要一上来就动 Agent Loop。
第 16 章 沉淀：把经验变成可复用的 Skill
16.1 为什么值得沉淀
你刚走完一个完整插件的全部流程。下次开发一个类似插件（查股票、查物流、查数据库），80% 的步骤是重复的：环境、骨架、构建、安装、测试、避坑。
把这些沉淀成一个 Skill（给 AI 的"作业规范手册"），就能让 AI 照着做、少踩坑、速度快一倍。
16.2 一个 dsh 插件开发 Skill 应该装什么
| 资源 | 内容 |
|---|
SKILL.md | 7 步工作流（选型→环境→骨架→实现→构建→安装→测试） |
references/ | 深度文档：架构、四种类型、工具、技能、系统提示、浏览器端、构建测试、排错 |
assets/plugin-skeleton/ | 可直接复制的插件骨架模板 |
assets/examples/weather-plugin/ | 完整可运行的天气插件案例（就是本课做的这个） |
scripts/scaffold_plugin.py | 一键生成插件项目脚手架 |
16.3 你从这门课带走的核心资产
- 一套方法论：需求 → 选型 → 环境 → 骨架 → 实现 → 构建 → 安装 → 测试 → 验收；
- 一个真实 API 认知：
defineTool、SkillProvider {list,get}、systemPrompt.section、slots.inject——都是当前版本的真实用法，网上很多旧资料是错的；
- 一个可运行的案例：天气插件（查天气 + 动效卡片），可作为任何新插件的起点；
- 一堆避坑经验：Node 22、junction 顺序、file: 同步、ModuleLoader、中文城市 geocode……都在附录 C 有对照表。
附录
附录 A · 完整代码清单（weather-plugin）
天气插件的完整源码位于 D:\dsh-openmaic-main\weather-plugin\。核心文件速览：
| 文件 | 职责 | 关键代码 |
|---|
src/index.ts | 入口 + 配置 | export const name / inject / Config（schemastery z.object）/ apply 里三个 ctx.effect 注册 |
src/tool.ts | weather 工具 | defineTool：name / description / parameters / output（render+presentationMeta）/ execute / presentCall / presentResult |
src/skill.ts | weather-briefing 技能 | SkillProvider { name, list(), get() }，正文 BODY 是播报规范 |
src/fragment.ts | 共享契约 | weatherTypeFromCode（WMO 码→动效/中文）、parseWeather、summarize、weatherMetaFrom |
src/client/index.tsx | 浏览器端 | ctx.slots.inject('tool.call.toolview') + keyed WeatherCardView + 6 种纯 CSS 天气动画 |
tsdown.config.ts | 双端打包 | Node ESM + 浏览器 CJS 单文件 + ModuleLoader banner/footer |
cordis.patch.yml | 挂载声明 | - insert: { id: weather-plugin, name: '@demo/weather-plugin' } |
scripts/build.ps1 | 一键构建 | install → link_deps → tsdown → 自检 |
scripts/link_deps.py | junction 链依赖 | mklink /J 链 @deepseek-ai/* |
scripts/sync_profile.py | 同步产物 | 拷 lib/ + patch + package.json 到 profile |
这份源码也完整保存在 dsh-plugin-developer Skill 的 assets/examples/weather-plugin/，可随时对照。
附录 B · 常用命令速查
| 目的 | 命令 |
|---|
| 检查 Node 版本（必须 ≥22） | node -v |
| 生成插件骨架 | python scripts/scaffold_plugin.py <目录> --name @scope/name |
| 一键构建 | powershell -ExecutionPolicy Bypass -File scripts/build.ps1 |
| 链宿主依赖 | python scripts/link_deps.py |
| 双端打包 | npx tsdown |
| 安装进 profile | dsh plugin --profile web add file:<绝对路径> |
| headless 冒烟 | dsh --profile headless "北京天气怎么样" |
| 启动 web | dsh --profile web（浏览器开 http://127.0.0.1:3080） |
| 同步产物到 profile | python scripts/sync_profile.py |
| 检查浏览器端产物是否被 serve | 浏览器访问 http://127.0.0.1:3080/plugins/weather-plugin/client.js |
附录 C · 常见报错对照表
| 报错/现象 | 原因 | 解法 |
|---|
Promise.withResolvers is not a function | Node 太旧（需 22+） | 升级 Node 22+，或用 node22 的 node.exe 跑 dsh |
zlib.createZstdDecompress is not a function | Node < 22 | 同上 |
module.stripTypeScriptTypes is not a function | Node < 22 | 同上 |
构建找不到 @deepseek-ai/* | junction 被 npm install 清掉 | link_deps 放 npm install 之后重跑 |
mklink /J 需要管理员权限 | 用了符号链接 | 用 junction（mklink /J），不需要管理员 |
tsdown 报 Promise.withResolvers | tsdown 0.22+ 也要 Node 22 | Node 20 用 tsdown@^0.19.0 |
| npm peerDependencies 冲突 | dsh 各包 peer 相互引用 | npm install --legacy-peer-deps |
前端报 __ModuleLoader__ is not a function | client.js 缺 banner/footer | 配 tsdown outputOptions banner/footer |
| 改了代码行为没变 | file: 依赖是复制 | 重建后 python scripts/sync_profile.py |
| 工具返回了但前端没渲染 | meta 缺失 / key 不一致 | 查 presentationMeta、slots.register 的 key |
| "纽约"查不到天气 | geocode API 中文问题 | 换英文名或北京/上海 |
| PowerShell 中文乱码 | PS 5.1 编码 | 脚本输出用纯英文 |
附录 D · 术语表
| 术语 | 含义 |
|---|
| dsh | DeepSeek Harness，万物皆插件的智能体框架 |
| Cordis | 插件容器框架，所有插件挂载于此 |
| 插件（Plugin） | 一个 npm 包，导出 apply(ctx, config)，给 dsh 加能力 |
| Profile | dsh 的配置档案，管理一组插件（如 web、headless） |
| 工具（Tool） | 给模型的可执行动作，defineTool + execute |
| 技能（Skill） | 给模型的写作规范，SkillProvider {list,get} 两级加载 |
| 系统提示（System Prompt） | 常驻指导文字，ctx.systemPrompt.section |
| Toolview | 浏览器端把工具结果渲染成界面的组件 |
| meta | Node 端写、浏览器端读的持久化结构化数据 |
| presentationMeta | 工具把结构化数据投影进持久化 meta 的钩子 |
| junction | Windows 目录联接，用于链宿主依赖 |
| tsdown | TS 打包器，本课用于双端打包 |
| ModuleLoader | dsh 网页端加载浏览器端产物的机制（window.__ModuleLoader__.load） |
| Bundle | profile 的插件清单（dsh.profile.bundles） |
| Open-Meteo | 免费天气 API（地理编码 + 实时预报，无需 key） |
结语
恭喜你走完了从 0 到 1 开发 dsh 插件的完整旅程。你现在掌握了：
- 认知：dsh 的"万物皆插件"哲学，插件双端架构；
- 实战：工具、技能、系统提示、浏览器端动效四块核心能力的真实 API 写法；
- 工程：Node 22 环境、junction 链依赖、tsdown 双端构建、ModuleLoader 包装；
- 交付：profile 安装、headless 冒烟、web 界面验收、发布维护；
- 沉淀：把经验变成可复用 Skill。
下一步建议：用脚手架生成一个新骨架，把天气插件换成你的真实需求（查股票、查物流、查数据库……），照本课流程再走一遍。第二次会比第一次快一倍。
祝你做出好插件！
