@huaqiu/dsh-tool-kicad-schematic-gen 0.6.8 → 0.6.9

package/README.md

@@ -4,6 +4,8 @@
 
 One installable plugin containing twelve tools and the kicad-schematic-design skill. Internal modules preserve the former component-library, module-catalog and schematic-tool contracts. Component search is provided by the KiCad built-in plugin @huaqiu/dsh-tool-part-search and its search_hqsch_parts tool.
 
+布局交付：简单项目默认首版、一次集中修复、验证并交付；首版达标可直接交付。额外修复必须有具体阻塞缺陷，真实错误不受轮数限制。不为装饰偏好或清零保守警告重复重建。流程和验收条件见 [布局修复与交付停止条件](skills/kicad-schematic-design/references/layout-delivery.md)，启动器摘要返回 nextAction 提示，不自动宣称方案或电气验证通过。
+
 Configuration is grouped under components, modules.search, modules.download and schematic. Templates ship under skills/kicad-schematic-design; the public scripting API is available at ./builder. Module downloads resolve the current HQ Edge host at execution time, so a missing host does not prevent other tools or the skill from loading.
 
 Imports remain workspace scoped and use DSH sandbox policy. Model inspection reports pin/pad summaries; paired import checks unique pin/pad number sets, but does not verify electrical suitability or package dimensions. Placement and routing are explicitly authored in design scripts. Datasheet extraction preserves missing/truncated status.
@@ -18,6 +20,10 @@ Power symbols: declare actual shared nets with the builder's `requiredPowerSymbo
 
 Standalone common-only symbols with pins (e.g. SW-PTB-2_0_1) are automatically normalized in project copies to unit 1 without changing pins or graphics. Model summaries and import results report builderCompatibility.normalization=common_only_to_unit_1. Inherited, empty, malformed or alternate-only definitions are not normalized. Unsupported imports report part, symbol, sections and source URL.
 
-最终概览卡片：正式预览传入 `delivery: true` 和包含全部本地库的 `projectDir`，显示页面切换、缩放、ZIP 下载。复用已有 PNG，不重新生成电路，无重新生成/详情按钮。需 KiCad Harness 的 webServer 与前端加载支持；不可用时仍返回本地预览路径。快照保存在插件 `.overview-cache/`，重启后可读取；移除该目录后历史卡片下载将失效。ZIP 为工程目录内相关设计文件与库的快照，不收集脚本、预览或外部库。
+最终概览卡片：正式预览传入 `delivery: true` 和包含全部本地库的 `projectDir`，待本轮正常完成后，在最终回复后的轮次尾部显示页面切换、缩放、ZIP 下载；工具执行期间不展示正式卡片。正式概览必须是本轮最后一个工具操作，之后调用其他工具或普通预览时须重新正式交付；失败、取消、中断的轮次不显示正式卡片。卡片从所属轮次的工具记录恢复，切换会话无需全局缓存。复用已有 PNG，不重新生成电路，无重新生成/详情按钮。需 KiCad Harness 的 webServer、conversation.chat.turnTail 和 useChat（ChatSnapshot 的 locations/nodes）支持；不可用时仍返回本地预览路径。快照保存在插件 `.overview-cache/`，重启后可读取；移除该目录后历史卡片下载将失效。ZIP 为工程目录内相关设计文件与库的快照，不收集脚本、预览或外部库。
 
 Module analysis queries use `analyze_kicad_module({schematicPath, view, reference?, pin?, net?, offset?, kicadCliPath?})`, with explicit `view`. Downloads already return a summary: query only needed components, grouped nets or grouped BOM. CLI/project options are resolved internally; optional absolute `kicadCliPath` is for recovery using the existing `get_eda_host_info` result. On `CLI_START_FAILED`, retry analysis with that path and `view:summary`, without downloading again. Successful paths are reused; default CLI command names preserve automatic discovery. Probe errors return `error:{code,executable}` and retain causes; capability failures are distinct from startup failures. Matching same-stem projects and downloaded `.source.kicad_pro` files are discovered. Detail output contains `status`, `items`, and optional `nextOffset`/`warnings`; missing `nextOffset` means completion. Component custom fields require a reference filter. Partial results are reused for detail queries; after fixing configuration use `view:summary` to retry. Full local artifacts are preserved. This replaces the previous analysis query arguments and response contract; existing callers must migrate. See [module analysis](skills/kicad-schematic-design/references/module-analysis.md).
+
+方案先行：先保存硬件方案，用 `scripts/run-design.mjs --read-plan <方案.md>` 读回，再按文档编写脚本。运行时必须传 `--plan <path> --plan-sha256 <sha256>`；构建库直接调用也要求 `designPlan:{path,sha256}`。平铺 create 与层次生成工具同样检查方案。缺失、空文档或版本变化时阻止生成；只读模块分析和预览不受影响。构建报告保存方案全文、方案 hash 和脚本 hash。此检查保证文件和版本前置，不代替方案电气完整性及文图一致性审查。
+
+电气栅格：默认 50 mil（1.27 mm）。构建器吸附器件放置、导线坐标、标签和模块平移量；`gridPoint/snapGrid` 可用于脚本规划。引脚库必须兼容同一格点，原理图生成与正式交付检查实际引脚及连接点，偏离时阻止交付。已有工程需从脚本重新构建，不通过独立舍入引脚/连线修补。

package/lib/builder.d.ts

@@ -180,6 +180,17 @@ interface PowerPlanningOptions extends Pick<PowerLabelSpec, 'libraryPath' | 'net
   maxMoveMm?: number;
 }
 //#endregion
+//#region src/schematic/design-plan.d.ts
+interface DesignPlanReference {
+  path: string;
+  sha256: string;
+}
+interface DesignPlan extends DesignPlanReference {
+  text: string;
+}
+declare function readDesignPlan(path: string): DesignPlan;
+declare function loadDesignPlan(input?: DesignPlanReference): DesignPlan;
+//#endregion
 //#region src/schematic/builder.d.ts
 /** Explicit instance placement in millimetres; library files must be trusted project inputs. */
 interface SymbolPlacement {
@@ -200,6 +211,8 @@ interface SymbolPlacement {
 }
 /** Explicit deployment templates and page choice; no implicit file discovery. */
 interface SchematicOptions {
+  /** Saved plan version reviewed before generation; runner supplies this via environment. */
+  designPlan?: DesignPlanReference;
   projectName: string;
   templateDir: string;
   paper: 'A4' | 'A3' | 'A2' | 'A1' | 'A0';
@@ -312,6 +325,7 @@ declare class Schematic {
   private readonly objectModules;
   private readonly requiredPowerSymbols;
   private readonly templates;
+  private readonly designPlan;
   /** Load validated templates. @param options Project identity, page and template directory. */
   constructor(options: SchematicOptions);
   /** Reserve a non-overlapping fixed module frame before placing its circuit.
@@ -419,6 +433,7 @@ declare class Schematic {
     projectPath: string;
     frames: ResolvedFlatFrame[];
     layoutWarnings: PowerLayoutWarning[];
+    designPlan: DesignPlanReference;
   };
 }
 //#endregion
@@ -483,4 +498,10 @@ declare function attachPinLabels(target: LabelTarget, spec: {
   })[];
 };
 //#endregion
-export { ModuleRegion, ModuleRegionSpec, PowerLabelEntry, PowerLabelReplacement, PowerLabelSpec, PowerLayoutWarning, type PowerPlacementPlan, type PowerPlanningOptions, PowerSymbolStatus, Schematic, SchematicOptions, SymbolPlacement, attachPinLabel, attachPinLabels, resolveKiCadPaths };
+//#region src/schematic/grid.d.ts
+/** Electrical schematic coordinates use KiCad's 50 mil connection grid. */
+declare const SCHEMATIC_GRID_MM = 1.27;
+declare function snapGrid(n: number): number;
+declare function gridPoint(p: readonly number[]): [number, number];
+//#endregion
+export { ModuleRegion, ModuleRegionSpec, PowerLabelEntry, PowerLabelReplacement, PowerLabelSpec, PowerLayoutWarning, type PowerPlacementPlan, type PowerPlanningOptions, PowerSymbolStatus, SCHEMATIC_GRID_MM, Schematic, SchematicOptions, SymbolPlacement, attachPinLabel, attachPinLabels, gridPoint, loadDesignPlan, readDesignPlan, resolveKiCadPaths, snapGrid };

package/lib/builder.js

@@ -1,4 +1,4 @@
-import { C as resolveKiCadPaths, _ as children, a as flatTextSize, b as required, c as validatePreviewSchematic, f as alignVendorSymbolIds, g as applyEdits, h as normalizeCommonUnits, l as assignFootprintText, n as listFlatObjects, r as loadFlatTemplates, t as buildFlatCopy, v as parse, x as value, y as quote } from "./flat--E2zWV_r.js";
+import { A as required, D as children, E as applyEdits, N as resolveKiCadPaths, O as parse, S as alignVendorSymbolIds, T as normalizeCommonUnits, a as snapGrid, c as loadDesignPlan, d as buildFlatCopy, f as listFlatObjects, h as flatTextSize, i as onGrid, j as value, k as quote, n as SCHEMATIC_GRID_MM, p as loadFlatTemplates, r as gridPoint, t as assertSchematicGrid, u as readDesignPlan, v as validatePreviewSchematic, y as assignFootprintText } from "./grid-check-BgWU7a8j.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -402,7 +402,7 @@ var ModuleRegion = class {
 };
 function point(at) {
 	if (at.length !== 2 || at.some((n) => !Number.isFinite(n))) throw new Error("coordinates require two finite millimetre values");
-	return at;
+	return gridPoint(at);
 }
 function definition(source, name, chain = []) {
 	const root = parse(source);
@@ -549,9 +549,19 @@ var Schematic = class Schematic {
 	objectModules = /* @__PURE__ */ new Map();
 	requiredPowerSymbols;
 	templates;
+	designPlan;
 	/** Load validated templates. @param options Project identity, page and template directory. */
 	constructor(options) {
 		this.options = options;
+		const { path, sha256 } = loadDesignPlan(options.designPlan);
+		if (options.designPlan && process.env.DSH_DESIGN_BRIEF_PATH) {
+			const runnerPlan = loadDesignPlan();
+			if (path !== runnerPlan.path || sha256 !== runnerPlan.sha256) throw new Error("DESIGN_PLAN_MISMATCH: script and runner must use the same saved plan version");
+		}
+		this.designPlan = {
+			path,
+			sha256
+		};
 		if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(options.projectName)) throw new Error("projectName must be an ASCII filename without an extension");
 		if (![
 			"A4",
@@ -606,9 +616,14 @@ var Schematic = class Schematic {
 	* @returns Reference map, translated label anchors, net names and object UUIDs for frames.
 	*/
 	importModule(spec) {
+		spec = {
+			...spec,
+			offset: gridPoint(spec.offset)
+		};
 		if (this.importedModules.has(spec.name)) throw new Error(`duplicate imported module: ${spec.name}`);
 		const used = new Set([...this.references.keys()].map((key) => key.slice(0, key.lastIndexOf(":"))));
 		const sourceText = readFileSync(spec.sourcePath, "utf8");
+		assertSchematicGrid(sourceText);
 		const prepared = prepareFlatImport(sourceText, spec, this.options.projectName, this.rootId, used);
 		const footprints = {};
 		if (spec.footprintMappingPath) {
@@ -656,6 +671,14 @@ var Schematic = class Schematic {
 		const symbolName = spec.libId.slice(separator + 1);
 		const raw = normalizeCommonUnits(definition(readFileSync(spec.libraryPath, "utf8"), symbolName)), form = parse(raw);
 		const sections = children(form, "symbol");
+		for (const section of sections) {
+			const suffix = /_(\d+)_(\d+)$/u.exec(value(section));
+			if (!suffix || ![0, unit].includes(Number(suffix[1])) || ![0, 1].includes(Number(suffix[2]))) continue;
+			for (const pin of children(section, "pin")) {
+				const at = children(pin, "at")[0];
+				if (!at || ![Number(value(at, 1)), Number(value(at, 2))].every(onGrid)) throw new Error(`SYMBOL_PIN_OFF_GRID: ${spec.libId} pin ${value(children(pin, "number")[0])} requires a 50 mil (1.27 mm) compatible library symbol. Do not round pin geometry independently of the circuit.`);
+			}
+		}
 		if (!sections.some((s) => {
 			const m = /_(\d+)_(\d+)$/u.exec(value(s));
 			return m && Number(m[1]) === unit && [0, 1].includes(Number(m[2]));
@@ -741,7 +764,8 @@ var Schematic = class Schematic {
 			this.endpoint(from),
 			...via.map(point),
 			this.endpoint(to)
-		];
+		].filter((p, i, all) => i === 0 || p[0] !== all[i - 1][0] || p[1] !== all[i - 1][1]);
+		if (points.length < 2) throw new Error("wire collapses on the 50 mil (1.27 mm) grid; increase the lead length");
 		const segments = [], ids = [];
 		for (let i = 1; i < points.length; i++) {
 			const a = points[i - 1], b = points[i];
@@ -1004,7 +1028,9 @@ var Schematic = class Schematic {
 	* @returns Schematic text, project JSON text, resolved frames and edit counts.
 	*/
 	render() {
+		loadDesignPlan(this.designPlan);
 		this.checkPowerSymbols();
+		assertSchematicGrid(this.source());
 		if (!this.instances.length) throw new Error("place at least one symbol before rendering");
 		return buildFlatCopy(this.source(), this.options.projectName, {
 			removeReferences: [],
@@ -1030,7 +1056,8 @@ var Schematic = class Schematic {
 			schematicPath,
 			projectPath,
 			frames: result.resolvedFrames,
-			layoutWarnings: this.powerLayoutWarnings()
+			layoutWarnings: this.powerLayoutWarnings(),
+			designPlan: { ...this.designPlan }
 		};
 	}
 };
@@ -1131,4 +1158,4 @@ function attachPinLabels(target, spec) {
 	};
 }
 //#endregion
-export { ModuleRegion, Schematic, attachPinLabel, attachPinLabels, resolveKiCadPaths };
+export { ModuleRegion, SCHEMATIC_GRID_MM, Schematic, attachPinLabel, attachPinLabels, gridPoint, loadDesignPlan, readDesignPlan, resolveKiCadPaths, snapGrid };

package/lib/client.js

@@ -47,6 +47,32 @@
 		}
 	}
 	//#endregion
+	//#region src/client/turn-overview.ts
+	const NO_OVERVIEW = { kind: "review" };
+	/** Read only this completed turn's persisted tool nodes; no global/session cache or DOM timing. */
+	function overviewForTurn(turn, chat) {
+		if (turn?.status !== "closed" || turn.end?.data.reason.kind !== "completed" || !chat) return NO_OVERVIEW;
+		const calls = [];
+		const visited = /* @__PURE__ */ new Set();
+		function walk(value, depth = 0) {
+			if (!value || typeof value !== "object" || visited.has(value) || depth > 64) return;
+			visited.add(value);
+			const block = value;
+			if (block.kind === "tool-result" && !block.subCalls?.length && typeof block.seq === "number") calls.push({
+				seq: block.seq,
+				block,
+				name: block.call?.name
+			});
+			if (Array.isArray(block.subCalls)) for (const child of block.subCalls) walk(child, depth + 1);
+		}
+		for (const key of chat.locations.getTurn(turn.turn)) {
+			const node = chat.nodes.get(key);
+			if (node?.kind === "tool-call") walk(node.data?.root);
+		}
+		const latest = calls.sort((a, b) => a.seq - b.seq).at(-1);
+		return latest?.name === "render_kicad_module_preview" ? parseCard(latest.block) : NO_OVERVIEW;
+	}
+	//#endregion
 	//#region src/client/place.ts
 	function placementHost(get) {
 		try {
@@ -71,18 +97,6 @@
 		if (result?.ok === false) throw new Error(result.message ?? "编辑器拒绝放置。");
 	}
 	//#endregion
-	//#region src/client/latest-overview.ts
-	/** Choose the newest mounted snapshot for each session/project; never compare titles. */
-	function supersededOverviews(rows) {
-		const latest = /* @__PURE__ */ new Map();
-		rows.forEach((row, index) => {
-			if (!row.session || !row.project) return;
-			const key = JSON.stringify([row.session, row.project]), previous = latest.get(key);
-			if (previous === void 0 || row.createdAt >= rows[previous].createdAt) latest.set(key, index);
-		});
-		return rows.map((row, index) => !!row.session && !!row.project && latest.get(JSON.stringify([row.session, row.project])) !== index);
-	}
-	//#endregion
 	//#region ../dsh-sidebar-entry/lib/index.mjs
 	/** Find the sidebar shell root element, or undefined while not yet mounted. */
 	function sidebarRoot() {
@@ -262,11 +276,11 @@
 	* family row means adding its selector here (and to no plugin-local list).
 	*/
 	const HUAQIU_SIDEBAR_ENTRY_FAMILY = [
-		"[data-hq-plugin-update-entry]",
 		"[data-hqcg-footprint-entry]",
 		"[data-hqcg-symbol-entry]",
 		"[data-hqcg-schematic-entry]",
-		"[data-hq-dummy-entry]"
+		"[data-hq-dummy-entry]",
+		"[data-hq-plugin-update-entry]"
 	];
 	/**
 	* Read the host UI language from `<html lang>`.
@@ -1057,52 +1071,14 @@
 	}
 	//#endregion
 	//#region src/client/index.ts
-	/** Harness compacts finished tool calls; keep only our delivery card visible. */
-	function keepDeliveryVisible() {
-		if (typeof document === "undefined" || typeof MutationObserver === "undefined") return () => {};
-		let frame = 0, disposed = false;
-		const reveal = () => {
-			frame = 0;
-			if (disposed) return;
-			const cards = Array.from(document.querySelectorAll(".dsh-local-overview"));
-			const hidden = supersededOverviews(cards.map((card) => ({
-				session: card.dataset.overviewSession ?? "",
-				project: card.dataset.overviewProject ?? "",
-				createdAt: Number(card.dataset.overviewCreated ?? 0)
-			})));
-			for (const [index, card] of cards.entries()) {
-				if (card.hidden !== hidden[index]) card.hidden = hidden[index];
-				if (hidden[index]) continue;
-				let parent = card.parentElement;
-				while (parent) {
-					if (parent.hasAttribute("data-turn-process-hidden")) parent.removeAttribute("hidden");
-					parent = parent.parentElement;
-				}
-			}
-		};
-		const observer = new MutationObserver(() => {
-			if (!frame) frame = requestAnimationFrame(reveal);
-		});
-		observer.observe(document.documentElement, {
-			subtree: true,
-			childList: true,
-			attributes: true,
-			attributeFilter: ["hidden", "data-turn-process-hidden"]
-		});
-		reveal();
-		return () => {
-			disposed = true;
-			observer.disconnect();
-			if (frame) cancelAnimationFrame(frame);
-		};
-	}
 	window.__ModuleLoader__.load({
 		id: "@huaqiu/dsh-tool-kicad-schematic-gen",
 		factory: (require) => {
 			const { createElement: h, useState, useEffect } = require("react");
 			let getHost;
 			function Card(props) {
-				const state = parseCard(props.block), result = state.result;
+				const chat = props.useChat?.((snapshot) => snapshot);
+				const state = chat ? overviewForTurn(props.turn, chat) : NO_OVERVIEW, result = state.result;
 				const [page, setPage] = useState(0), [zoom, setZoom] = useState(1), [message, setMessage] = useState(""), [busy, setBusy] = useState(false);
 				useEffect(() => {
 					setPage(0);
@@ -1247,7 +1223,6 @@
 				inject: ["slots", "inputTriggers"],
 				apply: (ctx) => {
 					getHost = () => ctx.get?.("hqEdge");
-					const stopVisibility = keepDeliveryVisible();
 					const source = registerSchematicGenSourceWhenReady(() => ctx.get?.("inputTriggers"));
 					try {
 						console.debug("[schematic-gen:client] apply", {
@@ -1283,12 +1258,12 @@
 					try {
 						console.debug("[schematic-gen:client] sidebar row", { rows: document.querySelectorAll("[data-hqcg-schematic-entry]").length });
 					} catch {}
-					const dispose = ctx.slots.inject("tool.call.toolview", () => ctx.slots.register({
-						name: "tool.call.toolview",
-						key: "render_kicad_module_preview"
+					const dispose = ctx.slots.inject("conversation.chat.turnTail", () => ctx.slots.register({
+						name: "conversation.chat.turnTail",
+						id: "huaqiu-schematic-overview",
+						order: 100
 					}, Card));
 					ctx.effect?.(() => () => {
-						stopVisibility();
 						source.dispose();
 						stopEntry();
 						if (typeof dispose === "function") dispose();

package/lib/{flat--E2zWV_r.js → grid-check-BgWU7a8j.js}

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { delimiter, dirname, join } from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 //#region src/runtime-paths.ts
 const isDefaultCommand = (value) => !value || /^kicad-cli(?:\.exe)?$/i.test(value.trim());
 /** Explicit paths override discovery; default command names still discover the host and PATH. */
@@ -602,7 +602,8 @@ function buildProject(edited, projectName, sheetName, expectedPorts, drivenInput
 			schematic: {
 				legacy_lib_dir: "",
 				legacy_lib_list: [],
-				...imported.schematic
+				...imported.schematic,
+				connection_grid_size: 50
 			},
 			sheets: [],
 			text_variables: {},
@@ -1504,4 +1505,108 @@ function buildFlatCopy(source, projectName, plan, templates) {
 	};
 }
 //#endregion
-export { resolveKiCadPaths as C, getKiCadPaths as S, children as _, flatTextSize as a, required as b, validatePreviewSchematic as c, footprintRequirements as d, alignVendorSymbolIds as f, applyEdits as g, normalizeCommonUnits as h, summarizeFlatLayout as i, assignFootprintText as l, isCommonOnlyUnit as m, listFlatObjects as n, PreviewError as o, buildProject as p, loadFlatTemplates as r, previewExportError as s, buildFlatCopy as t, auditFootprints as u, parse as v, value as x, quote as y };
+//#region src/schematic/design-plan.ts
+/** Required, version-bound design document input for schematic generation. */
+const DESIGN_PLAN_MAX_BYTES = 1048576;
+function designPlanReference(input) {
+	const plan = input;
+	if (!plan || typeof plan.path !== "string" || !plan.path.trim() || typeof plan.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(plan.sha256)) throw new Error("DESIGN_PLAN_REQUIRED: save the hardware design document, read it with run-design.mjs --read-plan <path>, then supply designPlan:{path,sha256}. Do not generate first and write the document afterwards.");
+	return {
+		path: plan.path,
+		sha256: plan.sha256
+	};
+}
+/** Structural check only; the model must still review engineering completeness. */
+function inspectDesignPlan(path, text) {
+	if (Buffer.byteLength(text, "utf8") > 1048576 || text.trim().length < 200 || !/^#\s+\S/m.test(text) || !/^##\s+\S/m.test(text)) throw new Error("DESIGN_PLAN_INCOMPLETE: provide a saved Markdown hardware plan with a title, substantive sections, and at least 200 characters. Review requirements, parts, circuits, connections and budgets before generation.");
+	return {
+		path,
+		sha256: createHash("sha256").update(text).digest("hex"),
+		text
+	};
+}
+function matchDesignPlan(reference, text) {
+	const plan = inspectDesignPlan(reference.path, text);
+	if (plan.sha256 !== reference.sha256) throw new Error("DESIGN_PLAN_CHANGED: the document changed after it was read. Read the latest document and update the design script/connection plan before rebuilding with its new sha256.");
+	return plan;
+}
+function readDesignPlan(path) {
+	try {
+		const canonical = realpathSync(path), info = statSync(canonical);
+		if (!info.isFile() || info.size > 1048576) throw new Error("expected a document file no larger than 1 MiB");
+		return inspectDesignPlan(canonical, new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(canonical)));
+	} catch (error) {
+		throw new Error(`DESIGN_PLAN_UNAVAILABLE: ${path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+}
+function loadDesignPlan(input) {
+	const reference = designPlanReference(input ?? {
+		path: process.env.DSH_DESIGN_BRIEF_PATH,
+		sha256: process.env.DSH_DESIGN_BRIEF_SHA256
+	});
+	const plan = readDesignPlan(reference.path);
+	return matchDesignPlan({
+		...reference,
+		path: plan.path
+	}, plan.text);
+}
+//#endregion
+//#region src/schematic/grid.ts
+/** Electrical schematic coordinates use KiCad's 50 mil connection grid. */
+const SCHEMATIC_GRID_MM = 1.27;
+function snapGrid(n) {
+	if (!Number.isFinite(n)) throw new Error("GRID_COORDINATE_INVALID: expected finite millimetres");
+	return Number((Math.round(n / SCHEMATIC_GRID_MM) * SCHEMATIC_GRID_MM).toFixed(6));
+}
+function gridPoint(p) {
+	if (p.length !== 2) throw new Error("grid point requires two coordinates");
+	return [snapGrid(p[0]), snapGrid(p[1])];
+}
+function onGrid(n) {
+	return Number.isFinite(n) && Math.abs(n - snapGrid(n)) < 1e-6;
+}
+//#endregion
+//#region src/schematic/grid-check.ts
+/** Never round an existing circuit's wires and library pins independently: that can break nets. */
+function assertSchematicGrid(source) {
+	const failures = [];
+	const root = parse(source), sheets = children(root, "sheet");
+	const check = (name, p) => {
+		if (!p.every(onGrid) && failures.length < 16) failures.push(`${name} (${p.join(", ")})`);
+	};
+	const flat = applyEdits(source, sheets.map((sheet) => ({
+		start: sheet.start,
+		end: sheet.end,
+		text: ""
+	})));
+	for (const object of listFlatObjects(flat)) if (object.type === "symbol") {
+		if (object.pinError) throw new Error(`GRID_PIN_UNRESOLVED: ${object.reference}: ${object.pinError}`);
+		if (object.at) check(object.reference ?? "symbol", object.at);
+		for (const pin of object.pins ?? []) check(`${object.reference}.${pin.number}`, pin.at);
+	} else if (["wire", "bus"].includes(object.type)) {
+		if (object.from) check(`${object.type} start`, object.from);
+		if (object.to) check(`${object.type} end`, object.to);
+	} else if ([
+		"label",
+		"global_label",
+		"hierarchical_label",
+		"junction",
+		"no_connect"
+	].includes(object.type) && object.at) check(object.type, object.at);
+	for (const sheet of sheets) {
+		for (const at of children(sheet, "at")) check("sheet", [Number(value(at, 1)), Number(value(at, 2))]);
+		for (const pin of children(sheet, "pin")) for (const at of children(pin, "at")) check(`sheet pin ${value(pin)}`, [Number(value(at, 1)), Number(value(at, 2))]);
+	}
+	for (const kind of ["wire", "bus"]) for (const wire of children(root, kind)) for (const pts of children(wire, "pts")) for (const xy of children(pts, "xy")) check(kind, [Number(value(xy, 1)), Number(value(xy, 2))]);
+	for (const entry of children(root, "bus_entry")) {
+		const at = children(entry, "at")[0], size = children(entry, "size")[0];
+		if (at && size) {
+			const x = Number(value(at, 1)), y = Number(value(at, 2));
+			check("bus entry", [x, y]);
+			check("bus entry end", [x + Number(value(size, 1)), y + Number(value(size, 2))]);
+		}
+	}
+	if (failures.length) throw new Error(`SCHEMATIC_OFF_GRID: expected 50 mil (1.27 mm). ${failures.join("; ")}. Fix source placement/routing or select a 50 mil compatible symbol; do not round library pins and connected wires separately.`);
+}
+//#endregion
+export { required as A, buildProject as C, children as D, applyEdits as E, getKiCadPaths as M, resolveKiCadPaths as N, parse as O, alignVendorSymbolIds as S, normalizeCommonUnits as T, previewExportError as _, snapGrid as a, auditFootprints as b, loadDesignPlan as c, buildFlatCopy as d, listFlatObjects as f, PreviewError as g, flatTextSize as h, onGrid as i, value as j, quote as k, matchDesignPlan as l, summarizeFlatLayout as m, SCHEMATIC_GRID_MM as n, DESIGN_PLAN_MAX_BYTES as o, loadFlatTemplates as p, gridPoint as r, designPlanReference as s, assertSchematicGrid as t, readDesignPlan as u, validatePreviewSchematic as v, isCommonOnlyUnit as w, footprintRequirements as x, assignFootprintText as y };

package/lib/index.js

@@ -1,4 +1,4 @@
-import { S as getKiCadPaths, _ as children, b as required, c as validatePreviewSchematic, d as footprintRequirements, g as applyEdits, h as normalizeCommonUnits, i as summarizeFlatLayout, l as assignFootprintText, m as isCommonOnlyUnit, n as listFlatObjects, o as PreviewError, p as buildProject, r as loadFlatTemplates, s as previewExportError, t as buildFlatCopy, u as auditFootprints, v as parse, x as value, y as quote } from "./flat--E2zWV_r.js";
+import { A as required, C as buildProject, D as children, E as applyEdits, M as getKiCadPaths, O as parse, T as normalizeCommonUnits, _ as previewExportError, b as auditFootprints, d as buildFlatCopy, f as listFlatObjects, g as PreviewError, j as value, k as quote, l as matchDesignPlan, m as summarizeFlatLayout, o as DESIGN_PLAN_MAX_BYTES, p as loadFlatTemplates, r as gridPoint, s as designPlanReference, t as assertSchematicGrid, v as validatePreviewSchematic, w as isCommonOnlyUnit, x as footprintRequirements, y as assignFootprintText } from "./grid-check-BgWU7a8j.js";
 import { getLogger } from "@huaqiu/dsh-plugin-log";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readFileSync } from "node:fs";
@@ -5218,7 +5218,7 @@ function text(value, field, max = 300) {
 }
 function point(value, field) {
 	if (!Array.isArray(value) || value.length !== 2 || value.some((item) => typeof item !== "number" || !Number.isFinite(item) || Math.abs(item) > 2e3)) throw new Error(`${field} must be two finite coordinates in millimetres, each within +/-2000`);
-	return value;
+	return gridPoint(value);
 }
 function endpoint(value, field) {
 	if (Array.isArray(value)) return point(value, field);
@@ -5255,7 +5255,8 @@ function parseFlatRequest(args, listLimit) {
 		"setValues",
 		"setLabels",
 		"addWires",
-		"frames"
+		"frames",
+		"designPlan"
 	], "edit_kicad_flat_schematic");
 	const sourcePath = requiredString(input, "sourcePath");
 	if (input.action === "connections") {
@@ -5394,7 +5395,8 @@ function parseFlatRequest(args, listLimit) {
 		sourcePath,
 		targetDir: requiredString(input, "targetDir"),
 		projectName: requiredString(input, "projectName"),
-		plan
+		plan,
+		designPlan: designPlanReference(input.designPlan)
 	};
 }
 //#endregion
@@ -5646,6 +5648,30 @@ function previewConfig(config, kicadCliPath) {
 //#endregion
 //#region src/schematic/tools.ts
 /** Read, preview, and generate KiCad schematic copies through workspace-scoped DSH tools. */
+const designPlanSchema = {
+	type: "object",
+	description: "Required saved hardware design document and exact version returned by run-design.mjs --read-plan. Read and implement this plan before generation.",
+	additionalProperties: false,
+	properties: {
+		path: { type: "string" },
+		sha256: { type: "string" }
+	},
+	required: ["path", "sha256"]
+};
+/** Read the exact plan version through workspace policy before any generation writes. */
+async function readWorkspaceDesignPlan(fs, workspace, input, signal) {
+	const reference = designPlanReference(input);
+	const root = await fs.resolve(workspace, { signal }), target = await fs.resolve(reference.path, {
+		cwd: workspace,
+		signal
+	});
+	if (!fs.contains(root, target) || (await fs.stat(target, signal))?.type !== "file") throw new Error("DESIGN_PLAN_UNAVAILABLE: designPlan.path must be an existing document inside the workspace");
+	const text = new TextDecoder("utf-8", { fatal: true }).decode(await fs.readBytes(target, signal, DESIGN_PLAN_MAX_BYTES));
+	return matchDesignPlan({
+		...reference,
+		path: target.displayPath
+	}, text);
+}
 async function writeOutputs(fs, targets, policy, signal) {
 	const written = [];
 	for (const { target, content } of targets) {
@@ -6106,6 +6132,7 @@ function registerSchematicTools(ctx, config) {
 					});
 					for (const item of sources) {
 						const sheet = item.schematicPath === source.path ? source : await readWorkspaceSchematic(ctx.fs, workspace, item.schematicPath, config.maxSchematicBytes, exec.signal);
+						assertSchematicGrid(sheet.text);
 						const footprints = await auditFootprints(sheet.text, resolved.displayPath, ctx.fs, exec.signal);
 						if (footprints.status !== "ready") throw new Error(`FOOTPRINTS_UNRESOLVED: ${footprints.unresolved.length} of ${footprints.total} physical instances in ${item.schematicPath} lack project-local footprints. Run localize_kicad_module_footprints check/import and persist script mappings before delivery.`);
 					}
@@ -6155,6 +6182,7 @@ function registerSchematicTools(ctx, config) {
 			type: "object",
 			additionalProperties: false,
 			properties: {
+				designPlan: designPlanSchema,
 				projectName: {
 					type: "string",
 					description: "ASCII filename stem: letters, digits, underscores, and hyphens; starts with a letter."
@@ -6202,7 +6230,8 @@ function registerSchematicTools(ctx, config) {
 				"projectName",
 				"title",
 				"targetDir",
-				"sheets"
+				"sheets",
+				"designPlan"
 			]
 		},
 		output: {
@@ -6210,6 +6239,7 @@ function registerSchematicTools(ctx, config) {
 				type: "object",
 				additionalProperties: false,
 				properties: {
+					designPlan: designPlanSchema,
 					projectPath: { type: "string" },
 					rootPath: { type: "string" },
 					symbolLibraryPath: { type: "string" },
@@ -6276,7 +6306,8 @@ function registerSchematicTools(ctx, config) {
 				"projectName",
 				"title",
 				"targetDir",
-				"sheets"
+				"sheets",
+				"designPlan"
 			], "create_kicad_hierarchy");
 			const projectName = requiredString(input, "projectName", 64);
 			if (!/^[A-Za-z][A-Za-z0-9_-]*$/u.test(projectName)) throw new Error("projectName must start with an ASCII letter and contain only letters, digits, underscores, or hyphens");
@@ -6284,6 +6315,7 @@ function registerSchematicTools(ctx, config) {
 			const targetDir = requiredString(input, "targetDir");
 			if (!Array.isArray(input.sheets) || input.sheets.length < 1 || input.sheets.length > 9) throw new Error("sheets must contain 1 to 9 modules");
 			const workspace = workspaceRoot(exec.agent);
+			const designPlan = await readWorkspaceDesignPlan(ctx.fs, workspace, input.designPlan, exec.signal);
 			const workspacePath = await ctx.fs.resolve(workspace, { signal: exec.signal });
 			const directory = await ctx.fs.resolve(targetDir, {
 				cwd: workspace,
@@ -6311,8 +6343,14 @@ function registerSchematicTools(ctx, config) {
 				};
 			}));
 			const files = buildAssembly(projectName, title, sheets);
+			assertSchematicGrid(files.root);
+			for (const child of files.children) assertSchematicGrid(child.text);
 			const paths = await publishAssembly(ctx.fs, workspace, targetDir, projectName, files, void 0, exec.signal);
 			return {
+				designPlan: {
+					path: designPlan.path,
+					sha256: designPlan.sha256
+				},
 				projectPath: paths.projectPath,
 				rootPath: paths.rootPath,
 				symbolLibraryPath: paths.symbolLibraryPath,
@@ -6343,6 +6381,10 @@ function registerSchematicTools(ctx, config) {
 			type: "object",
 			additionalProperties: false,
 			properties: {
+				designPlan: {
+					...designPlanSchema,
+					description: "Required for action:create. Saved and reviewed hardware plan path and exact sha256 returned by run-design.mjs --read-plan. Not used for list/connections."
+				},
 				action: {
 					type: "string",
 					enum: [
@@ -6512,6 +6554,7 @@ function registerSchematicTools(ctx, config) {
 				type: "object",
 				additionalProperties: false,
 				properties: {
+					designPlan: designPlanSchema,
 					sha256: { type: "string" },
 					connection: { type: "object" },
 					status: { type: "string" },
@@ -6581,7 +6624,9 @@ function registerSchematicTools(ctx, config) {
 						nextAction: "Reuse the requested information; fetch nextOffset only if needed. Planning reads do not require an edited copy. Only when implementing edits, use these UUIDs/coordinates and prefer frames autoBounds:true. Image sizes are in mm; bounds describe layout, not electrical connectivity."
 					};
 				}
+				const designPlan = await readWorkspaceDesignPlan(ctx.fs, workspace, request.designPlan, exec.signal);
 				const files = buildFlatCopy(source.text, request.projectName, request.plan, flatTemplates);
+				assertSchematicGrid(files.schematic);
 				const directory = await ctx.fs.resolve(request.targetDir, {
 					cwd: workspace,
 					signal: exec.signal
@@ -6599,6 +6644,10 @@ function registerSchematicTools(ctx, config) {
 				}));
 				await writeOutputs(ctx.fs, targets, void 0, exec.signal);
 				return {
+					designPlan: {
+						path: designPlan.path,
+						sha256: designPlan.sha256
+					},
 					status: "created",
 					sourcePath: source.path,
 					schematicPath: targets[0].target.displayPath,
@@ -7450,9 +7499,12 @@ const SCHEMATIC_GEN_TOKEN = "@schematic-gen";
 function schematicGenSectionText() {
 	return [
 		`Schematic Gen: the ${SCHEMATIC_GEN_TOKEN} token in a user message is the Schematic Gen chip — the user explicitly chose it for that request. Produce the design with the \`kicad-schematic-design\` skill, which starts from the hardware design brief when none exists yet.`,
+		"For every new schematic project, first show the requirements summary, scope, key unknowns and recommended choices. Ask with ask_user_question and wait for an actual user reply BEFORE writing formal design documents or generation scripts. If the tool is unavailable, ask in chat and end the turn to wait. Silence, timeout, cancellation or a preselected option is not confirmation. Reuse an already confirmed requirements baseline for the same project; do not ask again unless core requirements change.",
+		"Before writing or running a schematic generation script, save the hardware design document and read it back with run-design.mjs --read-plan. Implement that document; pass its path and sha256 to generation. Never postpone the plan until after drawing. ",
 		"Never hand-write .kicad_sch files or KiCad project files yourself; go through the skill and its tools.",
 		"Use the user's own words as the design description — if they have not described the circuit yet, ask for the requirements instead of assuming them.",
-		"Follow-up messages in the same conversation continue that work without repeating the token."
+		"Follow-up messages in the same conversation continue that work without repeating the token.",
+		"For a simple schematic, plan layout before the first build, collect concrete readability defects and fix them together once, then verify and deliver. Stop layout edits when connections, grid, readability, page fit and project files meet the delivery criteria. Further iterations require an identified blocking defect; do not rebuild for cosmetic preferences or to drive conservative layout warnings to zero. Real errors must still be fixed, regardless of iteration count."
 	].join("\n");
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-tool-kicad-schematic-gen",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "KiCad 原理图设计：电路模块搜索、器件模型与手册、符号导入、编辑预览、脚本构建及设计技能",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,8 +32,8 @@
     "pdfjs-dist": "6.3.289",
     "sharp": "0.35.4",
     "undici": "^8.10.0",
-    "@huaqiu/dsh-plugin-log": "0.6.8",
-    "@huaqiu/dsh-sidebar-entry": "0.6.8"
+    "@huaqiu/dsh-plugin-log": "0.6.9",
+    "@huaqiu/dsh-sidebar-entry": "0.6.9"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",