dsh-better-edit 0.1.4 → 0.1.6

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.
Files changed (3) hide show
  1. package/README.md +157 -63
  2. package/README.zh.md +208 -0
  3. package/package.json +8 -5
package/README.md CHANGED
@@ -1,76 +1,105 @@
1
1
  # dsh-better-edit
2
2
 
3
+ [English](README.md) · [中文](README.zh.md)
4
+
3
5
  Hash-anchored `read` / `edit` / `batch_edit` / `undo_last_edit` tools for
4
6
  [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`).
5
- Every line of a file gets a unique 3-character hash, and you edit by hash. No
6
- line numbers, no fuzzy matching, no edits landing on the wrong line.
7
-
8
- This is a dsh port of
9
- [pi-hashline-edit-lsz](https://github.com/Rianico/pi-hashline-edit-lsz) (itself
10
- a self-maintained fork of pi-hashline-edit / pi-hashline-edit-pro by RimuruW
11
- and Yugimob). The hashline core is ported byte-for-byte; the tool layer is
12
- rewritten on dsh's plugin API.
13
-
14
- ## What you get
15
-
16
- - **Read with anchors.** Every line comes back as `HASH│content`. The hash is
17
- the line's address.
18
- - **Edit by hash.** `edit` targets a range of hashes
19
- (`remove_from` / `remove_to`), so edits always land on the lines you meant.
20
- - **Anchors that stay put.** Edit one part of a file and the hashes of the
21
- rest stay the same. Read once, keep editing.
22
- - **Fresh anchors, automatically.** After every `write` you get the new
23
- anchors (auto-read). After every `edit` you get the diff with the new
24
- hashes.
25
- - **Undo when you need it.** The last edit on a file can be reverted, even
26
- after a restart.
27
- - **Safe writes.** Permissions, line endings, BOMs, symlinks, and hard links
28
- survive every edit (writes go through `ctx.fs`, honoring sandboxed/remote
29
- backends).
30
- - **Reject-and-serve.** A stale or never-served range is hard-rejected with
31
- fresh `HASH│content` rows so the retry needs no `read`.
32
-
33
- ## How it replaces the built-in tools
34
-
35
- dsh's tool registry resolves per scope: an agent sees `agent → preset →
36
- global`, and its **own** layer always wins. The built-in `read`/`edit` live on
37
- the agent-preset layer, so a plain global registration cannot replace them.
38
- This plugin:
39
-
40
- 1. Mounts as a host-plane Cordis plugin via its `cordis.patch.yml` bundle
41
- patch.
42
- 2. On `agent/session-start`, registers the hashline tools **and** the
43
- `tool:read` / `tool:edit` prompt sections on the agent's own scope layer —
44
- they shadow the preset's built-ins for that agent and unwind automatically
45
- when the agent is disposed.
46
- 3. Leaves the built-in `write` in place, but a scoped `tools/post-execute`
47
- listener appends the hashline auto-read to write results.
48
-
49
- ## Installation
50
-
51
- From npm:
52
-
53
- ```sh
54
- dsh plugin --profile <name> add dsh-better-edit
7
+ Every line of a file gets a unique 3-character hash — a **content address** —
8
+ and you edit by hash. No line numbers, no fuzzy matching, no edits landing on
9
+ the wrong line.
10
+
11
+ Three things this plugin is built around:
12
+
13
+ - **Token-saving.** An edit call carries `remove_from` / `remove_to` (two
14
+ 3-char hashes) plus the replacement text — it never echoes the text being
15
+ replaced. A `str_replace` call must reproduce that text verbatim. On a
16
+ 12-edit session over a realistic file this is **28% fewer output tokens**
17
+ (40% on multi-line ranges) — see the [benchmark](#benchmark--reproducible).
18
+ - **Correctness.** Every resolved edit range is verified against the exact
19
+ lines the model was shown. A stale, never-served, or ambiguous range is
20
+ hard-rejected **before anything is written**, and the current range is
21
+ echoed back as fresh anchors (reject-and-serve). Wrong-line edits cannot
22
+ silently land.
23
+ - **A modern edit pattern for agents.** Content-addressed anchors are
24
+ line-number-agnostic: edit one part of a file and the hashes of the rest
25
+ stay put, so chained edits need no re-reads. The model pins a line by what
26
+ it *is*, not by where it used to sit.
27
+
28
+ ## Core concepts
29
+
30
+ ```mermaid
31
+ flowchart LR
32
+ F["file.ts"] --> R["read"]
33
+ R --> A["ve7 │ function hello()<br/>szJ │ const x = 1<br/>kQm │ return x<br/>9xR │ }"]
34
+ A --> E["edit by hash<br/>remove_from : szJ<br/>remove_to : kQm<br/>replacement_text : …"]
35
+ E --> D["diff, fresh anchors<br/>− szJ │ const x = 1<br/>+ a3m │ const x = 2<br/> kQm │ return x"]
55
36
  ```
56
37
 
57
- From a local checkout:
38
+ - **Every line is addressed by its content, not its position.** `read`
39
+ returns `HASH│content`; the hash is a stable address for that line. Change
40
+ the line and it gets a new hash; leave it alone and it keeps the hash even
41
+ as the lines around it move.
58
42
 
59
- ```sh
60
- dsh plugin --profile <name> add /path/to/dsh-better-edit
43
+ ```mermaid
44
+ flowchart TB
45
+ B["before<br/>ve7 │ const a = 1<br/>szJ │ const b = 2<br/>kQm │ const c = 3"] --> X["insert 3 lines above const c"]
46
+ 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"]
47
+ C --> N["kQm still names const c = 3<br/>line numbers would have shifted"]
61
48
  ```
62
49
 
63
- The profile's next session runs with the hashline tools installed. To verify
64
- the layer is active:
50
+ - **Anchors survive edits.** Insert or delete lines above a target and its
51
+ hash is unchanged — a later `edit` by that hash still lands on it. With
52
+ line numbers, every edit above shifts everything below and forces a
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:
65
95
 
66
96
  ```sh
67
- dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
97
+ npm install # installs js-tiktoken (pinned)
98
+ npm run benchmark # node benchmark/run.mjs
68
99
  ```
69
100
 
70
- ### Requirements
71
-
72
- - Node `^22.19.0 || >=24.0.0` (dsh's requirement; the store uses `node:sqlite`)
73
- - A dsh profile (`dsh plugin` initializes one on first use)
101
+ Full methodology, results, and honest limitations (what the baseline does and
102
+ doesn't model) are in [`benchmark/README.md`](benchmark/README.md).
74
103
 
75
104
  ## Usage
76
105
 
@@ -94,7 +123,8 @@ kQm│}
94
123
  ```
95
124
 
96
125
  1. Keep editing. Anchors for lines you didn't touch stay valid; the post-edit
97
- diff and the auto-read after `write` hand you fresh anchors.
126
+ diff and the auto-read after `write` hand you fresh anchors. A `read` is
127
+ on-demand recovery, not a per-edit ritual.
98
128
 
99
129
  ### The read tool
100
130
 
@@ -134,6 +164,48 @@ still matches the stored post-edit content. A later external write clears the
134
164
  history instead of being overwritten. Undo survives restarts (stored in the
135
165
  hash store).
136
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.
182
+
183
+ ## Installation
184
+
185
+ From npm:
186
+
187
+ ```sh
188
+ dsh plugin --profile <name> add dsh-better-edit
189
+ ```
190
+
191
+ From a local checkout:
192
+
193
+ ```sh
194
+ dsh plugin --profile <name> add /path/to/dsh-better-edit
195
+ ```
196
+
197
+ The profile's next session runs with the hashline tools installed. To verify
198
+ the layer is active:
199
+
200
+ ```sh
201
+ dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
202
+ ```
203
+
204
+ ### Requirements
205
+
206
+ - Node `^22.19.0 || >=24.0.0` (dsh's requirement; the store uses `node:sqlite`)
207
+ - A dsh profile (`dsh plugin` initializes one on first use)
208
+
137
209
  ## Store
138
210
 
139
211
  Hash snapshots, served-state rows, and undo history live in one SQLite store
@@ -177,6 +249,27 @@ home — treat any pre-0.1.2 undo entries as gone.
177
249
  | `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted; the edit was not applied. |
178
250
  | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` to clear it. |
179
251
 
252
+ ## Inspiration and lineage
253
+
254
+ Hash-anchored editing descends from Can Bölük's
255
+ [*The Harness Problem*](https://stencil.so/blog/the-harness-problem), which
256
+ showed that the harness — not the model — was the bottleneck, and that
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.
267
+
268
+ Related reading: [Hash anchors + Myers diff + single-token anchors
269
+ (dirac.run)](https://dirac.run/posts/hash-anchors-myers-diff-single-token)
270
+ (a design review of the O(S+R) → O(R) edit-call saving) and an independent
271
+ [hashline-vs-replace benchmark](https://nwyin.com/blogs/hashline-vs-replace-edit-bench.html).
272
+
180
273
  ## Development
181
274
 
182
275
  ```sh
@@ -184,12 +277,13 @@ npm install
184
277
  npm run typecheck # tsc --noEmit
185
278
  npm test # vitest run
186
279
  npm run build # tsc → lib/
280
+ npm run benchmark # reproducible token-cost benchmark (benchmark/)
187
281
  ```
188
282
 
189
- The test suite is ported from pi-hashline-edit-lsz (598 tests) and drives the
283
+ The test suite is ported from pi-hashline-edit-lsz (615 tests) and drives the
190
284
  dsh tool builders directly over a local filesystem bridge.
191
285
 
192
286
  ## License
193
287
 
194
288
  MIT — see [LICENSE](LICENSE). Ported from pi-hashline-edit-lsz (MIT), which
195
- itself carries the upstream copyrights of RimuruW and Yugimob.
289
+ itself carries the upstream copyrights of RimuruW and YuGiMob.
package/README.zh.md ADDED
@@ -0,0 +1,208 @@
1
+ # dsh-better-edit
2
+
3
+ [English](README.md) · 中文
4
+
5
+ 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)提供的基于哈希锚定的 `read` / `edit` / `batch_edit` / `undo_last_edit` 工具。文件的每一行都分配一个唯一的 3 字符哈希——即**内容地址**——编辑时按哈希定位。没有行号、没有模糊匹配、不会改错行。
6
+
7
+ 这个插件围绕三件事构建:
8
+
9
+ - **省 token。** 一次编辑调用只携带 `remove_from` / `remove_to`(两个 3 字符哈希)加替换文本——从不回显被替换的文本。`str_replace` 调用则必须逐字复现被替换的文本。在一个真实文件上的 12 次编辑会话中,这可以**减少 28% 的输出 token**(多行范围达 40%)——见[基准测试](#基准测试--可复现)。
10
+ - **正确性。** 每个解析出的编辑范围都会与模型实际看到的行逐行核对。过期、从未提供或歧义的范围会在**写入任何内容之前**被硬性拒绝,并把当前范围以全新锚点的形式回显(reject-and-serve)。错行编辑不会悄悄落盘。
11
+ - **面向 Agent 的现代编辑范式。** 内容地址锚点与行号无关:编辑文件的一部分,其余行的哈希保持不变,因此连续编辑无需重新读取。模型按行**是什么**来定位,而不是按它之前在第几行。
12
+
13
+ ## 核心概念
14
+
15
+ ```mermaid
16
+ flowchart LR
17
+ F["file.ts"] --> R["read"]
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%** |
57
+
58
+ 读文件流量对两种工具完全相同,可抵消。以上是模型的**输出** token,按输入的约 5-6 倍计费——按 5 倍计,hashline 的实际成本**低约 1.4 倍**。节省随被替换文本的规模增长:短单行接近持平(锚点开销大致抵消一行 `old_string`),多行范围为 25–46%。
59
+
60
+ 自行复现——确定性、自带自检、无需构建步骤:
61
+
62
+ ```sh
63
+ npm install # 安装 js-tiktoken(固定版本)
64
+ npm run benchmark # node benchmark/run.mjs
65
+ ```
66
+
67
+ 完整的测量方法、结果与诚实的局限说明(基线没有建模的部分)见 [`benchmark/README.md`](benchmark/README.md)。
68
+
69
+ ## 用法
70
+
71
+ 1. 读取文件:
72
+
73
+ ```text
74
+ ve7│function hello() {
75
+ szJ│ console.log("world");
76
+ kQm│}
77
+ ```
78
+
79
+ 1. 按哈希编辑某行:
80
+
81
+ ```json
82
+ {
83
+ "path": "src/main.ts",
84
+ "remove_from": "szJ",
85
+ "remove_to": "szJ",
86
+ "replacement_text": " console.log('hi');"
87
+ }
88
+ ```
89
+
90
+ 1. 继续编辑。未触碰行的锚点依然有效;编辑后的 diff 与 `write` 之后的自动读取会交给你新锚点。`read` 是按需恢复,而不是每次编辑前的例行公事。
91
+
92
+ ### read 工具
93
+
94
+ `read` 返回一个文本文件,每一行都以 `HASH│内容` 为前缀(哈希 = `A-Za-z0-9` 中的 3 个字符)。参数:`offset`(1 起始的行号)、`limit`(最大行数)。分页输出以 `[Showing lines N-M of T. Use offset=… to continue.]` 结尾。超过 200KB 的行会显示为一个标记并附带 `sed` 检查提示——哈希锚点需要完整行。
95
+
96
+ ### edit 工具
97
+
98
+ | 字段 | 含义 |
99
+ | --- | --- |
100
+ | `path` | 要编辑的路径(相对会话 cwd;绝对路径亦可)。 |
101
+ | `remove_from` | 要删除的第一行的裸 3 字符哈希。 |
102
+ | `remove_to` | 要删除的最后一行的裸 3 字符哈希。 |
103
+ | `replacement_text` | 替换文本;`""` 表示删除该范围。 |
104
+
105
+ 该工具会对解析出的范围内**每一行**与模型实际看到的内容逐一核对。范围内某行自被提供以来在磁盘上发生了变化,就会被 `[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]` / `[E_RANGE_UNVERIFIED]` 硬性拒绝,并把当前范围以全新锚点的形式回显(reject-and-serve)。diff 窗口之外行的锚点通过 `read` 恢复——这是文档化的按需恢复方式。
106
+
107
+ ### batch_edit
108
+
109
+ 在单个原子调用中完成多次编辑:`{ edits: [{ path?, remove_from, remove_to, replacement_text }, …] }`。全有或全无——任何一项失败都会使整个批次被拒绝且不写入任何内容,失败项的当前范围会以新锚点的形式回显。最多 32 项。
110
+
111
+ ### undo_last_edit
112
+
113
+ `{ path }` 撤销该文件上一次 hashline 编辑,仅当文件仍与存储的编辑后内容一致时才生效。之后发生的外部写入会清除历史记录,而不是被覆盖。撤销在重启后依然有效(存储于哈希库中)。
114
+
115
+ ## 如何替换内置工具
116
+
117
+ dsh 的工具注册表按作用域解析:agent 看到的是 `agent → preset → global`,且**自身**层总是优先。内置的 `read`/`edit` 位于 agent-preset 层,因此普通的全局注册无法替换它们。本插件:
118
+
119
+ 1. 通过其 `cordis.patch.yml` bundle 补丁作为宿主层 Cordis 插件挂载。
120
+ 2. 在 `agent/session-start` 时,将 hashline 工具**以及** `tool:read` / `tool:edit` 提示词片段注册到 agent 自身的作用域层——从而为该 agent 遮蔽 preset 的内置工具,并在 agent 销毁时自动解除。
121
+ 3. 保留内置的 `write`,但通过一个作用域内的 `tools/post-execute` 监听器把 hashline 自动读取附加到 write 结果之后。
122
+
123
+ ## 安装
124
+
125
+ 从 npm:
126
+
127
+ ```sh
128
+ dsh plugin --profile <name> add dsh-better-edit
129
+ ```
130
+
131
+ 从本地源码:
132
+
133
+ ```sh
134
+ dsh plugin --profile <name> add /path/to/dsh-better-edit
135
+ ```
136
+
137
+ 该 profile 的下一个会话将带着 hashline 工具运行。验证该层是否生效:
138
+
139
+ ```sh
140
+ dsh --profile <name> --dump-config # 会显示 "# == dsh-better-edit" 层
141
+ ```
142
+
143
+ ### 环境要求
144
+
145
+ - Node `^22.19.0 || >=24.0.0`(dsh 的要求;存储使用 `node:sqlite`)
146
+ - 一个 dsh profile(首次使用 `dsh plugin` 时初始化)
147
+
148
+ ## 存储
149
+
150
+ 哈希快照、已提供状态行与撤销历史存放在一个 SQLite 库中,**与被编辑的工作区放在一起**——每个会话 cwd 一个库:
151
+
152
+ - `<workspace>/.dsh_better_edit/hash-store.sqlite`
153
+
154
+ 不同工作区中的并行会话各自持有独立的库(会话 cwd 会随每次工具调用传递),因此一个项目的锚点与撤销历史不会泄漏到另一个项目。在工具调用之外(测试、预览)会回退到共享的 DeepSeek Harness 主目录(`$DSH_HOME/plugins/dsh-better-edit/hash-store.sqlite`)。
155
+
156
+ 7 天 TTL 会清理已提供的行;启动时清理缺失文件的快照。损坏的库会被隔离并自动重建。迁移到按工作区布局**不会**迁移共享主目录中的早期撤销历史——把 0.1.2 之前的撤销记录视为已丢失。
157
+
158
+ ## 错误码
159
+
160
+ | 代码 | 含义 |
161
+ | --- | --- |
162
+ | `[E_ACCESS]` | 文件存在但工具不可读/不可写。 |
163
+ | `[E_AMBIGUOUS_ANCHOR]` | 一个哈希匹配当前多行;调用 `read` 获取新锚点。 |
164
+ | `[E_BAD_OP]` | 范围结束先于范围开始(首尾颠倒时会自动纠正)。 |
165
+ | `[E_BAD_REF]` | `remove_from`/`remove_to` 不是裸 3 字符哈希。 |
166
+ | `[E_BAD_SHAPE]` | 请求/字段形态错误(未知字段、缺少 path、非字符串文本等)。 |
167
+ | `[E_BARE_HASH_PREFIX]` | `HASH│` 前缀被粘贴进 `replacement_text`(自动纠正)。 |
168
+ | `[E_BATCH_ABORT]` | 批次内某项失败;整个批次被拒绝,未写入任何内容。 |
169
+ | `[E_FILE_TOO_LARGE]` | 文件超过 hashline 行数上限;请改用 `write` 或其他方式。 |
170
+ | `[E_INVALID_PATCH]` | diff 预览标记被粘贴进 `replacement_text`(自动纠正)。 |
171
+ | `[E_NOOP_LOOP]` | 完全相同的编辑反复不产生任何变化;再次提交会被拒绝。 |
172
+ | `[E_NOT_FOUND]` | 文件不存在。 |
173
+ | `[E_NOT_OBSERVED]` | 该文件在本会话中尚未被观察(先读后写策略);请先调用 `read`。 |
174
+ | `[E_NOT_TEXT]` | 路径是目录、二进制或非 UTF-8 文件;hashline 只能编辑文本。 |
175
+ | `[E_RANGE_STALE]` | 某行自被读取以来在磁盘上发生变化;范围以全新锚点回显。 |
176
+ | `[E_RANGE_UNSERVED]` | 范围内包含从未提供给模型的行。 |
177
+ | `[E_RANGE_UNVERIFIED]` | 边界锚点无法对照已提供状态验证。 |
178
+ | `[E_STALE_ANCHOR]` | 锚点不再能解析;调用 `read` 获取新锚点。 |
179
+ | `[E_UNDO_STALE]` | 无法撤销:编辑之后文件被修改(或删除)。 |
180
+ | `[E_UNDO_UNAVAILABLE]` | 撤销历史无法持久化;编辑未被应用。 |
181
+ | `[E_WOULD_EMPTY]` | 编辑会把非空文件清空;请用 `write` 清空。 |
182
+
183
+ ## 灵感与血统
184
+
185
+ 哈希锚定编辑源于 Can Bölük 的
186
+ [*The Harness Problem*](https://stencil.so/blog/the-harness-problem)(Can Bölük),它证明了瓶颈在于 harness 而非模型,并且锚定编辑优于搜索替换。本项目是以下作品的 dsh 移植:
187
+
188
+ - [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit)(RimuruW)——引入 3 字符哈希与冲突消解的原创 pi-coding-agent 扩展。
189
+ - [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro)(YuGiMob)——本仓库 hashline 核心所移植自的加固版 fork。
190
+ - [**pi-hashline-edit-lsz**](https://github.com/Rianico/pi-hashline-edit-lsz)——本项目所跟随的自维护 fork。hashline 核心逐字节移植;工具层基于 dsh 的插件 API 重写。
191
+
192
+ 延伸阅读:[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)。
193
+
194
+ ## 开发
195
+
196
+ ```sh
197
+ npm install
198
+ npm run typecheck # tsc --noEmit
199
+ npm test # vitest run
200
+ npm run build # tsc → lib/
201
+ npm run benchmark # 可复现的 token 成本基准测试(benchmark/)
202
+ ```
203
+
204
+ 测试套件移植自 pi-hashline-edit-lsz(615 个测试),通过本地文件系统桥接直接驱动 dsh 工具构建器。
205
+
206
+ ## 许可证
207
+
208
+ MIT——见 [LICENSE](LICENSE)。移植自 pi-hashline-edit-lsz(MIT),其本身带有 RimuruW 与 YuGiMob 的上游版权声明。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-better-edit",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
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",
@@ -16,7 +16,8 @@
16
16
  "lib",
17
17
  "cordis.patch.yml",
18
18
  "README.md",
19
- "LICENSE"
19
+ "LICENSE",
20
+ "README.zh.md"
20
21
  ],
21
22
  "repository": {
22
23
  "type": "git",
@@ -50,10 +51,10 @@
50
51
  }
51
52
  },
52
53
  "dependencies": {
54
+ "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
53
55
  "diff": "^8.0.2",
54
56
  "file-type": "^21.3.0",
55
- "xxhash-wasm": "^1.1.0",
56
- "@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6"
57
+ "xxhash-wasm": "^1.1.0"
57
58
  },
58
59
  "peerDependencies": {
59
60
  "@deepseek-ai/cordis": "^4.0.0",
@@ -71,7 +72,8 @@
71
72
  "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
72
73
  "test": "vitest run",
73
74
  "test:watch": "vitest",
74
- "prepublishOnly": "npm run typecheck && npm test"
75
+ "prepublishOnly": "npm run typecheck && npm test",
76
+ "benchmark": "node benchmark/run.mjs"
75
77
  },
76
78
  "devDependencies": {
77
79
  "@deepseek-ai/cordis": "^4.0.1",
@@ -82,6 +84,7 @@
82
84
  "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
83
85
  "@types/node": "^24.0.0",
84
86
  "@vitest/coverage-v8": "^4.1.10",
87
+ "js-tiktoken": "1.0.21",
85
88
  "typescript": "^5.8.0",
86
89
  "vitest": "^4.1.8"
87
90
  }