# 照着 dsh-global-memory 写一个 host + client 双端 DSH 插件

这份指引面向「想给 DeepSeek Harness（DSH）写插件」的开发者：本插件（host 注入 + Agent 工具 + HTTP 路由 + 设置页面板）是一个**最小但完整**的双端样本，照抄结构即可起步。文中所有形态都取自本仓库的真实代码。

## 0. 你需要哪一端

| 你的需求 | host | client |
| --- | --- | --- |
| 改 system prompt / 提供工具 / 提供 HTTP 接口 | ✅ 必需 | — |
| 在设置页或界面上出一块 UI | ✅（提供数据接口） | ✅ 必需 |
| 纯后台逻辑、无界面 | ✅ | — |

host 是 Node 侧（插件包的 `main`），client 是浏览器侧（`exports["./client"]`），两者通过**同源 HTTP** 通信——**不要**试图让 client 直接读文件或 import host 模块，浏览器里没有这些东西。

## 1. 最小文件骨架

```
my-plugin/
├── index.js            # host 入口（必需）
├── lib/                # 你自己的 host 逻辑（示例：store.js / api.js）
├── src/client/index.tsx # client 源码（双端才需要）
├── build.mjs           # 打包 client → lib/client.js
├── lib/client.js       # 构建产物，随仓库提交
├── cordis.patch.yml    # 装配自己（bundle 补丁层）
└── package.json
```

## 2. package.json 元数据约定（最容易漏的一步）

```jsonc
{
  "name": "my-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",                       // host 入口
  "exports": {
    ".": "./index.js",
    "./client": "./lib/client.js",          // ← client 端入口必须导出 "./client"
    "./cordis.patch.yml": "./cordis.patch.yml"
  },
  "engines": { "node": ">=22" },
  "dsh": {
    "client": {                             // ← 有 UI 才需要
      "platform": "web",
      "inject": [                           // client 侧依赖的客户端服务
        "@deepseek-ai/dsh-client-ui-settings",
        "@deepseek-ai/dsh-client-locale"
      ]
    },
    "bundle": { "patch": "./cordis.patch.yml" } // ← 安装时自动应用这个补丁层
  }
}
```

- `exports["./client"]` 与 `dsh.client` 缺任何一个，设置页面板都不会挂载（host 照常工作）。
- `cordis.patch.yml` 里声明自己，安装（把包名加进 profile 的 `dsh.profile.bundles`）后由 bundles 自动应用：

  ```yaml
  - insert:
      - id: my-plugin          # 插件 id（同时是 loader entry id）
        name: my-plugin        # 包名
        config:
          enabled: true        # 自己的装配开关，apply 里读 config.enabled
  ```

## 3. host 侧：三条链路

完整可复制片段见仓库根 [README 的「与宿主 API 的对接点」](../README.md#与宿主-api-的对接点)。要点：

```js
export const name = 'my-plugin'
export const inject = ['systemPrompt'] // 必需服务；缺它插件不激活

export function apply(ctx, config) {
  if (config?.enabled === false) return

  // 注入：注册返回 disposer，交给 ctx.effect 才能在卸载/热重载时撤销
  ctx.effect(() => ctx.systemPrompt.section({ name: 'my-plugin', order: 555, text: '……' }), 'my-plugin: section')

  // 工具、路由：可选服务用 ctx.inject 等就绪，不要同步 get
  ctx.inject(['tools'], (child) => { /* child.get('tools').register({...}) */ })
  ctx.inject(['webServer'], (child) => { /* child.get('webServer').register({ kind:'prefix', path, handler }) */ })
}
```

三条硬规则：

1. **必需服务**写在 `export const inject = [...]`；**可选服务**（可能永远不存在，例如没有 web 服务的 profile）用 `ctx.inject([...], child => …)`，回调里再 `child.get(name)`，并判 `undefined`——服务缺失时插件必须照常可用。
2. **一切注册都包在 `ctx.effect(fn, '标签')` 里**，`fn` 返回撤销函数。否则热重载/卸载会留下残留的 prompt 段、工具或路由。
3. **服务用字符串名取**，可以不 import 任何 `@deepseek-ai/*`。这样包在任何 profile 里都不会因为依赖解析失败而加载不了；代价是字段形状要自己对齐（`tools.register` 只校验 `parameters` + `output.schema` + `output.render`）。

## 4. client 侧：源码约定

client 入口只被宿主消费两个导出：`inject` 与 `apply`（本插件额外导出了 `Panel`、`__internals` 供测试，无副作用）。

```ts
import React from 'react'

const NS = 'my-plugin'
const API = '/my-plugin/api'

// client 侧服务：slots（注册界面）与 locale（i18n）
export const inject = ['slots', 'locale']

export const ZH = { title: '我的插件', save: '保存' }
export const EN = { title: 'My Plugin', save: 'Save' }

export function apply(ctx: any) {
  // i18n 字典：zh 必给，en 缺失时宿主回退 zh
  ctx.effect(() => ctx.locale.register(NS, { zh: ZH, en: EN }), 'my-plugin: locale')
  const bound = typeof ctx.locale.bind === 'function' ? ctx.locale.bind(NS) : null
  const t = (key: string) => (bound && bound(key)) || (ZH as any)[key] || key

  // 注册一块设置页 section
  ctx.effect(
    () =>
      ctx.slots.inject('settings.section', () =>
        ctx.slots.register(
          { name: 'settings.section', id: NS, order: 30, label: () => t('title'), locale: NS, inject: () => ({}) },
          () => React.createElement(Panel, { t }),
        ),
      ),
    'my-plugin: settings section',
  )
}
```

约定与建议：

- `slots.inject(slotName, () => slots.register(定义, 渲染函数))`：`inject` 负责「槽位就绪后再注册」，别绕过它。
- `id` 在同一个 slot 内必须唯一；`order` 决定排序（本插件用 `30`，排在通用设置之后）。
- **样式内联**：用 `<style>` 或行内 `style`，颜色走 CSS 变量（`currentColor` / `inherit`）以便同时适配浅色/深色主题；不要引入外部 CSS 文件，客户端没有静态资源的加载通道。
- **数据全走同源 `fetch`**，相对路径（如 `fetch('/my-plugin/api/state')`），不要拼 host/port。
- 只 import 共享运行时（`react` / `react-dom` / `@deepseek-ai/cordis`）——它们由宿主在运行时注入。

## 5. 打包 client：`window.__ModuleLoader__.load` 包装

`lib/client.js` **不是**普通 bundle，必须是这个包装格式：

```js
// lib/client.js（构建产物，不手改）
window.__ModuleLoader__.load({
  id: 'my-plugin',
  factory: (require) => {
    var module = { exports: {} };
    var exports = module.exports;
    /* ---- esbuild 的 cjs 产物原样嵌在这里 ---- */
    return module.exports;
  },
});
```

- `id` 必须等于包名/插件 id；`factory(require)` 里的 `require` 由宿主注入，只能解析你在 `external` 里声明的共享运行时，**拿不到 Node 内建模块**（`fs`、`path` 一律不可用）。
- esbuild 关键配置（见 `build.mjs`）：

  ```js
  {
    entryPoints: ['src/client/index.tsx'],
    bundle: true,
    format: 'cjs',            // 必须是 cjs：包装里按 module.exports 取导出
    platform: 'browser',
    target: 'es2022',
    jsx: 'automatic',
    external: ['react', 'react/jsx-runtime', 'react-dom', '@deepseek-ai/cordis'],
    minifyWhitespace: true,
    minifySyntax: true,
    minifyIdentifiers: false, // ← 见下方说明，不要开
  }
  ```

- **绝不要 `minify: true` / `minifyIdentifiers: true`**：全量压缩会把顶层标识符改名，注入器的注入前预检正则在产物里找不到 `inject = ['slots', …]` 这个字面量，会误判成「用了 `ctx.slots` 却缺 `inject` 含 `slots`」并**阻断注入**（本插件实测踩过）。
- **绝不把 React 打进产物**：必须 external。打进两份 React 会造成运行时身份冲突，hooks/context 行为错乱。产物体积应远小于 200KB，可作为「有没有误打包运行时」的粗略信号。
- 打包后做产物自查：`__ModuleLoader__.load` 包装存在、`id` 正确、自己的路由前缀与 slot 名字面量存在、`react/jsx-runtime` 仍是 `require(...)`。本插件的 `build.mjs` 就是这么做的，不通过直接 `exit 1`。

## 6. 数据通路：host 前缀路由 ↔ client 相对 fetch

host 侧：

```js
// ctx.inject(['webServer'], child => …) 内
const dispose = webServer.register({ kind: 'prefix', path: '/my-plugin/api', handler })
```

`kind: 'prefix'` 表示「凡是以该 path 开头的请求都交给这个 handler」（本插件的 handler 自己再解析 `/state`、`/text` 等子路径，见 `lib/api.js`）。handler 形态是 Node 的 `(req, res)`：

- 自己设 `res.statusCode` 与 `res.setHeader('content-type', 'application/json; charset=utf-8')`；
- 加 `cache-control: no-store`，避免设置页拿到缓存的旧状态；
- **错误也返回 JSON**，别让客户端收到 HTML（前端 `res.json()` 会解析失败，报错信息变成噪声）；
- 用 `res.end(...)` 收尾。

client 侧据此 `fetch('/my-plugin/api/state')`，同源、无跨域、无需鉴权配置（宿主通常只监听回环地址；若要暴露到网络，必须自己加鉴权层——本插件不提供）。

把 host 的 HTTP 处理写成**不依赖宿主的纯函数**（本插件的 `lib/api.js` 只依赖 `store.js`），就能用假的 `req`/`res` 直接跑单元测试，无需启动宿主。

## 7. 端到端自检清单

装进 profile（`dependencies` 加 `"my-plugin": "link:<路径>"`、`dsh.profile.bundles` 追加 `"my-plugin"`、建 `node_modules` 链接、重启宿主）之后逐条验：

1. **host 加载**：宿主日志出现自己的启动日志（本插件会打印「已加载：注入中，N 字，存储 <路径>」）。
2. **注入生效**：开一个新会话，看 system prompt 里有没有你的段落（或在 index.js 里临时 log 一下注册结果）。
3. **工具可用**：工具列表里能看到你的工具，调用一次拿到预期返回。
4. **HTTP 可用**：`curl -s http://127.0.0.1:<端口>/my-plugin/api/state` 返回 JSON，而不是 HTML 404。
5. **UI 挂载**：设置页出现你的 section，读写一轮，刷新页面状态仍在（说明真源是 host 存储而不是前端内存）。
6. **卸载干净**：卸载后（移除 bundles/依赖 + 删链接 + 重启），你的段落、工具、路由都消失；最好在**重启前**先看一遍 `/my-plugin/api/state` 是否已经 404——这是验证 `ctx.effect` 清理有没有写对的最快方式。
7. **热重载干净**：改 `lib/client.js`（client 侧产物）后重载插件，UI 不应出现两份 section（出现两份说明注册没走 `ctx.effect`，或者注入器没有正确释放旧实例）。

## 8. 踩坑速查

| 症状 | 原因 | 解法 |
| --- | --- | --- |
| 路由恒 404 | apply 时同步 `ctx.get('webServer')`，该服务尚未挂载 | 改用 `ctx.inject(['webServer'], child => …)`，再 `child.get('webServer')` |
| 卸载后 prompt 段/工具/路由残留到重启 | 注册没包在 `ctx.effect` 里，没返回 disposer | 一切注册都交给 `ctx.effect(fn, '标签')` |
| 设置页不出现 | 缺 `exports["./client"]` 或 `dsh.client` | 按第 2 节补齐两个字段 |
| 注入器拒绝注入 | client 产物被全量 minify，`inject = ['slots', …]` 字面量丢失 | `minifyIdentifiers: false`（或整体不开 minify） |
| 前端 hook 报错/状态错乱 | 把 React 打进 bundle | external `react`、`react-dom`、`react/jsx-runtime` |
| client 报 `require is not defined` / `fs not found` | 在浏览器侧代码里用了 Node API | client 只做 UI + 同源 fetch，文件/进程操作留在 host |
| 设置页拿到旧值 | 响应被缓存 | 响应加 `cache-control: no-store` |
| 改完 client 源码没反应 | 忘了重新构建 | 重跑 `npm run build:client`（产物 `lib/client.js` 已提交，但不会自动重建） |
| 会话里看不到注入内容 | 正文为空、`enabled=false`、或必需服务缺失 | 检查存储字段与宿主日志 |