dsh-stm32 0.1.6 → 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.
- package/README.md +410 -517
- package/README_EN.md +410 -510
- package/client/client.js +4363 -24
- package/docs/reading-guide.md +62 -0
- package/lib/client.js +4363 -24
- package/lib/commands/register.js +5 -5
- package/lib/data/chips.js +4 -4
- package/lib/data/clock-db.js +24 -24
- package/lib/data/clock-f1.js +2 -2
- package/lib/data/cmsis-sources.js +6 -6
- package/lib/data/db-presets.js +4 -4
- package/lib/data/device-facts.js +6 -6
- package/lib/data/family.js +16 -16
- package/lib/data/firmware-packages.js +10 -10
- package/lib/data/install-guides.js +18 -18
- package/lib/data/ioc-presets.js +3 -3
- package/lib/data/ioc-schema.js +32 -32
- package/lib/data/rm-topics.js +6 -6
- package/lib/data/search-roots.js +62 -16
- package/lib/data/serial-config.js +7 -7
- package/lib/data/stm32f1.js +1 -1
- package/lib/data/svd.js +7 -7
- package/lib/data/toolchain-config.js +3 -3
- package/lib/engine/artifacts.js +123 -0
- package/lib/engine/assets.js +5 -5
- package/lib/engine/breakpoint-hits.js +73 -0
- package/lib/engine/breakpoints.js +5 -5
- package/lib/engine/build.js +73 -3
- package/lib/engine/cache.js +4 -4
- package/lib/engine/channel-tap.js +227 -0
- package/lib/engine/channels.js +48 -0
- package/lib/engine/clock-derived.js +2 -2
- package/lib/engine/clock-direct.js +3 -3
- package/lib/engine/clock-plan.js +7 -7
- package/lib/engine/clock-pllmn.js +6 -6
- package/lib/engine/clocks.js +192 -0
- package/lib/engine/cmake-sources.js +9 -9
- package/lib/engine/code-patch.js +5 -5
- package/lib/engine/cube-mx-guard.js +3 -3
- package/lib/engine/cube-programmer.js +4 -4
- package/lib/engine/cubemx-db.js +7 -7
- package/lib/engine/debug-session.js +58 -13
- package/lib/engine/debug.js +3 -3
- package/lib/engine/doctor.js +12 -12
- package/lib/engine/download.js +1 -1
- package/lib/engine/event-bus.js +158 -0
- package/lib/engine/event-log.js +335 -0
- package/lib/engine/facts-acquire.js +3 -3
- package/lib/engine/fault-hints.js +146 -0
- package/lib/engine/fetch.js +2 -2
- package/lib/engine/firmware-install.js +16 -16
- package/lib/engine/firmware-official.js +8 -8
- package/lib/engine/flash.js +22 -22
- package/lib/engine/fs-longpath.js +1 -1
- package/lib/engine/gdb-mi.js +7 -7
- package/lib/engine/generate-script.js +2 -2
- package/lib/engine/generate.js +17 -17
- package/lib/engine/hal-chip.js +7 -7
- package/lib/engine/interrupts.js +247 -0
- package/lib/engine/ioc-diff.js +369 -0
- package/lib/engine/ioc-plan.js +52 -52
- package/lib/engine/ioc-rules.js +9 -9
- package/lib/engine/ioc-sync.js +58 -0
- package/lib/engine/ioc-verify.js +34 -34
- package/lib/engine/msys2-install.js +81 -56
- package/lib/engine/panel-actions.js +103 -0
- package/lib/engine/pinout.js +140 -0
- package/lib/engine/probe-error.js +8 -8
- package/lib/engine/probe-info.js +95 -0
- package/lib/engine/probe-session.js +3 -3
- package/lib/engine/probe.js +47 -50
- package/lib/engine/progress.js +99 -0
- package/lib/engine/project-conf.js +199 -0
- package/lib/engine/project-export.js +1 -1
- package/lib/engine/register-clock.js +5 -5
- package/lib/engine/register-gpio.js +3 -3
- package/lib/engine/register-linker.js +7 -7
- package/lib/engine/register-template.js +22 -22
- package/lib/engine/regs.js +3 -3
- package/lib/engine/rm-extract.js +2 -2
- package/lib/engine/rm-sources.js +1 -1
- package/lib/engine/route-plan.js +9 -9
- package/lib/engine/rtt.js +18 -18
- package/lib/engine/scaffold.js +22 -22
- package/lib/engine/serial.js +24 -24
- package/lib/engine/session-context.js +19 -0
- package/lib/engine/source-slice.js +59 -0
- package/lib/engine/tar.js +1 -1
- package/lib/engine/text-file.js +1 -1
- package/lib/engine/thirdparty.js +3 -3
- package/lib/engine/tool-env.js +2 -2
- package/lib/engine/tool-events.js +119 -0
- package/lib/engine/toolchain-gate.js +8 -8
- package/lib/engine/usercode-merge.js +2 -2
- package/lib/engine/vscode-config.js +2 -2
- package/lib/engine/watch-admin.js +101 -0
- package/lib/engine/watch-record.js +39 -0
- package/lib/engine/watch-recorder.js +116 -0
- package/lib/engine/web-api.js +887 -5
- package/lib/engine/web-routes.js +18 -1
- package/lib/engine/workspace-memo.js +41 -0
- package/lib/engine/xcube-catalog.js +1 -1
- package/lib/index.js +72 -29
- package/lib/skill/stm32-workflow.js +1 -1
- package/lib/tools/assets.js +1 -1
- package/lib/tools/cache.js +2 -2
- package/lib/tools/debug-session.js +5 -5
- package/lib/tools/doctor.js +2 -2
- package/lib/tools/download.js +1 -1
- package/lib/tools/env-install.js +3 -3
- package/lib/tools/firmware-install.js +5 -5
- package/lib/tools/flash.js +8 -8
- package/lib/tools/generate.js +1 -1
- package/lib/tools/ioc-apply.js +10 -1
- package/lib/tools/ioc-plan.js +1 -1
- package/lib/tools/ioc-verify.js +11 -11
- package/lib/tools/project-create.js +32 -4
- package/lib/tools/project-dir.js +8 -2
- package/lib/tools/regs.js +10 -10
- package/lib/tools/route-plan.js +9 -9
- package/lib/tools/rtt.js +17 -9
- package/lib/tools/serial.js +30 -8
- package/lib/tools/watch.js +24 -2
- package/package.json +70 -70
- package/templates/scaffold/RTT.md +26 -34
package/docs/reading-guide.md
CHANGED
|
@@ -857,3 +857,65 @@ const fake = {
|
|
|
857
857
|
---
|
|
858
858
|
|
|
859
859
|
读完这一遍,最值得回头再看两处的顺序是:**先 7.8(generate)再看 5.5**,因为 generate 是全仓库复杂度顶点,看懂它就等于看懂了「编码层 + 备份 + 缓存 + 产物判据 + 锁」这五条横切关注点如何在一个流程里共存。
|
|
860
|
+
|
|
861
|
+
## 15. 调试台:事件流与停靠网格(0.1.7 增补,S1–S89)
|
|
862
|
+
|
|
863
|
+
> 接续 §14。这一节新增的是一个主窗口标签(`conversation.view`)和它背后的只读事件流,不改任何工具的行为与契约。
|
|
864
|
+
|
|
865
|
+
### 15.1 先读哪里
|
|
866
|
+
|
|
867
|
+
- `src/engine/event-bus.ts`:环形缓冲与序号。`EVENT_RING_LIMIT = 5000`、`EVENT_PAYLOAD_LIMIT = 8192`、`EVENT_PENDING_LIMIT = 2000`;`emitEvent` 是唯一写入入口。
|
|
868
|
+
- `src/engine/event-log.ts`:被挤出的事件按 30 秒一批写到 `<证据根>/<日期>/<会话键>/events-<HHmmss>.jsonl`;缺口先写一条 `kind:"log"` 的事件。
|
|
869
|
+
- `src/engine/tool-events.ts`:装配期 Proxy 只包 `tools.register`,给 `stm32_*` 工具加 start / ok / fail。
|
|
870
|
+
- `src/engine/channels.ts`:串口 / RTT / 监视的输出编成 `channel:<名字>` 事件(单行 ≤400 字符、单次 ≤400 行)。
|
|
871
|
+
- `src/engine/web-api.ts` 的 `openEventStream` 与 `EVENT_STREAM_PATH`(`/dsh-stm32/api/events`,SSE,`?since=` 续播、`&session=` 按会话过滤);`/status` 返回计数与证据目录,`?session=` 只数本会话。`self` 带版本、`libMtimeMs`、`startedAt`、`routeCount`——状态条据此提示「有新构建」。
|
|
872
|
+
- `src/engine/web-routes.ts`:事件流单独分支,直接写原始 `response`,不进 JSON 分发器。
|
|
873
|
+
- `GET /dsh-stm32/api/debug` 与客户端会话卡:只读调试会话摘要(端口、剩余租约、断点与观察点配额),5 秒轮询。
|
|
874
|
+
- `POST /dsh-stm32/api/debug/breakpoints`:断点面板的三个动作(list / add / remove),位置与编号白名单,不做任意 gdb 命令转发。
|
|
875
|
+
- `src/engine/progress.ts` 与 `POST /dsh-stm32/api/abort`:在途调用登记表与中止;派生 AbortController 把宿主的 abort 转发进来,面板只掐自己这一支,工具仍把信号透传给子进程。`/status` 的 `running` 与事件流里的 `callId` 是同一份事实的两种读法。
|
|
876
|
+
- `src/engine/pinout.ts` 与 `/pinout`:引脚面板。`readPinout(projectDir, env)` 复用 `summarizeIoc`,`groupOfPin` / `groupPins` 决定分组与顺序(外设自然序在前,GPIO/调试口/时钟/虚拟引脚在后);同一份报告里的 `physical` 来自 `readPhysicalLayout`(读 CubeMX `db/mcu/<Mcu.Name>.xml` 的 `Position`,`pinCount` 取最大脚号而不是去重后的名字数),客户端「方框」视图由 `pinBoxSides` 摊到四边、`PinBox` 渲染,没有 db 时只显示 `reason`。
|
|
877
|
+
- `src/engine/fault-hints.ts` 与 `/faults`:故障页。`decodeFault` 是纯函数规则表,按最具体优先;没命中就返回空提示,不猜原因。`groupFaults` 按规则合并计数给面板显示,不改事件本身。
|
|
878
|
+
- `/evidence` 与 `/replay`:列证据文件(`groupEvidenceFiles` 按会话分组,路径仍是唯一标识)、按路径还原事件;回放入口在时间线工具栏,不与实时事件混流。
|
|
879
|
+
- `src/engine/ioc-diff.ts` 与 `/ioc-diff`、`/ioc-diff/save`、`/ioc-diff/restore`:当前 .ioc 与用户目录里基线的逐键差异;基线覆盖式保存,不依赖 git;`restoreIocKey` 把某个键写回基线值,写前备份到 `<工程>/.dsh-stm32/backups`。
|
|
880
|
+
- `readIocKeysForPin` 与 `/ioc-keys`:引脚页「ioc」按钮查看该脚在 `.ioc` 里占的键(前缀匹配,退一步取第一段)。
|
|
881
|
+
- `src/engine/breakpoint-hits.ts`:从 gdb 输出解析断点/观察点停点,`HitHistory` 环形 50 条;`/debug` 的 `hits` 给断点面板底部列表。
|
|
882
|
+
- `DebugSessionManager` 的 `EvalTrace` 与 `recentTraces()`:`/debug` 的 `outputs` 给会话卡显示最近几次 gdb 原始输出(环形 20 条、每条留尾部 2000 字符)。
|
|
883
|
+
- `src/engine/watch-recorder.ts` 与 `watch-record.ts`:监视自动采样。定时器夹在 500–60000 ms、一次最多 10 分钟,`sample` 复用 `debugSessions.sampleWatches`,结果仍走 `channel:watch`,面板不换数据源。
|
|
884
|
+
- `POST /serial/send`:面板在串口通道里发一行,参数校验后调 `sendSerial`,与工具入口共用桥命令;无会话时 409。
|
|
885
|
+
- 引脚行点击复制引用(`PA9 USART1_TX`),`PinRow` 里内联实现,没有服务端接口。
|
|
886
|
+
- `ChannelBlock` 的关键字过滤与 RTT 级别按钮:纯展示层,只作用于当前暂停/清空窗口。
|
|
887
|
+
- `POST /debug/touch` 与 `DebugSessionManager.touch()`:会话续期只重置空闲计时,总时长上限不变。
|
|
888
|
+
- 时间线工具栏:状态筛选(全部 / 只看失败)与「导出 JSONL」,纯客户端,导出的是当前视图。
|
|
889
|
+
- 客户端 `toolDurations`:按 `callId` 配对 start 与 ok/fail 算耗时,超过 `TOOL_SLOW_MS`(5 秒)标黄;工具栏可切「按时间 / 按耗时」。
|
|
890
|
+
- 时间线勾选与「复制已选(N)」:`eventRefBlock` 把多条事件拼成一段引用,顺序按时间线而不是勾选顺序;纯客户端。
|
|
891
|
+
- `src/engine/artifacts.ts` 与 `/artifacts`:产物页。`readArtifacts` 只读构建目录里的 elf/hex/bin 文件属性,容量取 `findChipFact` 的芯片事实;Flash/RAM 占用不在这里算,面板从 `stm32_build` 的 ok 事件里取 `memoryUsage`,保证只有一份数字。
|
|
892
|
+
- 客户端 `OverviewPanel` 的工具链一行:`useProbeSummary(60000)` 读 `GET /probe`,能力四项只认 `capabilities`,缺件直接列名。
|
|
893
|
+
- 客户端 `OverviewPanel`:概览页,纯拼装 `usePinout` / `useClockTree` / `useArtifacts` / `useDebugStatus` 与事件流里的构建、烧录时间戳,没有对应的服务端接口。
|
|
894
|
+
- `src/engine/clocks.ts` 与 `/clocks`:时钟页。只读 `.ioc` 的 `RCC.*Freq_Value`,不复算;`dividerLabel` / `mulLabel` 只做展示翻译。`familyOfCpn` / `limitForNode` 按芯片族给出 APB1/APB2/ADC 上限并判超限,`suggestFix` 只对这三路枚举分频档给出「改成 ÷N」的建议(不写 `.ioc`,改配置仍走 `stm32_ioc_plan`);客户端 `ClockPanel` 的表/图两种模式共用同一份节点数据,图模式由 `ClockFlow` 用 `clockFlowRows` 摊平层级后渲染。
|
|
895
|
+
- `src/engine/event-log.ts` 的 `pruneEvidence`:证据保留(7 天 / 20 会话)与 `/evidence/prune`。
|
|
896
|
+
- `src/engine/tool-events.ts` 的 `resultDigest`:白名单决定面板能看见哪些结果字段(`errors` 截 20 条、`projectDir` 用于跳源码)。
|
|
897
|
+
- `src/engine/source-slice.ts` 与 `/source`:停点与编译错误跳源码。
|
|
898
|
+
- `src/engine/serial.ts` 的 `openSerial`/`closeSerial`/`serialStatus`/`listPorts` 与 `/serial*`:面板上的串口卡片,与工具同源。`resolveSourceFile` 要求目标落在工程目录内,`readSourceSlice` 把行号夹到文件范围、上下文封顶 20 行。
|
|
899
|
+
- `src/engine/panel-actions.ts` 与 `/build`、`/flash`:人在面板点构建/烧录,直接调 `runBuild` / `runFlash`,结果以 `source: "user"` 的同形事件进时间线。
|
|
900
|
+
- `src/engine/watch-admin.ts` 与 `/watch`:面板编辑监视登记表,与 `stm32_watch` 共用 `watchState`;删项交给 `debugSessions.removeWatchpoints`,顺带清 gdb 比较器。
|
|
901
|
+
- `src/engine/ioc-sync.ts` 与 `/ioc-sync`:只比 `.ioc` 与 `Core/Src/main.c` 的修改时间,判断「配置改了还没重新生成」;没有 `main.c` 时不下结论。
|
|
902
|
+
- `src/engine/interrupts.ts` 与 `/interrupts`、`/interrupts/priority`:中断页。读 `.ioc` 的 `NVIC.*`(值里的冒号是转义的),优先级排序按抢占→子→名字;段数不足给 -1,不冒充 0;`setInterruptPriority` 只改第二、三段并先备份。
|
|
903
|
+
- `src/engine/channel-tap.ts` 与 `/channels`、`/channels/start`、`/channels/stop`:常驻通道。串口 700 ms 读一次 `rx.ndjson` 的增量、RTT 2 000 ms `dump` 一次,都写回同一套 `channel:*` 事件;偏移靠「尾部指纹」而不是长度判断,桥重写文件也不会错位,`p: true` 的残行跨记录拼接。
|
|
904
|
+
- `client/client.js`:`DebugConsole`(时间线 / 详情 / 通道 / 控制台 / 抽屉)、`SessionCard`、`WatchCurves`(按表达式画最近 120 点)、`BreakpointPanel`;`conversation.view` 的 `inject(sessionId)` 把宿主会话键交给面板,事件与状态都按它过滤;布局存 `dsh-stm32.debug.layout.v1`。
|
|
905
|
+
- `test/event-bus-units.test.mjs`、`test/client-debug-units.test.mjs`:改事件层或客户端结构后先跑这两个。
|
|
906
|
+
|
|
907
|
+
### 15.2 三条不变量
|
|
908
|
+
|
|
909
|
+
1. **单一事实源**:面板不缓存第二份数据,只按 `seq` 增量续播;重连从 `lastSeq` 开始,不重放全量。
|
|
910
|
+
2. **落盘可表达缺口**:缓冲区溢出或写入失败时,证据目录里必须有痕迹(缺口事件或整批回队),不能静默丢。
|
|
911
|
+
3. **埋点与工具解耦**:工具实现不感知事件系统;`stm32_*` 前缀决定是否被包装,其它插件的工具原样注册。
|
|
912
|
+
|
|
913
|
+
### 15.3 计数口径(0.1.7 起)
|
|
914
|
+
|
|
915
|
+
| 项 | 当前值 |
|
|
916
|
+
| --- | --- |
|
|
917
|
+
| 注册工具 | 25 个 |
|
|
918
|
+
| 源码 | `src/**/*.ts` 131 个文件 |
|
|
919
|
+
| 单测 | 80 个套件 / 1088 pass / 0 fail |
|
|
920
|
+
| 客户端 | `client/client.js` 5021 行(手写,不经 tsc) |
|
|
921
|
+
| 包体 | 1979.8 KB / 295 文件 / 解包 15772.0 KB(护栏上限 3906.3 KB) |
|