Mineral Daily Agent

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

快速演示

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

或在 Python 3.12 + uv 环境运行：

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

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

Related MCP server: article-scraper-mcp

架构

自然语言请求
  -> 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 工具

所有工具都返回 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，已知限制见 LIMITATIONS.md。

开发验证

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