内容
# 视觉电子索引
代理辅助的电子元件/PCB 照片索引。该软件包使用 Cloudflare Workers AI 处理图像，提取可见的 IC/封装标记，准备元件以进行数据表查找，并生成丰富的库存 CSV 文件。它旨在与编码代理一起使用，以填充数据，并通过以下方式提供工具：Pi 和用于其他代理的替代 MCP 服务器。
典型流程：
```text
照片 -> 视觉提取 -> 原始 JSON + 证据 -> 代理数据表验证 -> inventory.csv
```
视觉步骤不会执行数据表查找或发明元件详细信息。数据表丰富由带有网络搜索/浏览器工具的 Pi 代理或手动审查处理。
## 我应该使用哪种设置？
- **使用 Pi？** 使用 `pi install npm:vision-electronic-indexing-pi` 安装软件包，然后运行 `/vision-inventory-setup`。
- **使用 Claude Code、Codex CLI、OpenCode、Cursor 或另一个 MCP 兼容的工具？** 在 `.universal/scripts/quick-install.sh` 中使用推荐的通用安装程序。
- **使用纯 Python 或手动 MCP 配置？** 安装 `requirements.txt`，配置 Cloudflare 凭证，然后直接运行 `vision_inventory_mcp.py`。
## 使用 Pi 进行快速设置
### 1. 安装 Pi 软件包
```bash
pi install npm:vision-electronic-indexing-pi
```
### 2. 计划数据表网络搜索
数据表丰富需要单独的 Pi 网络搜索或浏览器工具/技能。该软件包故意不包含一个，并且不尝试自动检测一个，因为检测不可靠。
可接受的能力示例：
- 一个 Brave/search Pi 技能
- 一个浏览器自动化技能
- 另一个受信任的网络搜索扩展/工具
如果没有可用的搜索/浏览器功能，工作流程仍然可以生成 `parts_to_lookup.json`，但无法验证数据表。手动填写 `datasheet_cache.json`。
### 3. 配置 Cloudflare 凭证
启动 Pi 并运行：
```text
/vision-inventory-setup
```
设置命令使用配置的 `python3` 命令检查 Python 依赖项，提供使用 `python3 -m pip install -r requirements.txt` 安装缺少的软件包，警告数据表丰富需要单独的网络搜索/浏览器功能，并在第一次提示 Cloudflare Workers AI API 令牌凭证。
凭证存储在：
```text
~/.pi/agent/vision-inventory/credentials.json
```
当支持时，文件以 `chmod 600` 写入。令牌输入可能会根据您的 Pi UI 可见；避免在屏幕共享时输入凭证。
要更改凭证：
```text
/vision-inventory-credentials
```
环境变量也起作用，并覆盖存储的凭证：
```bash
export CLOUDFLARE_ACCOUNT_ID=your_account_id
export CLOUDFLARE_AUTH_TOKEN=your_workers_ai_api_token
# CLOUDFLARE_API_TOKEN 也被接受为别名：
export CLOUDFLARE_API_TOKEN=your_workers_ai_api_token
```
可选模型覆盖：
```bash
export WORKERS_AI_MODEL=@cf/meta/llama-4-scout-17b-16e-instruct
```
## 其他工具 / 通用 MCP 兼容性
_由用户 [@Brun0-v](https://github.com/Brun0-V) 贡献_
该存储库还包括 `.universal/` 中的一个与工具无关的兼容性层，用于 OpenCode、Claude Code、Codex CLI、Cursor 和类似客户端等 MCP 兼容的编码代理。
通用层不会取代 Pi 软件包集成。Pi 用户应继续使用上述命令。
对于其他工具，请使用通用安装程序：
```bash
curl -fsSL https://raw.githubusercontent.com/Pichi-Cell/vision-electronic-indexing-mcp/main/.universal/scripts/quick-install.sh -o /tmp/vei-install.sh && bash /tmp/vei-install.sh
```
这安装到 `~/.vei/`，设置 Python 虚拟环境，提示 Cloudflare Workers AI API 令牌凭证，安装代理技能，并 **自动配置代理设置中的 MCP 服务器**。**需要 MCP 兼容的代理**（OpenCode、Claude Code、Codex CLI、Cursor 等）。
警告：一些 MCP 客户端以纯文本 JSON 配置文件存储环境变量。优先使用 shell 环境变量或代理的秘密存储（如果可用）。
其他工具也可以直接连接到 Python MCP 服务器：
```bash
python3 /path/to/vision-electronic-indexing-mcp/vision_inventory_mcp.py
```
### 1. 手动设置：安装 Python 依赖项
从存储库根目录：
```bash
python3 -m pip install -r requirements.txt
# 可选的 iPhone HEIC/HEIF 照片：
# python3 -m pip install pillow-heif
```
### 2. 配置 Cloudflare 凭证
将 `.env.example` 复制到存储库根目录中的 `.env`:
```bash
cp .env.example .env
# 编辑 .env 并设置 CLOUDFLARE_ACCOUNT_ID 和 CLOUDFLARE_AUTH_TOKEN
# CLOUDFLARE_AUTH_TOKEN 应该是您的 Cloudflare Workers AI API 令牌。
```
或者，将凭证直接放入工具的 MCP 服务器配置中。请注意，许多工具配置存储这些值在纯文本中。
### 3. 将 MCP 服务器添加到工具
示例配置片段在：
```text
.universal/configs/opencode.json.example
.universal/configs/claude.json.example
.universal/configs/codex.json.example
.universal/configs/cursor.json.example
```
每个配置都应指向存储库根目录中的服务器文件，例如：
```json
{
"mcpServers": {
"vision-inventory": {
"command": "python3",
"args": ["/path/to/vision-electronic-indexing-mcp/vision_inventory_mcp.py"],
"env": {
"CLOUDFLARE_ACCOUNT_ID": "your_cloudflare_account_id",
"CLOUDFLARE_AUTH_TOKEN": "your_cloudflare_workers_ai_api_token"
}
}
}
}
```
`.universal/configs/*.json.example` 文件是严格的 JSON；将适当的文件复制到工具配置位置并调整路径/凭证。OpenCode 使用特定于工具的 `mcp` 形状；其他示例使用 `mcpServers`。
较旧的 `.universal/setup/install.sh` 和 `.universal/setup/install.ps1` 脚本是手动/旧版帮助程序。优先使用 `.universal/scripts/quick-install.sh` 进行自动通用设置。
原始 MCP 服务器公开这些工具名称：
| 工具 | 用途 |
|---|---|
| `process_image` | 分析一张电子/PCB 图片。 |
| `process_image_folder` | 分析一个受支持的图片文件夹。 |
| `save_inventory` | 将库存输出保存为 JSON 或快速 CSV 导出。使用批处理工作流程获取完整的 BOM/证据输出。 |
### 4. 安装通用技能/提示（如果工具支持）
通用工作流程资产可在：
```text
.universal/skills/vision-inventory-workflow/SKILL.md
.universal/prompts/vision-inventory-agent-bom.md
```
将它们复制到工具特定的技能/提示位置。技能指示代理运行确定性工作流程，读取 `parts_to_lookup.json`，使用网络搜索验证数据表，填充 `datasheet_cache.json`，使用 `--skip-vision` 重新生成 CSV，并总结不确定性。
确定性工作流程命令与手动 shell 工作流程相同：
```bash
python3 scripts/inventory_folder_to_csv.py ./photos ./output
python3 scripts/inventory_folder_to_csv.py ./photos ./output --skip-vision
```
数据表丰富仍然需要代理中的单独网络搜索/浏览器功能。该软件包不包含此功能。
## 推荐的工作流程
### 1. 拍照
拍摄 IC 组或 PCB 部分的清晰、近距离的照片。裁剪的、光线充足的 IC 近景比整个电路板的照片更适合 OCR。
示例文件夹：
```text
photos/
image_001.jpeg
image_002.jpeg
image_003.jpeg
```
### 2. 运行完整代理工作流程
在 Pi 中：
```text
/vision-inventory-agent-bom ./photos ./output
```
在其他工具中：
```text
/vision-inventory-workflow ./photos ./output
```
有用选项：
```text
/vision-inventory-agent-bom ./photos ./output --recursive
/vision-inventory-agent-bom ./photos ./output --limit 3
/vision-inventory-agent-bom ./photos ./output --segment-ics
/vision-inventory-agent-bom ./photos ./output --max-side 0 --jpeg-quality 85
```
代理工作流程将：
1. 运行图像处理批处理脚本。
2. 编写原始 JSON 文件以进行审计。
3. 构建 `parts_to_lookup.json`。
4. 搜索数据表，优先使用官方制造商来源。
5. 填充 `datasheet_cache.json`。
6. 使用 `--skip-vision` 重新运行 CSV 生成。
7. 总结 BOM 并列出不确定的行。
### 3. 审查输出
生成的文件：
```text
output/
raw/ # 一个原始 JSON 结果对应一个图像
parts_to_lookup.json # 需要数据表查找的零件/证据
datasheet_cache.template.json # 丰富模板
datasheet_cache.json # 代理/用户填充的丰富缓存
inventory.csv # 净化后的最终 BOM
inventory_evidence.csv # 每个图像/每个候选证据行
```
始终审查以下行：
```text
needs_review=true
verified=false
```
还应审查带有提及 `Visual same-as hypothesis` 的注释的行；这些行包括一个或多个无法读取的 IC，计数基于封装/布局相似性而非直接标记 OCR。
## CSV 输出列
`inventory.csv` 按 `normalized_part` 净化，这是从视觉 `likely_part` 和数据表丰富中得出的主要/最终零件编号列。多个图像或来自一个图像的多个候选可以合并为一个 BOM 行，当它们解析为相同的 `normalized_part` 时。
列：
| 列 | 描述 |
|---|---|
| `normalized_part` | 主要净化键/最终零件编号，通常来自数据表丰富，基于视觉 `likely_part`。 |
| `candidate_parts` | 从视觉标记中提取的候选零件编号。 |
| `amount` | 合并的 BOM 行的估计数量。 |
| `sighting_count` | 合并到此 BOM 行的证据行数。 |
| `description` | 简短的数据表验证描述。 |
| `datasheet_url` | 用于丰富的数据表/来源 URL。 |
| `manufacturer` | 验证或可能的制造商。 |
| `verified` | 仅当数据表匹配被验证时为 `true`。 |
| `vision_confidence` | 为该行观察到的视觉/OCR 置信度值。 |
| `needs_review` | 当 OCR 或数据表丰富不确定时为 `true`。 |
| `images` | 贡献于此行的源图像。 |
| `observed_markings` | 在封装上看到的原始可见标记。 |
| `raw_json` | 用作证据的原始 JSON 文件。 |
| `notes` | 数据表/丰富注释或不确定性解释。 |
`inventory_evidence.csv` 保留用于构建 BOM 的非净化证据行。单个照片可以产生多个证据行，当它包含多个不同的 IC 时。
## 命令和工具
### Pi 命令
```text
/vision-inventory-setup
/vision-inventory-credentials
/vision-inventory-restart
/vision-inventory-bom <image_folder> <output_dir> [options]
/vision-inventory-agent-bom <image_folder> <output_dir> [options]
```
命令摘要：
| 命令 | 用途 |
|---|---|
| `/vision-inventory-setup` | 配置凭证并检查依赖项。 |
| `/vision-inventory-credentials` | 更改存储的 Cloudflare 凭证。 |
| `/vision-inventory-restart` | 重启本地视觉桥接进程。 |
| `/vision-inventory-bom` | 仅运行确定性的图像到 CSV 工作流程。 |
| `/vision-inventory-agent-bom` | 运行完整代理辅助工作流程，包括数据表丰富。 |
### Pi 工具暴露给代理
| 工具 | 用途 |
|---|---|
| `vision_inventory_process_image` | 分析一张电子/PCB 图片。 |
| `vision_inventory_process_folder` | 分析一个受支持的图片文件夹。 |
| `vision_inventory_save` | 将库存输出保存为 JSON 或快速 CSV 导出。对于完整 BOM 工作流程，请使用 `/vision-inventory-bom` 或 `scripts/inventory_folder_to_csv.py`。 |
## 手动 shell 工作流程
您可以在不使用 Pi 命令的情况下运行确定性工作流程：
```bash
python3 -m pip install -r requirements.txt
python3 scripts/inventory_folder_to_csv.py ./photos ./output --validate-setup
python3 scripts/inventory_folder_to_csv.py ./photos ./output
# 可选：在 OCR 之前裁剪暗 IC 类封装，有助于 IC 具有混合方向。
python3 scripts/inventory_folder_to_csv.py ./photos ./output --segment-ics
```
然后手动或使用代理填充 `output/datasheet_cache.json`，并在不重新处理图像的情况下重新生成 CSV：
```bash
python3 scripts/inventory_folder_to_csv.py ./photos ./output --skip-vision
```
## 无 Cloudflare 演示和示例输出
基于固定装置的演示在：
```text
examples/no-cloudflare-demo/
```
在没有 Cloudflare 凭证的情况下运行它：
```bash
python3 scripts/inventory_folder_to_csv.py ./examples/no-cloudflare-demo/photos ./examples/no-cloudflare-demo/output --skip-vision
```
演示包括模拟的原始视觉 JSON，一个小的 `datasheet_cache.json` 和生成的示例输出：
```text
examples/no-cloudflare-demo/output/parts_to_lookup.json
examples/no-cloudflare-demo/output/datasheet_cache.json
examples/no-cloudflare-demo/output/inventory.csv
examples/no-cloudflare-demo/output/inventory_evidence.csv
```
使用这些文件在运行实际图像分析之前了解预期的输出形状。
## Python 要求
建议使用 Python 3.10 或更高版本。
`requirements.txt` 中约束了可重复安装的所需版本：
```text
mcp>=1.0,<2.0
requests>=2.31,<3.0
pillow>=10.0,<12.0
python-dotenv>=1.0,<2.0
```
安装：
```bash
python3 -m pip install -r requirements.txt
```
可选的 iPhone HEIC/HEIF 支持：
```bash
python3 -m pip install pillow-heif
```
支持的图像格式：
```text
.jpg .jpeg .png .webp .bmp .gif .heic .heif
```
HEIC/HEIF 需要 `pillow-heif`。
## 图像处理的工作原理
在将图像发送到 Cloudflare Workers AI 之前，Python 服务器：
1. 使用 Pillow 打开图像。
2. 应用 EXIF 方向修正。
3. 默认情况下发送完整分辨率；仅当设置 `max_side` 为正值且图像大于该限制时才进行调整大小。
4. 将透明度转换为白色背景。
5. 将图像转换为 RGB。
6. 将其编码为 JPEG。
7. 将其作为 base64 图像数据 URL 发送。
默认值：
```text
max_side: 0（完整分辨率）
jpeg_quality: 85
model: @cf/meta/llama-4-scout-17b-16e-instruct
```
## 多 IC 和视觉相同行为
图像可能包含一个 IC 或多个不同的 IC。工作流程不会强制一个图像中的所有可见 IC 共享相同的标记或零件系列。
视觉提示要求模型在 IC 共享封装/主体大小、方向、引脚数和电路板区域时分配视觉组。如果无法读取的 IC 在视觉上与附近重复的可读 IC 非常相似，则原始 JSON 可能包括 `possible_same_as_likely_part` 假设。
重要：视觉相同仅是一种数量/分组假设。无法读取的 IC 保留 `package_marking="unreadable"`，保留 `likely_part="unknown"`，并强制 `needs_review=true`。当置信度高时，批处理 CSV 可以在添加注释的情况下将其计入视觉匹配的零件下，例如 `Visual same-as hypothesis for unreadable IC(s): ...`。
批处理工作流程为每个图像/候选零件构建一个证据行，因此一张照片可以贡献多个 BOM 行。
对于某些 IC 标记相对于其他标记上下颠倒或旋转的照片，请使用 `--segment-ics`。这启用了一个仅使用 Pillow 的分割预传递，检测暗 IC 类矩形封装，将裁剪写入 `output/crops/`/`，并发送每个裁剪块的检查 0/90/180/270 度旋转的指令。分段裁剪的提交被调整为 `max_side=250`，与完整图像的 `--max-side` 设置无关。如果未为图像找到类似 IC 的裁剪，则工作流程将恢复为使用完整图像。
默认情况下，分段裁剪会被上下文遮蔽：检测到的 IC 主体像素以外的像素以及小焦点填充都会被漂白后保存裁剪块。这可以防止部分相邻 IC 在裁剪边缘被计为单独零件。如需调试或保留周围上下文，请仅在需要时使用 `--no-segment-mask-context`。
分段增加了 API 调用，因为每个裁剪块都单独处理。如有需要，可以使用 `--segment-max-crops`、`--segment-dark-threshold`、`--segment-detection-max-side`、`--segment-padding-ratio` 和 `--segment-focus-padding-ratio` 调整检测。
这提高了混合 IC 照片、重复逻辑芯片和旋转封装的处理能力，但 OCR 仍可能遗漏、合并或误读小标记。需要准确性时，请查看原始 JSON 和证据行。
## 数据表丰富规则
代理应：
- 优先使用官方制造商数据表或产品页面。
- 保持描述简短。
- 如果精确的候选搜索失败，但官方结果强烈表明可能的 OCR 校正，则保留原始候选作为 `datasheet_cache.json` 键，并将 `normalized_part` 设置为官方数据表零件编号。
- 示例：如果 `SN74AS283N` 没有官方数据表，但官方 TI 结果与 `SN74LS283N` 匹配，并且图像可能混淆字符，则使用键 `SN74AS283N`，将 `normalized_part` 设置为 `SN74LS283N`，并在 `notes` 中提及校正。
- 仅当官方源证据和视觉/封装上下文使校正高度可能时，将 `verified` 设置为 `true`。
- 如果标记、零件编号、封装或源不确定，则将 `verified` 设置为 `false`。
- 不要发明零件编号、制造商、电压、功能或数据表网址。
示例 `datasheet_cache.json` 条目：
```json
{
"MAX232N": {
"normalized_part": "MAX232N",
"description": "MAX232N 双 EIA-232/RS-232 驱动器接收器 5V DIP",
"datasheet_url": "https://www.ti.com/lit/ds/symlink/max232.pdf",
"manufacturer": "Texas Instruments",
"verified": true,
"notes": "已针对 TI 数据表验证。"
}
}
```
## 本地 MCP 服务器详细信息
在内部，视觉步骤由 `vision_inventory_mcp.py` 实现，这是一个本地 Python MCP 标准输入/输出服务器。Pi 扩展程序惰性启动此服务器，并将其功能公开为 Pi 工具。
MCP 工具：
| MCP 工具 | 用途 |
|---|---|
| `process_image` | 分析一张图像并返回结构化的可见库存数据。 |
| `process_image_folder` | 分析文件夹中的所有受支持图像。 |
| `save_inventory` | 将库存输出保存为 JSON 或快速 CSV 导出。使用 `scripts/inventory_folder_to_csv.py` 获取完整的 BOM/证据工作流程。 |
直接为兼容的 MCP 客户端运行：
```bash
python3 vision_inventory_mcp.py
```
示例 MCP 客户端配置：
```json
{
"mcpServers": {
"vision-inventory": {
"command": "python3",
"args": ["/path/to/vision_inventory_mcp.py"],
"env": {
"CLOUDFLARE_ACCOUNT_ID": "your_cloudflare_account_id",
"CLOUDFLARE_AUTH_TOKEN": "your_cloudflare_workers_ai_api_token"
}
}
}
}
```
## 错误处理
服务器在可能的情况下返回结构化错误，例如：
```json
{
"error": true,
"message": "缺少 CLOUDFLARE_ACCOUNT_ID 环境变量。"
}
```
已处理的情形包括：
- 缺少 Cloudflare 凭证。
- 无效的图像路径。
- 不受支持的图像扩展名。
- 图像预处理失败。
- Cloudflare API 错误。
- 模型返回的无效 JSON。
- 缺失或无效的文件夹。
- 保存/写入失败。
## 限制
- 视觉模型可能会误读小型、模糊或低对比度的 IC 标记。
- 裁剪的近景通常比提示更改更有帮助。
- 数据表丰富程度取决于安装的网络搜索/浏览器工具的质量。
- 仍应审查官方数据表以获取重要工作。
- 工作流程按标准零件编号去重，而不是按物理元件身份在重叠照片之间去重。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器