内容
# 🪨 rockie-nugget
**一款用于长期、自主人工智能研究的开放式框架。**
rockie-nugget 是一个薄、与模型无关的智能体运行时，旨在执行一项任务：运行一个可以进行 *真正研究* 的人工智能智能体 — 读取文献、编写代码、启动 GPU 实验、读取指标并迭代 — 数小时不停顿。它可以在你的笔记本电脑、服务器上运行，或作为 Rockie 平台上的每个租户的运行时。
> **状态：早期，公开开发中。** 下面的架构是我们正在构建的目标，部分功能仍在完善中。如果您从事自我改进的人工智能、智能体研究或研究智能体评估，这正是您参与的最佳时机 — 请参阅 [协作](#协作)。
---
## 为什么需要另一个框架？
因为框架不应该是有趣的部分。过去两年的经验告诉我们，复杂的智能体脚手架会被更好的模型所取代 — 因此 rockie-nugget 故意保持 **简单**，并将杠杆作用放在持久的地方：
- **与模型无关。** 将其指向任何与 OpenAI 兼容的端点 — 前沿模型、廉价的开放权重模型或您自己的本地服务器。带上您自己的密钥。
- **MCP 原生。** 工具是 [模型上下文协议](https://modelcontextprotocol.io) 服务器。智能体的整个能力集是一个声明性、版本化的工具合约 — 请参阅 [`contract/`](./contract/research-env-v1/)。
- **技能只是 Markdown。** Rockie 技能生态系统是纯 `.md` 文件 — 读取、fork、编写您自己的。无需 DSL，无需锁定。
- **旨在成为评估 *和* 训练环境。** 同一个框架可以服务于任务，可以衡量模型在研究方面的表现，也可以（在我们这边私密地）训练一个模型。
## 智能体实际执行的操作
每个步骤，智能体从一个小的、固定的工具菜单中选择一个操作 — [`research-env-v1`](./contract/research-env-v1/) 动作空间：
| 动词 | 工具 |
|---|---|
| 收集 | `web_search`, `fetch_url`, `read_file`, `list_files` |
| 编写 | `write_file` |
| 运行 | `run_command`（沙箱） |
| 实验 | `submit_job`, `get_job` — 预置 GPU 运行，读取其结果 |
| 完成 | `finish` |
这足以完成真正的事情：阅读论文，实现想法，启动训练运行，读取指标，决定下一步。GPU 实验是 **提供者无关的** — 智能体请求 `8xH100`，运行时决定 *在哪里* 预置它（您看不到，也无需关心哪个云回答了）。
## 快速入门
> 自带密钥（BYOK）。安装程序需要一个 **Linux x86_64 主机，glibc ≥ 2.36** （Debian bookworm，Ubuntu 22.04+）和 `python3` — 运行时是一个 Linux 二进制文件。原生 `cargo install` 正在计划中（[#1953](https://github.com/Rockielab/rockie-nugget/issues/1953)）。
```bash
# 安装（从此检查点组装运行时 + 工具表面 — 仅配置）
git clone https://github.com/Rockielab/rockie-nugget.git
cd rockie-nugget
./install.sh
# 将 ~/.local/bin 添加到 PATH（如果尚未添加）
export PATH="$HOME/.local/bin:$PATH"
# 将其指向任何与 OpenAI 兼容的模型（前沿模型、开放权重模型或您自己的服务器）— 自带密钥
export OPENAI_BASE_URL=https://api.your-provider.com OPENAI_API_KEY=sk-...
# 运行研究任务
nugget run "重现 learned-representations 存储库中的排名富集结果，并提出一个可以提高有效排名的实验。"
```
`install.sh` 获取 sha-verified Goose 运行时到 `~/.local/bin/goose`，将此存储库的 [`research-env-v1` MCP 服务器](./mcp/research-env-mcp/) 注册为智能体的工具表面，位于 `~/.config/goose/config.yaml` 中，安装 **Rockie 叠加层**（如下），并安装一个 `nugget` 启动器，将您的 BYOK 环境映射到 Goose 提供者（`OPENAI_*` → openai，`ANTHROPIC_API_KEY` → anthropic）。重新运行是幂等的。可以在无头状态下运行，进行长期工作。
## Rockie 叠加层
裸 Goose 是一个有能力的智能体；**叠加层**（[`overlay/`](./overlay/)）使其具有 Rockie 的思维方式。它仅限于配置 — 本地安装程序复制到 `~/.config/goose/` 的文件与平台挂载的文件相同，因此 **本地安装 ≡ 平台运行时**。
- **`overlay/goosehints`** — 精神。硬规则，**计划 → 研究 → 构建 → 审计 → 运行 → 评估 → 编码** 循环，预实验检查清单和头脑风暴 → 研究 → 攻击 → 验证瀑布流。每次加载。安装程序将其合并到 `~/.config/goose/.goosehints` 下一个托管的哨兵块中，因此您的提示永远不会被覆盖。
- **`overlay/recipes/`** — 可组合的任务模板：`autoresearch.yaml`（冻结度量循环），`experiment.yaml`（预实验门控 → `submit_job` → 轮询 → 报告），和 `clean.yaml`（反拖累前提交传递）。使用 `goose run --recipe <file>` 运行一个。
- **`overlay/memory/` + 内置内存扩展** — 持久的跨会话内存。智能体发出 `[LEARN]` / `[DEAD-END]` 块；`Stop` 钩子（[`overlay/hooks/capture.sh`](./overlay/hooks/)) 将它们附加到纯文本内存中，以便下一个会话回忆。无需数据库 — 纯文件，刻意为之。
叠加层没有命名模型标识或提供者 SKU：它是完全与模型无关的，因此无论您是在本地运行 BYOK 还是在平台上运行服务端模型，它的工作方式都相同。
## 评估模型的科研能力
rockie-nugget 配备了一个 **评估环境**，您可以衡量 *任何* 模型在 *框架内* 进行研究的能力 — 不是在排行榜上抽象地衡量，而是在实际运行的循环中。适配器模式是一个 3 文件合约（`prepare` / `run` / `grade`）；请参阅 [`eval/adapters/super/`](./eval/adapters/super/) 中针对开放 [SUPER](https://github.com/allenai/super) 基准测试的示例适配器。适配器针对开放的研究智能体基准测试：
- **RE-Bench** (METR) — 真实的 ML 研发工程（内核，缩放律）
- **ScienceAgentBench** — 来自真实论文的数据驱动科学任务
- **SUPER** (allenai) — 建立和运行来自野外的研究存储库 *(已附带适配器)*
- **MLE-bench** — Kaggle 风格的 ML 工程
```bash
# 在 BYOK 模型上运行 SUPER 适配器（3 文件 prepare/run/grade 合约）
eval/adapters/super/prepare.sh && eval/adapters/super/run.sh # 一个模型，一个框架，一个数字
```
> 一个单一的 `nugget eval <bench>` 前端程序来管理这些适配器正在开发中；今天适配器直接运行。
我们认真对待的一点是：**框架本身会移动基准分数十位**，因此 rockie-nugget 的评估始终一次更改一个变量 — 修复框架以比较模型，修复模型以比较框架更改。来自移动框架的分数是噪音。
## 它与 Rockie 如何融合
rockie-nugget 是开放的，可以在任何地方运行。 [Rockie](https://rockielab.com) 平台添加了需要后端的部分：
- **技能** — Markdown 研究工具链（开放）。
- **`mcp-rockie`** — 用于将智能体调度到 24/7 运行时和通过 Rockie **配置 GPU** 的 MCP 服务器。
- **Rockie 模型** — 一个 Rockie 主持的模型，我们正在为长期研究调优。使用 Rockie 平台上的端点，通过 rockie-nugget 指向它；使用情况通过您的 Rockie 积分计量。
您可以完全在本地运行 rockie-nugget，使用您自己的模型，并且永远不需要触摸平台 — 这就是目的。当您通过 Rockie 配置计算资源或使用托管模型时，Rockie 会赚取其价值，而不是通过框架锁定。
## 架构
```
您的任务
│
▼
┌─────────────────────────────────────────────┐
│ rockie-nugget 循环 （薄、与模型无关） │
│ 提示 → 模型 → 工具调用 → 结果 → … │
└───────────────┬─────────────────────────────┘
│ 冻结的、版本化的工具合约（MCP）
▼
web · 文件 · run_command · submit_job/get_job · 完成
│
▼ （GPU 工作与提供者无关 — 云对智能体隐藏）
Rockie GPU 配置 / 您自己的计算
```
智能体只会看到一个统一的工具表面。所有因非研究原因而变化的内容 — 哪个 GPU 云，连接详细信息，凭证 — 都被推送到 **工具边界以下**，因此轨迹看起来相同，无论在哪里运行。（同样的属性使环境也可以作为我们这边干净的训练数据。）
## 存储库布局
| 路径 | 内容 |
|---|---|
| [`overlay/`](./overlay/) | Rockie 叠加层（仅限配置）：精神 `goosehints`，研究 `recipes/`，内存支架 + 捕获 `hooks/`。这将裸 Goose 转换为 Rockie 框架。 |
| [`contract/`](./contract/) | 版本化的工具合约 (`research-env-v1`) — JSON 模式，清单和版本控制规则。这是智能体的动作空间。 |
| [`mcp/research-env-mcp/`](./mcp/research-env-mcp/) | 一个小的标准库 Python 标准输入/输出 MCP 服务器，暴露合约的工具给任何 MCP 原生智能体（例如 Goose）。 |
| [`eval/adapters/`](./eval/adapters/) | 基准测试适配器 — 用于在框架内评估模型的 3 文件 `prepare` / `run` / `grade` 模式。 |
## 协作
rockie-nugget 是公开构建的，其中最有趣的开放问题是研究问题，而不是工程问题：长期研究的奖励设计，抗污染评估，以及智能体的工具表面应该是什么。如果您是从事自我改进人工智能、智能体研究或智能体评估的研究人员，**我们希望与您一起构建这个项目，而且我们是认真的。** 打开一个问题，领取一个 [良好的初始问题](./CONTRIBUTING.md#good-first-issues)，或联系 [rockielab.com](https://rockielab.com) 团队。
参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 以了解如何开始，[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) 以了解社区期望。
## 许可证
[Apache License 2.0](./LICENSE)。rockie-nugget 建立在
[Goose](https://github.com/block/goose) （© Block, Inc., Apache-2.0）之上；请参阅
[`NOTICE`](./NOTICE) 以了解归属。
*rockie-nugget 是 Rockie / Pebble ML 堆栈的一部分。 🪨 堆栈上的另一块岩石。*
