Research Compute Fabric (RCF)

给 AI Agent 用的科研算力控制面：先计划、再确认、可追溯。

RCF 把本机、SSH 工作站（含 WSL）和 Slurm 集群收进同一套 CLI 与 stdio MCP 接口。它不取代调度器， 也不要求远端常驻服务；配置用 TOML，计划、运行、GPU 租约与审计用 SQLite。

Agent / CLI → RcfService → 配置、计划、SQLite、审计
                            ├─ Local 进程
                            ├─ SSH + 状态文件
                            └─ Slurm 客户端命令

为什么不是又一个 sbatch 包装器

提交一条命令很容易，难的是回答：

• 这次跑的是哪份代码、哪个环境、哪批输入？

• 命令会在哪台机器、哪个目录、用哪张 GPU 执行？

• 提交回执丢了，作业是没跑、在跑，还是已经结束？

• 产物在哪、能不能复现，旧文件能不能安全清理？

RCF 把这些答案放进同一条链路：plan → review → submit → observe。所有执行先有一份可审阅的 计划，计划里包含命令预览、工作目录、资源需求、环境指纹和阻塞项；提交必须显式确认； 运行状态从执行器重新读取，不拿数据库里的旧值冒充事实。

Related MCP server: secure-cluster-mcp

能做什么

安装

需要 Python 3.11+。仓库带 uv.lock，推荐用 uv：

cd research-compute-fabric
uv sync
uv run rcf --help

没有 uv 时也可以用虚拟环境：

python -m venv .venv
# Linux / macOS
.venv/bin/python -m pip install -e .

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .

安装依赖可能需要网络，请只在你允许的环境中执行；RCF 不会自行下载依赖，也不会连接未登记的节点。 安装后可直接使用 rcf；如果没有激活虚拟环境，用 uv run rcf 或虚拟环境中的绝对路径。

5 分钟本机演示

uv run python examples/quickstart.py

脚本会在系统临时目录创建独立的 RCF home，用当前 Python 运行 examples/demo/compute.py， 执行一次 1000 步的 CPU 小任务，并核对确定性结果。它不连接远程节点，临时目录会保留供检查。

输出类似下面这样（路径和 ID 因机器而异）：

Isolated RCF home retained at: .../rcf-example-...
Plan plan_...: ...
Run run_...: succeeded
Completed 1000 steps; result written to the declared output directory
Verified result: .../outputs/result.json

这证明本机链路可用，不代表远程集群、GPU、MPI 或你的项目环境已经验证。

配置与第一次真实运行

uv run rcf init        # 生成 ~/.rcf/{rcf,nodes,projects,environments}.toml
uv run rcf doctor      # 检查配置、依赖与安全姿态

按 examples/ 修改自己的 RCF home。示例里的 /home/researcher、/path/to/checkout 和 example-* 都是占位符，必须替换；不要把实际配置提交到仓库。

--home 是全局参数，要放在子命令之前：

rcf --home /path/to/private-rcf-home doctor

一次运行的最小闭环：

rcf run plan --project demo --node local \
  --param steps=1000 --param seed=1 --minutes 1
rcf run submit PLAN_ID --yes
rcf run status RUN_ID
rcf run logs RUN_ID
rcf run results RUN_ID

PLAN_ID / RUN_ID 用上一步实际返回值替换，不是可以直接执行的字面参数。submit 只接受 plan_id，不接受临时拼的命令行；计划默认 30 分钟后过期，过期后应重新 plan。

接入新机器前，先手动 ssh 一次并核对主机指纹，再运行：

rcf node inspect NODE
rcf node selftest NODE   # 约 10 秒，只验证控制路径与目录，不提交作业

接入 Agent（MCP）

rcf mcp serve（等价 rcf-mcp）启动 stdio MCP server。当前暴露 29 个工具，覆盖节点探测、 计划/提交/状态/日志、环境、项目同步、结果回收、存储治理和进度/ETA。

Claude Code 或其他兼容 stdio 的客户端示例：

{
  "mcpServers": {
    "rcf": {
      "command": "rcf",
      "args": ["mcp", "serve"],
      "env": { "RCF_HOME": "/home/you/.rcf" }
    }
  }
}

Windows 把 RCF_HOME 写成 C:/Users/you/.rcf；如果 rcf 不在 PATH，使用虚拟环境中的 绝对路径。rcf mcp tools 可查看当前工具清单，完整配置、工具表和 Agent 工作循环见 Agent 接入指南。

安全边界（先读这一段）

RCF 不是沙箱。任务以当前账户权限运行；危险命令检测、日志脱敏都是启发式，不是安全隔离。

已经强制的约束：

• 计划与执行分离：plan_run 无副作用，submit_run 需要 confirm 且计划中没有阻塞项；

• 配置中没有密码、私钥或 token 字段，SSH 主机密钥验证永不放宽；

• 环境写入按路径所有权与显式确认放行，[environments].managed_roots 默认为空；

• 有副作用的操作写审计；RCF 内部 GPU 租约用 SQLite 部分唯一索引避免重复占用。

明确不保证：多用户隔离、恶意脚本防护、远程文件防篡改、全局 GPU 调度、跨机断点续传、 自动备份/清理，以及多节点 MPI 的普适兼容。完整清单见安全模型与边界 和验收状态。

项目状态

当前版本 0.1.0，处于公开候选阶段：离线回归与模拟执行器已有覆盖；原生 Linux/macOS、 远端 CI 和真实计算节点尚未在本轮公开验收中声明通过。能力、测试入口和已知限制以 docs/status.md 为唯一可信来源。

文档

仓库结构

src/rcf/       服务层、执行器、运行管理、进度证据、存储治理
docs/          深入文档（从 docs/README.md 进入）
examples/      本机快速开始、示例配置与 CPU demo
tests/         离线/模拟执行器测试；真实设备测试默认不启用
tools/         公开材料扫描与发布候选验收

开发前请读开发规范。测试默认不连接真实节点；真实设备验证需要单独授权。

许可证

MIT，见 LICENSE。