@huaqiu/dsh-tool-kicad-schematic-gen 0.6.4 → 0.6.6

package/lib/client.js

@@ -331,10 +331,13 @@
 	* SSE agents were removed with the package). The chip identity, the `@`
 	* trigger, the clipboard projection and the menu row are preserved verbatim so
 	* existing drafts and the composer UX keep working. The one deliberate change:
-	* the chip's model text now pins the bundled `kicad-schematic-design` skill
-	* instead of the deleted online tools (`generate_schematic_from_description` /
-	* `generate_system_module_graph`), because the design skill is the new local
-	* entry point the agent must follow.
+	* the chip's model text is now the bare clipboard token — the semantics that
+	* used to ride in the payload (pin the `kicad-schematic-design` skill instead
+	* of the deleted online tools `generate_schematic_from_description` /
+	* `generate_system_module_graph`, forbid hand-written KiCad files, defer to
+	* the user's words) moved to the node half's `huaqiu:schematic-gen`
+	* system-prompt section; see {@link SCHEMATIC_GEN_SERIALIZED} and
+	* `src/prompt.ts`.
 	*
 	* One module owns the identity of the chip, its menu row, and the model text
 	* the chip expands to at submit time. Registering the source is MANDATORY, not
@@ -344,6 +347,12 @@
 	* source"). A chip inserted without a registered source would therefore block
 	* the user's message instead of degrading quietly.
 	*
+	* The registration is also ORDER-sensitive: the trigger service is provided by
+	* a plugin whose own dependency chain is longer than ours, so reading it once
+	* at `apply()` time can find nothing. The entry therefore declares
+	* `inputTriggers` in its `inject` (cordis parks the plugin until the provider
+	* exists) and retries briefly if it still arrives late.
+	*
 	* Registering it also buys the typed path for free: the user can type `@` and
 	* pick *Generate schematic* (生成原理图 under a Chinese UI) from a group beside
 	* *Files & folders* / *Sessions*.
@@ -407,20 +416,27 @@
 	}
 	/**
 	* Model form of the chip: what the agent actually reads at the chip's position
-	* in the user message.
+	* in the user message — the clipboard token itself, nothing more.
+	*
+	* This is the idiomatic mention pattern (DSH's own draft tests serialize a
+	* reference to its ref), and it is deliberate on two counts:
 	*
-	* Deliberately an *intent*, never a fabricated design description — the user's
-	* own words stay the only source of requirements, and the plugin being loaded
-	* is never by itself a reason to generate.
+	* 1. **Whatever `serialize` returns lands in the USER message** — the submit
+	*    plane splices it over the chip's clipboard range — so a long payload is
+	*    noise the user reads back in their own transcript on every send.
+	* 2. **The token has no semantics of its own**, so the semantics cannot live
+	*    here; they live in the node half's `huaqiu:schematic-gen` system-prompt
+	*    section (see `src/prompt.ts`), which defines the token, pins the
+	*    `kicad-schematic-design` skill, and carries the guardrails.
 	*
-	* The retired plugin pinned the online tools here
-	* (`generate_schematic_from_description` / `generate_system_module_graph`).
-	* The migrated chip pins the bundled `kicad-schematic-design` skill instead:
-	* the skill owns the module search / part import / editable-project flow, and
-	* starts from the hardware design brief when no plan exists yet. Hand-written
-	* KiCad files stay forbidden in both worlds.
+	* History: the chip first shipped a 6-line `<schematic-gen intent=…>` block,
+	* then a 3-line trimmed form, and now delegates entirely to the section. The
+	* retired plugin pinned deleted online tools here
+	* (`generate_schematic_from_description` / `generate_system_module_graph`);
+	* nothing in this constant may ever name a tool again — the skill pin is the
+	* section's job.
 	*/
-	const SCHEMATIC_GEN_SERIALIZED = "<schematic-gen intent=\"kicad-schematic-design\">\nThe user explicitly chose Schematic Gen for this request. Produce the design with the `kicad-schematic-design` skill; when the hardware design brief is missing or incomplete, the skill starts by preparing it before the schematic work.\nNever hand-write .kicad_sch files or KiCad project files yourself — always go through the skill and its tools.\nUse the user's own words as the design description. If they have not described the circuit yet, ask for the requirements instead of assuming them.\n</schematic-gen>";
+	const SCHEMATIC_GEN_SERIALIZED = SCHEMATIC_GEN_CLIPBOARD;
 	/**
 	* The `ReferenceInsert` this source produces on pick (and on button click).
 	*
@@ -476,23 +492,125 @@
 		};
 	}
 	/**
-	* Register the source and return its disposer.
+	* One registration attempt, reported instead of swallowed.
+	*
+	* {@link registerSchematicGenSource} is the disposer-only view for callers that
+	* do not care; this is the same attempt with the outcome visible, which is what
+	* a caller needs to decide whether a chip may be inserted at all — an
+	* unregistered source makes every send fail (see the module header).
 	*
-	* Never throws: a missing service, a duplicate registration (a second live
-	* copy of this plugin) or a throwing registry must not take the whole client
-	* half down. Without a registered source the sidebar button degrades to
-	* inserting nothing rather than producing a chip that would block submission.
 	* @param registry - `ctx.get('inputTriggers')`, or undefined.
-	* @returns disposer (a no-op when registration did not happen).
+	* @returns whether the registration landed, plus its disposer.
 	*/
-	function registerSchematicGenSource(registry) {
-		if (registry === void 0 || registry === null || typeof registry.registerSource !== "function") return () => {};
+	function registerSchematicGenSourceTracked(registry) {
+		if (registry === void 0 || registry === null || typeof registry.registerSource !== "function") return {
+			registered: false,
+			dispose: () => {}
+		};
 		try {
 			const dispose = registry.registerSource(createSchematicGenSource());
-			return typeof dispose === "function" ? dispose : () => {};
+			return {
+				registered: true,
+				dispose: typeof dispose === "function" ? dispose : () => {}
+			};
 		} catch {
-			return () => {};
+			return {
+				registered: true,
+				dispose: () => {}
+			};
+		}
+	}
+	/**
+	* Host timer, or undefined where there is none.
+	*
+	* The retry is browser-only machinery, and the built bundle is also evaluated
+	* in bare hosts (the vm-based card test, a non-DOM worker) where `setInterval`
+	* does not exist. Those must degrade to "not registered yet" — a throw here
+	* would take the whole client half down, which is the failure mode this module
+	* exists to prevent.
+	*/
+	function hostTimer() {
+		if (typeof setInterval !== "function" || typeof clearInterval !== "function") return void 0;
+		return {
+			set: (fn, ms) => setInterval(fn, ms),
+			clear: (handle) => clearInterval(handle)
+		};
+	}
+	/**
+	* Register the source, polling while the trigger service has not activated yet.
+	*
+	* Why this exists: activation is service-availability driven, and
+	* `inputTriggers` is provided by a plugin (`dsh-client-ui-input-trigger`) whose
+	* own dependency chain is far longer than ours. A plugin that reads the service
+	* exactly once at `apply()` time and finds it absent registers NOTHING —
+	* silently. The chip then lands in the composer (insertion only needs
+	* `conversation`) and the send dies on
+	* `slash: no serializer for reference source "schematic-gen"`, because the
+	* controller routes every chip to its owner's codec. Declaring `inputTriggers`
+	* in the plugin's `inject` is the primary fix (cordis then parks this plugin
+	* until the provider exists); this poll is the belt-and-braces path for a
+	* provider that arrives later than that declaration could promise.
+	*
+	* @param getRegistry - returns the current `ctx.get('inputTriggers')` value.
+	* @param hooks - scheduler/trace seams.
+	* @returns a live binding whose `registered()` the caller may consult.
+	*/
+	function registerSchematicGenSourceWhenReady(getRegistry, hooks = {}) {
+		const intervalMs = hooks.intervalMs ?? 250;
+		const maxAttempts = hooks.maxAttempts ?? 80;
+		const traceFn = hooks.trace ?? trace$1;
+		const timer = hooks.setTimer !== void 0 && hooks.clearTimer !== void 0 ? {
+			set: hooks.setTimer,
+			clear: hooks.clearTimer
+		} : hostTimer();
+		let current = registerSchematicGenSourceTracked(getRegistry());
+		let handle;
+		let attempts = 0;
+		let stopped = false;
+		const stopTimer = () => {
+			if (handle === void 0 || timer === void 0) return;
+			timer.clear(handle);
+			handle = void 0;
+		};
+		const dispose = () => {
+			stopped = true;
+			stopTimer();
+			current.dispose();
+		};
+		if (current.registered) return {
+			registered: () => true,
+			dispose
+		};
+		if (timer === void 0) {
+			traceFn("no timer host — source registration not retried");
+			return {
+				registered: () => false,
+				dispose
+			};
 		}
+		traceFn("waiting for inputTriggers", {
+			intervalMs,
+			maxAttempts
+		});
+		handle = timer.set(() => {
+			if (stopped) return;
+			attempts += 1;
+			const next = registerSchematicGenSourceTracked(getRegistry());
+			if (next.registered) {
+				current = next;
+				stopTimer();
+				traceFn("registered (late)", { attempts });
+				return;
+			}
+			if (attempts >= maxAttempts) {
+				stopTimer();
+				traceFn("source registration gave up", { attempts });
+			}
+		}, intervalMs);
+		return {
+			registered: () => current.registered,
+			dispose
+		};
 	}
 	//#endregion
 	//#region src/client/sidebar-entry.ts
@@ -1126,24 +1244,33 @@
 				}, busy ? "处理中…" : "放置到编辑器") : null, h("span", { style: { fontSize: 12 } }, `${result.fileCount} 个工程和库文件`)), result.status !== "ok" ? h("p", null, "存在未渲染页面或预览警告，请结合工具结果检查。") : null, message ? h("p", { role: "alert" }, message) : null);
 			}
 			return {
-				inject: ["slots"],
+				inject: ["slots", "inputTriggers"],
 				apply: (ctx) => {
 					getHost = () => ctx.get?.("hqEdge");
 					const stopVisibility = keepDeliveryVisible();
-					const triggers = ctx.get?.("inputTriggers");
+					const source = registerSchematicGenSourceWhenReady(() => ctx.get?.("inputTriggers"));
 					try {
 						console.debug("[schematic-gen:client] apply", {
-							inputTriggers: triggers !== void 0 && triggers !== null,
+							inputTriggers: source.registered(),
 							slots: typeof ctx.slots?.inject === "function"
 						});
 					} catch {}
-					const stopRefs = registerSchematicGenSource(triggers);
 					const chipDeps = {
 						getConversation: () => ctx.get?.("conversation"),
 						getSessions: () => ctx.get?.("sessions")
 					};
 					const stopEntry = mountSchematicGenSidebarEntry({
 						onToggle: () => {
+							if (!source.registered()) {
+								try {
+									console.debug("[schematic-gen:chip] click", {
+										ok: false,
+										reason: "source-unregistered"
+									});
+								} catch {}
+								notifyComposer(ctx, "source-unregistered");
+								return;
+							}
 							const result = insertSchematicChip(chipDeps);
 							try {
 								console.debug("[schematic-gen:chip] click", result);
@@ -1162,7 +1289,7 @@
 					}, Card));
 					ctx.effect?.(() => () => {
 						stopVisibility();
-						stopRefs();
+						source.dispose();
 						stopEntry();
 						if (typeof dispose === "function") dispose();
 					});
@@ -1187,6 +1314,7 @@
 					case "no-session": return "Open a conversation first, then click Schematic Gen again.";
 					case "busy": return "The composer is busy — try again once the current message settles.";
 					case "conflict": return "The composer changed while inserting — click Schematic Gen again.";
+					case "source-unregistered": return "Schematic Gen is still starting up — click again in a moment.";
 					default: return "Schematic Gen is unavailable in this session.";
 				}
 			}

package/lib/index.d.ts

@@ -415,7 +415,7 @@ declare function resolveConfig(input?: ConfigInput): Config;
 //#endregion
 //#region src/index.d.ts
 declare const name = "@huaqiu/dsh-tool-kicad-schematic-gen";
-declare const inject: readonly ["tools", "fs", "sandboxPolicy", "skills", "webServer"];
+declare const inject: readonly ["tools", "fs", "sandboxPolicy", "skills", "webServer", "systemPrompt"];
 declare function apply(ctx: Context, input?: ConfigInput): void;
 //#endregion
 export { Config, apply, inject, name, resolveConfig };

package/lib/index.js

@@ -7392,6 +7392,95 @@ function registerModuleAnalysis(ctx, config, analyze = createModuleAnalyzer(ctx,
 	return analyze;
 }
 //#endregion
+//#region src/prompt.ts
+/**
+* The `huaqiu:schematic-gen` system-prompt section.
+*
+* Split out from `src/index.ts` so the text and the registration are
+* unit-testable without a cordis context, tools, or a skill registry — the
+* same split `@huaqiu/dsh-eda-selection` uses for its `eda:selection` section.
+*
+* ── Why a section at all ────────────────────────────────────────────────────
+* The composer chip's model form is the bare `@schematic-gen` token (see
+* `client/schematic-ref.ts`): the token is a UI affordance with no semantics
+* of its own, and whatever `codec.serialize` returns lands in the USER
+* message — repeating it on every send is noise the user reads back in their
+* own transcript. The section carries the semantics once, in the system
+* prompt, where policy text belongs.
+*
+* ── Why static, not a per-session provider ──────────────────────────────────
+* "Once the user chose Schematic Gen, the rest of the conversation continues
+* that work" is already true without any session state: the token sits in the
+* conversation history for every later turn, and the section is re-read on
+* every assembly. A dynamic provider would need a session-state source — the
+* only candidates are message-history I/O or a client→node signal, and prompt
+* assembly is on the agent's hot path (`dsh-eda-selection` documents the same
+* no-I/O rule). So the section is static text gated on the token, not a
+* per-session flag.
+*
+* @module
+*/
+/**
+* Unique prompt-section name.
+*
+* Reuses the retired `huaqiu:schematic-gen` name: `dsh-eda-selection` records
+* that the old section "has moved to the bundled kicad-schematic-design
+* skill", and this is that section coming back for the chip era — same slot,
+* same adjacency, no other registration to collide with.
+*/
+const HUAQIU_SCHEMATIC_GEN_SECTION = "huaqiu:schematic-gen";
+/** The chip token the section is gated on — the chip's clipboard projection. */
+const SCHEMATIC_GEN_TOKEN = "@schematic-gen";
+/**
+* The section text: what the `@schematic-gen` token MEANS.
+*
+* Static on purpose (see the module header). Four jobs, each mapping to a
+* failure mode observed with the earlier inline-payload chip:
+* 1. define the token as an explicit user choice — a bare token alone is an
+*    opaque string the model has no trained semantics for;
+* 2. pin the `kicad-schematic-design` skill — the retired online tools are
+*    gone, so an unpinned agent may reach for a dead entry point;
+* 3. forbid hand-written `.kicad_sch` files — asked for "an ESP32 mini", an
+*    LLM will otherwise author KiCad files itself, which KiCad cannot open;
+* 4. defer requirements to the user's own words — a gesture is not a spec.
+*
+* It never claims the token carries content: it says what the token means,
+* nothing about what the user asked for.
+*/
+function schematicGenSectionText() {
+	return [
+		`Schematic Gen: the ${SCHEMATIC_GEN_TOKEN} token in a user message is the Schematic Gen chip — the user explicitly chose it for that request. Produce the design with the \`kicad-schematic-design\` skill, which starts from the hardware design brief when none exists yet.`,
+		"Never hand-write .kicad_sch files or KiCad project files yourself; go through the skill and its tools.",
+		"Use the user's own words as the design description — if they have not described the circuit yet, ask for the requirements instead of assuming them.",
+		"Follow-up messages in the same conversation continue that work without repeating the token."
+	].join("\n");
+}
+/**
+* Register the static Schematic Gen section.
+*
+* Never throws: a DSH deployment without the prompt service, or one where a
+* duplicate registration races (hot reload), must still load the tools and
+* the skill — the section is an enhancement, not a dependency of the rest of
+* the plugin. A duplicate is the expected hot-reload case, so it is swallowed
+* rather than surfaced; the first registration keeps serving.
+*
+* @param systemPrompt - `ctx.systemPrompt`, or undefined.
+* @returns the section's disposer, or `undefined` when nothing was registered.
+*/
+function registerSchematicGenSection(systemPrompt) {
+	if (systemPrompt === void 0 || systemPrompt === null || typeof systemPrompt.section !== "function") return;
+	try {
+		const dispose = systemPrompt.section({
+			name: HUAQIU_SCHEMATIC_GEN_SECTION,
+			order: 590,
+			text: schematicGenSectionText()
+		});
+		return typeof dispose === "function" ? dispose : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
 //#region src/index.ts
 const name = "@huaqiu/dsh-tool-kicad-schematic-gen";
 const inject = [
@@ -7399,11 +7488,12 @@ const inject = [
 	"fs",
 	"sandboxPolicy",
 	"skills",
-	"webServer"
+	"webServer",
+	"systemPrompt"
 ];
 /** Shared component name for the unified DSH-plugin log (`~/.hq-edge/logs/dsh-plugins`). */
 const log = getLogger("dsh-schematic-gen");
-log.info("schematic-gen: module loaded (waiting for the tools, fs, sandboxPolicy, skills and webServer services)");
+log.info("schematic-gen: module loaded (waiting for the tools, fs, sandboxPolicy, skills, webServer and systemPrompt services)");
 function apply(ctx, input = {}) {
 	const config = resolveConfig(input);
 	log.info("applying schematic-gen node half", {
@@ -7416,6 +7506,9 @@ function apply(ctx, input = {}) {
 		registerModules(ctx, config.modules, analyze);
 		apply$2(ctx, config.schematic);
 		apply$1(ctx, config.schematic.kicadCliPath);
+		const disposeSection = registerSchematicGenSection(ctx.systemPrompt);
+		if (disposeSection === void 0) log.warn("systemPrompt service unavailable — the huaqiu:schematic-gen section was not registered");
+		else ctx.effect(() => disposeSection);
 	} catch (error) {
 		log.error("schematic-gen node half failed", { error: String(error?.message ?? error) });
 		throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-tool-kicad-schematic-gen",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "KiCad 原理图设计：电路模块搜索、器件模型与手册、符号导入、编辑预览、脚本构建及设计技能",
   "type": "module",
   "main": "./lib/index.js",
@@ -32,8 +32,8 @@
     "pdfjs-dist": "6.3.289",
     "sharp": "0.35.4",
     "undici": "^8.10.0",
-    "@huaqiu/dsh-plugin-log": "0.6.4",
-    "@huaqiu/dsh-sidebar-entry": "0.6.4"
+    "@huaqiu/dsh-plugin-log": "0.6.6",
+    "@huaqiu/dsh-sidebar-entry": "0.6.6"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
@@ -46,7 +46,8 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime"
+        "@deepseek-ai/dsh-client-runtime",
+        "inputTriggers"
       ]
     }
   },

package/src/client/index.ts

@@ -3,7 +3,7 @@ import type * as ReactTypes from 'react'
 import {parseCard} from './overview-result.ts'
 import {placementHost,placeOverview,type PlacementHost} from './place.ts'
 import {supersededOverviews} from './latest-overview.ts'
-import {registerSchematicGenSource} from './schematic-ref.ts'
+import {registerSchematicGenSourceWhenReady} from './schematic-ref.ts'
 import {mountSchematicGenSidebarEntry} from './sidebar-entry.ts'
 import {insertSchematicChip,currentSessionId,resolveSessionScope,type ChipInserterDeps,type ConversationLike,type SessionsLike} from './composer-chip.ts'
 
@@ -71,17 +71,21 @@ loader.load({id:'@huaqiu/dsh-tool-kicad-schematic-gen',factory:(require:(name:st
    result.status!=='ok'?h('p',null,'存在未渲染页面或预览警告，请结合工具结果检查。'):null,
    message?h('p',{role:'alert'},message):null)
  }
- return {inject:['slots'],apply:(ctx:ClientContext)=>{
+ return {inject:['slots','inputTriggers'],apply:(ctx:ClientContext)=>{
   getHost=()=>ctx.get?.('hqEdge') as PlacementHost|undefined
   const stopVisibility=keepDeliveryVisible()
   // Trace the two things that decide whether the plugin is visible at all:
   // the trigger registry (the `@` menu) and the mounted sidebar row. When the
   // node half fails to import, DSH never loads this file — so silence here
   // means "the entry did not activate", not "the row failed to mount".
-  const triggers=ctx.get?.('inputTriggers')
-  try{console.debug('[schematic-gen:client] apply',{inputTriggers:triggers!==undefined&&triggers!==null,
+  // `inputTriggers` is declared in `inject`, so cordis parks this plugin until
+  // the provider exists; `registerSchematicGenSourceWhenReady` still polls, so
+  // a provider that arrives later than that promise still gets our source —
+  // an unregistered source makes every send fail with
+  // `slash: no serializer for reference source "schematic-gen"`.
+  const source=registerSchematicGenSourceWhenReady(()=>ctx.get?.('inputTriggers'))
+  try{console.debug('[schematic-gen:client] apply',{inputTriggers:source.registered(),
     slots:typeof ctx.slots?.inject==='function'})}catch{}
-  const stopRefs=registerSchematicGenSource(triggers)
   // The sidebar toolbutton. Clicking it inserts the chip; it never opens a
   // workspace. Both services are read lazily — they may materialize after this
   // plugin, and a missing one must not take the client half down.
@@ -90,6 +94,15 @@ loader.load({id:'@huaqiu/dsh-tool-kicad-schematic-gen',factory:(require:(name:st
    getSessions:()=>ctx.get?.('sessions') as SessionsLike|undefined,
   }
   const stopEntry=mountSchematicGenSidebarEntry({onToggle:()=>{
+   // Never insert a chip DSH cannot submit: the controller routes every chip to
+   // its owner's codec, so a source that never registered blocks the whole send
+   // instead of degrading. While the trigger pipeline is still warming up, say
+   // so and leave the draft clean.
+   if(!source.registered()){
+    try{console.debug('[schematic-gen:chip] click',{ok:false,reason:'source-unregistered'})}catch{}
+    notifyComposer(ctx,'source-unregistered')
+    return
+   }
    const result=insertSchematicChip(chipDeps)
    // The one line that answers "I clicked and nothing happened": every failure
    // path in the inserter is traced, so the browser console names the reason.
@@ -101,7 +114,7 @@ loader.load({id:'@huaqiu/dsh-tool-kicad-schematic-gen',factory:(require:(name:st
   },position:'after'})
   try{console.debug('[schematic-gen:client] sidebar row',{rows:document.querySelectorAll('[data-hqcg-schematic-entry]').length})}catch{}
   const dispose=ctx.slots.inject('tool.call.toolview',()=>ctx.slots.register({name:'tool.call.toolview',key:'render_kicad_module_preview'},Card))
-  ctx.effect?.(()=>()=>{stopVisibility();stopRefs();stopEntry();if(typeof dispose==='function')dispose()})
+  ctx.effect?.(()=>()=>{stopVisibility();source.dispose();stopEntry();if(typeof dispose==='function')dispose()})
  }}
  /** Surface why a chip insertion did not happen, through the composer's own notice channel. Best-effort by design. */
  function notifyComposer(context:ClientContext,reason:string){
@@ -119,13 +132,16 @@ loader.load({id:'@huaqiu/dsh-tool-kicad-schematic-gen',factory:(require:(name:st
    input?.notify?.('info',noticeFor(reason))
   }catch{/* notice delivery is strictly optional */}
  }
- /** Human-readable notice text for one insertion failure reason. */
- function noticeFor(reason:string):string{
-  switch(reason){
-   case 'no-session':return 'Open a conversation first, then click Schematic Gen again.'
-   case 'busy':return 'The composer is busy — try again once the current message settles.'
-   case 'conflict':return 'The composer changed while inserting — click Schematic Gen again.'
-   default:return 'Schematic Gen is unavailable in this session.'
-  }
+/** Human-readable notice text for one insertion failure reason. */
+function noticeFor(reason:string):string{
+ switch(reason){
+  case 'no-session':return 'Open a conversation first, then click Schematic Gen again.'
+  case 'busy':return 'The composer is busy — try again once the current message settles.'
+  case 'conflict':return 'The composer changed while inserting — click Schematic Gen again.'
+  // The trigger pipeline has not registered our source yet. Inserting anyway
+  // would produce a chip DSH refuses to submit, so the click is declined.
+  case 'source-unregistered':return 'Schematic Gen is still starting up — click again in a moment.'
+  default:return 'Schematic Gen is unavailable in this session.'
  }
+}
 }})

package/src/client/schematic-ref.ts

@@ -5,10 +5,13 @@
  * SSE agents were removed with the package). The chip identity, the `@`
  * trigger, the clipboard projection and the menu row are preserved verbatim so
  * existing drafts and the composer UX keep working. The one deliberate change:
- * the chip's model text now pins the bundled `kicad-schematic-design` skill
- * instead of the deleted online tools (`generate_schematic_from_description` /
- * `generate_system_module_graph`), because the design skill is the new local
- * entry point the agent must follow.
+ * the chip's model text is now the bare clipboard token — the semantics that
+ * used to ride in the payload (pin the `kicad-schematic-design` skill instead
+ * of the deleted online tools `generate_schematic_from_description` /
+ * `generate_system_module_graph`, forbid hand-written KiCad files, defer to
+ * the user's words) moved to the node half's `huaqiu:schematic-gen`
+ * system-prompt section; see {@link SCHEMATIC_GEN_SERIALIZED} and
+ * `src/prompt.ts`.
  *
  * One module owns the identity of the chip, its menu row, and the model text
  * the chip expands to at submit time. Registering the source is MANDATORY, not
@@ -18,6 +21,12 @@
  * source"). A chip inserted without a registered source would therefore block
  * the user's message instead of degrading quietly.
  *
+ * The registration is also ORDER-sensitive: the trigger service is provided by
+ * a plugin whose own dependency chain is longer than ours, so reading it once
+ * at `apply()` time can find nothing. The entry therefore declares
+ * `inputTriggers` in its `inject` (cordis parks the plugin until the provider
+ * exists) and retries briefly if it still arrives late.
+ *
  * Registering it also buys the typed path for free: the user can type `@` and
  * pick *Generate schematic* (生成原理图 under a Chinese UI) from a group beside
  * *Files & folders* / *Sessions*.
@@ -115,30 +124,27 @@ export function schematicGenDescription(lang: HostLocale | undefined = detectHos
 
 /**
  * Model form of the chip: what the agent actually reads at the chip's position
- * in the user message.
+ * in the user message — the clipboard token itself, nothing more.
+ *
+ * This is the idiomatic mention pattern (DSH's own draft tests serialize a
+ * reference to its ref), and it is deliberate on two counts:
  *
- * Deliberately an *intent*, never a fabricated design description — the user's
- * own words stay the only source of requirements, and the plugin being loaded
- * is never by itself a reason to generate.
+ * 1. **Whatever `serialize` returns lands in the USER message** — the submit
+ *    plane splices it over the chip's clipboard range — so a long payload is
+ *    noise the user reads back in their own transcript on every send.
+ * 2. **The token has no semantics of its own**, so the semantics cannot live
+ *    here; they live in the node half's `huaqiu:schematic-gen` system-prompt
+ *    section (see `src/prompt.ts`), which defines the token, pins the
+ *    `kicad-schematic-design` skill, and carries the guardrails.
  *
- * The retired plugin pinned the online tools here
- * (`generate_schematic_from_description` / `generate_system_module_graph`).
- * The migrated chip pins the bundled `kicad-schematic-design` skill instead:
- * the skill owns the module search / part import / editable-project flow, and
- * starts from the hardware design brief when no plan exists yet. Hand-written
- * KiCad files stay forbidden in both worlds.
+ * History: the chip first shipped a 6-line `<schematic-gen intent=…>` block,
+ * then a 3-line trimmed form, and now delegates entirely to the section. The
+ * retired plugin pinned deleted online tools here
+ * (`generate_schematic_from_description` / `generate_system_module_graph`);
+ * nothing in this constant may ever name a tool again — the skill pin is the
+ * section's job.
  */
-export const SCHEMATIC_GEN_SERIALIZED =
-  '<schematic-gen intent="kicad-schematic-design">\n' +
-  'The user explicitly chose Schematic Gen for this request. Produce the design ' +
-  'with the `kicad-schematic-design` skill; when the hardware design brief is ' +
-  'missing or incomplete, the skill starts by preparing it before the schematic ' +
-  'work.\n' +
-  'Never hand-write .kicad_sch files or KiCad project files yourself — always go ' +
-  'through the skill and its tools.\n' +
-  "Use the user's own words as the design description. If they have not described " +
-  'the circuit yet, ask for the requirements instead of assuming them.\n' +
-  '</schematic-gen>'
+export const SCHEMATIC_GEN_SERIALIZED = SCHEMATIC_GEN_CLIPBOARD
 
 /** Menu/group candidate description. */
 /**
@@ -255,18 +261,167 @@ export function createSchematicGenSource(
  * @returns disposer (a no-op when registration did not happen).
  */
 export function registerSchematicGenSource(registry: unknown): () => void {
+  return registerSchematicGenSourceTracked(registry).dispose
+}
+
+/** Outcome of one registration attempt. */
+export interface SchematicGenRegistration {
+  /** Whether the source is now live in the trigger roster. */
+  readonly registered: boolean
+  /** Unregister (a no-op when the attempt did not register). */
+  readonly dispose: () => void
+}
+
+/**
+ * One registration attempt, reported instead of swallowed.
+ *
+ * {@link registerSchematicGenSource} is the disposer-only view for callers that
+ * do not care; this is the same attempt with the outcome visible, which is what
+ * a caller needs to decide whether a chip may be inserted at all — an
+ * unregistered source makes every send fail (see the module header).
+ *
+ * @param registry - `ctx.get('inputTriggers')`, or undefined.
+ * @returns whether the registration landed, plus its disposer.
+ */
+export function registerSchematicGenSourceTracked(registry: unknown): SchematicGenRegistration {
   if (
     registry === undefined || registry === null ||
     typeof (registry as InputTriggerRegistryLike).registerSource !== 'function'
   ) {
-    return () => {}
+    return { registered: false, dispose: () => {} }
   }
   try {
     const dispose = (registry as InputTriggerRegistryLike).registerSource(createSchematicGenSource())
-    return typeof dispose === 'function' ? dispose : () => {}
+    return {
+      registered: true,
+      dispose: typeof dispose === 'function' ? dispose : () => {},
+    }
   } catch {
     // Already registered (duplicate trigger/name) — the existing owner keeps
     // serving our chips, which is the correct outcome.
-    return () => {}
+    return { registered: true, dispose: () => {} }
+  }
+}
+
+/** Scheduler seam for {@link registerSchematicGenSourceWhenReady} (tests inject fakes). */
+export interface RegistrationRetryHooks {
+  /** Poll interval while the trigger service is still absent. */
+  intervalMs?: number
+  /** Give up after this many polls; default 80 (≈20 s at 250 ms). */
+  maxAttempts?: number
+  /** Timer constructor; defaults to the host `setInterval`. */
+  setTimer?: (fn: () => void, ms: number) => unknown
+  /** Timer destructor; defaults to the host `clearInterval`. */
+  clearTimer?: (handle: unknown) => void
+  /** Trace sink; defaults to this module's {@link trace}. */
+  trace?: (event: string, payload?: unknown) => void
+}
+
+/** Live registration handle returned by {@link registerSchematicGenSourceWhenReady}. */
+export interface SchematicGenSourceBinding {
+  /** Whether the source is registered RIGHT NOW (re-read on every call). */
+  registered(): boolean
+  /** Stop retrying and unregister. */
+  dispose(): void
+}
+
+/**
+ * Host timer, or undefined where there is none.
+ *
+ * The retry is browser-only machinery, and the built bundle is also evaluated
+ * in bare hosts (the vm-based card test, a non-DOM worker) where `setInterval`
+ * does not exist. Those must degrade to "not registered yet" — a throw here
+ * would take the whole client half down, which is the failure mode this module
+ * exists to prevent.
+ */
+function hostTimer(): { set: (fn: () => void, ms: number) => unknown; clear: (handle: unknown) => void } | undefined {
+  if (typeof setInterval !== 'function' || typeof clearInterval !== 'function') return undefined
+  return {
+    set: (fn, ms) => setInterval(fn, ms),
+    clear: (handle) => clearInterval(handle as never),
+  }
+}
+
+/**
+ * Register the source, polling while the trigger service has not activated yet.
+ *
+ * Why this exists: activation is service-availability driven, and
+ * `inputTriggers` is provided by a plugin (`dsh-client-ui-input-trigger`) whose
+ * own dependency chain is far longer than ours. A plugin that reads the service
+ * exactly once at `apply()` time and finds it absent registers NOTHING —
+ * silently. The chip then lands in the composer (insertion only needs
+ * `conversation`) and the send dies on
+ * `slash: no serializer for reference source "schematic-gen"`, because the
+ * controller routes every chip to its owner's codec. Declaring `inputTriggers`
+ * in the plugin's `inject` is the primary fix (cordis then parks this plugin
+ * until the provider exists); this poll is the belt-and-braces path for a
+ * provider that arrives later than that declaration could promise.
+ *
+ * @param getRegistry - returns the current `ctx.get('inputTriggers')` value.
+ * @param hooks - scheduler/trace seams.
+ * @returns a live binding whose `registered()` the caller may consult.
+ */
+export function registerSchematicGenSourceWhenReady(
+  getRegistry: () => unknown,
+  hooks: RegistrationRetryHooks = {},
+): SchematicGenSourceBinding {
+  const intervalMs = hooks.intervalMs ?? 250
+  const maxAttempts = hooks.maxAttempts ?? 80
+  const traceFn = hooks.trace ?? trace
+  const timer = hooks.setTimer !== undefined && hooks.clearTimer !== undefined
+    ? { set: hooks.setTimer, clear: hooks.clearTimer }
+    : hostTimer()
+
+  let current: SchematicGenRegistration = registerSchematicGenSourceTracked(getRegistry())
+  let handle: unknown
+  let attempts = 0
+  let stopped = false
+
+  const stopTimer = (): void => {
+    if (handle === undefined || timer === undefined) return
+    timer.clear(handle)
+    handle = undefined
+  }
+
+  const dispose = (): void => {
+    stopped = true
+    stopTimer()
+    current.dispose()
+  }
+
+  if (current.registered) {
+    return { registered: () => true, dispose }
+  }
+
+  if (timer === undefined) {
+    // No timer host: the caller's `registered()` stays false and the sidebar
+    // click declines to insert, which is the honest outcome — a chip that
+    // cannot be submitted is worse than no chip.
+    traceFn('no timer host — source registration not retried')
+    return { registered: () => false, dispose }
+  }
+
+  traceFn('waiting for inputTriggers', { intervalMs, maxAttempts })
+  handle = timer.set(() => {
+    if (stopped) return
+    attempts += 1
+    const next = registerSchematicGenSourceTracked(getRegistry())
+    if (next.registered) {
+      // The earlier attempt registered nothing, so it carries no disposer of
+      // its own — only the winning registration needs unregistering.
+      current = next
+      stopTimer()
+      traceFn('registered (late)', { attempts })
+      return
+    }
+    if (attempts >= maxAttempts) {
+      stopTimer()
+      traceFn('source registration gave up', { attempts })
+    }
+  }, intervalMs)
+
+  return {
+    registered: () => current.registered,
+    dispose,
   }
 }

package/src/index.ts

@@ -8,10 +8,11 @@ import {apply as registerSchematic} from './schematic/index.ts'
 import {apply as registerSkills} from './skills.ts'
 import {registerModuleAnalysis} from './schematic/analysis-tool.ts'
 import {getKiCadPaths} from './runtime-paths.ts'
+import {registerSchematicGenSection} from './prompt.ts'
 
 export {Config,resolveConfig} from './config.ts'
 export const name='@huaqiu/dsh-tool-kicad-schematic-gen'
-export const inject=['tools','fs','sandboxPolicy','skills','webServer'] as const
+export const inject=['tools','fs','sandboxPolicy','skills','webServer','systemPrompt'] as const
 
 /** Shared component name for the unified DSH-plugin log (`~/.hq-edge/logs/dsh-plugins`). */
 const log = getLogger('dsh-schematic-gen')
@@ -20,7 +21,7 @@ const log = getLogger('dsh-schematic-gen')
 // ready" means the entry is parked on an unprovided service (or that another
 // entry's failure stopped the boot), which is a different problem from a
 // failure inside apply().
-log.info('schematic-gen: module loaded (waiting for the tools, fs, sandboxPolicy, skills and webServer services)')
+log.info('schematic-gen: module loaded (waiting for the tools, fs, sandboxPolicy, skills, webServer and systemPrompt services)')
 
 export function apply(ctx:Context, input:ConfigInput={}):void {
   const config=resolveConfig(input)
@@ -36,6 +37,14 @@ export function apply(ctx:Context, input:ConfigInput={}):void {
     registerModules(ctx,config.modules,analyze)
     registerSchematic(ctx,config.schematic)
     registerSkills(ctx,config.schematic.kicadCliPath)
+    // The `@schematic-gen` chip serializes to its bare token; this section is
+    // what gives that token meaning (see prompt.ts for why it is static).
+    const disposeSection = registerSchematicGenSection((ctx as {systemPrompt?:unknown}).systemPrompt)
+    if (disposeSection === undefined) {
+      log.warn('systemPrompt service unavailable — the huaqiu:schematic-gen section was not registered')
+    } else {
+      ctx.effect(() => disposeSection)
+    }
   } catch (error) {
     log.error('schematic-gen node half failed',{error:String((error as Error)?.message??error)})
     throw error

package/src/prompt.ts

@@ -0,0 +1,131 @@
+/**
+ * The `huaqiu:schematic-gen` system-prompt section.
+ *
+ * Split out from `src/index.ts` so the text and the registration are
+ * unit-testable without a cordis context, tools, or a skill registry — the
+ * same split `@huaqiu/dsh-eda-selection` uses for its `eda:selection` section.
+ *
+ * ── Why a section at all ────────────────────────────────────────────────────
+ * The composer chip's model form is the bare `@schematic-gen` token (see
+ * `client/schematic-ref.ts`): the token is a UI affordance with no semantics
+ * of its own, and whatever `codec.serialize` returns lands in the USER
+ * message — repeating it on every send is noise the user reads back in their
+ * own transcript. The section carries the semantics once, in the system
+ * prompt, where policy text belongs.
+ *
+ * ── Why static, not a per-session provider ──────────────────────────────────
+ * "Once the user chose Schematic Gen, the rest of the conversation continues
+ * that work" is already true without any session state: the token sits in the
+ * conversation history for every later turn, and the section is re-read on
+ * every assembly. A dynamic provider would need a session-state source — the
+ * only candidates are message-history I/O or a client→node signal, and prompt
+ * assembly is on the agent's hot path (`dsh-eda-selection` documents the same
+ * no-I/O rule). So the section is static text gated on the token, not a
+ * per-session flag.
+ *
+ * @module
+ */
+
+/**
+ * Unique prompt-section name.
+ *
+ * Reuses the retired `huaqiu:schematic-gen` name: `dsh-eda-selection` records
+ * that the old section "has moved to the bundled kicad-schematic-design
+ * skill", and this is that section coming back for the chip era — same slot,
+ * same adjacency, no other registration to collide with.
+ */
+export const HUAQIU_SCHEMATIC_GEN_SECTION = 'huaqiu:schematic-gen'
+
+/**
+ * Centrally allocated placement: 590, between DSH's `PLAN_POLICY` (500) and
+ * `TEAM_POLICY` (600).
+ *
+ * That is where `dsh-eda-selection` pins its `eda:selection` section, so both
+ * Huaqiu policy blocks stay adjacent and both precede the tool-list sections
+ * (`TOOL_*` at 1000+) they refer to. `ctx.systemPrompt.getSectionOrder()`
+ * resolves only DSH's own named positions, so the number is pinned here and
+ * asserted by a test.
+ */
+export const HUAQIU_SCHEMATIC_GEN_SECTION_ORDER = 590
+
+/** The chip token the section is gated on — the chip's clipboard projection. */
+export const SCHEMATIC_GEN_TOKEN = '@schematic-gen'
+
+/**
+ * The section text: what the `@schematic-gen` token MEANS.
+ *
+ * Static on purpose (see the module header). Four jobs, each mapping to a
+ * failure mode observed with the earlier inline-payload chip:
+ * 1. define the token as an explicit user choice — a bare token alone is an
+ *    opaque string the model has no trained semantics for;
+ * 2. pin the `kicad-schematic-design` skill — the retired online tools are
+ *    gone, so an unpinned agent may reach for a dead entry point;
+ * 3. forbid hand-written `.kicad_sch` files — asked for "an ESP32 mini", an
+ *    LLM will otherwise author KiCad files itself, which KiCad cannot open;
+ * 4. defer requirements to the user's own words — a gesture is not a spec.
+ *
+ * It never claims the token carries content: it says what the token means,
+ * nothing about what the user asked for.
+ */
+export function schematicGenSectionText(): string {
+  return [
+    `Schematic Gen: the ${SCHEMATIC_GEN_TOKEN} token in a user message is the ` +
+      'Schematic Gen chip — the user explicitly chose it for that request. ' +
+      'Produce the design with the `kicad-schematic-design` skill, which ' +
+      'starts from the hardware design brief when none exists yet.',
+    'Never hand-write .kicad_sch files or KiCad project files yourself; go ' +
+      'through the skill and its tools.',
+    "Use the user's own words as the design description — if they have not " +
+      'described the circuit yet, ask for the requirements instead of ' +
+      'assuming them.',
+    'Follow-up messages in the same conversation continue that work without ' +
+      'repeating the token.',
+  ].join('\n')
+}
+
+/**
+ * Structural view of `ctx.systemPrompt` — only the face we use.
+ *
+ * Structural so this module compiles without depending on
+ * `@deepseek-ai/dsh-system-prompt` (whose `Context` augmentation would
+ * otherwise have to be in the compilation for a typed `ctx.systemPrompt`).
+ */
+export interface SystemPromptLike {
+  section(section: {
+    name: string
+    order: number
+    text: string | ((context: unknown) => string)
+  }): () => void
+}
+
+/**
+ * Register the static Schematic Gen section.
+ *
+ * Never throws: a DSH deployment without the prompt service, or one where a
+ * duplicate registration races (hot reload), must still load the tools and
+ * the skill — the section is an enhancement, not a dependency of the rest of
+ * the plugin. A duplicate is the expected hot-reload case, so it is swallowed
+ * rather than surfaced; the first registration keeps serving.
+ *
+ * @param systemPrompt - `ctx.systemPrompt`, or undefined.
+ * @returns the section's disposer, or `undefined` when nothing was registered.
+ */
+export function registerSchematicGenSection(systemPrompt: unknown): (() => void) | undefined {
+  if (
+    systemPrompt === undefined || systemPrompt === null ||
+    typeof (systemPrompt as SystemPromptLike).section !== 'function'
+  ) {
+    return undefined
+  }
+  try {
+    const dispose = (systemPrompt as SystemPromptLike).section({
+      name: HUAQIU_SCHEMATIC_GEN_SECTION,
+      order: HUAQIU_SCHEMATIC_GEN_SECTION_ORDER,
+      text: schematicGenSectionText(),
+    })
+    return typeof dispose === 'function' ? dispose : undefined
+  } catch {
+    // Duplicate registration (hot reload) — the first one is still live.
+    return undefined
+  }
+}