datasheet-lens

datasheet-lens

datasheet-lens 是电子元器件数据手册的集中存储库。它会为每份数据手册只保存一份，并将其关联到使用它的项目。这样，项目中的每个人和每个 AI Agent 使用的都是同一份正确文档。

• 电子设计。 设计仓库中的项目文件 datasheet-lens.toml 会记录设计所用的元器件及其数据手册。datasheet-lens 会让这份清单与 CAD 项目（KiCad 和其他 EDA 工具）中的元器件保持一致。
• 软件和固件。 开发者及其 AI Agent 获取的数据手册与硬件团队相同：文档和修订版本都相同，而不是来自未知来源的副本。
• 两者共用一个来源。 硬件设计和软件可以共用一个项目文件，也可以各用一个包含相同元器件的项目文件。存储库通过 SHA-256 识别每个 PDF，因此两个项目使用的是同一份文档。

大模型 Agent 通过 MCP 服务读取数据手册。该工具不会将数据手册转换为文本。转换会产生看似正确的错误：上标丢失、表格行合并、列错位，以及从图表中读出错误数值。datasheet-lens 会建立索引以查找内容，并按需向模型提供原始页面和区域。模型只读取工作所需的部分，并从原文中读取每个数值。

状态：开发中（版本 0.3）。工具可以使用，也有测试。接口可能会发生变化。

功能

• 深入查阅文档。 索引（大纲、表格和图注、页面质量）、文本搜索、带有元素 ID 的页面地图，以及元素、区域、图注（例如“表 57”；使用 docling 时也包括跨多页的表格）或整页的图像，分辨率为 300 至 600 dpi。
• 集中存储，供所有项目共享。 每位用户有一个存储库（默认为 ~/.datasheet-lens），供所有设计项目使用。每个 PDF 只存储一次（按 SHA-256），并附带其索引、元素地图、元器件信息，以及会话从中读取的事实。一个项目添加的数据手册会立即供其他项目使用：不会再次下载、建立索引或读取。一个元器件可以有数据手册、手册和勘误表。
• 事实。 会话读取的数值会连同其来源（文档、页面、元素）一起保存，以便后续会话查找。
• 项目文件。 设计仓库中的 datasheet-lens.toml 会记录设计所用的元器件及其文档。团队成员可以通过仓库获取该文件。project_check 会将其与 CAD 项目的元器件进行比对。
• 可订购元器件。 数据手册中的订购代码，以及经销商官方 API 提供的生命周期状态、库存和价格（目前支持 Mouser）。不会进行网页抓取。
• 团队服务（可选）。 团队共用一个存储库，用于存放文档、元器件信息、事实，以及每份文档的索引和元素地图。每个人都保留一个可在离线状态下使用的本地存储库，并与服务同步。服务端（datasheet-lens[server]）提供带角色和令牌的账户；设置向导会安装 PostgreSQL、Garage 对象存储、nginx 和 Let's Encrypt 证书。

典型用途

datasheet-lens 可帮助管理设计项目的输入文档，并将其保存在代码库中。它能让 BOM 与 CAD 项目保持一致。它可以让 Agent 检查 BOM，并根据原始数据手册检查设计。

• 确保设计的数据手册齐全并纳入 Git，让团队中的每个人使用相同的数据手册。
• 将项目与 CAD 项目中的元器件进行比较，找出缺失、多余和不同的元器件。
• 为基础元器件选择具体可订购的 MPN，并确认其可以订购。
• 根据数据手册审查原理图：引脚、绝对最大额定值、逻辑电平和应用电路。
• 将封装与数据手册中的封装图进行比较。
• 为固件读取寄存器映射、位字段和时序值，并将其连同来源一起保存为事实。
• 在多个项目中使用相同的元器件：一个项目的数据手册和事实会同时在同一用户的其他项目中提供。

datasheet-lens 本身不会读取原理图。元器件来自 CAD 工具、其 MCP 服务或 BOM 文件。有关每种用法的步骤，请参阅 doc/use-cases.md。

安装

datasheet-lens 需要 Python 3.11 或更高版本，可在 Linux、macOS 和 Windows 上运行。

pipx install datasheet-lens
datasheet-lens init

datasheet-lens init 会创建中央存储区（默认为 ~/.datasheet-lens，也可以使用环境变量 DATASHEET_LENS_HOME 指定的文件夹）。它还可以安装 docling，以提供更完善的元素映射（表格和图）。docling 为可选项：需要数 GB 磁盘空间。不安装时，工具会使用文本层。

在 Claude Code 中注册 MCP 服务（stdio）：

claude mcp add --scope user datasheet-lens -- datasheet-lens-mcp

若要使用其他 MCP 客户端，请将命令 datasheet-lens-mcp 设置为不带参数。服务会向 Agent 提供操作说明。请参阅 doc/installation.md 和 doc/mcp-server.md。

快速入门

在设计代码库的根文件夹中：

datasheet-lens project init     # the project file, and a block in AGENTS.md, CLAUDE.md
datasheet-lens add PATH|URL     # add a datasheet; it proposes the MPN of the part
datasheet-lens sync             # copy the documents into the project folder
datasheet-lens check BOM.csv    # compare the project with a BOM of the CAD project

Agent 会通过 MCP 服务调用相同的功能。AGENTS.md 或 CLAUDE.md 中的代码块会告知 Agent 操作流程。project init 只会修改已存在的文件：如果需要添加代码块，请先创建其中一个文件。

命令	功能
add PATH|URL	将文档添加到存储区和项目中
ls、sync	显示项目，或同步其副本
check BOM.csv	将项目与 CAD 项目的 BOM（CSV）进行比较，并找出字段 MPN、Value 和 Value_Confirmed 的变更与冲突（仅使用 KiCad 和 Eagle 导出的 BOM 进行过测试）
set MPN -m NEW	更改项目元器件的 MPN、基础元器件、类别或制造商
rm MPN	从项目中移除元器件（或使用 -d DOC 移除文档）
search TEXT --part MPN	在某个元器件的文档中查找文本
codes DOC	显示数据手册中的可订购代码
links MPN	显示数据手册、库存、符号、封装和 3D 模型的搜索链接
find MPN	在分销商处查找元器件（生命周期、库存、价格）
stock	显示各项目元器件的生命周期状态和库存
key NAME	保存分销商的 API 密钥，或团队服务的令牌（key team）
server connect URL	将存储区连接到团队服务；server sync、server（状态）
dist NAME ...	选择分销商（全局选择，或使用 --local 仅为项目选择）

所有命令和选项请参阅 doc/cli.md。

每位用户都需要为每个分销商准备个人 API 密钥。请在 Mouser API Hub 免费获取 Mouser 密钥（Search API 密钥，而非 Cart API 密钥），然后运行 datasheet-lens key mouser。请参阅 doc/distributors.md。

文档

文档	内容
doc/installation.md	要求、安装、init、docling、存储位置、升级、卸载
doc/use-cases.md	典型用途、分步说明
doc/mcp-server.md	MCP 服务：注册、说明、所有工具
doc/agent-workflow.md	Agent 如何读取数据手册，附示例
doc/projects.md	项目文件、布局、同步、团队工作流、与 CAD 项目的一致性
doc/cli.md	所有 CLI 命令和选项的参考
doc/distributors.md	分销商数据、API 密钥、分销商选择、搜索链接
doc/team-server.md	团队服务：安装、账户和令牌、存储连接、同步、API
doc/architecture.md	面向开发者：设计决策和模块概览
doc/development.md	开发环境设置、测试、代码和文本风格

开发

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest

请参阅 doc/development.md。

许可证

MIT。请参阅 LICENSE。