DeepSeek Harness 第一个插件：先挂上去，再谈产品化

插件到底是什么

官方教程里，插件是一个导出 apply 的 TypeScript 模块。框架加载时把 ctx 交给你，你在 apply 里注册能力。最小形状：

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

export const name = 'hello-plugin'

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

这就是完整配置。不要一上来写工具、改模型、接外部 API。

官方路径的顺序

1. 从已完成源码构建的仓库根目录开始。
2. 建一个本地插件文件。
3. 用 cordis.yml overlay insert 进去，路径必须是绝对路径。
4. 用该 overlay 启动 Web UI，看控制台是否打出加载日志。

具体命令与 YAML 字段以官方教程为准——预览期间字段名会变。

跑通之后再做什么

别把第一个插件写成「什么都能做的代理」。按官方架构表选一个缝：

• 只想加一条人类命令：ctx.commands
• 只想给模型一个窄工具：ctx.tools
• 只想换模型厂商：ctx.llm

插件仓库打上 GitHub topic dsh-plugin，官方 README 用这个做发现。

安全边界

插件能接到文件系统、子进程和凭证。本地实验可以宽；要给别人用，先把权限收窄。不要在插件里硬编密钥，不要默认打开任意 shell。

常见问题

插件为什么没加载？

官方教程强调路径必须绝对。patch 文件只贡献配置，不改变 loader 解析模块的工作目录。

应该发布成 npm 包吗？

先本地 overlay 跑通。真正要分发再按官方插件发布说明来，并打上 dsh-plugin topic。

官方来源：Your first plugin。本文是边界和顺序导读，不替代教程里的 YAML 与启动命令。