@huaqiu/dsh-hqsch 0.4.8

package/skills/hqsch-scenario-b/docs/rpc-index/pattern-layout.md

@@ -0,0 +1,38 @@
+---
+name: eda-pattern-layout
+metadata:
+  category: pattern-layout
+description: >-
+  Pattern Layout operations for Huaqiu EDA. Use this skill when you need to work with pattern-layout-related operations including apply circuit pattern, get page occupancy, list circuit patterns.
+version: 0.1.0
+vendor: Huaqiu Electronics
+tags:
+  - eda
+  - huaqiu
+  - pattern-layout
+entry: "@huaqiu/hqeda"
+manifest: "@huaqiu/hqeda/skill.json"
+---
+
+# Pattern Layout Skills
+
+Pattern Layout operations for Huaqiu EDA. Use this skill when you need to work with pattern-layout-related operations including apply circuit pattern, get page occupancy, list circuit patterns.
+
+## Available Capabilities
+
+Total: **3** skills in the **pattern-layout** domain.
+
+| Skill | Description | Streaming |
+| --- | --- | --- |
+| [`apply-circuit-pattern`](apply-circuit-pattern/SKILL.md) | Lay out and wire one circuit pattern. plan_only = true is the dry-run. | no |
+| [`get-page-occupancy`](get-page-occupancy/SKILL.md) | Bounding boxes of what is already on the page, for floorplanning / avoidance. | no |
+| [`list-circuit-patterns`](list-circuit-patterns/SKILL.md) | Self-describing catalog — keeps the skill docs from drifting away from the
+implementation. Call it  | no |
+
+## See Also
+
+- [All EDA skills](../SKILL.md)
+- [quickstart.md](../references/quickstart.md)
+- [serialization.md](../references/serialization.md)
+- [`@huaqiu/hqeda` npm package](https://www.npmjs.com/package/@huaqiu/hqeda) — shared runtime + capability registry
+

package/skills/hqsch-scenario-b/docs/rpc-index/placement.md

@@ -0,0 +1,48 @@
+---
+name: eda-placement
+metadata:
+  category: placement
+description: >-
+  Placement operations for Huaqiu EDA. Invoke when placing parts, symbols, or blocks on a schematic — R/C/Q/U via PlaceKicadSymbol (online), GND/VCC/port via PlaceSymbolFromLibrary, local fallback via PlacePartFromLibrary.
+version: 0.1.0
+vendor: Huaqiu Electronics
+tags:
+  - eda
+  - huaqiu
+  - placement
+entry: "@huaqiu/hqeda"
+manifest: "@huaqiu/hqeda/skill.json"
+---
+
+# Placement Skills
+
+Placement operations for Huaqiu EDA. Invoke when placing parts, symbols, or blocks on a schematic — R/C/Q/U via PlaceKicadSymbol (online), GND/VCC/port via PlaceSymbolFromLibrary, local fallback via PlacePartFromLibrary.
+
+## Available Capabilities
+
+Total: **14** skills in the **placement** domain.
+
+| Skill | Description | Streaming |
+| --- | --- | --- |
+| [`cancel-block-draw`](cancel-block-draw/SKILL.md) | Cancel Block Draw via ComponentPlaceService.CancelBlockDraw | no |
+| [`clear-net-alias-attach-obj`](clear-net-alias-attach-obj/SKILL.md) | Clear Net Alias Attach Obj via ComponentPlaceService.ClearNetAliasAttachObj | no |
+| [`handle-block-draw-click`](handle-block-draw-click/SKILL.md) | Handle Block Draw Click via ComponentPlaceService.HandleBlockDrawClick | no |
+| [`handle-part-draw-click`](handle-part-draw-click/SKILL.md) | Handle Part Draw Click via ComponentPlaceService.HandlePartDrawClick | no |
+| [`handle-symbol-draw-click`](handle-symbol-draw-click/SKILL.md) | Handle Symbol Draw Click via ComponentPlaceService.HandleSymbolDrawClick | no |
+| [`list-part-libraries`](list-part-libraries/SKILL.md) | Fallback listing for local/builtin part libraries — agents prefer online part-search (searchParts →  | no |
+| [`list-symbol-libraries`](list-symbol-libraries/SKILL.md) | Agent path: list global/power/gnd, port, off-page symbols — call before PlaceSymbolFromLibrary | no |
+| [`place-block`](place-block/SKILL.md) | block | no |
+| [`place-kicad-symbol`](place-kicad-symbol/SKILL.md) | Place R/C/Q/U from online KiCad symbol URL (SCH_PlaceKicadSymbolFromResource). Invoke after part-sea | no |
+| [`place-part`](place-part/SKILL.md) | INTERNAL: low-level part placement — requires engine-native JSON; agents use PlaceKicadSymbol (onlin | no |
+| [`place-part-from-library`](place-part-from-library/SKILL.md) | Place a part from local/builtin library (discrete, etc.). Invoke when online part-search has no matc | no |
+| [`place-symbol`](place-symbol/SKILL.md) | INTERNAL: low-level symbol placement — requires engine-native JSON; agents use PlaceSymbolFromLibrar | no |
+| [`place-symbol-from-library`](place-symbol-from-library/SKILL.md) | Place GND/VCC/power, port, or off-page symbol from symbol libraries. Invoke for power symbols and co | no |
+| [`set-net-alias-attach-obj`](set-net-alias-attach-obj/SKILL.md) | net alias attach | no |
+
+## See Also
+
+- [All EDA skills](../SKILL.md)
+- [quickstart.md](../references/quickstart.md)
+- [serialization.md](../references/serialization.md)
+- [`@huaqiu/hqeda` npm package](https://www.npmjs.com/package/@huaqiu/hqeda) — shared runtime + capability registry
+

package/skills/hqsch-scenario-b/docs/rpc-index/project.md

@@ -0,0 +1,47 @@
+---
+name: eda-project
+metadata:
+  category: project
+description: >-
+  Project operations for Huaqiu EDA. Invoke when opening, saving, or navigating project pages and schematics.
+version: 0.1.0
+vendor: Huaqiu Electronics
+tags:
+  - eda
+  - huaqiu
+  - project
+entry: "@huaqiu/hqeda"
+manifest: "@huaqiu/hqeda/skill.json"
+---
+
+# Project Skills
+
+Project operations for Huaqiu EDA. Invoke when opening, saving, or navigating project pages and schematics.
+
+## Available Capabilities
+
+Total: **10** skills in the **project** domain.
+
+| Skill | Description | Streaming |
+| --- | --- | --- |
+| [`activate-page-in-project`](activate-page-in-project/SKILL.md) | Switch active workspace and open the target page canvas. | no |
+| [`add-page-to-project`](add-page-to-project/SKILL.md) | Add a VxPage to an existing VxSchematic in an opened project (does not open canvas).
+See AddPageToP | no |
+| [`close-project`](close-project/SKILL.md) | Closes an opened project. | no |
+| [`create-project`](create-project/SKILL.md) | Create a new project/design at directory/file_name and open it.
+A default schematic (typically SCHE | no |
+| [`get-active-project`](get-active-project/SKILL.md) | Returns the project currently active in the editor UI. | no |
+| [`get-project`](get-project/SKILL.md) | Returns one opened project. | no |
+| [`list-open-projects`](list-open-projects/SKILL.md) | Returns all projects currently opened in this HQ EDA process.
+Use response.projects[].name as proje | no |
+| [`list-project-tree`](list-project-tree/SKILL.md) | List schematic/page tree (VxSchematic::m_strName → VxPage::m_strName[]) for an opened project. | no |
+| [`open-project`](open-project/SKILL.md) | Opens a project into the current HQ EDA editor process. | no |
+| [`save-project`](save-project/SKILL.md) | Persists an opened project. | no |
+
+## See Also
+
+- [All EDA skills](../SKILL.md)
+- [quickstart.md](../references/quickstart.md)
+- [serialization.md](../references/serialization.md)
+- [`@huaqiu/hqeda` npm package](https://www.npmjs.com/package/@huaqiu/hqeda) — shared runtime + capability registry
+

package/skills/hqsch-scenario-b/docs/serialization.md

@@ -0,0 +1,60 @@
+# Serializing Protobuf Responses
+
+Skill responses are protobuf message objects from `@bufbuild/protobuf`. **Do not use `JSON.stringify()` directly** on RPC results — it throws on `BigInt` fields and produces empty objects for oneof ADT fields.
+
+## Recommended helpers (RPC responses)
+
+```typescript
+import { toJson, toJsonString } from "@huaqiu/hqeda";
+// Also available from @huaqiu/huaqiu-client in this package's template.
+
+// Plain JSON object (BigInts → strings)
+const jsonObj = toJson(result);
+
+// Formatted JSON string
+const jsonStr = toJsonString(result, { prettySpaces: 2 });
+
+// Include zero-valued fields
+const full = toJsonString(result, { alwaysEmitImplicit: true });
+```
+
+These helpers handle:
+
+- **BigInt fields** — converted to strings (protobuf JSON convention)
+- **oneof fields** — serialized as `{ case, value }` ADT objects
+- **Well-known types** — `Timestamp` → ISO string, `Duration` → `"Ns"` format, `Struct` → plain object
+- **bytes fields** — base64-encoded strings
+- **Zero-value omission** — empty fields excluded by default (protobuf default)
+
+## Common mistake (protobuf messages)
+
+```typescript
+// Wrong — throws "Do not know how to serialize a BigInt"
+JSON.stringify(result);
+
+// Correct
+toJsonString(result);
+```
+
+## Snapshot / position BigInt (raw traversal)
+
+Even after you pull fields out of a snapshot (e.g. `pin.position.x/y`), those
+coordinates are still **`bigint`**. If you build a plain object and call
+`JSON.stringify` without a replacer, you hit:
+
+```text
+TypeError: Do not know how to serialize a BigInt
+```
+
+Use a replacer whenever you stringify **extracted** snapshot data (not only
+whole RPC messages):
+
+```typescript
+const bigIntSafe = (_k: string, v: unknown) =>
+  typeof v === "bigint" ? String(v) : v;
+
+console.log(JSON.stringify(row, bigIntSafe, 2));
+```
+
+Prefer `toJsonString` for full RPC responses; use the replacer for hand-built
+summaries from `GetSnapshot` fields.

package/skills/hqsch-scenario-b/docs/skill-dependencies.md

@@ -0,0 +1,93 @@
+# Cross-Skill Dependencies
+
+Common prerequisite chains when composing multi-step Agent workflows.
+
+## Obtaining projectId
+
+Required by: `bom-get-bom`, `bom-watch-bom`, `netlist-*`, and most project-scoped operations.
+
+| Step | Skill | Purpose |
+| --- | --- | --- |
+| 1 | [`project-get-active-project`](../project/get-active-project/SKILL.md) | Read the currently active project |
+| alt | [`project-list-open-projects`](../project/list-open-projects/SKILL.md) | List all open projects when none is active |
+
+## Building context
+
+Required by: canvas, selection, project save/open, and most editor-mutating RPCs.
+
+| Context type | How to build | Used by |
+| --- | --- | --- |
+| Editor context | `client.createEditorContext()` after `connect()` | Project listing, discovery |
+| Project context | `client.createProjectContext(projectId)` | Canvas ops, selection, placement |
+
+See [quickstart.md](quickstart.md) for the full connect chain.
+
+## Typical workflows
+
+### Read BOM for active project
+
+```
+connect → project-get-active-project → bom-get-bom
+```
+
+### Select object then query property
+
+```
+connect → project-get-active-project → selection-set-selection → canvas-get-object-property
+```
+
+### Run ERC then show findings
+
+```
+connect → project-get-active-project → erc-run-checks → erc-show-findings
+```
+
+### Place symbol on canvas
+
+```
+connect → project-get-active-project → placement-list-symbol-libraries → placement-place-kicad-symbol
+```
+
+### Apply a circuit pattern (decoupling / pull / I2C / SPI / crystal)
+
+```
+connect → project-get-active-project
+  → pattern-layout-list-circuit-patterns
+  → pattern-layout-get-page-occupancy
+  → placement-place-kicad-symbol (or placement-place-symbol-from-library)
+  → pattern-layout-apply-circuit-pattern (plan_only=true)
+  → pattern-layout-apply-circuit-pattern (plan_only=false)
+  → kernel-get-snapshot / netlist-get-active-page-net-list
+```
+
+| Step | Skill | Purpose |
+| --- | --- | --- |
+| 1 | [`pattern-layout-list-circuit-patterns`](../pattern-layout/list-circuit-patterns/SKILL.md) | Roles, terminals, options, typical_size |
+| 2 | [`pattern-layout-get-page-occupancy`](../pattern-layout/get-page-occupancy/SKILL.md) | Floorplan / pick a free `anchor` |
+| 3 | [`placement-place-kicad-symbol`](../placement/place-kicad-symbol/SKILL.md) | Place bound parts (position may be rough) |
+| 4 | [`pattern-layout-apply-circuit-pattern`](../pattern-layout/apply-circuit-pattern/SKILL.md) | Dry-run then execute; book-keep `occupied_box` |
+
+Guide: [circuit-pattern-layout.md](../../hqeda/guides/circuit-pattern-layout.md).
+
+### Connect distant pins via stub + Net Alias
+
+Use when Manhattan > **400** (cross-part), estimated L-route > **500**, crossings ≥ 3,
+or connecting **different parts** on the same net (SPI default). Full heuristics:
+[placement-conventions.md](../../hqeda/guides/placement-conventions.md#stub--net-alias-long-distance--many-crossings).
+
+```
+connect → project-get-active-project → kernel-get-snapshot (or canvas-list-wire-segments)
+  → [agent: distance / crossing check]
+  → per pin end (same netName at both ends): place-pin-stub-wire-and-net-alias
+  → kernel-get-snapshot or netlist-get-active-page-net-list (verify)
+```
+
+| Step | Skill | Purpose |
+| --- | --- | --- |
+| 1 | [`project-get-active-project`](../project/get-active-project/SKILL.md) | Build `ProjectContext` |
+| 2 | [`kernel-get-snapshot`](../kernel/get-snapshot/SKILL.md) or [`canvas-list-wire-segments`](../canvas/list-wire-segments/SKILL.md) | Pin positions, existing wires (crossing check) |
+| 3 | [`obj-place-place-pin-stub-wire-and-net-alias`](../obj-place/place-pin-stub-wire-and-net-alias/SKILL.md) | Per pin (`objectId`+`pinNum`): new stub unless wire **endpoint** at that pin; verify via NetAlias/netlist, not `wireSegments.netName` |
+
+## Domain index
+
+Browse all domains from the [top-level skill index](../SKILL.md).

package/skills/hqsch-scenario-b/skill.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://schema.huaqiu.com/skills/v1/skill.schema.json",
+  "id": "hqeda-scenario-b",
+  "name": "HQ EDA Scenario B — Coding Agent + Local Scripts",
+  "vendor": "Huaqiu Electronics",
+  "version": "0.1.0",
+  "description": "Self-contained skill for Work Buddy, Codex, and Claude: schematic placement, circuit patterns, routing, netlist check, zoom-all. Agent auto-runs TypeScript via @huaqiu/huaqiu-client.",
+  "skillMarkdown": "./SKILL.md",
+  "resources": {
+    "guides": "./docs",
+    "prompts": "./SYSTEM-PROMPT.md"
+  }
+}

package/skills/hqsch-scenario-b/template/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "hqeda-scenario-b",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "hello": "tsx scripts/hello.ts"
+  },
+  "dependencies": {
+    "@huaqiu/huaqiu-client": "^0.1.7",
+    "@huaqiu/hqeda": "^0.2.7"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/hqsch-scenario-b/template/scripts/edit-property-by-ref.ts

@@ -0,0 +1,44 @@
+/**
+ * Flow C 配方：按位号改属性
+ * REF=C201 PROP=Value NEW="1 µF" CONFIRM=1 npx tsx scripts/edit-property-by-ref.ts
+ */
+import { connect } from "@huaqiu/huaqiu-client";
+
+const REF = process.env.REF;
+const PROP = process.env.PROP ?? "Value";
+const NEW = process.env.NEW;
+const CONFIRM = process.env.CONFIRM === "1";
+
+async function main() {
+  if (!REF || NEW === undefined) throw new Error("需要 REF= 与 NEW=");
+  const client = await connect({ instanceId: process.env.HQ_INSTANCE_ID });
+  const active = await client.project.getActiveProject({ context: client.createEditorContext() });
+  const projectId = active.project?.projectId;
+  if (!projectId) throw new Error("请先打开工程");
+  const ctx = client.createProjectContext(projectId);
+  console.log("projectId:", projectId);
+
+  const found = await client.canvasOps.findObjectByProperty({ context: ctx, propKey: "Reference", propValue: REF });
+  const id = found.objectIds?.[0];
+  if (!id) throw new Error(`找不到 ${REF}`);
+
+  let oldVal = "";
+  try {
+    const g = await client.canvasOps.getObjectProperty({ context: ctx, objectId: id, propKey: PROP });
+    oldVal = String(g.propValue ?? "");
+  } catch { oldVal = "(未知)"; }
+
+  console.log(`\n计划修改: ${REF} ${PROP}: "${oldVal}" → "${NEW}"  objectId=${id}`);
+  if (!CONFIRM) { console.log("未执行。设 CONFIRM=1 后重跑。"); return; }
+
+  await client.canvasOps.setObjectProperty({ context: ctx, objectId: id, propKey: PROP, propValue: NEW, op: 1, commitUndo: true });
+  console.log("✓ 已写入");
+
+  const snap = await client.kernel.getSnapshot({ context: ctx });
+  const sym = (snap.snapshot as { symbolInstances?: Array<{ designator?: string; metadata?: { properties?: Array<{ key: string; value: unknown }> } }> })
+    .symbolInstances?.find((s) => s.designator === REF);
+  const v = sym?.metadata?.properties?.find((p) => p.key === PROP);
+  console.log("快照验收:", PROP, "=", v ? String(Object.values(v.value as object)[0] ?? v.value) : NEW);
+}
+
+main().catch((e) => { console.error("❌", e.message); process.exit(1); });

package/skills/hqsch-scenario-b/template/scripts/fix-designators.ts

@@ -0,0 +1,52 @@
+/**
+ * 修正位号与参数值：
+ *   C1 → C_IN (10 μF), C2 → C_IN_BYPASS (0.1 μF)
+ *   C3 → C_OUT1 (10 μF), C4 → C_OUT2 (0.1 μF)
+ */
+import { connect } from "@huaqiu/huaqiu-client";
+
+const RENAMES: Array<[string, string, string]> = [
+  // [oldRef, newRef, value]
+  ["C1", "C_IN", "10 μF"],
+  ["C2", "C_IN_BYPASS", "0.1 μF"],
+  ["C3", "C_OUT1", "10 μF"],
+  ["C4", "C_OUT2", "0.1 μF"],
+];
+
+async function main() {
+  const client = await connect();
+  const active = await client.project.getActiveProject({ context: client.createEditorContext() });
+  const projectId = active.project?.projectId;
+  if (!projectId) throw new Error("no project");
+  const ctx = client.createProjectContext(projectId);
+
+  for (const [oldRef, newRef, value] of RENAMES) {
+    const found = await client.canvasOps.findObjectByProperty({
+      context: ctx, propKey: "Reference", propValue: oldRef,
+    });
+    const id = found.objectIds?.[0];
+    if (!id) { console.log(`  ⚠ 找不到 ${oldRef}`); continue; }
+
+    await client.canvasOps.setObjectProperty({
+      context: ctx, objectId: id,
+      propKey: "Part Reference", propValue: newRef, op: 1, commitUndo: true,
+    });
+    await client.canvasOps.setObjectProperty({
+      context: ctx, objectId: id,
+      propKey: "Value", propValue: value, op: 1, commitUndo: true,
+    });
+    console.log(`  ✓ ${oldRef} → ${newRef} (${value}) id=${id}`);
+  }
+
+  // 验证
+  console.log("\n验证:");
+  for (const [, newRef] of RENAMES) {
+    const r = await client.canvasOps.findObjectByProperty({
+      context: ctx, propKey: "Reference", propValue: newRef,
+    });
+    console.log(`  ${newRef}: ${(r.objectIds?.length ?? 0) > 0 ? "✓" : "✗"}`);
+  }
+  await client.canvasOps.zoomAll({ context: ctx });
+}
+
+main().catch((e) => { console.error("错误:", e.message); process.exit(1); });

package/skills/hqsch-scenario-b/template/scripts/hello.ts

@@ -0,0 +1,46 @@
+/**
+ * Scenario B smoke test — verify HQ EDA connectivity before circuit automation.
+ *
+ *   npm install
+ *   npx tsx scripts/hello.ts
+ *
+ * Optional: HQ_INSTANCE_ID=<id> when multiple editors are open (run listEditors first).
+ */
+import { connect, listEditors, toJsonString } from "@huaqiu/huaqiu-client";
+
+const INSTANCE = process.env.HQ_INSTANCE_ID;
+
+async function main() {
+  const editors = await listEditors();
+  console.log("editors:", toJsonString(editors, { prettySpaces: 2 }));
+
+  const client = INSTANCE
+    ? await connect({ instanceId: INSTANCE })
+    : await connect();
+
+  console.log("connected:", client.info.instanceId);
+
+  const editorCtx = client.createEditorContext();
+  const active = await client.project.getActiveProject({ context: editorCtx });
+  const projectId = active.project?.projectId;
+  if (!projectId) {
+    throw new Error("No active project — open a schematic in HQ EDA first");
+  }
+  console.log("active project:", active.project?.name, projectId);
+
+  const ctx = client.createProjectContext(projectId);
+  const snap = await client.kernel.getSnapshot({ context: ctx });
+  const parts = snap.symbolInstances?.length ?? 0;
+  const wires = snap.wireSegments?.length ?? 0;
+  console.log(`snapshot: ${parts} symbols, ${wires} wire segments on active page`);
+
+  await client.canvasOps.zoomAll({ context: ctx });
+  console.log("zoomAll: OK");
+
+  console.log("OK — ready for LLM-generated placement scripts");
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});