插件工坊 liyown/dshx

DSHX

构建、检查并发布类型安全的 DeepSeek Harness 插件。

English · 文档 · Framework Hub · 路线图

DSHX 是面向 DeepSeek Harness 仓库外插件的构建期工具链，提供类型安全的 Host/Client authoring、受约束的 Vite 构建、离线诊断、Profile 开发流程和可复现模板。执行、registry、scope、transport、持久化、Prompt assembly、HMR 与 disposer 生命周期仍由官方 DSH/Cordis 管理。

首个可用版本通过 npm 的 preview tag 分发；完成 Preview 验证前，不覆盖现有 latest 开发版本。

创建项目

pnpm create dshx@preview my-plugin
cd my-plugin
pnpm check
pnpm dev

默认生成最小 starter + css-modules：一个 Host Tool 和一个可见 Client Slot。需要完整 Candidate API 示例和可选 Tailwind 时执行：

pnpm create dshx@preview my-plugin --template showcase --style tailwind

模板为 starter | showcase，样式为 css-modules | tailwind | none。Tailwind 使用标准 v4 Vite 插件、dshx: 前缀，并省略 Preflight。

正式参考插件

@becomeopc/dshx-plugin-marketplace 是仓库内的正式自举参考插件。它以普通 DSH bundle 接入「设置 → 插件 → 插件市场」，并完整串联 defineHost、defineSettings、defineApi、defineClient、defineLocale、defineSlot、Standard Schema 校验、useApiQuery、CSS Modules、Profile 安装和 Client HMR。

装进 DSH Profile（保留 @preview 标签——直接写包名仍会解析到旧的、只支持 DSH < 0.2 的版本），或用真实 DSH 开发 Profile 运行：

dsh plugin --profile web add @becomeopc/dshx-plugin-marketplace@preview
pnpm --filter @becomeopc/dshx-plugin-marketplace dev

Authoring 示例

// src/api/status.ts
import { defineApi, method } from "@becomeopc/dshx/api";

export const statusApi = defineApi({
id: "status",
version: 1,
methods: {
get: method<void, { readonly ready: boolean }>(),
},
});

// src/host.ts
import { defineHost } from "@becomeopc/dshx/host";
import { statusApi } from "./api/status.js";

export default defineHost({
apis: [
statusApi.host({
get: () => ({ ready: true }),
}),
],
});

// src/client.tsx
import type {} from "@deepseek-ai/dsh-client-ui-sidebar/client";
import {
defineClient,
defineLocale,
defineSlot,
useApiQuery,
type PropsLocaleOf,
} from "@becomeopc/dshx/client";
import { statusApi } from "./api/status.js";

const copy = defineLocale("my-plugin.status", {
zh: { ready: "就绪", unavailable: "不可用" },
en: { ready: "Ready", unavailable: "Unavailable" },
});

function Status({ t }: PropsLocaleOf<typeof copy>) {
const query = useApiQuery(statusApi, "get", { enabled: true });
if (query.status === "pending") return {query.fetchStatus};
if (query.status === "error")
return Retry;
return {t(query.data.ready ? "ready" : "unavailable")};
}

const statusSlot = defineSlot("sidebar.footer.action", {
id: "my-plugin.status",
order: 0,
locale: copy,
component: Status,
});

export default defineClient({ locales: [copy], slots: [statusSlot] });

defineLocale 推导唯一词条集合、在 Slot 前注册词典，并为组件提供类型安全的 t()。package 仍须在 dsh.client.inject 声明 @deepseek-ai/dsh-client-locale；create-dshx 会生成该 provider edge。最终 tree-shaking 后仍保留的 useApiQuery 会自动声明 connection 能力。

公共入口

| 入口 | 状态 | 用途 |
| @becomeopc/dshx 与 /config | API Candidate | 仅 browser-safe defineConfig 和 DshxConfig |
| /host | API Candidate | Host 定义、Tools、Commands、Prompt contribution |
| /client | API Candidate | Client 定义、Locale、Slots、API/Settings Hooks |
| /api | API Candidate | 共享类型 API contract 与 opaque error |
| /settings | API Candidate | 共享 Schemastery Config schema，由 DSH SettingsForms 投影 |
| /experimental/conversation | Experimental | 纯官方事件生命周期和 React renderer |
| /tooling | Tooling / Experimental | Node-only compiler、兼容、诊断、CLI、repair API |

API Candidate 表示当前 0.2.x 计划保持的 authoring 形状，不是 1.0 稳定承诺。DSH 0.2 的 Settings、Conversation、Connection 与 manifest 变化见从 0.1 迁移到 0.2。

技术文档

| 章节 | API 与行为 |
| Host | defineHost、注册顺序、inject、生命周期 |
| Client、Locale 与 Slot | defineClient、defineLocale、defineSlot、官方 props 与接线 |
| Typed API | Standard Schema、handler、命令式调用、useApiQuery、错误 |
| Settings | contract、Host facet、decoder、secret、Hook 状态与 mutation |
| Prompt | Section、Context、顺序与 assembly ownership |
| Conversation | 实验性 initial/reduce/project/render 生命周期 |
| Build | Vite 插件约束、CSS/资源、Tailwind、declaration、watch |
| Creator | 模板/样式矩阵和 programmatic generation |
| Tooling | programmatic build/watch、兼容、诊断、repair |

另见 CLI 参考、兼容与验证和架构。

Preview 范围与已知限制见 Preview，插件包发布要求见 Publishing。

CLI

dshx check # 离线检查 config、manifest、迁移、兼容、TypeScript dshx check --runtime # 额外要求 Profile、Composition、bridge、runtime readiness dshx build # 先 typecheck，再构建 Host/Client dshx dev # Vite build-watch 加官方 DSH 开发会话 dshx inspect services # 也支持 tools、events、configs dshx add ui --slot --provider <package> --id <id>

除非显式使用 --fix，check 保持只读。build 不改写源码或 Manifest 元数据。inspect 需要受支持且正在运行的 Composition。DSH 0.2 不再提供运行时 Slot catalog，inspect slots 会返回 DSHX3204；add ui 接受显式的 --slot/--provider，并由 dshx check 验证生成结果。完整命令与 JSON 字段见 CLI 参考。

兼容性

当前 protocol-2 adapter 发布 peer range >=0.2.1-rc.2 <0.3.0-0，公开支持范围优先写入 engines.dsh（缺失时回退到 peerDependencies）。真实运行时基线是源码 tag dsh-v0.2.1-rc.2 的构建；当前 npm 0.2.1-rc.2 产物包含过期的 profile-boot 代码，在上游重新发布前按 experimental 处理。本地开发使用一个具体 devDependencies 版本。

Settings 使用官方插件 Config schema 与 ctx.configForms，ConfigForm 身份是 Host profile 的 entry id。Conversation 仍为 Experimental，因为已发布协议没有仓库外 durable event vocabulary registry；它只能使用官方 SessionEventMap 键。

开发本仓库

pnpm install --frozen-lockfile
DSH_SOURCE_ROOT=/path/to/deepseek-harness pnpm check:all

check:all 已包含打包产物与真实 DSH 两套 smoke；指定源码目录后，后者使用已验证的 DSH 构建，而不是过期的 npm 产物。

提交前请阅读贡献指南、依赖政策和安全政策。

许可证

MIT © DSHX contributors.