EcoLink 批量搜索

批量调用 EcoLink 服务器原始匹配 API 搜索碳足迹数据库（ecoinvent + CPCD + GHG因子库），LLM 功能在本地执行（走用户自己的 API 余额），生成结构化结果文件。

架构

用户输入 → Skill脚本
         ├─ /api/search/raw（服务器只查库，零LLM费用）
         ├─ 本地LLM: 翻译 + 别名 + 复合材料判断
         ├─ 本地LLM: 化学品分解（无直接匹配时）
         ├─ 本地LLM: 替代品推荐（分解也无结果时）
         └─ 生成 CSV/Excel 结果文件

完整搜索管道（与网页端 app.py 对齐）

| 步骤 | 功能 | LLM | 对应 app.py 函数 | |------|------|-----|-----------------| | 1 | 材料分析：翻译 + 别名 + 复合材料判断 | 用户余额 | llm_analyze_material() | | 2 | 数据库匹配：中文 + 英文 + 别名多路搜索 | 无（服务器） | local_search() + search_cpcd() + search_ghg_factor() | | 2a | [--strict] 验证相关性 + 重试 | 用户余额 | llm_validate_results() | | 2b | [--strict] 逐条过滤不相关结果 | 用户余额 | llm_filter_results() | | 3 | 化学品分解：分子式 + 组分 + 质量比 + 反应方程式 | 用户余额 | llm_decompose_chemical() | | 4 | 替代品推荐：同类具体产品，黑名单过滤 | 用户余额 | llm_suggest_alternatives() | | 5 | 原因说明：每个结果附带匹配原因 | 含在步骤1中 | reason 字段 |

前置要求

Python 3.8+
requests 库
openpyxl 库（仅 Excel 输入/输出时需要）

工作流程

Step 1: 获取输入

支持三种方式：

文本列表: 用户直接列出产品名称（逗号分隔）
Excel文件: 用户上传 Excel，读取指定列
CSV文件: 用户上传 CSV，读取指定列

如用户提供文件，先读取确认列名。

Step 2: 获取 LLM 配置（需用户授权）

安全要求：

API Key 必须由用户显式提供，不得自动从环境变量读取
API URL 仅限官方域名（openrouter.ai / api.openai.com / api.deepseek.com 等），脚本内置白名单校验
向用户说明 LLM 调用会消耗其 API 余额，确认后再执行

获取方式：

询问用户：「批量搜索需要调用 LLM 进行翻译和分析，会消耗您的 API 余额。请提供您的 LLM API Key，或选择 --no-llm 纯匹配模式（零费用）。」
用户可使用 Agent 当前已配置的 API Key（用户主动提供）
默认 API URL：https://openrouter.ai/api/v1/chat/completions（用户可指定其他官方域名）

Step 3: 确认其他配置

以下配置有合理默认值，除非用户明确要求修改，否则直接使用默认值：

| 配置项 | 默认值 | 说明 | |--------|--------|------| | 输出格式 | csv | csv 或 excel | | 每库取前N条 | 3 | 每个数据库返回的结果数 | | 请求间隔 | 0.5s | 防止服务器过载 | | 严格模式 | 关闭 | 加 --strict 开启（费用翻倍，质量与网页端一致） |

Step 4: 执行批量搜索

Agent 使用用户提供的 API Key 执行脚本：

# 文本列表 + LLM
python skill/scripts/batch_search.py \
  --input "钢材,水泥,PVC,R401C" \
  --output results.csv \
  --api-key "sk-or-用户提供的key"

# 严格模式（与网页端完全一致，含LLM验证+逐条过滤，费用约翻倍）
python skill/scripts/batch_search.py \
  --input "钢材,水泥,PVC" \
  --output results.csv \
  --api-key "sk-or-用户提供的key" --strict

# Excel文件 + LLM
python skill/scripts/batch_search.py \
  --file products.xlsx --column "产品名称" \
  --output results.xlsx --format excel \
  --api-key "sk-or-用户提供的key"

# 纯匹配模式（不调LLM，零费用）
python skill/scripts/batch_search.py \
  --input "PVC,R401C" \
  --output results.csv --no-llm

Step 5: 交付结果

展示摘要统计 + 结果文件路径。

输出文件结构

| 列名 | 说明 | |------|------| | 搜索词 | 用户输入的原始产品名称 | | 结果类型 | direct / composite / decomposition / alternative | | AI翻译 | LLM 翻译的英文名 | | 数据来源 | ecoinvent / CPCD / GHG因子库 | | 产品名称 | product_name / fuel_type（复合/分解结果带组分前缀） | | Activity名称 | ecoinvent 专属 | | 型号 | CPCD 专属 | | 地理区域 | ecoinvent 专属 | | 碳足迹/因子值 | 核心数值 | | 单位 | 因子单位 | | 质量评分 | 数据质量评分 | | 功能单元 | CPCD 专属 | | 数据年份 | CPCD 专属 | | 匹配原因 | AI 给出的匹配/推荐原因 | | 说明 | CPCD 专属（数据说明） | | 专家点评 | CPCD 专属 |

结果类型说明

| 类型 | 含义 | 触发条件 | |------|------|---------| | direct | 直接匹配 | 中文名/英文名/别名在数据库中找到匹配 | | composite | 复合材料 | LLM 判断为复合材料，拆解各组分分别搜索 | | decomposition | 化学分解 | 直接匹配无结果，LLM 分解为化学组分并搜索 | | alternative | 替代品推荐 | 分解也无结果，LLM 推荐同类具体产品 |

`--no-llm` 模式

不调用任何 LLM API，零费用：

直接用中文搜索数据库，不做翻译
适合产品名本身就是英文/型号（如 PVC、R401C）或已知精确名称

`--strict` 严格模式

与网页端搜索管道完全一致，额外增加两个 LLM 步骤：

| 步骤 | 功能 | 对应 app.py 函数 | |------|------|----------------| | 验证相关性 | LLM 判断结果是否真正相关，不相关则用更好的搜索词重试 | llm_validate_results() | | 逐条过滤 | LLM 审查每条 ecoinvent 结果，移除不相关条目 | llm_filter_results() |

费用影响：每个产品多 2-3 次 LLM 调用，费用约翻倍。

适用场景：对结果质量要求高、产品数量较少（<50个）时使用。

注意事项

LLM 功能走用户自己的 API 余额，不消耗 EcoLink 服务器资源
服务器 /api/search/raw 只做数据库查询（<1秒），零 LLM 费用
API Key 不会被存储，仅在运行时使用
替代品推荐有黑名单过滤（禁止 chemical, inorganic 等宽泛类别）