ee-circuit-draw-simulator 0.2.0 → 0.2.1

package/README.md

@@ -13,6 +13,7 @@ Numbers come from the engine, never from a formula the model recalled. Every val
 
 - Engine: [ExtCircuitJS](https://github.com/blankwy/ExtCircuitJS) — a CircuitJS1 fork with a JSON netlist layer and an MCP bridge, GPL-2.0-or-later
 - Skill: pure Node ≥ 22, no runtime dependencies, one CLI, JSON on stdout
+- CLI on npm: [`ee-circuit-draw-simulator`](https://www.npmjs.com/package/ee-circuit-draw-simulator)
 - Works with any agent that reads `SKILL.md` (Claude Code, Codex CLI, DeepSeek Harness, WorkBuddy, …)
 
 ## What it answers
@@ -45,13 +46,22 @@ Measured examples (reproducible with the commands below):
 
 ### 1. Get the skill and its engine
 
+**As an agent skill (recommended).** The agent needs the files on disk to read `SKILL.md`, so clone:
+
 ```bash
 git clone https://github.com/blankwy/ee-circuit-draw-simulator.git ~/ee-circuit-draw-simulator
 cd ~/ee-circuit-draw-simulator
 node scripts/circuitlab.mjs setup
 ```
 
-`setup` clones the engine into `vendor/ExtCircuitJS`, installs its build dependencies plus the headless-browser driver (`playwright-core`), and builds `dist/`. One time, ~2–4 minutes. Already have an engine checkout? Skip this and point at it:
+**As a plain CLI.** Also published on npm — no clone, good for scripts and CI:
+
+```bash
+npx ee-circuit-draw-simulator@latest setup     # engine → ~/.ee-circuit/ExtCircuitJS
+npx ee-circuit-draw-simulator run --circuit lrc --step 0.005 --measure all
+```
+
+`setup` clones the engine, installs its build dependencies plus the headless-browser driver (`playwright-core`), and builds `dist/`. One time, ~2–4 minutes. With a clone the engine lands in `vendor/ExtCircuitJS`; installed from npm (0.2.1 and later) it goes to `~/.ee-circuit/ExtCircuitJS`, so upgrading the package never throws away a 2-minute build. Already have an engine checkout? Skip both and point at it:
 
 ```bash
 export EXTCIRCUIT_HOME=/path/to/ExtCircuitJS

package/README.zh-CN.md

@@ -15,6 +15,7 @@
 
 - 引擎：[ExtCircuitJS](https://github.com/blankwy/ExtCircuitJS)（CircuitJS1 二开，JSON 网表层 + MCP 桥，GPL-2.0-or-later）
 - 技能本体：纯 Node ≥ 22，零运行时依赖，一个 CLI，stdout 只出 JSON
+- CLI 也发在 npm：[`ee-circuit-draw-simulator`](https://www.npmjs.com/package/ee-circuit-draw-simulator)
 - 任何会读 `SKILL.md` 的助手都能用（Claude Code、Codex CLI、DeepSeek Harness、WorkBuddy…）
 
 ## 它能回答什么
@@ -47,14 +48,24 @@
 
 ### 1. 拿到技能和它的引擎
 
+**当技能装（推荐）。** 助手要靠磁盘上的文件读 `SKILL.md`，所以克隆下来：
+
 ```bash
 git clone https://github.com/blankwy/ee-circuit-draw-simulator.git ~/ee-circuit-draw-simulator
 cd ~/ee-circuit-draw-simulator
 node scripts/circuitlab.mjs setup
 ```
 
-`setup` 会把引擎克隆到 `vendor/ExtCircuitJS`、装构建依赖和无头浏览器驱动（`playwright-core`）、生成 `dist/`。一次性，约 2–4 分钟。
-已经有引擎 checkout？跳过这步，指过去即可：
+**当纯 CLI 用。** 也发在 npm 上了，不用克隆，适合脚本和 CI：
+
+```bash
+npx ee-circuit-draw-simulator@latest setup     # 引擎装到 ~/.ee-circuit/ExtCircuitJS
+npx ee-circuit-draw-simulator run --circuit lrc --step 0.005 --measure all
+```
+
+`setup` 会克隆引擎、装构建依赖和无头浏览器驱动（`playwright-core`）、生成 `dist/`。一次性，约 2–4 分钟。
+克隆方式下引擎落在 `vendor/ExtCircuitJS`；从 npm 装时（0.2.1 起）落在 `~/.ee-circuit/ExtCircuitJS`，
+这样升级包版本不会连那 2 分钟的构建一起丢掉。已经有引擎 checkout？两条都跳过，指过去即可：
 
 ```bash
 export EXTCIRCUIT_HOME=/path/to/ExtCircuitJS

package/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools:
   - Glob
   - Grep
 metadata:
-  version: 0.2.0
+  version: 0.2.1
   homepage: https://github.com/blankwy/ee-circuit-draw-simulator
   engine: ExtCircuitJS (CircuitJS1 fork; real nodal-analysis simulator driven headlessly over an MCP bridge)
   trigger: 电路仿真、波形、元件参数、滤波器/振荡器/放大器、生成电路图、分享可交互电路
@@ -24,6 +24,8 @@ metadata:
 采样 → 参数扫描 → 出 SVG → 出分享链接」全链路，一次进程跑完，stdout 只有 JSON。
 
 > 回答用用户的语言；数值、单位、元件名照 CLI 输出原样引用。
+> 本文件里写作 `node <skill>/scripts/circuitlab.mjs`；如果手上只有 npm 包没有技能目录，
+> 换成 `npx ee-circuit-draw-simulator`，参数完全一样。
 
 ## 一、先决条件（按顺序做，别跳）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ee-circuit-draw-simulator",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Agent skill for real circuit simulation: draw, simulate, measure, plot and share circuits instead of guessing numbers.",
   "type": "module",
   "license": "GPL-2.0-or-later",
@@ -13,8 +13,8 @@
     "url": "https://github.com/blankwy/ee-circuit-draw-simulator/issues"
   },
   "bin": {
-    "ee-circuit-draw-simulator": "./scripts/circuitlab.mjs",
-    "circuitlab": "./scripts/circuitlab.mjs"
+    "ee-circuit-draw-simulator": "scripts/circuitlab.mjs",
+    "circuitlab": "scripts/circuitlab.mjs"
   },
   "files": [
     "SKILL.md",

package/scripts/circuitlab.mjs

@@ -26,6 +26,7 @@ import {
     defaultEngineDir,
     isEngineRepo,
     hasPlaywrightCore,
+    SKILL_IN_NODE_MODULES,
     ENGINE_URL,
     SKILL_DIR,
 } from "./lib/backend.mjs";
@@ -34,7 +35,8 @@ import { parseValue, fmtEng, round } from "./lib/units.mjs";
 
 const HELP = `ee-circuit-draw-simulator —— 电子电路绘制仿真助手 CLI
 
-用法: node circuitlab.mjs <命令> [选项]
+用法: ee-circuit-draw-simulator <命令> [选项]
+      （等价写法：npx ee-circuit-draw-simulator ... / node scripts/circuitlab.mjs ...）
 
 命令:
   setup     第一次用：克隆并构建 ExtCircuitJS 引擎（一次就够）
@@ -51,7 +53,8 @@ const HELP = `ee-circuit-draw-simulator —— 电子电路绘制仿真助手 CL
   --out <dir>       产物目录（默认 ./circuit-out）
 
 setup 的选项:
-  --dir <path>      引擎装到哪（默认 <skill>/vendor/ExtCircuitJS）
+  --dir <path>      引擎装到哪（默认 <skill>/vendor/ExtCircuitJS；
+                    npx / 全局安装时默认 ~/.ee-circuit/ExtCircuitJS）
   --url <git url>   换一个 fork（默认 ${ENGINE_URL}）
   --skip-install    跳过 core install
   --skip-build      跳过 build（没有 dist 就只能用 dev server）
@@ -848,9 +851,13 @@ async function cmdProbe(o) {
         }
     }
     if (!repo) {
+        const how = SKILL_IN_NODE_MODULES
+            ? "npx ee-circuit-draw-simulator setup"
+            : "node <skill>/scripts/circuitlab.mjs setup";
         out.hint = [
             "还没装引擎（ExtCircuitJS）。一条命令搞定：",
-            "  node <skill>/scripts/circuitlab.mjs setup",
+            `  ${how}`,
+            `引擎会装到：${defaultEngineDir()}`,
             `找过的位置：${tried.slice(0, 5).join(" / ")}`,
         ];
     } else if (!out.ok && !out.hint) {

package/scripts/lib/backend.mjs

@@ -21,9 +21,20 @@ export const SKILL_DIR = path.resolve(HERE, "../..");
 /** 官方引擎仓库。setup 命令按它克隆；也可以 --url 换成自己的 fork。 */
 export const ENGINE_URL = "https://github.com/blankwy/ExtCircuitJS.git";
 
+/**
+ * 技能目录是不是躺在某个 node_modules 里（npx / -g / 装成依赖）。
+ * 那种位置的目录会被升级、`npm cache clean`、临时安装目录回收抹掉。
+ */
+export const SKILL_IN_NODE_MODULES = /[\\/](node_modules|_npx)[\\/]/.test(`${SKILL_DIR}${path.sep}`);
+
 /** 技能自带引擎的落点（.gitignore 掉，不进本仓库）。 */
 export function defaultEngineDir() {
-    return process.env.EE_CIRCUIT_ENGINE_DIR || path.join(SKILL_DIR, "vendor", "ExtCircuitJS");
+    if (process.env.EE_CIRCUIT_ENGINE_DIR) return process.env.EE_CIRCUIT_ENGINE_DIR;
+    // 从 npm 装着跑（npx 最典型）时，包目录是临时/可回收的：引擎放到用户目录，
+    // 否则换一次版本就得重下一份引擎、重构建两分钟。
+    return SKILL_IN_NODE_MODULES
+        ? path.join(os.homedir(), ".ee-circuit", "ExtCircuitJS")
+        : path.join(SKILL_DIR, "vendor", "ExtCircuitJS");
 }
 
 /** 判断一个目录是不是 ExtCircuitJS 仓库根。 */