Mini Data Engine Runtime Copilot

交互式数据系统实验室

可运行的 Python 和 Rust 数据系统内部实现，搭配原生支持 MCP 的运行时 Copilot 层。

此仓库包含两部分：

• 一个本地优先的工程实验室，探索类似 PostgreSQL 和 Databricks 的内部实现；
• 一个 Runtime Copilot MCP 接口，用于诊断、可解释性分析、回归检查和运维记忆。

核心功能

• 存储与规划器内部实现：堆表、B-tree 索引、选择率和计划选择。
• 持久化与重放：类似 WAL/检查点的流程和确定性状态转换。
• 工作流与写入路径建模：事件优先架构、幂等性、重试语义。
• 可解释的运行时运维：跟踪运行、故障摘要、回归判定、基线对比。
• MCP 访问：提供机器可用的运维接口，而非临时编写的 Shell 脚本。

适用对象

• 学习数据仓库和查询引擎内部实现的数据工程师。
• 教授存储和执行基础知识的平台与基础设施工程师。
• 构建入门实验、研讨会和演示环境的团队。

快速开始

依赖要求：

• Python 3.10+（已使用 Python 3.14 测试）

设置：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "psycopg[binary]"

运行端到端流程：

cargo run --bin e2e_flow

运行核心演示：

.venv/bin/python mini_pg_like.py
.venv/bin/python mini_databricks_clone.py
cargo run --bin mini_pg_like
cargo run --bin mini_databricks_clone

此仓库包含的内容

• mini_pg_like.py：类似 PostgreSQL 的玩具引擎，包含堆表、B-tree 索引和规划器输出。
• mini_databricks_clone.py：类似 Databricks 的玩具平台，包含版本控制、分区、DAG 和事件。
• src/bin/mini_pg_like.rs：Rust 版 PostgreSQL 类演示。
• src/bin/mini_databricks_clone.rs：Rust 版 Databricks 类演示。
• src/lib.rs、src/common.rs、src/pg.rs：共享的 Rust 核心模块。
• mcp_engine_server.py：用于诊断和回归工作流的 MCP 运行时适配器。

创建此项目的原因

大多数内部实现相关内容止步于图示。本项目保持可运行、可检查：

• 对比同一系统概念的 Python 和 Rust 实现；
• 通过具体事件和状态转换追踪写入路径行为；
• 通过 MCP 运行可解释的回归检查；
• 将运行时运维转化为 AI 客户端可发现的控制接口。

MCP 适配层

此仓库还包含一个封装实验室操作的精简 MCP 服务：

• mcp_engine_server.py
• Cursor 配置：.cursor/mcp.json

此版本的 MCP 工具列表（共 47 个工具）：

引擎状态和运行时：

• init_engine
• insert_row
• upsert_row
• create_index
• explain_customer
• reindex_project
• run_e2e_flow

可解释性和演示：

• explain_run
• demo_explain_run
• demo_explain_run_failure
• demo_explain_semantic_failure
• demo_explain_idempotency_conflict
• demo_explain_concurrency_failure_storm
• explain_regression_suite

追踪和检索：

• record_tool_trace
• similar_incidents
• refresh_trace_path
• refresh_docs_path
• memory_upsert
• memory_search

SLO 和 ROI：

• health_check
• benchmark_calls
• scenario_load_test
• capture_roi_baseline
• report_drift_bug
• decision_gate

架构评估（通过 MCP 返回结论和报告，无需外部 Postgres）：

• schema_load_tool
• schema_explain_tool
• schema_evaluate_tool
• schema_evaluate_full_tool

项目契约和回归：

• project_manifest
• project_capabilities
• project_tool_catalog
• project_get_defaults
• project_run_regression
• project_capture_baseline
• project_compare_baseline

通用项目状态：

• project_list_entities
• project_get_entity
• project_upsert_entity
• project_delete_entity
• project_append_event
• project_ingest_trace
• project_explain_run
• project_export_state

通用启发式分析：

• project_list_heuristics
• project_run_heuristic

若要以机器可读的方式发现工具，建议使用：

• project_tool_catalog
• project_get_defaults

可通过 project_run_heuristic 使用的当前启发式分析配置：

• pain_structure
• naive_bias
• price_distribution
• liquidity_signals
• price_liquidity_matrix
• cross_category
• sale_format
• speed_signals
• trust_signals

如果已启用 Cursor MCP 自动发现，请重启 Cursor 并连接 mini-data-engine。 默认 MCP 运行时数据路径位于 tests/artifacts/mcp/* 下。

Cursor 审批设置（减少重复提示）

如果 Cursor 每次调用 MCP 或命令时都要求审批，请一次性完成以下设置：

1. 在 Cursor 用户设置中启用工作区信任：

"security.workspace.trust.enabled": true

2. 在 Cursor 中打开 Settings -> Agents -> Auto-Run 并设置：

   • Auto-run mode：Run in Sandbox
   • MCP Allowlist：添加常用的 mini-data-engine 工具
   • Command Allowlist：添加常用的安全命令

3. 将此仓库保持为同一个受信任的工作区，并重新加载一次窗口。

注意：

• MCP 服务审批和按工具设置的允许列表行为由 Cursor 安全设置强制执行。
• 某些 Cursor 版本中的允许列表行为可能无法保证完全生效，极少数情况下仍会显示提示。

通过 MCP 体验全新可解释性用例的最快方式：

demo_explain_run

这一条工具调用会创建一次带追踪的运行，在同一个 run_id 下记录各步骤事件，并返回一份说明，其中包含：

• 按顺序排列的时间线
• 工具调用路径
• 总耗时
• 出现故障时的失败摘要

之后，你可以直接重放同一份说明：

explain_run(run_id="...")

解释型回归套件

如果你希望通过 MCP 运行回归检查，并以可解释的运行摘要而非孤立的测试输出作为结果，请使用 explain_regression_suite。

该套件通过 MCP 层驱动当前验证范围，附加 run_id 跟踪信息，并为每项检查返回解释输出，以便使用与运行时事件相同的机制检查回归问题。

目前运行的检查包括：

• 通过 python -m unittest discover 运行 Python 单元测试
• 通过 cargo test 运行 Rust 测试，包括当前的 engine_cli 集成测试
• health_check
• benchmark_calls
• scenario_load_test
• 可解释性控制演示

这些可解释性演示有意同时包含正向和负向控制：

• demo_explain_run，作为 expected_success
• demo_explain_run_failure，作为 expected_failure
• demo_explain_semantic_failure，作为 expected_failure
• demo_explain_idempotency_conflict，作为 expected_failure
• demo_explain_concurrency_failure_storm，作为 expected_failure

这意味着该套件不仅会检查正常路径是否保持正常，还会检查解释层能否正确分类并总结已知的故障类型。

当前回归范围涵盖：

• 正常路径跟踪执行
• 运行时／路径故障
• 语义数据验证故障
• 幂等性冲突故障
• 并发与故障风暴控制场景
• 抽样基准测试和场景 SLO 回归

调用完整回归套件最快的 MCP 调用：

explain_regression_suite

如果你希望通过一次调用获得以下信息，可将其用作顶层 MCP 回归入口：

• 哪些检查已通过
• 哪些故障属于预期控制
• 每次跟踪运行的解释摘要
• 延迟或行为回归出现的早期信号

MCP 层是访问接口，而非产品构想的核心。该存储库的核心是可运行的实验室本身。

产品说明：

• PRODUCT_NOTE_RUNTIME_EXPLAINABILITY.md 简要说明运行时可解释性的应用场景、所需信号以及 explain_run MVP。
• PRODUCT_NOTE_RUNTIME_COPILOT.md 将 Runtime Copilot 定位为 MCP 原生运维大脑的产品说明。
• EXPLAIN_REGRESSION_SUITE_FEASIBILITY.md 简要介绍该存储库对解释优先型回归套件的验证结果，以及当前覆盖范围仍然有限的原因。

在 Codex 中使用：

• 技能包：codex/skills/runtime-copilot/SKILL.md
• 自动化示例：codex/automations
• 指南：docs/use-in-codex.md

运行持久化引擎 CLI（产品化路径）：

# Initialize storage
cargo run --bin engine_cli -- init ./tests/artifacts/engine/data orders

# Insert and upsert (WAL append)
cargo run --bin engine_cli -- insert ./tests/artifacts/engine/data orders 1 4242 50
cargo run --bin engine_cli -- upsert ./tests/artifacts/engine/data orders 1 4242 55

# Build index and explain
cargo run --bin engine_cli -- index ./tests/artifacts/engine/data orders
cargo run --bin engine_cli -- explain ./tests/artifacts/engine/data orders 4242

# Write snapshot and truncate WAL
cargo run --bin engine_cli -- checkpoint ./tests/artifacts/engine/data orders

# Transaction simulation: begin/commit/rollback semantics,
# per-table write lock, snapshot read, and conflict detection
cargo run --bin engine_cli -- tx-demo ./tests/artifacts/engine/data orders

# Crash/restart recovery for transaction journals
cargo run --bin engine_cli -- tx-recovery-list ./tests/artifacts/engine/data orders
cargo run --bin engine_cli -- tx-recovery-commit ./tests/artifacts/engine/data orders <tx_id>
cargo run --bin engine_cli -- tx-recovery-rollback ./tests/artifacts/engine/data orders <tx_id>

你应该看到什么

• 在 mini_pg_like.py 中：选择性谓词会切换到 Index Scan；非选择性谓词仍使用 Seq Scan。
• 在 mini_databricks_clone.py 中：逐层演示输出、工作流 DAG 顺序/指标，以及来自单一写入路径的规范事件计数。
• 在 mini_pg_like（Rust）中：使用共享核心模块实现相同的规划器行为。
• 在 mini_databricks_clone（Rust）中：使用共享 Rust 库代码实现相同的分层演示。
• 在 engine_cli（Rust）中：持久化快照 + WAL 重放流程，以及简单的运维命令。
• 在 engine_cli tx-demo 中：显式事务范围、快照读取、按表写锁，以及并发 upsert 冲突检测。
• 在 engine_cli tx-recovery-* 中：暂存的事务操作通过每个事务的日志文件跨进程重启保留，并且可以显式提交或回滚。
• 在 e2e_flow 中：一条命令即可运行写入路径、检查点、bronze->silver 转换、规划器 explain，以及对持久化数据进行 DuckDB SQL 验证。

技术设计基础

TECHNICAL_DESIGN_GENERIC.md 记录了代码背后的架构规范：

• 跨层推理（Idea -> API -> Runtime -> Storage -> Perf），
• 确定性的状态转换，
• 事件优先设计，
• 适配器契约，
• DAG 驱动的编排，
• 可衡量的 go/no-go 标准。

这不是一项独立的产品声明，而是整个实验室采用的评审与实现主线。

Docker 软件包

使用本地构建（推荐用于开发）

从此仓库构建镜像，使 MCP 使用你的本地代码（包括架构工具），而不是 GitHub 镜像：

./scripts/docker-build-local.sh

这会构建 mini-data-engine:local。若要通过此 MCP 驱动另一个项目（例如 threads），请将 Cursor MCP 设置为使用本地镜像，并将该项目挂载为工作区：

• 将 .cursor/mcp.docker.local.json 复制到项目的 .cursor/mcp.json 中（或将 mcpServers 条目合并到 Cursor 用户配置中）。
• 打开你要驱动的项目（例如 threads）。${workspaceFolder} 将指向该项目；容器会获得 WORKSPACE_ROOT=/workspace，并将你的项目挂载到 /workspace，因此例如 schema_path="schema.sql" 会解析为该项目中的文件。

本地配置示例（使用 mini-data-engine:local，并将当前工作区挂载到 /workspace）：

{
  "mcpServers": {
    "mini-data-engine": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "WORKSPACE_ROOT=/workspace",
        "-v", "${workspaceFolder}:/workspace",
        "-v", "${workspaceFolder}/tests/artifacts:/app/tests/artifacts",
        "mini-data-engine:local"
      ]
    }
  }
}

使用已发布的镜像（GHCR）

镜像已发布到 GHCR：

• ghcr.io/kroq86/data-engineering-runtime-lab:latest

拉取：

docker pull ghcr.io/kroq86/data-engineering-runtime-lab:latest

在 Cursor MCP 配置中使用（示例）：

{
  "mcpServers": {
    "mini-data-engine": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${workspaceFolder}/tests/artifacts:/app/tests/artifacts",
        "ghcr.io/kroq86/data-engineering-runtime-lab:latest"
      ]
    }
  }
}

Loom 技术栈

面向 loom-ops 和运维运行手册的 MCP 接口。生态系统：ECOSYSTEM.md

pip install ops-runtime-mcp
ops-runtime-mcp   # stdio MCP; see docs/use-in-codex.md