内容
# 预测平台 Omen
<img src="https://raw.githubusercontent.com/badass-data-science/omen-agentic-time-series-forecasting/main/book/title-page-image.png" width="400" alt="Omen title page illustration" />
**Omen 为 AI 代理提供了一套经过测试、具有统计学严谨性的时间序列预测工具包，而不是让 AI 自己编写统计代码。** 五个 FastMCP 服务器，每个预测生命周期阶段一个，可作为单个 `pip install` 安装。
```bash
pip install "omen-agentic-forecasting[all]"
```
*状态：Alpha，已在 PyPI 发布。 161 个真实测试，每个配套书籍中的示例都针对实时工具输出运行，而不是手动输入。 CI（GitHub Actions）每次推送和 PR 时都会运行完整的测试套件以及 ruff linting 和 mypy 类型检查。请参阅 `CHANGELOG.md` 获取版本历史。*
## 为什么存在
时间序列预测是一个经过充分研究统计学科，但很容易出错：跳过平稳性检查、从不与朴素基线比较、报告没有置信区间的点预测。要求通用 AI 模型“预测这个序列”，它通常会编写看似合理的 `pandas`/`statsmodels` 代码，但会跳过这些检查——不是因为统计数据难以命名，而是因为每次都正确、正确地编写统计代码对于 LLM 来说比看起来要难得多。
Omen 的解决方案是停止要求代理即兴发挥统计数据。 这里的每个操作——检查平稳性、用真实的保留数据回测模型、计算置信区间、决定是否值得重新部署经过重新训练的候选模型——都是预先构建、测试、类型化的工具，通过模型上下文协议（MCP）作为 FastMCP 服务器公开，并附带 OpenClaw 技能（这些工具的推理工作流程）。AI 代理的工作变成了选择下一个要调用的工具，并根据返回的结构化结果进行推理，而不是从头开始编写统计代码。诸如重新部署实时模型等重要操作，在明确的代码检查确认之前是被禁止的；开放式推理，例如哪个模型家族适合序列的形状，留给代理，这是它的本职。
## 五层
这种划分体现在五个层中，每个层涵盖预测生命周期中的一个阶段，从首先查看数据到数月后决定是否重新训练：
- **第 1 层 — `ts-analyst`**：探索序列——平稳性、季节性、异常、结构性中断——并建议具有推理的预测方法。
- **第 2 层 — `ts-forecaster`**：拟合候选模型与共同的保留窗口，回测它们（可选地跨多个滚动源），统计比较它们，并建议一个基于真实误差指标和残差诊断的模型。
- **第 3 层 — `ts-deploy`**：在完整序列上重新训练选定的模型，并生成超出数据末端的真实预测，具有预测区间（只要模型能诚实地支持），自动合理性检查与序列历史对比，以及多个候选者的可选加权集成。
- **第 4 层 — `ts-monitor`**：一旦存在真实观测，检查部署的预测是否仍在跟踪现实（具有误差指标的自举置信区间），检测数据漂移（具有效应大小，而不仅仅是裸 p 值），并建议是否重新训练——当建议接近阈值而不是明确时发出标志。
- **第 5 层 — `ts-retrain`**：当 `ts-monitor` 表示 `retrain_now` 时，重新运行第 1-2 层在更新的序列上，并确定性地决定新候选者是否优于当前部署的模型，值得重新部署，具有置信区间感知两侧的比较。除非明确 `confirmed=True`，否则绝不重新部署——默认情况下，这意味着停止人工确认，可选的自主模式替代由真实、代码检查的授权记录支持，而不是简单的书面合同。
第 1-4 层还公开了 13 个 `plot_*` 工具，渲染 matplotlib 图形并将其作为内联图像返回，附带可选的 `out_path` 以保存 PNG 到磁盘。这些是严格的补充：每个图表都从其 JSON 对应项已经返回的精确计算中重新导出其图像，因此图表永远不会与背后的数字无声地不一致。
## 快速入门
```bash
pip install "omen-agentic-forecasting[all]"
```
此命令安装每个层的依赖项和五个控制台脚本（`ts-analyst-server`、`ts-forecaster-server`、`ts-deploy-server`、`ts-monitor-server`、`ts-retrain-server`），每个脚本都是 FastMCP 服务器，准备好与任何支持 MCP 的客户端代理注册——OpenClaw、Claude Code、Claude Desktop 或类似。 一个可直接合并的 OpenClaw 配置片段，`openclaw.config.snippet.jsonc`，位于存储库根目录。 如果只需要部分层，也可以选择每层的额外依赖： `[analyst]`、`[forecaster]`、`[deploy]`、`[monitor]`、`[retrain]`。
**完整平台设置指南** —— OpenClaw、Claude Code、通用 MCP 客户端和最常见的安装陷阱（按照实际发生的情况讲述）—— 请参阅 `book/chapter-02-installing-omen.md`。
连接后，单个消息即可驱动整个管道：
> 使用 `ts-analyst` 探索合成时间序列，然后使用 `ts-forecaster` 拟合并回测由您的发现所指导的候选模型，然后使用 `ts-deploy` 使用最佳性能模型和设置生成 30 天的预测。
## 从头到尾使用
一旦时间流逝，CSV 文件中有了新的真实观测：
> 使用 `ts-monitor` 检查该预测是否仍然符合实际情况，并告诉我是否应该重新训练。
在第一次真正的 `ts-deploy` 调用之后，记录部署了什么，以便第 5 层有一个基准来进行比较：
> 使用 `ts-retrain` 记录此模型及其回测指标现已部署。
如果 `ts-monitor` 返回 `retrain_now`：
> 使用 `ts-retrain` 重新运行分析师和预测器，更新序列，并告诉我新的候选者是否值得重新部署。
该调用在判决处停止——`ts-retrain` 默认情况下绝不重新部署。如果判决表示 `should_redeploy: true` 并且您想继续，请在后续消息中明确确认：
> 继续重新部署您刚刚推荐的候选模型。
这实际上触发了 `ts-retrain__execute_redeploy(...，confirmed=True)` 并更新了清单。
如果您不想每次都为特定序列询问具体操作，可以选择显式进入自主模式：
> 特别是对于 `daily_demand.csv` 序列，您被授权在 `ts-retrain` 找到优于当前部署的候选者时自动重新部署——无需每次都询问我。其他一切仍按通常需要我的确认。
该授权是代理应该通过 `ts-retrain__authorize_autonomous_mode(csv_path="daily_demand.csv", authorized_by="user, in conversation")` 转换为持久记录的——而不仅仅是在会话期间记住。 有了该记录，当该序列的后续 `retrain_now` 循环将调用 `execute_redeploy(confirmed=True, autonomous=True)` 本身，并在 `should_redeploy: true` 返回时报告它做了什么，而不是暂停询问。
## 了解更多
- **`book/`** — *超级恶棍的代理时间序列预测*，一本完整的 22 章电子书（附有词汇表、工具参考和进一步阅读附录），通过此工具包教授时间序列预测，每个概念一章，每个工作示例都针对实时 MCP 服务器运行，而不是手打。 从 `book/outline.md` 开始或直接跳转到 `book/chapter-01-*.md`。
- **`book/appendix-b-tool-reference.md`** — 所有五层工具的单行查找表，如果您只想知道给定工具的作用而不阅读介绍它的章节。
- **`AGENTS.md`** — 项目自己的密集、内部设计日志：确切的工具机制、确认的边缘情况和非显而易见的约定，写给接手此代码的人，而不是第一次阅读。
- **`blog-posts/`** — 较短、有力的文章，涵盖相同的五层，每层一篇文章，加上介绍性概述。
- **`prompts/testing-and-learning-prompts.md`** — 适用于所有五层的即用提示，用于使用您自己的数据进行实践。
## 项目布局
```
omen/
├── pyproject.toml
├── LICENSE
├── README.md
├── AGENTS.md
├── .gitignore
├── openclaw.config.snippet.jsonc
├── .github/
│ └── workflows/
│ └── ci.yml # ruff + mypy + pytest (3.10/3.11/3.12) on every push/PR
├── graphify-out/ # 知识图谱（代码 + 文档 + 书籍 + 图像）
│ ├── graph.json # GraphRAG-ready 节点/边
│ ├── graph.html # 交互式可视化
│ ├── GRAPH_REPORT.md # 普通语言摘要
│ ├── manifest.json
│ └── .graphify_labels.json
├── src/
│ └── omen/
│ ├── __init__.py # 版本 + 技能目录（）辅助函数
│ ├── data_prep.py # 共享：合成数据 + CSV 加载器（所有 5 层使用）
│ ├── plotting.py # 共享：render_plot（）-- 内联图像 + 可选 PNG，用于所有 plot_* 工具
│ ├── analyst/
│ │ ├── __init__.py
│ │ ├── analysis_tools.py # 第 1 层诊断函数
│ │ ├── plot_tools.py # 第 1 层绘图函数（6 个工具）
│ │ └── server.py # FastMCP 服务器：ts-analyst
│ ├── forecaster/
│ │ ├── __init__.py
│ │ ├── model_tools.py # 第 2 层拟合/回测函数
│ │ ├── plot_tools.py # 第 2 层绘图函数（3 个工具）
│ │ └── server.py # FastMCP 服务器：ts-forecaster
│ ├── deploy/
│ │ ├── __init__.py
│ │ ├── forecast_tools.py # 第 3 层重新训练/预测函数
│ │ ├── plot_tools.py # 第 3 层绘图函数（1 个工具）
│ │ └── server.py # FastMCP 服务器：ts-deploy
│ ├── monitor/
│ │ ├── __init__.py
│ │ ├── monitor_tools.py # 第 4 层比较/漂移/重新训练决策函数
│ │ ├── plot_tools.py # 第 4 层绘图函数（3 个工具）
│ │ └── server.py # FastMCP 服务器：ts-monitor
│ ├── retrain/
│ │ ├── __init__.py
│ │ ├── retrain_tools.py # 第 5 层部署清单 + 重新部署决策函数
│ │ └── server.py # FastMCP 服务器：ts-retrain（无绘图工具）
│ └── skills/ # 打包为数据 - 请参阅 skills_dir（）
│ ├── ts-analyst/SKILL.md
│ ├── ts-forecaster/SKILL.md
│ ├── ts-deploy/SKILL.md
│ ├── ts-monitor/SKILL.md
│ └── ts-retrain/SKILL.md
├── tests/
│ ├── test_data_prep.py
│ ├── test_analyst_tools.py
│ ├── test_analyst_plot_tools.py
│ ├── test_forecaster_tools.py
│ ├── test_forecaster_plot_tools.py
│ ├── test_deploy_tools.py
│ ├── test_deploy_plot_tools.py
│ ├── test_monitor_tools.py
│ ├── test_monitor_plot_tools.py
│ └── test_retrain_tools.py
├── blog-posts/ # 项目的草稿文章，不是软件包的一部分
│ ├── introducing-omen.md
│ ├── ts-analyst-gets-a-statistics-degree.md
│ ├── ts-forecaster-shows-its-work.md
│ ├── ts-deploy-ships-it.md
│ ├── ts-monitor-learns-to-doubt-good-news.md
│ └── ts-retrain-checks-its-papers.md
├── prompts/ # 每个层的即用提示，用于测试/学习
│ └── testing-and-learning-prompts.md
└── book/ # “超级恶棍的代理时间序列预测”，不是软件包的一部分
├── dedication.md, ai_use_statement.md, about_the_author.md, about_the_series.md
├── title-page-image.png # 封面图片，也嵌入在上面和书的标题页
├── outline.md
├── chapter-01-introducing-omen-and-agentic-ai.md ... chapter-22-conclusion.md
├── appendix-a-glossary.md, appendix-b-tool-reference.md, appendix-c-further-reading.md
└── examples/
├── README.md # 数据集/绘图/组装脚本如何组合
├── generate_book_datasets.py # 重新生成书籍使用的每个数据集
├── generate_book_plots.py # 重新生成书籍嵌入的每个绘图图像
├── assemble_book.py # 将书籍合并为一个 Markdown 文件 + PDF
├── book_datasets/ # 提交的 CSV 副本 - 书籍使用的每个数据集
└── images/ # 书籍章节中嵌入的 32 个真实 PNG
```
## 开发
```bash
python -m venv .venv && source .venv/bin/activate # 可选但推荐
pip install -e ".[all,dev]" # 可编辑安装，每层 + 测试依赖
pytest # 161 个测试
ruff check . # lint
mypy # 类型检查
```
逐一检查每个服务器独立运行（Ctrl+C 停止；无输出/崩溃 = 良好）：
```bash
ts-analyst-server
ts-forecaster-server
ts-deploy-server
ts-monitor-server
ts-retrain-server
```
可导入模块在安装方式上保持为纯 `omen` —— 只有 PyPI *列表* 名称为 `omen-agentic-forecasting`（纯 `omen` 已被占用；请参见 `pyproject.toml` 中 `[project.scripts]` 上方的注释）。 有关构建/发布命令和一组非显式项目约定，请参阅 `AGENTS.md`。
