DeepSeek Harness (DSH) 插件开发权威指南
核心定位声明 本项目是一个用于【开发 DeepSeek Harness (DSH) 插件】的辅助 Agent Skill(纯文本权威开发标准与架构知识库)。
本项目本身是一个 Skill,绝不是 DSH 插件本身! 它的核心目标是辅助开发者、架构师与 AI 智能体快速、零踩坑、高质量地编写、审查、调试各类 DSH / Cordis 插件。
本项目是开发、审查、调试与验收 DeepSeek Harness(DSH)插件与生态扩展的参考知识库(Agent Skill)。本项目自身也属于线索级材料:默认支持最新 DSH 版本(多版本源码见 deepseek-harness)。任何 API、服务挂载名、配置字段和版本行为,都必须再回到目标环境的真实源码与运行时核对后才可使用。证据优先级为运行时行为 > 发布物实现与 JSDoc > 包内 README > 文档站散文 > 本技能库正文。
DSH 是基于 Cordis 微内核构建的高可扩展 Agent Harness。在 DSH 架构中,一切皆为插件 (Everything is a Plugin):会话日志、工具注册表、系统提示词装配、模型适配器、UI 界面以及执行循环驱动器均作为平等、可插拔的插件运行。
一、两条不可协商的工作前置
- 源码至上:读完参考文档只是起点。动手写插件前必须打开目标运行时的真实源码——先查 pnpm 再查 npm、命中即停;本机安装的源码没有混淆,读到了就不必解包桌面版;并能指出每个契约出自哪个包的哪个文件。三层来源、跨平台定位方式与缓存目录约定见 source-verification-and-caches.md。
- 隔离验收:插件完成的标志是在只装了基础插件与目标插件的全新实例上,冷装、热装、热更新、卸载四态全过,并在真实浏览器里逐项点击、回读真值;测试模型必须由用户选定。流程见 isolated-instance-acceptance.md。
二、核心架构原则
- 零特权微内核:不存在固化的特权逻辑。所有业务与平台能力均通过向共享
Context挂载服务或监听事件提供。 - 核心服务大动脉 (The Core Spine):单复数是硬约束——
ctx.sessions、ctx.agents、ctx.agentTeams、ctx.tools为复数;ctx.systemPrompt、ctx.configEditor、ctx.schedule、ctx.planMode、ctx.llm为单数。ctx.agentLoop是唯一的具体循环包(bundle),扩展插件依赖dsh-agent的事件与服务即可。完整 core/seam/bundle 角色矩阵见 services.md。 - 事件派发模式必须分别核对:
emit、waterfall、parallel、serial、bail的等待、短路和返回值语义不同,不能按名称推断。源码级调度算法与isBailed边界见 events.md。 - 配置落点与全量替换规约:
$DSH_HOME/settings.yaml已废弃;四层补丁(组合包 → profile → 全局 →--patch)后层按行胜出;条目config整体替换,不做深合并,改一个字段必须写全该层所需字段。详见 config.md。 - 可逆副作用 (Reversible Effects):所有经
ctx.on()、ctx.effect()、ctx.tools.register()注册的资源由所属 Fiber 跟踪,插件停用或热重载时自动逆向注销。
三、三角色物理架构模型
| 角色 | 运行环境 | 核心职责 | 安全与隔离机制 |
|---|---|---|---|
| Browser | 浏览器 / Desktop Webview | React 界面、浏览器端 Cordis 运行时、Slots 插槽、本地多语言 | 零本地文件系统与系统调用权限,经 Typert Remote(HTTP + Remote 流)交互 |
| Host | 常驻 Node.js 进程 | 核心 Cordis 大动脉服务、工具执行管线、会话日志持久化、Web 服务 | 具备宿主系统权限,管理敏感凭据与单调守卫 |
| 隔离进程(源码中 Worker 专指 worker_threads) | 独立子进程 (Native Runner) | 执行高风险外部命令、隔离沙箱脚本与重计算任务 | 文件效果沙箱(bwrap/Landlock、Seatbelt、Windows ACL),崩溃不影响 Host |
UI 插件必须遵循双面插件 (Dual-Face) 规范:Node 端 lib/index.js,Browser 端 lib/client.js(经 dsh.client 声明、Slots 挂载;loader 行解析到其 package.json 后按该包名判定半侧,子路径行同样适用)。
四、技术参考文档索引 (References)
完整参考目录见 references/README.md,版本核验与变更历史见 CHANGELOG.md。新插件先读其中的通用专题,再按具体需求进入 DSH API 专题;通用专题覆盖依赖、生命周期、发现缓存、双面 UI、补丁与发布、静默失效、跨模块治理、源码核验与隔离验收。每篇专题末尾都有「相关 DSH 源码」清单,列出上游仓库相对路径与版本号,可据此直接打开真实源码。
五、交付前自检
本技能是纯文本规范集,不含脚本、脚手架或示例工程。按 SKILL.md 的路由和交付清单逐项自检:先核对真实服务与版本,再核对插件入口、依赖注入、生命周期、双面插件隔离、构建产物、打包清单和运行时真值,最后在隔离新实例上完成四态安装与浏览器逐项验证。
六、快速开始
# 1. 向目标 profile 添加插件组合包(plugin 子命令必须带 --profile)
dsh plugin --profile <profile> add ./path/to/my-plugin
# 2. 导出并验证合并后的完整配置树
dsh --profile <profile> --dump-config
# 3. 启动 DSH Web 实例
dsh web
# 4. UI 或跨端插件:在真实浏览器中操作后回读接口、磁盘或注册表真值
No comments yet. Be the first to write one.