dsh-better-edit 0.1.6 → 0.1.7
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 +245 -212
- package/README.zh.md +174 -111
- package/assets/banner.svg +58 -0
- package/assets/logo.svg +21 -0
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,109 +1,55 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
re-read.
|
|
54
|
-
- **Reject-and-serve.** A stale or never-served range is hard-rejected with
|
|
55
|
-
the current `HASH│content` rows echoed back, so the retry needs no `read`.
|
|
56
|
-
|
|
57
|
-
## Why not `str_replace`?
|
|
58
|
-
|
|
59
|
-
Traditional edit tools ask the model to echo the old code token-for-token
|
|
60
|
-
before stating the replacement (`old_string` + `new_string`). That costs
|
|
61
|
-
`O(replaced text)` tokens per edit **and** is where models fail: the original
|
|
62
|
-
[harness-problem](https://stencil.so/blog/the-harness-problem) post reported
|
|
63
|
-
patch-format failure rates of 46–51% for several models with replace-style
|
|
64
|
-
edits, and a **61% output-token reduction** after switching to anchored
|
|
65
|
-
edits. hashline sends two 3-char anchors instead:
|
|
66
|
-
|
|
67
|
-
| | `str_replace` | hashline `edit` |
|
|
68
|
-
| --- | --- | --- |
|
|
69
|
-
| request | `{ path, old_string, new_string }` | `{ path, remove_from, remove_to, replacement_text }` |
|
|
70
|
-
| replaced text | reproduced verbatim | never sent |
|
|
71
|
-
| range verification | none (first match wins) | every line checked against served state |
|
|
72
|
-
| stale file | old_string may still match — and hit the wrong occurrence | rejected with fresh anchors (`E_RANGE_STALE`) |
|
|
73
|
-
| ambiguous text | first occurrence, silently | boundary anchors verified — call `read` for fresh anchors |
|
|
74
|
-
|
|
75
|
-
## Benchmark — reproducible
|
|
76
|
-
|
|
77
|
-
`benchmark/run.mjs` measures the model-side token cost of the two patterns on
|
|
78
|
-
the same 103-line file with the same 12 replacements (8 single-line, 4
|
|
79
|
-
multi-line of 3/6/10/15 lines), tokenized with the pinned `js-tiktoken`
|
|
80
|
-
`cl100k_base`:
|
|
81
|
-
|
|
82
|
-
| scenario | lines | hashline | str_replace | saved | % |
|
|
83
|
-
| --- | --- | --- | --- | --- | --- |
|
|
84
|
-
| single-line ×8 | 1 | 311 | 314 | 3 | 1% |
|
|
85
|
-
| multi-line ×4 | 3–15 | 390 | 655 | 265 | **40%** |
|
|
86
|
-
| **TOTAL ×12** | | **701** | **969** | **268** | **28%** |
|
|
87
|
-
|
|
88
|
-
Read traffic is identical for both tools and cancels. These are the model's
|
|
89
|
-
**output** tokens, billed at ~5-6× the input rate — at the 5× rate, hashline
|
|
90
|
-
costs **~1.4× less** on effective cost. Savings scale with the replaced text:
|
|
91
|
-
near parity on short single lines (the anchors' overhead roughly cancels a
|
|
92
|
-
one-line `old_string`), 25–46% on multi-line ranges.
|
|
93
|
-
|
|
94
|
-
Reproduce it yourself — deterministic, self-checking, no build step:
|
|
95
|
-
|
|
96
|
-
```sh
|
|
97
|
-
npm install # installs js-tiktoken (pinned)
|
|
98
|
-
npm run benchmark # node benchmark/run.mjs
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
Full methodology, results, and honest limitations (what the baseline does and
|
|
102
|
-
doesn't model) are in [`benchmark/README.md`](benchmark/README.md).
|
|
103
|
-
|
|
104
|
-
## Usage
|
|
105
|
-
|
|
106
|
-
1. Read a file:
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/logo.svg" alt="dsh-better-edit" width="200">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<h1 align="center">dsh-better-edit</h1>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>Hash-anchored edit tools for DeepSeek Harness.<br>
|
|
9
|
+
Edit by content address — not line numbers. Fewer tokens. Zero misapplied edits.</strong>
|
|
10
|
+
</p>
|
|
11
|
+
|
|
12
|
+
<p align="center">
|
|
13
|
+
<strong>English</strong> ·
|
|
14
|
+
<a href="README.zh.md">简体中文</a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="#quick-start">Quick Start</a> •
|
|
19
|
+
<a href="#why-hashline">Why Hashline</a> •
|
|
20
|
+
<a href="#benchmark">Benchmark</a> •
|
|
21
|
+
<a href="#installation">Installation</a> •
|
|
22
|
+
<a href="#tools">Tools</a> •
|
|
23
|
+
<a href="#acknowledgments">Acknowledgments</a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
<p align="center">
|
|
27
|
+
<img src="https://img.shields.io/badge/version-0.1.6-blue.svg" alt="Version">
|
|
28
|
+
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
|
|
29
|
+
<img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-blueviolet.svg" alt="DeepSeek Harness Plugin">
|
|
30
|
+
<img src="https://img.shields.io/npm/v/dsh-better-edit" alt="npm version">
|
|
31
|
+
<img src="https://img.shields.io/npm/dm/dsh-better-edit" alt="npm downloads">
|
|
32
|
+
<img src="https://img.shields.io/github/stars/Rianico/dsh-better-edit?style=social" alt="GitHub Stars">
|
|
33
|
+
</p>
|
|
34
|
+
|
|
35
|
+
<p align="center">
|
|
36
|
+
<img src="assets/banner.svg" alt="file.ts → read → hashed lines → edit by hash → diff" width="900">
|
|
37
|
+
</p>
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
> *"The harness — not the model — is the bottleneck."*
|
|
42
|
+
> — Can Bölük, [*The Harness Problem*](https://stencil.so/blog/the-harness-problem)
|
|
43
|
+
|
|
44
|
+
Most edit tools ask the model to echo the old code **token-for-token** before it can change anything
|
|
45
|
+
— and that's exactly where agents fail: 46–51% patch-format failure rates for several models with
|
|
46
|
+
replace-style edits. **dsh-better-edit** goes deeper. Every line of a file gets a unique 3-character
|
|
47
|
+
content hash, and edits target hashes. The old text is never echoed, anchors survive edits, and every
|
|
48
|
+
resolved range is verified against exactly what the model saw — wrong-line edits cannot silently land.
|
|
49
|
+
|
|
50
|
+
## Quick Start
|
|
51
|
+
|
|
52
|
+
`read` returns every line prefixed by its hash — the hash *is* the line's address:
|
|
107
53
|
|
|
108
54
|
```text
|
|
109
55
|
ve7│function hello() {
|
|
@@ -111,7 +57,7 @@ szJ│ console.log("world");
|
|
|
111
57
|
kQm│}
|
|
112
58
|
```
|
|
113
59
|
|
|
114
|
-
|
|
60
|
+
`edit` targets a range of hashes, so edits always land on the lines you meant:
|
|
115
61
|
|
|
116
62
|
```json
|
|
117
63
|
{
|
|
@@ -122,109 +68,111 @@ kQm│}
|
|
|
122
68
|
}
|
|
123
69
|
```
|
|
124
70
|
|
|
125
|
-
|
|
126
|
-
diff and the auto-read after `write` hand you fresh anchors. A `read` is
|
|
127
|
-
on-demand recovery, not a per-edit ritual.
|
|
71
|
+
and produces a diff with fresh anchors, so the next edit verifies cleanly with no re-read:
|
|
128
72
|
|
|
129
|
-
|
|
73
|
+
```text
|
|
74
|
+
− szJ │ console.log("world");
|
|
75
|
+
+ a3m │ console.log('hi');
|
|
76
|
+
kQm │ }
|
|
77
|
+
```
|
|
130
78
|
|
|
131
|
-
|
|
132
|
-
3 chars from `A-Za-z0-9`). Parameters: `offset` (1-based start line), `limit`
|
|
133
|
-
(maximum lines). Paged output ends with `[Showing lines N-M of T. Use
|
|
134
|
-
offset=… to continue.]`. Lines larger than 200KB are shown as a marker with a
|
|
135
|
-
`sed` inspection hint — hash anchors need full lines.
|
|
79
|
+
## Why Hashline
|
|
136
80
|
|
|
137
|
-
|
|
81
|
+
**Token-saving.** An edit call carries `remove_from` / `remove_to` (two 3-char hashes) plus the
|
|
82
|
+
replacement text — it never echoes the text being replaced. A `str_replace` call must reproduce that
|
|
83
|
+
text verbatim. On a 12-edit session over a realistic file this is **28% fewer output tokens** (40%
|
|
84
|
+
on multi-line ranges) — and these are *output* tokens, billed at ~5-6× the input rate. See the
|
|
85
|
+
[benchmark](#benchmark).
|
|
138
86
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
| `remove_from` | Bare 3-char hash of the first line to remove. |
|
|
143
|
-
| `remove_to` | Bare 3-char hash of the last line to remove. |
|
|
144
|
-
| `replacement_text` | Replacement text; `""` deletes the range. |
|
|
145
|
-
|
|
146
|
-
The tool verifies **every line** of the resolved range against what the model
|
|
147
|
-
was actually shown. A line inside the range that changed on disk since it was
|
|
148
|
-
served is hard-rejected with `[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]` /
|
|
149
|
-
`[E_RANGE_UNVERIFIED]`, and the current range is echoed back as fresh anchors
|
|
150
|
-
(reject-and-serve). Anchors for lines outside the post-edit diff window are
|
|
151
|
-
recovered with a `read` — that is the documented on-demand recovery.
|
|
152
|
-
|
|
153
|
-
### batch_edit
|
|
154
|
-
|
|
155
|
-
Several edits in one atomic call: `{ edits: [{ path?, remove_from,
|
|
156
|
-
remove_to, replacement_text }, …] }`. All-or-nothing — any failing item
|
|
157
|
-
rejects the whole batch with nothing written, and the failing item's current
|
|
158
|
-
range is echoed as fresh serves. Up to 32 items.
|
|
159
|
-
|
|
160
|
-
### undo_last_edit
|
|
161
|
-
|
|
162
|
-
`{ path }` reverts the last hashline edit on the file, only while the file
|
|
163
|
-
still matches the stored post-edit content. A later external write clears the
|
|
164
|
-
history instead of being overwritten. Undo survives restarts (stored in the
|
|
165
|
-
hash store).
|
|
166
|
-
|
|
167
|
-
## How it replaces the built-in tools
|
|
168
|
-
|
|
169
|
-
dsh's tool registry resolves per scope: an agent sees `agent → preset →
|
|
170
|
-
global`, and its **own** layer always wins. The built-in `read`/`edit` live on
|
|
171
|
-
the agent-preset layer, so a plain global registration cannot replace them.
|
|
172
|
-
This plugin:
|
|
173
|
-
|
|
174
|
-
1. Mounts as a host-plane Cordis plugin via its `cordis.patch.yml` bundle
|
|
175
|
-
patch.
|
|
176
|
-
2. On `agent/session-start`, registers the hashline tools **and** the
|
|
177
|
-
`tool:read` / `tool:edit` prompt sections on the agent's own scope layer —
|
|
178
|
-
they shadow the preset's built-ins for that agent and unwind automatically
|
|
179
|
-
when the agent is disposed.
|
|
180
|
-
3. Leaves the built-in `write` in place, but a scoped `tools/post-execute`
|
|
181
|
-
listener appends the hashline auto-read to write results.
|
|
87
|
+
**Correctness.** Every resolved edit range is verified against the exact lines the model was shown.
|
|
88
|
+
A stale, never-served, or ambiguous range is hard-rejected **before anything is written**, and the
|
|
89
|
+
current range is echoed back as fresh anchors (reject-and-serve) — the retry needs no `read`.
|
|
182
90
|
|
|
183
|
-
|
|
91
|
+
**A modern edit pattern for agents.** Content-addressed anchors are line-number-agnostic: edit one
|
|
92
|
+
part of a file and the hashes of the rest stay put, so chained edits need no re-reads. The model
|
|
93
|
+
pins a line by what it *is*, not by where it used to sit.
|
|
184
94
|
|
|
185
|
-
|
|
95
|
+
### How It Compares
|
|
186
96
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
97
|
+
| | hashline `edit` | `str_replace` | line-number edit |
|
|
98
|
+
| --- | :---: | :---: | :---: |
|
|
99
|
+
| Replaced text echoed in the call | ✅ no — 2 hashes | ❌ verbatim | ✅ no |
|
|
100
|
+
| Verification against what the model saw | ✅ every line | ❌ first match wins | ~ |
|
|
101
|
+
| Stale file detected | ✅ rejects, fresh anchors | ❌ may match wrong spot | ~ |
|
|
102
|
+
| Anchors survive edits above | ✅ content-addressed | ✅ content-based | ❌ re-read needed |
|
|
103
|
+
| Chained edits without re-reads | ✅ diff serves fresh anchors | ~ | ❌ |
|
|
104
|
+
| Unambiguous when text repeats | ✅ boundary anchors verified | ❌ first occurrence | ~ |
|
|
105
|
+
| Wrong-line edit can land silently | ❌ impossible | ✅ | ✅ |
|
|
106
|
+
|
|
107
|
+
> `~` = occasionally / inconsistently. Line-number edit tools accept a line range and apply it to
|
|
108
|
+
> whatever is at that offset when the call executes — cheap, but stale the moment anything above
|
|
109
|
+
> moves.
|
|
110
|
+
|
|
111
|
+
## Benchmark
|
|
190
112
|
|
|
191
|
-
|
|
113
|
+
Measured on the same 103-line file with the same 12 replacements (8 single-line, 4 multi-line of
|
|
114
|
+
3/6/10/15 lines), tokenized with the pinned `js-tiktoken` `cl100k_base`:
|
|
115
|
+
|
|
116
|
+
| Criterion | hashline | str_replace |
|
|
117
|
+
| ----------- | :---: | :---: |
|
|
118
|
+
| Replaced text sent over the wire | ✅ never | ❌ every edit |
|
|
119
|
+
| Output tokens saved (12-edit session) | ✅ **28%** | ❌ 0% |
|
|
120
|
+
| Multi-line range savings (3–15 lines) | ✅ **25–46%** | ❌ 0% |
|
|
121
|
+
| Effective cost at 5× output pricing | ✅ **~1.4× less** | ❌ 1× |
|
|
122
|
+
| Ranges verified against served state | ✅ 100% | ❌ none |
|
|
123
|
+
| Deterministic, reproducible locally | ✅ `npm run benchmark` | — |
|
|
124
|
+
|
|
125
|
+
### Reproducible
|
|
126
|
+
|
|
127
|
+
The numbers above are **deterministic and you can reproduce them locally** — `npm run benchmark`:
|
|
128
|
+
|
|
129
|
+
| Scenario | Lines | hashline | str_replace | Saved | % |
|
|
130
|
+
| --- | :---: | :---: | :---: | :---: | :---: |
|
|
131
|
+
| single-line ×8 | 1 | 311 | 314 | 3 | 1% |
|
|
132
|
+
| multi-line ×4 | 3–15 | 390 | 655 | 265 | **40%** |
|
|
133
|
+
| **TOTAL ×12** | | **701** | **969** | **268** | **28%** |
|
|
134
|
+
|
|
135
|
+
The script is deterministic by construction: a frozen corpus, a content-addressed edit script that
|
|
136
|
+
self-checks (a reformatted corpus throws instead of silently changing what's measured), and a pinned
|
|
137
|
+
tokenizer. Because everything is fixed, `npm run benchmark` gives everyone the same result.
|
|
138
|
+
|
|
139
|
+
> **Scope & honesty.** The benchmark measures **request-payload tokens** — what the model emits per
|
|
140
|
+
> edit call — with identical read traffic excluded (it cancels) and identical replacement text.
|
|
141
|
+
> It does **not** model transcription failure and retries, which is where the real-world gap is
|
|
142
|
+
> largest: the original [harness-problem](https://stencil.so/blog/the-harness-problem) post reported
|
|
143
|
+
> a **61% output-token reduction** and patch-failure drops from 46–51% to near zero after switching
|
|
144
|
+
> to anchored edits. Full methodology and limitations in
|
|
145
|
+
> [`benchmark/README.md`](benchmark/README.md).
|
|
146
|
+
|
|
147
|
+
## Installation
|
|
192
148
|
|
|
193
149
|
```sh
|
|
194
|
-
dsh plugin --profile <name> add
|
|
150
|
+
dsh plugin --profile <name> add dsh-better-edit # from npm
|
|
151
|
+
dsh plugin --profile <name> add /path/to/dsh-better-edit # from a local checkout
|
|
195
152
|
```
|
|
196
153
|
|
|
197
|
-
The profile's next session runs with the hashline tools installed. To verify
|
|
198
|
-
the layer is active:
|
|
154
|
+
The profile's next session runs with the hashline tools installed. To verify the layer is active:
|
|
199
155
|
|
|
200
156
|
```sh
|
|
201
157
|
dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
|
|
202
158
|
```
|
|
203
159
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
## Store
|
|
210
|
-
|
|
211
|
-
Hash snapshots, served-state rows, and undo history live in one SQLite store
|
|
212
|
-
**co-located with the workspace being edited** — one store per session cwd:
|
|
160
|
+
| Requirement | |
|
|
161
|
+
| --- | --- |
|
|
162
|
+
| Node | `^22.19.0 \|\| >=24.0.0` (dsh's requirement; the store uses `node:sqlite`) |
|
|
163
|
+
| Profile | a dsh profile (`dsh plugin` initializes one on first use) |
|
|
164
|
+
| Backends | sandboxed / remote filesystems supported (writes go through `ctx.fs`) |
|
|
213
165
|
|
|
214
|
-
|
|
166
|
+
## Tools
|
|
215
167
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
168
|
+
| Tool | What it does |
|
|
169
|
+
| ------ | -------------- |
|
|
170
|
+
| `read` | Returns a file with every line as `HASH│content`. Parameters: `offset` (1-based), `limit`. Paged output ends with `[Showing lines N-M of T. Use offset=… to continue.]`. Lines >200KB are shown as a marker with a `sed` hint — hash anchors need full lines. |
|
|
171
|
+
| `edit` | Replaces a range of lines by hash. `path` · `remove_from` · `remove_to` · `replacement_text` (`""` deletes). Verifies **every line** of the resolved range against served state; `[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]` / `[E_RANGE_UNVERIFIED]` reject-and-serve fresh anchors. |
|
|
172
|
+
| `batch_edit` | Up to 32 edits in one atomic call: `{ edits: [{ path?, remove_from, remove_to, replacement_text }, …] }`. All-or-nothing; the failing item's range is echoed as fresh serves. |
|
|
173
|
+
| `undo_last_edit` | `{ path }` reverts the last hashline edit, only while the file still matches the stored post-edit content; survives restarts. |
|
|
221
174
|
|
|
222
|
-
|
|
223
|
-
Corrupt stores are quarantined and rebuilt automatically. Moving to the
|
|
224
|
-
per-workspace layout does not migrate earlier undo history from the shared
|
|
225
|
-
home — treat any pre-0.1.2 undo entries as gone.
|
|
226
|
-
|
|
227
|
-
## Error codes
|
|
175
|
+
### Error codes
|
|
228
176
|
|
|
229
177
|
| Code | Meaning |
|
|
230
178
|
| --- | --- |
|
|
@@ -249,41 +197,126 @@ home — treat any pre-0.1.2 undo entries as gone.
|
|
|
249
197
|
| `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted; the edit was not applied. |
|
|
250
198
|
| `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` to clear it. |
|
|
251
199
|
|
|
252
|
-
##
|
|
200
|
+
## How It Replaces the Built-in Tools
|
|
253
201
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
anchored edits beat search-and-replace. This project is a dsh port of:
|
|
258
|
-
|
|
259
|
-
- [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit) by
|
|
260
|
-
RimuruW — the original pi-coding-agent extension that introduced
|
|
261
|
-
3-character hashes and collision resolution.
|
|
262
|
-
- [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro)
|
|
263
|
-
by YuGiMob — the hardened fork the hashline core here is ported from.
|
|
264
|
-
- [**pi-hashline-edit-lsz**](https://github.com/Rianico/pi-hashline-edit-lsz) —
|
|
265
|
-
the self-maintained fork this project tracks. The hashline core is ported
|
|
266
|
-
byte-for-byte; the tool layer is rewritten on dsh's plugin API.
|
|
202
|
+
dsh's tool registry resolves per scope: an agent sees `agent → preset → global`, and its **own**
|
|
203
|
+
layer always wins. The built-in `read`/`edit` live on the agent-preset layer, so a plain global
|
|
204
|
+
registration cannot replace them. This plugin:
|
|
267
205
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
206
|
+
1. Mounts as a host-plane Cordis plugin via its `cordis.patch.yml` bundle patch.
|
|
207
|
+
2. On `agent/session-start`, registers the hashline tools **and** the `tool:read` / `tool:edit`
|
|
208
|
+
prompt sections on the agent's own scope layer — they shadow the preset's built-ins for that
|
|
209
|
+
agent and unwind automatically when the agent is disposed.
|
|
210
|
+
3. Leaves the built-in `write` in place, but a scoped `tools/post-execute` listener appends the
|
|
211
|
+
hashline auto-read to write results.
|
|
212
|
+
|
|
213
|
+
## Store
|
|
214
|
+
|
|
215
|
+
Hash snapshots, served-state rows, and undo history live in one SQLite store **co-located with the
|
|
216
|
+
workspace being edited** — one store per session cwd:
|
|
217
|
+
|
|
218
|
+
```
|
|
219
|
+
<workspace>/.dsh_better_edit/hash-store.sqlite
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Parallel sessions in different workspaces keep separate stores (the session cwd is carried through
|
|
223
|
+
each tool call), so one project's anchors and undo history never leak into another's. Outside a tool
|
|
224
|
+
call (tests, previews) the store falls back to the shared DeepSeek Harness home
|
|
225
|
+
(`$DSH_HOME/plugins/dsh-better-edit/hash-store.sqlite`).
|
|
226
|
+
|
|
227
|
+
A 7-day TTL prunes served rows; missing-file snapshots are pruned at startup. Corrupt stores are
|
|
228
|
+
quarantined and rebuilt automatically. Moving to the per-workspace layout does not migrate earlier
|
|
229
|
+
undo history from the shared home — treat any pre-0.1.2 undo entries as gone.
|
|
230
|
+
|
|
231
|
+
## Project Structure
|
|
232
|
+
|
|
233
|
+
```
|
|
234
|
+
dsh-better-edit/
|
|
235
|
+
├── src/
|
|
236
|
+
│ ├── hashline/ # hash + served-state core (ported byte-for-byte from pi-hashline-edit-lsz)
|
|
237
|
+
│ ├── tool-read.ts # read — HASH│content, offset/limit paging
|
|
238
|
+
│ ├── tool-edit.ts # edit — range-by-hash, reject-and-serve
|
|
239
|
+
│ ├── tool-batch-edit.ts
|
|
240
|
+
│ ├── tool-undo.ts # undo_last_edit
|
|
241
|
+
│ ├── sandbox.ts # FsSandboxController mirror (sandbox_permissions/justification)
|
|
242
|
+
│ ├── write-hook.ts # auto-read appended to write results
|
|
243
|
+
│ ├── served-store.ts # per-workspace SQLite store (node:sqlite)
|
|
244
|
+
│ └── workspace.ts # session-cwd AsyncLocalStorage carrier
|
|
245
|
+
├── benchmark/ # reproducible hashline-vs-str_replace token benchmark
|
|
246
|
+
│ └── corpus/ # frozen 103-line fixture
|
|
247
|
+
├── test/ # 615 tests (ported + regression)
|
|
248
|
+
├── assets/ # logo + banner
|
|
249
|
+
├── cordis.patch.yml # bundle patch
|
|
250
|
+
└── package.json # dsh.bundle manifest
|
|
251
|
+
```
|
|
272
252
|
|
|
273
253
|
## Development
|
|
274
254
|
|
|
275
255
|
```sh
|
|
276
256
|
npm install
|
|
277
257
|
npm run typecheck # tsc --noEmit
|
|
278
|
-
npm test # vitest run
|
|
258
|
+
npm test # vitest run (615 tests)
|
|
279
259
|
npm run build # tsc → lib/
|
|
280
260
|
npm run benchmark # reproducible token-cost benchmark (benchmark/)
|
|
281
261
|
```
|
|
282
262
|
|
|
283
|
-
The test suite is ported from pi-hashline-edit-lsz
|
|
284
|
-
|
|
263
|
+
The test suite is ported from pi-hashline-edit-lsz and drives the dsh tool builders directly over a
|
|
264
|
+
local filesystem bridge.
|
|
265
|
+
|
|
266
|
+
## Roadmap
|
|
267
|
+
|
|
268
|
+
**Current state (0.1.6):** 615 tests, per-workspace store, sandbox policy participation, the
|
|
269
|
+
served-tail truncation fix, reproducible benchmark, EN + 中文 READMEs, published on npm.
|
|
270
|
+
|
|
271
|
+
<details><summary>Next</summary>
|
|
272
|
+
|
|
273
|
+
- Verify 0.1.6 live in a dsh session after the served-tail fix.
|
|
274
|
+
- Upstream the served-tail truncation fix to pi-hashline-edit-lsz / upstream (their `upsertServed`
|
|
275
|
+
never truncates either).
|
|
276
|
+
- Re-check plugin wiring against the next dsh release (pinned to `0.1.0-rc.6`; dsh is in developer
|
|
277
|
+
preview and promises breaking changes).
|
|
278
|
+
|
|
279
|
+
</details>
|
|
280
|
+
|
|
281
|
+
## Contributing
|
|
282
|
+
|
|
283
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) (or just open an [issue](https://github.com/Rianico/dsh-better-edit/issues)).
|
|
284
|
+
The most valuable contributions right now are more benchmark scenarios and edge-case tests for the
|
|
285
|
+
served-state verification.
|
|
285
286
|
|
|
286
287
|
## License
|
|
287
288
|
|
|
288
|
-
MIT — see [LICENSE](LICENSE). Ported from pi-hashline-edit-lsz (MIT), which
|
|
289
|
+
MIT License — see [LICENSE](LICENSE) for details. Ported from pi-hashline-edit-lsz (MIT), which
|
|
289
290
|
itself carries the upstream copyrights of RimuruW and YuGiMob.
|
|
291
|
+
|
|
292
|
+
## Acknowledgments
|
|
293
|
+
|
|
294
|
+
Hash-anchored editing descends from Can Bölük's
|
|
295
|
+
[*The Harness Problem*](https://stencil.so/blog/the-harness-problem) — the post that showed the
|
|
296
|
+
harness, not the model, is the bottleneck, and that anchored edits beat search-and-replace. This
|
|
297
|
+
project stands on the shoulders of:
|
|
298
|
+
|
|
299
|
+
- [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit) by RimuruW — the original
|
|
300
|
+
pi-coding-agent extension that introduced 3-character hashes and collision resolution.
|
|
301
|
+
- [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro) by YuGiMob — the
|
|
302
|
+
hardened fork the hashline core here is ported from.
|
|
303
|
+
- [**pi-hashline-edit-lsz**](https://github.com/Rianico/pi-hashline-edit-lsz) — the self-maintained
|
|
304
|
+
fork this project tracks. The hashline core is ported byte-for-byte; the tool layer is rewritten
|
|
305
|
+
on dsh's plugin API.
|
|
306
|
+
|
|
307
|
+
Related reading: [Hash anchors + Myers diff + single-token anchors
|
|
308
|
+
(dirac.run)](https://dirac.run/posts/hash-anchors-myers-diff-single-token) (a design review of the
|
|
309
|
+
O(S+R) → O(R) edit-call saving) and an independent
|
|
310
|
+
[hashline-vs-replace benchmark](https://nwyin.com/blogs/hashline-vs-replace-edit-bench.html).
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## Star History
|
|
315
|
+
|
|
316
|
+
[](https://star-history.com/#Rianico/dsh-better-edit&Date)
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
<p align="center">
|
|
321
|
+
<strong>⭐ If hashline editing made your agent edit better, give it a star!</strong>
|
|
322
|
+
</p>
|
package/README.zh.md
CHANGED
|
@@ -1,74 +1,51 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="assets/logo.svg" alt="dsh-better-edit" width="200">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
<h1 align="center">dsh-better-edit</h1>
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>面向 DeepSeek Harness 的哈希锚定编辑工具。<br>
|
|
9
|
+
按内容地址编辑——而不是行号。更省 token。绝不会改错行。</strong>
|
|
10
|
+
</p>
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="README.md">English</a> ·
|
|
14
|
+
<strong>简体中文</strong>
|
|
15
|
+
</p>
|
|
8
16
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="#快速开始">快速开始</a> •
|
|
19
|
+
<a href="#为什么用-hashline">为什么用 Hashline</a> •
|
|
20
|
+
<a href="#基准测试">基准测试</a> •
|
|
21
|
+
<a href="#安装">安装</a> •
|
|
22
|
+
<a href="#工具">工具</a> •
|
|
23
|
+
<a href="#致谢">致谢</a>
|
|
24
|
+
</p>
|
|
12
25
|
|
|
13
|
-
|
|
26
|
+
<p align="center">
|
|
27
|
+
<img src="https://img.shields.io/badge/version-0.1.7-blue.svg" alt="Version">
|
|
28
|
+
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
|
|
29
|
+
<img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-blueviolet.svg" alt="DeepSeek Harness Plugin">
|
|
30
|
+
<img src="https://img.shields.io/npm/v/dsh-better-edit" alt="npm version">
|
|
31
|
+
<img src="https://img.shields.io/npm/dm/dsh-better-edit" alt="npm downloads">
|
|
32
|
+
<img src="https://img.shields.io/github/stars/Rianico/dsh-better-edit?style=social" alt="GitHub Stars">
|
|
33
|
+
</p>
|
|
14
34
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
R --> A["ve7 │ function hello()<br/>szJ │ const x = 1<br/>kQm │ return x<br/>9xR │ }"]
|
|
19
|
-
A --> E["edit by hash<br/>remove_from : szJ<br/>remove_to : kQm<br/>replacement_text : …"]
|
|
20
|
-
E --> D["diff, fresh anchors<br/>− szJ │ const x = 1<br/>+ a3m │ const x = 2<br/> kQm │ return x"]
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
- **每行都按内容、而非位置寻址。** `read` 返回 `HASH│内容`;哈希是该行的稳定地址。行被修改则获得新哈希;行未被改动则保持原哈希,即使周围的行发生移动。
|
|
24
|
-
|
|
25
|
-
```mermaid
|
|
26
|
-
flowchart TB
|
|
27
|
-
B["before<br/>ve7 │ const a = 1<br/>szJ │ const b = 2<br/>kQm │ const c = 3"] --> X["insert 3 lines above const c"]
|
|
28
|
-
X --> C["after<br/>ve7 │ const a = 1<br/>szJ │ const b = 2<br/>x4n │ const d = 4<br/>r7p │ const e = 5<br/>kQm │ const c = 3"]
|
|
29
|
-
C --> N["kQm still names const c = 3<br/>line numbers would have shifted"]
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
- **锚点在编辑后依然有效。** 在目标上方插入或删除行,其哈希不变——之后按该哈希 `edit` 依然能精确定位。而使用行号时,每一次上方编辑都会让下方所有内容错位,并被迫重新读取。
|
|
33
|
-
- **Reject-and-serve。** 过期或从未提供过的范围会被硬性拒绝,并把当前 `HASH│内容` 行回显出来,重试无需 `read`。
|
|
34
|
-
|
|
35
|
-
## 为什么不用 `str_replace`?
|
|
36
|
-
|
|
37
|
-
传统编辑工具要求模型在给出替换内容(`old_string` + `new_string`)之前,先逐 token 复述旧代码。每次编辑都要付出 `O(被替换文本)` 的 token 成本,**而且**这正是模型最容易出错的地方:最初的
|
|
38
|
-
[harness-problem](https://stencil.so/blog/the-harness-problem) 文章报告称,多个模型在 replace 式编辑下的补丁格式失败率高达 46–51%,改用锚定编辑后**输出 token 减少 61%**。hashline 只发送两个 3 字符锚点:
|
|
39
|
-
|
|
40
|
-
| | `str_replace` | hashline `edit` |
|
|
41
|
-
| --- | --- | --- |
|
|
42
|
-
| 请求 | `{ path, old_string, new_string }` | `{ path, remove_from, remove_to, replacement_text }` |
|
|
43
|
-
| 被替换文本 | 逐字复现 | 从不发送 |
|
|
44
|
-
| 范围校验 | 无(取第一个匹配) | 每一行都与已提供状态核对 |
|
|
45
|
-
| 文件已过期 | old_string 可能仍然匹配——并命中错误的出现位置 | 被拒绝并回传新锚点(`E_RANGE_STALE`) |
|
|
46
|
-
| 文本有歧义 | 静默取第一个匹配 | 边界锚点需校验——调用 `read` 获取新锚点 |
|
|
47
|
-
|
|
48
|
-
## 基准测试 —— 可复现
|
|
49
|
-
|
|
50
|
-
`benchmark/run.mjs` 在同一份 103 行文件上、用相同的 12 组替换(8 个单行、4 个 3/6/10/15 行多行),以固定的 `js-tiktoken` `cl100k_base` 词表测量两种模式的模型侧 token 成本:
|
|
51
|
-
|
|
52
|
-
| 场景 | 行数 | hashline | str_replace | 节省 | % |
|
|
53
|
-
| --- | --- | --- | --- | --- | --- |
|
|
54
|
-
| 单行 ×8 | 1 | 311 | 314 | 3 | 1% |
|
|
55
|
-
| 多行 ×4 | 3–15 | 390 | 655 | 265 | **40%** |
|
|
56
|
-
| **合计 ×12** | | **701** | **969** | **268** | **28%** |
|
|
35
|
+
<p align="center">
|
|
36
|
+
<img src="assets/banner.svg" alt="file.ts → read → hashed lines → edit by hash → diff" width="900">
|
|
37
|
+
</p>
|
|
57
38
|
|
|
58
|
-
|
|
39
|
+
---
|
|
59
40
|
|
|
60
|
-
|
|
41
|
+
> *"瓶颈在于 harness——而不是模型。"*
|
|
42
|
+
> —— Can Bölük,[*The Harness Problem*](https://stencil.so/blog/the-harness-problem)
|
|
61
43
|
|
|
62
|
-
|
|
63
|
-
npm install # 安装 js-tiktoken(固定版本)
|
|
64
|
-
npm run benchmark # node benchmark/run.mjs
|
|
65
|
-
```
|
|
44
|
+
大多数编辑工具要求模型在改动任何东西之前,先**逐 token** 复述旧代码——而这正是 Agent 最容易出错的地方:多个模型在 replace 式编辑下的补丁格式失败率高达 46–51%。**dsh-better-edit** 走得更远。文件的每一行都分配一个唯一的 3 字符内容哈希,编辑时按哈希定位。旧文本从不回显,锚点在编辑后依然有效,每个解析出的范围都会与模型实际看到的内容逐一核对——错行编辑不可能悄悄落盘。
|
|
66
45
|
|
|
67
|
-
|
|
46
|
+
## 快速开始
|
|
68
47
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
1. 读取文件:
|
|
48
|
+
`read` 返回的每一行都带有哈希前缀——哈希*就是*这一行的地址:
|
|
72
49
|
|
|
73
50
|
```text
|
|
74
51
|
ve7│function hello() {
|
|
@@ -76,7 +53,7 @@ szJ│ console.log("world");
|
|
|
76
53
|
kQm│}
|
|
77
54
|
```
|
|
78
55
|
|
|
79
|
-
|
|
56
|
+
`edit` 按哈希范围定位,因此编辑总能落在你想要的行的位置:
|
|
80
57
|
|
|
81
58
|
```json
|
|
82
59
|
{
|
|
@@ -87,51 +64,68 @@ kQm│}
|
|
|
87
64
|
}
|
|
88
65
|
```
|
|
89
66
|
|
|
90
|
-
|
|
67
|
+
并产生带全新锚点的 diff,让下一次编辑无需重新读取即可通过校验:
|
|
91
68
|
|
|
92
|
-
|
|
69
|
+
```text
|
|
70
|
+
− szJ │ console.log("world");
|
|
71
|
+
+ a3m │ console.log('hi');
|
|
72
|
+
kQm │ }
|
|
73
|
+
```
|
|
93
74
|
|
|
94
|
-
|
|
75
|
+
## 为什么用 Hashline
|
|
95
76
|
|
|
96
|
-
|
|
77
|
+
**省 token。** 一次编辑调用只携带 `remove_from` / `remove_to`(两个 3 字符哈希)加替换文本——从不回显被替换的文本。`str_replace` 调用则必须逐字复现被替换的文本。在一个真实文件上的 12 次编辑会话中,这可以**减少 28% 的输出 token**(多行范围达 40%)——而且这些是*输出* token,按输入的约 5-6 倍计费。见[基准测试](#基准测试)。
|
|
97
78
|
|
|
98
|
-
|
|
99
|
-
| --- | --- |
|
|
100
|
-
| `path` | 要编辑的路径(相对会话 cwd;绝对路径亦可)。 |
|
|
101
|
-
| `remove_from` | 要删除的第一行的裸 3 字符哈希。 |
|
|
102
|
-
| `remove_to` | 要删除的最后一行的裸 3 字符哈希。 |
|
|
103
|
-
| `replacement_text` | 替换文本;`""` 表示删除该范围。 |
|
|
79
|
+
**正确性。** 每个解析出的编辑范围都会与模型实际看到的行逐行核对。过期、从未提供或歧义的范围会在**写入任何内容之前**被硬性拒绝,并把当前范围以全新锚点的形式回显(reject-and-serve)——重试无需 `read`。
|
|
104
80
|
|
|
105
|
-
|
|
81
|
+
**面向 Agent 的现代编辑范式。** 内容地址锚点与行号无关:编辑文件的一部分,其余行的哈希保持不变,因此连续编辑无需重新读取。模型按行**是什么**来定位,而不是按它之前在第几行。
|
|
106
82
|
|
|
107
|
-
###
|
|
83
|
+
### 对比
|
|
108
84
|
|
|
109
|
-
|
|
85
|
+
| | hashline `edit` | `str_replace` | 行号编辑 |
|
|
86
|
+
| --- | :---: | :---: | :---: |
|
|
87
|
+
| 调用中回显被替换文本 | ✅ 不需要——两个哈希 | ❌ 逐字回显 | ✅ 不需要 |
|
|
88
|
+
| 对照模型所见内容校验 | ✅ 每一行 | ❌ 取第一个匹配 | ~ |
|
|
89
|
+
| 检测文件已过期 | ✅ 拒绝并回传新锚点 | ❌ 可能匹配到错误位置 | ~ |
|
|
90
|
+
| 上方编辑后锚点依然有效 | ✅ 内容寻址 | ✅ 基于内容 | ❌ 需要重读 |
|
|
91
|
+
| 连续编辑无需重读 | ✅ diff 提供新锚点 | ~ | ❌ |
|
|
92
|
+
| 文本重复时无歧义 | ✅ 边界锚点需校验 | ❌ 取第一个出现 | ~ |
|
|
93
|
+
| 错行编辑会悄悄落盘 | ❌ 不可能 | ✅ | ✅ |
|
|
110
94
|
|
|
111
|
-
|
|
95
|
+
> `~` = 偶尔/不稳定。行号编辑工具接受一个行范围,并在调用执行时应用到该偏移处的内容——成本低,但只要上方有任何内容移动就会失效。
|
|
112
96
|
|
|
113
|
-
|
|
97
|
+
## 基准测试
|
|
114
98
|
|
|
115
|
-
|
|
99
|
+
在同一份 103 行文件上、用相同的 12 组替换(8 个单行、4 个 3/6/10/15 行多行),以固定的 `js-tiktoken` `cl100k_base` 词表测量:
|
|
116
100
|
|
|
117
|
-
|
|
101
|
+
| 指标 | hashline | str_replace |
|
|
102
|
+
| ----------- | :---: | :---: |
|
|
103
|
+
| 被替换文本是否上线 | ✅ 从不 | ❌ 每次编辑都发 |
|
|
104
|
+
| 输出 token 节省(12 次编辑) | ✅ **28%** | ❌ 0% |
|
|
105
|
+
| 多行范围节省(3–15 行) | ✅ **25–46%** | ❌ 0% |
|
|
106
|
+
| 按 5 倍输出计价的实际成本 | ✅ **低约 1.4 倍** | ❌ 1× |
|
|
107
|
+
| 范围对照已提供状态校验 | ✅ 100% | ❌ 无 |
|
|
108
|
+
| 确定性、可在本地复现 | ✅ `npm run benchmark` | — |
|
|
118
109
|
|
|
119
|
-
|
|
120
|
-
2. 在 `agent/session-start` 时,将 hashline 工具**以及** `tool:read` / `tool:edit` 提示词片段注册到 agent 自身的作用域层——从而为该 agent 遮蔽 preset 的内置工具,并在 agent 销毁时自动解除。
|
|
121
|
-
3. 保留内置的 `write`,但通过一个作用域内的 `tools/post-execute` 监听器把 hashline 自动读取附加到 write 结果之后。
|
|
110
|
+
### 可复现
|
|
122
111
|
|
|
123
|
-
|
|
112
|
+
上面的数字**是确定性的,你可以本地复现**——`npm run benchmark`:
|
|
124
113
|
|
|
125
|
-
|
|
114
|
+
| 场景 | 行数 | hashline | str_replace | 节省 | % |
|
|
115
|
+
| --- | :---: | :---: | :---: | :---: | :---: |
|
|
116
|
+
| 单行 ×8 | 1 | 311 | 314 | 3 | 1% |
|
|
117
|
+
| 多行 ×4 | 3–15 | 390 | 655 | 265 | **40%** |
|
|
118
|
+
| **合计 ×12** | | **701** | **969** | **268** | **28%** |
|
|
126
119
|
|
|
127
|
-
|
|
128
|
-
dsh plugin --profile <name> add dsh-better-edit
|
|
129
|
-
```
|
|
120
|
+
脚本天然确定:固定语料、内容寻址且自带自检的编辑脚本(语料被重排会直接抛错,而不是悄悄改变测量对象)、固定版本的 tokenizer。因为一切都是固定的,`npm run benchmark` 对每个人都是同一个结果。
|
|
130
121
|
|
|
131
|
-
|
|
122
|
+
> **范围与诚实。** 基准测试衡量的是**请求负载 token**——每次编辑调用时模型发出的内容——读文件流量完全相同故已排除(可抵消),替换文本也完全一致。它**没有**建模转录失败与重试,而真实差距恰恰主要在那边:最初的 [harness-problem](https://stencil.so/blog/the-harness-problem) 文章报告改用锚定编辑后**输出 token 减少 61%**,补丁失败率从 46–51% 降至接近零。完整的方法论与局限见 [`benchmark/README.md`](benchmark/README.md)。
|
|
123
|
+
|
|
124
|
+
## 安装
|
|
132
125
|
|
|
133
126
|
```sh
|
|
134
|
-
dsh plugin --profile <name> add
|
|
127
|
+
dsh plugin --profile <name> add dsh-better-edit # 从 npm
|
|
128
|
+
dsh plugin --profile <name> add /path/to/dsh-better-edit # 从本地源码
|
|
135
129
|
```
|
|
136
130
|
|
|
137
131
|
该 profile 的下一个会话将带着 hashline 工具运行。验证该层是否生效:
|
|
@@ -140,22 +134,22 @@ dsh plugin --profile <name> add /path/to/dsh-better-edit
|
|
|
140
134
|
dsh --profile <name> --dump-config # 会显示 "# == dsh-better-edit" 层
|
|
141
135
|
```
|
|
142
136
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
## 存储
|
|
149
|
-
|
|
150
|
-
哈希快照、已提供状态行与撤销历史存放在一个 SQLite 库中,**与被编辑的工作区放在一起**——每个会话 cwd 一个库:
|
|
137
|
+
| 要求 | |
|
|
138
|
+
| --- | --- |
|
|
139
|
+
| Node | `^22.19.0 \|\| >=24.0.0`(dsh 的要求;存储使用 `node:sqlite`) |
|
|
140
|
+
| Profile | 一个 dsh profile(首次使用 `dsh plugin` 时初始化) |
|
|
141
|
+
| 后端 | 支持沙箱/远程文件系统(写入经 `ctx.fs`) |
|
|
151
142
|
|
|
152
|
-
|
|
143
|
+
## 工具
|
|
153
144
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
145
|
+
| 工具 | 作用 |
|
|
146
|
+
| ------ | ------ |
|
|
147
|
+
| `read` | 以 `HASH│内容` 形式返回文件。参数:`offset`(1 起始)、`limit`。分页输出以 `[Showing lines N-M of T. Use offset=… to continue.]` 结尾。超过 200KB 的行显示为标记并附 `sed` 提示——哈希锚点需要完整行。 |
|
|
148
|
+
| `edit` | 按哈希替换行范围。`path` · `remove_from` · `remove_to` · `replacement_text`(`""` 表示删除)。对解析出的范围内**每一行**对照已提供状态校验;`[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]` / `[E_RANGE_UNVERIFIED]` 拒绝并回传新锚点。 |
|
|
149
|
+
| `batch_edit` | 单次原子调用最多 32 项编辑:`{ edits: [{ path?, remove_from, remove_to, replacement_text }, …] }`。全有或全无;失败项的范围会以新锚点的形式回显。 |
|
|
150
|
+
| `undo_last_edit` | `{ path }` 撤销该文件上一次 hashline 编辑,仅当文件仍与存储的编辑后内容一致时生效;重启后依然有效。 |
|
|
157
151
|
|
|
158
|
-
|
|
152
|
+
### 错误码
|
|
159
153
|
|
|
160
154
|
| 代码 | 含义 |
|
|
161
155
|
| --- | --- |
|
|
@@ -180,29 +174,98 @@ dsh --profile <name> --dump-config # 会显示 "# == dsh-better-edit" 层
|
|
|
180
174
|
| `[E_UNDO_UNAVAILABLE]` | 撤销历史无法持久化;编辑未被应用。 |
|
|
181
175
|
| `[E_WOULD_EMPTY]` | 编辑会把非空文件清空;请用 `write` 清空。 |
|
|
182
176
|
|
|
183
|
-
##
|
|
177
|
+
## 如何替换内置工具
|
|
184
178
|
|
|
185
|
-
|
|
186
|
-
[*The Harness Problem*](https://stencil.so/blog/the-harness-problem)(Can Bölük),它证明了瓶颈在于 harness 而非模型,并且锚定编辑优于搜索替换。本项目是以下作品的 dsh 移植:
|
|
179
|
+
dsh 的工具注册表按作用域解析:agent 看到的是 `agent → preset → global`,且**自身**层总是优先。内置的 `read`/`edit` 位于 agent-preset 层,因此普通的全局注册无法替换它们。本插件:
|
|
187
180
|
|
|
188
|
-
|
|
189
|
-
-
|
|
190
|
-
|
|
181
|
+
1. 通过其 `cordis.patch.yml` bundle 补丁作为宿主层 Cordis 插件挂载。
|
|
182
|
+
2. 在 `agent/session-start` 时,将 hashline 工具**以及** `tool:read` / `tool:edit` 提示词片段注册到 agent 自身的作用域层——从而为该 agent 遮蔽 preset 的内置工具,并在 agent 销毁时自动解除。
|
|
183
|
+
3. 保留内置的 `write`,但通过一个作用域内的 `tools/post-execute` 监听器把 hashline 自动读取附加到 write 结果之后。
|
|
191
184
|
|
|
192
|
-
|
|
185
|
+
## 存储
|
|
186
|
+
|
|
187
|
+
哈希快照、已提供状态行与撤销历史存放在一个 SQLite 库中,**与被编辑的工作区放在一起**——每个会话 cwd 一个库:
|
|
188
|
+
|
|
189
|
+
```
|
|
190
|
+
<workspace>/.dsh_better_edit/hash-store.sqlite
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
不同工作区中的并行会话各自持有独立的库(会话 cwd 会随每次工具调用传递),因此一个项目的锚点与撤销历史不会泄漏到另一个项目。在工具调用之外(测试、预览)会回退到共享的 DeepSeek Harness 主目录(`$DSH_HOME/plugins/dsh-better-edit/hash-store.sqlite`)。
|
|
194
|
+
|
|
195
|
+
7 天 TTL 会清理已提供的行;启动时清理缺失文件的快照。损坏的库会被隔离并自动重建。迁移到按工作区布局**不会**迁移共享主目录中的早期撤销历史——把 0.1.2 之前的撤销记录视为已丢失。
|
|
196
|
+
|
|
197
|
+
## 项目结构
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
dsh-better-edit/
|
|
201
|
+
├── src/
|
|
202
|
+
│ ├── hashline/ # 哈希 + 已提供状态核心(从 pi-hashline-edit-lsz 逐字节移植)
|
|
203
|
+
│ ├── tool-read.ts # read — HASH│内容、offset/limit 分页
|
|
204
|
+
│ ├── tool-edit.ts # edit — 按哈希范围、reject-and-serve
|
|
205
|
+
│ ├── tool-batch-edit.ts
|
|
206
|
+
│ ├── tool-undo.ts # undo_last_edit
|
|
207
|
+
│ ├── sandbox.ts # FsSandboxController 镜像(sandbox_permissions/justification)
|
|
208
|
+
│ ├── write-hook.ts # 附加到 write 结果的自动读取
|
|
209
|
+
│ ├── served-store.ts # 按工作区的 SQLite 存储(node:sqlite)
|
|
210
|
+
│ └── workspace.ts # 会话 cwd 的 AsyncLocalStorage 载体
|
|
211
|
+
├── benchmark/ # 可复现的 hashline 与 str_replace token 基准测试
|
|
212
|
+
│ └── corpus/ # 固定的 103 行语料
|
|
213
|
+
├── test/ # 615 个测试(移植 + 回归)
|
|
214
|
+
├── assets/ # logo 与 banner
|
|
215
|
+
├── cordis.patch.yml # bundle 补丁
|
|
216
|
+
└── package.json # dsh.bundle manifest
|
|
217
|
+
```
|
|
193
218
|
|
|
194
219
|
## 开发
|
|
195
220
|
|
|
196
221
|
```sh
|
|
197
222
|
npm install
|
|
198
223
|
npm run typecheck # tsc --noEmit
|
|
199
|
-
npm test # vitest run
|
|
224
|
+
npm test # vitest run(615 个测试)
|
|
200
225
|
npm run build # tsc → lib/
|
|
201
226
|
npm run benchmark # 可复现的 token 成本基准测试(benchmark/)
|
|
202
227
|
```
|
|
203
228
|
|
|
204
|
-
测试套件移植自 pi-hashline-edit-lsz
|
|
229
|
+
测试套件移植自 pi-hashline-edit-lsz,通过本地文件系统桥接直接驱动 dsh 工具构建器。
|
|
230
|
+
|
|
231
|
+
## 路线图
|
|
232
|
+
|
|
233
|
+
**当前状态(0.1.7):** 615 个测试、按工作区存储、参与沙箱策略、served-tail 截断修复、可复现基准测试、中英双语 README、已发布 npm。
|
|
234
|
+
|
|
235
|
+
<details><summary>下一步</summary>
|
|
236
|
+
|
|
237
|
+
- 在 dsh 会话中实测 0.1.7(served-tail 修复之后)。
|
|
238
|
+
- 把 served-tail 截断修复回馈给 pi-hashline-edit-lsz / 上游(他们的 `upsertServed` 同样从不截断)。
|
|
239
|
+
- 对照下一个 dsh 版本重新核对插件接线(当前固定在 `0.1.0-rc.6`;dsh 处于开发者预览阶段,承诺会有破坏性变更)。
|
|
240
|
+
|
|
241
|
+
</details>
|
|
242
|
+
|
|
243
|
+
## 贡献
|
|
244
|
+
|
|
245
|
+
见 [CONTRIBUTING.md](CONTRIBUTING.md)(或者直接开 [issue](https://github.com/Rianico/dsh-better-edit/issues))。当前最有价值的贡献是更多基准场景和针对已提供状态校验的边界测试。
|
|
205
246
|
|
|
206
247
|
## 许可证
|
|
207
248
|
|
|
208
|
-
MIT
|
|
249
|
+
MIT License——详见 [LICENSE](LICENSE)。移植自 pi-hashline-edit-lsz(MIT),其本身带有 RimuruW 与 YuGiMob 的上游版权声明。
|
|
250
|
+
|
|
251
|
+
## 致谢
|
|
252
|
+
|
|
253
|
+
哈希锚定编辑源于 Can Bölük 的 [*The Harness Problem*](https://stencil.so/blog/the-harness-problem)——那篇文章证明了瓶颈在于 harness 而非模型,并证明锚定编辑优于搜索替换。本项目站在以下巨人的肩膀上:
|
|
254
|
+
|
|
255
|
+
- [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit)(RimuruW)——引入 3 字符哈希与冲突消解的原创 pi-coding-agent 扩展。
|
|
256
|
+
- [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro)(YuGiMob)——本仓库 hashline 核心所移植自的加固版 fork。
|
|
257
|
+
- [**pi-hashline-edit-lsz**](https://github.com/Rianico/pi-hashline-edit-lsz)——本项目所跟随的自维护 fork。hashline 核心逐字节移植;工具层基于 dsh 的插件 API 重写。
|
|
258
|
+
|
|
259
|
+
延伸阅读:[Hash anchors + Myers diff + single-token anchors(dirac.run)](https://dirac.run/posts/hash-anchors-myers-diff-single-token)(关于编辑调用 O(S+R) → O(R) 节省的设计评论)以及一个独立的 [hashline 与 replace 对比基准测试](https://nwyin.com/blogs/hashline-vs-replace-edit-bench.html)。
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## Star History
|
|
264
|
+
|
|
265
|
+
[](https://star-history.com/#Rianico/dsh-better-edit&Date)
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
<p align="center">
|
|
270
|
+
<strong>⭐ 如果 hashline 编辑让 Agent 的编辑更可靠,就给它一个 star 吧!</strong>
|
|
271
|
+
</p>
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 170" width="900" height="170" role="img" aria-label="file.ts → read → hashed lines → edit by hash → diff">
|
|
2
|
+
<defs>
|
|
3
|
+
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
|
|
4
|
+
<path d="M 0 0 L 10 5 L 0 10 z" fill="#8b949e"/>
|
|
5
|
+
</marker>
|
|
6
|
+
</defs>
|
|
7
|
+
<rect width="900" height="170" rx="18" fill="#0d1117"/>
|
|
8
|
+
|
|
9
|
+
<!-- 1 · file.ts -->
|
|
10
|
+
<rect x="24" y="60" width="110" height="52" rx="10" fill="#30363d" stroke="#484f58"/>
|
|
11
|
+
<text x="79" y="82" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="14" font-weight="700" fill="#e6edf3" text-anchor="middle">file.ts</text>
|
|
12
|
+
<text x="79" y="101" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#8b949e" text-anchor="middle">function hello()</text>
|
|
13
|
+
|
|
14
|
+
<!-- arrow 1 -->
|
|
15
|
+
<line x1="138" y1="86" x2="170" y2="86" stroke="#8b949e" stroke-width="2.5" marker-end="url(#arrow)"/>
|
|
16
|
+
|
|
17
|
+
<!-- 2 · read -->
|
|
18
|
+
<rect x="174" y="60" width="104" height="52" rx="10" fill="#1f6feb" stroke="#388bfd"/>
|
|
19
|
+
<text x="226" y="82" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="14" font-weight="700" fill="#ffffff" text-anchor="middle">read</text>
|
|
20
|
+
<text x="226" y="101" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#b6d4ff" text-anchor="middle">HASH │ line</text>
|
|
21
|
+
|
|
22
|
+
<!-- arrow 2 -->
|
|
23
|
+
<line x1="282" y1="86" x2="314" y2="86" stroke="#8b949e" stroke-width="2.5" marker-end="url(#arrow)"/>
|
|
24
|
+
|
|
25
|
+
<!-- 3 · hashed lines -->
|
|
26
|
+
<rect x="318" y="30" width="196" height="112" rx="10" fill="#101623" stroke="#238636"/>
|
|
27
|
+
<rect x="334" y="40" width="32" height="18" rx="5" fill="#238636"/>
|
|
28
|
+
<text x="350" y="53" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" font-weight="700" fill="#ffffff" text-anchor="middle">ve7</text>
|
|
29
|
+
<text x="374" y="53" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#e6edf3">function hello()</text>
|
|
30
|
+
<rect x="334" y="70" width="32" height="18" rx="5" fill="#1f6feb"/>
|
|
31
|
+
<text x="350" y="83" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" font-weight="700" fill="#ffffff" text-anchor="middle">szJ</text>
|
|
32
|
+
<text x="374" y="83" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#e6edf3">const x = 1</text>
|
|
33
|
+
<rect x="334" y="100" width="32" height="18" rx="5" fill="#bf3989"/>
|
|
34
|
+
<text x="350" y="113" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" font-weight="700" fill="#ffffff" text-anchor="middle">kQm</text>
|
|
35
|
+
<text x="374" y="113" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#e6edf3">return x</text>
|
|
36
|
+
|
|
37
|
+
<!-- arrow 3 -->
|
|
38
|
+
<line x1="518" y1="86" x2="550" y2="86" stroke="#8b949e" stroke-width="2.5" marker-end="url(#arrow)"/>
|
|
39
|
+
|
|
40
|
+
<!-- 4 · edit by hash -->
|
|
41
|
+
<rect x="554" y="30" width="160" height="112" rx="10" fill="#241b33" stroke="#a371f7"/>
|
|
42
|
+
<text x="634" y="50" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" font-weight="700" fill="#d2a8ff" text-anchor="middle">edit</text>
|
|
43
|
+
<text x="634" y="70" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#e6edf3" text-anchor="middle">remove_from : szJ</text>
|
|
44
|
+
<text x="634" y="87" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#e6edf3" text-anchor="middle">remove_to : kQm</text>
|
|
45
|
+
<text x="634" y="104" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#e6edf3" text-anchor="middle">replacement_text : …</text>
|
|
46
|
+
<text x="634" y="126" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="10" fill="#8b949e" text-anchor="middle">no old text echoed</text>
|
|
47
|
+
|
|
48
|
+
<!-- arrow 4 -->
|
|
49
|
+
<line x1="718" y1="86" x2="750" y2="86" stroke="#8b949e" stroke-width="2.5" marker-end="url(#arrow)"/>
|
|
50
|
+
|
|
51
|
+
<!-- 5 · diff -->
|
|
52
|
+
<rect x="754" y="30" width="122" height="112" rx="10" fill="#101623" stroke="#da3633"/>
|
|
53
|
+
<text x="815" y="50" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" font-weight="700" fill="#ff7b72" text-anchor="middle">diff</text>
|
|
54
|
+
<text x="815" y="70" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#ffa198" text-anchor="middle">− szJ │ x = 1</text>
|
|
55
|
+
<text x="815" y="87" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#7ee787" text-anchor="middle">+ a3m │ x = 2</text>
|
|
56
|
+
<text x="815" y="104" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="11" fill="#e6edf3" text-anchor="middle">kQm │ return x</text>
|
|
57
|
+
<text x="815" y="126" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="10" fill="#8b949e" text-anchor="middle">fresh anchors</text>
|
|
58
|
+
</svg>
|
package/assets/logo.svg
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 200" width="200" height="200" role="img" aria-label="dsh-better-edit">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
|
|
4
|
+
<stop offset="0" stop-color="#1c2330"/>
|
|
5
|
+
<stop offset="1" stop-color="#0d1117"/>
|
|
6
|
+
</linearGradient>
|
|
7
|
+
</defs>
|
|
8
|
+
<rect x="8" y="8" width="184" height="184" rx="28" fill="url(#bg)" stroke="#30363d" stroke-width="2"/>
|
|
9
|
+
<!-- row 1 -->
|
|
10
|
+
<rect x="30" y="46" width="38" height="20" rx="6" fill="#1f6feb"/>
|
|
11
|
+
<text x="49" y="60" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" font-weight="700" fill="#ffffff" text-anchor="middle">ve7</text>
|
|
12
|
+
<text x="78" y="60" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" fill="#e6edf3">hello()</text>
|
|
13
|
+
<!-- row 2 -->
|
|
14
|
+
<rect x="30" y="90" width="38" height="20" rx="6" fill="#238636"/>
|
|
15
|
+
<text x="49" y="104" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" font-weight="700" fill="#ffffff" text-anchor="middle">szJ</text>
|
|
16
|
+
<text x="78" y="104" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" fill="#e6edf3">const x = 1</text>
|
|
17
|
+
<!-- row 3 -->
|
|
18
|
+
<rect x="30" y="134" width="38" height="20" rx="6" fill="#bf3989"/>
|
|
19
|
+
<text x="49" y="148" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" font-weight="700" fill="#ffffff" text-anchor="middle">kQm</text>
|
|
20
|
+
<text x="78" y="148" font-family="ui-monospace,SFMono-Regular,Menlo,Consolas,monospace" font-size="13" fill="#e6edf3">return x</text>
|
|
21
|
+
</svg>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-better-edit",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.7",
|
|
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",
|
|
@@ -17,7 +17,8 @@
|
|
|
17
17
|
"cordis.patch.yml",
|
|
18
18
|
"README.md",
|
|
19
19
|
"LICENSE",
|
|
20
|
-
"README.zh.md"
|
|
20
|
+
"README.zh.md",
|
|
21
|
+
"assets/"
|
|
21
22
|
],
|
|
22
23
|
"repository": {
|
|
23
24
|
"type": "git",
|