@huaqiu/dsh-eda-host 0.3.20

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,66 @@
+# @huaqiu/dsh-eda-host
+
+DSH plugin exposing the current EDA host's schematic netlist to agents through
+hq-edge.
+
+## What it provides
+
+| Tool | Scope |
+|---|---|
+| `get_project_netlist` | complete logical netlist of the current project |
+| `get_selection_netlist` | netlist of the currently selected components |
+| `get_active_page_netlist` | netlist of the active schematic page |
+
+Each tool returns lossless JSON:
+
+```json
+{
+  "ok": true,
+  "scope": "project",
+  "netlist": {
+    "components": [
+      { "referenceDesignators": ["R1"], "value": "10k", "footprint": "R_0603",
+        "manufacturerPartNumber": "", "description": "", "pins": [
+          { "pinNumber": "1", "pinName": "1", "electricalType": "ELECTRICAL_TYPE_PASSIVE" }
+        ] }
+    ],
+    "nets": [
+      { "name": "GND", "pinReferences": [
+        { "referenceDesignator": "R1", "pinNumber": "2" }
+      ] }
+    ]
+  }
+}
+```
+
+A valid-but-empty design is `ok: true` with empty `components`/`nets` — it is
+NOT an error. On failure the tool returns `ok: false` with a semantic
+`error.kind`:
+
+- `FAILED_PRECONDITION` — no EDA host / no live editor (ask the user to open
+  the design first).
+- `UNIMPLEMENTED` — the host does not support this scope (e.g. active page on
+  KiCad). Do not retry.
+- `UNAVAILABLE` — hq-edge host unreachable.
+- `INTERNAL` — host-side failure.
+
+## Architecture
+
+```
+DSH
+ ↓
+dsh-eda-host      (this plugin: DSH integration only, self-contained)
+ ↓ hq-edge HTTP
+hq-edge           (semantic protocol + orchestration; /api/v1/netlist/*)
+ ↓ gRPC
+EDA Host          (hq.ir.schematic.v1.NetListService — KiCad / HQ EDA)
+ ↓
+native EDA model
+```
+
+- No `@hqedge/*` dependency: the base URL arrives as overlay config
+  (`hqEdgeBaseUrl`, delivered by the hq-edge supervisor) or `HQ_EDGE_BASE_URL`
+  env fallback.
+- No KiCad code, no schematic parsing, no host IPC in this package.
+- Errors are propagated with semantic kinds — never converted into fake empty
+  netlists.

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# DSH bundle patch: inserts the Huaqiu EDA host netlist tool plugin.
+# The entry inject must match the node-half module contract (`src/index.ts` —
+# export const inject). The tool's apply() reads the `tools` service; the
+# hq-edge supervisor delivers the base URL as overlay config.
+- insert:
+    - id: huaqiu-dsh-eda-host
+      name: '@huaqiu/dsh-eda-host'
+      inject: ['tools']

package/lib/index.d.mts

@@ -0,0 +1,112 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+/**
+ * Runtime config resolution for `@huaqiu/dsh-eda-host`.
+ *
+ * The plugin never opens a direct connection to the EDA host — it only talks
+ * to `hq-edge`, which owns the host session. The base URL is delivered by the
+ * hq-edge supervisor as overlay config (`hqEdgeBaseUrl`), with the
+ * `HQ_EDGE_BASE_URL` env as fallback for non-supervisor installs. This mirrors
+ * the `@huaqiu/dsh-auth` host-config convention.
+ *
+ * @module
+ */
+interface EdaHostConfig {
+  /** HQ Edge base URL, e.g. "http://localhost:18080". Absent → no host. */
+  hqEdgeBaseUrl?: string;
+  /** Path prefix on the host; default "/api/v1/netlist". */
+  netlistPathPrefix?: string;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Semantic netlist types for `@huaqiu/dsh-eda-host`.
+ *
+ * Self-contained structural mirror of `hq.ir.schematic.v1` (the hq-edge-owned
+ * semantic protobuf contract). The plugin intentionally does NOT depend on
+ * `@hqedge/*` — this file is the only place the wire shapes are named, so
+ * keeping them aligned with the proto is a one-file concern.
+ *
+ * @module
+ */
+/** Electrical type of a pin — mirrors `hq.ir.logical.v1.ElectricalType`. */
+type ElectricalType = 'ELECTRICAL_TYPE_UNSPECIFIED' | 'ELECTRICAL_TYPE_INPUT' | 'ELECTRICAL_TYPE_OUTPUT' | 'ELECTRICAL_TYPE_BIDIRECTIONAL' | 'ELECTRICAL_TYPE_TRISTATE' | 'ELECTRICAL_TYPE_PASSIVE' | 'ELECTRICAL_TYPE_POWER_IN' | 'ELECTRICAL_TYPE_POWER_OUT' | 'ELECTRICAL_TYPE_OPEN_COLLECTOR' | 'ELECTRICAL_TYPE_OPEN_EMITTER' | 'ELECTRICAL_TYPE_NO_CONNECT';
+interface PinDefinition {
+  pinNumber: string;
+  pinName: string;
+  electricalType: ElectricalType;
+}
+interface SchematicComponent {
+  referenceDesignators: string[];
+  value: string;
+  manufacturerPartNumber: string;
+  footprint: string;
+  description: string;
+  pins: PinDefinition[];
+}
+interface PinReference {
+  referenceDesignator: string;
+  pinNumber: string;
+}
+interface ElectricalNet {
+  name: string;
+  portName?: string;
+  pinReferences: PinReference[];
+}
+interface SchematicNetlist {
+  components: SchematicComponent[];
+  nets: ElectricalNet[];
+}
+/**
+ * Semantic error categories for netlist retrieval. Mirrors the gRPC status
+ * contract of `hq.ir.schematic.v1.NetListService` so an agent can distinguish
+ * "valid but empty" from "cannot answer at all".
+ */
+type NetlistErrorKind =
+/** No EDA host is reachable (hq-edge not configured / host down). */
+'FAILED_PRECONDITION' |
+/** The host does not implement this scope (e.g. active page on KiCad). */
+'UNIMPLEMENTED' |
+/** Host-side runtime failure. */
+'INTERNAL' |
+/** Host unavailable (connection refused). */
+'UNAVAILABLE';
+declare class NetlistError extends Error {
+  readonly kind: NetlistErrorKind;
+  constructor(kind: NetlistErrorKind, message: string);
+}
+//#endregion
+//#region src/client.d.ts
+interface EdaHostClient {
+  /** Netlist of the currently selected components. */
+  getSelectionNetlist(): Promise<SchematicNetlist>;
+  /** Complete logical netlist for the current project. */
+  getProjectNetlist(): Promise<SchematicNetlist>;
+  /** Netlist of the current active schematic page. */
+  getActivePageNetlist(): Promise<SchematicNetlist>;
+}
+//#endregion
+//#region src/index.d.ts
+/** Plugin id — matches package.json. */
+declare const name = "@huaqiu/dsh-eda-host";
+/** Cordis services this half depends on. */
+declare const inject: readonly ["tools"];
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    edaHost: EdaHostClient;
+  }
+}
+/**
+ * Host plugin body — provide `edaHost` and register the three netlist tools.
+ *
+ * When no host base URL is configured, tools return ok:false with
+ * error.kind "FAILED_PRECONDITION" instead of throwing at load time: the
+ * plugin can be installed in standalone DSH where hq-edge is absent, and the
+ * tools degrade to a clear semantic message.
+ *
+ * @param ctx - real cordis context (node side).
+ * @returns disposer — unregisters the tools on plugin dispose.
+ */
+declare function apply(ctx: Context, config?: Partial<EdaHostConfig>): () => void;
+//#endregion
+export { type EdaHostClient, type EdaHostConfig, type ElectricalNet, type ElectricalType, NetlistError, type NetlistErrorKind, type PinDefinition, type PinReference, type SchematicComponent, type SchematicNetlist, apply, inject, name };

package/lib/index.mjs

@@ -0,0 +1,212 @@
+import { getLogger } from "@huaqiu/dsh-plugin-log";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+const SCOPE_ROUTE = {
+	project: "/project",
+	selection: "/selection",
+	"active-page": "/active-page"
+};
+function resolveEdaHostConfig(config, env = process.env) {
+	return {
+		hqEdgeBaseUrl: config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? "",
+		netlistPathPrefix: config?.netlistPathPrefix ?? env.HQ_EDGE_NETLIST_PATH ?? "/api/v1/netlist"
+	};
+}
+/** True when a host base URL is available (host mode). */
+function hasHost(config) {
+	return typeof config.hqEdgeBaseUrl === "string" && config.hqEdgeBaseUrl.trim().length > 0;
+}
+/** Build the absolute URL for one netlist scope. */
+function netlistUrlOf(config, scope) {
+	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.netlistPathPrefix ?? "/api/v1/netlist").replace(/^\/+|\/+$/g, "")}${SCOPE_ROUTE[scope]}`;
+}
+//#endregion
+//#region src/types.ts
+var NetlistError = class extends Error {
+	kind;
+	constructor(kind, message) {
+		super(message);
+		this.name = "NetlistError";
+		this.kind = kind;
+	}
+};
+//#endregion
+//#region src/client.ts
+/**
+* Netlist transport for `@huaqiu/dsh-eda-host`.
+*
+* DSH → dsh-eda-host → hq-edge → EDA Host is the ONLY production path. This
+* module fetches the semantic netlist from the hq-edge netlist router and
+* maps the HTTP status back to the semantic gRPC error categories. It never
+* parses schematic files and never touches KiCad.
+*
+* @module
+*/
+/** HTTP status → semantic error kind (see routes/netlist.ts on hq-edge). */
+function statusToKind(status) {
+	if (status === 412) return "FAILED_PRECONDITION";
+	if (status === 501) return "UNIMPLEMENTED";
+	if (status === 503) return "UNAVAILABLE";
+	return "INTERNAL";
+}
+function createEdaHostClient(config, deps = {}) {
+	const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+	async function fetchScope(scope) {
+		const url = netlistUrlOf(config, scope);
+		let response;
+		try {
+			response = await fetchImpl(url, {
+				method: "GET",
+				headers: { Accept: "application/json" }
+			});
+		} catch (err) {
+			throw new NetlistError("UNAVAILABLE", `eda-host: cannot reach hq-edge at ${url}: ${String(err?.message ?? err)}`);
+		}
+		if (!response.ok) {
+			let detail = "";
+			try {
+				const body = await response.json();
+				if (typeof body.detail === "string") detail = body.detail;
+			} catch {}
+			throw new NetlistError(statusToKind(response.status), `eda-host: netlist request failed (${response.status}${detail ? `: ${detail}` : ""})`);
+		}
+		const body = await response.json();
+		if (!body || typeof body.netlist !== "object" || body.netlist === null) throw new NetlistError("INTERNAL", "eda-host: malformed netlist response from hq-edge");
+		const netlist = body.netlist;
+		netlist.components ??= [];
+		netlist.nets ??= [];
+		return netlist;
+	}
+	return {
+		getSelectionNetlist: () => fetchScope("selection"),
+		getProjectNetlist: () => fetchScope("project"),
+		getActivePageNetlist: () => fetchScope("active-page")
+	};
+}
+//#endregion
+//#region src/tools.ts
+/**
+* Agent tools for `@huaqiu/dsh-eda-host`.
+*
+* Three semantic operations, one per netlist scope:
+*
+*   get_project_netlist     complete logical netlist of the current project
+*   get_selection_netlist   netlist of the currently selected components
+*   get_active_page_netlist netlist of the active schematic page
+*
+* The tools are pure pass-throughs: they call the hq-edge netlist router and
+* return the semantic `SchematicNetlist` as lossless JSON. Errors are
+* propagated with a semantic `kind` (FAILED_PRECONDITION / UNIMPLEMENTED /
+* INTERNAL / UNAVAILABLE) — never converted into a fake empty netlist. A
+* valid-but-empty netlist is `ok: true` with empty `components`/`nets`.
+*
+* @module
+*/
+/** The normalized domain values are lossless-JSON plain objects. */
+function asJson(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+function renderJson(_args, value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value)
+	}];
+}
+async function runScope(env, scope) {
+	try {
+		let netlist;
+		if (scope === "project") netlist = await env.client.getProjectNetlist();
+		else if (scope === "selection") netlist = await env.client.getSelectionNetlist();
+		else netlist = await env.client.getActivePageNetlist();
+		return {
+			ok: true,
+			scope,
+			netlist
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			scope,
+			error: {
+				kind: err instanceof NetlistError ? err.kind : "INTERNAL",
+				message: String(err?.message ?? err)
+			}
+		};
+	}
+}
+function scopeDescription(scope, extra) {
+	return "Read the current schematic netlist from the EDA host through hq-edge (DSH → dsh-eda-host → hq-edge → EDA host). " + extra + " The result is a semantic netlist JSON: { ok, scope, netlist: { components[], nets[] } }. Each component has referenceDesignators[], value, manufacturerPartNumber, footprint, description and pins[] (pinNumber, pinName, electricalType); each net has name and pinReferences[] (referenceDesignator, pinNumber). IMPORTANT SEMANTICS: ok:true with empty components/nets is a VALID empty design — do not treat it as a failure. On ok:false, error.kind distinguishes the cause: \"FAILED_PRECONDITION\" (no EDA host / no live editor — ask the user to open the design in the EDA editor first, then retry), \"UNIMPLEMENTED\" (this scope is not supported by the current host — do NOT retry; report it to the user), \"UNAVAILABLE\" (hq-edge host unreachable), \"INTERNAL\" (host-side failure). Do NOT fabricate netlist data.";
+}
+function createNetListTools(env) {
+	const mkTool = (scope, name, desc) => defineTool({
+		name,
+		description: desc,
+		parameters: {},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		async execute(_args, _exec) {
+			return asJson(await runScope(env, scope));
+		}
+	});
+	return [
+		mkTool("project", "get_project_netlist", scopeDescription("project", "Returns the complete logical netlist for the current project (all sheets, all nets).")),
+		mkTool("selection", "get_selection_netlist", scopeDescription("selection", "Returns the netlist associated with the currently selected schematic components, including the nets they participate in (each net lists every connected pin, not only the selected ones).")),
+		mkTool("active_page", "get_active_page_netlist", scopeDescription("active_page", "Returns the netlist for the currently active schematic page. NOTE: KiCad host does not implement this scope — expect ok:false with error.kind \"UNIMPLEMENTED\"."))
+	];
+}
+//#endregion
+//#region src/index.ts
+/** Plugin id — matches package.json. */
+const name = "@huaqiu/dsh-eda-host";
+/** Cordis services this half depends on. */
+const inject = ["tools"];
+const log = getLogger("dsh-eda-host");
+/**
+* Host plugin body — provide `edaHost` and register the three netlist tools.
+*
+* When no host base URL is configured, tools return ok:false with
+* error.kind "FAILED_PRECONDITION" instead of throwing at load time: the
+* plugin can be installed in standalone DSH where hq-edge is absent, and the
+* tools degrade to a clear semantic message.
+*
+* @param ctx - real cordis context (node side).
+* @returns disposer — unregisters the tools on plugin dispose.
+*/
+function apply(ctx, config = {}) {
+	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-eda-host requires the DSH `tools` service (ctx.tools.register).");
+	const resolved = resolveEdaHostConfig(config);
+	log.info("applying dsh-eda-host node half", {
+		hasHost: hasHost(resolved),
+		hqEdgeBaseUrl: resolved.hqEdgeBaseUrl ?? null,
+		netlistPathPrefix: resolved.netlistPathPrefix
+	});
+	let client;
+	if (hasHost(resolved)) client = createEdaHostClient(resolved);
+	else client = {
+		getProjectNetlist: async () => {
+			throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
+		},
+		getSelectionNetlist: async () => {
+			throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
+		},
+		getActivePageNetlist: async () => {
+			throw new NetlistError("FAILED_PRECONDITION", "eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — netlist tools require the hq-edge EDA host bridge.");
+		}
+	};
+	ctx.effect(() => ctx.provide("edaHost", client));
+	const tools = createNetListTools({ client });
+	const disposers = [];
+	for (const tool of tools) disposers.push(ctx.tools.register(tool));
+	log.info("dsh-eda-host node half ready", {
+		tools: 3,
+		hostMode: hasHost(resolved)
+	});
+	return () => {
+		for (const dispose of disposers) try {
+			dispose();
+		} catch {}
+	};
+}
+//#endregion
+export { NetlistError, apply, inject, name };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@huaqiu/dsh-eda-host",
+  "version": "0.3.20",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.0"
+  },
+  "dependencies": {
+    "@huaqiu/dsh-plugin-log": "0.3.20"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,90 @@
+/**
+ * Netlist transport for `@huaqiu/dsh-eda-host`.
+ *
+ * DSH → dsh-eda-host → hq-edge → EDA Host is the ONLY production path. This
+ * module fetches the semantic netlist from the hq-edge netlist router and
+ * maps the HTTP status back to the semantic gRPC error categories. It never
+ * parses schematic files and never touches KiCad.
+ *
+ * @module
+ */
+
+import { netlistUrlOf, type EdaHostConfig, type NetlistScope } from './config.js'
+import {
+  NetlistError,
+  type SchematicNetlist,
+} from './types.js'
+
+export interface EdaHostClientDeps {
+  fetchImpl?: typeof fetch
+}
+
+export interface EdaHostClient {
+  /** Netlist of the currently selected components. */
+  getSelectionNetlist(): Promise<SchematicNetlist>
+  /** Complete logical netlist for the current project. */
+  getProjectNetlist(): Promise<SchematicNetlist>
+  /** Netlist of the current active schematic page. */
+  getActivePageNetlist(): Promise<SchematicNetlist>
+}
+
+/** HTTP status → semantic error kind (see routes/netlist.ts on hq-edge). */
+function statusToKind(status: number): NetlistError['kind'] {
+  if (status === 412) return 'FAILED_PRECONDITION'
+  if (status === 501) return 'UNIMPLEMENTED'
+  if (status === 503) return 'UNAVAILABLE'
+  return 'INTERNAL'
+}
+
+export function createEdaHostClient(
+  config: EdaHostConfig,
+  deps: EdaHostClientDeps = {},
+): EdaHostClient {
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch
+
+  async function fetchScope(scope: NetlistScope): Promise<SchematicNetlist> {
+    const url = netlistUrlOf(config, scope)
+
+    let response: Response
+    try {
+      response = await fetchImpl(url, { method: 'GET', headers: { Accept: 'application/json' } })
+    } catch (err) {
+      // Connection-level failure: host not running / unreachable.
+      throw new NetlistError(
+        'UNAVAILABLE',
+        `eda-host: cannot reach hq-edge at ${url}: ${String((err as Error)?.message ?? err)}`,
+      )
+    }
+
+    if (!response.ok) {
+      let detail = ''
+      try {
+        const body = (await response.json()) as { detail?: unknown }
+        if (typeof body.detail === 'string') detail = body.detail
+      } catch {
+        // non-JSON error body — fall through with empty detail
+      }
+      throw new NetlistError(
+        statusToKind(response.status),
+        `eda-host: netlist request failed (${response.status}${detail ? `: ${detail}` : ''})`,
+      )
+    }
+
+    // Valid (possibly empty) result: { netlist: { components, nets } }.
+    const body = (await response.json()) as { netlist?: SchematicNetlist }
+    if (!body || typeof body.netlist !== 'object' || body.netlist === null) {
+      throw new NetlistError('INTERNAL', 'eda-host: malformed netlist response from hq-edge')
+    }
+
+    const netlist = body.netlist
+    netlist.components ??= []
+    netlist.nets ??= []
+    return netlist
+  }
+
+  return {
+    getSelectionNetlist: () => fetchScope('selection'),
+    getProjectNetlist: () => fetchScope('project'),
+    getActivePageNetlist: () => fetchScope('active-page'),
+  }
+}

package/src/config.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime config resolution for `@huaqiu/dsh-eda-host`.
+ *
+ * The plugin never opens a direct connection to the EDA host — it only talks
+ * to `hq-edge`, which owns the host session. The base URL is delivered by the
+ * hq-edge supervisor as overlay config (`hqEdgeBaseUrl`), with the
+ * `HQ_EDGE_BASE_URL` env as fallback for non-supervisor installs. This mirrors
+ * the `@huaqiu/dsh-auth` host-config convention.
+ *
+ * @module
+ */
+
+export interface EdaHostConfig {
+  /** HQ Edge base URL, e.g. "http://localhost:18080". Absent → no host. */
+  hqEdgeBaseUrl?: string
+  /** Path prefix on the host; default "/api/v1/netlist". */
+  netlistPathPrefix?: string
+}
+
+export const DEFAULT_NETLIST_PATH_PREFIX = '/api/v1/netlist'
+
+/** Scope → route suffix on the host netlist router. */
+export type NetlistScope = 'project' | 'selection' | 'active-page'
+
+export const SCOPE_ROUTE: Record<NetlistScope, string> = {
+  project: '/project',
+  selection: '/selection',
+  'active-page': '/active-page',
+}
+
+export function resolveEdaHostConfig(
+  config?: Partial<EdaHostConfig> | null,
+  env: NodeJS.ProcessEnv = process.env,
+): EdaHostConfig {
+  const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? ''
+  const pathPrefix =
+    config?.netlistPathPrefix ?? env.HQ_EDGE_NETLIST_PATH ?? DEFAULT_NETLIST_PATH_PREFIX
+  return {
+    hqEdgeBaseUrl: baseUrl,
+    netlistPathPrefix: pathPrefix,
+  }
+}
+
+/** True when a host base URL is available (host mode). */
+export function hasHost(config: EdaHostConfig): boolean {
+  return typeof config.hqEdgeBaseUrl === 'string' && config.hqEdgeBaseUrl.trim().length > 0
+}
+
+/** Build the absolute URL for one netlist scope. */
+export function netlistUrlOf(config: EdaHostConfig, scope: NetlistScope): string {
+  const base = (config.hqEdgeBaseUrl ?? '').replace(/\/+$/, '')
+  const prefix = (config.netlistPathPrefix ?? DEFAULT_NETLIST_PATH_PREFIX).replace(/^\/+|\/+$/g, '')
+  return `${base}/${prefix}${SCOPE_ROUTE[scope]}`
+}

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * `@huaqiu/dsh-eda-host` — node plugin entry.
+ *
+ * Provides the `edaHost` service (semantic EDA-host capability) and registers
+ * three agent tools:
+ *
+ *   get_project_netlist      complete project netlist
+ *   get_selection_netlist    currently selected components netlist
+ *   get_active_page_netlist  active schematic page netlist
+ *
+ * ── Architectural boundary (task: add-dsh-eda-host) ─────────────────────────
+ * The ONLY production request path is DSH → dsh-eda-host → hq-edge → EDA host.
+ * This plugin owns DSH integration only: it translates tool calls into hq-edge
+ * requests and returns the semantic `SchematicNetlist`. It contains no
+ * KiCad-specific logic, no schematic parsing, and no host IPC. The plugin is
+ * self-contained — no `@hqedge/*` dependency; the base URL is delivered by the
+ * hq-edge supervisor as overlay config (`hqEdgeBaseUrl`), with
+ * `HQ_EDGE_BASE_URL` as env fallback (same convention as `@huaqiu/dsh-auth`).
+ *
+ * @module @huaqiu/dsh-eda-host
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { getLogger } from '@huaqiu/dsh-plugin-log'
+import { createEdaHostClient, type EdaHostClient } from './client.js'
+import { hasHost, resolveEdaHostConfig, type EdaHostConfig } from './config.js'
+import { createNetListTools } from './tools.js'
+import { NetlistError } from './types.js'
+
+/** Plugin id — matches package.json. */
+export const name = '@huaqiu/dsh-eda-host'
+
+/** Cordis services this half depends on. */
+export const inject = ['tools'] as const
+
+export type { EdaHostConfig } from './config.js'
+export type { EdaHostClient } from './client.js'
+export type {
+  ElectricalNet,
+  ElectricalType,
+  NetlistErrorKind,
+  PinDefinition,
+  PinReference,
+  SchematicComponent,
+  SchematicNetlist,
+} from './types.js'
+export { NetlistError } from './types.js'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    edaHost: EdaHostClient
+  }
+}
+
+/** Shared component name for the unified DSH-plugin log. */
+const COMPONENT = 'dsh-eda-host'
+const log = getLogger(COMPONENT)
+
+/**
+ * Host plugin body — provide `edaHost` and register the three netlist tools.
+ *
+ * When no host base URL is configured, tools return ok:false with
+ * error.kind "FAILED_PRECONDITION" instead of throwing at load time: the
+ * plugin can be installed in standalone DSH where hq-edge is absent, and the
+ * tools degrade to a clear semantic message.
+ *
+ * @param ctx - real cordis context (node side).
+ * @returns disposer — unregisters the tools on plugin dispose.
+ */
+export function apply(ctx: Context, config: Partial<EdaHostConfig> = {}): () => void {
+  if (!ctx.tools || typeof ctx.tools.register !== 'function') {
+    throw new Error(
+      '@huaqiu/dsh-eda-host requires the DSH `tools` service (ctx.tools.register).',
+    )
+  }
+
+  const resolved = resolveEdaHostConfig(config)
+  log.info('applying dsh-eda-host node half', {
+    hasHost: hasHost(resolved),
+    hqEdgeBaseUrl: resolved.hqEdgeBaseUrl ?? null,
+    netlistPathPrefix: resolved.netlistPathPrefix,
+  })
+
+  let client: EdaHostClient
+
+  if (hasHost(resolved)) {
+    client = createEdaHostClient(resolved)
+  } else {
+    // Standalone install (no hq-edge supervisor): every scope degrades to
+    // FAILED_PRECONDITION with a clear message.
+    const unavailable: EdaHostClient = {
+      getProjectNetlist: async () => {
+        throw new NetlistError(
+          'FAILED_PRECONDITION',
+          'eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — ' +
+            'netlist tools require the hq-edge EDA host bridge.',
+        )
+      },
+      getSelectionNetlist: async () => {
+        throw new NetlistError(
+          'FAILED_PRECONDITION',
+          'eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — ' +
+            'netlist tools require the hq-edge EDA host bridge.',
+        )
+      },
+      getActivePageNetlist: async () => {
+        throw new NetlistError(
+          'FAILED_PRECONDITION',
+          'eda-host: no hq-edge base URL configured (hqEdgeBaseUrl / HQ_EDGE_BASE_URL) — ' +
+            'netlist tools require the hq-edge EDA host bridge.',
+        )
+      },
+    }
+    client = unavailable
+  }
+
+  ctx.effect(() => ctx.provide('edaHost', client))
+
+  const tools = createNetListTools({ client })
+  const disposers: Array<() => void> = []
+  for (const tool of tools) {
+    disposers.push(ctx.tools.register(tool))
+  }
+
+  log.info('dsh-eda-host node half ready', { tools: 3, hostMode: hasHost(resolved) })
+
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        // best-effort teardown
+      }
+    }
+  }
+}

package/src/tools.ts

@@ -0,0 +1,131 @@
+/**
+ * Agent tools for `@huaqiu/dsh-eda-host`.
+ *
+ * Three semantic operations, one per netlist scope:
+ *
+ *   get_project_netlist     complete logical netlist of the current project
+ *   get_selection_netlist   netlist of the currently selected components
+ *   get_active_page_netlist netlist of the active schematic page
+ *
+ * The tools are pure pass-throughs: they call the hq-edge netlist router and
+ * return the semantic `SchematicNetlist` as lossless JSON. Errors are
+ * propagated with a semantic `kind` (FAILED_PRECONDITION / UNIMPLEMENTED /
+ * INTERNAL / UNAVAILABLE) — never converted into a fake empty netlist. A
+ * valid-but-empty netlist is `ok: true` with empty `components`/`nets`.
+ *
+ * @module
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { EdaHostClient } from './client.js'
+import { NetlistError, type SchematicNetlist } from './types.js'
+
+/** Structural alias of the DSH `JsonValue`. */
+type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
+
+/** The normalized domain values are lossless-JSON plain objects. */
+function asJson<T>(value: T): Json {
+  return JSON.parse(JSON.stringify(value)) as Json
+}
+
+function renderJson(_args: unknown, value: unknown) {
+  return [{ type: 'text' as const, text: JSON.stringify(value) }]
+}
+
+export type NetlistScopeKind = 'project' | 'selection' | 'active_page'
+
+export interface NetlistToolEnv {
+  client: EdaHostClient
+}
+
+/** Tool execution context (structural view of DSH's ToolRunContext). */
+export interface ToolExecLike {
+  signal?: AbortSignal
+  callId?: string
+}
+
+type ScopeResult =
+  | { ok: true; scope: NetlistScopeKind; netlist: SchematicNetlist }
+  | { ok: false; scope: NetlistScopeKind; error: { kind: string; message: string } }
+
+async function runScope(
+  env: NetlistToolEnv,
+  scope: NetlistScopeKind,
+): Promise<ScopeResult> {
+  try {
+    let netlist: SchematicNetlist
+    if (scope === 'project') netlist = await env.client.getProjectNetlist()
+    else if (scope === 'selection') netlist = await env.client.getSelectionNetlist()
+    else netlist = await env.client.getActivePageNetlist()
+
+    return { ok: true, scope, netlist }
+  } catch (err) {
+    const kind =
+      err instanceof NetlistError
+        ? err.kind
+        : ('INTERNAL' as const)
+    const message = String((err as Error)?.message ?? err)
+    return { ok: false, scope, error: { kind, message } }
+  }
+}
+
+function scopeDescription(scope: NetlistScopeKind, extra: string): string {
+  return (
+    `Read the current schematic netlist from the EDA host through hq-edge ` +
+    `(DSH → dsh-eda-host → hq-edge → EDA host). ` +
+    extra +
+    ` The result is a semantic netlist JSON: { ok, scope, netlist: { components[], nets[] } }. ` +
+    `Each component has referenceDesignators[], value, manufacturerPartNumber, footprint, ` +
+    `description and pins[] (pinNumber, pinName, electricalType); each net has name and ` +
+    `pinReferences[] (referenceDesignator, pinNumber). ` +
+    `IMPORTANT SEMANTICS: ok:true with empty components/nets is a VALID empty design — do not ` +
+    `treat it as a failure. On ok:false, error.kind distinguishes the cause: ` +
+    `"FAILED_PRECONDITION" (no EDA host / no live editor — ask the user to open the design in ` +
+    `the EDA editor first, then retry), "UNIMPLEMENTED" (this scope is not supported by the ` +
+    `current host — do NOT retry; report it to the user), "UNAVAILABLE" (hq-edge host unreachable), ` +
+    `"INTERNAL" (host-side failure). Do NOT fabricate netlist data.`
+  )
+}
+
+export function createNetListTools(env: NetlistToolEnv) {
+  const mkTool = (scope: NetlistScopeKind, name: string, desc: string) =>
+    defineTool({
+      name,
+      description: desc,
+      parameters: {},
+      output: { schema: { type: 'json' }, render: renderJson },
+      async execute(_args: unknown, _exec: ToolExecLike) {
+        return asJson(await runScope(env, scope))
+      },
+    })
+
+  return [
+    mkTool(
+      'project',
+      'get_project_netlist',
+      scopeDescription(
+        'project',
+        'Returns the complete logical netlist for the current project (all sheets, all nets).',
+      ),
+    ),
+    mkTool(
+      'selection',
+      'get_selection_netlist',
+      scopeDescription(
+        'selection',
+        'Returns the netlist associated with the currently selected schematic components, ' +
+          'including the nets they participate in (each net lists every connected pin, not ' +
+          'only the selected ones).',
+      ),
+    ),
+    mkTool(
+      'active_page',
+      'get_active_page_netlist',
+      scopeDescription(
+        'active_page',
+        'Returns the netlist for the currently active schematic page. NOTE: KiCad host does ' +
+          'not implement this scope — expect ok:false with error.kind "UNIMPLEMENTED".',
+      ),
+    ),
+  ]
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+/**
+ * Semantic netlist types for `@huaqiu/dsh-eda-host`.
+ *
+ * Self-contained structural mirror of `hq.ir.schematic.v1` (the hq-edge-owned
+ * semantic protobuf contract). The plugin intentionally does NOT depend on
+ * `@hqedge/*` — this file is the only place the wire shapes are named, so
+ * keeping them aligned with the proto is a one-file concern.
+ *
+ * @module
+ */
+
+/** Electrical type of a pin — mirrors `hq.ir.logical.v1.ElectricalType`. */
+export type ElectricalType =
+  | 'ELECTRICAL_TYPE_UNSPECIFIED'
+  | 'ELECTRICAL_TYPE_INPUT'
+  | 'ELECTRICAL_TYPE_OUTPUT'
+  | 'ELECTRICAL_TYPE_BIDIRECTIONAL'
+  | 'ELECTRICAL_TYPE_TRISTATE'
+  | 'ELECTRICAL_TYPE_PASSIVE'
+  | 'ELECTRICAL_TYPE_POWER_IN'
+  | 'ELECTRICAL_TYPE_POWER_OUT'
+  | 'ELECTRICAL_TYPE_OPEN_COLLECTOR'
+  | 'ELECTRICAL_TYPE_OPEN_EMITTER'
+  | 'ELECTRICAL_TYPE_NO_CONNECT'
+
+export interface PinDefinition {
+  pinNumber: string
+  pinName: string
+  electricalType: ElectricalType
+}
+
+export interface SchematicComponent {
+  referenceDesignators: string[]
+  value: string
+  manufacturerPartNumber: string
+  footprint: string
+  description: string
+  pins: PinDefinition[]
+}
+
+export interface PinReference {
+  referenceDesignator: string
+  pinNumber: string
+}
+
+export interface ElectricalNet {
+  name: string
+  portName?: string
+  pinReferences: PinReference[]
+}
+
+export interface SchematicNetlist {
+  components: SchematicComponent[]
+  nets: ElectricalNet[]
+}
+
+/**
+ * Semantic error categories for netlist retrieval. Mirrors the gRPC status
+ * contract of `hq.ir.schematic.v1.NetListService` so an agent can distinguish
+ * "valid but empty" from "cannot answer at all".
+ */
+export type NetlistErrorKind =
+  /** No EDA host is reachable (hq-edge not configured / host down). */
+  | 'FAILED_PRECONDITION'
+  /** The host does not implement this scope (e.g. active page on KiCad). */
+  | 'UNIMPLEMENTED'
+  /** Host-side runtime failure. */
+  | 'INTERNAL'
+  /** Host unavailable (connection refused). */
+  | 'UNAVAILABLE'
+
+export class NetlistError extends Error {
+  readonly kind: NetlistErrorKind
+
+  constructor(kind: NetlistErrorKind, message: string) {
+    super(message)
+    this.name = 'NetlistError'
+    this.kind = kind
+  }
+}