@nelsonlongxiang/dsh-prompt-templates 0.13.4 → 0.14.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 +54 -7
- package/README_zh.md +53 -6
- package/cordis.patch.yml +37 -28
- package/docs/clipboard-verification.md +54 -0
- package/docs/event-failure-contract.md +46 -0
- package/docs/spec-event-inject.md +316 -0
- package/docs/test-plan-phase-c.md +183 -0
- package/lib/cli/database.js +17 -10
- package/lib/client/Library.js +95 -14
- package/lib/client/Panel.js +2 -1
- package/lib/client/PromptTab.js +2 -2
- package/lib/client/api.js +20 -0
- package/lib/client/clipboard.js +86 -0
- package/lib/client/index.js +4 -1
- package/lib/client/locales.js +42 -6
- package/lib/client.js +424 -29
- package/lib/client.js.map +1 -1
- package/lib/event-detect.js +99 -0
- package/lib/event-features.js +220 -0
- package/lib/event-inject.js +270 -0
- package/lib/event-store.js +327 -0
- package/lib/evolution-default.js +20 -0
- package/lib/index.js +57 -3
- package/lib/store.js +26 -5
- package/lib/types/client/api.d.ts +37 -0
- package/lib/types/client/clipboard.d.ts +26 -0
- package/lib/types/client/locales.d.ts +42 -6
- package/lib/types/client/slots.d.ts +11 -2
- package/lib/types/event-detect.d.ts +79 -0
- package/lib/types/event-features.d.ts +81 -0
- package/lib/types/event-inject.d.ts +117 -0
- package/lib/types/event-store.d.ts +146 -0
- package/lib/types/evolution-default.d.ts +8 -0
- package/lib/types/index.d.ts +13 -0
- package/lib/types/store.d.ts +9 -1
- package/package.json +104 -98
package/README.md
CHANGED
|
@@ -33,7 +33,9 @@ No Python toolchain required — since 0.3.0 the host half persists templates th
|
|
|
33
33
|
## Sharing (cross-instance copy)
|
|
34
34
|
|
|
35
35
|
- The row ⧉ button shares **one template**; the category tab ⧉ shares **a whole category** (member templates + the category definition)
|
|
36
|
-
- The
|
|
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.
|
|
37
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
|
|
38
40
|
- What is shared is the **raw text**: `{{date}}`/`{{turn}}` re-expand at delivery on the receiving instance
|
|
39
41
|
|
|
@@ -43,9 +45,22 @@ Each template (global or session-scoped) carries its own **switch + interval N**
|
|
|
43
45
|
|
|
44
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
|
|
45
47
|
- A boundary round is never injected twice, even across restarts or step retries
|
|
46
|
-
- Config persists in the plugin's SQLite database (schema
|
|
48
|
+
- Config persists in the plugin's SQLite database (schema v5); `injectEnabled: false` in the patch config silences **scheduled injection only** — event reminders (below) have their own independent master switch `eventInject.enabled`
|
|
47
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)
|
|
48
50
|
|
|
51
|
+
## Event reminders (off by default)
|
|
52
|
+
|
|
53
|
+
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.
|
|
54
|
+
|
|
55
|
+
- Two switches in series, both off by default: the deployment master `eventInject.enabled`, then each rule's toggle. The panel's ⚙ dropdown displays the master switch **read-only** and manages rule toggles, threshold/cooldown, and the read-only episode ledger; changing the master switch still requires deployment configuration.
|
|
56
|
+
- 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
|
|
57
|
+
- 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
|
|
58
|
+
- 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.
|
|
59
|
+
- 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
|
|
60
|
+
- Delivery is at-least-once with dedup against the session log, so restarts and rejected steps neither lose nor duplicate a reminder
|
|
61
|
+
- 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
|
|
62
|
+
- 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)
|
|
63
|
+
|
|
49
64
|
## Template variables
|
|
50
65
|
|
|
51
66
|
Placeholders `{{date}}` `{{time}}` `{{datetime}}` `{{weekday}}` `{{session}}` `{{turn}}` expand **at delivery time** — insert, send-now, interject, and scheduled injection all expand:
|
|
@@ -59,7 +74,7 @@ Placeholders `{{date}}` `{{time}}` `{{datetime}}` `{{weekday}}` `{{session}}` `{
|
|
|
59
74
|
```text
|
|
60
75
|
src/ TypeScript plugin (host half + browser half)
|
|
61
76
|
index.ts Host: owns the TS store, exposes the HTTP routes
|
|
62
|
-
store.ts Pure-TS
|
|
77
|
+
store.ts Pure-TS store over node:sqlite (database schema v5)
|
|
63
78
|
inject.ts Host: scheduled auto-injection on the pre-step waterfall
|
|
64
79
|
invariant.ts Host: registers the package's invariant companion
|
|
65
80
|
cli/ The sync CLI (export/diff/merge/import) shipped as bin
|
|
@@ -74,7 +89,7 @@ The store is pure TS inside the host half; no child process is spawned.
|
|
|
74
89
|
|
|
75
90
|
## Security
|
|
76
91
|
|
|
77
|
-
- Template content reaches a model request in exactly two ways: as ordinary user text the user chose to insert, or as scheduled auto-injection of templates where the switch was explicitly enabled — every injection is a durable session event
|
|
92
|
+
- Template **content** reaches a model request in exactly two ways: as ordinary user text the user chose to insert, or as scheduled auto-injection of templates where the switch was explicitly enabled — every 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
|
|
78
93
|
- The panel talks to the host store over the Host's plugin routes only; no extra listener, no outbound network
|
|
79
94
|
|
|
80
95
|
## Database sync CLI
|
|
@@ -99,7 +114,22 @@ dsh-prompt-templates import --db /path/to/db.sqlite3 --in merged.json --apply \
|
|
|
99
114
|
--expect-db-sha256 <db-sha256> --confirm-summary-hash <dry-run-summary-sha256> --output=json
|
|
100
115
|
```
|
|
101
116
|
|
|
102
|
-
`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
|
|
117
|
+
`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).
|
|
118
|
+
|
|
119
|
+
## Repository layout
|
|
120
|
+
|
|
121
|
+
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:
|
|
122
|
+
|
|
123
|
+
| Path | Responsibility |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `src/` | Host plugin, CLI, and browser-client sources |
|
|
126
|
+
| `scripts/` | Rerunnable ops entries: `patrol.sh`, `branch-audit.sh`, `remote-heads.sh`, `push-master.sh`, `release.sh` |
|
|
127
|
+
| `docs/` | Human-facing documents: specs, release notes, handover; the npm package ships only the explicitly listed user/acceptance guides |
|
|
128
|
+
| `tests/` | `node:test` suites behind `pnpm verify` |
|
|
129
|
+
| `images/` | Static assets referenced by the READMEs |
|
|
130
|
+
| `tmp/<task>/` | Git-ignored scratch; automated tests use `tmp/test-runs/` via `tests/temp-dir.mjs`; task lifetime only, never in git |
|
|
131
|
+
| `lib/`, `node_modules/` | Build output and dependencies — ignored, never tracked |
|
|
132
|
+
| `.npmrc`, `.claude/`, `.obelisk/` | Local tool state (registry config, workbench junctions, agent memories) — ignored, never tracked |
|
|
103
133
|
|
|
104
134
|
## Development
|
|
105
135
|
|
|
@@ -116,15 +146,32 @@ pnpm verify:release # alias of pnpm verify
|
|
|
116
146
|
3. **build** — host `tsc`, client `tsc`, and the tsdown browser bundle
|
|
117
147
|
4. **test:package** — every CSS module class is present in `lib/client.js`, then `npm pack` and the packed `dsh-prompt-templates --help` shim
|
|
118
148
|
|
|
119
|
-
GitHub Actions (`.github/workflows/verify.yml`) runs the same command on pushes and pull requests to `master
|
|
149
|
+
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.
|
|
150
|
+
|
|
151
|
+
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.
|
|
120
152
|
|
|
121
153
|
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.
|
|
122
154
|
|
|
155
|
+
### Maintainer release workflow
|
|
156
|
+
|
|
157
|
+
Publishing requires separate owner authorization. Use `bash scripts/release.sh "<subject>"` only on **master**, with either:
|
|
158
|
+
|
|
159
|
+
- a version-only package bump plus the matching non-empty release notes (all other changes already landed, and HEAD equals remote master); or
|
|
160
|
+
- 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.
|
|
161
|
+
|
|
162
|
+
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.
|
|
163
|
+
|
|
164
|
+
`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.
|
|
165
|
+
|
|
166
|
+
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.
|
|
167
|
+
|
|
168
|
+
**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.
|
|
169
|
+
|
|
123
170
|
## Known limitations
|
|
124
171
|
|
|
125
172
|
- **Session templates need a current session** — with no session open, only global templates are reachable
|
|
126
173
|
- **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
|
|
127
|
-
- **
|
|
174
|
+
- **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.
|
|
128
175
|
|
|
129
176
|
## License
|
|
130
177
|
|
package/README_zh.md
CHANGED
|
@@ -33,7 +33,9 @@ dsh plugin --profile web add @nelsonlongxiang/dsh-prompt-templates
|
|
|
33
33
|
## 分享(跨实例复制)
|
|
34
34
|
|
|
35
35
|
- 行内 ⧉ 按钮分享**单模板**;类目 tab 旁 ⧉ 分享**整类目**(成员模板 + 类目定义)
|
|
36
|
-
-
|
|
36
|
+
- **分享模板 JSON / 分享分类 JSON** 传递带 `format`/`version` 标记的分享载荷,不是单独的提示词正文;无文件、无网络。
|
|
37
|
+
- 自动复制先用浏览器 Clipboard API,再尝试兼容复制命令;两者都失败时展示只读的**手动复制分享 JSON** 面板,保留完全相同的载荷。全选后按 Ctrl+C / ⌘C,再粘贴到目标实例的导入框。面板区分 API 缺失、页面未聚焦、写入拒绝和安全限制,不据此判断系统剪贴板损坏。
|
|
38
|
+
- 限制取决于浏览器与页面环境:普通局域网 HTTP 可能缺该 API;`http://127.0.0.1` 等回环来源虽用 HTTP 也可能属于可信来源。无需修改全局安全设置,也不会读取剪贴板。
|
|
37
39
|
- 目标实例工具栏「导入」粘贴解析:缺失类目自动补建;**同名同域模板弹覆盖确认**——覆盖=更新现有模板(内容/描述/分类/注入配置),拒绝=跳过;完成提示「新建/覆盖/跳过」三计数
|
|
38
40
|
- 分享的是**原始文本**:`{{date}}`/`{{turn}}` 等变量在目标实例投递时按其上下文重新展开
|
|
39
41
|
|
|
@@ -43,9 +45,22 @@ dsh plugin --profile web add @nelsonlongxiang/dsh-prompt-templates
|
|
|
43
45
|
|
|
44
46
|
- 注入内容是一条持久的 `<system-reminder>` 用户消息,记入会话日志(source kind `prompt-template-schedule`),重放与审计可精确还原模型所见
|
|
45
47
|
- 同一边界轮绝不重复注入——跨重启、跨步骤重试都不例外
|
|
46
|
-
- 配置持久化在插件 SQLite 库(schema
|
|
48
|
+
- 配置持久化在插件 SQLite 库(schema v5);patch 配置里的 `injectEnabled: false` 只关**定时注入**——事件提醒(见下)有独立总开关 `eventInject.enabled`,互不控制
|
|
47
49
|
- 每条模板可选交付模式:**静默**(默认,只进模型上下文)或**对话流可见**(以普通用户消息渲染,带 ⚙️ 定时注入标记)
|
|
48
50
|
|
|
51
|
+
## 事件提醒(默认关闭)
|
|
52
|
+
|
|
53
|
+
除了按固定轮次,插件还可以**根据刚发生的行动**提醒 Agent:观察工具的最终结果,识别两类问题——**重复准备**(反复手工带上同一段前缀,比如环境变量加解释器绝对路径,任务部分不同)和**重复失败**(同一目标以相同方式反复失败,或成功后又失败)——然后在下一次模型决策前追加一条短提醒,包括定时注入会跳过的工具结果那一步。
|
|
54
|
+
|
|
55
|
+
- 两级开关串联,默认全关:部署级总开关 `eventInject.enabled`,加上每条规则自己的开关——面板 ⚙ 下拉可管理规则开关、门槛/冷却与只读问题台账;总开关本体留在部署配置里
|
|
56
|
+
- 介入时机:工具结果落地之后、**同轮下一次模型决策之前**追加提醒。它拦不住首次违规,也撤销不了已发生的副作用或已并行发出的兄弟调用
|
|
57
|
+
- 存的是什么:指纹(哈希)加一条长度受限、启发式脱敏的参数摘要。不整存原始参数/输出,但摘要仍可能带上未被掩码的参数片段;摘要永不作为指令或授权
|
|
58
|
+
- 失败分类优先取 `isError` 及错误码,再取整数 `meta.exitCode`(含零);只有元数据没有有效退出码时,`bash` 适配才读取最后一个文本片段的精确尾行 `[exit code: N]`。输出里的成功/失败等任意措辞不改变分类;命令也能自行打印同形标记,因此回退存在误报可能。`ok` 仅代表工具层完成,不等于任务已验证成功。字段优先级、记录宿主限制与未测项见[失败契约](docs/event-failure-contract.md)。
|
|
59
|
+
- 有预算:默认每个**用户轮**最多一条(长自治轮因此最多一条)、有字数上限、每条规则有冷却(默认 3 轮)、每个问题有次数上限;没有新证据就不提醒
|
|
60
|
+
- 投递是"至少一次 + 按会话日志去重",重启或步骤被拒都不会丢失或重复
|
|
61
|
+
- 插件只把问题标到 `notified`。`changed` / `repeated` 只是弱行为信号不是结论:同工具跑一条无关命令也可能翻转它。结案(`verified`、`rejected` 等)走 `PATCH …/event-episodes/<id>`,必须带证据引用——只有完整轨迹复核才算验证完成
|
|
62
|
+
- 提醒是 user-role 消息:不是用户指令,不授予权限。Agent 该怎么处理以 Agent Atelier 的 `references/improvement-loop.md` 为准;设计见 [docs/spec-event-inject.md](docs/spec-event-inject.md)
|
|
63
|
+
|
|
49
64
|
## 模板变量
|
|
50
65
|
|
|
51
66
|
模板内容中的 `{{date}}` `{{time}}` `{{datetime}}` `{{weekday}}` `{{session}}` `{{turn}}` 在**投递时**展开——插入、直接发送、插话打断、定时注入四条路全部生效:
|
|
@@ -59,7 +74,7 @@ dsh plugin --profile web add @nelsonlongxiang/dsh-prompt-templates
|
|
|
59
74
|
```text
|
|
60
75
|
src/ TypeScript 插件(host 面 + 浏览器面)
|
|
61
76
|
index.ts Host:持有 TS 存储,暴露 HTTP 路由
|
|
62
|
-
store.ts 纯 TS
|
|
77
|
+
store.ts 纯 TS 存储(node:sqlite,数据库 schema v5)
|
|
63
78
|
inject.ts Host:挂在 pre-step waterfall 上的定时注入
|
|
64
79
|
invariant.ts Host:注册本包的 invariant 伴生插件
|
|
65
80
|
cli/ 随 bin 发布的同步 CLI(export/diff/merge/import)
|
|
@@ -73,7 +88,7 @@ cordis.patch.yml Bundle patch:挂插件行
|
|
|
73
88
|
|
|
74
89
|
## 安全
|
|
75
90
|
|
|
76
|
-
-
|
|
91
|
+
- 模板**内容**进入模型请求只有两条路:用户主动插入的普通用户文本,或开关被显式打开的定时注入模板——每次注入都是一条持久会话事件。事件提醒是独立通道:不携带模板内容,开关也与定时注入互不控制
|
|
77
92
|
- 面板仅经 Host 的插件路由访问 host 存储;无额外监听、无外联网络
|
|
78
93
|
|
|
79
94
|
## 数据同步 CLI
|
|
@@ -98,7 +113,22 @@ dsh-prompt-templates import --db /path/to/db.sqlite3 --in merged.json --apply \
|
|
|
98
113
|
--expect-db-sha256 <db-sha256> --confirm-summary-hash <dry-run-summary-sha256> --output=json
|
|
99
114
|
```
|
|
100
115
|
|
|
101
|
-
`import` 仅按模板 ID 插入/更新,绝不自动删除;未知字段、错误 schema、hash 漂移、同名异 ID,以及超过 `--max-changes`(默认 100)的变更均阻断。schema-v2 快照(无注入字段)仍可导入——注入项默认关闭;导出恒为
|
|
116
|
+
`import` 仅按模板 ID 插入/更新,绝不自动删除;未知字段、错误 schema、hash 漂移、同名异 ID,以及超过 `--max-changes`(默认 100)的变更均阻断。schema-v2 快照(无注入字段)仍可导入——注入项默认关闭;导出恒为 schema v4(仅模板与类目,不含事件策略及运行状态)。
|
|
117
|
+
|
|
118
|
+
## 目录定义
|
|
119
|
+
|
|
120
|
+
声明的目录布局——根级白名单之外即散落,巡检门(`scripts/patrol.sh` 的 dir convention 段)会判失败:
|
|
121
|
+
|
|
122
|
+
| 路径 | 职责 |
|
|
123
|
+
|---|---|
|
|
124
|
+
| `src/` | 宿主插件、CLI 与浏览器客户端源码 |
|
|
125
|
+
| `scripts/` | 可重跑运维入口:`patrol.sh`、`branch-audit.sh`、`remote-heads.sh`、`push-master.sh`、`release.sh` |
|
|
126
|
+
| `docs/` | 面向人的文档:spec、发布说明、交接指南;npm 包仅携带白名单明确列出的使用/验收说明 |
|
|
127
|
+
| `tests/` | `pnpm verify` 背后的 `node:test` 套件 |
|
|
128
|
+
| `images/` | README 引用的静态图 |
|
|
129
|
+
| `tmp/<任务>/` | 已忽略的临时区;自动测试经 `tests/temp-dir.mjs` 使用 `tmp/test-runs/`;限任务生命周期,永不入库 |
|
|
130
|
+
| `lib/`、`node_modules/` | 构建产物与依赖——忽略,永不入库 |
|
|
131
|
+
| `.npmrc`、`.claude/`、`.obelisk/` | 本地工具状态(registry 配置、工坊 junction、代理记忆)——忽略,永不入库 |
|
|
102
132
|
|
|
103
133
|
## 开发
|
|
104
134
|
|
|
@@ -117,13 +147,30 @@ pnpm verify:release # pnpm verify 的别名
|
|
|
117
147
|
|
|
118
148
|
GitHub Actions(`.github/workflows/verify.yml`)在指向 `master` 的 push / pull request 以及 `v*` tag 上用 Node 24 跑同一命令。`test:cli` 还含 DSH 0.2.x 契约测试(peer 版本线 / patch 沙箱 / store 真执行 / slot 声明 / 图标导出),上游漂移当场爆红。仓库 `scripts/` 提供运维稳定入口(分支预算审计 / 吸收分类 / 隐私排查推送)。`@deepseek-ai/*` devDependencies 来自公网 npm,CI 不需要 registry token,也不需要 harness 检出。
|
|
119
149
|
|
|
150
|
+
构建后运行 `node tests/clipboard-browser.mjs zh`(或 `en`)可生成自包含分享测试页,内含合成复制场景和只读环境检查;隐私边界与 macOS 复验步骤见[复制验收说明](docs/clipboard-verification.md)。生成/解析页面不等于浏览器验收。
|
|
151
|
+
|
|
120
152
|
仍需人工、因为它们依赖真实 harness profile:启动 `dsh web`、浏览器面板对接真实 web server,以及用真实会话日志验证 resume / compaction。
|
|
121
153
|
|
|
154
|
+
### 维护者发布流程
|
|
155
|
+
|
|
156
|
+
发布需另有属主明确授权。`bash scripts/release.sh "<主题>"` 只允许在 **master** 上执行,输入仅限两种:
|
|
157
|
+
|
|
158
|
+
- 仅改版本号的 package bump,加本版非空发布说明;其他变更已入主干,当前 HEAD 与远端 master 一致;或
|
|
159
|
+
- 已提交且干净的精确 `chore(release): <版本> — <主题>` 提交,仅含本版 bump 与说明。未推历史最多这一条提交。
|
|
160
|
+
|
|
161
|
+
首次发布前续接必须传相同主题。主题首尾空白在 verify/提交前直接拒绝,不静默修剪,以免 Git 修剪标题后造成身份不一致。生成发布提交前会核对暂存路径与 Git 规范化后的 blob,提交命令限定为本版两个路径,不吸收外来暂存;启用 CRLF 规范化时仍用原始工作文件摘要检测材料漂移。脚本在 verify/publish 之前核对分支、包身份、允许路径、实际远端 master、本地/远端版本标签剥离后的目标,并在 verify 后重查 HEAD、材料与暂存 blob。冲突即拒绝,不自行切分支、不改写已有标签;远端标签已指向验证提交时无需推送,即使两端标签对象不同。
|
|
162
|
+
|
|
163
|
+
`DRYRUN=1 bash scripts/release.sh "<主题>"` 只走预检和正常 verify/构建门,不生成发布提交、不 publish/tag/push/创建 GitHub Release。它不是“零落盘”:常规构建与测试临时物仍会生成。
|
|
164
|
+
|
|
165
|
+
拉回直验只用本次拥有的忽略目录 `tmp/release/run-*/`;EXIT/INT/TERM 仅清理路径与所有权标记均相符的目录,身份不符则保留排查。这是拒绝式预检,不是文件系统沙箱,也不是阻止并发写入的锁。
|
|
166
|
+
|
|
167
|
+
**发布后不盲重试**:脚本不自动重发,也不是任意阶段的恢复器。registry 已接受版本、publish 超时或结果未知时,必须先对该 registry 对账;不能为续做后面的 push/tag/Release 而重跑整条链。自动回归只用新建合成 Git 仓与离线命令 stub,不代表真实发布或生产部署已验证。
|
|
168
|
+
|
|
122
169
|
## 已知限制
|
|
123
170
|
|
|
124
171
|
- **会话模板需要当前会话**——无会话打开时只能用全局模板
|
|
125
172
|
- **注入不在对话流中渲染**——DSH 对话视图按设计省略注入的 context 行(消息 source 非 `user`);可在轨迹 tab 查看。交付模式为"对话流可见"的模板是例外:以普通用户消息渲染
|
|
126
|
-
-
|
|
173
|
+
- **正式使用优先安装 npm 发布构建**——Git/源码安装会执行 `prepare` 构建,需要开发工具链和依赖。本仓所述验证门禁使用公网 `@deepseek-ai/*` 包,不需要 harness 源码检出;该门禁没有验证直接 Git-URL 安装。使用预构建包请运行 `dsh plugin --profile <name> add @nelsonlongxiang/dsh-prompt-templates`。
|
|
127
174
|
|
|
128
175
|
## 许可证
|
|
129
176
|
|
package/cordis.patch.yml
CHANGED
|
@@ -1,28 +1,37 @@
|
|
|
1
|
-
# dsh-prompt-templates bundle patch: mounts the prompt-templates plugin into
|
|
2
|
-
# the host composition of a dsh profile. The plugin registers its
|
|
3
|
-
# /plugins/dsh-prompt-templates routes into the shared web server and its
|
|
4
|
-
# settings namespace into the shared settings document, so it needs no realm.
|
|
5
|
-
#
|
|
6
|
-
# Install: `dsh plugin --profile <name> add <this package>` (npm, a local
|
|
7
|
-
# path, or Git). The `dsh plugin` command pnpm-installs the package into the
|
|
8
|
-
# profile and reconciles it into the profile's `dsh.profile.bundles` layer
|
|
9
|
-
# list.
|
|
10
|
-
#
|
|
11
|
-
# The host half is pure TS: templates persist through `node:sqlite`
|
|
12
|
-
# directly inside the host process (no Python child, no pythonBridge
|
|
13
|
-
# service dependency). The patch JS sandbox exposes `process`; the default
|
|
14
|
-
# database path already resolves under $DSH_HOME, so only overrides need it.
|
|
15
|
-
- insert:
|
|
16
|
-
- id: prompt-templates
|
|
17
|
-
# Node-resolvable package name — must stay in sync with package.json
|
|
18
|
-
# `name`. Quoted because `@` is a reserved YAML indicator.
|
|
19
|
-
name: '@nelsonlongxiang/dsh-prompt-templates'
|
|
20
|
-
config:
|
|
21
|
-
# Explicit SQLite database path so persistence lands under
|
|
22
|
-
# $DSH_HOME/ext/prompt-templates/ regardless of cwd or environment drift.
|
|
23
|
-
dbPath: !!js >
|
|
24
|
-
`${(process.env.DSH_HOME ?? `${process.getBuiltinModule('node:os').homedir()}/.dsh`).replace(/\\/g, '/')}/ext/prompt-templates/db.sqlite3`
|
|
25
|
-
# Scheduled auto-injection (defaults shown; the schema fills them when
|
|
26
|
-
# omitted, so these lines are optional):
|
|
27
|
-
# injectEnabled: true — master switch; false keeps the listener pass-through
|
|
28
|
-
# injectMaxEvery: 1000 — upper bound accepted for a template's interval
|
|
1
|
+
# dsh-prompt-templates bundle patch: mounts the prompt-templates plugin into
|
|
2
|
+
# the host composition of a dsh profile. The plugin registers its
|
|
3
|
+
# /plugins/dsh-prompt-templates routes into the shared web server and its
|
|
4
|
+
# settings namespace into the shared settings document, so it needs no realm.
|
|
5
|
+
#
|
|
6
|
+
# Install: `dsh plugin --profile <name> add <this package>` (npm, a local
|
|
7
|
+
# path, or Git). The `dsh plugin` command pnpm-installs the package into the
|
|
8
|
+
# profile and reconciles it into the profile's `dsh.profile.bundles` layer
|
|
9
|
+
# list.
|
|
10
|
+
#
|
|
11
|
+
# The host half is pure TS: templates persist through `node:sqlite`
|
|
12
|
+
# directly inside the host process (no Python child, no pythonBridge
|
|
13
|
+
# service dependency). The patch JS sandbox exposes `process`; the default
|
|
14
|
+
# database path already resolves under $DSH_HOME, so only overrides need it.
|
|
15
|
+
- insert:
|
|
16
|
+
- id: prompt-templates
|
|
17
|
+
# Node-resolvable package name — must stay in sync with package.json
|
|
18
|
+
# `name`. Quoted because `@` is a reserved YAML indicator.
|
|
19
|
+
name: '@nelsonlongxiang/dsh-prompt-templates'
|
|
20
|
+
config:
|
|
21
|
+
# Explicit SQLite database path so persistence lands under
|
|
22
|
+
# $DSH_HOME/ext/prompt-templates/ regardless of cwd or environment drift.
|
|
23
|
+
dbPath: !!js >
|
|
24
|
+
`${(process.env.DSH_HOME ?? `${process.getBuiltinModule('node:os').homedir()}/.dsh`).replace(/\\/g, '/')}/ext/prompt-templates/db.sqlite3`
|
|
25
|
+
# Scheduled auto-injection (defaults shown; the schema fills them when
|
|
26
|
+
# omitted, so these lines are optional):
|
|
27
|
+
# injectEnabled: true — master switch; false keeps the listener pass-through
|
|
28
|
+
# injectMaxEvery: 1000 — upper bound accepted for a template's interval
|
|
29
|
+
# Event-triggered reminders (OFF by default; rules also ship disabled
|
|
30
|
+
# and are enabled per rule via PATCH …/event-policies/<rule>):
|
|
31
|
+
# eventInject:
|
|
32
|
+
# enabled: false — master switch, independent of injectEnabled
|
|
33
|
+
# maxPerTurn: 1 — reminders per session per turn (retries included)
|
|
34
|
+
# maxChars: 600 — character budget of one merged reminder
|
|
35
|
+
# maxAttempts: 3 — delivery attempts before a reminder is marked failed
|
|
36
|
+
# observationWindow: 200 — redacted observations kept per session
|
|
37
|
+
# ignoreTools: [] — tool names never observed
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# 分享复制:隔离浏览器复验
|
|
2
|
+
|
|
3
|
+
用于 issue #14 的可重复验收。先验插件复制链,再核原故障页面;二者结果不混用。默认只用合成模板,不连接 DSH、不改模板库/权限/全局设置,不读取剪贴板。
|
|
4
|
+
|
|
5
|
+
## 1. 生成与打开
|
|
6
|
+
|
|
7
|
+
在已有依赖和已核对的维护检出运行(不需要新安装):
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
pnpm build
|
|
11
|
+
node tests/clipboard-browser.mjs zh # 或 en
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
输出为本项目 `tmp/test-runs/clipboard-browser-*/index.html` 的 file URL。该 HTML 内联当前构建的插件与本地 React,可在浏览器打开,也可把这个**合成页面**带到获准的 macOS 测试机;不用复制真实 DSH profile 或模板库。记录插件提交、构建摘要、操作系统、浏览器版本、访问方式;不同 origin/iframe 条件不能外推。
|
|
15
|
+
|
|
16
|
+
页面提供“复制场景”下拉框及“刷新只读环境”。原生/兼容成功场景会覆盖剪贴板为合成 JSON,开始前由操作者确认剪贴板中无需要保留的内容;其余模拟失败场景不会写系统剪贴板。不要为测试读取剪贴板、改浏览器安全策略或开启全局权限。
|
|
17
|
+
|
|
18
|
+
## 2. 交互判据
|
|
19
|
+
|
|
20
|
+
| 场景 | 操作与期待 |
|
|
21
|
+
|---|---|
|
|
22
|
+
| API 缺失 | 点分享分类/单模板;出现只读 JSON,自动聚焦/全选;提示 API 不可用而非系统剪贴板损坏 |
|
|
23
|
+
| 写入拒绝 | 选择 Denied 再点分享;显示 NotAllowedError 与拒绝文案,仍能手动复制 |
|
|
24
|
+
| 安全限制 | 选择 Security restriction;显示 SecurityError,保留相同 JSON |
|
|
25
|
+
| 手动键盘流 | Tab 到全选,Enter;再 Tab 到关闭,Enter;面板关闭,焦点回实际触发的分享按钮,而非之前获焦的输入框 |
|
|
26
|
+
| 鼠标不抢焦点 | 先点搜索框,再鼠标点单模板分享(行会 preventDefault 保持原焦点);关闭回退面板后焦点必须回这次分享按钮。类目分享也以实际触发按钮为准,不依赖浏览器自动focus |
|
|
27
|
+
| 兼容复制 | 选择 Compatibility,明确允许合成剪贴板写入后点分享;只有浏览器 execCommand 返回 true 才提示成功,否则降为手动 |
|
|
28
|
+
| 原生复制 | 选择 Native,明确允许合成剪贴板写入后点分享;只有实际 writeText resolved 才提示成功;拒绝则兼容/手动降级 |
|
|
29
|
+
|
|
30
|
+
JSON 应保留中文、换行和 `{{date}}` 字面量;分类分享包含分类定义,单模板分享不混入其他模板。关闭不会删除模板。不要用“复制成功”文案冒充内容已被目标实例验收。
|
|
31
|
+
|
|
32
|
+
自动回归 `tests/client-clipboard.test.ts` 覆盖错误分类、同一载荷、焦点/选区恢复、旧请求晚失败不再执行兼容复制;异步乱序的浏览器探针可使用夹具的 delayed 模式,不需改生产。
|
|
33
|
+
|
|
34
|
+
## 3. 原故障页面:先只读核验
|
|
35
|
+
|
|
36
|
+
以下片段不读取或写入剪贴板:
|
|
37
|
+
|
|
38
|
+
```js
|
|
39
|
+
({
|
|
40
|
+
origin: location.origin,
|
|
41
|
+
secure: window.isSecureContext,
|
|
42
|
+
clipboardAPI: typeof navigator.clipboard?.writeText,
|
|
43
|
+
focused: document.hasFocus(),
|
|
44
|
+
embedded: window.self !== window.top
|
|
45
|
+
})
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`http://127.0.0.1` 等回环来源可以属于可信来源,不能仅凭 HTTP 判断不安全。API 存在不等于写入获准,NotAllowedError 也不单独证明权限、焦点或系统哪一项是根因。保留实际异常类与页面环境,不输出模板内容、凭证或原始错误中可能的秘密。
|
|
49
|
+
|
|
50
|
+
原页面复验仍需获得该目标的操作授权、实际故障/修复制品身份与完整轨迹;没有入口或证据时记 NOT_RUN,不擅自重装/重启/改全局设置。
|
|
51
|
+
|
|
52
|
+
## 4. 记录与收口
|
|
53
|
+
|
|
54
|
+
在原 issue/PR 留:精确提交/制品、系统与浏览器、页面条件、逐项 PASS/FAIL/NOT_RUN、是否写入合成剪贴板、限制与下一步。合成夹具 PASS 不关闭 macOS 原现场未复验项,不代替独立运维复验或授权合并。页面临时产物留在项目 tmp;确认记录可追溯后按获准生命周期处理,不把唯一证据交给临时区。
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Event-reminder tool-result failure contract
|
|
2
|
+
|
|
3
|
+
Status: recorded from a real Windows test host at published DSH version **0.2.2-rc.3**.
|
|
4
|
+
The source commit SHA of that installed build was not captured. This is a version/platform-scoped record, not proof of source-SHA pinning or compatibility with every 0.2.x build.
|
|
5
|
+
The isolated host ran `web --port 3081`, with event observation explicitly enabled. Samples were recorded on 2026-11-16 from its durable session log (`session.v4.jsonl.zstd`, event `tool/result`).
|
|
6
|
+
|
|
7
|
+
## Recorded host samples
|
|
8
|
+
|
|
9
|
+
The recorded cases were exit 0, exit 1, exit 3, exit 7, a lone `[` command, and a normal command. Only the observed fields below are claimed; the marker alone does not identify the shell failure cause.
|
|
10
|
+
|
|
11
|
+
Fields below are under `event.data`: `message` carries the tool message, and `meta` is a sibling, **not** `message.meta`. The live `tools/result` listener and the durable event are different surfaces.
|
|
12
|
+
|
|
13
|
+
| Recorded case | `message.isError` | `message.content` text | `meta` | `message.error` |
|
|
14
|
+
|---|---|---|---|---|
|
|
15
|
+
| success / exit 0 | `false` | `(no output)` | `{ cwd }` | absent |
|
|
16
|
+
| exit 1/3/7 | `false` | `(no output)\n[exit code: 1]` | `{ cwd }` | absent |
|
|
17
|
+
| lone `[` command | `false` | `(no output)\n[exit code: 1]` | `{ cwd }` | absent |
|
|
18
|
+
|
|
19
|
+
No structured exit code was present in these samples, and `isError` remained false even for the non-zero commands. The exit-1/3/7 samples all carried marker `1`. This does **not** establish that every command, shell, platform or host build collapses all non-zero codes to 1.
|
|
20
|
+
|
|
21
|
+
Before the adapter, these command failures were classified `ok`; their observation `exit_code` values were null. The `isError: true` / `error.info.code` branch is covered by synthetic fixtures, not by a real tool exception in this recording.
|
|
22
|
+
|
|
23
|
+
## Current classification priority
|
|
24
|
+
|
|
25
|
+
1. `isError: true` selects `error:<error.info.code>`, or `error:unknown` when the code is absent.
|
|
26
|
+
2. An integer `meta.exitCode` decides the exit path: non-zero selects `error:exit:<code>`; **zero selects `ok` and suppresses a conflicting text marker**. This structured shape is supported by fixtures but was not observed on the recorded host.
|
|
27
|
+
3. Only when metadata has no valid integer exit code, the `bash` adapter checks the last non-whitespace line of the last text part for `[exit code: N]`: non-zero selects `error:exit:<N>`, zero selects `ok`. Other tools ignore this text marker.
|
|
28
|
+
4. Otherwise the result is `ok`, including when exit data is missing or invalid.
|
|
29
|
+
|
|
30
|
+
`ok` means **tool-layer completion**, not verified task success. A command can exit zero without accomplishing its task; this plugin does not infer business success. A valid metadata zero is different from a missing or string-valued exit code.
|
|
31
|
+
|
|
32
|
+
## Boundaries
|
|
33
|
+
|
|
34
|
+
- The marker is an unauthenticated text fallback, not a structured field. A command can print a lookalike marker and cause a false positive. The adapter cannot prove whether the shell or command emitted the line.
|
|
35
|
+
- Arbitrary output wording such as success/failure does not affect the result. Do not broaden the adapter into mixed-output keyword matching.
|
|
36
|
+
- Classification does not persist output bodies. The observer stores derived outcome/exit-code fields, fingerprints, and a length-bounded, heuristically redacted **argument** summary. Unmasked argument fragments can remain; redaction is not a no-secrets guarantee.
|
|
37
|
+
- A reminder is advisory, not a new instruction, permission, hard guard, independent verification or production enablement.
|
|
38
|
+
- A different build may move or omit the marker. Re-record against the actual version, platform and available source SHA before claiming support.
|
|
39
|
+
|
|
40
|
+
## Verification levels
|
|
41
|
+
|
|
42
|
+
- Historical test-host contract recording: the samples above were observed. The original host source SHA is unknown.
|
|
43
|
+
- Pure fixture coverage: `tests/event-features.test.ts`, including metadata-zero precedence, conflicting marker, CRLF marker, tool scoping and output exclusion from argument summaries.
|
|
44
|
+
- Historical end-to-end reminder delivery was recorded separately on test host 3081 (issue #11 history), not by these unit tests.
|
|
45
|
+
- Real tool exception, timeout, cancellation, Linux/macOS and different host versions: **NOT_RUN / not covered** by this recording.
|
|
46
|
+
- Unit fixtures and historical host observations do not constitute an independent OPS acceptance or an all-platform PASS.
|