@huaqiu/dsh-kicad 0.4.2

package/skills/kicad-ipc/scripts/kipy_common.py

@@ -0,0 +1,80 @@
+"""Shared helpers for the KiCad IPC CRUD script templates.
+
+Run the sibling scripts with the Python environment that contains the official
+``kicad-python`` package.  This module deliberately has no pcbnew fallback.
+"""
+
+from __future__ import annotations
+
+from kipy import KiCad
+from kipy.board_types import BoardLayer
+
+
+def connect_board(timeout_ms: int = 5000):
+    """Return a checked KiCad connection and the currently open PCB board."""
+    kicad = KiCad(timeout_ms=timeout_ms)
+
+    if not kicad.check_version():
+        raise RuntimeError(
+            "kicad-python 与已连接 KiCad 的 API 版本不匹配；请使用匹配的官方包。"
+        )
+
+    board = kicad.get_board()
+    if board is None:
+        raise RuntimeError("没有打开的 PCB；请先在 PCB Editor 中打开 .kicad_pcb。")
+
+    return kicad, board
+
+
+def close_kicad(kicad) -> None:
+    """Close newer clients without breaking KiCad 10 / kicad-python 0.8 clients."""
+    close = getattr(kicad, "close", None)
+    if callable(close):
+        close()
+
+
+def get_required_net(board, name: str):
+    """Resolve an existing board net by exact name; never invent a replacement."""
+    for net in board.get_nets():
+        if net.name == name:
+            return net
+    raise ValueError(f"PCB 中不存在网络 {name!r}；请先从原理图同步网络。")
+
+
+def resolve_copper_layer(board, name: str):
+    """Resolve a current-board copper layer, with a safe F.Cu/B.Cu legacy fallback."""
+    if hasattr(board, "get_layer_by_name"):
+        layer = board.get_layer_by_name(name)
+        if layer != BoardLayer.BL_UNDEFINED:
+            if layer in board.get_enabled_layers():
+                return layer
+            raise ValueError(f"层 {name!r} 未在当前 PCB 中启用。")
+
+    standard_layers = {
+        "F.Cu": BoardLayer.BL_F_Cu,
+        "B.Cu": BoardLayer.BL_B_Cu,
+    }
+    try:
+        layer = standard_layers[name]
+    except KeyError as exc:
+        raise ValueError(
+            f"无法在此 KiCad 版本解析层 {name!r}；请使用 F.Cu/B.Cu 或升级。"
+        ) from exc
+
+    if hasattr(board, "get_enabled_layers") and layer not in board.get_enabled_layers():
+        raise ValueError(f"层 {name!r} 未在当前 PCB 中启用。")
+    return layer
+
+
+def commit_or_drop(board, message: str, operation, validate=None):
+    """Run an operation and optional result check in one KiCad undo transaction."""
+    commit = board.begin_commit()
+    try:
+        result = operation()
+        if validate is not None:
+            validate(result)
+        board.push_commit(commit, message)
+        return result
+    except Exception:
+        board.drop_commit(commit)
+        raise

package/skills/kicad-ipc/scripts/move_rotate_footprint.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Move and/or rotate one existing footprint via KiCad IPC."""
+
+from __future__ import annotations
+
+import argparse
+
+from kipy.geometry import Angle, Vector2
+
+from kipy_common import close_kicad, commit_or_drop, connect_board
+
+
+def get_footprint(board, reference: str):
+    matches = [
+        footprint
+        for footprint in board.get_footprints()
+        if footprint.reference_field.text.value == reference
+    ]
+    if len(matches) != 1:
+        raise RuntimeError(f"reference {reference!r} 匹配到 {len(matches)} 个封装；未做修改。")
+    return matches[0]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reference", required=True, help="目标封装 reference，例如 R1")
+    parser.add_argument("--dx-mm", type=float, default=0.0, help="X 位移，单位 mm")
+    parser.add_argument("--dy-mm", type=float, default=0.0, help="Y 位移，单位 mm")
+    parser.add_argument("--rotation-deg", type=float, default=0.0, help="增量旋转角度，单位度")
+    parser.add_argument("--save", action="store_true", help="验证成功后通过 IPC 保存 PCB")
+    args = parser.parse_args()
+    if args.dx_mm == 0 and args.dy_mm == 0 and args.rotation_deg == 0:
+        parser.error("至少指定一个位移或旋转参数")
+
+    kicad, board = connect_board()
+    try:
+        footprint = get_footprint(board, args.reference)
+        old_position = footprint.position
+        old_orientation = footprint.orientation
+        footprint.position += Vector2.from_xy_mm(args.dx_mm, args.dy_mm)
+        footprint.orientation += Angle.from_degrees(args.rotation_deg)
+
+        def validate(updated):
+            if len(updated) != 1:
+                raise RuntimeError("KiCad 未更新恰好一个封装。")
+            if updated[0].position == old_position and updated[0].orientation == old_orientation:
+                raise RuntimeError("KiCad 没有应用封装变换。")
+
+        updated, = commit_or_drop(
+            board,
+            f"Move/rotate footprint {args.reference}",
+            lambda: board.update_items(footprint),
+            validate,
+        )
+        print(f"已更新 {args.reference}: position={updated.position}, orientation={updated.orientation}")
+        if args.save:
+            board.save()
+            print("已通过 IPC 保存 PCB。")
+    finally:
+        close_kicad(kicad)
+
+
+if __name__ == "__main__":
+    main()

package/skills/kicad-ipc/scripts/refill_zones.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Fill existing copper zones on the open PCB via KiCad IPC."""
+
+from __future__ import annotations
+
+import argparse
+
+from kipy_common import close_kicad, connect_board
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--save", action="store_true", help="填充完成后通过 IPC 保存 PCB")
+    args = parser.parse_args()
+
+    kicad, board = connect_board(timeout_ms=30000)
+    try:
+        zones = list(board.get_zones())
+        if not zones:
+            print("当前 PCB 没有区域，无需填充。")
+            return
+
+        board.refill_zones(block=True, max_poll_seconds=120.0)
+        print(f"已请求并等待 {len(zones)} 个区域填充完成。")
+        if args.save:
+            board.save()
+            print("已通过 IPC 保存 PCB。")
+    finally:
+        close_kicad(kicad)
+
+
+if __name__ == "__main__":
+    main()

package/skills/kicad-ipc/scripts/remove_selected_items.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Delete exactly the currently selected KiCad items via IPC."""
+
+from __future__ import annotations
+
+import argparse
+
+from kipy_common import close_kicad, commit_or_drop, connect_board
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--yes", action="store_true", help="确认删除当前选择中的所有对象")
+    parser.add_argument("--save", action="store_true", help="删除后通过 IPC 保存 PCB")
+    args = parser.parse_args()
+    if not args.yes:
+        parser.error("删除需要显式传入 --yes")
+
+    kicad, board = connect_board()
+    try:
+        targets = list(board.get_selection())
+        if not targets:
+            raise RuntimeError("KiCad 当前没有选择对象；未做任何修改。")
+
+        print(f"即将删除当前选择中的 {len(targets)} 个对象。")
+        commit_or_drop(
+            board,
+            f"Delete {len(targets)} selected items",
+            lambda: board.remove_items(targets),
+        )
+        print("已删除当前选择中的对象。")
+        if args.save:
+            board.save()
+            print("已通过 IPC 保存 PCB。")
+    finally:
+        close_kicad(kicad)
+
+
+if __name__ == "__main__":
+    main()

package/skills/kicad-ipc/scripts/update_selected_track_width.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Update the width of currently selected straight or arc tracks via IPC."""
+
+from __future__ import annotations
+
+import argparse
+
+from kipy.board_types import ArcTrack, Track
+from kipy.util import from_mm
+
+from kipy_common import close_kicad, commit_or_drop, connect_board
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--width-mm", type=float, required=True, help="目标线宽，单位 mm")
+    parser.add_argument("--save", action="store_true", help="验证成功后通过 IPC 保存 PCB")
+    args = parser.parse_args()
+    if args.width_mm <= 0:
+        parser.error("--width-mm 必须大于 0")
+
+    kicad, board = connect_board()
+    try:
+        targets = [item for item in board.get_selection() if isinstance(item, (Track, ArcTrack))]
+        if not targets:
+            raise RuntimeError("当前 KiCad 选择中没有直线或圆弧走线；未做任何修改。")
+
+        requested_width = from_mm(args.width_mm)
+        for target in targets:
+            target.width = requested_width
+
+        def validate(updated):
+            if len(updated) != len(targets):
+                raise RuntimeError("KiCad 未更新全部目标走线。")
+            if any(item.width != requested_width for item in updated):
+                raise RuntimeError("KiCad 未接受全部目标线宽。")
+
+        updated = commit_or_drop(
+            board,
+            f"Set width of {len(targets)} selected tracks",
+            lambda: board.update_items(targets),
+            validate,
+        )
+
+        print(f"已更新 {len(updated)} 条选中走线。")
+        if args.save:
+            board.save()
+            print("已通过 IPC 保存 PCB。")
+    finally:
+        close_kicad(kicad)
+
+
+if __name__ == "__main__":
+    main()

package/skills/kicad-ipc/scripts/verify_live_ipc.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Run a non-persistent live IPC smoke test against the open PCB.
+
+The test performs real API creates, updates, a footprint clone, a copper-zone
+create, and a delete inside one unpushed KiCad commit, then drops that commit.
+It never calls save().  Use only on a board whose unsaved edits you have
+reviewed: dropping a commit does not protect unrelated unsaved GUI changes.
+"""
+
+from __future__ import annotations
+
+from kipy.board_types import BoardLayer, Track, Via, Zone
+from kipy.common_types import PolygonWithHoles
+from kipy.geometry import Angle, PolyLine, PolyLineNode, Vector2
+from kipy.util import from_mm
+
+from kipy_common import close_kicad, connect_board
+
+
+def main() -> None:
+    kicad, board = connect_board(timeout_ms=10000)
+    commit = None
+    try:
+        nets = {net.name: net for net in board.get_nets()}
+        if "GND" not in nets:
+            raise RuntimeError("烟测要求当前板已有 GND 网络。")
+        source = board.get_footprints()[0]
+        before = (len(board.get_tracks()), len(board.get_vias()), len(board.get_zones()), len(board.get_footprints()))
+
+        commit = board.begin_commit()
+
+        track = Track()
+        track.start = Vector2.from_xy_mm(1.0, 1.0)
+        track.end = Vector2.from_xy_mm(2.0, 1.0)
+        track.width = from_mm(0.25)
+        track.layer = BoardLayer.BL_F_Cu
+        track.net = nets["GND"]
+        created_track, = board.create_items(track)
+        assert created_track.net.name == "GND"
+
+        created_track.width = from_mm(0.30)
+        updated_track, = board.update_items(created_track)
+        assert updated_track.width == from_mm(0.30)
+
+        via = Via()
+        via.position = Vector2.from_xy_mm(1.5, 1.0)
+        via.diameter = from_mm(0.8)
+        via.drill_diameter = from_mm(0.4)
+        via.net = nets["GND"]
+        created_via, = board.create_items(via)
+        assert created_via.net.name == "GND"
+
+        source.position += Vector2.from_xy_mm(0.1, 0.1)
+        source.orientation += Angle.from_degrees(5)
+        updated_footprint, = board.update_items(source)
+        assert updated_footprint.id == source.id
+
+        clone = updated_footprint.clone()
+        clone.position += Vector2.from_xy_mm(1.0, 1.0)
+        clone.reference_field.text.value = "__IPC_SMOKE_TEST__"
+        created_footprint, = board.create_items(clone)
+        assert created_footprint.reference_field.text.value == "__IPC_SMOKE_TEST__"
+
+        outline = PolyLine()
+        for x_mm, y_mm in ((3.0, 1.0), (4.0, 1.0), (4.0, 2.0), (3.0, 2.0), (3.0, 1.0)):
+            outline.append(PolyLineNode.from_xy(from_mm(x_mm), from_mm(y_mm)))
+        polygon = PolygonWithHoles()
+        polygon.outline = outline
+        zone = Zone()
+        zone.net = nets["GND"]
+        zone.layers = [BoardLayer.BL_F_Cu]
+        zone.outline = polygon
+        created_zone, = board.create_items(zone)
+        assert created_zone.net is not None and created_zone.net.name == "GND"
+
+        board.remove_items(updated_track)
+        board.drop_commit(commit)
+        commit = None
+
+        after = (len(board.get_tracks()), len(board.get_vias()), len(board.get_zones()), len(board.get_footprints()))
+        if after != before:
+            raise RuntimeError(f"drop_commit 后对象数量不匹配：before={before}, after={after}")
+        print("IPC live smoke test passed; all temporary changes were dropped and not saved.")
+    finally:
+        if commit is not None:
+            board.drop_commit(commit)
+        close_kicad(kicad)
+
+
+if __name__ == "__main__":
+    main()

package/src/config.ts

@@ -0,0 +1,79 @@
+/**
+ * Configuration for `@huaqiu/dsh-kicad`.
+ *
+ * Deliberately small. Everything KiCad-specific (socket, token, board state)
+ * belongs to KiCad and the bundled scripts — the scripts read
+ * `KICAD_API_SOCKET` / `KICAD_API_TOKEN` that KiCad injects, and this package
+ * never guesses them. The only host configuration here is *how to reach the
+ * Python environment that owns `kipy`*, which is a machine concern, not a
+ * design concern.
+ *
+ * @module
+ */
+
+/** Configuration accepted by the plugin's `apply()`. */
+export interface KicadConfig {
+  /**
+   * Python interpreter used to run the bundled KiCad scripts. It must have the
+   * official `kicad-python` package (`kipy`) installed.
+   */
+  pythonPath: string
+  /** Scripts directory override (defaults to the bundled skill's `scripts/`). */
+  skillsDir?: string
+  /** Per-script timeout in milliseconds. */
+  timeoutMs: number
+  /** Timeout for the two diagnostic scripts, which are fast but must be prompt. */
+  diagnosticTimeoutMs: number
+  /** Timeout for `refill_zones`, which can legitimately block for ~2 minutes. */
+  refillTimeoutMs: number
+}
+
+export type KicadConfigInput = Partial<KicadConfig>
+
+/** Default Python interpreter when nothing is configured. */
+export const DEFAULT_PYTHON_PATH = 'python3'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_DIAGNOSTIC_TIMEOUT_MS = 15_000
+/** `refill_zones.py` polls zone fills; the script itself documents ~120 s. */
+const DEFAULT_REFILL_TIMEOUT_MS = 150_000
+
+function firstNonEmpty(...values: Array<string | undefined>): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim().length > 0) return value
+  }
+  return undefined
+}
+
+/**
+ * Resolve the effective configuration.
+ *
+ * Precedence matches the rest of the Huaqiu DSH package set: explicit plugin
+ * config wins over the environment, which wins over the default.
+ */
+export function resolveKicadConfig(input: KicadConfigInput = {}): KicadConfig {
+  const pythonPath =
+    firstNonEmpty(input.pythonPath, process.env['DSH_KICAD_PYTHON']) ?? DEFAULT_PYTHON_PATH
+
+  const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  const diagnosticTimeoutMs = input.diagnosticTimeoutMs ?? DEFAULT_DIAGNOSTIC_TIMEOUT_MS
+  const refillTimeoutMs = input.refillTimeoutMs ?? DEFAULT_REFILL_TIMEOUT_MS
+
+  return {
+    pythonPath,
+    ...(input.skillsDir ? { skillsDir: input.skillsDir } : {}),
+    timeoutMs,
+    diagnosticTimeoutMs,
+    refillTimeoutMs,
+  }
+}
+
+/** Whether any host configuration was supplied (used for startup logging). */
+export function hasHostConfig(input: KicadConfigInput = {}): boolean {
+  return Boolean(
+    input.pythonPath ??
+      process.env['DSH_KICAD_PYTHON'] ??
+      input.skillsDir ??
+      process.env['DSH_KICAD_SKILLS_DIR'],
+  )
+}

package/src/index.ts

@@ -0,0 +1,230 @@
+/**
+ * `@huaqiu/dsh-kicad` — node plugin entry.
+ *
+ * ── Delivery boundary (task: dsh-kicad-skill-plugin §14, §28) ───────────────
+ * This plugin ships TWO things that used to need two installations:
+ *
+ *   1. ten KiCad tools, registered with `ctx.tools.register(defineTool(...))`
+ *   2. the `kicad-ipc` skill, registered with `ctx.skills.register(...)`
+ *
+ * Installing the Huaqiu DSH PCB/EDA bundle therefore makes KiCad agent
+ * capabilities AND the skill that teaches the agent to use them available out of
+ * the box. There is no separate skill installation step, and this plugin adds no
+ * second skill-registration mechanism — `ctx.skills.register()` is the DSH
+ * runtime's own plugin-bundled skill channel.
+ *
+ * ── Boundaries ──────────────────────────────────────────────────────────────
+ * KiCad IPC is reached through the bundled Python scripts under
+ * `skills/kicad-ipc/scripts/` (see `./ipc.ts`). This package holds no HQ Edge
+ * dependency of any kind — no runtime, executable, service, port, config or
+ * artifact dependency (§3, §21) — and no `@hqedge/*` import.
+ *
+ * @module @huaqiu/dsh-kicad
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { getLogger } from '@huaqiu/dsh-plugin-log'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  hasHostConfig,
+  resolveKicadConfig,
+  type KicadConfig,
+  type KicadConfigInput,
+} from './config.js'
+import { requireSkillDir, resolveSkillDir, scriptsDir } from './paths.js'
+import { KICAD_SKILL_NAME } from './scripts.js'
+import { createKicadTools, kicadToolNames } from './tools.js'
+
+/** Plugin id — matches package.json. */
+export const name = '@huaqiu/dsh-kicad'
+
+/**
+ * Cordis services this half depends on.
+ *
+ * `skills` is REQUIRED: it is the DSH runtime's skill registry, and registering
+ * the bundled `kicad-ipc` skill is this plugin's core job. Without the inject,
+ * `apply()`'s `ctx.skills` access would throw
+ * `cannot get property "skills" without inject`.
+ *
+ * `tools` is the DSH node runtime tool registry used for the KiCad tools.
+ *
+ * Note what is NOT here: `hqEdge`. Unlike `@huaqiu/dsh-eda-host`, this plugin
+ * talks to KiCad directly, so it must never depend on the edge bridge.
+ */
+export const inject = ['skills', 'tools'] as const
+
+export type { KicadConfig, KicadConfigInput } from './config.js'
+export type { KicadError, KicadErrorKind, ScriptRun } from './ipc.js'
+export type { KicadScript, ScriptEffect } from './scripts.js'
+export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, kicadScript } from './scripts.js'
+export { kicadToolNames } from './tools.js'
+export { resolveSkillDir, requireSkillDir, scriptsDir } from './paths.js'
+export { runKicadScript, classifyRun, invokeKicadScript } from './ipc.js'
+export { createKicadTools } from './tools.js'
+
+/**
+ * The `skills` service as this plugin uses it.
+ *
+ * `@deepseek-ai/dsh-tools` already augments `Context` with `tools`, but nothing
+ * in this workspace augments `skills` — `@deepseek-ai/dsh-skill` is a runtime
+ * dependency of the harness, not of this package (we never import it; the
+ * service arrives through Cordis injection). Declaring the shape we consume is
+ * the same technique `@huaqiu/dsh-eda-host` uses for `hqEdge`.
+ */
+export interface SkillRegistration {
+  /** Skill id — must match `/^[a-z0-9]+(?:-[a-z0-9]+)*$/` to be discoverable. */
+  name: string
+  /** Catalog description shown to the model. */
+  description: string
+  /** Full SKILL.md body. */
+  content: string
+  /** Where `references/` and `scripts/` live for progressive disclosure. */
+  resourceBase: { kind: 'directory'; path: string }
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** DSH skill registry, provided by the `@deepseek-ai/dsh-skill` service. */
+    skills: {
+      /** Register a plugin-bundled skill; returns its unregister disposer. */
+      register(skill: SkillRegistration): () => void
+    }
+  }
+}
+
+/** Shared component name for the unified DSH-plugin log. */
+const COMPONENT = 'dsh-kicad'
+const log = getLogger(COMPONENT)
+
+// Emitted on import, before any Cordis dependency is resolved. Pairs with the
+// "node half ready" marker in apply(): if this line is logged but that one is
+// not, the `skills`/`tools` services were never provided and this plugin is
+// still pending — which is otherwise completely silent. Same idiom as
+// `@huaqiu/dsh-eda-host`.
+log.info('dsh-kicad: module loaded (waiting for the skills + tools services)')
+
+/**
+ * Used only when the bundled SKILL.md has no parseable `description`
+ * frontmatter. The real value always comes from the shipped file, so the skill
+ * catalog cannot drift away from the skill body.
+ */
+const FALLBACK_SKILL_DESCRIPTION =
+  'Operate a KiCad PCB through the official KiCad IPC API: inspect the live ' +
+  'board and create, modify or delete objects. Use for PCB automation and ' +
+  'autorouter-result import — not for editing .kicad_pcb files directly.'
+
+/**
+ * Extract the `description` field from SKILL.md YAML frontmatter.
+ *
+ * Only the single-line form is supported (quoted or bare), which is what the
+ * migrated skill uses. Returns `undefined` when absent so the caller can fall
+ * back rather than registering a skill with an empty description — DSH ignores
+ * frontmatter-less skills entirely, so an empty description would silently
+ * break discovery.
+ */
+export function skillDescription(markdown: string): string | undefined {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown)
+  if (!frontmatter?.[1]) return undefined
+  const line = frontmatter[1]
+    .split(/\r?\n/)
+    .find((candidate) => /^\s*description\s*:/.test(candidate))
+  if (!line) return undefined
+  const raw = line.slice(line.indexOf(':') + 1).trim()
+  const unquoted = raw.replace(/^["']/, '').replace(/["']$/, '')
+  return unquoted.length > 0 ? unquoted : undefined
+}
+
+/**
+ * Read the bundled `kicad-ipc` SKILL.md.
+ *
+ * Exposed for tests and for callers that want the skill body without loading
+ * the plugin (e.g. a packaging check).
+ */
+export function readBundledSkill(moduleUrl: string, override?: string): {
+  dir: string
+  name: string
+  description: string
+  content: string
+} {
+  const dir = requireSkillDir(moduleUrl, override)
+  const content = readFileSync(join(dir, 'SKILL.md'), 'utf8')
+  return {
+    dir,
+    name: KICAD_SKILL_NAME,
+    description: skillDescription(content) ?? FALLBACK_SKILL_DESCRIPTION,
+    content,
+  }
+}
+
+/**
+ * Host plugin body — register the `kicad-ipc` skill and the KiCad tools.
+ *
+ * Both halves are registered here so that one installation delivers both. The
+ * skill's `resourceBase` points at the bundled skill directory, which is how
+ * the agent reaches `references/ipc-pcb-workflows.md` and `scripts/` as
+ * progressive-disclosure resources.
+ *
+ * @param ctx - real cordis context (node side).
+ * @param config - plugin overlay config (python interpreter, timeouts).
+ * @returns disposer — unregisters the skill and the tools on plugin dispose.
+ */
+export function apply(ctx: Context, config: KicadConfigInput = {}): () => void {
+  if (!ctx.tools || typeof ctx.tools.register !== 'function') {
+    throw new Error('@huaqiu/dsh-kicad requires the DSH `tools` service (ctx.tools.register).')
+  }
+  if (!ctx.skills || typeof ctx.skills.register !== 'function') {
+    throw new Error('@huaqiu/dsh-kicad requires the DSH `skills` service (ctx.skills.register).')
+  }
+
+  const resolved = resolveKicadConfig(config)
+
+  // Throws when the installed package is missing its skill — a packaging
+  // failure must be loud, not silently degraded (§15).
+  const skill = readBundledSkill(import.meta.url, config.skillsDir)
+
+  log.info('applying dsh-kicad node half', {
+    hasConfigHost: hasHostConfig(config),
+    pythonPath: resolved.pythonPath,
+    skillDir: skill.dir,
+    timeoutMs: resolved.timeoutMs,
+  })
+
+  const disposers: Array<() => void> = []
+
+  // ── Skill (bundled, no separate installation) ────────────────────────────
+  disposers.push(
+    ctx.skills.register({
+      name: skill.name,
+      description: skill.description,
+      content: skill.content,
+      resourceBase: { kind: 'directory', path: skill.dir },
+    }),
+  )
+
+  // ── Tools ────────────────────────────────────────────────────────────────
+  const tools = createKicadTools({
+    scriptsDir: scriptsDir(skill.dir),
+    pythonPath: resolved.pythonPath,
+    config: resolved,
+  })
+  for (const tool of tools) {
+    disposers.push(ctx.tools.register(tool))
+  }
+
+  log.info('dsh-kicad node half ready', {
+    skill: skill.name,
+    tools: tools.length,
+    expectedTools: kicadToolNames().length,
+  })
+
+  return () => {
+    for (const dispose of disposers.reverse()) {
+      try {
+        dispose()
+      } catch (err) {
+        log.warn('dsh-kicad disposer failed', { error: String((err as Error)?.message ?? err) })
+      }
+    }
+  }
+}