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

package/README.md

@@ -4,13 +4,15 @@
 
 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.
 
 Build, typecheck and test from the repository workspace. Restart the KiCad assistant after replacing the old bundles. See [merge notes](../../docs/SCHEMATIC-MERGE.md).
 
-Paired import: `import_kicad_component({manufacturer_id, mpn, projectDir})` downloads a symbol and footprint, registers `sym-lib-table` and `fp-lib-table`, and returns `footprintId`. Place with `addSymbol({libraryPath, libId, footprint: footprintId, ...})`. Success requires both usable models and matching unique pin/pad number sets. Public tool arguments use required `manufacturer_id` and `mpn`, matching `@huaqiu/dsh-tool-part-search`; imports also accept optional `projectDir` (defaults to the workspace root). `mfgId` is retained only by the internal identity parser for legacy direct callers; schema-validated tool calls must use `manufacturer_id`. See the skill's [component and PCB reference](skills/kicad-schematic-design/references/component-pcb.md).
+Paired import: `import_kicad_component({manufacturer_id, mpn, projectDir})` downloads a symbol and footprint, registers `sym-lib-table` and `fp-lib-table`, and returns `footprintId`. Place with `addSymbol({libraryPath, libId, footprint: footprintId, ...})`. Success requires both usable models and matching unique pin/pad number sets. Public tool arguments use required `manufacturer_id` and `mpn`, matching `@huaqiu/dsh-tool-part-search`; imports also accept optional `projectDir` (defaults to the workspace root). The obsolete `mfgId` parameter is rejected; all callers must use `manufacturer_id`. See the skill's [component and PCB reference](skills/kicad-schematic-design/references/component-pcb.md).
 
 Power symbols: declare actual shared nets with the builder's `requiredPowerSymbols` option. `powerLabelCatalog(nets)` returns current-build label UUIDs, coordinates and imported-module names for reproducible placement. `checkPowerSymbols()` and render/save reject missing symbols or unconverted labels for declared nets. Layout warnings still require visual review. See [power-symbol delivery](skills/kicad-schematic-design/references/power-symbols.md).
 
@@ -18,6 +20,14 @@ 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）支持；不可用时仍返回本地预览路径。持久快照默认保存在当前用户家目录的 `.hq-edge/plugin-data/dsh-tool-kicad-schematic-gen/overview-cache/`，家目录通过 `os.homedir()` 动态获取；可用绝对路径 `HQ_EDGE_HOME` 覆盖 `.hq-edge` 根目录，不随 `DSH_HOME` 或插件版本变化。重启后可读取，手动删除快照后对应历史卡片下载将失效。工程、中间产物和预览保存在当前工作区；插件安装目录仅用于读取代码和模板，不读写概览快照。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` 可用于脚本规划。引脚库必须兼容同一格点，原理图生成与正式交付检查实际引脚及连接点，偏离时阻止交付。已有工程需从脚本重新构建，不通过独立舍入引脚/连线修补。
+
+候选预览与交付状态：普通 `render_kicad_module_preview` 可传 `projectDir`，在首版预览时校验全部页的本地封装，无需先复制库到候选目录。`footprintCheck` 返回逐页的实际解析结果，缺库时顶层 `status:error`，已渲染图片仍保留。`renderStatus` 单独表示渲染结果；`deliveryStatus` 为 `not_requested`、`ready` 或 `blocked`。正式交付失败不会返回整体成功；只有 `deliveryStatus:ready` 和有效概览才代表正式快照已创建，这仍不代表电气验证通过。
+
+技能加载时提供 `pluginDir`、`skillDir`、`runtimePath`、`runnerPath`、`geometryPath` 等只读资源绝对路径，避免混淆插件根目录与技能根目录。资源安装目录不用于保存项目输出。失败恢复、有限重试及候选检查顺序见技能的 `references/troubleshooting.md`。

package/README.zh.md

@@ -8,7 +8,7 @@
 | 电路模块搜索下载 | eda_module_rag_search、eda_module_category_search、eda_module_precise_search、download_eda_module_schematic |
 | 原理图工具 | get_kicad_module_ports、render_kicad_module_preview、create_kicad_hierarchy、edit_kicad_flat_schematic |
 
-同时注册 kicad-schematic-design 技能。元件搜索由KiCad 内置的 @huaqiu/dsh-tool-part-search 提供，调用 search_hqsch_parts。该搜索插件随 KiCad 提供，可在插件管理器中启用；原理图插件本身不注册它的四个查询工具。两者间将搜索结果的 manufacturer.id 映射为 manufacturer_id，mpn 保持不变；公开工具统一要求 manufacturer_id 和 mpn，不再暴露 mfgId；两个导入工具额外支持可选 projectDir，默认工作区根目录。内部身份解析保留旧调用兼容，经过工具 Schema 校验的调用必须使用 manufacturer_id。
+同时注册 kicad-schematic-design 技能。元件搜索由KiCad 内置的 @huaqiu/dsh-tool-part-search 提供，调用 search_hqsch_parts。该搜索插件随 KiCad 提供，可在插件管理器中启用；原理图插件本身不注册它的四个查询工具。两者间将搜索结果的 manufacturer.id 映射为 manufacturer_id，mpn 保持不变；公开工具统一要求 manufacturer_id 和 mpn，不再暴露 mfgId；两个导入工具额外支持可选 projectDir，默认工作区根目录。内部身份解析同样拒绝旧参数 mfgId，所有调用统一使用 manufacturer_id。
 
 配置分为 components、modules.search、modules.download、schematic，使用原配置的默认限额。flatTemplateDir 默认指向本包技能模板。Node 22.19+，KiCad 10 CLI 路径可通过 schematic.kicadCliPath 配置。
 
@@ -16,7 +16,7 @@
 
 公开脚本入口是 lib/builder.js 或包的 ./builder 导出。设计技能、资源与模板位于 skills/kicad-schematic-design/。
 
-新导入器件库默认保存到 `project/libraries/symbols/` 和 `project/libraries/footprints/`，库表保留在 project 根目录，使用 `${KIPRJMOD}` 相对路径注册。相同器件重复导入复用原文件；旧项目已有根目录库时保持兼容，不自动移动。脚本使用导入返回的实际 libraryPath 和 footprintId；概览 ZIP 会递归收集 libraries 下的器件库。
+新导入器件库默认保存到 `project/libraries/symbols/` 和 `project/libraries/footprints/`，库表保留在 project 根目录，使用 `${KIPRJMOD}` 相对路径注册。相同器件重复导入复用原文件；不再复用工程根目录中的旧库；同名库表仍指向旧目录时明确报冲突，不自动迁移或覆盖。脚本使用导入返回的实际 libraryPath 和 footprintId；概览 ZIP 会递归收集 libraries 下的器件库。
 
 复用模块的封装通过 `localize_kicad_module_footprints` 的 list/import/check 流程本地化。模块下载现在保留 ZIP 中的 `.kicad_mod` 并返回 footprints 列表；缺失时使用明确选择的 manufacturer_id/mpn 查询在线封装。原嵌入符号、引脚和布线不替换，编号集合不匹配时拒绝导入。映射存入 `libraries/mappings/`，在设计脚本中使用 `importModule({...,footprintMappingPath})` 持久应用；来源变化后旧映射会拒绝使用。正式 delivery 在生成概览前验证根图和子页的本地封装引用。映射和封装一并进入项目 ZIP；尺寸、电气功能及 3D 完整性仍需单独确认。已有工程不会在插件加载时自动选择或替换器件。
 
@@ -24,11 +24,11 @@ KiCad CLI 自动从当前运行时安装位置或 PATH 查找，也可通过 KIC
 
 路径发现由配置与 skill 共用缓存，环境变量变化后重新识别。模型已有 get_eda_host_info 返回结果时，可以把其中的 kicad-cli 绝对路径传给 render_kicad_module_preview 的可选 kicadCliPath；只影响当前调用，不修改默认配置。原理图文件生成和预览不要求 PCB IPC 诊断或 Python 路径查询。
 
-正式概览快照保存到当前 DSH_HOME/plugin-data/dsh-tool-kicad-schematic-gen/overview-cache；没有 DSH_HOME 时使用用户数据目录，不要求插件安装目录可写。快照完整写入后才发布，旧会话仍可读取插件目录中原有的 .overview-cache。不会自动删除历史快照；手动清理对应快照后，旧会话中的下载和放置操作将失效。
+正式概览快照默认保存到 `~/.hq-edge/plugin-data/dsh-tool-kicad-schematic-gen/overview-cache/`（`~` 为当前用户家目录，使用 `os.homedir()` 获取）；设置绝对路径 `HQ_EDGE_HOME` 时保存到该根目录下同一子目录。不会使用 `DSH_HOME`、`LOCALAPPDATA` 或插件安装目录作为新快照的默认存储位置。快照完整写入后才发布；不再兼容读取插件目录中的旧快照，相关旧会话卡片需重新生成正式概览。不会自动删除历史快照；手动清理对应快照后，旧会话中的下载和放置操作将失效。
 
-在工作区根目录执行 pnpm --filter @huaqiu/dsh-tool-kicad-schematic-gen build、typecheck 或 test。使用配套 DSH CLI 注册本目录，替换旧四个插件，并重新打开 KiCad AI 助手。历史备份和旧脚本兼容见 [合并说明](../../docs/SCHEMATIC-MERGE.md)。
+在工作区根目录执行 pnpm --filter @huaqiu/dsh-tool-kicad-schematic-gen build、typecheck 或 test。使用配套 DSH CLI 注册本目录，替换旧四个插件，并重新打开 KiCad AI 助手。旧脚本须更新为当前接口，不提供历史调用兼容。
 
-成套器件导入：`import_kicad_component({manufacturer_id, mpn, projectDir})` 同时下载符号与封装，登记两个项目库表，返回 `footprintId`。放置时传 `footprint: imported.footprintId`。两种实际模型可用且引脚/焊盘编号集合匹配才成功；仍需手册核对尺寸与功能。公开调用只使用 `manufacturer_id`，旧 `mfgId` 仅在内部解析层为历史直接调用保留。
+成套器件导入：`import_kicad_component({manufacturer_id, mpn, projectDir})` 同时下载符号与封装，登记两个项目库表，返回 `footprintId`。放置时传 `footprint: imported.footprintId`。两种实际模型可用且引脚/焊盘编号集合匹配才成功；仍需手册核对尺寸与功能。公开调用只使用 `manufacturer_id`，内部解析层同样拒绝旧 `mfgId` 参数。
 
 电源符号：在构建选项中声明实际共享网络 `requiredPowerSymbols`。`powerLabelCatalog(nets)` 返回本次标签 UUID、网络、坐标和导入模块名，按这些条件定位后生成 placements，不引用上一轮 UUID。`checkPowerSymbols()` 与 render/save 检查声明网络的标准符号和残留标签；未完成时拒绝保存。遮挡提示仍需局部预览确认，详见 [电源符号交付](skills/kicad-schematic-design/references/power-symbols.md)。
 
@@ -36,14 +36,18 @@ KiCad CLI 自动从当前运行时安装位置或 PATH 查找，也可通过 KIC
 
 含引脚的独立公共单元符号（如 SW-PTB-2_0_1）在项目副本中自动规范为单元 1，保留引脚与图形。模型摘要和导入结果通过 builderCompatibility.normalization=common_only_to_unit_1 报告；继承、空单元、异常命名及仅替代图形的符号不做自动规范。不支持的导入错误包含器件、符号、单元名称及源文件 URL。
 
-最终概览卡片：正式预览传入 `delivery: true` 和包含全部本地库的 `projectDir`，显示页面切换、缩放、ZIP 下载。复用已有 PNG，不重新生成电路，无重新生成/详情按钮。需 KiCad Harness 的 webServer 与前端加载支持；不可用时仍返回本地预览路径。快照保存在插件 `.overview-cache/`，重启后可读取；移除该目录后历史卡片下载将失效。ZIP 为工程目录内相关设计文件与库的快照，不收集脚本、预览或外部库。
+最终概览卡片：正式预览传入 `delivery: true` 和包含全部本地库的 `projectDir`，显示页面切换、缩放、ZIP 下载。复用已有 PNG，不重新生成电路，无重新生成/详情按钮。需 KiCad Harness 的 webServer 与前端加载支持；不可用时仍返回本地预览路径。持久快照默认保存在当前用户家目录的 `.hq-edge/plugin-data/dsh-tool-kicad-schematic-gen/overview-cache/`，家目录通过 `os.homedir()` 动态获取；可用绝对路径 `HQ_EDGE_HOME` 覆盖 `.hq-edge` 根目录，不随 `DSH_HOME` 或插件版本变化。重启后可读取，手动删除快照后对应历史卡片下载将失效。工程、中间产物和预览保存在当前工作区；插件安装目录仅用于读取代码和模板，不读写概览快照。ZIP 为工程目录内相关设计文件与库的快照，不收集脚本、预览或外部库。
 # 生成流程耗时优化
 
 - 模块封装 `import` 返回 `stage: prepared`，仅表示本地库和映射准备完成；源文件默认不改写。`check_mapping` 验证来源应用映射后的状态，`check` 检查实际候选或最终原理图，避免混淆。
 - 封装准备最多 4 并发；项目库表按项目串行写入。批次验证失败不写库，错误返回失败 assignment 索引；已验证下载在当前进程缓存 15 分钟（最多 128 项、16 MiB），退出进程后清空。瞬时网络/429/5xx 错误内部最多重试一次，格式和编号错误不自动重试。
-- 使用现有供应商符号缓存对齐逻辑读取模块，支持旧式 `(module ...)` 封装的焊盘元数据，不改写源封装。编号核对不等于尺寸或电气验证。
+- 使用现有供应商符号缓存对齐逻辑读取模块；封装仅支持当前 `(footprint ...)` 格式，旧式 `(module ...)` 明确拒绝，不自动转换。编号核对不等于尺寸或电气验证。
 - builder 新增 `attachPinLabel`，支持显式方向、引线长度与通道错列；不推断引脚方向或自动避障。
 - 技能目录 `scripts/run-design.mjs` 使用参数数组启动生成脚本，将退出码、执行时间和完整输出保存为 UTF-8 JSON；终端仅返回摘要，避免 PowerShell 转义、输出截断和 BOM 返工。模块封装准备提前进行，文档与脚本复用连接计划。
 
 
 模块分析查询：`analyze_kicad_module({schematicPath, view, reference?, pin?, net?, offset?, kicadCliPath?})`。`view` 必填；下载已给分析摘要，直接查询所需 `components`、`nets` 或 `bom`。CLI/源工程默认内部解析；路径或启动失败 `CLI_START_FAILED` 时，复用 `get_eda_host_info` 返回的 kicad-cli 绝对路径，通过可选 `kicadCliPath` + `view:summary` 直接重试分析，不重新下载。成功路径后续复用，默认命令名不会覆盖自动发现；探测失败返回 `error:{code,executable}` 并区分启动、能力不支持、超时和命令失败。任意本地图采用同名 `.kicad_pro`，下载模块重启后可识别同名 `.source.kicad_pro`。详情返回 `status`、`items`、可选 `nextOffset`/`warnings`；网络按组分块，BOM 按全部物料字段与装配状态合并，器件自定义字段在指定 `reference` 时返回。部分失败结果供详情查询复用，修复后用 `view:summary` 重试。缺失 `nextOffset` 表示结束；不可用数据会明确警告。完整本地分析文件仍保留，详见 [模块分析](skills/kicad-schematic-design/references/module-analysis.md)。此接口替换旧版分析查询参数及返回结构，旧调用需同步更新。
+
+候选预览与交付状态：普通 `render_kicad_module_preview` 可传 `projectDir`，在首版预览时校验全部页的本地封装，无需先复制库到候选目录。`footprintCheck` 返回逐页的实际解析结果，缺库时顶层 `status:error`，已渲染图片仍保留。`renderStatus` 单独表示渲染结果；`deliveryStatus` 为 `not_requested`、`ready` 或 `blocked`。正式交付失败不会返回整体成功；只有 `deliveryStatus:ready` 和有效概览才代表正式快照已创建，这仍不代表电气验证通过。
+
+技能加载时提供 `pluginDir`、`skillDir`、`runtimePath`、`runnerPath`、`geometryPath` 等只读资源绝对路径，避免混淆插件根目录与技能根目录。资源安装目录不用于保存项目输出。失败恢复、有限重试及候选检查顺序见技能的 `references/troubleshooting.md`。

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

@@ -19,6 +19,10 @@
 				message: String(o.overviewError),
 				formal: true
 			};
+			if (o.footprintCheck?.status === "blocked") return {
+				kind: "error",
+				message: String(o.footprintCheck.error || "工程本地封装检查未通过")
+			};
 			if (!v) return o.status === "error" ? {
 				kind: "error",
 				message: "未能生成预览"
@@ -47,6 +51,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 +101,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 +280,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 +1075,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 +1227,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 +1262,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 };