@huaqiu/dsh-hqsch 0.4.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳华秋智联股份有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @huaqiu/dsh-hqsch
+
+HQSCH scenario-b agent skill for DeepSeek Harness, shipped as one DSH plugin.
+Installing the Huaqiu DSH PCB/EDA bundle makes the `hqsch-scenario-b` skill
+available without a separate skill installation step.
+
+## What You Get
+
+```
+@huaqiu/dsh-hqsch
+└── Skills    hqsch-scenario-b - SKILL.md + SYSTEM-PROMPT.md + docs/ + template/
+```
+
+This package intentionally registers no DSH tools. The bundled skill teaches the
+agent to generate TypeScript scripts from `template/` and execute them locally
+against HQ EDA.
+
+## How The Plugin Is Wired
+
+```yaml
+- insert:
+    - id: huaqiu-dsh-hqsch
+      name: '@huaqiu/dsh-hqsch'
+      inject: ['skills']
+```
+
+`skills` is the DSH runtime's plugin-bundled skill registry. `apply()` registers
+the `hqsch-scenario-b` skill and returns a disposer.
+
+The skill is resolved relative to the loaded module:
+
+```
+<package>/lib/index.mjs  ->  <package>/skills/hqsch-scenario-b
+```
+
+That is why `files[]` contains `skills`; otherwise npm would strip the bundled
+skill from the published artifact.
+
+## Runtime Requirements
+
+The skill's own instructions apply: HQ EDA desktop must be running with a
+schematic project open, and the agent runs generated TypeScript scripts from the
+bundled `template/` directory.

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# DSH bundle patch: inserts the Huaqiu HQSCH scenario-b bundled skill plugin.
+#
+# This package registers the `hqsch-scenario-b` skill at load time via
+# `ctx.skills.register()`. It intentionally registers no tools: scenario-b
+# teaches the agent to generate and execute local TypeScript scripts against
+# HQ EDA.
+#
+# The entry `inject` MUST match the node-half module contract (`src/index.ts`
+# `export const inject`): `skills`.
+- insert:
+    - id: huaqiu-dsh-hqsch
+      name: '@huaqiu/dsh-hqsch'
+      inject: ['skills']

package/lib/index.d.mts

@@ -0,0 +1,98 @@
+import { Context } from "@deepseek-ai/cordis";
+//#region src/config.d.ts
+/**
+ * Configuration for `@huaqiu/dsh-hqsch`.
+ *
+ * This plugin only bundles and registers the HQSCH scenario-b skill. The skill
+ * itself guides the agent to generate and run local TypeScript scripts against
+ * HQ EDA, so there is no host connection configured here.
+ *
+ * @module
+ */
+/** Canonical skill directory name shipped by this package. */
+declare const HQSCH_SKILL_NAME = "hqsch-scenario-b";
+/** Configuration accepted by the plugin's `apply()`. */
+interface HqschConfig {
+  /** Bundled skill directory override (defaults to this package's skills/). */
+  skillsDir?: string;
+}
+type HqschConfigInput = Partial<HqschConfig>;
+//#endregion
+//#region src/paths.d.ts
+/**
+ * Absolute path of the bundled HQSCH scenario-b skill directory.
+ *
+ * Resolution order: explicit override, `DSH_HQSCH_SKILLS_DIR`, then the
+ * package-relative location.
+ */
+declare function resolveSkillDir(moduleUrl: string, override?: string): string;
+/**
+ * Resolve the skill directory and assert the skill is actually present.
+ *
+ * @throws when `SKILL.md` is missing.
+ */
+declare function requireSkillDir(moduleUrl: string, override?: string): string;
+//#endregion
+//#region src/index.d.ts
+/** Plugin id - matches package.json. */
+declare const name = "@huaqiu/dsh-hqsch";
+/**
+ * `skills` is REQUIRED: it is the DSH runtime's plugin-bundled skill registry.
+ */
+declare const inject: readonly ["skills"];
+/** The `skills` service shape consumed by this plugin. */
+interface SkillRegistration {
+  /** Skill id - must match DSH's discoverable skill id format. */
+  name: string;
+  /** Catalog description shown to the model. */
+  description: string;
+  /** Full SKILL.md body. */
+  content: string;
+  /** Discovery source for plugin-bundled skills. */
+  source: 'runtime';
+  /** Where docs/ and template/ live for progressive disclosure. */
+  resourceBase: {
+    kind: 'directory';
+    path: string;
+  };
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** DSH skill registry, provided by the runtime skill service. */
+    skills: {
+      /** Register a plugin-bundled skill; returns its unregister disposer. */
+      register(skill: SkillRegistration): () => void;
+    };
+  }
+}
+/**
+ * Extract the `description` field from SKILL.md YAML frontmatter.
+ *
+ * Supports both single-line values and the folded block form used by
+ * hqeda-scenario-b (`description: >-` followed by indented lines).
+ */
+declare function skillDescription(markdown: string): string | undefined;
+/** Read the bundled HQSCH scenario-b SKILL.md. */
+declare function readBundledSkill(moduleUrl: string, override?: string): {
+  dir: string;
+  name: string;
+  description: string;
+  content: string;
+};
+/**
+ * Read the bundled skill, or `null` when the installed package does not carry
+ * one. A missing skill is a packaging failure, but it should degrade this
+ * plugin instead of killing the whole DSH process.
+ */
+declare function tryReadBundledSkill(moduleUrl: string, override?: string): {
+  dir: string;
+  name: string;
+  description: string;
+  content: string;
+} | null;
+/**
+ * Host plugin body - register the bundled HQSCH scenario-b skill.
+ */
+declare function apply(ctx: Context, config?: HqschConfigInput): () => void;
+//#endregion
+export { HQSCH_SKILL_NAME, type HqschConfig, type HqschConfigInput, SkillRegistration, apply, inject, name, readBundledSkill, requireSkillDir, resolveSkillDir, skillDescription, tryReadBundledSkill };

package/lib/index.mjs

@@ -0,0 +1,159 @@
+import { getLogger } from "@huaqiu/dsh-plugin-log";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/config.ts
+/**
+* Configuration for `@huaqiu/dsh-hqsch`.
+*
+* This plugin only bundles and registers the HQSCH scenario-b skill. The skill
+* itself guides the agent to generate and run local TypeScript scripts against
+* HQ EDA, so there is no host connection configured here.
+*
+* @module
+*/
+/** Canonical skill directory name shipped by this package. */
+const HQSCH_SKILL_NAME = "hqsch-scenario-b";
+/** Whether any host configuration was supplied (used for startup logging). */
+function hasHostConfig(input = {}) {
+	return Boolean(input.skillsDir ?? process.env["DSH_HQSCH_SKILLS_DIR"]);
+}
+//#endregion
+//#region src/paths.ts
+/**
+* Resolution of the bundled HQSCH scenario-b skill directory at runtime.
+*
+* The skill ships inside the installed package
+* (`<pkg>/skills/hqsch-scenario-b/`), not beside a separate checkout. Resolving
+* relative to the loaded module works for source tests, built artifacts and npm
+* installs.
+*
+* @module
+*/
+/**
+* Absolute path of the bundled HQSCH scenario-b skill directory.
+*
+* Resolution order: explicit override, `DSH_HQSCH_SKILLS_DIR`, then the
+* package-relative location.
+*/
+function resolveSkillDir(moduleUrl, override) {
+	if (override && override.trim().length > 0) return resolve(override);
+	const envOverride = process.env["DSH_HQSCH_SKILLS_DIR"];
+	if (envOverride && envOverride.trim().length > 0) return resolve(envOverride);
+	const here = dirname(fileURLToPath(moduleUrl));
+	return resolve(here, "..", "skills", HQSCH_SKILL_NAME);
+}
+/**
+* Resolve the skill directory and assert the skill is actually present.
+*
+* @throws when `SKILL.md` is missing.
+*/
+function requireSkillDir(moduleUrl, override) {
+	const dir = resolveSkillDir(moduleUrl, override);
+	const skillFile = join(dir, "SKILL.md");
+	if (!existsSync(skillFile)) throw new Error(`@huaqiu/dsh-hqsch: bundled skill missing at ${skillFile}. The installed package is incomplete; reinstall @huaqiu/dsh-hqsch so that its skills/ directory is present.`);
+	return dir;
+}
+//#endregion
+//#region src/index.ts
+/** Plugin id - matches package.json. */
+const name = "@huaqiu/dsh-hqsch";
+/**
+* `skills` is REQUIRED: it is the DSH runtime's plugin-bundled skill registry.
+*/
+const inject = ["skills"];
+const log = getLogger("dsh-hqsch");
+log.info("dsh-hqsch: module loaded (waiting for the skills service)");
+const FALLBACK_SKILL_DESCRIPTION = "HQSCH scenario-b automation skill for HQ EDA schematic drawing, reading and local surgical edits through generated TypeScript scripts.";
+/**
+* Extract the `description` field from SKILL.md YAML frontmatter.
+*
+* Supports both single-line values and the folded block form used by
+* hqeda-scenario-b (`description: >-` followed by indented lines).
+*/
+function skillDescription(markdown) {
+	const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
+	if (!frontmatter?.[1]) return void 0;
+	const lines = frontmatter[1].split(/\r?\n/);
+	const lineIndex = lines.findIndex((candidate) => /^\s*description\s*:/.test(candidate));
+	if (lineIndex < 0) return void 0;
+	const raw = lines[lineIndex].slice(lines[lineIndex].indexOf(":") + 1).trim();
+	if (raw === ">-" || raw === ">" || raw === "|-" || raw === "|") {
+		const block = [];
+		for (const line of lines.slice(lineIndex + 1)) {
+			if (/^\s+\S/.test(line)) {
+				block.push(line.trim());
+				continue;
+			}
+			if (line.trim().length === 0) continue;
+			break;
+		}
+		const text = block.join(" ").trim();
+		return text.length > 0 ? text : void 0;
+	}
+	const unquoted = raw.replace(/^["']/, "").replace(/["']$/, "");
+	return unquoted.length > 0 ? unquoted : void 0;
+}
+/** Read the bundled HQSCH scenario-b SKILL.md. */
+function readBundledSkill(moduleUrl, override) {
+	const dir = requireSkillDir(moduleUrl, override);
+	const content = readFileSync(join(dir, "SKILL.md"), "utf8");
+	return {
+		dir,
+		name: HQSCH_SKILL_NAME,
+		description: skillDescription(content) ?? FALLBACK_SKILL_DESCRIPTION,
+		content
+	};
+}
+/**
+* Read the bundled skill, or `null` when the installed package does not carry
+* one. A missing skill is a packaging failure, but it should degrade this
+* plugin instead of killing the whole DSH process.
+*/
+function tryReadBundledSkill(moduleUrl, override) {
+	try {
+		return readBundledSkill(moduleUrl, override);
+	} catch (err) {
+		log.error("dsh-hqsch: bundled skill unavailable - continuing degraded without skill registration", {
+			expectedDir: resolveSkillDir(moduleUrl, override),
+			error: String(err?.message ?? err)
+		});
+		return null;
+	}
+}
+/**
+* Host plugin body - register the bundled HQSCH scenario-b skill.
+*/
+function apply(ctx, config = {}) {
+	if (!ctx.skills || typeof ctx.skills.register !== "function") throw new Error("@huaqiu/dsh-hqsch requires the DSH `skills` service (ctx.skills.register).");
+	const skill = tryReadBundledSkill(import.meta.url, config.skillsDir);
+	log.info("applying dsh-hqsch node half", {
+		hasConfigHost: hasHostConfig(config),
+		skillDir: skill?.dir ?? resolveSkillDir(import.meta.url, config.skillsDir),
+		skillPresent: skill !== null
+	});
+	const disposers = [];
+	if (skill) disposers.push(ctx.skills.register({
+		name: skill.name,
+		description: skill.description,
+		content: skill.content,
+		source: "runtime",
+		resourceBase: {
+			kind: "directory",
+			path: skill.dir
+		}
+	}));
+	log.info("dsh-hqsch node half ready", {
+		skill: skill?.name ?? null,
+		degraded: skill === null
+	});
+	return () => {
+		for (const dispose of disposers.reverse()) try {
+			dispose();
+		} catch (err) {
+			log.warn("dsh-hqsch disposer failed", { error: String(err?.message ?? err) });
+		}
+	};
+}
+//#endregion
+export { HQSCH_SKILL_NAME, apply, inject, name, readBundledSkill, requireSkillDir, resolveSkillDir, skillDescription, tryReadBundledSkill };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@huaqiu/dsh-hqsch",
+  "version": "0.4.8",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "@huaqiu/dsh-plugin-log": "0.4.8"
+  },
+  "files": [
+    "lib",
+    "src",
+    "skills",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

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

@@ -0,0 +1,209 @@
+# HQ EDA 原理图自动化 — System Prompt / 项目指令
+
+> **默认语言：中文。** 安装说明见 [INSTALL.md](./INSTALL.md)。
+>
+> | 平台 | 用法 |
+> | --- | --- |
+> | **Codex CLI** | 复制到项目根 `AGENTS.md`，或 `.codex/instructions.md` |
+> | **Work Buddy** | 粘贴到平台 System Prompt UI，或合并进项目 `AGENTS.md` |
+> | **Claude Project** | Custom Instructions 粘贴全文；Project Knowledge 上传 `docs/` |
+
+---
+
+你是 HQ EDA 原理图自动化助手。你**不直接连接**编辑器；你在用户工作区内生成 TypeScript 脚本，并**在终端自动执行** `npx tsx scripts/xxx.ts`，读取 stdout/stderr 并根据结果修正脚本。
+
+## 必读文档（按顺序，路径相对本 skill 包根目录）
+
+1. `docs/placement-conventions.md` — 坐标、布局、**routing mode gate**（短→autoConnect，长→stub+alias）
+2. `docs/circuit-pattern-layout.md` — 优先用 pattern（pull_resistor、reset_circuit、decoupling_cap）
+3. `docs/part-search.md` — searchParts → getEdaModels → PlaceKicadSymbol
+4. `docs/quickstart.md` — connect、createProjectContext
+5. `docs/property-conventions.md` — 位号、引脚坐标
+6. `docs/reading-a-circuit.md` — 读电路 / GetSnapshot 三表联结 / 邻域 / 串联穿透
+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 的精确字段名时查阅
+
+## 硬性规则
+
+- 器件（R/C/Q/U）：在线搜索 + `client.componentPlace.placeKicadSymbol`；**禁止**手写 `json_part` / `PlacePart`
+- 电源符号：`ListSymbolLibraries` → `PlaceSymbolFromLibrary`
+  - `kind`：电源/地用 **`LibrarySymbolKind.GLOBAL`（=1）**；`OFF_PAGE=2`，`PORT=3`
+  - **`symbolName`** = 库里的**图形符号名**（模糊匹配库符号）
+  - **`netName`** = 写入实例 **"Name"** 用户属性的网络名；传空则 Name 沿用 `symbolName` —— **勿把图形名和网络名混为一谈**
+  - `autoConnect` 时电源符号引脚用 pin **0**
+- **先 pattern 后 hand-wire**；`connections[].routed=true` 的 net 不要重连
+- **每条 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`
+- **读取导线段字段是 `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**（抖动正常）。勿用超时反推「未实现」
+
+## Agent 执行流程（必须遵守）
+
+**先判任务类型**：
+- **画电路** → 按「流程 A」执行；不可跳过 pattern 规划直接写放置/接线代码。
+- **读电路 / 理解已有设计**（如"VR201 有什么作用"、"这个网络为什么叫 +3.3V"）→ 按「流程 B」，**只读不改**。
+- **改部分电路**（如"把 C201 改成 1µF"、"把 R5 改接到 +3.3V"、"换掉 U3"）→ 按「流程 C」，**外科手术式**；禁止清页重画。
+
+### 流程 A — 画电路
+
+1. **连通性检查**（首次任务前）：在 `template/` 执行 `npm install`（若未安装），然后 `npx tsx scripts/hello.ts`；失败则停止并提示用户打开 HQ EDA 与原理图工程。
+
+2. **Pattern 规划**（生成脚本前，必做）：
+   - 先调 `client.patternLayout.listCircuitPatterns({ context: ctx })` 刷新目录（RPC 是权威来源）。
+   - 读 `docs/circuit-pattern-layout.md`，对照用户需求列出适用的 pattern。
+   - 在脚本设计说明里**先写**将用哪些 pattern、host 器件、各 pattern 的 roles / anchor。
+   - 若无适用 pattern，在设计说明中**显式声明**「本任务无 pattern，原因：…」，再进入 hand-wire。
+
+   **Pattern 触发词表**（需求中出现 → 先想 pattern，不许直接手画）：
+
+   | 需求特征 | pattern | apply 次数 |
+   | --- | --- | --- |
+   | LDO / 稳压 / 输入输出滤波 / 去耦 / 旁路电容 | `decoupling_cap` | 每个电源引脚一次 |
+   | 上拉 / 下拉电阻 | `pull_resistor` | 同极性同 rail 合并一次 |
+   | 复位电路 / reset 按键 | `reset_circuit` | 一次 |
+   | I2C + 上拉 | `i2c_bus` | 一次 |
+   | SPI 主从 | `spi_bus` | 一次（route_mode=NONE） |
+   | 晶振 + 负载电容 | `crystal` | 一次 |
+
+3. **生成脚本**（脚本内电路步骤顺序固定）：
+   ```
+   connect → getActiveProject → createProjectContext
+   → 放置 host / 独立器件（part-search → placeKicadSymbol；电源符号 → PlaceSymbolFromLibrary）
+   → 【等待注册】轮询 getPageOccupancy 直到所有新 id 出现（关键！否则 apply 失败）
+   → 规范位号 / 容值（覆盖引擎自动分配的 C1..C4）
+   → applyCircuitPattern（每个适用 pattern 一次；先 planOnly 可选，再正式 apply）
+   → 仅对 pattern 未覆盖的 net 做 hand-wire（每条 net 先跑 routing gate）
+   → zoomAll + 验收输出（netlist + listWireSegments().wires）
+   ```
+   写入 `template/scripts/<名称>.ts`（或用户指定的 scripts 目录）。
+   **禁止**跳过 `applyCircuitPattern` 直接 `autoConnect` 全图；**禁止**重连 `connections[].routed=true` 的 net。
+
+4. **自动执行**：立即在脚本所在目录运行 `npx tsx scripts/<名称>.ts`，读取 stdout/stderr。
+
+5. **失败重试**：若脚本报错，根据 stderr 修正后重试，**最多 3 次**。
+
+6. **验收**（脚本成功后必做）：
+   - 检查每个 pattern 的 `status` / `connections`（是否 `routed=true`）。
+   - 用 `netList.getActivePageNetList` 核对关键 net（**注意访问器是 `netList`，大写 L**）。
+   - 用 `canvasOps.listWireSegments` 统计导线段 —— **字段是 `wires`**，`wireSegments` 会恒为 undefined。
+   - 调用 `client.canvasOps.zoomAll({ context: ctx })` 便于用户目视检查。
+   - ERC 在部分构建中未实现（`RunChecks not implemented`），不要把它当验收依赖。
+
+### 流程 B — 读电路 / 理解已有设计
+
+**只读**：不放置、不删除、不改属性。详见 `docs/reading-a-circuit.md`。
+
+1. `client.project.getActiveProject` → **打印 projectId**；不要跨任务缓存（用户可能切换工程，编辑器也可能重启）。
+2. `client.kernel.getSnapshot({ context: ctx })` —— **一次调用覆盖全工程**（实测 160 器件 / 602 导线 / 181 网络，约 1.6s）。这是理解电路的主数据源。
+3. 建三张表还原拓扑（**已验证的配方**）：
+   - `designator → symbolInstance`（取 `metadata.id`）
+   - `symbolDefinition.pins` → **引脚号→引脚名**（用实例的 `definitionId` 精确匹配 `symbolDefinitions[].name`）
+   - `nets[].pinInstanceIds` → **引脚实例→网络名**
+4. 器件语义**优先读 `symbolInstance.metadata.properties`** —— 自带 `Description`、`Datasheet`、`output_voltage`、`input_voltage`、`topology`、`supply_current`、`PSRR` 等电气参数，**无需联网查 datasheet**。
+5. 需要器件清单语义（MPN/description/footprint）时用 `netList.getProjectNetList`；纯网络查询也可用它（约 27ms，比快照快）。
+6. 回答时**必须指出电气一致性疑点**：把器件参数与网络名对照（如 `output_voltage=5V` 却驱动 `+3.3V` 网络），这是用户最需要知道的。
+
+**流程 B 硬性规则**：
+- **不要**依赖 `graph.GetConnectivity`、`kernel.GetEntity`、`erc.RunChecks`、`selection.*`、`export.*`、`runtime.*`、`transaction.*` —— 本引擎构建**均未实现**；完整禁建表见 `docs/rpc-availability.md`。scenario-b **不**等待引擎补齐这些接口再建流程。
+- `project.ListProjectTree` 返回空（`error:3`）；`find.FindNet` 常**恒返回 `success:false`（静默）** —— **禁止**据此判断网络不存在，改用快照 `nets`。
+- `position.x/y` 是 **bigint**：`JSON.stringify` 会抛 "Do not know how to serialize a BigInt"，用 `docs/serialization.md` 的 replacer。
+- 快照**含未连接引脚**（netList 不含）—— 判断悬空/未接引脚时以快照为准。
+- 读电路默认**不要** `zoomAll`（避免改视口）；用户需要看图时可再调。
+- 回答「器件作用」按模板：身份 → 引脚→网络 → **邻域（同网邻居）** → （可选）**串联穿透** `TRACE=1` → 一致性疑点 → 作用总结。详见 `docs/reading-a-circuit.md`。
+- 串联穿透 C/R/L/磁珠：**不需新 RPC**；`read-circuit.ts` 客户端 BFS；去耦电容（一脚 GND/VCC）不穿透。
+- 读懂后要改：输出块 **canvas 编辑 id**（`canvasObjectId` / `FindObject`）供流程 C 使用。
+
+### 流程 C — 局部改电路
+
+**可写**，但必须 **先 diff、后执行**。详见 `docs/editing-a-circuit.md`。
+
+1. `getActiveProject` → 打印 `projectId`。
+2. `GetSnapshot` + `read-circuit.ts`（`REF=`）定位目标与邻域；记录 `objectId`。
+3. **修改集**：只列将改的对象/网络；禁止顺手清页。
+4. **向用户复述 diff**，待确认后再写（脚本可用 `CONFIRM=1` 跳过交互）。
+5. **最小 RPC 执行**：
+   - 改属性 → `FindObjectByProperty` + `SetObjectProperty`（位号用 `Part Reference`）
+   - 改接脚 → `autoConnectObjectsById` 或 `placePinStubWireAndNetAlias`（routing gate）
+   - 换器件 → 快照坐标 → `deleteObjectsByIds` → `placeKicadSymbol` → 按 pin 重连
+6. **双源验收**：再 `GetSnapshot`（pin→net）+ `netList` + 一致性复查。
+
+**流程 C 硬性规则**：
+- **禁止**把局部修改做成流程 A 整页重画。
+- **禁止**未确认大批量 `deleteObjectsByIds`。
+- 模板脚本：`edit-property-by-ref.ts`、`rewire-pin-by-ref.ts`、`replace-part-by-ref.ts`。
+- 仍**禁止**依赖 `GetConnectivity` / `selection.*` / `transaction.*`；见 `docs/rpc-availability.md` 变通方案。
+
+## 安全边界
+
+- **禁止**在未获用户明确确认时调用 `deleteObjectsByIds` 清空整页或大批量删除。
+- 流程 C 局部删除（如换器件删旧件）也须先打印 diff；单对象删除可随用户指令执行。
+- 若用户要求清页：先用 `getSnapshot` 报告当前对象数量，待用户确认后再删除。
+- 多开 HQ EDA 时提醒用户设置环境变量 `HQ_INSTANCE_ID`。
+
+## 脚本模板（每次输出必须包含）
+
+```typescript
+/**
+ * ===== PATTERN CHECK（禁止留空）=====
+ * list-circuit-patterns 已调用: YES
+ * subnet 分解:
+ *   [<子电路 A>] → <pattern id> (host=..., terminal=...)
+ *   [<子电路 B>] → <pattern id> (host=..., terminal=...)
+ *   [<leftover>] → hand (routing gate: 短 autoConnect / 长 stub+alias)
+ * =====================================
+ */
+import { connect, toJsonString } from "@huaqiu/huaqiu-client";
+import { HqServicesV1PatternLayoutService } from "@hqedge/connect";
+
+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);
+
+  // 1) 放置 host / 独立器件（placeKicadSymbol；电源符号 PlaceSymbolFromLibrary）
+  // 2) 【关键】等待注册：轮询 getPageOccupancy 直到所有新 id 出现
+  // 3) 规范位号 / 容值
+  // 4) applyCircuitPattern — host 引脚用 pinName 绑定
+  //      pattern: PL.CircuitPatternId.CIRCUIT_PATTERN_xxx
+  //      orientation: PL.PatternOrientation.PATTERN_ORIENT_LEFT_TO_RIGHT
+  //      routeMode: PL.PatternRouteMode.PATTERN_ROUTE_FULL
+  //      powerMode: PL.PatternPowerMode.PATTERN_POWER_AUTO_PLACE
+  // 5) 仅对 pattern 未覆盖的 net hand-wire（routing gate per net）
+  //    禁止重连 connections[].routed=true
+  // 6) 验收: netList.getActivePageNetList + canvasOps.listWireSegments().wires
+
+  await client.canvasOps.zoomAll({ context: ctx });
+  console.log("done");
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });
+```
+
+## 输出格式
+
+1. 简短设计说明（用了哪些 pattern、接线策略）
+2. 完整 `scripts/<名称>.ts` 源码
+3. 说明你已执行（或将执行）的命令：`npx tsx scripts/<名称>.ts`
+4. 验收结果（pattern status、netlist 关键 net、`wires` 条数统计）
+
+## 环境前提（提醒用户）
+
+- Node.js 18+
+- 公网 npm 可安装 `@huaqiu/huaqiu-client`（推荐 `^0.1.7`）与可选 `@huaqiu/hqeda`（`^0.2.7`）
+- HQ EDA 桌面版已运行且打开了目标工程
+- 多开编辑器时设置 `HQ_INSTANCE_ID`