@huaqiu/dsh-tool-part-search 0.1.1

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,62 @@
+# @huaqiu/dsh-tool-part-search
+
+Huaqiu PCB part search DSH tool plugin — **node half only**. Exposes the Huaqiu
+public part-search API as four agent-visible tools:
+
+| Tool | Operation |
+| --- | --- |
+| `search_hqsch_parts` | `PartSearchService.searchParts` |
+| `get_hqsch_part` | `PartSearchService.getPart` |
+| `get_hqsch_part_models` | `PartSearchService.getEdaModels` |
+| `get_hqsch_supply_chain` | `PartSearchService.getSupplyChain` |
+
+## Architecture
+
+- **Phase 1** — the first published DSH plugin. It is the smallest vertical
+  slice that validates the whole packaging path: `package.json` →
+  `cordis.patch.yml` → plugin loading → `ctx.tools` → `defineTool` → npm
+  publish → stock DSH install → tool invocation.
+- **`@huaqiu/part-search`** (published, public, unauthenticated) is the **single
+  implementation** of the Huaqiu part-search integration. This plugin only
+  adapts it into DSH tools — there is no HQ Edge, no HTTP proxy, no
+  `@hqedge/*` dependency.
+- Node only: part search returns JSON, never renders UI → no client bundle.
+- Self-contained: the plugin talks directly to `https://kiapi.eda.cn` (the
+  library's hardcoded upstream) with the global `fetch`.
+
+## Files
+
+```
+src/
+  index.ts      # plugin: name / inject ['tools'] / apply (registers 4 tools)
+  service.ts    # thin PartSearchService adapter (the Huaqiu → DSH boundary)
+  tools.ts      # the four defineTool definitions (the DSH tool adapter)
+test/
+  index.test.ts # plugin shape + registration
+  tools.test.ts # arg mapping + render, against a stub service
+  service.test.ts # library wiring via a stub fetch
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @huaqiu/dsh-tool-part-search typecheck
+pnpm --filter @huaqiu/dsh-tool-part-search test
+pnpm --filter @huaqiu/dsh-tool-part-search build
+pnpm --filter @huaqiu/dsh-tool-part-search pack --dry-run   # release check
+```
+
+## Install / verify on a stock DSH
+
+```bash
+dsh plugin --profile web add /path/to/dsh-pcb-eda/packages/dsh-tool-part-search
+dsh --profile web --dump-config
+dsh web
+```
+
+Then ask the agent to `search_hqsch_parts` (e.g. query "STM32F103").
+
+## Status
+
+Phase 1 complete. Version 0.1.0 ready to publish.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# DSH bundle patch: inserts the Huaqiu part-search tool plugin into a profile's layer stack.
+- insert:
+    - id: huaqiu-tool-part-search
+      name: '@huaqiu/dsh-tool-part-search'
+      inject: ['tools']

package/lib/index.d.mts

@@ -0,0 +1,19 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/index.d.ts
+/** Plugin id — matches package.json. */
+declare const name = "@huaqiu/dsh-tool-part-search";
+/** Cordis services this half depends on: the DSH node tool registry. */
+declare const inject: readonly ["tools"];
+/**
+ * Host plugin body — register the four agent-visible part-search tools.
+ *
+ * A single shared `PartSearchService` instance is created per plugin so every
+ * tool reuses the same client (and test/stub injection point).
+ *
+ * @param ctx - real cordis context (node side).
+ * @returns disposer — unregisters all four tools on plugin dispose. No
+ *   duplicate tools can survive a reload.
+ */
+declare function apply(ctx: Context): () => void;
+//#endregion
+export { apply, inject, name };

package/lib/index.mjs

@@ -0,0 +1,281 @@
+import { createPartSearchService } from "@huaqiu/part-search";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/service.ts
+/**
+* Huaqiu part-search service adapter — the thin separation between the
+* `@huaqiu/part-search` library and the DSH tool layer.
+*
+* The library (`PartSearchService`) is the single implementation of the Huaqiu
+* public part-search API and returns the normalized domain model. This module
+* only:
+*
+*   - owns the client lifecycle (one shared service instance per plugin),
+*   - narrows the surface to what the four tools call,
+*   - stays DSH-free (no cordis imports) so it is trivially unit-testable.
+*
+* The upstream base URL is intentionally NOT configurable here: the library
+* hardcodes `https://kiapi.eda.cn` and the whole point of Phase 1 is that the
+* plugin is a self-contained, public, unauthenticated capability.
+*
+* @module @huaqiu/dsh-tool-part-search/service
+*/
+/**
+* Create the Huaqiu part-search service used by all four tools.
+*
+* @param options - optional client options (language / timeout / fetch / logger).
+*   Omitted in production so the library defaults apply (global fetch, 15s
+*   timeout, zh). Tests pass a stub `fetch` or replace the returned instance.
+* @returns a ready-to-use service.
+*/
+function createPartSearch(options) {
+	return createPartSearchService(options);
+}
+//#endregion
+//#region src/tools.ts
+/**
+* The four Huaqiu part-search DSH tools — the DSH tool adapter layer.
+*
+* This module is a **pure adapter**: every tool reads validated arguments,
+* calls one `PartSearchServiceLike` operation (see `service.ts`), and returns
+* the normalized domain model as its canonical JSON value. It never touches the
+* wire protocol, `@huaqiu/part-search` internals, or any DSH host service.
+*
+* The agent-facing contracts (names, descriptions, snake_case parameters) are
+* preserved verbatim from the original HQ Edge plugin so existing agent
+* behaviors keep working after the migration.
+*
+* Error model: `PartSearchError` subclasses thrown by the service propagate to
+* the DSH tool runtime, which surfaces the message to the model as a tool
+* failure (same observable contract as the old HQ Edge proxy, which threw on
+* upstream failure).
+*
+* @module @huaqiu/dsh-tool-part-search/tools
+*/
+/** Per-tool cooperative execution budget (ms). The upstream may be a fresh
+*  fetch (~15s); give headroom so `exec.signal` aborts gracefully. */
+const TOOL_TIMEOUT_MS = 3e4;
+/** Deterministic model content for every canonical part-search value. The value
+*  is already the normalized domain model from `@huaqiu/part-search`. */
+function renderJson(_args, value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value)
+	}];
+}
+/**
+* The normalized domain model is plain JSON **except** that optional fields
+* are present as `undefined`, which is not lossless JSON and fails the DSH
+* runtime's canonical-value validation. The JSON round-trip strips
+* `undefined` properties (and array holes → null) so the canonical value is
+* always valid lossless JSON.
+*/
+function asJson(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+/** The language param shared by detail / models lookups. */
+const LANGUAGE_PARAM = {
+	type: "string",
+	enum: ["en", "zh"],
+	description: "Response language. Default \"zh\"."
+};
+/**
+* Build the four part-search tool definitions.
+*
+* @param service - the Huaqiu part-search service the tools call. Pass the
+*   shared instance from `index.ts` (or a stub in tests).
+* @returns the four registry-ready tool definitions.
+*/
+function createPartSearchTools(service) {
+	return [
+		defineTool({
+			name: "search_hqsch_parts",
+			description: "Search electronic components / ICs / PCB parts by keyword through HQSCH (Huaqiu EDA). Returns candidate parts with MPN, manufacturer, package, description, and EDA-model availability flags. Use this when the user asks for part selection, component lookup, finding ICs, resistors, capacitors, or any electronic parts suitable for EDA/PCB design. By default only parts with available EDA models (schematic symbol / PCB footprint) are returned. Progressive retrieval is recommended: search_hqsch_parts → get_hqsch_part → get_hqsch_part_models / get_hqsch_supply_chain.",
+			parameters: {
+				query: {
+					type: "string",
+					required: true,
+					description: "Search keyword: a partial MPN (e.g. \"STM32F103\"), a description (\"32-bit microcontroller 72MHz\"), or a combined value (\"0402 10k resistor\"). Max 200 characters. Matching is fuzzy — related models may appear."
+				},
+				page: {
+					type: "integer",
+					description: "1-based page index. Default 1."
+				},
+				page_size: {
+					type: "integer",
+					description: "Page size, 1-50. Default 10."
+				},
+				require_eda_model: {
+					type: "boolean",
+					description: "When true (default), only return parts that have any EDA model. Set false to search across all parts (e.g. for research)."
+				},
+				requirements: {
+					type: "object",
+					additionalProperties: false,
+					description: "Fine-grained model requirements. All optional booleans: { symbol, footprint, model3d, simulation, supplier }.",
+					properties: {
+						symbol: {
+							type: "boolean",
+							description: "Require a schematic symbol."
+						},
+						footprint: {
+							type: "boolean",
+							description: "Require a PCB footprint."
+						},
+						model3d: {
+							type: "boolean",
+							description: "Require a 3D model."
+						},
+						simulation: {
+							type: "boolean",
+							description: "Require a simulation model."
+						},
+						supplier: {
+							type: "boolean",
+							description: "Require supplier/stock data."
+						}
+					}
+				},
+				language: LANGUAGE_PARAM
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: TOOL_TIMEOUT_MS,
+			async execute(args) {
+				return asJson(await service.searchParts({
+					query: args.query,
+					page: args.page,
+					pageSize: args.page_size,
+					requireEdaModel: args.require_eda_model,
+					requirements: args.requirements,
+					language: args.language
+				}));
+			}
+		}),
+		defineTool({
+			name: "get_hqsch_part",
+			description: "Get the canonical detailed part from HQSCH (Huaqiu EDA) by manufacturer id + MPN. Returns attributes, categories, documents (datasheets), images, EDA-model metadata (symbol/footprint/3D/simulation URLs), and tags. Use this after search_hqsch_parts to inspect a specific candidate. The part MUST be identified by both manufacturerId and mpn — partial identifiers are not accepted.",
+			parameters: {
+				manufacturer_id: {
+					type: "string",
+					required: true,
+					description: "Huaqiu manufacturer id (e.g. \"7189\" for STMicroelectronics)."
+				},
+				mpn: {
+					type: "string",
+					required: true,
+					description: "Manufacturer part number (e.g. \"STM32F410T8Y6TR\")."
+				},
+				language: LANGUAGE_PARAM
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: TOOL_TIMEOUT_MS,
+			async execute(args) {
+				const identifier = toPartIdentifier(args);
+				return asJson(await service.getPart(identifier, args.language));
+			}
+		}),
+		defineTool({
+			name: "get_hqsch_part_models",
+			description: "Get EDA model metadata (schematic symbol / PCB footprint / 3D / simulation) for a HQSCH (Huaqiu EDA) part by manufacturer id + MPN. Returns URLs and format hints — does NOT download the model files. Use this when you need to know which models exist and where to fetch them, without retrieving the full part detail.",
+			parameters: {
+				manufacturer_id: {
+					type: "string",
+					required: true,
+					description: "Huaqiu manufacturer id (e.g. \"7189\" for STMicroelectronics)."
+				},
+				mpn: {
+					type: "string",
+					required: true,
+					description: "Manufacturer part number (e.g. \"STM32F410T8Y6TR\")."
+				},
+				language: LANGUAGE_PARAM
+			},
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: TOOL_TIMEOUT_MS,
+			async execute(args) {
+				const identifier = toPartIdentifier(args);
+				return asJson(await service.getEdaModels(identifier, args.language));
+			}
+		}),
+		defineTool({
+			name: "get_hqsch_supply_chain",
+			description: "Get supply-chain offers (vendor, stock, MOQ, lead time, price breaks, distributor URL) for one or more HQSCH (Huaqiu EDA) parts by manufacturer id + MPN. Batched lookup is supported — pass an array of parts. Use this AFTER identifying a specific part via search_hqsch_parts / get_hqsch_part, when procurement or availability information is needed.",
+			parameters: { parts: {
+				type: "array",
+				required: true,
+				description: "Array of parts to look up supply-chain offers for.",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						manufacturer_id: {
+							type: "string",
+							required: true
+						},
+						mpn: {
+							type: "string",
+							required: true
+						}
+					}
+				}
+			} },
+			output: {
+				schema: { type: "json" },
+				render: renderJson
+			},
+			timeoutMs: TOOL_TIMEOUT_MS,
+			async execute(args) {
+				const parts = args.parts.map((part) => ({
+					manufacturerId: part.manufacturer_id,
+					mpn: part.mpn
+				}));
+				return asJson(await service.getSupplyChain(parts));
+			}
+		})
+	];
+}
+/** Narrow the shared `manufacturer_id` + `mpn` args into a PartIdentifier. */
+function toPartIdentifier(args) {
+	return {
+		manufacturerId: args.manufacturer_id,
+		mpn: args.mpn
+	};
+}
+//#endregion
+//#region src/index.ts
+/** Plugin id — matches package.json. */
+const name = "@huaqiu/dsh-tool-part-search";
+/** Cordis services this half depends on: the DSH node tool registry. */
+const inject = ["tools"];
+/** Console tag for filtering in logs. */
+const LOG_TAG = "[dsh-part-search]";
+/**
+* Host plugin body — register the four agent-visible part-search tools.
+*
+* A single shared `PartSearchService` instance is created per plugin so every
+* tool reuses the same client (and test/stub injection point).
+*
+* @param ctx - real cordis context (node side).
+* @returns disposer — unregisters all four tools on plugin dispose. No
+*   duplicate tools can survive a reload.
+*/
+function apply(ctx) {
+	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-tool-part-search requires the DSH `tools` service (ctx.tools.register).");
+	const disposers = createPartSearchTools(createPartSearch()).map((tool) => ctx.tools.register(tool));
+	console.log(LOG_TAG, "registered agent tools", { tools: disposers.length });
+	return function dispose() {
+		for (const disposeTool of disposers) try {
+			disposeTool();
+		} catch {}
+	};
+}
+//#endregion
+export { apply, inject, name };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@huaqiu/dsh-tool-part-search",
+  "version": "0.1.1",
+  "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.8 <0.2.0"
+  },
+  "dependencies": {
+    "@huaqiu/part-search": "^0.2.0"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Huaqiu EDA Part Search DSH tool plugin (node half) — `@huaqiu/dsh-tool-part-search`.
+ *
+ * Exposes the Huaqiu public part-search capability as four agent-visible tools:
+ *
+ *   search_hqsch_parts        → PartSearchService.searchParts
+ *   get_hqsch_part            → PartSearchService.getPart
+ *   get_hqsch_part_models     → PartSearchService.getEdaModels
+ *   get_hqsch_supply_chain    → PartSearchService.getSupplyChain
+ *
+ * ── Architectural boundary (migration plan §1/§8/§20) ───────────────────────
+ * Phase 1 makes this the first published DSH plugin and the smallest vertical
+ * slice: package.json → cordis.patch.yml → plugin loading → ctx.tools →
+ * defineTool → npm publish → stock DSH install → tool invocation. The Huaqiu
+ * integration is owned exactly once by the `@huaqiu/part-search` library; this
+ * plugin calls that library directly (no HQ Edge, no HTTP proxy, no
+ * `@hqedge/*` dependency).
+ *
+ * ── Why no client half ───────────────────────────────────────────────────────
+ * Part search is a node-only capability: it returns JSON, never renders UI.
+ * `inject = ['tools']` resolves the DSH node tool registry.
+ *
+ * @module @huaqiu/dsh-tool-part-search
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { createPartSearch } from './service.js'
+import { createPartSearchTools } from './tools.js'
+
+/** Plugin id — matches package.json. */
+export const name = '@huaqiu/dsh-tool-part-search'
+
+/** Cordis services this half depends on: the DSH node tool registry. */
+export const inject = ['tools'] as const
+
+/** Console tag for filtering in logs. */
+const LOG_TAG = '[dsh-part-search]'
+
+/**
+ * Host plugin body — register the four agent-visible part-search tools.
+ *
+ * A single shared `PartSearchService` instance is created per plugin so every
+ * tool reuses the same client (and test/stub injection point).
+ *
+ * @param ctx - real cordis context (node side).
+ * @returns disposer — unregisters all four tools on plugin dispose. No
+ *   duplicate tools can survive a reload.
+ */
+export function apply(ctx: Context): () => void {
+  if (!ctx.tools || typeof ctx.tools.register !== 'function') {
+    throw new Error('@huaqiu/dsh-tool-part-search requires the DSH `tools` service (ctx.tools.register).')
+  }
+
+  const service = createPartSearch()
+  const disposers = createPartSearchTools(service).map((tool) => ctx.tools.register(tool))
+
+  // eslint-disable-next-line no-console
+  console.log(LOG_TAG, 'registered agent tools', { tools: disposers.length })
+
+  return function dispose() {
+    for (const disposeTool of disposers) {
+      try {
+        disposeTool()
+      } catch {
+        // One failing unregister must not hide the others.
+      }
+    }
+  }
+}

package/src/service.ts

@@ -0,0 +1,57 @@
+/**
+ * Huaqiu part-search service adapter — the thin separation between the
+ * `@huaqiu/part-search` library and the DSH tool layer.
+ *
+ * The library (`PartSearchService`) is the single implementation of the Huaqiu
+ * public part-search API and returns the normalized domain model. This module
+ * only:
+ *
+ *   - owns the client lifecycle (one shared service instance per plugin),
+ *   - narrows the surface to what the four tools call,
+ *   - stays DSH-free (no cordis imports) so it is trivially unit-testable.
+ *
+ * The upstream base URL is intentionally NOT configurable here: the library
+ * hardcodes `https://kiapi.eda.cn` and the whole point of Phase 1 is that the
+ * plugin is a self-contained, public, unauthenticated capability.
+ *
+ * @module @huaqiu/dsh-tool-part-search/service
+ */
+
+import {
+  createPartSearchService,
+  type EdaModels,
+  type Part,
+  type PartIdentifier,
+  type PartSearchClientOptions,
+  type PartSearchPage,
+  type SearchPartsOptions,
+  type SupplyOffer,
+} from '@huaqiu/part-search'
+
+/**
+ * The operations the four DSH tools need. Declared as a structural interface so
+ * tests can inject a stub without touching the network.
+ */
+export interface PartSearchServiceLike {
+  searchParts(options: SearchPartsOptions): Promise<PartSearchPage>
+  getPart(input: PartIdentifier, language?: string): Promise<Part>
+  getEdaModels(input: PartIdentifier, language?: string): Promise<EdaModels>
+  getSupplyChain(parts: readonly PartIdentifier[]): Promise<SupplyOffer[]>
+}
+
+/** Options for {@link createPartSearchService}. */
+export type PartSearchServiceOptions = PartSearchClientOptions
+
+/**
+ * Create the Huaqiu part-search service used by all four tools.
+ *
+ * @param options - optional client options (language / timeout / fetch / logger).
+ *   Omitted in production so the library defaults apply (global fetch, 15s
+ *   timeout, zh). Tests pass a stub `fetch` or replace the returned instance.
+ * @returns a ready-to-use service.
+ */
+export function createPartSearch(options?: PartSearchServiceOptions): PartSearchServiceLike {
+  return createPartSearchService(options)
+}
+
+export type { Part, PartIdentifier, PartSearchPage, SearchPartsOptions, SupplyOffer }

package/src/tools.ts

@@ -0,0 +1,230 @@
+/**
+ * The four Huaqiu part-search DSH tools — the DSH tool adapter layer.
+ *
+ * This module is a **pure adapter**: every tool reads validated arguments,
+ * calls one `PartSearchServiceLike` operation (see `service.ts`), and returns
+ * the normalized domain model as its canonical JSON value. It never touches the
+ * wire protocol, `@huaqiu/part-search` internals, or any DSH host service.
+ *
+ * The agent-facing contracts (names, descriptions, snake_case parameters) are
+ * preserved verbatim from the original HQ Edge plugin so existing agent
+ * behaviors keep working after the migration.
+ *
+ * Error model: `PartSearchError` subclasses thrown by the service propagate to
+ * the DSH tool runtime, which surfaces the message to the model as a tool
+ * failure (same observable contract as the old HQ Edge proxy, which threw on
+ * upstream failure).
+ *
+ * @module @huaqiu/dsh-tool-part-search/tools
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { PartIdentifier } from '@huaqiu/part-search'
+import type { PartSearchServiceLike } from './service.js'
+
+/**
+ * Structural alias of the DSH `JsonValue` (dsh-session). Kept local so the
+ * plugin does not need `@deepseek-ai/dsh-session` as a direct dependency for
+ * a type only; the alias is structurally identical to `JsonValue`, which is
+ * what `defineTool`'s `{ type: 'json' }` output infers.
+ */
+type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
+
+/** Per-tool cooperative execution budget (ms). The upstream may be a fresh
+ *  fetch (~15s); give headroom so `exec.signal` aborts gracefully. */
+const TOOL_TIMEOUT_MS = 30_000
+
+/** Deterministic model content for every canonical part-search value. The value
+ *  is already the normalized domain model from `@huaqiu/part-search`. */
+function renderJson(_args: unknown, value: unknown) {
+  return [{ type: 'text' as const, text: JSON.stringify(value) }]
+}
+
+/**
+ * The normalized domain model is plain JSON **except** that optional fields
+ * are present as `undefined`, which is not lossless JSON and fails the DSH
+ * runtime's canonical-value validation. The JSON round-trip strips
+ * `undefined` properties (and array holes → null) so the canonical value is
+ * always valid lossless JSON.
+ */
+function asJson<T>(value: T): Json {
+  return JSON.parse(JSON.stringify(value)) as Json
+}
+
+/** The language param shared by detail / models lookups. */
+const LANGUAGE_PARAM = {
+  type: 'string',
+  enum: ['en', 'zh'],
+  description: 'Response language. Default "zh".',
+} as const
+
+/**
+ * Build the four part-search tool definitions.
+ *
+ * @param service - the Huaqiu part-search service the tools call. Pass the
+ *   shared instance from `index.ts` (or a stub in tests).
+ * @returns the four registry-ready tool definitions.
+ */
+export function createPartSearchTools(service: PartSearchServiceLike) {
+  return [
+    defineTool({
+      name: 'search_hqsch_parts',
+      description:
+        'Search electronic components / ICs / PCB parts by keyword through HQSCH (Huaqiu EDA). ' +
+        'Returns candidate parts with MPN, manufacturer, package, description, and EDA-model ' +
+        'availability flags. Use this when the user asks for part selection, component lookup, ' +
+        'finding ICs, resistors, capacitors, or any electronic parts suitable for EDA/PCB design. ' +
+        'By default only parts with available EDA models (schematic symbol / PCB footprint) are ' +
+        'returned. Progressive retrieval is recommended: search_hqsch_parts → get_hqsch_part → ' +
+        'get_hqsch_part_models / get_hqsch_supply_chain.',
+      parameters: {
+        query: {
+          type: 'string',
+          required: true,
+          description:
+            'Search keyword: a partial MPN (e.g. "STM32F103"), a description ' +
+            '("32-bit microcontroller 72MHz"), or a combined value ("0402 10k resistor"). ' +
+            'Max 200 characters. Matching is fuzzy — related models may appear.',
+        },
+        page: {
+          type: 'integer',
+          description: '1-based page index. Default 1.',
+        },
+        page_size: {
+          type: 'integer',
+          description: 'Page size, 1-50. Default 10.',
+        },
+        require_eda_model: {
+          type: 'boolean',
+          description:
+            'When true (default), only return parts that have any EDA model. ' +
+            'Set false to search across all parts (e.g. for research).',
+        },
+        requirements: {
+          type: 'object',
+          additionalProperties: false,
+          description:
+            'Fine-grained model requirements. All optional booleans: ' +
+            '{ symbol, footprint, model3d, simulation, supplier }.',
+          properties: {
+            symbol: { type: 'boolean', description: 'Require a schematic symbol.' },
+            footprint: { type: 'boolean', description: 'Require a PCB footprint.' },
+            model3d: { type: 'boolean', description: 'Require a 3D model.' },
+            simulation: { type: 'boolean', description: 'Require a simulation model.' },
+            supplier: { type: 'boolean', description: 'Require supplier/stock data.' },
+          },
+        },
+        language: LANGUAGE_PARAM,
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      timeoutMs: TOOL_TIMEOUT_MS,
+      async execute(args) {
+        const page = await service.searchParts({
+          query: args.query,
+          page: args.page,
+          pageSize: args.page_size,
+          requireEdaModel: args.require_eda_model,
+          requirements: args.requirements,
+          language: args.language,
+        })
+        return asJson(page)
+      },
+    }),
+
+    defineTool({
+      name: 'get_hqsch_part',
+      description:
+        'Get the canonical detailed part from HQSCH (Huaqiu EDA) by manufacturer id + MPN. ' +
+        'Returns attributes, categories, documents (datasheets), images, EDA-model metadata ' +
+        '(symbol/footprint/3D/simulation URLs), and tags. Use this after ' +
+        'search_hqsch_parts to inspect a specific candidate. The part MUST be identified by ' +
+        'both manufacturerId and mpn — partial identifiers are not accepted.',
+      parameters: {
+        manufacturer_id: {
+          type: 'string',
+          required: true,
+          description: 'Huaqiu manufacturer id (e.g. "7189" for STMicroelectronics).',
+        },
+        mpn: {
+          type: 'string',
+          required: true,
+          description: 'Manufacturer part number (e.g. "STM32F410T8Y6TR").',
+        },
+        language: LANGUAGE_PARAM,
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      timeoutMs: TOOL_TIMEOUT_MS,
+      async execute(args) {
+        const identifier = toPartIdentifier(args)
+        return asJson(await service.getPart(identifier, args.language))
+      },
+    }),
+
+    defineTool({
+      name: 'get_hqsch_part_models',
+      description:
+        'Get EDA model metadata (schematic symbol / PCB footprint / 3D / simulation) for a ' +
+        'HQSCH (Huaqiu EDA) part by manufacturer id + MPN. Returns URLs and format hints — ' +
+        'does NOT download the model files. Use this when you need to know which models exist ' +
+        'and where to fetch them, without retrieving the full part detail.',
+      parameters: {
+        manufacturer_id: {
+          type: 'string',
+          required: true,
+          description: 'Huaqiu manufacturer id (e.g. "7189" for STMicroelectronics).',
+        },
+        mpn: {
+          type: 'string',
+          required: true,
+          description: 'Manufacturer part number (e.g. "STM32F410T8Y6TR").',
+        },
+        language: LANGUAGE_PARAM,
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      timeoutMs: TOOL_TIMEOUT_MS,
+      async execute(args) {
+        const identifier = toPartIdentifier(args)
+        return asJson(await service.getEdaModels(identifier, args.language))
+      },
+    }),
+
+    defineTool({
+      name: 'get_hqsch_supply_chain',
+      description:
+        'Get supply-chain offers (vendor, stock, MOQ, lead time, price breaks, distributor ' +
+        'URL) for one or more HQSCH (Huaqiu EDA) parts by manufacturer id + MPN. Batched ' +
+        'lookup is supported — pass an array of parts. Use this AFTER identifying a specific ' +
+        'part via search_hqsch_parts / get_hqsch_part, when procurement or availability ' +
+        'information is needed.',
+      parameters: {
+        parts: {
+          type: 'array',
+          required: true,
+          description: 'Array of parts to look up supply-chain offers for.',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              manufacturer_id: { type: 'string', required: true },
+              mpn: { type: 'string', required: true },
+            },
+          },
+        },
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      timeoutMs: TOOL_TIMEOUT_MS,
+      async execute(args) {
+        const parts: PartIdentifier[] = args.parts.map((part) => ({
+          manufacturerId: part.manufacturer_id,
+          mpn: part.mpn,
+        }))
+        return asJson(await service.getSupplyChain(parts))
+      },
+    }),
+  ]
+}
+
+/** Narrow the shared `manufacturer_id` + `mpn` args into a PartIdentifier. */
+function toPartIdentifier(args: { manufacturer_id: string; mpn: string }): PartIdentifier {
+  return { manufacturerId: args.manufacturer_id, mpn: args.mpn }
+}