dsh-custom-mode 1.9.18 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ # 双语配对一致性记录:两侧在「上次确认一致」时的 git blob 哈希。
2
+ # 两份文档权威相同——改完任意一侧,请把另一侧也改掉,然后重新记录:
3
+ # node tools/verify-translation-pairing.mjs --write
4
+ README.md: abc63086044c1e6eef27959da5b97d100b72b825
5
+ README.zh.md: 425b733e7415ee451b7dcc176fde40f397495298
package/README.md CHANGED
@@ -1,79 +1,411 @@
1
1
  # dsh-custom-mode
2
2
 
3
+ English | [中文](README.zh.md)
4
+
5
+ **DeepSeek Harness (dsh) custom mode plugin** — edit a mode's system prompt, base mode and plugin switches in
6
+ the settings page, and keep several assistants side by side (multi-mode / multi-persona, coding, chat or
7
+ role-play). · **中文**:DeepSeek Harness(dsh)自定义模式插件 —— 在设置页编辑系统提示词、选择基础模式、逐行
8
+ 开关插件,可并存多个助手(多模式 / 多角色扮演 RP)。
9
+
3
10
  ![dsh-custom-mode — a settings page for dsh agent modes](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/header.png)
4
11
 
12
+ <!-- community badge row: required in every new repository (see the storefront template in the operator SOP/DSH Plugins folder) -->
13
+
5
14
  [![npm](https://img.shields.io/npm/v/dsh-custom-mode?label=npm&style=flat-square&logo=npm&logoColor=white&labelColor=1f2430)](https://www.npmjs.com/package/dsh-custom-mode) [![CI](https://img.shields.io/github/actions/workflow/status/BOWLUNA/dsh-custom-mode/test.yml?label=CI&style=flat-square&logo=githubactions&logoColor=white&labelColor=1f2430)](https://github.com/BOWLUNA/dsh-custom-mode/actions/workflows/test.yml) [![license](https://img.shields.io/badge/license-MIT-97ca00?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=1f2430)](LICENSE) [![dsh](https://img.shields.io/badge/dsh-%E2%89%A50.1.5--rc.2-4d6bfe?style=flat-square&logo=deepseek&logoColor=white&labelColor=1f2430)](https://github.com/BOWLUNA/dsh-custom-mode#readme)
6
15
 
7
16
  <!-- badge rows: same two-part structure (dark label + coloured value) in both rows; every new repo copies this block -->
8
17
  [![bilibili](https://img.shields.io/badge/bilibili-videos-%2300A1D6?style=flat-square&logo=bilibili&logoColor=white&labelColor=1f2430)](https://b23.tv/qJ4Ev0W) [![Douyin](https://img.shields.io/badge/Douyin-shorts-%23FE2C55?style=flat-square&logo=tiktok&logoColor=white&labelColor=1f2430)](https://v.douyin.com/VWh0M03Fa4Y/) [![RedNote](https://img.shields.io/badge/RedNote-notes-%23FF2442?style=flat-square&logo=xiaohongshu&logoColor=white&labelColor=1f2430)](https://xhslink.cn/o/A7QtXmePBBF) [![Discord](https://img.shields.io/badge/Discord-chat-%235865F2?style=flat-square&logo=discord&logoColor=white&labelColor=1f2430)](https://discord.gg/pz97SfAfSy) [![GitHub](https://img.shields.io/github/discussions/BOWLUNA/dsh-custom-mode?label=GitHub&style=flat-square&logo=github&logoColor=white&labelColor=1f2430)](https://github.com/BOWLUNA/dsh-custom-mode/discussions)
9
18
 
10
- <!-- community badge row: required in every new repository (see the storefront template in the operator SOP/DSH Plugins folder) -->
19
+ A custom mode for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh). Its
20
+ system prompt is a plain file you can edit on the Web settings page, and an edit takes effect on the
21
+ **next model step** — no restart, no new session.
11
22
 
12
- The **settings-page half** of [dsh-custom-mode](https://github.com/BOWLUNA/dsh-custom-mode) — a Web UI for
13
- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) agent modes: choose a mode's base
14
- composition, toggle the plugin rows it mounts, and edit its **system prompt**, which is a plain file the
15
- agent loop re-reads before every model step — **a save applies on the next step, with no restart and no new
16
- session**. Several modes ("assistants") live side by side, each with its own prompt.
23
+ In one line: **a settings page for dsh agent modes** — choose a mode's base composition, toggle the plugin
24
+ rows it mounts, and edit its system prompt, which the agent loop re-reads before every model step. Several
25
+ modes ("assistants") can live side by side, each with its own prompt.
17
26
 
18
- Searched for as: custom mode · custom prompt · system-prompt editor · multi-mode / several assistants ·
19
- multi-agent · roleplay (RP) / chat personas ·
20
- 自定义模式 · 自定义提示词 · 多助手/多模式 · 角色扮演/聊天人格(RP).
27
+ Also searched for as: custom mode · custom prompt · system-prompt editor · multi-mode / several assistants ·
28
+ multi-agent · roleplay (RP) / chat personas.
21
29
 
22
- ![Assistant manager](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/05-assistant-manager.png)
30
+ **Two dsh lines are supported: the newest line and the previous stable** — both checked on every push,
31
+ neither merely claimed. npm's `latest` and `next` have both pointed at `0.2.0-rc.2` since 2026-09-29, so
32
+ "latest stable" and "latest preview" are one release now; the second leg stays because most installs in
33
+ the field are still on `0.1.7-rc.2`:
34
+
35
+ | dsh | role | status |
36
+ | --- | --- | --- |
37
+ | `0.2.0-rc.2` | **newest line** — npm's `latest` *and* `next`, and the line the official desktop app ships (it is version-locked to dsh) | ✅ CI (ubuntu node 20/24 + **windows**) + a real instance: install, composition and the seeded preset verified on this line (the full render gate runs here) |
38
+ | `0.1.7-rc.2` | previous stable — still inside the declared range, and what most existing installs run | ✅ CI + a real instance: verified rendered on this line since 1.9.15 |
23
39
 
24
- ![Mode name and base mode](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/01-mode-switch.png)
40
+ Older builds (`0.1.5-rc.3`, `0.1.6-alpha.*`) use the same mechanisms and remain inside the declared peer
41
+ range, but they no longer get a CI leg of their own.
25
42
 
26
- ![Plugin switches](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/02-plugin-switches.png)
43
+ The four official modes (`standard` / `ptc` / `minimal` / `cordis`) are untouched.
27
44
 
28
- ![System prompt](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/03-system-prompt.png)
45
+ | | |
46
+ | --- | --- |
47
+ | ![Mode name and base mode](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/01-mode-switch.png) | ![Plugin switches](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/02-plugin-switches.png) |
48
+ | ![System prompt](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/03-system-prompt.png) | ![Mode picker](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/04-preset-picker.png) |
29
49
 
30
- ![Mode picker](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/04-preset-picker.png)
50
+ The assistant manager, cropped to its own section. All five images are English, **all exactly 800x800**, and
51
+ shot on a throwaway `DSH_HOME` with no sessions by `tools/screenshots/shoot-fresh.mjs` (the rendered page
52
+ is what `tools/browser-verify.mjs` checks):
53
+
54
+ ![Assistant manager](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/05-assistant-manager.png)
31
55
 
32
56
  ## Install
33
57
 
58
+ One command installs everything — the settings-page plugin, and the preset it seeds on first
59
+ activation:
60
+
61
+ ```sh
62
+ dsh plugin --profile web add dsh-custom-mode@1.10.0 # pin the version to get this one for sure
63
+ # A bare `add dsh-custom-mode` is subject to pnpm's release cooldown (`minimumReleaseAge`, 1 day by
64
+ # default): for hours after a release it can silently install an OLDER version — measured: a bare
65
+ # install 38 minutes after 1.3.0 shipped landed on 1.0.3. Check what you got with `npm ls
66
+ # dsh-custom-mode` inside the profile, or pin the version as above.
67
+ ```
68
+
69
+ Restart dsh afterwards, then choose「自定义模式」for a new session. The preset is written to
70
+ `$DSH_HOME/.agent-presets/custom/`; anything already there is left alone, so a `prompt.md` you wrote
71
+ yourself is never overwritten.
72
+
73
+ **Platforms**: the suite runs on every push under Ubuntu (Node 20 and 24) **and Windows (Node 24)** — the
74
+ Windows job exists because that platform has its own failure modes (MSYS paths in `install.sh`, `rename`
75
+ locking under concurrent saves, platform expressions evaluating the other way). Both shell scripts work in
76
+ any POSIX shell, Git Bash included.
77
+
78
+ ### Installing from the interface (no terminal)
79
+
80
+ From dsh `0.1.6-alpha.2` there is a Plugins page: **sidebar → Plugins → Add plugin**. It takes three
81
+ kinds of input, and all three work here:
82
+
83
+ | Input | What to paste |
84
+ | --- | --- |
85
+ | **Package name** | `dsh-custom-mode` |
86
+ | **GitHub repository URL** | `https://github.com/BOWLUNA/dsh-custom-mode` (the repository root) |
87
+ | **Local plugin directory** | `<your clone>` — the repository root, which *is* the package |
88
+
89
+ There is also an **in-app market** for browsing the whole ecosystem: install `dshmarket`
90
+ (`dsh plugin --profile web add dshmarket`), open **Settings → Plugin Market** and search
91
+ `dsh-custom-mode` — its cards read the `engines.dsh` range this plugin declares, and the curated shots
92
+ listed in the repository's `screenshots.json` (five images; they are the same `docs/images/*.png`
93
+ files the README shows, so each picture exists once).
94
+
95
+ All three work because the repository's **root `package.json` is the published package**: `dsh.bundle`,
96
+ `main` and `exports["./client"]` are declared there, so an npm install and a GitHub-URL install fetch
97
+ the same files. Before 1.10.0 this repository carried two manifests — a `private: true` wrapper at the
98
+ root plus `editor/package.json` — and that is what made third-party catalogues render the plugin as
99
+ `dsh-custom-mode#editor` and what made dshfind-derived cards read the wrapper's `private: true` and
100
+ report "not published to npm". One manifest at the root, and `test/manifests.test.mjs` keeps it that way.
101
+
102
+ ### On the desktop app
103
+
104
+ The desktop application is part of dsh itself (`apps/desktop`), version-locked to it — Electron and
105
+ `@deepseek-ai/dsh` always carry the same exact version — and it is **the complete Web application in an
106
+ Electron shell**, so this plugin's page renders there unchanged. One install path, and it is the one above:
107
+
108
+ - **Install from inside the app**: sidebar → **Plugins** → add plugin → search `dsh-custom-mode`.
109
+ The app runs the shared plugin manager with its own bundled pnpm.
110
+ - **Do not try to use the CLI for it — dsh itself refuses** (measured on 0.1.7-rc.2):
111
+ ```
112
+ $ dsh plugin --profile desktop add .
113
+ error: profile "desktop" is managed exclusively by the Electron application
114
+ ```
115
+ The desktop owns `$DSH_HOME/profiles/desktop`: package operations there hold a profile transaction lock
116
+ and startup recovery renames `cordis.patch.yml`. `install.sh` therefore **refuses** `--profile desktop`
117
+ too and points you at the app, so the two agree instead of one silently working around the other.
118
+ (A lab simulation of the profile shape can override it with `DSH_ALLOW_DESKTOP_PROFILE=1`.)
119
+ - **Nothing else to do on the preset side**: `$DSH_HOME/.agent-presets/` is product data shared by the
120
+ desktop app and the CLI, and the preset is seeded by the plugin on first activation.
121
+ - If a third-party bundle ever keeps the app from starting, the native recovery dialog offers
122
+ **Disable third-party plugins**; installed packages and the plugin's own data stay on disk.
123
+
124
+ **Compatibility is declared, not assumed.** dsh checks every plugin's
125
+ `peerDependencies["@deepseek-ai/dsh"]` against the running runtime (prereleases included), and since
126
+ 0.2.0 that check is an **installation gate**, not a warning: a range that does not cover the runtime
127
+ means `dsh plugin add` refuses the package outright
128
+ (`installation rejected: Plugin … is incompatible with dsh 0.2.0-rc.2`). The declared range therefore
129
+ *is* the support statement, which is why it moves only after the new line has been installed and tested
130
+ — a range that "probably" works is exactly the kind of claim that turns into a support ticket.
131
+
132
+ To keep the sources around as well — or to install without npm — clone and run the script, which does
133
+ the same two things explicitly:
134
+
34
135
  ```sh
35
- dsh plugin --profile web add dsh-custom-mode
136
+ git clone https://github.com/BOWLUNA/dsh-custom-mode
137
+ cd dsh-custom-mode
138
+ ./install.sh # copies preset/ into $DSH_HOME/.agent-presets/custom/ and installs the plugin
139
+ ./uninstall.sh # removes the plugin; keeps your prompt unless you pass --purge
36
140
  ```
37
141
 
38
- **That one command is the whole install.** The package carries the agent preset, and the host half writes it
39
- into `$DSH_HOME/.agent-presets/` on first activation — filling in only what is missing, so a `prompt.md` you
40
- wrote yourself is never overwritten.
142
+ The mode needs a profile that ships `agent-presets` — the `web` profile does, `tui` and `headless` do
143
+ not.
144
+
145
+ ## Usage
146
+
147
+ The settings page (Settings → "Custom mode") is an **assistant manager**: the top of the page lists
148
+ every custom mode you have — create, switch, delete — and the four blocks below (name, base mode,
149
+ plugin switches, system prompt) edit **whichever one is selected**.
150
+
151
+ - **Ordering** — "Move up / Move down" writes the order into each assistant's `preset.yml` (`order`,
152
+ the roster's own sort key), so it survives a restart and the new-session picker follows it.
153
+ - **Import / export a prompt** — "Export prompt" saves the current text as a `.md`; "Import prompt"
154
+ reads a file into the **editor** (nothing is written until you save), so an import goes through the
155
+ same `{{…}}` validation as anything typed.
156
+ - **Asking the agent to change its own prompt requires your approval.** The in-session `custom_prompt`
157
+ tool goes through the platform's approval seam (`tools/pre-execute` returning `ask`), so the request waits
158
+ for an explicit「允许一次」and shows what would be written and where. Measured: with the `ask` approval
159
+ policy the panel appears and approving really writes; with `never` (full access) nothing prompts and the
160
+ call is **denied**. The worst case is therefore "the change does not happen", never "it happened quietly".
161
+ - **配置了却不生效会被点名** — the page warns when a setting cannot take effect: the「身份(系统提示词)」
162
+ row is off while `prompt.md` still has content (so your prompt is silently ignored), the `custom_prompt`
163
+ tool row is off, the assistant has no name or no description (the picker shows the bare id /「暂无描述」).
164
+ - **The agent can change its own prompt, with your approval** — the in-session `custom_prompt` tool reads the
165
+ prompt, replaces it, or **appends** to it. Appending matters because it never has to *reproduce* the whole
166
+ prompt: an agent that wants to remember one rule cannot lose existing content on the way (measured: it may
167
+ still read first to see what it is adding to). Both writing actions go through the platform's approval panel
168
+ first.
169
+ - **Change history** — every save, *and* any change made outside this page (the in-session
170
+ `custom_prompt` tool, a hand edit of `prompt.md`), leaves a version in the history list under the
171
+ prompt box, labelled with when and where it came from. Loading one only edits the draft: nothing is
172
+ written until you save, so browsing old versions cannot destroy the current one. Before this, a prompt
173
+ changed from inside a session was invisible — the page only ever showed "the current text".
174
+ - **Reset to the factory prompt** — one click puts the **shipped template** (the text a new assistant
175
+ starts from) back into the editor. It is draft-only like every other edit: nothing is written until
176
+ you save, and Reload discards it. Before this existed, a prompt you had edited into a corner could
177
+ only be recovered by deleting the assistant and creating it again.
178
+ - **New assistant** — type a name and click "New assistant". It is seeded from the packaged template:
179
+ the full Standard row set plus a starter prompt, selectable in a new session as soon as you save it —
180
+ **in an already-open page the picker's list is a load-time snapshot, so refresh (F5) once to see a new
181
+ assistant there** (measured; the roster itself is up to date).
182
+ - **Duplicate** — copies the selected assistant's prompt, base mode and row switches into a new one;
183
+ the two are independent afterwards.
184
+ - **Each assistant is independent** — its prompt, base mode and row switches are its own; changing one
185
+ leaves the others alone.
186
+ - **Base mode is the row set, not the prompt** — it decides which rows exist and which tools the mode has;
187
+ this plugin always replaces the base's `persona` row with its own reader (`complete: false`), so the
188
+ base's *prompt* semantics are **not** inherited. Minimal is the visible case: you get minimal's tool set,
189
+ not minimal's prompt.
190
+ - **Switching assistants never discards drafts** — each keeps its own unsaved edits, marked
191
+ "Unsaved" in the list; the only path that throws edits away is the reload button, which renames
192
+ itself to say so.
193
+ - **Delete** — a confirmation, then the plugin does the removal itself. Which confirmation depends on the
194
+ line: when the shell hands a third-party client plugin its `RiskConfirmation` atom you get the shell's own
195
+ dialog with a tick-box; on `0.1.7-rc.2` the client seed table only exposes `Button/Input/Switch/Tag/Pill`,
196
+ so it degrades to a native `confirm` (same guardrail, one prompt instead of a dialog). Removal works on both
197
+ lines: `0.1.6` and older have `agentPresets.remove()`, while `0.1.7`+ has no such call at all — there the
198
+ plugin disposes its own registration and removes the directory. It only removes the mode directory from disk:
199
+ **sessions already using it keep running** (their composition was read when they started), and new sessions
200
+ no longer offer it.
201
+ - **Ask the agent** — every assistant ships a `custom_prompt` tool, so a session can read or rewrite
202
+ **its own** prompt.
203
+ - **Edit the file** — `$DSH_HOME/.agent-presets/<assistant id>/prompt.md` is that assistant's single
204
+ source of truth.
205
+
206
+ Only `{{model}}`, `{{cwd}}` and `{{provider}}` are interpolated. An unknown `{{…}}` is rejected when
207
+ saved: the renderer throws on it, which would fail every request in that mode.
208
+
209
+ Every control (buttons, inputs, switches, tags, the confirmation dialog, icons) comes from the
210
+ shell's own `@deepseek-ai/dsh-client-ui-primitives`, so theme, light/dark and future restyling reach
211
+ this page automatically; a shell that does not provide those atoms falls back to built-in plain
212
+ controls with the same behaviour.
213
+
214
+ An "assistant" is **one directory** under the user preset root (default `$DSH_HOME/.agent-presets/`),
215
+ and its directory name is its internal id. The page manages only **presets this tool created** — the
216
+ test is that the directory carries `prompt.md` and that its composition injects identity through
217
+ `prompt-reader.mjs`. Any other hand-authored preset is neither listed nor touched: the page
218
+ regenerates a composition from a base mode, and doing that to a hand-written one would destroy it.
219
+
220
+ ### How this differs from the built-in Plugins page
221
+
222
+ From dsh `0.1.6-alpha.2` the harness ships a Plugins page that can enable and disable plugins live.
223
+ It and this mode's per-row switches act at **different levels**:
224
+
225
+ | | Built-in Plugins page | This mode's per-row switches |
226
+ | --- | --- | --- |
227
+ | Scope | **The whole profile** — what this machine has installed | **One agent mode** — which rows its composition mounts |
228
+ | Typical use | Turn a plugin off globally | Keep Standard fully loaded and trim this mode to what it needs |
41
229
 
42
- To keep the source around as well, clone the repository and run `./install.sh` instead; it does the same two
43
- things explicitly, and `./uninstall.sh` undoes them (keeping your prompt unless you pass `--purge`).
230
+ They coexist: the harness decides what the machine has, this mode decides which of it the mode uses.
44
231
 
45
- The mode is **web-profile only**: `agent-presets`, the service that mounts presets at all, ships with dsh's
46
- `web` profile. In `tui` / `headless` this package activates but registers nothing.
232
+ The boundary is **drawn by upstream**: the Plugins page documents that it manages "the profile's bundles
233
+ and their uniquely addressable rows", and states plainly that **agent-preset rows remain read-only**.
234
+ The preset layer is therefore out of its reach — and that is exactly the layer this mode covers.
47
235
 
48
- ## Requirements
236
+ A demonstrable example: `tool-plugin-manager` (the agent-facing install/toggle tool) ships **off in
237
+ Standard and PTC** — only Creator enables it. The official modes give you no way to change that; here
238
+ you flip one switch.
49
239
 
50
- - **dsh `>=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0`**(两条线:最新正式版 `0.1.5-rc.3` 与最新预览版 `0.1.7-rc.2`;更早的 `0.1.6-alpha.*` 与正式版同一套机制,仍在范围内但不单独测)** — declared in `engines.dsh` and as an *optional* peer range. This package never
51
- imports `@deepseek-ai/dsh`; it only reads the host services dsh injects.
52
- - **No build step, no dependencies**: the source is published as-is and uses only Node's standard library.
53
- - The package version is its own line (`1.0.0`, `1.0.1`, …). Which dsh it supports is declared in
54
- `engines.dsh`; see the repository README's "Versioning" section.
240
+ ## How it works
241
+
242
+ dsh normally takes the system prompt from a preset's YAML, and `@deepseek-ai/dsh-persona` resolves its
243
+ `prefix` once at mount. This preset registers the same `deployment:persona-prefix` section but makes
244
+ its `text` a **function**, which the agent loop calls before every model step.
245
+
246
+ Two different things therefore decide when a change lands:
247
+
248
+ - **Prompt text** is re-read per step, so an edit applies to the **running** session immediately.
249
+ - **Switches and base mode** rewrite the composition file. `agent-presets` remounts a preset when that
250
+ file's `mtimeMs` and `size` change, so a **new session** picks them up; a running session keeps the
251
+ configuration it started with, which is deliberate — swapping a tool set mid-conversation would be wrong.
252
+
253
+ Row switches are tri-state. A row you never touched stays byte-identical to the shipped one, including
254
+ its `!!js` platform condition and its shipped `disabled` state; an explicit on/off replaces that
255
+ condition with a boolean. Platform expressions are evaluated on the host, so the page shows the state
256
+ actually in force on this machine rather than whether a key exists.
257
+
258
+ Several assistants need no new mechanism: `dsh-agent-presets` already scans **every** directory under
259
+ the user preset root, and re-reads those roots on each roster call, so a directory created just now is
260
+ selectable the next time a session is started. Each assistant's `prompt-reader.mjs` / `prompt-tool.mjs`
261
+ resolves `prompt.md` relative to **its own module location**, so N copies are N independent prompts.
262
+ Creation seeds the packaged template; deletion goes through the platform's `agentPresets.remove()` where it
263
+ exists and through the plugin's own dispose-and-remove path where it does not (0.1.7+),
264
+ which refuses a shipped preset and re-checks that the directory really lives under the writable root.
265
+
266
+ ## Versioning
267
+
268
+ The package version is its **own line** — `1.0.0`, then `1.0.1`, … It does not mirror the DSH release.
269
+ What this plugin supports is declared in `engines.dsh` and the `@deepseek-ai/dsh` peer range in
270
+ `package.json`, and `tools/verify-version-consistency.mjs` (run in CI) asserts that the DSH
271
+ version CI installs and tests falls inside those ranges.
272
+
273
+ **Two lines are supported: the newest line (`0.2.0-rc.2`, which npm's `latest` and `next` both point at
274
+ since 2026-09-29, and the line the desktop app ships) and the previous stable (`0.1.7-rc.2` — still inside
275
+ the declared range, and what most existing installs run)** — declared as
276
+ `>=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0` (the extra clauses exist because
277
+ semver only matches a pre-release inside a range that names its own `major.minor.patch`), and CI installs both
278
+ and runs the whole suite against each — the rendered gate runs on the **newest** line, because that is
279
+ where the shell's own UI changes land first.
280
+ **The official desktop app (DeepSeek Harness Desktop) is covered too**: it is version-locked to dsh and now
281
+ ships `0.2.0-rc.2`, i.e. the same combination this matrix pins. Install it from inside the app (sidebar →
282
+ Plugins); the CLI is refused for that profile by dsh itself. On `0.2.0-rc.2` measured (2026-09-30, clean
283
+ throwaway `DSH_HOME`): `dsh plugin --profile web add dsh-custom-mode` resolves the package in 640 ms, the
284
+ composition tree carries the row, boot seeds all five preset files, the declarative registry syncs the
285
+ assistant, and the `agentPresets` capability set is unchanged (`list, register, inventory, select,
286
+ document`).
287
+
288
+ Two reasons for the split. A bare `x.y.z` is what directories and markets require before they will
289
+ auto-install a package — several resolve npm `latest` and reject anything carrying a prerelease tag.
290
+ And a version string was never a checkable claim anyway: the declared range is, and it is the thing
291
+ that goes stale when upstream moves. What decides compatibility in practice is still whether the APIs
292
+ below exist, which is what the ranges are for.
293
+
294
+ <details>
295
+ <summary>Coupling points (check these when upgrading dsh)</summary>
296
+
297
+ | Dependency | Failure if it changes |
298
+ | --- | --- |
299
+ | `ctx.systemPrompt.section()` with a **function** `text` | the prompt stops hot-reloading — the point of the project |
300
+ | `agentPresets` remounts on composition `mtimeMs`+`size` | switches need a process restart to apply |
301
+ | `ctx.tools.register()` | loses the `custom_prompt` tool |
302
+ | `ctx.connection.fetch.register({ path, methods, requestBody, fetch })` | settings page 404s — nothing is registered |
303
+ | `kind: 'prefix'` matching both `path` and `path/…` | only the list opens; `/state`, `/create`, `/delete` all 404 |
304
+ | `agentPresets.list()` rows carrying `id` / `trust` / `path`, with `preset.yml` supplying `name` / `description` | the assistant list is empty or unrecognisable |
305
+ | `agentPresets.remove(id)` (legacy only), refusing `trust: 'system'` | 0.1.7+ deletion no longer needs it — the declarative backend disposes the registration and deletes the directory instead |
306
+ | the `/api` channel's fence (Host/Origin + browser auth) | the page cannot authenticate at all; do **not** "fix" it by moving the route to the raw `webServer` table |
307
+ | `ctx.inject(deps, cb)` (scoped wait) | the row parks in `pending` in profiles without a web server |
308
+ | `dsh.client` + `exports["./client"]`, client bundle id == package name | the browser half is not discovered |
309
+ | `settings.section` slot (`id` / `order` / `label`) | page placement and label |
310
+ | **`settings.section` no longer takes `locale:`** (since 0.1.6-alpha.2) | the shell does not hand over a `t` bound to this namespace; the page carries its own dictionaries as a floor — see ARCHITECTURE §15 |
311
+ | `preset.yml`'s `order` participating in the roster sort | move up/down stops working |
312
+ | `ctx.locale.register/bind` | falls back to Chinese |
313
+ | **where the base composition comes from** — `agentPresets.readDocument(<mode>).content` on 0.1.7+, the `@deepseek-ai/dsh-agent-presets` files before that | the base mode and the plugin switches become read-only (the prompt still saves); see `base-composition.mjs` |
314
+ | shipped layout `<presets>/<id>/agent.cordis.yml` and row text shape | base-mode switching breaks |
315
+ | `!!js` platform expressions | platform rows display the wrong state |
316
+
317
+ </details>
55
318
 
56
319
  ## Documentation
57
320
 
58
- The full documentation is bilingual in the repository:
321
+ - [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — failures reproduced on a real machine, with symptoms, cause and a way out.
322
+ - [`docs/MEASUREMENTS.md`](docs/MEASUREMENTS.md) — the commands and raw output behind each claim.
323
+ - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — why this is two artifacts, and which host APIs it depends on.
324
+ - [`docs/PUBLISHING.md`](docs/PUBLISHING.md) — how the npm package is published.
325
+ - [`AGENTS.md`](AGENTS.md) — agent-facing notes, including the full recipe for verifying the UI in a
326
+ real browser on the lab (`tools/browser-verify.mjs`).
327
+ - [`CHANGELOG.md`](CHANGELOG.md) · [`SECURITY.md`](SECURITY.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md)
328
+
329
+ ## Development
59
330
 
60
- - [README](https://github.com/BOWLUNA/dsh-custom-mode#readme) (English) ·
61
- [中文说明](https://github.com/BOWLUNA/dsh-custom-mode/blob/main/README.zh.md)
62
- - [Troubleshooting](https://github.com/BOWLUNA/dsh-custom-mode/blob/main/docs/TROUBLESHOOTING.md) —
63
- every failure that was actually reproduced, with symptoms, cause and a way out
64
- - [Measurements](https://github.com/BOWLUNA/dsh-custom-mode/blob/main/docs/MEASUREMENTS.md) — the commands
65
- and raw output behind every claim
66
- - [Architecture](https://github.com/BOWLUNA/dsh-custom-mode/blob/main/docs/ARCHITECTURE.md) — why this had
67
- to be two artifacts, and which host APIs it depends on
331
+ ```sh
332
+ node test/run.mjs # 15 suites; resolves the shipped presets itself (0.1.7+ derives them from the host)
333
+ ```
68
334
 
69
- ## Security note
335
+ Edits to `client.js` are hot-swapped by `@deepseek-ai/dsh-client-hmr` about a second later; the
336
+ host half (`index.mjs`, `composition.mjs`, `meta.mjs`, `paths.mjs`) needs a restart. See
337
+ [`test/README.md`](test/README.md) for what each suite protects, and [`CONTRIBUTING.md`](CONTRIBUTING.md)
338
+ before changing behaviour.
70
339
 
71
- The route this package serves runs the platform's own browser-trust check
72
- (`ctx.connection.requestRejection`) before anything else and **fails closed** when that service is
73
- unavailable. Before that check existed, the route could be read and written unauthenticated — see
74
- [SECURITY.md](https://github.com/BOWLUNA/dsh-custom-mode/blob/main/SECURITY.md) for the affected range and
75
- the mitigation.
340
+ ## If it helps
341
+
342
+ A ⭐ on GitHub is what makes a plugin findable in a catalogue of thousands — it costs you nothing and it is
343
+ the whole reason this page keeps getting maintenance. If it is **not** working on your dsh line, open an issue
344
+ with the output of `dsh --version`: that is the fastest path to a fix, and the compatibility table above is
345
+ what came out of the last one.
76
346
 
77
347
  ## License
78
348
 
79
349
  MIT
350
+
351
+ ---
352
+
353
+ ## Built with
354
+
355
+ | | |
356
+ | --- | --- |
357
+ | Model | DeepSeek V4.1 Flash (`deepseek-v4-flash`, provider `deepseek-official`) |
358
+ | Runtime | DeepSeek Harness **0.2.0-rc.2** (newest line) / **0.1.7-rc.2** (previous stable) — the two supported lines; the token figures below are from an earlier `0.1.6-alpha.2` session |
359
+ | Uncached input | 224,058 tok |
360
+ | Cache reads | 125,638,016 tok |
361
+ | Output | 425,539 tok |
362
+
363
+ The whole project, research and dead ends included, cost the DSH client **126,287,613 tokens** at a
364
+ **99.8%** cache hit rate (cache reads ÷ all input, 125,862,074).
365
+
366
+ ### What the review-driven iterations cost
367
+
368
+ Four external reviews turned into releases `1.4.0` … `1.9.0` (the stable-line picker fix, the Windows write
369
+ races, the i18n leaks, the portability fixes, the two UI passes). Measured in the same client:
370
+
371
+ | | |
372
+ | --- | --- |
373
+ | Uncached input | 3,973,904 tok |
374
+ | Cache reads | 711,962,624 tok |
375
+ | Output | 1,559,791 tok |
376
+
377
+ That is **717,496,319 tokens** (3,973,904 + 711,962,624 + 1,559,791) at a **99.4%** cache hit rate
378
+ (711,962,624 ÷ 715,936,528). Counting the first pass as well, the project stands at **843,783,932 tokens**,
379
+ **99.5%** cached (837,600,640 ÷ 841,798,602).
380
+
381
+ ## Updating
382
+
383
+ The plugin lives in the profile's `node_modules` and the platform owns that installation, so updating means
384
+ installing again — your data is not touched:
385
+
386
+ ```sh
387
+ # the pinned form: what you ask for is what you get
388
+ dsh plugin --profile web add dsh-custom-mode@1.10.0
389
+ # then restart the DSH process that serves the web profile
390
+ ```
391
+
392
+ **Do not install by bare name if you want this release.** pnpm applies a release cooldown (`minimumReleaseAge`,
393
+ 24 hours by default) and a bare `dsh plugin add dsh-custom-mode` resolves to *the newest version older than 24
394
+ hours*. Measured on a clean machine while 1.9.0 was latest: the bare command installed **1.0.1**. Pinning the
395
+ version bypasses the cooldown, which is why the command above carries `@`.
396
+
397
+ **How to know what you are running**: the settings page shows the installed version at the bottom (`插件版本`).
398
+ Compare it with `npm view dsh-custom-mode version`.
399
+
400
+ **What an update does not touch**: `$DSH_HOME/.agent-presets/<your assistants>/` — `prompt.md`, `preset.yml` and
401
+ your row switches are yours. Seeding only fills in *missing* files, so a prompt you wrote is never overwritten.
402
+
403
+ **If the base mode and the plugin switches are greyed out with a one-line warning**: this dsh line exposes no
404
+ shipped composition to this plugin (the resolver tried the host's `readDocument()`, the legacy presets package
405
+ and the packaged `dsh-web-app` patch — the host log names each attempt). The system prompt still saves on its
406
+ own; nothing else about the mode is touched. On 0.1.7 that was a hard 500 until 1.9.13.
407
+
408
+ **If a mode stops appearing in the picker after an update**: an assistant created by an older version keeps its
409
+ old composition file, and if that file enables a plugin row this dsh line does not ship, the platform marks the
410
+ whole preset broken and silently drops it while the settings page keeps working. Open the settings page: it says
411
+ so and offers **「Fix for this line」**, which turns exactly those rows off and leaves everything else alone.
package/README.zh.md ADDED
@@ -0,0 +1,316 @@
1
+ # dsh-custom-mode
2
+
3
+ [English](README.md) | 中文
4
+
5
+ **DeepSeek Harness(dsh)自定义模式插件** —— 在设置页编辑系统提示词、选择基础模式、逐行开关插件,可并存多个
6
+ 助手(多模式 / 多角色扮演 RP)。英文关键词:dsh custom mode / custom prompt / system prompt editor /
7
+ base mode / plugin switches / multi-assistant / multi-persona。
8
+
9
+ ![dsh-custom-mode —— 给 dsh 模式用的设置页](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/header.png)
10
+
11
+ <!-- 社区入口:第二排徽章在每个新仓库里都要加(见 SOP/DSH Plugins/仓库门面模板.md) -->
12
+
13
+ [![npm](https://img.shields.io/npm/v/dsh-custom-mode?label=npm&style=flat-square&logo=npm&logoColor=white&labelColor=1f2430)](https://www.npmjs.com/package/dsh-custom-mode) [![CI](https://img.shields.io/github/actions/workflow/status/BOWLUNA/dsh-custom-mode/test.yml?label=CI&style=flat-square&logo=githubactions&logoColor=white&labelColor=1f2430)](https://github.com/BOWLUNA/dsh-custom-mode/actions/workflows/test.yml) [![license](https://img.shields.io/badge/license-MIT-97ca00?style=flat-square&logo=opensourceinitiative&logoColor=white&labelColor=1f2430)](LICENSE) [![dsh](https://img.shields.io/badge/dsh-%E2%89%A50.1.5--rc.2-4d6bfe?style=flat-square&logo=deepseek&logoColor=white&labelColor=1f2430)](https://github.com/BOWLUNA/dsh-custom-mode#readme)
14
+
15
+ <!-- 徽章:两排统一"深色标签 + 彩色值"的两段式;新仓库照抄这一块 -->
16
+ [![bilibili](https://img.shields.io/badge/bilibili-视频-%2300A1D6?style=flat-square&logo=bilibili&logoColor=white&labelColor=1f2430)](https://b23.tv/qJ4Ev0W) [![抖音](https://img.shields.io/badge/抖音-短视频-%23FE2C55?style=flat-square&logo=tiktok&logoColor=white&labelColor=1f2430)](https://v.douyin.com/VWh0M03Fa4Y/) [![小红书](https://img.shields.io/badge/小红书-笔记-%23FF2442?style=flat-square&logo=xiaohongshu&logoColor=white&labelColor=1f2430)](https://xhslink.cn/o/A7QtXmePBBF) [![Discord](https://img.shields.io/badge/Discord-群组-%235865F2?style=flat-square&logo=discord&logoColor=white&labelColor=1f2430)](https://discord.gg/pz97SfAfSy) [![GitHub](https://img.shields.io/github/discussions/BOWLUNA/dsh-custom-mode?label=GitHub&style=flat-square&logo=github&logoColor=white&labelColor=1f2430)](https://github.com/BOWLUNA/dsh-custom-mode/discussions)
17
+
18
+ [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(dsh)用的自定义模式。它的系统提示词是一个普通文件,可以在 Web 设置页里编辑,**改完下一步模型调用即生效** —— 不用重启,也不用新建会话。
19
+
20
+ 一句话:**给 dsh 的 agent 模式用的设置页** —— 选这个模式的基础组成、逐行开关它挂载的插件、并编辑它的系统提示词;提示词每个模型调用前重新读取。可以并存多个模式(「助手」),各自的提示词互不影响。
21
+
22
+ 常见的叫法:自定义模式 · 自定义提示词 · 系统提示词编辑 · 多助手/多模式 · 多个 Agent 模式 ·
23
+ 角色扮演/聊天人格(RP)。
24
+
25
+ **支持两条线:最新线(npm 的 `latest` 与 `next` 自 2026-09-29 起都指向 `0.2.0-rc.2`)与上一个正式版** —— 两条都是每次 push 真跑,不是声明:
26
+
27
+ | dsh | 定位 | 状态 |
28
+ | --- | --- | --- |
29
+ | `0.2.0-rc.2` | **最新线** —— npm 的 `latest` 与 `next` 都指向它,官方桌面端也在这一条线上(与 dsh 同版本号) | ✅ CI(ubuntu node 20/24 + **windows**)+ 真机:这条线上安装、组合树与播种都验过(整道渲染闸门跑在这里)|
30
+ | `0.1.7-rc.2` | 上一个正式版 —— 仍在声明范围内,现役安装大多在它上面 | ✅ CI + 真机:自 1.9.15 起就在这条线上验过渲染 |
31
+
32
+ 更早的线(`0.1.5-rc.3`、`0.1.6-alpha.*`)共用同一套机制,peer 范围仍然接纳,但不再单独占 CI 腿。
33
+
34
+ 官方四个模式(`standard` / `ptc` / `minimal` / `cordis`)不受影响。
35
+
36
+ | | |
37
+ | --- | --- |
38
+ | ![模式名称与基础模式](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/01-mode-switch.png) | ![插件开关](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/02-plugin-switches.png) |
39
+ | ![系统提示词](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/03-system-prompt.png) | ![模式选择器](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/04-preset-picker.png) |
40
+
41
+ 多助手管理器(裁到它自己那一段)。五张图都是英文、**统一 800x800**,由一个**没有会话记录的**一次性
42
+ `DSH_HOME` 拍出,脚本是 `tools/screenshots/shoot-fresh.mjs`(渲染后的页面由 `tools/browser-verify.mjs` 校验):
43
+
44
+ ![助手管理器](https://raw.githubusercontent.com/BOWLUNA/dsh-custom-mode/main/docs/images/05-assistant-manager.png)
45
+
46
+ ## 安装
47
+
48
+ 一条命令装完——设置页插件,以及它在首次激活时自动播种的 preset:
49
+
50
+ ```sh
51
+ dsh plugin --profile web add dsh-custom-mode@1.10.0 # 钉版本才能确定拿到这一版
52
+ # 不带版本号会受 pnpm 的发布冷却期影响(`minimumReleaseAge`,默认一天):发布后数小时内按名安装
53
+ # 可能**静默装到旧版** —— 实测 1.3.0 发布 38 分钟后按名安装装到了 1.0.3。用 profile 里的
54
+ # `npm ls dsh-custom-mode` 核对实际装到的版本,或像上面那样钉版本。
55
+ ```
56
+
57
+ 装完重启 dsh,新建会话时选「自定义模式」。preset 会被写到 `$DSH_HOME/.agent-presets/custom/`;
58
+ **那里已有的文件一律不动**,所以你自己写过的 `prompt.md` 不会被覆盖。
59
+
60
+ **平台**:测试套件每次 push 都在 Ubuntu(Node 20 与 24)**和 Windows(Node 24)**上跑 —— 加 Windows
61
+ 任务是因为那个平台有自己的失败模式(`install.sh` 里的 MSYS 路径、并发保存时 `rename` 的目标锁、平台表达式
62
+ 求值方向相反)。两个 shell 脚本在任何 POSIX shell 下都能用,含 Git Bash。
63
+
64
+ ### 图形界面安装(不用终端)
65
+
66
+ dsh `0.1.6-alpha.2` 起有插件管理页:**侧边栏 → 插件 → 添加插件**。它接受三种输入,本插件对应如下:
67
+
68
+ | 输入 | 填什么 | 说明 |
69
+ | --- | --- | --- |
70
+ | **包名** | `dsh-custom-mode` | 最省事 |
71
+ | **GitHub 仓库地址** | `https://github.com/BOWLUNA/dsh-custom-mode` | 指向**仓库根**即可 |
72
+ | **本地插件目录** | `<你 clone 的路径>` | 就是仓库根 —— 仓库根**本身**就是发布包 |
73
+
74
+ 想逛整个生态还有一个**应用内市场**:装 `dshmarket`(`dsh plugin --profile web add dshmarket`),
75
+ 打开 **设置 → 插件市场**,搜 `dsh-custom-mode` —— 卡片会读本插件声明的 `engines.dsh` 范围,
76
+ 以及仓库里 `screenshots.json` 列出的精选截图(五张;它们就是 README 用的那几张
77
+ `docs/images/*.png`,所以每张图在仓库里只有一份)。
78
+
79
+ 三条都可用,因为**仓库根的 `package.json` 就是发布包**:`dsh.bundle` / `main` /
80
+ `exports["./client"]` 都声明在仓库根,所以 npm 安装与"GitHub 地址"安装拿到的是同一批文件。
81
+ 1.10.0 之前这个仓库有**两份清单**——根部的 `private: true` 包装清单加 `editor/package.json`——
82
+ 那正是第三方目录把本插件显示成 `dsh-custom-mode#editor`、以及 dshfind 这类站点读到包装清单的
83
+ `private: true` 后报"作者尚未发布到 npm"的原因。现在只有根清单一份,`test/manifests.test.mjs` 盯着它不被加回来。
84
+
85
+ ### 桌面端
86
+
87
+ 桌面端就在 dsh 仓库里(`apps/desktop`),**与 dsh 同版本号发布**(Electron 与 `@deepseek-ai/dsh`
88
+ 永远同一个精确版本),而且它就是**套了 Electron 壳的完整 Web 应用** —— 所以本插件的页面在那边原样渲染。
89
+ 安装只有一条路,就是上面那条:
90
+
91
+ - **在应用里装**:侧栏 → **插件** → 添加插件 → 搜 `dsh-custom-mode`。应用自带 pnpm,走的是同一套插件管理器。
92
+ - **不要试着用 CLI 装 —— dsh 自己就会拒绝**(0.1.7-rc.2 实测):
93
+ ```
94
+ $ dsh plugin --profile desktop add .
95
+ error: profile "desktop" is managed exclusively by the Electron application
96
+ ```
97
+ 桌面端独占 `$DSH_HOME/profiles/desktop`:那里的包操作持有 profile 事务锁,启动恢复还会重命名
98
+ `cordis.patch.yml`。所以 `install.sh` 也**拒绝** `--profile desktop` 并指向应用内安装 —— 两边一致,
99
+ 而不是某一方偷偷绕过去。(只想在本机模拟 profile 形状时可设 `DSH_ALLOW_DESKTOP_PROFILE=1`。)
100
+ - **预设那一侧不用做任何事**:`$DSH_HOME/.agent-presets/` 是桌面端与 CLI 共享的产品数据,
101
+ 预设由插件首次激活时落盘。
102
+ - 万一某个第三方 bundle 让应用起不来:原生恢复对话框提供**「禁用第三方插件」**,已安装的包与插件数据都留在磁盘上。
103
+
104
+ **兼容性是声明出来的,不是猜的。** dsh 会拿每个插件的 `peerDependencies["@deepseek-ai/dsh"]` 与运行时
105
+ 版本比对(含预发布版);而且自 0.2.0 起这项检查从"警告"升级成了**安装闸门**:范围不覆盖运行时就
106
+ 直接装不进去(`installation rejected: Plugin … is incompatible with dsh 0.2.0-rc.2`)。所以那个范围
107
+ **就是**支持声明本身,只有在真实安装并测过新线之后才会动——"大概能用"的范围正是会变成支持工单的那种声明。
108
+
109
+ 想同时留下源码(或者不用 npm 安装),就 clone 下来跑脚本,它把同样两件事显式做一遍:
110
+
111
+ ```sh
112
+ git clone https://github.com/BOWLUNA/dsh-custom-mode
113
+ cd dsh-custom-mode
114
+ ./install.sh # 复制 preset/ 到 $DSH_HOME/.agent-presets/custom/,并安装插件
115
+ ./uninstall.sh # 卸载插件;默认保留你的提示词,加 --purge 一并删除
116
+ ```
117
+
118
+ 模式需要带 `agent-presets` 的 profile:`web` 有,`tui` 与 `headless` 没有。
119
+
120
+ ## 使用
121
+
122
+ 设置页(设置 → 「自定义模式」)是一个**助手管理器**:上面列出你所有的自定义模式,可以新增、切换、删除,下面四个区块(模式名称 / 基础模式 / 插件开关 / 系统提示词)编辑的是**当前选中的那一个**。
123
+
124
+ - **排序** —— 选中助手后「上移 / 下移」,顺序写在每个助手的 `preset.yml` 里(`order`,也就是 roster 自己的排序键),所以重启后仍然生效,新建会话的选择器按这个顺序排列。
125
+ - **导入 / 导出提示词** —— 「导出提示词」把当前文本存成 `.md`;「导入提示词」把文件读进**编辑器**(不会直接落盘,仍需点保存),因此导入同样要过 `{{…}}` 校验。
126
+ - **让 agent 改自己的提示词要经过你批准** —— 会话内的 `custom_prompt` 工具走平台的审批缝
127
+ (`tools/pre-execute` 返回 `ask`):请求会停在「等待审批」,面板里写明**要写什么、写到哪**,你点「允许一次」
128
+ 才会执行。实测:审批策略为 `ask` 时弹面板且批准后真的写入;为 `never`(完全权限)时不弹窗、**直接拒绝**。
129
+ 所以最坏情况是"改不成",从不是"悄悄改成了"。
130
+ - **「配置了却不生效」会被点名** —— 设置页会指出那些不生效的配置:「身份(系统提示词)」这一行关着而
131
+ `prompt.md` 还有内容(你写的提示词被静默忽略)、`custom_prompt` 工具行关着、助手没有名字或描述
132
+ (选择器里会显示成裸 id 或「暂无描述」)。
133
+ - **agent 能改自己的提示词,但要你批准** —— 会话内的 `custom_prompt` 工具可以读、整体替换,或者**追加**。
134
+ 追加的意义在于**不必把整段提示词重新写一遍**:想记住一条规则时,不可能因为重写而丢掉已有内容
135
+ (实测:模型可能仍会先读一次,看看自己要加到什么内容后面)。两种写入动作都会先过平台的审批面板。
136
+ - **改动历史** —— 每次保存,以及**在设置页之外**发生的任何改动(会话内的 `custom_prompt` 工具、手工编辑 `prompt.md`),都会在提示词框下面留下一版,并标明时间与来源。载入某一版**只改草稿**:不点保存不会落盘,所以翻旧版本不会毁掉当前这版。在此之前,提示词被会话内改掉是**看不见的** —— 页面永远只显示"当前文本"。
137
+ - **恢复出厂提示词** —— 一键把**出厂模板**(新建助手时得到的那份文本)填回编辑器。它和页面上其它改动一样只改**草稿**:不点保存不会落盘,「重新读取」即可撤销。在此之前,把提示词改坏了只能删掉助手重建。
138
+ - **新增助手** —— 填个名字点「新增助手」。新助手从模板生成:标准模式的全部行 + 一份默认提示词,写好后在新建会话的选择器里就能选到它 —— **已经打开的页面里,选择器的列表是加载时的快照,要看到新助手需刷新一次(F5)**(实测;roster 本身已是最新)。
139
+ - **复制一份** —— 把当前助手的提示词、基础模式、逐行开关整个复制到新助手,之后各改各的。
140
+ - **每个助手各自独立** —— 提示词、基础模式、逐行开关都属于它自己,改一个不影响别的。
141
+ - **基础模式是"行集合",不是提示词** —— 底子决定有哪些行、这个模式有哪些工具;本插件始终把底子的
142
+ `persona` 行替换成自己的读取器(`complete: false`),所以底子的**提示词语义不会被继承**。最明显的是
143
+ 「极简模式」:你拿到的是极简的工具集,不是极简的提示词。
144
+ - **切换助手不会丢草稿** —— 每个助手各自留着未保存的修改,列表上用「未保存」标出来;唯一会放弃修改的是「放弃修改并重新读取」(有草稿时按钮会改名说明)。
145
+ - **删除** —— 先确认,再由插件自己动手删。确认形态取决于这条线:壳把 `RiskConfirmation` 交给第三方客户端插件时,是壳自己的弹窗(需勾选);而 `0.1.7-rc.2` 的客户端种子表只暴露 `Button/Input/Switch/Tag/Pill`,于是退化为原生 `confirm`(护栏不变,少一个勾选框)。删除两条线都能用:`0.1.6` 及更早有 `agentPresets.remove()`,`0.1.7`+ 根本没有这个调用 —— 那里由插件自己注销注册表项并删掉目录。删除只移除磁盘上的模式目录:**正在使用它的会话不受影响**(组成在会话创建时就已读取),新建会话时不再出现。
146
+ - **直接对 agent 说** —— 每个助手都自带 `custom_prompt` 工具,会话里可以读取或改写**它自己**的提示词。
147
+ - **直接改文件** —— `$DSH_HOME/.agent-presets/<助手 id>/prompt.md` 是那个助手的唯一事实来源。
148
+
149
+ 插值变量只有 `{{model}}`、`{{cwd}}`、`{{provider}}`。出现未知的 `{{…}}` 会在保存时被拒绝:渲染器对它抛错,那会让该模式每个请求都失败。
150
+
151
+ 界面控件(按钮、输入框、开关、标签、确认弹窗、图标)全部来自壳自己的
152
+ `@deepseek-ai/dsh-client-ui-primitives`,因此主题、深浅色与后续改版都会自动作用到本页;老壳没有提供这组
153
+ 原子组件时会退回内置的朴素控件,功能不变。
154
+
155
+ 「助手」= 用户预设根目录(默认 `$DSH_HOME/.agent-presets/`)下的**一个目录**,目录名就是它的内部 id。设置页只管理**本工具创建的模式**(判据:目录里有 `prompt.md`,且组成文件用 `prompt-reader.mjs` 注入身份)。手工编写的其它 preset 不会被列进来,更不会被改写 —— 页面会按基础模式重新生成组成文件,对一份手写的组成文件做这件事等于毁掉它。
156
+
157
+ ### 与官方「插件管理」页的分工
158
+
159
+ dsh `0.1.6-alpha.2` 起自带了插件管理页,可以实时启用/停用插件。它和本模式的逐行开关**管的是不同层级**:
160
+
161
+ | | 官方插件管理页 | 本模式的逐行开关 |
162
+ | --- | --- | --- |
163
+ | 作用范围 | **这套 profile**:这台机器装了哪些插件 | **这一个 agent 模式**:它的组成文件里挂哪些行 |
164
+ | 典型用法 | 全局关掉某个插件 | 让标准模式全开,而这个模式只留必要行 |
165
+
166
+ 两者并存,不冲突:官方决定「这台机器有什么」,本模式决定「这个模式用其中的哪些」。
167
+
168
+ 而且界限是**官方划的**:插件管理页的说明写着它管理「本 profile 的 bundle 与其中可寻址的行」,并明确
169
+ **agent-preset 行保持只读**。也就是说**官方管不到 preset 这一层**——本模式补的正是这一块。
170
+
171
+ 一个可以当场演示的例子:`tool-plugin-manager`(模型侧的插件安装/启停工具)在**标准模式与 PTC 模式里
172
+ 出厂就是关闭的**(只有创造模式默认打开)。官方模式不给你改它的入口,而在这里**拨一下就能打开**。
173
+
174
+ ## 工作原理
175
+
176
+ dsh 的系统提示词通常来自 preset 的 YAML,而官方 `@deepseek-ai/dsh-persona` 的 `prefix` 只在挂载时解析一次。本 preset 注册同名的 `deployment:persona-prefix` section,但把 `text` 写成**函数**,agent loop 在每次模型调用前都会调它。
177
+
178
+ 因此两件事的生效时机不同:
179
+
180
+ - **提示词文本**每步重新读取,所以改动对**正在运行**的会话立即生效。
181
+ - **开关与基础模式**会重写组成文件。`agent-presets` 在该文件的 `mtimeMs` 与 `size` 变化时重新挂载,所以由**新会话**生效;已开着的会话保持它启动时的配置 —— 这是刻意的,中途换工具集会出问题。
182
+
183
+ 行开关是三态。没碰过的行与出厂行逐字节相同,包括 `!!js` 平台条件与出厂 `disabled`;显式开或关才会把那个条件替换成布尔值。平台表达式在宿主端求值,所以页面显示的是这台机器上实际生效的状态,而不是"有没有这个键"。
184
+
185
+ 多助手不需要机制上的新能力:`dsh-agent-presets` 本来就会扫描用户预设根目录下的**每一个**目录,而且每次读 roster 都重新扫盘,所以一个刚建的目录在下一次选会话时就可见。每个助手的 `prompt-reader.mjs` / `prompt-tool.mjs` 都是按**自己模块位置**解析 `prompt.md` 的,N 份拷贝等于 N 套互不干扰的提示词。新增用包内模板播种;删除在有 `agentPresets.remove()` 的线上交给平台(它会拒绝删出厂 preset,并再确认目录确实在可写根目录下),在 `0.1.7`+ 上由本插件自己注销注册表项并删目录。
186
+
187
+ ## 版本
188
+
189
+ **支持两条线:最新线(`0.2.0-rc.2`,npm 的 `latest` 与 `next` 自 2026-09-29 起都指向它,也是桌面端
190
+ 所在的那条线)与上一个正式版(`0.1.7-rc.2`,仍在声明范围内,现役安装大多在它上面)** —— 声明为
191
+ `>=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0`(多出来的两段是因为
192
+ semver 只允许范围里**点名了** `major.minor.patch` 的预发布版本被匹配到),CI 会两条线各装一次并各跑一遍
193
+ 完整测试 —— 其中**渲染闸门跑在最新线**上,因为壳自己的 UI 改动最先落在那里。
194
+ 这里的策略是"只跟两个最新的":更早的线(`0.1.5-rc.3`、`0.1.6-alpha.*`)仍在 peer 范围内,但不单独占 CI 腿。
195
+ **官方桌面端(DeepSeek Harness Desktop)也在覆盖范围内**:它与 dsh 同版本号,当前即为 `0.2.0-rc.2`,
196
+ 正是这条矩阵钉住的组合;在应用内(侧栏 → Plugins)安装即可,CLI 那条路 dsh 自己会拒。
197
+ `0.2.0-rc.2` 实测(2026-09-30,干净的一次性 `DSH_HOME`):`dsh plugin --profile web add dsh-custom-mode`
198
+ 640ms 解析成功、组合树里有本插件的行、启动时五个预设文件全部播种、声明式注册表同步出助手,
199
+ 且 `agentPresets` 能力面不变(`list, register, inventory, select, document`)。
200
+
201
+ 包版本走**自己的线** —— `1.0.0`、`1.0.1` …… 它不镜像 DSH 的版本号。本插件支持哪些 dsh,由
202
+ 根 `package.json` 的 `engines.dsh` 与 `@deepseek-ai/dsh` peer 范围声明,并由
203
+ `tools/verify-version-consistency.mjs`(CI 里执行)断言"CI 实际安装并测试的 dsh 版本落在这些范围内"。
204
+
205
+ 拆开有两个原因。一是目录与市场要求裸 `x.y.z` 才自动安装 —— 有的会解析 npm `latest` 并拒绝任何带
206
+ 预发布标签的版本;二是版本号字符串本来就不是一个可校验的声明,声明式的范围才是,而且它才是官方改动时
207
+ 会过期的那一个。实际决定兼容性的仍然是下面这些 API 是否还在 —— 那些范围就是为它们写的。
208
+
209
+ <details>
210
+ <summary>耦合点清单(升级 dsh 时逐个核对)</summary>
211
+
212
+ | 依赖 | 变化后的后果 |
213
+ | --- | --- |
214
+ | `ctx.systemPrompt.section()` 且 `text` 支持**函数** | 提示词不再热更新 —— 整个项目的立足点 |
215
+ | `agentPresets` 依据组成文件的 `mtimeMs`+`size` 重挂载 | 开关要重启进程才生效 |
216
+ | `ctx.tools.register()` | 失去 `custom_prompt` 工具 |
217
+ | `ctx.connection.fetch.register({ path, methods, requestBody, fetch })` | 设置页 404 —— 什么都没注册 |
218
+ | `kind: 'prefix'` 同时匹配 `path` 与 `path/…` | 只有列表能打开,`/state`、`/create`、`/delete` 全部 404 |
219
+ | `agentPresets.list()` 行里有 `id` / `trust` / `path`,`preset.yml` 提供 `name` / `description` | 助手列表为空或认不出助手 |
220
+ | `agentPresets.remove(id)`(仅旧线),且拒绝 `trust: 'system'` | 0.1.7+ 的删除不再需要它 —— 声明式后端自己注销注册表项并删目录 |
221
+ | `ctx.connection.requestRejection(req)` | 设置页失败关闭(503),不再提供服务 |
222
+ | `ctx.inject(deps, cb)`(作用域化等待) | 在没有 web 服务器的 profile 里,整行会停在 `pending` |
223
+ | `dsh.client` + `exports["./client"]`,且客户端 bundle id 等于包名 | 浏览器半不会被发现 |
224
+ | `settings.section` 插槽(`id` / `order` / `label`) | 设置项位置与标签 |
225
+ | **`settings.section` 不再提供 `locale:`**(0.1.6-alpha.2 起) | 壳不会递进绑定到本命名空间的 `t`;页面自带词典兜底,见 ARCHITECTURE §15 |
226
+ | `preset.yml` 的 `order` 参与 roster 排序 | 「上移 / 下移」不生效 |
227
+ | `ctx.locale.register/bind` | 回退中文 |
228
+ | **出厂组成从哪来** —— 0.1.7+ 是 `agentPresets.readDocument(<mode>).content`,更早是 `@deepseek-ai/dsh-agent-presets` 的文件 | 基础模式与插件开关变为只读(提示词仍可保存),见 `base-composition.mjs` |
229
+ | 出厂布局 `<presets>/<id>/agent.cordis.yml` 与行的文本形状 | 基础模式切换失效 |
230
+ | `!!js` 平台表达式 | 平台行显示错误状态 |
231
+
232
+ </details>
233
+
234
+ ## 文档
235
+
236
+ - [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.zh.md) —— 在真机上复现过的失败,含症状、原因与自救方法。
237
+ - [`docs/MEASUREMENTS.md`](docs/MEASUREMENTS.zh.md) —— 每条结论背后的命令与原始输出。
238
+ - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.zh.md) —— 为什么必须是两个产物,以及依赖了哪些宿主 API。
239
+ - [`docs/PUBLISHING.md`](docs/PUBLISHING.zh.md) —— npm 包的发布方式。
240
+ - [`AGENTS.md`](AGENTS.md) —— 给 agent 的工作说明,含「实验机上做真浏览器验证」的完整配方(`tools/browser-verify.mjs`)。
241
+ - [`CHANGELOG.md`](CHANGELOG.zh.md) · [`SECURITY.md`](SECURITY.zh.md) · [`CONTRIBUTING.zh.md`](CONTRIBUTING.zh.md)
242
+
243
+ ## 开发
244
+
245
+ ```sh
246
+ node test/run.mjs # 15 个套件;自己解析出厂 preset 目录(0.1.7+ 从宿主声明派生)
247
+ ```
248
+
249
+ 改 `client.js` 会被 `@deepseek-ai/dsh-client-hmr` 在约 1 秒后热替换;改宿主半(`index.mjs`、`composition.mjs`、`meta.mjs`、`paths.mjs`)需要重启。每个套件在防什么见 [`test/README.md`](test/README.zh.md),改行为之前先读 [`CONTRIBUTING.zh.md`](CONTRIBUTING.zh.md)。
250
+
251
+ ## 如果它有用
252
+
253
+ 在 GitHub 上点个 ⭐,是让一个插件在几千个条目的目录里被看见的唯一办法 —— 它不花你什么,却正是这个项目
254
+ 还在被维护的理由。如果它在你的 dsh 线上**不好用**,带上 `dsh --version` 提个 issue:那是最快的修法,
255
+ 上面那张兼容表就是上一次这么来的。
256
+
257
+ ## License
258
+
259
+ MIT
260
+
261
+ ---
262
+
263
+ ## 构建环境
264
+
265
+ | | |
266
+ | --- | --- |
267
+ | 模型 | DeepSeek V4.1 Flash(`deepseek-v4-flash`,provider `deepseek-official`) |
268
+ | 运行时 | DeepSeek Harness **0.2.0-rc.2**(最新线)/ **0.1.7-rc.2**(上一个正式版)—— 支持的就是这两条线;下面的用量数字来自更早的 `0.1.6-alpha.2` 那一轮 |
269
+ | 未缓存输入 | 224,058 tok |
270
+ | 缓存读取 | 125,638,016 tok |
271
+ | 输出 | 425,539 tok |
272
+
273
+ 整个项目(含调研与返工)由 DSH 客户端统计:**126,287,613 tok**,缓存命中率 **99.8%**
274
+
275
+ ### 评审驱动的迭代轮次花了多少
276
+
277
+ 四份外部审阅变成了 `1.4.0` … `1.9.0` 这些版本(稳定线选择器修复、Windows 写入竞争、i18n 泄漏、可移植性修复、
278
+ 两轮 UI 改动)。同一个客户端里的实测:
279
+
280
+ | | |
281
+ | --- | --- |
282
+ | 未缓存输入 | 3,973,904 tok |
283
+ | 缓存读取 | 711,962,624 tok |
284
+ | 输出 | 1,559,791 tok |
285
+
286
+ 合计 **717,496,319 tokens**(3,973,904 + 711,962,624 + 1,559,791),缓存命中率 **99.4%**
287
+ (711,962,624 ÷ 715,936,528)。连同第一遍一起,项目累计 **843,783,932 tokens**,缓存命中 **99.5%**
288
+ (837,600,640 ÷ 841,798,602)。
289
+ (缓存读取 ÷ 全部输入 125,862,074)。
290
+
291
+ ## 更新
292
+
293
+ 插件装在 profile 的 `node_modules` 里,安装由平台负责,所以"更新"就是**再装一次** —— 你的数据不会被碰:
294
+
295
+ ```sh
296
+ # 钉版本的写法:要哪版就是哪版
297
+ dsh plugin --profile web add dsh-custom-mode@1.10.0
298
+ # 然后重启为该 profile 提供服务的 DSH 进程
299
+ ```
300
+
301
+ **想要这一版就别用不带版本号的安装。** pnpm 有发布冷却期(`minimumReleaseAge`,默认 24 小时),
302
+ `dsh plugin add dsh-custom-mode` 会解析成**"超过 24 小时的最新版"**。实测:在 1.9.0 已是 latest 的干净机器上,
303
+ 不带版本号的命令装到的是 **1.0.1**。钉版本可以绕过冷却期,所以上面的命令带 `@`。
304
+
305
+ **怎么知道自己在跑哪一版**:设置页底部显示已安装版本(「插件版本」),与 `npm view dsh-custom-mode version` 对照即可。
306
+
307
+ **更新不会碰的东西**:`$DSH_HOME/.agent-presets/<你的助手>/` —— `prompt.md`、`preset.yml` 与你逐行拨过的开关都属于你。
308
+ 播种只补**缺失**的文件,你写过的提示词永远不会被覆盖。
309
+
310
+ **如果基础模式与插件开关变灰、并带一行提示**:这条 dsh 线没有向本插件交出出厂组成(解析器依次试过宿主的
311
+ `readDocument()`、旧线的 presets 包、打包的 `dsh-web-app` patch,宿主日志里会写清每一次尝试)。系统提示词
312
+ 仍可单独保存,模式本身不受影响。0.1.7 上这在 1.9.13 之前是一个硬 500。
313
+
314
+ **如果更新后某个模式不再出现在选择器里**:老版本创建的助手会保留它自己的组成文件;如果那份文件启用了一行本机
315
+ 这条 dsh 线不提供的插件,平台会把整个预设判为 broken 并从选择器里静默丢弃(设置页照常能开)。打开设置页:
316
+ 它会明确告诉你,并提供**「按本线修复」** —— 只关掉那几行,其它选择一字不动。
package/client.js CHANGED
@@ -55,7 +55,7 @@ try {
55
55
  const ATOMS_MODULE = "@deepseek-ai/dsh-client-ui-primitives"
56
56
 
57
57
  /**
58
- * Copy for this page, generated from editor/locales.mjs (single source of
58
+ * Copy for this page, generated from locales.mjs (single source of
59
59
  * truth, checked for key parity by test/locales.test.mjs).
60
60
  */
61
61
  const ZH = {
package/journal.mjs CHANGED
@@ -116,7 +116,7 @@ export function recordPrompt(directory, text, by = HISTORY_SOURCE.settings) {
116
116
  const file = historyFile(directory)
117
117
  // 与宿主半同一条纪律:随机临时名(消除 tmp-vs-tmp 碰撞)+ 重试(Windows 上目标被并发 rename
118
118
  // 持有时会短暂 EPERM)+ 失败清理。
119
- // 与宿主半共用同一份实现(editor/atomic.mjs):这里原先自己留了一份重试与清理,两份会各自漂移
119
+ // 与宿主半共用同一份实现(atomic.mjs):这里原先自己留了一份重试与清理,两份会各自漂移
120
120
  // —— 外部审阅点名了这一点。预设侧(prompt-tool.mjs)仍保留自己的副本,因为那个文件独立分发、不能 import 宿主半。
121
121
  writeAtomic(file, lines.join('\n') + '\n')
122
122
  return { recorded: true, at, n }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-custom-mode",
3
- "version": "1.9.18",
3
+ "version": "1.10.0",
4
4
  "description": "Custom modes and custom prompts for DeepSeek Harness (dsh): edit a mode's system prompt on the settings page (it takes effect on the next model step), pick its base mode, switch plugin rows one by one, and keep several assistants side by side — coding, chat or roleplay (RP) personas (multi-mode / multi-agent).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -12,8 +12,7 @@
12
12
  },
13
13
  "repository": {
14
14
  "type": "git",
15
- "url": "git+https://github.com/BOWLUNA/dsh-custom-mode.git",
16
- "directory": "editor"
15
+ "url": "git+https://github.com/BOWLUNA/dsh-custom-mode.git"
17
16
  },
18
17
  "homepage": "https://github.com/BOWLUNA/dsh-custom-mode#readme",
19
18
  "bugs": {
@@ -22,8 +21,10 @@
22
21
  "keywords": [
23
22
  "dsh",
24
23
  "deepseek-harness",
24
+ "deepseek",
25
25
  "dsh-plugin",
26
26
  "cordis",
27
+ "plugin",
27
28
  "agent-preset",
28
29
  "agent-mode",
29
30
  "custom-mode",
@@ -37,7 +38,6 @@
37
38
  "multi-agent",
38
39
  "roleplay",
39
40
  "chat",
40
- "deepseek",
41
41
  "settings-page",
42
42
  "自定义模式",
43
43
  "系统提示词",
@@ -71,14 +71,12 @@
71
71
  "preset/"
72
72
  ],
73
73
  "scripts": {
74
- "test": "node ../test/run.mjs"
74
+ "test": "node test/run.mjs",
75
+ "verify-translation-pairing": "node tools/verify-translation-pairing.mjs",
76
+ "verify-doc-numbers": "node tools/verify-doc-numbers.mjs"
75
77
  },
76
78
  "peerDependencies": {
77
- "@deepseek-ai/dsh": ">=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0"
78
- },
79
- "publishConfig": {
80
- "access": "public",
81
- "tag": "latest"
79
+ "@deepseek-ai/dsh": ">=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0"
82
80
  },
83
81
  "peerDependenciesMeta": {
84
82
  "@deepseek-ai/dsh": {
@@ -86,6 +84,11 @@
86
84
  }
87
85
  },
88
86
  "engines": {
89
- "dsh": ">=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0"
87
+ "node": ">=20",
88
+ "dsh": ">=0.1.5-rc.2 <0.2.0-0 || >=0.1.6-alpha.1 <0.2.0-0 || >=0.1.7-alpha.1 <0.2.0-0 || >=0.2.0-0 <0.3.0-0"
89
+ },
90
+ "publishConfig": {
91
+ "access": "public",
92
+ "tag": "latest"
90
93
  }
91
94
  }
@@ -58,7 +58,7 @@
58
58
  # ROOT loader's entries; an agent preset's rows are mounted at runtime through
59
59
  # an Include subtree, so a browser half declared in this file is never
60
60
  # discovered. That page therefore lives in its own profile-level package
61
- # (the `editor/` directory of this repo, linked into the profile as
61
+ # (this repository, linked into the profile as
62
62
  # `profiles/<profile>/node_modules/dsh-custom-mode` by install.sh),
63
63
  # which is the only plane where a browser half is reachable. See README.md.
64
64
 
package/seed.mjs CHANGED
@@ -36,7 +36,7 @@ export const PRESET_FILES = [
36
36
  'prompt-tool.mjs',
37
37
  ]
38
38
 
39
- /** Directory of the packaged copy: `editor/preset/` beside this module. */
39
+ /** Directory of the packaged copy: `preset/` beside this module (the package root is the repo root). */
40
40
  export function packagedPresetDir() {
41
41
  return join(dirname(fileURLToPath(import.meta.url)), 'preset')
42
42
  }