dsh-stm32 0.1.0 → 0.1.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.
Files changed (82) hide show
  1. package/README.md +127 -29
  2. package/README_EN.md +125 -29
  3. package/client/client.js +682 -0
  4. package/docs/development-notes.md +1385 -5
  5. package/docs/logic-audit.md +607 -0
  6. package/docs/reading-guide.md +738 -0
  7. package/lib/client.js +682 -0
  8. package/lib/commands/register.js +214 -12
  9. package/lib/data/chips.js +134 -4
  10. package/lib/data/clock-f1.js +158 -0
  11. package/lib/data/cmsis-sources.js +316 -0
  12. package/lib/data/f1-ram.generated.js +34 -0
  13. package/lib/data/firmware-packages.js +352 -0
  14. package/lib/data/install-guides.js +190 -0
  15. package/lib/data/search-roots.js +135 -15
  16. package/lib/data/stm32f1.js +186 -0
  17. package/lib/data/toolchain-config.js +310 -0
  18. package/lib/engine/build.js +121 -16
  19. package/lib/engine/cache.js +336 -0
  20. package/lib/engine/clock-plan.js +608 -0
  21. package/lib/engine/cmake-sources.js +428 -0
  22. package/lib/engine/code-patch.js +18 -6
  23. package/lib/engine/debug-session.js +163 -4
  24. package/lib/engine/debug.js +84 -19
  25. package/lib/engine/doctor.js +395 -4
  26. package/lib/engine/fetch.js +287 -0
  27. package/lib/engine/firmware-install.js +668 -0
  28. package/lib/engine/flash.js +145 -15
  29. package/lib/engine/fs-longpath.js +107 -0
  30. package/lib/engine/generate-cache.js +118 -0
  31. package/lib/engine/generate-script.js +30 -8
  32. package/lib/engine/generate.js +296 -14
  33. package/lib/engine/hal-chip.js +230 -0
  34. package/lib/engine/ioc-plan.js +47 -8
  35. package/lib/engine/msys2-install.js +1870 -0
  36. package/lib/engine/probe.js +57 -6
  37. package/lib/engine/project-export.js +129 -0
  38. package/lib/engine/register-clock.js +132 -0
  39. package/lib/engine/register-linker.js +129 -0
  40. package/lib/engine/register-template.js +449 -0
  41. package/lib/engine/regs.js +18 -4
  42. package/lib/engine/route-plan.js +553 -0
  43. package/lib/engine/scaffold.js +303 -72
  44. package/lib/engine/subprocess-runner.js +2 -0
  45. package/lib/engine/tar.js +250 -0
  46. package/lib/engine/text-file.js +150 -0
  47. package/lib/engine/thirdparty.js +243 -0
  48. package/lib/engine/tool-env.js +51 -0
  49. package/lib/engine/toolchain-gate.js +386 -0
  50. package/lib/engine/vscode-config.js +99 -0
  51. package/lib/engine/web-api.js +375 -0
  52. package/lib/engine/web-routes.js +100 -0
  53. package/lib/engine/xcube-catalog.js +102 -0
  54. package/lib/engine/xcube.js +254 -0
  55. package/lib/engine/zip.js +142 -0
  56. package/lib/index.js +44 -2
  57. package/lib/skill/stm32-workflow.js +3 -3
  58. package/lib/tools/build.js +55 -3
  59. package/lib/tools/cache.js +250 -0
  60. package/lib/tools/code-patch.js +29 -2
  61. package/lib/tools/debug-session.js +56 -14
  62. package/lib/tools/debug.js +43 -2
  63. package/lib/tools/doctor.js +16 -3
  64. package/lib/tools/env-install.js +472 -0
  65. package/lib/tools/env-probe.js +6 -2
  66. package/lib/tools/firmware-install.js +255 -0
  67. package/lib/tools/flash.js +41 -2
  68. package/lib/tools/generate.js +96 -10
  69. package/lib/tools/ioc-apply.js +27 -11
  70. package/lib/tools/ioc-inspect.js +4 -2
  71. package/lib/tools/ioc-plan.js +209 -11
  72. package/lib/tools/project-create.js +229 -21
  73. package/lib/tools/project-dir.js +95 -0
  74. package/lib/tools/project-export.js +100 -0
  75. package/lib/tools/regs.js +82 -7
  76. package/lib/tools/route-plan.js +467 -0
  77. package/package.json +11 -4
  78. package/templates/register/CMakeLists.txt +52 -0
  79. package/templates/register/Core/Src/main.c +72 -0
  80. package/templates/scaffold/openocd.cfg +8 -0
  81. package/templates/scaffold/vscode/launch.json +8 -6
  82. package/templates/scaffold/vscode/settings.json +5 -11
@@ -6,6 +6,7 @@
6
6
  * rollbackFrom 走回滚路径,把某次备份的 .ioc 写回去(写前再备份当前文件)。
7
7
  */
8
8
  import { applyIocPlan, rollbackIoc } from "../engine/ioc-plan.js";
9
+ import { resolveProjectDir } from "./project-dir.js";
9
10
  export const IOC_APPLY_TOOL = "stm32_ioc_apply";
10
11
  export const outputSchema = {
11
12
  type: "object",
@@ -18,6 +19,11 @@ export const outputSchema = {
18
19
  iocPath: { type: "string" },
19
20
  planId: { type: "string" },
20
21
  appliedChanges: { type: "number" },
22
+ /**
23
+ * 这一趟是不是回滚。为什么要单独一个字段:回滚不改配置,却和"应用了变更"共用一张报告,
24
+ * 只靠 mode 判断的话调用方很容易把回滚读成"改了 1 处"(审计 A18)。
25
+ */
26
+ rolledBack: { type: "boolean" },
21
27
  shaBefore: { type: "string" },
22
28
  shaAfter: { type: "string" },
23
29
  backupPath: { type: "string" },
@@ -26,7 +32,7 @@ export const outputSchema = {
26
32
  },
27
33
  required: [
28
34
  "message", "mode", "ok", "projectDir", "iocPath", "planId", "appliedChanges",
29
- "shaBefore", "shaAfter", "backupPath", "warnings", "notes",
35
+ "rolledBack", "shaBefore", "shaAfter", "backupPath", "warnings", "notes",
30
36
  ],
31
37
  };
32
38
  export function registerIocApply(ctx) {
@@ -52,6 +58,8 @@ export function registerIocApply(ctx) {
52
58
  if (typed.shaBefore !== "" && typed.shaAfter !== "") {
53
59
  lines.push("SHA-256:" + typed.shaBefore.slice(0, 16) + "… -> " + typed.shaAfter.slice(0, 16) + "…");
54
60
  }
61
+ if (typed.rolledBack)
62
+ lines.push("这是回滚:appliedChanges 记 0(回滚不是应用变更)。");
55
63
  if (typed.backupPath !== "")
56
64
  lines.push("备份:" + typed.backupPath);
57
65
  for (const note of typed.notes)
@@ -61,10 +69,15 @@ export function registerIocApply(ctx) {
61
69
  return [{ type: "text", text: lines.join("\n") }];
62
70
  },
63
71
  },
64
- async execute(rawArgs) {
65
- const projectDir = rawArgs.projectDir ?? process.cwd();
66
- if (rawArgs.rollbackFrom !== undefined && rawArgs.rollbackFrom !== "") {
67
- const rollback = rollbackIoc({ projectDir, backupFrom: rawArgs.rollbackFrom });
72
+ async execute(rawArgs, exec) {
73
+ // 宿主可能不传 arguments(工具无参数调用)→ rawArgs 是 undefined。
74
+ // 这里兜成 {} 而不是相信它一定有值:缺参数的正常表现应该是"报告说缺 planId",不是 TypeError(审计 A31)。
75
+ const args = rawArgs ?? {};
76
+ const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
77
+ const projectDir = resolution.projectDir;
78
+ const extraNotes = resolution.note === null ? [] : [resolution.note];
79
+ if (args.rollbackFrom !== undefined && args.rollbackFrom !== "") {
80
+ const rollback = rollbackIoc({ projectDir, backupFrom: args.rollbackFrom });
68
81
  return {
69
82
  message: rollback.message,
70
83
  mode: "rollback",
@@ -72,20 +85,22 @@ export function registerIocApply(ctx) {
72
85
  projectDir: rollback.projectDir,
73
86
  iocPath: rollback.iocPath,
74
87
  planId: "",
75
- appliedChanges: rollback.ok ? 1 : 0,
88
+ // 回滚没有"应用变更"这回事:原来记 rollback.ok ? 1 : 0 是拿数字编事实(审计 A18)。
89
+ appliedChanges: 0,
90
+ rolledBack: rollback.ok,
76
91
  shaBefore: rollback.shaBefore,
77
92
  shaAfter: rollback.shaAfter,
78
93
  backupPath: rollback.backupPath,
79
94
  warnings: [],
80
- notes: rollback.ok ? ["回滚后建议 stm32_generate 重新生成,让代码与 .ioc 一致"] : [],
95
+ notes: [...(rollback.ok ? ["回滚后建议 stm32_generate 重新生成,让代码与 .ioc 一致"] : []), ...extraNotes],
81
96
  };
82
97
  }
83
- const planId = rawArgs.planId ?? "";
98
+ const planId = args.planId ?? "";
84
99
  if (planId === "") {
85
100
  return {
86
101
  message: "没写入:必须带 planId(先 stm32_ioc_plan 拿到计划 ID);要回滚请用 rollbackFrom。",
87
- mode: "apply", ok: false, projectDir, iocPath: "", planId: "", appliedChanges: 0,
88
- shaBefore: "", shaAfter: "", backupPath: "", warnings: [], notes: [],
102
+ mode: "apply", ok: false, projectDir, iocPath: "", planId: "", appliedChanges: 0, rolledBack: false,
103
+ shaBefore: "", shaAfter: "", backupPath: "", warnings: [], notes: extraNotes,
89
104
  };
90
105
  }
91
106
  const applied = applyIocPlan({ projectDir, planId });
@@ -97,11 +112,12 @@ export function registerIocApply(ctx) {
97
112
  iocPath: applied.iocPath,
98
113
  planId: applied.planId,
99
114
  appliedChanges: applied.appliedChanges,
115
+ rolledBack: false,
100
116
  shaBefore: applied.shaBefore,
101
117
  shaAfter: applied.shaAfter,
102
118
  backupPath: applied.backupPath,
103
119
  warnings: applied.warnings,
104
- notes: applied.notes,
120
+ notes: [...applied.notes, ...extraNotes],
105
121
  };
106
122
  },
107
123
  });
@@ -9,6 +9,7 @@ import { readFileSync } from "node:fs";
9
9
  import { resolve } from "node:path";
10
10
  import { findIocFile } from "../engine/generate.js";
11
11
  import { summarizeIoc } from "../engine/ioc.js";
12
+ import { resolveProjectDir } from "./project-dir.js";
12
13
  export const IOC_INSPECT_TOOL = "stm32_ioc_inspect";
13
14
  const pinSchema = {
14
15
  type: "object",
@@ -181,9 +182,10 @@ export function registerIocInspect(ctx) {
181
182
  return [{ type: "text", text: formatValue(typed).join("\n") }];
182
183
  },
183
184
  },
184
- async execute(rawArgs, _exec) {
185
+ async execute(rawArgs, exec) {
185
186
  const args = rawArgs ?? {};
186
- const projectDir = args.projectDir ?? process.cwd();
187
+ const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
188
+ const projectDir = resolution.projectDir;
187
189
  const iocPath = args.iocPath === undefined ? findIocFile(projectDir) : resolve(projectDir, args.iocPath);
188
190
  if (iocPath === null) {
189
191
  return { found: false, path: "", message: "在 " + projectDir + " 里没找到唯一的 *.ioc,请用 iocPath 指定", warnings: [] };
@@ -3,8 +3,13 @@
3
3
  *
4
4
  * 返回 planId + 源文件 SHA-256 + 逐键 diff。确认之后必须调用 stm32_ioc_apply({ planId }),
5
5
  * apply 会核对源文件 SHA-256 是否还是 plan 时那份(期间你若用 CubeMX GUI 改过就会被拒绝)。
6
+ *
7
+ * 时钟(clock 入参)走同一个 plan:时钟就是 .ioc 里的一段键,单开工具会让"改引脚"和"改时钟"
8
+ * 变成两次 plan/apply,中间还可能留下 PLL 与 APB 分频不自洽的中间态。详见 engine/clock-plan.ts。
6
9
  */
7
10
  import { planIocChanges } from "../engine/ioc-plan.js";
11
+ import { formatHz } from "../engine/clock-plan.js";
12
+ import { resolveProjectDir } from "./project-dir.js";
8
13
  export const IOC_PLAN_TOOL = "stm32_ioc_plan";
9
14
  const changeSchema = {
10
15
  type: "object",
@@ -17,6 +22,129 @@ const changeSchema = {
17
22
  },
18
23
  required: ["key", "kind", "before", "after"],
19
24
  };
25
+ const clockRequestedSchema = {
26
+ type: "object",
27
+ additionalProperties: false,
28
+ properties: {
29
+ targetHz: { type: "number" },
30
+ pllSource: { type: "string" },
31
+ pllMul: { type: "number" },
32
+ apb1Div: { type: "number" },
33
+ apb2Div: { type: "number" },
34
+ adcDiv: { type: "number" },
35
+ },
36
+ required: ["targetHz", "pllSource", "pllMul", "apb1Div", "apb2Div", "adcDiv"],
37
+ };
38
+ const clockChainSchema = {
39
+ type: "object",
40
+ additionalProperties: false,
41
+ properties: {
42
+ pllSource: { type: "string" },
43
+ pllSourceLabel: { type: "string" },
44
+ pllInHz: { type: "number" },
45
+ pllMul: { type: "number" },
46
+ pllClkHz: { type: "number" },
47
+ sysclkHz: { type: "number" },
48
+ hclkHz: { type: "number" },
49
+ apb1Div: { type: "number" },
50
+ apb1Hz: { type: "number" },
51
+ apb1TimHz: { type: "number" },
52
+ apb2Div: { type: "number" },
53
+ apb2Hz: { type: "number" },
54
+ apb2TimHz: { type: "number" },
55
+ adcDiv: { type: "number" },
56
+ adcHz: { type: "number" },
57
+ usbHz: { type: "number" },
58
+ usbAvailable: { type: "boolean" },
59
+ usbPrescaled: { type: "boolean" },
60
+ mcoHz: { type: "number" },
61
+ },
62
+ required: [
63
+ "pllSource", "pllSourceLabel", "pllInHz", "pllMul", "pllClkHz", "sysclkHz", "hclkHz",
64
+ "apb1Div", "apb1Hz", "apb1TimHz", "apb2Div", "apb2Hz", "apb2TimHz", "adcDiv", "adcHz",
65
+ "usbHz", "usbAvailable", "usbPrescaled", "mcoHz",
66
+ ],
67
+ };
68
+ const clockAlternativeSchema = {
69
+ type: "object",
70
+ additionalProperties: false,
71
+ properties: {
72
+ sysclkHz: { type: "number" },
73
+ pllSource: { type: "string" },
74
+ pllSourceLabel: { type: "string" },
75
+ pllMul: { type: "number" },
76
+ apb1Div: { type: "number" },
77
+ adcDiv: { type: "number" },
78
+ usbAvailable: { type: "boolean" },
79
+ deltaHz: { type: "number" },
80
+ },
81
+ required: ["sysclkHz", "pllSource", "pllSourceLabel", "pllMul", "apb1Div", "adcDiv", "usbAvailable", "deltaHz"],
82
+ };
83
+ const clockPeripheralSchema = {
84
+ type: "object",
85
+ additionalProperties: false,
86
+ properties: {
87
+ id: { type: "string" },
88
+ label: { type: "string" },
89
+ bus: { type: "string" },
90
+ clockHz: { type: "number" },
91
+ note: { type: "string" },
92
+ },
93
+ required: ["id", "label", "bus", "clockHz", "note"],
94
+ };
95
+ const clockBaudRowSchema = {
96
+ type: "object",
97
+ additionalProperties: false,
98
+ properties: {
99
+ baud: { type: "number" },
100
+ brr: { type: "number" },
101
+ actualBaud: { type: "number" },
102
+ errorPercent: { type: "number" },
103
+ },
104
+ required: ["baud", "brr", "actualBaud", "errorPercent"],
105
+ };
106
+ const clockBaudTableSchema = {
107
+ type: "object",
108
+ additionalProperties: false,
109
+ properties: {
110
+ id: { type: "string" },
111
+ clockHz: { type: "number" },
112
+ worstBaud: { type: "number" },
113
+ worstErrorPercent: { type: "number" },
114
+ rows: { type: "array", items: clockBaudRowSchema },
115
+ },
116
+ required: ["id", "clockHz", "worstBaud", "worstErrorPercent", "rows"],
117
+ };
118
+ const clockEntrySchema = {
119
+ type: "object",
120
+ additionalProperties: false,
121
+ properties: { key: { type: "string" }, value: { type: "string" } },
122
+ required: ["key", "value"],
123
+ };
124
+ const clockPlanSchema = {
125
+ type: "object",
126
+ additionalProperties: false,
127
+ properties: {
128
+ mode: { type: "string", enum: ["snapshot", "nearest", "explicit", "none"] },
129
+ ok: { type: "boolean" },
130
+ reachable: { type: "boolean" },
131
+ deltaHz: { type: "number" },
132
+ note: { type: "string" },
133
+ requested: clockRequestedSchema,
134
+ achieved: clockChainSchema,
135
+ alternatives: { type: "array", items: clockAlternativeSchema },
136
+ peripherals: { type: "array", items: clockPeripheralSchema },
137
+ bauds: { type: "array", items: clockBaudTableSchema },
138
+ entries: { type: "array", items: clockEntrySchema },
139
+ unset: { type: "array", items: { type: "string" } },
140
+ warnings: { type: "array", items: { type: "string" } },
141
+ errors: { type: "array", items: { type: "string" } },
142
+ },
143
+ required: [
144
+ "mode", "ok", "reachable", "deltaHz", "note", "requested", "achieved", "alternatives",
145
+ "peripherals", "bauds", "entries", "unset", "warnings", "errors",
146
+ ],
147
+ };
20
148
  export const outputSchema = {
21
149
  type: "object",
22
150
  additionalProperties: false,
@@ -34,10 +162,11 @@ export const outputSchema = {
34
162
  notes: { type: "array", items: { type: "string" } },
35
163
  errors: { type: "array", items: { type: "string" } },
36
164
  nextStep: { type: "string" },
165
+ clockPlan: clockPlanSchema,
37
166
  },
38
167
  required: [
39
168
  "message", "ok", "projectDir", "iocPath", "planId", "sourceSha256", "candidateSha256",
40
- "changes", "pinsAfter", "warnings", "notes", "errors", "nextStep",
169
+ "changes", "pinsAfter", "warnings", "notes", "errors", "nextStep", "clockPlan",
41
170
  ],
42
171
  };
43
172
  /** 宿主不接受 null(声明为 string 的字段给 null 会被拒),所以"不存在"用空串表达。 */
@@ -49,7 +178,52 @@ function toViews(changes) {
49
178
  after: change.after ?? "",
50
179
  }));
51
180
  }
52
- function format(changes, message, warnings, errors, nextStep) {
181
+ /** 时钟段落:一行结论 + 总线/外设/波特率/备选,数字都从 clockPlan 里取,不重算。 */
182
+ function formatClock(plan) {
183
+ if (plan.mode === "none" && plan.achieved.sysclkHz === 0) {
184
+ return ["时钟:" + plan.note];
185
+ }
186
+ const chain = plan.achieved;
187
+ const lines = [];
188
+ lines.push("时钟:" + plan.note);
189
+ lines.push(" " + (plan.mode === "snapshot" ? "现状" : "结果") + ":SYSCLK " + formatHz(chain.sysclkHz) +
190
+ " / HCLK " + formatHz(chain.hclkHz) +
191
+ "(" + chain.pllSourceLabel + " ×" + String(chain.pllMul) + " = " + formatHz(chain.pllClkHz) + ")");
192
+ if (chain.sysclkHz > 0) {
193
+ lines.push(" 总线:APB1 " + formatHz(chain.apb1Hz) + "(÷" + String(chain.apb1Div) + ",定时器 " + formatHz(chain.apb1TimHz) + ")" +
194
+ " / APB2 " + formatHz(chain.apb2Hz) + "(÷" + String(chain.apb2Div) + ",定时器 " + formatHz(chain.apb2TimHz) + ")" +
195
+ " / ADC " + formatHz(chain.adcHz) + "(÷" + String(chain.adcDiv) + ")" +
196
+ " / USB " + (chain.usbAvailable ? formatHz(chain.usbHz) : "不可用") +
197
+ " / MCO " + formatHz(chain.mcoHz));
198
+ for (const bus of ["apb2", "apb1", "ahb"]) {
199
+ const rows = plan.peripherals.filter((item) => item.bus === bus);
200
+ if (rows.length === 0)
201
+ continue;
202
+ const parts = rows.map((item) => {
203
+ const tag = item.note.includes("未在 .ioc 启用") ? "(未启用)" : "";
204
+ const clock = item.id === "USB" && !chain.usbAvailable ? "—" : formatHz(item.clockHz);
205
+ return item.label + " " + clock + tag;
206
+ });
207
+ lines.push(" " + bus.toUpperCase() + " 外设:" + parts.join(" / "));
208
+ }
209
+ const baud = plan.bauds
210
+ .filter((table) => table.clockHz > 0 && table.rows.length > 0)
211
+ .map((table) => table.id + "@" + formatHz(table.clockHz) + " 最差 " + String(table.worstBaud) + " " +
212
+ (table.worstErrorPercent > 0 ? "+" : "") + table.worstErrorPercent.toFixed(3) + "%");
213
+ if (baud.length > 0)
214
+ lines.push(" 波特率误差(16 倍过采样,BRR=round(fCK/baud)):" + baud.join(" / "));
215
+ }
216
+ if (!plan.reachable && plan.alternatives.length > 0) {
217
+ const parts = plan.alternatives.map((item) => formatHz(item.sysclkHz) + "(差 " + (item.deltaHz >= 0 ? "+" : "-") + formatHz(Math.abs(item.deltaHz)) + ")");
218
+ lines.push(" 备选(按接近程度):" + parts.join(" / "));
219
+ }
220
+ if (plan.entries.length > 0) {
221
+ lines.push(" 写入 " + String(plan.entries.length) + " 个 RCC 键(含 RCC.IPParameters 合并);" +
222
+ (plan.unset.length > 0 ? "删除 " + plan.unset.join("、") + ";" : "") + "逐个值见上面的 diff。");
223
+ }
224
+ return lines;
225
+ }
226
+ function format(changes, message, warnings, errors, nextStep, clockPlan) {
53
227
  const lines = [message];
54
228
  for (const change of changes.slice(0, 40)) {
55
229
  if (change.kind === "added")
@@ -61,6 +235,7 @@ function format(changes, message, warnings, errors, nextStep) {
61
235
  }
62
236
  if (changes.length > 40)
63
237
  lines.push(" … 还有 " + String(changes.length - 40) + " 个键");
238
+ lines.push(...formatClock(clockPlan));
64
239
  for (const warning of warnings)
65
240
  lines.push("! " + warning);
66
241
  for (const error of errors.slice(0, 8))
@@ -72,7 +247,7 @@ function format(changes, message, warnings, errors, nextStep) {
72
247
  export function registerIocPlan(ctx) {
73
248
  ctx.tools.register({
74
249
  name: IOC_PLAN_TOOL,
75
- description: "改 STM32CubeMX .ioc 的第一步:只读源文件、算出逐键 diff 与源 SHA-256,返回 planId,不写盘。支持 entries(设键)/unset(删键)/pins(加 GPIO 引脚)/serialWire(补 Serial Wire 调试口)。确认 diff 之后必须用 stm32_ioc_apply({planId}) 才真正写入。",
250
+ description: "改 STM32CubeMX .ioc 的第一步:只读源文件、算出逐键 diff 与源 SHA-256,返回 planId,不写盘。支持 entries(设键)/unset(删键)/pins(加 GPIO 引脚)/serialWire(补 Serial Wire 调试口)/clock(改时钟:targetHz 就近或 pllMul 定点,自动重算整套 RCC 派生键并给逐外设频率与 UART 波特率误差)。确认 diff 之后必须用 stm32_ioc_apply({planId}) 才真正写入。",
76
251
  parameters: {
77
252
  type: "object",
78
253
  additionalProperties: false,
@@ -107,6 +282,21 @@ export function registerIocPlan(ctx) {
107
282
  },
108
283
  },
109
284
  serialWire: { type: "boolean", description: "确保 PA13/PA14 是 Serial Wire,并清掉 No_Debug(VP_SYS_VS_ND)残留。" },
285
+ clock: {
286
+ type: "object",
287
+ additionalProperties: false,
288
+ description: "改时钟:给 targetHz 就近取最接近的合法档(不可达时报告明写「不可达,已选 X MHz」),或给 pllMul 定点;只会重算 RCC 的派生键,不动引脚。",
289
+ properties: {
290
+ targetHz: { type: "number", description: "目标 SYSCLK(Hz),例如 60000000。" },
291
+ pllSource: { type: "string", enum: ["hse", "hsi-div2", "hsi"], description: "PLL 输入源;缺省按 .ioc 有没有配 HSE 晶振决定。" },
292
+ pllMul: { type: "number", minimum: 2, maximum: 16, description: "定点倍频 ×2..×16;给了就不再就近搜。" },
293
+ apb1Div: { type: "number", description: "APB1 分频 1/2/4/8/16;缺省取满足 APB1≤36 MHz 的最小分频。" },
294
+ apb2Div: { type: "number", description: "APB2 分频;缺省 1(降频只会拖慢外设)。" },
295
+ adcDiv: { type: "number", description: "ADC 预分频 2/4/6/8;缺省取满足 ADC≤14 MHz 的最小分频。" },
296
+ usb: { type: "boolean", description: "按「要用 USB」规划(写 RCC.USBPrescaler=÷1.5,只有 PLLCLK=72 MHz 才给得出 48 MHz)。" },
297
+ bauds: { type: "array", items: { type: "number" }, description: "要算整除误差的波特率档,缺省 9600…230400。" },
298
+ },
299
+ },
110
300
  },
111
301
  },
112
302
  timeoutMs: 30_000,
@@ -115,18 +305,25 @@ export function registerIocPlan(ctx) {
115
305
  schema: outputSchema,
116
306
  render: (_args, value) => {
117
307
  const typed = value;
118
- return [{ type: "text", text: format(typed.changes, typed.message, typed.warnings, typed.errors, typed.nextStep).join("\n") }];
308
+ return [{ type: "text", text: format(typed.changes, typed.message, typed.warnings, typed.errors, typed.nextStep, typed.clockPlan).join("\n") }];
119
309
  },
120
310
  },
121
- async execute(rawArgs) {
311
+ async execute(rawArgs, exec) {
312
+ // 宿主可能不传 arguments(无参数调用)→ 兜成 {}:缺参数要表现成"报告说没事可做",
313
+ // 而不是 rawArgs.projectDir 上的 TypeError(审计 A31)。
314
+ const args = rawArgs ?? {};
315
+ const resolution = await resolveProjectDir(ctx, args.projectDir, exec);
122
316
  const report = planIocChanges({
123
- projectDir: rawArgs.projectDir ?? process.cwd(),
124
- ...(rawArgs.iocPath === undefined ? {} : { iocPath: rawArgs.iocPath }),
125
- ...(rawArgs.entries === undefined ? {} : { entries: rawArgs.entries }),
126
- ...(rawArgs.unset === undefined ? {} : { unset: rawArgs.unset }),
127
- ...(rawArgs.pins === undefined ? {} : { pins: rawArgs.pins }),
128
- ...(rawArgs.serialWire === undefined ? {} : { serialWire: rawArgs.serialWire }),
317
+ projectDir: resolution.projectDir,
318
+ ...(args.iocPath === undefined ? {} : { iocPath: args.iocPath }),
319
+ ...(args.entries === undefined ? {} : { entries: args.entries }),
320
+ ...(args.unset === undefined ? {} : { unset: args.unset }),
321
+ ...(args.pins === undefined ? {} : { pins: args.pins }),
322
+ ...(args.serialWire === undefined ? {} : { serialWire: args.serialWire }),
323
+ ...(args.clock === undefined ? {} : { clock: args.clock }),
129
324
  });
325
+ if (resolution.note !== null)
326
+ report.notes.push(resolution.note);
130
327
  const changes = toViews(report.changes);
131
328
  const nextStep = report.ok
132
329
  ? "确认无误后:stm32_ioc_apply({ projectDir: \"" + report.projectDir.replace(/\\/gu, "/") + "\", planId: \"" + report.planId + "\" }),然后 stm32_generate 重新生成代码。"
@@ -145,6 +342,7 @@ export function registerIocPlan(ctx) {
145
342
  notes: report.notes,
146
343
  errors: report.errors,
147
344
  nextStep,
345
+ clockPlan: report.clockPlan,
148
346
  };
149
347
  },
150
348
  });