插件工程化组织、单元测试与构建实操

1. 1

   初始化插件包结构并配置 package.json，规范 ESM 导出项与 TypeScript 类型声明。

   json

   {
     "name": "dsh-plugin-weather-gate",
     "version": "1.0.0",
     "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "scripts": {
       "build": "tsc",
       "test": "vitest run",
       "lint": "tsc --noEmit"
     },
     "peerDependencies": {
       "@deepseek-ai/cordis": "*"
     },
     "devDependencies": {
       "@deepseek-ai/cordis": "^4.0.2",
       "typescript": "^5.5.0",
       "vitest": "^2.0.0"
     }
   }

2. 2

   编写标准插件源码 src/index.ts，实现工具注册、配置校验与资源清理回调。

   typescript

   import type { Context } from '@deepseek-ai/cordis'
   
   export const name = 'weather-gate'
   export const inject = ['tools']
   
   export interface Config {
     apiKey?: string
     timeout?: number
   }
   
   export function apply(ctx: Context, config: Config = {}) {
     const timeout = config.timeout ?? 5000
   
     ctx.tools.register({
       name: 'query_weather',
       description: 'Query weather for a specific city',
       parameters: {
         city: { type: 'string', required: true, description: 'City name' }
       },
       output: {
         schema: { type: 'string' },
         render: (_args: any, value: string) => [{ type: 'text', text: value }]
       },
       async execute(args: { city: string }) {
         return `Weather in ${args.city}: Sunny, 24°C (timeout: ${timeout}ms)`
       }
     })
   
     ctx.effect(() => {
       return () => {
         // 注册资源释放回调
       }
     })
   }

3. 3

   编写针对 Cordis Mock 上下文的单元测试 tests/index.spec.ts，验证插件装载、工具调用与 Fiber 销毁回滚。

   typescript

   import { describe, it, expect } from 'vitest'
   import { Context } from '@deepseek-ai/cordis'
   import * as WeatherPlugin from '../src/index.js'
   
   describe('WeatherPlugin Quality Gate Test', () => {
     it('should load plugin and register tool on ready context', async () => {
       const ctx = new Context()
       
       // Mock tools 服务仓库
       const registeredTools: any[] = []
       ctx.provide('tools', {
         register(tool: any) {
           registeredTools.push(tool)
         }
       })
   
       const fiber = ctx.plugin(WeatherPlugin, { timeout: 3000 })
       await ctx.start()
   
       expect(registeredTools).toHaveLength(1)
       expect(registeredTools[0].name).toBe('query_weather')
   
       const result = await registeredTools[0].execute({ city: 'Beijing' })
       expect(result).toContain('Beijing: Sunny, 24°C (timeout: 3000ms)')
   
       // 验证销毁行为与 Fiber 可逆性
       await fiber.dispose()
     })
   })

4. 4

   执行质量门禁流水线：运行类型检查、单元测试并构建产物。

   bash

   pnpm lint && pnpm test && pnpm build