OPC 将电子元器件网站上的分类、型号、规格、价格和库存整理为结构化数据，可用于元器件目录建设、选型资料整理和后续数据分析。
核心模块 component_agent 由按职责划分的 Agent 和 Coordinator 组成，提供网站识别、全站采集及旧版型号查询三个入口。当前流程基于规则、解析器和站点适配器运行，不需要配置 LLM API Key。
仓库还保留 ICkey、立创商城和 TI 的独立爬虫源码；这些历史脚本的依赖完整性与核心模块不同，详见支持范围。
| 能力 | 说明 |
|---|---|
| 网站识别与规划 | 识别分销商、制造商、商城等网站类型，有限探索页面并生成采集计划 |
| 分类与分页遍历 | 支持 DFS / BFS，以及 page、offset、cursor、Next 链接和浏览器 Next 控件 |
| 多来源解析 | 提取 JSON API、JSON-LD、嵌入状态及 HTML 中的商品数据 |
| 商品字段标准化 | 整理型号、厂商、封装、价格、库存和规格，保留原始属性与字段来源 |
| 断点续采 | 保存分类队列、商品种子与详情 checkpoint，恢复时跳过成功任务 |
| 分阶段验证 | ValidationAgent 检查目录、商品和最终结果，输出重试、重新规划或暂停建议 |
| 验证后发布 | 最终验证允许发布后才写入分类与商品结果，保留问题和任务日志供排查 |
| 可扩展站点适配 | 使用 SiteAdapter 补充站点规划、目录解析及详情策略 |
全站 Coordinator 在网络请求前检查 robots 策略；仅允许目录采集时，可使用 catalog_only 模式完成标准化。这项约束属于全站流程，旧版查询和独立脚本不共享全部机制。
需要 Python 3.10+。以下命令从仓库根目录执行，推荐使用虚拟环境。
git clone https://github.com/iiChole/OPC.git
cd OPC
python -m venv .venv
source .venv/bin/activate
# Windows PowerShell：.venv\Scripts\Activate.ps1
python -m pip install -e .基础安装包含 HTTP 请求和 HTML 解析依赖。需要动态页面或浏览器回退时，再安装：
python -m pip install -e '.[browser]'
python -m playwright install chromiumopc --decide-site ti.com该命令只输出网站分类与建议策略，不访问目标网站。也可以使用 python -m component_agent 替代 opc。
opc --crawl-site https://www.icgoo.net/ \
--max-categories 1 \
--delay 1.0 \
--no-browser \
--run-state-root outputs/sample命令选取一个分类，并尝试遍历该分类的全部分页，不等于只采集一个商品。结果和断点写入 outputs/sample/icgoo/；完成情况以 crawl_summary.json 和 validation.json 为准。
同一任务中断后，使用相同参数和输出目录重新运行即可读取断点。正式全量任务请去掉 --max-categories，并使用新的状态目录，例如 --run-state-root outputs/full，避免混用样本与全量任务的状态。
更多参数和恢复机制见全站采集指南。
opc --plan-site https://www.icgoo.net/ --delay 1.0 --no-browser有限探索分类入口、API 和分页方式，输出计划，不执行完整商品采集。仅通过 --decide-site 识别出某网站，不代表已完成该站点适配。
opc --query STM32F103C8T6 \
--fields price,stock,package,manufacturer \
--sites ickey,szlcsc,ti \
--max-results 5 \
--no-browser \
--output-dir outputs/queries查询入口使用 compat/ 下的历史适配器，按型号收集有限结果，输出到指定目录下的查询子目录。默认字段覆盖全部支持字段；实际获取情况取决于页面、网络及站点访问条件。它不调用根目录中的独立爬虫脚本。
flowchart TD
A[网站 URL] --> B[WebsiteDecisionAgent：网站识别]
B --> C[robots 策略检查]
C --> D[CrawlPlanAgent / SiteAdapter：采集计划]
D --> E[CatalogAgent：分类、分页、商品种子]
E --> F[ValidationAgent：目录异常检查]
F --> G[ProductAgent / CatalogOnlyProductAgent：商品标准化]
G --> H[ValidationAgent：商品与最终结果检查]
H --> I{允许发布?}
I -->|是| J[categories.json + products_final.json]
I -->|否| K[重试、重新规划或暂停并保留断点]
Agent 返回结构化结果和交接建议，由 Coordinator 负责调度与恢复。模块职责、数据契约及扩展方式见架构文档。
| 入口 / 站点 | 当前实现 | 边界 |
|---|---|---|
| 全站采集：ICGoGo | 内置 sitemap 与分类表格适配器，有离线端到端测试 | 采用 catalog_only，不承诺目录之外的实时价格和库存 |
| 全站采集：其他网站 | 通用规划、目录与详情解析流程 | 页面结构可能需要新增适配器，未逐站验证 |
| 型号查询：ICkey / 立创 / TI | 保留 compat 查询适配器 |
属于有限结果查询，线上可用性取决于站点状态 |
独立脚本：ickey/、szlcs/、ti/ |
保留分类、列表、详情及合并源码 | 当前缺少共享 SQLite 存储与传输模块，不能视为开箱即用 |
独立脚本的具体能力和缺失依赖见历史爬虫说明。项目处于实验阶段；自动化测试使用本地样例和模拟请求，不代表对所有目标站点完成实时验证。
全站流程默认写入 component_agent/run_state/<site>/；推荐通过 --run-state-root 指定工作目录。
| 文件 | 用途 |
|---|---|
robots.json、crawl_plan.json |
请求策略及采集计划 |
checkpoints.json、product_checkpoints.json |
分类进度、成功商品和待重试任务 |
product_seeds.jsonl、product_details.jsonl |
阶段间商品数据及详情历史 |
tasks.jsonl、issues.jsonl |
任务事件、异常和诊断线索 |
validation.json、crawl_summary.json |
验证结论与运行摘要 |
categories.json、products_final.json |
本轮最终验证通过后写入的结果 |
products_final.json 是商品对象数组，字段按实际来源填充：
| 字段组 | 代表字段 |
|---|---|
| 身份与分类 | site_key、category_id、sku、part_number、model |
| 规格与交易 | manufacturer、package、price、stock、moq、attributes |
| 语义与来源 | raw_attributes、normalized_attributes、field_provenance、source_url |
| 状态与诊断 | fetch_status、missing_fields、error、fetched_at |
缺失信息会保留为空值或记录为问题；目录模式不会生成页面中不存在的价格、库存。旧版查询的最终文件是包含 results、issues 和 diagnostics 的报告对象，与全站结果格式不同。
OPC/
├── component_agent/ # 核心 Python 包
│ ├── agents/ # 决策、计划、目录、商品与验证 Agent
│ ├── domains/ # 数据契约、解析器、分页和 checkpoint
│ ├── orchestration/ # 全站调度、robots 策略与恢复
│ ├── sites/ # 全站站点适配器
│ ├── compat/ # 历史型号查询与兼容入口
│ ├── tests/ # 离线回归测试
│ ├── cli.py # 公共命令行选项与全站执行逻辑
│ └── tools.py # HTTP / Playwright 工具
├── ickey/ # ICkey 独立爬虫源码
├── szlcs/ # 立创商城独立爬虫源码
├── ti/ # TI 独立爬虫源码
├── docs/ # 补充文档
├── .github/workflows/ # 自动化测试
├── pyproject.toml # 包元数据、依赖与 opc 命令
└── CONTRIBUTING.md # 开发与贡献指南
python -m pip install -e .
python -m unittest discover -s component_agent/tests -v欢迎通过 Issue 提交脱敏页面样例、解析问题或站点适配需求。提交代码前请阅读贡献指南。
仓库当前未提供 LICENSE 文件，尚未声明开源许可证。发布或分发时应先由维护者确定授权方式。