ccdb-factor-search（ccdb 因子搜索）

CCDB Factor Search

Find the best-fit CCDB emission factor for carbon footprint, PCF, LCA, and carbon accounting work — not just a raw result list.

This skill is built for the real business question:

Which factor should I actually use?

It searches in Chinese + English, compares candidates, filters weak matches, explains risks, and returns a recommended factor with direct-use guidance.

It is especially useful when the database is broad and the user needs help choosing from domestic + international sources, including ecoinvent and other mainstream institutional datasets.

Why this is better than plain search

• plain search → returns a list of possible factors
• this skill → recommends the best-fit factor for the actual use case
• plain search → easy to mis-pick wrong region / wrong unit / wrong factor type
• this skill → filters weak matches and explains risks before use
• plain search → stops at retrieval
• this skill → supports real carbon-accounting decisions

What this skill does

It can:

• search CCDB factors in Chinese + English
• compare multiple candidates and select the best-fit one
• distinguish carbon footprint factor vs emission factor
• reject weak matches such as wrong-region, wrong-unit, or spend-based factors
• explain whether a result is safe to use directly, review-first, estimate-only, or not suitable
• work across a broad factor data range, including China + international sources and ecoinvent-related records where available in CCDB

Best-fit use cases

Use this skill when you need to:

• 查碳因子 / 排放因子 / 碳足迹因子
• 因子匹配 / 选因子 / 因子筛选
• LCA 因子 / PCF 因子 / scope 3 因子
• BOM 因子匹配 / 供应商材料因子匹配
• 判断某个因子能不能直接用于正式报告
• 区分 carbon footprint factor vs emission factor
• 避免选错 地区 / 单位 / 因子类型 / 金额口径因子

Also activate proactively when:

• user requests 产品碳足迹建模 / LCA建模 / 排放清单核算 / 情景测算 and factor data is clearly needed
• user provides BOM or material list and asks for carbon footprint calculation
• task involves 供应链碳排放 / scope 3 核算 and activity data is present but no factor has been supplied

Before vs after

User asks

帮我找中国最新全国电力因子。

Plain search might return

• multiple electricity-related candidates
• mixed carbon-footprint vs emission-factor results
• unclear region / year / direct-use suitability

This skill returns

• one recommended candidate
• why it was selected
• risk notes
• alternatives considered
• whether it is safe for direct use or should be reviewed first

Very short examples

• 查询最新中国全国电力因子
• 帮我找聚酯切片的碳因子
• 这个因子能不能直接用于正式报告？
• Compare carbon footprint factor vs emission factor for electricity
• Find the best CCDB factor for primary aluminium

How to invoke

Natural-language examples

• 查询最新中国全国电力因子
• 帮我找聚酯切片的碳因子，如果中文结果不好就切英文继续找
• 这个因子能不能直接用于正式报告？
• Compare carbon footprint factor vs emission factor for electricity
• Find the best CCDB factor for primary aluminium, prefer physical-unit factor

Script examples

python3 scripts/query_ccdb.py --auto --user-request "查询最新的中国全国电力因子，单位最好是 kgCO2e/kWh。"
python3 scripts/query_ccdb.py --query "electricity" --lang en --top 5

Typical example prompts

Example 1

查询最新的中国全国电力因子，单位最好是 kgCO2e/kWh。

Expected behavior:

• prioritize China electricity candidates
• prefer recent applicable years
• distinguish carbon footprint factor vs emission factor
• return direct-use guidance

Example 2

帮我找聚酯切片的碳因子，如果中文结果不好就切英文继续找。

Expected behavior:

• derive PET / polyester synonyms
• search bilingually
• compare candidates across rounds
• return one recommended factor plus alternatives

Example 3

请帮我找原铝的排放因子，优先物理量单位，不要误选成按金额计算的因子。

Expected behavior:

• reject or downgrade spend-based factors
• prefer physical-unit candidates
• explain why the chosen factor is safer

Example 4

这个因子能不能直接用于正式报告？

Expected behavior:

• explain whether it is direct-use / needs review / estimate-only / not suitable

Standard output example

推荐结果:
  匹配等级: close_match
  因子名称: 电力
  因子值: 0.5777
  单位: kgCO2e/kWh
  适用地区: 中国
  适用年份开始: 2024
  适用年份结束: 2024
  发布年份: 2024
  来源机构: 生态环境部
  来源级别: 国家排放因子
  使用建议: 建议人工复核后使用

风险与注意事项:
  - 这是碳足迹因子，不等同于 CO2 排放因子
  - 若用于正式核算或核查，请先确认适用口径

Key fields to return when possible

A good result should explain these fields clearly:

• 因子名称 / name
• 因子值 / factor value
• 单位 / unit
• 适用地区 / countries
• 适用年份开始 / 结束 / applyYear ~ applyYearEnd
• 发布年份 / year
• 来源机构 / institution
• 来源级别 / sourceLevel
• 来源说明 / source
• 使用建议 / direct-use guidance

Match classes

• direct_match → highly aligned, usually safe to use after quick sanity check
• close_match → mostly aligned, should usually be reviewed before formal reporting
• fallback_generic → usable only as rough estimate / placeholder
• not_suitable → should not be used directly
• api_unavailable → no recommendation; retry later

What this skill must do

1. Parse the real search intent

Identify as much as possible from the request:

• material / process / activity
• region
• year
• unit
• use purpose
• whether the user wants 碳足迹因子 or 排放因子

2. Search bilingually

For non-trivial factor matching, do not search in only one language. Always try:

• Chinese core term
• English equivalent
• a few nearby synonyms where needed

3. Rank candidates instead of trusting the first hit

Do not judge a factor from one field only. Key ranking dimensions include:

• semantic fit (name, description, specification)
• region fit (countries)
• unit fit (unit)
• applicability time (applyYear ~ applyYearEnd)
• publication year (year)
• authority (institution, sourceLevel)
• factor-type fit (碳足迹因子 vs 排放因子)

4. Be conservative

Do not force a recommendation when evidence is weak. Prefer:

• not_suitable
• api_unavailable

over a misleading confident answer.

5. Explain the choice

The final answer should explain:

• what was selected
• why it was selected
• what risks remain
• what alternatives were considered
• whether the result can be used directly or only as reference

Key working rules

Carbon footprint factor vs emission factor

These are not always interchangeable.

• If the user explicitly asks for 碳足迹 / carbon footprint / PCF, prefer carbon footprint factors.
• If the user explicitly asks for 排放因子 / CO2 emission factor / emissions accounting, prefer emission factors.
• If the user only says something vague like “电力因子”, warn that multiple factor types may exist and should not be mixed directly.

China-first bias for Chinese requests

If:

• the request is in Chinese
• no explicit region is given
• the query is geo-sensitive (especially 电力 / 蒸汽 / 天然气)

then Chinese candidates should be preferred by default.

Region warning for geo-sensitive factors

For electricity / steam / natural gas queries, if region is missing, surface that clearly as a risk.

Latest-factor requests

If the user asks for “最新 / latest”, ranking should prefer more recent applyYear, not only lexical similarity.

No spend-based mismatch

If the user wants a physical activity factor, do not recommend spend-based / monetary-unit factors as if they were equivalent.

Implementation notes

• Main script: scripts/query_ccdb.py
• API contract: references/api-contract.md
• Matching logic notes: references/matching-strategy.md
• Output template: references/output-template.md

If the API contract changes, update the script and references/api-contract.md together.

Keep scoring / filtering logic in code rather than overloading SKILL.md with implementation detail.

Advanced fallback / debugging

Script unavailable fallback

If scripts/query_ccdb.py is missing or fails to run, fall back to a direct API call:

curl -s -X POST https://gateway.carbonstop.com/management/system/website/searchFactorDataMcp \
  -H 'Content-Type: application/json' \
  -d '{"sign":"<md5(\"mcp_ccdb_search\"+keyword)>","name":"<keyword>","lang":"zh"}'

The sign is md5("mcp_ccdb_search" + keyword). In Python:

import hashlib, requests
keyword = "电力"
sign = hashlib.md5(("mcp_ccdb_search" + keyword).encode()).hexdigest()
resp = requests.post("https://gateway.carbonstop.com/management/system/website/searchFactorDataMcp",
    json={"sign": sign, "name": keyword, "lang": "zh"})
print(resp.json())

Even in fallback mode, apply the same ranking, matching, and output rules defined above. Do not return raw API results without analysis.

Packaging guidance

For public packaging, keep the skill folder lean. Recommended public package contents:

• SKILL.md
• README.md
• _meta.json
• CHANGELOG.md
• scripts/query_ccdb.py
• references/api-contract.md
• references/matching-strategy.md
• references/output-template.md
• evals/evals.json

Draft notes and publishing scratch files should not be included in the final public package.