@huaqiu/dsh-tool-quote 0.0.0-stage → 0.5.3

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/cordis.patch.yml

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

package/lib/index.d.mts

@@ -0,0 +1,64 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+/**
+ * Runtime config resolution for `@huaqiu/dsh-tool-quote`.
+ *
+ * The plugin never opens a direct connection to the price providers — it only
+ * talks to `hq-edge`, which owns the quote capability (hq.fab.v1.QuoteService
+ * bridged over HTTP, see apps/server/src/routes/quote.ts on hq-edge). The base
+ * URL is delivered by the hq-edge supervisor as overlay config
+ * (`hqEdgeBaseUrl`), with `HQ_EDGE_BASE_URL` as env fallback — the same
+ * convention as `@huaqiu/dsh-eda-host` / `@huaqiu/dsh-auth`.
+ *
+ * @module
+ */
+interface QuoteToolConfig {
+  /** HQ Edge base URL, e.g. "http://localhost:18080". Absent → no host. */
+  hqEdgeBaseUrl?: string;
+  /** Path prefix on the host; default "/api/v1/quote". */
+  quotePathPrefix?: string;
+  /** End-to-end budget for one quote request, in milliseconds (default 30_000). */
+  requestTimeoutMs?: number;
+}
+//#endregion
+//#region src/client.d.ts
+/** Semantic failure of a quote request, mirroring hq-edge's envelope kinds. */
+declare class QuoteToolError extends Error {
+  readonly kind: string;
+  readonly status: number;
+  readonly detail?: string | undefined;
+  readonly code?: string | number | undefined;
+  constructor(kind: string, message: string, status: number, detail?: string | undefined, code?: string | number | undefined);
+}
+//#endregion
+//#region src/index.d.ts
+/** Plugin id — matches package.json. */
+declare const name = "@huaqiu/dsh-tool-quote";
+/** Cordis services this half depends on: the node tool registry + hq-edge
+ *  bridge (REQUIRED — quote cannot work standalone). */
+declare const inject: readonly ["hqEdge", "tools"];
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /**
+     * Provided by the hq-edge `edge-bridge` plugin (the HOST). `baseUrl` is
+     * the loopback HQ Edge endpoint, e.g. "http://localhost:18080". Read
+     * lazily on every request; REQUIRED for this plugin to load.
+     */
+    hqEdge: {
+      baseUrl?: string;
+    };
+  }
+}
+/**
+ * Host plugin body — register the two quote tools.
+ *
+ * The HQ Edge endpoint is resolved lazily at request time from the
+ * `ctx.hqEdge` service (edge-bridge), falling back to the overlay config /
+ * `HQ_EDGE_BASE_URL` env (same convention as `@huaqiu/dsh-eda-host`).
+ *
+ * @param ctx - real cordis context (node side).
+ * @returns disposer — unregisters the tools on plugin dispose.
+ */
+declare function apply(ctx: Context, config?: Partial<QuoteToolConfig>): () => void;
+//#endregion
+export { type QuoteToolConfig, QuoteToolError, apply, inject, name };

package/lib/index.mjs

@@ -0,0 +1,384 @@
+import { getLogger } from "@huaqiu/dsh-plugin-log";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+function resolveQuoteToolConfig(config, env = process.env) {
+	const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? "";
+	const pathPrefix = config?.quotePathPrefix ?? env.HQ_EDGE_QUOTE_PATH ?? "/api/v1/quote";
+	const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS;
+	const timeout = Number.parseInt(String(timeoutRaw ?? ""), 10);
+	return {
+		hqEdgeBaseUrl: baseUrl,
+		quotePathPrefix: pathPrefix,
+		requestTimeoutMs: Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS
+	};
+}
+/** 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 quote kind route ("pcb" | "smt"). */
+function quoteUrlOf(config, kind) {
+	return `${(config.hqEdgeBaseUrl ?? "").replace(/\/+$/, "")}/${(config.quotePathPrefix ?? "/api/v1/quote").replace(/^\/+|\/+$/g, "")}/${kind}`;
+}
+//#endregion
+//#region src/client.ts
+/** Semantic failure of a quote request, mirroring hq-edge's envelope kinds. */
+var QuoteToolError = class extends Error {
+	kind;
+	status;
+	detail;
+	code;
+	constructor(kind, message, status, detail, code) {
+		super(message);
+		this.kind = kind;
+		this.status = status;
+		this.detail = detail;
+		this.code = code;
+		this.name = "QuoteToolError";
+	}
+};
+/** HTTP status → semantic kind (hq-edge envelope, mirrors eda-host mapping). */
+function statusToKind(status) {
+	if (status === 400) return "VALIDATION";
+	if (status === 501) return "UNIMPLEMENTED";
+	if (status === 503) return "UNAVAILABLE";
+	if (status === 504) return "DEADLINE_EXCEEDED";
+	return "INTERNAL";
+}
+function isAbortError(err) {
+	const name = err?.name;
+	return name === "AbortError" || name === "TimeoutError";
+}
+function resolveSignal(deadlineMs, caller) {
+	const signals = [caller, deadlineMs > 0 ? AbortSignal.timeout(deadlineMs) : void 0].filter((s) => Boolean(s));
+	if (signals.length === 0) return void 0;
+	if (signals.length === 1) return signals[0];
+	const anyFn = AbortSignal.any;
+	return typeof anyFn === "function" ? anyFn.call(AbortSignal, signals) : signals[0];
+}
+function createQuoteToolClient(config, deps = {}) {
+	const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+	const resolveBaseUrl = () => {
+		const fromService = deps.baseUrlResolver?.();
+		const base = fromService?.trim().length ? fromService : config.hqEdgeBaseUrl;
+		if (!base || base.trim().length === 0) throw new QuoteToolError("FAILED_PRECONDITION", "quote: no hq-edge base URL available (edge-bridge service or HQ_EDGE_BASE_URL)", 412);
+		return base.trim();
+	};
+	const request = async (kind, payload, options = {}) => {
+		const base = resolveBaseUrl();
+		const url = quoteUrlOf({
+			...config,
+			hqEdgeBaseUrl: base
+		}, kind);
+		const signal = resolveSignal(config.requestTimeoutMs ?? 0, options.signal);
+		try {
+			const response = await fetchImpl(url, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(payload),
+				signal
+			});
+			const text = await response.text();
+			let body;
+			try {
+				body = text.length > 0 ? JSON.parse(text) : null;
+			} catch {
+				body = null;
+			}
+			if (!response.ok) {
+				const envelope = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+				throw new QuoteToolError(typeof envelope.error === "string" ? envelope.error : statusToKind(response.status), typeof envelope.detail === "string" ? envelope.detail : "quote request failed", response.status, typeof envelope.detail === "string" ? envelope.detail : void 0, typeof envelope.code === "string" || typeof envelope.code === "number" ? envelope.code : void 0);
+			}
+			return body;
+		} catch (err) {
+			if (err instanceof QuoteToolError) throw err;
+			if (isAbortError(err)) throw new QuoteToolError("DEADLINE_EXCEEDED", "quote request timed out", 504);
+			throw new QuoteToolError("INTERNAL", `quote request failed: ${String(err)}`, 500);
+		}
+	};
+	return {
+		quotePcb: (payload, options) => request("pcb", payload, options),
+		quoteSmt: (payload, options) => request("smt", payload, options)
+	};
+}
+//#endregion
+//#region src/tools.ts
+/**
+* Agent tools for `@huaqiu/dsh-tool-quote`.
+*
+*   quote_pcb   real-time PCB fabrication price for the requested region
+*   quote_smt   real-time SMT assembly price (single-side / double-side)
+*
+* The tools are pure pass-throughs: they read validated arguments, build the
+* canonical quote request (matching hq.fab.v1.QuoteService / the hq-edge
+* router contract), call hq-edge via the client, and return the normalized
+* QuotePrice as lossless JSON. Errors carry a semantic `kind`
+* (FAILED_PRECONDITION / VALIDATION / UNIMPLEMENTED / UPSTREAM_REJECTED /
+* DEADLINE_EXCEEDED / INTERNAL) — the agent sees why a quote failed, not a
+* bare HTTP status.
+*
+* Note on enums: only the enumerated choices are accepted, mirroring the
+* proto/type definitions on hq-edge. Unknown fields are rejected upstream
+* (Zod .strict()), so the tools never send unsupported keys.
+*
+* @module
+*/
+function asJson(value) {
+	return JSON.parse(JSON.stringify(value));
+}
+function renderJson(_args, value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value)
+	}];
+}
+/** Pick the EDA derivation flags (only when explicitly true). */
+function edaOf(args) {
+	const eda = {};
+	if (args.derive_board_size === true) eda.deriveBoardSize = true;
+	if (args.derive_board_stackup === true) eda.deriveBoardStackup = true;
+	return Object.keys(eda).length > 0 ? eda : void 0;
+}
+function createQuoteTools(env) {
+	const { client } = env;
+	/** Build the canonical PCB form from the flat tool args. */
+	const pcbFormOf = (a) => {
+		const form = {};
+		if (a.bcount !== void 0) form.bcount = a.bcount;
+		if (a.blayer !== void 0) form.blayer = a.blayer;
+		if (a.blength !== void 0) form.blength = a.blength;
+		if (a.bwidth !== void 0) form.bwidth = a.bwidth;
+		if (a.board_tg !== void 0) form.boardTg = a.board_tg;
+		if (a.color !== void 0) form.color = a.color;
+		if (a.cover !== void 0) form.cover = a.cover;
+		if (a.spray !== void 0) form.spray = a.spray;
+		return Object.keys(form).length > 0 ? form : void 0;
+	};
+	/** Optional EDA-host derivation flags shared by both tools. */
+	const edaFlagProps = {
+		derive_board_size: {
+			type: "boolean",
+			description: "When true, ask hq-edge to derive board length/width from the current PCB board (approximate bounding box of footprints; only when a board is open in the host)."
+		},
+		derive_board_stackup: {
+			type: "boolean",
+			description: "NOT SUPPORTED (explicit capability gap): hq-edge has no board-properties source, so stack-up is never derived or fabricated. Provide blayer/bheight explicitly instead."
+		},
+		include_raw_response: {
+			type: "boolean",
+			description: "Include the bounded raw upstream payload for diagnostics (default false)."
+		}
+	};
+	return [defineTool({
+		name: "quote_pcb",
+		description: "Get a real-time PCB fabrication price quote (multi-layer, panel pricing, delivery options) for the requested region through Huaqiu/NextPCB. Use when the user asks how much a PCB would cost, \"报价\", \"价格\", delivery time estimates, or comparing fab options. Returns the itemized price breakdown, total price, and delivery alternatives (name + build time in days + total price) with currency symbol (¥ CN / ￥ intl). When derive_board_size / derive_board_stackup is set, the response also carries the effective quote form: EDA-extracted board facts (length/width from the board outline, layer count + thickness from the stack-up in KiCad) merged with the caller overrides — plus server defaults applied on the wire (e.g. bcount default 5). Inspect \"form\" in the result, adjust any parameter the user wants to change (e.g. color, blayer, board_tg), and re-query with the corrected form rather than guessing values. Progressive usage: quote_pcb for PCB fabrication, quote_smt for assembly, then the user places the order in the EDA host. This is a quote-only query — no order is created.",
+		parameters: {
+			region: {
+				type: "string",
+				enum: [
+					"cn",
+					"eu_us",
+					"jp"
+				],
+				required: true,
+				description: "Pricing region. \"cn\" = Huaqiu China (eda.cn, ¥), \"eu_us\" = NextPCB EU/US, \"jp\" = NextPCB Japan (both ￥)."
+			},
+			bcount: {
+				type: "integer",
+				description: "Panel quantity (boards per panel), >= 1. Default 5."
+			},
+			blayer: {
+				type: "integer",
+				description: "PCB layer count, 1-64. Default 4."
+			},
+			blength: {
+				type: "number",
+				description: "Board length in mm, > 0 (canonical mm; converted to cm on the wire)."
+			},
+			bwidth: {
+				type: "number",
+				description: "Board width in mm, > 0."
+			},
+			board_tg: {
+				type: "string",
+				enum: [
+					"tg130",
+					"tg150",
+					"tg170"
+				],
+				description: "Glass transition temperature grade (4+ layers only)."
+			},
+			color: {
+				type: "string",
+				enum: [
+					"green",
+					"red",
+					"yellow",
+					"blue",
+					"white",
+					"black",
+					"matte_black"
+				],
+				description: "Solder mask color. Default green."
+			},
+			cover: {
+				type: "string",
+				enum: [
+					"covered",
+					"exposed",
+					"solder_mask_plug",
+					"non_conductive_fill"
+				],
+				description: "Via process (tenting / open / solder-mask-plug / non-conductive fill). Default covered."
+			},
+			spray: {
+				type: "string",
+				enum: [
+					"hasl_lead",
+					"hasl_lf",
+					"enig",
+					"osp"
+				],
+				description: "Surface finish. Default HASL (lead)."
+			},
+			...edaFlagProps
+		},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		async execute(args, exec) {
+			const a = args;
+			const payload = {
+				region: a.region,
+				form: pcbFormOf(a),
+				eda: edaOf(a),
+				includeRawResponse: a.include_raw_response === true
+			};
+			return asJson(await client.quotePcb(payload, { signal: exec.signal }));
+		}
+	}), defineTool({
+		name: "quote_smt",
+		description: "Get a real-time SMT assembly price quote (single/double side, stencil, X-ray, conformal coating, Huaqiu agent part purchasing) for the requested region through Huaqiu/NextPCB. Use when the user asks about assembly costs, \"贴片价格\", \"SMT 报价\", \"焊接费用\", or delivery time for assembly. Embeds the PCB order (layers/size/quantity) used for the assembly quote. Returns the normalized price with SMT fee detail (no-tax, total, tax) and currency symbol. When derive_board_size / derive_board_stackup is set, the response carries the effective form: EDA-extracted board facts (panel size, embedded PCB length/width/layers/thickness) merged with the caller overrides — inspect \"form\" and re-query with corrected parameters instead of guessing. Quote-only — no order is created.",
+		parameters: {
+			region: {
+				type: "string",
+				enum: [
+					"cn",
+					"eu_us",
+					"jp"
+				],
+				required: true,
+				description: "Pricing region. \"cn\" = Huaqiu China (eda.cn, ¥), \"eu_us\" = NextPCB EU/US, \"jp\" = NextPCB Japan (both ￥)."
+			},
+			number: {
+				type: "string",
+				description: "Assembly quantity as string (e.g. \"5\"). Default \"5\"."
+			},
+			buy_bom: {
+				type: "string",
+				enum: [
+					"hq_select",
+					"user_upload",
+					"online_match"
+				],
+				description: "BOM parts source: hq_select = Huaqiu agent purchasing (default), user_upload = customer parts, online_match = online parts matching."
+			},
+			single_or_double_technique: {
+				type: "string",
+				enum: ["single", "double"],
+				description: "Single-side or double-side assembly. Default double."
+			},
+			pcb_blayer: {
+				type: "integer",
+				description: "Embedded PCB layer count, 1-64 (assembly quote depends on the PCB order). Default 4."
+			},
+			pcb_blength: {
+				type: "number",
+				description: "Embedded PCB board length in mm, > 0."
+			},
+			pcb_bwidth: {
+				type: "number",
+				description: "Embedded PCB board width in mm, > 0."
+			},
+			pcb_bcount: {
+				type: "integer",
+				description: "Embedded PCB panel quantity, >= 1. Default 5."
+			},
+			...edaFlagProps
+		},
+		output: {
+			schema: { type: "json" },
+			render: renderJson
+		},
+		async execute(args, exec) {
+			const a = args;
+			const form = {};
+			if (a.number !== void 0) form.number = a.number;
+			if (a.buy_bom !== void 0) form.buyBom = a.buy_bom;
+			if (a.single_or_double_technique !== void 0) form.singleOrDoubleTechnique = a.single_or_double_technique;
+			const pcb = {};
+			if (a.pcb_blayer !== void 0) pcb.blayer = a.pcb_blayer;
+			if (a.pcb_blength !== void 0) pcb.blength = a.pcb_blength;
+			if (a.pcb_bwidth !== void 0) pcb.bwidth = a.pcb_bwidth;
+			if (a.pcb_bcount !== void 0) pcb.bcount = a.pcb_bcount;
+			if (Object.keys(pcb).length > 0) form.pcbOrder = pcb;
+			const payload = {
+				region: a.region,
+				form: Object.keys(form).length > 0 ? form : void 0,
+				eda: edaOf(a),
+				includeRawResponse: a.include_raw_response === true
+			};
+			return asJson(await client.quoteSmt(payload, { signal: exec.signal }));
+		}
+	})];
+}
+//#endregion
+//#region src/index.ts
+/** Plugin id — matches package.json. */
+const name = "@huaqiu/dsh-tool-quote";
+/** Cordis services this half depends on: the node tool registry + hq-edge
+*  bridge (REQUIRED — quote cannot work standalone). */
+const inject = ["hqEdge", "tools"];
+/** Shared component name for the unified DSH-plugin log. */
+const COMPONENT = "dsh-tool-quote";
+let _log = null;
+function log() {
+	if (_log === null) _log = getLogger(COMPONENT);
+	return _log;
+}
+/**
+* Host plugin body — register the two quote tools.
+*
+* The HQ Edge endpoint is resolved lazily at request time from the
+* `ctx.hqEdge` service (edge-bridge), falling back to the overlay config /
+* `HQ_EDGE_BASE_URL` env (same convention as `@huaqiu/dsh-eda-host`).
+*
+* @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-tool-quote requires the DSH `tools` service (ctx.tools.register).");
+	const resolved = resolveQuoteToolConfig(config);
+	const hq = ctx.hqEdge;
+	if (!hq || typeof hq.baseUrl !== "string" || hq.baseUrl.trim().length === 0) throw new Error("@huaqiu/dsh-tool-quote requires a usable hq-edge context: the edge-bridge plugin did not provide ctx.hqEdge.baseUrl. Quote tools cannot work without hq-edge — check that the bridge started and that the HQ Edge port is valid.");
+	const getHqEdgeBaseUrl = () => {
+		const current = ctx.hqEdge;
+		return current?.baseUrl && current.baseUrl.trim().length > 0 ? current.baseUrl : void 0;
+	};
+	log().info("applying dsh-tool-quote node half", {
+		hasConfigHost: hasHost(resolved),
+		hqEdgeBaseUrlFromConfig: resolved.hqEdgeBaseUrl ?? null,
+		quotePathPrefix: resolved.quotePathPrefix,
+		requestTimeoutMs: resolved.requestTimeoutMs
+	});
+	const disposers = createQuoteTools({ client: createQuoteToolClient(resolved, { baseUrlResolver: getHqEdgeBaseUrl }) }).map((tool) => ctx.tools.register(tool));
+	log().info("dsh-tool-quote node half ready", { tools: disposers.length });
+	return () => {
+		for (const dispose of disposers) try {
+			dispose();
+		} catch {}
+	};
+}
+//#endregion
+export { QuoteToolError, apply, inject, name };

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@huaqiu/dsh-tool-quote",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.3",
+  "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.5.3"
+  },
+  "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,154 @@
+/**
+ * Transport for `@huaqiu/dsh-tool-quote`.
+ *
+ * DSH → dsh-tool-quote → hq-edge → price provider is the ONLY production
+ * path. This module POSTs the canonical quote request to the hq-edge quote
+ * router, maps the stable error envelope back to semantic kinds, and enforces
+ * the single end-to-end request budget. It contains no provider logic — that
+ * lives in hq-edge (apps/server/src/quote/*).
+ *
+ * hq-edge error envelope (stable contract):
+ *
+ *   { error, detail, code?, status?, operation? }
+ *
+ *     error   → VALIDATION | UNIMPLEMENTED | UPSTREAM_HTTP | UPSTREAM_REJECTED
+ *               | PARSE | UNAVAILABLE | INTERNAL
+ *     status  → 400 | 501 | 502 | 503 | 504 | 500
+ *
+ * @module
+ */
+
+import type { QuoteToolConfig } from './config.js'
+import { quoteUrlOf } from './config.js'
+
+export type QuoteKind = 'pcb' | 'smt'
+
+export interface QuoteToolClientDeps {
+  fetchImpl?: typeof fetch
+  /** Late-bound resolver for the HQ Edge base URL (edge-bridge service). */
+  baseUrlResolver?: () => string | undefined
+}
+
+export interface QuoteToolRequestOptions {
+  signal?: AbortSignal
+}
+
+/** Semantic failure of a quote request, mirroring hq-edge's envelope kinds. */
+export class QuoteToolError extends Error {
+  constructor(
+    readonly kind: string,
+    message: string,
+    readonly status: number,
+    readonly detail?: string,
+    readonly code?: string | number,
+  ) {
+    super(message)
+    this.name = 'QuoteToolError'
+  }
+}
+
+/** HTTP status → semantic kind (hq-edge envelope, mirrors eda-host mapping). */
+function statusToKind(status: number): string {
+  if (status === 400) return 'VALIDATION'
+  if (status === 501) return 'UNIMPLEMENTED'
+  if (status === 503) return 'UNAVAILABLE'
+  if (status === 504) return 'DEADLINE_EXCEEDED'
+  return 'INTERNAL'
+}
+
+function isAbortError(err: unknown): boolean {
+  const name = (err as Error | undefined)?.name
+  return name === 'AbortError' || name === 'TimeoutError'
+}
+
+function resolveSignal(deadlineMs: number, caller?: AbortSignal): AbortSignal | undefined {
+  const budget = deadlineMs > 0 ? AbortSignal.timeout(deadlineMs) : undefined
+  const signals = [caller, budget].filter((s): s is AbortSignal => Boolean(s))
+  if (signals.length === 0) return undefined
+  if (signals.length === 1) return signals[0]
+  const anyFn = (AbortSignal as unknown as { any?: (s: AbortSignal[]) => AbortSignal }).any
+  return typeof anyFn === 'function' ? anyFn.call(AbortSignal, signals) : signals[0]
+}
+
+export interface QuoteToolClient {
+  quotePcb(payload: unknown, options?: QuoteToolRequestOptions): Promise<unknown>
+  quoteSmt(payload: unknown, options?: QuoteToolRequestOptions): Promise<unknown>
+}
+
+export function createQuoteToolClient(
+  config: QuoteToolConfig,
+  deps: QuoteToolClientDeps = {},
+): QuoteToolClient {
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch
+
+  const resolveBaseUrl = (): string => {
+    const fromService = deps.baseUrlResolver?.()
+    const base = fromService?.trim().length ? fromService : config.hqEdgeBaseUrl
+    if (!base || base.trim().length === 0) {
+      throw new QuoteToolError(
+        'FAILED_PRECONDITION',
+        'quote: no hq-edge base URL available (edge-bridge service or HQ_EDGE_BASE_URL)',
+        412,
+      )
+    }
+    return base.trim()
+  }
+
+  const request = async (
+    kind: QuoteKind,
+    payload: unknown,
+    options: QuoteToolRequestOptions = {},
+  ): Promise<unknown> => {
+    const base = resolveBaseUrl()
+    const url = quoteUrlOf({ ...config, hqEdgeBaseUrl: base }, kind)
+    const signal = resolveSignal(config.requestTimeoutMs ?? 0, options.signal)
+    try {
+      const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+        signal,
+      })
+      const text = await response.text()
+      let body: unknown
+      try {
+        body = text.length > 0 ? JSON.parse(text) : null
+      } catch {
+        body = null
+      }
+      if (!response.ok) {
+        const envelope =
+          body && typeof body === 'object' && !Array.isArray(body)
+            ? (body as Record<string, unknown>)
+            : {}
+        const kindFromEnvelope =
+          typeof envelope.error === 'string' ? envelope.error : statusToKind(response.status)
+        throw new QuoteToolError(
+          kindFromEnvelope,
+          typeof envelope.detail === 'string' ? envelope.detail : 'quote request failed',
+          response.status,
+          typeof envelope.detail === 'string' ? envelope.detail : undefined,
+          typeof envelope.code === 'string' || typeof envelope.code === 'number'
+            ? envelope.code
+            : undefined,
+        )
+      }
+      return body
+    } catch (err) {
+      if (err instanceof QuoteToolError) throw err
+      if (isAbortError(err)) {
+        throw new QuoteToolError(
+          'DEADLINE_EXCEEDED',
+          'quote request timed out',
+          504,
+        )
+      }
+      throw new QuoteToolError('INTERNAL', `quote request failed: ${String(err)}`, 500)
+    }
+  }
+
+  return {
+    quotePcb: (payload, options) => request('pcb', payload, options),
+    quoteSmt: (payload, options) => request('smt', payload, options),
+  }
+}

package/src/config.ts

@@ -0,0 +1,57 @@
+/**
+ * Runtime config resolution for `@huaqiu/dsh-tool-quote`.
+ *
+ * The plugin never opens a direct connection to the price providers — it only
+ * talks to `hq-edge`, which owns the quote capability (hq.fab.v1.QuoteService
+ * bridged over HTTP, see apps/server/src/routes/quote.ts on hq-edge). The base
+ * URL is delivered by the hq-edge supervisor as overlay config
+ * (`hqEdgeBaseUrl`), with `HQ_EDGE_BASE_URL` as env fallback — the same
+ * convention as `@huaqiu/dsh-eda-host` / `@huaqiu/dsh-auth`.
+ *
+ * @module
+ */
+
+export interface QuoteToolConfig {
+  /** HQ Edge base URL, e.g. "http://localhost:18080". Absent → no host. */
+  hqEdgeBaseUrl?: string
+  /** Path prefix on the host; default "/api/v1/quote". */
+  quotePathPrefix?: string
+  /** End-to-end budget for one quote request, in milliseconds (default 30_000). */
+  requestTimeoutMs?: number
+}
+
+export const DEFAULT_QUOTE_PATH_PREFIX = '/api/v1/quote'
+
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000
+
+export function resolveQuoteToolConfig(
+  config?: Partial<QuoteToolConfig> | null,
+  env: NodeJS.ProcessEnv = process.env,
+): QuoteToolConfig {
+  const baseUrl = config?.hqEdgeBaseUrl ?? env.HQ_EDGE_BASE_URL ?? ''
+  const pathPrefix =
+    config?.quotePathPrefix ?? env.HQ_EDGE_QUOTE_PATH ?? DEFAULT_QUOTE_PATH_PREFIX
+  const timeoutRaw = config?.requestTimeoutMs ?? env.HQ_EDGE_REQUEST_TIMEOUT_MS
+  const timeout = Number.parseInt(String(timeoutRaw ?? ''), 10)
+  return {
+    hqEdgeBaseUrl: baseUrl,
+    quotePathPrefix: pathPrefix,
+    requestTimeoutMs:
+      Number.isFinite(timeout) && timeout > 0 ? timeout : DEFAULT_REQUEST_TIMEOUT_MS,
+  }
+}
+
+/** True when a host base URL is available (host mode). */
+export function hasHost(config: QuoteToolConfig): boolean {
+  return typeof config.hqEdgeBaseUrl === 'string' && config.hqEdgeBaseUrl.trim().length > 0
+}
+
+/** Build the absolute URL for one quote kind route ("pcb" | "smt"). */
+export function quoteUrlOf(config: QuoteToolConfig, kind: 'pcb' | 'smt'): string {
+  const base = (config.hqEdgeBaseUrl ?? '').replace(/\/+$/, '')
+  const prefix = (config.quotePathPrefix ?? DEFAULT_QUOTE_PATH_PREFIX).replace(
+    /^\/+|\/+$/g,
+    '',
+  )
+  return `${base}/${prefix}/${kind}`
+}

package/src/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Huaqiu EDA Quote DSH tool plugin (node half) — `@huaqiu/dsh-tool-quote`.
+ *
+ * Exposes real-time PCB / SMT price querying as two agent-visible tools:
+ *
+ *   quote_pcb   → hq-edge POST /api/v1/quote/pcb
+ *   quote_smt   → hq-edge POST /api/v1/quote/smt
+ *
+ * ── Architectural boundary ─────────────────────────────────────────────────
+ * Quote logic is owned ONCE by hq-edge (hq.fab.v1.QuoteService bridged over
+ * HTTP — apps/server/src/quote/*). This plugin is a thin adapter: it
+ * translates tool calls into canonical quote requests and returns the
+ * normalized QuotePrice. It contains NO provider logic (no eda.cn / nextpcb
+ * endpoints, no form serialization, no parsing) and no `@hqedge/*`
+ * dependency — it only talks to hq-edge through the edge-bridge.
+ *
+ * `hqEdge` is a REQUIRED inject: the plugin cannot reach hq-edge without the
+ * bridge's `ctx.hqEdge.baseUrl`. This matches the `@huaqiu/dsh-eda-host`
+ * contract (docs/tasks/expose-capability.md §3/§7) — quote tools are hq-edge
+ * capabilities, not standalone DSH features.
+ *
+ * @module @huaqiu/dsh-tool-quote
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { getLogger, type PluginLogger } from '@huaqiu/dsh-plugin-log'
+import { createQuoteToolClient } from './client.js'
+import {
+  hasHost,
+  resolveQuoteToolConfig,
+  type QuoteToolConfig,
+} from './config.js'
+import { createQuoteTools } from './tools.js'
+
+/** Plugin id — matches package.json. */
+export const name = '@huaqiu/dsh-tool-quote'
+
+/** Cordis services this half depends on: the node tool registry + hq-edge
+ *  bridge (REQUIRED — quote cannot work standalone). */
+export const inject = ['hqEdge', 'tools'] as const
+
+export type { QuoteToolConfig } from './config.js'
+export { QuoteToolError } from './client.js'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /**
+     * Provided by the hq-edge `edge-bridge` plugin (the HOST). `baseUrl` is
+     * the loopback HQ Edge endpoint, e.g. "http://localhost:18080". Read
+     * lazily on every request; REQUIRED for this plugin to load.
+     */
+    hqEdge: { baseUrl?: string }
+  }
+}
+
+/** Shared component name for the unified DSH-plugin log. */
+const COMPONENT = 'dsh-tool-quote'
+
+let _log: PluginLogger | null = null
+function log(): PluginLogger {
+  if (_log === null) _log = getLogger(COMPONENT)
+  return _log
+}
+
+/**
+ * Host plugin body — register the two quote tools.
+ *
+ * The HQ Edge endpoint is resolved lazily at request time from the
+ * `ctx.hqEdge` service (edge-bridge), falling back to the overlay config /
+ * `HQ_EDGE_BASE_URL` env (same convention as `@huaqiu/dsh-eda-host`).
+ *
+ * @param ctx - real cordis context (node side).
+ * @returns disposer — unregisters the tools on plugin dispose.
+ */
+export function apply(ctx: Context, config: Partial<QuoteToolConfig> = {}): () => void {
+  if (!ctx.tools || typeof ctx.tools.register !== 'function') {
+    throw new Error('@huaqiu/dsh-tool-quote requires the DSH `tools` service (ctx.tools.register).')
+  }
+
+  const resolved = resolveQuoteToolConfig(config)
+
+  const hq = ctx.hqEdge
+  if (!hq || typeof hq.baseUrl !== 'string' || hq.baseUrl.trim().length === 0) {
+    throw new Error(
+      '@huaqiu/dsh-tool-quote requires a usable hq-edge context: the edge-bridge ' +
+        'plugin did not provide ctx.hqEdge.baseUrl. Quote tools cannot work without ' +
+        'hq-edge — check that the bridge started and that the HQ Edge port is valid.',
+    )
+  }
+
+  const getHqEdgeBaseUrl = (): string | undefined => {
+    const current = ctx.hqEdge
+    return current?.baseUrl && current.baseUrl.trim().length > 0 ? current.baseUrl : undefined
+  }
+
+  log().info('applying dsh-tool-quote node half', {
+    hasConfigHost: hasHost(resolved),
+    hqEdgeBaseUrlFromConfig: resolved.hqEdgeBaseUrl ?? null,
+    quotePathPrefix: resolved.quotePathPrefix,
+    requestTimeoutMs: resolved.requestTimeoutMs,
+  })
+
+  const client = createQuoteToolClient(resolved, { baseUrlResolver: getHqEdgeBaseUrl })
+  const disposers = createQuoteTools({ client }).map((tool) => ctx.tools.register(tool))
+
+  log().info('dsh-tool-quote node half ready', { tools: disposers.length })
+
+  return () => {
+    for (const dispose of disposers) {
+      try {
+        dispose()
+      } catch {
+        // best-effort teardown
+      }
+    }
+  }
+}

package/src/tools.ts

@@ -0,0 +1,250 @@
+/**
+ * Agent tools for `@huaqiu/dsh-tool-quote`.
+ *
+ *   quote_pcb   real-time PCB fabrication price for the requested region
+ *   quote_smt   real-time SMT assembly price (single-side / double-side)
+ *
+ * The tools are pure pass-throughs: they read validated arguments, build the
+ * canonical quote request (matching hq.fab.v1.QuoteService / the hq-edge
+ * router contract), call hq-edge via the client, and return the normalized
+ * QuotePrice as lossless JSON. Errors carry a semantic `kind`
+ * (FAILED_PRECONDITION / VALIDATION / UNIMPLEMENTED / UPSTREAM_REJECTED /
+ * DEADLINE_EXCEEDED / INTERNAL) — the agent sees why a quote failed, not a
+ * bare HTTP status.
+ *
+ * Note on enums: only the enumerated choices are accepted, mirroring the
+ * proto/type definitions on hq-edge. Unknown fields are rejected upstream
+ * (Zod .strict()), so the tools never send unsupported keys.
+ *
+ * @module
+ */
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { QuoteToolClient } from './client.js'
+
+/** Structural alias of the DSH `JsonValue`. */
+type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
+
+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) }]
+}
+
+/** Tool execution context (structural view of DSH's ToolRunContext). */
+interface ToolExecLike {
+  signal?: AbortSignal
+  callId?: string
+}
+
+interface QuoteToolEnv {
+  client: QuoteToolClient
+}
+
+/** Pick the EDA derivation flags (only when explicitly true). */
+function edaOf(args: Record<string, unknown>): Record<string, unknown> | undefined {
+  const eda: Record<string, unknown> = {}
+  if (args.derive_board_size === true) eda.deriveBoardSize = true
+  if (args.derive_board_stackup === true) eda.deriveBoardStackup = true
+  return Object.keys(eda).length > 0 ? eda : undefined
+}
+
+export function createQuoteTools(env: QuoteToolEnv) {
+  const { client } = env
+
+  /** Build the canonical PCB form from the flat tool args. */
+  const pcbFormOf = (a: Record<string, unknown>): Record<string, unknown> | undefined => {
+    const form: Record<string, unknown> = {}
+    if (a.bcount !== undefined) form.bcount = a.bcount
+    if (a.blayer !== undefined) form.blayer = a.blayer
+    if (a.blength !== undefined) form.blength = a.blength
+    if (a.bwidth !== undefined) form.bwidth = a.bwidth
+    if (a.board_tg !== undefined) form.boardTg = a.board_tg
+    if (a.color !== undefined) form.color = a.color
+    if (a.cover !== undefined) form.cover = a.cover
+    if (a.spray !== undefined) form.spray = a.spray
+    return Object.keys(form).length > 0 ? form : undefined
+  }
+
+  /** Optional EDA-host derivation flags shared by both tools. */
+  const edaFlagProps = {
+    derive_board_size: {
+      type: 'boolean' as const,
+      description:
+        'When true, ask hq-edge to derive board length/width from the current PCB board ' +
+        '(approximate bounding box of footprints; only when a board is open in the host).',
+    },
+    derive_board_stackup: {
+      type: 'boolean' as const,
+      description:
+        'NOT SUPPORTED (explicit capability gap): hq-edge has no board-properties source, ' +
+        'so stack-up is never derived or fabricated. Provide blayer/bheight explicitly instead.',
+    },
+    include_raw_response: {
+      type: 'boolean' as const,
+      description: 'Include the bounded raw upstream payload for diagnostics (default false).',
+    },
+  }
+
+  return [
+    defineTool({
+      name: 'quote_pcb',
+      description:
+        'Get a real-time PCB fabrication price quote (multi-layer, panel pricing, delivery options) ' +
+        'for the requested region through Huaqiu/NextPCB. Use when the user asks how much a PCB ' +
+        'would cost, "报价", "价格", delivery time estimates, or comparing fab options. ' +
+        'Returns the itemized price breakdown, total price, and delivery alternatives ' +
+        '(name + build time in days + total price) with currency symbol (¥ CN / ￥ intl). ' +
+        'When derive_board_size / derive_board_stackup is set, the response also carries the ' +
+        'effective quote form: EDA-extracted board facts (length/width from the board outline, ' +
+        'layer count + thickness from the stack-up in KiCad) merged with the caller overrides — ' +
+        'plus server defaults applied on the wire (e.g. bcount default 5). Inspect "form" in the ' +
+        'result, adjust any parameter the user wants to change (e.g. color, blayer, board_tg), and ' +
+        're-query with the corrected form rather than guessing values. Progressive usage: quote_pcb ' +
+        'for PCB fabrication, quote_smt for assembly, then the user places the order in the EDA ' +
+        'host. This is a quote-only query — no order is created.',
+      parameters: {
+        region: {
+          type: 'string',
+          enum: ['cn', 'eu_us', 'jp'],
+          required: true,
+          description:
+            'Pricing region. "cn" = Huaqiu China (eda.cn, ¥), "eu_us" = NextPCB EU/US, ' +
+            '"jp" = NextPCB Japan (both ￥).',
+        },
+        bcount: {
+          type: 'integer',
+          description: 'Panel quantity (boards per panel), >= 1. Default 5.',
+        },
+        blayer: {
+          type: 'integer',
+          description: 'PCB layer count, 1-64. Default 4.',
+        },
+        blength: {
+          type: 'number',
+          description: 'Board length in mm, > 0 (canonical mm; converted to cm on the wire).',
+        },
+        bwidth: {
+          type: 'number',
+          description: 'Board width in mm, > 0.',
+        },
+        board_tg: {
+          type: 'string',
+          enum: ['tg130', 'tg150', 'tg170'],
+          description: 'Glass transition temperature grade (4+ layers only).',
+        },
+        color: {
+          type: 'string',
+          enum: ['green', 'red', 'yellow', 'blue', 'white', 'black', 'matte_black'],
+          description: 'Solder mask color. Default green.',
+        },
+        cover: {
+          type: 'string',
+          enum: ['covered', 'exposed', 'solder_mask_plug', 'non_conductive_fill'],
+          description:
+            'Via process (tenting / open / solder-mask-plug / non-conductive fill). Default covered.',
+        },
+        spray: {
+          type: 'string',
+          enum: ['hasl_lead', 'hasl_lf', 'enig', 'osp'],
+          description: 'Surface finish. Default HASL (lead).',
+        },
+        ...edaFlagProps,
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      async execute(args: unknown, exec: ToolExecLike): Promise<Json> {
+        const a = args as Record<string, unknown>
+        const payload = {
+          region: a.region,
+          form: pcbFormOf(a),
+          eda: edaOf(a),
+          includeRawResponse: a.include_raw_response === true,
+        }
+        const result = await client.quotePcb(payload, { signal: exec.signal })
+        return asJson(result)
+      },
+    }),
+    defineTool({
+      name: 'quote_smt',
+      description:
+        'Get a real-time SMT assembly price quote (single/double side, stencil, X-ray, conformal coating, ' +
+        'Huaqiu agent part purchasing) for the requested region through Huaqiu/NextPCB. Use when the user ' +
+        'asks about assembly costs, "贴片价格", "SMT 报价", "焊接费用", or delivery time for assembly. ' +
+        'Embeds the PCB order (layers/size/quantity) used for the assembly quote. Returns the normalized ' +
+        'price with SMT fee detail (no-tax, total, tax) and currency symbol. When derive_board_size / ' +
+        'derive_board_stackup is set, the response carries the effective form: EDA-extracted board facts ' +
+        '(panel size, embedded PCB length/width/layers/thickness) merged with the caller overrides — ' +
+        'inspect "form" and re-query with corrected parameters instead of guessing. Quote-only — no ' +
+        'order is created.',
+      parameters: {
+        region: {
+          type: 'string',
+          enum: ['cn', 'eu_us', 'jp'],
+          required: true,
+          description:
+            'Pricing region. "cn" = Huaqiu China (eda.cn, ¥), "eu_us" = NextPCB EU/US, ' +
+            '"jp" = NextPCB Japan (both ￥).',
+        },
+        number: {
+          type: 'string',
+          description: 'Assembly quantity as string (e.g. "5"). Default "5".',
+        },
+        buy_bom: {
+          type: 'string',
+          enum: ['hq_select', 'user_upload', 'online_match'],
+          description:
+            'BOM parts source: hq_select = Huaqiu agent purchasing (default), ' +
+            'user_upload = customer parts, online_match = online parts matching.',
+        },
+        single_or_double_technique: {
+          type: 'string',
+          enum: ['single', 'double'],
+          description: 'Single-side or double-side assembly. Default double.',
+        },
+        pcb_blayer: {
+          type: 'integer',
+          description:
+            'Embedded PCB layer count, 1-64 (assembly quote depends on the PCB order). Default 4.',
+        },
+        pcb_blength: {
+          type: 'number',
+          description: 'Embedded PCB board length in mm, > 0.',
+        },
+        pcb_bwidth: {
+          type: 'number',
+          description: 'Embedded PCB board width in mm, > 0.',
+        },
+        pcb_bcount: {
+          type: 'integer',
+          description: 'Embedded PCB panel quantity, >= 1. Default 5.',
+        },
+        ...edaFlagProps,
+      },
+      output: { schema: { type: 'json' }, render: renderJson },
+      async execute(args: unknown, exec: ToolExecLike): Promise<Json> {
+        const a = args as Record<string, unknown>
+        const form: Record<string, unknown> = {}
+        if (a.number !== undefined) form.number = a.number
+        if (a.buy_bom !== undefined) form.buyBom = a.buy_bom
+        if (a.single_or_double_technique !== undefined)
+          form.singleOrDoubleTechnique = a.single_or_double_technique
+        const pcb: Record<string, unknown> = {}
+        if (a.pcb_blayer !== undefined) pcb.blayer = a.pcb_blayer
+        if (a.pcb_blength !== undefined) pcb.blength = a.pcb_blength
+        if (a.pcb_bwidth !== undefined) pcb.bwidth = a.pcb_bwidth
+        if (a.pcb_bcount !== undefined) pcb.bcount = a.pcb_bcount
+        if (Object.keys(pcb).length > 0) form.pcbOrder = pcb
+        const payload = {
+          region: a.region,
+          form: Object.keys(form).length > 0 ? form : undefined,
+          eda: edaOf(a),
+          includeRawResponse: a.include_raw_response === true,
+        }
+        const result = await client.quoteSmt(payload, { signal: exec.signal })
+        return asJson(result)
+      },
+    }),
+  ]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.