DeepSeek Harness Tauri 桌面版 | Only 8mb installer, zero environment setup, preset plugins, Windows / macOS / Linux.
该文档已被固定,禁止修改
插件客户端架构规范 (Plugin Client Architecture Protocol)
本规范是 通用软件开发规范与协议 (devlopment.md)[cite: 1] 在 DeepSeek Harness 插件客户端半区(Browser Runtime) 的具象化工程落地协议。所有插件的
src/client实现必须严格遵循本规范。 姊妹协议:插件宿主端架构规范 (plugin.host.md)[cite: 2] 与 插件宿主端领域服务协议 (plugin.host.service.md)。两端共享 SSOT、零无用中间层与单向依赖流哲学[cite: 2],但客户端使用 React 与浏览器生命周期词汇表。
一、 核心架构原则
- 唯一事实来源 (SSOT)
- UI 读取的可变共享状态只能存放在
store/modules/<domain>.ts(defineStore定义)[cite: 1]。 - 禁止在
service//register// 组件中持有模块级可变状态。跨调用留存数据必须进入 store 或defineRegister的 controller 闭包。
- 零无用中间层
src/client/index.ts只做装配,不放状态、监听、初始化或请求[cite: 2]。- 严禁建立纯转发的 barrel;
service/与utils/按文件名直接引用[cite: 2]。 - 禁止薄别名:业务层必须直接调用
apis/函数,不得建立改名转发函数。
- 彻底删除与零包袱
- 彻底删除旧注册写法、过渡包装与兼容 re-export[cite: 2];重命名与搬迁统一使用
git mv[cite: 1, 2]。 - 注册函数统一使用
register*前缀,**不保留install***。
- 单向依赖流
- 依赖严格自上而下流动,严禁跨层反向依赖或同级环状引用[cite: 2]:
$$\text{client/index.ts} \longrightarrow \begin{bmatrix} \text{register/} \ \text{hooks/} \ \text{components/} \end{bmatrix} \longrightarrow \text{service/} \longrightarrow \begin{bmatrix} \text{apis/} \ \text{store/} \end{bmatrix} \longrightarrow \text{dsh-tauri/client}$$
apis/不得导入store/**,utils/不得导入任何上层目录**[cite: 1]。
- 生命周期声明式收敛
- 副作用统一由
defineRegister的controller托管(订阅、timeout、interval、observe、listen)[cite: 1]。 - 禁止裸写
setTimeout/setInterval/addEventListener/new MutationObserver等原生副作用[cite: 1]。命令式白名单写法需标注// keep:effect <原因>[cite: 1]。
二、 目录结构与决策树
每个插件的 src/client 必须严格遵循以下职责边界[cite: 1, 2]:
| 目录/文件 | 职责说明 | 关键约束 |
|---|---|---|
index.ts |
装配入口 | 仅平铺装配 feature 与样式(<40 行),无业务逻辑与初始化请求[cite: 2]。 |
constants/ |
静态常量 | 声明 slot 名、注册 ID、storage key、排序权重;跨 half 常量放 src/shared/[cite: 2]。 |
types/ |
类型定义 | 导出跨文件共享的 interface / type,纯类型无实现[cite: 2]。单一模块专属的类型不入此目录,而是与所属模块同目录同名,命名为 <module>.types.ts(如 components/sidebar.types.ts、store/modules/settings.types.ts);此目录仅保留被多个模块共享的类型。 |
locales/ |
本地化字典 | 纯词典定义与 defineLocale 导出,无业务代码。 |
apis/ |
HTTP 出口 | 唯一允许发请求的层。由 dsh-h3/genapi 根据 host/server/index.ts 生成请求函数及 DTO,路径、body、query 与服务端注册一致。 |
store/ |
状态管理 | 包含 index.ts(纯聚合)与 modules/<domain>.ts(一领域一文件,包含 state 与同步 actions)[cite: 1]。 |
register/ |
副作用注册 | 唯一允许登记副作用的层。使用 defineRegister 处理槽位、订阅、观察者与 DOM 补丁[cite: 1]。 |
service/ |
领域服务 | 包含 Query(fetch*/load*)与 Action(领域动作)原型,无副作用生命周期。 |
hooks/ |
React 组合 | 跨组件复用的 Hook(含参数化 useStore 订阅封装)[cite: 1]。 |
components/ |
纯 UI 组件 | 一组件一文件;通用控件从 dsh-tauri-ui 取用(其样式用 tv),包内业务组件直接写 Tailwind className;仅读 store、发命令[cite: 1]。 |
styles/ |
全局样式 | 唯一允许 .cssr.ts 的地方:无组件面的全局样式树,仅导出 CNode 对象。 |
config/ |
只读配置 | 存放静态默认值与初始化标志,严禁存放可变状态[cite: 2]。 |
utils/ |
纯工具函数 | 无状态纯函数,不得认识业务概念,不得导入 store//service//register/[cite: 1, 2]。单一模块专属的工具与所属模块同目录同名,命名为 <module>.utils.ts;此目录仅保留被多个模块共享的纯工具(如 style.ts)。 |
落点决策树:
- 可变且驱动渲染?→
store/;只读配置/常量?→config/或constants/[cite: 1]。 - 发送网络请求?→
apis/(裸请求)或service/(业务编排)。 - 跨多次事件存活(订阅/定时器/DOM观察)?→
register/;仅纯逻辑调度?→service/[cite: 1]。 - 仅在 React 渲染周期内使用?→
hooks/;返回 JSX?→components/[cite: 1]。 - 纯数据处理且脱离业务概念?→
utils/[cite: 1]。 - 类型/工具只服务于单一模块?→ 与该模块同目录同名:
<module>.types.ts/<module>.utils.ts;被多个模块共享?→ 才落入types/、utils/。
三、 各层通用实现规范
1. 装配入口 (src/client/index.ts)
- 平铺调用
ctx.effect(feature, LABEL)与ctx.slots.register(),禁止内联回调 >2 行,禁止启动期异步请求[cite: 2]。 - effect 标签不得硬编码字符串:按 plugin.baisc.md 的《通用协议:常量归属》决定落点——多消费方进
constants/(如LOCALE_EFFECT),单一消费方留在消费方文件[cite: 2]。
2. 状态层 (store/)
- 导出标识符匹配文件名驼峰化(如
worktree.ts$\rightarrow$worktree)。 - 使用
defineStore({ state, actions }):state存数据,actions仅做同步状态迁移[cite: 1]。禁止请求与try/catch。 - 缺席态必须使用模块级常量以保障引用稳定;内容投影至 store 时必须比较值而非引用。
- 禁止建立转发层:外部直接使用
store.<domain>.<field>、useStore(store.<domain>)或store.<domain>.<action>()。严禁自造select*/use*State/patch*等单行转发函数。 store/index.ts仅导出聚合对象;参数化 selector 一律落入utils/并显式接收 state[cite: 1]。
3. 领域服务层 (service/)
只允许以下两种函数原型,签名统一为 (input: X) => Promise<R>:
- Query:只读数据并更新 store,使用
fetch*/load*前缀,返回Promise<Data>。 - Action:响应用户意图并更新 store,使用领域动词(
create/attach/checkout),返回Promise<{ ok: boolean, error?: string }>。
约束:无模块级可变状态,无副作用生命周期(不得调用 setTimeout/subscribe),乐观更新与失败回滚必须在同一个 Action 内完成[cite: 1]。
4. 注册层 (register/)
- 一个 feature 一个文件,导出
export const <feature> = defineRegister(...)。 - 资源必须通过
controller.add()/observe()/interval()/timeout()/listen()托管,彻底避免手动清理[cite: 1]。 - 长流程必须显式检查
controller.isDisposed()。代码超过 150 行时,必须将纯状态机逻辑下沉至service/。 - 内核能力差异一律经适配层:
defineRegister第三个参数adapter(由defineAdapter(ctx)创建)只读能力探测面(adapter.has('sessions.list')、adapter.sessions、adapter.workspaces),按 plugin.baisc.md 的退级阶梯择路,不猜核心版本号、不写死槽名。 - DOM 补丁归属于
register/(不设dom/目录),观察器与事件必须经由 controller 托管,选择器仅允许使用稳定属性(aria-label、role、插件前缀 class)。
5. API 层 (apis/)
- 唯一允许发请求的层。JSON 请求使用
dsh-tauri/client导出的ofetch(与既有fetch为同一 JSON 实例,不是流式传输);严禁使用axios或window.fetch。 apis/index.ts与apis/index.type.ts由根目录genapi.config.ts使用dsh-h3/genapi从host/server/index.ts生成,修改服务契约后运行pnpm genapi,禁止手改生成结果或恢复genapi.pipeline.ts。插件路径统一为/api/tauri/<插件短名>(如/api/tauri/remote/machines),生成类型与消费方按新路径同步,不建立旧 URL 或 DTO 名别名。- 请求函数名使用
HTTP动词 + 路径领域名词,通过根配置的 transform/patch 保持必要的既有操作名;body/query 必须传入生成函数对应参数,不能误当请求 options。业务类型可从生成响应的成功分支派生,保留真实错误联合,不复制另一套 DTO。 - 保持现有 JSON 传输:插件生成文件使用
dsh-tauri/client的ofetch与 type-onlyFetchOptions;桌面壳 SSH 的src/apis/remote.ts使用./http的 invoke 适配,不改用浏览器原生 fetch。
6. UI 与样式 (components/, styles/, hooks/)
- 组件全小写 kebab-case,仅读 store 和调用 service,禁止直接修改 store 或发网络请求[cite: 1]。
- 资源化优先
dsh-tauri-ui:通用控件(按钮、图标按钮、chip、tag、开关、复选框、下拉菜单、输入、分段控件、面板容器)与图标一律从dsh-tauri-ui/client取用;严禁在包内自建同名通用组件,也严禁直接 import 官方@deepseek-ai/dsh-client-ui-primitives(官方组件的跨内核版本差异由dsh-tauri-ui统一吸收)。缺什么就补进dsh-tauri-ui的组件层,不在消费包里各写一份。 - 包内
components/只保留业务组件与包专属布局样式;任何可能被第二个包复用的组件,上提到dsh-tauri-ui。 - 样式选型按「通用 / 业务」二分:
- 通用控件一律用
tv(tailwind-variants)+ Tailwind 工具类:变体即类型(VariantProps推导,禁止手写变体/尺寸类型),多部件用slots,条件态用布尔变体与compoundSlots。 - 业务组件直接写
className:一次性布局与配色不建 variant 层、不抽象tv。 - 颜色优先用
tailwind.plugins.config.js已登记的语义 token(text-primary、bg-layer-1、border-border-l3、shadow-focus-ring);未登记的官方变量才回退任意值bg-[var(--dsw-*)]。新增主题键必须同步该配置文件。 - 新写的工具类只有在插件 Tailwind 产物里存在才生效——产物是
dsh-tauri-ui的src/client/styles/index.ts(由scripts/taiwindcss.ts消费同目录index.css、扫描packages/*/src生成、lightningcss 压缩后内嵌,并由dsh-tauri-ui自己mountStyle);dev 下 watcher 自动重生成,提交前跑pnpm build:taiwindcss;漏生成不会报错,只是静默无样式。 - 叠加同类工具类必须消歧:Tailwind 里同属性谁生效由产物顺序决定,不由 className 里的先后决定。
bg-transparent font-normal这类「基础态」不要与条件类同列叠加(bg-transparent在产物里更靠后,会盖掉条件分支的bg-[…]);手写className用cn()(dsh-tauri/client转出的 tailwind-merge)合并,或三元整段互换;tv内部已走 merge,无需额外处理。 - 禁止用
font简写:[font:inherit]是 shorthand,会把同列text-[13px]的font-size一起重置(产物里 arbitrary property 排在字号工具类之后 → 字号变大)。要继承字体只写[font-family:inherit]。
- 通用控件一律用
.cssr.ts仅用于全局样式(styles/下的公共样式树,如global.cssr.ts):组件级样式一律不进 cssr;只导出CNode,挂载统一通过mountStyle/register/styles.ts[cite: 1]。- Hook 命名为
use-<thing>.ts,优先复用@reause/core原语(如useIntervalFn)[cite: 1]。
7. 依赖与本地化 (locales/, 依赖关系)
- 使用
defineLocale(PLUGIN_ID, { zh, en })声明语言包,通过ctx.effect(locale.registerLocale, LOCALE_EFFECT)安装。 - 禁止自建 locale store、
let activeLocale或在 DOM 选择器中使用文案[cite: 1]。通用动词直接复用common命名空间。 - 依赖隔离:第三方库(
unstorage/ofetch/valtio-define/@reause/core/lodash-es)统一由dsh-tauri/client转出,严禁插件直接 import;需要白名单外的lodash-es方法时,先补进packages/dsh-tauri/src/client/modules/lodash-es.ts。
四、 客户端封闭原型总表
| 原型 | 宏 / 落点 | 动词白名单 / 结构 | 状态持有 | 副作用权限 |
|---|---|---|---|---|
| Store | defineStore @ store/modules/<domain>.ts |
state + actions(同步迁移) |
持有(唯一真值)[cite: 1] | 严禁[cite: 1] |
| Query / Action | 纯函数 @ service/<domain>.ts |
Query: fetch*/load* |
Action: 领域动词 | 严禁模块级 | 严禁[cite: 1] |
| Feature | defineRegister @ register/<feature>.ts | controller.add/observe/interval/timeout/listen | 允许闭包状态 | 唯一合法持有者[cite: 1] |
禁止出现的违规形态:
service/下出现.tsx文件或handle*/*Manager命名。- 根目录放置功能文件或设立独立的
dom/目录。 - 建立仅有转发作用的
index.ts或 store 访问代理函数(如select*/use*State)。 - 插件直接 import 第三方工具库或在各包中自建 locale 管理器。
五、 重构与质量自检清单
- 装配精简:
client/index.ts<40 行,无逻辑内联与启动期异步请求[cite: 2]。 - 状态收口:模块级可变状态(Map/Set/let)已全部收拢至 store 或 controller 闭包[cite: 1]。
- Store 纯度:
store/modules/*.ts仅有state与同步actions;store/index.ts仅做聚合导出,无转发函数[cite: 1]。 - 服务原型:
service/函数严格划分为 Query 与 Action 原型,无副作用 API[cite: 1]。 - 副作用收敛:无裸写原生定时器、DOM 观察器或事件监听,全部由 controller 托管[cite: 1]。
- 注册层薄度:
register/*.ts仅做登记编排,>150 行的代码已将逻辑下沉至service/。 - 请求纯度:所有网络请求集中于
apis/,JSON 请求统一使用dsh-tauri/client的 JSON 实例ofetch/fetch,不把该实例作为流式传输。 - 依赖与本地化:无第三方库直接 import;本地化统一采用
defineLocale[cite: 1]。 - 类型/工具归属:单一模块专属的类型/工具是否与所属模块同目录同名(
<module>.types.ts/<module>.utils.ts),types/、utils/是否只留真正跨模块共享的文件? - 零无意义封装:不存在
function f(x) { return lodashFn(x) }这类纯转调包装;手写处理逻辑(裁剪、比较、排序、去重、取值、判空)一律改用dsh-tauri/client转出的lodash-es。 - 组件资源化:通用控件与图标全部来自
dsh-tauri-ui/client,包内无重复实现、无对官方@deepseek-ai/dsh-client-ui-primitives的直连 import。 - 工程校验:
pnpm --filter <pkg> typecheck/lint/test/build全部通过[cite: 2]。