Project Bourne

Project Bourne 是面向可复现科学与工程工作负载的开源执行与溯源基础设施。

它能够在本地机器、GPU、Slurm 和 PBS 上规划并执行计算实验，同时保留输入、输出、执行上下文、工件谱系、遥测、验证以及复现结果所需的历史信息。

它面向研究人员、从本科到博士阶段的学生、教师、研究工程师、计算科学家、科学软件用户，以及学术界、公共研究和产业研发领域的科学计算团队。

快速开始

人类用户

人类 CLI 现已公开：

python -m pip install bourneprov

bourne run python examples/demo.py
bourne list
bourne show @1

# Or execute an ExecutionRequest v1 document:
bourne execute --request bourne.json

智能体 / MCP

v0.6.0 智能体与 MCP 入口现已公开：

python -m pip install "bourneprov[mcp]==0.6.0"
npx -y @project-bourne/mcp@0.6.0

如需从源码检出进行开发，请使用：

python -m pip install -e ".[mcp]"
bourne mcp

Related MCP server: heddle

为什么选择 Bourne

Bourne 包装任意可执行文件，无需修改科学程序本身。它采用本地优先且与框架无关的设计：Python、编译求解器、Julia、MPI 程序以及其他命令均使用相同的持久化实验模型。

bourne run bash -c "echo hello"
bourne run ./solver case.yaml
bourne run julia simulation.jl
bourne run mpirun -np 64 ./solver

程序的 stdout 和 stderr 在执行期间保持可见，并保存在实验记录中。

架构

Bourne Core 负责确定性执行、规划、存储和溯源。人类可以通过 CLI 或 Python 服务使用它；智能体可以通过可选的 MCP 适配器使用相同的服务：

             Project Bourne Core
                    │
       ┌────────────┼────────────┐
       │            │            │
      CLI          SDK          MCP
    humans                     agents

智能体接口是可选的访问路径，而非 Bourne 的产品定位。MCP 无需便携式 Skill 即可工作，Bourne 也不包含嵌入式 LLM。

智能体与 MCP 集成

规范的本地 stdio 服务器是 bourne mcp。稳定的官方 MCP Registry 标识为 io.github.KozakHou/project-bourne，便携式 Agent Skill 位于 skills/project-bourne。v0.6.0 npm 包及对应的 Registry 条目均已公开。

兼容 MCP 的智能体可以将诸如"使用四块 GPU 运行此模拟并保留溯源"这样的显式请求转换为 ExecutionRequest v1，要求 Bourne 进行规划，展示确定性解析结果，并在确立执行意图后执行不可变计划。Bourne 本身不解释无约束的自然语言，也不会调用其他模型。

智能体路径刻意采用两阶段设计：

agent intent → ExecutionRequest v1 → bourne_plan → inspect → bourne_execute_plan

规划阶段绝不运行工作负载，也不会静默发现基础设施。模糊的目标和未知的事实保持未解析状态。MCP 注解是宿主 UX 提示；Bourne Core 仍然强制执行不可变计划、精确 argv、调度器作业所有权、工件语义和溯源。参见 MCP 集成 和 智能体指南。

执行请求

执行现在可以用一个有界、版本化的 JSON 请求一次性描述：

{
  "kind": "bourne.execution-request",
  "version": 1,
  "command": ["python", "train.py", "--case", "case1"],
  "artifacts": {
    "inputs": ["config.yaml"],
    "outputs": ["result.h5"]
  },
  "resources": {"cpus": 8, "gpus": 1, "walltime": "2h"},
  "execution": {"backend": "direct"},
  "verification": {
    "checks": [
      {"type": "output_exists", "path": "result.h5"},
      {"type": "output_min_bytes", "path": "result.h5", "min_bytes": 1024}
    ]
  }
}

将其保存为 bourne.json，然后对规划或执行使用相同的意图：

bourne request validate bourne.json
bourne request show bourne.json

bourne discover
bourne plan --request bourne.json
bourne execute --request bourne.json

创建最小请求而不执行或发现任何内容：

bourne request init --output bourne.json -- python train.py
bourne request schema > execution-request-v1.schema.json

现有的基于标志的命令仍然受支持。它们编译到相同的 ExecutionRequest → WorkloadSpec → ExecutionPlan 流水线中，而非并行实现：

bourne execute --backend direct --cpus 2 --output result.txt -- python script.py

对于请求文件，相对 working_directory 从请求文件所在目录解析。声明的工件随后从该科学工作目录解析。Bourne 同时保留词法和工作目录的解析值，并且在解析或规划期间不会展开 $HOME、求值 shell 语法、导入项目代码或执行任何内容。

父引用遵循相同的意图保留规则。请求可以使用 latest、@N、唯一前缀或完整 ULID。Bourne 保留该请求值，同时单独记录编译后工作负载所使用的规范父 ULID。

摘要遥测默认启用，并使用已捕获的事实：墙钟时间、UTF-8 stdout/stderr 字节数、已知工件字节总数、请求的资源、观察到的分配以及时间戳可确定时的调度器队列时序。"telemetry": {"mode": "off"} 可禁用摘要。缺失的指标保持不可用状态，绝不会为零。

初始的确定性验证检查是 output_exists、output_min_bytes 和 output_sha256。它们仅评估已捕获的声明输出 Artifact 记录。验证与进程状态分开持久化：实验可以是 completed 状态而验证为 failed 或 unknown 状态。这些检查确立工件事实，而非一般科学有效性。有关确切契约和安全限制，请参见 执行请求、遥测和验证。

规划与执行

Project Bourne v0.4.0 在 v0.3 清单之上增加了持久化规划层：

bourne discover

bourne plan --backend direct -- python examples/demo.py
bourne execute --backend direct -- python examples/demo.py

bourne execution list
bourne execution show @1

bourne plan 绝不运行科学命令，也绝不执行发现。它创建与框架无关的 WorkloadSpec，将其显式和推断的需求与现有清单进行比较，解释每个候选方案，并且仅在选择无歧义时持久化不可变的 ExecutionPlan。需要时使用显式资源和放置约束：

bourne plan \
  --backend slurm \
  --target gpu \
  --cpus 16 \
  --gpus 4 \
  --nodes 1 \
  --memory 64G \
  --walltime 2h \
  -- ./solver case.yaml

执行选定的 Slurm 计划，然后检查或等待生成的执行尝试：

bourne execute --plan @1
bourne execution show @1
bourne execution wait @1

当已记录的作业仍处于活动状态时，bourne execution cancel @1 请求取消该 Bourne 管理的作业。相同的规划和生命周期模型支持 --backend pbs。

直接执行复用 Bourne 现有的实时输出、进程组、工件、谱系和实验溯源机制。Slurm 和 PBS 计划使用随计划一起暂存的独立 Bourne worker。worker 执行预检并记录实际分配的主机和科学实验；访问端控制器以事务方式导入其有界 JSON 结果。无需计算节点 SSH 或预装的 bourneprov 包，尽管计算分配必须提供 Python 3 以及对暂存和工作目录的可见性。

提交不是实验，调度器完成不是科学成功，请求的资源也不是已分配的资源。Bourne 将这些记录为独立的持久化事实。取消接受 Bourne 执行引用——而非任意调度器作业 ID——并检查提交身份。有关确切模型、安全边界和当前限制，请参见 工作负载规划与调度器执行。

计算站点发现（v0.3.0）

Bourne 可以获取当前身份可见的执行表面的不可变本地快照：

bourne discover
bourne inventory
bourne inventory --find python
bourne inventory --json

发现涵盖当前身份和访问目标、允许列表中的用户相关存储路径、直接执行上下文、通用 PATH 可执行文件、可选的 Conda/virtualenv/容器/模块上下文、安全系统能力、Bourne 历史以及可用时的只读 Slurm/PBS 目标类摘要。未知可执行文件被泛化记录而不运行。笔记本电脑、桌面和 GPU 工作站、DGX 级个人机器、共享实验室系统以及基于调度器的 HPC 站点都是有效的计算站点。无调度器的机器本身就是一个完整的站点。

发现是观察性的：可执行文件不验证工作负载兼容性，可见的调度器分区不证明提交授权，存储角色提示也不是保留或备份策略。清单保持本地。提供者不会遍历其他用户的主目录、爬取共享存储、检查 SSH 凭据或容器密钥、转储任意环境变量、SSH 进入计算节点、提交或取消调度器作业，也不会修改环境。有关确切拓扑、证据、限制和安全语义，请参见 计算站点发现。

溯源、工件与谱系

Project Bourne v0.2 增加了显式输入/输出指纹、最小化的 derived_from 关系、安全的执行上下文观察和工件追踪。从隔离目录运行确定性示例：

cp -R examples/provenance /tmp/bourne-provenance-demo
cd /tmp/bourne-provenance-demo
export BOURNE_DB="$PWD/bourne.sqlite3"

bourne run \
  --input config_A.json \
  --output result_A.csv \
  -- python demo_simulation.py config_A.json result_A.csv

bourne run \
  --derived-from @1 \
  --input config_B.json \
  --input result_A.csv \
  --output result_B.csv \
  -- python demo_simulation.py config_B.json result_B.csv

bourne show @2
bourne show @1
bourne trace result_B.csv

输入在执行前进行指纹计算。输出在执行后进行指纹计算，包括失败或中断运行后缺失的预期输出。SHA-256 读取以分块流式进行；Bourne 不会复制或上传声明的文件。

路径不是工件身份。每次捕获都有稳定的 ULID，而 SHA-256 区分内容版本。当历史路径可能标识多个版本且当前文件内容无法消除歧义时，bourne trace 会列出候选并拒绝猜测。

有关确切的捕获、追踪、迁移和安全语义，请参见 工件、谱系和执行上下文。

人类友好的实验引用

规范的实验标识仍然是 26 字符的 ULID。接受实验的命令也理解：

01M02GDJEW...   case-insensitive unique ULID prefix
latest          most recent experiment
@1              most recent experiment
@2              second-most-recent experiment
@3              third-most-recent experiment

例如：

bourne show latest
bourne show 01M02GDJEW
bourne compare @2 @1
bourne run --derived-from @1 -- ./solver case_B.yaml

当前缀有歧义时，Bourne 绝不猜测。bourne list 默认显示 10 字符前缀；bourne list --full-id 显示规范 ID。

Shell 补全

补全候选包括规范实验 ID、latest 和最近的 @N 引用。为当前 shell 会话激活补全：

# Bash
source <(bourne completion bash)

# Zsh
source <(bourne completion zsh)

# Fish
bourne completion fish | source

bourne show 和 bourne compare 的补全会查询当前配置的数据库，包括 BOURNE_DB。

Bourne 记录的内容

每个实验记录：

• 执行状态（completed、failed 或 interrupted）、精确参数向量、工作目录、UTC 时间戳、持续时间和退出码；

• 实时和捕获的 stdout/stderr；

• Git 仓库根目录、提交、分支和脏状态（可用时）；

• 操作系统、架构、主机名、CPU 和可选的 NVIDIA 运行时元数据；

• 请求和解析的可执行路径以及严格允许列表中的 virtualenv/Conda 上下文提示；

• 显式声明的输入/输出工件版本和直接谱系。

收集器优雅降级。缺少 Git、NVIDIA 工具、GPU、环境提示或可执行文件解析不会阻止工作负载运行。任意环境变量不会被持久化，因此凭据和令牌默认不会被捕获。

失败和中断的命令在 bourne 返回其进程语义之前被保存：

bourne run --output expected.csv -- python -c "raise RuntimeError('boom')"
bourne show @1

在 POSIX 系统上，Bourne 使用专用进程组，因此 Ctrl+C 通常终止后代进程而不会影响不相关的进程。

执行成功不是验证，确定性工件验证也不是一般科学有效性。Bourne 分别记录这些状态。

本地存储与迁移

默认 SQLite 路径为：

~/.local/share/bourne/experiments.sqlite3

使用项目特定数据库：

export BOURNE_DB=/path/to/experiments.sqlite3

使用此发布候选版本打开 v0.1.1、v0.2.0、v0.3.0 或 v0.4.0 数据库会执行确定性的事务性迁移，直至 schema 5。现有的实验、工件、谱系、清单、工作负载、计划、执行、调度器作业、分配、事件和实验链接保持可读。迁移不会为 v0.4 记录凭空生成 ExecutionRequest 历史。未知或更新的 schema 版本会显式失败；Bourne 绝不会重置现有数据库。每次新的发现都会创建独立的不可变快照。

许可证

Project Bourne v0.5.0 及更高版本根据 Apache License 2.0 分发。截至 v0.4.0 的版本仍按其发布时的 MIT License 条款分发。详情请参见 许可历史。

发布验证

仓库版本为 0.6.0。基础运行时零第三方依赖；MCP 支持仍然是显式的可选附加项。

使用以下命令运行源码树测试：

PYTHONPATH=src python -W error::ResourceWarning -m unittest discover -s tests -v

stdout 和 stderr 在最终持久化之前仍会在内存中累积。磁盘暂存的实验日志、自动工件发现、工件归档、自动科学依赖安装、自动模块加载、容器编排、SSH 执行、远程复制、利用率采样、性能分析、任意验证脚本、广泛的科学有效性推断、托管 HTTP MCP、嵌入式 LLM 和自然语言解析仍不在 v0.6.0 的范围内。更长期的方向请参阅 docs/VISION.md。