DeepSeek Harness 开发实战教程

概览与核心思想

DeepSeek Harness 是一个基于 Cordis 插件框架的 AI Agent 开发平台。它的核心思想是：一切皆插件，能力可组合。

什么是 Cordis？

Cordis 是一个轻量级的插件框架。在 Harness 中，每一个功能——工具注册、LLM 调用、事件监听——都是一个插件。插件之间通过 服务（Service）共享能力，通过 事件（Event）松耦合通信。

四个核心概念

本教程的实战样本

后半部分的三章到十二章全部围绕三个已发布、可安装、有真实用户的插件展开，它们覆盖了 DSH 插件开发的三种主要形态：

第一个插件

插件就是一个导出 apply 函数的 TypeScript 模块。框架加载时调用它，传入上下文对象 ctx。

最小插件

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

三种插件形态

函数形式最常用，但 Cordis 还支持对象形式和类形式：

① 函数形式（推荐）

export function apply(ctx: Context) { /* ... */ }

② 对象形式

export const objectPlugin = {
  name: 'object-plugin',
  apply(ctx: Context) { /* ... */ }
}

③ 类形式（用于提供服务）

export class MyService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'myService')
  }
}

组合应用：cordis.yml

插件写好后，通过 cordis.yml 组合成应用：

# cordis.yml — 这就是你的应用
- name: './hello.ts'

列表中的各项并发启动，顺序由服务依赖（inject）决定，而非文件位置。

生命周期与 Effect

插件可能因配置修改、热重载、资源释放或依赖消失而卸载。Cordis 通过 Effect 机制确保资源被正确清理。

Fiber 状态机

每个已加载的插件实例都有一个 Fiber（运行时句柄），在以下状态间转换：

Effect：管理自定义资源

对于 Cordis 不管理的资源（定时器、连接、watcher），用 ctx.effect() 包装，返回一个 disposer：

export function apply(ctx: Context) {
  ctx.effect(() => {
    // 加载时：创建资源
    const timer = setInterval(() => console.log('tick'), 200)

    // 卸载时：返回清理函数
    return () => {
      clearInterval(timer)
      console.log('cleaned up')
    }
  })
}

ctx.effect(() => () => cache.dispose(), 'github-trending: cache disposal')
ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-sprite: dictionaries')

已经是 Effect 的操作

大多数内置 API 本身就是 effect，不需要手动清理：

手动卸载子插件

// 挂载子插件，获得 fiber 句柄
const fiber = ctx.plugin(childPlugin)

// 稍后手动卸载（等待所有异步清理完成）
await fiber.dispose()

服务与依赖注入

服务是插件向其他插件公开的命名能力。Harness 中的 ctx.tools、ctx.llm、ctx.agents 都是服务。

提供服务

继承 Service 基类，在构造函数中用 super(ctx, '服务名') 注册：

import { Service, type Context } from '@deepseek-ai/cordis'

// 编译时：TypeScript 声明合并，让 ctx.greeter 有类型
declare module '@deepseek-ai/cordis' {
  interface Context {
    greeter: GreeterService
  }
}

export class GreeterService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'greeter')  // 运行时：以 'greeter' 名称注册
  }

  greet(who: string) {
    return `Hello, ${who}!`
  }
}

export const name = 'greeter'
export function apply(ctx: Context) {
  ctx.plugin(GreeterService)  // Service 子类本身就是插件
}

消费服务：inject

用 inject 声明依赖，框架保证服务就绪后才加载你的插件：

export const name = 'consumer'
export const inject = ['greeter']  // 声明依赖

export function apply(ctx: Context) {
  // 这里 ctx.greeter 一定已经就绪
  console.log(ctx.greeter.greet('world'))
}

依赖的动态行为

inject 不是一次性检查。运行期间如果服务消失：

1. 依赖它的插件会自动卸载
2. 服务恢复后，插件自动重新加载

这就是为什么可以在运行时替换服务提供方——所有依赖方会自动重启并使用新实现。

可选依赖的两种写法

写法 A：探测式（ctx.get）

如果服务缺失时插件仍可运行，跳过 inject，用 ctx.get() 探测：

export function apply(ctx: Context) {
  const greeter = ctx.get('greeter')  // 无提供方时为 undefined
  console.log(greeter?.greet('maybe') ?? 'no greeter available')
}

写法 B：回调式（ctx.inject）—— spritely 用的就是这种

把"需要服务才能做的那部分"隔离到一个回调里。服务缺失时插件照常加载，只是那段注册不发生；服务后来出现时，回调会被重新执行。这是最优雅的降级方式。

/** 注册持久化设置命名空间；没有 settings 服务时插件仍然可用（回退 localStorage）。 */
export function apply(ctx: Context): void {
  ctx.inject(['settings'], (settingsCtx) => {
    settingsCtx.settings.register(
      settingsNamespace(SPRITELY_SETTINGS_NAMESPACE),
      SpritelySettingsSchema,
    )
  })
}

事件系统

事件让插件无需知道谁在监听，就能发出通知。Harness 用事件处理工具结果、模型请求、审批决定等交互。

基本用法

// 监听事件
ctx.on('event-name', (payload) => {
  // 处理事件
})

// 触发事件
ctx.emit('event-name', payload)

五种分发模式

waterfall：拦截与转换

waterfall 是最强大的模式。每个监听器收到参数和 next()，可以：

• 调用 next() 获取下游结果，然后转换它
• 不调用 next() 直接返回，短路整条链

// 监听器 1：包装下游结果
ctx.on('demo/transform', async (input, next) => {
  const downstream = await next()
  return downstream.toUpperCase()
})

// 监听器 2：条件短路
ctx.on('demo/transform', async (input, next) => {
  if (input.includes('blocked')) return '** blocked **'
  return next()
})

// 触发
await ctx.waterfall('demo/transform', 'hello', async () => 'hello')
// → "HELLO"

await ctx.waterfall('demo/transform', 'blocked words', async () => 'blocked words')
// → "** BLOCKED **"

类型安全的事件

用 TypeScript 声明合并为事件提供类型：

declare module '@deepseek-ai/cordis' {
  interface Events {
    'stats/report'(name: string, count: number): void
    'demo/transform'(input: string, next: () => Promise<string>): Promise<string>
  }
}

配置与 Schema

插件可以接受来自 cordis.yml 的配置。通过导出 Schemastery schema，框架在加载前验证配置，错误配置会导致明确的加载失败。

定义可配置插件

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

export const name = 'config-demo'

// TypeScript 接口
export interface Config {
  greeting: string
  targets: string[]
}

// 同名的运行时 schema（默认值写在这里）
export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  targets: Schema.array(String).default(['world']),
})

export function apply(ctx: Context, config: Config) {
  for (const target of config.targets) {
    console.log(`${config.greeting}, ${target}!`)
  }
}

在 cordis.yml 中配置

- name: './config-demo.ts'
  config:
    targets: ['alpha', 'beta']
    # greeting 未提供，使用 schema 默认值 'Hello'

严格校验示例

export const Config = Schema.object({
  apiKey: Schema.string().required(),
  timeout: Schema.number().default(30000),
  mode: Schema.union(['fast', 'accurate']).default('fast'),
})

配置不合法时，插件进入 FAILED 状态并给出明确错误：

ValidationError: invalid config:
  - $.targets expected array but got not-an-array (at targets)

function assertPositiveInteger(name: string, value: number): void {
  if (!Number.isInteger(value) || value <= 0) {
    throw new Error(`github-trending: ${name} must be a positive integer`)
  }
}

// provider 与 model 必须成对配置：只给一个是不可能工作的
const hasProvider = resolved.overviewsProvider !== undefined && resolved.overviewsProvider !== ''
const hasModel = resolved.overviewsModel !== undefined && resolved.overviewsModel !== ''
if (hasProvider !== hasModel) {
  throw new Error('github-trending: overviewsProvider and overviewsModel must be configured together')
}

计算配置值：!!js

Loader 支持 !!js 标签，用于加载时计算配置值：

- name: './config-demo.ts'
  config:
    greeting: !!js process.env.DEMO_GREETING ?? 'Hello'

!!js 仅在 config 和 disabled 字段内有效。

组合与热重载

cordis.yml 不只是插件列表——它是应用的定义。本章讲解配置项元数据、热模块替换（HMR）和如何诊断"插件不加载"的问题。

配置项的完整字段

- id: greeter           # 稳定标识，用于 HMR 区分修改 vs 删除重建
  name: './greeter.ts'  # 模块路径或 npm 包名
  disabled: true         # 跳过挂载，但保留配置项
  config:                # 插件配置
    key: value

热模块替换 (HMR)

加载 @deepseek-ai/cordis-plugin-hmr 后，保存文件会自动：

# cordis.yml
- id: logger
  name: '@deepseek-ai/cordis-plugin-logger-console'
- id: timer
  name: '@deepseek-ai/cordis-plugin-timer'
- id: hmr
  name: '@deepseek-ai/cordis-plugin-hmr'
  config:
    root: ['.']
- id: hello
  name: './hello.ts'

诊断：为什么我的插件没输出？

如果插件的 inject 指定了无人提供的服务，它会一直 PENDING，不输出任何内容。用以下代码诊断：

import { FiberState, type Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  setTimeout(() => {
    for (const runtime of ctx.registry.values()) {
      for (const fiber of runtime.fibers) {
        if (fiber.state === FiberState.PENDING) {
          console.log(`${fiber.name} is PENDING — 缺少必需服务`)
        }
      }
    }
  }, 500)
}

开发一个 Tool

Tool 是模型可调用的工具。Harness 提供 defineTool DSL，让你声明参数、输出和执行逻辑，框架自动处理 JSON Schema 生成、参数校验和结果渲染。

完整示例

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',

    // 参数定义 → 自动生成 JSON Schema，自动校验模型输入
    parameters: {
      name: {
        type: 'string',
        required: true,
        description: 'The name to greet',
      },
    },

    // 输出：规范值 + 渲染器
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },

    // 执行逻辑
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

defineTool 各字段解析

上面只是最小可用集。第 16 章会用 GT 的完整工具定义展示生产级的全部字段，包括结果卡片、超时预算、并发安全声明。

通过流水线执行工具

import { CallId } from '@deepseek-ai/dsh-llm'

const result = await ctx.tools.execute({
  callId: CallId('demo-1'),
  name: 'greet',
  arguments: { name: 'Cordis' },
  signal: new AbortController().signal,
})
console.log('tool replied:', JSON.stringify(result.content))

观察工具调用：事件监听

import type {} from '@deepseek-ai/dsh-tools'  // 引入类型声明合并

export function apply(ctx: Context) {
  ctx.on('tools/result', (exec, result) => {
    const text = result.content
      .map(block => block.type === 'text' ? block.text : '')
      .join('')
    console.log(`[tool-logger] ${exec.name} -> ${text}`)
  })
}

能力的三层拆分

当一项能力足够通用、需要支持可替换的提供方时，Harness 将其拆分为三种角色：Service Definition、Service Provider 和 Consumer。

三种角色

以 Bash 能力为例

实战：构建三层能力

第一步：Service Definition

// my-cap/src/index.ts
import { Service, type Context } from '@deepseek-ai/cordis'

declare module '@deepseek-ai/cordis' {
  interface Context { myCap: MyCapService }
}

export abstract class MyCapService extends Service {
  constructor(ctx: Context) { super(ctx, 'myCap') }
  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}

export interface MyCapRequest { input: string }
export interface MyCapResult { output: string }

第二步：Service Provider

// my-cap-local/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'

class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest): Promise<MyCapResult> {
    return { output: request.input.toUpperCase() }
  }
}

export const name = 'my-cap-local'
export function apply(ctx: Context) {
  ctx.plugin(MyCapLocal)
}

第三步：Consumer（工具）

// tool-my-cap/src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'tool-my-cap'
export const inject = ['tools', 'myCap']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap',
    description: 'Execute my capability.',
    parameters: { input: { type: 'string', required: true } },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      const result = await ctx.myCap.execute({ input: args.input })
      return result.output
    },
  }))
}

组合

- name: '@deepseek-ai/dsh-my-cap-local'   # Provider
- name: '@deepseek-ai/dsh-tool-my-cap'     # Consumer

LLM 适配器开发

LLM 适配器将 Harness 的提供方无关请求转换为具体模型 API 的调用，并将响应转换回 Harness 的流式分片协议。

最小实现

import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
import {
  LlmAdapter, type GenerateOptions, type StreamChunk
} from '@deepseek-ai/dsh-llm'

class MyAdapter extends LlmAdapter {
  constructor(private apiKey: string) { super() }

  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
    // 1. 将 options.messages 转换为提供方格式
    // 2. 调用流式 API
    // 3. 将响应转换为 StreamChunk
  }
}

export interface Config {
  apiKey: string
  providers: string[]
}
export const Config: Schema<Config> = Schema.object({
  apiKey: Schema.string().required(),
  providers: Schema.array(Schema.string()).required(),
})

export const name = 'my-llm-adapter'
export const inject = ['llm']

export function apply(ctx: Context, config: Config) {
  const adapter = new MyAdapter(config.apiKey)
  ctx.llm.registerAdapter(config.providers, adapter)
}

StreamChunk 协议

stream() 必须按以下协议生成分片：

async function *exampleChunks(): AsyncIterable<StreamChunk> {
  // 文本块
  yield { type: 'block-start', index: 0, blockType: 'text' }
  yield { type: 'text-delta', index: 0, text: 'Hello' }
  yield { type: 'text-delta', index: 0, text: ' world' }
  yield {
    type: 'block-end', index: 0,
    block: { type: 'text', text: 'Hello world' },
  }

  // 工具调用块
  yield { type: 'block-start', index: 1, blockType: 'tool-call' }
  yield {
    type: 'tool-call-delta', index: 1,
    id: CallId('call-123'), name: 'bash',
    argumentsDelta: '{"command":"ls"}',
  }
  yield {
    type: 'block-end', index: 1,
    block: { type: 'tool-call', id: CallId('call-123'), name: 'bash', arguments: '{"command":"ls"}' },
  }

  // 使用量 + 结束
  yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
  yield { type: 'finish', reason: { kind: 'stop' } }
}

错误处理

适配器应通过带稳定 code 的 LlmError 抛出错误，agent loop 会保留该错误用于诊断和策略处理：

import { LlmAdapter, LlmError, attributionHeaders } from '@deepseek-ai/dsh-llm'

class HttpAdapter extends LlmAdapter {
  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
    const response = await fetch(this.endpoint, {
      method: 'POST',
      headers: { 'content-type': 'application/json', ...attributionHeaders() },
      body: JSON.stringify({ model: options.model, messages: options.messages }),
      ...options.signal ? { signal: options.signal } : {},
    })
    if (!response.ok) {
      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
    }
    // ... 解析响应并输出分片
  }
}

在 cordis.yml 中使用

- id: my-llm
  name: './src/my-llm-adapter.ts'
  config:
    apiKey: !!js process.env.MY_API_KEY
    providers:
      - my-provider

- id: agent-loop
  name: '@deepseek-ai/dsh-agent-loop'
  config:
    agents:
      - id: main
        provider: my-provider
        model: my-model-v1

打包与发布插件

将插件打包为可安装的组合包（bundle），用 dsh plugin add 安装进 profile。

两个核心概念

组合包结构

package.json

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

cordis.patch.yml

- insert:
  - id: hello
    name: dsh-hello-plugin   # 按包名引用，Node 模块解析能找到已安装代码

安装进 Profile

# 安装本地包
dsh plugin --profile demo add ./hello-plugin

# 从 GitHub 安装
dsh plugin --profile demo add github:you/hello-plugin

# 查看生效配置
dsh --profile demo --dump-config

# 启动
dsh --profile demo

配置层加载顺序

生效配置在空根之上按以下顺序逐层组合（后应用的层胜出）：

1. 组合包 patch（按 dsh.profile.bundles 列表顺序）
2. profile 自己的 cordis.patch.yml
3. home 级 cordis.patch.yml（各 profile 共享）
4. --patch overlay（按命令行参数顺序）

从 GitHub 安装的注意事项

Git 安装拉取的是源码，不是构建产物。需要两边各做一件事：

• 作者：提供 prepare 脚本，pnpm 在 git 安装后运行它来构建
• 用户：在 profile 的 pnpm-workspace.yaml 中授权构建：

  allowBuilds:
    dsh-hello-plugin: true

如果不想让用户做构建授权，可以：

• 发布到 npm：pnpm publish 时构建好，用户安装的是预构建代码
• 交付 tarball：pnpm pack 打包，用户 dsh plugin add ./hello-plugin-0.1.0.tgz

速查手册（基础）

基础 API 和模式的快速参考。含 Host 端 RPC、Client 端 Slot、Tool、LLM 调用等实战 API 的完整速查见第 23 章。

插件骨架

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

export const name = 'my-plugin'
export const inject = ['tools']  // 可选：声明依赖

export function apply(ctx: Context) {
  // 在这里注册能力
}

常用 API 一览

事件模式选择

常见问题排查

学习路径建议

全景：三种插件形态

动手写代码之前，先看清"插件"这个词在 DSH 里到底有几种可能。同一个 npm 包里可以同时存在 Host 半部分（Node 端）和 Client 半部分（浏览器端），两端的职责边界决定了你会用到哪些 API。

双端模型

一个 DSH bundle 插件有两半，各自有独立的入口、独立的依赖、独立的生命周期：

三个样本对照

加载链路（四个阶段）

选型决策树

工程脚手架与双端构建

DSH 共享的 clientBundle 预设没有对外发布，第三方插件必须在自己的 tsdown.config.ts 里复刻同样的产物格式。这是外部插件开发最大的一块隐形门槛，本章把它彻底讲透。

目录结构

package.json 解剖

三个项目都遵循同一套约定，以下以 AV 为例（已省略 repository / keywords 等无关字段）：

{
  "name": "@wangjunjian/dsh-artifact-viewer",
  "version": "0.4.0",
  "type": "module",
  "packageManager": "pnpm@10.33.2",

  // ── 双入口 ─────────────────────────────────
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "exports": {
    ".":       { "types": "./lib/types/index.d.ts",       "default": "./lib/index.js" },
    "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" },
    "./cordis.patch.yml": "./cordis.patch.yml",   // loader 需要读它
    "./package.json": "./package.json"
  },

  // ── DSH manifest ───────────────────────────
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": ["@deepseek-ai/dsh-client-runtime"],
      "external": ["@deepseek-ai/dsh-client-ui-primitives"]
    }
  },

  "files": ["lib/index.js", "lib/client.js", "lib/types/**/*.d.ts",
            "cordis.patch.yml", "README.md", "LICENSE"],

  // ── 依赖分层 ───────────────────────────────
  "peerDependencies": { // 宿主/web shell 提供，不随包安装
    "@deepseek-ai/cordis": "^4.0.1",
    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
    "react": "^18.2.0"
    // …其余 @deepseek-ai/* 全部列出
  },
  "dependencies": { // 真正要随包安装的（会被内联进 client bundle）
    "@deepseek-ai/schemastery": "^3.18.1"
  },

  "scripts": {
    "build": "tsc -b tsconfig.json && tsdown",
    "prepare": "tsc -b tsconfig.json && tsdown",   // git 安装 / publish 时自动构建
    "test": "vitest run",
    "typecheck": "tsc --noEmit",
    "lint": "biome check ."
  }
}

tsdown 双产物配置

一次构建要产出两类东西：

① Node 半部分：标准库构建

function clientLibraryConfig(id, libEntry) {
  return {
    name: id,
    entry: [...libEntry],          // ['lib/types/index.js', 'lib/types/invariant.js']
    outDir: 'lib',
    format: ['esm'],
    platform: 'node',
    target: 'es2024',
    dts: false,               // 类型由 tsc -b 单独产出到 lib/types
    clean: false,              // 两个 config 写同一个 outDir，不能互相清空
  }
}

② 浏览器部分：闭包工厂 + banner/footer 包裹

web shell 加载的是一个调用 __ModuleLoader__.load 的脚本文件，模块表通过 factory(require) 注入。这个包装完全靠 outputOptions 的 banner / footer / intro 拼出来：

outputOptions: {
  entryFileNames: 'client.js',
  // 关键：把整个 bundle 包成一个 factory 函数体
  banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(id)}, factory: (require) => {`,
  footer: 'return module.exports; } });',
  intro:  'var module = { exports: {} }; var exports = module.exports;',
  // 关键：必须内联动态 import。mermaid 这类库内部用动态 import，
  // 不内联会被拆成几十个 chunk，浏览器 module loader 根本加载不了。
  inlineDynamicImports: true,
}

③ 模块表 external

web shell 维护一张冻结的模块表，表内的包由宿主提供，你的 bundle 不能内联它们：

const MODULE_TABLE_EXTERNALS = new Set([
  'react', 'react/jsx-runtime', 'react-dom', 'react-dom/client',
  '@deepseek-ai/cordis',
  '@deepseek-ai/dsh-client-ui-slots',
  '@deepseek-ai/dsh-client-ui-primitives',
  '@deepseek-ai/dsh-client-runtime/client',
])

deps: {
  neverBundle: (s) => MODULE_TABLE_EXTERNALS.has(s),
  alwaysBundle: (s) => !MODULE_TABLE_EXTERNALS.has(s),
}

④ Purity gate：把"不该内联"变成构建期错误

光靠 external 不够——万一有人手滑 import { X } from '@deepseek-ai/dsh-xxx' 引了个不在表里的包，它会被静默内联，运行时出现微妙的 scope 不匹配。两个项目都在 tsdown 插件里加了硬闸门：

plugins: [{
  name: 'dsh-artifact-viewer-bundle-purity',
  resolveId(source) {
    if (!source.startsWith('@deepseek-ai/')) return null
    if (isModuleTableExternal(source)) return null
    throw new Error(
      `client bundle purity: "${source}" is not in the module table — `
      + 'declare it in dsh.client.external or collaborate through cordis services',
    )
  },
}]

⑤ CSS Modules：虚拟模块 + 自动注入 style 标签

tsc 只编译 TS，不拷贝样式表。所以 CSS Modules 必须在 tsdown 侧处理：拦截 *.module.css，用 lightningcss 编译，再生成一个虚拟模块把 CSS 注入成插件自有的 <style> 标签。

const CSS_VIRTUAL_PREFIX = '\0dsh-css:'
const CSS_VIRTUAL_SUFFIX = '.mjs'

plugins: [{
  name: 'dsh-artifact-viewer-css-modules',
  resolveId(source, importer) {
    if (!source.endsWith('.module.css') || importer === undefined) return null
    const resolved = new URL(source, `file://${importer}`).pathname
    // tsc 把 JS 吐在 lib/ 但没拷 CSS，所以要把 lib 路径映射回 src 再读
    const sourcePath = resolved.replace(/\/lib\//, '/src/')
    return CSS_VIRTUAL_PREFIX + sourcePath + CSS_VIRTUAL_SUFFIX
  },
  async load(virtualId) {
    if (!virtualId.startsWith(CSS_VIRTUAL_PREFIX)) return null
    const fileId = virtualId.slice(CSS_VIRTUAL_PREFIX.length, -CSS_VIRTUAL_SUFFIX.length)
    this.addWatchFile(fileId)          // watch 模式能热更
    const source = await readFile(fileId)
    const { code, exports: cssExports } = transform({
      filename: fileId, code: source,
      cssModules: { pattern: '[hash]_[local]' },   // 哈希类名，避免和宿主撞名
      minify: true,
    })
    // 收集 classMap 作为默认导出：import css from './X.module.css'
    const classMap = {}
    for (const [local, exp] of Object.entries(cssExports ?? {})) classMap[local] = exp.name
    return styleInjectionModule(fileId, code.toString(), classMap)
  },
}]

生成的虚拟模块长这样（去重靠 data-plugin-css 属性查询）：

const css = "._hash_panel{...}";
const tagId = "@wangjunjian/dsh-artifact-viewer/ArtifactPanel.module.css";
if (typeof document !== 'undefined'
    && document.querySelector('style[data-plugin-css=' + JSON.stringify(tagId) + ']') === null) {
  const tag = document.createElement('style');
  tag.dataset.plugin = "@wangjunjian/dsh-artifact-viewer";
  tag.dataset.pluginCss = tagId;
  tag.textContent = css;
  document.head.appendChild(tag);
}
export default { "panel": "_hash_panel", /* … */ };

⑥ define 注入：别让浏览器读到未定义变量

define: {
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'production'),
  'import.meta.env.MODE': JSON.stringify(process.env.NODE_ENV ?? 'production'),
  'import.meta.env': JSON.stringify({ MODE: process.env.NODE_ENV ?? 'production' }),
}

TypeScript 配置要点

• module / moduleResolution 用 NodeNext，源码里相对导入必须写 .js / .ts 后缀。
• declarationDir 单独输出到 lib/types，与 JS 产物分离，避免互相覆盖。
• lib/ 不提交 git；npm 包内容完全由 files 字段白名单控制。
• src 里需要一个 css-modules.d.ts，让 TS 认识 *.module.css 的默认导出。

Host 端：RPC 通道与持久化

AV 要解决的是"浏览器想读写用户磁盘上的文件、想保存跨会话的收藏"。浏览器做不到，Host 能——于是用一条 loopback RPC 通道把能力暴露出去。

核心 API

通道命名：第一个坑

connection: invalid or reserved RPC channel "/plugin/artifact-viewer"

正确做法：用自定义的短路径，并在 Host 与 Client 两边共用同一个常量。

// 两边都写死同一个字符串；生产代码建议抽到共享模块导出
const CHANNEL = '/artifact-viewer'

Handler 的形状

一个 channel 下挂多个 endpoint，用第一个参数分发。返回值必须是统一的 RpcResult 信封——不要抛异常给调用方，把错误变成 ok: false 的数据。

export const name = 'artifact-viewer'
export const inject = ['connection']

export function apply(ctx: Context, config: Config): void {
  if (!config.enabled) return

  const connection = ctx.get('connection') as HostConnectionHandle

  connection.rpc.handle(
    CHANNEL,
    async (endpoint, payload): Promise<RpcResult> => {
      // 1) 公共入参校验（每个 endpoint 都要 projectPath）
      const rawProjectPath = (payload as { projectPath?: unknown }).projectPath
      if (typeof rawProjectPath !== 'string') return badRequest('projectPath is required')
      const projectPath = await resolveProjectPath(rawProjectPath)

      // 2) 按 endpoint 分发
      if (endpoint === 'bookmarks/read')  return readBookmarks(projectPath)
      if (endpoint === 'bookmarks/write') return writeBookmarks(projectPath, payload)
      if (endpoint === 'file/preview')   return previewFile(projectPath, payload)

      return badRequest(`unknown endpoint ${endpoint}`)
    },
    { authority: 'loopback' },   // ← 关键：只接受本机回环调用
  )
}

// 统一的失败信封
function badRequest(message: string): RpcResult {
  return { ok: false, error: { code: 'bad-request', message, details: { issues: [] } } }
}

持久化：三个必须做对的细节

① 路径用 dshHomePath，不要自己拼

import { dshHomePath } from '@deepseek-ai/dsh-home-paths'

function storagesDir(): string {
  return dshHomePath('storages', 'artifact-viewer')  // ~/.dsh/storages/artifact-viewer
}
function bookmarksStoreFile(): string {
  return join(storagesDir(), 'bookmarks.json')
}

dshHomePath 会尊重 $DSH_HOME 覆盖，用户改了宿主目录也不会写到错误的地方。

② 写入必须原子：tmp + rename

直接 writeFile(file) 时进程被杀会留下半截 JSON，下次启动直接解析失败、用户收藏全丢。

async function saveBookmarkStore(store: BookmarkStore): Promise<RpcResult> {
  const file = bookmarksStoreFile()
  try {
    await mkdir(storagesDir(), { recursive: true })
    const tmp = `${file}.tmp`
    await writeFile(tmp, `${JSON.stringify(store, null, 2)}\n`)
    await rename(tmp, file)      // 同分区内 rename 是原子的
    return { ok: true, value: null }
  } catch (error) {
    return { ok: false, error: { code: 'internal', message: errorMessage(error), details: {} } }
  }
}

③ key 要 realpath 规范化

async function resolveProjectPath(raw: string): Promise<string> {
  try { return await realpath(raw) }
  catch (error) { if (isENOENT(error)) return raw; throw error }
}

文件预览：二进制与编码

文本走 utf8、二进制走 base64，并做三重保护：必须是文件、不超过 512 KB、文本必须是合法 UTF-8。

const PREVIEW_MAX_BYTES = 512 * 1024

// Buffer.toString('utf8') 会静默替换非法字节，必须用 fatal 模式显式检测
function isValidUtf8(buffer: Buffer): boolean {
  try {
    const decoder = new TextDecoder('utf-8', { fatal: true })
    decoder.decode(buffer)
    return true
  } catch { return false }
}

// 客户端拿到 base64 后按扩展名推断 mediaType 再展示
function inferMediaType(path: string): string {
  const lower = path.toLowerCase()
  if (lower.endsWith('.md') || lower.endsWith('.markdown')) return 'text/markdown'
  if (lower.endsWith('.png')) return 'image/png'
  // …
  return 'application/octet-stream'
}

Client 侧：把 RPC 包成控制器 + 快照仓库

组件不该直接碰 rpc.call。AV 用一个 BookmarkController 收敛全部读写，并把状态放进 SnapshotStore，组件订阅它即可。

import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'

const CHANNEL = '/artifact-viewer'

export class BookmarkController {
  readonly store: SnapshotStore<BookmarkState>

  constructor(private readonly rpc: ClientConnectionRpc) {
    this.store = createSnapshotStore<BookmarkState>({
      status: 'idle', bookmarks: [], error: null,
    })
  }

  async load(projectPath: string): Promise<void> {
    this.store.update((state) => { state.status = 'loading'; state.error = null })
    const result = await this.rpc.call(CHANNEL, 'bookmarks/read', { projectPath })
    if (!result.ok) { this.fail(result.error.message); return }
    if (!Array.isArray(result.value)) { this.fail('bookmarks file is not an array'); return }
    this.store.update((state) => {
      state.status = 'ready'
      state.bookmarks = result.value as BookmarkRecord[]
    })
  }

  async toggle(projectPath: string, record: BookmarkRecord): Promise<void> {
    const exists = this.store.getSnapshot().bookmarks.some((e) => e.id === record.id)
    await (exists ? this.remove(projectPath, record.id) : this.add(projectPath, record))
  }

  private fail(message: string): void {
    this.store.update((state) => { state.status = 'error'; state.error = message })
  }
}

端到端数据流

Client 端：Slots 插槽与 Face 注入

Client 插件不"渲染页面"，而是往宿主声明的插槽里贡献组件。三个项目加起来用了五个不同的插槽，本章把它们和配套的三件套（locale、store、face）一次讲完。

两个 API 的分工

最小可运行骨架

GT 的 client 入口只有 48 行，是最干净的模板：

import type {} from '@deepseek-ai/dsh-client-locale/client'
import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
import type {} from '@deepseek-ai/dsh-client-ui-layout/client'   // 拉 slot 契约
import { GithubTrendingPanel } from './GithubTrendingPanel.js'
import { en, type GithubTrendingKey, zh } from './locales.js'

const NS = 'github-trending'

// 声明合并：让 t('panel.title') 有 key 自动补全和类型检查
declare module '@deepseek-ai/dsh-client-ui-slots' {
  interface LocaleNamespaceMap { 'github-trending': GithubTrendingKey }
}

export const inject = ['slots', 'locale']

export function apply(ctx: ClientContext): void {
  // ① 注册字典（effect 包裹 → 卸载自动注销）
  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'github-trending: dictionaries')

  // ② 等插槽出现 → 登记组件
  ctx.slots.inject('shell.overlay', () =>
    ctx.slots.register(
      {
        name: 'shell.overlay',
        id: 'github-trending-panel',   // 全局唯一，重名会冲突
        order: 20,                          // additive 插槽的排序权重
        locale: NS,                        // 组件自动拿到 t 函数
      },
      GithubTrendingPanel,
    ),
  )
}

常用插槽清单

single slot "conversation.message.images" already has a registration at priority 0

ctx.slots.inject('conversation.message.images', () =>
  ctx.slots.register(
    { name: 'conversation.message.images', locale: NS, priority: -1,
      inject: (): MessageImagesFace => ({ hooks: { bookmarks: bookmarks.store }, bookmarks }) },
    ArtifactMessageImages,
  ),
)

Face 注入：组件与业务的解耦层

插槽组件是纯展示的，它拿不到 ctx，也不该拿。宿主通过 inject 回调把一族能力（叫 face）塞进 props。三个项目都定义了显式的 face 接口：

/** 注入给浮动产物面板的业务面 */
export interface ArtifactPanelFace {
  hooks: {
    currentSession: CurrentSessionSource   // 可订阅的当前会话
    bookmarks: BookmarkController['store']
  }
  bookmarks: BookmarkController
  rpc: ConnectionHandle['rpc']
  onOpenPath: (path: string) => Promise<void>   // 用宿主默认应用打开
  onOpenSession: (sessionId: string) => void       // 跳回源会话
}

ctx.slots.inject('shell.overlay', () =>
  ctx.slots.register(
    { name: 'shell.overlay', id: 'artifact-viewer-panel', order: 50, locale: NS, store: viewerStore,
      inject: (): ArtifactPanelFace => ({
        hooks: { currentSession, bookmarks: bookmarks.store },
        bookmarks,
        rpc,
        onOpenPath: (path) => ctx.workspaces.openPath(path),
        onOpenSession: (id) => ctx.sessions.open(id as SessionId),
      }),
    },
    ArtifactPanel,
  ),
)

共享状态：defineStore

面板的开关、宽度、当前标签页这类 UI 状态，用 runtime 提供的 defineStore。actions 是 Immer draft mutator，直接改就行：

import { defineStore } from '@deepseek-ai/dsh-client-runtime/client'

export const createArtifactViewerStore = () =>
  defineStore({
    init: (): ArtifactViewerState => ({
      panelOpen: false, activeTab: 'current', expanded: false, width: 420,
    }),
    actions: {
      togglePanel: (draft) => { draft.panelOpen = !draft.panelOpen },
      setTab: (draft, tab: 'current' | 'bookmarks') => { draft.activeTab = tab },
      openArtifactByPath: (draft, path: string) => {
        draft.panelOpen = true
        draft.activeTab = 'current'
        draft.pendingOpenPath = path
      },
    },
  })

把 store 挂到 slot 描述里（store: viewerStore），组件就能拿到同一份状态；注册时也可以传 createArtifactViewerStore().create() 在测试里拿到真实实例，不需要 mock 任何 hook。

三个项目的 Slot 用法对照

清理契约

slots.inject 的回调必须返回 cleanup，把所有在回调里创建的东西关掉。SP 是最完整的示例——它在一个回调里创建了六个资源，就返回六个 dispose：

ctx.slots.inject('shell.overlay', () => {
  const source        = createSpriteStateSource(ctx.sessions)   // 订阅会话
  const background    = createBackgroundSource()                // localStorage
  const spriteKind    = createSpriteKindSource()
  const position      = createSpritePositionSource()
  const selection     = createSelectionSource()                 // 划词监听
  const sync          = new SpriteSettingsSync(settings, { spriteKind, position, background })
  const presenter     = new BackgroundPresenter()
  presenter.apply(background.getSnapshot())
  const unsubscribeBackground = background.subscribe(() => presenter.apply(background.getSnapshot()))

  const dispose       = ctx.slots.register({ /* … */ }, SpriteMascot)
  const disposeToolbar = ctx.slots.register({ /* … */ }, SelectionToolbar)

  // 回调返回 cleanup：插槽消失 / 插件卸载时全部回收
  return () => {
    dispose(); disposeToolbar()
    source.dispose(); selection.dispose(); sync.dispose()
    unsubscribeBackground(); presenter.dispose()
  }
})

注意 settings（settingsScope.bind 的结果）是在 apply 顶层创建、被回调捕获的——它属于插件生命周期，不属于插槽生命周期，所以没有出现在这个 cleanup 里。区分"谁创建谁负责"是写 cleanup 的关键。

Tool 实战：让模型会用你的能力

第 7 章的 defineTool 只是最小可用集。本章用 GT 的 github_trending 展示生产级工具的全部字段，以及一个容易被忽略的核心设计：给模型看的和给 UI 看的是两条独立的输出通道。

完整字段表

三层输出模型

规范值 → 给模型的 Markdown

export interface GithubTrendingResult {
  repositories: TrendingRepository[]   // 规范值：结构化，UI 和未来的逻辑都靠它
  truncated: boolean
}

/** 把规范值格式化成给模型看的精简 Markdown 列表 */
export function formatTrendingOutput(result: GithubTrendingResult): string {
  if (result.repositories.length === 0) return 'No trending repositories found.'

  const header = result.truncated
    ? `Top ${result.repositories.length} trending repositories (truncated):`
    : `Top ${result.repositories.length} trending repositories:`

  const lines = result.repositories.map((repo) => {
    const today = repo.starsToday > 0 ? ` | +${repo.starsToday.toLocaleString()} today` : ''
    const lang  = repo.language !== undefined ? ` | ${repo.language}` : ''
    const stars = repo.stars > 0 ? ` | ⭐ ${repo.stars.toLocaleString()}` : ''
    const forks = repo.forks > 0 ? ` | 🍴 ${repo.forks.toLocaleString()}` : ''
    const description = repo.description !== undefined ? `\n  ${repo.description}` : ''
    return `${repo.rank}. [${repo.fullName}](${repo.url})${lang}${stars}${forks}${today}${description}`
  })

  return [header, ...lines].join('\n')
}

要点：字段为空就不输出。模型看到的是"信息密度最高"的文本，而不是一堆 null。

规范值 → 给 UI 的可重放元数据

presentationMeta 会被持久化到会话记录里。未来的某次重放（重新打开旧会话）不会再执行 execute，而是拿这段元数据重新渲染卡片。所以：

• 只放渲染必需的最小字段（GT 只留 fullName / url / starsToday，丢掉了 description 和 README）；
• 读取时必须做防御性校验——它可能被旧版本写入、也可能被手改。

// 写：只保留卡片需要的字段
export function trendingMetaFromValue(result: GithubTrendingResult): JsonValue {
  return {
    count: result.repositories.length,
    truncated: result.truncated,
    repositories: result.repositories.map((r) => ({ fullName: r.fullName, url: r.url, starsToday: r.starsToday })),
  }
}

// 读：逐个字段校验，任何一项不对就返回 undefined 让调用方降级
export function trendingMetaFromResult(meta: unknown): TrendingMeta | undefined {
  if (typeof meta !== 'object' || meta === null || Array.isArray(meta)) return undefined
  const { count, truncated, repositories } = meta as Record<string, unknown>
  if (typeof count !== 'number' || typeof truncated !== 'boolean' || !Array.isArray(repositories)) return undefined
  const repos = repositories.filter((repo): repo is TrendingRepoMeta => {
    if (typeof repo !== 'object' || repo === null) return false
    const r = repo as Record<string, unknown>
    return typeof r.fullName === 'string' && typeof r.url === 'string' && typeof r.starsToday === 'number'
  })
  return { count, truncated, repositories: repos }
}

两种卡片视图

/** 调用中：一张通用卡，告诉用户"在搜什么" */
export function presentTrendingCall(args: GithubTrendingArgs): GenericCallView {
  const language = args.language?.trim() || 'all languages'
  return {
    card: 'generic',
    title: `GitHub Trending: ${language} (${args.since})`,
    kind: 'search',
    rawInput: `${language} / ${args.since}`,
  }
}

/** 完成后：搜索结果卡，列出命中的链接。出错或元数据损坏时返回 undefined → 回退默认渲染 */
export function presentTrendingResult(args: GithubTrendingArgs, result: ToolResult): SearchResultView | undefined {
  if (result.isError) return undefined
  const meta = trendingMetaFromResult(result.meta)
  if (meta === undefined) return undefined
  return {
    card: 'search',
    shape: 'paths',
    title: `GitHub Trending: ${args.language ?? 'all languages'} (${args.since})`,
    paths: meta.repositories.map((repo) => repo.url),
    total: meta.count,
    truncated: meta.truncated,
  }
}

注册：连同系统提示词一起

注册工具不等于模型会用它。还需要在系统提示词里告诉模型有这么个能力、什么时候用：

export function applyGithubTrendingTool(ctx: Context, config: ToolConfig): void {
  ctx.systemPrompt.section({
    name: 'tool:github_trending',
    order: 112,
    text: 'Use the github_trending tool to discover currently popular repositories on GitHub. '
        + 'It returns repository names, descriptions, languages, star counts, and stars gained today.',
  })

  ctx.tools.register(defineTool({
    name: 'github_trending',
    description: 'Fetch currently trending GitHub repositories for a language and time window.',

    parameters: {
      language: {
        type: 'string',
        description: 'Optional programming language filter (e.g. "python", "typescript", "go"). Omit to list trending repositories across all languages.',
      },
      since: {
        type: 'string',
        description: 'Time window: "daily", "weekly", or "monthly". Defaults to "daily".',
      },
      maxResults: {
        type: 'integer',
        description: `Maximum number of repositories to return (1-${Math.min(config.maxResults, MAX_RESULTS_LIMIT)}).`,
      },
    },

    output: {
      schema: { /* 完整的对象 schema，见仓库源码 */ },
      render: (_args, value) => [{ type: 'text', text: formatTrendingOutput(value) }],
      presentationMeta: (_args, value) => trendingMetaFromValue(value),
    },

    timeoutMs: config.timeoutMs,
    isConcurrencySafe: () => true,   // 只读的抓取，天然可并发

    async execute(args, exec: ToolRunContext): Promise<GithubTrendingResult> {
      const language   = typeof args.language === 'string' ? args.language : undefined
      const maxResults = resolveMaxResults(args.maxResults, config.maxResults)
      const url = buildTrendingUrl({ language, since: args.since, maxResults })

      const repositories = await fetchTrendingRepositories(url, exec.signal)   // 转发取消信号
      return { repositories: repositories.slice(0, maxResults), truncated: repositories.length > maxResults }
    },

    presentCall: presentTrendingCall,
    presentResult: (args, result) => presentTrendingResult(args, result),
  }))
}

防御性细节

export function resolveMaxResults(requested, configCap) {
  const cap = Math.min(configCap, MAX_RESULTS_LIMIT)
  if (requested === undefined || !Number.isFinite(requested))
    return Math.min(DEFAULT_MAX_RESULTS, cap)
  return Math.max(1, Math.min(Math.round(requested), cap))
}

export function buildTrendingUrl(args) {
  const base = 'https://github.com/trending'
  const path = args.language?.trim()
    ? `${base}/${encodeURIComponent(args.language.trim())}`
    : base
  // since 做白名单，绝不拼原始输入
  const since = args.since === 'weekly' || args.since === 'monthly'
    ? args.since : 'daily'
  return `${path}?since=${since}`
}

组合与依赖

// src/index.ts
export const name = 'github-trending'
export const inject = ['tools', 'systemPrompt', 'webServer', 'llm', 'agentDefaultModel']

export function apply(ctx: Context, config: Config): void {
  // 1) 先做交叉校验（第 5 章）：正整数、成对覆盖、语言取值
  // 2) 注册工具
  applyGithubTrendingTool(ctx, {
    timeoutMs: resolved.timeoutMs,
    maxResults: Math.min(resolved.maxResults, MAX_RESULTS_LIMIT),
  })
  // 3) 可选：LLM 概览生成器（第 18 章）
  // 4) 缓存 + web 路由（第 17 章）
}

Host HTTP 路由、缓存与长轮询

RPC 适合"点对点调用"，但浏览器要轮询一份共享数据时，一条 HTTP 路由更自然。GT 在宿主上开了 /github-trending，把抓取放在 Host 侧——顺带解决了浏览器 CORS 问题。

注册路由

webServer.register 返回 disposer，用 ctx.effect 包起来，插件卸载时路由自动注销：

ctx.effect(
  () => ctx.webServer.register({
    kind: 'prefix',
    path: '/github-trending',
    handler: createTrendingHandler(cache, generator, introGenerator, resolved.overviewsMaxRepos),
  }),
  'github-trending: web route',
)

Handler 的三条规则

return async (req, res) => {
  if (req.method !== 'GET' && req.method !== 'HEAD') {
    res.writeHead(405, { 'content-type': 'application/json' })
    res.end(JSON.stringify({ error: 'Method not allowed' }))
    return
  }

  const url = new URL(req.url ?? '/', 'http://x')

  // 按需生成项目介绍：?intro=owner/name —— 先做正则白名单
  const introFullName = url.searchParams.get('intro')
  if (introFullName !== null) {
    if (!/^[\w.-]+\/[\w.-]+$/.test(introFullName)) {
      res.writeHead(400, { 'content-type': 'application/json' })
      res.end(JSON.stringify({ error: 'intro must be an owner/name repository path' }))
      return
    }
    // …生成并返回
  }

  const language     = url.searchParams.get('language') ?? undefined
  const sinceRaw      = url.searchParams.get('since') ?? 'daily'
  const since         = sinceRaw === 'weekly' || sinceRaw === 'monthly' ? sinceRaw : 'daily'
  const forceRefresh  = url.searchParams.get('refresh') === '1'

  try {
    // 命中缓存就直接返回；未命中才 refresh
    const entry = forceRefresh
      ? (await cache.refreshAll(fetchers, language))[since]
      : cache.get(language, since) === undefined
        ? await cache.refresh(fetchers[since], language, since)
        : cache.get(language, since)!

    res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' })
    res.end(present(entry))
  } catch (error) {
    // ③ 关键：刷新失败时服务旧数据，别让整个面板挂掉
    const cached = cache.get(language, since)
    if (cached !== undefined) {
      res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
      res.end(present(cached))
      return
    }
    res.writeHead(502, { 'content-type': 'application/json; charset=utf-8' })
    res.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }))
  }
}

缓存设计

TrendingCache 的四个要点，任何"Host 侧抓外部数据"的插件都能直接复用：

private async fetchWithRetry(fetcher) {
  const MAX_RETRIES = 3, RETRY_DELAY_MS = 500
  let lastError: unknown
  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
    const controller = new AbortController()
    const timer = setTimeout(() => controller.abort(), this.options.timeoutMs)
    try {
      return await fetcher(controller.signal)
    } catch (error) {
      lastError = error
      if (attempt < MAX_RETRIES) await new Promise((r) => setTimeout(r, RETRY_DELAY_MS))
    } finally {
      clearTimeout(timer)     // 成功也要清，否则 Node 不退出
    }
  }
  throw lastError
}

private notifyRefreshed(entry, language, since): void {
  if (this.options.onRefreshed === undefined) return
  try { this.options.onRefreshed(entry, language, since) }
  catch { /* 钩子失败绝不能破坏缓存 */ }
}

ctx.effect(() => () => { cache.dispose() }, 'github-trending: cache disposal')

长轮询：让"生成中"真的动起来

概览是后台逐个生成的。朴素做法是前端固定间隔轮询——但轮询间隔内新生成的概览看不到，间隔太短又浪费请求。GT 的做法是 ?wait=1 长轮询：

// Host：有未完成的概览时，把请求挂起到"下一个仓库开始或结束"
const waitForProgress = req.method === 'GET' && url.searchParams.get('wait') === '1'
if (waitForProgress && generator !== undefined && hasPending(entry)) {
  await generator.waitForChange(OVERVIEW_WAIT_TIMEOUT_MS)
  entry = cache.get(language, since) ?? entry   // 等待期间可能已被刷新替换，重新读
}

// 生成器侧：状态一变就唤醒所有等待者
waitForChange(timeoutMs: number): Promise<void> {
  return new Promise((resolve) => {
    const onChange = (): void => { clearTimeout(timer); resolve() }
    const timer = setTimeout(() => {
      this.listeners.delete(onChange)
      resolve()
    }, timeoutMs)
    this.listeners.add(onChange)
  })
}

const hasPendingOverviews = currentEntry?.repositories.some((r) => r.overviewPending) ?? false

useEffect(() => {
  if (!state.open || state.collapsed || !hasPendingOverviews) return
  const controller = new AbortController()
  const since = state.since
  void (async () => {
    for (;;) {                                // ← 循环在 effect 体内，不依赖定时器续命
      try {
        const data = await fetchEntry(since, false, controller.signal, true)
        if (controller.signal.aborted) return
        setEntries((prev) => ({ ...prev, [since]: data }))
        if (!data.repositories.some((r) => r.overviewPending)) return
      } catch {
        if (controller.signal.aborted) return
        await new Promise((r) => setTimeout(r, PENDING_RETRY_INTERVAL_MS))
      }
    }
  })()
  return () => { controller.abort() }
}, [state.open, state.collapsed, hasPendingOverviews, state.since, fetchEntry])

前端布局推挤技巧

DSH 目前没有原生右侧栏插槽，面板只能浮在 shell.overlay 上，会遮住对话。GT 用一个运行时 CSS 变量把中间列挤开：

const PUSH_CLASS = 'dsh-github-trending-pushed'

// 一次性注入样式（用 !important 覆盖宿主布局）
style.textContent = `
  .${PUSH_CLASS} > div:nth-child(2),
  .${PUSH_CLASS} > div:nth-child(3) {
    margin-right: var(--dsh-github-trending-width, 0px) !important;
    transition: margin-right var(--ds-transition-duration-slow, 0.2s) var(--ds-ease-in-out, ease);
  }
`

// 向上找到 [data-shell-overlay] 的父元素（AppFrame 根），加类 + 设变量
if (enabled) {
  frame.classList.add(PUSH_CLASS)
  frame.style.setProperty('--dsh-github-trending-width', `${width}px`)
} else {
  frame.classList.remove(PUSH_CLASS)
  frame.style.removeProperty('--dsh-github-trending-width')
}

选择器全部带插件前缀 + 用宿主自己的 CSS 变量兜底（var(--ds-transition-duration-slow, 0.2s)），不侵入主项目代码，宿主改了布局也不至于崩。

在插件里调用 LLM

Tool 是"让模型用你的能力"，这一章反过来：插件自己调模型。GT 用宿主 LLM 服务把每个仓库的 README 压成一段 80 词的中文简介——这是目前三个项目里唯一一处 LLM 消费，也是最容易踩坑的地方。

18.1 三步走：注入 → 解析路由 → 流式取回

调用链只有三步，但每一步都有隐含约定：

GT 的 src/index.ts 里是这样构造生成器的：

export const inject = ['tools', 'systemPrompt', 'webServer', 'llm', 'agentDefaultModel']

// ① 懒解析：包成箭头函数，每次 pass 开头才求值
const resolveRoute = (): OverviewRoute => {
  const selection = ctx.agentDefaultModel.currentSelection()
  return { provider: selection.provider, model: selection.model }
}

// ② 生成器拿到的是函数，不是值
const generator = new OverviewGenerator(ctx, resolveRoute, resolved.overviews)

18.2 一次完整的流式调用

下面这个函数是可以直接抄的模板。它做了四件容易被忽略的事：超时用 AbortSignal 而不是 race、区分 finish 原因、判空、finally 里取消定时器。

/** Abort signal that fires after timeoutMs, with its timer handle. */
function deadline(timeoutMs: number): { signal: AbortSignal; cancel: () => void } {
  const controller = new AbortController()
  const timer = setTimeout(() => {
    controller.abort()
  }, timeoutMs)
  return { signal: controller.signal, cancel: () => clearTimeout(timer) }
}

export async function streamGeneratedText(
  ctx: Context,
  route: OverviewRoute,
  request: {
    messages: GenerateOptions['messages']
    system: string
    maxTokens: number
    timeoutMs: number
    label: string
  },
): Promise<string> {
  const call = deadline(request.timeoutMs)
  try {
    const assembler = new BlockAssembler()
    for await (const chunk of ctx.llm.stream({
      provider: route.provider,
      model: route.model,
      messages: request.messages,
      system: request.system,
      maxTokens: request.maxTokens,
      signal: call.signal,
    })) {
      assembler.push(chunk)
    }

    const finish = assembler.finish
    // ① max-tokens 视为"部分成功"：截断的简介好过没有简介
    if (finish.kind !== 'stop' && finish.kind !== 'max-tokens') {
      const detail = 'failure' in finish ? finish.failure.message : finish.kind
      throw new Error(
        `${request.label} via ${route.provider}/${route.model} finished with ${finish.kind}: ${detail}`,
      )
    }

    const text = assembler
      .blocks()
      .filter((block) => block.type === 'text')
      .map((block) => block.text)
      .join('')
      .trim()

    // ② 空文本必须报错：否则你会在 UI 上看到一堆空白卡片
    if (text === '') {
      throw new Error(
        `${request.label} via ${route.provider}/${route.model} returned empty text (finish: ${finish.kind})`,
      )
    }
    return text
  } finally {
    // ③ 成功失败都要清定时器，否则 Node 进程被悬挂的 timer 拖住
    call.cancel()
  }
}

18.3 构造消息：createUserMessage 与 source 标记

插件发起的调用不是用户在说话，但也要以 user 消息的形式送进去。宿主要知道"这条消息来自哪个插件"，所以 source 字段不能省：

const system =
  `You write concise overviews of GitHub repositories for a trending list. ` +
  `Write in ${LANGUAGE_NAMES[options.language]}. Reply with a single short ` +
  `paragraph (at most 80 words) explaining what the project is, what problem ` +
  `it solves, and why it might be gaining attention. No markdown, no preamble, no headings.`

const messages = [
  createUserMessage({
    content: [
      {
        type: 'text',
        text:
          `Repository: ${repo.fullName}\n` +
          `Description: ${repo.description ?? '(none)'}\n\n` +
          `README (truncated):\n${readme}`,
      },
    ],
    // 让宿主知道来源插件 —— 日志、配额、审计都靠它
    source: { kind: 'plugin', plugin: 'github-trending' },
  }),
]

return streamGeneratedText(ctx, route, {
  messages,
  system,
  maxTokens: options.maxTokens,
  timeoutMs: options.timeoutMs,
  label: `overview generation for ${repo.fullName}`,
})

label 是个小设计但很值：所有错误信息都带上"哪个仓库的什么调用走的哪条路由"，日志里一眼能定位是 provider 配错了还是某个仓库的 README 太长。

18.4 串行调度器：绝不让 N 个 LLM 请求并发

一次刷新有最多 10 个仓库要生成简介。如果直接 Promise.all，你会：瞬间打爆 provider 限流、把用户的正常对话请求挤到排队、以及拿到一堆 429。GT 用一个串行队列解决，而且它比"简单队列"多考虑了四件事：

private async drain(): Promise<void> {
  if (this.draining) return          // 单飞：已在 drain 就直接返回
  this.draining = true
  try {
    for (;;) {
      const next = this.pickNext()
      if (next === undefined) return
      const { key, entry, version } = next
      try {
        // 每轮 pass 都重新解析路由 —— 用户换模型立即生效
        const route = this.resolveRoute()
        await enrichEntryWithOverviews(this.ctx, route, entry, this.options, {
          isStale: () => this.versions.get(key) !== version,
          onRepoStart: (repo) => {
            this.current = repo.fullName
            this.notifyChange()
          },
          onRepoDone: (repo, outcome, skipReason) => {
            this.current = undefined
            if (outcome === 'skipped')
              this.recordFailure(entry, repo.fullName, skipReason ?? 'unknown')
            this.notifyChange()
          },
        })
      } catch {
        // pass 级失败（比如插件被卸载）绝不能 reject 这个 fire-and-forget
      }
    }
  } finally {
    this.draining = false
  }
}

request(entry, language, since): void {
  const key = pendingKey(language, since)
  this.versions.set(key, (this.versions.get(key) ?? 0) + 1)
  this.pending.set(key, entry)
  void this.drain()   // 故意不 await
}

18.5 单层失败绝不上抛

enrichEntryWithOverviews 的循环体里，每个仓库一个 try/catch，失败只记 reason 继续下一个：

for (const repo of entry.repositories.slice(0, options.maxRepos)) {
  if (hooks?.isStale?.() === true) return
  hooks?.onRepoStart?.(repo)
  let outcome: EnrichOutcome = 'skipped'
  let skipReason: string | undefined
  try {
    const call = deadline(options.timeoutMs)
    let readme: string | undefined
    try {
      readme = await fetchReadmeText(repo.fullName, call.signal)
    } finally {
      call.cancel()
    }
    if (readme === undefined) {
      skipReason = 'no README found on the default branch'
    } else {
      repo.overview = await summarizeRepository(ctx, route, repo, readme, options)
      outcome = 'generated'
    }
  } catch (error) {
    skipReason = error instanceof Error ? error.message : String(error)
    ctx.logger.warn('github-trending: overview generation skipped for %s: %s', repo.fullName, skipReason)
  } finally {
    hooks?.onRepoDone?.(repo, outcome, skipReason)
  }
}

设置持久化与优雅降级

Config 是管理员在 patch 里写的启动参数，Settings 是用户在界面上改的偏好。混用两者是新手最常见的架构错误。SP 是三个项目里唯一用了 Settings 服务的，而且它把"三层降级"做到了极致。

19.1 先分清：Config vs Settings

19.2 Schema 两端共享：一个模块，两种用途

关键洞察：Schema 文件必须同时被 Host 和 Client 引用，所以它不能 import 任何 Node-only 的东西。SP 的 src/settings.ts 只依赖 schemastery：

export const SPRITELY_SETTINGS_NAMESPACE = 'ui-sprite'

export const SPRITELY_CHARACTER_FIELD  = 'character'
export const SPRITELY_POSITION_FIELD   = 'position'
export const SPRITELY_BACKGROUND_FIELD = 'background'

export interface SpritelySettings {
  character: SpriteKind
  position: SpritePosition | null
  background: BackgroundState | null
  veil: number
}

export const SpritelySettingsSchema = z.object({
  character:  z.union([...CHARACTER_KINDS]).default('blob'),
  position:   z.object({ ... }).nullable().default(z.const(null)),
  background: z.object({ ... }).nullable().default(z.const(null)),
  veil:       z.number().default(0.5),
})

19.3 Host 端：用可选依赖注册命名空间

这是 SP 整个 Host 半边的全部代码（18 行）。注意它用的是 ctx.inject(['settings'], cb) 而不是 export const inject——因为 settings 服务可能不存在：

import type { Context } from '@deepseek-ai/cordis'
import { settingsNamespace } from '@deepseek-ai/dsh-settings'
import { SPRITELY_SETTINGS_NAMESPACE, SpritelySettingsSchema } from './settings.js'

export function apply(ctx: Context): void {
  // settings 是可选依赖：宿主没装 settings 插件时，回调根本不会执行，
  // 插件其余部分照常工作（localStorage 模式）
  ctx.inject(['settings'], (settingsCtx) => {
    settingsCtx.settings.register(
      settingsNamespace(SPRITELY_SETTINGS_NAMESPACE),
      SpritelySettingsSchema,
    )
  })
}

19.4 Client 端：绑定命名空间与快照字段

Client 侧只需一行绑定：

// 绑定后拿到一个 SettingsScope<SpritelySettings>
const settings = ctx.settingsScope.bind<SpritelySettings>({
  namespace: SPRITELY_SETTINGS_NAMESPACE,
})

scope.getSnapshot() 返回的字段是理解整套机制的关键：

19.5 双向桥：SpriteSettingsSync

localStorage 快（首帧就能读），Host 文档准（跨浏览器共享）。SP 用一座桥把两者接起来，遵循三条规则：

export class SpriteSettingsSync {
  private readonly unsubscribe: () => void
  private migrated = false

  constructor(
    private readonly scope: SettingsScope<SpritelySettings>,
    private readonly sources: SpriteSettingsSources,
  ) {
    this.unsubscribe = scope.subscribe(() => {
      this.adopt()
    })
    this.adopt()      // 构造时立即采纳一次
  }

  // 用户写入：本地 + Host 双写，本地先行
  setCharacter(kind: SpriteKind): void {
    this.sources.spriteKind.set(kind)
    this.write(SPRITELY_CHARACTER_FIELD, kind)
  }

  private adopt(): void {
    const snapshot = this.scope.getSnapshot()
    if (snapshot.status !== 'ready' || snapshot.value === undefined) return
    if (!this.hasUserLayer(snapshot)) {
      this.migrate(snapshot)   // 全新命名空间 → 本地值上行
      return
    }
    const { value } = snapshot
    const user = snapshot.user as Partial<SpritelySettings>
    // 只采纳用户层持有的字段，且值不同才写（避免回环）
    if (SPRITELY_CHARACTER_FIELD in user &&
        !sameValue(this.sources.spriteKind.getSnapshot(), value.character)) {
      this.sources.spriteKind.set(value.character)
    }
    // position / background 同理
  }

  private write(field: string, value: unknown): void {
    const snapshot = this.scope.getSnapshot()
    if (snapshot.mode !== 'host' || !snapshot.writable) return
    void this.scope.set(field, value)
  }

  dispose(): void { this.unsubscribe() }
}

19.6 三层降级全景

把上面的机制串起来，SP 在任何环境下都不会"白屏"或"报错"：

客户端状态源模式

Client 端有两种状态容器，用错是新手最容易犯的设计错误。这一章讲清楚 defineStore 和 Source（Observable） 的分工，以及 SP 里那个教科书级的 Source 实现。

20.1 两种容器，一个判据

20.2 Source 契约：四个方法，三条铁律

Source 就是 React useSyncExternalStore 要求的那个形状，只是多了一个 dispose：

export interface SpriteStateSource extends HostObservable<SpriteState> {
  /** Unsubscribe from the sessions list and the current session snapshot. */
  dispose(): void
}

// HostObservable<T> 的形状：
//   getSnapshot(): T          —— 返回当前值
//   subscribe(fn): () => void —— 订阅，返回退订函数

1. getSnapshot() 必须返回稳定引用。两次调用之间没有变化时，必须返回同一个对象。返回新对象会让 React 认为每次都变了，陷入无限重渲染。
2. 只有值真的变了才通知。用值比较（不是引用比较）过滤，否则高频上游会淹没订阅者。
3. 通知时先拷贝监听器集合。for (const fn of [...listeners]) fn()——监听器可能在回调里退订自己，直接遍历原集合会漏通知或抛错。

20.3 第一步：把派生逻辑抽成纯函数

这是整个模式的核心价值：投影逻辑是纯函数，可以单测，无需 mock 任何服务。SP 把"会话当前在干嘛"压缩成 6 种姿态，优先级写在文档注释里：

export type SpriteActivity =
  | 'idle' | 'thinking' | 'writing' | 'working' | 'waiting' | 'error'

export interface SpriteState {
  readonly activity: SpriteActivity
  /** Name of the in-flight tool call while activity === 'working', else undefined. */
  readonly toolName: string | undefined
}

const IDLE: SpriteState = Object.freeze({ activity: 'idle', toolName: undefined })

/**
 * Precedence: a pending interaction wins (the user must answer), then a
 * failed turn, then the running phase, then idle. While running, in-flight
 * tool calls rank first (working), then a streamed text block (writing),
 * then reasoning or the pre-first-token latency (thinking).
 */
export function deriveSpriteState(
  list: SessionListState,
  snapshot: ConversationSnapshot | undefined,
): SpriteState {
  const row = list.current === undefined ? undefined : list.byId[list.current]

  // ① 待用户交互最高优先级：权限确认/追问不回答，一切都不会继续
  if (row?.pendingInteraction !== undefined) {
    return { activity: 'waiting', toolName: undefined }
  }
  if (snapshot === undefined) return { activity: 'idle',   toolName: undefined }
  if (snapshot.lastAgentError !== null)  return { activity: 'error',  toolName: undefined }
  if (!snapshot.running)                     return { activity: 'idle',   toolName: undefined }

  // ② 运行中的细分：工具调用 > 文本流 > 推理/等待首 token
  const calls = snapshot.runningCalls
  if (calls.length > 0) {
    return { activity: 'working', toolName: calls[calls.length - 1]?.name }
  }
  const blocks = snapshot.partial?.blocks ?? []
  if (blocks.some((b) => b.kind === 'tool-call')) return { activity: 'working',  toolName: undefined }
  if (blocks.some((b) => b.kind === 'text'))      return { activity: 'writing',  toolName: undefined }

  // Reasoning-only partial, or running with no visible chunk yet.
  return { activity: 'thinking', toolName: undefined }
}

20.4 第二步：包装成 Source，跟随当前会话

纯函数只处理"给定输入得出输出"。Source 负责两件事：订阅上游、在选中会话变化时重新订阅。注意 refresh（重算）和 follow（重挂）是分开的：

export function createSpriteStateSource(sessions: ISessions): SpriteStateSource {
  const listeners = new Set<() => void>()
  let current: SpriteState = IDLE
  let unsubscribeSession: (() => void) | undefined

  // 重算：读列表快照 + 当前会话快照 → 纯派生 → 变了才通知
  const refresh = (): void => {
    const list = sessions.list.getSnapshot()
    const id = list.current
    const binding = id === undefined ? undefined : sessions.binding(id)
    const snapshot = binding?.session.getSnapshot()
    const next = deriveSpriteState(list, snapshot)

    if (!sameState(current, next)) {   // 值比较，不是引用比较
      current = next
      for (const fn of [...listeners]) fn()   // 拷贝后再遍历
    }
  }

  // 重挂：选中会话变了，退订旧的、订阅新的
  const follow = (): void => {
    unsubscribeSession?.()
    unsubscribeSession = undefined
    const id = sessions.list.getSnapshot().current
    const binding = id === undefined ? undefined : sessions.binding(id)
    if (binding !== undefined) {
      unsubscribeSession = binding.session.subscribe(refresh)
    }
    refresh()
  }

  const unsubscribeList = sessions.list.subscribe(follow)
  follow()   // 构造时立即挂载一次

  return {
    getSnapshot: () => current,
    subscribe(fn) {
      listeners.add(fn)
      return () => { listeners.delete(fn) }
    },
    dispose() {
      unsubscribeList()
      unsubscribeSession?.()
    },
  }
}

20.5 在组件里消费

Source 通过 Face 注入传给组件（见第 15 章），组件用标准 hook 消费，全程不知道 sessions 服务存在：

// Face 声明：hooks 里塞的是 Source 本身，不是值
inject(): SpriteMascotInjected => ({
  hooks: { sprite: source, background, spriteKind, position },
  startSession: () => { ctx.workspaces.startSession() },
  setSpriteKind: (kind) => { sync.setCharacter(kind) },
  // …
})

// 组件内部：标准 useSyncExternalStore
const state = useSyncExternalStore(
  hooks.sprite.subscribe,
  hooks.sprite.getSnapshot,
)
// state.activity === 'working' → 播放敲键盘动画

测试策略

双端插件的测试难点在于：Host 代码跑在 Node，Client 代码跑在浏览器，同一个 tests/ 目录里要同时支持两种环境。三个项目给出了两套可行配置，以及一套"能不 mock 就不 mock"的分层原则。

21.1 三层测试金字塔

21.2 双环境配置（两种写法）

AV 和 GT 用 Vitest 3 的 environmentMatchGlobs；SP 用 Vitest 4，该选项已被移除，改为逐文件 pragma。两种都要会：

import { fileURLToPath } from 'node:url'
import { defineConfig } from 'vitest/config'

const root = fileURLToPath(new URL('.', import.meta.url))

export default defineConfig({
  test: {
    globals: false,
    environment: 'node',
    environmentMatchGlobs: [
      ['tests/**/*.client.spec.tsx', 'jsdom'],
      ['tests/**/*.client.spec.ts',  'jsdom'],
    ],
    server: {
      deps: { inline: [/@deepseek-ai/] },   // 别让 CJS 产物走 extern
    },
  },
  resolve: {
    alias: [
      // 源码为 NodeNext 写的 .js 后缀，测回 .ts
      { find: /^(\.\.?\/.*)\.js$/, replacement: '$1' },
      { find: /^react$/,              replacement: `${root}node_modules/react` },
      { find: /^react-dom$/,          replacement: `${root}node_modules/react-dom` },
      { find: /^react\/jsx-runtime$/, replacement: `${root}node_modules/react/jsx-runtime` },
    ],
  },
})

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: false,
    include: ['tests/**/*.spec.{ts,tsx}'],
    setupFiles: ['tests/setup.ts'],
    // Individual client specs opt into jsdom via the per-file
    // `@vitest-environment jsdom` pragma; the default stays Node.
    // (`environmentMatchGlobs` no longer exists in Vitest 4.)
  },
})

// @vitest-environment jsdom
import { afterEach, describe, expect, it, vi } from 'vitest'

21.3 测试 Host 端：真 Context + 假服务

Host 插件测试的最佳姿势是用真的 Context 加载真的插件模块，只把宿主服务换成假的。关键是让假服务把 handler 收集起来，供测试直接调用：

import { mkdtemp, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { Context } from '@deepseek-ai/cordis'
import * as ArtifactViewerPlugin from '../src/index.js'

let ctx: Context
let fiber: Awaited<ReturnType<Context['plugin']>>
let rpcHandlers: Map<string, Function>

beforeEach(async () => {
  tmpDir = await mkdtemp(join(tmpdir(), 'dsh-artifact-viewer-'))
  rpcHandlers = new Map()

  ctx = new Context()
  // ① provide 假服务：把注册进来的 handler 存起来，返回 disposer
  ctx.provide('connection', {
    rpc: {
      handle: vi.fn((channel, handler) => {
        rpcHandlers.set(channel, handler)
        return () => { rpcHandlers.delete(channel) }
      }),
    },
  } as never)

  // ② 用真插件模块加载真 fiber
  fiber = await ctx.plugin(ArtifactViewerPlugin, {})
})

afterEach(async () => {
  await fiber.dispose()                              // 验证清理逻辑
  await rm(tmpDir, { recursive: true, force: true })
})

it('reads and writes bookmarks', async () => {
  // ③ 直接调 handler，不用真的 RPC 传输层
  const handler = rpcHandlers.get('/artifact-viewer')!
  await handler('bookmarks/write', { entries: [...] })
  const read = await handler('bookmarks/read', {})
  expect(read).toMatchObject({ ok: true })
})

21.4 测试 Client 端：假 Source + 纯 props 组件

组件保持"纯 props"的回报在这里兑现——测组件时你只需要给它一组假的 hooks：

// ① 迷你 Source 工厂：localStorage 可选持久化（正好复刻真实 source 的行为）
function createSnapshotStore<T>(
  initial: T,
  options?: { persist?: { name: string } },
) {
  const key = options?.persist?.name
  const stored = key ? localStorage.getItem(key) : null
  let current: T = stored !== null ? JSON.parse(stored) : initial
  const listeners = new Set<() => void>()
  return {
    getSnapshot: () => current,
    subscribe: (fn: () => void) => { listeners.add(fn); return () => { listeners.delete(fn) } },
    set: (value: T) => {
      current = value
      if (key) localStorage.setItem(key, JSON.stringify(value))
      for (const fn of [...listeners]) fn()
    },
  }
}

// ② 组件测的是"给 props → 出什么 DOM / 调什么回调"
render(<SpriteMascot hooks={{ sprite: fakeSource, … }} setSpriteKind={spy} />)
await user.click(screen.getByRole('button', { name: '切换形象' }))
expect(spy).toHaveBeenCalledWith('cat')

21.5 三个项目的测试清单

发布、安装与排错

这一章全部是踩过的坑。前面 21 章教你写代码，这一章教你的代码真的跑起来。

22.1 发布前验证

22.2 package.json 检查清单

{
  "name": "@wangjunjian/dsh-artifact-viewer",
  "version": "0.4.0",
  "type": "module",
  "main": "./lib/index.js",          // ← Host 半边（ESM）
  "types": "./lib/index.d.ts",
  "exports": {
    ".":                  "./lib/index.js",
    "./client":           "./lib/client.js",   // ← Client 半边（CJS 自注册）
    "./cordis.patch.yml": "./cordis.patch.yml", // ← Bundle 清单，必须导出
    "./package.json":     "./package.json"
  },
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": [...],     // Client 需要的服务
      "external": [...]    // 走模块表、不内联
    }
  },
  "files": ["lib", "cordis.patch.yml", "README.md"],
  "peerDependencies": { // 宿主提供，运行时由模块表解析
    "@deepseek-ai/cordis": "*",
    "react": "*"
  },
  "scripts": {
    "build": "tsc -b tsconfig.json && tsdown",
    "prepare": "tsc -b tsconfig.json && tsdown"
  }
}

22.3 CI 与 Trusted Publishing

三个项目都用 GitHub Actions + npm OIDC 免 token 发布。两个工作流：

release.yml 里有三个非显然的必需步骤：

# 1. 权限：OIDC 必须
permissions:
  contents: read
  id-token: write

# 2. 版本一致性校验：release tag 去 v 后必须等于 package.json 的 version
- name: Verify version consistency
  run: |
    tag_version="${GITHUB_REF_NAME#v}"
    pkg_version="$(node -p "require('./package.json').version")"
    [ "$tag_version" = "$pkg_version" ] || { echo "version mismatch"; exit 1; }

# 3. 升级 npm CLI：trusted publishing 要求 npm ≥ 11.5.1，Node 22 自带的是 10
- run: npm install -g npm@latest
- run: npm publish --provenance --access public

22.4 发版命令序列

# 1. bump package.json 的 version（如 0.2.0 → 0.2.1）后：
version="$(node -p "require('./package.json').version")"
git commit -am "release: v${version}"
git tag "v${version}"
git push origin main --tags

# 2. 创建 GitHub Release —— 这才是触发发布工作流的关键一步
gh release create "v${version}" --title "v${version}" --notes "本次变更说明"

# 3. 观察结果
gh run watch --workflow=Publish
npm view <pkg> version      # 新包有几分钟元数据传播延迟

22.5 安装与升级

# 从 npm 安装
dsh plugin --profile web add @wangjunjian/dsh-artifact-viewer

# 从本地路径安装（开发时最常用，改动后需重新 add 或 link）
dsh plugin --profile web add /Users/you/GitHub/wang-junjian/dsh-artifact-viewer

# 移除
dsh plugin --profile web remove @wangjunjian/dsh-artifact-viewer

dsh plugin add 的实际效果可以直接检查 ~/.dsh/profiles/web/package.json 里的 dependencies 和 dsh.profile.bundles——这是排错时最快的事实来源。

22.6 坑位总表

22.7 调试技巧

• 先看 DSH 启动日志。绝大多数加载失败（RPC 保留前缀、slot 优先级冲突、module table 内联、loader entry 重复）都在这里有明确报错。
• 浏览器控制台查 window.__ModuleLoader__，确认你的 client bundle 是否真的注册进去了、id 对不对。
• 样式问题先查 CSS 变量。DSH 主题变量有没有被正确赋值；你的 fallback 值（var(--ds-xxx, 兜底值)）是否写对。
• 直接检查 profile 目录 ~/.dsh/profiles/web/package.json，看 dependencies 与 bundles 的实际内容，比任何日志都准。

22.8 推荐开发流程（八步）

速查手册（实战版）

把三个项目里反复出现的写法压成可复制的模板。这一章就是拿来抄的。

23.1 Host 端骨架

// src/index.ts
import type { Context } from '@deepseek-ai/cordis'
import { z } from '@deepseek-ai/schemastery'

export const name = 'my-plugin'          // 与 cordis.patch.yml 的 id 一致

// ① 硬依赖：缺了插件就加载失败
export const inject = ['connection', 'webServer', 'llm']

// ② Config schema（管理员在 patch 里写）
export interface Config { timeoutMs: number }
export const Config = z.object({ timeoutMs: z.number().default(30_000) })

export function apply(ctx: Context, config: Config): void {
  // ③ 跨字段校验：schema 表达不了的放这里
  if (config.timeoutMs <= 0) throw new Error('timeoutMs must be positive')

  // ④ 可选依赖：服务不存在则回调不执行，插件照常加载
  ctx.inject(['settings'], (sctx) => {
    sctx.settings.register(settingsNamespace('my-plugin'), MySchema)
  })

  // ⑤  dispose 型资源一律用 effect 包起来（带 label，便于调试）
  ctx.effect(() => ctx.webServer.register({
    kind: 'prefix', path: '/my-plugin', handler,
  }), 'my-plugin: http route')

  ctx.effect(() => () => cache.dispose(), 'my-plugin: cache disposal')

  // ⑥ RPC：channel 绝不能用 /plugin/* 前缀
  ctx.connection.rpc.handle('/my-plugin', async (endpoint, payload) => {
    try {
      switch (endpoint) {
        case 'items/read':  return { ok: true, value: await read() }
        case 'items/write': return { ok: true, value: await write(payload) }
        default: return { ok: false, error: `unknown endpoint: ${endpoint}` }
      }
    } catch (error) {
      // ⑦ 异常不外抛，转成 error 信封
      return { ok: false, error: error instanceof Error ? error.message : String(error) }
    }
  }, { authority: 'loopback' })
}

23.2 Client 端骨架

// src/client/index.ts
import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
// 类型专用导入：只取 Context 合并，不产生运行时依赖（bundle 纯净门禁）
import type {} from '@deepseek-ai/dsh-client-locale/client'
import type {} from '@deepseek-ai/dsh-client-ui-settings/client'

export const inject = ['slots', 'locale', 'connection', 'settingsScope']

// 声明合并：把本插件的文案 key 挂进宿主的命名空间表
declare module '@deepseek-ai/dsh-client-ui-slots' {
  interface LocaleNamespaceMap { 'my-plugin': MyKey }
}

export function apply(ctx: ClientContext): void {
  ctx.effect(() => ctx.locale.register('my-plugin', { zh, en }), 'my-plugin: dictionaries')

  const settings = ctx.settingsScope.bind<MySettings>({ namespace: 'my-plugin' })

  // ⚠️ 用 inject 声明 slot，不要直接 register —— slot 可能还没被声明
  ctx.slots.inject('shell.overlay', () => {
    const source = createMySource(ctx.sessions)      // 外部状态 → Source
    const store  = createMyStore()                   // 自有状态 → defineStore
    const sync   = new MySettingsSync(settings, source)

    const dispose = ctx.slots.register(
      {
        name: 'shell.overlay',
        id: 'my-plugin-panel',        // 全局唯一
        locale: 'my-plugin',
        order: 50,                        // 叠加型 slot 用 order
        // priority: -1                    // 单一型 slot 才用 priority
        inject: (): MyPanelInjected => ({   // Face 注入：组件保持纯 props
          hooks: { source },
          onSubmit: (v) => { sync.set(v) },
        }),
      },
      MyPanel,
    )

    // 谁创建，谁销毁 —— 严格逆序
    return () => {
      dispose()
      source.dispose()
      sync.dispose()
    }
  })
}

23.3 服务目录

23.4 Host API 速查

23.5 Client API 速查

23.6 三条贯穿全书的铁律

到这里，三个项目的源码已经被拆成了可复用的模式。下一步是打开 dsh-artifact-viewer 的 docs/best-practices.md——那份文档是这三个项目在真实迭代中积累的踩坑记录，本教程的第 22 章大量取材于它。写代码时遇到诡异行为，先去那里搜一遍。