---
name: esg-greenwash-analyzer
version: 2.0.0
description: >
  ESG 漂綠分析專家。從永續報告書段落或全文中抽取 ESG 承諾句,評判
  promise/evidence/timeline/quality 四欄位,套用確定性規則產出漂綠風險等級,
  並生成經反幻覺驗證的改寫建議。源自 AI CUP 2026 ESG 永續承諾驗證競賽
  (TEAM_10858, 6/143)。v2 架構:確定性歸腳本,判斷歸模型。
category: finance
tags: [esg, greenwash, sustainability, tej, csr, compliance, audit, rag]
allowed-tools:
  - Read
  - Bash
  - Glob
  - Grep
---

# ESG 漂綠分析專家 v2

## 分工鐵則:確定性歸腳本,判斷歸模型

執行本 skill 的 LLM(你)**只做三件事**:

1. **承諾句抽取**——從段落判斷哪些是 ESG 承諾句
2. **四欄位初評**——promise / timeline / evidence_status / evidence_quality
3. **改寫文字生成**——對高/中風險句寫改寫建議

**其餘一律呼叫 `scripts/` 腳本,嚴禁在腦中套規則**:約束修正、風險分類、改寫驗證、talk-walk 計算、回歸評分,全部有確定性實作。這保證同樣的四欄位輸入永遠得到同樣的風險結論,而模型升級只會改善上面三件事的品質。

## 環境

```powershell
$SKILL = "$env:USERPROFILE\.agents\skills\_finance\esg-greenwash-analyzer"
$env:PYTHONUTF8 = "1"   # 必設,否則中文輸出在 cp950 console 會炸
cd $SKILL\scripts
```

Python 3.11+,需要 chromadb、sentence-transformers、pandas、numpy、pyarrow。首次安裝:

```powershell
cd $SKILL
python -m pip install -r requirements.txt
```

所有路徑集中在 `config.json`:`upstream` 與 `local` 均指向本包內的相對路徑。換機器通常不需要改路徑;若要替換資料資產,只改這一檔。

## 工作流 A:判斷(段落 → 風險分級)

```
1. RAG 召回     python rag_query.py --text "<承諾句或段落>" --k 5 --out ..\work\fewshot.json
                (快速模式加 --no-semantic,跳過 36 秒模型載入,只用關鍵詞+金標)
2. LLM 判斷     讀 fewshot.json 的相似案例與 golden 範例,對每句評四欄位
                → 寫 ..\work\judged.jsonl(schema 見下)
                ★ 判斷前必讀 references/label_guide.md(稀有標籤與慣例)
3. 約束修正     python apply_constraints.py --in ..\work\judged.jsonl --out ..\work\constrained.jsonl
4. 風險分類     python classify_risk.py --in ..\work\constrained.jsonl --out ..\work\risked.jsonl
```

judged.jsonl 每行一筆:

```json
{"claim_id": "p48-1", "claim_text": "原句", "page_no": 48, "esg_type": "E",
 "promise_status": "Yes", "verification_timeline": "more_than_5_years",
 "evidence_status": "No", "evidence_string": "", "evidence_quality": "N/A",
 "judge_rationale": "一句話理由(繁中)"}
```

## 工作流 B:改寫協助(高/中風險句 → 驗證過的改寫)

```
1. 取目標       risked.jsonl 中 risk_level ∈ {高, 中} 的句子
2. LLM 改寫     ★ 必讀 references/rewrite_guide.md(占位符鐵則+規則碼對照)
                → 寫 ..\work\rewrites.jsonl(schema 見 rewrite_guide)
3. 驗證門檻     python validate_rewrite.py --in ..\work\rewrites.jsonl --out ..\work\rewrites_checked.jsonl
4. 重寫循環     rewrite_pass=false 的句子,帶著 violations 重寫,回到步驟 3
                最多 2 輪;仍未過 → 標記「人工覆核」,絕不硬塞進報告
```

## 工作流 C:公司級 talk−walk(實驗性)

```
python talk_walk.py --claims ..\work\risked.jsonl --ticker 2454 --pages 120
```

輸出含 z_talk 成分、z_walk(TEJ 產業內 robust-z)、greenwash_index 與 **caveat**。
T7 預登記驗證未支持此指數與問題率的相關性(ρ=-0.014, p=0.92, n=49),
報告中此節**必須**標示「實驗性指標,僅供參考」,不得作為主要結論。

## 工作流 D:回歸評測(換模型必跑)

```
1. 出題   python eval_regression.py --make-sample 50 --seed 42
2. 作答   讀 work\eval_questions.json,依工作流 A 的判斷規範逐筆評四欄位
          → 寫 work\eval_preds.jsonl({id, 四欄位})
          ★ 絕對不可讀 work\eval_gold.json
3. 對分   python eval_regression.py --score ..\work\eval_preds.jsonl
```

門檻(config.json thresholds):promise 0.85 / timeline 0.55 / evidence_status 0.65 / evidence_quality 0.45。固定 seed 使歷次評測可比,報告存 `work\eval_report_*.json`——這條「模型版本 × 準確率」曲線就是產品自我改善的證據。

## 自我測試(改動腳本後跑)

```powershell
python apply_constraints.py --self-test
python classify_risk.py --self-test      # 15 unit + 120 組合窮舉
python validate_rewrite.py --self-test
```

## 資產索引

| 資產 | 位置 | 用途 |
|---|---|---|
| ChromaDB 向量庫 | `data/chroma_db`(collection: esg_train_claims) | train_1000 語意檢索,384 維 MiniLM |
| 金標 few-shot | `data/golden_fewshot.json` | 13 筆涵蓋全部 (promise,timeline,quality) 組合 |
| 關鍵詞倒排索引 | `data/index.json` | 149 個 ESG 關鍵詞 → record ids |
| TEJ 摘要 | `data/tej_summary.json` | 2,804 家公司硬指標 |
| 產業對照 | `data/industry_map.json` | top-50 ticker → 產業/板塊 |
| 本地大資產 | config.json `upstream` | train/val 1000、TEJ parquet(17,753列)、top-50 產業對照 |
| 回饋報告模板 | `references/report_template.md` | 產出 HTML/MD 報告時的固定結構 |

## 產品原則

- **不商業化**;TEJ 數據只能以百分位/z 分數呈現,不得揭露原始數值。
- 改寫建議所有數值都是〔占位符〕,由報告書編製者填入,本工具不提供推估數字。
- 報告固定聲明:AI 輔助分析、需人工覆核、方法源自競賽第 6 名方案。

## 競賽基準(參考,與本 skill 的 accuracy 不可直接比較)

v43 ensemble Test Weighted Score:promise 0.7853 / timeline 0.6032 / evidence 0.6872 / quality 0.4353;Overall Private 0.6457(6/143)。