Project Bourne

Project Bourne

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

它回答的问题是：这项科学结果究竟是如何产生的？

让 AI 远离集群

Researcher's workstation
  Linux / macOS
        │
  AI / Agent (optional)
        │ local stdio MCP
        ▼
  Bourne Control Plane
        │
        ├─ freezes immutable ExecutionPlan
        ├─ builds/stages versioned Bourne workers
        └─ uses existing VPN / OpenSSH
        ▼

HPC login / access node
  one-shot Bourne Remote Worker
        │
        ├─ validates the plan
        ├─ verifies staged file digests
        ├─ stages the execution bundle
        └─ submits with sbatch / qsub / bsub
        ▼

Slurm / PBS / IBM LSF
        │
        │ allocates resources
        ▼

Compute allocation
  execution-scoped Bourne Compute Worker
        │
        ├─ reads immutable ExecutionPlan
        ├─ observes actual allocation
        ├─ reproduces selected environment
        ├─ performs compute-side preflight
        ├─ executes exact scientific argv
        └─ writes durable result evidence
        ▼

Scientific workload

Later:

Researcher's workstation
        │
        │ existing SSH
        ▼
Remote Worker: reconcile
        │
        ├─ exact Bourne-owned scheduler job state
        └─ bounded result evidence
        ▼
Local Bourne provenance database

远程 Worker 和计算 Worker 都不是 Agent 或持久服务，而是短期运行、带版本号的 Bourne Worker。Bourne 不会直接通过 SSH 连接计算节点。Slurm/PBS/LSF 会将计算 Worker 放入分配的资源中，并在接受提交后负责管理作业生命周期。研究人员的工作站／控制平面可能会断开连接，之后再对同一执行进行协调。

HPC 路径无需在集群上使用 AI、MCP 服务、AI 凭据、入站端口、root 访问权限、持久守护进程或公共互联网访问。它使用研究人员现有的 OpenSSH 配置和调度器访问权限。Agent 接收的是类型化的 Bourne 操作，而不是不受限制的远程 Shell。

Bourne 控制平面在 Linux 和 macOS 上受支持并经过测试。原生 Windows 尚未验证，也不受支持。

Bourne 原生支持 Agent，但不依赖 Agent。CLI 和 Python 服务无需 Agent 或 MCP 即可运行。

快速开始

人工操作

从 PyPI 安装 Project Bourne v0.8.1：

python -m pip install "bourneprov==0.8.1"

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

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

使用已安装的 CLI 配置适用于站点的 SSH 工作流：

bourne site add imperial \
  --ssh login.example.edu \
  --scheduler slurm \
  --local-root "$PWD" \
  --remote-root /work/$USER/project

bourne discover --site imperial
bourne plan --site imperial --request bourne.json --provider constraints.json

首次调用 plan 时会显示有界候选项。随后由人工或 Agent 明确做出偏好决策：

bourne plan --site imperial --request bourne.json \
  --provider constraints.json \
  --trust-provider-classifications \
  --candidate sha256:...

bourne execute --plan <plan-id>
bourne execution wait <execution-id>

信任标志用于明确审核声明式提供程序中的语义分类；提供程序不能自行授予自己这一权限。如需范围更窄的用户决策，请使用 --approve-variant-change PARAMETER 或 --declare-execution-only PARAMETER。如果所选候选项更改了绑定到提供程序的 JSON 输入，Bourne 会保留原始输入，并自动将单独哈希的 WorkloadVariant 绑定到计划。

Slurm/PBS/LSF 在接受作业后负责管理作业。研究人员的工作站／控制平面、VPN、SSH 连接、MCP 主机和 Agent 均可断开连接；Bourne 之后会重新连接，并对确切的执行进行协调。连接失败且状态不明时，绝不会盲目重新提交。

Agent / MCP

v0.8.1 的 Agent 和 MCP 入口仍使用本地 stdio：

python -m pip install "bourneprov[mcp]==0.8.1"
bourne mcp

# Or use the public transparent launcher:
npx -y @project-bourne/[email protected]

开发

Project Bourne 使用 uv 作为开发、依赖锁定、测试和构建前端。安装 uv 后，同步已提交的锁文件并运行测试套件：

uv sync --locked --all-extras --dev
uv run --frozen --no-sync python -W error::ResourceWarning -m unittest discover -s tests -v
uv build --no-sources

CI 使用这些命令的锁定／冻结版本，因此过期的 uv.lock 会导致失败，而不会产生依赖漂移。uv 仅用于开发：它不是 bourneprov 的运行时依赖，pip install 无需它，npm 启动器也不会使用它，并且在 HPC 登录节点或计算节点上始终不需要它。完整的贡献者工作流请参阅 CONTRIBUTING.md。

为什么选择 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

程序的标准输出和标准错误在执行期间仍会显示，并保存在实验记录中。

v0.8 中的运行时事实

v0.8 将规划事实、调度器事实、运行时事实、实验事实、验证和科学有效性分别处理。执行范围内的计算工作进程会记录带版本的进程、分配、CPU、内存、I/O、GPU 和环境证据，并明确标注覆盖状态为 observed、partially_observed、unavailable、unsupported 或 unknown。遥测缺失不会导致有效工作负载失败，也绝不会被伪造为零。

IBM LSF 与 Slurm 和 PBS 一样，支持有界队列发现、bsub、针对精确作业的活动 bjobs、近期已完成作业的 bjobs -a、持久化的 bhist 对账，以及 bkill。现有的 Apptainer/Singularity 镜像可以冻结到选定的站点感知计划中； Bourne 会在计算端验证现有运行时/镜像，并将科学命令作为精确 argv 传递。它不会构建、拉取、安装或管理镜像。v0.8 不会编排多节点容器启动、选择 MPI 启动器与容器的顺序，也不会注入 MPI 启动器。请参阅 运行时证据与调度器覆盖范围。

核心架构

Bourne Core 负责确定性执行、证据、规划、存储和来源追踪。CLI、SDK 和 MCP 是同一组服务之上的适配器：

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

远程工作进程是一次性、用户空间、非 AI、非守护进程。它只接受用于发现、计划验证、暂存、调度器提交和对账的带版本操作。科学命令在不可变计划中始终保持为精确 argv；不会将任何科学 argv 插入远程 shell 文本。 远程工作进程协议仍为 v1。v0.8 新增工作进程结果协议 v3 和暂存计划协议 v4，同时保留对已发布的工作进程结果 v1/v2 和暂存计划 v1/v2/v3 负载的读取支持。

Agent 与 MCP 集成

规范的本地 stdio 服务端是 bourne mcp。稳定的官方 MCP Registry 标识为 io.github.KozakHou/project-bourne，可移植的 Agent Skill 位于 skills/project-bourne。v0.8.1 npm 包与对应的 Registry 元数据使用相同的版本标识。

兼容 MCP 的 Agent 可以将“使用四块 GPU 运行此模拟并保留来源追踪”这类明确请求转换为 ExecutionRequest v2，请求 Bourne 规划、展示确定性的解析结果，并在确立执行意图后执行不可变计划。Bourne 本身不会解释不受约束的自然语言，也不会调用其他模型。

Agent 路径有意分为两个阶段：

agent intent → ExecutionRequest v2 → bourne_plan → inspect → bourne_execute_plan

规划不会运行工作负载，也不会悄然发现基础设施。模糊的目标和未知事实仍保持未解决状态。MCP 注解只是宿主端的 UX 提示；Bourne Core 仍会强制执行不可变计划、精确 argv、调度器作业归属、制品语义和来源追踪。请参阅 MCP 集成和 Agent 指南。

执行请求

现在可以通过一个有界、带版本的 JSON 请求来描述一次执行：

{
  "kind": "bourne.execution-request",
  "version": 2,
  "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-v2.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 和 --backend lsf。

直接执行会复用 Bourne 现有的实时输出、进程组、构件、谱系和实验溯源机制。Slurm、PBS 和 LSF 计划会使用随计划暂存的独立 Bourne 工作器。工作器会执行预检并记录实际分配的主机和科学实验；访问侧控制器会以事务方式导入其有界 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/LSF 目标类别摘要。未知的可执行文件会被通用记录，但不会运行。笔记本电脑、台式机和 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 记录的内容

每次实验都会记录：

• 执行状态（已完成、失败或中断）、确切的参数向量、 工作目录、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.8.0 打开较旧的 Bourne 数据库（包括已发布的 v0.1.1 至 v0.7.0 数据库）时，会通过事务确定性地迁移至架构 7。 现有实验、制品、血缘关系、清单、工作负载、计划、执行记录、调度器作业、 分配、事件和实验链接仍可读取。迁移不会为 v0.4 记录虚构 ExecutionRequest 历史。遇到未知或更新的架构版本时会明确报错；Bourne 绝不会重置现有数据库。每次新的发现都会创建单独的不可变快照。

许可证

Project Bourne v0.5.0 及更高版本根据 Apache 许可证 2.0 分发。v0.4.0 及更早版本仍遵循其发布时所依据的 MIT 许可证条款。详情请参阅 许可历史。

发布验证

发布版本为 0.8.1。基础运行时没有第三方依赖；MCP 支持仍是明确声明的可选 扩展。

运行源代码树测试：

uv sync --locked --all-extras --dev
uv run --frozen --no-sync python -W error::ResourceWarning -m unittest discover -s tests -v
uv build --no-sources

计算工作节点的 stdout 和 stderr 会实时输出，并在结果包中将每个捕获流限制为 8 MiB；截断会作为明确的运行时证据记录。普通本地 bourne run 保留现有的 捕获行为。磁盘暂存日志、自动制品发现/归档、科学依赖安装或源代码构建、通用 数据同步、不受限制的远程 shell、无需调度器且断开连接安全的远程监控、整个 资源分配范围的分布式遥测、队列/性能预测、任意验证脚本、托管式 HTTP MCP、 内嵌大模型以及广泛的科学有效性推断，仍不属于 v0.8 的范围。请参阅 运行时证据和调度器覆盖范围、 感知站点的架构和 VISION。

目前尚未进行实时 LSF 和实时 Apptainer 验证。运行时采样仅针对单次执行，不会 自动汇总多节点资源分配的数据。Bourne 不会注入 MPI 启动器，也不会自动选择 容器/MPI 的顺序。可移植的 LSF 内存/GPU 资源语法仍因站点而异，尚未解决。