dsh-stm32 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +256 -363
  2. package/README_EN.md +257 -357
  3. package/client/client.js +4340 -1
  4. package/docs/reading-guide.md +62 -0
  5. package/lib/client.js +4340 -1
  6. package/lib/engine/artifacts.js +123 -0
  7. package/lib/engine/breakpoint-hits.js +73 -0
  8. package/lib/engine/build.js +73 -3
  9. package/lib/engine/channel-tap.js +227 -0
  10. package/lib/engine/channels.js +48 -0
  11. package/lib/engine/clocks.js +192 -0
  12. package/lib/engine/debug-session.js +46 -1
  13. package/lib/engine/event-bus.js +158 -0
  14. package/lib/engine/event-log.js +335 -0
  15. package/lib/engine/fault-hints.js +146 -0
  16. package/lib/engine/interrupts.js +247 -0
  17. package/lib/engine/ioc-diff.js +369 -0
  18. package/lib/engine/ioc-sync.js +58 -0
  19. package/lib/engine/msys2-install.js +31 -6
  20. package/lib/engine/panel-actions.js +103 -0
  21. package/lib/engine/pinout.js +140 -0
  22. package/lib/engine/probe-info.js +95 -0
  23. package/lib/engine/progress.js +99 -0
  24. package/lib/engine/project-conf.js +199 -0
  25. package/lib/engine/session-context.js +19 -0
  26. package/lib/engine/source-slice.js +59 -0
  27. package/lib/engine/tool-events.js +119 -0
  28. package/lib/engine/watch-admin.js +101 -0
  29. package/lib/engine/watch-record.js +39 -0
  30. package/lib/engine/watch-recorder.js +116 -0
  31. package/lib/engine/web-api.js +886 -4
  32. package/lib/engine/web-routes.js +18 -1
  33. package/lib/engine/workspace-memo.js +41 -0
  34. package/lib/index.js +67 -24
  35. package/lib/tools/ioc-apply.js +9 -0
  36. package/lib/tools/project-create.js +28 -0
  37. package/lib/tools/project-dir.js +7 -1
  38. package/lib/tools/rtt.js +8 -0
  39. package/lib/tools/serial.js +22 -0
  40. package/lib/tools/watch.js +24 -2
  41. package/package.json +1 -1
@@ -0,0 +1,192 @@
1
+ /**
2
+ * 时钟树:从 .ioc 的 `RCC.*` 键读出各路时钟频率与分频,供调试台的时钟页显示。
3
+ *
4
+ * 与 `src/data/clock-db.ts` 的分工:那个模块按芯片算「目标频率该怎么配 PLL」,
5
+ * 是写 .ioc 之前的规划;这里只读已经写进 .ioc 的结果,不推导、不修改。
6
+ * 频率一律取 CubeMX 自己写下的 `*Freq_Value` 键——插件复算容易与 CubeMX 的取整口径不一致。
7
+ */
8
+ import { readFileSync } from "node:fs";
9
+ import { BUS_LIMITS } from "../data/clock-db.js";
10
+ import { parseIocEntries } from "./ioc.js";
11
+ import { findIocPath } from "./pinout.js";
12
+ const NODE_SPECS = [
13
+ { label: "SYSCLK", key: "RCC.SYSCLKFreq_VALUE" },
14
+ { label: "HCLK / AHB", key: "RCC.AHBFreq_Value" },
15
+ { label: "PCLK1 / APB1", key: "RCC.APB1Freq_Value", dividerKey: "RCC.APB1CLKDivider" },
16
+ { label: "PCLK2 / APB2", key: "RCC.APB2Freq_Value", dividerKey: "RCC.APB2CLKDivider" },
17
+ { label: "TIM (APB1)", key: "RCC.APB1TimFreq_Value" },
18
+ { label: "TIM (APB2)", key: "RCC.APB2TimFreq_Value" },
19
+ { label: "Cortex 内核", key: "RCC.FCLKCortexFreq_Value" },
20
+ { label: "ADC", key: "RCC.ADCFreqValue" },
21
+ { label: "USB", key: "RCC.USBFreq_Value" },
22
+ { label: "SysTick", key: "RCC.TimSysFreq_Value" },
23
+ { label: "MCO", key: "RCC.MCOFreq_Value" },
24
+ ];
25
+ /**
26
+ * 型号 → 总线上限表的键(S66),例如 STM32F103C8T6 → STM32F1、STM32G431CBT6 → STM32G4。
27
+ * 表里没有的族返回空串;此时不做上限判断,而不是猜一个值。
28
+ */
29
+ export function familyOfCpn(cpn) {
30
+ const match = /^STM32([A-Z])(\d)/u.exec(cpn.trim().toUpperCase());
31
+ if (match === null || match[1] === undefined || match[2] === undefined)
32
+ return "";
33
+ const family = "STM32" + match[1] + match[2];
34
+ return BUS_LIMITS[family] === undefined ? "" : family;
35
+ }
36
+ /** 节点 → 该族总线上限;只有真正受手册约束的三路给出上限。 */
37
+ export function limitForNode(label, limits) {
38
+ if (limits === null)
39
+ return null;
40
+ if (label === "PCLK1 / APB1")
41
+ return limits.apb1Hz;
42
+ if (label === "PCLK2 / APB2")
43
+ return limits.apb2Hz;
44
+ if (label === "ADC")
45
+ return limits.adcHz;
46
+ return null;
47
+ }
48
+ /** 各总线允许的分频档;F1 的 APB 分频与 ADC 预分频不是同一组。 */
49
+ const APB_DIVISORS = [2, 4, 8, 16];
50
+ const ADC_DIVISORS = [2, 4, 6, 8];
51
+ /**
52
+ * 超限修法(S71):算出「最小够用的分频档」,让人不必自己除。
53
+ *
54
+ * 只给分频建议,不写 .ioc——改配置仍走 stm32_ioc_plan,那里会重算全部派生键。
55
+ */
56
+ export function suggestFix(label, hz, limitHz, baseHz = null) {
57
+ if (hz === null || limitHz === null || hz <= limitHz)
58
+ return "";
59
+ const isAdc = label === "ADC";
60
+ const isApb = label === "PCLK1 / APB1" || label === "PCLK2 / APB2";
61
+ if (!isAdc && !isApb)
62
+ return "";
63
+ const divisors = isAdc ? ADC_DIVISORS : APB_DIVISORS;
64
+ // 分频器挂在父时钟上:ADC 预分频除 PCLK2、APB 分频除 HCLK。
65
+ // 直接拿「当前频率 ÷ 分频」会把 36/4=9 这种不存在的档位说给人听。
66
+ const source = baseHz !== null && baseHz > 0 ? baseHz : hz;
67
+ const knob = isAdc ? "ADC 预分频" : label === "PCLK1 / APB1" ? "APB1 分频" : "APB2 分频";
68
+ for (const divisor of divisors) {
69
+ const next = source / divisor;
70
+ if (next <= limitHz) {
71
+ const mhz = (next / 1_000_000).toFixed(1).replace(/\.0$/u, "");
72
+ return "把 " + knob + "改成 ÷" + String(divisor) + "(" + mhz + " MHz)";
73
+ }
74
+ }
75
+ return "现有分频档都不够,需要降低源频率";
76
+ }
77
+ /** `.ioc` 的频率值是十进制整数;带小数的写法一律视为没有。 */
78
+ export function parseHz(raw) {
79
+ if (raw === undefined)
80
+ return null;
81
+ const text = raw.trim();
82
+ if (!/^\d+$/u.test(text))
83
+ return null;
84
+ const value = Number(text);
85
+ return Number.isSafeInteger(value) ? value : null;
86
+ }
87
+ /** `RCC_HCLK_DIV2` → `÷2`;`RCC_SYSCLK_DIV1` → `÷1`。认不出就原样返回。 */
88
+ export function dividerLabel(raw) {
89
+ const match = /_DIV(\d+)$/u.exec(raw.trim());
90
+ return match === null || match[1] === undefined ? raw : "÷" + match[1];
91
+ }
92
+ const SYSCLK_SOURCES = {
93
+ RCC_SYSCLKSOURCE_HSI: "HSI",
94
+ RCC_SYSCLKSOURCE_HSE: "HSE",
95
+ RCC_SYSCLKSOURCE_PLLCLK: "PLL",
96
+ RCC_SYSCLKSOURCE_PLLRCLK: "PLLR",
97
+ RCC_SYSCLKSOURCE_MSI: "MSI",
98
+ RCC_SYSCLKSOURCE_HSI48: "HSI48",
99
+ };
100
+ const PLL_SOURCES = {
101
+ RCC_PLLSOURCE_HSI: "HSI",
102
+ RCC_PLLSOURCE_HSE: "HSE",
103
+ RCC_PLLSOURCE_HSI_DIV2: "HSI/2",
104
+ RCC_PLLSOURCE_MSI: "MSI",
105
+ };
106
+ /** `RCC_PLL_MUL9` → `×9`。 */
107
+ export function mulLabel(raw) {
108
+ const match = /_MUL(\d+)$/u.exec(raw.trim());
109
+ return match === null || match[1] === undefined ? raw : "×" + match[1];
110
+ }
111
+ export function readClockTree(projectDir) {
112
+ const dir = projectDir.trim();
113
+ if (dir === "")
114
+ return { ok: false, error: "projectDir 不能为空" };
115
+ const iocPath = findIocPath(dir);
116
+ if (iocPath === "")
117
+ return { ok: false, error: "工程目录里没有可读的 .ioc:" + dir };
118
+ let entries;
119
+ try {
120
+ entries = parseIocEntries(readFileSync(iocPath, "utf8"));
121
+ }
122
+ catch (error) {
123
+ const message = error instanceof Error ? error.message : String(error);
124
+ return { ok: false, error: "读取 .ioc 失败:" + message };
125
+ }
126
+ const used = new Set();
127
+ const cpn = entries.get("Mcu.CPN") ?? "";
128
+ const hclkHz = parseHz(entries.get("RCC.AHBFreq_Value"));
129
+ // .ioc 里没有 ADC 外设时,ADCFreqValue 只是 CubeMX 顺手算出的派生键,不是真在用的时钟。
130
+ const adcUsed = [...entries.values()].some((value) => /^ADC\d/u.test(value.trim()));
131
+ const apb2Hz = parseHz(entries.get("RCC.APB2Freq_Value"));
132
+ const family = familyOfCpn(cpn);
133
+ const limits = family === "" ? null : (BUS_LIMITS[family] ?? null);
134
+ const nodes = NODE_SPECS.map((spec) => {
135
+ used.add(spec.key);
136
+ if (spec.dividerKey !== undefined)
137
+ used.add(spec.dividerKey);
138
+ const divider = spec.dividerKey === undefined ? "" : dividerLabel(entries.get(spec.dividerKey) ?? "");
139
+ const hz = parseHz(entries.get(spec.key));
140
+ const limitHz = limitForNode(spec.label, limits);
141
+ const overLimit = hz !== null && limitHz !== null && hz > limitHz;
142
+ const baseHz = spec.label === "ADC" ? apb2Hz : spec.label.startsWith("PCLK") ? hclkHz : null;
143
+ return {
144
+ label: spec.label,
145
+ hz,
146
+ key: spec.key,
147
+ divider,
148
+ limitHz,
149
+ overLimit,
150
+ suggest: (() => {
151
+ if (!overLimit)
152
+ return "";
153
+ const fix = suggestFix(spec.label, hz, limitHz, baseHz);
154
+ if (fix === "")
155
+ return "";
156
+ return spec.label === "ADC" && !adcUsed ? "工程没有启用 ADC,这条不影响运行;启用时" + fix : fix;
157
+ })(),
158
+ };
159
+ });
160
+ const others = [];
161
+ for (const [key, value] of entries) {
162
+ if (!key.startsWith("RCC.") || !/Freq/iu.test(key) || used.has(key))
163
+ continue;
164
+ const hz = parseHz(value);
165
+ if (hz === null)
166
+ continue;
167
+ others.push({ label: key.slice("RCC.".length), hz, key, divider: "", limitHz: null, overLimit: false, suggest: "" });
168
+ }
169
+ others.sort((left, right) => left.key.localeCompare(right.key, "en"));
170
+ const source = entries.get("RCC.SYSCLKSource") ?? "";
171
+ const pllSource = entries.get("RCC.PLLSourceVirtual") ?? entries.get("RCC.PLLSource") ?? "";
172
+ const pllMul = entries.get("RCC.PLLMUL") ?? entries.get("RCC.PLLMultiplier") ?? "";
173
+ return {
174
+ ok: true,
175
+ report: {
176
+ projectDir: dir,
177
+ iocPath,
178
+ cpn,
179
+ sysclkSource: source,
180
+ sysclkSourceLabel: SYSCLK_SOURCES[source] ?? source,
181
+ pll: {
182
+ source: pllSource,
183
+ sourceLabel: PLL_SOURCES[pllSource] ?? pllSource,
184
+ mul: pllMul,
185
+ mulLabel: mulLabel(pllMul),
186
+ },
187
+ nodes,
188
+ others,
189
+ limits: limits === null ? null : { family, apb1Hz: limits.apb1Hz, apb2Hz: limits.apb2Hz, adcHz: limits.adcHz },
190
+ },
191
+ };
192
+ }
@@ -14,6 +14,7 @@ import { existsSync } from "node:fs";
14
14
  import net from "node:net";
15
15
  import { resolveSearchConfig } from "../data/search-roots.js";
16
16
  import { F1_BREAKPOINT_BUDGET, collectBreakpointRequests, planBreakpoints, quotaOf, resolveBreakpointBudget } from "./breakpoints.js";
17
+ import { HitHistory } from "./breakpoint-hits.js";
17
18
  import { isPortBusy, pickPort, resolveElfPath } from "./debug.js";
18
19
  import { MiSession, formatStopLocation, steppingCommandFor } from "./gdb-mi.js";
19
20
  import { WATCH_KIND_LABELS, formatWatchDelta, formatWatchSampleNote, hardwareWatchpoints, isHardwareWatchpoint, markWatchpointsStale, normalizeWatchExpression, parseWatchMarkers, parseWatchpointNumber, recordWatchSample, registerWatch, removeWatchByIds, resetWatchState, sampledWatches, watchState, } from "./watch.js";
@@ -23,6 +24,10 @@ import { liveProbeChoice, openocdTransportArgs } from "./doctor.js";
23
24
  import { resolveToolIn } from "./probe.js";
24
25
  import { runCapture } from "./subprocess-runner.js";
25
26
  import { waitForListening } from "./debug.js";
27
+ /** 轨迹保留条数;面板只要最近几次。 */
28
+ const TRACE_LIMIT = 20;
29
+ /** 单条轨迹保留的输出字符数(从尾部截)。 */
30
+ const TRACE_TEXT_LIMIT = 2000;
26
31
  const DEFAULT_IDLE_TTL_MS = 90_000;
27
32
  const DEFAULT_HARD_TTL_MS = 10 * 60_000;
28
33
  const SWEEP_MS = 5_000;
@@ -133,6 +138,10 @@ export class DebugSessionManager {
133
138
  aliveProbe = (port) => isPortBusy(port, 500);
134
139
  current = null;
135
140
  timer = null;
141
+ /** 断点与观察点的命中历史:跨 eval 保留,关会话时清空。 */
142
+ hits = new HitHistory();
143
+ /** 最近几次 eval 的命令与输出尾部:面板展示原始 gdb 输出用,关会话时清空。 */
144
+ traces = [];
136
145
  now;
137
146
  constructor(options = {}) {
138
147
  this.now = options.now ?? (() => Date.now());
@@ -151,11 +160,30 @@ export class DebugSessionManager {
151
160
  setAliveProbe(probe) {
152
161
  this.aliveProbe = probe;
153
162
  }
163
+ /** 本次会话的命中历史,最新在后。 */
164
+ hitHistory() {
165
+ return this.hits.list();
166
+ }
167
+ /** 最近几次 eval 的命令与输出,最新在后。 */
168
+ recentTraces(limit = 5) {
169
+ const count = Math.max(1, Math.min(Math.floor(limit), TRACE_LIMIT));
170
+ return this.traces.slice(-count);
171
+ }
172
+ /** 记一条 eval 轨迹:输出只留尾部,避免面板被长 log 拖住。 */
173
+ rememberTrace(command, ok, output) {
174
+ const text = output.length > TRACE_TEXT_LIMIT ? output.slice(output.length - TRACE_TEXT_LIMIT) : output;
175
+ this.traces.push({ at: this.now(), command: command, ok: ok, output: text });
176
+ while (this.traces.length > TRACE_LIMIT)
177
+ this.traces.shift();
178
+ }
154
179
  isActive() {
155
180
  return this.current !== null;
156
181
  }
157
182
  /**
158
- * 续租:会话刚被用过一次(B3 的 regs 快路径每读一次都算"用过")。
183
+ * 续租:把空闲计时器归零,总时长上限不动。
184
+ *
185
+ * 调用方有两处:regs 快路径每读一次都算"用过";面板「续期」按钮重置空闲计时
186
+ * (盯日志十几分钟不该因为没敲命令被关掉,但也不能让轮询无限延长一次调试)。
159
187
  * 返回是否真的有会话被续租。
160
188
  */
161
189
  touch() {
@@ -184,6 +212,13 @@ export class DebugSessionManager {
184
212
  const hardDeadline = session.startedAt + session.hardTtlMs;
185
213
  return Math.max(0, Math.min(idleDeadline, hardDeadline) - this.now());
186
214
  }
215
+ /** 单测用:丢掉内存里的会话记录(不关进程、不碰探针)。 */
216
+ resetForTest() {
217
+ this.current = null;
218
+ this.stopSweeper();
219
+ this.hits.clear();
220
+ this.traces.length = 0;
221
+ }
187
222
  /** 扫一次租约:过期的会话立刻关。定时器与单测共用这一条路径。 */
188
223
  async sweepExpired() {
189
224
  const session = this.current;
@@ -468,6 +503,8 @@ export class DebugSessionManager {
468
503
  if (!miStillActive)
469
504
  miErrors.push("会话在本次 eval 期间已关闭");
470
505
  const miOutput = lines.join("\n").trim();
506
+ this.hits.record(miOutput, this.now());
507
+ this.rememberTrace(commandLine, miErrors.length === 0, miOutput);
471
508
  return {
472
509
  ok: miErrors.length === 0,
473
510
  output: miOutput,
@@ -498,6 +535,8 @@ export class DebugSessionManager {
498
535
  });
499
536
  session.lastUsedAt = this.now();
500
537
  const output = (outcome.stdout + "\n" + outcome.stderr).trim();
538
+ this.hits.record(output, this.now());
539
+ this.rememberTrace(commands.join(" ;; "), outcome.exitCode === 0 && !outcome.timedOut, output);
501
540
  const errors = [];
502
541
  if (outcome.spawnError !== null)
503
542
  errors.push("gdb 启动失败:" + outcome.spawnError);
@@ -889,6 +928,8 @@ export class DebugSessionManager {
889
928
  }
890
929
  this.current = null;
891
930
  this.stopSweeper();
931
+ this.hits.clear();
932
+ this.traces.length = 0;
892
933
  // 观察点住在 gdb 进程里:会话一关就全没了,登记表必须跟着清,
893
934
  // 否则下次会话里 action=list 会报一堆已经不存在的观察点。
894
935
  resetWatchState();
@@ -936,6 +977,10 @@ export class DebugSessionManager {
936
977
  }
937
978
  /** 进程内单例:工具、turn/end 监听、dispose 共用同一个会话。 */
938
979
  export const debugSessions = new DebugSessionManager();
980
+ /** 单测用:清空当前会话摘要,避免用例之间互相影响。 */
981
+ export function resetDebugSessionsForTest() {
982
+ debugSessions.resetForTest();
983
+ }
939
984
  /** 通过 Tcl 口让 openocd 自行 shutdown(探针能收到正常的断开序列)。失败时交由 kill 回退处理。 */
940
985
  function requestOpenocdShutdown(port, timeoutMs) {
941
986
  if (!Number.isFinite(port) || port <= 0)
@@ -0,0 +1,158 @@
1
+ /**
2
+ * 调试台的事件总线:把工具调用、面板操作与设备副作用收敛成一条带序号的流。
3
+ *
4
+ * 设计取舍:
5
+ * - 单一事实源。时间线、SSE 推流、证据目录都读这一份事件,面板不各自记账,
6
+ * 所以「模型做了什么」与「用户看到什么」不会分叉。
7
+ * - 只保留最近 5000 条(环形)。RTT 与串口已按窗口汇总,剩下的条目量级在千级,
8
+ * 5000 条足够回看一整轮联调,内存占用保持在兆级以内。
9
+ * - 被挤出的条目不是直接丢弃,而是交给 event-log.ts 定期落盘(默认 30 秒一批),
10
+ * 于是「内存里只留近期」与「证据目录里的完整记录」同时成立。
11
+ *
12
+ * 本模块是纯内存实现:不碰文件系统、不碰定时器,可在单测里直接驱动。
13
+ */
14
+ /** 内存里保留的事件条数。 */
15
+ export const EVENT_RING_LIMIT = 5000;
16
+ /** 单条事件 payload 的序列化上限(字节)。超出时保留预览并标记截断。 */
17
+ export const EVENT_PAYLOAD_LIMIT = 8192;
18
+ /** 等待落盘的挤出条目上限;落盘通道卡住时丢弃最旧的,并留一条缺口事件。 */
19
+ export const EVENT_PENDING_LIMIT = 2000;
20
+ const ring = [];
21
+ let pending = [];
22
+ let pendingDropped = 0;
23
+ let nextSeq = 1;
24
+ let sessionKey = "";
25
+ const listeners = new Set();
26
+ function trimmedPayload(payload) {
27
+ if (payload === undefined)
28
+ return { payload: undefined, truncated: false };
29
+ let text;
30
+ try {
31
+ text = JSON.stringify(payload);
32
+ }
33
+ catch {
34
+ return { payload: { note: "payload 含无法序列化的值,已省略" }, truncated: true };
35
+ }
36
+ if (text.length <= EVENT_PAYLOAD_LIMIT)
37
+ return { payload, truncated: false };
38
+ return {
39
+ payload: { preview: text.slice(0, EVENT_PAYLOAD_LIMIT - 32) },
40
+ truncated: true,
41
+ };
42
+ }
43
+ /**
44
+ * 追加一条事件。
45
+ *
46
+ * 序号由总线分配,调用方不要自己造:面板按 seq 增量拉取,自己造的序号会让续播错位。
47
+ */
48
+ export function emitEvent(input) {
49
+ const trimmed = trimmedPayload(input.payload);
50
+ const event = {
51
+ seq: nextSeq,
52
+ time: new Date().toISOString(),
53
+ source: input.source,
54
+ kind: input.kind,
55
+ status: input.status ?? "info",
56
+ summary: input.summary,
57
+ };
58
+ if (trimmed.payload !== undefined)
59
+ event.payload = trimmed.payload;
60
+ if (trimmed.truncated)
61
+ event.truncated = true;
62
+ if (input.refs !== undefined && input.refs.length > 0)
63
+ event.refs = input.refs;
64
+ const owner = (input.session ?? sessionKey).trim();
65
+ if (owner !== "")
66
+ event.session = owner;
67
+ nextSeq += 1;
68
+ ring.push(event);
69
+ if (ring.length > EVENT_RING_LIMIT) {
70
+ const overflow = ring.splice(0, ring.length - EVENT_RING_LIMIT);
71
+ for (const item of overflow)
72
+ pending.push(item);
73
+ if (pending.length > EVENT_PENDING_LIMIT) {
74
+ pendingDropped += pending.length - EVENT_PENDING_LIMIT;
75
+ pending = pending.slice(pending.length - EVENT_PENDING_LIMIT);
76
+ }
77
+ }
78
+ for (const listener of listeners) {
79
+ try {
80
+ listener(event);
81
+ }
82
+ catch {
83
+ // 订阅方自己出错不影响其它订阅方,也不该让工具调用失败。
84
+ }
85
+ }
86
+ return event;
87
+ }
88
+ /** 订阅新事件,返回注销函数。 */
89
+ export function subscribeEvents(listener) {
90
+ listeners.add(listener);
91
+ return () => {
92
+ listeners.delete(listener);
93
+ };
94
+ }
95
+ /**
96
+ * 取序号大于 since 的事件(按 seq 升序)。
97
+ * 传 session 时只返回该会话的事件;不传则返回全部(单会话时面板不传也能用)。
98
+ */
99
+ export function eventSnapshot(since = 0, session) {
100
+ const wanted = (session ?? "").trim();
101
+ const base = since <= 0 ? ring.slice() : ring.filter((event) => event.seq > since);
102
+ if (wanted === "")
103
+ return base;
104
+ return base.filter((event) => event.session === wanted);
105
+ }
106
+ /** 内存里当前保留的事件条数(面板与诊断用);传 session 时只数该会话的。 */
107
+ export function eventCount(session) {
108
+ const wanted = (session ?? "").trim();
109
+ if (wanted === "")
110
+ return ring.length;
111
+ return ring.reduce((total, event) => (event.session === wanted ? total + 1 : total), 0);
112
+ }
113
+ /** 取走待落盘的挤出事件;调用方负责写入成功后再确认。 */
114
+ export function drainEvicted() {
115
+ const drained = pending;
116
+ pending = [];
117
+ return drained;
118
+ }
119
+ /** 把落盘失败的条目放回队首(维持时间顺序),供下一轮重试。 */
120
+ export function requeueEvicted(events) {
121
+ if (events.length === 0)
122
+ return;
123
+ pending = events.concat(pending);
124
+ if (pending.length > EVENT_PENDING_LIMIT) {
125
+ pendingDropped += pending.length - EVENT_PENDING_LIMIT;
126
+ pending = pending.slice(pending.length - EVENT_PENDING_LIMIT);
127
+ }
128
+ }
129
+ /** 因落盘积压被丢弃的条数,写进缺口事件,避免证据目录看起来连续其实是断的。 */
130
+ export function takeDroppedCount() {
131
+ const count = pendingDropped;
132
+ pendingDropped = 0;
133
+ return count;
134
+ }
135
+ /**
136
+ * 绑定会话键:证据目录按它分目录,做到「一个会话一个目录」。
137
+ *
138
+ * 工具执行时能拿到 agent id,面板能拿到 session id,两者谁先到就用谁;
139
+ * 都没绑定时退回进程级默认键,事件照样可用,只是目录不按会话切分。
140
+ */
141
+ export function setEventSessionKey(key) {
142
+ const normalized = key.trim();
143
+ if (normalized === "" || normalized === sessionKey)
144
+ return;
145
+ sessionKey = normalized;
146
+ }
147
+ export function eventSessionKey() {
148
+ return sessionKey;
149
+ }
150
+ /** 单测用:清空全部状态。 */
151
+ export function resetEventBus() {
152
+ ring.length = 0;
153
+ pending = [];
154
+ pendingDropped = 0;
155
+ nextSeq = 1;
156
+ sessionKey = "";
157
+ listeners.clear();
158
+ }