peaks-loop 4.1.12 → 4.1.14
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/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +118 -0
- package/dist/cli/commands/_register.js +2 -0
- package/dist/cli/commands/batch-commands.d.ts +6 -0
- package/dist/cli/commands/batch-commands.js +70 -0
- package/dist/cli/commands/batch-diagnose-command.d.ts +10 -0
- package/dist/cli/commands/batch-diagnose-command.js +196 -0
- package/dist/cli/commands/batch-diagnose-envelope.d.ts +25 -0
- package/dist/cli/commands/batch-diagnose-envelope.js +60 -0
- package/dist/cli/commands/batch-diagnose-record.d.ts +21 -0
- package/dist/cli/commands/batch-diagnose-record.js +51 -0
- package/dist/cli/commands/batch-item-input.d.ts +59 -0
- package/dist/cli/commands/batch-item-input.js +113 -0
- package/dist/cli/commands/batch-report-command.d.ts +22 -0
- package/dist/cli/commands/batch-report-command.js +199 -0
- package/dist/cli/commands/code-gate-command.d.ts +18 -0
- package/dist/cli/commands/code-gate-command.js +95 -32
- package/dist/cli/commands/core/skill-context-verdict.d.ts +16 -1
- package/dist/cli/commands/core/skill-context-verdict.js +38 -8
- package/dist/cli/commands/lint-commands.js +8 -0
- package/dist/cli/commands/lint-rules-command.d.ts +14 -0
- package/dist/cli/commands/lint-rules-command.js +44 -0
- package/dist/services/batch/batch-active-batch.d.ts +55 -0
- package/dist/services/batch/batch-active-batch.js +127 -0
- package/dist/services/batch/batch-context-reminder.d.ts +85 -0
- package/dist/services/batch/batch-context-reminder.js +201 -0
- package/dist/services/batch/batch-diagnosis-finding.d.ts +25 -0
- package/dist/services/batch/batch-diagnosis-finding.js +227 -0
- package/dist/services/batch/batch-diagnosis-report-store.d.ts +49 -0
- package/dist/services/batch/batch-diagnosis-report-store.js +133 -0
- package/dist/services/batch/batch-diagnosis-summary.d.ts +31 -0
- package/dist/services/batch/batch-diagnosis-summary.js +129 -0
- package/dist/services/batch/batch-diagnosis.d.ts +36 -0
- package/dist/services/batch/batch-diagnosis.js +107 -0
- package/dist/services/batch/batch-entry.d.ts +22 -0
- package/dist/services/batch/batch-entry.js +42 -0
- package/dist/services/batch/batch-fix-agent.d.ts +39 -0
- package/dist/services/batch/batch-fix-agent.js +126 -0
- package/dist/services/batch/batch-fix-types.d.ts +85 -0
- package/dist/services/batch/batch-fix-types.js +11 -0
- package/dist/services/batch/batch-fix.d.ts +15 -0
- package/dist/services/batch/batch-fix.js +229 -0
- package/dist/services/batch/batch-phase-advance.d.ts +45 -0
- package/dist/services/batch/batch-phase-advance.js +105 -0
- package/dist/services/batch/batch-progress-store.d.ts +52 -0
- package/dist/services/batch/batch-progress-store.js +219 -0
- package/dist/services/batch/batch-progress-types.d.ts +79 -0
- package/dist/services/batch/batch-progress-types.js +10 -0
- package/dist/services/batch/batch-recovery.d.ts +5 -0
- package/dist/services/batch/batch-recovery.js +24 -0
- package/dist/services/batch/batch-verify.d.ts +93 -0
- package/dist/services/batch/batch-verify.js +216 -0
- package/dist/services/code/auto-compact-decision.d.ts +17 -0
- package/dist/services/code/auto-compact-decision.js +6 -0
- package/dist/services/code/auto-compact-orchestrator.js +6 -0
- package/dist/services/code/batch-compaction-point.d.ts +45 -0
- package/dist/services/code/batch-compaction-point.js +99 -0
- package/dist/services/context/context-schema.d.ts +1 -1
- package/dist/services/hooks/pre-tool-code-gate.d.ts +33 -1
- package/dist/services/hooks/pre-tool-code-gate.js +67 -6
- package/dist/services/lint/curated-rule-reader.d.ts +37 -0
- package/dist/services/lint/curated-rule-reader.js +179 -0
- package/dist/services/lint/project-lint-declarations.d.ts +27 -0
- package/dist/services/lint/project-lint-declarations.js +217 -0
- package/dist/services/lint/project-lint-tool-detection.d.ts +14 -0
- package/dist/services/lint/project-lint-tool-detection.js +208 -0
- package/dist/services/lint/project-lint-tool-rules.d.ts +19 -0
- package/dist/services/lint/project-lint-tool-rules.js +199 -0
- package/dist/services/lint/rule-pre-read-types.d.ts +66 -0
- package/dist/services/lint/rule-pre-read-types.js +22 -0
- package/dist/services/lint/rule-pre-read.d.ts +20 -0
- package/dist/services/lint/rule-pre-read.js +145 -0
- package/dist/services/skill/skill-search-service.d.ts +3 -3
- package/package.json +5 -5
- package/skills/peaks-code/references/micro-cycle.md +13 -1
- package/skills/peaks-race-code/SKILL.md +40 -1
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
// src/services/batch/batch-diagnosis-finding.ts
|
|
2
|
+
//
|
|
3
|
+
// What a diagnosis report SAYS, read out of the report itself.
|
|
4
|
+
//
|
|
5
|
+
// WHY THIS IS A SEPARATE MODULE. The diagnosis report has two forms: the
|
|
6
|
+
// full report the diagnostician produced, and the bounded summary the
|
|
7
|
+
// orchestrator's window may hold (see `batch-diagnosis-summary.ts`). The
|
|
8
|
+
// summary is BUILT from this module's answer, and the answer is read from
|
|
9
|
+
// the report — never typed by hand. The file set is a MEASUREMENT, and a
|
|
10
|
+
// hand-typed copy of a measurement is a guess; a guess here is a wave
|
|
11
|
+
// that puts two agents on one file.
|
|
12
|
+
//
|
|
13
|
+
// WHY THE PARSER IS TOLERANT BUT NOT GUESSY. A heading must be a
|
|
14
|
+
// heading: the label, optionally followed by the prompt's bilingual
|
|
15
|
+
// parenthetical and/or a colon. Free prose that merely contains the word
|
|
16
|
+
// "sketch" is not a heading, and a report with no heading at all parses
|
|
17
|
+
// to `null` — "this report is not in the expected shape", which is a
|
|
18
|
+
// different answer from "this report says nothing".
|
|
19
|
+
//
|
|
20
|
+
// THE REPORT SHAPE. The diagnosis prompt (`buildDiagnosisPrompt`) asks for
|
|
21
|
+
// four things in this order: root cause, expected files, risk surface hit,
|
|
22
|
+
// fix sketch. Each is introduced by a labelled heading, and the parser
|
|
23
|
+
// accepts that heading with or without markdown decoration and with or
|
|
24
|
+
// without the bilingual parenthetical (`Root cause (根因)`). The risk
|
|
25
|
+
// section is recognised so that it ENDS the section before it — the file
|
|
26
|
+
// set must not swallow the risk number.
|
|
27
|
+
import { normalizeFileSet } from './batch-progress-store.js';
|
|
28
|
+
/**
|
|
29
|
+
* The section headings the parser recognises.
|
|
30
|
+
*
|
|
31
|
+
* Order matters: the longer label is tried first, so `Expected files` is
|
|
32
|
+
* not read as `files` and `Fix sketch` is not read as `sketch`.
|
|
33
|
+
*/
|
|
34
|
+
const MARKERS = [
|
|
35
|
+
{ key: 'rootCause', marker: 'root cause' },
|
|
36
|
+
{ key: 'rootCause', marker: '根因' },
|
|
37
|
+
{ key: 'files', marker: 'expected files' },
|
|
38
|
+
{ key: 'files', marker: '预计文件集' },
|
|
39
|
+
{ key: 'files', marker: '文件集' },
|
|
40
|
+
{ key: 'risk', marker: 'risk surface hit' },
|
|
41
|
+
{ key: 'risk', marker: 'risk surface' },
|
|
42
|
+
{ key: 'risk', marker: '风险面' },
|
|
43
|
+
{ key: 'sketch', marker: 'fix sketch' },
|
|
44
|
+
{ key: 'sketch', marker: '修复草图' },
|
|
45
|
+
{ key: 'sketch', marker: 'sketch' }
|
|
46
|
+
];
|
|
47
|
+
/**
|
|
48
|
+
* Strip the decoration a heading may carry: markdown heading marks, list
|
|
49
|
+
* numbering, a bullet, and emphasis.
|
|
50
|
+
*
|
|
51
|
+
* Only the DOUBLE emphasis is removed everywhere: a single underscore is
|
|
52
|
+
* part of an identifier (`session_manager`), and a file set that lost its
|
|
53
|
+
* underscores would name files that do not exist.
|
|
54
|
+
*/
|
|
55
|
+
function stripDecoration(line) {
|
|
56
|
+
let text = line.trim();
|
|
57
|
+
text = text.replace(/^#{1,6}\s*/, '');
|
|
58
|
+
text = text.replace(/^\(?\d+[.)]\s*/, '');
|
|
59
|
+
text = text.replace(/^[-*+]\s+/, '');
|
|
60
|
+
text = text.replace(/\*\*|__/g, '');
|
|
61
|
+
text = text.replace(/^(?:\*|_)+/, '');
|
|
62
|
+
text = text.replace(/(?:\*|_)+$/, '');
|
|
63
|
+
return text.trim();
|
|
64
|
+
}
|
|
65
|
+
/** The closing bracket of a parenthetical, in either width. */
|
|
66
|
+
function findParenEnd(text) {
|
|
67
|
+
const half = text.indexOf(')');
|
|
68
|
+
const full = text.indexOf(')');
|
|
69
|
+
if (half === -1)
|
|
70
|
+
return full;
|
|
71
|
+
if (full === -1)
|
|
72
|
+
return half;
|
|
73
|
+
return Math.min(half, full);
|
|
74
|
+
}
|
|
75
|
+
/** Whether the text after a label opens the answer rather than continuing prose. */
|
|
76
|
+
function isLabelSeparator(text) {
|
|
77
|
+
return text.startsWith(':') || text.startsWith(':') || text.startsWith('—');
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The text that follows a label, and whether the line is a heading at all.
|
|
81
|
+
*
|
|
82
|
+
* With the prompt's bilingual parenthetical the line IS a heading, and
|
|
83
|
+
* whatever follows is the answer or the prompt's own description. Without
|
|
84
|
+
* it, the text after the label must be a separator — a label followed by
|
|
85
|
+
* prose is a sentence that mentions the label, not a heading.
|
|
86
|
+
*/
|
|
87
|
+
function readLabelTail(rest) {
|
|
88
|
+
let text = rest;
|
|
89
|
+
if (text.startsWith('(') || text.startsWith('(')) {
|
|
90
|
+
const end = findParenEnd(text);
|
|
91
|
+
if (end === -1)
|
|
92
|
+
return { tail: '', isHeading: false };
|
|
93
|
+
text = text.slice(end + 1).trim();
|
|
94
|
+
}
|
|
95
|
+
else if (text !== '' && !isLabelSeparator(text)) {
|
|
96
|
+
return { tail: '', isHeading: false };
|
|
97
|
+
}
|
|
98
|
+
if (text.startsWith(':') || text.startsWith(':'))
|
|
99
|
+
text = text.slice(1).trim();
|
|
100
|
+
if (text.startsWith('—'))
|
|
101
|
+
text = text.slice(1).trim();
|
|
102
|
+
return { tail: text, isHeading: true };
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Recognise a section heading.
|
|
106
|
+
*
|
|
107
|
+
* The heading must be the label itself: the label, then optionally the
|
|
108
|
+
* prompt's bilingual parenthetical, then optionally a colon and the
|
|
109
|
+
* answer. The text that follows the label on the heading line is kept as
|
|
110
|
+
* a FALLBACK, because the prompt prints a DESCRIPTION after every label
|
|
111
|
+
* and a report that answers on the following lines must not be read as
|
|
112
|
+
* the description.
|
|
113
|
+
*/
|
|
114
|
+
function matchHeading(line) {
|
|
115
|
+
const text = stripDecoration(line);
|
|
116
|
+
if (text === '')
|
|
117
|
+
return null;
|
|
118
|
+
const lower = text.toLowerCase();
|
|
119
|
+
for (const { key, marker } of MARKERS) {
|
|
120
|
+
if (!lower.startsWith(marker.toLowerCase()))
|
|
121
|
+
continue;
|
|
122
|
+
const { tail, isHeading } = readLabelTail(text.slice(marker.length).trim());
|
|
123
|
+
if (!isHeading)
|
|
124
|
+
continue;
|
|
125
|
+
return { key, inline: tail };
|
|
126
|
+
}
|
|
127
|
+
return null;
|
|
128
|
+
}
|
|
129
|
+
/** A token that could be a path: no whitespace, and either a separator or an extension. */
|
|
130
|
+
const PATH_TOKEN = /^[A-Za-z0-9_@.\-+/\\]+$/;
|
|
131
|
+
function looksLikePath(token) {
|
|
132
|
+
if (!PATH_TOKEN.test(token))
|
|
133
|
+
return false;
|
|
134
|
+
if (token.includes('/') || token.includes('\\'))
|
|
135
|
+
return true;
|
|
136
|
+
return /\.[A-Za-z0-9]+$/.test(token);
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Pull the file set out of the files section.
|
|
140
|
+
*
|
|
141
|
+
* The section is free text: the paths may be one per line, bulleted, in
|
|
142
|
+
* backticks, or comma-separated on one line. Tokens that cannot be paths
|
|
143
|
+
* (an English word, a stray parenthesis) are dropped, because a guessed
|
|
144
|
+
* file is a wave-planning input that sends two agents to one file.
|
|
145
|
+
*/
|
|
146
|
+
function readFiles(body) {
|
|
147
|
+
const found = [];
|
|
148
|
+
for (const line of body) {
|
|
149
|
+
const cleaned = line
|
|
150
|
+
.trim()
|
|
151
|
+
.replace(/^[-*+]\s+/, '')
|
|
152
|
+
.replace(/`/g, '');
|
|
153
|
+
if (cleaned === '')
|
|
154
|
+
continue;
|
|
155
|
+
for (const token of cleaned.split(/[\s,]+/)) {
|
|
156
|
+
const candidate = token.replace(/[.,;:]+$/, '');
|
|
157
|
+
if (candidate === '' || !looksLikePath(candidate))
|
|
158
|
+
continue;
|
|
159
|
+
found.push(candidate);
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return normalizeFileSet(found);
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Collapse a paragraph to one line.
|
|
166
|
+
*
|
|
167
|
+
* Exported because the summary renders the same fields, and two modules
|
|
168
|
+
* that shape the same text must shape it the same way.
|
|
169
|
+
*/
|
|
170
|
+
export function collapse(text) {
|
|
171
|
+
return text.replace(/\s+/g, ' ').trim();
|
|
172
|
+
}
|
|
173
|
+
/** The first non-empty line of a section, collapsed. */
|
|
174
|
+
function firstLine(text) {
|
|
175
|
+
for (const line of text.split('\n')) {
|
|
176
|
+
const collapsed = collapse(line);
|
|
177
|
+
if (collapsed !== '')
|
|
178
|
+
return collapsed;
|
|
179
|
+
}
|
|
180
|
+
return '';
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Read the finding out of a diagnosis report.
|
|
184
|
+
*
|
|
185
|
+
* @param report - The report the diagnostician produced, verbatim.
|
|
186
|
+
* @returns The finding, or `null` when the report carries no recognised
|
|
187
|
+
* section at all — a report in another shape, which the caller must
|
|
188
|
+
* read rather than summarise.
|
|
189
|
+
*/
|
|
190
|
+
export function parseBatchDiagnosisFinding(report) {
|
|
191
|
+
const lines = report.split('\n');
|
|
192
|
+
const bodies = new Map();
|
|
193
|
+
const inlines = new Map();
|
|
194
|
+
let current = null;
|
|
195
|
+
let sawHeading = false;
|
|
196
|
+
for (const line of lines) {
|
|
197
|
+
const head = matchHeading(line);
|
|
198
|
+
if (head !== null) {
|
|
199
|
+
current = head.key;
|
|
200
|
+
sawHeading = true;
|
|
201
|
+
if (!bodies.has(current))
|
|
202
|
+
bodies.set(current, []);
|
|
203
|
+
if (head.inline !== '')
|
|
204
|
+
inlines.set(current, head.inline);
|
|
205
|
+
continue;
|
|
206
|
+
}
|
|
207
|
+
if (current === null)
|
|
208
|
+
continue;
|
|
209
|
+
bodies.get(current).push(line);
|
|
210
|
+
}
|
|
211
|
+
if (!sawHeading)
|
|
212
|
+
return null;
|
|
213
|
+
// The body wins over the heading line's own text: the prompt prints a
|
|
214
|
+
// DESCRIPTION after every label, and a report that answers on the
|
|
215
|
+
// following lines must not be read as the description.
|
|
216
|
+
const textOf = (key) => {
|
|
217
|
+
const body = (bodies.get(key) ?? []).join('\n').trim();
|
|
218
|
+
if (body !== '')
|
|
219
|
+
return body;
|
|
220
|
+
return inlines.get(key) ?? '';
|
|
221
|
+
};
|
|
222
|
+
return {
|
|
223
|
+
rootCause: collapse(textOf('rootCause')),
|
|
224
|
+
files: readFiles(textOf('files').split('\n')),
|
|
225
|
+
sketch: firstLine(textOf('sketch'))
|
|
226
|
+
};
|
|
227
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/** Which report: the batch, the item, and where the session lives. */
|
|
2
|
+
export interface BatchDiagnosisReportRef {
|
|
3
|
+
readonly projectRoot: string;
|
|
4
|
+
readonly sessionId: string;
|
|
5
|
+
readonly batchId: string;
|
|
6
|
+
readonly itemId: string;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* The directory one batch's diagnosis reports live in.
|
|
10
|
+
*
|
|
11
|
+
* @param projectRoot - Absolute path to the project root.
|
|
12
|
+
* @param sessionId - The session the batch belongs to.
|
|
13
|
+
* @param batchId - The batch's id.
|
|
14
|
+
*/
|
|
15
|
+
export declare function batchDiagnosisReportDir(projectRoot: string, sessionId: string, batchId: string): string;
|
|
16
|
+
/**
|
|
17
|
+
* The report path for one item of one batch.
|
|
18
|
+
*
|
|
19
|
+
* @param ref - Which report: the project, the session, the batch, the item.
|
|
20
|
+
*/
|
|
21
|
+
export declare function batchDiagnosisReportPath(ref: BatchDiagnosisReportRef): string;
|
|
22
|
+
/**
|
|
23
|
+
* Write one item's diagnosis report, atomically.
|
|
24
|
+
*
|
|
25
|
+
* The report is stored verbatim: it is the diagnostician's own words, and
|
|
26
|
+
* the summary is derived from it rather than replacing it.
|
|
27
|
+
*
|
|
28
|
+
* @param ref - Which report: the project, the session, the batch, the item.
|
|
29
|
+
* @param report - The report text, verbatim.
|
|
30
|
+
*/
|
|
31
|
+
export declare function writeBatchDiagnosisReport(ref: BatchDiagnosisReportRef, report: string): void;
|
|
32
|
+
/**
|
|
33
|
+
* Read one item's diagnosis report.
|
|
34
|
+
*
|
|
35
|
+
* @returns The report text, or `null` when the item has no report yet.
|
|
36
|
+
*/
|
|
37
|
+
export declare function readBatchDiagnosisReport(ref: BatchDiagnosisReportRef): string | null;
|
|
38
|
+
/**
|
|
39
|
+
* Read one item's diagnosis report AS THE SUMMARY the window may hold.
|
|
40
|
+
*
|
|
41
|
+
* The summary is derived from the stored report every time it is asked
|
|
42
|
+
* for, so the two can never drift apart: there is no second copy of the
|
|
43
|
+
* file set to fall out of date.
|
|
44
|
+
*
|
|
45
|
+
* @returns The summary, or `null` when there is no report, or when the
|
|
46
|
+
* report carries none of the sections the diagnosis prompt asks for — a
|
|
47
|
+
* report in another shape is read, not summarised.
|
|
48
|
+
*/
|
|
49
|
+
export declare function readBatchDiagnosisSummary(ref: BatchDiagnosisReportRef): string | null;
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
// src/services/batch/batch-diagnosis-report-store.ts
|
|
2
|
+
//
|
|
3
|
+
// The diagnosis report's home on disk, next to the batch record it belongs
|
|
4
|
+
// to.
|
|
5
|
+
//
|
|
6
|
+
// WHY THE REPORT IS A FILE. A batch produces one diagnosis report per
|
|
7
|
+
// item, and the orchestrator's window cannot hold all of them — twenty
|
|
8
|
+
// reports cost ≈60 KB ≈15K tokens, and a batch produces N at once. So the
|
|
9
|
+
// report lands here, under the batch's own directory, and the orchestrator
|
|
10
|
+
// keeps only the bounded summary (see `batch-diagnosis-summary.ts`). The
|
|
11
|
+
// full report is read back on demand, when a phase needs the detail the
|
|
12
|
+
// summary left out.
|
|
13
|
+
//
|
|
14
|
+
// WHERE IT LIVES. `<sessionDir>/batch/<batchId>/diagnosis/<itemId>.md` —
|
|
15
|
+
// beside `progress.json`, one directory per batch, one file per item. The
|
|
16
|
+
// record and the reports are the same fact in two forms: the record says
|
|
17
|
+
// WHICH items are done, the reports say WHY.
|
|
18
|
+
//
|
|
19
|
+
// WHY THE WRITE IS ATOMIC. A reader that sees a half-written report reads
|
|
20
|
+
// it as a report with no sections, and the summary built from it carries
|
|
21
|
+
// no file set — so the topology stage would plan from an empty input
|
|
22
|
+
// rather than from a broken one. The write goes to a temp file in the same
|
|
23
|
+
// directory and is renamed over the target, the same pattern the progress
|
|
24
|
+
// record uses.
|
|
25
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
|
|
26
|
+
import { dirname, join } from 'node:path';
|
|
27
|
+
import { isUnsafePathInput } from '../../shared/path-safety.js';
|
|
28
|
+
import { getSessionDir } from '../session/getSessionDir.js';
|
|
29
|
+
import { parseBatchDiagnosisFinding } from './batch-diagnosis-finding.js';
|
|
30
|
+
import { buildBatchDiagnosisSummary } from './batch-diagnosis-summary.js';
|
|
31
|
+
import { readBatchProgress } from './batch-progress-store.js';
|
|
32
|
+
const BATCH_DIR = 'batch';
|
|
33
|
+
const DIAGNOSIS_DIR = 'diagnosis';
|
|
34
|
+
const REPORT_EXTENSION = '.md';
|
|
35
|
+
/**
|
|
36
|
+
* A path segment the caller supplied, checked before it is joined.
|
|
37
|
+
*
|
|
38
|
+
* `batchId` and `itemId` both become path segments, so `..`, an absolute
|
|
39
|
+
* path, and a nested `a/b` would each write outside the directory the
|
|
40
|
+
* batch owns. The check is the same one the progress record uses.
|
|
41
|
+
*/
|
|
42
|
+
function requireSegment(value, what) {
|
|
43
|
+
if (isUnsafePathInput(value) || value.includes('/') || value.includes('\\')) {
|
|
44
|
+
throw new Error(`Invalid ${what}: ${value} (must be a single safe path segment)`);
|
|
45
|
+
}
|
|
46
|
+
return value;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* The directory one batch's diagnosis reports live in.
|
|
50
|
+
*
|
|
51
|
+
* @param projectRoot - Absolute path to the project root.
|
|
52
|
+
* @param sessionId - The session the batch belongs to.
|
|
53
|
+
* @param batchId - The batch's id.
|
|
54
|
+
*/
|
|
55
|
+
export function batchDiagnosisReportDir(projectRoot, sessionId, batchId) {
|
|
56
|
+
requireSegment(batchId, 'batch id');
|
|
57
|
+
return join(getSessionDir(projectRoot, sessionId), BATCH_DIR, batchId, DIAGNOSIS_DIR);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The report path for one item of one batch.
|
|
61
|
+
*
|
|
62
|
+
* @param ref - Which report: the project, the session, the batch, the item.
|
|
63
|
+
*/
|
|
64
|
+
export function batchDiagnosisReportPath(ref) {
|
|
65
|
+
const safeItemId = requireSegment(ref.itemId, 'item id');
|
|
66
|
+
return join(batchDiagnosisReportDir(ref.projectRoot, ref.sessionId, ref.batchId), `${safeItemId}${REPORT_EXTENSION}`);
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The item's human name, from the batch record.
|
|
70
|
+
*
|
|
71
|
+
* The record is where the item's label lives; the report does not repeat
|
|
72
|
+
* it. When the record has no such item — a report written before the
|
|
73
|
+
* record caught up — the id stands in, so the summary still names the
|
|
74
|
+
* item it is about.
|
|
75
|
+
*/
|
|
76
|
+
function readItemLabel(ref) {
|
|
77
|
+
const progress = readBatchProgress(ref.projectRoot, ref.sessionId, ref.batchId);
|
|
78
|
+
const item = progress?.items.find((entry) => entry.id === ref.itemId);
|
|
79
|
+
return item?.label ?? ref.itemId;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Write one item's diagnosis report, atomically.
|
|
83
|
+
*
|
|
84
|
+
* The report is stored verbatim: it is the diagnostician's own words, and
|
|
85
|
+
* the summary is derived from it rather than replacing it.
|
|
86
|
+
*
|
|
87
|
+
* @param ref - Which report: the project, the session, the batch, the item.
|
|
88
|
+
* @param report - The report text, verbatim.
|
|
89
|
+
*/
|
|
90
|
+
export function writeBatchDiagnosisReport(ref, report) {
|
|
91
|
+
const path = batchDiagnosisReportPath(ref);
|
|
92
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
93
|
+
// Temp file in the same directory, then rename: a write that fails
|
|
94
|
+
// halfway leaves the previous report intact rather than a truncated one.
|
|
95
|
+
const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
|
|
96
|
+
writeFileSync(tmp, report, 'utf8');
|
|
97
|
+
renameSync(tmp, path);
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* Read one item's diagnosis report.
|
|
101
|
+
*
|
|
102
|
+
* @returns The report text, or `null` when the item has no report yet.
|
|
103
|
+
*/
|
|
104
|
+
export function readBatchDiagnosisReport(ref) {
|
|
105
|
+
const path = batchDiagnosisReportPath(ref);
|
|
106
|
+
if (!existsSync(path))
|
|
107
|
+
return null;
|
|
108
|
+
return readFileSync(path, 'utf8');
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Read one item's diagnosis report AS THE SUMMARY the window may hold.
|
|
112
|
+
*
|
|
113
|
+
* The summary is derived from the stored report every time it is asked
|
|
114
|
+
* for, so the two can never drift apart: there is no second copy of the
|
|
115
|
+
* file set to fall out of date.
|
|
116
|
+
*
|
|
117
|
+
* @returns The summary, or `null` when there is no report, or when the
|
|
118
|
+
* report carries none of the sections the diagnosis prompt asks for — a
|
|
119
|
+
* report in another shape is read, not summarised.
|
|
120
|
+
*/
|
|
121
|
+
export function readBatchDiagnosisSummary(ref) {
|
|
122
|
+
const report = readBatchDiagnosisReport(ref);
|
|
123
|
+
if (report === null)
|
|
124
|
+
return null;
|
|
125
|
+
const finding = parseBatchDiagnosisFinding(report);
|
|
126
|
+
if (finding === null)
|
|
127
|
+
return null;
|
|
128
|
+
return buildBatchDiagnosisSummary({
|
|
129
|
+
id: ref.itemId,
|
|
130
|
+
label: readItemLabel(ref),
|
|
131
|
+
finding
|
|
132
|
+
});
|
|
133
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { type BatchDiagnosisFinding } from './batch-diagnosis-finding.js';
|
|
2
|
+
/**
|
|
3
|
+
* The hard ceiling on the summary that may enter the orchestrator's
|
|
4
|
+
* window. The same 2 KB the report cap sets for a sub-agent's own final
|
|
5
|
+
* report: the orchestrator reads N of these, so the cap has to hold per
|
|
6
|
+
* report and the N has to be small.
|
|
7
|
+
*/
|
|
8
|
+
export declare const BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES = 2048;
|
|
9
|
+
/** The summary's input: which item it is about, and what was found. */
|
|
10
|
+
export interface BatchDiagnosisSummaryInput {
|
|
11
|
+
readonly id: string;
|
|
12
|
+
readonly label: string;
|
|
13
|
+
readonly finding: BatchDiagnosisFinding;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Cut a string to a byte budget without splitting a character.
|
|
17
|
+
*
|
|
18
|
+
* A cut that lands inside a multi-byte character produces a replacement
|
|
19
|
+
* character in the summary, which is a fact nobody asked for.
|
|
20
|
+
*/
|
|
21
|
+
export declare function truncateToBytes(text: string, maxBytes: number): string;
|
|
22
|
+
/**
|
|
23
|
+
* Render the summary the orchestrator's window may hold.
|
|
24
|
+
*
|
|
25
|
+
* The shape is three lines under one heading: the conclusion, the file
|
|
26
|
+
* set, and the sketch.
|
|
27
|
+
*
|
|
28
|
+
* @param input - Which item the summary is about, and what was found.
|
|
29
|
+
* @returns A summary of at most {@link BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES} bytes.
|
|
30
|
+
*/
|
|
31
|
+
export declare function buildBatchDiagnosisSummary(input: BatchDiagnosisSummaryInput): string;
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
// src/services/batch/batch-diagnosis-summary.ts
|
|
2
|
+
//
|
|
3
|
+
// The bounded summary of one diagnosis report — the only form of that
|
|
4
|
+
// report the orchestrator's window may hold.
|
|
5
|
+
//
|
|
6
|
+
// WHY THE FULL REPORT MUST NOT ENTER THE WINDOW. Measured in this
|
|
7
|
+
// repository: twenty sub-agent reports cost ≈60 KB ≈15K tokens of the
|
|
8
|
+
// orchestrator's window. A batch produces N diagnosis reports at once, so
|
|
9
|
+
// the batch lane's window is hit by N reports arriving together —
|
|
10
|
+
// exactly the moment the orchestrator has to decide what to do next. So
|
|
11
|
+
// the report lands on disk (see `batch-diagnosis-report-store.ts`) and the
|
|
12
|
+
// window keeps only this summary: the conclusion, the file set, and a
|
|
13
|
+
// one-line sketch.
|
|
14
|
+
//
|
|
15
|
+
// WHY THE FILE SET IS MANDATORY IN THE SUMMARY. The topology stage plans
|
|
16
|
+
// the parallel waves from the MEASURED file sets and from nothing else
|
|
17
|
+
// (`planBatchTopology`). A summary without the file set would force the
|
|
18
|
+
// orchestrator to re-read N full reports to recover the one input it
|
|
19
|
+
// needs — which is the cost this module exists to remove. So the file set
|
|
20
|
+
// is the part of the summary that is never dropped.
|
|
21
|
+
//
|
|
22
|
+
// THE BUDGET IS SPENT IN A FIXED ORDER. The file set first, because it is
|
|
23
|
+
// the input the topology stage needs; the conclusion next; the sketch
|
|
24
|
+
// last, because it is the one the orchestrator can re-read from the full
|
|
25
|
+
// report if it must. What does not fit is cut — and what was cut is said
|
|
26
|
+
// out loud, because a summary that silently drops half a file set is
|
|
27
|
+
// worse than one that says it is partial.
|
|
28
|
+
import { collapse } from './batch-diagnosis-finding.js';
|
|
29
|
+
import { normalizeFileSet } from './batch-progress-store.js';
|
|
30
|
+
/**
|
|
31
|
+
* The hard ceiling on the summary that may enter the orchestrator's
|
|
32
|
+
* window. The same 2 KB the report cap sets for a sub-agent's own final
|
|
33
|
+
* report: the orchestrator reads N of these, so the cap has to hold per
|
|
34
|
+
* report and the N has to be small.
|
|
35
|
+
*/
|
|
36
|
+
export const BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES = 2048;
|
|
37
|
+
/**
|
|
38
|
+
* The ceiling on the conclusion inside the summary.
|
|
39
|
+
*
|
|
40
|
+
* The conclusion is "a sentence or two" by the diagnosis prompt's own
|
|
41
|
+
* wording; the cap keeps a chatty conclusion from eating the budget the
|
|
42
|
+
* file set needs.
|
|
43
|
+
*/
|
|
44
|
+
const CONCLUSION_MAX_BYTES = 512;
|
|
45
|
+
/** The number of lines the summary renders, and so the newlines it costs. */
|
|
46
|
+
const SUMMARY_LINES = 4;
|
|
47
|
+
/** The top bits of a UTF-8 byte: set on every byte of a multi-byte character. */
|
|
48
|
+
const UTF8_LEAD_BITS = 0xc0;
|
|
49
|
+
/** The bit pattern of a UTF-8 continuation byte. */
|
|
50
|
+
const UTF8_CONTINUATION_BIT = 0x80;
|
|
51
|
+
/** The byte length of a string. The cap is a byte cap, not a character cap. */
|
|
52
|
+
function bytes(text) {
|
|
53
|
+
return Buffer.byteLength(text, 'utf8');
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Cut a string to a byte budget without splitting a character.
|
|
57
|
+
*
|
|
58
|
+
* A cut that lands inside a multi-byte character produces a replacement
|
|
59
|
+
* character in the summary, which is a fact nobody asked for.
|
|
60
|
+
*/
|
|
61
|
+
export function truncateToBytes(text, maxBytes) {
|
|
62
|
+
if (maxBytes <= 0)
|
|
63
|
+
return '';
|
|
64
|
+
const buffer = Buffer.from(text, 'utf8');
|
|
65
|
+
if (buffer.length <= maxBytes)
|
|
66
|
+
return text;
|
|
67
|
+
const ellipsis = '…';
|
|
68
|
+
const room = maxBytes - bytes(ellipsis);
|
|
69
|
+
if (room <= 0)
|
|
70
|
+
return '';
|
|
71
|
+
let end = room;
|
|
72
|
+
while (end > 0 && ((buffer[end] ?? 0) & UTF8_LEAD_BITS) === UTF8_CONTINUATION_BIT)
|
|
73
|
+
end -= 1;
|
|
74
|
+
return `${buffer.subarray(0, end).toString('utf8')}${ellipsis}`;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Fit as many paths as the budget allows, and say how many were left out.
|
|
78
|
+
*
|
|
79
|
+
* The file set is mandatory, so it is the last thing to be cut — but a
|
|
80
|
+
* file set of a hundred paths does not fit in 2 KB, and a summary that
|
|
81
|
+
* silently drops half of it is worse than one that says so. The full set
|
|
82
|
+
* stays authoritative on disk.
|
|
83
|
+
*/
|
|
84
|
+
function fitFiles(files, budget) {
|
|
85
|
+
const kept = [];
|
|
86
|
+
for (const file of files) {
|
|
87
|
+
if (bytes([...kept, file].join(', ')) > budget)
|
|
88
|
+
break;
|
|
89
|
+
kept.push(file);
|
|
90
|
+
}
|
|
91
|
+
const omitted = files.length - kept.length;
|
|
92
|
+
if (omitted === 0)
|
|
93
|
+
return kept.join(', ');
|
|
94
|
+
const marker = ` …(+${omitted})`;
|
|
95
|
+
while (kept.length > 0 && bytes(kept.join(', ')) + bytes(marker) > budget)
|
|
96
|
+
kept.pop();
|
|
97
|
+
const room = budget - bytes(kept.join(', '));
|
|
98
|
+
if (room <= 0)
|
|
99
|
+
return kept.join(', ');
|
|
100
|
+
return `${kept.join(', ')}${truncateToBytes(marker, room)}`;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Render the summary the orchestrator's window may hold.
|
|
104
|
+
*
|
|
105
|
+
* The shape is three lines under one heading: the conclusion, the file
|
|
106
|
+
* set, and the sketch.
|
|
107
|
+
*
|
|
108
|
+
* @param input - Which item the summary is about, and what was found.
|
|
109
|
+
* @returns A summary of at most {@link BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES} bytes.
|
|
110
|
+
*/
|
|
111
|
+
export function buildBatchDiagnosisSummary(input) {
|
|
112
|
+
const header = `## ${input.id} · ${input.label}`;
|
|
113
|
+
const files = normalizeFileSet(input.finding.files);
|
|
114
|
+
const conclusion = collapse(input.finding.rootCause);
|
|
115
|
+
const sketch = collapse(input.finding.sketch);
|
|
116
|
+
const overhead = bytes(header) + bytes('结论:') + bytes('文件集:') + bytes('草图:') + SUMMARY_LINES;
|
|
117
|
+
let budget = BATCH_DIAGNOSIS_SUMMARY_MAX_BYTES - overhead;
|
|
118
|
+
let fileText = files.join(', ');
|
|
119
|
+
if (bytes(fileText) > budget) {
|
|
120
|
+
fileText = fitFiles(files, budget);
|
|
121
|
+
}
|
|
122
|
+
budget -= bytes(fileText);
|
|
123
|
+
const conclusionText = bytes(conclusion) > budget
|
|
124
|
+
? truncateToBytes(conclusion, Math.min(budget, CONCLUSION_MAX_BYTES))
|
|
125
|
+
: conclusion;
|
|
126
|
+
budget -= bytes(conclusionText);
|
|
127
|
+
const sketchText = bytes(sketch) > budget ? truncateToBytes(sketch, budget) : sketch;
|
|
128
|
+
return `${header}\n结论:${conclusionText}\n文件集:${fileText}\n草图:${sketchText}\n`;
|
|
129
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { type FileOverlapWavePlan } from '../dispatch/file-overlap-wave-planner.js';
|
|
2
|
+
import type { BatchItem } from './batch-progress-types.js';
|
|
3
|
+
/**
|
|
4
|
+
* The one item a diagnostician is asked about.
|
|
5
|
+
*
|
|
6
|
+
* `symptom` is what the user reported, in the user's words. It is the
|
|
7
|
+
* symptom, not a diagnosis — the agent is the one that has to find the
|
|
8
|
+
* cause.
|
|
9
|
+
*/
|
|
10
|
+
export interface BatchDiagnosisItem {
|
|
11
|
+
readonly id: string;
|
|
12
|
+
readonly label: string;
|
|
13
|
+
readonly symptom: string;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Plan the batch's waves from the file sets its items MEASURED.
|
|
17
|
+
*
|
|
18
|
+
* @param items - The batch's items, each carrying the file set its
|
|
19
|
+
* diagnosis reported.
|
|
20
|
+
* @returns The wave plan: items with disjoint file sets share a wave, and
|
|
21
|
+
* an item that collides with an earlier one is deferred behind it with
|
|
22
|
+
* the colliding file named.
|
|
23
|
+
*/
|
|
24
|
+
export declare function planBatchTopology(items: readonly BatchItem[]): FileOverlapWavePlan;
|
|
25
|
+
/**
|
|
26
|
+
* Build the read-only prompt one diagnostician receives.
|
|
27
|
+
*
|
|
28
|
+
* The prompt asks for exactly the four outputs the batch pipeline
|
|
29
|
+
* consumes — the root cause, the files it expects to change, the risk
|
|
30
|
+
* surface it hit, and a fix sketch — and forbids the three write tools, so
|
|
31
|
+
* the file set it reports is a MEASUREMENT rather than a guess.
|
|
32
|
+
*
|
|
33
|
+
* @param item - The one item to diagnose.
|
|
34
|
+
* @returns The composed prompt, ready to be a sub-agent's dispatch body.
|
|
35
|
+
*/
|
|
36
|
+
export declare function buildDiagnosisPrompt(item: BatchDiagnosisItem): string;
|