dsh-better-edit 0.2.1 → 0.2.2
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 +6 -0
- package/README.md +21 -5
- package/README.zh.md +24 -5
- package/lib/guidance.js +131 -22
- package/lib/index.js +9 -1
- package/lib/types/guidance.d.ts +45 -13
- package/package.json +2 -10
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,12 @@ Entries link to the originating spec issue in [pi-hashline-edit-lsz](https://git
|
|
|
6
6
|
|
|
7
7
|
## [Unreleased]
|
|
8
8
|
|
|
9
|
+
## [0.2.2] - 2026-08-19
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Guidance reset & restore defaults (issue #17): emptying or deleting an override file — or deleting its whole `<preset>/` directory — restores that section's compiled default guidance and order: the default renders at session-start and the file re-seeds at next boot (shipped presets; a deleted custom-preset override stays absent). A whitespace-only file with no front-matter fence means "I want the default"; any well-formed fence (even keyless, even an empty body) is a deliberate-intent signal and is never reset. Malformed fences now fast-fail instead of degrading to prose: a missing closing `---`, a non-integer `order`, or an unknown key rejects the file — the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
|
|
14
|
+
|
|
9
15
|
## [0.2.1] - 2026-08-18
|
|
10
16
|
|
|
11
17
|
### Added
|
package/README.md
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
<h1 align="center">dsh-better-edit</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<strong>
|
|
9
|
-
|
|
8
|
+
<strong>A better edit tool for DeepSeek Harness<br>
|
|
9
|
+
Powered by hash‑anchored positioning — not by line numbers, not by string replacement, fewer tokens, more context space for real work.</strong>
|
|
10
10
|
</p>
|
|
11
11
|
|
|
12
12
|
<p align="center">
|
|
@@ -59,8 +59,9 @@ Not for one-line touch-ups (near parity) or new files (`write`). It pays off in
|
|
|
59
59
|
### Install
|
|
60
60
|
|
|
61
61
|
```sh
|
|
62
|
-
dsh plugin --profile
|
|
63
|
-
dsh plugin --profile
|
|
62
|
+
npx @deepseek-ai/dsh plugin --profile web add github:Rianico/dsh-better-edit # from github
|
|
63
|
+
npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # from npm
|
|
64
|
+
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # from a local checkout
|
|
64
65
|
```
|
|
65
66
|
|
|
66
67
|
The profile's next session runs with the hashline tools installed. To verify the layer is active:
|
|
@@ -125,7 +126,8 @@ On first boot the plugin seeds the four shipped presets — `standard/`, `code/`
|
|
|
125
126
|
`minimal/`, `cordis/` — each with the compiled guidance as editable files (plus
|
|
126
127
|
`order` front-matter), so every preset's guidance starts editable rather than
|
|
127
128
|
blank. A `README.md` at the plugin-home root documents the scheme. Files are
|
|
128
|
-
seeded once and never rewritten, so your edits survive
|
|
129
|
+
seeded once and never rewritten, so your edits survive — a reset is the one
|
|
130
|
+
exception (see *Reset / restore defaults* below). A preset directory may
|
|
129
131
|
hold only the sections you want to override — the rest fall through to the
|
|
130
132
|
compiled defaults.
|
|
131
133
|
|
|
@@ -148,6 +150,20 @@ dir to its name. A deployment without the `agentPresets` service (no preset
|
|
|
148
150
|
roster) keeps the compiled defaults and never touches these files; presets are
|
|
149
151
|
never required.
|
|
150
152
|
|
|
153
|
+
### Reset / restore defaults
|
|
154
|
+
|
|
155
|
+
Emptying or deleting an override file restores that section's compiled default
|
|
156
|
+
guidance and order: the default renders at session-start, and the file re-seeds
|
|
157
|
+
at next boot.
|
|
158
|
+
|
|
159
|
+
- **Reset = delete the file, or empty it AND remove the front-matter fence.** A whitespace-only file with no fence means "I want the default" — the compiled default renders, and the file re-seeds at next boot for any preset dir, shipped or custom.
|
|
160
|
+
- **Blank on purpose = keep a valid fence.** Any well-formed `---` fence — even a keyless `---\n---\n`, even an empty body — is a deliberate-intent signal: the file is explicit content and is never reset or re-seeded.
|
|
161
|
+
- **Broken fence = fast fail.** A `---` fence that does not parse (missing closing `---`, non-integer `order`, unknown key) is rejected: the malformed text is never injected into the context, the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
|
|
162
|
+
- **Shipped vs custom.** Shipped preset files (`standard`, `code`, `minimal`, `cordis`) re-seed at boot; a deleted custom-preset override stays absent — absence is no override. Deleting a whole `<preset>/` directory re-seeds all four section files at boot (shipped presets).
|
|
163
|
+
- **Reset restores the current bundle defaults** — a plugin upgrade yields new defaults.
|
|
164
|
+
|
|
165
|
+
Re-seeding happens at boot, never mid-session.
|
|
166
|
+
|
|
151
167
|
## Why Hashline
|
|
152
168
|
|
|
153
169
|
**Token-saving.** An edit call carries `remove_from` / `remove_to` (two 3-char hashes) plus the
|
package/README.zh.md
CHANGED
|
@@ -5,8 +5,8 @@
|
|
|
5
5
|
<h1 align="center">dsh-better-edit</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<strong
|
|
9
|
-
|
|
8
|
+
<strong>一个专为 DeepSeek Harness 而生的更好的编辑工具。<br>
|
|
9
|
+
底层基于 hash-anchored 定位——不依赖行号,也不靠字符串替换,更少的词源消耗,留出更多的上下文空间给真正的工作。</strong>
|
|
10
10
|
</p>
|
|
11
11
|
|
|
12
12
|
<p align="center">
|
|
@@ -55,8 +55,9 @@ Hashline 用两个哈希代替旧文本——**编辑 token 减少 31%**(多
|
|
|
55
55
|
### 安装
|
|
56
56
|
|
|
57
57
|
```sh
|
|
58
|
-
dsh plugin --profile
|
|
59
|
-
dsh plugin --profile
|
|
58
|
+
npx @deepseek-ai/dsh plugin --profile web add github:Rianico/dsh-better-edit # 从 github
|
|
59
|
+
npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # 从 npm
|
|
60
|
+
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # 从本地源码
|
|
60
61
|
```
|
|
61
62
|
|
|
62
63
|
该 profile 的下一个会话将带着 hashline 工具运行。验证该层是否生效:
|
|
@@ -118,7 +119,7 @@ $DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md
|
|
|
118
119
|
|
|
119
120
|
首次启动时插件会为四个随附 preset——`standard/`、`code/`、`minimal/`、`cordis/`——各自写入编译内置的
|
|
120
121
|
可编辑指引文件(含 `order` front-matter),让每个 preset 的指引一开始就可编辑,而不是空白。插件主目录
|
|
121
|
-
根的 `README.md`
|
|
122
|
+
根的 `README.md` 说明整套机制。文件只在首次写入时生成、之后绝不被覆盖,因此你的修改会保留——唯一的例外是重置(见下文 *重置 / 恢复默认*)。preset 目录
|
|
122
123
|
里可以只放你想覆盖的片段文件,其余自动回退到编译内置默认值。
|
|
123
124
|
|
|
124
125
|
文件默认为纯文本;除非以 `order` front-matter 栅栏开头,它会改变该片段在组装后的系统提示中的位置:
|
|
@@ -137,6 +138,24 @@ session-start 时读取一次,因此修改只影响新会话——绝不影响
|
|
|
137
138
|
(即没有 preset 名册)的部署继续使用编译内置默认值,完全不会触碰这些文件;
|
|
138
139
|
preset 从来不是必需的。
|
|
139
140
|
|
|
141
|
+
### 重置 / 恢复默认
|
|
142
|
+
|
|
143
|
+
**想让指引“回到默认”?删掉覆盖文件,或把它清空(同时删掉开头的 `---` 栅栏)即可。**
|
|
144
|
+
|
|
145
|
+
清空文件时,只要文件里是空白内容、并且没有 `---` 栅栏,插件就认为你不想再自定义这一片段了,于是:
|
|
146
|
+
|
|
147
|
+
- 新会话开始时,直接使用插件内置的默认指引;
|
|
148
|
+
- 下一次启动插件时,会用默认内容把这个文件重新生成。
|
|
149
|
+
|
|
150
|
+
再细致一点:
|
|
151
|
+
|
|
152
|
+
- **为什么要连栅栏一起删**:只要文件里还有 `---` 栅栏,哪怕是空的、什么内容也没有,插件都当成“你有意留空”,不会去动它。所以“故意留空”就保留栅栏;“恢复默认”就把栅栏和内容一起清掉。
|
|
153
|
+
- **栅栏写错了会怎样**:少了一个 `---`、`order` 不是数字、出现了不认识的键——只要栅栏格式不对,插件会直接忽略这个文件:仍然渲染默认指引,并在日志里提示是哪个文件、哪里写错了。你写的正文会原样留在磁盘上,方便改好后再用。
|
|
154
|
+
- **自带 preset 与自定义 preset**:插件自带的四个 preset(`standard`、`code`、`minimal`、`cordis`)会在下一次启动时自动补全空白文件;自定义 preset 里删除的覆盖文件不会自动出现(删了就当“没有这个文件”)。删掉某一整个 preset 目录,下次启动时插件会重新生成里面的四个文件(仅限自带 preset)。
|
|
155
|
+
- **恢复的是“当前版本”的默认**:插件升级后,重置得到的是新版本带的新默认内容,不是旧版本留下的。
|
|
156
|
+
|
|
157
|
+
文件的重新生成只发生在插件启动时,绝不影响进行中的会话。
|
|
158
|
+
|
|
140
159
|
## 为什么用 Hashline
|
|
141
160
|
|
|
142
161
|
**省 token。** 一次编辑调用只携带 `remove_from` / `remove_to`(两个 3 字符哈希)加替换文本——从不回显被替换的文本。`str_replace` 调用则必须逐字复现被替换的文本。在一个真实文件上的 12 次编辑会话中,这可以**减少 31% 的输出 token**(多行范围达 43%)——而且这些是*输出* token,按输入的约 5-6 倍计费。见[基准测试](#基准测试)。
|
package/lib/guidance.js
CHANGED
|
@@ -9,11 +9,13 @@
|
|
|
9
9
|
* never the workspace store) and are resolved per section as
|
|
10
10
|
* `<preset>/<section>.md` → compiled default.
|
|
11
11
|
*
|
|
12
|
-
*
|
|
13
|
-
* fence
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
12
|
+
* fence carrying only an `order` key (`---` / `order: N` / `---`). Any
|
|
13
|
+
* well-formed fence — even keyless, even an empty body — is deliberate content
|
|
14
|
+
* and wins. A leading `---` that does not parse (a missing closing fence, a
|
|
15
|
+
* non-integer `order`, an unknown key) is a MALFORMED override and must never
|
|
16
|
+
* reach the model: resolution falls back to the compiled default and reports
|
|
17
|
+
* the file and parse reason. An absent or blank override (whitespace-only body,
|
|
18
|
+
* no fence) means "use the default" and is re-seeded at boot.
|
|
17
19
|
*
|
|
18
20
|
* Resolution is pure: no cordis services, no harness wiring. The installer
|
|
19
21
|
* ticket reads the resolved sections once per agent at session-start;
|
|
@@ -82,25 +84,41 @@ function stripCR(line) {
|
|
|
82
84
|
}
|
|
83
85
|
/**
|
|
84
86
|
* Parse an override file. Only a leading `---` fence whose lines are empty or
|
|
85
|
-
* `order: <integer>` is accepted
|
|
86
|
-
* fence, unknown key, non-integer value)
|
|
87
|
+
* `order: <integer>` is accepted. A leading `---` that does not parse (no
|
|
88
|
+
* closing fence, unknown key, non-integer value) is a malformed override;
|
|
89
|
+
* anything else is pure prose (the whole file as text).
|
|
87
90
|
*/
|
|
88
91
|
export function parseSectionFile(content) {
|
|
89
92
|
const lines = content.split("\n");
|
|
90
|
-
if (
|
|
93
|
+
if (stripCR(lines[0]) !== "---") {
|
|
91
94
|
return { text: content };
|
|
92
95
|
}
|
|
93
96
|
const close = lines.findIndex((line, index) => index > 0 && stripCR(line) === "---");
|
|
94
|
-
if (close < 0)
|
|
95
|
-
return { text: content };
|
|
97
|
+
if (close < 0) {
|
|
98
|
+
return { text: content, malformed: true, reason: "missing closing fence" };
|
|
99
|
+
}
|
|
96
100
|
let order;
|
|
97
101
|
for (let index = 1; index < close; index++) {
|
|
98
102
|
const line = stripCR(lines[index]);
|
|
99
103
|
if (line.trim() === "")
|
|
100
104
|
continue;
|
|
105
|
+
const key = line.split(":")[0].trim();
|
|
101
106
|
const match = /^order:\s*(-?\d+)\s*$/.exec(line);
|
|
102
|
-
if (!match)
|
|
103
|
-
|
|
107
|
+
if (!match) {
|
|
108
|
+
if (key === "order") {
|
|
109
|
+
const value = line.slice(line.indexOf(":") + 1).trim();
|
|
110
|
+
return {
|
|
111
|
+
text: content,
|
|
112
|
+
malformed: true,
|
|
113
|
+
reason: `non-integer order '${value}'`,
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
return {
|
|
117
|
+
text: content,
|
|
118
|
+
malformed: true,
|
|
119
|
+
reason: `unknown key '${key}'`,
|
|
120
|
+
};
|
|
121
|
+
}
|
|
104
122
|
order = Number.parseInt(match[1], 10);
|
|
105
123
|
}
|
|
106
124
|
// Front-matter body: strip leading blank lines after the closing fence so
|
|
@@ -112,6 +130,27 @@ export function parseSectionFile(content) {
|
|
|
112
130
|
bodyStart++;
|
|
113
131
|
return { order, text: body.slice(bodyStart).join("\n") };
|
|
114
132
|
}
|
|
133
|
+
/**
|
|
134
|
+
* True when an override file is blank: whitespace-only body and NO front-matter
|
|
135
|
+
* fence (the "I want the default" case). The single source of truth for whether
|
|
136
|
+
* a boot-time materialization pass should re-seed a file. False for prose with
|
|
137
|
+
* content, for any valid fence (including a keyless/empty one — a deliberate
|
|
138
|
+
* blank), and for malformed files.
|
|
139
|
+
*/
|
|
140
|
+
export function isBlankOverride(content) {
|
|
141
|
+
const parsed = parseSectionFile(content);
|
|
142
|
+
return (!parsed.malformed &&
|
|
143
|
+
parsed.order === undefined &&
|
|
144
|
+
parsed.text.trim() === "" &&
|
|
145
|
+
!startsWithFenceLine(content));
|
|
146
|
+
}
|
|
147
|
+
/** True when an override file opens with a leading `---` fence that is malformed. */
|
|
148
|
+
export function isMalformedOverride(content) {
|
|
149
|
+
return parseSectionFile(content).malformed === true;
|
|
150
|
+
}
|
|
151
|
+
function startsWithFenceLine(content) {
|
|
152
|
+
return stripCR(content.split("\n")[0]) === "---";
|
|
153
|
+
}
|
|
115
154
|
function overrideCandidates(file, options) {
|
|
116
155
|
const candidates = [];
|
|
117
156
|
if (options.presetId !== undefined) {
|
|
@@ -121,8 +160,9 @@ function overrideCandidates(file, options) {
|
|
|
121
160
|
}
|
|
122
161
|
/**
|
|
123
162
|
* Resolve one section's guidance: the first override file that exists wins,
|
|
124
|
-
* falling back to the compiled default. A missing file (ENOENT
|
|
125
|
-
* chain;
|
|
163
|
+
* falling back to the compiled default. A missing or blank file (ENOENT, or
|
|
164
|
+
* whitespace-only with no fence) advances the chain; a malformed file resolves
|
|
165
|
+
* to the compiled default and reports itself; any other read error propagates.
|
|
126
166
|
*/
|
|
127
167
|
export async function resolveSection(name, options) {
|
|
128
168
|
const section = SECTION_BY_NAME.get(name);
|
|
@@ -137,6 +177,22 @@ export async function resolveSection(name, options) {
|
|
|
137
177
|
if (content === undefined)
|
|
138
178
|
continue;
|
|
139
179
|
const parsed = parseSectionFile(content);
|
|
180
|
+
if (parsed.malformed) {
|
|
181
|
+
// A broken override must never reach the model. Resolve to the
|
|
182
|
+
// compiled default and report the file + parse reason to the caller.
|
|
183
|
+
return {
|
|
184
|
+
order: section.defaultOrder,
|
|
185
|
+
text: section.renderDefault(),
|
|
186
|
+
malformed: {
|
|
187
|
+
file: candidate,
|
|
188
|
+
reason: parsed.reason ?? "malformed override",
|
|
189
|
+
},
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
// Blank (no fence, whitespace-only) means "use the default": advance the
|
|
193
|
+
// fallback chain rather than render an empty section.
|
|
194
|
+
if (isBlankOverride(content))
|
|
195
|
+
continue;
|
|
140
196
|
return { order: parsed.order ?? section.defaultOrder, text: parsed.text };
|
|
141
197
|
}
|
|
142
198
|
return { order: section.defaultOrder, text: section.renderDefault() };
|
|
@@ -147,11 +203,16 @@ export async function resolveSection(name, options) {
|
|
|
147
203
|
*/
|
|
148
204
|
export async function composeSections(presetId, homeDir) {
|
|
149
205
|
return Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
150
|
-
const
|
|
206
|
+
const resolved = await resolveSection(section.name, {
|
|
151
207
|
presetId,
|
|
152
208
|
homeDir,
|
|
153
209
|
});
|
|
154
|
-
return {
|
|
210
|
+
return {
|
|
211
|
+
name: section.name,
|
|
212
|
+
order: resolved.order,
|
|
213
|
+
text: resolved.text,
|
|
214
|
+
malformed: resolved.malformed,
|
|
215
|
+
};
|
|
155
216
|
}));
|
|
156
217
|
}
|
|
157
218
|
/**
|
|
@@ -237,9 +298,13 @@ export const GUIDANCE_HOME_README_ZH = `# dsh-better-edit 指引
|
|
|
237
298
|
* For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
|
|
238
299
|
* undo_last_edit}.md\` rendered from the compiled defaults (with order
|
|
239
300
|
* front-matter), plus a root \`README.md\` documenting the convention.
|
|
240
|
-
* Idempotent:
|
|
241
|
-
*
|
|
242
|
-
*
|
|
301
|
+
* Idempotent: a user-edited file survives repeated calls. A blank override file
|
|
302
|
+
* (whitespace-only body, no fence) is re-seeded with the current compiled
|
|
303
|
+
* default; malformed, non-blank, and deliberate-blank (valid-fence) files are
|
|
304
|
+
* never touched. Custom preset directories present on disk are scanned the same
|
|
305
|
+
* way but never fabricated. Missing directories are created on demand (shipped
|
|
306
|
+
* presets only), and shipped files are written exclusively so two concurrent
|
|
307
|
+
* first runs race safely.
|
|
243
308
|
*/
|
|
244
309
|
export async function ensurePresetGuidance(homeDir) {
|
|
245
310
|
await mkdir(homeDir, { recursive: true });
|
|
@@ -248,10 +313,12 @@ export async function ensurePresetGuidance(homeDir) {
|
|
|
248
313
|
await mkdir(dir, { recursive: true });
|
|
249
314
|
const existing = new Set(await readdir(dir));
|
|
250
315
|
await Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
251
|
-
|
|
316
|
+
const path = join(dir, section.file);
|
|
317
|
+
if (existing.has(section.file)) {
|
|
318
|
+
await healBlankOverride(path, section);
|
|
252
319
|
return;
|
|
253
|
-
|
|
254
|
-
await writeFile(
|
|
320
|
+
}
|
|
321
|
+
await writeFile(path, seededContent(section), {
|
|
255
322
|
encoding: "utf-8",
|
|
256
323
|
flag: "wx",
|
|
257
324
|
}).catch((error) => {
|
|
@@ -262,6 +329,21 @@ export async function ensurePresetGuidance(homeDir) {
|
|
|
262
329
|
});
|
|
263
330
|
}));
|
|
264
331
|
}));
|
|
332
|
+
// Custom presets present on disk: heal existing blank section files only.
|
|
333
|
+
// Absence is respected — a custom preset's files are never fabricated, and
|
|
334
|
+
// malformed / non-blank / deliberate-blank files are left untouched.
|
|
335
|
+
const entries = await readdir(homeDir, { withFileTypes: true });
|
|
336
|
+
await Promise.all(entries
|
|
337
|
+
.filter((entry) => entry.isDirectory() && !DEFAULT_PRESETS.includes(entry.name))
|
|
338
|
+
.map(async (entry) => {
|
|
339
|
+
const dir = join(homeDir, entry.name);
|
|
340
|
+
const existing = new Set(await readdir(dir));
|
|
341
|
+
await Promise.all(GUIDANCE_SECTIONS.map(async (section) => {
|
|
342
|
+
if (!existing.has(section.file))
|
|
343
|
+
return;
|
|
344
|
+
await healBlankOverride(join(dir, section.file), section);
|
|
345
|
+
}));
|
|
346
|
+
}));
|
|
265
347
|
const homeFiles = new Set(await readdir(homeDir));
|
|
266
348
|
const readmes = [
|
|
267
349
|
["README.md", GUIDANCE_HOME_README],
|
|
@@ -280,3 +362,30 @@ export async function ensurePresetGuidance(homeDir) {
|
|
|
280
362
|
});
|
|
281
363
|
}));
|
|
282
364
|
}
|
|
365
|
+
/** The content a seeded override file carries, rendered from the current defaults. */
|
|
366
|
+
function seededContent(section) {
|
|
367
|
+
return `---\norder: ${section.defaultOrder}\n---\n\n${section.renderDefault()}`;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Heal an existing empty override file: a blank file means "use the default",
|
|
371
|
+
* so it is rewritten with the current seeded default. Malformed, non-blank, and
|
|
372
|
+
* deliberate-blank (valid-fence) files are left untouched — overwriting a
|
|
373
|
+
* malformed file would destroy the user's salvageable body. Plain overwrite:
|
|
374
|
+
* the file already exists. Errors propagate to the boot caller, which never
|
|
375
|
+
* fails init.
|
|
376
|
+
*/
|
|
377
|
+
async function healBlankOverride(path, section) {
|
|
378
|
+
let content;
|
|
379
|
+
try {
|
|
380
|
+
content = await readFile(path, "utf-8");
|
|
381
|
+
}
|
|
382
|
+
catch (error) {
|
|
383
|
+
// Vanished between readdir and read; nothing to heal.
|
|
384
|
+
if (errCode(error) === "ENOENT")
|
|
385
|
+
return;
|
|
386
|
+
throw error;
|
|
387
|
+
}
|
|
388
|
+
if (!isBlankOverride(content))
|
|
389
|
+
return;
|
|
390
|
+
await writeFile(path, seededContent(section), { encoding: "utf-8" });
|
|
391
|
+
}
|
package/lib/index.js
CHANGED
|
@@ -56,7 +56,15 @@ async function resolveAgentSections(rootCtx, agent) {
|
|
|
56
56
|
return compiledDefaultSections();
|
|
57
57
|
try {
|
|
58
58
|
const presetId = agentPresets.composedPreset(agent.ctx);
|
|
59
|
-
|
|
59
|
+
const sections = await composeSections(presetId, configDir());
|
|
60
|
+
// Warn once per agent install (this runs once per agent, under the
|
|
61
|
+
// WeakSet guard) about any malformed override we had to ignore.
|
|
62
|
+
for (const section of sections) {
|
|
63
|
+
if (section.malformed) {
|
|
64
|
+
rootCtx.logger.warn(`dsh-better-edit: ignoring malformed guidance override ${section.malformed.file}: ${section.malformed.reason}; using compiled default`);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
return sections;
|
|
60
68
|
}
|
|
61
69
|
catch (error) {
|
|
62
70
|
rootCtx.logger.warn(`dsh-better-edit: guidance resolution failed for agent ${agent.id}, using compiled defaults: ${error instanceof Error ? error.message : String(error)}`);
|
package/lib/types/guidance.d.ts
CHANGED
|
@@ -9,11 +9,13 @@
|
|
|
9
9
|
* never the workspace store) and are resolved per section as
|
|
10
10
|
* `<preset>/<section>.md` → compiled default.
|
|
11
11
|
*
|
|
12
|
-
*
|
|
13
|
-
* fence
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
12
|
+
* fence carrying only an `order` key (`---` / `order: N` / `---`). Any
|
|
13
|
+
* well-formed fence — even keyless, even an empty body — is deliberate content
|
|
14
|
+
* and wins. A leading `---` that does not parse (a missing closing fence, a
|
|
15
|
+
* non-integer `order`, an unknown key) is a MALFORMED override and must never
|
|
16
|
+
* reach the model: resolution falls back to the compiled default and reports
|
|
17
|
+
* the file and parse reason. An absent or blank override (whitespace-only body,
|
|
18
|
+
* no fence) means "use the default" and is re-seeded at boot.
|
|
17
19
|
*
|
|
18
20
|
* Resolution is pure: no cordis services, no harness wiring. The installer
|
|
19
21
|
* ticket reads the resolved sections once per agent at session-start;
|
|
@@ -41,15 +43,30 @@ export declare function renderSectionDefault(name: string): string;
|
|
|
41
43
|
export interface ParsedSection {
|
|
42
44
|
/** Front-matter `order`, when present and valid. */
|
|
43
45
|
order?: number;
|
|
44
|
-
/** The section text: the file body, or the whole file when
|
|
46
|
+
/** The section text: the file body, or the whole file when no fence is present. */
|
|
45
47
|
text: string;
|
|
48
|
+
/** True when a leading `---` fence is present but does not parse (fast fail). */
|
|
49
|
+
malformed?: boolean;
|
|
50
|
+
/** Human-readable parse reason, present only when `malformed` is true. */
|
|
51
|
+
reason?: string;
|
|
46
52
|
}
|
|
47
53
|
/**
|
|
48
54
|
* Parse an override file. Only a leading `---` fence whose lines are empty or
|
|
49
|
-
* `order: <integer>` is accepted
|
|
50
|
-
* fence, unknown key, non-integer value)
|
|
55
|
+
* `order: <integer>` is accepted. A leading `---` that does not parse (no
|
|
56
|
+
* closing fence, unknown key, non-integer value) is a malformed override;
|
|
57
|
+
* anything else is pure prose (the whole file as text).
|
|
51
58
|
*/
|
|
52
59
|
export declare function parseSectionFile(content: string): ParsedSection;
|
|
60
|
+
/**
|
|
61
|
+
* True when an override file is blank: whitespace-only body and NO front-matter
|
|
62
|
+
* fence (the "I want the default" case). The single source of truth for whether
|
|
63
|
+
* a boot-time materialization pass should re-seed a file. False for prose with
|
|
64
|
+
* content, for any valid fence (including a keyless/empty one — a deliberate
|
|
65
|
+
* blank), and for malformed files.
|
|
66
|
+
*/
|
|
67
|
+
export declare function isBlankOverride(content: string): boolean;
|
|
68
|
+
/** True when an override file opens with a leading `---` fence that is malformed. */
|
|
69
|
+
export declare function isMalformedOverride(content: string): boolean;
|
|
53
70
|
/** Options for resolving one section's guidance. */
|
|
54
71
|
export interface ResolveGuidanceOptions {
|
|
55
72
|
/** Agent preset id, or undefined to skip the preset layer. */
|
|
@@ -61,11 +78,17 @@ export interface ResolveGuidanceOptions {
|
|
|
61
78
|
export interface GuidanceResolution {
|
|
62
79
|
order: number;
|
|
63
80
|
text: string;
|
|
81
|
+
/** Set when the override file was malformed and the compiled default was used. */
|
|
82
|
+
malformed?: {
|
|
83
|
+
file: string;
|
|
84
|
+
reason: string;
|
|
85
|
+
};
|
|
64
86
|
}
|
|
65
87
|
/**
|
|
66
88
|
* Resolve one section's guidance: the first override file that exists wins,
|
|
67
|
-
* falling back to the compiled default. A missing file (ENOENT
|
|
68
|
-
* chain;
|
|
89
|
+
* falling back to the compiled default. A missing or blank file (ENOENT, or
|
|
90
|
+
* whitespace-only with no fence) advances the chain; a malformed file resolves
|
|
91
|
+
* to the compiled default and reports itself; any other read error propagates.
|
|
69
92
|
*/
|
|
70
93
|
export declare function resolveSection(name: string, options: ResolveGuidanceOptions): Promise<GuidanceResolution>;
|
|
71
94
|
/** The resolved configuration of one section, ready for the systemPrompt registry. */
|
|
@@ -73,6 +96,11 @@ export interface SectionOverride {
|
|
|
73
96
|
name: string;
|
|
74
97
|
order: number;
|
|
75
98
|
text: string;
|
|
99
|
+
/** Set when the override file was malformed and the compiled default was used. */
|
|
100
|
+
malformed?: {
|
|
101
|
+
file: string;
|
|
102
|
+
reason: string;
|
|
103
|
+
};
|
|
76
104
|
}
|
|
77
105
|
/**
|
|
78
106
|
* Resolve all four sections for a preset. `presetId === undefined` skips the
|
|
@@ -91,8 +119,12 @@ export declare const GUIDANCE_HOME_README_ZH = "# dsh-better-edit \u6307\u5F15\n
|
|
|
91
119
|
* For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
|
|
92
120
|
* undo_last_edit}.md\` rendered from the compiled defaults (with order
|
|
93
121
|
* front-matter), plus a root \`README.md\` documenting the convention.
|
|
94
|
-
* Idempotent:
|
|
95
|
-
*
|
|
96
|
-
*
|
|
122
|
+
* Idempotent: a user-edited file survives repeated calls. A blank override file
|
|
123
|
+
* (whitespace-only body, no fence) is re-seeded with the current compiled
|
|
124
|
+
* default; malformed, non-blank, and deliberate-blank (valid-fence) files are
|
|
125
|
+
* never touched. Custom preset directories present on disk are scanned the same
|
|
126
|
+
* way but never fabricated. Missing directories are created on demand (shipped
|
|
127
|
+
* presets only), and shipped files are written exclusively so two concurrent
|
|
128
|
+
* first runs race safely.
|
|
97
129
|
*/
|
|
98
130
|
export declare function ensurePresetGuidance(homeDir: string): Promise<void>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-better-edit",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.2",
|
|
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",
|
|
@@ -54,19 +54,10 @@
|
|
|
54
54
|
}
|
|
55
55
|
},
|
|
56
56
|
"dependencies": {
|
|
57
|
-
"@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
|
|
58
57
|
"diff": "^8.0.2",
|
|
59
58
|
"file-type": "^21.3.0",
|
|
60
59
|
"xxhash-wasm": "^1.1.0"
|
|
61
60
|
},
|
|
62
|
-
"peerDependencies": {
|
|
63
|
-
"@deepseek-ai/cordis": "^4.0.0",
|
|
64
|
-
"@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
|
|
65
|
-
"@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
|
|
66
|
-
"@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
|
|
67
|
-
"@deepseek-ai/dsh-session": "^0.1.0-rc.6",
|
|
68
|
-
"@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
|
|
69
|
-
},
|
|
70
61
|
"engines": {
|
|
71
62
|
"node": "^22.19.0 || >=24.0.0"
|
|
72
63
|
},
|
|
@@ -87,6 +78,7 @@
|
|
|
87
78
|
"@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
|
|
88
79
|
"@deepseek-ai/dsh-session": "0.1.0-rc.6",
|
|
89
80
|
"@deepseek-ai/dsh-tools": "0.1.0-rc.6",
|
|
81
|
+
"@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
|
|
90
82
|
"@types/node": "^24.0.0",
|
|
91
83
|
"@vitest/coverage-v8": "^4.1.10",
|
|
92
84
|
"js-tiktoken": "1.0.21",
|