dsh-prompt-customizer
System-prompt & tool-catalog customizer for DeepSeek Harness.
Block / replace / inject / reorder prompt sections by name, layered by session phase and agent preset — all from a settings-panel UI.
English ·
简体中文
Installation •
Features •
Usage •
How it works •
Known limitations
⭐ GitHub repo: DreamsTOF/dsh-prompt-customizer — if you find it useful, please drop a star; bug reports and feature requests go to Issues
---
A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) plugin that lets you control the **system prompt** and the **tool catalog** from a settings-panel UI.
Plugin-injected prompt sections can pollute your system prompt. This plugin lets you **block**, **replace**, **inject** and **reorder** prompt sections by name, and **hide tools** from the model-facing catalog — live, without touching any other plugin.
Two ideas run through the whole design:
- **Per session phase.** Bootstrap (before promotion) / resident (after promotion) / compaction-controlled (after a compaction, before re-promotion) each get their **own block list, their own ordering space and their own tool catalog**. One preset can therefore show the model 1 tool and a handful of sections on the first turn, then open everything up after promotion.
- **Per agent preset.** The selector at the top chooses where edits land: `Target: global default` edits the defaults; picking an agent preset writes a field-level override for that preset only (set fields take over, unset fields keep falling back to global).
## How the session phases flow
The phases are not a fixed three-beat rhythm — they are **derived from durable session
events**: the first durable `tool/call` or `assistant/message` promotes, and a
`compaction/end` resets that promotion. The three parts of the panel map to those states.
① Session starts
bootstrap
Guide period |
→ |
② First durable signal
tool/call · assistant/message
Resident period active |
→ |
③ A compaction
compaction/end
Compaction-controlled compaction |
|
④ another durable signal after the compaction → back to the resident period; compact again and it falls back to compaction-controlled
|
Every transition (note the guide period can reach compaction-controlled without passing through resident):
| Current phase | Event | Next |
| --------------------- | ----------------------------------------------- | ------------------------- |
| Guide | first durable `tool/call` / `assistant/message` | **Resident** |
| Guide | `compaction/end` | **Compaction-controlled** |
| Resident | `compaction/end` (promotion reset) | **Compaction-controlled** |
| Compaction-controlled | a new durable signal after the compaction | **Resident** |
| Any | subagent session (`delegationDepth > 0`) | always **Resident** |
| Any | read with no session (inventory, preview) | always **Resident** |
What each phase resolves to — the three panel parts map one-to-one onto config fields:
| Panel part | Effective section blocks | Injected `phase` | Effective tool blacklist |
| -------------------------------------- | ------------------------ | ------------------------- | ------------------------------------------------------------------ |
| Guide-period sections / tools | `sectionsBootstrap` | `bootstrap` (+ `always`) | `tools.bootstrap.exclude`, falling back to static when unset |
| Resident-period sections / tools | `sections` | `active` (+ `always`) | `tools.exclude` (static) |
| Compaction-controlled sections / tools | `sectionsCompaction` | `compaction` (+ `always`) | `tools.compaction.exclude`, falling back to bootstrap, then static |
Two things that bite:
- **`always` injections are present in all three phases**, and each phase has its own ordering space — which is why this plugin emits phase entries _after_ the `always` group: the assembly applies inject records in array order and the last write wins, so the phase order is what survives.
- **A phase view is "what this state resolves to", not "what the session has been".** Native preset phase rules (zero-tool bootstrap, warmup, …) are in play at the same moment and may still change the result after other plugins — see [Known limitations](#known-limitations).
## UI
## Features
### Prompt sections
- **Block** — remove a section by name. A blocked row does not disappear: it stays draggable and editable and can be restored at any time. Blocking only means "not injected into the model".
- **Replace** — edit a section's text; the editor is pre-filled with the text currently in effect (dynamically generated sections are resolved first so you see real content).
- **Inject** — every phase part has its own name + text box to add a brand-new section, badged `manual` and deletable.
- **Reorder** — drag a whole row (an insert line appears above/below the target row) or use ↑/↓. Order is stored as a contiguous 0-based virtual index, so there are never duplicate or fractional orders and no number to type by hand.
- **Independent per phase** — bootstrap blocks go to `sectionsBootstrap`, compaction blocks to `sectionsCompaction`, resident blocks to `sections`; each phase has its own ordering space, so "5 sections during bootstrap, everything when resident" is expressible.
### Tool catalog
- **Blacklist only** (`exclude`) — unchecking a tool hides it **in that phase**; checking it back restores it. There is no whitelist mode: it silenced `exclude` entirely, and a single drag could quietly switch off every other tool in the phase while offering no expressive gain.
- **Dragging in = make that one tool visible in the phase** (remove it from the phase blacklist); dragging back to _All system tools_ hides it there. Every action touches only the tool you dragged.
- **Phase catalogs** — bootstrap and compaction each have their own blacklist. Runtime precedence is **compaction > bootstrap > static**: after a compaction with a compaction catalog configured, it applies; otherwise an un-promoted session uses the bootstrap catalog; everything else uses the static filter.
- **Narrowing only, never widening** — the filter operates on the catalog the assembly already produced. A tool a phase never had cannot be made to appear here; that means editing the preset's composition.
- Only the model-facing catalog is affected; the tools themselves and routing keep working.
### Model-view preview
The Preview tab shows the final system prompt and tool catalog after **all** plugins have filtered, switchable per phase. It reads the same assembly as the prompt and tools tabs, so what you see is what the model sees. The tools view reports "visible to the model / registry total" side by side — presets such as PTC or Code Mode wrap the whole catalog into a single `run_code`, so the registry alone misleads.
### Prompt template variables
The host registers only `provider` / `model` / `cwd` as template variables; referencing any other `{{name}}` in section text makes the whole assembly fail. This plugin adds two more families through the official extension point:
- **Built-in system facts**: `date` / `time` / `datetime` / `weekday` / `hostname` / `platform` / `arch` / `username` / `home` / `shell` / `locale` / `node_version`, computed fresh at every assembly.
- **Every environment variable**: each `process.env` key maps to `env_`, e.g. `PATH` → `{{env_path}}`, `USER.NAME` → `{{env_user_name}}`.
**Blocklist (`envBlocklist`)**: environment variables often carry secrets, and anything in the prompt is sent to the model with every request, so keys matching the blocklist are never registered. The prefilled entries cover common credential-style keys (`SECRET` / `TOKEN` / `PASSWORD` / `API_KEY` / `*_DSN` and friends); entries support `*` wildcards and are case-insensitive. The environment variable blocklist card in the panel lets you add or remove entries at any time, and its collapsible list shows the variables actually registered right now. Blocklist changes take effect at the next assembly (whether you edit the panel or `config.yaml` by hand).
**Carried by export / import**: exporting a preset writes the current blocklist along with it; import merges it in by union (grow-only), consistent with the snapshot library semantics.
The cost of strict rendering: referencing an unregistered name (such as a key the blocklist blocks) makes the **whole assembly fail** rather than rendering empty — only use names that appear in the panel's variable list.
### Config snapshots and agent presets
- **Save current config** — capture the complete customization of the current scope (per-phase block lists, per-phase ordering and phase tool catalogs) as a reusable snapshot.
- **Apply** — same-name sections are overridden, current sections outside the snapshot list are blocked, and snapshot sections that do not match the current system are skipped (cross-system imports never fabricate sections). Phase fields the snapshot does not carry keep your current values instead of being wiped. Only one snapshot is active at a time.
- **Export / import** — snapshots round-trip as JSON (native save/open dialogs under Tauri, download / file picker on web); same-name presets are skipped. Order is stored relatively (each section records which section it follows), so snapshots stay portable across different section sets.
- **Save as agent preset** — **copy** the whole preset directory of the current edit target (composition file, companion scripts, skill directories) into the user preset root, then write the current customization into its override. The new preset immediately appears in the target selector: a real switchable agent preset, not merely a config copy.
### Cross-preset registry pool
_All system sections_ / _All system tools_ do not follow the edit target: they are a **union across presets that only ever grows** (same name — last seen wins; new name — appended), filled in as you browse presets and stored in the derived cache `catalog.yaml`, which rebuilds itself if deleted.
## How it works
The full path a change takes from the panel to the model:
① Settings panel
sections / tools / config / preview
edits an in-memory draft only |
→ |
② Plugin routes
/config · /config/apply
/preview · /inventory · /presets |
→ |
③ config.yaml
global fields + overrides[preset]
mtime-lazy reload, hand edits apply at once |
→ |
④ Assembly waterfall
the system-prompt/assemble hook derives the phase from the session, resolves the effective config and filters |
inside ④, in order: mergeConfig(global, overrides[session preset]) → sections: block → replace → inject → sort by order; tools: pickToolsFilter (compaction > bootstrap > static) → applyToolFilter |
⑤ one last move before handing in: after the waterfall the host restores the single complete: true section as the whole sections array when one exists — exactly why the panel shows a yellow warning for such presets (the tool catalog is unaffected)
|
| ⑥ the model receives: the final system prompt + visible tool catalog; the Preview tab reads this very result |
Code map:
| Path | Role |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `lib/index.js` | host half: assembly hook, five HTTP routes, agent-preset fork, one-off legacy cleanup |
| `lib/effective.js` | pure functions: field-level override merge, phase selection (injections / tool catalogs), blacklist filtering |
| `lib/promotion.js` | derives `{promoted, boundary}` from durable events — compaction resets, subagents always promoted |
| `lib/vars.js` | prompt variables: built-in system facts + full env mapping / blocklist, lazily re-synced at the assembly entry by signature |
| `lib/sectionOps.mjs` | phase-state pure functions **shared by the panel and the unit tests** (which list to write, injection identity, reorder, per-phase persistence) |
| `lib/store.js` / `lib/catalog.js` | atomic write + last-good fallback config store; cross-preset section/tool accumulation cache |
| `src/client/` | the panel (React written with `h()`, no JSX sugar), bundled into `client/client.js` |
The key convention: phase logic exists once. `lib/sectionOps.mjs` is both bundled into the
browser by tsdown and imported directly by `node --test`, so there is no second
implementation standing between "tests pass" and "the UI behaves".
## Installation
```bash
dsh plugin --profile web add dsh-prompt-customizer
```
Or from a local checkout:
```bash
dsh plugin --profile web add /path/to/dsh-prompt-customizer
```
Then open the dsh web UI → **Settings** → **提示词定制** (Prompt Customizer) in the sidebar.
## Usage
### Prompt tab
The three phase parts (bootstrap / resident / compaction-controlled) are **always rendered** — if a preset has no such phase, that part is simply empty rather than hidden. Each row offers:
- a **checkbox** to block / unblock (`未屏蔽` / `已屏蔽` badge)
- **Edit** to replace the section text; replaced rows carry an `已替换` badge and a restore button
- **↑/↓** and a **drag handle** to reorder within the phase; `#N` is the current virtual index
- a `system` / `manual` badge for provenance — only `manual` sections can be deleted
`阶段可见 N` next to each title is the number of rows in that part. The name + text box at the bottom injects into that part, with the phase already fixed.
### Tools tab
One part per phase, chip-listing the catalog entering that phase's filter, titled `阶段可见 enabled / total`. Check to keep a tool visible in that phase, uncheck to hide it; dragging a tool in from _All system tools_ only makes **that one tool** visible in the phase, and dragging it back hides it there. For what the model actually receives, use the tools view in the Preview tab.
### Config tab
Five cards: **Save current config** (snapshot), **Save as agent preset** (fork the current target's preset directory), **Import config**, **Environment variable blocklist** (add/remove entries, inspect the variables actually registered right now), **Force override switch**. Each snapshot row is Apply / Export / Delete, and the active row carries an "in use" badge.
### Edit target and saving
The selector at the top decides where changes land. The prompt and tools tabs share one unsaved draft, and **Save** writes it in a single request; switching to the config / preview tabs or changing the edit target discards the draft (after confirming). Nothing you mistype reaches the file until you press Save.
## Where the config lives
- `~/.dsh/prompt-customizer/config.yaml` — the single source of truth. On first start, if this file is missing but the legacy `settings.yaml` has the section, it is migrated once (the master document is left intact and stays rollback-able). Hand edits take effect on the next read, no restart needed.
- `~/.dsh/prompt-customizer/catalog.yaml` — the cross-preset accumulation cache for the pools above. Purely derived; delete it and it rebuilds as you browse.
## Known limitations
All of the below are measured, and the panel shows a yellow warning in exactly these situations rather than leaving you to guess:
- **Some presets have no section-composed prompt.** If a section is registered with `complete: true` (dsh-persona's wholesale takeover), the host restores that single section as the entire `sections` array **after** the assembly waterfall — so this plugin's blocking / replacement / injection / ordering never reaches the model (tool filtering still applies). The panel says so explicitly ("taken over wholesale by `deployment:persona`"). The only way to make section customization work is to turn off `complete` in that agent preset.
- **Dropping sections has more than one cause.** Besides `complete` takeover, a preset can also trim sections itself for a specific phase (measured: 20 → 1 sections during bootstrap, with no `complete` section in the registry). The panel therefore also compares names mechanically: it diffs the sections this plugin emitted against the final assembly and reports "emitted N, model sees M" when they disagree.
- **The synthetic session behind a preview can degrade.** Phase views are driven by a fabricated session; some preset plugins throw on it, so that phase falls back to an agent-less assembly and is marked degraded — i.e. it shows the result _without_ native phase narrowing.
- **Replacing a dynamically generated section freezes its content.** Sections like `app:web-surface` are generated at assembly time (embedding the current web port and so on). After replacing, the text is fixed at the value you edited and no longer tracks runtime state. To keep following it, block the section instead.
- **Dynamic text resolution is best-effort.** The panel calls a dynamic section's generator with a minimal context to echo real content; sections that need richer context and throw fall back to `<动态生成>`, with no other effect. Also, sections containing `{{model}}` / `{{cwd}}` style variables show the **unsubstituted template** in the list — the Preview tab is where the substituted final text appears.
- **Export depends on the host allowing downloads.** The web fallback uses a browser download: if the host webview silently drops it, the panel still reports "exported" while no file lands. Import (file picker) is unaffected.
- **Tool catalogs cannot be widened** — see "narrowing only" above.
## Development
```bash
npm install
npm run check # typecheck + build + full test suite
```
The browser half is built with [tsdown](https://github.com/rolldown/tsdown) into `client/client.js` (a `__ModuleLoader__` factory bundle); the host half lives in `lib/`. Phase state logic sits in `lib/sectionOps.mjs`: the same pure functions are bundled into the UI and exercised directly by `node --test`, so the tests are the shipped code.
## License
[MIT](LICENSE) © 2026 DreamsTOF
---
## Star History
[](https://star-history.com/#DreamsTOF/dsh-prompt-customizer&Date)
---
⭐ If this plugin keeps your system prompt cleaner and your tool catalog tamer, give it a star!