@nelsonlongxiang/dsh-prompt-templates 0.14.0 → 0.16.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.
- package/README.md +182 -178
- package/README_zh.md +181 -177
- package/cordis.patch.yml +37 -37
- package/docs/clipboard-verification.md +53 -53
- package/docs/event-failure-contract.md +45 -45
- package/docs/evolution-default.md +46 -0
- package/docs/library-packs.md +43 -0
- package/docs/spec-event-inject.md +317 -316
- package/docs/test-plan-phase-c.md +183 -183
- package/lib/cli/database.js +12 -12
- package/lib/client/Library.js +28 -13
- package/lib/client/Panel.js +2 -2
- package/lib/client/PromptTab.js +2 -2
- package/lib/client/api.js +14 -0
- package/lib/client/index.js +2 -1
- package/lib/client/locales.js +6 -4
- package/lib/client.js +154 -103
- package/lib/client.js.map +1 -1
- package/lib/event-inject.js +42 -5
- package/lib/event-store.js +110 -78
- package/lib/evolution-default.js +12 -12
- package/lib/index.js +72 -4
- package/lib/inject.js +21 -2
- package/lib/interventions.js +85 -0
- package/lib/store.js +236 -57
- package/lib/types/client/api.d.ts +9 -0
- package/lib/types/client/locales.d.ts +6 -4
- package/lib/types/client/slots.d.ts +4 -2
- package/lib/types/event-inject.d.ts +13 -1
- package/lib/types/event-store.d.ts +17 -0
- package/lib/types/index.d.ts +7 -0
- package/lib/types/inject.d.ts +1 -0
- package/lib/types/interventions.d.ts +73 -0
- package/lib/types/store.d.ts +71 -3
- package/lib/types/types.d.ts +7 -0
- package/package.json +107 -104
- package/packs/atelier-5.16.1.json +75 -0
package/README.md
CHANGED
|
@@ -1,178 +1,182 @@
|
|
|
1
|
-
# @nelsonlongxiang/dsh-prompt-templates
|
|
2
|
-
|
|
3
|
-
English | [中文](README_zh.md)
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@nelsonlongxiang/dsh-prompt-templates)
|
|
6
|
-
|
|
7
|
-
Quick prompt templates for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): global and per-session templates, a right-side browser panel, and pure-TS SQLite persistence via `node:sqlite` — one self-contained plugin, installable with `dsh plugin`.
|
|
8
|
-
|
|
9
|
-

|
|
10
|
-
|
|
11
|
-
## Install
|
|
12
|
-
|
|
13
|
-
```sh
|
|
14
|
-
dsh plugin --profile web add @nelsonlongxiang/dsh-prompt-templates
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
Restart `dsh web`, then look for the templates button in the composer tool row. Since 0.12.0 the same library is also a **right-sidebar tab**: open it from the sidebar's `+` guide page (entry “Prompt templates”) — it lives beside the conversation, keeps the composer visible, and always targets the session the sidebar is viewing. On hosts without the sidebar services the tab stays dormant and the floating panel keeps working.
|
|
18
|
-
|
|
19
|
-
No Python toolchain required — since 0.3.0 the host half persists templates through `node:sqlite` (Node ≥ 24) directly inside the host process, reading and writing the same `$DSH_HOME/ext/prompt-templates/db.sqlite3` the former Python child owned (zero data migration).
|
|
20
|
-
|
|
21
|
-
## What you get
|
|
22
|
-
|
|
23
|
-
- **Global + per-session templates** — globals apply everywhere; session templates stay private to one conversation and can be promoted to global in one click
|
|
24
|
-
- **Scheduled auto-injection** — per-template switch and interval: the host re-surfaces an enabled template into the model context at the first request of every Nth round, persisted in SQLite and logged as a durable session event; click the toolbar `⟳N` badge to open the session's last 20 injections (turn, time, template names, injected bodies)
|
|
25
|
-
- **Template variables** — content supports `{{date}}` `{{time}}` `{{datetime}}` `{{weekday}}` `{{session}}` `{{turn}}`, expanded at delivery across insert, send-now, interject, and scheduled injection; unresolved values stay literal and storage keeps the raw text
|
|
26
|
-
- **Cross-instance sharing** — copy one template or a whole category as a clipboard payload; paste-import on the target instance with an explicit same-name overwrite confirm
|
|
27
|
-
- **Insert or send** — one click inserts the template at the composer caret (or replaces the current selection); send-now dispatches immediately; edit, delete, and make-global all live in the row
|
|
28
|
-
- **Right-sidebar tab** — the full library also docks as a sidebar tab (DSH ≥ 0.2.x): open it from the `+` guide and it follows the session you are viewing; the floating panel remains for quick one-shot use
|
|
29
|
-
- **Search & scroll** — filter the list as you type, reliable scrolling for long collections
|
|
30
|
-
- **Drag to reposition, double-click to reset** — the panel remembers where you put it
|
|
31
|
-
- **Durable by design** — templates persist in SQLite through a pure-TS store (`node:sqlite`) owned by the host plugin and closed with its lifecycle
|
|
32
|
-
|
|
33
|
-
## Sharing (cross-instance copy)
|
|
34
|
-
|
|
35
|
-
- The row ⧉ button shares **one template**; the category tab ⧉ shares **a whole category** (member templates + the category definition)
|
|
36
|
-
- The **Share template JSON / Share category JSON** buttons share a self-describing payload (`format`/`version` markers), not just the prompt body. No files or network are used.
|
|
37
|
-
- Automatic copying tries the browser Clipboard API first, then a compatibility copy command. If both fail, a read-only **Copy share JSON manually** panel preserves exactly the same payload: select all, press Ctrl+C / ⌘C, and paste into the target instance Import box. The panel distinguishes unavailable API, unfocused page, denied write and security restriction; it does not diagnose a damaged system clipboard.
|
|
38
|
-
- Clipboard restrictions depend on the browser/context. Plain LAN HTTP may lack the API; loopback origins such as `http://127.0.0.1` can be trustworthy despite HTTP. No global security changes or clipboard-reading permission are needed.
|
|
39
|
-
- Paste into the toolbar **Import** box on the target instance: missing categories are created, and **same-name same-scope templates raise an explicit overwrite confirm** — overwrite updates the existing row (content/description/category/inject facts), declining skips; the result reports created/overwritten/skipped counts
|
|
40
|
-
- What is shared is the **raw text**: `{{date}}`/`{{turn}}` re-expand at delivery on the receiving instance
|
|
41
|
-
|
|
42
|
-
## Auto-inject
|
|
43
|
-
|
|
44
|
-
Each template (global or session-scoped) carries its own **switch + interval N**. When on, the host injects the template at the first request of every Nth round of the conversation — N=5 means rounds 5, 10, 15, …; rounds count user→assistant exchanges and keep their numbering across restarts.
|
|
45
|
-
|
|
46
|
-
- The injected content arrives as one durable `<system-reminder>` user message recorded in the session log (source kind `prompt-template-schedule`), so replays and audits reconstruct exactly what the model saw
|
|
47
|
-
- A boundary round is never injected twice, even across restarts or step retries
|
|
48
|
-
- Config persists in the plugin's SQLite database (schema
|
|
49
|
-
- Each template picks a delivery mode: **silent** (default, model context only) or **visible in chat** (rendered as a normal user message with a ⚙️ scheduled-injection header)
|
|
50
|
-
|
|
51
|
-
##
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
62
|
-
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
The
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
|
128
|
-
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
1
|
+
# @nelsonlongxiang/dsh-prompt-templates
|
|
2
|
+
|
|
3
|
+
English | [中文](README_zh.md)
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@nelsonlongxiang/dsh-prompt-templates)
|
|
6
|
+
|
|
7
|
+
Quick prompt templates for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): global and per-session templates, a right-side browser panel, and pure-TS SQLite persistence via `node:sqlite` — one self-contained plugin, installable with `dsh plugin`.
|
|
8
|
+
|
|
9
|
+

|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
dsh plugin --profile web add @nelsonlongxiang/dsh-prompt-templates
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Restart `dsh web`, then look for the templates button in the composer tool row. Since 0.12.0 the same library is also a **right-sidebar tab**: open it from the sidebar's `+` guide page (entry “Prompt templates”) — it lives beside the conversation, keeps the composer visible, and always targets the session the sidebar is viewing. On hosts without the sidebar services the tab stays dormant and the floating panel keeps working.
|
|
18
|
+
|
|
19
|
+
No Python toolchain required — since 0.3.0 the host half persists templates through `node:sqlite` (Node ≥ 24) directly inside the host process, reading and writing the same `$DSH_HOME/ext/prompt-templates/db.sqlite3` the former Python child owned (zero data migration).
|
|
20
|
+
|
|
21
|
+
## What you get
|
|
22
|
+
|
|
23
|
+
- **Global + per-session templates** — globals apply everywhere; session templates stay private to one conversation and can be promoted to global in one click
|
|
24
|
+
- **Scheduled auto-injection** — per-template switch and interval: the host re-surfaces an enabled template into the model context at the first request of every Nth round, persisted in SQLite and logged as a durable session event; click the toolbar `⟳N` badge to open the session's last 20 injections (turn, time, template names, injected bodies)
|
|
25
|
+
- **Template variables** — content supports `{{date}}` `{{time}}` `{{datetime}}` `{{weekday}}` `{{session}}` `{{turn}}`, expanded at delivery across insert, send-now, interject, and scheduled injection; unresolved values stay literal and storage keeps the raw text
|
|
26
|
+
- **Cross-instance sharing** — copy one template or a whole category as a clipboard payload; paste-import on the target instance with an explicit same-name overwrite confirm
|
|
27
|
+
- **Insert or send** — one click inserts the template at the composer caret (or replaces the current selection); send-now dispatches immediately; edit, delete, and make-global all live in the row
|
|
28
|
+
- **Right-sidebar tab** — the full library also docks as a sidebar tab (DSH ≥ 0.2.x): open it from the `+` guide and it follows the session you are viewing; the floating panel remains for quick one-shot use
|
|
29
|
+
- **Search & scroll** — filter the list as you type, reliable scrolling for long collections
|
|
30
|
+
- **Drag to reposition, double-click to reset** — the panel remembers where you put it
|
|
31
|
+
- **Durable by design** — templates persist in SQLite through a pure-TS store (`node:sqlite`) owned by the host plugin and closed with its lifecycle
|
|
32
|
+
|
|
33
|
+
## Sharing (cross-instance copy)
|
|
34
|
+
|
|
35
|
+
- The row ⧉ button shares **one template**; the category tab ⧉ shares **a whole category** (member templates + the category definition)
|
|
36
|
+
- The **Share template JSON / Share category JSON** buttons share a self-describing payload (`format`/`version` markers), not just the prompt body. No files or network are used.
|
|
37
|
+
- Automatic copying tries the browser Clipboard API first, then a compatibility copy command. If both fail, a read-only **Copy share JSON manually** panel preserves exactly the same payload: select all, press Ctrl+C / ⌘C, and paste into the target instance Import box. The panel distinguishes unavailable API, unfocused page, denied write and security restriction; it does not diagnose a damaged system clipboard.
|
|
38
|
+
- Clipboard restrictions depend on the browser/context. Plain LAN HTTP may lack the API; loopback origins such as `http://127.0.0.1` can be trustworthy despite HTTP. No global security changes or clipboard-reading permission are needed.
|
|
39
|
+
- Paste into the toolbar **Import** box on the target instance: missing categories are created, and **same-name same-scope templates raise an explicit overwrite confirm** — overwrite updates the existing row (content/description/category/inject facts), declining skips; the result reports created/overwritten/skipped counts
|
|
40
|
+
- What is shared is the **raw text**: `{{date}}`/`{{turn}}` re-expand at delivery on the receiving instance
|
|
41
|
+
|
|
42
|
+
## Auto-inject
|
|
43
|
+
|
|
44
|
+
Each template (global or session-scoped) carries its own **switch + interval N**. When on, the host injects the template at the first request of every Nth round of the conversation — N=5 means rounds 5, 10, 15, …; rounds count user→assistant exchanges and keep their numbering across restarts.
|
|
45
|
+
|
|
46
|
+
- The injected content arrives as one durable `<system-reminder>` user message recorded in the session log (source kind `prompt-template-schedule`), so replays and audits reconstruct exactly what the model saw
|
|
47
|
+
- A boundary round is never injected twice, even across restarts or step retries
|
|
48
|
+
- Config persists in the plugin's SQLite database (schema v6, including evolution enrollment); `injectEnabled: false` in the patch config silences **scheduled injection only** — event reminders (below) have their own independent master switch `eventInject.enabled`
|
|
49
|
+
- Each template picks a delivery mode: **silent** (default, model context only) or **visible in chat** (rendered as a normal user message with a ⚙️ scheduled-injection header)
|
|
50
|
+
|
|
51
|
+
## Atelier evolution checkpoint (unreleased)
|
|
52
|
+
|
|
53
|
+
A session-scoped `工坊·演化自评估` template is provisioned once by default and scheduled every 100 user turns. Existing same-name global/session templates and user edits, disabling and deletion are preserved. This is a reminder, not migration execution or authorization. Set `evolutionAssessmentEnabled: false` to opt out. See [the lifecycle, counting and rollback contract](docs/evolution-default.md).
|
|
54
|
+
|
|
55
|
+
## Event reminders (off by default)
|
|
56
|
+
|
|
57
|
+
Besides fixed rounds, the plugin can remind the agent **because of what just happened**. It watches final tool results, detects two problems — **repeated preparation** (the same hand-built prefix such as environment variables plus an absolute interpreter path, with different tasks) and **repeated failure** (the same target failing the same way, or failing again after it had succeeded) — and appends one short reminder before the next model decision, including the tool-result steps that scheduled injection skips.
|
|
58
|
+
|
|
59
|
+
- Two switches in series: the master switch lives in the plugin database (the panel ⚙ dropdown toggles it, effective immediately without a restart; the deployment `eventInject.enabled` value only seeds it on first read) and each rule keeps its own toggle alongside threshold/cooldown and the read-only episode ledger. Owner ruling 2026-11-18: the master switch moved from deployment-config-only to panel-owned, reversing the 2026-11-14 posture.
|
|
60
|
+
- Timing: observation happens after a tool result; the reminder is appended before the **next model decision in the same turn**. It cannot block a first violation, and cannot undo side effects or already-issued sibling parallel calls
|
|
61
|
+
- What is stored: fingerprints (hashes) plus a length-bounded, heuristically redacted summary of the arguments. Raw arguments/output are not stored wholesale, but the summary may still carry argument fragments the redaction did not mask; it is never treated as an instruction or authorization
|
|
62
|
+
- Failure classification prioritizes `isError` and its error code, then an integer `meta.exitCode` (including zero). Only when metadata has no valid exit code does the `bash` adapter read the exact trailing `[exit code: N]` marker from the last text part. Arbitrary output words such as success or failure do not decide the result. A command can print a lookalike marker, so this fallback can produce a false positive; `ok` means tool-layer completion, not verified task success. See the [failure contract](docs/event-failure-contract.md) for priority, recorded-host limits, and untested cases.
|
|
63
|
+
- Budgeted: one reminder per **user turn** by default (long autonomous turns therefore get at most one), a character cap, a per-rule cooldown (3 turns by default), and a per-problem limit; no new evidence, no reminder
|
|
64
|
+
- Delivery is at-least-once with dedup against the session log, so restarts and rejected steps neither lose nor duplicate a reminder
|
|
65
|
+
- The plugin only marks a problem `notified`. The `changed` / `repeated` field is a weak behavioral hint, not a verdict: an unrelated command on the same tool can flip it. Closing an episode (`verified`, `rejected`, …) goes through `PATCH …/event-episodes/<id>` and requires evidence references — only a full-trajectory review counts as verification
|
|
66
|
+
- A reminder is a user-role message: not a user instruction, no extra permission. How an agent should handle it is defined in Agent Atelier's `references/improvement-loop.md`; the design is in [docs/spec-event-inject.md](docs/spec-event-inject.md)
|
|
67
|
+
|
|
68
|
+
## Template variables
|
|
69
|
+
|
|
70
|
+
Placeholders `{{date}}` `{{time}}` `{{datetime}}` `{{weekday}}` `{{session}}` `{{turn}}` expand **at delivery time** — insert, send-now, interject, and scheduled injection all expand:
|
|
71
|
+
|
|
72
|
+
- Clock variables read the local clock; `{{session}}` is the target session id; `{{turn}}` resolves only on the scheduled-injection path (it stays literal on insert/send)
|
|
73
|
+
- Unknown names pass through untouched — nothing is silently deleted; the template form shows a variable hint line
|
|
74
|
+
- Storage always keeps the raw text; expansion happens at the moment of delivery, so the history dropdown shows exactly what went out
|
|
75
|
+
|
|
76
|
+
## How it works
|
|
77
|
+
|
|
78
|
+
```text
|
|
79
|
+
src/ TypeScript plugin (host half + browser half)
|
|
80
|
+
index.ts Host: owns the TS store, exposes the HTTP routes
|
|
81
|
+
store.ts Pure-TS store over node:sqlite (database schema v6)
|
|
82
|
+
inject.ts Host: scheduled auto-injection on the pre-step waterfall
|
|
83
|
+
invariant.ts Host: registers the package's invariant companion
|
|
84
|
+
cli/ The sync CLI (export/diff/merge/import) shipped as bin
|
|
85
|
+
client/ Browser: shared template library mounted as both the
|
|
86
|
+
shell.overlay floating panel and the right-sidebar
|
|
87
|
+
tab body (sidebar.right.pane.tab), plus the
|
|
88
|
+
conversation.input.right toggle button
|
|
89
|
+
cordis.patch.yml Bundle patch: mounts the plugin row
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The store is pure TS inside the host half; no child process is spawned.
|
|
93
|
+
|
|
94
|
+
## Security
|
|
95
|
+
|
|
96
|
+
- Template **content** reaches a model request in exactly two ways: as ordinary user text the user chose to insert, or through scheduled auto-injection. User templates follow their saved switches; the unreleased Atelier default is enabled at once-per-session creation unless the deployment opts out, and remains editable/disableable/deletable by the user. Each delivered injection is a durable session event. Event reminders are a separate channel: they carry no template content, and their switch is independent of scheduled injection
|
|
97
|
+
- The panel talks to the host store over the Host's plugin routes only; no extra listener, no outbound network
|
|
98
|
+
|
|
99
|
+
## Database sync CLI
|
|
100
|
+
|
|
101
|
+
The package ships a deterministic, local-only CLI for comparing and merging prompt-template databases across DSH homes. It never writes a remote database directly.
|
|
102
|
+
|
|
103
|
+
```sh
|
|
104
|
+
# Export a schema-v4 snapshot (canonical order + data_sha256)
|
|
105
|
+
dsh-prompt-templates export --db /path/to/db.sqlite3 --out snapshot.json --output=json
|
|
106
|
+
|
|
107
|
+
# Compare two snapshots (exit 1 with --fail-on-diff)
|
|
108
|
+
dsh-prompt-templates diff left.json right.json --output=json --fail-on-diff
|
|
109
|
+
|
|
110
|
+
# Merge into a JSON artifact only; equal-time or name conflicts block by default
|
|
111
|
+
dsh-prompt-templates merge base.json incoming.json --strategy newer --out merged.json --output=json
|
|
112
|
+
|
|
113
|
+
# Dry-run import (the default): review summary_sha256 and database hash
|
|
114
|
+
dsh-prompt-templates import --db /path/to/db.sqlite3 --in merged.json --output=json
|
|
115
|
+
|
|
116
|
+
# Apply only after binding both reviewed values; creates a backup, then one transaction
|
|
117
|
+
dsh-prompt-templates import --db /path/to/db.sqlite3 --in merged.json --apply \
|
|
118
|
+
--expect-db-sha256 <db-sha256> --confirm-summary-hash <dry-run-summary-sha256> --output=json
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`import` inserts/updates by template id and never prunes rows. It rejects unknown snapshot fields, unsupported schemas, mismatched hashes, same-name/different-id conflicts, and changes above `--max-changes` (default 100). Schema-v2 snapshots (pre-auto-inject) still import — the inject facts default to off; exports are always schema v4 (templates/categories only, not event policies or runtime state).
|
|
122
|
+
|
|
123
|
+
## Repository layout
|
|
124
|
+
|
|
125
|
+
Declared layout — anything outside this allowlist at the repo root is scatter, and the patrol gate (`scripts/patrol.sh`, dir-convention section) fails on it:
|
|
126
|
+
|
|
127
|
+
| Path | Responsibility |
|
|
128
|
+
|---|---|
|
|
129
|
+
| `src/` | Host plugin, CLI, and browser-client sources |
|
|
130
|
+
| `scripts/` | Rerunnable ops entries: `patrol.sh`, `branch-audit.sh`, `remote-heads.sh`, `push-master.sh`, `release.sh` |
|
|
131
|
+
| `docs/` | Human-facing documents: specs, release notes, handover; the npm package ships only the explicitly listed user/acceptance guides |
|
|
132
|
+
| `tests/` | `node:test` suites behind `pnpm verify` |
|
|
133
|
+
| `images/` | Static assets referenced by the READMEs |
|
|
134
|
+
| `tmp/<task>/` | Git-ignored scratch; automated tests use `tmp/test-runs/` via `tests/temp-dir.mjs`; task lifetime only, never in git |
|
|
135
|
+
| `lib/`, `node_modules/` | Build output and dependencies — ignored, never tracked |
|
|
136
|
+
| `.npmrc`, `.claude/`, `.obelisk/` | Local tool state (registry config, workbench junctions, agent memories) — ignored, never tracked |
|
|
137
|
+
|
|
138
|
+
## Development
|
|
139
|
+
|
|
140
|
+
```sh
|
|
141
|
+
pnpm install
|
|
142
|
+
pnpm verify # everyday gate (local and CI)
|
|
143
|
+
pnpm verify:release # alias of pnpm verify
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`pnpm verify` is the gate to run before pushing. It does not boot a DeepSeek Harness process. In order:
|
|
147
|
+
|
|
148
|
+
1. **typecheck** — `tsc --noEmit` for the host project and the client project
|
|
149
|
+
2. **test:cli** — `node:test` over `tests/*.test.ts`: CLI sync, store rules, schema migration, inject helpers, client filters, and an in-process host check. That check mounts `apply()` on Cordis with a stand-in web server, drives the `/plugins/dsh-prompt-templates` routes (including inject-status), and runs the `agent/pre-step` listener against a fake session log
|
|
150
|
+
3. **build** — host `tsc`, client `tsc`, and the tsdown browser bundle
|
|
151
|
+
4. **test:package** — every CSS module class is present in `lib/client.js`, then `npm pack` and the packed `dsh-prompt-templates --help` shim
|
|
152
|
+
|
|
153
|
+
GitHub Actions (`.github/workflows/verify.yml`) runs the same command with Node 24 on pushes and pull requests to `master` and on `v*` tags. `test:cli` also carries the DSH 0.2.x contract tests (peer version line, patch sandbox, real store execution, slot declarations, icon exports) — upstream drift fails the gate. Repo `scripts/` hold the stable ops entries (branch-budget audit, absorption classification, privacy-checked push). The `@deepseek-ai/*` devDependencies are public npm packages, so CI needs no registry token and no harness checkout.
|
|
154
|
+
|
|
155
|
+
A self-contained sharing test page can be generated with `node tests/clipboard-browser.mjs en` (or `zh`) after build. It includes synthetic copy scenarios and read-only environment checks; see [clipboard verification](docs/clipboard-verification.md) for privacy boundaries and macOS acceptance steps. Generating/parsing the page is not browser acceptance.
|
|
156
|
+
|
|
157
|
+
Still manual, because they need a live harness profile: booting `dsh web`, the browser panel against the real web server, and resume or compaction against a real session log.
|
|
158
|
+
|
|
159
|
+
### Maintainer release workflow
|
|
160
|
+
|
|
161
|
+
Publishing requires separate owner authorization. Use `bash scripts/release.sh "<subject>"` only on **master**, with either:
|
|
162
|
+
|
|
163
|
+
- a version-only package bump plus the matching non-empty release notes (all other changes already landed, and HEAD equals remote master); or
|
|
164
|
+
- a clean, exact `chore(release): <version> — <subject>` commit containing only that version bump and its notes. At most this one commit may be ahead of remote master.
|
|
165
|
+
|
|
166
|
+
The same subject must be supplied on a pre-publish resume. Leading/trailing whitespace is rejected before verification or commit, rather than silently normalizing a title that Git may trim. Immediately before creating a release commit, staged paths and Git-normalized blobs are checked; the commit is limited to the two release paths so foreign staging is not absorbed. Raw working-file hashes still detect changed inputs when CRLF normalization is active. The script checks branch, package identity, allowed paths, actual remote master and peeled local/remote version tags **before** verification/publishing, then rechecks HEAD, release inputs and staged blobs after verification. Conflicts fail closed; it never switches branches or rewrites existing tags. A remote tag already pointing at the verified commit needs no push, even when local/remote tag objects differ.
|
|
167
|
+
|
|
168
|
+
`DRYRUN=1 bash scripts/release.sh "<subject>"` performs preflight and the ordinary verify/build gate, without a release commit, publish, tag, push or GitHub Release. It is not a promise of zero filesystem writes: normal verification builds and test scratch still run.
|
|
169
|
+
|
|
170
|
+
Pull-back verification uses ignored `tmp/release/run-*/` owned by this invocation. EXIT/INT/TERM clean only a directory whose path and ownership marker still match; a mismatch is preserved for inspection. These are fail-closed preflights, not a filesystem sandbox or a lock against concurrent writers.
|
|
171
|
+
|
|
172
|
+
**No blind retry after publish:** the script does not retry publishing and is not an arbitrary-phase recovery engine. A version already accepted by a registry, a timed-out publish, or an unknown result must be reconciled at that registry before any further action; do not rerun the whole chain to resume its later push/tag/Release steps. The automated regressions use fresh synthetic Git repositories and offline command doubles only, not real publishing or production deployment.
|
|
173
|
+
|
|
174
|
+
## Known limitations
|
|
175
|
+
|
|
176
|
+
- **Session templates need a current session** — with no session open, only global templates are reachable
|
|
177
|
+
- **Injections don't render in the chat transcript** — the DSH chat view omits injected context rows by design (they carry a non-`user` message source); see them in the trajectory tab. Templates with delivery mode **visible** are the exception: they render as ordinary user messages
|
|
178
|
+
- **Use the published npm build for normal installation** — Git/source installations run a `prepare` build and require the development toolchain and dependencies. The documented verification gate uses public `@deepseek-ai/*` packages and requires no harness source checkout; direct Git-URL installation is not verified by that gate. Use `dsh plugin --profile <name> add @nelsonlongxiang/dsh-prompt-templates` for a prebuilt package.
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
MIT
|