@huaqiu/dsh-tool-schematic-gen 0.3.13 → 0.3.15

package/lib/index.mjs

@@ -887,8 +887,75 @@ function needsAuth(kind) {
 	};
 }
 /**
-* `generate_schematic_from_description` body — stream `schemagen`, extract the
-* inline `.kicad_sch` files, then store each sheet as a preview artifact.
+* Host whitelist for the project-zip download — mirrors the web app's
+* `/api/sch_sub_gen/download_zip` proxy (`apps/web/.../download_zip/route.ts`):
+* only https/http URLs on `eda.cn` / `*.eda.cn` are allowed. The URL comes
+* from the design agent's STATE_SNAPSHOT, but a node-side guard keeps a
+* compromised/misbehaving agent from turning the plugin into an SSRF proxy.
+*/
+function isAllowedZipHost(url) {
+	if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+	return url.hostname === "eda.cn" || url.hostname.endsWith(".eda.cn");
+}
+/**
+* Download the project zip from the agent-uploaded URL.
+*
+* `project_achieve_url` is the source of truth — the same eda.cn datastream
+* URL the web app streams for export/download. It carries the full KiCad
+* project (sheets AND the footprints that keep sch↔pcb in sync). A plain GET
+* suffices (the web app proxies it only because of browser CORS; node has no
+* such restriction). Returns null when the URL is absent, not on the eda.cn
+* whitelist, or the download fails — the caller then falls back to inline
+* sheets.
+*/
+async function fetchSchematicProjectZip(env, url) {
+	if (!url) return null;
+	let target;
+	try {
+		target = new URL(url);
+	} catch {
+		log$1.warn("schematic zip download skipped — malformed url", { url });
+		return null;
+	}
+	if (!isAllowedZipHost(target)) {
+		log$1.warn("schematic zip download skipped — host not allowed", {
+			host: target.hostname,
+			url
+		});
+		return null;
+	}
+	const fetchImpl = env.deps?.fetchImpl ?? fetch;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("schematic-gen: zip download did not respond within 1800000ms")), HTTP_TIMEOUT_MS);
+	try {
+		const res = await fetchImpl(url, {
+			signal: controller.signal,
+			headers: { accept: "application/zip" }
+		});
+		if (!res || !res.ok) {
+			log$1.warn("schematic zip download failed", {
+				status: res && res.status,
+				url
+			});
+			return null;
+		}
+		const ab = await res.arrayBuffer();
+		return Buffer.from(ab);
+	} catch (err) {
+		log$1.warn("schematic zip download failed", {
+			error: String(err?.message || err),
+			url
+		});
+		return null;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* `generate_schematic_from_description` body — stream `schemagen`, then store
+* the agent-uploaded project ZIP as a `zip` preview artifact (single source of
+* truth: it carries the sheets AND the footprints that keep sch↔pcb in sync).
+* Sheets are kept inline only as a fallback when the zip is unavailable.
 */
 async function runGenerateSchematic(args, exec, env) {
 	const account = await resolveAccount(env.auth);
@@ -926,18 +993,30 @@ async function runGenerateSchematic(args, exec, env) {
 		prog.failed(message);
 		throw new Error(message);
 	}
-	const materialized = await materializeSchematicArtifacts(env, extracted.schFiles);
 	const result = {
 		status: "generated",
 		kind: "schematic",
 		design_name: extracted.outProject || "",
-		schFiles: materialized.schFiles,
-		schArtifacts: materialized.schArtifacts,
 		kicadPro: extracted.kicadPro,
 		project_achieve_url: extracted.project_achieve_url
 	};
-	if (materialized.note) result.note = materialized.note;
-	if (materialized.agentNote) result.agentNote = materialized.agentNote;
+	const zipBuf = await fetchSchematicProjectZip(env, extracted.project_achieve_url);
+	if (zipBuf && zipBuf.length > 0) {
+		result.zip_bytes = zipBuf.length;
+		try {
+			result.zipArtifact = await toArtifactEntry(env, await createPreviewArtifact(env, "zip", sanitizeZipBaseName(extracted.outProject || "schematic") + ".zip", zipBuf.toString("base64"), "base64"));
+		} catch (storeErr) {
+			result.note = "Could not store the project zip as an artifact (" + String(storeErr?.message || storeErr) + ").";
+			result.agentNote = "The project zip (sheets + footprints) is still available at project_achieve_url; the card falls back to rendering the inline sheets below.";
+		}
+	}
+	if (!result.zipArtifact) {
+		const materialized = await materializeSchematicArtifacts(env, extracted.schFiles);
+		result.schFiles = materialized.schFiles;
+		if (materialized.schArtifacts) result.schArtifacts = materialized.schArtifacts;
+		if (materialized.note) result.note = (result.note ? result.note + " " : "") + materialized.note;
+		if (materialized.agentNote) result.agentNote = materialized.agentNote;
+	}
 	prog.done();
 	return result;
 }
@@ -1034,7 +1113,7 @@ const AUTH_GATE_NOTE = "AUTH: This tool requires a Huaqiu EDA (eda.cn) account.
 function createSchematicTool(env) {
 	return defineTool({
 		name: "generate_schematic_from_description",
-		description: "Generate a KiCad schematic (.kicad_sch files) from a natural-language description of a circuit or sub-circuit — e.g. \"design a 5V LM7805 linear regulator power supply with input and output filter capacitors\". Calls the online HQ-EDA schematic generation agent and returns schFiles (filename references), schArtifacts (preview artifact references with id/type/filename/size plus a uri when the cross-process placement channel is available), kicadPro and project_achieve_url. Use this when the user asks to draw, generate or create a circuit schematic from a description (not from an image — for that use the symbol/footprint tools). IMPORTANT: The generated schematic renders automatically as a result card in the web client — an interactive canvas preview per sheet (multi-sheet results get a sheet tab bar) and a download button for the current sheet. Do NOT paste the schematic source, file URLs, or any fenced code block into your reply; just note in one line that the schematic was generated and how many sheets it has. " + AUTH_GATE_NOTE,
+		description: "Generate a KiCad schematic (.kicad_sch files) from a natural-language description of a circuit or sub-circuit — e.g. \"design a 5V LM7805 linear regulator power supply with input and output filter capacitors\". Calls the online HQ-EDA schematic generation agent and returns zipArtifact (the project zip — the single source of truth: it contains the .kicad_sch sheets AND the footprints that keep sch↔pcb in sync), plus kicadPro and project_achieve_url. Use this when the user asks to draw, generate or create a circuit schematic from a description (not from an image — for that use the symbol/footprint tools). IMPORTANT: The generated schematic renders automatically as a result card in the web client — an interactive canvas preview of the project (root sheet of the zip) and a download button that downloads the full project zip. Do NOT paste the schematic source, file URLs, or any fenced code block into your reply; just note in one line that the schematic was generated and how many sheets it has. " + AUTH_GATE_NOTE,
 		parameters: {
 			description: {
 				type: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-tool-schematic-gen",
-  "version": "0.3.13",
+  "version": "0.3.15",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -30,8 +30,8 @@
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.0",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.0",
-    "@huaqiu/dsh-auth": "^0.3.13",
-    "@huaqiu/dsh-artifacts": "^0.3.13",
+    "@huaqiu/dsh-auth": "^0.3.15",
+    "@huaqiu/dsh-artifacts": "^0.3.15",
     "react": "^18"
   },
   "devDependencies": {
@@ -39,9 +39,9 @@
     "@huaqiu/kicad-sexpr-parser": "^0.1.1",
     "@types/react": "^18.3.31",
     "react": "^18.3.1",
-    "@huaqiu/dsh-artifacts": "0.3.13",
-    "@huaqiu/dsh-tool-uncollapse": "0.3.13",
-    "@huaqiu/dsh-auth": "0.3.13"
+    "@huaqiu/dsh-auth": "0.3.15",
+    "@huaqiu/dsh-tool-uncollapse": "0.3.15",
+    "@huaqiu/dsh-artifacts": "0.3.15"
   },
   "files": [
     "lib",
@@ -52,7 +52,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.3.13"
+    "@huaqiu/dsh-plugin-log": "0.3.15"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/client/b64.ts

@@ -0,0 +1,14 @@
+/**
+ * Base64-encode a byte array for transport inside JSON (the edge-bridge proxy
+ * serializes object bodies to JSON, so binary must travel base64). Chunked to
+ * avoid call-stack limits on large zips. Pure module — no DOM/ecad imports —
+ * so node-side tests can import it directly.
+ */
+export function bytesToBase64(bytes: Uint8Array): string {
+  let bin = ''
+  const chunkSize = 0x8000
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    bin += String.fromCharCode(...bytes.subarray(i, i + chunkSize))
+  }
+  return btoa(bin)
+}

package/src/client/hit-card.tsx

@@ -26,6 +26,7 @@ import { placeSupportOf, type HqEdgePlaceLike } from './place.js'
 import { useLocale, useTheme } from './theme.js'
 import { buildLoginUrl, loginIframeBackground } from './login-url.js'
 import { LiveProgress } from './stack-frame.jsx'
+import { bytesToBase64 } from './b64.js'
 
 /** Login-state view used by the needs_auth card (from the auth plugin's shared localStorage). */
 export interface AuthStateLike {
@@ -33,6 +34,22 @@ export interface AuthStateLike {
   nickname?: string
 }
 
+/**
+ * Structural view of the `huaqiuAuth` CLIENT service (declared structurally,
+ * never imported — each package must remain independently installable).
+ * `login()` in HQ Edge host mode triggers the EDA login dialog through
+ * hq-edge (`POST /api/v1/auth/login` → EDA `TriggerLoginDialog`) instead of
+ * the auth.eda.cn iframe; `isHostMode()` tells the card which surface to show.
+ */
+export interface AuthClientLike {
+  auth?: {
+    isAuthenticated(): boolean
+    isHostMode?(): boolean
+    login?(options?: { lang?: string; theme?: string }): Promise<void>
+    onAuthStateChanged(listener: (info: { nickname?: string } | null) => void): () => void
+  }
+}
+
 export type PromptSender = (sessionId: string | undefined, message: string) => Promise<unknown>
 
 const TOOL_SCHEMATIC = 'generate_schematic_from_description'
@@ -53,6 +70,13 @@ export interface GenHitProps {
   inspect?: () => void
   authState?: AuthStateLike
   sendPrompt?: PromptSender
+  /**
+   * Lazy accessor for the `huaqiuAuth` client service (auth plugin browser
+   * half). Absent/undefined in a broken install — the needs_auth card then
+   * falls back to the embedded auth.eda.cn iframe. Lazy (not captured once)
+   * so plugin load order resolves correctly at click time.
+   */
+  getAuth?: () => AuthClientLike | undefined
   /**
    * Lazy accessor for the host's `hqEdge` service (edge-bridge browser half).
    * Absent/undefined in standalone DSH — the Place button is then hidden.
@@ -147,7 +171,8 @@ function PreviewStage({ payload, t }: { payload: PreviewPayload; t: Translate })
         })
         if (cancelled || canvas !== canvasRef.current) return
         sizeCanvasFor(canvas)
-        if (payload.kind === 'system' && payload.bytes) {
+        if (payload.bytes) {
+          // A bytes payload is the full project zip — render its root sheet.
           disposeViewer = await renderProjectZipToCanvas(payload.bytes, canvas)
         } else if (payload.source) {
           disposeViewer = await renderSheetToCanvas(payload.source, canvas)
@@ -186,9 +211,16 @@ function PreviewStage({ payload, t }: { payload: PreviewPayload; t: Translate })
 
 // ── needs_auth login card ───────────────────────────────────────────────────
 
-function LoginCard({ toolName, authState, t }: { toolName: string; authState?: AuthStateLike; t: Translate }): ReactElement {
+function LoginCard({ toolName, authState, t, getAuth }: { toolName: string; authState?: AuthStateLike; t: Translate; getAuth?: () => AuthClientLike | undefined }): ReactElement {
   const dark = useTheme()
   const locale = useLocale()
+  const authClient = getAuth?.()?.auth
+  // HQ Edge host mode: EDA owns the credential — login must ask EDA to open
+  // its own TriggerLoginDialog (hq-edge POST /api/v1/auth/login), not the
+  // auth.eda.cn iframe (a browser-pushed token is ignored by the STRICT host
+  // resolver). Standalone DSH keeps the inline iframe.
+  const hostMode = authClient?.isHostMode?.() ?? false
+
   // FILL mode (`fill=full`): this card IS the surface, so let the embed paint
   // it edge-to-edge with its own `bg-background`. Without it the embed's
   // `grid-rows-[20px_1fr_20px]` wrapper leaves two transparent strips above
@@ -202,6 +234,41 @@ function LoginCard({ toolName, authState, t }: { toolName: string; authState?: A
   // its URL params once on mount), silently ignoring the new `fill`/`theme`.
   const remountKey = `${locale}|${dark ? 'd' : 'l'}`
 
+  const statusLine = (
+    <p className="hq-sch__login-status" style={{ color: authState?.authenticated ? '#1677ff' : '#d4380d' }}>
+      {authState?.authenticated
+        ? t('card.auth.loggedIn', {
+            nickname: authState.nickname ? t('card.nicknameSep', { nickname: authState.nickname }) : '',
+          })
+        : t('card.auth.loggedOut')}
+    </p>
+  )
+
+  if (hostMode) {
+    return (
+      <div className="hq-sch">
+        <div className="hq-sch__header">
+          <span className="hq-sch__icon">⇶</span>
+          <span className="hq-sch__title">{t('card.auth.title')}</span>
+        </div>
+        <div className="hq-sch__login">
+          <p className="hq-sch__login-desc">{t('card.auth.descHost', { tool: toolName })}</p>
+          {statusLine}
+          <button
+            type="button"
+            className="hq-sch__login-btn"
+            onClick={() => {
+              void authClient?.login?.({ lang: locale, theme: dark ? 'dark' : 'light' })
+                .catch(() => { /* login cancelled / dialog failed — card keeps showing the button */ })
+            }}
+          >
+            {t('card.auth.loginBtn')}
+          </button>
+        </div>
+      </div>
+    )
+  }
+
   return (
     <div className="hq-sch">
       <div className="hq-sch__header">
@@ -210,13 +277,7 @@ function LoginCard({ toolName, authState, t }: { toolName: string; authState?: A
       </div>
       <div className="hq-sch__login">
         <p className="hq-sch__login-desc">{t('card.auth.desc', { tool: toolName })}</p>
-        <p className="hq-sch__login-status" style={{ color: authState?.authenticated ? '#1677ff' : '#d4380d' }}>
-          {authState?.authenticated
-            ? t('card.auth.loggedIn', {
-                nickname: authState.nickname ? t('card.nicknameSep', { nickname: authState.nickname }) : '',
-              })
-            : t('card.auth.loggedOut')}
-        </p>
+        {statusLine}
         <iframe
           key={remountKey}
           src={src}
@@ -253,8 +314,11 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
     setPayload({ phase: 'loading', source: null, bytes: null, filename: null, error: null })
     ;(async () => {
       try {
-        const kind = result.kind ?? 'schematic'
-        if (kind === 'system') {
+        // The artifact type decides the payload: a `zip` artifact is the full
+        // KiCad project (sheets + footprints) → bytes for project rendering /
+        // download; a `schematic` artifact is a single inline sheet → text.
+        const artType = result?.artifact?.type ?? (result?.kind === 'system' ? 'zip' : 'schematic')
+        if (artType === 'zip') {
           const art = await resolveArtifactBytes(artifactKey)
           if (cancelled) return
           setPayload({ phase: 'ready', source: null, bytes: art.bytes, filename: art.filename, error: null })
@@ -278,6 +342,8 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
   // Outcome of the last Place attempt: 'ok' | 'error:<detail>'. Rendered as a
   // one-line status under the actions so the user knows the placement landed.
   const [placeStatus, setPlaceStatus] = useState<string | null>(null)
+  // Outcome of the last "Open in EDA" attempt (host mode import via hq-edge).
+  const [importStatus, setImportStatus] = useState<string | null>(null)
 
   function onDownload(): void {
     if (busy || payload.phase !== 'ready') return
@@ -285,7 +351,10 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
     const filename = downloadFilenameFor(kind, result?.artifact ?? null, result?.designName ?? null)
     setBusy('download')
     try {
-      if (kind === 'system' && payload.bytes) {
+      // A bytes payload is the full project zip — download it as-is. A text
+      // payload is a legacy inline sheet (no zip was stored) — download it as
+      // plain text.
+      if (payload.bytes) {
         downloadBytes(filename, payload.bytes)
       } else if (payload.source != null) {
         downloadText(filename, payload.source)
@@ -295,6 +364,40 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
     }
   }
 
+  /**
+   * Open the generated project in the EDA editor. Host mode only: the browser
+   * half posts the project zip (base64 in JSON — the edge-bridge proxy cannot
+   * carry multipart) to hq-edge `POST /api/v1/import/kicad-b64`, which runs
+   * the ImportDesign pipeline (extract → gRPC → EDA opens the design).
+   */
+  async function onOpenInEda(): Promise<void> {
+    if (busy || payload.phase !== 'ready' || !payload.bytes) return
+    const api = props.getHqEdge?.()?.api
+    if (!api || typeof api.request !== 'function') return
+    setBusy('open-in-eda')
+    setImportStatus(null)
+    try {
+      const res = await api.request({
+        method: 'POST',
+        path: '/api/v1/import/kicad-b64',
+        body: {
+          zip_b64: bytesToBase64(payload.bytes),
+          filename: payload.filename ?? 'design.zip',
+          project_name: result?.designName ?? 'schematic',
+          source_vendor: 'circuit_agent',
+          source_format: 'kicad',
+        },
+      })
+      const body = (res ?? {}) as { design_id?: string; status?: string }
+      setImportStatus(t('card.import.done', { id: body.design_id ?? body.status ?? 'ok' }))
+    } catch (e) {
+      console.warn('[hq-schematic-gen] open-in-eda failed', e)
+      setImportStatus(t('card.import.failed', { detail: String((e as Error)?.message || e) }))
+    } finally {
+      setBusy(null)
+    }
+  }
+
   function onRegenerate(): void {
     if (busy) return
     setBusy('regenerate')
@@ -364,7 +467,7 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
 
   // needs_auth
   if (state.phase === 'needs_auth') {
-    return <LoginCard toolName={props.toolName} authState={props.authState} t={t} />
+    return <LoginCard toolName={props.toolName} authState={props.authState} t={t} getAuth={props.getAuth} />
   }
 
   const headerKind = result?.kind ?? kindOf(props.toolName)
@@ -425,6 +528,11 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
   const placeSupport = placeSupportOf(props.getHqEdge, 'schematic')
   const placeableCount = result.artifacts.filter((a) => a.uri).length
   const canPlace = !!placeSupport?.() && placeableCount > 0
+  // Open in EDA (host mode): available when the edge-bridge proxy exists and a
+  // project zip is present in the card (both system and schematic results
+  // store the zip as the single source of truth).
+  const canOpenInEda = payload.phase === 'ready' && payload.bytes != null &&
+    !!props.getHqEdge?.()?.api?.request
 
   return (
     <div className="hq-sch">
@@ -436,6 +544,13 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
         <button type="button" className="hq-sch__act" onClick={onDownload} disabled={!canDownload || busy === 'download'}>
           ⭳ {busy === 'download' ? t('card.action.downloading') : t('card.action.download')}
         </button>
+        {canOpenInEda
+          ? (
+            <button type="button" className="hq-sch__act" onClick={onOpenInEda} disabled={busy === 'open-in-eda'}>
+              ⇱ {busy === 'open-in-eda' ? t('card.action.openingInEda') : t('card.action.openInEda')}
+            </button>
+          )
+          : null}
         {canPlace
           ? (
             <button type="button" className="hq-sch__act" onClick={onPlace} disabled={busy === 'place'}>
@@ -450,6 +565,7 @@ export const GenHit = memo(function GenHit(props: GenHitProps): ReactElement {
           ? <button type="button" className="hq-sch__act" onClick={() => props.inspect?.()}>{t('card.action.inspect')}</button>
           : null}
       </div>
+      {importStatus ? <div className="hq-sch__note">{importStatus}</div> : null}
       {placeStatus ? <div className="hq-sch__note">{placeStatus}</div> : null}
     </div>
   )

package/src/client/i18n.ts

@@ -47,6 +47,10 @@ const ZH = {
     'card.action.downloading': '下载中…',
     'card.action.place': '放置到编辑器',
     'card.action.placing': '放置中…',
+    'card.action.openInEda': '在 EDA 中打开',
+    'card.action.openingInEda': '导入中…',
+    'card.import.done': '已在 EDA 中打开设计（{id}）',
+    'card.import.failed': '在 EDA 中打开失败：{detail}',
     'card.place.done': '已放置 {count} 个文件到编辑器',
     'card.place.partial': '已放置 {placed} 个，{failed} 个失败：',
     'card.place.failed': '放置失败：',
@@ -59,6 +63,8 @@ const ZH = {
     'card.auth.desc': '工具「{tool}」需要登录华秋 EDA AI 账号才能继续。请在下方的登录框完成登录（或点击左侧「华秋EDA AI登录」按钮）；登录完成后，回复助手「已登录，请重试」，助手会自动重新调用该工具。',
     'card.auth.loggedIn': '✓ 已登录{nickname}—— 现在可以回复助手「已登录，请重试」，助手会重新调用工具。',
     'card.auth.loggedOut': '未登录 —— 请在上方登录华秋 EDA AI（eda.cn）账号，或点击左侧「华秋EDA AI 登录」按钮；登录完成后让助手重试。',
+    'card.auth.descHost': '工具「{tool}」需要登录华秋 EDA AI 账号才能继续。点击下方按钮后，EDA（KiCad）将弹出登录窗口，请在弹出的窗口中完成登录；登录完成后回复助手「已登录，请重试」，助手会自动重新调用该工具。',
+    'card.auth.loginBtn': '登录华秋 EDA AI',
     // Substituted into `{nickname}` by `card.auth.loggedIn`. zh uses a
     // full-width colon, en a half-width one plus a space — hardcoding '：'
     // made the English card read "Logged in：John".
@@ -102,6 +108,10 @@ const EN: Record<CopyKey, string> = {
     'card.action.downloading': 'Downloading…',
     'card.action.place': 'Place in editor',
     'card.action.placing': 'Placing…',
+    'card.action.openInEda': 'Open in EDA',
+    'card.action.openingInEda': 'Importing…',
+    'card.import.done': 'Design opened in EDA ({id})',
+    'card.import.failed': 'Failed to open in EDA: {detail}',
     'card.place.done': 'Placed {count} file(s) into the editor',
     'card.place.partial': 'Placed {placed}, {failed} failed: ',
     'card.place.failed': 'Placement failed: ',
@@ -116,6 +126,8 @@ const EN: Record<CopyKey, string> = {
     'card.auth.desc': 'Tool "{tool}" requires a Huaqiu EDA AI login. Complete the login below (or use the 华秋EDA AI sidebar button); then reply "I have logged in, please retry" so the assistant can retry the tool.',
     'card.auth.loggedIn': '✓ Logged in{nickname} — reply "I have logged in, please retry" and the assistant will retry.',
     'card.auth.loggedOut': 'Not logged in — complete the login above, or use the 华秋EDA AI sidebar button.',
+    'card.auth.descHost': 'Tool "{tool}" requires a Huaqiu EDA AI account. Click the button below — EDA (KiCad) will open its login dialog. Complete the login there, then reply "I have logged in, please retry" so the assistant can retry the tool.',
+    'card.auth.loginBtn': 'Sign in to Huaqiu EDA AI',
     'card.nicknameSep': ': {nickname}',
 }
 

package/src/client/index.ts

@@ -159,6 +159,7 @@ export function apply(ctx: ClientContext): () => void {
         sendPrompt,
         authState: useAuthState(),
         getHqEdge,
+        getAuth: () => authService,
       })
 
     for (const toolName of TOOLVIEW_KEYS) {

package/src/client/parse.ts

@@ -115,12 +115,19 @@ export function parseSchResult(text: string): SchResult | null {
     artifact = artOf(o.zipArtifact)
     if (artifact) artifacts.push(artifact)
   } else {
+    // The project zip is the single source of truth (sheets + footprints); the
+    // per-sheet artifacts are a legacy fallback when no zip was stored.
+    const zipRef = artOf(o.zipArtifact)
+    if (zipRef) {
+      artifact = zipRef
+      artifacts.push(zipRef)
+    }
     const list = Array.isArray(o.schArtifacts) ? (o.schArtifacts as unknown[]) : []
     for (const entry of list) {
       const ref = artOf(entry)
       if (ref) artifacts.push(ref)
     }
-    artifact = artifacts.length > 0 ? artifacts[0]! : null
+    if (!artifact) artifact = artifacts.length > 0 ? artifacts[0]! : null
   }
 
   return {

package/src/client/theme.ts

@@ -181,6 +181,8 @@ const CSS = `
 .hq-sch__login-desc { margin: 0 0 10px; font: var(--dsw-font-xxs-12, 12px/1.4 system-ui, sans-serif); color: var(--dsw-alias-label-secondary, currentColor); line-height: 1.5; }
 .hq-sch__login-status { margin: 0 0 10px; font: var(--dsw-font-xxs-12, 12px/1.4 system-ui, sans-serif); line-height: 1.5; }
 .hq-sch__login-iframe { width: 100%; height: ${LOGIN_IFRAME_HEIGHT}px; border: 0; border-radius: 8px; display: block; }
+.hq-sch__login-btn { display: inline-flex; align-items: center; gap: 4px; border: 1px solid var(--dsw-alias-border-l1, currentColor); border-radius: 6px; padding: 6px 16px; background: var(--dsw-alias-interactive-bg-hover, rgba(127,127,127,0.08)); color: var(--dsw-alias-label-primary, currentColor); font: var(--dsw-font-xxs-12, 12px/1.4 system-ui, sans-serif); cursor: pointer; }
+.hq-sch__login-btn:hover { filter: brightness(1.08); }
 
 /* ── live call stack (long-running generations) ───────────────────────────── */
 .hq-sch__progress { display: flex; align-items: center; gap: 8px; padding: 0 12px 8px; font: var(--dsw-font-xxs-12, 12px/1.4 system-ui, sans-serif); color: var(--dsw-alias-label-secondary, currentColor); }

package/src/tools.ts

@@ -323,8 +323,68 @@ export function needsAuth(kind: 'schematic' | 'system'): Record<string, unknown>
 }
 
 /**
- * `generate_schematic_from_description` body — stream `schemagen`, extract the
- * inline `.kicad_sch` files, then store each sheet as a preview artifact.
+ * Host whitelist for the project-zip download — mirrors the web app's
+ * `/api/sch_sub_gen/download_zip` proxy (`apps/web/.../download_zip/route.ts`):
+ * only https/http URLs on `eda.cn` / `*.eda.cn` are allowed. The URL comes
+ * from the design agent's STATE_SNAPSHOT, but a node-side guard keeps a
+ * compromised/misbehaving agent from turning the plugin into an SSRF proxy.
+ */
+function isAllowedZipHost(url: URL): boolean {
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') return false
+  return url.hostname === 'eda.cn' || url.hostname.endsWith('.eda.cn')
+}
+
+/**
+ * Download the project zip from the agent-uploaded URL.
+ *
+ * `project_achieve_url` is the source of truth — the same eda.cn datastream
+ * URL the web app streams for export/download. It carries the full KiCad
+ * project (sheets AND the footprints that keep sch↔pcb in sync). A plain GET
+ * suffices (the web app proxies it only because of browser CORS; node has no
+ * such restriction). Returns null when the URL is absent, not on the eda.cn
+ * whitelist, or the download fails — the caller then falls back to inline
+ * sheets.
+ */
+async function fetchSchematicProjectZip(env: SchematicGenEnv, url: string): Promise<Buffer | null> {
+  if (!url) return null
+  let target: URL
+  try {
+    target = new URL(url)
+  } catch {
+    log.warn('schematic zip download skipped — malformed url', { url })
+    return null
+  }
+  if (!isAllowedZipHost(target)) {
+    log.warn('schematic zip download skipped — host not allowed', { host: target.hostname, url })
+    return null
+  }
+  const fetchImpl = env.deps?.fetchImpl ?? fetch
+  const controller = new AbortController()
+  const timer = setTimeout(
+    () => controller.abort(new Error('schematic-gen: zip download did not respond within ' + HTTP_TIMEOUT_MS + 'ms')),
+    HTTP_TIMEOUT_MS,
+  )
+  try {
+    const res = await fetchImpl(url, { signal: controller.signal, headers: { accept: 'application/zip' } })
+    if (!res || !res.ok) {
+      log.warn('schematic zip download failed', { status: res && res.status, url })
+      return null
+    }
+    const ab = await res.arrayBuffer()
+    return Buffer.from(ab)
+  } catch (err) {
+    log.warn('schematic zip download failed', { error: String((err as Error)?.message || err), url })
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * `generate_schematic_from_description` body — stream `schemagen`, then store
+ * the agent-uploaded project ZIP as a `zip` preview artifact (single source of
+ * truth: it carries the sheets AND the footprints that keep sch↔pcb in sync).
+ * Sheets are kept inline only as a fallback when the zip is unavailable.
  */
 export async function runGenerateSchematic(
   args: Record<string, unknown>,
@@ -373,18 +433,46 @@ export async function runGenerateSchematic(
     prog.failed(message)
     throw new Error(message)
   }
-  const materialized = await materializeSchematicArtifacts(env, extracted.schFiles)
+
   const result: Record<string, unknown> = {
     status: 'generated',
     kind: 'schematic',
     design_name: extracted.outProject || '',
-    schFiles: materialized.schFiles,
-    schArtifacts: materialized.schArtifacts,
     kicadPro: extracted.kicadPro,
     project_achieve_url: extracted.project_achieve_url,
   }
-  if (materialized.note) result.note = materialized.note
-  if (materialized.agentNote) result.agentNote = materialized.agentNote
+
+  // The project ZIP is the single source of truth (sheets + footprints for
+  // sch↔pcb sync). Store it as a `zip` preview artifact — the card renders the
+  // zip's root sheet and downloads the zip itself.
+  const zipBuf = await fetchSchematicProjectZip(env, extracted.project_achieve_url)
+  if (zipBuf && zipBuf.length > 0) {
+    result.zip_bytes = zipBuf.length
+    try {
+      const safeName = sanitizeZipBaseName(extracted.outProject || 'schematic')
+      const created = await createPreviewArtifact(env, 'zip', safeName + '.zip', zipBuf.toString('base64'), 'base64')
+      result.zipArtifact = await toArtifactEntry(env, created)
+    } catch (storeErr) {
+      result.note = 'Could not store the project zip as an artifact (' +
+        String((storeErr as Error)?.message || storeErr) + ').'
+      result.agentNote =
+        'The project zip (sheets + footprints) is still available at project_achieve_url; ' +
+        'the card falls back to rendering the inline sheets below.'
+    }
+  }
+
+  if (!result.zipArtifact) {
+    // Fallback (older agent without an uploaded zip, or zip fetch/store
+    // failure): store each sheet as a preview artifact — the card can still
+    // render and download the individual sheet.
+    const materialized = await materializeSchematicArtifacts(env, extracted.schFiles)
+    result.schFiles = materialized.schFiles
+    if (materialized.schArtifacts) result.schArtifacts = materialized.schArtifacts
+    if (materialized.note) {
+      result.note = (result.note ? result.note + ' ' : '') + materialized.note
+    }
+    if (materialized.agentNote) result.agentNote = materialized.agentNote
+  }
   prog.done()
   return result
 }
@@ -542,15 +630,16 @@ function createSchematicTool(env: SchematicGenEnv) {
       'description of a circuit or sub-circuit — e.g. "design a 5V LM7805 linear ' +
       'regulator power supply with input and output filter capacitors". Calls the ' +
       'online HQ-EDA schematic generation agent and returns ' +
-      'schFiles (filename references), schArtifacts (preview artifact references ' +
-      'with id/type/filename/size plus a uri when the cross-process placement ' +
-      'channel is available), kicadPro and project_achieve_url. ' +
+      'zipArtifact (the project zip — the single source of truth: it contains ' +
+      'the .kicad_sch sheets AND the footprints that keep sch↔pcb in sync), ' +
+      'plus kicadPro and project_achieve_url. ' +
       'Use this when the user asks to draw, generate or create a circuit ' +
       'schematic from a description (not from an image — for that use the ' +
       'symbol/footprint tools). ' +
       'IMPORTANT: The generated schematic renders automatically as a result card ' +
-      'in the web client — an interactive canvas preview per sheet (multi-sheet ' +
-      'results get a sheet tab bar) and a download button for the current sheet. ' +
+      'in the web client — an interactive canvas preview of the project (root ' +
+      'sheet of the zip) and a download button that downloads the full project ' +
+      'zip. ' +
       'Do NOT paste the schematic source, file URLs, or any fenced code block ' +
       'into your reply; just note in one line that the schematic was generated ' +
       'and how many sheets it has. ' + AUTH_GATE_NOTE,