PCB 元器件搜索Huaqiu-Electronics/dsh-pcb-parts-search

dsh-tool-pcb-parts-search

English

DSH PCB 元器件搜索工具插件 —— 按关键词搜索 IC / 有源 / 无源电子元器件，用于 PCB 设计与 EDA 选型。通过芯灵（eda.cn）queryPage 接口查询，默认只返回带 EDA 模型（原理图符号 / PCB 封装）的器件。

License

动机

Agent 做 PCB 设计、原理图绘制、BOM 选型时，需要按型号或描述查找电子元器件。现有路径是起 bash 进程让模型现写 curl 脚本调搜索引擎：

1. 每次调用都起进程——Windows 上尤其昂贵，且模型手写 HTTP 请求错误率高
2. 结果不可结构化——模型从网页 HTML 里提取型号、描述、数据手册地址，字段缺失/格式混乱是常态
3. 无法保证可设计性——搜到的器件不一定有 EDA 模型（原理图符号 / PCB 封装），放进设计后发现无法布局连线

本插件封装芯灵 queryPage 搜索接口为一次函数调用，毫秒级返回结构化 JSON（mpn / 制造商 / 描述 / 数据手册），默认过滤出带 EDA 模型的器件，保证结果可直接用于 PCB 设计。

安全模型

- 白名单域名：仅向写死的 https://www.eda.cn/api/chiplet/products/queryPage 发送 POST 请求，不接受用户传入的 URL
- 入口参数双重校验：工具入口（runSearch）与 API 客户端（queryPageSearch）各自独立校验，不依赖上游 schema
- keyword：非空字符串，≤200 字符
- page_size：整数 1–50
- require_eda_model：布尔值
- HTTP 状态码 + 业务 code 双重校验：HTTP 200 不代表业务成功，必须再检查响应体 code === 200000（eda.cn 接口的坑，详见 queryPage.ts 文件头注释）
- 防御性结构解包：对 result[].queryPartVO.part 做空值过滤，避免下游 map 时 undefined 报错
- 字段白名单：返回只取 mpn / manufacturer_id / part_desc / datasheet 四个字段，不透传接口原始返回的其他字段
- 超时兜底：timeoutMs: 15000（网络请求，高于纯计算工具的 1000ms）
- 工具参数会记入会话日志，不要传入敏感数据

架构

┌──────────────────────────────────────┐
│            DSH Agent                  │
│  tool call: pcb_parts_search { ... }  │
└──────────────┬───────────────────────┘
│ ctx.tools.register()
┌──────────────▼───────────────────────┐
│         src/index.ts                  │
│         Cordis 插件入口                │
│  runSearch() → queryPageSearch()      │
│  renderResults() → 文本块              │
└──────────────┬───────────────────────┘
│
┌──────────────▼───────────────────────┐
│         src/queryPage.ts              │
│  fetch(SEARCH_URL, POST)              │
│  HTTP 校验 → code 校验 → 结构拍平       │
└──────────────────────────────────────┘

- src/index.ts：Cordis 插件入口（name/inject/apply），注册 pcb_parts_search 工具；含参数防御、结果映射、文本渲染
- src/queryPage.ts：queryPageSearch(keyword, options): Promise——请求 eda.cn 接口，校验 HTTP + 业务 code，拍平嵌套结构
- src/invariant.ts：不变量伴随插件（无运行时不变量，行为由测试覆盖）

工具声明

注册 pcb_parts_search 工具（@deepseek-ai/dsh-tool-pcb-parts-search，row id tool-pcb-parts-search），输出 JSON 文本字符串。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | string | ✅ | 搜索关键词：型号（如 "STM32F103C8T6"）、描述（如 "32-bit microcontroller 72MHz"）或组合值（如 "0402 10k resistor"）。≤200 字符。模糊匹配，可能返回型号相近的候选 |
| page_size | integer | | 最多返回条数，范围 1–50，默认 5。选型用 5–10 即可；广泛对比可调大 |
| require_eda_model | boolean | | 是否只返回有 EDA 模型（原理图符号 + PCB 封装）的器件，默认 true。仅做调研不需要布局时设 false |

返回格式

JSON 数组，每项结构如下：

[
{
"mpn": "STM32F103C8T6",
"mfgid": "8598",
"description": "ARM Cortex-M3 32位微控制器 72MHz 64KB Flash LQFP-48",
"datasheet": "//file.eda.cn/web2/M00/1B/31/pYYBAGGCZMuAXwY2AAV0cV9Yibc636.pdf"
}
]

渲染输出（给对话 UI 展示）：

1. STM32F103C8T6（mfgid：8598）— ARM Cortex-M3 32位微控制器 72MHz 64KB Flash LQFP-48
datasheet: https://file.eda.cn/web2/M00/1B/31/pYYBAGGCZMuAXwY2AAV0cV9Yibc636.pdf

datasheet 字段可能是协议相对 URL（// 开头），渲染时自动补 https: 前缀。

示例

pcb_parts_search { keyword: "STM32F103C8T6" }
→ [{ "mpn": "STM32F103C8T6", "mfgid": "8598", "description": "...", "datasheet": "..." }]

pcb_parts_search { keyword: "0402 10k resistor", page_size: 10 }
→ [{ "mpn": "RK73H1JTTD1003F", "mfgid": "8598", "description": "0402 10kΩ ±1% 贴片电阻", "datasheet": "..." }, ...]

pcb_parts_search { keyword: "LM358", require_eda_model: false }
→ [{ "mpn": "LM358", "mfgid": "...", "description": "双运算放大器", "datasheet": "..." }, ...]

边界行为

| 情况 | 处理 |
|---|---|
| 空关键词 | 报错：pcb_parts_search: keyword cannot be empty |
| 关键词 >200 字符 | 报错：pcb_parts_search: keyword too long (N > 200) |
| page_size 非整数或超出 1–50 | 报错：pcb-parts-search: pageSize must be an integer between 1 and 50 |
| page_size 非数字 | 回退默认值 5 |
| require_eda_model 非布尔 | 回退默认值 true |
| HTTP 非 200 | 报错：pcb-parts-search: HTTP  |
| 业务 code !== 200000 | 报错：pcb-parts-search: 接口返回异常:   |
| result 数组为空 | 返回空数组 []，渲染输出 No PCB parts matched the search criteria. |
| result[].queryPartVO.part 为 null | 过滤掉该项，不报错 |
| 器件字段缺失 | 回退为空串 ""，不出现 undefined |
| datasheet 为协议相对 URL | 渲染时补 https: 前缀；JSON 输出保留原始值 |
| 网络超时 | 15s 后工具超时，由 DSH 超时机制处理 |

关键词搜索 vs 精确查询

queryPage 的 desc 字段是模糊关键词匹配，不是 MPN 精确查询。传入 MPN 当关键词能搜到候选列表，但列表里可能混入型号相近的其他器件，顺序也不保证"精确匹配排最前"。需要精确定位到某一条时，调用方需自行在返回结果里按 mpn（建议大小写不敏感）+ mfgid 做二次过滤。

npm 0.1.0-rc.6 兼容

本插件遵循 DSH 0.1.0-rc.6（npm）依赖线：

- 类型/运行时：@deepseek-ai/cordis: ^4.0.1 + @deepseek-ai/dsh-tools: >=0.0.1-rc.1 =0.0.1-rc.1
一次性任务（headless）profile —— dsh run 默认使用 headless
dsh plugin --profile headless add

也可以先用 npm pack 打出 tarball 再安装：
sh
cd dsh-pcb-parts-search
npm install && npm pack
dsh plugin --profile web add ./deepseek-ai-dsh-tool-pcb-parts-search-.tgz
dsh plugin --profile headless add ./deepseek-ai-dsh-tool-pcb-parts-search-.tgz

包内 dsh.bundle.patch（指向 cordis.patch.yml）会在安装后自动把插件加入 profile 的 layer stack（row id：tool-pcb-parts-search）。插件缺失的 peer 依赖（@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-invariants）由 profile 的 healed profiles/node_modules 回退安装提供。
⚠️ web 与 headless 是不同 profile：web 安装不会自动覆盖 headless；dsh run 默认使用 headless profile。Windows 路径使用正斜杠（C:/...）。

验证安装
sh
dsh --profile web --dump-config | grep tool-pcb-parts-search

运行验证
sh
dsh run "使用 pcb_parts_search 工具搜索 STM32F103C8T6"

源码开发依赖链接

本插件 peer 依赖来自 DSH monorepo。源码开发时需链接依赖：
sh
Windows (PowerShell)
New-Item -ItemType Junction -Path "node_modules\cordis" -Target "C:\code\deepseek-harness\vendor\cordis" -Force
New-Item -ItemType Junction -Path "node_modules\@deepseek-ai\dsh-tools" -Target "C:\code\deepseek-harness\packages\core\tools" -Force
New-Item -ItemType Junction -Path "node_modules\@deepseek-ai\dsh-invariants" -Target "C:\code\deepseek-harness\packages\runtime-diagnostics\invariants" -Force

用法

安装后，agent 自动获得 pcb_parts_search 工具：

pcb_parts_search { keyword: "STM32F103C8T6", page_size: 10 }  →  [{ "mpn": "...", ... }]

工具名满足 DeepSeek 函数名约束（≤64 字符，[A-Za-z0-9_-]）。注册后自动进入 Code Mode SDK（await tools.pcb_parts_search(...)），canonical 返回值为 JSON 文本字符串。

已知限制

1. 仅支持关键词搜索：queryPage 的 desc 是模糊匹配，不是 MPN 精确查询；需要精确定位时调用方需自行二次过滤
2. 数据源单一：仅查询芯灵 eda.cn，不聚合 DigiKey / Mouser / LCSC 等其他元器件平台
3. 需要网络访问：工具会向 www.eda.cn 发送 HTTPS 请求，离线环境不可用
4. 接口可用性依赖第三方：eda.cn 服务不可用时工具会报错，无降级策略
5. 返回字段有限：只取 mpn / mfgid / description / datasheet，不包含库存、价格、封装尺寸等采购信息

测试
bash
npm test

- register.spec.ts：注册契约（AUDIT-CROSS-02 风格）——验证插件导出 name/inject/apply、工具注册名 pcb_parts_search、参数 schema、render 函数、timeout 配置

许可

MIT