# Mineral Daily Agent

一个证据优先、可离线复现的矿权日报 MVP。它用三个独立的 MCP stdio server 收集新闻、矿产资源量和商品价格证据，再由固定七状态 Agent 生成带引用的 Markdown 简报。

## 快速演示

```bash
docker compose run --rm app brief "给我生成一份关于 Pilbara 锂矿的今日简报" --mode fixture
```

或在 Python 3.12 + uv 环境运行：

```bash
uv sync --frozen
uv run mineral-daily brief "给我生成一份关于 Pilbara 锂矿的今日简报" --mode fixture
```

完整的 5 分钟步骤、质量命令和桌面 MCP 配置见 [RUN.md](RUN.md)。

## 架构

```text
自然语言请求
  -> typed planner（无 key 时确定性 fallback）
  -> 固定七状态有界工作流
  -> 3 个独立 MCP stdio clients
       -> mining-news-mcp
       -> mineral-pdf-mcp
       -> lme-price-mcp
  -> evidence validator
  -> grounded synthesis（可选）/ deterministic renderer
  -> 四章节 Markdown + source_id + 直接链接 + warnings
```

工作流没有开放式 ReAct 循环；三类工具各最多调用一次，网络 provider 内部仅允许有限重试。任一来源失败时，报告保留其他证据并显式标为 `partial`，不会用 fixture 静默替代 live 数据。

## MCP 工具

| Server | Tools | 数据边界 |
| --- | --- | --- |
| `mining-news-mcp` | `search(query, days)`、`fetch_article(url)` | fixture；可选 MINING.com RSS live adapter |
| `mineral-pdf-mcp` | `extract_resources(pdf_url)` | fixture；受 HTTPS、DNS/IP、重定向、类型、大小和超时约束的远程 PDF |
| `lme-price-mcp` | `get_price(commodity, date)`、`get_trend(commodity, days)` | fixture；仅在显式授权配置下使用 licensed feed |

所有工具都返回 `ok | partial | unavailable`、`data_mode`、`as_of`、结构化 payload、来源和 warning。

## 数据真实性边界

- 默认 fixture 是带来源 URL 与采集日期的可重复快照，不是实时行情。
- Pilgangoora 资源快照声明为 JORC，不冒充 NI 43-101。
- 锂价格快照来自公开的 IMF Primary Commodity Price System 月度基准数据，仅用于演示；不是 LME 官方报价或投资建议。
- 项目不抓取 LME 官网。live price 只有在用户提供已授权 HTTPS feed 与 token 时才启用。
- 所有报告数字必须映射到 bibliography 中存在的 `source_id`；校验失败会阻止渲染。

## LLM 边界

没有 API key 时，确定性 planner 和 renderer 可完成完整离线演示。配置 OpenAI-compatible gateway 后，模型只负责一次 typed plan 和一次已收集证据的压缩改写；固定工具集合、调用上限、catalog target 和来源由代码约束。模型新增数字、来源或改变状态时，输出会被拒绝，并以 `LLM_SYNTHESIS_FALLBACK` warning 显式回退。

## 取舍与限制

该版本针对 24 小时 MVP：只内置一个 Pilbara/Pilgangoora catalog target，不做 OCR、任意 PDF 表格理解、实时 LME、自动调度、数据库、Web UI 或投资建议。详细安全模型见 [SECURITY.md](SECURITY.md)，已知限制见 [LIMITATIONS.md](LIMITATIONS.md)。

## 开发验证

默认测试完全离线。完整发布门禁为 lint、format、strict mypy、pytest（覆盖率至少 80%）、7-case fixture eval、Compose 配置和干净容器演示；具体命令见 [RUN.md](RUN.md)。