@huaqiu/dsh-tool-pcb-viewer 0.4.1

package/lib/index.d.mts

@@ -0,0 +1,26 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/index.d.ts
+/** Plugin id — matches package.json. */
+declare const name = "@huaqiu/dsh-tool-pcb-viewer";
+/**
+ * Cordis services this half depends on.
+ */
+declare const inject: readonly ["tools", "systemPrompt", "webServer", "sessions"];
+interface PcbViewerPluginConfig {
+  /** max .kicad_pcb file size in bytes (default 120MB). */
+  maxFileBytes?: number;
+}
+interface BoardStats {
+  sizeKB: number;
+  comps: number;
+  pads: number;
+  traces: number;
+  zones: number;
+  vias: number;
+  layers: number;
+  widthMM: number;
+  heightMM: number;
+}
+declare function apply(ctx: Context, config?: PcbViewerPluginConfig): () => void;
+//#endregion
+export { BoardStats, PcbViewerPluginConfig, apply, inject, name };

package/lib/index.mjs

@@ -0,0 +1,616 @@
+import fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/pcb/parseKicad.ts
+function tokenize(src) {
+	const toks = [];
+	let i = 0;
+	const n = src.length;
+	while (i < n) {
+		const c = src[i];
+		if (c === " " || c === "	" || c === "\n" || c === "\r") {
+			i++;
+			continue;
+		}
+		if (c === ";") {
+			while (i < n && src[i] !== "\n") i++;
+			continue;
+		}
+		if (c === "(" || c === ")") {
+			toks.push(c);
+			i++;
+			continue;
+		}
+		if (c === "\"") {
+			let j = i + 1;
+			let s = "";
+			while (j < n && src[j] !== "\"") {
+				if (src[j] === "\\") {
+					const e = src[j + 1];
+					s += e === "n" ? "\n" : e === "t" ? "	" : e === "r" ? "\r" : e ?? "";
+					j += 2;
+					continue;
+				}
+				s += src[j];
+				j++;
+			}
+			toks.push("\"" + s);
+			i = j + 1;
+			continue;
+		}
+		let j = i;
+		while (j < n && !" 	\n\r()".includes(src[j])) j++;
+		toks.push(src.slice(i, j));
+		i = j;
+	}
+	return toks;
+}
+function parseSexp(toks) {
+	let pos = 0;
+	function parse() {
+		if (toks[pos] === "(") {
+			pos++;
+			const list = [];
+			while (pos < toks.length && toks[pos] !== ")") list.push(parse());
+			pos++;
+			return list;
+		}
+		return toks[pos++] ?? "";
+	}
+	const roots = [];
+	while (pos < toks.length) roots.push(parse());
+	return roots[0] ?? [];
+}
+const num = (v) => typeof v === "string" ? parseFloat(v) : NaN;
+const atom = (v) => typeof v === "string" ? v.replace(/^"/, "") : "";
+/** find first child list whose head matches */
+function child(list, head) {
+	for (const c of list) if (Array.isArray(c) && c[0] === head) return c;
+	return null;
+}
+function children(list, head) {
+	const out = [];
+	for (const c of list) if (Array.isArray(c) && c[0] === head) out.push(c);
+	return out;
+}
+/** (at x y [rot]) → {x,y,rot} */
+function parseAt(node) {
+	if (!node) return {
+		x: 0,
+		y: 0,
+		rot: 0
+	};
+	return {
+		x: num(node[1]),
+		y: num(node[2]),
+		rot: node[3] !== void 0 ? num(node[3]) : 0
+	};
+}
+const rad = (d) => d * Math.PI / 180;
+/** rotate local point by deg then translate */
+function xform(lx, ly, fp) {
+	const r = rad(fp.rot), cs = Math.cos(r), sn = Math.sin(r);
+	return [fp.x + lx * cs - ly * sn, fp.y + lx * sn + ly * cs];
+}
+function parseKicad(src) {
+	const root = parseSexp(tokenize(src));
+	if (!Array.isArray(root)) throw new Error("not a valid .kicad_pcb");
+	const netName = /* @__PURE__ */ new Map();
+	for (const n of children(root, "net")) netName.set(num(n[1]), atom(n[2]));
+	let cuLayers = [];
+	const layersNode = child(root, "layers");
+	if (layersNode) for (const L of layersNode.slice(1)) {
+		const nm = Array.isArray(L) ? atom(L[1]) : "";
+		if (nm.endsWith(".Cu")) cuLayers.push(nm);
+	}
+	cuLayers.sort((a, b) => {
+		const rank = (s) => s === "F.Cu" ? 0 : s === "B.Cu" ? 100 : 1 + (parseInt(s.replace(/\D+/g, "")) || 0);
+		return rank(a) - rank(b);
+	});
+	if (cuLayers.length < 2) cuLayers = ["F.Cu", "B.Cu"];
+	const outline = [];
+	const collectCuts = (nodes, kind) => {
+		for (const g of nodes) {
+			const layerN = child(g, "layer");
+			if (!layerN || atom(layerN[1]) !== "Edge.Cuts") continue;
+			if (kind === "line") {
+				const st = child(g, "start"), en = child(g, "end");
+				outline.push({
+					type: "line",
+					a: [num(st[1]), num(st[2])],
+					b: [num(en[1]), num(en[2])]
+				});
+			} else if (kind === "arc") {
+				const st = child(g, "start"), md = child(g, "mid"), en = child(g, "end");
+				outline.push({
+					type: "arc",
+					a: [num(st[1]), num(st[2])],
+					m: [num(md[1]), num(md[2])],
+					b: [num(en[1]), num(en[2])]
+				});
+			} else if (kind === "rect") {
+				const st = child(g, "start"), en = child(g, "end");
+				const a = [num(st[1]), num(st[2])];
+				const b = [num(en[1]), num(en[2])];
+				outline.push({
+					type: "line",
+					a,
+					b: [b[0], a[1]]
+				}, {
+					type: "line",
+					a: [b[0], a[1]],
+					b
+				}, {
+					type: "line",
+					a: b,
+					b: [a[0], b[1]]
+				}, {
+					type: "line",
+					a: [a[0], b[1]],
+					b: a
+				});
+			} else {
+				const cN = child(g, "center"), eN = child(g, "end");
+				const c = [num(cN[1]), num(cN[2])];
+				const e = [num(eN[1]), num(eN[2])];
+				outline.push({
+					type: "circle",
+					c,
+					r: Math.hypot(e[0] - c[0], e[1] - c[1])
+				});
+			}
+		}
+	};
+	for (const node of root) {
+		if (!Array.isArray(node)) continue;
+		if (node[0] === "gr_line") collectCuts([node], "line");
+		else if (node[0] === "gr_arc") collectCuts([node], "arc");
+		else if (node[0] === "gr_rect") collectCuts([node], "rect");
+		else if (node[0] === "gr_circle") collectCuts([node], "circle");
+	}
+	const comps = [];
+	for (const fpNode of children(root, "footprint")) {
+		const fp = atom(fpNode[1]);
+		const layerNode = child(fpNode, "layer");
+		const layer = layerNode ? atom(layerNode[1]) : "F.Cu";
+		const at = parseAt(child(fpNode, "at"));
+		let ref = "";
+		for (const p of children(fpNode, "property")) if (atom(p[1]) === "Reference") ref = atom(p[2]);
+		if (!ref) {
+			const fpText = child(fpNode, "fp_text");
+			if (fpText && atom(fpText[1]) === "reference") ref = atom(fpText[2]);
+		}
+		const pads = [];
+		for (const pad of children(fpNode, "pad")) {
+			const pAt = parseAt(child(pad, "at"));
+			const sizeN = child(pad, "size");
+			const w = sizeN ? num(sizeN[1]) : 1;
+			const l = sizeN ? num(sizeN[2]) : 1;
+			const layersN = child(pad, "layers");
+			const layers = layersN ? layersN.slice(1).map(atom) : [];
+			const netN = child(pad, "net");
+			const net = netN ? netName.get(num(netN[1])) ?? atom(netN[2]) ?? "" : "";
+			const th = pad[2] === "thru_hole";
+			const shape = typeof pad[3] === "string" ? pad[3] : "rect";
+			const [ax, ay] = xform(pAt.x, pAt.y, at);
+			const totalRot = at.rot + pAt.rot;
+			const swap = Math.abs((totalRot % 180 + 180) % 180 - 90) < 45;
+			pads.push({
+				x: +ax.toFixed(4),
+				y: +ay.toFixed(4),
+				w: +(swap ? l : w).toFixed(4),
+				l: +(swap ? w : l).toFixed(4),
+				shape,
+				net,
+				top: th || layers.includes("F.Cu") || layers.includes("*.Cu"),
+				bottom: th || layers.includes("B.Cu") || layers.includes("*.Cu"),
+				th
+			});
+		}
+		comps.push({
+			ref,
+			x: +at.x.toFixed(4),
+			y: +at.y.toFixed(4),
+			rot: +at.rot.toFixed(2),
+			layer,
+			fp,
+			pads
+		});
+	}
+	const traces = [];
+	for (const node of root) {
+		if (!Array.isArray(node)) continue;
+		if (node[0] === "segment") {
+			const st = child(node, "start"), en = child(node, "end");
+			const layerN = child(node, "layer");
+			const widthN = child(node, "width");
+			traces.push({
+				pts: [[num(st[1]), num(st[2])], [num(en[1]), num(en[2])]],
+				w: widthN ? num(widthN[1]) : .25,
+				layer: layerN ? atom(layerN[1]) : "F.Cu"
+			});
+		} else if (node[0] === "arc") {
+			const st = child(node, "start"), mid = child(node, "mid"), en = child(node, "end");
+			const layerN = child(node, "layer");
+			const widthN = child(node, "width");
+			traces.push({
+				arc: true,
+				pts: [
+					[num(st[1]), num(st[2])],
+					[num(mid[1]), num(mid[2])],
+					[num(en[1]), num(en[2])]
+				],
+				w: widthN ? num(widthN[1]) : .25,
+				layer: layerN ? atom(layerN[1]) : "F.Cu"
+			});
+		}
+	}
+	const zones = [];
+	for (const z of children(root, "zone")) {
+		const layerN = child(z, "layer");
+		const layersN = child(z, "layers");
+		const netN = child(z, "net_name");
+		const layerNames = layersN ? layersN.slice(1).map(atom) : [layerN ? atom(layerN[1]) : "F.Cu"];
+		for (const poly of children(z, "polygon")) {
+			const ptsN = child(poly, "pts");
+			if (!ptsN) continue;
+			const pts = [];
+			for (const xy of ptsN.slice(1)) if (Array.isArray(xy) && xy[0] === "xy") pts.push([num(xy[1]), num(xy[2])]);
+			if (pts.length >= 3) zones.push({
+				pts,
+				layer: layerNames[0] ?? "F.Cu",
+				layers: layerNames,
+				net: netN ? atom(netN[1]) : ""
+			});
+		}
+	}
+	const vias = [];
+	for (const v of children(root, "via")) {
+		const at = parseAt(child(v, "at"));
+		const sizeN = child(v, "size");
+		const drillN = child(v, "drill");
+		vias.push({
+			x: +at.x.toFixed(3),
+			y: +at.y.toFixed(3),
+			size: sizeN ? num(sizeN[1]) : .8,
+			drill: drillN ? num(drillN[1]) : .4
+		});
+	}
+	const texts = [];
+	for (const t of children(root, "gr_text")) {
+		const layerN = child(t, "layer");
+		const lyr = layerN ? atom(layerN[1]) : "";
+		if (!lyr.includes("SilkS")) continue;
+		const at = parseAt(child(t, "at"));
+		const effects = child(t, "effects");
+		const font = effects ? child(effects, "font") : null;
+		const sizeN = font ? child(font, "size") : null;
+		texts.push({
+			text: atom(t[1]),
+			x: at.x,
+			y: at.y,
+			rot: at.rot,
+			size: sizeN ? num(sizeN[1]) : 1,
+			layer: lyr
+		});
+	}
+	let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+	const eat = (x, y) => {
+		x0 = Math.min(x0, x);
+		y0 = Math.min(y0, y);
+		x1 = Math.max(x1, x);
+		y1 = Math.max(y1, y);
+	};
+	if (outline.length) for (const o of outline) if (o.type === "circle") {
+		eat(o.c[0] - o.r, o.c[1] - o.r);
+		eat(o.c[0] + o.r, o.c[1] + o.r);
+	} else {
+		eat(o.a[0], o.a[1]);
+		eat(o.b[0], o.b[1]);
+		if (o.type === "arc") eat(o.m[0], o.m[1]);
+	}
+	else {
+		for (const c of comps) for (const p of c.pads) eat(p.x, p.y);
+		x0 -= 3;
+		y0 -= 3;
+		x1 += 3;
+		y1 += 3;
+	}
+	return {
+		outline,
+		bbox: {
+			x0,
+			y0,
+			x1,
+			y1
+		},
+		cuLayers,
+		comps,
+		traces,
+		zones,
+		vias,
+		texts
+	};
+}
+//#endregion
+//#region src/parse.ts
+function parseBoard(text) {
+	return parseKicad(text);
+}
+//#endregion
+//#region src/index.ts
+/**
+* @huaqiu/dsh-tool-pcb-viewer — DSH host 半边。
+*
+* 职责：
+* - `pcb_preview` 工具：接收 .kicad_pcb 路径（绝对或相对会话工作目录），用
+*   @huaqiu/kicad-sexpr-parser + ./adapter.js 解析出板子统计信息，并把文件登记到
+*   一个 key 上供客户端经 webServer 路由拉取。
+* - 只读路由 /pcb-viewer/api/file?key=…：把登记的板文件文本发给浏览器半边
+*   （文件可能上百 MB，不走工具结果本体）。
+* - /pcb-viewer/view + /pcb-viewer/standalone.js：「浏览器打开」整页。
+* - systemPrompt 段：告诉模型何时调用 pcb_preview。
+*
+* 渲染全部发生在浏览器半边（lib/client.js，经 exports["./client"] + dsh.client 加载）。
+*
+* @module @huaqiu/dsh-tool-pcb-viewer
+*/
+/** Plugin id — matches package.json. */
+const name = "@huaqiu/dsh-tool-pcb-viewer";
+/**
+* Cordis services this half depends on.
+*/
+const inject = [
+	"tools",
+	"systemPrompt",
+	"webServer",
+	"sessions"
+];
+const bundleRev = (() => {
+	try {
+		const f = path.join(path.dirname(fileURLToPath(import.meta.url)), "standalone.js");
+		const st = fs.statSync(f);
+		return `${st.size.toString(36)}-${Math.floor(st.mtimeMs).toString(36)}`;
+	} catch {
+		return "";
+	}
+})();
+const GUIDANCE = `## pcb_preview 工具
+- 当用户给出 .kicad_pcb 文件路径、或要求查看/预览/渲染 PCB 板子时，调用 pcb_preview。
+- path 支持绝对路径，或相对会话工作目录的路径。
+- 调用成功后用户会在右侧面板看到实时的「2D 走线视图 + 3D 渲染」大屏，可点击放大到全屏。
+- 不要在回复里粘贴文件内容；只需告诉用户已打开预览即可。`;
+const registry = /* @__PURE__ */ new Map();
+const REGISTRY_CAP = 32;
+function registrySet(key, file) {
+	if (registry.size >= REGISTRY_CAP) {
+		const oldest = registry.keys().next().value;
+		if (oldest !== void 0) registry.delete(oldest);
+	}
+	registry.set(key, file);
+}
+function sessionCwdOf(ctx, exec) {
+	const e = exec;
+	const sid = e?.sessionId ?? e?.session?.id ?? e?.context?.sessionId;
+	const sessions = ctx.sessions;
+	const cwd = sid ? sessions?.get?.(sid)?.header?.cwd : null;
+	return typeof cwd === "string" && cwd ? cwd : null;
+}
+function resolveBoardPath(ctx, exec, input) {
+	const p = String(input ?? "").trim();
+	if (!p) throw Object.assign(/* @__PURE__ */ new Error("path is required"), { status: 400 });
+	if (path.isAbsolute(p)) return path.resolve(p);
+	const cwd = sessionCwdOf(ctx, exec) ?? process.cwd();
+	return path.resolve(cwd, p);
+}
+function sendJson(res, status, body) {
+	const text = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": Buffer.byteLength(text)
+	});
+	res.end(text);
+}
+function isTrustedRequest(req) {
+	const host = String(req.headers.host ?? "");
+	if (!/^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(host)) return false;
+	const origin = req.headers.origin;
+	if (origin && !/^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(String(origin))) return false;
+	return true;
+}
+async function readStats(filePath, config) {
+	const stat = await fs.promises.stat(filePath);
+	if (stat.size > config.maxFileBytes) throw Object.assign(/* @__PURE__ */ new Error(`file too large: ${(stat.size / 1048576).toFixed(1)}MB > ${(config.maxFileBytes / 1048576).toFixed(0)}MB`), { status: 413 });
+	const b = parseBoard(await fs.promises.readFile(filePath, "utf8"));
+	return {
+		sizeKB: Math.round(stat.size / 1024),
+		comps: b.comps.length,
+		pads: b.comps.reduce((s, c) => s + c.pads.length, 0),
+		traces: b.traces.length,
+		zones: b.zones.length,
+		vias: b.vias.length,
+		layers: b.cuLayers.length,
+		widthMM: +(b.bbox.x1 - b.bbox.x0).toFixed(1),
+		heightMM: +(b.bbox.y1 - b.bbox.y0).toFixed(1)
+	};
+}
+function apply(ctx, config = {}) {
+	if (!ctx.tools || typeof ctx.tools.register !== "function") throw new Error("@huaqiu/dsh-tool-pcb-viewer requires the DSH `tools` service (ctx.tools.register).");
+	const cfg = { maxFileBytes: config.maxFileBytes ?? 125829120 };
+	if (ctx.webServer && typeof ctx.webServer.register === "function") ctx.effect(() => ctx.webServer.register({
+		kind: "prefix",
+		path: "/pcb-viewer",
+		handler: (req, res) => {
+			if (!isTrustedRequest(req)) {
+				sendJson(res, 403, {
+					ok: false,
+					error: {
+						code: "forbidden",
+						message: "forbidden"
+					}
+				});
+				return;
+			}
+			try {
+				const url = new URL(req.url ?? "/", "http://dsh.internal");
+				const p = url.pathname;
+				if (p === "/pcb-viewer/api/file") {
+					const key = url.searchParams.get("key") ?? "";
+					const file = registry.get(key);
+					if (!file) {
+						sendJson(res, 404, {
+							ok: false,
+							error: {
+								code: "not-found",
+								message: "unknown file key"
+							}
+						});
+						return;
+					}
+					res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+					fs.createReadStream(file).pipe(res);
+					return;
+				}
+				if (p === "/pcb-viewer/view") {
+					const html = `<!doctype html>
+<html lang="zh-CN"><head><meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width,initial-scale=1"/>
+<title>PCB 3D</title>
+<style>html,body{margin:0;height:100%;overflow:hidden;background:#090b0f}#app{position:fixed;inset:0}</style>
+</head><body><div id="app"></div>
+<script src="/pcb-viewer/standalone.js${bundleRev ? `?rev=${bundleRev}` : ""}"><\/script>
+</body></html>`;
+					res.writeHead(200, {
+						"content-type": "text/html; charset=utf-8",
+						"cache-control": "no-store"
+					});
+					res.end(html);
+					return;
+				}
+				if (p === "/pcb-viewer/standalone.js") {
+					const file = path.join(path.dirname(fileURLToPath(import.meta.url)), "standalone.js");
+					if (!fs.existsSync(file)) {
+						res.writeHead(503, { "content-type": "text/plain; charset=utf-8" });
+						res.end("standalone bundle missing — run: pnpm build");
+						return;
+					}
+					res.writeHead(200, {
+						"content-type": "text/javascript; charset=utf-8",
+						"cache-control": "no-store"
+					});
+					fs.createReadStream(file).pipe(res);
+					return;
+				}
+				sendJson(res, 404, {
+					ok: false,
+					error: {
+						code: "not-found",
+						message: "unknown pcb-viewer route"
+					}
+				});
+			} catch (error) {
+				sendJson(res, 500, {
+					ok: false,
+					error: {
+						code: "internal",
+						message: error instanceof Error ? error.message : String(error)
+					}
+				});
+			}
+		}
+	}), "dsh-tool-pcb-viewer: /pcb-viewer routes");
+	ctx.systemPrompt.section({
+		name: "tool:pcb_preview",
+		order: 107,
+		text: GUIDANCE
+	});
+	const tool = defineTool({
+		name: "pcb_preview",
+		description: "Render a KiCad .kicad_pcb file as an interactive 2D layout + 3D board view embedded in the conversation. Use whenever the user gives a .kicad_pcb path or asks to view/preview/render a PCB board.",
+		parameters: { path: {
+			type: "string",
+			required: true,
+			description: "Absolute path, or path relative to the session working directory"
+		} },
+		output: {
+			schema: { type: "json" },
+			render: (_args, value) => {
+				const v = value;
+				if (!v || v.ok !== true) return [{
+					type: "text",
+					text: JSON.stringify(value, null, 2)
+				}];
+				const s = v.stats ?? {};
+				return [{
+					type: "text",
+					text: `PCB 预览已打开：${v.name}（${s.widthMM}×${s.heightMM}mm，${s.layers} 层，${s.comps} 器件 / ${s.pads} 焊盘 / ${s.traces} 走线 / ${s.vias} 过孔）。右侧面板可见 2D 走线 + 3D 渲染，点击可放大。`
+				}, {
+					type: "text",
+					text: JSON.stringify(v)
+				}];
+			}
+		},
+		presentCall(args) {
+			const p = typeof args?.path === "string" ? args.path : "";
+			return {
+				card: "generic",
+				title: p ? `PCB 预览：${path.basename(p)}` : "PCB 预览",
+				kind: "read",
+				...p ? { locations: [{ path: p }] } : {}
+			};
+		},
+		presentResult(_args, result) {
+			let info = null;
+			for (const block of result?.content ?? []) {
+				if (block?.type !== "text") continue;
+				try {
+					const parsed = JSON.parse(block.text);
+					if (parsed && parsed.ok === true && parsed.stats) {
+						info = parsed;
+						break;
+					}
+				} catch {}
+			}
+			if (!info || !info.stats) return void 0;
+			const s = info.stats;
+			return {
+				card: "generic",
+				title: `PCB 预览：${info.name}`,
+				content: [{
+					type: "text",
+					text: `${s.widthMM}×${s.heightMM}mm · ${s.layers} 层 · ${s.comps} 器件 · ${s.pads} 焊盘 · ${s.traces} 走线 · ${s.vias} 过孔`
+				}]
+			};
+		},
+		async execute(args, exec) {
+			const filePath = resolveBoardPath(ctx, exec, (args && typeof args === "object" ? args : {}).path);
+			if (!/\.kicad_pcb$/i.test(filePath)) return {
+				ok: false,
+				error: `not a .kicad_pcb file: ${filePath}`
+			};
+			if (!fs.existsSync(filePath)) return {
+				ok: false,
+				error: `file not found: ${filePath}`
+			};
+			const stats = await readStats(filePath, cfg);
+			const key = `pcb-${randomUUID()}`;
+			registrySet(key, filePath);
+			return {
+				ok: true,
+				name: path.basename(filePath),
+				path: filePath,
+				key,
+				viewUrl: `/pcb-viewer/api/file?key=${key}`,
+				stats
+			};
+		}
+	});
+	const unregister = ctx.tools.register(tool);
+	return () => {
+		if (typeof unregister === "function") unregister();
+	};
+}
+//#endregion
+export { apply, inject, name };