flow-comet 1.6.1 → 1.6.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/.flow-comet/skills/flow-comet/GUIDANCE.md +4 -2
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +31 -1
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
- package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +2697 -12
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +55 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +602 -1
- package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +145 -1
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +5 -3
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +153 -27
- package/.flow-comet/skills/flow-comet-change/SKILL.md +11 -1
- package/.flow-comet/skills/flow-comet-design/SKILL.md +4 -2
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
- package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +28 -3
- package/README.md +2 -2
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +2 -2
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// context-scan.mjs — 项目上下文重扫(侧命令 · 显式调用 · 不在 8 节点流程内)
|
|
3
|
+
//
|
|
4
|
+
// 干什么:对一个已接入的项目重跑上下文探测,产出扫描工件(快照 + 与上次基线的差异清单),
|
|
5
|
+
// 并把扫描时刻**双落点**更新——引擎 state 的 last_intel_scan 与 .specs/CONTEXT.md 的
|
|
6
|
+
// `## intel-scan 元数据` 段(与首次接入路径同一字段语义;两处不一致时以 state 为准)。
|
|
7
|
+
//
|
|
8
|
+
// 单一来源:探测 / 判决 / 结构校验 / 补齐指引 / 结构提取一律复用 context-init.mjs 的导出;
|
|
9
|
+
// 时间戳一律走 time-utils.mjs(本地时间 + 显式偏移);state 路径与字段校验走 state-schema.mjs;
|
|
10
|
+
// 「改写前备份」的命名族与失败处置走 state-schema.mjs 的 backupBeforeWrite。
|
|
11
|
+
// 本文件不复制其中任何一份实现——同一判据两份实现必然分叉。
|
|
12
|
+
//
|
|
13
|
+
// 边界:
|
|
14
|
+
// · 不生成也不重写 CONTEXT.md 的内容(生成是 agent 全量阅读的职责);只替换元数据字段那一行的
|
|
15
|
+
// 首个取值词元,行尾说明文字原样保留;改写该行**之前先落备份**(目标同目录 `.bak-<本地日期>`,
|
|
16
|
+
// 经共享助手落盘;复制不成功即整轮 fail-closed——目标文档与 state 都保持原值);
|
|
17
|
+
// · 结构或格式校验不通过时零元数据写入,只输出补齐指引(与首次接入同规则:校验通过才记录扫描时间);
|
|
18
|
+
// · state 在场时字段校验先于两次写入——校验不通过则 CONTEXT 段与 state 都保持原值(不留半写);
|
|
19
|
+
// · 不新建 state 文件——项目没有接入过就没有状态可更新,输出提示即可,不凭空造状态;
|
|
20
|
+
// · 工件落 .specs/context-scan/<日期>-SCAN.md;同日重扫覆盖同名工件(覆盖前的内容即本次基线)。
|
|
21
|
+
//
|
|
22
|
+
// 用法:node context-scan.mjs [--root <项目根>] [--stdout]
|
|
23
|
+
// 退出码 0 = 扫描完成;1 = 未通过(未初始化 / 结构或格式校验不通过 / 元数据未能双落点)。
|
|
24
|
+
|
|
25
|
+
import { promises as fs } from 'fs';
|
|
26
|
+
import path from 'path';
|
|
27
|
+
import { probeProject, classify, validateContext, printGenerationGuide, extractContextStructure } from './context-init.mjs';
|
|
28
|
+
// 参数解析走侧命令共用的单一实现(evolve.mjs 导出):`--root` 两种形态 / `--stdout` / `--help` /
|
|
29
|
+
// 未知参数各只在一处表达,三条横向命令的 CLI 契约因此同形(本文件不再自写一份脚手架)。
|
|
30
|
+
// 同一模块另导出 state 三态读入口(readStateInfo)——本文件的读盘面与 evolve 共用同一条实现。
|
|
31
|
+
import { parseSideCommandArgs, readStateInfo, relativeLabel } from './evolve.mjs';
|
|
32
|
+
import { archiveDateFromName, formatLocalDate, nowTimestamp } from './time-utils.mjs';
|
|
33
|
+
import { RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, backupBeforeWrite, validateStateFields, writeJsonAtomic } from './state-schema.mjs';
|
|
34
|
+
|
|
35
|
+
// 工件目录与命名(横向命令不在 change 生命周期内,落独立的领域目录)
|
|
36
|
+
const SCAN_DIR_SEGMENT = 'context-scan';
|
|
37
|
+
const SCAN_SUFFIX = '-SCAN.md';
|
|
38
|
+
// 机器快照标记:下一次重扫据此取出上一份快照做逐项比对(人读段落不参与比对)
|
|
39
|
+
const SNAPSHOT_MARKER = '<!-- context-scan-snapshot -->';
|
|
40
|
+
// 元数据段与字段(与 context-init 的格式校验同一段名 / 字段名)
|
|
41
|
+
const INTEL_SECTION = 'intel-scan 元数据';
|
|
42
|
+
const INTEL_FIELD = 'last_intel_scan';
|
|
43
|
+
// 字段行形态:`- **last_intel_scan**: <取值词元> <说明…>`——替换只换取值词元,说明原样保留
|
|
44
|
+
const INTEL_FIELD_LINE = new RegExp('^(\\s*-\\s*\\*\\*' + INTEL_FIELD + '\\*\\*\\s*[::]\\s*)(\\S+)([\\s\\S]*)$');
|
|
45
|
+
|
|
46
|
+
function usage() {
|
|
47
|
+
return [
|
|
48
|
+
'用法: node context-scan.mjs [--root <项目根>] [--stdout] [--help]',
|
|
49
|
+
' --root <路径> 项目根(缺省 = 当前目录;`--root=<路径>` 等号形等价)',
|
|
50
|
+
' --stdout 工件正文原样写到标准输出(与落盘内容一致)',
|
|
51
|
+
' --help, -h 打印本用法后退出(不扫描)',
|
|
52
|
+
'说明: 工件落 .specs/context-scan/<日期>-SCAN.md;扫描时刻双落点(引擎 state + CONTEXT 段)。',
|
|
53
|
+
].join('\n');
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
async function readTextFile(file) {
|
|
57
|
+
try { return await fs.readFile(file, 'utf8'); } catch { return ''; }
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
// 读引擎 state:解析失败与文件缺失必须分开——缺失是「项目未接入」(照常出工件),
|
|
61
|
+
// 损坏是「状态不可信」(fail-closed,零元数据写入)。三态判定与 BOM 容忍**不再在本文件内联第二份**:
|
|
62
|
+
// 走 evolve.mjs 导出的 readStateInfo(同一条读入口被两条侧命令共用;第二条实现必然与另一条分叉)。
|
|
63
|
+
|
|
64
|
+
// 基线 = .specs/context-scan/ 下最近一份 `<日期>-SCAN.md`。排序取**文件名日期**(随工件固化),
|
|
65
|
+
// 不取 mtime——检出 / 复制会重写 mtime,据它判时间会得出相反结论。日期前缀的形态与日历
|
|
66
|
+
// 合法性判定复用 time-utils 的同一实现,本文件不另写一份日历校验。
|
|
67
|
+
async function listBaselines(root) {
|
|
68
|
+
const dir = path.join(root, '.specs', SCAN_DIR_SEGMENT);
|
|
69
|
+
let names;
|
|
70
|
+
try { names = await fs.readdir(dir); } catch { return []; }
|
|
71
|
+
return names
|
|
72
|
+
.map((name) => ({ name, date: archiveDateFromName(name) }))
|
|
73
|
+
.filter((entry) => entry.name.endsWith(SCAN_SUFFIX) && entry.date !== null)
|
|
74
|
+
.sort((a, b) => (a.date + a.name).localeCompare(b.date + b.name))
|
|
75
|
+
.map((entry) => ({ ...entry, file: path.join(dir, entry.name) }));
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// 取既有工件的机器快照:无标记 / 解析失败一律返回 null,调用方按「无法比对」显式说明(不静默省略)
|
|
79
|
+
async function readSnapshot(file) {
|
|
80
|
+
const text = await readTextFile(file);
|
|
81
|
+
const at = text.indexOf(SNAPSHOT_MARKER);
|
|
82
|
+
if (at === -1) return null;
|
|
83
|
+
const block = /```json\r?\n([\s\S]*?)\r?\n```/.exec(text.slice(at));
|
|
84
|
+
if (!block) return null;
|
|
85
|
+
try { return JSON.parse(block[1]); } catch { return null; }
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function buildSnapshot({ scannedAt, probe, verdict, validation, structure }) {
|
|
89
|
+
const metadata = {};
|
|
90
|
+
for (const [section, fields] of Object.entries(structure.metadata)) {
|
|
91
|
+
metadata[section] = {};
|
|
92
|
+
for (const [field, entry] of Object.entries(fields)) metadata[section][field] = entry.value;
|
|
93
|
+
}
|
|
94
|
+
return {
|
|
95
|
+
scannedAt,
|
|
96
|
+
verdict,
|
|
97
|
+
probe: {
|
|
98
|
+
hasContext: probe.hasContext,
|
|
99
|
+
hasCodeContext: probe.hasCodeContext,
|
|
100
|
+
aiDocs: [...probe.aiDocs].sort(),
|
|
101
|
+
projectDocs: [...probe.projectDocs].sort(),
|
|
102
|
+
},
|
|
103
|
+
validation: {
|
|
104
|
+
missingSections: [...validation.missingSections].sort(),
|
|
105
|
+
formatIssues: [...validation.formatIssues].sort(),
|
|
106
|
+
},
|
|
107
|
+
context: {
|
|
108
|
+
sections: structure.sections,
|
|
109
|
+
abstractionIndex: structure.abstractionIndex,
|
|
110
|
+
metadata,
|
|
111
|
+
},
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// 差异可比项:维度(kind)+ 条目(key)→ 取值(value)。三态比对只吃这一份数据,
|
|
116
|
+
// 渲染层不再各自判断——同一事实的第二套判定会与快照漂移。
|
|
117
|
+
function comparableItems(snapshot) {
|
|
118
|
+
const items = [];
|
|
119
|
+
const add = (kind, key, value) => { items.push({ kind, key, value: String(value) }); };
|
|
120
|
+
for (const doc of snapshot.probe.aiDocs) add('AI 上下文文档', doc, '在场');
|
|
121
|
+
for (const doc of snapshot.probe.projectDocs) add('项目文档', doc, '在场');
|
|
122
|
+
for (const name of snapshot.context.sections) add('CONTEXT 段', name, '在场');
|
|
123
|
+
for (const [group, entries] of Object.entries(snapshot.context.abstractionIndex)) {
|
|
124
|
+
for (const entry of entries) add('抽象索引条目', group + ' / ' + entry, '在场');
|
|
125
|
+
}
|
|
126
|
+
for (const [section, fields] of Object.entries(snapshot.context.metadata)) {
|
|
127
|
+
for (const [field, value] of Object.entries(fields)) add('元数据字段', section + ' / ' + field, value);
|
|
128
|
+
}
|
|
129
|
+
add('探测标志', 'CONTEXT.md 在场', snapshot.probe.hasContext ? '是' : '否');
|
|
130
|
+
add('探测标志', '代码上下文信号', snapshot.probe.hasCodeContext ? '有' : '无');
|
|
131
|
+
add('判决', '初始化检测判决', snapshot.verdict);
|
|
132
|
+
for (const name of snapshot.validation.missingSections) add('缺段', name, '缺失');
|
|
133
|
+
for (const issue of snapshot.validation.formatIssues) add('格式问题', issue, '存在');
|
|
134
|
+
return items;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function diffItems(before, after) {
|
|
138
|
+
const byId = (items) => new Map(items.map((item) => [item.kind + '|' + item.key, item]));
|
|
139
|
+
const oldItems = byId(before);
|
|
140
|
+
const newItems = byId(after);
|
|
141
|
+
const diff = { added: [], removed: [], changed: [] };
|
|
142
|
+
for (const [id, item] of newItems) {
|
|
143
|
+
const previous = oldItems.get(id);
|
|
144
|
+
if (!previous) diff.added.push(item);
|
|
145
|
+
else if (previous.value !== item.value) diff.changed.push({ ...item, from: previous.value });
|
|
146
|
+
}
|
|
147
|
+
for (const [id, item] of oldItems) {
|
|
148
|
+
if (!newItems.has(id)) diff.removed.push(item);
|
|
149
|
+
}
|
|
150
|
+
return diff;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function renderItemList(items, render) {
|
|
154
|
+
if (items.length === 0) return ['- (无)'];
|
|
155
|
+
return items.map(render);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
function renderSnapshotLines(lines, snapshot) {
|
|
159
|
+
lines.push('## 快照');
|
|
160
|
+
lines.push('');
|
|
161
|
+
lines.push('### 探测(复用初始化检测的探测口径)');
|
|
162
|
+
lines.push('');
|
|
163
|
+
lines.push('- CONTEXT.md 在场: ' + (snapshot.probe.hasContext ? '是' : '否'));
|
|
164
|
+
lines.push('- 代码上下文信号: ' + (snapshot.probe.hasCodeContext ? '有' : '无'));
|
|
165
|
+
lines.push('- AI 上下文文档: ' + (snapshot.probe.aiDocs.length > 0 ? snapshot.probe.aiDocs.join(' / ') : '无'));
|
|
166
|
+
lines.push('- 项目文档: ' + (snapshot.probe.projectDocs.length > 0 ? snapshot.probe.projectDocs.join(' / ') : '无'));
|
|
167
|
+
lines.push('');
|
|
168
|
+
lines.push('### 结构校验');
|
|
169
|
+
lines.push('');
|
|
170
|
+
lines.push('- 段清单: ' + (snapshot.context.sections.length > 0 ? snapshot.context.sections.join(' / ') : '无'));
|
|
171
|
+
lines.push('- 缺段: ' + (snapshot.validation.missingSections.length > 0 ? snapshot.validation.missingSections.join(' / ') : '无'));
|
|
172
|
+
lines.push('- 格式问题: ' + (snapshot.validation.formatIssues.length > 0 ? snapshot.validation.formatIssues.join(' / ') : '无'));
|
|
173
|
+
lines.push('');
|
|
174
|
+
lines.push('### 抽象索引条目');
|
|
175
|
+
lines.push('');
|
|
176
|
+
const groups = Object.entries(snapshot.context.abstractionIndex);
|
|
177
|
+
if (groups.length === 0) {
|
|
178
|
+
lines.push('- (无——CONTEXT.md 没有抽象索引条目)');
|
|
179
|
+
} else {
|
|
180
|
+
for (const [group, entries] of groups) {
|
|
181
|
+
lines.push('- **' + group + '**(' + entries.length + ')');
|
|
182
|
+
// 条目行本身可能是列表项(`- **路径**:…`)——渲染时去掉行首标记,避免出现双破折号
|
|
183
|
+
for (const entry of entries) lines.push(' - ' + entry.replace(/^[-*]\s+/, ''));
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
lines.push('');
|
|
187
|
+
lines.push('### 元数据段字段(本次更新前的取值)');
|
|
188
|
+
lines.push('');
|
|
189
|
+
const metadataSections = Object.entries(snapshot.context.metadata);
|
|
190
|
+
if (metadataSections.length === 0) {
|
|
191
|
+
lines.push('- (无)');
|
|
192
|
+
} else {
|
|
193
|
+
for (const [section, fields] of metadataSections) {
|
|
194
|
+
for (const [field, value] of Object.entries(fields)) lines.push('- `' + section + '` · ' + field + ': ' + value);
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
lines.push('');
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
function renderDiffLines(lines, { root, baseline, baselineSnapshot, diff }) {
|
|
201
|
+
lines.push('## 差异');
|
|
202
|
+
lines.push('');
|
|
203
|
+
if (!baseline) {
|
|
204
|
+
lines.push('> **本次为基线,无差异可比**——`.specs/' + SCAN_DIR_SEGMENT + '/` 下没有可比的既有工件。');
|
|
205
|
+
lines.push('> 本次快照即后续重扫的比对基准。');
|
|
206
|
+
} else if (!baselineSnapshot) {
|
|
207
|
+
lines.push('> 基线 `' + relativeLabel(root, baseline.file) + '`(' + baseline.date + ')**不含可解析的机器快照**——');
|
|
208
|
+
lines.push('> 本次无法逐项比对(不静默省略差异段);本次快照仍落盘,作为下一次重扫的基准。');
|
|
209
|
+
} else {
|
|
210
|
+
const renderItem = (item) => '- ' + item.kind + ' · ' + item.key;
|
|
211
|
+
lines.push('> 基线:`' + relativeLabel(root, baseline.file) + '`(' + baseline.date + ')——逐项比对本次快照与该基线。');
|
|
212
|
+
lines.push('');
|
|
213
|
+
lines.push('### 新增(' + diff.added.length + ')');
|
|
214
|
+
lines.push('');
|
|
215
|
+
lines.push(...renderItemList(diff.added, renderItem));
|
|
216
|
+
lines.push('');
|
|
217
|
+
lines.push('### 消失(' + diff.removed.length + ')');
|
|
218
|
+
lines.push('');
|
|
219
|
+
lines.push(...renderItemList(diff.removed, renderItem));
|
|
220
|
+
lines.push('');
|
|
221
|
+
lines.push('### 变更(' + diff.changed.length + ')');
|
|
222
|
+
lines.push('');
|
|
223
|
+
lines.push(...renderItemList(diff.changed, (item) => renderItem(item) + ': ' + item.from + ' → ' + item.value));
|
|
224
|
+
}
|
|
225
|
+
lines.push('');
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function renderReport({ root, reportFile, snapshot, baseline, baselineSnapshot, diff }) {
|
|
229
|
+
const lines = [];
|
|
230
|
+
lines.push('# 项目上下文重扫报告 · ' + formatLocalDate());
|
|
231
|
+
lines.push('');
|
|
232
|
+
lines.push('- **扫描时刻**: ' + snapshot.scannedAt);
|
|
233
|
+
lines.push('- **扫描根**: ' + root);
|
|
234
|
+
lines.push('- **工件**: `' + relativeLabel(root, reportFile) + '`');
|
|
235
|
+
lines.push('- **初始化检测判决**: ' + snapshot.verdict);
|
|
236
|
+
lines.push('- **元数据更新**: `' + INTEL_FIELD + '` = ' + snapshot.scannedAt + '(引擎 state + `' + INTEL_SECTION + '` 段)');
|
|
237
|
+
lines.push('');
|
|
238
|
+
renderSnapshotLines(lines, snapshot);
|
|
239
|
+
renderDiffLines(lines, { root, baseline, baselineSnapshot, diff });
|
|
240
|
+
lines.push('## 机器快照');
|
|
241
|
+
lines.push('');
|
|
242
|
+
lines.push(SNAPSHOT_MARKER);
|
|
243
|
+
lines.push('```json');
|
|
244
|
+
lines.push(JSON.stringify(snapshot, null, 2));
|
|
245
|
+
lines.push('```');
|
|
246
|
+
lines.push('');
|
|
247
|
+
lines.push('> 本节是下一次重扫的比对输入(逐项快照);上面的差异段由它与基线派生。');
|
|
248
|
+
lines.push('');
|
|
249
|
+
return lines.join('\n');
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
// 只替换元数据字段行的取值词元:段 / 字段由结构提取定位到原文行号,行尾说明文字原样保留。
|
|
253
|
+
// 段不在场或行形态不符 → 不写(fail-closed,由调用方报出原因,不猜不改)。
|
|
254
|
+
// 形态判定先做 `test` 再做替换:拿「替换结果与原行相等」当形态判据会把「同一秒内重扫」
|
|
255
|
+
// (取值未变 → 替换是无变化操作)误判成行形态不符,进而假 BLOCK。
|
|
256
|
+
function replaceContextTimestamp(contextText, structure, value) {
|
|
257
|
+
const field = structure.metadata[INTEL_SECTION] ? structure.metadata[INTEL_SECTION][INTEL_FIELD] : undefined;
|
|
258
|
+
if (!field) return { text: null, reason: '段或缺字段不在场' };
|
|
259
|
+
const lines = contextText.split('\n');
|
|
260
|
+
const line = lines[field.lineIndex];
|
|
261
|
+
if (typeof line !== 'string') return { text: null, reason: '字段行号越界' };
|
|
262
|
+
if (!INTEL_FIELD_LINE.test(line)) {
|
|
263
|
+
return { text: null, reason: '字段行形态不符(取值词元之前须为 `**' + INTEL_FIELD + '**:`)' };
|
|
264
|
+
}
|
|
265
|
+
lines[field.lineIndex] = line.replace(INTEL_FIELD_LINE, (match, prefix, oldValue, suffix) => prefix + value + suffix);
|
|
266
|
+
return { text: lines.join('\n'), reason: null };
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
// 写引擎 state 的扫描时刻:路径与字段校验走 state-schema 的既有导出;写盘走同一原子写导出
|
|
270
|
+
// (目标要么旧内容要么新内容,不出现半写状态;临时文件固定同目录,rename 不跨卷)。
|
|
271
|
+
async function writeStateTimestamp(stateFile, state, value) {
|
|
272
|
+
const bad = validateStateFields({ ...state, [INTEL_FIELD]: value });
|
|
273
|
+
if (bad.length > 0) return { updated: false, reason: '字段校验不通过: ' + bad.join(', ') };
|
|
274
|
+
const next = { ...state };
|
|
275
|
+
next[INTEL_FIELD] = value;
|
|
276
|
+
await writeJsonAtomic(stateFile, next);
|
|
277
|
+
return { updated: true, reason: null };
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
// 双落点更新扫描时刻:CONTEXT 段在前、state 在后——段写不进去就绝不动 state(避免半边更新)。
|
|
281
|
+
// 改写 CONTEXT.md 前的备份走 state-schema.mjs 的共享助手(单一来源:同目录 `.bak-<本地日期>`
|
|
282
|
+
// 命名族、内容 = 改写前版本、复制失败即抛出 → 整轮 fail-closed);本模块不自持第二份命名族或
|
|
283
|
+
// 复制调用。同日重复改写同名覆盖(不堆积);取值未变(同一秒内重扫)时既不改写也不落备份——
|
|
284
|
+
// 无变化就没有可备份的「改写前版本」。
|
|
285
|
+
async function updateScanTimestamp({ root, contextFile, contextText, structure, stateInfo, stateFile, scannedAt }) {
|
|
286
|
+
const contextUpdate = replaceContextTimestamp(contextText, structure, scannedAt);
|
|
287
|
+
if (contextUpdate.text === null) {
|
|
288
|
+
return { ok: false, reason: 'CONTEXT.md 的 `' + INTEL_SECTION + '` 段未更新(' + contextUpdate.reason + ')——state 保持原值,两处仍一致。' };
|
|
289
|
+
}
|
|
290
|
+
// state 在场时**先**校验本次要写入的字段(判据 = 写闸门用的同一个 validateStateFields 导出):
|
|
291
|
+
// 校验不通过即两处都不动。判据的输入在两次写入之前就齐了——先改文档会把双落点拆成两半
|
|
292
|
+
// (段侧已指向新扫描时刻、state 侧被拒,段侧那个时刻引擎根本不认,而 state 才是权威侧)。
|
|
293
|
+
if (stateInfo.exists) {
|
|
294
|
+
const bad = validateStateFields({ ...stateInfo.state, [INTEL_FIELD]: scannedAt });
|
|
295
|
+
if (bad.length > 0) {
|
|
296
|
+
return { ok: false, reason: '引擎 state 字段校验不通过(' + bad.join(', ') + ')——两处均未改写;先修状态再重跑。' };
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
if (contextUpdate.text !== contextText) {
|
|
300
|
+
await backupBeforeWrite(contextFile, scannedAt);
|
|
301
|
+
await fs.writeFile(contextFile, contextUpdate.text, 'utf8');
|
|
302
|
+
}
|
|
303
|
+
if (!stateInfo.exists) {
|
|
304
|
+
console.log('CONTEXT-SCAN: state 未找到(' + relativeLabel(root, stateFile) + ')——项目未接入过,本次只更新 CONTEXT 段。');
|
|
305
|
+
return { ok: true, stateUpdated: false };
|
|
306
|
+
}
|
|
307
|
+
const stateUpdate = await writeStateTimestamp(stateFile, stateInfo.state, scannedAt);
|
|
308
|
+
if (!stateUpdate.updated) {
|
|
309
|
+
return { ok: false, reason: '引擎 state 未更新(' + stateUpdate.reason + ')——CONTEXT 段已更新,两处暂时不一致;先修状态再重跑。' };
|
|
310
|
+
}
|
|
311
|
+
return { ok: true, stateUpdated: true };
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
// 结果摘要(前缀行供机检检索;--stdout 时先原样输出工件正文,便于消费方一次取全)
|
|
315
|
+
function printResult({ stdout, root, reportText, reportFile, baseline, baselineSnapshot, diff, scannedAt, stateUpdated }) {
|
|
316
|
+
const output = [];
|
|
317
|
+
if (stdout) output.push(reportText, '');
|
|
318
|
+
output.push('CONTEXT-SCAN: 报告 `' + relativeLabel(root, reportFile) + '`');
|
|
319
|
+
output.push('CONTEXT-SCAN: 基线 ' + (baseline
|
|
320
|
+
? '`' + relativeLabel(root, baseline.file) + '`(' + baseline.date + ')'
|
|
321
|
+
: '无(本次为基线,无差异可比)'));
|
|
322
|
+
if (!baseline) output.push('CONTEXT-SCAN: 差异 无(本次为基线,无差异可比)');
|
|
323
|
+
else if (!baselineSnapshot) output.push('CONTEXT-SCAN: 差异 无(既有基线不含机器快照,无法比对)');
|
|
324
|
+
else output.push('CONTEXT-SCAN: 差异 新增 ' + diff.added.length + ' / 消失 ' + diff.removed.length + ' / 变更 ' + diff.changed.length);
|
|
325
|
+
output.push('CONTEXT-SCAN: ' + INTEL_FIELD + ' = ' + scannedAt
|
|
326
|
+
+ (stateUpdated ? '(引擎 state + CONTEXT 段)' : '(仅 CONTEXT 段)'));
|
|
327
|
+
output.push('CONTEXT-SCAN-DONE');
|
|
328
|
+
console.log(output.join('\n'));
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
// 前置门(两条,均零元数据写入):
|
|
332
|
+
// ① 结构 / 格式校验不通过 → 输出补齐指引(复用首次接入的同一指引)后 BLOCK;
|
|
333
|
+
// ② 状态文件在场但解析失败 → 状态不可信,先修状态再扫。
|
|
334
|
+
// 返回 false = 已 BLOCK(原因已输出),调用方直接退出。
|
|
335
|
+
async function preflight({ root, probe, validation, contextText, stateInfo, stateFile }) {
|
|
336
|
+
if (validation.missingSections.length > 0 || validation.formatIssues.length > 0) {
|
|
337
|
+
const problems = [...validation.formatIssues, ...validation.missingSections.map((name) => '缺段 ' + name)];
|
|
338
|
+
if (contextText === '') await printGenerationGuide(root, probe);
|
|
339
|
+
else await printGenerationGuide(root, probe, { rewrite: true, problems });
|
|
340
|
+
console.error('BLOCKED: CONTEXT.md 未通过结构校验——本次不写扫描时间;按上面的指引补齐后重跑 context-scan。');
|
|
341
|
+
return false;
|
|
342
|
+
}
|
|
343
|
+
if (stateInfo.exists && stateInfo.state === null) {
|
|
344
|
+
console.error('BLOCKED: 引擎状态文件无法解析(' + relativeLabel(root, stateFile) + ')——本次零写入,先修复状态再重跑。');
|
|
345
|
+
return false;
|
|
346
|
+
}
|
|
347
|
+
return true;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
async function main() {
|
|
351
|
+
const options = parseSideCommandArgs(process.argv.slice(2), { usage: usage() });
|
|
352
|
+
if (options.help) { console.log(usage()); return 0; }
|
|
353
|
+
const root = options.root;
|
|
354
|
+
const contextFile = path.join(root, '.specs', 'CONTEXT.md');
|
|
355
|
+
const stateFile = path.join(root, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME);
|
|
356
|
+
const scannedAt = nowTimestamp();
|
|
357
|
+
|
|
358
|
+
// ① 探测 / 判决 / 结构校验 / 结构提取——一律复用 context-init 的导出(本文件不另写一套)
|
|
359
|
+
const stateInfo = await readStateInfo(root);
|
|
360
|
+
const probe = await probeProject(root, stateInfo.state);
|
|
361
|
+
const verdict = classify(probe, stateInfo.state);
|
|
362
|
+
const validation = await validateContext(root);
|
|
363
|
+
const contextText = await readTextFile(contextFile);
|
|
364
|
+
const structure = extractContextStructure(contextText);
|
|
365
|
+
if (!await preflight({ root, probe, validation, contextText, stateInfo, stateFile })) return 1;
|
|
366
|
+
|
|
367
|
+
// ② 快照与差异:基线 = 最近一份既有工件(同日重扫覆盖同名文件,覆盖前的内容即基线)
|
|
368
|
+
const snapshot = buildSnapshot({ scannedAt, probe, verdict, validation, structure });
|
|
369
|
+
const baselines = await listBaselines(root);
|
|
370
|
+
const baseline = baselines.length > 0 ? baselines[baselines.length - 1] : null;
|
|
371
|
+
const baselineSnapshot = baseline ? await readSnapshot(baseline.file) : null;
|
|
372
|
+
const diff = baselineSnapshot ? diffItems(comparableItems(baselineSnapshot), comparableItems(snapshot)) : null;
|
|
373
|
+
|
|
374
|
+
// ③ 双落点更新扫描时刻(失败即 BLOCK,零工件落盘——不谎称两处都写了)
|
|
375
|
+
const update = await updateScanTimestamp({ root, contextFile, contextText, structure, stateInfo, stateFile, scannedAt });
|
|
376
|
+
if (!update.ok) {
|
|
377
|
+
console.error('BLOCKED: ' + update.reason);
|
|
378
|
+
return 1;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
// ④ 工件落盘(基线只在元数据写成功后才前进;同日重扫覆盖同名文件,覆盖前的内容即本次基线)
|
|
382
|
+
const reportFile = path.join(root, '.specs', SCAN_DIR_SEGMENT, formatLocalDate() + SCAN_SUFFIX);
|
|
383
|
+
const reportText = renderReport({ root, reportFile, snapshot, baseline, baselineSnapshot, diff });
|
|
384
|
+
await fs.mkdir(path.dirname(reportFile), { recursive: true });
|
|
385
|
+
await fs.writeFile(reportFile, reportText, 'utf8');
|
|
386
|
+
|
|
387
|
+
printResult({ stdout: options.stdout, root, reportText, reportFile, baseline, baselineSnapshot, diff, scannedAt, stateUpdated: update.stateUpdated });
|
|
388
|
+
return 0;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
main()
|
|
392
|
+
.then((code) => { process.exitCode = code; })
|
|
393
|
+
.catch((error) => {
|
|
394
|
+
console.error('BLOCKED: ' + (error && error.message ? error.message : String(error)));
|
|
395
|
+
process.exitCode = 1;
|
|
396
|
+
});
|