如何创建 DeepSeek Harness 插件

DeepSeek Harness 插件通过与内置能力相同的 Cordis 组合系统扩展智能体运行时。一个可靠的插件应只解决清晰的问题，明确声明依赖，能清理它注册的全部副作用，并为安装者提供可核验的证据。

DeepSeek Harness 仍处于开发者预览阶段。发布前请以官方仓库中的当前接口为准。

1. 选择单一能力边界

先定义具体用户结果：连接一个服务、注册模型可调用工具、增加界面、持久化某类状态，或观察运行时事件。不要把互不相关的高权限能力塞进同一个插件。边界越清晰，权限、测试、故障和用户信任就越容易解释。

可以浏览完整插件目录和插件分类，了解现有项目如何描述用途。

2. 理解插件生命周期

Harness 通过 Cordis 挂载插件。插件可以提供或消费服务、监听事件、注册工具或贡献配置。每一项注册都应有对应的清理路径，卸载后不能遗留监听器、定时器、进程或被修改的全局状态。

应覆盖以下生命周期：

1. 在产生副作用前完成配置校验。
2. 缺少必需服务时，以清晰错误停止启动。
3. 只有校验成功后才获取资源。
4. 卸载时释放监听器、定时器、子进程和临时资源。
5. 反复挂载和卸载不会重复注册行为。

3. 声明配置与权限

文档中列出每个配置项的类型、默认值，以及它是否包含密钥。不要把凭据写入源码、生成包、示例日志或浏览器可见配置。遵循最小权限，只申请插件确实需要的文件路径、网络域名、命令和服务。

如果插件提供模型可调用工具，必须在边界校验全部参数。把模型输出当作不可信输入；限制文件路径和进程执行，尽可能使用白名单，错误信息不得泄露凭据。

4. 让所有副作用可逆

Cordis 可以跟踪并在卸载时移除注册项，但插件仍需通过受支持的生命周期注册工作。避免脱离生命周期的全局修改；长时间任务应支持取消，并处理卸载与正在执行的工具调用之间的竞争。

5. 测试真实行为

至少测试：

• 合法与非法配置；
• 必需服务存在或缺失时的启动；
• 完整成功用户流程；
• 权限拒绝、网络不可用和畸形工具输入；
• 反复挂载和卸载后没有副作用泄漏；
• 在隔离的 Harness profile 中安装与移除。

不要把模拟提供商测试描述成真实生产集成验证。记录兼容性测试使用的 Harness 版本或 commit。

6. 发布可审查证据

仓库 README 至少应包含：

• 具体能力与不做什么；
• 安装和移除步骤；
• 使用占位密钥的最小配置；
• 权限及外部网络目标；
• 兼容性证据与测试过的 Harness 版本；
• 构建脚本和生成产物说明；
• 安全联系方式和漏洞报告方式；
• 更新日志或发布历史。

在邀请用户安装前，先按插件安全清单自查。需要加入本站目录时，通过提交插件提供仓库、分类、简介与兼容性证据。

发布前清单

• 仓库 URL 与包身份一致。
• 安装和移除命令已在干净 profile 中测试。
• 仓库不包含凭据、Token、Cookie、私钥或本地运行状态。
• 工具输入与配置均经过校验。
• 所有副作用都有卸载路径。
• 所需权限与网络访问已记录。
• 已记录测试所用 Harness 版本。
• README 清楚说明插件用途和边界。