openharness-rule-for-dsh-plugin

Readme

# openharness-rule-for-dsh-plugin

一个 DeepSeek Harness（dsh）插件：往**系统提示词**注入「DSH 插件开发规范」——四类规则：
能做什么（CAN）/ 应该做什么（SHOULD）/ 不能做什么（MUST NOT）/ 不应该做什么（SHOULD NOT）。
并在 dsh **设置页侧边栏**显示「插件开发规范」一项。

- 纯 dsh plugin（bundle），装在 web profile 即可生效；
- host 半：`ctx.systemPrompt.section({ name, order: 46, text })` 注入规范（真实逻辑）；
- client 半：注册 `settings.section` 槽，显示侧边栏项（写法与已发布的公开插件 `openharness-reply-in-cn` 完全同构，仅 `id`/`label` 不同）。

> **对使用者**：注入的规范正文是**自包含、环境无关**的——只引用官方公开入口（官方 skill `cordis-plugin-development`、官方文档、postmortem 等），**不依赖作者的本地目录或私有资料**。任何安装此插件的人都能读到同样明确、可执行的规则。正文结尾附了一小段「探索参考线索」，列出已发布到 npm 的开源 dsh 插件，仅供喜欢深挖的实现者可选参考，并非使用本插件的前提，也不增加任何使用流程。

---

## 注入逻辑（host half，`src/host/index.ts`）

```ts
export const inject = ['systemPrompt']              // 申报依赖，否则 boot 崩
export const name = 'openharness-rule-for-dsh-plugin'
export function apply(ctx, config) {
  if (config?.enabled === false) return             // 可通过 patch 关闭
  const disposer = ctx.systemPrompt.section({
    name: 'openharness:rule-for-dsh-plugin',
    order: 46,                                      // persona(0) 之后、工具引导(100+)之前
    text: (context) => (context.agent === undefined ? '' : <规范正文>),
  })
  return () => disposer?.()   // apply 返回 disposer，卸载时清理
}
```

- 取 `order:46`，落在 persona（0）之后、工具引导 section（100+）之前，与同层级的其它已安装 section 互不影响。
- 规则正文本体是一个字符串数组 `ruleText`，含 CAN / SHOULD / MUST NOT / SHOULD NOT 四段 + 结尾「探索参考线索」。
- 正文已**自包含、环境无关**：只引用官方公开入口，不指向任何本地目录/私有资料，任何使用者读到都同样有效；参考插件仅在其结尾作为可选学习线索列出。
- 只有真实 agent 装配（`context.agent` 存在）才渲染，不污染非 agent 的 assemble 调用。

**遵循程度**：这是**软约束**。注入**一定发生**（官方装配按 order 拼接、当前 profile 无 `complete` 段覆盖），但「模型是否严格遵守」无法 100% 保证——靠 order 靠前 + 措辞「最高优先级」尽量稳住。

**验证注入是否生效**：在对话框直接问「系统提示里有没有『DSH 插件开发规范：能做什么/不能做什么』这条」——模型能复述即注入成功。

---

## 侧边栏项（client half，`src/client/index.ts`）

```ts
slots.inject('settings.section', () => slots.register(
  { name: 'settings.section', id: 'openharness-rule-for-dsh-plugin', order: 20, label: () => '插件开发规范' },
  Section,
))
```

- `settings.section` 是 **list 槽**：多个插件同时注册不冲突、都会显示（与 中文回复/ADHDGoFly/OpenHarness Reader 并列）。
- client 结构与 `openharness-reply-in-cn` 同样式（同构写法，该插件已发布为公开 npm 包），只是 `id`/`label` 不同。

---

## ⚠️ 必读：为什么代码对了却不显示（缓存/进程坑，2026-08 真实教训）

这是调试中最隐蔽的坑之一（安装任何 DSH client 插件后漏看新项的最常见原因）。现象：**两个 client bundle 结构完全一致、都进了 boot 图、rev 也更新了，但新加的侧边栏项就是看不到。**

**根因**：
- Tauri 壳（OpenHarness）的「重启 DSH」按钮只杀**后端 node 进程**并重新 spawn，**不会重建前端 webview、不让页面重新加载**。
- dsh 的 client bundle 按 `rev`（内容哈希）缓存在 **webview 内存**里；后端重启、`rev` 变后，webview 仍用旧的，拿不到新插件/新 bundle。
- 所以反复按「重启DSH」看不到新插件项——**不是代码问题，是 webview 没刷新**。

**正确做法**：
1. 改 client / 加新 client 插件后，不要只按「重启DSH」。
2. **彻底退出 OpenHarness（⌘Q）再重开**，或手动刷新/重载 dsh 页面——让 webview 重新请求 `client.js?rev=<新>`。
3. 判断「代码问题 vs 缓存问题」：`lib/client.js` 结构是否与已验证的一致 + boot 图是否引用它 + `rev` 是否更新 → 三者都对却看不到 → **先彻底重启 webview 再看**。

---

## 安装

```sh
# 当前依赖目录（开发）：
dsh plugin --profile web add ./openharness-rule-for-dsh-plugin
# 或发布后按名装：
dsh plugin --profile web add openharness-rule-for-dsh-plugin
```

装完**彻底退出 app 重开**（见上文缓存坑）。

---

## 依赖与构建

```sh
pnpm install   # 生成 node_modules（含 esbuild / typescript）
pnpm build     # 产出 lib/index.js（host）+ lib/client.js（client）
```

`package.json`：
- `dsh.bundle.patch: ./cordis.patch.yml`（插入插件行）
- `dsh.client.platform: "web"`（声明 client 半）
- `exports["./client"] → lib/client.js`（浏览器 bundle）
- `main → lib/index.js`（host）

---

## 文件结构

```
openharness-rule-for-dsh-plugin/
├── src/host/index.ts      # 注入「插件开发规范」system-prompt section（order 46）
├── src/client/index.ts    # 注册 settings.section 侧边栏项「插件开发规范」
├── build.mjs              # esbuild 双半打包
├── package.json           # dsh bundle + client 声明 + exports
├── cordis.patch.yml       # 插入插件行
└── tsconfig.json
```

---

## 我开发的 DSH 插件

我（zuoguyoupan2023）开发维护的一系列 DeepSeek Harness（dsh）插件，均可按需通过 `dsh plugin --profile web add <name>` 安装：

| 插件 | 作用 | GitHub 仓库 | 安装 |
|---|---|---|---|
| **adhdgofly-dsh-ext** | DSH Web 界面词性高亮（名绿/动红/形紫/其他灰） | [zuoguyoupan2023/adhdgofly-dsh-ext](https://github.com/zuoguyoupan2023/adhdgofly-dsh-ext) | `dsh plugin --profile web add adhdgofly-dsh-ext` |
| **openharness-reader** | 工作区文件浏览/编辑 + Markdown 预览 | [zuoguyoupan2023/openharness-reader](https://github.com/zuoguyoupan2023/openharness-reader) | `dsh plugin --profile web add openharness-reader` |
| **openharness-reply-in-cn** | 强制模型用简体中文回复，侧边栏「中文回复」项 | [zuoguyoupan2023/openharness-reply-in-cn](https://github.com/zuoguyoupan2023/openharness-reply-in-cn) | `dsh plugin --profile web add openharness-reply-in-cn` |
| **openharness-rule-for-dsh-plugin** | 注入 DSH 插件开发的 CAN/SHOULD/MUST NOT 规范，侧边栏「插件开发规范」项 | [zuoguyoupan2023/openharness-rule-for-dsh-plugin](https://github.com/zuoguyoupan2023/openharness-rule-for-dsh-plugin) | `dsh plugin --profile web add openharness-rule-for-dsh-plugin` |

> 上表中的插件均已发布为**公开 npm 包**，也就对应了注入规范正文结尾的「探索参考线索」。它们是**可选的实现参考**，供喜欢深挖的开发者查看结构；本插件本身的使用并不依赖它们，也不要求你安装它们。

### 对使用者：一份自包含的参考索引

本插件的目的是让任何 dsh 插件开发者（不依赖作者的本地资料）都能得到可执行的最佳实践。因此规范正文与本文档只引用**官方、公开**的入口：

- 官方 skill `cordis-plugin-development`（随官方 `cordis` agent preset 分发的开发 skill，不属顶层内置 skill 库）：<https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/config/agent-presets/cordis/skills/cordis-plugin-development/SKILL.md>；
- 官方用户文档（bundle 教程）：<https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md>；
- 系统提示词子系统：<https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/system-prompt/README.md> 与 <https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/system-prompt.md>；
- 官方 postmortem（默认导出丢 inject）：<https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/postmortem/0001-acp-default-export-drops-inject.md>；
- 排查工具：`@deepseek-ai/dsh-tool-cordis` 的 `cordis_inspect`（精确读某个槽/服务）。

这些入口都托管在公开仓库 `deepseek-ai/deepseek-harness`（master 分支）中，上面的链接可直接点开核对；正文中的规范即可据此一一对应，不必自己搜索定位。