DeepSeek Harness 插件入门：创建、加载与卸载一个最小本地插件

本文沿用官方最小插件教程的接口，目标是建立一个可观察、可卸载的本地扩展。适用前提：已经完成官方仓库的源码安装与构建。API 仍在演进，先记录仓库提交；以下是文档示例，本站没有执行安装或运行验证。

1. 创建一个只打印日志的插件

在仓库根目录创建 scratch-plugin/src/operator-note.ts，先不接入任何业务系统：

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

export const name = 'operator-note'

export function apply(ctx: Context) {
  console.log('[operator-note] initialized')
}

apply 在框架加载插件时执行。第一步只验证模块能被找到、入口能被调用，不同时混入模型请求、网络连接和文件写入。

2. 写入加载 overlay

创建 scratch-plugin/cordis.yml。把示例路径替换成你实际仓库的绝对路径：

- insert:
    - id: operator-note
      name: '/absolute/path/deepseek-harness/scratch-plugin/src/operator-note.ts'

在仓库根目录启动：

pnpm dsh web --patch ./scratch-plugin/cordis.yml

终端出现 [operator-note] initialized 才说明这个入口已执行；只看到 Web 页面打开还不够。路径错误时先检查文件是否存在、路径是否绝对，不要靠反复安装依赖掩盖配置问题。

3. 再增加依赖与清理

若插件需要 tools 等服务，应按当前服务文档导出 inject，并核对对应接口后再调用。框架会等待依赖可用。通过框架上下文登记的效果与自行创建的资源，要按官方生命周期处理；例如直接创建的计时器可在 ctx.effect 中返回 clearInterval 清理函数。

4. 用四个现象验收

先检查加载日志，再改变一个可观察配置，随后卸载插件，最后重新加载。分别确认：新值生效、卸载后相关资源停止、重载没有重复效果。不要把一次启动成功写成插件已经适用于所有预览版本。

需要进一步开发时，再阅读配置 schema与服务依赖。发布插件前记录依赖版本、适用的 Harness 版本和一个明确的演示任务。