ee-circuit-draw-simulator 0.0.0-stage → 0.2.0

package/README.zh-CN.md

@@ -0,0 +1,226 @@
+# 电子电路绘制仿真助手
+
+[English](README.md) · **简体中文**
+
+一个 [Agent Skill](https://skill.md)：让 AI 助手**真的把电路跑起来**，而不是凭记忆描述。
+载入或现造一个电路，改个电阻，确定性地推进仿真，读节点电压，采波形，扫参数，出 SVG ——
+最后给你一个点开就能拖滑块调参的链接。
+
+```
+你的一句话 ──▶ agent ──▶ circuitlab.mjs ──▶ 无头 Chrome ──▶ 真实的节点分析仿真器
+                     ◀── 数值 · 波形 · SVG · 分享链接 ──
+```
+
+数值来自引擎，不是模型背下来的公式。本文里每个数都是这个 skill 跑出来的。
+
+- 引擎：[ExtCircuitJS](https://github.com/blankwy/ExtCircuitJS)（CircuitJS1 二开，JSON 网表层 + MCP 桥，GPL-2.0-or-later）
+- 技能本体：纯 Node ≥ 22，零运行时依赖，一个 CLI，stdout 只出 JSON
+- 任何会读 `SKILL.md` 的助手都能用（Claude Code、Codex CLI、DeepSeek Harness、WorkBuddy…）
+
+## 它能回答什么
+
+| 你问 | 它给 |
+|---|---|
+| "这个 RC 滤波器的截止频率是多少？" | 扫频后的幅频响应，−3 dB 点由实测 Vpp 算出 |
+| "这个 555 跑多快？" | 实测 239.5 Hz、占空比 49.6%（窗口 t=0.2–0.8 s） |
+| "R2 换成 22 kΩ 会怎样？" | 同一次扫描里两组数，可直接比 |
+| "画个波形 / 画个电路图" | 内联 SVG，自带坐标轴与图例 |
+| "我想自己调调看" | 分享链接，点开就是可交互电路 |
+| "这振荡器为什么不起振？" | `engineSteps`、平坦通道与收敛告警 |
+
+实测样例（用下面的命令可复现）：
+
+| 电路 | 结果 |
+|---|---|
+| RC 低通，R=1 kΩ、C=100 nF | 100 Hz–6.4 kHz 之间 Vpp 从 9.98 掉到 2.40 V；1.6 kHz 处 0.707×（理论 1591 Hz） |
+| 555 无稳态，R2 = 10 k / 22 k / 47 k | 239.5 Hz / 108.8 Hz / 50.8 Hz，占空比 48–50% |
+| 运放同相放大，R2/R1 = 2 k/1 k | 增益 3：1 V 输入 → 3.00 V 输出；用原本的 5 V 源会削顶在 ±15 V 轨 |
+| 分压器 9 V、1 k/2 k | 分压点 6 V |
+
+## 安装
+
+### 0. 前置条件
+
+- **Node ≥ 22**
+- 本机有 **Chrome 或 Edge**（引擎跑在无头浏览器里，经页面桥驱动）
+- `git`
+
+### 1. 拿到技能和它的引擎
+
+```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？跳过这步，指过去即可：
+
+```bash
+export EXTCIRCUIT_HOME=/path/to/ExtCircuitJS
+```
+
+### 2. 装进你的助手
+
+技能就是一个根目录带 `SKILL.md` 的文件夹，下面各家用的内容完全一样，只有搜索路径不同。
+克隆一次，再链进去（软链只保留一份；复制一份也能用）：
+
+| 助手 | 用户级路径 | 项目级路径 |
+|---|---|---|
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| Codex CLI | `~/.codex/skills/` | `.codex/skills/` |
+| DeepSeek Harness（`dsh`） | `~/.dsh/skills/` 或 `~/.agents/skills/` | `.dsh/skills/` 或 `.agents/skills/` |
+| WorkBuddy | `~/.workbuddy/skills/` | `.workbuddy/skills/` |
+
+```bash
+mkdir -p ~/.claude/skills
+ln -s ~/ee-circuit-draw-simulator ~/.claude/skills/ee-circuit-draw-simulator
+```
+
+Windows（PowerShell，软链需要开发者模式或管理员）：
+
+```powershell
+New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\skills\ee-circuit-draw-simulator" -Target "$env:USERPROFILE\ee-circuit-draw-simulator"
+```
+
+没有软链权限就整个复制过去 —— 所有路径都相对技能根目录。
+
+#### Claude Code
+
+```bash
+ln -s ~/ee-circuit-draw-simulator ~/.claude/skills/ee-circuit-draw-simulator
+```
+
+随便开个会话问电路问题，任务匹配时 Claude Code 会自己加载这个技能。团队共用就链到
+`.claude/skills/` 并提交。
+
+#### Codex CLI
+
+技能还藏在实验开关后面：
+
+```toml
+# ~/.codex/config.toml
+[features]
+skills = true
+```
+
+```bash
+ln -s ~/ee-circuit-draw-simulator ~/.codex/skills/ee-circuit-draw-simulator
+```
+
+之后正常描述任务，或用 `$ee-circuit-draw-simulator` 显式点名。`/skills` 能看它扫到了什么。
+仓库里还带了 `AGENTS.md`，所以不开开关、直接在仓库里跑 `codex` 也能拿到工作流。
+
+#### DeepSeek Harness（`dsh`）
+
+```bash
+mkdir -p ~/.dsh/skills
+ln -s ~/ee-circuit-draw-simulator ~/.dsh/skills/ee-circuit-draw-simulator
+```
+
+`dsh` 的扫描顺序是 项目 `.dsh/skills/` → `.agents/skills/` → `~/.dsh/skills/` → `~/.agents/skills/`，
+只往下看一层、认文件夹名、`SKILL.md` 必须在根上 —— 本仓库已经合规（kebab-case 名、description
+控制在 500 字符渲染上限内）。用 `/ee-circuit-draw-simulator` 调用。
+
+#### WorkBuddy
+
+```bash
+mkdir -p ~/.workbuddy/skills
+ln -s ~/ee-circuit-draw-simulator ~/.workbuddy/skills/ee-circuit-draw-simulator
+```
+
+放进项目的 `.workbuddy/skills/` 就只在该工作区生效。
+
+#### 其它支持 Agent Skills 的客户端
+
+把它的技能目录指到这个文件夹就行。没有 MCP 服务器要配，没有后台进程要开。
+
+### 3. 验一下
+
+```bash
+node ~/ee-circuit-draw-simulator/scripts/circuitlab.mjs probe
+```
+
+`ok: true` 表示引擎在、后端通。后端没起也不用管：下一次 `run` 会自己拉起静态服务，跑完回收。
+
+## 用法
+
+```bash
+CLI=~/ee-circuit-draw-simulator/scripts/circuitlab.mjs
+
+# 367 个内置电路，可搜
+node $CLI corpus --search 555
+
+# 一轮完整仿真：载入 → 读数
+node $CLI run --circuit lrc --measure all
+
+# 波形：240 Hz 方波采 0.6 s，出 SVG
+node $CLI run --circuit 555square --sample n2 --span 0.6 --points 2000 --settle 0.2 --svg
+
+# 参数扫描：同一次运行三组值，可横向比
+node $CLI run --circuit 555square --sweep e14.resistance=10k,22k,47k \
+  --probe n2 --settle 0.2 --span 0.6 --points 2000 --svg
+
+# 频率响应（对数轴）
+node $CLI run --netlist ~/ee-circuit-draw-simulator/references/examples/rc-lowpass.json \
+  --sweep e1.frequency=100,200,400,800,1600,3200,6400 --probe n1 \
+  --settle 0.02 --span 0.02 --points 100 --logx --svg
+
+# 分享链接（不需要浏览器）
+node $CLI share --circuit lrc
+
+# 导出电路图
+node $CLI shot --circuit lrc --out lrc.svg
+```
+
+`stdout` 永远只有一个 JSON 对象，诊断信息走 `stderr`。这是故意的：助手可以直接把结果接进推理，
+不用先解析散文。
+
+常用参数：
+
+| 参数 | 含义 |
+|---|---|
+| `--circuit <名>` / `--netlist <json\|@文件>` / `--text` / `--file` | 电路来源。网表只写拓扑，编译器负责布局布线，不用坐标 |
+| `--set <ref>=<值>` | 改元件参数；`e14.resistance`、`ResistorElm#2.resistance`；支持 `4.7k`、`100n`、`2.2M` |
+| `--step <秒>` | 确定性推进（内部自动分块 —— 桥对单次长步进会静默截断） |
+| `--measure all \| n1,n2` / `--components` | 瞬时节点电压 / 元件电流 |
+| `--sample` `--span` `--points` `--settle` | 时域采样，不依赖引擎自带的示波器缓冲 |
+| `--sweep <ref>=v1,v2,…` `--probe` `--logx` | 参数扫描，一个值一行结果 |
+| `--svg` `--shot` `--share` `--dump` | 波形图、电路图、分享链接、电路文本 |
+
+## 目录
+
+```
+ee-circuit-draw-simulator/
+├── SKILL.md                  助手入口：先决条件、交付形态、工作流、硬性纪律
+├── AGENTS.md                 给读仓库说明的助手（Codex 等）的同款工作流
+├── scripts/
+│   ├── circuitlab.mjs        CLI（setup / probe / corpus / run / share / shot）
+│   └── lib/
+│       ├── backend.mjs       引擎定位、探活、自启后端
+│       ├── svg.mjs           波形/扫描 → 内联 SVG，按量纲分面
+│       └── units.mjs         4.7k / 100n 解析与格式化
+├── references/               网表 schema、语料索引、MCP 工具表、排障
+└── vendor/                   setup 克隆下来的引擎（已 gitignore）
+```
+
+## 写进技能里的"老实规矩"
+
+1. 数值只能来自 `measurements` / `sample` / `sweep`，不许把公式结果当实测值报。
+2. 只用 `sim.step`（冻结墙钟）。`sim.run` 由墙钟驱动，两次跑数不一样。
+3. 不手写坐标：手写 XML 差 1 px 就是静默开路。
+4. 多端元件（运放、555、晶体管）用内置语料 + `--set`；把这类电路手写成网表，自动布线可能让求解停住，CLI 会报出来。
+5. 采样太稀不藏着：`resolutionWarning` 就是"加大 `--points` 重跑"。
+
+## 边界
+
+- 对话里没有可交互画布：能点能拖的东西一律做成分享链接。
+- 链接只承载电路本身，不含仿真状态（对方从 t=0 开始）。
+- 单文件离线 HTML（`ext bundle-single`）没有内置电路列表与中文语言包（`file://` 的 CORS 限制），仿真本身正常。
+- 引擎是 GPL-2.0-or-later；本技能沿用同一许可，不打包引擎代码。
+- `references/` 下的深水区文档是中文（作者的一手实验笔记）；`SKILL.md`、`AGENTS.md` 与英文 README 为英文。
+
+## 致谢
+
+建立在 Paul Falstad / Iain Sharp 的 [CircuitJS1](https://github.com/pfalstad/circuitjs1) 之上，经
+[ExtCircuitJS](https://github.com/blankwy/ExtCircuitJS) 二开。技能文本与 CLI：GPL-2.0-or-later，见 [LICENSE](LICENSE)。

package/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: ee-circuit-draw-simulator
+description: "Run real circuit simulation instead of guessing: load or author a circuit, tweak part values, step deterministically, read node voltages, sample waveforms, sweep parameters, render SVG plots and schematics, and emit shareable interactive links. Use when a circuit/electronics answer needs real numbers or waveforms: filter cutoff, 555 duty cycle, op-amp gain, dividers, resonance, rectifier ripple, RC charging, why it will not oscillate. 需要真实数值或波形的电路问题与电路图：滤波器、555、运放、分压、谐振、整流、RC、起振排障。"
+license: GPL-2.0-or-later
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+metadata:
+  version: 0.2.0
+  homepage: https://github.com/blankwy/ee-circuit-draw-simulator
+  engine: ExtCircuitJS (CircuitJS1 fork; real nodal-analysis simulator driven headlessly over an MCP bridge)
+  trigger: 电路仿真、波形、元件参数、滤波器/振荡器/放大器、生成电路图、分享可交互电路
+---
+
+# 电子电路绘制仿真助手
+
+回答电路问题时，不要"画一个像电路的图"再凭公式估数 —— 在 **ExtCircuitJS 引擎**上跑，
+把真实读数、真实波形给出来。555 的占空比、RC 的 −3dB 点、运放的增益，都能算出来、也能被验证。
+
+核心资产是一个 CLI：`scripts/circuitlab.mjs`。它已封装「载入 → 改参 → 确定性步进 → 读数 →
+采样 → 参数扫描 → 出 SVG → 出分享链接」全链路，一次进程跑完，stdout 只有 JSON。
+
+> 回答用用户的语言；数值、单位、元件名照 CLI 输出原样引用。
+
+## 一、先决条件（按顺序做，别跳）
+
+```bash
+node <skill>/scripts/circuitlab.mjs probe
+```
+
+- `ok: true` → 有引擎、有后端，直接干活。
+- `ok: false` + `hint` 说"还没装引擎" → 装一次（克隆 ExtCircuitJS 到 `vendor/`，装依赖、无头浏览器驱动与构建，约 2–4 分钟）：
+
+```bash
+node <skill>/scripts/circuitlab.mjs setup
+```
+
+- `ok: false` + 引擎在、后端不在 → **不用管**：下一次 `run` 会自己拉起静态服务（有 `dist/` 走
+  `ext serve`，没有走 `ext dev`），跑完自动回收。加 `--no-spawn` 可关掉这个行为。
+
+引擎查找顺序：`--repo` → `$EXTCIRCUIT_HOME` → `<skill>/vendor/ExtCircuitJS` → 同级 `../ExtCircuitJS`
+→ `~/.ee-circuit/ExtCircuitJS` → `cwd`。想用别的 clone：
+
+```bash
+export EXTCIRCUIT_HOME=/path/to/ExtCircuitJS
+```
+
+需要 Node ≥ 22 与本机 Chrome/Edge（引擎是无头浏览器里的真仿真器，经 MCP 桥驱动）。
+
+> GitHub Pages 上的在线站点**只能给人点开看**，MCP 驱动不了（探活只支持 http）——别把它当后端。
+
+## 二、交付形态怎么选
+
+| 用户想要 | 给什么 | 命令要点 |
+|---|---|---|
+| 一句话能答的概念问题 | 直接文字，别折腾 | — |
+| 要真实数值 / 看波形 | 读数 + SVG 曲线 | `--sample ... --svg` |
+| 想对比改参数前后 | 同一次扫描里给出多组数值 | `--sweep` |
+| **想自己动手试、拖滑块调参** | **分享链接**（最轻，首选） | `--share` |
+| 要电路长什么样 | 电路图 SVG | `--shot out.svg` |
+| 离线 / 内网 / 存档 | 单文件 HTML（1.4 MB，`<引擎>/build/circuitjs-single.html`） | `node tools/ext.mjs bundle-single` |
+
+## 三、标准回合（照这个顺序做）
+
+### 1. 找电路
+
+```bash
+# 内置 367 个电路，按关键词找（RC 滤波、555、运放、振荡器…）
+node <skill>/scripts/circuitlab.mjs corpus --search 555
+node <skill>/scripts/circuitlab.mjs corpus --list        # 按 52 个分类全列
+```
+
+内置语料没有合适的 → 自己写网表 JSON（`references/netlist.md` 有 schema、元件表和示例）。
+**不要手写坐标**：网表只描述拓扑，编译器自动布局 + 布线（含多端元件）。
+
+### 2. 看清电路
+
+```bash
+node <skill>/scripts/circuitlab.mjs run --circuit lrc --measure all
+```
+
+返回 `circuit.elements`（稳定 id `e1..eN` + 参数）与 `circuit.nets`（网名 `n0..` + 引脚归属，
+导线引脚已滤掉）。**引擎会把网表里的自定义网名改成 `n0/n1…`**，所以要靠
+`nets[].pins` 判断哪个网是输出 —— 例：`n1: [e2:1, e3:0]` = 接在电阻 1 脚与电容 0 脚之间的那个网。
+
+### 3. 改参数 + 看波形
+
+```bash
+# 时域波形：覆盖 0.6 s（约 144 个周期），SVG 会自动缩到前几个周期展示，统计仍按全窗口
+node <skill>/scripts/circuitlab.mjs run --circuit 555square \
+  --sample n2 --span 0.6 --points 2000 --settle 0.2 --svg
+```
+
+```bash
+# 参数扫描：改 R2，看频率/占空比怎么变（同一次进程，前后可比）
+node <skill>/scripts/circuitlab.mjs run --circuit 555square \
+  --sweep e14.resistance=10k,22k,47k --probe n2 \
+  --settle 0.2 --span 0.6 --points 2000 --svg
+```
+
+```bash
+# 频率响应：扫频看 −3dB 点（RC 低通，R=1k C=100n → 理论 1591 Hz）
+node <skill>/scripts/circuitlab.mjs run --netlist <skill>/references/examples/rc-lowpass.json \
+  --sweep e1.frequency=100,200,400,800,1600,3200,6400 --probe n1 \
+  --settle 0.02 --span 0.02 --points 100 --logx --svg
+```
+
+元件引用支持两种写法：稳定 id（`e14.resistance`）或 `类型#序号`（`ResistorElm#2.resistance`）。
+数值支持工程单位：`4.7k`、`100n`、`2.2M`、`1e-7`。
+
+### 4. 读数怎么写进回答
+
+`sample.channels[]` 每个网给：`min / max / vpp / mean / rms / final / dutyCycle / dutyAboveMid / freqEstimate`。
+`freqEstimate` 与 `dutyCycle` 由过中点时刻**线性插值**算出（不是数窗口边缘的边沿），所以
+`--points` 从 600 加到 4000，同一个 555 的频率只在 239.5 Hz 附近抖动 ±0.1 Hz；`dutyAboveMid`
+是纯采样计数，粗看用。`--measure` 给瞬时值，`--components` 给元件电流。
+
+写结论时必须带**数值 + 单位 + 条件**：
+
+> 该 555 方波语料（定时电阻 e14=10 kΩ、定时电容 0.3 µF）输出频率 **239.5 Hz**、占空比 **49.6%**
+> （实测，窗口 t=0.2–0.8 s）；把 e14 换成 22 kΩ → **108.8 Hz**，47 kΩ → **50.8 Hz**（占空比 48–50%）。
+
+不要写"频率会变低"这种没有数的话。
+
+### 5. 用户想自己玩 → 分享链接
+
+```bash
+node <skill>/scripts/circuitlab.mjs run --circuit 555square --set e14.resistance=22k --share
+```
+
+返回一行 URL（`length` < 2000 安全）。点开即见电路、可点 RUN、可拖滑块调参。
+链接只含电路本身，不含仿真状态（对方看到的是 t=0）。超过 2000 字符时改用
+`--share-out share.html`（1–2KB 分享页）。
+
+## 四、硬性纪律
+
+1. **数值只能来自 CLI 输出**（`measurements` / `sample` / `sweep`）。不许按公式"推"一个数再当实测值报。
+   想对比理论值就明确写"实测 X，理论 Y"。
+2. **不要绕过 CLI 自己写 Node 脚本调 MCP** —— 除非 CLI 缺能力（此时先补 CLI）。
+3. **确定性步进**：CLI 内部只用 `sim.step`（冻结墙钟、可复现）。绝不要改用 `sim.run`（墙钟驱动，两次跑数值不同）。
+4. **不手写坐标**。改电路用 `--set`；造电路用网表 JSON。手写 XML 坐标差 1 px 会静默开路（不报错、全 0 V）。
+   **多端元件（运放 / 555 / 晶体管）优先用内置语料 + `--set`**：实测把运放反馈网络写成网表，
+   自动布线会生成重复/交叉导线，仿真直接停住（`engineSteps=0`）。
+5. **采样要够密**：每个周期 ≥ 8 点、窗口 ≥ 3 个周期。返回里出现 `resolutionWarning` 就加大
+   `--points` / `--span` 重跑，别拿失真数据下结论。
+6. **每个网至少接 2 个引脚**（地除外）。悬空节点会让引擎停在 t=0、读数全 0。
+7. 读数全 0 时先 `--step 0.001` 再看 —— t=0 那一刻引擎还没建立节点电压。
+
+## 五、SVG 怎么放进回答
+
+CLI 把图写到 `--out` 目录（默认 `./circuit-out/`，文件名 `waveform.svg` / `sweep.svg`）。
+用 Read 读出 `<svg …>…</svg>` 全文，直接内联进回复 —— 它自带坐标轴、刻度、图例，
+按量纲分面（V 与 A 不混在一张图），透明背景，深色/浅色主题都能读。
+同时把文件路径给用户，方便另存。
+
+电路图（`--shot x.svg`）是引擎画布的真实矢量导出（白底），适合"这电路长什么样"。
+
+## 六、排障
+
+| 现象 | 处理 |
+|---|---|
+| `ok:false` + "还没装引擎" | `node <skill>/scripts/circuitlab.mjs setup` |
+| `ok:false` + "没有可达的后端" | 去掉 `--no-spawn`，或手动 `node tools/ext.mjs serve --port 8080` |
+| `backend_unavailable` / 找不到 Chrome | 装 Chrome 或 Edge；或设 `EXT_CHROME`/`EXT_PW_CORE` |
+| 改参 `applied: 0` / 参数名对不上 | 看 `circuit.elements[].props` 里的真实字段名（如 `capacitance` 不是 `capacitor`） |
+| 读数全 0 / t 一直是 0 / `engineSteps=0` | 悬空节点、没步进、或布线把节点接错（多端元件常见）；先 `--step` 并看 `warnings` |
+| 波形是一条直线 / `flat` 里有网名 | 该网没被驱动（悬空或未连接到源） |
+| 扫描出来的数不像理论值 | 先确认 `--settle` 够长（跳过暂态）、`--span` 覆盖 ≥3 周期 |
+| 链接打开是空白 | URL 被截断（>2000 字符），改用 `--share-out` 出分享页 |
+
+更细的坑见 `references/troubleshooting.md`。
+
+## 七、参考文件
+
+| 文件 | 内容 |
+|---|---|
+| `references/netlist.md` | 网表 JSON schema、常用元件参数与引脚数、可直接抄的示例 |
+| `references/circuits.md` | 367 个内置语料的分类索引（52 类）+ 怎么搜 |
+| `references/tools.md` | 底层 MCP 11 个工具（CLI 已封装，改造/排障时看） |
+| `references/troubleshooting.md` | 已知坑与判定方法 |

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "ee-circuit-draw-simulator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "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",
+  "homepage": "https://github.com/blankwy/ee-circuit-draw-simulator",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blankwy/ee-circuit-draw-simulator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/blankwy/ee-circuit-draw-simulator/issues"
+  },
+  "bin": {
+    "ee-circuit-draw-simulator": "./scripts/circuitlab.mjs",
+    "circuitlab": "./scripts/circuitlab.mjs"
+  },
+  "files": [
+    "SKILL.md",
+    "AGENTS.md",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE",
+    "scripts/",
+    "references/"
+  ],
+  "scripts": {
+    "setup": "node scripts/circuitlab.mjs setup",
+    "probe": "node scripts/circuitlab.mjs probe",
+    "check": "node --check scripts/circuitlab.mjs && node --check scripts/lib/backend.mjs && node --check scripts/lib/svg.mjs && node --check scripts/lib/units.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "codex",
+    "deepseek-harness",
+    "circuit",
+    "circuit-simulation",
+    "electronics",
+    "spice",
+    "schematic",
+    "waveform",
+    "education"
+  ]
+}

package/references/circuits.md

@@ -0,0 +1,46 @@
+# 内置语料索引（367 个电路 / 52 类）
+
+```bash
+node <skill>/scripts/circuitlab.mjs corpus --list                 # 全部，按分类
+node <skill>/scripts/circuitlab.mjs corpus --search filter        # 按名字/标题搜
+node <skill>/scripts/circuitlab.mjs corpus --category "Filters"   # 按分类筛
+node <skill>/scripts/circuitlab.mjs corpus --search 555
+```
+
+用法：`run --circuit <name>`（不带 `.txt`）。找不到就先用 `corpus --search`，别猜名字。
+
+## 教学最常用的几类
+
+| 主题 | 分类 | 代表语料 |
+|---|---|---|
+| 基本定律 / 分压分流 | Basics / Series·Parallel | `ohms`、`resistors`、`voltdivide`、`potdivide`、`thevenin`、`norton`、`capseries`、`indpar` |
+| RC/RL 充放电、交流阻抗 | A/C Circuits | `capac`、`inductac`、`impedance`、`res-series`、`res-par` |
+| 无源滤波 | Passive Filters | `filt-lopass`、`filt-hipass`、`filt-lopass-l`、`bandpass`、`notch`、`twint`、`butter10lo` |
+| 有源滤波 | Active Filters | `filt-vcvs-lopass`、`filt-vcvs-hipass`、`switchedcap` |
+| 二极管 / 整流 | Diodes / Zener | `rectify`、`diodecurve`、`diodevar`、`zeneriv`、`zenerref` |
+| 倍压 / 电源变换 | Voltage Multipliers / Power Converters | `voltdouble`、`volttriple`、`conv-buck`、`conv-boost`、`conv-buckboost` |
+| 运放与放大器 | Op-Amps / Amplifiers | `opamp`、`opampfeedback`、`amp-invert`、`amp-noninvert`、`amp-follower` |
+| 晶体管 / MOSFET | Transistors / MOSFETs | `npn`、`pnp`、`transswitch`、`nmosfet`、`pmosfet`、`mosswitch` |
+| 振荡器 | Oscillators | `relaxosc`、`phaseshiftosc`、`triangle`、`wienbridge`、`varactorvco` |
+| 555 定时器 | 555 Timer Chip | `555square`、`555saw`、`555lowduty`、`555monostable`、`555int` |
+| 多谐振荡 / 触发器 | Multivibrators / Flip-Flops | `multivib-a`、`multivib-bi`、`multivib-mono`、`nandff`、`clockedsrff` |
+| 数字逻辑 | Combinational / Counters / Shift Registers | `xor`、`halfadd`、`fulladd`、`counter`、`sipo-sr` |
+| 逻辑门族（RTL/DTL/TTL/CMOS） | RTL / DTL / TTL / CMOS | `rtlinverter`、`ttlnand`、`cmosinverter`、`cmosnand` |
+| 锁相环 | Phase-Locked Loops | `pll`、`xorphasedet`、`phasecomp` |
+| 传输线 | Transmission Lines | `tl`、`tlstand`、`tlterm` |
+| 受控源 | Controlled Sources | `cs-resistor`、`cs-varyresistor`、`cs-opamp` |
+| 弛豫 / 张弛 | Tunnel Diodes / Spark Gap | `tdosc`、`tdrelax`、`spark-sawtooth`、`tesla` |
+| 混沌 | Chaotic Circuits | `chua`、`rossler`、`vilnius` |
+| 继电器 | Relays | `relay`、`relayand`、`relayor` |
+| 2D 示波器（李萨如） | 2-D Scope | `lissa`、`plot2d-color` |
+
+## 使用提示
+
+- 373 个语料文件里（索引收录 367 个有分类的）**只有 27 个自带示波器（scope）**，所以别指望 `read_scope` 一定有数据。
+  本 skill 的 `--sample` 是自己逐步测量建的时序，不依赖 scope，任意网都能画。
+- 语料里的元件 id 由引擎分配（`e1..eN`，导线也占号），**每次载入后先用 `--measure all` 看
+  `circuit.elements` 再决定改哪个**，不要照抄文档里的 id。
+- 语料里的 `SweepElm`（扫频源）是 CircuitJS 的"频率自动扫描"元件，跟本 skill 的
+  `--sweep`（参数扫描）不是一回事：前者靠仿真时间推进频率，后者是我们主动改参数重新跑。
+  要做频率响应，**用 `VoltageElm` + `--sweep e?.frequency=...` 更可控**。
+- 语料是 GPL-2.0 上游内容，随仓库分发；改出来的电路用 `--share` 出链接最省事。

package/references/examples/divider.json

@@ -0,0 +1,14 @@
+{
+  "schema": "netlist/0.1",
+  "components": [
+    { "id": "v1", "type": "VoltageElm", "props": { "waveform": 0, "maxVoltage": 9, "bias": 0 } },
+    { "id": "r1", "type": "ResistorElm", "props": { "resistance": 1000 } },
+    { "id": "r2", "type": "ResistorElm", "props": { "resistance": 2000 } },
+    { "id": "g1", "type": "GroundElm", "props": {} }
+  ],
+  "nets": [
+    { "id": "in", "pins": ["v1:0", "r1:0"] },
+    { "id": "out", "pins": ["r1:1", "r2:0"] },
+    { "id": "gnd", "pins": ["v1:1", "r2:1", "g1:0"], "ground": true }
+  ]
+}

package/references/examples/halfwave-rectifier.json

@@ -0,0 +1,14 @@
+{
+  "schema": "netlist/0.1",
+  "components": [
+    { "id": "v1", "type": "VoltageElm", "props": { "waveform": 1, "frequency": 50, "maxVoltage": 10 } },
+    { "id": "d1", "type": "DiodeElm", "props": { "modelName": "default" } },
+    { "id": "r1", "type": "ResistorElm", "props": { "resistance": 1000 } },
+    { "id": "g1", "type": "GroundElm", "props": {} }
+  ],
+  "nets": [
+    { "id": "ac", "pins": ["v1:0", "d1:0"] },
+    { "id": "dc", "pins": ["d1:1", "r1:0"] },
+    { "id": "gnd", "pins": ["v1:1", "r1:1", "g1:0"], "ground": true }
+  ]
+}

package/references/examples/rc-lowpass.json

@@ -0,0 +1,14 @@
+{
+  "schema": "netlist/0.1",
+  "components": [
+    { "id": "v1", "type": "VoltageElm", "props": { "waveform": 1, "frequency": 1000, "maxVoltage": 5, "bias": 0, "phaseShift": 0 } },
+    { "id": "r1", "type": "ResistorElm", "props": { "resistance": 1000 } },
+    { "id": "c1", "type": "CapacitorElm", "props": { "capacitance": 1e-7 } },
+    { "id": "g1", "type": "GroundElm", "props": {} }
+  ],
+  "nets": [
+    { "id": "in", "pins": ["v1:0", "r1:0"] },
+    { "id": "out", "pins": ["r1:1", "c1:0"] },
+    { "id": "gnd", "pins": ["v1:1", "c1:1", "g1:0"], "ground": true }
+  ]
+}