@huaqiu/dsh-hqsch 0.4.9 → 0.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-hqsch",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -21,7 +21,7 @@
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "dependencies": {
-    "@huaqiu/dsh-plugin-log": "0.4.9"
+    "@huaqiu/dsh-plugin-log": "0.4.10"
   },
   "files": [
     "lib",

package/skills/hqsch-scenario-b/AGENTS.md

@@ -23,10 +23,14 @@
 7. `docs/editing-a-circuit.md` — **局部改电路（Flow C）** / 确认 diff / 修改集 / 验收
 8. `docs/rpc-availability.md` — 接口可用性、禁建列表、耗时基线
 9. `docs/serialization.md` — toJsonString 与 BigInt
-10. `docs/rpc/*.md` — 仅当需要某个 RPC 的精确字段名时查阅
+10. `docs/script-lifetime.md` — **进程生命周期：必须用 `hqMain`，否则泄漏 node 进程**（写任何脚本前先读）
+11. `docs/rpc/*.md` — 仅当需要某个 RPC 的精确字段名时查阅
 
 ## 硬性规则
 
+- **所有脚本必须经 `scripts/lib/hq.ts` 的 `hqMain` / `hqMainWithProject` 进入**；**禁止**裸 `connect()` + `main().catch(e => process.exit(1))`。该外壳负责：每个 RPC 超时、硬看门狗、`client.close()`、保证进程退出。见 `docs/script-lifetime.md`。
+- **不要依赖"脚本会自己退出"**：卡住的 RPC 会让 node 进程永久存活，重试一次多泄漏一个。
+
 - 器件（R/C/Q/U）：在线搜索 + `client.componentPlace.placeKicadSymbol`；**禁止**手写 `json_part` / `PlacePart`
 - 电源符号：`ListSymbolLibraries` → `PlaceSymbolFromLibrary`
   - `kind`：电源/地用 **`LibrarySymbolKind.GLOBAL`（=1）**；`OFF_PAGE=2`，`PORT=3`
@@ -37,7 +41,7 @@
 - **每条 net 先跑 routing gate**：量距离 → 短（≤300 ext、交叉<3）用 `autoConnect`；长/拥挤用双端 `placePinStubWireAndNetAlias`（同一 `netName`）
 - 字母引脚（CC1、A5）：用 `pinName` / `pinNumber` **字符串**，禁止 `Number("A5")`
 - **pattern 的 host 电源引脚必须用 `pinName` 绑定**（如 `pinName:"VIN"`）；用 `pinNum` 会返回 `PIN_RESOLVE_FAILED`
-- **放置后必须等对象注册再 apply**：轮询 `getPageOccupancy` 直到所有新 id 出现，否则 apply 报 `OBJECT_NOT_FOUND` 或假 `PARTIAL`
+- **放置后必须等对象注册再 apply**：轮询 `client.patternLayout.getPageOccupancy`（**不是 canvasOps**；响应字段是 `items[].objectId`，**没有** `objectIds`）直到所有新 id 出现，否则 apply 报 `OBJECT_NOT_FOUND` 或假 `PARTIAL`。推荐直接调用 `waitForRegistered(client, ctx, ids)`（`scripts/lib/hq.ts`）。
 - **读取导线段字段是 `wires`**（`listWireSegments().wires`），**不是** `wireSegments`
 - 打印 protobuf 响应用 `toJsonString`；禁止对 RPC 结果裸 `JSON.stringify()`。遍历快照 `position.x/y`（bigint）时见 `docs/serialization.md` replacer
 - 耗时基线（区间，非 SLA）：快照约 **1.6–3.2s**；单次 pattern/放置脚本约 **15–20s**（抖动正常）。勿用超时反推「未实现」
@@ -74,7 +78,7 @@
    ```
    connect → getActiveProject → createProjectContext
    → 放置 host / 独立器件（part-search → placeKicadSymbol；电源符号 → PlaceSymbolFromLibrary）
-   → 【等待注册】轮询 getPageOccupancy 直到所有新 id 出现（关键！否则 apply 失败）
+   → 【等待注册】轮询 `client.patternLayout.getPageOccupancy`（或 `waitForRegistered()`）直到所有新 id 出现（关键！否则 apply 失败）
    → 规范位号 / 容值（覆盖引擎自动分配的 C1..C4）
    → applyCircuitPattern（每个适用 pattern 一次；先 planOnly 可选，再正式 apply）
    → 仅对 pattern 未覆盖的 net 做 hand-wire（每条 net 先跑 routing gate）
@@ -157,26 +161,23 @@
  *   [<leftover>] → hand (routing gate: 短 autoConnect / 长 stub+alias)
  * =====================================
  */
-import { connect, toJsonString } from "@huaqiu/huaqiu-client";
 import { HqServicesV1PatternLayoutService } from "@hqedge/connect";
+import { hqMainWithProject, waitForRegistered } from "./lib/hq.js";
 
 const PL = HqServicesV1PatternLayoutService;   // 枚举来源
-const INSTANCE = process.env.HQ_INSTANCE_ID;
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-async function main() {
-  const client = INSTANCE
-    ? await connect({ instanceId: INSTANCE })
-    : await connect();
 
-  const editorCtx = client.createEditorContext();
-  const active = await client.project.getActiveProject({ context: editorCtx });
-  const projectId = active.project?.projectId;
-  if (!projectId) throw new Error("请先在 HQ EDA 中打开原理图工程");
-  const ctx = client.createProjectContext(projectId);
+// ⚠ 必须走 hqMainWithProject：它给每个 RPC 加超时、挂硬看门狗、finally 里
+//   client.close()，并保证进程退出。裸 connect() 会泄漏 node 进程。
+hqMainWithProject(async ({ client, projectId, projectContext: ctx }) => {
+  console.log("projectId:", projectId);
 
   // 1) 放置 host / 独立器件（placeKicadSymbol；电源符号 PlaceSymbolFromLibrary）
-  // 2) 【关键】等待注册：轮询 getPageOccupancy 直到所有新 id 出现
+  //    记下返回的 objectId，放进 newIds
+  const newIds: bigint[] = [];
+
+  // 2) 【关键】等待注册：所有新 id 都出现在页面上再继续
+  await waitForRegistered(client, ctx, newIds);
+
   // 3) 规范位号 / 容值
   // 4) applyCircuitPattern — host 引脚用 pinName 绑定
   //      pattern: PL.CircuitPatternId.CIRCUIT_PATTERN_xxx
@@ -189,11 +190,12 @@ async function main() {
 
   await client.canvasOps.zoomAll({ context: ctx });
   console.log("done");
-}
-
-main().catch((e) => { console.error(e); process.exit(1); });
+});
 ```
 
+**禁止**把结尾写成 `main().catch((e) => { console.error(e); process.exit(1); })` ——
+成功路径没有 `process.exit(0)`，且卡住的 RPC 会让进程永不退出。
+
 ## 输出格式
 
 1. 简短设计说明（用了哪些 pattern、接线策略）

package/skills/hqsch-scenario-b/CLAUDE.md

@@ -23,10 +23,14 @@
 7. `docs/editing-a-circuit.md` — **局部改电路（Flow C）** / 确认 diff / 修改集 / 验收
 8. `docs/rpc-availability.md` — 接口可用性、禁建列表、耗时基线
 9. `docs/serialization.md` — toJsonString 与 BigInt
-10. `docs/rpc/*.md` — 仅当需要某个 RPC 的精确字段名时查阅
+10. `docs/script-lifetime.md` — **进程生命周期：必须用 `hqMain`，否则泄漏 node 进程**（写任何脚本前先读）
+11. `docs/rpc/*.md` — 仅当需要某个 RPC 的精确字段名时查阅
 
 ## 硬性规则
 
+- **所有脚本必须经 `scripts/lib/hq.ts` 的 `hqMain` / `hqMainWithProject` 进入**；**禁止**裸 `connect()` + `main().catch(e => process.exit(1))`。该外壳负责：每个 RPC 超时、硬看门狗、`client.close()`、保证进程退出。见 `docs/script-lifetime.md`。
+- **不要依赖"脚本会自己退出"**：卡住的 RPC 会让 node 进程永久存活，重试一次多泄漏一个。
+
 - 器件（R/C/Q/U）：在线搜索 + `client.componentPlace.placeKicadSymbol`；**禁止**手写 `json_part` / `PlacePart`
 - 电源符号：`ListSymbolLibraries` → `PlaceSymbolFromLibrary`
   - `kind`：电源/地用 **`LibrarySymbolKind.GLOBAL`（=1）**；`OFF_PAGE=2`，`PORT=3`
@@ -37,7 +41,7 @@
 - **每条 net 先跑 routing gate**：量距离 → 短（≤300 ext、交叉<3）用 `autoConnect`；长/拥挤用双端 `placePinStubWireAndNetAlias`（同一 `netName`）
 - 字母引脚（CC1、A5）：用 `pinName` / `pinNumber` **字符串**，禁止 `Number("A5")`
 - **pattern 的 host 电源引脚必须用 `pinName` 绑定**（如 `pinName:"VIN"`）；用 `pinNum` 会返回 `PIN_RESOLVE_FAILED`
-- **放置后必须等对象注册再 apply**：轮询 `getPageOccupancy` 直到所有新 id 出现，否则 apply 报 `OBJECT_NOT_FOUND` 或假 `PARTIAL`
+- **放置后必须等对象注册再 apply**：轮询 `client.patternLayout.getPageOccupancy`（**不是 canvasOps**；响应字段是 `items[].objectId`，**没有** `objectIds`）直到所有新 id 出现，否则 apply 报 `OBJECT_NOT_FOUND` 或假 `PARTIAL`。推荐直接调用 `waitForRegistered(client, ctx, ids)`（`scripts/lib/hq.ts`）。
 - **读取导线段字段是 `wires`**（`listWireSegments().wires`），**不是** `wireSegments`
 - 打印 protobuf 响应用 `toJsonString`；禁止对 RPC 结果裸 `JSON.stringify()`。遍历快照 `position.x/y`（bigint）时见 `docs/serialization.md` replacer
 - 耗时基线（区间，非 SLA）：快照约 **1.6–3.2s**；单次 pattern/放置脚本约 **15–20s**（抖动正常）。勿用超时反推「未实现」
@@ -74,7 +78,7 @@
    ```
    connect → getActiveProject → createProjectContext
    → 放置 host / 独立器件（part-search → placeKicadSymbol；电源符号 → PlaceSymbolFromLibrary）
-   → 【等待注册】轮询 getPageOccupancy 直到所有新 id 出现（关键！否则 apply 失败）
+   → 【等待注册】轮询 `client.patternLayout.getPageOccupancy`（或 `waitForRegistered()`）直到所有新 id 出现（关键！否则 apply 失败）
    → 规范位号 / 容值（覆盖引擎自动分配的 C1..C4）
    → applyCircuitPattern（每个适用 pattern 一次；先 planOnly 可选，再正式 apply）
    → 仅对 pattern 未覆盖的 net 做 hand-wire（每条 net 先跑 routing gate）
@@ -157,26 +161,23 @@
  *   [<leftover>] → hand (routing gate: 短 autoConnect / 长 stub+alias)
  * =====================================
  */
-import { connect, toJsonString } from "@huaqiu/huaqiu-client";
 import { HqServicesV1PatternLayoutService } from "@hqedge/connect";
+import { hqMainWithProject, waitForRegistered } from "./lib/hq.js";
 
 const PL = HqServicesV1PatternLayoutService;   // 枚举来源
-const INSTANCE = process.env.HQ_INSTANCE_ID;
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-async function main() {
-  const client = INSTANCE
-    ? await connect({ instanceId: INSTANCE })
-    : await connect();
 
-  const editorCtx = client.createEditorContext();
-  const active = await client.project.getActiveProject({ context: editorCtx });
-  const projectId = active.project?.projectId;
-  if (!projectId) throw new Error("请先在 HQ EDA 中打开原理图工程");
-  const ctx = client.createProjectContext(projectId);
+// ⚠ 必须走 hqMainWithProject：它给每个 RPC 加超时、挂硬看门狗、finally 里
+//   client.close()，并保证进程退出。裸 connect() 会泄漏 node 进程。
+hqMainWithProject(async ({ client, projectId, projectContext: ctx }) => {
+  console.log("projectId:", projectId);
 
   // 1) 放置 host / 独立器件（placeKicadSymbol；电源符号 PlaceSymbolFromLibrary）
-  // 2) 【关键】等待注册：轮询 getPageOccupancy 直到所有新 id 出现
+  //    记下返回的 objectId，放进 newIds
+  const newIds: bigint[] = [];
+
+  // 2) 【关键】等待注册：所有新 id 都出现在页面上再继续
+  await waitForRegistered(client, ctx, newIds);
+
   // 3) 规范位号 / 容值
   // 4) applyCircuitPattern — host 引脚用 pinName 绑定
   //      pattern: PL.CircuitPatternId.CIRCUIT_PATTERN_xxx
@@ -189,11 +190,12 @@ async function main() {
 
   await client.canvasOps.zoomAll({ context: ctx });
   console.log("done");
-}
-
-main().catch((e) => { console.error(e); process.exit(1); });
+});
 ```
 
+**禁止**把结尾写成 `main().catch((e) => { console.error(e); process.exit(1); })` ——
+成功路径没有 `process.exit(0)`，且卡住的 RPC 会让进程永不退出。
+
 ## 输出格式
 
 1. 简短设计说明（用了哪些 pattern、接线策略）

package/skills/hqsch-scenario-b/INSTALL.md

@@ -13,13 +13,13 @@
 | `docs/` | LLM 知识库（工程规范 + 常用 RPC） |
 | `template/` | 本地脚本工程 + 连通性测试 |
 
-维护者更新 guides 或 Scenario-B playbooks 后在本仓库运行：
+**没有组装脚本。** 本目录（`packages/dsh-hqsch/skills/hqsch-scenario-b/`）就是权威来源，
+`docs/` 与 `template/` 直接在此维护；`@huaqiu/dsh-hqsch` 在加载时通过
+`ctx.skills.register` 把整个目录注册为 DSH 内建 skill（`resourceBase = <本目录>`）。
 
-```bash
-cd skills/hqeda && pnpm run build:scenario-b
-```
-
-`build:scenario-b` 会从 monorepo 拷贝 guides + RPC 文档，再合并 `onboarding/scenario-b/docs/`（读电路 / 改电路 / rpc-availability 等）与 `onboarding/scenario-b/template/`。
+> 旧版本 INSTALL 提到的 `cd skills/hqeda && pnpm run build:scenario-b` **已不存在**：
+> 仓库中没有 `skills/hqeda` 目录，也没有任何 `package.json` 定义该 script。
+> 改动 `docs/`、`SYSTEM-PROMPT.md` 后请同步 `AGENTS.md` / `CLAUDE.md`（三者内容一致）。
 
 ---
 
@@ -48,7 +48,7 @@ Skill 包**不包含** HQ EDA 软件本身。
 ```
 my-project/
 ├── AGENTS.md          ← 从本包复制或合并
-├── hqeda-scenario-b/  ← 或解压内容直接放在根目录
+├── hqsch-scenario-b/  ← 或解压内容直接放在根目录
 │   ├── docs/
 │   ├── template/
 │   └── ...
@@ -66,7 +66,7 @@ my-project/
 ### 3. 安装依赖并冒烟测试
 
 ```bash
-cd template    # 或你的 hqeda-scenario-b/template
+cd template    # 或你的 hqsch-scenario-b/template
 npm install
 npx tsx scripts/hello.ts
 ```
@@ -124,17 +124,19 @@ npx skills add <git-url> --path hqeda/scenario-b
 
 ## 五、分发给他人
 
-将整个 `scenario-b/` 打成 `hqeda-scenario-b.zip`：
+将整个 `hqsch-scenario-b/` 打成 `hqsch-scenario-b.zip`：
 
 ```
-hqeda-scenario-b.zip
+hqsch-scenario-b.zip
 ├── SKILL.md
 ├── SYSTEM-PROMPT.md
 ├── AGENTS.md          ← Codex 项目根
 ├── CLAUDE.md          ← Work Buddy / Claude UI
 ├── INSTALL.md
 ├── docs/
+│   └── script-lifetime.md   ← 进程生命周期（必读）
 └── template/
+    └── scripts/lib/hq.ts    ← 所有脚本的运行时外壳（必用）
 ```
 
 附一句：**「解压 → 配置 AGENTS.md 或粘贴 CLAUDE.md → 跑 template/hello.ts → 开始描述电路」**

package/skills/hqsch-scenario-b/SKILL.md

@@ -48,7 +48,8 @@ Follow [SYSTEM-PROMPT.md](./SYSTEM-PROMPT.md) in full. The agent **must auto-run
 | 7 | [docs/editing-a-circuit.md](./docs/editing-a-circuit.md) | **Local edit (Flow C)** — diff, blast radius, verify |
 | 8 | [docs/rpc-availability.md](./docs/rpc-availability.md) | Which RPCs work / ban list / timing baselines |
 | 9 | [docs/serialization.md](./docs/serialization.md) | `toJsonString` + BigInt replacer |
-| 10 | [docs/rpc/](./docs/rpc/) | RPC field reference |
+| 10 | [docs/script-lifetime.md](./docs/script-lifetime.md) | **Process lifetime — must use `hqMain`, or node processes leak** |
+| 11 | [docs/rpc/](./docs/rpc/) | RPC field reference |
 
 **Runtime (agent executes on user's machine):**
 
@@ -58,6 +59,11 @@ cd template && npm install && npx tsx scripts/hello.ts
 
 HQ EDA desktop must be running with a schematic project open.
 
+> **Every script must enter through `hqMain` / `hqMainWithProject` in
+> `scripts/lib/hq.ts`** (per-RPC deadline + hard watchdog + guaranteed exit).
+> A stalled RPC pins the Node event loop and makes the process immortal, so each
+> retry leaks another one. See [docs/script-lifetime.md](./docs/script-lifetime.md).
+
 ## Execution flow (summary)
 
 **Three task types — pick first:**
@@ -103,5 +109,10 @@ HQ EDA desktop must be running with a schematic project open.
   `RunChecks`, `GetSelection` and `Export*` are **unimplemented** in this engine
   build — do not build flows on them. Full map: [docs/rpc-availability.md](./docs/rpc-availability.md).
 - Timing baselines (not SLA): snapshot ~1.6–3.2 s; pattern/place script ~15–20 s.
+- Scripts enter via `hqMain` / `hqMainWithProject` (`scripts/lib/hq.ts`) — never a bare
+  `connect()` + `main().catch()`. Otherwise leaked node processes accumulate on retry.
+- `GetPageOccupancy` is on **`patternLayout`**, not `canvasOps`; its response field is
+  `items[].objectId` (there is no `objectIds`).
+- `GetSnapshot` payloads live one level down: `response.snapshot.symbolInstances`.
 
 Full rules: [SYSTEM-PROMPT.md](./SYSTEM-PROMPT.md).

package/skills/hqsch-scenario-b/SYSTEM-PROMPT.md

@@ -23,10 +23,14 @@
 7. `docs/editing-a-circuit.md` — **局部改电路（Flow C）** / 确认 diff / 修改集 / 验收
 8. `docs/rpc-availability.md` — 接口可用性、禁建列表、耗时基线
 9. `docs/serialization.md` — toJsonString 与 BigInt
-10. `docs/rpc/*.md` — 仅当需要某个 RPC 的精确字段名时查阅
+10. `docs/script-lifetime.md` — **进程生命周期：必须用 `hqMain`，否则泄漏 node 进程**（写任何脚本前先读）
+11. `docs/rpc/*.md` — 仅当需要某个 RPC 的精确字段名时查阅
 
 ## 硬性规则
 
+- **所有脚本必须经 `scripts/lib/hq.ts` 的 `hqMain` / `hqMainWithProject` 进入**；**禁止**裸 `connect()` + `main().catch(e => process.exit(1))`。该外壳负责：每个 RPC 超时、硬看门狗、`client.close()`、保证进程退出。见 `docs/script-lifetime.md`。
+- **不要依赖"脚本会自己退出"**：卡住的 RPC 会让 node 进程永久存活，重试一次多泄漏一个。
+
 - 器件（R/C/Q/U）：在线搜索 + `client.componentPlace.placeKicadSymbol`；**禁止**手写 `json_part` / `PlacePart`
 - 电源符号：`ListSymbolLibraries` → `PlaceSymbolFromLibrary`
   - `kind`：电源/地用 **`LibrarySymbolKind.GLOBAL`（=1）**；`OFF_PAGE=2`，`PORT=3`
@@ -37,7 +41,7 @@
 - **每条 net 先跑 routing gate**：量距离 → 短（≤300 ext、交叉<3）用 `autoConnect`；长/拥挤用双端 `placePinStubWireAndNetAlias`（同一 `netName`）
 - 字母引脚（CC1、A5）：用 `pinName` / `pinNumber` **字符串**，禁止 `Number("A5")`
 - **pattern 的 host 电源引脚必须用 `pinName` 绑定**（如 `pinName:"VIN"`）；用 `pinNum` 会返回 `PIN_RESOLVE_FAILED`
-- **放置后必须等对象注册再 apply**：轮询 `getPageOccupancy` 直到所有新 id 出现，否则 apply 报 `OBJECT_NOT_FOUND` 或假 `PARTIAL`
+- **放置后必须等对象注册再 apply**：轮询 `client.patternLayout.getPageOccupancy`（**不是 canvasOps**；响应字段是 `items[].objectId`，**没有** `objectIds`）直到所有新 id 出现，否则 apply 报 `OBJECT_NOT_FOUND` 或假 `PARTIAL`。推荐直接调用 `waitForRegistered(client, ctx, ids)`（`scripts/lib/hq.ts`）。
 - **读取导线段字段是 `wires`**（`listWireSegments().wires`），**不是** `wireSegments`
 - 打印 protobuf 响应用 `toJsonString`；禁止对 RPC 结果裸 `JSON.stringify()`。遍历快照 `position.x/y`（bigint）时见 `docs/serialization.md` replacer
 - 耗时基线（区间，非 SLA）：快照约 **1.6–3.2s**；单次 pattern/放置脚本约 **15–20s**（抖动正常）。勿用超时反推「未实现」
@@ -74,7 +78,7 @@
    ```
    connect → getActiveProject → createProjectContext
    → 放置 host / 独立器件（part-search → placeKicadSymbol；电源符号 → PlaceSymbolFromLibrary）
-   → 【等待注册】轮询 getPageOccupancy 直到所有新 id 出现（关键！否则 apply 失败）
+   → 【等待注册】轮询 `client.patternLayout.getPageOccupancy`（或 `waitForRegistered()`）直到所有新 id 出现（关键！否则 apply 失败）
    → 规范位号 / 容值（覆盖引擎自动分配的 C1..C4）
    → applyCircuitPattern（每个适用 pattern 一次；先 planOnly 可选，再正式 apply）
    → 仅对 pattern 未覆盖的 net 做 hand-wire（每条 net 先跑 routing gate）
@@ -157,26 +161,23 @@
  *   [<leftover>] → hand (routing gate: 短 autoConnect / 长 stub+alias)
  * =====================================
  */
-import { connect, toJsonString } from "@huaqiu/huaqiu-client";
 import { HqServicesV1PatternLayoutService } from "@hqedge/connect";
+import { hqMainWithProject, waitForRegistered } from "./lib/hq.js";
 
 const PL = HqServicesV1PatternLayoutService;   // 枚举来源
-const INSTANCE = process.env.HQ_INSTANCE_ID;
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-async function main() {
-  const client = INSTANCE
-    ? await connect({ instanceId: INSTANCE })
-    : await connect();
 
-  const editorCtx = client.createEditorContext();
-  const active = await client.project.getActiveProject({ context: editorCtx });
-  const projectId = active.project?.projectId;
-  if (!projectId) throw new Error("请先在 HQ EDA 中打开原理图工程");
-  const ctx = client.createProjectContext(projectId);
+// ⚠ 必须走 hqMainWithProject：它给每个 RPC 加超时、挂硬看门狗、finally 里
+//   client.close()，并保证进程退出。裸 connect() 会泄漏 node 进程。
+hqMainWithProject(async ({ client, projectId, projectContext: ctx }) => {
+  console.log("projectId:", projectId);
 
   // 1) 放置 host / 独立器件（placeKicadSymbol；电源符号 PlaceSymbolFromLibrary）
-  // 2) 【关键】等待注册：轮询 getPageOccupancy 直到所有新 id 出现
+  //    记下返回的 objectId，放进 newIds
+  const newIds: bigint[] = [];
+
+  // 2) 【关键】等待注册：所有新 id 都出现在页面上再继续
+  await waitForRegistered(client, ctx, newIds);
+
   // 3) 规范位号 / 容值
   // 4) applyCircuitPattern — host 引脚用 pinName 绑定
   //      pattern: PL.CircuitPatternId.CIRCUIT_PATTERN_xxx
@@ -189,11 +190,12 @@ async function main() {
 
   await client.canvasOps.zoomAll({ context: ctx });
   console.log("done");
-}
-
-main().catch((e) => { console.error(e); process.exit(1); });
+});
 ```
 
+**禁止**把结尾写成 `main().catch((e) => { console.error(e); process.exit(1); })` ——
+成功路径没有 `process.exit(0)`，且卡住的 RPC 会让进程永不退出。
+
 ## 输出格式
 
 1. 简短设计说明（用了哪些 pattern、接线策略）

package/skills/hqsch-scenario-b/docs/rpc-availability.md

@@ -20,13 +20,21 @@ Do not reverse-engineer “performance regression” from a single hang: some
 unimplemented RPCs historically blocked for minutes before returning a clean
 `unimplemented` in ~2 ms. Prefer this table over timeout guessing.
 
+> **But never wait indefinitely.** A stalled RPC leaves the HTTP/2 stream open,
+> which `ref()`s the Node event loop and makes the `tsx` process immortal — every
+> retry leaks another one. All scripts therefore go through `hqMain` /
+> `hqMainWithProject` in `scripts/lib/hq.ts`, which injects a per-RPC deadline
+> (default 30 s) and a hard watchdog (default 180 s, exit code `124`).
+> See [script-lifetime.md](./script-lifetime.md).
+
 ## Works — OK for flows
 
 | Service | Method | Role |
 | --- | --- | --- |
 | `kernel` | `GetSnapshot` | **Primary** read-circuit / verify source (project-wide) |
 | `netList` | `GetProjectNetList` / `GetActivePageNetList` / `GetSelectionNetList` | Netlist semantics; accessor is **`netList`** (capital L) |
-| `canvasOps` / pattern host | `GetPageOccupancy` | Object registration poll after place |
+| `patternLayout` (**not** `canvasOps`) | `GetPageOccupancy` | Object registration poll after place; response is **`items[].objectId`** — there is no `objectIds` field |
+| `canvasOps` | `AutoConnectObjectsById` | Pin-to-pin connect; `pinNum` accepts **numeric pins only** |
 | `canvasOps` | `ListWireSegments` | Wire stats — field is **`wires`**, not `wireSegments` |
 | `canvasOps` | `GetObjectsJsonByIds` / `GetObjectJsonById` | Optional deep object JSON (advanced) |
 | `find` | `FindObject` | Optional object query (advanced; not Flow B primary) |

package/skills/hqsch-scenario-b/docs/script-lifetime.md

@@ -0,0 +1,92 @@
+# 脚本进程生命周期（强制）
+
+> 每个脚本都必须通过 `scripts/lib/hq.ts` 的 `hqMain` / `hqMainWithProject` 进入。
+> 直接写 `connect(...)` + `main().catch(() => process.exit(1))` 会泄漏 node 进程。
+
+## 症状
+
+跑完脚本后 `ps aux | grep tsx` 里残留一堆 node 进程；agent 重试 3 次就多 3 个；
+最终机器变卡、端口/内存被吃光，而 agent 看到的只是"命令没返回"。
+
+## 根因
+
+`connect()` 内部用 `createGrpcTransport`。HTTP/2 stream 打开期间，会话管理器会
+`ref()` Node 事件循环。若某个 RPC 迟迟不返回：
+
+1. `await` 永不 settle；
+2. stream 不关闭 → 事件循环无法排空；
+3. node 进程永远不退出。
+
+`docs/rpc-availability.md` 明确记录过"部分 RPC 历史上阻塞数分钟后才返回 clean
+unimplemented"，而它同时又叮嘱"不要用超时反推未实现"——两者叠加，agent 就会
+无限等下去，再重试，再泄漏一个进程。
+
+### 为什么 `finally { client.close() }` 救不了
+
+`await` 不 settle 时，控制流根本到不了 `finally`。必须先让 `await` 一定会 settle，
+清理才有意义。`EditorClient.close()` 的官方注释也只保证"测试进程能退出"，
+不保证"卡住的 await 能被唤醒"。
+
+## `scripts/lib/hq.ts` 做什么
+
+| 机制 | 作用 |
+| --- | --- |
+| 每个 RPC 注入 `AbortSignal` 超时 | 让 `await` 一定会 settle（默认 30s） |
+| 硬看门狗 | 无论如何进程都会在 N ms 内终止（默认 180s，退出码 124） |
+| `finally { client.close() }` | 释放 HTTP/2 连接 |
+| `process.exitCode` + 冲刷宽限 | 保证 stdout/stderr 完整输出，不会被 `process.exit()` 截断 |
+
+超时由客户端级代理注入，所以**调用点不用改**——
+`client.kernel.getSnapshot({ context })` 依旧能写，底层已经带 deadline。
+这一点是刻意的：靠 agent 记得给每个 RPC 传 `{ signal }` 是不可靠的。
+
+## 用法
+
+```typescript
+import { hqMain, hqMainWithProject, waitForRegistered } from "./lib/hq.js";
+
+// 只需要连接
+hqMain(async (client) => { /* ... */ });
+
+// 需要活动工程（绝大多数 Flow A/B/C 脚本）
+hqMainWithProject(async ({ client, projectId, projectContext: ctx }) => {
+  // ...
+  await waitForRegistered(client, ctx, newIds);   // 放置后等注册
+});
+```
+
+**不要**再写：
+
+```typescript
+const client = await connect({ instanceId: process.env.HQ_INSTANCE_ID });
+// ...
+main().catch((e) => { console.error(e); process.exit(1); });
+```
+
+## 环境变量
+
+| 变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `HQ_INSTANCE_ID` | — | 多开编辑器时指定实例；**未设时不要传 `undefined`**，否则绕过自动发现 |
+| `HQ_RPC_TIMEOUT_MS` | 30000 | 单个 RPC 超时 |
+| `HQ_HARD_TIMEOUT_MS` | 180000 | 整个脚本硬上限 |
+
+## 退出码
+
+| 码 | 含义 |
+| --- | --- |
+| `0` | 成功 |
+| `1` | 脚本抛错（stderr 有 `❌` 前缀） |
+| `124` | 硬看门狗触发 —— 说明有 RPC 卡死且 deadline 未生效，需排查而非调大超时 |
+
+看到 124 **不要**简单调大 `HQ_HARD_TIMEOUT_MS`：那只是把泄漏时间拉长。
+应该查是哪个 RPC 卡住，并把它加入 `docs/rpc-availability.md` 的禁建表。
+
+## 顺带修掉的两个坑（同一批改动）
+
+- `GetPageOccupancy` 在 **`client.patternLayout`** 上，不在 `canvasOps`；
+  响应字段是 **`items[].objectId`**，没有 `objectIds`。旧写法
+  `(occ.objectIds ?? [])` 恒为空 → 轮询第一次就"通过"。用 `waitForRegistered()`。
+- `GetSnapshotResponse` 的实体在 **`snapshot` 内层**：
+  `snap.snapshot.symbolInstances`，不是 `snap.symbolInstances`
+  （后者恒为 `undefined`，会静默打印 0）。

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

@@ -1,6 +1,6 @@
 {
   "$schema": "https://schema.huaqiu.com/skills/v1/skill.schema.json",
-  "id": "hqeda-scenario-b",
+  "id": "hqsch-scenario-b",
   "name": "HQ EDA Scenario B — Coding Agent + Local Scripts",
   "vendor": "Huaqiu Electronics",
   "version": "0.1.0",

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

@@ -1,15 +1,17 @@
 {
-  "name": "hqeda-scenario-b",
+  "name": "hqsch-scenario-b",
   "private": true,
   "type": "module",
   "scripts": {
-    "hello": "tsx scripts/hello.ts"
+    "hello": "tsx scripts/hello.ts",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@huaqiu/huaqiu-client": "^0.1.7",
     "@huaqiu/hqeda": "^0.2.7"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   }

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

@@ -2,20 +2,15 @@
  * 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";
+import { hqMainWithProject } from "./lib/hq.js";
 
 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() {
+hqMainWithProject(async ({ client, projectId, projectContext: ctx }) => {
   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 });
@@ -39,6 +34,4 @@ async function main() {
     .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

@@ -3,7 +3,7 @@
  *   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";
+import { hqMainWithProject } from "./lib/hq.js";
 
 const RENAMES: Array<[string, string, string]> = [
   // [oldRef, newRef, value]
@@ -13,13 +13,7 @@ const RENAMES: Array<[string, string, string]> = [
   ["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);
-
+hqMainWithProject(async ({ client, projectContext: ctx }) => {
   for (const [oldRef, newRef, value] of RENAMES) {
     const found = await client.canvasOps.findObjectByProperty({
       context: ctx, propKey: "Reference", propValue: oldRef,
@@ -47,6 +41,4 @@ async function main() {
     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

@@ -5,19 +5,16 @@
  *   npx tsx scripts/hello.ts
  *
  * Optional: HQ_INSTANCE_ID=<id> when multiple editors are open (run listEditors first).
+ *
+ * 进程一定会退出（含 RPC 超时与硬看门狗），见 scripts/lib/hq.ts。
  */
-import { connect, listEditors, toJsonString } from "@huaqiu/huaqiu-client";
-
-const INSTANCE = process.env.HQ_INSTANCE_ID;
+import { listEditors, toJsonString } from "@huaqiu/huaqiu-client";
+import { hqMain } from "./lib/hq.js";
 
-async function main() {
+hqMain(async (client) => {
   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();
@@ -29,18 +26,15 @@ async function main() {
   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;
+  // 注意：实体在 `snapshot` 内层（`GetSnapshotResponse.snapshot`），直接读
+  // `snap.symbolInstances` 恒为 undefined，会静默打印 0。
+  const snapshot = (await client.kernel.getSnapshot({ context: ctx })).snapshot;
+  const parts = snapshot?.symbolInstances?.length ?? 0;
+  const wires = snapshot?.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);
 });

package/skills/hqsch-scenario-b/template/scripts/lib/hq.ts

@@ -0,0 +1,346 @@
+/**
+ * scripts/lib/hq.ts —— Scenario B 所有脚本的统一运行时外壳（强制使用）
+ *
+ * ── 为什么必须有这一层（改动前请读完）────────────────────────────
+ * `connect()` 内部使用 `createGrpcTransport`，它在 HTTP/2 stream 打开期间会
+ * `ref()` Node 事件循环。若某个 RPC 迟迟不返回（docs/rpc-availability.md 记录了
+ * "历史上阻塞数分钟后才返回 clean unimplemented" 的情况），`await` 永不 settle、
+ * stream 不关闭，事件循环无法排空 —— node 进程变成"永生进程"。agent 每次重试
+ * （最多 3 次）都会再泄漏一个进程。
+ *
+ * 关键陷阱：**把 `client.close()` 写进 `finally` 救不了**。`await` 不 settle 时
+ * `finally` 根本不会执行。必须先让 `await` 一定会 settle，再谈清理。
+ *
+ * 因此本外壳同时做三件事：
+ *   1. 每个 RPC 注入 `AbortSignal` 超时 → `await` 一定会 settle；
+ *   2. 硬看门狗（hard watchdog）→ 无论发生什么，进程都能在 N 毫秒内终止；
+ *   3. `finally` 中 `client.close()`，并给 stdout 留出冲刷时间后退出。
+ *
+ * ── 用法 ───────────────────────────────────────────────────────
+ *   import { hqMain, hqMainWithProject } from "./lib/hq.js";
+ *
+ *   hqMain(async (client) => { ... });                 // 只需连接
+ *   hqMainWithProject(async ({ client, projectContext }) => { ... });  // 还需要活动工程
+ *
+ * 禁止再直接写 `connect(...)` + `main().catch(e => process.exit(1))`，
+ * 那正是进程泄漏的来源。
+ *
+ * 环境变量：
+ *   HQ_INSTANCE_ID        多开编辑器时指定实例
+ *   HQ_RPC_TIMEOUT_MS     单个 RPC 超时（默认 30000）
+ *   HQ_HARD_TIMEOUT_MS    整个脚本硬超时（默认 180000）
+ */
+
+import { connect, type EditorClient } from "@huaqiu/huaqiu-client";
+
+export type { EditorClient };
+
+/** 单个 RPC 的默认超时。超过即抛 DeadlineExceeded，而不是无限等待。 */
+export const DEFAULT_RPC_TIMEOUT_MS = 30_000;
+/** 整个脚本的硬上限。到点强制退出，杜绝进程堆积。 */
+export const DEFAULT_HARD_TIMEOUT_MS = 180_000;
+/** 退出前留给 stdout/stderr 冲刷的宽限期。 */
+const FLUSH_GRACE_MS = 3_000;
+
+export type ProjectContext = ReturnType<EditorClient["createProjectContext"]>;
+export type EditorContext = ReturnType<EditorClient["createEditorContext"]>;
+
+export interface HqOptions {
+  /** 多开 HQ EDA 时指定实例；未设则走自动发现。 */
+  instanceId?: string;
+  /** 直连指定 gRPC endpoint（测试 / 远程调试用）；未设则走本地注册表发现。 */
+  grpcEndpoint?: string;
+  /** 覆盖单 RPC 超时（毫秒）。 */
+  rpcTimeoutMs?: number;
+  /** 覆盖硬看门狗（毫秒）。 */
+  hardTimeoutMs?: number;
+}
+
+export interface HqProjectSession {
+  /** 已注入 RPC 超时代理的客户端（务必用这个，不要用裸 connect 的结果）。 */
+  client: EditorClient;
+  projectId: string;
+  projectContext: ProjectContext;
+  editorContext: EditorContext;
+}
+
+type AnyFn = (...args: any[]) => any;
+type CallOptions = { signal?: AbortSignal; timeoutMs?: number; [k: string]: unknown };
+
+function positiveIntEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+/**
+ * EditorClient 上属于 gRPC-CONNECT 服务的命名空间。
+ * 只有这些需要注入 deadline；`parts`（part-search，HTTP）与 `info`/`sessionId`
+ * 等普通字段不在此列。
+ */
+const RPC_NAMESPACES = new Set<string>([
+  "discovery",
+  "capability",
+  "context",
+  "project",
+  "kernel",
+  "graph",
+  "selection",
+  "canvasOps",
+  "componentPlace",
+  "objPlace",
+  "patternLayout",
+  "interactivePlace",
+  "erc",
+  "edaBom",
+  "netList",
+  "runtime",
+  "transaction",
+  "event",
+  "find",
+  "import",
+  "export",
+]);
+
+/**
+ * 给单个服务命名空间套一层代理：每次调用都自动补上 `signal`。
+ *
+ * 这样调用点无需改动——`client.kernel.getSnapshot({ context })` 依然写得出来，
+ * 但底层已经带上了超时。这一点很重要：agent 生成的脚本不可能记得给每个 RPC
+ * 手动传 options，必须由外壳兜住。
+ */
+function withDeadline<T extends object>(service: T, timeoutMs: number): T {
+  return new Proxy(service, {
+    get(target, prop) {
+      const value = (target as Record<string | symbol, unknown>)[prop];
+      if (typeof value !== "function") return value;
+
+      const fn = value as AnyFn;
+      return (request?: unknown, callOptions?: CallOptions) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+          controller.abort(new Error(`RPC 超时 ${timeoutMs}ms`));
+        }, timeoutMs);
+        const call = Promise.resolve(
+          fn.call(target, request, { signal: controller.signal, ...(callOptions ?? {}) }),
+        );
+        // 无论成功失败都清掉计时器，避免无谓地挂住事件循环。
+        return call.finally(() => clearTimeout(timer));
+      };
+    },
+  });
+}
+
+/** 客户端级代理：方法绑定回原对象，RPC 命名空间则换成带 deadline 的版本。 */
+function withDeadlineClient(client: EditorClient, timeoutMs: number): EditorClient {
+  return new Proxy(client, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop, target);
+      if (typeof prop === "string" && RPC_NAMESPACES.has(prop) && typeof value === "object" && value !== null) {
+        return withDeadline(value as object, timeoutMs);
+      }
+      return typeof value === "function" ? (value as AnyFn).bind(target) : value;
+    },
+  }) as EditorClient;
+}
+
+/**
+ * 退出：先设 exitCode 让 stdout/stderr 有机会冲刷干净；
+ * 若仍有句柄吊住事件循环，兜底强杀。绝不让进程"安静地永远活着"。
+ */
+function finish(code: number): void {
+  process.exitCode = code;
+  const grace = setTimeout(() => process.exit(code), FLUSH_GRACE_MS);
+  (grace as unknown as { unref?: () => void }).unref?.();
+}
+
+/** 连接 → 执行 → 关闭 → 退出。Scenario B 脚本的唯一入口。 */
+export async function hqMain(
+  fn: (client: EditorClient) => Promise<void>,
+  options: HqOptions = {},
+): Promise<void> {
+  const rpcTimeoutMs = options.rpcTimeoutMs ?? positiveIntEnv("HQ_RPC_TIMEOUT_MS", DEFAULT_RPC_TIMEOUT_MS);
+  const hardTimeoutMs = options.hardTimeoutMs ?? positiveIntEnv("HQ_HARD_TIMEOUT_MS", DEFAULT_HARD_TIMEOUT_MS);
+  const instanceId = options.instanceId ?? process.env.HQ_INSTANCE_ID;
+
+  // 硬看门狗：故意不 unref——即使 await 永不 settle、且没有任何 ref 住的句柄
+  // （那种情况下 Node 会静默退出、脚本像"成功"一样消失），也要让它变成一次
+  // 响亮的 exit 124。
+  const watchdog = setTimeout(() => {
+    console.error(
+      `\n⏱  硬看门狗触发（${hardTimeoutMs}ms）：强制终止进程。\n` +
+        `   常见原因：某个 RPC 未返回且 deadline 未生效。调大 HQ_HARD_TIMEOUT_MS 只能掩盖问题。`,
+    );
+    process.exit(124);
+  }, hardTimeoutMs);
+
+  let client: EditorClient | undefined;
+  let exitCode = 0;
+
+  try {
+    // 只在真的有值时传 instanceId——传 undefined 会绕过自动发现逻辑。
+    const connectOptions: { instanceId?: string; grpcEndpoint?: string } = {};
+    if (options.grpcEndpoint) connectOptions.grpcEndpoint = options.grpcEndpoint;
+    else if (instanceId) connectOptions.instanceId = instanceId;
+    client = await connect(connectOptions);
+    await fn(withDeadlineClient(client, rpcTimeoutMs));
+  } catch (e) {
+    exitCode = 1;
+    console.error("❌", e instanceof Error ? e.message : e);
+  } finally {
+    clearTimeout(watchdog);
+    try {
+      client?.close();
+    } catch {
+      // 关闭失败无所谓，连接已经要没了
+    }
+  }
+
+  finish(exitCode);
+}
+
+/** `hqMain` + 取活动工程并建好 ProjectContext。Flow A/B/C 绝大多数脚本用这个。 */
+export async function hqMainWithProject(
+  fn: (session: HqProjectSession) => Promise<void>,
+  options: HqOptions = {},
+): Promise<void> {
+  return hqMain(async (client) => {
+    const editorContext = client.createEditorContext();
+    const active = await client.project.getActiveProject({ context: editorContext });
+    const projectId = active.project?.projectId;
+    if (!projectId) throw new Error("请先在 HQ EDA 中打开原理图工程");
+    await fn({
+      client,
+      projectId,
+      projectContext: client.createProjectContext(projectId),
+      editorContext,
+    });
+  }, options);
+}
+
+/**
+ * 自然序比较，用于引脚号排序。
+ *
+ * 禁止用 `Number(a) - Number(b)`：位号引脚常是 "A5"/"CC1" 这类字母前缀，
+ * `Number("A5")` 得到 NaN，排序直接失去意义。
+ */
+export function naturalCompare(a: string, b: string): number {
+  const re = /(\d+)|(\D+)/g;
+  const pa = String(a).match(re) ?? [];
+  const pb = String(b).match(re) ?? [];
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i];
+    const y = pb[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const nx = /^\d/.test(x);
+    const ny = /^\d/.test(y);
+    if (nx && ny) {
+      const d = Number(x) - Number(y);
+      if (d !== 0) return d;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/**
+ * 把引脚号解析为 RPC 需要的数字。
+ *
+ * `pinNum1` 只接受数字，而原理图上引脚号可能是 "A5"/"CC1"。硬规则：不要对
+ * 非纯数字引脚做 `Number()` —— 那会静默产生 NaN 并连错脚。这里显式抛错，
+ * 让调用方改用 pinName 路径。
+ */
+export function pinNumber(pin: string | undefined, label = "PIN"): number {
+  const s = String(pin ?? "").trim();
+  if (!/^\d+$/.test(s)) {
+    throw new Error(
+      `${label}="${s}" 不是纯数字引脚号，无法用于 pinNum（autoConnect）。` +
+        `字母前缀引脚请改用 pinName 路径，或先在快照中确认引脚编号。`,
+    );
+  }
+  return Number(s);
+}
+
+/** 轮询用 sleep。 */
+export const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/* ────────────────────────────────────────────────────────────────
+ * 对象注册等待（放置后的关键步骤）
+ * ────────────────────────────────────────────────────────────────
+ * 两个易错点，都已在旧版脚本/文档中出现过：
+ *   1. `GetPageOccupancy` 属于 **PatternLayoutService**（`client.patternLayout`），
+ *      不在 `canvasOps` 上。
+ *   2. 响应字段是 **`items: PageOccupancyItem[]`**（每项 `objectId`/`objType`/
+ *      `designator`/`bbox`），**没有** `objectIds` 这个字段。
+ *      读 `occ.objectIds ?? []` 恒为空 → 轮询第一次就"通过"，随后 apply
+ *      报 `OBJECT_NOT_FOUND` 或假 `PARTIAL`。
+ * ──────────────────────────────────────────────────────────────── */
+
+async function occupancyIds(client: EditorClient, ctx: ProjectContext): Promise<Set<string>> {
+  const occ = await client.patternLayout.getPageOccupancy({ context: ctx });
+  const items = (occ as unknown as { items?: Array<{ objectId?: bigint | string }> }).items ?? [];
+  return new Set(items.map((it) => String(it.objectId)));
+}
+
+export interface PollOptions {
+  /** 最长等待时间，默认 15000ms。超时抛错，不静默放过。 */
+  timeoutMs?: number;
+  /** 轮询间隔，默认 300ms。 */
+  intervalMs?: number;
+  /** 日志前缀。 */
+  label?: string;
+}
+
+/** 等到所有 objectId 都出现在页面上（放置后立即调用，再 apply pattern）。 */
+export async function waitForRegistered(
+  client: EditorClient,
+  ctx: ProjectContext,
+  objectIds: Array<string | bigint>,
+  options: PollOptions = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const intervalMs = options.intervalMs ?? 300;
+  const wanted = objectIds.map(String);
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const present = await occupancyIds(client, ctx);
+    const missing = wanted.filter((id) => !present.has(id));
+    if (missing.length === 0) return;
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `${options.label ?? "waitForRegistered"}: ${timeoutMs}ms 内未注册完成，仍缺 ${missing.length} 个对象 ` +
+          `(${missing.slice(0, 5).join(", ")}). 继续 apply 会得到 OBJECT_NOT_FOUND 或假 PARTIAL。`,
+      );
+    }
+    await sleep(intervalMs);
+  }
+}
+
+/** 等到指定 objectId 全部从页面上消失（删除后调用）。 */
+export async function waitForRemoved(
+  client: EditorClient,
+  ctx: ProjectContext,
+  objectIds: Array<string | bigint>,
+  options: PollOptions = {},
+): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const intervalMs = options.intervalMs ?? 300;
+  const wanted = new Set(objectIds.map(String));
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const present = await occupancyIds(client, ctx);
+    const still = [...wanted].filter((id) => present.has(id));
+    if (still.length === 0) return;
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `${options.label ?? "waitForRemoved"}: ${timeoutMs}ms 后对象仍存在 (${still.slice(0, 5).join(", ")})`,
+      );
+    }
+    await sleep(intervalMs);
+  }
+}

package/skills/hqsch-scenario-b/template/scripts/read-circuit.ts

@@ -7,9 +7,8 @@
  *   NET=+3.3V npx tsx scripts/read-circuit.ts
  *   REF=VR201 TRACE=1 npx tsx scripts/read-circuit.ts
  */
-import { connect } from "@huaqiu/huaqiu-client";
+import { hqMainWithProject, naturalCompare, type EditorClient, type ProjectContext } from "./lib/hq.js";
 
-const INSTANCE = process.env.HQ_INSTANCE_ID;
 const REF = process.env.REF;
 const NET = process.env.NET;
 const TRACE = process.env.TRACE === "1" || process.env.TRACE === "true";
@@ -135,7 +134,8 @@ class SnapCtx {
         net: this.netOf.get(pinMetaId(p)) ?? "(未连接)",
         pos: p.position,
       }))
-      .sort((a, b) => Number(a.num) - Number(b.num));
+      // 引脚号可能是 "A5"/"CC1" —— 禁止 Number() 强转，用自然序比较。
+      .sort((a, b) => naturalCompare(a.num, b.num));
   }
   netMembers(netName: string, excludeRef?: string): Array<{ ref: string; pinLabel: string }> {
     const net = this.netByName.get(netName);
@@ -271,12 +271,7 @@ function printRoleSummary(ref: string, sym: Sym, rows: PinRow[], props: Array<{
   console.log(`    总结: 结合邻域${TRACE ? "/穿透" : ""}块描述 ${ref} 在局部子电路中的功能`);
 }
 
-async function resolveCanvasIds(
-  client: Awaited<ReturnType<typeof connect>>,
-  ctx: ReturnType<Awaited<ReturnType<typeof connect>>["createProjectContext"]>,
-  ref: string,
-  sym: Sym,
-): Promise<void> {
+async function resolveCanvasIds(client: EditorClient, ctx: ProjectContext, ref: string, sym: Sym): Promise<void> {
   console.log(`\n  ── canvas 编辑 id（读懂 → 改电路桥接）──`);
   console.log(`    snapshot metadata.id:  ${symMetaId(sym)}`);
   console.log(`    canvasObjectId:       ${sym.canvasObjectId ?? "(空)"}`);
@@ -288,12 +283,7 @@ async function resolveCanvasIds(
   }
 }
 
-async function main() {
-  const client = INSTANCE ? await connect({ instanceId: INSTANCE }) : await connect();
-  const active = await client.project.getActiveProject({ context: client.createEditorContext() });
-  const projectId = active.project?.projectId;
-  if (!projectId) throw new Error("请先打开原理图工程");
-  const pctx = client.createProjectContext(projectId);
+hqMainWithProject(async ({ client, projectId, projectContext: pctx }) => {
   console.log(`工程 projectId: ${projectId}\n`);
 
   const t = Date.now();
@@ -352,6 +342,4 @@ async function main() {
     for (const b of bridgesFromNet(buildSeriesBridgeGraph(ctx), NET))
       console.log(`    串联: ${b.ref} → 对侧 ${otherNet(b, NET)}`);
   }
-}
-
-main().catch((e) => { console.error("❌", e.message); process.exit(1); });
+});

package/skills/hqsch-scenario-b/template/scripts/replace-part-by-ref.ts

@@ -3,24 +3,19 @@
  * OLD_REF=U3 CONFIRM=1 npx tsx scripts/replace-part-by-ref.ts
  *
  * 完整替换需：searchParts → placeKicadSymbol → 按 OLD 的 pin→net 逐脚 autoConnect
+ * ⚠ 本脚本只做"定位 + 删除"，不放置新器件、不重连引脚。
  */
-import { connect } from "@huaqiu/huaqiu-client";
+import { hqMainWithProject, waitForRemoved } from "./lib/hq.js";
 
 const OLD_REF = process.env.OLD_REF;
 const CONFIRM = process.env.CONFIRM === "1";
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
-async function main() {
+hqMainWithProject(async ({ client, projectId, projectContext: ctx }) => {
   if (!OLD_REF) throw new Error("需要 OLD_REF=");
-  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 snap = await client.kernel.getSnapshot({ context: ctx });
-  const s = snap.snapshot as Record<string, unknown[]>;
+  const s = snap.snapshot as unknown as Record<string, unknown[]>;
   const sym = (s.symbolInstances as Array<Record<string, unknown>>)?.find((x) => x.designator === OLD_REF);
   if (!sym) throw new Error(`快照无 ${OLD_REF}`);
 
@@ -32,13 +27,7 @@ async function main() {
   const id = found.objectIds?.[0];
   if (!id) throw new Error("FindObject 失败");
   await client.canvasOps.deleteObjectsByIds({ context: ctx, objectIds: [id] });
-  for (let i = 0; i < 10; i++) {
-    await sleep(300);
-    const occ = await client.canvasOps.getPageOccupancy({ context: ctx });
-    const ids = (occ.objectIds ?? []).map(String);
-    if (!ids.includes(String(id))) break;
-  }
+  // 删除后等对象真正消失（GetPageOccupancy 在 patternLayout 上，字段是 items[].objectId）
+  await waitForRemoved(client, ctx, [id], { label: `删除 ${OLD_REF}` });
   console.log(`✓ 已删除 ${OLD_REF} — 请 placeKicadSymbol 并 autoConnect 各 pin`);
-}
-
-main().catch((e) => { console.error("❌", e.message); process.exit(1); });
+});

package/skills/hqsch-scenario-b/template/scripts/rewire-pin-by-ref.ts

@@ -1,8 +1,11 @@
 /**
  * Flow C 配方：把 REF 的某 pin 接到 TARGET_REF 的 TARGET_PIN（autoConnect）
  * REF=R201 PIN=1 TARGET_REF=U301 TARGET_PIN=14 CONFIRM=1 npx tsx scripts/rewire-pin-by-ref.ts
+ *
+ * 注意：`pinNum` 只接受纯数字。字母前缀引脚（A5/CC1…）请改用 pinName 路径，
+ * 本脚本会显式报错而不是静默传 NaN。
  */
-import { connect } from "@huaqiu/huaqiu-client";
+import { hqMainWithProject, pinNumber } from "./lib/hq.js";
 
 const REF = process.env.REF;
 const PIN = process.env.PIN;
@@ -10,13 +13,8 @@ const TARGET_REF = process.env.TARGET_REF;
 const TARGET_PIN = process.env.TARGET_PIN ?? "1";
 const CONFIRM = process.env.CONFIRM === "1";
 
-async function main() {
+hqMainWithProject(async ({ client, projectId, projectContext: ctx }) => {
   if (!REF || !PIN || !TARGET_REF) throw new Error("需要 REF= PIN= TARGET_REF=");
-  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 a = await client.canvasOps.findObjectByProperty({ context: ctx, propKey: "Reference", propValue: REF });
@@ -32,11 +30,9 @@ async function main() {
   await client.canvasOps.autoConnectObjectsById({
     context: ctx,
     objectId1: id1,
-    pinNum1: [Number(PIN)],
+    pinNum1: [pinNumber(PIN, "PIN")],
     objectId2: id2,
-    pinNum2: [Number(TARGET_PIN)],
+    pinNum2: [pinNumber(TARGET_PIN, "TARGET_PIN")],
   });
   console.log("✓ autoConnect 完成 — 请 GetSnapshot 验收 pin→net");
-}
-
-main().catch((e) => { console.error("❌", e.message); process.exit(1); });
+});