@huaqiu/dsh-kicad 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳华秋智联股份有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @huaqiu/dsh-kicad
+
+KiCad agent capabilities for DeepSeek Harness, shipped as **one** DSH plugin: the
+executable KiCad tools *and* the `kicad-ipc` skill that teaches the agent how to use
+them. Installing the Huaqiu DSH PCB/EDA bundle makes both available out of the box —
+there is no separate skill installation step.
+
+Migrated from the standalone `kicad-agent` repository.
+
+## What you get
+
+```
+@huaqiu/dsh-kicad
+├── Tools     10 KiCad tools, registered with ctx.tools.register(defineTool(...))
+└── Skills    kicad-ipc — SKILL.md + references/ + 11 python script templates
+```
+
+### Tools
+
+| Tool | Script | Effect |
+|---|---|---|
+| `kicad_ipc_diagnose` | `diagnose_ipc_connection.py` | read |
+| `kicad_ipc_verify_live` | `verify_live_ipc.py` | probe (commit dropped) |
+| `kicad_pcb_create_track` | `create_track.py` | mutate |
+| `kicad_pcb_create_via` | `create_via.py` | mutate |
+| `kicad_pcb_create_copper_zone` | `create_copper_zone.py` | mutate |
+| `kicad_pcb_add_footprint_from_template` | `add_footprint_from_board_template.py` | mutate |
+| `kicad_pcb_move_rotate_footprint` | `move_rotate_footprint.py` | mutate |
+| `kicad_pcb_update_selected_track_width` | `update_selected_track_width.py` | mutate |
+| `kicad_pcb_refill_zones` | `refill_zones.py` | mutate |
+| `kicad_pcb_remove_selected_items` | `remove_selected_items.py` | mutate (needs `confirm`) |
+
+Every tool returns the same envelope:
+
+```jsonc
+{ "ok": true,  "script": "create_track", "effect": "mutate", "output": "…" }
+{ "ok": false, "script": "create_track", "effect": "mutate",
+  "error": { "kind": "FAILED_PRECONDITION", "message": "…" } }
+```
+
+`error.kind` is one of `FAILED_PRECONDITION` (KiCad IPC cannot run at all — do not
+retry), `UNAVAILABLE` (KiCad unreachable — retry once after checking the environment),
+`DEADLINE_EXCEEDED` (timed out), `INVALID_ARGUMENT` (board untouched), `INTERNAL`
+(script failed; the commit was dropped).
+
+### Skill
+
+`skills/kicad-ipc/SKILL.md` is the agent's operating guidance: when to use KiCad, how to
+inspect current state, how to verify mutations, and when to stop and ask. It is *not* an
+IPC API specification — the tool schemas are the executable interface, the skill is the
+reasoning around them.
+
+Progressive disclosure: `references/ipc-pcb-workflows.md` holds version matrices, the
+public CRUD table and failure handling; `scripts/` holds runnable templates. Both are
+reachable by the agent because the skill is registered with a `resourceBase` pointing at
+its directory.
+
+## How the plugin is wired
+
+```yaml
+# cordis.patch.yml
+- insert:
+    - id: huaqiu-dsh-kicad
+      name: '@huaqiu/dsh-kicad'
+      inject: ['skills', 'tools']
+```
+
+`inject` must match `export const inject` in `src/index.ts`. `skills` is required —
+that is the DSH runtime's own plugin-bundled skill channel (`ctx.skills.register`).
+`apply()` registers the skill and the ten tools and returns a single disposer.
+
+The skill is located relative to the **loaded module**, not the source tree, so one
+resolver works for `src/` (tests), `lib/` (built) and an npm install:
+
+```
+<package>/lib/index.mjs  ->  <package>/skills/kicad-ipc
+```
+
+That is why `files[]` must contain `skills` — otherwise npm strips it and `apply()`
+throws loudly instead of silently degrading.
+
+## Runtime requirements
+
+KiCad IPC is not bundled; these are host requirements, the same ones `kicad-agent` had:
+
+- KiCad **9.0+** with the KiCad API service enabled (Preferences → Plugins) and PCB
+  Editor restarted, with a `.kicad_pcb` open.
+- A Python interpreter with the official `kicad-python` package (`kipy`) whose version
+  matches the running KiCad. Configure it with plugin config `pythonPath` or
+  `$DSH_KICAD_PYTHON` (default `python3`).
+- DSH running with **Full Access** — a non-Full-Access sandbox cannot reach KiCad's
+  named pipe on Windows.
+
+`KICAD_API_SOCKET` / `KICAD_API_TOKEN` are injected by KiCad and read by `kipy`. This
+package never guesses, hardcodes or scans for them.
+
+### Configuration
+
+| Setting | Env | Default |
+|---|---|---|
+| `pythonPath` | `DSH_KICAD_PYTHON` | `python3` |
+| `skillsDir` | `DSH_KICAD_SKILLS_DIR` | bundled `skills/kicad-ipc` |
+| `timeoutMs` | — | `30000` |
+| `diagnosticTimeoutMs` | — | `15000` |
+| `refillTimeoutMs` | — | `150000` |
+
+## Boundaries
+
+- **No HQ Edge dependency.** Unlike `@huaqiu/dsh-eda-host`, this plugin talks to KiCad
+  directly: no runtime, executable, service, port, config or artifact dependency, and no
+  `@hqedge/*` import.
+- **KiCad is the source of truth.** The adapter returns what KiCad said, verbatim. There
+  is no second authoritative representation of board state in this package.
+- **The scripts own the protocol.** The adapter shells out to the migrated Python
+  templates rather than re-implementing KiCad IPC in TypeScript.
+
+## Layout
+
+```
+packages/dsh-kicad/
+  src/index.ts     # plugin entry: apply() registers skill + tools
+  src/tools.ts     # 10 defineTool definitions
+  src/ipc.ts       # KiCad IPC adapter (script runner + error classification)
+  src/scripts.ts   # bundled script registry
+  src/paths.ts     # runtime skill-directory resolution
+  src/config.ts    # python interpreter / timeouts
+  skills/kicad-ipc/
+    SKILL.md
+    agents/openai.yaml
+    references/ipc-pcb-workflows.md
+    scripts/*.py
+  test/            # plugin loading, tool registration, skill discovery, bundling
+```
+
+## Tests
+
+```bash
+pnpm --filter @huaqiu/dsh-kicad test
+```
+
+46 tests covering plugin loading, the disposer, skill discovery, tool registration, argv
+construction, pre-flight validation, semantic error mapping and packaging. Execution is
+exercised against a fake interpreter, so no KiCad or `kipy` is needed.

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# DSH bundle patch: inserts the Huaqiu KiCad plugin into a profile's layer stack.
+#
+# This one row delivers BOTH halves of `dsh-kicad` (task: dsh-kicad-skill-plugin):
+# the KiCad tools and the bundled `kicad-ipc` skill. The plugin registers the
+# skill itself at load time via `ctx.skills.register()`, so there is no separate
+# skill installation step and no second skill registration mechanism.
+#
+# The entry `inject` MUST match the node-half module contract (`src/index.ts`
+# `export const inject`): `skills` + `tools`. `skills` is REQUIRED — without it
+# `apply()`'s `ctx.skills` access throws `cannot get property "skills" without
+# inject`.
+- insert:
+    - id: huaqiu-dsh-kicad
+      name: '@huaqiu/dsh-kicad'
+      inject: ['skills', 'tools']

package/lib/index.d.mts

@@ -0,0 +1,284 @@
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+/**
+ * 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()`. */
+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;
+}
+type KicadConfigInput = Partial<KicadConfig>;
+//#endregion
+//#region src/scripts.d.ts
+/**
+ * Registry of the KiCad IPC script templates bundled with this package.
+ *
+ * The scripts are the migrated `kicad-agent` executable surface. They live
+ * under `skills/kicad-ipc/scripts/` and are shipped verbatim — this module only
+ * describes them so the DSH tools and the skill stay in sync. Nothing here
+ * reimplements KiCad IPC: the scripts own it (see `./ipc.ts`).
+ *
+ * @module
+ */
+/** How one bundled script changes (or does not change) the KiCad board. */
+type ScriptEffect =
+/** Reads only. Safe to run at any time. */
+'read' |
+/** Mutates the board inside a dropped commit — nothing is persisted. */
+'probe' |
+/** Mutates the board and pushes the commit. Persists only with `save`. */
+'mutate';
+interface KicadScript {
+  /** Stable id — the script's file stem. */
+  readonly id: string;
+  /** File name inside `skills/kicad-ipc/scripts/`. */
+  readonly file: string;
+  /** One-line, agent-facing summary of what the script does. */
+  readonly summary: string;
+  /** What the script does to the board. */
+  readonly effect: ScriptEffect;
+  /** Whether the script accepts the shared `--save` flag. */
+  readonly supportsSave: boolean;
+}
+/**
+ * Every bundled script, keyed by id.
+ *
+ * Mirrors `skills/kicad-ipc/scripts/` 1:1. Adding a script to the skill means
+ * adding it here (and exposing it in `./tools.ts`) — the bundling test asserts
+ * that all three stay consistent.
+ */
+declare const KICAD_SCRIPTS: Readonly<Record<string, KicadScript>>;
+/** The bundled script ids, in registration order. */
+declare const KICAD_SCRIPT_IDS: readonly string[];
+/**
+ * Look up one script by id.
+ * @throws when the id is not part of the bundled set.
+ */
+declare function kicadScript(id: string): KicadScript;
+/** The canonical skill directory name shipped by this package. */
+declare const KICAD_SKILL_NAME = "kicad-ipc";
+//#endregion
+//#region src/ipc.d.ts
+/**
+ * Semantic failure kinds, shared by every KiCad tool.
+ *
+ * Same vocabulary as `@huaqiu/dsh-eda-host` so the agent's error handling does
+ * not have to differ per EDA plugin.
+ */
+type KicadErrorKind =
+/** The environment cannot run KiCad IPC at all (no python, no kipy, no board). */
+'FAILED_PRECONDITION' |
+/** KiCad is installed but unreachable right now — retryable. */
+'UNAVAILABLE' |
+/** The script did not finish inside its timeout. */
+'DEADLINE_EXCEEDED' |
+/** The arguments were rejected before KiCad was touched. */
+'INVALID_ARGUMENT' |
+/** KiCad or the script failed after the connection was established. */
+'INTERNAL';
+interface KicadError {
+  kind: KicadErrorKind;
+  message: string;
+}
+/** Raw result of one script invocation. */
+interface ScriptRun {
+  /** Script identifier (file stem). */
+  script: string;
+  /** Process exit code; `null` when it never started or was killed. */
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  /** Exact argv handed to the interpreter, for auditability. */
+  argv: string[];
+  /** `true` when the process was killed because the timeout elapsed. */
+  timedOut: boolean;
+}
+interface RunScriptOptions {
+  /** Directory holding the bundled scripts. */
+  scriptsDir: string;
+  /** Python interpreter with `kipy` available. */
+  pythonPath: string;
+  /** Script to run. */
+  script: KicadScript;
+  /** CLI flags, already stringified (e.g. `['--net', 'GND']`). */
+  args?: readonly string[];
+  /** Timeout in milliseconds. */
+  timeoutMs: number;
+  /** Optional cancellation from the tool call. */
+  signal?: AbortSignal;
+}
+/**
+ * Run one bundled KiCad script.
+ *
+ * Never throws for script-level failures — the outcome is reported, so a
+ * missing `kipy` or a closed KiCad degrades into a typed error the agent can
+ * act on instead of crashing the plugin. It only throws when the script itself
+ * is not part of the package.
+ */
+declare function runKicadScript(options: RunScriptOptions): Promise<ScriptRun>;
+/**
+ * Translate a raw run into a semantic error, or `undefined` on success.
+ *
+ * Exit codes are part of the scripts' contract:
+ *
+ *   - `diagnose_ipc_connection.py`: 0 ok, 1 unreachable, 2 `kipy` missing,
+ *     3 API version mismatch, 4 no board open.
+ *   - every argparse script: 2 = rejected arguments (KiCad untouched).
+ *   - anything else non-zero: a real KiCad/script failure.
+ */
+declare function classifyRun(run: ScriptRun): KicadError | undefined;
+/** Convenience: run a script and return its semantic outcome. */
+declare function invokeKicadScript(options: RunScriptOptions): Promise<{
+  ok: boolean;
+  run: ScriptRun;
+  error?: KicadError;
+}>;
+//#endregion
+//#region src/tools.d.ts
+/** Everything a tool needs to reach the bundled scripts. */
+interface KicadToolEnv {
+  /** Directory holding the bundled Python scripts. */
+  scriptsDir: string;
+  /** Python interpreter with `kipy`. */
+  pythonPath: string;
+  config: KicadConfig;
+}
+/**
+ * All KiCad tools contributed by this plugin.
+ */
+declare function createKicadTools(env: KicadToolEnv): ReturnType<typeof defineTool>[];
+/**
+ * Names of every tool this plugin registers — asserted by the tests and used
+ * for startup logging.
+ */
+declare function kicadToolNames(): string[];
+//#endregion
+//#region src/paths.d.ts
+/**
+ * Absolute path of the bundled `kicad-ipc` skill directory.
+ *
+ * Resolution order: an explicit override (config / `DSH_KICAD_SKILLS_DIR`),
+ * then the package-relative location.
+ *
+ * @param moduleUrl - `import.meta.url` of the calling module.
+ * @param override - explicit directory (plugin config or env var).
+ * @returns the resolved directory, whether or not it exists yet.
+ */
+declare function resolveSkillDir(moduleUrl: string, override?: string): string;
+/**
+ * Resolve the skill directory and assert the skill is actually present.
+ *
+ * @throws when `SKILL.md` is missing — this is a packaging failure, not a
+ * runtime condition, so it must be loud rather than silently degraded.
+ */
+declare function requireSkillDir(moduleUrl: string, override?: string): string;
+/** Absolute path of the bundled Python script directory. */
+declare function scriptsDir(skillDir: string): string;
+//#endregion
+//#region src/index.d.ts
+/** Plugin id — matches package.json. */
+declare 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.
+ */
+declare const inject: readonly ["skills", "tools"];
+/**
+ * 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`.
+ */
+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;
+    };
+  }
+}
+/**
+ * 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.
+ */
+declare function skillDescription(markdown: string): string | 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).
+ */
+declare function readBundledSkill(moduleUrl: string, override?: string): {
+  dir: string;
+  name: string;
+  description: string;
+  content: string;
+};
+/**
+ * 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.
+ */
+declare function apply(ctx: Context, config?: KicadConfigInput): () => void;
+//#endregion
+export { KICAD_SCRIPTS, KICAD_SCRIPT_IDS, KICAD_SKILL_NAME, type KicadConfig, type KicadConfigInput, type KicadError, type KicadErrorKind, type KicadScript, type ScriptEffect, type ScriptRun, SkillRegistration, apply, classifyRun, createKicadTools, inject, invokeKicadScript, kicadScript, kicadToolNames, name, readBundledSkill, requireSkillDir, resolveSkillDir, runKicadScript, scriptsDir, skillDescription };