DeepSeek Harness Tauri 桌面版 | Only 8mb installer, zero environment setup, preset plugins, Windows / macOS / Linux.
该文档已固定,禁止修改。
插件宿主端架构规范 (Plugin Host Architecture Protocol)
本规范为 devlopment.md 在 DeepSeek Harness 插件宿主端(Node Runtime) 的落地协议。插件
src/host实现必须严格遵守本规范。 服务层细则见:plugin.host.service.md(定义宏、动词白名单与签名铁律)。
一、 核心架构原则
- 唯一事实来源 (SSOT):运行期内存单例(防抖队列、在途任务映射、会话标记等)必须统一由
config/runtime.ts导出。严禁参数层层透传可变状态。 - 零无用中间层:
apply.ts只做装配接线,不写业务逻辑;禁止为 2~3 个文件建立纯转发的index.ts;临时数据转换必须就地处理。 - 彻底删除与零包袱:彻底清理废弃逻辑、兼容层与存根代码,严禁保留
legacy/compat文件。文件移动/重命名统一使用git mv。 - 单向依赖流:
$$\text{apply.ts (装配)} \longrightarrow \begin{bmatrix} \text{server/routes/} \ \text{tools/} \ \text{events/} \ \text{prompts/} \end{bmatrix} \longrightarrow \text{service/ (业务领域)} \longrightarrow \begin{bmatrix} \text{storage/} \ \text{utils/} \end{bmatrix}$$
二、 目录结构与规范
各插件 src/host/ 物理落点定义如下:
| 目录/文件 | 职责说明 | 关键约束 |
|---|---|---|
apply.ts |
装配入口 | 仅做声明式组装(工具/事件/提示词/路由),控制在 30~50 行以内,不含业务逻辑。 |
config/ |
配置与运行状态 | runtime.ts: 仅保存业务内存状态及 reset/dispose,不保存宿主 Context;没有业务状态时删除该文件。 |
constants.ts: 静态常量与配置,严禁硬编码 Magic Number/String;只登记两个及以上模块消费的常量(单一消费方的常量归属见 plugin.baisc.md 的《通用协议:常量归属》),config/ 下不允许出现 *.types.ts。 |
| types/ | 类型定义 | 导出领域模型、DTO、输入输出接口(纯类型定义)。单一模块专属的类型与所属模块同目录同名,命名为 <module>.types.ts(如 service/worktree.types.ts);此目录仅保留被多个模块共享的类型(如 index.ts)——跨模块共享的宿主面类型(SessionHost / PanelExtensionHost 等)统一放 types/index.ts。 |
| storage/ | 持久化实例 | index.ts 纯粹导出持久化驱动实例,不包含任何业务读写逻辑。 |
| server/ | HTTP 服务层 (可选) | index.ts 使用 dsh-h3 的 defineWebServer 声明服务,routes/ 保存 H3 handler。handler 文件按 URL 层级与方法落位(如 server/routes/session/open/path/post.ts),不根据文件名自动注册路由;URL 与方法以 server/index.ts 的显式注册为唯一依据,仅做协议解析、DTO 校验与 Service 调用。入口以 app.post('/api/tauri/<插件短名>/session/open/path', handler) 等直接注册完整字面量,禁止路径常量、拼接与自造路由宏。 |
| tools/ | Agent 工具层 (可选) | 单工具单文件,包含声明、JSON Schema 与 execute 编排。 |
| prompts/ | 系统提示词层 (可选) | 拆分为常驻提示词 (*-section.ts) 与动态单次上下文注入 (*-context.ts)。 |
| events/ | 事件监听层 (可选) | 宿主生命周期事件处理(如 turn/end、工具前置拦截等)。 |
| service/ | 领域服务层 | 领域服务使用 defineService,统一承接业务 storage 读写与宿主能力访问;共享请求中间件属于基础设施例外。 |
| utils/ | 底层工具纯函数 | 纯粹、无状态,不包含业务上下文与契约宏。返回标准操作结果 { ok: boolean, ... }。单一模块专属的工具与所属模块同目录同名,命名为 <module>.utils.ts;此目录仅保留被多个模块共享的纯函数(如 git.ts、paths.ts)。 |
三、 结构范例 (dsh-tauri-worktree)
packages/dsh-tauri-worktree/src/host/
├── apply.ts # 平铺装配器
├── config/ (runtime.ts | constants.ts)
├── types/index.ts # 仅跨多模块共享类型;单模块专属类型与其模块同目录同名
├── storage/index.ts # 仅导出 storage 实例
├── server/
│ ├── index.ts # defineWebServer + 原生 app 方法注册
│ └── routes/ # handler 文件;URL 与方法由 index.ts 显式注册
├── tools/ # Agent 工具定义 (create-worktree.ts, checkout-worktree.ts)
├── prompts/ # 提示词注入 (worktree-section.ts, checkout-context.ts)
├── events/ # 事件监听 (session-event.ts, tools-execute.ts)
├── service/ # 业务领域服务 (文件名 = 导出标识符)
│ ├── worktree.ts # 领域编排 (create/checkout/attach)
│ ├── ledger.ts # 持久化 <Binding> (load/save/remove/list)
│ ├── cleaner.ts # 长任务调度 (start/lookup/unsettled)
│ └── session-context.ts # 只读推演 (resolve/peek)
└── utils/ # 仅跨多模块共享纯函数 (git.ts, filesystem.ts);单模块专属工具与其模块同目录同名
四、 核心层实现细则
1. 装配总线 (apply.ts)
- 仅包含声明式注册 (
ctx.tools.register()、ctx.on()、ctx.systemPrompt.*()、ctx.effect())。 - 超过 2 行的回调必须抽离至
events/或prompts/。禁止创建全局deps对象透传。
import { server } from './server'
export function apply(ctx: HostContext): void {
ctx.effect(() => server(ctx), 'plugin: routes')
ctx.tools.register(createWorktreeTool())
ctx.tools.register(checkoutWorktreeTool())
ctx.on('session/event', (session, event) => handleSessionEvent(session, event))
ctx.on('tools/execute', (exec, next) => handleToolsExecute(exec, next))
ctx.systemPrompt.context(checkoutContextProvider)
ctx.systemPrompt.section(worktreeSectionProvider)
}
2. 配置与状态层 (config/)
dsh-h3基线为0.2.1,Context 泛型由上游原生支持:import { getServerContext, getServerOptions } from 'dsh-h3/utils'。runtime.ts仅导出业务内存状态及清除/销毁函数;Context 与服务配置由dsh-h3管理,禁止重新实现defineHostRuntime、宿主 set/get 槽或路由依赖副本。server(ctx, options)返回的 disposer 必须由ctx.effect托管。server必须先于依赖它的恢复任务、事件监听及服务调用激活;服务内从dsh-h3/utils导入getServerContext和getServerOptions,使用原生getServerContext<HostContext>(server);激活前和卸载后不得读取 Context。请求内的实例配置使用getServerOptions<Options>(event),禁止在dsh-tauri重导出或另建泛型兼容层。
3. 持久化层 (storage/)
storage/index.ts仅负责创建并导出驱动实例(如createStorage({ driver: fsAtomicDriver(...) }))。- 禁止在
storage/目录下编写业务增删改查,存取逻辑统一收拢于service/对应的持久化服务中。
4. 业务领域服务层 (service/)
- 统一使用
dsh-tauri的defineService宏声明,禁止自造宏。 server/routes/、tools/、events/、prompts/不直接执行业务宿主操作或读写storage,必须通过领域服务访问;路由读取实例配置与共享安全中间件检查请求来源不属于业务穿透。
5. 服务与路由形态 (server/index.ts、server/routes/)
- 原生服务入口:
export const server = defineWebServer<Options>((app) => { ... }),无配置时省略泛型。共享安全检查在入口统一app.use(guard),业务 handler 不重复鉴权。精确路由不经过官方/api前缀闸门;桌面gate放行登录 401 不代表取消 Host/Origin 的 403。 - 统一命名空间:插件 API 使用
/api/tauri/<插件短名>,例如dsh-tauri-rightclick对应/api/tauri/rightclick;包名与注册标识不变。根资源不强加末尾斜杠,不保留旧路径别名。服务注册、生成客户端、Rust 桥接白名单与 SSE 订阅必须同步。 - 默认 RESTful 资源化:URL 只描述资源,动作由 HTTP 方法承担。文件按方法命名(
get.ts、post.ts、put.ts、delete.ts),同一资源的多个方法在server/index.ts使用app.get/post/put/delete分别注册;不恢复defineRoutes或原共享 routes 实现。 - 方法与请求体契约:沿用 H3/dsh-h3 原生方法处理,GET 包含 HEAD,未注册 OPTIONS 时返回 405;不恢复
desktopPreflight或固定MAX_REQUEST_BODY_BYTES。业务输入仍必须校验。 - 动作端点例外:无法表达为资源状态迁移的操作,允许
POST /<资源>/<动作>(/tasks/toggle、/tasks/run、/skills/refresh、/import/apply、/mcp/check、/restart等)。动作名必须是动词性领域词,且不得与标准方法语义重复;能用方法表达的写入一律不许写成动作端点。 - 禁止:用动作后缀表达 CRUD(
/create、/update、/delete、/save、/remove)——一律改为标准方法 + 资源路径;同一(method, path)不得重复声明。
6. API 生成契约
- 使用根目录
genapi.config.ts的dsh-h3/genapi与既有 ofetch preset,输入为host/server/index.ts,输出为客户端apis/index.ts和apis/index.type.ts;禁止恢复本地genapi.pipeline.ts或手写同一套生成逻辑。 - 注册必须使用直接的
app.get/post/...调用与静态完整路径,不能通过动态循环、路径拼接或注册 helper 隐藏。handler 中的getQuery<Query>(event)、readBody<Body>(event)必须位于 handler 本体,不能藏在嵌套回调内;只用as Query不足以声明生成契约。 - 响应类型须可 JSON 序列化并由 handler 推导或显式声明。若为
defineEventHandler指定 request 泛型,必须同时保证 response 不退化成 unknown;服务返回值、错误分支与客户端类型须一致。
五、 自检清单 (Checklist)
- 装配精简:
apply.ts是否仅包含声明式注册(无逻辑内联/过度嵌套)? - 状态收口:内存 Map/Set 是否收拢于
config/runtime.ts?是否存在参数击穿透传? - 服务约束:领域服务是否使用
defineService(共享请求中间件除外)?文件名与导出标识符是否一致?方法名是否为该领域的动作动词且全仓无同义词混用? - 签名收口:领域服务参数是否按需声明且不含
ctx/host(载体gate.attach除外)?是否仅领域服务内部使用getServerContext<HostContext>(server),且无独立宿主槽? - 路由纯度:
server/routes/是否仅负责协议解析与 DTO 校验?无直接操作storage/宿主对象/系统命令行为? - 路由形态:URL 是否为资源路径 + 标准方法(方法命名文件);动作端点是否仅限
POST /<资源>/<动作>,且路径里没有/create、/update、/delete、/save、/remove这类 CRUD 动作后缀? - 存储抽象:
storage/index.ts是否仅导出驱动实例? - 工具解耦:
utils/是否无状态、脱离业务上下文且未引入契约宏? - 类型/工具归属:单一模块专属的类型/工具是否与所属模块同目录同名(
<module>.types.ts/<module>.utils.ts),types/、utils/是否只留真正跨模块共享的文件? - 常量归属:
config/constants.ts是否只剩多消费方常量,单一消费方的常量是否已直接定义在消费方文件(import 之后、不导出)? - 彻底清理:废弃代码/兼容层/无用
index.ts是否已清理?重命名是否使用git mv? - 工程校验:
pnpm --filter <pkg> typecheck与test是否全绿通过?