dsh-better-edit 0.2.0 → 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 +24 -0
- package/README.md +173 -53
- package/README.zh.md +133 -47
- package/lib/guidance.js +391 -0
- package/lib/index.js +56 -32
- package/lib/prompts.js +53 -49
- package/lib/types/guidance.d.ts +130 -0
- package/lib/types/index.d.ts +4 -0
- package/lib/types/prompts.d.ts +19 -9
- package/package.json +3 -10
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-preset guidance overrides for the hashline tool sections.
|
|
3
|
+
*
|
|
4
|
+
* Each of the four `tool:*` prompt sections the plugin registers has a
|
|
5
|
+
* compiled default rendered from `prompts.ts` (byte-identical to the inline
|
|
6
|
+
* rendering `src/index.ts` uses today). A user can override any section's text
|
|
7
|
+
* and `order` with a plain markdown file keyed by agent preset: the override
|
|
8
|
+
* files live in the plugin's shared home (`$DSH_HOME/plugins/dsh-better-edit`,
|
|
9
|
+
* never the workspace store) and are resolved per section as
|
|
10
|
+
* `<preset>/<section>.md` → compiled default.
|
|
11
|
+
*
|
|
12
|
+
* 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.
|
|
19
|
+
*
|
|
20
|
+
* Resolution is pure: no cordis services, no harness wiring. The installer
|
|
21
|
+
* ticket reads the resolved sections once per agent at session-start;
|
|
22
|
+
* nothing here watches or caches files.
|
|
23
|
+
* @module dsh-better-edit/guidance
|
|
24
|
+
*/
|
|
25
|
+
/** The presets shipped by the harness, each seeded with editable guidance. */
|
|
26
|
+
export declare const DEFAULT_PRESETS: readonly string[];
|
|
27
|
+
/** One overridable tool section. */
|
|
28
|
+
export interface GuidanceSection {
|
|
29
|
+
/** Registry section name, e.g. `tool:edit`. */
|
|
30
|
+
name: string;
|
|
31
|
+
/** Override file name inside a preset directory, e.g. `edit.md`. */
|
|
32
|
+
file: string;
|
|
33
|
+
/** Order used when the override file carries no front-matter `order`. */
|
|
34
|
+
defaultOrder: number;
|
|
35
|
+
/** The compiled default text, byte-identical to today's inline rendering. */
|
|
36
|
+
renderDefault(): string;
|
|
37
|
+
}
|
|
38
|
+
/** The four sections, in default-order sequence. */
|
|
39
|
+
export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
|
|
40
|
+
/** Render the compiled default text for one section. */
|
|
41
|
+
export declare function renderSectionDefault(name: string): string;
|
|
42
|
+
/** The parsed content of one override file. */
|
|
43
|
+
export interface ParsedSection {
|
|
44
|
+
/** Front-matter `order`, when present and valid. */
|
|
45
|
+
order?: number;
|
|
46
|
+
/** The section text: the file body, or the whole file when no fence is present. */
|
|
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;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Parse an override file. Only a leading `---` fence whose lines are empty or
|
|
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).
|
|
58
|
+
*/
|
|
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;
|
|
70
|
+
/** Options for resolving one section's guidance. */
|
|
71
|
+
export interface ResolveGuidanceOptions {
|
|
72
|
+
/** Agent preset id, or undefined to skip the preset layer. */
|
|
73
|
+
presetId?: string;
|
|
74
|
+
/** Plugin shared home directory (`$DSH_HOME/plugins/dsh-better-edit`). */
|
|
75
|
+
homeDir: string;
|
|
76
|
+
}
|
|
77
|
+
/** The resolved text and order for one section. */
|
|
78
|
+
export interface GuidanceResolution {
|
|
79
|
+
order: number;
|
|
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
|
+
};
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Resolve one section's guidance: the first override file that exists wins,
|
|
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.
|
|
92
|
+
*/
|
|
93
|
+
export declare function resolveSection(name: string, options: ResolveGuidanceOptions): Promise<GuidanceResolution>;
|
|
94
|
+
/** The resolved configuration of one section, ready for the systemPrompt registry. */
|
|
95
|
+
export interface SectionOverride {
|
|
96
|
+
name: string;
|
|
97
|
+
order: number;
|
|
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
|
+
};
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Resolve all four sections for a preset. `presetId === undefined` skips the
|
|
107
|
+
* `<preset>/` layer and resolves straight to the compiled defaults.
|
|
108
|
+
*/
|
|
109
|
+
export declare function composeSections(presetId: string | undefined, homeDir: string): Promise<SectionOverride[]>;
|
|
110
|
+
/**
|
|
111
|
+
* The root README: the per-preset customization convention users see in the
|
|
112
|
+
* plugin home.
|
|
113
|
+
*/
|
|
114
|
+
export declare const GUIDANCE_HOME_README = "# dsh-better-edit guidance\n\nEach agent preset has its own guidance directory here: `<preset>/<section>.md`.\nOn first boot the plugin seeds the shipped presets (`standard`, `code`,\n`minimal`, `cordis`) with the compiled defaults; existing files are never\noverwritten, so your edits survive.\n\nEach file is one tool section:\n\n- `read.md` -> `tool:read`\n- `edit.md` -> `tool:edit`\n- `batch_edit.md` -> `tool:batch_edit`\n- `undo_last_edit.md` -> `tool:undo_last_edit`\n\n## Customize\n\nEdit the `<section>.md` file for the preset and section you want to change \u2014\nthe file body IS the text the model reads for that section. Files are read once\nper agent at session-start, so edits apply to new sessions.\n\nAn optional YAML front-matter fence places the section at a custom position in\nthe assembled system prompt:\n\n ---\n order: 150\n ---\n\n <section text>\n\nA file without front-matter keeps the default order. A malformed fence (a\nmissing closing `---`, a non-integer `order`, an unknown key) makes the whole\nfile plain prose.\n\n## Fallback\n\nA preset with no directory here, or a missing section file, falls back to the\ncompiled defaults in the plugin bundle. To customize a preset that has no\nseeded directory, copy a seeded one to its name.\n";
|
|
115
|
+
export declare const GUIDANCE_HOME_README_ZH = "# dsh-better-edit \u6307\u5F15\n\n\u6BCF\u4E2A agent preset \u5728\u8FD9\u91CC\u90FD\u6709\u81EA\u5DF1\u7684\u6307\u5F15\u76EE\u5F55\uFF1A`<preset>/<section>.md`\u3002\u9996\u6B21\u542F\u52A8\u65F6\n\u63D2\u4EF6\u4F1A\u4E3A\u968F\u9644\u7684 preset\uFF08`standard`\u3001`code`\u3001`minimal`\u3001`cordis`\uFF09\u5199\u5165\u7F16\u8BD1\u5185\u7F6E\u7684\n\u9ED8\u8BA4\u5185\u5BB9\uFF1B\u5DF2\u6709\u6587\u4EF6\u7EDD\u4E0D\u88AB\u8986\u76D6\uFF0C\u56E0\u6B64\u4F60\u7684\u7F16\u8F91\u4F1A\u4FDD\u7559\u3002\n\n\u6BCF\u4E2A\u6587\u4EF6\u5BF9\u5E94\u4E00\u4E2A\u5DE5\u5177\u7247\u6BB5\uFF1A\n\n- `read.md` -> `tool:read`\n- `edit.md` -> `tool:edit`\n- `batch_edit.md` -> `tool:batch_edit`\n- `undo_last_edit.md` -> `tool:undo_last_edit`\n\n## \u81EA\u5B9A\u4E49\n\n\u7F16\u8F91\u4F60\u60F3\u4FEE\u6539\u7684 preset \u4E0E\u7247\u6BB5\u7684 `<section>.md` \u6587\u4EF6\u5373\u53EF\u2014\u2014\u6587\u4EF6\u6B63\u6587\u5C31\u662F\u8BE5\u7247\u6BB5\u5448\n\u73B0\u7ED9\u6A21\u578B\u7684\u6587\u672C\u3002\u6587\u4EF6\u5728 agent \u7684 session-start \u65F6\u8BFB\u53D6\u4E00\u6B21\uFF0C\u56E0\u6B64\u4FEE\u6539\u53EA\u5F71\u54CD\u65B0\u4F1A\u8BDD\u3002\n\n\u53EF\u4EE5\u7528\u53EF\u9009\u7684 YAML front-matter \u6805\u680F\u628A\u7247\u6BB5\u653E\u5230\u7EC4\u88C5\u540E\u7CFB\u7EDF\u63D0\u793A\u4E2D\u7684\u81EA\u5B9A\u4E49\u4F4D\u7F6E\uFF1A\n\n ---\n order: 150\n ---\n\n <\u7247\u6BB5\u6587\u672C>\n\n\u6CA1\u6709 front-matter \u7684\u6587\u4EF6\u4FDD\u6301\u9ED8\u8BA4\u987A\u5E8F\u3002\u683C\u5F0F\u9519\u8BEF\u7684\u6805\u680F\uFF08\u7F3A\u5C11\u6536\u5C3E `---`\u3001\u975E\u6574\u6570\n`order`\u3001\u672A\u77E5\u952E\uFF09\u4F1A\u8BA9\u6574\u4E2A\u6587\u4EF6\u9000\u5316\u4E3A\u7EAF\u6587\u672C\u3002\n\n## \u56DE\u9000\n\n\u8FD9\u91CC\u6CA1\u6709\u5BF9\u5E94\u76EE\u5F55\u7684 preset\u3001\u6216\u7F3A\u5931\u67D0\u4E2A\u7247\u6BB5\u6587\u4EF6\u65F6\uFF0C\u4F1A\u56DE\u9000\u5230\u63D2\u4EF6\u5305\u5185\u7684\u7F16\u8BD1\u5185\u7F6E\u9ED8\u8BA4\n\u503C\u3002\u8981\u81EA\u5B9A\u4E49\u6CA1\u6709\u79CD\u5B50\u76EE\u5F55\u7684 preset\uFF0C\u628A\u4E00\u4E2A\u79CD\u5B50\u76EE\u5F55\u590D\u5236\u6210\u5B83\u7684\u540D\u5B57\u5373\u53EF\u3002\n";
|
|
116
|
+
/**
|
|
117
|
+
* Materialize per-preset guidance directories in the plugin home.
|
|
118
|
+
*
|
|
119
|
+
* For each of \`DEFAULT_PRESETS\` creates \`<preset>/{read,edit,batch_edit,
|
|
120
|
+
* undo_last_edit}.md\` rendered from the compiled defaults (with order
|
|
121
|
+
* front-matter), plus a root \`README.md\` documenting the convention.
|
|
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.
|
|
129
|
+
*/
|
|
130
|
+
export declare function ensurePresetGuidance(homeDir: string): Promise<void>;
|
package/lib/types/index.d.ts
CHANGED
|
@@ -9,6 +9,10 @@
|
|
|
9
9
|
* automatically when the agent is disposed. The built-in `write` stays in
|
|
10
10
|
* place; a scoped `tools/post-execute` listener appends the fresh hashline
|
|
11
11
|
* preview to write results.
|
|
12
|
+
*
|
|
13
|
+
* The four `tool:*` guidance sections resolve per agent preset from override
|
|
14
|
+
* files in the shared home (see `src/guidance.ts`); deployments without the
|
|
15
|
+
* `agentPresets` service keep the compiled defaults unchanged.
|
|
12
16
|
* @module dsh-better-edit
|
|
13
17
|
*/
|
|
14
18
|
import type { Context } from "@deepseek-ai/cordis";
|
package/lib/types/prompts.d.ts
CHANGED
|
@@ -1,17 +1,27 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Model-facing prompt text for the hashline tools, embedded so the bundle
|
|
3
|
-
* ships no external prompt files. Each tool's description is short;
|
|
4
|
-
* `tool:*` system-prompt sections carry the
|
|
5
|
-
* reads when the tools are presented.
|
|
3
|
+
* ships no external prompt files. Each tool's schema `description` is short;
|
|
4
|
+
* the `tool:*` system-prompt sections carry the brief guidance the model
|
|
5
|
+
* reads when the tools are presented. Guidance is uniform: a one-line opener
|
|
6
|
+
* followed by tight bullets.
|
|
6
7
|
* @module dsh-better-edit/prompts
|
|
7
8
|
*/
|
|
9
|
+
/**
|
|
10
|
+
* One tool's guidance: a brief opener plus concise bullets. The `intro` is
|
|
11
|
+
* shown above the bullets; it does not duplicate the tool-schema `description`
|
|
12
|
+
* (that already reaches the model through the tool catalog).
|
|
13
|
+
*/
|
|
14
|
+
export interface ToolGuidance {
|
|
15
|
+
/** One-line lead shown above the bullets. */
|
|
16
|
+
intro: string;
|
|
17
|
+
/** Concise bullets; each is self-contained within its section. */
|
|
18
|
+
lines: readonly string[];
|
|
19
|
+
}
|
|
8
20
|
export declare const EDIT_DESCRIPTION: string;
|
|
9
|
-
export declare const
|
|
10
|
-
export declare const EDIT_GUIDELINES: string[];
|
|
21
|
+
export declare const EDIT_GUIDANCE: ToolGuidance;
|
|
11
22
|
export declare const READ_DESCRIPTION: string;
|
|
12
|
-
export declare const
|
|
13
|
-
export declare const READ_GUIDELINES: string[];
|
|
23
|
+
export declare const READ_GUIDANCE: ToolGuidance;
|
|
14
24
|
export declare const BATCH_EDIT_DESCRIPTION: string;
|
|
15
|
-
export declare const
|
|
25
|
+
export declare const BATCH_EDIT_GUIDANCE: ToolGuidance;
|
|
16
26
|
export declare const UNDO_DESCRIPTION: string;
|
|
17
|
-
export declare const
|
|
27
|
+
export declare const UNDO_GUIDANCE: ToolGuidance;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-better-edit",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.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",
|
|
@@ -35,6 +35,7 @@
|
|
|
35
35
|
"dsh-plugin",
|
|
36
36
|
"deepseek-harness",
|
|
37
37
|
"coding-agent",
|
|
38
|
+
"oh-my-pi",
|
|
38
39
|
"hashline",
|
|
39
40
|
"hash-anchored",
|
|
40
41
|
"hash",
|
|
@@ -53,19 +54,10 @@
|
|
|
53
54
|
}
|
|
54
55
|
},
|
|
55
56
|
"dependencies": {
|
|
56
|
-
"@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
|
|
57
57
|
"diff": "^8.0.2",
|
|
58
58
|
"file-type": "^21.3.0",
|
|
59
59
|
"xxhash-wasm": "^1.1.0"
|
|
60
60
|
},
|
|
61
|
-
"peerDependencies": {
|
|
62
|
-
"@deepseek-ai/cordis": "^4.0.0",
|
|
63
|
-
"@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
|
|
64
|
-
"@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
|
|
65
|
-
"@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
|
|
66
|
-
"@deepseek-ai/dsh-session": "^0.1.0-rc.6",
|
|
67
|
-
"@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
|
|
68
|
-
},
|
|
69
61
|
"engines": {
|
|
70
62
|
"node": "^22.19.0 || >=24.0.0"
|
|
71
63
|
},
|
|
@@ -86,6 +78,7 @@
|
|
|
86
78
|
"@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
|
|
87
79
|
"@deepseek-ai/dsh-session": "0.1.0-rc.6",
|
|
88
80
|
"@deepseek-ai/dsh-tools": "0.1.0-rc.6",
|
|
81
|
+
"@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
|
|
89
82
|
"@types/node": "^24.0.0",
|
|
90
83
|
"@vitest/coverage-v8": "^4.1.10",
|
|
91
84
|
"js-tiktoken": "1.0.21",
|