# E1 — 碳材料品质鉴定插件（plugins/carbon_analysis/）

> **定性：可选扩展插件，不随软件本体发布，独立分发，用户按需安装。**
> 本目录职责：分析碳纳米管/石墨烯等碳材料的 D/G/2D 拉曼特征峰，计算 ID/IG 比，评估材料品质。
> 只允许修改 `plugins/carbon_analysis/` 目录下的文件。
> 继承 PluginInterface（见 `plugins/CLAUDE.md`）。

---

## 识别码（plugin.json）— 必须存在

```json
{
  "plugin_id":       "carbon_analysis_v1",
  "name":            "碳材料品质鉴定",
  "version":         "1.0.0",
  "description":     "分析碳纳米管/石墨烯等碳材料的D/G/2D特征峰，计算ID/IG比，评估材料品质",
  "author":          "四川森普力科技有限公司",
  "category":        "拉曼分析",
  "entry_module":    "carbon_module",
  "entry_class":     "CarbonPlugin",
  "requires_stop":   true,
  "input_type":      "spectrum",
  "output_type":     "json",
  "min_app_version": "1.8.0",
  "builtin":         false
}
```

## Python 元信息（与 plugin.json 保持一致）

```python
PluginInfo(
    plugin_id  = "carbon_analysis_v1",
    name       = "碳材料品质鉴定",
    version    = "1.0.0",
    requires_stop = True    # 采集停止后才能运行
)
```

---

## 核心数据结构

```python
@dataclass
class PeakInfo:
    center_cm:  float       # 峰位（cm⁻¹）
    intensity:  float       # 峰强度
    fwhm_cm:    float       # 半高宽（cm⁻¹）
    r_squared:  float       # Lorentzian 拟合 R²

@dataclass
class CarbonAnalysisResult:
    D_peak:     PeakInfo | None   # ~1350 cm⁻¹
    G_peak:     PeakInfo | None   # ~1580 cm⁻¹
    peak_2D:    PeakInfo | None   # ~2700 cm⁻¹（可选）
    ID_IG:      float | None      # D/G 强度比
    I2D_IG:     float | None      # 2D/G 强度比（可选）
    material:   str               # 材料分类（见下表）
    confidence: float             # 分类置信度 0–1
```

**材料分类表**：

| ID/IG | 2D/G | material |
|-------|------|----------|
| < 0.1 | > 2.0 | 单层石墨烯 |
| < 0.1 | 1–2 | 少层石墨烯 |
| 0.1–0.5 | — | 多层石墨烯/高质量石墨 |
| 0.5–1.0 | — | 纳米晶石墨 |
| > 1.0 | — | 无定形碳/高缺陷 |
| G峰缺失 | — | 未知/非碳材料 |

---

## 公开接口（carbon_module.py）

```python
def analyze(wl: np.ndarray, intensities: np.ndarray) -> CarbonAnalysisResult:
    """主接口：自动搜索 D/G/2D 峰，计算比值，输出分类结果。
    输入谱线 X 轴必须为 cm⁻¹（拉曼位移），否则结果无意义。
    所有峰均未找到 → 返回全 None 的结果，material="未知/非碳材料"。
    """

def find_d_peak(
    wl: np.ndarray, intensities: np.ndarray,
    search_range: tuple[float, float] = (1250.0, 1450.0)
) -> PeakInfo | None:
    """Lorentzian 拟合 D 峰（~1350 cm⁻¹），SNR < 3 返回 None。"""

def find_g_peak(
    wl: np.ndarray, intensities: np.ndarray,
    search_range: tuple[float, float] = (1500.0, 1650.0)
) -> PeakInfo | None:
    """Lorentzian 拟合 G 峰（~1580 cm⁻¹）。"""

def find_2d_peak(
    wl: np.ndarray, intensities: np.ndarray,
    search_range: tuple[float, float] = (2600.0, 2800.0)
) -> PeakInfo | None:
    """Lorentzian 拟合 2D 峰（~2700 cm⁻¹）。"""
```

---

## config.json（峰位搜索范围，用户可调）

```json
{
  "D_peak_range_cm": [1250, 1450],
  "G_peak_range_cm": [1500, 1650],
  "2D_peak_range_cm": [2600, 2800],
  "min_snr": 3.0
}
```

---

## validate_input 规则

- 输入谱 X 轴范围须覆盖 1250–1650 cm⁻¹（D+G 峰区）
- 数据点数 ≥ 50
- 不合法返回 `(False, "输入谱线需覆盖1250–1650 cm⁻¹范围")`

---

## 约束

- 仅支持拉曼谱（cm⁻¹ 轴），不支持普通吸收/反射谱
- 禁止修改 `plugins/base_plugin.py`
- 禁止访问 `spectrum_ops/`、`Driver/`、`manager/`


---

## 进度文件（必须维护）

本模块进度记录：**`plugins/carbon_analysis/PROGRESS.md`**

每完成一个文件立即更新，未更新 `PROGRESS.md` 前不得开始下一个文件。
发现其他模块的问题，记入"跨模块问题"栏，不得顺手修改。

本模块待完成文件清单：
- [ ] `plugin.json`（识别码，必须先创建）
- [ ] `__init__.py`
- [ ] `carbon_module.py`（E1 主逻辑）
- [ ] `config.json`

---

## Agent 状态上报（必须执行）

**本 Agent ID**：`agent-carbon`
**状态文件**：`{项目根目录}/.agents/agent-carbon.status.json`
**上报协议**：参阅 `references/agent_protocol.md`

### 关键时机

| 时机 | status 值 |
|------|----------|
| 开始新阶段 | `running` |
| 完成一个文件/功能 | 更新 step + progress |
| 需要用户授权（删除/覆盖/架构决策）| `waiting` + wait_reason |
| 全部完成 | `done`，progress=100 |
| 遇到无法解决的错误 | `error` + 错误说明 |

**写状态样板代码**：参见 `references/agent_protocol.md`

---

## ⛔ Git 提交禁令

**本 Agent 禁止执行任何 git 操作**（`git add`、`git commit`、`git push` 等）。

完成工作后只需：
1. 更新本模块 `PROGRESS.md`
2. 更新根目录 `PROGRESS.md` 的阶段进度
3. 将状态文件写为 `done`（100%）

**Git 提交由总管 Agent 统一执行。**
