dsh-better-edit 0.2.0 → 0.2.1
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/CHANGELOG.md +18 -0
- package/README.md +156 -52
- package/README.zh.md +113 -46
- package/lib/guidance.js +282 -0
- package/lib/index.js +48 -32
- package/lib/prompts.js +53 -49
- package/lib/types/guidance.d.ts +98 -0
- package/lib/types/index.d.ts +4 -0
- package/lib/types/prompts.d.ts +19 -9
- package/package.json +2 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,24 @@ Entries link to the originating spec issue in [pi-hashline-edit-lsz](https://git
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.2.1] - 2026-08-18
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Configurable per-preset tool guidance (issues #7, #8; tickets #9–#13): the four `tool:*` prompt sections resolve from plain-markdown override files keyed by agent preset — `$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md` — with an optional `order` front-matter. On first boot the plugin seeds each shipped preset (`standard`, `code`, `minimal`, `cordis`) with its guidance as editable files plus a root README documenting the scheme. Per section the chain is `<preset>/<section>.md` → compiled default; files are read once per agent at session-start, so edits apply to new sessions. Deployments without the `agentPresets` service keep the compiled defaults untouched.
|
|
14
|
+
Default orders sit at 130–133, above the built-in tool-guidance band (100–116 in the shipped
|
|
15
|
+
dsh), so a same-order section merge with unrelated tool guidance cannot occur out of the box; the
|
|
16
|
+
seeded preset files expose that `order` as editable front-matter.
|
|
17
|
+
- Default guidance text simplified per the writing-for-agents principles; the `*_GUIDELINES` constants unified on `*_GUIDANCE`.
|
|
18
|
+
- Thanks to [@R-LEI2536](https://github.com/R-LEI2536) for requesting configurable per-preset prompts and for the design input that shaped this release (issue [#7](https://github.com/Rianico/dsh-better-edit/issues/7)).
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
|
|
22
|
+
- Benchmark extended to a third arm, `@oh-my-pi/hashline`: same corpus, same 12 replacements, two modes (per-edit `seq` with renumbered lines + one-document `batch` fixed to original line numbers). Payloads are built from the package's published grammar and validated before counting (the package is Bun-only, so it cannot run under the Node benchmark). Honest result, reported as such: hashline saves 31% vs `str_replace` on the session (43% on multi-line ranges) and remains the plugin's claim; the compact patch language saves 42% per edit / 53% batched — and this README says so. `npm run benchmark` stays byte-deterministic (verified over repeated runs).
|
|
23
|
+
- READMEs (English and 中文) refined along ponytail-style lines: "How It Compares" gains an `@oh-my-pi/hashline` column plus a same-lineage/different-jobs comparison; the Benchmark section documents all three arms, adds an honest "regenerate, don't trust" reproducibility note, and widens the scope-and-honesty block with what the payload numbers do *not* capture (renumber/tag-chase cost, block ops, Bun-vs-Node, tool-pair vs patcher library).
|
|
24
|
+
- `package.json` keywords now include `oh-my-pi` alongside `hashline`.
|
|
25
|
+
- Roadmap gains a first-class decision item: close or justify the gap vs `@oh-my-pi/hashline` (payload-lighter by 42%/53% vs 31%, with block ops / registers / `REM`/`MV` / multi-hunk documents / pluggable fs we do not support — against correctness costs: unverified line numbers, renumber-per-edit, best-effort merge on stale tags, model skill floor). A reference record lives at `../oh-my-pi.md` (workspace-level, outside this repo): the token comparison, the correctness asymmetry, the ability-by-ability status, and the decision rationale.
|
|
26
|
+
|
|
9
27
|
## [0.2.0] - 2026-08-16
|
|
10
28
|
|
|
11
29
|
### Changed
|
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<strong>Hash-anchored edit tools for DeepSeek Harness.<br>
|
|
9
|
-
Edit by content address — not line numbers. Fewer tokens. Zero misapplied edits.</strong>
|
|
9
|
+
Edit by content address — not by line numbers, not by string replacement. Fewer tokens. More attention for real work. Zero misapplied edits.</strong>
|
|
10
10
|
</p>
|
|
11
11
|
|
|
12
12
|
<p align="center">
|
|
@@ -18,7 +18,6 @@
|
|
|
18
18
|
<a href="#quick-start">Quick Start</a> •
|
|
19
19
|
<a href="#why-hashline">Why Hashline</a> •
|
|
20
20
|
<a href="#benchmark">Benchmark</a> •
|
|
21
|
-
<a href="#installation">Installation</a> •
|
|
22
21
|
<a href="#tools">Tools</a> •
|
|
23
22
|
<a href="#acknowledgments">Acknowledgments</a>
|
|
24
23
|
</p>
|
|
@@ -57,6 +56,25 @@ Not for one-line touch-ups (near parity) or new files (`write`). It pays off in
|
|
|
57
56
|
|
|
58
57
|
## Quick Start
|
|
59
58
|
|
|
59
|
+
### Install
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
dsh plugin --profile <name> add dsh-better-edit # from npm
|
|
63
|
+
dsh plugin --profile <name> add /path/to/dsh-better-edit # from a local checkout
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The profile's next session runs with the hashline tools installed. To verify the layer is active:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
| Requirement | |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| Node | `^22.19.0 \|\| >=24.0.0` (dsh's requirement; the store uses `node:sqlite`) |
|
|
75
|
+
| Profile | a dsh profile (`dsh plugin` initializes one on first use) |
|
|
76
|
+
| Backends | sandboxed / remote filesystems supported (writes go through `ctx.fs`) |
|
|
77
|
+
|
|
60
78
|
`read` returns every line prefixed by its hash — the hash *is* the line's address:
|
|
61
79
|
|
|
62
80
|
```text
|
|
@@ -84,6 +102,52 @@ and produces a diff with fresh anchors, so the next edit verifies cleanly with n
|
|
|
84
102
|
kQm │ }
|
|
85
103
|
```
|
|
86
104
|
|
|
105
|
+
## Configuring Guidance per Preset
|
|
106
|
+
|
|
107
|
+
The `tool:read` / `tool:edit` / `tool:batch_edit` / `tool:undo_last_edit` guidance sections are
|
|
108
|
+
plain-markdown files, overridable per agent preset. Override files live in the plugin's shared
|
|
109
|
+
home — never the workspace store:
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
(default home `~/.dsh`, so `~/.dsh/plugins/dsh-better-edit/`). The section table:
|
|
116
|
+
|
|
117
|
+
| File | Section | Default order |
|
|
118
|
+
| --- | --- | --- |
|
|
119
|
+
| `read.md` | `tool:read` | 130 |
|
|
120
|
+
| `edit.md` | `tool:edit` | 131 |
|
|
121
|
+
| `batch_edit.md` | `tool:batch_edit` | 132 |
|
|
122
|
+
| `undo_last_edit.md` | `tool:undo_last_edit` | 133 |
|
|
123
|
+
|
|
124
|
+
On first boot the plugin seeds the four shipped presets — `standard/`, `code/`,
|
|
125
|
+
`minimal/`, `cordis/` — each with the compiled guidance as editable files (plus
|
|
126
|
+
`order` front-matter), so every preset's guidance starts editable rather than
|
|
127
|
+
blank. A `README.md` at the plugin-home root documents the scheme. Files are
|
|
128
|
+
seeded once and never rewritten, so your edits survive. A preset directory may
|
|
129
|
+
hold only the sections you want to override — the rest fall through to the
|
|
130
|
+
compiled defaults.
|
|
131
|
+
|
|
132
|
+
A file is pure prose unless it opens with an `order` front-matter fence, which moves the section in
|
|
133
|
+
the assembled system prompt:
|
|
134
|
+
|
|
135
|
+
```md
|
|
136
|
+
---
|
|
137
|
+
order: 150
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
<section text>
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Per section, resolution reads `<preset>/<section>.md`, else the compiled
|
|
144
|
+
default. Files are read once per agent at session-start, so edits apply to new
|
|
145
|
+
sessions — never mid-session. A preset with no seeded directory (e.g. a
|
|
146
|
+
user-authored one) falls back to the compiled defaults unless you copy a seeded
|
|
147
|
+
dir to its name. A deployment without the `agentPresets` service (no preset
|
|
148
|
+
roster) keeps the compiled defaults and never touches these files; presets are
|
|
149
|
+
never required.
|
|
150
|
+
|
|
87
151
|
## Why Hashline
|
|
88
152
|
|
|
89
153
|
**Token-saving.** An edit call carries `remove_from` / `remove_to` (two 3-char hashes) plus the
|
|
@@ -92,6 +156,11 @@ text verbatim. On a 12-edit session over a realistic file this is **31% fewer ou
|
|
|
92
156
|
on multi-line ranges) — and these are *output* tokens, billed at ~5-6× the input rate. See the
|
|
93
157
|
[benchmark](#benchmark).
|
|
94
158
|
|
|
159
|
+
**But this was never about “fewest tokens.”** Savings scale with the replaced text — near parity on
|
|
160
|
+
one-line touch-ups — and a compact patch language like [@oh-my-pi/hashline](#how-it-compares) can
|
|
161
|
+
emit a lighter payload still (42–53% on the same session). The point is the *right* kind of edit
|
|
162
|
+
call: no re-typing old code, and nothing for the model to track except two stable content addresses.
|
|
163
|
+
|
|
95
164
|
**Correctness.** Every resolved edit range is verified against the exact lines the model was shown.
|
|
96
165
|
A stale, never-served, or ambiguous range is hard-rejected **before anything is written**, and the
|
|
97
166
|
current range is echoed back as fresh anchors (reject-and-serve) — the retry needs no `read`.
|
|
@@ -102,74 +171,108 @@ pins a line by what it *is*, not by where it used to sit.
|
|
|
102
171
|
|
|
103
172
|
### How It Compares
|
|
104
173
|
|
|
105
|
-
| | hashline `edit` | `str_replace` |
|
|
174
|
+
| | hashline `edit` | `str_replace` (Claude Code / Codex) | @oh-my-pi/hashline patch |
|
|
106
175
|
| --- | :---: | :---: | :---: |
|
|
107
|
-
| Replaced text echoed in the call | ✅
|
|
108
|
-
|
|
|
109
|
-
|
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
176
|
+
| Replaced text never echoed in the call | ✅ 2 hashes only | ❌ verbatim | ✅ `+` rows only |
|
|
177
|
+
| Lines addressed by | content hash | text match | number + file-content tag |
|
|
178
|
+
| Verified against what the model saw | ✅ every line | ❌ first match wins | ~ file version only |
|
|
179
|
+
| Stale file detected | ✅ rejects, fresh anchors | ❌ may match wrong spot | ✅ tag mismatch → refuse or 3-way merge |
|
|
180
|
+
| Anchors survive edits above | ✅ content-addressed | ✅ content-based | ❌ renumber + new tag |
|
|
181
|
+
| Chained edits without re-reads | ✅ diff serves fresh anchors | ~ | ~ via edit-response numbers |
|
|
182
|
+
| Unambiguous when text repeats | ✅ boundary anchors verified | ❌ first occurrence | ~ position, unverified per line |
|
|
183
|
+
| Wrong-line edit never lands silently | ✅ every line verified | ❌ first match wins | ~ possible in principle (tag checks version, not lines) |
|
|
184
|
+
| Block ops / registers / `MV` / `REM` | ❌ | ❌ | ✅ |
|
|
185
|
+
| One document per change | ❌ per-edit call | ❌ per-edit call | ✅ multi-hunk patch |
|
|
186
|
+
| Runtime | ✅ Node (dsh) | — | ⚠️ Bun only |
|
|
187
|
+
| Undo | ✅ persisted | ❌ | ❌ not in scope |
|
|
188
|
+
|
|
189
|
+
> `~` = occasionally / inconsistently. `@oh-my-pi/hashline` is a compact line-anchored patch language
|
|
190
|
+
> ([npm](https://www.npmjs.com/package/@oh-my-pi/hashline), [repo](https://github.com/can1357/oh-my-pi/tree/main/packages/hashline)):
|
|
191
|
+
> `[path#tag]` headers bind each hunk to a full-file content hash, `PUT N.=M:` addresses lines by
|
|
192
|
+
> number, and every edit renumbers — take the next numbers and tag from the edit response or a fresh `read`.
|
|
193
|
+
|
|
194
|
+
**Different jobs, same lineage.** Both descend from the
|
|
195
|
+
[harness-problem](https://stencil.so/blog/the-harness-problem) insight that the model should never
|
|
196
|
+
re-type old code. `@oh-my-pi/hashline` is a **patch-language library** — payload-light (42% saved
|
|
197
|
+
per edit, 53% in a single batch document, see [benchmark](#benchmark)), with syntactic block ops
|
|
198
|
+
(`PUT N*:`), registers, `REM`/`MV`, multi-hunk documents, a pluggable filesystem for any backend,
|
|
199
|
+
and session-aware 3-way-merge recovery on stale tags. This plugin is a **dsh tool pair**: `read`
|
|
200
|
+
hands the model 3-char content hashes, `edit` takes two of them, and every resolved line is verified
|
|
201
|
+
against the served state — no line numbers to renumber, no tag to re-fetch, a wrong anchor can never
|
|
202
|
+
land on the wrong line, and `undo_last_edit` survives restarts. Its trade-offs: a JSON envelope per
|
|
203
|
+
edit costs a little payload, there are no block ops, and it lives inside dsh (Node) rather than as a
|
|
204
|
+
standalone patcher (Bun). Pick hashline-the-library for a cross-backend patch format; pick
|
|
205
|
+
hashline-the-tool for verified, content-addressed edits in your agent.
|
|
206
|
+
|
|
207
|
+
### Correctness in edge cases
|
|
208
|
+
|
|
209
|
+
The token benchmark measures the payload the model emits — it assumes the model gets every
|
|
210
|
+
address right, for free. Correctness is where the two hashline implementations actually diverge.
|
|
211
|
+
These are the real failure modes from the harness-problem literature (wrong-line edits, drift,
|
|
212
|
+
repeated text), and what each tool does when they hit:
|
|
213
|
+
|
|
214
|
+
| Edge case | hashline `edit` (this plugin) | @oh-my-pi/hashline patch |
|
|
215
|
+
| --- | --- | --- |
|
|
216
|
+
| Wrong address (off-by-one anchor / line number) | **Impossible** — anchors resolve to specific lines; every resolved line is verified against served state, rejected **before** anything is written | **Possible** — a wrong line number against a current tag applies **silently** at the wrong place; the tag proves the file version, never the lines |
|
|
217
|
+
| File changed on disk after the model's view | Hard reject + fresh anchors echoed (reject-and-serve); retry needs no `read` | Tag mismatch → refuse **or best-effort 3-way merge** onto unknown current content |
|
|
218
|
+
| An edit above shifts the file | Nothing shifts — anchors are content addresses; the diff serves fresh anchors | **Every edit renumbers** — “RE-GROUND AFTER EVERY EDIT” is the format's own #1 rule; the model carries the bookkeeping |
|
|
219
|
+
| Repeated / identical text | Per-line hashes are unique (collision-resolved); ambiguity → `[E_AMBIGUOUS_ANCHOR]` | Position-based, so repeats don't confuse it — but the position itself is unverified |
|
|
220
|
+
| Lines never shown to the model | `[E_RANGE_UNSERVED]` — hard reject with fresh anchors | Undisplayed hunks rejected — same reliance on the model knowing what it saw |
|
|
221
|
+
| Mid-expression / wrong block node | Irrelevant — any verified line range is valid | Grammar rules + `PUT N*:` node choice; mispointing (anchoring `def` orphans its decorator) silently lands wrong; no syntax check |
|
|
222
|
+
| Multi-edit batch fails mid-way | `batch_edit` — atomic, all-or-nothing; the failing item is echoed as fresh serves | Multi-section patches preflighted up front — also atomic |
|
|
223
|
+
|
|
224
|
+
> The 42–53% oh-my-pi payload saving is a lighter wire format; the table above is what that
|
|
225
|
+
> format asks the model to hold in its head instead — renumbering, tag-chasing, node choice —
|
|
226
|
+
> the exact component that fails most (46–51% patch-failure rates on replace-style edits). This
|
|
227
|
+
> plugin's 31% is the price of a contract where a wrong edit cannot land, and any rejection
|
|
228
|
+
> needs no re-read.
|
|
118
229
|
|
|
119
230
|
## Benchmark
|
|
120
231
|
|
|
121
232
|
Measured on the same 103-line file with the same 12 replacements (8 single-line, 4 multi-line of
|
|
122
|
-
3/6/10/15 lines), tokenized with the pinned `js-tiktoken` `cl100k_base
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
|
|
|
233
|
+
3/6/10/15 lines), tokenized with the pinned `js-tiktoken` `cl100k_base`. Three arms emit the same
|
|
234
|
+
replacements: this plugin's `edit` (two 3-char anchors), a `str_replace` tool (old text echoed
|
|
235
|
+
verbatim), and [`@oh-my-pi/hashline`](https://www.npmjs.com/package/@oh-my-pi/hashline) in both of
|
|
236
|
+
its modes — one `[path#tag]` section per edit (`seq`) and one multi-hunk batch document (`batch`):
|
|
237
|
+
|
|
238
|
+
| Criterion | hashline | str_replace | oh-my-pi seq / batch |
|
|
239
|
+
| ----------- | :---: | :---: | :---: |
|
|
240
|
+
| Replaced text sent over the wire | ✅ never | ❌ every edit | ✅ never |
|
|
241
|
+
| Output tokens saved (12-edit session) | ✅ **31%** | ❌ 0% | ✅ **42% / 53%** |
|
|
242
|
+
| Multi-line range savings (3–15 lines) | ✅ **29–47%** | ❌ 0% | ✅ **40–53%** |
|
|
243
|
+
| Effective cost at 5× output pricing | ✅ **~1.4× less** | ❌ 1× | ✅ **~1.7× / ~2.1× less** |
|
|
244
|
+
| Ranges verified against served state | ✅ 100% | ❌ none | ~ file version only |
|
|
245
|
+
| Line numbers the model must track | ✅ none — content anchors | ✅ none — text match | ❌ renumber every edit |
|
|
246
|
+
| Deterministic, reproducible locally | ✅ `npm run benchmark` | — | — |
|
|
132
247
|
|
|
133
248
|
### Reproducible
|
|
134
249
|
|
|
135
250
|
The numbers above are **deterministic and you can reproduce them locally** — `npm run benchmark`:
|
|
136
251
|
|
|
137
|
-
| Scenario | Lines | hashline | str_replace |
|
|
252
|
+
| Scenario | Lines | hashline | str_replace | oh-my-pi seq | oh-my-pi batch |
|
|
138
253
|
| --- | :---: | :---: | :---: | :---: | :---: |
|
|
139
|
-
| single-line ×8 | 1 | 309 | 324 |
|
|
140
|
-
| multi-line ×4 | 3–15 | 393 | 691 |
|
|
141
|
-
| **TOTAL ×12** | | **702** | **1015** | **
|
|
254
|
+
| single-line ×8 | 1 | 309 | 324 | 241 | — |
|
|
255
|
+
| multi-line ×4 | 3–15 | 393 | 691 | 349 | — |
|
|
256
|
+
| **TOTAL ×12** | | **702** | **1015** | **590** | **480** |
|
|
257
|
+
|
|
258
|
+
Saved vs `str_replace`: hashline **313 (31%)** · oh-my-pi per-edit **425 (42%)** · oh-my-pi batch **535 (53%)**.
|
|
142
259
|
|
|
143
260
|
The script is deterministic by construction: a frozen corpus, a content-addressed edit script that
|
|
144
|
-
self-checks (a reformatted corpus throws instead of silently changing what's measured),
|
|
145
|
-
tokenizer
|
|
261
|
+
self-checks (a reformatted corpus throws instead of silently changing what's measured), a pinned
|
|
262
|
+
tokenizer, and oh-my-pi payloads validated against the package's published grammar before counting.
|
|
263
|
+
Because everything is fixed, `npm run benchmark` gives everyone the same result — the numbers in
|
|
264
|
+
this README are a snapshot of that run; regenerate, don't trust.
|
|
146
265
|
|
|
147
266
|
> **Scope & honesty.** The benchmark measures **request-payload tokens** — what the model emits per
|
|
148
267
|
> edit call — with identical read traffic excluded (it cancels) and identical replacement text.
|
|
149
268
|
> It does **not** model transcription failure and retries, which is where the real-world gap is
|
|
150
269
|
> largest: the original [harness-problem](https://stencil.so/blog/the-harness-problem) post reported
|
|
151
270
|
> a **61% output-token reduction** and patch-failure drops from 46–51% to near zero after switching
|
|
152
|
-
> to anchored edits.
|
|
153
|
-
>
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
```sh
|
|
158
|
-
dsh plugin --profile <name> add dsh-better-edit # from npm
|
|
159
|
-
dsh plugin --profile <name> add /path/to/dsh-better-edit # from a local checkout
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
The profile's next session runs with the hashline tools installed. To verify the layer is active:
|
|
163
|
-
|
|
164
|
-
```sh
|
|
165
|
-
dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
| Requirement | |
|
|
169
|
-
| --- | --- |
|
|
170
|
-
| Node | `^22.19.0 \|\| >=24.0.0` (dsh's requirement; the store uses `node:sqlite`) |
|
|
171
|
-
| Profile | a dsh profile (`dsh plugin` initializes one on first use) |
|
|
172
|
-
| Backends | sandboxed / remote filesystems supported (writes go through `ctx.fs`) |
|
|
271
|
+
> to anchored edits. It also does **not** model what a line-numbered format costs the model *between*
|
|
272
|
+
> calls — renumbering and re-fetching the file tag after every edit — nor block-op power, nor the
|
|
273
|
+
> Bun-vs-Node runtime difference, nor the fact that `@oh-my-pi/hashline` is a standalone patcher
|
|
274
|
+
> while this plugin is a dsh tool pair with `read`/`edit`/`undo`. Full methodology, the per-edit
|
|
275
|
+
> table, and the complete limitation list in [`benchmark/README.md`](benchmark/README.md). The correctness gap behind those numbers is spelled out above in [Correctness in edge cases](#correctness-in-edge-cases).
|
|
173
276
|
|
|
174
277
|
## Tools
|
|
175
278
|
|
|
@@ -250,7 +353,7 @@ dsh-better-edit/
|
|
|
250
353
|
│ ├── write-hook.ts # auto-read appended to write results
|
|
251
354
|
│ ├── served-store.ts # per-workspace SQLite store (node:sqlite)
|
|
252
355
|
│ └── workspace.ts # session-cwd AsyncLocalStorage carrier
|
|
253
|
-
├── benchmark/ # reproducible hashline-vs-str_replace token benchmark
|
|
356
|
+
├── benchmark/ # reproducible hashline-vs-str_replace-vs-oh-my-pi token benchmark
|
|
254
357
|
│ └── corpus/ # frozen 103-line fixture
|
|
255
358
|
├── test/ # 615 tests (ported + regression)
|
|
256
359
|
├── assets/ # logo + banner
|
|
@@ -290,6 +393,7 @@ served-tail truncation fix, reproducible benchmark, EN + 中文 READMEs, publish
|
|
|
290
393
|
|
|
291
394
|
<details><summary>Next</summary>
|
|
292
395
|
|
|
396
|
+
- **Close or justify the gap vs @oh-my-pi/hashline** (reference: [`../oh-my-pi.md`](../oh-my-pi.md)). The sibling patch language is payload-lighter — 42%/53% vs our 31% vs `str_replace` on the benchmark, because a bare patch document skips the JSON envelope we pay per call — and offers four abilities we do not support: syntactic block ops (`PUT N*:`), registers + `REM`/`MV`, one multi-hunk document per change, and a pluggable filesystem. The counterweight is correctness: its line numbers are unverified (a wrong number on a current tag lands silently), every edit renumbers, stale tags trigger best-effort 3-way merge instead of verification, and the grammar raises the model skill floor. Decide each ability reject-or-adopt on its own merits — the payload gap alone is not a reason to switch formats.
|
|
293
397
|
- Verify 0.1.6 live in a dsh session after the served-tail fix.
|
|
294
398
|
- Upstream the served-tail truncation fix to pi-hashline-edit-lsz / upstream (their `upsertServed`
|
|
295
399
|
never truncates either).
|
package/README.zh.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<strong>面向 DeepSeek Harness 的哈希锚定编辑工具。<br>
|
|
9
|
-
|
|
9
|
+
按内容地址编辑——不靠行号,也不靠字符串替换。更省 token。更多注意力留给真正的工作。绝不会改错行。</strong>
|
|
10
10
|
</p>
|
|
11
11
|
|
|
12
12
|
<p align="center">
|
|
@@ -18,7 +18,6 @@
|
|
|
18
18
|
<a href="#快速开始">快速开始</a> •
|
|
19
19
|
<a href="#为什么用-hashline">为什么用 Hashline</a> •
|
|
20
20
|
<a href="#基准测试">基准测试</a> •
|
|
21
|
-
<a href="#安装">安装</a> •
|
|
22
21
|
<a href="#工具">工具</a> •
|
|
23
22
|
<a href="#致谢">致谢</a>
|
|
24
23
|
</p>
|
|
@@ -53,6 +52,25 @@ Hashline 用两个哈希代替旧文本——**编辑 token 减少 31%**(多
|
|
|
53
52
|
|
|
54
53
|
## 快速开始
|
|
55
54
|
|
|
55
|
+
### 安装
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
dsh plugin --profile <name> add dsh-better-edit # 从 npm
|
|
59
|
+
dsh plugin --profile <name> add /path/to/dsh-better-edit # 从本地源码
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
该 profile 的下一个会话将带着 hashline 工具运行。验证该层是否生效:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
dsh --profile <name> --dump-config # 会显示 "# == dsh-better-edit" 层
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
| 要求 | |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| Node | `^22.19.0 \|\| >=24.0.0`(dsh 的要求;存储使用 `node:sqlite`) |
|
|
71
|
+
| Profile | 一个 dsh profile(首次使用 `dsh plugin` 时初始化) |
|
|
72
|
+
| 后端 | 支持沙箱/远程文件系统(写入经 `ctx.fs`) |
|
|
73
|
+
|
|
56
74
|
`read` 返回的每一行都带有哈希前缀——哈希*就是*这一行的地址:
|
|
57
75
|
|
|
58
76
|
```text
|
|
@@ -80,73 +98,121 @@ kQm│}
|
|
|
80
98
|
kQm │ }
|
|
81
99
|
```
|
|
82
100
|
|
|
101
|
+
## 按 preset 配置指引
|
|
102
|
+
|
|
103
|
+
`tool:read` / `tool:edit` / `tool:batch_edit` / `tool:undo_last_edit` 四个提示词片段的指引是
|
|
104
|
+
纯 Markdown 文件,可以按 agent preset 覆盖。覆盖文件位于插件的共享主目录——绝不放在工作区存储中:
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
(默认主目录为 `~/.dsh`,即 `~/.dsh/plugins/dsh-better-edit/`)。片段对照表:
|
|
111
|
+
|
|
112
|
+
| 文件 | 提示词片段 | 默认 order |
|
|
113
|
+
| --- | --- | --- |
|
|
114
|
+
| `read.md` | `tool:read` | 130 |
|
|
115
|
+
| `edit.md` | `tool:edit` | 131 |
|
|
116
|
+
| `batch_edit.md` | `tool:batch_edit` | 132 |
|
|
117
|
+
| `undo_last_edit.md` | `tool:undo_last_edit` | 133 |
|
|
118
|
+
|
|
119
|
+
首次启动时插件会为四个随附 preset——`standard/`、`code/`、`minimal/`、`cordis/`——各自写入编译内置的
|
|
120
|
+
可编辑指引文件(含 `order` front-matter),让每个 preset 的指引一开始就可编辑,而不是空白。插件主目录
|
|
121
|
+
根的 `README.md` 说明整套机制。文件只在首次写入时生成、之后绝不被覆盖,因此你的修改会保留。preset 目录
|
|
122
|
+
里可以只放你想覆盖的片段文件,其余自动回退到编译内置默认值。
|
|
123
|
+
|
|
124
|
+
文件默认为纯文本;除非以 `order` front-matter 栅栏开头,它会改变该片段在组装后的系统提示中的位置:
|
|
125
|
+
|
|
126
|
+
```md
|
|
127
|
+
---
|
|
128
|
+
order: 150
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
<片段文本>
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
每个片段的解析顺序为:读取 `<preset>/<section>.md`,否则回退到编译内置默认值。文件只在 agent 的
|
|
135
|
+
session-start 时读取一次,因此修改只影响新会话——绝不影响进行中的会话。没有种子目录的 preset(例如
|
|
136
|
+
用户自建的)会回退到编译内置默认值,除非你把某个种子目录复制成它的名字。没有 `agentPresets` 服务
|
|
137
|
+
(即没有 preset 名册)的部署继续使用编译内置默认值,完全不会触碰这些文件;
|
|
138
|
+
preset 从来不是必需的。
|
|
139
|
+
|
|
83
140
|
## 为什么用 Hashline
|
|
84
141
|
|
|
85
142
|
**省 token。** 一次编辑调用只携带 `remove_from` / `remove_to`(两个 3 字符哈希)加替换文本——从不回显被替换的文本。`str_replace` 调用则必须逐字复现被替换的文本。在一个真实文件上的 12 次编辑会话中,这可以**减少 31% 的输出 token**(多行范围达 43%)——而且这些是*输出* token,按输入的约 5-6 倍计费。见[基准测试](#基准测试)。
|
|
86
143
|
|
|
144
|
+
**但这从来不是“最省 token”。** 节省随被替换文本的规模增长——单行微调时几乎持平——而且像 [@oh-my-pi/hashline](#对比) 这样的紧凑补丁语言还能发出更轻的负载(同一会话中 42–53%)。关键在于**正确形态**的编辑调用:不复述旧代码,模型除了两个稳定的内容地址外无需跟踪任何东西。
|
|
145
|
+
|
|
87
146
|
**正确性。** 每个解析出的编辑范围都会与模型实际看到的行逐行核对。过期、从未提供或歧义的范围会在**写入任何内容之前**被硬性拒绝,并把当前范围以全新锚点的形式回显(reject-and-serve)——重试无需 `read`。
|
|
88
147
|
|
|
89
148
|
**面向 Agent 的现代编辑范式。** 内容地址锚点与行号无关:编辑文件的一部分,其余行的哈希保持不变,因此连续编辑无需重新读取。模型按行**是什么**来定位,而不是按它之前在第几行。
|
|
90
149
|
|
|
91
150
|
### 对比
|
|
92
151
|
|
|
93
|
-
| | hashline `edit` | `str_replace
|
|
152
|
+
| | hashline `edit` | `str_replace`(Claude Code / Codex) | @oh-my-pi/hashline 补丁 |
|
|
94
153
|
| --- | :---: | :---: | :---: |
|
|
95
|
-
|
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
103
|
-
|
|
154
|
+
| 调用中永不回显被替换文本 | ✅ 只有两个哈希 | ❌ 逐字回显 | ✅ 只有 `+` 行 |
|
|
155
|
+
| 按什么定位行 | 内容哈希 | 文本匹配 | 行号 + 文件内容标签 |
|
|
156
|
+
| 对照模型所见内容校验 | ✅ 每一行 | ❌ 取第一个匹配 | ~ 仅文件版本 |
|
|
157
|
+
| 检测文件已过期 | ✅ 拒绝并回传新锚点 | ❌ 可能匹配到错误位置 | ✅ 标签不匹配 → 拒绝或三方合并 |
|
|
158
|
+
| 上方编辑后锚点依然有效 | ✅ 内容寻址 | ✅ 基于内容 | ❌ 重新编号 + 新标签 |
|
|
159
|
+
| 连续编辑无需重读 | ✅ diff 提供新锚点 | ~ | ~ 从编辑响应取行号 |
|
|
160
|
+
| 文本重复时无歧义 | ✅ 边界锚点需校验 | ❌ 取第一个出现 | ~ 按位置,行未逐行校验 |
|
|
161
|
+
| 错行编辑永远不会悄悄落盘 | ✅ 每一行都校验 | ❌ 取第一个匹配 | ~ 原则上可能(标签只校验版本,不校验行) |
|
|
162
|
+
| 块操作 / 寄存器 / `MV` / `REM` | ❌ | ❌ | ✅ |
|
|
163
|
+
| 一次变更一个文档 | ❌ 每次一个调用 | ❌ 每次一个调用 | ✅ 多 hunk 补丁 |
|
|
164
|
+
| 运行时 | ✅ Node(dsh) | — | ⚠️ 仅 Bun |
|
|
165
|
+
| 撤销 | ✅ 持久化 | ❌ | ❌ 不在范围内 |
|
|
166
|
+
|
|
167
|
+
> `~` = 偶尔/不稳定。`@oh-my-pi/hashline` 是一种紧凑的行锚定补丁语言([npm](https://www.npmjs.com/package/@oh-my-pi/hashline)、[仓库](https://github.com/can1357/oh-my-pi/tree/main/packages/hashline)):`[path#tag]` 头把每个 hunk 绑定到全文件内容哈希,`PUT N.=M:` 按行号定位;每次编辑都会重新编号——下一次的行号与标签取自编辑响应或重新 `read`。
|
|
168
|
+
|
|
169
|
+
**不同的工作,同一条血脉。** 两者都源于 [harness-problem](https://stencil.so/blog/the-harness-problem) 的洞见:模型绝不该复述旧代码。`@oh-my-pi/hashline` 是**补丁语言库**——负载更轻(每次编辑省 42%,单个批量文档省 53%,见[基准测试](#基准测试)),支持语法块操作(`PUT N*:`)、寄存器、`REM`/`MV`、多 hunk 文档、可插拔文件系统(任何后端),以及标签过期时的会话感知三方合并恢复。本插件则是一对 **dsh 工具**:`read` 把 3 字符内容哈希交给模型,`edit` 取其中两个,并对解析出的每一行对照已提供状态校验——无需重新编号、无需重新取标签、错误锚点永远不可能落到错误的行,`undo_last_edit` 重启后依然有效。代价:每次编辑的 JSON 外壳会多一点负载、没有块操作,并且它活在 dsh(Node)内部,而不是独立补丁器(Bun)。要跨后端的补丁格式选 hashline 库;要在 Agent 里做可校验、内容寻址的编辑,选 hashline 工具。
|
|
170
|
+
|
|
171
|
+
### 边界情况下的正确性
|
|
172
|
+
|
|
173
|
+
token 基准测试衡量的是模型发出的负载——它假设模型每次都能拿到**正确**的地址,而且免费。正确性才是两种 hashline 实现真正分道扬镳的地方。下面是 harness-problem 文献里的真实故障模式(错行编辑、漂移、重复文本),以及各自在遭遇它们时的表现:
|
|
174
|
+
|
|
175
|
+
| 边界情况 | hashline `edit`(本插件) | @oh-my-pi/hashline 补丁 |
|
|
176
|
+
| --- | --- | --- |
|
|
177
|
+
| 错误地址(锚点/行号差一行) | **不可能**——锚点解析到具体行;解析出的每一行都对照已提供状态校验,在**写入任何内容之前**被拒绝 | **可能**——当前标签下的错误行号会**悄悄**落到错误位置;标签只证明文件版本,从不证明行 |
|
|
178
|
+
| 模型查看后文件在磁盘上被改动 | 硬拒绝 + 回传新锚点(reject-and-serve);重试无需 `read` | 标签不匹配 → 拒绝**或**对未知的当前内容做尽力而为的三方合并 |
|
|
179
|
+
| 上方编辑导致文件移位 | 什么都不移位——锚点是内容地址;diff 提供新锚点 | **每次编辑都重新编号**——“RE-GROUND AFTER EVERY EDIT” 是它自己的头号规则;账由模型记 |
|
|
180
|
+
| 重复/相同文本 | 每行哈希唯一(冲突已消解);歧义 → `[E_AMBIGUOUS_ANCHOR]` | 基于位置,重复不会混淆——但位置本身未被校验 |
|
|
181
|
+
| 从未展示给模型的行 | `[E_RANGE_UNSERVED]`——硬拒绝并回传新锚点 | 未展示的 hunk 被拒绝——同样依赖模型知道自己看过什么 |
|
|
182
|
+
| 表达式中间 / 错误的块节点 | 无关——任何已校验的行范围都合法 | 语法规则 + `PUT N*:` 节点选择;点错(锚在 `def` 会让装饰器变成孤儿)会悄悄落错;无语法检查 |
|
|
183
|
+
| 多编辑批量中途失败 | `batch_edit`——原子、全有或全无;失败项以新锚点回显 | 多段补丁先预检——同样原子 |
|
|
184
|
+
|
|
185
|
+
> oh-my-pi 42–53% 的负载节省来自更轻的线格式;上表才是该格式反过来要求模型记在脑中的东西——重新编号、追标签、选节点——而这恰恰是最容易出错的组件(替换式编辑的补丁失败率 46–51%)。本插件 31% 的代价买来的是一个“错编辑落不了地、任何拒绝都不需要重读”的契约。
|
|
104
186
|
|
|
105
187
|
## 基准测试
|
|
106
188
|
|
|
107
|
-
在同一份 103 行文件上、用相同的 12 组替换(8 个单行、4 个 3/6/10/15 行多行),以固定的 `js-tiktoken` `cl100k_base`
|
|
189
|
+
在同一份 103 行文件上、用相同的 12 组替换(8 个单行、4 个 3/6/10/15 行多行),以固定的 `js-tiktoken` `cl100k_base` 词表测量。三个被测方发出相同的替换文本:本插件的 `edit`(两个 3 字符锚点)、`str_replace` 工具(逐字回显旧文本)、以及 [`@oh-my-pi/hashline`](https://www.npmjs.com/package/@oh-my-pi/hashline) 的两种模式——每次编辑一个 `[path#tag]` 段(`seq`)和一个多 hunk 批量文档(`batch`):
|
|
108
190
|
|
|
109
|
-
| 指标 | hashline | str_replace |
|
|
110
|
-
| ----------- | :---: | :---: |
|
|
111
|
-
| 被替换文本是否上线 | ✅ 从不 | ❌ 每次编辑都发 |
|
|
112
|
-
| 输出 token 节省(12 次编辑) | ✅ **31%** | ❌ 0% |
|
|
113
|
-
| 多行范围节省(3–15 行) | ✅ **29–47%** | ❌ 0% |
|
|
114
|
-
| 按 5 倍输出计价的实际成本 | ✅ **低约 1.4 倍** | ❌ 1× |
|
|
115
|
-
| 范围对照已提供状态校验 | ✅ 100% | ❌ 无 |
|
|
116
|
-
|
|
|
191
|
+
| 指标 | hashline | str_replace | oh-my-pi seq / batch |
|
|
192
|
+
| ----------- | :---: | :---: | :---: |
|
|
193
|
+
| 被替换文本是否上线 | ✅ 从不 | ❌ 每次编辑都发 | ✅ 从不 |
|
|
194
|
+
| 输出 token 节省(12 次编辑) | ✅ **31%** | ❌ 0% | ✅ **42% / 53%** |
|
|
195
|
+
| 多行范围节省(3–15 行) | ✅ **29–47%** | ❌ 0% | ✅ **40–53%** |
|
|
196
|
+
| 按 5 倍输出计价的实际成本 | ✅ **低约 1.4 倍** | ❌ 1× | ✅ **低约 1.7 倍 / 2.1 倍** |
|
|
197
|
+
| 范围对照已提供状态校验 | ✅ 100% | ❌ 无 | ~ 仅文件版本 |
|
|
198
|
+
| 模型需要跟踪的行号 | ✅ 无——内容锚点 | ✅ 无——文本匹配 | ❌ 每次编辑重新编号 |
|
|
199
|
+
| 确定性、可在本地复现 | ✅ `npm run benchmark` | — | — |
|
|
117
200
|
|
|
118
201
|
### 可复现
|
|
119
202
|
|
|
120
203
|
上面的数字**是确定性的,你可以本地复现**——`npm run benchmark`:
|
|
121
204
|
|
|
122
|
-
| 场景 | 行数 | hashline | str_replace |
|
|
205
|
+
| 场景 | 行数 | hashline | str_replace | oh-my-pi seq | oh-my-pi batch |
|
|
123
206
|
| --- | :---: | :---: | :---: | :---: | :---: |
|
|
124
|
-
| 单行 ×8 | 1 | 309 | 324 |
|
|
125
|
-
| 多行 ×4 | 3–15 | 393 | 691 |
|
|
126
|
-
| **合计 ×12** | | **702** | **1015** | **
|
|
127
|
-
|
|
128
|
-
脚本天然确定:固定语料、内容寻址且自带自检的编辑脚本(语料被重排会直接抛错,而不是悄悄改变测量对象)、固定版本的 tokenizer。因为一切都是固定的,`npm run benchmark` 对每个人都是同一个结果。
|
|
129
|
-
|
|
130
|
-
> **范围与诚实。** 基准测试衡量的是**请求负载 token**——每次编辑调用时模型发出的内容——读文件流量完全相同故已排除(可抵消),替换文本也完全一致。它**没有**建模转录失败与重试,而真实差距恰恰主要在那边:最初的 [harness-problem](https://stencil.so/blog/the-harness-problem) 文章报告改用锚定编辑后**输出 token 减少 61%**,补丁失败率从 46–51% 降至接近零。完整的方法论与局限见 [`benchmark/README.md`](benchmark/README.md)。
|
|
131
|
-
|
|
132
|
-
## 安装
|
|
133
|
-
|
|
134
|
-
```sh
|
|
135
|
-
dsh plugin --profile <name> add dsh-better-edit # 从 npm
|
|
136
|
-
dsh plugin --profile <name> add /path/to/dsh-better-edit # 从本地源码
|
|
137
|
-
```
|
|
207
|
+
| 单行 ×8 | 1 | 309 | 324 | 241 | — |
|
|
208
|
+
| 多行 ×4 | 3–15 | 393 | 691 | 349 | — |
|
|
209
|
+
| **合计 ×12** | | **702** | **1015** | **590** | **480** |
|
|
138
210
|
|
|
139
|
-
|
|
211
|
+
相对 `str_replace` 的节省:hashline **313(31%)** · oh-my-pi 逐次 **425(42%)** · oh-my-pi 批量 **535(53%)**。
|
|
140
212
|
|
|
141
|
-
|
|
142
|
-
dsh --profile <name> --dump-config # 会显示 "# == dsh-better-edit" 层
|
|
143
|
-
```
|
|
213
|
+
脚本天然确定:固定语料、内容寻址且自带自检的编辑脚本(语料被重排会直接抛错,而不是悄悄改变测量对象)、固定版本的 tokenizer,且 oh-my-pi 负载在计数前会对照其发布的语法校验。因为一切都是固定的,`npm run benchmark` 对每个人都是同一个结果——本 README 里的数字就是该次运行的一个快照;重新生成,不要轻信。
|
|
144
214
|
|
|
145
|
-
|
|
146
|
-
| --- | --- |
|
|
147
|
-
| Node | `^22.19.0 \|\| >=24.0.0`(dsh 的要求;存储使用 `node:sqlite`) |
|
|
148
|
-
| Profile | 一个 dsh profile(首次使用 `dsh plugin` 时初始化) |
|
|
149
|
-
| 后端 | 支持沙箱/远程文件系统(写入经 `ctx.fs`) |
|
|
215
|
+
> **范围与诚实。** 基准测试衡量的是**请求负载 token**——每次编辑调用时模型发出的内容——读文件流量完全相同故已排除(可抵消),替换文本也完全一致。它**没有**建模转录失败与重试,而真实差距恰恰主要在那边:最初的 [harness-problem](https://stencil.so/blog/the-harness-problem) 文章报告改用锚定编辑后**输出 token 减少 61%**,补丁失败率从 46–51% 降至接近零。它同样**没有**建模行号格式在调用**之间**让模型付出的代价——每次编辑后重新编号、重新获取文件标签——也不包括块操作能力、Bun 与 Node 的运行时差异,以及 `@oh-my-pi/hashline` 是独立补丁器、而本插件是带 `read`/`edit`/`undo` 的 dsh 工具对这一事实。完整方法论、逐编辑表与完整局限清单见 [`benchmark/README.md`](benchmark/README.md)。这些数字背后的正确性差距见上文[边界情况下的正确性](#边界情况下的正确性)。
|
|
150
216
|
|
|
151
217
|
## 工具
|
|
152
218
|
|
|
@@ -216,7 +282,7 @@ dsh-better-edit/
|
|
|
216
282
|
│ ├── write-hook.ts # 附加到 write 结果的自动读取
|
|
217
283
|
│ ├── served-store.ts # 按工作区的 SQLite 存储(node:sqlite)
|
|
218
284
|
│ └── workspace.ts # 会话 cwd 的 AsyncLocalStorage 载体
|
|
219
|
-
├── benchmark/ # 可复现的 hashline 与
|
|
285
|
+
├── benchmark/ # 可复现的 hashline、str_replace 与 oh-my-pi token 基准测试
|
|
220
286
|
│ └── corpus/ # 固定的 103 行语料
|
|
221
287
|
├── test/ # 615 个测试(移植 + 回归)
|
|
222
288
|
├── assets/ # logo 与 banner
|
|
@@ -251,6 +317,7 @@ npm publish --registry https://registry.npmjs.org # 版本未打 tag 前会被
|
|
|
251
317
|
|
|
252
318
|
<details><summary>下一步</summary>
|
|
253
319
|
|
|
320
|
+
- **缩小或证明与 @oh-my-pi/hashline 的差距**(参考:[`../oh-my-pi.md`](../oh-my-pi.md))。这个兄弟补丁语言负载更轻——基准测试中相对 `str_replace` 省 42%/53%,而我们省 31%,因为它裸文本式的补丁文档跳过了我们每次调用都要付的 JSON 外壳——还提供了我们不支持的四种能力:语法块操作(`PUT N*:`)、寄存器 + `REM`/`MV`、一次变更一个多 hunk 文档、可插拔文件系统。代价在正确性一侧:它的行号未经验证(当前标签下的错行号会静默落盘)、每次编辑都要重新编号、过期标签触发尽力而为的三方合并而非校验、语法也抬高了模型的技能门槛。逐项决定是拒绝还是采纳——负载差距本身不足以成为切换格式的理由。
|
|
254
321
|
- 在 dsh 会话中实测 0.1.7(served-tail 修复之后)。
|
|
255
322
|
- 把 served-tail 截断修复回馈给 pi-hashline-edit-lsz / 上游(他们的 `upsertServed` 同样从不截断)。
|
|
256
323
|
- 对照下一个 dsh 版本重新核对插件接线(当前固定在 `0.1.0-rc.6`;dsh 处于开发者预览阶段,承诺会有破坏性变更)。
|
package/lib/guidance.js
ADDED
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-preset guidance overrides for the hashline tool sections.
|
|
3
|
+
*
|
|
4
|
+
* Each of the four `tool:*` prompt sections the plugin registers has a
|
|
5
|
+
* compiled default rendered from `prompts.ts` (byte-identical to the inline
|
|
6
|
+
* rendering `src/index.ts` uses today). A user can override any section's text
|
|
7
|
+
* and `order` with a plain markdown file keyed by agent preset: the override
|
|
8
|
+
* files live in the plugin's shared home (`$DSH_HOME/plugins/dsh-better-edit`,
|
|
9
|
+
* never the workspace store) and are resolved per section as
|
|
10
|
+
* `<preset>/<section>.md` → compiled default.
|
|
11
|
+
*
|
|
12
|
+
* An override file is pure prose unless it opens with a valid YAML front-matter
|
|
13
|
+
* fence carrying only an `order` key (`---` / `order: N` / `---`); anything
|
|
14
|
+
* else — a missing closing fence, a non-integer `order`, an unknown key —
|
|
15
|
+
* degrades the WHOLE file to prose so the mistake stays visible in the
|
|
16
|
+
* rendered section.
|
|
17
|
+
*
|
|
18
|
+
* Resolution is pure: no cordis services, no harness wiring. The installer
|
|
19
|
+
* ticket reads the resolved sections once per agent at session-start;
|
|
20
|
+
* nothing here watches or caches files.
|
|
21
|
+
* @module dsh-better-edit/guidance
|
|
22
|
+
*/
|
|
23
|
+
import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
|
|
24
|
+
import { join } from "node:path";
|
|
25
|
+
import { BATCH_EDIT_GUIDANCE, EDIT_GUIDANCE, READ_GUIDANCE, UNDO_GUIDANCE, } from "./prompts.js";
|
|
26
|
+
import { errCode } from "./utils.js";
|
|
27
|
+
/** The presets shipped by the harness, each seeded with editable guidance. */
|
|
28
|
+
export const DEFAULT_PRESETS = [
|
|
29
|
+
"standard",
|
|
30
|
+
"code",
|
|
31
|
+
"minimal",
|
|
32
|
+
"cordis",
|
|
33
|
+
];
|
|
34
|
+
/**
|
|
35
|
+
* Render one tool's guidance as its intro line, a blank line, then bullets.
|
|
36
|
+
* Uniform across the four sections: no tool-schema description is duplicated
|
|
37
|
+
* (that already reaches the model through the tool catalog).
|
|
38
|
+
*/
|
|
39
|
+
function guidanceText(g) {
|
|
40
|
+
return [g.intro, "", bulletLines(g.lines)].join("\n");
|
|
41
|
+
}
|
|
42
|
+
function bulletLines(lines) {
|
|
43
|
+
return lines.map((line) => `- ${line}`).join("\n");
|
|
44
|
+
}
|
|
45
|
+
/** The four sections, in default-order sequence. */
|
|
46
|
+
export const GUIDANCE_SECTIONS = [
|
|
47
|
+
{
|
|
48
|
+
name: "tool:read",
|
|
49
|
+
file: "read.md",
|
|
50
|
+
defaultOrder: 130,
|
|
51
|
+
renderDefault: () => guidanceText(READ_GUIDANCE),
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
name: "tool:edit",
|
|
55
|
+
file: "edit.md",
|
|
56
|
+
defaultOrder: 131,
|
|
57
|
+
renderDefault: () => guidanceText(EDIT_GUIDANCE),
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
name: "tool:batch_edit",
|
|
61
|
+
file: "batch_edit.md",
|
|
62
|
+
defaultOrder: 132,
|
|
63
|
+
renderDefault: () => guidanceText(BATCH_EDIT_GUIDANCE),
|
|
64
|
+
},
|
|
65
|
+
{
|
|
66
|
+
name: "tool:undo_last_edit",
|
|
67
|
+
file: "undo_last_edit.md",
|
|
68
|
+
defaultOrder: 133,
|
|
69
|
+
renderDefault: () => guidanceText(UNDO_GUIDANCE),
|
|
70
|
+
},
|
|
71
|
+
];
|
|
72
|
+
const SECTION_BY_NAME = new Map(GUIDANCE_SECTIONS.map((section) => [section.name, section]));
|
|
73
|
+
/** Render the compiled default text for one section. */
|
|
74
|
+
export function renderSectionDefault(name) {
|
|
75
|
+
const section = SECTION_BY_NAME.get(name);
|
|
76
|
+
if (!section)
|
|
77
|
+
throw new Error(`unknown guidance section: ${name}`);
|
|
78
|
+
return section.renderDefault();
|
|
79
|
+
}
|
|
80
|
+
function stripCR(line) {
|
|
81
|
+
return line.endsWith("\r") ? line.slice(0, -1) : line;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Parse an override file. Only a leading `---` fence whose lines are empty or
|
|
85
|
+
* `order: <integer>` is accepted; every other shape (no fence, no closing
|
|
86
|
+
* fence, unknown key, non-integer value) yields the whole file as prose.
|
|
87
|
+
*/
|
|
88
|
+
export function parseSectionFile(content) {
|
|
89
|
+
const lines = content.split("\n");
|
|
90
|
+
if (lines.length < 3 || stripCR(lines[0]) !== "---") {
|
|
91
|
+
return { text: content };
|
|
92
|
+
}
|
|
93
|
+
const close = lines.findIndex((line, index) => index > 0 && stripCR(line) === "---");
|
|
94
|
+
if (close < 0)
|
|
95
|
+
return { text: content };
|
|
96
|
+
let order;
|
|
97
|
+
for (let index = 1; index < close; index++) {
|
|
98
|
+
const line = stripCR(lines[index]);
|
|
99
|
+
if (line.trim() === "")
|
|
100
|
+
continue;
|
|
101
|
+
const match = /^order:\s*(-?\d+)\s*$/.exec(line);
|
|
102
|
+
if (!match)
|
|
103
|
+
return { text: content };
|
|
104
|
+
order = Number.parseInt(match[1], 10);
|
|
105
|
+
}
|
|
106
|
+
// Front-matter body: strip leading blank lines after the closing fence so
|
|
107
|
+
// `---\n…\n---\n\nbody` and `---\n…\n---\nbody` parse identically (the
|
|
108
|
+
// materialized preset files carry a blank line after the fence).
|
|
109
|
+
const body = lines.slice(close + 1);
|
|
110
|
+
let bodyStart = 0;
|
|
111
|
+
while (bodyStart < body.length && body[bodyStart].trim() === "")
|
|
112
|
+
bodyStart++;
|
|
113
|
+
return { order, text: body.slice(bodyStart).join("\n") };
|
|
114
|
+
}
|
|
115
|
+
function overrideCandidates(file, options) {
|
|
116
|
+
const candidates = [];
|
|
117
|
+
if (options.presetId !== undefined) {
|
|
118
|
+
candidates.push(join(options.homeDir, options.presetId, file));
|
|
119
|
+
}
|
|
120
|
+
return candidates;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Resolve one section's guidance: the first override file that exists wins,
|
|
124
|
+
* falling back to the compiled default. A missing file (ENOENT) advances the
|
|
125
|
+
* chain; any other read error propagates.
|
|
126
|
+
*/
|
|
127
|
+
export async function resolveSection(name, options) {
|
|
128
|
+
const section = SECTION_BY_NAME.get(name);
|
|
129
|
+
if (!section)
|
|
130
|
+
throw new Error(`unknown guidance section: ${name}`);
|
|
131
|
+
for (const candidate of overrideCandidates(section.file, options)) {
|
|
132
|
+
const content = await readFile(candidate, "utf-8").catch((error) => {
|
|
133
|
+
if (errCode(error) === "ENOENT")
|
|
134
|
+
return undefined;
|
|
135
|
+
throw error;
|
|
136
|
+
});
|
|
137
|
+
if (content === undefined)
|
|
138
|
+
continue;
|
|
139
|
+
const parsed = parseSectionFile(content);
|
|
140
|
+
return { order: parsed.order ?? section.defaultOrder, text: parsed.text };
|
|
141
|
+
}
|
|
142
|
+
return { order: section.defaultOrder, text: section.renderDefault() };
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Resolve all four sections for a preset. `presetId === undefined` skips the
|
|
146
|
+
* `<preset>/` layer and resolves straight to the compiled defaults.
|
|
147
|
+
*/
|
|
148
|
+
export async function composeSections(presetId, homeDir) {
|
|
149
|
+
return Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
150
|
+
const { order, text } = await resolveSection(section.name, {
|
|
151
|
+
presetId,
|
|
152
|
+
homeDir,
|
|
153
|
+
});
|
|
154
|
+
return { name: section.name, order, text };
|
|
155
|
+
}));
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* The root README: the per-preset customization convention users see in the
|
|
159
|
+
* plugin home.
|
|
160
|
+
*/
|
|
161
|
+
export const GUIDANCE_HOME_README = `# dsh-better-edit guidance
|
|
162
|
+
|
|
163
|
+
Each agent preset has its own guidance directory here: \`<preset>/<section>.md\`.
|
|
164
|
+
On first boot the plugin seeds the shipped presets (\`standard\`, \`code\`,
|
|
165
|
+
\`minimal\`, \`cordis\`) with the compiled defaults; existing files are never
|
|
166
|
+
overwritten, so your edits survive.
|
|
167
|
+
|
|
168
|
+
Each file is one tool section:
|
|
169
|
+
|
|
170
|
+
- \`read.md\` -> \`tool:read\`
|
|
171
|
+
- \`edit.md\` -> \`tool:edit\`
|
|
172
|
+
- \`batch_edit.md\` -> \`tool:batch_edit\`
|
|
173
|
+
- \`undo_last_edit.md\` -> \`tool:undo_last_edit\`
|
|
174
|
+
|
|
175
|
+
## Customize
|
|
176
|
+
|
|
177
|
+
Edit the \`<section>.md\` file for the preset and section you want to change —
|
|
178
|
+
the file body IS the text the model reads for that section. Files are read once
|
|
179
|
+
per agent at session-start, so edits apply to new sessions.
|
|
180
|
+
|
|
181
|
+
An optional YAML front-matter fence places the section at a custom position in
|
|
182
|
+
the assembled system prompt:
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
order: 150
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
<section text>
|
|
189
|
+
|
|
190
|
+
A file without front-matter keeps the default order. A malformed fence (a
|
|
191
|
+
missing closing \`---\`, a non-integer \`order\`, an unknown key) makes the whole
|
|
192
|
+
file plain prose.
|
|
193
|
+
|
|
194
|
+
## Fallback
|
|
195
|
+
|
|
196
|
+
A preset with no directory here, or a missing section file, falls back to the
|
|
197
|
+
compiled defaults in the plugin bundle. To customize a preset that has no
|
|
198
|
+
seeded directory, copy a seeded one to its name.
|
|
199
|
+
`;
|
|
200
|
+
export const GUIDANCE_HOME_README_ZH = `# dsh-better-edit 指引
|
|
201
|
+
|
|
202
|
+
每个 agent preset 在这里都有自己的指引目录:\`<preset>/<section>.md\`。首次启动时
|
|
203
|
+
插件会为随附的 preset(\`standard\`、\`code\`、\`minimal\`、\`cordis\`)写入编译内置的
|
|
204
|
+
默认内容;已有文件绝不被覆盖,因此你的编辑会保留。
|
|
205
|
+
|
|
206
|
+
每个文件对应一个工具片段:
|
|
207
|
+
|
|
208
|
+
- \`read.md\` -> \`tool:read\`
|
|
209
|
+
- \`edit.md\` -> \`tool:edit\`
|
|
210
|
+
- \`batch_edit.md\` -> \`tool:batch_edit\`
|
|
211
|
+
- \`undo_last_edit.md\` -> \`tool:undo_last_edit\`
|
|
212
|
+
|
|
213
|
+
## 自定义
|
|
214
|
+
|
|
215
|
+
编辑你想修改的 preset 与片段的 \`<section>.md\` 文件即可——文件正文就是该片段呈
|
|
216
|
+
现给模型的文本。文件在 agent 的 session-start 时读取一次,因此修改只影响新会话。
|
|
217
|
+
|
|
218
|
+
可以用可选的 YAML front-matter 栅栏把片段放到组装后系统提示中的自定义位置:
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
order: 150
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
<片段文本>
|
|
225
|
+
|
|
226
|
+
没有 front-matter 的文件保持默认顺序。格式错误的栅栏(缺少收尾 \`---\`、非整数
|
|
227
|
+
\`order\`、未知键)会让整个文件退化为纯文本。
|
|
228
|
+
|
|
229
|
+
## 回退
|
|
230
|
+
|
|
231
|
+
这里没有对应目录的 preset、或缺失某个片段文件时,会回退到插件包内的编译内置默认
|
|
232
|
+
值。要自定义没有种子目录的 preset,把一个种子目录复制成它的名字即可。
|
|
233
|
+
`;
|
|
234
|
+
/**
|
|
235
|
+
* Materialize per-preset guidance directories in the plugin home.
|
|
236
|
+
*
|
|
237
|
+
* For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
|
|
238
|
+
* undo_last_edit}.md\` rendered from the compiled defaults (with order
|
|
239
|
+
* front-matter), plus a root \`README.md\` documenting the convention.
|
|
240
|
+
* Idempotent: existing files are never rewritten (a user-edited file survives
|
|
241
|
+
* repeated calls) and missing directories are created on demand. Each file is
|
|
242
|
+
* written exclusively, so two concurrent first runs race safely.
|
|
243
|
+
*/
|
|
244
|
+
export async function ensurePresetGuidance(homeDir) {
|
|
245
|
+
await mkdir(homeDir, { recursive: true });
|
|
246
|
+
await Promise.all(DEFAULT_PRESETS.map(async (preset) => {
|
|
247
|
+
const dir = join(homeDir, preset);
|
|
248
|
+
await mkdir(dir, { recursive: true });
|
|
249
|
+
const existing = new Set(await readdir(dir));
|
|
250
|
+
await Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
251
|
+
if (existing.has(section.file))
|
|
252
|
+
return;
|
|
253
|
+
const content = `---\norder: ${section.defaultOrder}\n---\n\n${section.renderDefault()}`;
|
|
254
|
+
await writeFile(join(dir, section.file), content, {
|
|
255
|
+
encoding: "utf-8",
|
|
256
|
+
flag: "wx",
|
|
257
|
+
}).catch((error) => {
|
|
258
|
+
// A concurrent writer landed first; never clobber it.
|
|
259
|
+
if (errCode(error) === "EEXIST")
|
|
260
|
+
return;
|
|
261
|
+
throw error;
|
|
262
|
+
});
|
|
263
|
+
}));
|
|
264
|
+
}));
|
|
265
|
+
const homeFiles = new Set(await readdir(homeDir));
|
|
266
|
+
const readmes = [
|
|
267
|
+
["README.md", GUIDANCE_HOME_README],
|
|
268
|
+
["README.zh.md", GUIDANCE_HOME_README_ZH],
|
|
269
|
+
];
|
|
270
|
+
await Promise.all(readmes.map(async ([file, content]) => {
|
|
271
|
+
if (homeFiles.has(file))
|
|
272
|
+
return;
|
|
273
|
+
await writeFile(join(homeDir, file), content, {
|
|
274
|
+
encoding: "utf-8",
|
|
275
|
+
flag: "wx",
|
|
276
|
+
}).catch((error) => {
|
|
277
|
+
if (errCode(error) === "EEXIST")
|
|
278
|
+
return;
|
|
279
|
+
throw error;
|
|
280
|
+
});
|
|
281
|
+
}));
|
|
282
|
+
}
|
package/lib/index.js
CHANGED
|
@@ -9,6 +9,10 @@
|
|
|
9
9
|
* automatically when the agent is disposed. The built-in `write` stays in
|
|
10
10
|
* place; a scoped `tools/post-execute` listener appends the fresh hashline
|
|
11
11
|
* preview to write results.
|
|
12
|
+
*
|
|
13
|
+
* The four `tool:*` guidance sections resolve per agent preset from override
|
|
14
|
+
* files in the shared home (see `src/guidance.ts`); deployments without the
|
|
15
|
+
* `agentPresets` service keep the compiled defaults unchanged.
|
|
12
16
|
* @module dsh-better-edit
|
|
13
17
|
*/
|
|
14
18
|
import { ctxFsIO } from "./fs-bridge.js";
|
|
@@ -19,7 +23,8 @@ import { registerBatchEditTool } from "./tool-batch-edit.js";
|
|
|
19
23
|
import { registerUndoTool } from "./tool-undo.js";
|
|
20
24
|
import { registerWriteHook } from "./write-hook.js";
|
|
21
25
|
import { initHasher } from "./hashline/hasher.js";
|
|
22
|
-
import {
|
|
26
|
+
import { composeSections, ensurePresetGuidance, GUIDANCE_SECTIONS, } from "./guidance.js";
|
|
27
|
+
import { configDir } from "./paths.js";
|
|
23
28
|
/** Cordis plugin name used by loader diagnostics. */
|
|
24
29
|
export const name = "dsh-better-edit";
|
|
25
30
|
/**
|
|
@@ -30,8 +35,36 @@ export const name = "dsh-better-edit";
|
|
|
30
35
|
* session-start.
|
|
31
36
|
*/
|
|
32
37
|
export const inject = ["tools", "systemPrompt", "fs"];
|
|
38
|
+
/** The four sections as compiled, byte-identical to the pre-guidance install. */
|
|
39
|
+
function compiledDefaultSections() {
|
|
40
|
+
return GUIDANCE_SECTIONS.map((section) => ({
|
|
41
|
+
name: section.name,
|
|
42
|
+
order: section.defaultOrder,
|
|
43
|
+
text: section.renderDefault(),
|
|
44
|
+
}));
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Resolve the four guidance sections for one agent. Without the `agentPresets`
|
|
48
|
+
* service the fast path returns the compiled defaults untouched. With it, the
|
|
49
|
+
* agent's preset id drives `composeSections` against the shared home; any
|
|
50
|
+
* resolution failure degrades to compiled defaults so a bad override file can
|
|
51
|
+
* never fail the install.
|
|
52
|
+
*/
|
|
53
|
+
async function resolveAgentSections(rootCtx, agent) {
|
|
54
|
+
const agentPresets = rootCtx.get("agentPresets");
|
|
55
|
+
if (!agentPresets)
|
|
56
|
+
return compiledDefaultSections();
|
|
57
|
+
try {
|
|
58
|
+
const presetId = agentPresets.composedPreset(agent.ctx);
|
|
59
|
+
return await composeSections(presetId, configDir());
|
|
60
|
+
}
|
|
61
|
+
catch (error) {
|
|
62
|
+
rootCtx.logger.warn(`dsh-better-edit: guidance resolution failed for agent ${agent.id}, using compiled defaults: ${error instanceof Error ? error.message : String(error)}`);
|
|
63
|
+
return compiledDefaultSections();
|
|
64
|
+
}
|
|
65
|
+
}
|
|
33
66
|
function installAgentTools(rootCtx, agent) {
|
|
34
|
-
|
|
67
|
+
agent.ctx.effect(async () => {
|
|
35
68
|
// `fs` is host-plane: use the plugin's own context (covered by
|
|
36
69
|
// inject) rather than the agent's scoped one, whose fiber chain does
|
|
37
70
|
// not declare it. Session cwd still reaches the bridge per call via
|
|
@@ -44,36 +77,13 @@ function installAgentTools(rootCtx, agent) {
|
|
|
44
77
|
disposers.push(registerBatchEditTool(rootCtx, agent.ctx, io, sandbox));
|
|
45
78
|
disposers.push(registerUndoTool(rootCtx, agent.ctx, io, sandbox));
|
|
46
79
|
disposers.push(registerWriteHook(rootCtx, agent.ctx, io));
|
|
47
|
-
// Shadow the preset's built-in tool guidance with the hashline
|
|
48
|
-
// Same section names on the agent's own layer win over the
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
"",
|
|
55
|
-
EDIT_GUIDELINES.map((line) => `- ${line}`).join("\n"),
|
|
56
|
-
].join("\n"),
|
|
57
|
-
}));
|
|
58
|
-
disposers.push(agent.ctx.systemPrompt.section({
|
|
59
|
-
name: "tool:read",
|
|
60
|
-
order: 100,
|
|
61
|
-
text: [
|
|
62
|
-
"Use the read tool — not shell commands like cat — to inspect text files.",
|
|
63
|
-
"",
|
|
64
|
-
READ_GUIDELINES.map((line) => `- ${line}`).join("\n"),
|
|
65
|
-
].join("\n"),
|
|
66
|
-
}));
|
|
67
|
-
disposers.push(agent.ctx.systemPrompt.section({
|
|
68
|
-
name: "tool:batch_edit",
|
|
69
|
-
order: 103,
|
|
70
|
-
text: BATCH_EDIT_GUIDELINES.map((line) => `- ${line}`).join("\n"),
|
|
71
|
-
}));
|
|
72
|
-
disposers.push(agent.ctx.systemPrompt.section({
|
|
73
|
-
name: "tool:undo_last_edit",
|
|
74
|
-
order: 104,
|
|
75
|
-
text: UNDO_GUIDELINES.map((line) => `- ${line}`).join("\n"),
|
|
76
|
-
}));
|
|
80
|
+
// Shadow the preset's built-in tool guidance with the hashline
|
|
81
|
+
// contract. Same section names on the agent's own layer win over the
|
|
82
|
+
// preset's; text and order come from the per-preset resolution.
|
|
83
|
+
const sections = await resolveAgentSections(rootCtx, agent);
|
|
84
|
+
for (const section of sections) {
|
|
85
|
+
disposers.push(agent.ctx.systemPrompt.section(section));
|
|
86
|
+
}
|
|
77
87
|
return () => {
|
|
78
88
|
for (const dispose of disposers)
|
|
79
89
|
dispose();
|
|
@@ -88,6 +98,12 @@ export function apply(rootCtx) {
|
|
|
88
98
|
initHasher().catch((error) => {
|
|
89
99
|
rootCtx.logger.warn(`dsh-better-edit: hasher warm-up failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
90
100
|
});
|
|
101
|
+
// Seed each shipped preset's guidance directory once, so users have
|
|
102
|
+
// editable per-preset overrides (idempotent: never rewrites existing
|
|
103
|
+
// files). A failure must never fail the boot.
|
|
104
|
+
ensurePresetGuidance(configDir()).catch((error) => {
|
|
105
|
+
rootCtx.logger.warn(`dsh-better-edit: guidance materialization failed: ${error instanceof Error ? error.message : String(error)}`);
|
|
106
|
+
});
|
|
91
107
|
const registered = new WeakSet();
|
|
92
108
|
rootCtx.on("agent/session-start", ({ agent }) => {
|
|
93
109
|
if (registered.has(agent))
|
package/lib/prompts.js
CHANGED
|
@@ -1,54 +1,58 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Model-facing prompt text for the hashline tools, embedded so the bundle
|
|
3
|
-
* ships no external prompt files. Each tool's description is short;
|
|
4
|
-
* `tool:*` system-prompt sections carry the
|
|
5
|
-
* reads when the tools are presented.
|
|
3
|
+
* ships no external prompt files. Each tool's schema `description` is short;
|
|
4
|
+
* the `tool:*` system-prompt sections carry the brief guidance the model
|
|
5
|
+
* reads when the tools are presented. Guidance is uniform: a one-line opener
|
|
6
|
+
* followed by tight bullets.
|
|
6
7
|
* @module dsh-better-edit/prompts
|
|
7
8
|
*/
|
|
8
|
-
export const EDIT_DESCRIPTION =
|
|
9
|
-
|
|
9
|
+
export const EDIT_DESCRIPTION = "Edit a range of lines in a text file, targeted by the 3-char HASH anchors from read output. " +
|
|
10
|
+
"remove_from and remove_to must each be a BARE 3-character hash: copy only the hash from the " +
|
|
10
11
|
'leftmost column of a read row (row `ve7│function hello() {` means `"remove_from": "ve7"`). ' +
|
|
11
|
-
|
|
12
|
-
export const
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
export const
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
export const BATCH_EDIT_DESCRIPTION =
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
export const
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
export const UNDO_DESCRIPTION =
|
|
50
|
-
|
|
51
|
-
export const
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
12
|
+
"Never pass the line content, a code line, or a paragraph into these fields.";
|
|
13
|
+
export const EDIT_GUIDANCE = {
|
|
14
|
+
intro: "Edit a range of lines via a bare 3-char HASH anchor from read output — never by line content.",
|
|
15
|
+
lines: [
|
|
16
|
+
"`edit`: anchor the exact first and last lines that change by their stripped hash (`ve7`, not `ve7│function…`). A single line uses the same hash in both fields; never anchor a whole function or import block when part of it changes.",
|
|
17
|
+
"`edit`: replacement_text is byte-exact for the whole range — every line inside it you do not reproduce byte-exact is deleted, and leading whitespace is preserved exactly.",
|
|
18
|
+
"`edit`: `\\n` is a line break, so a range ending on a blank line must end replacement_text with `\\n` and a non-blank last line must not; a blank-line run is one `\\n` per blank line.",
|
|
19
|
+
"`edit`: the post-edit diff rows carry fresh anchors for follow-ups. A stale or never-served range is hard-rejected (`[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]`); copy the echoed rows and retry — only tool-served rows count.",
|
|
20
|
+
"`edit`: for multiple edits to one file, use batch_edit — it validates every item before writing and applies them all-or-nothing.",
|
|
21
|
+
],
|
|
22
|
+
};
|
|
23
|
+
export const READ_DESCRIPTION = "Read a text file; each line returned as HASH│content with a 3-char alphanumeric hash. " +
|
|
24
|
+
"No line numbers — use the HASH as the anchor in edit calls. Binary/directory → rejected; " +
|
|
25
|
+
"empty → HASH│ (edit to insert); pageable with offset/limit; BOM stripped; non-UTF-8 shown as U+FFFD.";
|
|
26
|
+
export const READ_GUIDANCE = {
|
|
27
|
+
intro: "Use read, not shell commands, to inspect text files and obtain the HASH anchors the editing tools require.",
|
|
28
|
+
lines: [
|
|
29
|
+
"`read`: call it only for content the tools have not served — a page you never saw, or lines past the post-edit diff.",
|
|
30
|
+
"`read`: each row is `HASH│content`; the HASH is the anchor (no line numbers). Rejection echoes return fresh rows that count as serves.",
|
|
31
|
+
"`read`: binary/directory rejects; page large files with offset/limit.",
|
|
32
|
+
],
|
|
33
|
+
};
|
|
34
|
+
export const BATCH_EDIT_DESCRIPTION = "Apply several edits in one atomic call. Each item is exactly like the edit tool: " +
|
|
35
|
+
"{ path?, remove_from, remove_to, replacement_text }, where remove_from and remove_to are " +
|
|
36
|
+
"bare 3-char hashes from read or diff output. Items targeting the same file are applied in order. " +
|
|
37
|
+
"Every item is verified against what the tool served you before ANYTHING is written: if any item " +
|
|
38
|
+
"fails — stale or ambiguous anchor, changed range interior, never-served line — the whole batch " +
|
|
39
|
+
"is rejected and no file changes. The failing item\u2019s current range is served back as fresh " +
|
|
40
|
+
"HASH│content rows so you can retry without a read. Use batch_edit whenever you have multiple " +
|
|
41
|
+
"edits; do not issue several edit calls in one message.";
|
|
42
|
+
export const BATCH_EDIT_GUIDANCE = {
|
|
43
|
+
intro: "Apply several edits in one atomic call.",
|
|
44
|
+
lines: [
|
|
45
|
+
"`batch_edit`: each item is edit\u2019s shape — { path?, remove_from, remove_to, replacement_text } — with bare hash anchors; items apply in order, and same-file ranges must not overlap.",
|
|
46
|
+
"`batch_edit`: all-or-nothing — any failing item writes nothing anywhere and echoes its current range as fresh rows that count as serves.",
|
|
47
|
+
"`batch_edit`: a no-op item is reported without failing; the result is one combined diff per file with fresh anchors.",
|
|
48
|
+
],
|
|
49
|
+
};
|
|
50
|
+
export const UNDO_DESCRIPTION = "Undo the last edit on a file, reverting it to its previous state. Use when an edit produced " +
|
|
51
|
+
"incorrect results (e.g., wrong content, duplicated lines, broken syntax).";
|
|
52
|
+
export const UNDO_GUIDANCE = {
|
|
53
|
+
intro: "Revert the last edit on a file.",
|
|
54
|
+
lines: [
|
|
55
|
+
"`undo_last_edit`: reverts only the most recent edit — any write clears history, so call it immediately after a bad edit.",
|
|
56
|
+
"`undo_last_edit`: the restored diff\u2019s `+HASH│` and ` HASH│` rows are fresh anchors for follow-up edits.",
|
|
57
|
+
],
|
|
58
|
+
};
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-preset guidance overrides for the hashline tool sections.
|
|
3
|
+
*
|
|
4
|
+
* Each of the four `tool:*` prompt sections the plugin registers has a
|
|
5
|
+
* compiled default rendered from `prompts.ts` (byte-identical to the inline
|
|
6
|
+
* rendering `src/index.ts` uses today). A user can override any section's text
|
|
7
|
+
* and `order` with a plain markdown file keyed by agent preset: the override
|
|
8
|
+
* files live in the plugin's shared home (`$DSH_HOME/plugins/dsh-better-edit`,
|
|
9
|
+
* never the workspace store) and are resolved per section as
|
|
10
|
+
* `<preset>/<section>.md` → compiled default.
|
|
11
|
+
*
|
|
12
|
+
* An override file is pure prose unless it opens with a valid YAML front-matter
|
|
13
|
+
* fence carrying only an `order` key (`---` / `order: N` / `---`); anything
|
|
14
|
+
* else — a missing closing fence, a non-integer `order`, an unknown key —
|
|
15
|
+
* degrades the WHOLE file to prose so the mistake stays visible in the
|
|
16
|
+
* rendered section.
|
|
17
|
+
*
|
|
18
|
+
* Resolution is pure: no cordis services, no harness wiring. The installer
|
|
19
|
+
* ticket reads the resolved sections once per agent at session-start;
|
|
20
|
+
* nothing here watches or caches files.
|
|
21
|
+
* @module dsh-better-edit/guidance
|
|
22
|
+
*/
|
|
23
|
+
/** The presets shipped by the harness, each seeded with editable guidance. */
|
|
24
|
+
export declare const DEFAULT_PRESETS: readonly string[];
|
|
25
|
+
/** One overridable tool section. */
|
|
26
|
+
export interface GuidanceSection {
|
|
27
|
+
/** Registry section name, e.g. `tool:edit`. */
|
|
28
|
+
name: string;
|
|
29
|
+
/** Override file name inside a preset directory, e.g. `edit.md`. */
|
|
30
|
+
file: string;
|
|
31
|
+
/** Order used when the override file carries no front-matter `order`. */
|
|
32
|
+
defaultOrder: number;
|
|
33
|
+
/** The compiled default text, byte-identical to today's inline rendering. */
|
|
34
|
+
renderDefault(): string;
|
|
35
|
+
}
|
|
36
|
+
/** The four sections, in default-order sequence. */
|
|
37
|
+
export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
|
|
38
|
+
/** Render the compiled default text for one section. */
|
|
39
|
+
export declare function renderSectionDefault(name: string): string;
|
|
40
|
+
/** The parsed content of one override file. */
|
|
41
|
+
export interface ParsedSection {
|
|
42
|
+
/** Front-matter `order`, when present and valid. */
|
|
43
|
+
order?: number;
|
|
44
|
+
/** The section text: the file body, or the whole file when front-matter is absent or malformed. */
|
|
45
|
+
text: string;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Parse an override file. Only a leading `---` fence whose lines are empty or
|
|
49
|
+
* `order: <integer>` is accepted; every other shape (no fence, no closing
|
|
50
|
+
* fence, unknown key, non-integer value) yields the whole file as prose.
|
|
51
|
+
*/
|
|
52
|
+
export declare function parseSectionFile(content: string): ParsedSection;
|
|
53
|
+
/** Options for resolving one section's guidance. */
|
|
54
|
+
export interface ResolveGuidanceOptions {
|
|
55
|
+
/** Agent preset id, or undefined to skip the preset layer. */
|
|
56
|
+
presetId?: string;
|
|
57
|
+
/** Plugin shared home directory (`$DSH_HOME/plugins/dsh-better-edit`). */
|
|
58
|
+
homeDir: string;
|
|
59
|
+
}
|
|
60
|
+
/** The resolved text and order for one section. */
|
|
61
|
+
export interface GuidanceResolution {
|
|
62
|
+
order: number;
|
|
63
|
+
text: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Resolve one section's guidance: the first override file that exists wins,
|
|
67
|
+
* falling back to the compiled default. A missing file (ENOENT) advances the
|
|
68
|
+
* chain; any other read error propagates.
|
|
69
|
+
*/
|
|
70
|
+
export declare function resolveSection(name: string, options: ResolveGuidanceOptions): Promise<GuidanceResolution>;
|
|
71
|
+
/** The resolved configuration of one section, ready for the systemPrompt registry. */
|
|
72
|
+
export interface SectionOverride {
|
|
73
|
+
name: string;
|
|
74
|
+
order: number;
|
|
75
|
+
text: string;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Resolve all four sections for a preset. `presetId === undefined` skips the
|
|
79
|
+
* `<preset>/` layer and resolves straight to the compiled defaults.
|
|
80
|
+
*/
|
|
81
|
+
export declare function composeSections(presetId: string | undefined, homeDir: string): Promise<SectionOverride[]>;
|
|
82
|
+
/**
|
|
83
|
+
* The root README: the per-preset customization convention users see in the
|
|
84
|
+
* plugin home.
|
|
85
|
+
*/
|
|
86
|
+
export declare const GUIDANCE_HOME_README = "# dsh-better-edit guidance\n\nEach agent preset has its own guidance directory here: `<preset>/<section>.md`.\nOn first boot the plugin seeds the shipped presets (`standard`, `code`,\n`minimal`, `cordis`) with the compiled defaults; existing files are never\noverwritten, so your edits survive.\n\nEach file is one tool section:\n\n- `read.md` -> `tool:read`\n- `edit.md` -> `tool:edit`\n- `batch_edit.md` -> `tool:batch_edit`\n- `undo_last_edit.md` -> `tool:undo_last_edit`\n\n## Customize\n\nEdit the `<section>.md` file for the preset and section you want to change \u2014\nthe file body IS the text the model reads for that section. Files are read once\nper agent at session-start, so edits apply to new sessions.\n\nAn optional YAML front-matter fence places the section at a custom position in\nthe assembled system prompt:\n\n ---\n order: 150\n ---\n\n <section text>\n\nA file without front-matter keeps the default order. A malformed fence (a\nmissing closing `---`, a non-integer `order`, an unknown key) makes the whole\nfile plain prose.\n\n## Fallback\n\nA preset with no directory here, or a missing section file, falls back to the\ncompiled defaults in the plugin bundle. To customize a preset that has no\nseeded directory, copy a seeded one to its name.\n";
|
|
87
|
+
export declare const GUIDANCE_HOME_README_ZH = "# dsh-better-edit \u6307\u5F15\n\n\u6BCF\u4E2A agent preset \u5728\u8FD9\u91CC\u90FD\u6709\u81EA\u5DF1\u7684\u6307\u5F15\u76EE\u5F55\uFF1A`<preset>/<section>.md`\u3002\u9996\u6B21\u542F\u52A8\u65F6\n\u63D2\u4EF6\u4F1A\u4E3A\u968F\u9644\u7684 preset\uFF08`standard`\u3001`code`\u3001`minimal`\u3001`cordis`\uFF09\u5199\u5165\u7F16\u8BD1\u5185\u7F6E\u7684\n\u9ED8\u8BA4\u5185\u5BB9\uFF1B\u5DF2\u6709\u6587\u4EF6\u7EDD\u4E0D\u88AB\u8986\u76D6\uFF0C\u56E0\u6B64\u4F60\u7684\u7F16\u8F91\u4F1A\u4FDD\u7559\u3002\n\n\u6BCF\u4E2A\u6587\u4EF6\u5BF9\u5E94\u4E00\u4E2A\u5DE5\u5177\u7247\u6BB5\uFF1A\n\n- `read.md` -> `tool:read`\n- `edit.md` -> `tool:edit`\n- `batch_edit.md` -> `tool:batch_edit`\n- `undo_last_edit.md` -> `tool:undo_last_edit`\n\n## \u81EA\u5B9A\u4E49\n\n\u7F16\u8F91\u4F60\u60F3\u4FEE\u6539\u7684 preset \u4E0E\u7247\u6BB5\u7684 `<section>.md` \u6587\u4EF6\u5373\u53EF\u2014\u2014\u6587\u4EF6\u6B63\u6587\u5C31\u662F\u8BE5\u7247\u6BB5\u5448\n\u73B0\u7ED9\u6A21\u578B\u7684\u6587\u672C\u3002\u6587\u4EF6\u5728 agent \u7684 session-start \u65F6\u8BFB\u53D6\u4E00\u6B21\uFF0C\u56E0\u6B64\u4FEE\u6539\u53EA\u5F71\u54CD\u65B0\u4F1A\u8BDD\u3002\n\n\u53EF\u4EE5\u7528\u53EF\u9009\u7684 YAML front-matter \u6805\u680F\u628A\u7247\u6BB5\u653E\u5230\u7EC4\u88C5\u540E\u7CFB\u7EDF\u63D0\u793A\u4E2D\u7684\u81EA\u5B9A\u4E49\u4F4D\u7F6E\uFF1A\n\n ---\n order: 150\n ---\n\n <\u7247\u6BB5\u6587\u672C>\n\n\u6CA1\u6709 front-matter \u7684\u6587\u4EF6\u4FDD\u6301\u9ED8\u8BA4\u987A\u5E8F\u3002\u683C\u5F0F\u9519\u8BEF\u7684\u6805\u680F\uFF08\u7F3A\u5C11\u6536\u5C3E `---`\u3001\u975E\u6574\u6570\n`order`\u3001\u672A\u77E5\u952E\uFF09\u4F1A\u8BA9\u6574\u4E2A\u6587\u4EF6\u9000\u5316\u4E3A\u7EAF\u6587\u672C\u3002\n\n## \u56DE\u9000\n\n\u8FD9\u91CC\u6CA1\u6709\u5BF9\u5E94\u76EE\u5F55\u7684 preset\u3001\u6216\u7F3A\u5931\u67D0\u4E2A\u7247\u6BB5\u6587\u4EF6\u65F6\uFF0C\u4F1A\u56DE\u9000\u5230\u63D2\u4EF6\u5305\u5185\u7684\u7F16\u8BD1\u5185\u7F6E\u9ED8\u8BA4\n\u503C\u3002\u8981\u81EA\u5B9A\u4E49\u6CA1\u6709\u79CD\u5B50\u76EE\u5F55\u7684 preset\uFF0C\u628A\u4E00\u4E2A\u79CD\u5B50\u76EE\u5F55\u590D\u5236\u6210\u5B83\u7684\u540D\u5B57\u5373\u53EF\u3002\n";
|
|
88
|
+
/**
|
|
89
|
+
* Materialize per-preset guidance directories in the plugin home.
|
|
90
|
+
*
|
|
91
|
+
* For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
|
|
92
|
+
* undo_last_edit}.md\` rendered from the compiled defaults (with order
|
|
93
|
+
* front-matter), plus a root \`README.md\` documenting the convention.
|
|
94
|
+
* Idempotent: existing files are never rewritten (a user-edited file survives
|
|
95
|
+
* repeated calls) and missing directories are created on demand. Each file is
|
|
96
|
+
* written exclusively, so two concurrent first runs race safely.
|
|
97
|
+
*/
|
|
98
|
+
export declare function ensurePresetGuidance(homeDir: string): Promise<void>;
|
package/lib/types/index.d.ts
CHANGED
|
@@ -9,6 +9,10 @@
|
|
|
9
9
|
* automatically when the agent is disposed. The built-in `write` stays in
|
|
10
10
|
* place; a scoped `tools/post-execute` listener appends the fresh hashline
|
|
11
11
|
* preview to write results.
|
|
12
|
+
*
|
|
13
|
+
* The four `tool:*` guidance sections resolve per agent preset from override
|
|
14
|
+
* files in the shared home (see `src/guidance.ts`); deployments without the
|
|
15
|
+
* `agentPresets` service keep the compiled defaults unchanged.
|
|
12
16
|
* @module dsh-better-edit
|
|
13
17
|
*/
|
|
14
18
|
import type { Context } from "@deepseek-ai/cordis";
|
package/lib/types/prompts.d.ts
CHANGED
|
@@ -1,17 +1,27 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Model-facing prompt text for the hashline tools, embedded so the bundle
|
|
3
|
-
* ships no external prompt files. Each tool's description is short;
|
|
4
|
-
* `tool:*` system-prompt sections carry the
|
|
5
|
-
* reads when the tools are presented.
|
|
3
|
+
* ships no external prompt files. Each tool's schema `description` is short;
|
|
4
|
+
* the `tool:*` system-prompt sections carry the brief guidance the model
|
|
5
|
+
* reads when the tools are presented. Guidance is uniform: a one-line opener
|
|
6
|
+
* followed by tight bullets.
|
|
6
7
|
* @module dsh-better-edit/prompts
|
|
7
8
|
*/
|
|
9
|
+
/**
|
|
10
|
+
* One tool's guidance: a brief opener plus concise bullets. The `intro` is
|
|
11
|
+
* shown above the bullets; it does not duplicate the tool-schema `description`
|
|
12
|
+
* (that already reaches the model through the tool catalog).
|
|
13
|
+
*/
|
|
14
|
+
export interface ToolGuidance {
|
|
15
|
+
/** One-line lead shown above the bullets. */
|
|
16
|
+
intro: string;
|
|
17
|
+
/** Concise bullets; each is self-contained within its section. */
|
|
18
|
+
lines: readonly string[];
|
|
19
|
+
}
|
|
8
20
|
export declare const EDIT_DESCRIPTION: string;
|
|
9
|
-
export declare const
|
|
10
|
-
export declare const EDIT_GUIDELINES: string[];
|
|
21
|
+
export declare const EDIT_GUIDANCE: ToolGuidance;
|
|
11
22
|
export declare const READ_DESCRIPTION: string;
|
|
12
|
-
export declare const
|
|
13
|
-
export declare const READ_GUIDELINES: string[];
|
|
23
|
+
export declare const READ_GUIDANCE: ToolGuidance;
|
|
14
24
|
export declare const BATCH_EDIT_DESCRIPTION: string;
|
|
15
|
-
export declare const
|
|
25
|
+
export declare const BATCH_EDIT_GUIDANCE: ToolGuidance;
|
|
16
26
|
export declare const UNDO_DESCRIPTION: string;
|
|
17
|
-
export declare const
|
|
27
|
+
export declare const UNDO_GUIDANCE: ToolGuidance;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-better-edit",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Hash-anchored read/edit/batch_edit/undo_last_edit tools for DeepSeek Harness (dsh). Every line gets a unique 3-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -35,6 +35,7 @@
|
|
|
35
35
|
"dsh-plugin",
|
|
36
36
|
"deepseek-harness",
|
|
37
37
|
"coding-agent",
|
|
38
|
+
"oh-my-pi",
|
|
38
39
|
"hashline",
|
|
39
40
|
"hash-anchored",
|
|
40
41
|
"hash",
|