内容
# Petrel 代理 MCP
**适用于斯伦贝耶 Petrel 的 AI 代理控制界面 - 无需 Ocean SDK、无需供应商 API、无需 Python 连接器。**
本仓库包含一个 41 工具 [模型上下文协议](https://modelcontextprotocol.io) 服务器，允许 AI 代理（Claude、Codex 或任何 MCP 客户端）通过 Petrel 2018.2 盘点、导出、转换、审计和往返数据。它的存在是为了证明一个更广泛的论点：
> **代理 AI 可以控制没有 API 的软件。** 旧版本、封闭的桌面应用程序、许可证控制的供应商 SDK - 如果人类可以操作它，代理可以被赋予一个安全、确定、证据控制的工具界面。
Petrel 2018.2 是演示案例，而不是边界。这里没有任何内容使用 Ocean 开发框架或任何现代 Petrel 连接器；此版本的连接器要么不存在，要么需要本项目故意省略的许可证。
## 工作原理：四条路线
每个工具都建立在严格层次结构的最高可行层级上：
| 层级 | 路线 | 示例工具 |
|------|-------|---------------|
| 1 | **零 GUI 文件处理** - 直接解码和写入 Petrel 自有的文件格式 | 原始存储导出、`.zhz` 表面解码 → ZMAP+/XYZ、ZGY 地震 → 数组、LAS → CSV、井顶部 ASCII 写入器、项目审计报告 |
| 2 | **保存工作流编辑器 / 原始控制** - 通过其自身保存的工作流无头驱动 Petrel，并带有受保护的修补程序运行恢复 | 通过捐赠工作流导出 SEG-Y、SystemCmd 桥接、工作流运行器 |
| 3 | **确定性 GUI 微工作流** - 失败关闭 UIA + OCR 自动化，无硬编码坐标 | 井顶部 ASCII 导出（验证 84/84 行）、井日志 LAS 导出 |
| 4 | **发现 / 捐赠捕获** - 仅限映射和分析，绝不生产自动化 | 原始工作流区域映射器、克隆准备分析器 |
**41 个工具中有 32 个从不启动 Petrel** - 它们纯粹基于项目文件运行，因此无需消耗 Petrel 许可证（项目文件本身源自授权的 Petrel）。
## 安全模型
- 每个工具都带有 **失败关闭的失败策略** (`mcp/petrel_mcp_failure_policies.json`)，并返回每次运行的 **结果审计**，包含证据、失败类别和下一个安全操作。
- 可能启动 Petrel 的工具 **默认情况下为干运行**，需要显式选择启用标志。
- 原始项目文件在快照 → 修补 → 验证 → 恢复证据之前绝不会被修改。
- 每个导出的工件都在 **清单中注册 SHA-256 校验和** 并验证。
- 未经验证的内容会大声拒绝（`layout_unresolved`、`preflight_failed`、`blocked`）而不是猜测。
- 每个工具调用都会追加到本地 **使用日志** (`build\mcp_usage\*.jsonl`：工具、持续时间、结果、审计状态、失败类别），以便实时监控行为并报告带有证据的失败 - 请参见 `docs/INSTALL_NEW_MACHINE.md` §9。
## 快速入门（新机器）
要求：Windows、Python 3.10+（MCP 服务器本身是 **纯标准库** - 无需 `pip install` 即可运行）。
```powershell
git clone https://github.com/ahmedsahernouh/petrel-agent-mcp ; cd petrel-agent-mcp
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\setup_petrel_mcp.ps1
```
该单个命令检查您的 Python 版本，创建本地 `.venv`，安装可选的地理数据包（numpy、zmapio、pyzgy、lasio、pandas - 用于表面/ZGY/网格/LAS 链工具），写入项目 `.mcp.json`，报告 Tesseract 和 Petrel 是否存在，并通过运行 41 工具协议烟雾测试结束。如果它打印 `Petrel MCP 烟雾测试通过`，则表示您已完成。传递 `-NoVenv -NoGeodata -NoSmoke` 以获取最小配置行为；`scripts\doctor_petrel_mcp.ps1` 是更深入的环境检查。
然后在您的 MCP 客户端（Claude Code 自动拾取项目 `.mcp.json`）中批准服务器，或手动注册：
```powershell
claude mcp add --transport stdio petrel-no-ocean-control -- python <checkout>\mcp\petrel_mcp_server.py
```
某些路由需要的外部工具（设置会检测并报告两者；如果没有它们，任何操作都不会失败）：
- [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) - 仅限确定性 GUI 工具
- Petrel 2018.2 - 仅限于启动或驱动 Petrel 本身的 9 个工具
## 快速入门（您自己的 Petrel 项目）
1. 使用您的 `.pet` 项目路径调用 `petrel_prepare_mvp` - 为清单和导出包搭建。
2. 运行零 GUI 导出器：`petrel_export_native_zero_gui`、`petrel_export_native_semantic_zero_gui`、`petrel_export_well_tables_zero_gui`、`petrel_export_surfaces_zero_gui`、`petrel_export_seismic_zgy_zero_gui`。
3. 调用 `petrel_project_audit_report` - 一个自包含的 HTML 审计，检查所有内容，带有 QC 标志，无需启动 Petrel。
4. 对于实时 Petrel 路线（保存工作流 SEG-Y 导出、GUI 导出），请遵循 `docs/NO_OCEAN_MCP_CONTROL.md` - 这些需要每个项目的一次性设置（捐赠保存工作流、GUI 校准传递）。
每次代理会话均以 `petrel_agent_readiness` → `petrel_status` → `petrel_tool_creation_hierarchy` → `petrel_tool_failure_policy` 启动；服务器会告知代理哪些是已验证的，哪些是测试版，哪些是被拒绝的。
## 诚实的边界
- **版本范围是 Petrel 2018.2.** 原始格式解码和 GUI 几何图形在此处验证，其他地方未验证；框架具有版本感知，但跨版本使用需要重新验证，工具会说明，而不是假装否则。
- 在一个完整的演示项目上进行了端到端验证；新项目需要上述每个项目的设置步骤。
- 原始二进制 *标记选取* 解码 **未** 解决（ASCII 往返路线解决了）；*新建* 工作流命令的零 GUI 创建 **未** 解决（分析器处于 `blocked` 状态，等待捐赠证据）。文档记录了失败的内容和成功的内容一样仔细。
- 本项目开发的知识库（OKF/wiki）源自许可的 Petrel 文档，**不** 包含在内；`petrel_query_kb` 和 `petrel_generate_workflow_from_okf` 在没有它时也能正常运行。`docs/AGENT_INDEX_AND_RETRIEVAL.md` + `scripts/build_agent_index.py` 允许您构建自己的索引。
## 文档
| 文档 | 内容 |
|-----|----------|
| `docs/AI_CODER_HANDOVER_2026-07-08.md` | 适用于 AI 编码器的完整操作移交 |
| `docs/NO_OCEAN_MCP_CONTROL.md` | 控制路径：每个工具、每个边界 |
| `docs/PETREL_TOOL_CREATION_HIERARCHY.md` | 四层工具创建合同 |
| `docs/MCP_FAILURE_POLICY.md` | 失败关闭策略 + 结果审计系统 |
| `docs/DETERMINISTIC_PETREL_GUI_WORKFLOWS.md` | UIA/OCR GUI 自动化：模式、性能、鲁棒性 |
| `docs/PETREL_NATIVE_WORKFLOW_EDITING.md` | 原始存储研究：已验证的内容、被拒绝的内容 |
| `docs/FULL_PROJECT_EXPORT_MVP.md` | 完整的项目导出管道 |
| `docs/STAGE_1_NO_OCEAN_MCP_BASELINE.md` | 第一阶段基线和证据 |
## 商标和意图
Petrel 和 Ocean 是 SLB（斯伦贝耶）的商标。本项目是一个独立的研究项目，与 SLB 无关，也未得到 SLB 的认可。文件格式处理是为了与用户已经拥有的数据进行互操作；这里没有任何内容绕过许可 - 需要 Petrel 的工具仍然需要获得许可的 Petrel。
