需要查询/采购电子元器件或批量同步数据手册时，用…

适用于按 MPN/关键词查元器件规格、价格、库存、封装，或为 KiCad 项目/MPN 列表批量下载并维护数据手册。

适用场景

解决思路

1. 在 digikey.com 创建 DigiKey 账号。
2. 在 developer.digikey.com 注册 API app：进入 My Apps → Create App；App name 任意；选择 Product Information v4；OAuth type 选 Client Credentials（2-legged，无需用户登录）；Callback URL 填 https://localhost；创建后记录 Client ID 和 Client Secret。
3. 运行脚本前设置环境变量：export DIGIKEY_CLIENT_ID=your_client_id_here 和 export DIGIKEY_CLIENT_SECRET=your_client_secret_here。
4. 若凭据存放在集中 secrets 文件（如 ~/.config/secrets.env），先加载：export $(grep -v '^#' ~/.config/secrets.env | grep -v '^$' | xargs)。
5. 获取 OAuth token：curl -s -X POST https://api.digikey.com/v1/oauth2/token -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=${DIGIKEY_CLIENT_ID}&client_secret=${DIGIKEY_CLIENT_SECRET}&grant_type=client_credentials"；响应中的 access_token 有效 10 分钟，缓存到 shell 变量并在同一会话复用；遇到 401 时重新认证。
6. 每个 API 请求都带必需 header：X-DIGIKEY-Client-Id: ${DIGIKEY_CLIENT_ID} 和 Authorization: Bearer <access_token>。
7. 可选 locale header：X-DIGIKEY-Locale-Language 可设为 en/ja/de/fr/ko/zhs/zht/it/es；X-DIGIKEY-Locale-Currency 可设为 USD/CAD/EUR/GBP/JPY 等；X-DIGIKEY-Locale-Site 可设为 US/CA/UK/DE 等。
8. 用 KeywordSearch 作为主搜索端点：POST /products/v4/search/keyword，按 MPN、DigiKey part number、描述或关键词搜索。
9. KeywordSearch 请求体字段：Keywords（string，最多 250 字符）；Limit（1-50）；Offset；FilterOptionsRequest 中 MinimumQuantityAvailable、SearchOptions（InStock、HasDatasheet、RoHSCompliant、NormallyStocking、Has3DModel、HasCadModel、HasProductPhoto、NewProduct）、ManufacturerFilter[].Id、CategoryFilter[].Id、StatusFilter[].Id、MarketPlaceFilter（NoFilter/ExcludeMarketPlace/MarketPlaceOnly）；SortOptions.Field 可取 Price、QuantityAvailable、Manufacturer、ManufacturerProductNumber、DigiKeyProductNumber、MinimumQuantity；SortOptions.SortOrder 可取 Ascending。
10. 解析 KeywordSearch 响应中 Products[] 的关键字段：ManufacturerProductNumber、Manufacturer、Description、UnitPrice、QuantityAvailable、ProductUrl、DatasheetUrl、PhotoUrl、ProductVariations（含 DigiKeyProductNumber、PackageType、StandardPricing[].BreakQuantity/UnitPrice/TotalPrice、QuantityAvailableforPackageType、MinimumOrderQuantity、StandardPackage）、Parameters、ProductStatus、Category、Classifications、Discontinued、EndOfLife、NormallyStocking。
11. 用 ProductDetails 获取单个料号完整信息：GET /products/v4/search/{productNumber}/productdetails；{productNumber} 可为 DigiKey part number 或 manufacturer part number；可用查询参数 manufacturerId 区分匹配多个厂商的同名 MPN（如 CR2032）。
12. 按需使用其他端点：GET /products/v4/search/{pn}/productpricing 查含 MyPricing 的价格；GET /products/v4/search/{pn}/media 查所有媒体（图片、datasheets）；GET /products/v4/search/manufacturers 查厂商 ID；GET /products/v4/search/categories 查分类 ID；GET /products/v4/search/{pn}/alternatepackaging 查替代包装；GET /products/v4/search/{pn}/substitutions 查替代料；GET /products/v4/search/{pn}/recommendedproducts 查推荐/关联料。
13. 遵守速率限制：每分钟和每日配额适用；超过时返回 HTTP 429 并带 Retry-After header，按该 header 等待。
14. 解析错误响应：所有错误返回 DKProblemDetails，字段包括 type、title、status、detail、correlationId。
15. 若 API 凭据不可用或认证失败，回退抓取 DigiKey 网页：https://www.digikey.com/en/products/result?keywords=<url-encoded-query>；按 MPN 示例 https://www.digikey.com/en/products/result?keywords=GRM155R71C104KA88D，按规格示例 https://www.digikey.com/en/products/result?keywords=100nF+0402+X7R+16V；在商品表行中找 DigiKey part number、MPN、描述、单价、库存、datasheet 链接；若结果截断或为空，改用精确 MPN 搜索而非关键词。
16. 数据手册下载优先用 DigiKey API 的直接 PDF URL，避免网页抓取并得到可靠稳定链接；其他 kicad、bom 等 skill 应把 DigiKey API 作为首选 datasheet 来源。
17. 用 sync_datasheets_digikey.py 维护 KiCad 项目旁的 datasheets/ 目录：从 schematic 提取元件，搜索 DigiKey datasheet URL，下载缺失 PDF，并写 manifest.json；后续运行增量，只获取新增或变化的部分。
18. sync_datasheets_digikey.py 常用命令：python3 <skill-path>/scripts/sync_datasheets_digikey.py <file.kicad_sch>；--dry-run 预览将下载内容；--force 重试此前失败下载；-o ./my-datasheets 自定义输出目录；analyzer_output.json 使用预计算 analyzer JSON；--parallel 3 并行下载；--mpn-list mpns.txt --output ./datasheets 从纯 MPN 列表批量同步且无需 KiCad 项目。
19. MPN-list batch mode：文件一行一个 MPN；空行和 # 注释（整行及行内）跳过；用 is_real_mpn() 过滤非 MPN 字符串（如 100nF 或 DNP）并去重；省略 --output 时默认输出到当前工作目录 ./datasheets/。
20. sync_datasheets_digikey.py 行为：自动运行 kicad schematic analyzer 提取元件和 MPN；过滤没有真实 MPN 的通用无源件（如 100nF、10K）；先尝试 schematic URL（KiCad symbol 内嵌 datasheet URL）再打 DigiKey API 以节省 API 调用；写 manifest.json 映射每个 MPN 到 PDF 文件、制造商、描述、下载状态和 URL，kicad skill 在设计审查时读取；记录失败及错误，后续不重试除非 --force；DigiKey API 调用间隔 1 秒，可用 --delay 配置；增量保存进度，中断时保留已下载文件。
21. manifest.json 结构包含：schematic、last_sync、parts[MPN] 下的 file、manufacturer、description、datasheet_url、status、references、size_bytes。
22. 单次数据手册下载用 fetch_datasheet_digikey.py：python3 <skill-path>/scripts/fetch_datasheet_digikey.py --search "TPS61023" -o datasheet.pdf；直接 URL 下载 python3 <skill-path>/scripts/fetch_datasheet_digikey.py "https://www.ti.com/lit/gpn/tps61023" -o datasheet.pdf；JSON 输出 python3 <skill-path>/scripts/fetch_datasheet_digikey.py --search "ADP1706" --json。
23. fetch_datasheet_digikey.py 行为：OS-agnostic，使用 Python requests，未安装 requests 时回退 urllib；规范化重定向 URL，TI 的 DatasheetUrl 指向 JS 重定向页时提取直接 PDF 链接，并修复协议相对 URL //mm.digikey.com/...；设置正确浏览器 User-Agent；校验 PDF header，前 4 字节应为 %PDF；Microchip 主 URL 失败时尝试已知替代 URL 模式；若安装 playwright，则最后用 headless Chromium 处理通过 JavaScript 提供 PDF 的站点（Broadcom doc viewer、Espressif download redirects），拦截下载事件并直接读取 response bodies。
24. fetch_datasheet_digikey.py 退出码：0 成功，1 下载失败，2 搜索/API 错误；依赖：pip install requests（强烈推荐；urllib 回退无法处理 analog.com 等 HTTP/2 站点）；可选 pip install playwright && playwright install chromium（启用 headless browser fallback）。
25. 参考厂商兼容性并采取对应做法：TI 需 URL normalization 去 JS redirect wrapper；ADI/Analog 用 requests 透明处理 HTTP/2；STMicro、Nexperia、Lite-On、Molex 需 User-Agent header；Renesas、ON Semi、NXP、Diodes Inc、Microchip 可直接下载；YAGEO、Samsung、Murata 使用 DigiKey 托管 PDF（mm.digikey.com）；Broadcom、Espressif 需 Playwright；Lattice 部分 URL 需要 cookies/auth。
26. 下载失败（exit code 1）时告诉用户并提供 URL，让用户用真实浏览器打开并保存到本地，然后读取和分析；--json 输出即使失败也始终包含 datasheet_url 字段，可程序化提取 URL。
27. 手动下载 workflow：先用 KeywordSearch 或 ProductDetails 搜索；从 API 响应提取 DatasheetUrl；规范化 URL，若以 // 开头则前加 https:，若包含 ti.com/general/docs/suppproductinfo 则提取 gotoUrl 查询参数；用 requests（Python）或 wget/curl 并带浏览器 User-Agent 下载；验证前 4 字节为 %PDF。
28. 如果 DatasheetUrl 为空或所有下载方法失败：把 URL 提供给用户手动浏览器下载；尝试 /products/v4/search/{pn}/media 端点获取替代媒体链接；最后用 web search，例如 "<MPN> datasheet filetype:pdf"。
29. 分析 datasheet 用于 KiCad 设计审查时提取：Absolute maximum ratings（电压、电流、温度限制）；Recommended operating conditions；Pinout and pin descriptions，用于对照 KiCad symbol；Package dimensions，用于对照 KiCad footprint；Typical application circuit，用于对照用户 schematic；Thermal characteristics（θJA、θJC）用于功耗计算；Electrical characteristics（Vout、Iq、PSRR 等关键参数）。
30. 选料时注意 DigiKey part number 后缀：-ND 标准，-1-ND cut tape，-2-ND digi-reel，-6-ND full reel；用 ExcludeMarketPlace 过滤第三方卖家列表；检查 ProductVariations[].StandardPricing[] 中 BreakQuantity 价格档；选择料号前检查 ProductStatus、Discontinued、EndOfLife。

适用边界 · 注意事项

• 生产订单/量产采购不应以 DigiKey 为主；生产订单应看 lcsc/jlcpcb，BOM 管理和导出工作流应走 bom skill。
• 没有 DigiKey API 凭据、OAuth 配置失败或账号不可用时，不能依赖 API；只能回退网页抓取，且 DigiKey 页面 JS-heavy、结果可能嘈杂、截断或为空。
• 部分厂商站点（如 Lattice、TDK InvenSense）需要交互登录、cookies 或 CAPTCHA，即使有 Playwright 也可能无法自动下载，应让用户用浏览器手动保存。