内容
# 核糖体
**工具/运行时版本和MCP服务器的前置依赖物化工具。**
给定项目的声明运行时和MCP服务器，核糖体会解析和物化它们 **在任何工作流运行之前** —— 将运行时重复数据消除到共享池中，并将所有内容固定到一个可复制的锁定文件中 —— 因此，缺失的工具或无法解析的服务器会在验证阶段失败，而不是在执行过程中。
[](https://github.com/medullaflow/ribosome/actions/workflows/ci.yml)
[](https://www.gnu.org/licenses/agpl-3.0)
[](#状态)
---
## 为什么选择核糖体
生态系统已经有运行时管理器（mise、asdf、nix）和MCP客户端，它们读取 `server.json` 并启动服务器。 **没有人将两者统一起来**：解决您的运行时 *和* MCP服务器，重复使用共享运行时，并固定一个单一的可复制锁定文件 —— 在前端。
核糖体正好填补了这一空白。它 **在配置轴上符合** （其 `mcpServers` 部分是现有MCP配置格式的兼容超集），并且 **在运行时轴上竞争** （这些格式不提供的配置）。
## 两个仓库，刻意如此
- **[ribosome-schema](https://github.com/medullaflow/ribosome-schema)** —— **标准**：`ribosome.json`/`ribosome.lock.json` 的规范性JSON模式，遵从性语料库和TypeScript绑定。 **Apache-2.0** —— 在任何产品中实现它，无论是开源还是闭源，都没有义务。
- **ribosome（此仓库）** —— **参考解析器/编排器**：mise + MCP注册表适配器和物化管道。 **AGPL-3.0-or-later** —— 作为网络服务运行修改后的副本，您必须共享您的更改。
核糖体依赖于 `@medullaflow/ribosome-schema` 作为普通包，与依赖其他库的方式相同。此仓库 **不携带任何模式、JSON模式文件或遵从性测试** —— 请参阅 [ribosome-schema](https://github.com/medullaflow/ribosome-schema) 以获取这些。
## 安装
```bash
npm install @medullaflow/ribosome
```
> Pre-alpha: not yet published（见 [状态](#状态)）。`@medullaflow/ribosome-schema`，本仓库实现的 标准，已经发布 —— 见 [开发](#开发).
## 清单 —— `ribosome.json`
完整格式： [ribosome-schema](https://github.com/medullaflow/ribosome-schema).
```jsonc
{
"$schema": "https://schema.ribosome.medullaflow.org/v1/manifest.schema.json",
"schemaVersion": "1",
// 项目的工具版本 —— 以及MCP运行时的版本策略。
"runtimes": { "node": "24", "python": "3.12" },
// 命名MCP注册表以进行解析。
"registries": {
"default": "official",
"sources": { "official": { "url": "https://registry.modelcontextprotocol.io" } }
},
"mcpServers": {
// 从注册表通过反向DNS名称解析；注册表的server.json确定运行时、传输和启动。
"fs": { "source": "registry", "name": "io.modelcontextprotocol/filesystem", "version": "1.2.0" },
// 自定义服务器，用完整的标准server.json描述（声明其自己的运行时/包；可以干净地迁移到注册表稍后）。
"custom": { "source": "inline", "server": { /* server.json */ } },
// 从.mcp.json /编辑器配置的复制粘贴桥。
"legacy": { "source": "process", "command": "npx", "args": ["-y", "@foo/bar"] }
}
}
```
## 用法
```typescript
import {
validateManifest, // 从 @medullaflow/ribosome-schema 重新导出
Materializer,
MiseEnvironmentProvider,
OfficialMcpRegistry,
} from "@medullaflow/ribosome";
// 1. 验证非类型化输入与规范模式 —— 立即抛出每个错误，一次性完成，离线（无网络往返）。
const manifest = validateManifest(JSON.parse(rawRibosomeJson));
// 2. 连接所需的适配器（此处为mise；可自由交换）并物化。
const materializer = new Materializer({
environmentProvider: new MiseEnvironmentProvider(),
registries: [new OfficialMcpRegistry()],
});
const lock = await materializer.materialize(manifest, { cwd: projectRoot });
// lock.runtimePool —— 消除重复的运行时，精确版本
// lock.project —— 项目的环境视图（pathPrepend + envVars)
// lock.mcpServers —— 解析的服务器：启动命令 + 隔离环境
```
> **Pre-alpha:** `MiseEnvironmentProvider` 是真实的（通过真实的mise安装；与真实的mise集成测试），注册表适配器和编排管道仍然抛出 `not implemented`。见 [状态](#状态).
## 它是如何工作的
核糖体是一种 [端口和适配器](https://alistair.cockburn.us/hexagonal-architecture/) 设计，与没有具体的工具耦合：
| 层 | 角色 |
|-------|------|
| **[ribosome-schema](https://github.com/medullaflow/ribosome-schema)** （外部） | 标准：规范性JSON模式，生成的类型，验证。 |
| **端口** | 抽象：`EnvironmentProvider`，`McpRegistry`. |
| **适配器** | 实现：mise，官方MCP注册表。可交换。 |
| **编排器** | 分阶段的管道，发出锁定文件。 |
运行时被重复使用到 **共享池**；项目和每个MCP服务器都获得 **隔离环境视图**。MCP服务器的运行时 **从注册表派生** （`server.json`），而不是由您重新声明。
**→ 完整设计，图表和决策： [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).**
## 项目布局
```
src/
├── ports/ 抽象 —— EnvironmentProvider，McpRegistry
├── adapters/ 实现 —— mise/，mcp-registry/
└── orchestrator/ 分阶段的物化管道
```
标准（模式，生成的类型，验证，遵从性语料库）位于单独的 [ribosome-schema](https://github.com/medullaflow/ribosome-schema) 仓库中，不在此处。
## 状态
| 部分 | 状态 |
|------|-------|
| 标准（ribosome-schema）：模式，验证，遵从性语料库 | **真实** —— 已测试，在其自己的仓库中 |
| 端口（`EnvironmentProvider`，`McpRegistry`） | **真实** 接口 |
| `MiseEnvironmentProvider` | **真实** —— 与真实的mise安装集成测试 |
| 注册表适配器，编排管道 | **骨架** —— 存根抛出 `not implemented` |
路线图：实现mise适配器（`mise install`/`where`），注册表HTTP适配器和分阶段编排器。见 [ROADMAP.md](ROADMAP.md).
## 开发
```bash
git clone https://github.com/medullaflow/ribosome && cd ribosome
bun install # 还会连接pre-commit SPDX-header + lint检查；@medullaflow/ribosome-schema从npm解析
bun run build # tsc —— 仍然是dist/的类型检查源，是npm可嵌入的工件
bun run test # 构建，然后运行真正的测试套件（包括实时mise集成测试）
bun run compile # bun build --compile —— 证明独立二进制路径仍然有效
bun run lint # Biome —— lint + 格式化 + 导入组织检查
```
此仓库自己的开发/构建/测试工具链完全运行在 **[bun](https://bun.sh)** 上，而不是Node —— 见 [`docs/ARCHITECTURE.md` D14](docs/ARCHITECTURE.md#设计决策). `npm install @medullaflow/ribosome`（上文）仍然适用于消费者：`tsc` 仍然发出一个普通的，可移植的 `dist/` 以嵌入任何Node/TS主机：bun是此仓库自己的工具链选择，而不是对消费者的要求。
见 [CONTRIBUTING.md](CONTRIBUTING.md) 贡献/归属工作流和DCO签到。
### 由人类和代理共同构建
此仓库旨在由 **人类和LLM编码代理** 共同开发 —— 大部分代码由代理编写。这决定了它的构建方式：标准工具只能 **建议** 的约定正在转换为确定性，机器强制的防护栏（linting，架构边界检查，类型安全性和测试充分性门控），因此更改无法合并同时破坏架构，无论谁或什么编写它。该工作在 [防护栏和治理里程碑](https://github.com/medullaflow/ribosome/milestones).
在此仓库中工作的代理应首先阅读 **[AGENTS.md](AGENTS.md)** —— 机器可读的操作合同（工具链，设置，命令和代理无法从代码推断的硬约束）。它是代理面向的对应 [CONTRIBUTING.md](CONTRIBUTING.md).
## 为什么是“核糖体”？
核糖体是细胞的依赖物化器：它们接受声明（mRNA）并将其转换为工作机械（蛋白质）。这里的想法相同。
## 许可
AGPL-3.0-or-later —— 见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE). 此仓库是参考 **实现**；它实现的 **标准** ([ribosome-schema](https://github.com/medullaflow/ribosome-schema)) 是一个单独的Apache-2.0仓库，没有此类义务。见 [CONTRIBUTING.md](CONTRIBUTING.md#为什么-agpl) 了解原因。
核糖体是 [medullaflow](https://github.com/medullaflow/medullaflow) 项目的组成部分，旨在单独重用。
## 归属
**主要作者：** Matteo Lacchio — [@ookmash](https://github.com/ookmash). 主要作者和版权： [AUTHORS](AUTHORS). 完整的贡献者列表：仓库的 [贡献者图](https://github.com/medullaflow/ribosome/graphs/contributors).
---
由 Matteo Lacchio 和贡献者共同创建。
