# @crossdelta/platform-sdk 中文文档

规范地址：https://npmcn.com/package/%40crossdelta/platform-sdk/

版本：0\.26\.15
npm 元数据更新时间：2026-11-04T05:48:14.103Z
中文译文更新时间：2026-11-11T01:34:52.498Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crossdelta/platform-sdk
原文对照：https://npmcn.com/package/%40crossdelta/platform-sdk/?lang=original
项目主页：https://www.npmjs.com/package/@crossdelta/platform-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：628 kB，96 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=21\.0\.0
- 运行依赖：21 个
- peer 依赖：turbo ^2\.0\.0，@nestjs/schematics ^11\.0\.5
- 首次发布：2025-11-30T21:26:51.126Z
- 最新版本发布：2026-11-04T05:48:13.950Z
- 近 30 天下载量：5321（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：255（近 12 个月 255 个）

## 中文简介

事件驱动微服务平台工具包——将代码和基础设施锁定.

## 安装

```sh
npm install @crossdelta/platform-sdk
```

也可以使用：`pnpm add @crossdelta/platform-sdk`、`yarn add @crossdelta/platform-sdk`、`bun add @crossdelta/platform-sdk`

## README

![pf](https://unpkg.com/@crossdelta/platform-sdk/logo.png)

# 平台 SDK

**后端+基础设施平台工具包.**

`pf` 脚手架现实世界平台:后端服务,事件驱动信息,基础设施. 全部接通并保持同步.

  

[![npm version](https://img.shields.io/npm/v/@crossdelta/platform-sdk.svg?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/@crossdelta/platform-sdk)   ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)   ![Bun](https://img.shields.io/badge/Bun-000000?style=for-the-badge&logo=bun&logoColor=white)   ![MIT License](https://img.shields.io/badge/License-MIT-be1b4b?style=for-the-badge)

[快速启动](https://npmcn.com/package/%40crossdelta/platform-sdk/#readme--quick-start) 二. 支助 [教学](https://npmcn.com/package/%40crossdelta/platform-sdk/#readme--5-minute-tutorial) 二. 支助 [图标](https://npmcn.com/package/%40crossdelta/platform-sdk/#readme--commands) 二. 支助 [部署](https://npmcn.com/package/%40crossdelta/platform-sdk/#readme--deployment)

* * *

## QQ 快速启动

```bash
# With Bun
bun add -g @crossdelta/platform-sdk

# With npm
npm install -g @crossdelta/platform-sdk

# Or auto-install (macOS/Linux/WSL)
curl -fsSL https://unpkg.com/@crossdelta/platform-sdk@latest/install.sh | bash
```

> **视窗用户 :** 使用 [WSL 维基月球](https://learn.microsoft.com/en-us/windows/wsl/install) 对于最佳的经验.

**然后创建您的第一个平台:**

```bash
pf new workspace my-platform -y && cd my-platform
pf dev
```

  

<table><tbody><tr><td>✅</td><td>带有 Biome 林定的涡轮平面</td></tr><tr><td>✅</td><td>NATS + JetStream 用于事件驱动信件</td></tr><tr><td>✅</td><td>准备部署的普鲁米基础设施</td></tr><tr><td>✅</td><td>自动生成 <code>.env.local</code> 有服务端口</td></tr></tbody></table>

* * *

## 5分教学

增加两个服务,并在它们之间连接一个事件:

```bash
# 1. Create two services
pf new hono-micro services/orders
pf new hono-micro services/notifications

# 2. Wire an event from orders → notifications
pf cloudevents add order.created --service services/notifications

# 3. Restart to pick up new services
pf dev

# 4. Publish a test event, watch notifications react
pf cloudevents publish order.created
```

  

| 刚才发生的事 |
| :-- |
| 2个健康检查和Pulumi配置服务  
一份活动合同 `packages/contracts/`  
一个自动发现事件的处理者  
✨ **没有手工接线。 无相相相通. 一切都是明确的.** |

* * *

## QQ 命令

| 命令 | 它会做什么 |
| :-- | :-- |
| `pf dev` | QQ 启动开发基础设施(NATS)+所有监视模式的服务 |
| `pf new hono-micro <path>` | QQ 创建 Hono 服务( 轻量级, Bun- 优化) |
| `pf new nest-micro <path>` | QQ 创建 NestJS 服务( 全功能, 装饰) |
| `pf new workspace [name]` | QQ 创建新工作空间并设置基础设施 |
| `pf cloudevents add <type> --service <path>` | +++ 合同 + 接线流 |
| `pf cloudevents list` | 列出可用的事件和消费者 |
| `pf cloudevents publish <type>` | 将模拟事件发布到NATS |
| `pf setup completion` | \* 安装外壳自动补全(zsh/bash) |
| `pf test` | \* 在整个单列波运行测试 |
| `pf build` | \* 建立所有软件包和服务 |
| `pf lint` | 使用 Biome 的 Lint 和格式 |
| `pf audit` | \* 运行依赖性安全审计 |
| `pf pulumi <args>` | 在工作区运行普鲁米 `infra/` 目录,例如:. `pf pulumi up` |

> 您的工作空间可以添加自己的命令 : `pf.commands` 在树根中 `package.json` (可选为 `cwd` 财务报告和审定财务报表 `command`),或任意根 `scripts` 条目,以 `pf <name>`下列出插件 `pf.plugins` 添加命令组, 如 `@crossdelta/cloudevents` 对 `pf cloudevents`。插件接口在 `docs/plugins.md` 在数据源中.

* * *

## \* 与编码代理合作

`@crossdelta/pf-mcp` 是一个 [示范背景协议](https://github.com/modelcontextprotocol/typescript-sdk) 用于 SDK 平台的服务器。 它暴露出四个工具:

| 工具 | 它会做什么 |
| :-- | :-- |
| `scan_workspace` | 扫描服务、合同和配置的工作空间 |
| `generate_service` | 生成一个新的微服务计划( 默认干运行) |
| `plan_review` | 应用前验证生成计划 |
| `apply_changes` | 应用生成计划中的更改 |

服务器计划结构;代理写内容. 服务按此顺序创建: 代理呼叫 `generate_service` 及时收到一份附有文件的计划 `planHash`,为这些文件写代码,可选调用 `plan_review`,请您确认,然后打电话 `apply_changes` 与 `expectedPlanHash`。 。 。 .

```bash
bun add @crossdelta/pf-mcp
node ./node_modules/@crossdelta/pf-mcp/dist/cli.js --stdio
```

服务器通过stdio说话,所以你的代理的MCP客户端必须启动这个命令. 它还为来自 `docs/generators/` 作为 MCP 资源的软件包源中 `docs://generators`。 。 。 .

* * *

## 部署

```bash
pf pulumi up              # deploys the current Pulumi stack
```

每艘工作空间飞船都有一个Pulumi堆栈并预先配置了GitHub Actions. 添加更多堆栈( 如 . `stage`, (中文(简体) ), `production`随着你的平台增长. `pf` 财务报告和审定财务报表 `generate-env` 使用任意堆栈名称.

`pf dev` 生成 `.env.local` 从当前堆栈的 Pulumi 配置( 密钥, API 密钥) 并发现了服务端口 .

**预配置的 GitHub 动作包括:**

| 触发 | 行动 |
| :-- | :-- |
| 公关改为 `main` | QQ Lint + 测试 |
| 推动 `main` | \* 构建、推动到全球大气监测、部署 |
| 变动 `packages/` | QQ 发布到 npm |

\* 所需机密  

| 秘诀 | 说明 |
| :-- | :-- |
| `PULUMI_ACCESS_TOKEN` | [普鲁米·克罗克特](https://app.pulumi.com/account/tokens) |
| `DIGITALOCEAN_TOKEN` | [DO API 签名](https://cloud.digitalocean.com/account/api/tokens) |

* * *

## 所需经费

| 所需经费 | 页:1 |
| :-- | :-- |
| **阿宝** 或节点.js 21 | 速度推荐包 |
| **[普鲁米CLI](https://www.pulumi.com/docs/install/)** | 用于部署基础设施 |
| **[夹克](https://www.docker.com/)** | 当地NATS |

* * *

## 在兜帽男的脚下

📁 **项目结构**  

```
my-platform/
├── services/           # Your microservices
│   ├── orders/
│   └── notifications/
├── packages/
│   └── contracts/      # Event contracts (single source of truth)
├── infra/
│   └── services/       # Auto-generated Pulumi configs
└── .env.local          # Auto-generated from infra
```

**关键见解是:** 服务定义了它们的端口,env vars,以及一次活动订阅. 其他一切皆从所出.

🛠️ **技术堆栈**  

| 层 | 技术 |
| :-- | :-- |
| 单曲 | [涡轮](https://turbo.build/repo) |
| 服务 | [浩诺](https://hono.dev/) 或者说 [网点JS](https://nestjs.com/) |
| 通讯 | [海军](https://nats.io/) + 喷气相机 |
| 活动 | [@ crossdelta/ clodevents (英语)](https://www.npmjs.com/package/@crossdelta/cloudevents) (单位:千美元)[云节](https://cloudevents.io/) + Zod) 组合键 |
| 基础设施 | [普鲁米](https://pulumi.com/) • 数字海洋(可扩展) |
| 运行时间 | [阿宝](https://bun.sh/) |

⚙️ **工作空间配置**  

```json
{
  "pf": {
    "registry": "my-org/my-platform",
    "commands": {
      "deploy": {
        "cwd": "infra",
        "command": "pulumi up --yes",
        "description": "Deploy infrastructure to production"
      }
    },
    "paths": {
      "services": { "path": "services", "watch": true },
      "contracts": { "path": "packages/contracts" }
    }
  }
}
```
🏗️ **服务基础设施配置**  

```typescript
// infra/services/orders.ts
import { ports, type K8sServiceConfig } from '@crossdelta/infrastructure'

const config: K8sServiceConfig = {
  name: 'orders',
  ports: ports().http(4001).build(),
  replicas: 1,
  healthCheck: { httpPath: '/health' },
  resources: {
    requests: { cpu: '50m', memory: '64Mi' },
    limits: { cpu: '150m', memory: '128Mi' },
  },
}

export default config
```

见 [@ crossdelta/ 基础设施](https://www.npmjs.com/package/@crossdelta/infrastructure) 完全选择.

📡 **事件驱动的架构**  

**合同** 住在这里 `packages/contracts/` 作为真理的唯一来源:

```typescript
// packages/contracts/src/events/orders/created.ts
import { createContract } from '@crossdelta/cloudevents'
import { z } from 'zod'

export const OrderCreatedSchema = z.object({
  orderId: z.string(),
  total: z.number(),
})

export type OrderCreatedData = z.infer<typeof OrderCreatedSchema>

export const OrdersCreatedContract = createContract({
  type: 'order.created',
  channel: { stream: 'ORDERS' },
  schema: OrderCreatedSchema,
})
```

**处理器** 进口合同和授权使用案件:

```typescript
// services/notifications/src/events/order-created.handler.ts
import { handleEvent } from '@crossdelta/cloudevents'
import { OrdersCreatedContract } from '@my-platform/contracts'
import { sendOrderNotification } from '../use-cases/send-notification.use-case'

export default handleEvent(OrdersCreatedContract, async (data) => {
  await sendOrderNotification(data)
})
```

掌柜是自动发现的 无人工订阅.

见 [@ crossdelta/ clodevents (英语)](https://www.npmjs.com/package/@crossdelta/cloudevents) (原始内容存档于2018-10-21). For full event API.

⚡ **NATS 信件经纪人**  

> **本地NATS 开始于 `pf dev` 发展基础设施.** **生产流是通过合同中的Pulumi实现的.**

每个工作空间包括预配置的有JetStream用于开发的NATS:

**发展:**

-   自动启动 `pf dev` (以多克为主,以麻黄为主
-   端口 : `4222` (客户), `8222` (监测)
-   健康检查: `curl http://localhost:8222/healthz`
-   流: 由 : `pf dev` (备忘录,保留1小时)

**生产:**

-   通过普鲁米部署(`infra/`(中文(简体) )
-   采用保留政策的合同的流程
-   有明确限制的持久储存(基于文件)

> **服务从不创建流.** 在德夫语中, `pf dev` 自动创建合同。 在prod中,普鲁米实现.

* * *

## 许可证

麻省理工学院 [横跨德尔塔](https://crossdelta.de/)

## 常见问题

### @crossdelta/platform-sdk 是什么？

事件驱动微服务平台工具包——将代码和基础设施锁定\.

### 如何安装 @crossdelta/platform-sdk？

在项目目录运行 npm install @crossdelta/platform-sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pf，可以用 npx pf 直接运行。

### @crossdelta/platform-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crossdelta/platform-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @crossdelta/platform-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=21\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @crossdelta/platform-sdk 可以商用吗？

@crossdelta/platform-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crossdelta/platform-sdk 的下载量有多少？

根据 npm 官方下载统计，@crossdelta/platform-sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 5,321 次，日均约 177 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crossdelta/platform-sdk 还在维护吗？

最新版本 0\.26\.15 发布于 2026/11/04（6 天前）；至今共发布 255 个版本，其中过去 12 个月发布了 255 个；首次发布于 2025/12/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。