插件开发指南 Wenaixi/dsh-plugin-dev

DeepSeek Harness (DSH) 插件开发权威指南

核心定位声明本项目是一个用于【开发 DeepSeek Harness (DSH) 插件】的辅助 Agent Skill（纯文本权威开发标准与架构知识库）。
本项目本身是一个 Skill，绝不是 DSH 插件本身！ 它的核心目标是辅助开发者、架构师与 AI 智能体快速、零踩坑、高质量地编写、审查、调试各类 DSH / Cordis 插件。

本项目是开发、审查、调试与验收 DeepSeek Harness（DSH）插件与生态扩展的参考知识库（Agent Skill）。本项目自身也属于线索级材料：任何 API、服务挂载名、配置字段和版本行为，都必须再回到目标环境的真实源码与运行时核对后才可使用。证据优先级为运行时行为 > 发布物实现与 JSDoc > 包内 README > 文档站散文 > 本技能库正文。

DSH 基于 Cordis 微内核构建，是高度可扩展的 Agent Harness。在 DSH 架构中，一切皆为插件 (Everything is a Plugin)：会话日志、工具注册表、系统提示词装配、模型适配器、UI 界面以及执行循环驱动器，都作为平等、可插拔的插件运行。

一、两条不可协商的工作前置

1. 源码至上：读完参考文档只是起点。动手写插件前必须打开目标运行时的真实源码——先查 pnpm 再查 npm、命中即停；本机安装的源码没有混淆，读到了就不必解包桌面版；并能指出每个契约出自哪个包的哪个文件。三层来源、跨平台定位方式与缓存目录约定见 source-verification-and-caches.md。
2. 隔离验收：插件完成的标志是在只装了基础插件与目标插件的全新实例上，冷装、热装、热更新、卸载四态全过，并在真实浏览器里逐项点击、回读真值；测试模型必须由用户选定。流程见 isolated-instance-acceptance.md。

二、核心架构原则

1. 零特权微内核：不存在固化的特权逻辑。所有业务与平台能力，都通过向共享 Context 挂载服务或监听事件来提供。
2. 核心服务大动脉 (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。
3. 事件派发模式必须分别核对：emit、waterfall、parallel、serial、bail 的等待、短路和返回值语义各不相同，不能按名称推断。源码级调度算法与 isBailed 边界见 events.md。
4. 配置落点与全量替换规约：$DSH_HOME/settings.yaml 已废弃；四层补丁（组合包 → profile → 全局 → --patch）后层按行胜出；条目 config 整体替换，不做深合并，改一个字段必须写全该层所需字段。详见 config.md。
5. 可逆副作用 (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。新插件先读其中的通用专题，再按具体需求进入 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 或跨端插件：在真实浏览器中操作后回读接口、磁盘或注册表真值