dsh-stm32 0.1.7 → 0.1.9

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 (153) hide show
  1. package/README.md +567 -516
  2. package/README_EN.md +544 -510
  3. package/client/client.js +7033 -682
  4. package/docs/reading-guide.md +921 -859
  5. package/lib/client.js +7033 -682
  6. package/lib/commands/register.js +2 -0
  7. package/lib/data/firmware-packages.js +35 -0
  8. package/lib/data/firmware-pins.js +7 -0
  9. package/lib/data/install-guides.js +110 -0
  10. package/lib/data/ioc-presets.js +118 -0
  11. package/lib/engine/artifacts.js +123 -0
  12. package/lib/engine/breakpoint-hits.js +73 -0
  13. package/lib/engine/build.js +161 -5
  14. package/lib/engine/channel-tap.js +227 -0
  15. package/lib/engine/channels.js +48 -0
  16. package/lib/engine/clocks.js +192 -0
  17. package/lib/engine/datasheet/auto.js +74 -0
  18. package/lib/engine/datasheet/digest.js +74 -0
  19. package/lib/engine/datasheet/lcsc.js +60 -0
  20. package/lib/engine/datasheet/pinout.js +119 -0
  21. package/lib/engine/datasheet/price.js +152 -0
  22. package/lib/engine/datasheet/search.js +147 -0
  23. package/lib/engine/datasheet/store.js +371 -0
  24. package/lib/engine/debug-session.js +48 -2
  25. package/lib/engine/ecad/autobuild.js +156 -0
  26. package/lib/engine/ecad/bom.js +238 -0
  27. package/lib/engine/ecad/brief.js +205 -0
  28. package/lib/engine/ecad/checks.js +239 -0
  29. package/lib/engine/ecad/design.js +177 -0
  30. package/lib/engine/ecad/dfm.js +314 -0
  31. package/lib/engine/ecad/easyeda.js +454 -0
  32. package/lib/engine/ecad/fabrication.js +104 -0
  33. package/lib/engine/ecad/gen/footprint.js +159 -0
  34. package/lib/engine/ecad/gen/symbol.js +103 -0
  35. package/lib/engine/ecad/import.js +372 -0
  36. package/lib/engine/ecad/jlcpcb.js +141 -0
  37. package/lib/engine/ecad/libs.js +316 -0
  38. package/lib/engine/ecad/models3d.js +89 -0
  39. package/lib/engine/ecad/netgate.js +286 -0
  40. package/lib/engine/ecad/normalize.js +182 -0
  41. package/lib/engine/ecad/package.js +126 -0
  42. package/lib/engine/ecad/padmerge.js +128 -0
  43. package/lib/engine/ecad/padprecheck.js +123 -0
  44. package/lib/engine/ecad/part-import.js +257 -0
  45. package/lib/engine/ecad/pcb/apply.js +53 -0
  46. package/lib/engine/ecad/pcb/emc-deep.js +396 -0
  47. package/lib/engine/ecad/pcb/emc.js +275 -0
  48. package/lib/engine/ecad/pcb/geometry.js +63 -0
  49. package/lib/engine/ecad/pcb/gerber.js +499 -0
  50. package/lib/engine/ecad/pcb/hand-sync.js +242 -0
  51. package/lib/engine/ecad/pcb/impedance.js +119 -0
  52. package/lib/engine/ecad/pcb/ipc-open.js +78 -0
  53. package/lib/engine/ecad/pcb/ipc-script.js +276 -0
  54. package/lib/engine/ecad/pcb/ipc.js +129 -0
  55. package/lib/engine/ecad/pcb/krt.js +182 -0
  56. package/lib/engine/ecad/pcb/links.js +393 -0
  57. package/lib/engine/ecad/pcb/mech.js +201 -0
  58. package/lib/engine/ecad/pcb/model-fix.js +178 -0
  59. package/lib/engine/ecad/pcb/netlist.js +146 -0
  60. package/lib/engine/ecad/pcb/pcb-svg.js +199 -0
  61. package/lib/engine/ecad/pcb/placement.js +140 -0
  62. package/lib/engine/ecad/pcb/power.js +203 -0
  63. package/lib/engine/ecad/pcb/render3d.js +208 -0
  64. package/lib/engine/ecad/pcb/route.js +167 -0
  65. package/lib/engine/ecad/pcb/router.js +469 -0
  66. package/lib/engine/ecad/pcb/rules.js +122 -0
  67. package/lib/engine/ecad/pcb/scene.js +513 -0
  68. package/lib/engine/ecad/pcb/stackup.js +154 -0
  69. package/lib/engine/ecad/pcb/swap.js +222 -0
  70. package/lib/engine/ecad/pcb/tracks.js +70 -0
  71. package/lib/engine/ecad/runtime.js +227 -0
  72. package/lib/engine/ecad/toolchain.js +146 -0
  73. package/lib/engine/ecad/tsci.js +362 -0
  74. package/lib/engine/ecad/zip.js +98 -0
  75. package/lib/engine/event-bus.js +158 -0
  76. package/lib/engine/event-log.js +335 -0
  77. package/lib/engine/fault-hints.js +146 -0
  78. package/lib/engine/generate-script.js +4 -1
  79. package/lib/engine/generate.js +145 -5
  80. package/lib/engine/interrupts.js +247 -0
  81. package/lib/engine/ioc-diff.js +369 -0
  82. package/lib/engine/ioc-plan.js +12 -2
  83. package/lib/engine/ioc-sync.js +58 -0
  84. package/lib/engine/mcu-info.js +134 -0
  85. package/lib/engine/msys2-install.js +31 -6
  86. package/lib/engine/panel-actions.js +103 -0
  87. package/lib/engine/pdf/curve.js +321 -0
  88. package/lib/engine/pdf/png.js +83 -0
  89. package/lib/engine/pdf/reader.js +336 -0
  90. package/lib/engine/pdf/schematic.js +93 -0
  91. package/lib/engine/pdf/tables.js +249 -0
  92. package/lib/engine/pdf/toolchain.js +50 -0
  93. package/lib/engine/pinout.js +140 -0
  94. package/lib/engine/probe-info.js +95 -0
  95. package/lib/engine/probe.js +45 -0
  96. package/lib/engine/progress.js +99 -0
  97. package/lib/engine/project-conf.js +254 -0
  98. package/lib/engine/project-layout.js +198 -0
  99. package/lib/engine/project-repair.js +205 -0
  100. package/lib/engine/schematic/checks.js +153 -0
  101. package/lib/engine/schematic/draw.js +390 -0
  102. package/lib/engine/schematic/edit.js +229 -0
  103. package/lib/engine/schematic/kicad-sch.js +225 -0
  104. package/lib/engine/schematic/model.js +442 -0
  105. package/lib/engine/schematic/nets.js +219 -0
  106. package/lib/engine/schematic/pcb.js +144 -0
  107. package/lib/engine/schematic/review.js +134 -0
  108. package/lib/engine/schematic/sexpr.js +134 -0
  109. package/lib/engine/schematic/to-ioc.js +197 -0
  110. package/lib/engine/schematic/transform.js +25 -0
  111. package/lib/engine/session-context.js +106 -0
  112. package/lib/engine/source-slice.js +59 -0
  113. package/lib/engine/tool-events.js +119 -0
  114. package/lib/engine/toolchain-gate.js +8 -0
  115. package/lib/engine/watch-admin.js +101 -0
  116. package/lib/engine/watch-record.js +39 -0
  117. package/lib/engine/watch-recorder.js +116 -0
  118. package/lib/engine/web-api.js +1123 -4
  119. package/lib/engine/web-routes.js +18 -1
  120. package/lib/engine/workspace-memo.js +41 -0
  121. package/lib/index.js +118 -24
  122. package/lib/skill/stm32-workflow.js +1 -1
  123. package/lib/tools/build.js +10 -2
  124. package/lib/tools/code-patch.js +2 -2
  125. package/lib/tools/datasheet.js +447 -0
  126. package/lib/tools/debug-session.js +9 -4
  127. package/lib/tools/debug.js +2 -2
  128. package/lib/tools/doctor.js +2 -2
  129. package/lib/tools/ecad.js +903 -0
  130. package/lib/tools/flash.js +2 -2
  131. package/lib/tools/gen.js +166 -0
  132. package/lib/tools/generate.js +7 -5
  133. package/lib/tools/import-circuit.js +146 -0
  134. package/lib/tools/ioc-apply.js +11 -2
  135. package/lib/tools/ioc-inspect.js +2 -2
  136. package/lib/tools/ioc-plan.js +2 -2
  137. package/lib/tools/ioc-verify.js +2 -2
  138. package/lib/tools/layout.js +92 -0
  139. package/lib/tools/mcu-info.js +163 -0
  140. package/lib/tools/part-import.js +182 -0
  141. package/lib/tools/pcb.js +2316 -0
  142. package/lib/tools/pdf.js +423 -0
  143. package/lib/tools/project-create.js +28 -0
  144. package/lib/tools/project-dir.js +25 -1
  145. package/lib/tools/regs.js +2 -2
  146. package/lib/tools/route-plan.js +2 -2
  147. package/lib/tools/rtt.js +10 -2
  148. package/lib/tools/sch-draw.js +433 -0
  149. package/lib/tools/sch-edit.js +145 -0
  150. package/lib/tools/schematic.js +817 -0
  151. package/lib/tools/serial.js +22 -0
  152. package/lib/tools/watch.js +24 -2
  153. package/package.json +1 -1
@@ -0,0 +1,423 @@
1
+ /**
2
+ * PDF 读取工具(S117)。
3
+ *
4
+ * 一个工具四种用法,覆盖读数据手册与原理图 PDF 的全部动作:
5
+ * info —— 页数、纸张、有没有文字层(决定后面走文字还是走图);
6
+ * text —— 指定页范围的文字(-layout 保版面,表格能读);
7
+ * figures —— 从图注/目录行里列图与表,知道「第几页有什么图」;
8
+ * render —— 页面或局部渲染成 PNG,返回文件路径供视觉读图(曲线、框图、丝印)。
9
+ *
10
+ * 为什么不一个动作做完:整本 1000 页转文本会烧掉上下文,渲染整页也不总是需要的。
11
+ * 先 info 判断,再按需取页,是本工具的使用姿势。
12
+ */
13
+ import { extname, isAbsolute, resolve } from "node:path";
14
+ import { resolveSearchConfig } from "../data/search-roots.js";
15
+ import { extractPdfTables, extractPdfText, listFigures, readPdfCurves, readPdfInfo, renderPdfPage, readPdfSchematic, } from "../engine/pdf/reader.js";
16
+ import { locatePoppler } from "../engine/pdf/toolchain.js";
17
+ import { datasheetCacheDir, resolveDatasheetRef } from "../engine/datasheet/store.js";
18
+ export const PDF_READ_TOOL = "stm32_pdf_read";
19
+ const MODES = ["info", "text", "figures", "table", "render", "curve", "schematic"];
20
+ const noteSchema = {
21
+ type: "array",
22
+ items: { type: "string" },
23
+ description: "本次调用的补充说明:为什么给了这个结果、下一步该做什么。",
24
+ };
25
+ const outputSchema = {
26
+ type: "object",
27
+ additionalProperties: false,
28
+ properties: {
29
+ ok: { type: "boolean" },
30
+ error: { type: "string" },
31
+ mode: { type: "string", enum: [...MODES] },
32
+ file: { type: "string" },
33
+ info: {
34
+ type: "object",
35
+ additionalProperties: false,
36
+ properties: {
37
+ pages: { type: "number" },
38
+ title: { type: "string" },
39
+ producer: { type: "string" },
40
+ pageSize: { type: "string" },
41
+ encrypted: { type: "boolean" },
42
+ hasTextLayer: { type: "boolean" },
43
+ },
44
+ required: ["pages", "title", "producer", "pageSize", "encrypted", "hasTextLayer"],
45
+ },
46
+ pages: {
47
+ type: "array",
48
+ items: {
49
+ type: "object",
50
+ additionalProperties: false,
51
+ properties: {
52
+ page: { type: "number" },
53
+ text: { type: "string" },
54
+ },
55
+ required: ["page", "text"],
56
+ },
57
+ },
58
+ schematic: {
59
+ type: "object",
60
+ additionalProperties: false,
61
+ properties: {
62
+ pages: { type: "number" },
63
+ words: { type: "number" },
64
+ components: {
65
+ type: "array",
66
+ items: {
67
+ type: "object",
68
+ additionalProperties: false,
69
+ properties: {
70
+ ref: { type: "string" },
71
+ value: { type: "string" },
72
+ page: { type: "number" },
73
+ },
74
+ required: ["ref", "value", "page"],
75
+ },
76
+ },
77
+ labels: {
78
+ type: "array",
79
+ items: {
80
+ type: "object",
81
+ additionalProperties: false,
82
+ properties: {
83
+ name: { type: "string" },
84
+ pages: { type: "array", items: { type: "number" } },
85
+ count: { type: "number" },
86
+ },
87
+ required: ["name", "pages", "count"],
88
+ },
89
+ },
90
+ notes: { type: "array", items: { type: "string" } },
91
+ },
92
+ required: ["pages", "words", "components", "labels", "notes"],
93
+ },
94
+ curves: {
95
+ type: "object",
96
+ additionalProperties: false,
97
+ properties: {
98
+ page: { type: "number" },
99
+ series: {
100
+ type: "array",
101
+ items: {
102
+ type: "object",
103
+ additionalProperties: false,
104
+ properties: {
105
+ hue: { type: "string" },
106
+ label: { type: "string", description: "图例里认出的名字(Mean / Max);认不出为空串。" },
107
+ color: { type: "string" },
108
+ pixels: { type: "number" },
109
+ points: {
110
+ type: "array",
111
+ items: {
112
+ type: "object",
113
+ additionalProperties: false,
114
+ properties: { x: { type: "number" }, y: { type: "number" } },
115
+ required: ["x", "y"],
116
+ },
117
+ },
118
+ },
119
+ required: ["hue", "color", "pixels", "points"],
120
+ },
121
+ },
122
+ xTicks: { type: "array", items: { type: "number" } },
123
+ yTicks: { type: "array", items: { type: "number" } },
124
+ },
125
+ required: ["page", "series", "xTicks", "yTicks"],
126
+ },
127
+ figures: {
128
+ type: "array",
129
+ items: {
130
+ type: "object",
131
+ additionalProperties: false,
132
+ properties: {
133
+ number: { type: "string" },
134
+ title: { type: "string" },
135
+ page: { type: "number" },
136
+ },
137
+ required: ["number", "title", "page"],
138
+ },
139
+ },
140
+ tables: {
141
+ type: "array",
142
+ items: {
143
+ type: "object",
144
+ additionalProperties: false,
145
+ properties: {
146
+ title: { type: "string" },
147
+ page: { type: "number" },
148
+ rows: { type: "number" },
149
+ columns: { type: "array", items: { type: "string" } },
150
+ cells: { type: "array", items: { type: "array", items: { type: "string" } } },
151
+ confidence: { type: "string", enum: ["high", "medium"] },
152
+ warnings: { type: "array", items: { type: "string" } },
153
+ },
154
+ required: ["title", "page", "rows", "columns", "cells", "confidence", "warnings"],
155
+ },
156
+ },
157
+ imageFile: { type: "string" },
158
+ imageWidth: { type: "number" },
159
+ imageHeight: { type: "number" },
160
+ dpi: { type: "number" },
161
+ notes: noteSchema,
162
+ },
163
+ required: ["ok", "error", "mode", "file", "notes"],
164
+ };
165
+ export function popplerDirs() {
166
+ const config = resolveSearchConfig(process.env);
167
+ const extra = (process.env["DSH_STM32_BIN_DIRS"] ?? "")
168
+ .split(";")
169
+ .map((dir) => dir.trim())
170
+ .filter((dir) => dir !== "");
171
+ return [...new Set([...extra, ...config.binDirs])];
172
+ }
173
+ function absoluteFile(raw) {
174
+ return isAbsolute(raw) ? raw : resolve(raw);
175
+ }
176
+ export function registerPdfTools(ctx) {
177
+ ctx.tools.register({
178
+ name: PDF_READ_TOOL,
179
+ description: "读 PDF:数据手册与原理图都适用。mode=info 看页数与有无文字层;text 取指定页文字(-layout 保版面,表格可读);figures 列图与表;render 把页面或局部渲染成 PNG 并返回路径,供视觉读曲线与框图。",
180
+ parameters: {
181
+ type: "object",
182
+ additionalProperties: false,
183
+ properties: {
184
+ file: { type: "string", description: "PDF 路径;相对工程根或当前目录。" },
185
+ mode: { type: "string", enum: [...MODES], description: "info(默认)/ text / figures / table / render / curve / schematic。" },
186
+ first: { type: "number", description: "text 与 figures 的起始页(默认 1)。" },
187
+ last: { type: "number", description: "text / figures / table 的结束页(默认同 first;text 最多 20 页)。" },
188
+ page: { type: "number", description: "render 的页码(从 1 开始)。" },
189
+ dpi: { type: "number", description: "render 的分辨率 72–600,默认 150;抠字用 400。" },
190
+ crop: {
191
+ type: "object",
192
+ additionalProperties: false,
193
+ properties: {
194
+ x: { type: "number" },
195
+ y: { type: "number" },
196
+ width: { type: "number" },
197
+ height: { type: "number" },
198
+ },
199
+ required: ["x", "y", "width", "height"],
200
+ description: "render 的裁切区域:按该 dpi 渲染后的像素坐标,用于放大某一张图。",
201
+ },
202
+ },
203
+ required: ["file"],
204
+ },
205
+ output: {
206
+ schema: outputSchema,
207
+ render: (_args, value) => {
208
+ const result = value;
209
+ if (!result.ok)
210
+ return [{ type: "text", text: "读取失败:" + result.error }];
211
+ const lines = [];
212
+ if (result.mode === "info" && result.info !== undefined) {
213
+ lines.push("PDF:" + result.file, "页数 " + String(result.info.pages) + " · " + result.info.pageSize + " · 文字层 " + (result.info.hasTextLayer ? "有" : "无"));
214
+ }
215
+ if (result.mode === "text" && result.pages !== undefined) {
216
+ for (const page of result.pages) {
217
+ lines.push("", "=== 第 " + String(page.page) + " 页 ===", page.text);
218
+ }
219
+ }
220
+ if (result.mode === "schematic" && result.schematic !== undefined) {
221
+ const view = result.schematic;
222
+ const lines = [
223
+ "元件清单:" + String(view.components.length) + " 个(第 " + String(view.pages) + " 页文字,共 " + String(view.words) + " 个词)",
224
+ ];
225
+ for (const item of view.components.slice(0, 40)) {
226
+ lines.push(" " + item.ref + (item.value === "" ? "" : " " + item.value) + "(第 " + String(item.page) + " 页)");
227
+ }
228
+ if (view.components.length > 40)
229
+ lines.push(" …其余 " + String(view.components.length - 40) + " 个略");
230
+ if (view.labels.length > 0) {
231
+ lines.push("网络标签:" + view.labels.slice(0, 20).map((label) => label.name + "×" + String(label.count)).join("、"));
232
+ }
233
+ for (const note of view.notes)
234
+ lines.push("· " + note);
235
+ return [{ type: "text", text: lines.join("\n") }];
236
+ }
237
+ if (result.mode === "figures" && result.figures !== undefined) {
238
+ lines.push("图与表 " + String(result.figures.length) + " 条:");
239
+ for (const figure of result.figures) {
240
+ lines.push(" Figure " + figure.number + " · " + figure.title + (figure.page > 0 ? "(第 " + String(figure.page) + " 页)" : ""));
241
+ }
242
+ }
243
+ if (result.mode === "curve" && result.curves !== undefined) {
244
+ const lines = [
245
+ "曲线:" + String(result.curves.series.length) + " 条(第 " + String(result.curves.page) + " 页," + String(result.dpi ?? 0) + " dpi)",
246
+ "纵轴刻度:" + result.curves.yTicks.join(" / "),
247
+ "横轴刻度:" + result.curves.xTicks.join(" / "),
248
+ ];
249
+ for (const item of result.curves.series) {
250
+ const first = item.points[0];
251
+ const last = item.points[item.points.length - 1];
252
+ lines.push("- " + item.hue + (item.label === undefined || item.label === "" ? "" : "(" + item.label + ")") + ":" + String(item.points.length) + " 点," +
253
+ (first === undefined ? "?" : String(first.x) + " → " + String(first.y)) + " … " +
254
+ (last === undefined ? "?" : String(last.x) + " → " + String(last.y)));
255
+ }
256
+ return [{ type: "text", text: lines.join("\n") }];
257
+ }
258
+ if (result.mode === "table" && result.tables !== undefined) {
259
+ lines.push("表 " + String(result.tables.length) + " 张:");
260
+ for (const table of result.tables) {
261
+ lines.push("", table.title + "(第 " + String(table.page) + " 页," + table.confidence + ")");
262
+ lines.push(" " + table.columns.join(" | "));
263
+ for (const row of table.cells.slice(1, 21))
264
+ lines.push(" " + row.join(" | "));
265
+ for (const warning of table.warnings)
266
+ lines.push(" ! " + warning);
267
+ }
268
+ }
269
+ if (result.mode === "render" && result.imageFile !== undefined) {
270
+ lines.push("第 " + String(result.dpi ?? 0) + " dpi · " + String(result.imageWidth ?? 0) + "×" + String(result.imageHeight ?? 0), "图像:" + result.imageFile);
271
+ }
272
+ for (const note of result.notes)
273
+ lines.push("· " + note);
274
+ return [{ type: "text", text: lines.join("\n") }];
275
+ },
276
+ },
277
+ timeoutMs: 180_000,
278
+ isConcurrencySafe: () => false,
279
+ execute: async (args, exec) => {
280
+ const mode = args.mode ?? "info";
281
+ // 允许直接写立创编号或型号:命中本地手册缓存时按缓存路径读(S119)。
282
+ const cached = resolveDatasheetRef(datasheetCacheDir(), args.file);
283
+ const file = cached === null ? absoluteFile(args.file) : cached.file;
284
+ const located = locatePoppler(popplerDirs());
285
+ const base = {
286
+ ok: false,
287
+ error: "",
288
+ mode,
289
+ file,
290
+ notes: [],
291
+ schematic: undefined,
292
+ curves: undefined,
293
+ };
294
+ if (cached !== null)
295
+ base.notes.push("手册来自本地缓存:" + cached.entry.code + " · " + cached.entry.mpn);
296
+ if (located.tools === null)
297
+ return { ...base, error: located.error };
298
+ if (mode === "info") {
299
+ const info = await readPdfInfo(ctx.subprocess, located.tools, file, exec.signal);
300
+ if (!info.ok)
301
+ return { ...base, error: info.error };
302
+ return {
303
+ ...base,
304
+ ok: true,
305
+ info: {
306
+ pages: info.pages,
307
+ title: info.title,
308
+ producer: info.producer,
309
+ pageSize: info.pageSize,
310
+ encrypted: info.encrypted,
311
+ hasTextLayer: info.hasTextLayer,
312
+ },
313
+ notes: [
314
+ ...info.notes,
315
+ info.hasTextLayer ? "文字层可用:先用 text 取参数页,再按需 render 看图。" : "文字层不可用:直接 render 去看图。",
316
+ ],
317
+ };
318
+ }
319
+ if (mode === "text") {
320
+ const first = Math.max(1, Math.floor(args.first ?? 1));
321
+ const last = Math.min(first + 19, Math.max(first, Math.floor(args.last ?? first)));
322
+ const text = await extractPdfText(ctx.subprocess, located.tools, file, { first, last }, exec.signal);
323
+ if (!text.ok)
324
+ return { ...base, error: text.error };
325
+ return { ...base, ok: true, pages: text.pages, notes: text.notes };
326
+ }
327
+ if (mode === "table") {
328
+ const first = Math.max(1, Math.floor(args.first ?? 1));
329
+ const last = Math.min(first + 4, Math.max(first, Math.floor(args.last ?? first)));
330
+ const result = await extractPdfTables(ctx.subprocess, located.tools, file, { first, last }, exec.signal);
331
+ if (!result.ok)
332
+ return { ...base, error: result.error };
333
+ return { ...base, ok: true, tables: result.tables, notes: result.notes };
334
+ }
335
+ if (mode === "figures") {
336
+ const first = Math.max(1, Math.floor(args.first ?? 1));
337
+ const last = Math.max(first, Math.floor(args.last ?? Math.min(first + 29, 40)));
338
+ const whole = await extractPdfText(ctx.subprocess, located.tools, file, { first, last }, exec.signal);
339
+ if (!whole.ok)
340
+ return { ...base, error: whole.error };
341
+ const joined = whole.pages.map((page) => page.text).join("\n");
342
+ const figures = listFigures(joined, 60);
343
+ return {
344
+ ...base,
345
+ ok: true,
346
+ figures,
347
+ notes: [
348
+ "第 " + String(first) + "–" + String(last) + " 页里找到 " + String(figures.length) + " 条图注;目录页会给出页号,正文图注只有标题。",
349
+ figures.length === 0 ? "这一段没有图注行:换个页范围,或直接 render 该页看。" : "用 render 打开带页号的那一页,即可读图。",
350
+ ],
351
+ };
352
+ }
353
+ if (mode === "schematic") {
354
+ const firstPage = Math.max(1, Math.floor(args.first ?? 1));
355
+ const lastPage = Math.max(firstPage, Math.floor(args.last ?? firstPage));
356
+ const result = await readPdfSchematic(ctx.subprocess, located.tools, file, { first: firstPage, last: lastPage }, exec.signal);
357
+ if (!result.ok)
358
+ return { ...base, error: result.error, notes: result.notes };
359
+ return {
360
+ ...base,
361
+ ok: true,
362
+ schematic: {
363
+ pages: result.pages,
364
+ words: result.words,
365
+ components: result.components,
366
+ labels: result.labels,
367
+ notes: result.notes,
368
+ },
369
+ notes: result.notes,
370
+ };
371
+ }
372
+ if (mode === "curve") {
373
+ const page = Math.max(1, Math.floor(args.page ?? 1));
374
+ const result = await readPdfCurves(ctx.subprocess, located.tools, file, {
375
+ page,
376
+ dpi: args.dpi ?? 200,
377
+ signal: exec.signal,
378
+ });
379
+ if (!result.ok)
380
+ return { ...base, error: result.error };
381
+ return {
382
+ ...base,
383
+ ok: true,
384
+ imageFile: result.imageFile,
385
+ dpi: result.dpi,
386
+ curves: {
387
+ page: result.page,
388
+ series: result.series.map((item) => ({
389
+ hue: item.hue,
390
+ color: item.color,
391
+ pixels: item.pixels,
392
+ points: item.points,
393
+ })),
394
+ yTicks: (result.calibration?.y.ticks ?? []).map((tick) => tick.value),
395
+ xTicks: (result.calibration?.x.ticks ?? []).map((tick) => tick.value),
396
+ },
397
+ notes: [
398
+ ...result.notes,
399
+ "序列按色相命名(图上没有可直接读取的图例文字):先用 render 看一眼确认哪种颜色是哪条线。",
400
+ "刻度由页面上最近的一列/一行数字拟合,若同页有多张图,page 要指定到那一页。",
401
+ ],
402
+ };
403
+ }
404
+ const page = Math.max(1, Math.floor(args.page ?? 1));
405
+ const render = await renderPdfPage(ctx.subprocess, located.tools, file, { page, dpi: args.dpi ?? 150, ...(args.crop === undefined ? {} : { crop: args.crop }) }, exec.signal);
406
+ if (!render.ok)
407
+ return { ...base, error: render.error };
408
+ return {
409
+ ...base,
410
+ ok: true,
411
+ imageFile: render.imageFile,
412
+ imageWidth: render.width,
413
+ imageHeight: render.height,
414
+ dpi: render.dpi,
415
+ notes: [
416
+ ...render.notes,
417
+ "图像已落盘:" + extname(render.imageFile) + " 用 read_image 打开即可读图。",
418
+ "要抠数字就把 crop 收紧、dpi 提到 300–400;整页概览用 150–200。",
419
+ ],
420
+ };
421
+ },
422
+ });
423
+ }
@@ -12,6 +12,7 @@
12
12
  * 两条路线的门禁不同:HAL 路线要 CubeMX(capability=generate),
13
13
  * 寄存器路线仅需编译工具链(capability=build)——即"缺少 CubeMX 亦可用"的场景。
14
14
  */
15
+ import { dirname, resolve } from "node:path";
15
16
  import { ensureAssets } from "../engine/assets.js";
16
17
  import { createProjectScaffold, preflightTarget } from "../engine/scaffold.js";
17
18
  import { createRegisterProject } from "../engine/register-template.js";
@@ -21,6 +22,7 @@ import { generationRiskNotes } from "../engine/facts.js";
21
22
  import { ensureFacts } from "../engine/facts-acquire.js";
22
23
  import { liveProbeChoice } from "../engine/doctor.js";
23
24
  import { validateToolArgs } from "./project-dir.js";
25
+ import { registerWorkspaceProject, writeProjectConf } from "../engine/project-conf.js";
24
26
  export const PROJECT_CREATE_TOOL = "stm32_project_create";
25
27
  const reportSchema = {
26
28
  type: "object",
@@ -114,6 +116,30 @@ function normalizeRoute(value) {
114
116
  return "register";
115
117
  return null;
116
118
  }
119
+ /**
120
+ * 建完工程把描述写下来(S82):工程根一份 `dsh-stm32.conf`,工作区根再登记一条。
121
+ *
122
+ * 只在成功时写;写失败只影响面板的工程选择器,不回滚已建好的工程。
123
+ */
124
+ function recordProjectConf(report) {
125
+ if (!report.ok)
126
+ return;
127
+ const dir = report.targetDir;
128
+ if (dir.trim() === "")
129
+ return;
130
+ const written = writeProjectConf(dir, {
131
+ name: report.projectName ?? "",
132
+ mcu: report.mcu ?? "",
133
+ ioc: report.iocPath ?? "",
134
+ build: "Debug",
135
+ });
136
+ if (!written)
137
+ return;
138
+ // 工作区根取工程目录的上一级:用户建工程时给的就是工作区里的一个子目录。
139
+ const parent = dirname(resolve(dir));
140
+ if (parent !== resolve(dir))
141
+ registerWorkspaceProject(parent, dir);
142
+ }
117
143
  export function registerProjectCreate(ctx) {
118
144
  ctx.tools.register({
119
145
  name: PROJECT_CREATE_TOOL,
@@ -308,6 +334,7 @@ export function registerProjectCreate(ctx) {
308
334
  for (const n of generationRiskNotes(normalized.mcu))
309
335
  normalized.warnings.push(n);
310
336
  }
337
+ recordProjectConf(normalized);
311
338
  return { message: normalized.message, report: normalized };
312
339
  }
313
340
  const config = resolveSearchConfig(process.env, args.cubeMxRoots === undefined ? {} : { cubeMxRoots: args.cubeMxRoots });
@@ -352,6 +379,7 @@ export function registerProjectCreate(ctx) {
352
379
  halReport.warnings.push(n);
353
380
  }
354
381
  }
382
+ recordProjectConf(halReport);
355
383
  return { message: halReport.message, report: halReport };
356
384
  },
357
385
  });
@@ -11,6 +11,9 @@
11
11
  * 序列化时直接抛 "returned invalid output: value is not lossless JSON",真正原因被淹没。入口先
12
12
  * 校验,缺参数就回一句中文说明,报告字段一律填默认值。
13
13
  */
14
+ import { noteSessionAgent } from "../engine/session-context.js";
15
+ import { rememberWorkspace } from "../engine/workspace-memo.js";
16
+ import { resolveProjectLayout } from "../engine/project-layout.js";
14
17
  function usableDir(value) {
15
18
  if (typeof value !== "string")
16
19
  return null;
@@ -23,15 +26,21 @@ function usableDir(value) {
23
26
  * 顺序:显式 projectDir → 宿主 workingDirectory 服务(会话工作目录)→ 插件进程 cwd(并警告)。
24
27
  */
25
28
  export async function resolveProjectDir(ctx, explicit, exec) {
29
+ // 工具层是唯一稳定带着 agent 的地方:按 agent.id 记一份,Web API 才能按会话查到工作目录(S91)。
30
+ const agentId = typeof exec?.agent?.id === "string" ? exec.agent.id : "";
31
+ noteSessionAgent(agentId, exec?.agent);
26
32
  const given = usableDir(explicit);
27
- if (given !== null)
33
+ if (given !== null) {
34
+ rememberWorkspace(given);
28
35
  return { projectDir: given, note: null, fallbackToProcessCwd: false };
36
+ }
29
37
  let failure = null;
30
38
  const service = typeof ctx.get === "function" ? ctx.get("workingDirectory") : undefined;
31
39
  if (service !== undefined && typeof service.ensure === "function") {
32
40
  try {
33
41
  const sessionDir = usableDir(await service.ensure(exec?.agent, exec?.signal));
34
42
  if (sessionDir !== null) {
43
+ rememberWorkspace(sessionDir);
35
44
  return {
36
45
  projectDir: sessionDir,
37
46
  note: "工程目录缺省取会话工作目录:" + sessionDir,
@@ -55,6 +64,21 @@ export async function resolveProjectDir(ctx, explicit, exec) {
55
64
  fallbackToProcessCwd: true,
56
65
  };
57
66
  }
67
+ /**
68
+ * 程序目录(S95/S96):工程根按约定可能只放 `program/`、`hardware/` 与 `.dsh-stm32/`,
69
+ * 固件相关的工具(构建、烧录、生成、`.ioc`、调试)要作用在程序目录上,而不是工程根。
70
+ *
71
+ * 解析不出程序目录时退回工程根,保持老工程的行为不变。
72
+ */
73
+ export async function resolveFirmwareDir(ctx, explicit, exec) {
74
+ const root = await resolveProjectDir(ctx, explicit, exec);
75
+ const layout = resolveProjectLayout(root.projectDir);
76
+ const firmware = layout.firmwareDir === "" ? root.projectDir : layout.firmwareDir;
77
+ if (firmware === root.projectDir)
78
+ return root;
79
+ const note = root.note === null ? "程序目录:" + firmware : root.note + ";程序目录:" + firmware;
80
+ return { projectDir: firmware, note, fallbackToProcessCwd: root.fallbackToProcessCwd };
81
+ }
58
82
  function isBlank(value) {
59
83
  return typeof value === "string" && value.trim() === "";
60
84
  }
package/lib/tools/regs.js CHANGED
@@ -18,7 +18,7 @@ import { ensureSession, readWordsViaSession } from "../engine/probe-session.js";
18
18
  import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
19
19
  import { readIocCpn } from "../engine/breakpoints.js";
20
20
  import { SVD_FULL_PROFILE_HINT, SVD_KNOWN_LINES, SvdError, decodeRegisterValue, describeAddress, formatAddress, loadSvd, parseAddressText, resolveRegisterRef, svdLineForChip, } from "../data/svd.js";
21
- import { resolveProjectDir, validateToolArgs } from "./project-dir.js";
21
+ import { resolveFirmwareDir, validateToolArgs } from "./project-dir.js";
22
22
  export const REGS_TOOL = "stm32_regs_read";
23
23
  /** 只给外设名时一次最多 dump 多少个寄存器(GPIOC 这种寄存器少的根本到不了上限,RCC 也就几十个)。 */
24
24
  export const REG_DUMP_MAX = 64;
@@ -456,7 +456,7 @@ export function registerRegsRead(ctx) {
456
456
  if (invalid !== null) {
457
457
  return { message: invalid, report: failureReport(typeof args.projectDir === "string" ? args.projectDir : "", invalid, [invalid]) };
458
458
  }
459
- const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
459
+ const resolution = await resolveFirmwareDir(ctx, args.projectDir, exec);
460
460
  // D2:先把符号名/外设名解析成地址(零成本、不占探针)。解析不了就直接失败——
461
461
  // 没解析清楚就去借探针,等于白占一次硬件。
462
462
  const svd = resolveProjectSvd(resolution.projectDir);
@@ -19,7 +19,7 @@ import { findIocFile } from "../engine/generate.js";
19
19
  import { summarizeIoc } from "../engine/ioc.js";
20
20
  import { assessRoute, familyOf, findFirmwarePackage, } from "../engine/route-plan.js";
21
21
  import { ensureToolchain } from "../engine/toolchain-gate.js";
22
- import { resolveProjectDir } from "./project-dir.js";
22
+ import { resolveFirmwareDir } from "./project-dir.js";
23
23
  export const ROUTE_PLAN_TOOL = "stm32_route_plan";
24
24
  /** CubeMX 会在 .ioc 中写入这三条虚拟条目,其并非外设,不能作为"已使能"的证据。 */
25
25
  const VIRTUAL_IOC_IPS = new Set(["nvic", "rcc", "sys"]);
@@ -351,7 +351,7 @@ export function registerRoutePlan(ctx) {
351
351
  return emptyValue("requirement 必填:一句话说清要做什么,例如「按键控制 LED,串口每秒打印一次状态」。"
352
352
  + "只有把要用的外设说出来,才能判断 HAL 与寄存器哪条划算。");
353
353
  }
354
- const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
354
+ const resolution = await resolveFirmwareDir(ctx, args.projectDir, exec);
355
355
  const projectDir = resolution.projectDir;
356
356
  const notes = [];
357
357
  if (resolution.note !== null)
package/lib/tools/rtt.js CHANGED
@@ -16,7 +16,8 @@ import { PROBE_ERROR_SCHEMA } from "../engine/probe-error.js";
16
16
  import { isPortBusy } from "../engine/debug.js";
17
17
  import { ensureSession, release, sessionInfo } from "../engine/probe-session.js";
18
18
  import { ensureToolchain, gateReportNotes } from "../engine/toolchain-gate.js";
19
- import { resolveProjectDir, validateToolArgs } from "./project-dir.js";
19
+ import { resolveFirmwareDir, validateToolArgs } from "./project-dir.js";
20
+ import { emitChannel } from "../engine/channels.js";
20
21
  export const RTT_TOOL = "stm32_rtt";
21
22
  /**
22
23
  * RTT 自己起的调试会话的 startedAt(复用的会话不记)。
@@ -234,7 +235,7 @@ export function registerRtt(ctx) {
234
235
  async execute(rawArgs, exec) {
235
236
  const args = (rawArgs ?? {});
236
237
  const action = typeof args.action === "string" ? args.action.trim() : "";
237
- const resolution = await resolveProjectDir(ctx, readString(args.projectDir), exec);
238
+ const resolution = await resolveFirmwareDir(ctx, readString(args.projectDir), exec);
238
239
  const projectDir = resolution.projectDir;
239
240
  const notes = resolution.note === null ? [] : [resolution.note];
240
241
  if (!ACTIONS.includes(action)) {
@@ -425,6 +426,13 @@ export function registerRtt(ctx) {
425
426
  snapshotInto(report, rttStatus());
426
427
  report.port = dumped.port;
427
428
  report.addr = dumped.addr === "" ? report.addr : dumped.addr;
429
+ if (dumped.ok && dumped.records.length > 0) {
430
+ emitChannel({
431
+ channel: "rtt",
432
+ lines: dumped.records.map((record) => "[" + String(record.level) + "] " + record.text),
433
+ meta: { action },
434
+ });
435
+ }
428
436
  if (dumped.probeError !== null)
429
437
  report.probeError = dumped.probeError;
430
438
  return { message: dumped.message, report };